@mixd-id/web-scaffold 0.2.250801013 → 0.2.260801002

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;
+}
+```

package/docs/components/WebPageBuilder.md

@@ -0,0 +1,125 @@
+# WebPageBuilder
+A full-screen visual page builder widget. It renders a three-pane editor — settings panel (page info / layout / components / chat), a live preview iframe, and a per-component setting panel — and talks to a socket controller for loading, saving and previewing pages.
+
+Registered globally by the scaffold plugin as an async component, so it can be used directly without importing.
+
+## Requirements
+- `vue-router` must be installed; the page uid is read from `$route.params.uid`, and a navigation guard warns about unsaved changes.
+- The host app must provide the scaffold injections: `alert`, `appStyle`, `confirm`, `useSocket`, `toast` (all provided by the standard scaffold app setup).
+- A preview route (returned by the server as `previewHost`, e.g. `/web-preview`) that renders the page inside the iframe and implements the iframe message protocol below.
+
+## Props
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| controller | String | `undefined` | Socket controller namespace. Every server call is prefixed with it, e.g. `web-page.open` |
+| presetKey | String | `undefined` | Key used to persist UI state (tab index, panel widths, zoom level…) via `${controller}.preset` |
+| canManageLayout | Boolean | `false` | Whether the user may manage layouts |
+| excludeComponents | Array | `[]` | Component `type` strings to hide from the component selector |
+| moreComponents | Array | `[]` | Extra component definitions added to the selector (`{ type, name, group, props }`) |
+| uploadConfig | Object | `undefined` | Axios-style config (`{ method, url, data }`) used to upload images when `uploadImageFn` is not given |
+| uploadImageFn | Function | `undefined` | `(image, extra?, opt?) => Promise` — custom image upload handler; takes precedence over `uploadConfig` |
+| useChat | Boolean | `false` | Shows the AI chat tab; requires a `${controller}.chat` handler on the server |
+| useDatasource | Array | `undefined` | Datasource support tuple; the second element is the socket path used to load datasource data (the Datasource tab is currently disabled) |
+
+## Events
+| Event | Payload | Description |
+|-------|---------|-------------|
+| close | - | Emitted when the close (✕) button is clicked. The parent decides where to navigate |
+| unmount | `{ uid }` | Emitted when the builder unmounts, with the page uid |
+
+## Methods
+| Method | Parameters | Description |
+|--------|------------|-------------|
+| getPage | - | Returns the current (reactive) page object |
+
+## Server contract
+The widget expects these socket paths on `controller` (base controller paths included):
+
+| Path | Payload | Returns |
+|------|---------|---------|
+| `${controller}.open` | `{ uid }` | `{ page, previewHost, debugMode? }` — `page.app.hosts[0].name` is used to build the public URL |
+| `${controller}.save` | `{ ...page, layout }` | - |
+| `${controller}.load-layouts` | `{}` | Array of layout objects |
+| `${controller}.create-layout` | layout | The created layout |
+| `${controller}.load-templates` | - | `{ items }` — component templates for the selector |
+| `${controller}.subscribe` / `.unsubscribe` | `{ name:'page' }` | - |
+| `${controller}.preset` | `{ key }` / `{ key, config }` | Persisted UI config |
+| `${controller}.chat` | `{ key, prompt, attachments, pageId, input }` | `{ messages }` — only needed when `useChat` is set |
+
+## Preview iframe protocol
+Messages are exchanged with the preview iframe via `postMessage`.
+
+Sent to the iframe:
+| Message | Description |
+|---------|-------------|
+| `{ action:'update', page }` | Full page JSON (headers, footers, components, stylesheet, data, editMode). Throttled; sent on every page/layout change |
+| `{ action:'select', uid }` | Scrolls/highlights the component with `uid` |
+| `{ action:'reload' }` | Reloads the preview |
+
+Received from the iframe:
+| Message | Description |
+|---------|-------------|
+| `{ type:'mounted' }` | Preview is ready; triggers the first update |
+| `{ type:'component-click', uid }` | Selects the clicked component in the editor |
+| `{ type:'setProp', uid, value }` | Merges `value` into the component's props (inline editing) |
+| `{ type:'setSubAction', value }` | Forwarded to the active setting component |
+
+## Provided injections
+`*Setting` components rendered in the right panel can inject: `imageUrl`, `imageSrc`, `store`, `postIframe`, `getPage`, `uploadImage`, `openComponentSelector`, `setUid`, `openRightPane2`, `getRightPane`, `pageHistory`, `duplicate`.
+
+Each component type `Foo` resolves its setting panel as a globally registered `FooSetting` component.
+
+## Keyboard shortcuts
+| Shortcut | Action |
+|----------|--------|
+| Alt+1 | Mobile view |
+| Alt+2 | Tablet view (`md:`) |
+| Alt+3 | Desktop view (`xl:`) |
+| Alt+4 | Wide view (`2xl:`) |
+
+## Samples
+
+### Page builder page (see `admin/src/pages/WebPageEdit.vue`)
+```vue
+<template>
+  <div class="flex-1 flex flex-col">
+    <WebPageBuilder class="flex-1"
+                    controller="web-page"
+                    preset-key="web-page"
+                    :more-components="components"
+                    :upload-image-fn="uploadImage"
+                    :use-chat="true"
+                    @close="$router.push({ name:'WebPage' })" />
+  </div>
+</template>
+
+<script setup>
+import {inject, ref} from 'vue'
+
+const socket = inject('useSocket')()
+
+const components = ref([
+  { type:'SaasRegister', name:'SAAS Register', group:'SAAS', props:{ items:[] }},
+])
+
+async function uploadImage(image){
+  return socket.send('web-page.upload-image', { image })
+}
+</script>
+```
+
+The route must carry the page uid, e.g.:
+```js
+{
+  name: 'WebPageEdit',
+  path: 'web-page/:uid',
+  component: () => import('./pages/WebPageEdit.vue')
+}
+```
+
+### Upload via config instead of a function
+```vue
+<WebPageBuilder controller="web-page"
+                :upload-config="{ method:'post', url:'/api/upload' }"
+                @close="$router.back()" />
+```