altitude-design 0.2.1 → 0.3.0

package/dist/types/chart.d.ts

@@ -0,0 +1,570 @@
+import * as React from 'react';
+/** A categorical slot of the data palette. */
+export type ChartSlot = `data-${1 | 2 | 3 | 4 | 5 | 6}` | 'data-other';
+export interface ChartSeriesConfig {
+    /** The series' name, in the legend, the readout, the summary and the table. */
+    label: string;
+    /** Formats a value of this series: ticks, readouts, the summary. Default: Intl.NumberFormat. */
+    format?: (value: number) => string;
+    /** The series' colour slot. Default: its place in the config (the first is data-1); a seventh and later are data-other. */
+    color?: ChartSlot;
+}
+/** Each data key a chart draws, mapped to its label, format and colour slot. The order is the colour order, fixed for the chart's life. */
+export type ChartConfig = Record<string, ChartSeriesConfig>;
+export type ChartDatum = Record<string, unknown>;
+/**
+ * Data that isn't yet the record (#67): `partial` is a period still being counted (this month so far), `projected` a
+ * value that hasn't happened (a forecast). Both are drawn hatched or dashed, never raised, and say so in words.
+ */
+export type ChartStatus = 'partial' | 'projected';
+/** The words each status says, in point names, the readout and the table. */
+export declare const CHART_STATUS_WORDS: Record<ChartStatus, string>;
+export interface ChartSeries {
+    key: string;
+    label: string;
+    slot: ChartSlot;
+    /** `var(--data-n)`: use it as a fill or stroke. The figure also sets `--color-<key>` to it. */
+    color: string;
+    format: (value: number) => string;
+}
+export interface LinearScale {
+    (value: number): number;
+    kind: 'linear';
+    domain: [number, number];
+    range: [number, number];
+    ticks: number[];
+}
+export interface TimeScale {
+    (value: string | number): number;
+    kind: 'time';
+    domain: [number, number];
+    range: [number, number];
+    ticks: number[];
+}
+export interface BandScale {
+    (value: string): number;
+    kind: 'band';
+    domain: string[];
+    range: [number, number];
+    ticks: string[];
+    bandwidth: number;
+    step: number;
+}
+export type ChartXScale = LinearScale | TimeScale | BandScale;
+/** ISO 'YYYY-MM-DD' (or a full ISO timestamp), read as UTC, or epoch milliseconds. */
+export declare function toTime(v: unknown): number;
+export declare function textWidth(s: string): number;
+/** A label cut with an ellipsis to fit max px. The full text stays in the summary, the readout and the table. */
+export declare function fit(s: string, max: number, measure?: (s: string) => number): string;
+export interface ChartContextValue {
+    /** The plot's size in px, inside the axes. Marks draw from (0, 0) at its top left. */
+    width: number;
+    height: number;
+    x: ChartXScale;
+    y: LinearScale;
+    /** Where a datum sits on x: a band's centre, or its time or value. */
+    xOf: (d: ChartDatum) => number;
+    /** The y of the ground line: y(0) when zero is in the domain, otherwise the plot's foot. */
+    ground: number;
+    /** The records as they're shown right now: while the data changes, values glide and leaving records linger. */
+    data: ChartDatum[];
+    xKey: string;
+    config: ChartConfig;
+    series: ChartSeries[];
+    /**
+     * How present a mark is, 0–1, while records or series enter and leave: multiply it into the mark's opacity. Pass
+     * the record, the series key, or both.
+     */
+    alpha: (d?: ChartDatum | null, seriesKey?: string) => number;
+    /** Formats a value of a series (by its key), or an x value. */
+    format: (key: string, value: number) => string;
+    formatX: (value: unknown) => string;
+    /**
+     * Categories run down the side and values along the bottom. `x` still places categories and `y` values; only their
+     * directions change: x(cat) is a distance from the top, y(v) from the left, and `ground` is y(0) across.
+     */
+    horizontal: boolean;
+    /** The series the keyboard is on, or null: chart types draw the others receded. */
+    emphasis: string | null;
+    /** The record the readout is on (pointed at, touched, or focused from the keyboard), or null. */
+    active: ChartDatum | null;
+    /** Put the readout on a record by its index in `data`, or take it away with null: for keyboard paths. */
+    setActive: (index: number | null) => void;
+    /**
+     * How to draw a series so it's told apart without colour: its fill (a hatch when patterns are on), stroke, dash and
+     * marker, fixed by its slot like its colour. Use these instead of `series.color` and every mode is handled. Pass the
+     * record for a mark that stands for one (a bar, a dot), so a record focus can set it in data-context.
+     */
+    encode: (seriesKey: string, d?: ChartDatum) => ChartEncoding;
+    /** Patterns are on: the `patterns` prop, forced colours or print. */
+    patterns: boolean;
+    /** Label series directly at their marks, not only in a legend: on under forced colours and in print. */
+    directLabels: boolean;
+    /** Line width (2, or 3 under contrast="more"), and the gap between adjacent marks (2, or 3). */
+    strokeWidth: number;
+    gap: number;
+    /** Whether a record is the record yet: undefined for settled data, or 'partial' / 'projected' (#67). */
+    status: (d: ChartDatum) => ChartStatus | undefined;
+    /** Some record has a status: chart types draw the not-yet-record parts with `encode(key).pending`. */
+    hasStatus: boolean;
+    /**
+     * The stretches of x that aren't yet the record, and those that are, in plot px, for clipping a line or an area: a
+     * segment is pending when either of its ends is. Empty `pending` when every record is settled.
+     */
+    statusRanges: {
+        record: Array<[number, number]>;
+        pending: Array<[number, number]>;
+    };
+    /** Filtered in place (#70): 'match', 'miss' or undefined (no filter). Misses recede; nothing is removed. */
+    relevance: (d: ChartDatum) => 'match' | 'miss' | undefined;
+    /** The chart was given a relevance: chart types wrap marks in a receding group (ChartRelevance) so changes cross-fade. */
+    hasRelevance: boolean;
+    /** For lines and areas: the stretch of x each record owns (to the midpoints with its neighbours), and whether it's a miss. */
+    relevanceRegions: Array<{
+        key: string;
+        x0: number;
+        x1: number;
+        miss: boolean;
+    }>;
+    /** Changed since a snapshot (#191): a mark's old value where it changed (null if it didn't, or is new), or null without `since`. */
+    sinceOld: ((d: ChartDatum, seriesKey: string) => number | null) | null;
+}
+export type ChartMarkerShape = 'circle' | 'square' | 'triangle' | 'diamond' | 'ring' | 'cross';
+export interface ChartEncoding {
+    slot: ChartSlot;
+    /** Outside the chart's focus (#188): drawn in data-context (GrayText under forced colours), its label in ink-muted. */
+    context: boolean;
+    /** For bars and areas: the series colour, a hatch of it, or CanvasText under forced colours. */
+    fill: string;
+    /** For lines and outlines. */
+    stroke: string;
+    /** For a line: undefined is solid. Set only while patterns are on, except slot 1, which is always solid. */
+    dash?: string;
+    marker: ChartMarkerShape;
+    /** A 1px edge for a filled mark: ink under contrast="more", CanvasText under forced colours, otherwise none. */
+    edge?: string;
+    /**
+     * For a mark that isn't yet the record: a 45° hatch of the series colour on the plot's own colour, no solid fill.
+     * While patterns are on, a slot that already has a hatch keeps it, faded to `pendingOpacity`, so it stays told apart.
+     */
+    pending: string;
+    /** The fill-opacity to draw `pending` at: 1, or less for a slot's own hatch while patterns are on. */
+    pendingOpacity: number;
+    /** The dash a not-yet-record line takes: the slot's own dash while patterns are on, otherwise 5 4. */
+    pendingDash: string;
+}
+/** A series' marker, centred on (x, y): the shape its slot gives it, so points are told apart without colour. */
+export declare function ChartMarker({ shape, x, y, size, color, ...rest }: {
+    shape: ChartMarkerShape;
+    x: number;
+    y: number;
+    size?: number;
+    color: string;
+} & React.SVGProps<SVGElement>): React.JSX.Element;
+/** A clip to stretches of x (from `statusRanges`), for drawing a line or an area's record and not-yet-record parts apart. */
+export declare function ChartStatusClip({ id, ranges, height }: {
+    id: string;
+    ranges: Array<[number, number]>;
+    height: number;
+}): React.JSX.Element;
+/**
+ * A group that recedes when what it draws doesn't match the filter (#70): 35% opacity, cross-faded over dur-travel-1,
+ * never moved or recoloured. Wrap each mark (or each record's clipped stretch of a line) in one.
+ */
+export declare function ChartRelevance({ miss, children, ...rest }: {
+    miss: boolean;
+    children?: React.ReactNode;
+} & React.SVGProps<SVGGElement>): React.JSX.Element;
+/** The scales, plot size and config of the nearest ChartContainer, for drawing your own marks. */
+export declare function useChart(): ChartContextValue;
+/**
+ * What a chart type tells its container, as a static `chartInfo` on the component: its name for the summary, how to
+ * place x, whether zero must be on y, and the y extent if it isn't the plain min and max of the series (a stack).
+ */
+export interface ChartInfo {
+    kind?: string;
+    xScale?: 'band' | 'time' | 'linear';
+    zero?: boolean;
+    yExtent?: [number, number];
+    /** Categories down the side and values along the bottom (band x only). */
+    layout?: 'vertical' | 'horizontal';
+    /** The records as the chart wants them placed (sorted, say). Return the same array for the same input, or every render is a change. */
+    data?: ChartDatum[];
+    /** Formats the value axis only, when the axis isn't in the series' units (shares of a stack). */
+    yFormat?: (value: number) => string;
+    /** Formats every value (axis, readout, names, summary) of a series that has no format of its own. */
+    format?: (value: number) => string;
+    /**
+     * What the chart is about (#188): series keys that keep their colours while the rest take data-context, or a test
+     * for the records that keep theirs (bars, dots).
+     */
+    focus?: string[] | ((d: ChartDatum) => boolean);
+    /**
+     * Read against the record before (#189): the key holding each record's previous value, the series it's compared with
+     * (null: the stack's total), and the earlier period's name. Previous values join y and glide with the data.
+     */
+    compare?: {
+        key: string;
+        series: string | null;
+        label: string;
+    };
+    /** Readings can be pinned to the plot (#190): true for two, or how many. */
+    pinnable?: boolean | number;
+    /** The pinned readings' x values, controlled; and when they change. */
+    pins?: Array<string | number>;
+    onPinsChange?: (pins: Array<string | number>) => void;
+    /** Bank the plot's proportions to the data (#194): the chart type asked for aspect="banked". */
+    aspect?: 'banked';
+    /** Extra room at the plot's right edge, in px: for labels a chart sets beside its marks (a line's end label). */
+    right?: number;
+    /** How the legend draws this chart's series: a block (bars, areas) or a short line (lines). */
+    swatch?: 'rect' | 'line' | 'marker';
+    /** The imprint's shape while data loads. Default: a line for line swatches, bars otherwise. */
+    imprint?: 'bars' | 'line' | 'area' | 'grid' | 'dots';
+    /** Series are drawn bottom to top (a stack of areas): ↑ moves to the series above, ↓ to the one below. */
+    seriesUp?: boolean;
+    /** A stacked point names its share of the total ("31% of 3.9K") rather than only the total. */
+    share?: boolean;
+    /** Marks you can select (#69): the selected record's x, and what to do when a record is chosen (null clears). */
+    selected?: unknown;
+    onSelect?: (d: ChartDatum | null) => void;
+    /** Marks you drill into (#69): the id of the current Drilldown node's child that a record opens. */
+    drill?: (d: ChartDatum) => string | null | undefined;
+    /** Filter in place (#70): which records match. Misses recede to 35%, keeping their place and colour. */
+    relevance?: (d: ChartDatum) => 'match' | 'miss' | undefined;
+    /** Fit y to the matches rather than holding the axis. The rescale is staged as any is. */
+    rescale?: boolean;
+    /** Which records aren't yet the record (#67). */
+    status?: (d: ChartDatum) => ChartStatus | undefined;
+    /** The rule where the record ends and the rest begins: its word (default "Today"), or false for none. */
+    boundary?: string | false;
+    /** The x domain to show (a sliding window's span), instead of the records' extent. Time and linear x only. */
+    xDomain?: [number, number];
+    /** An uncertainty band around one series: its low and high keys, which also count toward y's extent. */
+    band?: {
+        series?: string;
+        low: string;
+        high: string;
+        label: string;
+    };
+    /** A record's identity, when x alone doesn't name it (a cell, a dot): keys motion, the table, selection and live changes. */
+    id?: (d: ChartDatum) => string;
+    /** A record's short name, for the readout's heading, the table and "Filtered to …". Default: its x, formatted. */
+    label?: (d: ChartDatum) => string;
+    /** The key the chart places along x, when it isn't an `x` prop (a calendar's date). */
+    x?: string;
+    /**
+     * The chart draws its own plot: 'grid' is cells over two categories, labelled by the chart, with no value axis,
+     * gridlines, ground line or crosshair; 'xy' is dots over two measures, found in two dimensions, with no crosshair.
+     * Either way the readout sits beside the mark.
+     */
+    plot?: 'grid' | 'xy';
+    /** Room above the plot for labels the chart sets itself (a measure's name over its axis), in px. */
+    top?: number;
+    /** Room below the axis for labels the chart sets itself (a measure's name under its axis), in px. */
+    bottom?: number;
+    /** Room at the plot's left for labels the chart sets itself (a grid's row names), in px. */
+    left?: number;
+    /** The plot's height for its width, when the content sets it (a calendar's weeks): replaces the aspect ratio. */
+    fitHeight?: (plotWidth: number) => number;
+    /** The keyboard goes from the summary straight to the records, without a series level (groups, or one value). */
+    flat?: boolean;
+    /**
+     * 'none': values change in place, and the chart type cross-fades its own marks (a heatmap's cells). 'fade': every
+     * change cross-fades, for records with no stable identity to glide by.
+     */
+    motion?: 'none' | 'fade';
+    /** Extra keys that glide with the values (a dot's x). */
+    glide?: string[];
+    /** The series, when they aren't the config's keys (a scatter's groups). The config then names the measures. */
+    series?: Array<{
+        key: string;
+        label: string;
+        color?: ChartSlot;
+        format?: (v: number) => string;
+    }>;
+    /** Formats x values (ticks, the readout), when the chart knows x's format (a measure in the config). */
+    xFormat?: (value: unknown) => string;
+    /** The table view's columns, when a column per series isn't the shape of the data. */
+    columns?: ChartColumn[];
+    /** The generated summary, when the chart type can say it better than a trend per series. */
+    summary?: string;
+}
+/** A column of the table view. */
+export interface ChartColumn {
+    key: string;
+    header: string;
+    cell: (d: ChartDatum) => React.ReactNode;
+    sortValue?: (d: ChartDatum) => string | number;
+    align?: 'start' | 'end';
+}
+/** What a chart type puts in the readout instead of a row per series. */
+export interface ChartReadout {
+    label: string;
+    items: ChartTooltipItem[];
+    indicator?: 'line' | 'dot';
+}
+export interface ChartTooltipItem {
+    key: string;
+    label: string;
+    value: number;
+    /** The value as its series formats it. */
+    text: string;
+    color: string;
+    dash?: string;
+    /** An uncertainty band's row ("80K–95K, Range"), keyed by a block of its fill rather than a stroke. */
+    range?: boolean;
+}
+export interface ChartTooltipContentProps {
+    /** How each row is keyed: a short stroke of the series colour (default), a dot, or a dashed stroke. */
+    indicator?: 'line' | 'dot' | 'dashed';
+    /** Formats the readout's heading, the x value. Default: the container's. */
+    labelFormat?: (x: unknown) => React.ReactNode;
+    hideLabel?: boolean;
+    hideIndicator?: boolean;
+    /** Filled in by the container: the x being read, and one item per shown series with a value there. */
+    label?: unknown;
+    payload?: ChartTooltipItem[];
+    /** Filled in by the container: formats x. */
+    formatX?: (x: unknown) => string;
+    /** Filled in by the container: "So far" or "Projected" when the record under the readout isn't yet the record. */
+    note?: string;
+    /** Filled in by the container: what a click does here ("Select to filter"), when marks act. Hover is a promise. */
+    action?: string;
+}
+/**
+ * The readout's rows: value first (ink, tabular), series name second (ink-muted), keyed by a short stroke of the
+ * series colour, which takes the series' dash when patterns are on. Labels are text, never HTML.
+ */
+export declare function ChartTooltipContent({ indicator, labelFormat, hideLabel, hideIndicator, label, payload, formatX, note, action }: ChartTooltipContentProps): React.JSX.Element;
+/**
+ * Puts your own content in a chart's readout. The readout is on for every chart by default; this only changes what it
+ * shows. Place it inside the chart type or the container: `<ChartTooltip content={<ChartTooltipContent indicator="dot" />} />`.
+ */
+export declare function ChartTooltip(_: {
+    content?: React.ReactElement<ChartTooltipContentProps>;
+}): null;
+export declare namespace ChartTooltip {
+    var chartHtml: boolean;
+    var chartTooltip: boolean;
+}
+export interface ChartLegendItem {
+    key: string;
+    label: string;
+    fill: string;
+    stroke: string;
+    dash?: string;
+    hidden: boolean;
+    marker?: ChartMarkerShape;
+    /** Outside the chart's focus (#188): its label recedes to ink-muted. */
+    context?: boolean;
+    /** In the chart's focus: said as "highlighted". */
+    highlighted?: boolean;
+}
+export interface ChartLegendContentProps {
+    /** Let people hide and show series. Each key becomes a switch-like button in a toolbar. Default false: keys only name. */
+    toggle?: boolean;
+    /** The hidden series' keys, controlled. */
+    hidden?: string[];
+    /** The hidden series' keys to start with, uncontrolled. */
+    defaultHidden?: string[];
+    onHiddenChange?: (hidden: string[]) => void;
+    /** The toolbar's name. Default "Series". */
+    label?: string;
+    /** Filled in by the container. */
+    items?: ChartLegendItem[];
+    swatch?: 'rect' | 'line' | 'marker';
+    onToggle?: (key: string) => void;
+}
+/**
+ * The legend's keys. Without `toggle` they're labels, flush on the ground: a swatch in the series colour and its name
+ * in ink. With `toggle` each key is a choice, so it's built like a Checkbox: a trench the series colour pours into
+ * while the series is shown, inside a ghost button that lifts when pointed at. The keys form one toolbar (one Tab
+ * stop; ←/→ between keys), each an aria-pressed button; the last shown series can't be hidden.
+ */
+export declare function ChartLegendContent({ toggle, label, items, swatch, onToggle }: ChartLegendContentProps): React.JSX.Element;
+/** A legend for the chart: place it inside the chart type or the container, with its content. */
+export declare function ChartLegend(_: {
+    content?: React.ReactElement<ChartLegendContentProps>;
+}): null;
+export declare namespace ChartLegend {
+    var chartHtml: boolean;
+    var chartLegend: boolean;
+}
+/**
+ * The record before, to read each value against (#189): a field on the same record (`key`), or records matched by x
+ * position (`data`, for a shifted period on a time axis), named by `label` ("August", "Last week"). `series` is the
+ * one compared, by default the first; a stack is compared by its total.
+ */
+export interface ChartCompare {
+    key?: string;
+    data?: ChartDatum[];
+    label: string;
+    series?: string;
+}
+/** Where a matched earlier period's value is kept on each record. */
+export declare const COMPARE_KEY = "__compare";
+/**
+ * Each record with its earlier value under COMPARE_KEY: the sum of `keys` on the record at the same position in
+ * `before`. The same arrays give the same result, so it isn't mistaken for a change.
+ */
+export declare function withCompare(rows: ChartDatum[], before: ChartDatum[], keys: string[]): ChartDatum[];
+/** A change in words: "+10.6%", or the difference itself when the earlier value is zero. */
+export declare function changeWords(now: number, before: number, format: (v: number) => string): string;
+export interface ChartReferenceProps {
+    /** Where on the value axis: a value (a line), a range [low, high] (a band), or the 'mean' or 'median' of a series. */
+    y: number | [number, number] | 'mean' | 'median';
+    /** What it is, in words: "Target 99.9%", "Normal range", "Average". A mean or median adds its value. */
+    label: string;
+    /** A threshold that means good or bad: the line wears caution or critical, and its label the status icon. */
+    tone?: 'caution' | 'critical';
+    /** The series a mean or median is read from. Default: the first shown. */
+    series?: string;
+}
+/**
+ * Something to read the chart against: a target, a limit, a normal range, the average. A line is 1px ink-muted and
+ * solid (dashes mean "projected"), labelled at its right end; a band is a flat line-coloured fill, labelled inside.
+ * Place it inside the chart type or the container. The container draws it, so labels stay clear of each other and of
+ * the marks.
+ */
+export declare function ChartReference(_: ChartReferenceProps): null;
+export declare namespace ChartReference {
+    var chartHtml: boolean;
+    var chartReference: boolean;
+}
+export interface ChartAnnotationProps {
+    /** Where on x: a date, a number or a category, as the data's x values are written. */
+    x: string | number;
+    /** The event, in a few words: "v2 launch". */
+    label: string;
+    /** Makes the plate a button, which lifts one level when pointed at. */
+    onSelect?: () => void;
+}
+/**
+ * An event on x ("the day we shipped v2"): a Badge plate flush at the top of the plot with a 1px line-control leader
+ * down to its x. Plates that would overlap stack into rows, above the data. Listed after the summary for screen readers.
+ */
+export declare function ChartAnnotation(_: ChartAnnotationProps): null;
+export declare namespace ChartAnnotation {
+    var chartHtml: boolean;
+    var chartAnnotation: boolean;
+}
+/** Where a change is: the axis rescaling, the marks gliding to their values, or a cross-fade. */
+export type ChartStage = 'rescale' | 'values' | 'fade';
+export interface ChartContainerProps extends Omit<React.HTMLAttributes<HTMLElement>, 'title'> {
+    config: ChartConfig;
+    /**
+     * The records. Optional when the chart inside takes `data` itself. `undefined` or a promise: the chart's imprint
+     * until they land. `null` or `[]`: an EmptyState. A rejected promise goes to your error boundary.
+     */
+    data?: ChartDatum[] | null | PromiseLike<ChartDatum[] | null>;
+    /** The key of x in each record. Optional when the chart inside takes `x`. */
+    x?: string;
+    /** How x is placed. Default: time for ISO dates, epoch numbers or Dates; linear for other numbers; band otherwise. */
+    xScale?: 'band' | 'time' | 'linear';
+    /**
+     * Width ÷ height of the plot. Default 2, unless `height` is set. 'banked' (#194): the line chart's segments set it,
+     * banked to an average of 45° so slopes read accurately, between 1 and 4 for the data area; the width is the card's.
+     */
+    aspect?: number | 'banked';
+    /** The plot's height in px, instead of an aspect ratio. */
+    height?: number;
+    /** A visible name, inside the figure. Leave it out when a CardTitle names the chart, and pass `aria-labelledby`. */
+    title?: React.ReactNode;
+    /**
+     * The one thing the chart says, as its heading: "Cedar shipped twice as often as Delta in March" (#187). The title
+     * then sits above it as a small label, so the chart is still named; screen readers hear the title, then this, then
+     * the summary. Write it from the data shown, a trend or a comparison rather than the encoding. It's never generated.
+     */
+    takeaway?: React.ReactNode;
+    description?: React.ReactNode;
+    /** What the chart shows, in a sentence or two: "Revenue rose 18% while costs held flat." Shown under the plot. Without it a summary is generated for screen readers. */
+    summary?: React.ReactNode;
+    /** Force zero onto y. Default true: bars always stand on the ground line, and lines read best against it too. */
+    zero?: boolean;
+    /** A fixed y domain, instead of the series' extent made nice. */
+    yDomain?: [number, number];
+    /** Formats y ticks. Default: the first series' format. */
+    yFormat?: (value: number) => string;
+    /** Formats x ticks and x values. Default: by the scale (dates in the reader's locale, numbers as numbers). */
+    xFormat?: (value: unknown) => string;
+    /** The gap between bands, as a fraction of a band's step. Default 0.2. */
+    bandPadding?: number;
+    /** Turns the axes off, for a chart that labels its marks directly. Gridlines and the ground line stay. */
+    axes?: boolean;
+    /**
+     * Where the value axis's labels go (#193). 'gutter' (default): a column at the plot's left. 'inline': each label sits
+     * just above its gridline at the plot's left, on a halo, so the plot runs the full width; the top label carries the
+     * unit, a label that would cover a mark is left out, and the ground line goes unlabelled (it is zero). Vertical
+     * cartesian charts only.
+     */
+    yLabels?: 'gutter' | 'inline';
+    /** The locale for numbers and dates. Default: the reader's. */
+    locale?: string;
+    /** The crosshair and readout. Default true; a chart type's `tooltip={false}` turns it off too. */
+    tooltip?: boolean;
+    /**
+     * Adds a Chart | Table control: the same data as a sortable table, in the chart's own box. true starts on the chart,
+     * 'table' on the table.
+     */
+    views?: boolean | 'chart' | 'table';
+    /** The view shown, controlled. */
+    view?: 'chart' | 'table';
+    onViewChange?: (view: 'chart' | 'table') => void;
+    /** The table's first column header. Default: the x key, capitalised. */
+    xLabel?: string;
+    /**
+     * Tell series apart by pattern as well as colour: a hatch per slot on fills, a dash on lines, a marker on points.
+     * Always on under forced colours and in print; turn it on anywhere else for readers who want it.
+     */
+    patterns?: boolean;
+    /**
+     * Fresh data is on its way while this data stays shown: after dur-grace the marks drop to half strength and the
+     * plot says "Updating". A new promise passed while data shows does the same by itself.
+     */
+    refreshing?: boolean;
+    /** What the plot says when the data is null or empty: an EmptyState at widget size. Default title "No data to show". */
+    empty?: ChartEmpty;
+    /**
+     * The data updates on its own (#66). New or changed marks get an afterglow (more than four at once, and the
+     * "Updated 12:04" caption gets it instead); a window that moves on glides one step; and while the pointer or focus is
+     * in the plot, updates wait until you leave, so nothing changes under what you're reading.
+     */
+    live?: boolean;
+    /** With `live`: a "Pause updates" switch in the frame, for WCAG 2.2.2 (Pause, Stop, Hide). */
+    pausable?: boolean;
+    /**
+     * What changed since a snapshot (#191): the records as they were (`data`, matched by x or the chart's id) and when,
+     * in words (`label`: "since Tuesday 09:00"). A changed bar carries a tick at its old value, a changed line point a
+     * hollow ring; the frame says "3 changed since Tuesday 09:00" in a switch that filters to them; up to four changed
+     * marks get the afterglow on arrival. Storing what a person last saw is the application's.
+     */
+    since?: {
+        data: ChartDatum[];
+        label: string;
+    };
+    /** Updates are paused, controlled. Uncontrolled with `pausable`. */
+    paused?: boolean;
+    onPausedChange?: (paused: boolean) => void;
+    /**
+     * With `live`: what to say when new data lands, or nothing. Nothing is announced per tick by default; return a
+     * sentence only for what matters ("Error rate crossed 2%"). It's said politely.
+     */
+    announce?: (data: ChartDatum[], previous: ChartDatum[] | null) => string | null | undefined;
+    /** While a chart type's `relevance` filters, how the frame says how many match. Default "4 of 12 match". */
+    countLabel?: (matches: number, total: number) => string;
+}
+export interface ChartEmpty {
+    title?: React.ReactNode;
+    description?: React.ReactNode;
+    action?: React.ReactNode;
+}
+/**
+ * The frame every chart shares (see ChartFrame), and what it shows while its data is on its way. `undefined` or a
+ * pending promise: an imprint in the chart's shape, pressed into the page, with the title, description and legend
+ * already in place. It lands by fading in place: a chart's marks never rise out of their imprint, because rising
+ * would lift bars off the ground line and misstate every value. `null` or `[]`: an EmptyState in the plot. A new
+ * promise (or `refreshing`) while data shows: the old chart stays, at half strength after dur-grace. A rejected
+ * promise goes to your error boundary.
+ */
+export declare function ChartContainer(props: ChartContainerProps): React.JSX.Element;

package/dist/types/checklist.d.ts

@@ -0,0 +1,71 @@
+import * as React from 'react';
+export interface ChecklistPlace {
+    parentId: string | null;
+    index: number;
+}
+/** One change per action. The application applies it to `items` (synchronously, or before resolving). */
+export type ChecklistOp = {
+    type: 'add';
+    id: string;
+    text: string;
+    done: boolean;
+    parentId: string | null;
+    index: number;
+} | {
+    type: 'edit';
+    id: string;
+    text: string;
+    previous: string;
+} | {
+    type: 'toggle';
+    id: string;
+    done: boolean;
+} | {
+    type: 'remove';
+    id: string;
+    text: string;
+    done: boolean;
+    parentId: string | null;
+    index: number;
+} | {
+    type: 'move' | 'indent' | 'outdent';
+    id: string;
+    parentId: string | null;
+    index: number;
+    from: ChecklistPlace;
+};
+export type ChecklistResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+export interface ChecklistProps<T> {
+    'aria-label'?: string;
+    'aria-labelledby'?: string;
+    items: T[];
+    getKey: (item: T) => string;
+    getText: (item: T) => string;
+    isDone: (item: T) => boolean;
+    getChildren?: (item: T) => T[] | undefined;
+    /** Allow Tab and Shift+Tab to nest items. Default false: a flat list. */
+    nested?: boolean;
+    /** Show done items after the rest in each list. Default false. */
+    sortDone?: boolean;
+    /** Each action, as one op. Return a failure to mark the item and offer Retry. */
+    onChange: (op: ChecklistOp) => ChecklistResult | void | Promise<ChecklistResult | void>;
+    /** Ctrl/Cmd+Z: reverse the last structural op (add, remove, move, indent, outdent). A removal's announcement names the shortcut. */
+    onUndo?: (op: ChecklistOp) => void;
+    /** Ids for new items. Default: a random id. */
+    createId?: () => string;
+    /** The last, empty line's placeholder. Default “Add an item”. */
+    placeholder?: string;
+    disabled?: boolean;
+    className?: string;
+}
+/**
+ * A list you write into, one line per item. Each line is the editor (no Save, no read mode): it commits when you
+ * leave it. Items lie flush; the empty line at the end is an opening; the checkbox is a choice built like the Switch,
+ * and a done item is pressed into the record: muted and struck through, kept in place.
+ */
+export declare function Checklist<T>({ items, getKey, getText, isDone, getChildren, nested, sortDone, onChange, onUndo, createId, placeholder, disabled, className, ...aria }: ChecklistProps<T>): React.JSX.Element;

package/dist/types/code-block.d.ts

@@ -0,0 +1,32 @@
+import * as React from 'react';
+export interface CodeBlockTab {
+    label: string;
+    code: string;
+    language?: string;
+}
+export interface CodeBlockProps extends Omit<React.HTMLAttributes<HTMLElement>, 'title'> {
+    /** The code, for a single block. */
+    code?: string;
+    language?: string;
+    /** A filename or what the code is ("Install"). Shown in the header and names the scroll region. */
+    title?: React.ReactNode;
+    /** The same thing in several forms (npm, pnpm; curl, Node, Python): a segmented switch in the header. */
+    tabs?: CodeBlockTab[];
+    /** Lines to highlight, counted from 1. */
+    highlight?: number[];
+    /** Your highlighter (Shiki, Prism): returns the code coloured. Altitude ships none. */
+    syntax?: (code: string, language?: string) => React.ReactNode;
+    /** Line numbers in a gutter (hidden from assistive technology). Default false. */
+    lineNumbers?: boolean;
+    /** The code is still arriving (from an agent): a dashed rule and "Writing…", aria-busy. */
+    streaming?: boolean;
+    /** Taller code scrolls. Default 360. */
+    maxHeight?: number | string;
+    /** Default true. */
+    copyable?: boolean;
+}
+/**
+ * Code shown to read and copy is the record: it lies flush on the ground with a line rim, in mono, with no shadow.
+ * Several forms of the same thing switch with segmented Tabs; copy is a CopyButton; code still arriving has a dashed rule.
+ */
+export declare function CodeBlock({ code, language, title, tabs, highlight, syntax, lineNumbers, streaming, maxHeight, copyable, className, ...rest }: CodeBlockProps): React.JSX.Element;