@adia-ai/web-components 0.8.6 → 0.8.7

package/patterns/overview/overview.examples.html

@@ -0,0 +1,119 @@
+<header>
+    <div>
+      <h1>Patterns</h1>
+    </div>
+    <p>Reusable compositions that solve common UI problems — from app shells to data tables, permissions grids, and AI agent surfaces.</p>
+  </header>
+
+<section data-section data-property="what-are-patterns">
+  <h2 variant="section">What are patterns</h2>
+  <p data-note>Patterns are two things simultaneously: <strong>shell elements</strong> (web components that coordinate multiple child regions) and <strong>composition recipes</strong> (documented HTML structures that show how to assemble primitives for a specific problem).</p>
+  <p>Shell elements (<code>admin-shell</code>, <code>chat-shell</code>, <code>editor-shell</code>) stamp no markup — they orchestrate behaviors CSS alone cannot: resize observers, keyboard routing, panel toggling, state sync. You author the HTML; the pattern wires the JavaScript. Composition recipes are documented in the /site/patterns/ pages and serve as copy-paste starting points.</p>
+</section>
+
+<section data-section data-property="decision-matrix">
+  <h2 variant="section">Decision matrix</h2>
+  <p data-note>Start here. Find your intent, go straight to the pattern.</p>
+  <table>
+    <thead><tr><th>I need to build…</th><th>Pattern</th></tr></thead>
+    <tbody>
+      <tr><td colspan="2" style="background:var(--a-canvas-1);font-weight:600;font-size:var(--a-ui-sm);color:var(--a-fg-muted);letter-spacing:.04em;text-transform:uppercase;">App Shells</td></tr>
+      <tr><td>A full admin SaaS app (sidebar + topbar + content + statusbar)</td><td><a href="/site/patterns/admin-shell">admin-shell</a></td></tr>
+      <tr><td>A chat interface with history, input, and streaming responses</td><td><a href="/site/patterns/chat-shell">chat-shell</a></td></tr>
+      <tr><td>A design-tool shell (canvas + navigator + inspector panes)</td><td><a href="/site/patterns/editor-shell">editor-shell</a></td></tr>
+      <tr><td>A sidebar that collapses to a drawer at narrow viewports</td><td><a href="/site/patterns/responsive-shell-sidebar">responsive-shell-sidebar</a></td></tr>
+      <tr><td>App navigation: sidebar rail, grouped nav, sub-nav, collapsible</td><td><a href="/site/patterns/app-nav">app-nav</a></td></tr>
+
+      <tr><td colspan="2" style="background:var(--a-canvas-1);font-weight:600;font-size:var(--a-ui-sm);color:var(--a-fg-muted);letter-spacing:.04em;text-transform:uppercase;">Data &amp; Tables</td></tr>
+      <tr><td>A data table with inline editing and tree/expand rows</td><td><a href="/site/patterns/data-tables-inline-edit-and-tree">data-tables-inline-edit-and-tree</a></td></tr>
+      <tr><td>A kanban board with draggable cards and column swim lanes</td><td><a href="/site/patterns/kanban-board">kanban-board</a></td></tr>
+      <tr><td>Bulk actions toolbar for selected rows (delete, export, move)</td><td><a href="/site/patterns/bulk-action-toolbar">bulk-action-toolbar</a></td></tr>
+      <tr><td>A filter bar above a list or table (multi-facet, chips, clear-all)</td><td><a href="/site/patterns/filter-bar">filter-bar</a></td></tr>
+      <tr><td>Search with result previews, categories, recent, and suggestions</td><td><a href="/site/patterns/search-discovery">search-discovery</a></td></tr>
+      <tr><td>A chart embedded inside a card (KPI, sparkline, summary)</td><td><a href="/site/patterns/chart-in-card">chart-in-card</a></td></tr>
+      <tr><td>A conversion funnel visualization</td><td><a href="/site/patterns/conversion-funnel">conversion-funnel</a></td></tr>
+      <tr><td>A retention / cohort heatmap</td><td><a href="/site/patterns/retention-cohort">retention-cohort</a></td></tr>
+
+      <tr><td colspan="2" style="background:var(--a-canvas-1);font-weight:600;font-size:var(--a-ui-sm);color:var(--a-fg-muted);letter-spacing:.04em;text-transform:uppercase;">Forms &amp; Wizards</td></tr>
+      <tr><td>A form layout (field groups, sections, submit/cancel footer)</td><td><a href="/site/patterns/form-system">form-system</a></td></tr>
+      <tr><td>A form inside a drawer (side panel form, quick-edit)</td><td><a href="/site/patterns/form-drawer">form-drawer</a></td></tr>
+      <tr><td>Conditional form fields, dependent selects, autocomplete inputs</td><td><a href="/site/patterns/forms-conditional-and-autocomplete">forms-conditional-and-autocomplete</a></td></tr>
+      <tr><td>A multi-step wizard or onboarding flow in a drawer</td><td><a href="/site/patterns/wizard-drawer">wizard-drawer</a></td></tr>
+
+      <tr><td colspan="2" style="background:var(--a-canvas-1);font-weight:600;font-size:var(--a-ui-sm);color:var(--a-fg-muted);letter-spacing:.04em;text-transform:uppercase;">Permissions &amp; Access</td></tr>
+      <tr><td>A permissions grid (role × resource matrix)</td><td><a href="/site/patterns/permissions-matrix">permissions-matrix</a></td></tr>
+      <tr><td>A role picker (assign roles to users)</td><td><a href="/site/patterns/permissions-role-picker">permissions-role-picker</a></td></tr>
+      <tr><td>Sharing / collaborator management (invite, revoke, change level)</td><td><a href="/site/patterns/permissions-sharing">permissions-sharing</a></td></tr>
+      <tr><td>Access requests (request → review → approve / deny flow)</td><td><a href="/site/patterns/access-requests">access-requests</a></td></tr>
+      <tr><td>API key management + data export controls</td><td><a href="/site/patterns/admin-keys-and-export">admin-keys-and-export</a></td></tr>
+
+      <tr><td colspan="2" style="background:var(--a-canvas-1);font-weight:600;font-size:var(--a-ui-sm);color:var(--a-fg-muted);letter-spacing:.04em;text-transform:uppercase;">Records &amp; Review</td></tr>
+      <tr><td>A record detail view in a side drawer</td><td><a href="/site/patterns/record-detail-drawer">record-detail-drawer</a></td></tr>
+      <tr><td>An approval workflow (request → reviewers → decision)</td><td><a href="/site/patterns/approvals">approvals</a></td></tr>
+      <tr><td>A diff view (code or content before/after comparison)</td><td><a href="/site/patterns/diff-review">diff-review</a></td></tr>
+      <tr><td>Comments, mentions, threaded replies, reactions</td><td><a href="/site/patterns/comments-and-collaboration">comments-and-collaboration</a></td></tr>
+      <tr><td>A public profile page with verification badges</td><td><a href="/site/patterns/profile-public-and-verification">profile-public-and-verification</a></td></tr>
+
+      <tr><td colspan="2" style="background:var(--a-canvas-1);font-weight:600;font-size:var(--a-ui-sm);color:var(--a-fg-muted);letter-spacing:.04em;text-transform:uppercase;">AI &amp; Agent Surfaces</td></tr>
+      <tr><td>Display LLM token usage and cost per request</td><td><a href="/site/patterns/agent-cost">agent-cost</a></td></tr>
+      <tr><td>Show the agent's memory / context window state</td><td><a href="/site/patterns/agent-memory">agent-memory</a></td></tr>
+      <tr><td>A prompt library with save, search, and insert</td><td><a href="/site/patterns/agent-prompt-library">agent-prompt-library</a></td></tr>
+      <tr><td>Display tool calls the agent made (name, args, result)</td><td><a href="/site/patterns/agent-tool-call">agent-tool-call</a></td></tr>
+
+      <tr><td colspan="2" style="background:var(--a-canvas-1);font-weight:600;font-size:var(--a-ui-sm);color:var(--a-fg-muted);letter-spacing:.04em;text-transform:uppercase;">Communication &amp; Notifications</td></tr>
+      <tr><td>Notification bell with badge + dropdown digest</td><td><a href="/site/patterns/notifications-bell-and-digest">notifications-bell-and-digest</a></td></tr>
+      <tr><td>System-wide banners (announcements, maintenance, warnings)</td><td><a href="/site/patterns/system-banners">system-banners</a></td></tr>
+
+      <tr><td colspan="2" style="background:var(--a-canvas-1);font-weight:600;font-size:var(--a-ui-sm);color:var(--a-fg-muted);letter-spacing:.04em;text-transform:uppercase;">Marketing &amp; Public</td></tr>
+      <tr><td>Marketing sections (hero, pricing, CTA, testimonials)</td><td><a href="/site/patterns/marketing-engagement">marketing-engagement</a></td></tr>
+    </tbody>
+  </table>
+</section>
+
+<section data-section data-property="pattern-vs-component">
+  <h2 variant="section">Pattern vs Component</h2>
+  <table>
+    <thead><tr><th></th><th>Component</th><th>Pattern</th></tr></thead>
+    <tbody>
+      <tr><td>Renders UI</td><td>Yes — light DOM, <code>@scope</code>-isolated CSS, slots</td><td>Shell elements orchestrate author-supplied HTML; composition recipes are documented starting points</td></tr>
+      <tr><td>Scope</td><td>Single element</td><td>Coordinates multiple elements via slots and <code>data-*</code> roles</td></tr>
+      <tr><td>Examples</td><td><code>button-ui</code>, <code>card-ui</code>, <code>modal-ui</code></td><td><code>admin-shell</code>, <code>kanban-board</code> recipe, <code>permissions-matrix</code> recipe</td></tr>
+      <tr><td>Customization</td><td>Attributes, slots, CSS custom properties</td><td>HTML structure, <code>data-*</code> region markers, slot vocabulary</td></tr>
+    </tbody>
+  </table>
+</section>
+
+<section data-section data-property="usage">
+  <h2 variant="section">Using a shell pattern</h2>
+  <p data-note>Shell elements stamp no HTML — you author the structure; the element wires the behavior.</p>
+  <code-ui language="html">&lt;admin-shell mode="rounded"&gt;
+  &lt;admin-sidebar slot="leading" resizable collapsible&gt;
+    &lt;admin-topbar slot="header"&gt;
+      &lt;span slot="heading"&gt;My App&lt;/span&gt;
+    &lt;/admin-topbar&gt;
+    &lt;section-ui&gt;
+      &lt;nav-ui&gt;
+        &lt;nav-item-ui icon="house" text="Dashboard" selected&gt;&lt;/nav-item-ui&gt;
+        &lt;nav-item-ui icon="gear" text="Settings"&gt;&lt;/nav-item-ui&gt;
+      &lt;/nav-ui&gt;
+    &lt;/section-ui&gt;
+  &lt;/admin-sidebar&gt;
+
+  &lt;admin-content&gt;
+    &lt;admin-topbar&gt;
+      &lt;button-ui data-sidebar-toggle="leading" icon="sidebar" variant="ghost" size="sm"&gt;&lt;/button-ui&gt;
+      &lt;breadcrumb-ui&gt;&lt;span&gt;Dashboard&lt;/span&gt;&lt;/breadcrumb-ui&gt;
+    &lt;/admin-topbar&gt;
+    &lt;admin-scroll&gt;
+      &lt;admin-page&gt;
+        &lt;admin-page-header&gt;
+          &lt;header&gt;&lt;div&gt;&lt;h1&gt;Dashboard&lt;/h1&gt;&lt;/div&gt;&lt;/header&gt;
+        &lt;/admin-page-header&gt;
+        &lt;admin-page-body&gt;
+          &lt;section&gt;&lt;!-- page content --&gt;&lt;/section&gt;
+        &lt;/admin-page-body&gt;
+      &lt;/admin-page&gt;
+    &lt;/admin-scroll&gt;
+  &lt;/admin-content&gt;
+&lt;/admin-shell&gt;</code-ui>
+</section>

package/patterns/overview/overview.html

@@ -0,0 +1,42 @@
+<!DOCTYPE html>
+<html lang="en" theme="auto">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Patterns (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">
+
+  <!-- Component JS -->
+  <script type="module" src="../../components/code/code.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('./overview.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 overview.examples.html — ${err.message}</p>`;
+      console.error('[overview.html]', err);
+    }
+  </script>
+
+</body>
+</html>

package/patterns/permissions-matrix/permissions-matrix.examples.html

@@ -0,0 +1,91 @@
+<header>
+  <div>
+    <h1>Permission Matrix</h1>
+    <div data-actions>
+      <tag-ui size="sm">card-ui</tag-ui> <tag-ui size="sm">table-ui</tag-ui> <tag-ui size="sm">check-ui</tag-ui> <tag-ui size="sm">description-list-ui</tag-ui> <tag-ui size="sm">tag-ui</tag-ui>
+    </div>
+  </div>
+  <p>The full RBAC grid — capabilities (rows) × roles (columns), check-mark cells indicating which role grants which capability. Two shapes: an editable grid for custom roles (admin authoring), and a read-only summary card showing one role's permissions in plain language.</p>
+</header>
+
+<section data-section data-property="when-to-use">
+  <h2 variant="section">When to use</h2>
+  <p data-note>
+    Reach for the matrix when the role count exceeds the rich-picker
+    sweet spot (~5) or when permissions are configurable. For built-in
+    roles only, the summary view is enough — the matrix is the
+    authoring surface, the summary is the runtime surface.
+  </p>
+</section>
+
+<section data-section data-property="grid">
+  <h2 variant="section">Editable matrix</h2>
+  <p data-note>Capability per row, role per column, <code>check-ui</code> in each cell. Built-in roles (Viewer / Member / Admin / Owner) render <code>disabled</code> — they reflect the role's permissions but can't be edited from this surface. The <em>Custom</em> column is the authoring affordance: cells there toggle freely and save on change.</p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label="permission matrix grid">
+      <card-ui data-chunk="permissions-matrix-grid" data-perm-card>
+        <header>
+          <span slot="heading" variant="section">Permissions</span>
+          <text-ui slot="description" color="subtle">Changes save automatically</text-ui>
+          <button-ui slot="action" text="Add custom role" variant="ghost" size="sm" icon-leading="plus"></button-ui>
+        </header>
+        <section bleed>
+          <table-ui id="pat-perm-matrix"></table-ui>
+        </section>
+        <footer divider>
+          <text-ui slot="description" color="subtle" size="sm">Built-in roles are read-only. The Custom column is editable.</text-ui>
+        </footer>
+      </card-ui>
+    </div>
+  </div>
+</section>
+
+<section data-section data-property="summary">
+  <h2 variant="section">Read-only role summary</h2>
+  <p data-note>One card per role; <code>description-list-ui</code> with capability category as term, list of capabilities as description. Inline tag indicates whether the role is built-in or custom.</p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label="role summary card">
+      <card-ui data-chunk="permissions-matrix-summary" data-perm-summary>
+        <header>
+          <span slot="heading" variant="section">Admin</span>
+          <text-ui slot="description" color="subtle">Built-in role · 3 members</text-ui>
+          <tag-ui slot="action" variant="accent" size="sm">Built-in</tag-ui>
+        </header>
+        <section>
+          <description-list-ui>
+            <span slot="term">Content</span>
+            <span slot="description">Read · Comment · Edit own</span>
+            <span slot="term">Members</span>
+            <span slot="description">Manage members (invite, change role, remove)</span>
+            <span slot="term">Workspace</span>
+            <span slot="description">All settings except deletion (Owner only)</span>
+          </description-list-ui>
+        </section>
+        <footer divider>
+          <button-ui slot="action" text="View matrix" variant="ghost" size="sm" icon-trailing="arrow-right"></button-ui>
+        </footer>
+      </card-ui>
+    </div>
+  </div>
+</section>
+
+<section data-section data-property="composition">
+  <h2 variant="section">Composition rules</h2>
+  <ul>
+    <li><strong>Group capabilities by resource</strong>, not alphabetically — "Members: invite / remove / change role" reads cleaner than three rows scattered.</li>
+    <li><strong>Built-in role columns are <code>disabled</code></strong> — their cells reflect each role's permissions but can't be edited from the matrix. Owner is always fully checked; the others vary.</li>
+    <li><strong>The Custom column is the editable surface</strong> — that's where the matrix earns its keep over a role-picker. New custom roles append a column to the right.</li>
+    <li><strong>Auto-save, don't queue</strong> — checkboxes are atomic decisions; a "Save" button at the bottom invites batching errors.</li>
+    <li><strong>Use the summary view in tooltips</strong> — when a user hovers a role tag in a members table, surface the summary card via popover; don't make them click through to settings.</li>
+  </ul>
+</section>
+
+<section data-section data-property="cross-references">
+  <h2 variant="section">See also</h2>
+  <ul>
+    <li><a href="/site/components/table">table-ui</a> — grid primitive used for the matrix.</li>
+    <li><a href="/site/components/check">check-ui</a> — cell primitive (auto-rendered by <code>type: 'boolean'</code> columns).</li>
+    <li><a href="/site/components/description-list">description-list-ui</a> — summary card layout.</li>
+    <li><a href="/site/patterns/permissions-role-picker">permissions-role-picker</a> — sibling for role assignment.</li>
+  </ul>
+</section>

package/patterns/permissions-matrix/permissions-matrix.examples.js

@@ -0,0 +1,28 @@
+/** Permissions Matrix pattern — capability rows × role columns. */
+
+const renderEditable = (v) =>
+  `<check-ui ${v ? 'checked' : ''}></check-ui>`;
+
+const columns = [
+  { key: 'capability', label: 'Capability', width: 220 },
+  { key: 'viewer',  label: 'Viewer',  type: 'boolean', width: 90 },
+  { key: 'member',  label: 'Member',  type: 'boolean', width: 90 },
+  { key: 'admin',   label: 'Admin',   type: 'boolean', width: 90 },
+  { key: 'owner',   label: 'Owner',   type: 'boolean', width: 90 },
+  { key: 'custom',  label: 'Custom',  align: 'center', width: 90, render: renderEditable },
+];
+
+const data = [
+  { capability: 'Read content',       viewer: true,  member: true,  admin: true,  owner: true, custom: true  },
+  { capability: 'Comment on content', viewer: false, member: true,  admin: true,  owner: true, custom: true  },
+  { capability: 'Edit own content',   viewer: false, member: true,  admin: true,  owner: true, custom: false },
+  { capability: 'Manage members',     viewer: false, member: false, admin: true,  owner: true, custom: false },
+  { capability: 'Delete workspace',   viewer: false, member: false, admin: false, owner: true, custom: false },
+];
+
+export default function setup(router) {
+  const table = router.querySelector('#pat-perm-matrix');
+  if (!table) return;
+  table.columns = columns;
+  table.data = data;
+}

package/patterns/permissions-matrix/permissions-matrix.html

@@ -0,0 +1,56 @@
+<!DOCTYPE html>
+<html lang="en" theme="auto">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Permission Matrix (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/description-list/description-list.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">
+
+  <!-- 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/description-list/description-list.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('./permissions-matrix.examples.html');
+      if (!res.ok) throw new Error(`fetch failed (${res.status})`);
+      root.innerHTML = await res.text();
+      try {
+        const mod = await import(/* @vite-ignore */ './permissions-matrix.examples.js');
+        mod.default?.(root);
+      } catch (e) { console.error('[permissions-matrix.html] setup failed:', e); }
+    } catch (err) {
+      root.innerHTML = `<p style="color:var(--a-danger-strong);">Failed to load permissions-matrix.examples.html — ${err.message}</p>`;
+      console.error('[permissions-matrix.html]', err);
+    }
+  </script>
+
+</body>
+</html>

package/patterns/permissions-role-picker/permissions-role-picker.examples.html

@@ -0,0 +1,81 @@
+<header>
+  <div>
+    <h1>Permissions Role Picker</h1>
+    <div data-actions>
+      <tag-ui size="sm">option-card-ui</tag-ui> <tag-ui size="sm">radio-ui</tag-ui> <tag-ui size="sm">select-ui</tag-ui> <tag-ui size="sm">field-ui</tag-ui>
+    </div>
+  </div>
+  <p>Surface for assigning a role — at invite time, when promoting an existing member, or when editing a row in a members table. Two shapes: a rich radio group with role descriptions (settings-page or invite flow), and a compact select for inline edits inside a member row.</p>
+</header>
+
+<section data-section data-property="when-to-use">
+  <h2 variant="section">When to use</h2>
+  <p data-note>
+    Use the rich radio group when the user is making a deliberate
+    role decision — invite, promotion, role change inside a drawer.
+    Use the compact select when the role is a column inside a table
+    and the user is sweeping through many rows. Both pull from the
+    same role list, but the surfaces have different rhythms.
+  </p>
+</section>
+
+<section data-section data-property="radio">
+  <h2 variant="section">Rich radio group</h2>
+  <p data-note>Each role gets an <code>option-card-ui</code> with name, one-line description, and (optionally) a "recommended" badge. Default selection lands on the lowest-privilege role — promote-by-decision, not by accident.</p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label="rich role picker">
+      <field-ui data-chunk="permissions-role-picker-radio" label="Role" hint="Members can be promoted to admin later by any owner.">
+        <col-ui gap="2">
+          <option-card-ui name="role" value="viewer" heading="Viewer" description="Can read everything; cannot edit, comment, or share."></option-card-ui>
+          <option-card-ui name="role" value="member" heading="Member" description="Can edit content they own and comment on anything." checked></option-card-ui>
+          <option-card-ui name="role" value="admin" description="Can manage members, billing, and integrations.">
+            <span slot="heading">Admin <tag-ui size="sm">Recommended for leads</tag-ui></span>
+          </option-card-ui>
+          <option-card-ui name="role" value="owner" heading="Owner" description="Admin powers plus the ability to delete the workspace."></option-card-ui>
+        </col-ui>
+      </field-ui>
+    </div>
+  </div>
+</section>
+
+<section data-section data-property="select">
+  <h2 variant="section">Compact select (table inline)</h2>
+  <p data-note>Used inside a members table. The select replaces the static role tag on row-hover, or stays inline when the table is in edit mode. Falls back to a non-interactive <code>tag-ui</code> when the current user can't change roles.</p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label="role select inline">
+      <row-ui data-chunk="permissions-role-picker-select" gap="3" align="center" padding="2" style="max-width: 480px;">
+        <avatar-ui size="sm" text="Kim Granlund"></avatar-ui>
+        <col-ui gap="0" grow>
+          <text-ui strong>Kim Granlund</text-ui>
+          <text-ui color="subtle" size="sm">kim@example.com</text-ui>
+        </col-ui>
+        <select-ui value="admin" size="sm" style="min-width: 140px;">
+          <option value="viewer">Viewer</option>
+          <option value="member">Member</option>
+          <option value="admin" selected>Admin</option>
+          <option value="owner">Owner</option>
+        </select-ui>
+      </row-ui>
+    </div>
+  </div>
+</section>
+
+<section data-section data-property="composition">
+  <h2 variant="section">Composition rules</h2>
+  <ul>
+    <li><strong>Default to the lowest privilege</strong> — Viewer (or Member if there's no Viewer in your model). Make promotion an explicit click, not an oversight.</li>
+    <li><strong>Description is mandatory</strong> in the rich variant — users hovering between Member and Admin should see exactly what changes.</li>
+    <li><strong>Don't mix scope into role names</strong> — "Workspace Admin" vs "Project Admin" are scope distinctions; either pick scope first then role, or use a dedicated permission matrix (36b).</li>
+    <li><strong>The role list is short</strong> — 3–5 roles. Beyond that, the user can't hold the mental model and you should reach for custom roles (04d).</li>
+  </ul>
+</section>
+
+<section data-section data-property="cross-references">
+  <h2 variant="section">See also</h2>
+  <ul>
+    <li><a href="/site/components/option-card">option-card-ui</a> — rich-radio surface.</li>
+    <li><a href="/site/components/select">select-ui</a> — compact select.</li>
+    <li><a href="/site/components/field">field-ui</a> — wrapper with label / hint / error.</li>
+    <li><a href="/site/patterns/form-drawer">form-drawer</a> — host for invite flows.</li>
+  </ul>
+</section>

package/patterns/permissions-role-picker/permissions-role-picker.html

@@ -0,0 +1,56 @@
+<!DOCTYPE html>
+<html lang="en" theme="auto">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Permissions Role Picker (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/col/col.css">
+  <link rel="stylesheet" href="../../components/field/field.css">
+  <link rel="stylesheet" href="../../components/option-card/option-card.css">
+  <link rel="stylesheet" href="../../components/row/row.css">
+  <link rel="stylesheet" href="../../components/select/select.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/col/col.js"></script>
+  <script type="module" src="../../components/field/field.js"></script>
+  <script type="module" src="../../components/option-card/option-card.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/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('./permissions-role-picker.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 permissions-role-picker.examples.html — ${err.message}</p>`;
+      console.error('[permissions-role-picker.html]', err);
+    }
+  </script>
+
+</body>
+</html>