@mithrl/design-system 0.4.0 → 0.4.1

package/dist/components/approval-card/ApprovalCard.d.ts

@@ -1,70 +1,61 @@
-import { type HTMLAttributes, type ReactNode } from "react";
+import { type FormHTMLAttributes } from "react";
 
-/** One selectable answer on an approval question. */
-export interface ApprovalOption {
+export type ApprovalCardMode = "single" | "multi";
+export type ApprovalCardOption = {
     id: string;
-    label: string;
-    /** Short clarifier shown under the label. Keep it to one plain sentence. */
-    description?: string;
-}
-/** A single question the agent asks before it acts. */
-export interface ApprovalQuestion {
+    title: string;
+    subtitle?: string;
+    disabled?: boolean;
+};
+export type ApprovalCardQuestion = {
     id: string;
-    /** The question itself, phrased the way a colleague would ask it. */
-    prompt: string;
-    /** Optional context sentence shown under the prompt. */
-    helpText?: ReactNode;
-    options: ApprovalOption[];
-    /** Allow more than one option. Defaults to single choice. */
-    multiSelect?: boolean;
-}
-/** Selected option ids keyed by question id. */
-export type ApprovalAnswers = Record<string, string[]>;
-type RestrictedApprovalCardAttribute = "children" | "onSubmit" | "role";
-export type ApprovalCardProps = Omit<HTMLAttributes<HTMLElement>, RestrictedApprovalCardAttribute> & {
-    /** Ordered questions. The card pages through them one at a time. */
-    questions: ApprovalQuestion[];
-    /** Optional heading above the question, e.g. the run the agent is planning. */
-    eyebrow?: ReactNode;
-    /** Controlled answers. Pair with `onAnswersChange`. */
-    answers?: ApprovalAnswers;
-    /** Initial answers when the card owns its own state. */
-    defaultAnswers?: ApprovalAnswers;
-    onAnswersChange?: (answers: ApprovalAnswers) => void;
-    /** Fired once the last question is confirmed. */
-    onComplete?: (answers: ApprovalAnswers) => void;
-    /** Fired when the scientist declines to answer and lets the agent decide. */
-    onSkip?: (answers: ApprovalAnswers) => void;
-    skipLabel?: string;
-    continueLabel?: string;
-    /** Label for the final page's primary action. */
-    completeLabel?: string;
-    /** Require a selection before the primary action enables. @default true */
-    requireAnswer?: boolean;
+    title: string;
+    mode: ApprovalCardMode;
+    options: readonly ApprovalCardOption[];
+};
+export type ApprovalCardAnswer = {
+    selectedOptionIds: readonly string[];
+    customValue: string;
+};
+export type ApprovalCardNavigationReason = "previous" | "next" | "continue" | "auto";
+export type ApprovalCardLabels = {
+    customAnswer: string;
+    previousQuestion: string;
+    nextQuestion: string;
+    skip: string;
+    continue: string;
+    submit: string;
+    submitting: string;
+};
+type NativeApprovalCardProps = Omit<FormHTMLAttributes<HTMLFormElement>, "children" | "onSubmit">;
+export type ApprovalCardProps = NativeApprovalCardProps & {
+    questions: readonly ApprovalCardQuestion[];
+    activeQuestionId: string;
+    answers: Readonly<Record<string, ApprovalCardAnswer | undefined>>;
+    onAnswerChange: (questionId: string, answer: ApprovalCardAnswer) => void;
+    onActiveQuestionChange: (questionId: string, reason: ApprovalCardNavigationReason) => void;
+    onSubmit: (answers: Readonly<Record<string, ApprovalCardAnswer | undefined>>) => void;
+    onSkip?: (questionId: string) => void;
+    error?: string;
+    submitting?: boolean;
+    disabled?: boolean;
+    showSkip?: boolean;
+    autoAdvanceSingle?: boolean;
+    labels?: Partial<ApprovalCardLabels>;
 };
-/**
- * Human-in-the-loop approval. The agent pauses, asks what it should do, and
- * waits: one question per page, a clear way out, and no hidden defaults.
- */
-export declare const ApprovalCard: import("react").ForwardRefExoticComponent<Omit<HTMLAttributes<HTMLElement>, RestrictedApprovalCardAttribute> & {
-    /** Ordered questions. The card pages through them one at a time. */
-    questions: ApprovalQuestion[];
-    /** Optional heading above the question, e.g. the run the agent is planning. */
-    eyebrow?: ReactNode;
-    /** Controlled answers. Pair with `onAnswersChange`. */
-    answers?: ApprovalAnswers;
-    /** Initial answers when the card owns its own state. */
-    defaultAnswers?: ApprovalAnswers;
-    onAnswersChange?: (answers: ApprovalAnswers) => void;
-    /** Fired once the last question is confirmed. */
-    onComplete?: (answers: ApprovalAnswers) => void;
-    /** Fired when the scientist declines to answer and lets the agent decide. */
-    onSkip?: (answers: ApprovalAnswers) => void;
-    skipLabel?: string;
-    continueLabel?: string;
-    /** Label for the final page's primary action. */
-    completeLabel?: string;
-    /** Require a selection before the primary action enables. @default true */
-    requireAnswer?: boolean;
-} & import("react").RefAttributes<HTMLElement>>;
+export declare const ApprovalCard: import("react").ForwardRefExoticComponent<NativeApprovalCardProps & {
+    questions: readonly ApprovalCardQuestion[];
+    activeQuestionId: string;
+    answers: Readonly<Record<string, ApprovalCardAnswer | undefined>>;
+    onAnswerChange: (questionId: string, answer: ApprovalCardAnswer) => void;
+    onActiveQuestionChange: (questionId: string, reason: ApprovalCardNavigationReason) => void;
+    onSubmit: (answers: Readonly<Record<string, ApprovalCardAnswer | undefined>>) => void;
+    onSkip?: (questionId: string) => void;
+    error?: string;
+    submitting?: boolean;
+    disabled?: boolean;
+    showSkip?: boolean;
+    autoAdvanceSingle?: boolean;
+    labels?: Partial<ApprovalCardLabels>;
+} & import("react").RefAttributes<HTMLFormElement>>;
 export {};

package/dist/components/command-search/CommandSearch.d.ts

@@ -13,6 +13,22 @@ export type CommandSearchItem = {
     onSelect?: (item: CommandSearchItem) => void;
     /** Removes the item from keyboard navigation and selection. */
     disabled?: boolean;
+    /**
+     * Opaque consumer payload, carried untouched through selection and
+     * `renderItem`. CommandSearch never reads it — it exists so a caller does not
+     * have to keep a parallel id-to-record map just to draw an icon or route a
+     * command.
+     */
+    data?: unknown;
+};
+/** State handed to `renderItem` for one row. */
+export type CommandSearchItemState = {
+    /** This row currently carries the roving highlight. */
+    active: boolean;
+    /** This row is not selectable and is skipped by keyboard navigation. */
+    disabled: boolean;
+    /** The live query, for a consumer highlighting its own text. */
+    query: string;
 };
 export type CommandSearchProps = Omit<HTMLAttributes<HTMLDivElement>, "children" | "onSelect"> & {
     items: readonly CommandSearchItem[];
@@ -31,11 +47,38 @@ export type CommandSearchProps = Omit<HTMLAttributes<HTMLDivElement>, "children"
     grouped?: boolean;
     /** Secondary line shown under the empty-state title. */
     emptyHint?: ReactNode;
+    /**
+     * Run the built-in label/group/hint substring filter. @default true
+     *
+     * Set `false` when the caller already filtered — an alias-aware catalog or a
+     * server content search, say. Every item then renders exactly as supplied
+     * and nothing is hidden, so a result that matched on something CommandSearch
+     * cannot see (an alias, a synonym, document body text) still appears. Match
+     * highlighting is unaffected: a label that happens to contain the query is
+     * still marked, and one that does not simply renders plain.
+     */
+    filter?: boolean;
+    /**
+     * Replaces the content of a row — icon, label, status, shortcut, whatever the
+     * surface needs. CommandSearch keeps ownership of the listbox and option
+     * semantics around it: ids, `role`, `aria-selected`, active handling, pointer
+     * and click wiring, and disabled skipping are all unchanged, so a custom row
+     * cannot break keyboard navigation.
+     *
+     * Default row content (marked label plus hint) is used when this is omitted.
+     */
+    renderItem?: (item: CommandSearchItem, state: CommandSearchItemState) => ReactNode;
 };
 /**
  * A command palette search surface. CommandSearch renders inline as an
  * embedded panel and can be composed inside a Dialog by the consumer; it owns
  * filtering, match highlighting, and roving keyboard selection only.
+ *
+ * Both halves of that are optional. A surface whose catalog already knows about
+ * aliases, or whose results come back from a server search, passes
+ * `filter={false}` and keeps the listbox semantics without the second,
+ * narrower filter running behind it. A surface needing richer rows than
+ * label-plus-hint passes `renderItem` and keeps the keyboard model.
  */
 export declare const CommandSearch: import("react").ForwardRefExoticComponent<Omit<HTMLAttributes<HTMLDivElement>, "children" | "onSelect"> & {
     items: readonly CommandSearchItem[];
@@ -54,4 +97,25 @@ export declare const CommandSearch: import("react").ForwardRefExoticComponent<Om
     grouped?: boolean;
     /** Secondary line shown under the empty-state title. */
     emptyHint?: ReactNode;
+    /**
+     * Run the built-in label/group/hint substring filter. @default true
+     *
+     * Set `false` when the caller already filtered — an alias-aware catalog or a
+     * server content search, say. Every item then renders exactly as supplied
+     * and nothing is hidden, so a result that matched on something CommandSearch
+     * cannot see (an alias, a synonym, document body text) still appears. Match
+     * highlighting is unaffected: a label that happens to contain the query is
+     * still marked, and one that does not simply renders plain.
+     */
+    filter?: boolean;
+    /**
+     * Replaces the content of a row — icon, label, status, shortcut, whatever the
+     * surface needs. CommandSearch keeps ownership of the listbox and option
+     * semantics around it: ids, `role`, `aria-selected`, active handling, pointer
+     * and click wiring, and disabled skipping are all unchanged, so a custom row
+     * cannot break keyboard navigation.
+     *
+     * Default row content (marked label plus hint) is used when this is omitted.
+     */
+    renderItem?: (item: CommandSearchItem, state: CommandSearchItemState) => ReactNode;
 } & import("react").RefAttributes<HTMLDivElement>>;

package/dist/components/dot-field/DotField.d.ts

@@ -0,0 +1,102 @@
+import { type CSSProperties, type RefObject } from "react";
+
+/**
+ * A plain rectangle in the field's own coordinate space — CSS pixels measured
+ * from the top-left of the canvas, not from the viewport. Stored as a plain
+ * object rather than a `DOMRect` so the exclusion maths can be tested without
+ * a DOM.
+ */
+export interface DotFieldRect {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+}
+/**
+ * Spotlight falloff at `distance` from the pointer, in `[0, 1]`.
+ *
+ * Quadratic rather than linear: the brightened region reads as a soft pool of
+ * light with no visible rim, because the derivative goes to zero at the edge.
+ * `0` at and beyond `radius`, `1` exactly under the pointer.
+ *
+ * A non-positive radius disables the spotlight entirely rather than dividing
+ * by zero.
+ */
+export declare function dotFieldFalloff(distance: number, radius: number): number;
+/** Grow a rectangle equally on all sides. */
+export declare function dotFieldInflateRect(rect: DotFieldRect, padding: number): DotFieldRect;
+/**
+ * Shortest distance from a point to a rectangle. Zero when the point is inside
+ * or on the boundary.
+ */
+export declare function dotFieldDistanceToRect(x: number, y: number, rect: DotFieldRect): number;
+/**
+ * How much of a dot survives the exclusion halo, in `[0, 1]`.
+ *
+ * `0` anywhere inside an already-inflated rect — no dot is drawn at all — then
+ * a linear ramp back to `1` over `feather` pixels outside it, so the halo has
+ * no hard cut. With several rects the smallest value wins, which is what makes
+ * overlapping halos merge into one hole instead of cancelling each other out.
+ *
+ * Rects are expected pre-inflated; `dotFieldInflateRect` does that separately
+ * so the padding is applied once per layout rather than once per dot.
+ */
+export declare function dotFieldExclusionAlpha(x: number, y: number, rects: readonly DotFieldRect[], feather: number): number;
+export interface DotFieldProps {
+    /** Lattice pitch in CSS pixels. @default 24 */
+    spacing?: number;
+    /** Radius of a resting dot in CSS pixels. @default 0.5 */
+    dotRadius?: number;
+    /** Opacity of the resting lattice. @default 0.14 */
+    baseAlpha?: number;
+    /** Opacity directly under the pointer. @default 0.75 */
+    peakAlpha?: number;
+    /** Spotlight reach in CSS pixels. @default 180 */
+    radius?: number;
+    /** Dot scale directly under the pointer. @default 2.6 */
+    peakScale?: number;
+    /**
+     * Element whose pointer movement drives the field. Defaults to the host's
+     * own parent, which is the common case: the field is the background layer of
+     * the section it reacts to.
+     */
+    containerRef?: RefObject<HTMLElement | null>;
+    /**
+     * Element the lattice makes room for. Its bounding box, inflated by
+     * `exclusionPadding` and feathered, renders no dots. One element means one
+     * collective halo, however many children it wraps.
+     */
+    exclusionRef?: RefObject<HTMLElement | null>;
+    /**
+     * Static exclusion rects in the field's own coordinate space, as an
+     * alternative to `exclusionRef`. Combined with it when both are given.
+     */
+    exclusionRects?: readonly DotFieldRect[];
+    /** Inflation applied to every exclusion rect. @default 24 */
+    exclusionPadding?: number;
+    /** Alpha ramp width at the exclusion edge. @default 40 */
+    exclusionFeather?: number;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * Cursor-reactive dot lattice, as a full-bleed background layer.
+ *
+ * At rest it is a dim monotone grid of dots. Under the pointer a soft pool of
+ * light brightens and enlarges the dots it covers, trailing the cursor by a
+ * frame or two so the surface feels physical rather than pinned. An optional
+ * exclusion element punches a feathered hole in the lattice, so content
+ * floating above the field keeps a clean field of its own.
+ *
+ * Performance: the resting lattice is rasterised once to an offscreen canvas
+ * and blitted each frame, so per-frame work is bounded by the spotlight's
+ * footprint (a few hundred dots) rather than the page's (several thousand).
+ * The rAF loop runs only while the pointer is inside and until the eased
+ * pointer settles; an untouched field costs nothing.
+ *
+ * Colour is resolved from `--color-foreground` at draw time and re-resolved
+ * when `data-theme` changes, so the field is monotone and correct in both
+ * themes without a theme prop. It is decorative: `aria-hidden` and inert to
+ * pointer events.
+ */
+export declare function DotField({ spacing, dotRadius, baseAlpha, peakAlpha, radius, peakScale, containerRef, exclusionRef, exclusionRects, exclusionPadding, exclusionFeather, className, style, }: DotFieldProps): import("react/jsx-runtime").JSX.Element;

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

@@ -1,5 +1,6 @@
 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. */
@@ -54,6 +55,11 @@ export type FlowchartTriggerProps = Omit<HTMLAttributes<HTMLDivElement>, "title"
     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"> & {
@@ -67,6 +73,11 @@ export declare const FlowchartTrigger: import("react").ForwardRefExoticComponent
     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;
@@ -79,6 +90,11 @@ export type FlowchartActionProps = Omit<HTMLAttributes<HTMLDivElement>, "title">
     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"> & {
@@ -92,6 +108,11 @@ export declare const FlowchartAction: import("react").ForwardRefExoticComponent<
     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 = {
@@ -121,6 +142,11 @@ export type FlowchartConditionProps = Omit<HTMLAttributes<HTMLDivElement>, "titl
     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"> & {
@@ -137,4 +163,88 @@ export declare const FlowchartCondition: import("react").ForwardRefExoticCompone
     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/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;