Deepen-merge overrides for a single locale.
(locale: Locale, table: PartialMessages) => voidPublic chart handle. Series APIs attach here in Phase 2. This module must never import WebGL or WebGPU symbols.
interface Chart| engine | Engine |
| scene | Scene |
| disposed | boolean |
| theme | ChartThemeName |
| rendererKind | RendererKind | undefined |
| mount | () => Promise<void> |
| resize | (width?: number, height?: number) => void |
| render | () => void |
| addPrimitive | (options: CreatePrimitiveOptions) => PrimitiveNode |
| setBackground | (color: ColorInput) => void |
| dispose | () => void |
(options: Chart3DOptions) => RekhlyChart3D(options: BarChartOptions) => BarChart(options: DataGridOptions) => DataGridAn operation was attempted on a chart, engine, or renderer that has already been disposed.
class ChartDisposedError(o: PartChartOptions) => DonutChart(options: FinancialChartOptions) => FinancialChart(o: PartChartOptions) => FunnelChart(o: PartChartOptions) => GaugeChart(options: HeatmapChartOptions) => HeatmapChart(options: LinearGaugeOptions) => LinearGauge(options: MapChartOptions) => MapChartOptions for {@link createChart} / {@link RekhlyChart}.
interface ChartOptions| container | string | HTMLElement |
| canvas? | HTMLCanvasElement | undefined |
| theme? | ChartThemeName | undefined |
| renderer? | RendererPrefs | undefined |
| autoResize? | boolean | undefined |
| pixelRatio? | number | undefined |
| width? | number | undefined |
| height? | number | undefined |
(options: ParallelChartOptions) => ParallelCoordinateChart(o: PartChartOptions) => PieChart(options: PolarChartOptions) => PolarChart(o: PartChartOptions) => PyramidChart(o: PartChartOptions) => RadarChart(o: PartChartOptions) => SankeyChart(o: PartChartOptions) => RadarChartBuilt-in theme tokens for Phase 1. Full theme packs land in later phases.
type ChartThemeName = ChartThemeName(o: PartChartOptions) => TreemapChartCreate an XY chart. Initialization runs in the background; await {@link XYChart.ready} before the first GPU frame is guaranteed.
(options: XYChartOptions) => XYChartClear all custom overrides (tests / hot reload). Built-ins are unchanged.
() => voidAccepted color inputs at public APIs. - {@link Rgba} object - `[r, g, b]` or `[r, g, b, a]` in 0–1 - CSS hex (`#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`) - `rgb()` / `rgba()` functions - a small set of named colors
type ColorInput = ColorInputValue → color lookup used by heatmaps, parallel coordinates, and gauges. Original Rekhly helper — not a wrapper of any third-party LUT type.
class ColorLutMerge app-level configuration into the global catalog.
(config: I18nConfig) => voidCreate and mount a Rekhly chart.
(options: ChartOptions) => Promise<Chart>Create an uninitialized engine. Call {@link Engine.initialize} before drawing.
(options: EngineOptions) => EngineCreate a mutable group node.
(options?: CreateGroupOptions) => GroupNodeConvenience constructor.
(steps: readonly LutStep[], interpolate?: boolean) => ColorLutCreate a primitive scene node in clip space.
(options: CreatePrimitiveOptions) => PrimitiveNodeOptions for {@link createPrimitive}.
interface CreatePrimitiveOptions| primitive | PrimitiveKind |
| vertices | ArrayLike<number> |
| color | ColorInput |
| id? | string | undefined |
| visible? | boolean | undefined |
| zIndex? | number | undefined |
| texture? | HeatmapTexture | undefined |
| mesh? | Mesh3DData | undefined |
Create and initialize a renderer for `canvas`. Core path is always WebGL2: hardware GPU when present, software WebGL2 when it is not. Canvas is opt-in (`force: "canvas"` or an explicit prefer list). WebGPU is skipped unless ready.
(canvas: RenderTarget, prefs?: RendererPrefs) => Promise<Renderer>Create an empty scene with the default dark background.
() => SceneCreate an immutable theme, optionally extending a base (default: dark).
(input?: ThemeInput, base?: Theme) => ThemeCreate a translator, optionally seeded with a locale and/or overrides.
(options?: { readonly locale?: Locale; readonly messages?: PartialMessages; }) => TranslatorCreate and wait for the first initialized frame.
(options: XYChartOptions) => Promise<XYChart>(main: XYChart, options: ZoomOverviewOptions) => ZoomOverviewPer-locale partial overrides supplied by the host app.
type CustomLocaleMessages = Partial<Record<Locale, Partial<MessageTable>>>Built-in dark theme (graphite + electric cyan).
ThemeLocalized chart description for screen readers (includes keyboard help).
(locale: Locale, title: string, seriesCount: number, sampleCount: number) => stringOwns the scene, renderer, frame loop, and resource lifetime. Frame-loop ownership lives here — not on individual charts. Charts request frames via {@link Engine.requestFrame}; they do not call `requestAnimationFrame` themselves.
interface Engine| scene | Scene |
| renderer | Renderer | undefined |
| resources | ResourceManager |
| disposed | boolean |
| initialized | boolean |
| viewport | ViewportSize |
| cssSize | ViewportSize |
| pixelRatio | number |
| initialize | () => Promise<void> |
| resize | (width: number, height: number) => void |
| requestFrame | () => void |
| renderNow | () => void |
| start | () => void |
| stop | () => void |
| dispose | () => void |
| on | <K extends keyof EngineEventMap>(event: K, handler: (payload: EngineEventMap[K]) => void) => () => void |
interface EngineOptions| canvas | RenderTarget |
| renderer? | RendererPrefs | undefined |
| autoResize? | boolean | undefined |
| pixelRatio? | number | undefined |
Formats a date/time using the locale's `Intl.DateTimeFormat` conventions.
(locale: Locale, value: number | Date, options?: Intl.DateTimeFormatOptions) => stringFormats a number using the locale's `Intl.NumberFormat` conventions.
(locale: Locale, value: number, options?: Intl.NumberFormatOptions) => stringCurrent process-wide default locale.
() => LocaleConfigure the process-wide i18n defaults used by chart chrome when a chart does not pass its own `locale` / `translations`. Call once at app startup — overrides merge on top of the built-in tables and later calls deepen-merge rather than replace the whole catalog.
interface I18nConfig| locale? | Locale | undefined |
| messages? | Partial<Record<Locale, Partial<MessageTable>>> | undefined |
| fallback? | Locale | undefined |
Input data failed validation (wrong arity, NaN, empty required buffer).
class InvalidDataErrorBuilt-in light theme.
Themeinterface LinearAxis| id | string |
| orientation | "x" | "y" |
| inverted | boolean |
| title | string |
| autoFit | boolean |
| scale | AxisScale |
| getDomain | () => NumericRange |
| getVisibleRange | () => NumericRange |
| setVisibleRange | (range: NumericRange | { readonly width: number; }) => LinearAxis |
| setWindowWidth | (width: number | undefined) => LinearAxis |
| getWindowWidth | () => number | undefined |
| setDomain | (range: NumericRange) => LinearAxis |
| setTitle | (title: string) => LinearAxis |
| setInverted | (inverted: boolean) => LinearAxis |
| setFitPadding | (padding: number) => LinearAxis |
| getFitPadding | () => number |
| setTickProvider | (provider: TickProvider | undefined) => LinearAxis |
| ticks | (countHint: number) => readonly AxisTick[] |
| format | (value: number) => string |
| fit | () => LinearAxis |
| setScale | (scale: AxisScale) => LinearAxis |
| setScrollMode | (mode: AxisScrollMode) => LinearAxis |
| getScrollMode | () => AxisScrollMode |
| setCategories | (labels: readonly string[]) => LinearAxis |
| setTimeZone | (zone: "utc" | "local") => LinearAxis |
| setFormatStyle | (style: "plain" | "scientific" | "engineering") => LinearAxis |
| setUnitLabel | (label: string) => LinearAxis |
Built-in UI / tooltip / a11y messages for every supported locale. Keys are stable public identifiers — apps override by key, not by English text.
type Locale = LocaleStable message keys used by chart chrome, tooltips, and a11y labels.
type MessageKey = MessageKeyLocaleMessagesResolves a browser `navigator.languages` list or a Next.js `Accept-Language` header value down to the best supported {@link Locale}, falling back to `"en"`. Base-language matches (`"de-AT"` → `"de"`) count.
(preferred: readonly string[] | string, supported?: readonly Locale[]) => LocaleSubscribe to global locale / catalog changes. Returns an unsubscribe.
(listener: (locale: Locale) => void) => () => voidNormalize a public color input into clamped RGBA 0–1.
(input: ColorInput) => Rgbatype PartialMessages = Partial<MessageTable>interface PrimitiveNode| kind | "primitive" |
| primitive | PrimitiveKind |
| color | Rgba |
| vertices | Float32Array<ArrayBufferLike> |
| texture? | HeatmapTexture | undefined |
| mesh? | Mesh3DData | undefined |
| clipRect? | readonly [number, number, number, number] | undefined |
| id | string |
| visible | boolean |
| zIndex | number |
Deepen-merge overrides for many locales at once (typical package import path).
(table: CustomLocaleMessages) => voidPublic Rekhly namespace matching the PRD factory sketch.
{ readonly chartXY: typeof chartXY; readonly createXYChart: typeof createXYChart; readonly createChart: typeof createChart; readonly chart3D: typeof chart3D; readonly chartMap: typeof chartMap; readonly chartHeatmap: typeof chartHeatmap; readonly chartFinancial: typeof chartFinancial; readonly chartPie: typeof chartPie; readonly chartDonut: typeof chartDonut; readonly chartRadar: typeof chartRadar; readonly chartSpider: typeof chartSpider; readonly chartGauge: typeof chartGauge; readonly chartLinearGauge: typeof chartLinearGauge; readonly chartFunnel: typeof chartFunnel; readonly chartPyramid: typeof chartPyramid; readonly chartTreemap: typeof chartTreemap; readonly chartSankey: typeof chartSankey; readonly chartPolar: typeof chartPolar; readonly chartParallel: typeof chartParallel; readonly chartDataGrid: typeof chartDataGrid; readonly chartBar: typeof chartBar; }Framework-neutral chart. Owns an {@link Engine} and a host canvas.
class RekhlyChartBase typed error. All public Rekhly failures extend this class so callers can branch on {@link RekhlyError.code} without string-matching `name`.
class RekhlyErrorBackend-agnostic renderer contract (PRD §3). Chart and series code must never call WebGL/WebGPU APIs directly. Custom drawing goes through scene primitives or a later plugin API.
interface Renderer| kind | RendererKind |
| device | RendererDevice |
| disposed | boolean |
| viewport | ViewportSize |
| lastFrameStats? | RendererFrameStats | undefined |
| initialize | () => Promise<void> |
| resize | (width: number, height: number) => void |
| render | (scene: Scene) => void |
| dispose | () => void |
Renderer construction or `initialize()` failed for a reason other than a specific backend being unavailable.
class RendererInitializationErrorSupported rendering backends (PRD §3). Preference order when a backend is ready: WebGPU → WebGL2 → Canvas. WebGPU is not production-ready in Phase 1 and is skipped unless forced.
type RendererKind = RendererKindRenderer selection preferences.
interface RendererPrefs| prefer? | readonly RendererKind[] | undefined |
| force? | RendererKind | undefined |
| strict? | boolean | undefined |
| powerPreference? | "default" | "high-performance" | "low-power" | undefined |
| failIfMajorPerformanceCaveat? | boolean | undefined |
| allowSoftware? | boolean | undefined |
A GPU/CPU resource could not be created, compiled, or disposed cleanly.
class ResourceErrorCPU-side scene. The public chart API mutates the scene; renderers only consume {@link Scene.compile}.
interface Scene| background | Rgba |
| nodes | readonly SceneNode[] |
| dirty | boolean |
| add | (node: SceneNode) => SceneNode |
| remove | (id: NodeId) => boolean |
| get | (id: NodeId) => SceneNode | undefined |
| clear | () => void |
| markDirty | () => void |
| compile | () => RenderGraph |
Set the process-wide default locale. Charts that already hold an explicit locale are unchanged; call their `setLocale` (when available) to update them.
(locale: Locale) => voidreadonly Locale[]Translate a built-in message key. Resolution order: locale overrides → locale built-in → fallback overrides → fallback built-in → English → the key itself.
(key: MessageKey, vars?: MessageVars, locale?: Locale) => stringResolved, immutable visual theme (PRD §34–35).
interface Theme| name | string |
| background | Rgba |
| plot | { readonly fill: Rgba; readonly padding: ThemePadding; } |
| axis | { readonly line: Rgba; readonly tick: Rgba; readonly label: Rgba; readonly title: Rgba; readonly fontFamily: string; readonly fontSize: number; readonly titleSize: number; } |
| grid | { readonly major: Rgba; readonly minor: Rgba; } |
| cursor | { readonly line: Rgba; } |
| tooltip | { readonly background: Rgba; readonly border: Rgba; readonly text: Rgba; readonly fontFamily: string; readonly fontSize: number; } |
| series | readonly Rgba[] |
| typography | { readonly fontFamily: string; readonly fontSize: number; } |
A bound translator for one chart / component tree. Owns its own locale and optional local overrides; still falls through to the global catalog.
interface Translator| locale | Locale |
| messages | Partial<MessageTable> |
| t | (key: MessageKey, vars?: MessageVars) => string |
| setLocale | (locale: Locale) => void |
| addTranslations | (table: PartialMessages) => void |
| table | () => MessageTable |
WebGL2 was requested (or required as fallback) but the environment could not produce a `webgl2` context.
class WebGLUnavailableErrorWebGPU was requested but is unavailable, or is not production-ready in this Rekhly release.
class WebGPUUnavailableErrorTyped-array XY dataset. `x` and `y` must have the same length.
interface XYBuffer| x | Float32Array<ArrayBufferLike> | Float64Array<ArrayBufferLike> |
| y | Float32Array<ArrayBufferLike> | Float64Array<ArrayBufferLike> |
Interactive Cartesian chart.
interface XYChart| ready | Promise<void> |
| engine | Engine |
| scene | Scene |
| disposed | boolean |
| xAxis | LinearAxis |
| yAxis | LinearAxis |
| cursor | CursorController |
| coordinates | CoordinateSpace |
| overlay | HTMLElement |
| theme | Theme |
| hud | PerformanceMonitor |
| legend | ChartLegend |
| annotations | AnnotationLayer |
| animations | AnimationController |
| markers | MarkerLayer |
| limitLines | LimitLineLayer |
| detectionBars | DetectionBarLayer |
| setLegendOptions | (options: LegendOptions) => XYChart |
| getComponents | () => Required<XYChartComponents> |
| setComponents | (next: boolean | XYChartComponents) => XYChart |
| use | (plugin: ChartPlugin) => XYChart |
| enableHud | () => XYChart |
| disableHud | () => XYChart |
| onLodChange | (handler: (event: LodChangeEvent) => void) => () => void |
| addLineSeries | (options?: LineSeriesOptions) => LineSeries |
| addScatterSeries | (options?: ScatterSeriesOptions) => ScatterSeries |
| addBarSeries | (options?: BarSeriesOptions) => BarSeries |
| addAreaSeries | (options?: AreaSeriesOptions) => AreaSeries |
| addStepSeries | (options?: LineSeriesOptions) => StepSeries |
| addSplineSeries | (options?: LineSeriesOptions) => SplineSeries |
| addBandSeries | (options?: LineSeriesOptions) => BandSeries |
| addHorizontalBarSeries | (options?: BarSeriesOptions) => HorizontalBarSeries |
| addBubbleSeries | (options?: ScatterSeriesOptions) => BubbleSeries |
| addErrorBarSeries | (options?: LineSeriesOptions) => ErrorBarSeries |
| addWaterfallSeries | (options?: BarSeriesOptions) => WaterfallSeries |
| addViolinSeries | (options?: LineSeriesOptions) => ViolinSeries |
| addPointSeries | (options?: ScatterSeriesOptions) => ScatterSeries |
| addHistogramSeries | (values: ArrayLike<number>, bins?: number) => BarSeries |
| addColumnSeries | (options?: BarSeriesOptions) => BarSeries |
| addStackedBarSeries | (options?: BarSeriesOptions) => StackedBarSeries |
| addStackedAreaSeries | (options?: AreaSeriesOptions) => StackedAreaSeries |
| addBoxPlotSeries | (options?: SeriesOptions) => BoxPlotSeries |
| addRectangleSeries | (options?: SeriesOptions) => RectangleSeries |
| addEllipseSeries | (options?: SeriesOptions) => EllipseSeries |
| addPolygonSeries | (options?: SeriesOptions) => PolygonSeries |
| addSegmentSeries | (options?: SeriesOptions) => SegmentSeries |
| addConstantLine | (options?: SeriesOptions) => ConstantLineSeries |
| addConstantBand | (options?: SeriesOptions) => ConstantBandSeries |
| addVectorSeries | (options?: SeriesOptions) => VectorFieldSeries |
| addYAxis | (options?: { readonly id?: string; }) => LinearAxis |
| setTitle | (title: string) => XYChart |
| setPadding | (padding: number | Partial<ThemePadding>) => XYChart |
| setUserInteractions | (next: boolean | UserInteractions) => XYChart |
| setZoomMode | (active: boolean) => XYChart |
| getZoomMode | () => boolean |
| setZoomConstraint | (axis: "x" | "y" | "both") => XYChart |
| getZoomConstraint | () => "x" | "y" | "both" |
| setCaptureDistance | (px: number) => XYChart |
| getCaptureDistance | () => number |
| pauseStreaming | () => XYChart |
| resumeStreaming | () => XYChart |
| flushIngest | () => XYChart |
| setSweepMode | (mode: "continuous" | "sweep-once" | "sweep-multi" | "none") => XYChart |
| getSweepMode | () => "continuous" | "sweep-once" | "sweep-multi" | "none" |
| setSweepSource | { (source: undefined): XYChart; (source: (frame: number) => void, options: { readonly totalFrames: number; readonly intervalMs?: number; }): XYChart; } |
| runSweepOnce | () => XYChart |
| runSweepRepeat | () => XYChart |
| stopSweep | () => XYChart |
| getSweepStatus | () => SweepStatus |
| getActiveSweepAction | () => "sweep-once" | "sweep-multi" | undefined |
| onSweepStatus | (handler: (status: SweepStatus) => void) => () => void |
| zoomIn | () => XYChart |
| zoomOut | () => XYChart |
| setTitlePosition | (position: OverlayPosition, dy?: number) => XYChart |
| setToolbarPosition | (position: OverlayPosition | "outside-bottom") => XYChart |
| setControlsPosition | (position: OverlayPosition) => XYChart |
| onViewChange | (handler: (event: { x: NumericRange; y: NumericRange; }) => void) => () => void |
| onCursorSync | (handler: (payload: { x: number; y: number; values: readonly TooltipSeriesValue[]; }) => void) => () => void |
| syncCursorFrom | (x: number, y: number, values: readonly TooltipSeriesValue[]) => void |
| zoom | (factor: number, anchor?: { x: number; y: number; }) => XYChart |
| pan | (dxPx: number, dyPx: number) => XYChart |
| restorePreviousView | () => XYChart |
| resetView | () => XYChart |
| setTheme | (theme: "light" | "dark" | Theme) => XYChart |
| setLocale | (locale: Locale) => XYChart |
| getLocale | () => Locale |
| addTranslations | (table: PartialMessages) => XYChart |
| fitView | () => XYChart |
| resize | (width?: number, height?: number) => void |
| render | () => void |
| serialize | () => ChartConfig |
| dispose | () => void |
| getSeries | () => readonly XYSeries[] |
Construction options for {@link chartXY}.
interface XYChartOptions| container | string | HTMLElement |
| canvas? | HTMLCanvasElement | undefined |
| theme? | Theme | BuiltinThemeName | undefined |
| renderer? | RendererPrefs | undefined |
| autoResize? | boolean | undefined |
| pixelRatio? | number | undefined |
| width? | number | undefined |
| height? | number | undefined |
| components? | boolean | XYChartComponents | undefined |
| captureDistance? | number | undefined |
| locale? | Locale | undefined |
| translations? | Partial<MessageTable> | undefined |
| titlePosition? | "top-right" | "top-left" | "top-center" | "bottom-right" | "bottom-left" | "bottom-center" | "middle-right" | "middle-left" | "middle-center" | undefined |
| titleOffset? | number | undefined |
| toolbarPosition? | "top-right" | "top-left" | "top-center" | "bottom-right" | "bottom-left" | "bottom-center" | "middle-right" | "middle-left" | "middle-center" | "outside-bottom" | undefined |
| controlsPosition? | "top-right" | "top-left" | "top-center" | "bottom-right" | "bottom-left" | "bottom-center" | "middle-right" | "middle-left" | "middle-center" | undefined |
Accepted XY inputs at the public series API.
type XYData = XYDataOne Cartesian sample as a public object form (PRD §6). Prefer {@link XYBuffer} on the hot path. Object arrays are converted once into typed storage internally.
interface XYPoint| x | number |
| y | number |
Got any questions? I'm happy to help with products, licensing, and examples.