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

@adia-ai/web-components 0.8.6 → 0.8.7

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 (102) hide show

package/patterns/agent-tool-call/agent-tool-call.html ADDED Viewed

@@ -0,0 +1,60 @@
+<!DOCTYPE html>
+<html lang="en" theme="auto">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Agent Tool Call (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/agent-artifact/agent-artifact.css">
+  <link rel="stylesheet" href="../../components/alert/alert.css">
+  <link rel="stylesheet" href="../../components/button/button.css">
+  <link rel="stylesheet" href="../../components/code/code.css">
+  <link rel="stylesheet" href="../../components/col/col.css">
+  <link rel="stylesheet" href="../../components/description-list/description-list.css">
+  <link rel="stylesheet" href="../../components/progress/progress.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/agent-artifact/agent-artifact.js"></script>
+  <script type="module" src="../../components/alert/alert.js"></script>
+  <script type="module" src="../../components/button/button.js"></script>
+  <script type="module" src="../../components/code/code.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/progress/progress.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('./agent-tool-call.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 agent-tool-call.examples.html — ${err.message}</p>`;
+      console.error('[agent-tool-call.html]', err);
+    }
+  </script>
+</body>
+</html>

package/patterns/alert-dialog/alert-dialog.examples.html ADDED Viewed

@@ -0,0 +1,105 @@
+<header>
+  <div>
+    <h1>Alert dialog</h1>
+    <div data-actions>
+      <tag-ui size="sm">modal-ui</tag-ui> <tag-ui size="sm">field-ui</tag-ui> <tag-ui size="sm">button-ui</tag-ui>
+    </div>
+  </div>
+  <p>Demands acknowledgement before continuing (WAI-APG <a href="https://www.w3.org/WAI/ARIA/apg/patterns/alertdialog/">alertdialog</a>). modal-ui composed with destructive-confirm semantics: clear consequence prose, danger-colored primary action, Cancel as the safe default. Distinct from <code>&lt;modal-ui&gt;</code> bare (informational / form modal — role=dialog) and from <a href="/site/components/toast">toast-ui</a> with action (which is non-blocking).</p>
+</header>
+<section data-section data-property="when-to-use">
+  <h2 variant="section">When to use</h2>
+  <p data-note>Action is irreversible, affects others (workspace-wide delete, billing change), or violates a strong invariant (data loss). The interruption is the point — modal blocks the page; the user must explicitly confirm or cancel. Distinct from <a href="/site/patterns/inline-dialog">inline-dialog</a> (reversible micro-decisions) and from confirm-toast (reversible with timed undo).</p>
+</section>
+<section data-section data-property="simple-confirm">
+  <h2 variant="section">Simple — one-click confirm</h2>
+  <p data-note>For ordinary destructive actions where the consequence is bounded (delete a single item). Title carries the question; body carries the consequence; Cancel + Delete actions. modal-ui's <code>[text]</code> attribute is the title — don't author a separate <code>&lt;header&gt;</code>.</p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label="delete item — simple confirm">
+      <button-ui data-chunk="alert-dialog-simple-trigger" text="Delete item" variant="outline"
+        onclick="document.getElementById('alert-dialog-simple').open = true"></button-ui>
+      <modal-ui id="alert-dialog-simple" data-chunk="alert-dialog-simple" text="Delete this item?" role="alertdialog">
+        <p>This action cannot be undone. The item will be permanently removed from your workspace.</p>
+        <div slot="footer" style="display:flex; gap:var(--a-space-2); justify-content:flex-end;">
+          <button-ui text="Cancel" variant="ghost"
+            onclick="this.closest('modal-ui').open=false"></button-ui>
+          <button-ui text="Delete" color="danger"
+            onclick="this.closest('modal-ui').open=false"></button-ui>
+        </div>
+      </modal-ui>
+    </div>
+  </div>
+</section>
+<section data-section data-property="type-to-confirm">
+  <h2 variant="section">Type-to-confirm — high-consequence gate</h2>
+  <p data-note>For workspace-wide / billing / account-level destructives. User must type the resource name (or a fixed string like "DELETE") into the input — the danger button stays disabled until the typed string matches verbatim. Friction is the point: prevents muscle-memory mistakes.</p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label="delete workspace — typed gate">
+      <button-ui data-chunk="alert-dialog-typed-trigger" text="Delete workspace" variant="outline"
+        onclick="document.getElementById('alert-dialog-typed').open = true"></button-ui>
+      <modal-ui id="alert-dialog-typed" data-chunk="alert-dialog-typed" text='Delete workspace "acme-prod"?' role="alertdialog">
+        <col-ui gap="3">
+          <p>This will permanently delete the workspace, all members, all data, and all integrations. <strong>This cannot be undone.</strong></p>
+          <field-ui label='Type "acme-prod" to confirm' required>
+            <input-ui id="alert-dialog-typed-input" name="confirm" placeholder="acme-prod"
+              oninput="document.getElementById('alert-dialog-typed-submit').disabled = this.value !== 'acme-prod'"></input-ui>
+          </field-ui>
+        </col-ui>
+        <div slot="footer" style="display:flex; gap:var(--a-space-2); justify-content:flex-end;">
+          <button-ui text="Cancel" variant="ghost"
+            onclick="this.closest('modal-ui').open=false; document.getElementById('alert-dialog-typed-input').value='';"></button-ui>
+          <button-ui id="alert-dialog-typed-submit" text="Delete workspace" color="danger" disabled
+            onclick="this.closest('modal-ui').open=false"></button-ui>
+        </div>
+      </modal-ui>
+    </div>
+  </div>
+</section>
+<section data-section data-property="warning-unsaved">
+  <h2 variant="section">Warning — unsaved changes</h2>
+  <p data-note>Non-destructive but interrupts to surface a consequence ("leaving this page will lose your edits"). Same alertdialog role; primary action is the SAFE path (Save & close) with the risky path (Discard) as an outline button.</p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label="unsaved changes — discard or save">
+      <button-ui data-chunk="alert-dialog-unsaved-trigger" text="Close editor" variant="outline"
+        onclick="document.getElementById('alert-dialog-unsaved').open = true"></button-ui>
+      <modal-ui id="alert-dialog-unsaved" data-chunk="alert-dialog-unsaved" text="Discard unsaved changes?" role="alertdialog">
+        <p>You have unsaved changes to this document. Leaving will lose them.</p>
+        <div slot="footer" style="display:flex; gap:var(--a-space-2); justify-content:flex-end;">
+          <button-ui text="Cancel" variant="ghost"
+            onclick="this.closest('modal-ui').open=false"></button-ui>
+          <button-ui text="Discard" variant="outline" color="danger"
+            onclick="this.closest('modal-ui').open=false"></button-ui>
+          <button-ui text="Save & close" variant="primary"
+            onclick="this.closest('modal-ui').open=false"></button-ui>
+        </div>
+      </modal-ui>
+    </div>
+  </div>
+</section>
+<section data-section data-property="composition">
+  <h2 variant="section">Composition rules</h2>
+  <ul>
+    <li><strong>role="alertdialog" (not "dialog")</strong> — WAI-APG calls out alertdialog for "demands acknowledgement before continuing". Screen readers announce more assertively + don't allow tab-out to background content.</li>
+    <li><strong>Use modal-ui's <code>[text]</code> attribute for the title</strong> — NOT a child <code>&lt;header&gt;</code>. modal-ui auto-stamps the title bar from the attr; authoring your own header collides with the default slot (and the title ends up rendered as body content). See the modal-ui docs for its canonical slot vocabulary.</li>
+    <li><strong>Default size is md</strong> — don't downsize to <code>sm</code> "to look tighter". md gives the action buttons proper breathing room. Use <code>lg</code> only when the body has a multi-section form.</li>
+    <li><strong>Cancel is safe + first</strong> — render Cancel as <code>variant="ghost"</code> on the left; render the destructive action as <code>color="danger"</code> on the right. Pressing Enter on whatever has focus is the muscle-memory danger — keep Cancel-shaped affordances obvious.</li>
+    <li><strong>Type-to-confirm for high-consequence</strong> — disable the danger button until the user types the resource name verbatim. The inline <code>oninput</code> handler toggles <code>[disabled]</code>. Friction is the feature.</li>
+    <li><strong>Prose names the consequence + the scope</strong> — "all members, all data, all integrations" beats "this workspace and its contents". Specific scope reduces re-read time.</li>
+    <li><strong>Three buttons max</strong> — Cancel + 1 or 2 actions. Anything more is a settings surface, not an alert.</li>
+  </ul>
+</section>
+<section data-section data-property="cross-references">
+  <h2 variant="section">Cross-references</h2>
+  <ul>
+    <li><a href="/site/components/modal">modal-ui</a> — the surface primitive ([text] attribute for title; slot="footer" for actions; role override via <code>role="alertdialog"</code>).</li>
+    <li><a href="/site/patterns/inline-dialog">inline-dialog</a> — reversible micro-decision alternative (anchored, non-modal).</li>
+    <li><a href="/site/components/toast">toast-ui</a> — undo-able confirmation alternative (non-blocking, timed).</li>
+    <li><a href="https://www.w3.org/WAI/ARIA/apg/patterns/alertdialog/">WAI-APG alertdialog</a> — pattern source.</li>
+  </ul>
+</section>

package/patterns/alert-dialog/alert-dialog.html ADDED Viewed

@@ -0,0 +1,57 @@
+<!DOCTYPE html>
+<html lang="en" theme="auto">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Alert dialog (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/col/col.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/modal/modal.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">
+  <script type="module" src="../../components/avatar/avatar.js"></script>
+  <script type="module" src="../../components/button/button.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/icon/icon.js"></script>
+  <script type="module" src="../../components/input/input.js"></script>
+  <script type="module" src="../../components/modal/modal.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('./alert-dialog.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 alert-dialog.examples.html — ${err.message}</p>`;
+      console.error('[alert-dialog.html]', err);
+    }
+  </script>
+</body>
+</html>

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

@@ -0,0 +1,421 @@
+<style>
+  /* Page-local demo helpers — keep inline styles off individual demo
+     elements so the markup reads cleanly. ────────────────────────── */
+  /* Bounded-height frame for nav patterns that need real vertical
+     space (Spacer, Full Example). Frame is a flex column so the
+     nested nav-ui can take remaining height; `min-height: 0`
+     lets it shrink + scroll instead of overflowing the rounded box. */
+  [data-nav-frame] {
+    border: 1px solid var(--md-sys-color-neutral-outline);
+    border-radius: var(--a-radius-lg);
+    display: flex;
+    flex-direction: column;
+  }
+  [data-nav-frame="md"] { height: 300px; }
+  [data-nav-frame="lg"] { height: 480px; }
+  [data-nav-frame] > nav-ui {
+    flex: 1;
+    min-height: 0;
+  }
+  /* Side-by-side expanded vs collapsed comparison demo. */
+  [data-nav-compare] {
+    display: flex;
+    gap: var(--a-space-4);
+  }
+  [data-nav-compare] > [data-col="expanded"]  { max-width: 280px; flex: 1; }
+  [data-nav-compare] > [data-col="collapsed"] { max-width: 60px;  flex: 0 0 auto; }
+  [data-nav-compare] [data-col-label] {
+    margin-bottom: var(--a-space-2);
+    color: var(--a-fg-muted);
+  }
+  /* Bordered, content-sized nav for the comparison demo (no fixed
+     height — sizes to its own content). */
+  [data-nav-bordered] {
+    border: 1px solid var(--md-sys-color-neutral-outline);
+    border-radius: var(--a-radius-lg);
+    padding: var(--a-space-2);
+  }
+</style>
+<header>
+    <div>
+      <h1>App Nav</h1>
+      <div data-actions>
+        <tag-ui size="sm">nav-ui</tag-ui>
+      </div>
+    </div>
+    <p>Sidebar navigation pattern with groups, items, dividers, spacers, badges, and collapsed popover flyouts.</p>
+  </header>
+<section data-section data-property="overview">
+  <h2 variant="section">Overview</h2>
+  <p>
+    The <code>nav-ui</code> pattern provides a complete sidebar navigation tree.
+    Items can be grouped with collapsible headers, separated with dividers,
+    and labeled with section headings. When the nav is collapsed (narrow width),
+    groups show their children in popover flyouts instead of inline.
+  </p>
+  </section>
+<section data-section data-property="structure">
+  <h2 variant="section">Structure</h2>
+  <code-ui language="html">
+    <template>
+      <nav-ui>
+        <!-- Top-level item with icon -->
+        <nav-item-ui icon="magnifying-glass" text="Search" value="search">
+          <kbd slot="trailing">&#8984;K</kbd>
+        </nav-item-ui>
+        <!-- Divider + label -->
+        <hr data-nav-divider />
+        <span data-nav-label>Platform</span>
+        <!-- Collapsible group -->
+        <nav-group-ui icon="gear" text="Settings" open>
+          <nav-item-ui text="General" value="general" selected></nav-item-ui>
+          <nav-item-ui text="Security" value="security"></nav-item-ui>
+          <nav-item-ui text="Billing" value="billing" badge="Pro"></nav-item-ui>
+        </nav-group-ui>
+        <!-- Spacer pushes remaining items to the bottom -->
+        <span data-nav-spacer></span>
+        <!-- Bottom items -->
+        <nav-item-ui icon="question" text="Help" value="help"></nav-item-ui>
+      </nav-ui>
+    </template>
+  </code-ui>
+  </section>
+<section data-section data-property="groups">
+  <h2 variant="section">Groups</h2>
+  <p>
+    Groups are collapsible sections with a header row. They display an icon,
+    label, optional badge, and a caret indicator. Click the header to toggle.
+  </p>
+  <div data-artifact-container>
+    <div data-demo data-artifact-item data-artifact-label="groups">
+      <nav-ui data-chunk="app-nav-groups">
+        <nav-group-ui icon="gear" text="Settings" open>
+          <nav-item-ui text="General" value="general" selected></nav-item-ui>
+          <nav-item-ui text="Security" value="security"></nav-item-ui>
+          <nav-item-ui text="Notifications" value="notifications"></nav-item-ui>
+        </nav-group-ui>
+        <nav-group-ui icon="user" text="Team" badge="5">
+          <nav-item-ui text="Members" value="members"></nav-item-ui>
+          <nav-item-ui text="Roles" value="roles"></nav-item-ui>
+          <nav-item-ui text="Invites" value="invites" badge="2"></nav-item-ui>
+        </nav-group-ui>
+      </nav-ui>
+    </div>
+  </div>
+  </section>
+<section data-section data-property="items">
+  <h2 variant="section">Items</h2>
+  <p>
+    Standalone items live outside groups. They can have icons, text, badges,
+    and trailing slots (such as keyboard shortcuts).
+  </p>
+  <div data-artifact-container>
+    <div data-demo data-artifact-item data-artifact-label="items">
+      <nav-ui data-chunk="app-nav-items">
+        <nav-item-ui icon="house" text="Dashboard" value="dashboard" selected></nav-item-ui>
+        <nav-item-ui icon="chart-bar" text="Analytics" value="analytics"></nav-item-ui>
+        <nav-item-ui icon="book-open" text="Documentation" value="docs"></nav-item-ui>
+        <nav-item-ui icon="chat-circle" text="Support" value="support" badge="3"></nav-item-ui>
+      </nav-ui>
+    </div>
+  </div>
+  </section>
+<section data-section data-property="badges">
+  <h2 variant="section">Badges</h2>
+  <p>
+    Items and groups both accept a <code>badge</code> attribute that
+    renders a small trailing chip. The badge takes any string —
+    numeric counts, "New" / "Beta" callouts, plan tiers, status
+    labels — single visual style, content does the differentiating.
+  </p>
+  <h3>Counts</h3>
+  <p data-note>
+    Inbox / notifications / pending items. Use literal numbers up to
+    a threshold then "<code>99+</code>" or similar to keep the chip
+    width bounded.
+  </p>
+  <div data-artifact-container>
+    <div data-demo data-artifact-item data-artifact-label="counts">
+      <nav-ui data-chunk="app-nav-badges-counts">
+        <nav-item-ui icon="tray" text="Inbox" value="inbox" badge="12" selected></nav-item-ui>
+        <nav-item-ui icon="bell" text="Notifications" value="notifications" badge="3"></nav-item-ui>
+        <nav-item-ui icon="envelope-open" text="Mentions" value="mentions" badge="1"></nav-item-ui>
+        <nav-item-ui icon="warning-circle" text="Alerts" value="alerts" badge="99+"></nav-item-ui>
+      </nav-ui>
+    </div>
+  </div>
+  <h3>Status callouts</h3>
+  <p data-note>
+    "New" / "Beta" / "Soon" — flag a feature lifecycle stage so users
+    know what's just shipped, what's in preview, and what's coming.
+  </p>
+  <div data-artifact-container>
+    <div data-demo data-artifact-item data-artifact-label="status callouts">
+      <nav-ui data-chunk="app-nav-badges-status-callouts">
+        <nav-item-ui icon="sparkle" text="AI Assistant" value="assistant" badge="New"></nav-item-ui>
+        <nav-item-ui icon="flask" text="Experiments" value="experiments" badge="Beta"></nav-item-ui>
+        <nav-item-ui icon="hourglass" text="Real-time sync" value="rtsync" badge="Soon"></nav-item-ui>
+        <nav-item-ui icon="archive" text="Archive" value="archive"></nav-item-ui>
+      </nav-ui>
+    </div>
+  </div>
+  <h3>Plan tiers</h3>
+  <p data-note>
+    Surface paywalled / tier-locked items so users see what their plan
+    unlocks. Pair with a click-handler that opens a billing dialog
+    when a non-eligible plan tries to enter.
+  </p>
+  <div data-artifact-container>
+    <div data-demo data-artifact-item data-artifact-label="plan tiers">
+      <nav-ui data-chunk="app-nav-badges-plan-tiers">
+        <nav-item-ui icon="house" text="Dashboard" value="dashboard"></nav-item-ui>
+        <nav-item-ui icon="chart-line" text="Forecasting" value="forecasting" badge="Pro"></nav-item-ui>
+        <nav-item-ui icon="users-three" text="Audit log" value="audit" badge="Team"></nav-item-ui>
+        <nav-item-ui icon="key" text="SSO" value="sso" badge="Enterprise"></nav-item-ui>
+      </nav-ui>
+    </div>
+  </div>
+  <h3>Groups with rollup badges</h3>
+  <p data-note>
+    Group headers carry a badge that summarizes child state — total
+    open count, oldest unread, "needs attention" indicator. The group
+    badge sits on the collapsed header so users see the rollup
+    without expanding.
+  </p>
+  <div data-artifact-container>
+    <div data-demo data-artifact-item data-artifact-label="group rollup badges">
+      <nav-ui data-chunk="app-nav-badges-group-rollup-badges">
+        <nav-group-ui icon="tray" text="Inbox" badge="14" open>
+          <nav-item-ui text="Unread" value="unread" badge="12" selected></nav-item-ui>
+          <nav-item-ui text="Mentions" value="mentions" badge="2"></nav-item-ui>
+          <nav-item-ui text="All messages" value="all"></nav-item-ui>
+        </nav-group-ui>
+        <nav-group-ui icon="users" text="Team" badge="3 invites">
+          <nav-item-ui text="Members" value="members"></nav-item-ui>
+          <nav-item-ui text="Pending invites" value="invites" badge="3"></nav-item-ui>
+        </nav-group-ui>
+      </nav-ui>
+    </div>
+  </div>
+  <h3>Mixed</h3>
+  <p data-note>
+    Real navs combine the above — counts on activity-driven items,
+    status callouts on new features, plan badges on paywalled
+    surfaces, group rollups summarizing child state. The badge slot
+    is one of the cheapest ways to surface "what changed since I
+    last looked" inside a sidebar.
+  </p>
+  <div data-artifact-container>
+    <div data-demo data-artifact-item data-artifact-label="mixed">
+      <nav-ui data-chunk="app-nav-badges-mixed">
+        <nav-item-ui icon="house" text="Home" value="home" selected></nav-item-ui>
+        <nav-item-ui icon="tray" text="Inbox" value="inbox" badge="7"></nav-item-ui>
+        <hr data-nav-divider />
+        <span data-nav-label>Workspace</span>
+        <nav-group-ui icon="folder" text="Projects" badge="2 stale">
+          <nav-item-ui text="Active" value="active"></nav-item-ui>
+          <nav-item-ui text="Stale" value="stale" badge="2"></nav-item-ui>
+          <nav-item-ui text="Archived" value="archived"></nav-item-ui>
+        </nav-group-ui>
+        <nav-item-ui icon="sparkle" text="AI Assistant" value="assistant" badge="New"></nav-item-ui>
+        <nav-item-ui icon="chart-line" text="Forecasting" value="forecasting" badge="Pro"></nav-item-ui>
+      </nav-ui>
+    </div>
+  </div>
+  <p data-note>
+    Badges hide automatically when <code>nav-ui[collapsed]</code>
+    is set — see the <a href="#collapsed-mode">Collapsed Mode</a>
+    section. If a badge needs to remain visible in the collapsed rail
+    (e.g., a "9+" attention dot on Inbox), use a custom indicator in
+    the <code>trailing</code> slot of the icon-only item instead.
+  </p>
+</section>
+<section data-section data-property="labels-and-dividers">
+  <h2 variant="section">Labels and Dividers</h2>
+  <p>
+    Use <code>data-nav-label</code> for section headings and
+    <code>data-nav-divider</code> for visual separation.
+  </p>
+  <div data-artifact-container>
+    <div data-demo data-artifact-item data-artifact-label="labels and dividers">
+      <nav-ui data-chunk="app-nav-labels-and-dividers">
+        <span data-nav-label>Platform</span>
+        <nav-item-ui icon="gear" text="Settings" value="settings"></nav-item-ui>
+        <nav-item-ui icon="user" text="Profile" value="profile"></nav-item-ui>
+        <hr data-nav-divider />
+        <span data-nav-label>Resources</span>
+        <nav-item-ui icon="book-open" text="Docs" value="docs"></nav-item-ui>
+        <nav-item-ui icon="chat-circle" text="Support" value="support"></nav-item-ui>
+      </nav-ui>
+    </div>
+  </div>
+  </section>
+<section data-section data-property="spacer">
+  <h2 variant="section">Spacer</h2>
+  <p>
+    The <code>data-nav-spacer</code> element acts as a flex spacer, pushing
+    subsequent items to the bottom of the sidebar.
+  </p>
+  <div data-artifact-container>
+    <div data-demo data-artifact-item data-artifact-label="spacer" data-nav-frame="md">
+      <nav-ui data-chunk="app-nav-spacer">
+        <nav-item-ui icon="house" text="Home" value="home" selected></nav-item-ui>
+        <nav-item-ui icon="gear" text="Settings" value="settings"></nav-item-ui>
+        <span data-nav-spacer></span>
+        <hr data-nav-divider />
+        <nav-item-ui icon="question" text="Help & Feedback" value="help"></nav-item-ui>
+      </nav-ui>
+    </div>
+  </div>
+  </section>
+<section data-section data-property="collapsed-mode">
+  <h2 variant="section">Collapsed Mode</h2>
+  <p>
+    When <code>collapsed</code> is set on the nav, labels and badges hide.
+    Only icons remain visible. Clicking a group header opens a popover flyout
+    with its children instead of toggling inline.
+  </p>
+  <div data-demo data-nav-compare>
+    <div data-col="expanded">
+      <p data-col-label>Expanded</p>
+      <nav-ui data-nav-bordered>
+        <nav-group-ui icon="gear" text="Settings" open>
+          <nav-item-ui text="General" value="general" selected></nav-item-ui>
+          <nav-item-ui text="Security" value="security"></nav-item-ui>
+        </nav-group-ui>
+        <nav-item-ui icon="book-open" text="Docs" value="docs"></nav-item-ui>
+      </nav-ui>
+    </div>
+    <div data-col="collapsed">
+      <p data-col-label>Collapsed</p>
+      <nav-ui collapsed data-nav-bordered>
+        <nav-group-ui icon="gear" text="Settings">
+          <nav-item-ui text="General" value="general2"></nav-item-ui>
+          <nav-item-ui text="Security" value="security2"></nav-item-ui>
+        </nav-group-ui>
+        <nav-item-ui icon="book-open" text="Docs" value="docs2"></nav-item-ui>
+      </nav-ui>
+    </div>
+  </div>
+  </section>
+<section data-section data-property="full-example">
+  <h2 variant="section">Full Example</h2>
+  <p>A complete navigation sidebar as used in the admin pattern:</p>
+  <div data-artifact-container>
+    <div data-demo data-artifact-item data-artifact-label="full example" data-nav-frame="lg">
+      <nav-ui data-chunk="app-nav-full-example">
+        <nav-item-ui icon="magnifying-glass" text="Search" value="search">
+          <kbd slot="trailing">&#8984;K</kbd>
+        </nav-item-ui>
+        <hr data-nav-divider />
+        <span data-nav-label>Platform</span>
+        <nav-group-ui icon="gear" text="Settings" open>
+          <nav-item-ui text="General" value="general" selected></nav-item-ui>
+          <nav-item-ui text="Security" value="security"></nav-item-ui>
+          <nav-item-ui text="Notifications" value="notifications"></nav-item-ui>
+          <nav-item-ui text="Billing" value="billing" badge="Pro"></nav-item-ui>
+        </nav-group-ui>
+        <nav-group-ui icon="user" text="Team" badge="5">
+          <nav-item-ui text="Members" value="members"></nav-item-ui>
+          <nav-item-ui text="Roles" value="roles"></nav-item-ui>
+        </nav-group-ui>
+        <hr data-nav-divider />
+        <span data-nav-label>Observe</span>
+        <nav-group-ui icon="chart-bar" text="Analytics">
+          <nav-item-ui text="Dashboard" value="dashboard"></nav-item-ui>
+          <nav-item-ui text="Reports" value="reports"></nav-item-ui>
+        </nav-group-ui>
+        <span data-nav-spacer></span>
+        <hr data-nav-divider />
+        <nav-item-ui icon="question" text="Help & Feedback" value="help"></nav-item-ui>
+      </nav-ui>
+    </div>
+  </div>
+  </section>
+<section data-section data-property="api">
+  <h2 variant="section">API</h2>
+  <table>
+    <thead>
+      <tr>
+        <th>Element</th>
+        <th>Attribute</th>
+        <th>Type</th>
+        <th>Description</th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr><td><code>nav-ui</code></td><td><code>collapsed</code></td><td>boolean</td><td>Show icons only, groups use popover flyouts</td></tr>
+      <tr><td><code>nav-group-ui</code></td><td><code>icon</code></td><td>string</td><td>Phosphor icon name for the group header</td></tr>
+      <tr><td><code>nav-group-ui</code></td><td><code>text</code></td><td>string</td><td>Group label text</td></tr>
+      <tr><td><code>nav-group-ui</code></td><td><code>badge</code></td><td>string</td><td>Badge text on the group header</td></tr>
+      <tr><td><code>nav-group-ui</code></td><td><code>open</code></td><td>boolean</td><td>Expand this group on load</td></tr>
+      <tr><td><code>nav-item-ui</code></td><td><code>icon</code></td><td>string</td><td>Phosphor icon name</td></tr>
+      <tr><td><code>nav-item-ui</code></td><td><code>text</code></td><td>string</td><td>Item label</td></tr>
+      <tr><td><code>nav-item-ui</code></td><td><code>value</code></td><td>string</td><td>Value emitted in nav-select event</td></tr>
+      <tr><td><code>nav-item-ui</code></td><td><code>badge</code></td><td>string</td><td>Badge text</td></tr>
+      <tr><td><code>nav-item-ui</code></td><td><code>selected</code></td><td>boolean</td><td>Marks this item as the current selection</td></tr>
+    </tbody>
+  </table>
+  </section>
+<section data-section data-property="events">
+  <h2 variant="section">Events</h2>
+  <table>
+    <thead>
+      <tr>
+        <th>Event</th>
+        <th>Target</th>
+        <th>Detail</th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr><td><code>nav-select</code></td><td><code>nav-ui</code></td><td><code>{ item, text, value }</code></td></tr>
+    </tbody>
+  </table>
+</section>
+<section data-section data-property="rules">
+  <h2 variant="section">Authoring rules</h2>
+  <ul>
+    <li><strong>Always use <code>nav-ui</code> + <code>nav-item-ui</code></strong> for sidebar and in-page navigation. Never use <code>menu-ui</code> in a nav context — <code>menu-ui</code> is for popover dropdown menus, not navigation rails.</li>
+    <li><strong>Every <code>nav-item-ui</code> must have <code>icon=</code>.</strong> When the sidebar collapses to icon-only mode, items without an icon become invisible. Provide a meaningful Phosphor icon name on every row.</li>
+    <li><strong>Use <code>nav-group-ui</code> for collapsible sub-navs</strong>, never nested <code>nav-ui</code>. <code>nav-group-ui</code> owns the chevron toggle, open/closed state, and keyboard navigation for the group.</li>
+    <li><strong>Use <code>&lt;hr data-nav-divider /&gt;</code> for visual separators</strong>, not bare <code>&lt;hr&gt;</code>. The plain <code>&lt;hr&gt;</code> renders as a content divider with different spacing; <code>data-nav-divider</code> renders as a subtle nav-rail separator.</li>
+    <li><strong>The workspace switcher belongs in <code>&lt;admin-topbar slot="header"&gt;</code></strong>, not inside <code>nav-ui</code>. The topbar header is the canonical location for workspace context and brand.</li>
+    <li><strong>The user switcher belongs in <code>&lt;admin-statusbar slot="footer"&gt;</code></strong>. Placing it inside the nav scroll area causes it to scroll out of view on long nav lists.</li>
+    <li><strong>Do not put interactive elements (<code>button-ui</code>, <code>switch-ui</code>) directly inside <code>nav-ui</code></strong> — they break the roving tab index and keyboard navigation model. Use <code>nav-item-ui</code> with event delegation, or place the control outside the nav rail.</li>
+  </ul>
+</section>