@silverpoint/core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1018 @@
+/** A row of data. Charts reach its fields through accessors. */
+type Datum = Readonly<Record<string, unknown>>;
+/** Access to a field: key name or pure function. */
+type Accessor<T = number> = string | ((d: Datum, i: number) => T);
+/** Inking mode. `precision` amounts to using NullInker (REQ-021). */
+type InkMode = 'ink' | 'precision';
+/** Seed. A string is converted to an integer stably (REQ-003). */
+type Seed = number | string;
+/** Prepared substrates of the silverpoint ground (REQ-046). */
+type SubstrateName = 'cream' | 'green' | 'blue' | 'ochre';
+/** Active item resolved by the interaction engine (REQ-140). */
+interface ActiveItem {
+    readonly seriesKey: string;
+    readonly index: number;
+    readonly datum: Datum;
+    readonly value: number;
+    /** Coordinates in SVG space, not screen space. */
+    readonly point: Readonly<{
+        x: number;
+        y: number;
+    }>;
+}
+
+/** What a stroke is. Determines whether the Inker may touch it (REQ-022). */
+type StrokeRole = 'encoding' | 'ornament' | 'hatch';
+/** Semantic paint slot; maps to a CSS variable (API Spec §10). */
+type StrokePart = 'ink' | 'ink-secondary' | 'heighten' | 'rule' | 'grid' | 'axis';
+/**
+ * How the stylesheet paints the shape: its outline, its interior with the part colour, its
+ * interior with a hatch tile, or nothing — a toned shape whose edges other strokes draw, so the
+ * Inker hatches it and no outline covers those edges.
+ * @internal
+ */
+type StrokePaint = 'stroke' | 'fill' | 'tile' | 'none';
+/** Tonal level on the ground's ramp; 0 is no fill (Data Model §3.4). */
+type ToneLevel = 0 | 1 | 2 | 3 | 4;
+/** Stroke instruction. It carries no color: color comes from CSS (REQ-042). */
+interface Stroke {
+    /** SVG path data, already rounded to 2 decimals (REQ-002). */
+    readonly d: string;
+    readonly role: StrokeRole;
+    readonly part: StrokePart;
+    /** Relative weight, resolved against the ground's token. */
+    readonly weight?: number;
+    /** @internal Defaults to `'stroke'`. */
+    readonly paint?: StrokePaint;
+    /** @internal Dash pattern, resolved by the stylesheet. */
+    readonly dash?: 'dotted';
+    /** @internal Tonal level a closed shape asks the Inker to hatch. */
+    readonly tone?: ToneLevel;
+    /** @internal Id of the tile in `Geometry.defs` that fills this shape. */
+    readonly tile?: string;
+}
+/** Kind of text a label carries; the stylesheet sets type by it. */
+type LabelKind = 'title' | 'badge' | 'value' | 'unit' | 'footer' | 'tick' | 'empty';
+interface TextLabel {
+    readonly x: number;
+    readonly y: number;
+    readonly text: string;
+    readonly kind: LabelKind;
+    /** Paint slot: `text` for primary labels, `axis` for muted ones. */
+    readonly part: 'text' | 'axis';
+    readonly anchor: 'start' | 'middle' | 'end';
+}
+/** A datum's position, as the interaction engine sees it (REQ-140). */
+interface HitArea {
+    readonly seriesKey: string;
+    readonly index: number;
+    readonly datum: Datum;
+    readonly value: number;
+    readonly x: number;
+    readonly y: number;
+    /** The item's area, when it has one — a bar, a cell, a tile. A pointer inside it wins. */
+    readonly box?: Rect;
+    /**
+     * The item's place in a grid, when the chart is one. When every item has one, the arrow keys
+     * move by column (left, right) and by row (up, down) across the whole grid (REQ-122).
+     */
+    readonly cell?: Readonly<{
+        column: number;
+        row: number;
+    }>;
+}
+/**
+ * A hatch tile shared by every shape of one tonal level (REQ-029).
+ * @internal
+ */
+interface Tile {
+    /** Scoped to the chart instance (REQ-030). */
+    readonly id: string;
+    readonly width: number;
+    readonly height: number;
+    /** Rotation of the tile in degrees. */
+    readonly angle: number;
+    readonly strokes: readonly Stroke[];
+}
+interface Rect {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
+/** Everything a chart needs in order to draw itself. Serializable (REQ-011). */
+interface Geometry {
+    readonly viewBox: Rect;
+    readonly strokes: readonly Stroke[];
+    readonly labels: readonly TextLabel[];
+    readonly hitAreas: readonly HitArea[];
+    /** @internal Hatch tiles referenced by strokes painted with `'tile'`. */
+    readonly defs: readonly Tile[];
+    /** @internal The drawing area; the interaction engine ignores anything outside it. */
+    readonly plot: Rect;
+}
+
+/** One step of a ground's tonal ramp (Data Model §3.4). */
+interface ToneSpec {
+    readonly style: 'hachure' | 'cross-hatch';
+    readonly gap: number;
+    /** Hatch angle in degrees; cross-hatch adds the perpendicular. */
+    readonly angle: number;
+}
+type TonalRamp = Readonly<Record<Exclude<ToneLevel, 0>, ToneSpec>>;
+interface InkOptions {
+    readonly seed: number;
+    readonly roughness: number;
+    readonly bowing: number;
+    readonly hatchAngle: number;
+    readonly hatchGap: number;
+    readonly fillWeight: number;
+    /** Upper bound of nodes the Inker must not exceed. */
+    readonly nodeBudget: number;
+    /** @internal `tile` shares one hatch tile per tonal level (REQ-029). */
+    readonly hatchFill?: 'tile' | 'per-shape';
+    /** @internal The ground's tonal ramp. */
+    readonly tonalRamp?: TonalRamp;
+    /** @internal Prefix that scopes generated ids to the chart instance (REQ-030). */
+    readonly scope?: string;
+}
+interface Inker {
+    readonly name: string;
+    /** Receives exact geometry and returns the inked geometry. */
+    ink(geometry: Geometry, options: InkOptions): Geometry;
+}
+
+/** Name of a registered ground. */
+type GroundName = 'silverpoint' | (string & {});
+/** Declarative token set of a style ground (API Spec §6, Art. 7). */
+interface Ground {
+    readonly name: string;
+    /** How it builds tonal value. `wash` is the anticipated exception to Art. 6. */
+    readonly tonalMechanism: 'hatch' | 'weight' | 'wash';
+    /** Name of the registered Inker that inks it. */
+    readonly inker: string;
+    readonly substrates: Readonly<Record<string, string>>;
+    readonly ink: Readonly<{
+        primary: string;
+        secondary: string;
+        heighten: string;
+        rule: string;
+        grid: string;
+        text: string;
+        textMuted: string;
+    }>;
+    readonly inkOptions: Omit<InkOptions, 'seed' | 'nodeBudget' | 'hatchFill' | 'tonalRamp' | 'scope'>;
+    /** Hatch density bound, to stay within the node budget. */
+    readonly maxHatchDensity: number;
+    /** Tonal levels 1-4 (Data Model §3.4). */
+    readonly tonalRamp: TonalRamp;
+    readonly typography: Readonly<{
+        display: string;
+        scale: number;
+    }>;
+    /** What to draw when there is no data (REQ-007). */
+    readonly emptyState: Readonly<{
+        text: string;
+        rule: boolean;
+    }>;
+    /** Expansion of degenerate domains (REQ-010). */
+    readonly domainPadding: number;
+}
+/** Name of a registered ground, or a complete ground. */
+type GroundRef = GroundName | Ground;
+
+/** Props present in every chart, identical in React and Angular (REQ-094). */
+interface CommonChartProps {
+    /** Rows to draw. If omitted, the demo dataset is rendered (REQ-093). */
+    data?: readonly Datum[];
+    /** Style ground. Defaults to the app provider's, or `silverpoint`. */
+    ground?: GroundRef;
+    /** Prepared substrate within the ground (REQ-046). */
+    substrate?: SubstrateName;
+    /** `ink` by default; `precision` disables inking (REQ-021). */
+    mode?: InkMode;
+    /** Seed. If omitted, it is derived from `id` stably (REQ-003). */
+    seed?: Seed;
+    /** Stable identifier. If omitted, it is generated deterministically. */
+    id?: string;
+    /** Height of the drawing area in px. Width is the container's unless pinned. */
+    height?: number;
+    width?: number;
+    /** `card` draws the full frame; `bare` only the drawing area (REQ-095). */
+    chrome?: 'card' | 'bare';
+    /** How areas are filled (REQ-029). */
+    hatchFill?: 'tile' | 'per-shape';
+    title?: string;
+    badge?: string;
+    value?: string | number;
+    unit?: string;
+    footerLeft?: string;
+    footerRight?: string;
+    /** Accessible name. If omitted, it is derived from `title` (REQ-120). */
+    label?: string;
+    /** Long description for screen readers (REQ-120). */
+    description?: string;
+    /** Tabular alternative; `hidden` leaves it for assistive technology only (REQ-121). */
+    dataTable?: 'visible' | 'hidden' | 'none';
+    locale?: string;
+    numberFormat?: Intl.NumberFormatOptions;
+    className?: string;
+}
+type LineCurve = 'monotone' | 'linear' | 'natural' | 'step';
+/** `LineChart` (REQ-060): spline with an optional dotted baseline series. */
+interface LineChartProps extends CommonChartProps {
+    xKey?: Accessor<string | number>;
+    valueKey?: Accessor<number | null | undefined>;
+    secondaryKey?: Accessor<number | null | undefined>;
+    curve?: LineCurve;
+    /** `all` draws the secondary series when there is one; `primary` omits it. */
+    series?: 'all' | 'primary';
+    /** Whether a gap left by a missing value is bridged (REQ-008). */
+    connectNulls?: boolean;
+}
+/** Configuration an application sets once for every chart (API Spec §8). */
+interface ProviderConfig {
+    ground?: GroundRef;
+    substrate?: SubstrateName;
+    mode?: InkMode;
+    locale?: string;
+}
+/** `BulletChart` (REQ-069): one bar per target, with a marker at the target. Values in 0-100. */
+interface BulletChartProps extends CommonChartProps {
+    titleKey?: Accessor<string>;
+    actualKey?: Accessor<number | null | undefined>;
+    targetKey?: Accessor<number | null | undefined>;
+}
+/** `PyramidChart` (REQ-070): stacked tiers whose width encodes the value (0-100). */
+interface PyramidChartProps extends CommonChartProps {
+    labelKey?: Accessor<string>;
+    widthKey?: Accessor<number | null | undefined>;
+    toneKey?: Accessor<number | null | undefined>;
+}
+/** `HeatmapChart` (REQ-084): labelled rows of values, normalised against `scaleMax`. */
+interface HeatmapChartProps extends CommonChartProps {
+    labelKey?: Accessor<string>;
+    valuesKey?: Accessor<readonly (number | null)[] | null | undefined>;
+    /** Value that maps to the darkest tone; 100 by default. */
+    scaleMax?: number;
+    /** Names of the columns, in order; missing ones fall back to `#k` (delta-006). */
+    columnLabels?: readonly string[];
+}
+/** `TreemapChart` (REQ-085): tiles of `cols × rows` cells placed in a `columns × rows` grid. */
+interface TreemapChartProps extends CommonChartProps {
+    labelKey?: Accessor<string>;
+    shareKey?: Accessor<number | null | undefined>;
+    columns?: number;
+    rows?: number;
+}
+/** `SankeyChart` (REQ-086): flow bands between layered nodes. */
+interface SankeyChartProps extends CommonChartProps {
+    sourceKey?: Accessor<string>;
+    targetKey?: Accessor<string>;
+    valueKey?: Accessor<number | null | undefined>;
+}
+/** `ActivityGrid` (REQ-087): one cell per day, a column per week. */
+interface ActivityGridProps extends CommonChartProps {
+    dateKey?: Accessor<string>;
+    countKey?: Accessor<number | null | undefined>;
+    levelKey?: Accessor<number | null | undefined>;
+    /** Weeks shown, the most recent last; 26 by default. */
+    weeks?: number;
+}
+/** `StepChart` (REQ-061): a series drawn as steps. */
+interface StepChartProps extends CommonChartProps {
+    xKey?: Accessor<string | number>;
+    valueKey?: Accessor<number | null | undefined>;
+    /** Where the step sits between two points; `after` by default. */
+    step?: 'after' | 'before' | 'middle';
+}
+/** `SparklineRows` (REQ-062): one row per series — name, sparkline, readout (delta-008). */
+interface SparklineRowsProps extends CommonChartProps {
+    /** Rows shown, from the first; all by default. */
+    rows?: number;
+    nameKey?: Accessor<string>;
+    /** The printed readout; the last value of the series by default. */
+    readoutKey?: Accessor<string | number | null | undefined>;
+    /** The row's points: an array. */
+    seriesKey?: Accessor<readonly unknown[] | null | undefined>;
+    /** The value of one point; the point itself when it is a number, else its `value`. */
+    pointKey?: Accessor<number | null | undefined>;
+}
+/** `KpiCard` (REQ-063): a metric, its delta, and an area sparkline of the series. */
+interface KpiCardProps extends CommonChartProps {
+    valueKey?: Accessor<number | null | undefined>;
+    /** The metric's name, printed under the figure. */
+    metric?: string;
+    /** Signed change, printed with its sign and a direction mark. */
+    delta?: number;
+    /** Direction of the mark; from the sign of `delta` by default. */
+    deltaTone?: 'up' | 'down' | 'flat';
+}
+/** `BarChart` (REQ-064): pill bars, as columns or rows, with an optional second series. */
+interface BarChartProps extends CommonChartProps {
+    xKey?: Accessor<string | number>;
+    valueKey?: Accessor<number | null | undefined>;
+    secondaryKey?: Accessor<number | null | undefined>;
+    orientation?: 'columns' | 'rows';
+}
+/** `StackedBarChart` (REQ-065): one stacked segment per key. */
+interface StackedBarChartProps extends CommonChartProps {
+    xKey?: Accessor<string | number>;
+    keys?: readonly string[];
+    /** Display names of the keys, in order; the keys themselves by default. */
+    names?: readonly string[];
+}
+/** `ComposedChart` (REQ-066): columns and a spline on one value scale. */
+interface ComposedChartProps extends CommonChartProps {
+    xKey?: Accessor<string | number>;
+    barKey?: Accessor<number | null | undefined>;
+    lineKey?: Accessor<number | null | undefined>;
+    showLine?: boolean;
+}
+/** `WaterfallChart` (REQ-067): totals from zero and floating deltas from the running total. */
+interface WaterfallChartProps extends CommonChartProps {
+    stepKey?: Accessor<string>;
+    /** An absolute total: the bar starts at zero and resets the running total. */
+    baseKey?: Accessor<number | null | undefined>;
+    /** A change from the running total. */
+    deltaKey?: Accessor<number | null | undefined>;
+}
+/** `FunnelChart` (REQ-068): horizontal, centred stages. */
+interface FunnelChartProps extends CommonChartProps {
+    stageKey?: Accessor<string>;
+    valueKey?: Accessor<number | null | undefined>;
+}
+/** `CandlestickChart` (REQ-071): OHLC bodies and wicks (Data Model §2.6). */
+interface CandlestickChartProps extends CommonChartProps {
+    timeKey?: Accessor<string | number>;
+    openKey?: Accessor<number | null | undefined>;
+    highKey?: Accessor<number | null | undefined>;
+    lowKey?: Accessor<number | null | undefined>;
+    closeKey?: Accessor<number | null | undefined>;
+    /** Price bounds of the scale; derived from the data when omitted (REQ-097). */
+    bounds?: readonly [number, number];
+}
+/** `AreaChart` (REQ-072): a curved, toned area under its line. */
+interface AreaChartProps extends CommonChartProps {
+    xKey?: Accessor<string | number>;
+    valueKey?: Accessor<number | null | undefined>;
+    curve?: LineCurve;
+}
+/** `RangeBandChart` (REQ-073): the band between a low and a high series. */
+interface RangeBandChartProps extends CommonChartProps {
+    xKey?: Accessor<string | number>;
+    lowKey?: Accessor<number | null | undefined>;
+    highKey?: Accessor<number | null | undefined>;
+}
+/** `StreamChart` (REQ-074): two waves, overlaid or stacked. */
+interface StreamChartProps extends CommonChartProps {
+    xKey?: Accessor<string | number>;
+    keys?: readonly string[];
+    stacked?: boolean;
+}
+/** `ScatterChart` (REQ-082): points on two linear scales, optionally sized. */
+interface ScatterChartProps extends CommonChartProps {
+    xKey?: Accessor<number | null | undefined>;
+    yKey?: Accessor<number | null | undefined>;
+    sizeKey?: Accessor<number | null | undefined>;
+    /** Marker area in px², smallest to largest; `[60, 240]` by default. */
+    sizeRange?: readonly [number, number];
+}
+/** `BubbleChart` (REQ-083): circles whose area encodes `sizeKey`. */
+interface BubbleChartProps extends CommonChartProps {
+    xKey?: Accessor<number | null | undefined>;
+    yKey?: Accessor<number | null | undefined>;
+    sizeKey?: Accessor<number | null | undefined>;
+    /** Circle area in px², smallest to largest; `[100, 500]` by default. */
+    sizeRange?: readonly [number, number];
+}
+/** `DonutChart` (REQ-075): sectors ∝ value around a central readout (Data Model §2.2). */
+interface DonutChartProps extends CommonChartProps {
+    nameKey?: Accessor<string | number>;
+    valueKey?: Accessor<number | null | undefined>;
+    /** Printed in the centre; the total by default. */
+    centerValue?: string | number;
+    /** A line under the centre value. */
+    centerLabel?: string;
+    /** Names every sector with its share beside the ring; `true` by default. */
+    legend?: boolean;
+}
+/** `RadarChart` (REQ-076): one spoke per subject, a closed polygon of values (Data Model §2.2). */
+interface RadarChartProps extends CommonChartProps {
+    subjectKey?: Accessor<string | number>;
+    valueKey?: Accessor<number | null | undefined>;
+    /** The value range along a spoke; `[0, the largest value]`, niced, by default. */
+    domain?: readonly [number, number];
+}
+/** `PolarBarChart` (REQ-077): 360° bars out from a hole, length ∝ value (Data Model §2.2). */
+interface PolarBarChartProps extends CommonChartProps {
+    nameKey?: Accessor<string | number>;
+    valueKey?: Accessor<number | null | undefined>;
+}
+/** `CoxcombChart` (REQ-088): equal angles, sector **area** ∝ value (Data Model §2.2). */
+interface CoxcombChartProps extends CommonChartProps {
+    nameKey?: Accessor<string | number>;
+    valueKey?: Accessor<number | null | undefined>;
+    /** Where the first sector starts, in degrees clockwise from 12 o'clock; 0 by default. */
+    startAngle?: number;
+}
+/** `RadialArcGroup` (REQ-078): concentric 180° tracks, sweep ∝ value / the largest (Data Model §2.2). */
+interface RadialArcGroupProps extends CommonChartProps {
+    nameKey?: Accessor<string | number>;
+    valueKey?: Accessor<number | null | undefined>;
+}
+/** `RadialRings` (REQ-079): concentric progress rings, sweep ∝ value in 0-100 (Data Model §2.2). */
+interface RadialRingsProps extends CommonChartProps {
+    nameKey?: Accessor<string | number>;
+    valueKey?: Accessor<number | null | undefined>;
+}
+/** `GaugeArc` (REQ-080): a 240° arc swept to a percent (Data Model §2.3). */
+interface GaugeArcProps extends CommonChartProps {
+    /** 0 to 100; saturated at the ends outside it. */
+    percent?: number;
+    /** Names the measure under the readout. */
+    caption?: string;
+    /** Printed in place of the percent. */
+    readout?: string;
+}
+/** `MeterChart` (REQ-081): a semicircular meter with a needle at a percent (Data Model §2.3). */
+interface MeterChartProps extends CommonChartProps {
+    /** 0 to 100; saturated at the ends outside it. */
+    percent?: number;
+    /** Names the measure under the readout. */
+    caption?: string;
+    /** Printed in place of the percent. */
+    readout?: string;
+}
+/** `WindRose` (REQ-089): observations of (bearing, speed) binned by compass sector and speed. */
+interface WindRoseProps extends CommonChartProps {
+    /** Where the wind blows from, in degrees clockwise from north. */
+    bearingKey?: Accessor<number | null | undefined>;
+    /** The wind speed; 0 is a calm, which has no direction. */
+    valueKey?: Accessor<number | null | undefined>;
+    /** Compass sectors: 4, 8, 16 or 32; 16 by default. */
+    sectors?: number;
+    /** Ascending speed thresholds that split each sector; `[5, 10, 15, 20]` by default. */
+    bins?: readonly number[];
+}
+/** `ChordRing` (REQ-091): directed flows between categories around a circle (Data Model §2.7). */
+interface ChordRingProps extends CommonChartProps {
+    sourceKey?: Accessor<string | number>;
+    targetKey?: Accessor<string | number>;
+    valueKey?: Accessor<number | null | undefined>;
+    /** Categories drawn; past it the smallest merge into "Other" (`SP010`). 12 by default. */
+    maxCategories?: number;
+}
+/** `OrbitChart` (REQ-092): nested elliptical orbits with markers along them (Data Model §2.10, delta-009). */
+interface OrbitChartProps extends CommonChartProps {
+    /** Orbits shown, from the inside out; all by default. */
+    orbits?: number;
+    /** A row's markers; `'markers'` by default. */
+    markerKey?: Accessor<readonly unknown[] | null | undefined>;
+    /** A marker's period, 0-1 over the cycle; `'period'` by default. */
+    periodKey?: Accessor<number | null | undefined>;
+}
+/** `VolvelleChart` (REQ-090): concentric categorical rings read against one index (delta-010). */
+interface VolvelleChartProps extends CommonChartProps {
+    /** Rings shown, from the inside out; all by default. */
+    rings?: number;
+    /** The ring whose segment is brought under the index, 0-based; 0 by default. */
+    indexRing?: number;
+    /** The segment of `indexRing` under the index; its first segment by default. */
+    indexValue?: string;
+}
+
+/** Tabular alternative of a chart's data, already formatted (REQ-121). */
+interface DataTable {
+    readonly caption: string;
+    readonly columns: readonly string[];
+    readonly rows: readonly (readonly string[])[];
+}
+/** What a recipe needs beyond the props: the resolved environment. */
+interface RecipeContext {
+    /** Resolved instance id. */
+    readonly id: string;
+    /** Resolved container width in px; `undefined` while it has not been measured. */
+    readonly width: number | undefined;
+    readonly locale: string;
+    readonly emptyState: Ground['emptyState'];
+    readonly domainPadding: number;
+}
+/**
+ * Everything an adapter renders: the geometry plus the accessible layer. Adapters translate
+ * it into nodes and compute nothing (Art. 2).
+ */
+interface ChartModel {
+    readonly chart: string;
+    readonly id: string;
+    /** `deferred` while the container has no usable size (REQ-009). */
+    readonly status: 'ready' | 'deferred';
+    readonly geometry: Geometry;
+    readonly chrome: 'card' | 'bare';
+    /** Accessible name (REQ-120). */
+    readonly name: string;
+    /** Description summarising the series (REQ-120). */
+    readonly description: string;
+    readonly ids: Readonly<{
+        title: string;
+        desc: string;
+        table: string;
+    }>;
+    readonly table: DataTable;
+    readonly dataTable: 'visible' | 'hidden' | 'none';
+}
+/** A chart: its display name and the pure function from props to model. */
+interface ChartRecipe<P extends CommonChartProps> {
+    readonly name: string;
+    build(props: P, context: RecipeContext): ChartModel;
+}
+/** Imperative handle every adapter exposes, deliberately minimal (API Spec §8.1). */
+interface ChartHandle {
+    getGeometry(): Geometry;
+    toSVGString(): string;
+}
+
+/** Rounds to 2 decimals, the precision of every emitted coordinate (REQ-002). */
+declare function round2(value: number): number;
+/** Rounds every number inside SVG path data to 2 decimals. */
+declare function roundPathData(d: string): string;
+/** Rounds all coordinates of a geometry to 2 decimals, returning a new object (REQ-002). */
+declare function roundGeometry(geometry: Geometry): Geometry;
+
+/** Serialises a geometry to JSON. Geometry holds no functions and no DOM nodes (REQ-011). */
+declare function serializeGeometry(geometry: Geometry): string;
+/** Inverse of `serializeGeometry`. */
+declare function parseGeometry(json: string): Geometry;
+/** Bytes of path data a geometry carries, tiles included (NFR §7). */
+declare function pathBytes(geometry: Geometry): number;
+/** Path data budget per chart (API Spec §12). */
+declare const PATH_BYTE_BUDGET = 40000;
+
+/**
+ * 32-bit FNV-1a over the UTF-8 bytes of the input (DD-006).
+ *
+ * Frozen by SemVer: changing it changes every derived seed, and with it every golden image.
+ */
+declare function fnv1a32(input: string): number;
+/** Derives the seed of a chart from its identifier (REQ-003). */
+declare function deriveSeed(id: string): number;
+/** `seed ?? derive(id)`, with string seeds hashed and numbers taken as unsigned 32-bit. */
+declare function resolveSeed(seed: Seed | undefined, id: string): number;
+
+/**
+ * A seeded 32-bit PRNG (mulberry32), for generated demo data (Data Model §4). Owned here rather
+ * than imported, so its sequence is frozen by SemVer like the seed derivation (DD-006): changing
+ * it changes demo output, which is never a patch.
+ */
+declare function createPrng(seed: number): () => number;
+
+/** Days since the epoch of an ISO `YYYY-MM-DD` date; `NaN` when it is not one. */
+declare function parseIsoDate(iso: string): number;
+/** The ISO `YYYY-MM-DD` form of a day number. */
+declare function isoDate(day: number): string;
+declare function addDays(day: number, days: number): number;
+/** Day of the week in UTC, 0 = Sunday. */
+declare function weekday(day: number): number;
+
+/**
+ * Holds the heightening rules on a geometry:
+ * - a single heightened element per chart (REQ-024); a second one throws SP005 in development
+ *   and is dropped in production (REQ-025);
+ * - every heightened element carries an outline in the main ink (REQ-031), which is added
+ *   when the recipe did not draw it.
+ */
+declare function enforceHeightening(geometry: Geometry, chart: string): Geometry;
+
+/**
+ * The SVG a chart renders, as flat element descriptors with every attribute value already a
+ * string. Each adapter's template writes these fields to the same attribute names, one to one,
+ * and computes nothing (Art. 2); `svgString` writes them too, and its output is the canonical
+ * render every adapter is compared against (Art. 3, DD-004).
+ *
+ * Colour never appears here: the stylesheet paints by `part` (REQ-042).
+ */
+interface SvgView {
+    readonly svg: Readonly<{
+        viewBox: string;
+        width: string;
+        height: string;
+        /** `class` attribute. */
+        class: string;
+        /** `data-substrate` attribute. */
+        substrate: string;
+        /** `data-mode` attribute. */
+        mode: InkMode;
+        role: 'img';
+        /** `aria-labelledby` attribute. */
+        labelledby: string;
+    }>;
+    readonly title: Readonly<{
+        id: string;
+        text: string;
+    }>;
+    readonly desc: Readonly<{
+        id: string;
+        text: string;
+    }>;
+    /** `<pattern>` elements inside `<defs>`; `<defs>` is omitted when there are none. */
+    readonly patterns: readonly PatternView[];
+    readonly paths: readonly PathView[];
+    readonly texts: readonly TextView[];
+}
+interface PatternView {
+    readonly id: string;
+    readonly width: string;
+    readonly height: string;
+    /** `patternTransform` attribute. */
+    readonly transform: string;
+    readonly paths: readonly PathView[];
+}
+interface PathView {
+    readonly d: string;
+    /** `part` attribute: `sp-<part>`. */
+    readonly part: string;
+    /** `data-role` attribute. */
+    readonly role: Stroke['role'];
+    /** `data-paint` attribute. */
+    readonly paint: StrokePaint;
+    /** `data-dash` attribute, omitted when `null`. */
+    readonly dash: string | null;
+    /** `fill` attribute — only ever a `url(#tile)` reference, omitted when `null`. */
+    readonly fill: string | null;
+}
+interface TextView {
+    readonly x: string;
+    readonly y: string;
+    /** `part` attribute: `sp-text` or `sp-axis`. */
+    readonly part: string;
+    /** `data-kind` attribute. */
+    readonly kind: TextLabel['kind'];
+    /** `text-anchor` attribute. */
+    readonly anchor: TextLabel['anchor'];
+    readonly text: string;
+}
+interface ViewStyle {
+    readonly ground: string;
+    readonly substrate: string;
+    readonly mode: InkMode;
+}
+/** Builds the element descriptors of a chart model (API Spec §10). */
+declare function toSvgView(model: ChartModel, style: ViewStyle): SvgView;
+/**
+ * Serialises a view to SVG markup. This is the canonical render stored with each fixture;
+ * user text is always escaped, never interpolated as markup (TD §6).
+ */
+declare function svgString(view: SvgView): string;
+
+/** Stable diagnostic codes, part of the public surface (API Spec §11). */
+type SpCode = 'SP001' | 'SP002' | 'SP003' | 'SP004' | 'SP005' | 'SP006' | 'SP007' | 'SP008' | 'SP009' | 'SP010' | 'SP011' | 'SP012' | 'SP013';
+interface Detail {
+    /** The property involved. */
+    readonly property: string;
+    /** Specifics of this occurrence, appended to what happened. */
+    readonly message?: string;
+}
+/** Thrown by diagnostics of `error` severity. */
+declare class SilverpointError extends Error {
+    readonly code: SpCode;
+    constructor(code: SpCode, message: string);
+}
+/** Receives every warning; replaceable so tests and tools can observe diagnostics. */
+type DiagnosticSink = (code: SpCode, message: string) => void;
+/**
+ * Replaces the warning sink and forgets already reported warnings. Returns a function that
+ * restores the console sink.
+ * @internal
+ */
+declare function __setDiagnosticSink(next: DiagnosticSink | null): () => void;
+/**
+ * The single diagnostic channel (TD §5.4). `error` codes always throw; `warn` codes reach
+ * the sink only outside production and are stripped from production bundles.
+ */
+declare function diagnose(code: SpCode, chart: string, detail: Detail): void;
+
+/** The subset of `FontFaceSet` the check needs; injected so the core stays DOM-free. */
+interface FontFaceSetLike {
+    load(font: string): Promise<readonly unknown[]>;
+    check(font: string): boolean;
+}
+/** Font shorthand used to probe the display face. */
+declare const DISPLAY_FACE_PROBE = "16px \"EB Garamond\"";
+/**
+ * Checks that the display typeface loaded. On failure it reports SP013 and resolves `false`;
+ * it never throws and never blocks the render (REQ-032).
+ */
+declare function checkTypeface(fonts: FontFaceSetLike, chart: string, face?: string): Promise<boolean>;
+
+/**
+ * `extent`, `min` and `max` are owned here instead of imported from `d3-array`, which is
+ * not in the allowlist (TD §5.3).
+ */
+declare function min(values: readonly number[]): number | undefined;
+declare function max(values: readonly number[]): number | undefined;
+declare function extent(values: readonly number[]): [number, number] | undefined;
+
+interface ScaleSite {
+    /** Chart name, for diagnostics. */
+    readonly chart: string;
+    /** Property the domain comes from, for diagnostics. */
+    readonly property: string;
+}
+/**
+ * Expands a zero-length domain by the ground's `domainPadding` instead of dividing by zero
+ * (REQ-010). A constant `v` becomes `[v - |v|·p, v + |v|·p]`, or `[-p, p]` around zero — `[0, 2p]`
+ * on a zero-based axis, which never shows a value below zero that no datum has.
+ */
+declare function expandDomain(domain: readonly [number, number], padding: number, site: ScaleSite, 
+/** A zero-based axis (bars, areas): a flat zero domain grows upward only, never below zero. */
+fromZero?: boolean): [number, number];
+interface LinearScale {
+    (value: number): number;
+    readonly domain: readonly [number, number];
+    ticks(count: number): number[];
+}
+/** Linear scale over `d3-scale`, with degenerate-domain expansion. */
+declare function linearScale(domain: readonly [number, number], range: readonly [number, number], options: ScaleSite & {
+    readonly padding: number;
+    readonly nice?: boolean;
+    readonly fromZero?: boolean;
+}): LinearScale;
+interface BandScale {
+    /** Start of the band, or `undefined` for a value outside the domain. */
+    (value: string): number | undefined;
+    readonly bandwidth: number;
+    /** Centre of the band. */
+    center(value: string): number | undefined;
+}
+/** Band scale over `d3-scale`. */
+declare function bandScale(domain: readonly string[], range: readonly [number, number], options?: {
+    readonly paddingInner?: number;
+    readonly paddingOuter?: number;
+}): BandScale;
+
+/** Returns the geometry untouched and uncopied. `precision` mode is exactly this (REQ-021). */
+declare const NullInker: Inker;
+
+/** Registers an inker under its `name`, replacing any previous one with that name. */
+declare function registerInker(inker: Inker): void;
+/**
+ * Resolves an inker by name among the registered ones and `builtins`. An unknown name falls
+ * back to `NullInker` and emits SP006; the render continues (REQ-026).
+ */
+declare function resolveInker(name: string, chart: string, builtins?: readonly Inker[]): Inker;
+
+interface ResolvedConfig {
+    readonly ground: GroundRef;
+    readonly substrate: SubstrateName;
+    readonly mode: InkMode;
+    readonly chrome: 'card' | 'bare';
+    readonly hatchFill: 'tile' | 'per-shape';
+    readonly height: number;
+    readonly dataTable: 'visible' | 'hidden' | 'none';
+    readonly locale: string;
+}
+/** Default values, part of the contract (API Spec §5.1). */
+declare const DEFAULTS: Readonly<{
+    readonly ground: "silverpoint";
+    readonly substrate: "cream";
+    readonly mode: "ink";
+    readonly chrome: "card";
+    readonly hatchFill: "tile";
+    readonly height: 160;
+    readonly dataTable: "hidden";
+    readonly locale: "en";
+}>;
+/**
+ * Resolves `ground`, `substrate` and `mode` with the precedence of API Spec §5.1: chart prop,
+ * then provider, then library default — except that a media query forcing precision wins
+ * over everything, because it is an accessibility requirement (REQ-123).
+ */
+declare function resolveConfig(props: CommonChartProps, provider?: ProviderConfig, environment?: {
+    readonly forcedPrecision?: boolean;
+    readonly locale?: string;
+}): ResolvedConfig;
+/** Media query under which the environment forces `precision` mode (REQ-123). */
+declare const FORCED_PRECISION_QUERY = "(prefers-contrast: more), (forced-colors: active)";
+/**
+ * Builds a deterministic instance id from the chart name and a token the adapter owns, such
+ * as React's `useId()` or Angular's creation order. The result is safe inside `id` and `url()`.
+ */
+declare function instanceId(chart: string, token: string | number): string;
+
+/** `LineChart` recipe (REQ-060): props plus scales produce exact geometry. */
+declare const lineChart: ChartRecipe<LineChartProps>;
+
+/**
+ * Demo dataset of `LineChart` (REQ-093). Frozen, and part of the stable surface: changing it
+ * alters the SVG of anyone who renders without data, so it is never a patch (Data Model §4).
+ */
+declare const LINE_CHART_DEMO: readonly Datum[];
+declare const LINE_CHART_DEMO_KEYS: Readonly<{
+    readonly xKey: "hour";
+    readonly valueKey: "hits";
+    readonly secondaryKey: "baseline";
+}>;
+
+/** SVG path of a circle, drawn as two arcs so it survives inking as a closed path. */
+declare function circlePath(cx: number, cy: number, r: number): string;
+
+type PointerKind = 'mouse' | 'pen' | 'touch';
+/** Minimum touch target, in px (REQ-144). */
+declare const MIN_TOUCH_TARGET = 24;
+/**
+ * Resolves the active item as a pure function of a pointer position, in SVG space, and the
+ * geometry — no DOM involved (REQ-140).
+ *
+ * A pointer inside an item's box resolves to that item. Otherwise a mouse or pen resolves to the
+ * item nearest along x, then along y. Touch resolves by
+ * proximity and only within a target at least 24 px wide (REQ-144). A point outside the
+ * drawing area resolves to `null`.
+ */
+declare function resolveActive(geometry: Geometry, pointer: Readonly<{
+    x: number;
+    y: number;
+}>, kind?: PointerKind): ActiveItem | null;
+/**
+ * Converts a client-space pointer position into SVG space, given the rendered bounding box of
+ * the `<svg>` element. Adapters pass numbers; the arithmetic stays here (Art. 2).
+ */
+declare function toSvgPoint(client: Readonly<{
+    x: number;
+    y: number;
+}>, box: Readonly<{
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}>, viewBox: Rect): {
+    x: number;
+    y: number;
+};
+/** Keys that move the active item (REQ-122). */
+declare const NAVIGATION_KEYS: readonly string[];
+/**
+ * Keyboard traversal of the data points, as a pure function (REQ-122). Right and down move to
+ * the next point of the series, left and up to the previous one, Home and End to its ends,
+ * Escape clears. On a grid — every item carries a `cell` — the arrows move by column and row
+ * instead. Returns `undefined` for a key that is not a navigation key.
+ */
+declare function stepActive(geometry: Geometry, current: ActiveItem | null, key: string): ActiveItem | null | undefined;
+/** Readout of an active item, positioned as percentages of the viewBox (REQ-141). */
+interface Readout {
+    readonly heading: string;
+    readonly text: string;
+    readonly left: string;
+    readonly top: string;
+    /** Sentence announced to assistive technology (REQ-122). */
+    readonly announcement: string;
+    /** Marker drawn over the active point. */
+    readonly marker: Stroke;
+}
+/**
+ * Builds the readout of an active item from the chart's own tabular alternative, so the
+ * readout, the table and the announcement always say the same.
+ */
+declare function readout(model: {
+    readonly geometry: Geometry;
+    readonly table: {
+        readonly columns: readonly string[];
+        readonly rows: readonly (readonly string[])[];
+    };
+}, active: ActiveItem): Readout;
+
+type Point = Readonly<{
+    x: number;
+    y: number;
+}>;
+type Box = Readonly<{
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}>;
+/** A DOM event, reduced to the numbers the interaction engine needs. */
+type InteractionEvent = {
+    readonly type: 'pointer' | 'click';
+    readonly client: Point;
+    readonly box: Box;
+    readonly kind: PointerKind;
+} | {
+    readonly type: 'leave' | 'focus' | 'blur';
+} | {
+    readonly type: 'key';
+    readonly key: string;
+};
+interface InteractionResult {
+    readonly active: ActiveItem | null;
+    /** The active item differs from the current one: emit `activeChange` (REQ-141, REQ-143). */
+    readonly changed: boolean;
+    /** An item was chosen: emit `select` (API Spec §9). */
+    readonly selected?: ActiveItem;
+    /** The event was consumed; a key event should not scroll the page. */
+    readonly handled: boolean;
+}
+/** Same item: same series and index. */
+declare function sameActive(a: ActiveItem | null, b: ActiveItem | null): boolean;
+/**
+ * The whole interaction of a chart as one pure function (REQ-140): current item plus event gives
+ * the next item. Adapters wire DOM events to it and keep the result; they decide nothing.
+ */
+declare function reduceInteraction(geometry: Geometry, current: ActiveItem | null, event: InteractionEvent): InteractionResult;
+
+/** `BulletChart` recipe (REQ-069): a bar to the actual value and a marker at the target, on 0-100. */
+declare const bulletChart: ChartRecipe<BulletChartProps>;
+
+/** `PyramidChart` recipe (REQ-070): stacked, centred tiers whose width encodes the value. */
+declare const pyramidChart: ChartRecipe<PyramidChartProps>;
+
+/** `HeatmapChart` recipe (REQ-084): labelled rows of cells, toned by value and printed. */
+declare const heatmapChart: ChartRecipe<HeatmapChartProps>;
+
+/** `TreemapChart` recipe (REQ-085): tiles placed first-fit in a declared grid, each labelled with its share. */
+declare const treemapChart: ChartRecipe<TreemapChartProps>;
+
+/** `SankeyChart` recipe (REQ-086): flow bands between nodes layered by longest path. */
+declare const sankeyChart: ChartRecipe<SankeyChartProps>;
+
+/** `ActivityGrid` recipe (REQ-087): one cell per day, a column per week, sized and toned by level. */
+declare const activityGrid: ChartRecipe<ActivityGridProps>;
+
+/** `StepChart` recipe (REQ-061): a series drawn as exact steps. */
+declare const stepChart: ChartRecipe<StepChartProps>;
+
+/** `SparklineRows` recipe (REQ-062): one row per series — name, sparkline, printed readout. */
+declare const sparklineRows: ChartRecipe<SparklineRowsProps>;
+
+/** `KpiCard` recipe (REQ-063): the figure, its signed delta with a direction mark, and an area sparkline. */
+declare const kpiCard: ChartRecipe<KpiCardProps>;
+
+/** `BarChart` recipe (REQ-064): pill bars, columns or rows, with an optional second series. */
+declare const barChart: ChartRecipe<BarChartProps>;
+
+/** `StackedBarChart` recipe (REQ-065): one segment per key, stacked from zero, named in a legend. */
+declare const stackedBarChart: ChartRecipe<StackedBarChartProps>;
+
+/** `ComposedChart` recipe (REQ-066): columns and a spline on one value scale. */
+declare const composedChart: ChartRecipe<ComposedChartProps>;
+
+/** `WaterfallChart` recipe (REQ-067): totals from zero and signed deltas floating on the running total. */
+declare const waterfallChart: ChartRecipe<WaterfallChartProps>;
+
+/** `FunnelChart` recipe (REQ-068): centred stages, width ∝ value, value and share printed. */
+declare const funnelChart: ChartRecipe<FunnelChartProps>;
+
+/** `DonutChart` recipe (REQ-075): sectors ∝ value, a central readout, a legend with shares. */
+declare const donutChart: ChartRecipe<DonutChartProps>;
+
+/** `RadarChart` recipe (REQ-076): one spoke per subject, a closed polygon of values. */
+declare const radarChart: ChartRecipe<RadarChartProps>;
+
+/** `PolarBarChart` recipe (REQ-077): equal slots around the turn, bar length ∝ value. */
+declare const polarBarChart: ChartRecipe<PolarBarChartProps>;
+
+/** `CoxcombChart` recipe (REQ-088): Nightingale's polar area — equal angles, area ∝ value. */
+declare const coxcombChart: ChartRecipe<CoxcombChartProps>;
+
+/** `RadialArcGroup` recipe (REQ-078): concentric 180° tracks, sweep ∝ value / the largest. */
+declare const radialArcGroup: ChartRecipe<RadialArcGroupProps>;
+
+/** `RadialRings` recipe (REQ-079): concentric progress rings, sweep ∝ value in 0-100. */
+declare const radialRings: ChartRecipe<RadialRingsProps>;
+
+/** `GaugeArc` recipe (REQ-080): a 240° arc swept to a percent, the readout at its centre. */
+declare const gaugeArc: ChartRecipe<GaugeArcProps>;
+
+/** `MeterChart` recipe (REQ-081): a semicircular meter whose needle points at a percent. */
+declare const meterChart: ChartRecipe<MeterChartProps>;
+
+/** `WindRose` recipe (REQ-089): the share of observations per compass sector, stacked by speed. */
+declare const windRose: ChartRecipe<WindRoseProps>;
+
+/** `ChordRing` recipe (REQ-091): directed flows between categories, ribbons over `d3-chord`. */
+declare const chordRing: ChartRecipe<ChordRingProps>;
+
+/** `OrbitChart` recipe (REQ-092): nested tilted orbits, markers along them by period, sized by value. */
+declare const orbitChart: ChartRecipe<OrbitChartProps>;
+
+/** `VolvelleChart` recipe (REQ-090): concentric categorical rings read against one index. */
+declare const volvelleChart: ChartRecipe<VolvelleChartProps>;
+
+/** `CandlestickChart` recipe (REQ-071): OHLC bodies and wicks, bounds derived or pinned (REQ-097). */
+declare const candlestickChart: ChartRecipe<CandlestickChartProps>;
+
+/** `AreaChart` recipe (REQ-072): a curved area, toned, under its exact line. */
+declare const areaChart: ChartRecipe<AreaChartProps>;
+
+/** `RangeBandChart` recipe (REQ-073): the band between a low and a high series. */
+declare const rangeBandChart: ChartRecipe<RangeBandChartProps>;
+
+/** `StreamChart` recipe (REQ-074): two waves, overlaid or stacked, told apart by dash and name. */
+declare const streamChart: ChartRecipe<StreamChartProps>;
+
+/** `ScatterChart` recipe (REQ-082): points on two linear scales, optionally sized by area. */
+declare const scatterChart: ChartRecipe<ScatterChartProps>;
+
+/** `BubbleChart` recipe (REQ-083): circles whose area encodes the size. */
+declare const bubbleChart: ChartRecipe<BubbleChartProps>;
+
+export { type Accessor, type ActiveItem, type ActivityGridProps, type AreaChartProps, type BandScale, type BarChartProps, type BubbleChartProps, type BulletChartProps, type CandlestickChartProps, type ChartHandle, type ChartModel, type ChartRecipe, type ChordRingProps, type CommonChartProps, type ComposedChartProps, type CoxcombChartProps, DEFAULTS, DISPLAY_FACE_PROBE, type DataTable, type Datum, type Detail, type DiagnosticSink, type DonutChartProps, FORCED_PRECISION_QUERY, type FontFaceSetLike, type FunnelChartProps, type GaugeArcProps, type Geometry, type Ground, type GroundName, type GroundRef, type HeatmapChartProps, type HitArea, type InkMode, type InkOptions, type Inker, type InteractionEvent, type InteractionResult, type KpiCardProps, LINE_CHART_DEMO, LINE_CHART_DEMO_KEYS, type LabelKind, type LineChartProps, type LineCurve, type LinearScale, MIN_TOUCH_TARGET, type MeterChartProps, NAVIGATION_KEYS, NullInker, type OrbitChartProps, PATH_BYTE_BUDGET, type PathView, type PatternView, type PointerKind, type PolarBarChartProps, type ProviderConfig, type PyramidChartProps, type RadarChartProps, type RadialArcGroupProps, type RadialRingsProps, type RangeBandChartProps, type Readout, type RecipeContext, type Rect, type ResolvedConfig, type SankeyChartProps, type ScaleSite, type ScatterChartProps, type Seed, SilverpointError, type SpCode, type SparklineRowsProps, type StackedBarChartProps, type StepChartProps, type StreamChartProps, type Stroke, type StrokePaint, type StrokePart, type StrokeRole, type SubstrateName, type SvgView, type TextLabel, type TextView, type Tile, type TonalRamp, type ToneLevel, type ToneSpec, type TreemapChartProps, type ViewStyle, type VolvelleChartProps, type WaterfallChartProps, type WindRoseProps, __setDiagnosticSink, activityGrid, addDays, areaChart, bandScale, barChart, bubbleChart, bulletChart, candlestickChart, checkTypeface, chordRing, circlePath, composedChart, coxcombChart, createPrng, deriveSeed, diagnose, donutChart, enforceHeightening, expandDomain, extent, fnv1a32, funnelChart, gaugeArc, heatmapChart, instanceId, isoDate, kpiCard, lineChart, linearScale, max, meterChart, min, orbitChart, parseGeometry, parseIsoDate, pathBytes, polarBarChart, pyramidChart, radarChart, radialArcGroup, radialRings, rangeBandChart, readout, reduceInteraction, registerInker, resolveActive, resolveConfig, resolveInker, resolveSeed, round2, roundGeometry, roundPathData, sameActive, sankeyChart, scatterChart, serializeGeometry, sparklineRows, stackedBarChart, stepActive, stepChart, streamChart, svgString, toSvgPoint, toSvgView, treemapChart, volvelleChart, waterfallChart, weekday, windRose };