@zuilib/charts 0.3.0

package/README.md

@@ -0,0 +1,140 @@
+# @zuilib/charts
+
+Enterprise analytics charts on Recharts, styled only through ZUI tokens: a
+serializable chart spec for runtime chart builders, styled primitives for
+hand-written composition, and cross-filtering that links charts to each
+other and to `@zuilib/data-grid` — without a hard dependency on it.
+
+## Install
+
+```bash
+pnpm add @zuilib/charts @zuilib/components @zuilib/tokens recharts
+```
+
+`recharts` (v3), `react` and `@zuilib/tokens` are peer dependencies. The
+package imports the `@zuilib/components` primitives, so the components'
+Tailwind source (or the prebuilt `zui.css`) must be loaded once in your
+app; with the Tailwind source, add `@source "…/@zuilib/charts/dist"` so the
+chart utilities are generated.
+
+## Usage
+
+```tsx
+import Chart from '@zuilib/charts'
+
+// Plain JSON: store it, send it from a server, let users build it.
+const spec = {
+  version: 1,
+  type: 'bar',
+  title: 'Revenue by region',
+  xKey: 'region',
+  series: [{field: 'revenue', label: 'Revenue', format: 'currency:USD'}],
+  yAxis: {format: 'compact'},
+}
+
+<Chart spec={spec} rows={rows} />
+```
+
+## Component API
+
+### Chart — `@zuilib/charts`
+
+| Prop | Type | Default |
+|------|------|---------|
+| `spec` | `ChartSpec` | required — the serializable chart description |
+| `rows` | `ChartRow[]` | required — the rows behind the chart |
+| `registry` | `ChartRegistry` | built-ins — `createChartRegistry(defaultChartTypes, yourDefs)` adds or overrides types without forking the component |
+| `formats` | `Record<string, FormatterFn \| FormatterFactory>` | — custom formatter tokens the spec may name (functions stay out of the spec) |
+| `locale` | `string` | user's locale — BCP 47 tag for formatted values |
+| `width` / `height` | `number` | responsive — fixed pixel size for tests and SSR |
+| `aspect` | `number` | `16/9` — responsive width/height ratio when `height` is left out |
+| `loading` | `boolean` | `false` — renders a skeleton instead of the chart |
+| `error` | `ReactNode` | — renders an error state instead of the chart |
+| `emptyState` | `ReactNode` | the `noData` label — renders when `rows` is empty |
+| `hiddenSeries` / `defaultHiddenSeries` / `onHiddenSeriesChange` | `string[]`, `string[]`, `(fields: string[]) => void` | — series fields hidden by the legend; controlled when `hiddenSeries` is passed, otherwise kept internally from `defaultHiddenSeries` |
+| `onMarkClick` | `(event: ChartMarkEvent) => void` | — every mark click, whether or not a `CrossFilterProvider` is present |
+| `labels` | `Partial<ChartLabels>` | English — every built-in string |
+| `animate` | `boolean` | `true` unless the user prefers reduced motion |
+| `ariaLabel` | `string` | the spec's title — accessible name of the figure |
+| `className` | `string` | merged onto the container |
+
+## Entry points
+
+`@zuilib/charts` (or `./chart`) is the config-driven renderer: ten chart
+types (line, area, bar, pie/donut, scatter, composed, radar, radial-bar,
+funnel, treemap) from one discriminated `ChartSpec`, with loading, error
+and empty states, a controlled `hiddenSeries` legend, and `onMarkClick`.
+Formats are named tokens (`'currency:USD'`, `'compact'`, `'percent'`,
+`'date:short'`) resolved through `./format`; custom formatter functions
+arrive via the `formats` prop so the spec stays JSON.
+
+`./registry` is the open chart-type registry `<Chart>` dispatches through.
+Every type is a `ChartTypeDef` — renderer, cross-filter fields, and a
+complete JSON Schema of its spec variant — and
+`createChartRegistry(defaultChartTypes, yourDefs)` merges defs last-wins
+by `type`, so an app adds or overrides a chart type without forking the
+package:
+
+```tsx
+import { createChartRegistry, defaultChartTypes, defineChartType, chartTypeSchema } from '@zuilib/charts/registry'
+
+const registry = createChartRegistry(defaultChartTypes, [
+  defineChartType<GaugeChartSpec>({
+    type: 'gauge',
+    family: 'named',
+    render: GaugeRenderer, // receives RendererProps<GaugeChartSpec> from @zuilib/charts/authoring
+    crossFilterField: (spec) => spec.nameKey,
+    schema: chartTypeSchema('gauge', {
+      nameKey: { type: 'string' },
+      valueKey: { type: 'string' },
+    }, ['nameKey', 'valueKey']),
+  }),
+])
+
+<Chart spec={gaugeSpec} rows={rows} registry={registry} />
+```
+
+Custom specs type as `CustomChartSpec` (`type` plus the shared options and
+whatever the def's schema declares); built-in specs stay the closed
+`ChartSpec` union, so the escape hatch never loosens their checking.
+`chartSpecJsonSchema(registry?)` emits the whole ChartSpec JSON Schema
+(draft 2020-12, per-type `if`/`then` conditionals from the defs' complete
+fragments) for validation and structured generation — one source, so the
+schema can't drift from what renders.
+
+`./authoring` is the custom-chart authoring surface: `RendererProps` (what
+a registered renderer receives) and the mark-interaction helpers
+(`reportMarkClick`, `activeCategoryValues`, `markDimOpacity`,
+`MarkInteraction`) that keep an app-registered chart type's clicks and
+dimming consistent with the built-ins.
+
+`./chart-frame`, `./chart-tooltip`, `./chart-legend` and
+`./chart-defaults` are the primitives for hand-written Recharts
+composition: `ChartFrame` owns the series-color CSS variables
+(`fill={seriesColorVar('revenue')}`) and the states; `ChartTooltipPanel`
+and `ChartLegendList` render on popover tokens via Recharts'
+`Tooltip`/`Legend` `content` prop, the legend as real buttons (click
+isolates, shift-click toggles, `aria-pressed`).
+
+`./cross-filter` is the shared filter/highlight state
+(`CrossFilterProvider`, `useCrossFilter`) with the same
+controlled/uncontrolled whole-state contract as the data grid; `./interop`
+is four pure converters (`toColumnFilters`, `fromColumnFilters`,
+`toHighlight`, `applyFilters`) that wire it to a data grid's
+`columnFilters` and row selection structurally, with zero imports.
+
+## Theming
+
+Series colors are the `--chart-1` … `--chart-8` tokens — a categorical
+palette validated for color-vision-deficiency separation in both modes.
+Slots are assigned in fixed declaration order and never cycled. A brand may
+override `--chart-1` with its primary hue; overriding more slots requires
+re-validating the order. Grid lines, ticks, tooltips and states read the
+same semantic tokens as every other ZUI package.
+
+## Localisation
+
+Every built-in string is overridable through the `labels` prop
+(`ChartLabels`), and every formatted value honors the `locale` prop.
+Mark entrance animation follows `prefers-reduced-motion` (or the `animate`
+prop).

package/dist/authoring.d.ts

@@ -0,0 +1,47 @@
+import { UseCrossFilterResult } from './cross-filter.js';
+import { Formatters } from './format.js';
+import { d as ChartRow, c as ChartMarkEvent } from './chart-spec-CH0tAkLG.js';
+import 'react/jsx-runtime';
+import 'react';
+
+/**
+ * Renderer plumbing shared by every chart type: the normalized mark-click
+ * pipeline (one `ChartMarkEvent` shape regardless of Recharts' per-chart
+ * payloads) and the dim/keep logic for cross-filtered marks. Public through
+ * `@zuilib/charts/authoring` for app-registered chart types; internal
+ * renderers import this module directly.
+ */
+
+interface MarkInteraction {
+    /** The category field of this chart (its `xKey` / `nameKey` / `groupKey`). */
+    field: string;
+    crossFilter: UseCrossFilterResult | null;
+    interaction: 'filter' | 'highlight' | 'none';
+    onMarkClick?: (event: ChartMarkEvent) => void;
+}
+/** What every renderer receives from the `<Chart>` dispatcher. */
+interface RendererProps<S> {
+    spec: S;
+    rows: ChartRow[];
+    formats: Formatters;
+    hiddenSeries: string[];
+    markInteraction: MarkInteraction;
+    /** Injected by `ChartFrame` at fixed size; forwarded to the chart root. */
+    width?: number;
+    /** Injected by `ChartFrame` at fixed size; forwarded to the chart root. */
+    height?: number;
+    /** Mark entrance animation; off under `prefers-reduced-motion`. */
+    animate: boolean;
+}
+/** Reports a mark click and applies the spec's cross-filter interaction. */
+declare function reportMarkClick(interaction: MarkInteraction, value: string | number, seriesField: string | undefined, row: ChartRow, additive: boolean): void;
+/**
+ * The category values whose marks render full-strength, or null when
+ * nothing dims. A highlight on this chart's field wins over its filter
+ * entry.
+ */
+declare function activeCategoryValues(interaction: MarkInteraction): (string | number)[] | null;
+/** Opacity for the mark of `value`: dimmed outside the active set. */
+declare function markDimOpacity(active: (string | number)[] | null, value: unknown): number | undefined;
+
+export { type MarkInteraction, type RendererProps, activeCategoryValues, markDimOpacity, reportMarkClick };

package/dist/authoring.js

@@ -0,0 +1,11 @@
+import {
+  activeCategoryValues,
+  markDimOpacity,
+  reportMarkClick
+} from "./chunk-HNJKYOPE.js";
+import "./chunk-7WJ26NHR.js";
+export {
+  activeCategoryValues,
+  markDimOpacity,
+  reportMarkClick
+};

package/dist/chart-defaults.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Themed default prop bags for Recharts elements, plus the palette helpers.
+ * Pure module — spread these into hand-written charts:
+ *
+ * ```tsx
+ * <XAxis dataKey="month" {...xAxisDefaults} />
+ * <CartesianGrid {...cartesianGridDefaults} />
+ * ```
+ */
+/** Number of `--chart-N` palette slots the token contract defines. */
+declare const CHART_COLOR_COUNT = 8;
+/** The CSS variable of palette slot `slot` (1-based, clamped to the palette). */
+declare function chartColorVar(slot: number): string;
+/**
+ * The CSS variable `ChartFrame` defines for a series field
+ * (`var(--color-revenue)`); non-word characters are folded to `-`.
+ */
+declare function seriesColorVar(field: string): string;
+/** The custom-property name behind `seriesColorVar` (for inline styles). */
+declare function seriesColorProperty(field: string): string;
+/** Recessive category axis: no axis or tick lines, muted tick labels. */
+declare const xAxisDefaults: {
+    readonly tickLine: false;
+    readonly axisLine: false;
+    readonly tickMargin: 8;
+    readonly tick: {
+        readonly fill: "var(--muted-foreground)";
+        readonly fontSize: 12;
+    };
+};
+/** Recessive value axis: no axis or tick lines, muted tick labels. */
+declare const yAxisDefaults: {
+    readonly tickLine: false;
+    readonly axisLine: false;
+    readonly tickMargin: 8;
+    readonly tick: {
+        readonly fill: "var(--muted-foreground)";
+        readonly fontSize: 12;
+    };
+};
+/** Horizontal-only grid on the border token. */
+declare const cartesianGridDefaults: {
+    readonly stroke: "var(--border)";
+    readonly strokeDasharray: "3 3";
+    readonly vertical: false;
+};
+/** Hover cursor for bar/area charts: a soft wash of the accent surface. */
+declare const tooltipCursorDefaults: {
+    readonly fill: "var(--accent)";
+    readonly opacity: 0.5;
+};
+/** Hover cursor for line/scatter charts: a hairline crosshair. */
+declare const tooltipCrosshairDefaults: {
+    readonly stroke: "var(--border)";
+    readonly strokeWidth: 1;
+};
+/** Opacity of marks outside the active cross-filter or highlight. */
+declare const DIMMED_OPACITY = 0.35;
+
+export { CHART_COLOR_COUNT, DIMMED_OPACITY, cartesianGridDefaults, chartColorVar, seriesColorProperty, seriesColorVar, tooltipCrosshairDefaults, tooltipCursorDefaults, xAxisDefaults, yAxisDefaults };

package/dist/chart-defaults.js

@@ -0,0 +1,24 @@
+import {
+  CHART_COLOR_COUNT,
+  DIMMED_OPACITY,
+  cartesianGridDefaults,
+  chartColorVar,
+  seriesColorProperty,
+  seriesColorVar,
+  tooltipCrosshairDefaults,
+  tooltipCursorDefaults,
+  xAxisDefaults,
+  yAxisDefaults
+} from "./chunk-7WJ26NHR.js";
+export {
+  CHART_COLOR_COUNT,
+  DIMMED_OPACITY,
+  cartesianGridDefaults,
+  chartColorVar,
+  seriesColorProperty,
+  seriesColorVar,
+  tooltipCrosshairDefaults,
+  tooltipCursorDefaults,
+  xAxisDefaults,
+  yAxisDefaults
+};

package/dist/chart-frame-B9fxUxGG.d.ts

@@ -0,0 +1,90 @@
+import * as react from 'react';
+import { ComponentPropsWithoutRef, ReactNode } from 'react';
+import { createFormatters } from './format.js';
+import { F as FormatToken } from './chart-spec-CH0tAkLG.js';
+
+/**
+ * Every string a chart renders or announces, overridable for another
+ * language. A `{name}` placeholder is replaced with the value named.
+ */
+interface ChartLabels {
+    /** The default empty state. @default 'No data' */
+    noData: string;
+    /** Announced while `loading`. @default 'Loading chart…' */
+    loading: string;
+    /** The default error state title. @default 'Chart failed to load' */
+    chartError: string;
+    /** A legend button. `{series}` is replaced. @default 'Toggle {series}' */
+    toggleSeries: string;
+    /** The legend list's accessible name. @default 'Chart legend' */
+    legend: string;
+    /** Announced on a cross-filtering mark. `{value}` is replaced. @default 'Filter by {value}' */
+    filterBy: string;
+}
+declare const defaultChartLabels: ChartLabels;
+/** Replaces each `{name}` in a label with `values[name]`. */
+declare function fillLabel(template: string, values: Record<string, string | number>): string;
+
+/** How one series is labeled and colored. */
+interface ChartSeriesConfig {
+    /** Legend / tooltip name. */
+    label: string;
+    /** Any CSS color; `var(--chart-N)` normally. Wins over `theme`. */
+    color?: string;
+    /** Per-mode colors, emitted scoped to this chart for light and `.dark`. */
+    theme?: {
+        light: string;
+        dark: string;
+    };
+    /** Value format for tooltip rows of this series. */
+    format?: FormatToken;
+}
+/** Series field → its config. Key order assigns the default palette slots. */
+type ChartConfig = Record<string, ChartSeriesConfig>;
+interface ChartFrameProps extends Omit<ComponentPropsWithoutRef<'div'>, 'children'> {
+    /** The series behind the chart; drives colors, the legend and the tooltip. */
+    config: ChartConfig;
+    /** Recharts elements (one chart root, e.g. `<BarChart>`). */
+    children: ReactNode;
+    /**
+     * Fixed pixel size. Both set, the chart renders at exactly this size with
+     * no `ResizeObserver` (tests, SSR); otherwise it fills its parent's width.
+     */
+    width?: number;
+    /** Fixed pixel height (with `width`), or the responsive height. @default aspect-driven */
+    height?: number;
+    /** Responsive width/height ratio when `height` is left out. @default 16/9 */
+    aspect?: number;
+    /** Renders a skeleton instead of the chart. @default false */
+    loading?: boolean;
+    /** Renders an error state instead of the chart. */
+    error?: ReactNode;
+    /** Renders instead of the chart when `empty`. @default the `noData` label */
+    emptyState?: ReactNode;
+    /** Marks the data empty. @default false */
+    empty?: boolean;
+    /** Accessible name of the figure. */
+    ariaLabel?: string;
+    /** String overrides for another language. */
+    labels?: Partial<ChartLabels>;
+    /** Custom format tokens the series configs may name. */
+    formats?: Parameters<typeof createFormatters>[1];
+    /** BCP 47 tag for formatted values. @default the user's locale */
+    locale?: string;
+    /** Series fields hidden by the legend (controlled; kept internally when left out). */
+    hiddenSeries?: string[];
+    /** Series fields hidden initially when uncontrolled. @default [] */
+    defaultHiddenSeries?: string[];
+    /** Reports the next hidden set on a legend interaction. */
+    onHiddenSeriesChange?: (fields: string[]) => void;
+    /** Category charts: the field legend entries cross-filter on. */
+    categoryField?: string;
+    /** Category charts: the legend entries, in palette order. */
+    categories?: {
+        value: string | number;
+        color: string;
+    }[];
+}
+declare const ChartFrame: react.ForwardRefExoticComponent<ChartFrameProps & react.RefAttributes<HTMLDivElement>>;
+
+export { type ChartConfig as C, ChartFrame as a, type ChartFrameProps as b, type ChartLabels as c, type ChartSeriesConfig as d, defaultChartLabels as e, fillLabel as f };

package/dist/chart-frame.d.ts

@@ -0,0 +1,4 @@
+import 'react';
+import './format.js';
+import './chart-spec-CH0tAkLG.js';
+export { C as ChartConfig, a as ChartFrame, b as ChartFrameProps, d as ChartSeriesConfig, a as default } from './chart-frame-B9fxUxGG.js';

package/dist/chart-frame.js

@@ -0,0 +1,14 @@
+"use client";
+import {
+  ChartFrame,
+  chart_frame_default
+} from "./chunk-G4FXJJ66.js";
+import "./chunk-7WABBHMT.js";
+import "./chunk-3VGLTPGL.js";
+import "./chunk-UN3XPBZ5.js";
+import "./chunk-IPOBQIYU.js";
+import "./chunk-7WJ26NHR.js";
+export {
+  ChartFrame,
+  chart_frame_default as default
+};

package/dist/chart-legend.d.ts

@@ -0,0 +1,25 @@
+import { ReactNode } from 'react';
+
+/**
+ * Interactive themed legend list. Recharts' `Legend` wires it into the
+ * chart; pass `content={<ChartLegendList />}` to get real buttons: a plain
+ * click isolates the series (and restores all when it is already alone),
+ * shift-click toggles just it. On category charts (pie family) the buttons
+ * cross-filter the category value instead.
+ */
+
+interface LegendEntry {
+    dataKey?: unknown;
+    value?: unknown;
+    color?: string;
+}
+interface ChartLegendListProps {
+    /** Injected by Recharts. */
+    payload?: readonly LegendEntry[];
+    /** Extra classes on the list. */
+    className?: string;
+}
+/** One legend button per entry; hidden entries dim but never disappear. */
+declare function ChartLegendList({ payload, className }: ChartLegendListProps): ReactNode;
+
+export { ChartLegendList, type ChartLegendListProps, ChartLegendList as default };

package/dist/chart-legend.js

@@ -0,0 +1,13 @@
+"use client";
+import {
+  ChartLegendList,
+  chart_legend_default
+} from "./chunk-SHQZRND7.js";
+import "./chunk-WVWGHGZE.js";
+import "./chunk-UN3XPBZ5.js";
+import "./chunk-IPOBQIYU.js";
+import "./chunk-7WJ26NHR.js";
+export {
+  ChartLegendList,
+  chart_legend_default as default
+};

package/dist/chart-spec-CH0tAkLG.d.ts

@@ -0,0 +1,226 @@
+/**
+ * The serializable chart contract. Everything in a `ChartSpec` is JSON-safe —
+ * no functions, no dates, no JSX — so a spec can be stored in a database,
+ * sent by a server, or produced by a runtime chart builder. Formatting is
+ * named by token (see `format.ts`); custom formatter functions travel as
+ * React props on `<Chart>`, never inside the spec.
+ */
+/**
+ * Names a formatter: a built-in (`'number'`, `'compact'`, `'percent'`,
+ * `'currency:USD'`, `'date:short'`, `'datetime:medium'`, `'none'`) or a
+ * custom token registered through `<Chart formats={...}>`. The part after
+ * `:` is the factory argument.
+ */
+type FormatToken = string;
+/** One plotted series: a row field, and how it is drawn and labeled. */
+interface SeriesSpec {
+    /** Row field holding this series' value. */
+    field: string;
+    /** Legend / tooltip name. @default the field */
+    label?: string;
+    /**
+     * Palette slot 1–8 (`--chart-N`). Left out, slots are assigned in series
+     * declaration order — fixed order, never cycled.
+     */
+    paletteSlot?: number;
+    /**
+     * Value axis. `'secondary'` enables the secondary axis; prefer small
+     * multiples over dual axes. @default 'primary'
+     */
+    axis?: 'primary' | 'secondary';
+    /** Series sharing a `stackId` stack; `stacked` on the spec is shorthand for one shared stack. */
+    stackId?: string;
+    /** Composed charts only: how this series is drawn. @default 'bar' */
+    mark?: 'line' | 'area' | 'bar';
+    /** Value format for tooltips and labels. @default the spec's y-axis format */
+    format?: FormatToken;
+}
+/** Axis options. All optional; defaults come from the themed axis prop bags. */
+interface AxisSpec {
+    /** Axis title. */
+    label?: string;
+    /** Tick format. */
+    format?: FormatToken;
+    /** Value-axis domain. @default ['auto', 'auto'] */
+    domain?: [number | 'auto' | 'dataMin', number | 'auto' | 'dataMax'];
+    /** Suggested tick count. */
+    tickCount?: number;
+    /** Hides the axis entirely. @default false */
+    hidden?: boolean;
+    /** X axis only: the scale the x values live on. @default 'band' */
+    scale?: 'band' | 'number' | 'time' | 'log';
+}
+/** A horizontal or vertical reference line. */
+interface ReferenceLineSpec {
+    /**
+     * Which axis the value belongs to: `'y'`/`'y2'` draw horizontal lines
+     * (`'y2'` positions on the secondary value axis), `'x'` vertical.
+     */
+    axis: 'x' | 'y' | 'y2';
+    /** Position on that axis. */
+    value: number | string;
+    /** Text beside the line. */
+    label?: string;
+    /** Palette slot 1–8. @default the muted foreground */
+    paletteSlot?: number;
+    /** Dashed stroke. @default true */
+    dashed?: boolean;
+}
+/** Options shared by every chart type. */
+interface ChartSpecCommon {
+    /** Contract version of this spec. */
+    version: 1;
+    /** Figure title, also the default accessible name. */
+    title?: string;
+    /** Longer description for assistive tech. */
+    description?: string;
+    /** Legend visibility/placement. @default true for two or more series, false for one */
+    legend?: boolean | {
+        placement: 'top' | 'bottom';
+    };
+    /** @default true */
+    tooltip?: boolean;
+    /**
+     * What a mark click does inside a `CrossFilterProvider`: update the shared
+     * filters, only the shared highlight, or nothing. @default 'filter'
+     */
+    interaction?: 'filter' | 'highlight' | 'none';
+}
+/** The cartesian frame: axes, grid, reference lines, brush. */
+interface CartesianFrameSpec extends ChartSpecCommon {
+    xAxis?: AxisSpec;
+    yAxis?: AxisSpec;
+    /** Secondary value axis; used by series with `axis: 'secondary'`. */
+    secondaryAxis?: AxisSpec;
+    /** Grid lines. @default horizontal only */
+    grid?: boolean | {
+        horizontal?: boolean;
+        vertical?: boolean;
+    };
+    referenceLines?: ReferenceLineSpec[];
+    /** Renders a range brush under the plot. @default false */
+    brush?: boolean;
+}
+/** Options shared by the series-based cartesian chart types. */
+interface CartesianSpecCommon extends CartesianFrameSpec {
+    /** Category / x field. Also the field mark clicks cross-filter on. */
+    xKey: string;
+    /** The plotted series, in palette-slot order. */
+    series: SeriesSpec[];
+}
+interface LineChartSpec extends CartesianSpecCommon {
+    type: 'line';
+    /** @default 'monotone' */
+    curve?: 'linear' | 'monotone' | 'step';
+    /** Dots on every point (dots always show on hover). @default false */
+    dots?: boolean;
+}
+interface AreaChartSpec extends CartesianSpecCommon {
+    type: 'area';
+    /** @default 'monotone' */
+    curve?: 'linear' | 'monotone' | 'step';
+    /** `true` stacks the series; `'percent'` normalizes each stack to 100%. @default false */
+    stacked?: boolean | 'percent';
+}
+interface BarChartSpec extends CartesianSpecCommon {
+    type: 'bar';
+    /** Bar direction: `'horizontal'` lays categories on the y axis. @default 'vertical' */
+    orientation?: 'vertical' | 'horizontal';
+    /** `true` stacks the series; `'percent'` normalizes each stack to 100%. @default false */
+    stacked?: boolean | 'percent';
+}
+interface ScatterChartSpec extends CartesianFrameSpec {
+    type: 'scatter';
+    /** Row field of the x value (numeric). */
+    xKey: string;
+    /** Row field of the y value. */
+    yKey: string;
+    /**
+     * Row field that splits points into colored groups; at most 3 concurrent
+     * groups (the all-pairs-validated palette subset). Also the field mark
+     * clicks cross-filter on. Left out, all points form one series.
+     */
+    groupKey?: string;
+    /** Row field sized into bubble area. */
+    sizeKey?: string;
+    /** Bubble size range in px². @default [64, 400] */
+    sizeRange?: [number, number];
+}
+interface ComposedChartSpec extends CartesianSpecCommon {
+    type: 'composed';
+    /** Stacks the bar series. @default false */
+    stacked?: boolean;
+}
+interface PieChartSpec extends ChartSpecCommon {
+    /** `'donut'` is a pie with an inner radius. */
+    type: 'pie' | 'donut';
+    /** Row field of the slice name; also the cross-filter field. */
+    nameKey: string;
+    /** Row field of the slice value. */
+    valueKey: string;
+    /** Value format for tooltip and labels. @default 'number' */
+    format?: FormatToken;
+    /** Direct labels beside the slices. @default false */
+    labels?: boolean;
+}
+interface RadarChartSpec extends ChartSpecCommon {
+    type: 'radar';
+    /** Row field of the spoke name. */
+    xKey: string;
+    /** The plotted series. */
+    series: SeriesSpec[];
+    /** Translucent fill under each outline. @default true */
+    filled?: boolean;
+}
+interface RadialBarChartSpec extends ChartSpecCommon {
+    type: 'radial-bar';
+    /** Row field of the ring name; also the cross-filter field. */
+    nameKey: string;
+    /** Row field of the ring value. */
+    valueKey: string;
+    /** Domain start. @default 0 */
+    min?: number;
+    /** Domain end. @default the data max */
+    max?: number;
+    /** @default 'number' */
+    format?: FormatToken;
+}
+interface FunnelChartSpec extends ChartSpecCommon {
+    type: 'funnel';
+    /** Row field of the stage name; also the cross-filter field. */
+    nameKey: string;
+    /** Row field of the stage value. */
+    valueKey: string;
+    /** @default 'number' */
+    format?: FormatToken;
+}
+interface TreemapChartSpec extends ChartSpecCommon {
+    type: 'treemap';
+    /** Row field of the tile name; also the cross-filter field. */
+    nameKey: string;
+    /** Row field sized into tile area. */
+    sizeKey: string;
+    /** Row field that groups tiles into colored clusters. */
+    groupKey?: string;
+    /** @default 'number' */
+    format?: FormatToken;
+}
+/** The serializable chart description `<Chart>` renders. Discriminated on `type`. */
+type ChartSpec = LineChartSpec | AreaChartSpec | BarChartSpec | ScatterChartSpec | ComposedChartSpec | PieChartSpec | RadarChartSpec | RadialBarChartSpec | FunnelChartSpec | TreemapChartSpec;
+/** A row of chart data. Values are read through the spec's row fields. */
+type ChartRow = Record<string, unknown>;
+/** What a mark click reports, whether or not a `CrossFilterProvider` is present. */
+interface ChartMarkEvent {
+    /** The field the clicked mark belongs to (the spec's `xKey` / `nameKey`). */
+    field: string;
+    /** The clicked mark's category value. */
+    value: string | number;
+    /** The clicked series' field, when the mark belongs to one. */
+    seriesField?: string;
+    /** The full row behind the mark. */
+    row: ChartRow;
+    /** Whether the click asked for additive (shift-click) filtering. */
+    additive: boolean;
+}
+
+export type { AreaChartSpec as A, BarChartSpec as B, CartesianFrameSpec as C, FormatToken as F, LineChartSpec as L, PieChartSpec as P, RadarChartSpec as R, ScatterChartSpec as S, TreemapChartSpec as T, AxisSpec as a, CartesianSpecCommon as b, ChartMarkEvent as c, ChartRow as d, ChartSpec as e, ChartSpecCommon as f, ComposedChartSpec as g, FunnelChartSpec as h, RadialBarChartSpec as i, ReferenceLineSpec as j, SeriesSpec as k };