@xeplr/ui-factory 1.0.1 → 1.0.3

package/src/model.js

@@ -3,13 +3,20 @@
 //
 //   import { screenFromSpec, validateDocument, formSchema } from '@xeplr/ui-factory/model'
 
-export { CONTROLS, OPTION_ID, OPTION_LABEL, LABEL_VARIANTS, BUTTON_ACTIONS, controlGroups, withControls } from './controls.js'
+export { CONTROLS, OPTION_ID, OPTION_LABEL, LABEL_VARIANTS, LABEL_PRESETS, LIST_ACTIONS, STYLE_KEYS, SCREEN_STYLE_KEYS, FONT_FAMILIES, controlGroups, withControls } from './controls.js'
 export {
-  DOCUMENT_KIND, DOCUMENT_VERSION, DEFAULT_ASPECT, MARGIN, GAP,
-  createScreen, renameScreen, addControl, moveNode, setNodeProperty, getNodeProperty, removeNodes,
+  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
 } from './document.js'
 export { validateDocument, assertValidDocument } from './validateDocument.js'
-export { formSchema, initialValues, parseInput, validateValues, fieldError, sameId, optionValue } from './values.js'
-export { screenFromSpec, SPEC_HEIGHTS, ROW_GAP } from './generate.js'
+export { formSchema, initialValues, parseInput, validateValues, fieldError, sameId, optionValue, saveState, recordValues, displayValue, listColumns, listSource } from './values.js'
+export { screenFromSpec, screensFromSpec, entityNames, SPEC_HEIGHTS, ROW_GAP } from './generate.js'
+export { scaffoldEntity } from './scaffold.js'
 export { getAtPath, setAtPath } from './propertyPath.js'
+export { createFactoryApi } from './remote.js'
+export {
+  STANDARD_COLUMNS, RESERVED_COLUMNS, MAX_IDENTIFIER,
+  columnForField, tableForScreen, columnSql, widening, diffTables, migrationFor, nextMigrationName,
+  createStatements, addStatements, alterStatement, dropStatement, columnFromDatabase, planTableChange
+} from './tableSchema.js'

package/src/pages.jsx

@@ -1,16 +1,20 @@
 import { useFactoryBuilder } from './useFactoryBuilder.js'
 import { useFactoryScreen } from './useFactoryScreen.js'
-import { BuilderSample, ScreenSample } from './designs/index.js'
+import { BuilderSample, ScreenSample, ScreenModal } from './designs/index.js'
 
 /**
- * The builder, ready-made.
+ * The builder, ready-made. Saves itself — there is no Save button.
  *
  * @prop document     the screen to edit (omit for a new one)
  * @prop name         name for a new screen
- * @prop onSave       async (document) → void — the app stores it; only called with a valid document
+ * @prop onSave       async (document) → void — called automatically after edits, only with a valid document
  * @prop onChange     (document) → void — every edit
- * @prop listTables   async () → [{ id, name }] | string[] — for "dropdown from a table"
- * @prop fetchOptions async ({ table }) → [{ id, name }] — enables Preview with real options
+ * @prop onPublish    async (document) → { version } — shows a Publish button; throw to refuse, with `detail` to show (e.g. the migration to run)
+ * @prop listTables   async () → [{ id, name }] | string[] — for "Saves to", lists and table dropdowns
+ * @prop fetchOptions async ({ table }) → [{ id, name }] — Preview with real options
+ * @prop fetchRecords async ({ source }) → records — Preview with real records
+ * @prop lockedNames  field names that are already columns of the table — shown read-only
+ * @prop screens      [{ id, name, document? }] — other screens: "Edit in" choices, and Preview's popups
  * @prop controls     control registry (default: built-ins)
  */
 export function FactoryBuilder(props) {
@@ -21,22 +25,70 @@ export function FactoryBuilder(props) {
       className={props.className}
       style={props.style}
       renderPreview={(doc) => (
-        <FactoryScreen document={doc} fetchOptions={props.fetchOptions} controls={props.controls} />
+        // Preview never writes: onSave/onDelete are left out on purpose.
+        <FactoryScreen
+          document={doc}
+          fetchOptions={props.fetchOptions}
+          fetchRecords={props.fetchRecords}
+          screens={Object.fromEntries((props.screens || []).filter((s) => s.document).map((s) => [s.id, s.document]))}
+          controls={props.controls}
+        />
       )}
     />
   )
 }
 
 /**
- * A saved screen, running.
+ * A saved screen, running. Saves itself in the background — there is no submit.
  *
  * @prop document     a screen document (an invalid one renders its problems, loudly)
+ * @prop record       the record to open (omit for a new one)
+ * @prop recordKey    the id field on a record (default 'id')
+ * @prop onSave       async (values, { id, source, document }) → the saved record, with its id
  * @prop fetchOptions async ({ table }) → [{ id, name }] — rows for table dropdowns
- * @prop onSubmit     async (values, { document }) → void
- * @prop values       starting values, e.g. the record being edited
+ * @prop fetchRecords async ({ source }) → records — rows for lists
+ * @prop fetchRecord  async ({ screen, id }) → record — Edit loads the record fresh
+ * @prop onDelete     async ({ id, source, record }) → void
+ * @prop onChange     (values) → void
+ * @prop screens      { id → document } — the screens a list's Edit / New open in a popup
+ * @prop loadScreen   async (id) → document — for screens not in `screens`
  * @prop controls     control registry (default: built-ins)
  */
 export function FactoryScreen(props) {
   const ctrl = useFactoryScreen(props)
-  return <ScreenSample ctrl={ctrl} className={props.className} style={props.style} />
+  return (
+    <ScreenSample
+      ctrl={ctrl}
+      className={props.className}
+      style={props.style}
+      renderPopup={(popup) => (
+        <ScreenModal
+          title={popup.document ? popup.document.name : 'Loading…'}
+          width={popup.document ? popup.document.width : undefined}
+          onClose={ctrl.closeEditor}
+        >
+          {popup.error && <div className="xeplr-factory-invalid" role="alert">{popup.error}</div>}
+          {popup.loading && <div className="xeplr-factory-hint">Loading…</div>}
+          {popup.document && (
+            // The same component, one level down: the edit screen saves itself,
+            // and every save refreshes the list behind the popup.
+            <FactoryScreen
+              key={`${popup.screenId}:${popup.record ? popup.record[ctrl.recordKey] : 'new'}`}
+              document={popup.document}
+              record={popup.record}
+              recordKey={props.recordKey}
+              onSave={ctrl.popupSave}
+              fetchOptions={props.fetchOptions}
+              fetchRecord={props.fetchRecord}
+              fetchRecords={props.fetchRecords}
+              onDelete={props.onDelete}
+              screens={props.screens}
+              loadScreen={props.loadScreen}
+              controls={props.controls}
+            />
+          )}
+        </ScreenModal>
+      )}
+    />
+  )
 }

package/src/remote.js

@@ -0,0 +1,66 @@
+// The browser side of @xeplr/factory: every call FactoryScreen and
+// FactoryBuilder need, as requests to its routes. Records live in REAL tables
+// in the app's database; this only sends and receives.
+//
+//   import { authFetch } from '@xeplr/ui-account'
+//   const factory = createFactoryApi({ fetch: authFetch })
+//   <FactoryScreen document={screen} {...factory.screenProps} />
+//   <FactoryBuilder document={screen} {...factory.builderProps} lockedNames={…} />
+//
+// Responses are xeplr's { code, message, error, dataArray }.
+
+/**
+ * @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 '')
+ */
+export function createFactoryApi({ fetch: doFetch, base = '' } = {}) {
+  if (typeof doFetch !== 'function') throw new Error('createFactoryApi: pass { fetch } — usually authFetch from @xeplr/ui-account')
+
+  async function call(method, path, body) {
+    const res = await doFetch(`${base}/factory${path}`, {
+      method,
+      headers: body === undefined ? undefined : { 'Content-Type': 'application/json' },
+      body: body === undefined ? undefined : JSON.stringify(body)
+    })
+    let json = null
+    try { json = await res.json() } catch (_) { /* not JSON — reported below */ }
+    if (!res.ok) {
+      const err = new Error((json && json.message) || `${method} ${path} failed (${res.status})`)
+      err.status = res.status
+      err.fields = json && json.error && json.error.fields
+      const extra = (json && json.dataArray && json.dataArray[0]) || {}
+      // Publish: columns it would drop, waiting for a yes — and what it keeps.
+      err.confirm = extra.confirm
+      err.keep = extra.keep
+      err.refused = extra.refused
+      if (extra.statements) err.detail = extra.statements.join('\n')
+      throw err
+    }
+    return json ? json.dataArray : []
+  }
+  const one = (rows) => (Array.isArray(rows) ? rows[0] : rows)
+  const enc = encodeURIComponent
+
+  const api = {
+    // screens
+    listScreens: () => call('GET', '/screens'),
+    loadScreen: async (key) => one(await call('GET', `/screens/${enc(key)}`)).document,
+    loadDraft: async (key) => one(await call('GET', `/screens/${enc(key)}?draft=true`)),
+    saveDraft: (doc) => call('PUT', `/screens/${enc(doc.id)}/draft`, { document: doc }),
+    // Changes the screen's table directly. Rejects with err.confirm = [{ column, records }]
+    // when a removed field would drop a column; call again with { confirmDrop: [names] }.
+    publish: async (doc, options) => one(await call('POST', `/screens/${enc(doc.id)}/publish`, { confirmDrop: (options && options.confirmDrop) || [] })),
+    listTables: () => call('GET', '/tables'),
+
+    // records
+    fetchRecords: ({ screen }) => call('GET', `/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 })),
+    onDelete: ({ id, screen }) => call('POST', `/records/${enc(screen)}/delete`, { id }),
+    fetchOptions: ({ table }) => call('GET', `/options/${enc(table)}`)
+  }
+  api.screenProps = { loadScreen: api.loadScreen, onSave: api.onSave, fetchRecords: api.fetchRecords, fetchRecord: api.fetchRecord, onDelete: api.onDelete, fetchOptions: api.fetchOptions }
+  api.builderProps = { onSave: api.saveDraft, onPublish: api.publish, listTables: api.listTables, fetchOptions: api.fetchOptions, fetchRecords: api.fetchRecords }
+  return api
+}

package/src/scaffold.js

@@ -0,0 +1,116 @@
+// THE FILES an entity becomes in an app.
+//
+// Asked for "a form for employees", Claude produces two screens and two
+// pages that show them:
+//
+//   employee-list.screen.json   EmployeeList.jsx   — the list; Edit / New open a popup
+//   employee-edit.screen.json   EditEmployee.jsx   — the add / edit form, also a page on its own
+//   employee.hooks.js                              — the server's hooks for its records (all empty)
+//
+// The pages are thin on purpose: a screen document and the app's data calls,
+// nothing else. Changing what a screen shows is editing its JSON in the
+// designer, never these files.
+//
+// Pure: returns { path → contents }. Writing them is the caller's (the CLI).
+
+import { screensFromSpec, entityNames } from './generate.js'
+
+/**
+ * @param spec  as screensFromSpec
+ * @returns {{ files: Object<string, string>, names, list, edit }}
+ */
+export function scaffoldEntity(spec, controls) {
+  const { list, edit } = screensFromSpec(spec, controls)
+  const names = entityNames(spec.entity, spec.plural)
+  const listJson = `${names.file}-list.screen.json`
+  const editJson = `${names.file}-edit.screen.json`
+
+  const files = {
+    [listJson]: JSON.stringify(list, null, 2) + '\n',
+    [editJson]: JSON.stringify(edit, null, 2) + '\n',
+    [`${names.listComponent}.jsx`]: listPage(names, listJson, editJson, list, edit),
+    [`${names.editComponent}.jsx`]: editPage(names, editJson, edit),
+    [`${names.file}.hooks.js`]: hooksFile(names, edit)
+  }
+  return { files, names, list, edit }
+}
+
+function listPage(n, listJson, editJson, list, edit) {
+  return `import { FactoryScreen } from '@xeplr/ui-factory'
+import listScreen from './${listJson}'
+import editScreen from './${editJson}'
+
+// ${n.pluralTitle} — the saved ${list.source}, with New / Edit / Delete.
+// Edit and New open "${edit.name}" (${edit.id}) in a popup.
+//
+// \`api\` is the app's data calls — the factory never touches a database:
+//   onSave(values, { id, source })  → the saved record, with its id
+//   fetchRecords({ source })        → records
+//   onDelete({ id, source, record })
+//   fetchOptions({ table })         → [{ id, name }] for dropdowns
+export default function ${n.listComponent}({ api }) {
+  return (
+    <FactoryScreen
+      document={listScreen}
+      screens={{ [editScreen.id]: editScreen }}
+      {...api}
+    />
+  )
+}
+`
+}
+
+function hooksFile(n, edit) {
+  return `// Server hooks for ${n.singular} records — screen "${edit.id}" (and "${n.key}_list", which edits in it).
+//
+// Register with @xeplr/factory:
+//   factory.init({ knex, hooks: { ${edit.id}: require('./${n.file}.hooks') } })
+//
+// Each operation has four hooks. Delete the ones you do not need.
+//   before(ctx)       first — save: return new values to replace them (they are then checked
+//                     against the screen's rules); get: narrow ctx.query; any: ctx.reject(message, { field })
+//   after(ctx)        once it succeeded — ctx.id, ctx.result; return a value to replace the result.
+//                     If it throws, the operation still happened (and error is told).
+//   error(ctx, err)   when the operation failed
+//   override(ctx)     does the WHOLE operation instead — no rules, no before / after / error,
+//                     no generic query. What it returns is the response.
+//
+// ctx: op, screenKey, screen, table, id, isNew (save), many (get), input (what the UI sent, read-only),
+//      values (save), previous (save / delete: the row before), result, user, tenant, knex, query (get), reject
+
+module.exports = {
+  save: {
+    // before: async function(ctx) { return ctx.values },
+    // after: async function(ctx) {},
+    // error: async function(ctx, err) {},
+    // override: async function(ctx) { return savedRecord },
+  },
+  get: {
+    // before: async function(ctx) { /* ctx.query.where(...) */ },
+    // after: async function(ctx) { return ctx.result },
+    // error: async function(ctx, err) {},
+    // override: async function(ctx) { return ctx.id ? record : records },
+  },
+  delete: {
+    // before: async function(ctx) {},
+    // after: async function(ctx) {},
+    // error: async function(ctx, err) {},
+    // override: async function(ctx) { return { id: ctx.id } },
+  }
+}
+`
+}
+
+function editPage(n, editJson, edit) {
+  return `import { FactoryScreen } from '@xeplr/ui-factory'
+import editScreen from './${editJson}'
+
+// ${edit.name} — saves itself as it is filled in; there is no submit.
+// Opened in a popup from ${n.listComponent}, or on its own page:
+//   <${n.editComponent} api={api} />                 a new ${n.singular}
+//   <${n.editComponent} api={api} record={row} />    an existing one
+export default function ${n.editComponent}({ api, record }) {
+  return <FactoryScreen document={editScreen} record={record} {...api} />
+}
+`
+}

package/src/tableSchema.js

@@ -0,0 +1,329 @@
+// A FORM IS A REAL TABLE.
+//
+// Records are never stored as JSON: every entity has its own table, and every
+// field of its edit screen is a column of that table, named exactly as the
+// field. `select * from employees` is how you read them, and reporting is plain
+// SQL.
+//
+// This file derives that table from a screen and writes the migration that
+// gets the database there — the first time a CREATE TABLE, after that only what
+// changed. The migrations are ordinary files in the app's migrations folder,
+// written (usually by Claude) and reviewed like any other; nothing here touches
+// a database.
+//
+// Conventions are the xeplr ones (see xeplr-bi 0066_dashboard_groups.sql):
+// varchar(25) ids, quoted camelCase columns, isActive for soft delete, mtId1–4
+// for tenancy, recordCreated/Modified Date/By for audit.
+//
+// ── CHANGES THAT ARE SAFE, AND CHANGES THAT ARE REFUSED ──────────────────
+//   new field                 ADD COLUMN
+//   wider (varchar 80 → 120, varchar → text, integer → numeric)   ALTER TYPE
+//   narrower, or a different type (text → number)   REFUSED — data would be
+//                             lost or rejected; write that migration by hand
+//   field removed             column KEPT, reported as unused — dropping data
+//                             is a deliberate migration, never a side effect
+//   field renamed             seen as a NEW column beside an unused old one, with
+//                             the data left behind — which is why a field's name is
+//                             locked once its table exists (see the builder's
+//                             lockedNames). A real rename is a manual migration.
+
+import { CONTROLS } from './controls.js'
+import { inputNodes } from './document.js'
+
+/** Columns every entity table has, in this order. Fields may not use these names. */
+export const STANDARD_COLUMNS = [
+  { name: 'id', sql: 'varchar(25) PRIMARY KEY' },
+  { name: 'isActive', sql: 'boolean DEFAULT true' },
+  { name: 'mtId1', sql: 'varchar(25)' },
+  { name: 'mtId2', sql: 'varchar(25)' },
+  { name: 'mtId3', sql: 'varchar(25)' },
+  { name: 'mtId4', sql: 'varchar(25)' },
+  { name: 'recordCreatedDate', sql: 'timestamp DEFAULT now()' },
+  { name: 'recordModifiedDate', sql: 'timestamp DEFAULT now()' },
+  { name: 'recordCreatedBy', sql: 'varchar(25)' },
+  { name: 'recordModifiedBy', sql: 'varchar(25)' }
+]
+
+export const RESERVED_COLUMNS = STANDARD_COLUMNS.map((c) => c.name)
+
+/** Postgres truncates identifiers past this — two long fields would collide silently. */
+export const MAX_IDENTIFIER = 63
+
+const TEXT_DEFAULT_LENGTH = 255
+const OPTION_MIN_LENGTH = 50
+
+/**
+ * The column a field is stored in.
+ * @returns {{ name, type: 'varchar'|'text'|'integer'|'numeric'|'date'|'boolean', length?, references?, notNull?, default? }}
+ */
+export function columnForField(node) {
+  const p = node.props || {}
+  const v = p.validation || {}
+  const base = { name: p.name, label: p.label }
+  switch (node.type) {
+    case 'text':
+      return { ...base, type: 'varchar', length: v.maxLength || TEXT_DEFAULT_LENGTH }
+    case 'textarea':
+      return { ...base, type: 'text' }
+    case 'number':
+      return { ...base, type: v.integer ? 'integer' : 'numeric' }
+    case 'date':
+      return { ...base, type: 'date' }
+    case 'checkbox':
+      return { ...base, type: 'boolean', notNull: true, default: 'false' }
+    case 'dropdown': {
+      const data = p.data || {}
+      if (data.source === 'table') {
+        // A real foreign key to the other entity's id.
+        return { ...base, type: 'varchar', length: 25, references: data.table }
+      }
+      const longest = (data.options || []).reduce((m, o) => Math.max(m, String(o.id).length), 0)
+      return { ...base, type: 'varchar', length: Math.max(OPTION_MIN_LENGTH, longest) }
+    }
+    default:
+      return null
+  }
+}
+
+/**
+ * The table an edit screen saves to.
+ * @returns {{ table, columns }} — columns are the fields, in reading order
+ */
+export function tableForScreen(doc, controls = CONTROLS) {
+  if (!doc || !doc.source) throw new Error('The screen has no "source" — which table does it save to?')
+  const columns = inputNodes(doc, controls).map(columnForField).filter(Boolean)
+  if (!columns.length) throw new Error(`Screen "${doc.id}" has no fields, so it defines no table columns — generate the migration from the edit screen`)
+  return { table: doc.source, columns }
+}
+
+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")`)
+  if (col.notNull) parts.push('NOT NULL')
+  if (col.default !== undefined) parts.push(`DEFAULT ${col.default}`)
+  return parts.join(' ')
+}
+
+/** Is changing `from` to `to` safe for data already in the column? */
+export function widening(from, to) {
+  if (from.references || to.references) {
+    if (from.references !== to.references) return { ok: false, reason: `it points at "${from.references || 'no table'}" and would point at "${to.references || 'no table'}"` }
+  }
+  if (from.type === to.type) {
+    if (from.type !== 'varchar') return { ok: true, same: true }
+    if (to.length === from.length) return { ok: true, same: true }
+    if (to.length > from.length) return { ok: true }
+    return { ok: false, reason: `varchar(${from.length}) → varchar(${to.length}) would cut longer values` }
+  }
+  if (from.type === 'varchar' && to.type === 'text') return { ok: true }
+  if (from.type === 'integer' && to.type === 'numeric') return { ok: true }
+  return { ok: false, reason: `${describe(from)} → ${describe(to)} is a different kind of value` }
+}
+
+/**
+ * What it takes to go from the table as it was to the table as the screen now
+ * describes it.
+ * @param before  { table, columns } or null for a new table
+ * @returns {{ create, add, alter, unused, refused, same }}
+ */
+export function diffTables(before, after) {
+  if (before && before.table !== after.table) {
+    return { create: false, add: [], alter: [], unused: [], same: false, refused: [{ column: null, reason: `the screen now saves to "${after.table}" instead of "${before.table}" — moving records to another table is a manual migration` }] }
+  }
+  if (!before) return { create: true, add: after.columns, alter: [], unused: [], refused: [], same: false }
+  const was = Object.fromEntries(before.columns.map((c) => [c.name, c]))
+  const now = Object.fromEntries(after.columns.map((c) => [c.name, c]))
+  const add = []
+  const alter = []
+  const refused = []
+  after.columns.forEach((c) => {
+    const old = was[c.name]
+    if (!old) { add.push(c); return }
+    const w = widening(old, c)
+    if (!w.ok) refused.push({ column: c.name, reason: w.reason })
+    else if (!w.same) alter.push({ from: old, to: c })
+  })
+  const unused = before.columns.filter((c) => !now[c.name])
+  return { create: false, add, alter, unused, refused, same: !add.length && !alter.length && !unused.length && !refused.length }
+}
+
+/**
+ * The migration SQL from one version of an edit screen to the next.
+ * @param previous  the edit screen as last migrated, or null
+ * @param next      the edit screen now
+ * @returns {{ sql, diff, table, empty }} — throws if a change is refused
+ */
+export function migrationFor(previous, next, controls = CONTROLS) {
+  const after = tableForScreen(next, controls)
+  const before = previous ? tableForScreen(previous, controls) : null
+  const diff = diffTables(before, after)
+  if (diff.refused.length) {
+    const e = new Error(`Cannot migrate "${after.table}" safely:\n` + diff.refused.map((r) => `  ${r.column ? `"${r.column}": ` : ''}${r.reason}`).join('\n'))
+    e.refused = diff.refused
+    throw e
+  }
+  if (diff.same || (!diff.create && !diff.add.length && !diff.alter.length)) {
+    return { sql: '', diff, table: after.table, empty: true }
+  }
+
+  const t = after.table
+  const lines = []
+  const header = [
+    `-- ${diff.create ? 'Create' : 'Update'} "${t}" for screen "${next.id}" (${next.name}).`,
+    '--',
+    '-- Written from the screen by @xeplr/ui-factory: one column per field, named'
+  , '-- exactly as the field. Review before applying.'
+  ]
+  if (diff.unused.length) {
+    header.push('--', `-- Kept, no longer on the screen (drop by hand if the data is not needed): ${diff.unused.map((c) => `"${c.name}"`).join(', ')}`)
+  }
+  lines.push(...header, '')
+
+  if (diff.create) {
+    lines.push(...createStatements(after, { annotate: true }))
+  } else {
+    diff.add.forEach((c) => lines.push(...addStatements(t, c, { annotate: true })))
+    diff.alter.forEach(({ from, to }) => lines.push(alterStatement(t, from, to, { annotate: true })))
+  }
+  return { sql: lines.join('\n') + '\n', diff, table: t, empty: false }
+}
+
+// ── statements ───────────────────────────────────────────────────────────
+
+/** CREATE TABLE with the fields and the standard columns, and its indexes. */
+export function createStatements(after, { annotate } = {}) {
+  const t = after.table
+  const cols = [...STANDARD_COLUMNS.slice(0, 1), ...after.columns.map((c) => ({ name: c.name, sql: columnSql(c), label: c.label })), ...STANDARD_COLUMNS.slice(1)]
+  const width = Math.max(...cols.map((c) => c.name.length)) + 2
+  const body = cols.map((c, i) => {
+    const comma = i < cols.length - 1 ? ',' : ''
+    const note = annotate && c.label ? `  -- ${c.label}` : ''
+    return `  ${q(c.name).padEnd(width)} ${c.sql}${comma}${note}`
+  })
+  const out = [`CREATE TABLE IF NOT EXISTS ${q(t)} (\n${body.join('\n')}\n);`]
+  out.push(`CREATE INDEX IF NOT EXISTS ${q(`${t}_mt_index`)} ON ${q(t)} ("mtId1", "mtId2");`)
+  after.columns.filter((c) => c.references).forEach((c) => {
+    out.push(`CREATE INDEX IF NOT EXISTS ${q(`${t}_${c.name}_index`)} ON ${q(t)} (${q(c.name)});`)
+  })
+  return out
+}
+
+export function addStatements(t, c, { annotate } = {}) {
+  const out = [`ALTER TABLE ${q(t)} ADD COLUMN IF NOT EXISTS ${q(c.name)} ${columnSql(c)};${annotate && c.label ? `  -- ${c.label}` : ''}`]
+  if (c.references) out.push(`CREATE INDEX IF NOT EXISTS ${q(`${t}_${c.name}_index`)} ON ${q(t)} (${q(c.name)});`)
+  return out
+}
+
+export function alterStatement(t, from, to, { annotate } = {}) {
+  const type = to.type === 'varchar' ? `varchar(${to.length})` : to.type
+  return `ALTER TABLE ${q(t)} ALTER COLUMN ${q(to.name)} TYPE ${type};${annotate ? `  -- was ${describe(from)}` : ''}`
+}
+
+/** Drops the column and every value in it. Its foreign key and index go with it. */
+export function dropStatement(t, name) {
+  return `ALTER TABLE ${q(t)} DROP COLUMN IF EXISTS ${q(name)};`
+}
+
+// ── publish: apply directly ──────────────────────────────────────────────
+//
+// Publishing a screen changes its table straight away — no migration files.
+// It compares the screen with the table AS IT IS in the database (not with
+// the previous version), so a table changed by hand, or a publish that failed
+// halfway, is still seen for what it is.
+//
+// A REMOVED FIELD DROPS ITS COLUMN AND ITS DATA — only after the person
+// confirms, and never for a column this factory did not create:
+//   managed  names that were fields of a published version of a screen on this
+//            table. A column somebody added by hand is not in it, and is left alone.
+//   inUse    names another published screen on the same table still has —
+//            another company's screen, say. The column is shared; it stays.
+
+/** A column as Postgres describes it → the shape columnForField returns. */
+export function columnFromDatabase(c) {
+  const base = { name: c.name }
+  if (c.references) base.references = c.references
+  switch (c.udtName) {
+    case 'varchar': return { ...base, type: 'varchar', length: c.maxLength }
+    case 'text': return { ...base, type: 'text' }
+    case 'int2':
+    case 'int4': return { ...base, type: 'integer' }
+    case 'numeric': return { ...base, type: 'numeric' }
+    case 'date': return { ...base, type: 'date' }
+    case 'bool': return { ...base, type: 'boolean' }
+    // Anything else (a timestamp, a bigint someone chose) is not a type a field
+    // makes — so any change to it is refused rather than guessed at.
+    default: return { ...base, type: c.udtName }
+  }
+}
+
+/**
+ * What publishing `next` does to its table.
+ *
+ * @param current  { table, columns: [{ name, udtName, maxLength, references }] }
+ *                 as the database describes it, or null when the table does not exist
+ * @param options.managed      names ever published as fields on this table
+ * @param options.inUse        names other published screens on this table still use
+ * @param options.confirmDrop  names the person has confirmed dropping
+ * @returns {{
+ *   table, create,
+ *   add, alter,             what will change
+ *   drop,                   columns to drop: [{ name }]
+ *   unconfirmed,            of those, the ones not yet confirmed — nothing runs until this is empty
+ *   keep,                   columns left in place, with why: [{ name, reason }]
+ *   refused,                changes that cannot be made safely: [{ column, reason }] — nothing runs
+ *   statements              the SQL, in order — empty while anything is refused or unconfirmed
+ * }}
+ */
+export function planTableChange(current, next, options = {}, controls = CONTROLS) {
+  const after = tableForScreen(next, controls)
+  const managed = new Set(options.managed || [])
+  const inUse = new Set(options.inUse || [])
+  const confirmed = new Set(options.confirmDrop || [])
+  const plan = { table: after.table, create: false, add: [], alter: [], drop: [], unconfirmed: [], keep: [], refused: [], statements: [] }
+
+  if (!current) {
+    plan.create = true
+    plan.add = after.columns
+    plan.statements = createStatements(after)
+    return plan
+  }
+
+  const existing = current.columns
+    .filter((c) => !RESERVED_COLUMNS.includes(c.name))
+    .map(columnFromDatabase)
+  const diff = diffTables({ table: after.table, columns: existing }, after)
+  plan.add = diff.add
+  plan.alter = diff.alter
+  plan.refused = diff.refused
+
+  diff.unused.forEach((c) => {
+    if (!managed.has(c.name)) plan.keep.push({ name: c.name, reason: 'not created by a screen — left as it is' })
+    else if (inUse.has(c.name)) plan.keep.push({ name: c.name, reason: 'another published screen on this table still uses it' })
+    else plan.drop.push({ name: c.name })
+  })
+  plan.unconfirmed = plan.drop.filter((d) => !confirmed.has(d.name)).map((d) => d.name)
+
+  if (plan.refused.length || plan.unconfirmed.length) return plan
+  plan.add.forEach((c) => plan.statements.push(...addStatements(after.table, c)))
+  plan.alter.forEach(({ from, to }) => plan.statements.push(alterStatement(after.table, from, to)))
+  plan.drop.forEach((d) => plan.statements.push(dropStatement(after.table, d.name)))
+  return plan
+}
+
+/** Next migration file name in a folder of NNNN_*.sql files. */
+export function nextMigrationName(existingFiles, table, create) {
+  const top = (existingFiles || []).reduce((m, f) => {
+    const n = /^(\d+)_/.exec(f)
+    return n ? Math.max(m, Number(n[1])) : m
+  }, 0)
+  return `${String(top + 1).padStart(4, '0')}_factory_${table}_${create ? 'create' : 'update'}.sql`
+}
+
+function describe(c) {
+  return c.type === 'varchar' ? `varchar(${c.length})` : c.type
+}
+
+function q(identifier) {
+  return `"${String(identifier).replace(/"/g, '""')}"`
+}