@adia-ai/web-components 0.8.6 → 0.8.7

package/patterns/conversion-funnel/conversion-funnel.examples.html

@@ -0,0 +1,158 @@
+<header>
+  <div>
+    <h1>Conversion Funnel</h1>
+    <div data-actions>
+      <tag-ui size="sm">card-ui</tag-ui> <tag-ui size="sm">progress-row-ui</tag-ui> <tag-ui size="sm">row-ui</tag-ui> <tag-ui size="sm">col-ui</tag-ui>
+    </div>
+  </div>
+  <p>Composition pattern: render a multi-step drop-off funnel without a dedicated funnel component. Uses <code>progress-row-ui</code> for each step so the bar, label, and meta text stay aligned to the card-ui content rhythm.</p>
+</header>
+
+<section data-section data-property="when-to-use">
+  <h2 variant="section">When to use</h2>
+  <p data-note>
+    Funnel charts ship with a lot of visual baggage (trapezoidal segments, angled
+    labels) that don't compose well inside a card. A stack of labeled progress rows
+    reads clearer, hits the same "big → small" shape, and stays accessible:
+    every step is a real DOM element with a percentage. Use this whenever a user
+    needs to see sequential drop-off — onboarding, checkout, activation, paywall.
+  </p>
+</section>
+
+<section data-section data-property="4-step-funnel">
+  <h2 variant="section">Four-step funnel</h2>
+  <p data-note>Top step is an explicit 100% baseline (no progress bar — it's the anchor). Subsequent steps use <code>progress-row-ui</code> with the count + percentage in the meta slot.</p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label="conversion funnel">
+      <card-ui data-chunk="conversion-funnel-4-step-funnel" style="max-width: 560px;">
+        <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>
+    </div>
+  </div>
+</section>
+
+<section data-section data-property="with-segment-compare">
+  <h2 variant="section">With segment comparison</h2>
+  <p data-note>Pair the funnel card with a segmented control in <code>slot="action"</code> so users can switch between cohorts (e.g. new-vs-returning, mobile-vs-desktop). Swap the <code>value</code> + <code>meta</code> attributes in setup.js on segment change.</p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label="funnel with cohort toggle">
+      <card-ui data-chunk="conversion-funnel-with-segment-compare" style="max-width: 560px;">
+        <header>
+          <h3>Checkout funnel</h3>
+          <text-ui slot="description" color="subtle">Last 30 days · by first-time vs returning</text-ui>
+          <span slot="action">
+            <segmented-ui value="new" size="sm">
+              <segment-ui value="new" text="New"></segment-ui>
+              <segment-ui value="returning" text="Returning"></segment-ui>
+            </segmented-ui>
+          </span>
+        </header>
+        <section>
+          <col-ui gap="3">
+            <row-ui align="center" gap="3">
+              <col-ui gap="0" grow>
+                <text-ui strong>Cart viewed</text-ui>
+                <text-ui color="subtle">42,180 sessions</text-ui>
+              </col-ui>
+              <text-ui strong>100%</text-ui>
+            </row-ui>
+            <progress-row-ui label="Added to cart" value="58" meta="24,464 · 58%"></progress-row-ui>
+            <progress-row-ui label="Reached payment" value="34" meta="14,341 · 34%"></progress-row-ui>
+            <progress-row-ui label="Completed purchase" value="19" meta="8,014 · 19%"></progress-row-ui>
+          </col-ui>
+        </section>
+        <footer divider>
+          <small slot="description">Funnel window: 30 days · ends at first purchase or abandonment.</small>
+          <span slot="action">
+            <button-ui text="View in analytics" variant="ghost" size="sm" icon="arrow-square-out"></button-ui>
+          </span>
+        </footer>
+      </card-ui>
+    </div>
+  </div>
+</section>
+
+<section data-section data-property="wide-summary">
+  <h2 variant="section">Wide summary with step-over-step delta</h2>
+  <p data-note>For board reporting, combine the funnel with a step-over-step delta column so stakeholders can see exactly where the biggest drop-off happens. Delta is a <code>badge-ui</code> colored by severity.</p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label="funnel with step-over-step">
+      <card-ui data-chunk="conversion-funnel-wide-summary" style="max-width: 640px;">
+        <header>
+          <h3>Signup funnel</h3>
+          <text-ui slot="description" color="subtle">Step-over-step conversion, last 7 days</text-ui>
+        </header>
+        <section>
+          <col-ui gap="3">
+            <row-ui align="center" gap="3">
+              <col-ui gap="0" grow>
+                <text-ui strong>Signup form viewed</text-ui>
+                <text-ui color="subtle">8,420 visitors</text-ui>
+              </col-ui>
+              <text-ui strong>100%</text-ui>
+            </row-ui>
+            <row-ui align="center" gap="3">
+              <progress-row-ui label="Email verified" value="68" meta="5,726 · 68%" grow></progress-row-ui>
+              <badge-ui text="−32%" variant="warning"></badge-ui>
+            </row-ui>
+            <row-ui align="center" gap="3">
+              <progress-row-ui label="Workspace created" value="54" meta="4,547 · 54%" grow></progress-row-ui>
+              <badge-ui text="−21%" variant="muted"></badge-ui>
+            </row-ui>
+            <row-ui align="center" gap="3">
+              <progress-row-ui label="Invited a teammate" value="22" meta="1,852 · 22%" grow></progress-row-ui>
+              <badge-ui text="−59%" variant="danger"></badge-ui>
+            </row-ui>
+          </col-ui>
+        </section>
+      </card-ui>
+    </div>
+  </div>
+</section>
+
+<section data-section data-property="variants-and-knobs">
+  <h2 variant="section">Variants &amp; knobs</h2>
+  <ul data-note>
+    <li><strong>Step count.</strong> Keep to 3–6 steps. Beyond 6 the drop-off numbers lose impact; split into nested funnels.</li>
+    <li><strong>Top-row value.</strong> Always show the absolute count next to a 100% label — it anchors every subsequent percentage.</li>
+    <li><strong>Meta format.</strong> <code>meta="count · percent"</code> is the canonical order. Count first reads as data, percent second reads as insight.</li>
+    <li><strong>Color coding.</strong> Don't tint the progress bars by drop-off severity — it implies "bad" for inherently-lossy funnels. Use a neutral progress color and let the numbers speak.</li>
+    <li><strong>Delta column (optional).</strong> When step-over-step matters more than overall conversion, add a <code>badge-ui</code> in a sibling column: <code>warning</code> for 20–40% drop, <code>danger</code> above 40%.</li>
+  </ul>
+</section>
+
+<section data-section data-property="anti-patterns">
+  <h2 variant="section">Anti-patterns</h2>
+  <ul data-note>
+    <li><strong>Don't use a trapezoidal funnel SVG.</strong> The angled geometry burns horizontal space, makes labels hard to align, and provides no precision benefit over a stacked progress pattern.</li>
+    <li><strong>Don't fill the bar for step 1.</strong> 100% is the anchor, not data. Render it as a plain row so step 2 becomes the first visible drop.</li>
+    <li><strong>Don't encode drop-off in bar color alone.</strong> CVD users can't distinguish severities by hue — always pair with a numeric badge or explicit text.</li>
+  </ul>
+</section>
+
+<section data-section data-property="rules">
+  <h2 variant="section">Authoring rules</h2>
+  <ul>
+    <li><strong>Steps must be ordered by drop-off severity</strong> — widest bar at top (entry), narrowest at bottom (conversion). Do not reorder steps for aesthetic reasons.</li>
+    <li><strong>Label every step with the action, not the state.</strong> "Started checkout" not "Checkout". The label describes what the user did to enter this stage.</li>
+    <li><strong>Always show the percentage alongside the absolute count</strong> — absolute numbers without percentages hide relative drop-off; percentages without absolutes hide scale.</li>
+    <li><strong>Use <code>chart-in-card</code> pattern for standalone KPI surfaces</strong>, not <code>conversion-funnel</code>. Funnels require at least 3 sequential stages and a meaningful conversion event.</li>
+  </ul>
+</section>

package/patterns/conversion-funnel/conversion-funnel.examples.js

@@ -0,0 +1,4 @@
+/** Conversion Funnel pattern — no dynamic wiring; static demo content. */
+export default function setup(_router) {
+  // Pattern is pure HTML. Kept a setup hook for parity with other patterns.
+}

package/patterns/conversion-funnel/conversion-funnel.html

@@ -0,0 +1,64 @@
+<!DOCTYPE html>
+<html lang="en" theme="auto">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Conversion Funnel (pattern) — AdiaUI</title>
+
+  <!-- Token base -->
+  <link rel="stylesheet" href="../../styles/resets.css">
+  <link rel="stylesheet" href="../../styles/tokens.css">
+
+  <!-- Component CSS — primitives this pattern composes -->
+  <link rel="stylesheet" href="../../components/badge/badge.css">
+  <link rel="stylesheet" href="../../components/button/button.css">
+  <link rel="stylesheet" href="../../components/card/card.css">
+  <link rel="stylesheet" href="../../components/col/col.css">
+  <link rel="stylesheet" href="../../components/progress-row/progress-row.css">
+  <link rel="stylesheet" href="../../components/row/row.css">
+  <link rel="stylesheet" href="../../components/segment/segment.css">
+  <link rel="stylesheet" href="../../components/segmented/segmented.css">
+  <link rel="stylesheet" href="../../components/tag/tag.css">
+  <link rel="stylesheet" href="../../components/text/text.css">
+
+  <!-- Component JS -->
+  <script type="module" src="../../components/badge/badge.js"></script>
+  <script type="module" src="../../components/button/button.js"></script>
+  <script type="module" src="../../components/card/card.js"></script>
+  <script type="module" src="../../components/col/col.js"></script>
+  <script type="module" src="../../components/progress-row/progress-row.js"></script>
+  <script type="module" src="../../components/row/row.js"></script>
+  <script type="module" src="../../components/segment/segment.js"></script>
+  <script type="module" src="../../components/segmented/segmented.js"></script>
+  <script type="module" src="../../components/tag/tag.js"></script>
+  <script type="module" src="../../components/text/text.js"></script>
+
+  <style>
+    :where(html, body) { margin: 0; min-height: 100vh; background: var(--md-sys-color-neutral-background); color: var(--md-sys-color-neutral-on-surface); font-family: var(--a-font-family); }
+    main { max-width: 960px; margin-inline: auto; padding: var(--a-space-6) var(--a-space-5); }
+  </style>
+</head>
+<body>
+
+  <main id="demo-root">
+    <p>Loading examples…</p>
+  </main>
+
+  <script type="module">
+    const root = document.getElementById('demo-root');
+    try {
+      const res = await fetch('./conversion-funnel.examples.html');
+      if (!res.ok) throw new Error(`fetch failed (${res.status})`);
+      root.innerHTML = await res.text();
+      try {
+        const mod = await import(/* @vite-ignore */ './conversion-funnel.examples.js');
+        mod.default?.(root);
+      } catch (e) { console.error('[conversion-funnel.html] setup failed:', e); }
+    } catch (err) {
+      root.innerHTML = `<p style="color:var(--a-danger-strong);">Failed to load conversion-funnel.examples.html — ${err.message}</p>`;
+      console.error('[conversion-funnel.html]', err);
+    }
+  </script>
+
+</body>
+</html>

package/patterns/data-tables-inline-edit-and-tree/data-tables-inline-edit-and-tree.examples.html

@@ -0,0 +1,196 @@
+<header>
+  <div>
+    <h1>Inline-edit grids &amp; tree tables</h1>
+    <div data-actions>
+      <tag-ui size="sm">table-ui</tag-ui> <tag-ui size="sm">tree-ui</tag-ui> <tag-ui size="sm">input-ui</tag-ui> <tag-ui size="sm">field-ui</tag-ui> <tag-ui size="sm">tag-ui</tag-ui>
+    </div>
+  </div>
+  <p>Two adjacent advanced data-table patterns: spreadsheet-style cells the user can edit inline (06i) and hierarchical rows with expand/collapse (06j). Both compose existing primitives — `&lt;table-ui&gt;` for the grid, `&lt;tree-ui&gt;` for the hierarchy.</p>
+</header>
+
+<section data-section data-property="when-to-use">
+  <h2 variant="section">When to use</h2>
+  <p data-note>
+    Inline-edit grids: when the user spends most of their time
+    correcting/refining row data — pricing matrices, inventory
+    counts, bulk metadata editing. Distinct from a detail drawer
+    (12b) which is for one-row-at-a-time depth. Tree tables: when
+    rows are recursively nested and the hierarchy is the data —
+    org charts, file trees, accounting categories. Distinct from
+    a flat table with a parent-id column.
+  </p>
+</section>
+
+<section data-section data-property="inline-edit-row">
+  <h2 variant="section">Inline-edit — single editing row</h2>
+  <p data-note>The most common shape: a normal table where one row at a time enters edit mode (double-click or pencil button). Cells become `&lt;input-ui&gt;` / `&lt;select-ui&gt;` / etc.; Save / Cancel actions appear in the row's trailing column.</p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label="single editing row">
+      <card-ui data-chunk="table-inline-edit-row">
+        <header>
+          <span slot="heading" variant="section">Pricing matrix</span>
+          <text-ui slot="description" color="subtle">12 rows · 1 unsaved</text-ui>
+          <button-ui slot="action" text="Add row" variant="ghost" size="sm" icon-leading="plus"></button-ui>
+        </header>
+        <section bleed>
+          <!-- A real <table> in <table-ui raw> (consumer-owns-body mode) gives
+               true column alignment; the editing row (Pro) swaps its Price/Limits
+               cells for <input-ui> and its action cell for Save/Cancel. -->
+          <table-ui raw>
+            <table>
+              <thead>
+                <tr><th>Plan</th><th>Price</th><th>Limits</th><th></th></tr>
+              </thead>
+              <tbody>
+                <tr>
+                  <td><text-ui strong>Starter</text-ui></td>
+                  <td><text-ui color="subtle">$0 / month</text-ui></td>
+                  <td><text-ui color="subtle">5 seats · 1k requests</text-ui></td>
+                  <td><button-ui icon="pencil-simple" variant="ghost" size="sm" aria-label="Edit"></button-ui></td>
+                </tr>
+                <tr style="background: var(--a-bg-subtle);">
+                  <td><text-ui strong>Pro</text-ui></td>
+                  <td><input-ui name="pro_price" value="$29" size="sm"></input-ui></td>
+                  <td><input-ui name="pro_features" value="50 seats · 100k requests" size="sm"></input-ui></td>
+                  <td>
+                    <row-ui gap="2" align="center">
+                      <button-ui text="Save" variant="primary" size="sm"></button-ui>
+                      <button-ui text="Cancel" variant="ghost" size="sm"></button-ui>
+                    </row-ui>
+                  </td>
+                </tr>
+                <tr>
+                  <td><text-ui strong>Enterprise</text-ui></td>
+                  <td><text-ui color="subtle">Custom</text-ui></td>
+                  <td><text-ui color="subtle">Unlimited · SSO · SLA</text-ui></td>
+                  <td><button-ui icon="pencil-simple" variant="ghost" size="sm" aria-label="Edit"></button-ui></td>
+                </tr>
+              </tbody>
+            </table>
+          </table-ui>
+        </section>
+      </card-ui>
+    </div>
+  </div>
+</section>
+
+<section data-section data-property="spreadsheet-cells">
+  <h2 variant="section">Spreadsheet — every cell editable</h2>
+  <p data-note>The full Excel-style shape: every cell renders an `&lt;input-ui&gt;` (or typed equivalent — number, select, date). Tab moves to the next cell, Enter commits + moves down. Saves are auto-debounced; the dirty state surfaces as a per-row tag.</p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label="spreadsheet cells">
+      <card-ui data-chunk="table-spreadsheet-cells">
+        <header>
+          <span slot="heading" variant="section">Inventory — Q4 forecast</span>
+          <text-ui slot="description" color="subtle">Auto-saving · 3 cells dirty</text-ui>
+          <row-ui slot="action" gap="2">
+            <button-ui text="Undo" variant="ghost" size="sm" icon-leading="arrow-counter-clockwise"></button-ui>
+            <button-ui text="Save now" variant="primary" size="sm"></button-ui>
+          </row-ui>
+        </header>
+        <section bleed>
+          <!-- Every cell is an <input-ui>; a real <table> gives the Excel-style
+               column alignment the list-item flex layout couldn't. The per-row
+               dirty/clean state sits in its own Status column. -->
+          <table-ui raw>
+            <table>
+              <thead>
+                <tr><th>Item</th><th>Oct</th><th>Nov</th><th>Dec</th><th>Status</th></tr>
+              </thead>
+              <tbody>
+                <tr>
+                  <td><text-ui strong>Widget A</text-ui></td>
+                  <td><input-ui type="number" value="124" size="sm"></input-ui></td>
+                  <td><input-ui type="number" value="98" size="sm"></input-ui></td>
+                  <td><input-ui type="number" value="156" size="sm"></input-ui></td>
+                  <td><tag-ui size="sm" variant="muted">clean</tag-ui></td>
+                </tr>
+                <tr>
+                  <td><text-ui strong>Widget B</text-ui></td>
+                  <td><input-ui type="number" value="42" size="sm"></input-ui></td>
+                  <td><input-ui type="number" value="51" size="sm"></input-ui></td>
+                  <td><input-ui type="number" value="78" size="sm"></input-ui></td>
+                  <td><tag-ui size="sm" variant="warning">dirty</tag-ui></td>
+                </tr>
+                <tr>
+                  <td><text-ui strong>Widget C</text-ui></td>
+                  <td><input-ui type="number" value="0" size="sm"></input-ui></td>
+                  <td><input-ui type="number" value="0" size="sm"></input-ui></td>
+                  <td><input-ui type="number" value="320" size="sm"></input-ui></td>
+                  <td><tag-ui size="sm" variant="warning">dirty</tag-ui></td>
+                </tr>
+                <tr>
+                  <td><text-ui strong>Widget D</text-ui></td>
+                  <td><input-ui type="number" value="200" size="sm"></input-ui></td>
+                  <td><input-ui type="number" value="245" size="sm"></input-ui></td>
+                  <td><input-ui type="number" value="280" size="sm"></input-ui></td>
+                  <td><tag-ui size="sm" variant="muted">clean</tag-ui></td>
+                </tr>
+              </tbody>
+            </table>
+          </table-ui>
+        </section>
+      </card-ui>
+    </div>
+  </div>
+</section>
+
+<section data-section data-property="tree-table-basic">
+  <h2 variant="section">Tree table — hierarchical rows</h2>
+  <p data-note>Use <code>&lt;tree-ui&gt;</code> for the recursion. Each <code>&lt;tree-item-ui&gt;</code> renders the chevron + indent automatically; nested items go inside the parent's default slot. Common in budgets, org charts, file browsers.</p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label="tree table">
+      <card-ui data-chunk="tree-table-basic">
+        <header>
+          <span slot="heading" variant="section">Q4 budget — by department</span>
+          <text-ui slot="description" color="subtle">Total: $1.24M · 4 departments · 12 categories</text-ui>
+        </header>
+        <section bleed>
+          <tree-ui style="padding: var(--a-space-2);">
+            <tree-item-ui text="Engineering — $620k" icon="cpu">
+              <tree-item-ui text="Salaries — $480k"></tree-item-ui>
+              <tree-item-ui text="Tooling — $80k"></tree-item-ui>
+              <tree-item-ui text="Travel — $60k"></tree-item-ui>
+            </tree-item-ui>
+            <tree-item-ui text="Design — $180k" icon="palette">
+              <tree-item-ui text="Salaries — $140k"></tree-item-ui>
+              <tree-item-ui text="Software — $20k"></tree-item-ui>
+              <tree-item-ui text="Conferences — $20k"></tree-item-ui>
+            </tree-item-ui>
+            <tree-item-ui text="Sales &amp; marketing — $320k" icon="megaphone-simple">
+              <tree-item-ui text="Salaries — $200k"></tree-item-ui>
+              <tree-item-ui text="Ad spend — $80k"></tree-item-ui>
+              <tree-item-ui text="Events — $40k"></tree-item-ui>
+            </tree-item-ui>
+            <tree-item-ui text="Operations — $120k" icon="gear"></tree-item-ui>
+          </tree-ui>
+        </section>
+      </card-ui>
+    </div>
+  </div>
+</section>
+
+<section data-section data-property="composition">
+  <h2 variant="section">Composition rules</h2>
+  <ul>
+    <li><strong>One editing row at a time is the default</strong> — a single editable row preserves the table's scan-readability for unaffected rows. Reach for full spreadsheet only when the user's job <em>is</em> to edit most cells.</li>
+    <li><strong>Highlight the editing row</strong> — a subtle <code>--a-bg-subtle</code> background makes the active row obvious. Without it, users lose track of which row they're editing after scrolling.</li>
+    <li><strong>Save / Cancel are inline, not modal</strong> — the actions appear at the trailing edge of the row. Modal save dialogs break the table flow.</li>
+    <li><strong>Dirty state surfaces per row, not just per cell</strong> — a <code>tag-ui variant="warning">dirty</tag-ui></code> trailing tag tells the user which rows have unsaved changes. Per-cell highlighting is too noisy.</li>
+    <li><strong>Auto-save is the right default for spreadsheets</strong> — debounced 800ms after last keystroke. The "Save now" button is for users who want to force a flush before navigating away.</li>
+    <li><strong>Tree depth caps at 4</strong> — beyond that, indentation eats the column width and the structure stops reading. Use a search/filter (06g) or breadcrumbs to navigate deep trees.</li>
+    <li><strong>Tree rows render the same shape at every depth</strong> — an icon + text + optional metadata. Don't make the root row look different from leaves; the chevron + indent already encode hierarchy.</li>
+    <li><strong>Aggregates roll up</strong> — "Engineering — $620k" includes the children's $480 + $80 + $60. Show the total at the parent so users don't have to expand to verify.</li>
+  </ul>
+</section>
+
+<section data-section data-property="cross-references">
+  <h2 variant="section">See also</h2>
+  <ul>
+    <li><a href="/site/components/table">table-ui</a> — the canonical grid primitive (used for the spreadsheet body).</li>
+    <li><a href="/site/components/tree">tree-ui</a> · <a href="/site/components/tree-item">tree-item-ui</a> — hierarchy primitive.</li>
+    <li><a href="/site/components/input">input-ui</a> · <a href="/site/components/field">field-ui</a> — cell editor primitives.</li>
+    <li><a href="/site/patterns/filter-bar">filter-bar</a> — adjacent (filter the rows before drilling in).</li>
+    <li><a href="/site/patterns/bulk-action-toolbar">bulk-action-toolbar</a> — adjacent (apply edits to selected rows).</li>
+  </ul>
+</section>

package/patterns/data-tables-inline-edit-and-tree/data-tables-inline-edit-and-tree.html

@@ -0,0 +1,58 @@
+<!DOCTYPE html>
+<html lang="en" theme="auto">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Inline-edit grids &amp; tree tables (pattern) — AdiaUI</title>
+
+  <!-- Token base -->
+  <link rel="stylesheet" href="../../styles/resets.css">
+  <link rel="stylesheet" href="../../styles/tokens.css">
+
+  <!-- Component CSS — primitives this pattern composes -->
+  <link rel="stylesheet" href="../../components/button/button.css">
+  <link rel="stylesheet" href="../../components/card/card.css">
+  <link rel="stylesheet" href="../../components/field/field.css">
+  <link rel="stylesheet" href="../../components/input/input.css">
+  <link rel="stylesheet" href="../../components/list/list.css">
+  <link rel="stylesheet" href="../../components/row/row.css">
+  <link rel="stylesheet" href="../../components/tag/tag.css">
+  <link rel="stylesheet" href="../../components/text/text.css">
+  <link rel="stylesheet" href="../../components/tree/tree.css">
+
+  <!-- Component JS -->
+  <script type="module" src="../../components/button/button.js"></script>
+  <script type="module" src="../../components/card/card.js"></script>
+  <script type="module" src="../../components/field/field.js"></script>
+  <script type="module" src="../../components/input/input.js"></script>
+  <script type="module" src="../../components/list/list.js"></script>
+  <script type="module" src="../../components/row/row.js"></script>
+  <script type="module" src="../../components/tag/tag.js"></script>
+  <script type="module" src="../../components/text/text.js"></script>
+  <script type="module" src="../../components/tree/tree.js"></script>
+
+  <style>
+    :where(html, body) { margin: 0; min-height: 100vh; background: var(--md-sys-color-neutral-background); color: var(--md-sys-color-neutral-on-surface); font-family: var(--a-font-family); }
+    main { max-width: 960px; margin-inline: auto; padding: var(--a-space-6) var(--a-space-5); }
+  </style>
+</head>
+<body>
+
+  <main id="demo-root">
+    <p>Loading examples…</p>
+  </main>
+
+  <script type="module">
+    const root = document.getElementById('demo-root');
+    try {
+      const res = await fetch('./data-tables-inline-edit-and-tree.examples.html');
+      if (!res.ok) throw new Error(`fetch failed (${res.status})`);
+      root.innerHTML = await res.text();
+    } catch (err) {
+      root.innerHTML = `<p style="color:var(--a-danger-strong);">Failed to load data-tables-inline-edit-and-tree.examples.html — ${err.message}</p>`;
+      console.error('[data-tables-inline-edit-and-tree.html]', err);
+    }
+  </script>
+
+</body>
+</html>

package/patterns/diff-review/diff-review.examples.html

@@ -0,0 +1,147 @@
+<header>
+  <div>
+    <h1>Diff &amp; Review</h1>
+    <div data-actions>
+      <tag-ui size="sm">code-ui</tag-ui> <tag-ui size="sm">card-ui</tag-ui> <tag-ui size="sm">text-ui</tag-ui> <tag-ui size="sm">tag-ui</tag-ui>
+    </div>
+  </div>
+  <p>The before/after viewer that surfaces every change. Three shapes: code diff (side-by-side or inline), prose diff (rendered text with markup), and structured diff (field-level deltas on a record).</p>
+</header>
+
+<section data-section data-property="when-to-use">
+  <h2 variant="section">When to use</h2>
+  <p data-note>
+    Anywhere the user needs to see what changed before approving,
+    merging, or rolling back. Code review surfaces, content
+    publishing flows, settings change-history, audit detail views.
+    The right shape depends on the data: line-oriented text →
+    code diff; paragraph-flow prose → prose diff; tabular fields →
+    structured diff.
+  </p>
+</section>
+
+<section data-section data-property="side-by-side">
+  <h2 variant="section">Code diff — side by side</h2>
+  <p data-note>Two-column view with the old version on the left and the new on the right. Removed lines tinted danger; added lines tinted success. Compose two <code>code-ui line-numbers</code> blocks side-by-side; per-line tint comes from a <code>data-line-states</code> CSV (one entry per line: <code>unchanged</code>, <code>added</code>, or <code>removed</code>).</p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label="side-by-side diff">
+      <card-ui data-chunk="diff-side-by-side">
+        <header>
+          <span slot="heading" variant="section">tokens.css</span>
+          <text-ui slot="description" color="subtle">+3 −2 · 5 lines changed</text-ui>
+          <row-ui slot="action" gap="2">
+            <button-ui text="Inline" variant="ghost" size="sm"></button-ui>
+            <button-ui text="Side-by-side" variant="primary" size="sm"></button-ui>
+          </row-ui>
+        </header>
+        <section bleed>
+          <grid-ui columns="2" gap="0" style="grid-template-columns: minmax(0, 1fr) minmax(0, 1fr); border-block-start: 1px solid var(--md-sys-color-neutral-outline-variant);">
+            <code-ui language="css" line-numbers bare data-line-states="unchanged,removed,unchanged,removed,unchanged" style="min-width: 0; border-inline-end: 1px solid var(--md-sys-color-neutral-outline-variant);">
+:root {
+  --a-primary-bg: oklch(64% 0.15 245);
+  --a-primary-fg: oklch(98% 0.01 245);
+  --a-primary-border: oklch(60% 0.12 245);
+}
+            </code-ui>
+            <code-ui language="css" line-numbers bare data-line-states="unchanged,added,unchanged,added,added,unchanged" style="min-width: 0;">
+:root {
+  --a-primary-bg: oklch(64% 0.18 245);
+  --a-primary-fg: oklch(98% 0.01 245);
+  --a-primary-border: oklch(60% 0.15 245);
+  --a-primary-hover: oklch(58% 0.18 245);
+}
+            </code-ui>
+          </grid-ui>
+        </section>
+      </card-ui>
+    </div>
+  </div>
+</section>
+
+<section data-section data-property="inline">
+  <h2 variant="section">Code diff — inline (unified)</h2>
+  <p data-note>Single-column view with `+` and `−` line markers. Better for narrow columns and quick scan-reading. Compose <code>code-ui language="diff" line-numbers</code>; the `+`/`−`/space prefix on each line auto-resolves to <code>added</code> / <code>removed</code> / <code>unchanged</code> tint.</p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label="inline unified diff">
+      <card-ui data-chunk="diff-inline" style="max-width: 640px;">
+        <header>
+          <span slot="heading" variant="section">tokens.css — inline diff</span>
+          <text-ui slot="description" color="subtle">+3 −2</text-ui>
+        </header>
+        <section bleed>
+          <code-ui language="diff" line-numbers bare>
+ :root {
+-  --a-primary-bg: oklch(64% 0.15 245);
++  --a-primary-bg: oklch(64% 0.18 245);
+   --a-primary-fg: oklch(98% 0.01 245);
+-  --a-primary-border: oklch(60% 0.12 245);
++  --a-primary-border: oklch(60% 0.15 245);
++  --a-primary-hover: oklch(58% 0.18 245);
+ }
+          </code-ui>
+        </section>
+      </card-ui>
+    </div>
+  </div>
+</section>
+
+<section data-section data-property="structured">
+  <h2 variant="section">Structured diff — field-level</h2>
+  <p data-note>For settings or records where the underlying shape is a key-value object, not lines of text. Each row shows the field name + old → new value pair. <code>description-list-ui</code> for layout; <code>tag-ui</code> with diff variants for the value pair.</p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label="structured field diff">
+      <card-ui data-chunk="diff-structured" style="max-width: 640px;">
+        <header>
+          <span slot="heading" variant="section">Workspace settings — change preview</span>
+          <text-ui slot="description" color="subtle">3 fields changed</text-ui>
+        </header>
+        <section>
+          <description-list-ui>
+            <description-term-ui>Workspace name</description-term-ui>
+            <description-detail-ui>
+              <row-ui gap="2" align="center">
+                <tag-ui size="sm" variant="danger" icon-leading="minus">Adia</tag-ui>
+                <tag-ui size="sm" variant="success" icon-leading="plus">Adia AI</tag-ui>
+              </row-ui>
+            </description-detail-ui>
+            <description-term-ui>Default theme</description-term-ui>
+            <description-detail-ui>
+              <row-ui gap="2" align="center">
+                <tag-ui size="sm" variant="danger" icon-leading="minus">light</tag-ui>
+                <tag-ui size="sm" variant="success" icon-leading="plus">auto</tag-ui>
+              </row-ui>
+            </description-detail-ui>
+            <description-term-ui>Member invites</description-term-ui>
+            <description-detail-ui>
+              <row-ui gap="2" align="center">
+                <tag-ui size="sm" variant="danger" icon-leading="minus">Admin only</tag-ui>
+                <tag-ui size="sm" variant="success" icon-leading="plus">Anyone with link</tag-ui>
+              </row-ui>
+            </description-detail-ui>
+          </description-list-ui>
+        </section>
+      </card-ui>
+    </div>
+  </div>
+</section>
+
+<section data-section data-property="composition">
+  <h2 variant="section">Composition rules</h2>
+  <ul>
+    <li><strong>Color is the primary signal, not the only one</strong> — green/red tints carry the diff but icons and the `+`/`−` markers must work without color too. Color-blind users still need to read the diff.</li>
+    <li><strong>Side-by-side for review, inline for scan</strong> — side-by-side maps to "I'm comparing two versions", inline to "I'm reading the change". Offer both as a header toggle on review surfaces.</li>
+    <li><strong>Show context lines, not just the changes</strong> — a 5-line hunk with 3 changes is unreviewable without context; show ±3 unchanged lines around each change.</li>
+    <li><strong>Structured diff is for shaped data, not for code</strong> — if the field has a long string body, fall back to the line diff for that field. Don't tag-render multi-paragraph values.</li>
+    <li><strong>Counts in the header</strong> — "+3 −2" or "3 fields changed" lets the user calibrate before they start reading. Bare diffs feel arbitrarily long.</li>
+  </ul>
+</section>
+
+<section data-section data-property="cross-references">
+  <h2 variant="section">See also</h2>
+  <ul>
+    <li><a href="/site/components/code">code-ui</a> — line-number gutter + language hint primitive.</li>
+    <li><a href="/site/components/description-list">description-list-ui</a> — structured diff layout.</li>
+    <li><a href="/site/patterns/approvals">approvals</a> — host pattern (review surfaces use diff for the body).</li>
+    <li><a href="/site/components/richtext">richtext-ui</a> — for prose-diff (body of a Notion/Google-Docs-style edit).</li>
+  </ul>
+</section>