@agent-ui-kit/components 0.0.3

package/dist/controls/stat/stat.js

@@ -0,0 +1,73 @@
+// stat.ts — UIStatElement, the Display-class metric tile (LLD-C5, report-family.lld.md §3; SPEC-R7..R10;
+// ADR-0111). Real, selectable DOM text — label + value + optional delta + optional caption — in a small
+// component-built grid; deliberately NO heading stamp (SPEC-R8 — a stat's value is not a document
+// heading; this retires the fake-`h3`-in-a-card idiom the whole intake was forced by,
+// `a2ui/src/examples/patterns.ts:183-187` / `catalog-coverage.ts:319-323`). Non-interactive,
+// non-form-associated: no events, no keyboard contract, no focus, no `size`/`scale` geometry (Display
+// class, SPEC-R17). No child/slot seam (ADR-0111 fork F2, binding — composing a Sparkline beside a stat
+// is pure composition in a Row, OUTSIDE this component; never a slot here).
+//
+// ONE render effect (reads label/value/delta/caption): a full `replaceChildren` rebuild per change —
+// unlike ui-table there is no interior user state worth preserving on a four-span tile (no scroll, no
+// selection), so the simple whole-swap is correct (LLD-C5). No internals ARIA is minted: real text
+// carries the tile's whole meaning, including the delta's DIRECTION (SPEC-R9) — the direction word is
+// real, visually-hidden-but-announced text preceding the signed number; the glyph is `aria-hidden` and
+// text-free; direction never travels by color (ADR-0057 — no `[data-dir]` rule in stat.css touches ink).
+import { UIElement, prop } from "../../dom/index.js";
+import { deltaParts, formatStatValue, statDeltaProp, statValueProp } from "./stat-model.js";
+const props = {
+    label: { ...prop.string(''), reflect: true },
+    figure: statValueProp, // string | number · number → Intl-formatted, string passes through (stat-model.ts). Renamed from `value` (TKT-0069 item 1 ruling: `value` = the FACE form value, reserved; the A2UI catalog keeps wire `value`, mapped in its bespoke factory)
+    delta: statDeltaProp, // number | null · absent/non-finite → the delta region is not rendered (SPEC-R7)
+    caption: prop.string(''),
+};
+export class UIStatElement extends UIElement {
+    static props = props;
+    connected() {
+        this.effect(() => {
+            const label = this.label;
+            const value = formatStatValue(this.figure);
+            const caption = this.caption;
+            const delta = deltaParts(this.delta);
+            // Reading order label → value → delta → caption is DOM order (SPEC-R8) — the array below IS that
+            // order; one replaceChildren commits the whole tile (whole-swap semantics, no incremental patching).
+            const nodes = [this.#part('label', label), this.#part('value', value)];
+            if (delta !== null)
+                nodes.push(this.#deltaNode(delta));
+            if (caption !== '')
+                nodes.push(this.#part('caption', caption));
+            this.replaceChildren(...nodes);
+        });
+    }
+    /** One `<span data-part="{part}">{text}</span>` — the tile's plain text cells (label/value/caption). */
+    #part(part, text) {
+        const span = document.createElement('span');
+        span.setAttribute('data-part', part);
+        span.textContent = text;
+        return span;
+    }
+    /**
+     * The delta region (SPEC-R9): `data-dir` carries direction for the CSS glyph orientation; a
+     * component-drawn `aria-hidden` glyph (omitted when `dir === 'flat'` — no arrow for "unchanged"); a
+     * visually-hidden-but-announced direction WORD precedes the signed number, so the direction is real,
+     * readable text — never color, never a bare glyph codepoint (ADR-0111 cl.4, ADR-0057).
+     */
+    #deltaNode(delta) {
+        const region = document.createElement('span');
+        region.setAttribute('data-part', 'delta');
+        region.setAttribute('data-dir', delta.dir);
+        if (delta.dir !== 'flat') {
+            const glyph = document.createElement('span');
+            glyph.setAttribute('data-part', 'delta-glyph');
+            glyph.setAttribute('aria-hidden', 'true');
+            region.append(glyph);
+        }
+        const word = document.createElement('span');
+        word.setAttribute('data-part', 'delta-word');
+        word.textContent = `${delta.word} `;
+        region.append(word, document.createTextNode(delta.text));
+        return region;
+    }
+}
+if (!customElements.get('ui-stat'))
+    customElements.define('ui-stat', UIStatElement); // idempotent self-define

package/dist/controls/status-stream/status-stream.css

@@ -0,0 +1,151 @@
+/* status-stream.css — ui-status-stream, the single-file component stylesheet (ADR-0003;
+ * timeline-family.lld.md §4 · SPEC-R10/R14/R15). Like ui-timeline, the rail geometry/rhythm belongs
+ * entirely to the authored `ui-timeline-item` children this host creates via its own API
+ * (status-stream.ts) — this file owns ONLY the live strip's scroll region (the one-owned-scroll-region
+ * law, SPEC-R10) and its bounded viewport.
+ *
+ *   [1] TOKEN BLOCK — `:where(ui-status-stream)` declares the strip's OWN dimensional facts: the
+ *       bare-host `min-inline-size` floor (the ui-slider whole-shape lesson) and a bounded
+ *       `max-block-size` so the strip is a genuine scrollable "now" viewport, not an ever-growing page.
+ *   [2] STYLES BLOCK — `@scope (ui-status-stream)` lays out the imperatively-appended `ui-timeline-item`
+ *       children as a vertical flex stack and OWNS its scroll region (`overflow-y: auto` — the fleet's
+ *       physical-property convention for a scroll viewport, card.css/menu.css/combo-box.css precedent).
+ */
+
+/* ════════════════ [1] TOKEN BLOCK — :where(ui-status-stream) declares --ui-status-stream-* ════════════════ */
+
+:where(ui-status-stream) {
+  --ui-status-stream-min-inline-size: 16rem;
+  --ui-status-stream-max-block-size: 20rem;
+
+  /* the opt-in streaming header (ADR-0146 F8) — chrome pinned above the scroll region. Marker sizes are
+     em/rem (never raw px), so the header rides the ambient type scale with no per-scale ramp of its own. */
+  --ui-status-stream-header-marker-box: 1em;
+  --ui-status-stream-header-dot-size: 0.5em;
+  --ui-status-stream-header-gap: var(--md-sys-space-sm);
+  --ui-status-stream-header-pad: var(--md-sys-space-xs) var(--md-sys-space-sm);
+  --ui-status-stream-header-surface: var(--md-sys-color-neutral-surface);
+  --ui-status-stream-header-border: var(--md-sys-color-neutral-outline-variant);
+  --ui-status-stream-header-ink: var(--md-sys-color-neutral-on-surface);
+  /* the overall-status ink — the SHAPE (glyph/dot/ring) is the primary ADR-0057 signifier; this is the
+     redundant secondary channel, keyed by [data-status] in the styles block below. */
+  --ui-status-stream-header-status-ink: var(--md-sys-color-neutral-on-surface-variant);
+}
+:where(ui-status-stream [data-part='header'][data-status='active']) {
+  --ui-status-stream-header-status-ink: var(--md-sys-color-primary);
+}
+:where(ui-status-stream [data-part='header'][data-status='done']) {
+  --ui-status-stream-header-status-ink: var(--md-sys-color-success);
+}
+:where(ui-status-stream [data-part='header'][data-status='error']) {
+  --ui-status-stream-header-status-ink: var(--md-sys-color-danger);
+}
+:where(ui-status-stream [data-part='header'][data-status='warning']) {
+  --ui-status-stream-header-status-ink: var(--md-sys-color-warning);
+}
+
+/* ════════════════ [2] STYLES BLOCK — @scope (ui-status-stream) consumes ONLY --ui-status-stream-* ════════════════ */
+
+@scope (ui-status-stream) {
+  :scope {
+    display: flex;
+    flex-direction: column;
+    min-inline-size: var(--ui-status-stream-min-inline-size);
+    max-block-size: var(--ui-status-stream-max-block-size);
+    overflow-y: auto; /* the stream OWNS its scroll region (SPEC-R10) — the one-owned-scroll-region law */
+    overscroll-behavior: contain; /* a nested strip's scroll never chains into the page behind it */
+  }
+
+  /* ── the opt-in streaming header (ADR-0146 F8) — chrome PINNED above the scroll region ── */
+  /* `position: sticky; inset-block-start: 0` keeps the header at the scroll viewport's top while entries
+     overflow under it — the realization of F8's "chrome outside the scroll region, never scrolls away"
+     without restructuring the host's single-scroll-region model (entries stay direct flex children). An
+     opaque surface + a bottom hairline keep scrolled entries from bleeding through. */
+  :scope > [data-part='header'] {
+    position: sticky;
+    inset-block-start: 0;
+    z-index: 1;
+    display: flex;
+    align-items: center;
+    gap: var(--ui-status-stream-header-gap);
+    padding: var(--ui-status-stream-header-pad);
+    background: var(--ui-status-stream-header-surface);
+    border-block-end: 1px solid var(--ui-status-stream-header-border); /* 1px hairline — the annotated exception */
+    color: var(--ui-status-stream-header-ink);
+    font-weight: 500;
+  }
+  :scope > [data-part='header'] [data-part='header-label'] {
+    flex: 1 1 auto;
+    min-inline-size: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  /* the overall-status marker — mirrors the ui-timeline-item marker's SHAPE law (ADR-0057): done/error/
+     warning show their injected glyph (currentColor); '' / active paint a filled dot, pending a hollow
+     ring — each a distinct SHAPE, the status ink the redundant secondary channel. */
+  :scope > [data-part='header'] [data-part='header-marker'] {
+    position: relative;
+    flex: 0 0 auto;
+    inline-size: var(--ui-status-stream-header-marker-box);
+    block-size: var(--ui-status-stream-header-marker-box);
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    color: var(--ui-status-stream-header-status-ink);
+  }
+  /* the injected done/error/warning glyph — sizes to the marker box, inherits the status ink. */
+  :scope > [data-part='header'] [data-part='header-marker'] [data-role='marker'] {
+    inline-size: var(--ui-status-stream-header-marker-box);
+    block-size: var(--ui-status-stream-header-marker-box);
+  }
+  /* the dot/ring — painted for the in-progress statuses (no injected glyph present). '' / active = filled
+     dot; pending = hollow ring. Suppressed when a glyph is present (done/error/warning). */
+  :scope > [data-part='header'] [data-part='header-marker']:not(:has([data-role='marker']))::before {
+    content: '';
+    position: absolute;
+    inline-size: var(--ui-status-stream-header-dot-size);
+    block-size: var(--ui-status-stream-header-dot-size);
+    border-radius: 50%;
+    background: currentColor;
+  }
+  :scope > [data-part='header'][data-status='pending'] [data-part='header-marker']::before {
+    background: transparent;
+    border: 1px solid currentColor; /* 1px hairline ring — the annotated exception */
+  }
+  /* active — a pulse ping (box-shadow, so the dot box never resizes — the centering law); static under
+     reduced-motion (ADR-0122 F4 / SPEC-R4 AC3). */
+  :scope > [data-part='header'][data-status='active'] [data-part='header-marker']::before {
+    animation: ui-status-stream-header-pulse 1.6s ease-out infinite;
+  }
+  @media (prefers-reduced-motion: reduce) {
+    :scope > [data-part='header'][data-status='active'] [data-part='header-marker']::before {
+      animation: none;
+    }
+  }
+  @keyframes ui-status-stream-header-pulse {
+    0% {
+      box-shadow: 0 0 0 0 currentColor;
+    }
+    100% {
+      box-shadow: 0 0 0 calc(var(--ui-status-stream-header-dot-size) / 1.5) transparent;
+    }
+  }
+
+  /* forced-colors (WHCM) — keep the header legible by SHAPE when fills flatten. The glyph/dot resolve to
+     CanvasText; the hairline separators to CanvasText so the chrome stays delineated. */
+  @media (forced-colors: active) {
+    :scope > [data-part='header'] {
+      border-block-end-color: CanvasText;
+      color: CanvasText;
+    }
+    :scope > [data-part='header'] [data-part='header-marker'] {
+      color: CanvasText;
+    }
+    :scope > [data-part='header'] [data-part='header-marker']::before {
+      background: CanvasText;
+      border-color: CanvasText;
+    }
+  }
+}

package/dist/controls/status-stream/status-stream.d.ts

@@ -0,0 +1,108 @@
+import { UIContainerElement, type ReactiveProps } from '../../dom/index.js';
+import { UITimelineItemElement } from '../timeline-item/timeline-item.js';
+import '../timeline/timeline.js';
+/** The closed lifecycle-status vocabulary (ADR-0122 F3 + ADR-0146 F7's `warning`). Mirrors
+ *  ui-timeline-item's own `status` enum exactly — the entry projects 1:1 onto the item's typed prop. */
+export type ItemStatus = '' | 'pending' | 'active' | 'done' | 'error' | 'warning';
+/** The structured entry a consumer pushes as its stream yields (F4). NOT parsed — a plain record. */
+export interface StatusEntry {
+    key: string;
+    status?: ItemStatus;
+    label?: string;
+    description?: string;
+    timestamp?: string;
+    icon?: string;
+    /** Streamed chain-of-thought text — appended/replaced in place, NEVER tokenized/parsed. */
+    text?: string;
+    /** ADR-0146 F5 — an existing entry's key: when set (and known), this entry NESTS under that group (a
+     *  nested `<ui-timeline>` in the parent item's `[data-role="nested"]` slot) instead of as a top-level
+     *  sibling. A routing fact consumed by `appendEntry`, NEVER a timeline-item prop; an unknown parent key
+     *  degrades to a flat top-level append (never a throw). Set once at append time — `update` does not re-parent. */
+    parent?: string;
+}
+/**
+ * Worst-child-wins over the closed ADR-0146 F6 ladder — the single reduce both the (future) group header
+ * and the stream header use. Monotone-truthful: the result never reads calmer than the worst contributor
+ * (a group with one `error` child and one still-`active` child reads `error`, the truth that something
+ * already failed outranking "still working"). Neutral '' entries contribute nothing. Pure + exported so
+ * it is directly unit-tested (the ladder's `error`-beats-`active` and `done`+`warning`→`warning` cases).
+ */
+export declare function escalateStatus(statuses: readonly ItemStatus[]): ItemStatus;
+declare const props: {
+    size: {
+        reflect: true;
+        type: import("../../index.js").PropType<"sm" | "md" | "lg">;
+        default: "sm" | "md" | "lg";
+        attribute?: string | false;
+    };
+    label: {
+        reflect: true;
+        type: import("../../index.js").PropType<string>;
+        default: string;
+        attribute?: string | false;
+    };
+    header: {
+        reflect: true;
+        type: import("../../index.js").PropType<boolean>;
+        default: boolean;
+        attribute?: string | false;
+    };
+};
+export interface UIStatusStreamElement extends ReactiveProps<typeof props> {
+}
+export declare class UIStatusStreamElement extends UIContainerElement {
+    #private;
+    static props: {
+        size: {
+            reflect: true;
+            type: import("../../index.js").PropType<"sm" | "md" | "lg">;
+            default: "sm" | "md" | "lg";
+            attribute?: string | false;
+        };
+        label: {
+            reflect: true;
+            type: import("../../index.js").PropType<string>;
+            default: string;
+            attribute?: string | false;
+        };
+        header: {
+            reflect: true;
+            type: import("../../index.js").PropType<boolean>;
+            default: boolean;
+            attribute?: string | false;
+        };
+    };
+    constructor();
+    protected connected(): void;
+    /** Append a new entry, tail-follow to it, return the created item (the toast-region.show() return
+     *  precedent). Named `appendEntry`, NOT `append` — the native Node.prototype.append() every element
+     *  inherits is incompatible; see the file-header NAMED LLD DEVIATION note. ADR-0146 F5: an entry carrying
+     *  a KNOWN `parent` nests under that group's `[data-role="nested"]` slot instead of as a flat sibling.
+     *
+     *  Duplicate-key guard (issue #37): a key already in `#byKey` is REJECTED — returns the EXISTING item
+     *  untouched, never creating a second element. This is the same "graceful, never throw, no-op the
+     *  invalid case" posture the rest of this file already applies to creation-adjacent edge cases (an
+     *  unknown `parent` degrades to a flat append rather than throwing; a self-referencing `parent` does the
+     *  same) — appendEntry's contract is to CREATE, so a key collision is the invalid case here, symmetric
+     *  with update()'s own no-op on an UNKNOWN key. The alternative (tear down the old item and re-key it)
+     *  was rejected: the old item may itself be a GROUP PARENT with live nested children (#childrenOf/
+     *  #nestedByParent), and re-parenting those children's DOM + registry links onto a freshly-created
+     *  replacement item is a second, much larger surgery this fix does not need — silently keeping the
+     *  first-registered item is sufficient to close the acceptance criteria (never two live elements for one
+     *  key) without inventing a re-parent path the design never specified. A consumer that truly needs to
+     *  replace an entry's fields still can, via `update(key, patch)` on the SAME key. */
+    appendEntry(entry: StatusEntry): UITimelineItemElement;
+    /** Keyed, in-place mutation — transition status / grow text / reveal detail. No-op if the key is unknown.
+     *  Reaches a NESTED entry identically (the flat registry), and a status transition re-escalates its
+     *  enclosing group chain + the header (ADR-0146 F6, mediated — every child status change flows through here). */
+    update(key: string, patch: Partial<StatusEntry>): void;
+    /** The completion invariant — mark every still-pending/active entry TRUNCATED (SPEC-R11), then settle the
+     *  header to the escalated FINAL status (ADR-0146 F8). */
+    finalize(): void;
+    /** A failed stream (ADR-0146 F8): the completion invariant PLUS a header forced to `error` — the
+     *  completion invariant now has a header-level face. Marks still-pending/active entries truncated exactly
+     *  as `finalize()` does (a failed turn is also torn), then paints the header `error` regardless of the
+     *  entries' own escalation. */
+    fail(): void;
+}
+export {};