@xeplr/ui-factory 1.0.11 → 1.0.13

package/src/flow.js

@@ -0,0 +1,318 @@
+// A FLOW — screens, one after another, and what decides which comes next.
+//
+// A screen is a form; a flow is the journey across several of them. Each step
+// shows one screen, and the arrows leaving it say where to go once it is
+// filled in: the first arrow whose test passes, and failing all of them, the
+// one with no test — "otherwise". A step with no arrows ends the journey.
+//
+// Pure data, like controls.js: no React, no requests. The designer edits this
+// shape, the server is handed the same shape, and both sides check it with
+// validateFlow().
+//
+//   { kind: 'xeplr-flow', version: 1, key: 'employee_registration',
+//     name: 'Employee registration',
+//     steps: [
+//       { stepKey: 'details', screen: 'employee_edit', label: 'Details',
+//         layout: { x: 40, y: 40 },
+//         transitions: [
+//           { when: { field: 'type', op: '=', value: 'contractor' }, target: 'contract' },
+//           { when: null, target: 'payroll' }
+//         ] },
+//       …
+//     ] }
+//
+// WHO RUNS IT: the workflow engine, not the browser. A run remembers where it
+// got to, so a journey can be left and picked up later — by someone else, on
+// another day. The browser only shows the screen it is told to and sends back
+// what was typed.
+
+export const FLOW_KIND = 'xeplr-flow'
+export const FLOW_VERSION = 1
+
+/** Where a journey can end, instead of another step — the engine's own word for a journey that finished. */
+export const FLOW_END = 'end_success'
+
+/**
+ * The tests an arrow can carry, spelled the way the workflow engine accepts
+ * them. One comparison per arrow; more than one is more steps.
+ */
+export const FLOW_OPERATORS = [
+  { op: '=', label: 'is' },
+  { op: '!=', label: 'is not' },
+  { op: '>', label: 'is more than' },
+  { op: '>=', label: 'is at least' },
+  { op: '<', label: 'is less than' },
+  { op: '<=', label: 'is at most' },
+  { op: 'contains', label: 'contains' },
+  { op: 'notContains', label: 'does not contain' },
+  { op: 'startsWith', label: 'starts with' },
+  { op: 'endsWith', label: 'ends with' },
+  { op: 'isEmpty', label: 'is empty' },
+  { op: 'isNotEmpty', label: 'is not empty' }
+]
+
+/** The comparisons that need no value typed beside them. */
+export const VALUELESS_OPERATORS = ['isEmpty', 'isNotEmpty']
+
+const KEY = /^[A-Za-z][A-Za-z0-9_]*$/
+const MAX_KEY = 63
+
+/** An empty flow, ready to have screens dropped on it. */
+export function createFlow({ key, name } = {}) {
+  const flowName = name || 'New flow'
+  return {
+    kind: FLOW_KIND,
+    version: FLOW_VERSION,
+    key: key || flowKey(flowName),
+    name: flowName,
+    steps: []
+  }
+}
+
+/** "Employee registration" → "employee_registration". */
+export function flowKey(name) {
+  const out = String(name || '')
+    .normalize('NFKD').replace(/[̀-ͯ]/g, '')
+    .replace(/[^A-Za-z0-9]+/g, '_')
+    .replace(/^_+|_+$/g, '')
+    .toLowerCase()
+    .slice(0, MAX_KEY)
+  return KEY.test(out) ? out : 'flow_' + out.replace(/^[^A-Za-z]+/, '')
+}
+
+/** Adds a step showing `screen`, at `at` (canvas pixels). Returns { flow, step }. */
+export function addStep(flow, screen, { at, label, stepKey } = {}) {
+  const base = stepKey || uniqueStepKey(flow, flowKey(screen))
+  const step = {
+    stepKey: base,
+    screen,
+    label: label || screen,
+    layout: { x: Math.round((at && at.x) || 40), y: Math.round((at && at.y) || 40) },
+    transitions: []
+  }
+  const steps = [...flow.steps, step]
+  // The step before it, if it ended the journey, now leads here: dropping a
+  // second screen on an empty canvas means "and then this one".
+  const previous = flow.steps[flow.steps.length - 1]
+  if (previous && !previous.transitions.length) {
+    return { flow: { ...flow, steps: steps.map((s) => (s.stepKey === previous.stepKey ? { ...s, transitions: [{ when: null, target: step.stepKey }] } : s)) }, step }
+  }
+  return { flow: { ...flow, steps }, step }
+}
+
+/** A step key nothing else in the flow is using. */
+export function uniqueStepKey(flow, base) {
+  const taken = new Set(flow.steps.map((s) => s.stepKey))
+  const stem = KEY.test(base) ? base : 'step'
+  if (!taken.has(stem)) return stem
+  let n = 2
+  while (taken.has(`${stem}_${n}`)) n++
+  return `${stem}_${n}`
+}
+
+/** Moves a step on the canvas. */
+export function moveStep(flow, stepKey, at) {
+  return mapStep(flow, stepKey, (s) => ({ ...s, layout: { x: Math.round(at.x), y: Math.round(at.y) } }))
+}
+
+/** Changes one thing about a step — its screen, its label. */
+export function setStep(flow, stepKey, patch) {
+  return mapStep(flow, stepKey, (s) => ({ ...s, ...patch }))
+}
+
+/** Removes a step, and every arrow pointing at it. */
+export function removeStep(flow, stepKey) {
+  return {
+    ...flow,
+    steps: flow.steps
+      .filter((s) => s.stepKey !== stepKey)
+      .map((s) => ({ ...s, transitions: s.transitions.filter((t) => t.target !== stepKey) }))
+  }
+}
+
+/**
+ * Draws an arrow from one step to another (or to the end). A step's LAST
+ * arrow is the one with no test — "otherwise" — so a new arrow goes in front
+ * of it and the flow always has somewhere to go.
+ */
+export function addTransition(flow, fromKey, target, when = null) {
+  return mapStep(flow, fromKey, (s) => {
+    const rest = s.transitions.filter((t) => t.when !== null)
+    const otherwise = s.transitions.find((t) => t.when === null)
+    const next = when === null
+      ? [...rest, { when: null, target }]
+      : [...rest, { when, target }, ...(otherwise ? [otherwise] : [])]
+    return { ...s, transitions: next }
+  })
+}
+
+/** Changes one arrow of a step, by its position. */
+export function setTransition(flow, fromKey, index, patch) {
+  return mapStep(flow, fromKey, (s) => ({
+    ...s,
+    transitions: s.transitions.map((t, i) => (i === index ? { ...t, ...patch } : t))
+  }))
+}
+
+/** Removes one arrow of a step, by its position. */
+export function removeTransition(flow, fromKey, index) {
+  return mapStep(flow, fromKey, (s) => ({ ...s, transitions: s.transitions.filter((_, i) => i !== index) }))
+}
+
+/** The step a journey starts at: the first one that nothing else points to, else the first. */
+export function firstStep(flow) {
+  if (!flow.steps.length) return null
+  const pointedAt = new Set(flow.steps.flatMap((s) => s.transitions.map((t) => t.target)))
+  return flow.steps.find((s) => !pointedAt.has(s.stepKey)) || flow.steps[0]
+}
+
+/** Every step that can be reached from the first one. */
+export function reachableSteps(flow) {
+  const start = firstStep(flow)
+  if (!start) return new Set()
+  const byKey = new Map(flow.steps.map((s) => [s.stepKey, s]))
+  const seen = new Set()
+  const walk = (key) => {
+    if (!key || key === FLOW_END || seen.has(key)) return
+    const step = byKey.get(key)
+    if (!step) return
+    seen.add(key)
+    step.transitions.forEach((t) => walk(t.target))
+  }
+  walk(start.stepKey)
+  return seen
+}
+
+/**
+ * Lays the steps out as the journey reads: the first on the left, each step
+ * one column right of the step that leads to it, and the branches of one step
+ * stacked in the same column — so an arrow runs forward and never crosses a
+ * card to reach the one it means.
+ * @param size  { w, h, gapX, gapY, left, top } in pixels
+ */
+export function layoutFlow(flow, size = {}) {
+  const { w = 200, h = 86, gapX = 110, gapY = 50, left = 60, top = 60 } = size
+  const start = firstStep(flow)
+  if (!start) return flow
+  const byKey = new Map(flow.steps.map((s) => [s.stepKey, s]))
+  const depth = new Map([[start.stepKey, 0]])
+  const queue = [start.stepKey]
+  while (queue.length) {
+    const key = queue.shift()
+    ;(byKey.get(key).transitions || []).forEach((t) => {
+      if (!byKey.has(t.target) || depth.has(t.target)) return
+      depth.set(t.target, depth.get(key) + 1)
+      queue.push(t.target)
+    })
+  }
+  // Steps nothing reaches go in a column of their own at the end, where they
+  // are easy to see and to connect.
+  const deepest = Math.max(0, ...depth.values())
+  flow.steps.forEach((s) => { if (!depth.has(s.stepKey)) depth.set(s.stepKey, deepest + 1) })
+  const rows = new Map()
+  return {
+    ...flow,
+    steps: flow.steps.map((s) => {
+      const d = depth.get(s.stepKey)
+      const row = rows.get(d) || 0
+      rows.set(d, row + 1)
+      return { ...s, layout: { x: left + d * (w + gapX), y: top + row * (h + gapY) } }
+    })
+  }
+}
+
+/**
+ * What is wrong with this flow, in the words of the person drawing it.
+ * @param options.screens  the screen keys that exist, so a step cannot point at one that does not
+ * @returns {{ ok, errors: [{ path, message }] }}
+ */
+export function validateFlow(flow, options = {}) {
+  const errors = []
+  const err = (path, message) => errors.push({ path, message })
+
+  if (!flow || typeof flow !== 'object' || Array.isArray(flow)) {
+    err('', 'A flow must be an object')
+    return { ok: false, errors }
+  }
+  if (flow.kind !== FLOW_KIND) err('kind', `must be "${FLOW_KIND}"`)
+  if (flow.version !== FLOW_VERSION) err('version', `must be ${FLOW_VERSION}`)
+  if (!KEY.test(String(flow.key || ''))) err('key', 'must start with a letter and contain only letters, digits and _')
+  else if (String(flow.key).length > MAX_KEY) err('key', `is longer than ${MAX_KEY} characters`)
+  if (!String(flow.name || '').trim()) err('name', 'is required — what this journey is called')
+  if (!Array.isArray(flow.steps)) {
+    err('steps', 'must be an array of steps')
+    return { ok: false, errors }
+  }
+  if (!flow.steps.length) err('steps', 'a flow needs at least one screen')
+
+  const keys = new Map()
+  const screens = options.screens ? new Set(options.screens) : null
+
+  flow.steps.forEach((step, i) => {
+    const at = `steps[${i}]`
+    if (!step || typeof step !== 'object') { err(at, 'must be an object'); return }
+    if (!KEY.test(String(step.stepKey || ''))) err(`${at}.stepKey`, 'must start with a letter and contain only letters, digits and _')
+    else if (keys.has(step.stepKey)) err(`${at}.stepKey`, `"${step.stepKey}" is already used by steps[${keys.get(step.stepKey)}]`)
+    else keys.set(step.stepKey, i)
+    if (!String(step.screen || '').trim()) err(`${at}.screen`, 'must name the screen this step shows')
+    else if (screens && !screens.has(step.screen)) err(`${at}.screen`, `"${step.screen}" is not a published screen`)
+    if (step.layout && (!Number.isFinite(step.layout.x) || !Number.isFinite(step.layout.y))) {
+      err(`${at}.layout`, 'must be { x, y } in pixels')
+    }
+    if (!Array.isArray(step.transitions)) { err(`${at}.transitions`, 'must be an array'); return }
+    let otherwiseAt = -1
+    step.transitions.forEach((t, j) => {
+      const tp = `${at}.transitions[${j}]`
+      if (!t || typeof t !== 'object') { err(tp, 'must be { when, target }'); return }
+      if (!String(t.target || '').trim()) err(`${tp}.target`, `must name the step this arrow goes to, or "${FLOW_END}"`)
+      if (t.when === null || t.when === undefined) {
+        if (otherwiseAt !== -1) err(tp, 'a step can have only one "otherwise" — the others need a test')
+        otherwiseAt = j
+      } else {
+        checkWhen(t.when, tp, err)
+        if (otherwiseAt !== -1) err(tp, '"otherwise" must be the last arrow, or the ones after it are never tried')
+      }
+    })
+  })
+
+  // Targets are checked once every step key is known.
+  flow.steps.forEach((step, i) => {
+    ;(step.transitions || []).forEach((t, j) => {
+      const target = t && t.target
+      if (!target || target === FLOW_END) return
+      if (!keys.has(target)) err(`steps[${i}].transitions[${j}].target`, `"${target}" is not a step of this flow`)
+    })
+  })
+
+  const reachable = reachableSteps(flow)
+  flow.steps.forEach((step, i) => {
+    if (step && step.stepKey && !reachable.has(step.stepKey)) {
+      err(`steps[${i}]`, `nothing leads to "${step.label || step.stepKey}" — draw an arrow to it, or remove it`)
+    }
+  })
+
+  return { ok: errors.length === 0, errors }
+}
+
+function checkWhen(when, at, err) {
+  if (typeof when !== 'object' || Array.isArray(when)) { err(at + '.when', 'must be { field, op, value }'); return }
+  if (!String(when.field || '').trim()) err(`${at}.when.field`, 'must name a field of the screen this step shows')
+  const known = FLOW_OPERATORS.some((o) => o.op === when.op)
+  if (!known) err(`${at}.when.op`, `must be one of: ${FLOW_OPERATORS.map((o) => o.op).join(', ')}`)
+  if (known && !VALUELESS_OPERATORS.includes(when.op) && (when.value === undefined || when.value === null || when.value === '')) {
+    err(`${at}.when.value`, 'needs a value to compare with')
+  }
+}
+
+/** A test in words: "Type is contractor". */
+export function describeWhen(when, fieldLabel) {
+  if (!when) return 'otherwise'
+  const op = FLOW_OPERATORS.find((o) => o.op === when.op)
+  const name = fieldLabel || when.field
+  if (VALUELESS_OPERATORS.includes(when.op)) return `${name} ${op ? op.label : when.op}`
+  return `${name} ${op ? op.label : when.op} ${when.value}`
+}
+
+function mapStep(flow, stepKey, fn) {
+  return { ...flow, steps: flow.steps.map((s) => (s.stepKey === stepKey ? fn(s) : s)) }
+}

package/src/flows.js

@@ -0,0 +1,112 @@
+// The browser side of FLOWS: designing a chain of screens, and running one.
+//
+// The factory does not run a flow — the app's workflow service does, which is
+// why every call here goes to endpoints the app supplies. A run remembers
+// where it got to, so a journey can be left and picked up later; the browser
+// only asks "what should this person see now" and sends back what was typed.
+//
+//   import { authFetch } from '@xeplr/ui-account'
+//   const flows = createFlowsApi({ fetch: authFetch, base: '/api' })
+//   <FlowRunner {...flows.runnerProps} flowKey="employee_registration" />
+//
+// Answers may come as xeplr's { code, message, dataArray } or as the plain
+// object or list itself — the workflow service speaks the second. Both are read
+// the same way (payload()), so a client never cares which service it is talking to.
+
+import { FLOW_KIND, FLOW_VERSION } from './flow.js'
+
+/**
+ * A flow as the server sends it → the document the designer edits. The server
+ * stores steps, not the document's envelope, so the envelope is put back here
+ * and a step with no label is named after its screen.
+ */
+export function asFlow(row) {
+  if (!row) return row
+  return {
+    kind: FLOW_KIND,
+    version: FLOW_VERSION,
+    key: row.key,
+    name: row.name,
+    status: row.status,
+    // A list or a publish answer counts the steps rather than listing them.
+    ...(Array.isArray(row.steps) ? {} : { stepCount: Number(row.steps) || 0 }),
+    steps: (Array.isArray(row.steps) ? row.steps : []).map((s) => ({
+      stepKey: s.stepKey,
+      screen: s.screen,
+      label: s.label || s.screen,
+      layout: s.layout || { x: 40, y: 40 },
+      transitions: s.transitions || []
+    }))
+  }
+}
+
+/**
+ * @param options.fetch  a fetch that adds auth and tenant headers (authFetch)
+ * @param options.base   prefix before /flows (default '')
+ */
+export function createFlowsApi({ fetch: doFetch, base = '' } = {}) {
+  if (typeof doFetch !== 'function') throw new Error('createFlowsApi: pass { fetch } — usually authFetch from @xeplr/ui-account')
+
+  async function call(method, path, body) {
+    let res
+    try {
+      res = await doFetch(`${base}/flows${path}`, {
+        method,
+        headers: body === undefined ? undefined : { 'Content-Type': 'application/json' },
+        body: body === undefined ? undefined : JSON.stringify(body)
+      })
+    } catch (err) {
+      if (err && err.body !== undefined && err.status) throw failure(method, path, err.status, err.body, err.message)
+      throw err
+    }
+    if (res && typeof res.json === 'function' && typeof res.ok === 'boolean') {
+      let json = null
+      try { json = await res.json() } catch (_) { /* not JSON — reported below */ }
+      if (!res.ok) throw failure(method, path, res.status, json)
+      return payload(json)
+    }
+    return payload(res)
+  }
+
+  /** The payload, enveloped or not. */
+  function payload(json) {
+    if (json === null || json === undefined) return []
+    if (typeof json === 'object' && !Array.isArray(json) && Array.isArray(json.dataArray)) return json.dataArray
+    return json
+  }
+
+  function failure(method, path, status, json, fallback) {
+    const err = new Error((json && json.message) || fallback || `${method} ${path} failed (${status})`)
+    err.status = status
+    err.fields = json && json.error && json.error.fields
+    err.code = json && json.code
+    return err
+  }
+  const one = (rows) => (Array.isArray(rows) ? rows[0] : rows)
+  const enc = encodeURIComponent
+
+  const api = {
+    // designing
+    listFlows: () => call('GET', ''),
+    createFlow: async (spec) => asFlow(one(await call('POST', '', spec))),
+    loadFlow: async (key) => asFlow(one(await call('GET', `/${enc(key)}`))),
+    saveFlow: async (flow) => asFlow(one(await call('PUT', `/${enc(flow.key)}`, {
+      name: flow.name,
+      steps: flow.steps.map((s) => ({ stepKey: s.stepKey, label: s.label, screen: s.screen, layout: s.layout, transitions: s.transitions }))
+    }))),
+    // Answers with the flow's status, not its steps — nothing to rebuild from it.
+    publishFlow: async (key) => one(await call('POST', `/${enc(key)}/publish`)),
+
+    // running
+    startRun: async (key) => one(await call('POST', `/${enc(key)}/runs`)),
+    loadRun: async (runId) => one(await call('GET', `/runs/${enc(runId)}`)),
+    /** What the person filled in. Answers with the next screen, or that it is done. */
+    submitRun: async (runId, values, recordId) => one(await call('POST', `/runs/${enc(runId)}/submit`, { values, recordId })),
+    /** Journeys of this flow that are still going — "in progress". */
+    myRuns: (key) => call('GET', `/${enc(key)}/runs?mine=1`)
+  }
+
+  api.builderProps = { listFlows: api.listFlows, loadFlow: api.loadFlow, onSave: api.saveFlow, onPublish: api.publishFlow, onCreate: api.createFlow }
+  api.runnerProps = { startRun: api.startRun, loadRun: api.loadRun, submitRun: api.submitRun, myRuns: api.myRuns }
+  return api
+}

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/index.js

@@ -11,12 +11,14 @@ export * from './model.js'
 // Controllers
 export { useFactoryBuilder } from './useFactoryBuilder.js'
 export { useFactoryScreen, normaliseOptions, AUTOSAVE_DELAY } from './useFactoryScreen.js'
+export { useFlowRun } from './useFlowRun.js'
+export { useFlowBuilder, FLOW_AUTOSAVE_DELAY } from './useFlowBuilder.js'
 
 // Designs
-export { BuilderSample, ScreenSample, ListView, ScreenModal, ControlView, VIEWS, Palette, DRAG_TYPE, PropertyPanel, EDITORS } from './designs/index.js'
+export { BuilderSample, ScreenSample, ListView, ScreenModal, FlowRunnerSample, FlowBuilderSample, ControlView, VIEWS, Palette, DRAG_TYPE, PropertyPanel, EDITORS } from './designs/index.js'
 
 // Front-end hooks — extend FactoryHooks, override what you need, call super
 export { FactoryHooks } from './hooks.js'
 
 // Ready-made
-export { FactoryBuilder, FactoryScreen } from './pages.jsx'
+export { FactoryBuilder, FactoryScreen, FlowRunner, FlowBuilder } from './pages.jsx'

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'
@@ -21,3 +21,9 @@ export {
   columnForField, tableForScreen, columnSql, widening, diffTables, migrationFor, nextMigrationName,
   createStatements, addStatements, alterStatement, dropStatement, columnFromDatabase, planTableChange
 } from './tableSchema.js'
+export { createFlowsApi } from './flows.js'
+export {
+  FLOW_KIND, FLOW_VERSION, FLOW_END, FLOW_OPERATORS, VALUELESS_OPERATORS,
+  createFlow, flowKey, addStep, uniqueStepKey, moveStep, setStep, removeStep,
+  addTransition, setTransition, removeTransition, firstStep, reachableSteps, layoutFlow, validateFlow, describeWhen
+} from './flow.js'

package/src/pages.jsx

@@ -1,6 +1,8 @@
 import { useFactoryBuilder } from './useFactoryBuilder.js'
 import { useFactoryScreen } from './useFactoryScreen.js'
-import { BuilderSample, ScreenSample, ScreenModal } from './designs/index.js'
+import { useFlowRun } from './useFlowRun.js'
+import { useFlowBuilder } from './useFlowBuilder.js'
+import { BuilderSample, ScreenSample, ScreenModal, FlowRunnerSample, FlowBuilderSample } from './designs/index.js'
 
 /**
  * The builder, ready-made. Saves itself — there is no Save button.
@@ -94,3 +96,66 @@ export function FactoryScreen(props) {
     />
   )
 }
+
+/**
+ * A FLOW, running: one screen at a time, and the run decides which comes next.
+ *
+ * The journey is not in this page. It asks the run what to show, renders that
+ * screen — which saves itself into its own table, as anywhere else — and hands
+ * back what was filled in; the arrows leaving that step decide the rest.
+ *
+ * @prop flowKey    the flow to start
+ * @prop runId      a run to pick up instead of starting one
+ * @prop startRun   async (flowKey) → { runId, status, stepKey, screen }
+ * @prop loadRun    async (runId) → { runId, status, stepKey, screen, values }
+ * @prop submitRun  async (runId, values, recordId) → { status, stepKey, screen }
+ * @prop onStep     (step) → void — each move, for the address bar
+ * @prop onFinish   (run) → void — the journey is over
+ * @prop renderDone what to show at the end (default: a plain "All done")
+ * Everything a screen needs — loadScreen, onSave, fetchOptions, uploadFile… —
+ * is passed straight through, so `{...factory.screenProps}` covers it.
+ */
+export function FlowRunner(props) {
+  const run = useFlowRun(props)
+  const screen = useFactoryScreen({
+    ...props,
+    document: run.document || EMPTY_SCREEN,
+    record: run.values || undefined
+  })
+  return (
+    <FlowRunnerSample
+      run={run}
+      screen={screen}
+      title={props.title}
+      renderDone={props.renderDone}
+      className={props.className}
+      style={props.style}
+    />
+  )
+}
+
+// A screen the runner can hold before the run has said what to show. Valid, so
+// the controller has nothing to complain about, and never drawn.
+const EMPTY_SCREEN = {
+  kind: 'xeplr-screen', version: 1, id: 'flow_waiting', name: 'Waiting',
+  units: 'fraction', aspect: 1, width: 800, nodes: []
+}
+
+/**
+ * The FLOW designer, ready-made: screens on a canvas, arrows between them.
+ *
+ * Saves itself once what is drawn makes sense; Publish is deliberate, because
+ * a published flow is what people walk through.
+ *
+ * @prop flow       the flow to edit (omit for a new one)
+ * @prop name       name for a new flow
+ * @prop screens    [{ id, name }] — the published screens a step can show
+ * @prop loadScreen async (id) → the screen document, so an arrow can offer its fields
+ * @prop onSave     async (flow) → void
+ * @prop onPublish  async (key) → void
+ * @prop onChange   (flow) → void
+ */
+export function FlowBuilder(props) {
+  const ctrl = useFlowBuilder(props)
+  return <FlowBuilderSample ctrl={ctrl} className={props.className} style={props.style} />
+}