@adia-ai/web-components 0.8.13 → 0.8.14

package/components/page/page.examples.md

@@ -16,31 +16,54 @@
 </page-ui>
 ```
 
-## Sticky header
+## max-width · padding
 
 ```html
-<page-ui max-width="prose" padding="6" sticky-header>
-  <header-ui>
-    <text-ui variant="title">Long article</text-ui>
-  </header-ui>
-  <section-ui>
-    <!-- long content -->
-  </section-ui>
+<page-ui max-width="prose" padding="6" style="border:1px solid var(--md-sys-color-neutral-outline-variant);border-radius:var(--a-radius-md)">
+  <header>
+    <text-ui variant="title">Welcome back</text-ui>
+  </header>
+  <section>
+    <text-ui>
+      Sign in to continue — the
+      <code>prose</code>
+      clamp keeps the reading column comfortable regardless of viewport width.
+    </text-ui>
+  </section>
+  <footer>
+    <button-ui text="Sign in" variant="solid"></button-ui>
+  </footer>
 </page-ui>
 ```
 
-## Composition with <admin-shell>
+## Region model — rhythm · bleed · padding
 
 ```html
-<admin-shell>
-  <header-ui slot="leading">…</header-ui>
-  <aside-ui slot="leading">…</aside-ui>
-  <section-ui>
-    <page-ui max-width="prose" padding="6">
-      <!-- omit [scroll] — the shell scrolls -->
-      <header-ui>…</header-ui>
-      <section-ui>…</section-ui>
-    </page-ui>
-  </section-ui>
-</admin-shell>
+<page-ui max-width="wide" padding="6" style="border:1px solid var(--md-sys-color-neutral-outline-variant);border-radius:var(--a-radius-md)">
+  <header>
+    <text-ui variant="title">Dashboard</text-ui>
+  </header>
+  <section bleed style="background:var(--md-sys-color-primary-container);padding:var(--a-space-4) var(--a-space-6);">
+    <text-ui>
+      This
+      <code>[bleed]</code>
+      banner runs edge-to-edge — its background spans the full page width, past the
+      <code>padding="6"</code>
+      inset.
+    </text-ui>
+  </section>
+  <section>
+    <text-ui>A default section sits within the page inset with consistent rhythm above and below.</text-ui>
+  </section>
+  <section padding>
+    <text-ui>
+      A
+      <code>section[padding]</code>
+      is a padded sub-surface — its own background and radius, like a card body nested in the page.
+    </text-ui>
+  </section>
+  <footer>
+    <button-ui text="Save changes" variant="solid"></button-ui>
+  </footer>
+</page-ui>
 ```

package/components/password-strength/password-strength.examples.md

@@ -0,0 +1,28 @@
+# password-strength — Examples
+
+## paired with input-ui[type=password]
+
+```html
+<field-ui label="Password" id="pwd-field-1">
+  <input-ui type="password" name="password" placeholder="Type to score…"></input-ui>
+</field-ui>
+<password-strength-ui id="pwd-meter-1"></password-strength-ui>
+```
+
+## score buckets (preview at each level)
+
+```html
+<password-strength-ui id="pwd-empty"></password-strength-ui>
+```
+
+## min-score (submit-button gating)
+
+```html
+<col-ui gap="2">
+  <field-ui label="Password" id="pwd-field-gated">
+    <input-ui type="password" name="password" placeholder="Type to unlock submit…"></input-ui>
+  </field-ui>
+  <password-strength-ui id="pwd-meter-gated" min-score="2"></password-strength-ui>
+  <button-ui id="pwd-submit-gated" variant="primary" text="Create account" disabled></button-ui>
+</col-ui>
+```

package/components/popover/popover.css

@@ -7,7 +7,13 @@
 
     /* ── Colors (default panel chrome — opt out per `:has(>card-ui)` rule
        below or by setting tokens to transparent / 0) ── */
-    --popover-bg:      var(--md-sys-color-neutral-surface-dimmer);
+    /* surface-bright, not surface-dimmer: a floating overlay reads as
+       ELEVATED above the page, and elevation moves toward brighter in dark
+       mode (dimmer = neutral-925, darker than the neutral-875 page it floats
+       over — the panel read near-black). Matches select-ui's own dropdown
+       surface exactly, so the two overlays on a shell's topbar (a select
+       menu and a popover panel) sit on one plane. */
+    --popover-bg:      var(--md-sys-color-neutral-surface-bright);
     --popover-border:  var(--md-sys-color-neutral-outline-variant);
     --popover-shadow:  var(--a-shadow-lg);
   }

package/components/preview/preview.examples.md

@@ -0,0 +1,30 @@
+# preview — Examples
+
+## Basic — stacked (default)
+
+```html
+<preview-ui>
+  <button-ui text="Save" variant="primary"></button-ui>
+  <button-ui text="Cancel" variant="ghost"></button-ui>
+</preview-ui>
+```
+
+## layout="split"
+
+```html
+<preview-ui layout="split">
+  <badge-ui text="New" variant="accent"></badge-ui>
+  <badge-ui text="Beta" variant="warning"></badge-ui>
+  <badge-ui text="Stable" variant="success"></badge-ui>
+</preview-ui>
+```
+
+## code-first
+
+```html
+<preview-ui code-first>
+  <field-ui label="Email" hint="We'll never share it.">
+    <input-ui type="email" placeholder="you@example.com"></input-ui>
+  </field-ui>
+</preview-ui>
+```

package/components/progress/progress.examples.md

@@ -3,17 +3,17 @@
 ## value
 
 ```html
-<progress-ui value="0" style="width:200px"></progress-ui>
+<progress-ui value="0"></progress-ui>
 ```
 
 ## indeterminate
 
 ```html
-<progress-ui style="width:200px"></progress-ui>
+<progress-ui></progress-ui>
 ```
 
 ## variant
 
 ```html
-<progress-ui value="60" variant="bar" style="width:200px"></progress-ui>
+<progress-ui value="60" variant="bar"></progress-ui>
 ```

package/components/qr-code/qr-code.examples.md

@@ -0,0 +1,19 @@
+# qr-code — Examples
+
+## [value] — auto-encode a string
+
+```html
+<qr-code-ui value="https://adia.dev"></qr-code-ui>
+```
+
+## [size] — display dimensions
+
+```html
+<qr-code-ui value="https://example.com" size="128"></qr-code-ui>
+```
+
+## [error-correction] — recovery vs. capacity tradeoff
+
+```html
+<qr-code-ui value="https://example.com" error-correction="L"></qr-code-ui>
+```

package/components/radio/radio.examples.md

@@ -6,14 +6,33 @@
 <radio-ui label="Unchecked" name="demo-state"></radio-ui>
 ```
 
-## disabled
+## Typography registers
 
 ```html
-<radio-ui label="Disabled Unchecked" name="demo-dis" disabled></radio-ui>
+<row-ui gap="6" align="start" wrap>
+  <col-ui gap="2">
+    <text-ui variant="caption" color="muted">verse</text-ui>
+    <div verse>
+      <radio-ui label="Standard" name="reg-verse" checked></radio-ui>
+    </div>
+  </col-ui>
+  <col-ui gap="2">
+    <text-ui variant="caption" color="muted">regular</text-ui>
+    <div>
+      <radio-ui label="Standard" name="reg-regular" checked></radio-ui>
+    </div>
+  </col-ui>
+  <col-ui gap="2">
+    <text-ui variant="caption" color="muted">prose</text-ui>
+    <div prose>
+      <radio-ui label="Standard" name="reg-prose" checked></radio-ui>
+    </div>
+  </col-ui>
+</row-ui>
 ```
 
-## label
+## disabled
 
 ```html
-<radio-ui label="With Label" name="demo-label"></radio-ui>
+<radio-ui label="Disabled Unchecked" name="demo-dis" disabled></radio-ui>
 ```

package/components/relative-time/relative-time.examples.md

@@ -0,0 +1,19 @@
+# relative-time — Examples
+
+## default
+
+```html
+<relative-time-ui datetime="2026-05-25T11:00:00Z"></relative-time-ui>
+```
+
+## time-style (long | short | narrow)
+
+```html
+<relative-time-ui datetime="2026-05-25T09:00:00Z" time-style="long"></relative-time-ui>
+```
+
+## numeric (auto | always)
+
+```html
+<relative-time-ui datetime="2026-05-24T12:00:00Z" numeric="auto"></relative-time-ui>
+```

package/components/row/row.examples.md

@@ -9,3 +9,23 @@
   <tag-ui text="Owner" size="sm"></tag-ui>
 </row-ui>
 ```
+
+## Rendered demos
+
+```html
+<row-ui gap="2">
+  <button-ui text="Cancel" variant="ghost"></button-ui>
+  <button-ui text="Save changes" variant="primary"></button-ui>
+</row-ui>
+```
+
+## Responsive (@bp)
+
+```html
+<!-- Stack on mobile (via col-ui), unwrap to a row at md+ -->
+<!-- For row-specific @bp: vary gap or alignment by viewport -->
+<row-ui gap="sm lg@md" align="start center@lg">
+  <button-ui text="Cancel" variant="ghost"></button-ui>
+  <button-ui text="Save" variant="primary"></button-ui>
+</row-ui>
+```

package/components/skip-nav/skip-nav.examples.md

@@ -0,0 +1,27 @@
+# skip-nav — Examples
+
+## Appearance
+
+```html
+<a class="skip-nav-preview" tabindex="-1" aria-hidden="true">Skip to main content</a>
+```
+
+## Live behavior — Tab into the demo
+
+```html
+<input-ui placeholder="Click here, then press Tab"></input-ui>
+<skip-nav-ui target="#demo-main-target"></skip-nav-ui>
+<div id="demo-main-target" tabindex="-1" style="margin-top: var(--a-space-6); padding: var(--a-space-4); border: 2px dashed var(--a-primary-bg); border-radius: var(--a-radius-md);">
+  <strong>#demo-main-target</strong>
+  — the skip-link's destination. Focus moves here on Enter; you'll see the dashed accent outline activate.
+</div>
+```
+
+## Custom target + label
+
+```html
+<!-- Default -->
+<skip-nav-ui></skip-nav-ui>
+<!-- Custom target + label -->
+<skip-nav-ui target="#article-body" text="Skip to article"></skip-nav-ui>
+```

package/components/spinner/spinner.examples.md

@@ -1,26 +1,19 @@
 # spinner — Examples
 
-## Default
+## variant
 
 ```html
 <spinner-ui></spinner-ui>
 ```
 
-## Loading button
-
-Canonical composition. Disable the button while the operation is in
-progress; `tone="current"` keeps the spinner matched to the button's
-label color.
+## size
 
 ```html
-<button-ui variant="primary" disabled>
-  <spinner-ui size="sm" tone="current" label="Saving"></spinner-ui>
-  Saving
-</button-ui>
+<spinner-ui size="sm"></spinner-ui>
 ```
 
-## Typing indicator
+## paused
 
 ```html
-<spinner-ui variant="dots" tone="subtle" label="Assistant is typing"></spinner-ui>
+<spinner-ui size="lg"></spinner-ui>
 ```

package/components/stack/stack.examples.md

@@ -8,3 +8,20 @@
   <badge-ui text="3" variant="solid" color="danger"></badge-ui>
 </stack-ui>
 ```
+
+## align
+
+```html
+<stack-ui align="top-left" style="width:150px;height:84px;border:1px dashed var(--md-sys-color-neutral-outline-variant);border-radius:var(--a-radius-md)">
+  <badge-ui text="top-left" variant="solid"></badge-ui>
+</stack-ui>
+```
+
+## Rendered demos
+
+```html
+<stack-ui style="width:fit-content">
+  <avatar-ui text="KG" size="md"></avatar-ui>
+  <badge-ui text="3" variant="danger" style="position:absolute;top:-4px;right:-4px;"></badge-ui>
+</stack-ui>
+```

package/components/stat/stat.examples.md

@@ -6,14 +6,33 @@
 <stat-ui value="1,234" label="Total Users"></stat-ui>
 ```
 
-## value
+## Typography registers
 
 ```html
-<stat-ui value="1,234" label="Users"></stat-ui>
+<row-ui gap="6" align="start" wrap>
+  <col-ui gap="2">
+    <text-ui variant="caption" color="muted">verse</text-ui>
+    <div verse style="width:180px">
+      <stat-ui value="$48.2k" label="Revenue" change="+12.5%" trend="up"></stat-ui>
+    </div>
+  </col-ui>
+  <col-ui gap="2">
+    <text-ui variant="caption" color="muted">regular</text-ui>
+    <div style="width:180px">
+      <stat-ui value="$48.2k" label="Revenue" change="+12.5%" trend="up"></stat-ui>
+    </div>
+  </col-ui>
+  <col-ui gap="2">
+    <text-ui variant="caption" color="muted">prose</text-ui>
+    <div prose style="width:180px">
+      <stat-ui value="$48.2k" label="Revenue" change="+12.5%" trend="up"></stat-ui>
+    </div>
+  </col-ui>
+</row-ui>
 ```
 
-## label
+## value
 
 ```html
-<stat-ui value="847" label="Active Users"></stat-ui>
+<stat-ui value="1,234" label="Users"></stat-ui>
 ```

package/components/swatch/swatch.examples.md

@@ -16,8 +16,8 @@
 </row-ui>
 ```
 
-## composition — chart-legend-ui
+## detail · copyable — design-token tile
 
 ```html
-<chart-legend-ui shape="dot" position="bottom" id="demo-legend-dot"></chart-legend-ui>
+<swatch-ui shape="square" size="lg" color="oklch(0.55 0.2 264)" label="primary-500" detail="oklch(0.55 0.2 264)" copyable></swatch-ui>
 ```

package/components/switch/switch.examples.md

@@ -6,14 +6,33 @@
 <switch-ui label="Off"></switch-ui>
 ```
 
-## size
+## Typography registers
 
 ```html
-<switch-ui label="Small" size="sm" checked></switch-ui>
+<row-ui gap="6" align="start" wrap>
+  <col-ui gap="2">
+    <text-ui variant="caption" color="muted">verse</text-ui>
+    <div verse>
+      <switch-ui label="Enabled" checked></switch-ui>
+    </div>
+  </col-ui>
+  <col-ui gap="2">
+    <text-ui variant="caption" color="muted">regular</text-ui>
+    <div>
+      <switch-ui label="Enabled" checked></switch-ui>
+    </div>
+  </col-ui>
+  <col-ui gap="2">
+    <text-ui variant="caption" color="muted">prose</text-ui>
+    <div prose>
+      <switch-ui label="Enabled" checked></switch-ui>
+    </div>
+  </col-ui>
+</row-ui>
 ```
 
-## disabled
+## size
 
 ```html
-<switch-ui label="Disabled Off" disabled></switch-ui>
+<switch-ui label="Small" size="sm" checked></switch-ui>
 ```

package/components/table-toolbar/table-toolbar.examples.md

@@ -10,3 +10,49 @@
   </section-ui>
 </card-ui>
 ```
+
+## Rendered demos
+
+```html
+<col-ui gap="0">
+  <table-toolbar-ui for="demo-table" text="All employees" count="32" placeholder="Search employees…"></table-toolbar-ui>
+  <card-ui>
+    <section bleed>
+      <table-ui id="demo-table" sortable raw>
+        <table>
+          <thead>
+            <tr>
+              <th>Name</th>
+              <th>Role</th>
+              <th>Status</th>
+            </tr>
+          </thead>
+          <tbody>
+            <tr>
+              <td>Maya Chen</td>
+              <td>Designer</td>
+              <td>
+                <tag-ui size="sm" variant="success">Active</tag-ui>
+              </td>
+            </tr>
+            <tr>
+              <td>Alex Park</td>
+              <td>Engineer</td>
+              <td>
+                <tag-ui size="sm" variant="success">Active</tag-ui>
+              </td>
+            </tr>
+            <tr>
+              <td>Jordan Lee</td>
+              <td>Product</td>
+              <td>
+                <tag-ui size="sm" variant="warning">Away</tag-ui>
+              </td>
+            </tr>
+          </tbody>
+        </table>
+      </table-ui>
+    </section>
+  </card-ui>
+</col-ui>
+```

package/components/tabs/tabs.examples.md

@@ -16,6 +16,19 @@
 </tabs-ui>
 ```
 
+## variant
+
+```html
+<tabs-ui value="overview" variant="bordered">
+  <tab-ui value="overview" text="Overview">
+    <p>The bordered variant frames the tab strip — useful inside cards or panels.</p>
+  </tab-ui>
+  <tab-ui value="details" text="Details">
+    <p>Detailed specifications and technical information.</p>
+  </tab-ui>
+</tabs-ui>
+```
+
 ## with icons
 
 ```html
@@ -31,19 +44,3 @@
   </tab-ui>
 </tabs-ui>
 ```
-
-## disabled tab
-
-```html
-<tabs-ui value="active">
-  <tab-ui value="active" text="Active">
-    <p>This tab is active and selectable.</p>
-  </tab-ui>
-  <tab-ui value="also-active" text="Also Active">
-    <p>This tab is also selectable.</p>
-  </tab-ui>
-  <tab-ui value="locked" text="Locked" disabled>
-    <p>This content is locked.</p>
-  </tab-ui>
-</tabs-ui>
-```

package/components/tag/tag.examples.md

@@ -6,14 +6,14 @@
 <tag-ui text="Default"></tag-ui>
 ```
 
-## size
+## tone
 
 ```html
-<tag-ui text="Small" size="sm"></tag-ui>
+<tag-ui text="Default" tone="solid"></tag-ui>
 ```
 
-## removable
+## size
 
 ```html
-<tag-ui text="Removable" removable></tag-ui>
+<tag-ui text="Small" size="sm"></tag-ui>
 ```

package/components/tags-input/tags-input.examples.md

@@ -8,85 +8,18 @@
 </field-ui>
 ```
 
-Type a value + press Enter (or comma) to commit a chip. Backspace from the
-empty inline input removes the last chip.
-
-## pre-populated
-
-```html
-<tags-input-ui name="tags" value='["bug","high-priority","needs-triage"]'></tags-input-ui>
-```
-
-The `value` attribute accepts JSON — `["a","b","c"]`. The form value
-under `name` serializes back to the same JSON string.
-
 ## transform="lowercase"
 
 ```html
-<tags-input-ui transform="lowercase"></tags-input-ui>
+<field-ui label="Labels">
+  <tags-input-ui name="labels" transform="lowercase" placeholder="Type FOO, see foo"></tags-input-ui>
+</field-ui>
 ```
 
-Tokens are lowercased on commit. Available values:
-`""` (preserve), `"lowercase"`, `"trim"`, `"strip-spaces"`.
-
 ## max — count cap
 
 ```html
-<tags-input-ui name="tags" max="3"></tags-input-ui>
-```
-
-Once 3 tokens have been added, further commits fire
-`invalid` with `detail.reason === "max"`.
-
-## delimiter="enter"
-
-```html
-<tags-input-ui delimiter="enter"></tags-input-ui>
-```
-
-Disables in-line character commits when the token grammar legitimately
-contains the default `,` (e.g. display names like "Doe, Jane"). Only
-Enter (or programmatic `addToken`) commits.
-
-## validateFn — email-format gate
-
-```html
-<tags-input-ui id="to" name="to" placeholder="Email…"></tags-input-ui>
-<script>
-  const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
-  document.getElementById('to').validateFn = (value) => EMAIL_RE.test(value);
-</script>
-```
-
-`validateFn` may return a `Promise<boolean>` — the host flips into
-`[validating]` until the promise settles.
-
-## paste-split — bulk entry
-
-```html
-<tags-input-ui name="domains" paste-split=",\n"></tags-input-ui>
-```
-
-Pasting `"example.com, foo.com\nbar.com"` commits three chips.
-
-## suggestions — autocomplete hints
-
-```html
-<tags-input-ui id="tags" name="tags"></tags-input-ui>
-<script>
-  document.getElementById('tags').suggestions = ['bug', 'feature', 'chore'];
-</script>
-```
-
-Suggestions are hints, not gates — the typed value still wins. When
-non-empty, the host announces as `role="combobox"` with the popover
-listed below the field.
-
-## readonly chip display
-
-```html
-<tags-input-ui readonly value='["bug","urgent"]'></tags-input-ui>
+<field-ui label="Up to 3 tags">
+  <tags-input-ui name="tags" max="3" placeholder="Try adding a 4th tag" value='["one","two"]'></tags-input-ui>
+</field-ui>
 ```
-
-Readonly hides the remove affordance on each chip + blocks the inline
-input.