@xeplr/ui-factory 1.7.3 → 1.8.1

package/README.md

@@ -395,6 +395,34 @@ Controllers, for a design of your own: `useFlowBuilder` (the flow, plus
 functions, `forEvent`). Model: `navigationOf`, `setNavigation`, `arrowTargets`,
 `setEvent`, `functionsFor`.
 
+## Filled in from a screen before — `{previous.<screen>.values.<field>}`
+
+In a flow, what one screen saved is handed to the screens after it as plain
+JSON, by SCREEN key (the workflow API's `previous` on every run view):
+
+```json
+{ "department_edit": { "values": { "id": "dep_42", "name": "Finance" } } }
+```
+
+A field fills itself from it with a default of
+`{previous.department_edit.values.name}` — or `.id`, the row that screen
+saved, to link to it. Pick it in the builder: **Fill in from** on any field
+offers this screen's own inputs (`{params.x}`) and every form's fields, so
+nothing is typed. Any kind of field may be filled this way, a number or a date
+too.
+
+- **No contract.** A screen not on this run's way here, or a field it does not
+  have, leaves the field empty — nothing errors. Making the names line up is
+  the flow's author's job; declared contracts between steps are the paid
+  workflow's.
+- **By screen, not by step**, because the binding lives on the screen, and a
+  screen is the same form in every flow. A screen shown twice hands over its
+  latest.
+- `FlowRunner` passes the run's `previous` to the screen; with your own design,
+  hand it to `useFactoryScreen({ previous })`. Model: `previousBinding`,
+  `resolveBinding(value, params, previous)`, `initialValues(doc, params,
+  controls, previous)`.
+
 ## Masters — the lists the rest of the app points at
 
 Departments, statuses, countries, categories. Mark a form as a master in its
@@ -545,6 +573,21 @@ run is only what the arrows need and the id of the row that was written
 that exists, arrows that point somewhere, one "otherwise" at the end, and
 nothing unreachable.
 
+### A review screen inside a workflow
+
+A screen can also be one step of an ordinary Xeplr Workflow: the run parks on it until a person answers. The workflow step says what it is handed, who answers it and with which buttons:
+
+```json
+{ "actionName": "screen-show", "kind": "wait",
+  "values": { "screen": "unmatched_review", "values": { "lines": "{steps.match.output.rows}" },
+              "assignTo": "Accounts", "buttons": [{ "key": "approve", "label": "Approve" }, { "key": "send_back", "label": "Send back" }] } }
+```
+
+- **A `table` shows what it was handed** (`rows: '{params.lines}'`, a screen input), with a tick per row; the ticked rows are the field's value (`selected`).
+- **The step's buttons replace Next** in `FlowRunner` (the first is the main one). The one pressed is sent as `action` and becomes the step's `output.action`, so its arrows branch on it.
+- **A screen with no table of its own saves nothing**: a button goes straight to the run.
+- `createFlowsApi(...).waiting()` lists every screen waiting for one of the signed-in person's roles (`GET /flows/waiting`).
+
 ### A flow and a stepper
 
 Both walk someone through something, and they answer different questions:
@@ -574,6 +617,7 @@ Both walk someone through something, and they answer different questions:
 | `stepper` | — | a journey across the top; every other control says which step it is on |
 | `label` | — | text with a heading, subheading or text preset |
 | `list` | — | saved records, with New / Edit / Delete |
+| `table` | array of the rows ticked | `minItems`, `maxItems`; `required` = at least one. Rows the screen is **handed** (`rows: '{params.lines}'`), not a table it reads; `columns` (`ref, amount`) or every key of the first row; `selectable` (a tick per row, on by default). Adds no column — see below |
 | `subform` | — | another form drawn inside this one (palette: **Form**), saving into its own table — see below |
 
 A screen is a **sheet**, centred in the space it is given and shown at its

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xeplr/ui-factory",
-  "version": "1.7.3",
+  "version": "1.8.1",
   "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/controls.js

@@ -95,6 +95,10 @@ const FIELD_BASICS = (extra) => ({
     { path: 'props.label', label: 'Label', type: 'text' },
     { path: 'props.name', label: 'Field name', type: 'text', help: 'The key this value is saved under — letters, digits and _' },
     ...(extra || []),
+    // FILLED IN WHEN THE SCREEN OPENS, from somewhere else — the same
+    // props.default, holding a binding instead of a typed value.
+    { path: 'props.default', label: 'Fill in from', type: 'fillFrom',
+      help: 'What this screen is called with, or — in a flow — what a screen before this one saved. Nothing is checked: a screen not on the way here leaves it empty.' },
     { path: 'props.required', label: 'Required', type: 'toggle' }
   ]
 })
@@ -572,6 +576,59 @@ CONTROLS.list = {
   ]
 }
 
+// A TABLE OF ROWS THE WORKFLOW HANDS THE SCREEN — the unmatched bank lines
+// a person reviews — with a tick per row. Its value is the rows ticked, under
+// its name (default `selected`), so the step's output.selected is what the
+// person chose. The rows come from a binding to the screen's inputs
+// (`rows: '{params.lines}'`), filled by the workflow step's `values`.
+//
+// Not a list: a list reads a database table; this shows what the run already
+// has, and saves nothing of its own (no column: columnForField ignores it).
+CONTROLS.table = {
+  type: 'table',
+  label: 'Table',
+  group: 'Data',
+  input: true,
+  valueType: 'array',
+  defaultSize: { w: 0.92, h: 0.42 },
+  defaults: { label: 'Rows', rows: '{params.rows}', selectable: true, columns: '' },
+  props: ['name', 'label', 'required', 'rows', 'columns', 'selectable', 'validation', 'style'],
+  validation: ['minItems', 'maxItems'],
+  styles: ['fontFamily', 'fontSize', 'color', 'background', 'borderColor', 'borderWidth', 'borderRadius'],
+  properties: [
+    FIELD_BASICS(),
+    {
+      key: 'table',
+      title: 'Rows',
+      fields: [
+        { path: 'props.rows', label: 'Rows from', type: 'text',
+          help: 'One of this screen\'s inputs, e.g. {params.lines}. The workflow step fills it.' },
+        { path: 'props.columns', label: 'Columns', type: 'text',
+          help: 'Which, in order, e.g. ref, amount, date. Blank: every column of the first row.' },
+        { path: 'props.selectable', label: 'A tick per row', type: 'checkbox',
+          help: 'The ticked rows are what this field gives the workflow.' }
+      ]
+    },
+    {
+      key: 'validation',
+      title: 'Validation',
+      fields: [
+        { path: 'props.validation.minItems', label: 'Tick at least', type: 'number' },
+        { path: 'props.validation.maxItems', label: 'Tick at most', type: 'number' }
+      ]
+    },
+    ...styleGroups(['fontFamily', 'fontSize', 'color', 'background', 'borderColor', 'borderWidth', 'borderRadius'])
+  ]
+}
+
+/** The columns a table shows: its own list, else every key of the first row. */
+export function tableColumns(p, rows) {
+  const listed = String((p && p.columns) || '').split(',').map((c) => c.trim()).filter(Boolean)
+  if (listed.length) return listed
+  const first = (rows || []).find((r) => r && typeof r === 'object')
+  return first ? Object.keys(first) : []
+}
+
 // A FORM INSIDE THIS ONE — Access's subform. Another published form, drawn
 // inline with its own fields, saving into ITS OWN table: this employee's bank
 // details. One record of it belongs to each record of this one, through

package/src/designs/BuilderSample.jsx

@@ -29,7 +29,9 @@ const STATUS = {
   error: 'Not saved'
 }
 
-export default function BuilderSample({ ctrl, renderPreview, className, style }) {
+// screenApi: the app's factory API client, for designing a child table in place.
+// forms: the app's forms and their fields (useFormFields), for "Fill in from".
+export default function BuilderSample({ ctrl, renderPreview, className, style, screenApi, forms }) {
   const { document: doc } = ctrl
   const [preview, setPreview] = useState(false)
   const problemCount = ctrl.validation.errors.length
@@ -272,6 +274,7 @@ export default function BuilderSample({ ctrl, renderPreview, className, style })
             errors={ctrl.selectedNode ? ctrl.errorsByNode[ctrl.selectedNode.id] : ctrl.errorsByNode._document}
             tables={ctrl.tables}
             screens={ctrl.screens}
+            forms={forms}
             lockedNames={ctrl.lockedNames}
             onChange={(path, value) => (
               // A list's table is not an ordinary property: changing it makes

package/src/designs/ControlView.jsx

@@ -1,5 +1,5 @@
 import { useState } from 'react'
-import { LABEL_PRESETS } from '../controls.js'
+import { tableColumns, LABEL_PRESETS } from '../controls.js'
 import { stepsOf } from '../document.js'
 import ListView from './ListView.jsx'
 import { fieldStyle, labelStyle, boxStyle } from './styles.js'
@@ -13,7 +13,7 @@ import { fieldStyle, labelStyle, boxStyle } from './styles.js'
 
 const ids = (node) => `xeplr-factory-${node.id}`
 
-export default function ControlView({ node, mode = 'live', value, error, options, onChange, onBlur, disabled, list, upload, stepper, subform }) {
+export default function ControlView({ node, mode = 'live', value, error, options, onChange, onBlur, disabled, list, upload, stepper, subform, rows }) {
   const View = VIEWS[node.type]
   if (!View) {
     return <div className="xeplr-factory-unknown">Unknown control “{node.type}”</div>
@@ -34,6 +34,7 @@ export default function ControlView({ node, mode = 'live', value, error, options
       upload={upload}
       stepper={stepper}
       subform={subform}
+      rows={rows}
     />
   )
 }
@@ -459,6 +460,65 @@ function SubformView({ p, node, design, subform }) {
   )
 }
 
+// Rows the workflow handed the screen, a tick per row. The value is the rows
+// ticked. In the designer: three placeholder rows, so it reads as a table.
+function TableView({ node, p, design, value, error, onChange, disabled, rows }) {
+  const shown = design ? [{ ref: 'A1', amount: 500 }, { ref: 'A2', amount: 20 }, { ref: 'A3', amount: 75 }] : (rows || [])
+  const columns = tableColumns(p, shown)
+  const chosen = Array.isArray(value) ? value : []
+  const selectable = p.selectable !== false
+  const ticked = (row) => chosen.some((c) => c === row || JSON.stringify(c) === JSON.stringify(row))
+  const toggle = (row, on) => {
+    const rest = chosen.filter((c) => !(c === row || JSON.stringify(c) === JSON.stringify(row)))
+    onChange(on ? [...rest, row] : rest)
+  }
+  const all = shown.length > 0 && shown.every(ticked)
+  const text = boxStyle(p.style)
+  return (
+    <Field node={node} p={p} error={error}>
+      <div className="xeplr-factory-table-wrap" role="group" aria-labelledby={`${ids(node)}-label`}>
+        {shown.length === 0 ? (
+          <div className="xeplr-factory-hint">Nothing to show.</div>
+        ) : (
+          <table className="xeplr-factory-table" style={{ fontSize: text.fontSize, color: text.color }}>
+            <thead>
+              <tr>
+                {selectable && (
+                  <th className="xeplr-factory-table-tick">
+                    <input type="checkbox" aria-label="Tick every row" checked={all} disabled={disabled}
+                      onChange={(e) => onChange(e.target.checked ? shown.slice() : [])} />
+                  </th>
+                )}
+                {columns.map((c) => <th key={c}>{c}</th>)}
+              </tr>
+            </thead>
+            <tbody>
+              {shown.map((row, i) => (
+                <tr key={i} className={selectable && ticked(row) ? 'is-ticked' : undefined}>
+                  {selectable && (
+                    <td className="xeplr-factory-table-tick">
+                      <input type="checkbox" aria-label={'Row ' + (i + 1)} checked={ticked(row)} disabled={disabled}
+                        onChange={(e) => toggle(row, e.target.checked)} />
+                    </td>
+                  )}
+                  {columns.map((c) => {
+                    const v = row ? row[c] : null
+                    return <td key={c} className={typeof v === 'number' ? 'is-number' : undefined}>{v === null || v === undefined ? '' : typeof v === 'object' ? JSON.stringify(v) : String(v)}</td>
+                  })}
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        )}
+      </div>
+      {!design && selectable && shown.length > 0 && (
+        <div className="xeplr-factory-hint">{chosen.length} of {shown.length} ticked</div>
+      )}
+      {design && <div className="xeplr-factory-hint">Rows from {p.rows || '— set "Rows from"'}</div>}
+    </Field>
+  )
+}
+
 function ListControl({ node, design, list }) {
   return <ListView node={node} design={design} {...(list || {})} />
 }
@@ -478,5 +538,6 @@ export const VIEWS = {
   stepper: StepperView,
   label: LabelView,
   list: ListControl,
+  table: TableView,
   subform: SubformView
 }

package/src/designs/FlowRunnerSample.jsx

@@ -1,7 +1,8 @@
 import { useRef } from 'react'
 import ScreenSample from './ScreenSample.jsx'
 
-// A flow, running: the screen the run is parked on, and one button forward.
+// A flow, running: the screen the run is parked on, and the way forward — one
+// Next, or the step's own buttons (Approve / Send back), each saying which.
 //
 // Presentation only — everything comes from useFlowRun and useFactoryScreen.
 // "Next" saves the screen into its own table (one AJAX call, only if anything
@@ -49,8 +50,11 @@ export default function FlowRunnerSample({ run, screen, className, style, title,
           // not two that both look like the way on.
           // The id comes from the save that Next just made when there was one:
           // a new record's id has not reached the ref yet (that is a render away).
-          done: (r) => run.submit(values.current, r && r.record && r.record[screen.recordKey] != null ? r.record[screen.recordKey] : record.current),
-          doneLabel: run.sending ? 'Saving…' : 'Next'
+          done: (r, action) => run.submit(values.current, r && r.record && r.record[screen.recordKey] != null ? r.record[screen.recordKey] : record.current, action),
+          doneLabel: run.sending ? 'Saving…' : 'Next',
+          // The step's own buttons, when it has them: each is a way on.
+          doneButtons: run.buttons && run.buttons.length ? run.buttons : null,
+          sending: run.sending
         }}
       />
       <FlowValues screen={screen} values={values} record={record} />

package/src/designs/PropertyPanel.jsx

@@ -1,7 +1,8 @@
 import { useEffect, useState } from 'react'
 import { getAtPath } from '../propertyPath.js'
 import { FIELD_PRESETS, presetFor } from '../presets.js'
-import { slugify, inputNodes, paramsText } from '../document.js'
+import { slugify, inputNodes, paramsText, screenParams } from '../document.js'
+import { isBinding, previousBinding } from '../values.js'
 import { FONT_FAMILIES, STYLE_KEYS, SCREEN_STYLE_KEYS, LIST_ACTIONS, FILE_KINDS } from '../controls.js'
 
 // The selected control's properties, GENERATED from its entry in controls.js:
@@ -58,7 +59,7 @@ function FieldType({ node, controls, hint, onConvert, onKeepPlain }) {
   )
 }
 
-export default function PropertyPanel({ doc, node, control, controls, errors, tables, screens, lockedNames, onChange, onConvert, hint, onScreenChange, onRemove, onMakeChildTable, selectionCount }) {
+export default function PropertyPanel({ doc, node, control, controls, errors, tables, screens, forms, lockedNames, onChange, onConvert, hint, onScreenChange, onRemove, onMakeChildTable, selectionCount }) {
   if (selectionCount > 1) {
     return (
       <aside className="xeplr-factory-panel">
@@ -95,17 +96,22 @@ export default function PropertyPanel({ doc, node, control, controls, errors, ta
             // A field name that is already a column cannot change — see setNodeProperty.
             const locked = field.path === 'props.name' && (lockedNames || []).includes(node.props?.name)
             const Editor = locked ? LockedEditor : (EDITORS[field.type] || TextEditor)
-            const id = `xf-prop-${node.id}-${field.path.replace(/\W+/g, '-')}`
+            const id = `xf-prop-${node.id}-${field.path.replace(/\W+/g, '-')}-${field.type}`
+            // A default that is a BINDING belongs to "Fill in from"; the typed
+            // box beside it shows empty rather than the binding's braces.
+            const raw = getAtPath(node, field.path)
+            const value = field.path === 'props.default' && field.type !== 'fillFrom' && isBinding(raw) ? undefined : raw
             return (
-              <div key={field.path} className={`xeplr-factory-prop${errs.length ? ' has-error' : ''}`}>
+              <div key={field.path + ':' + field.type} className={`xeplr-factory-prop${errs.length ? ' has-error' : ''}`}>
                 {field.type !== 'toggle' && field.type !== 'toggleValue' && field.type !== 'columns' && field.type !== 'actions' && <label className="xeplr-factory-prop-label" htmlFor={id}>{field.label}</label>}
                 <Editor
                   id={id}
                   field={field}
-                  value={getAtPath(node, field.path)}
+                  value={value}
                   onChange={(v) => onChange(field.path, v)}
                   tables={tables}
                   screens={screens}
+                  forms={forms}
                   node={node}
                   doc={doc}
                   errors={errs}
@@ -568,6 +574,43 @@ function FormEditor({ id, value, onChange, screens, doc }) {
   return <input id={id} className="xeplr-factory-prop-input xeplr-factory-mono" type="text" placeholder="bank_details_edit" value={value ?? ''} onChange={(e) => onChange(e.target.value.trim() || undefined)} />
 }
 
+/**
+ * FILL IN FROM — a field's default as a BINDING, picked, never typed: what
+ * this screen is called with ({params.x}), or what a screen before it in a
+ * flow saved ({previous.<screen>.values.<field>}). Picking "nothing" clears
+ * only a binding; a typed default value is left alone.
+ */
+function FillFromEditor({ id, value, onChange, doc, forms }) {
+  const bound = isBinding(value) ? value : ''
+  const inputs = doc ? screenParams(doc) : []
+  const others = (forms || []).filter((f) => !doc || f.key !== doc.id)
+  const offered = new Set([
+    ...inputs.map((p) => `{params.${p.name}}`),
+    ...others.flatMap((f) => f.fields.map((x) => previousBinding(f.key, x.name)))
+  ])
+  return (
+    <select
+      id={id}
+      className="xeplr-factory-prop-input"
+      value={bound}
+      onChange={(e) => { if (e.target.value || bound) onChange(e.target.value || undefined) }}
+    >
+      <option value="">Nothing — empty, or the default value</option>
+      {inputs.length > 0 && (
+        <optgroup label="What this screen is called with">
+          {inputs.map((p) => <option key={p.name} value={`{params.${p.name}}`}>{p.label || p.name}</option>)}
+        </optgroup>
+      )}
+      {others.map((f) => (
+        <optgroup key={f.key} label={`${f.name} — a screen before this one`}>
+          {f.fields.map((x) => <option key={x.name} value={previousBinding(f.key, x.name)}>{f.name} → {x.label}</option>)}
+        </optgroup>
+      ))}
+      {bound && !offered.has(bound) && <option value={bound}>{bound}</option>}
+    </select>
+  )
+}
+
 const ACTION_LABELS = { new: 'New — add a record', edit: 'Edit — open a row for editing', delete: 'Delete — remove a row' }
 
 function ActionsEditor({ value, onChange }) {
@@ -751,6 +794,7 @@ export const EDITORS = {
   table: TableEditor,
   screen: ScreenEditor,
   form: FormEditor,
+  fillFrom: FillFromEditor,
   columns: ColumnsEditor,
   listTable: ListTableEditor,
   actions: ActionsEditor,

package/src/designs/ScreenSample.jsx

@@ -100,6 +100,22 @@ function StepNav({ ctrl, node, status, children }) {
  */
 function SaveButtons({ ctrl }) {
   const saving = ctrl.status === 'saving'
+  // A WORKFLOW STEP'S OWN BUTTONS (Approve / Send back): each saves what is
+  // unsaved, then moves the run on, saying which was pressed — its arrows
+  // branch on it. The first is the main one.
+  if (ctrl.doneButtons && ctrl.doneButtons.length) {
+    return (
+      <>
+        {ctrl.doneButtons.slice().reverse().map((b, i, list) => (
+          <button key={b.key} type="button" disabled={saving || ctrl.sending}
+            className={i === list.length - 1 ? 'xeplr-factory-primary' : 'xeplr-factory-secondary'}
+            onClick={() => ctrl.flush().then((r) => { if (r && r.ok) ctrl.done(r, b.key) })}>
+            {b.label}
+          </button>
+        ))}
+      </>
+    )
+  }
   if (ctrl.doneLabel) {
     return (
       <button type="button" className="xeplr-factory-primary" disabled={saving}
@@ -184,6 +200,7 @@ export default function ScreenSample({ ctrl, className, style, renderPopup, rend
               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}
+              rows={node.type === 'table' && ctrl.rowsFor ? ctrl.rowsFor(node) : undefined}
               stepper={node.type === 'stepper' ? {
                 active: ctrl.steps.active(node.id),
                 isDisabled: (i) => ctrl.steps.isDisabled(node.id, i),

package/src/designs/factory.css

@@ -636,3 +636,12 @@
 .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; }
+
+/* A table of rows the workflow handed the screen, a tick per row. */
+.xeplr-factory-table-wrap { overflow: auto; max-height: 100%; border: 1px solid var(--xf-border); border-radius: 6px; }
+.xeplr-factory-table { width: 100%; border-collapse: collapse; font-size: max(11px, calc(12 * var(--xf-u))); }
+.xeplr-factory-table th, .xeplr-factory-table td { text-align: left; padding: 6px 8px; border-bottom: 1px solid var(--xf-border); white-space: nowrap; }
+.xeplr-factory-table th { position: sticky; top: 0; background: var(--xeplr-bg-secondary, #fff); color: var(--xf-muted); font-weight: 600; }
+.xeplr-factory-table td.is-number { text-align: right; font-variant-numeric: tabular-nums; }
+.xeplr-factory-table tr.is-ticked td { background: var(--xeplr-accent-soft, rgba(47, 91, 211, 0.07)); }
+.xeplr-factory-table-tick { width: 28px; }

package/src/flows.js

@@ -101,7 +101,9 @@ export function createFlowsApi({ fetch: doFetch, base = '' } = {}) {
     startRun: async (key) => one(await call('POST', `/${enc(key)}/runs`)),
     loadRun: async (runId) => one(await call('GET', `/runs/${enc(runId)}`)),
     /** What the person filled in. Answers with the next screen, or that it is done. */
-    submitRun: async (runId, values, recordId) => one(await call('POST', `/runs/${enc(runId)}/submit`, { values, recordId })),
+    submitRun: async (runId, values, recordId, action) => one(await call('POST', `/runs/${enc(runId)}/submit`, action ? { values, recordId, action } : { values, recordId })),
+    /** Every screen waiting for one of the signed-in person's roles, in any workflow. */
+    waiting: () => call('GET', '/waiting'),
     /** Journeys of this flow that are still going — "in progress". */
     myRuns: (key) => call('GET', `/${enc(key)}/runs?mine=1`)
   }

package/src/index.js

@@ -23,6 +23,8 @@ export { useFlowBuilder, FLOW_AUTOSAVE_DELAY } from './useFlowBuilder.js'
 export { useScreenEvents } from './useScreenEvents.js'
 export { useFunctionCatalog } from './useFunctionCatalog.js'
 export { useUrlTab } from './useUrlPlaces.js'
+// The app's forms and their fields — what "Fill in from" offers.
+export { useFormFields } from './useFormFields.js'
 
 // Designs
 export { BuilderSample, ScreenSample, ListView, ScreenModal, FlowRunnerSample, FlowBuilderSample, FlowDesignerSample, FLOW_DESIGNER_TABS, ScreenEditorSample, ControlView, VIEWS, Palette, DRAG_TYPE, PropertyPanel, EDITORS } from './designs/index.js'

package/src/model.js

@@ -25,7 +25,7 @@ export {
   createStatements, addStatements, alterStatement, dropStatement, columnFromDatabase, planTableChange, conversionFor
 } from './tableSchema.js'
 // A value with a {params.x} token is a binding; a plain value is a literal.
-export { resolveBinding, isBinding } from './values.js'
+export { resolveBinding, isBinding, previousBinding } from './values.js'
 // A code people can read out, unlike the record's own key.
 export { codeFields, countedFields, generateCode } from './values.js'
 export { FIELD_PRESETS, PATTERNS, INPUT_TYPES, presetFor, presetProps, suggestPreset, presetGroup, presetHints, convertField } from './presets.js'

package/src/pages.jsx

@@ -3,6 +3,7 @@ import { useFactoryBuilder } from './useFactoryBuilder.js'
 import { useFactoryScreen } from './useFactoryScreen.js'
 import { useFlowRun } from './useFlowRun.js'
 import { useFlowBuilder } from './useFlowBuilder.js'
+import { useFormFields } from './useFormFields.js'
 import { useScreenEvents } from './useScreenEvents.js'
 import { useFunctionCatalog } from './useFunctionCatalog.js'
 import { useUrlTab } from './useUrlPlaces.js'
@@ -27,9 +28,12 @@ import { BuilderSample, ScreenSample, ScreenModal, FlowRunnerSample, FlowBuilder
  */
 export function FactoryBuilder(props) {
   const ctrl = useFactoryBuilder(props)
+  // The app's forms and their fields, for a field's "Fill in from".
+  const forms = useFormFields(props.screenApi)
   return (
     <BuilderSample
       ctrl={ctrl}
+      forms={forms}
       className={props.className}
       style={props.style}
       // So a child table made here can be designed here — see the modal in
@@ -174,7 +178,10 @@ export function FlowRunner(props) {
     record: run.values || undefined,
     // What the flow called this screen with — its step's own input, resolved
     // by the engine. A field bound to {params.x} is filled from here.
-    params: run.given || undefined
+    params: run.given || undefined,
+    // What the screens before this one saved, by screen key — a field bound to
+    // {previous.<screen>.values.<field>} is filled from here.
+    previous: run.previous || undefined
   })
   return (
     <FlowRunnerSample

package/src/useFactoryScreen.js

@@ -2,7 +2,7 @@ import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import { CONTROLS, CHOICE_TYPES } from './controls.js'
 import { inputNodes, nodesForSteps, steppers, stepsOf, stepOf, resolveStep, reachableStep, nextOpenStep } from './document.js'
 import { validateDocument } from './validateDocument.js'
-import { initialValues, parseInput, saveState, fieldError, optionValue, recordValues, listSource } from './values.js'
+import { initialValues, parseInput, saveState, fieldError, optionValue, recordValues, listSource, resolveBinding } from './values.js'
 import { hookMethod } from './hooks.js'
 import { useUrlSteps } from './useUrlPlaces.js'
 
@@ -67,10 +67,14 @@ import { useUrlSteps } from './useUrlPlaces.js'
  *   the form from a list supplies nothing. A field whose default is
  *   `{params.x}` is filled from here, and left empty (for the person to fill
  *   in) when nobody said.
+ * @param previous  in a flow, what the screens before this one saved, by
+ *   screen key: { department_edit: { values: { id, name, … } } }. A field
+ *   whose default is `{previous.department_edit.values.name}` is filled from
+ *   here — empty when that screen was not on this run's path.
  */
 export function useFactoryScreen({
   document: doc, record, recordKey = 'id', onSave, fetchOptions, fetchRecords, fetchRecord, onDelete, onChange, screens, loadScreen, hooks, uploadFile, fileUrl,
-  onOpenRecord, onDone, onDirtyChange, params, urlKey,
+  onOpenRecord, onDone, onDirtyChange, params, urlKey, previous,
   link, onReady,
   controls = CONTROLS
 } = {}) {
@@ -134,9 +138,9 @@ export function useFactoryScreen({
   // reopened wins, because the row is the truth once there is one.
   const startValues = useCallback(
     (rec) => (rec
-      ? { ...initialValues(doc, params || {}, controls), ...recordValues(doc, rec, controls) }
-      : initialValues(doc, params || {}, controls)),
-    [doc, controls, params]
+      ? { ...initialValues(doc, params || {}, controls, previous), ...recordValues(doc, rec, controls) }
+      : initialValues(doc, params || {}, controls, previous)),
+    [doc, controls, params, previous]
   )
 
   const [values, setValues] = useState(() => (check.ok ? startValues(record) : {}))
@@ -334,6 +338,13 @@ export function useFactoryScreen({
     return out
   }, [doc.id])
 
+  // A table's rows: its binding to this screen's inputs (`{params.lines}`),
+  // filled by whoever opened it — a workflow step's values.
+  const rowsFor = useCallback((node) => {
+    const rows = resolveBinding(node && node.props ? node.props.rows : undefined, params || {}, previous)
+    return Array.isArray(rows) ? rows : []
+  }, [params, previous])
+
   const optionsFor = useCallback((node) => {
     if (node.props.data?.source === 'static') return { loading: false, items: node.props.data.options, error: null }
     return options[node.id] || { loading: false, items: [], error: null }
@@ -392,7 +403,9 @@ export function useFactoryScreen({
     if (!subsOk) { setStatus('invalid'); return { ok: false } }
     const customSave = hooksRef.current && typeof hooksRef.current.save === 'function'
     const writing = changes.current
-    if (!l.onSave && !customSave) { savedChanges.current = writing; setDirty(false); setStatus('saved'); return { ok: true } }
+    // Nothing to save to: no save given, or a screen with no table of its own
+    // (a review screen in a workflow, whose values go only to the run).
+    if ((!l.onSave || !l.source) && !customSave) { savedChanges.current = writing; setDirty(false); setStatus('saved'); return { ok: true } }
 
     setStatus('saving')
     setSaveError(null)
@@ -778,6 +791,7 @@ export function useFactoryScreen({
     setValue,
     touch,
     optionsFor,
+    rowsFor,
     done: onDone || null,
     steps: stepControl,
     visibleNodes,

package/src/useFlowRun.js

@@ -15,8 +15,9 @@ import { useCallback, useEffect, useRef, useState } from 'react'
  * @param flowKey    which flow to run (starting one, or picking up a run)
  * @param runId      an existing run to continue — omit to start one
  * @param startRun   async (flowKey) → { runId, status, stepKey, screen }
- * @param loadRun    async (runId) → { runId, status, stepKey, screen, values, given }
- * @param submitRun  async (runId, values, recordId) → { status, stepKey, screen }
+ * @param loadRun    async (runId) → { runId, status, stepKey, screen, values, given, previous }
+ * @param submitRun  async (runId, values, recordId, action) → { status, stepKey, screen }
+ *                   (action: the button pressed, when the step has buttons)
  * @param loadScreen async (key) → the screen document
  * @param onStep     (step) → void — told each time the run moves, for the address bar
  * @param onFinish   (run) → void — the journey is over
@@ -25,7 +26,7 @@ export function useFlowRun({ flowKey, runId, startRun, loadRun, submitRun, loadS
   // `given` is what the flow called this screen with — the step's own input,
   // resolved by the engine (see @xeplr/workflow's screen-show). A field bound
   // to {params.x} is filled from it.
-  const [state, setState] = useState({ loading: true, error: null, runId: runId || null, status: null, stepKey: null, screen: null, document: null, values: null, given: null })
+  const [state, setState] = useState({ loading: true, error: null, runId: runId || null, status: null, stepKey: null, screen: null, document: null, values: null, given: null, previous: null, buttons: null })
   const [sending, setSending] = useState(false)
   const live = useRef({})
   live.current = { startRun, loadRun, submitRun, loadScreen, onStep, onFinish, flowKey }
@@ -43,7 +44,11 @@ export function useFlowRun({ flowKey, runId, startRun, loadRun, submitRun, loadS
     setState({
       loading: false, error: null,
       runId: run.runId, status: run.status || 'running', stepKey: run.stepKey, screen: run.screen,
-      document: doc, values: run.values || null, given: run.given || null
+      // previous: what the screens before this one saved, by screen key —
+      // what {previous.<screen>.values.<field>} defaults fill from.
+      document: doc, values: run.values || null, given: run.given || null, previous: run.previous || null,
+      // The step's buttons ([{ key, label }]); none is one Next.
+      buttons: Array.isArray(run.buttons) && run.buttons.length ? run.buttons : null
     })
     if (live.current.onStep) live.current.onStep(run)
   }, [])
@@ -71,11 +76,11 @@ export function useFlowRun({ flowKey, runId, startRun, loadRun, submitRun, loadS
    * next; `recordId` is the row the screen just saved, so later steps and
    * their arrows can refer to it.
    */
-  const submit = useCallback(async (values, recordId) => {
+  const submit = useCallback(async (values, recordId, action) => {
     if (!live.current.submitRun) throw new Error('No submitRun was provided')
     setSending(true)
     try {
-      const next = await live.current.submitRun(state.runId, values || {}, recordId)
+      const next = await live.current.submitRun(state.runId, values || {}, recordId, action)
       await open({ runId: state.runId, ...next })
     } catch (err) {
       setState((s) => ({ ...s, error: err.message || 'That could not be sent' }))

package/src/useFormFields.js

@@ -0,0 +1,37 @@
+import { useEffect, useState } from 'react'
+import { inputNodes } from './document.js'
+
+// THE APP'S FORMS AND THEIR FIELDS — what a field's "Fill in from" picker
+// offers: in a flow, a screen before this one, and what it saved. No JSX.
+//
+// Every published screen that has fields of its own (a list screen has none),
+// each with `id` — the row it saved — then its fields by the name they are
+// saved under. Loaded once per builder, through the app's own API client.
+
+/**
+ * @param api  a createFactoryApi() instance (builderProps.screenApi)
+ * @returns [{ key, name, fields: [{ name, label }] }]
+ */
+export function useFormFields(api) {
+  const [forms, setForms] = useState([])
+  useEffect(() => {
+    if (!api || !api.listScreens || !api.loadScreen) return undefined
+    let gone = false
+    Promise.resolve()
+      .then(() => api.listScreens())
+      .then((rows) => Promise.all((rows || []).filter((r) => r && r.version).map(async (r) => {
+        try {
+          const doc = await api.loadScreen(r.screenKey)
+          const fields = inputNodes(doc).map((n) => ({ name: n.props.name, label: n.props.label || n.props.name }))
+          if (!fields.length) return null
+          return { key: doc.id, name: doc.name || doc.id, fields: [{ name: 'id', label: 'the row it saved (id)' }, ...fields] }
+        } catch (err) {
+          return null
+        }
+      })))
+      .then((list) => { if (!gone) setForms(list.filter(Boolean)) })
+      .catch(() => { /* the picker then offers this screen's own inputs only */ })
+    return () => { gone = true }
+  }, [api])
+  return forms
+}

package/src/validateDocument.js

@@ -15,6 +15,7 @@ import { CONTROLS, LABEL_VARIANTS, LIST_ACTIONS, STYLE_KEYS, SCREEN_STYLE_KEYS,
 import { DOCUMENT_KIND, DOCUMENT_VERSION } from './document.js'
 import { RESERVED_COLUMNS, MAX_IDENTIFIER } from './tableSchema.js'
 import { FIELD_PRESETS, INPUT_TYPES, presetFor } from './presets.js'
+import { isBinding } from './values.js'
 
 const FIELD_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/
 const TABLE_NAME = /^[A-Za-z_][A-Za-z0-9_.$-]*$/
@@ -210,6 +211,10 @@ function checkGeometry(node, at, err) {
 function checkDefault(node, def, at, err) {
   const v = node.props.default
   if (v === undefined) return
+  // A BINDING fills the field when the screen opens — {params.x} or
+  // {previous.<screen>.values.<field>} — so it is text whatever the field
+  // holds. A date or number field may be filled from one as well.
+  if (isBinding(v)) return
   const isDatetime = node.type === 'datetime'
   const ok = {
     string: () => typeof v === 'string',

package/src/values.js

@@ -61,33 +61,50 @@ export function formSchema(doc, controls = CONTROLS) {
  * Whole-value only. `{params.a}-{params.b}` is not a value a form field takes,
  * and splicing text is a formula's job, not a form's.
  */
-export function resolveBinding(value, params) {
+export function resolveBinding(value, params, previous) {
   if (typeof value !== 'string') return value
-  const m = /^\{params\.([A-Za-z_][\w]*)\}$/.exec(value.trim())
-  if (!m) return value
-  return params ? params[m[1]] : undefined
+  const v = value.trim()
+  const p = PARAM_BINDING.exec(v)
+  if (p) return params ? params[p[1]] : undefined
+  // WHAT A SCREEN BEFORE THIS ONE SAVED, in a flow — by that screen's key, the
+  // saved row as `id`. Handed over as plain JSON with no contract: a screen
+  // not reached on this run, or a field it does not have, is simply empty.
+  const q = PREVIOUS_BINDING.exec(v)
+  if (q) {
+    const screen = previous && previous[q[1]]
+    return screen && screen.values ? screen.values[q[2]] : undefined
+  }
+  return value
 }
 
-/** Is this what somebody typed, or a reference to an input? */
+const PARAM_BINDING = /^\{params\.([A-Za-z_][\w]*)\}$/
+const PREVIOUS_BINDING = /^\{previous\.([A-Za-z][A-Za-z0-9_]*)\.values\.([A-Za-z_][\w]*)\}$/
+
+/** Is this what somebody typed, or a reference — to an input, or to a screen before this one? */
 export function isBinding(value) {
-  return typeof value === 'string' && /^\{params\.[A-Za-z_][\w]*\}$/.test(value.trim())
+  return typeof value === 'string' && (PARAM_BINDING.test(value.trim()) || PREVIOUS_BINDING.test(value.trim()))
 }
 
-export function initialValues(doc, provided = {}, controls = CONTROLS) {
+/** The binding to a field a screen before this one saved: `{previous.<screen>.values.<field>}`. */
+export function previousBinding(screen, field) {
+  return `{previous.${screen}.values.${field}}`
+}
+
+export function initialValues(doc, provided = {}, controls = CONTROLS, previous = null) {
   const out = {}
   inputNodes(doc, controls).forEach((node) => {
     const name = node.props.name
     if (provided[name] !== undefined) out[name] = provided[name]
     else if (node.props.default !== undefined) {
       // A default may be a binding to one of the screen's own inputs.
-      const resolved = resolveBinding(node.props.default, provided)
+      const resolved = resolveBinding(node.props.default, provided, previous)
       if (resolved !== undefined) out[name] = resolved
       else if (!isBinding(node.props.default)) out[name] = node.props.default
       else if (node.type === 'checkbox') out[name] = false
-      else if (node.type === 'multiselect') out[name] = []
+      else if (node.type === 'multiselect' || node.type === 'table') out[name] = []
     }
     else if (node.type === 'checkbox') out[name] = false
-    else if (node.type === 'multiselect') out[name] = []
+    else if (node.type === 'multiselect' || node.type === 'table') out[name] = []
   })
   return out
 }
@@ -100,6 +117,7 @@ export function initialValues(doc, provided = {}, controls = CONTROLS) {
 export function parseInput(node, raw) {
   if (node.type === 'checkbox') return Boolean(raw)
   if (node.type === 'multiselect') return Array.isArray(raw) ? raw : fromDbValue(node, raw) || []
+  if (node.type === 'table') return Array.isArray(raw) ? raw : []
   if (raw === undefined || raw === null || raw === '') return undefined
   if (node.type === 'number') {
     const n = typeof raw === 'number' ? raw : Number(String(raw).trim())
@@ -140,6 +158,14 @@ export function fieldError(node, value, loadedOptions) {
   if (node.type === 'checkbox') {
     return p.required && value !== true ? `${label} must be ticked` : null
   }
+  // A TABLE'S VALUE is the rows ticked: required is at least one.
+  if (node.type === 'table') {
+    const ticked = Array.isArray(value) ? value : []
+    if (!ticked.length) return p.required ? `${label}: tick at least one row` : null
+    if (v.minItems != null && ticked.length < v.minItems) return `${label}: tick at least ${v.minItems}`
+    if (v.maxItems != null && ticked.length > v.maxItems) return `${label}: tick at most ${v.maxItems}`
+    return null
+  }
   if (node.type === 'multiselect') {
     const chosen = Array.isArray(value) ? value : []
     if (!chosen.length) return p.required ? `${label} is required` : null
@@ -260,7 +286,7 @@ export function recordValues(doc, record, controls = CONTROLS) {
     const v = record ? record[name] : undefined
     if (v !== undefined && v !== null) out[name] = fromDbValue(node, v)
     else if (node.type === 'checkbox') out[name] = false
-    else if (node.type === 'multiselect') out[name] = []
+    else if (node.type === 'multiselect' || node.type === 'table') out[name] = []
   })
   return out
 }