@xeplr/ui-factory 1.8.2 → 1.8.4

package/AUTHORING.md

@@ -25,7 +25,9 @@ A request for "a form for employees" is an **entity**. Every entity is the same
 | the request says… | change |
 |---|---|
 | a field, a label, a rule, a dropdown, the layout, a colour | the screen JSON (then validate) |
-| "show / hide / filter rows on screen", "an extra button on each row", "fill in X before saving" (convenience) | front-end hooks in `EditEmployee.jsx` |
+| "a button that does something to a record" — set a status, confirm, approve | a **Buttons** control naming a function (event `button`) and its parameters; the function in `employee.functions.js` — one function, many buttons with different parameters |
+| "a list whose rows are worked out", "a search box", "filter chips with counts" | a list with `rowsFrom` naming a function (event `listRows`) that returns `{ rows, counts }` — the text it shows is the function's |
+| "show / hide / filter rows on screen", "fill in X before saving" (browser convenience — web only) | front-end hooks in `EditEmployee.jsx` |
 | "must", "only if", "check against…", "email when…", "only managers see…" | a server function in `employee.functions.js`, named in the screen's `events` |
 | "store as…", "convert…", "comma-separated / array", "work out X from Y" (data shape) | server model in `employee.model.js` |
 | a query in your own server code | `factory.table('employees')` — this company, active rows, the model applied |
@@ -228,6 +230,23 @@ For an entity, `screens` makes the list for you. By hand: a `list` shows the sav
 
 A list needs a table: set the screen's `source` or the list's own.
 
+## Buttons
+
+A button is **a registered function and its parameters** — never code. Several buttons that do the same thing with different values (eight statuses) are one function:
+
+```json
+{ "type": "buttons", "props": { "buttons": [
+  { "id": "packed", "label": "Packed", "action": "setOrderStatus", "params": { "status": "packed" },
+    "ask": { "note": "Reason (optional)" }, "disabledWhen": [{ "field": "customStatus", "op": "eq", "value": "packed" }] }
+] } }
+```
+
+Register the function with `event: 'button'` and an `inputSchema` (with `options` for the values allowed, and a `note` input if a button asks for one). `when` / `disabledWhen` are `@xeplr/rules` rules on the record. Publishing refuses parameters the function does not take. See the README's "Buttons".
+
+## When the document cannot say it
+
+Say so — "this needs a new control" — rather than writing a page by hand around it. If a hand-written page is agreed, list it in the app's `ui/pages.json` under `webOnly` with the reason: it will not be in a phone app, and `npx xeplr-factory pages` says so on every commit.
+
 ## Dropdowns
 
 A dropdown **always saves an `id` and shows a `name`.**
@@ -312,6 +331,7 @@ npx xeplr-factory generate <spec.json|-> [-o <screen.json>]   # spec → documen
 npx xeplr-factory validate <screen.json|->                    # exit 1 with every problem listed
 npx xeplr-factory controls                                     # controls, props, validation rules
 npx xeplr-factory schema <screen.json|->                       # the form's @xeplr/schema-handler schema
+npx xeplr-factory pages [<ui dir>] [--strict]                  # warn about web-only pages and routes ui/pages.json does not list
 ```
 
 The `schema` output is what the app's server checks a submission against: `applySchema(formSchema(document), body)`.

package/README.md

@@ -117,6 +117,21 @@ If `onSave` throws an error with `fields: [{ field, message }]` (what `createFac
 
 Values arrive typed: numbers as numbers, checkboxes as booleans, dates as `"YYYY-MM-DD"`, a date and time as `"YYYY-MM-DDTHH:MM"`, a dropdown or radio group as the option's own `id` (a table's numeric id stays a number), a multi-select as an **array** of ids, and a file as the stored file's **path**.
 
+### On a phone
+
+Below **640px wide** (the viewport, not the box the screen sits in) a screen stops being a scaled-down canvas and **stacks**: every control takes the full width, one per row, in reading order — top to bottom, left to right across a row, the same order `inputNodes` reads. Nothing to set and nothing to design twice: the positions you placed are simply not used there.
+
+- Controls are drawn at their real size, not shrunk. Inputs are at least **16px** (smaller makes iOS zoom the page when a field is focused) and **44px** tall; tick boxes, radio buttons and Remove are thumb-sized.
+- Error messages sit under their field and wrap, rather than being cut off at the screen's edge.
+- The footer wraps: what the save is doing on its own line, the buttons under it sharing the width.
+- A popup (a list's Edit / New) fills the screen.
+- A list keeps its table, which scrolls sideways inside its card; its row buttons stay pinned at the right edge (that part is `@xeplr/ui-table`, 1.1.3 or later).
+- An identifier still to be numbered takes no space.
+
+Above 640px nothing changes: a screen is shown at its design width, scaled down only when its box is narrower. A screen in a narrow side panel on a desktop keeps its designed layout. The builder and the flow designer are not for phones and are left as they are.
+
+How: `ScreenSample` hands each control's position to CSS as variables (`--xf-x`, `--xf-y`, `--xf-w`, `--xf-h`) and its reading-order place as `--xf-order`; `factory.css` uses the positions on a desktop and the order on a phone. A design of your own can do the same.
+
 ### Where each value is kept
 
 A record is columns in a real table, never JSON — so the two types that are not
@@ -346,6 +361,163 @@ to one of these); the screen only names it:
 - **Checked twice.** Here, that each name could be a function and each event exists. On the server, at publish and when it runs, that the function is registered *for that event* — a missing one refuses with its name (`missingFunctions(doc, registry)`).
 - `SCREEN_EVENTS` carries each event's contract (`when`, `gets`, `returns`) — what the designer shows beside each picker.
 
+## Screens and buttons — the rules
+
+These are the rules every app's `CLAUDE.md` points to. They keep a screen
+drawable by **anything that reads a document** — the web today, a phone app
+next — and they hold whoever does the work.
+
+1. **A screen is a document.** To change a screen, change its document (the
+   `.screen.json`, or the builder) and run `npx xeplr-factory validate`. Never
+   hand-write a page for something a document can say.
+2. **A button is a function and its parameters.** The app registers the
+   function once on the server (`@xeplr/actions`, `event: 'button'`, an
+   `inputSchema` saying what it takes); the document names it and gives the
+   values. Eight status buttons are **one** function with eight `status`
+   values — not eight functions, and never code in the document.
+3. **Rows that are worked out come from a function too** (`rowsFrom`, event
+   `listRows`), and so does a cell's hover box (`details`, event
+   `rowDetails`). Formatting — times in the business zone, money, "2h ago" —
+   is the function's: the screen shows the text it wrote.
+4. **When the document cannot say it**, say so first — "this needs a new
+   control" — and add the control to this package, with its web view now
+   and a phone view to follow. Do not build around it.
+5. **If a page must be hand-written anyway, it is web only, out loud.** List
+   it in the app's `ui/pages.json` under `webOnly` with the reason.
+   `npx xeplr-factory pages` (the pre-commit hook) warns about every web-only
+   page and every route nobody listed, and the app's menu settings tag the
+   item "Web only". It is never refused — only never secret.
+6. **Checked on the server.** Publishing refuses a screen whose functions are
+   not registered, are registered for something else, or are given parameters
+   they do not take — saying which button and why (`functionProblems`).
+
+## Buttons — a function and its parameters
+
+A **Buttons** control (palette: Actions → Buttons) is a panel of buttons, each
+naming a function of the app and the values it is given:
+
+```json
+{ "type": "buttons", "props": { "title": "Status", "buttons": [
+  { "id": "packed", "label": "Packed", "action": "setOrderStatus", "params": { "status": "packed" },
+    "ask": { "title": "Change status to “Packed”?", "note": "Reason (optional)" },
+    "disabledWhen": [{ "field": "customStatus", "op": "eq", "value": "packed" }] },
+  { "id": "cod-confirm", "label": "Confirm COD", "action": "confirmCod", "params": { "undo": false },
+    "when": [{ "field": "paymentMethod", "op": "eq", "value": "COD" }], "variant": "primary" }
+] } }
+```
+
+The function, in the app's server code:
+
+```js
+actions.register({
+  name: 'setOrderStatus', event: 'button',
+  description: 'Sets the order status and posts who changed it',
+  inputSchema: [
+    { name: 'status', type: 'string', required: true, options: [{ value: 'packed', label: 'Packed' }, { value: 'shipped', label: 'Shipped' }] },
+    { name: 'note', type: 'string' }
+  ],
+  execute: async ({ input, system }) => {
+    // system: { record, id, user, tenant, knex, db, screen, screenKey, button, reject }
+    await system.db('orders').where('id', system.id).update({ customStatus: input.status })
+    return { message: 'Order ' + system.record.name + ' is now ' + input.status }
+  }
+})
+```
+
+| key | |
+|---|---|
+| `id` | what a press names the button by — unique on the screen |
+| `label` | the button's text |
+| `action` | the registered function (event `button`) |
+| `params` | the values it is given — plain values, checked against its `inputSchema` (`options` = the values allowed) at publish |
+| `ask` | asked first: `title`, `message`, and `note` — the label of a note box, whose text reaches the function as `note` (it must take one) |
+| `when` | shown only when every rule matches the record |
+| `disabledWhen` | greyed out when every rule matches |
+| `variant` | `default`, `primary`, `danger` |
+
+Rules are [`@xeplr/rules`](https://www.npmjs.com/package/@xeplr/rules) rules — `{ field, op, value }`, with `eq`, `neq`, `isEmpty`, `contains`, `gt`, … — read from **the record the screen is about**: the `record` handed to `<FactoryScreen>`, with the form's own changes on top.
+
+- **The press runs on the server** (`POST /factory/buttons/:screen/:button`). It reads the button — function and parameters — from the **published** screen, so a request cannot run another function or change the values; it sends the record's id and the note, nothing else.
+- **The record decides.** The server reads the record (this company, active rows) and checks `when` / `disabledWhen` again, so a hidden or greyed-out button cannot be pressed by sending the request — "does not apply to this record now" (409) when it changed underneath.
+- **What happens next is the host's.** The panel shows the function's `message`; `onButtonDone({ button, result, record })` lets the page reload what it shows. Lists on the same screen reload by themselves.
+- **In the builder**, picking a function lists the parameters it takes — a dropdown where it names the values allowed — so nobody types a status by hand. Functions come from `listFunctions` (`createFactoryApi`'s `builderProps` has it).
+
+## A list whose rows a function works out — `rowsFrom`
+
+A list reads one table's records. When the rows are **worked out** — an
+order's state from its tasks, "New" for the person looking, an urgency sort —
+a registered function answers instead (event `listRows`), with a search box,
+filter chips and the count on each:
+
+```json
+{ "type": "list", "props": {
+  "title": "Orders", "rowsFrom": "orderList", "actions": [], "editScreen": "order_actions", "openIn": "page", "rowOpen": true,
+  "search": { "placeholder": "Search order, customer or city" },
+  "filters": [{ "key": "all", "label": "All" }, { "key": "packed", "label": "Packed" }],
+  "refreshEvery": 60, "highlight": "isNew", "pageSize": 50, "grow": true,
+  "columns": [
+    { "field": "orderNumber", "label": "Order", "text": "orderLabel", "badges": [{ "field": "isNew", "label": "New" }, { "field": "cancelled", "label": "Cancelled", "tone": "danger" }] },
+    { "field": "customerName", "label": "Customer", "sub": "city" },
+    { "field": "images", "label": "Items", "display": "images", "more": "moreImages", "sortable": false },
+    { "field": "ageMs", "label": "Aging", "text": "agingText" },
+    { "field": "lastActivityAt", "label": "Last activity", "text": "lastActivityText", "display": "activity", "details": "orderActivity", "sortable": false }
+  ] } }
+```
+
+```js
+actions.register({ name: 'orderList', event: 'listRows', execute: async (ctx) => {
+  // ctx.query = { q, filter } — what was typed, and the chip (always one of the list's own)
+  // ctx.user, ctx.tenant, ctx.db(table), ctx.knex
+  return { rows: [...], counts: { all: 41, packed: 6 } }
+} })
+actions.register({ name: 'orderActivity', event: 'rowDetails', execute: async (ctx) =>
+  // ctx.id — the row; ctx.column
+  [{ text: 'Status set to Packed', sub: 'Asha', at: 'Today, 4:00 pm', open: { tab: 'comments' } }]
+})
+```
+
+| column key | |
+|---|---|
+| `field` | the value the column **sorts by** (a number, an ISO time) |
+| `text` | the field holding what is **shown** — written by the function, in the app's words and time zone. Blank → the value |
+| `sub` | a second line, smaller |
+| `badges` | `[{ field, label, tone }]` after the text, where `field` is true. Tones: `accent`, `success`, `warning`, `danger`, `muted` |
+| `display` | `text` (default), `images` (`[{ src, name }]`, plus `more`: how many others), `activity` (a line with a hover box) |
+| `details` | for `activity`: the function (event `rowDetails`) whose entries the hover box lists; an entry with `open` opens the row at that place (passed to `onOpenRecord` as `params`) |
+| `sortable` | `false` for a column whose header should not sort |
+
+- **The search and the chip live in the URL** under the screen's `urlKey` (`<urlKey>Q`, `<urlKey>Filter`), so a refresh shows the same rows. The search waits for a pause in typing.
+- **`refreshEvery`** (seconds, 10–3600) asks again — for text that changes with time. **`reloadKey`** on `<FactoryScreen>` reloads every list when it changes (the host heard something happen).
+- **`grow`** (a list that is its screen's **one** control) lets the page grow with the rows on a desktop, instead of the list scrolling inside the box it was placed in — a full-page list like Orders. Phones always flow.
+- **`rowOpen`** makes a click anywhere on a row open it (the first cell is also a button, for the keyboard); **`highlight`** marks rows whose field is true.
+- **Rows that are worked out are not a table's records**: no Delete, and Edit / New only with an `editScreen`.
+- Routes: `GET /factory/rows/:screen` (`?node=&q=&filter=`) and `/factory/rows/:screen/details` (`?node=&column=&id=`) — see `@xeplr/factory`.
+
+## Web-only pages — `ui/pages.json`
+
+Each app keeps an inventory of its pages: drawn from documents, or
+hand-written for the browser (and so **not** in a phone app).
+
+```json
+{
+  "routes": ["src/App.jsx"],
+  "documents": [{ "path": "/orders", "menu": "Orders", "screen": "orders_board" }],
+  "webOnly": [{ "path": "/home", "menu": "Home", "reason": "The dashboard's cards are hand-written" }]
+}
+```
+
+```sh
+npx xeplr-factory pages ui            # warnings, exit 0
+npx xeplr-factory pages ui --strict   # warnings fail
+```
+
+It warns about every web-only page (with its reason), every `<Route path>`
+in the `routes` files that the inventory does not list, and every listed page
+no route declares any more. Redirects and `*` are not pages. Run it from the
+app's pre-commit hook; it never blocks a commit. `webOnlyMenus(inventory)`
+gives `{ menu key → reason }`, for a menu-settings screen to tag those items
+"Web only".
+
 ## The flow designer, as a list — `<FlowDesigner>`
 
 Your screens as a journey: the steps down the left; for the one picked, its
@@ -616,7 +788,8 @@ Both walk someone through something, and they answer different questions:
 | `file` | the stored file's path | `accept` (extensions), `maxSize` (MB) |
 | `stepper` | — | a journey across the top; every other control says which step it is on |
 | `label` | — | text with a heading, subheading or text preset |
-| `list` | — | saved records, with New / Edit / Delete |
+| `list` | — | saved records, with New / Edit / Delete — or rows a function works out (`rowsFrom`), with search, filter chips and counts; see above |
+| `buttons` | — | a panel of buttons, each a registered function and its parameters — see above (palette: **Actions → Buttons**) |
 | `table` | array of the rows ticked | `minItems`, `maxItems`; `required` = at least one. Rows the screen is **handed** (`rows: '{params.lines}'`), not a table it reads; `columns` (`ref, amount`) or every key of the first row; `selectable` (a tick per row, on by default). Adds no column — see below |
 | `subform` | — | another form drawn inside this one (palette: **Form**), saving into its own table — see below |
 
@@ -811,6 +984,7 @@ The control whose properties are open, the step a stepper is open at, and the fl
 | `useFactoryBuilder` / `<FactoryBuilder>` | `<urlKey>Steps` | the step each stepper is open at: `stepperId:index`, comma-separated, step 0 left out | replaces |
 | `useFactoryScreen` / `<FactoryScreen>`, `<FlowRunner>` | `<urlKey>Steps` | as above | replaces |
 | `useFlowBuilder` / `<FlowBuilder>` | `<urlKey>Selected` | the key of the selected flow step | as for a control |
+| `useFactoryScreen` / `<FactoryScreen>` | `<urlKey>Q`, `<urlKey>Filter` | a function-fed list's search and chip (the first chip is left out) | replaces |
 
 ```jsx
 <FactoryBuilder urlKey="form" document={doc} onSave={save} />    // ?formSelected=email&formSteps=stepper:1
@@ -839,7 +1013,7 @@ Buttons, steps and list actions all show hover, a visible press, and a keyboard-
 
 ```sh
 npm install
-npm run dev     # http://localhost:19006 — Screen · List / Edit and Designer · List / Edit for the example employee, records kept in localStorage
+npm run dev     # http://localhost:19006 — Screen · List / Edit / Orders and Designer · List / Edit / Orders / Buttons, records kept in localStorage
 ```
 
 ## Files
@@ -861,13 +1035,15 @@ src/
   useFactoryBuilder.js   ─ builder controller
   useFactoryScreen.js    ─ screen controller
   useFlowBuilder.js      ─ flow designer controller
+  buttons.js             ─ buttons and function-fed lists: conditions, what a press sends, functionProblems' checks (React-free)
+  pagesInventory.js      ─ ui/pages.json: routesIn, pageWarnings, webOnlyMenus (React-free)
   urlState.js            ─ the URL keys and values for selection and steps (React-free)
   useUrlPlaces.js        ─ useUrlSteps, useUrlSelection: those places, in the URL or in memory
   useScreenSource.js     ─ { screens, screenEditor } for @xeplr/ui-workflow's Screen step
-  designs/               ─ BuilderSample, ScreenSample, ScreenEditorSample, ControlView, ListView, Palette, PropertyPanel, styles.js, factory.css
+  designs/               ─ BuilderSample, ScreenSample, ScreenEditorSample, ControlView, ListView, FedList, ButtonsView, Palette, PropertyPanel, styles.js, factory.css
   pages.jsx              ─ FactoryBuilder, FactoryScreen
-bin/xeplr-factory.js     ─ screens / generate / validate / controls / schema
-examples/                ─ employee.entity.json and what `screens` makes of it
+bin/xeplr-factory.js     ─ screens / generate / validate / controls / schema / pages
+examples/                ─ employee.entity.json and what `screens` makes of it; orders-board and order-actions (a function-fed list, buttons)
 dev/                     ─ the stand-in app for `npm run dev` (not published)
 ```
 
@@ -877,8 +1053,17 @@ dev/                     ─ the stand-in app for `npm run dev` (not published)
 npm test
 ```
 
+`test/buttons.test.js` covers buttons and function-fed lists in the document: what the checker refuses, when a button shows or is greyed out, what a press sends (the document's parameters, never the request's), and `functionProblems` against a registry. `test/cli.test.js` includes `pages`.
+
 `test/urlState.test.js` covers the URL state: the key format, and the three controllers reading their places back from a real `MemoryRouter` and being clicked through in memory, rendered with `react-dom/server`.
 
+```sh
+npx playwright install chromium-headless-shell   # once
+npm run test:phone
+```
+
+`test/phone.check.js` opens the dev app (`dev/`) in a real browser at 360, 390 and 430px wide and holds every screen to the phone rules: the page never scrolls sideways; fields are one per row, full width, in reading order, none overlapping; inputs are 16px or larger and 44px tall; the footer's buttons are 44px and on screen; a list's row buttons are on screen without scrolling the table; a popup fills the screen. At 1280px it checks that the designed layout is untouched. On the Orders page it checks the function-fed list and buttons at phone sizes (16px / 44px search, chips on screen, an "ask first" that fills the screen) and, at 1280px, that they work: search and chips narrow the rows and the counts, the hover box lists entries, a row opens, a press with a note changes the order and greys its button out, and Confirm COD gives way to Undo. It is not part of `npm test` — it needs a browser and starts a dev server — so run it before releasing anything that changes how a screen is drawn. The list checks use the `@xeplr/ui-table` installed here.
+
 ## License
 
 MIT

package/bin/xeplr-factory.js

@@ -12,6 +12,7 @@
 //   xeplr-factory validate screen.json                   check a document (exit 1 on problems)
 //   xeplr-factory controls                               the controls and their props
 //   xeplr-factory schema screen.json                     the form's @xeplr/schema-handler schema
+//   xeplr-factory pages [ui dir] [--strict]              warn about pages that are web only, or not listed in pages.json
 //
 // "-" as the file reads stdin.
 
@@ -23,6 +24,7 @@ import { scaffoldEntity } from '../src/scaffold.js'
 import { migrationFor, nextMigrationName } from '../src/tableSchema.js'
 import { validateDocument } from '../src/validateDocument.js'
 import { formSchema } from '../src/values.js'
+import { routesIn, pageWarnings } from '../src/pagesInventory.js'
 
 const USAGE = `usage:
   xeplr-factory screens <entity.json|-> [-o <dir>] [--force] [--no-pages]
@@ -30,7 +32,8 @@ const USAGE = `usage:
   xeplr-factory generate <spec.json|-> [-o <out.json>]
   xeplr-factory validate <screen.json|->
   xeplr-factory controls
-  xeplr-factory schema <screen.json|->`
+  xeplr-factory schema <screen.json|->
+  xeplr-factory pages [<ui dir>] [--strict]`
 
 function readJson(file) {
   const text = readFileSync(file === '-' ? 0 : file, 'utf8')
@@ -167,6 +170,29 @@ switch (cmd) {
     break
   }
 
+  // WEB-ONLY PAGES, SAID OUT LOUD. Reads <ui dir>/pages.json and the routes
+  // files it names; prints a warning per page written by hand for the browser
+  // and per route nobody listed. Warnings only — exit 0 — unless --strict.
+  // Run by an app's pre-commit hook, so a hand-written page is never a secret.
+  case 'pages': {
+    const dir = path.resolve(args.find((a) => !a.startsWith('--')) || '.')
+    const file = path.join(dir, 'pages.json')
+    let inv = null
+    if (existsSync(file)) inv = readJson(file)
+    const routeFiles = (inv && Array.isArray(inv.routes) && inv.routes.length ? inv.routes : ['src/App.jsx']).map((f) => path.join(dir, f))
+    const routes = routeFiles.filter((f) => existsSync(f)).flatMap((f) => routesIn(readFileSync(f, 'utf8')))
+    const warnings = inv
+      ? pageWarnings(inv, routes)
+      : [{ kind: 'inventory', message: `no pages.json in ${dir} — none of its ${routes.length} routes says whether it works outside the browser` }]
+    routeFiles.filter((f) => !existsSync(f)).forEach((f) => warnings.push({ kind: 'inventory', message: `${path.relative(dir, f)} (in pages.json "routes") does not exist` }))
+    if (!warnings.length) { process.stdout.write('pages: every page is listed, none is web only\n'); break }
+    process.stderr.write(warnings.map((w) => `warning: ${w.message}`).join('\n') + '\n')
+    const web = warnings.filter((w) => w.kind === 'webOnly').length
+    process.stderr.write(`pages: ${web} web-only page${web === 1 ? '' : 's'}, ${warnings.length - web} other warning${warnings.length - web === 1 ? '' : 's'}\n`)
+    if (args.includes('--strict')) process.exit(1)
+    break
+  }
+
   default:
     fail(USAGE, cmd ? 2 : 0)
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xeplr/ui-factory",
-  "version": "1.8.2",
+  "version": "1.8.4",
   "description": "Design data-entry screens on @xeplr/ui-canvas, save them as JSON, run them as auto-saving forms with lists of saved records — built for Claude to draft and people to refine",
   "type": "module",
   "main": "src/index.js",
@@ -19,7 +19,8 @@
   ],
   "scripts": {
     "dev": "vite",
-    "test": "for f in test/*.test.js; do node \"$f\" || exit 1; done"
+    "test": "for f in test/*.test.js; do node \"$f\" || exit 1; done",
+    "test:phone": "node test/phone.check.js"
   },
   "keywords": [
     "form-builder",
@@ -49,6 +50,7 @@
     "@xeplr/ui-canvas": "^1.0.2",
     "@xeplr/ui-table": "^1.0.6",
     "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0",
     "react-router-dom": "^6.0.0 || ^7.0.0"
   },
   "devDependencies": {
@@ -56,13 +58,15 @@
     "@vitejs/plugin-react": "^5.2.0",
     "@xeplr/schema-handler": "^1.0.5",
     "@xeplr/ui-canvas": "^1.0.1",
-    "@xeplr/ui-table": "^1.0.6",
+    "@xeplr/ui-table": "^1.1.3",
+    "playwright": "^1.64.1",
     "react": "^19.2.4",
     "react-dom": "^19.2.4",
     "react-router-dom": "^7.18.4",
     "vite": "^7.3.1"
   },
   "dependencies": {
+    "@xeplr/rules": "^1.0.8",
     "@xeplr/ui-utils": "^1.1.2"
   }
 }

package/src/buttons.js

@@ -0,0 +1,142 @@
+// BUTTONS AND FUNCTION-FED LISTS — the parts of a screen that run the app's
+// own code, named in the document and registered on the server.
+//
+// A button is an ACTION NAME PLUS PARAMETERS. Eight status buttons are one
+// registered function, setOrderStatus, and eight buttons that give it a
+// different `status`:
+//
+//   { id: 'packed', label: 'Packed', action: 'setOrderStatus', params: { status: 'packed' },
+//     ask: { title: 'Change status to Packed', note: 'Reason (optional)' },
+//     disabledWhen: [{ field: 'customStatus', op: 'eq', value: 'packed' }] }
+//
+// The function lives in the app, registered with @xeplr/actions and an
+// `event` saying what it is for:
+//
+//   button      a button's press. Its inputSchema says which parameters it
+//               takes — and, with `options`, which values each may have — so
+//               the designer offers them and publishing checks them.
+//   listRows    the rows of a list that are worked out rather than read from
+//               one table: { rows, counts } for a search and a filter chip.
+//   rowDetails  what a list cell's hover box lists for one row.
+//
+// Nothing here runs code. A document holds names and values only, so the same
+// screen can be drawn by anything that reads it, and what a button may do is
+// decided on the server, where nobody can skip it.
+//
+// Conditions — when a button shows, when it is disabled — are @xeplr/rules
+// rules, the same condition language as the rest of xeplr, read from the
+// record the screen is about. Every rule must match.
+
+import { matches, OPERATORS } from '@xeplr/rules'
+
+export const BUTTON_EVENT = 'button'
+export const LIST_ROWS_EVENT = 'listRows'
+export const ROW_DETAILS_EVENT = 'rowDetails'
+
+/** How a button looks: an ordinary one, the main one, or one that undoes or removes. */
+export const BUTTON_VARIANTS = ['default', 'primary', 'danger']
+
+/** What a list column can be drawn as. Every one shows text the server wrote. */
+export const COLUMN_DISPLAYS = ['text', 'images', 'activity']
+
+/** A badge's colour. */
+export const BADGE_TONES = ['accent', 'success', 'warning', 'danger', 'muted']
+
+/** The name a button's note reaches its function under. */
+export const NOTE_INPUT = 'note'
+
+/** Operators a button's condition can use: every one that compares a single value. */
+export const CONDITION_OPERATORS = OPERATORS.filter((o) => !o.needsRows)
+
+/** Whether every rule matches the record. No rules: true. */
+export function conditionMet(rules, record) {
+  if (!Array.isArray(rules) || !rules.length) return true
+  const rec = record || {}
+  return rules.every((r) => matches(r, rec[r.field]))
+}
+
+/** Whether a button shows for this record. */
+export function buttonShown(button, record) {
+  return conditionMet(button && button.when, record)
+}
+
+/** Whether a shown button is greyed out for this record. No disabledWhen: never. */
+export function buttonDisabled(button, record) {
+  const rules = button && button.disabledWhen
+  return Array.isArray(rules) && rules.length > 0 && conditionMet(rules, record)
+}
+
+/** Every button on a screen, with the panel it is on. */
+export function screenButtons(doc) {
+  return ((doc && doc.nodes) || [])
+    .filter((n) => n.type === 'buttons')
+    .flatMap((node) => ((node.props && node.props.buttons) || []).map((button) => ({ node, button })))
+}
+
+/** One button by its id — what a press names. Null when the screen has none of that id. */
+export function buttonById(doc, id) {
+  return screenButtons(doc).find((b) => b.button && b.button.id === id) || null
+}
+
+/** What a press sends the function: the document's parameters, and the person's note when it asks for one. */
+export function buttonInput(button, note) {
+  const input = { ...((button && button.params) || {}) }
+  if (button && button.ask && button.ask.note && note !== undefined && note !== null && String(note).trim() !== '') {
+    input[NOTE_INPUT] = String(note).trim()
+  }
+  return input
+}
+
+/**
+ * The functions a screen's CONTROLS name, as [{ event, name, at }] — a list's
+ * rows, a column's hover box, each button. `at` is where in the document, so
+ * a refusal says which one.
+ */
+export function nodeFunctions(doc) {
+  const out = []
+  ;((doc && doc.nodes) || []).forEach((node, i) => {
+    const p = node.props || {}
+    if (node.type === 'list') {
+      if (typeof p.rowsFrom === 'string' && p.rowsFrom) out.push({ event: LIST_ROWS_EVENT, name: p.rowsFrom, at: `nodes[${i}].props.rowsFrom` })
+      ;(Array.isArray(p.columns) ? p.columns : []).forEach((c, j) => {
+        if (c && typeof c.details === 'string' && c.details) out.push({ event: ROW_DETAILS_EVENT, name: c.details, at: `nodes[${i}].props.columns[${j}].details` })
+      })
+    }
+    if (node.type === 'buttons') {
+      ;(Array.isArray(p.buttons) ? p.buttons : []).forEach((b, j) => {
+        if (b && typeof b.action === 'string' && b.action) out.push({ event: BUTTON_EVENT, name: b.action, at: `nodes[${i}].props.buttons[${j}].action`, button: b })
+      })
+    }
+  })
+  return out
+}
+
+/**
+ * What stops a button's parameters reaching its function: one it does not
+ * take, a required one missing, a value outside its options, a note it has no
+ * input for. Read from the function's inputSchema, as the server lists it.
+ */
+export function paramProblems(button, inputSchema) {
+  const schema = Array.isArray(inputSchema) ? inputSchema : []
+  const byName = new Map(schema.filter((f) => f && f.name).map((f) => [f.name, f]))
+  const params = (button && button.params) || {}
+  const problems = []
+  Object.keys(params).forEach((k) => {
+    const f = byName.get(k)
+    if (!f) { problems.push(`takes no parameter "${k}"${byName.size ? ` — it takes: ${[...byName.keys()].join(', ')}` : ''}`); return }
+    const allowed = optionValues(f.options)
+    if (allowed.length && !allowed.includes(params[k])) problems.push(`"${k}" must be one of: ${allowed.join(', ')}`)
+  })
+  schema.forEach((f) => {
+    if (!f || !f.name || !f.required || f.default !== undefined) return
+    if (f.name === NOTE_INPUT && button && button.ask && button.ask.note) return
+    if (params[f.name] === undefined || params[f.name] === null || params[f.name] === '') problems.push(`needs "${f.name}"`)
+  })
+  if (button && button.ask && button.ask.note && !byName.has(NOTE_INPUT)) problems.push(`asks for a note, but takes no "${NOTE_INPUT}"`)
+  return problems
+}
+
+/** A schema field's allowed values: `options` as plain values or { value, label }. */
+export function optionValues(options) {
+  return (Array.isArray(options) ? options : []).map((o) => (o && typeof o === 'object' && 'value' in o ? o.value : o))
+}

package/src/controls.js

@@ -545,7 +545,10 @@ CONTROLS.list = {
   // PAGE of the app's own (openIn: 'page', which calls onOpenRecord and lets
   // the app navigate). Without one, Edit opens the row in this screen's own
   // fields (a list on a form).
-  props: ['title', 'source', 'belongsTo', 'editScreen', 'openIn', 'columns', 'pageSize', 'actions', 'style'],
+  // rowsFrom: rows a registered function works out (event "listRows") —
+  // with its search box, filter chips and their counts — instead of one
+  // table's records. See buttons.js.
+  props: ['title', 'source', 'belongsTo', 'editScreen', 'openIn', 'columns', 'pageSize', 'actions', 'rowsFrom', 'search', 'filters', 'refreshEvery', 'rowOpen', 'highlight', 'grow', 'style'],
   validation: [],
   styles: ['fontFamily', 'fontSize', 'color', 'background', 'borderColor', 'borderWidth', 'borderRadius'],
   properties: [
@@ -570,6 +573,21 @@ CONTROLS.list = {
         { path: 'props.pageSize', label: 'Rows per page', type: 'number' }
       ]
     },
+    {
+      key: 'rows',
+      title: 'Rows from a function',
+      fields: [
+        { path: 'props.rowsFrom', label: 'Rows from', type: 'function', event: 'listRows',
+          help: 'A function of the app that works the rows out — instead of reading one table. Blank → the table above.' },
+        { path: 'props.search.placeholder', label: 'Search box hint', type: 'text', help: 'Blank → no search box. Needs "Rows from".' },
+        { path: 'props.filters', label: 'Filter chips', type: 'filters', help: 'The first is where the list starts. The function counts each.' },
+        { path: 'props.refreshEvery', label: 'Refresh every (seconds)', type: 'number', help: 'For rows whose text changes with time, like "2h ago". Blank → never.' },
+        { path: 'props.rowOpen', label: 'A click on a row opens it', type: 'toggle' },
+        { path: 'props.highlight', label: 'Mark rows where', type: 'text', help: 'A field of the row; a row where it is true is marked — "isNew".' },
+        { path: 'props.grow', label: 'As tall as its rows', type: 'toggle',
+          help: 'The page grows with the list instead of the list scrolling in its box. Only for a list that is the screen\'s one control.' }
+      ]
+    },
     { key: 'columns', title: 'Columns', fields: [{ path: 'props.columns', label: 'Columns', type: 'columns' }] },
     { key: 'actions', title: 'Actions', fields: [{ path: 'props.actions', label: 'Actions', type: 'actions' }] },
     ...styleGroups(['fontFamily', 'fontSize', 'color', 'background', 'borderColor', 'borderWidth', 'borderRadius'])
@@ -664,6 +682,35 @@ CONTROLS.subform = {
   ]
 }
 
+// A PANEL OF BUTTONS, each the name of a function the app registered (event
+// "button") and the parameters it is given — eight status buttons are one
+// function with eight `status` values. Whether one shows, and whether it is
+// greyed out, are conditions on the record the screen is about. The press
+// runs on the server, which reads the button from the PUBLISHED screen, so
+// nobody can send a function or parameters of their own. See buttons.js.
+CONTROLS.buttons = {
+  type: 'buttons',
+  label: 'Buttons',
+  group: 'Actions',
+  input: false,
+  defaultSize: { w: 0.92, h: 0.07 },
+  defaults: { buttons: [] },
+  props: ['title', 'buttons', 'style'],
+  validation: [],
+  styles: ['fontFamily', 'fontSize', 'color', 'background', 'borderColor', 'borderWidth', 'borderRadius'],
+  properties: [
+    {
+      key: 'buttons',
+      title: 'Buttons',
+      fields: [
+        { path: 'props.title', label: 'Title', type: 'text', help: 'Shown before the buttons. Blank → none' },
+        { path: 'props.buttons', label: 'Buttons', type: 'buttons' }
+      ]
+    },
+    ...styleGroups(['fontFamily', 'fontSize', 'color', 'background', 'borderColor', 'borderWidth', 'borderRadius'])
+  ]
+}
+
 export const LABEL_VARIANTS = ['heading', 'subheading', 'text']
 
 /** The sizes a label preset starts from, in px at the design width. */

package/src/designs/BuilderSample.jsx

@@ -273,6 +273,7 @@ export default function BuilderSample({ ctrl, renderPreview, className, style, s
             selectionCount={ctrl.selected.size}
             errors={ctrl.selectedNode ? ctrl.errorsByNode[ctrl.selectedNode.id] : ctrl.errorsByNode._document}
             tables={ctrl.tables}
+            functions={ctrl.functions}
             screens={ctrl.screens}
             forms={forms}
             lockedNames={ctrl.lockedNames}