@agent-ui-kit/components 0.0.3

package/dist/controls/toast/toast.d.ts

@@ -0,0 +1,28 @@
+import { UIElement, type ReactiveProps } from '../../dom/index.js';
+import '../icon/icon.js';
+declare const props: {
+    urgent: import("../../index.js").PropConfig<boolean>;
+    duration: import("../../index.js").PropConfig<number | null>;
+    action: import("../../index.js").PropConfig<string>;
+};
+export interface UIToastElement extends ReactiveProps<typeof props> {
+}
+export declare class UIToastElement extends UIElement {
+    #private;
+    static props: {
+        urgent: import("../../index.js").PropConfig<boolean>;
+        duration: import("../../index.js").PropConfig<number | null>;
+        action: import("../../index.js").PropConfig<string>;
+    };
+    constructor();
+    protected connected(): void;
+    protected disconnected(): void;
+    /**
+     * Close the toast (SPEC-R14 AC1/AC2). Idempotent (a `closed` latch): clears any running timer,
+     * dispatches exactly ONE `close`, then removes the host from the DOM. Invoked by the close
+     * affordance, timer expiry, AND an actionable commit (which emits `select` first) — the ledger #11
+     * duplicate-path race is closed by the latch, not by the caller.
+     */
+    close(): void;
+}
+export {};

package/dist/controls/toast/toast.js

@@ -0,0 +1,191 @@
+// toast.ts — UIToastElement, the fleet's first transient notification surface (feed-family.lld.md
+// LLD-C7 · SPEC-R14/R15/R16/R19 · ADR-0112 cl.5). BEHAVIOUR + props + the control-built message/
+// action/close parts + self-define ONLY. Anatomy/geometry per the LLD; styling lives in toast.css,
+// the public contract in toast.md. Region ownership + the `show()` convenience live beside it in
+// toast-region.ts (the radio/radio-group same-folder precedent — ADR-0112's Decision cl.1). NOT
+// catalogued (ADR-0112 cl.6) — the app-surface consumption story is region-hosted, never direct markup
+// an agent emits.
+//
+// role=status is set in the CONSTRUCTOR (SPEC-R15 AC2), not connected() — the live-region semantics
+// must exist BEFORE the element is inserted (construction strictly precedes any append call — e.g.
+// UIToastRegionElement.show() creates the element, assigns props, sets textContent, THEN appends), so
+// content present at append announces. connected()'s `urgent` effect flips status↔alert afterwards —
+// a role CHANGE on an already-live region, a lesser concern than "was it live from the start."
+//
+// Anatomy (connected(), ONCE — an idempotent guard, the modal.ts/disclosure.ts part-persistence
+// precedent): light-DOM children present at connect (typically the message text, set by a caller
+// BEFORE append) are adopted (moved, ADR-0022) into a component-built `<span data-part="message">`;
+// late-added children are out of scope v1 (ledger #7, documented in toast.md). `action` non-empty ⇒ an
+// `<ui-button data-part="action">` is appended; a `<ui-button data-part="close">` icon-only
+// (`<ui-icon glyph="x">`, `aria-label="Dismiss"`) is ALWAYS appended. Both affordances are reachable in
+// normal tab order (ui-button's own `tabbable` trait) — no tabindex games, no autofocus (SPEC-R15
+// AC3). Native `<button>` is banned (fleet law); the `<ui-button>`/`<ui-icon>` sibling imports are the
+// sanctioned cross-control edge (the segmented-control → radio precedent).
+//
+// The timer (SPEC-R16) — remaining-time accounting, all element-local state (no separate trait; the
+// LLD keeps this element-owned, not a reusable behaviour). Armed iff `action === '' &&
+// Number.isFinite(duration) && duration > 0` — an actionable toast NEVER auto-dismisses (WCAG 2.2.1).
+// Pause predicate = hovered ∨ focusWithin, tracked via four host listeners; `focusout` treats a null
+// `relatedTarget` (window blur) as focus-left ⇒ resume (ledger #5 — a timer running in a blurred tab
+// is the platform norm; the hover flag still pauses independently). `close()` is idempotent (a
+// `closed` latch): clears the timer, dispatches exactly ONE `close`, `this.remove()` (ledger #11).
+//
+// `controls → dom + controls/button + controls/icon` — the allowed import direction (cross-control,
+// the segmented-control/radio precedent).
+import { UIElement, prop } from "../../dom/index.js";
+import { UIButtonElement } from "../button/button.js";
+import "../icon/icon.js";
+const props = {
+    urgent: prop.boolean(false), // role=alert opt-in (SPEC-R15)
+    duration: prop.number(6000), // ms; ≤0/non-finite ⇒ never auto-dismiss (SPEC-R14)
+    action: prop.string(''), // non-empty ⇒ actionable ⇒ NEVER auto-dismisses (SPEC-R16, WCAG 2.2.1)
+};
+export class UIToastElement extends UIElement {
+    static props = props;
+    // The control-built message part — created ONCE (idempotent guard in #ensureParts); persists
+    // through disconnect/reconnect (the modal.ts/disclosure.ts precedent).
+    #message = null;
+    // Timer state (SPEC-R16) — all local/imperative (never reactively read; the eligibility effect below
+    // is the ONE reactive entry point, everything else — hover/focus/expiry — mutates it directly).
+    #remaining = 0;
+    #startedAt = 0;
+    #timerId = null;
+    #hovered = false;
+    #focusWithin = false;
+    #closed = false;
+    constructor() {
+        super();
+        // SPEC-R15 AC2 — the live-region role exists BEFORE insertion (construction strictly precedes any
+        // append call), so content present at append announces. connected()'s urgent effect flips this to
+        // 'alert' when appropriate — a role CHANGE on an already-live region, not a first-insertion race.
+        this.internals.role = 'status';
+    }
+    connected() {
+        this.#ensureParts();
+        // urgent ⇒ role flips status↔alert (SPEC-R15).
+        this.effect(() => {
+            this.internals.role = this.urgent ? 'alert' : 'status';
+        });
+        // The timer (SPEC-R16) — (re)computes eligibility + remaining time on every action/duration change;
+        // an actionable toast never has a live timer. Pause/resume (hover/focus, below) are imperative,
+        // driven off the SAME #remaining/#timerId state this effect seeds.
+        this.effect(() => {
+            const eligible = this.#eligible();
+            this.#pauseTimer();
+            this.#remaining = eligible ? this.duration : 0;
+            if (eligible && !this.#paused())
+                this.#armTimer();
+        });
+        // Pause predicate = hovered ∨ focusWithin (SPEC-R16) — four host listeners.
+        this.listen(this, 'pointerenter', () => {
+            this.#hovered = true;
+            this.#pauseTimer();
+        });
+        this.listen(this, 'pointerleave', () => {
+            this.#hovered = false;
+            this.#resumeIfEligible();
+        });
+        this.listen(this, 'focusin', () => {
+            this.#focusWithin = true;
+            this.#pauseTimer();
+        });
+        this.listen(this, 'focusout', (event) => {
+            const related = event.relatedTarget;
+            if (related && this.contains(related))
+                return; // focus moved WITHIN the toast — still focusWithin
+            this.#focusWithin = false; // null relatedTarget (window blur) is treated as focus-left ⇒ resume (ledger #5)
+            this.#resumeIfEligible();
+        });
+    }
+    disconnected() {
+        this.#pauseTimer();
+    }
+    /**
+     * Close the toast (SPEC-R14 AC1/AC2). Idempotent (a `closed` latch): clears any running timer,
+     * dispatches exactly ONE `close`, then removes the host from the DOM. Invoked by the close
+     * affordance, timer expiry, AND an actionable commit (which emits `select` first) — the ledger #11
+     * duplicate-path race is closed by the latch, not by the caller.
+     */
+    close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.#pauseTimer();
+        this.emit('close');
+        this.remove();
+    }
+    /** Armable iff not actionable and `duration` is a positive finite number (SPEC-R16). */
+    #eligible() {
+        return this.action === '' && Number.isFinite(this.duration) && this.duration > 0;
+    }
+    #paused() {
+        return this.#hovered || this.#focusWithin;
+    }
+    #resumeIfEligible() {
+        if (this.#eligible() && !this.#paused())
+            this.#armTimer();
+    }
+    #armTimer() {
+        if (this.#timerId !== null || this.#remaining <= 0)
+            return;
+        this.#startedAt = performance.now();
+        this.#timerId = setTimeout(() => this.close(), this.#remaining);
+    }
+    /** clearTimeout + fold the elapsed time into `#remaining` (a no-op when no timer is running). */
+    #pauseTimer() {
+        if (this.#timerId === null)
+            return;
+        clearTimeout(this.#timerId);
+        this.#timerId = null;
+        this.#remaining -= performance.now() - this.#startedAt;
+    }
+    /**
+     * Build the light-DOM anatomy ONCE (idempotent guard; the part persists across reconnect — the
+     * modal.ts/disclosure.ts precedent). Pre-existing host children (the message, set by a caller BEFORE
+     * append — e.g. `UIToastRegionElement.show()`) are adopted (moved, ADR-0022) into the message part;
+     * children added later are out of scope v1 (ledger #7, documented in toast.md). `action` is read
+     * ONCE here — the affordance cluster is fixed at connect, matching the v1 usage pattern (`show()`
+     * assigns every prop BEFORE the element ever connects).
+     */
+    #ensureParts() {
+        if (this.#message)
+            return;
+        const message = document.createElement('span');
+        message.setAttribute('data-part', 'message');
+        while (this.firstChild)
+            message.appendChild(this.firstChild);
+        this.appendChild(message);
+        this.#message = message;
+        if (this.action !== '') {
+            const actionBtn = document.createElement('ui-button');
+            actionBtn.setAttribute('data-part', 'action');
+            actionBtn.textContent = this.action;
+            this.appendChild(actionBtn);
+            this.listen(actionBtn, 'click', () => {
+                this.emit('select');
+                this.close();
+            });
+        }
+        // Always present, icon-only — a real accessible name via aria-label (button.md's textContent
+        // source has nothing to read here), the fleet's icon-only-button idiom. `icon-only` opts into
+        // button.css's fifth (square) structure — WITHOUT this attribute the button itself would render
+        // non-square (the slotted icon + empty label reserving a dead 1fr label track); WITH it (as
+        // shipped here) the button is a genuine square, proven by button-geometry.browser.test.ts's s14
+        // suite. The card-level grid placement of this part is a SEPARATE concern — see toast.css's
+        // `[data-part='close']` grid-column pin (TKT-0014).
+        const closeBtn = document.createElement('ui-button');
+        closeBtn.setAttribute('data-part', 'close');
+        closeBtn.setAttribute('variant', 'ghost'); // a subtle dismiss — never competes with an actionable CTA
+        closeBtn.setAttribute('icon-only', '');
+        closeBtn.setAttribute('aria-label', 'Dismiss');
+        const icon = document.createElement('ui-icon');
+        icon.setAttribute('slot', 'leading');
+        icon.setAttribute('data-role', 'icon');
+        icon.setAttribute('glyph', 'x');
+        closeBtn.appendChild(icon);
+        this.appendChild(closeBtn);
+        this.listen(closeBtn, 'click', () => this.close());
+    }
+}
+if (!customElements.get('ui-toast'))
+    customElements.define('ui-toast', UIToastElement);

package/dist/controls/toolbar/toolbar.css

@@ -0,0 +1,125 @@
+/* toolbar.css — the SINGLE sheet for ui-toolbar (ADR-0121; toolbar.lld.md LLD-C5). Two sectioned blocks
+ * (ADR-0003): a :where() TOKEN block (declares the --ui-toolbar-* chain off the --md-sys-space layout ladder + the
+ * control-height register) then an @scope STYLES block (consumes ONLY --ui-toolbar-*). Host-as-flex — light-DOM
+ * children ARE the flex items (the ui-row precedent); no named slots, no [slot=…] selector anywhere in this sheet.
+ *
+ * Geometry (geometry.md "Pattern" size-class — toolbar is a NAMED example): the toolbar owns NO control-height
+ * `size` prop of its own — its ITEMS take their own control height. The toolbar's own contribution is padding +
+ * gap off the --md-sys-space layout ladder, plus a min-block-size FLOOR tied to the control-height register (the
+ * ui-md row height) so an empty or short bar still reads as a bar (SPEC-R7 AC2, the whole-shape law).
+ *
+ * Surface (ADR-0015): the floating/embedded posture is entirely the shared controls/_surface/container.css seam
+ * this element is added to (--ui-container-bg/-tint) — this sheet paints NO surface colour of its own (the
+ * ui-tabs precedent, ADR-0104). elevation=0/unset is transparent/flush (embedded); elevation ≥ 1 is a raised
+ * plane (floating), which also establishes the ADR-0052 [data-box] isolation z-scope when the consumer opts a
+ * raised toolbar into the shared container-box seam. */
+
+/* ════════════════ [1] TOKEN BLOCK — :where(ui-toolbar) declares --ui-toolbar-* ════════════════ */
+
+:where(ui-toolbar) {
+  --ui-toolbar-align: center; /* align (cross-axis) → align-items; center is the toolbar's OWN default (the bar look — differs from ui-row's start) */
+  --ui-toolbar-justify: start; /* justify (main-axis distribution) → justify-content */
+  --ui-toolbar-gap: var(--md-sys-space-sm); /* gap default 'sm' — toolbars are tight (differs from ui-row's 'none') */
+  --ui-toolbar-pad-inline: var(--md-sys-space-sm);
+  --ui-toolbar-pad-block: var(--md-sys-space-xs);
+  --ui-toolbar-min-block-size: var(--md-sys-height-md); /* the whole-shape bar floor (SPEC-R7 AC2) — the control-height register, NOT a --md-sys-space quantity */
+
+  box-sizing: border-box;
+}
+
+/* align → align-items. start/end/stretch/baseline are valid align-items keywords (the box-alignment logical
+   values, the ui-row precedent), so the mapping is 1:1 — only the non-default members need a repoint (center is
+   the default declared above). */
+:where(ui-toolbar[align='start']) {
+  --ui-toolbar-align: start;
+}
+:where(ui-toolbar[align='end']) {
+  --ui-toolbar-align: end;
+}
+:where(ui-toolbar[align='stretch']) {
+  --ui-toolbar-align: stretch;
+}
+:where(ui-toolbar[align='baseline']) {
+  --ui-toolbar-align: baseline;
+}
+
+/* justify → justify-content. start/center/end map 1:1; between/around/evenly cross to the `space-*` forms
+   (the one keyword translation in the grammar, the ui-row precedent). */
+:where(ui-toolbar[justify='center']) {
+  --ui-toolbar-justify: center;
+}
+:where(ui-toolbar[justify='end']) {
+  --ui-toolbar-justify: end;
+}
+:where(ui-toolbar[justify='between']) {
+  --ui-toolbar-justify: space-between;
+}
+:where(ui-toolbar[justify='around']) {
+  --ui-toolbar-justify: space-around;
+}
+:where(ui-toolbar[justify='evenly']) {
+  --ui-toolbar-justify: space-evenly;
+}
+
+/* gap → a step on the --md-sys-space ladder (density-responsive — rides [density], NOT [scale]; ADR-0015 cl.4).
+   'sm' is the default declared above; every OTHER step needs a repoint. */
+:where(ui-toolbar[gap='none']) {
+  --ui-toolbar-gap: var(--md-sys-space-none);
+}
+:where(ui-toolbar[gap='xs']) {
+  --ui-toolbar-gap: var(--md-sys-space-xs);
+}
+:where(ui-toolbar[gap='md']) {
+  --ui-toolbar-gap: var(--md-sys-space-md);
+}
+:where(ui-toolbar[gap='lg']) {
+  --ui-toolbar-gap: var(--md-sys-space-lg);
+}
+:where(ui-toolbar[gap='xl']) {
+  --ui-toolbar-gap: var(--md-sys-space-xl);
+}
+:where(ui-toolbar[gap='2xl']) {
+  --ui-toolbar-gap: var(--md-sys-space-2xl);
+}
+
+/* ════════════════ [2] STYLES BLOCK — @scope (ui-toolbar) consumes ONLY --ui-toolbar-* ════════════════ */
+
+@scope (ui-toolbar) {
+  :scope {
+    display: flex;
+    flex-direction: row; /* [orientation=vertical] flips to column below */
+    flex-wrap: wrap; /* overflow='wrap' is the default (F4 — never hides an action); [overflow=scroll] overrides */
+    align-items: var(--ui-toolbar-align);
+    justify-content: var(--ui-toolbar-justify);
+    gap: var(--ui-toolbar-gap);
+    min-block-size: var(--ui-toolbar-min-block-size);
+    padding: var(--ui-toolbar-pad-block) var(--ui-toolbar-pad-inline);
+    min-inline-size: 0; /* allow shrink within a flex/grid parent — a bar never forces its parent wider */
+    /* NO background/border here — the surface plane is the shared controls/_surface/container.css seam this
+       element sits on (--ui-container-bg/-tint); elevation=0/unset stays transparent (embedded), elevation ≥ 1
+       paints a raised plane (floating) — this sheet holds zero colour opinion (the ui-tabs/ADR-0104 precedent). */
+  }
+
+  /* orientation=vertical — flips the flex axis (the roving key-axis is resolved once at connect in toolbar.ts);
+     pair with overflow=scroll rather than wrap (documented as odd, not an error — LLD §6). */
+  :scope[orientation='vertical'] {
+    flex-direction: column;
+  }
+
+  /* overflow=scroll — a single line; the toolbar owns its own scroll region (F4). */
+  :scope[overflow='scroll'] {
+    flex-wrap: nowrap;
+    overflow-inline: auto;
+  }
+
+  /* forced-colors (WHCM) — belt-and-braces with the shared container.css surface block (the ui-row precedent):
+     a surfaced toolbar keeps a system colour and drops the tonal wash. The bar paints no intent surface of its
+     own in v1 (SPEC-R9 note), so there is no selected/active cue of its own to additionally protect (unlike
+     ui-tabs' indicator). */
+  @media (forced-colors: active) {
+    :scope {
+      background-color: Canvas;
+      background-image: none;
+    }
+  }
+}

package/dist/controls/toolbar/toolbar.d.ts

@@ -0,0 +1,108 @@
+import { UIContainerElement, type ReactiveProps } from '../../dom/index.js';
+declare const props: {
+    orientation: {
+        reflect: true;
+        type: import("../../index.js").PropType<"horizontal" | "vertical">;
+        default: "horizontal" | "vertical";
+        attribute?: string | false;
+    };
+    align: {
+        reflect: true;
+        type: import("../../index.js").PropType<"end" | "start" | "center" | "stretch" | "baseline">;
+        default: "end" | "start" | "center" | "stretch" | "baseline";
+        attribute?: string | false;
+    };
+    justify: {
+        reflect: true;
+        type: import("../../index.js").PropType<"end" | "start" | "center" | "between" | "around" | "evenly">;
+        default: "end" | "start" | "center" | "between" | "around" | "evenly";
+        attribute?: string | false;
+    };
+    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;
+    };
+    overflow: {
+        reflect: true;
+        type: import("../../index.js").PropType<"wrap" | "scroll">;
+        default: "wrap" | "scroll";
+        attribute?: string | false;
+    };
+    label: {
+        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 UIToolbarElement extends ReactiveProps<typeof props> {
+}
+export declare class UIToolbarElement extends UIContainerElement {
+    #private;
+    static props: {
+        orientation: {
+            reflect: true;
+            type: import("../../index.js").PropType<"horizontal" | "vertical">;
+            default: "horizontal" | "vertical";
+            attribute?: string | false;
+        };
+        align: {
+            reflect: true;
+            type: import("../../index.js").PropType<"end" | "start" | "center" | "stretch" | "baseline">;
+            default: "end" | "start" | "center" | "stretch" | "baseline";
+            attribute?: string | false;
+        };
+        justify: {
+            reflect: true;
+            type: import("../../index.js").PropType<"end" | "start" | "center" | "between" | "around" | "evenly">;
+            default: "end" | "start" | "center" | "between" | "around" | "evenly";
+            attribute?: string | false;
+        };
+        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;
+        };
+        overflow: {
+            reflect: true;
+            type: import("../../index.js").PropType<"wrap" | "scroll">;
+            default: "wrap" | "scroll";
+            attribute?: string | false;
+        };
+        label: {
+            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/toolbar/toolbar.js

@@ -0,0 +1,68 @@
+// toolbar.ts — UIToolbarElement, the Pattern-class action-bar control (ADR-0121; toolbar.lld.md LLD-C1..C4).
+//
+// A light-DOM host-as-flex container (the ui-row precedent — no named slots, the consumer's own interactive
+// children ARE the flex items) that gives them `role="toolbar"` + arrow-key roving focus via the shared
+// `roving-focus` trait, DECOUPLED from selection (focus-only — no `select` event, no selected state; the
+// load-bearing difference from the ui-tabs reuse, ADR-0121 F3). The floating/embedded posture is expressed
+// purely through the inherited `elevation`/`brightness` surface axis (ADR-0015) — no posture prop, no overlay
+// machinery, no positioning of its own (ADR-0121 F1). The toolbar emits no events and owns no value — it is
+// arrangement + focus semantics, not a command bus (ADR-0121 F6).
+//
+// Layer: controls/ — imports reactive + dom + traits (inward-only ✓).
+import { UIContainerElement, prop } from "../../dom/index.js";
+import { rovingFocus } from "../../traits/roving-focus.js";
+const ORIENTATIONS = ['horizontal', 'vertical'];
+const ALIGNS = ['start', 'center', 'end', 'stretch', 'baseline']; // ADR-0039 box-alignment dialect
+const JUSTIFIES = ['start', 'center', 'end', 'between', 'around', 'evenly'];
+const GAPS = ['none', 'xs', 'sm', 'md', 'lg', 'xl', '2xl'];
+const OVERFLOWS = ['wrap', 'scroll']; // F4 — the `menu` member is a fenced, additive v2
+// Item discovery (LLD-C4): the toolbar's focusable interactive descendants, in DOM order, excluding disabled.
+// Descendant query (not direct-child) so ui-row grouping still roves (SPEC-R4 AC3). `data-toolbar-item` is the
+// explicit escape hatch for a control the button-like set misses.
+const ITEM_SELECTOR = 'ui-button, button, a[href], [role="button"], [data-toolbar-item]';
+const props = {
+    // Surface axis (ADR-0015) — the F1 posture lever. Spread from the container base's surfaceProps so the
+    // enum/default/reflect match the fleet seam ui-row/ui-card/ui-tabs share (do NOT redefine the values).
+    ...UIContainerElement.surfaceProps, // elevation, brightness — enum [0,1,2,3,-1,-2,-3], default 0, reflect
+    orientation: { ...prop.enum(ORIENTATIONS, 'horizontal'), reflect: true },
+    align: { ...prop.enum(ALIGNS, 'center'), reflect: true }, // NOTE default 'center' (bar look), not row's 'start'
+    justify: { ...prop.enum(JUSTIFIES, 'start'), reflect: true },
+    gap: { ...prop.enum(GAPS, 'sm'), reflect: true }, // NOTE default 'sm' (toolbars are tight)
+    overflow: { ...prop.enum(OVERFLOWS, 'wrap'), reflect: true },
+    label: { ...prop.string(''), reflect: true }, // author accessible name → internals.ariaLabel
+};
+export class UIToolbarElement extends UIContainerElement {
+    static props = props;
+    connected() {
+        // LLD-C2 — role + ARIA via internals ONLY (never a host attribute). role is static; aria reflects live.
+        this.internals.role = 'toolbar';
+        this.effect(() => {
+            this.internals.ariaOrientation = this.orientation === 'vertical' ? 'vertical' : null;
+        });
+        this.effect(() => {
+            this.internals.ariaLabel = this.label === '' ? null : this.label;
+        });
+        // LLD-C3 — roving focus, decoupled from selection: focus-only, no wrap, no type-ahead, no commit.
+        // Called DIRECTLY — traits are bare calls in this fleet; there is NO host.use() (popover.ts:5 says so
+        // explicitly; tabs.ts / radio-group.ts / menu.ts / select.ts / listbox-element.ts all call
+        // rovingFocus(this, {…}) directly). It rides connected()'s connection AbortSignal, so it auto-releases
+        // on disconnect and re-arms on reconnect. orientation is RESOLVED ONCE here as a VALUE (the trait's
+        // `orientation` is a RovingOrientation read once at invoke — roving-focus.ts:100 — NOT an accessor;
+        // passing a function is a type error and leaves the comparison permanently false); the radio-group.ts:
+        // 120-144 precedent — connect-resolve the axis, pass the value (see §3 note + §8).
+        const rovingOrientation = this.orientation === 'vertical' ? 'vertical' : 'horizontal';
+        rovingFocus(this, {
+            items: () => this.#items(),
+            orientation: rovingOrientation,
+            loop: false,
+            typeAhead: false,
+            // no onMove selection coupling, no syncIndex — the trait moves focus, the toolbar tracks nothing.
+        });
+    }
+    // LLD-C4 — live descendant query, DOM order, disabled excluded (the trait re-reads this on every key event).
+    #items() {
+        return Array.from(this.querySelectorAll(ITEM_SELECTOR)).filter((el) => !el.hasAttribute('disabled') && el.getAttribute('aria-disabled') !== 'true');
+    }
+}
+if (!customElements.get('ui-toolbar'))
+    customElements.define('ui-toolbar', UIToolbarElement);

package/dist/controls/tooltip/tooltip.css

@@ -0,0 +1,80 @@
+/* tooltip.css — ui-tooltip, the single-file component stylesheet (ADR-0003 · overlay-controller.lld.md).
+ * Two clearly-SECTIONED blocks, mirroring popover.css:
+ *
+ *   [1] TOKEN BLOCK  — `:where(ui-tooltip)` (specificity 0,0,0) sets the tooltip's OWN default
+ *       surface tokens and DECLARES the `--ui-tooltip-*` chain from the colour roles
+ *       (`--md-sys-color-{family}-{role}`, family = neutral) and the dimensions (`--md-sys-space-*` /
+ *       `--md-sys-shape-corner-base`). Raw `--md-sys-color-*` roles enter ONLY here; `@scope` never reads them.
+ *   [2] STYLES BLOCK — `@scope (ui-tooltip)` CONSUMES only the `--ui-tooltip-*` chain. The host
+ *       is `display: contents` — a logical wrapper that generates no box. The panel part
+ *       (`[data-part="panel"]`) is the Container/surface: `--ui-tooltip-bg`, `--md-sys-shape-corner-base`,
+ *       `--md-sys-space-sm` padding — NOT a control height (`--md-sys-height-*` is never read).
+ *       A `min-inline-size` floor prevents collapse (the ADR-0021 lesson: the overlay JS
+ *       positions against measured bounds, so a zero-width panel places at wrong coords).
+ *       A `forced-color-adjust` block keeps the surface visible in system colours.
+ *
+ * The panel's `popover="manual"` attribute (set by the overlay controller) gives it
+ * `display: none` in the UA stylesheet until `showPopover()` places it in the top layer —
+ * our CSS only applies to the visible (open) panel, which is correct.
+ */
+
+/* ════════════════ [1] TOKEN BLOCK — :where(ui-tooltip) declares --ui-tooltip-* ════════════════ */
+
+:where(ui-tooltip) {
+  /* Surface plane — the neutral floating-overlay surface (same opaque role popover uses; the
+     earlier `--md-sys-color-neutral-surface-variant` was a non-existent role → transparent panel, caught by
+     the cross-engine smoke). @scope consumes --ui-tooltip-bg / --ui-tooltip-ink, never the raw --md-sys-color-* roles. */
+  --ui-tooltip-bg: var(--md-sys-color-neutral-surface);
+  --ui-tooltip-ink: var(--md-sys-color-neutral-on-surface-variant);
+
+  /* Frame */
+  --ui-tooltip-outline: var(--md-sys-color-neutral-outline-variant);
+  --ui-tooltip-radius: var(--md-sys-shape-corner-base); /* the shared fleet radius (ADR-0015 cl.5) */
+
+  /* Shell spacing — panel-class geometry (Container/surface, NOT a control height) */
+  --ui-tooltip-padding: var(--md-sys-space-sm); /* tooltips are compact — sm, not md */
+
+  /* Size floor — prevents collapse when tooltip content is absent or narrow.
+     The overlay JS positions against the measured bounding box, so a zero-width
+     panel would be placed at incorrect coordinates (the ADR-0021 lesson). A shorter
+     floor than popover: tooltips are compact inline labels, not panel surfaces. */
+  --ui-tooltip-min-inline-size: 4rem;
+}
+
+/* ════════════════ [2] STYLES BLOCK — @scope (ui-tooltip) consumes ONLY --ui-tooltip-* ════════════════ */
+
+@scope (ui-tooltip) {
+  /* The host is a logical tooltip wrapper — it generates no box; only the anchor (in the
+     document flow) and the panel (in the top layer when open) render as visible surfaces. */
+  :scope {
+    display: contents;
+  }
+
+  /* The tooltip panel — a Container/surface in the top layer (the Popover API places it).
+     `position: fixed` and the inset are set by the JS positioning controller (overlay.ts)
+     on open — we do NOT fix a position here; the controller owns placement completely.
+     `margin: 0` prevents UA-default centering from conflicting with the controller's inset.
+     The UA `[popover]` rule hides this with display:none until `showPopover()` is called;
+     our styles paint only when the panel is in the top layer (already visible). */
+  :scope > [data-part='panel'] {
+    box-sizing: border-box;
+    margin: 0; /* the controller sets position:fixed + top/left — UA margin must not override */
+    min-inline-size: var(--ui-tooltip-min-inline-size);
+
+    background-color: var(--ui-tooltip-bg);
+    color: var(--ui-tooltip-ink);
+    border: 1px solid var(--ui-tooltip-outline);
+    border-radius: var(--ui-tooltip-radius);
+    padding: var(--ui-tooltip-padding);
+  }
+
+  /* forced-colors (WHCM) — the surface, frame, and ink stay visible as system colours.
+     Tooltip surfaces are opaque (not washed overlays), so Canvas/CanvasText applies cleanly. */
+  @media (forced-colors: active) {
+    :scope > [data-part='panel'] {
+      background-color: Canvas;
+      color: CanvasText;
+      border-color: CanvasText;
+    }
+  }
+}

package/dist/controls/tooltip/tooltip.d.ts

@@ -0,0 +1,57 @@
+import { type ReactiveProps } from '../../dom/index.js';
+import { UIElement } from '../../dom/index.js';
+import { type OverlayHandle } from '../../traits/overlay.js';
+declare const props: {
+    open: {
+        reflect: true;
+        type: import("../../index.js").PropType<boolean>;
+        default: boolean;
+        attribute?: string | false;
+    };
+    placement: {
+        reflect: true;
+        type: import("../../index.js").PropType<"bottom-start" | "bottom-end" | "top-start" | "top-end" | "left-start" | "left-end" | "right-start" | "right-end">;
+        default: "bottom-start" | "bottom-end" | "top-start" | "top-end" | "left-start" | "left-end" | "right-start" | "right-end";
+        attribute?: string | false;
+    };
+    delay: {
+        type: import("../../index.js").PropType<number | null>;
+        default: number | null;
+        attribute?: string | false;
+        reflect?: boolean;
+    };
+};
+export interface UITooltipElement extends ReactiveProps<typeof props> {
+}
+export declare class UITooltipElement extends UIElement {
+    #private;
+    static props: {
+        open: {
+            reflect: true;
+            type: import("../../index.js").PropType<boolean>;
+            default: boolean;
+            attribute?: string | false;
+        };
+        placement: {
+            reflect: true;
+            type: import("../../index.js").PropType<"bottom-start" | "bottom-end" | "top-start" | "top-end" | "left-start" | "left-end" | "right-start" | "right-end">;
+            default: "bottom-start" | "bottom-end" | "top-start" | "top-end" | "left-start" | "left-end" | "right-start" | "right-end";
+            attribute?: string | false;
+        };
+        delay: {
+            type: import("../../index.js").PropType<number | null>;
+            default: number | null;
+            attribute?: string | false;
+            reflect?: boolean;
+        };
+    };
+    /**
+     * Protected overlay handle — accessible to test probes (C10 idempotent-cleanup DoD).
+     * Replaced on each reconnect; the old handle's cleanup fires via the scope effect disposer
+     * at disconnect before this is re-assigned.
+     */
+    protected _overlayHandle: OverlayHandle | null;
+    protected connected(): void;
+    protected disconnected(): void;
+}
+export {};