@xeplr/ui-factory 1.7.3 → 1.8.0

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xeplr/ui-factory",
-  "version": "1.7.3",
+  "version": "1.8.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/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' }
   ]
 })

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/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/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

@@ -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) : {}))

package/src/useFlowRun.js

@@ -15,7 +15,7 @@ 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 loadRun    async (runId) → { runId, status, stepKey, screen, values, given, previous }
  * @param submitRun  async (runId, values, recordId) → { status, stepKey, screen }
  * @param loadScreen async (key) → the screen document
  * @param onStep     (step) → void — told each time the run moves, for the address bar
@@ -25,7 +25,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 })
   const [sending, setSending] = useState(false)
   const live = useRef({})
   live.current = { startRun, loadRun, submitRun, loadScreen, onStep, onFinish, flowKey }
@@ -43,7 +43,9 @@ 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
     })
     if (live.current.onStep) live.current.onStep(run)
   }, [])

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,26 +61,43 @@ 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()))
+}
+
+/** 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) {
+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