@xeplr/ui-factory 1.2.0 → 1.4.0

package/src/useFactoryScreen.js

@@ -29,6 +29,15 @@ import { useUrlSteps } from './useUrlPlaces.js'
 // A list whose `editScreen` names another screen opens that screen in a popup
 // for Edit and New. The screen comes from `screens` ({ id → document }) or the
 // host's `loadScreen(id)`. The list refreshes as the popup saves.
+//
+// ── A FORM INSIDE THIS ONE (subform) ─────────────────────────────────────
+// A `subform` node draws another published form inline, saving into its own
+// table. The view renders it as a second useFactoryScreen with `link` (the
+// field on it pointing back here) and `onReady`, through which it hands this
+// one a handle: validate / dirty / save. One Save writes THIS record first —
+// so a new one has an id — then every subform with changes, with that id in
+// its link field. An untouched subform is not saved: it is one optional
+// record, and an empty one is not worth a row.
 
 /**
  * @param document      a valid screen document
@@ -52,12 +61,33 @@ import { useUrlSteps } from './useUrlPlaces.js'
  * @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, urlKey,
+  onOpenRecord, onDone, onDirtyChange, params, urlKey,
+  link, onReady,
   controls = CONTROLS
 } = {}) {
   const check = useMemo(() => validateDocument(doc, controls), [doc, controls])
+  // EMBEDDED AS A SUBFORM: `link` is the field pointing back at the record
+  // this sits in. It is never shown and never asked for — the host fills it
+  // in on save — so it is left out of what is checked here, and a form
+  // without that field is a mistake said out loud, not a record saved
+  // belonging to nothing.
+  const embedded = Boolean(link)
+  const checkDoc = useMemo(
+    () => (embedded && check.ok ? { ...doc, nodes: doc.nodes.filter((n) => !(n.props && n.props.name === link)) } : doc),
+    [doc, link, embedded, check.ok]
+  )
+  const linkError = embedded && check.ok && !inputNodes(doc, controls).some((n) => n.props.name === link)
+    ? { path: '', message: `"${doc.name || doc.id}" has no field "${link}" — add it, or change "Linked by" on the form this is placed in` }
+    : null
   // Read at call time, so a new hooks object never re-runs loads by itself.
   const hooksRef = useRef(hooks); hooksRef.current = hooks
   const hook = (name) => hookMethod(hooksRef.current, name)
@@ -100,9 +130,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) : {}))
@@ -128,7 +162,7 @@ export function useFactoryScreen({
 
   // Latest of everything a save needs, read at the moment it runs.
   const live = useRef({})
-  live.current = { doc, values, recordId, touched, source, onSave, controls, recordKey }
+  live.current = { doc, checkDoc, values, recordId, touched, source, onSave, controls, recordKey }
 
   // ── options for table dropdowns, fetched once per table ───────────────
   const [options, setOptions] = useState({})   // node id → { loading, items, error }
@@ -169,7 +203,10 @@ export function useFactoryScreen({
   // have branches; which of them apply is the app's to say, from its hooks.
   const [disabledSteps, setDisabledSteps] = useState({})
   const stepperNodes = useMemo(() => (check.ok ? steppers(doc, controls) : []), [check.ok, doc, controls])
-  const visibleNodes = useMemo(() => (check.ok ? nodesForSteps(doc, openSteps, controls) : []), [check.ok, doc, openSteps, controls])
+  const visibleNodes = useMemo(
+    () => (check.ok ? nodesForSteps(doc, openSteps, controls).filter((n) => !(embedded && n.props && n.props.name === link)) : []),
+    [check.ok, doc, openSteps, controls, embedded, link]
+  )
 
   // 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. Steppers this
@@ -309,26 +346,50 @@ export function useFactoryScreen({
   }, [options])
   live.current.loadedItems = loadedItems
 
-  const state = useMemo(() => (check.ok ? saveState(doc, values, touched, loadedItems, controls) : { canSave: false, status: 'invalid', errors: {}, shown: {} }),
-    [check.ok, doc, values, touched, loadedItems, controls])
+  const state = useMemo(() => (check.ok ? saveState(checkDoc, values, touched, loadedItems, controls) : { canSave: false, status: 'invalid', errors: {}, shown: {} }),
+    [check.ok, checkDoc, values, touched, loadedItems, controls])
+
+  // ── subforms: the handles they hand over, and which hold changes ──────
+  const subApis = useRef({})          // node id → { validate, dirty, save, name }
+  const subDirty = useRef(new Set())  // node ids of subforms with unsaved changes
+  const [subVersion, setSubVersion] = useState(0)
+  const registerSubform = useCallback((id, api) => {
+    if (api) subApis.current[id] = api
+    else { delete subApis.current[id]; subDirty.current.delete(id) }
+  }, [])
 
   // ── saving ────────────────────────────────────────────────────────────
   const inFlight = useRef(null)     // the promise of the save running now
 
-  /** Save — what the Save button does. One AJAX call; never on its own. */
-  const runSave = useCallback(async () => {
+  /**
+   * Is it fit to save? Says what is missing on every field — including the
+   * ones nobody has been in yet — because pressing Save is the moment to.
+   */
+  const checkNow = useCallback(() => {
+    const l = live.current
+    const st = saveState(l.checkDoc, l.values, l.touched, l.loadedItems, l.controls)
+    if (st.canSave) return { ok: true }
+    const t = new Set([...l.touched, ...Object.keys(st.errors)])
+    live.current.touched = t
+    setTouched(t)
+    setStatus('invalid')
+    return { ok: false, errors: st.errors }
+  }, [])
+
+  /**
+   * Save — what the Save button does. One AJAX call; never on its own.
+   * `extra` is merged into what is sent: a subform's link, from its host.
+   */
+  const runSave = useCallback(async (extra) => {
     if (inFlight.current) return inFlight.current
     const l = live.current
-    const st = saveState(l.doc, l.values, l.touched, l.loadedItems, l.controls)
-    if (!st.canSave) {
-      // Pressing Save is the moment to say what is missing — on every field,
-      // including the ones nobody has been in yet.
-      const t = new Set([...l.touched, ...Object.keys(st.errors)])
-      live.current.touched = t
-      setTouched(t)
-      setStatus('invalid')
-      return { ok: false, errors: st.errors }
-    }
+    // A subform with changes is checked BEFORE anything is written, so a bad
+    // bank account never leaves an employee saved without one.
+    const subs = Object.entries(subApis.current).filter(([id]) => subDirty.current.has(id))
+    const subsOk = subs.map(([, api]) => api.validate()).every(Boolean)
+    const own = checkNow()
+    if (!own.ok) return own
+    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 } }
@@ -338,13 +399,14 @@ export function useFactoryScreen({
     const task = (async () => {
       try {
         const meta = { id: l.recordId, source: l.source, screen: l.doc.id, document: l.doc }
-        const saved = await hook('save')(l.values, {
+        const vals = extra ? { ...l.values, ...extra } : l.values
+        const saved = await hook('save')(vals, {
           ...meta,
           isNew: l.recordId === null || l.recordId === undefined,
           // Save is where an app usually learns which branch it is on, so it
           // can switch steps off from here as well as from step().
           steps: live.current.steps,
-          defaults: { save: (vals) => (l.onSave ? l.onSave(vals, meta) : undefined) }
+          defaults: { save: (v) => (l.onSave ? l.onSave(v, meta) : undefined) }
         })
         // A new record's first save creates it; its id makes the next save an update.
         if (saved && typeof saved === 'object' && saved[l.recordKey] !== undefined && saved[l.recordKey] !== null) {
@@ -352,7 +414,28 @@ export function useFactoryScreen({
           live.current.recordId = saved[l.recordKey]
         }
         savedChanges.current = writing
-        const still = changes.current !== writing
+
+        // THEN THE SUBFORMS, each with this record's id in its link field.
+        // One that fails leaves this record saved and says which did not.
+        if (subs.length) {
+          const failed = []
+          for (const [id, api] of subs) {
+            const r = await api.save(live.current.recordId)
+            if (!r || !r.ok) failed.push(`${api.name()}${r && r.error && r.error.message ? ` (${r.error.message})` : ''}`)
+            // Read from the subform itself, now — its own report of being
+            // clean arrives after this function has decided what to say.
+            else if (!api.dirty()) subDirty.current.delete(id)
+          }
+          setSubVersion((v) => v + 1)
+          if (failed.length) {
+            setDirty(true)
+            setSaveError(`this record was saved, but ${failed.join(', ')} was not`)
+            setStatus('error')
+            return { ok: false, record: saved }
+          }
+        }
+
+        const still = changes.current !== writing || subDirty.current.size > 0
         setDirty(still)
         setSavedAt(new Date())
         setListVersion((v) => v + 1)
@@ -375,21 +458,45 @@ export function useFactoryScreen({
     })()
     inFlight.current = task
     return task
+  }, [setDirty, checkNow])
+
+  /** A subform's changes are this form's unsaved changes too. */
+  const subformDirty = useCallback((id, d) => {
+    if (d) subDirty.current.add(id)
+    else subDirty.current.delete(id)
+    setDirty(changes.current !== savedChanges.current || subDirty.current.size > 0)
+    if (d) setStatus('pending')
   }, [setDirty])
 
+  const unsaved = () => changes.current !== savedChanges.current || subDirty.current.size > 0
+
   /** Save if there is anything unsaved — what a flow's Next does before moving on. */
   const flush = useCallback(async () => {
     if (inFlight.current) await inFlight.current
-    if (changes.current !== savedChanges.current) return runSave()
+    if (unsaved()) return runSave()
     return { ok: true }
-  }, [runSave])
+  }, [runSave])                                               // eslint-disable-line react-hooks/exhaustive-deps
+
+  // EMBEDDED: hand the host what it needs to check and save this form as part
+  // of its own Save. Read through refs, so the handle never goes stale.
+  const onReadyRef = useRef(onReady); onReadyRef.current = onReady
+  useEffect(() => {
+    if (!onReadyRef.current) return undefined
+    onReadyRef.current({
+      validate: () => checkNow().ok,
+      dirty: () => changes.current !== savedChanges.current,
+      save: (ownerId) => runSave({ [link]: ownerId }),
+      name: () => live.current.doc.name || live.current.doc.id
+    })
+    return () => { if (onReadyRef.current) onReadyRef.current(null) }
+  }, [runSave, checkNow, link])
 
   /**
    * May the person leave? True when nothing is unsaved, or when they agree to
    * lose it. Cancel, the popup's × and opening another record all ask this.
    */
   const confirmDiscard = useCallback(() => {
-    if (changes.current === savedChanges.current) return true
+    if (!unsaved()) return true
     // eslint-disable-next-line no-alert
     return typeof window === 'undefined' || window.confirm('Discard your unsaved changes?')
   }, [])
@@ -456,6 +563,8 @@ export function useFactoryScreen({
     setSaveError(null)
     setServerErrors({})
     setStatus('idle')
+    // Its subforms are this record's, so they are read again for it.
+    setSubVersion((v) => v + 1)
   }, [startValues, recordKey, setDirty])
 
   const newRecord = useCallback(() => openRecord(null), [openRecord])
@@ -484,7 +593,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
+            })
           }
         }
       }))
@@ -545,12 +663,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]
@@ -574,6 +700,49 @@ export function useFactoryScreen({
     }
   }, [])
 
+  // ── subforms: the form each draws, and this record's row of it ────────
+  //
+  // Read when the screen opens, when another record is opened, and after a
+  // Save — never just because the id changed, or a new record's first save
+  // would re-read an empty row over the subform it is in the middle of saving.
+  const [subforms, setSubforms] = useState({})   // node id → { loading, error, document, record }
+  const subformNodes = useMemo(() => (check.ok ? doc.nodes.filter((n) => n.type === 'subform') : []), [doc, check.ok])
+  useEffect(() => {
+    if (!subformNodes.length) return undefined
+    let cancelled = false
+    subformNodes.forEach((node) => {
+      const screenId = node.props.screen
+      setSubforms((m) => ({ ...m, [node.id]: { ...(m[node.id] || {}), loading: true, error: null } }))
+      ;(async () => {
+        let found = screensRef.current && screensRef.current[screenId]
+        if (!found && loadScreenRef.current) found = await loadScreenRef.current(screenId)
+        if (!found) throw new Error(`Form "${screenId}" was not provided — pass it in \`screens\` or supply loadScreen`)
+        const ownerId = live.current.recordId
+        // Nothing to read for a record that is not saved yet: it owns nothing.
+        if (ownerId === null || ownerId === undefined) return { document: found, record: null }
+        const rows = await hook('get')({
+          many: true, id: null, screen: screenId, source: found.source || null, node, document: found,
+          defaults: {
+            get: () => {
+              if (!fetchRecordsRef.current) throw new Error(`No fetchRecords was provided to read "${screenId}"`)
+              return fetchRecordsRef.current({
+                source: found.source || null, screen: screenId, node,
+                belongsTo: node.props.belongsTo, belongsToId: ownerId
+              })
+            }
+          }
+        })
+        return { document: found, record: Array.isArray(rows) && rows.length ? rows[0] : null }
+      })().then(
+        (got) => { if (!cancelled) setSubforms((m) => ({ ...m, [node.id]: { loading: false, error: null, ...got } })) },
+        (err) => { if (!cancelled) setSubforms((m) => ({ ...m, [node.id]: { ...(m[node.id] || {}), loading: false, error: err.message || 'Could not load the form' } })) }
+      )
+    })
+    return () => { cancelled = true }
+  }, [subformNodes, subVersion])                              // eslint-disable-line react-hooks/exhaustive-deps
+
+  const subformFor = useCallback((node) => subforms[node.id] || { loading: true, error: null, document: null, record: null }, [subforms])
+
   const closeEditor = useCallback(() => {
     setPopup(null)
     setListVersion((v) => v + 1)
@@ -589,7 +758,11 @@ export function useFactoryScreen({
 
   return {
     document: doc,
-    documentErrors: check.errors,
+    documentErrors: linkError ? [...check.errors, linkError] : check.errors,
+    embedded,
+    subformFor,
+    registerSubform,
+    subformDirty,
     popup,
     fieldsFor,
     openEditor,

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/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)
     }
@@ -107,6 +162,7 @@ export function validateDocument(doc, controls = CONTROLS) {
     if (node.type === 'stepper') checkSteps(props, at, err)
     checkStep(node, doc, at, err)
     if (node.type === 'list') checkList(props, doc, at, err)
+    if (node.type === 'subform') checkSubform(props, doc, at, err)
     if (node.type === 'label') {
       if (typeof props.text !== 'string') err(`${at}.props.text`, 'must be a string')
       if (props.variant !== undefined && !LABEL_VARIANTS.includes(props.variant)) err(`${at}.props.variant`, `must be one of: ${LABEL_VARIANTS.join(', ')}`)
@@ -330,6 +386,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(', ')}`)
@@ -351,6 +418,20 @@ function checkList(props, doc, at, err) {
   }
 }
 
+/**
+ * A form inside this one. Both halves are required: a form with no link saves
+ * a record belonging to nothing, and a link with no form is nothing. Itself is
+ * refused — a form containing itself draws forever.
+ */
+function checkSubform(props, doc, at, err) {
+  if (props.title !== undefined && typeof props.title !== 'string') err(`${at}.props.title`, 'must be a string')
+  if (!(nonEmptyString(props.screen) && SCREEN_ID.test(props.screen))) err(`${at}.props.screen`, 'is required — the id of the form drawn here, e.g. "bank_details_edit"')
+  else if (props.screen === doc.id) err(`${at}.props.screen`, 'cannot be this screen — a form cannot contain itself')
+  if (!(nonEmptyString(props.belongsTo) && /^[A-Za-z_][\w]*$/.test(props.belongsTo))) {
+    err(`${at}.props.belongsTo`, 'is required — the field on that form pointing back at this record, e.g. "employeeId"')
+  }
+}
+
 function nonEmptyString(v) {
   return typeof v === 'string' && v.trim() !== ''
 }