@agent-ui-kit/components 0.0.3

package/dist/base-styles.css

@@ -0,0 +1,8 @@
+/* base-styles.css — the DOCUMENT BASE barrel (the foundation-styles.css pattern): the foundational theme
+ * any host page loads to get the document basics — typeface (--md-sys-typeface-sans), body leading, ambient
+ * surface/ink, font rendering — from @agent-ui-kit/shared's base.css. Load AFTER foundation-styles.css (base
+ * consumes the roles/constants foundation declares) and BEFORE page-local sheets. A page composing the
+ * docs shell does NOT need this (the shell's _page.css sets its own document rule); a SHELL-LESS page
+ * (agent-admin-app.html is the shape) does, or it renders in the UA serif.
+ */
+@import '@agent-ui-kit/shared/base.css';

package/dist/component-styles.css

@@ -0,0 +1,147 @@
+/* component-styles.css — the per-component stylesheet barrel (ADR-0003). Aggregates every FACE control's
+ * single `{name}.css` (each = a `:where(ui-{name})` token block + an `@scope (ui-{name})` styles block).
+ * A host page links this AFTER foundation-styles.css so the foundation (the `--md-sys-color-*` colour roles + the
+ * `--ui-{height,font,gap,space}-*` ramp + `--md-sys-shape-corner-base`) is already declared when a control's `:where()`
+ * block reads it. Exposed as the package `./component-styles.css` export. Pure CSS — NEVER injected from a
+ * control's `.ts` (behaviour-only `.ts`, no runtime style injection — plan §2). Grows one `@import` per control.
+ *
+ * DO NOT REORDER — the imports are append-only in control-addition order. Each control's sheet is fully
+ * self-scoped (a `:where(ui-{name})` token block + an `@scope (ui-{name})` styles block), so the controls do
+ * not interact across the cascade; the stable order keeps any future shared/global rule deterministic. New
+ * controls APPEND after the last import.
+ *
+ * THE ONE SHARED SEAM (decomp s12): `_surface/container.css` is NOT a control sheet — it is the cross-family
+ * surface mapping (the `--ui-container-bg`/`-tint` consumption seam, ADR-0015) that the whole G9
+ * container/layout family sits on. It is imported FIRST, before any element sheet, so its `:where()` surface
+ * tokens are declared when a container element's own `@scope` block consumes them. It does NOT establish
+ * `container-type` on any element (ADR-0100 deleted that blanket rule — a layout primitive is never a size
+ * query container by default; establishment now belongs to externally-sized composition boundaries, e.g. an
+ * A2UI mount surface or app-shell). The container element sheets follow it in a stable, annotated order (also
+ * do-not-reorder).
+ */
+@import './controls/_surface/container.css';
+/* The shared container BOX-MODEL (margin inset + sticky-region pattern) — a surface opts in with [data-box].
+ * After the surface PAINT layer above, before any element sheet (so an element's @scope can override it). */
+@import './controls/_surface/container-box.css';
+
+/* form controls (G5/G6) */
+@import './controls/button/button.css';
+@import './controls/text-field/text-field.css';
+
+/* display controls (ADR-0025) */
+@import './controls/text/text.css';
+
+/* the icon adapter's declarative consumer (ADR-0065/0066) */
+@import './controls/icon/icon.css';
+
+/* Indicator controls — Wave 1 (ADR-0041/0042: widget-box geometry + UIIndicatorElement base) */
+@import './controls/checkbox/checkbox.css';
+@import './controls/switch/switch.css';
+@import './controls/radio/radio.css';
+@import './controls/radio/radio-group.css';
+
+/* Range controls — Wave 2 (ADR-0042 Range half): single + dual-thumb slider. */
+@import './controls/slider/slider.css';
+@import './controls/slider-multi/slider-multi.css';
+
+/* Pattern controls — ADR-0095 (supersedes ADR-0086's ui-radio-group[variant='segmented'], hard cutover):
+ * the standalone segmented control. segment.css FIRST (the leaf, no dot to suppress — its own base layout +
+ * focus ring), segmented-control.css SECOND (the host's compound selectors consume ui-segment by tag). */
+@import './controls/segment/segment.css';
+@import './controls/segmented-control/segmented-control.css';
+
+/* G9 container / layout family — each sheet consumes the shared `_surface/container.css` seam above. */
+@import './controls/row/row.css';
+@import './controls/column/column.css';
+@import './controls/list/list.css';
+@import './controls/grid/grid.css';
+@import './controls/card/card.css';
+@import './controls/tabs/tabs.css';
+@import './controls/modal/modal.css';
+
+/* Overlay controls — Wave 4 (ADR-0043): each is self-scoped (a `:where(ui-{name})` token block + an
+ * `@scope (ui-{name})` styles block); the popup panels are Container/surface, the triggers Control-class. */
+@import './controls/popover/popover.css';
+@import './controls/tooltip/tooltip.css';
+@import './controls/menu/menu.css';
+@import './controls/select/select.css';
+@import './controls/combo-box/combo-box.css';
+
+/* Picker controls — Wave 5B (ADR-0048): standalone month-grid date picker. */
+@import './controls/calendar/calendar.css';
+
+/* Coordination controls — G7 (ADR-0050/ADR-0051): the label/description/error wrapper + the aggregation
+ * provider. form-provider.css declares no --ui-form-provider-* tokens (LLD-C8 — pure coordination, no paint). */
+@import './controls/field/field.css';
+@import './controls/form-provider/form-provider.css';
+
+/* Coordination/carrier controls — ADR-0117: the fleet's second pure UIElement coordination primitive.
+ * theme-provider.css declares no --ui-theme-provider-* tokens (SPEC-R6 — pure coordination, no paint). */
+@import './controls/theme-provider/theme-provider.css';
+
+/* Chart family — Wave M1 (ADR-0107, chart-family.lld.md LLD-C8): Display-class, axis-free chart marks. */
+@import './controls/sparkline/sparkline.css';
+@import './controls/bar-chart/bar-chart.css';
+
+/* Report family — Wave M1 (ADR-0111, report-family.lld.md LLD-C10): the native table, the metric tile,
+ * and the compact-realm intent badge. All Display-class, non-interactive, non-form-associated leaves. */
+@import './controls/table/table.css';
+@import './controls/stat/stat.css';
+@import './controls/badge/badge.css';
+
+/* Content family — Wave M1 (ADR-0113, content-family.lld.md LLD-C11): the zero-machinery code leaf and
+ * the native details/summary disclosure. (The ui-text hyperlink extension lives in text/text.css, above.) */
+@import './controls/code/code.css';
+@import './controls/disclosure/disclosure.css';
+
+/* ADR-0124 — the ui-swiper family: a CSS-native scroll-snap carousel (swiper-family.lld.md). Five files —
+ * swiper.css is the PRIMARY sheet (declares the family --ui-swiper-* token table + the host's own anatomy)
+ * and MUST load before the four leaf sheets, which consume that prefix (the family-root rule, ADR-0124
+ * Consequences). */
+@import './controls/swiper/swiper.css';
+@import './controls/swiper/swiper-item.css';
+@import './controls/swiper/swiper-pagination.css';
+@import './controls/swiper/swiper-paddles.css';
+@import './controls/swiper/swiper-label.css';
+
+/* Token-surface family — M1 (ADR-0118, token-surfaces.lld.md LLD-C9): show-never-edit color/dimension
+ * primitives (swatch/ramp/ladder). All Display-class, non-interactive, non-form-associated leaves. */
+@import './controls/swatch/swatch.css';
+@import './controls/ramp/ramp.css';
+@import './controls/ladder/ladder.css';
+
+/* Feed family — Wave M1 (ADR-0112, feed-family.lld.md LLD-C11): agent-activity primitives — the thin-rail
+ * progress bar, the compact identity mark, the FilePart-aligned file card, and the toast pair (a fixed
+ * notification card + its top-layer stacking host). */
+@import './controls/progress/progress.css';
+@import './controls/avatar/avatar.css';
+@import './controls/attachment/attachment.css';
+@import './controls/toast/toast.css';
+@import './controls/toast/toast-region.css';
+
+/* M4 Phase 1 — the split primitive (ADR-0120 cl.2, app-surfaces-m4.lld.md LLD-C5): ui-split (the
+ * separator/divider geometry) + ui-split-pane (the axis-oblique pane geometry it drives via a JS seam). */
+@import './controls/split/split.css';
+@import './controls/split/split-pane.css';
+
+/* ADR-0121 — ui-toolbar, a Pattern-class action bar (host-as-flex + role=toolbar + roving focus, decoupled
+ * from selection; posture via the existing elevation/brightness surface axis, no positioning machine). */
+@import './controls/toolbar/toolbar.css';
+
+/* ADR-0122 — the timeline family: the shared marker-system rail row (ui-timeline-item), its durable
+ * authored-children host (ui-timeline), and its live imperatively-fed sibling (ui-status-stream). */
+@import './controls/timeline-item/timeline-item.css';
+@import './controls/timeline/timeline.css';
+@import './controls/status-stream/status-stream.css';
+
+/* ADR-0125 — ui-command-modal, the CMD-K command palette (command-modal.lld.md): nests ui-modal for the
+ * surface (already imported above) and paints only its own search/list/status/empty parts. */
+@import './controls/command-modal/command-modal.css';
+
+/* ADR-0123 — ui-color-picker, the OKLCH-internal 2-axis color-input control (color-picker.lld.md): the
+ * pad + channel-row/readout geometry; composes ui-slider/ui-text-field/ui-swatch (already imported above). */
+@import './controls/color-picker/color-picker.css';
+
+/* ADR-0134 — ui-textarea, the multi-line FACE sibling of ui-text-field (a SEPARATE geometry law, not the
+ * single-line (scale×size)→§1-row lookup text-field.css uses — see textarea.css's own header). */
+@import './controls/textarea/textarea.css';

package/dist/controls/_base/index.d.ts

@@ -0,0 +1,3 @@
+export { UIIndicatorElement } from './indicator-element.js';
+export { UIRangeElement } from './range-element.js';
+export { UIListboxElement } from './listbox-element.js';

package/dist/controls/_base/index.js

@@ -0,0 +1,9 @@
+// controls/_base/ — the shared control-base sub-layer (analogous to _surface/ for layout primitives).
+// Exports the abstract bases leaf controls extend; NOT re-exported from the top-level controls/index.ts
+// (the ui-* family barrel) — only the leaf controls that extend these classes are the public surface.
+//
+// Import these in leaf control files:
+//   import { UIIndicatorElement } from '../_base/index.ts'  // (from controls/{name}/)
+export { UIIndicatorElement } from "./indicator-element.js";
+export { UIRangeElement } from "./range-element.js";
+export { UIListboxElement } from "./listbox-element.js";

package/dist/controls/_base/indicator-element.d.ts

@@ -0,0 +1,132 @@
+import { UIFormElement, type ReactiveProps } from '../../dom/index.js';
+import type { FormValue } from '../../dom/index.js';
+declare const indicatorProps: {
+    checked: {
+        reflect: true;
+        type: import("../../index.js").PropType<boolean>;
+        default: boolean;
+        attribute?: string | false;
+    };
+    value: {
+        reflect: true;
+        type: import("../../index.js").PropType<string>;
+        default: string;
+        attribute?: string | false;
+    };
+    size: {
+        reflect: true;
+        type: import("../../index.js").PropType<"sm" | "md" | "lg">;
+        default: "sm" | "md" | "lg";
+        attribute?: string | false;
+    };
+    name: {
+        reflect: true;
+        type: import("../../index.js").PropType<string>;
+        default: string;
+        attribute?: string | false;
+    };
+    disabled: {
+        reflect: true;
+        type: import("../../index.js").PropType<boolean>;
+        default: boolean;
+        attribute?: string | false;
+    };
+    required: {
+        reflect: true;
+        type: import("../../index.js").PropType<boolean>;
+        default: boolean;
+        attribute?: string | false;
+    };
+};
+export interface UIIndicatorElement extends ReactiveProps<typeof indicatorProps> {
+}
+export declare class UIIndicatorElement extends UIFormElement {
+    #private;
+    static props: {
+        checked: {
+            reflect: true;
+            type: import("../../index.js").PropType<boolean>;
+            default: boolean;
+            attribute?: string | false;
+        };
+        value: {
+            reflect: true;
+            type: import("../../index.js").PropType<string>;
+            default: string;
+            attribute?: string | false;
+        };
+        size: {
+            reflect: true;
+            type: import("../../index.js").PropType<"sm" | "md" | "lg">;
+            default: "sm" | "md" | "lg";
+            attribute?: string | false;
+        };
+        name: {
+            reflect: true;
+            type: import("../../index.js").PropType<string>;
+            default: string;
+            attribute?: string | false;
+        };
+        disabled: {
+            reflect: true;
+            type: import("../../index.js").PropType<boolean>;
+            default: boolean;
+            attribute?: string | false;
+        };
+        required: {
+            reflect: true;
+            type: import("../../index.js").PropType<boolean>;
+            default: boolean;
+            attribute?: string | false;
+        };
+    };
+    /**
+     * LLD-C2: the ARIA role this indicator carries — declared by each leaf subclass (LLD-C2).
+     * `'checkbox'` / `'switch'` / `'radio'`; the base sets `internals.role` from it in `connected()`.
+     */
+    static role: string;
+    /**
+     * LLD-C1: platform checkbox semantics — unchecked submits nothing; checked submits `this.value`.
+     */
+    protected formValue(): FormValue;
+    /**
+     * The reset baseline — native `HTMLInputElement.defaultChecked` parity: a PUBLIC, read-only reflection
+     * of the checked state this control was upgraded/connected with (see `#defaultChecked` above). Exposed
+     * so a coordinating ancestor (`ui-radio-group`) can recompute ITS OWN post-reset state from every
+     * child's default WITHOUT depending on `formResetCallback` invocation order between the group and its
+     * radios (both are separate `UIFormElement` participants the platform resets independently) — reading
+     * this getter is stable regardless of whether the group's or the radio's own reset runs first.
+     */
+    get defaultChecked(): boolean;
+    protected connected(): void;
+    /**
+     * LLD-C3: pre-toggle hook — called immediately before `this.checked` is flipped in the click handler.
+     * The base is a no-op. `UICheckboxElement` overrides this to clear `indeterminate` (so clicking an
+     * indeterminate checkbox clears the indeterminate visual and then toggles checked — platform parity).
+     * Switch and radio are binary; they do not override this.
+     */
+    protected beforeToggle(): void;
+    /**
+     * LLD-C5: grouping hook — the radio subclass overrides this to wire roving-focus + exclusive
+     * selection within a name-scoped group. Called from `connected()` after all base wiring is in place.
+     * Checkbox/switch leave it a no-op.
+     */
+    protected grouped(): void;
+    /**
+     * Form reset → checked ← `defaultChecked` (native `<input type=checkbox/radio>.defaultChecked` parity;
+     * the bug-A fix — this was missing entirely, so every Indicator control ignored BOTH reset paths:
+     * native `form.reset()` and a form-less provider's direct `formResetCallback()` call). Silent — no
+     * `input`/`change` emitted, matching text-field's own `formReset()` (a reset is not a user edit).
+     * `indeterminate` (checkbox-only) is untouched here — a reset restores the boolean `checked` value;
+     * native `<input type=checkbox>` does not reset `indeterminate` either (it is never form-serialized and
+     * carries no default of its own).
+     *
+     * A `ui-radio` inside a `ui-radio-group`: this restores THIS radio's own visual `checked` correctly, but
+     * the GROUP is a SEPARATE `UIFormElement` participant with its OWN `#selectedValue` signal — this reset
+     * alone cannot update it (no click/change event fires). `UIRadioGroupElement` carries its own
+     * `formReset()` override (radio-group.ts) that recomputes `#selectedValue` from every child's
+     * `defaultChecked` getter (above) — stable regardless of which of the two resets the platform runs first.
+     */
+    protected formReset(): void;
+}
+export {};

package/dist/controls/_base/indicator-element.js

@@ -0,0 +1,158 @@
+// indicator-element.ts — UIIndicatorElement, the shared base for the Indicator class
+// (ui-checkbox · ui-switch · ui-radio). indicator-element.lld.md.
+//
+// Owns: the boolean form value (LLD-C1), the checked-state machine + ARIA (LLD-C2), the toggle via
+// pressActivation + click (LLD-C3), and the widget-box geometry seam (LLD-C4, CSS in the subclass).
+// The subclass declares `static role` (LLD-C2), the glyph in its `.css` (LLD-C4), and (radio) the
+// group wiring via `grouped()` (LLD-C5).
+//
+// `indeterminate` is deliberately NOT in the base — it is checkbox-specific tri-state (checkbox overrides
+// `beforeToggle()` to clear it and runs its own supplemental effect). Switch and radio are binary; they
+// should not carry an indeterminate property at all.
+//
+// Layer: controls/_base/ — imports dom + traits (inward-only ✓).
+// Inward-only ✓ (controls ← traits ← dom ← reactive).
+import { UIFormElement, prop } from "../../dom/index.js";
+import { tabbable } from "../../traits/tabbable.js";
+import { pressActivation } from "../../traits/press-activation.js";
+const indicatorProps = {
+    ...UIFormElement.formProps,
+    // LLD-C1: the boolean form value; reflected so `[checked]` drives CSS + is observable as an attribute.
+    checked: { ...prop.boolean(false), reflect: true },
+    // LLD-C1: the submitted string when checked (HTML checkbox semantics, default 'on'); reflected.
+    value: { ...prop.string('on'), reflect: true },
+    // LLD-C4: the widget-box size axis — selects --md-sys-compact-{size} via [size] in the leaf's CSS (ADR-0041).
+    // All Indicator controls share this axis; each leaf's stylesheet rewires the token.
+    size: { ...prop.enum(['sm', 'md', 'lg'], 'md'), reflect: true },
+};
+export class UIIndicatorElement extends UIFormElement {
+    static props = indicatorProps;
+    /**
+     * LLD-C2: the ARIA role this indicator carries — declared by each leaf subclass (LLD-C2).
+     * `'checkbox'` / `'switch'` / `'radio'`; the base sets `internals.role` from it in `connected()`.
+     */
+    static role = '';
+    // LLD-C3: suppress the next click when it originated from an Enter keydown.
+    // Platform parity: Enter does NOT toggle a checkbox; but pressActivation fires host.click() on Enter,
+    // so a keydown guard registered BEFORE pressActivation marks the pending Enter-click for suppression.
+    #suppressNextClick = false;
+    // The native-parity reset baseline — `defaultChecked` (LLD-C1 extended, the bug-A fix). Captured ONCE
+    // at the FIRST connect (guarded — a later reconnect must not re-snapshot an already-toggled value; the
+    // text-field `#defaultValue`/`#defaultCaptured` precedent). Reading `this.checked` here is equivalent to
+    // reading the `checked` ATTRIBUTE (native `<input type=checkbox>.defaultChecked` parity): `checked`
+    // REFLECTS (props.ts's outbound reflect fires synchronously on every property write, including the
+    // ADR-0005 property-wins upgrade replay), so `this.hasAttribute('checked') === this.checked` holds at
+    // every point `connected()` can observe it — reading the resolved prop is equivalent and avoids
+    // re-parsing the attribute string.
+    #defaultChecked = false;
+    #defaultCaptured = false;
+    /**
+     * LLD-C1: platform checkbox semantics — unchecked submits nothing; checked submits `this.value`.
+     */
+    formValue() {
+        return this.checked ? this.value : null;
+    }
+    /**
+     * The reset baseline — native `HTMLInputElement.defaultChecked` parity: a PUBLIC, read-only reflection
+     * of the checked state this control was upgraded/connected with (see `#defaultChecked` above). Exposed
+     * so a coordinating ancestor (`ui-radio-group`) can recompute ITS OWN post-reset state from every
+     * child's default WITHOUT depending on `formResetCallback` invocation order between the group and its
+     * radios (both are separate `UIFormElement` participants the platform resets independently) — reading
+     * this getter is stable regardless of whether the group's or the radio's own reset runs first.
+     */
+    get defaultChecked() {
+        return this.#defaultChecked;
+    }
+    connected() {
+        // Seed the reset baseline ONCE from the checked state at first connect (see `#defaultChecked` above).
+        if (!this.#defaultCaptured) {
+            this.#defaultChecked = this.checked;
+            this.#defaultCaptured = true;
+        }
+        const ctor = this.constructor;
+        // LLD-C2: set the ARIA role from the subclass's static declaration. Never a host attribute (FACE).
+        this.internals.role = ctor.role;
+        // LLD-C3: tabbable — tabindex=0 while enabled, removed from the tab order while disabled (ADR-0010).
+        tabbable(this, { disabled: () => this.effectiveDisabled() });
+        // LLD-C3: Enter suppressor — must register BEFORE pressActivation so this keydown handler runs
+        // first. pressActivation fires host.click() on Enter keydown; that synthetic click is suppressed
+        // in the click handler below. Disabled-guarded: pressActivation also early-returns while disabled,
+        // so a disabled-Enter must not arm the flag (else the next enabled mouse-click would be swallowed).
+        this.listen(this, 'keydown', (event) => {
+            if (!this.effectiveDisabled() && event.key === 'Enter') {
+                this.#suppressNextClick = true;
+            }
+        });
+        // LLD-C3: pressActivation — Space activates on keyup; Enter fires host.click() (suppressed below).
+        pressActivation(this, { disabled: () => this.effectiveDisabled() });
+        // LLD-C3: click → toggle checked (mouse clicks + Space-activated synthetic clicks; Enter suppressed).
+        // `beforeToggle()` is called first so subclasses can hook in pre-toggle side effects (checkbox clears
+        // its `indeterminate` here; switch/radio leave it a no-op via the base implementation).
+        this.listen(this, 'click', () => {
+            if (this.#suppressNextClick) {
+                this.#suppressNextClick = false;
+                return; // Enter-click: no toggle (platform checkbox parity)
+            }
+            if (this.effectiveDisabled())
+                return;
+            this.beforeToggle();
+            this.checked = !this.checked;
+            this.emit('input');
+            this.emit('change');
+        });
+        // LLD-C2: checked-state effect — reactive on `checked`, publishes:
+        //   · custom state :state(checked) (CustomStateSet, absent in jsdom)
+        //   · internals.ariaChecked ("true" / "false") — the jsdom-accessible ARIA proxy.
+        // NOTE: `indeterminate` is NOT tracked here — checkbox adds its own supplemental effect (which runs
+        // after this one) to override ariaChecked="mixed" and :state(indeterminate) when needed.
+        this.effect(() => {
+            const checked = this.checked;
+            const states = this.internals.states; // CustomStateSet; absent in jsdom (optional-chained below)
+            if (checked) {
+                states?.add('checked');
+                this.internals.ariaChecked = 'true';
+            }
+            else {
+                states?.delete('checked');
+                this.internals.ariaChecked = 'false';
+            }
+        });
+        // LLD-C3: ariaDisabled mirrors effectiveDisabled() — reactive, scope-owned (same form as button.ts).
+        this.effect(() => {
+            this.internals.ariaDisabled = this.effectiveDisabled() ? 'true' : null;
+        });
+        // LLD-C5: delegate to the subclass's group wiring (radio overrides; checkbox/switch leave it no-op).
+        this.grouped();
+    }
+    /**
+     * LLD-C3: pre-toggle hook — called immediately before `this.checked` is flipped in the click handler.
+     * The base is a no-op. `UICheckboxElement` overrides this to clear `indeterminate` (so clicking an
+     * indeterminate checkbox clears the indeterminate visual and then toggles checked — platform parity).
+     * Switch and radio are binary; they do not override this.
+     */
+    beforeToggle() { }
+    /**
+     * LLD-C5: grouping hook — the radio subclass overrides this to wire roving-focus + exclusive
+     * selection within a name-scoped group. Called from `connected()` after all base wiring is in place.
+     * Checkbox/switch leave it a no-op.
+     */
+    grouped() { }
+    /**
+     * Form reset → checked ← `defaultChecked` (native `<input type=checkbox/radio>.defaultChecked` parity;
+     * the bug-A fix — this was missing entirely, so every Indicator control ignored BOTH reset paths:
+     * native `form.reset()` and a form-less provider's direct `formResetCallback()` call). Silent — no
+     * `input`/`change` emitted, matching text-field's own `formReset()` (a reset is not a user edit).
+     * `indeterminate` (checkbox-only) is untouched here — a reset restores the boolean `checked` value;
+     * native `<input type=checkbox>` does not reset `indeterminate` either (it is never form-serialized and
+     * carries no default of its own).
+     *
+     * A `ui-radio` inside a `ui-radio-group`: this restores THIS radio's own visual `checked` correctly, but
+     * the GROUP is a SEPARATE `UIFormElement` participant with its OWN `#selectedValue` signal — this reset
+     * alone cannot update it (no click/change event fires). `UIRadioGroupElement` carries its own
+     * `formReset()` override (radio-group.ts) that recomputes `#selectedValue` from every child's
+     * `defaultChecked` getter (above) — stable regardless of which of the two resets the platform runs first.
+     */
+    formReset() {
+        this.checked = this.#defaultChecked;
+    }
+}

package/dist/controls/_base/listbox-element.d.ts

@@ -0,0 +1,70 @@
+import { UIFormElement, type ReactiveProps } from '../../dom/index.js';
+import type { FormValue, ValidityResult } from '../../dom/index.js';
+declare const listboxProps: {
+    multiple: {
+        reflect: true;
+        type: import("../../index.js").PropType<boolean>;
+        default: boolean;
+        attribute?: string | false;
+    };
+    name: {
+        reflect: true;
+        type: import("../../index.js").PropType<string>;
+        default: string;
+        attribute?: string | false;
+    };
+    disabled: {
+        reflect: true;
+        type: import("../../index.js").PropType<boolean>;
+        default: boolean;
+        attribute?: string | false;
+    };
+    required: {
+        reflect: true;
+        type: import("../../index.js").PropType<boolean>;
+        default: boolean;
+        attribute?: string | false;
+    };
+};
+export interface UIListboxElement extends ReactiveProps<typeof listboxProps> {
+}
+export declare class UIListboxElement extends UIFormElement {
+    #private;
+    static props: {
+        multiple: {
+            reflect: true;
+            type: import("../../index.js").PropType<boolean>;
+            default: boolean;
+            attribute?: string | false;
+        };
+        name: {
+            reflect: true;
+            type: import("../../index.js").PropType<string>;
+            default: string;
+            attribute?: string | false;
+        };
+        disabled: {
+            reflect: true;
+            type: import("../../index.js").PropType<boolean>;
+            default: boolean;
+            attribute?: string | false;
+        };
+        required: {
+            reflect: true;
+            type: import("../../index.js").PropType<boolean>;
+            default: boolean;
+            attribute?: string | false;
+        };
+    };
+    /**
+     * LLD-C3: the selected option's `value` attribute (single mode), or a newline-joined list
+     * (multi mode), or `null` when nothing is selected.
+     */
+    protected formValue(): FormValue;
+    /**
+     * LLD-C3: `required` + nothing selected → `{ valid: false, flags: { valueMissing: true } }`.
+     */
+    protected formValidity(): ValidityResult;
+    protected connected(): void;
+}
+export {};

package/dist/controls/_base/listbox-element.js

@@ -0,0 +1,74 @@
+// listbox-element.ts — UIListboxElement, the form-associated listbox base
+// (ui-listbox · ui-select options popup · ui-combo-box options popup). listbox-roving LLD-C3.
+//
+// Owns: `role=listbox` (via internals), the form value (the selected option's `value` string, or
+// a `\n`-joined list for multi), `required` → `valueMissing`, and the wiring of `rovingFocus` +
+// `selectionCommit` over its `[role=option]` children.
+//
+// The options are light-DOM children (`ui-option` or `<li role=option>`); the host carries no role
+// attribute (FACE internals). ui-menu is NOT this class — it is a plain UIElement + rovingFocus
+// (no form value; role=menu; LLD-C4 in listbox-roving.lld.md).
+//
+// Layer: controls/_base/ — imports dom + traits (inward-only ✓).
+// Inward-only ✓ (controls ← traits ← dom ← reactive).
+import { signal } from "../../reactive/index.js";
+import { UIFormElement, prop } from "../../dom/index.js";
+import { rovingFocus } from "../../traits/roving-focus.js";
+import { selectionCommit } from "../../traits/selection-commit.js";
+const listboxProps = {
+    ...UIFormElement.formProps,
+    // multi-select: a Set of selected keys vs. at most one. Reflected so `[multiple]` drives CSS.
+    multiple: { ...prop.boolean(false), reflect: true },
+};
+export class UIListboxElement extends UIFormElement {
+    static props = listboxProps;
+    // LLD-C3: the committed selection, updated by selectionCommit's `onSelect` callback.
+    // Single mode: a string key ('' = nothing selected).
+    // Multi mode: a ReadonlySet<string> (empty Set = nothing selected).
+    // Both empty cases return null from formValue(). The codec is value-agnostic — formValue() /
+    // formValidity() handle both union arms uniformly.
+    #selection = signal('');
+    /**
+     * LLD-C3: the selected option's `value` attribute (single mode), or a newline-joined list
+     * (multi mode), or `null` when nothing is selected.
+     */
+    formValue() {
+        const sel = this.#selection.value;
+        if (typeof sel === 'string')
+            return sel === '' ? null : sel;
+        if (sel.size === 0)
+            return null;
+        return [...sel].join('\n');
+    }
+    /**
+     * LLD-C3: `required` + nothing selected → `{ valid: false, flags: { valueMissing: true } }`.
+     */
+    formValidity() {
+        const sel = this.#selection.value;
+        const empty = typeof sel === 'string' ? sel === '' : sel.size === 0;
+        if (this.required && empty) {
+            return { valid: false, flags: { valueMissing: true }, message: 'Please select an option.' };
+        }
+        return { valid: true };
+    }
+    connected() {
+        // LLD-C3: set ARIA role via internals — never a host attribute (FACE).
+        this.internals.role = 'listbox';
+        // LLD-C3: live accessor for [role=option] children (re-read per event for dynamic item sets).
+        const items = () => [...this.querySelectorAll('[role=option]')];
+        // LLD-C3: key extractor — the option's `value` attribute ('' = no key, skipped by selectionCommit).
+        const keyOf = (el) => el.getAttribute('value') ?? '';
+        // LLD-C3: roving-focus over the option set (vertical orientation, looping, type-ahead on by default).
+        rovingFocus(this, { items });
+        // LLD-C3: selection-commit — mode from the `multiple` prop at connect time; onSelect updates
+        // #selection, which drives formValue() + formValidity() reactively via the UIFormElement effects.
+        selectionCommit(this, {
+            mode: this.multiple ? 'multi' : 'single',
+            items,
+            keyOf,
+            onSelect: (selection) => {
+                this.#selection.value = selection;
+            },
+        });
+    }
+}