@xeplr/ui-factory 1.0.11 → 1.0.12

package/README.md

@@ -235,6 +235,25 @@ class TaskHooks extends FactoryHooks {
 }
 ```
 
+A screen with branches can **rule steps out** from the same hook — they stay on
+the bar, struck through, and Next and Back pass over them:
+
+```js
+step(ctx) {
+  if (ctx.from === 0 && ctx.values.kind === 'simple') {
+    ctx.disable(['pricing', 'approval'])   // by key, label or number
+    return 'summary'                        // and go straight there
+  }
+  ctx.enable()                              // every step applies again
+  return super.step(ctx)
+}
+```
+
+`ctx.go`, `ctx.disable` and `ctx.enable` act on that stepper; `ctx.steps` is the
+same for a screen with more than one (`ctx.steps.disable('approval', stepperId)`).
+`ctx.steps` is on `save` and `get` too, since a save is usually where an app
+learns which branch it is on. "Step 2 of 4" counts only the steps that apply.
+
 **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.11",
+  "version": "1.0.12",
   "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/ControlView.jsx

@@ -341,7 +341,8 @@ function StepperView({ node, p, design, stepper }) {
     <div className="xeplr-factory-stepper" style={{ ...fieldStyle(p.style), ...text }}>
       <ol className="xeplr-factory-steps">
         {steps.map((s, i) => {
-          const state = i === active ? 'is-active' : i < active ? 'is-done' : ''
+          const off = Boolean(stepper && stepper.isDisabled && stepper.isDisabled(i))
+          const state = off ? 'is-off' : i === active ? 'is-active' : i < active ? 'is-done' : ''
           return (
             <li key={s.key} className={`xeplr-factory-step ${state}`} aria-current={i === active ? 'step' : undefined}>
               <button
@@ -349,7 +350,9 @@ function StepperView({ node, p, design, stepper }) {
                 className="xeplr-factory-step-button"
                 // On the canvas a press must still be able to drag the control,
                 // so the step is taken on click, never on mousedown.
-                onClick={(e) => { if (go) { e.stopPropagation(); go(i) } }}
+                onClick={(e) => { if (go && !off) { e.stopPropagation(); go(i) } }}
+                disabled={off}
+                aria-disabled={off || undefined}
                 tabIndex={design ? -1 : undefined}
               >
                 <span className="xeplr-factory-step-mark" aria-hidden="true">{i < active ? '✓' : (p.showNumbers === false ? '' : i + 1)}</span>

package/src/designs/ScreenSample.jsx

@@ -29,17 +29,26 @@ const STATUS = {
  */
 function StepNav({ ctrl, node, children }) {
   const at = ctrl.steps.active(node.id)
-  const last = ctrl.steps.count(node.id) - 1
+  const total = ctrl.steps.count(node.id)
+  const off = ctrl.steps.disabled(node.id)
   const unfinished = ctrl.steps.fieldsOn(node.id, at).filter((n) => ctrl.allErrors[n.props.name])
+  // Back and Next go to the nearest step that is switched on, passing over any
+  // the app has ruled out; null means there is none that way.
+  const back = ctrl.steps.nextOpen(node.id, 'back')
+  const forward = ctrl.steps.nextOpen(node.id, 'next')
   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), direction)
+    if (to === null) return
+    if (direction === 'next' && unfinished.length) { unfinished.forEach((n) => ctrl.touch(n)); return }
+    ctrl.steps.go(node.id, to, direction)
   }
+  // "Step 2 of 4" counts the steps that apply, not the ones ruled out.
+  const live = total - off.length
+  const place = at - off.filter((i) => i < at).length + 1
   return (
     <div className="xeplr-factory-stepnav">
-      <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, 'next')} disabled={at === last}>Next</button>
+      <button type="button" className="xeplr-factory-secondary" onClick={() => go(back, 'back')} disabled={back === null}>Back</button>
+      <span className="xeplr-factory-stepnav-where">Step {place} of {live}</span>
+      <button type="button" className="xeplr-factory-primary" onClick={() => go(forward, 'next')} disabled={forward === null}>Next</button>
       {children}
     </div>
   )
@@ -116,7 +125,11 @@ 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, 'jump') } : undefined}
+              stepper={node.type === 'stepper' ? {
+                active: ctrl.steps.active(node.id),
+                isDisabled: (i) => ctrl.steps.isDisabled(node.id, i),
+                onStep: (i) => ctrl.steps.go(node.id, i, 'jump')
+              } : undefined}
               onChange={(raw) => ctrl.setValue(node, raw)}
               onBlur={() => ctrl.touch(node)}
               list={node.type === 'list' ? {

package/src/designs/factory.css

@@ -129,6 +129,10 @@
 .xeplr-factory-step.is-active .xeplr-factory-step-mark,
 .xeplr-factory-step.is-done .xeplr-factory-step-mark { background: var(--xf-accent); color: #fff; }
 .xeplr-factory-step.is-active .xeplr-factory-step-button { color: var(--xf-accent); font-weight: 600; }
+/* A step the app has ruled out: still shown, so the journey reads the same,
+   but plainly not one of the stops. */
+.xeplr-factory-step.is-off .xeplr-factory-step-button { opacity: 0.4; cursor: default; }
+.xeplr-factory-step.is-off .xeplr-factory-step-label { text-decoration: line-through; }
 
 /* Back / Next, under the page. */
 .xeplr-factory-stepnav { display: flex; align-items: center; gap: 12px; padding: 10px 0; }

package/src/document.js

@@ -155,6 +155,46 @@ export function nodesForSteps(doc, active = {}, controls = CONTROLS) {
   return (doc.nodes || []).filter((n) => shown(n, new Set()))
 }
 
+// Which step a move lands on. Pure, and the only place the rules live: a step
+// may be named by its key, its label or its number; a step that is switched
+// off is passed over, in the direction of travel, and only when there is
+// nothing that way is the other direction tried.
+
+/** A step named by key, label or number → its index, or -1. */
+export function resolveStep(steps, which) {
+  if (Number.isInteger(which)) return which >= 0 && which < steps.length ? which : -1
+  return steps.findIndex((s) => s.key === which || s.label === which)
+}
+
+/**
+ * The step actually reached when aiming at `index`.
+ * @param disabled  indexes switched off
+ * @param direction 'next' | 'back' | 'jump'
+ * @param from      where we are now, for when nothing is open either way
+ */
+export function reachableStep(count, index, disabled = [], direction = 'next', from = 0) {
+  if (count <= 0) return 0
+  const off = (i) => disabled.includes(i)
+  const clamp = (i) => Math.min(Math.max(i, 0), count - 1)
+  const way = direction === 'back' ? -1 : 1
+  let i = clamp(index)
+  while (i >= 0 && i < count && off(i)) i += way
+  if (i < 0 || i >= count) {
+    i = clamp(index)
+    while (i >= 0 && i < count && off(i)) i -= way
+  }
+  return i >= 0 && i < count ? i : clamp(from)
+}
+
+/** The nearest open step in this direction, or null when there is none. */
+export function nextOpenStep(count, at, disabled = [], direction = 'next') {
+  const step = direction === 'back' ? -1 : 1
+  const aim = at + step
+  if (aim < 0 || aim >= count) return null
+  const i = reachableStep(count, aim, disabled, direction, at)
+  return i === at || disabled.includes(i) ? null : i
+}
+
 /** Merges a geometry patch — what the canvas reports on drop. */
 export function moveNode(doc, id, patch) {
   const geometry = {}

package/src/hooks.js

@@ -42,6 +42,8 @@ export class FactoryHooks {
   /**
    * Save — called on every autosave, so keep it quick and safe to repeat.
    * @param values  what the form holds
+   * @param ctx.steps  switch steps off or on as the record decides them —
+   *        ctx.steps.disable('approval'), ctx.steps.enable()
    * @returns the saved record (its id makes the next save an update)
    */
   save(values, ctx) {
@@ -61,14 +63,32 @@ export class FactoryHooks {
    *     return super.step(ctx)
    *   }
    *
+   * A screen with branches decides which of them apply from here:
+   *
+   *   step(ctx) {
+   *     if (ctx.from === 0) {
+   *       if (ctx.values.kind === 'simple') { ctx.disable(['pricing', 'approval']); return 'summary' }
+   *       ctx.enable()                       // every step applies again
+   *     }
+   *     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.
+   * @param ctx.go         (step) → move there (a key or a number)
+   * @param ctx.disable    (steps) → switch them off: shown, but passed over by
+   *                       Next and Back and not clickable. A key, a number, or
+   *                       a list of either.
+   * @param ctx.enable     (steps) → switch them back on; no arguments, all of them
+   * @param ctx.steps      the same, for a screen with more than one stepper:
+   *                       disable(which, stepperId), active(id), disabled(id)
+   * @returns false to stay where you are, a step (its key or its 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

package/src/model.js

@@ -8,7 +8,7 @@ export {
   DOCUMENT_KIND, DOCUMENT_VERSION, DEFAULT_ASPECT, DEFAULT_WIDTH, MARGIN, GAP,
   createScreen, renameScreen, setScreenProperty, addControl, moveNode, setNodeProperty, getNodeProperty, removeNodes,
   inputNodes, readingOrder, contentBottom, camelName, slugify, uniqueFieldName, nextPosition,
-  steppers, stepsOf, stepOf, setNodeStep, nodesForSteps
+  steppers, stepsOf, stepOf, setNodeStep, nodesForSteps, resolveStep, reachableStep, nextOpenStep
 } from './document.js'
 export { validateDocument, assertValidDocument } from './validateDocument.js'
 export { formSchema, initialValues, parseInput, validateValues, fieldError, sameId, optionValue, chooseable, saveState, recordValues, displayValue, fileLabel, toDbValue, fromDbValue, listColumns, listSource } from './values.js'

package/src/useFactoryScreen.js

@@ -1,6 +1,6 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import { CONTROLS, CHOICE_TYPES } from './controls.js'
-import { inputNodes, nodesForSteps, steppers, stepsOf, stepOf } from './document.js'
+import { inputNodes, nodesForSteps, steppers, stepsOf, stepOf, resolveStep, reachableStep, nextOpenStep } from './document.js'
 import { validateDocument } from './validateDocument.js'
 import { initialValues, parseInput, saveState, fieldError, optionValue, recordValues, listSource } from './values.js'
 import { hookMethod } from './hooks.js'
@@ -152,6 +152,9 @@ export function useFactoryScreen({
   // the fields of the steps not showing are still filled in, still checked and
   // still saved — a step is what the person sees, not a separate form.
   const [openSteps, setOpenSteps] = useState({})
+  // Steps the app has switched off — { stepper id: [index, …] }. A screen may
+  // have branches; which of them apply is the app's to say, from its hooks.
+  const [disabledSteps, setDisabledSteps] = useState({})
   const stepperNodes = useMemo(() => (check.ok ? steppers(doc, controls) : []), [check.ok, doc, controls])
   const visibleNodes = useMemo(() => (check.ok ? nodesForSteps(doc, openSteps, controls) : []), [check.ok, doc, openSteps, controls])
 
@@ -173,42 +176,104 @@ export function useFactoryScreen({
 
   const stepControl = useMemo(() => {
     const at = (id) => (Number.isInteger(openSteps[id]) ? openSteps[id] : 0)
-    return {
+    const only = () => (stepperNodes.length === 1 ? stepperNodes[0].id : null)
+    const nodeFor = (id) => stepperNodes.find((n) => n.id === id) || stepperNodes[0] || null
+    const lastOf = (id) => stepsOf(nodeFor(id)).length - 1
+    /** A step named by its key ("planning"), its label, or its number from 0. */
+    const indexOf = (id, which) => resolveStep(stepsOf(nodeFor(id)), which)
+    const offList = (id) => disabledSteps[id] || []
+    const isOff = (id, index) => offList(id).includes(index)
+    const reachable = (id, index, direction) => reachableStep(lastOf(id) + 1, index, offList(id), direction, at(id))
+    const setOff = (id, list) => setDisabledSteps((d) => ({ ...d, [id || only()]: list }))
+
+    const control = {
       nodes: stepperNodes,
       active: at,
-      count: (id) => stepsOf(stepperNodes.find((n) => n.id === id)).length,
+      count: (id) => stepsOf(nodeFor(id)).length,
+      labels: (id) => stepsOf(nodeFor(id)),
+      indexOf,
+      /** Is this step switched off — shown, but not one you can be on? */
+      isDisabled: (id, index) => isOff(id, index),
+      disabled: (id) => (disabledSteps[id || only()] || []).slice(),
+      /**
+       * Switch steps off (a key, a number, or a list of them). A step that is
+       * off cannot be reached by Next, Back or a click, and Next passes over
+       * it. Switching off the step someone is on moves them to the nearest one
+       * that is open.
+       */
+      disable: (which, id) => {
+        const on = id || only()
+        if (!on) return []
+        const add = (Array.isArray(which) ? which : [which]).map((w) => indexOf(on, w)).filter((i) => i >= 0)
+        const next = [...new Set([...(disabledSteps[on] || []), ...add])]
+        setOff(on, next)
+        return next
+      },
+      /** Switch them back on. No arguments switches every step of it back on. */
+      enable: (which, id) => {
+        const on = id || only()
+        if (!on) return []
+        if (which === undefined) { setOff(on, []); return [] }
+        const drop = (Array.isArray(which) ? which : [which]).map((w) => indexOf(on, w))
+        const next = (disabledSteps[on] || []).filter((i) => !drop.includes(i))
+        setOff(on, next)
+        return next
+      },
       /**
        * 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))
+        const on = id || only()
+        const from = at(on)
+        const way = direction || (index > from ? 'next' : 'back')
+        const to = reachable(on, indexOf(on, index), way)
         if (to === from) return from
         const decide = hookMethod(hooksRef.current, 'step')
         const answer = await decide({
           from,
           to,
-          direction: direction || (to > from ? 'next' : 'back'),
+          direction: way,
           values: live.current.values,
-          stepper: id,
+          stepper: on,
           screen: doc.id,
-          document: doc
+          document: doc,
+          // What the hook can DO from here: send them somewhere, or say which
+          // steps this answer makes beside the point.
+          steps: control,
+          go: (where) => control.go(on, where, 'jump'),
+          disable: (which) => control.disable(which, on),
+          enable: (which) => control.enable(which, on)
         })
         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 }))
+        const asked = Number.isInteger(answer) || typeof answer === 'string' ? indexOf(on, answer) : to
+        const where = reachable(on, asked >= 0 ? asked : to, way)
+        setOpenSteps((o) => ({ ...o, [on]: where }))
         return where
       },
+      /** The next step in this direction that is open, for Back and Next. */
+      nextOpen: (id, direction) => {
+        const on = id || only()
+        return nextOpenStep(lastOf(on) + 1, at(on), offList(on), direction)
+      },
       /** 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)
-        return step && step.of === id && step.index === index
+        return step && step.of === (id || only()) && step.index === index
       })
     }
-  }, [stepperNodes, openSteps, doc, controls])
+    return control
+  }, [stepperNodes, openSteps, disabledSteps, doc, controls])
+
+  live.current.steps = stepControl
+
+  // A step that is switched off cannot be the one showing.
+  useEffect(() => {
+    stepperNodes.forEach((n) => {
+      if (stepControl.isDisabled(n.id, stepControl.active(n.id))) stepControl.go(n.id, stepControl.active(n.id) + 1, 'next')
+    })
+  }, [stepperNodes, stepControl])
 
   // ── a file field's upload ─────────────────────────────────────────────
   const uploadRef = useRef(uploadFile); uploadRef.current = uploadFile
@@ -257,6 +322,9 @@ export function useFactoryScreen({
         const saved = await hook('save')(l.values, {
           ...meta,
           isNew: l.recordId === null || l.recordId === undefined,
+          // Save is where an app usually learns which branch it is on, so it
+          // can switch steps off from here as well as from step().
+          steps: live.current.steps,
           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.
@@ -376,6 +444,7 @@ export function useFactoryScreen({
       setLists((l) => ({ ...l, [node.id]: { rows: l[node.id]?.rows || [], loading: true, error: null } }))
       const run = Promise.resolve().then(() => hook('get')({
         many: true, id: null, screen: doc.id, source: src, node, document: doc,
+        steps: live.current.steps,
         defaults: {
           get: () => {
             if (!fetchRecordsRef.current) throw new Error(`No fetchRecords was provided to list "${src}"`)