Charts API

Complete API reference for @oge-ui/charts. The kernel — 1-2-5 nice-tick scales, calendar-true time ticks, stacking, bar slotting, single-path builders, pie layout, zoom math and the O(log n) hit-testing — is pure TypeScript inside the package; live demos are on the overview page.

Properties Methods Events Types

OgeChart

oge-chart

Properties 18

Data & series

Name	Type	Default	Description
`dataSource`	`readonly T[]`	`[]`	Data items; never mutated.
`series`	`readonly OgeChartSeriesInput[]`	`[]`	Series definitions: `type` (16 kinds), field mapping (`valueField`/`argumentField` — names, dotted paths or getters), `name`, `color`, `axis` (value-axis index), `stack` group, `dashStyle`/`width`/`opacity`, `showInLegend`, rangeArea bounds (`value1Field`/`value2Field`) and candlestick OHLC (`openField`/`highField`/`lowField`/`closeField`), `sizeField` (bubble area), `visible` (start hidden; the legend re-shows) and `showLabels` (SI-formatted value labels on small series). Null/NaN values render as gaps.
`commonSeries`	`Partial<OgeChartSeriesInput>`	`{}`	Defaults merged under every series (dx `commonSeriesSettings` parity).
`palette`	`readonly string[] \| undefined`	—	Series colors; defaults to the 10-color `OGE_CHART_PALETTE` (concrete hex values so exported images keep their colors).

Axes

Name	Type	Default	Description
`argumentAxis`	`OgeChartAxisOptions`	`{}`	Argument axis: `type` auto-detects (numbers / dates / categories) when unset; `min`/`max`, `inverted`, `grid`, `title`, `labelFormat`, `labelOverlap` (`rotate`/`skip`/`none`).
`valueAxis`	`OgeChartAxisOptions \| readonly OgeChartAxisOptions[]`	`{}`	One or more value axes; series pick theirs via `axis`. `position: 'end'` renders on the right, `type: 'logarithmic'` spaces decades evenly, `abbreviate: false` disables SI labels (`1.2K`).
`stripLines`	`readonly OgeChartStripLine[]`	`[]`	Argument-axis markers: `{ start, end?, label?, color? }` — a line without `end`, a shaded band with it.
`annotations`	`readonly OgeChartAnnotation[]`	`[]`	Plot annotations: `type: 'point'` draws a marker dot with a connector into a label box at (`argument`, `value`); `'text'` places the label alone (top of the plot without a value). `axis`, `color` and `offsetX/Y` refine placement.

Interaction

Name	Type	Default	Description
`zoomEnabled / panEnabled`	`'none' \| 'wheel' \| 'drag' \| 'both' / boolean`	`'none' / false`	Cursor-centered wheel zoom, drag-select zoom (Escape cancels mid-drag, 8px threshold), Shift+drag pan. Escape on the focused plot resets the zoom.
`visualRange`	`OgeChartRange \| null`	`null`	The zoom window in argument-axis units (`null` = full extent). Two-way (`[(visualRange)]`); writes clamp into the data bounds.
`tooltip`	`OgeChartTooltipOptions`	`{}`	`{ enabled?, shared? }` — shared lists every series at the hovered argument; otherwise the value-nearest series wins.
`crosshair`	`OgeChartCrosshairOptions`	`{}`	`{ enabled?, horizontal? }` — the vertical tracker snaps to the nearest argument (binary search).
`legend`	`OgeChartLegendOptions`	`{}`	`{ visible?, position? (top/bottom/start/end), interactive? }` — real buttons with `aria-pressed`; clicking toggles the series and the axes rescale.
`selectionMode / selectedPoints`	`'point' \| 'series' \| 'none' / readonly OgeChartPointRef[]`	`'none' / []`	Click (or Enter) selects; Ctrl adds points to the set; series mode selects the whole series. Two-way (`[(selectedPoints)]`).

Appearance & i18n

Name	Type	Default	Description
`title / subtitle`	`string`	`''`	Headings above the plot.
`animation`	`boolean`	`true`	Hover/selection transitions; honors `prefers-reduced-motion`.
`locale`	`string \| undefined`	—	BCP 47 locale for every `Intl` format; defaults to the config locale, then the browser locale.
`messages`	`Partial<OgeChartsMessages>`	`{}`	Per-instance message overrides, merged over the DI config per top-level block.

Methods 7

Name	Type	Description
`zoomToRange(range) / resetZoom()`	`void`	Programmatic zoom (clamped into the data bounds) / back to the full extent, announced.
`hideTooltip()`	`void`	Clears the hover state (tooltip + crosshair).
`refresh()`	`void`	Re-measures the container (ResizeObserver normally covers it).
`focus()`	`void`	Focuses the keyboard-inspectable plot region.
`getExportData()`	`OgeChartExportData<T>`	Snapshot for custom pipelines: per-series names/types/colors/visibility/points plus the plotted range.
`getSvgElement()`	`SVGSVGElement`	The live SVG root — what the image exporters serialize.

Export entry point (lazy, dependency-free)

Name	Type	Description
`exportChartToPng(chart, options?) / exportChartToSvg(chart, options?) / serializeChartSvg(svg, options?)`	`@oge-ui/charts/export-image`	No third-party libraries: the live SVG is cloned with computed styles inlined, then downloaded as a standalone `.svg` or rasterized onto a canvas for `.png` (`pixelRatio`, `background`). Import the entry point dynamically.

Events 5

Name	Type	Description
`pointClick / seriesClick`	`OgeChartPointEvent<T> / OgeChartSeriesEvent`	Pointer (and keyboard Enter) activation with the normalized point payload.
`legendClick`	`OgeChartLegendClickEvent`	Cancelable — set `cancel = true` to veto the visibility toggle; carries `willHide`.
`tooltipShowing`	`OgeChartTooltipShowingEvent<T>`	Cancelable, before the tooltip shows for a new argument.
`visualRangeChange / selectedPointsChange`	`OgeChartRange \| null / readonly OgeChartPointRef[]`	The two-way model outputs.
`drawn`	`void`	After every render pass.

Types 6

Name	Type	Description
`OgeChartSeriesType`	`string union`	'line' \| 'spline' \| 'stepLine' \| 'area' \| 'splineArea' \| 'stepArea' \| 'stackedArea' \| 'fullStackedArea' \| 'bar' \| 'stackedBar' \| 'fullStackedBar' \| 'rangeBar' \| 'scatter' \| 'bubble' \| 'rangeArea' \| 'candlestick'.
`OgeChartPoint<T>`	`interface`	The normalized point: `argument`, `argNumeric`, `value`(s incl. OHLC), `source`, `index`.
`OgeChartAxisType / OgeChartRange`	`'linear' \| 'logarithmic' \| 'category' \| 'time' / { min, max }`	Axis kinds and the numeric window type (time axes: epoch ms; category: index space).
`[ogeChartTooltipTemplate]`	`structural directive (OgeChartTooltipTemplate)`	Replaces the tooltip's content; context `OgeChartTooltipTemplateContext`: `{ $implicit: OgeChartPointEvent[] }`.
`[ogeChartAnnotationTemplate]`	`structural directive (OgeChartAnnotationTemplate)`	Replaces an annotation's label (rendered in a `foreignObject`, so any HTML works); context `OgeChartAnnotationTemplateContext`: `{ $implicit: { text } }`.
`[ogeChartLegendTemplate]`	`structural directive (OgeChartLegendTemplate)`	Replaces a legend item's content; context `OgeChartLegendTemplateContext`: `{ $implicit: { name, color, hidden } }`.

OgePieChart

oge-pie-chart

Properties 7

Name	Type	Default	Description
`dataSource / argumentField / valueField`	`readonly T[] / string \| getter`	`[] / 'argument' / 'value'`	One slice per item; negative values clamp to zero.
`type / innerRadius / startAngle`	`'pie' \| 'doughnut' / number / number`	`'pie' / 0.5 / 0`	Doughnut hole as an outer-radius fraction; start angle in radians (0 = 12 o'clock, clockwise).
`smallValuesGrouping`	`OgeChartSmallValuesGrouping \| null`	`null`	`{ mode: 'topN' \| 'smallValueThreshold', topCount?, threshold? }` — the tail folds into an "Others" slice (`othersLabel`).
`othersLabel`	`string`	`'Others'`	Label (and `argument` of the event payload) of the grouped tail slice.
`showLabels`	`boolean`	`true`	Outside labels in two anti-overlap columns with connector lines.
`selectedSlices`	`readonly number[]`	`[]`	Selected slice indexes — selected slices explode. Two-way (`[(selectedSlices)]`).
`legend / tooltipEnabled / palette / title / locale / messages`	`see OgeChart`	—	Shared options with the cartesian chart.

Methods 1

Name	Type	Description
`getSvgElement()`	`SVGSVGElement`	The live SVG root — what the image exporters serialize.

Events 2

Name	Type	Description
`sliceClick`	`OgeChartPieSliceEvent<T>`	Slice activation: `argument`, `value`, `fraction`, merged `sources` and the `grouped` flag for the "Others" slice.
`legendClick / selectedSlicesChange`	`OgeChartLegendClickEvent / readonly number[]`	Cancelable legend toggle; the two-way selection output.

OgePolarChart

oge-polar-chart

Properties 6

Name	Type	Default	Description
`dataSource / series / commonSeries`	`readonly T[] / readonly OgeChartSeriesInput[] / Partial`	`[] / [] / {}`	Same field mapping as the cartesian chart; supported polar types: `'line'` and `'area'` (closed radar loops — a null value breaks the loop into a gap), `'scatter'` (markers) and `'bar'` (sectors from the center).
`spider`	`boolean`	`false`	Straight-segment (polygon) grid rings instead of circles.
`startAngle`	`number`	`0`	First category's angle in radians (0 = 12 o'clock, clockwise).
`valueAxis`	`OgeChartAxisOptions`	`{}`	The radial axis: `max` override and `labelFormat` of the nice-tick rings.
`selectionMode / selectedPoints`	`'point' \| 'none' / readonly OgeChartPointRef[]`	`'none' / []`	Keyboard Enter on the active point selects it (a second Enter clears it); hovering markers and sectors shows the tooltip. Two-way (`[(selectedPoints)]`).
`legend / tooltipEnabled / palette / title / locale / messages`	`see OgeChart`	—	Shared options — the legend, tooltip, sr data table and keyboard inspection (arrows walk categories and series) work exactly like the cartesian chart.

Methods 1

Name	Type	Description
`focus() / getSvgElement()`	`void / SVGSVGElement`	Focuses the keyboard-inspectable plot / the live SVG root for the image exporters.

Events 1

Name	Type	Description
`pointClick / legendClick / selectedPointsChange`	`OgeChartPointEvent<T> / OgeChartLegendClickEvent / readonly OgeChartPointRef[]`	Point activation, the cancelable legend toggle and the two-way selection output.

OgeRangeSelector

oge-range-selector

Properties 4

Name	Type	Default	Description
`dataSource / series`	`readonly T[] / readonly OgeChartSeriesInput[]`	`[] / []`	The mini background chart (line/area recommended) drawn behind the selection window.
`value`	`OgeChartRange \| null`	`null`	The selected window in argument units (`null` = full range). Two-way (`[(value)]`) — bind the same signal to a chart's `[(visualRange)]` and the two stay in lockstep.
`scaleType`	`'time' \| 'linear' \| undefined`	—	Auto-detects from the first argument (dates → time) when unset.
`palette / locale / messages`	`see OgeChart`	—	Shared options; handle labels come from `messages.aria.rangeStart/rangeEnd/rangeWindow`.

Methods 1

Name	Type	Description
`reset()`	`void`	Back to the full range (`value = null`).

Events 1

Name	Type	Description
`valueChange`	`OgeChartRange \| null`	The two-way model output. Interaction: drag the window (grab cursor), drag either handle, click the track to center the window there — Escape mid-drag restores; the handles are WAI-ARIA sliders (arrow keys adjust by 2%, Home/End jump to the bounds, changes announced).

Configuration

Properties 5

Name	Type	Default	Description
`provideOgeChartsConfig(config)`	`Provider`	—	Configures every chart below the provider (`OgeChartsConfigInput`); shallow merge over `OGE_DEFAULT_CHARTS_CONFIG` per top-level key — a partial `messages` replaces whole nested blocks. The token is `OGE_CHARTS_CONFIG` (`OgeChartsConfig`).
`messages`	`OgeChartsMessages`	—	Every user-facing string, aria labels included: `aria` (`OgeChartsAriaMessages` — chart/pie labels with `{title}`/`{count}`, table caption, plot hint, legend label), `announcements` (`OgeChartsAnnouncementMessages` — live-region templates with `{series}`/`{argument}`/`{value}`) and `noData`. Defaults: `OGE_DEFAULT_CHARTS_MESSAGES`.
`locale`	`string \| undefined`	—	BCP 47 locale for every `Intl` format in scope; a per-instance `[locale]` input wins.
`a11yTableLimit`	`number`	`50`	Rows of the screen-reader data table.
`markerThreshold`	`number`	`200`	Marker circles render only up to this many points per series — beyond it the single path carries the series alone. Line-family paths additionally auto-downsample with LTTB to about one point per pixel once a series outgrows the plot width (hit-testing and tooltips keep the full data).

Notes

Rendering is dependency-free SVG (no D3, no Chart.js, no canvas library) and dates are plain local Dates (Intl-only house rule). Time ticks are calendar-true: month boundaries land on real month starts and DST never shifts a point.
No WAI-ARIA APG chart pattern exists. The widget composes: role="img" with a generated label, a screen-reader-only role="table" carrying the first a11yTableLimit rows of data, real legend buttons with aria-pressed, and a focusable plot region where arrow keys walk arguments and series with polite live-region announcements — Enter selects, Escape resets the zoom.
The performance contract: one <path> per series regardless of point count, markers only under markerThreshold, binary-search hit-testing and rAF-coalesced pointer/resize work — verified by a 50k-point smoke test.