@adia-ai/web-components 0.8.6 → 0.8.8

package/patterns/retention-cohort/retention-cohort.examples.html

@@ -0,0 +1,149 @@
+<header>
+  <div>
+    <h1>Retention Cohort</h1>
+    <div data-actions>
+      <tag-ui size="sm">card-ui</tag-ui> <tag-ui size="sm">table-ui</tag-ui> <tag-ui size="sm">badge-ui</tag-ui>
+    </div>
+  </div>
+  <p>Composition pattern: render a retention cohort "heatmap" using a regular <code>table-ui</code> with a badge-based cell renderer. Each cell is a <code>badge-ui</code> variant tinted by the retention bucket, so the table still sorts, paginates, and copies to clipboard like any other data table.</p>
+</header>
+
+<section data-section data-property="when-to-use">
+  <h2 variant="section">When to use</h2>
+  <p data-note>
+    A true pixel-grid heatmap loses the numeric precision that retention analysis
+    needs — you want to see that W4 held at 54% AND scan the color band. A table with
+    badge cells gives you both: precise numbers on one axis, color-coded buckets
+    across the row. It also preserves accessibility (each number is a real table
+    cell) and lets the same component render partial cohorts (null cells where
+    the cohort hasn't reached that week yet).
+  </p>
+</section>
+
+<section data-section data-property="default-retention">
+  <h2 variant="section">Default retention table</h2>
+  <p data-note>Each week-column uses the same <code>formatPct</code> renderer, which wraps the number in a <code>badge-ui</code> whose variant is keyed to three buckets: ≥60% success, 30–60% warning, &lt;30% muted. Null values render blank so partial cohorts don't force fake zeros.</p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label="retention by signup week">
+      <card-ui data-chunk="retention-cohort-default-retention">
+        <header>
+          <h3>Retention by signup week</h3>
+          <text-ui slot="description" color="subtle">% of users still active in week N</text-ui>
+        </header>
+        <section bleed>
+          <table-ui id="pat-retention-default"></table-ui>
+        </section>
+      </card-ui>
+    </div>
+  </div>
+</section>
+
+<section data-section data-property="with-legend">
+  <h2 variant="section">With a legend</h2>
+  <p data-note>For first-time viewers, pair the table with a tiny legend in the card footer so the buckets are decoded. The legend itself is three <code>badge-ui</code>s — same component the cells use — keeping the visual vocabulary tight.</p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label="retention with legend">
+      <card-ui data-chunk="retention-cohort-with-legend">
+        <header>
+          <h3>Retention by signup week</h3>
+          <text-ui slot="description" color="subtle">Percent of the cohort still active N weeks after signup</text-ui>
+        </header>
+        <section bleed>
+          <table-ui id="pat-retention-legend"></table-ui>
+        </section>
+        <footer divider>
+          <small slot="description">Retention buckets:</small>
+          <span slot="action">
+            <row-ui gap="2" align="center">
+              <badge-ui text="≥ 60%" variant="success"></badge-ui>
+              <badge-ui text="30–60%" variant="warning"></badge-ui>
+              <badge-ui text="< 30%" variant="muted"></badge-ui>
+            </row-ui>
+          </span>
+        </footer>
+      </card-ui>
+    </div>
+  </div>
+</section>
+
+<section data-section data-property="stat-pair">
+  <h2 variant="section">With headline stats</h2>
+  <p data-note>When the cohort table is the only chart in a section, prepend a stat pair for the most important numbers — W4 (early signal) and W12 (sustained retention). Stops users having to scan every row to answer "is this healthy?"</p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label="retention with stats">
+      <card-ui data-chunk="retention-cohort-stat-pair">
+        <header>
+          <h3>Retention</h3>
+          <text-ui slot="description" color="subtle">New signups · rolling 6-week view</text-ui>
+        </header>
+        <section>
+          <grid-ui columns="2" gap="3">
+            <card-ui>
+              <section>
+                <stat-ui label="W4 retention" value="54%" change="+4% vs last cohort" trend="up"></stat-ui>
+              </section>
+            </card-ui>
+            <card-ui>
+              <section>
+                <stat-ui label="W12 retention" value="32%" change="flat" trend="neutral"></stat-ui>
+              </section>
+            </card-ui>
+          </grid-ui>
+        </section>
+        <section bleed>
+          <table-ui id="pat-retention-stats"></table-ui>
+        </section>
+      </card-ui>
+    </div>
+  </div>
+</section>
+
+<section data-section data-property="the-cell-renderer">
+  <h2 variant="section">The cell renderer</h2>
+  <p data-note>All three examples use the same <code>formatPct</code> function defined in the page's <code>setup.js</code>. The column-definition object references it via <code>render: formatPct</code>:</p>
+  <code-ui language="javascript">const formatPct = (v) =&gt; {
+  if (v == null) return '';
+  const n = Math.round(v);
+  const variant = n &gt;= 60 ? 'success' : n &gt;= 30 ? 'warning' : 'muted';
+  return `&lt;badge-ui text='${n}%' variant='${variant}'&gt;&lt;/badge-ui&gt;`;
+};
+
+const columns = [
+  { key: 'week',  label: 'Signup week' },
+  { key: 'size',  label: 'Users' },
+  { key: 'w1',    label: 'W1',  render: formatPct },
+  { key: 'w2',    label: 'W2',  render: formatPct },
+  { key: 'w4',    label: 'W4',  render: formatPct },
+  { key: 'w8',    label: 'W8',  render: formatPct },
+  { key: 'w12',   label: 'W12', render: formatPct },
+];</code-ui>
+</section>
+
+<section data-section data-property="variants-and-knobs">
+  <h2 variant="section">Variants &amp; knobs</h2>
+  <ul data-note>
+    <li><strong>Bucket thresholds.</strong> 60/30 works for most SaaS cohorts. For transactional products (food delivery, e-commerce), bump to 40/20 — those products have lower week-N retention by nature.</li>
+    <li><strong>Null cells.</strong> Return <code>''</code> for unreached weeks, never a zero or dash. An empty cell reads as "not yet known"; zero reads as "churned."</li>
+    <li><strong>Column set.</strong> Canonical columns: Signup week · Users · W1 · W2 · W3 · W4 · W8 · W12. Drop W3 if space is tight; don't drop W1 or W4 (baseline + first truly revealing bucket).</li>
+    <li><strong>Number of rows.</strong> 6–8 cohorts is the sweet spot. More becomes noise; fewer loses the trend.</li>
+  </ul>
+</section>
+
+<section data-section data-property="anti-patterns">
+  <h2 variant="section">Anti-patterns</h2>
+  <ul data-note>
+    <li><strong>Don't use a continuous color ramp.</strong> Three buckets read faster than a gradient — users can scan for "red" rows without decoding shades.</li>
+    <li><strong>Don't left-align the percentages.</strong> Numbers belong right-aligned (or center via the badge) so magnitudes line up vertically.</li>
+    <li><strong>Don't include the current (incomplete) cohort.</strong> The top row should be the most-recent cohort whose W1 is complete; otherwise its zero-ish numbers distort the visual trend.</li>
+  </ul>
+</section>
+
+<section data-section data-property="rules">
+  <h2 variant="section">Authoring rules</h2>
+  <ul>
+    <li><strong>Cohort axis (rows) = time of acquisition</strong> — typically week or month. The column axis = time since acquisition. Do not transpose this: readers expect cohorts as rows.</li>
+    <li><strong>Always color-code by retention rate, not absolute count.</strong> The heatmap's value is in visual comparison across cohorts; absolute numbers belong in tooltips, not cell backgrounds.</li>
+    <li><strong>Show at least 4 cohorts and 4 time periods</strong> for the diagonal comparison to be meaningful. A 2×2 heatmap adds no insight over a single number.</li>
+    <li><strong>Use <code>data-stream-src</code> for live cohort data</strong> — cohort heatmaps are expensive to compute; don't poll more frequently than the underlying aggregation window (usually daily).</li>
+  </ul>
+</section>

package/patterns/retention-cohort/retention-cohort.examples.js

@@ -0,0 +1,37 @@
+/** Retention Cohort pattern — identical cell renderer used for all three tables. */
+
+const formatPct = (v) => {
+  if (v == null) return '';
+  const n = Math.round(v);
+  const variant = n >= 60 ? 'success' : n >= 30 ? 'warning' : 'muted';
+  return `<badge-ui text="${n}%" variant="${variant}"></badge-ui>`;
+};
+
+const columns = [
+  { key: 'week',  label: 'Signup week' },
+  { key: 'size',  label: 'Users' },
+  { key: 'w1',    label: 'W1',  render: formatPct },
+  { key: 'w2',    label: 'W2',  render: formatPct },
+  { key: 'w3',    label: 'W3',  render: formatPct },
+  { key: 'w4',    label: 'W4',  render: formatPct },
+  { key: 'w8',    label: 'W8',  render: formatPct },
+  { key: 'w12',   label: 'W12', render: formatPct },
+];
+
+const data = [
+  { week: 'Jan 6',  size: 420, w1: 100, w2: 78, w3: 62, w4: 54, w8: 41, w12: 32 },
+  { week: 'Jan 13', size: 480, w1: 100, w2: 82, w3: 68, w4: 58, w8: 45, w12: null },
+  { week: 'Jan 20', size: 510, w1: 100, w2: 80, w3: 66, w4: 57, w8: null, w12: null },
+  { week: 'Jan 27', size: 612, w1: 100, w2: 84, w3: 70, w4: null, w8: null, w12: null },
+  { week: 'Feb 3',  size: 584, w1: 100, w2: 81, w3: null, w4: null, w8: null, w12: null },
+  { week: 'Feb 10', size: 640, w1: 100, w2: null, w3: null, w4: null, w8: null, w12: null },
+];
+
+export default function setup(router) {
+  for (const id of ['pat-retention-default', 'pat-retention-legend', 'pat-retention-stats']) {
+    const table = router.querySelector(`#${id}`);
+    if (!table) continue;
+    table.columns = columns;
+    table.data = data;
+  }
+}

package/patterns/retention-cohort/retention-cohort.html

@@ -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>Retention Cohort (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/badge/badge.css">
+  <link rel="stylesheet" href="../../components/card/card.css">
+  <link rel="stylesheet" href="../../components/code/code.css">
+  <link rel="stylesheet" href="../../components/grid/grid.css">
+  <link rel="stylesheet" href="../../components/row/row.css">
+  <link rel="stylesheet" href="../../components/stat/stat.css">
+  <link rel="stylesheet" href="../../components/table/table.css">
+  <link rel="stylesheet" href="../../components/tag/tag.css">
+  <link rel="stylesheet" href="../../components/text/text.css">
+
+  <!-- Component JS -->
+  <script type="module" src="../../components/badge/badge.js"></script>
+  <script type="module" src="../../components/card/card.js"></script>
+  <script type="module" src="../../components/code/code.js"></script>
+  <script type="module" src="../../components/grid/grid.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/table/table.js"></script>
+  <script type="module" src="../../components/tag/tag.js"></script>
+  <script type="module" src="../../components/text/text.js"></script>
+
+  <style>
+    :where(html, body) { margin: 0; min-height: 100vh; background: var(--md-sys-color-neutral-background); color: var(--md-sys-color-neutral-on-surface); font-family: var(--a-font-family); }
+    main { max-width: 960px; margin-inline: auto; padding: var(--a-space-6) var(--a-space-5); }
+  </style>
+</head>
+<body>
+
+  <main id="demo-root">
+    <p>Loading examples…</p>
+  </main>
+
+  <script type="module">
+    const root = document.getElementById('demo-root');
+    try {
+      const res = await fetch('./retention-cohort.examples.html');
+      if (!res.ok) throw new Error(`fetch failed (${res.status})`);
+      root.innerHTML = await res.text();
+      try {
+        const mod = await import(/* @vite-ignore */ './retention-cohort.examples.js');
+        mod.default?.(root);
+      } catch (e) { console.error('[retention-cohort.html] setup failed:', e); }
+    } catch (err) {
+      root.innerHTML = `<p style="color:var(--a-danger-strong);">Failed to load retention-cohort.examples.html — ${err.message}</p>`;
+      console.error('[retention-cohort.html]', err);
+    }
+  </script>
+
+</body>
+</html>

package/patterns/search-discovery/search-discovery.examples.html

@@ -0,0 +1,263 @@
+<header>
+  <div>
+    <h1>Search &amp; Discovery</h1>
+    <div data-actions>
+      <tag-ui size="sm">card-ui</tag-ui> <tag-ui size="sm">search-ui</tag-ui> <tag-ui size="sm">tag-ui</tag-ui> <tag-ui size="sm">avatar-ui</tag-ui> <tag-ui size="sm">row-ui</tag-ui> <tag-ui size="sm">col-ui</tag-ui>
+    </div>
+  </div>
+  <p>The surfaces that surround a search input — what shows up below it. Result lists (flat and grouped), recent-searches menu, and saved-views list. Compose around <code>search-ui</code>; the input itself lives in its component demo.</p>
+</header>
+
+<section data-section data-property="when-to-use">
+  <h2 variant="section">When to use</h2>
+  <p data-note>
+    Whenever a product surfaces a search input, three secondary
+    surfaces follow: results below the input, recents shown when the
+    input is focused but empty, and saved views (when users curate
+    queries). Most products use all three; smaller products skip
+    saved views.
+  </p>
+</section>
+
+<section data-section data-property="results-list">
+  <h2 variant="section">Result list</h2>
+  <p data-note>Flat ranked list. Each row carries a title, snippet, meta (author / date / type), and an optional trailing action. <code>list-ui</code> + <code>list-item-ui</code> with <code>tag-ui</code> for the type.</p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label="search results list">
+      <card-ui data-chunk="search-results-list">
+        <header>
+          <span slot="heading" variant="section">42 results for "OKLCH tokens"</span>
+          <text-ui slot="description" color="subtle">Sorted by relevance · 0.18s</text-ui>
+        </header>
+        <section bleed>
+          <list-ui divider contained>
+            <list-item-ui text="Component Token Contract">
+              <span slot="description">"…all colors must reference --a-chrome-*, --a-data-0..9, or semantic tokens. Zero raw oklch in component CSS…"</span>
+              <tag-ui slot="action" size="sm">Spec</tag-ui>
+            </list-item-ui>
+            <list-item-ui text="2026-04-29 — primitive QA sweep">
+              <span slot="description">"…OKLCH-with-transparent red-shift bug fixed in Safari 18.0 (ADR-0007); we use oklab for color-mix instead…"</span>
+              <tag-ui slot="action" size="sm">Journal</tag-ui>
+            </list-item-ui>
+            <list-item-ui text="styles/tokens.css">
+              <span slot="description">"--a-primary-bg: oklch(64% 0.18 245); --a-primary-fg: oklch(98% 0.01 245)…"</span>
+              <tag-ui slot="action" size="sm">Code</tag-ui>
+            </list-item-ui>
+            <list-item-ui text="Reasoning About Color (skill)">
+              <span slot="description">"…OKLCH ramps that satisfy contrast, hue-stability, and perceptual-evenness…"</span>
+              <tag-ui slot="action" size="sm">Skill</tag-ui>
+            </list-item-ui>
+          </list-ui>
+        </section>
+        <footer divider>
+          <text-ui slot="description" color="subtle" size="sm">Showing 1–4 of 42</text-ui>
+          <button-ui slot="action" text="Load more" variant="ghost" size="sm" icon-trailing="arrow-down"></button-ui>
+        </footer>
+      </card-ui>
+    </div>
+  </div>
+</section>
+
+<section data-section data-property="results-grouped">
+  <h2 variant="section">Grouped results</h2>
+  <p data-note>Sectioned by type when the catalog is heterogeneous (Documents / People / Projects). Each group shows top 3–5; "See all in {group}" links to a filtered view.</p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label="grouped search results">
+      <card-ui data-chunk="search-results-grouped" style="max-width: 640px;">
+        <header>
+          <span slot="heading" variant="section">"kim"</span>
+          <text-ui slot="description" color="subtle">Across people, documents, and projects</text-ui>
+        </header>
+        <section bleed>
+          <col-ui gap="0">
+            <row-ui align="center" gap="2" style="padding: var(--a-space-2) var(--a-space-3); background: var(--a-bg-subtle);">
+              <text-ui strong size="sm" color="subtle">People · 3</text-ui>
+              <button-ui text="See all" variant="ghost" size="sm" style="margin-inline-start: auto;"></button-ui>
+            </row-ui>
+            <list-ui divider contained>
+              <list-item-ui>
+                <row-ui gap="3" align="center">
+                  <avatar-ui size="sm" text="Kim Granlund"></avatar-ui>
+                  <col-ui gap="0" grow>
+                    <text-ui strong>Kim Granlund</text-ui>
+                    <text-ui color="subtle" size="sm">kim@example.com · Owner</text-ui>
+                  </col-ui>
+                </row-ui>
+              </list-item-ui>
+              <list-item-ui>
+                <row-ui gap="3" align="center">
+                  <avatar-ui size="sm" text="Kim Park"></avatar-ui>
+                  <col-ui gap="0" grow>
+                    <text-ui strong>Kim Park</text-ui>
+                    <text-ui color="subtle" size="sm">kim.park@example.com · Member</text-ui>
+                  </col-ui>
+                </row-ui>
+              </list-item-ui>
+            </list-ui>
+            <row-ui align="center" gap="2" style="padding: var(--a-space-2) var(--a-space-3); background: var(--a-bg-subtle); border-block-start: 1px solid var(--md-sys-color-neutral-outline-variant);">
+              <text-ui strong size="sm" color="subtle">Documents · 12</text-ui>
+              <button-ui text="See all" variant="ghost" size="sm" style="margin-inline-start: auto;"></button-ui>
+            </row-ui>
+            <list-ui divider contained>
+              <list-item-ui>
+                <col-ui gap="0">
+                  <text-ui strong>Kim's onboarding plan</text-ui>
+                  <text-ui color="subtle" size="sm">Edited 2 hours ago · by Avery</text-ui>
+                </col-ui>
+              </list-item-ui>
+              <list-item-ui>
+                <col-ui gap="0">
+                  <text-ui strong>Kimchi recipe — team lunch</text-ui>
+                  <text-ui color="subtle" size="sm">Edited 4 days ago · by Jordan</text-ui>
+                </col-ui>
+              </list-item-ui>
+            </list-ui>
+            <row-ui align="center" gap="2" style="padding: var(--a-space-2) var(--a-space-3); background: var(--a-bg-subtle); border-block-start: 1px solid var(--md-sys-color-neutral-outline-variant);">
+              <text-ui strong size="sm" color="subtle">Projects · 1</text-ui>
+            </row-ui>
+            <list-ui contained>
+              <list-item-ui>
+                <col-ui gap="0">
+                  <text-ui strong>Kim's H2 roadmap</text-ui>
+                  <text-ui color="subtle" size="sm">Updated yesterday · 5 active items</text-ui>
+                </col-ui>
+              </list-item-ui>
+            </list-ui>
+          </col-ui>
+        </section>
+      </card-ui>
+    </div>
+  </div>
+</section>
+
+<section data-section data-property="recents-menu">
+  <h2 variant="section">Recent searches menu</h2>
+  <p data-note>Popover that appears when the search input is focused but empty. Recent queries with most-recent-first ordering, a "Clear" action in the footer. Each row reruns the query on click; trailing icon dismisses a single entry.</p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label="recent searches menu">
+      <card-ui data-chunk="search-recents-menu" style="max-width: 360px;">
+        <header>
+          <span slot="heading" variant="section">Recent</span>
+        </header>
+        <section bleed>
+          <list-ui divider contained>
+            <list-item-ui text="OKLCH tokens">
+              <icon-ui slot="icon" name="clock-counter-clockwise" size="sm"></icon-ui>
+              <button-ui slot="action" icon="x" variant="ghost" size="xs" aria-label="Dismiss"></button-ui>
+            </list-item-ui>
+            <list-item-ui text="primitive audit">
+              <icon-ui slot="icon" name="clock-counter-clockwise" size="sm"></icon-ui>
+              <button-ui slot="action" icon="x" variant="ghost" size="xs" aria-label="Dismiss"></button-ui>
+            </list-item-ui>
+            <list-item-ui text="drawer-ui safari fix">
+              <icon-ui slot="icon" name="clock-counter-clockwise" size="sm"></icon-ui>
+              <button-ui slot="action" icon="x" variant="ghost" size="xs" aria-label="Dismiss"></button-ui>
+            </list-item-ui>
+            <list-item-ui text="@scope hover bug">
+              <icon-ui slot="icon" name="clock-counter-clockwise" size="sm"></icon-ui>
+              <button-ui slot="action" icon="x" variant="ghost" size="xs" aria-label="Dismiss"></button-ui>
+            </list-item-ui>
+          </list-ui>
+        </section>
+        <footer divider>
+          <button-ui slot="action" text="Clear all recents" variant="ghost" size="sm" icon-leading="trash"></button-ui>
+        </footer>
+      </card-ui>
+    </div>
+  </div>
+</section>
+
+<section data-section data-property="saved-views">
+  <h2 variant="section">Saved views</h2>
+  <p data-note>List of curated queries the user has named and pinned. Each row shows the view name, a short description (or active filter chips), last-run time, and edit/share/delete actions. Used for "My open issues", "Q2 customer escalations", etc.</p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label="saved views list">
+      <card-ui data-chunk="search-saved-views">
+        <header>
+          <span slot="heading" variant="section">Saved views</span>
+          <text-ui slot="description" color="subtle">5 views · last edited 2 days ago</text-ui>
+          <button-ui slot="action" text="Save current view" variant="primary" size="sm" icon-leading="bookmark-simple"></button-ui>
+        </header>
+        <section bleed>
+          <list-ui divider contained>
+            <list-item-ui>
+              <row-ui gap="3" align="start">
+                <col-ui gap="1" grow>
+                  <text-ui strong>My open issues</text-ui>
+                  <row-ui gap="1" wrap>
+                    <tag-ui size="sm">assignee=me</tag-ui>
+                    <tag-ui size="sm">status=open</tag-ui>
+                  </row-ui>
+                </col-ui>
+                <text-ui color="subtle" size="sm">12 results · 3 min ago</text-ui>
+              </row-ui>
+            </list-item-ui>
+            <list-item-ui>
+              <row-ui gap="3" align="start">
+                <col-ui gap="1" grow>
+                  <text-ui strong>Q2 customer escalations</text-ui>
+                  <row-ui gap="1" wrap>
+                    <tag-ui size="sm">label=customer</tag-ui>
+                    <tag-ui size="sm">priority=p1</tag-ui>
+                    <tag-ui size="sm">created≥2026-04-01</tag-ui>
+                  </row-ui>
+                </col-ui>
+                <text-ui color="subtle" size="sm">7 results · today</text-ui>
+              </row-ui>
+            </list-item-ui>
+            <list-item-ui>
+              <row-ui gap="3" align="start">
+                <col-ui gap="1" grow>
+                  <text-ui strong>Stale PRs</text-ui>
+                  <row-ui gap="1" wrap>
+                    <tag-ui size="sm">type=pr</tag-ui>
+                    <tag-ui size="sm">updated&lt;30d</tag-ui>
+                    <tag-ui size="sm">status=open</tag-ui>
+                  </row-ui>
+                </col-ui>
+                <text-ui color="subtle" size="sm">23 results · 1 hour ago</text-ui>
+              </row-ui>
+            </list-item-ui>
+            <list-item-ui>
+              <row-ui gap="3" align="start">
+                <col-ui gap="1" grow>
+                  <text-ui strong>Recent docs from team</text-ui>
+                  <row-ui gap="1" wrap>
+                    <tag-ui size="sm">type=doc</tag-ui>
+                    <tag-ui size="sm">author∈team</tag-ui>
+                    <tag-ui size="sm">edited≤7d</tag-ui>
+                  </row-ui>
+                </col-ui>
+                <text-ui color="subtle" size="sm">31 results · 4 hours ago</text-ui>
+              </row-ui>
+            </list-item-ui>
+          </list-ui>
+        </section>
+      </card-ui>
+    </div>
+  </div>
+</section>
+
+<section data-section data-property="composition">
+  <h2 variant="section">Composition rules</h2>
+  <ul>
+    <li><strong>Result count + timing in the header</strong> — "42 results · 0.18s" reads as "the search worked"; bare lists feel uncertain.</li>
+    <li><strong>Snippets quote the source, not paraphrase</strong> — surrounding the matched term in the actual text builds trust faster than a synthesized summary.</li>
+    <li><strong>Group when the catalog is heterogeneous</strong> — flat is fine if all results share a type; group when "people / docs / projects" all share a query.</li>
+    <li><strong>Recents are queries, not results</strong> — clicking a recent re-runs the search, it doesn't open the previous result. The semantic distinction matters.</li>
+    <li><strong>Filter chips inside saved-view rows replace prose</strong> — "type=pr · updated&lt;30d" is faster to scan than "Pull requests updated in the last 30 days".</li>
+    <li><strong>Saved views are user-named</strong> — the system never auto-generates a name. "Untitled view" is the placeholder; users rename or discard.</li>
+  </ul>
+</section>
+
+<section data-section data-property="cross-references">
+  <h2 variant="section">See also</h2>
+  <ul>
+    <li><a href="/site/components/search">search-ui</a> — input primitive (debounce, default, name, placeholder, value).</li>
+    <li><a href="/site/components/list">list-ui</a> · <a href="/site/components/list-item">list-item-ui</a> — result-row anatomy.</li>
+    <li><a href="/site/components/menu">menu-ui</a> — recents menu surface.</li>
+    <li><a href="/site/components/command">command-ui</a> — Cmd+K palette (sibling to search).</li>
+    <li><a href="/site/patterns/filter-bar">filter-bar</a> — runtime filter system; saved views are persisted filter sets.</li>
+    <li><a href="/site/components/empty-state">empty-state-ui</a> — for "no results" surface.</li>
+  </ul>
+</section>

package/patterns/search-discovery/search-discovery.html

@@ -0,0 +1,58 @@
+<!DOCTYPE html>
+<html lang="en" theme="auto">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Search &amp; Discovery (pattern) — AdiaUI</title>
+
+  <!-- Token base -->
+  <link rel="stylesheet" href="../../styles/resets.css">
+  <link rel="stylesheet" href="../../styles/tokens.css">
+
+  <!-- Component CSS — primitives this pattern composes -->
+  <link rel="stylesheet" href="../../components/avatar/avatar.css">
+  <link rel="stylesheet" href="../../components/button/button.css">
+  <link rel="stylesheet" href="../../components/card/card.css">
+  <link rel="stylesheet" href="../../components/col/col.css">
+  <link rel="stylesheet" href="../../components/icon/icon.css">
+  <link rel="stylesheet" href="../../components/list/list.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/avatar/avatar.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/icon/icon.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/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('./search-discovery.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 search-discovery.examples.html — ${err.message}</p>`;
+      console.error('[search-discovery.html]', err);
+    }
+  </script>
+
+</body>
+</html>