@agent-ui-kit/components 0.0.3

package/dist/controls/split/split.d.ts

@@ -0,0 +1,42 @@
+import { UIContainerElement, type ReactiveProps } from '../../dom/index.js';
+declare const splitProps: {
+    axis: {
+        reflect: true;
+        type: import("../../index.js").PropType<"horizontal" | "vertical">;
+        default: "horizontal" | "vertical";
+        attribute?: string | false;
+    };
+    sizes: {
+        attribute: false;
+        type: import("../../index.js").PropType<number[] | undefined>;
+        default: number[] | undefined;
+        reflect?: boolean;
+    };
+};
+export interface UISplitElement extends ReactiveProps<typeof splitProps> {
+}
+export declare class UISplitElement extends UIContainerElement {
+    #private;
+    static props: {
+        axis: {
+            reflect: true;
+            type: import("../../index.js").PropType<"horizontal" | "vertical">;
+            default: "horizontal" | "vertical";
+            attribute?: string | false;
+        };
+        sizes: {
+            attribute: false;
+            type: import("../../index.js").PropType<number[] | undefined>;
+            default: number[] | undefined;
+            reflect?: boolean;
+        };
+    };
+    protected connected(): void;
+    protected disconnected(): void;
+    /** Expose the live separator elements for test probes (structural ARIA/keyboard-target assertions). */
+    protected get separatorElsSeam(): HTMLElement[];
+    /** Expose the CURRENT effective ratio vector (controlled `sizes`, reconciled, or the internal uncontrolled
+     *  vector) for test probes — the sum-invariance / clamp / dynamic-pane assertions read this directly. */
+    protected get ratiosSeam(): number[];
+}
+export {};

package/dist/controls/split/split.js

@@ -0,0 +1,364 @@
+// split.ts — UISplitElement, the multi-pane (N-slot) resizable split container (app-surfaces-m4.lld.md
+// LLD-C1/C4, SPEC-R1..R5; ADR-0120 cl.2 — the wave's hardest contract). A components-tier Container/layout
+// primitive (sibling to `ui-row`/`ui-column`/`ui-grid`, `tier: layout`, NO control height): lays its
+// `ui-split-pane` children out along one axis, control-managing exactly N−1 draggable + keyboard-resizable
+// ARIA `separator` elements between adjacent pairs (the slider-thumb precedent — the author authors panes,
+// never separators). `formAssociated: false` — a layout container contributes nothing to a form.
+//
+// Sizing model (SPEC-R2): controlled (`sizes` present) — the control RENDERS `sizes` and EMITS the
+// proposed ratios on user resize but never self-mutates it (prop-as-source-of-truth, ADR-0102); uncontrolled
+// (`sizes` undefined) — an internal `#ratios` signal drives the render directly, seeded from each pane's
+// `initial` prop at connect and re-derived on every pane-count change (SPEC-R2 AC5, the dynamic-panes contract
+// — a MutationObserver on `childList`, the `toast-region.ts` precedent). Mid-drag pane-count mutation
+// ABORTS the in-flight drag FIRST (SPEC-R2 M2) via the pane-resize handle's distinct `abortDrag()`.
+//
+// Geometry: a `display: flex` row/column (axis picks the CSS identity via `[axis=vertical]`, split.css);
+// each pane's proportional share rides a JS-written `--_pane-flex` custom property (the slider-multi
+// `--value-pct-lo/-hi` geometry-seam precedent — this file NEVER writes a real layout style property
+// directly, only namespaced custom properties CSS consumes). Two-neighbor redistribution + bounds-in-ratio-
+// space math is entirely `constrain.ts` (DOM-free, pure); this file's job is measuring the live container/
+// pane extents (`getBoundingClientRect`/`getComputedStyle`) and feeding ratio-space bounds into it.
+//
+// `controls → dom + traits + controls/split/split-pane.ts` — inward-only (no deep `packages/**/src`).
+import { signal } from "../../reactive/index.js";
+import { UIContainerElement, prop } from "../../dom/index.js";
+import { paneResize } from "../../traits/pane-resize.js";
+import { UISplitPaneElement } from "./split-pane.js";
+import { redistribute, seedRatios, rederiveRatios, reconcileRatios } from "./constrain.js";
+const splitProps = {
+    axis: { ...prop.enum(['horizontal', 'vertical'], 'horizontal'), reflect: true },
+    // `sizes` is a PROPERTY, not an attribute — too structured (a JS number[]) to reflect. `attribute: false`
+    // means it is never observed/coerced from markup; `prop.json` supplies a codec ONLY so the descriptor
+    // trip-wire's structural `kindOf` probe can classify it ('json' — the same array/structured-value
+    // classification bar-chart's `data`/sparkline's `values` codecs already establish). undefined ⇒
+    // UNCONTROLLED (internal ratios drive the render); present ⇒ CONTROLLED (SPEC-R2 §2).
+    sizes: { ...prop.json(undefined), attribute: false },
+};
+let paneIdSeq = 0;
+export class UISplitElement extends UIContainerElement {
+    static props = splitProps;
+    // Uncontrolled internal ratio vector — a kernel signal so reading it inside `this.effect` tracks it.
+    #ratios = signal([]);
+    // A structural-change poke the render/ARIA effect reads UNCONDITIONALLY (component-reviewer MEDIUM fix):
+    // in UNCONTROLLED mode, #syncPanes's `#ratios` write already re-triggers the effect on its own (a fresh
+    // array reference), but in CONTROLLED mode #syncPanes touches NO signal at all when the pane COUNT
+    // changes (sizes itself is unchanged) — new separators would render bare (no aria-valuenow/-controls) and
+    // the new pane would get no --_pane-flex until `sizes` next changed for an unrelated reason. Bumping this
+    // on every real #syncPanes pass (both branches) forces the effect to re-run regardless of which mode is
+    // active — the SPEC-R2 × SPEC-R4 intersection dynamic panes must hold in BOTH sizing modes.
+    #version = signal(0);
+    #observer = null;
+    #resizeHandle = null;
+    #separatorEls = [];
+    #lastPaneCount = null; // null = never synced (connect-time seed path)
+    #warnedSizesMismatch = false;
+    #collapseMemory = new Map();
+    // TKT-0015: the ORIGINAL effective ratios at a drag's first live move, held fixed for every subsequent
+    // onResize call in the SAME drag. `pane-resize.ts`'s `deltaRatio` is measured SINCE THE PRESS POINT — an
+    // absolute offset from drag start, re-derived fresh on every pointermove, NOT an increment since the last
+    // move (see its own doc comment). Applying that press-relative delta against the LIVE, already-mutated
+    // ratio vector (as the pre-fix code did) double-counts every prior move's contribution each time — a
+    // resize that compounds every pointermove instead of tracking the pointer 1:1 (the perceived "animation").
+    // `null` ⟺ no drag currently in flight — doubles as the drag-active flag for `:state(dragging)` below.
+    #dragBaseline = null;
+    connected() {
+        this.#lastPaneCount = null;
+        this.#warnedSizesMismatch = false;
+        this.#collapseMemory.clear();
+        this.#observer = new MutationObserver(() => this.#syncPanes());
+        this.#observer.observe(this, { childList: true });
+        this.#syncPanes(); // seed from any children already present (declarative markup)
+        this.#resizeHandle = paneResize(this, {
+            separators: () => this.#separatorEls,
+            axis: () => this.axis,
+            rtl: () => getComputedStyle(this).direction === 'rtl',
+            onResize: (sepIndex, deltaRatio, commit) => this.#applyPointerDelta(sepIndex, deltaRatio, commit),
+        });
+        this.listen(this, 'keydown', (event) => this.#handleKeydown(event));
+        // The one geometry+ARIA effect: re-runs on `axis`/`sizes` changes, on any pane's own `min`/`max` (read
+        // per-pane inside the loop below, tracking each one individually), AND on `#version` (bumped by every
+        // real #syncPanes pass regardless of sizing mode — the single render pass.
+        this.effect(() => this.#render());
+    }
+    disconnected() {
+        this.#observer?.disconnect();
+        this.#observer = null;
+        this.#resizeHandle?.release(); // ends any in-flight drag WITHOUT a commit — clear the baseline/state to match
+        this.#resizeHandle = null;
+        this.#dragBaseline = null;
+        this.internals.states?.delete('dragging');
+        for (const sep of this.#separatorEls)
+            sep.remove();
+        this.#separatorEls = [];
+    }
+    // ── pane discovery + separator lifecycle (SPEC-R1, SPEC-R2 AC5) ────────────────────────────────────
+    #panes() {
+        return [...this.children].filter((el) => el instanceof UISplitPaneElement);
+    }
+    /**
+     * Re-derive the separator set (N−1) + (uncontrolled) ratio vector from the CURRENT pane list. Guarded
+     * against re-entrant noise from the separator DOM mutations THIS function itself performs (the
+     * MutationObserver watches `childList` on the host, so inserting/removing separators — non-pane children
+     * — re-triggers the same callback; since `#panes()` filters to `UISplitPaneElement` only, a separator-
+     * only mutation reports an UNCHANGED pane count and the guard below no-ops it, terminating the recursion).
+     */
+    #syncPanes() {
+        const panes = this.#panes();
+        const n = panes.length;
+        const isFirst = this.#lastPaneCount === null;
+        const countChanged = !isFirst && this.#lastPaneCount !== n;
+        if (!isFirst && !countChanged)
+            return; // separator-only noise — nothing to re-derive
+        for (const pane of panes) {
+            if (!pane.id)
+                pane.id = `ui-split-pane-${++paneIdSeq}`;
+        }
+        // Mid-drag mutation (SPEC-R2 M2): abort BEFORE re-deriving — the captured separator index is stale.
+        // `abortDrag()` is silent (no `onResize` call, SPEC-R2 M2), so the commit branch in `#applyPointerDelta`
+        // never runs to clear `#dragBaseline`/`:state(dragging)` — clear both here instead.
+        if (countChanged) {
+            this.#resizeHandle?.abortDrag();
+            this.#dragBaseline = null;
+            this.internals.states?.delete('dragging');
+        }
+        for (const sep of this.#separatorEls)
+            sep.remove();
+        this.#separatorEls = [];
+        for (let i = 0; i < n - 1; i++) {
+            const sep = document.createElement('div');
+            sep.setAttribute('data-separator', '');
+            sep.setAttribute('role', 'separator');
+            sep.setAttribute('tabindex', '0');
+            panes[i].after(sep);
+            this.#separatorEls.push(sep);
+        }
+        if (this.sizes === undefined) {
+            const seeds = panes.map((p) => p.initial);
+            this.#ratios.value = isFirst ? seedRatios(seeds) : rederiveRatios(this.#ratios.value, seeds);
+        }
+        // Unconditional poke (component-reviewer MEDIUM fix): the uncontrolled branch above already re-triggers
+        // the render/ARIA effect via the `#ratios` write, but CONTROLLED mode touches no signal on a pane-count
+        // change — bump this every real sync (both branches) so fresh separators always get their ARIA + the
+        // new pane always gets its --_pane-flex, regardless of sizing mode.
+        this.#version.value++;
+        this.#lastPaneCount = n;
+    }
+    // ── ratio resolution (controlled vs uncontrolled, SPEC-R2 AC3/AC4) ─────────────────────────────────
+    #effectiveRatios(panes) {
+        const sizes = this.sizes;
+        if (sizes !== undefined) {
+            if (sizes.length !== panes.length) {
+                if (!this.#warnedSizesMismatch) {
+                    console.warn(`ui-split: "sizes" has ${sizes.length} entries but ${panes.length} pane(s) are present — reconciling`);
+                    this.#warnedSizesMismatch = true;
+                }
+            }
+            else {
+                this.#warnedSizesMismatch = false;
+            }
+            return reconcileRatios(sizes, panes.length);
+        }
+        return this.#ratios.value;
+    }
+    /** Physical [min,max] bounds in RATIO space, resolved from each pane's live CSS min/max (`getComputedStyle`
+     *  — the used-value px resolution; degrades gracefully to `[0,1]` when unresolvable, e.g. jsdom's no-layout
+     *  environment or a zero-extent container, per constrain.ts's own contradictory-bounds tolerance). */
+    #boundsFor(panes) {
+        const rect = this.getBoundingClientRect();
+        const isH = this.axis === 'horizontal';
+        const extent = isH ? rect.width : rect.height;
+        return panes.map((pane) => {
+            if (extent <= 0)
+                return [0, 1];
+            const cs = getComputedStyle(pane);
+            const minRaw = isH ? cs.minWidth : cs.minHeight;
+            const maxRaw = isH ? cs.maxWidth : cs.maxHeight;
+            const minPx = Number.parseFloat(minRaw) || 0;
+            const maxPx = maxRaw === 'none' || maxRaw === '' ? Infinity : Number.parseFloat(maxRaw);
+            const minR = Math.min(1, minPx / extent);
+            const maxR = Number.isFinite(maxPx) ? Math.min(1, maxPx / extent) : 1;
+            return [minR, Math.max(minR, maxR)];
+        });
+    }
+    // ── resize application (keyboard path — see #applyPointerDelta below for the pointer path) ────────────
+    /** The keyboard path's delta resolver: a discrete key press is an INCREMENT against the CURRENT/live
+     *  ratios (correct — unlike the pointer path's since-press delta, TKT-0015), so it reads `#effectiveRatios`
+     *  fresh on every call rather than a drag-start baseline. */
+    #resolveKeyDelta(sepIndex, deltaRatio) {
+        const panes = this.#panes();
+        return redistribute(this.#effectiveRatios(panes), sepIndex, deltaRatio, this.#boundsFor(panes));
+    }
+    #commitRatios(next) {
+        if (this.sizes === undefined)
+            this.#ratios.value = next;
+    }
+    /** The pane-resize trait's onResize callback (pointer path) — `input` per live move, `change` on commit
+     *  (SPEC-R3 AC1). Controlled mode never self-mutates `sizes`; the proposed ratios ride the event detail
+     *  (SPEC-R2 AC3 — the consumer reads `event.detail` and writes `sizes` back to move the rendered layout).
+     *
+     *  TKT-0015 (1:1 pointer tracking): `deltaRatio` is measured SINCE THE PRESS POINT (pane-resize.ts), so it
+     *  MUST be applied against the ratios captured at the drag's FIRST live move (`#dragBaseline`) — NOT the
+     *  live/current `#effectiveRatios()` vector (the keyboard path's `#resolveKeyDelta` correctly uses THAT,
+     *  since a key press is a fresh increment), which already reflects every prior move's application and
+     *  would double-count it on each subsequent move (the compounding bug: N moves overshoot far past the pointer).
+     *  The baseline is snapshotted lazily on the first call of a drag and cleared on commit (drag end) — its
+     *  nullness also gates `:state(dragging)` (TKT-0015 pt.2 — split.css suspends selection while it holds). */
+    #applyPointerDelta(sepIndex, deltaRatio, commit) {
+        const panes = this.#panes();
+        if (this.#dragBaseline === null) {
+            this.#dragBaseline = this.#effectiveRatios(panes);
+            this.internals.states?.add('dragging');
+        }
+        const next = redistribute(this.#dragBaseline, sepIndex, deltaRatio, this.#boundsFor(panes));
+        this.#commitRatios(next);
+        this.emit(commit ? 'change' : 'input', next);
+        if (commit) {
+            this.#dragBaseline = null;
+            this.internals.states?.delete('dragging');
+        }
+    }
+    /** The keyboard path — a discrete key press is both the live update AND the commit in one atomic action,
+     *  so it emits BOTH `input` and `change` (the native `<input type=range>` per-keystep parity). */
+    #applyKeyDelta(sepIndex, deltaRatio) {
+        const next = this.#resolveKeyDelta(sepIndex, deltaRatio);
+        this.#commitRatios(next);
+        this.emit('input', next);
+        this.emit('change', next);
+    }
+    // ── keyboard (SPEC-R4) ──────────────────────────────────────────────────────────────────────────────
+    #keyStepRatio() {
+        const raw = getComputedStyle(this).getPropertyValue('--ui-split-key-step').trim();
+        if (raw.endsWith('%')) {
+            const n = Number.parseFloat(raw);
+            if (Number.isFinite(n))
+                return n / 100;
+        }
+        return 0.05; // the fallback default (5%) — also what --ui-split-key-step declares
+    }
+    #handleKeydown(event) {
+        const target = event.target;
+        if (!(target instanceof HTMLElement) || !target.hasAttribute('data-separator'))
+            return;
+        const index = this.#separatorEls.indexOf(target);
+        if (index === -1)
+            return;
+        if (event.key === 'Enter') {
+            const pane = this.#panes()[index];
+            if (pane?.collapsible) {
+                event.preventDefault();
+                this.#toggleCollapse(index);
+            }
+            return;
+        }
+        const axis = this.axis;
+        const rtl = getComputedStyle(this).direction === 'rtl';
+        const isH = axis === 'horizontal';
+        const growKey = isH ? (rtl ? 'ArrowLeft' : 'ArrowRight') : 'ArrowDown';
+        const shrinkKey = isH ? (rtl ? 'ArrowRight' : 'ArrowLeft') : 'ArrowUp';
+        // `--ui-split-key-step` is a percentage of the two-neighbor PAIR (SPEC-R4), matching aria-valuenow's
+        // own normalization (split.md/split.css) — a screen-reader user hears aria-valuenow move by roughly the
+        // step's percentage on every press, regardless of how large the pair is relative to the whole track.
+        // `redistribute()` expects a whole-container-ratio delta, so the pair-relative step is scaled by the
+        // pair's own combined extent before being passed in.
+        const panes = this.#panes();
+        const ratios = this.#effectiveRatios(panes);
+        const pairExtent = (ratios[index] ?? 0) + (ratios[index + 1] ?? 0);
+        const step = this.#keyStepRatio() * pairExtent;
+        let delta = null;
+        switch (event.key) {
+            case growKey:
+                delta = step;
+                break;
+            case shrinkKey:
+                delta = -step;
+                break;
+            case 'Home':
+                delta = -1;
+                break; // drive the leading pane to its minimum — redistribute clamps it
+            case 'End':
+                delta = 1;
+                break; // drive the leading pane to its maximum — redistribute clamps it
+            default: return;
+        }
+        event.preventDefault();
+        this.#applyKeyDelta(index, delta);
+    }
+    #toggleCollapse(index) {
+        const panes = this.#panes();
+        const current = this.#effectiveRatios(panes);
+        const bounds = this.#boundsFor(panes);
+        const [minI] = bounds[index] ?? [0, 1];
+        const isCollapsed = current[index] <= minI + 1e-6;
+        if (isCollapsed) {
+            const restore = this.#collapseMemory.get(index) ?? 1 / panes.length;
+            this.#collapseMemory.delete(index);
+            this.#applyKeyDelta(index, restore - current[index]);
+        }
+        else {
+            this.#collapseMemory.set(index, current[index]);
+            this.#applyKeyDelta(index, minI - current[index]);
+        }
+    }
+    // ── render: geometry seam + ARIA (SPEC-R1/R4) ───────────────────────────────────────────────────────
+    #render() {
+        void this.#version.value; // tracked unconditionally — see #version's own doc for why (the CONTROLLED-mode dynamic-panes fix)
+        const axis = this.axis;
+        const isH = axis === 'horizontal';
+        const panes = this.#panes();
+        for (const pane of panes) {
+            pane.toggleAttribute('data-axis-vertical', !isH);
+            const min = pane.min; // tracked — a per-pane min/max change re-runs this whole effect
+            const max = pane.max;
+            // TKT-0045: `setProperty(name, '')` REMOVES a custom property (CSSOM spec) rather than setting it
+            // to an empty value — an unset `--_pane-min`/`--_pane-max` would then INHERIT from the nearest
+            // ancestor that set a real one, which leaks THIS split's per-pane geometry into any independent
+            // nested `ui-split` further down a pane's own content (e.g. `ui-master-detail`'s internal split)
+            // whose own panes don't set `min`/`max` themselves. The literal `'initial'` keyword is a real
+            // (non-removed) declaration that resets to the custom property's guaranteed-invalid value —
+            // blocking inheritance while still tripping `var(--_pane-min, var(--ui-split-pane-min))`'s
+            // fallback exactly as an actually-unset property would.
+            pane.style.setProperty('--_pane-min', min || 'initial');
+            pane.style.setProperty('--_pane-max', max || 'initial');
+        }
+        const ratios = this.#effectiveRatios(panes);
+        panes.forEach((pane, i) => {
+            pane.style.setProperty('--_pane-flex', String(Math.max(0, ratios[i] ?? 0)));
+        });
+        this.#updateAria(panes, ratios);
+    }
+    #updateAria(panes, ratios) {
+        const axis = this.axis;
+        const bounds = this.#boundsFor(panes);
+        this.#separatorEls.forEach((sep, i) => {
+            const j = i + 1;
+            sep.setAttribute('aria-orientation', axis);
+            sep.setAttribute('aria-controls', panes[i]?.id ?? '');
+            if (!sep.hasAttribute('aria-label'))
+                sep.setAttribute('aria-label', 'Resize panel');
+            const ri = ratios[i] ?? 0;
+            const rj = ratios[j] ?? 0;
+            const pairExtent = ri + rj;
+            const [minI] = bounds[i] ?? [0, 1];
+            const [minJ] = bounds[j] ?? [0, 1];
+            const hiI = Math.max(minI, pairExtent - minJ);
+            const now = pairExtent > 0 ? Math.round((ri / pairExtent) * 100) : 0;
+            const lo = pairExtent > 0 ? Math.round((minI / pairExtent) * 100) : 0;
+            const hi = pairExtent > 0 ? Math.round((hiI / pairExtent) * 100) : 100;
+            sep.setAttribute('aria-valuenow', String(now));
+            sep.setAttribute('aria-valuemin', String(lo));
+            sep.setAttribute('aria-valuemax', String(hi));
+        });
+    }
+    // ── protected test seams ────────────────────────────────────────────────────────────────────────────
+    /** Expose the live separator elements for test probes (structural ARIA/keyboard-target assertions). */
+    get separatorElsSeam() {
+        return this.#separatorEls;
+    }
+    /** Expose the CURRENT effective ratio vector (controlled `sizes`, reconciled, or the internal uncontrolled
+     *  vector) for test probes — the sum-invariance / clamp / dynamic-pane assertions read this directly. */
+    get ratiosSeam() {
+        return this.#effectiveRatios(this.#panes());
+    }
+}
+if (!customElements.get('ui-split'))
+    customElements.define('ui-split', UISplitElement);

package/dist/controls/stat/stat-model.d.ts

@@ -0,0 +1,22 @@
+import type { PropConfig } from '../../dom/props.js';
+/** The SPEC-R7 value rendering: finite number → Intl-formatted; non-finite number → the placeholder `—`
+ *  (U+2014); string → verbatim passthrough (the author controls formatting for non-numeric values). */
+export declare function formatStatValue(value: string | number): string;
+export interface DeltaParts {
+    dir: 'up' | 'down' | 'flat';
+    word: 'up' | 'down' | 'unchanged';
+    text: string;
+}
+/** null for any non-number / non-finite input — the delta region is not rendered at all (SPEC-R7 AC3). */
+export declare function deltaParts(delta: unknown): DeltaParts | null;
+/**
+ * The safe `value` codec (SPEC-R7): `from(attr)`: `null` (attribute absent) → `''`; a TRIMMED attribute
+ * that parses to a FINITE number → that number (so `value="48200"` formats); anything else → the
+ * verbatim, untrimmed attribute string (so `value="$1.2M"` passes through unchanged). Property writes
+ * keep whatever runtime type the author assigns — this codec only guards the ATTRIBUTE crossing.
+ */
+export declare const statValueProp: PropConfig<string | number>;
+/** The safe `delta` codec (SPEC-R7): `from(attr)`: `null` → `null`; `parseFloat`; non-finite → `null`
+ *  (never `NaN` reaches the render path — `deltaParts` would already guard it, but the codec stays
+ *  honest at the boundary too, the chart-family safe-codec discipline). */
+export declare const statDeltaProp: PropConfig<number | null>;

package/dist/controls/stat/stat-model.js

@@ -0,0 +1,69 @@
+// stat-model.ts — the pure, DOM-free math for `ui-stat` (LLD-C4, report-family.lld.md §3; SPEC-R7/R9;
+// ADR-0111). Everything here is a plain function over strings/numbers — no DOM, no signals,
+// unit-testable without a browser (the sparkline-math.ts / bar-math.ts pure-core precedent).
+//
+// `formatStatValue` (SPEC-R7): a finite number formats via the module-memoized default-locale
+// Intl.NumberFormat (the chart-family printed-value discipline); a non-finite number renders the
+// placeholder em dash; a string passes through verbatim (the author's own pre-formatted text, e.g.
+// "$1.2M" — no coercion, ever).
+//
+// `deltaParts` (SPEC-R9): the delta region announces DIRECTION, never valence — a `dir` (drives the CSS
+// glyph orientation), a `word` (the real, visually-hidden-but-announced text: "up"/"down"/"unchanged"),
+// and `text` (the Intl-formatted signed number, `signDisplay: 'exceptZero'` so 0 prints bare and ±N carry
+// an explicit sign). `null` for any non-number/non-finite input — the delta region is not rendered at all
+// (never a silent throw, never a fabricated direction for garbage input).
+const numberFormat = new Intl.NumberFormat(); // module-memoized default-locale formatter (SPEC-R7)
+const signedNumberFormat = new Intl.NumberFormat(undefined, { signDisplay: 'exceptZero' }); // SPEC-R9
+/** The SPEC-R7 value rendering: finite number → Intl-formatted; non-finite number → the placeholder `—`
+ *  (U+2014); string → verbatim passthrough (the author controls formatting for non-numeric values). */
+export function formatStatValue(value) {
+    if (typeof value === 'number')
+        return Number.isFinite(value) ? numberFormat.format(value) : '—';
+    return value;
+}
+/** null for any non-number / non-finite input — the delta region is not rendered at all (SPEC-R7 AC3). */
+export function deltaParts(delta) {
+    if (typeof delta !== 'number' || !Number.isFinite(delta))
+        return null;
+    const dir = delta > 0 ? 'up' : delta < 0 ? 'down' : 'flat';
+    const word = delta > 0 ? 'up' : delta < 0 ? 'down' : 'unchanged';
+    return { dir, word, text: signedNumberFormat.format(delta) };
+}
+/**
+ * The safe `value` codec (SPEC-R7): `from(attr)`: `null` (attribute absent) → `''`; a TRIMMED attribute
+ * that parses to a FINITE number → that number (so `value="48200"` formats); anything else → the
+ * verbatim, untrimmed attribute string (so `value="$1.2M"` passes through unchanged). Property writes
+ * keep whatever runtime type the author assigns — this codec only guards the ATTRIBUTE crossing.
+ */
+export const statValueProp = {
+    type: {
+        from(attr) {
+            if (attr === null)
+                return '';
+            const trimmed = attr.trim();
+            const n = Number(trimmed);
+            return trimmed !== '' && Number.isFinite(n) ? n : attr;
+        },
+        to(value) {
+            return String(value);
+        },
+    },
+    default: '',
+};
+/** The safe `delta` codec (SPEC-R7): `from(attr)`: `null` → `null`; `parseFloat`; non-finite → `null`
+ *  (never `NaN` reaches the render path — `deltaParts` would already guard it, but the codec stays
+ *  honest at the boundary too, the chart-family safe-codec discipline). */
+export const statDeltaProp = {
+    type: {
+        from(attr) {
+            if (attr === null)
+                return null;
+            const n = Number.parseFloat(attr);
+            return Number.isFinite(n) ? n : null;
+        },
+        to(value) {
+            return value === null ? null : String(value);
+        },
+    },
+    default: null,
+};

package/dist/controls/stat/stat.css

@@ -0,0 +1,101 @@
+/* stat.css — ui-stat, the Display-class metric tile (LLD-C6, report-family.lld.md §3; SPEC-R8/R9/R10/
+ * R14/R15/R16/R17; ADR-0111). Two sectioned blocks:
+ *
+ *   [1] TOKEN BLOCK — `:where(ui-stat)` declares the tile's rhythm/typography as `--ui-stat-*`: interior
+ *       gap + label/caption ink ride the space ladder + a supporting-text role (density-responsive for
+ *       free, ADR-0103); the delta glyph's mark geometry is density-invariant px/em (badge/sparkline
+ *       precedent). Display class (SPEC-R17): no [size]/[scale] control-band lookup, no `--md-sys-height-*`,
+ *       no `h/2` law — the lever is the type matrix (`--md-sys-typescale-*`) + the space ladder.
+ *   [2] STYLES BLOCK — `@scope (ui-stat)` consumes ONLY `--ui-stat-*`.
+ *
+ * The value register is the tile the fake-`h3` idiom faked: `--md-sys-typescale-headline-small-*` gives
+ * it real heading-scale typography WITHOUT a heading element (ADR-0078's semantics/style split honored —
+ * stat.ts never stamps h1-h6).
+ *
+ * SPEC-R9 AC2 — no valence channel exists to remove: the delta inherits `color: inherit`; no `[data-dir]`
+ * rule in this file touches ink. Direction lives ONLY in the glyph's clip-path orientation + the signed
+ * number + the hidden word (stat.ts). `neutral` isn't a concept here — up/down/flat share one ink.
+ *
+ * Forced colors (SPEC-R15): the delta glyph is `background: currentColor` (a mask shape, not text) — an
+ * explicit `forced-colors` block repoints it to `CanvasText` (the bar-chart/badge fill lesson: a
+ * background-drawn shape is otherwise forced to `Canvas` and vanishes). Every other part is real text and
+ * survives untouched — no dedicated block needed for label/value/caption.
+ *
+ * RTL: no dedicated mirroring rule needed — the tile is a single-column block stack (`display:
+ * inline-grid`, one column), so there is no inline-axis slot order to flip; the delta's glyph→word→number
+ * sequence is DOM order (stat.ts), which logical inline layout already reads correctly in both directions.
+ */
+
+/* ════════════════ [1] TOKEN BLOCK — :where(ui-stat) declares --ui-stat-* ════════════════ */
+
+:where(ui-stat) {
+  --ui-stat-min-inline-size: 8em; /* the whole-shape floor (SPEC-R10) */
+  --ui-stat-gap: var(--md-sys-space-xs); /* interior rhythm — rides [density] free (ADR-0103) */
+  --ui-stat-label-ink: var(--md-sys-color-neutral-on-surface-variant);
+  --ui-stat-caption-ink: var(--md-sys-color-neutral-on-surface-variant);
+  --ui-stat-delta-glyph-size: 0.6em; /* density-invariant mark geometry */
+}
+
+/* ════════════════ [2] STYLES BLOCK — @scope (ui-stat) consumes ONLY --ui-stat-* ════════════════ */
+
+@scope (ui-stat) {
+  :scope {
+    display: inline-grid;
+    gap: var(--ui-stat-gap);
+    min-inline-size: var(--ui-stat-min-inline-size);
+  }
+
+  :scope [data-part='label'] {
+    color: var(--ui-stat-label-ink);
+    font-size: var(--md-sys-typescale-label-medium-size);
+    line-height: var(--md-sys-typescale-label-medium-line-height);
+  }
+
+  :scope [data-part='value'] {
+    /* the tile register the fake-h3 idiom faked — real heading-scale STYLE without heading SEMANTICS
+       (ADR-0078's split honored; row names verified against dimensions.css at build) */
+    font-size: var(--md-sys-typescale-headline-small-size);
+    line-height: var(--md-sys-typescale-headline-small-line-height);
+    font-weight: var(--md-sys-typescale-headline-small-weight);
+    font-variant-numeric: tabular-nums;
+  }
+
+  :scope [data-part='delta'] {
+    font-size: var(--md-sys-typescale-body-medium-size);
+  }
+
+  :scope [data-part='caption'] {
+    color: var(--ui-stat-caption-ink);
+    font-size: var(--md-sys-typescale-body-small-size);
+  }
+
+  :scope [data-part='delta-glyph'] {
+    display: inline-block;
+    background: currentColor;
+    inline-size: var(--ui-stat-delta-glyph-size);
+    block-size: var(--ui-stat-delta-glyph-size);
+  }
+
+  :scope [data-dir='up'] [data-part='delta-glyph'] {
+    clip-path: polygon(50% 0, 100% 100%, 0 100%);
+  }
+  :scope [data-dir='down'] [data-part='delta-glyph'] {
+    clip-path: polygon(0 0, 100% 0, 50% 100%);
+  }
+
+  :scope [data-part='delta-word'] {
+    /* visually hidden, announced (SPEC-R9) — the direction word carries the meaning as REAL text */
+    position: absolute;
+    inline-size: 1px;
+    block-size: 1px;
+    overflow: hidden;
+    clip-path: inset(50%);
+    white-space: nowrap;
+  }
+
+  @media (forced-colors: active) {
+    :scope [data-part='delta-glyph'] {
+      background: CanvasText; /* SPEC-R15 — the bar-fill/badge lesson: a masked shape needs a system ink */
+    }
+  }
+}

package/dist/controls/stat/stat.d.ts

@@ -0,0 +1,30 @@
+import { UIElement, type ReactiveProps } from '../../dom/index.js';
+declare const props: {
+    label: {
+        reflect: true;
+        type: import("../../index.js").PropType<string>;
+        default: string;
+        attribute?: string | false;
+    };
+    figure: import("../../index.js").PropConfig<string | number>;
+    delta: import("../../index.js").PropConfig<number | null>;
+    caption: import("../../index.js").PropConfig<string>;
+};
+export interface UIStatElement extends ReactiveProps<typeof props> {
+}
+export declare class UIStatElement extends UIElement {
+    #private;
+    static props: {
+        label: {
+            reflect: true;
+            type: import("../../index.js").PropType<string>;
+            default: string;
+            attribute?: string | false;
+        };
+        figure: import("../../index.js").PropConfig<string | number>;
+        delta: import("../../index.js").PropConfig<number | null>;
+        caption: import("../../index.js").PropConfig<string>;
+    };
+    protected connected(): void;
+}
+export {};