@xeplr/ui-factory 1.1.0 → 1.3.0

package/src/designs/PropertyPanel.jsx

@@ -1,7 +1,7 @@
 import { useEffect, useState } from 'react'
 import { getAtPath } from '../propertyPath.js'
 import { FIELD_PRESETS, presetFor } from '../presets.js'
-import { slugify, inputNodes } from '../document.js'
+import { slugify, inputNodes, paramsText } from '../document.js'
 import { FONT_FAMILIES, STYLE_KEYS, SCREEN_STYLE_KEYS, LIST_ACTIONS, FILE_KINDS } from '../controls.js'
 
 // The selected control's properties, GENERATED from its entry in controls.js:
@@ -58,7 +58,7 @@ function FieldType({ node, controls, hint, onConvert, onKeepPlain }) {
   )
 }
 
-export default function PropertyPanel({ doc, node, control, controls, errors, tables, screens, lockedNames, onChange, onConvert, hint, onScreenChange, onRemove, selectionCount }) {
+export default function PropertyPanel({ doc, node, control, controls, errors, tables, screens, lockedNames, onChange, onConvert, hint, onScreenChange, onRemove, onMakeChildTable, selectionCount }) {
   if (selectionCount > 1) {
     return (
       <aside className="xeplr-factory-panel">
@@ -109,6 +109,7 @@ export default function PropertyPanel({ doc, node, control, controls, errors, ta
                   node={node}
                   doc={doc}
                   errors={errs}
+                  onMakeChildTable={onMakeChildTable}
                 />
                 {locked
                   ? <div className="xeplr-factory-prop-help">Saved as a column of <code>{doc?.source}</code> — renaming it would leave its data behind. A rename is a migration.</div>
@@ -149,7 +150,15 @@ function ScreenPanel({ doc, errors, tables, onChange }) {
     return (
       <div key={field.path} className={`xeplr-factory-prop${msg ? ' has-error' : ''}`}>
         {field.type !== 'toggle' && field.type !== 'toggleValue' && <label className="xeplr-factory-prop-label" htmlFor={id}>{field.label}</label>}
-        <Editor id={id} field={field} value={getAtPath(doc, field.path)} onChange={(v) => onChange(field.path, v)} tables={tables} errors={[]} {...extra} />
+        <Editor
+          id={id}
+          field={field}
+          value={field.path === 'paramsLine' ? paramsText(doc) : getAtPath(doc, field.path)}
+          onChange={(v) => onChange(field.path, v)}
+          tables={tables}
+          errors={[]}
+          {...extra}
+        />
         {field.help && <div className="xeplr-factory-prop-help">{field.help}</div>}
         {msg && <div className="xeplr-factory-prop-error">{msg}</div>}
       </div>
@@ -161,9 +170,48 @@ function ScreenPanel({ doc, errors, tables, onChange }) {
         <span className="xeplr-factory-panel-type">Screen</span>
       </header>
       <p className="xeplr-factory-panel-empty">Select a control to change it, or drag one in from the left.</p>
+      <fieldset className="xeplr-factory-group">
+        <legend>About</legend>
+        {/* WHAT IT IS FOR. When a lot of people can make forms, a lot of
+            people make the same one — and the fields say what a form holds,
+            never what it was for or whether this is the one still in use. */}
+        {row({
+          path: 'description',
+          label: 'What this form is for',
+          type: 'textarea',
+          help: 'One sentence. It is what tells this apart from the other three called the same thing.'
+        }, TextareaEditor)}
+      </fieldset>
       <fieldset className="xeplr-factory-group">
         <legend>Data</legend>
         {row({ path: 'source', label: 'Saves to', type: 'table', help: 'The table this screen\'s records are saved in' }, TableEditor)}
+        {/* A MASTER is a list other forms point at — departments, statuses,
+            countries. A flag on an ordinary form, not a kind of its own. */}
+        {row({
+          path: 'master',
+          label: 'This is a master',
+          type: 'toggle',
+          help: 'A list other forms choose from. Masters are kept together in the admin section.'
+        }, EDITORS.toggle || TextEditor)}
+        {doc.master && row({
+          path: 'labelField',
+          label: 'Shown as',
+          type: 'select',
+          options: [{ value: '', label: '— choose a field —' }].concat(
+            inputNodes(doc).map((n) => ({ value: n.props.name, label: n.props.label || n.props.name }))
+          ),
+          help: 'What a picker shows for a record. Said once here, not on every dropdown.'
+        }, EDITORS.select || TextEditor)}
+        {/* WHAT THIS FORM IS CALLED WITH. One line, because that is the whole
+            question — "this form needs contentId, age, name". A field then
+            binds to one with {params.contentId} as its default, the same
+            brace used in a workflow step or a report. */}
+        {row({
+          path: 'paramsLine',
+          label: 'Inputs',
+          type: 'text',
+          help: 'Names, comma separated. A field takes one with {params.name} as its default.'
+        }, ListLineEditor)}
       </fieldset>
       <fieldset className="xeplr-factory-group">
         <legend>Size</legend>
@@ -181,6 +229,46 @@ function LockedEditor({ id, value }) {
   return <input id={id} className="xeplr-factory-prop-input xeplr-factory-mono" type="text" value={value ?? ''} readOnly aria-readonly="true" />
 }
 
+/**
+ * A LIST TYPED AS A LINE — the screen's inputs.
+ *
+ * Two bugs live here, and this shape is what avoids both.
+ *
+ * It cannot be a plain TextEditor: what is STORED is a list and what is SHOWN
+ * is that list joined again, so a comma is parsed away the moment it is typed
+ * ("a," → ["a"] → "a") and the box refuses to let anybody start a second name.
+ *
+ * And it cannot commit on BLUR, which was the first fix: pressing Publish is
+ * one gesture, so the blur and the click race, and a name typed just before
+ * publishing was not in the document the publish read. The screen went out
+ * with no inputs and nothing said why.
+ *
+ * So the text is kept HERE for display, and the document is told on every
+ * keystroke. Nothing is ever waiting to be committed, and the line somebody
+ * is typing is never rewritten under their fingers.
+ */
+function ListLineEditor({ id, value, onChange }) {
+  const [text, setText] = useState(value ?? '')
+  const [typing, setTyping] = useState(false)
+
+  // Taken from the document again when it changes underneath — a different
+  // screen, an undo — unless the box is being typed in right now, which is
+  // the only thing this local copy exists for.
+  useEffect(() => { if (!typing) setText(value ?? '') }, [value, typing])
+
+  return (
+    <input
+      id={id}
+      className="xeplr-factory-prop-input"
+      type="text"
+      value={text}
+      onFocus={() => setTyping(true)}
+      onChange={(e) => { setText(e.target.value); onChange(e.target.value) }}
+      onBlur={(e) => { setTyping(false); onChange(e.target.value) }}
+    />
+  )
+}
+
 function TextEditor({ id, value, onChange }) {
   return <input id={id} className="xeplr-factory-prop-input" type="text" value={value ?? ''} onChange={(e) => onChange(e.target.value)} />
 }
@@ -282,12 +370,113 @@ function ToggleValueEditor({ id, field, value, onChange }) {
 }
 
 /** A table name: picked from the app's tables when it lists them, typed otherwise. */
+/**
+ * WHERE A DROPDOWN'S OPTIONS COME FROM.
+ *
+ * MASTERS FIRST, by the name a person knows them as — "Departments", not
+ * "departments" — because those are the lists that exist to be pointed at. A
+ * flat list of thirty raw table names is one nobody can read, and nothing in
+ * it says which tables were meant for this.
+ *
+ * Everything else is still underneath. A dropdown may legitimately read from
+ * any table a published screen reads, and hiding those would replace a
+ * confusing list with a dead end.
+ *
+ * Two groups in a plain <select>, not a combobox: typing jumps to an option
+ * in every browser, which is the searching somebody actually wants here, and
+ * a widget of our own would have to reimplement the keyboard to match.
+ */
+/**
+ * The same picker, plus a way out of the dead end.
+ *
+ * A sub-table points at a table that usually does not exist yet, and the
+ * honest answer to "which table?" at that moment is "the one I am about to
+ * make". Without this the designer has to be left, a form built, and the
+ * thought recovered on the way back.
+ *
+ * Only on a LIST, and only when the host can make one: it is a server act.
+ */
+function ListTableEditor({ id, value, onChange, tables, node, doc, onMakeChildTable }) {
+  const [making, setMaking] = useState(false)
+  const [name, setName] = useState('')
+  const [busy, setBusy] = useState(false)
+  const [error, setError] = useState(null)
+  const canMake = Boolean(onMakeChildTable && doc && doc.source && node)
+
+  const make = async () => {
+    if (!name.trim() || busy) return
+    setBusy(true)
+    try {
+      await onMakeChildTable(node.id, name.trim())
+      setMaking(false)
+      setName('')
+      setError(null)
+    } catch (err) {
+      setError(err.message)
+    } finally {
+      setBusy(false)
+    }
+  }
+
+  if (making) {
+    return (
+      <div>
+        <input
+          id={id}
+          className="xeplr-factory-prop-input"
+          autoFocus
+          value={name}
+          placeholder="Characteristics"
+          onChange={(e) => setName(e.target.value)}
+          onKeyDown={(e) => { if (e.key === 'Enter') { e.preventDefault(); make() } }}
+        />
+        <div className="xeplr-factory-prop-help">
+          Makes a table of rows belonging to this one, and points this list at it.
+        </div>
+        {error && <div className="xeplr-factory-prop-error">{error}</div>}
+        <button type="button" className="xeplr-factory-primary" disabled={!name.trim() || busy} onClick={make}>
+          {busy ? 'Making it…' : 'Make the table'}
+        </button>
+        <button type="button" className="xeplr-factory-secondary" onClick={() => { setMaking(false); setError(null) }}>Cancel</button>
+      </div>
+    )
+  }
+
+  return (
+    <div>
+      <TableEditor id={id} value={value} onChange={onChange} tables={tables} />
+      {canMake && (
+        <button type="button" className="xeplr-factory-secondary" onClick={() => setMaking(true)}>
+          New table…
+        </button>
+      )}
+    </div>
+  )
+}
+
 function TableEditor({ id, value, onChange, tables }) {
-  if (tables && tables.items.length > 0) {
+  const items = (tables && tables.items) || []
+  if (items.length > 0) {
+    const masters = items.filter((t) => t.master)
+    const rest = items.filter((t) => !t.master)
+    // A SELECT WHOSE VALUE IS NOT AN OPTION SHOWS NOTHING, which reads as the
+    // setting having been lost. It has not: a table made a moment ago is not
+    // in a list fetched when the page opened, and a table whose screens were
+    // deleted is still what this list names.
+    const known = items.some((t) => String(t.id) === String(value || ''))
+    const stray = value && !known ? { id: value, name: value } : null
+    const option = (t) => <option key={String(t.id)} value={String(t.id)}>{t.name}</option>
+
     return (
       <select id={id} className="xeplr-factory-prop-input" value={value ?? ''} onChange={(e) => onChange(e.target.value || undefined)}>
         <option value="">{tables.loading ? 'Loading tables…' : '—'}</option>
-        {tables.items.map((t) => <option key={String(t.id)} value={String(t.id)}>{t.name}</option>)}
+        {stray && <option value={String(stray.id)}>{stray.name}</option>}
+        {masters.length > 0 && <optgroup label="Masters">{masters.map(option)}</optgroup>}
+        {/* Named as what they are, so it reads as "the rest" rather than as a
+            second list of the same kind of thing. */}
+        {rest.length > 0 && (
+          <optgroup label={masters.length > 0 ? 'Other tables' : 'Tables'}>{rest.map(option)}</optgroup>
+        )}
       </select>
     )
   }
@@ -301,7 +490,17 @@ function TableEditor({ id, value, onChange, tables }) {
  */
 function ColumnsEditor({ value, onChange, doc, node, screens }) {
   const editDoc = node && node.props.editScreen ? (screens || []).find((s) => s.id === node.props.editScreen)?.document : null
-  const from = doc && inputNodes(doc).length ? doc : editDoc
+
+  // A LIST OF ANOTHER TABLE IS NOT DESCRIBED BY THIS SCREEN. Pointing a list
+  // at material_characteristics and being offered the MATERIAL's fields is
+  // worse than being offered nothing: every one of them ticks a column that
+  // will be blank in every row.
+  //
+  // The edit screen for those rows is the only description to hand here — a
+  // host that did not provide it leaves this empty, and the list falls back
+  // to the columns the rows themselves have (see listColumns).
+  const foreign = node && node.props.source && doc && node.props.source !== doc.source
+  const from = foreign ? editDoc : (doc && inputNodes(doc).length ? doc : editDoc)
   const fields = from
     ? inputNodes(from).map((n) => ({ field: n.props.name, label: n.props.label || n.props.name }))
     : (Array.isArray(value) ? value : [])
@@ -313,7 +512,18 @@ function ColumnsEditor({ value, onChange, doc, node, screens }) {
     // All of them again is the same as "not set" — keep the document clean.
     onChange(next.length === fields.length || next.length === 0 ? undefined : next.map((c) => ({ field: c.field, label: (current.find((x) => x.field === c.field) || c).label })))
   }
-  if (!fields.length) return <div className="xeplr-factory-prop-help">Add fields to the screen first — the list shows them as columns.</div>
+  if (!fields.length) {
+    // Two different nothings, and saying "add fields to this screen" to
+    // somebody pointing a list at another table sends them to fix the wrong
+    // thing.
+    return (
+      <div className="xeplr-factory-prop-help">
+        {foreign
+          ? 'Every column of ' + node.props.source + '. Set "Edit in" to that table\'s form to choose.'
+          : 'Add fields to the screen first — the list shows them as columns.'}
+      </div>
+    )
+  }
   return (
     <div className="xeplr-factory-checklist">
       {fields.map((f) => (
@@ -523,6 +733,7 @@ export const EDITORS = {
   table: TableEditor,
   screen: ScreenEditor,
   columns: ColumnsEditor,
+  listTable: ListTableEditor,
   actions: ActionsEditor,
   dataSource: DataSourceEditor
 }

package/src/designs/factory.css

@@ -98,6 +98,31 @@
 .xeplr-factory-input:hover { border-color: color-mix(in srgb, var(--xf-accent) 45%, var(--xf-field-border)); }
 .xeplr-factory-textarea { padding-block: calc(8 * var(--xf-u)); resize: none; }
 .xeplr-factory-input:focus { outline: none; border-color: var(--xf-accent); box-shadow: 0 0 0 3px color-mix(in srgb, var(--xf-accent) 25%, transparent); }
+
+/* ── Dropdowns ─────────────────────────────────────────────────────────────
+   Every <select> the factory draws — on a screen, in the builder's panels, in
+   the flow designer — gets our own chevron, inset from the edge with room
+   kept for it. The browser's own sat against the border and in a different
+   place per platform. Drawn with two gradients rather than an SVG, so it is
+   the theme's muted ink and follows a dark theme. Only background-image and
+   its longhands are set: each box keeps its own colour, and a control's
+   Background (boxStyle) is a background-COLOR so it cannot wipe the arrow. */
+:is(.xeplr-factory-screen, .xeplr-factory-canvas, .xeplr-factory-flow-builder, .xeplr-factory-builder, .xeplr-factory-modal-backdrop) select:not([multiple]) {
+  -webkit-appearance: none;
+  appearance: none;
+  /* Two thin diagonals side by side — each corner to corner of its own small
+     square — meet at the bottom as a ∨. */
+  background-image:
+    linear-gradient(45deg, transparent 42%, var(--xf-muted) 42%, var(--xf-muted) 58%, transparent 58%),
+    linear-gradient(135deg, transparent 42%, var(--xf-muted) 42%, var(--xf-muted) 58%, transparent 58%);
+  background-position: calc(100% - 16px) 50%, calc(100% - 10px) 50%;
+  background-size: 6px 6px, 6px 6px;
+  background-repeat: no-repeat;
+  padding-right: 30px;
+  text-overflow: ellipsis;
+  cursor: pointer;
+}
+:is(.xeplr-factory-screen, .xeplr-factory-canvas, .xeplr-factory-flow-builder, .xeplr-factory-builder, .xeplr-factory-modal-backdrop) select:not([multiple]):disabled { cursor: default; opacity: .6; }
 .xeplr-factory-field.has-error .xeplr-factory-input { border-color: var(--xf-danger); }
 .xeplr-factory-error {
   /* In the gap BELOW the field, out of flow: a message appearing must not
@@ -460,3 +485,28 @@
   padding: 16px; border-radius: 8px; border: 1px solid var(--xf-border);
   background: var(--xf-surface); color: var(--xf-ink);
 }
+
+
+/* ── a child table, designed where it was made ─────────────────────────── */
+/* Wide, because what is inside is a whole designer: palette, canvas and
+   property panel. A form builder in a dialog box is a canvas nobody can
+   work on. */
+.xeplr-factory-modal--wide {
+  width: min(1600px, 96vw);
+  height: min(1000px, 92vh);
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+}
+.xeplr-factory-modal-head {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 10px 14px;
+  border-bottom: 1px solid var(--xf-border);
+}
+.xeplr-factory-modal-spacer { flex: 1; }
+/* hidden, not auto: the builder inside manages its own panes */
+.xeplr-factory-modal-body { flex: 1; min-height: 0; overflow: hidden; }
+.xeplr-factory-modal-body > * { height: 100%; }
+.xeplr-factory-builder--nested { min-height: 0; }

package/src/designs/styles.js

@@ -32,7 +32,7 @@ export function boxStyle(style) {
     fontStyle: s.fontStyle,
     textAlign: s.textAlign,
     color: s.color,
-    background: s.background,
+    backgroundColor: s.background,
     borderColor: s.borderColor,
     borderWidth: s.borderWidth != null ? `${s.borderWidth}px` : undefined,
     borderStyle: s.borderWidth != null ? 'solid' : undefined,

package/src/document.js

@@ -33,6 +33,53 @@ export const MARGIN = 0.04
 export const GAP = 0.025
 
 /** A new, empty screen. */
+/**
+ * WHAT A SCREEN IS CALLED WITH.
+ *
+ * A form can need things it must not ask for: a containment needs the
+ * complaint it belongs to, and the person filling it in does not know a
+ * twenty-five character id. So a screen declares its INPUTS the way an action
+ * declares its inputSchema — one named list, at the screen — and a field
+ * binds to one with the same `{token}` this product uses everywhere else:
+ *
+ *   props.default = '{params.complaintId}'
+ *
+ * A value with a token is a binding; a plain value is a literal. Nothing is
+ * marked on the field, because nothing needs to be: the brace already says
+ * which it is.
+ *
+ * Written as a plain list of names, the shortest thing that answers the
+ * question — "this form needs contentId, age, name".
+ */
+export function screenParams(doc) {
+  var raw = (doc && doc.params) || []
+  if (typeof raw === 'string') raw = raw.split(',')
+  return raw
+    .map(function (p) { return typeof p === 'string' ? { name: p.trim() } : p })
+    .filter(function (p) { return p && p.name })
+}
+
+/** The list as one line, which is how it is typed. */
+export function paramsText(doc) {
+  return screenParams(doc).map(function (p) { return p.name }).join(', ')
+}
+
+/** One line back to the list, for the panel. */
+export function setScreenParams(doc, text) {
+  var names = String(text == null ? '' : text)
+    .split(',')
+    .map(function (n) { return n.trim() })
+    .filter(Boolean)
+  var seen = {}
+  var params = []
+  names.forEach(function (n) {
+    if (seen[n]) return
+    seen[n] = true
+    params.push({ name: n })
+  })
+  return Object.assign({}, doc, { params: params })
+}
+
 export function createScreen({ name, id, aspect, width, source, style } = {}) {
   const title = String(name || 'Untitled screen').trim() || 'Untitled screen'
   const doc = {
@@ -60,6 +107,10 @@ export function renameScreen(doc, name) {
  */
 export function setScreenProperty(doc, path, value) {
   if (path === 'nodes' || path.startsWith('nodes.')) throw new Error('setScreenProperty cannot change nodes')
+  // The inputs are TYPED as one line and STORED as a list, so the document
+  // stays self-describing — the server, the CLI and a flow read names, not a
+  // string somebody has to split again.
+  if (path === 'paramsLine') return setScreenParams(doc, value)
   return setAtPath(doc, path, value)
 }
 

package/src/index.js

@@ -14,7 +14,9 @@ export { useFactoryScreen, normaliseOptions } from './useFactoryScreen.js'
 // This app's screens, shaped for another package's designer — see
 // useScreenSource.js. Two props instead of a page of glue per application.
 export { useScreenSource } from './useScreenSource.js'
-export { describeScreen, screenStub, loadScreens, keyFromName, editScreenOf } from './screenSource.js'
+export { describeScreen, screenStub, loadScreens, keyFromName, editScreenOf, masterForms, formKeyOf, deleteForm } from './screenSource.js'
+// Making a master: the one form shape every application repeats.
+export { masterSpec, createMaster, possibleParents, singularOf, MASTER_LABEL, MASTER_ORDER, childSpec, createChildTable } from './masters.js'
 export { useFlowRun } from './useFlowRun.js'
 export { useFlowBuilder, FLOW_AUTOSAVE_DELAY } from './useFlowBuilder.js'
 

package/src/masters.js

@@ -0,0 +1,193 @@
+// MAKING A MASTER — the one form shape every application repeats.
+//
+// Departments, statuses, countries, categories, reasons, priorities. They are
+// all the same three things, and designing them one by one is drawing the same
+// form over and over:
+//
+//   name         what it is called — what every picker shows
+//   sortOrder    the order somebody wants to see them in, which is almost
+//                never alphabetical: Low / Medium / High, not High / Low /
+//                Medium
+//   parent       the master it belongs to, when there is one — a state in a
+//                country, a sub-category in a category
+//
+// So a master is MADE, not designed: name it, say what it belongs to, and it
+// exists. It is still an ordinary form afterwards — its design opens in the
+// builder like any other, and a fourth field can be added to it — because a
+// master is a flag on a form and not a kind of form (see screenSource.js).
+//
+// Pure except for `createMaster`, which is the one place that talks to the
+// server; the spec it builds is a plain object anything can check.
+
+import { screensFromSpec, entityNames } from './generate.js'
+import { describeScreen, formKeyOf } from './screenSource.js'
+
+/** The field every master is shown by. Said once, here and in labelField. */
+export var MASTER_LABEL = 'name'
+
+/** The field every master is ordered by. */
+export var MASTER_ORDER = 'sortOrder'
+
+/**
+ * "Departments" → "department": what the ENTITY is called.
+ *
+ * A master is named in the plural, because it is a list — and an entity is
+ * named in the singular, because it is one row. entityNames does not know
+ * that, so "Departments" straight through makes a `departmentses` table and a
+ * screen called department**s**_edit. Nobody notices until the table is
+ * created, and then it cannot be renamed.
+ *
+ * Crude on purpose: enough for the words masters are actually called, and
+ * wrong quietly rather than cleverly — the key is shown before anything is
+ * made, and can be typed over.
+ */
+export function singularOf(label) {
+  var words = String(label || '').trim().split(/\s+/).filter(Boolean)
+  if (!words.length) return ''
+  var last = words[words.length - 1]
+  words[words.length - 1] = /ies$/i.test(last) ? last.slice(0, -3) + 'y'
+    : /(ss|us|is)$/i.test(last) ? last
+    : /s$/i.test(last) ? last.slice(0, -1)
+    : last
+  return words.join(' ')
+}
+
+/**
+ * The entity spec for a master.
+ *
+ * @param name    what it is called, as a person writes it — "Departments"
+ * @param parent  optional { table, label } — the master this one belongs to
+ * @param plural  optional, when the plural is not name + s
+ */
+export function masterSpec({ name, parent, plural }) {
+  var label = String(name || '').trim()
+  if (!label) throw new Error('A master needs a name, e.g. "Departments"')
+
+  var fields = [
+    // Required, because a master row with no name is a blank line in every
+    // dropdown that points at it.
+    { label: 'Name', type: 'text', required: true },
+    // Not required: most lists are fine alphabetical, and a number somebody
+    // is forced to invent for every row is a tax on adding one.
+    { label: 'Sort order', type: 'number' }
+  ]
+
+  if (parent && parent.table) {
+    fields.push({
+      label: parent.label || 'Belongs to',
+      type: 'dropdown',
+      table: parent.table,
+      required: true
+    })
+  }
+
+  return { entity: entityNames(singularOf(label), plural).singular, plural: plural, fields: fields }
+}
+
+/**
+ * Make one: both screens, marked as a master, published.
+ *
+ * PUBLISHED, because a master that is a draft has no table, so nothing can
+ * point at it and nobody can add a row — which is the whole of what a master
+ * is for. The one case where publishing on somebody's behalf is right: there
+ * is no design decision left to make.
+ *
+ * @param api     a createFactoryApi() instance
+ * @param spec    { name, parent, plural } — see masterSpec
+ * @returns the new master, as describeScreen reports it
+ */
+export async function createMaster(api, spec) {
+  var pair = screensFromSpec(masterSpec(spec))
+
+  // The FLAG goes on the edit screen: it is the one that describes the
+  // record, and labelField can only name a field that exists there.
+  var edit = Object.assign({}, pair.edit, { master: true, labelField: MASTER_LABEL })
+  var list = Object.assign({}, pair.list, { master: true })
+
+  // Drafts first, then published — the same two steps the builder takes, so a
+  // master is not a second way of writing a screen.
+  await api.saveDraft(edit)
+  await api.saveDraft(list)
+  await api.publish(edit)
+  await api.publish(list)
+
+  return describeScreen(edit)
+}
+
+/**
+ * A CHILD TABLE — rows that belong to one record of another form.
+ *
+ * This material's characteristics, this order's lines. Two fields and a link,
+ * which is the whole of what a sub-table is before somebody designs it:
+ *
+ *   name     what the row is
+ *   value    what it says — optional, but it is why most sub-tables exist
+ *   <link>   the record it belongs to, DECLARED AS AN INPUT so the list that
+ *            opens it can supply it (see screenParams). Bound with
+ *            {params.<link>} rather than typed, hidden when given and asked
+ *            when not — the same field, whether it is opened from a material
+ *            or on its own.
+ *
+ * @param name    what the child is called — "Material characteristics"
+ * @param parent  { table, label, link } — the form it belongs to, and the
+ *                column pointing back at it
+ */
+export function childSpec({ name, parent, plural }) {
+  var label = String(name || '').trim()
+  if (!label) throw new Error('A table needs a name, e.g. "Characteristics"')
+  if (!parent || !parent.table || !parent.link) throw new Error('A child table needs the record it belongs to')
+
+  return {
+    entity: entityNames(singularOf(label), plural).singular,
+    plural: plural,
+    fields: [
+      // The link first, because it is what the row IS before it is anything
+      // else — and hidden in practice, since the list supplies it.
+      { label: parent.linkLabel || parent.label || 'Belongs to', name: parent.link,
+        type: 'dropdown', table: parent.table, required: true, default: '{params.' + parent.link + '}' },
+      { label: 'Name', type: 'text', required: true },
+      { label: 'Value', type: 'text' }
+    ]
+  }
+}
+
+/**
+ * Make one, published, with the link declared as an input.
+ *
+ * Published for the same reason a master is: a draft has no table, so the
+ * list that is about to point at it would have nothing to read.
+ *
+ * @returns { key, edit, list, link } — what the List control needs to be
+ *          pointed at it.
+ */
+export async function createChildTable(api, spec) {
+  var pair = screensFromSpec(childSpec(spec))
+  var link = spec.parent.link
+
+  // The link is what this screen is CALLED WITH. Declared here rather than
+  // left as an ordinary field so the form knows not to ask for it when the
+  // list already said.
+  var edit = Object.assign({}, pair.edit, { params: [{ name: link }] })
+
+  await api.saveDraft(edit)
+  await api.saveDraft(pair.list)
+  await api.publish(edit)
+  await api.publish(pair.list)
+
+  return {
+    key: formKeyOf(edit.id), edit: edit.id, list: pair.list.id, source: edit.source, link: link,
+    // What it holds, so a list pointed at it can show the right columns
+    // without reading the document back.
+    fields: describeScreen(edit).fields.map(function (f) { return { name: f.name, label: f.name } })
+  }
+}
+
+/**
+ * The masters another master may belong to: every one except itself.
+ *
+ * A master that is its own parent is a row that can never be filled in, and
+ * the dropdown would offer the record being created.
+ */
+export function possibleParents(masters, exceptKey) {
+  return (masters || []).filter(function (m) { return m && m.key && m.key !== exceptKey })
+}

package/src/model.js

@@ -8,6 +8,7 @@ export {
   DOCUMENT_KIND, DOCUMENT_VERSION, DEFAULT_ASPECT, DEFAULT_WIDTH, MARGIN, GAP,
   createScreen, renameScreen, setScreenProperty, addControl, moveNode, setNodeProperty, getNodeProperty, removeNodes,
   inputNodes, readingOrder, contentBottom, camelName, slugify, uniqueFieldName, nextPosition,
+  screenParams, paramsText, setScreenParams,
   steppers, stepsOf, stepOf, setNodeStep, nodesForSteps, resolveStep, reachableStep, nextOpenStep
 } from './document.js'
 export { validateDocument, assertValidDocument } from './validateDocument.js'
@@ -21,6 +22,10 @@ export {
   columnForField, tableForScreen, columnSql, widening, diffTables, migrationFor, nextMigrationName,
   createStatements, addStatements, alterStatement, dropStatement, columnFromDatabase, planTableChange, conversionFor
 } from './tableSchema.js'
+// A value with a {params.x} token is a binding; a plain value is a literal.
+export { resolveBinding, isBinding } from './values.js'
+// A code people can read out, unlike the record's own key.
+export { codeFields, countedFields, generateCode } from './values.js'
 export { FIELD_PRESETS, PATTERNS, INPUT_TYPES, presetFor, presetProps, suggestPreset, presetGroup, presetHints, convertField } from './presets.js'
 export { createFlowsApi } from './flows.js'
 export {