@mixd-id/web-scaffold 0.2.250801013 → 0.2.260801002

package/README.md

@@ -1,3 +1,27 @@
 # Web Scaffold for mixd.id
 
-This scaffold based on express vitejs vuejs
+`@mixd-id/web-scaffold` — the shared Vue 3 + Tailwind UI framework and utility library used by mixd CMS front ends (client: Vue 3 + Vite, server: Node.js ESM).
+
+- **[Getting started](docs/GETTING-STARTED.md)** — installation, plugin setup, Tailwind theme, WebSocket client/server, utilities.
+- **[Component docs](docs/components/)** — per-component usage and props.
+
+## Quick start
+
+```js
+// main.js of a Vite + Vue 3 app
+import webScaffold from '@mixd-id/web-scaffold'
+app.use(webScaffold) // registers all components globally (lazy) + directives + $util helpers
+```
+
+```js
+// tailwind.config.js
+module.exports = {
+  content: [
+    './src/**/*.{vue,js}',
+    './node_modules/@mixd-id/web-scaffold/src/**/*.{vue,js}',
+  ],
+  plugins: [require('@mixd-id/web-scaffold/themes/default')],
+}
+```
+
+This package ships uncompiled sources — the consuming app's Vite build compiles it. Within the monorepo it is consumed via `"file:../web-scaffold"`, so changes here are picked up without a publish step.

package/docs/components/AIDashboard.md

@@ -0,0 +1,557 @@
+# AIDashboard.vue
+
+## TLDR
+
+An AI-chat-style **dashboard builder** (think Claude web / ChatGPT, but the main
+content is a dashboard), split into three panels:
+
+- **Left** — a tabbed builder: **Presets** (the saved dashboards), **Build** (a
+  `TreeView` structure editor + node inspector), and **Data** (the data sources
+  available to query).
+- **Middle** — the **dashboard** itself: the active preset's widgets (metrics,
+  charts, tables), rendered top-to-bottom, groups as sections laid out per their
+  `layout` (grid / flex).
+- **Right** — an **AI chat** panel (same look as `AIChat`) that generates /
+  edits widgets. Chat history is kept **per preset**.
+
+The `config` object mirrors the server's **UserConfig model** (`UserConfig`
+hasMany `UserPreset`).
+
+The component runs in **two modes**, chosen by whether it is given a `socket` +
+`controller`:
+
+- **Offline** (no socket/controller) — makes **no** network calls. Sample data
+  comes from the `samples` prop, the chat appends canned widgets, and the host
+  page owns persistence. This is how `pages/Dashboard.vue` uses it.
+- **Connected** — mirrors the server `@mixd-id/web-scaffold/ai-dashboard`
+  mixin + the `ai-dashboard` socket controller: data sources load from
+  `<controller>.load-datasource`, widget data is hydrated by
+  `<controller>.load-dashboard`, chat calls `<controller>.chat`, and the config
+  is persisted through `<controller>.save`.
+
+```vue
+<!-- offline (host owns persistence + samples) -->
+<AIDashboard :config="config" :samples="samples" />
+
+<!-- connected (server-backed data via the ai-dashboard controller) -->
+<AIDashboard :config="config" :socket="socket" controller="ai-dashboard" />
+```
+
+---
+
+## Component family
+
+| Component | Responsibility |
+|-----------|----------------|
+| `AIDashboard` | Orchestrator. Owns preset CRUD + selection, the tabbed left builder (presets / structure tree / data sources), the three-panel layout + resizing, chat (offline canned **or** server-driven), and server sync (datasource load, hydration, persistence). |
+| `Widget` (inline) | Pure renderer for **one** node, branching on `node.type` (`metric` / `chart` / `table`). Render-function component; emits `remove`, never mutates the node. Charts use **vue-chartjs**; tables use **`VirtualTable`**. |
+| `AIChatItem` | Reused from `AIChat`. Renders one chat message. See `AIChat.md`. |
+| `AIChatTextbox` | Reused from `AIChat`. The composer input; emits the typed string. See `AIChat.md`. |
+| `AIDashboardMixin` (server) | `web-scaffold/src/utils/ai-dashboard.js` — socket-controller mixin persisting the same config shape to `UserConfig`/`UserPreset`, plus `load-dashboard` hydration and overridable `chat` / `analyze-node`. |
+| `AiDashboardController` (server) | `server/src/controllers/sockets/ai-dashboard.js` — the concrete controller: mixes in the above, exposes hardcoded **data sources** via `load-datasource`, and folds query **filters** into a Sequelize `where`. |
+
+---
+
+## Layout
+
+```
+┌──────────────────┬────────────────────────────────────┬────────────────┐
+│ [Presets|Build|Data]  Active preset name [Load samples] │ ✦ AI Assistant │ ← headers
+│ ──────────────── ├────────────────────────────────────┼────────────────┤
+│ Presets tab:     │  Overview                        ✕  │                │
+│   ▦ My Dash   ⋮  │   ┌──────┐ ┌──────┐ ┌──────┐ ┌────┐ │  assistant ▍   │
+│   ▦ Sales     ⋮  │   │metric│ │metric│ │metric│ │ …  │ │  reply…        │
+│                  │   └──────┘ └──────┘ └──────┘ └────┘ │                │
+│ Build tab:       │  ┌───────────────────────────────┐  │   ┌──────────┐ │
+│   ▸ Overview     │  │  chart (vue-chartjs)        ✕ │  │   │ user msg │ │
+│     • Revenue    │  └───────────────────────────────┘  │   └──────────┘ │
+│   ▸ Sales table  │  ┌───────────────────────────────┐  ├────────────────┤
+│   ── inspector ─ │  │  table (VirtualTable)       ✕ │  │ [ input  ] [▶] │ ← composer
+└──────────────────┴──┴───────────────────────────────┴──┴────────────────┘
+   ↑ resizable                                          ↑ resizable
+   220–520px                                            280–560px
+```
+
+- Three columns separated by hairline dividers. Left and right are fixed-width
+  (from `config.params`), the middle flexes to fill.
+- **Left** grab handle on its **right** edge; `leftWidth` clamped **220–520px**
+  (default **260**).
+- **Right** grab handle on its **left** edge; `rightWidth` clamped **280–560px**
+  (default **360**; delta *subtracted* — the panel grows when its left edge is
+  dragged left).
+- The left panel is a `Tabs` bar switching between **Presets**, **Build** and
+  **Data** (`config.params.leftTab`).
+- The chat message area uses a **reverse column** (`flex-col-reverse`) so it
+  stays pinned to the latest message as text streams in.
+- A floating `Card` handles preset renaming (replaces `window.prompt`).
+
+---
+
+## Data model — `config` mirrors UserConfig
+
+```js
+config = {
+  key:   String,                 // UserConfig.key (e.g. 'ai-dashboard') — sent on save
+  name:  String,                 // UserConfig.name
+  params: {                      // UserConfig.params — UI state
+    leftWidth:  Number,          //   builder panel width, px, 220–520, default 260
+    rightWidth: Number,          //   chat panel width, px, 280–560, default 360
+    leftTab:    String,          //   'presets' | 'build' | 'data', default 'presets'
+    presetIdx:  String|null,     //   uid of the active preset
+  },
+  presets: [ Preset, ... ],      // UserConfig.presets → UserPreset[] (array order = seq)
+}
+```
+
+`config` is a **plain object** (not a ref) and is **mutated in place** — access
+as `config.params.X`, never `config.value.params.X`. The parent owns the ref.
+
+---
+
+## Preset
+
+A **preset is one saved dashboard**. `config.presets` is the ordered list;
+array order becomes the server `seq`. The active preset is the one whose `uid`
+equals `config.params.presetIdx`.
+
+```js
+Preset = {
+  uid:  String,                  // unique id; client-generated 'p-<ts36>-<n>', server keeps it
+  name: String,                  // shown in the Presets tab + middle header
+  params: {                      // UserPreset.params — the dashboard content
+    structure: Node[],           //   the widget tree (groups + leaf widgets)
+    messages:  Message[],        //   chat history for THIS preset
+  },
+}
+```
+
+### Preset properties
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `uid` | `String` | ✅ | Stable unique id. Created by the component (`p-<timestamp36>-<counter>`) if missing; the server preserves the client value. Used for selection (`presetIdx`), reorder/seq, and targeted `remove-preset`. |
+| `name` | `String` | ✅ | Display name in the Presets tab and the middle header. Edited via the rename `Card`. |
+| `params` | `Object` | ✅ | The dashboard payload. Always normalized to contain `structure` and `messages`. |
+| `params.structure` | `Node[]` | ✅ | The widget tree (see **Node**). Empty array for a blank preset. |
+| `params.messages` | `Message[]` | ✅ | Per-preset chat history. On load, any message left `isLoading` by a reload is frozen (`body = display \|\| 'Cancelled.'`). |
+
+> Persistence-only preset fields (`UserPreset` also has `columns`, `filters`,
+> `sorts`, `pivot`, `datasource`, `search`, `views`). The AIDashboard component
+> does not use them; the server `save` passes any present through. Ignore them
+> for dashboards.
+
+### Node (recursive) — an entry in `params.structure`
+
+```js
+Node = {
+  uid:    String,                 // unique id, assigned by the component (NOT in samples)
+  name:   String,                 // widget title / section heading
+  type:   'group' | 'metric' | 'chart' | 'table',
+  items:  Node[],                 // children — 'group' only
+  layout: { mode, cols },         // 'group' only — how children are laid out
+  data:   Object,                 // type-specific render payload (see below)
+  query:  Object,                 // connected mode — how the server computes `data`
+}
+```
+
+| Property | Type | Applies to | Description |
+|----------|------|-----------|-------------|
+| `uid` | `String` | all | Unique id (`w-<ts36>-<n>`). Assigned on creation / instantiation; drives selection, removal (`removeFromTree`) and hydration merge-by-uid. |
+| `name` | `String` | all | Section heading (group) or widget card title. |
+| `type` | `String` | all | `group`, `metric`, `chart`, or `table`. |
+| `items` | `Node[]` | group | Child nodes. Only groups can contain children. |
+| `layout` | `Object` | group | `{ mode: 'grid' \| 'flex', cols: 1–4 }`. `grid` lays children in `cols` equal columns; `flex` wraps them. Defaults to `{ mode:'grid', cols: metricOnly ? 4 : 2 }`. |
+| `data` | `Object` | leaf | Render payload (see **Per-type `data`**). In offline mode you author it directly; in connected mode it is **derived** (hydrated) and stripped before save. |
+| `query` | `Object` | leaf | Data-source query used by `load-dashboard` / `analyze-node` to compute `data` (see **Per-type `query`**). Present only when a data source is bound. |
+
+### Per-type `data` (render payload)
+
+```js
+// metric — a single KPI
+data = { label: String, value: Number|String, delta: Number /* optional ±% */ }
+
+// chart — rendered as a vue-chartjs Bar
+data = { series: [ { label: String, value: Number }, ... ] }   // (also accepts `rows`)
+
+// table — rendered with VirtualTable
+data = {
+  columns: [ { key: String, label: String }, ... ],   // plain string allowed → key & label
+  rows:    [ { [key]: cellValue, ... }, ... ],
+}
+
+// group — no data; renders as a section heading + `layout`-driven children
+```
+
+### Per-type `query` (connected mode)
+
+Bound via the Build-tab inspector; resolved server-side against the controller's
+data sources. All types also accept a shared **`filters`** array.
+
+```js
+// metric
+query = { datasource, aggregation: 'count'|'sum'|'avg'|'min'|'max', field, filters }
+
+// chart — `aggregation`/`field` size each bar (count of rows when unset)
+query = { datasource, aggregation, field, groupBy,
+          dateModifier: ''|'day'|'week'|'month'|'year', limit, filters }
+
+// table — `order` is Sequelize's own shape, any number of levels
+query = { datasource, pageSize, page, order: [[field,'asc'|'desc'], ...], columns, filters }
+
+// filters (all types) — folded into a Sequelize `where` on the server
+filters = [ { field: String, op: '='|'!='|'>'|'>='|'<'|'<='|'contains'|'in', value }, ... ]
+```
+
+### Chat message — an entry in `params.messages`
+
+Same shape as `AIChat` (see `AIChat.md`):
+
+```js
+{ direction: 1|2, body, display, isLoading, model, ellapsed }
+```
+
+Messages live in `preset.params.messages`, so each preset has its own
+conversation, persisted with the config.
+
+### `samples` prop (offline seed, supplied by the page)
+
+```js
+samples = {
+  structure: Node[],              // dashboard used to seed the first preset; UID-LESS templates
+  widgets:   { [key]: Node },     // widgets the offline chat can append; UID-LESS templates
+}
+```
+
+Chat-understood keys: `metric`, `chart`, `table`, `group`. Templates **must
+not** carry `uid` — the component deep-clones each template and assigns fresh
+ids via `instantiate()` on every use.
+
+---
+
+## Modes: offline vs connected
+
+`connected = !!(socket && controller)`. Two further flags fine-tune a connected
+mount so a host can keep owning parts it already handles:
+
+| Flag | Default | Effect when **on** |
+|------|---------|--------------------|
+| `connected` (derived) | — | Enables the **Data** tab, `load-datasource`, and `load-dashboard` hydration. |
+| `autoSave` | `true` | Persists edits via debounced `<controller>.save`. Turn **off** when the host page persists (avoids a double write). |
+| `serverChat` | `true` | Routes chat through `<controller>.chat`. Turn **off** to keep the offline canned-widget generator even while connected. |
+
+`pages/Dashboard.vue` connects for **data only**: it passes `socket` +
+`controller="ai-dashboard"` but sets `:auto-save="false"` and
+`:server-chat="false"`, so it keeps its `loadConfig`/`saveConfig` persistence
+and the offline chat demo while gaining the Data tab and query hydration.
+
+---
+
+## Left panel — the tabbed builder
+
+### Presets tab (CRUD)
+
+- `activePreset` = the preset whose `uid === config.params.presetIdx`.
+- **Add** — pushes a blank preset (`name:'New Preset'`, empty structure) and
+  jumps to the **Build** tab.
+- **Rename** — opens the floating rename `Card` (Textbox + Save/Cancel).
+- **Duplicate** — deep-clones the preset with a fresh preset uid **and** fresh
+  uids for every node, inserts after the original, selects it.
+- **Remove** — splices it; if it was active, selection falls back to the first
+  preset (or `null`). In connected mode also calls `<controller>.remove-preset`.
+- Each row has a "⋮" button opening a context menu anchored to it.
+
+### Build tab (structure editor + inspector)
+
+- A **`TreeView`** of the active preset's `structure`. Each row shows a
+  type-colored icon + name; groups show their layout mode. Selecting a row sets
+  the inspected node; `TreeView` provides drag-reorder, drag-into-group, inline
+  add (groups → quick metric), duplicate and remove.
+- **Add component** (toolbar `+`) opens a menu (Section / Metric / Chart /
+  Table) that inserts into the selected group, else at the root.
+- **Node inspector** (bottom): edits `name`; for **groups** the `layout`
+  (mode + columns); for **leaves** the authored `data` (caption, and a metric's
+  value + delta) followed by the query builder — data source, aggregation +
+  eligible field (metric **and** chart), group-by / bucket / limit (chart),
+  column checkboxes + multi-level order rows + page size (table), and the
+  **Filters** editor (field / operator / value rows). A **Refresh** button
+  (connected) re-hydrates on demand; query edits re-hydrate automatically
+  (debounced ~450ms).
+
+### Data tab (data sources)
+
+- Lists the data sources returned by `<controller>.load-datasource` (or the
+  `datasources` prop offline). Each source expands to show its fields + types,
+  with a **"+ New metric from this source"** shortcut that drops a bound metric
+  into the current section and jumps to Build.
+- Data source descriptor shape:
+
+```js
+{ key: String, label: String,
+  aggregations: ['count','sum','avg','min','max'],   // supported metric aggregations
+  fields: [ { key, label, type: 'number'|'string'|'date' }, ... ] }
+```
+
+---
+
+## Middle panel — rendering
+
+The active preset's `structure` renders top-to-bottom (`flex flex-col gap-6`):
+
+- **group** → a section: heading (`node.name`) + its `items` laid out per
+  `node.layout` via **inline styles** (grid `repeat(cols, minmax(0,1fr))`, or
+  flex-wrap) — inline to survive Tailwind purge of dynamic column counts.
+- **leaf** (metric/chart/table) → a full-width `Widget` card.
+- Every widget card and section heading has a hover-revealed **✕** that removes
+  the node.
+- Empty preset / no preset → an empty-state illustration + hint.
+- Header: active preset name + a **Load samples** button that replaces the
+  active preset's structure with a fresh instantiation of `samples.structure`.
+
+### Widget rendering rules (`Widget`)
+
+Card (`bg-base-300 rounded-xl p-5`) with a title row (name + hover ✕), then:
+
+0. The card **caption** is `data.label || node.name` for every type, and a
+   node whose hydration failed renders `data.error` in red in place of its body.
+1. **metric** — a large `toLocaleString()` number, optional delta line
+   (`▲ n%` green / `▼ n%` red).
+2. **chart** — a **vue-chartjs `Bar`** in a 240px-tall box. Bar/grid/tick colors
+   are read from the active theme's CSS variables (`--primary`, `--border-50`,
+   `--text-300`) with SSR-safe fallbacks; empty series shows a "No data." hint.
+3. **table** — a **`VirtualTable`** built from `columns` / `rows` (string column
+   doubles as key + label); height caps at 320px.
+4. **anything else** — muted placeholder.
+
+---
+
+## Chat
+
+`send(prompt)` routes to server chat when `serverChat` is on and connected,
+otherwise the offline generator.
+
+### Offline (canned, generates into the ACTIVE preset)
+
+1. Push user message + assistant placeholder into `activePreset.params.messages`.
+2. Compute `reply = pickReply(prompt)` (keyword table below).
+3. **Stream** the reply: every **28ms** advance a cursor by
+   `max(2, ceil(remaining/24))` chars. When done, apply the widgets once and
+   finalize (`model:'offline-demo'`, `ellapsed`).
+
+| Keywords | Result |
+|----------|--------|
+| `overview`, `dashboard`, `build` | rebuild from `samples.structure` |
+| `table`, `customer`, `list` | append `widgets.table` |
+| `chart`, `bar`, `revenue`, `trend`, `graph` | append `widgets.chart` |
+| `metric`, `kpi`, `card`, `number` | append `widgets.metric` (into the last root group) |
+| `group`, `section` | append `widgets.group` |
+| (none) | help message listing available widget keys |
+
+`cancel()` stops the timer and freezes the in-flight message; the dashboard only
+changes once a reply fully streams in.
+
+### Connected (`serverChat`)
+
+`sendConnected` posts `{ messages, structure }` to `<controller>.chat` and
+applies the result: `reply` → assistant body; `structure` → replace the active
+preset's tree; `nodes` → instantiate + append (metrics into the last root
+group). Then re-hydrates and persists. Missing uids are backfilled.
+
+---
+
+## Persistence & hydration (connected)
+
+- **Hydrate** — on mount, preset switch, data-source change, query edit
+  (debounced) and the Refresh button, `hydrateActive()` posts the preset's
+  structure to `<controller>.load-dashboard` and **merges** returned `data` into
+  the live nodes **by uid**. Derived data is never authored by hand.
+- **Persist** — a deep `watch(config)` calls debounced (**700ms**)
+  `<controller>.save` with a cleaned config: on a node that has a `query` only
+  the authored `data.label` / `data.delta` are kept (the server recomputes
+  `value` / `series` / `rows`), and `messages` are frozen. No-op unless
+  `connected && autoSave`.
+
+### Offline persistence (host-owned)
+
+```js
+// pages/Dashboard.vue
+const config = ref(await loadConfig('dashboard', {
+  name: 'Dashboard',
+  params: { leftWidth: 260, rightWidth: 360, presetIdx: null },
+  presets: [],
+}))
+watch(() => config.value, to => saveConfig('dashboard', to), { deep: true })
+```
+
+> Web detail: this project's Tailwind config sets `important: true`, so panel
+> widths and group layouts are applied as **inline styles** with no competing
+> class.
+
+---
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `config` | `Object` | required | UserConfig-shaped object (see **Data model**). Mutated in place. |
+| `samples` | `Object` | `{ structure: [], widgets: {} }` | Offline seed layout + generatable widgets. Nodes are uid-less templates. |
+| `socket` | `Object` | `null` | Socket transport. With `controller`, switches the component to **connected** mode. |
+| `controller` | `String` | `''` | Socket namespace prefixing every call (`<controller>.load-datasource`, `.load-dashboard`, `.save`, `.chat`, `.remove-preset`). |
+| `datasources` | `Object\|Array` | `{}` | Optional client-side data-source descriptor — either `{ [key]: { label, fields, aggregations } }` or the `[{ key, label, fields, aggregations }]` array `load-datasource` returns; used only if the server returns none. |
+| `autoSave` | `Boolean` | `true` | Persist edits via `<controller>.save`. Set `false` when the host page owns persistence. |
+| `serverChat` | `Boolean` | `true` | Route chat through `<controller>.chat`. Set `false` to keep the offline generator while connected. |
+
+`AIDashboard` emits no events and exposes no methods.
+
+---
+
+## Server side
+
+### `ai-dashboard` socket controller
+
+`server/src/controllers/sockets/ai-dashboard.js` (registered as
+`routes['ai-dashboard']`) mixes in `AIDashboardMixin` and adds only what is
+project-specific:
+
+- **`get datasources()`** maps each catalogue `key` to a real Sequelize model,
+  so `load-dashboard` / `analyze-node` can compute widget data.
+- **`get datasourceList()`** the catalogue `load-datasource` answers with
+  (`order`, `message`, `inbox`, `customer`, `product` — typed fields +
+  supported aggregations). Without it the mixin describes the models in
+  `datasources` instead.
+- **`aiChat`** the real LLM call.
+
+Filtering is **not** the controller's job any more — the mixin folds
+`query.filters` into the `where` of every analyzer.
+
+### `AIDashboardMixin` (`@mixd-id/web-scaffold/ai-dashboard`)
+
+Host-class contract (getters): `Models` `{ UserConfig, UserPreset }`,
+`Sequelize` (for `Op`), `configKey` (the `UserConfig.key`), `conn` and
+`datasources` (for hydration), optionally `datasourceList`.
+`this.socket.token.userId` comes from the base socket `Controller`.
+
+Every field name a query names — `field`, `groupBy`, `columns[].key`,
+`order[][0]`, `filters[].field` — is checked against the model's attributes
+before it reaches `fn`/`col`/`literal`. An unknown one throws, and
+`load-dashboard` catches per node and returns `data.error` so one broken widget
+cannot blank the dashboard.
+
+**Filters → `where`** — `filtersToWhere(model, filters)` maps `{field, op, value}`
+rows to Sequelize (`= != > >= < <= contains in` →
+`Op.eq/ne/gt/gte/lt/lte/like/in`, blanks dropped, `in` comma-split).
+
+Methods (socket path → method, kebab→camel):
+
+| Socket path | Method | Does |
+|-------------|--------|------|
+| `<controller>.load` | `load()` | UserConfig + presets (seq-ordered), or `null` |
+| `<controller>.save` | `save({ config })` | Upsert UserConfig; sync presets (array order → `seq`, missing uids destroyed); returns fresh `load()` |
+| `<controller>.save-preset` | `savePreset({ preset })` | Upsert one preset (appends `seq` for new rows) |
+| `<controller>.remove-preset` | `removePreset({ uid })` | Destroy one preset → `{ removed }` |
+| `<controller>.load-dashboard` | `loadDashboard({ preset })` | Hydrate: walk the structure, compute `data` for every node with a `query`, recurse into groups; returns the hydrated preset |
+| `<controller>.load-datasource` | `loadDatasource()` | `{ datasources }` — `this.datasourceList`, or the models in `this.datasources` described |
+| `<controller>.analyze-node` | `analyzeNode({ node })` | Compute one node's `data`: metric → `{ value }`, chart → `{ series }`, table → `{ columns, rows, hasNext }`. Each query's `filters` are folded into its `where` here — no override needed |
+| `<controller>.chat` | `chat({ messages, structure })` | **Overridable stub** — real controllers return `{ reply, structure?, nodes?, model? }` |
+
+`mixin(Class, overrides)` copies mixin methods onto the prototype **without
+clobbering** methods the class already defines (e.g. a controller's own
+`loadDatasource` or `analyzeNode`); `overrides` always win.
+
+`server/docs/dashboard.json` is the worked fixture for all of this — one preset
+exercising every widget type, aggregation, bucket, order and filter operator the
+analyzers understand.
+
+### `apiMixin` (`@mixd-id/web-scaffold/ai-dashboard-api`)
+
+The REST counterpart. Same logic, same `UserConfig`/`UserPreset` rows — an API
+client and the component read and write the same dashboards.
+
+| Route | Verb → handler | Mixin method |
+|-------|----------------|--------------|
+| `/ai-dashboard` | GET → `index` | `load()` |
+| `/ai-dashboard` | POST → `store` | `save({ config })` |
+| `/ai-dashboard/preset` | POST → `store` | `savePreset({ preset })` |
+| `/ai-dashboard/preset?uid=` | DELETE → `destroy` | `removePreset({ uid })` |
+| `/ai-dashboard/datasource` | GET → `index` | `loadDatasource()` |
+| `/ai-dashboard/dashboard` | POST → `store` | `loadDashboard({ preset })` |
+| `/ai-dashboard/node` | POST → `store` | `analyzeNode({ node })` |
+| `/ai-dashboard/chat` | POST → `store` | `aiChat({ messages, structure })` |
+
+`apiMixin(host)` returns those grouped by route (`{ config, preset, datasource,
+dashboard, node, chat }`). `host` is the socket controller's getter contract as
+a plain object — `Models`, `Sequelize`, `conn`, `configKey`, `datasources`,
+optional `datasourceList` / `model` — plus:
+
+- **`ValidationError`** — when given, bodies are validated and a bad one is a
+  **400** (`uid`+`name` on a preset, `type` on a node, `messages` on chat).
+- **`NotFoundError`** — when given, an unknown preset uid is a **404**.
+- any override the socket controller would make, `aiChat` above all.
+
+Notes that bite:
+
+- Every body is taken both **wrapped** the way the socket path takes it
+  (`{ preset }`, `{ node }`, `{ config }`) and **bare**, so posting a preset as
+  the body does what it looks like it does.
+- `POST /ai-dashboard/dashboard` also accepts just `{ uid }` and hydrates the
+  stored preset — an API client should not have to post back a structure the
+  server already has.
+- **Identity is per request.** The http middleware calls a handler as
+  `fn.apply(route, [req, res])`, so `this` is the route object *shared by every
+  request*; the mixin builds a fresh context around `req.token` instead and
+  never stores a request on the route.
+- **DELETE takes `?uid=`**, not a path segment: wildcard routes match `[a-z0-9]`
+  only, which cannot hold a `p-lz4k2h-1`.
+- Controller files must stay **literal** — `npm run postman` reads `name` and
+  `examples` out of the source of `export default`, not out of anything a
+  function returned. So wire the handlers in, don't generate the object:
+
+```js
+// src/controllers/api/ai-dashboard/index.js
+import { apiMixin } from "@mixd-id/web-scaffold/ai-dashboard-api"
+import host from "./_host.js"
+
+const { config } = apiMixin(host)
+
+export default {
+  index: { name: 'Load the dashboard', fn: config.index },
+  store: { name: 'Save the dashboard', fn: config.store, examples: [ ... ] },
+}
+```
+
+Then register the path in `src/controllers/api/index.js` and its auth in
+`src/configs/api.js` (`'/ai-dashboard': { token: true }`).
+
+---
+
+## Constants & tunables
+
+| Name | Value | Meaning |
+|------|-------|---------|
+| Left width clamp | `220–520px` | builder panel resize bounds |
+| Left default width | `260px` | initial `leftWidth` |
+| Right width clamp | `280–560px` | chat panel resize bounds |
+| Right default width | `360px` | initial `rightWidth` |
+| Resize handle width | `3px` | grab strip on each inner panel edge |
+| Default group layout | `{ mode:'grid', cols: metricOnly ? 4 : 2 }` | new / seeded group layout |
+| Chart height | `240px` | vue-chartjs Bar container |
+| Table max height | `320px` | VirtualTable cap |
+| Save debounce | `700ms` | `<controller>.save` |
+| Hydrate debounce | `450ms` | `<controller>.load-dashboard` after query edits |
+| Reveal interval / step | `28ms` / `max(2, ceil(remaining/24))` | offline chat streaming |
+| First preset name | `'My Dashboard'` | auto-created on first run, seeded from samples |
+| Assistant `model` tag (offline) | `'offline-demo'` | footer label on generated replies |
+
+---
+
+## Files
+
+| File | Role |
+|------|------|
+| `src/components/AIDashboard.vue` | Orchestrator + inline `Widget` (this doc's subject). |
+| `src/components/AIChatItem.vue` | Reused chat message renderer (see `AIChat.md`). |
+| `src/components/AIChatTextbox.vue` | Reused composer input (see `AIChat.md`). |
+| `src/pages/Dashboard.vue` | Page host; owns `samples`, connects to `ai-dashboard` for data only (auto-save + server-chat off). |
+| `web-scaffold/src/utils/ai-dashboard.js` | Server-side `AIDashboardMixin` + `mixin()` for socket controllers. |
+| `web-scaffold/src/utils/ai-dashboard-api.js` | `apiMixin()` — the same logic behind REST handlers for `src/controllers/api`. |
+| `server/src/controllers/sockets/ai-dashboard.js` | Concrete `ai-dashboard` controller: the datasource catalogue, its models, and the real `ai-chat`. |
+| `server/docs/dashboard.json` | Worked fixture of the persisted shape + catalogue (see `server/docs/dashboard.md`). |

package/docs/components/Alert.md

@@ -12,9 +12,11 @@ None (controlled via methods)
 ## Methods
 | Method | Parameters | Description |
 |--------|------------|-------------|
-| open | `{ title?, message, buttonText?, onConfirm? }` | Opens the alert dialog |
+| open | `{ title?, message, buttonText?, onConfirm?, icon? }` | Opens the alert dialog. Pass `icon: false` to drop the red warning mark when the dialog is not reporting an error |
 | close | - | Closes the alert dialog |
 
+The dialog is capped at 80% of the viewport height: the title, message and details scroll inside it while the confirm button stays pinned at the bottom. Pressing Escape confirms and closes it, the same as the button.
+
 ## Slots
 | Slot | Description |
 |------|-------------|

package/docs/components/Card.md

@@ -13,6 +13,11 @@ A card component that can be used as a static container or floating modal.
 | hash | String | `undefined` | URL hash to control card visibility |
 | query | String | `undefined` | URL query param to control card visibility |
 
+## Events
+| Event | Payload | Description |
+|-------|---------|-------------|
+| show | `{ context, caller }` | Emitted when a floating card opens — by `open()`, or by its `hash`/`query` appearing in the route |
+
 ## Methods
 | Method | Parameters | Description |
 |--------|------------|-------------|