@agent-ui-kit/components 0.0.3

package/dist/controls/switch/switch.css

@@ -0,0 +1,194 @@
+/* switch.css — ui-switch, the single-file component stylesheet (indicator-element.lld.md LLD-C4 / ADR-0041).
+ * Two clearly-SECTIONED blocks:
+ *
+ *   [1] TOKEN BLOCK  — `:where(ui-switch)` (specificity 0,0,0) DECLARES the `--ui-switch-*` chain from the
+ *       colour roles (`--md-sys-color-{family}-{role}`) and the compact widget ramp (`--md-sys-compact-{size}` / ADR-0041).
+ *       `[size]` repoints the box token (the widget ramp step); `:state(checked)` repoints the track + thumb
+ *       colour channels to the primary family (ON = filled primary, OFF = muted neutral); `[disabled]` mutes
+ *       everything. No `color-mix` — colour opinions live in the token layer (ADR-0008).
+ *   [2] STYLES BLOCK — `@scope (ui-switch)` CONSUMES only `--ui-switch-*` for its OWN tokens. The host is
+ *       an `inline-flex` row: the TRACK (`::before`) is the pill (block-size = box, inline-size ≈ 1.8× box,
+ *       border-radius = box/2) and sits as the first flex item; the label slot follows it. The THUMB (`::after`)
+ *       is a circle (`position: absolute`) inset by `--md-sys-widget-inset` (2px) → thumb = box − 4px (ADR-0041
+ *       cl.3: the 2px inset law). The thumb slides from `inset-inline-start: inset` (unchecked) to
+ *       `translate: calc(box * 0.8)` on `:state(checked)` — a net shift of 0.8× box, landing the thumb
+ *       with a symmetric 2px inset from the track end (the ADR-0041 rendered-px proof).
+ *       `:focus-visible` ring (keyboard-only, ADR-0009). Forced-colors safe. Density-invariant.
+ *
+ * Standalone stylesheet — linked via the host page / component-styles barrel (Phase 2); NEVER injected from
+ * switch.ts (behaviour-only `.ts`, no runtime style injection — plan §2).
+ */
+
+/* ════════════════ [1] TOKEN BLOCK — :where(ui-switch) declares --ui-switch-* ════════════════ */
+
+:where(ui-switch) {
+  /* Track colour (unchecked default = solid neutral). A per-state ROLE-LADDER step, never a color-mix
+     (ADR-0008). The OFF track is a state-bearing control part → the SOLID --md-sys-color-neutral-track (SC 1.4.11
+     3:1 vs every surface plane), NOT the old translucent --md-sys-color-neutral-outline-variant which composited to
+     1.51:1 light / 1.73:1 (an SC 1.4.11 fail — the off switch went near-invisible; the white thumb did
+     not carry it either, 1.22–1.84:1). Hover steps one role more prominent (2026-07-02 color audit item 4
+     · ADR-0059). The CHECKED track (primary, below) already clears 3.94:1 light / 4.68:1 dark — untouched. */
+  --ui-switch-track: var(--md-sys-color-neutral-track);
+  --ui-switch-track-hover: var(--md-sys-color-neutral-track-hover);
+  /* Thumb colour (unchecked default = brightest neutral surface ≈ white). Constant across schemes. */
+  --ui-switch-thumb: var(--md-sys-color-neutral-surface-brightest);
+
+  /* Box geometry — the compact widget-box ramp step (ADR-0041; default size = md). `[size]` repoints. */
+  --ui-switch-box: var(--md-sys-compact-md);
+
+  /* Label gap — the rhythm between the pill and the optional label text (density-bearing, via --md-sys-gap-md). */
+  --ui-switch-gap: var(--md-sys-gap-md);
+}
+
+/* [size] → compact widget ramp repoint (ADR-0041: the LITERAL per-[scale] table in dimensions.css
+   re-tables --md-sys-compact-{sm,md,lg}; `[size]` on the host picks which step the switch box targets). */
+:where(ui-switch[size='sm']) {
+  --ui-switch-box: var(--md-sys-compact-sm);
+  --ui-switch-gap: var(--md-sys-gap-sm);
+}
+:where(ui-switch[size='lg']) {
+  --ui-switch-box: var(--md-sys-compact-lg);
+  --ui-switch-gap: var(--md-sys-gap-lg);
+}
+
+/* :state(checked) — primary-family track + on-primary thumb: the ON state, solid primary fill.
+   Hover steps to a darker primary (same ADR-0008 role-ladder pattern as the button). */
+:where(ui-switch):state(checked) {
+  --ui-switch-track: var(--md-sys-color-primary);
+  --ui-switch-track-hover: var(--md-sys-color-primary-hover);
+  --ui-switch-thumb: var(--md-sys-color-primary-on-primary);
+}
+
+/* [disabled] → muted neutral roles (overrides all states). HOLDS at idle: the disabled host is
+   pointer-inert (styles block), so `:hover` never matches it (ADR-0008 disabled pattern). */
+:where(ui-switch[disabled]) {
+  --ui-switch-track: var(--md-sys-color-neutral-surface-high);
+  --ui-switch-track-hover: var(--md-sys-color-neutral-surface-high);
+  --ui-switch-thumb: var(--md-sys-color-neutral-on-surface-variant);
+}
+
+/* ════════════════ [2] STYLES BLOCK — @scope (ui-switch) consumes ONLY --ui-switch-* ════════════════ */
+
+@scope (ui-switch) {
+  /* Host: inline-flex row — the pill track (::before) + optional label slot side by side. */
+  :scope {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--ui-switch-gap);
+    position: relative; /* containing block for the absolutely-positioned ::after thumb */
+    cursor: pointer;
+    -webkit-user-select: none; /* WebKit/Safari still requires the prefix */
+    user-select: none;
+  }
+
+  /* TRACK (::before) — the pill; a sized flex item.
+     block-size = --ui-switch-box; inline-size ≈ 1.8× box; pill radius = box/2.
+     State-PAINT transition only — geometry never animates (geometry.md). */
+  :scope::before {
+    content: '';
+    display: block;
+    flex-shrink: 0; /* never crushed by a long label */
+    box-sizing: border-box;
+
+    block-size: var(--ui-switch-box);
+    inline-size: calc(var(--ui-switch-box) * 1.8);
+    border-radius: calc(var(--ui-switch-box) / 2); /* pill radius = box/2 */
+
+    background: var(--ui-switch-track);
+    transition: background-color var(--md-sys-motion-duration-fast) var(--md-sys-motion-easing-standard);
+  }
+
+  /* THUMB (::after) — a circle inset by --md-sys-widget-inset (2px) on all sides (ADR-0041 cl.3).
+   *
+   * Size:    thumb = box − 2×inset = box − 4px.
+   * Block:   inset-block-start: 50% + transform: translateY(-50%) centres the thumb in the host height.
+   *          With align-items: center on the host, the track (::before) is also vertically centred, so
+   *          the thumb centre coincides with the track centre in both the bare-pill and with-label cases.
+   * Inline:  unchecked → inset-inline-start = inset (2px from inline-start of the host = of the track).
+   *          checked   → translate = 0.8×box (derived: track_width − thumb_size − inset − inset_start
+   *                      = 1.8×box − (box−4) − 2 − 2 = 0.8×box — start and end insets are symmetric).
+   *
+   * Motion: `translate` transitions the thumb slide — a paint-only transform (no layout shift). The
+   * transition is suppressed under `prefers-reduced-motion` (accessibility non-negotiable). */
+  :scope::after {
+    content: '';
+    position: absolute;
+    box-sizing: border-box;
+
+    /* ADR-0041 cl.3: thumb = box − 2×inset = box − 4px */
+    --ui-switch-thumb-size: calc(var(--ui-switch-box) - 2 * var(--md-sys-widget-inset));
+    inline-size: var(--ui-switch-thumb-size);
+    block-size: var(--ui-switch-thumb-size);
+    border-radius: 50%; /* circle */
+
+    /* Unchecked starting position: 2px from inline-start + vertically centred in the host */
+    inset-block-start: 50%;
+    transform: translateY(-50%);
+    inset-inline-start: var(--md-sys-widget-inset);
+
+    background: var(--ui-switch-thumb);
+    transition: translate var(--md-sys-motion-duration-fast) var(--md-sys-motion-easing-standard);
+  }
+
+  /* :state(checked) — slide the thumb to the END by 0.8×box (the net shift from the start position).
+   * The end-side inset = track_width − (inset_start + 0.8×box + thumb_size) = 2px = --md-sys-widget-inset ✓
+   * (the 2px inset law holds on BOTH edges and in BOTH states — the ADR-0041 rendered-px proof). */
+  :scope:state(checked)::after {
+    translate: calc(var(--ui-switch-box) * 0.8) 0;
+  }
+
+  /* Hover — repoints `background` of the track from the per-state token (ADR-0008). Disabled is
+     pointer-inert so :hover never matches it (the disabled token holds at the idle value, no lift possible). */
+  :scope:hover::before {
+    background: var(--ui-switch-track-hover);
+  }
+
+  /* Focus ring (ADR-0009) — the SHARED fleet ring: `:focus-visible` keyboard-only. These are the ONE
+     deliberate exception to "consume only --ui-switch-*": a focus ring is a fleet constant, read directly
+     so every control draws the identical ring. `outline` is layout-neutral (no box geometry shift). */
+  :scope:focus-visible {
+    outline: var(--md-sys-state-focus-ring-width) solid var(--md-sys-color-focus-ring);
+    outline-offset: var(--md-sys-state-focus-ring-offset);
+  }
+
+  /* Reduced motion — zero all transitions on this control (geometry.md: NEVER animate the ramp;
+     accessibility: non-negotiable for users who need it). */
+  @media (prefers-reduced-motion: reduce) {
+    :scope::before {
+      transition: none;
+    }
+    :scope::after {
+      transition: none; /* the thumb slide must also be suppressed */
+    }
+  }
+
+  /* disabled host — pointer-inert so :hover/:active never lift the muted neutral tokens */
+  :scope:is([disabled]) {
+    pointer-events: none;
+    cursor: default;
+  }
+
+  /* forced-colors — keep the track visible as a border + Canvas fill (unchecked) or Highlight (checked);
+     the thumb paints as ButtonText (off) / HighlightText (on). forced-color-adjust:none preserves our
+     explicit system-colour mappings so the browser does not re-override them (matches checkbox.css pattern).
+     The `:focus-visible` ring survives for free: `--md-sys-color-focus-ring → Highlight` from the token layer. */
+  @media (forced-colors: active) {
+    :scope::before {
+      border: 2px solid ButtonText;
+      background: Canvas;
+    }
+    :scope:state(checked)::before {
+      border-color: Highlight;
+      background: Highlight;
+      forced-color-adjust: none;
+    }
+    :scope::after {
+      background: ButtonText;
+      forced-color-adjust: none;
+    }
+    :scope:state(checked)::after {
+      background: HighlightText;
+      forced-color-adjust: none;
+    }
+  }
+}

package/dist/controls/switch/switch.d.ts

@@ -0,0 +1,5 @@
+import { UIIndicatorElement } from '../_base/index.js';
+export declare class UISwitchElement extends UIIndicatorElement {
+    /** LLD-C2: ARIA role for the switch widget — UIIndicatorElement.connected() sets internals.role from this. */
+    static role: string;
+}

package/dist/controls/switch/switch.js

@@ -0,0 +1,18 @@
+// switch.ts — UISwitchElement, the FACE switch control (goals.md §G6 / indicator-element.lld.md LLD-C4).
+// BEHAVIOUR + self-define ONLY — the base UIIndicatorElement owns everything: the boolean form value
+// (checked/value props + formValue()), the state machine + ARIA (ariaChecked, :state(checked),
+// tabbable/disabled), and the pressActivation toggle (click/Space toggles; Enter does NOT — platform parity).
+//
+// This leaf adds ONLY: `static role = 'switch'` (LLD-C2 — internals.role set from it in connected()), the
+// pill-track + 2px-inset thumb geometry in switch.css (LLD-C4), and the contract in switch.md.
+// Boolean only (no indeterminate — a switch is ON/OFF; the base's `indeterminate` property is not used
+// here and no CSS paints an indeterminate state). Optional label slot (light-DOM, anatomy ADR-0006).
+//
+// Layer: controls/ — imports only controls/_base/ (inward-only ✓: controls ← traits ← dom ← reactive).
+import { UIIndicatorElement } from "../_base/index.js";
+export class UISwitchElement extends UIIndicatorElement {
+    /** LLD-C2: ARIA role for the switch widget — UIIndicatorElement.connected() sets internals.role from this. */
+    static role = 'switch';
+}
+if (!customElements.get('ui-switch'))
+    customElements.define('ui-switch', UISwitchElement);

package/dist/controls/table/table-model.d.ts

@@ -0,0 +1,43 @@
+import type { PropConfig } from '../../dom/props.js';
+/** One table column — the SAME shape serves both the public input contract (SPEC-R1: `type` is optional,
+ *  defaulting to `'string'`) and the rendered-set (post-`cleanColumns`, `type` is always POPULATED — a
+ *  runtime invariant `cleanColumns` guarantees, not one TS enforces, so a caller may omit `type` and still
+ *  satisfy this interface). A valid `key`/`label` string pair; `type` NORMALIZED to a member of the closed
+ *  set when present. */
+export interface TableColumn {
+    key: string;
+    label: string;
+    type?: 'string' | 'number';
+}
+/** One table row — a structurally valid record (SPEC §2): a plain, non-null, non-array object. Cell
+ *  VALUES are unconstrained here (`string | number | null | undefined | unknown`) — `resolveCell` is the
+ *  only place a value is judged. Never positional (fork F1) — cells resolve by `column.key` lookup. */
+export type TableRow = Record<string, unknown>;
+/**
+ * Harden an arbitrary input into the rendered column set (SPEC-R3 rows 1/3/4): a non-array input yields
+ * `[]`; each entry survives only as a plain object with a `string` `key` AND a `string` `label` — dropped,
+ * never coerced (SPEC-R3 row 3). `type` is NORMALIZED, never a drop reason: `'number'` is kept as-is,
+ * anything else (absent, or an unknown string — SPEC-R3 row 4) becomes `'string'`. Order preserved
+ * (positional — duplicate keys both survive, SPEC-R3 row 12).
+ */
+export declare function cleanColumns(input: unknown): TableColumn[];
+/**
+ * Harden an arbitrary input into the rendered row set (SPEC-R3 row 5): a non-array input yields `[]`; each
+ * entry survives only as a plain object (non-null, non-array) — dropped, never coerced. Cell values are
+ * NOT inspected here (structural validity only, SPEC §2) — `resolveCell` judges each cell at render time.
+ * Order preserved (positional).
+ */
+export declare function cleanRows(input: unknown): TableRow[];
+/** Format a finite number via the shared, memoized `Intl.NumberFormat` (default locale). */
+export declare function formatNumber(v: number): string;
+/**
+ * The SPEC-R3 cell-resolution table (rows 6-11), as one pure, NEVER-throwing function: absent/missing key/
+ * `undefined`/`null` → `''` (the empty cell, rows 6/7) · a finite `number` (ANY column type — row 10, value-
+ * driven, never column-gated) → `formatNumber` · a non-finite `number` (`NaN`/`±Infinity`, row 8) → the `—`
+ * placeholder · a `string` (row 9, incl. a type-mismatched string in a `type:'number'` column) → verbatim,
+ * uncoerced · anything else — `boolean`/`object`/`array` (row 11, a foreign-typed cell) → `''`, the value
+ * dropped, the row survives. Alignment is NEVER decided here — it is column-driven (LLD-C2/C3).
+ */
+export declare function resolveCell(column: TableColumn, row: TableRow): string;
+export declare const tableColumnsProp: PropConfig<TableColumn[]>;
+export declare const tableRowsProp: PropConfig<TableRow[]>;

package/dist/controls/table/table-model.js

@@ -0,0 +1,124 @@
+// table-model.ts — the pure, DOM-free table math (LLD-C1, report-family.lld.md §2). No DOM, no host,
+// unit-testable in plain Node/Vitest. Owns four things (the bar-math/sparkline-math precedent — the
+// in-folder pure-core split, ADR-0111 cl.8):
+//
+//   1. Input hardening (`cleanColumns`/`cleanRows`, SPEC-R3 rows 1/3/4/5): a non-array input is `[]`; a
+//      column entry survives only as a plain object with a `string` `key` AND a `string` `label` — `type`
+//      is NORMALIZED ('number' kept, anything else incl. an unknown string → 'string'), never dropping the
+//      column over a bad `type`. A row entry survives only as a plain object (non-null, non-array) — cell
+//      VALUES are not judged here, that is `resolveCell`'s per-cell job (structural validity only, SPEC §2).
+//      Both drop, never coerce; order is preserved (positional — SPEC-R3 row 12's duplicate-key case).
+//   2. Cell resolution (`resolveCell`, SPEC-R3 rows 6-11): the pure mapping `(column, row) → rendered cell
+//      text`, covering every value-degenerate case. NEVER throws. Alignment is NOT decided here — it is
+//      COLUMN-driven (the `data-type='number'` attribute the element sets from `column.type`, LLD-C3) —
+//      this function only decides the printed TEXT, which is VALUE-driven.
+//   3. `formatNumber` — a module-memoized default-locale `Intl.NumberFormat` (the chart-family printed-value
+//      precedent, bar-math.ts/sparkline-math.ts).
+//   4. `tableColumnsProp`/`tableRowsProp`, the safe JSON codecs (SPEC-R1 AC3): `from(null)` (attribute
+//      absent/removed) is `[]`, NEVER `null`; malformed attribute JSON is caught and also falls back to
+//      `[]` — no throw ever reaches `attributeChangedCallback`. `dom/props.ts`'s generic `jsonType<T>()` is
+//      deliberately NOT used — its bare `JSON.parse` throws on malformed attributes and maps a removed
+//      attribute to `null`, both of which SPEC-R1 forbids reaching the render path (the exact reasoning
+//      bar-math.ts's `barDataProp` states for its own codec — the chart-family construction, reused here).
+/** A plain, non-null, non-array object — the structural test both `cleanColumns` and `cleanRows` share. */
+function isPlainObject(v) {
+    return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+/**
+ * Harden an arbitrary input into the rendered column set (SPEC-R3 rows 1/3/4): a non-array input yields
+ * `[]`; each entry survives only as a plain object with a `string` `key` AND a `string` `label` — dropped,
+ * never coerced (SPEC-R3 row 3). `type` is NORMALIZED, never a drop reason: `'number'` is kept as-is,
+ * anything else (absent, or an unknown string — SPEC-R3 row 4) becomes `'string'`. Order preserved
+ * (positional — duplicate keys both survive, SPEC-R3 row 12).
+ */
+export function cleanColumns(input) {
+    if (!Array.isArray(input))
+        return [];
+    const out = [];
+    for (const entry of input) {
+        if (!isPlainObject(entry))
+            continue;
+        const key = entry.key;
+        const label = entry.label;
+        if (typeof key !== 'string' || typeof label !== 'string')
+            continue;
+        out.push({ key, label, type: entry.type === 'number' ? 'number' : 'string' });
+    }
+    return out;
+}
+/**
+ * Harden an arbitrary input into the rendered row set (SPEC-R3 row 5): a non-array input yields `[]`; each
+ * entry survives only as a plain object (non-null, non-array) — dropped, never coerced. Cell values are
+ * NOT inspected here (structural validity only, SPEC §2) — `resolveCell` judges each cell at render time.
+ * Order preserved (positional).
+ */
+export function cleanRows(input) {
+    if (!Array.isArray(input))
+        return [];
+    const out = [];
+    for (const entry of input) {
+        if (isPlainObject(entry))
+            out.push(entry);
+    }
+    return out;
+}
+/** Module-memoized default-locale formatter — the exact text every finite-number cell prints (SPEC-R3 row 10). */
+const numberFormat = new Intl.NumberFormat();
+/** Format a finite number via the shared, memoized `Intl.NumberFormat` (default locale). */
+export function formatNumber(v) {
+    return numberFormat.format(v);
+}
+/** The defined "present but unrepresentable" placeholder (SPEC §2) — U+2014 EM DASH, never the strings
+ *  `NaN`/`Infinity`/`-Infinity`. */
+const PLACEHOLDER = '—';
+/**
+ * The SPEC-R3 cell-resolution table (rows 6-11), as one pure, NEVER-throwing function: absent/missing key/
+ * `undefined`/`null` → `''` (the empty cell, rows 6/7) · a finite `number` (ANY column type — row 10, value-
+ * driven, never column-gated) → `formatNumber` · a non-finite `number` (`NaN`/`±Infinity`, row 8) → the `—`
+ * placeholder · a `string` (row 9, incl. a type-mismatched string in a `type:'number'` column) → verbatim,
+ * uncoerced · anything else — `boolean`/`object`/`array` (row 11, a foreign-typed cell) → `''`, the value
+ * dropped, the row survives. Alignment is NEVER decided here — it is column-driven (LLD-C2/C3).
+ */
+export function resolveCell(column, row) {
+    const value = row[column.key];
+    if (value === undefined || value === null)
+        return '';
+    if (typeof value === 'number')
+        return Number.isFinite(value) ? formatNumber(value) : PLACEHOLDER;
+    if (typeof value === 'string')
+        return value;
+    return ''; // boolean / object / array — a foreign-typed cell value, dropped (the row survives)
+}
+/**
+ * The safe `columns`/`rows` codec (SPEC-R1 AC3): `from(null)` (the attribute absent/removed) → `[]`, never
+ * `null`; malformed attribute JSON is caught and also falls back to `[]` — no throw ever reaches
+ * `attributeChangedCallback`. Every parsed value (well-formed or not) is run through the matching hardening
+ * function, so the property never carries a raw, un-hardened array (the codec and the SPEC-R3 case-3
+ * property-write guard — table.ts's effects call `cleanColumns`/`cleanRows` again — share the one hardening
+ * function each).
+ */
+function safeJsonCodec(clean) {
+    return {
+        from(attr) {
+            if (attr === null)
+                return [];
+            try {
+                return clean(JSON.parse(attr));
+            }
+            catch {
+                return [];
+            }
+        },
+        to(value) {
+            return JSON.stringify(value);
+        },
+    };
+}
+export const tableColumnsProp = {
+    type: safeJsonCodec(cleanColumns),
+    default: [],
+};
+export const tableRowsProp = {
+    type: safeJsonCodec(cleanRows),
+    default: [],
+};

package/dist/controls/table/table.css

@@ -0,0 +1,90 @@
+/* table.css — ui-table, the Display-class static data table (LLD-C3, report-family.lld.md §2;
+ * report-family.spec.md SPEC-R2/R3/R5/R14/R15/R16/R17). Two clearly-SECTIONED blocks (ADR-0003):
+ *
+ *   [1] TOKEN BLOCK  — `:where(ui-table)` (specificity 0,0,0) DECLARES every `--ui-table-*` component
+ *       token from the fleet `--md-sys-color-*` roles + the `--md-sys-space-*` rhythm ladder. No `[size]`/
+ *       `[scale]` repoint matrix — `ui-table` is Display-class (SPEC-R17): no control height, no
+ *       `--md-sys-height-*` lever, the type matrix + the space ladder are the whole lever.
+ *   [2] STYLES BLOCK — `@scope (ui-table)` CONSUMES only `--ui-table-*` (∪ the shared `--md-sys-*`/
+ *       `--md-sys-space-*` namespaces). Owns the UA-default + page-cascade reset a stamped native `<table>`
+ *       needs (border-collapse, cell padding, caption alignment — SPEC-R2 AC2, the ADR-0078 cl.4
+ *       `font: inherit`-reset precedent scaled up) and the overflow-in-own-container law (SPEC-R5): the
+ *       component's OWN `[data-part='scroll']` container scrolls, never the page.
+ *
+ * RTL (SPEC-R16): logical properties throughout (`text-align: start/end`, `border-block-end`, block/inline
+ * padding pairs); the native `<table>` handles column order under `dir="rtl"` for free; `text-align: end`
+ * flips number-column alignment — the browser leg (table.browser.test.ts) measures it.
+ *
+ * WHCM (SPEC-R15): NO dedicated `forced-colors` block — every row/header separator is a REAL `border`
+ * (system-ink-repainted, never removed under `forced-colors: active`, unlike a background); all content is
+ * real text. The bar-chart/badge fill lesson (a background-drawn mark vanishing under WHCM) does not apply
+ * here — nothing in this file draws a background-only mark.
+ *
+ * Standalone stylesheet — linked via the host page / component-styles barrel (Phase 2); NEVER injected
+ * from table.ts (behaviour-only `.ts`, no runtime style injection — plan §2).
+ */
+
+/* ════════════════ [1] TOKEN BLOCK — :where(ui-table) declares --ui-table-* ════════════════ */
+
+:where(ui-table) {
+  --ui-table-min-inline-size: 16em; /* the whole-shape floor (SPEC-R14/R17 AC1) */
+  --ui-table-cell-pad-inline: var(--md-sys-space-sm); /* rhythm — rides [density] free (ADR-0103) */
+  --ui-table-cell-pad-block: var(--md-sys-space-xs);
+  --ui-table-rule-ink: var(--md-sys-color-neutral-outline-variant); /* row-separator hairline */
+  --ui-table-header-rule-ink: var(--md-sys-color-neutral-outline); /* thead underline, stronger */
+  --ui-table-caption-ink: var(--md-sys-color-neutral-on-surface-variant);
+}
+
+/* ════════════════ [2] STYLES BLOCK — @scope (ui-table) consumes ONLY --ui-table-* ════════════════ */
+
+@scope (ui-table) {
+  :scope {
+    display: block;
+    min-inline-size: var(--ui-table-min-inline-size); /* the whole-shape floor — a bare instance never collapses */
+  }
+
+  /* the component's OWN overflow container (SPEC-R5) — a wide table scrolls HERE, never the page */
+  :scope [data-part='scroll'] {
+    overflow-x: auto;
+  }
+
+  /* the UA-default + page-cascade reset (SPEC-R2 AC2) — a stamped native <table> owns its OWN geometry */
+  :scope table {
+    border-collapse: collapse;
+    inline-size: 100%; /* a narrow table fills the host — no orphaned gutter (SPEC-R5) */
+    font: inherit;
+    text-align: start;
+    font-size: var(--md-sys-typescale-body-medium-size);
+    line-height: var(--md-sys-typescale-body-medium-line-height);
+  }
+
+  :scope caption {
+    text-align: start;
+    color: var(--ui-table-caption-ink);
+    padding-block-end: var(--ui-table-cell-pad-block);
+  }
+
+  :scope th,
+  :scope td {
+    padding: var(--ui-table-cell-pad-block) var(--ui-table-cell-pad-inline);
+    text-align: start;
+    overflow-wrap: anywhere; /* a huge unbroken string wraps within its cell (SPEC-R3 row 14) */
+  }
+
+  :scope th {
+    font-weight: var(--md-sys-typescale-label-large-weight);
+    border-block-end: 1px solid var(--ui-table-header-rule-ink);
+  }
+
+  :scope tbody tr {
+    border-block-end: 1px solid var(--ui-table-rule-ink);
+  }
+
+  /* alignment is COLUMN-driven (SPEC-R3 row 9): every cell in a type:"number" column end-aligns and never
+     wraps — a huge mismatched string here forces the [data-part='scroll'] container instead (SPEC-R5). */
+  :scope [data-type='number'] {
+    text-align: end;
+    font-variant-numeric: tabular-nums;
+    white-space: nowrap;
+  }
+}

package/dist/controls/table/table.d.ts

@@ -0,0 +1,29 @@
+import { UIElement, type ReactiveProps } from '../../dom/index.js';
+import { type TableColumn, type TableRow } from './table-model.js';
+declare const props: {
+    columns: import("../../index.js").PropConfig<TableColumn[]>;
+    rows: import("../../index.js").PropConfig<TableRow[]>;
+    label: {
+        reflect: true;
+        type: import("../../index.js").PropType<string>;
+        default: string;
+        attribute?: string | false;
+    };
+};
+export interface UITableElement extends ReactiveProps<typeof props> {
+}
+export declare class UITableElement extends UIElement {
+    #private;
+    static props: {
+        columns: import("../../index.js").PropConfig<TableColumn[]>;
+        rows: import("../../index.js").PropConfig<TableRow[]>;
+        label: {
+            reflect: true;
+            type: import("../../index.js").PropType<string>;
+            default: string;
+            attribute?: string | false;
+        };
+    };
+    protected connected(): void;
+}
+export {};