@open-tomato/charts 0.0.0-stage → 0.1.1

package/dist/lib/index.d.ts

@@ -0,0 +1,2 @@
+/** Shared helpers every layer may import: `cn` today. */
+export { cn } from './cn.js';

package/dist/seam/ChartEngineProvider.d.ts

@@ -0,0 +1,12 @@
+import type { ChartPrimitives } from './types.js';
+import { type ReactElement, type ReactNode } from 'react';
+/** The props of {@link ChartEngineProvider}. */
+export interface ChartEngineProviderProps {
+    /** The engine every chart below draws with. */
+    readonly engine: ChartPrimitives;
+    readonly children: ReactNode;
+}
+/** Puts one engine in scope for the charts below it. */
+export declare function ChartEngineProvider({ engine, children }: ChartEngineProviderProps): ReactElement;
+/** The engine in scope; throws outside a provider so a missing wrap is loud. */
+export declare function useChartEngine(): ChartPrimitives;

package/dist/seam/FormatProvider.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The format context as React state: `FormatProvider` puts a locale, a
+ * currency and the custom formatters in scope, and `useFormatter` turns a
+ * `ValueFormat` into a primitive's `valueFormat` function over them. Kept
+ * apart from `format.ts`, so the headless engine imports no React.
+ */
+import { type ReactElement, type ReactNode } from 'react';
+import { type FormatContext, type ValueFormat, type ValueFormatter } from './format.js';
+/** The props of {@link FormatProvider}. */
+export interface FormatProviderProps {
+    /** The locale, currency and custom formatters below; keep the object stable across renders. */
+    readonly context: FormatContext;
+    readonly children: ReactNode;
+}
+/** Puts one format context in scope for the charts below it. */
+export declare function FormatProvider({ context, children }: FormatProviderProps): ReactElement;
+/** The format context in scope; the defaults (`en-GB`, `USD`, `UTC`) outside a provider. */
+export declare function useFormatContext(): FormatContext;
+/**
+ * `spec` as a `valueFormat` function over the context in scope, or
+ * undefined when `spec` is, so the primitive keeps its own default. The
+ * function is rebuilt only when the spec's content or the context changes,
+ * so an inline spec literal does not redraw the chart.
+ */
+export declare function useFormatter(spec?: ValueFormat): ValueFormatter | undefined;

package/dist/seam/format.d.ts

@@ -0,0 +1,171 @@
+/**
+ * Value formatting shared by the engines and the atoms: the plain helpers
+ * (`formatCompact`, `formatDay` and the rest), and the declarative
+ * `ValueFormat` spec, which `formatterFor` turns into the `(value) => string`
+ * function every primitive's `valueFormat` takes. No React and no zod, so
+ * the headless engine carries it; the zod schemas are in `format.schema.ts`
+ * and the React context in `FormatProvider.tsx`.
+ *
+ * Every date is written in UTC, so a tick label never depends on the
+ * machine's timezone.
+ */
+/** 1,284 → "1.3K", 4,200,000 → "4.2M"; integers below 1,000 stay as they are. */
+export declare function formatCompact(value: number): string;
+/** 0.78 → "78%". */
+export declare function formatPercent(fraction: number): string;
+/** 45 → "45 min", 90 → "1.5 h". */
+export declare function formatMinutes(minutes: number): string;
+/** A day as "1 Nov", in a fixed locale and in UTC, so the label never depends on the viewer. */
+export declare function formatDay(date: Date): string;
+/** The week starting on a date, as "w/c 1 Nov", in UTC. */
+export declare function formatWeek(date: Date): string;
+/**
+ * A count of seconds as "1h 3m 10s": zero units left out ("1h 10s"),
+ * "0s" for nothing, sub-second precision dropped, a negative count
+ * clamped to "0s".
+ */
+export declare function formatElapsed(seconds: number): string;
+/**
+ * An instant relative to `now`, on a ladder: the same UTC day reads as a
+ * clock time ("23:30"); then "6 hours ago", "yesterday", "3 days ago",
+ * "last week", "2 weeks ago", "last month", "4 months ago", "last year",
+ * "2 years ago". Months and years use average lengths. An instant after
+ * `now` mirrors the ladder ("tomorrow", "in 3 days").
+ */
+export declare function formatRelative(value: Date | number, now: Date | number, locale?: string): string;
+/** The kinds a {@link ValueFormat} can name. */
+export declare const VALUE_FORMAT_KINDS: readonly ["raw", "number", "compact", "percent", "money", "unit", "duration", "elapsed", "date", "relative", "custom"];
+/** How a `date` format writes its value: "1 Nov", "w/c 1 Nov", "23:30", "1 Nov, 23:30", "Nov 2026". */
+export declare const DATE_PATTERNS: readonly ["day", "week", "time", "datetime", "month"];
+/** The unit a `duration` format reads its value in. */
+export declare const DURATION_UNITS: readonly ["minutes", "seconds", "ms"];
+/** What a `percent` format's value is: a fraction (0.78) or already a percent (78). */
+export declare const PERCENT_BASES: readonly ["fraction", "percent"];
+/** Which side of the number a `unit` format puts its unit. */
+export declare const UNIT_POSITIONS: readonly ["after", "before"];
+export type ValueFormatKind = typeof VALUE_FORMAT_KINDS[number];
+export type DatePattern = typeof DATE_PATTERNS[number];
+export type DurationUnit = typeof DURATION_UNITS[number];
+export type PercentBase = typeof PERCENT_BASES[number];
+export type UnitPosition = typeof UNIT_POSITIONS[number];
+/**
+ * How a value is written, as data a spec or a data point can carry. Each
+ * kind reads the locale and the currency from the {@link FormatContext}
+ * unless it names its own. `digits` is the number of fraction digits, fixed.
+ */
+export type ValueFormat = 
+/** `String(value)`, or `value.toFixed(digits)`. */
+{
+    readonly kind: 'raw';
+    readonly digits?: number;
+}
+/** `Intl.NumberFormat` in the context's locale; `grouping` is on unless false. */
+ | {
+    readonly kind: 'number';
+    readonly digits?: number;
+    readonly grouping?: boolean;
+}
+/** `formatCompact`: 1,000 → "1K", 1,200,000 → "1.2M", in every locale. */
+ | {
+    readonly kind: 'compact';
+}
+/** 0.78 → "78%" (`of: 'fraction'`, the default), or 78 → "78%" (`of: 'percent'`); `signed` writes "+12%" and "-30%". */
+ | {
+    readonly kind: 'percent';
+    readonly digits?: number;
+    readonly of?: PercentBase;
+    readonly signed?: boolean;
+}
+/** A currency amount; the currency is the context's when the format names none. `compact` writes "$1.2K". */
+ | {
+    readonly kind: 'money';
+    readonly currency?: string;
+    readonly digits?: number;
+    readonly compact?: boolean;
+}
+/** "45 min" (`after`, the default, with a space) or "£45" (`before`, no space). */
+ | {
+    readonly kind: 'unit';
+    readonly unit: string;
+    readonly position?: UnitPosition;
+}
+/** A duration read in `from`, written by `formatMinutes`: "45 min", "1.5 h". */
+ | {
+    readonly kind: 'duration';
+    readonly from: DurationUnit;
+}
+/** A duration read in `from`, written by `formatElapsed`: "1h 3m 10s". */
+ | {
+    readonly kind: 'elapsed';
+    readonly from: DurationUnit;
+}
+/** An epoch in ms, written in UTC by `pattern`. */
+ | {
+    readonly kind: 'date';
+    readonly pattern: DatePattern;
+}
+/** An epoch in ms, written by `formatRelative` against the context's `now`, or the wall clock. */
+ | {
+    readonly kind: 'relative';
+}
+/** A formatter the context registers under `id` in `customFormatters`. */
+ | {
+    readonly kind: 'custom';
+    readonly id: string;
+};
+/** A value-to-text function, the shape of every primitive's `valueFormat`. */
+export type ValueFormatter = (value: number) => string;
+/** What a {@link ValueFormat} reads when it does not say: the locale, the currency, the custom formatters. */
+export interface FormatContext {
+    /** A BCP 47 tag; `en-GB` when absent. */
+    readonly locale?: string;
+    /** An ISO 4217 code for `money`; `USD` when absent. */
+    readonly currency?: string;
+    /** Dates are always written in UTC; the field names it so a contract can carry it. */
+    readonly timeZone?: 'UTC';
+    /** Formatters a `custom` format names by id, registered by the hub or an app. */
+    readonly customFormatters?: Readonly<Record<string, ValueFormatter>>;
+    /** The instant a `relative` format counts from, as an epoch in ms; the wall clock when absent. */
+    readonly now?: number;
+}
+/** A {@link FormatContext} with every default filled in; `now` stays open, so a relative value reads the clock when it is written. */
+export interface ResolvedFormatContext {
+    readonly locale: string;
+    readonly currency: string;
+    readonly timeZone: 'UTC';
+    readonly customFormatters: Readonly<Record<string, ValueFormatter>>;
+    readonly now?: number;
+}
+/** The defaults: `en-GB`, `USD`, `UTC`, no custom formatters. */
+export declare const DEFAULT_FORMAT_CONTEXT: ResolvedFormatContext;
+/** The context with its gaps filled from {@link DEFAULT_FORMAT_CONTEXT}. */
+export declare function resolveFormatContext(context?: FormatContext): ResolvedFormatContext;
+/**
+ * A date or an epoch in ms, written in UTC by `pattern` in `locale`
+ * (`en-GB` by default). `datetime` joins the day and the time with a comma
+ * rather than taking the locale's own joiner, which differs between ICU
+ * versions. `week` prefixes the day with "w/c" in every locale.
+ */
+export declare function formatDate(value: Date | number, pattern: DatePattern, locale?: string): string;
+/**
+ * The function that writes values as `spec` says, over `context`'s locale,
+ * currency and custom formatters. Throws when a `custom` id is not
+ * registered, or when `spec` names no known kind.
+ */
+export declare function formatterFor(spec: ValueFormat, context?: FormatContext): ValueFormatter;
+/** A value with its own unit and, optionally, its own format, which wins over the chart's. */
+export interface Measured {
+    readonly value: number;
+    /** Written after the number when the format writes no unit of its own. */
+    readonly unit?: string;
+    /** This value's format; it wins over the spec's. */
+    readonly format?: ValueFormat;
+}
+/**
+ * A measured value as text. The format is the point's own, else
+ * `specFormat`, else a `number` in the context's locale; the context fills
+ * whatever the format leaves out. The point's `unit` follows a bare number
+ * ("45 min"); a format with a unit of its own (percent, money, unit,
+ * duration, elapsed, date, relative, custom) keeps it alone.
+ */
+export declare function formatMeasured(measured: Measured, context?: FormatContext, specFormat?: ValueFormat): string;

package/dist/seam/format.schema.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The format spec as zod v4 schemas, for a contract that carries a
+ * `ValueFormat` or a `FormatContext` as data (`@open-tomato/atlas-ui`'s
+ * card contract embeds them). The types live in `format.ts`; each schema is
+ * annotated with its type because the repo compiles with
+ * `isolatedDeclarations`, and the annotation also holds the schema to it.
+ * Widen the type and the schema together.
+ */
+import type { FormatContext, ValueFormat } from './format.js';
+import { z } from 'zod';
+/** A `ValueFormat`, discriminated on `kind`. */
+export declare const valueFormatSchema: z.ZodType<ValueFormat>;
+/** A `FormatContext`; `customFormatters` holds functions, so it validates only in code, never from JSON. */
+export declare const formatContextSchema: z.ZodType<FormatContext>;

package/dist/seam/height.d.ts

@@ -0,0 +1,15 @@
+/**
+ * How tall a chart draws. A number is a plot height in px. `'fill'` takes
+ * the full height of the chart's container, which must have a height of
+ * its own (a sized box, a flex or grid cell that is stretched); the chart
+ * then follows that container as it resizes.
+ */
+export type ChartHeight = number | 'fill';
+/** Plot height in px when a chart is given none. */
+export declare const DEFAULT_CHART_HEIGHT = 220;
+/**
+ * The height in px a layout works with: the given px, or for `'fill'` the
+ * measured px of the container, or the default while nothing is measured
+ * yet (the first render, a headless drawing that did not resolve it).
+ */
+export declare function plotHeightOf(height: ChartHeight | undefined, measured?: number): number;

package/dist/seam/index.d.ts

@@ -0,0 +1,12 @@
+/** The seam: ChartPrimitives types, chart tones, formatters and the ChartEngineProvider. Engine-free. */
+export * from './types.js';
+export * from './height.js';
+export { ALL_TONES, CHROME_ROLES, SEQUENTIAL_STEPS, chartTone, readTokens, tokensFrom, toneVar, } from './tones.js';
+export type { ChartToneVariantProps, ChartToneVariants, ResolvedTokens } from './tones.js';
+export { useResolvedTokens } from './useResolvedTokens.js';
+export * from './format.js';
+export * from './format.schema.js';
+export { FormatProvider, useFormatContext, useFormatter } from './FormatProvider.js';
+export type { FormatProviderProps } from './FormatProvider.js';
+export { ChartEngineProvider, useChartEngine } from './ChartEngineProvider.js';
+export type { ChartEngineProviderProps } from './ChartEngineProvider.js';

package/dist/seam/tones.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Tone helpers shared by every engine. The names come from the theme's one
+ * token list (`../theme/`), so there is no second list to keep in step.
+ *
+ * - `chartTone`: the CVA variant that sets `color`, so SVG marks paint with
+ *   `currentColor`.
+ * - `toneVar`: the same token as a CSS `var()` string, for engines that take a
+ *   colour string per series.
+ * - `readTokens`: the tokens read from the computed style of `<html>`, for
+ *   canvas engines that cannot read CSS variables (ECharts);
+ *   `useResolvedTokens` (`useResolvedTokens.ts`) re-reads them on a flip.
+ * - `tokensFrom`: the same map from values a caller holds, for the headless
+ *   engine, which has no page to read.
+ *
+ * No React here, so the headless engine can import it.
+ */
+import type { ChartTone } from './types.js';
+import { type VariantProps } from 'class-variance-authority';
+import { type TokenName } from '../theme/index.js';
+/**
+ * The CVA variants that set `color` to a tone's token. The class names are
+ * written out in full so Tailwind can see them in this file.
+ */
+export declare const chartTone: (props?: ChartToneVariantProps) => string;
+/** The variant props `chartTone` takes. */
+export interface ChartToneVariantProps {
+    readonly tone?: ChartTone | null;
+}
+/** The variant props, as CVA reads them off the variants function. */
+export type ChartToneVariants = VariantProps<typeof chartTone>;
+/** Every tone, in the order the theme lists its tokens: series, status, poles, then the two neutrals. */
+export declare const ALL_TONES: readonly ChartTone[];
+/** The sequential ramp (light to dark) as token names, for heatmaps. */
+export declare const SEQUENTIAL_STEPS: readonly string[];
+/** Chrome roles the engines need beside the series tones. */
+export declare const CHROME_ROLES: readonly string[];
+/** `var(--color-<token>)` for a tone or a chrome role. */
+export declare function toneVar(toneOrRole: ChartTone | string): string;
+/** Concrete colour strings keyed by tone and by token name (`series-1`, `ink`, `seq-300`). */
+export type ResolvedTokens = Record<string, string>;
+/** Reads every token from the computed style of `<html>`; a name the theme leaves undefined reads as an empty string. */
+export declare function readTokens(): ResolvedTokens;
+/**
+ * The resolved tokens from values the caller holds, keyed by token name
+ * without its prefix (`series-1`, `ink`, `seq-300`): every token is kept
+ * under its name and every tone under its own, `neutral` reading `ink-2`.
+ * A headless caller has no CSS variables to read, so it passes the full set.
+ */
+export declare function tokensFrom(values: Readonly<Record<TokenName, string>>): ResolvedTokens;

package/dist/seam/types.d.ts

@@ -0,0 +1,322 @@
+/**
+ * The ChartPrimitives seam: the one interface every engine implements, so a
+ * card never imports a chart library. Props carry data and tones only;
+ * colours are resolved by the engine from the CSS tokens (see tones.ts).
+ */
+import type { ChartHeight } from './height.js';
+import type { POLE_TOKENS, SERIES_TOKENS, STATUS_TOKENS, TokenName } from '../theme/index.js';
+import type { ComponentType } from 'react';
+export type EngineId = 'echarts';
+/** A series colour name: `series-1` to `series-8`. */
+export type SeriesTone = TokenName<typeof SERIES_TOKENS[number]>;
+/** A status colour name: `good`, `warning`, `serious`, `critical`. */
+export type StatusTone = TokenName<typeof STATUS_TOKENS[number]>;
+/** A balance pole colour name: the rim colour and the `-core` colour at the centre. */
+export type PoleTone = TokenName<typeof POLE_TOKENS[number]>;
+/** A role, never a hex: the engines paint marks with the token behind it. */
+export type ChartTone = SeriesTone | StatusTone | PoleTone | 'neutral' | 'muted';
+export interface ChartCommonProps {
+    /**
+     * Plot height: px, or `'fill'` for the full height of the container, which
+     * must have a height of its own (a maximised card's box). 220px when absent.
+     * The width always follows the container.
+     */
+    height?: ChartHeight;
+    className?: string;
+    /** Read by assistive tech on the chart root; required. */
+    ariaLabel: string;
+    /** Formats a value for axis ticks, direct labels and tooltips. */
+    valueFormat?: (value: number) => string;
+    /**
+     * Mount animation and animated layouts. Defaults to true; stories, captures
+     * and tests that need a still picture pass false.
+     */
+    animate?: boolean;
+}
+export interface BarSeries {
+    id: string;
+    label: string;
+    tone: ChartTone;
+    /** One value per category, same order as `categories`. */
+    values: readonly number[];
+}
+export interface BarChartProps extends ChartCommonProps {
+    categories: readonly string[];
+    series: readonly BarSeries[];
+    /** grouped: side by side; stacked: sums; stacked100: shares of the category total. */
+    mode?: 'grouped' | 'stacked' | 'stacked100';
+    orientation?: 'vertical' | 'horizontal';
+    /** A reference line across the value axis (a WIP limit, a target). */
+    limit?: {
+        value: number;
+        label: string;
+    };
+}
+export interface TimePoint {
+    x: Date;
+    y: number;
+}
+export interface LineSeries {
+    id: string;
+    label: string;
+    tone: ChartTone;
+    points: readonly TimePoint[];
+}
+export interface LineChartProps extends ChartCommonProps {
+    series: readonly LineSeries[];
+    /** line: strokes only; area: one series with a 10% wash; stacked-area: sums. */
+    variant?: 'line' | 'area' | 'stacked-area';
+    /** A horizontal reference (an average, a target). */
+    baseline?: {
+        value: number;
+        label: string;
+    };
+    xFormat?: (date: Date) => string;
+    /** Pins the time axis's ticks to a step: `week` starts on a Monday and ticks every seven days, for a weekly `xFormat`. */
+    xStep?: 'week';
+    /** A range selector under the plot (a brush or data zoom); the plot shows the selected range. */
+    zoom?: boolean;
+    /** Fires when the selected range changes; null when the whole range is back. */
+    onRangeChange?: (range: {
+        from: Date;
+        to: Date;
+    } | null) => void;
+}
+export interface ScatterPoint {
+    x: Date;
+    y: number;
+    label: string;
+}
+export interface ScatterChartProps extends ChartCommonProps {
+    points: readonly ScatterPoint[];
+    /** A smoothed line over the points (a moving average), same x domain. */
+    trend?: readonly TimePoint[];
+    trendLabel?: string;
+    pointsLabel: string;
+    yLabel: string;
+    xFormat?: (date: Date) => string;
+}
+export interface HistogramBin {
+    from: number;
+    to: number;
+    count: number;
+}
+export interface HistogramProps extends ChartCommonProps {
+    bins: readonly HistogramBin[];
+    /** The unit of the binned value, for the x axis ("min"). */
+    unit: string;
+}
+export interface BoxGroup {
+    label: string;
+    min: number;
+    q1: number;
+    median: number;
+    q3: number;
+    max: number;
+    outliers?: readonly number[];
+}
+export interface BoxPlotProps extends ChartCommonProps {
+    groups: readonly BoxGroup[];
+    unit: string;
+}
+export interface GaugeProps extends ChartCommonProps {
+    value: number;
+    max: number;
+    label: string;
+    /** Fractions of max where the fill turns warning, then critical. */
+    thresholds?: {
+        warning: number;
+        critical: number;
+    };
+    /**
+     * A second reading on a thin inner arc (last week, the plan). When `value`
+     * passes `max` the main arc is full and critical, the text says the true
+     * share (124%), and a marker sits at the max.
+     */
+    compare?: {
+        value: number;
+        label: string;
+    };
+}
+export interface BulletProps extends ChartCommonProps {
+    value: number;
+    target: number;
+    max: number;
+    /** Band ends as fractions of max: good up to [0], warning up to [1], serious after. */
+    ranges: [number, number];
+    label: string;
+    /** false when a smaller value is the good one (a failure share). */
+    higherIsBetter?: boolean;
+}
+export interface DonutSlice {
+    id: string;
+    label: string;
+    tone: ChartTone;
+    value: number;
+}
+export interface DonutProps extends ChartCommonProps {
+    slices: readonly DonutSlice[];
+    /** A second set of slices on a thinner inner ring (the previous period), same ids and tones. */
+    compare?: {
+        label: string;
+        slices: readonly DonutSlice[];
+    };
+    centerValue?: string;
+    centerLabel?: string;
+}
+export interface TreemapNode {
+    id: string;
+    label: string;
+    value: number;
+    group: string;
+}
+export interface TreemapProps extends ChartCommonProps {
+    nodes: readonly TreemapNode[];
+    groupTones: Readonly<Record<string, ChartTone>>;
+    unit: string;
+}
+export interface HeatmapGridProps extends ChartCommonProps {
+    rows: readonly string[];
+    cols: readonly string[];
+    /** cells[rowIndex][colIndex]; the sequential blue ramp maps 0..max. */
+    cells: readonly (readonly number[])[];
+    /** Show every nth column label (weeks: 4). */
+    colLabelEvery?: number;
+    unit: string;
+    /** The cell is a button when set: click or Enter fires it. */
+    onCellClick?: (cell: HeatmapCell) => void;
+    /** The cell drawn with a selection ring. */
+    selected?: {
+        row: number;
+        col: number;
+    } | null;
+}
+export interface HeatmapCell {
+    row: number;
+    col: number;
+    value: number;
+}
+export interface GraphNode {
+    id: string;
+    label: string;
+    /** The group names the tone and, in a Sankey, the column. */
+    group: string;
+    /** Node weight (size in a network map). */
+    value?: number;
+}
+export interface GraphLink {
+    source: string;
+    target: string;
+    value: number;
+}
+export interface NetworkGraphProps extends ChartCommonProps {
+    nodes: readonly GraphNode[];
+    links: readonly GraphLink[];
+    groupTones: Readonly<Record<string, ChartTone>>;
+    onNodeClick?: (node: GraphNode) => void;
+}
+export interface SankeyProps extends ChartCommonProps {
+    /** A DAG; the engine lays columns out by group order when it can. */
+    nodes: readonly GraphNode[];
+    links: readonly GraphLink[];
+    groupTones: Readonly<Record<string, ChartTone>>;
+    /** Column order of the groups, left to right. */
+    groupOrder: readonly string[];
+}
+export interface RoseSlice {
+    id: string;
+    label: string;
+    value: number;
+    /** The group names the tone through `groupTones`; `tone` wins when set. */
+    group?: string;
+    tone?: ChartTone;
+}
+/** A Nightingale rose: equal angles, the radius encodes the value, so the biggest slice is the tallest. */
+export interface NightingaleProps extends ChartCommonProps {
+    slices: readonly RoseSlice[];
+    groupTones?: Readonly<Record<string, ChartTone>>;
+    unit: string;
+}
+export interface SunburstNode {
+    id: string;
+    label: string;
+    /** Leaf value; a parent's value is the sum of its children when left out. */
+    value?: number;
+    group?: string;
+    tone?: ChartTone;
+    children?: readonly SunburstNode[];
+}
+/** A layered sunburst: the inner ring is the first level, each outer ring a level deeper. */
+export interface SunburstProps extends ChartCommonProps {
+    nodes: readonly SunburstNode[];
+    groupTones?: Readonly<Record<string, ChartTone>>;
+    unit: string;
+    /** Fires with the ids from the root to the clicked node. */
+    onNodeClick?: (path: string[]) => void;
+}
+export interface RadarAxis {
+    id: string;
+    label: string;
+    /** The pole this axis is pulled toward; axes of one pole are contiguous. */
+    pole: string;
+}
+/** One of the directions the shape can tilt toward: a wedge behind its axes, coloured core to rim. */
+export interface RadarPole {
+    id: string;
+    label: string;
+    /** The colour at the rim of the wedge. */
+    tone: ChartTone;
+    /** The colour at the centre of the wedge. */
+    coreTone: ChartTone;
+    /** A glyph drawn at the wedge's outer edge (an emoji is fine). */
+    icon?: string;
+}
+export interface RadarSeries {
+    id: string;
+    label: string;
+    tone: ChartTone;
+    /** One value per axis, same order as `axes`, on the 0..max scale. */
+    values: readonly number[];
+}
+/** A radar whose axes are grouped into poles, so the shape's bulge reads as a tilt toward one pole. */
+export interface RadarProps extends ChartCommonProps {
+    axes: readonly RadarAxis[];
+    poles: readonly RadarPole[];
+    series: readonly RadarSeries[];
+    /** The outer edge of the scale; 1 is the baseline ring when values are ratios to a baseline. */
+    max?: number;
+    /** A ring drawn at this value with a label (the baseline). */
+    baseline?: {
+        value: number;
+        label: string;
+    };
+    /**
+     * How much history stands behind the baseline: `weeks` of `of`. The ring and
+     * the wedge cores inside it solidify as the share grows; absent means full.
+     */
+    history?: {
+        weeks: number;
+        of: number;
+    };
+}
+export interface ChartPrimitives {
+    id: EngineId;
+    label: string;
+    /** What this engine could not draw natively and how the gap is covered. */
+    notes: readonly string[];
+    BarChart: ComponentType<BarChartProps>;
+    LineChart: ComponentType<LineChartProps>;
+    ScatterChart: ComponentType<ScatterChartProps>;
+    Histogram: ComponentType<HistogramProps>;
+    BoxPlot: ComponentType<BoxPlotProps>;
+    Gauge: ComponentType<GaugeProps>;
+    Bullet: ComponentType<BulletProps>;
+    Donut: ComponentType<DonutProps>;
+    Treemap: ComponentType<TreemapProps>;
+    HeatmapGrid: ComponentType<HeatmapGridProps>;
+    NetworkGraph: ComponentType<NetworkGraphProps>;
+    Sankey: ComponentType<SankeyProps>;
+    Nightingale: ComponentType<NightingaleProps>;
+    Sunburst: ComponentType<SunburstProps>;
+    Radar: ComponentType<RadarProps>;
+}

package/dist/seam/useResolvedTokens.d.ts

@@ -0,0 +1,7 @@
+import { type ResolvedTokens } from './tones.js';
+/**
+ * The tokens as concrete colour strings, keyed by tone and by token name,
+ * re-read when the theme attribute changes on `<html>`. A write that leaves
+ * every colour as it was returns the same object, so a chart is not redrawn.
+ */
+export declare function useResolvedTokens(): ResolvedTokens;

package/dist/theme/index.d.ts

@@ -0,0 +1,3 @@
+/** The theme contract: token names only; the consuming app ships the values. */
+export { DARK_THEME, DELTA_TOKENS, POLE_TOKENS, SEQUENTIAL_TOKENS, SERIES_TOKENS, STATUS_TOKENS, SURFACE_TOKENS, THEME_ATTRIBUTE, THEME_TOKENS, TOKEN_PREFIX, tokenName, tokenNames, tokenVar, } from './tokens.js';
+export type { ThemeToken, TokenName } from './tokens.js';

package/dist/theme/index.js

@@ -0,0 +1,30 @@
+import {
+  DARK_THEME,
+  DELTA_TOKENS,
+  POLE_TOKENS,
+  SEQUENTIAL_TOKENS,
+  SERIES_TOKENS,
+  STATUS_TOKENS,
+  SURFACE_TOKENS,
+  THEME_ATTRIBUTE,
+  THEME_TOKENS,
+  TOKEN_PREFIX,
+  tokenName,
+  tokenNames,
+  tokenVar
+} from "../index-85mb21rn.js";
+export {
+  tokenVar,
+  tokenNames,
+  tokenName,
+  TOKEN_PREFIX,
+  THEME_TOKENS,
+  THEME_ATTRIBUTE,
+  SURFACE_TOKENS,
+  STATUS_TOKENS,
+  SERIES_TOKENS,
+  SEQUENTIAL_TOKENS,
+  POLE_TOKENS,
+  DELTA_TOKENS,
+  DARK_THEME
+};