@xeplr/ui-factory 1.7.0 → 1.7.2

package/AUTHORING.md

@@ -15,7 +15,7 @@ A request for "a form for employees" is an **entity**. Every entity is the same
 | `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.functions.js` | **server functions**, registered with `@xeplr/actions` by event (`beforeLoad`, `beforeSave`, `afterSave`, `beforeDelete`, `onError`) and named in the screen's `events` | 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.
@@ -26,7 +26,7 @@ A request for "a form for employees" is an **entity**. Every entity is the same
 |---|---|
 | 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` |
+| "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 |
 
@@ -37,7 +37,7 @@ A request for "a form for employees" is an **entity**. Every entity is the same
    ```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` (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.
+   This writes `employee-list.screen.json`, `employee-edit.screen.json`, `EmployeeList.jsx`, `EditEmployee.jsx` (which holds the front-end hooks — see below) and `employee.functions.js` (the server's functions, none registered yet). 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, the functions and the model 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:
@@ -89,7 +89,7 @@ A request for "a form for employees" is an **entity**. Every entity is the same
    ```
 
    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).
+8. **Server functions, 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 — is a function in `employee.functions.js`, never in the screen: `register({ name, event, description, execute })` with `@xeplr/actions`, then name it in `employee-edit.screen.json`'s `events` (`{ "beforeSave": "employeeBeforeSave" }`). Register before naming — a screen naming a function nobody registered is refused at publish. The app loads the file from its `functions/index.js`. The `screens` command never overwrites an existing functions file, even with `--force`. Details: the [`@xeplr/factory` README](https://www.npmjs.com/package/@xeplr/factory#events--the-apps-code-picked-by-name-in-the-screen).
 9. **Hand over.** The person opens the screens in the designer to move, resize and restyle controls.
 
 Do **not** add a button control for saving: every screen's footer already has **Save** (an AJAX call — never a form submit) and **Cancel** where it can go back. If the request mentions seeing or editing what was entered ("…and show the employees below"), add a `list`.

package/README.md

@@ -17,13 +17,13 @@ It is built to work with Claude: ask for *"a form for employees with name, email
 npx xeplr-factory screens employee.entity.json -o src/screens/employee
 #  employee-list.screen.json   EmployeeList.jsx     the list page — uses EditEmployee.jsx's hooks
 #  employee-edit.screen.json   EditEmployee.jsx     the form page, holding the FRONT-END hooks (EmployeeHooks extends FactoryHooks)
-#  employee.hooks.js           SERVER hooks: save / get / delete × before / after / error / override
+#  employee.functions.js       SERVER functions, registered by event, named in the screen's events
 #  employee.model.js           SERVER model: EmployeeModel extends FactoryModel — getters / setters for values
 ```
 
 `--no-pages` leaves out the two `.jsx` (for an app whose pages live elsewhere). `--force` replaces only the screen JSON: the pages, hooks and model are your code and are always kept.
 
-**Rules:** records live in real tables, never JSON · a form's **key** (`employee`) names its screens and table and never changes once published; its **label** (the screens' name) is renamed any time · rules that must hold go in server hooks, never front-end hooks.
+**Rules:** records live in real tables, never JSON · a form's **key** (`employee`) names its screens and table and never changes once published; its **label** (the screens' name) is renamed any time · rules that must hold go in server functions (named in the screen's `events`), never front-end hooks.
 
 See [examples/](./examples) for exactly what it writes.
 
@@ -382,6 +382,13 @@ const flows = createFlowsApi({ fetch: authFetch, base: '/api/workflow' })
 - Approvals (another person's turn, with an assignee and a timeout) are not
   part of this designer.
 
+An app page needs only its two API clients — the flow and the forms are
+loaded for it:
+
+```jsx
+<FlowDesignerPage factory={factory} flows={flows} flowKey={key} urlKey="flow" />
+```
+
 Controllers, for a design of your own: `useFlowBuilder` (the flow, plus
 `navigationOf` / `setNavigation`), `useScreenEvents` (one screen's events,
 `adopt` to share its draft with a builder), `useFunctionCatalog` (the app's
@@ -724,7 +731,7 @@ const screen = screenFromSpec({
 It lays the fields out as a tidy one- or two-column form and returns a checked document. The same is available on the command line:
 
 ```sh
-npx xeplr-factory screens entity.json -o dir   # an entity → list + edit screens, pages, server hooks + model  (--no-pages, --force)
+npx xeplr-factory screens entity.json -o dir   # an entity → list + edit screens, pages, server functions + model  (--no-pages, --force)
 npx xeplr-factory migration edit.screen.json   # preview the SQL Publish would run
 npx xeplr-factory generate spec.json -o screen.json   # one screen from a spec
 npx xeplr-factory validate screen.json      # every problem, with its path
@@ -800,7 +807,7 @@ src/
   validateDocument.js    ─ the document checker
   values.js              ─ values, validation, whether Save can go out, records and list columns, formSchema
   generate.js            ─ screenFromSpec, screensFromSpec (list + edit), entity names
-  scaffold.js            ─ an entity → its screen JSON, .jsx pages (with front-end hooks), server hooks + model stubs
+  scaffold.js            ─ an entity → its screen JSON, .jsx pages (with front-end hooks), server functions + model stubs
   hooks.js               ─ FactoryHooks: get / save / delete / actions — extend and call super
   presets.js             ─ ready-made fields (Email, Age, Gender…), changing a field's kind, label suggestions
   tableSchema.js         ─ a form → its table; the publish plan (create / add / widen / confirmed drops and conversions)

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, server hooks + model stubs
+//   xeplr-factory screens entity.json [-o dir]           an entity → list + edit screens, their .jsx pages, server functions + 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
@@ -81,11 +81,11 @@ switch (cmd) {
     } catch (err) {
       fail(err.message)
     }
-    // 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.
+    // The app's own code — the server functions and model, 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 kept = Object.keys(result.files).filter((f) => (f.endsWith('.functions.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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xeplr/ui-factory",
-  "version": "1.7.0",
+  "version": "1.7.2",
   "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/index.js

@@ -31,4 +31,4 @@ export { BuilderSample, ScreenSample, ListView, ScreenModal, FlowRunnerSample, F
 export { FactoryHooks } from './hooks.js'
 
 // Ready-made
-export { FactoryBuilder, FactoryScreen, FlowRunner, FlowBuilder, FlowDesigner } from './pages.jsx'
+export { FactoryBuilder, FactoryScreen, FlowRunner, FlowBuilder, FlowDesigner, FlowDesignerPage } from './pages.jsx'

package/src/pages.jsx

@@ -1,4 +1,4 @@
-import { useRef } from 'react'
+import { useEffect, useRef, useState } from 'react'
 import { useFactoryBuilder } from './useFactoryBuilder.js'
 import { useFactoryScreen } from './useFactoryScreen.js'
 import { useFlowRun } from './useFlowRun.js'
@@ -6,6 +6,7 @@ import { useFlowBuilder } from './useFlowBuilder.js'
 import { useScreenEvents } from './useScreenEvents.js'
 import { useFunctionCatalog } from './useFunctionCatalog.js'
 import { useUrlTab } from './useUrlPlaces.js'
+import { loadScreens } from './screenSource.js'
 import { BuilderSample, ScreenSample, ScreenModal, FlowRunnerSample, FlowBuilderSample, FlowDesignerSample } from './designs/index.js'
 
 /**
@@ -269,3 +270,52 @@ export function FlowDesigner(props) {
     />
   )
 }
+
+/**
+ * <FlowDesigner>, wired to an app's two API clients — what an app's
+ * /configure/flows/:key page renders, so the wiring lives here and not, copied
+ * and drifting, in every generated app.
+ *
+ * Loads the flow and the app's FORMS (screens with fields of their own — a
+ * step shows one to be filled in) and hands everything else straight on.
+ *
+ * @prop factory   createFactoryApi(…) — screens, drafts, publish, the app's functions
+ * @prop flows     createFlowsApi(…) — load, save, publish the flow
+ * @prop flowKey   the flow to open
+ * @prop urlKey    keep the selected step and tab in the URL
+ */
+export function FlowDesignerPage({ factory, flows, flowKey, urlKey, className, style }) {
+  const [flow, setFlow] = useState(null)
+  const [screens, setScreens] = useState(null)
+  const [error, setError] = useState(null)
+  useEffect(() => {
+    let gone = false
+    setFlow(null); setError(null)
+    Promise.all([flows.loadFlow(flowKey), loadScreens(factory)]).then(([f, list]) => {
+      if (gone) return
+      setFlow(f)
+      setScreens(list.filter((s) => s.fields && s.fields.length).map((s) => ({ id: s.key, name: s.name })))
+    }, (e) => { if (!gone) setError(e.message || `Could not open "${flowKey}"`) })
+    return () => { gone = true }
+  }, [factory, flows, flowKey])
+
+  if (error) return <div className="xeplr-factory-invalid" role="alert">{error}</div>
+  if (!flow || !screens) return <div className="xeplr-factory-hint">Opening the flow…</div>
+  return (
+    <FlowDesigner
+      flow={flow}
+      screens={screens}
+      loadScreen={factory.loadScreen}
+      onSave={flows.saveFlow}
+      onPublish={flows.publishFlow}
+      listFunctions={factory.listFunctions}
+      loadDraft={factory.loadDraft}
+      saveDraft={factory.saveDraft}
+      publishScreen={factory.publish}
+      builderProps={factory.builderProps}
+      urlKey={urlKey}
+      className={className}
+      style={style}
+    />
+  )
+}

package/src/scaffold.js

@@ -5,7 +5,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.functions.js                          — the code its events can run, registered by event (none yet)
 //   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,
@@ -31,7 +31,7 @@ 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}.functions.js`]: functionsFile(names, edit),
     [`${names.file}.model.js`]: modelFile(names, edit)
   }
   return { files, names, list, edit }
@@ -66,44 +66,40 @@ export default function ${n.listComponent}({ api }) {
 `
 }
 
-function hooksFile(n, edit) {
-  return `// Server hooks for ${n.singular} records — screen "${edit.id}" (and "${n.key}_list", which edits in it).
+function functionsFile(n, edit) {
+  return `// Functions for ${n.singular} records — the code the "${edit.id}" screen's events run.
 //
-// Register with @xeplr/factory:
-//   factory.init({ knex, hooks: { ${edit.id}: require('./${n.file}.hooks') } })
+// Each is registered with @xeplr/actions under the EVENT it is for, and runs
+// once the screen NAMES it — in ${n.file}-edit.screen.json's "events", or in the
+// designer (Configure UI → Flows → a step → Events). A screen naming a function
+// nobody registered is refused when it is published, so register first.
 //
-// Each operation has four hooks. Delete the ones you do not need.
-//   before(ctx)       first — save: return new values to replace them (they are then checked
-//                     against the screen's rules); get: narrow ctx.query; any: ctx.reject(message, { field })
-//   after(ctx)        once it succeeded — ctx.id, ctx.result; return a value to replace the result.
-//                     If it throws, the operation still happened (and error is told).
-//   error(ctx, err)   when the operation failed
-//   override(ctx)     does the WHOLE operation instead — no rules, no before / after / error,
-//                     no generic query. What it returns is the response.
+// Load this file once at startup, before the screens: require it from the
+// app's functions/index.js.
 //
-// ctx: op, screenKey, screen, table, id, isNew (save), many (get), input (what the UI sent, read-only),
-//      values (save), previous (save / delete: the row before), result, user, tenant, knex, query (get), reject
-
-module.exports = {
-  save: {
-    // before: async function(ctx) { return ctx.values },
-    // after: async function(ctx) {},
-    // error: async function(ctx, err) {},
-    // override: async function(ctx) { return savedRecord },
-  },
-  get: {
-    // before: async function(ctx) { /* ctx.query.where(...) */ },
-    // after: async function(ctx) { return ctx.result },
-    // error: async function(ctx, err) {},
-    // override: async function(ctx) { return ctx.id ? record : records },
-  },
-  delete: {
-    // before: async function(ctx) {},
-    // after: async function(ctx) {},
-    // error: async function(ctx, err) {},
-    // override: async function(ctx) { return { id: ctx.id } },
-  }
-}
+//   event          runs                                   return
+//   beforeLoad     before records are read                nothing, or a narrower ctx.query
+//   beforeSave     before a record is written             the values to save
+//   afterSave      once it is saved                       (ignored)
+//   beforeDelete   before a delete                        nothing
+//   onError        when load / save / delete failed       (ignored)
+//
+// ctx: op, screenKey, screen, table, id, isNew (save), many (get), input (what the
+//      UI sent, read-only), values (save), previous (save / delete: the row
+//      before), result (afterSave), error (onError), query (beforeLoad), user,
+//      tenant, knex, db() (this form's table, scoped), reject(message, { field })
+
+var { register } = require('@xeplr/actions');
+
+// register({
+//   name: '${n.key}BeforeSave',
+//   event: 'beforeSave',
+//   description: 'What it checks or changes, in one sentence — the designer shows it.',
+//   execute: function(ctx) {
+//     // ctx.reject('Explain what is wrong', { field: 'someField' })
+//     return ctx.values;
+//   }
+// });
 `
 }
 
@@ -111,10 +107,10 @@ 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')] })
+// Register with @xeplr/factory:  factory.init({ knex, models: [require('./${n.file}.model')] })
 //
 // Used everywhere: the screens' routes and factory.table('${edit.source}'). Models shape
-// data; the hooks file decides behaviour.
+// data; the functions its events name decide behaviour.
 
 var { FactoryModel } = require('@xeplr/factory');
 
@@ -159,7 +155,7 @@ import editScreen from './${editJson}'
 //
 // 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.
+// arrow functions. Rules that must hold belong in the server's functions (${n.file}.functions.js).
 export class ${n.hooksClass} extends FactoryHooks {
   /** A list's rows (ctx.many), or the record Edit opens (ctx.id). */
   get(ctx) {