@xeplr/ui-factory 1.1.0 → 1.3.0

package/src/useFactoryScreen.js

@@ -4,6 +4,7 @@ import { inputNodes, nodesForSteps, steppers, stepsOf, stepOf, resolveStep, reac
 import { validateDocument } from './validateDocument.js'
 import { initialValues, parseInput, saveState, fieldError, optionValue, recordValues, listSource } from './values.js'
 import { hookMethod } from './hooks.js'
+import { useUrlSteps } from './useUrlPlaces.js'
 
 // A saved screen, running. No JSX — designs/ScreenSample.jsx draws it.
 //
@@ -48,10 +49,19 @@ import { hookMethod } from './hooks.js'
  * @param onDirtyChange (dirty) → void — whether there are unsaved changes, as that changes
  * @param controls      the control registry (default: the built-ins)
  * @param hooks         a FactoryHooks (or an object with some of its methods) — get / save / delete / actions
+ * @param urlKey        where the open step of each stepper lives in the URL (`<urlKey>Steps`),
+ *                      so a refresh or a shared link lands on the same step. Omitted → in memory.
+ */
+/**
+ * @param params  what this screen was CALLED WITH — { name: value } for the
+ *   inputs it declares. A flow's Screen step supplies them; somebody opening
+ *   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.
  */
 export function useFactoryScreen({
   document: doc, record, recordKey = 'id', onSave, fetchOptions, fetchRecords, fetchRecord, onDelete, onChange, screens, loadScreen, hooks, uploadFile, fileUrl,
-  onOpenRecord, onDone, onDirtyChange,
+  onOpenRecord, onDone, onDirtyChange, params, urlKey,
   controls = CONTROLS
 } = {}) {
   const check = useMemo(() => validateDocument(doc, controls), [doc, controls])
@@ -97,9 +107,13 @@ export function useFactoryScreen({
   }, [check.ok, doc, inputs, fieldsFor])
   const source = check.ok ? doc.source || null : null
 
+  // WHAT IT WAS CALLED WITH, then what was actually saved: a record being
+  // reopened wins, because the row is the truth once there is one.
   const startValues = useCallback(
-    (rec) => (rec ? { ...initialValues(doc, {}, controls), ...recordValues(doc, rec, controls) } : initialValues(doc, {}, controls)),
-    [doc, controls]
+    (rec) => (rec
+      ? { ...initialValues(doc, params || {}, controls), ...recordValues(doc, rec, controls) }
+      : initialValues(doc, params || {}, controls)),
+    [doc, controls, params]
   )
 
   const [values, setValues] = useState(() => (check.ok ? startValues(record) : {}))
@@ -161,7 +175,7 @@ export function useFactoryScreen({
   // A stepper shows one step at a time. Which step each is open at lives here;
   // the fields of the steps not showing are still filled in, still checked and
   // still saved — a step is what the person sees, not a separate form.
-  const [openSteps, setOpenSteps] = useState({})
+  const [openSteps, setOpenSteps] = useUrlSteps(urlKey)
   // Steps the app has switched off — { stepper id: [index, …] }. A screen may
   // have branches; which of them apply is the app's to say, from its hooks.
   const [disabledSteps, setDisabledSteps] = useState({})
@@ -169,20 +183,20 @@ export function useFactoryScreen({
   const visibleNodes = useMemo(() => (check.ok ? nodesForSteps(doc, openSteps, controls) : []), [check.ok, doc, openSteps, controls])
 
   // A screen whose steps changed under it (a field moved to another step, a
-  // step removed) must not stay open at a step that is gone.
+  // step removed) must not stay open at a step that is gone. Steppers this
+  // document does not have are left alone: a screen still loading has none,
+  // and dropping them would lose the step a link was opened at.
   useEffect(() => {
     setOpenSteps((open) => {
-      let changed = false
-      const next = {}
+      const next = { ...open }
       stepperNodes.forEach((n) => {
         const count = stepsOf(n).length
         const at = Number.isInteger(open[n.id]) ? open[n.id] : 0
         next[n.id] = Math.min(Math.max(at, 0), Math.max(count - 1, 0))
-        if (next[n.id] !== open[n.id]) changed = true
       })
-      return changed || Object.keys(next).length !== Object.keys(open).length ? next : open
+      return next
     })
-  }, [stepperNodes])
+  }, [stepperNodes, setOpenSteps])
 
   const stepControl = useMemo(() => {
     const at = (id) => (Number.isInteger(openSteps[id]) ? openSteps[id] : 0)
@@ -274,7 +288,7 @@ export function useFactoryScreen({
       })
     }
     return control
-  }, [stepperNodes, openSteps, disabledSteps, doc, controls])
+  }, [stepperNodes, openSteps, setOpenSteps, disabledSteps, doc, controls])
 
   live.current.steps = stepControl
 
@@ -481,7 +495,16 @@ export function useFactoryScreen({
         defaults: {
           get: () => {
             if (!fetchRecordsRef.current) throw new Error(`No fetchRecords was provided to list "${src}"`)
-            return fetchRecordsRef.current({ source: src, screen: doc.id, node })
+            // A SUB-TABLE IS THIS RECORD'S. `belongsTo` names the column on
+            // those rows that points back here, and the id is this record's
+            // — which is nothing until it has been saved, and the server
+            // answers with no rows rather than with everybody's.
+            var link = node.props && node.props.belongsTo
+            return fetchRecordsRef.current({
+              source: src, screen: doc.id, node,
+              belongsTo: link || undefined,
+              belongsToId: link ? live.current.recordId : undefined
+            })
           }
         }
       }))
@@ -542,12 +565,20 @@ export function useFactoryScreen({
   const openRecordRef = useRef(onOpenRecord); openRecordRef.current = onOpenRecord
   const openEditor = useCallback(async (node, rec) => {
     const screenId = node.props.editScreen
+
+    // WHAT THE CHILD IS CALLED WITH. A sub-table's row belongs to THIS
+    // record, so the link column is handed to the screen that adds one — the
+    // same `params` a flow's Screen step passes. The person never sees it,
+    // and never has to know which material they are adding a line to.
+    const link = node.props.belongsTo
+    const given = link && live.current.recordId ? { [link]: live.current.recordId } : null
+
     if (node.props.openIn === 'page') {
       if (!openRecordRef.current) throw new Error('This list opens records on a page, but no onOpenRecord was provided to go there')
       const id = rec ? rec[live.current.recordKey] : null
-      return openRecordRef.current({ screen: screenId, id, record: rec || null, source: listSource(doc, node), node })
+      return openRecordRef.current({ screen: screenId, id, record: rec || null, source: listSource(doc, node), node, params: given })
     }
-    const base = { node, screenId, record: rec || null, document: null, loading: true, error: null }
+    const base = { node, screenId, record: rec || null, document: null, loading: true, error: null, params: given }
     setPopup(base)
     try {
       let found = screensRef.current && screensRef.current[screenId]

package/src/useFlowBuilder.js

@@ -4,6 +4,7 @@ import {
   addTransition, setTransition, removeTransition, validateFlow, firstStep, layoutFlow, FLOW_END
 } from './flow.js'
 import { inputNodes } from './document.js'
+import { useUrlSelection } from './useUrlPlaces.js'
 
 // DESIGNING a flow: which screens, in what order, and what decides the order.
 //
@@ -23,10 +24,12 @@ export const FLOW_AUTOSAVE_DELAY = 800
  * @param onSave      async (flow) → void — called after edits, only with a flow that makes sense
  * @param onPublish   async (key) → void — shows a Publish button
  * @param onChange    (flow) → void — every edit
+ * @param urlKey      where the selected step lives in the URL (`<urlKey>Selected`), so a
+ *                    refresh or a shared link opens the same step. Omitted → in memory.
  */
-export function useFlowBuilder({ flow: given, name, screens = [], loadScreen, onSave, onPublish, onChange } = {}) {
+export function useFlowBuilder({ flow: given, name, screens = [], loadScreen, onSave, onPublish, onChange, urlKey } = {}) {
   const [flow, setFlow] = useState(() => given || createFlow({ name }))
-  const [selected, setSelected] = useState(null)          // a step key
+  const [selected, setSelected] = useUrlSelection(urlKey)  // a step key
   const [dirty, setDirty] = useState(false)
   const [saving, setSaving] = useState(false)
   const [saveError, setSaveError] = useState(null)
@@ -102,13 +105,13 @@ export function useFlowBuilder({ flow: given, name, screens = [], loadScreen, on
     })
     if (added) setSelected(added.stepKey)
     return added
-  }, [update])
+  }, [update, setSelected])
   const move = useCallback((stepKey, at) => update((f) => moveStep(f, stepKey, at)), [update])
   const change = useCallback((stepKey, patch) => update((f) => setStep(f, stepKey, patch)), [update])
   const remove = useCallback((stepKey) => {
     update((f) => removeStep(f, stepKey))
     setSelected((s) => (s === stepKey ? null : s))
-  }, [update])
+  }, [update, setSelected])
   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])

package/src/useFlowRun.js

@@ -15,14 +15,17 @@ 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 }
+ * @param loadRun    async (runId) → { runId, status, stepKey, screen, values, given }
  * @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
  * @param onFinish   (run) → void — the journey is over
  */
 export function useFlowRun({ flowKey, runId, startRun, loadRun, submitRun, loadScreen, onStep, onFinish } = {}) {
-  const [state, setState] = useState({ loading: true, error: null, runId: runId || null, status: null, stepKey: null, screen: null, document: null, values: null })
+  // `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 [sending, setSending] = useState(false)
   const live = useRef({})
   live.current = { startRun, loadRun, submitRun, loadScreen, onStep, onFinish, flowKey }
@@ -40,7 +43,7 @@ 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
+      document: doc, values: run.values || null, given: run.given || null
     })
     if (live.current.onStep) live.current.onStep(run)
   }, [])

package/src/useScreenSource.js

@@ -21,7 +21,7 @@
 // createElement so the file stays .js.
 
 import { createElement, useCallback, useEffect, useMemo, useState } from 'react'
-import { loadScreens } from './screenSource.js'
+import { loadScreens, masterForms } from './screenSource.js'
 import { ScreenEditorSample } from './designs/ScreenEditorSample.jsx'
 
 /**
@@ -29,7 +29,7 @@ import { ScreenEditorSample } from './designs/ScreenEditorSample.jsx'
  * @param opts { Builder, labels } — the builder component to draw, normally
  *             FactoryBuilder. Passed in rather than imported so this hook does
  *             not pull the whole builder into a bundle that never opens it.
- * @returns { screens, screenEditor, reload, loading, error }
+ * @returns { screens, masters, screenEditor, reload, loading, error }
  */
 export function useScreenSource(api, opts) {
   opts = opts || {}
@@ -74,8 +74,12 @@ export function useScreenSource(api, opts) {
     })
   }, [api, Builder, labels, reload])
 
+  // The lists other forms point at, one entry per FORM — what the admin
+  // section shows. Derived here so no application groups screens by hand.
+  const masters = useMemo(() => masterForms(screens), [screens])
+
   return useMemo(
-    () => ({ screens, screenEditor, reload, loading, error }),
-    [screens, screenEditor, reload, loading, error]
+    () => ({ screens, masters, screenEditor, reload, loading, error }),
+    [screens, masters, screenEditor, reload, loading, error]
   )
 }

package/src/useUrlPlaces.js

@@ -0,0 +1,48 @@
+import { useCallback, useMemo, useRef } from 'react'
+import { useUrlState } from '@xeplr/ui-utils/src/url/useUrlState.js'
+import { factoryUrlKeys, encodeSteps, decodeSteps, replacesHistory } from './urlState.js'
+
+// The two places the factory's controllers keep, each in useState's shape so
+// a controller swaps one line. In the URL under the host's `urlKey`; without
+// one, in memory with the same rules (see urlState.js).
+
+/**
+ * [openSteps, setOpenSteps] — which step each stepper is open at,
+ * { stepper id: index }. Moving between steps is a switch, so it replaces the
+ * history entry rather than adding one.
+ */
+export function useUrlSteps(urlKey) {
+  const keys = factoryUrlKeys(urlKey)
+  const [value, setValue] = useUrlState(keys ? keys.steps : 'steps', { inUrl: Boolean(keys), replace: true })
+  const open = useMemo(() => decodeSteps(value), [value])
+  // Two moves in one event build on each other, as useState's updater would.
+  const openRef = useRef(open); openRef.current = open
+  const setOpen = useCallback((next) => {
+    const resolved = typeof next === 'function' ? next(openRef.current) : next
+    const encoded = encodeSteps(resolved)
+    if (encoded === encodeSteps(openRef.current)) return
+    openRef.current = decodeSteps(encoded)
+    setValue(encoded)
+  }, [setValue])
+  return [open, setOpen]
+}
+
+/**
+ * [selected, setSelected] — the one thing whose properties are open (a
+ * control's id, a flow step's key), or null. Opening or closing the
+ * properties adds a history entry; moving to another thing replaces it.
+ * Read back from the URL it is a string.
+ */
+export function useUrlSelection(urlKey) {
+  const keys = factoryUrlKeys(urlKey)
+  const [value, setValue] = useUrlState(keys ? keys.selected : 'selected', { inUrl: Boolean(keys) })
+  const valueRef = useRef(value); valueRef.current = value
+  const select = useCallback((next) => {
+    const resolved = typeof next === 'function' ? next(valueRef.current) : next
+    const v = resolved === undefined || resolved === '' ? null : resolved
+    if ((v === null ? null : String(v)) === valueRef.current) return
+    setValue(v, { replace: replacesHistory(valueRef.current, v) })
+    valueRef.current = v === null ? null : String(v)
+  }, [setValue])
+  return [value, select]
+}

package/src/validateDocument.js

@@ -18,7 +18,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', 'nodes']
+const DOCUMENT_KEYS = ['kind', 'version', 'id', 'name', 'source', 'units', 'aspect', 'width', 'style', 'description', 'master', 'labelField', 'params', 'nodes']
 const COLOR = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i
 
 /**
@@ -41,6 +41,49 @@ export function validateDocument(doc, controls = CONTROLS) {
   if (!(typeof doc.aspect === 'number' && doc.aspect > 0)) err('aspect', 'must be a number greater than 0 (1 = page as tall as it is wide)')
   if (!(Number.isInteger(doc.width) && doc.width >= 320 && doc.width <= 1920)) err('width', 'must be a whole number of pixels from 320 to 1920 — the width the screen is designed at')
   if (doc.source !== undefined && !(nonEmptyString(doc.source) && TABLE_NAME.test(doc.source))) err('source', 'must name the table records are saved to, e.g. "employees"')
+
+  // WHAT THIS FORM IS FOR, in the maker's own words. Three forms called
+  // "Inspection" are told apart by this and by who made them — never by their
+  // fields, which say what a form holds and not what it was for.
+  if (doc.description !== undefined && doc.description !== null && doc.description !== '') {
+    if (typeof doc.description !== 'string') err('description', 'must be a sentence about what this form is for')
+    else if (doc.description.length > 500) err('description', 'must be under 500 characters — a sentence, not the manual')
+  }
+
+  // A MASTER is a form whose records other forms point at — departments,
+  // statuses, countries. It is a FLAG on an ordinary form, not a kind of its
+  // own: a master has a table, a list, an edit screen and permissions like
+  // anything else, and a separate type would be two things that behave the
+  // same until they do not, with every later feature asking which it has.
+  if (doc.master !== undefined && typeof doc.master !== 'boolean') {
+    err('master', 'must be true or false — whether other forms pick from this one')
+  }
+  // What a picker SHOWS for a record. Said once here rather than on every
+  // dropdown that points at this form.
+  if (doc.labelField !== undefined) {
+    if (!nonEmptyString(doc.labelField)) err('labelField', 'must name a field of this screen, e.g. "name"')
+    else if (!(doc.nodes || []).some((n) => n.props && n.props.name === doc.labelField)) {
+      err('labelField', `"${doc.labelField}" is not a field on this screen`)
+    }
+  }
+
+  // WHAT THIS SCREEN IS CALLED WITH. Names only — a field binds to one with
+  // {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.
+  if (doc.params !== undefined) {
+    if (!Array.isArray(doc.params)) err('params', 'must be a list of inputs this screen is called with')
+    else {
+      const seen = new Set()
+      doc.params.forEach((p, i) => {
+        const name = p && p.name
+        if (!nonEmptyString(name)) err(`params.${i}.name`, 'must be a name, e.g. "complaintId"')
+        else if (!/^[A-Za-z_][\w]*$/.test(name)) err(`params.${i}.name`, `"${name}" must be letters, digits and _, starting with a letter`)
+        else if (seen.has(name)) err(`params.${i}.name`, `"${name}" is declared twice — a field binding to it would mean two things`)
+        else seen.add(name)
+      })
+    }
+  }
   checkStyle(doc.style, SCREEN_STYLE_KEYS, 'style', err, 'the screen')
   Object.keys(doc).forEach((k) => {
     if (!DOCUMENT_KEYS.includes(k)) err(k, `is not a screen property — allowed: ${DOCUMENT_KEYS.join(', ')}`)
@@ -92,6 +135,18 @@ export function validateDocument(doc, controls = CONTROLS) {
       // Where the field came from (a ready-made field's key), or false: plain on purpose.
       if (props.preset !== undefined && props.preset !== false && !presetFor(props.preset)) err(`${at}.props.preset`, `"${props.preset}" is not a ready-made field — one of: ${FIELD_PRESETS.map((p) => p.key).join(', ')}, or false`)
       if (props.inputType !== undefined && !INPUT_TYPES.includes(props.inputType)) err(`${at}.props.inputType`, `must be one of: ${INPUT_TYPES.join(', ')}`)
+
+      // AN IDENTIFIER — the number or code this record is known by. How it is
+      // made decides the column, so it is checked here rather than discovered
+      // at publish time.
+      if (props.idKind !== undefined && props.idKind !== 'code' && props.idKind !== 'auto') {
+        err(`${at}.props.idKind`, 'must be "code" (CMP-7K3QF9, assigned on save) or "auto" (a number the database counts)')
+      }
+      if (props.codePrefix !== undefined && props.codePrefix !== '') {
+        if (typeof props.codePrefix !== 'string' || !/^[A-Za-z0-9]{1,8}$/.test(props.codePrefix)) {
+          err(`${at}.props.codePrefix`, 'must be up to 8 letters or digits, e.g. "CMP" — it is what the code starts with')
+        }
+      }
       checkDefault(node, def, at, err)
       checkValidation(node, def, at, err)
     }
@@ -330,6 +385,17 @@ function checkList(props, doc, at, err) {
   if (props.source !== undefined && !(nonEmptyString(props.source) && TABLE_NAME.test(props.source))) err(`${at}.props.source`, 'must name the table to list records from')
   if (props.source === undefined && doc.source === undefined) err(`${at}.props.source`, 'is required when the screen has no "source" — which table should the list read?')
   if (props.editScreen !== undefined && !(nonEmptyString(props.editScreen) && SCREEN_ID.test(props.editScreen))) err(`${at}.props.editScreen`, 'must be the id of the screen that edits a record, e.g. "employee_edit"')
+
+  // THE LINK BACK, for a sub-table on a form: this material's
+  // characteristics. A column name, checked as one — a value that could never
+  // be a column is a list that is always empty and nobody knows why.
+  if (props.belongsTo !== undefined && props.belongsTo !== '') {
+    if (!(nonEmptyString(props.belongsTo) && /^[A-Za-z_][\w]*$/.test(props.belongsTo))) {
+      err(`${at}.props.belongsTo`, 'must be a column name, e.g. "materialId"')
+    } else if (!props.source) {
+      err(`${at}.props.belongsTo`, 'only means something with "Records from" set — a list of this screen\'s own table already belongs to this record')
+    }
+  }
   if (props.pageSize !== undefined && !(Number.isInteger(props.pageSize) && props.pageSize >= 1 && props.pageSize <= 200)) err(`${at}.props.pageSize`, 'must be a whole number from 1 to 200')
   if (props.actions !== undefined) {
     if (!Array.isArray(props.actions)) err(`${at}.props.actions`, `must be an array of: ${LIST_ACTIONS.join(', ')}`)

package/src/values.js

@@ -46,12 +46,46 @@ export function formSchema(doc, controls = CONTROLS) {
 }
 
 /** Each input's starting value: the caller's, else the control's default. */
+/**
+ * A VALUE WITH A TOKEN IS A BINDING; a plain value is a literal.
+ *
+ * `{params.complaintId}` in a field's default means "whatever this screen was
+ * called with" — the same brace this product uses in a workflow step, a
+ * condition and a report. Nothing is marked on the field: the brace says it.
+ *
+ * Unknown, or called with nothing, resolves to undefined — the field is then
+ * empty and the person fills it in, which is what the same form does when
+ * somebody opens it on its own. A form that will not open is worse than a
+ * question nobody expected.
+ *
+ * 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) {
+  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
+}
+
+/** Is this what somebody typed, or a reference to an input? */
+export function isBinding(value) {
+  return typeof value === 'string' && /^\{params\.[A-Za-z_][\w]*\}$/.test(value.trim())
+}
+
 export function initialValues(doc, provided = {}, controls = CONTROLS) {
   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) out[name] = node.props.default
+    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)
+      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 === 'checkbox') out[name] = false
     else if (node.type === 'multiselect') out[name] = []
   })
@@ -98,6 +132,11 @@ export function fieldError(node, value, loadedOptions) {
   const label = p.label || p.name
   const v = p.validation || {}
 
+  // AN IDENTIFIER IS NOT SOMEBODY'S TO FILL IN. The server assigns a code on
+  // first save and the database counts a number, so a rule here would refuse
+  // the very save that produces the value.
+  if (node.type === 'id') return null
+
   if (node.type === 'checkbox') {
     return p.required && value !== true ? `${label} must be ticked` : null
   }
@@ -234,8 +273,28 @@ export function listSource(doc, node) {
 }
 
 /** A list's columns: the ones chosen, else the screen's fields in reading order. */
-export function listColumns(doc, node, controls = CONTROLS) {
+export function listColumns(doc, node, controls = CONTROLS, rows) {
   if (node && Array.isArray(node.props?.columns) && node.props.columns.length) return node.props.columns
+
+  // A LIST OF ANOTHER TABLE HAS NOTHING TO DO WITH THIS SCREEN'S FIELDS.
+  //
+  // A sub-table — this material's characteristics — holds rows of a different
+  // shape entirely, so falling back to this screen's fields shows four empty
+  // columns named after the material. The rows themselves are the only
+  // description to hand, so they are what it reads.
+  const foreign = node && node.props && node.props.source && doc && node.props.source !== doc.source
+  if (foreign) {
+    const first = (rows || []).find((r) => r && typeof r === 'object')
+    if (first) {
+      return Object.keys(first)
+        // Neither is a column anybody asked to see: one is the row's handle,
+        // the other is the record it belongs to, which is the list itself.
+        .filter((k) => k !== 'id' && k !== (node.props.belongsTo || ''))
+        .map((k) => ({ field: k, label: k }))
+    }
+    return []
+  }
+
   return inputNodes(doc, controls).map((n) => ({ field: n.props.name, label: n.props.label || n.props.name }))
 }
 
@@ -299,3 +358,60 @@ export function fromDbValue(node, value) {
   }
   return value
 }
+
+// ── a code people can read out ──────────────────────────────────────────
+//
+// The record's own id is a 25-character key made on save. It is unique,
+// stable and completely unquotable: nobody reads one over the phone, writes
+// one on a form, or finds a complaint by it. So a field can be marked
+// GENERATED, and gets a short code instead — CMP-7K3QF9.
+//
+// RANDOM, not sequential. A counted number (CMP-0001) needs a counter bumped
+// in the same transaction as the insert, or two people saving at once take
+// the same one; and it still shows gaps whenever a save fails after the
+// number was taken, which somebody then has to explain. A random code has
+// neither problem, at the cost of not telling you the fifth from the five
+// hundredth — which is what the record's date is for.
+
+/**
+ * The alphabet, minus the characters people mistake for each other.
+ *
+ * ONE OF EACH PAIR SURVIVES, which is the whole trick: O and I and S are
+ * gone, so 0, 1 and 5 are unambiguous and can stay. Dropping both halves
+ * would cost a third of the alphabet to solve a problem already solved.
+ *
+ * The point of this code is that it survives being read aloud, written down
+ * and typed back in.
+ */
+var CODE_ALPHABET = '23456789ABCDEFGHJKLMNPQRTUVWXYZ'
+
+/** The fields a screen generates a code for. */
+export function codeFields(doc, controls = CONTROLS) {
+  return inputNodes(doc, controls).filter((n) => n.type === 'id' && (n.props || {}).idKind !== 'auto')
+}
+
+/**
+ * The identifiers the DATABASE fills in — a counted number. They are never
+ * sent on an insert: the column is an identity, so mentioning it at all would
+ * be claiming a number nobody chose.
+ */
+export function countedFields(doc, controls = CONTROLS) {
+  return inputNodes(doc, controls).filter((n) => n.type === 'id' && (n.props || {}).idKind === 'auto')
+}
+
+/**
+ * One code. `prefix` is what makes it recognisable at a glance — a complaint
+ * is CMP-…, a purchase order is PO-… — and is optional.
+ *
+ * Six characters from 31 is about 900 million codes, which is not a
+ * guarantee: whoever writes one is expected to check it is free and try
+ * again, which is cheap and has to be done in the database anyway.
+ */
+export function generateCode(prefix, length = 6) {
+  let out = ''
+  for (let i = 0; i < length; i++) {
+    out += CODE_ALPHABET[Math.floor(Math.random() * CODE_ALPHABET.length)]
+  }
+  const head = String(prefix || '').trim().toUpperCase().replace(/[^A-Z0-9]+/g, '')
+  return head ? head + '-' + out : out
+}