@xeplr/ui-factory 1.0.8 → 1.0.10

package/AUTHORING.md

@@ -159,7 +159,7 @@ Names are derived once and agree everywhere: ids `employee_list` / `employee_edi
 | `columns` | `1` or `2` (default `2`) |
 | `heading` | `true` (default) puts the name at the top; a string uses that text; `false` for none |
 | `fields` | **required** — in reading order |
-| `list` | `true`, or `{ title, source, columns: [{ field, label }], pageSize, actions: ["new","edit","delete"] }` — saved records below the fields |
+| `list` | `true`, or `{ title, source, columns: [{ field, label }], pageSize, actions: ["new","edit","delete"], openIn: "popup" \| "page" }` — saved records below the fields |
 | `width` | design width in px (default `800`) |
 | `style` | screen-wide defaults: `{ fontFamily, fontSize, color, background }` |
 

package/README.md

@@ -153,7 +153,17 @@ Rules that must hold belong in the server's hooks; the browser only shapes what
 
 ### 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.
+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.
+
+**Opens in: a page of its own** sends them to a page in your app instead. The factory has no router, so it asks — `onOpenRecord` on the list's screen, and `onDone` on the page, which draws a **Done** button that saves what is pending and calls it:
+
+```jsx
+<FactoryScreen document={taskList} {...factory.screenProps}
+  onOpenRecord={({ id }) => navigate(id ? `/tasks/${id}` : '/tasks/new')} />
+
+<FactoryScreen document={taskEdit} record={task} {...factory.screenProps}
+  onDone={() => navigate('/tasks')} />
+``` **Delete** removes a row after a confirmation. Dropdown columns show names, not ids — read from the edit screen's fields.
 
 The edit screen comes from `screens` (`{ id → document }`) or your `loadScreen(id)`. A list on a form with no **Edit in** opens rows in that form's own fields instead.
 
@@ -186,6 +196,11 @@ const clean = schemaHandler.applySchema(formSchema(screen), req.body)   // throw
 | `label` | — | text with a heading, subheading or text preset |
 | `list` | — | saved records, with New / Edit / Delete |
 
+A screen is a **sheet**: it paints its own surface, so a screen designed in
+dark ink stays readable inside a dark app. Give the screen a `background` in
+its own style to change it, or set `--xeplr-factory-paper` on the host for all
+of them.
+
 Every control also takes `style` — see [AUTHORING.md](./AUTHORING.md#styles) for the keys. Sizes are pixels at the screen's design `width` (default 800): a screen is shown at that size, never stretched, and scaled down only on a narrower display.
 
 ### Steps
@@ -207,6 +222,19 @@ document stays flat, so a control is still moved, styled, checked and saved
 exactly as before; the step only decides when it is on screen. Renaming a step
 keeps its `key`, so the controls on it stay where they are.
 
+A stepper also gives the front-end hooks a **`step`** method, run before every
+move — Next, Back and a click on the bar alike, so a rule cannot be walked
+around by clicking ahead:
+
+```js
+class TaskHooks extends FactoryHooks {
+  step(ctx) {                       // { from, to, direction, values, screen }
+    if (ctx.direction === 'next' && ctx.from === 0 && !ctx.values.title) return false
+    return super.step(ctx)          // false stays, a number goes there instead
+  }
+}
+```
+
 **A step is not a separate form.** Every field is a column, is checked, and is
 saved, whichever step is showing — a screen still saves itself as it is filled
 in. **Next** holds at a step whose own fields are not filled in, and says which,

package/package.json

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

@@ -477,10 +477,12 @@ CONTROLS.list = {
   input: false,
   defaultSize: { w: 0.92, h: 0.42 },
   // No columns → the screen's own fields, in reading order.
-  defaults: { title: 'Saved records', pageSize: 10, actions: ['new', 'edit', 'delete'] },
-  // editScreen: the id of the screen Edit and New open in a POPUP. Without one,
-  // Edit opens the row in this screen's own fields (a list on a form).
-  props: ['title', 'source', 'editScreen', 'columns', 'pageSize', 'actions', 'style'],
+  defaults: { title: 'Saved records', pageSize: 10, actions: ['new', 'edit', 'delete'], openIn: 'popup' },
+  // editScreen: the id of the screen Edit and New open — in a POPUP, or as a
+  // 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', 'editScreen', 'openIn', 'columns', 'pageSize', 'actions', 'style'],
   validation: [],
   styles: ['fontFamily', 'fontSize', 'color', 'background', 'borderColor', 'borderWidth', 'borderRadius'],
   properties: [
@@ -490,7 +492,11 @@ CONTROLS.list = {
       fields: [
         { path: 'props.title', label: 'Title', type: 'text' },
         { path: 'props.source', label: 'Records from', type: 'table', help: 'Blank → the table this screen saves to' },
-        { path: 'props.editScreen', label: 'Edit in', type: 'screen', help: 'The screen Edit and New open in a popup' },
+        { path: 'props.editScreen', label: 'Edit in', type: 'screen', help: 'The screen Edit and New open' },
+        { path: 'props.openIn', label: 'Opens in', type: 'select', options: [
+          { value: 'popup', label: 'A popup' },
+          { value: 'page', label: 'A page of its own' }
+        ], help: 'A page asks the app to go there — see onOpenRecord' },
         { path: 'props.pageSize', label: 'Rows per page', type: 'number' }
       ]
     },

package/src/designs/ScreenSample.jsx

@@ -31,15 +31,15 @@ function StepNav({ ctrl, node }) {
   const at = ctrl.steps.active(node.id)
   const last = ctrl.steps.count(node.id) - 1
   const unfinished = ctrl.steps.fieldsOn(node.id, at).filter((n) => ctrl.allErrors[n.props.name])
-  const go = (to) => {
+  const go = (to, direction) => {
     if (to > at && unfinished.length) { unfinished.forEach((n) => ctrl.touch(n)); return }
-    ctrl.steps.go(node.id, Math.min(Math.max(to, 0), last))
+    ctrl.steps.go(node.id, Math.min(Math.max(to, 0), last), direction)
   }
   return (
     <div className="xeplr-factory-stepnav">
-      <button type="button" className="xeplr-factory-secondary" onClick={() => go(at - 1)} disabled={at === 0}>Back</button>
+      <button type="button" className="xeplr-factory-secondary" onClick={() => go(at - 1, 'back')} disabled={at === 0}>Back</button>
       <span className="xeplr-factory-stepnav-where">Step {at + 1} of {last + 1}</span>
-      <button type="button" className="xeplr-factory-primary" onClick={() => go(at + 1)} disabled={at === last}>Next</button>
+      <button type="button" className="xeplr-factory-primary" onClick={() => go(at + 1, 'next')} disabled={at === last}>Next</button>
     </div>
   )
 }
@@ -105,7 +105,7 @@ export default function ScreenSample({ ctrl, className, style, renderPopup }) {
               error={node.props?.name ? ctrl.errors[node.props.name] : undefined}
               options={CHOICE_TYPES.includes(node.type) ? ctrl.optionsFor(node) : undefined}
               upload={node.type === 'file' ? ctrl.upload : undefined}
-              stepper={node.type === 'stepper' ? { active: ctrl.steps.active(node.id), onStep: (i) => ctrl.steps.go(node.id, i) } : undefined}
+              stepper={node.type === 'stepper' ? { active: ctrl.steps.active(node.id), onStep: (i) => ctrl.steps.go(node.id, i, 'jump') } : undefined}
               onChange={(raw) => ctrl.setValue(node, raw)}
               onBlur={() => ctrl.touch(node)}
               list={node.type === 'list' ? {
@@ -131,6 +131,13 @@ export default function ScreenSample({ ctrl, className, style, renderPopup }) {
       {ctrl.steps.nodes.map((node) => (
         <StepNav key={node.id} ctrl={ctrl} node={node} />
       ))}
+      {ctrl.done && (
+        <div className="xeplr-factory-done">
+          <button type="button" className="xeplr-factory-primary" onClick={() => ctrl.flush().then(ctrl.done, ctrl.done)}>
+            {ctrl.status === 'pending' || ctrl.status === 'saving' ? 'Saving…' : 'Done'}
+          </button>
+        </div>
+      )}
       {ctrl.popup && renderPopup && renderPopup(ctrl.popup, ctrl)}
     </div>
   )

package/src/designs/factory.css

@@ -19,8 +19,23 @@
   --xf-danger: var(--xeplr-danger, #c2372e);
 }
 
-/* ── the screen ─────────────────────────────────────────────────────────── */
-.xeplr-factory-screen { position: relative; width: 100%; color: var(--xf-ink); }
+/* ── the screen ───────────────────────────────────────────────────────────
+   A screen is a SHEET: it paints its own surface, the way the builder's canvas
+   does. Without that it is transparent, and a screen designed in dark ink
+   disappears into a dark app — what you designed is not what you get. The
+   screen's own `background` style overrides this (screenStyle), as does the
+   host with --xeplr-factory-paper. */
+.xeplr-factory-screen {
+  position: relative; width: 100%;
+  color: var(--xf-ink);
+  background: var(--xeplr-factory-paper, var(--xf-surface));
+  border-radius: calc(8 * var(--xf-u));
+}
+/* The status line and the step buttons live on the sheet, so they keep a
+   margin of their own rather than touching its edge. */
+.xeplr-factory-screen > .xeplr-factory-status,
+.xeplr-factory-screen > .xeplr-factory-stepnav,
+.xeplr-factory-screen > .xeplr-factory-done { padding-inline: calc(12 * var(--xf-u)); }
 .xeplr-factory-status {
   display: flex; justify-content: space-between; gap: 12px; min-height: 18px;
   padding: 4px 2px 8px; font-size: 12px; color: var(--xf-muted);
@@ -119,6 +134,9 @@
 .xeplr-factory-stepnav { display: flex; align-items: center; gap: 12px; padding: 10px 0; }
 .xeplr-factory-stepnav-where { flex: 1; text-align: center; color: var(--xf-muted); font-size: 12px; }
 
+/* Done — a page's way back, when the list opens records on one. */
+.xeplr-factory-done { display: flex; justify-content: flex-end; padding: 10px 0; }
+
 /* Which step the builder is on. */
 .xeplr-factory-building { display: flex; align-items: center; flex-wrap: wrap; gap: 8px; margin: 0 auto 8px; padding: 6px 0; }
 .xeplr-factory-building-what { color: var(--xf-muted); font-size: 12px; font-weight: 600; text-transform: uppercase; letter-spacing: 0.06em; }

package/src/generate.js

@@ -247,7 +247,7 @@ function round(v) {
 // The list names the edit screen (`editScreen`), which is the only link
 // between them; both save to and read from the same table.
 
-const ENTITY_KEYS = ['entity', 'plural', 'source', 'fields', 'columns', 'listColumns', 'pageSize', 'actions', 'width', 'style', 'aspect']
+const ENTITY_KEYS = ['entity', 'plural', 'source', 'fields', 'columns', 'listColumns', 'pageSize', 'actions', 'width', 'style', 'aspect', 'openIn']
 
 /**
  * @param spec
@@ -301,7 +301,9 @@ export function screensFromSpec(spec, controls = CONTROLS) {
       editScreen: edit.id,
       columns: listColumns,
       pageSize: spec.pageSize || 10,
-      actions: spec.actions || ['new', 'edit', 'delete']
+      actions: spec.actions || ['new', 'edit', 'delete'],
+      // 'page' sends Edit / New to a page of the app's own — see onOpenRecord.
+      openIn: spec.openIn || 'popup'
     }
   }, controls))
 

package/src/hooks.js

@@ -53,6 +53,27 @@ export class FactoryHooks {
     return ctx.defaults.delete(record)
   }
 
+  /**
+   * Before a stepper moves — Next, Back, or a click on the bar itself.
+   *
+   *   step(ctx) {
+   *     if (ctx.direction === 'next' && ctx.from === 0 && !ctx.values.title) return false
+   *     return super.step(ctx)
+   *   }
+   *
+   * @param ctx.from       the step being left, counting from 0
+   * @param ctx.to         the step asked for
+   * @param ctx.direction  'next' | 'back' | 'jump' (a click on the bar)
+   * @param ctx.values     what the form holds
+   * @param ctx.stepper    the stepper's node id
+   * @returns false to stay where you are, a step number to go somewhere else,
+   *          anything else to move as asked. The step's own required fields are
+   *          checked before this runs, so this is for your rules, not theirs.
+   */
+  step(ctx) {
+    return true
+  }
+
   /**
    * Extra buttons on each row, beside Edit and Delete:
    *   [{ label: 'Mark done', onClick: (record, ctx) => … }]

package/src/useFactoryScreen.js

@@ -35,6 +35,8 @@ export const AUTOSAVE_DELAY = 700
  * @param recordKey     the id field on a record (default 'id')
  * @param onSave        async (values, { id, source, document }) → saved record | void
  * @param fetchOptions  async ({ table, node }) → [{ id, name }]
+ * @param onOpenRecord  ({ screen, id, record, source }) → void — where a list whose "Opens in" is a page sends Edit / New
+ * @param onDone        () → void — a page's "Done": back to wherever the person came from
  * @param uploadFile    async (file, { screen, field, node }) → { path } — what a file field saves
  * @param fileUrl       (path) → the address an attached file is read back from
  * @param fetchRecords  async ({ source, node }) → records, for lists
@@ -49,6 +51,7 @@ export const AUTOSAVE_DELAY = 700
  */
 export function useFactoryScreen({
   document: doc, record, recordKey = 'id', onSave, fetchOptions, fetchRecords, fetchRecord, onDelete, onChange, screens, loadScreen, hooks, uploadFile, fileUrl,
+  onOpenRecord, onDone,
   autosaveDelay = AUTOSAVE_DELAY, controls = CONTROLS
 } = {}) {
   const check = useMemo(() => validateDocument(doc, controls), [doc, controls])
@@ -174,7 +177,31 @@ export function useFactoryScreen({
       nodes: stepperNodes,
       active: at,
       count: (id) => stepsOf(stepperNodes.find((n) => n.id === id)).length,
-      go: (id, index) => setOpenSteps((o) => ({ ...o, [id]: index })),
+      /**
+       * Move, if the app's `step` hook lets it: false keeps the person where
+       * they are, a number sends them somewhere else. The hook runs for Next,
+       * Back and a click on the bar alike, so a rule cannot be walked around.
+       */
+      go: async (id, index, direction) => {
+        const from = at(id)
+        const last = stepsOf(stepperNodes.find((n) => n.id === id)).length - 1
+        const to = Math.min(Math.max(index, 0), Math.max(last, 0))
+        if (to === from) return from
+        const decide = hookMethod(hooksRef.current, 'step')
+        const answer = await decide({
+          from,
+          to,
+          direction: direction || (to > from ? 'next' : 'back'),
+          values: live.current.values,
+          stepper: id,
+          screen: doc.id,
+          document: doc
+        })
+        if (answer === false) return from
+        const where = Number.isInteger(answer) ? Math.min(Math.max(answer, 0), Math.max(last, 0)) : to
+        setOpenSteps((o) => ({ ...o, [id]: where }))
+        return where
+      },
       /** The fields on this step, so Next can hold at a step that is not filled in. */
       fieldsOn: (id, index) => inputNodes(doc, controls).filter((n) => {
         const step = stepOf(n)
@@ -406,9 +433,19 @@ export function useFactoryScreen({
   const fetchRecordRef = useRef(fetchRecord); fetchRecordRef.current = fetchRecord
   const loadScreenRef = useRef(loadScreen); loadScreenRef.current = loadScreen
 
-  /** Edit (a record) or New (null) in the list's edit screen. */
+  /**
+   * Edit (a record) or New (null) in the list's edit screen — in a popup, or
+   * on a page of the app's own when the list says so. A page is the app's to
+   * open: the factory has no router, so it asks.
+   */
+  const openRecordRef = useRef(onOpenRecord); openRecordRef.current = onOpenRecord
   const openEditor = useCallback(async (node, rec) => {
     const screenId = node.props.editScreen
+    if (node.props.openIn === 'page') {
+      if (!openRecordRef.current) throw new Error('This list opens records on a page, but no onOpenRecord was provided to go there')
+      const id = rec ? rec[live.current.recordKey] : null
+      return openRecordRef.current({ screen: screenId, id, record: rec || null, source: listSource(doc, node), node })
+    }
     const base = { node, screenId, record: rec || null, document: null, loading: true, error: null }
     setPopup(base)
     try {
@@ -464,6 +501,7 @@ export function useFactoryScreen({
     setValue,
     touch,
     optionsFor,
+    done: onDone || null,
     steps: stepControl,
     visibleNodes,
     upload,

package/src/validateDocument.js

@@ -319,6 +319,9 @@ function checkStyle(style, allowed, at, err, owner) {
  * must be set.
  */
 function checkList(props, doc, at, err) {
+  if (props.openIn !== undefined && props.openIn !== 'popup' && props.openIn !== 'page') {
+    err(`${at}.props.openIn`, 'must be "popup" or "page"')
+  }
   if (props.title !== undefined && typeof props.title !== 'string') err(`${at}.props.title`, 'must be a string')
   if (props.source !== undefined && !(nonEmptyString(props.source) && TABLE_NAME.test(props.source))) err(`${at}.props.source`, 'must name the table to list records from')
   if (props.source === undefined && doc.source === undefined) err(`${at}.props.source`, 'is required when the screen has no "source" — which table should the list read?')