@xeplr/ui-factory 1.0.3 → 1.0.5

package/AUTHORING.md

@@ -2,16 +2,42 @@
 
 This guide is for whoever **writes** a screen definition — usually Claude, from a request like *"make a form for a new employee with name, email, department and start date"*. A person then refines the result in the builder.
 
-## The workflow
+> **In an app made by `@xeplr/cli`**, read the project's own `CLAUDE.md` first — it says where each file below goes in that app and how to wire it in. This guide is what the files mean.
+
+## What a new UI is made of
+
+A request for "a form for employees" is an **entity**. Every entity is the same set of files — create all of them, even the ones that only run the defaults:
+
+| file | what | runs |
+|---|---|---|
+| `employee.entity.json` | the spec: name and fields | — |
+| `employee-list.screen.json` | the **list** screen | browser |
+| `employee-edit.screen.json` | the **add / edit form** the list opens in a popup | browser |
+| `EditEmployee.jsx` | the form's page, holding the **front-end hooks** class (`EmployeeHooks extends FactoryHooks`) | browser |
+| `EmployeeList.jsx` | the list's page — uses `EditEmployee.jsx`'s hooks | browser |
+| `employee.hooks.js` | **server hooks**: `save` / `get` / `delete` × `before` / `after` / `error` / `override` | server |
+| `employee.model.js` | **server model**: `EmployeeModel extends FactoryModel` — getters / setters for values | server |
+
+`npx xeplr-factory screens employee.entity.json -o <dir>` writes all of them from the spec (`--no-pages` leaves out the two `.jsx`). The hooks and the model start as defaults — every method calling `super` — and stay that way unless the request needs more.
+
+**Which file for which request:**
 
-A request for "a form for employees" is an **entity**, and an entity is **two screens**: a list, and an add / edit form the list opens in a popup.
+| 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` |
+| "must", "only if", "check against…", "email when…", "only managers see…" | server hooks in `employee.hooks.js` |
+| "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 |
+
+## The workflow
 
 1. **Write an entity spec** — the entity's name and its fields, in reading order. Do not write coordinates.
 2. **Generate** both screens and their pages:
    ```sh
    npx xeplr-factory screens employee.entity.json -o src/screens/employee
    ```
-   This writes `employee-list.screen.json`, `employee-edit.screen.json`, `EmployeeList.jsx`, `EditEmployee.jsx` and an empty `employee.hooks.js`. Wire the two pages into the app's menu next to two `<FactoryBuilder>` pages for designing them (Screen · List, Screen · Edit, Designer · List, Designer · Edit). It refuses to overwrite existing files — they may have been refined in the designer — unless given `--force`.
+   This writes `employee-list.screen.json`, `employee-edit.screen.json`, `EmployeeList.jsx`, `EditEmployee.jsx` (which holds the front-end hooks — see below) and an empty `employee.hooks.js` (the server's). Wire the two pages into the app's menu next to two `<FactoryBuilder>` pages for designing them (Screen · List, Screen · Edit, Designer · List, Designer · Edit). It refuses to overwrite existing files — they may have been refined in the designer — unless given `--force`, which replaces the screen JSON only: the `.jsx` pages and the hooks file are the app's code and are always kept.
 
    A single screen that is not an entity (a settings form, say) uses `npx xeplr-factory generate spec.json -o screen.json` with the screen spec below.
 3. **The table comes from Publish.** Records live in a **real table** — `employees`, one column per field — never in JSON, and there are no migration files to write: **publishing** the edit screen creates its table (`CREATE TABLE`, a column per field, real foreign keys for table dropdowns, the standard `id` / `isActive` / `mtId1–4` / audit columns), and publishing a later version changes it:
@@ -29,8 +55,42 @@ A request for "a form for employees" is an **entity**, and an entity is **two sc
    ```
    Every problem names a path (`nodes[3].props.data.table`) and what belongs there. Fix and re-run until it prints `ok`.
 5. **Save and publish.** Save the screens as drafts, then publish — edit screens of referenced tables first. Publishing changes the table; if it would drop columns it returns them for the person to confirm.
-6. **Hooks, if the request needs them.** Anything beyond storing what the form shows — a value worked out on save, a check against other records, an email afterwards, a list narrowed to the user — goes in `employee.hooks.js`, never in the screen: `save`, `get` (list and one record) and `delete`, each with `before`, `after`, `error` and `override`. Register it with `factory.init({ hooks: { employee_edit: require('./employee.hooks') } })`. `override` replaces the whole operation — rules and the other hooks included — so use it only when the generic save / get / delete does not apply at all. The `screens` command never overwrites an existing hooks file, even with `--force`. Details: the [`@xeplr/factory` README](https://www.npmjs.com/package/@xeplr/factory#hooks).
-7. **Hand over.** The person opens the screens in the designer to move, resize and restyle controls.
+6. **Front-end hooks, if the request needs them in the browser.** `EditEmployee.jsx` holds a class, used by both pages and by the popup:
+
+   ```jsx
+   export class EmployeeHooks extends FactoryHooks {
+     get(ctx) { return super.get(ctx) }                          // a list's rows (ctx.many), or the record Edit opens (ctx.id)
+     save(values, ctx) { return super.save(values, ctx) }        // every autosave; returns the saved record
+     delete(record, ctx) { return super.delete(record, ctx) }    // a list row, after the person confirmed
+     actions(ctx) { return super.actions(ctx) }                  // extra row buttons: [{ label, onClick: (record, ctx) => … }]
+   }
+   ```
+
+   Every method already runs the default. **Change only the method the request is about** and keep calling `super`:
+   - *before* — change the input, then `return super.save(changed, ctx)`
+   - *after* — `const saved = await super.save(values, ctx)`, then use or change it
+   - *override* — do not call `super`
+   - *extra row buttons* — `actions(ctx) { return [{ label: 'Mark done', onClick: async (record) => { …; ctx.refresh() } }] }`
+
+   `ctx.screen` says which screen is calling (`employee_list` or `employee_edit`). Keep them **methods** — `super` does not work in arrow functions. Do not delete the unchanged ones; they show what can be changed.
+
+   Front-end hooks shape what the person sees and sends. **Anything that must hold goes in the server's hooks** (next step). The server keeps only values that are fields of the form: a value added in `save` that is not a field needs a server `save.before` that accepts it.
+7. **Server model, if values need shaping.** `employee.model.js`:
+
+   ```js
+   class EmployeeModel extends FactoryModel {
+     static table = 'employees';
+     static fields = {
+       skills: { set: (v) => (Array.isArray(v) ? v.join(',') : v), get: (v) => (v ? v.split(',') : []) }
+     };
+     static toDb(values) { return super.toDb(values); }     // override for more than one field at a time
+     static fromDb(row) { return super.fromDb(row); }
+   }
+   ```
+
+   Setters run on every write (after `save.before`, before the screen's rules), getters on every read, on the routes and in `factory.table()`. Register it: `factory.init({ knex, hooks, models: [require('./employee.model')] })`.
+8. **Server hooks, if the request needs them.** Anything beyond storing what the form shows — a value worked out on save, a check against other records, an email afterwards, a list narrowed to the user — goes in `employee.hooks.js`, never in the screen: `save`, `get` (list and one record) and `delete`, each with `before`, `after`, `error` and `override`. Register it with `factory.init({ hooks: { employee_edit: require('./employee.hooks') } })`. `override` replaces the whole operation — rules and the other hooks included — so use it only when the generic save / get / delete does not apply at all. The `screens` command never overwrites an existing hooks file, even with `--force`. Details: the [`@xeplr/factory` README](https://www.npmjs.com/package/@xeplr/factory#hooks).
+9. **Hand over.** The person opens the screens in the designer to move, resize and restyle controls.
 
 There is **no submit button** to add: a screen saves itself as it is filled in. If the request mentions seeing or editing what was entered ("…and show the employees below"), add a `list`.
 

package/README.md

@@ -92,6 +92,43 @@ 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"`, and a dropdown as the option's own `id` (a table's numeric id stays a number).
 
+### Front-end hooks
+
+What a screen does in the browser — load, save, delete, extra row buttons — is a class you extend. Every method is the default; override the one you need and call `super`:
+
+```jsx
+import { FactoryScreen, FactoryHooks } from '@xeplr/ui-factory'
+
+class TaskHooks extends FactoryHooks {
+  async save(values, ctx) {
+    const saved = await super.save({ ...values, title: values.title.trim() }, ctx)   // before
+    toast('Saved ' + saved.title)                                                   // after
+    return saved
+  }
+  async get(ctx) {
+    const rows = await super.get(ctx)
+    return ctx.many ? rows.filter((r) => r.status !== 'archived') : rows
+  }
+  actions(ctx) {
+    return [{ label: 'Mark done', onClick: async (record) => { await markDone(record.id); ctx.refresh() } }]
+  }
+}
+
+const taskHooks = new TaskHooks()
+<FactoryScreen document={taskList} {...api} hooks={taskHooks} />
+```
+
+| method | default | ctx |
+|---|---|---|
+| `get(ctx)` | `fetchRecords` for a list, `fetchRecord` for the record Edit opens | `many`, `id`, `screen`, `source` |
+| `save(values, ctx)` | `onSave` — on every autosave; return the saved record | `id`, `isNew`, `screen`, `source` |
+| `delete(record, ctx)` | `onDelete`, after the person confirmed | `id`, `screen`, `source` |
+| `actions(ctx)` | `[]` — extra row buttons `{ label, onClick(record, ctx) }` beside Edit / Delete | `screen`, `refresh()` |
+
+Not calling `super` replaces the default. The same hooks run in the popup a list opens (`ctx.screen` says which screen). Methods, not arrow functions — `super` needs them. `xeplr-factory screens` writes this class, every method calling `super`, into the edit page.
+
+Rules that must hold belong in the server's hooks; the browser only shapes what the person sees and sends.
+
 ### Lists of saved records
 
 A **List** control shows the records of the table the screen saves to (or another), in `@xeplr/ui-table`, with the columns you tick. Its **Edit in** names the edit screen: **Edit** and **New** open that screen in a popup, where it saves itself and the list refreshes behind it. **Delete** removes a row after a confirmation. Dropdown columns show names, not ids — read from the edit screen's fields.

package/bin/xeplr-factory.js

@@ -5,7 +5,7 @@
 // turn a short spec into a laid-out document, and check a document before
 // handing it to an app, with errors precise enough to fix without guessing.
 //
-//   xeplr-factory screens entity.json [-o dir]           an entity → list + edit screens, their .jsx pages, a hooks stub
+//   xeplr-factory screens entity.json [-o dir]           an entity → list + edit screens, their .jsx pages, server hooks + model stubs
 //   xeplr-factory migration edit.screen.json [--from previous.screen.json] [-o migrations/]
 //                                                        the SQL that makes the table match the form
 //   xeplr-factory generate spec.json [-o screen.json]   spec → laid-out document
@@ -25,7 +25,7 @@ import { validateDocument } from '../src/validateDocument.js'
 import { formSchema } from '../src/values.js'
 
 const USAGE = `usage:
-  xeplr-factory screens <entity.json|-> [-o <dir>] [--force]
+  xeplr-factory screens <entity.json|-> [-o <dir>] [--force] [--no-pages]
   xeplr-factory migration <edit.screen.json> [--from <previous.screen.json>] [-o <migrations dir>]
   xeplr-factory generate <spec.json|-> [-o <out.json>]
   xeplr-factory validate <screen.json|->
@@ -81,10 +81,12 @@ switch (cmd) {
     } catch (err) {
       fail(err.message)
     }
-    // The hooks file is the app's own code — kept as it is, even with --force.
-    const hooksFile = Object.keys(result.files).find((f) => f.endsWith('.hooks.js'))
-    const keptHooks = hooksFile && existsSync(path.join(dir, hooksFile)) ? hooksFile : null
-    const writing = Object.keys(result.files).filter((f) => f !== keptHooks)
+    // The app's own code — the server hooks, and the pages with their front-end
+    // hooks — is kept as it is, even with --force. Only the screen JSON is replaced.
+    // --no-pages: only the screens and the server files — for an app whose pages live elsewhere (ui/src/pages).
+    if (args.includes('--no-pages')) Object.keys(result.files).filter((f) => f.endsWith('.jsx')).forEach((f) => delete result.files[f])
+    const kept = Object.keys(result.files).filter((f) => (f.endsWith('.hooks.js') || f.endsWith('.model.js') || f.endsWith('.jsx')) && existsSync(path.join(dir, f)))
+    const writing = Object.keys(result.files).filter((f) => !kept.includes(f))
     const targets = writing.map((f) => path.join(dir, f))
     // Never overwrite a screen someone has since refined in the designer.
     const existing = targets.filter((t) => existsSync(t))
@@ -92,7 +94,7 @@ switch (cmd) {
     mkdirSync(dir, { recursive: true })
     writing.forEach((f) => writeFileSync(path.join(dir, f), result.files[f]))
     process.stderr.write(`wrote ${targets.join(', ')}\n`)
-    if (keptHooks) process.stderr.write(`kept ${path.join(dir, keptHooks)} — it is your code\n`)
+    if (kept.length) process.stderr.write(`kept ${kept.map((f) => path.join(dir, f)).join(', ')} — your code\n`)
     process.stderr.write(`list screen "${result.list.id}" opens "${result.edit.id}" for Edit / New; both use table "${result.edit.source}"\n`)
     break
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xeplr/ui-factory",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "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",

package/src/designs/ListView.jsx

@@ -9,7 +9,7 @@ import { boxStyle, fieldStyle } from './styles.js'
 // Edit and New open the list's edit screen in a popup (`editScreen`), or, for a
 // list on a form, load the row into the form's own fields. Delete removes it.
 
-export default function ListView({ node, doc, design, list, onEdit, onDelete, onNew, currentId, recordKey = 'id', canDelete, fieldNodes, optionsFor }) {
+export default function ListView({ node, doc, design, list, onEdit, onDelete, onNew, currentId, recordKey = 'id', canDelete, fieldNodes, optionsFor, extraActions = [] }) {
   const p = node.props || {}
   const columns = listColumns(doc, node)
   const actions = p.actions || ['new', 'edit', 'delete']
@@ -68,6 +68,11 @@ export default function ListView({ node, doc, design, list, onEdit, onDelete, on
     })
   }
 
+  // The app's own buttons (hooks.actions), after the built-in ones.
+  extraActions.forEach((a, i) => {
+    rowActions.push({ key: 'extra-' + i + '-' + a.label, label: a.label, variant: a.variant, onClick: (row) => a.onClick(row.__record) })
+  })
+
   return (
     <div className="xeplr-factory-list" style={style}>
       <div className="xeplr-factory-list-head">

package/src/designs/ScreenSample.jsx

@@ -88,6 +88,7 @@ export default function ScreenSample({ ctrl, className, style, renderPopup }) {
                 currentId: ctrl.recordId,
                 recordKey: ctrl.recordKey,
                 canDelete: ctrl.canDelete,
+                extraActions: ctrl.actionsFor ? ctrl.actionsFor(node) : [],
                 // A list with an edit screen opens it in a popup; one on a form
                 // opens the row in the form's own fields.
                 onEdit: (rec) => (node.props.editScreen ? ctrl.openEditor(node, rec) : ctrl.openRecord(rec)),

package/src/designs/factory.css

@@ -50,8 +50,11 @@
 .xeplr-factory-required { color: var(--xf-danger); }
 .xeplr-factory-input {
   flex: 1; min-height: 0; width: 100%; box-sizing: border-box;
-  font: inherit; color: var(--xf-ink); background: var(--xeplr-input-bg, var(--xf-surface));
-  border: 1px solid var(--xeplr-input-border, var(--xf-border)); border-radius: calc(6 * var(--xf-u));
+  /* The screen's own colours, never the host theme's input tokens: a dark theme
+     would give the box a dark background while the text stays the screen's
+     dark ink — unreadable. A screen's look is its style properties. */
+  font: inherit; color: var(--xf-ink); background: var(--xf-surface);
+  border: 1px solid var(--xf-border); border-radius: calc(6 * var(--xf-u));
   padding: 0 calc(10 * var(--xf-u));
 }
 .xeplr-factory-textarea { padding-block: calc(8 * var(--xf-u)); resize: none; }
@@ -89,7 +92,7 @@
 .xeplr-factory-list-mock { width: 100%; border-collapse: collapse; }
 .xeplr-factory-list-mock th { text-align: left; font-weight: 600; font-size: .9em; padding: calc(6 * var(--xf-u)) calc(10 * var(--xf-u)); border-bottom: 1px solid var(--xf-border); color: var(--xf-muted); }
 .xeplr-factory-list-mock td { padding: calc(8 * var(--xf-u)) calc(10 * var(--xf-u)); border-bottom: 1px solid var(--xf-border); }
-.xeplr-factory-list-bar { display: block; height: calc(8 * var(--xf-u)); width: 70%; border-radius: 4px; background: var(--xeplr-border-secondary, #ecebe4); }
+.xeplr-factory-list-bar { display: block; height: calc(8 * var(--xf-u)); width: 70%; border-radius: 4px; background: #ecebe4; }
 .xeplr-factory-list .xeplr-table-row.xeplr-factory-row-open td,
 .xeplr-factory-list tr.xeplr-factory-row-open td { background: color-mix(in srgb, var(--xf-accent) 10%, transparent); }
 
@@ -177,8 +180,8 @@
 .xeplr-factory-prop { margin-bottom: 10px; }
 .xeplr-factory-prop-label { display: block; margin-bottom: 3px; font-weight: 600; font-size: 12px; }
 .xeplr-factory-prop-input {
-  width: 100%; box-sizing: border-box; font: inherit; padding: 5px 7px; color: inherit;
-  border: 1px solid var(--xf-border); border-radius: 5px; background: var(--xeplr-input-bg, #fff);
+  width: 100%; box-sizing: border-box; font: inherit; padding: 5px 7px;
+  border: 1px solid var(--xf-border); border-radius: 5px; background: #fff; color: var(--xf-ink, #1a1a19);
 }
 .xeplr-factory-prop.has-error .xeplr-factory-prop-input { border-color: var(--xf-danger); }
 .xeplr-factory-prop-help { margin-top: 3px; color: var(--xf-muted); font-size: 11px; line-height: 1.4; }

package/src/generate.js

@@ -263,7 +263,9 @@ export function entityNames(entity, plural) {
     file: lower(words).join('-'),                         // "employee"  → employee-list.screen.json
     table: lower(pluralWords).join('_'),                  // "employees"
     listComponent: `${pascal(words)}List`,                // "EmployeeList"
-    editComponent: `Edit${pascal(words)}`                 // "EditEmployee"
+    editComponent: `Edit${pascal(words)}`,                // "EditEmployee"
+    hooksClass: `${pascal(words)}Hooks`,                  // "EmployeeHooks" — in EditEmployee.jsx
+    hooksInstance: `${lowerFirst(pascal(words))}Hooks`    // "employeeHooks"
   }
 }
 
@@ -273,6 +275,10 @@ function pluralise(word) {
   return word + 's'
 }
 
+function lowerFirst(s) {
+  return s.charAt(0).toLowerCase() + s.slice(1)
+}
+
 function capitalise(s) {
   return s.charAt(0).toUpperCase() + s.slice(1)
 }

package/src/hooks.js

@@ -0,0 +1,69 @@
+// FRONT-END HOOKS — the app's own code around what a screen does in the
+// browser: load its rows, save, delete, and extra buttons on a list's rows.
+//
+// Every method here IS the default. Extend the class, override only what you
+// need, and call super to run the default where you want it:
+//
+//   class TaskHooks extends FactoryHooks {
+//     async save(values, ctx) {
+//       values = { ...values, priority: values.priority || 'normal' }   // before
+//       const saved = await super.save(values, ctx)                     // the default save
+//       notify('Saved ' + saved.title)                                  // after
+//       return saved
+//     }
+//   }
+//   <FactoryScreen document={taskList} hooks={new TaskHooks()} />
+//
+//   before    change the input, then call super
+//   after     call super, then use or change what it returns
+//   override  do not call super
+//   error     try { return await super.save(values, ctx) } catch (err) { … }
+//
+// Write hooks as METHODS (save(values, ctx) { … }), not as arrow-function
+// properties (save = () => …) — super only works in methods.
+//
+// The same hooks run in the popup a list opens for Edit / New. ctx.screen says
+// which screen is calling ("task_list", "task_edit").
+//
+// The browser is not a security boundary: anything that must hold (a price, a
+// permission) belongs in the server's hooks. And the server keeps only values
+// that are fields of the form — a value added here that is not one needs a
+// server save.before that accepts it.
+
+export class FactoryHooks {
+  /**
+   * The rows of a list (ctx.many), or one record when Edit opens it (ctx.id).
+   * @returns rows | record
+   */
+  get(ctx) {
+    return ctx.defaults.get()
+  }
+
+  /**
+   * Save — called on every autosave, so keep it quick and safe to repeat.
+   * @param values  what the form holds
+   * @returns the saved record (its id makes the next save an update)
+   */
+  save(values, ctx) {
+    return ctx.defaults.save(values)
+  }
+
+  /** Delete a row of a list — after the person confirmed. */
+  delete(record, ctx) {
+    return ctx.defaults.delete(record)
+  }
+
+  /**
+   * Extra buttons on each row, beside Edit and Delete:
+   *   [{ label: 'Mark done', onClick: (record, ctx) => … }]
+   * ctx.refresh() reloads the list.
+   */
+  actions(ctx) {
+    return []
+  }
+}
+
+/** A method of the given hooks, or the default when they do not have it — so a plain object with only save() works too. */
+export function hookMethod(hooks, name) {
+  return hooks && typeof hooks[name] === 'function' ? hooks[name].bind(hooks) : FactoryHooks.prototype[name]
+}

package/src/index.js

@@ -15,5 +15,8 @@ export { useFactoryScreen, normaliseOptions, AUTOSAVE_DELAY } from './useFactory
 // Designs
 export { BuilderSample, ScreenSample, ListView, ScreenModal, ControlView, VIEWS, Palette, DRAG_TYPE, PropertyPanel, EDITORS } from './designs/index.js'
 
+// Front-end hooks — extend FactoryHooks, override what you need, call super
+export { FactoryHooks } from './hooks.js'
+
 // Ready-made
 export { FactoryBuilder, FactoryScreen } from './pages.jsx'

package/src/pages.jsx

@@ -53,6 +53,7 @@ export function FactoryBuilder(props) {
  * @prop screens      { id → document } — the screens a list's Edit / New open in a popup
  * @prop loadScreen   async (id) → document — for screens not in `screens`
  * @prop controls     control registry (default: built-ins)
+ * @prop hooks        your FactoryHooks subclass (get / save / delete / actions) — also used by the popup
  */
 export function FactoryScreen(props) {
   const ctrl = useFactoryScreen(props)
@@ -85,6 +86,7 @@ export function FactoryScreen(props) {
               screens={props.screens}
               loadScreen={props.loadScreen}
               controls={props.controls}
+              hooks={props.hooks}
             />
           )}
         </ScreenModal>

package/src/remote.js

@@ -16,27 +16,44 @@
 export function createFactoryApi({ fetch: doFetch, base = '' } = {}) {
   if (typeof doFetch !== 'function') throw new Error('createFactoryApi: pass { fetch } — usually authFetch from @xeplr/ui-account')
 
+  // Two kinds of fetch are accepted, because both are what apps have:
+  //   window.fetch-like  → a Response: read it, and throw on !res.ok
+  //   authFetch-like     → the PARSED body, and on failure it throws an Error
+  //                        carrying status and the body (err.status, err.body)
+  // Either way a failure becomes the same Error, with the server's fields,
+  // confirm and refused lists on it.
   async function call(method, path, body) {
-    const res = await doFetch(`${base}/factory${path}`, {
-      method,
-      headers: body === undefined ? undefined : { 'Content-Type': 'application/json' },
-      body: body === undefined ? undefined : JSON.stringify(body)
-    })
-    let json = null
-    try { json = await res.json() } catch (_) { /* not JSON — reported below */ }
-    if (!res.ok) {
-      const err = new Error((json && json.message) || `${method} ${path} failed (${res.status})`)
-      err.status = res.status
-      err.fields = json && json.error && json.error.fields
-      const extra = (json && json.dataArray && json.dataArray[0]) || {}
-      // Publish: columns it would drop, waiting for a yes — and what it keeps.
-      err.confirm = extra.confirm
-      err.keep = extra.keep
-      err.refused = extra.refused
-      if (extra.statements) err.detail = extra.statements.join('\n')
+    let res
+    try {
+      res = await doFetch(`${base}/factory${path}`, {
+        method,
+        headers: body === undefined ? undefined : { 'Content-Type': 'application/json' },
+        body: body === undefined ? undefined : JSON.stringify(body)
+      })
+    } catch (err) {
+      if (err && err.body !== undefined && err.status) throw failure(method, path, err.status, err.body, err.message)
       throw err
     }
-    return json ? json.dataArray : []
+    if (res && typeof res.json === 'function' && typeof res.ok === 'boolean') {
+      let json = null
+      try { json = await res.json() } catch (_) { /* not JSON — reported below */ }
+      if (!res.ok) throw failure(method, path, res.status, json)
+      return json ? json.dataArray : []
+    }
+    return res && Array.isArray(res.dataArray) ? res.dataArray : []
+  }
+
+  function failure(method, path, status, json, fallback) {
+    const err = new Error((json && json.message) || fallback || `${method} ${path} failed (${status})`)
+    err.status = status
+    err.fields = json && json.error && json.error.fields
+    const extra = (json && json.dataArray && json.dataArray[0]) || {}
+    // Publish: columns it would drop, waiting for a yes — and what it keeps.
+    err.confirm = extra.confirm
+    err.keep = extra.keep
+    err.refused = extra.refused
+    if (extra.statements) err.detail = extra.statements.join('\n')
+    return err
   }
   const one = (rows) => (Array.isArray(rows) ? rows[0] : rows)
   const enc = encodeURIComponent
@@ -51,6 +68,8 @@ export function createFactoryApi({ fetch: doFetch, base = '' } = {}) {
     // when a removed field would drop a column; call again with { confirmDrop: [names] }.
     publish: async (doc, options) => one(await call('POST', `/screens/${enc(doc.id)}/publish`, { confirmDrop: (options && options.confirmDrop) || [] })),
     listTables: () => call('GET', '/tables'),
+    // A new form from its name: { entity, plural? } → { entity, name, source, edit, list } — both screens as drafts.
+    createEntity: async (spec) => one(await call('POST', '/entities', spec)),
 
     // records
     fetchRecords: ({ screen }) => call('GET', `/records/${enc(screen)}`),

package/src/scaffold.js

@@ -6,6 +6,7 @@
 //   employee-list.screen.json   EmployeeList.jsx   — the list; Edit / New open a popup
 //   employee-edit.screen.json   EditEmployee.jsx   — the add / edit form, also a page on its own
 //   employee.hooks.js                              — the server's hooks for its records (all empty)
+//   employee.model.js                              — the server's model: getters / setters for its values (none yet)
 //
 // The pages are thin on purpose: a screen document and the app's data calls,
 // nothing else. Changing what a screen shows is editing its JSON in the
@@ -30,7 +31,8 @@ export function scaffoldEntity(spec, controls) {
     [editJson]: JSON.stringify(edit, null, 2) + '\n',
     [`${names.listComponent}.jsx`]: listPage(names, listJson, editJson, list, edit),
     [`${names.editComponent}.jsx`]: editPage(names, editJson, edit),
-    [`${names.file}.hooks.js`]: hooksFile(names, edit)
+    [`${names.file}.hooks.js`]: hooksFile(names, edit),
+    [`${names.file}.model.js`]: modelFile(names, edit)
   }
   return { files, names, list, edit }
 }
@@ -39,6 +41,7 @@ function listPage(n, listJson, editJson, list, edit) {
   return `import { FactoryScreen } from '@xeplr/ui-factory'
 import listScreen from './${listJson}'
 import editScreen from './${editJson}'
+import { ${n.hooksInstance} } from './${n.editComponent}.jsx'
 
 // ${n.pluralTitle} — the saved ${list.source}, with New / Edit / Delete.
 // Edit and New open "${edit.name}" (${edit.id}) in a popup.
@@ -48,12 +51,15 @@ import editScreen from './${editJson}'
 //   fetchRecords({ source })        → records
 //   onDelete({ id, source, record })
 //   fetchOptions({ table })         → [{ id, name }] for dropdowns
+//
+// Its hooks are ${n.editComponent}.jsx's — the same ones run in the popup.
 export default function ${n.listComponent}({ api }) {
   return (
     <FactoryScreen
       document={listScreen}
       screens={{ [editScreen.id]: editScreen }}
       {...api}
+      hooks={${n.hooksInstance}}
     />
   )
 }
@@ -101,16 +107,85 @@ module.exports = {
 `
 }
 
+function modelFile(n, edit) {
+  return `// The model for ${n.singular} records — how values are shaped between your code and
+// the "${edit.source}" table, like Sequelize's getters and setters.
+//
+// Register with @xeplr/factory:  factory.init({ knex, hooks, models: [require('./${n.file}.model')] })
+//
+// Used everywhere: the screens' routes and factory.table('${edit.source}'). Models shape
+// data; the hooks file decides behaviour.
+
+var { FactoryModel } = require('@xeplr/factory');
+
+class ${n.hooksClass.replace(/Hooks$/, 'Model')} extends FactoryModel {
+  static table = '${edit.source}';
+
+  // Per field: set(value, values) before it is written, get(value, row) after it is read.
+  //   tags: { set: (v) => (Array.isArray(v) ? v.join(',') : v), get: (v) => (v ? v.split(',') : []) }
+  static fields = {};
+
+  /** Every value about to be written. Override for more than one field at a time. */
+  static toDb(values) {
+    return super.toDb(values);
+  }
+
+  /** Every row just read. */
+  static fromDb(row) {
+    return super.fromDb(row);
+  }
+}
+
+module.exports = ${n.hooksClass.replace(/Hooks$/, 'Model')};
+`
+}
+
 function editPage(n, editJson, edit) {
-  return `import { FactoryScreen } from '@xeplr/ui-factory'
+  return `import { FactoryScreen, FactoryHooks } from '@xeplr/ui-factory'
 import editScreen from './${editJson}'
 
 // ${edit.name} — saves itself as it is filled in; there is no submit.
 // Opened in a popup from ${n.listComponent}, or on its own page:
 //   <${n.editComponent} api={api} />                 a new ${n.singular}
 //   <${n.editComponent} api={api} record={row} />    an existing one
+
+// ── WHAT THE SCREENS DO IN THE BROWSER ──────────────────────────────────
+// Every method runs the default (super). Change the ones you need; leave the
+// rest as they are. Used by this page, by ${n.listComponent} and by its popup.
+//
+//   before    change the input, then call super
+//   after     call super, then use or change what it returns
+//   override  do not call super
+//
+// ctx.screen says which screen is calling ("${n.key}_list" or "${edit.id}").
+// Keep them as methods (save(values, ctx) { … }) — super does not work in
+// arrow functions. Rules that must hold belong in the server's hooks.
+export class ${n.hooksClass} extends FactoryHooks {
+  /** A list's rows (ctx.many), or the record Edit opens (ctx.id). */
+  get(ctx) {
+    return super.get(ctx)
+  }
+
+  /** Every autosave — keep it quick. Returns the saved record. */
+  save(values, ctx) {
+    return super.save(values, ctx)
+  }
+
+  /** A list row, after the person confirmed. */
+  delete(record, ctx) {
+    return super.delete(record, ctx)
+  }
+
+  /** Extra row buttons beside Edit / Delete: [{ label, onClick: (record, ctx) => … }]. ctx.refresh() reloads. */
+  actions(ctx) {
+    return super.actions(ctx)
+  }
+}
+
+export const ${n.hooksInstance} = new ${n.hooksClass}()
+
 export default function ${n.editComponent}({ api, record }) {
-  return <FactoryScreen document={editScreen} record={record} {...api} />
+  return <FactoryScreen document={editScreen} record={record} {...api} hooks={${n.hooksInstance}} />
 }
 `
 }

package/src/useFactoryScreen.js

@@ -3,6 +3,7 @@ import { CONTROLS } from './controls.js'
 import { inputNodes } from './document.js'
 import { validateDocument } from './validateDocument.js'
 import { initialValues, parseInput, saveState, fieldError, optionValue, recordValues, listSource } from './values.js'
+import { hookMethod } from './hooks.js'
 
 // A saved screen, running. No JSX — designs/ScreenSample.jsx draws it.
 //
@@ -41,23 +42,48 @@ export const AUTOSAVE_DELAY = 700
  * @param loadScreen    async (id) → document — for screens not in `screens`
  * @param autosaveDelay ms (default 700)
  * @param controls      the control registry (default: the built-ins)
+ * @param hooks         a FactoryHooks (or an object with some of its methods) — get / save / delete / actions
  */
 export function useFactoryScreen({
-  document: doc, record, recordKey = 'id', onSave, fetchOptions, fetchRecords, fetchRecord, onDelete, onChange, screens, loadScreen,
+  document: doc, record, recordKey = 'id', onSave, fetchOptions, fetchRecords, fetchRecord, onDelete, onChange, screens, loadScreen, hooks,
   autosaveDelay = AUTOSAVE_DELAY, controls = CONTROLS
 } = {}) {
   const check = useMemo(() => validateDocument(doc, controls), [doc, controls])
+  // Read at call time, so a new hooks object never re-runs loads by itself.
+  const hooksRef = useRef(hooks); hooksRef.current = hooks
+  const hook = (name) => hookMethod(hooksRef.current, name)
   const inputs = useMemo(() => (check.ok ? inputNodes(doc, controls) : []), [doc, controls, check.ok])
 
   // A LIST SCREEN has no fields of its own; what its columns mean — that
   // `department` is a dropdown whose 2 reads "Finance" — lives on the screen it
   // edits in. Those fields are borrowed for display, and their table options
   // loaded alongside this screen's own.
+  //
+  // An edit screen not passed in `screens` is fetched with loadScreen as soon
+  // as the list shows — not when Edit is first pressed — or the list's columns
+  // would show stored values ("in_progress") until then.
+  const [loadedScreens, setLoadedScreens] = useState({})
+  const knownScreens = useMemo(() => ({ ...loadedScreens, ...(screens || {}) }), [loadedScreens, screens])
+  const editScreenIds = check.ok && !inputs.length
+    ? [...new Set(doc.nodes.filter((n) => n.type === 'list' && n.props.editScreen).map((n) => n.props.editScreen))].join('|')
+    : ''
+  useEffect(() => {
+    if (!editScreenIds || !loadScreen) return undefined
+    let cancelled = false
+    editScreenIds.split('|').filter((id) => !(screens && screens[id])).forEach((id) => {
+      loadScreen(id).then(
+        (found) => { if (!cancelled && found) setLoadedScreens((m) => (m[id] ? m : { ...m, [id]: found })) },
+        () => { /* shown when Edit is pressed, where the person is looking */ }
+      )
+    })
+    return () => { cancelled = true }
+  }, [editScreenIds])                                          // eslint-disable-line react-hooks/exhaustive-deps
+
   const fieldsFor = useCallback((node) => {
     if (inputs.length || !node || !node.props.editScreen) return inputs
-    const editDoc = screens && screens[node.props.editScreen]
+    const editDoc = knownScreens[node.props.editScreen]
     return editDoc && validateDocument(editDoc, controls).ok ? inputNodes(editDoc, controls) : []
-  }, [inputs, screens, controls])
+  }, [inputs, knownScreens, controls])
   const optionNodes = useMemo(() => {
     if (!check.ok) return []
     const borrowed = doc.nodes.filter((n) => n.type === 'list').flatMap((n) => (inputs.length ? [] : fieldsFor(n)))
@@ -142,13 +168,19 @@ export function useFactoryScreen({
     const l = live.current
     const st = saveState(l.doc, l.values, l.touched, l.loadedItems, l.controls)
     if (!st.canSave) { setStatus(st.status); return { ok: false, errors: st.errors } }
-    if (!l.onSave) { setStatus('saved'); return { ok: true } }
+    const customSave = hooksRef.current && typeof hooksRef.current.save === 'function'
+    if (!l.onSave && !customSave) { setStatus('saved'); return { ok: true } }
 
     setStatus('saving')
     setSaveError(null)
     const task = (async () => {
       try {
-        const saved = await l.onSave(l.values, { id: l.recordId, source: l.source, screen: l.doc.id, document: l.doc })
+        const meta = { id: l.recordId, source: l.source, screen: l.doc.id, document: l.doc }
+        const saved = await hook('save')(l.values, {
+          ...meta,
+          isNew: l.recordId === null || l.recordId === undefined,
+          defaults: { save: (vals) => (l.onSave ? l.onSave(vals, meta) : undefined) }
+        })
         // A new record's first save creates it; its id makes the next save an update.
         if (saved && typeof saved === 'object' && saved[l.recordKey] !== undefined && saved[l.recordKey] !== null) {
           setRecordId(saved[l.recordKey])
@@ -263,9 +295,15 @@ export function useFactoryScreen({
     listNodes.forEach((node) => {
       const src = listSource(doc, node)
       setLists((l) => ({ ...l, [node.id]: { rows: l[node.id]?.rows || [], loading: true, error: null } }))
-      const run = fetchRecordsRef.current
-        ? Promise.resolve().then(() => fetchRecordsRef.current({ source: src, screen: doc.id, node }))
-        : Promise.reject(new Error(`No fetchRecords was provided to list "${src}"`))
+      const run = Promise.resolve().then(() => hook('get')({
+        many: true, id: null, screen: doc.id, source: src, node, document: doc,
+        defaults: {
+          get: () => {
+            if (!fetchRecordsRef.current) throw new Error(`No fetchRecords was provided to list "${src}"`)
+            return fetchRecordsRef.current({ source: src, screen: doc.id, node })
+          }
+        }
+      }))
       run
         .then((rows) => { if (!cancelled) setLists((l) => ({ ...l, [node.id]: { rows: Array.isArray(rows) ? rows : [], loading: false, error: null } })) })
         .catch((err) => { if (!cancelled) setLists((l) => ({ ...l, [node.id]: { rows: l[node.id]?.rows || [], loading: false, error: err.message || 'Could not load records' } })) })
@@ -275,11 +313,33 @@ export function useFactoryScreen({
 
   const listFor = useCallback((node) => lists[node.id] || { rows: [], loading: false, error: null }, [lists])
 
+  /** Extra row buttons from hooks.actions — each onClick gets the row's record. */
+  const actionsFor = useCallback((node) => {
+    const ctx = { screen: doc.id, source: listSource(doc, node), node, document: doc, refresh: () => setListVersion((v) => v + 1) }
+    let extra
+    try { extra = hook('actions')(ctx) } catch (err) { console.error('[factory] hooks.actions failed:', err); extra = [] }
+    return (Array.isArray(extra) ? extra : []).filter((a) => a && a.label && typeof a.onClick === 'function').map((a) => ({
+      ...a,
+      onClick: (rec) => Promise.resolve().then(() => a.onClick(rec, ctx)).catch((err) => {
+        console.error('[factory] action "' + a.label + '" failed:', err)
+        // eslint-disable-next-line no-alert
+        if (typeof window !== 'undefined') window.alert(err.message || 'Could not ' + a.label)
+      })
+    }))
+  }, [doc, lists])                                              // eslint-disable-line react-hooks/exhaustive-deps
+
   const onDeleteRef = useRef(onDelete); onDeleteRef.current = onDelete
   const deleteRecord = useCallback(async (node, rec) => {
     const id = rec ? rec[recordKey] : undefined
-    if (!onDeleteRef.current) throw new Error('No onDelete was provided')
-    await onDeleteRef.current({ id, source: listSource(doc, node), screen: doc.id, record: rec })
+    await hook('delete')(rec, {
+      id, source: listSource(doc, node), screen: doc.id, node, document: doc,
+      defaults: {
+        delete: (r) => {
+          if (!onDeleteRef.current) throw new Error('No onDelete was provided')
+          return onDeleteRef.current({ id: r ? r[recordKey] : id, source: listSource(doc, node), screen: doc.id, record: r })
+        }
+      }
+    })
     // Deleting the record that is open leaves nothing to save into.
     if (id !== undefined && id === live.current.recordId) {
       clearTimeout(timer.current); timer.current = null
@@ -290,7 +350,7 @@ export function useFactoryScreen({
 
   // ── popup: a list's Edit / New in its edit screen ─────────────────────
   const [popup, setPopup] = useState(null)   // { node, screenId, record, document, loading, error }
-  const screensRef = useRef(screens); screensRef.current = screens
+  const screensRef = useRef(knownScreens); screensRef.current = knownScreens
   const fetchRecordRef = useRef(fetchRecord); fetchRecordRef.current = fetchRecord
   const loadScreenRef = useRef(loadScreen); loadScreenRef.current = loadScreen
 
@@ -308,8 +368,12 @@ export function useFactoryScreen({
       // Edit opens the record as it is NOW, through the server's get hooks —
       // not the list's copy, which may be stale or shaped for the list.
       let fresh = rec || null
-      if (rec && fetchRecordRef.current && rec[live.current.recordKey] !== undefined) {
-        fresh = await fetchRecordRef.current({ screen: screenId, id: rec[live.current.recordKey] })
+      if (rec && rec[live.current.recordKey] !== undefined) {
+        const id = rec[live.current.recordKey]
+        fresh = await hook('get')({
+          many: false, id, screen: screenId, document: found,
+          defaults: { get: () => (fetchRecordRef.current ? fetchRecordRef.current({ screen: screenId, id }) : rec) }
+        })
       }
       setPopup((p) => (p && p.screenId === screenId ? { ...p, document: found, record: fresh, loading: false } : p))
     } catch (err) {
@@ -355,7 +419,9 @@ export function useFactoryScreen({
     listFor,
     deleteRecord,
     recordKey,
-    canDelete: Boolean(onDelete)
+    canDelete: Boolean(onDelete) || Boolean(hooks && typeof hooks.delete === 'function'),
+    actionsFor,
+    hooks
   }
 }