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

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

@@ -0,0 +1,1066 @@
+# 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>
+```