@50arms/ui 0.0.0-stage → 35.2.0

package/dist/types/components/card-face/OverflowRow.d.ts

@@ -0,0 +1,40 @@
+import { type ReactNode } from "react";
+export interface OverflowItem {
+    /** Stable across renders; a card's marks come and go as its facts change. */
+    key: string;
+    /**
+     * Higher leaves the row FIRST. Display order is the array's order, never rank: rank only says which item a
+     * crowded row can least afford to keep.
+     */
+    hideRank: number;
+    /** DX-5422: the item never leaves for the `+N` popover; a crowded row shortens it and tucks the others instead. */
+    keep?: boolean;
+    /** `compact` is true once the row has had to shorten its items (step 2). */
+    render: (compact: boolean) => ReactNode;
+}
+/** Which item keys leave the row when `hiddenCount` of them must: highest `hideRank` first, the later item first among equals. */
+export declare function hiddenKeys(items: readonly OverflowItem[], hiddenCount: number): ReadonlySet<string>;
+export interface OverflowRowProps {
+    /** Always in the row, before the items, whatever the width; `compact` is true once the row has had to shorten its marks. */
+    pinned?: (compact: boolean) => ReactNode;
+    items: readonly OverflowItem[];
+    /**
+     * What the row's marks SAY, as one string: the pinned part's content and every mark's text that can change width
+     * under an unchanged key (a hold's count, a usage label, an age). When it changes the row starts over from the
+     * full form, so a mark that shrinks (a hold clears, a label gets shorter) is not left in a compacted row. It must
+     * be stable across renders that change nothing, or the row would restart on every one of them.
+     */
+    contentKey: string;
+    testId?: string;
+    className?: string;
+    /** The `+N` button's test id; its popover's list takes `<moreTestId>-items`. */
+    moreTestId?: string;
+    /**
+     * DX-5677: the row's marks sit at its END (an auto margin on the first mark, so an overflowing row still overflows
+     * to the end and `scrollWidth` still sees it). The row's flex-basis is then pinned to its FULL form's measured width
+     * once it has had to shorten, so a wrapping parent decides on the same width whatever form is drawn: without that, a
+     * shortened row would fit back beside its neighbour, be reset by the resize observer, no longer fit, and flicker.
+     */
+    alignEnd?: boolean;
+}
+export declare function OverflowRow({ pinned, items, contentKey, testId, className, moreTestId, alignEnd }: OverflowRowProps): import("react").JSX.Element;

package/dist/types/components/card-face/TapTip.d.ts

@@ -0,0 +1,15 @@
+import { type CSSProperties, type ReactNode } from "react";
+/** The CSS selector a click-delegating host uses to leave a `TapTip` to itself — matches the attribute below. */
+export declare const TAP_TIP_SELECTOR = "[data-tap-tip]";
+export interface TapTipProps {
+    tooltip: ReactNode;
+    /** The mark's accessible name, when it is a glyph with no text of its own; a mark that prints its words omits it. */
+    label?: string;
+    /** DX-4315: the tooltip's text as the mark's accessible description, present whether or not the tooltip is open (a screen reader has no hover). */
+    description?: string;
+    testId?: string;
+    className?: string;
+    style?: CSSProperties;
+    children: ReactNode;
+}
+export declare function TapTip({ tooltip, label, description, testId, className, style, children }: TapTipProps): import("react").JSX.Element;

package/dist/types/components/card-face/hit-area.d.ts

@@ -0,0 +1,20 @@
+/**
+ * DX-3984 / DX-5425 — a small mark's TOUCH target: on a coarse pointer an `::after` stretches the mark's hit area past its
+ * glyph (the target grows, the layout does not). Fine pointers keep the exact glyph box.
+ *
+ * THE STRETCH IS SET BY THE ROW, NOT BY THE MARK. A card face stacks two 16px rows 2px apart, so a fixed inset would make a
+ * mark's target run into its neighbours'. A row declares how far its marks may reach on each side through `--hit-t` /
+ * `--hit-b` / `--hit-x` (top, bottom, left and right) and chooses them so the targets TILE the stack and meet at the midpoint
+ * of every gap. A mark outside any such row reaches 8px every way.
+ *
+ * A mark's box must be as tall as its row for the vertical reach to land on the row's edge, so a row stretches its marks.
+ */
+export declare const COARSE_HIT_AREA: string;
+/**
+ * DX-4259 — a card face's activity-row mark height. The effort badge is 22px tall (an explicit `h-5.5`, DX-4799: an
+ * icon-only pill has no text line to size it), and the quality-gate and acceptance-criteria rings are exactly as tall: ring
+ * outer diameter = row height, no padding between the ring and the row's edge. The ring SVG is viewBox-scaled and its `row`
+ * track reaches the viewBox edge, so a size class on the ring is all it takes; `row` is kept for its thin track (a fat track
+ * at 22px would leave the centre icon no room).
+ */
+export declare const ROW_RING_SIZE = "size-5.5";

package/dist/types/components/card-face/vocabulary.d.ts

@@ -0,0 +1,83 @@
+import type { CoreIconName } from "../../icons/data";
+import type { PaletteKey } from "../../lib/calendar/types";
+import type { BADGE_TONE_TEXT } from "../Badge";
+import type { ProgressTone } from "../Progress";
+/** The icon of every meaning a card face draws. */
+export declare const CARD_FACE_ICONS: {
+    readonly "priority.lowest": "arrow-down";
+    readonly "priority.low": "chevron-down";
+    readonly "priority.medium": "minus";
+    readonly "priority.high": "chevron-up";
+    readonly "priority.very_high": "arrow-up";
+    readonly "priority.critical": "flame";
+    readonly "indicator.needsHuman": "hand";
+    readonly "indicator.snoozed": "alarm-clock";
+    readonly "indicator.effort": "cpu";
+    readonly "indicator.planGates": "clipboard-check";
+    readonly "indicator.codeGates": "file-code";
+    readonly "indicator.acceptanceCriteria": "list-checks";
+    readonly "indicator.comments": "message-square";
+    readonly "indicator.parent": "corner-left-up";
+    readonly "indicator.children": "git-branch";
+    readonly "indicator.retro": "scroll-text";
+    readonly "indicator.gateReviewer": "search-check";
+    readonly "indicator.pullRequest": "git-pull-request-arrow";
+    readonly "outcome.passed": "circle-check";
+    readonly "outcome.failed": "circle-x";
+    readonly "outcome.pending": "circle-dashed";
+    readonly "outcome.skipped": "skip-forward";
+    readonly "outcome.deferred": "clock";
+    readonly "outcome.withdrawn": "circle-minus";
+    readonly "solution.recommended": "star";
+    readonly "action.confirm": "check";
+    readonly "action.edit": "pencil";
+    readonly "action.dismiss": "x";
+};
+/** A tone a card-face mark is coloured by: the library's badge tones. */
+export type CardFaceTone = keyof typeof BADGE_TONE_TEXT;
+/** A priority tier, lowest to highest. */
+export declare const PRIORITY_TIERS: readonly ["lowest", "low", "medium", "high", "very_high", "critical"];
+export type PriorityTier = (typeof PRIORITY_TIERS)[number];
+/**
+ * Tiers rank on a grey → green → yellow → orange → red heat ramp: tertiary, success text, warning text, solid warning (the
+ * hotter amber), danger text, solid danger. Colour is never the only channel: the glyph differs per tier and every mark
+ * carries the tier's name in its tooltip and accessible name.
+ */
+export declare const PRIORITY_TIER_VISUALS: Readonly<Record<PriorityTier, {
+    icon: CoreIconName;
+    colorClass: string;
+}>>;
+/** A quality gate's verdict. */
+export declare const GATE_VERDICTS: readonly ["pass", "fail", "pending", "skipped"];
+export type GateVerdict = (typeof GATE_VERDICTS)[number];
+/** Same marks as the checklist states for the same meanings: a pass, a failure and a deliberate skip look alike everywhere. */
+export declare const GATE_VERDICT_VISUALS: Readonly<Record<GateVerdict, {
+    tone: CardFaceTone & ProgressTone;
+    icon: CoreIconName;
+}>>;
+/**
+ * A checklist item's (an acceptance criterion's) state, in SEVERITY order: a summary names a failure first. `cancelled`
+ * reads "Withdrawn" and `deferred` "Deferred", both `info`: each is resolved, and neither may look like a criterion still
+ * waiting to be met.
+ */
+export declare const CRITERION_STATES: readonly ["failing", "incomplete", "passing", "deferred", "cancelled"];
+export type CriterionState = (typeof CRITERION_STATES)[number];
+export declare const CRITERION_STATE_VISUALS: Readonly<Record<CriterionState, {
+    tone: CardFaceTone & ProgressTone;
+    icon: CoreIconName;
+}>>;
+/** The reasoning-effort rungs, lowest to highest. */
+export declare const EFFORT_RUNGS: readonly ["min", "very_low", "low", "medium", "high", "very_high", "max"];
+export type EffortRung = (typeof EFFORT_RUNGS)[number];
+/** A rung's pill colours, as CSS values: the family's subtle fill, its border and its text colour. */
+export declare function effortColors(rung: EffortRung): {
+    background: string;
+    borderColor: string;
+    color: string;
+};
+/** A hue's badge classes: fill, edge as border, `badgeText` as text (the edge, except slate's -text token, the one lifted to 4.5:1 so far). */
+export declare function paletteBadgeClassName(hue: PaletteKey): string;
+/** A hue's box classes (a lane's box around a parent's cards): fill and edge, no text colour. */
+export declare function paletteBoxClassName(hue: PaletteKey): string;
+/** A hue's text colour, for a `currentColor` icon that wears it: the edge for every hue, slate included. */
+export declare function paletteTextClassName(hue: PaletteKey): string;

package/dist/types/components/chart/BarList.d.ts

@@ -0,0 +1,27 @@
+import type { Ref } from "react";
+export interface BarListItem {
+    /** Unique within the list. */
+    id: string;
+    label: string;
+    /** Finite and >= 0 — anything else throws. */
+    value: number;
+    /** A quieter line under the label — a count, a unit, a note. */
+    secondary?: string;
+    /** Renders the row as a real link. Wins over `onSelect`. */
+    href?: string;
+    /** Renders the row as a button. */
+    onSelect?: () => void;
+}
+export interface BarListProps {
+    /** In the order to show; never re-sorted. */
+    items: readonly BarListItem[];
+    /** What the list measures, e.g. "What is contributing". Names the list and captions the table. */
+    label: string;
+    /** Keep this many rows and fold the rest into one `Other` row. @default every row */
+    maxItems?: number;
+    /** How a raw value reads in the row, the tooltip and the table. @default locale-formatted number */
+    formatValue?: (value: number) => string;
+    className?: string;
+    ref?: Ref<HTMLUListElement>;
+}
+export declare function BarList({ items, label, maxItems, formatValue: formatCaller, className, ref }: BarListProps): import("react").JSX.Element;

package/dist/types/components/chart/LineChart.d.ts

@@ -0,0 +1,64 @@
+import { type ReactNode, type Ref } from "react";
+import { type LineSeriesStyle } from "./line-series-style";
+import { type LinePoint } from "./line-chart-scale";
+export type { LinePoint } from "./line-chart-scale";
+export type { LineSeriesStyle } from "./line-series-style";
+export interface LineSeries {
+    /** Unique within the chart. */
+    key: string;
+    label: string;
+    /**
+     * DXUI-43: a line style in place of the palette colour. `"striped"` is a black-and-white striped line (ink over surface, so it reads in
+     * light and dark); `"danger"` is the danger (red) token; `"dashed"` is a long-dash line in the accent token (DXUI-50). Unset keeps the palette colour for the series' position.
+     */
+    style?: LineSeriesStyle;
+    /** Strictly ascending `t` (epoch ms), finite `value` >= 0 — anything else throws. May be empty. */
+    points: readonly LinePoint[];
+}
+/** A horizontal line at a value, e.g. the model's context window. */
+export interface LineReference {
+    /** Unique within the chart. */
+    id: string;
+    /** Finite and >= 0, in the same unit as the series' values. */
+    value: number;
+    /** Said beside the line and in the hidden list. */
+    label: string;
+}
+/** A point of interest on a series, e.g. a compaction. */
+export interface LineMarker {
+    /** Unique within the chart. */
+    id: string;
+    /** A `LineSeries.key`. */
+    series: string;
+    /** Epoch ms; must fall within that series' first and last point. */
+    t: number;
+    /** Names the marker in its tooltip, its accessible name and the hidden list. */
+    label: string;
+    /** Shown under the label and the time in the marker's tooltip. */
+    content?: ReactNode;
+}
+export interface LineChartProps {
+    /** What the chart measures, e.g. "Context size". Names the group and captions the table. */
+    label: string;
+    /** At most 8, in palette order. */
+    series: readonly LineSeries[];
+    referenceLines?: readonly LineReference[];
+    markers?: readonly LineMarker[];
+    /** How a raw value reads in the tooltip, the readout and the table. @default locale-formatted number */
+    formatValue?: (value: number) => string;
+    /** How a value reads on the y axis; use a compact form here. @default `formatValue` */
+    formatAxis?: (value: number) => string;
+    /** How an instant reads in the tooltip, the readout and the table. @default medium date and time in the viewer's locale */
+    formatTime?: (t: number) => string;
+    /** How an instant reads on the x axis, on one line. @default a time of day, with the date where the day changes */
+    formatAxisTime?: (t: number) => string;
+    /** IANA zone instants are labelled in, e.g. "UTC". @default the viewer's */
+    timeZone?: string;
+    /** Plot height in px. @default 240 */
+    height?: number;
+    /** Said when there is nothing to draw. @default the built-in "No data" */
+    emptyLabel?: string;
+    className?: string;
+    ref?: Ref<HTMLDivElement>;
+}
+export declare function LineChart(props: LineChartProps): import("react").JSX.Element;

package/dist/types/components/chart/ShareBar.d.ts

@@ -0,0 +1,26 @@
+import { type Ref } from "react";
+export interface ShareBarSegment {
+    /** Unique within the bar. */
+    id: string;
+    label: string;
+    /** Finite and >= 0 — anything else throws. */
+    value: number;
+    /** Any CSS colour. Wins over the palette hue the segment's position would get. */
+    color?: string;
+}
+export interface ShareBarProps {
+    segments: readonly ShareBarSegment[];
+    /** What the bar measures, e.g. "Model share". Names the group and captions the table. */
+    label: string;
+    /** How a raw value reads in the tooltip and the table. @default locale-formatted number */
+    formatValue?: (value: number) => string;
+    /**
+     * DXUI-26: draw the legend (and the direct share labels that lead into it) under the bar. `false` draws the bar
+     * alone, with neither in the DOM, for a surface that names the segments elsewhere (a hover popover). The segments
+     * keep their accessible names, tooltips and the hidden table either way. @default true
+     */
+    legend?: boolean;
+    className?: string;
+    ref?: Ref<HTMLDivElement>;
+}
+export declare function ShareBar({ segments, label, formatValue: formatCaller, legend: showLegend, className, ref }: ShareBarProps): import("react").JSX.Element;

package/dist/types/components/chart/TimeSeriesChart.d.ts

@@ -0,0 +1,60 @@
+import { type Ref } from "react";
+export type TimeSeriesRole = "member" | "other";
+export interface TimeSeriesSeries {
+    /** Unique within the chart. */
+    key: string;
+    label: string;
+    /** `other` is the neutral remainder: drawn last, in a neutral tone, never selectable. @default "member" */
+    role?: TimeSeriesRole;
+    /** One value per bucket, same order. Finite and >= 0 — anything else throws. */
+    points: readonly number[];
+}
+/** A named kind of unmeasured span: its label is its legend entry. At most two (45 and 135 degree hatching). */
+export interface TimeSeriesBlockKind {
+    key: string;
+    label: string;
+}
+/** A span the chart cannot place in time, drawn hatched in the bucket that holds `at`. */
+export interface TimeSeriesBlock {
+    /** Unique within the chart. */
+    id: string;
+    /** Epoch ms; must fall inside one of the buckets. */
+    at: number;
+    /** Finite and >= 0. Counts toward the bucket total. */
+    value: number;
+    /** What this span is, for its tooltip line and the table. */
+    label: string;
+    /** A `TimeSeriesBlockKind.key`. */
+    kind: string;
+}
+export interface TimeSeriesChartProps {
+    /** Each bucket's start, epoch ms, strictly ascending. */
+    buckets: readonly number[];
+    /** The width of one bucket in ms; null only when there are no buckets. */
+    bucketMs: number | null;
+    /** In stacking order, bottom first; also the palette order. */
+    series: readonly TimeSeriesSeries[];
+    blocks?: readonly TimeSeriesBlock[];
+    blockKinds?: readonly TimeSeriesBlockKind[];
+    /** What the chart measures, e.g. "Tokens over time". Names the group and captions the table. */
+    label: string;
+    /** @default "bar" */
+    variant?: "bar" | "area";
+    /** How a raw value reads in the tooltip and the table. @default locale-formatted number */
+    formatValue?: (value: number) => string;
+    /** How a value reads on the y axis; use a compact form here. @default `formatValue` */
+    formatAxis?: (value: number) => string;
+    /** IANA zone the buckets are labelled in, e.g. "UTC". @default the viewer's */
+    timeZone?: string;
+    /** Called with a member series' key when its band or its legend name is clicked. */
+    onSelectSeries?: (key: string) => void;
+    /** Plot height in px. @default 240 */
+    height?: number;
+    /** Said when there is nothing to draw. @default the built-in "No data" */
+    emptyLabel?: string;
+    /** Said over the axis when every value is zero. @default the built-in "All values are zero" */
+    zeroLabel?: string;
+    className?: string;
+    ref?: Ref<HTMLDivElement>;
+}
+export declare function TimeSeriesChart(props: TimeSeriesChartProps): import("react").JSX.Element;

package/dist/types/components/chart/label-metrics.d.ts

@@ -0,0 +1,9 @@
+/** Before the first measurement (and where there is no layout at all) a chart draws at this width. */
+export declare const FALLBACK_WIDTH = 600;
+export declare const MIN_WIDTH = 160;
+export declare const Y_LABEL_CHAR_PX = 8.5;
+export declare const Y_LABEL_GAP_PX = 10;
+/** Room the plot leaves on its left so the widest y-axis label sits fully inside the svg. */
+export declare function yAxisMargin(axisLabels: readonly string[]): number;
+export declare const LABEL_CHAR_PX = 6;
+export declare const LABEL_PAD_PX = 14;

package/dist/types/components/chart/line-chart-axis.d.ts

@@ -0,0 +1,14 @@
+export interface AxisTick {
+    t: number;
+    primary: string;
+    secondary: string | null;
+}
+/**
+ * The smallest round spacing whose labels fit side by side on a plot `plotW`
+ * wide, ticks on the zone's wall clock (midnights, hours, month starts). A span
+ * of no length is one tick. When no spacing fits, the widest one that gave two
+ * ticks is used and its labels crowd. When no spacing gave two ticks (a span
+ * shorter than the tightest spacing, or so long that even the widest would have
+ * more ticks than could be labelled) the axis is its two ends.
+ */
+export declare function axisTicks(min: number, max: number, plotW: number, timeZone: string | undefined, locale: string, formatAxisTime: ((t: number) => string) | undefined): AxisTick[];

package/dist/types/components/chart/line-chart-scale.d.ts

@@ -0,0 +1,55 @@
+export interface LinePoint {
+    /** Epoch ms. */
+    t: number;
+    /** Finite and >= 0. */
+    value: number;
+}
+/**
+ * How far the wall clock in `timeZone` is ahead of UTC at instant `t`, in ms
+ * (negative west of Greenwich). `undefined` is the viewer's own zone. The parts
+ * are read as Latin digits in the Gregorian calendar whatever `locale` is, so a
+ * Thai or Arabic locale cannot turn the year or the hour into something
+ * `Number` cannot read.
+ */
+export declare function zoneOffsetMs(t: number, timeZone: string | undefined, locale: string): number;
+/** Every multiple of `step` on the zone's wall clock whose instant is inside `[min, max]`, ascending. */
+export declare function timeTicks(min: number, max: number, step: number, timeZone: string | undefined, locale: string): number[];
+/** The first instant of every `months`-th month (counted from January of year 0) inside `[min, max]`, on the zone's calendar. */
+export declare function monthTicks(min: number, max: number, months: number, timeZone: string | undefined, locale: string): number[];
+export interface TickStep {
+    /** About how far apart the ticks are, ms: decides how many there could be and how a label reads. */
+    stepMs: number;
+    ticks: (min: number, max: number, timeZone: string | undefined, locale: string) => number[];
+}
+/** Every spacing the time axis may use, tightest first: seconds to hours, days, then calendar months to decades. */
+export declare const TICK_STEPS: readonly TickStep[];
+/** Index of the entry of `items` (ascending instants, or points by `t`) closest to `t`; the earlier one on a tie. `items` must not be empty. */
+export declare function nearestIndex(items: readonly number[] | readonly LinePoint[], t: number): number;
+/** The series' value at instant `t`: a point's own value at its instant, a straight line between neighbours elsewhere, null outside the series' span. */
+export declare function valueAt(points: readonly LinePoint[], t: number): number | null;
+/** Every distinct instant any series has a point at, ascending: the places a keyboard cursor can stand. */
+export declare function mergeInstants(series: readonly (readonly LinePoint[])[]): number[];
+/** The earliest and latest instant over every series' ascending points, or null when none has a point. */
+export declare function timeBounds(series: readonly (readonly LinePoint[])[]): {
+    min: number;
+    max: number;
+} | null;
+export interface PointSummary {
+    count: number;
+    /** Null when the series has no point. */
+    first: number | null;
+    last: number | null;
+    lowest: number | null;
+    highest: number | null;
+}
+/** A series reduced to what the text alternative says about it: how many points, the span in time, the range of values. */
+export declare function summarize(points: readonly LinePoint[]): PointSummary;
+/**
+ * Thin a long series to what the screen can show: when there are more points
+ * than twice the pixel columns, keep each column's first, lowest, highest and
+ * last point, in time order. A spike or a drop that spans less than a pixel
+ * survives, and the path stays a few hundred segments however many points came
+ * in. A series that already fits is returned as it is. `x` maps an instant to
+ * its pixel.
+ */
+export declare function decimate(points: readonly LinePoint[], x: (t: number) => number, columns: number): readonly LinePoint[];

package/dist/types/components/chart/line-series-style.d.ts

@@ -0,0 +1,14 @@
+/** `striped`: a black-and-white striped line. `danger`: the danger (red) token. `dashed`: a long-dash line in the accent token, no underlay, so it reads apart from `striped`. */
+export type LineSeriesStyle = "striped" | "danger" | "dashed";
+export interface LineSeriesPaint {
+    /** The line's colour, also the dots', the cursor dot's and the markers'. */
+    color: string;
+    /** A solid line drawn under the line (the other stripe colour); only a striped line has one. */
+    underlay?: string;
+    /** The line's `stroke-dasharray`; only a striped line has one. */
+    dash?: string;
+    /** A CSS `background` for the legend chip and the tooltip swatch, matching the line. */
+    swatch: string;
+}
+/** `fallback` is the palette colour for the series' position, kept when the series names no style. Theme tokens only: ink over surface flips with the theme. */
+export declare function lineSeriesPaint(style: LineSeriesStyle | undefined, fallback: string): LineSeriesPaint;

package/dist/types/components/chart/share-bar-labels.d.ts

@@ -0,0 +1,17 @@
+/** The smallest clear space, in px, left between two direct labels that sit side by side. */
+export declare const LABEL_GAP = 4;
+/** One direct label as laid out. All lengths are px, measured from the bar's LEFT edge (physical, also in RTL). */
+export interface LabelBox {
+    key: string;
+    share: number;
+    /** Offset of the label's centre (its segment's centre) from the bar's left edge. */
+    center: number;
+    /** Width of the printed label. */
+    width: number;
+}
+/**
+ * The keys of the labels that must NOT be drawn: one whose box (`center ± width / 2`) leaves `[0, barWidth]`
+ * (a clipping ancestor would cut it to a wrong number), or that comes within `LABEL_GAP` of a larger-share
+ * label already kept. The larger share wins a contested spot, so the answer does not depend on input order.
+ */
+export declare function labelsToDrop(boxes: readonly LabelBox[], barWidth: number): Set<string>;

package/dist/types/components/chart/shared.d.ts

@@ -0,0 +1,122 @@
+import { type ReactElement, type ReactNode, type Ref, type RefObject } from "react";
+/** The React key of a folded "Other" row. Caller ids are keyed `id:<id>`, so no caller id can equal it. */
+export declare const OTHER_KEY = "fold:other";
+export declare const rowKey: (id: string) => string;
+export interface ChartDatum {
+    id: string;
+    value: number;
+}
+/**
+ * Refuse an input a chart cannot draw truthfully, at the point it arrives.
+ * A negative magnitude has no length, a NaN has no share, and a duplicate id
+ * would collapse two rows into one React key — each is a caller bug that a
+ * clamped or skipped row would hide.
+ */
+export declare function assertChartData(component: string, data: readonly ChartDatum[]): void;
+/**
+ * A share as a person reads it: a whole number from 10% up, one decimal below
+ * (`4.5%`), and `<1%` for a real but tiny share so a nonzero segment is never
+ * printed as `0%`. A zero total reads `0%`, never `NaN%`.
+ */
+export declare function formatShare(fraction: number, locale: string): string;
+/** The default way a raw value reads. Callers pass `formatValue` for units. */
+export declare function defaultFormatValue(value: number, locale: string): string;
+/**
+ * A tooltip a keyboard and a finger can reach. Base UI opens its tooltip on
+ * hover and on KEYBOARD focus only — a tap or a programmatic focus never
+ * mounts it (DX-3014) — so the open state is held here and a plain `focus`
+ * opens it too. Escape and blur close it; hover is still Base UI's own.
+ */
+export declare function ChartTip({ content, children }: {
+    content: ReactNode;
+    children: ReactElement<Record<string, unknown>>;
+}): import("react").JSX.Element;
+/** What a tooltip says about one mark — ink tokens only, never the series colour. */
+export declare function TipBody({ label, lines }: {
+    label: ReactNode;
+    lines: readonly ReactNode[];
+}): import("react").JSX.Element;
+/**
+ * The visually hidden table every chart carries — the text-equivalent of its
+ * marks, in reading order, so colour and length are never the only way in.
+ * `sr-only` keeps it in the accessibility tree and out of the layout.
+ */
+export declare function ChartTable({ caption, columns, rows, }: {
+    caption: string;
+    columns: readonly string[];
+    rows: readonly {
+        key: string;
+        header: ReactNode;
+        cells: readonly ReactNode[];
+    }[];
+}): import("react").JSX.Element;
+/** The width of the element `ref` points at, kept current as it resizes; 0 until the first measurement. */
+export declare function useElementWidth(ref: RefObject<HTMLElement | null>): number;
+/** What a chart says when it has nothing to draw: the caption's group, a placeholder of the plot's height, and an empty table. */
+export declare function ChartEmpty({ label, text, height, className, ref, }: {
+    label: string;
+    text: string;
+    height: number;
+    className?: string;
+    ref?: Ref<HTMLDivElement>;
+}): import("react").JSX.Element;
+export interface PlotMargin {
+    top: number;
+    right: number;
+    bottom: number;
+}
+export interface PlotLayout {
+    /** Left edge of the plot: room for the widest y label. */
+    left: number;
+    /** The svg's width. */
+    W: number;
+    plotW: number;
+    plotH: number;
+}
+/** The plot's box inside an svg as wide as `measured` (or the fallback width where there is no layout). */
+export declare function plotLayout(measured: number, height: number, margin: PlotMargin, axisLabels: readonly string[]): PlotLayout;
+/** One horizontal gridline per tick with its label to the left. The zero line is the baseline marks grow from. */
+export declare function ValueGrid({ ticks, labels, left, right, y, }: {
+    ticks: readonly number[];
+    labels: readonly string[];
+    left: number;
+    /** The x the lines end at. */
+    right: number;
+    y: (value: number) => number;
+}): import("react").JSX.Element[];
+/** An x tick: a primary line, and a secondary one when the day (or year) changed. `at` names it for tests and probes. */
+export declare function XTickLabel({ at, x, y, primary, secondary }: {
+    at: number;
+    x: number;
+    y: number;
+    primary: string;
+    secondary: string | null;
+}): import("react").JSX.Element;
+/** The set of series keys the viewer has hidden from the legend, and the toggle that flips one. */
+export declare function useHiddenSeries(): readonly [ReadonlySet<string>, (key: string) => void];
+export declare const LEGEND_FRAME = "flex min-h-6 min-w-6 cursor-pointer items-center gap-1.5 rounded-md px-1 text-xs text-secondary hover:bg-surface-hover";
+export declare function LegendList({ label, children }: {
+    label: string;
+    children: ReactNode;
+}): import("react").JSX.Element;
+export declare function LegendItem({ id, other, children }: {
+    id: string;
+    other?: boolean;
+    children: ReactNode;
+}): import("react").JSX.Element;
+/** The colour box (or, with `className`, another shape) beside a legend name: filled while the series shows, an outline while hidden. */
+export declare function LegendSwatch({ color, swatch, off, className, }: {
+    color: string;
+    /** A CSS `background` for a swatch that is not one flat colour (a striped line); wins over `color` while the series shows. */
+    swatch?: string;
+    off: boolean;
+    className?: string;
+}): import("react").JSX.Element;
+/** The button that shows or hides one series; `name` is its accessible name. */
+export declare function LegendToggle({ name, off, onToggle, className, children, }: {
+    name: string;
+    off: boolean;
+    onToggle: () => void;
+    className?: string;
+    children: ReactNode;
+}): import("react").JSX.Element;

package/dist/types/components/chart/time-series-scale.d.ts

@@ -0,0 +1,29 @@
+export declare const MINUTE_MS = 60000;
+export declare const DAY_MS = 86400000;
+/**
+ * A value axis that starts at zero and ends on a round number at or above
+ * `max`, with about `count` intervals: steps of 1, 2 or 5 times a power of ten.
+ * No data (`max <= 0`) is a 0-to-1 axis, never a zero-height one.
+ */
+export declare function niceTicks(max: number, count?: number): {
+    ticks: number[];
+    max: number;
+};
+export interface TimeFormatters {
+    /** The label under a tick: a primary line, and a secondary line when the day (or year) changed since the last tick. */
+    tick: (ms: number, previousMs: number | null) => {
+        primary: string;
+        secondary: string | null;
+    };
+    /** The whole instant, for the tooltip and the table. */
+    full: (ms: number) => string;
+}
+/**
+ * How a bucket start reads for a bucket this wide. Under a day the time is the
+ * label and the date appears where it changes; a day or wider is labelled by
+ * its date; a month or wider by month and year. `timeZone` is passed straight
+ * to `Intl` (an unknown zone throws, loudly); undefined is the viewer's own.
+ */
+export declare function timeFormatters(bucketMs: number, locale: string, timeZone: string | undefined): TimeFormatters;
+/** The index of the bucket whose span `[start, start + bucketMs)` holds `at`, or -1. */
+export declare function bucketIndexAt(buckets: readonly number[], bucketMs: number, at: number): number;