@mithrl/design-system 0.3.0 → 0.4.1

package/dist/components/flowchart/Flowchart.d.ts

@@ -0,0 +1,250 @@
+import { type HTMLAttributes, type ReactNode } from "react";
+import { type IconGlyphComponent } from "../icon/Icon";
+import { type FlowchartGraphEdge, type FlowchartGraphNodeKind } from "./graphLayout";
+
+export type FlowchartCanvasProps = HTMLAttributes<HTMLDivElement> & {
+    /** Flow nodes and connectors, composed top to bottom. */
+    children: ReactNode;
+    /** Hides the dotted grid when the flow sits inside an already-textured surface. */
+    grid?: boolean;
+    /** Horizontal alignment of the node column. @default "center" */
+    align?: "center" | "start";
+};
+/**
+ * A static presentation surface for a vertically-connected workflow.
+ * Flowchart never owns drag, drop, or node editing: it renders an already
+ * decided pipeline so a reader can follow it top to bottom.
+ */
+export declare const FlowchartCanvas: import("react").ForwardRefExoticComponent<HTMLAttributes<HTMLDivElement> & {
+    /** Flow nodes and connectors, composed top to bottom. */
+    children: ReactNode;
+    /** Hides the dotted grid when the flow sits inside an already-textured surface. */
+    grid?: boolean;
+    /** Horizontal alignment of the node column. @default "center" */
+    align?: "center" | "start";
+} & import("react").RefAttributes<HTMLDivElement>>;
+export type FlowchartConnectorVariant = "line" | "elbow-left" | "elbow-right";
+export type FlowchartConnectorProps = Omit<HTMLAttributes<HTMLDivElement>, "children"> & {
+    /** Straight run, or an elbow that steps the flow into a branch column. */
+    variant?: FlowchartConnectorVariant;
+    /** Short branch caption such as `Yes`, `No`, or `On failure`. */
+    label?: string;
+    /** Draws the run dashed to signal a conditional or deferred path. */
+    dashed?: boolean;
+};
+/**
+ * The visual run between two flow nodes. Decorative by default; the label,
+ * when present, is the only readable content and is exposed to assistive tech.
+ */
+export declare const FlowchartConnector: import("react").ForwardRefExoticComponent<Omit<HTMLAttributes<HTMLDivElement>, "children"> & {
+    /** Straight run, or an elbow that steps the flow into a branch column. */
+    variant?: FlowchartConnectorVariant;
+    /** Short branch caption such as `Yes`, `No`, or `On failure`. */
+    label?: string;
+    /** Draws the run dashed to signal a conditional or deferred path. */
+    dashed?: boolean;
+} & import("react").RefAttributes<HTMLDivElement>>;
+export type FlowchartTriggerProps = Omit<HTMLAttributes<HTMLDivElement>, "title" | "children"> & {
+    /** Approved Lucide glyph naming the event source. */
+    icon?: IconGlyphComponent;
+    /** What starts the flow, phrased as an event. */
+    title: ReactNode;
+    /** One sentence of supporting detail about the event. */
+    description?: ReactNode;
+    /** Overrides the default `Trigger` eyebrow. */
+    eyebrow?: string;
+    /** Optional metadata slot, typically a `Tag`. */
+    trailing?: ReactNode;
+    /**
+     * Drag grip rendered at the card's leading edge. It repositions the card on
+     * the canvas; it does not reorder the flow, which stays owned by the edges.
+     */
+    handle?: ReactNode;
+};
+/** The entry node of a flow. Carries an accent left treatment. */
+export declare const FlowchartTrigger: import("react").ForwardRefExoticComponent<Omit<HTMLAttributes<HTMLDivElement>, "children" | "title"> & {
+    /** Approved Lucide glyph naming the event source. */
+    icon?: IconGlyphComponent;
+    /** What starts the flow, phrased as an event. */
+    title: ReactNode;
+    /** One sentence of supporting detail about the event. */
+    description?: ReactNode;
+    /** Overrides the default `Trigger` eyebrow. */
+    eyebrow?: string;
+    /** Optional metadata slot, typically a `Tag`. */
+    trailing?: ReactNode;
+    /**
+     * Drag grip rendered at the card's leading edge. It repositions the card on
+     * the canvas; it does not reorder the flow, which stays owned by the edges.
+     */
+    handle?: ReactNode;
+} & import("react").RefAttributes<HTMLDivElement>>;
+export type FlowchartActionProps = Omit<HTMLAttributes<HTMLDivElement>, "title"> & {
+    icon?: IconGlyphComponent;
+    /** What the step does. */
+    title: ReactNode;
+    description?: ReactNode;
+    /** Overrides the default `Action` eyebrow, e.g. `Step 2`. */
+    eyebrow?: string;
+    /** Optional metadata slot, typically a `Tag` or a duration. */
+    trailing?: ReactNode;
+    /** Extra detail rendered beneath the header. */
+    children?: ReactNode;
+    /**
+     * Drag grip rendered at the card's leading edge. It repositions the card on
+     * the canvas; it does not reorder the flow, which stays owned by the edges.
+     */
+    handle?: ReactNode;
+};
+/** A generic executed step in the flow. */
+export declare const FlowchartAction: import("react").ForwardRefExoticComponent<Omit<HTMLAttributes<HTMLDivElement>, "title"> & {
+    icon?: IconGlyphComponent;
+    /** What the step does. */
+    title: ReactNode;
+    description?: ReactNode;
+    /** Overrides the default `Action` eyebrow, e.g. `Step 2`. */
+    eyebrow?: string;
+    /** Optional metadata slot, typically a `Tag` or a duration. */
+    trailing?: ReactNode;
+    /** Extra detail rendered beneath the header. */
+    children?: ReactNode;
+    /**
+     * Drag grip rendered at the card's leading edge. It repositions the card on
+     * the canvas; it does not reorder the flow, which stays owned by the edges.
+     */
+    handle?: ReactNode;
+} & import("react").RefAttributes<HTMLDivElement>>;
+export type FlowchartClauseJoin = "and" | "or";
+export type FlowchartConditionClause = {
+    /** The measured entity, e.g. `run QC score`. */
+    entity: string;
+    /** The comparison, e.g. `is below`. */
+    operator: string;
+    /** The compared value, e.g. `0.8`. */
+    value: string;
+    /**
+     * How this clause joins the previous one. Ignored on the first clause.
+     * @default "and"
+     */
+    join?: FlowchartClauseJoin;
+};
+export type FlowchartConditionProps = Omit<HTMLAttributes<HTMLDivElement>, "title"> & {
+    icon?: IconGlyphComponent;
+    /** Short name for the decision, e.g. `Route low-quality runs`. */
+    title: ReactNode;
+    /** The clauses evaluated together, rendered as entity / operator / value chips. */
+    clauses: readonly FlowchartConditionClause[];
+    /** Overrides the default `If / Else` eyebrow. */
+    eyebrow?: string;
+    /** Caption for the true outcome. */
+    thenLabel?: string;
+    /** Caption for the false outcome. Omit for an if-only condition. */
+    elseLabel?: string;
+    /** Optional metadata slot, typically a `Tag`. */
+    trailing?: ReactNode;
+    /**
+     * Drag grip rendered at the card's leading edge. It repositions the card on
+     * the canvas; it does not reorder the flow, which stays owned by the edges.
+     */
+    handle?: ReactNode;
+};
+/** A branching If/Else node whose clauses read as inline chips. */
+export declare const FlowchartCondition: import("react").ForwardRefExoticComponent<Omit<HTMLAttributes<HTMLDivElement>, "title"> & {
+    icon?: IconGlyphComponent;
+    /** Short name for the decision, e.g. `Route low-quality runs`. */
+    title: ReactNode;
+    /** The clauses evaluated together, rendered as entity / operator / value chips. */
+    clauses: readonly FlowchartConditionClause[];
+    /** Overrides the default `If / Else` eyebrow. */
+    eyebrow?: string;
+    /** Caption for the true outcome. */
+    thenLabel?: string;
+    /** Caption for the false outcome. Omit for an if-only condition. */
+    elseLabel?: string;
+    /** Optional metadata slot, typically a `Tag`. */
+    trailing?: ReactNode;
+    /**
+     * Drag grip rendered at the card's leading edge. It repositions the card on
+     * the canvas; it does not reorder the flow, which stays owned by the edges.
+     */
+    handle?: ReactNode;
+} & import("react").RefAttributes<HTMLDivElement>>;
+type FlowchartGraphNodeBase = {
+    id: string;
+    title: ReactNode;
+    description?: ReactNode;
+    eyebrow?: string;
+    icon?: IconGlyphComponent;
+};
+/**
+ * A node in a graph-laid-out flowchart.
+ *
+ * Discriminated on `kind` so that `clauses` is *required* for a condition and
+ * unavailable on the other kinds. `FlowchartCondition` throws without at least
+ * one clause, so a condition that omits them has no valid rendering — this
+ * turns that into a compile error instead of silently drawing the branch as an
+ * ordinary action step.
+ */
+export type FlowchartGraphNode = (FlowchartGraphNodeBase & {
+    kind: Exclude<FlowchartGraphNodeKind, "condition">;
+    clauses?: never;
+}) | (FlowchartGraphNodeBase & {
+    kind: "condition";
+    clauses: readonly FlowchartConditionClause[];
+});
+export type FlowchartGraphProps = Omit<HTMLAttributes<HTMLDivElement>, "children"> & {
+    nodes: readonly FlowchartGraphNode[];
+    edges: readonly FlowchartGraphEdge[];
+    /** Hides the dotted grid when the flow sits inside an already-textured surface. */
+    grid?: boolean;
+    /** Widest layer the layout will accept. @default 3 */
+    maxLanes?: number;
+    /** Largest graph the layout will accept. @default 12 */
+    maxNodes?: number;
+    /** Rendered when the graph is outside the supported layout bound. */
+    fallback?: ReactNode;
+    /**
+     * Gives every card the reorder grip and lets a reader move it around the
+     * canvas. The grip is a real button, so pointer drag has a full keyboard
+     * equivalent: arrow keys nudge by 8px, `Shift` + arrow by 32px, and `Escape`
+     * returns the card to its laid-out position — cancelling an in-flight pointer
+     * drag as well as undoing keyboard nudges. Positions are ephemeral: they live
+     * for the life of the mount and are never persisted, because the graph itself
+     * is still the source of truth.
+     */
+    interactive?: boolean;
+};
+/**
+ * A bounded directed-acyclic flow: parallel branches sit side by side as lanes
+ * in the same layer, and lanes rejoin wherever a node has more than one
+ * incoming edge. Layout is automatic and presentation-only — the graph is
+ * already decided, `FlowchartGraph` only draws it.
+ *
+ * Supports at most `FLOWCHART_GRAPH_MAX_NODES` (12) nodes and
+ * `FLOWCHART_GRAPH_MAX_LANES` (3) parallel lanes per layer. Outside that
+ * bound it renders `fallback` (or nothing), so a consumer can present the flow
+ * some other way rather than show an unreadable tangle.
+ */
+export declare const FlowchartGraph: import("react").ForwardRefExoticComponent<Omit<HTMLAttributes<HTMLDivElement>, "children"> & {
+    nodes: readonly FlowchartGraphNode[];
+    edges: readonly FlowchartGraphEdge[];
+    /** Hides the dotted grid when the flow sits inside an already-textured surface. */
+    grid?: boolean;
+    /** Widest layer the layout will accept. @default 3 */
+    maxLanes?: number;
+    /** Largest graph the layout will accept. @default 12 */
+    maxNodes?: number;
+    /** Rendered when the graph is outside the supported layout bound. */
+    fallback?: ReactNode;
+    /**
+     * Gives every card the reorder grip and lets a reader move it around the
+     * canvas. The grip is a real button, so pointer drag has a full keyboard
+     * equivalent: arrow keys nudge by 8px, `Shift` + arrow by 32px, and `Escape`
+     * returns the card to its laid-out position — cancelling an in-flight pointer
+     * drag as well as undoing keyboard nudges. Positions are ephemeral: they live
+     * for the life of the mount and are never persisted, because the graph itself
+     * is still the source of truth.
+     */
+    interactive?: boolean;
+} & import("react").RefAttributes<HTMLDivElement>>;
+export {};

package/dist/components/flowchart/graphLayout.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Layered layout for the small directed acyclic graphs `FlowchartGraph`
+ * renders. The layout is deliberately bounded: past these limits a readable
+ * automatic layout stops being possible in a reading surface, and consumers
+ * are expected to fall back to their own presentation.
+ */
+export declare const FLOWCHART_GRAPH_MAX_NODES = 12;
+export declare const FLOWCHART_GRAPH_MAX_LANES = 3;
+export type FlowchartGraphNodeKind = "trigger" | "action" | "condition";
+export type FlowchartGraphEdge = {
+    from: string;
+    to: string;
+    /** Short caption drawn on the run, e.g. `Yes` or `on failure`. */
+    label?: string;
+    /** Draws the run dashed to signal a conditional or indirect path. */
+    dashed?: boolean;
+};
+export type FlowchartGraphLayout = {
+    /** Node ids grouped into layers, first layer first. */
+    layers: readonly (readonly string[])[];
+};
+type LayoutInput = {
+    ids: readonly string[];
+    edges: readonly FlowchartGraphEdge[];
+    maxNodes?: number;
+    maxLanes?: number;
+};
+/**
+ * Assigns every node to a layer using longest-path layering, so an edge always
+ * runs from a lower layer to a higher one and merges land on a shared layer.
+ * Returns `null` when the graph is outside the supported bound: unknown edge
+ * endpoints, a cycle, too many nodes, or a layer wider than the lane limit.
+ */
+export declare function layoutFlowchartGraph({ ids, edges, maxNodes, maxLanes, }: LayoutInput): FlowchartGraphLayout | null;
+export {};

package/dist/components/global-app-bar/GlobalAppBar.d.ts

@@ -1,4 +1,4 @@
-import { type AnchorHTMLAttributes, type ButtonHTMLAttributes, type HTMLAttributes, type MouseEventHandler, type ReactElement } from "react";
+import { type AnchorHTMLAttributes, type ButtonHTMLAttributes, type HTMLAttributes, type MouseEventHandler, type ReactElement, type ReactNode } from "react";
 import { type AccountMenuProps } from "../account-menu/AccountMenu";
 import { type DropdownMenuProps } from "../dropdown-menu/DropdownMenu";
 import { type ThemeMode } from "../switch/Switch";
@@ -59,6 +59,11 @@ export type GlobalAppBarProps = Omit<HTMLAttributes<HTMLElement>, "children"> &
     onAccountMenuOpenChange?: DropdownMenuProps["onOpenChange"];
     /** Additional native attributes for the account-menu button. */
     accountButtonProps?: AccountButtonProps;
+    /**
+     * Product-wide utility controls rendered before Theme Switch. Use for
+     * persistent utilities such as Notifications, never page-specific actions.
+     */
+    utilityActions?: ReactNode;
     /**
      * Workspace-only App Shell controls. Each control keeps its own semantics;
      * Global App Bar owns only their approved order and alignment.
@@ -70,9 +75,9 @@ export type GlobalAppBarProps = Omit<HTMLAttributes<HTMLElement>, "children"> &
     };
 };
 /**
- * Persistent application anchor. Home keeps the minimal brand, theme, and
- * account contract; Workspace adds structural panel controls and project
- * context without introducing a second App Bar component.
+ * Persistent application anchor. Home keeps brand, optional product-wide
+ * utilities, theme, and account; Workspace adds structural panel controls and
+ * project context without introducing a second App Bar component.
  */
 export declare const GlobalAppBar: import("react").ForwardRefExoticComponent<Omit<HTMLAttributes<HTMLElement>, "children"> & {
     /** Home destination used by the official Mithrl brand action. */
@@ -105,6 +110,11 @@ export declare const GlobalAppBar: import("react").ForwardRefExoticComponent<Omi
     onAccountMenuOpenChange?: DropdownMenuProps["onOpenChange"];
     /** Additional native attributes for the account-menu button. */
     accountButtonProps?: AccountButtonProps;
+    /**
+     * Product-wide utility controls rendered before Theme Switch. Use for
+     * persistent utilities such as Notifications, never page-specific actions.
+     */
+    utilityActions?: ReactNode;
     /**
      * Workspace-only App Shell controls. Each control keeps its own semantics;
      * Global App Bar owns only their approved order and alignment.

package/dist/components/icon-swap/IconSwap.d.ts

@@ -0,0 +1,30 @@
+import { type HTMLAttributes } from "react";
+import { type IconGlyphComponent, type IconSize } from "../icon/Icon";
+
+export type IconSwapProps = Omit<HTMLAttributes<HTMLSpanElement>, "aria-label" | "aria-hidden" | "children" | "role"> & {
+    /**
+     * Approved glyph to display. Changing the component identity swaps the
+     * glyph in place; the caller never manages two children.
+     */
+    icon: IconGlyphComponent;
+    /** Icon Foundation size token. Matches the `Icon` contract exactly. */
+    size?: IconSize;
+};
+/**
+ * Cross-fades two glyphs through one slot.
+ *
+ * IconSwap is a single-slot component: pass one `icon`, and whenever that
+ * component identity changes the outgoing glyph fades out while the incoming
+ * glyph fades in over it. Both share one grid cell so the slot never reflows.
+ *
+ * Motion — `--motion-duration-standard` on `--motion-easing-standard`, with
+ * the incoming glyph rising from `--motion-scale-enter` and
+ * `--motion-blur-soft` to rest. Under `prefers-reduced-motion: reduce` the
+ * scale and blur are dropped and the two glyphs cross-fade on opacity alone at
+ * `--motion-duration-fast`.
+ *
+ * Boundary — the swap is decorative. IconSwap announces nothing: the root and
+ * every glyph are hidden from assistive technology, exactly as a bare `Icon`
+ * without a `label` is. The accessible name belongs to the owning control.
+ */
+export declare function IconSwap({ icon, size, className, ...props }: IconSwapProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/insight-cards/InsightCards.d.ts

@@ -0,0 +1,97 @@
+import { type HTMLAttributes, type ReactNode } from "react";
+
+/** Direction of a change, mapped to semantic color. */
+export type InsightTone = "neutral" | "success" | "danger";
+/**
+ * One run of an insight sentence. `text` reads as prose, `entity` names a
+ * cohort, gene, batch, or assay, and `metric` carries a figure or delta.
+ */
+export type InsightSegment = {
+    kind: "text";
+    text: string;
+} | {
+    kind: "entity";
+    text: string;
+} | {
+    kind: "metric";
+    text: string;
+    tone?: InsightTone;
+};
+/** A compact before/after row rendered beneath the sentence. */
+export type InsightComparison = {
+    /** What is being compared, e.g. `Median TPM, responders`. */
+    label: string;
+    /** Signed relative change, already formatted, e.g. `+18.4%`. */
+    delta: string;
+    /** Absolute value, already formatted, e.g. `412.6 TPM`. */
+    value: string;
+    /** Semantic direction. @default "neutral" */
+    tone?: InsightTone;
+};
+/** A single plotted observation for the embedded mini chart. */
+export type InsightChartPoint = {
+    /** Axis label for the scrub readout, e.g. `Day 14`. */
+    label: string;
+    /** Plotted magnitude in the series' own units. */
+    value: number;
+};
+export type InsightChart = {
+    points: readonly InsightChartPoint[];
+    /** Unit suffix shown in the scrub readout, e.g. `TPM`. */
+    unit?: string;
+    /** Accessible summary of the series. Required — the SVG carries no text. */
+    ariaLabel: string;
+};
+export type InsightFollowUp = {
+    /** The suggested next question, phrased as the agent would ask it. */
+    label: string;
+    /** Stable identifier handed back to `onFollowUpSelect`. */
+    id?: string;
+};
+export type Insight = {
+    /** Stable identity for the page. */
+    id: string;
+    /** Short headline for the insight. */
+    title: string;
+    /** The insight itself, composed of prose, entity, and metric runs. */
+    sentence: readonly InsightSegment[];
+    /** Optional comparison rows. */
+    comparisons?: readonly InsightComparison[];
+    /** Optional embedded trend chart. */
+    chart?: InsightChart;
+    /** Optional suggested follow-up rendered in the footer. */
+    followUp?: InsightFollowUp;
+};
+export type InsightCardsProps = Omit<HTMLAttributes<HTMLElement>, "children" | "onSelect"> & {
+    /** The pages, in reading order. At least one is required. */
+    insights: readonly Insight[];
+    /** Header title. @default "Insights" */
+    heading?: ReactNode;
+    /** Controlled page index. */
+    page?: number;
+    /** Initial page index for uncontrolled use. @default 0 */
+    defaultPage?: number;
+    /** Called with the next index whenever the page changes. */
+    onPageChange?: (page: number) => void;
+    /** Called when the footer follow-up chip is activated. */
+    onFollowUpSelect?: (followUp: InsightFollowUp, insight: Insight) => void;
+};
+/**
+ * A paged carousel of agent-authored insights. Each page states one finding
+ * in a sentence built from entity and metric chips, supports it with
+ * comparison rows and a mini trend chart, and offers one follow-up question.
+ */
+export declare const InsightCards: import("react").ForwardRefExoticComponent<Omit<HTMLAttributes<HTMLElement>, "children" | "onSelect"> & {
+    /** The pages, in reading order. At least one is required. */
+    insights: readonly Insight[];
+    /** Header title. @default "Insights" */
+    heading?: ReactNode;
+    /** Controlled page index. */
+    page?: number;
+    /** Initial page index for uncontrolled use. @default 0 */
+    defaultPage?: number;
+    /** Called with the next index whenever the page changes. */
+    onPageChange?: (page: number) => void;
+    /** Called when the footer follow-up chip is activated. */
+    onFollowUpSelect?: (followUp: InsightFollowUp, insight: Insight) => void;
+} & import("react").RefAttributes<HTMLElement>>;

package/dist/components/number-flow/NumberFlow.d.ts

@@ -0,0 +1,93 @@
+import { type CSSProperties } from "react";
+
+/**
+ * Milliseconds one digit spends rolling. Mirrors `--motion-duration-moderate`;
+ * the CSS reads the token directly and only falls back to this number when the
+ * caller overrides `rollDuration`.
+ */
+export declare const NUMBER_FLOW_DEFAULT_DURATION_MS = 220;
+/** Milliseconds each successive cell waits before it starts rolling. */
+export declare const NUMBER_FLOW_DEFAULT_STAGGER_MS = 18;
+export type NumberFlowElement = "span" | "div" | "p" | "strong" | "em";
+export type NumberFlowSize = "small" | "medium" | "large";
+export interface NumberFlowProps {
+    /** The number to display. Changing it rolls the digits that differ. */
+    value: number;
+    /** `Intl.NumberFormat` options. Changing them reformats and animates. */
+    format?: Intl.NumberFormatOptions;
+    /** BCP 47 locale(s) for formatting. Defaults to the runtime locale. */
+    locale?: string | string[];
+    /**
+     * Height of the clipped roll window, as a multiple of the inherited line box.
+     * This is the only size NumberFlow owns — it never sets a font property.
+     * @default "medium"
+     */
+    size?: NumberFlowSize;
+    /** Host element. @default "span" */
+    as?: NumberFlowElement;
+    /** Per-digit delay, in milliseconds. @default 18 */
+    stagger?: number;
+    /** Roll duration, in milliseconds. @default `--motion-duration-moderate` */
+    rollDuration?: number;
+    className?: string;
+    style?: CSSProperties;
+}
+export type NumberFlowDirection = "up" | "down";
+export type NumberFlowCell = {
+    /** Glyph shown once the cell settles. */
+    char: string;
+    /** Glyph leaving the window, or `null` when the cell is new or unchanged. */
+    previous: string | null;
+    /** Digit-to-digit change: a clipped vertical roll. */
+    roll: boolean;
+    /** Any other change (separator, sign, or a brand new place): a crossfade. */
+    fade: boolean;
+    /** Roll direction, taken from the sign of the value delta. */
+    direction: NumberFlowDirection;
+};
+/**
+ * Cells are aligned from the RIGHT, not the left: in a number the units column
+ * is the fixed point, so 99 -> 100 must roll the two nines against the new
+ * tens and units rather than sliding every place one column over.
+ *
+ * Only cells whose glyph actually changed move — the same rule FlapText
+ * applies to characters. A digit replacing a digit rolls; anything else
+ * (a separator appearing, a sign flipping, a brand new leading place) is a
+ * quiet crossfade, because rolling a comma into a digit reads as noise.
+ */
+export declare function numberFlowCells(previous: string, next: string, direction?: NumberFlowDirection): NumberFlowCell[];
+/**
+ * A number that resolves instead of blinking.
+ *
+ * Each character of the formatted value is its own cell. When `value` changes,
+ * only the cells whose glyph differs move: a digit rolls vertically through a
+ * clipped window — the outgoing glyph leaves through one edge as the incoming
+ * one arrives from the other, softened by `--motion-blur-soft` — while
+ * separators and new leading places simply crossfade. Cells are staggered left
+ * to right so the least significant digit is the last to settle.
+ *
+ * This is a short roll, not a slot machine. The spinning-counter recipe's
+ * multi-revolution 0-9 strip, its directional SVG blur filter and its masked
+ * window edges are all deliberately absent: a scientific workspace wants a
+ * number that has clearly *changed*, not one that celebrates.
+ *
+ * Sharpness: settled cells carry `transform: none` exactly — never an identity
+ * matrix — `will-change` is present only while a cell is in flight, no scale is
+ * ever applied, and the component sets no font property, so text metrics are
+ * the caller's. `font-variant-numeric: tabular-nums` keeps the box from
+ * wobbling as digits change width.
+ *
+ * Accessibility: cells are `aria-hidden`, the host carries the formatted value
+ * as `aria-label`, and a visually hidden polite live region announces one clean
+ * string.
+ *
+ * Reduced motion: no roll and no blur — the value swaps instantly behind a
+ * `--motion-duration-fast` opacity crossfade.
+ */
+export declare function NumberFlow({ value, format, locale, size, as, stagger, rollDuration, className, style, }: NumberFlowProps): import("react").DetailedReactHTMLElement<{
+    className: string;
+    style: CSSProperties | undefined;
+    "aria-label": string;
+    "data-size": NumberFlowSize;
+    "data-animating": string;
+}, HTMLElement>;

package/dist/components/pixel-loader/PixelLoader.d.ts

@@ -0,0 +1,94 @@
+import type { CSSProperties } from "react";
+
+/**
+ * The pixel grid is always square. Five columns is the smallest grid that still
+ * reads as a *pattern* rather than a row of dots at 16px, and stays crisp at 50.
+ */
+export declare const PIXEL_LOADER_GRID = 5;
+/**
+ * Motion patterns. Each is a distinct reading of the same grid, not a speed
+ * variation of one loop:
+ *
+ * - `dots`   — cells pulse in a scattered, non-repeating rhythm.
+ * - `orbit`  — a lit cluster travels around the perimeter; the core stays dim.
+ * - `drive`  — a column sweeps left to right, like a plate reader head.
+ * - `surfer` — a diagonal wavefront crosses the grid corner to corner.
+ */
+export declare const pixelLoaderVariants: readonly ["dots", "orbit", "drive", "surfer"];
+export type PixelLoaderVariant = (typeof pixelLoaderVariants)[number];
+/**
+ * DS size scale, deliberately identical to `StatusOrbSize` so a running-state
+ * indicator can be swapped between the two without touching layout.
+ */
+export type PixelLoaderSize = "small" | "default" | "medium" | "large";
+/**
+ * Where one cell sits in the loop, as a fraction of the cycle in `[0, 1)`.
+ * `null` means the cell never lights for this variant and stays at rest — the
+ * dim core of `orbit`, for instance.
+ *
+ * Exported so the phase table can be asserted directly rather than inferred
+ * from rendered CSS.
+ */
+export declare function pixelLoaderCellPhase(variant: PixelLoaderVariant, x: number, y: number, grid?: number): number | null;
+/**
+ * Accessible name used when the caller supplies none, or supplies one that is
+ * blank once trimmed. `role="img"` must always resolve to a name.
+ */
+export declare const PIXEL_LOADER_DEFAULT_LABEL = "Loading";
+/**
+ * A cell's `animation-delay`, as a multiple of the cycle. Mirrors the `calc()`
+ * in `pixel-loader.css` exactly, and is asserted against that stylesheet in the
+ * tests so the two cannot drift.
+ *
+ * Always negative, so the loop is in flight on the first painted frame. The
+ * shape is `phase - 1`, not `-phase`: a negative delay advances the playhead by
+ * its own magnitude, so `-phase` would light the *highest* phase first and run
+ * every pattern backwards.
+ */
+export declare function pixelLoaderCellDelay(phase: number): number;
+/**
+ * Which cells are at peak brightness at wall-clock time `t`, expressed as a
+ * fraction of one cycle.
+ *
+ * This resolves the same delay/duration arithmetic the browser does — playhead
+ * `= t - delay`, brightest when the playhead sits on the keyframe's peak — so
+ * the *rendered travel direction* can be asserted directly rather than inferred
+ * from the phase table. Returned in row-major cell-index order.
+ */
+export declare function pixelLoaderLitCellsAt(variant: PixelLoaderVariant, t: number, grid?: number): number[];
+export interface PixelLoaderProps {
+    /** Which pattern the grid animates. @default "dots" */
+    variant?: PixelLoaderVariant;
+    /** DS size scale. @default "medium" (30px) */
+    size?: PixelLoaderSize;
+    /** One full pass of the pattern, in milliseconds. @default `--motion-duration-ambient` */
+    cycle?: number;
+    /** Sweep a soft highlight across the grid on top of the pattern. @default false */
+    shimmer?: boolean;
+    /** Freeze the pattern on its resting frame. @default false */
+    paused?: boolean;
+    /**
+     * Accessible name. Trimmed; a blank or whitespace-only value falls back to
+     * the default rather than leaving `role="img"` unnamed. @default "Loading"
+     */
+    "aria-label"?: string;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * Pixel-grid loading indicator.
+ *
+ * A 5×5 grid of cells lights in a variant-specific rhythm. Every cell carries a
+ * phase offset computed once at render; the animation itself is a single CSS
+ * keyframe on the compositor (opacity and transform only), so a page full of
+ * these costs no JavaScript per frame.
+ *
+ * Colour comes entirely from the brand ramp, mixed against `transparent`, so
+ * both themes are correct without a theme prop.
+ *
+ * Reduced motion: no travel. Cells settle into a static readout of their phase
+ * and the whole grid breathes on a slow, low-amplitude opacity pulse.
+ *
+ * This component never displays elapsed time.
+ */
+export declare function PixelLoader({ variant, size, cycle, shimmer, paused, "aria-label": ariaLabel, className, style, }: PixelLoaderProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/progress-indicator/ProgressIndicator.d.ts

@@ -7,8 +7,16 @@ export declare const progressIndicatorVariants: (props?: ({
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 export type ProgressIndicatorSize = NonNullable<VariantProps<typeof progressIndicatorVariants>["size"]>;
 export type ProgressIndicatorTone = NonNullable<VariantProps<typeof progressIndicatorVariants>["tone"]>;
+/**
+ * Loading is the default so every existing usage keeps its current behavior.
+ * Done resolves the same indicator into a drawn completion check.
+ */
+export type ProgressIndicatorState = "loading" | "done";
 type RestrictedProgressIndicatorAttribute = "aria-atomic" | "aria-busy" | "aria-hidden" | "aria-label" | "aria-live" | "children" | "onClick" | "onDoubleClick" | "onKeyDown" | "onKeyUp" | "role" | "tabIndex";
-type ProgressIndicatorBaseProps = Omit<HTMLAttributes<HTMLSpanElement>, RestrictedProgressIndicatorAttribute> & VariantProps<typeof progressIndicatorVariants>;
+type ProgressIndicatorBaseProps = Omit<HTMLAttributes<HTMLSpanElement>, RestrictedProgressIndicatorAttribute> & VariantProps<typeof progressIndicatorVariants> & {
+    /** Completion state. Defaults to `"loading"`. */
+    state?: ProgressIndicatorState;
+};
 type InformativeProgressIndicatorProps = {
     /** Concise accessible name announced through the status live region. */
     label: string;