@adia-ai/web-components 0.6.6 → 0.6.7

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog — @adia-ai/web-components
 
+## [0.6.7] — 2026-05-19
+
+### Added
+- **`<name>.examples.md` ships in npm package** (96 components, ~67KB total).
+  Generated by `scripts/build/generate-examples-md.mjs` from `<name>.examples.html`.
+  External consumers can now read canonical markup fragments directly from
+  `node_modules/@adia-ai/web-components/components/<name>/<name>.examples.md`.
+- **`custom-elements.json` ships in npm package** (W3C Custom Elements Manifest v2.1.0).
+  Generated from per-component yaml files. Enables IDE LSP autocomplete and
+  cross-tool interop (Storybook, VS Code WC extensions).
+- **`npx @adia-ai/web-components doc <name>` CLI** prints yaml summary + live
+  demo URL + first example fragment for any component. Bare `doc` lists all.
+- **`USAGE.md § Data binding with data-stream-*`** new top-level section
+  covering the declarative `data-stream-*` attribute family (was previously
+  undocumented despite being used in 12+ components).
+
 ## [0.6.6] — 2026-05-18
 
 ### Added

package/USAGE.md

@@ -14,11 +14,12 @@ The complete reference for engineers and agents **integrating** AdiaUI into an a
 4. [Property binding patterns (templates / framework integration)](#property-binding-patterns)
 5. [Event contract — `CustomEvent` with `detail`](#event-contract)
 6. [Form participation — `UIFormElement` + `ElementInternals`](#form-participation)
-7. [Lifecycle — `connected` / `render` / `updated` / `disconnected`](#lifecycle)
-8. [Theming, density, size](#theming-density-size)
-9. [Registration — auto vs explicit](#registration--auto-vs-explicit)
-10. [TypeScript](#typescript)
-11. [Anti-patterns](#anti-patterns)
+7. [Data binding with `data-stream-*`](#data-binding-with-data-stream-)
+8. [Lifecycle — `connected` / `render` / `updated` / `disconnected`](#lifecycle)
+9. [Theming, density, size](#theming-density-size)
+10. [Registration — auto vs explicit](#registration--auto-vs-explicit)
+11. [TypeScript](#typescript)
+12. [Anti-patterns](#anti-patterns)
 
 ---
 
@@ -461,6 +462,100 @@ form.addEventListener('submit', (e) => {
 
 ---
 
+## Data binding with `data-stream-*`
+
+Many AdiaUI components (`<chart-ui>`, `<heatmap-ui>`, `<table-ui>`, `<stat-ui>`, `<progress-row-ui>`, and ~7 others) support **declarative remote-data binding** via the `data-stream-*` attribute family. You point a component at a URL, and it self-fetches (REST poll) or self-subscribes (SSE) and pushes the result into one of its properties. No JS glue required.
+
+This is the canonical "wire a component to a backend" pattern in AdiaUI. Reach for it before writing a `fetch()` loop in your app code.
+
+### Concept
+
+A component that opts in watches its `data-stream-*` attributes. When `data-stream-src` is set on a connected element, the component starts a transport (poll, SSE, or manual) and assigns each payload to a target property (e.g. `data` on `<table-ui>`, `value` on `<stat-ui>`). Change the attribute and the transport restarts; remove the attribute (or disconnect the element) and the transport tears down.
+
+Because the binding is attribute-driven, it survives SSR, server-rendered partials, htmx swaps, framework hydration, and templating engines that have no concept of property assignment.
+
+### Attribute reference
+
+| Attribute | Purpose | Default |
+|---|---|---|
+| `data-stream-src` | URL — REST endpoint or SSE source. Setting this activates the binding. | (required) |
+| `data-stream-mode` | `"poll"`, `"sse"`, or `"manual"`. `manual` fetches once on connect and on attribute change. | `"poll"` |
+| `data-stream-interval` | Poll interval in milliseconds. Ignored for `sse` / `manual`. | `5000` |
+| `data-stream-path` | Dot-path into the JSON response to extract before binding (e.g. `claims` extracts `response.claims`; `data.items` extracts `response.data.items`). | (whole response) |
+| `data-stream-target` | Which component property receives the payload. | component-specific (`data` for `<table-ui>`, `value` for `<stat-ui>`, `data` for `<chart-ui>`, …) |
+| `data-stream-method` | HTTP method for REST mode. `POST` is supported when you need a request body via headers/config. | `"GET"` |
+| `data-stream-headers` | JSON-stringified object of request headers (e.g. `'{"Authorization":"Bearer …"}'`). | `null` |
+| `data-stream-id` | Logical transport key. Multiple elements with the same `data-stream-id` share one underlying fetch/SSE connection. | (per-element) |
+
+### REST polling
+
+```html
+<table-ui
+  data-stream-src="/api/claims"
+  data-stream-interval="10000"
+  data-stream-target="data"
+></table-ui>
+```
+
+The table fetches `/api/claims` every 10s and assigns the response to its `data` property. If the response is wrapped (e.g. `{ claims: [...] }`), add `data-stream-path="claims"` to drill in.
+
+### SSE streaming
+
+```html
+<stat-ui
+  label="Active"
+  data-stream-src="/api/active-count"
+  data-stream-mode="sse"
+  data-stream-target="value"
+></stat-ui>
+```
+
+Opens an `EventSource` against `/api/active-count`. Each SSE message's `data` field is JSON-parsed (when possible) and pushed into the stat's `value`. The connection closes on disconnect.
+
+### Shared transport
+
+When two or more components need the same source, give them a matching `data-stream-id` and they will share a single fetch/SSE subscription:
+
+```html
+<table-ui
+  data-stream-src="/api/claims"
+  data-stream-id="shared-claims"
+  data-stream-target="data"
+></table-ui>
+
+<stat-ui
+  label="Total"
+  data-stream-src="/api/claims"
+  data-stream-id="shared-claims"
+  data-stream-path="length"
+  data-stream-target="value"
+></stat-ui>
+```
+
+One request feeds both. Each element still applies its own `data-stream-path` and `data-stream-target` independently. The shared transport is reference-counted; the last element to disconnect tears it down.
+
+### SSR / server rendering
+
+`data-stream-*` is **client-only**. Server-rendered markup that contains these attributes is safe — the attributes are just strings on the element — and the transport only activates once the component is upgraded in the browser. This means you can:
+
+- Server-render the initial empty/skeleton state of a `<table-ui>` and let the client take over.
+- Emit `data-stream-*` from any templating layer (Jinja, ERB, Handlebars, htmx fragments) without server-side coupling to the data-stream runtime.
+- Hydrate framework apps without special-casing — React/Vue/Svelte just need to render the attribute; they do not need to subscribe.
+
+If you need a server-rendered first paint of *real* data, render it normally (slot or attribute) — the data-stream binding will replace it on first successful payload.
+
+### Authoritative source
+
+The implementation lives at:
+
+```
+packages/web-components/core/data-stream.js
+```
+
+A component opts in by declaring a `data_stream:` block in its YAML descriptor (see `packages/web-components/components/*/*.yaml`). That block is the source of truth for which target properties are bindable and which defaults apply for that specific component. When in doubt, read the component's YAML and `core/data-stream.js` — this document is a discoverability summary, not a spec.
+
+---
+
 ## Lifecycle
 
 `UIElement` exposes four overridable lifecycle methods. Defaults are no-ops. Override what you need:

package/bin/doc.mjs

@@ -0,0 +1,379 @@
+#!/usr/bin/env node
+/**
+ * Usage:
+ *   npx @adia-ai/web-components doc button
+ *   npx @adia-ai/web-components doc field
+ *   npx @adia-ai/web-components doc            # list all components
+ *
+ * Prints a quick summary + live demo URL + first example fragment for any
+ * AdiaUI component. Reads from the installed package's yaml/.examples.md
+ * (falls back to <name>.examples.html if .md is not present).
+ *
+ * No external yaml dependency — uses a minimal regex-based parser scoped
+ * to the small subset of fields we need: name, tag, component,
+ * description, props, slots, events.
+ */
+
+import { readFileSync, existsSync, readdirSync, statSync } from 'node:fs';
+import { resolve, dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// bin/ lives at packages/web-components/bin/, components/ is one level up
+const COMPONENTS_DIR = resolve(__dirname, '..', 'components');
+const DEMO_BASE = 'https://ui-kit.exe.xyz/site/components';
+
+/* ------------------------------------------------------------------ */
+/*  Minimal YAML extractor                                             */
+/* ------------------------------------------------------------------ */
+/**
+ * Parses just the subset of YAML used by AdiaUI component yaml files:
+ *  - top-level scalar keys (name, tag, component, description, …)
+ *  - top-level mapping keys whose values are mappings of leaf scalars
+ *    (props, slots, events)
+ *
+ * Returns:
+ *   {
+ *     name, tag, component, description,
+ *     props:  { propName:  { description, type, default, enum?, ... } },
+ *     slots:  { slotName:  { description } },
+ *     events: { eventName: { description, type? } },
+ *   }
+ *
+ * Defensive: any parse error returns a partial object plus an `_errors`
+ * array — the caller decides how to surface failures.
+ */
+function parseYaml(source) {
+  const out = {
+    name: '',
+    tag: '',
+    component: '',
+    description: '',
+    props: {},
+    slots: {},
+    events: {},
+    _errors: [],
+  };
+
+  // Strip comments + trailing whitespace, keep blank lines for block detection
+  const rawLines = source.split(/\r?\n/);
+  const lines = rawLines.map((l) => {
+    // strip line comments unless inside a quoted string (rough heuristic)
+    const m = l.match(/^([^#"']*)(#.*)?$/);
+    return m ? m[1].replace(/\s+$/, '') : l;
+  });
+
+  /** Find the line range of a top-level key block (indent === 0). */
+  function blockRange(key) {
+    const startRe = new RegExp(`^${key}\\s*:\\s*(.*)$`);
+    let start = -1;
+    let inlineValue = null;
+    for (let i = 0; i < lines.length; i++) {
+      const m = lines[i].match(startRe);
+      if (m && !lines[i].startsWith(' ') && !lines[i].startsWith('\t')) {
+        start = i;
+        inlineValue = m[1];
+        break;
+      }
+    }
+    if (start === -1) return null;
+
+    let end = lines.length;
+    for (let i = start + 1; i < lines.length; i++) {
+      const l = lines[i];
+      if (l === '') continue;
+      // next top-level key (no leading whitespace, contains ':')
+      if (!/^\s/.test(l) && /^[A-Za-z_$][\w$-]*\s*:/.test(l)) {
+        end = i;
+        break;
+      }
+    }
+    return { start, end, inlineValue };
+  }
+
+  /** Unquote a yaml scalar value (handles "…", '…', |, >, bare). */
+  function unquote(v) {
+    if (v == null) return '';
+    let s = String(v).trim();
+    if (s === '') return '';
+    if (
+      (s.startsWith('"') && s.endsWith('"')) ||
+      (s.startsWith("'") && s.endsWith("'"))
+    ) {
+      return s.slice(1, -1);
+    }
+    return s;
+  }
+
+  /** Extract a top-level scalar field (single-line OR block scalar). */
+  function scalar(key) {
+    const r = blockRange(key);
+    if (!r) return '';
+    const head = r.inlineValue.trim();
+    // block scalar?  `description: >-` / `>` / `|`
+    if (head === '>' || head === '>-' || head === '|' || head === '|-') {
+      const buf = [];
+      for (let i = r.start + 1; i < r.end; i++) {
+        const l = lines[i];
+        if (l === '') {
+          buf.push('');
+          continue;
+        }
+        if (!/^\s/.test(l)) break;
+        buf.push(l.replace(/^\s+/, ''));
+      }
+      const joined = buf.join(' ').replace(/\s+/g, ' ').trim();
+      return joined;
+    }
+    return unquote(head);
+  }
+
+  out.name = scalar('name');
+  out.tag = scalar('tag');
+  out.component = scalar('component');
+  out.description = scalar('description');
+
+  /**
+   * Parse a mapping-of-mappings block (props/slots/events).
+   * Each child key is a 2-space-indented identifier, its value is a
+   * 4-space-indented mapping of leaf scalars.
+   */
+  function mappingOfMappings(key) {
+    const r = blockRange(key);
+    if (!r) return {};
+    const result = {};
+    let currentKey = null;
+    let currentField = null; // for block-scalar accumulation
+    let currentBuf = null;
+    let currentIndent = 0;
+
+    const flushBlockScalar = () => {
+      if (currentKey && currentField && currentBuf) {
+        const joined = currentBuf.join(' ').replace(/\s+/g, ' ').trim();
+        result[currentKey][currentField] = joined;
+      }
+      currentField = null;
+      currentBuf = null;
+    };
+
+    for (let i = r.start + 1; i < r.end; i++) {
+      const l = lines[i];
+      if (l === '') continue;
+      const indent = l.match(/^( *)/)[0].length;
+
+      // 2-space child key:  "  propName:" or "  propName: value"
+      if (indent === 2) {
+        flushBlockScalar();
+        const m = l.match(/^ {2}([^:\s]+)\s*:\s*(.*)$/);
+        if (m) {
+          currentKey = m[1];
+          result[currentKey] = {};
+          const v = m[2].trim();
+          if (v && v !== '>' && v !== '>-' && v !== '|' && v !== '|-') {
+            // shorthand "  prop: desc"
+            result[currentKey].description = unquote(v);
+          }
+        }
+        continue;
+      }
+
+      // 4-space leaf field:  "    description: …"
+      if (indent === 4 && currentKey) {
+        flushBlockScalar();
+        const m = l.match(/^ {4}([^:\s]+)\s*:\s*(.*)$/);
+        if (m) {
+          const fk = m[1];
+          const v = m[2].trim();
+          if (v === '>' || v === '>-' || v === '|' || v === '|-') {
+            currentField = fk;
+            currentBuf = [];
+            currentIndent = 6;
+          } else {
+            result[currentKey][fk] = unquote(v);
+          }
+        }
+        continue;
+      }
+
+      // continuation of a block scalar (indent >= currentIndent)
+      if (currentField && currentBuf && indent >= currentIndent) {
+        currentBuf.push(l.slice(currentIndent));
+        continue;
+      }
+
+      // 6-space (or deeper) list/enum entries we ignore for now, but
+      // capture enum lists for props (best-effort).
+      if (indent >= 6 && currentKey) {
+        const em = l.match(/^\s+-\s+(.*)$/);
+        if (em && currentField === 'enum') {
+          currentBuf = currentBuf || [];
+          // we don't really store enum lists here; left for the
+          // manifest generator which re-parses with its own logic.
+        }
+      }
+    }
+    flushBlockScalar();
+    return result;
+  }
+
+  try {
+    out.props = mappingOfMappings('props');
+  } catch (e) {
+    out._errors.push(`props: ${e.message}`);
+  }
+  try {
+    out.slots = mappingOfMappings('slots');
+  } catch (e) {
+    out._errors.push(`slots: ${e.message}`);
+  }
+  try {
+    out.events = mappingOfMappings('events');
+  } catch (e) {
+    out._errors.push(`events: ${e.message}`);
+  }
+
+  return out;
+}
+
+/* ------------------------------------------------------------------ */
+/*  Pretty-print helpers                                               */
+/* ------------------------------------------------------------------ */
+function wrap(s, width = 76, indent = '    ') {
+  if (!s) return '';
+  const words = String(s).split(/\s+/);
+  const lines = [];
+  let line = '';
+  for (const w of words) {
+    if ((line + ' ' + w).trim().length > width) {
+      lines.push(line);
+      line = w;
+    } else {
+      line = (line ? line + ' ' : '') + w;
+    }
+  }
+  if (line) lines.push(line);
+  return lines.map((l) => indent + l).join('\n');
+}
+
+function printSection(title, entries, keyLabel) {
+  const keys = Object.keys(entries || {});
+  if (keys.length === 0) return;
+  console.log(`${title} (${keys.length})`);
+  for (const k of keys) {
+    const e = entries[k] || {};
+    const meta = [];
+    if (e.type) meta.push(e.type);
+    if (e.default !== undefined && e.default !== '') meta.push(`default: ${e.default}`);
+    const head = meta.length ? `  • ${k}  [${meta.join(', ')}]` : `  • ${k}`;
+    console.log(head);
+    if (e.description) console.log(wrap(e.description, 72, '      '));
+  }
+  console.log('');
+}
+
+function firstExampleFragment(md) {
+  // First markdown ## …  block, or whole file if no headings.
+  const lines = md.split(/\r?\n/);
+  let start = -1;
+  let end = lines.length;
+  for (let i = 0; i < lines.length; i++) {
+    if (/^##\s+/.test(lines[i])) {
+      if (start === -1) {
+        start = i;
+      } else {
+        end = i;
+        break;
+      }
+    }
+  }
+  if (start === -1) return md.trim();
+  return lines.slice(start, end).join('\n').trim();
+}
+
+function firstHtmlFragment(html) {
+  // Heuristic: first <section> … </section>, else first <!-- example: --> … next, else first ~30 lines.
+  const sect = html.match(/<section[\s\S]*?<\/section>/i);
+  if (sect) return sect[0].trim();
+  const lines = html.split(/\r?\n/);
+  return lines.slice(0, 30).join('\n').trim();
+}
+
+/* ------------------------------------------------------------------ */
+/*  Main                                                               */
+/* ------------------------------------------------------------------ */
+function listComponents() {
+  let entries;
+  try {
+    entries = readdirSync(COMPONENTS_DIR);
+  } catch (e) {
+    console.error(`Cannot read components directory: ${COMPONENTS_DIR}`);
+    process.exit(1);
+  }
+  const names = [];
+  for (const d of entries) {
+    let s;
+    try { s = statSync(join(COMPONENTS_DIR, d)); } catch { continue; }
+    if (!s.isDirectory()) continue;
+    const yamlPath = join(COMPONENTS_DIR, d, `${d}.yaml`);
+    if (existsSync(yamlPath)) names.push(d);
+  }
+  names.sort();
+  console.log(`AdiaUI — ${names.length} components\n`);
+  for (const c of names) console.log(`  ${c}`);
+  console.log(`\nRun: npx @adia-ai/web-components doc <name>\n`);
+}
+
+const name = process.argv[2];
+if (!name) {
+  listComponents();
+  process.exit(0);
+}
+
+const yamlPath = join(COMPONENTS_DIR, name, `${name}.yaml`);
+if (!existsSync(yamlPath)) {
+  console.error(`Component '${name}' not found in catalog.`);
+  console.error(`Try: npx @adia-ai/web-components doc    # list all`);
+  process.exit(1);
+}
+
+const source = readFileSync(yamlPath, 'utf-8');
+const data = parseYaml(source);
+
+console.log('');
+console.log(`${data.name || name}  <${data.tag || name + '-ui'}>`);
+console.log('─'.repeat(60));
+if (data.description) {
+  console.log(wrap(data.description, 76, ''));
+  console.log('');
+}
+
+printSection('Props',  data.props,  'prop');
+printSection('Slots',  data.slots,  'slot');
+printSection('Events', data.events, 'event');
+
+if (data._errors && data._errors.length) {
+  console.log('Parse warnings:');
+  for (const e of data._errors) console.log(`  - ${e}`);
+  console.log('');
+}
+
+console.log(`Live demo: ${DEMO_BASE}/${name}`);
+console.log('');
+
+const examplesMdPath = join(COMPONENTS_DIR, name, `${name}.examples.md`);
+const examplesHtmlPath = join(COMPONENTS_DIR, name, `${name}.examples.html`);
+if (existsSync(examplesMdPath)) {
+  const src = readFileSync(examplesMdPath, 'utf-8');
+  console.log('Example');
+  console.log('─'.repeat(60));
+  console.log(firstExampleFragment(src));
+  console.log('');
+} else if (existsSync(examplesHtmlPath)) {
+  const src = readFileSync(examplesHtmlPath, 'utf-8');
+  console.log('Example (HTML)');
+  console.log('─'.repeat(60));
+  console.log(firstHtmlFragment(src));
+  console.log('');
+}

package/components/accordion/accordion.examples.md

@@ -0,0 +1,49 @@
+# accordion — Examples
+
+## basic
+
+```html
+<accordion-ui>
+  <accordion-item-ui text="What is AdiaUI?">
+    <p>AdiaUI is a zero-dependency vanilla JS web component library for building modern interfaces. It uses native custom elements, OKLCH colors, and @scope CSS isolation.</p>
+  </accordion-item-ui>
+  <accordion-item-ui text="Do I need a build tool?">
+    <p>No. AdiaUI components are plain ES modules. Import them directly in a script tag or from a module bundler -- both work without configuration.</p>
+  </accordion-item-ui>
+  <accordion-item-ui text="How are styles scoped?">
+    <p>Each component uses CSS @scope blocks keyed to the element tag name. This provides isolation without Shadow DOM, keeping components inspectable in DevTools.</p>
+  </accordion-item-ui>
+</accordion-ui>
+```
+
+## multiple
+
+```html
+<accordion-ui multiple>
+  <accordion-item-ui text="Section A" open>
+    <p>This section starts open and remains open when you expand other sections.</p>
+  </accordion-item-ui>
+  <accordion-item-ui text="Section B">
+    <p>Open this alongside Section A to see multiple open behavior.</p>
+  </accordion-item-ui>
+  <accordion-item-ui text="Section C">
+    <p>All three can be expanded at the same time.</p>
+  </accordion-item-ui>
+</accordion-ui>
+```
+
+## pre-opened
+
+```html
+<accordion-ui>
+  <accordion-item-ui text="Closed by default">
+    <p>This item is collapsed initially.</p>
+  </accordion-item-ui>
+  <accordion-item-ui text="Open by default" open>
+    <p>This item renders expanded because it has the open attribute.</p>
+  </accordion-item-ui>
+  <accordion-item-ui text="Also closed">
+    <p>Another collapsed item.</p>
+  </accordion-item-ui>
+</accordion-ui>
+```

package/components/action-list/action-list.examples.md

@@ -0,0 +1,33 @@
+# action-list — Examples
+
+## Basic
+
+```html
+<action-list-ui>
+  <action-item-ui text="New Project" value="new"></action-item-ui>
+  <action-item-ui text="Import Data" value="import"></action-item-ui>
+  <action-item-ui text="Export Report" value="export"></action-item-ui>
+</action-list-ui>
+```
+
+## With Icons
+
+```html
+<action-list-ui>
+  <action-item-ui icon="plus" text="New Project" value="new"></action-item-ui>
+  <action-item-ui icon="users" text="Invite Team" value="invite"></action-item-ui>
+  <action-item-ui icon="download" text="Export Data" value="export"></action-item-ui>
+  <action-item-ui icon="gear" text="Settings" value="settings"></action-item-ui>
+</action-list-ui>
+```
+
+## Destructive Items
+
+```html
+<action-list-ui>
+  <action-item-ui icon="pencil" text="Edit" value="edit"></action-item-ui>
+  <action-item-ui icon="copy" text="Duplicate" value="duplicate"></action-item-ui>
+  <action-item-ui icon="archive" text="Archive" value="archive"></action-item-ui>
+  <action-item-ui icon="trash" text="Delete" value="delete" variant="danger"></action-item-ui>
+</action-list-ui>
+```

package/components/agent-artifact/agent-artifact.examples.md

@@ -0,0 +1,28 @@
+# agent-artifact — Examples
+
+## code body
+
+```html
+<agent-artifact-ui title="product-card-v2" kind="A2UI" icon="layout">
+  <button-ui slot="primary" text="Open in canvas" icon="arrows-out-simple" variant="outline" size="sm"></button-ui>
+  <button-ui slot="secondary" text="Copy" icon="copy" variant="ghost" size="sm"></button-ui>
+</agent-artifact-ui>
+```
+
+## tones
+
+```html
+<agent-artifact-ui title="validation-failed" kind="TICKET" icon="warning" tone="warning">
+  <button-ui slot="secondary" text="Download" icon="download" variant="ghost" size="sm"></button-ui>
+  <div style="font-size: var(--a-ui-sm); color: var(--a-fg-muted); line-height: 1.5;">Validation score 62/100 — the output is missing a price badge and has an unlabeled button. Retrying would help.</div>
+</agent-artifact-ui>
+```
+
+## Usage
+
+```html
+<agent-artifact-ui title="product-card" kind="A2UI" icon="layout">
+  <button-ui slot="primary" text="Open in canvas" icon="arrows-out-simple"></button-ui>
+  <button-ui slot="secondary" text="Copy" icon="copy"></button-ui>
+</agent-artifact-ui>
+```

package/components/agent-feedback-bar/agent-feedback-bar.examples.md

@@ -0,0 +1,24 @@
+# agent-feedback-bar — Examples
+
+## thumbs only
+
+```html
+<agent-feedback-bar-ui id="demo-basic"></agent-feedback-bar-ui>
+```
+
+## with save
+
+```html
+<agent-feedback-bar-ui id="demo-save" save-label="Save pattern"></agent-feedback-bar-ui>
+```
+
+## Usage
+
+```html
+<agent-feedback-bar-ui save-label="Save pattern"></agent-feedback-bar-ui>
+el.addEventListener('feedback-rate', (e) => persist(e.detail.rating));
+el.addEventListener('feedback-save', async () => {
+  const name = await savePattern(...);
+  el.setStatus(`Saved as "${name}"`, { lock: 'save' });
+});
+```

package/components/agent-questions/agent-questions.examples.md

@@ -0,0 +1,13 @@
+# agent-questions — Examples
+
+## single select
+
+```html
+<agent-questions-ui id="demo-single" question="Which direction fits best?" helper="Pick one — we can revisit later."></agent-questions-ui>
+```
+
+## multi select
+
+```html
+<agent-questions-ui id="demo-multi" multi question="Which features should we include?" helper="Select any that apply." submit-label="Generate"></agent-questions-ui>
+```