create-restforge-skills 0.2.0 → 0.4.0

package/skills/restforge/references/udf-catalog.md

@@ -1,496 +1,623 @@
-# Reference: UDF Catalog (UI Definition File)
-
-> **Offline mirror.** This file mirrors `designer_get_udf_catalog` from the
-> installed RESTForge designer. The live tool is authoritative — when this file
-> and the tool disagree, trust the tool, then update this file. Field types and
-> features depend on the active plugin version; always re-ground with the tool
-> (and `designer_list_plugins`) before defining a UDF payload.
-
-Source: `designer_get_udf_catalog` — installed designer version.
-Use as grounding before defining or editing any UDF payload.
-
----
-
-## Table of Contents
-
-1. [Payload Envelope](#payload-envelope)
-2. [App Config](#app-config)
-3. [Page Anatomy](#page-anatomy)
-4. [Field Types](#field-types)
-5. [Field Attributes](#field-attributes)
-6. [Field Rows (Layout)](#field-rows-layout)
-7. [Field States (Conditional)](#field-states-conditional)
-8. [Features](#features)
-9. [Data Source](#data-source)
-10. [Navigation](#navigation)
-11. [Homepage](#homepage)
-12. [Dashboard Page](#dashboard-page)
-13. [Master-Detail](#master-detail)
-14. [Workflow Actions](#workflow-actions)
-15. [ID Generation](#id-generation)
-16. [Live Sync](#live-sync)
-17. [Naming Conventions](#naming-conventions)
-18. [Plugins](#plugins)
-
----
-
-## Payload Envelope
-
-Root-level UDF structure. All properties at the top level.
-
-```json
-{
-  "appConfig": { ... },
-  "pages": [ ... ],
-  "navigation": [ ... ],
-  "homepage": "page-id"
-}
-```
-
-**Multi-file support:**
-- `extends`: inherit from a base file — `"extends": "./base.json"`
-- `include`: inline another file's pages array — `"include": "./orders-pages.json"`
-
----
-
-## App Config
-
-| Property | Type | Required | Notes |
-|---|---|---|---|
-| `appName` | string | yes | Display name shown in page title and header |
-| `appCode` | string | yes | Unique app identifier, kebab-case, used in file naming |
-| `plugin` | string | yes | Output plugin: `vanilla-js-basic`, `vanilla-js-auth`, or custom |
-| `apiBaseUrl` | string | yes | Base URL of the RESTForge backend API |
-| `port` | integer | no | Local dev server port; default: `3000` |
-| `numberFormat` | string | no | Locale for number display; default: `"id-ID"` |
-
-Plugin-specific properties (for `vanilla-js-auth`):
-- `authAppCode` — app code used for the auth API path
-- `idleTimeout` — session idle timeout in seconds
-
----
-
-## Page Anatomy
-
-Each entry in `pages[]` represents one page in the application.
-
-| Property | Type | Required | Notes |
-|---|---|---|---|
-| `pageId` | string | yes | Unique identifier; CRUD: `^[a-zA-Z0-9_-]+$`; dashboard: `^dash-[a-z0-9-]+$` |
-| `pageTitle` | string | yes | Display title shown in header and sidebar |
-| `pageSubtitle` | string | no | Subtitle shown below title |
-| `pageIcon` | string | no | Icon class (e.g., Tabler Icons: `"ti ti-home"`) |
-| `pageGroup` | string | no | Sidebar group name (Title Case); auto-derives navigation |
-| `pageType` | string | no | `"crud"` (default) or `"dashboard"` |
-| `apiPath` | string | yes (CRUD) | Backend endpoint path; e.g., `"/customer"` |
-| `primaryKey` | string | yes (CRUD) | Primary key field name; e.g., `"customer_id"` |
-| `displayField` | string | yes (CRUD) | Field used as record label in lookups |
-| `fields` | array | yes (CRUD) | Field definitions for the page |
-| `fieldRows` | array | no | Layout grouping for multi-column forms |
-| `fieldStates` | array | no | Conditional visibility/readonly rules |
-| `details` | array | no | Detail pages for master-detail pattern |
-| `workflow` | object | no | Workflow state machine config |
-| `workflowActions` | array | no | Action buttons for workflow transitions |
-| `features` | object | no | Page-level feature flags |
-
----
-
-## Field Types
-
-8 field types. Each type maps to a specific HTML element and optional library.
-
-| Type | HTML Element | Library | Key attributes |
-|---|---|---|---|
-| `text` | `<input type="text">` | — | `maxlength`, `placeholder` |
-| `textarea` | `<textarea>` | — | `rows`, `maxlength` |
-| `number` | `<input type="number">` | — | `min`, `max`, `step` |
-| `checkbox` | toggle switch | — | `defaultValue` (true/false), `checkboxText` |
-| `select` | `<select>` | Select2 | `dataSource`, `tableField` |
-| `date` | date picker | Flatpickr | `minDate`, `maxDate`, `dateFormat` |
-| `timestamp` | datetime picker | Flatpickr | `minDate`, `maxDate`, `dateFormat` |
-| `time` | time picker | Flatpickr | `minTime`, `maxTime` |
-
-**Notes:**
-- `select` requires a `dataSource` to populate options.
-- `date`/`timestamp`/`time` require Flatpickr assets bundled by the plugin.
-- `checkbox` renders as a toggle switch, not a standard checkbox input.
-
----
-
-## Field Attributes
-
-Common attributes for all field types.
-
-| Attribute | Type | Notes |
-|---|---|---|
-| `name` | string | Field name matching the RDF payload field; snake_case |
-| `label` | string | Display label shown on form and table header |
-| `type` | string | One of the 8 field types above |
-| `required` | boolean | Frontend validation — marks field as mandatory |
-| `readonly` | boolean | Renders as read-only input |
-| `inTable` | boolean | Show column in the data table; default: `true` |
-| `tableOrder` | integer | Column order in table; lower = leftmost |
-| `tableField` | string | Column value to display in table (for `select` — show label, not id) |
-| `width` | integer | Column width in pixels |
-| `placeholder` | string | Input placeholder text |
-| `defaultValue` | any | Default value on new record form |
-| `editorMode` | string | Form only (`"form"`) or table only (`"table"`) |
-| `maxlength` | integer | Max character length for `text`/`textarea` |
-| `rows` | integer | Row height for `textarea` |
-
----
-
-## Field Rows (Layout)
-
-`fieldRows[]` groups fields into a CSS Grid row for multi-column forms.
-Without `fieldRows`, fields render in a single column.
-
-```json
-"fieldRows": [
-  { "fields": ["first_name", "last_name"] },
-  { "fields": ["email", "phone", "status"] }
-]
-```
-
-- Each entry in `fields[]` refers to a field `name` defined in `fields[]`.
-- Fields within a row share the available width equally by default.
-- Use `colSpan` on a field attribute to span multiple columns:
-  `"colSpan": 2` makes a field take 2 of the row's grid columns.
-- Interacts with `features.fieldLayout`: `"horizontal"` places the label
-  to the left of the input; `"vertical"` (default) stacks them.
-
----
-
-## Field States (Conditional)
-
-`fieldStates[]` defines conditional visibility and readonly rules based on
-field values. Applied at runtime when field values change.
-
-```json
-"fieldStates": [
-  {
-    "when": { "field": "status", "value": "approved" },
-    "fields": ["approved_by", "approved_at"],
-    "state": "readonly"
-  },
-  {
-    "when": { "field": "order_type", "value": "internal" },
-    "fields": ["customer_id"],
-    "state": "hidden"
-  }
-]
-```
-
-| Property | Notes |
-|---|---|
-| `when.field` | The triggering field name |
-| `when.value` | The value that triggers the state change |
-| `fields[]` | Fields to affect when the condition is met |
-| `state` | `"readonly"` or `"hidden"` |
-
-Global scope: `fieldStates` at page level applies to all form instances.
-
----
-
-## Features
-
-`features` is an object at page level controlling toolbar and layout behavior.
-
-| Feature | Type | Notes |
-|---|---|---|
-| `enableSearch` | boolean | Show full-text search input in toolbar |
-| `enableStatusFilter` | object | Dropdown filter for boolean/enum field; requires `field` and `options[]` |
-| `enableDataFilter` | array | Dynamic dropdown filters; each entry requires `field` and `dataSource` |
-| `enableLiveSync` | boolean | Enable WebSocket live data refresh; requires `liveSync` at root level |
-| `fieldLayout` | string | Form field label placement: `"vertical"` (default) or `"horizontal"` |
-
-`enableStatusFilter` example:
-```json
-"enableStatusFilter": {
-  "field": "is_active",
-  "options": [
-    { "label": "Active", "value": "true" },
-    { "label": "Inactive", "value": "false" }
-  ]
-}
-```
-
-`enableDataFilter` example:
-```json
-"enableDataFilter": [
-  { "field": "category_id", "dataSource": { "type": "api", "apiPath": "/category" } }
-]
-```
-
----
-
-## Data Source
-
-Used by `select` fields and `enableDataFilter` to populate options.
-
-**Type: static**
-```json
-"dataSource": {
-  "type": "static",
-  "options": [
-    { "id": "active", "text": "Active" },
-    { "id": "inactive", "text": "Inactive" }
-  ]
-}
-```
-
-**Type: api**
-```json
-"dataSource": {
-  "type": "api",
-  "apiPath": "/category",
-  "id": "category_id",
-  "text": "category_name"
-}
-```
-
-- `apiPath` calls the backend `/lookup` endpoint of that resource.
-- `id` maps to the option value; `text` maps to the display label.
-- The `tableField` attribute on the field should reference `text` to show
-  the label (not the id) in the data table column.
-
----
-
-## Navigation
-
-`navigation[]` defines the sidebar menu. Three item types: `page`, `group`,
-`separator`.
-
-```json
-"navigation": [
-  { "type": "page", "pageId": "customer", "icon": "ti ti-users" },
-  { "type": "separator" },
-  {
-    "type": "group",
-    "label": "Master Data",
-    "icon": "ti ti-database",
-    "items": [
-      { "type": "page", "pageId": "category" },
-      { "type": "page", "pageId": "supplier" }
-    ]
-  }
-]
-```
-
-- Maximum nesting depth: 3 levels.
-- When `pageGroup` is set on a page, the sidebar auto-derives navigation —
-  manual `navigation[]` is optional.
-- Manual `navigation[]` overrides auto-derivation completely.
-- `icon` uses Tabler Icons class format: `"ti ti-<name>"`.
-
----
-
-## Homepage
-
-`homepage` sets the default landing page when the app loads.
-
-```json
-"homepage": "dashboard-main"
-```
-
-- Value must match a `pageId` in `pages[]`.
-- Supports both CRUD and dashboard pages.
-- When absent, the first page in `navigation[]` is loaded.
-
----
-
-## Dashboard Page
-
-A page with `pageType: "dashboard"` renders a grid-based analytics view.
-
-```json
-{
-  "pageId": "dash-overview",
-  "pageType": "dashboard",
-  "pageTitle": "Overview",
-  "dataSources": [
-    { "id": "ds-orders", "apiPath": "/order", "action": "aggregate" }
-  ],
-  "rows": [
-    {
-      "columns": [
-        { "colSpan": { "xl": 4, "lg": 6, "md": 12 }, "widget": { ... } },
-        { "colSpan": { "xl": 8, "lg": 6, "md": 12 }, "widget": { ... } }
-      ]
-    }
-  ]
-}
-```
-
-**7 widget types:**
-
-| Widget type | Display | Key properties |
-|---|---|---|
-| `column` | Vertical bar chart | `dataSource`, `labelField`, `valueField`, `color` |
-| `bar` | Horizontal bar chart | `dataSource`, `labelField`, `valueField`, `color` |
-| `pie` | Pie / donut chart | `dataSource`, `labelField`, `valueField` |
-| `area` | Area chart | `dataSource`, `labelField`, `valueField`, `color` |
-| `mini-bar` | Compact bar (KPI card) | `dataSource`, `valueField`, `label`, `icon`, `color` |
-| `progress` | Progress bar list | `dataSource`, `labelField`, `valueField`, `maxValue` |
-| `list` | Simple data list | `dataSource`, `columns[]` |
-
-`dataSources[]` at page level defines reusable data pools; widgets reference
-them by `id`. Each data source calls the backend `/aggregate` endpoint.
-
----
-
-## Master-Detail
-
-A page with `details[]` renders a master-detail composite form.
-
-```json
-{
-  "pageId": "sales-order",
-  "apiPath": "/order",
-  "primaryKey": "order_id",
-  "displayField": "order_no",
-  "fields": [ ... ],
-  "details": [
-    {
-      "pageId": "order-item",
-      "apiPath": "/order-item",
-      "foreignKey": "order_id",
-      "primaryKey": "item_id",
-      "displayField": "product_name",
-      "fields": [ ... ]
-    }
-  ]
-}
-```
-
-- Each entry in `details[]` is a sub-page bound to the master via `foreignKey`.
-- Multiple detail tabs are supported — one entry per detail entity.
-- Generates composite form: master header + detail items grid.
-- Backend must have composite endpoints (`/create-composite`, etc.) generated
-  from the RDF master-detail payload.
-
----
-
-## Workflow Actions
-
-`workflowActions[]` adds status-transition buttons to the form toolbar.
-
-```json
-"workflow": {
-  "statusField": "status"
-},
-"workflowActions": [
-  {
-    "action": "approve",
-    "label": "Approve",
-    "targetStatus": "approved",
-    "fromStatus": ["pending"],
-    "confirm": {
-      "message": "Approve this request?",
-      "summary": ["request_no", "requested_by", "amount"]
-    }
-  }
-]
-```
-
-| Property | Notes |
-|---|---|
-| `workflow.statusField` | Field name that holds the current status |
-| `action` | Action identifier sent to backend `/change-status` |
-| `label` | Button label |
-| `targetStatus` | Status value after transition |
-| `fromStatus[]` | Allowed current statuses for this action to appear |
-| `confirm.message` | Confirmation dialog message |
-| `confirm.summary[]` | Fields to display in the confirmation dialog |
-
----
-
-## ID Generation
-
-Supports auto-generated field values via `defaultValue.source: "idgen"`.
-Requires `IDGEN_ENABLED=true` in backend config.
-
-```json
-{
-  "name": "order_no",
-  "type": "text",
-  "defaultValue": {
-    "source": "idgen",
-    "mode": "serial",
-    "prefix": "ORD",
-    "format": "XXXX-XXXX"
-  }
-}
-```
-
-5 modes: `number` (sequential with prefix/format), `pin` (OTP numeric),
-`code` (voucher-style), `serial` (license key pattern), `random`.
-The field renders as readonly on the form; value is reserved on focus and
-confirmed on submit.
-
----
-
-## Live Sync
-
-WebSocket-based live data refresh. Requires `LIVE_SYNC_ENABLED=true` and
-`LIVE_SYNC_PORT` configured in backend.
-
-Root-level config in UDF:
-```json
-"liveSync": {
-  "url": "ws://localhost:3033",
-  "apiKey": "your-api-key"
-}
-```
-
-Per-page activation:
-```json
-"features": {
-  "enableLiveSync": true
-}
-```
-
-When active, the page's data table auto-refreshes when the backend pushes
-an event over the WebSocket channel.
-
----
-
-## Naming Conventions
-
-| Element | Pattern | Example |
-|---|---|---|
-| `pageId` (CRUD) | `^[a-zA-Z0-9_-]+$` | `sales-order`, `product_list` |
-| `pageId` (dashboard) | `^dash-[a-z0-9-]+$` | `dash-overview`, `dash-monthly` |
-| `widgetId` | `^[a-z][a-z0-9-]*$` | `chart-revenue`, `kpi-orders` |
-| field `name` | snake_case | `order_no`, `customer_id` |
-| `appCode` | kebab-case | `sales-app`, `inventory` |
-| `apiPath` | kebab-case with leading `/` | `"/sales-order"`, `"/product"` |
-| `pageGroup` | Title Case | `"Master Data"`, `"Reports"` |
-
----
-
-## Plugins
-
-Built-in plugins. Run `designer_list_plugins` to confirm what the installed
-version provides — do not hardcode this list.
-
-| Plugin | Auth | Notes |
-|---|---|---|
-| `vanilla-js-basic` | None | Standard CRUD app, no login flow |
-| `vanilla-js-auth` | Auth + RBAC | Login page, token refresh, role-based access |
-| `vanilla-js-custom` | Auth + RBAC | Customisable markup/CSS/JS; auth + RBAC capable (confirm via `designer_list_plugins`) |
-
-Plugin auth is built into the app at generation time. Disable it with
-`noAuth: true` (`--no-auth`) on `designer_init_project` to get the plugin's UI
-without auth. **Plugin auth (with RBAC) is distinct from the embedded `rfx_auth`
-extension** (`designer_auth_create`, no RBAC) — see references/auth.md.
-
-`vanilla-js-auth` accepts additional `appConfig` / init properties:
-- `authAppCode` — must match the backend auth module's app code
-- `idleTimeout` — auto-logout after inactivity (seconds)
-
-**Custom plugins:**
-Use `designer_scaffold_plugin` to generate a plugin template. The plugin
-structure contains `plugin.json` (metadata) and Jinja2 templates for each
-file type (HTML, JS, CSS). Use `designer_inspect_plugin` to verify capabilities
-before referencing a plugin in a UDF payload.
+# Reference: UDF Catalog (UI Definition File)
+
+> **Offline mirror.** This file mirrors `designer_get_udf_catalog` (the
+> `npx restforge-designer catalog` output, built from the validator constants) plus
+> the rules in `restforge-handbook/catalogs/udf/`. The live tool is
+> authoritative — when this file and the tool disagree, trust the tool, then
+> update this file. Field types and features depend on the active plugin
+> version; always re-ground with the tool (and `designer_list_plugins`) before
+> defining a UDF payload.
+
+Source: `designer_get_udf_catalog` — installed designer version.
+Use as grounding before defining or editing any UDF payload.
+
+**Derive, do not hand-write.** When a backend RDF exists, create the UDF with
+`codegen_migrate_payload` and edit its output. Migrate derives field types,
+`required`, `maxlength`, `decimalPlaces`, `format`, `temporalType`, lookups,
+`details[]`, `statusFilter`, `statusBadge`, and `appConfig.dateFormat` /
+`dateTimeFormat` from the RDF and the backend config. Hand-author a page only
+when no RDF exists.
+
+---
+
+## Table of Contents
+
+1. [Payload Envelope](#payload-envelope)
+2. [App Config](#app-config)
+3. [Page Anatomy](#page-anatomy)
+4. [Field Types](#field-types)
+5. [Field Attributes](#field-attributes)
+6. [Field Rows (Layout)](#field-rows-layout)
+7. [Field States (Row Lock)](#field-states-row-lock)
+8. [Features](#features)
+9. [Data Source](#data-source)
+10. [Navigation](#navigation)
+11. [Homepage](#homepage)
+12. [Dashboard Page](#dashboard-page)
+13. [Master-Detail](#master-detail)
+14. [Workflow Actions](#workflow-actions)
+15. [ID Generation](#id-generation)
+16. [Live Sync](#live-sync)
+17. [Naming Conventions](#naming-conventions)
+18. [Plugins](#plugins)
+
+---
+
+## Payload Envelope
+
+Root-level UDF structure:
+
+```json
+{
+  "extends": "app-config.json",
+  "appConfig": { ... },
+  "pages": [ ... ],
+  "navigation": { "items": [ ... ] },
+  "homepage": "contact",
+  "liveSync": { ... }
+}
+```
+
+| Key | Required | Notes |
+|---|---|---|
+| `extends` | no | Path (relative to this file) to a base UDF. `appConfig` comes entirely from the base; `pages` from this file; other root keys (e.g. `auth`, `navigation`) merge with this file winning |
+| `appConfig` | yes | See App Config |
+| `pages` | yes | At least one entry: an inline page object or `{ "include": "pages/contact.json" }` |
+| `navigation` | no | Object with `items[]` — see Navigation |
+| `homepage` | no | `pageId` loaded at the app root |
+| `liveSync` | no | WebSocket config — see Live Sync |
+| `auth` | no | Read by auth-capable plugins — see Plugins |
+
+An `include` file must itself contain a `pages` array (not a bare page object);
+the loader appends its pages in place of the entry, recursively.
+
+**Migrate output layout.** `codegen_migrate_payload` writes a split set into the
+output folder (default `frontend/payload/`): `app-config.json`, one file per
+page under `pages/`, an aggregator `<appCode>.json` that `extends` the config
+and `include`s the pages, and snapshots under `.meta/pages/`. Point every
+designer tool at the aggregator.
+
+---
+
+## App Config
+
+| Property | Type | Required | Notes |
+|---|---|---|---|
+| `appName` | string | yes | Display name shown in page title and header |
+| `appCode` | string | yes | Unique app identifier, kebab-case |
+| `plugin` | string | yes | Output plugin: `vanilla-js-basic`, `vanilla-js-auth`, `vanilla-js-custom`, or a custom plugin |
+| `apiBaseUrl` | string | yes | Backend base URL, joined with each page `apiPath`. A loopback host (`localhost`, `127.x`, `[::1]`, `0.0.0.0`) is re-resolved in the browser from the page's own host and port; use a relative path such as `/api/myapp` behind a reverse proxy on a non-standard port |
+| `port` | integer | no | Port of the static preview server (`app-start.bat`), 1–65535; a string is rejected |
+| `numberFormat` | object | no | `locale`: `en-US` (default, `12,500,000.00`) or `id-ID` (`12.500.000,00`); no other value is accepted. `currencyPrefix`: text before `format: "currency"` values, e.g. `"Rp "` |
+| `dateFormat` | string | no | Must equal backend `DATEFORMAT`. One of `yyyy-MM-dd` (default), `dd/MM/yyyy`, `dd-MM-yyyy`, `MM/dd/yyyy`, `yyyy/MM/dd` |
+| `dateTimeFormat` | string | no | Must equal backend `DATETIMEFORMAT`: `<date pattern> <time pattern>`, time `HH:mm`, `HH:mm:ss`, or `HH:mm:ss.SSS`. Default `yyyy-MM-dd HH:mm:ss.SSS` |
+
+- Decimal places are **not** an app setting: `numberFormat.decimalPlaces` is
+  rejected. Put `decimalPlaces` on the field.
+- `dateFormat` / `dateTimeFormat` are copied from the backend config by every
+  `codegen_migrate_payload` run and always overwritten there. Never keep a
+  locally edited value: the frontend cannot detect a pattern that differs from
+  the backend and would misread dates silently.
+
+---
+
+## Page Anatomy
+
+Each entry in `pages[]` is one page. CRUD page properties:
+
+| Property | Type | Required | Notes |
+|---|---|---|---|
+| `pageId` | string | yes | `^[a-zA-Z0-9_-]+$`; used as the output file name |
+| `pageTitle` | string | yes | Page heading |
+| `pageSubtitle` | string | no | Text under the title |
+| `pageIcon` | string | no | Icon name |
+| `pageGroup` | array of string | no | Sidebar group path, max 2 levels (e.g. `["Master", "People"]`); drives auto-derived navigation |
+| `pageType` | string | no | `"crud"` (default) or `"dashboard"` |
+| `pageSubject` | string | no | Singular object name used in `{addVerb} {pageSubject}`, `Edit {pageSubject}`, and success messages. Default `pageTitle` |
+| `addVerb` | string | no | `Add` (default), `Create`, `Upload`, or `Invite`; anything else is rejected |
+| `showNewBadge` | boolean | no | `New` badge on rows created today, default `true`; needs `created_at` in the list data |
+| `apiPath` | string | yes | Backend resource path, joined with `apiBaseUrl` |
+| `primaryKey` | string | yes | Primary key column; need not be in `fields` |
+| `displayField` | string | yes | Field used as the record label (dialogs, breadcrumb) |
+| `versionField` | string | no | Row-version column sent as `options.expectedVersion` on edit; the backend RDF needs a `concurrency` block for it to be checked |
+| `actions` | object | no | `{ "create", "read", "update", "delete" }` booleans, default all `true`. Hides basic CRUD controls when there is no `auth` block; with `auth`, permissions decide and `false` only produces a warning |
+| `fields` | array | yes | Field definitions (min 1) |
+| `fieldRows` | array | no | Form grid layout |
+| `fieldStates` | array | no | Status values that lock a row |
+| `features` | object | no | Toolbar and form features |
+| `details` | array | no | Master-detail grids |
+| `workflow` | object | no | `statusField` and `transitions` |
+| `workflowActions` | array | no | Status transition buttons |
+
+---
+
+## Field Types
+
+8 field types:
+
+| Type | Renders as | Type-specific attributes |
+|---|---|---|
+| `text` | `<input type="text">` | `maxlength`, `placeholder` |
+| `textarea` | `<textarea>` | `rows`, `maxlength`, `placeholder` |
+| `number` | number input | `min`, `max`, `step`, `format`, `decimalPlaces` |
+| `checkbox` | toggle switch | `defaultValue`, `checkboxText.checked`, `checkboxText.unchecked`, `statusBadge` |
+| `select` | Select2 dropdown | `dataSource` (required), `tableField`, `dependsOn`, `statusBadge` (static only) |
+| `date` | Flatpickr | `dateFormat` |
+| `timestamp` | Flatpickr with time | `dateFormat`, `temporalType` |
+| `time` | Flatpickr time only | — |
+
+- `date` is a calendar date; it never shifts with the reader's time zone.
+- `timestamp` with `temporalType: "timestamp"` (default) is wall-clock time shown
+  as stored. `temporalType: "timestamptz"` is an absolute moment converted to
+  the reader's time zone and sent as ISO UTC; migrate sets it for `timestamptz`
+  columns.
+- A `select` without `dataSource` renders empty (warning).
+
+---
+
+## Field Attributes
+
+Required on every field: `name`, `label`, `type`.
+
+| Attribute | Type | Default | Notes |
+|---|---|---|---|
+| `name` | string | — | Column name, snake_case |
+| `label` | string | — | Form label and table header |
+| `type` | string | — | One of the 8 types |
+| `required` | boolean | `false` | Client-side required check |
+| `readonly` | boolean | `false` | Read-only in every mode; not validated, not sent on save |
+| `readonlyOnEdit` | boolean | `false` | Read-only in edit mode only (e.g. a code set once on create). Cannot be combined with `readonly` or `editorMode` |
+| `editorMode` | string | — | `"hidden"`: rendered but invisible, filled from `defaultValue` on add and from the record on edit, then sent like a normal field. `"readonly"`: same as `readonly: true` |
+| `inTable` | boolean | `false` | Show as a list column |
+| `tableOrder` | integer | — | Column order (from 1); a warning when `inTable` is set without it |
+| `tableField` | string | — | Column to display in the list instead of `name`, e.g. `city_name` for `city_id` |
+| `width` | string | auto | CSS width of the list column, e.g. `"200px"`, `"30%"` |
+| `placeholder` | string | — | Input placeholder |
+| `maxlength` | integer | — | `text` / `textarea` |
+| `defaultValue` | any | — | Value on add: a literal, `today`/`now`, or an idgen object |
+| `format` | string | — | `number` only: `"number"` (thousand separators) or `"currency"` (prefix from `numberFormat.currencyPrefix`). Without `format`, the value is shown raw |
+| `decimalPlaces` | integer | `0` | `number` only, 0–20; migrate derives it from the column scale |
+| `dateFormat` | string | `appConfig.dateFormat` | `date` / `timestamp`: display pattern of the date part for this field only; parsing always uses the app patterns |
+| `temporalType` | string | `timestamp` | `timestamp` fields only: `timestamp` or `timestamptz` |
+| `statusBadge` | boolean | `false` | Show as the fixed-palette Status column. `checkbox` or static `select` only; max one per page. A `checkbox` with `statusBadge` also adds `Deactivate` / `Activate` to the row Actions menu |
+| `checkboxText` | object | — | `{ "checked": "Active", "unchecked": "Inactive" }` |
+
+`valueFormat` is no longer supported and is rejected. `min`/`max` on `date`
+fields are not read by the validator.
+
+---
+
+## Field Rows (Layout)
+
+`fieldRows[]` places several fields side by side in one CSS grid row. Without
+it, fields render one per row.
+
+```json
+"fieldRows": [
+  { "fields": ["first_name", "last_name"] },
+  { "fields": ["email", "phone", "status"] }
+]
+```
+
+- Each name refers to a `name` in `fields[]`; the column count equals the number
+  of fields in the row.
+- A field in `fields` that is not referenced in `fieldRows` is not rendered
+  (warning), except `editorMode: "hidden"` fields.
+- `features.fieldLayout` `"horizontal"` puts the label left of the input;
+  `"vertical"` (default) stacks them.
+
+---
+
+## Field States (Row Lock)
+
+`fieldStates[]` marks status values that make a row read-only: `Edit`,
+`Delete`, and `Deactivate`/`Activate` are shown disabled with an info tooltip.
+It does not hide or lock individual form fields.
+
+```json
+"fieldStates": [
+  { "when": { "status": ["posted", "cancelled"] }, "state": "readonly" }
+]
+```
+
+| Property | Notes |
+|---|---|
+| `when` | Key = the status field name (`workflow.statusField`, default `status`); value = array of status values |
+| `state` | `"readonly"` |
+
+Takes effect only with `vanilla-js-auth` or `vanilla-js-custom`, and only on a
+page with at least one `workflowActions` item. The validator also accepts
+`state: "hidden"`, a `fields` list, and a string `when`, but the generator
+ignores them. `fieldStates` is frontend only: enforce the same rule in the
+backend with a component hook (e.g. `onBeforeUpdate`, `onBeforeDelete`).
+
+---
+
+## Features
+
+`features` is an object on a CRUD page.
+
+| Feature | Type | Notes |
+|---|---|---|
+| `enableSearch` | boolean | Search box; server-side search |
+| `enableStatusFilter` | boolean | Status dropdown in the toolbar; configured by `statusFilter` |
+| `statusFilter` | object | `{ field, label, options: [{ value, text }] }`; required when `enableStatusFilter` is `true` |
+| `enableDataFilter` | boolean | Extra filters; configured by `dataFilters` |
+| `dataFilters` | array | Entries with keys `name`, `field`, `label`, `dataSource`, `dependsOn`, `display` (`inline` or `dropdown`), `width`. `field` is required for `vanilla-js-auth` and `vanilla-js-custom` |
+| `enableLiveSync` | boolean | WebSocket refresh; needs the root `liveSync` block |
+| `autoRefresh` | object | `{ "interval": <seconds, min 10> }` polling; not together with `enableLiveSync`; not in `vanilla-js-basic` |
+| `fieldLayout` | string | `"vertical"` (default) or `"horizontal"` |
+
+```json
+"features": {
+  "enableSearch": true,
+  "enableStatusFilter": true,
+  "statusFilter": {
+    "field": "is_active",
+    "label": "Status",
+    "options": [ { "value": "true", "text": "Active" }, { "value": "false", "text": "Inactive" } ]
+  },
+  "enableDataFilter": true,
+  "dataFilters": [
+    { "name": "city_id", "field": "city_id", "label": "City",
+      "dataSource": { "type": "api", "resource": "city", "select": ["city_id", "city_name"] } }
+  ]
+}
+```
+
+At most 2 filters (status + data filters) are shown inline; the rest move to a
+"More Filters" popup unless `display` overrides it. Migrate generates
+`statusFilter` for the main status column.
+
+---
+
+## Data Source
+
+Used by `select` fields and `dataFilters[]`.
+
+**Type: static**
+```json
+"dataSource": {
+  "type": "static",
+  "options": [
+    { "value": "active", "text": "Active" },
+    { "value": "inactive", "text": "Inactive" }
+  ]
+}
+```
+
+With `required: true` the first option is preselected; otherwise a
+`-- Select --` placeholder comes first.
+
+**Type: api**
+```json
+"dataSource": {
+  "type": "api",
+  "resource": "category",
+  "select": ["category_id", "category_name"]
+}
+```
+
+| Key | Notes |
+|---|---|
+| `resource` | Backend resource; the request goes to `POST <apiBaseUrl>/<resource>/lookup`, which answers `{ id, text }` rows (configured by RDF `fieldNameLookup`) |
+| `select` | Columns requested from `/lookup` |
+| `url` | Explicit lookup path; used only in master-detail grids, ignored on master pages |
+| `lookupMode` | `"static"` (load once, default) or `"dynamic"` (AJAX search while typing) |
+| `lookupDisplay` | `"select2"` (default) or `"modal"` (search dialog with a table) |
+| `optionColumns` | `[{ column, format: "number", decimalPlaces, align }]`; columns shown in the dropdown or modal, each must be in `select` |
+| `autofill` | Copies columns of the chosen row into other fields of the same form or grid row |
+
+`dependsOn` (a sibling `select` field name) turns a field into a cascade. Set
+`tableField` on the field so the list shows the label column, not the id.
+
+---
+
+## Navigation
+
+`navigation` is an **object** with `items[]`. Without it, the sidebar is
+derived from `pageGroup`; with it, `pageGroup` is ignored (warning).
+
+```json
+"navigation": {
+  "items": [
+    { "type": "page", "pageRef": "dashboard", "icon": "home" },
+    { "type": "separator" },
+    {
+      "type": "group",
+      "label": "Master Data",
+      "icon": "data",
+      "children": [
+        { "type": "page", "pageRef": "category" },
+        { "type": "page", "pageRef": "supplier", "badgeColor": "info" }
+      ]
+    },
+    { "type": "link", "label": "Payroll Report", "href": "report-payroll.html", "permission": "REPORT_PAYROLL_READ" }
+  ]
+}
+```
+
+| Item type | Keys |
+|---|---|
+| `page` | `pageRef` (required, a `pageId`), `label` (default `pageTitle`), `icon`, `badgeColor` |
+| `group` | `label` (required), `children` (required, non-empty), `icon` |
+| `link` | `label` and `href` (required; a hand-written HTML file), `permission` (string or array; used only with an `auth` block), `icon`, `badgeColor` |
+| `separator` | — |
+
+- `badgeColor`: `danger`, `info`, `primary`, `success`, `warning`.
+- Maximum nesting depth: 3. `icon` renders at depth 1 only.
+- Icons are Keenicons (`vanilla-js-auth`): one word (`"data"`) renders
+  `ki-outline ki-data fs-2`; a value with spaces is used as the class string.
+  Do not use Tabler classes (`ti ti-*`).
+- With an `auth` block, a `page` item is hidden when the user lacks
+  `permissions.<pageRef>.read`; groups whose items are all hidden disappear.
+- Re-running migrate keeps a hand-built `navigation` and adds new pages at the
+  top level.
+
+---
+
+## Homepage
+
+`homepage` sets the page loaded at the app root.
+
+```json
+"homepage": "dashboard-main"
+```
+
+- Value must match a `pageId` in `pages[]`; CRUD and dashboard pages both work.
+- When absent, the first page in `pages[]` is the default.
+
+---
+
+## Dashboard Page
+
+A page with `pageType: "dashboard"` renders a widget grid. It reads data from
+URLs you declare; it does not call `/aggregate` by itself.
+
+```json
+{
+  "pageId": "overview",
+  "pageType": "dashboard",
+  "pageTitle": "Overview",
+  "refreshInterval": 300,
+  "dataSources": {
+    "revenueMonthly": { "url": "/api/myapp/dash-sales/dashboard", "method": "POST", "body": {} }
+  },
+  "rows": [
+    {
+      "columns": [
+        {
+          "colSpan": { "base": 12, "md": 6, "lg": 4 },
+          "widgets": [
+            {
+              "widgetId": "revenue-chart",
+              "widgetType": "column",
+              "title": "Revenue per Month",
+              "dataSource": "revenueMonthly",
+              "chartEngine": "apexcharts",
+              "chart": { "xField": "month", "yField": "revenue" }
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}
+```
+
+| Part | Rules |
+|---|---|
+| `pageId` | `^[a-z][a-z0-9-]*$` (no underscore, no uppercase); no `dash-` prefix needed |
+| Allowed page keys | `dataSources`, `pageGroup`, `pageIcon`, `pageId`, `pageSubject`, `pageSubtitle`, `pageTitle`, `pageType`, `refreshInterval`, `rows` |
+| Forbidden keys (error) | `apiPath`, `primaryKey`, `displayField`, `fields`, `fieldRows`, `details`, `workflowActions`, `workflow`, `fieldStates`, `features` |
+| `dataSources` | Required object `name → { url, method, body }`; `method` is `GET` (default) or `POST`, `body` is sent with `POST` only |
+| `refreshInterval` | Seconds, 15–3600, default 300 |
+| `colSpan` | Per breakpoint `base`, `sm`, `md`, `lg`, `xl`, `xxl`, values 1–12 |
+| `widgets[]` | `widgetId` (`^[a-z][a-z0-9_-]*$`, unique per page), `widgetType`, `title`, `subtitle`, `dataSource` (a `dataSources` key), `chartEngine`, `chart`, `display` |
+
+7 widget types:
+
+| `widgetType` | Needs `chart` + `chartEngine` | `chart` keys |
+|---|---|---|
+| `column`, `bar`, `area` | yes | `xField`, `yField`, `format` |
+| `pie` | yes | `xField`, `yField`, `shape` (`pie`, `donut`, `semi-pie`, `semi-donut`), `format` |
+| `mini-bar` | yes | `xField`, `yField`, `format` |
+| `progress`, `list` | no — `chart`/`chartEngine` are rejected | — |
+
+`chartEngine`: `apexcharts` or `amcharts`. `chart.format.<xAxis|yAxis|tooltip|dataLabel>`
+accepts `prefix`, `suffix`, `decimalPlaces`. `chart.library` and
+`chart.orientation` are deprecated.
+
+---
+
+## Master-Detail
+
+A CRUD page with `details[]` renders the master form plus one editable grid per
+detail. Migrate builds `details[]` from the RDF `masterDetail` block.
+
+```json
+"details": [
+  {
+    "detailId": "items",
+    "detailTitle": "Order Items",
+    "primaryKey": "item_id",
+    "fields": [
+      { "name": "product_id", "label": "Product", "type": "select",
+        "dataSource": { "type": "api", "resource": "product", "select": ["product_id", "product_name", "price"],
+                        "autofill": { "price": "price" } } },
+      { "name": "qty", "label": "Qty", "type": "number", "defaultValue": 1 },
+      { "name": "price", "label": "Price", "type": "number", "format": "number", "decimalPlaces": 2 },
+      { "name": "subtotal", "label": "Subtotal", "type": "number", "readonly": true,
+        "calculated": { "formula": "qty * price" }, "format": "number", "decimalPlaces": 2 }
+    ],
+    "summary": { "totalItems": true, "totalQtyField": "qty", "grandTotalField": "subtotal" }
+  }
+]
+```
+
+| Property | Required | Notes |
+|---|---|---|
+| `detailId` | yes | Detail key in the composite payload |
+| `detailTitle` | no | Grid heading; default = `detailId` in Title Case |
+| `primaryKey` | yes | Detail row primary key |
+| `fields` | yes | Same field structure as the master |
+| `summary` | no | `totalItems`, `totalQtyField`, `grandTotalField` |
+
+- `calculated.formula` supports only `"<fieldA> * <fieldB>"`.
+- Only one detail level; no nested details.
+- The backend RDF needs `masterDetail` and the composite actions.
+- To keep a user-defined row order, store it in a `line_number` column the user
+  fills in; the server does not number rows.
+
+---
+
+## Workflow Actions
+
+`workflowActions[]` adds a **Change Status** item to each row's Actions menu.
+The dialog shows one button per allowed target status.
+
+```json
+"workflow": {
+  "statusField": "status",
+  "transitions": {
+    "pending": ["paid", "cancelled"],
+    "paid": ["shipped"],
+    "shipped": [],
+    "cancelled": []
+  }
+},
+"workflowActions": [
+  {
+    "actionId": "paid",
+    "label": "Paid",
+    "icon": "check",
+    "style": "success",
+    "confirm": { "title": "Mark this order as paid?", "message": "Stock will be deducted.", "confirmButton": "Yes, mark as paid", "cancelButton": "Cancel" },
+    "api": { "endpoint": "sales-order/change-status", "payload": { "sales_order_id": "$primaryKey", "status": "paid" } },
+    "onSuccess": { "notification": { "type": "success", "message": "Order marked as paid." } },
+    "onError": { "display": "modal", "title": "Payment rejected" }
+  }
+]
+```
+
+| Property | Notes |
+|---|---|
+| `workflow.statusField` | Required when `workflowActions` exists; the column must be returned by `/datatables` |
+| `workflow.transitions` | `current → [targets]`. A button renders only for a target listed here **and** having an action with the same `actionId`. Without `transitions` no button ever shows. Keep it identical to the RDF `workflow.transitions` |
+| `actionId` | Required, unique per page, **equal to the target status** |
+| `label` | Required |
+| `icon`, `style` | Optional; `style` = `primary` (default), `success`, `danger`, `secondary`, `info`, `warning` |
+| `confirm` | Optional: `title`, `message`, `confirmButton`, `cancelButton` |
+| `api` | Required: `endpoint` (default `<apiPath>/change-status`, no leading slash) and/or `payload` (`"$primaryKey"` is replaced) |
+| `onSuccess.notification` | `{ type, message }` |
+| `onError` | `{ display: "modal" \| "toast", title }` |
+
+`confirm.summary[]` is accepted by the validator but not rendered. A backend
+rejection (422 invalid transition, 400 hook rejection, 502 blocking hook failure)
+is shown with the response `message`.
+
+---
+
+## ID Generation
+
+`defaultValue.source: "idgen"` fills a field from the backend ID generator.
+Requires `IDGEN_ENABLED=true` in the backend config.
+
+```json
+{
+  "name": "invoice_no",
+  "type": "text",
+  "defaultValue": {
+    "source": "idgen",
+    "mode": "number",
+    "resource": "invoice",
+    "format": "yyyymm",
+    "numDigits": 5,
+    "separator": "-",
+    "reserve": true,
+    "ttl": 60
+  }
+}
+```
+
+| Key | Notes |
+|---|---|
+| `mode` | `number`, `pin`, `code`, `serial`, `random` |
+| `resource` | Required namespace; must not contain `:` |
+| `format` | `number` mode: `text`, `yyyy`, `yyyymm`, `yyyymmdd` |
+| `numDigits`, `separator` | `number` mode |
+| `digits` | `pin` mode (default 6) |
+| `pattern` | `code`, `serial`, `random` modes |
+| `reserve`, `ttl` | Reserve the value while the form is open; max one `reserve: true` field per page |
+
+Allowed field types: `number`, `text`, `textarea`.
+
+---
+
+## Live Sync
+
+WebSocket-based list refresh. Requires `LIVE_SYNC_ENABLED=true` and
+`LIVE_SYNC_PORT` in the backend config.
+
+Root-level config:
+```json
+"liveSync": {
+  "url": "ws://localhost:3033",
+  "apiKey": "your-api-key"
+}
+```
+
+Per-page activation: `"features": { "enableLiveSync": true }`. `url` must start
+with `ws://` or `wss://`. A page with `enableLiveSync` and no root `liveSync` is
+an error; a `liveSync` block no page uses is a warning.
+
+---
+
+## Naming Conventions
+
+| Element | Pattern | Example |
+|---|---|---|
+| `pageId` (CRUD) | `^[a-zA-Z0-9_-]+$` | `sales-order`, `product_list` |
+| `pageId` (dashboard) | `^[a-z][a-z0-9-]*$` | `overview`, `monthly-sales` |
+| `widgetId` | `^[a-z][a-z0-9_-]*$` | `chart-revenue`, `kpi_orders` |
+| field `name` | snake_case | `order_no`, `customer_id` |
+| `appCode` | kebab-case | `sales-app`, `inventory` |
+| `pageGroup` entries | consistent casing | `["Master Data"]` |
+
+---
+
+## Plugins
+
+Built-in plugins. Run `designer_list_plugins` to confirm what the installed
+version provides — do not hardcode this list.
+
+| Plugin | Auth | Notes |
+|---|---|---|
+| `vanilla-js-basic` | None | Standard CRUD app, no login flow |
+| `vanilla-js-auth` | Auth + RBAC | Login page, token refresh, role-based access |
+| `vanilla-js-custom` | Auth + RBAC | Customisable markup/CSS/JS; auth + RBAC capable (confirm via `designer_list_plugins`) |
+
+Plugin auth is built into the app at generation time. Disable it with
+`noAuth: true` (`--no-auth`) on `designer_init_project` to get the plugin's UI
+without auth. **Plugin auth (with RBAC) is distinct from the embedded `rfx_auth`
+extension** (`designer_auth_create`, no RBAC) — see references/auth.md.
+
+Auth-capable plugins read a root-level `auth` block, not `appConfig` keys:
+
+```json
+"auth": {
+  "appCode": "MY_APP",
+  "authApiUrl": "http://localhost:3000/api/auth",
+  "idleTimeoutMinutes": 30
+}
+```
+
+`designer_init_project` fills this block from its auth app code and idle
+timeout options. It also leaves an `appConfig.authAppCode` copy, which no plugin
+reads; edit `auth.appCode`, never `appConfig.authAppCode`.
+
+**Custom plugins:**
+Use `designer_scaffold_plugin` to generate a plugin template. The plugin
+structure contains `plugin.json` (metadata) and Jinja2 templates for each
+file type (HTML, JS, CSS). Use `designer_inspect_plugin` to verify capabilities
+before referencing a plugin in a UDF payload.