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

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

@@ -1,206 +0,0 @@
-# §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

@@ -1,348 +0,0 @@
-# §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>
-```
-
----
-