@xeplr/ui-factory 1.2.0 → 1.4.0

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 {

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
@@ -76,6 +79,32 @@ export function FactoryScreen(props) {
       ctrl={ctrl}
       className={props.className}
       style={props.style}
+      // A form inside this one: the same component again, saving into its own
+      // table, checked and saved by this one's Save (see useFactoryScreen).
+      // Keyed by the form, never by this record's id — a new record's first
+      // save changes that id while the subform is being saved.
+      renderSubform={(node, sub) => (
+        <FactoryScreen
+          key={`${node.id}:${sub.document.id}`}
+          document={sub.document}
+          record={sub.record || undefined}
+          link={node.props.belongsTo}
+          onReady={(api) => ctrl.registerSubform(node.id, api)}
+          onDirtyChange={(d) => ctrl.subformDirty(node.id, d)}
+          recordKey={props.recordKey}
+          onSave={props.onSave}
+          fetchOptions={props.fetchOptions}
+          fetchRecord={props.fetchRecord}
+          fetchRecords={props.fetchRecords}
+          onDelete={props.onDelete}
+          uploadFile={props.uploadFile}
+          fileUrl={props.fileUrl}
+          screens={props.screens}
+          loadScreen={props.loadScreen}
+          controls={props.controls}
+          hooks={props.hooks}
+        />
+      )}
       renderPopup={(popup) => (
         <ScreenModal
           title={popup.document ? popup.document.name : 'Loading…'}
@@ -91,6 +120,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 +167,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,