@xeplr/ui-factory 1.0.11 → 1.0.13

package/README.md

@@ -178,6 +178,55 @@ import schemaHandler from '@xeplr/schema-handler'          // CommonJS: default
 const clean = schemaHandler.applySchema(formSchema(screen), req.body)   // throws ValidationError listing each field
 ```
 
+## Flows — screens, one after another
+
+A screen is a form; a **flow** is the journey across several of them. Design it
+the same way you design a form — screens on a canvas, arrows between them:
+
+```jsx
+import { FlowBuilder, FlowRunner, createFlowsApi } from '@xeplr/ui-factory'
+const flows = createFlowsApi({ fetch: authFetch, base: '/api' })
+
+<FlowBuilder {...flows.builderProps} flow={flow} screens={published} loadScreen={factory.loadScreen} />
+<FlowRunner  {...flows.runnerProps} {...factory.screenProps} flowKey="employee_registration" runId={runId} />
+```
+
+An arrow is a question asked once its screen is filled in — the first one that
+fits wins, and the one with no test ("otherwise") catches the rest:
+
+```json
+{ "stepKey": "details", "screen": "employee_edit",
+  "transitions": [
+    { "when": { "field": "type", "op": "=", "value": "contractor" }, "target": "contract" },
+    { "when": null, "target": "payroll" }
+  ] }
+```
+
+**The browser does not run the journey.** `createFlowsApi` talks to a service
+that does — Xeplr Workflow — so a run remembers where it got to: a journey can
+be left and picked up later, by someone else, on another day. Without such a
+service there are no flows; the factory has no engine of its own, on purpose.
+
+**Each screen still saves itself, into its own table.** What travels with the
+run is only what the arrows need and the id of the row that was written
+(`recordId`), so the data is exactly where it would be without a flow.
+
+`validateFlow(flow, { screens })` is the same check on both sides: a screen
+that exists, arrows that point somewhere, one "otherwise" at the end, and
+nothing unreachable.
+
+### A flow and a stepper
+
+Both walk someone through something, and they answer different questions:
+
+| | stepper | flow |
+|---|---|---|
+| where | steps of ONE screen | several screens |
+| when | one sitting | over days, if need be |
+| who | one person | can change hands |
+| decides | a `step` hook, in the browser | the engine, on the server |
+| needs | nothing | a workflow service |
+
 ## Controls
 
 | type | value | validation |
@@ -235,6 +284,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.13",
   "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/FlowBuilderSample.jsx

@@ -0,0 +1,274 @@
+import { XeplrCanvas } from '@xeplr/ui-canvas'
+import { FLOW_END, FLOW_OPERATORS, VALUELESS_OPERATORS, describeWhen } from '../flow.js'
+
+// THE FLOW DESIGNER — screens on a canvas, arrows between them.
+//
+// A box is a screen. An arrow leaving it is a question asked once the screen
+// is filled in: the first arrow whose test passes wins, and the one with no
+// test — "otherwise" — catches the rest. That is the whole language, and it is
+// the same one the engine runs.
+//
+// Presentation only: everything comes from useFlowBuilder.
+
+const STEP_W = 200
+const STEP_H = 86
+
+const STATUS = {
+  saved: 'All changes saved',
+  pending: 'Unsaved changes…',
+  saving: 'Saving…',
+  invalid: 'Not saved — finish the flow first',
+  error: 'Not saved'
+}
+
+export default function FlowBuilderSample({ ctrl, className, style }) {
+  const { flow } = ctrl
+  const items = flow.steps.map((s) => ({
+    id: s.stepKey,
+    x: (s.layout && s.layout.x) || 40,
+    y: (s.layout && s.layout.y) || 40,
+    w: STEP_W,
+    h: STEP_H
+  }))
+  // One arrow per transition. A step that ends the journey gets a stub to a
+  // "Finished" pill, the way the workflow editor draws its ends.
+  const edges = flow.steps.flatMap((s) => s.transitions.map((t, i) => ({
+    id: `${s.stepKey}-${i}`,
+    from: s.stepKey,
+    ...(t.target === FLOW_END || !flow.steps.some((x) => x.stepKey === t.target)
+      ? { toOffset: { x: 90, y: 0 }, done: true }
+      : { to: t.target }),
+    variant: t.when ? undefined : 'dashed',
+    label: describeWhen(t.when, labelOf(ctrl, s.stepKey, t.when))
+  })))
+
+  return (
+    <div className={'xeplr-factory-flow-builder' + (className ? ' ' + className : '')} style={style}>
+      <header className="xeplr-factory-bar">
+        <input
+          className="xeplr-factory-name"
+          value={flow.name}
+          onChange={(e) => ctrl.rename(e.target.value)}
+          placeholder="What is this journey called?"
+          aria-label="Flow name"
+        />
+        <code className="xeplr-factory-flow-key" title="The key this flow is known by — it never changes">{flow.key}</code>
+        <div className={`xeplr-factory-bar-status xeplr-factory-bar-status--${ctrl.status}`} role="status" aria-live="polite">
+          {ctrl.status === 'error' ? `Not saved — ${ctrl.saveError}` : STATUS[ctrl.status]}
+        </div>
+        {ctrl.validation.errors.length > 0 && (
+          <span className="xeplr-factory-problems" title={ctrl.validation.errors.map((x) => `${x.path}: ${x.message}`).join('\n')}>
+            {ctrl.validation.errors.length} problem{ctrl.validation.errors.length === 1 ? '' : 's'}
+          </span>
+        )}
+        {flow.steps.length > 1 && (
+          <button type="button" className="xeplr-factory-secondary" onClick={ctrl.tidy} title="Lay the screens out as the journey reads">Tidy</button>
+        )}
+        {ctrl.canPublish && (
+          <button type="button" className="xeplr-factory-primary" onClick={ctrl.publish} disabled={ctrl.publishing || !ctrl.validation.ok}>
+            {ctrl.publishing ? 'Publishing…' : 'Publish'}
+          </button>
+        )}
+      </header>
+
+      {ctrl.publishResult && (
+        <div className={`xeplr-factory-publish${ctrl.publishResult.ok ? ' is-ok' : ' is-error'}`} role="status">
+          <span>{ctrl.publishResult.message}</span>
+          <button type="button" className="xeplr-factory-icon-button" aria-label="Dismiss" onClick={ctrl.clearPublishResult}>×</button>
+        </div>
+      )}
+
+      <div className="xeplr-factory-body">
+        <aside className="xeplr-factory-palette" aria-label="Screens">
+          <div className="xeplr-factory-palette-group">
+            <h3 className="xeplr-factory-palette-title">Screens</h3>
+            {ctrl.screens.length === 0 && <p className="xeplr-factory-hint">No published forms yet.</p>}
+            {ctrl.screens.map((s) => (
+              <button
+                key={s.id}
+                type="button"
+                className="xeplr-factory-palette-item"
+                onClick={() => ctrl.addStep(s.id, nextPlace(flow))}
+                title={`Add ${s.name || s.id} to the journey`}
+              >
+                {s.name || s.id}
+              </button>
+            ))}
+          </div>
+        </aside>
+
+        <div className="xeplr-factory-stage">
+          <XeplrCanvas
+            className="xeplr-factory-flow-canvas"
+            items={items}
+            edges={edges}
+            features={{ drag: true, snap: true }}
+            selection={ctrl.selected ? [ctrl.selected] : []}
+            onSelectionChange={(ids) => ctrl.setSelected([...ids][0] || null)}
+            onItemChange={(id, patch) => ctrl.moveStep(id, patch)}
+            onItemClick={(id) => ctrl.setSelected(id)}
+            renderItem={(item) => {
+              const step = flow.steps.find((s) => s.stepKey === item.id)
+              if (!step) return null
+              const problems = ctrl.errorsByStep[step.stepKey] || []
+              return (
+                <div className={`xeplr-factory-step-card${ctrl.selected === step.stepKey ? ' is-selected' : ''}${problems.length ? ' has-error' : ''}`}>
+                  <span className="xeplr-factory-step-card-name">{step.label || step.stepKey}</span>
+                  <span className="xeplr-factory-step-card-screen">{screenName(ctrl, step.screen)}</span>
+                  {ctrl.first && ctrl.first.stepKey === step.stepKey && <span className="xeplr-factory-step-card-first">starts here</span>}
+                </div>
+              )
+            }}
+            renderEdgeLabel={(edge, { mid }) => (
+              <span className="xeplr-factory-edge-label" style={{ position: 'absolute', left: mid.x, top: mid.y, transform: 'translate(-50%, -50%)' }}>
+                {edge.done ? 'Finished' : edge.label}
+              </span>
+            )}
+            underlay={flow.steps.length === 0 && (
+              <div className="xeplr-factory-empty">Add a screen from the left to start the journey</div>
+            )}
+          />
+        </div>
+
+        <StepPanel ctrl={ctrl} />
+      </div>
+    </div>
+  )
+}
+
+/** What a step does, and where it goes next. */
+function StepPanel({ ctrl }) {
+  const step = ctrl.selectedStep
+  if (!step) {
+    return (
+      <aside className="xeplr-factory-panel" aria-label="Step">
+        <p className="xeplr-factory-panel-empty">
+          Pick a screen on the canvas to say what happens after it.
+          <br /><br />
+          Each arrow is a question asked once that screen is filled in — the first one that fits wins, and “otherwise” catches the rest.
+        </p>
+      </aside>
+    )
+  }
+  const fields = ctrl.fieldsFor(step.stepKey)
+  const others = ctrl.flow.steps.filter((s) => s.stepKey !== step.stepKey)
+
+  return (
+    <aside className="xeplr-factory-panel" aria-label="Step">
+      <div className="xeplr-factory-panel-head">
+        <span className="xeplr-factory-panel-type">{step.label || step.stepKey}</span>
+        <button type="button" className="xeplr-factory-danger-link" onClick={() => ctrl.removeStep(step.stepKey)}>Remove</button>
+      </div>
+
+      <fieldset className="xeplr-factory-group">
+        <legend>Step</legend>
+        <div className="xeplr-factory-prop">
+          <label className="xeplr-factory-prop-label" htmlFor="xf-step-label">Name</label>
+          <input id="xf-step-label" className="xeplr-factory-prop-input" value={step.label || ''} onChange={(e) => ctrl.setStep(step.stepKey, { label: e.target.value })} />
+        </div>
+        <div className="xeplr-factory-prop">
+          <label className="xeplr-factory-prop-label" htmlFor="xf-step-screen">Shows</label>
+          <select id="xf-step-screen" className="xeplr-factory-prop-input" value={step.screen} onChange={(e) => ctrl.setStep(step.stepKey, { screen: e.target.value })}>
+            {ctrl.screens.map((s) => <option key={s.id} value={s.id}>{s.name || s.id}</option>)}
+          </select>
+        </div>
+      </fieldset>
+
+      <fieldset className="xeplr-factory-group">
+        <legend>Then</legend>
+        {step.transitions.length === 0 && <p className="xeplr-factory-hint">The journey ends here.</p>}
+        {step.transitions.map((t, i) => (
+          <div key={i} className="xeplr-factory-arrow">
+            {t.when === null ? (
+              <span className="xeplr-factory-arrow-when">Otherwise</span>
+            ) : (
+              <div className="xeplr-factory-arrow-test">
+                <select
+                  className="xeplr-factory-prop-input"
+                  value={t.when.field || ''}
+                  onChange={(e) => ctrl.setTransition(step.stepKey, i, { when: { ...t.when, field: e.target.value } })}
+                  aria-label="Field"
+                >
+                  <option value="">Which field…</option>
+                  {fields.map((f) => <option key={f.name} value={f.name}>{f.label}</option>)}
+                </select>
+                <select
+                  className="xeplr-factory-prop-input"
+                  value={t.when.op}
+                  onChange={(e) => ctrl.setTransition(step.stepKey, i, { when: { ...t.when, op: e.target.value } })}
+                  aria-label="Test"
+                >
+                  {FLOW_OPERATORS.map((o) => <option key={o.op} value={o.op}>{o.label}</option>)}
+                </select>
+                {!VALUELESS_OPERATORS.includes(t.when.op) && (
+                  <input
+                    className="xeplr-factory-prop-input"
+                    value={t.when.value ?? ''}
+                    placeholder="value"
+                    onChange={(e) => ctrl.setTransition(step.stepKey, i, { when: { ...t.when, value: e.target.value } })}
+                    aria-label="Value"
+                  />
+                )}
+              </div>
+            )}
+            <div className="xeplr-factory-arrow-target">
+              <span>go to</span>
+              <select
+                className="xeplr-factory-prop-input"
+                value={t.target}
+                onChange={(e) => ctrl.setTransition(step.stepKey, i, { target: e.target.value })}
+                aria-label="Goes to"
+              >
+                {others.map((s) => <option key={s.stepKey} value={s.stepKey}>{s.label || s.stepKey}</option>)}
+                <option value={FLOW_END}>Finish</option>
+              </select>
+              <button type="button" className="xeplr-factory-icon-button" aria-label="Remove this arrow" onClick={() => ctrl.disconnect(step.stepKey, i)}>×</button>
+            </div>
+          </div>
+        ))}
+        <div className="xeplr-factory-arrow-add">
+          <button
+            type="button"
+            className="xeplr-factory-add"
+            onClick={() => ctrl.connect(step.stepKey, others.length ? others[0].stepKey : FLOW_END, { field: fields[0] ? fields[0].name : '', op: '=', value: '' })}
+          >
+            + If a field says…
+          </button>
+          {!step.transitions.some((t) => t.when === null) && (
+            <button
+              type="button"
+              className="xeplr-factory-add"
+              onClick={() => ctrl.connect(step.stepKey, others.length ? others[0].stepKey : FLOW_END, null)}
+            >
+              + Otherwise
+            </button>
+          )}
+        </div>
+      </fieldset>
+
+      {(ctrl.errorsByStep[step.stepKey] || []).length > 0 && (
+        <div className="xeplr-factory-panel-errors" role="alert">
+          {ctrl.errorsByStep[step.stepKey].map((e, i) => <div key={i}>{e.message}</div>)}
+        </div>
+      )}
+    </aside>
+  )
+}
+
+/** Where the next screen goes: to the right of the last one, a row lower after four. */
+function nextPlace(flow) {
+  const n = flow.steps.length
+  return { x: 60 + (n % 4) * (STEP_W + 90), y: 80 + Math.floor(n / 4) * (STEP_H + 110) }
+}
+
+function screenName(ctrl, id) {
+  const hit = ctrl.screens.find((s) => s.id === id)
+  return (hit && hit.name) || id
+}
+
+/** A field's label, for an arrow that tests it — the person never sees column names. */
+function labelOf(ctrl, stepKey, when) {
+  if (!when) return null
+  const hit = ctrl.fieldsFor(stepKey).find((f) => f.name === when.field)
+  return hit ? hit.label : when.field
+}

package/src/designs/FlowRunnerSample.jsx

@@ -0,0 +1,69 @@
+import { useRef } from 'react'
+import ScreenSample from './ScreenSample.jsx'
+
+// A flow, running: the screen the run is parked on, and one button forward.
+//
+// Presentation only — everything comes from useFlowRun and useFactoryScreen.
+// The screen saves itself into its own table exactly as it does anywhere else;
+// "Next" hands the run what was filled in, and the run says which screen comes
+// after it. Nothing here knows the journey.
+
+export default function FlowRunnerSample({ run, screen, className, style, title, renderDone }) {
+  const values = useRef({})
+  const record = useRef(null)
+
+  if (run.loading) return <div className="xeplr-factory-flow-loading">Opening…</div>
+  if (run.error) {
+    return (
+      <div className="xeplr-factory-invalid" role="alert">
+        <strong>This journey cannot go on:</strong> {run.error}
+      </div>
+    )
+  }
+  if (run.status === 'done') {
+    return (
+      <div className={'xeplr-factory-flow' + (className ? ' ' + className : '')} style={style}>
+        {renderDone
+          ? renderDone(run)
+          : <div className="xeplr-factory-flow-done" role="status"><strong>All done.</strong> Nothing more to fill in.</div>}
+      </div>
+    )
+  }
+  if (!run.document) return null
+
+  return (
+    <div className={'xeplr-factory-flow' + (className ? ' ' + className : '')} style={style}>
+      {title && (
+        <div className="xeplr-factory-flow-head">
+          <span className="xeplr-factory-flow-where">{title}</span>
+          {run.sending && <span className="xeplr-factory-flow-sending">Working out what comes next…</span>}
+        </div>
+      )}
+      <ScreenSample
+        // A new step is a new form: the key stops the screen keeping the last
+        // one's values while the document changes under it.
+        key={run.stepKey}
+        ctrl={{
+          ...screen,
+          // The flow's forward button IS the screen's own, renamed: one button,
+          // not two that both look like the way on.
+          done: () => run.submit(values.current, record.current),
+          doneLabel: run.sending ? 'Saving…' : 'Next'
+        }}
+      />
+      <FlowValues screen={screen} values={values} record={record} />
+    </div>
+  )
+}
+
+/**
+ * The bridge between the screen and the run: what is filled in, and the row
+ * the screen saved. Kept in refs — the run reads them when the person moves
+ * on, and a re-render on every keystroke would be the form's business, not
+ * the journey's.
+ */
+function FlowValues({ screen, values, record }) {
+  values.current = screen.values
+  record.current = screen.recordId
+  return null
+}

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>
   )
@@ -49,8 +58,13 @@ function StepNav({ ctrl, node, children }) {
 function DoneButton({ ctrl }) {
   const saving = ctrl.status === 'pending' || ctrl.status === 'saving'
   return (
-    <button type="button" className="xeplr-factory-secondary" onClick={() => ctrl.flush().then(ctrl.done, ctrl.done)}>
-      {saving ? 'Saving…' : 'Done'}
+    <button
+      type="button"
+      className={ctrl.doneLabel ? 'xeplr-factory-primary' : 'xeplr-factory-secondary'}
+      disabled={!ctrl.canSave && ctrl.status === 'invalid'}
+      onClick={() => ctrl.flush().then(ctrl.done, ctrl.done)}
+    >
+      {saving ? 'Saving…' : (ctrl.doneLabel || 'Done')}
     </button>
   )
 }
@@ -116,7 +130,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

@@ -8,7 +8,8 @@
    it shrinks, so the layout keeps its proportions. */
 
 .xeplr-factory-screen,
-.xeplr-factory-canvas {
+.xeplr-factory-canvas,
+.xeplr-factory-flow-builder {
   container-type: inline-size;
   --xf-u: min(1px, calc(100cqw / var(--xf-width, 800)));
   --xf-accent: var(--xeplr-accent, #2563eb);
@@ -129,6 +130,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; }
@@ -314,3 +319,50 @@
 .xeplr-factory-confirm-text { flex: 1; line-height: 1.5; }
 .xeplr-factory-confirm-text ul { margin: 4px 0; padding-left: 18px; }
 .xeplr-factory-confirm-actions { display: flex; gap: 8px; flex-shrink: 0; }
+
+/* ── flows: screens joined by arrows ──────────────────────────────────────
+   The designer wears the builder's chrome (bar, palette, panel); what is new
+   is the step card on the canvas, the label on an arrow, and the rows that
+   say where a step goes next. */
+.xeplr-factory-flow-builder { display: flex; flex-direction: column; height: 100%; min-height: 0; color: var(--xeplr-text-primary, #1a1a19); }
+.xeplr-factory-flow-key { margin-right: auto; padding: 2px 6px; border-radius: 4px; background: var(--xf-border); font-size: 11px; }
+.xeplr-factory-flow-canvas { height: 100%; }
+
+.xeplr-factory-step-card {
+  display: flex; flex-direction: column; justify-content: center; gap: 2px;
+  width: 100%; height: 100%; box-sizing: border-box; padding: 10px 12px;
+  border: 1px solid var(--xf-border); border-radius: 10px; background: var(--xf-surface);
+  box-shadow: 0 1px 2px rgba(0, 0, 0, 0.06);
+}
+.xeplr-factory-step-card.is-selected { border-color: var(--xf-accent); box-shadow: 0 0 0 2px color-mix(in srgb, var(--xf-accent) 30%, transparent); }
+.xeplr-factory-step-card.has-error { border-color: var(--xf-danger); }
+.xeplr-factory-step-card-name { font-weight: 640; color: var(--xf-ink); }
+.xeplr-factory-step-card-screen { color: var(--xf-muted); font-size: 12px; }
+.xeplr-factory-step-card-first { color: var(--xf-accent); font-size: 11px; font-weight: 600; text-transform: uppercase; letter-spacing: 0.05em; }
+
+.xeplr-factory-edge-label {
+  /* Above the curve's midpoint rather than on it, so a label never sits on the
+     card an arrow is arriving at. */
+  margin-top: -12px;
+  padding: 1px 6px; border-radius: 999px; background: var(--xf-surface);
+  border: 1px solid var(--xf-border); color: var(--xf-muted); font-size: 11px; white-space: nowrap;
+}
+
+.xeplr-factory-arrow { padding: 8px 0; border-top: 1px dashed var(--xf-border); }
+.xeplr-factory-arrow:first-of-type { border-top: none; }
+.xeplr-factory-arrow-when { font-weight: 600; font-size: 12px; }
+.xeplr-factory-arrow-test { display: grid; gap: 4px; }
+.xeplr-factory-arrow-target { display: flex; align-items: center; gap: 6px; margin-top: 6px; color: var(--xf-muted); font-size: 12px; }
+.xeplr-factory-arrow-target select { flex: 1; }
+.xeplr-factory-arrow-add { display: flex; gap: 6px; flex-wrap: wrap; margin-top: 8px; }
+.xeplr-factory-danger-link { border: none; background: none; color: var(--xf-danger); font: inherit; cursor: pointer; padding: 0; }
+
+/* ── a flow, running ─────────────────────────────────────────────────────── */
+.xeplr-factory-flow { display: flex; flex-direction: column; gap: 8px; }
+.xeplr-factory-flow-head { display: flex; align-items: baseline; justify-content: space-between; gap: 12px; }
+.xeplr-factory-flow-where { font-weight: 640; }
+.xeplr-factory-flow-sending, .xeplr-factory-flow-loading { color: var(--xf-muted); font-size: 12px; }
+.xeplr-factory-flow-done {
+  padding: 16px; border-radius: 8px; border: 1px solid var(--xf-border);
+  background: var(--xf-surface); color: var(--xf-ink);
+}

package/src/designs/index.js

@@ -4,6 +4,8 @@ export { default as BuilderSample } from './BuilderSample.jsx'
 export { default as ScreenSample } from './ScreenSample.jsx'
 export { default as ListView } from './ListView.jsx'
 export { default as ScreenModal } from './ScreenModal.jsx'
+export { default as FlowRunnerSample } from './FlowRunnerSample.jsx'
+export { default as FlowBuilderSample } from './FlowBuilderSample.jsx'
 export { default as ControlView, VIEWS } from './ControlView.jsx'
 export { default as Palette, DRAG_TYPE } from './Palette.jsx'
 export { default as PropertyPanel, EDITORS } from './PropertyPanel.jsx'

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 = {}