@agent-ui-kit/components 0.0.3

package/dist/controls/field/field.js

@@ -0,0 +1,228 @@
+// field.ts — UIFieldElement, the visible label/description/error wrapper around ONE slotted form control
+// (goals.md §G7 / decomp g7-field-form-provider slice s2, LLD-C4). BEHAVIOUR + props + the three parts +
+// self-define ONLY; geometry/colour live in field.css (s3), the public contract in field.md (s4).
+//
+// `ui-field` extends `UIElement` (NOT `UIFormElement` — a field carries no form value of its own; wrapping
+// it form-associated would double-submit) and reads the ADR-0050 `ui-form-connect` protocol event the base
+// dispatches on EVERY `UIFormElement` connect. Labelling rides the ADR-0051 seam (`setFieldLabelling`) — the
+// field never reaches into a control's internals or parts; the visible error rides the control's OWN
+// user-invalid timing (`FormConnectDetail.userInvalid`), so there is exactly one timing source, never a
+// second one duplicated here.
+//
+// Error-rendering history (two shipped bugs, same root smell — event-driven OBSERVATION of a timing
+// signal, instead of just reading it reactively): (1) five DOM listeners (input/change/blur/invalid/reset)
+// each calling a render — broke because `blur`/`invalid` are capture-only (they don't bubble): capture runs
+// ancestor→target, so this field's listener (ancestor) could read the control's `userInvalid()` BEFORE the
+// deeper `trackUserInvalid` listener (registered on the control itself) flipped `interacted` on the SAME
+// dispatch — a stale read, first blur showed nothing. (2) a microtask-deferred re-render — passed every
+// scripted/jsdom repro (a synchronous `dispatchEvent` call holds the JS stack through the WHOLE
+// propagation, so a deferred read always lands after), but s11's real cross-engine browser probe falsified
+// it: a genuine user-driven blur inserts a microtask CHECKPOINT between capture listeners (each listener
+// return empties the call stack), so the deferred read still ran before the tracker's, in BOTH engines — no
+// microtask-hop count survives a UA checkpoint. THIS (3rd) design has no event-listener race to have at
+// all: `#associate` installs a scope-owned reactive EFFECT over the connect detail's tracked closures
+// (`userInvalid()` / `validity()`, ADR-0050 §4) — every real trigger (typing, blur/change flipping
+// `interacted`, a live `setCustomValidity` write, a reset writing `interacted` back to false) is a plain
+// signal write the kernel wakes this effect for directly; there is no DOM dispatch order to depend on.
+//
+// Association is event-driven, first-wins, nearest-field-scoped: the field does NOT stop the connect event
+// from bubbling (a provider ancestor still needs to see it), and accepts a control only when
+// `control.closest('ui-field') === this` — the guard that also refuses a control belonging to a nested
+// inner field. The option-A bridge (ADR-0051 cl.3) is the fallback for a control with no seam wire: when
+// the associating control exposes an empty string `label` prop, a scope-owned effect writes this field's
+// `label` text into it, disposed (and the write undone) on dissociation — never touching a consumer-set label.
+//
+// Upgrade order (define order ≠ tree order, ADR-0051 cl.5): a control can upgrade before this field does,
+// so its one connect dispatch lands before any listener is live here. The complement is a one-shot catch-up
+// scan at THIS field's own connect — `querySelectorAll('*')` → `instanceof UIFormElement` →
+// `announceFormConnect()` — re-run again after a dissociation (while the field stays connected) so a second,
+// still-slotted control can associate next (first-wins is per-tenure, not forever).
+//
+// Host carries no role/aria-* attribute (a structural wrapper); the only internals use is the
+// `user-invalid` custom state, mirroring the associated control's own gate. `controls → dom` is the
+// allowed import direction.
+import { UIElement, UIFormElement, FORM_CONNECT_EVENT, prop, } from "../../dom/index.js";
+// A per-instance id seed for the three parts (the text-field `messageSeq` precedent) — one sequence number
+// shared by all three ids on a given instance, so `ui-field-label-3` / `-description-3` / `-error-3` read as
+// a set at a glance.
+let fieldSeq = 0;
+function hasStringLabel(control) {
+    return typeof control.label === 'string';
+}
+const props = {
+    label: { ...prop.string(), reflect: true }, // the visible label text → [data-part=label] (reflect: false — text-field precedent)
+    description: prop.string(), // the visible description text → [data-part=description] (reflect: false)
+};
+export class UIFieldElement extends UIElement {
+    static props = props;
+    // The three parts, created ONCE (idempotent across reconnect — light-DOM children persist through
+    // disconnect, the text-field editor precedent). Nullable until `#ensureParts` runs; every other read
+    // happens after `connected()` has run, so a cast is safe there (the `#message as HTMLElement` precedent).
+    #label = null;
+    #description = null;
+    #error = null;
+    // The associated control's connect detail — `null` while unassociated. First-wins: set once per tenure,
+    // cleared by `#dissociate` (control removal, or the field's own teardown).
+    #assoc = null;
+    // The option-A bridge (ADR-0051 cl.3). `#bridgeControl` doubles as its own "armed" flag: non-null iff the
+    // bridge effect is live for THAT control, so `#dissociate` knows both whether to dispose the effect and
+    // whether to clear the control's label (never touching a consumer-set one).
+    #bridgeControl = null;
+    #bridgeDispose = null;
+    // The reactive error-render effect (design #3 — see the header history), installed per association
+    // (`#associate`) and disposed at `#dissociate` — the bridge-disposer pattern, applied twice.
+    #renderDispose = null;
+    connected() {
+        const { label, description } = this.#ensureParts();
+        // Visible text — reactive; the part ELEMENTS (and ids) stay stable across a prop change, so an
+        // associated control's labelling references never need a re-handoff.
+        this.effect(() => {
+            label.textContent = this.label;
+        });
+        this.effect(() => {
+            description.textContent = this.description;
+        });
+        // ── association (event-driven, the LLD-C1 event doing double duty) ──
+        // Deliberately NO stopPropagation — the event must keep bubbling to a provider ancestor.
+        this.listen(this, FORM_CONNECT_EVENT, (event) => {
+            const detail = event.detail;
+            if (!(detail?.control instanceof UIFormElement))
+                return; // defense — the event never fires without one
+            if (this.#assoc !== null)
+                return; // first-wins — a second control in this field stays un-associated
+            if (detail.control.closest('ui-field') !== this)
+                return; // nearest-field rule (also rejects a nested field's control)
+            this.#associate(detail);
+        });
+        // Error rendering is no longer a listener here at all — it rides a reactive effect installed per
+        // association (`#associate`, design #3 in the header history). No event listener, no dispatch-order
+        // to depend on: `assoc.control`'s own `formReset()` (text-field: writes `this.value` + the tracker's
+        // `interacted` back to false, both tracked signals) wakes the same effect, so a reset needs no separate
+        // observation path either.
+        // ── upgrade-path catch-up (LLD-C1 / ADR-0051 cl.5) — AFTER the listeners above install ──
+        this.#catchUp();
+    }
+    disconnected() {
+        this.#dissociate(); // resources still live — a field removed from around its control must not leave stale labelling
+    }
+    /**
+     * Accept a connect detail: store it, hand the parts to the control via the ADR-0051 seam, arm the
+     * option-A bridge, install the reactive error-render effect (design #3 — the header history), and watch
+     * the control's own connection signal so its removal dissociates this field.
+     */
+    #associate(detail) {
+        this.#assoc = detail;
+        detail.control.setFieldLabelling({ label: this.#label, description: this.#description, error: this.#error });
+        this.#armBridge(detail.control);
+        this.#renderDispose = this.effect(() => this.#renderValidity(detail));
+        this.listen(detail.signal, 'abort', () => this.#dissociate(), { once: true });
+    }
+    /**
+     * Idempotence insurance (the `#assoc === null` early return) — TWO paths reach this: the associated
+     * control's own abort listener (removed from the field) and this field's `disconnected()` (field itself
+     * removed). Clears the labelling handoff, the bridge, and the visible error; then, IFF the field itself
+     * stays connected, re-runs the catch-up scan so a remaining slotted control can associate next — first-wins
+     * is per-tenure, not forever. Skipped on the field-disconnect path: re-associating from a field being torn
+     * down would mint labelling refs into a detached subtree.
+     */
+    #dissociate() {
+        const assoc = this.#assoc;
+        if (assoc === null)
+            return;
+        this.#renderDispose?.(); // stop the reactive render — otherwise it outlives dissociation, reading a removed control
+        this.#renderDispose = null;
+        this.#bridgeDispose?.(); // stop the scope-owned effect — otherwise it outlives dissociation and keeps writing
+        this.#bridgeDispose = null;
+        if (this.#bridgeControl)
+            this.#bridgeControl.label = ''; // only the bridge's own write; a consumer-set label stands
+        this.#bridgeControl = null;
+        assoc.control.setFieldLabelling(null); // safe on a detached node — a plain signal write
+        this.#assoc = null;
+        const error = this.#error;
+        error.textContent = '';
+        error.hidden = true;
+        this.internals.states?.delete('user-invalid');
+        if (this.isConnected)
+            this.#catchUp(); // per-tenure re-arm — skipped when it is the field itself being removed
+    }
+    /**
+     * The option-A bridge (ADR-0051 cl.3): the fallback name path for a control with no seam wire. Arms ONLY
+     * when the control exposes a string `label` prop currently equal to `''` — a pre-set (consumer-owned)
+     * label is never touched, arriving or leaving. The effect tracks this field's `label` prop, so a later
+     * edit keeps the bridged control's name current.
+     */
+    #armBridge(control) {
+        if (!hasStringLabel(control) || control.label !== '')
+            return;
+        this.#bridgeControl = control;
+        this.#bridgeDispose = this.effect(() => {
+            control.label = this.label;
+        });
+    }
+    /**
+     * One-shot re-announce of every already-connected `UIFormElement` descendant (LLD-C1 / ADR-0051 cl.5) —
+     * covers a control that upgraded BEFORE this field did, whose own connect dispatch landed before any
+     * listener here was live. A not-yet-upgraded control is skipped (the `instanceof` filter) and covers
+     * itself: its own `connectedCallback` dispatches at upgrade, once this field is already listening.
+     */
+    #catchUp() {
+        for (const el of this.querySelectorAll('*')) {
+            if (el instanceof UIFormElement)
+                el.announceFormConnect();
+        }
+    }
+    /**
+     * The reactive error render (design #3 — the header history). Reads the associated control's OWN gates
+     * through the ADR-0050 connect closures — `assoc.validity()` / `assoc.userInvalid()` are TRACKED reads
+     * (an effect subscribes to whatever signals they close over: the control's `value`/`required` props, the
+     * `trackUserInvalid` tracker's `interacted` signal, `setCustomValidity`'s signal); `control.validationMessage`
+     * (the platform DOM getter) is deliberately NOT read here — an effect cannot subscribe to it, which is
+     * exactly the gap the two prior designs papered over with an event listener. Installed once per
+     * association (`this.effect(...)` in `#associate`) — its lifetime IS the association's, so there is no
+     * `#assoc` null-guard to write: `#dissociate` disposes this effect before anything else. An empty message
+     * while user-invalid is treated as not-showing — no empty-but-visible error box.
+     */
+    #renderValidity(assoc) {
+        const verdict = assoc.validity();
+        const message = !verdict.valid ? verdict.message : '';
+        const showing = assoc.userInvalid() && message !== '';
+        const error = this.#error;
+        error.textContent = showing ? message : '';
+        error.hidden = !showing;
+        if (showing)
+            this.internals.states?.add('user-invalid');
+        else
+            this.internals.states?.delete('user-invalid');
+    }
+    /**
+     * Create the three parts ONCE (idempotent across reconnect — light-DOM children persist through
+     * disconnect, the text-field editor precedent). DOM placement IS the reading order: label PREPENDED,
+     * description + error APPENDED (author children — the slotted control — sit between); column flow needs
+     * no CSS `order`. A `<div>` label, not a `<label>`: no `for` semantics apply here, and a bare `<label>`
+     * invites click-forwarding expectations this seam doesn't need. `error` starts hidden + empty.
+     */
+    #ensureParts() {
+        if (this.#label && this.#description && this.#error) {
+            return { label: this.#label, description: this.#description, error: this.#error };
+        }
+        const seq = ++fieldSeq;
+        const label = document.createElement('div');
+        label.setAttribute('data-part', 'label');
+        label.id = `ui-field-label-${seq}`;
+        this.#label = label;
+        this.prepend(label);
+        const description = document.createElement('div');
+        description.setAttribute('data-part', 'description');
+        description.id = `ui-field-description-${seq}`;
+        this.#description = description;
+        const error = document.createElement('div');
+        error.setAttribute('data-part', 'error');
+        error.id = `ui-field-error-${seq}`;
+        error.hidden = true;
+        this.#error = error;
+        this.append(description, error);
+        return { label, description, error };
+    }
+}
+if (!customElements.get('ui-field'))
+    customElements.define('ui-field', UIFieldElement);

package/dist/controls/form-provider/form-provider.css

@@ -0,0 +1,40 @@
+/* form-provider.css — ui-form-provider, the single-file component stylesheet (ADR-0003). The degenerate
+ * minimal case of the fleet's two-block shape (text-field.css / column.css): a pure coordination element
+ * carries NO visual voice, so both sections collapse to their smallest legal form —
+ *
+ *   [1] TOKEN BLOCK — `:where(ui-form-provider)` declares NOTHING. The provider discovers/aggregates
+ *       `UIFormElement` descendants and composes with an optional native `<form>` (LLD-C7,
+ *       field-form-provider.lld.md); it has no colour, geometry, or spacing opinion of its own, so there is
+ *       no `--ui-form-provider-*` chain to declare. An EMPTY token block is deliberately NOT invented here
+ *       (LLD-C8) — this comment stands in for the section, so the token-hygiene probes need no special
+ *       case: an absent chain is still zero raw `--md-sys-color-*` leakage, zero non-`--ui-form-provider-*` consumption.
+ *   [2] STYLES BLOCK — `@scope (ui-form-provider)` sets exactly one declaration: `display: block`. An
+ *       unstyled custom element defaults to `inline`, which would lay its slotted block-level descendants
+ *       (fields, buttons) out inline against the host — a first-paint layout defect. No further rule: no
+ *       colour, no spacing, no geometry: the coordination host paints nothing, the slotted subtree owns
+ *       every box.
+ *
+ * Standalone stylesheet — linked via the component-styles barrel (wired in s12); NEVER injected from
+ * form-provider.ts (behaviour-only `.ts`, no runtime style injection — plan §2).
+ *
+ * ADR-0103 re-confirms this contract UNCHANGED: unlike `ui-radio-group` (a value-owning group whose direct-
+ * children discovery makes a layout default the only fix, Lane A), the provider's descendants are discovered
+ * by event bubbling — arbitrary composition (grids, rows, cards) the provider must not fight — so vertical
+ * rhythm stays the page author's taught idiom (a `ui-column[gap]` wrap around the fields, Lane C), not a
+ * `display:flex` default here.
+ */
+
+/* ════════════════ [1] TOKEN BLOCK — :where(ui-form-provider) declares NOTHING ════════════════ */
+/* Deliberate absence (LLD-C8): a pure coordination element has no visual voice — there is no
+   --ui-form-provider-* token chain to declare, and nothing rides [size]/[tone]/state to repoint (LLD-C7:
+   NO static props on this element — attributes: []). */
+
+/* ════════════════ [2] STYLES BLOCK — @scope (ui-form-provider) consumes NOTHING ════════════════ */
+
+@scope (ui-form-provider) {
+  :scope {
+    display: block; /* the host's only rule: an unstyled custom element defaults to `inline`, which would
+       lay its slotted block-level descendants (fields, buttons) out inline against it — `block` is the
+       coordination host's structural default, not a styling opinion. */
+  }
+}

package/dist/controls/form-provider/form-provider.d.ts

@@ -0,0 +1,42 @@
+import { UIElement, UIFormElement } from '../../dom/index.js';
+import type { FormValue } from '../../dom/index.js';
+/**
+ * The `submit()` aggregate detail (LLD-C7 — pinned event naming). The closed house event vocab has no
+ * `submit`; a provider-level submit IS a commit semantically, so it rides `change`. Disambiguation from a
+ * bubbled member `change` (which carries `detail: null` through the provider): `event.target === provider`.
+ */
+export interface FormSubmitDetail {
+    entries: ReadonlyArray<readonly [string, FormValue]>;
+    values: Readonly<Record<string, FormValue>>;
+}
+export declare class UIFormProviderElement extends UIElement {
+    #private;
+    static props: {};
+    protected connected(): void;
+    protected disconnected(): void;
+    /** Live registered controls, registration order — a reactive read (projects `registry.members`). Empty while disconnected. */
+    get controls(): readonly UIFormElement[];
+    /** Submission entries — native FormData parity (see form-registry.ts). Empty while disconnected. */
+    entries(): ReadonlyArray<readonly [string, FormValue]>;
+    /** Keyed convenience view of entries() — last entry wins on a duplicate name. Empty while disconnected. */
+    values(): Readonly<Record<string, FormValue>>;
+    /** Members whose merged verdict is invalid, registration order. Empty while disconnected. */
+    invalid(): readonly UIFormElement[];
+    /** invalid().length === 0. Vacuously true while disconnected. */
+    valid(): boolean;
+    /**
+     * If invalid: `reportValidity()` on the FIRST invalid member (registration order — native "focus the
+     * first invalid control" parity; the UA anchors/announces it) and return `false`, no event. Else emit
+     * the aggregate as a `change` (this module's `FormSubmitDetail` — see the type doc for the
+     * disambiguation from a bubbled member `change`) and return `true`.
+     */
+    submit(): boolean;
+    /**
+     * Native composition (decomp `provider_and_native_form`): partition members by their public `.form` —
+     * each DISTINCT non-null owning `<form>` gets ONE `form.reset()` (the platform itself walks that form's
+     * FACE members' `formResetCallback`s — calling reset per-member here would double-reset); form-less
+     * members get a direct `formResetCallback()` call (the public platform callback). Both paths end in the
+     * base's `ui-form-reset` dispatch (LLD-C1, `dom/form.ts`) — this method never dispatches it itself.
+     */
+    reset(): void;
+}

package/dist/controls/form-provider/form-provider.js

@@ -0,0 +1,105 @@
+// form-provider.ts — UIFormProviderElement, the fleet's first context/provider primitive (ADR-0050;
+// LLD-C7, decomp g7-field-form-provider slice s5). BEHAVIOUR + self-define ONLY — geometry lives in
+// form-provider.css (s6), the public contract in form-provider.md (s7).
+//
+// A pure coordination element: NO static props (a coordination element takes no configuration — the
+// descriptor's `attributes: []`), extends `UIElement` directly — NOT `UIFormElement` (the provider carries
+// no value of its own; wrapping it `formAssociated` would double-submit, ADR-0050 alternatives) and NOT
+// `UIContainerElement` (no surface paint). Discovery/aggregation is entirely the ADR-0050 connect-time
+// registration event + `traits/form-registry.ts`'s reactive registry (the listener, the four aggregate
+// computeds, teardown-by-abort all live there); this class is the thin public surface over that registry
+// plus the two coordination methods, submit()/reset().
+//
+// Upgrade-path catch-up (LLD-C1 / ADR-0051 cl.5): "ancestors connect before descendants" holds for
+// INSERTION order but not custom-element UPGRADE order — pre-existing DOM whose control module upgrades
+// before this provider's does dispatches `ui-form-connect` into the void (no listener yet). `connected()`
+// runs a one-shot `querySelectorAll('*')` AFTER the registry's listener installs and re-announces every
+// already-connected `UIFormElement` it finds via `announceFormConnect()` — the registry's dup guard makes
+// the re-announce idempotent, so this scan never double-registers a control that connected in time.
+//
+// `controls → dom + traits` is the allowed import direction.
+import { UIElement, UIFormElement } from "../../dom/index.js";
+import { formRegistry } from "../../traits/form-registry.js";
+export class UIFormProviderElement extends UIElement {
+    // EMPTY by design — a coordination element takes no configuration (descriptor `attributes: []`). The
+    // field exists (rather than being omitted) for the fleet convention + the s10 descriptor trip-wire
+    // (`compareDescriptorToProps` needs a live PropsSchema object to compare against).
+    static props = {};
+    #registry = null; // created in connected(), nulled in disconnected()
+    connected() {
+        this.#registry = formRegistry(this);
+        // Upgrade-path catch-up (see header) — AFTER the registry's listener is live, so a re-announced
+        // control registers immediately rather than racing this scan.
+        for (const el of this.querySelectorAll('*')) {
+            if (el instanceof UIFormElement)
+                el.announceFormConnect();
+        }
+    }
+    disconnected() {
+        this.#registry?.release();
+        this.#registry = null;
+    }
+    /** Live registered controls, registration order — a reactive read (projects `registry.members`). Empty while disconnected. */
+    get controls() {
+        return this.#registry?.members.value.map((member) => member.control) ?? [];
+    }
+    /** Submission entries — native FormData parity (see form-registry.ts). Empty while disconnected. */
+    entries() {
+        return this.#registry?.entries.value ?? [];
+    }
+    /** Keyed convenience view of entries() — last entry wins on a duplicate name. Empty while disconnected. */
+    values() {
+        return this.#registry?.values.value ?? {};
+    }
+    /** Members whose merged verdict is invalid, registration order. Empty while disconnected. */
+    invalid() {
+        return this.#registry?.invalid.value ?? [];
+    }
+    /** invalid().length === 0. Vacuously true while disconnected. */
+    valid() {
+        return this.#registry?.valid.value ?? true;
+    }
+    /**
+     * If invalid: `reportValidity()` on the FIRST invalid member (registration order — native "focus the
+     * first invalid control" parity; the UA anchors/announces it) and return `false`, no event. Else emit
+     * the aggregate as a `change` (this module's `FormSubmitDetail` — see the type doc for the
+     * disambiguation from a bubbled member `change`) and return `true`.
+     */
+    submit() {
+        // Disconnected FIRST, ahead of the validity check: valid() is a read and degrades gracefully
+        // (vacuously true with no registry), but submit() is an ACTION — an empty aggregate from a
+        // disconnected provider means "I can't see the form," not "the form is empty," so it must refuse
+        // (no reportValidity, no emit), not report a hollow success.
+        if (this.#registry === null)
+            return false;
+        if (!this.valid()) {
+            this.invalid()[0]?.reportValidity();
+            return false;
+        }
+        this.emit('change', { entries: this.entries(), values: this.values() });
+        return true;
+    }
+    /**
+     * Native composition (decomp `provider_and_native_form`): partition members by their public `.form` —
+     * each DISTINCT non-null owning `<form>` gets ONE `form.reset()` (the platform itself walks that form's
+     * FACE members' `formResetCallback`s — calling reset per-member here would double-reset); form-less
+     * members get a direct `formResetCallback()` call (the public platform callback). Both paths end in the
+     * base's `ui-form-reset` dispatch (LLD-C1, `dom/form.ts`) — this method never dispatches it itself.
+     */
+    reset() {
+        const resetForms = new Set();
+        for (const control of this.controls) {
+            const form = control.form;
+            if (form === null) {
+                control.formResetCallback();
+                continue;
+            }
+            if (resetForms.has(form))
+                continue; // already reset via this form
+            resetForms.add(form);
+            form.reset();
+        }
+    }
+}
+if (!customElements.get('ui-form-provider'))
+    customElements.define('ui-form-provider', UIFormProviderElement);

package/dist/controls/grid/grid.css

@@ -0,0 +1,72 @@
+/* grid.css — ui-grid, the single-file component stylesheet (ADR-0003). Two clearly-SECTIONED blocks, mirroring
+ * button.css / text-field.css:
+ *
+ *   [1] TOKEN BLOCK  — `:where(ui-grid)` (specificity 0,0,0) DECLARES the `--ui-grid-*` chain: the `--ui-grid-min`
+ *       track FLOOR (a sensible default; grid.ts repoints it inline for a per-instance `min` override) and the
+ *       `--ui-grid-gap` off the `--md-sys-space-{step}` density-responsive LAYOUT-spacing ladder (ADR-0015 cl.4 /
+ *       geometry.md "--space-* is layout spacing, not control geometry"). `[gap=step]` repoints the gap (gap
+ *       reflects, so the attribute is present). NO `--md-sys-height-*` — a Container/layout primitive has no control
+ *       height (geometry.md "five size-classes"); spacing rides `--md-sys-space` × `[density]` only.
+ *   [2] STYLES BLOCK — `@scope (ui-grid)` CONSUMES only `--ui-grid-*` for its layout: `display: grid` with the
+ *       INTRINSIC auto-fit/`minmax` track model (ADR-0016 cl.3/4) — `repeat(auto-fit, minmax(var(--ui-grid-min),
+ *       1fr))` reflows by the grid's OWN rendered width (more tracks when wide, fewer when narrow) with NO
+ *       explicit column-count prop and NO `@container` rule (auto-fit IS the responsiveness — unlike ui-row/
+ *       ui-column, which wrap via `@container`). `gap` rides `--ui-grid-gap`.
+ *
+ * SURFACE + FORCED-COLORS are the shared sheet's job, NOT duplicated here: the `--ui-container-bg`/`-tint`
+ * elevation×brightness seam AND the `@media (forced-colors: active)` survival both cover `ui-grid` from
+ * controls/_surface/container.css (the `@import`-FIRST sheet in the component-styles barrel, s12). A bare
+ * ui-grid is transparent (an unset container is unchanged); `[elevation]`/`[brightness]` repoint the shared
+ * seam. `ui-grid` establishes NO `container-type` of its own (ADR-0100 — an intrinsically-sized primitive can
+ * never safely be a query container) — moot for its own responsiveness anyway, since the auto-fit/`minmax`
+ * track model below is TRACK SIZING, not a container query, so removing the establishment leaves it byte-for-
+ * byte unaffected. This sheet owns LAYOUT only.
+ *
+ * Standalone stylesheet — linked via the component-styles barrel (s12); NEVER injected from grid.ts
+ * (behaviour-only `.ts`, no runtime style injection — plan §2; the `min` token thread is the values-API, not a
+ * style rule). */
+
+/* ════════════════ [1] TOKEN BLOCK — :where(ui-grid) declares --ui-grid-* ════════════════ */
+
+:where(ui-grid) {
+  /* the auto-fit/minmax track FLOOR (ADR-0016 cl.3) — a sensible default; grid.ts repoints this INLINE for a
+     per-instance `min` override (inline custom property outranks this `:where()` declaration). */
+  --ui-grid-min: 16rem;
+  /* gap off the --md-sys-space density-responsive ladder (ADR-0015 cl.4); default = none (a bare grid has no gap).
+     [gap=step] repoints below — gap reflects, so the attribute is present for these selectors. */
+  --ui-grid-gap: var(--md-sys-space-none);
+}
+
+/* gap → the --md-sys-space ladder (the step vocabulary mirrors flexProps' gap enum 1:1) */
+:where(ui-grid[gap='xs']) {
+  --ui-grid-gap: var(--md-sys-space-xs);
+}
+:where(ui-grid[gap='sm']) {
+  --ui-grid-gap: var(--md-sys-space-sm);
+}
+:where(ui-grid[gap='md']) {
+  --ui-grid-gap: var(--md-sys-space-md);
+}
+:where(ui-grid[gap='lg']) {
+  --ui-grid-gap: var(--md-sys-space-lg);
+}
+:where(ui-grid[gap='xl']) {
+  --ui-grid-gap: var(--md-sys-space-xl);
+}
+:where(ui-grid[gap='2xl']) {
+  --ui-grid-gap: var(--md-sys-space-2xl);
+}
+
+/* ════════════════ [2] STYLES BLOCK — @scope (ui-grid) consumes ONLY --ui-grid-* ════════════════ */
+
+@scope (ui-grid) {
+  :scope {
+    display: grid;
+    /* the INTRINSIC reflow (ADR-0016 cl.3/4): auto-fit packs as many `--ui-grid-min`-floored tracks as the
+       grid's OWN width fits and reflows the column count by width — no explicit column-count prop, no
+       `@container` rule. Each track flexes 1fr between the floor and the available share. */
+    grid-template-columns: repeat(auto-fit, minmax(var(--ui-grid-min), 1fr));
+    gap: var(--ui-grid-gap);
+    box-sizing: border-box;
+  }
+}

package/dist/controls/grid/grid.d.ts

@@ -0,0 +1,60 @@
+import { type ReactiveProps } from '../../dom/index.js';
+import { UIContainerElement } from '../../dom/container.js';
+declare const props: {
+    gap: {
+        reflect: true;
+        type: import("../../index.js").PropType<"none" | "sm" | "md" | "lg" | "xs" | "xl" | "2xl">;
+        default: "none" | "sm" | "md" | "lg" | "xs" | "xl" | "2xl";
+        attribute?: string | false;
+    };
+    min: {
+        reflect: true;
+        type: import("../../index.js").PropType<string>;
+        default: string;
+        attribute?: string | false;
+    };
+    elevation: {
+        reflect: true;
+        type: import("../../index.js").PropType<"0" | "1" | "2" | "3" | "-3" | "-2" | "-1">;
+        default: "0" | "1" | "2" | "3" | "-3" | "-2" | "-1";
+        attribute?: string | false;
+    };
+    brightness: {
+        reflect: true;
+        type: import("../../index.js").PropType<"0" | "1" | "2" | "3" | "-3" | "-2" | "-1">;
+        default: "0" | "1" | "2" | "3" | "-3" | "-2" | "-1";
+        attribute?: string | false;
+    };
+};
+export interface UIGridElement extends ReactiveProps<typeof props> {
+}
+export declare class UIGridElement extends UIContainerElement {
+    static props: {
+        gap: {
+            reflect: true;
+            type: import("../../index.js").PropType<"none" | "sm" | "md" | "lg" | "xs" | "xl" | "2xl">;
+            default: "none" | "sm" | "md" | "lg" | "xs" | "xl" | "2xl";
+            attribute?: string | false;
+        };
+        min: {
+            reflect: true;
+            type: import("../../index.js").PropType<string>;
+            default: string;
+            attribute?: string | false;
+        };
+        elevation: {
+            reflect: true;
+            type: import("../../index.js").PropType<"0" | "1" | "2" | "3" | "-3" | "-2" | "-1">;
+            default: "0" | "1" | "2" | "3" | "-3" | "-2" | "-1";
+            attribute?: string | false;
+        };
+        brightness: {
+            reflect: true;
+            type: import("../../index.js").PropType<"0" | "1" | "2" | "3" | "-3" | "-2" | "-1">;
+            default: "0" | "1" | "2" | "3" | "-3" | "-2" | "-1";
+            attribute?: string | false;
+        };
+    };
+    protected connected(): void;
+}
+export {};

package/dist/controls/grid/grid.js

@@ -0,0 +1,56 @@
+// grid.ts — UIGridElement, the auto-fit/minmax track-grid layout primitive (goals.md §G9 / ADR-0016 cl.3;
+// decomp g9-containers slice s6). BEHAVIOUR + props + self-define ONLY; the layout/surface live in grid.css
+// (the @scope block), the public contract in grid.md.
+//
+// `ui-grid` is a STRUCTURAL container — it extends `UIContainerElement` (the shared surface base, ADR-0015),
+// is NOT form-associated (no value/validity), and has NO control height (geometry.md Container/layout class —
+// spacing rides `--md-sys-space` × density, never `--md-sys-height-*`). Its children are arbitrary light-DOM grid
+// items (the default cell); it `render()`s nothing (the inherited void), so the user's children are never
+// clobbered (the host-as-grid pattern — the CSS lays them out).
+//
+// The RESPONSIVENESS is INTRINSIC (ADR-0016 cl.3/4): `grid-template-columns: repeat(auto-fit, minmax(min,
+// 1fr))` reflows by the grid's OWN rendered width — more tracks when wide, fewer when narrow — with NO
+// explicit column-count prop and NO `@container` rule. The one author lever is `min`, the minmax() track
+// floor: an arbitrary CSS `<length>` that cannot ride an attribute selector (and `attr()` typed is not
+// WebKit-safe), so it is threaded into the role-pure `--ui-grid-min` token via the values-API (the effect
+// below) — the same token-repoint the CSS does, but with a runtime value. Unset ⇒ the grid.css default floor.
+//
+// `ui-grid` IS an A2UI catalog type — `Grid` (ADR-0087 Fork A, Wave C; supersedes ADR-0016's earlier
+// non-catalog exclusion) renders to `ui-grid`. Reach for `Grid` when the layout should reflow its column count
+// responsively with available width; prefer `Row`/`Column` (with an explicit `wrap`) for an author-controlled
+// arrangement, and `List` when the children are an itemized collection needing list semantics (a2ui-catalog.
+// spec.md §5.2). Imports the dom layer only (`controls → dom`); `UIContainerElement` is pulled from
+// container.ts directly (the dom barrel re-exports it at s12, the integration slice).
+import { prop } from "../../dom/index.js";
+import { UIContainerElement } from "../../dom/container.js";
+const props = {
+    // The two surface axes (elevation/brightness), spread from the shared base — props.ts has no static-props
+    // prototype merge, so the base exposes a SPREADABLE bag the subclass folds in (the ADR-0013 formProps pattern).
+    ...UIContainerElement.surfaceProps,
+    // `gap` — the ONE flex-grammar prop a track grid consumes (the `--md-sys-space` density-responsive ladder,
+    // ADR-0016 cl.1). Pulled as a single entry from the shared flexProps (a grid has no align/justify/wrap).
+    gap: UIContainerElement.flexProps.gap,
+    // `min` — the minmax() track FLOOR, an arbitrary CSS `<length>`. Threaded into the role-pure `--ui-grid-min`
+    // token (the connected() effect); unset ⇒ the grid.css default floor. Reflects so the attribute is the
+    // inspectable public API (the dimension itself rides the inline token, not an attribute selector).
+    min: { ...prop.string(), reflect: true },
+};
+export class UIGridElement extends UIContainerElement {
+    static props = props;
+    connected() {
+        // Thread the `min` `<length>` into the role-pure `--ui-grid-min` token seam — the one value the grid.css
+        // template's `minmax()` floor reads. An inline custom property outranks the `:where()` default, so a set
+        // `min` overrides the floor; unset ⇒ removeProperty ⇒ the grid.css default applies. Scope-owned: re-runs on
+        // `min` and re-applies on reconnect; disposed with the connection scope (zero LIVE residue — the inline
+        // token persists on the detached host like any light-DOM state, but the effect itself is torn down).
+        this.effect(() => {
+            const min = this.min;
+            if (min)
+                this.style.setProperty('--ui-grid-min', min);
+            else
+                this.style.removeProperty('--ui-grid-min');
+        });
+    }
+}
+if (!customElements.get('ui-grid'))
+    customElements.define('ui-grid', UIGridElement);

package/dist/controls/icon/icon.css

@@ -0,0 +1,37 @@
+/* icon.css — ui-icon, the Display-class icon primitive (LLD-C5 §3, ADR-0065/0066). Two sectioned blocks:
+ *
+ *   [1] TOKEN BLOCK  — `:where(ui-icon)` declares --md-sys-icon-size: 1em. ui-icon has NO size/tone lever
+ *       (no [size] ramp, no [variant] repoint) — it is a 1em×1em cell by design; a consumer sizes it via
+ *       ambient `font-size` or an explicit `inline-size` override on the host (LLD §3, geometry.md Display
+ *       class: "intrinsic structural sizing").
+ *   [2] STYLES BLOCK — `@scope (ui-icon)` consumes ONLY --md-sys-icon-size. `color: inherit` so the injected
+ *       <svg fill="currentColor"> (resolve.ts) tracks the surrounding ink with no per-icon color plumbing —
+ *       including in forced-colors mode, where the CONSUMING context's ink already resolves to the platform
+ *       system color, so ui-icon needs no dedicated `@media (forced-colors: active)` block of its own.
+ *
+ * The content-into-cell contract (LLD §3) is what makes this file this small: an injected <svg width=100%
+ * height=100%> fills whatever cell it lands in — an [data-role='icon'] cell at icon size, a
+ * [data-role='caret'] cell inset to font-rhythm by that cell's OWN existing padding — with ZERO change to
+ * button.css/select.css. This sheet only styles the STANDALONE <ui-icon> host itself.
+ */
+
+/* ════════════════ [1] TOKEN BLOCK — :where(ui-icon) declares --md-sys-icon-* ════════════════ */
+
+:where(ui-icon) {
+  --md-sys-icon-size: 1em;
+}
+
+/* ════════════════ [2] STYLES BLOCK — @scope (ui-icon) consumes ONLY --md-sys-icon-* ════════════════ */
+
+@scope (ui-icon) {
+  :scope {
+    display: inline-flex;
+    inline-size: var(--md-sys-icon-size);
+    block-size: var(--md-sys-icon-size);
+    color: inherit;
+  }
+
+  :scope svg {
+    display: block;
+  }
+}