@agent-ui-kit/components 0.0.3

package/dist/controls/table/table.js

@@ -0,0 +1,178 @@
+// table.ts — UITableElement, the Display-class static data table (LLD-C2, report-family.lld.md §2;
+// report-family.spec.md SPEC-R1…R6; ADR-0111 cl.1/3). BEHAVIOUR + props + the stable-skeleton mechanism +
+// the three-effect split + self-define ONLY; the pure cell-resolution/hardening math lives in
+// table-model.ts (DOM-free, unit-testable) and the CSS/token geometry lives in table.css.
+//
+// The mechanism is a REAL native `<table>` stamped in light DOM (the ui-text `as`-stamp doctrine scaled up
+// — ADR-0078 cl.4; ADR-0111 cl.3): header association, `th scope`, and SR table navigation come free from
+// the platform. The host mints NO ARIA via internals (SPEC-R6) — the stamped `<table>` IS the table.
+//
+// SPEC-R4's re-render contract — THE load-bearing mechanism (report-family.lld.md §2, LLD-C2's own framing)
+// — is a STABLE SKELETON built ONCE in `connected()`, held in private fields, never replaced by any later
+// data update: `#scroll` (the component's own overflow container — SPEC-R5) › `#table` › `#thead` + `#tbody`.
+// No code path anywhere in this file ever writes `#scroll.scrollLeft`/`.scrollTop` — the scroll offset a
+// user leaves behind survives a `rows` update by simple absence of any write, not by special-casing it.
+// Three INDEPENDENT effects, split by which signal(s) each reads (the fine-grained-waking discipline):
+//   • the COLUMNS effect (reads `columns` only) rebuilds `#thead`'s one header row; a `rows`-only update
+//     never re-runs it (SPEC-R4.3's identity clause) — `#table`/`#thead` node identity is untouched.
+//   • the BODY effect (reads `columns` AND `rows`) rebuilds ONLY `#tbody`'s content via `replaceChildren` —
+//     whole-array swap semantics (A2UI `updateDataModel`), deliberately NOT the ADR-0024 positional
+//     reconcile (inert text rows hold no per-node state worth reconciling, the bar-chart LLD §7 row 7
+//     precedent). `#scroll`'s node identity and scroll offsets are UNTOUCHED by construction.
+//   • the LABEL effect (reads `label` only) mints/removes exactly one `<caption>` and (un)sets the scroll
+//     region's `aria-labelledby` — touches nothing else (SPEC-R2 AC3).
+// `render()` stays the inherited no-op (host-as-grid is not this anatomy's shape; every node here is
+// component-built, imperatively, the sparkline/bar-chart precedent for a data-driven Display leaf).
+//
+// The interior scroll region (SPEC-R5 AC2) — `role="region" tabindex="0"` on `#scroll` — is the WAI-ARIA
+// APG accessible-overflow pattern on an INTERIOR node (the Option/MenuItem interior-attribute sanction; only
+// HOST aria rides internals). This is platform scroll AFFORDANCE, not a component keyboard contract: zero
+// component-defined key bindings are added (no roving tabindex, no arrow-key navigation) — `keyboard: []`
+// stands in table.md.
+//
+// Imports inward only (controls → dom): UIElement + prop + the typed-schema helpers from the dom barrel;
+// the pure math + safe codecs from the co-located table-model.ts (the ADR-0065 pure-core split, ADR-0111 cl.8).
+import { UIElement, prop } from "../../dom/index.js";
+import { cleanColumns, cleanRows, resolveCell, tableColumnsProp, tableRowsProp } from "./table-model.js";
+const props = {
+    columns: tableColumnsProp, // TableColumn[] · safe JSON codec (table-model.ts) · default []
+    rows: tableRowsProp, // TableRow[] · safe JSON codec (table-model.ts) · default []
+    label: { ...prop.string(''), reflect: true }, // the rendered <caption> text — the table's accessible name (SPEC-R2/R6)
+};
+export class UITableElement extends UIElement {
+    static props = props;
+    // The stable skeleton (SPEC-R4.1) — built ONCE EVER behind the `#built` guard (TKT-0067), held
+    // privately, NEVER replaced by any data-update effect below. `#`-private: nothing outside the host can
+    // reach in and mutate scroll state.
+    #built = false;
+    #scroll;
+    #table;
+    #thead;
+    #tbody;
+    // The mounted `<caption>` — null while `label` is empty (LLD-C2 step 4). Held so the label effect can
+    // find/remove/reuse the SAME element across reruns instead of re-minting one on every `label` change.
+    #caption = null;
+    // Live scroll-offset shadow (TKT-0067, MEASURED): node identity alone does NOT preserve scroll across
+    // a disconnect/reconnect — every engine resets a scroll container's offsets when it leaves the
+    // document (scroll state lives in the LAYOUT tree, not the DOM node; the probe measured 40 → 0 in
+    // Chromium AND WebKit even with the identical node reattached). Tracked by the scroll listener in
+    // connected() and restored on reconnect. Reading scrollLeft in disconnected() is too late — the
+    // element is already out of the document and reads 0 there.
+    #lastScrollLeft = 0;
+    #lastScrollTop = 0;
+    connected() {
+        // The skeleton — built ONCE EVER behind an idempotent guard (TKT-0067: previously rebuilt on every
+        // connect, which discarded the prior skeleton — and with it the scroll offset SPEC-R4.1 says
+        // "survives by omission" — on an ordinary disconnect/reconnect; the progress.ts field-guard shape,
+        // the fleet parts-once canon). NOT inside an effect (SPEC-R4.1's identity clause). `#table` starts
+        // with its `#thead`/`#tbody` already attached; `#scroll` starts EMPTY (the columns effect below
+        // attaches `#table` only once real columns exist — SPEC-R3 row 1's "no table is stamped" empty
+        // state). Light-DOM children persist across a disconnect, so a reconnect finds the prior skeleton —
+        // including its live `scrollLeft`/`scrollTop` and any mounted `#caption` — intact.
+        if (!this.#built) {
+            this.#built = true;
+            this.#scroll = document.createElement('div');
+            this.#scroll.setAttribute('data-part', 'scroll');
+            this.#scroll.setAttribute('role', 'region'); // SPEC-R5 AC2 — the accessible-overflow pattern
+            this.#scroll.setAttribute('tabindex', '0'); // platform scroll affordance, NOT a keyboard contract
+            this.#table = document.createElement('table');
+            this.#thead = document.createElement('thead');
+            this.#tbody = document.createElement('tbody');
+            this.#table.append(this.#thead, this.#tbody);
+            this.#caption = null;
+            this.replaceChildren(this.#scroll);
+        }
+        // Restore the pre-disconnect scroll offsets (TKT-0067) — a no-op on first connect (0/0). The
+        // synchronous write forces layout on the just-reinserted, already-populated skeleton so the value
+        // clamps against real content. Rides the connection: the listener below re-arms every connect.
+        if (this.#lastScrollLeft !== 0 || this.#lastScrollTop !== 0) {
+            this.#scroll.scrollLeft = this.#lastScrollLeft;
+            this.#scroll.scrollTop = this.#lastScrollTop;
+        }
+        this.listen(this.#scroll, 'scroll', () => {
+            this.#lastScrollLeft = this.#scroll.scrollLeft;
+            this.#lastScrollTop = this.#scroll.scrollTop;
+        });
+        // The COLUMNS effect (SPEC-R4.3) — reads ONLY `columns`. A `rows`-only update never re-runs this, so
+        // `#table`/`#thead` node identity holds across it (the identity clause proper).
+        this.effect(() => {
+            const cols = cleanColumns(this.columns);
+            if (cols.length === 0) {
+                // SPEC-R3 row 1: no valid columns ⇒ no table is stamped (the empty scroll container; the host box
+                // still paints via the CSS floor). `#table` itself is untouched — only detached, never destroyed —
+                // so a later columns write reattaches the SAME node (never a fresh one).
+                this.#scroll.replaceChildren();
+                return;
+            }
+            // Attach `#table` only on the detached→attached transition (attach churn only at that edge, never on
+            // every columns change) — `#scroll.replaceChildren(#table)` when it is not already `#scroll`'s child.
+            if (this.#table.parentNode !== this.#scroll)
+                this.#scroll.replaceChildren(this.#table);
+            const headerRow = document.createElement('tr');
+            for (const col of cols)
+                headerRow.append(this.#headerCell(col));
+            this.#thead.replaceChildren(headerRow);
+        });
+        // The BODY effect (SPEC-R4.3) — reads `columns` AND `rows`; rebuilds ONLY `#tbody`'s content
+        // (`replaceChildren`, whole-array swap). `#scroll`/`#table`/`#thead` are never touched here, and no
+        // DATA-update path writes `#scroll.scrollLeft`/`.scrollTop` — across data updates the scroll offset
+        // survives by omission. (Across a RECONNECT it cannot — the platform resets a removed container's
+        // offsets — so connected() restores from the tracked shadow; TKT-0067.)
+        this.effect(() => {
+            const cols = cleanColumns(this.columns);
+            const rows = cleanRows(this.rows);
+            this.#tbody.replaceChildren(...rows.map((row) => this.#rowNode(cols, row)));
+        });
+        // The LABEL effect (SPEC-R2 AC3) — reads ONLY `label`; mints/removes exactly one `<caption>` as
+        // `#table`'s first child and (un)sets `#scroll`'s `aria-labelledby` (the region is named by the SAME
+        // text the caption gives the table — one text, two consumers). Touches nothing else.
+        this.effect(() => {
+            const label = this.label;
+            if (label === '') {
+                this.#caption?.remove();
+                this.#caption = null;
+                this.#scroll.removeAttribute('aria-labelledby');
+                return;
+            }
+            if (!this.#caption) {
+                this.#caption = document.createElement('caption');
+                this.#caption.id = nextCaptionId();
+                this.#table.insertBefore(this.#caption, this.#table.firstChild);
+            }
+            this.#caption.textContent = label;
+            this.#scroll.setAttribute('aria-labelledby', this.#caption.id);
+        });
+    }
+    /** One `<th scope="col">` — `data-type='number'` set from the COLUMN's type (alignment is column-driven,
+     *  table.css's `[data-type='number']` rule; SPEC-R2/R3 row 9). */
+    #headerCell(col) {
+        const th = document.createElement('th');
+        th.setAttribute('scope', 'col');
+        if (col.type === 'number')
+            th.setAttribute('data-type', 'number');
+        th.textContent = col.label;
+        return th;
+    }
+    /** One `<tr>` of `<td>`s for `row` — cell text via the pure `resolveCell` (table-model.ts); alignment
+     *  rides the SAME column-driven `data-type` attribute as the header cell, regardless of the cell's own
+     *  resolved value (SPEC-R3 row 9 — a mismatched string in a number column keeps the column's alignment). */
+    #rowNode(cols, row) {
+        const tr = document.createElement('tr');
+        for (const col of cols) {
+            const td = document.createElement('td');
+            if (col.type === 'number')
+                td.setAttribute('data-type', 'number');
+            td.textContent = resolveCell(col, row);
+            tr.append(td);
+        }
+        return tr;
+    }
+}
+// The caption `id` mint — a module-scoped counter suffix, collision-free in light DOM (no crypto/uuid dep).
+let captionCounter = 0;
+function nextCaptionId() {
+    captionCounter += 1;
+    return `ui-table-caption-${captionCounter}`;
+}
+if (!customElements.get('ui-table'))
+    customElements.define('ui-table', UITableElement); // idempotent self-define

package/dist/controls/tabs/tab-panel.d.ts

@@ -0,0 +1,10 @@
+import { UIElement } from '../../dom/index.js';
+export declare class UITabPanelElement extends UIElement {
+    protected connected(): void;
+    /**
+     * Label this panel by the tab that controls it (called ONCE by the owning ui-tabs). Seeds a stable `id` when
+     * the author gave none (so `aria-controls` on the tab can resolve back), and points `aria-labelledby` at the
+     * tab via the internals element-reflection (no host attribute). Idempotent across reconnect.
+     */
+    link(tab: Element, ownId: string): void;
+}

package/dist/controls/tabs/tab-panel.js

@@ -0,0 +1,89 @@
+// tab-panel.ts — UITabPanelElement, the content region of the `ui-tabs` compound (goals.md §G9 / decomp
+// g9-containers s8). BEHAVIOUR + the `role=tabpanel` ARIA + the parent-driven labelling + self-define ONLY;
+// layout/colour live in tabs.css, the public contract in tabs.md.
+//
+// A `ui-tab-panel` is a component-native ChildList child the owning `ui-tabs` shows/hides by selection (only the
+// selected panel is visible — the rest carry the `hidden` attribute, staying in the DOM). It extends the plain
+// `UIElement` for the protected `internals` (`role=tabpanel` + the `aria-labelledby` element-reflection); it is
+// not a `UIContainerElement` (no surface axes — the container.css seam lists only `ui-tabs`). The host carries NO
+// `role`/`aria-*` attribute. `render()` stays the inherited void — the panel's body is its light-DOM children.
+//
+// Visibility rides the standard `hidden` attribute (a global attribute, NOT ARIA — set directly by ui-tabs), so
+// the family "no host aria-* attribute" rule is untouched. `controls → dom` is the allowed import direction.
+//
+// ADR-0144 Q1 cl.4 — keyboard-scroll disposition for a `fill`-mode panel, MEASURED at build (not assumed): a
+// focused, tabindex=0, `overflow-y:auto` region's platform default action for Arrow/Page/Home/End is NOT
+// reliably keyboard-scrollable across engines — the identical shape already measured for `ui-card-content`
+// (card-content.ts, ADR-0046 Amendment 6): Chromium moves it once trusted-focused, WebKit does not move it at
+// all. tabs.browser.test.ts re-measures the SAME gap for a filled tab panel and confirms it; this panel
+// therefore wires the SAME explicit keydown handler as `card-content.ts` rather than gamble on the default
+// action, deterministic on every shipped engine. The handler only acts when `event.target === this` (never
+// hijacks a focused DESCENDANT's own keys) and only when an ANCESTOR `ui-tabs` is in `fill` mode AND this
+// panel is the visible one (`fill`-less tabs stay ordinary document flow with no added listener effect).
+import { UIElement } from "../../dom/index.js";
+// Set an ARIA element-reflection relationship through internals (the only host-attribute-free path for an
+// IDREF-style relation); feature-detected — present in modern Chromium/WebKit, absent in jsdom (a no-op there,
+// proven live in tabs.browser.test.ts). Peer copy of tab.ts's helper (the folder ships no shared module).
+function reflectAriaElements(internals, name, elements) {
+    if (name in internals)
+        internals[name] = elements;
+}
+export class UITabPanelElement extends UIElement {
+    connected() {
+        this.internals.role = 'tabpanel'; // ARIA via internals — never a host role/aria-* attribute
+        // A tabpanel is focusable (APG: the panel takes tabindex=0 so a keyboard user can reach its content/scroll
+        // it). Self-set; the hidden panels are not reachable regardless (a `hidden` element is not focusable).
+        if (!this.hasAttribute('tabindex'))
+            this.tabIndex = 0;
+        // The EXPLICIT scroll (ADR-0144 Q1 cl.4, the card-content.ts precedent — see the file banner): the
+        // platform's own default action for arrow/Page/Home/End on a focused, tabindex=0, overflow-y:auto region is
+        // not reliable across engines, so a `fill`-mode panel scrolls itself deterministically instead of gambling
+        // on that default. Guarded to a no-op outside fill mode / on a hidden panel / when a focused DESCENDANT
+        // (not this panel itself) owns the key.
+        this.listen(this, 'keydown', (event) => {
+            if (event.target !== this || this.hidden)
+                return;
+            const tabs = this.closest('ui-tabs');
+            if (!tabs || !tabs.hasAttribute('fill'))
+                return;
+            const key = event.key;
+            const line = 40; // px per arrow press — an ordinary reading-line increment, density-invariant on purpose
+            const page = this.clientHeight * 0.9; // near-full-page, a small overlap (the standard page-scroll convention)
+            switch (key) {
+                case 'ArrowDown':
+                    this.scrollTop += line;
+                    break;
+                case 'ArrowUp':
+                    this.scrollTop -= line;
+                    break;
+                case 'PageDown':
+                    this.scrollTop += page;
+                    break;
+                case 'PageUp':
+                    this.scrollTop -= page;
+                    break;
+                case 'Home':
+                    this.scrollTop = 0;
+                    break;
+                case 'End':
+                    this.scrollTop = this.scrollHeight;
+                    break;
+                default:
+                    return;
+            }
+            event.preventDefault();
+        });
+    }
+    /**
+     * Label this panel by the tab that controls it (called ONCE by the owning ui-tabs). Seeds a stable `id` when
+     * the author gave none (so `aria-controls` on the tab can resolve back), and points `aria-labelledby` at the
+     * tab via the internals element-reflection (no host attribute). Idempotent across reconnect.
+     */
+    link(tab, ownId) {
+        if (!this.id)
+            this.id = ownId;
+        reflectAriaElements(this.internals, 'ariaLabelledByElements', [tab]);
+    }
+}
+if (!customElements.get('ui-tab-panel'))
+    customElements.define('ui-tab-panel', UITabPanelElement);

package/dist/controls/tabs/tab.d.ts

@@ -0,0 +1,26 @@
+import { UIElement, type ReactiveProps } from '../../dom/index.js';
+declare const props: {
+    key: import("../../index.js").PropConfig<string>;
+};
+export interface UITabElement extends ReactiveProps<typeof props> {
+}
+export declare class UITabElement extends UIElement {
+    static props: {
+        key: import("../../index.js").PropConfig<string>;
+    };
+    protected connected(): void;
+    /**
+     * Wire this tab to the panel it controls (called ONCE by the owning ui-tabs). Seeds a stable `id` (for the
+     * reverse `aria-labelledby` on the panel) when the author gave none, and points `aria-controls` at the panel
+     * via the internals element-reflection (no host attribute). Idempotent across reconnect.
+     */
+    link(panel: Element, ownId: string): void;
+    /**
+     * Reflect this tab's selection (called by the owning ui-tabs on every `selected` change). Drives THREE facts:
+     * `aria-selected` (via internals), the roving tabindex (0 when selected, −1 otherwise — exactly one tab is in
+     * the tab order), and the `:state(selected)` CSS hook the indicator/ink key off. `states` is optional-chained
+     * — jsdom has no CustomStateSet (the real selected-indicator paint is tabs.browser.test.ts).
+     */
+    setSelected(selected: boolean): void;
+}
+export {};

package/dist/controls/tabs/tab.js

@@ -0,0 +1,67 @@
+// tab.ts — UITabElement, the interactive tab row of the `ui-tabs` compound (goals.md §G9 / decomp
+// g9-containers s8). BEHAVIOUR + the `role=tab` ARIA + the parent-driven coordination API + self-define ONLY;
+// geometry/colour live in tabs.css (the family's single sheet), the public contract in tabs.md.
+//
+// A `ui-tab` is NOT a standalone control — it is a component-native ChildList child the owning `ui-tabs`
+// coordinates (the ratified "regions = sub-elements" model). It extends the plain `UIElement` (it needs the
+// protected `internals` for `role=tab` + `aria-selected` + the `:state(selected)` hook + the `aria-controls`
+// element-reflection — none of which a sibling can reach), but it owns no surface axes (it is not a
+// `UIContainerElement`; the container.css surface seam lists only `ui-tabs`). The host carries NO `role`/`aria-*`
+// attribute — every ARIA fact rides `this.internals` (the family discipline, CLAUDE.md). `render()` stays the
+// inherited void: the tab's label is its light-DOM children, placed by tabs.css (host-as-content), never clobbered.
+//
+// The coordination API (`link`/`setSelected`) is PUBLIC but ui-tabs-driven: the parent owns selection + the
+// roving tabindex, so it pushes each tab's selected state in (a sibling cannot set another element's protected
+// internals). `controls → dom` is the allowed import direction.
+import { UIElement, prop } from "../../dom/index.js";
+// Set an ARIA element-reflection relationship (`aria-controls`/`aria-labelledby` as ELEMENT refs, not IDREF
+// strings) THROUGH internals — the only way to express an IDREF-style ARIA relation without a host attribute
+// (the family bars host `aria-*`). Feature-detected: the reflection accessors landed in modern Chromium/WebKit
+// but NOT jsdom, so this is a no-op under the jsdom inner loop (the relation is proven in tabs.browser.test.ts)
+// and live in the real engines. Reused by tab-panel.ts (a 3-line peer copy — the folder ships no shared module).
+function reflectAriaElements(internals, name, elements) {
+    if (name in internals)
+        internals[name] = elements;
+}
+const props = {
+    // `key` — the tab's optional STABLE identity (the agent's tab id), OBSERVED (its initial attribute seeds the
+    // prop) but not reflected. ui-tabs resolves `selected` against `key` first, then falls back to the DOM index,
+    // so a `key`-less tab is addressed positionally. Mirrors the text-field `value` reflect:false precedent.
+    key: prop.string(), // renamed from `value` (TKT-0069 item 1 ruling: `value` = the FACE form value, reserved)
+};
+export class UITabElement extends UIElement {
+    static props = props;
+    connected() {
+        this.internals.role = 'tab'; // ARIA via internals — never a host role/aria-* attribute
+        // Roving-tabindex default: a tab starts OUT of the tab order; the owning ui-tabs promotes exactly the
+        // selected one to tabindex=0 (setSelected). Self-set so a tab is never tabbable before the parent wires it.
+        if (!this.hasAttribute('tabindex'))
+            this.tabIndex = -1;
+    }
+    /**
+     * Wire this tab to the panel it controls (called ONCE by the owning ui-tabs). Seeds a stable `id` (for the
+     * reverse `aria-labelledby` on the panel) when the author gave none, and points `aria-controls` at the panel
+     * via the internals element-reflection (no host attribute). Idempotent across reconnect.
+     */
+    link(panel, ownId) {
+        if (!this.id)
+            this.id = ownId;
+        reflectAriaElements(this.internals, 'ariaControlsElements', [panel]);
+    }
+    /**
+     * Reflect this tab's selection (called by the owning ui-tabs on every `selected` change). Drives THREE facts:
+     * `aria-selected` (via internals), the roving tabindex (0 when selected, −1 otherwise — exactly one tab is in
+     * the tab order), and the `:state(selected)` CSS hook the indicator/ink key off. `states` is optional-chained
+     * — jsdom has no CustomStateSet (the real selected-indicator paint is tabs.browser.test.ts).
+     */
+    setSelected(selected) {
+        this.internals.ariaSelected = selected ? 'true' : 'false';
+        this.tabIndex = selected ? 0 : -1; // roving: the selected tab is the single tab-order entry
+        if (selected)
+            this.internals.states?.add('selected');
+        else
+            this.internals.states?.delete('selected');
+    }
+}
+if (!customElements.get('ui-tab'))
+    customElements.define('ui-tab', UITabElement);

package/dist/controls/tabs/tabs.css

@@ -0,0 +1,181 @@
+/* tabs.css — the SINGLE sheet for the tabs compound: ui-tabs (the surface shell + the tablist strip), ui-tab
+ * (the interactive rows), ui-tab-panel (the content regions). Two sectioned blocks (ADR-0003): a :where() TOKEN
+ * block (specificity 0 — declares the --ui-tabs-* chain from the colour roles + the dimensional ramp) then an
+ * @scope STYLES block (consumes ONLY --ui-tabs-* + the shared fleet focus-ring/motion tokens — token hygiene).
+ * Linked via the component-styles barrel (wired in decomp s12), NEVER injected from a .ts (behaviour holds no
+ * runtime style; plan §2).
+ *
+ * Geometry (geometry.md "Pattern" size-class — tabs is the named example): the interactive TAB ROWS take the
+ * CONTROL height (--md-sys-height-*), while the SHELL (strip gap, panel padding) uses the --md-sys-space layout ladder.
+ * Two distinct ledgers, never interchanged. The surface (the shell background + the elevation/brightness axes)
+ * is the shared container.css seam — this sheet does not repoint --ui-container-bg (ADR-0104): a bare <ui-tabs>
+ * is transparent by default like the rest of the container family (ADR-0015 cl.1); a plane is an asked-for
+ * intent via the already-shipped `elevation`/`brightness` axes (e.g. `<ui-tabs elevation="0">`).
+ *
+ * `[fill]` (ADR-0144 Q1) — ONE opt-in CSS-only posture: the shell becomes a flex column filling a height-bounded
+ * parent (a pinned tablist strip + an internally scrolling active panel) — the exact composition `agent-admin.css`
+ * (TKT-0085) hand-rolled per consumer for lack of a shipped variant. The panel's scrollbar-visibility seam
+ * (`--ui-tabs-panel-scrollbar-width`) is consumer-INHERITED — var()-fallback only, deliberately NOT declared in
+ * the token block below (an own declaration would beat a composing surface's inherited value — the same
+ * TKT-0065 alias-resolution lesson `split-pane.css` already records). Default (`[fill]` absent) stays
+ * byte-identical to today's document-flow tabs — negative control in tabs.browser.test.ts. */
+
+/* ════════════════════════ [1] TOKEN BLOCK — :where() declarations (the --md-sys-color-* + ramp entry) ════════════════════════ */
+
+:where(ui-tabs) {
+  /* Tab-row geometry — the CONTROL band (the rows are interactive; geometry.md Pattern class). Fixed at the md
+     ramp step (ui-tabs exposes no [size] axis). */
+  --ui-tabs-tab-height: var(--md-sys-height-md);
+  --ui-tabs-tab-font: var(--md-sys-font-md);
+  --ui-tabs-tab-pad-inline: var(--md-sys-space-md); /* a tab's horizontal padding — the layout ladder */
+
+  /* Shell spacing — the --md-sys-space layout ladder (density-responsive; NEVER the control frame). */
+  --ui-tabs-strip-gap: var(--md-sys-space-xs); /* gap between tabs in the strip */
+  --ui-tabs-panel-pad: var(--md-sys-space-md); /* the panel body padding */
+
+  /* The strip divider + the indicator thickness. */
+  --ui-tabs-strip-line: var(--md-sys-color-neutral-outline-variant);
+  --ui-tabs-indicator-size: 2px;
+
+  /* The tab ink ladder (SOLID roles, never a color-mix — components hold zero colour opinion; ADR-0008) +
+     the selected-tab indicator. */
+  --ui-tabs-ink: var(--md-sys-color-neutral-on-surface-variant); /* idle tab label */
+  --ui-tabs-ink-hover: var(--md-sys-color-neutral-on-surface); /* hover */
+  --ui-tabs-ink-selected: var(--md-sys-color-neutral-on-surface); /* the active tab label */
+  --ui-tabs-indicator: var(--md-sys-color-primary); /* the active-tab underline */
+}
+
+/* ════════════════════════ [2] STYLES BLOCK — @scope (the --ui-tabs-* + fleet consumption) ════════════════════════ */
+
+@scope (ui-tabs) {
+  /* The shell — a block stack [ tablist · selected panel ]. The surface background is the container.css seam
+     (consumed there off --ui-container-bg); this sheet adds no background. */
+  :scope {
+    display: block;
+  }
+
+  /* The tablist strip — a horizontal row of tabs with a bottom divider. role=tablist rides the part div. */
+  :scope > [data-part='tablist'] {
+    display: flex;
+    flex-direction: row;
+    gap: var(--ui-tabs-strip-gap);
+    border-block-end: 1px solid var(--ui-tabs-strip-line);
+  }
+
+  /* A tab — an interactive CONTROL-height row; the host-as-content label is its light-DOM children. */
+  ui-tab {
+    position: relative;
+    box-sizing: border-box;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    block-size: var(--ui-tabs-tab-height);
+    padding-inline: var(--ui-tabs-tab-pad-inline);
+    font-size: var(--ui-tabs-tab-font);
+    color: var(--ui-tabs-ink);
+    white-space: nowrap; /* anonymous host-as-content label text — the SAME no-wrapper gap ui-button had
+                            (button.css, fixed by ADR-0133) also exists here: no overflow/text-overflow, so
+                            a tab label in a narrow tablist would clip/overlap with no ellipsis affordance.
+                            NAMED DEFERRAL, not fixed here (ADR-0133 §Decision cl.3, TKT-0042): no evidence
+                            has been submitted that a tab label actually overflows in practice, and
+                            ADR-0106's Alternatives already rejected a generic fleet-wide truncate fix —
+                            per-control adoption stays per-control evidence. A future report against this
+                            control reopens ADR-0133's Alternatives with its own evidence, rather than
+                            starting cold. */
+    cursor: pointer;
+    user-select: none;
+    -webkit-user-select: none; /* WebKit honours selection-none only via the prefix (button.browser proof) */
+  }
+
+  ui-tab:hover {
+    color: var(--ui-tabs-ink-hover);
+  }
+
+  /* selected — aria-selected rides internals (no [aria-selected] attribute to match), so the visual cue keys
+     off the :state(selected) custom state the parent sets via the tab's internals. */
+  ui-tab:state(selected) {
+    color: var(--ui-tabs-ink-selected);
+  }
+
+  /* The active-tab underline indicator — a ::after bar, transparent until selected. */
+  ui-tab::after {
+    content: '';
+    position: absolute;
+    inset-inline: 0;
+    inset-block-end: 0;
+    block-size: var(--ui-tabs-indicator-size);
+    background: transparent;
+  }
+  ui-tab:state(selected)::after {
+    background: var(--ui-tabs-indicator);
+  }
+
+  /* The shared focus ring (ADR-0009) — keyboard-only :focus-visible, read DIRECTLY from the fleet tokens (the
+     one token-hygiene exception every control shares). Inset offset so the ring sits inside the strip. */
+  ui-tab:focus-visible {
+    outline: var(--md-sys-state-focus-ring-width) solid var(--md-sys-color-focus-ring);
+    outline-offset: calc(-1 * var(--md-sys-state-focus-ring-offset));
+  }
+
+  /* A panel — the body region; only the selected one shows (the rest carry `hidden` and stay in the DOM). The
+     [hidden] rule must be authored here: an author `display:block` on a custom element OUTRANKS the UA
+     `[hidden]{display:none}` (author beats UA), so it would un-hide a hidden panel without this explicit rule. */
+  ui-tab-panel {
+    display: block;
+    padding: var(--ui-tabs-panel-pad);
+  }
+  ui-tab-panel[hidden] {
+    display: none;
+  }
+
+  /* [fill] (ADR-0144 Q1 cl.1) — the shell becomes a flex column filling its height-bounded parent: the tablist
+     strip stays at its natural content height (an ordinary, non-grow flex item, so it stays pinned as the
+     panel scrolls beneath it), the visible panel becomes the ONE flexible, internally-scrolling item. The
+     panel gains NO content-region semantics here (Q3) — it becomes exactly what its shipped `tabindex=0`
+     already promises: a scroll container; header/body/footer composition inside it is the author's own
+     `[data-box]`/`ui-card`, never this sheet's business. */
+  :scope[fill] {
+    display: flex;
+    flex-direction: column;
+    block-size: 100%;
+    min-block-size: 0;
+  }
+  :scope[fill] ui-tab-panel:not([hidden]) {
+    flex: 1 1 auto;
+    min-block-size: 0;
+    overflow-y: auto;
+    /* Consumer-INHERITED scrollbar-visibility seam (the split-pane shape) — see the file banner; deliberately
+       NOT declared in the :where() token block, so the default rides the var() fallback. */
+    scrollbar-width: var(--ui-tabs-panel-scrollbar-width, auto);
+  }
+
+  /* Motion — the state PAINT only (ink + the indicator), gated behind :state(ready) so the first paint SNAPS
+     (the selection applied synchronously at connect does not animate) and only later changes transition. Never
+     geometry, never `all`; timing from the shared motion token. */
+  :scope:state(ready) ui-tab {
+    transition: color var(--md-sys-motion-duration-fast) var(--md-sys-motion-easing-standard);
+  }
+  :scope:state(ready) ui-tab::after {
+    transition: background-color var(--md-sys-motion-duration-fast) var(--md-sys-motion-easing-standard);
+  }
+  @media (prefers-reduced-motion: reduce) {
+    :scope:state(ready) ui-tab,
+    :scope:state(ready) ui-tab::after {
+      transition: none;
+    }
+  }
+
+  /* Forced-colors (WHCM) — keep the selected-tab indicator + label visible as a system colour (the surface
+     drops to Canvas via the container.css role layer; here we guarantee the SELECTED cue survives). */
+  @media (forced-colors: active) {
+    :scope > [data-part='tablist'] {
+      border-block-end-color: CanvasText;
+    }
+    ui-tab:state(selected) {
+      color: Highlight;
+    }
+    ui-tab:state(selected)::after {
+      background: Highlight;
+    }
+  }
+}

package/dist/controls/tabs/tabs.d.ts

@@ -0,0 +1,61 @@
+import { UIContainerElement } from '../../dom/container.js';
+import { type ReactiveProps } from '../../dom/index.js';
+declare const props: {
+    selected: {
+        reflect: true;
+        type: import("../../index.js").PropType<string>;
+        default: string;
+        attribute?: string | false;
+    };
+    fill: {
+        reflect: true;
+        type: import("../../index.js").PropType<boolean>;
+        default: boolean;
+        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 UITabsElement extends ReactiveProps<typeof props> {
+}
+export declare class UITabsElement extends UIContainerElement {
+    #private;
+    static props: {
+        selected: {
+            reflect: true;
+            type: import("../../index.js").PropType<string>;
+            default: string;
+            attribute?: string | false;
+        };
+        fill: {
+            reflect: true;
+            type: import("../../index.js").PropType<boolean>;
+            default: boolean;
+            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 {};