@agent-ui-kit/components 0.0.3

package/dist/controls/textarea/textarea.js

@@ -0,0 +1,312 @@
+// textarea.ts — UITextareaElement, the FACE multi-line text primitive (ADR-0134; a SIBLING of ui-text-field,
+// NOT a text-field mode). BEHAVIOUR + props + the contenteditable editor part + self-define ONLY;
+// geometry/colour live in textarea.css (its OWN multi-line law, not the single-line (scale×size)→§1-row
+// lookup), the public contract in textarea.md.
+//
+// Editable surface — the ADR-0014 contenteditable PATTERN reused verbatim: a stable, control-created
+// light-DOM `<div data-part="editor" contenteditable="plaintext-only" role="textbox" aria-multiline="true">`,
+// appended ONCE (an idempotent guard) and NEVER re-rendered. `value`↔surface is the same two scope-owned
+// wires as ui-text-field (surface→model on `input`, model→surface under the CARET GUARD), both suppressed
+// during IME composition.
+//
+// The INVERSION from ui-text-field (ADR-0134's whole reason to be a sibling, not a mode): `aria-multiline`
+// is `true`, and `Enter` is NOT intercepted — it inserts a newline exactly like a native `<textarea>`, and
+// commit is BLUR-with-change ONLY (never Enter). Geometry inverts too: `rows` sets a GROWABLE
+// `min-block-size`, real `padding-block`, `align-items: start`, prose `line-height`, `resize: vertical` —
+// see textarea.css for the law. No `type` prop, no adornment/overlay/codec machinery — none of that applies
+// to plain multi-line text (ADR-0134 "Decision").
+//
+// The HOST carries no `role`/`aria-*` attribute — form semantics ride `internals` (ADR-0013) and the editor
+// PART carries `role=textbox`. ARIA + the custom states are set THROUGH the protected `internals`. Disabled
+// rides the editor + the platform form-disabled channel (`effectiveDisabled = own || form`), NOT host
+// `ariaDisabled`; `readonly` is editable=false but focusable (still submits). `user-invalid` timing comes
+// from the `trackUserInvalid` controller, reinforced by a non-colour `aria-describedby` message node (WCAG
+// 1.4.1). `controls → dom + traits` is the allowed import direction.
+import { prop } from "../../dom/index.js";
+import { UIFormElement } from "../../dom/form.js";
+import { trackUserInvalid } from "../../traits/track-user-invalid.js";
+// The editor's editable mode (ADR-0014 cl.1, reused) and a per-instance id seed for aria-describedby.
+const EDITABLE = 'plaintext-only';
+let messageSeq = 0;
+// ── props ─────────────────────────────────────────────────────────────────────
+const props = {
+    // The universal form attributes (name / disabled(reflect) / required(reflect)) are SPREAD, not inherited —
+    // props.ts has no static-props prototype merge, so UIFormElement exposes them as a spreadable bag (ADR-0013).
+    ...UIFormElement.formProps,
+    // `value` is OBSERVED (its initial attribute seeds the reset baseline) but NOT reflected — the live value
+    // rides the editor surface, never a host attribute.
+    value: prop.string(),
+    label: { ...prop.string(), reflect: true }, // → the editor's aria-label (the labelling SEAM; yields under a ui-field association)
+    placeholder: prop.string(), // shown via [data-empty]::before { content: attr(data-placeholder) } when empty
+    // rows: native <textarea rows> parity — the MIN-height lever (ADR-0134), not a fixed control height. reflects
+    // so [rows] attribute-selector / attr-based CSS repoints apply to JS-set values too.
+    rows: { ...prop.number(3), reflect: true },
+    // size repoints font + block-padding + the per-row line-box in textarea.css (NOT a fixed height lever —
+    // the single-line (scale×size)→§1-row lookup does not apply here, ADR-0134).
+    size: { ...prop.enum(['sm', 'md', 'lg'], 'md'), reflect: true },
+    readonly: { ...prop.boolean(false), reflect: true },
+};
+export class UITextareaElement extends UIFormElement {
+    static props = props;
+    // The stable contenteditable editor PART + the aria-describedby message node. Light-DOM children, so they
+    // persist across disconnect/reconnect — created ONCE and never re-appended (the idempotent guard below).
+    #editor = null;
+    #message = null;
+    // The native-parity reset baseline — seeded ONCE from the initial `value` attribute (native `defaultValue`).
+    #defaultValue = '';
+    #defaultCaptured = false;
+    // The `change`-on-commit baseline (value at the last focus/commit) + the IME-composition guard.
+    #committed = '';
+    #composing = false;
+    // The user-invalid TIMING controller, created per connection (re-arms on reconnect; released on disconnect).
+    #userInvalid = null;
+    connected() {
+        // Seed the reset baseline ONCE from the INITIAL `value` attribute (native `defaultValue` — the value
+        // attribute is never reflected, so it stays the markup value and survives later property writes).
+        if (!this.#defaultCaptured) {
+            this.#defaultValue = this.getAttribute('value') ?? '';
+            this.#defaultCaptured = true;
+        }
+        const editor = this.#ensureParts();
+        const message = this.#message;
+        // ── surface → model (ADR-0014 cl.1, reused) — the editor's edits flow into `value`, IME-guarded ──
+        this.listen(editor, 'input', (event) => {
+            if (this.#composing)
+                return; // never mid-composition — compositionend commits the final composed text
+            event.stopPropagation(); // suppress the raw editor input; the host re-emits ONE composed `input` (target = host)
+            this.value = editor.textContent ?? ''; // model ← surface (the caret guard below then skips the echo write)
+            this.emit('input');
+        });
+        this.listen(editor, 'compositionstart', () => {
+            this.#composing = true;
+        });
+        this.listen(editor, 'compositionend', () => {
+            this.#composing = false;
+            this.value = editor.textContent ?? ''; // catch the model up to the composed result (the suppressed inputs)
+        });
+        // ── change on commit — blur-with-change ONLY (ADR-0134: the Enter-commits law INVERTS — Enter inserts a
+        // newline here, never commits; no keydown interception at all, unlike ui-text-field) ──
+        this.listen(editor, 'focus', () => {
+            this.#committed = this.value;
+        });
+        this.listen(editor, 'blur', () => {
+            if (this.value === this.#committed)
+                return;
+            this.#committed = this.value;
+            this.emit('change');
+        });
+        // ── the user-invalid TIMING controller — gates the danger treatment until the first blur/change ──
+        const controller = trackUserInvalid(this, { invalid: () => !this.formValidity().valid });
+        this.#userInvalid = controller;
+        // ── model → surface (ADR-0014 cl.1: the CARET GUARD) + the placeholder presence flag ──
+        this.effect(() => {
+            const value = this.value; // tracked — re-runs on every value change (typed OR programmatic/reset/restore)
+            if (this.#composing)
+                return; // never write mid-composition
+            // CARET GUARD: rewrite the editor ONLY when the model diverges from the surface, so a keystroke (which
+            // already updated textContent) never resets the caret; a programmatic write/reset/restore DOES flow.
+            if (editor.textContent !== value)
+                editor.textContent = value;
+            editor.toggleAttribute('data-empty', value === ''); // keys the CSS placeholder (not :empty — see ADR cl.1)
+        });
+        // ── editor attribute mirror — the label seam, the placeholder text, the required mirror ──
+        this.effect(() => {
+            // Yield: aria-label is the BARE stand-in only — a `ui-field` association carries the name via
+            // aria-labelledby (applyFieldLabelling below), which beats aria-label in accname resolution anyway;
+            // clearing it here keeps the editor's AX tree clean under association (the ADR-0051 pattern).
+            if (this.label && this.fieldLabelling === null)
+                editor.setAttribute('aria-label', this.label);
+            else
+                editor.removeAttribute('aria-label');
+            editor.setAttribute('data-placeholder', this.placeholder); // the CSS placeholder reads attr(data-placeholder)
+            if (this.required)
+                editor.setAttribute('aria-required', 'true');
+            else
+                editor.removeAttribute('aria-required');
+        });
+        // ── the disabled / readonly channel (ADR-0014 dev#b, reused) — effectiveDisabled = own || form-disabled ──
+        this.effect(() => {
+            if (this.effectiveDisabled()) {
+                editor.setAttribute('contenteditable', 'false');
+                editor.removeAttribute('tabindex'); // not focusable (out of the tab order, like <textarea disabled>)
+                editor.setAttribute('aria-disabled', 'true');
+                editor.removeAttribute('aria-readonly');
+                this.internals.states?.add('disabled'); // the :state(disabled) CSS hook (NOT host ariaDisabled)
+            }
+            else if (this.readonly) {
+                editor.setAttribute('contenteditable', 'false'); // not editable …
+                editor.setAttribute('tabindex', '0'); // … but still focusable / selectable (and still submits)
+                editor.removeAttribute('aria-disabled');
+                editor.setAttribute('aria-readonly', 'true');
+                this.internals.states?.delete('disabled');
+            }
+            else {
+                editor.setAttribute('contenteditable', EDITABLE); // editable; a contenteditable region is intrinsically focusable
+                editor.removeAttribute('tabindex');
+                editor.removeAttribute('aria-disabled');
+                editor.removeAttribute('aria-readonly');
+                this.internals.states?.delete('disabled');
+            }
+        });
+        // ── user-invalid → aria-invalid + the non-colour message cue + :state(user-invalid) (ADR-0014 cl.2c/4) ──
+        // Reused verbatim from ui-text-field: the message node is VISIBLE when carrying a message (ADR-0029 A1);
+        // under a `ui-field` association the internal message yields — empty, hidden, dropped from
+        // aria-describedby — so the field's own error part is the ONE AT-announced error (ADR-0051 cl.4).
+        this.effect(() => {
+            const fielded = this.fieldLabelling !== null;
+            if (controller.userInvalid()) {
+                const verdict = this.formValidity();
+                const text = verdict.valid ? '' : verdict.message;
+                editor.setAttribute('aria-invalid', 'true');
+                if (fielded) {
+                    message.textContent = '';
+                    message.hidden = true;
+                }
+                else {
+                    editor.setAttribute('aria-describedby', message.id);
+                    message.textContent = text;
+                    message.hidden = text === '';
+                }
+                this.internals.states?.add('user-invalid');
+            }
+            else {
+                editor.removeAttribute('aria-invalid');
+                if (!fielded)
+                    editor.removeAttribute('aria-describedby'); // never touch it while fielded (F3 precedent)
+                message.textContent = '';
+                message.hidden = true;
+                this.internals.states?.delete('user-invalid');
+            }
+        });
+        // ── rows → the CSS min-block-size lever (ADR-0134: rows is a MIN, not a fixed height) ──
+        this.effect(() => {
+            this.style.setProperty('--ui-textarea-rows', String(this.rows ?? 3));
+        });
+        // Motion gate (interaction-states standard) — arm `ready` ONE frame past first paint so the upgrade/first
+        // paint SNAPS and only subsequent state changes animate. `states` optional-chained — jsdom has no
+        // CustomStateSet (the real motion is the browser smoke).
+        requestAnimationFrame(() => this.internals.states?.add('ready'));
+    }
+    disconnected() {
+        this.#userInvalid?.release(); // idempotent — the controller's listeners already die with the connection scope
+        this.#userInvalid = null;
+    }
+    /** Forward host focus to the editor PART (label-association + native `.focus()` parity). */
+    focus(options) {
+        if (this.#editor)
+            this.#editor.focus(options);
+        else
+            super.focus(options);
+    }
+    /**
+     * Focus the editor and move the caret to the END of its text (a `ui-textarea`-friendly equivalent of the
+     * native `<textarea>.setSelectionRange(len, len)` a contenteditable host does not expose — the ADR-0134
+     * migration seam `entry-list.ts` uses to restore an in-progress edit after a re-render). A no-op before
+     * the editor part exists (guards a not-yet-connected control, mirroring `focus()`'s own guard above).
+     */
+    selectToEnd() {
+        const editor = this.#editor;
+        if (!editor)
+            return;
+        editor.focus();
+        const selection = editor.ownerDocument.defaultView?.getSelection() ?? window.getSelection();
+        if (!selection)
+            return;
+        const range = editor.ownerDocument.createRange();
+        range.selectNodeContents(editor);
+        range.collapse(false); // collapse to the END
+        selection.removeAllRanges();
+        selection.addRange(range);
+    }
+    // ── form hooks (overrides of the UIFormElement seams) ─────────────────────────
+    /** The value contributed to the owning form (FACE — the base publishes it via internals.setFormValue). */
+    formValue() {
+        return this.value;
+    }
+    /**
+     * The validity verdict: `required && value === ''` → `valueMissing`; valid otherwise. No codec/type
+     * validation — plain multi-line text has no value-shape to mismatch (ADR-0134). A disabled field is barred
+     * from constraint validation (native parity).
+     */
+    formValidity() {
+        if (this.effectiveDisabled())
+            return { valid: true };
+        if (this.required && this.value === '') {
+            return {
+                valid: false,
+                flags: { valueMissing: true },
+                message: 'Please fill out this field.',
+                anchor: this.#editor ?? undefined,
+            };
+        }
+        return { valid: true };
+    }
+    /**
+     * Form reset → value ← the initial `value` attribute (native-parity defaultValue) + clear the touched
+     * state (so a required-empty field does not show `:state(user-invalid)` until the user re-interacts).
+     */
+    formReset() {
+        this.value = this.#defaultValue;
+        this.#userInvalid?.reset();
+    }
+    /** Restore the value after navigation/autofill (FACE state restore). */
+    formStateRestore(state) {
+        if (typeof state === 'string')
+            this.value = state;
+    }
+    // ── ADR-0051 — the field-labelling seam wire (the ui-text-field part-role override, reused verbatim) ──────
+    /**
+     * The part-role override (ADR-0051 cl.2) — the editor's `role=textbox` rides a light-DOM PART, not
+     * `internals.role`, so the base's guarded internals-reflection default never fires here; id-reference the
+     * editor directly instead. See text-field.ts's own doc for the full ordering rationale (reused verbatim —
+     * `aria-describedby` is only WRITTEN here on association; on dissociation the user-invalid/message effect
+     * above stays the exclusive owner, avoiding a two-effect write race).
+     */
+    applyFieldLabelling(refs) {
+        const editor = this.#editor;
+        if (!editor)
+            return;
+        if (refs === null) {
+            editor.removeAttribute('aria-labelledby');
+            return;
+        }
+        if (refs.label)
+            editor.setAttribute('aria-labelledby', refs.label.id);
+        else
+            editor.removeAttribute('aria-labelledby');
+        const described = [refs.description, refs.error].filter((el) => el !== null);
+        if (described.length > 0)
+            editor.setAttribute('aria-describedby', described.map((el) => el.id).join(' '));
+        else
+            editor.removeAttribute('aria-describedby');
+    }
+    /** Feeds `FormConnectDetail.userInvalid` (ADR-0050) — the `trackUserInvalid` tracker IS the timing source. */
+    formUserInvalid() {
+        return this.#userInvalid?.userInvalid() ?? false;
+    }
+    /**
+     * Create the editor PART + the aria message node ONCE (idempotent across reconnect — both are light-DOM
+     * children that persist through disconnect), returning the editor. The message node is NOT a public part
+     * (the descriptor lists only `editor` under `parts`) — it is `hidden`, carrying `validity().message` only
+     * under `user-invalid`.
+     */
+    #ensureParts() {
+        if (this.#editor)
+            return this.#editor;
+        const editor = document.createElement('div');
+        editor.setAttribute('data-part', 'editor');
+        editor.setAttribute('contenteditable', EDITABLE);
+        editor.setAttribute('role', 'textbox'); // the role rides the PART — the host carries NO role/aria-* attribute
+        editor.setAttribute('aria-multiline', 'true'); // the ADR-0134 inversion from ui-text-field's aria-multiline="false"
+        this.#editor = editor;
+        const message = document.createElement('div');
+        message.className = 'ui-textarea-message'; // a queryable hook, NOT a [data-part] (it is not a public part)
+        message.id = `ui-textarea-message-${++messageSeq}`;
+        message.hidden = true;
+        this.#message = message;
+        this.append(editor, message);
+        return editor;
+    }
+}
+if (!customElements.get('ui-textarea'))
+    customElements.define('ui-textarea', UITextareaElement);

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

@@ -0,0 +1,48 @@
+/* theme-provider.css — ui-theme-provider, the single-file component stylesheet (ADR-0003). The degenerate
+ * minimal case of the fleet's two-block shape (text-field.css / column.css), the SAME shape
+ * form-provider.css already establishes for a pure coordination/carrier element —
+ *
+ *   [1] TOKEN BLOCK — `:where(ui-theme-provider)` declares ONE thing: the scheme-boundary INK RE-ROOT
+ *       (ADR-0148, amending SPEC-R6's original "declares nothing"). The provider maps `scheme` to its own
+ *       `color-scheme` (LLD-C1/C2), but `color-scheme` alone does not re-resolve an INHERITED `color` —
+ *       `light-dark()` only re-resolves where a property containing it is declared, so ink computed ONCE
+ *       at an outer scheme leaks into a forced subtree as the WRONG channel values (white text on a light
+ *       surface; issue #31, first hit by the gallery as the TKT-0002 class). Re-declaring `color` here, at
+ *       the boundary, makes inherited ink re-resolve against the provider's own scheme. Zero specificity
+ *       (`:where()`) is load-bearing: any consumer declaration on any real selector outranks it (and
+ *       `color: inherit` restores the leak-through on purpose). Ink ONLY — no background, no surface: the
+ *       invariant is that every BACKGROUND reachable under a provider is itself scheme-declared (all fleet
+ *       surfaces are), so ink and ground re-resolve in step. Still no `--ui-theme-provider-*` chain — the
+ *       rule consumes the shared, universally-consumable neutral ink role directly (family-coherence
+ *       B-group's sanctioned shape); nothing to theme remains true (form-provider.css LLD-C8 precedent).
+ *   [2] STYLES BLOCK — `@scope (ui-theme-provider)` sets exactly one declaration: `display: block`. An
+ *       unstyled custom element defaults to `inline`, which would lay its slotted block-level descendants
+ *       out inline against the host — a first-paint layout defect. No further rule: no spacing, no
+ *       geometry, no surface — the coordination host paints nothing, the slotted subtree owns every box.
+ *       (Deliberately NOT the home of the ink re-root: a scoped `:scope` rule carries (0,1,0) specificity
+ *       plus scoping proximity and would silently BEAT a consumer's class-selector ink — the TKT-0001 trap.)
+ *
+ * Standalone stylesheet — linked via the component-styles barrel; NEVER injected from theme-provider.ts
+ * (behaviour-only `.ts`, no runtime style injection — plan §2). No forced-colors block: the component
+ * paints no surface of its own (SPEC-R6).
+ */
+
+/* ════════════════ [1] TOKEN BLOCK — :where(ui-theme-provider): the ink re-root, nothing else ════════════════ */
+/* Still no --ui-theme-provider-* token chain (SPEC-R6 as amended by ADR-0148): a pure coordination/carrier
+   element has no visual voice of its own. `scale`/`density` ride the ambient [scale]/[density] selectors in
+   dimensions.css, unmodified by this sheet (SPEC-R4); `theme` is wired but inert (SPEC-R5). The single
+   declaration below is the SCHEME-BOUNDARY INK RE-ROOT (banner §[1]) — inherited-ink re-resolution at the
+   provider's own color-scheme, not a painted surface. */
+:where(ui-theme-provider) {
+  color: var(--md-sys-color-neutral-on-surface);
+}
+
+/* ════════════════ [2] STYLES BLOCK — @scope (ui-theme-provider) consumes NOTHING ════════════════ */
+
+@scope (ui-theme-provider) {
+  :scope {
+    display: block; /* the host's only rule: an unstyled custom element defaults to `inline`, which would
+       lay its slotted block-level descendants out inline against it — `block` is the coordination host's
+       structural default, not a styling opinion. */
+  }
+}

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

@@ -0,0 +1,59 @@
+import { UIElement, type ReactiveProps } from '../../dom/index.js';
+declare const props: {
+    scheme: {
+        reflect: true;
+        type: import("../../index.js").PropType<"" | "light" | "dark">;
+        default: "" | "light" | "dark";
+        attribute?: string | false;
+    };
+    scale: {
+        reflect: true;
+        type: import("../../index.js").PropType<"" | "ui-sm" | "ui-md" | "ui-lg" | "content-sm" | "content-md" | "content-lg">;
+        default: "" | "ui-sm" | "ui-md" | "ui-lg" | "content-sm" | "content-md" | "content-lg";
+        attribute?: string | false;
+    };
+    density: {
+        reflect: true;
+        type: import("../../index.js").PropType<"" | "compact" | "comfortable" | "spacious">;
+        default: "" | "compact" | "comfortable" | "spacious";
+        attribute?: string | false;
+    };
+    theme: {
+        reflect: true;
+        type: import("../../index.js").PropType<string>;
+        default: string;
+        attribute?: string | false;
+    };
+};
+export interface UIThemeProviderElement extends ReactiveProps<typeof props> {
+}
+export declare class UIThemeProviderElement extends UIElement {
+    static props: {
+        scheme: {
+            reflect: true;
+            type: import("../../index.js").PropType<"" | "light" | "dark">;
+            default: "" | "light" | "dark";
+            attribute?: string | false;
+        };
+        scale: {
+            reflect: true;
+            type: import("../../index.js").PropType<"" | "ui-sm" | "ui-md" | "ui-lg" | "content-sm" | "content-md" | "content-lg">;
+            default: "" | "ui-sm" | "ui-md" | "ui-lg" | "content-sm" | "content-md" | "content-lg";
+            attribute?: string | false;
+        };
+        density: {
+            reflect: true;
+            type: import("../../index.js").PropType<"" | "compact" | "comfortable" | "spacious">;
+            default: "" | "compact" | "comfortable" | "spacious";
+            attribute?: string | false;
+        };
+        theme: {
+            reflect: true;
+            type: import("../../index.js").PropType<string>;
+            default: string;
+            attribute?: string | false;
+        };
+    };
+    protected connected(): void;
+}
+export {};

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

@@ -0,0 +1,40 @@
+// theme-provider.ts — UIThemeProviderElement, the fleet's second UIElement-based pure-coordination/carrier
+// primitive (ADR-0117; SPEC theme-provider.spec.md; LLD theme-provider.lld.md LLD-C1/C2). BEHAVIOUR +
+// self-define ONLY — geometry lives in theme-provider.css (LLD-C3), the public contract in
+// theme-provider.md (LLD-C4).
+//
+// Promotes site/lib/theme-provider.ts's CONTRACT (not its file) to a shipped `@agent-ui-kit/components`
+// control, with one deliberate behavioral fix (SPEC-R3): `scheme` unset no longer collapses to light — it
+// clears any inline override and lets `color-scheme` inherit (the page default, or an ancestor provider's,
+// if nested). `scale`/`density`/`theme` are pure attribute carriers with zero JS-side effect (SPEC-R4/R5) —
+// `dimensions.css`'s `[scale]`/`[density]` selectors and a future `[theme='<name>']` package layer read them
+// directly; this class does nothing beyond reflecting them.
+//
+// `controls → dom` is the allowed import direction (this control needs no trait).
+import { UIElement, prop } from "../../dom/index.js";
+const SCHEMES = ['', 'light', 'dark'];
+const SCALES = ['', 'ui-sm', 'ui-md', 'ui-lg', 'content-sm', 'content-md', 'content-lg']; // ADR-0032
+const DENSITIES = ['', 'compact', 'comfortable', 'spacious'];
+const props = {
+    // The ONE prop with a JS-side effect (below) — SPEC-R3.
+    scheme: { ...prop.enum(SCHEMES, ''), reflect: true },
+    // Pure carriers — reflected, zero effect; dimensions.css [scale]/[density] key off the attribute (SPEC-R4).
+    scale: { ...prop.enum(SCALES, ''), reflect: true },
+    density: { ...prop.enum(DENSITIES, ''), reflect: true },
+    // The reserved package seam (ADR-0079 cl.3 / SPEC-R5) — free string, inert until a future [theme=] layer ships.
+    theme: { ...prop.string(''), reflect: true },
+};
+export class UIThemeProviderElement extends UIElement {
+    static props = props;
+    connected() {
+        // SPEC-R3 — '' clears any inline color-scheme (never coerces to 'light'), so an unset provider imposes
+        // NO override and its subtree inherits the ambient color-scheme: the page's own, or an ANCESTOR
+        // provider's if this one nests inside another (SPEC-R3 AC4). This is the load-bearing fix over the
+        // site-local predecessor, which collapsed any non-'dark' value — including genuinely unset — to 'light'.
+        this.effect(() => {
+            this.style.colorScheme = this.scheme === '' ? '' : this.scheme;
+        });
+    }
+}
+if (!customElements.get('ui-theme-provider'))
+    customElements.define('ui-theme-provider', UIThemeProviderElement);

package/dist/controls/timeline/timeline.css

@@ -0,0 +1,33 @@
+/* timeline.css — ui-timeline, the single-file component stylesheet (ADR-0003; timeline-family.lld.md §3 ·
+ * SPEC-R6/R7/R14/R15). ui-timeline is a STRUCTURAL container (SPEC-R7: "MAY declare nothing else
+ * value-bearing — it is a structural container") — the rail RHYTHM (row-gap) and MARKER geometry are
+ * owned entirely by each authored `ui-timeline-item` child (its own `margin-block-end` + marker-system
+ * table, timeline-item.css); this host contributes ONLY the vertical flex stack + its accessible-name
+ * wiring (`label` → `internals.ariaLabel`, timeline.ts). No `[size]` CSS selector — `size` is a
+ * first-class prop for family/catalog symmetry (ADR-0122 F2) but this structural container itself has no
+ * geometry of its own to repoint (family-coherence A2b: a CSS `[size` selector is never present WITHOUT a
+ * declared attribute — the inverse holds trivially here, same shape as toast.css's "no [size] axis" note).
+ *
+ *   [1] TOKEN BLOCK — `:where(ui-timeline)` declares the one dimensional quantity this host owns: the
+ *       bare-host `min-inline-size` floor (the ui-slider whole-shape lesson — SPEC-R14 AC1).
+ *   [2] STYLES BLOCK — `@scope (ui-timeline)` lays out the authored `ui-timeline-item` children as a
+ *       vertical stack, DOM order, no auto-sort (the adia rule) — page/container-scrolled, static.
+ */
+
+/* ════════════════ [1] TOKEN BLOCK — :where(ui-timeline) declares --ui-timeline-* ════════════════ */
+
+:where(ui-timeline) {
+  --ui-timeline-min-inline-size: 12rem;
+}
+
+/* ════════════════ [2] STYLES BLOCK — @scope (ui-timeline) consumes ONLY --ui-timeline-* ════════════════ */
+
+@scope (ui-timeline) {
+  :scope {
+    display: flex;
+    flex-direction: column;
+    /* min-inline-size floor — the ui-slider whole-shape lesson: a bare/unsized host must not collapse to a
+       0-width sliver (SPEC-R14 AC1). Above the floor, width stays the layout's job. */
+    min-inline-size: var(--ui-timeline-min-inline-size);
+  }
+}

package/dist/controls/timeline/timeline.d.ts

@@ -0,0 +1,39 @@
+import { UIContainerElement, type ReactiveProps } from '../../dom/index.js';
+import '../timeline-item/timeline-item.js';
+declare const props: {
+    size: {
+        reflect: true;
+        type: import("../../index.js").PropType<"sm" | "md" | "lg">;
+        default: "sm" | "md" | "lg";
+        attribute?: string | false;
+    };
+    label: {
+        reflect: true;
+        type: import("../../index.js").PropType<string>;
+        default: string;
+        attribute?: string | false;
+    };
+};
+export interface UITimelineElement extends ReactiveProps<typeof props> {
+}
+export declare class UITimelineElement extends UIContainerElement {
+    #private;
+    static props: {
+        size: {
+            reflect: true;
+            type: import("../../index.js").PropType<"sm" | "md" | "lg">;
+            default: "sm" | "md" | "lg";
+            attribute?: string | false;
+        };
+        label: {
+            reflect: true;
+            type: import("../../index.js").PropType<string>;
+            default: string;
+            attribute?: string | false;
+        };
+    };
+    constructor();
+    protected connected(): void;
+    protected disconnected(): void;
+}
+export {};

package/dist/controls/timeline/timeline.js

@@ -0,0 +1,52 @@
+// timeline.ts — UITimelineElement, the timeline family's DURABLE host (timeline-family.lld.md §3 ·
+// SPEC-R6/R7 · ADR-0122 F1/F2/F6). BEHAVIOUR + props + the terminal-connector marking + self-define ONLY.
+// Anatomy/geometry per the LLD; styling lives in timeline.css, the public contract in timeline.md.
+//
+// Authored-children ingress, DOM order, NO auto-sort (the adia rule) — the consumer's `ui-timeline-item`
+// light-DOM children are the chronology, read back in the order authored. `internals.role = 'list'` (the
+// `ui-list` precedent — list.ts:50), never a host `role` attribute; items are `role="listitem"` (their
+// own contract). STATIC — no imperative append/update/finalize API, no MutationObserver tail-follow, no
+// live-region role: the negative control separating this from `ui-status-stream` (SPEC-R6 AC3). The ONE
+// observer this host owns re-marks the terminal item's connector suppressed (`data-last`) whenever the
+// child list changes — the `ui-toast-region` childList-observer precedent (toast-region.ts:55-57),
+// repurposed for a STRUCTURAL fact (which item is last), not liveness.
+//
+// `controls → dom + controls/timeline-item/timeline-item.ts` — the allowed import direction (cross-folder
+// sibling, the toast→button precedent direction).
+import { UIContainerElement, prop } from "../../dom/index.js";
+import "../timeline-item/timeline-item.js"; // registers the item child (the cross-folder sibling edge — the LLD's './timeline-item.ts' is a typo for this path, since timeline-item/ is a SIBLING folder per §1's layout, not nested under timeline/)
+const SIZE = ['sm', 'md', 'lg'];
+const props = {
+    size: { ...prop.enum(SIZE, 'md'), reflect: true }, // first-class geometry (F2); NO variant/data/orientation prop in v1
+    label: { ...prop.string(''), reflect: true }, // author accessible name → internals.ariaLabel (the toolbar.ts precedent)
+};
+export class UITimelineElement extends UIContainerElement {
+    static props = props; // deliberately does NOT spread surfaceProps/flexProps — a timeline owns no elevation axis
+    #observer = null;
+    constructor() {
+        super();
+        this.internals.role = 'list'; // role VALUE = the ui-list precedent (list.ts:50); constructor PLACEMENT
+        // (semantics before insertion) = the toast precedent (toast.ts:68)
+    }
+    connected() {
+        this.effect(() => {
+            this.internals.ariaLabel = this.label === '' ? null : this.label;
+        });
+        this.#markLastItem(); // seed from any children already present (declarative markup)
+        this.#observer = new MutationObserver(() => this.#markLastItem());
+        this.#observer.observe(this, { childList: true });
+    }
+    disconnected() {
+        this.#observer?.disconnect();
+        this.#observer = null;
+    }
+    /** Clear `data-last` on every authored item, then set it on the last — the CSS suppresses that item's
+     *  own terminal connector (SPEC-R6 AC2). Re-run on every childList mutation so a late-appended durable
+     *  item re-marks the terminal correctly (the toast-region observer precedent). */
+    #markLastItem() {
+        const items = this.querySelectorAll(':scope > ui-timeline-item');
+        items.forEach((item, i) => item.toggleAttribute('data-last', i === items.length - 1));
+    }
+}
+if (!customElements.get('ui-timeline'))
+    customElements.define('ui-timeline', UITimelineElement);