@xeplr/ui-factory 1.4.0 → 1.6.0

package/README.md

@@ -323,6 +323,71 @@ Controller: the embedded screen is a second `useFactoryScreen` with `link`
 save, name }`). `FactoryScreen` wires both; a custom design gets `subformFor(node)`,
 `registerSubform(id, api)` and `subformDirty(id, dirty)` from the host's controller.
 
+## Events — the app's code, picked by name
+
+A screen says which of the app's functions run around its records, one per
+event. The code is registered in the app (with `@xeplr/actions`, `event` set
+to one of these); the screen only names it:
+
+```json
+"events": { "beforeSave": "checkSalaryBand", "afterSave": "notifyHR" }
+```
+
+| event | runs | gets | returns |
+|---|---|---|---|
+| `beforeLoad` | Before records are read — the list, and one record for Edit | ctx.query (narrow it), ctx.id (one record) or ctx.many (the list), ctx.user, ctx.tenant | nothing, or a new query |
+| `beforeSave` | Before a record is written — the screen's rules run on what it returns | ctx.values, ctx.isNew, ctx.previous (on update), ctx.user | the values to save (or nothing to keep them); ctx.reject(message, { field }) refuses |
+| `afterSave` | Once the record is saved | ctx.result (the saved row), ctx.isNew, ctx.values | nothing — what it does is the point (an email, another record) |
+| `beforeDelete` | Before a record is deleted | ctx.previous (the row), ctx.id | nothing; ctx.reject(message) refuses |
+| `onError` | When loading, saving or deleting failed | ctx.error, ctx.op (get, save or delete) | nothing — the error is still the answer; this is for telling someone |
+
+- **This is the only way to attach code to a screen's records.** One function per event, named in the screen — the screen is the one place that says what runs.
+- **Every event runs on the server** (`@xeplr/factory` 2+). A rule that runs in the browser is one a person can skip.
+- **Checked twice.** Here, that each name could be a function and each event exists. On the server, at publish and when it runs, that the function is registered *for that event* — a missing one refuses with its name (`missingFunctions(doc, registry)`).
+- `SCREEN_EVENTS` carries each event's contract (`when`, `gets`, `returns`) — what the designer shows beside each picker.
+
+## The flow designer, as a list — `<FlowDesigner>`
+
+Your screens as a journey: the steps down the left; for the one picked, its
+**Form design** (the screen's builder), the **events** the app's functions run
+on, and **where it goes next**. The selected step and tab live in the URL
+(`<urlKey>Selected`, `<urlKey>Tab`).
+
+```jsx
+const factory = createFactoryApi({ fetch: authFetch, base: '/api' })
+const flows = createFlowsApi({ fetch: authFetch, base: '/api/workflow' })
+
+<FlowDesigner
+  flow={flow} screens={screens} loadScreen={factory.loadScreen}
+  onSave={flows.saveFlow} onPublish={flows.publishFlow}
+  listFunctions={factory.listFunctions}
+  loadDraft={factory.loadDraft} saveDraft={factory.saveDraft} publishScreen={factory.publish}
+  builderProps={factory.builderProps}
+  urlKey="flow"
+/>
+```
+
+- **Events are the screen's.** Picking a function saves it to that screen's
+  draft; it runs once the screen is **published** (a button on the card), and
+  in every journey that shows the screen. Each picker offers only the functions
+  the app registered for that event, with what each is handed and returns —
+  the code itself is never in the designer.
+- **Navigation is the flow's:** go to a screen, **let a function decide** (a
+  registered `decide` function, and the steps it may choose), or finish the
+  journey. A step whose arrows test its fields shows them, and can be replaced
+  with one of the three.
+- **Nothing runs in the browser.** Before load, Before save, After save,
+  Before delete and On error run on the server; On load / On change / On exit
+  are not offered, because nothing would run them.
+- Approvals (another person's turn, with an assignee and a timeout) are not
+  part of this designer.
+
+Controllers, for a design of your own: `useFlowBuilder` (the flow, plus
+`navigationOf` / `setNavigation`), `useScreenEvents` (one screen's events,
+`adopt` to share its draft with a builder), `useFunctionCatalog` (the app's
+functions, `forEvent`). Model: `navigationOf`, `setNavigation`, `arrowTargets`,
+`setEvent`, `functionsFor`.
+
 ## Masters — the lists the rest of the app points at
 
 Departments, statuses, countries, categories. Mark a form as a master in its

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xeplr/ui-factory",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "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/FlowDesignerSample.jsx

@@ -0,0 +1,371 @@
+import { FLOW_END, describeWhen } from '../flow.js'
+import { DECIDE_EVENT } from '../events.js'
+
+// THE FLOW DESIGNER, AS A LIST — the screens of a journey down the left; for
+// the one picked, its form, its events and where it goes next.
+//
+//   left    the steps, in order, and "Add a screen"
+//   top     the step's name, and the flow's own save state and Publish
+//   tabs    Form design — the screen's builder (renderFormDesign)
+//           Events & navigation — what runs around its records, and what
+//           comes after it
+//
+// EVENTS ARE THE SCREEN'S, NAVIGATION IS THE FLOW'S. A screen's records behave
+// the same in every flow that shows it, so its events are saved to the
+// screen's draft and take effect when the screen is published; where a step
+// goes next belongs to this flow alone and saves with it.
+//
+// The code is never here. Each picker offers the functions the app registered
+// for that event (useFunctionCatalog), with what each is for and what it is
+// handed and returns — the developer writes the code in the app.
+//
+// Presentation only: everything comes from useFlowBuilder (ctrl),
+// useScreenEvents (events) and useFunctionCatalog (catalog).
+
+const FLOW_STATUS = {
+  saved: 'All changes saved',
+  pending: 'Unsaved changes…',
+  saving: 'Saving…',
+  invalid: 'Not saved — finish the flow first',
+  error: 'Not saved'
+}
+
+export const FLOW_DESIGNER_TABS = [
+  { key: 'settings', label: 'Events & navigation' },
+  { key: 'design', label: 'Form design' }
+]
+
+export default function FlowDesignerSample({ ctrl, step, events, catalog, tab, onTab, renderFormDesign, className, style }) {
+  const { flow } = ctrl
+  return (
+    <div className={'xeplr-factory-fd' + (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"
+        />
+        <div className={`xeplr-factory-bar-status xeplr-factory-bar-status--${ctrl.status}`} role="status" aria-live="polite">
+          {ctrl.status === 'error' ? `Not saved — ${ctrl.saveError}` : FLOW_STATUS[ctrl.status]}
+        </div>
+        {ctrl.validation.errors.length > 0 && (
+          <span className="xeplr-factory-problems" title={ctrl.validation.errors.map((x) => x.message).join('\n')}>
+            {ctrl.validation.errors.length} problem{ctrl.validation.errors.length === 1 ? '' : 's'}
+          </span>
+        )}
+        {ctrl.canPublish && (
+          <button type="button" className="xeplr-factory-primary" onClick={ctrl.publish} disabled={ctrl.publishing || !ctrl.validation.ok}>
+            {ctrl.publishing ? 'Publishing…' : 'Publish flow'}
+          </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-fd-body">
+        <Steps ctrl={ctrl} step={step} />
+        <main className="xeplr-factory-fd-main">
+          {!step ? (
+            <div className="xeplr-factory-fd-empty">Add a screen on the left to start the journey.</div>
+          ) : (
+            <>
+              <div className="xeplr-factory-fd-head">
+                <input
+                  className="xeplr-factory-fd-step-name"
+                  value={step.label || ''}
+                  placeholder={step.stepKey}
+                  onChange={(e) => ctrl.setStep(step.stepKey, { label: e.target.value })}
+                  aria-label="Step name"
+                />
+                <span className="xeplr-factory-fd-step-screen">Shows <code>{screenName(ctrl, step.screen)}</code></span>
+                <button type="button" className="xeplr-factory-fd-remove" onClick={() => ctrl.removeStep(step.stepKey)}>Remove step</button>
+              </div>
+              <div className="xeplr-factory-fd-tabs" role="tablist">
+                {FLOW_DESIGNER_TABS.map((t) => (
+                  <button
+                    key={t.key}
+                    type="button"
+                    role="tab"
+                    aria-selected={tab === t.key}
+                    className={'xeplr-factory-fd-tab' + (tab === t.key ? ' is-active' : '')}
+                    onClick={() => onTab(t.key)}
+                  >
+                    {t.label}
+                  </button>
+                ))}
+              </div>
+              {tab === 'design' ? (
+                <div className="xeplr-factory-fd-design">{renderFormDesign ? renderFormDesign(step, events) : null}</div>
+              ) : (
+                <div className="xeplr-factory-fd-settings">
+                  <EventsPanel step={step} events={events} catalog={catalog} ctrl={ctrl} />
+                  <NavigationPanel step={step} ctrl={ctrl} catalog={catalog} />
+                </div>
+              )}
+            </>
+          )}
+        </main>
+      </div>
+    </div>
+  )
+}
+
+/** The journey's screens, in order, with "Add a screen" under them. */
+function Steps({ ctrl, step }) {
+  const { flow } = ctrl
+  const unused = ctrl.screens.filter((s) => !flow.steps.some((x) => x.screen === s.id))
+  return (
+    <nav className="xeplr-factory-fd-steps" aria-label="Screens of this journey">
+      <ol className="xeplr-factory-fd-step-list">
+        {flow.steps.map((s, i) => {
+          const problems = ctrl.errorsByStep[s.stepKey] || []
+          const on = step && step.stepKey === s.stepKey
+          return (
+            <li key={s.stepKey}>
+              <button
+                type="button"
+                className={'xeplr-factory-fd-step' + (on ? ' is-selected' : '') + (problems.length ? ' has-error' : '')}
+                aria-current={on ? 'step' : undefined}
+                onClick={() => ctrl.setSelected(s.stepKey)}
+                title={problems.map((p) => p.message).join('\n') || undefined}
+              >
+                <span className="xeplr-factory-fd-step-number">{i + 1}</span>
+                <span className="xeplr-factory-fd-step-text">
+                  <span className="xeplr-factory-fd-step-label">{s.label || s.stepKey}</span>
+                  <span className="xeplr-factory-fd-step-next">{nextInWords(ctrl, s)}</span>
+                </span>
+              </button>
+            </li>
+          )
+        })}
+      </ol>
+      <label className="xeplr-factory-fd-add">
+        <span className="xeplr-factory-fd-add-label">Add a screen</span>
+        <select
+          value=""
+          onChange={(e) => { if (e.target.value) ctrl.addStep(e.target.value) }}
+          aria-label="Add a screen to the journey"
+        >
+          <option value="">{ctrl.screens.length ? 'Choose a form…' : 'No published forms yet'}</option>
+          {unused.map((s) => <option key={s.id} value={s.id}>{s.name || s.id}</option>)}
+          {unused.length < ctrl.screens.length && unused.length > 0 && <option disabled>──────────</option>}
+          {ctrl.screens.filter((s) => !unused.includes(s)).map((s) => <option key={s.id} value={s.id}>{s.name || s.id} (again)</option>)}
+        </select>
+      </label>
+    </nav>
+  )
+}
+
+/** The screen's events: one function per event, from those the app registered for it. */
+function EventsPanel({ step, events, catalog }) {
+  return (
+    <section className="xeplr-factory-fd-card" aria-labelledby="xf-fd-events">
+      <div className="xeplr-factory-fd-card-head">
+        <h3 id="xf-fd-events">Events of this screen</h3>
+        <p>
+          The app’s own functions, run on the server around <strong>{step.label || step.stepKey}</strong>’s records.
+          They belong to the screen, so they run in every journey that shows it.
+        </p>
+      </div>
+      {events.loading && <p className="xeplr-factory-hint">Opening the screen…</p>}
+      {events.error && <div className="xeplr-factory-invalid" role="alert">{events.error}</div>}
+      {catalog.error && <div className="xeplr-factory-invalid" role="alert">{catalog.error}</div>}
+      {events.document && (
+        <>
+          <ul className="xeplr-factory-fd-events">
+            {events.rows.map((row) => {
+              const options = catalog.forEvent(row.key)
+              const picked = row.picked ? catalog.byName(row.picked) : null
+              const gone = row.picked && !catalog.loading && (!picked || picked.event !== row.key)
+              const id = `xf-fd-event-${row.key}`
+              return (
+                <li key={row.key} className={'xeplr-factory-fd-event' + (row.picked ? ' is-on' : '') + (gone ? ' has-error' : '')}>
+                  <div className="xeplr-factory-fd-event-what">
+                    <label htmlFor={id} className="xeplr-factory-fd-event-name">{row.label}</label>
+                    <span className="xeplr-factory-fd-event-when">{row.when}</span>
+                  </div>
+                  <select
+                    id={id}
+                    value={row.picked}
+                    onChange={(e) => events.setEvent(row.key, e.target.value)}
+                  >
+                    <option value="">{options.length ? 'Nothing runs' : 'No functions for this yet'}</option>
+                    {options.map((f) => <option key={f.name} value={f.name}>{f.name}</option>)}
+                    {gone && <option value={row.picked}>{row.picked} (not registered)</option>}
+                  </select>
+                  {row.picked && (
+                    <div className="xeplr-factory-fd-contract">
+                      {gone
+                        ? <p className="xeplr-factory-fd-contract-gone">“{row.picked}” is not registered for {row.label.toLowerCase()} in the app. Publishing this screen will be refused until it is — or pick another.</p>
+                        : picked && picked.description && <p className="xeplr-factory-fd-contract-desc">{picked.description}</p>}
+                      <dl>
+                        <dt>Gets</dt><dd>{row.gets}</dd>
+                        <dt>Returns</dt><dd>{row.returns}</dd>
+                      </dl>
+                    </div>
+                  )}
+                </li>
+              )
+            })}
+          </ul>
+          <div className="xeplr-factory-fd-card-foot">
+            <span className={`xeplr-factory-fd-save xeplr-factory-fd-save--${events.status}`} role="status" aria-live="polite">
+              {events.status === 'saving' ? 'Saving…'
+                : events.status === 'error' ? `Not saved — ${events.saveError}`
+                  : events.status === 'saved' ? 'Saved to the screen’s draft — publish the screen to use it'
+                    : 'Changes take effect when the screen is published'}
+            </span>
+            {events.canPublish && (
+              <button type="button" className="xeplr-factory-secondary" onClick={events.publish} disabled={events.publishing}>
+                {events.publishing ? 'Publishing…' : 'Publish screen'}
+              </button>
+            )}
+          </div>
+          {events.publishResult && (
+            <div className={'xeplr-factory-fd-result' + (events.publishResult.ok ? ' is-ok' : ' is-error')} role="status">{events.publishResult.message}</div>
+          )}
+        </>
+      )}
+    </section>
+  )
+}
+
+/** Where this step goes once its screen is saved: a screen, a function's choice, or the end. */
+function NavigationPanel({ step, ctrl, catalog }) {
+  const nav = navigationOfStep(ctrl, step)
+  const others = ctrl.flow.steps.filter((s) => s.stepKey !== step.stepKey)
+  const deciders = catalog.forEvent(DECIDE_EVENT)
+  const set = (patch) => ctrl.setNavigation(step.stepKey, { ...nav, ...patch })
+  const name = `xf-fd-nav-${step.stepKey}`
+  const picked = nav.mode === 'decide' && nav.decide ? catalog.byName(nav.decide) : null
+  const problems = ctrl.errorsByStep[step.stepKey] || []
+
+  return (
+    <section className="xeplr-factory-fd-card" aria-labelledby="xf-fd-nav">
+      <div className="xeplr-factory-fd-card-head">
+        <h3 id="xf-fd-nav">After this screen is saved</h3>
+        <p>Where the journey goes next. This belongs to this flow only.</p>
+      </div>
+
+      {nav.mode === 'branches' ? (
+        <div className="xeplr-factory-fd-branches">
+          <p>This step chooses by what was filled in:</p>
+          <ul>
+            {step.transitions.map((t, i) => (
+              <li key={i}>{describeWhen(t.when, fieldLabel(ctrl, step, t.when))} → {targetName(ctrl, t.target)}</li>
+            ))}
+          </ul>
+          <button type="button" className="xeplr-factory-secondary" onClick={() => ctrl.setNavigation(step.stepKey, { mode: 'screen', target: others[0] ? others[0].stepKey : '' })}>
+            Replace with one choice below
+          </button>
+        </div>
+      ) : (
+        <div className="xeplr-factory-fd-choices" role="radiogroup" aria-labelledby="xf-fd-nav">
+          <div className={'xeplr-factory-fd-choice' + (nav.mode === 'screen' ? ' is-on' : '')}>
+            <label className="xeplr-factory-fd-choice-pick">
+              <input type="radio" name={name} checked={nav.mode === 'screen'} onChange={() => ctrl.setNavigation(step.stepKey, { mode: 'screen', target: others[0] ? others[0].stepKey : '' })} />
+              <span>Go to a screen</span>
+            </label>
+            {nav.mode === 'screen' && (
+              <select value={nav.target || ''} onChange={(e) => set({ target: e.target.value })} aria-label="Go to">
+                {!nav.target && <option value="">Choose a screen…</option>}
+                {others.map((s) => <option key={s.stepKey} value={s.stepKey}>{s.label || s.stepKey}</option>)}
+              </select>
+            )}
+          </div>
+
+          <div className={'xeplr-factory-fd-choice' + (nav.mode === 'decide' ? ' is-on' : '')}>
+            <label className="xeplr-factory-fd-choice-pick">
+              <input type="radio" name={name} checked={nav.mode === 'decide'} onChange={() => ctrl.setNavigation(step.stepKey, { mode: 'decide', decide: deciders[0] ? deciders[0].name : '', targets: others.map((s) => s.stepKey) })} />
+              <span>Let a function decide</span>
+            </label>
+            {nav.mode === 'decide' && (
+              <div className="xeplr-factory-fd-decide">
+                <select value={nav.decide || ''} onChange={(e) => set({ decide: e.target.value })} aria-label="Function that decides">
+                  {!nav.decide && <option value="">{deciders.length ? 'Choose a function…' : 'No decide functions registered'}</option>}
+                  {deciders.map((f) => <option key={f.name} value={f.name}>{f.name}</option>)}
+                  {nav.decide && !picked && !catalog.loading && <option value={nav.decide}>{nav.decide} (not registered)</option>}
+                </select>
+                {picked && picked.description && <p className="xeplr-factory-fd-contract-desc">{picked.description}</p>}
+                <fieldset className="xeplr-factory-fd-targets">
+                  <legend>It may choose</legend>
+                  {others.map((s) => (
+                    <label key={s.stepKey} className="xeplr-factory-fd-target">
+                      <input
+                        type="checkbox"
+                        checked={(nav.targets || []).includes(s.stepKey)}
+                        onChange={(e) => set({ targets: e.target.checked ? [...(nav.targets || []), s.stepKey] : (nav.targets || []).filter((k) => k !== s.stepKey) })}
+                      />
+                      <span>{s.label || s.stepKey}</span>
+                    </label>
+                  ))}
+                  <label className="xeplr-factory-fd-target">
+                    <input
+                      type="checkbox"
+                      checked={(nav.targets || []).includes(FLOW_END)}
+                      onChange={(e) => set({ targets: e.target.checked ? [...(nav.targets || []), FLOW_END] : (nav.targets || []).filter((k) => k !== FLOW_END) })}
+                    />
+                    <span>Finish the journey</span>
+                  </label>
+                </fieldset>
+                <p className="xeplr-factory-hint">It is handed what was filled in and returns one of these — anything else stops the journey and says so.</p>
+              </div>
+            )}
+          </div>
+
+          <div className={'xeplr-factory-fd-choice' + (nav.mode === 'end' ? ' is-on' : '')}>
+            <label className="xeplr-factory-fd-choice-pick">
+              <input type="radio" name={name} checked={nav.mode === 'end'} onChange={() => ctrl.setNavigation(step.stepKey, { mode: 'end' })} />
+              <span>Finish the journey</span>
+            </label>
+          </div>
+        </div>
+      )}
+
+      {problems.length > 0 && (
+        <div className="xeplr-factory-invalid" role="alert">
+          {problems.map((p, i) => <div key={i}>{p.message}</div>)}
+        </div>
+      )}
+    </section>
+  )
+}
+
+function navigationOfStep(ctrl, step) {
+  return ctrl.navigationOf(step)
+}
+
+/** "→ Contract", "→ routeByAmount decides", "Finishes" — under each step in the list. */
+function nextInWords(ctrl, step) {
+  const nav = ctrl.navigationOf(step)
+  if (nav.mode === 'screen') return '→ ' + targetName(ctrl, nav.target)
+  if (nav.mode === 'decide') return nav.decide ? `→ ${nav.decide} decides` : '→ a function decides'
+  if (nav.mode === 'branches') return `→ ${step.transitions.length} branches`
+  if (nav.mode === 'end') return 'Finishes the journey'
+  return 'Where next?'
+}
+
+function targetName(ctrl, key) {
+  if (!key) return '…'
+  if (key === FLOW_END) return 'Finish'
+  const s = ctrl.flow.steps.find((x) => x.stepKey === key)
+  return s ? (s.label || s.stepKey) : key
+}
+
+function screenName(ctrl, id) {
+  const hit = ctrl.screens.find((s) => s.id === id)
+  return (hit && hit.name) || id
+}
+
+function fieldLabel(ctrl, step, when) {
+  if (!when) return null
+  const hit = ctrl.fieldsFor(step.stepKey).find((f) => f.name === when.field)
+  return hit ? hit.label : when.field
+}

package/src/designs/factory.css

@@ -26,6 +26,7 @@
 .xeplr-factory-screen,
 .xeplr-factory-canvas,
 .xeplr-factory-flow-builder,
+.xeplr-factory-fd,
 .xeplr-factory-builder,
 .xeplr-factory-modal-backdrop {
   --xf-accent: var(--xeplr-accent, #2563eb);
@@ -107,7 +108,7 @@
    the theme's muted ink and follows a dark theme. Only background-image and
    its longhands are set: each box keeps its own colour, and a control's
    Background (boxStyle) is a background-COLOR so it cannot wipe the arrow. */
-:is(.xeplr-factory-screen, .xeplr-factory-canvas, .xeplr-factory-flow-builder, .xeplr-factory-builder, .xeplr-factory-modal-backdrop) select:not([multiple]) {
+:is(.xeplr-factory-screen, .xeplr-factory-canvas, .xeplr-factory-flow-builder, .xeplr-factory-fd, .xeplr-factory-builder, .xeplr-factory-modal-backdrop) select:not([multiple]) {
   -webkit-appearance: none;
   appearance: none;
   /* Two thin diagonals side by side — each corner to corner of its own small
@@ -122,7 +123,7 @@
   text-overflow: ellipsis;
   cursor: pointer;
 }
-:is(.xeplr-factory-screen, .xeplr-factory-canvas, .xeplr-factory-flow-builder, .xeplr-factory-builder, .xeplr-factory-modal-backdrop) select:not([multiple]):disabled { cursor: default; opacity: .6; }
+:is(.xeplr-factory-screen, .xeplr-factory-canvas, .xeplr-factory-flow-builder, .xeplr-factory-fd, .xeplr-factory-builder, .xeplr-factory-modal-backdrop) select:not([multiple]):disabled { cursor: default; opacity: .6; }
 .xeplr-factory-field.has-error .xeplr-factory-input { border-color: var(--xf-danger); }
 .xeplr-factory-error {
   /* In the gap BELOW the field, out of flow: a message appearing must not
@@ -524,3 +525,115 @@
 .xeplr-factory-modal-body { flex: 1; min-height: 0; overflow: hidden; }
 .xeplr-factory-modal-body > * { height: 100%; }
 .xeplr-factory-builder--nested { min-height: 0; }
+
+/* ── the flow designer, as a list (FlowDesignerSample) ────────────────────
+   The journey's screens down the left; for the one picked, two cards side by
+   side — the screen's events, and where the journey goes after it. Wears the
+   builder's bar; everything else is its own. */
+.xeplr-factory-fd {
+  display: flex; flex-direction: column; height: 100%; min-height: 560px;
+  color: var(--xf-ink); background: var(--xf-plane); font-size: 13px;
+}
+.xeplr-factory-fd select, .xeplr-factory-fd-step-name {
+  font: inherit; color: var(--xf-ink); background-color: var(--xf-field-bg);
+  border: 1px solid var(--xf-field-border); border-radius: 6px; padding: 6px 8px; min-width: 0;
+}
+.xeplr-factory-fd select:focus-visible, .xeplr-factory-fd-step-name:focus-visible {
+  outline: none; border-color: var(--xf-accent); box-shadow: 0 0 0 3px color-mix(in srgb, var(--xf-accent) 22%, transparent);
+}
+.xeplr-factory-fd-body { flex: 1; min-height: 0; display: flex; }
+
+/* the steps */
+.xeplr-factory-fd-steps {
+  width: 260px; flex: 0 0 auto; display: flex; flex-direction: column; gap: 12px;
+  padding: 14px 12px; border-right: 1px solid var(--xf-border); background: var(--xf-surface); overflow-y: auto;
+}
+.xeplr-factory-fd-step-list { list-style: none; margin: 0; padding: 0; display: flex; flex-direction: column; gap: 6px; }
+.xeplr-factory-fd-step {
+  display: flex; align-items: flex-start; gap: 10px; width: 100%; padding: 9px 10px; text-align: left;
+  font: inherit; color: inherit; background: transparent; cursor: pointer;
+  border: 1px solid transparent; border-radius: 8px;
+}
+.xeplr-factory-fd-step:hover { background: var(--xf-hover); }
+.xeplr-factory-fd-step.is-selected { border-color: color-mix(in srgb, var(--xf-accent) 55%, var(--xf-border)); background: color-mix(in srgb, var(--xf-accent) 9%, transparent); }
+.xeplr-factory-fd-step.has-error .xeplr-factory-fd-step-number { background: var(--xf-danger); color: #fff; }
+.xeplr-factory-fd-step-number {
+  flex: 0 0 auto; width: 22px; height: 22px; border-radius: 50%; display: inline-flex; align-items: center; justify-content: center;
+  font-size: 11px; font-weight: 700; background: var(--xf-hover); color: var(--xf-muted);
+}
+.xeplr-factory-fd-step.is-selected .xeplr-factory-fd-step-number { background: var(--xf-accent); color: var(--xf-accent-ink); }
+.xeplr-factory-fd-step-text { display: flex; flex-direction: column; gap: 2px; min-width: 0; }
+.xeplr-factory-fd-step-label { font-weight: 600; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.xeplr-factory-fd-step-next { color: var(--xf-muted); font-size: 12px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.xeplr-factory-fd-add { display: flex; flex-direction: column; gap: 4px; padding-top: 10px; border-top: 1px solid var(--xf-border); }
+.xeplr-factory-fd-add-label { font-size: 11px; font-weight: 700; letter-spacing: .05em; text-transform: uppercase; color: var(--xf-muted); }
+
+/* the step that is open */
+.xeplr-factory-fd-main { flex: 1; min-width: 0; display: flex; flex-direction: column; overflow-y: auto; }
+.xeplr-factory-fd-empty { margin: auto; color: var(--xf-muted); }
+.xeplr-factory-fd-head { display: flex; align-items: center; gap: 12px; padding: 14px 20px 0; flex-wrap: wrap; }
+.xeplr-factory-fd-step-name { font-size: 18px; font-weight: 650; background: transparent; border-color: transparent; padding: 4px 8px; margin-left: -8px; min-width: 220px; }
+.xeplr-factory-fd-step-name:hover { border-color: var(--xf-border); }
+.xeplr-factory-fd-step-screen { color: var(--xf-muted); }
+.xeplr-factory-fd-step-screen code { color: var(--xf-ink); }
+.xeplr-factory-fd-remove { margin-left: auto; font: inherit; font-size: 12px; color: var(--xf-danger); background: none; border: none; cursor: pointer; padding: 4px 6px; border-radius: 6px; }
+.xeplr-factory-fd-remove:hover { background: color-mix(in srgb, var(--xf-danger) 10%, transparent); }
+.xeplr-factory-fd-tabs { display: flex; gap: 4px; padding: 10px 20px 0; border-bottom: 1px solid var(--xf-border); }
+.xeplr-factory-fd-tab {
+  font: inherit; font-weight: 500; color: var(--xf-muted); background: none; cursor: pointer;
+  border: none; border-bottom: 2px solid transparent; padding: 8px 12px; margin-bottom: -1px;
+}
+.xeplr-factory-fd-tab:hover { color: var(--xf-ink); }
+.xeplr-factory-fd-tab.is-active { color: var(--xf-accent); border-bottom-color: var(--xf-accent); font-weight: 600; }
+.xeplr-factory-fd-design { flex: 1; min-height: 560px; display: flex; }
+.xeplr-factory-fd-design > * { flex: 1; min-width: 0; }
+.xeplr-factory-fd-settings { display: grid; grid-template-columns: minmax(0, 3fr) minmax(0, 2fr); gap: 16px; padding: 16px 20px 24px; align-items: start; }
+@container (max-width: 900px) { .xeplr-factory-fd-settings { grid-template-columns: minmax(0, 1fr); } }
+@media (max-width: 1100px) { .xeplr-factory-fd-settings { grid-template-columns: minmax(0, 1fr); } }
+
+/* a card: the events, or the navigation */
+.xeplr-factory-fd-card { display: flex; flex-direction: column; gap: 12px; padding: 16px; border: 1px solid var(--xf-border); border-radius: 12px; background: var(--xf-surface); }
+.xeplr-factory-fd-card-head h3 { margin: 0 0 4px; font-size: 15px; }
+.xeplr-factory-fd-card-head p { margin: 0; color: var(--xf-muted); line-height: 1.45; }
+.xeplr-factory-fd-card-foot { display: flex; align-items: center; gap: 12px; justify-content: space-between; padding-top: 4px; }
+.xeplr-factory-fd-save { color: var(--xf-muted); font-size: 12px; }
+.xeplr-factory-fd-save--saved { color: var(--xf-good); }
+.xeplr-factory-fd-save--error { color: var(--xf-danger); }
+.xeplr-factory-fd-result { font-size: 12px; padding: 8px 10px; border-radius: 8px; }
+.xeplr-factory-fd-result.is-ok { color: var(--xf-good); background: color-mix(in srgb, var(--xf-good) 10%, transparent); }
+.xeplr-factory-fd-result.is-error { color: var(--xf-danger); background: color-mix(in srgb, var(--xf-danger) 10%, transparent); }
+
+/* one event */
+.xeplr-factory-fd-events { list-style: none; margin: 0; padding: 0; display: flex; flex-direction: column; gap: 8px; }
+.xeplr-factory-fd-event {
+  display: grid; grid-template-columns: minmax(0, 1fr) minmax(180px, 240px); gap: 6px 14px; align-items: center;
+  padding: 10px 12px; border: 1px solid var(--xf-border); border-radius: 10px;
+}
+.xeplr-factory-fd-event.is-on { border-color: color-mix(in srgb, var(--xf-accent) 40%, var(--xf-border)); }
+.xeplr-factory-fd-event.has-error { border-color: var(--xf-danger); }
+.xeplr-factory-fd-event-what { display: flex; flex-direction: column; gap: 2px; min-width: 0; }
+.xeplr-factory-fd-event-name { font-weight: 600; }
+.xeplr-factory-fd-event-when { color: var(--xf-muted); font-size: 12px; line-height: 1.4; }
+.xeplr-factory-fd-contract { grid-column: 1 / -1; display: flex; flex-direction: column; gap: 6px; padding: 8px 10px; border-radius: 8px; background: var(--xf-plane); font-size: 12px; }
+.xeplr-factory-fd-contract dl { display: grid; grid-template-columns: auto 1fr; gap: 3px 10px; margin: 0; }
+.xeplr-factory-fd-contract dt { color: var(--xf-muted); font-weight: 600; }
+.xeplr-factory-fd-contract dd { margin: 0; }
+.xeplr-factory-fd-contract-desc { margin: 0; }
+.xeplr-factory-fd-contract-gone { margin: 0; color: var(--xf-danger); }
+
+/* navigation */
+.xeplr-factory-fd-choices { display: flex; flex-direction: column; gap: 8px; }
+.xeplr-factory-fd-choice { display: flex; flex-direction: column; gap: 8px; padding: 10px 12px; border: 1px solid var(--xf-border); border-radius: 10px; }
+.xeplr-factory-fd-choice.is-on { border-color: color-mix(in srgb, var(--xf-accent) 45%, var(--xf-border)); background: color-mix(in srgb, var(--xf-accent) 6%, transparent); }
+.xeplr-factory-fd-choice-pick { display: flex; align-items: center; gap: 8px; font-weight: 600; cursor: pointer; }
+.xeplr-factory-fd-choice-pick input { accent-color: var(--xf-accent); margin: 0; }
+.xeplr-factory-fd-choice > select { margin-left: 24px; }
+.xeplr-factory-fd-decide { display: flex; flex-direction: column; gap: 8px; margin-left: 24px; }
+.xeplr-factory-fd-targets { display: flex; flex-direction: column; gap: 4px; margin: 0; padding: 8px 10px; border: 1px solid var(--xf-border); border-radius: 8px; }
+.xeplr-factory-fd-targets legend { padding: 0 4px; font-size: 11px; font-weight: 700; letter-spacing: .05em; text-transform: uppercase; color: var(--xf-muted); }
+.xeplr-factory-fd-target { display: flex; align-items: center; gap: 8px; cursor: pointer; }
+.xeplr-factory-fd-target input { accent-color: var(--xf-accent); margin: 0; }
+.xeplr-factory-fd-branches { display: flex; flex-direction: column; gap: 8px; }
+.xeplr-factory-fd-branches p { margin: 0; color: var(--xf-muted); }
+.xeplr-factory-fd-branches ul { margin: 0; padding-left: 18px; }
+.xeplr-factory-fd-branches button { align-self: flex-start; }

package/src/designs/index.js

@@ -6,6 +6,8 @@ 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'
+// The flow designer as a list of screens, with each one's events and navigation.
+export { default as FlowDesignerSample, FLOW_DESIGNER_TABS } from './FlowDesignerSample.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/events.js

@@ -0,0 +1,100 @@
+// A SCREEN'S EVENTS — the moments a developer's code may run around its
+// records, each picked BY NAME from the functions the app registered.
+//
+// The code lives in the app (registered with @xeplr/actions, `event` set to
+// one of the keys below); the screen only names it:
+//
+//   doc.events = { beforeSave: 'checkSalaryBand', afterSave: 'notifyHR' }
+//
+// One function per event, and this is the ONLY way to attach one — the screen
+// is the one place that says what runs. Every event runs on the SERVER: a rule
+// that runs in the browser is one a person can skip.
+//
+// What each is called with, and what it may return, is the contract a
+// developer writes to. `@xeplr/factory` runs them; the designer lists them.
+
+export const SCREEN_EVENTS = [
+  {
+    key: 'beforeLoad',
+    label: 'Before load',
+    when: 'Before records are read — the list, and one record for Edit',
+    gets: 'ctx.query (narrow it), ctx.id (one record) or ctx.many (the list), ctx.user, ctx.tenant',
+    returns: 'nothing, or a new query'
+  },
+  {
+    key: 'beforeSave',
+    label: 'Before save',
+    when: 'Before a record is written — the screen\'s rules run on what it returns',
+    gets: 'ctx.values, ctx.isNew, ctx.previous (on update), ctx.user',
+    returns: 'the values to save (or nothing to keep them); ctx.reject(message, { field }) refuses'
+  },
+  {
+    key: 'afterSave',
+    label: 'After save',
+    when: 'Once the record is saved',
+    gets: 'ctx.result (the saved row), ctx.isNew, ctx.values',
+    returns: 'nothing — what it does is the point (an email, another record)'
+  },
+  {
+    key: 'beforeDelete',
+    label: 'Before delete',
+    when: 'Before a record is deleted',
+    gets: 'ctx.previous (the row), ctx.id',
+    returns: 'nothing; ctx.reject(message) refuses'
+  },
+  {
+    key: 'onError',
+    label: 'On error',
+    when: 'When loading, saving or deleting failed',
+    gets: 'ctx.error, ctx.op (get, save or delete)',
+    returns: 'nothing — the error is still the answer; this is for telling someone'
+  }
+]
+
+export const SCREEN_EVENT_KEYS = SCREEN_EVENTS.map((e) => e.key)
+
+/**
+ * A FLOW's "let a function decide": the function an arrow asks for the next
+ * step. Not a screen event — the workflow engine runs it, between screens.
+ */
+export const DECIDE_EVENT = 'decide'
+
+/** A function's name: what it was registered under. */
+export const FUNCTION_NAME = /^[A-Za-z_][\w.-]{0,99}$/
+
+/** The functions a screen names, as [{ event, name }] — what has to be registered for it to run. */
+export function screenFunctions(doc) {
+  const ev = (doc && doc.events) || {}
+  return SCREEN_EVENT_KEYS.filter((k) => typeof ev[k] === 'string' && ev[k]).map((k) => ({ event: k, name: ev[k] }))
+}
+
+/**
+ * Which of a screen's functions are not registered, or are registered for a
+ * different event — given the registry's list ([{ name, event }]). Empty when
+ * the screen can run. Said by name, so the fix is obvious.
+ */
+export function missingFunctions(doc, registered) {
+  const byName = new Map((registered || []).map((f) => [f.name, f]))
+  return screenFunctions(doc).flatMap(({ event, name }) => {
+    const f = byName.get(name)
+    if (!f) return [{ event, name, problem: `"${name}" is not a registered function` }]
+    if (f.event !== event) return [{ event, name, problem: `"${name}" is written for ${f.event ? `"${f.event}"` : 'a workflow step'}, not "${event}"` }]
+    return []
+  })
+}
+
+/** The screen with one event set to a function — or cleared, given nothing. */
+export function setEvent(doc, key, name) {
+  if (!SCREEN_EVENT_KEYS.includes(key)) throw new Error(`"${key}" is not an event — one of: ${SCREEN_EVENT_KEYS.join(', ')}`)
+  const events = { ...((doc && doc.events) || {}) }
+  if (name) events[key] = name
+  else delete events[key]
+  const next = { ...doc, events }
+  if (!Object.keys(events).length) delete next.events
+  return next
+}
+
+/** The functions a picker offers one event: those registered for it, by name. */
+export function functionsFor(functions, event) {
+  return (functions || []).filter((f) => f && f.event === event).slice().sort((a, b) => a.name.localeCompare(b.name))
+}

package/src/flow.js

@@ -21,6 +21,12 @@
 //       …
 //     ] }
 //
+// LET A FUNCTION DECIDE: an arrow may name one of the app's registered
+// functions (@xeplr/actions, event 'decide') instead of a step. The engine
+// asks it where to go; `targets` are the steps it may choose (none: any):
+//
+//   { when: null, decide: 'routeByAmount', targets: ['review', 'thanks'] }
+//
 // 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
@@ -55,6 +61,18 @@ export const FLOW_OPERATORS = [
 export const VALUELESS_OPERATORS = ['isEmpty', 'isNotEmpty']
 
 const KEY = /^[A-Za-z][A-Za-z0-9_]*$/
+// A registered function's name — the same rule as events.js.
+const FUNCTION = /^[A-Za-z_][\w.-]{0,99}$/
+
+/**
+ * Where an arrow can lead: its target, or — when a function decides — the
+ * steps it may choose, and every step when it lists none.
+ */
+export function arrowTargets(flow, t) {
+  if (!t) return []
+  if (t.decide) return Array.isArray(t.targets) && t.targets.length ? t.targets : flow.steps.map((s) => s.stepKey)
+  return t.target ? [t.target] : []
+}
 const MAX_KEY = 63
 
 /** An empty flow, ready to have screens dropped on it. */
@@ -126,7 +144,12 @@ export function removeStep(flow, stepKey) {
     ...flow,
     steps: flow.steps
       .filter((s) => s.stepKey !== stepKey)
-      .map((s) => ({ ...s, transitions: s.transitions.filter((t) => t.target !== stepKey) }))
+      .map((s) => ({
+        ...s,
+        transitions: s.transitions
+          .filter((t) => t.decide || t.target !== stepKey)
+          .map((t) => (t.decide && Array.isArray(t.targets) ? { ...t, targets: t.targets.filter((k) => k !== stepKey) } : t))
+      }))
   }
 }
 
@@ -162,7 +185,9 @@ export function removeTransition(flow, fromKey, 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)))
+  // A function that may go anywhere points at nothing in particular — it does
+  // not make every step look like the middle of the journey.
+  const pointedAt = new Set(flow.steps.flatMap((s) => s.transitions.flatMap((t) => (t.decide && !(t.targets && t.targets.length) ? [] : arrowTargets(flow, t)))))
   return flow.steps.find((s) => !pointedAt.has(s.stepKey)) || flow.steps[0]
 }
 
@@ -177,7 +202,7 @@ export function reachableSteps(flow) {
     const step = byKey.get(key)
     if (!step) return
     seen.add(key)
-    step.transitions.forEach((t) => walk(t.target))
+    step.transitions.forEach((t) => arrowTargets(flow, t).forEach(walk))
   }
   walk(start.stepKey)
   return seen
@@ -200,9 +225,11 @@ export function layoutFlow(flow, size = {}) {
   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)
+      arrowTargets(flow, t).forEach((target) => {
+        if (!byKey.has(target) || depth.has(target)) return
+        depth.set(target, depth.get(key) + 1)
+        queue.push(target)
+      })
     })
   }
   // Steps nothing reaches go in a column of their own at the end, where they
@@ -264,7 +291,10 @@ export function validateFlow(flow, options = {}) {
     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.decide !== undefined && t.decide !== null && t.decide !== '') {
+        if (!FUNCTION.test(String(t.decide))) err(`${tp}.decide`, 'must be the name of a registered function, e.g. "routeByAmount"')
+        if (t.targets !== undefined && !(Array.isArray(t.targets) && t.targets.every((k) => typeof k === 'string' && k))) err(`${tp}.targets`, 'must be a list of the steps the function may choose')
+      } else if (!String(t.target || '').trim()) err(`${tp}.target`, `must name the step this arrow goes to, or "${FLOW_END}" — or a function to decide`)
       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
@@ -278,6 +308,12 @@ export function validateFlow(flow, options = {}) {
   // Targets are checked once every step key is known.
   flow.steps.forEach((step, i) => {
     ;(step.transitions || []).forEach((t, j) => {
+      if (t && t.decide) {
+        ;(t.targets || []).forEach((k) => {
+          if (k !== FLOW_END && !keys.has(k)) err(`steps[${i}].transitions[${j}].targets`, `"${t.decide}" may choose "${k}", which is not a step of this flow`)
+        })
+        return
+      }
       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`)
@@ -304,6 +340,41 @@ function checkWhen(when, at, err) {
   }
 }
 
+// ── navigation: where a step goes once its screen is saved ──────────────
+//
+// What the designer's Navigation panel says, in three plain choices — the
+// common case of a step's arrows. A step whose arrows test its fields
+// ("branches") is drawn with those; the panel says so rather than flattening
+// them.
+
+/**
+ * How a step moves on:
+ *   { mode: 'screen', target }            — always to this step
+ *   { mode: 'decide', decide, targets }   — a registered function chooses
+ *   { mode: 'end' }                       — the journey finishes here
+ *   { mode: 'branches' }                  — arrows that test the screen's fields
+ *   { mode: 'none' }                      — nothing chosen yet
+ */
+export function navigationOf(step) {
+  const ts = (step && step.transitions) || []
+  if (!ts.length) return { mode: 'none' }
+  if (ts.some((t) => t.when)) return { mode: 'branches' }
+  const t = ts[0]
+  if (t.decide) return { mode: 'decide', decide: t.decide, targets: t.targets || [] }
+  if (t.target === FLOW_END) return { mode: 'end' }
+  return { mode: 'screen', target: t.target }
+}
+
+/** Sets how a step moves on — one of navigationOf's shapes (not 'branches'). */
+export function setNavigation(flow, stepKey, nav) {
+  const n = nav || {}
+  const transitions = n.mode === 'decide' ? [{ when: null, decide: n.decide || '', targets: n.targets || [] }]
+    : n.mode === 'end' ? [{ when: null, target: FLOW_END }]
+      : n.mode === 'screen' ? [{ when: null, target: n.target || '' }]
+        : []
+  return mapStep(flow, stepKey, (s) => ({ ...s, transitions }))
+}
+
 /** A test in words: "Type is contractor". */
 export function describeWhen(when, fieldLabel) {
   if (!when) return 'otherwise'

package/src/index.js

@@ -19,12 +19,16 @@ export { describeScreen, screenStub, loadScreens, keyFromName, editScreenOf, mas
 export { masterSpec, createMaster, possibleParents, singularOf, MASTER_LABEL, MASTER_ORDER, childSpec, createChildTable } from './masters.js'
 export { useFlowRun } from './useFlowRun.js'
 export { useFlowBuilder, FLOW_AUTOSAVE_DELAY } from './useFlowBuilder.js'
+// A screen's events, set from outside its builder, and the app's functions to pick from.
+export { useScreenEvents } from './useScreenEvents.js'
+export { useFunctionCatalog } from './useFunctionCatalog.js'
+export { useUrlTab } from './useUrlPlaces.js'
 
 // Designs
-export { BuilderSample, ScreenSample, ListView, ScreenModal, FlowRunnerSample, FlowBuilderSample, ScreenEditorSample, ControlView, VIEWS, Palette, DRAG_TYPE, PropertyPanel, EDITORS } from './designs/index.js'
+export { BuilderSample, ScreenSample, ListView, ScreenModal, FlowRunnerSample, FlowBuilderSample, FlowDesignerSample, FLOW_DESIGNER_TABS, ScreenEditorSample, 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, FlowRunner, FlowBuilder } from './pages.jsx'
+export { FactoryBuilder, FactoryScreen, FlowRunner, FlowBuilder, FlowDesigner } from './pages.jsx'

package/src/model.js

@@ -12,6 +12,8 @@ export {
   steppers, stepsOf, stepOf, setNodeStep, nodesForSteps, resolveStep, reachableStep, nextOpenStep
 } from './document.js'
 export { validateDocument, assertValidDocument } from './validateDocument.js'
+// A screen's events: functions picked by name, run on the server.
+export { SCREEN_EVENTS, SCREEN_EVENT_KEYS, DECIDE_EVENT, FUNCTION_NAME, screenFunctions, missingFunctions, setEvent, functionsFor } from './events.js'
 export { formSchema, initialValues, parseInput, validateValues, fieldError, sameId, optionValue, chooseable, saveState, recordValues, displayValue, fileLabel, toDbValue, fromDbValue, listColumns, listSource } from './values.js'
 export { screenFromSpec, screensFromSpec, entityNames, SPEC_HEIGHTS, ROW_GAP } from './generate.js'
 export { scaffoldEntity } from './scaffold.js'
@@ -31,5 +33,6 @@ 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
+  addTransition, setTransition, removeTransition, firstStep, reachableSteps, layoutFlow, validateFlow, describeWhen,
+  arrowTargets, navigationOf, setNavigation
 } from './flow.js'

package/src/pages.jsx

@@ -3,7 +3,10 @@ import { useFactoryBuilder } from './useFactoryBuilder.js'
 import { useFactoryScreen } from './useFactoryScreen.js'
 import { useFlowRun } from './useFlowRun.js'
 import { useFlowBuilder } from './useFlowBuilder.js'
-import { BuilderSample, ScreenSample, ScreenModal, FlowRunnerSample, FlowBuilderSample } from './designs/index.js'
+import { useScreenEvents } from './useScreenEvents.js'
+import { useFunctionCatalog } from './useFunctionCatalog.js'
+import { useUrlTab } from './useUrlPlaces.js'
+import { BuilderSample, ScreenSample, ScreenModal, FlowRunnerSample, FlowBuilderSample, FlowDesignerSample } from './designs/index.js'
 
 /**
  * The builder, ready-made. Saves itself — there is no Save button.
@@ -210,3 +213,59 @@ export function FlowBuilder(props) {
   const ctrl = useFlowBuilder(props)
   return <FlowBuilderSample ctrl={ctrl} className={props.className} style={props.style} />
 }
+
+/**
+ * The FLOW designer as a list — the screens of a journey down the left; for
+ * the one picked, its form (Form design), the app's functions that run around
+ * its records (Events) and where it goes next (Navigation). The design is
+ * FlowDesignerSample; its controllers are useFlowBuilder, useScreenEvents and
+ * useFunctionCatalog, for a custom design to use directly.
+ *
+ * @prop flow, name, screens, loadScreen, onSave, onPublish, onChange  as FlowBuilder
+ * @prop listFunctions  async () → [{ name, event, description }] — the app's registered functions
+ * @prop loadDraft      async (screenId) → { document } — a step's screen, to set its events
+ * @prop saveDraft      async (document) → void
+ * @prop publishScreen  async (document) → { version } — makes a screen's events take effect
+ * @prop builderProps   what FactoryBuilder needs for the Form design tab (createFactoryApi's builderProps)
+ * @prop urlKey         keep the selected step and tab in the URL (<urlKey>Selected, <urlKey>Tab)
+ */
+export function FlowDesigner(props) {
+  const ctrl = useFlowBuilder(props)
+  const catalog = useFunctionCatalog({ listFunctions: props.listFunctions })
+  // The step open on the right: the one picked, else the first — a journey
+  // opened with nothing in the URL shows its start, not a blank page.
+  const step = ctrl.selectedStep || ctrl.flow.steps[0] || null
+  const events = useScreenEvents({
+    screen: step ? step.screen : null,
+    loadDraft: props.loadDraft,
+    saveDraft: props.saveDraft,
+    publish: props.publishScreen,
+    functions: catalog.functions
+  })
+  const [tab, setTab] = useUrlTab(props.urlKey, 'settings')
+  return (
+    <FlowDesignerSample
+      ctrl={ctrl}
+      step={step}
+      events={events}
+      catalog={catalog}
+      tab={tab}
+      onTab={setTab}
+      className={props.className}
+      style={props.style}
+      renderFormDesign={() => (events.document ? (
+        <FactoryBuilder
+          key={events.document.id}
+          {...(props.builderProps || {})}
+          document={events.document}
+          // One draft, two editors: the builder's changes become the
+          // document Events sets functions on (useScreenEvents.adopt).
+          onChange={events.adopt}
+          screens={(props.screens || []).map((s) => ({ id: s.id, name: s.name }))}
+        />
+      ) : (
+        <div className="xeplr-factory-hint">{events.error || 'Opening the screen…'}</div>
+      ))}
+    />
+  )
+}

package/src/remote.js

@@ -97,6 +97,9 @@ export function createFactoryApi({ fetch: doFetch, base = '' } = {}) {
       confirmConvert: (options && options.confirmConvert) || []
     })),
     listTables: () => call('GET', '/tables'),
+    // The app's registered functions a screen's events — and a flow's "let a
+    // function decide" — can pick: [{ name, event, description }], never code.
+    listFunctions: () => call('GET', '/functions'),
     // DELETE A FORM'S SCREEN. The design always goes; the table only when it
     // is empty and nothing else describes it — the answer says which
     // happened, and how many records kept it. Refused while another

package/src/urlState.js

@@ -12,11 +12,11 @@
 
 /**
  * The query keys under a host's `urlKey`, or null (in memory).
- *   factoryUrlKeys('form') → { steps: 'formSteps', selected: 'formSelected' }
+ *   factoryUrlKeys('form') → { steps: 'formSteps', selected: 'formSelected', tab: 'formTab' }
  */
 export function factoryUrlKeys(urlKey) {
   if (!urlKey) return null
-  return { steps: `${urlKey}Steps`, selected: `${urlKey}Selected` }
+  return { steps: `${urlKey}Steps`, selected: `${urlKey}Selected`, tab: `${urlKey}Tab` }
 }
 
 /**

package/src/useFlowBuilder.js

@@ -1,7 +1,8 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import {
   createFlow, addStep, moveStep, setStep, removeStep,
-  addTransition, setTransition, removeTransition, validateFlow, firstStep, layoutFlow, FLOW_END
+  addTransition, setTransition, removeTransition, validateFlow, firstStep, layoutFlow, FLOW_END,
+  navigationOf, setNavigation
 } from './flow.js'
 import { inputNodes } from './document.js'
 import { useUrlSelection } from './useUrlPlaces.js'
@@ -115,6 +116,8 @@ export function useFlowBuilder({ flow: given, name, screens = [], loadScreen, on
   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])
+  /** Where a step goes once its screen is saved — a screen, a function's choice, or the end (flow.js). */
+  const changeNavigation = useCallback((stepKey, nav) => update((f) => setNavigation(f, stepKey, nav)), [update])
   /** Lays every step out by where it falls in the journey. */
   const tidy = useCallback(() => update((f) => layoutFlow(f)), [update])
 
@@ -174,6 +177,8 @@ export function useFlowBuilder({ flow: given, name, screens = [], loadScreen, on
     connect,
     setTransition: changeTransition,
     disconnect,
+    navigationOf,
+    setNavigation: changeNavigation,
     tidy,
     end: FLOW_END,
     status,

package/src/useFunctionCatalog.js

@@ -0,0 +1,41 @@
+import { useCallback, useEffect, useRef, useState } from 'react'
+import { functionsFor } from './events.js'
+
+// THE APP'S FUNCTIONS — what a screen's events and a flow's "let a function
+// decide" can pick. Registered in the app's code (@xeplr/actions, with an
+// `event`); the server lists names, events and descriptions, never code.
+// No JSX — a design draws the pickers.
+
+/**
+ * @param listFunctions  async () → [{ name, event, description }]  (createFactoryApi's listFunctions)
+ */
+export function useFunctionCatalog({ listFunctions } = {}) {
+  const [functions, setFunctions] = useState([])
+  const [loading, setLoading] = useState(Boolean(listFunctions))
+  const [error, setError] = useState(null)
+  const listRef = useRef(listFunctions); listRef.current = listFunctions
+
+  const reload = useCallback(() => {
+    if (!listRef.current) { setLoading(false); return Promise.resolve([]) }
+    setLoading(true)
+    setError(null)
+    return Promise.resolve()
+      .then(() => listRef.current())
+      .then((rows) => { const list = Array.isArray(rows) ? rows : []; setFunctions(list); return list })
+      .catch((err) => { setError(err.message || 'Could not list the app\'s functions'); return [] })
+      .finally(() => setLoading(false))
+  }, [])
+
+  useEffect(() => { reload() }, [reload])
+
+  return {
+    functions,
+    loading,
+    error,
+    reload,
+    /** The functions one event may pick, by name. */
+    forEvent: useCallback((event) => functionsFor(functions, event), [functions]),
+    /** One function by name — or null: picked once, no longer registered. */
+    byName: useCallback((name) => functions.find((f) => f.name === name) || null, [functions])
+  }
+}

package/src/useScreenEvents.js

@@ -0,0 +1,110 @@
+import { useCallback, useEffect, useRef, useState } from 'react'
+import { SCREEN_EVENTS, setEvent as withEvent, missingFunctions } from './events.js'
+
+// ONE SCREEN'S EVENTS, edited outside its builder — the flow designer's
+// "Events" panel for the screen a step shows. No JSX.
+//
+// Events belong to the SCREEN, not to the flow: a screen's records behave the
+// same in every flow that shows it. So a change here is a change to that
+// screen's draft — saved at once, like any edit in the builder — and takes
+// effect when the screen is PUBLISHED. Publishing is deliberate and separate,
+// because the draft may hold other changes (a field added in Form design).
+
+/**
+ * @param screen      the screen's id (a step's `screen`), or null
+ * @param loadDraft   async (id) → { document } — the screen's draft (createFactoryApi)
+ * @param saveDraft   async (document) → void
+ * @param publish     async (document) → { version } — refuses with the functions that are missing
+ * @param functions   [{ name, event }] — the app's registry, to say which picked ones are gone
+ */
+export function useScreenEvents({ screen, loadDraft, saveDraft, publish, functions } = {}) {
+  const [doc, setDoc] = useState(null)
+  const [loading, setLoading] = useState(false)
+  const [error, setError] = useState(null)
+  const [status, setStatus] = useState('idle')          // idle | saving | saved | error
+  const [saveError, setSaveError] = useState(null)
+  const [publishing, setPublishing] = useState(false)
+  const [publishResult, setPublishResult] = useState(null)
+  const calls = useRef({}); calls.current = { loadDraft, saveDraft, publish }
+  const docRef = useRef(null); docRef.current = doc
+
+  useEffect(() => {
+    setDoc(null); setError(null); setStatus('idle'); setPublishResult(null)
+    if (!screen || !calls.current.loadDraft) return undefined
+    let cancelled = false
+    setLoading(true)
+    Promise.resolve()
+      .then(() => calls.current.loadDraft(screen))
+      .then((row) => { if (!cancelled) setDoc((row && row.document) || row || null) })
+      .catch((err) => { if (!cancelled) setError(err.message || `Could not open "${screen}"`) })
+      .finally(() => { if (!cancelled) setLoading(false) })
+    return () => { cancelled = true }
+  }, [screen])
+
+  /** Pick a function for an event (or clear it with nothing). Saved to the draft at once. */
+  const setEvent = useCallback(async (key, name) => {
+    const current = docRef.current
+    if (!current) return
+    const next = withEvent(current, key, name)
+    setDoc(next)
+    docRef.current = next
+    setPublishResult(null)
+    if (!calls.current.saveDraft) return
+    setStatus('saving')
+    setSaveError(null)
+    try {
+      await calls.current.saveDraft(next)
+      setStatus('saved')
+    } catch (err) {
+      setSaveError(err.message || 'Could not save')
+      setStatus('error')
+    }
+  }, [])
+
+  const publishNow = useCallback(async () => {
+    const current = docRef.current
+    if (!current || !calls.current.publish) return
+    setPublishing(true)
+    setPublishResult(null)
+    try {
+      const out = await calls.current.publish(current)
+      setPublishResult({ ok: true, message: `Published${out && out.version ? ` — version ${out.version}` : ''}. These events run from the next save.` })
+    } catch (err) {
+      setPublishResult({ ok: false, message: err.message || 'Could not publish' })
+    } finally {
+      setPublishing(false)
+    }
+  }, [])
+
+  /**
+   * The screen's builder changed the same draft (Form design) — take its
+   * document as the one events are set on, so neither editor writes back a
+   * copy older than the other's.
+   */
+  const adopt = useCallback((next) => {
+    if (!next) return
+    setDoc(next)
+    docRef.current = next
+  }, [])
+
+  const events = (doc && doc.events) || {}
+  return {
+    screen,
+    document: doc,
+    loading,
+    error,
+    events,
+    /** The events a screen has, each with its contract and the function picked for it. */
+    rows: SCREEN_EVENTS.map((e) => ({ ...e, picked: events[e.key] || '' })),
+    /** Picked functions the app no longer registers, or registered for another event. */
+    missing: doc && functions ? missingFunctions(doc, functions) : [],
+    setEvent,
+    adopt,
+    status,
+    saveError,
+    canPublish: Boolean(publish) && Boolean(doc),
+    publish: publishNow,
+    publishing,
+    publishResult
+  }
+}

package/src/useUrlPlaces.js

@@ -46,3 +46,15 @@ export function useUrlSelection(urlKey) {
   }, [setValue])
   return [value, select]
 }
+
+/**
+ * [tab, setTab] — which tab of a panel is open (the flow designer's Form
+ * design / Events & navigation). Switching tabs is a switch, so it replaces
+ * the history entry. Absent from the URL is the first tab.
+ */
+export function useUrlTab(urlKey, first) {
+  const keys = factoryUrlKeys(urlKey)
+  const [value, setValue] = useUrlState(keys ? keys.tab : 'tab', { inUrl: Boolean(keys), replace: true })
+  const setTab = useCallback((next) => setValue(next === first ? null : next), [setValue, first])
+  return [value || first, setTab]
+}

package/src/validateDocument.js

@@ -10,6 +10,7 @@
 // Loud by design: a screen that half-renders — a dropdown with no options, two
 // fields writing the same key — looks like a data problem to whoever uses it.
 
+import { SCREEN_EVENT_KEYS, FUNCTION_NAME } from './events.js'
 import { CONTROLS, LABEL_VARIANTS, LIST_ACTIONS, STYLE_KEYS, SCREEN_STYLE_KEYS, LAYOUTS, MULTI_SEPARATOR, MAX_FILE_MB, STEP_LIMIT, acceptList } from './controls.js'
 import { DOCUMENT_KIND, DOCUMENT_VERSION } from './document.js'
 import { RESERVED_COLUMNS, MAX_IDENTIFIER } from './tableSchema.js'
@@ -18,7 +19,7 @@ import { FIELD_PRESETS, INPUT_TYPES, presetFor } from './presets.js'
 const FIELD_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/
 const TABLE_NAME = /^[A-Za-z_][A-Za-z0-9_.$-]*$/
 const SCREEN_ID = /^[A-Za-z0-9_-]+$/
-const DOCUMENT_KEYS = ['kind', 'version', 'id', 'name', 'source', 'units', 'aspect', 'width', 'style', 'description', 'master', 'labelField', 'params', 'nodes']
+const DOCUMENT_KEYS = ['kind', 'version', 'id', 'name', 'source', 'units', 'aspect', 'width', 'style', 'description', 'master', 'labelField', 'params', 'events', 'nodes']
 const COLOR = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i
 
 /**
@@ -71,6 +72,17 @@ export function validateDocument(doc, controls = CONTROLS) {
   // {params.<name>} as its default, so a name that is not a plain identifier
   // could never be referenced, and a duplicate would make the reference mean
   // two things.
+  // EVENTS — functions picked by name, one per event (see events.js). Whether
+  // each is REGISTERED is the server's to say, at publish and at run time:
+  // this checks only that the screen asks for something that could exist.
+  if (doc.events !== undefined) {
+    if (!doc.events || typeof doc.events !== 'object' || Array.isArray(doc.events)) err('events', `must be { ${SCREEN_EVENT_KEYS.join(', ')} } — each the name of a registered function`)
+    else Object.keys(doc.events).forEach((k) => {
+      const v = doc.events[k]
+      if (!SCREEN_EVENT_KEYS.includes(k)) err(`events.${k}`, `is not an event — one of: ${SCREEN_EVENT_KEYS.join(', ')}`)
+      else if (v !== null && v !== '' && !(typeof v === 'string' && FUNCTION_NAME.test(v))) err(`events.${k}`, 'must be the name of a registered function, e.g. "checkSalaryBand"')
+    })
+  }
   if (doc.params !== undefined) {
     if (!Array.isArray(doc.params)) err('params', 'must be a list of inputs this screen is called with')
     else {