@adia-ai/web-components 0.8.21 → 0.8.23

package/patterns/bulk-action-toolbar/bulk-action-toolbar.examples.html

@@ -2,60 +2,145 @@
   <div>
     <h1>Bulk Action Toolbar</h1>
     <div data-actions>
-      <tag-ui size="sm">table-toolbar-ui</tag-ui> <tag-ui size="sm">toolbar-ui</tag-ui> <tag-ui size="sm">table-ui</tag-ui>
+      <tag-ui size="sm">table-toolbar-ui</tag-ui> <tag-ui size="sm">toolbar-ui</tag-ui> <tag-ui size="sm">table-ui</tag-ui> <tag-ui size="sm">card-ui</tag-ui>
     </div>
   </div>
-  <p>When a table has row selection, swap the standard <code>&lt;table-toolbar-ui&gt;</code> for a contextual bulk-action bar at the same surface position. Selection count anchors the left, actions flow from the right, destructive action last.</p>
+  <p>When a table has row selection, surface a contextual bulk-action bar. Two variants: swap the standard <code>&lt;table-toolbar-ui&gt;</code> for a bar at the same surface position, or float a card-like elevated bar at the bottom of the table's own scroll container. Selection count anchors the left, actions flow from the right, destructive action last.</p>
 </header>
 
 <section data-section data-property="when-to-use">
   <h2 variant="section">When to use</h2>
   <p data-note>
     Any table where users act on multiple rows at once: archive, delete, export, move.
-    Swapping the toolbar (rather than stacking a second bar) keeps the surface compact and
-    signals "selection mode" with the strongest possible affordance — the chrome itself changes.
+  </p>
+  <p data-note>
+    Pick the <strong>toolbar swap</strong> for short or inline tables — everything fits in one
+    viewport, so the swapped bar at the top stays visible and "the chrome itself changes" is the
+    strongest possible affordance for selection mode.
+  </p>
+  <p data-note>
+    Pick the <strong>floating variant</strong> as the default once a table can run taller than
+    ~one viewport (long lists, paginated consoles at 50+ rows). Selections made mid-scroll get no
+    feedback from a toolbar that has already scrolled out of view — the floating bar stays
+    anchored to the bottom of the table's own scroll container so it's visible at the moment of
+    use, without pinning to the browser viewport and ignoring shell chrome.
   </p>
 </section>
 
-<section data-section data-property="toolbar-swap" data-chunk="bulk-action-toolbar-swap">
-  <h2 variant="section">Toolbar swap on selection</h2>
-  <p data-note>Tick the checkboxes below — the default <code>&lt;table-toolbar-ui&gt;</code> swaps for the bulk-action bar at the same height. Untick to return.</p>
+<section data-section data-property="toolbar-swap" data-chunk="bulk-action-toolbar-swap" data-chunk-kind="block"
+  data-chunk-domain="data"
+  data-chunk-description="Bulk-action toolbar over a selectable table — the default table toolbar swaps at the same height for an 'N selected' bar with Archive, Export, Move, a divider, and Delete when rows are checked."
+  data-chunk-keywords="bulk actions toolbar selection selected rows table checkbox archive export move delete swap batch multi-select bar">
+  <h2 variant="section">Toolbar swap (top-anchored)</h2>
+  <p data-note>Tick the checkboxes below — the default <code>&lt;table-toolbar-ui&gt;</code> swaps for the bulk-action bar at the same height. Untick to return. Best for short/inline tables (see When to use).</p>
   <card-ui raw>
     <section bleed>
       <table-toolbar-ui id="pat-bulk-default" for="pat-bulk-table" text="Resources" count="6" no-filter no-sort no-columns></table-toolbar-ui>
 
-      <toolbar-ui id="pat-bulk-actions" data-bulk-bar role="toolbar" aria-label="Bulk actions" hidden>
-        <text-ui strong><span data-bulk-count>0</span> selected</text-ui>
-        <span data-spacer style="flex:1 1 auto"></span>
-        <button-ui text="Archive" icon="archive" variant="ghost" size="sm" data-bulk-action="archive"></button-ui>
-        <button-ui text="Export" icon="download-simple" variant="ghost" size="sm" data-bulk-action="export"></button-ui>
-        <button-ui text="Move" icon="folder-simple" variant="ghost" size="sm" data-bulk-action="move"></button-ui>
-        <divider-ui vertical></divider-ui>
-        <button-ui text="Delete" icon="trash" variant="ghost" size="sm" data-bulk-action="delete"></button-ui>
+      <!-- align="space-between" pushes the trailing group right — NOT a
+           flex-grow spacer span (gh#494 audit finding: toolbar-ui's overflow
+           reflow sums each top-level child's RENDERED width to decide what
+           fits; a flex-grow spacer has already expanded to fill the free
+           space by the time it's measured, so the sum always reads "full"
+           and spuriously spills the trailing action(s) into the "more" menu
+           — Delete was silently unreachable here before this fix, even with
+           plenty of room). Grouping into two <toolbar-group-ui> atoms keeps
+           the reflow's width sum accurate; see the floating variant below
+           for the same fix applied at a smaller width. -->
+      <toolbar-ui id="pat-bulk-actions" data-bulk-bar role="toolbar" aria-label="Bulk actions" align="space-between" hidden>
+        <toolbar-group-ui>
+          <text-ui strong><span data-bulk-count>0</span> selected</text-ui>
+        </toolbar-group-ui>
+        <toolbar-group-ui>
+          <button-ui text="Archive" icon="archive" variant="ghost" size="sm" data-bulk-action="archive"></button-ui>
+          <button-ui text="Export" icon="download-simple" variant="ghost" size="sm" data-bulk-action="export"></button-ui>
+          <button-ui text="Move" icon="folder-simple" variant="ghost" size="sm" data-bulk-action="move"></button-ui>
+          <divider-ui vertical></divider-ui>
+          <button-ui text="Delete" icon="trash" variant="ghost" size="sm" data-bulk-action="delete"></button-ui>
+        </toolbar-group-ui>
       </toolbar-ui>
 
-      <table-ui id="pat-bulk-table" selectable sortable striped></table-ui>
+      <table-ui frameless id="pat-bulk-table" selectable sortable striped></table-ui>
+    </section>
+  </card-ui>
+</section>
+
+<section data-section data-property="floating-variant" data-chunk="bulk-action-toolbar-floating" data-chunk-kind="block"
+  data-chunk-domain="data"
+  data-chunk-description="Floating bottom-anchored bulk-action bar — a card-like elevated toolbar (elevation 3) that appears sticky to the bottom of a table's own scroll container (not the browser viewport) when rows are selected, with selection count, an optional per-flow controls slot, actions with destructive last, and an explicit Clear button. Composes table-ui's select event with card-ui + toolbar-ui; no focus steal on appearance, Escape clears selection when the bar owns focus, count is aria-live=polite."
+  data-chunk-keywords="floating bulk action bar bottom anchored sticky selection toolbar card elevated table scroll container escape clear aria-live gmail linear notion">
+  <h2 variant="section">Floating (bottom-anchored)</h2>
+  <p data-note>
+    Tick the checkboxes below — a card-like elevated bar rises from the bottom of the table's own
+    scroll container (scroll the table, the bar tracks it, not the page). Press
+    <code>Escape</code> while the bar has focus, or use the explicit Clear button, to release
+    the selection.
+  </p>
+  <card-ui raw>
+    <section bleed>
+      <table-toolbar-ui id="pat-bulk-float-default" for="pat-bulk-float-table" text="Resources" count="12" no-filter no-sort no-columns></table-toolbar-ui>
+
+      <div data-table-scroll>
+        <table-ui frameless id="pat-bulk-float-table" selectable sortable striped></table-ui>
+
+        <card-ui id="pat-bulk-float-bar" elevation="3" data-bulk-bar-floating>
+          <section>
+            <!-- align="space-between" pushes the trailing group right —
+                 NOT a flex-grow spacer span or an auto margin on a content
+                 item. toolbar-ui's overflow reflow sums each top-level
+                 child's RENDERED width to decide what fits; any child that
+                 absorbs free space (flex-grow, or an auto margin resolved
+                 to real pixels post-layout) has already expanded to fill
+                 that space by the time it's measured, so the sum always
+                 reads "full" and spuriously spills content. `justify-content`
+                 only repositions flex items — it doesn't touch their
+                 individual widths (toolbar-ui's own CSS pins every direct
+                 child at `flex: 0 0 auto`) — so grouping into two
+                 `<toolbar-group-ui>` atoms and letting `align="space-between"`
+                 do the pushing keeps the reflow's width sum accurate. -->
+            <toolbar-ui role="toolbar" aria-label="Bulk actions" align="space-between">
+              <toolbar-group-ui>
+                <text-ui strong aria-live="polite"><span data-bulk-float-count>0</span> selected</text-ui>
+                <span data-bulk-controls></span>
+              </toolbar-group-ui>
+              <toolbar-group-ui>
+                <button-ui icon="archive" icon-only aria-label="Archive" variant="ghost" size="sm" data-bulk-action="archive"></button-ui>
+                <button-ui icon="download-simple" icon-only aria-label="Export" variant="ghost" size="sm" data-bulk-action="export"></button-ui>
+                <button-ui icon="folder-simple" icon-only aria-label="Move" variant="ghost" size="sm" data-bulk-action="move"></button-ui>
+                <divider-ui vertical></divider-ui>
+                <button-ui icon="trash" icon-only aria-label="Delete" variant="ghost" size="sm" data-bulk-action="delete"></button-ui>
+                <divider-ui vertical></divider-ui>
+                <button-ui text="Clear" variant="ghost" size="sm" data-bulk-clear></button-ui>
+              </toolbar-group-ui>
+            </toolbar-ui>
+          </section>
+        </card-ui>
+      </div>
     </section>
   </card-ui>
 </section>
 
 <section data-section data-property="anatomy">
-  <h2 variant="section">Anatomy</h2>
+  <h2 variant="section">Anatomy — toolbar swap</h2>
   <p data-note>Both toolbars sit inside the same <code>&lt;section bleed&gt;</code> so they share one surface. Toggle visibility on the <code>select</code> event from the table.</p>
   <code-ui language="html">&lt;card-ui&gt;
   &lt;section bleed&gt;
     &lt;!-- Default state — modern foundation --&gt;
     &lt;table-toolbar-ui for="resources" text="Resources" count="6"&gt;&lt;/table-toolbar-ui&gt;
 
-    &lt;!-- Bulk action bar — swaps in when rows are selected --&gt;
-    &lt;toolbar-ui data-bulk-bar hidden role="toolbar" aria-label="Bulk actions"&gt;
-      &lt;text-ui strong&gt;&lt;span data-bulk-count&gt;0&lt;/span&gt; selected&lt;/text-ui&gt;
-      &lt;span data-spacer&gt;&lt;/span&gt;
-      &lt;button-ui text="Archive" icon="archive" variant="ghost" size="sm"&gt;&lt;/button-ui&gt;
-      &lt;button-ui text="Export"  icon="download-simple" variant="ghost" size="sm"&gt;&lt;/button-ui&gt;
-      &lt;button-ui text="Move"    icon="folder-simple"   variant="ghost" size="sm"&gt;&lt;/button-ui&gt;
-      &lt;divider-ui vertical&gt;&lt;/divider-ui&gt;
-      &lt;button-ui text="Delete"  icon="trash" variant="ghost" size="sm"&gt;&lt;/button-ui&gt;
+    &lt;!-- Bulk action bar — swaps in when rows are selected. align="space-between"
+         (not a flex-grow spacer — see Rules) pushes the action group right. --&gt;
+    &lt;toolbar-ui data-bulk-bar hidden role="toolbar" aria-label="Bulk actions" align="space-between"&gt;
+      &lt;toolbar-group-ui&gt;
+        &lt;text-ui strong&gt;&lt;span data-bulk-count&gt;0&lt;/span&gt; selected&lt;/text-ui&gt;
+      &lt;/toolbar-group-ui&gt;
+      &lt;toolbar-group-ui&gt;
+        &lt;button-ui text="Archive" icon="archive" variant="ghost" size="sm"&gt;&lt;/button-ui&gt;
+        &lt;button-ui text="Export"  icon="download-simple" variant="ghost" size="sm"&gt;&lt;/button-ui&gt;
+        &lt;button-ui text="Move"    icon="folder-simple"   variant="ghost" size="sm"&gt;&lt;/button-ui&gt;
+        &lt;divider-ui vertical&gt;&lt;/divider-ui&gt;
+        &lt;button-ui text="Delete"  icon="trash" variant="ghost" size="sm"&gt;&lt;/button-ui&gt;
+      &lt;/toolbar-group-ui&gt;
     &lt;/toolbar-ui&gt;
 
     &lt;table-ui id="resources" selectable sortable&gt;&lt;/table-ui&gt;
@@ -75,15 +160,108 @@ table.addEventListener('select', (e) =&gt; {
 });</code-ui>
 </section>
 
+<section data-section data-property="anatomy-floating">
+  <h2 variant="section">Anatomy — floating (bottom-anchored)</h2>
+  <p data-note>
+    <code>[data-table-scroll]</code> wraps the table and IS its scroll container (bounded height +
+    <code>overflow: auto</code>); the floating bar is a sibling of <code>&lt;table-ui&gt;</code>
+    inside it, positioned with <code>position: sticky</code> so it pins to that box's bottom edge
+    — never the browser viewport, and never a child of <code>&lt;table-ui&gt;</code> (it owns its
+    own light DOM). The bar is a <code>&lt;card-ui elevation="3"&gt;</code> for the card-like
+    elevated container, holding a standard <code>&lt;toolbar-ui&gt;</code>.
+  </p>
+  <code-ui language="html">&lt;section bleed&gt;
+  &lt;table-toolbar-ui for="resources" text="Resources" count="12"&gt;&lt;/table-toolbar-ui&gt;
+
+  &lt;div data-table-scroll&gt;   &lt;!-- position: relative; overflow: auto; max-height: … --&gt;
+    &lt;table-ui id="resources" selectable sortable&gt;&lt;/table-ui&gt;
+
+    &lt;!-- Floating bar — position: sticky; bottom: … in the pattern's CSS.
+         No [hidden]/display:none toggle — see the pattern's CSS comment
+         on why (toolbar-ui's overflow measurement gets stuck at 0px). --&gt;
+    &lt;card-ui elevation="3" data-bulk-bar-floating&gt;
+      &lt;section&gt;
+        &lt;!-- align="space-between" pushes the action group right — NOT a
+             flex-grow spacer span or an auto margin on a content item.
+             toolbar-ui's overflow reflow sums each top-level child's
+             RENDERED width to decide what fits; anything that absorbs free
+             space has already expanded to fill it by the time it's
+             measured, so the sum always reads "full" and spuriously spills
+             content. Two &lt;toolbar-group-ui&gt; atoms + align="space-between"
+             keeps the width sum accurate (see Rules). --&gt;
+        &lt;toolbar-ui role="toolbar" aria-label="Bulk actions" align="space-between"&gt;
+          &lt;toolbar-group-ui&gt;
+            &lt;text-ui strong aria-live="polite"&gt;&lt;span data-bulk-count&gt;0&lt;/span&gt; selected&lt;/text-ui&gt;
+            &lt;span data-bulk-controls&gt;&lt;/span&gt;  &lt;!-- optional per-flow controls, e.g. a shared-rationale input --&gt;
+          &lt;/toolbar-group-ui&gt;
+          &lt;toolbar-group-ui&gt;
+            &lt;!-- Icon-only (icon-only + aria-label) — a compact floating
+                 pill has less width to spend than the full-width top-swap
+                 bar. --&gt;
+            &lt;button-ui icon="archive" icon-only aria-label="Archive" variant="ghost" size="sm"&gt;&lt;/button-ui&gt;
+            &lt;button-ui icon="download-simple" icon-only aria-label="Export" variant="ghost" size="sm"&gt;&lt;/button-ui&gt;
+            &lt;button-ui icon="folder-simple"   icon-only aria-label="Move"   variant="ghost" size="sm"&gt;&lt;/button-ui&gt;
+            &lt;divider-ui vertical&gt;&lt;/divider-ui&gt;
+            &lt;button-ui icon="trash" icon-only aria-label="Delete" variant="ghost" size="sm"&gt;&lt;/button-ui&gt;
+            &lt;divider-ui vertical&gt;&lt;/divider-ui&gt;
+            &lt;button-ui text="Clear" variant="ghost" size="sm" data-bulk-clear&gt;&lt;/button-ui&gt;
+          &lt;/toolbar-group-ui&gt;
+        &lt;/toolbar-ui&gt;
+      &lt;/section&gt;
+    &lt;/card-ui&gt;
+  &lt;/div&gt;
+&lt;/section&gt;</code-ui>
+  <code-ui language="javascript">// Enter/exit toggles [data-open]/[data-closing]; the CSS does the rest —
+// including the delayed `visibility: hidden` on close (see the pattern's
+// own &lt;style&gt; block). No [hidden]/display:none toggle: toolbar-ui's
+// spillover system measures its own width via ResizeObserver on first
+// connect, and a display:none ancestor at that moment gives it a 0px
+// reading it does not reliably re-measure later — items it moved to the
+// "more" overflow menu at that 0px reading stay stuck there even once the
+// bar has real width. `visibility` keeps the box laid out (real width,
+// always measurable) while still pulling it out of the a11y tree, tab
+// order, and click target when closed.
+
+function showBar(bar) {
+  bar.removeAttribute('data-closing');
+  bar.setAttribute('data-open', '');   // no .focus() — never steal focus on appearance
+}
+
+function hideBar(bar) {
+  bar.setAttribute('data-closing', '');
+  bar.removeAttribute('data-open');
+}
+
+table.addEventListener('select', (e) =&gt; {
+  const n = e.detail?.selected?.length ?? 0;
+  countEl.textContent = String(n);
+  n &gt; 0 ? showBar(bar) : hideBar(bar);
+});
+
+// Escape clears selection ONLY when the bar owns focus (listener lives
+// on the bar itself, so it only fires while focus is inside it).
+bar.addEventListener('keydown', (e) =&gt; {
+  if (e.key === 'Escape') { e.stopPropagation(); table.clearSelection(); }
+});
+
+bar.addEventListener('press', (e) =&gt; {
+  if (e.target?.closest?.('[data-bulk-clear], [data-bulk-action]')) {
+    table.clearSelection();
+  }
+});</code-ui>
+</section>
+
 <section data-section data-property="rules">
   <h2 variant="section">Rules</h2>
   <ul>
-    <li>Default state uses <code>&lt;table-toolbar-ui&gt;</code> — the modern foundation. It already wires Filter / Sort / Columns / Search to the table via <code>[for]</code>; don't hand-roll those.</li>
-    <li>Bulk bar uses <code>&lt;toolbar-ui&gt;</code> with <code>role="toolbar"</code> and <code>aria-label="Bulk actions"</code>. Match its <code>--toolbar-py</code> / <code>--toolbar-px</code> to <code>--table-toolbar-py</code> / <code>--table-toolbar-px</code> so the swap is seamless.</li>
-    <li>Both toolbars sit inside the same <code>&lt;section bleed&gt;</code> as the table — one surface, flush alignment with the first table cell.</li>
-    <li>Selection count leads the bulk bar; <code>&lt;span data-spacer&gt;</code> pushes actions right.</li>
-    <li>Destructive actions go last and are visually separated with a <code>&lt;divider-ui vertical&gt;</code>.</li>
+    <li>Pick one variant per table — see When to use. Both stay valid; don't run both at once on the same table.</li>
+    <li>Default state uses <code>&lt;table-toolbar-ui&gt;</code> — the modern foundation. It already wires Filter / Sort / Columns / Search to the table via <code>[for]</code>; don't hand-roll those. The floating variant keeps it visible at all times (it doesn't swap).</li>
+    <li>Every bulk bar uses <code>&lt;toolbar-ui&gt;</code> with <code>role="toolbar"</code> and <code>aria-label="Bulk actions"</code>.</li>
+    <li><strong>Toolbar swap:</strong> match its <code>--toolbar-py</code> / <code>--toolbar-px</code> to <code>--table-toolbar-py</code> / <code>--table-toolbar-px</code> so the swap is seamless; both toolbars sit inside the same <code>&lt;section bleed&gt;</code> as the table, flush with the first table cell.</li>
+    <li><strong>Floating:</strong> wrap the bar in <code>&lt;card-ui elevation="3"&gt;</code> for the card-like elevated surface (tokens only — <code>--a-shadow-*</code> via <code>[elevation]</code>, never a raw color/shadow); position it with <code>position: sticky</code> inside a <code>[data-table-scroll]</code> wrapper that IS the table's own scroll container (bounded height + <code>overflow: auto</code>) — never <code>position: fixed</code> to the viewport, and never a child of <code>&lt;table-ui&gt;</code> itself (it owns its own light DOM).</li>
+    <li>Selection count leads every bar. Group the count (+ optional controls) and the action buttons into two <code>&lt;toolbar-group-ui&gt;</code> atoms and set <code>&lt;toolbar-ui align="space-between"&gt;</code> to push the action group right — <strong>not</strong> a flex-grow <code>&lt;span&gt;</code> spacer or an auto margin on a content item. <code>&lt;toolbar-ui&gt;</code>'s overflow reflow sums each top-level child's rendered width to decide what fits; anything that absorbs free space (flex-grow, or an auto margin resolved to real pixels post-layout) has already expanded to fill that space by the time it's measured, so the sum always reads "full" and spuriously spills the trailing action(s) into an unreachable "more" menu — this is a real, previously-shipped bug in this pattern's own swap-variant demo (Delete was silently unreachable), fixed alongside the floating variant (gh#494 audit finding). <code>justify-content</code> only repositions flex items, never their widths, so it doesn't trip the same measurement. On the floating bar the count sits in an <code>aria-live="polite"</code> element so screen readers hear the running total; an optional <code>&lt;span data-bulk-controls&gt;</code> slot follows it for per-flow controls (e.g. a shared-rationale input) — empty by default.</li>
+    <li>Destructive actions go last and are visually separated with a <code>&lt;divider-ui vertical&gt;</code>. The floating bar additionally ends with an explicit Clear button (its own divider before it) — don't make "untick every row" the only way to dismiss it.</li>
     <li>Keep bulk actions to 3–5; overflow belongs in a <code>&lt;popover-ui&gt;</code> "More" menu trailing the divider.</li>
-    <li>Drive the swap from the table's <code>select</code> event (<code>detail.selected: number[]</code>) — toggle <code>hidden</code> on each toolbar; don't unmount.</li>
+    <li>Drive both variants from the table's <code>select</code> event (<code>detail.selected: number[]</code>) — don't unmount. The toolbar swap toggles <code>hidden</code>. The floating bar toggles <code>[data-open]</code>/<code>[data-closing]</code> instead — never <code>[hidden]</code>/<code>display:none</code>, which resets <code>&lt;toolbar-ui&gt;</code>'s overflow measurement to 0px and strands items in its "more" menu even once the bar has real width again. The floating bar additionally: never calls <code>.focus()</code> on appearance (no focus steal), and its <code>keydown</code> listener lives on the bar itself so Escape only clears selection while the bar owns focus.</li>
   </ul>
 </section>

package/patterns/bulk-action-toolbar/bulk-action-toolbar.examples.js

@@ -1,10 +1,13 @@
 /**
- * Bulk action toolbar — populates the demo table and wires the
- * selection-driven toolbar swap.
+ * Bulk action toolbar — populates the demo tables and wires both
+ * selection-driven variants: the top-anchored toolbar swap, and the
+ * bottom-anchored floating bar (gh#494).
  *
  * Default state shows <table-toolbar-ui> (Filter/Sort/Columns/Search,
- * wired via [for]). When rows are selected, swap to <toolbar-ui>
- * with the bulk actions; selection count anchors the left.
+ * wired via [for]). When rows are selected: the swap variant hides it
+ * for <toolbar-ui data-bulk-bar>; the floating variant leaves it
+ * visible and rises a <card-ui elevation="3"> bar from the bottom of
+ * the table's own scroll container.
  */
 
 const columns = [
@@ -26,7 +29,25 @@ const data = [
   { name: 'Hiring plan',      owner: 'Sarah Miller', status: 'Draft',    updated: '2 weeks ago' },
 ];
 
+// Floating-variant demo needs more rows than fit in the bounded
+// [data-table-scroll] height, so the scroll behavior (bar tracks the
+// table's own scroll box, not the page) is actually exercisable.
+const floatData = [
+  ...data,
+  { name: 'Vendor contracts', owner: 'James Park',   status: 'Active',   updated: '3 weeks ago' },
+  { name: 'Onboarding kit',   owner: 'Maria Lopez',  status: 'Draft',    updated: '1 month ago' },
+  { name: 'Security review',  owner: 'Alex Chen',    status: 'Active',   updated: '1 month ago' },
+  { name: 'Retro notes',      owner: 'Sarah Miller', status: 'Archived', updated: '2 months ago' },
+  { name: 'Budget draft',     owner: 'James Park',   status: 'Draft',    updated: '2 months ago' },
+  { name: 'Partner deck',     owner: 'Maria Lopez',  status: 'Active',   updated: '3 months ago' },
+];
+
 export default function setup(router) {
+  setupSwap(router);
+  setupFloating(router);
+}
+
+function setupSwap(router) {
   const table = router.querySelector('#pat-bulk-table');
   const tbar  = router.querySelector('#pat-bulk-default');
   const bulk  = router.querySelector('#pat-bulk-actions');
@@ -67,3 +88,61 @@ export default function setup(router) {
     table.clearSelection();
   });
 }
+
+function setupFloating(router) {
+  const table   = router.querySelector('#pat-bulk-float-table');
+  const tbar    = router.querySelector('#pat-bulk-float-default');
+  const bar     = router.querySelector('#pat-bulk-float-bar');
+  const countEl = bar?.querySelector('[data-bulk-float-count]');
+  if (!table || !tbar || !bar) return;
+
+  table.columns = columns;
+  table.data    = floatData;
+
+  // Enter/exit toggles [data-open]/[data-closing]; the CSS does the rest
+  // (packages/web-components/patterns/bulk-action-toolbar/bulk-action-toolbar.html),
+  // including the delayed `visibility: hidden` on close. Deliberately NOT
+  // [hidden]/display:none: toolbar-ui's spillover system measures its own
+  // width via ResizeObserver on first connect, and a display:none ancestor
+  // at that moment gives it a 0px reading it does not reliably re-measure
+  // later — items it moves to the "more" overflow menu at that 0px reading
+  // stay stuck there even once the bar has real width (found composing
+  // this pattern; not a toolbar-ui fix in scope here). `visibility` keeps
+  // the box laid out (real, measurable width) while still pulling it out
+  // of the a11y tree, tab order, and click target when closed. No
+  // .focus() call anywhere — appearance never steals focus.
+  function showBar() {
+    bar.removeAttribute('data-closing');
+    bar.setAttribute('data-open', '');
+  }
+
+  function hideBar() {
+    bar.setAttribute('data-closing', '');
+    bar.removeAttribute('data-open');
+  }
+
+  table.addEventListener('select', (e) => {
+    const n = e.detail?.selected?.length ?? 0;
+    if (countEl) countEl.textContent = String(n);
+    if (n > 0) showBar(); else hideBar();
+  });
+
+  // Escape clears selection ONLY when the bar owns focus — the listener
+  // lives on the bar itself so it only fires while focus is inside it,
+  // never as a page-wide Escape trap.
+  bar.addEventListener('keydown', (e) => {
+    if (e.key === 'Escape') {
+      e.stopPropagation();
+      table.clearSelection();
+    }
+  });
+
+  // Demo-only: both bulk-action buttons and the explicit Clear button
+  // release the selection so the floating bar's exit transition is
+  // exercisable from either affordance.
+  bar.addEventListener('press', (e) => {
+    const target = e.target?.closest?.('[data-bulk-clear], [data-bulk-action]');
+    if (!target) return;
+    table.clearSelection();
+  });
+}

package/patterns/bulk-action-toolbar/bulk-action-toolbar.html

@@ -10,10 +10,13 @@
   <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/check/check.css">
   <link rel="stylesheet" href="../../components/code/code.css">
   <link rel="stylesheet" href="../../components/divider/divider.css">
+  <link rel="stylesheet" href="../../components/icon/icon.css">
   <link rel="stylesheet" href="../../components/table/table.css">
   <link rel="stylesheet" href="../../components/table-toolbar/table-toolbar.css">
   <link rel="stylesheet" href="../../components/tag/tag.css">
@@ -21,19 +24,84 @@
   <link rel="stylesheet" href="../../components/toolbar/toolbar.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/check/check.js"></script>
   <script type="module" src="../../components/code/code.js"></script>
   <script type="module" src="../../components/divider/divider.js"></script>
+  <script type="module" src="../../components/icon/icon.js"></script>
   <script type="module" src="../../components/table/table.js"></script>
   <script type="module" src="../../components/table-toolbar/table-toolbar.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/toolbar/toolbar.js"></script>
 
+  <script type="module" src="../../core/icons-phosphor.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); }
+
+    /* ── Floating bulk-action bar (gh#494) ──
+       [data-table-scroll] IS the table's scroll container — bounded
+       height + overflow: auto — so `position: sticky` on the floating
+       bar pins it to THAT box's bottom edge, never the browser viewport.
+       This is the compose-from-primitives shape gh#495's anchored-surface
+       primitive would eventually own; card-ui + toolbar-ui + sticky
+       positioning gets there without it. */
+    [data-table-scroll] {
+      position: relative;
+      overflow: auto;
+      max-height: 16rem;
+    }
+    /* `width: fit-content` here would create a circular sizing trap:
+       toolbar-ui's own overflow reflow measures ITS available width from
+       this box, but this box's fit-content size would in turn be derived
+       from the toolbar's (possibly already-collapsed) rendered content —
+       a self-reinforcing collapse the first time reflow ever runs while
+       hidden (0 available width) spills items into the overflow popover.
+       A fixed `max-width` breaks the loop: the box's width is deterministic
+       (bounded by the scroll container, capped at 40rem), independent of
+       the toolbar's own spillover state. */
+    [data-bulk-bar-floating] {
+      position: sticky;
+      bottom: var(--a-space-3);
+      z-index: 1;
+      margin-inline: auto;
+      width: 100%;
+      max-width: min(46rem, calc(100% - var(--a-space-6)));
+      opacity: 0;
+      transform: translateY(0.75rem);
+      transition: opacity var(--a-duration) var(--a-easing-out),
+                  transform var(--a-duration) var(--a-easing-out),
+                  visibility 0s linear var(--a-duration);
+      /* `visibility`, not `[hidden]`/`display:none` — closed state still
+         has box + layout, kept out of the a11y tree + tab order + click
+         target instead. toolbar-ui's spillover system measures its own
+         width via ResizeObserver on first connect; a `display:none`
+         ancestor at that moment gives it a 0px reading it never reliably
+         re-measures after unhiding (observed empirically: items it moved
+         to the "more" overflow menu at that 0px reading stayed stuck
+         there even once the bar had 700px+ to work with). Never toggling
+         display avoids the trap entirely — no toolbar-ui change needed. */
+      visibility: hidden;
+    }
+    [data-bulk-bar-floating][data-open] {
+      opacity: 1;
+      transform: translateY(0);
+      visibility: visible;
+      transition: opacity var(--a-duration) var(--a-easing-out),
+                  transform var(--a-duration) var(--a-easing-out);
+    }
+    [data-bulk-bar-floating][data-closing] {
+      opacity: 0;
+      transform: translateY(0.75rem);
+    }
+
+    @media (prefers-reduced-motion: reduce) {
+      [data-bulk-bar-floating] { transition: none; }
+    }
   </style>
 </head>
 <body>

package/patterns/changelog-feed/changelog-feed.examples.html

@@ -18,7 +18,10 @@
   <p data-note>Section-grouped layout (GitHub / Linear convention): each release carries a version + date header, then per-section eyebrows (Added / Changed / Fixed / Deprecated / Removed) followed by bulleted prose. Sections are <em>grouped</em>, not tagged per row — variable tag widths break left-edge alignment of prose; eyebrow + bullets keep one consistent reading column.</p>
   <div data-artifact-container>
     <div data-artifact-item data-artifact-label="changelog feed — 3 releases">
-      <card-ui data-chunk="changelog-feed-basic" style="max-width: 640px;">
+      <card-ui data-chunk="changelog-feed-basic" data-chunk-kind="block"
+        data-chunk-domain="content"
+        data-chunk-description="Changelog feed card — 'What's new' releases in reverse order, each with version number, Latest tag, date, and categorized change entries (features, fixes) as text rows."
+        data-chunk-keywords="changelog whats-new releases feed version latest date features fixes updates notes product announcements" style="max-width: 640px;">
         <header>
           <span slot="heading" variant="section">What's new</span>
           <text-ui slot="description" color="subtle">3 releases in the last 30 days</text-ui>

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

@@ -22,7 +22,10 @@
   <p data-note>KPI + trend shape. Used in overview rows to show 4–6 metrics side-by-side.</p>
   <div data-artifact-container>
     <div data-artifact-item data-artifact-label="sparkline tile">
-      <card-ui data-chunk="chart-in-card-sparkline-tile" style="max-width:320px;">
+      <card-ui data-chunk="chart-in-card-sparkline-tile" data-chunk-kind="block"
+        data-chunk-domain="dashboard"
+        data-chunk-description="Sparkline metric tile — compact card with metric name, big current value (Page Views 84,232), and an edge-to-edge sparkline chart bleeding below."
+        data-chunk-keywords="sparkline tile metric card page-views value chart compact dashboard kpi trend mini analytics" style="max-width:320px;">
         <header>
           <span slot="heading"><h2>Page Views</h2></span>
           <text-ui slot="description" variant="title">84,232</text-ui>
@@ -40,7 +43,10 @@
   <p data-note>Chart as primary content. Header names the metric; footer adds a supporting action.</p>
   <div data-artifact-container>
     <div data-artifact-item data-artifact-label="full chart">
-      <card-ui data-chunk="chart-in-card-full-chart" style="max-width:520px;">
+      <card-ui data-chunk="chart-in-card-full-chart" data-chunk-kind="block"
+        data-chunk-domain="dashboard"
+        data-chunk-description="Full chart card — Revenue bar chart over the last 12 months with title and range description in the header and a stretch View-report footer button."
+        data-chunk-keywords="chart card bar revenue months report full analytics dashboard footer button range" style="max-width:520px;">
         <header>
           <span slot="heading"><h3>Revenue</h3></span>
           <text-ui slot="description" color="subtle">Last 12 months</text-ui>
@@ -61,7 +67,10 @@
   <p data-note>Stat in header pairs with the chart so the current value is legible before the chart renders.</p>
   <div data-artifact-container>
     <div data-artifact-item data-artifact-label="chart plus stat">
-      <card-ui data-chunk="chart-in-card-chart-plus-stat" style="max-width:520px;">
+      <card-ui data-chunk="chart-in-card-chart-plus-stat" data-chunk-kind="block"
+        data-chunk-domain="dashboard"
+        data-chunk-description="Stat-headed chart card — an MRR stat with change delta and trend arrow as the card header, over a smooth line chart of the metric's history."
+        data-chunk-keywords="chart stat card mrr line smooth trend delta header metric history dashboard analytics revenue" style="max-width:520px;">
         <header>
           <span slot="heading">
             <stat-ui label="MRR" value="$48,290" change="+12.4%" trend="up"></stat-ui>
@@ -80,7 +89,10 @@
   <p data-note>Chart shows aggregate; breakdown beneath gives the composition. Most SaaS "Overview" tiles follow this shape.</p>
   <div data-artifact-container>
     <div data-artifact-item data-artifact-label="chart plus breakdown">
-      <card-ui data-chunk="chart-in-card-chart-plus-breakdown" style="max-width:520px;">
+      <card-ui data-chunk="chart-in-card-chart-plus-breakdown" data-chunk-kind="block"
+        data-chunk-domain="dashboard"
+        data-chunk-description="Chart with breakdown card — Sessions bar chart for the week over a 3-up grid of stat tiles decomposing the total by segment (Desktop / Mobile / Tablet)."
+        data-chunk-keywords="chart breakdown card sessions bar stats grid desktop mobile tablet segments decomposition dashboard analytics" style="max-width:520px;">
         <header>
           <span slot="heading"><h3>Sessions</h3></span>
           <text-ui slot="description" color="subtle">This week</text-ui>
@@ -105,7 +117,10 @@
   <p data-note>Footer carries trend narrative + period caption using the new footer <code>heading</code> / <code>description</code> slot routing (symmetric with header). Shadcn-style revenue card translated to AdiaUI primitives.</p>
   <div data-artifact-container>
     <div data-artifact-item data-artifact-label="area chart + trend footer">
-      <card-ui data-chunk="chart-in-card-trend-footer" style="max-width:520px;">
+      <card-ui data-chunk="chart-in-card-trend-footer" data-chunk-kind="block"
+        data-chunk-domain="dashboard"
+        data-chunk-description="Area chart card with trend footer — Revenue area chart for a date range, footer states the takeaway ('Trending up by 5.2% this month') with a data-scope caption."
+        data-chunk-keywords="chart area card trend footer takeaway revenue range summary insight dashboard analytics" style="max-width:520px;">
         <header>
           <span slot="heading"><h3>Revenue</h3></span>
           <text-ui slot="description" color="subtle">January – March 2024</text-ui>
@@ -127,7 +142,10 @@
   <p data-note>Stat-ui's <code>chart</code> slot positions a sparkline to the right of the hero number — KPI and its trajectory as one visual unit.</p>
   <div data-artifact-container>
     <div data-artifact-item data-artifact-label="stat with sparkline slot">
-      <card-ui data-chunk="chart-in-card-stat-with-sparkline" style="max-width:320px;">
+      <card-ui data-chunk="chart-in-card-stat-with-sparkline" data-chunk-kind="block"
+        data-chunk-domain="dashboard"
+        data-chunk-description="Stat with inline sparkline — a single stat (Revenue $48.2k, +12.5% up) carrying a sparkline in its chart slot; the smallest chart-bearing KPI tile."
+        data-chunk-keywords="stat sparkline kpi tile revenue change trend inline chart slot compact dashboard metric" style="max-width:320px;">
         <section>
           <stat-ui label="Revenue" value="$48.2k" change="+12.5%" trend="up">
             <chart-ui id="pat-stat-spark" slot="chart" type="sparkline" x="month" y="value"></chart-ui>
@@ -143,7 +161,10 @@
   <p data-note>A <code>segmented-ui</code> in the header's <code>action</code> slot drives a time-range selection. Wire its <code>value</code> to refetch / slice the chart's <code>.data</code> via a controller.</p>
   <div data-artifact-container>
     <div data-artifact-item data-artifact-label="chart with 1w / 2w / 1m / 3m pills">
-      <card-ui data-chunk="chart-in-card-chart-with-filter-pills" style="max-width:520px;">
+      <card-ui data-chunk="chart-in-card-chart-with-filter-pills" data-chunk-kind="block"
+        data-chunk-domain="dashboard"
+        data-chunk-description="Chart card with range picker — Sessions chart whose header action is a segmented control of time ranges (1w / 2w / 1m / 3m) that filters the plotted window."
+        data-chunk-keywords="chart card segmented range picker filter pills time window sessions week month dashboard analytics toggle" style="max-width:520px;">
         <header>
           <span slot="heading"><h3>Sessions</h3></span>
           <segmented-ui slot="action" value="1m">