@adia-ai/web-components 0.8.44 → 0.8.46

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/web-components",
-  "version": "0.8.44",
+  "version": "0.8.46",
   "description": "AdiaUI web components \u2014 vanilla custom elements. A2UI runtime (renderer, registry, streams, wiring) lives in @adia-ai/a2ui.",
   "type": "module",
   "types": "./index.d.ts",

package/patterns/chart-in-card/chart-in-card.examples.html

@@ -185,13 +185,23 @@
 <section data-section data-property="full-bleed-with-legend">
   <h2 variant="section">Full-bleed chart + legend band</h2>
   <p data-note>
-    <code>bleed</code> only earns true edge-to-edge treatment for bare plotted
-    marks — a sparkline, or another chart type with both <code>no-grid</code>
-    and <code>no-values</code> set (gh#1095). A multi-series chart still
-    needs a legend, so keep <code>&lt;chart-legend-ui&gt;</code> OUT of the
-    bled section — wire it to the chart via <code>[for]</code> in a normal
-    (inset) section below instead. It reads as its own band beneath the
-    plot, and never collides with the card's rounded corners.
+    <code>bleed</code> is unconditionally author-controlled (gh#1801) — card.css
+    never restores the section's inset for you, so it's on the author to keep
+    any guide/value text or legend clear of the card's rounded corners. Bare
+    plotted marks (a sparkline, or another chart type with both
+    <code>no-grid</code> and <code>no-values</code> set) are naturally safe to
+    bleed since they draw no such text. A multi-series chart still needs a
+    legend, so keep <code>&lt;chart-legend-ui&gt;</code> OUT of the bled
+    section — wire it to the chart via <code>[for]</code> in a normal (inset)
+    section below instead. It reads as its own band beneath the plot, and
+    never collides with the card's rounded corners. As of the Charts 2.0
+    foundations (ADR-0081), <code>no-grid</code>/<code>no-values</code> bare-marks
+    isn't the only corner-safe option anymore — <code>labels="chip"</code>
+    (REQ-F-004/006) keeps real gridlines and axis chips inset within the plot
+    box with normative clamp/clearance rules, so a bled chart can show its own
+    axis without hand-suppressing it. Bare-marks stays the right call for a
+    sparkline-style tile with no chrome at all; chip mode is the right call
+    for a bled chart that still needs to show its axis.
   </p>
   <div data-artifact-container>
     <div data-artifact-item data-artifact-label="bled multi-line + legend band">
@@ -211,6 +221,23 @@
         </section>
       </card-ui>
     </div>
+    <div data-artifact-item data-artifact-label="bled bar + chip labels + legend band (ADR-0081)">
+      <card-ui data-chunk="chart-in-card-full-bleed-chip-legend" data-chunk-kind="block"
+        data-chunk-domain="dashboard"
+        data-chunk-description="Full-bleed bar chart with chip-label axis and legend band — Revenue/Target grouped-bar chart bleeding edge-to-edge inside the card with inset axis-value chips, paired with a chart-legend-ui mirroring its series in a normal-inset section below."
+        data-chunk-keywords="chart card bar chip labels legend bleed edge-to-edge revenue target dashboard analytics adr-0081" style="max-width:520px;">
+        <header>
+          <span slot="heading"><h3>Revenue vs target</h3></span>
+          <text-ui slot="description" color="subtle">Last 6 months</text-ui>
+        </header>
+        <section bleed>
+          <chart-ui id="pat-bleed-chip-legend-chart" type="grouped-bar" labels="chip" x="month" y="revenue,target"></chart-ui>
+        </section>
+        <section>
+          <chart-legend-ui for="pat-bleed-chip-legend-chart" shape="line"></chart-legend-ui>
+        </section>
+      </card-ui>
+    </div>
   </div>
 </section>
 
@@ -353,8 +380,8 @@
   <h2 variant="section">Rules</h2>
   <ul>
     <li>For sparklines, set <code>bleed</code> on the card's <code>&lt;section&gt;</code> so the line touches the edges.</li>
-    <li><code>bleed</code> is a bare-marks affordance, not a general "edge-to-edge chart" switch (gh#1095). It's safe for a sparkline, or for any other chart <code>type</code> that also sets both <code>no-grid</code> and <code>no-values</code> — i.e. nothing that renders axis ticks, gridlines, or value text. A chart that still shows guides or values needs the card's normal inset so that text doesn't collide with (and clip under) the card's rounded corners; card.css restores the inset automatically if it detects either case, so a forgotten <code>no-grid</code>/<code>no-values</code> fails safe rather than clipping silently.</li>
-    <li>Never put <code>&lt;chart-legend-ui&gt;</code> inside a <code>bleed</code> section — its badge rows need their own breathing room too. Place it in a plain <code>&lt;section&gt;</code> immediately after the chart's section, wired via <code>chart-legend-ui[for="&lt;chart id&gt;"]</code> (mirrors <code>.legendData</code>; see the "Full-bleed chart + legend band" example above and <a href="/site/components/chart-legend">chart-legend-ui</a>'s own <code>for</code> docs). card.css also restores the section's inset if a legend ends up inside a bled section anyway, so the fallback stays readable rather than edge-clipped.</li>
+    <li><code>bleed</code> is unconditionally author-controlled — card.css never re-inserts the card's inset for you (gh#1801; supersedes gh#1095's removed auto-restore guard). A bare-marks chart (a sparkline, or any other <code>type</code> that also sets both <code>no-grid</code> and <code>no-values</code> — i.e. nothing that renders axis ticks, gridlines, or value text) is naturally safe to bleed since it draws no such text. A chart that needs to keep its axis visible while bleeding sets <code>labels="chip"</code> instead (Charts 2.0 foundations, ADR-0081/REQ-F-004–006): axis-value and category chips render inset within the plot box with normative clamp/corner-clearance rules, so nothing renders close enough to the card's rounded corners to clip. A chart that shows guides or values inside a bled section with NEITHER <code>no-grid</code>/<code>no-values</code> NOR <code>labels="chip"</code> WILL collide with (and clip under) the card's rounded corners — that combination now clips silently instead of failing safe, so treat it as a real authoring hazard, not a style preference.</li>
+    <li>Never put <code>&lt;chart-legend-ui&gt;</code> inside a <code>bleed</code> section — its badge rows need their own breathing room too, and nothing restores that room automatically anymore. Place it in a plain <code>&lt;section&gt;</code> immediately after the chart's section, wired via <code>chart-legend-ui[for="&lt;chart id&gt;"]</code> (mirrors <code>.legendData</code>; see the "Full-bleed chart + legend band" example above and <a href="/site/components/chart-legend">chart-legend-ui</a>'s own <code>for</code> docs). A legend left inside a bled section now clips under the card's rounded corner instead of falling back to a readable inset.</li>
     <li>Put <code>no-values</code> on bar/line charts inside cards — the stat in the header already shows the current number.</li>
     <li>Use <code>&lt;stat-ui&gt;</code> in the heading slot only when the card's primary metric is a single number; otherwise use <code>&lt;h3&gt;</code> + description.</li>
     <li>Keep breakdowns shallow — 3–4 stats max. More belongs in a full section, not inside a tile.</li>

package/patterns/new-enrollments/new-enrollments.examples.html

@@ -0,0 +1,140 @@
+<header>
+  <div>
+    <h1>New Enrollments</h1>
+  </div>
+  <div data-tags>
+    <code>card-ui</code> <code>chart-ui</code> <code>chart-legend-ui</code> <code>select-ui</code> <code>button-ui</code> <code>row-ui</code>
+  </div>
+  <p>Recreation of Figma "Claude Code Gateway" node 129-2881 — a "New enrollments" dashboard card rendered four ways (stacked-bar, area/spline, sparkline + tooltip, radial-bar), one shared header grammar (title + date-range select + kebab menu), each chart body full-bleed per the Charts 2.0 foundations model.</p>
+</header>
+
+<section data-section data-property="new-enrollments-family">
+  <h2 variant="section">The card, four ways</h2>
+  <!-- Pattern source: docs/ops/spec/spec-charts-2-0-foundations.md (Design source: Figma node 129-2881) -->
+  <p data-note>
+    Built on <a href="/site/docs/adr/adr-0081">ADR-0081</a>'s Charts 2.0 foundations: <code>labels="chip"</code>
+    keeps a real axis inset within a bled plot box, <code>today</code> marks the boundary between complete
+    and in-progress periods, a per-datum <code>.provisional</code> flag renders the current/incomplete period
+    as a soft tonal fill with a dashed outline (bar family) or dashed-stroke-with-faded-fill (area/line), and the legend band
+    (<code>&lt;chart-legend-ui for&gt;</code> in a plain section below the bled plot) is the only sanctioned
+    legend pairing per OPEN-6.
+  </p>
+  <p data-note>
+    The Figma source itself carries five defects, corrected here rather than reproduced — see
+    "Fixes applied against the Figma source" below.
+  </p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label="stacked-bar — provisional period + legend band">
+      <card-ui data-chunk="new-enrollments-stacked-bar" data-chunk-kind="block"
+        data-chunk-domain="dashboard"
+        data-chunk-description="New enrollments stacked-bar card — New vs Returning enrollments by month, the current month rendered with a soft tonal fill and dashed outline as a provisional/incomplete period, paired with a legend band naming both segments."
+        data-chunk-keywords="new enrollments dashboard card stacked-bar provisional tonal dashed legend today-marker new returning analytics chart"
+        style="max-width:360px;">
+        <header>
+          <span slot="heading"><h3>New enrollments</h3></span>
+          <row-ui slot="action" gap="2" align="center">
+            <select-ui size="sm" variant="ghost" value="6m">
+              <option value="6m">Last 6 months</option>
+              <option value="3m">Last 3 months</option>
+              <option value="1m">Last month</option>
+            </select-ui>
+            <button-ui icon="dots-three-vertical" variant="ghost" size="sm" aria-label="Card options"></button-ui>
+          </row-ui>
+        </header>
+        <section bleed>
+          <chart-ui id="ne-stacked-bar" type="stacked-bar" labels="chip" today="Aug" x="month" y="New,Returning"
+            data='[{"month":"Mar","New":5,"Returning":3},{"month":"Apr","New":6,"Returning":4},{"month":"May","New":7,"Returning":4},{"month":"Jun","New":6,"Returning":5},{"month":"Jul","New":10,"Returning":6},{"month":"Aug","New":12,"Returning":8,"provisional":true}]'>
+          </chart-ui>
+        </section>
+        <section>
+          <chart-legend-ui for="ne-stacked-bar"></chart-legend-ui>
+        </section>
+      </card-ui>
+    </div>
+    <div data-artifact-item data-artifact-label="area/spline — provisional period (fix #3)">
+      <card-ui data-chunk="new-enrollments-area" data-chunk-kind="block"
+        data-chunk-domain="dashboard"
+        data-chunk-description="New enrollments area/spline card — total monthly enrollments trend, the current month rendered with a dashed stroke and faded fill as a provisional/incomplete period, matching the stacked-bar sibling's treatment for the same underlying state."
+        data-chunk-keywords="new enrollments dashboard card area spline trend provisional dashed faded today-marker analytics chart"
+        style="max-width:360px;">
+        <header>
+          <span slot="heading"><h3>New enrollments</h3></span>
+          <row-ui slot="action" gap="2" align="center">
+            <select-ui size="sm" variant="ghost" value="6m">
+              <option value="6m">Last 6 months</option>
+              <option value="3m">Last 3 months</option>
+              <option value="1m">Last month</option>
+            </select-ui>
+            <button-ui icon="dots-three-vertical" variant="ghost" size="sm" aria-label="Card options"></button-ui>
+          </row-ui>
+        </header>
+        <section bleed>
+          <chart-ui id="ne-area" type="area" labels="chip" today="Aug" smooth="0.4" no-values no-average x="month" y="value"
+            data='[{"month":"Mar","value":8},{"month":"Apr","value":10},{"month":"May","value":11},{"month":"Jun","value":11},{"month":"Jul","value":16},{"month":"Aug","value":20,"provisional":true}]'>
+          </chart-ui>
+        </section>
+      </card-ui>
+    </div>
+    <div data-artifact-item data-artifact-label="sparkline + tooltip">
+      <card-ui data-chunk="new-enrollments-sparkline" data-chunk-kind="block"
+        data-chunk-domain="dashboard"
+        data-chunk-description="New enrollments sparkline card — 30-day daily enrollment trend as a bare-marks sparkline, hovering any point surfaces the exact count and day via the built-in tooltip."
+        data-chunk-keywords="new enrollments dashboard card sparkline tooltip trend daily compact bare-marks analytics chart"
+        style="max-width:360px;">
+        <header>
+          <span slot="heading"><h3>New enrollments</h3></span>
+          <row-ui slot="action" gap="2" align="center">
+            <select-ui size="sm" variant="ghost" value="30d">
+              <option value="30d">Last 30 days</option>
+              <option value="7d">Last 7 days</option>
+            </select-ui>
+            <button-ui icon="dots-three-vertical" variant="ghost" size="sm" aria-label="Card options"></button-ui>
+          </row-ui>
+        </header>
+        <section bleed>
+          <chart-ui id="ne-sparkline" type="sparkline" x="day" y="value"
+            data='[{"day":"Jul 25","value":1580},{"day":"Jul 26","value":1620},{"day":"Jul 27","value":1550},{"day":"Jul 28","value":1670},{"day":"Jul 29","value":1710},{"day":"Jul 30","value":1640},{"day":"Jul 31","value":1690},{"day":"Aug 1","value":1730},{"day":"Aug 2","value":1660},{"day":"Aug 3","value":1780},{"day":"Aug 4","value":1810},{"day":"Aug 5","value":1750},{"day":"Aug 6","value":1700},{"day":"Aug 7","value":1840},{"day":"Aug 8","value":1790},{"day":"Aug 9","value":1880},{"day":"Aug 10","value":1820},{"day":"Aug 11","value":1760},{"day":"Aug 12","value":1910},{"day":"Aug 13","value":1850},{"day":"Aug 14","value":1800},{"day":"Aug 15","value":1940},{"day":"Aug 16","value":1890},{"day":"Aug 17","value":1830},{"day":"Aug 18","value":1970},{"day":"Aug 19","value":1920},{"day":"Aug 20","value":1870},{"day":"Aug 21","value":2032},{"day":"Aug 22","value":1950},{"day":"Aug 23","value":1990}]'>
+          </chart-ui>
+        </section>
+      </card-ui>
+    </div>
+    <div data-artifact-item data-artifact-label="radial-bar — real content + legend band (fixes #1, #2, #5)">
+      <card-ui data-chunk="new-enrollments-radial-bar" data-chunk-kind="block"
+        data-chunk-domain="dashboard"
+        data-chunk-description="New enrollments radial-bar card — enrollment channel mix (Online, Referral, Walk-in) each as percent of its monthly target reached, paired with a legend band naming all three channels."
+        data-chunk-keywords="new enrollments dashboard card radial-bar channel mix online referral walk-in target legend analytics chart"
+        style="max-width:360px;">
+        <header>
+          <span slot="heading"><h3>New enrollments</h3></span>
+          <row-ui slot="action" gap="2" align="center">
+            <select-ui size="sm" variant="ghost" value="30d">
+              <option value="30d">Last 30 days</option>
+              <option value="7d">Last 7 days</option>
+            </select-ui>
+            <button-ui icon="dots-three-vertical" variant="ghost" size="sm" aria-label="Card options"></button-ui>
+          </row-ui>
+        </header>
+        <section bleed>
+          <chart-ui id="ne-radial-bar" type="radial-bar" x="channel" y="v"
+            data='[{"channel":"Online","v":82},{"channel":"Referral","v":61},{"channel":"Walk-in","v":45}]'>
+          </chart-ui>
+        </section>
+        <section>
+          <chart-legend-ui for="ne-radial-bar"></chart-legend-ui>
+        </section>
+      </card-ui>
+    </div>
+  </div>
+</section>
+
+<section data-section data-property="figma-defect-fixes">
+  <h2 variant="section">Fixes applied against the Figma source</h2>
+  <p data-note>Figma node 129-2881 itself carries five defects. Each is corrected in this recreation rather than reproduced:</p>
+  <ul>
+    <li><strong>Content-truth mismatch (radial-bar).</strong> The Figma frame's title/subtitle read "New enrollments" / "Last 30 days" over unrelated CPU/Memory/Disk content. Replaced with real enrollment-channel data (Online/Referral/Walk-in against monthly target) so title and body agree.</li>
+    <li><strong>"DISC" legend typo (radial-bar).</strong> Moot once the CPU/Memory/Disk placeholder content is replaced — that legend row, and its typo, no longer ship.</li>
+    <li><strong>Missing provisional state (area/spline).</strong> The Figma area frame showed no distinct treatment for its own incomplete current period, unlike its stacked-bar sibling. Applied the same <code>.provisional</code> datum flag here (dashed stroke, faded fill — REQ-F-015/OPEN-3), so siblings give consistent feedback for the same state.</li>
+    <li><strong>No legend for stacked segments (stacked-bar).</strong> The Figma stacked-bar frame had two unlabeled segments with no legend, while its radial-bar sibling had one. Added a legend band below the plot naming both segments (New, Returning).</li>
+    <li><strong>Sub-region count diverged by chart type (radial-bar).</strong> The Figma radial-bar frame paired its rings with an inline legend column beside them — a second sub-region no other frame had, and the exact chrome-layer legend shape OPEN-6 rules OUT. Moved to the same legend-band section every multi-series variant here uses. Sub-region count now tracks series count, not chart type: the two single-series cards (area, sparkline) render only the plot; the two multi-series cards (stacked-bar, radial-bar) pair the plot with one legend band.</li>
+  </ul>
+</section>

package/patterns/new-enrollments/new-enrollments.html

@@ -0,0 +1,54 @@
+<!DOCTYPE html>
+<html lang="en" theme="auto">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>New Enrollments (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/chart/chart.css">
+  <link rel="stylesheet" href="../../components/chart-legend/chart-legend.css">
+  <link rel="stylesheet" href="../../components/icon/icon.css">
+  <link rel="stylesheet" href="../../components/row/row.css">
+  <link rel="stylesheet" href="../../components/select/select.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/chart/chart.js"></script>
+  <script type="module" src="../../components/chart-legend/chart-legend.js"></script>
+  <script type="module" src="../../components/icon/icon.js"></script>
+  <script type="module" src="../../components/row/row.js"></script>
+  <script type="module" src="../../components/select/select.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('./new-enrollments.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 new-enrollments.examples.html — ${err.message}</p>`;
+      console.error('[new-enrollments.html]', err);
+    }
+  </script>
+
+</body>
+</html>

package/patterns/table-in-card/table-in-card.examples.html

@@ -0,0 +1,168 @@
+<header>
+  <div>
+    <h1>Table in Card</h1>
+  </div>
+  <div data-tags>
+    <code>card-ui</code> <code>table-toolbar-ui</code> <code>table-ui</code> <code>table-footer-ui</code>
+  </div>
+  <p>Composition pattern: the full table structural system (gh#1807, spec-table-structural-system) — a card header (title + primary action), a title-less toolbar row (count + search + filter/sort/columns), a bleed table, and a footer (range label + pager). Figma reference: "Metabolic Tests" (node 134-4348).</p>
+</header>
+
+<section data-section data-property="when-to-use">
+  <h2 variant="section">When to use</h2>
+  <p data-note>
+    The canonical shape for any card-framed data grid that needs a pager — a
+    standalone <code>table-ui</code> (no card, no toolbar, no footer) is
+    still correct for a small, unpaginated list; reach for this pattern the
+    moment the table earns a toolbar (search/filter/sort/columns) and/or a
+    footer (a page range). The title lives in the card header, never
+    duplicated on the toolbar — see table-toolbar.yaml's title-collision rule.
+  </p>
+</section>
+
+<section data-section data-property="anatomy">
+  <h2 variant="section">Anatomy</h2>
+  <code-ui language="html">&lt;card-ui&gt;
+  &lt;header&gt;
+    &lt;span slot="heading"&gt;Metabolic Tests&lt;/span&gt;
+    &lt;button-ui slot="action" variant="primary" size="sm"&gt;New test&lt;/button-ui&gt;
+  &lt;/header&gt;
+  &lt;section&gt;
+    &lt;!-- title-less: the card header already owns the title --&gt;
+    &lt;table-toolbar-ui for="tests" count="128"&gt;&lt;/table-toolbar-ui&gt;
+  &lt;/section&gt;
+  &lt;section bleed&gt;
+    &lt;table-ui id="tests" sortable&gt;&lt;/table-ui&gt;
+  &lt;/section&gt;
+  &lt;footer divider&gt;
+    &lt;table-footer-ui for="tests" page="1" page-size="10" range-total="128"&gt;&lt;/table-footer-ui&gt;
+  &lt;/footer&gt;
+&lt;/card-ui&gt;</code-ui>
+</section>
+
+<section data-section data-property="server-mode">
+  <h2 variant="section">Server-mode (Shape 1)</h2>
+  <p data-note>The server returns the page's rows plus the total row count (gh#1754 Shape 1). <code>table-ui[paginate="0"]</code> holds only the current page's rows; <code>table-footer-ui[range-total]</code> carries the server's total. The reference anatomy: leading status-dot column, sortable headers, tag chips, a status badge, and a kebab row-actions column — all via existing table-ui cell types and <code>render</code> cells.</p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label="Metabolic Tests — server-mode, canonical composition"
+         data-chunk="table-in-card-server-mode"
+         data-chunk-kind="block"
+         data-chunk-domain="data"
+         data-chunk-description="Metabolic Tests card — card header with title and New test action, title-less toolbar with count/search/filter/sort/columns, bleed table with status-dot/sortable-name/patient/date/status-badge/tag-chips/kebab-actions columns, and a footer with range label and pager (server-mode, gh#1754 Shape 1)."
+         data-chunk-keywords="table card toolbar footer pagination metabolic tests status dot badge tags kebab actions server mode data grid healthcare">
+      <card-ui style="max-width:720px;">
+        <header>
+          <span slot="heading">Metabolic Tests</span>
+          <button-ui slot="action" variant="primary" size="sm" icon="plus" text="New test"></button-ui>
+        </header>
+        <section>
+          <table-toolbar-ui for="pat-tests" count="128" placeholder="Search tests…"></table-toolbar-ui>
+        </section>
+        <section bleed>
+          <table-ui id="pat-tests" sortable></table-ui>
+        </section>
+        <footer divider>
+          <table-footer-ui for="pat-tests" page="1" page-size="10" range-total="128"></table-footer-ui>
+        </footer>
+      </card-ui>
+    </div>
+  </div>
+</section>
+
+<section data-section data-property="client-mode">
+  <h2 variant="section">Client-mode (paginate + no-pager)</h2>
+  <p data-note><code>table-ui[paginate]</code> slices the FULL dataset client-side; <code>[no-pager]</code> hides the table's own internal pagination bar so the bound footer's composed pager is the only one visible (ADR-0080's anti-doubled-pager rule — explicit, never automatic).</p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label="Metabolic Tests — client-mode, paginate + no-pager"
+         data-chunk="table-in-card-client-mode"
+         data-chunk-kind="block"
+         data-chunk-domain="data"
+         data-chunk-description="Metabolic Tests card in client-mode — table-ui paginate=6 no-pager slices a full in-browser dataset, with table-footer-ui as the sole visible pager."
+         data-chunk-keywords="table card toolbar footer pagination client mode paginate no-pager metabolic tests data grid healthcare">
+      <card-ui style="max-width:720px;">
+        <header>
+          <span slot="heading">Metabolic Tests</span>
+        </header>
+        <section>
+          <table-toolbar-ui for="pat-tests-client" count="18"></table-toolbar-ui>
+        </section>
+        <section bleed>
+          <table-ui id="pat-tests-client" paginate="6" no-pager sortable></table-ui>
+        </section>
+        <footer divider>
+          <table-footer-ui for="pat-tests-client"></table-footer-ui>
+        </footer>
+      </card-ui>
+    </div>
+  </div>
+</section>
+
+<section data-section data-property="empty">
+  <h2 variant="section">Empty</h2>
+  <p data-note>A confirmed-empty result set (explicit <code>range-total="0"</code>) — the footer's <code>empty</code> slot renders in the range label's own position; the pager stays hidden.</p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label="Metabolic Tests — empty result set"
+         data-chunk="table-in-card-empty"
+         data-chunk-kind="block"
+         data-chunk-domain="data"
+         data-chunk-description="Metabolic Tests card with zero matching rows — table-ui empty overlay in the bleed section, table-footer-ui range-total=0 with a slotted 'no tests match your filters' message."
+         data-chunk-keywords="table card toolbar footer pagination empty no results filters metabolic tests data grid healthcare">
+      <card-ui style="max-width:720px;">
+        <header>
+          <span slot="heading">Metabolic Tests</span>
+        </header>
+        <section>
+          <table-toolbar-ui for="pat-tests-empty" count="0"></table-toolbar-ui>
+        </section>
+        <section bleed>
+          <table-ui id="pat-tests-empty"></table-ui>
+        </section>
+        <footer divider>
+          <table-footer-ui for="pat-tests-empty" range-total="0">
+            <span slot="empty">No tests match your filters</span>
+          </table-footer-ui>
+        </footer>
+      </card-ui>
+    </div>
+  </div>
+</section>
+
+<section data-section data-property="loading">
+  <h2 variant="section">Loading</h2>
+  <p data-note>While data fetches, <code>table-ui[loading]</code> renders its own skeleton rows and the footer's <code>range-total</code> stays absent — the footer contributes silence, not a spinner (REQ-S-001).</p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label="Metabolic Tests — loading"
+         data-chunk="table-in-card-loading"
+         data-chunk-kind="block"
+         data-chunk-domain="data"
+         data-chunk-description="Metabolic Tests card mid-fetch — table-ui loading skeleton rows, table-footer-ui with no range-total set (both the range label and pager stay hidden)."
+         data-chunk-keywords="table card toolbar footer pagination loading skeleton fetch metabolic tests data grid healthcare">
+      <card-ui style="max-width:720px;">
+        <header>
+          <span slot="heading">Metabolic Tests</span>
+        </header>
+        <section>
+          <table-toolbar-ui for="pat-tests-loading"></table-toolbar-ui>
+        </section>
+        <section bleed>
+          <table-ui id="pat-tests-loading" loading></table-ui>
+        </section>
+        <footer divider>
+          <table-footer-ui for="pat-tests-loading"></table-footer-ui>
+        </footer>
+      </card-ui>
+    </div>
+  </div>
+</section>
+
+<section data-section data-property="rules">
+  <h2 variant="section">Rules</h2>
+  <ul>
+    <li>The title lives in the card header (<code>[slot="heading"]</code>) — the toolbar carries no <code>[text]</code>. A toolbar with <code>[text]</code> sharing a card with a heading-slotted header doubles the title row (table-toolbar.yaml's title-collision rule, gh#1807 REQ-C-004); a title-less toolbar under a card header is the canonical shape, not doubled chrome.</li>
+    <li>The toolbar's <code>[count]</code> badge and the footer's range label coexist — they answer different questions (collection summary vs. page-window position) and neither replaces the other.</li>
+    <li>In a composition that includes a <code>table-footer-ui</code>, leave the toolbar's <code>[range-start]</code>/<code>[range-end]</code>/<code>[range-total]</code> unset — the range summary's home is the footer.</li>
+    <li>Client-mode (<code>[paginate]</code>) needs <code>[no-pager]</code> on the table so the internal bar and the footer's composed pager don't both render.</li>
+    <li>The <code>&lt;footer divider&gt;</code> — card-ui's own footer grammar supplies inset, bottom-pin, and the divider line; the bleed section's zero trailing margin puts the divider flush under the last row.</li>
+    <li>Status-dot, tag chips, and the kebab row-actions column are all <code>render</code>-function columns over existing primitives (<code>swatch-ui</code>, <code>tag-ui</code>, <code>menu-ui</code>/<code>menu-item-ui</code>) — no new table-ui cell type.</li>
+  </ul>
+</section>

package/patterns/table-in-card/table-in-card.examples.js

@@ -0,0 +1,139 @@
+/** Table in Card pattern — render-cell columns + sample data (gh#1807) */
+
+// A semantic-token dot (swatch-ui) per status — no new cell type, no raw
+// colors: --swatch-color always resolves to a real --a-* family token.
+const STATUS_DOT_TOKEN = {
+  Complete: 'var(--a-success)',
+  Pending: 'var(--a-warning)',
+  Failed: 'var(--a-danger)',
+};
+
+const STATUS_BADGE_VARIANT = { Complete: 'success', Pending: 'warning', Failed: 'danger' };
+
+function renderStatusDot(value) {
+  const dot = document.createElement('swatch-ui');
+  dot.setAttribute('shape', 'dot');
+  dot.setAttribute('size', 'sm');
+  dot.setAttribute('aria-hidden', 'true');
+  dot.style.setProperty('--swatch-color', STATUS_DOT_TOKEN[value] || 'var(--a-fg-muted)');
+  return dot;
+}
+
+function renderTags(value) {
+  const wrap = document.createElement('row-ui');
+  wrap.setAttribute('gap', '1');
+  wrap.setAttribute('wrap', '');
+  for (const t of value || []) {
+    const tag = document.createElement('tag-ui');
+    tag.setAttribute('text', t);
+    tag.setAttribute('size', 'sm');
+    wrap.appendChild(tag);
+  }
+  return wrap;
+}
+
+function renderKebabActions(_value, row) {
+  const menu = document.createElement('menu-ui');
+  const trigger = document.createElement('button-ui');
+  trigger.setAttribute('slot', 'trigger');
+  trigger.setAttribute('icon', 'dots-three-vertical');
+  trigger.setAttribute('variant', 'ghost');
+  trigger.setAttribute('size', 'sm');
+  trigger.setAttribute('aria-label', `Actions for ${row.name}`);
+  menu.appendChild(trigger);
+  for (const [text, icon] of [['View', 'eye'], ['Edit', 'pencil-simple'], ['Archive', 'archive']]) {
+    const item = document.createElement('menu-item-ui');
+    item.setAttribute('text', text);
+    item.setAttribute('icon', icon);
+    menu.appendChild(item);
+  }
+  return menu;
+}
+
+const COLUMNS = [
+  { key: 'status', label: '', render: (v) => renderStatusDot(v), width: 32, sortable: false },
+  { key: 'name', label: 'Test', sortable: true },
+  { key: 'patient', label: 'Patient', sortable: true },
+  { key: 'date', label: 'Date', type: 'date', sortable: true },
+  { key: 'status', label: 'Status', type: 'badge', meta: { variants: STATUS_BADGE_VARIANT } },
+  { key: 'tags', label: 'Tags', render: (v) => renderTags(v) },
+  // Render-only column, no backing data field — the idiom table-toolbar-ui's
+  // own docs establish for columns like this (`_cancel`/`_download`/`_replay`).
+  { key: '_actions', label: '', render: renderKebabActions, width: 48, sortable: false },
+];
+
+const NAMES = ['CMP', 'BMP', 'Lipid Panel', 'A1C', 'TSH', 'CBC', 'Vitamin D', 'Ferritin', 'PT/INR', 'Liver Panel', 'Renal Panel', 'Electrolyte Panel'];
+const PATIENTS = ['A. Chen', 'J. Park', 'L. Kim', 'M. Rivera', 'S. Torres', 'P. Nair', 'O. Haddad', 'T. Baker'];
+const STATUSES = ['Complete', 'Pending', 'Failed'];
+const TAG_SETS = [['Routine'], ['STAT'], ['Fasting', 'Routine'], ['Repeat'], []];
+
+function makeRows(count) {
+  return Array.from({ length: count }, (_, i) => ({
+    name: NAMES[i % NAMES.length],
+    patient: PATIENTS[i % PATIENTS.length],
+    date: `2026-08-${String((i % 27) + 1).padStart(2, '0')}`,
+    status: STATUSES[i % STATUSES.length],
+    tags: TAG_SETS[i % TAG_SETS.length],
+  }));
+}
+
+export default function setup(router) {
+  // Server-mode (Shape 1) — the table only ever holds the CURRENT page's
+  // rows; the total (128) lives on the footer's own range-total.
+  const server = router.querySelector('#pat-tests');
+  const serverFooter = router.querySelector('table-footer-ui[for="pat-tests"]');
+  if (server) {
+    server.columns = COLUMNS;
+    server.data = makeRows(10);
+
+    // REQ-D-002's fetch loop (CodeRabbit review, PR #1811): the footer
+    // never optimistically advances its own [page] in server-mode — this
+    // handler's write-back after the "fetch" resolves is the state
+    // authority. `makeRows`'s own generator is offset-seeded per page so
+    // each page's fixture rows visibly differ (deterministic, not a real
+    // fetch, but the same swap-then-confirm shape a real one would have).
+    if (serverFooter) {
+      serverFooter.addEventListener('page-change', (e) => {
+        const page = e.detail?.page;
+        server.data = makeRows(10).map((row, i) => ({
+          ...row,
+          name: NAMES[(i + page * 3) % NAMES.length],
+          patient: PATIENTS[(i + page * 5) % PATIENTS.length],
+        }));
+        serverFooter.setAttribute('page', String(page));
+      });
+    }
+  }
+
+  // Client-mode — the FULL in-browser dataset; table-ui[paginate] slices it.
+  const client = router.querySelector('#pat-tests-client');
+  if (client) {
+    client.columns = COLUMNS;
+    client.data = makeRows(18);
+
+    // REQ-W-006's named staleness edge (see table-footer.examples.js for
+    // the full rationale) — the static markup's zero-attribute footer
+    // connects before this setup() runs; recreate it now that real data
+    // is in place so its bind-time derivation reads the populated table.
+    const oldFooter = router.querySelector('table-footer-ui[for="pat-tests-client"]');
+    if (oldFooter) {
+      const freshFooter = document.createElement('table-footer-ui');
+      freshFooter.setAttribute('for', 'pat-tests-client');
+      oldFooter.replaceWith(freshFooter);
+    }
+  }
+
+  // Empty — columns set, zero rows; table-ui renders its own empty overlay.
+  const empty = router.querySelector('#pat-tests-empty');
+  if (empty) {
+    empty.columns = COLUMNS;
+    empty.data = [];
+  }
+
+  // Loading — columns set so the header renders; loading=true shows
+  // skeleton rows regardless of .data.
+  const loading = router.querySelector('#pat-tests-loading');
+  if (loading) {
+    loading.columns = COLUMNS;
+  }
+}