@agent-ui-kit/components 0.0.3

package/dist/controls/progress/progress.css

@@ -0,0 +1,106 @@
+/* progress.css — ui-progress, the Display-class thin-rail progress bar (LLD-C1, feed-family.lld.md §2;
+ * SPEC-R2/R18/R19/R20; ADR-0112 cl.2). Two sectioned blocks:
+ *
+ *   [1] TOKEN BLOCK — `:where(ui-progress)` declares `--ui-progress-*`: a DENSITY-INVARIANT thin rail
+ *       thickness (the slider-rail precedent verbatim, slider.css:76-79 — a bar is a rail, NOT a
+ *       `--md-sys-compact-*` widget box) + the whole-shape floor (SPEC-R18 AC1, the slider-dot collapse
+ *       lesson) + track/fill color roles (track = `--md-sys-color-neutral-track`, the ADR-0059 solid-track
+ *       role; fill = the primary role).
+ *   [2] STYLES BLOCK — `@scope (ui-progress)` consumes ONLY `--ui-progress-*`.
+ *
+ * Display class (SPEC-R20): no [size]/[scale] control-band lookup, no `--md-sys-height-*`, no `h/2` centering
+ * law — the rail is a fixed px constant regardless of [density]/[scale] (SPEC-R18 AC3).
+ *
+ * RTL (SPEC-R2 AC3): the fill's `inset-inline-start` is a LOGICAL property — the determinate fill and the
+ * indeterminate sweep both mirror for free under `dir="rtl"`; no dedicated per-direction rule is needed.
+ *
+ * Motion (SPEC-R2 AC2): indeterminate animates `inset-inline-start` (a translating sweep). Under
+ * `prefers-reduced-motion: reduce` the sweep is replaced by a STATIONARY partial fill with a slow
+ * opacity pulse — no translation, no scaling — that stays visually distinct from any determinate state.
+ * The keyframes live at stylesheet TOP LEVEL (outside `@scope`) — scoped `@keyframes` name resolution is
+ * exactly the kind of engine variance the fleet doesn't need (LLD-C1); names are `ui-progress-*`-prefixed.
+ *
+ * Forced colors (SPEC-R19): a background-drawn fill vanishes under WHCM (the bar-chart lesson,
+ * bar-chart.css:101-107) — an explicit `forced-colors` block repoints the fill to `CanvasText` and keeps
+ * the track distinguishable (`Canvas` + a `CanvasText` border).
+ */
+
+/* ════════════════ [1] TOKEN BLOCK — :where(ui-progress) declares --ui-progress-* ════════════════ */
+
+:where(ui-progress) {
+  --ui-progress-track-size: 4px; /* thin rail — density-invariant constant (slider.css:76-79 kin) */
+  --ui-progress-min-inline-size: 8em; /* the whole-shape floor (SPEC-R18 AC1; the slider-dot lesson) */
+  --ui-progress-track-ink: var(--md-sys-color-neutral-track); /* the ADR-0059 solid-track role */
+  --ui-progress-fill-ink: var(--md-sys-color-primary);
+}
+
+/* ════════════════ [2] STYLES BLOCK — @scope (ui-progress) consumes ONLY --ui-progress-* ════════════════ */
+
+@scope (ui-progress) {
+  :scope {
+    display: block;
+    min-inline-size: var(--ui-progress-min-inline-size);
+  }
+
+  :scope [data-part='track'] {
+    display: block;
+    position: relative;
+    overflow: hidden;
+    block-size: var(--ui-progress-track-size);
+    border-radius: calc(var(--ui-progress-track-size) / 2);
+    background: var(--ui-progress-track-ink);
+  }
+
+  :scope [data-part='fill'] {
+    position: absolute;
+    inset-block: 0;
+    inset-inline-start: 0;
+    inline-size: calc(var(--_pct, 0) * 1%);
+    background: var(--ui-progress-fill-ink);
+    border-radius: inherit;
+  }
+
+  :scope [data-part='fill'][data-indeterminate] {
+    /* the sweep (SPEC-R2 AC2) — a partial-width fill translating along the track */
+    inline-size: 40%;
+    animation: ui-progress-sweep 1.5s linear infinite;
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    :scope [data-part='fill'][data-indeterminate] {
+      /* stationary; opacity-only — no translation, no scaling (SPEC-R2 AC2) */
+      inset-inline-start: 30%;
+      animation: ui-progress-pulse 2s ease-in-out infinite;
+    }
+  }
+
+  @media (forced-colors: active) {
+    /* the bar-chart lesson (SPEC-R19) — a background-drawn fill otherwise vanishes */
+    :scope [data-part='fill'] {
+      background: CanvasText;
+    }
+    :scope [data-part='track'] {
+      background: Canvas;
+      border: 1px solid CanvasText;
+    }
+  }
+}
+
+@keyframes ui-progress-sweep {
+  from {
+    inset-inline-start: -40%;
+  }
+  to {
+    inset-inline-start: 100%;
+  }
+}
+
+@keyframes ui-progress-pulse {
+  0%,
+  100% {
+    opacity: 0.35;
+  }
+  50% {
+    opacity: 1;
+  }
+}

package/dist/controls/progress/progress.d.ts

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

package/dist/controls/progress/progress.js

@@ -0,0 +1,80 @@
+// progress.ts — UIProgressElement, the Display-class thin-rail progress bar (LLD-C1, feed-family.lld.md
+// §2; SPEC-R1/R2/R3/R18/R19/R20; ADR-0112 cl.2). Non-interactive, non-form-associated leaf: no events, no
+// keyboard contract, no [size]/[scale] control geometry — a bar is a rail, not a widget box. Value model
+// mirrors the native <progress> semantic: `value === null` (default) ⇒ INDETERMINATE, never a separate
+// boolean to desync. `render()` stays the inherited no-op — the track/fill pair is built once in
+// `connected()` (survives reconnect via the private field guard) and mutated per-change by two effects.
+//
+// Hardening (SPEC-R1's table) is a pure in-file pair — the math is two clamps, no separate module:
+// `effectiveMax` floors a non-finite/≤0/malformed `max` to the ARIA default (100); `effectiveValue` maps
+// an absent/non-finite `value` to `null` (indeterminate) and clamps a real value into [0, effectiveMax].
+// No case throws — every input, however malformed, resolves to a paintable, announced state.
+import { UIElement, prop } from "../../dom/index.js";
+const props = {
+    current: prop.number(null), // null ⇒ indeterminate (the native <progress> semantic — no boolean to desync). Renamed from `value` (TKT-0069 item 1 ruling: `value` = the FACE form value, reserved — this rename spends real native-<progress> parity deliberately; the A2UI catalog keeps wire `value`, mapped in its bespoke factory)
+    max: prop.number(100), // the ARIA progressbar default — percent-natural for {value:42} with zero extra props
+    label: { ...prop.string(''), reflect: true }, // the accessible name (SPEC-R3); empty ⇒ no internals.ariaLabel
+};
+/** SPEC-R1: non-finite / ≤0 / malformed `max` floors to the ARIA progressbar default. */
+function effectiveMax(max) {
+    return max !== null && Number.isFinite(max) && max > 0 ? max : 100;
+}
+/** SPEC-R1: absent/non-finite `value` ⇒ null (indeterminate); else clamped into [0, eMax]. */
+function effectiveValue(value, eMax) {
+    return value === null || !Number.isFinite(value) ? null : Math.min(Math.max(value, 0), eMax);
+}
+// Module-memoized (SPEC-R3): the percent reading behind `ariaValueText`, default locale.
+const percentFormat = new Intl.NumberFormat(undefined, { style: 'percent', maximumFractionDigits: 0 });
+export class UIProgressElement extends UIElement {
+    static props = props;
+    #track = null;
+    #fill = null;
+    connected() {
+        // Built ONCE (LLD-C1) — a private-field guard so a reconnect (children survive removal/re-append)
+        // never mints a second track/fill pair.
+        if (!this.#track) {
+            this.#track = document.createElement('span');
+            this.#track.setAttribute('data-part', 'track');
+            this.#fill = document.createElement('span');
+            this.#fill.setAttribute('data-part', 'fill');
+            this.#track.append(this.#fill);
+            this.append(this.#track);
+        }
+        const fill = this.#fill;
+        // Mark effect (SPEC-R2): determinate ⇒ the fill's --_pct custom property; indeterminate ⇒
+        // data-indeterminate on the fill (an interior node, never a host attribute — CSS drives the sweep).
+        this.effect(() => {
+            const eMax = effectiveMax(this.max);
+            const eValue = effectiveValue(this.current, eMax);
+            if (eValue === null) {
+                fill.setAttribute('data-indeterminate', '');
+                fill.style.removeProperty('--_pct');
+            }
+            else {
+                fill.removeAttribute('data-indeterminate');
+                fill.style.setProperty('--_pct', String((eValue / eMax) * 100));
+            }
+        });
+        // ARIA effect (SPEC-R3): role=progressbar is ALWAYS set — status data, never silent (the chart
+        // inversion, ADR-0112 cl.2). Determinate publishes ariaValueNow/Text; indeterminate omits both while
+        // role/min/max persist — the ARIA-native indeterminate signal.
+        this.effect(() => {
+            const eMax = effectiveMax(this.max);
+            const eValue = effectiveValue(this.current, eMax);
+            this.internals.role = 'progressbar';
+            this.internals.ariaValueMin = '0';
+            this.internals.ariaValueMax = String(eMax);
+            if (eValue === null) {
+                this.internals.ariaValueNow = null;
+                this.internals.ariaValueText = null;
+            }
+            else {
+                this.internals.ariaValueNow = String(eValue);
+                this.internals.ariaValueText = percentFormat.format(eValue / eMax);
+            }
+            this.internals.ariaLabel = this.label || null;
+        });
+    }
+}
+if (!customElements.get('ui-progress'))
+    customElements.define('ui-progress', UIProgressElement); // idempotent self-define

package/dist/controls/radio/radio-group.css

@@ -0,0 +1,84 @@
+/* radio-group.css — ui-radio-group, the radio-button container stylesheet (Wave 1 S3, ADR-0003).
+ *
+ * The container convention requires a .css even for a small layout footprint (process.md §4,
+ * container-family rule): every FACE component ships a stylesheet that at minimum carries the
+ * `:where(ui-{name})` token block and the `@scope (ui-{name})` block. The group has no visual surface of
+ * its own — its `ui-radio` children carry all visible affordances — but it DOES own its interior layout
+ * (ADR-0103); its forced-colors block stays minimal.
+ *
+ * ADR-0086 previously grew a "segmented" presentation variant here (a joined-button track + one shared
+ * moving highlight, keyed off `[variant='segmented']`). ADR-0095 supersedes that architecture: the segmented
+ * presentation is now the standalone `ui-segmented-control` (controls/segmented-control/segmented-control.css)
+ * — a hard cutover, no alias. This file is restored to its pre-ADR-0086 truth for presentation; ADR-0103
+ * then fills the token block's long-reserved seat with the group's OWN layout token (not a variant).
+ *
+ * ADR-0103 (the spacing pair): a value-owning group whose children must be its DIRECT children
+ * (radio-group.ts:194's `[...this.children].filter(...)`) cannot be fixed by composition — wrapping the
+ * radios in a `ui-column` would sever discovery. So the group owns the SAME flex structure the site used to
+ * hand-author per-page (component-preview.css, now deleted): a vertical stack by default,
+ * `[orientation='horizontal']` a wrapping row — with the gap re-based to the `--md-sys-space` ladder (`sm`) so it
+ * rides `[density]` for free, rather than the site's hard-coded `0.4rem`/`--md-sys-space-md` duplicates.
+ *
+ * Standalone stylesheet — linked via the component-styles barrel (s12, after radio.css); NEVER injected
+ * from radio-group.ts (behaviour-only `.ts`, no runtime style injection — plan §2).
+ */
+
+/* ════════════ [1] TOKEN BLOCK — :where(ui-radio-group) (specificity 0,0,0) ════════════ */
+
+:where(ui-radio-group) {
+  /* ADR-0103: the group's own interior gap, off the layout ladder (density-responsive for free) — the seat
+     this block's comment reserved ("future density/gap props without a cascade-order change"). Page authors
+     retune per-instance with one custom property (the ADR-0102 override freedom); no catalog `gap` enum yet
+     (a foreseen Lane B extension only if live evidence shows models need magnitude control). */
+  --ui-radio-group-gap: var(--md-sys-space-sm);
+
+  /* user-invalid (ADR-0051) — the danger border repoint reaching into each ui-radio child's own
+     ::before ring (the group has no visual surface of its own, see the file header). Appears only
+     AFTER the first interaction (the trackUserInvalid controller owns that timing; radio-group.ts
+     toggles :state(user-invalid) on the group host). */
+  --ui-radio-group-border-invalid: var(--md-sys-color-danger);
+}
+
+/* ════════════ [2] STYLES BLOCK — @scope (ui-radio-group) ════════════ */
+
+@scope (ui-radio-group) {
+  /* ADR-0103: a vertical stack by default — the roving-focus axis (Arrow Up/Down, radio-group.ts's
+     `defaultOrientation()`) and the visual axis are now the SAME source of truth. No explicit block-size or
+     inline-size — the group sizes to its content; only the gap is opinionated. */
+  :scope {
+    display: flex;
+    flex-direction: column;
+    gap: var(--ui-radio-group-gap);
+  }
+
+  /* `[orientation='horizontal']` (reflected once at connect, radio-group.ts's connected()) switches to a
+     wrapping row — `flex-wrap: wrap` is graceful degradation in a cramped container (the ADR-0016 row-side
+     philosophy), and `align-items: center` keeps radios of differing label height on one visual baseline. */
+  :scope[orientation='horizontal'] {
+    flex-direction: row;
+    flex-wrap: wrap;
+    align-items: center;
+  }
+
+  /* Forced colors (WHCM) — no visual surface of its own: the ui-radio children carry their own
+     forced-color treatments. This block is present for fleet discipline (every FACE control's scope
+     includes a forced-colors rule). */
+  @media (forced-colors: active) {
+    :scope {
+      /* no group-level WHCM adjustments; the children carry their own forced-color rules */
+      forced-color-adjust: none;
+    }
+  }
+}
+
+/* ════════════ user-invalid (ADR-0051) — a cross-boundary reach into ui-radio's own paint ════════════
+ * The group carries no visual surface of its own (the [2] block above); the danger repoint must reach
+ * INTO each `ui-radio` child's own `::before` ring instead. A plain top-level compound selector,
+ * deliberately OUTSIDE `@scope` — the SAME technique segmented-control.css uses to reach `ui-segment`
+ * (its own file header explains why: this clears `ui-radio`'s own `@scope (ui-radio) { :scope::before }`
+ * rule ((0,1,1)) without `!important`, since `ui-radio-group:state(user-invalid) ui-radio::before` is
+ * (0,1,3)). Never co-occurs with `:state(checked)::before` in practice — `formValidity()` only reports
+ * `valueMissing` when NO radio is checked, so no specificity race with the checked-fill rule. */
+ui-radio-group:state(user-invalid) ui-radio::before {
+  border-color: var(--ui-radio-group-border-invalid);
+}

package/dist/controls/radio/radio-group.d.ts

@@ -0,0 +1,152 @@
+import { UIFormElement } from '../../dom/form.js';
+import type { FormValue, ValidityResult } from '../../dom/form.js';
+import { type ReactiveProps } from '../../dom/props.js';
+import { type RovingOrientation } from '../../traits/roving-focus.js';
+import { UIRadioElement } from './radio.js';
+declare const groupProps: {
+    orientation: {
+        reflect: true;
+        type: import("../../index.js").PropType<"horizontal" | "vertical">;
+        default: "horizontal" | "vertical";
+        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 UIRadioGroupElement extends ReactiveProps<typeof groupProps> {
+}
+export declare class UIRadioGroupElement extends UIFormElement {
+    #private;
+    static props: {
+        orientation: {
+            reflect: true;
+            type: import("../../index.js").PropType<"horizontal" | "vertical">;
+            default: "horizontal" | "vertical";
+            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;
+        };
+    };
+    protected connected(): void;
+    /**
+     * The group's selected value — the checked `ui-radio` child's `value`, or `null` when none is
+     * selected. A public getter/setter pair delegating to the private `#selectedValue` signal (the
+     * `UICheckboxElement.indeterminate` precedent, checkbox.ts:39 — a plain accessor over a private
+     * signal, not a `prop.*`-declared attribute: the value is DERIVED from child radio state, so it
+     * has nothing of its own to reflect).
+     *
+     * The getter reads the signal directly — a reactive caller (e.g. inside `this.effect`) tracks it
+     * exactly like any other signal read.
+     *
+     * The setter is the PROGRAMMATIC path (e.g. a two-way data-bind write): it selects the child
+     * `ui-radio` whose `value` matches (unchecking all others) via `#applySelection` — the SAME state
+     * transition `#commit` drives for a user click/keyboard commit — but it does NOT emit `change`.
+     * This matches the fleet convention for a programmatic prop write on a value-bearing control
+     * (`UICheckboxElement.checked` / `UISelectElement.value` are directly settable and never
+     * self-emit on assignment; only the interaction-driven commit path — `#commit` here — emits).
+     *
+     * `null` clears the selection (unchecks every radio). A value matching NO child radio also CLEARS
+     * the selection, rather than a silent no-op — the native `HTMLSelectElement.value` precedent:
+     * assigning a `<select>`'s `.value` to a string with no matching `<option>` resolves
+     * `selectedIndex` to `-1` (the value reads back as `''`) instead of leaving the prior selection
+     * in place.
+     */
+    get value(): string | null;
+    set value(v: string | null);
+    /**
+     * ADR-0095 clause 1 — the CLASS-derived default roving-axis orientation, consulted by `connected()`'s
+     * resolve-once-and-reflect ONLY when no explicit `orientation` attribute is authored. This base returns
+     * `'vertical'` (today's shipped roving, unchanged). `UISegmentedControlElement` overrides this to
+     * `'horizontal'` — the ADR-0086 "variant=segmented ⇒ horizontal" default, now class-derived instead of
+     * variant-derived.
+     */
+    protected defaultOrientation(): RovingOrientation;
+    /**
+     * ADR-0095 clause 2 — a protected, no-op-in-the-base post-selection hook, fired from every
+     * selection-DEFINING event: the connect-time seed, every `#applySelection` (both `#commit`'s user-driven
+     * path AND the public `value` setter's programmatic path), and `formReset()`. This is the SAME seam
+     * ADR-0086's (now-retired) private `#writeIndexCount` fired from — moved here, as a protected hook,
+     * so `UISegmentedControlElement` can write its own `--ui-segmented-control-index`/`-count` moving-
+     * indicator state WITHOUT this base class knowing anything about segments or indicators. A no-op here
+     * costs nothing for the plain dot-group presentation.
+     */
+    protected selectionChanged(_radios: UIRadioElement[], _index: number): void;
+    /**
+     * The group's form value: the selected radio's `value`, or `null` when nothing is checked.
+     * Reads `#selectedValue.value` (a signal) so the UIFormElement base's scope-owned setFormValue
+     * effect re-runs automatically when selection changes.
+     */
+    protected formValue(): FormValue;
+    /**
+     * Validity: `required` + no selection → `valueMissing`. Reads `#selectedValue.value` so the
+     * UIFormElement base's setValidity effect re-runs when selection changes. An empty, required group
+     * stays invalid until a radio is committed; a non-required empty group is always valid.
+     */
+    protected formValidity(): ValidityResult;
+    /**
+     * Form reset — group-level coordination (bug-A fix). Each child radio is its OWN `UIFormElement`
+     * participant with its OWN `formResetCallback` (now fixed, indicator-element.ts) that silently restores
+     * ITS `checked` to ITS `defaultChecked` — but the GROUP owns a SEPARATE `#selectedValue` signal
+     * (`formValue()`/`formValidity()` above), which no radio's own reset can reach. Recompute it here from
+     * every child's `defaultChecked` (a stable, native-parity PUBLIC getter — see UIIndicatorElement) rather
+     * than each child's live `checked`: the platform resets the group and its radios as INDEPENDENT
+     * `UIFormElement`s, in an order this class must not assume (tree order suggests ancestor-first, i.e.
+     * this runs BEFORE the radios' own resets — reading live `checked` here would see PRE-reset values).
+     * `defaultChecked` sidesteps the ordering question entirely: it is a fixed snapshot from each radio's
+     * first connect, unaffected by reset order on either side. Silent — no `change` emitted (a reset is not
+     * a user commit; matches `#commit`'s own emit-on-user-action-only discipline).
+     *
+     * Bug fix (component-reviewer B4, blocking; ADR-0086, preserved verbatim by ADR-0095 clause 2): a reset
+     * must ALSO fire the post-selection hook (`selectionChanged`). The hook was previously (ADR-0086) a
+     * private `#writeIndexCount` written only at connect and in `#commit` — but a radio's own reset
+     * (`indicator-element.ts`) restores its `checked` OUTSIDE `#commit`, so without this the seam desyncs
+     * in a subclass that consumes it (e.g. `UISegmentedControlElement`'s moving indicator): the CSS
+     * `:not(:has(ui-radio[checked]))`-style gate correctly re-shows the indicator (the DOM `[checked]` is
+     * genuinely restored), but a STALE index would still park the moving fill on the pre-reset selection —
+     * a visible indicator/ink mismatch. Recomputed from `defaultChecked` for the same reset-order-
+     * independence reason as `#selectedValue` above (not live `checked`, which may not have reset yet on
+     * this radio's siblings). `findIndex` returns `-1` when no radio was ever default-checked; a consuming
+     * subclass's hook is expected to clamp that to `0` the same way ADR-0086's seam did — harmless, since a
+     * segmented indicator hides itself whenever nothing is `[checked]`.
+     */
+    protected formReset(): void;
+    protected disconnected(): void;
+    /** Feeds `FormConnectDetail.userInvalid` (ADR-0050) — the `trackUserInvalid` tracker IS the one
+     *  timing source; this override just exposes its gate. Inherited by `UISegmentedControlElement`
+     *  unchanged (it never overrides connected()/formReset(), so this base's wiring applies to its
+     *  own internals directly). */
+    protected formUserInvalid(): boolean;
+}
+export {};