@xeplr/ui-factory 1.0.11 → 1.0.13

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}"`)

package/src/useFlowBuilder.js

@@ -0,0 +1,186 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
+import {
+  createFlow, addStep, moveStep, setStep, removeStep,
+  addTransition, setTransition, removeTransition, validateFlow, firstStep, layoutFlow, FLOW_END
+} from './flow.js'
+import { inputNodes } from './document.js'
+
+// DESIGNING a flow: which screens, in what order, and what decides the order.
+//
+// The same shape as useFactoryBuilder, so the two designers feel like one
+// product: the document, what is selected, and a save that happens by itself
+// once what is drawn makes sense. Publishing is separate and deliberate — a
+// flow that is published is what people actually walk through.
+
+/** Quiet time after the last change before a save goes out. */
+export const FLOW_AUTOSAVE_DELAY = 800
+
+/**
+ * @param flow        the flow to edit (omit for a new one)
+ * @param name        name for a new flow
+ * @param screens     [{ id, name }] — the published screens a step can show
+ * @param loadScreen  async (id) → the screen document, so a condition can offer its fields
+ * @param onSave      async (flow) → void — called after edits, only with a flow that makes sense
+ * @param onPublish   async (key) → void — shows a Publish button
+ * @param onChange    (flow) → void — every edit
+ */
+export function useFlowBuilder({ flow: given, name, screens = [], loadScreen, onSave, onPublish, onChange } = {}) {
+  const [flow, setFlow] = useState(() => given || createFlow({ name }))
+  const [selected, setSelected] = useState(null)          // a step key
+  const [dirty, setDirty] = useState(false)
+  const [saving, setSaving] = useState(false)
+  const [saveError, setSaveError] = useState(null)
+  const [publishing, setPublishing] = useState(false)
+  const [publishResult, setPublishResult] = useState(null)
+
+  // A flow handed in from outside replaces what is being edited only when it
+  // is a different flow — otherwise a re-render would undo what was typed.
+  const givenKey = given && given.key
+  useEffect(() => { if (given) { setFlow(given); setDirty(false) } }, [givenKey])   // eslint-disable-line react-hooks/exhaustive-deps
+
+  const live = useRef({})
+  live.current = { flow, onSave, onChange }
+
+  const check = useMemo(() => validateFlow(flow, { screens: screens.map((s) => s.id) }), [flow, screens])
+  const errorsByStep = useMemo(() => {
+    const out = {}
+    check.errors.forEach((e) => {
+      const m = /^steps\[(\d+)\]/.exec(e.path || '')
+      if (!m) return
+      const step = flow.steps[Number(m[1])]
+      if (!step) return
+      out[step.stepKey] = [...(out[step.stepKey] || []), e]
+    })
+    return out
+  }, [check, flow])
+
+  // ── the fields a condition can test ───────────────────────────────────
+  // A condition reads what the person filled in on THAT step's screen, so the
+  // designer offers exactly those fields, by name, with their labels.
+  const [fields, setFields] = useState({})                // screen id → [{ name, label }]
+  const loadRef = useRef(loadScreen); loadRef.current = loadScreen
+  useEffect(() => {
+    const wanted = [...new Set(flow.steps.map((s) => s.screen).filter(Boolean))]
+    const missing = wanted.filter((id) => !fields[id])
+    if (!missing.length || !loadRef.current) return undefined
+    let cancelled = false
+    Promise.all(missing.map((id) => Promise.resolve()
+      .then(() => loadRef.current(id))
+      .then((doc) => [id, inputNodes(doc).map((n) => ({ name: n.props.name, label: n.props.label || n.props.name }))])
+      .catch(() => [id, []])))
+      .then((pairs) => { if (!cancelled) setFields((f) => ({ ...f, ...Object.fromEntries(pairs) })) })
+    return () => { cancelled = true }
+  }, [flow.steps, fields])
+
+  /** The fields of the screen a step shows — what its arrows can test. */
+  const fieldsFor = useCallback((stepKey) => {
+    const step = flow.steps.find((s) => s.stepKey === stepKey)
+    return (step && fields[step.screen]) || []
+  }, [flow, fields])
+
+  // ── edits ─────────────────────────────────────────────────────────────
+  const update = useCallback((fn) => {
+    setFlow((f) => {
+      const next = fn(f)
+      if (next === f) return f
+      live.current.flow = next
+      setDirty(true)
+      if (live.current.onChange) live.current.onChange(next)
+      return next
+    })
+  }, [])
+
+  const rename = useCallback((value) => update((f) => ({ ...f, name: value })), [update])
+  const screensRef = useRef(screens); screensRef.current = screens
+  const add = useCallback((screen, at) => {
+    let added = null
+    const known = screensRef.current.find((x) => x.id === screen)
+    update((f) => {
+      const r = addStep(f, screen, { at, label: known && known.name ? known.name : undefined })
+      added = r.step
+      return r.flow
+    })
+    if (added) setSelected(added.stepKey)
+    return added
+  }, [update])
+  const move = useCallback((stepKey, at) => update((f) => moveStep(f, stepKey, at)), [update])
+  const change = useCallback((stepKey, patch) => update((f) => setStep(f, stepKey, patch)), [update])
+  const remove = useCallback((stepKey) => {
+    update((f) => removeStep(f, stepKey))
+    setSelected((s) => (s === stepKey ? null : s))
+  }, [update])
+  const connect = useCallback((fromKey, target, when = null) => update((f) => addTransition(f, fromKey, target, when)), [update])
+  const changeTransition = useCallback((fromKey, index, patch) => update((f) => setTransition(f, fromKey, index, patch)), [update])
+  const disconnect = useCallback((fromKey, index) => update((f) => removeTransition(f, fromKey, index)), [update])
+  /** Lays every step out by where it falls in the journey. */
+  const tidy = useCallback(() => update((f) => layoutFlow(f)), [update])
+
+  // ── saving ────────────────────────────────────────────────────────────
+  const timer = useRef(null)
+  useEffect(() => {
+    if (!dirty || !onSave) return undefined
+    clearTimeout(timer.current)
+    timer.current = setTimeout(() => {
+      const f = live.current.flow
+      if (!validateFlow(f, { screens: screens.map((s) => s.id) }).ok) return       // saved once it makes sense
+      setSaving(true)
+      setSaveError(null)
+      Promise.resolve()
+        .then(() => live.current.onSave(f))
+        .then(() => { setDirty(false) })
+        .catch((err) => setSaveError(err.message || 'Could not save'))
+        .finally(() => setSaving(false))
+    }, FLOW_AUTOSAVE_DELAY)
+    return () => clearTimeout(timer.current)
+  }, [flow, dirty, onSave, screens])
+
+  const publish = useCallback(async () => {
+    if (!onPublish) return
+    setPublishing(true)
+    setPublishResult(null)
+    try {
+      clearTimeout(timer.current)
+      if (dirty && onSave) await onSave(live.current.flow)
+      await onPublish(live.current.flow.key)
+      setDirty(false)
+      setPublishResult({ ok: true, message: 'Published — people can walk through it now' })
+    } catch (err) {
+      setPublishResult({ ok: false, message: err.message || 'Could not publish' })
+    } finally {
+      setPublishing(false)
+    }
+  }, [onPublish, onSave, dirty])
+
+  const status = saveError ? 'error' : saving ? 'saving' : dirty ? (check.ok ? 'pending' : 'invalid') : 'saved'
+
+  return {
+    flow,
+    screens,
+    selected,
+    setSelected,
+    selectedStep: flow.steps.find((s) => s.stepKey === selected) || null,
+    first: firstStep(flow),
+    validation: check,
+    errorsByStep,
+    fieldsFor,
+    rename,
+    addStep: add,
+    moveStep: move,
+    setStep: change,
+    removeStep: remove,
+    connect,
+    setTransition: changeTransition,
+    disconnect,
+    tidy,
+    end: FLOW_END,
+    status,
+    saving,
+    saveError,
+    dirty,
+    canPublish: Boolean(onPublish),
+    publish,
+    publishing,
+    publishResult,
+    clearPublishResult: () => setPublishResult(null)
+  }
+}

package/src/useFlowRun.js

@@ -0,0 +1,86 @@
+import { useCallback, useEffect, useRef, useState } from 'react'
+
+// RUNNING a flow: one screen at a time, and the run decides which.
+//
+// The browser holds no route through the journey. It asks the run what to
+// show, renders that screen, and when the person is finished with it sends
+// the values back — the engine tests the arrows leaving that step and answers
+// with the next screen, or that the journey is done.
+//
+// The record itself is saved the ordinary way, by the screen, into its own
+// table. What travels with the run is only what the arrows need to decide,
+// plus the id of the row that was written.
+
+/**
+ * @param flowKey    which flow to run (starting one, or picking up a run)
+ * @param runId      an existing run to continue — omit to start one
+ * @param startRun   async (flowKey) → { runId, status, stepKey, screen }
+ * @param loadRun    async (runId) → { runId, status, stepKey, screen, values }
+ * @param submitRun  async (runId, values, recordId) → { status, stepKey, screen }
+ * @param loadScreen async (key) → the screen document
+ * @param onStep     (step) → void — told each time the run moves, for the address bar
+ * @param onFinish   (run) → void — the journey is over
+ */
+export function useFlowRun({ flowKey, runId, startRun, loadRun, submitRun, loadScreen, onStep, onFinish } = {}) {
+  const [state, setState] = useState({ loading: true, error: null, runId: runId || null, status: null, stepKey: null, screen: null, document: null, values: null })
+  const [sending, setSending] = useState(false)
+  const live = useRef({})
+  live.current = { startRun, loadRun, submitRun, loadScreen, onStep, onFinish, flowKey }
+
+  /** A step the run reports → the screen to draw. */
+  const open = useCallback(async (run) => {
+    if (!run) throw new Error('The run said nothing about what to show')
+    if (run.status === 'done' || !run.screen) {
+      setState((s) => ({ ...s, loading: false, error: null, runId: run.runId || s.runId, status: 'done', stepKey: null, screen: null, document: null }))
+      if (live.current.onFinish) live.current.onFinish(run)
+      return
+    }
+    if (!live.current.loadScreen) throw new Error('No loadScreen was provided, so the flow cannot show "' + run.screen + '"')
+    const doc = await live.current.loadScreen(run.screen)
+    setState({
+      loading: false, error: null,
+      runId: run.runId, status: run.status || 'running', stepKey: run.stepKey, screen: run.screen,
+      document: doc, values: run.values || null
+    })
+    if (live.current.onStep) live.current.onStep(run)
+  }, [])
+
+  // Start, or pick up where a run got to.
+  useEffect(() => {
+    let cancelled = false
+    setState((s) => ({ ...s, loading: true, error: null }))
+    const begin = async () => {
+      if (runId) {
+        if (!live.current.loadRun) throw new Error('No loadRun was provided')
+        return live.current.loadRun(runId)
+      }
+      if (!live.current.startRun) throw new Error('No startRun was provided')
+      return live.current.startRun(live.current.flowKey)
+    }
+    begin()
+      .then((run) => { if (!cancelled) return open(run) })
+      .catch((err) => { if (!cancelled) setState((s) => ({ ...s, loading: false, error: err.message || 'The flow could not be opened' })) })
+    return () => { cancelled = true }
+  }, [flowKey, runId, open])
+
+  /**
+   * Done with this screen. The values go to the run, which decides what comes
+   * next; `recordId` is the row the screen just saved, so later steps and
+   * their arrows can refer to it.
+   */
+  const submit = useCallback(async (values, recordId) => {
+    if (!live.current.submitRun) throw new Error('No submitRun was provided')
+    setSending(true)
+    try {
+      const next = await live.current.submitRun(state.runId, values || {}, recordId)
+      await open({ runId: state.runId, ...next })
+    } catch (err) {
+      setState((s) => ({ ...s, error: err.message || 'That could not be sent' }))
+      throw err
+    } finally {
+      setSending(false)
+    }
+  }, [state.runId, open])
+
+  return { ...state, sending, submit }
+}