@xeplr/ui-factory 1.4.0 → 1.5.0

package/README.md

@@ -323,6 +323,29 @@ Controller: the embedded screen is a second `useFactoryScreen` with `link`
 save, name }`). `FactoryScreen` wires both; a custom design gets `subformFor(node)`,
 `registerSubform(id, api)` and `subformDirty(id, dirty)` from the host's controller.
 
+## Events — the app's code, picked by name
+
+A screen says which of the app's functions run around its records, one per
+event. The code is registered in the app (with `@xeplr/actions`, `event` set
+to one of these); the screen only names it:
+
+```json
+"events": { "beforeSave": "checkSalaryBand", "afterSave": "notifyHR" }
+```
+
+| event | runs | gets | returns |
+|---|---|---|---|
+| `beforeLoad` | Before records are read — the list, and one record for Edit | ctx.query (narrow it), ctx.id (one record) or ctx.many (the list), ctx.user, ctx.tenant | nothing, or a new query |
+| `beforeSave` | Before a record is written — the screen's rules run on what it returns | ctx.values, ctx.isNew, ctx.previous (on update), ctx.user | the values to save (or nothing to keep them); ctx.reject(message, { field }) refuses |
+| `afterSave` | Once the record is saved | ctx.result (the saved row), ctx.isNew, ctx.values | nothing — what it does is the point (an email, another record) |
+| `beforeDelete` | Before a record is deleted | ctx.previous (the row), ctx.id | nothing; ctx.reject(message) refuses |
+| `onError` | When loading, saving or deleting failed | ctx.error, ctx.op (get, save or delete) | nothing — the error is still the answer; this is for telling someone |
+
+- **This is the only way to attach code to a screen's records.** One function per event, named in the screen — the screen is the one place that says what runs.
+- **Every event runs on the server** (`@xeplr/factory` 2+). A rule that runs in the browser is one a person can skip.
+- **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.
+
 ## Masters — the lists the rest of the app points at
 
 Departments, statuses, countries, categories. Mark a form as a master in its

package/package.json

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

@@ -0,0 +1,84 @@
+// A SCREEN'S EVENTS — the moments a developer's code may run around its
+// records, each picked BY NAME from the functions the app registered.
+//
+// The code lives in the app (registered with @xeplr/actions, `event` set to
+// one of the keys below); the screen only names it:
+//
+//   doc.events = { beforeSave: 'checkSalaryBand', afterSave: 'notifyHR' }
+//
+// One function per event, and this is the ONLY way to attach one — the screen
+// is the one place that says what runs. Every event runs on the SERVER: a rule
+// that runs in the browser is one a person can skip.
+//
+// What each is called with, and what it may return, is the contract a
+// developer writes to. `@xeplr/factory` runs them; the designer lists them.
+
+export const SCREEN_EVENTS = [
+  {
+    key: 'beforeLoad',
+    label: 'Before load',
+    when: 'Before records are read — the list, and one record for Edit',
+    gets: 'ctx.query (narrow it), ctx.id (one record) or ctx.many (the list), ctx.user, ctx.tenant',
+    returns: 'nothing, or a new query'
+  },
+  {
+    key: 'beforeSave',
+    label: 'Before save',
+    when: 'Before a record is written — the screen\'s rules run on what it returns',
+    gets: 'ctx.values, ctx.isNew, ctx.previous (on update), ctx.user',
+    returns: 'the values to save (or nothing to keep them); ctx.reject(message, { field }) refuses'
+  },
+  {
+    key: 'afterSave',
+    label: 'After save',
+    when: 'Once the record is saved',
+    gets: 'ctx.result (the saved row), ctx.isNew, ctx.values',
+    returns: 'nothing — what it does is the point (an email, another record)'
+  },
+  {
+    key: 'beforeDelete',
+    label: 'Before delete',
+    when: 'Before a record is deleted',
+    gets: 'ctx.previous (the row), ctx.id',
+    returns: 'nothing; ctx.reject(message) refuses'
+  },
+  {
+    key: 'onError',
+    label: 'On error',
+    when: 'When loading, saving or deleting failed',
+    gets: 'ctx.error, ctx.op (get, save or delete)',
+    returns: 'nothing — the error is still the answer; this is for telling someone'
+  }
+]
+
+export const SCREEN_EVENT_KEYS = SCREEN_EVENTS.map((e) => e.key)
+
+/**
+ * A FLOW's "let a function decide": the function an arrow asks for the next
+ * step. Not a screen event — the workflow engine runs it, between screens.
+ */
+export const DECIDE_EVENT = 'decide'
+
+/** A function's name: what it was registered under. */
+export const FUNCTION_NAME = /^[A-Za-z_][\w.-]{0,99}$/
+
+/** The functions a screen names, as [{ event, name }] — what has to be registered for it to run. */
+export function screenFunctions(doc) {
+  const ev = (doc && doc.events) || {}
+  return SCREEN_EVENT_KEYS.filter((k) => typeof ev[k] === 'string' && ev[k]).map((k) => ({ event: k, name: ev[k] }))
+}
+
+/**
+ * Which of a screen's functions are not registered, or are registered for a
+ * different event — given the registry's list ([{ name, event }]). Empty when
+ * the screen can run. Said by name, so the fix is obvious.
+ */
+export function missingFunctions(doc, registered) {
+  const byName = new Map((registered || []).map((f) => [f.name, f]))
+  return screenFunctions(doc).flatMap(({ event, name }) => {
+    const f = byName.get(name)
+    if (!f) return [{ event, name, problem: `"${name}" is not a registered function` }]
+    if (f.event !== event) return [{ event, name, problem: `"${name}" is written for ${f.event ? `"${f.event}"` : 'a workflow step'}, not "${event}"` }]
+    return []
+  })
+}

package/src/model.js

@@ -12,6 +12,8 @@ export {
   steppers, stepsOf, stepOf, setNodeStep, nodesForSteps, resolveStep, reachableStep, nextOpenStep
 } from './document.js'
 export { validateDocument, assertValidDocument } from './validateDocument.js'
+// A screen's events: functions picked by name, run on the server.
+export { SCREEN_EVENTS, SCREEN_EVENT_KEYS, DECIDE_EVENT, FUNCTION_NAME, screenFunctions, missingFunctions } from './events.js'
 export { formSchema, initialValues, parseInput, validateValues, fieldError, sameId, optionValue, chooseable, saveState, recordValues, displayValue, fileLabel, toDbValue, fromDbValue, listColumns, listSource } from './values.js'
 export { screenFromSpec, screensFromSpec, entityNames, SPEC_HEIGHTS, ROW_GAP } from './generate.js'
 export { scaffoldEntity } from './scaffold.js'

package/src/validateDocument.js

@@ -10,6 +10,7 @@
 // Loud by design: a screen that half-renders — a dropdown with no options, two
 // fields writing the same key — looks like a data problem to whoever uses it.
 
+import { SCREEN_EVENT_KEYS, FUNCTION_NAME } from './events.js'
 import { CONTROLS, LABEL_VARIANTS, LIST_ACTIONS, STYLE_KEYS, SCREEN_STYLE_KEYS, LAYOUTS, MULTI_SEPARATOR, MAX_FILE_MB, STEP_LIMIT, acceptList } from './controls.js'
 import { DOCUMENT_KIND, DOCUMENT_VERSION } from './document.js'
 import { RESERVED_COLUMNS, MAX_IDENTIFIER } from './tableSchema.js'
@@ -18,7 +19,7 @@ import { FIELD_PRESETS, INPUT_TYPES, presetFor } from './presets.js'
 const FIELD_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/
 const TABLE_NAME = /^[A-Za-z_][A-Za-z0-9_.$-]*$/
 const SCREEN_ID = /^[A-Za-z0-9_-]+$/
-const DOCUMENT_KEYS = ['kind', 'version', 'id', 'name', 'source', 'units', 'aspect', 'width', 'style', 'description', 'master', 'labelField', 'params', 'nodes']
+const DOCUMENT_KEYS = ['kind', 'version', 'id', 'name', 'source', 'units', 'aspect', 'width', 'style', 'description', 'master', 'labelField', 'params', 'events', 'nodes']
 const COLOR = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i
 
 /**
@@ -71,6 +72,17 @@ export function validateDocument(doc, controls = CONTROLS) {
   // {params.<name>} as its default, so a name that is not a plain identifier
   // could never be referenced, and a duplicate would make the reference mean
   // two things.
+  // EVENTS — functions picked by name, one per event (see events.js). Whether
+  // each is REGISTERED is the server's to say, at publish and at run time:
+  // this checks only that the screen asks for something that could exist.
+  if (doc.events !== undefined) {
+    if (!doc.events || typeof doc.events !== 'object' || Array.isArray(doc.events)) err('events', `must be { ${SCREEN_EVENT_KEYS.join(', ')} } — each the name of a registered function`)
+    else Object.keys(doc.events).forEach((k) => {
+      const v = doc.events[k]
+      if (!SCREEN_EVENT_KEYS.includes(k)) err(`events.${k}`, `is not an event — one of: ${SCREEN_EVENT_KEYS.join(', ')}`)
+      else if (v !== null && v !== '' && !(typeof v === 'string' && FUNCTION_NAME.test(v))) err(`events.${k}`, 'must be the name of a registered function, e.g. "checkSalaryBand"')
+    })
+  }
   if (doc.params !== undefined) {
     if (!Array.isArray(doc.params)) err('params', 'must be a list of inputs this screen is called with')
     else {