npm - @adia-ai/web-components - Versions diffs - 0.8.6 → 0.8.8 - Mend

@adia-ai/web-components 0.8.6 → 0.8.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (108) hide show

package/patterns/app-nav/app-nav.html ADDED Viewed

@@ -0,0 +1,50 @@
+<!DOCTYPE html>
+<html lang="en" theme="auto">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>App Nav (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/code/code.css">
+  <link rel="stylesheet" href="../../components/nav/nav.css">
+  <link rel="stylesheet" href="../../components/nav-group/nav-group.css">
+  <link rel="stylesheet" href="../../components/nav-item/nav-item.css">
+  <link rel="stylesheet" href="../../components/tag/tag.css">
+  <!-- Component JS -->
+  <script type="module" src="../../components/code/code.js"></script>
+  <script type="module" src="../../components/nav/nav.js"></script>
+  <script type="module" src="../../components/nav-group/nav-group.js"></script>
+  <script type="module" src="../../components/nav-item/nav-item.js"></script>
+  <script type="module" src="../../components/tag/tag.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('./app-nav.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 app-nav.examples.html — ${err.message}</p>`;
+      console.error('[app-nav.html]', err);
+    }
+  </script>
+</body>
+</html>

package/patterns/approvals/approvals.examples.html ADDED Viewed

@@ -0,0 +1,131 @@
+<header>
+  <div>
+    <h1>Approvals</h1>
+    <div data-actions>
+      <tag-ui size="sm">card-ui</tag-ui> <tag-ui size="sm">list-ui</tag-ui> <tag-ui size="sm">button-ui</tag-ui> <tag-ui size="sm">tag-ui</tag-ui> <tag-ui size="sm">avatar-ui</tag-ui>
+    </div>
+  </div>
+  <p>The queue + detail surface for items waiting on a human to approve, reject, or request changes — expense reports, PRs, access requests, content reviews. Always asynchronous; the approver sees a list and acts on each item independently.</p>
+</header>
+<section data-section data-property="when-to-use">
+  <h2 variant="section">When to use</h2>
+  <p data-note>
+    When work has to pause for a human gate. Distinct from confirms
+    (12e, blocking and sync) — approvals are out-of-band, batched,
+    and may carry a reviewer queue that the requester can see status
+    of but not skip.
+  </p>
+</section>
+<section data-section data-property="queue">
+  <h2 variant="section">Approval queue</h2>
+  <p data-note>List of pending items, most-urgent first. Each row carries the requester avatar + title + amount/scope + age + a pair of approve/reject buttons. Bulk select for batch approve.</p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label="approval queue">
+      <card-ui data-chunk="approvals-queue">
+        <header>
+          <span slot="heading" variant="section">Pending your approval</span>
+          <text-ui slot="description" color="subtle">5 items · 2 high priority</text-ui>
+          <button-ui slot="action" text="Approve all" variant="ghost" size="sm" icon-leading="check"></button-ui>
+        </header>
+        <section bleed>
+          <!-- Canonical list-item rows: text + slot="description" + slot="icon" +
+               slot="action". The action slot promotes the row to a 3-column grid
+               (icon | content | action) and right-aligns the action cluster, so
+               Reject/Approve land in a consistent trailing column across every
+               row regardless of the High badge. -->
+          <list-ui divider contained>
+            <list-item-ui text="Q2 onboarding budget — $48,000">
+              <avatar-ui slot="icon" size="sm" text="Jordan Lee"></avatar-ui>
+              <span slot="description">Jordan Lee · Engineering · 2 hours ago</span>
+              <row-ui slot="action" gap="2" align="center">
+                <tag-ui size="sm" variant="warning">High</tag-ui>
+                <button-ui text="Reject" variant="ghost" size="sm"></button-ui>
+                <button-ui text="Approve" variant="primary" size="sm" icon-leading="check"></button-ui>
+              </row-ui>
+            </list-item-ui>
+            <list-item-ui text="Vendor contract — Adobe Creative Cloud">
+              <avatar-ui slot="icon" size="sm" text="Avery Chen"></avatar-ui>
+              <span slot="description">Avery Chen · Design · 5 hours ago</span>
+              <row-ui slot="action" gap="2" align="center">
+                <button-ui text="Reject" variant="ghost" size="sm"></button-ui>
+                <button-ui text="Approve" variant="primary" size="sm" icon-leading="check"></button-ui>
+              </row-ui>
+            </list-item-ui>
+            <list-item-ui text="Access request — production database">
+              <avatar-ui slot="icon" size="sm" text="Sam Park"></avatar-ui>
+              <span slot="description">Sam Park · Data · 1 day ago</span>
+              <row-ui slot="action" gap="2" align="center">
+                <tag-ui size="sm" variant="warning">High</tag-ui>
+                <button-ui text="Reject" variant="ghost" size="sm"></button-ui>
+                <button-ui text="Approve" variant="primary" size="sm" icon-leading="check"></button-ui>
+              </row-ui>
+            </list-item-ui>
+            <list-item-ui text="Travel — SF → NYC, May 12–14">
+              <avatar-ui slot="icon" size="sm" text="Riley Tan"></avatar-ui>
+              <span slot="description">Riley Tan · Sales · 2 days ago</span>
+              <row-ui slot="action" gap="2" align="center">
+                <button-ui text="Reject" variant="ghost" size="sm"></button-ui>
+                <button-ui text="Approve" variant="primary" size="sm" icon-leading="check"></button-ui>
+              </row-ui>
+            </list-item-ui>
+          </list-ui>
+        </section>
+      </card-ui>
+    </div>
+  </div>
+</section>
+<section data-section data-property="detail">
+  <h2 variant="section">Approval detail</h2>
+  <p data-note>The single-item review surface. Header carries the request title + status + reviewer chain. Body shows the request data (line items / diff / metadata). Footer is a primary Approve, a secondary Reject, and a "Request changes" path for fixable issues.</p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label="approval detail">
+      <card-ui data-chunk="approvals-detail" style="max-width: 720px;">
+        <header>
+          <span slot="heading" variant="section">Q2 onboarding budget — $48,000</span>
+          <text-ui slot="description" color="subtle">Submitted by Jordan Lee · 2 hours ago</text-ui>
+          <tag-ui slot="action" variant="warning">Pending review</tag-ui>
+        </header>
+        <section>
+          <col-ui gap="3">
+            <description-list-ui>
+              <dt>Requester</dt><dd>Jordan Lee · Engineering Lead</dd>
+              <dt>Justification</dt><dd>Onboarding 4 new senior engineers in Q2; covers laptops, software licenses, training, and team setup costs.</dd>
+              <dt>Budget breakdown</dt><dd>Hardware $24k · Software $12k · Training $8k · Team setup $4k</dd>
+              <dt>Reviewer chain</dt><dd>You → CFO → CEO (auto-approve under $50k after CFO)</dd>
+            </description-list-ui>
+          </col-ui>
+        </section>
+        <footer divider>
+          <button-ui slot="action" text="Reject" variant="ghost"></button-ui>
+          <button-ui slot="action" text="Request changes" variant="ghost"></button-ui>
+          <button-ui slot="action" text="Approve" variant="primary" icon-leading="check"></button-ui>
+        </footer>
+      </card-ui>
+    </div>
+  </div>
+</section>
+<section data-section data-property="composition">
+  <h2 variant="section">Composition rules</h2>
+  <ul>
+    <li><strong>Approve is primary, not destructive</strong> — even when approval has financial weight, the reviewer's main job is to approve eligible items. Reject is the secondary action; type-to-confirm is reserved for irreversible terminal states (deny + lock).</li>
+    <li><strong>"Request changes" lives in the footer too</strong> — most rejected requests can be fixed and re-submitted. Surfacing the third path keeps the reviewer from forcing a binary outcome on a fixable issue.</li>
+    <li><strong>Show the reviewer chain</strong> — "You → CFO → CEO" sets the right expectation: this approval isn't terminal. Without the chain, requesters chase ghosts.</li>
+    <li><strong>Bulk approve only for low-stakes items</strong> — "Approve all" should be ghost-styled, not primary. The default is one-by-one because the queue is curated; if it isn't, fix the upstream policy.</li>
+    <li><strong>Pending status uses warning, not info</strong> — pending blocks downstream work. The queue should look like work, not a passive list.</li>
+  </ul>
+</section>
+<section data-section data-property="cross-references">
+  <h2 variant="section">See also</h2>
+  <ul>
+    <li><a href="/site/components/list">list-ui</a> · <a href="/site/components/list-item">list-item-ui</a> — queue row anatomy.</li>
+    <li><a href="/site/components/description-list">description-list-ui</a> — request metadata layout.</li>
+    <li><a href="/site/components/tag">tag-ui</a> — pending / approved / rejected status tags.</li>
+    <li><a href="/site/patterns/permissions-sharing">permissions-sharing</a> — adjacent pattern (access requests as a sub-flavor of approvals, see 33f).</li>
+    <li><a href="/site/patterns/bulk-action-toolbar">bulk-action-toolbar</a> — shared row-selection affordance for batched approvals.</li>
+  </ul>
+</section>

package/patterns/approvals/approvals.html ADDED Viewed

@@ -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>Approvals (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/avatar/avatar.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/description-list/description-list.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">
+  <!-- Component JS -->
+  <script type="module" src="../../components/avatar/avatar.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/description-list/description-list.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>
+  <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('./approvals.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 approvals.examples.html — ${err.message}</p>`;
+      console.error('[approvals.html]', err);
+    }
+  </script>
+</body>
+</html>

package/patterns/audit-log/audit-log.examples.html ADDED Viewed

@@ -0,0 +1,74 @@
+<header>
+  <div>
+    <h1>Audit log</h1>
+    <div data-actions>
+      <tag-ui size="sm">card-ui</tag-ui> <tag-ui size="sm">table-ui</tag-ui> <tag-ui size="sm">tag-ui</tag-ui> <tag-ui size="sm">select-ui</tag-ui> <tag-ui size="sm">input-ui</tag-ui>
+    </div>
+  </div>
+  <p>Timestamped actor / action / resource rows for compliance, security review, and operational tracing. table-ui carries the rows; tag-ui carries the action verb's severity; the card header carries filters. Distinct from <a href="/site/components/timeline">timeline-ui</a> (single-actor chronological events) and from <a href="/site/components/feed">feed-ui</a> (notifications / posts surface).</p>
+</header>
+<section data-section data-property="when-to-use">
+  <h2 variant="section">When to use</h2>
+  <p data-note>Multi-actor history needing scan + filter + occasional drill-down. Audit logs are compliance evidence: every row is a who / when / what / where on a single resource class. The table-ui format scales to thousands of rows + cursor pagination; if the use case is single-actor narrative or fewer than ~20 events, prefer timeline-ui.</p>
+</section>
+<section data-section data-property="basic">
+  <h2 variant="section">Basic — admin actions on workspace</h2>
+  <p data-note>Standard layout: title + filters in the header, table in a bleed section, footer carrying status + pagination. Action column uses a tag-ui colored by verb severity (success/warning/danger). Resource column uses code-ui for monospace IDs.</p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label="audit log — admin">
+      <card-ui data-chunk="audit-log-basic">
+        <header>
+          <span slot="heading" variant="section">Audit log</span>
+          <text-ui slot="description" color="subtle">Last 90 days · admin actions only</text-ui>
+          <row-ui slot="action" gap="2" align="center">
+            <select-ui name="actor" style="min-width: 8rem;">
+              <option value="">All actors</option>
+              <option value="kim">kim@example.com</option>
+              <option value="alex">alex@example.com</option>
+              <option value="bot">automation-bot</option>
+            </select-ui>
+            <select-ui name="verb" style="min-width: 8rem;">
+              <option value="">All actions</option>
+              <option value="create">create</option>
+              <option value="update">update</option>
+              <option value="delete">delete</option>
+            </select-ui>
+          </row-ui>
+        </header>
+        <section bleed>
+          <table-ui id="audit-log-table"></table-ui>
+        </section>
+        <footer divider>
+          <text-ui color="subtle" size="sm">Showing 8 of 247 events</text-ui>
+          <row-ui slot="action" gap="2">
+            <button-ui text="Export" variant="ghost" size="sm" icon-leading="download-simple"></button-ui>
+            <button-ui text="Load older" variant="ghost" size="sm"></button-ui>
+          </row-ui>
+        </footer>
+      </card-ui>
+    </div>
+  </div>
+</section>
+<section data-section data-property="composition">
+  <h2 variant="section">Composition rules</h2>
+  <ul>
+    <li><strong>table-ui driven by JS</strong> — never author <code>&lt;tbody&gt;</code>/<code>&lt;tr&gt;</code> in light DOM; the HTML parser foster-parents those out of custom elements. Set <code>[columns]</code> and <code>[data]</code> via the JS API (see audit-log.examples.js).</li>
+    <li><strong>Action verb gets a tag-ui</strong> — colored by severity: <code>create</code>/<code>update</code> = primary, <code>delete</code>/<code>revoke</code> = danger, <code>read</code>/<code>export</code> = muted. The color is the audit signal at a glance; never use uncolored text.</li>
+    <li><strong>Resource ID in native <code>&lt;code&gt;</code></strong> — monospace makes scanning vertically aligned IDs trivial. <code>&lt;code-ui&gt;</code> is the BLOCK component (CODE label + Copy chrome); for a table cell use the native inline element. Never truncate trailing chars (they're how the user disambiguates similar IDs).</li>
+    <li><strong>Time column is relative + absolute</strong> — "2 hours ago" with the absolute timestamp in a tooltip. Use relative-time-ui for the surface; copy the ISO string to clipboard on row click for forensic work.</li>
+    <li><strong>IP / user-agent column is hidden by default</strong> — too wide for the scan layout. Surface in a row-detail drawer (drawer-ui) or per-row "Details" affordance, not as a primary column.</li>
+    <li><strong>Pagination is cursor-based</strong> — "Load older" appends rather than swaps pages. Audit logs grow append-only; the user is typically scrolling backward in time, not jumping to page 47.</li>
+  </ul>
+</section>
+<section data-section data-property="cross-references">
+  <h2 variant="section">Cross-references</h2>
+  <ul>
+    <li><a href="/site/components/table">table-ui</a> · <a href="/site/components/tag">tag-ui</a> · <a href="/site/components/relative-time">relative-time-ui</a> — primitives composed here.</li>
+    <li><a href="/site/components/timeline">timeline-ui</a> — single-actor chronological event log alternative.</li>
+    <li><a href="/site/patterns/export-flow">export-flow</a> — the "Export" affordance in the footer wires to this pattern.</li>
+  </ul>
+</section>

package/patterns/audit-log/audit-log.examples.js ADDED Viewed

@@ -0,0 +1,60 @@
+/** Audit-log pattern — populate table-ui via [columns] with col.render functions. */
+const VERB_TONE = {
+  create:  'primary',
+  update:  'primary',
+  delete:  'danger',
+  revoke:  'danger',
+  rotate:  'warning',
+  export:  'muted',
+  read:    'muted',
+  login:   'muted',
+};
+const ROWS = [
+  { time: '2 minutes ago',  actor: 'kim@example.com',    verb: 'delete',  resource: 'api_key_sk_live_…A4F2',   ip: '10.0.4.21' },
+  { time: '14 minutes ago', actor: 'alex@example.com',   verb: 'update',  resource: 'workspace_settings',     ip: '10.0.4.88' },
+  { time: '47 minutes ago', actor: 'automation-bot',     verb: 'export',  resource: 'invoices.2024-q4.csv',   ip: '127.0.0.1' },
+  { time: '1 hour ago',     actor: 'alex@example.com',   verb: 'create',  resource: 'webhook_evt_92h2k',      ip: '10.0.4.88' },
+  { time: '2 hours ago',    actor: 'kim@example.com',    verb: 'rotate',  resource: 'api_key_sk_live_…9821',  ip: '10.0.4.21' },
+  { time: '4 hours ago',    actor: 'kim@example.com',    verb: 'login',   resource: 'session_a4e8f0',         ip: '10.0.4.21' },
+  { time: 'Yesterday',      actor: 'alex@example.com',   verb: 'revoke',  resource: 'invite_inv_3kf02',       ip: '10.0.4.88' },
+  { time: '2 days ago',     actor: 'automation-bot',     verb: 'read',    resource: 'audit_log',              ip: '127.0.0.1' },
+];
+const escape = (s) => String(s ?? '').replace(/[&<>"']/g, (c) => (
+  { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]
+));
+export default function setup(router) {
+  const root = (router?.querySelector?.('#audit-log-table')) || document.querySelector('#audit-log-table');
+  if (!root) return;
+  root.columns = [
+    { key: 'time',  label: 'When',  align: 'left' },
+    {
+      key: 'actor', label: 'Actor', align: 'left',
+      render: (v) => {
+        const initial = (v[0] || '?').toUpperCase();
+        return `<span style="display:inline-flex;align-items:center;gap:.5rem;">
+          <avatar-ui size="sm" text="${escape(initial)}" color="muted"></avatar-ui>
+          <span>${escape(v)}</span>
+        </span>`;
+      },
+    },
+    {
+      key: 'verb', label: 'Action', align: 'left',
+      render: (v) => {
+        const tone = VERB_TONE[v] || 'muted';
+        return `<tag-ui size="sm" variant="${tone}">${escape(v)}</tag-ui>`;
+      },
+    },
+    {
+      key: 'resource', label: 'Resource', align: 'left',
+      // Native <code> for inline monospace — code-ui is the BLOCK component
+      // (CODE label + Copy header chrome) which is wrong for a table cell.
+      render: (v) => `<code>${escape(v)}</code>`,
+    },
+    { key: 'ip', label: 'IP', align: 'left' },
+  ];
+  root.data = ROWS;
+}

package/patterns/audit-log/audit-log.html ADDED Viewed

@@ -0,0 +1,63 @@
+<!DOCTYPE html>
+<html lang="en" theme="auto">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Audit log (pattern) — AdiaUI</title>
+  <link rel="stylesheet" href="../../styles/resets.css">
+  <link rel="stylesheet" href="../../styles/tokens.css">
+  <link rel="stylesheet" href="../../components/avatar/avatar.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/code/code.css">
+  <link rel="stylesheet" href="../../components/field/field.css">
+  <link rel="stylesheet" href="../../components/icon/icon.css">
+  <link rel="stylesheet" href="../../components/input/input.css">
+  <link rel="stylesheet" href="../../components/row/row.css">
+  <link rel="stylesheet" href="../../components/select/select.css">
+  <link rel="stylesheet" href="../../components/table/table.css">
+  <link rel="stylesheet" href="../../components/tag/tag.css">
+  <link rel="stylesheet" href="../../components/text/text.css">
+  <script type="module" src="../../components/avatar/avatar.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/code/code.js"></script>
+  <script type="module" src="../../components/field/field.js"></script>
+  <script type="module" src="../../components/icon/icon.js"></script>
+  <script type="module" src="../../components/input/input.js"></script>
+  <script type="module" src="../../components/row/row.js"></script>
+  <script type="module" src="../../components/select/select.js"></script>
+  <script type="module" src="../../components/table/table.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('./audit-log.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 audit-log.examples.html — ${err.message}</p>`;
+      console.error('[audit-log.html]', err);
+    }
+  </script>
+</body>
+</html>

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

@@ -0,0 +1,89 @@
+<header>
+  <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>
+    </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>
+</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>
+</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>
+  <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>
+      </toolbar-ui>
+      <table-ui id="pat-bulk-table" selectable sortable striped></table-ui>
+    </section>
+  </card-ui>
+</section>
+<section data-section data-property="anatomy">
+  <h2 variant="section">Anatomy</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;/toolbar-ui&gt;
+    &lt;table-ui id="resources" selectable sortable&gt;&lt;/table-ui&gt;
+  &lt;/section&gt;
+&lt;/card-ui&gt;</code-ui>
+  <code-ui language="javascript">// Wire the swap. table-ui dispatches 'select' with detail.selected (number[]).
+const table   = document.getElementById('resources');
+const tbar    = document.querySelector('table-toolbar-ui');
+const bulk    = document.querySelector('[data-bulk-bar]');
+const countEl = bulk.querySelector('[data-bulk-count]');
+table.addEventListener('select', (e) =&gt; {
+  const n = e.detail.selected?.length ?? 0;
+  countEl.textContent = String(n);
+  tbar.hidden  = n &gt; 0;
+  bulk.hidden  = n === 0;
+});</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>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>
+  </ul>
+</section>

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

@@ -0,0 +1,69 @@
+/**
+ * Bulk action toolbar — populates the demo table and wires the
+ * selection-driven toolbar swap.
+ *
+ * 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.
+ */
+const columns = [
+  { key: 'name',   label: 'Name',   sortable: true, flex: 2 },
+  { key: 'owner',  label: 'Owner',  sortable: true, flex: 1 },
+  { key: 'status', label: 'Status', sortable: true, flex: 1, render: (val) => {
+    const v = { Active: 'success', Draft: 'muted', Archived: 'warning' }[val] || '';
+    return `<badge-ui text="${val}" variant="${v}"></badge-ui>`;
+  }},
+  { key: 'updated', label: 'Updated', sortable: true, flex: 1 },
+];
+const data = [
+  { name: 'Q4 roadmap',       owner: 'Alex Chen',    status: 'Active',   updated: '2 hours ago' },
+  { name: 'Design review',    owner: 'Sarah Miller', status: 'Active',   updated: '5 hours ago' },
+  { name: 'Brand guidelines', owner: 'James Park',   status: 'Draft',    updated: 'Yesterday' },
+  { name: 'Launch checklist', owner: 'Maria Lopez',  status: 'Archived', updated: '3 days ago' },
+  { name: 'API v2 spec',      owner: 'Alex Chen',    status: 'Active',   updated: '1 week ago' },
+  { name: 'Hiring plan',      owner: 'Sarah Miller', status: 'Draft',    updated: '2 weeks ago' },
+];
+export default function setup(router) {
+  const table = router.querySelector('#pat-bulk-table');
+  const tbar  = router.querySelector('#pat-bulk-default');
+  const bulk  = router.querySelector('#pat-bulk-actions');
+  if (!table || !tbar || !bulk) return;
+  table.columns = columns;
+  table.data    = data;
+  // Match the bulk-action toolbar height + horizontal alignment to
+  // <table-toolbar-ui>'s default variant so the swap is seamless.
+  // table-toolbar-ui ships --table-toolbar-py: var(--a-space-2) and
+  // --table-toolbar-px: 0 (alignment to flush table cells in a bleed
+  // section). Mirror those on the toolbar-ui that swaps in. Set via
+  // setProperty rather than an inline <style> block — pattern pages
+  // adjacent to harvest pages get the same "JS hydration is fine,
+  // styling stored in HTML is not" treatment by default.
+  bulk.style.setProperty('--toolbar-py',  'var(--a-space-2)');
+  bulk.style.setProperty('--toolbar-px',  '0');
+  bulk.style.setProperty('--toolbar-gap', 'var(--a-space-2)');
+  const countEl = bulk.querySelector('[data-bulk-count]');
+  table.addEventListener('select', (e) => {
+    const n = e.detail?.selected?.length ?? 0;
+    if (countEl) countEl.textContent = String(n);
+    tbar.hidden = n > 0;
+    bulk.hidden = n === 0;
+  });
+  // Demo-only: bulk-action buttons return the table to default-toolbar
+  // state so the swap is exercisable in both directions. Uses the
+  // public clearSelection() method (added 2026-04-29) — used to require
+  // re-assigning `data` to trigger the internal #selected.clear() side
+  // effect, but the symmetric API now exists.
+  bulk.addEventListener('press', (e) => {
+    const target = e.target?.closest?.('[data-bulk-action]');
+    if (!target) return;
+    table.clearSelection();
+  });
+}