@mixd-id/web-scaffold 0.2.250801014 → 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

@@ -191,11 +191,12 @@ data sources. All types also accept a shared **`filters`** array.
 // metric
 query = { datasource, aggregation: 'count'|'sum'|'avg'|'min'|'max', field, filters }
 
-// chart
-query = { datasource, groupBy, dateModifier: ''|'day'|'week'|'month'|'year', limit, 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
-query = { datasource, pageSize, order: [[field,'desc']], columns, 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 }, ... ]
@@ -268,10 +269,13 @@ and the offline chat demo while gaining the Data tab and query hydration.
 - **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 data source, aggregation / group-by /
-  page-size, eligible field, and the **Filters** editor (field / operator /
-  value rows). A **Refresh** button (connected) re-hydrates on demand; query
-  edits re-hydrate automatically (debounced ~450ms).
+  (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)
 
@@ -307,8 +311,10 @@ The active preset's `structure` renders top-to-bottom (`flex flex-col gap-6`):
 
 Card (`bg-base-300 rounded-xl p-5`) with a title row (name + hover ✕), then:
 
-1. **metric** — caption (`data.label || node.name`), a large
-   `toLocaleString()` number, optional delta line (`▲ n%` green / `▼ n%` red).
+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.
@@ -359,9 +365,10 @@ group). Then re-hydrates and persists. Missing uids are backfilled.
   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: node `data` is stripped from any
-  node that has a `query` (the server recomputes it), and `messages` are frozen.
-  No-op unless `connected && autoSave`.
+  `<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)
 
@@ -389,7 +396,7 @@ watch(() => config.value, to => saveConfig('dashboard', to), { deep: true })
 | `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` | `{}` | Optional client-side data-source descriptor `{ [key]: { label, fields, aggregations } }`; used only if the server returns none. |
+| `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. |
 
@@ -402,24 +409,36 @@ watch(() => config.value, to => saveConfig('dashboard', to), { deep: true })
 ### `ai-dashboard` socket controller
 
 `server/src/controllers/sockets/ai-dashboard.js` (registered as
-`routes['ai-dashboard']`) mixes in `AIDashboardMixin` and adds:
-
-- **`load-datasource`** → `loadDatasource()` returns `{ datasources: [...] }`,
-  a **hardcoded** list (`order`, `message`, `inbox`, `customer`, `product`)
-  with typed fields + supported aggregations.
-- **`get datasources()`** maps each `key` to a real Sequelize model, so
-  `load-dashboard` / `analyze-node` can compute widget data.
-- **Filtering** — `buildWhere(filters)` maps `{field, op, value}` rows to a
-  Sequelize `where` (`= != > >= < <= contains in` → `Op.eq/ne/gt/gte/lt/lte/like/in`,
-  blanks dropped, `in` comma-split). An `analyzeNode` override folds
-  `query.filters` into `where` before delegating to the mixin analyzers.
+`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). `this.socket.token.userId` comes from the base
-socket `Controller`.
+`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):
 
@@ -430,13 +449,77 @@ Methods (socket path → method, kebab→camel):
 | `<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()` | *(controller, not mixin)* the available data sources |
-| `<controller>.analyze-node` | `analyzeNode({ node })` | Compute one node's `data`: metric → `{ value }`, chart → `{ series }`, table → `{ columns, rows, hasNext }` |
+| `<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. the controller's own
-`analyzeNode`); `overrides` always win.
+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 }`).
 
 ---
 
@@ -469,4 +552,6 @@ clobbering** methods the class already defines (e.g. the controller's own
 | `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. |
-| `server/src/controllers/sockets/ai-dashboard.js` | Concrete `ai-dashboard` controller: hardcoded `load-datasource` + filter→`where`. |
+| `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 |
 |--------|------------|-------------|

package/docs/components/PivotList.md

@@ -0,0 +1,207 @@
+# PivotList
+
+A pivot-first data list. Same structure and preset system as `List`, but the
+preset is **always** in pivot mode and the result renders in a **single
+`VirtualTable`**. Built for aggregating a Sequelize model — including columns
+that live across **relationships** (`customer.name`, `order.customer.city`) —
+with client-side **virtual columns** edited in a spreadsheet-style formula bar.
+
+## TL;DR — how to use
+
+**1. Client** (any CMS front end):
+
+```vue
+<PivotList title="Sales"
+           controller="order"
+           preset-key="order-pivot"
+           subscribe-key="order"
+           :default-config="defaultConfig"
+           @pivot-item-click="drillDown" />
+```
+
+```js
+import PivotList from '@mixd-id/web-scaffold/components/PivotList.vue'
+
+const defaultConfig = () => ({
+  name: 'Orders',
+  columns: [
+    { key: 'status', label: 'Status', filterable: true, search: true },
+    { key: 'amount', label: 'Amount', type: 'currency', filterable: true },
+    { key: 'orderedAt', label: 'Ordered', type: 'date', filterable: true },
+    // relationship column — dotted key resolves through model.associations
+    { key: 'customer.city', label: 'City', filterable: true },
+  ],
+  presets: [{
+    name: 'By city / month',
+    pivot: {
+      rows: [
+        { key: 'customer.city' },
+        { key: 'orderedAt', aggregate: 'month' },
+      ],
+      values: [
+        { key: 'amount', aggregate: 'sum' },
+        { key: 'id', aggregate: 'count' },
+      ],
+      sorts: [ { key: '_amount-sum', type: 'desc' } ],
+      useTotal: true,
+    },
+  }],
+})
+
+const drillDown = ({ item, column, filters }) => {
+  // filters are ready-made List filters equivalent to the clicked cell
+  // — e.g. navigate to the orders List with them applied
+}
+```
+
+**2. Server** — apply the mixin once on the model base class
+(`server/src/classes/model.js`):
+
+```js
+import { PivotListMixin } from '@mixd-id/web-scaffold/pivot-list'
+
+class CustomModel extends PivotListMixin(Model) { ... }
+```
+
+then add the socket handler the component calls (`${controller}.pivot-load`):
+
+```js
+// server/src/controllers/sockets/order.js
+async 'pivot-load'(preset){
+  return Order.findAllFromPivotPreset(preset, {
+    config: { columns: [ ...same column defs... ] },
+    Sequelize
+  })
+}
+```
+
+(Or skip the mixin and call the standalone helper:
+`findAllFromPivotPreset(Order, preset, { config })`.)
+
+**3. Presets** persist exactly like `List`: pass `preset-key` and the config
+(presets, pivot setup, virtual columns, sidebar state) auto-saves to
+`${controller}.preset` (falling back to `user.preset`) a moment after any
+change, and reloads on mount. No extra wiring if your controller already
+supports `List` presets.
+
+That's it — the sidebar (`Alt+\``) gives users groups, aggregates, crosstab
+spreads, ordering, top-N limits, filters and sharing; the formula bar adds
+calculated columns without touching the server.
+
+## How it differs from List
+
+| | List | PivotList |
+|---|---|---|
+| Pivot | optional per preset | always on (`pivot.enabled` is forced) |
+| Result view | table or grid, pivot drill-down opens a second table | one `VirtualTable`, always |
+| Pagination | infinite scroll (`afterItem`) | none — one grouped result set, cap with `pivot.limit` |
+| Drill-down | opens the built-in ext panel | emits `pivot-item-click` with ready-made filters; the host decides |
+| Relationships | filter-only (`filtersToSequelizeInclude`) | groups, aggregates, spreads, filters and sorts on dotted keys |
+| Virtual columns | — | client-side formula columns (formula bar) |
+| Server endpoint | `${controller}.load` | `${controller}.pivot-load` |
+
+## Data-type behavior
+
+Column types come from your config or, when omitted, from the model
+(`columnTypes` in the response — dotted relationship keys included). The type
+changes what the pivot does with a column:
+
+| Type | As a group (row) | As a value (aggregate) | Default aggregate |
+|---|---|---|---|
+| `number` / `currency` | groups raw values | `sum`, `avg`, `min`, `max`, `stddev`, `count`, `countDistinct`, `first`, `last` | `sum` |
+| `date` | buckets: `hour`, `date`, `week`, `month`, `quarter`, `year` | `min` (earliest), `max` (latest), `count`, `countDistinct` | `max` |
+| `boolean` | groups true/false | `countTrue`, `countFalse`, `count` | `countTrue` |
+| `string` / `enum` | groups raw values | `count`, `countDistinct`, `groupConcat` (distinct values in one cell), `min`, `max` | `count` |
+
+An aggregate that doesn't fit the column's type falls back to the type's
+default (e.g. `sum` on a string becomes `count`). Value-returning aggregates
+(`min`/`max`/`first`/`last`) keep the source column's type and format in the
+result — a date's `max` renders as a date, an enum's `first` resolves its
+enum label.
+
+Drill-down filters are also type-aware: boolean cells compare as booleans and
+date buckets become `fn: 'format_month'`-style filters, on both own and
+relationship columns.
+
+## Relationships (Sequelize)
+
+Any dotted key resolves through `model.associations`, joining as needed:
+
+```js
+rows:   [ { key: 'customer.city' } ]             // GROUP BY `customer`.`city`
+values: [ { key: 'customer.name', aggregate: 'countDistinct' } ]
+filters:[ { key: 'customer.city', value: [ { operator: 'contains', value: 'Jak' } ] } ]
+```
+
+Nested paths work too (`order.customer.company.name` →
+`` `order->customer->company`.`name` ``). Joins are `LEFT OUTER` with
+`attributes: []` — they exist only for grouping/aggregating.
+
+Caveats:
+- **hasMany joins multiply rows.** Aggregating a parent measure while joining
+  a hasMany relation inflates `sum`/`count` — prefer pivoting from the child
+  model, or use `countDistinct`.
+- `first`/`last` are only supported on own columns (they resolve via the root
+  table's id); on dotted keys they fall back to `count`.
+
+## Virtual columns (formula bar)
+
+The `fx` bar above the table adds columns **calculated client-side** per pivot
+row — including the total row — like a spreadsheet formula:
+
+```
+=([_amount-sum] - [_cost-sum]) / [_amount-sum] * 100
+=IF([_id-count] > 100, "High", "Low")
+=ROUND([_amount-sum] / [_qty-sum], 2)
+```
+
+- Reference pivot result columns as `[key]` — focus the input and click a
+  chip to insert one. Aggregate aliases follow the `List` contract:
+  `_<key>-<aggregate>`, spreads `_<key>-<aggregate>-<group>`, plus
+  `_rowTotal`.
+- Operators: `+ - * / % ^`, `&` (concat), comparisons `= <> > >= < <=`.
+- Functions: `IF`, `AND`, `OR`, `NOT`, `ABS`, `ROUND`, `FLOOR`, `CEIL`,
+  `MIN`, `MAX`, `SUM`, `AVG`, `COUNT`, `CONCAT`, `LEN`, `UPPER`, `LOWER`.
+- Blank cells count as `0`; per-cell failures show Excel-style codes
+  (`#DIV/0!`, `#VALUE!`, `#NAME?`) without breaking the column.
+- Stored on the preset (`pivot.virtualColumns`), so they persist and share
+  with the preset; recomputed locally after every load — the server never
+  sees them.
+
+## Props
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| config | Object | `undefined` | Preset config (columns/presets); omit to use `defaultConfig` + `presetKey` |
+| defaultConfig | Function | `undefined` | Returns the default config when no saved preset exists |
+| presetKey | String | `undefined` | Persistence key — enables preset load/save |
+| controller | String | `undefined` | Socket controller prefix (`<controller>.pivot-load`, `<controller>.preset`) |
+| src | String | `` `${controller}.pivot-load` `` | Override the load endpoint |
+| subscribeKey | String | `undefined` | Realtime channel; signals trigger a debounced pivot reload |
+| title | String | `'Untitled'` | Small title above the preset name |
+| updateInterval | Number | `1200` | Debounce (ms) for realtime reloads |
+| presetMode | String | `'sidebar'` | `'sidebar'`, `'popup'` or `'external'` (emits `open-preset`) |
+| searchable | Boolean/String | `true` | Show the search box (columns with `search: true` are matched) |
+| toolbar | Boolean/String | `true` | Show the right toolbar + formula bar |
+| headerClass / containerClass / itemClass | String | — | Styling pass-throughs (same as `List`) |
+| itemsFn | Function | `undefined` | Transform the loaded rows before render |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| pivot-item-click | `{ item, column, filters }` | Aggregate cell clicked — `filters` reproduce the cell's row slice |
+| item-click | `(item, column)` | Group-column or virtual-column cell clicked |
+| after-load | — | Pivot data loaded |
+| signal | `(event, items)` | Realtime signal received (reload already scheduled) |
+| open-preset | — | `presetMode="external"` asked to open the preset editor |
+
+## Slots
+
+`head`, `left`, `left-toolbar`, `toolbar`, `right-toolbar`, `mobile-toolbar`,
+and per-column `col-<key>` header/content slots — same contract as `List`.
+
+## Keyboard
+
+- `Alt+\`` — toggle the preset sidebar
+- `Alt+1..9` — switch preset

package/docs/components/Textbox.md

@@ -6,7 +6,7 @@ A versatile text input component with support for various types, formatting, and
 |----------|------|---------|-------------|
 | modelValue | Any | `undefined` | The input value. Supports `v-model` |
 | value | Any | `undefined` | Alternative value prop |
-| type | String | `undefined` | Input type: `'text'`, `'tel'`, `'password'`, `'number'` |
+| type | String | `undefined` | Input type: `'text'`, `'tel'`, `'password'`, `'number'`. `tel` accepts digits and one decimal separator — see below |
 | placeholder | String | `undefined` | Placeholder text |
 | readonly | Any | `undefined` | Makes the input read-only |
 | disabled | Any | `undefined` | Disables the input |
@@ -63,6 +63,25 @@ A versatile text input component with support for various types, formatting, and
 <Textbox v-model="phone" type="tel" placeholder="+62..." />
 ```
 
+### `type="tel"` and decimals
+
+`tel` takes digits and **one** decimal separator. Either key produces it — a dot and a comma
+mean the same thing here, because which one a keyboard offers depends on the layout, and
+being told the key you have is the wrong one is not a useful thing for a number field to say.
+
+What is shown follows the locale (`Intl.NumberFormat` — a dot in `en`, a comma in `id`, `de`,
+`fr`), and **what is emitted is always written with a dot**, so `Number()` and `v-model.number`
+read it the same wherever it was typed:
+
+| typed | shown (en) | shown (id) | emitted |
+|---|---|---|---|
+| `0.7` | `0.7` | `0,7` | `0.7` |
+| `0,7` | `0.7` | `0,7` | `0.7` |
+| `1,2,3` | `1.23` | `1,23` | `1.23` |
+
+Only the first separator is one; anything after it belongs to the fraction. `maxlength` counts
+the separator, so a field expecting `0.75` needs at least 4.
+
 ### With clear button
 ```vue
 <Textbox v-model="search" clearable @clear="search = ''" />

package/docs/components/Tooltip.md

@@ -0,0 +1,148 @@
+# Tooltip
+Floating label shown on hover, keyboard focus, or long-press. A single tooltip layer is mounted lazily on first use and reused for every tooltip in the app, so only one tooltip element ever exists in the DOM.
+
+Three ways to use it:
+
+- `v-tooltip` directive — the common case, works on any element.
+- `<Tooltip>` component — wraps a trigger, useful when you want props instead of a binding object.
+- `showTooltip()` / `hideTooltip()` — programmatic, for custom triggers.
+
+## Props
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| text | String | `undefined` | Tooltip body. Supports `\n` for multiple lines |
+| title | String | `undefined` | Optional bold first line, for a label + description tooltip |
+| shortcut | String | `undefined` | Keyboard hint rendered as a chip, e.g. `⌘S` |
+| placement | String | `'top'` | `'top'`, `'bottom'`, `'left'`, `'right'`. Flips automatically when it doesn't fit |
+| variant | String | `'base'` | `'base'`, `'primary'`, `'secondary'`, `'accent'`, `'danger'`, `'success'` |
+| delay | Number | `null` | Hover intent in ms before showing (default `400`). `0` shows immediately |
+| offset | Number | `8` | Gap in px between the anchor and the tooltip |
+| maxWidth | Number/String | `260` | Max width of the tooltip surface |
+| arrow | Boolean | `true` | Show the arrow pointing at the anchor |
+| disabled | Boolean | `false` | Never show this tooltip |
+| open | Boolean | `null` | Controlled mode — when set, hover/focus is ignored |
+| tag | String | `'span'` | Element used for the trigger wrapper |
+| singleton | Boolean | `false` | Renders the shared layer instead of a trigger. Set by the controller — you never need this |
+
+## Events
+| Event | Payload | Description |
+|-------|---------|-------------|
+| show | - | Emitted when the tooltip actually becomes visible for this trigger (after the hover-intent delay) |
+| hide | - | Emitted when it stops being visible — including self-hides such as `Escape` or scrolling the anchor away |
+| update:open | Boolean | Emitted alongside `show`/`hide`, enables `v-model:open` |
+
+Events come from the wrapper component only; the `v-tooltip` directive doesn't emit.
+
+## Methods
+| Method | Parameters | Description |
+|--------|------------|-------------|
+| show | - | Shows the tooltip |
+| hide | `immediate` | Hides it, skipping the hide delay when `immediate` is true |
+
+## Slots
+| Slot | Description |
+|------|-------------|
+| default | The trigger element the tooltip is anchored to |
+
+## Directive
+
+```vue
+<button v-tooltip="'Save changes'">Save</button>
+```
+
+Placement via argument or modifier, variant via modifier, `.now` to skip the delay:
+
+```vue
+<button v-tooltip:bottom="'Filters'">…</button>
+<button v-tooltip.right.primary="'Filters'">…</button>
+<button v-tooltip.now="'Copied'">…</button>
+```
+
+Object form, for anything richer:
+
+```vue
+<button v-tooltip="{ title: 'Save', text: 'Writes to the server', shortcut: '⌘S', placement: 'bottom' }">
+  Save
+</button>
+```
+
+The binding is read at show time, so a value that starts empty and fills in later works — as does `v-tooltip` on a **disabled** button, which the directive hit-tests separately because disabled controls never fire mouse events.
+
+## Samples
+
+### Basic
+```vue
+<Tooltip text="Delete this row">
+  <button>Delete</button>
+</Tooltip>
+```
+
+### Title, description and shortcut
+```vue
+<Tooltip title="Publish" text="Makes the page visible to everyone" shortcut="⌘↵" placement="bottom">
+  <Button text="Publish" />
+</Tooltip>
+```
+
+### Variants
+```vue
+<Tooltip text="Looks good" variant="success"><span>✓</span></Tooltip>
+<Tooltip text="Quota exceeded" variant="danger"><span>!</span></Tooltip>
+```
+
+### Controlled
+```vue
+<Tooltip text="Copied to clipboard" :open="justCopied" placement="right">
+  <button @click="copy">Copy</button>
+</Tooltip>
+```
+
+### Reacting to show/hide
+```vue
+<Tooltip text="Writes to the server" @show="track('tooltip-seen')" @hide="onHidden">
+  <button>Save</button>
+</Tooltip>
+```
+
+`v-model:open` keeps a controlled tooltip in sync when it closes itself (Escape, scrolling away):
+
+```vue
+<Tooltip text="Copied to clipboard" v-model:open="justCopied">
+  <button @click="copy">Copy</button>
+</Tooltip>
+```
+
+### Programmatic
+```js
+import { showTooltip, hideTooltip } from '@mixd-id/web-scaffold/tooltip'
+
+showTooltip(el, { text: 'Drop files here', placement: 'bottom', delay: 0 })
+hideTooltip(el)
+```
+
+## Behaviour
+- Shows after `400ms` of hover intent; while a tooltip is already open (or one closed within `320ms`) the next one appears instantly, so scanning a toolbar doesn't stutter.
+- Hides on mouse leave, click, blur, `Escape`, and when the anchor scrolls out of view. It repositions itself while the page scrolls or resizes.
+- Keyboard focus shows it only for `:focus-visible`, so clicking a button doesn't leave a tooltip behind.
+- Touch devices: long-press (`450ms`) shows it, and it auto-hides after `2.5s`.
+- Text is rendered as text, never HTML.
+
+## Styling
+The layer is global CSS (class `mx-tooltip`) and paints itself entirely from the app's theme tokens — no colours of its own — so it follows whatever theme is active, light or dark:
+
+| Part | Token |
+|------|-------|
+| surface, arrow | `bg-base-500`, `border-border-100` |
+| text | `text-text` |
+| description under a title | `text-text-400` |
+| shortcut chip | `bg-base-300`, `text-text-400` |
+| `primary` / `secondary` / `accent` | that tone's `-500` surface, `-400` border, `-50` / `-100` text |
+
+Only layout knobs are exposed as custom properties:
+
+```css
+.mx-tooltip{
+  --mx-tooltip-max-width: 320px;
+  --mx-tooltip-z: 12000;
+}
+```