@adia-ai/adia-ui-factory 0.2.2 → 0.2.3

package/skills/adia-ui-kit/references/flows-content.md

@@ -0,0 +1,206 @@
+# §Flows — Error pages, kanban boards, agent surfaces
+
+> **Loading note.** Reference bundle extracted from `SKILL.md` per the
+> §LoadingProtocol inversion contract (v2.20.3+). Load via
+> `skill_view(name='adia-ui-kit', file_path='references/flows-content.md')`
+> When wiring content-tier surfaces — 404/500 error pages, kanban with drag-friendly columns, agent reasoning + activity + chat panes. Skip if your task doesn't involve these surfaces — the
+> seed has a stub naming each flow + the load invocation.
+
+### Error pages (404, 500, maintenance)
+
+All three share the same shape: centered hero, brand mark, heading,
+explanatory text, optional alert with diagnostic info, primary action.
+The canonical wrapper is `<simple-shell centered>` + `<simple-hero>` —
+substrate ships this exactly for error / 404 / 500 / maintenance / thank-you
+flows. Do **not** hand-roll `<main style="display: grid; place-items: center">`
++ `<card-ui>` for these surfaces — that re-implements `[centered]` and
+bypasses the canonical slot vocabulary.
+
+**404 — page not found:**
+
+```html
+<simple-shell centered>
+  <simple-hero>
+    <img slot="heading" src="/logo.svg" alt="" style="height: 4rem" />
+    <h1 slot="heading">404 — Page not found</h1>
+    <p slot="lede">We couldn't find that page. It may have moved or never existed.</p>
+    <div slot="actions">
+      <button-ui text="Go to home" variant="primary" icon="house"
+        onclick="location.href = '/'"></button-ui>
+      <button-ui text="Go back" variant="outline" icon="arrow-left"
+        onclick="history.back()"></button-ui>
+    </div>
+    <alert-ui variant="info" icon="map-trifold">
+      <span slot="content">Path: <code>/that/route/that/wasnt/found</code></span>
+    </alert-ui>
+  </simple-hero>
+</simple-shell>
+```
+
+**500 — server error** (substitutions: `<alert-ui variant="warning" icon="warning">`,
+heading "Something went wrong", trace ID + "Try again" / "Status page" actions).
+
+**Maintenance** (substitutions: `<alert-ui variant="info" icon="wrench">`, heading
+"We'll be right back", window/affected services + "Status page" action).
+
+> **Pitfall:** error pages render before `installIconLoadersForRegistered`
+> if the JS fails to load. Inline an SVG fallback for the logo, and prefer
+> `text` over `icon=` for critical alerts on the 500 path.
+
+> **CSS-import note:** when using the bundler path, import the simple-shell
+> stylesheet alongside the primitives bundle:
+> `import '@adia-ai/web-modules/simple/simple-shell.css';`
+
+---
+
+
+### Kanban board (3-column drag-friendly)
+
+```html
+<grid-ui columns="3" gap="4">
+  <card-ui raw>
+    <header>
+      <row-ui gap="2" align="center">
+        <text-ui weight="semibold">To Do</text-ui>
+        <badge-ui text="3" variant="muted" size="sm"></badge-ui>
+      </row-ui>
+    </header>
+    <section>
+      <col-ui gap="2">
+        <card-ui size="sm" draggable><section><text-ui>Design system tokens</text-ui></section></card-ui>
+        <card-ui size="sm" draggable><section><text-ui>Component audit</text-ui></section></card-ui>
+        <card-ui size="sm" draggable><section><text-ui>Accessibility review</text-ui></section></card-ui>
+      </col-ui>
+    </section>
+  </card-ui>
+  <card-ui raw>
+    <header>
+      <row-ui gap="2" align="center">
+        <text-ui weight="semibold">In Progress</text-ui>
+        <badge-ui text="2" variant="accent" size="sm"></badge-ui>
+      </row-ui>
+    </header>
+    <section>
+      <col-ui gap="2">
+        <card-ui size="sm" draggable><section><text-ui>Dark mode palette</text-ui></section></card-ui>
+        <card-ui size="sm" draggable><section><text-ui>Button variants</text-ui></section></card-ui>
+      </col-ui>
+    </section>
+  </card-ui>
+  <card-ui raw>
+    <header>
+      <row-ui gap="2" align="center">
+        <text-ui weight="semibold">Done</text-ui>
+        <badge-ui text="5" variant="success" size="sm"></badge-ui>
+      </row-ui>
+    </header>
+    <section><!-- done cards --></section>
+  </card-ui>
+</grid-ui>
+```
+
+The `draggable` trait wires native HTML5 drag-and-drop on each card.
+Listen for `dragstart` / `dragover` / `drop` on the column `<section>` to
+move cards between columns.
+
+---
+
+
+### Agent surface (reasoning + activity + chat)
+
+The full AI/agent UI: reasoning trace, streaming chat, activity feed,
+artifact previews.
+
+**Chat streaming surface:**
+
+```html
+<card-ui raw style="height: 100%">
+  <section style="overflow: auto; flex: 1">
+    <chat-thread-ui id="thread" streaming>
+      <div role="user">What's the status?</div>
+      <div role="assistant">Processing your request...</div>
+    </chat-thread-ui>
+  </section>
+  <footer>
+    <row-ui gap="2" align="center">
+      <chat-input-ui id="prompt" placeholder="Ask follow-up..." style="flex:1"></chat-input-ui>
+      <button-ui id="send-btn" icon="paper-plane-right" variant="primary" size="sm"></button-ui>
+    </row-ui>
+  </footer>
+</card-ui>
+```
+
+**Live reasoning trace** (paired alongside the chat):
+
+```html
+<card-ui>
+  <header>
+    <h3>Agent Activity</h3>
+    <text-ui slot="description" color="subtle">Live reasoning trace</text-ui>
+  </header>
+  <section>
+    <col-ui gap="3">
+      <agent-trace-ui></agent-trace-ui>
+      <agent-reasoning-ui></agent-reasoning-ui>
+      <agent-artifact-ui></agent-artifact-ui>
+    </col-ui>
+  </section>
+</card-ui>
+```
+
+**Imports needed** (none are in the barrel for the agent cluster):
+
+```js
+import '@adia-ai/web-components/components/chat-thread/chat-thread.js';
+import '@adia-ai/web-components/components/chat-thread/chat-input.js';
+import '@adia-ai/web-components/components/agent-reasoning/agent-reasoning.js';
+import '@adia-ai/web-components/components/agent-trace/agent-trace.js';
+import '@adia-ai/web-components/components/agent-artifact/agent-artifact.js';
+import '@adia-ai/web-components/components/agent-feedback-bar/agent-feedback-bar.js';
+import '@adia-ai/web-components/components/agent-suggestions/agent-suggestions.js';
+```
+
+**Sending a message + handling streaming:**
+
+```js
+const thread = document.getElementById('thread');
+const prompt = document.getElementById('prompt');
+const send = document.getElementById('send-btn');
+
+send.addEventListener('press', async () => {
+  const text = prompt.value.trim();
+  if (!text) return;
+  prompt.value = '';
+
+  // Add user bubble
+  thread.appendMessage({ role: 'user', content: text });
+  // Add empty assistant bubble that will fill via streaming
+  const asstId = thread.appendMessage({ role: 'assistant', content: '', streaming: true });
+
+  // Stream from /api/chat (or your LLM endpoint)
+  const res = await fetch('/api/chat', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ messages: [{ role: 'user', content: text }] }),
+  });
+  const reader = res.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = '';
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    buffer += decoder.decode(value, { stream: true });
+    // Parse SSE-style data: lines
+    for (const line of buffer.split('\n')) {
+      if (line.startsWith('data: ')) {
+        const chunk = JSON.parse(line.slice(6));
+        thread.appendToMessage(asstId, chunk.text);
+      }
+    }
+  }
+  thread.finalizeMessage(asstId);
+});
+```
+
+---
+

package/skills/adia-ui-kit/references/flows-data.md

@@ -0,0 +1,348 @@
+# §Flows — Settings, tables, dashboards, charts
+
+> **Loading note.** Reference bundle extracted from `SKILL.md` per the
+> §LoadingProtocol inversion contract (v2.20.3+). Load via
+> `skill_view(name='adia-ui-kit', file_path='references/flows-data.md')`
+> When wiring data-display surfaces — preference panes, sortable tables, KPI strips, chart-card pairings. Skip if your task doesn't involve these surfaces — the
+> seed has a stub naming each flow + the load invocation.
+
+### Settings page
+
+`aside | data-col` two-column layout. Each group is a `<section>`
+separated by `<divider-ui>`. Danger actions open `<drawer-ui>`.
+
+```html
+<admin-page-body>
+  <section-ui>
+    <article>
+
+    <section>
+      <h2>Workspace</h2>
+      <div data-section>
+        <aside><h3>Details</h3><p>Name and identify your workspace.</p></aside>
+        <col-ui gap="4">
+          <field-ui label="Workspace name">
+            <input-ui name="name" value="Acme Inc."></input-ui>
+          </field-ui>
+          <field-ui label="Slug">
+            <input-ui name="slug" prefix="/" value="acme"></input-ui>
+          </field-ui>
+          <field-ui label="Description">
+            <textarea-ui name="description" rows="3"></textarea-ui>
+          </field-ui>
+          <row-ui justify="flex-end">
+            <button-ui text="Save changes" variant="primary"></button-ui>
+          </row-ui>
+        </col-ui>
+      </div>
+    </section>
+
+    <divider-ui></divider-ui>
+
+    <section>
+      <h2>Appearance</h2>
+      <div data-section>
+        <aside><h3>Theme</h3><p>Light, dark, or system.</p></aside>
+        <col-ui>
+          <field-ui label="Color scheme" inline>
+            <segmented-ui value="auto">
+              <segment-ui value="light" text="Light"></segment-ui>
+              <segment-ui value="dark"  text="Dark"></segment-ui>
+              <segment-ui value="auto"  text="System"></segment-ui>
+            </segmented-ui>
+          </field-ui>
+        </col-ui>
+      </div>
+    </section>
+
+    <divider-ui></divider-ui>
+
+    <section>
+      <h2>Notifications</h2>
+      <div data-section>
+        <aside><h3>Preferences</h3><p>What to be notified about.</p></aside>
+        <col-ui gap="3">
+          <switch-ui name="email-digest"  label="Weekly email digest" checked></switch-ui>
+          <switch-ui name="push-mentions" label="Push on @mention"    checked></switch-ui>
+          <switch-ui name="push-assigns"  label="Push on assignment"></switch-ui>
+        </col-ui>
+      </div>
+    </section>
+
+    <divider-ui></divider-ui>
+
+    <section>
+      <h2>Danger zone</h2>
+      <div data-section>
+        <aside><h3>Delete workspace</h3><p>Permanent and irreversible.</p></aside>
+        <col-ui>
+          <button-ui text="Delete workspace" variant="danger"
+            onclick="document.getElementById('drawer-delete').open = true">
+          </button-ui>
+        </col-ui>
+      </div>
+    </section>
+
+  </article>
+  </section-ui>
+
+  <drawer-ui id="drawer-delete" side="right">
+    <card-ui>
+      <header slot="header"><span slot="heading">Delete workspace?</span></header>
+      <section>
+        <col-ui gap="4">
+          <alert-ui variant="danger" icon="warning">
+            <span slot="content">This cannot be undone.</span>
+          </alert-ui>
+          <field-ui label="Type workspace name to confirm">
+            <input-ui name="confirm" placeholder="Acme Inc."></input-ui>
+          </field-ui>
+        </col-ui>
+      </section>
+      <footer slot="footer">
+        <row-ui gap="2" justify="flex-end">
+          <button-ui text="Cancel" variant="ghost"
+            onclick="this.closest('drawer-ui').open = false"></button-ui>
+          <button-ui text="Delete" variant="danger"></button-ui>
+        </row-ui>
+      </footer>
+    </card-ui>
+  </drawer-ui>
+</admin-page-body>
+```
+
+---
+
+
+### Tables
+
+**Always pair `<table-ui>` with `<table-toolbar-ui>`.**
+Columns and data are set via JavaScript — never via HTML attributes.
+
+```html
+<card-ui>
+  <header><span slot="heading">Users</span></header>
+  <section style="padding: 0;">
+    <table-toolbar-ui id="users-toolbar"></table-toolbar-ui>
+    <table-ui id="users-table" sortable selectable striped></table-ui>
+  </section>
+</card-ui>
+
+<script type="module">
+  const table   = document.getElementById('users-table');
+  const toolbar = document.getElementById('users-toolbar');
+  toolbar.table = table;  // links search/sort/export to the table
+
+  table.columns = [
+    { key: 'name',   label: 'Name',   type: 'avatar' },
+    { key: 'email',  label: 'Email',  type: 'link' },
+    { key: 'status', label: 'Status', type: 'badge',
+      meta: { variants: { Active: 'success', Pending: 'warning', Inactive: 'danger' } } },
+    { key: 'role',   label: 'Role' },
+    { key: 'joined', label: 'Joined', type: 'date' },
+    { key: 'id',     label: '',       type: 'actions', width: 80,
+      meta: { actions: [
+        { icon: 'pencil-simple', label: 'Edit',   event: 'edit-row' },
+        { icon: 'trash',         label: 'Delete', event: 'delete-row' },
+      ] } },
+  ];
+
+  // Static data or fetch from endpoint
+  table.data = [
+    { id: 1, name: 'Alice Johnson', email: 'alice@acme.com', role: 'Engineer',
+      status: 'Active',  joined: '2024-03-15' },
+    { id: 2, name: 'Bob Smith',     email: 'bob@acme.com',   role: 'Designer',
+      status: 'Pending', joined: '2024-05-22' },
+  ];
+  // fetch('/api/users').then(r => r.json()).then(d => { table.data = d.items; });
+
+  table.addEventListener('edit-row',   e => console.log('edit',   e.detail.row));
+  table.addEventListener('delete-row', e => console.log('delete', e.detail.row));
+</script>
+```
+
+**Cell type reference:**
+
+| `type` | Renders | `meta` shape |
+|---|---|---|
+| (default) | Plain string | — |
+| `avatar` | Avatar + name | — |
+| `link` | Anchor `<a>` | `{ href: row => '/users/' + row.id }` |
+| `badge` | `<badge-ui>` | `{ variants: { Active: 'success' } }` |
+| `progress` | Progress bar | — |
+| `date` | Formatted date | `{ format: 'relative' }` |
+| `actions` | Icon buttons | `{ actions: [{icon, label, event}] }` |
+
+---
+
+
+### Dashboard + KPI
+
+```html
+<admin-page-body>
+  <section-ui data-full-bleed>
+    <col-ui gap="6">
+
+    <!-- 4-column KPI strip -->
+    <grid-ui columns="4" gap="4">
+      <card-ui size="sm"><section>
+        <stat-ui label="Revenue" value="$45,231" change="+20.1%" trend="up" icon="currency-dollar">
+        </stat-ui>
+      </section></card-ui>
+      <card-ui size="sm"><section>
+        <stat-ui label="Subscriptions" value="+2,350" change="+180%" trend="up" icon="users">
+        </stat-ui>
+      </section></card-ui>
+      <card-ui size="sm"><section>
+        <stat-ui label="Sales" value="+12,234" change="+19%" trend="up" icon="credit-card">
+        </stat-ui>
+      </section></card-ui>
+      <card-ui size="sm"><section>
+        <stat-ui label="Active Now" value="+573" change="+201" trend="up" icon="chart-bar">
+        </stat-ui>
+      </section></card-ui>
+    </grid-ui>
+
+    <!-- Chart (3 cols) + activity feed (2 cols) -->
+    <grid-ui columns="5" gap="4">
+      <card-ui style="grid-column: span 3">
+        <header><span slot="heading">Revenue over time</span></header>
+        <section>
+          <chart-ui id="revenue-chart" type="area" x="month" y="revenue"></chart-ui>
+        </section>
+      </card-ui>
+      <card-ui style="grid-column: span 2">
+        <header><span slot="heading">Recent activity</span></header>
+        <section><!-- activity list --></section>
+      </card-ui>
+    </grid-ui>
+
+    <!-- Transactions table -->
+    <card-ui>
+      <header><span slot="heading">Recent transactions</span></header>
+      <section style="padding: 0;">
+        <table-toolbar-ui id="txn-toolbar"></table-toolbar-ui>
+        <table-ui id="txn-table" sortable striped></table-ui>
+      </section>
+    </card-ui>
+
+    </col-ui>
+  </section-ui>
+  <!--
+    Note on <section-ui data-full-bleed>: admin-page-body wraps an inner
+    <section-ui> by default for centered reading-column rhythm (per
+    admin-page-body.yaml a2ui rules). Dashboards with tables/charts/
+    grids want full content width — opt into that with [data-full-bleed]
+    on the wrapping <section-ui>. For text-heavy pages (settings forms,
+    documentation), use <section-ui> without [data-full-bleed] to get
+    the centered reading column.
+  -->
+</admin-page-body>
+
+<script type="module">
+  // Charts: data MUST be set via JS — not HTML attributes
+  document.getElementById('revenue-chart').data = [
+    { month: 'Jan', revenue: 40 }, { month: 'Feb', revenue: 55 },
+    { month: 'Mar', revenue: 48 }, { month: 'Apr', revenue: 62 },
+    { month: 'May', revenue: 70 }, { month: 'Jun', revenue: 65 },
+  ];
+
+  const txn = document.getElementById('txn-table');
+  document.getElementById('txn-toolbar').table = txn;
+  txn.columns = [
+    { key: 'customer', label: 'Customer', type: 'avatar' },
+    { key: 'amount',   label: 'Amount' },
+    { key: 'status',   label: 'Status',   type: 'badge',
+      meta: { variants: { Paid: 'success', Pending: 'warning', Failed: 'danger' } } },
+    { key: 'date',     label: 'Date',     type: 'date' },
+  ];
+  // txn.data = await fetch('/api/transactions').then(r => r.json()).then(d => d.items);
+</script>
+```
+
+---
+
+
+### Charts
+
+`<chart-ui>` **requires `.data` set via JS** — HTML only declares `type`, `x`, `y`.
+
+**18 types across 5 families:**
+
+| Family | Types |
+|---|---|
+| Axis | `bar`, `line`, `area`, `scatter`, `sparkline` |
+| Categorical | `pie`, `donut`, `segments` |
+| Radial | `radar`, `radial-bar`, `gauge` |
+| Multi-series | `stacked-bar`, `grouped-bar`, `multi-line`, `composed` |
+| Flow/hierarchy | `funnel`, `treemap`, `sankey` |
+
+**Wiring template:**
+
+```html
+<chart-ui id="my-chart" type="bar" x="month" y="value"></chart-ui>
+<chart-legend-ui for="my-chart"></chart-legend-ui>
+<tooltip-ui follows="pointer"></tooltip-ui>
+
+<script type="module">
+  // Single-series (bar, line, area, scatter, sparkline)
+  document.getElementById('my-chart').data = [
+    { month: 'Jan', value: 30 }, { month: 'Feb', value: 45 },
+    { month: 'Mar', value: 28 }, { month: 'Apr', value: 62 },
+  ];
+
+  // Multi-series — extra keys beyond y become additional series
+  // el.data = [{ quarter: 'Q1', desktop: 40, mobile: 25 }, ...];
+
+  // Gauge — needs max field
+  // el.data = [{ label: 'Capacity', value: 72, max: 100 }];
+</script>
+```
+
+**KPI + sparkline card:**
+
+```html
+<card-ui size="sm">
+  <section>
+    <row-ui justify="space-between" align="flex-start">
+      <col-ui gap="1">
+        <text-ui variant="label" color="subtle">Monthly Revenue</text-ui>
+        <text-ui variant="heading-lg">$42,350</text-ui>
+        <badge-ui text="+12.5%" variant="success" icon="trend-up"></badge-ui>
+      </col-ui>
+      <chart-ui id="spark" type="sparkline" x="month" y="value"
+        style="width: 80px; height: 40px"></chart-ui>
+    </row-ui>
+  </section>
+</card-ui>
+<script type="module">
+  document.getElementById('spark').data = [
+    { month: 'Jan', value: 30 }, { month: 'Feb', value: 38 },
+    { month: 'Mar', value: 35 }, { month: 'Apr', value: 42 },
+  ];
+</script>
+```
+
+**Heatmap:**
+
+```html
+<!-- Day-grid (GitHub contributions) -->
+<heatmap-ui id="activity" type="day-grid" rows="7" cols="52"
+  start-date="2025-01-01" color-scheme="data-ramp"
+  aria-label="Activity grid"></heatmap-ui>
+
+<!-- Matrix with live data-stream -->
+<heatmap-ui type="matrix" rows="7" cols="12" color-scheme="accent"
+  data-stream-src="/api/activity"
+  data-stream-path="cells"></heatmap-ui>
+
+<script type="module">
+  // Static: flat array of {r, c, v}
+  document.getElementById('activity').data = [
+    { r: 0, c: 0, v: 3 }, { r: 0, c: 1, v: 7 }, { r: 1, c: 0, v: 1 },
+  ];
+</script>
+```
+
+---
+