@adia-ai/web-components 0.8.6 → 0.8.8

package/patterns/system-banners/system-banners.examples.html

@@ -0,0 +1,150 @@
+<header>
+  <div>
+    <h1>System &amp; App Banners</h1>
+    <div data-actions>
+      <tag-ui size="sm">alert-ui</tag-ui> <tag-ui size="sm">button-ui</tag-ui> <tag-ui size="sm">text-ui</tag-ui>
+    </div>
+  </div>
+  <p>Persistent strip-shaped surfaces above the app shell. System banners (offline, maintenance, update available), live-update banners ("new since you opened this"), and announcement banners (beta callouts, promos). All three are <code>alert-ui</code> compositions; the variant + dismiss + CTA pattern is what differs.</p>
+</header>
+
+<section data-section data-property="when-to-use">
+  <h2 variant="section">When to use</h2>
+  <p data-note>
+    Three reasons a banner exists at the top of an app: the system is in
+    a degraded state (08j), real-time activity has out-paced the user's
+    view (17f), or product wants to promote something (14e). They share
+    a primitive but differ in tone, dismissibility, and persistence —
+    system banners are non-dismissible while the condition holds; live
+    + announcement are dismissible.
+  </p>
+</section>
+
+<section data-section data-property="system-offline">
+  <h2 variant="section">System status — offline</h2>
+  <p data-note><code>variant="warning"</code> with a network-slash icon. Non-dismissible while the connection is down. The banner disappears on its own when the network returns; users don't dismiss it manually.</p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label="offline banner">
+      <alert-ui data-chunk="banner-system-offline" variant="warning" icon="wifi-slash">
+        <col-ui slot="content" gap="1">
+          <text-ui strong>You're offline.</text-ui>
+          <text-ui>Changes will sync when the connection returns. Some features are unavailable.</text-ui>
+        </col-ui>
+      </alert-ui>
+    </div>
+  </div>
+</section>
+
+<section data-section data-property="system-maintenance">
+  <h2 variant="section">System status — maintenance window</h2>
+  <p data-note><code>variant="info"</code> with a wrench icon. Posted ahead of a planned outage. Carries the start time and an optional "Learn more" link to a status page. Not dismissible — users need to know.</p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label="maintenance banner">
+      <alert-ui data-chunk="banner-system-maintenance" variant="info" icon="wrench">
+        <col-ui slot="content" gap="1">
+          <text-ui strong>Scheduled maintenance — Sunday, 2:00–4:00 AM UTC.</text-ui>
+          <text-ui>The service will be read-only during this window.</text-ui>
+          <row-ui gap="2" justify="end">
+            <button-ui text="Status page" variant="ghost" size="sm" icon-trailing="arrow-up-right"></button-ui>
+          </row-ui>
+        </col-ui>
+      </alert-ui>
+    </div>
+  </div>
+</section>
+
+<section data-section data-property="system-update">
+  <h2 variant="section">System status — update available</h2>
+  <p data-note><code>variant="info"</code> with an arrow-clockwise icon and a primary "Refresh" CTA. Appears when the client detects a newer build. Dismissible (user is in the middle of something) but reappears on next session start.</p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label="update available banner">
+      <alert-ui data-chunk="banner-system-update" variant="info" icon="arrow-clockwise" closable>
+        <col-ui slot="content" gap="1">
+          <text-ui strong>A new version is available.</text-ui>
+          <text-ui>Refresh to get the latest features and fixes.</text-ui>
+          <row-ui gap="2" justify="end">
+            <button-ui text="Refresh" variant="primary" size="sm"></button-ui>
+          </row-ui>
+        </col-ui>
+      </alert-ui>
+    </div>
+  </div>
+</section>
+
+<section data-section data-property="live-update">
+  <h2 variant="section">Live updates — "new since you opened this"</h2>
+  <p data-note><code>variant="info"</code> with a count + a "Show new" CTA. Sits above a list / feed / table to signal that the underlying data has new rows the user hasn't seen yet. Clicking the CTA scrolls the new items in and dismisses the banner. Companion to the <code>data-stream</code> trait.</p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label="live update banner">
+      <alert-ui data-chunk="banner-live-update" variant="info" icon="arrow-up">
+        <col-ui slot="content" gap="1">
+          <row-ui gap="2" align="baseline" wrap>
+            <text-ui strong>12 new items</text-ui>
+            <text-ui color="subtle">since you opened this view 4 minutes ago.</text-ui>
+          </row-ui>
+          <row-ui gap="2" justify="end">
+            <button-ui text="Show new" variant="primary" size="sm" icon-trailing="arrow-up"></button-ui>
+          </row-ui>
+        </col-ui>
+      </alert-ui>
+    </div>
+  </div>
+</section>
+
+<section data-section data-property="announcement-beta">
+  <h2 variant="section">Announcement — beta callout</h2>
+  <p data-note><code>variant="info"</code> or <code>variant="muted"</code> with a sparkle / flask icon. Promotes a new feature to opted-in users; carries a "Try it" CTA + dismiss. Once dismissed, persists per-user — don't show twice.</p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label="beta announcement banner">
+      <alert-ui data-chunk="banner-announcement-beta" variant="muted" icon="sparkle" closable>
+        <col-ui slot="content" gap="1">
+          <text-ui strong>New: Saved views.</text-ui>
+          <text-ui>Curate filter sets and reuse them across the workspace. Now in beta.</text-ui>
+          <row-ui gap="2" justify="end">
+            <button-ui text="Try it" variant="primary" size="sm"></button-ui>
+          </row-ui>
+        </col-ui>
+      </alert-ui>
+    </div>
+  </div>
+</section>
+
+<section data-section data-property="announcement-promo">
+  <h2 variant="section">Announcement — promo / event</h2>
+  <p data-note><code>variant="info"</code> with a megaphone or calendar icon. Time-boxed (event date, promo end). Dismiss persists for the campaign window. CTA goes to the landing page or signup flow.</p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label="promo announcement banner">
+      <alert-ui data-chunk="banner-announcement-promo" variant="info" icon="megaphone-simple" closable>
+        <col-ui slot="content" gap="1">
+          <text-ui strong>UIConf 2026 — May 22, virtual.</text-ui>
+          <text-ui>Two days of sessions on generative UI, A2UI internals, and the road ahead.</text-ui>
+          <row-ui gap="2" justify="end">
+            <button-ui text="Save your seat" variant="primary" size="sm" icon-trailing="arrow-up-right"></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>System banners are non-dismissible while the condition holds</strong> — offline, maintenance windows, and incidents disappear on their own when the situation resolves. Forcing a manual dismiss invites confusion ("did I miss something?").</li>
+    <li><strong>Update-available is the exception</strong> — the user is allowed to keep working through their current task; the banner reappears next session.</li>
+    <li><strong>Live-update banners pair with <code>data-stream</code></strong> — the banner's count comes from the same stream that's feeding the list below it. The CTA reveals queued items already in memory; the banner is a UX-layer affordance, not a re-fetch.</li>
+    <li><strong>Announcements respect a per-user dismiss</strong> — once a user closes a beta callout or promo, do not show it again on this device for the campaign window. Persist server-side if the campaign spans devices.</li>
+    <li><strong>One banner at a time</strong> — stacking three banners above the app shell pushes content down and reads as broken. Prioritize: system &gt; live &gt; announcement; suppress lower-priority banners while higher-priority ones are visible.</li>
+    <li><strong>Banner text leads with the noun, not the verb</strong> — "12 new items", "Scheduled maintenance", "New version available". Action verbs go on the button.</li>
+  </ul>
+</section>
+
+<section data-section data-property="cross-references">
+  <h2 variant="section">See also</h2>
+  <ul>
+    <li><a href="/site/components/alert">alert-ui</a> — the underlying primitive (variants, closable, icon, slots).</li>
+    <li><a href="/site/patterns/data-stream">data-stream</a> — the trait that powers live-update counts.</li>
+    <li><a href="/site/components/toast">toast-ui</a> — transient ephemeral notifications (sibling, not interchangeable).</li>
+    <li><a href="/site/patterns/auth-status-pages">auth status pages</a> — full-page status surfaces (sibling for non-banner system states).</li>
+  </ul>
+</section>

package/patterns/system-banners/system-banners.html

@@ -0,0 +1,52 @@
+<!DOCTYPE html>
+<html lang="en" theme="auto">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>System &amp; App Banners (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/col/col.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/alert/alert.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/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('./system-banners.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 system-banners.examples.html — ${err.message}</p>`;
+      console.error('[system-banners.html]', err);
+    }
+  </script>
+
+</body>
+</html>

package/patterns/timezone-selector/timezone-selector.examples.html

@@ -0,0 +1,82 @@
+<header>
+  <div>
+    <h1>Time-zone selector</h1>
+    <div data-actions>
+      <tag-ui size="sm">select-ui</tag-ui> <tag-ui size="sm">field-ui</tag-ui>
+    </div>
+  </div>
+  <p>IANA timezone picker — searchable select-ui populated from <code>Intl.supportedValuesOf('timeZone')</code> (browser-native, ~400 zones, zero-deps). Each option renders as <code>America/Los_Angeles · UTC-8</code> so users can scan by offset or search by city / region.</p>
+</header>
+
+<section data-section data-property="when-to-use">
+  <h2 variant="section">When to use</h2>
+  <p data-note>User preferences / scheduling / log-display surfaces where the operator must pick a canonical IANA zone (not just a display offset). Defaults to the browser's resolved zone via <code>Intl.DateTimeFormat().resolvedOptions().timeZone</code> — overrides for users in multi-zone accounts.</p>
+</section>
+
+<section data-section data-property="basic">
+  <h2 variant="section">Basic — searchable picker</h2>
+  <p data-note>Type to filter by city, region, or offset. Default value resolved from the browser's locale; the current-tz hint sits under the input. Composes select-ui[searchable] with no new primitive.</p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label="timezone picker">
+      <card-ui data-chunk="timezone-selector-basic" style="max-width: 480px;">
+        <header>
+          <span slot="heading" variant="section">Display time zone</span>
+          <text-ui slot="description" color="subtle">Used for log timestamps, scheduled reports, and meeting times</text-ui>
+        </header>
+        <section>
+          <col-ui gap="3">
+            <field-ui label="Time zone">
+              <select-ui id="tz-select-basic" searchable placeholder="Search by city or region…"></select-ui>
+            </field-ui>
+            <text-ui color="subtle" size="sm" id="tz-hint-basic">Detected from your browser locale.</text-ui>
+          </col-ui>
+        </section>
+      </card-ui>
+    </div>
+  </div>
+</section>
+
+<section data-section data-property="with-preview">
+  <h2 variant="section">With live preview</h2>
+  <p data-note>The chosen zone's current local time updates in the description as the user changes the picker. Useful for "Send at" / "Schedule report" forms where the time-in-target matters more than the offset.</p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label="timezone picker with preview">
+      <card-ui data-chunk="timezone-selector-preview" style="max-width: 480px;">
+        <header>
+          <span slot="heading" variant="section">Schedule report</span>
+        </header>
+        <section>
+          <col-ui gap="3">
+            <field-ui label="Time zone">
+              <select-ui id="tz-select-preview" searchable></select-ui>
+            </field-ui>
+            <field-ui label="Send at">
+              <input-ui type="time" name="send-at" value="09:00"></input-ui>
+            </field-ui>
+            <text-ui id="tz-preview" color="subtle" size="sm"></text-ui>
+          </col-ui>
+        </section>
+      </card-ui>
+    </div>
+  </div>
+</section>
+
+<section data-section data-property="composition">
+  <h2 variant="section">Composition rules</h2>
+  <ul>
+    <li><strong>Data from <code>Intl.supportedValuesOf('timeZone')</code></strong> — browser-native, always current with the IANA database the browser ships. No external tz-data dependency.</li>
+    <li><strong>Label format: <code>region/city · UTC±N</code></strong> — gives both the canonical identifier (for storage) and the human offset (for scanning). Users sort by either.</li>
+    <li><strong>Default from <code>Intl.DateTimeFormat().resolvedOptions().timeZone</code></strong> — the browser's resolved zone is the right zero-friction default. Surface the value as a hint so users can confirm before saving.</li>
+    <li><strong>Recompute offsets per render</strong> — DST transitions move; cache the offset string at render time, not at boot. (Re-rendering on each open is cheap; the cost is the ~400-option list which we already accept.)</li>
+    <li><strong>For account-level multi-zone scheduling</strong> — pair with a second select-ui for the user's locale-zone vs the report-target-zone. Don't try to encode both into one picker.</li>
+  </ul>
+</section>
+
+<section data-section data-property="cross-references">
+  <h2 variant="section">Cross-references</h2>
+  <ul>
+    <li><a href="/site/components/select">select-ui</a> — base primitive ([searchable] flag is the load-bearing feature).</li>
+    <li><a href="/site/components/relative-time">relative-time-ui</a> — companion for showing past/future timestamps in the chosen zone.</li>
+    <li><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/supportedValuesOf">Intl.supportedValuesOf MDN</a> — data source.</li>
+  </ul>
+</section>

package/patterns/timezone-selector/timezone-selector.examples.js

@@ -0,0 +1,72 @@
+/** Timezone-selector pattern — populate select-ui[searchable] from Intl.supportedValuesOf. */
+
+function offsetLabel(tz, when = new Date()) {
+  try {
+    const parts = new Intl.DateTimeFormat('en-US', {
+      timeZone: tz,
+      timeZoneName: 'shortOffset',
+    }).formatToParts(when);
+    const name = parts.find(p => p.type === 'timeZoneName')?.value || '';
+    // shortOffset → "GMT-8" / "GMT+05:30"; normalize to "UTC-8".
+    return name.replace(/^GMT/, 'UTC') || '';
+  } catch {
+    return '';
+  }
+}
+
+function localTimeIn(tz, when = new Date()) {
+  try {
+    return new Intl.DateTimeFormat([], {
+      timeZone: tz,
+      hour: '2-digit',
+      minute: '2-digit',
+      weekday: 'short',
+    }).format(when);
+  } catch {
+    return '';
+  }
+}
+
+function timezoneOptions() {
+  let zones = [];
+  try {
+    zones = Intl.supportedValuesOf('timeZone');
+  } catch {
+    zones = ['UTC', 'America/Los_Angeles', 'America/New_York', 'Europe/London', 'Europe/Berlin', 'Asia/Tokyo', 'Asia/Shanghai', 'Australia/Sydney'];
+  }
+  return zones.map(tz => ({
+    value: tz,
+    label: `${tz} · ${offsetLabel(tz)}`,
+  }));
+}
+
+function populate(select, defaultTz) {
+  select.options = timezoneOptions();
+  if (defaultTz) select.value = defaultTz;
+}
+
+export default function setup(router) {
+  const root = router || document;
+  const defaultTz = Intl.DateTimeFormat().resolvedOptions().timeZone;
+
+  // Basic picker
+  const basic = root.querySelector?.('#tz-select-basic');
+  if (basic) {
+    populate(basic, defaultTz);
+    const hint = root.querySelector('#tz-hint-basic');
+    if (hint) hint.textContent = `Detected from your browser locale: ${defaultTz} (${offsetLabel(defaultTz)}).`;
+  }
+
+  // With live preview
+  const preview = root.querySelector?.('#tz-select-preview');
+  const previewLine = root.querySelector?.('#tz-preview');
+  if (preview && previewLine) {
+    populate(preview, defaultTz);
+    const update = () => {
+      const tz = preview.value || defaultTz;
+      previewLine.textContent = `Current time in ${tz}: ${localTimeIn(tz)} (${offsetLabel(tz)}).`;
+    };
+    update();
+    preview.addEventListener('change', update);
+  }
+}

package/patterns/timezone-selector/timezone-selector.html

@@ -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>Time-zone selector (pattern) — AdiaUI</title>
+
+  <link rel="stylesheet" href="../../styles/resets.css">
+  <link rel="stylesheet" href="../../styles/tokens.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/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">
+
+  <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/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('./timezone-selector.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 timezone-selector.examples.html — ${err.message}</p>`;
+      console.error('[timezone-selector.html]', err);
+    }
+  </script>
+
+</body>
+</html>

package/patterns/wizard-drawer/wizard-drawer.examples.html

@@ -0,0 +1,144 @@
+<header>
+  <div>
+    <h1>Wizard Drawer</h1>
+    <div data-actions>
+      <tag-ui size="sm">drawer-ui</tag-ui> <tag-ui size="sm">stepper-ui</tag-ui> <tag-ui size="sm">button-ui</tag-ui>
+    </div>
+  </div>
+  <p>Multi-step form in a drawer. Stepper in the header tracks progress; body swaps content per step; footer pins Back / Next, with a primary finish on the last step. The canonical onboarding-inside-an-app shape.</p>
+</header>
+
+<section data-section data-property="when-to-use">
+  <h2 variant="section">When to use</h2>
+  <p data-note>
+    Any 3–5 step flow where each step has its own set of decisions and the user benefits
+    from seeing progress: invite flow, integration setup, first-run onboarding, payment
+    collection, multi-stage approvals. For 6+ steps, consider a dedicated page.
+  </p>
+</section>
+
+<section data-section data-property="three-step-wizard">
+  <h2 variant="section">Three-step create wizard</h2>
+  <p data-note>Stepper header, step body, Back/Next footer. The interactive buttons below advance the stepper and switch the body panel.</p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label="wizard">
+      <button-ui data-chunk="wizard-drawer-three-step-wizard" text="Create workspace" icon="plus" variant="primary" onclick="this.nextElementSibling.open=true"></button-ui>
+      <drawer-ui id="pat-wizard" side="right" size="lg">
+        <header slot="header">
+          <col-ui gap="2" grow>
+            <text-ui strong>Create workspace</text-ui>
+            <stepper-ui id="pat-wizard-stepper" step="0">
+              <stepper-item-ui text="Details"></stepper-item-ui>
+              <stepper-item-ui text="Members"></stepper-item-ui>
+              <stepper-item-ui text="Review"></stepper-item-ui>
+            </stepper-ui>
+          </col-ui>
+        </header>
+        <section slot="body">
+          <div data-wizard-step="0">
+            <col-ui gap="3">
+              <h4>Workspace details</h4>
+              <field-ui label="Name">
+                <input-ui placeholder="Acme Team" required></input-ui>
+              </field-ui>
+              <field-ui label="Slug">
+                <input-ui prefix="/" placeholder="acme-team"></input-ui>
+              </field-ui>
+              <field-ui label="Description">
+                <textarea-ui rows="2" placeholder="What does this team work on?"></textarea-ui>
+              </field-ui>
+            </col-ui>
+          </div>
+          <div data-wizard-step="1" hidden>
+            <col-ui gap="3">
+              <h4>Invite team members</h4>
+              <field-ui label="Email addresses">
+                <textarea-ui placeholder="alex@acme.com, sarah@acme.com" rows="3"></textarea-ui>
+              </field-ui>
+              <field-ui label="Default role">
+                <select-ui placeholder="Select role">
+                <option value="admin">Admin</option>
+                <option value="member" selected>Member</option>
+                <option value="viewer">Viewer</option>
+              </select-ui>
+              </field-ui>
+              <field-ui label="Send welcome email" inline>
+                <switch-ui checked></switch-ui>
+              </field-ui>
+            </col-ui>
+          </div>
+          <div data-wizard-step="2" hidden>
+            <col-ui gap="3">
+              <h4>Review and create</h4>
+              <alert-ui text="Your workspace will be created and team members will be invited by email." variant="info" icon="info"></alert-ui>
+              <description-list-ui>
+                <dt>Name</dt><dd>Acme Team</dd>
+                <dt>Slug</dt><dd>/acme-team</dd>
+                <dt>Members</dt><dd>2 invited</dd>
+                <dt>Plan</dt><dd>Free (14-day Pro trial)</dd>
+              </description-list-ui>
+            </col-ui>
+          </div>
+        </section>
+        <footer slot="footer">
+          <span slot="action-leading">
+            <button-ui id="pat-wizard-back" text="Back" variant="ghost" disabled></button-ui>
+          </span>
+          <span slot="action">
+            <button-ui text="Cancel" variant="ghost" onclick="this.closest('drawer-ui').open=false"></button-ui>
+            <button-ui id="pat-wizard-next" text="Next" variant="primary"></button-ui>
+          </span>
+        </footer>
+      </drawer-ui>
+    </div>
+  </div>
+</section>
+
+<section data-section data-property="anatomy">
+  <h2 variant="section">Anatomy</h2>
+  <code-ui language="html">&lt;drawer-ui side="right" size="lg"&gt;
+
+  &lt;!-- stepper in header tracks progress --&gt;
+  &lt;header slot="header"&gt;
+    &lt;col-ui gap="2" grow&gt;
+      &lt;text-ui weight="semibold"&gt;Create workspace&lt;/text-ui&gt;
+      &lt;stepper-ui step="0"&gt;
+        &lt;stepper-item-ui text="Details"&gt;&lt;/stepper-item-ui&gt;
+        &lt;stepper-item-ui text="Members"&gt;&lt;/stepper-item-ui&gt;
+        &lt;stepper-item-ui text="Review"&gt;&lt;/stepper-item-ui&gt;
+      &lt;/stepper-ui&gt;
+    &lt;/col-ui&gt;
+  &lt;/header&gt;
+
+  &lt;!-- one panel per step, toggled via hidden attr --&gt;
+  &lt;section slot="body"&gt;
+    &lt;div data-wizard-step="0"&gt; ...details... &lt;/div&gt;
+    &lt;div data-wizard-step="1" hidden&gt; ...members... &lt;/div&gt;
+    &lt;div data-wizard-step="2" hidden&gt; ...review... &lt;/div&gt;
+  &lt;/section&gt;
+
+  &lt;!-- Back on the leading edge, Cancel/Next on the trailing edge --&gt;
+  &lt;footer slot="footer"&gt;
+    &lt;span slot="action-leading"&gt;
+      &lt;button-ui text="Back" variant="ghost"&gt;&lt;/button-ui&gt;
+    &lt;/span&gt;
+    &lt;span slot="action"&gt;
+      &lt;button-ui text="Cancel" variant="ghost"&gt;&lt;/button-ui&gt;
+      &lt;button-ui text="Next" variant="primary"&gt;&lt;/button-ui&gt;
+    &lt;/span&gt;
+  &lt;/footer&gt;
+
+&lt;/drawer-ui&gt;</code-ui>
+</section>
+
+<section data-section data-property="rules">
+  <h2 variant="section">Rules</h2>
+  <ul>
+    <li>Stepper is in the <strong>header</strong>, not the body. The user always sees progress even when the body scrolls.</li>
+    <li>Use <code>stepper-ui.step</code> (numeric) as the source of truth. Toggle <code>hidden</code> on <code>[data-wizard-step="N"]</code> to swap panels.</li>
+    <li>The primary action label changes on the last step: "Next" → "Create" / "Finish". Back button is disabled on step 0.</li>
+    <li>Every step validates independently before advancing. Advance triggers <code>.next()</code> on the stepper AND unhides the next panel.</li>
+    <li>If steps can be revisited, make <code>stepper-item-ui</code> clickable and wire to <code>.goTo(i)</code>. Otherwise keep it display-only.</li>
+    <li>Consider using the <code>state-machine</code> controller on the drawer for more complex flows (branching, validation states, resumable wizards).</li>
+  </ul>
+</section>

package/patterns/wizard-drawer/wizard-drawer.examples.js

@@ -0,0 +1,33 @@
+/** Wizard drawer pattern — wire stepper to step-panel swap */
+
+export default function setup(router) {
+  const stepper = router.querySelector('#pat-wizard-stepper');
+  const backBtn = router.querySelector('#pat-wizard-back');
+  const nextBtn = router.querySelector('#pat-wizard-next');
+  const drawer  = router.querySelector('#pat-wizard');
+  if (!stepper || !backBtn || !nextBtn || !drawer) return;
+
+  const total = 3;
+  let step = 0;
+
+  const sync = () => {
+    stepper.step = step;
+    for (let i = 0; i < total; i++) {
+      const panel = router.querySelector(`[data-wizard-step="${i}"]`);
+      if (panel) panel.hidden = i !== step;
+    }
+    backBtn.disabled = step === 0;
+    nextBtn.text = step === total - 1 ? 'Create' : 'Next';
+  };
+
+  backBtn.addEventListener('press', () => {
+    if (step > 0) { step--; sync(); }
+  });
+
+  nextBtn.addEventListener('press', () => {
+    if (step < total - 1) { step++; sync(); }
+    else { drawer.open = false; step = 0; sync(); }
+  });
+
+  sync();
+}