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/admin-keys-and-export/admin-keys-and-export.html ADDED Viewed

@@ -0,0 +1,64 @@
+<!DOCTYPE html>
+<html lang="en" theme="auto">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>API keys, webhooks &amp; data export (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/alert/alert.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/field/field.css">
+  <link rel="stylesheet" href="../../components/icon/icon.css">
+  <link rel="stylesheet" href="../../components/input/input.css">
+  <link rel="stylesheet" href="../../components/list/list.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/alert/alert.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/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/list/list.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('./admin-keys-and-export.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 admin-keys-and-export.examples.html — ${err.message}</p>`;
+      console.error('[admin-keys-and-export.html]', err);
+    }
+  </script>
+</body>
+</html>

package/patterns/admin-shell/admin-shell.examples.html ADDED Viewed

@@ -0,0 +1,327 @@
+<header>
+  <div>
+    <h1>Admin Shell — Composition Pattern</h1>
+    <div data-actions>
+      <tag-ui size="sm">admin-shell</tag-ui>
+      <tag-ui size="sm" variant="ghost">cluster-namespaced</tag-ui>
+    </div>
+  </div>
+  <p>
+    The canonical composition pattern for an admin / SaaS / dashboard
+    application. Built from cluster-namespaced bespoke children — every
+    structural part has its own custom element with its own state-as-attribute
+    semantics. The legacy raw-HTML form (<code>&lt;aside data-sidebar&gt;</code>,
+    <code>&lt;main&gt;</code>, <code>&lt;dialog data-command&gt;</code>) was
+    retired in v0.4.0 per
+    <a href="../../../../.brain/adrs/0024-legacy-shell-shapes-retired.md">ADR-0024</a>;
+    new code uses the bespoke shape exclusively per
+    <a href="../../../../.brain/adrs/0023-bespoke-shell-tier-children.md">ADR-0023</a>.
+  </p>
+</header>
+<section data-section data-property="canonical-hierarchy">
+  <h2 variant="section">Canonical hierarchy</h2>
+  <p data-note>
+    The live docs site you're reading runs inside one of these. The
+    paste-ready reference at
+    <a href="/site/examples/admin-dashboard">/site/examples/admin-dashboard</a>
+    matches this hierarchy exactly.
+  </p>
+  <code-ui language="html">&lt;admin-shell mode="rounded borderless"&gt;
+  &lt;!-- LEADING sidebar — workspace switcher · nav rail · user switcher --&gt;
+  &lt;admin-sidebar slot="leading" resizable collapsible&gt;
+    &lt;admin-topbar slot="header"&gt;
+      &lt;select-ui avatar="…" value="workspace" variant="ghost" style="flex:1"&gt;&lt;/select-ui&gt;
+    &lt;/admin-topbar&gt;
+    &lt;section-ui&gt;
+      &lt;nav-ui&gt;
+        &lt;nav-item-ui icon="house" text="Home" 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-statusbar slot="footer"&gt;
+      &lt;select-ui avatar="…" value="user" variant="ghost" style="flex:1"&gt;&lt;/select-ui&gt;
+    &lt;/admin-statusbar&gt;
+    &lt;div data-resize&gt;&lt;/div&gt;
+  &lt;/admin-sidebar&gt;
+  &lt;!-- MAIN content column — breadcrumb topbar · scrollable page · status footer --&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;a href="#"&gt;Home&lt;/a&gt;&lt;span&gt;Dashboard&lt;/span&gt;&lt;/breadcrumb-ui&gt;
+      &lt;span data-spacer&gt;&lt;/span&gt;
+      &lt;div data-actions&gt;
+        &lt;button-ui text="Export" icon="download" variant="outline" size="sm"&gt;&lt;/button-ui&gt;
+        &lt;button-ui text="+ New" variant="primary" size="sm"&gt;&lt;/button-ui&gt;
+      &lt;/div&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 data-actions&gt;…page-level actions…&lt;/div&gt;
+            &lt;/div&gt;
+            &lt;p&gt;Description.&lt;/p&gt;
+          &lt;/header&gt;
+        &lt;/admin-page-header&gt;
+        &lt;admin-page-body&gt;
+          …grid-ui · card-ui · stat-ui · table-ui · etc.…
+        &lt;/admin-page-body&gt;
+      &lt;/admin-page&gt;
+    &lt;/admin-scroll&gt;
+    &lt;admin-statusbar&gt;
+      &lt;span&gt;My App&lt;/span&gt;
+      &lt;span data-spacer&gt;&lt;/span&gt;
+      &lt;span&gt;v1.0.0&lt;/span&gt;
+    &lt;/admin-statusbar&gt;
+  &lt;/admin-content&gt;
+  &lt;!-- TRAILING sidebar (optional) — context inspector / changelog rail --&gt;
+  &lt;admin-sidebar slot="trailing" resizable collapsible hidden&gt;
+    &lt;admin-topbar slot="header"&gt;
+      &lt;span slot="heading"&gt;Inspector&lt;/span&gt;
+      &lt;button-ui slot="action" data-sidebar-toggle="trailing" icon="x" variant="ghost" size="sm"&gt;&lt;/button-ui&gt;
+    &lt;/admin-topbar&gt;
+    &lt;section-ui&gt;…&lt;/section-ui&gt;
+    &lt;div data-resize&gt;&lt;/div&gt;
+  &lt;/admin-sidebar&gt;
+  &lt;!-- Command palette — top-level child, NOT nested in admin-content --&gt;
+  &lt;admin-command&gt;
+    &lt;command-ui placeholder="Search pages..."&gt;&lt;/command-ui&gt;
+  &lt;/admin-command&gt;
+&lt;/admin-shell&gt;</code-ui>
+</section>
+<section data-section data-property="part-by-part-reference">
+  <h2 variant="section">Part-by-part reference</h2>
+  <p>Each part owns its own state-as-attribute semantics and has its own per-part docs page covering variants and permutations.</p>
+  <table>
+    <thead>
+      <tr><th>Part</th><th>Role</th><th>Variants</th></tr>
+    </thead>
+    <tbody>
+      <tr>
+        <td><a href="/site/components/admin-shell"><code>&lt;admin-shell&gt;</code></a></td>
+        <td>Behavior-only host. Wires sidebar toggle, command palette, ResizeObserver responsive collapse.</td>
+        <td><code>mode="rounded borderless"</code></td>
+      </tr>
+      <tr>
+        <td><a href="/site/components/admin-sidebar"><code>&lt;admin-sidebar&gt;</code></a> · <a href="/site/patterns/admin-sidebar">pattern</a></td>
+        <td>Leading or trailing rail. Holds workspace switcher + nav + user switcher.</td>
+        <td>Simple · grouped · with dividers · with sub-navs · workspace+user variants</td>
+      </tr>
+      <tr>
+        <td><a href="/site/components/admin-topbar"><code>&lt;admin-topbar&gt;</code></a></td>
+        <td>Sticky band. Inside sidebar = workspace switcher; inside content = breadcrumb + actions; with <code>slot="header"</code> = sidebar header band.</td>
+        <td>Breadcrumb + actions · breadcrumb only · with tabs · with search · with sidebar-toggle</td>
+      </tr>
+      <tr>
+        <td><a href="/site/components/admin-content"><code>&lt;admin-content&gt;</code></a> · <a href="/site/patterns/admin-content-topbar">pattern</a></td>
+        <td>Main column. Wraps topbar + scroll + statusbar.</td>
+        <td>With trailing-aside subnav · with multiple pages (router-ui)</td>
+      </tr>
+      <tr>
+        <td><a href="/site/components/admin-scroll"><code>&lt;admin-scroll&gt;</code></a></td>
+        <td>Scrollable region inside content. Wraps the page (or router).</td>
+        <td>Single page · router · with section-rail aside</td>
+      </tr>
+      <tr>
+        <td><a href="/site/components/admin-page"><code>&lt;admin-page&gt;</code></a></td>
+        <td>Page boundary inside admin-scroll. Holds page-header + page-body.</td>
+        <td>—</td>
+      </tr>
+      <tr>
+        <td><a href="/site/components/admin-page-header"><code>&lt;admin-page-header&gt;</code></a> · <a href="/site/patterns/admin-page-header">pattern</a></td>
+        <td>Page title band. Wraps <code>&lt;header&gt;</code> with title + actions + description.</td>
+        <td>Regular · with actions · with tabs · with breadcrumb above · <code>data-flush</code> (no border)</td>
+      </tr>
+      <tr>
+        <td><a href="/site/components/admin-page-body"><code>&lt;admin-page-body&gt;</code></a></td>
+        <td>Page content area. Holds the actual UI (grids, cards, tables, etc.).</td>
+        <td>—</td>
+      </tr>
+      <tr>
+        <td><a href="/site/components/admin-statusbar"><code>&lt;admin-statusbar&gt;</code></a></td>
+        <td>Footer band. Inside sidebar = user switcher; inside content = global status footer.</td>
+        <td>User switcher · sign-in CTA · static brand · version + spacer</td>
+      </tr>
+      <tr>
+        <td><a href="/site/components/admin-command"><code>&lt;admin-command&gt;</code></a></td>
+        <td>Cmd+K palette. Top-level child of <code>admin-shell</code>, self-stamps a <code>&lt;dialog&gt;</code>.</td>
+        <td>—</td>
+      </tr>
+    </tbody>
+  </table>
+</section>
+<section data-section data-property="authoring-rules">
+  <h2 variant="section">Authoring rules</h2>
+  <ul>
+    <li><strong>Cluster-namespaced children only.</strong> Inside <code>&lt;admin-shell&gt;</code>, use <code>&lt;admin-sidebar&gt;</code>, <code>&lt;admin-content&gt;</code>, <code>&lt;admin-topbar&gt;</code>, <code>&lt;admin-statusbar&gt;</code>, <code>&lt;admin-page&gt;</code>, <code>&lt;admin-command&gt;</code>. Don't use raw <code>&lt;aside&gt;</code>, <code>&lt;main&gt;</code>, <code>&lt;dialog&gt;</code> — they no longer style or wire (ADR-0024).</li>
+    <li><strong>Sidebar nav uses <code>&lt;nav-ui&gt;</code> + <code>&lt;nav-item-ui&gt;</code>.</strong> NOT <code>&lt;menu-ui&gt;</code> / <code>&lt;menu-item-ui&gt;</code> — those are popover action menus (dropdowns), wrong primitive for nav.</li>
+    <li><strong>Workspace + user switcher use <code>&lt;select-ui avatar="…" value="…" variant="ghost"&gt;</code>.</strong> Auto-stamps avatar + label + caret-up-down row. The <code>&lt;menu-ui&gt;</code>-with-button-trigger form documented elsewhere is the v0.5.x legacy shape; new code uses <code>&lt;select-ui&gt;</code>.</li>
+    <li><strong>Page-header wraps an inner <code>&lt;header&gt;</code>.</strong> The shape is <code>&lt;admin-page-header&gt;&lt;header&gt;&lt;div&gt;&lt;h1&gt;…&lt;/h1&gt;&lt;div data-actions&gt;…&lt;/div&gt;&lt;/div&gt;&lt;p&gt;…&lt;/p&gt;&lt;/header&gt;&lt;/admin-page-header&gt;</code>. Add <code>data-flush</code> on the inner <code>&lt;header&gt;</code> to drop the bottom border.</li>
+    <li><strong>Sidebar collapses to icons.</strong> <code>&lt;nav-item-ui&gt;</code> rows centre to their icon when the rail is collapsed — every row needs an <code>icon=</code> attribute or a <code>[slot="icon"]</code> child to remain legible.</li>
+    <li><strong>State is queryable as attributes.</strong> <code>shell.querySelector('admin-sidebar[slot="leading"]').hasAttribute('collapsed')</code>. Style cross-cuts via <code>:has()</code>; no <code>getBoundingClientRect</code> math.</li>
+  </ul>
+</section>
+<section data-section data-property="where-to-next">
+  <h2 variant="section">Where to next</h2>
+  <ul>
+    <li><a href="/site/examples/admin-dashboard">Live example</a> — paste-ready full dashboard at the canonical hierarchy.</li>
+    <li><a href="/site/patterns/admin-page-header">admin-page-header pattern</a> — title row · actions · tabs · breadcrumb-above · flush.</li>
+    <li><a href="/site/patterns/admin-sidebar">admin-sidebar pattern</a> — simple · groups · dividers · sub-navs · topbar/statusbar variants.</li>
+    <li><a href="/site/patterns/admin-content-topbar">admin-content topbar pattern</a> — breadcrumb · actions · tabs · search · trailing-toggle.</li>
+    <li><a href="/site/patterns/admin-content-aside">admin-content aside pattern</a> — section subnav · changelog rail · context inspector.</li>
+    <li><a href="/site/getting-started/cdn-usage">CDN usage</a> — drop AdiaUI into any HTML page (CodePen, marketing, static).</li>
+  </ul>
+</section>
+<style>
+  /* Tamed admin-shell demos — fixed height, in-flow positioning */
+  .admin-shell-demo {
+    position: static;
+    inset: auto;
+    height: 440px;
+    border: 1px solid var(--md-sys-color-neutral-outline-variant);
+    border-radius: var(--a-radius-lg);
+    overflow: hidden;
+    margin-block: var(--a-space-3);
+  }
+  .admin-shell-demo admin-content { border-inline-start: none; }
+  .demo-content-area {
+    flex: 1;
+    min-height: 0;
+    overflow: auto;
+    padding: var(--a-space-6);
+    color: var(--a-fg-muted);
+    font-size: var(--a-ui-sm);
+  }
+</style>
+<section data-section data-property="live-demos">
+  <h2 variant="section">Live demos</h2>
+  <p data-note>Each demo is a real <code>&lt;admin-shell&gt;</code> rendered at fixed height. These are the patterns to emit when generating admin/SaaS/dashboard surfaces.</p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label="standard — leading nav + content"
+         data-chunk="admin-shell-standard"
+         data-chunk-kind="page"
+         data-chunk-domain="layout"
+         data-chunk-description="Standard admin shell — leading sidebar with workspace switcher, nav rail, user switcher; content column with topbar breadcrumb and scrollable page."
+         data-chunk-keywords="admin shell layout sidebar nav topbar breadcrumb content page dashboard saas">
+      <admin-shell class="admin-shell-demo" mode="">
+        <admin-sidebar slot="leading" name="demo-standard">
+          <admin-topbar slot="header">
+            <select-ui avatar="/icons/agent-ui-light.svg" value="my-app" variant="ghost" style="flex:1">
+              <option value="my-app">My App</option>
+              <option value="my-app-staging">My App · Staging</option>
+            </select-ui>
+          </admin-topbar>
+          <section-ui>
+            <nav-ui>
+              <nav-item-ui icon="house" text="Dashboard" selected></nav-item-ui>
+              <nav-item-ui icon="users" text="Team"></nav-item-ui>
+              <nav-item-ui icon="chart-bar" text="Reports"></nav-item-ui>
+              <nav-item-ui icon="gear" text="Settings"></nav-item-ui>
+            </nav-ui>
+          </section-ui>
+          <admin-statusbar slot="footer">
+            <admin-entity-item slot="heading">
+              <avatar-ui slot="icon" text="MC" size="sm"></avatar-ui>
+              <span slot="label">Maya Chen</span>
+            </admin-entity-item>
+          </admin-statusbar>
+        </admin-sidebar>
+        <admin-content>
+          <admin-topbar>
+            <button-ui data-sidebar-toggle="leading" icon="sidebar" variant="ghost" size="sm"></button-ui>
+            <breadcrumb-ui><a href="#">My App</a><span>Dashboard</span></breadcrumb-ui>
+            <span data-spacer></span>
+            <div data-actions>
+              <button-ui text="+ New" variant="primary" size="sm"></button-ui>
+            </div>
+          </admin-topbar>
+          <admin-scroll>
+            <admin-page>
+              <admin-page-header>
+                <header>
+                  <div><h1>Dashboard</h1></div>
+                  <p>Welcome back. Here's what's happening today.</p>
+                </header>
+              </admin-page-header>
+              <admin-page-body>
+                <section>
+                  <div class="demo-content-area"><p>Page content goes here.</p></div>
+                </section>
+              </admin-page-body>
+            </admin-page>
+          </admin-scroll>
+        </admin-content>
+      </admin-shell>
+    </div>
+    <div data-artifact-item data-artifact-label="borderless rounded — modern aesthetic"
+         data-chunk="admin-shell-rounded-borderless"
+         data-chunk-kind="page"
+         data-chunk-domain="layout"
+         data-chunk-description="Rounded borderless admin shell — floating card aesthetic with gap between sidebar and content. Modern SaaS visual style."
+         data-chunk-keywords="admin shell rounded borderless floating card sidebar content modern saas aesthetic layout">
+      <admin-shell class="admin-shell-demo" mode="rounded borderless">
+        <admin-sidebar slot="leading" name="demo-rounded">
+          <admin-topbar slot="header">
+            <admin-entity-item slot="heading">
+              <icon-ui slot="icon" name="lightning"></icon-ui>
+              <span slot="label">Adia Studio</span>
+            </admin-entity-item>
+          </admin-topbar>
+          <section-ui>
+            <nav-ui>
+              <nav-item-ui icon="house" text="Home" selected></nav-item-ui>
+              <nav-item-ui icon="tray" text="Inbox" badge="4"></nav-item-ui>
+              <nav-item-ui icon="chart-bar" text="Analytics"></nav-item-ui>
+              <nav-item-ui icon="gear" text="Settings"></nav-item-ui>
+            </nav-ui>
+          </section-ui>
+          <admin-statusbar slot="footer">
+            <admin-entity-item slot="heading">
+              <avatar-ui slot="icon" text="KG" size="sm"></avatar-ui>
+              <span slot="label">Kim Granlund</span>
+            </admin-entity-item>
+          </admin-statusbar>
+        </admin-sidebar>
+        <admin-content>
+          <admin-topbar>
+            <button-ui data-sidebar-toggle="leading" icon="sidebar" variant="ghost" size="sm"></button-ui>
+            <breadcrumb-ui><span>Home</span></breadcrumb-ui>
+            <span data-spacer></span>
+            <button-ui icon="bell" variant="ghost" size="sm"></button-ui>
+          </admin-topbar>
+          <admin-scroll>
+            <admin-page>
+              <admin-page-header>
+                <header data-flush>
+                  <div><h1>Home</h1></div>
+                </header>
+              </admin-page-header>
+              <admin-page-body>
+                <section>
+                  <div class="demo-content-area"><p>Page body.</p></div>
+                </section>
+              </admin-page-body>
+            </admin-page>
+          </admin-scroll>
+        </admin-content>
+      </admin-shell>
+    </div>
+  </div>
+</section>

package/patterns/admin-shell/admin-shell.html ADDED Viewed

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

package/patterns/agent-cost/agent-cost.examples.html ADDED Viewed

@@ -0,0 +1,111 @@
+<header>
+  <div>
+    <h1>Agent Cost &amp; Usage</h1>
+    <div data-actions>
+      <tag-ui size="sm">tag-ui</tag-ui> <tag-ui size="sm">stat-ui</tag-ui> <tag-ui size="sm">alert-ui</tag-ui>
+    </div>
+  </div>
+  <p>How an agent surfaces its own consumption: token usage, dollar cost, rate-limit headroom. Three shapes — an inline footer indicator, a detailed breakdown card for billing/admin pages, and a rate-limit alert for soft warnings.</p>
+</header>
+<section data-section data-property="when-to-use">
+  <h2 variant="section">When to use</h2>
+  <p data-note>
+    The user is paying for the agent — directly (per-call billing) or
+    indirectly (their company's plan). Surface usage where it informs
+    a decision: at the bottom of a chat thread (inline), in the
+    workspace billing tab (detailed), and as an inline alert when
+    they're approaching a cap. Don't surface it inside every
+    individual reply — the noise outweighs the signal.
+  </p>
+</section>
+<section data-section data-property="inline">
+  <h2 variant="section">Inline indicator</h2>
+  <p data-note>Compact footer for the chat thread. Tokens + cost + duration. Uses <code>tag-ui</code> in a row; subtle text color so it doesn't compete with replies.</p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label="inline cost indicator">
+      <row-ui data-chunk="agent-cost-inline" gap="2" align="center" padding="2" style="max-width: 560px;">
+        <tag-ui icon="coins" size="sm">$0.014</tag-ui>
+        <tag-ui icon="hash" size="sm">2,184 tok</tag-ui>
+        <tag-ui icon="timer" size="sm">3.2s</tag-ui>
+        <row-ui grow></row-ui>
+        <text-ui color="subtle" size="sm">claude-opus-4-7</text-ui>
+      </row-ui>
+    </div>
+  </div>
+</section>
+<section data-section data-property="detailed">
+  <h2 variant="section">Detailed breakdown card</h2>
+  <p data-note>Full breakdown for a billing or admin view. Stat tiles for the headline numbers; <code>description-list-ui</code> for the per-channel decomposition (input / output / cache).</p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label="cost breakdown card">
+      <card-ui data-chunk="agent-cost-detailed" style="max-width: 560px;">
+        <header>
+          <span slot="heading" variant="section">Today's usage</span>
+          <text-ui slot="description" color="subtle">Apr 29 · across all sessions</text-ui>
+        </header>
+        <section>
+          <col-ui gap="3">
+            <grid-ui columns="3" gap="2">
+              <stat-ui label="Cost" value="$2.41" trend="up" delta="+18%"></stat-ui>
+              <stat-ui label="Tokens" value="184k" trend="up" delta="+12%"></stat-ui>
+              <stat-ui label="Calls" value="47" trend="flat"></stat-ui>
+            </grid-ui>
+            <description-list-ui layout="inline" align="between">
+              <dt>Input tokens</dt><dd>142,108 · $0.43</dd>
+              <dt>Output tokens</dt><dd>38,294 · $1.72</dd>
+              <dt>Cache reads</dt><dd>3,841 · $0.01</dd>
+              <dt>Cache writes</dt><dd>1,267 · $0.25</dd>
+            </description-list-ui>
+          </col-ui>
+        </section>
+        <footer divider>
+          <text-ui slot="description" color="subtle" size="sm">Plan limit: 1M tokens / day</text-ui>
+          <button-ui slot="action" text="View invoice" variant="ghost" size="sm" icon-leading="receipt"></button-ui>
+        </footer>
+      </card-ui>
+    </div>
+  </div>
+</section>
+<section data-section data-property="rate-limit">
+  <h2 variant="section">Rate-limit warning</h2>
+  <p data-note>Soft warning when the user is approaching a rate-limit. <code>alert-ui variant="warning"</code> with a <code>progress-ui</code> showing remaining headroom. Action button offers upgrade or wait-time.</p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label="rate-limit warning">
+      <alert-ui data-chunk="agent-rate-limit" variant="warning" icon="warning" style="max-width: 560px;">
+        <col-ui slot="content" gap="2">
+          <text-ui strong>Approaching token limit</text-ui>
+          <text-ui>You've used 870k of your 1M daily token allowance. Resets at midnight UTC (in 4h 12m).</text-ui>
+          <progress-ui value="87" size="sm"></progress-ui>
+          <row-ui gap="2" justify="end">
+            <button-ui text="Wait" variant="ghost" size="sm"></button-ui>
+            <button-ui text="Upgrade plan" variant="primary" size="sm"></button-ui>
+          </row-ui>
+        </col-ui>
+      </alert-ui>
+    </div>
+  </div>
+</section>
+<section data-section data-property="composition">
+  <h2 variant="section">Composition rules</h2>
+  <ul>
+    <li><strong>Inline = three signals max</strong> — cost, tokens, duration. Anything more belongs in the detailed view.</li>
+    <li><strong>Stats round consistently</strong> — kilo-tokens at 3 sig figs (184k, 1.42M); cost to 2 decimals ($0.01 floor).</li>
+    <li><strong>Rate-limit warning fires at 80%, not 100%</strong> — gives the user time to act. The 100% case is an error, not a warning.</li>
+    <li><strong>Trend deltas are vs the prior day</strong> — week-over-week deltas confuse users in active sessions. Use week comparison only on the billing tab.</li>
+  </ul>
+</section>
+<section data-section data-property="cross-references">
+  <h2 variant="section">See also</h2>
+  <ul>
+    <li><a href="/site/components/stat">stat-ui</a> — tile primitive used in detailed breakdown.</li>
+    <li><a href="/site/components/alert">alert-ui</a> — the rate-limit warning surface.</li>
+    <li><a href="/site/components/progress">progress-ui</a> — headroom indicator.</li>
+    <li><a href="/site/components/tag">tag-ui</a> — inline indicator chips.</li>
+  </ul>
+</section>

package/patterns/agent-cost/agent-cost.html ADDED Viewed

@@ -0,0 +1,62 @@
+<!DOCTYPE html>
+<html lang="en" theme="auto">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Agent Cost &amp; Usage (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/alert/alert.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/grid/grid.css">
+  <link rel="stylesheet" href="../../components/progress/progress.css">
+  <link rel="stylesheet" href="../../components/row/row.css">
+  <link rel="stylesheet" href="../../components/stat/stat.css">
+  <link rel="stylesheet" href="../../components/tag/tag.css">
+  <link rel="stylesheet" href="../../components/text/text.css">
+  <!-- Component JS -->
+  <script type="module" src="../../components/alert/alert.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/grid/grid.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/stat/stat.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-cost.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-cost.examples.html — ${err.message}</p>`;
+      console.error('[agent-cost.html]', err);
+    }
+  </script>
+</body>
+</html>