@xeplr/ui-factory 1.2.0 → 1.3.0

package/src/pages.jsx

@@ -28,6 +28,9 @@ export function FactoryBuilder(props) {
       ctrl={ctrl}
       className={props.className}
       style={props.style}
+      // So a child table made here can be designed here — see the modal in
+      // BuilderSample. Supplied by createFactoryApi's builderProps.
+      screenApi={props.screenApi}
       renderPreview={(doc) => (
         // Preview never writes: onSave/onDelete are left out on purpose.
         <FactoryScreen
@@ -91,6 +94,10 @@ export function FactoryScreen(props) {
               key={`${popup.screenId}:${popup.record ? popup.record[ctrl.recordKey] : 'new'}`}
               document={popup.document}
               record={popup.record}
+              // What the sub-table calls it with: the column pointing back at
+              // the record this list is on. Hidden on the form when the
+              // screen says a field is filled in by whoever opens it.
+              params={popup.params || undefined}
               recordKey={props.recordKey}
               onSave={ctrl.popupSave}
               fetchOptions={props.fetchOptions}
@@ -134,7 +141,10 @@ export function FlowRunner(props) {
   const screen = useFactoryScreen({
     ...props,
     document: run.document || EMPTY_SCREEN,
-    record: run.values || undefined
+    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
   })
   return (
     <FlowRunnerSample

package/src/remote.js

@@ -13,6 +13,8 @@
  * @param options.fetch  a fetch that adds auth and tenant headers (e.g. @xeplr/ui-account's authFetch)
  * @param options.base   prefix before /factory, if the router is mounted elsewhere (default '')
  */
+import { createChildTable } from './masters.js'
+
 export function createFactoryApi({ fetch: doFetch, base = '' } = {}) {
   if (typeof doFetch !== 'function') throw new Error('createFactoryApi: pass { fetch } — usually authFetch from @xeplr/ui-account')
 
@@ -95,11 +97,23 @@ export function createFactoryApi({ fetch: doFetch, base = '' } = {}) {
       confirmConvert: (options && options.confirmConvert) || []
     })),
     listTables: () => call('GET', '/tables'),
+    // DELETE A FORM'S SCREEN. The design always goes; the table only when it
+    // is empty and nothing else describes it — the answer says which
+    // happened, and how many records kept it. Refused while another
+    // published screen chooses from this form's table.
+    deleteScreen: async (key) => one(await call('DELETE', `/screens/${enc(key)}`)),
     // A new form from its name: { entity, plural? } → { entity, name, source, edit, list } — both screens as drafts.
     createEntity: async (spec) => one(await call('POST', '/entities', spec)),
 
     // records
-    fetchRecords: ({ screen }) => call('GET', `/records/${enc(screen)}`),
+    // `belongsTo` + `belongsToId`: a sub-table on a form asks for the rows of
+    // another table that belong to THIS record. Without an owner the server
+    // answers with none — a record that has not been saved yet owns nothing,
+    // and showing the whole table there is how somebody edits another
+    // record's lines.
+    fetchRecords: ({ screen, belongsTo, belongsToId }) => call('GET', belongsTo
+      ? `/records/${enc(screen)}?belongsTo=${enc(belongsTo)}&belongsToId=${enc(belongsToId == null ? '' : belongsToId)}`
+      : `/records/${enc(screen)}`),
     // One record, through the screen's get hooks — what Edit opens.
     fetchRecord: async ({ screen, id }) => one(await call('GET', `/records/${enc(screen)}/${enc(id)}`)),
     onSave: async (values, { id, screen }) => one(await call('POST', `/records/${enc(screen)}/save`, { id, values })),
@@ -116,6 +130,12 @@ export function createFactoryApi({ fetch: doFetch, base = '' } = {}) {
     fileUrl: (path) => `${base}/factory/files/${String(path).split('/').map(enc).join('/')}`
   }
   api.screenProps = { loadScreen: api.loadScreen, onSave: api.onSave, fetchRecords: api.fetchRecords, fetchRecord: api.fetchRecord, onDelete: api.onDelete, fetchOptions: api.fetchOptions, uploadFile: api.uploadFile, fileUrl: api.fileUrl }
-  api.builderProps = { onSave: api.saveDraft, onPublish: api.publish, listTables: api.listTables, fetchOptions: api.fetchOptions, fetchRecords: api.fetchRecords }
+  // makeChildTable: a list on a form can make the table it is about to point
+  // at — rows belonging to this record — without leaving the designer. A
+  // server act, which is why the builder is given it rather than doing it.
+  api.builderProps = { onSave: api.saveDraft, onPublish: api.publish, listTables: api.listTables, fetchOptions: api.fetchOptions, fetchRecords: api.fetchRecords, makeChildTable: function (spec) { return createChildTable(api, spec) },
+    // The builder designs a child table in place, which needs the same calls
+    // this api already makes — handed over rather than rebuilt.
+    screenApi: api }
   return api
 }

package/src/screenSource.js

@@ -15,7 +15,7 @@
 //
 // Pure: no React. The hook around it is useScreenSource.js.
 
-import { inputNodes } from './document.js'
+import { inputNodes, screenParams } from './document.js'
 
 /**
  * A screen document → what the designer needs.
@@ -29,12 +29,65 @@ export function describeScreen(doc) {
   return {
     key: doc.id,
     name: doc.name || doc.id,
+    description: doc.description || null,
     fields: inputNodes(doc).map(function (n) {
       return { name: n.id, type: n.type }
-    })
+    }),
+    // WHAT THIS SCREEN IS CALLED WITH — the inputs it declares, the way an
+    // action declares its inputSchema. A flow's Screen step asks for exactly
+    // these; a screen that declares none is asked for nothing.
+    inputs: screenParams(doc).map(function (p) {
+      return { name: p.name, label: p.label || p.name, type: p.type || 'string', required: Boolean(p.required) }
+    }),
+    // A MASTER is a list other forms point at. Reported here so a picker can
+    // offer "Departments" before it offers thirty raw table names, and so the
+    // admin section can gather them without reading every document again.
+    master: Boolean(doc.master),
+    labelField: doc.labelField || null,
+    source: doc.source || null
   }
 }
 
+/** The form a screen belongs to: task_edit and task_list are one form. */
+export function formKeyOf(screenKey) {
+  var m = /^(.*)_(edit|list)$/.exec(String(screenKey || ''))
+  return m ? m[1] : String(screenKey || '')
+}
+
+/**
+ * THE MASTERS, gathered from the screens an app has.
+ *
+ * A master is a property of the FORM, and a form is two screens — the edit
+ * screen is where it is declared, because that is the one that describes the
+ * record. The list screen is what the admin section opens, because looking at
+ * a master means looking at its rows.
+ *
+ * Returns [{ key, name, labelField, edit, list, source }], by name.
+ */
+export function masterForms(screens) {
+  var byForm = {}
+  ;(screens || []).forEach(function (sc) {
+    if (!sc || !sc.key) return
+    var form = formKeyOf(sc.key)
+    var entry = byForm[form] || (byForm[form] = { key: form, name: null, labelField: null, edit: null, list: null, source: null })
+    if (/_list$/.test(sc.key)) entry.list = sc.key
+    else entry.edit = sc.key
+    if (sc.master) {
+      entry.master = true
+      entry.name = entry.name || sc.name
+      entry.labelField = entry.labelField || sc.labelField
+      entry.source = entry.source || sc.source
+    }
+    // A name to show even when the flag is on the other half of the pair.
+    if (!entry.name && !/_list$/.test(sc.key)) entry.name = sc.name
+  })
+
+  return Object.keys(byForm)
+    .map(function (k) { return byForm[k] })
+    .filter(function (f) { return f.master })
+    .sort(function (a, b) { return String(a.name).localeCompare(String(b.name)) })
+}
+
 /** A listing row → the same shape, before its document has been read. */
 export function screenStub(row) {
   if (!row) return null
@@ -69,6 +122,36 @@ export async function loadScreens(api, onList) {
   }))
 }
 
+/**
+ * DELETE A FORM — both of its screens.
+ *
+ * The list first, then the edit screen: while the list still exists the table
+ * is still described, so the edit screen's delete is the one that can find
+ * the table unused and empty. The other order leaves the table behind.
+ *
+ * @returns what became of the table: { table, tableDropped, records }
+ */
+export async function deleteForm(api, form) {
+  if (!form || !form.key) throw new Error('Which form?')
+
+  // A HALF OF A FORM IS A KEY OR THE ROW THAT CARRIES ONE. Callers group
+  // screens for their own listing and hold whatever was convenient — a key
+  // here, a listing row there — and a row put into a URL reads as
+  // "[object Object]", which is a 404 naming a screen nobody could have
+  // asked for.
+  var half = function (x) {
+    if (!x) return null
+    return typeof x === 'string' ? x : (x.screenKey || x.id || x.key || null)
+  }
+
+  var list = half(form.list)
+  var edit = half(form.edit) || form.key
+
+  if (list) await api.deleteScreen(list)
+  var last = await api.deleteScreen(edit)
+  return last || { table: null, tableDropped: false, records: null }
+}
+
 /** "Leave request" → "leave_request": what a new form is keyed by. */
 export function keyFromName(label) {
   return String(label == null ? '' : label)

package/src/tableSchema.js

@@ -55,6 +55,8 @@ export const MAX_IDENTIFIER = 63
 
 const TEXT_DEFAULT_LENGTH = 255
 const OPTION_MIN_LENGTH = 50
+// prefix (8) + separator + six characters, with room to spare.
+const ID_CODE_LENGTH = 24
 const FILE_PATH_LENGTH = 255
 
 /**
@@ -68,6 +70,15 @@ export function columnForField(node) {
   switch (node.type) {
     case 'text':
       return { ...base, type: 'varchar', length: v.maxLength || TEXT_DEFAULT_LENGTH }
+    // AN IDENTIFIER. The kind decides the column, which is the point of it
+    // being a type: a counted number is the database's to assign (identity,
+    // so an insert that does not mention it still gets one), and a code is a
+    // short string the server writes. Unique either way — an identifier two
+    // rows share is not one.
+    case 'id':
+      return p.idKind === 'auto'
+        ? { ...base, type: 'integer', identity: true, notNull: true, unique: true }
+        : { ...base, type: 'varchar', length: ID_CODE_LENGTH, unique: true }
     case 'textarea':
       return { ...base, type: 'text' }
     case 'number':
@@ -114,8 +125,13 @@ export function columnSql(col) {
   const type = col.type === 'varchar' ? `varchar(${col.length})` : col.type
   const parts = [type]
   if (col.references) parts.push(`REFERENCES ${q(col.references)}("id")`)
+  // BY DEFAULT, not ALWAYS: the database counts, and an import carrying real
+  // numbers can still write its own. ALWAYS would refuse them outright.
+  if (col.identity) parts.push('GENERATED BY DEFAULT AS IDENTITY')
   if (col.notNull) parts.push('NOT NULL')
   if (col.default !== undefined) parts.push(`DEFAULT ${col.default}`)
+  // An identifier two rows share is not one.
+  if (col.unique) parts.push('UNIQUE')
   return parts.join(' ')
 }
 

package/src/useFactoryBuilder.js

@@ -42,7 +42,22 @@ import { selectionPlace } from './urlState.js'
  *                    `<urlKey>Selected` and `<urlKey>Steps`, so a refresh or a shared
  *                    link lands on the same control. Omitted → kept in memory.
  */
-export function useFactoryBuilder({ document: given, name, onSave, onChange, onPublish, listTables, screens, lockedNames, controls = CONTROLS, autosaveDelay = 800, urlKey } = {}) {
+/**
+ * What the link column on a child is called: materials → materialId.
+ *
+ * From the parent's TABLE rather than its name, because the table is what the
+ * column points at and is the thing that cannot be renamed later.
+ */
+function linkNameFor(doc) {
+  var table = String((doc && doc.source) || 'parent').replace(/[^A-Za-z0-9]+/g, '_').replace(/_+$/, '')
+  var singular = /ies$/.test(table) ? table.slice(0, -3) + 'y'
+    : /(ss|us|is)$/.test(table) ? table
+    : /s$/.test(table) ? table.slice(0, -1)
+    : table
+  return singular.replace(/_([a-z])/g, function (_, c) { return c.toUpperCase() }) + 'Id'
+}
+
+export function useFactoryBuilder({ document: given, name, onSave, onChange, onPublish, listTables, makeChildTable, screens, lockedNames, controls = CONTROLS, autosaveDelay = 800, urlKey } = {}) {
   const [doc, setDoc] = useState(() => given || createScreen({ name }))
 
   // ── selection ─────────────────────────────────────────────────────────
@@ -105,6 +120,11 @@ export function useFactoryBuilder({ document: given, name, onSave, onChange, onP
   const [tables, setTables] = useState({ loading: Boolean(listTables), items: [], error: null })
   const listTablesRef = useRef(listTables); listTablesRef.current = listTables
   const hasListTables = Boolean(listTables)
+  // Bumped when this designer MAKES a table. The list is otherwise fetched
+  // once, which was right while tables only ever appeared elsewhere — and
+  // wrong the moment "New table…" existed: the table was made, the list was
+  // pointed at it, and the picker had never heard of it, so it showed blank.
+  const [tableRound, setTableRound] = useState(0)
   useEffect(() => {
     if (!hasListTables) return undefined
     let cancelled = false
@@ -117,7 +137,7 @@ export function useFactoryBuilder({ document: given, name, onSave, onChange, onP
       })
       .catch((err) => { if (!cancelled) setTables({ loading: false, items: [], error: err.message || 'Could not list tables' }) })
     return () => { cancelled = true }
-  }, [hasListTables])
+  }, [hasListTables, tableRound])
 
   // ── edits ─────────────────────────────────────────────────────────────
   const rename = useCallback((value) => update((d) => renameScreen(d, value)), [update])
@@ -276,6 +296,8 @@ export function useFactoryBuilder({ document: given, name, onSave, onChange, onP
   // Deliberate, unlike saving: a half-finished design must not reach everyone
   // filling the form in.
   const onPublishRef = useRef(onPublish); onPublishRef.current = onPublish
+  const makeChildTableRef = useRef(makeChildTable); makeChildTableRef.current = makeChildTable
+  const [designingChild, setDesigningChild] = useState(null)
   const [publishing, setPublishing] = useState(false)
   const [publishResult, setPublishResult] = useState(null)   // { ok, message, version?, detail? }
   /**
@@ -379,6 +401,85 @@ export function useFactoryBuilder({ document: given, name, onSave, onChange, onP
     },
     visibleNodes,
     setProperty,
+    /**
+     * A list's table, and the columns that only made sense for the old one.
+     *
+     * Chosen columns are field names. Point the list at another table and
+     * every one of them is a name that table has never heard of — so the grid
+     * keeps drawing the old headers over blank cells, which reads as the
+     * panel not having noticed the change. Clearing them falls back to "all
+     * the columns the rows have", which is right for whatever it now points
+     * at.
+     *
+     * The link goes too: it belonged to the old table's shape.
+     */
+    setListSource: function (nodeId, table) {
+      update(function (d) {
+        var node = d.nodes.find(function (n) { return n.id === nodeId })
+        var was = node && node.props ? node.props.source : undefined
+        var next = setNodeProperty(d, nodeId, 'props.source', table || undefined)
+        if ((was || '') === (table || '')) return next
+        next = setNodeProperty(next, nodeId, 'props.columns', undefined)
+        return setNodeProperty(next, nodeId, 'props.belongsTo', undefined)
+      })
+    },
+    /**
+     * Make the table a list is about to point at, and point it there.
+     *
+     * TWO PROPERTIES AT ONCE, which is why it is here rather than a button in
+     * the panel: a table without its link is a list of everybody's rows, and
+     * a link without a table is nothing at all. Neither half is a state worth
+     * being able to reach.
+     *
+     * The host does the making (it is a server act, and this package does not
+     * know where the server is) and answers with what the list needs.
+     */
+    // The child just made, waiting to be designed — { nodeId, screenKey }.
+    // Nothing is forced: closing it leaves a table with the two fields it was
+    // made with, which is a working sub-table.
+    designingChild: designingChild,
+    closeChild: function (screen) {
+      // Designed and published: its fields are the list's columns now. A
+      // close with nothing keeps what was set when it was made.
+      if (screen && Array.isArray(screen.fields) && designingChild) {
+        var link = designingChild.link
+        var columns = screen.fields
+          .filter(function (f) { return f.name !== link })
+          .map(function (f) { return { field: f.name, label: f.label || f.name } })
+        if (columns.length) {
+          var nodeId = designingChild.nodeId
+          update(function (d) { return setNodeProperty(d, nodeId, 'props.columns', columns) })
+        }
+      }
+      setDesigningChild(null)
+    },
+
+    makeChildTable: makeChildTableRef.current ? async function (nodeId, name) {
+      var made = await makeChildTableRef.current({
+        name: name,
+        parent: { table: docRef.current.source, label: docRef.current.name, link: linkNameFor(docRef.current) }
+      })
+      if (!made || !made.source) throw new Error('Could not make that table')
+      // So the picker knows the table this list is about to name.
+      setTableRound(function (n) { return n + 1 })
+      update(function (d) {
+        var withTable = setNodeProperty(d, nodeId, 'props.source', made.source)
+        var linked = setNodeProperty(withTable, nodeId, 'props.belongsTo', made.link)
+        // The child's own columns, which are known because it was just made
+        // — minus the link, which is the list itself and not a column anybody
+        // asked to see.
+        var columns = (made.fields || [])
+          .filter(function (f) { return f.name !== made.link })
+          .map(function (f) { return { field: f.name, label: f.label || f.name } })
+        return columns.length ? setNodeProperty(linked, nodeId, 'props.columns', columns) : linked
+      })
+      // STRAIGHT INTO ITS DESIGNER. A sub-table is made for the fields it is
+      // going to hold, and "Name" and "Value" are a guess at those — so the
+      // form opens where it was made, rather than being something to go and
+      // find afterwards with the thought already lost.
+      setDesigningChild({ nodeId: nodeId, screenKey: made.edit, link: made.link, name: name })
+      return made
+    } : null,
     convertControl,
     hints,
     removeSelected,

package/src/useFactoryScreen.js

@@ -52,9 +52,16 @@ 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,
   controls = CONTROLS
 } = {}) {
   const check = useMemo(() => validateDocument(doc, controls), [doc, controls])
@@ -100,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) : {}))
@@ -484,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
+            })
           }
         }
       }))
@@ -545,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/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)
     }
@@ -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(', ')}`)