@adia-ai/adia-ui-factory 0.2.3 → 0.8.0

package/skills/adia-ui-kit/references/patterns-data.md

@@ -1,1066 +0,0 @@
-# Data & Dashboard Patterns
-
-## Composition rule: no `<style>`, no inline `style=`
-
-Training-data and gen-UI example pages are expected to be **pure primitive
-composition**: the HTML contains only AdiaUI component tags + native HTML
-(h1-h6, p, article, section, etc.). A `<style>` block or any `style="…"`
-attribute in a page is a signal that the page has drifted — either the
-author hasn't discovered the right primitive, or the layout needs a new
-primitive extracted.
-
-Concretely:
-
-- **Layout comes from `col-ui`, `row-ui`, `grid-ui`, `stack-ui`** — not from
-  `display: flex; flex-direction: column` on a `<div>`.
-- **Width constraints are set via design-token CSS variables on a
-  controller-owned element, not inline style.** For a 48rem reading column
-  on a doc-template page, setup.js does
-  `section.style.setProperty('--page-content-max-width', '48rem')` on the
-  existing `[data-content-body] > section` instead of declaring a local
-  `<style>` block.
-- **Asymmetric ratios use `grid-ui[columns="N"]` + `[span="M"]`** — never
-  `style="grid-template-columns: …"`. See "Asymmetric Grid" below.
-- **Child sizing inside row-ui** uses `[grow]` — never `style="flex:1"`.
-- **"Fake" elements** — custom tag names dressed up in page-local CSS
-  (`<tool-call-ui>`, `<citation-ui>`, `<link-preview-ui>`, `<map-ui>` used
-  purely as styled `<div>` replacements without a real component class)
-  are a hard reject. Either promote them to a real component with its own
-  CSS file, or replace with a primitive composition (`accordion-ui` for
-  collapsibles, `tag-ui` for chips, `card-ui` + `[slot="media"]` for link
-  previews, `image-ui` for map placeholders).
-
-JS-driven hydration via `setup.js` (setting data, attaching listeners,
-reading URL state, setting CSS variables via `setProperty`) is always
-allowed. The rule isn't "no JS styling" — it's "no styling stored in the
-HTML page."
-
-**Recognition:** if grep of an example page finds `<style`, `style="`, or a
-custom tag name not present in `packages/web-components/components/`, the
-page needs a rewrite before it's fit for training-data extraction.
-
-## Stat Cards (KPI Grid)
-
-```html
-<grid-ui columns="4" gap="2">
-  <card-ui>
-    <header><span slot="heading" variant="label"><small>Revenue</small></span></header>
-    <section><col-ui gap="1">
-      <strong variant="title">$48,200</strong>
-      <badge-ui text="+12.5%" variant="success" size="xs"></badge-ui>
-    </col-ui></section>
-  </card-ui>
-  <card-ui>
-    <header><span slot="heading" variant="label"><small>Users</small></span></header>
-    <section><col-ui gap="1">
-      <strong variant="title">2,340</strong>
-      <badge-ui text="+8%" variant="success" size="xs"></badge-ui>
-    </col-ui></section>
-  </card-ui>
-  <card-ui>
-    <header><span slot="heading" variant="label"><small>Bounce Rate</small></span></header>
-    <section><col-ui gap="1">
-      <strong variant="title">24.3%</strong>
-      <badge-ui text="-3.1%" variant="danger" size="xs"></badge-ui>
-    </col-ui></section>
-  </card-ui>
-  <card-ui>
-    <header><span slot="heading" variant="label"><small>Avg Session</small></span></header>
-    <section><col-ui gap="1">
-      <strong variant="title">4m 23s</strong>
-      <badge-ui text="+15s" variant="info" size="xs"></badge-ui>
-    </col-ui></section>
-  </card-ui>
-</grid-ui>
-```
-
-Key rule: `Grid > Card > Header + Section > Column`. Never Grid inside Grid for stats.
-
-## Data Table
-
-Table data is set via JS properties. **Pair every non-trivial table with
-`<table-toolbar-ui for="…">`** for filter / sort / columns-visibility /
-search affordances — the toolbar already wires those into the bound table
-+ auto-detects column types. Use **cell-types** in the column descriptors
-to delegate formatting + alignment + sort to the table itself.
-
-### Canonical shape — toolbar above card (per `table-toolbar.yaml` a2ui.rules)
-
-The yaml-preferred composition: toolbar OUTSIDE `<card-ui>`, paired via a
-`<col-ui gap="3">`. Card holds only the table, in a `<section bleed>` for
-edge-to-edge rows:
-
-```html
-<col-ui gap="3">
-  <table-toolbar-ui for="orders" text="Recent orders"></table-toolbar-ui>
-  <card-ui>
-    <section bleed>
-      <table-ui id="orders" sortable selectable></table-ui>
-    </section>
-    <footer>
-      <pagination-ui total="100" page="1" siblings="2"></pagination-ui>
-    </footer>
-  </card-ui>
-</col-ui>
-```
-
-### Alternative — toolbar inside card, two-`<section>` split
-
-When the surface already has a card-ui header (title + non-toolbar
-actions like "Export" or "New"), keep the toolbar **inside** the same
-card. The composition uses **two adjacent `<section>` slots**: toolbar
-in normal-inset section, table in `<section bleed>`. Substrate-supported,
-intentional — the `bleed` attribute is a per-section knob, not a
-per-card knob.
-
-```html
-<card-ui>
-  <header>
-    <span slot="heading" variant="section">Recent orders</span>
-    <button-ui slot="action" text="Export" variant="ghost" size="sm" icon="download"></button-ui>
-  </header>
-  <section>
-    <table-toolbar-ui for="orders"></table-toolbar-ui>
-  </section>
-  <section bleed>
-    <table-ui id="orders" sortable selectable></table-ui>
-  </section>
-  <footer>
-    <pagination-ui total="100" page="1" siblings="2"></pagination-ui>
-  </footer>
-</card-ui>
-```
-
-> ⚠️ **Do NOT place `<table-toolbar-ui>` and `<table-ui>` inside the same
-> `<section bleed>`.** Both get edge-to-edge treatment; the toolbar's
-> Filter / Sort / Columns / Search controls then touch the card border
-> with zero inset. The right shape uses **two** sections — `<section>`
-> (normal inset) for the toolbar, `<section bleed>` (opt-out) for the
-> table.
->
-> Likewise, do NOT place both inside a single bare `<section>` (no
-> bleed). The table rows then get the card's content padding on every
-> row — wasted horizontal real estate on a data-dense surface.
->
-> Reference: `card-ui.yaml` `<section[bleed]>` slot; `table-toolbar.yaml`
-> a2ui.rules: "Place the toolbar ABOVE the `<card-ui>` containing the
-> table-ui, or use `[variant="card"]` when standing alone outside a
-> card-ui parent."
-
-### Anti-pattern — hand-rolled toolbar children
-
-`<table-toolbar-ui>` **always auto-renders** Filter / Sort / Columns /
-Search (each opt-out-able via `no-filter` / `no-sort` / `no-columns` /
-`no-search` booleans). Slotted filter children render in **addition**
-to the auto-chrome — produces a doubled toolbar:
-
-```html
-<!-- WRONG — double chrome -->
-<table-toolbar-ui for="orders">
-  <input-ui placeholder="Search…" icon="magnifying-glass"></input-ui>
-  <select-ui placeholder="Status"></select-ui>           <!-- redundant -->
-  <select-ui placeholder="Tags"></select-ui>             <!-- redundant -->
-</table-toolbar-ui>
-```
-
-The right shape: drop the children, let the toolbar own its chrome.
-For trailing primary actions (Invite / Export / +New), use the
-`slot="actions"` slot:
-
-```html
-<table-toolbar-ui for="orders" text="Recent orders">
-  <button-ui slot="actions" text="New" variant="primary" icon="plus"></button-ui>
-</table-toolbar-ui>
-```
-
-Equally wrong: re-implementing filter / search affordances in the parent
-`<card-ui>`'s `<header>` while `<table-toolbar-ui>` is mounted — same
-doubled-chrome class. The toolbar owns those affordances; card-header
-buttons should be page-level actions (Export, +New, Invite), not data
-controls.
-
-Reference: `table-toolbar.yaml` props lines 32-81 (six boolean opt-outs
-+ `for=` binding); a2ui.rules: "Do NOT also use `<card-ui>`'s `<header>`
-on the same card — that produces a doubled chrome row."
-
-### Column descriptors — pass raw values, use cell-types
-
-`<table-ui>` ships **12 built-in cell types** + a `render(value, row, cell, meta)`
-escape hatch for custom rendering. Each cell type handles formatting,
-default alignment, and the sort comparator automatically — pre-formatting
-values in the data layer **defeats the cell-types system + leaves columns
-left-aligned by default**.
-
-```js
-const STATUS_VARIANTS = {
-  'submitted': 'info',
-  'in-review': 'warning',
-  'approved':  'success',
-  'denied':    'danger',
-  'paid':      'success',
-};
-
-const table = document.querySelector('#orders');
-table.columns = [
-  { key: 'id',        label: 'Order ID' },
-  { key: 'customer',  label: 'Customer' },
-  { key: 'status',    label: 'Status',    type: 'badge',
-    meta: { variants: STATUS_VARIANTS } },
-  { key: 'amount',    label: 'Amount',    type: 'currency',
-    meta: { currency: 'USD' } },
-  { key: 'submitted', label: 'Submitted', type: 'date' },
-  { key: 'tags',      label: 'Tags',      render: renderTagsCell,
-    sortable: false },
-];
-table.data = [
-  { id: '#4021', customer: 'Jane Doe', status: 'approved',
-    amount: 240.00, submitted: '2026-05-19T22:34:03Z',
-    tags: [{ id: 't1', label: 'priority', color: 'warning' }] },
-  { id: '#4022', customer: 'John Smith', status: 'in-review',
-    amount: 89.50, submitted: '2026-05-20T08:12:11Z',
-    tags: [] },
-];
-
-function renderTagsCell(value, row, cell) {
-  cell.replaceChildren();
-  const tags = Array.isArray(value) ? value : [];
-  if (tags.length === 0) return;
-  const chips = document.createElement('row-ui');
-  chips.setAttribute('gap', '1');
-  for (const t of tags) {
-    const chip = document.createElement('tag-ui');
-    chip.setAttribute('variant', t.color ?? 'neutral');
-    chip.setAttribute('size', 'sm');
-    chip.textContent = t.label;
-    chips.appendChild(chip);
-  }
-  cell.appendChild(chips);
-}
-```
-
-Note: `row.amount` is a raw `number` (not `"$240.00"`), `row.submitted`
-is a raw ISO string (not `"May 19, 2026"`), `row.tags` is a raw array
-(not `"priority, paid"`). The data layer stays domain-shaped; the
-cell-type formats on render — and the `currency` type right-aligns
-the column automatically (consumer-set `align: 'end'` on the column
-descriptor has no effect without a matching `type:`).
-
-### Built-in cell types
-
-Source-of-truth: `node_modules/@adia-ai/web-components/components/table/cell-types.js`.
-The 12 registered types:
-
-| Type | Value shape | Renders as | Align | Sort |
-|---|---|---|---|---|
-| `text` (default) | string | flat text | left | alphanumeric |
-| `number` | number | `Intl.NumberFormat()` | right | numeric |
-| `currency` | number | `Intl.NumberFormat(currency)` (default USD; override via `meta.currency`) | right | numeric |
-| `percent` | number | `${value}%` | right | numeric |
-| `date` | ISO string \| Date | localized date (`Intl.DateTimeFormat`, year/month/day) | left | datetime |
-| `datetime` | ISO string \| Date | localized date + time | left | datetime |
-| `boolean` | boolean | `<check-ui disabled>` (checked if truthy) | center | basic |
-| `badge` | string (also lookup key) | `<badge-ui>` with variant from `meta.variants[value]` | left | alphanumeric |
-| `avatar` | string (name) | `<avatar-ui>` + name span | left | alphanumeric |
-| `link` | string (URL or email) | `<a href>` (auto `mailto:` when string contains `@`); use `meta.label` to override display text | left | alphanumeric |
-| `progress` | number (0-100) | `<progress-ui>` + `${value}%` label | left | numeric |
-| `actions` | (no value) — uses `meta.actions: [{ icon, label, event }]` | `<row-ui gap="1">` of `<button-ui icon variant="ghost" size="sm">`; click dispatches `CustomEvent(action.event, { detail: { row } })` | center | (no sort) |
-
-The `meta` field on a column descriptor is per-cell-type configuration:
-`meta.variants` for `badge`, `meta.currency` for `currency`,
-`meta.actions` for `actions`, `meta.label` for `link`.
-
-### Custom rendering — the `render` escape hatch
-
-For cells that need multiple elements, complex layout, or a primitive
-not in the built-in registry (multi-tag chip rows, avatar stacks,
-inline editors), use `render(value, row, cell, meta)`:
-
-```js
-{ key: 'tags', label: 'Tags', sortable: false,
-  render(value, row, cell, meta) {
-    cell.replaceChildren();
-    // ...build DOM into `cell`...
-  },
-  format(value /* , row, meta */) {
-    return (value ?? []).map(t => t.label).join(', ');
-  },
-}
-```
-
-Constraints:
-
-- `render` receives the cell element directly — write into it via
-  `cell.replaceChildren()` + `cell.appendChild(...)`. Don't return a
-  string or a node.
-- `render` is called on every re-render (filter / sort / paginate /
-  data refresh). Memoize expensive content per row; reuse existing
-  child nodes when possible. The built-in `badge` / `avatar` /
-  `progress` cell types model this pattern (re-attach to the cached
-  child element rather than recreate).
-- Set `sortable: false` on columns whose value isn't a sortable scalar
-  (multi-element cells like tag-chip rows have no obvious scalar to
-  sort on).
-- Provide `format(value, row, meta)` as the **text-export fallback** —
-  used by CSV export, accessibility (screen reader), and aria-label
-  composition. Without it, `render`-only cells export as empty strings.
-
-### Toolbar — opt-outs
-
-`<table-toolbar-ui>` shows search + filter + sort + columns by default.
-Hide individually via boolean attributes (each `default: false`,
-`reflect: true`):
-
-| Attribute | Hides |
-|---|---|
-| `no-filter` | Filter popover button |
-| `no-sort` | Sort popover button |
-| `no-columns` | Columns visibility popover button |
-| `no-search` | Search input |
-
-Plus: `variant="card"` wraps the toolbar in card-ui-style chrome when
-standing alone outside a parent `<card-ui>` (used when the toolbar
-floats above a bare table without its own card frame).
-
-Filter rows auto-pick a primitive per column from the bound table's
-`.columns` metadata:
-
-- ≤ 50 distinct values → multi-select (searchable when ≥ 12 options)
-- id-like keys → free-text contains input
-- Override per column via the column descriptor's `filterType: 'select' | 'text'`
-
-Use `<section bleed>` for edge-to-edge table inside a card.
-Table `kind` options: `traditional` (default), `data-list`, `spreadsheet`.
-
-## Chart
-
-```html
-<card-ui>
-  <header>
-    <span slot="heading" variant="section">Revenue</span>
-    <span slot="description">Last 6 months</span>
-  </header>
-  <section>
-    <chart-ui id="revenue" type="bar" x="month" y="revenue"></chart-ui>
-  </section>
-</card-ui>
-```
-
-```js
-document.querySelector('#revenue').data = [
-  { month: 'Jan', revenue: 4200 },
-  { month: 'Feb', revenue: 5100 },
-  { month: 'Mar', revenue: 4800 },
-];
-```
-
-Chart palette: `--a-chart-1` through `--a-chart-10` (OKLCH categorical colors, 36 degree spacing).
-
-## Progress & Loading
-
-```html
-<!-- Linear progress -->
-<col-ui gap="1">
-  <row-ui justify="between">
-    <small>Storage</small><small>6.5 / 10 GB</small>
-  </row-ui>
-  <progress-ui value="65"></progress-ui>
-</col-ui>
-
-<!-- Skeleton placeholder -->
-<card-ui>
-  <section><col-ui gap="4">
-    <skeleton-ui height="1.5rem" width="60%"></skeleton-ui>
-    <skeleton-ui height="1rem" width="80%"></skeleton-ui>
-    <skeleton-ui height="200px"></skeleton-ui>
-  </col-ui></section>
-</card-ui>
-```
-
-## Live Data (DataStreamController)
-
-```js
-import { DataStreamController } from '@adiahealth/web-components/controllers';
-
-const ctrl = new DataStreamController({ max: 50, throttle: 200 });
-ctrl.connect(chartElement);
-ctrl.commands.connect('sse', '/api/metrics/stream');
-// Chart auto-updates as data arrives via ctrl.notify()
-```
-
-Supports: `connect('sse'|'ws', url)`, `poll(url, interval)`, `consume(asyncIterable)`, `push(point)`.
-
-## Dashboard Layout
-
-When this fragment is hosted inside an `<admin-shell>` route fragment,
-wrap it in `<admin-page-body>` → `<section>` per the shell-anatomy
-contract (see `patterns-shells.md` §Wrapper-vs-column + recipes-route-
-fragment). The `<col-ui gap="4">` below is the **content owner inside
-the `<section>`**, not the direct child of `<admin-page-body>`.
-
-```html
-<admin-page>
-  <admin-page-header>
-    <header>
-      <div>
-        <h1>Dashboard</h1>
-        <div data-actions>
-          <select-ui size="sm">
-            <option>Last 7 days</option>
-            <option>Last 30 days</option>
-          </select-ui>
-          <button-ui text="Export" variant="outline" size="sm" icon="download"></button-ui>
-        </div>
-      </div>
-    </header>
-  </admin-page-header>
-  <admin-page-body>
-    <section>
-      <col-ui gap="4">
-
-        <!-- KPI row -->
-        <grid-ui columns="4" gap="2"><!-- stat cards --></grid-ui>
-
-        <!-- Charts -->
-        <grid-ui columns="2" gap="4">
-          <card-ui>
-            <header><span slot="heading" variant="section">Revenue</span></header>
-            <section><chart-ui id="rev" type="bar" x="month" y="value"></chart-ui></section>
-          </card-ui>
-          <card-ui>
-            <header><span slot="heading" variant="section">Users</span></header>
-            <section><chart-ui id="users" type="bar" x="month" y="value"></chart-ui></section>
-          </card-ui>
-        </grid-ui>
-
-        <!-- Activity table — toolbar above card per table-toolbar.yaml canonical -->
-        <col-ui gap="3">
-          <table-toolbar-ui for="activity" text="Recent activity"></table-toolbar-ui>
-          <card-ui>
-            <section bleed><table-ui id="activity" sortable></table-ui></section>
-            <footer><pagination-ui total="100" page="1" siblings="2"></pagination-ui></footer>
-          </card-ui>
-        </col-ui>
-
-      </col-ui>
-    </section>
-  </admin-page-body>
-</admin-page>
-```
-
-The `<section>` inside `<admin-page-body>` owns the page-content inset
-(`--card-inset`). The `<col-ui gap="4">` is the content column inside
-that inset — never a direct child of `<admin-page-body>`. Same contract
-as `patterns-shells.md` §Wrapper-vs-column.
-
-## Asymmetric Grid (3:2, 2:1)
-
-Dashboards routinely want charts wider than sidebars. Express the split via
-`grid-ui[columns="N"]` + `[span="M"]` on children. Do **not** use inline
-`style="grid-template-columns: …"`.
-
-```html
-<!-- 2:1 — main chart + sidebar donut -->
-<grid-ui columns="3" gap="4">
-  <card-ui span="2">
-    <header><h3>Traffic</h3></header>
-    <section><chart-ui type="line" ...></chart-ui></section>
-  </card-ui>
-  <card-ui>
-    <header><h3>Sources</h3></header>
-    <section><chart-ui type="donut" ...></chart-ui></section>
-  </card-ui>
-</grid-ui>
-
-<!-- 3:2 — overview + recent activity -->
-<grid-ui columns="5" gap="4">
-  <card-ui span="3">
-    <header><h3>Overview</h3></header>
-    <section><chart-ui type="bar" ...></chart-ui></section>
-  </card-ui>
-  <card-ui span="2">
-    <header><h3>Recent Sales</h3></header>
-    <section><list-ui divider>...</list-ui></section>
-  </card-ui>
-</grid-ui>
-```
-
-Available ratios out of the box: 1:1 (`columns="2"`), 2:1 (`columns="3"` +
-`span="2"`), 3:1 (`columns="4"` + `span="3"`), 3:2 (`columns="5"` +
-`span="3"+"2"`), 4:1 (`columns="5"` + `span="4"`). Don't reach for 7:5 or
-similar — round to 3:2 instead.
-
-## Dashboard Tabs (with routing)
-
-Declare tabs in the header; put each tab's body in a `[data-tab-panel]`
-sibling. A 10-line setup.js switches visibility on change.
-
-```html
-<div data-content-header>
-  <header>
-    <div>
-      <h1>Analytics</h1>
-      <div data-actions>
-        <segmented-ui value="30d">
-          <segment-ui value="7d" text="7d"></segment-ui>
-          <segment-ui value="30d" text="30d"></segment-ui>
-          <segment-ui value="90d" text="90d"></segment-ui>
-        </segmented-ui>
-      </div>
-    </div>
-    <p>Visitor behavior, acquisition, and conversion.</p>
-    <tabs-ui value="audience">
-      <tab-ui value="audience"    text="Audience"></tab-ui>
-      <tab-ui value="acquisition" text="Acquisition"></tab-ui>
-      <tab-ui value="behavior"    text="Behavior"></tab-ui>
-      <tab-ui value="conversion"  text="Conversion"></tab-ui>
-    </tabs-ui>
-  </header>
-</div>
-
-<div data-content-body>
-  <section>
-  <div data-dashboard-content>
-
-    <!-- cross-tab filter bar lives OUTSIDE the panels -->
-    <grid-ui><card-ui><section>...</section></card-ui></grid-ui>
-
-    <div data-tab-panel="audience">...</div>
-    <div data-tab-panel="acquisition">...</div>
-    <div data-tab-panel="behavior">...</div>
-    <div data-tab-panel="conversion">...</div>
-
-  </div>
-  </section>
-</div>
-```
-
-```javascript
-// index.setup.js — 10-line tab wiring (identical on every dashboard)
-const tabs = router.querySelector('tabs-ui');
-if (tabs) {
-  const panels = router.querySelectorAll('[data-tab-panel]');
-  const sync = (value) => {
-    for (const p of panels) p.hidden = p.dataset.tabPanel !== value;
-  };
-  tabs.addEventListener('change', (e) => sync(e.detail.value));
-  sync(tabs.value || 'audience');
-}
-```
-
-Cross-tab chrome (filter bars, date range pickers, subtitles) goes OUTSIDE
-the panels so it persists across tab switches.
-
-## Row-Click → Detail Drawer
-
-Populated tables can open a detail drawer on row click via `cell-click`.
-The drawer pre-declares structure; setup.js fills data-attribute-marked
-fields from the clicked row.
-
-```html
-<!-- Markup -->
-<table-ui id="tx-table" sortable striped raw paginate="5"></table-ui>
-
-<drawer-ui id="drawer-transaction" side="right" size="md">
-  <header>
-    <span slot="icon"><avatar-ui icon="receipt"></avatar-ui></span>
-    <span slot="heading">
-      <text-ui strong data-tx-customer>Transaction</text-ui>
-      <badge-ui data-tx-status text="Completed" variant="success"></badge-ui>
-    </span>
-    <span slot="action"></span>
-  </header>
-  <section>
-    <text-ui color="subtle" size="sm" data-tx-meta>Details.</text-ui>
-  </section>
-  <section>
-    <grid-ui columns="2" gap="3">
-      <card-ui size="sm"><section><stat-ui label="Amount" data-tx-amount value="—"></stat-ui></section></card-ui>
-      <card-ui size="sm"><section><stat-ui label="Date" data-tx-date value="—"></stat-ui></section></card-ui>
-    </grid-ui>
-    <divider-ui></divider-ui>
-    <col-ui gap="3">
-      <text-ui strong>Customer</text-ui>
-      <input-ui label="Name" data-tx-name readonly></input-ui>
-      <input-ui label="Email" data-tx-email readonly></input-ui>
-    </col-ui>
-  </section>
-  <footer slot="footer">
-    <grid-ui>
-      <button-ui text="Refund" variant="danger"></button-ui>
-      <button-ui text="Close" variant="ghost" onclick="this.closest('drawer-ui').open = false"></button-ui>
-      <button-ui text="View receipt" variant="primary"></button-ui>
-    </grid-ui>
-  </footer>
-</drawer-ui>
-```
-
-```javascript
-// setup.js — the fill() helper handles adia-form + text-element asymmetry
-const VALUE_TAGS = new Set(['input-ui', 'textarea-ui', 'select-ui', 'stat-ui']);
-const fill = (scope, attr, val) => {
-  const el = scope.querySelector(`[${attr}]`);
-  if (!el) return;
-  const tag = el.localName;
-  if (tag === 'input-ui' || tag === 'textarea-ui') {
-    // input-ui/textarea-ui sync their [slot="text"] + data-empty from `value`
-    // (0.6.44+). Do NOT also mirror [slot="text"].textContent — pre-writing it
-    // makes input-ui's update() see no textContent change, so it skips clearing
-    // data-empty → the placeholder renders over the value (FB-87).
-    el.value = val;
-  } else if (VALUE_TAGS.has(tag)) {
-    el.setAttribute('value', val);
-  } else {
-    el.textContent = val;
-  }
-};
-
-table.addEventListener('cell-click', (e) => {
-  const row = e.detail?.row;
-  if (!row) return;
-  fill(drawer, 'data-tx-customer', row.customer);
-  fill(drawer, 'data-tx-meta',     `${row.email} · ${row.date}`);
-  fill(drawer, 'data-tx-name',     row.customer);
-  fill(drawer, 'data-tx-email',    row.email);
-  fill(drawer, 'data-tx-amount',   row.amount);
-  fill(drawer, 'data-tx-date',     row.date);
-  // Status badge uses attribute for both text and variant.
-  const status = drawer.querySelector('[data-tx-status]');
-  const variant = { Completed:'success', Pending:'warning', Failed:'danger' }[row.status] || '';
-  status?.setAttribute('text', row.status);
-  status?.setAttribute('variant', variant);
-  drawer.open = true;
-});
-```
-
-### Editable drawer fields — wrap with `<field-ui>`
-
-The recipe above shows the **read-only** display case (`input-ui readonly`)
-and **numeric KPIs in cards** (`stat-ui` for Amount/Date). For drawers
-that ALSO have **editable string/numeric fields** (CRUD detail panels —
-edit claim, edit project, edit invoice — the most common admin-shell
-drawer shape), wrap each control in `<field-ui>`:
-
-```html
-<section>
-  <col-ui gap="3">
-    <text-ui strong>Claim Details</text-ui>
-    <grid-ui columns="2" gap="3">
-      <field-ui label="Amount (USD)">
-        <input-ui id="drawer-amount" data-tx-amount></input-ui>
-      </field-ui>
-      <field-ui label="Status">
-        <select-ui id="drawer-status" data-tx-status>
-          <option value="submitted">Submitted</option>
-          <option value="approved">Approved</option>
-          <option value="denied">Denied</option>
-        </select-ui>
-      </field-ui>
-    </grid-ui>
-    <field-ui label="Diagnosis codes (ICD-10)" hint="Comma-separated">
-      <input-ui id="drawer-diagnosis" data-tx-diagnosis></input-ui>
-    </field-ui>
-    <field-ui label="Notes">
-      <textarea-ui id="drawer-notes" data-tx-notes rows="3"></textarea-ui>
-    </field-ui>
-  </col-ui>
-</section>
-```
-
-**Why `<field-ui>` is the canonical wrapper (not `input-ui label=…` bare):**
-
-`input-ui`'s `label=` attribute is **inline mode** — the label renders
-as a leading caption *inside* the input chrome, between any prefix and
-the value (per `input.yaml` prop description). When a value is set, the
-inline label concatenates visually with the value — e.g.
-`<input-ui label="Amount (USD)">` with `value="5475.59"` renders as
-"Amount (USD)5475.59" inside the input chrome with no visual separator.
-This is correct for compact single-line UI (filter bars, toolbar
-inputs), wrong for drawer detail panels where each field needs a
-visible stacked label.
-
-`<field-ui label="…">` is the **stacked label wrapper**: composes a
-`<label for="…">` above the control (auto-minting an `id` on the
-slotted control when missing, so clicking the label focuses the
-control — better accessibility than bare `input-ui label=…`).
-
-**`<select-ui>`'s `label=` IS already stacked** (renders above the
-trigger per `select.yaml`), but the canonical
-`packages/web-components/patterns/form-drawer/form-drawer.examples.html`
-still wraps `<select-ui>` in `<field-ui>` for visual + accessibility
-consistency with input/textarea siblings — the `<label for=…>` binding
-that field-ui provides is a strict accessibility upgrade. Use
-`<field-ui>` uniformly for all three (`input-ui`, `select-ui`,
-`textarea-ui`); don't mix bare `label=…` on some and `<field-ui>`
-wrap on others.
-
-**Authoritative exemplar**: `packages/web-components/patterns/form-drawer/form-drawer.examples.html`
-in the substrate — uses `<field-ui>` 17 times across "simple create
-form" + "edit form with destructive action" + multi-step variants.
-That's the canonical reference if you need more permutations.
-
-### ⚠️ Do NOT substitute `<stat-ui>` for `<input-ui readonly>` on string fields
-
-When the user complains "too many inputs" about a drawer's read-only
-display fields, the wrong fix is to replace `<input-ui readonly>` with
-`<stat-ui label="…" value="…">`. `<stat-ui>` is a **KPI display
-primitive** — value + label rendered as a stacked block with prominent
-value in title-weight CSS (per `stat.yaml`). This is correct for
-numeric metrics like "766 claims" or "$48,200 revenue" displayed in
-dashboard cards (the §Row-Click recipe above uses `<stat-ui>` for
-"Amount" + "Date" cards, which IS a legitimate KPI use). It is
-**visually catastrophic for string values** (names, IDs, statuses,
-diagnosis codes) at prose scale inside a drawer panel — the name
-renders as headline-weight text and the drawer reads as a KPI dashboard
-tile instead of a detail panel.
-
-**The right alternatives**:
-
-| Use case | Right primitive |
-|----------|-----------------|
-| Numeric metric in a dashboard card / drawer summary tile | `<stat-ui label value>` (KPI weight) |
-| Editable form field with stacked label | `<field-ui label><input-ui></input-ui></field-ui>` |
-| Read-only mirror of a form field (intentional "looks like an input, isn't editable") | `<field-ui label><input-ui readonly></input-ui></field-ui>` or bare `<input-ui readonly label>` |
-| Lightweight key-value pair (label / value at prose scale, no input chrome) | `<col-ui gap="0"><text-ui size="sm" color="subtle">Label</text-ui><text-ui>Value</text-ui></col-ui>` |
-| Definition list (multiple compact key-value pairs) | `<dl>` + `<dt>` / `<dd>` (native HTML) OR a `<grid-ui columns="2">` with `<text-ui>` pairs |
-
-The "too many inputs" complaint usually means the visual density is too
-high (form-chrome on every read-only field). The fix is **either** (a)
-accept the form-chrome as intentional design-system style (the panel is
-an editor surface; readonly inputs read as "you could edit this but
-the row is locked"), **or** (b) drop to the lightweight `<col-ui>` +
-`<text-ui>` pair shown in the table above for fields that genuinely
-don't belong in form chrome. Do NOT reach for `<stat-ui>` — the
-title-weight is wrong at prose scale.
-
-## Shared Detail Drawer — Per-Row Hydration (no table)
-
-When a list of cards (not a table) needs a "drill-down" drawer, mount ONE
-drawer and re-populate it from each row's click. Use a CustomEvent for the
-hydrate step so the drawer doesn't need to know which row triggered it.
-
-```html
-<!-- Row cards — each carries its own payload in the onclick -->
-<card-ui>
-  <header>
-    <span slot="icon"><avatar-ui icon="envelope"></avatar-ui></span>
-    <span slot="heading">
-      <text-ui strong>james@acme.com</text-ui>
-      <badge-ui text="Member" variant="info"></badge-ui>
-    </span>
-    <span slot="action">
-      <button-ui
-        text="Manage"
-        variant="outline"
-        size="sm"
-        onclick="
-          const d = document.getElementById('drawer-invite');
-          d.dataset.email = 'james@acme.com';
-          d.dataset.role = 'Member';
-          d.dataset.invitedBy = 'Alex Chen';
-          d.dispatchEvent(new CustomEvent('hydrate'));
-          d.open = true;
-        "
-      ></button-ui>
-    </span>
-  </header>
-</card-ui>
-
-<!-- Shared drawer — same layout for every row -->
-<drawer-ui id="drawer-invite" side="right" size="md">
-  <header>
-    <span slot="icon"><avatar-ui icon="envelope"></avatar-ui></span>
-    <span slot="heading">
-      <text-ui strong data-invite-email>Invite</text-ui>
-      <badge-ui data-invite-role text="Member" variant="info"></badge-ui>
-    </span>
-    <span slot="action"></span>
-  </header>
-  <section>
-    <col-ui gap="3">
-      <input-ui label="Email" data-invite-email readonly></input-ui>
-      <select-ui label="Role" data-invite-role value="Member">…</select-ui>
-      <input-ui label="Invited by" data-invite-inviter readonly></input-ui>
-    </col-ui>
-  </section>
-  <footer slot="footer">
-    <grid-ui>
-      <button-ui text="Revoke" variant="danger"></button-ui>
-      <button-ui text="Cancel" variant="ghost"></button-ui>
-      <button-ui text="Resend" variant="primary"></button-ui>
-    </grid-ui>
-  </footer>
-</drawer-ui>
-```
-
-```javascript
-// setup.js — wire the hydrate handler once.
-const drawer = router.querySelector('#drawer-invite');
-
-// querySelectorAll (not querySelector) because the same data-* hook may
-// appear on BOTH a [data-…] text-ui heading AND a [data-…] input-ui field.
-// Missing the second occurrence is the most common fill-helper bug.
-const fill = (attr, val) => {
-  for (const el of drawer.querySelectorAll(`[${attr}]`)) {
-    const tag = el.localName;
-    if (tag === 'input-ui' || tag === 'textarea-ui') {
-      // input-ui/textarea-ui sync [slot="text"] + data-empty from `value` (0.6.44+);
-      // mirroring textContent defeats update()'s change check and leaves data-empty
-      // stale → placeholder over the value (FB-87).
-      el.value = val;
-    } else if (tag === 'stat-ui' || tag === 'select-ui') {
-      el.setAttribute('value', val);
-    } else if (tag === 'badge-ui') {
-      el.setAttribute('text', val);
-    } else {
-      el.textContent = val;
-    }
-  }
-};
-
-drawer.addEventListener('hydrate', () => {
-  const { email, role, invitedBy } = drawer.dataset;
-  fill('data-invite-email',   email);
-  fill('data-invite-role',    role);
-  fill('data-invite-inviter', invitedBy);
-});
-```
-
-**When to pick this over the `cell-click` variant:**
-- Row data lives in HTML (static list) — no table columns / data binding.
-- You want each button to carry explicit payload rather than derive it
-  from a shared row object.
-- The same drawer is reused across multiple discrete list surfaces on the
-  page (e.g. pending invites + revoked invites both reusing `#drawer-invite`).
-
-For tables where a row object already exists, prefer the `cell-click` +
-`e.detail.row` pattern from "Row-Click → Detail Drawer".
-
-## State-Coverage Menu (Default / Loading / Empty / Error)
-
-To demonstrate all async states on one card, add a `menu-ui` "View as"
-trigger in the card's action slot. `action` event drives an `applyState()`
-that swaps the card's section children.
-
-```html
-<card-ui>
-  <header>
-    <h3>Recent Transactions</h3>
-    <text-ui slot="description" color="subtle">Manage and track recent orders</text-ui>
-    <span slot="action">
-      <menu-ui id="tx-state-menu">
-        <button-ui slot="trigger" text="View as" icon="caret-down" variant="ghost" size="sm"></button-ui>
-        <menu-item-ui text="Default" value="default"></menu-item-ui>
-        <menu-item-ui text="Loading" value="loading" icon="spinner"></menu-item-ui>
-        <menu-item-ui text="Empty"   value="empty"   icon="tray"></menu-item-ui>
-        <menu-item-ui text="Error"   value="error"   icon="warning"></menu-item-ui>
-      </menu-ui>
-    </span>
-  </header>
-  <section bleed data-tx-surface>
-    <table-ui id="dash-transactions" sortable striped raw paginate="5"></table-ui>
-  </section>
-</card-ui>
-```
-
-```javascript
-const table = router.querySelector('#dash-transactions');
-const surface = router.querySelector('[data-tx-surface]');
-const menu = router.querySelector('#tx-state-menu');
-
-const applyState = (state) => {
-  // Reset — re-mount the table, clear any overlays, drop loading.
-  if (!surface.contains(table)) surface.replaceChildren(table);
-  for (const o of surface.querySelectorAll('[data-tx-overlay]')) o.remove();
-  table.removeAttribute('loading');
-
-  if (state === 'loading') {
-    table.setAttribute('loading', '');
-  } else if (state === 'empty') {
-    table.data = [];
-    const empty = document.createElement('empty-state-ui');
-    empty.setAttribute('icon', 'receipt');
-    empty.setAttribute('heading', 'No transactions yet');
-    empty.setAttribute('description', 'Transactions appear here once customers check out.');
-    empty.setAttribute('data-tx-overlay', '');
-    empty.innerHTML = '<button-ui slot="action" text="Set up payments" variant="primary"></button-ui>';
-    surface.replaceChildren(empty);
-  } else if (state === 'error') {
-    const alert = document.createElement('alert-ui');
-    alert.setAttribute('variant', 'danger');
-    alert.setAttribute('icon', 'warning');
-    alert.setAttribute('heading', 'Could not load transactions');
-    alert.setAttribute('text', 'The payments API returned a 502.');
-    alert.setAttribute('data-tx-overlay', '');
-    alert.innerHTML = '<row-ui slot="action" gap="2"><button-ui text="Retry" variant="primary" size="sm"></button-ui></row-ui>';
-    surface.replaceChildren(alert);
-  } else {
-    table.data = populatedData;
-  }
-};
-applyState('default');
-menu?.addEventListener('action', (e) => applyState(e.detail.value));
-```
-
-Pattern notes:
-- `empty-state-ui` carries its own icon/heading/description API; the action
-  slot is author-owned (a primary CTA).
-- `alert-ui variant="danger"` with `slot="action"` holds retry + status
-  buttons for the error state.
-- `loading` is a built-in attribute on `table-ui`; no overlay needed.
-
-## Interactive Filter Bar
-
-Filter chips above a data view. Handle add/remove/clear; let consumers
-listen for `filter-change` to persist to URL or query.
-
-```html
-<row-ui gap="2" align="center" wrap data-filter-bar>
-  <text-ui color="subtle" weight="semibold">Filters:</text-ui>
-  <tag-ui text="Country: United States" removable></tag-ui>
-  <tag-ui text="Device: Desktop" removable></tag-ui>
-  <button-ui data-filter-add   text="+ Add filter" variant="ghost" size="sm"></button-ui>
-  <span data-spacer></span>
-  <button-ui data-filter-clear text="Clear all"    variant="ghost" size="sm"></button-ui>
-</row-ui>
-```
-
-```javascript
-const filterRow = router.querySelector('[data-filter-bar]');
-const addBtn    = filterRow.querySelector('[data-filter-add]');
-const clearBtn  = filterRow.querySelector('[data-filter-clear]');
-const presets   = ['Country: Germany', 'Device: Mobile', 'Source: Organic', /* … */];
-let idx = 0;
-
-const addFilter = (text) => {
-  const tag = document.createElement('tag-ui');
-  tag.setAttribute('text', text);
-  tag.setAttribute('removable', '');
-  filterRow.insertBefore(tag, addBtn);
-  tag.addEventListener('remove', (e) => {
-    router.dispatchEvent(new CustomEvent('filter-change', { detail: { removed: e.detail.text } }));
-  });
-};
-
-addBtn.addEventListener('press', () => addFilter(presets[idx++ % presets.length]));
-clearBtn.addEventListener('press', () => {
-  for (const t of filterRow.querySelectorAll('tag-ui[removable]')) t.remove();
-});
-
-// Make authored chips participate in the same event channel.
-for (const t of filterRow.querySelectorAll('tag-ui[removable]')) {
-  t.addEventListener('remove', (e) => {
-    router.dispatchEvent(new CustomEvent('filter-change', { detail: { removed: e.detail.text } }));
-  });
-}
-```
-
-Key: `tag-ui[removable]` dispatches a `remove` CustomEvent and then removes
-itself, so the listener is a signal-only hook. `button-ui` uses a `press`
-event (not `click`) — fires on both click and keyboard activation.
-
-## Conversion Funnel (composition recipe)
-
-A funnel without a `funnel-ui` component. Top step is a plain row showing
-100% as the anchor; remaining steps are `progress-row-ui`.
-
-```html
-<card-ui>
-  <header>
-    <h3>Conversion funnel</h3>
-    <text-ui slot="description" color="subtle">Visit → Sign up → Activate → Convert</text-ui>
-  </header>
-  <section>
-    <col-ui gap="3">
-      <row-ui align="center" gap="3">
-        <col-ui gap="0" grow>
-          <text-ui strong>Visited landing page</text-ui>
-          <text-ui color="subtle">28,432 visitors</text-ui>
-        </col-ui>
-        <text-ui strong>100%</text-ui>
-      </row-ui>
-      <progress-row-ui label="Signed up"         value="42" meta="11,942 · 42%"></progress-row-ui>
-      <progress-row-ui label="Activated"         value="28" meta="7,961 · 28%"></progress-row-ui>
-      <progress-row-ui label="Converted to paid" value="8"  meta="2,274 · 8.0%"></progress-row-ui>
-    </col-ui>
-  </section>
-</card-ui>
-```
-
-Meta format: `"{count} · {percent}"`. Count first reads as data, percent
-second reads as insight. Step-over-step delta is an optional badge in a
-sibling column: `warning` for 20–40% drop, `danger` above 40%.
-
-## Retention Cohort (composition recipe)
-
-A retention "heatmap" as a regular `table-ui` with a badge-cell renderer.
-Each percentage wraps in a `badge-ui` variant keyed to three buckets.
-
-```javascript
-const formatPct = (v) => {
-  if (v == null) return '';          // partial cohort → blank, never zero
-  const n = Math.round(v);
-  const variant = n >= 60 ? 'success' : n >= 30 ? 'warning' : 'muted';
-  return `<badge-ui text="${n}%" variant="${variant}"></badge-ui>`;
-};
-
-const columns = [
-  { key: 'week',  label: 'Signup week' },
-  { key: 'size',  label: 'Users' },
-  { key: 'w1',    label: 'W1',  render: formatPct },
-  { key: 'w2',    label: 'W2',  render: formatPct },
-  { key: 'w4',    label: 'W4',  render: formatPct },
-  { key: 'w8',    label: 'W8',  render: formatPct },
-  { key: 'w12',   label: 'W12', render: formatPct },
-];
-```
-
-Bucket thresholds: 60/30 for SaaS; 40/20 for transactional products.
-Canonical column set: `Signup week · Users · W1 · W2 · W3 · W4 · W8 · W12`.
-
-## Radio Cards (rich radio-group)
-
-For "choose a plan"-style selection with rich labels + descriptions, wrap
-each option in `card-ui` with a `<radio-ui slot="icon">`, then wrap the whole
-list in `role="radiogroup"` so `radio-ui`'s sibling lookup works across
-containers.
-
-```html
-<div role="radiogroup" aria-label="Plan" data-plan-picker
-     onclick="const r = event.target.closest('card-ui')?.querySelector('radio-ui'); r && r.click()">
-  <list-ui divider>
-    <list-item-ui>
-      <card-ui>
-        <header>
-          <radio-ui slot="icon" name="plan" value="pro" checked></radio-ui>
-          <span slot="heading">
-            <text-ui strong>Pro · $49/mo</text-ui>
-            <badge-ui text="Current" variant="accent"></badge-ui>
-          </span>
-          <span slot="description">
-            <text-ui color="subtle" size="sm">Unlimited conversations, advanced charts, 100 GB storage</text-ui>
-          </span>
-        </header>
-      </card-ui>
-    </list-item-ui>
-    <!-- additional options -->
-  </list-ui>
-</div>
-```
-
-The inline delegate forwards any card-click to the card's inner radio;
-radio-ui's own click handler no-ops on an already-checked radio, so
-click-through is safe.
-
-## Alerts & Badges
-
-```html
-<alert-ui variant="success" icon="check-circle" text="Changes saved"></alert-ui>
-<alert-ui variant="danger" icon="warning" text="Failed to load"></alert-ui>
-<alert-ui variant="warning" icon="info" text="Trial expires in 3 days"></alert-ui>
-
-<badge-ui text="Active" variant="success"></badge-ui>
-<badge-ui text="Pending" variant="warning"></badge-ui>
-<badge-ui text="Failed" variant="danger"></badge-ui>
-<badge-ui status="New"></badge-ui>  <!-- auto-maps to info variant -->
-<badge-ui variant="info" size="xs"></badge-ui>
-```