@xeplr/ui-factory 1.0.5 → 1.0.7

package/src/generate.js

@@ -23,14 +23,17 @@
 // The result is an ordinary document, checked before it is returned; from
 // there it is edited like any other.
 
-import { CONTROLS } from './controls.js'
-import { createScreen, addControl, MARGIN, GAP, slugify, camelName } from './document.js'
+import { CONTROLS, CHOICE_TYPES } from './controls.js'
+import { createScreen, addControl, MARGIN, GAP, slugify, camelName, stepsOf } from './document.js'
 import { assertValidDocument } from './validateDocument.js'
 
 /** Heights by control, as page fractions (a page is as tall as it is wide). */
 export const SPEC_HEIGHTS = {
-  text: 0.08, number: 0.08, date: 0.08, dropdown: 0.08,
+  text: 0.08, number: 0.08, date: 0.08, datetime: 0.08, dropdown: 0.08,
+  file: 0.1, stepper: 0.09,
   textarea: 0.18,
+  // A group is as tall as its options make it — see heightOf().
+  radio: 0.14, multiselect: 0.18,
   checkbox: 0.05,
   list: 0.42,
   label: { heading: 0.07, subheading: 0.055, text: 0.045 }
@@ -42,7 +45,7 @@ export const SPEC_HEIGHTS = {
  */
 export const ROW_GAP = 0.04
 
-const FIELD_KEYS = ['type', 'label', 'name', 'required', 'placeholder', 'default', 'validation', 'data', 'options', 'table', 'width', 'text', 'variant', 'style']
+const FIELD_KEYS = ['type', 'label', 'name', 'required', 'placeholder', 'default', 'validation', 'data', 'options', 'table', 'layout', 'accept', 'maxSize', 'step', 'steps', 'showNumbers', 'width', 'text', 'variant', 'style']
 const SPEC_KEYS = ['name', 'id', 'source', 'columns', 'heading', 'fields', 'list', 'aspect', 'width', 'style']
 const LIST_KEYS = ['title', 'source', 'columns', 'pageSize', 'actions', 'style']
 
@@ -79,20 +82,48 @@ export function screenFromSpec(spec, controls = CONTROLS) {
   let col = 0
   let rowH = 0
 
+  // A stepper on the screen, and where each of its steps starts: every step is
+  // laid out from just under the bar, so they sit on top of one another rather
+  // than running down a page as long as all of them put together.
+  let stepper = null
+  let stepTop = 0
+  let step = null
+
   const place = (type, props, width) => {
     const h = heightOf(type, props)
-    const isFull = width === 'full' || columns === 1 || type === 'textarea' || type === 'label' || type === 'list'
+    const isFull = width === 'full' || columns === 1 || type === 'textarea' || type === 'label' || type === 'list' || type === 'stepper'
+    let node
     if (isFull) {
       if (col > 0) { y += rowH + ROW_GAP; col = 0; rowH = 0 }
-      ;({ document: doc } = addControl(doc, type, { at: { x: MARGIN, y: round(y) }, size: { w: round(full), h }, props }, controls))
+      ;({ document: doc, node } = addControl(doc, type, { at: { x: MARGIN, y: round(y) }, size: { w: round(full), h }, props, step }, controls))
       y += h + ROW_GAP
-      return
+    } else {
+      const x = MARGIN + col * (colW + GAP)
+      ;({ document: doc, node } = addControl(doc, type, { at: { x: round(x), y: round(y) }, size: { w: colW, h }, props, step }, controls))
+      rowH = Math.max(rowH, h)
+      col++
+      if (col === columns) { y += rowH + ROW_GAP; col = 0; rowH = 0 }
+    }
+    if (type === 'stepper') {
+      stepper = node
+      stepTop = y
+      step = { of: node.id, index: 0 }
     }
-    const x = MARGIN + col * (colW + GAP)
-    ;({ document: doc } = addControl(doc, type, { at: { x: round(x), y: round(y) }, size: { w: colW, h }, props }, controls))
-    rowH = Math.max(rowH, h)
-    col++
-    if (col === columns) { y += rowH + ROW_GAP; col = 0; rowH = 0 }
+    return node
+  }
+
+  /** Move the layout to a step: back to the top, under the bar. */
+  const openStep = (which) => {
+    const steps = stepsOf(stepper)
+    const index = typeof which === 'number' ? which - 1 : steps.findIndex((s) => s.key === which || s.label === which)
+    if (index < 0 || index >= steps.length) {
+      throw new Error(`screenFromSpec: step ${JSON.stringify(which)} is not one of ${steps.map((s) => s.label).join(', ')}`)
+    }
+    if (step && step.index === index) return
+    step = { of: stepper.id, index }
+    y = stepTop
+    col = 0
+    rowH = 0
   }
 
   if (spec.heading !== false) {
@@ -106,6 +137,10 @@ export function screenFromSpec(spec, controls = CONTROLS) {
     const type = field.type || 'text'
     if (!controls[type]) throw new Error(`screenFromSpec: ${at}.type "${type}" is not a control — one of: ${Object.keys(controls).join(', ')}`)
     if (field.width !== undefined && field.width !== 'half' && field.width !== 'full') throw new Error(`screenFromSpec: ${at}.width must be "half" or "full"`)
+    if (field.step !== undefined) {
+      if (!stepper) throw new Error(`screenFromSpec: ${at}.step needs a stepper before it — { "type": "stepper", "steps": [...] }`)
+      openStep(field.step)
+    }
     place(type, propsFromField(type, field, at), field.width)
   })
 
@@ -123,6 +158,18 @@ export function screenFromSpec(spec, controls = CONTROLS) {
 }
 
 function propsFromField(type, field, at) {
+  if (type === 'stepper') {
+    const steps = field.steps
+    if (!Array.isArray(steps) || steps.length < 2) throw new Error(`screenFromSpec: ${at} is a stepper — give it steps: ["Connect", "Transform", …]`)
+    const props = {
+      steps: steps.map((s, i) => (typeof s === 'string'
+        ? { key: slugify(s, '_') || `step_${i + 1}`, label: s }
+        : s))
+    }
+    if (field.showNumbers !== undefined) props.showNumbers = field.showNumbers
+    if (field.style) props.style = field.style
+    return props
+  }
   if (type === 'label') {
     const props = { text: field.text ?? field.label ?? '', variant: field.variant || 'subheading' }
     if (field.style) props.style = field.style
@@ -134,17 +181,23 @@ function propsFromField(type, field, at) {
     if (field[k] !== undefined) props[k] = field[k]
   })
   if (type === 'dropdown' && props.placeholder === undefined) props.placeholder = 'Select…'
-  if (type === 'dropdown') {
-    props.data = dataFromField(field, at)
-    // A dropdown reading another table stores that row's id: name the column
+  if (CHOICE_TYPES.includes(type)) {
+    props.data = dataFromField(field, at, type)
+    if (field.layout !== undefined && type !== 'dropdown') props.layout = field.layout
+    // A field reading another table stores that row's id: name the column
     // for what it holds — "Department" → departmentId, a foreign key.
-    if (props.data.source === 'table' && props.name === undefined) props.name = camelName(field.label) + 'Id'
+    if (props.data.source === 'table' && props.name === undefined && type !== 'multiselect') props.name = camelName(field.label) + 'Id'
+  }
+  else if (field.options || field.table || field.data) throw new Error(`screenFromSpec: ${at} — options/table/data only apply to ${CHOICE_TYPES.join(', ')}`)
+  if (type === 'file') {
+    ;['accept', 'maxSize'].forEach((k) => { if (field[k] !== undefined) props[k] = field[k] })
+  } else if (field.accept !== undefined || field.maxSize !== undefined) {
+    throw new Error(`screenFromSpec: ${at} — accept/maxSize only apply to a file`)
   }
-  else if (field.options || field.table || field.data) throw new Error(`screenFromSpec: ${at} — options/table/data only apply to a dropdown`)
   return props
 }
 
-function dataFromField(field, at) {
+function dataFromField(field, at, type) {
   if (field.data) return field.data
   if (field.table) return { source: 'table', table: field.table }
   if (Array.isArray(field.options)) {
@@ -155,15 +208,26 @@ function dataFromField(field, at) {
         : o))
     }
   }
-  throw new Error(`screenFromSpec: ${at} is a dropdown — give it options: [...] or table: "<name>"`)
+  throw new Error(`screenFromSpec: ${at} is a ${type} — give it options: [...] or table: "<name>"`)
 }
 
 function heightOf(type, props) {
   const h = SPEC_HEIGHTS[type]
   if (type === 'label') return h[props.variant] || h.text
+  // A group of options grows with them: the label, then a line per option
+  // (or one line for all of them, side by side).
+  if (type === 'radio' || type === 'multiselect') {
+    const n = props.data?.source === 'static' ? (props.data.options || []).length : 4
+    const lines = props.layout === 'horizontal' ? 1 : Math.max(n, 1)
+    return round(LABEL_H + lines * OPTION_H)
+  }
   return h || 0.08
 }
 
+/** A field's label, and one option, as page fractions. */
+const LABEL_H = 0.035
+const OPTION_H = 0.03
+
 function unknownKeys(obj, allowed, at) {
   const extra = Object.keys(obj).filter((k) => !allowed.includes(k))
   if (extra.length) throw new Error(`screenFromSpec: ${at} has unknown key(s) ${extra.join(', ')} — allowed: ${allowed.join(', ')}`)

package/src/model.js

@@ -3,14 +3,15 @@
 //
 //   import { screenFromSpec, validateDocument, formSchema } from '@xeplr/ui-factory/model'
 
-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 { CONTROLS, OPTION_ID, OPTION_LABEL, LABEL_VARIANTS, LABEL_PRESETS, LIST_ACTIONS, STYLE_KEYS, SCREEN_STYLE_KEYS, FONT_FAMILIES, LAYOUTS, CHOICE_TYPES, STEP_LIMIT, MULTI_SEPARATOR, FILE_KINDS, MAX_FILE_MB, acceptList, controlGroups, withControls } from './controls.js'
 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
+  inputNodes, readingOrder, contentBottom, camelName, slugify, uniqueFieldName, nextPosition,
+  steppers, stepsOf, stepOf, setNodeStep, nodesForSteps
 } from './document.js'
 export { validateDocument, assertValidDocument } from './validateDocument.js'
-export { formSchema, initialValues, parseInput, validateValues, fieldError, sameId, optionValue, saveState, recordValues, displayValue, listColumns, listSource } from './values.js'
+export { formSchema, initialValues, parseInput, validateValues, fieldError, sameId, optionValue, chooseable, saveState, recordValues, displayValue, fileLabel, toDbValue, fromDbValue, 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'

package/src/remote.js

@@ -43,6 +43,27 @@ export function createFactoryApi({ fetch: doFetch, base = '' } = {}) {
     return res && Array.isArray(res.dataArray) ? res.dataArray : []
   }
 
+  /**
+   * The same call, with a body the browser must describe itself (a FormData's
+   * multipart boundary). Nothing sets Content-Type here — see authFetch.
+   */
+  async function send(method, path, body) {
+    let res
+    try {
+      res = await doFetch(`${base}/factory${path}`, { method, body })
+    } catch (err) {
+      if (err && err.body !== undefined && err.status) throw failure(method, path, err.status, err.body, err.message)
+      throw err
+    }
+    if (res && typeof res.json === 'function' && typeof res.ok === 'boolean') {
+      let json = null
+      try { json = await res.json() } catch (_) { /* not JSON — reported below */ }
+      if (!res.ok) throw failure(method, path, res.status, json)
+      return json ? json.dataArray : []
+    }
+    return res && Array.isArray(res.dataArray) ? res.dataArray : []
+  }
+
   function failure(method, path, status, json, fallback) {
     const err = new Error((json && json.message) || fallback || `${method} ${path} failed (${status})`)
     err.status = status
@@ -77,9 +98,18 @@ export function createFactoryApi({ fetch: doFetch, base = '' } = {}) {
     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)}`)
+    fetchOptions: ({ table }) => call('GET', `/options/${enc(table)}`),
+
+    // A file field's upload. The answer's `path` is what the record stores;
+    // the file itself is read back through the same route, with auth.
+    uploadFile: async (file, { screen, field }) => {
+      const form = new FormData()
+      form.append('file', file)
+      return one(await send('POST', `/files/${enc(screen)}/${enc(field)}`, form))
+    },
+    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 }
+  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 }
   return api
 }

package/src/tableSchema.js

@@ -51,10 +51,11 @@ export const MAX_IDENTIFIER = 63
 
 const TEXT_DEFAULT_LENGTH = 255
 const OPTION_MIN_LENGTH = 50
+const FILE_PATH_LENGTH = 255
 
 /**
  * The column a field is stored in.
- * @returns {{ name, type: 'varchar'|'text'|'integer'|'numeric'|'date'|'boolean', length?, references?, notNull?, default? }}
+ * @returns {{ name, type: 'varchar'|'text'|'integer'|'numeric'|'date'|'timestamp'|'boolean', length?, references?, notNull?, default? }}
  */
 export function columnForField(node) {
   const p = node.props || {}
@@ -69,9 +70,18 @@ export function columnForField(node) {
       return { ...base, type: v.integer ? 'integer' : 'numeric' }
     case 'date':
       return { ...base, type: 'date' }
+    case 'datetime':
+      return { ...base, type: 'timestamp' }
+    case 'file':
+      // The stored file's path, as the upload answered with it.
+      return { ...base, type: 'varchar', length: FILE_PATH_LENGTH }
+    case 'multiselect':
+      // Every chosen id in one text column, separated by commas.
+      return { ...base, type: 'text' }
     case 'checkbox':
       return { ...base, type: 'boolean', notNull: true, default: 'false' }
-    case 'dropdown': {
+    case 'dropdown':
+    case 'radio': {
       const data = p.data || {}
       if (data.source === 'table') {
         // A real foreign key to the other entity's id.
@@ -118,6 +128,8 @@ export function widening(from, to) {
   }
   if (from.type === 'varchar' && to.type === 'text') return { ok: true }
   if (from.type === 'integer' && to.type === 'numeric') return { ok: true }
+  // A date becomes that day at midnight; the other way round would lose the time.
+  if (from.type === 'date' && to.type === 'timestamp') return { ok: true }
   return { ok: false, reason: `${describe(from)} → ${describe(to)} is a different kind of value` }
 }
 
@@ -250,6 +262,8 @@ export function columnFromDatabase(c) {
     case 'int4': return { ...base, type: 'integer' }
     case 'numeric': return { ...base, type: 'numeric' }
     case 'date': return { ...base, type: 'date' }
+    case 'timestamp':
+    case 'timestamptz': return { ...base, type: 'timestamp' }
     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.

package/src/useFactoryBuilder.js

@@ -1,7 +1,8 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import { CONTROLS, controlGroups } from './controls.js'
 import {
-  createScreen, renameScreen, setScreenProperty, addControl as addControlTo, moveNode, setNodeProperty,
+  createScreen, renameScreen, setScreenProperty, addControl as addControlTo, moveNode, setNodeProperty, setNodeStep,
+  steppers, stepsOf, stepOf, nodesForSteps,
   removeNodes
 } from './document.js'
 import { validateDocument } from './validateDocument.js'
@@ -98,17 +99,42 @@ export function useFactoryBuilder({ document: given, name, onSave, onChange, onP
   /** A screen property by path — `source`, `width`, `style.fontSize`. */
   const setScreen = useCallback((path, value) => update((d) => setScreenProperty(d, path, value)), [update])
 
+  // ── steps ─────────────────────────────────────────────────────────────
+  // Which step of each stepper is open on the canvas. Everything dropped while
+  // a step is open belongs to that step, and the canvas shows only that step —
+  // so one screen holds as many little screens as it has steps.
+  const [openSteps, setOpenSteps] = useState({})
+  const stepperNodes = useMemo(() => steppers(doc, controls), [doc, controls])
+  const [building, setBuilding] = useState(null)      // the stepper being built
+  const activeStepper = stepperNodes.find((n) => n.id === building) || stepperNodes[stepperNodes.length - 1] || null
+  const stepAt = useCallback((id) => (Number.isInteger(openSteps[id]) ? openSteps[id] : 0), [openSteps])
+
+  const goToStep = useCallback((id, index) => {
+    setBuilding(id)
+    setOpenSteps((o) => ({ ...o, [id]: index }))
+  }, [])
+
+  /** The step a new control lands on: the one open on the stepper being built. */
+  const dropStep = useCallback(() => (
+    activeStepper ? { of: activeStepper.id, index: stepAt(activeStepper.id) } : null
+  ), [activeStepper, stepAt])
+
+  /** Moves a control to a step, or to none — shown whatever step is open. */
+  const setStep = useCallback((id, step) => update((d) => setNodeStep(d, id, step)), [update])
+
+  const visibleNodes = useMemo(() => nodesForSteps(doc, openSteps, controls), [doc, openSteps, controls])
+
   /** Adds a control and selects it, so its properties are open straight away. */
   const addControl = useCallback((type, at) => {
     let added = null
     update((d) => {
-      const r = addControlTo(d, type, { at }, controls)
+      const r = addControlTo(d, type, { at, step: dropStep() }, controls)
       added = r.node
       return r.document
     })
     if (added) setSelected(new Set([added.id]))
     return added
-  }, [update, controls])
+  }, [update, controls, dropStep])
 
   const moveControl = useCallback((id, patch) => update((d) => moveNode(d, id, patch)), [update])
 
@@ -271,6 +297,17 @@ export function useFactoryBuilder({ document: given, name, onSave, onChange, onP
     setScreen,
     addControl,
     moveControl,
+    steps: {
+      nodes: stepperNodes,
+      building: activeStepper ? activeStepper.id : null,
+      active: stepAt,
+      count: (id) => stepsOf(stepperNodes.find((n) => n.id === id)).length,
+      labels: (id) => stepsOf(stepperNodes.find((n) => n.id === id)),
+      go: goToStep,
+      of: stepOf,
+      set: setStep
+    },
+    visibleNodes,
     setProperty,
     removeSelected,
     duplicateSelected,

package/src/useFactoryScreen.js

@@ -1,6 +1,6 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
-import { CONTROLS } from './controls.js'
-import { inputNodes } from './document.js'
+import { CONTROLS, CHOICE_TYPES } from './controls.js'
+import { inputNodes, nodesForSteps, steppers, stepsOf, stepOf } from './document.js'
 import { validateDocument } from './validateDocument.js'
 import { initialValues, parseInput, saveState, fieldError, optionValue, recordValues, listSource } from './values.js'
 import { hookMethod } from './hooks.js'
@@ -19,6 +19,7 @@ import { hookMethod } from './hooks.js'
 //   fetchRecords({ source, screen, node })             → rows, for a list
 //   onDelete({ id, source, screen, record })
 //   fetchOptions({ table, node })              → [{ id, name }], for a table dropdown
+//   uploadFile(file, { screen, field, node })  → { path } — a file field's upload
 //
 // ── LIST → EDIT IN A POPUP ───────────────────────────────────────────────
 // A list whose `editScreen` names another screen opens that screen in a popup
@@ -34,6 +35,8 @@ export const AUTOSAVE_DELAY = 700
  * @param recordKey     the id field on a record (default 'id')
  * @param onSave        async (values, { id, source, document }) → saved record | void
  * @param fetchOptions  async ({ table, node }) → [{ id, name }]
+ * @param uploadFile    async (file, { screen, field, node }) → { path } — what a file field saves
+ * @param fileUrl       (path) → the address an attached file is read back from
  * @param fetchRecords  async ({ source, node }) → records, for lists
  * @param onDelete      async ({ id, source, record }) → void
  * @param onChange      (values) → void — every change, before any save
@@ -45,7 +48,7 @@ export const AUTOSAVE_DELAY = 700
  * @param hooks         a FactoryHooks (or an object with some of its methods) — get / save / delete / actions
  */
 export function useFactoryScreen({
-  document: doc, record, recordKey = 'id', onSave, fetchOptions, fetchRecords, fetchRecord, onDelete, onChange, screens, loadScreen, hooks,
+  document: doc, record, recordKey = 'id', onSave, fetchOptions, fetchRecords, fetchRecord, onDelete, onChange, screens, loadScreen, hooks, uploadFile, fileUrl,
   autosaveDelay = AUTOSAVE_DELAY, controls = CONTROLS
 } = {}) {
   const check = useMemo(() => validateDocument(doc, controls), [doc, controls])
@@ -116,7 +119,7 @@ export function useFactoryScreen({
   const fetchOptionsRef = useRef(fetchOptions); fetchOptionsRef.current = fetchOptions
   useEffect(() => {
     let cancelled = false
-    const tableNodes = optionNodes.filter((n) => n.type === 'dropdown' && n.props.data?.source === 'table')
+    const tableNodes = optionNodes.filter((n) => CHOICE_TYPES.includes(n.type) && n.props.data?.source === 'table')
     if (!tableNodes.length) { setOptions({}); return undefined }
     setOptions(Object.fromEntries(tableNodes.map((n) => [n.id, { loading: true, items: [], error: null }])))
     const byTable = new Map()
@@ -141,6 +144,54 @@ export function useFactoryScreen({
     return () => { cancelled = true }
   }, [optionNodes])
 
+  // ── steps ─────────────────────────────────────────────────────────────
+  // A stepper shows one step at a time. Which step each is open at lives here;
+  // the fields of the steps not showing are still filled in, still checked and
+  // still saved — a step is what the person sees, not a separate form.
+  const [openSteps, setOpenSteps] = useState({})
+  const stepperNodes = useMemo(() => (check.ok ? steppers(doc, controls) : []), [check.ok, doc, controls])
+  const visibleNodes = useMemo(() => (check.ok ? nodesForSteps(doc, openSteps, controls) : []), [check.ok, doc, openSteps, controls])
+
+  // A screen whose steps changed under it (a field moved to another step, a
+  // step removed) must not stay open at a step that is gone.
+  useEffect(() => {
+    setOpenSteps((open) => {
+      let changed = false
+      const next = {}
+      stepperNodes.forEach((n) => {
+        const count = stepsOf(n).length
+        const at = Number.isInteger(open[n.id]) ? open[n.id] : 0
+        next[n.id] = Math.min(Math.max(at, 0), Math.max(count - 1, 0))
+        if (next[n.id] !== open[n.id]) changed = true
+      })
+      return changed || Object.keys(next).length !== Object.keys(open).length ? next : open
+    })
+  }, [stepperNodes])
+
+  const stepControl = useMemo(() => {
+    const at = (id) => (Number.isInteger(openSteps[id]) ? openSteps[id] : 0)
+    return {
+      nodes: stepperNodes,
+      active: at,
+      count: (id) => stepsOf(stepperNodes.find((n) => n.id === id)).length,
+      go: (id, index) => setOpenSteps((o) => ({ ...o, [id]: index })),
+      /** The fields on this step, so Next can hold at a step that is not filled in. */
+      fieldsOn: (id, index) => inputNodes(doc, controls).filter((n) => {
+        const step = stepOf(n)
+        return step && step.of === id && step.index === index
+      })
+    }
+  }, [stepperNodes, openSteps, doc, controls])
+
+  // ── a file field's upload ─────────────────────────────────────────────
+  const uploadRef = useRef(uploadFile); uploadRef.current = uploadFile
+  const upload = useCallback(async (file, node) => {
+    if (!uploadRef.current) throw new Error('No uploadFile was provided, so a file cannot be attached')
+    const out = await uploadRef.current(file, { screen: doc.id, field: node.props.name, node })
+    if (!out || !out.path) throw new Error('The upload did not answer with the stored file')
+    return out
+  }, [doc.id])
+
   const optionsFor = useCallback((node) => {
     if (node.props.data?.source === 'static') return { loading: false, items: node.props.data.options, error: null }
     return options[node.id] || { loading: false, items: [], error: null }
@@ -229,7 +280,8 @@ export function useFactoryScreen({
   const onChangeRef = useRef(onChange); onChangeRef.current = onChange
   const setValue = useCallback((node, raw) => {
     let value = parseInput(node, raw)
-    if (node.type === 'dropdown' && value !== undefined) value = optionValue(optionsFor(node).items, value)
+    if ((node.type === 'dropdown' || node.type === 'radio') && value !== undefined) value = optionValue(optionsFor(node).items, value)
+    if (node.type === 'multiselect' && Array.isArray(value)) value = value.map((v) => optionValue(optionsFor(node).items, v))
     const name = node.props.name
     const next = { ...live.current.values }
     if (value === undefined) delete next[name]
@@ -412,6 +464,10 @@ export function useFactoryScreen({
     setValue,
     touch,
     optionsFor,
+    steps: stepControl,
+    visibleNodes,
+    upload,
+    fileUrl,
     flush,
     saveNow: runSave,
     openRecord,

package/src/validateDocument.js

@@ -10,7 +10,7 @@
 // Loud by design: a screen that half-renders — a dropdown with no options, two
 // fields writing the same key — looks like a data problem to whoever uses it.
 
-import { CONTROLS, LABEL_VARIANTS, LIST_ACTIONS, STYLE_KEYS, SCREEN_STYLE_KEYS } from './controls.js'
+import { CONTROLS, LABEL_VARIANTS, LIST_ACTIONS, STYLE_KEYS, SCREEN_STYLE_KEYS, LAYOUTS, MULTI_SEPARATOR, MAX_FILE_MB, STEP_LIMIT, acceptList } from './controls.js'
 import { DOCUMENT_KIND, DOCUMENT_VERSION } from './document.js'
 import { RESERVED_COLUMNS, MAX_IDENTIFIER } from './tableSchema.js'
 
@@ -93,7 +93,15 @@ export function validateDocument(doc, controls = CONTROLS) {
     }
 
     checkStyle(props.style, def.styles || [], `${at}.props.style`, err, `"${node.type}"`)
-    if (node.type === 'dropdown') checkDataSource(props.data, `${at}.props.data`, err)
+    if (node.type === 'dropdown' || node.type === 'radio' || node.type === 'multiselect') {
+      checkDataSource(props.data, `${at}.props.data`, err, node.type === 'multiselect')
+    }
+    if (node.type === 'radio' || node.type === 'multiselect') {
+      if (props.layout !== undefined && !LAYOUTS.includes(props.layout)) err(`${at}.props.layout`, `must be one of: ${LAYOUTS.join(', ')}`)
+    }
+    if (node.type === 'file') checkFile(props, at, err)
+    if (node.type === 'stepper') checkSteps(props, at, err)
+    checkStep(node, doc, at, err)
     if (node.type === 'list') checkList(props, doc, at, err)
     if (node.type === 'label') {
       if (typeof props.text !== 'string') err(`${at}.props.text`, 'must be a string')
@@ -130,16 +138,86 @@ function checkGeometry(node, at, err) {
 function checkDefault(node, def, at, err) {
   const v = node.props.default
   if (v === undefined) return
+  const isDatetime = node.type === 'datetime'
   const ok = {
     string: () => typeof v === 'string',
     number: () => typeof v === 'number' && Number.isFinite(v),
     boolean: () => typeof v === 'boolean',
-    date: () => typeof v === 'string' && ISO_DATE.test(v)
+    array: () => Array.isArray(v),
+    date: () => typeof v === 'string' && (isDatetime ? ISO_DATETIME.test(v) : ISO_DATE.test(v))
   }[def.valueType]
-  if (ok && !ok()) err(`${at}.props.default`, `must be a ${def.valueType === 'date' ? 'date as "YYYY-MM-DD"' : def.valueType}`)
+  if (ok && !ok()) err(`${at}.props.default`, `must be ${dateWord(def.valueType, isDatetime)}`)
+}
+
+function dateWord(valueType, isDatetime) {
+  if (valueType === 'date') return isDatetime ? 'a date and time as "YYYY-MM-DDTHH:MM"' : 'a date as "YYYY-MM-DD"'
+  if (valueType === 'array') return 'an array'
+  return `a ${valueType}`
 }
 
 const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/
+const ISO_DATETIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2})?$/
+
+/**
+ * A stepper's steps: at least two, each with a key of its own, so a control can
+ * be tied to one and stay tied to it when the others are renamed.
+ */
+function checkSteps(props, at, err) {
+  const steps = props.steps
+  if (!Array.isArray(steps)) { err(`${at}.props.steps`, 'must be an array of { key, label }'); return }
+  if (steps.length < 2) err(`${at}.props.steps`, 'needs at least two steps — one step is not a journey')
+  if (steps.length > STEP_LIMIT) err(`${at}.props.steps`, `has ${steps.length} steps — at most ${STEP_LIMIT}`)
+  const seen = new Set()
+  steps.forEach((s, j) => {
+    const p = `${at}.props.steps[${j}]`
+    if (!s || typeof s !== 'object') { err(p, 'must be { key, label }'); return }
+    if (!nonEmptyString(s.key)) err(`${p}.key`, 'must be a non-empty string — what the controls on this step point at')
+    else if (seen.has(s.key)) err(`${p}.key`, `"${s.key}" appears twice`)
+    else seen.add(s.key)
+    if (!nonEmptyString(s.label)) err(`${p}.label`, 'must be a non-empty string — what the person reads')
+    const extra = Object.keys(s).filter((k) => k !== 'key' && k !== 'label')
+    if (extra.length) err(p, `only "key" and "label" are used — remove: ${extra.join(', ')}`)
+  })
+  if (props.showNumbers !== undefined && typeof props.showNumbers !== 'boolean') err(`${at}.props.showNumbers`, 'must be true or false')
+}
+
+/** A node's `step`: a stepper that exists, and one of its steps. */
+function checkStep(node, doc, at, err) {
+  if (node.step === undefined) return
+  const step = node.step
+  if (!step || typeof step !== 'object' || Array.isArray(step)) { err(`${at}.step`, 'must be { of, index } — the stepper, and which step'); return }
+  const extra = Object.keys(step).filter((k) => k !== 'of' && k !== 'index')
+  if (extra.length) err(`${at}.step`, `only "of" and "index" are used — remove: ${extra.join(', ')}`)
+  if (!nonEmptyString(step.of)) { err(`${at}.step.of`, 'must be the id of a stepper on this screen'); return }
+  if (step.of === node.id) { err(`${at}.step.of`, 'a stepper cannot be a step of itself'); return }
+  const owner = (doc.nodes || []).find((n) => n && n.id === step.of)
+  if (!owner || owner.type !== 'stepper') { err(`${at}.step.of`, `"${step.of}" is not a stepper on this screen`); return }
+  const count = Array.isArray(owner.props?.steps) ? owner.props.steps.length : 0
+  if (!Number.isInteger(step.index) || step.index < 0 || step.index >= count) {
+    err(`${at}.step.index`, `must be a step of "${step.of}" — it has ${count}`)
+  }
+}
+
+/** A file field: which extensions it takes, and how big a file may be. */
+function checkFile(props, at, err) {
+  if (props.accept !== undefined) {
+    if (typeof props.accept !== 'string') err(`${at}.props.accept`, 'must be a string of extensions, e.g. ".pdf,.docx"')
+    else {
+      const list = acceptList(props.accept)
+      if (!list.length) err(`${at}.props.accept`, 'names no extension — ".pdf,.docx", or leave it out for any file')
+      list.forEach((x) => {
+        if (!EXTENSION.test(x)) err(`${at}.props.accept`, `"${x}" is not an extension — letters and digits after a dot, e.g. ".xlsx"`)
+      })
+    }
+  }
+  if (props.maxSize !== undefined) {
+    if (!(Number.isFinite(props.maxSize) && props.maxSize > 0 && props.maxSize <= MAX_FILE_MB)) {
+      err(`${at}.props.maxSize`, `must be a number of megabytes from 1 to ${MAX_FILE_MB}`)
+    }
+  }
+}
+
+const EXTENSION = /^\.[a-z0-9]{1,12}$/
 
 function checkValidation(node, def, at, err) {
   const v = node.props.validation
@@ -161,14 +239,18 @@ function checkValidation(node, def, at, err) {
     } else if (key === 'pattern') {
       try { new RegExp(val) } catch (_) { err(path, `"${val}" is not a valid regular expression`) }
       if (typeof val !== 'string') err(path, 'must be a string')
+    } else if (key === 'minItems' || key === 'maxItems') {
+      if (!(Number.isInteger(val) && val >= 0)) err(path, 'must be a whole number, 0 or more')
     } else if (key === 'patternMessage') {
       if (typeof val !== 'string') err(path, 'must be a string')
     } else if (def.valueType === 'number') {
       if (!(typeof val === 'number' && Number.isFinite(val))) err(path, 'must be a number')
     } else if (def.valueType === 'date') {
-      if (!(typeof val === 'string' && ISO_DATE.test(val))) err(path, 'must be a date as "YYYY-MM-DD"')
+      const re = node.type === 'datetime' ? ISO_DATETIME : ISO_DATE
+      if (!(typeof val === 'string' && re.test(val))) err(path, `must be ${dateWord('date', node.type === 'datetime')}`)
     }
   })
+  if (v.minItems != null && v.maxItems != null && v.minItems > v.maxItems) err(`${at}.props.validation`, 'minItems is greater than maxItems — nothing could pass')
   if (v.minLength != null && v.maxLength != null && v.minLength > v.maxLength) err(`${at}.props.validation`, 'minLength is greater than maxLength — nothing could pass')
   if (typeof v.min === 'number' && typeof v.max === 'number' && v.min > v.max) err(`${at}.props.validation`, 'min is greater than max — nothing could pass')
   if (typeof v.min === 'string' && typeof v.max === 'string' && v.min > v.max) err(`${at}.props.validation`, 'min is after max — no date could pass')
@@ -178,7 +260,7 @@ function checkValidation(node, def, at, err) {
  * A dropdown's options: typed in, or read from a table. Either way each option
  * is { id, name } — the id is what is saved, the name is what is shown.
  */
-function checkDataSource(data, at, err) {
+function checkDataSource(data, at, err, multi) {
   if (!data || typeof data !== 'object') {
     err(at, 'is required — { "source": "static", "options": [{ "id", "name" }] } or { "source": "table", "table": "<name>" }')
     return
@@ -190,6 +272,7 @@ function checkDataSource(data, at, err) {
       const p = `${at}.options[${j}]`
       if (!o || typeof o !== 'object') { err(p, 'must be { id, name }'); return }
       if (!(typeof o.id === 'string' || typeof o.id === 'number') || o.id === '') err(`${p}.id`, 'must be a non-empty string or a number')
+      else if (multi && String(o.id).includes(MULTI_SEPARATOR)) err(`${p}.id`, `"${o.id}" contains "${MULTI_SEPARATOR}" — several choices are stored in one column, separated by it`)
       else if (seen.has(o.id)) err(`${p}.id`, `"${o.id}" appears twice`)
       else seen.add(o.id)
       if (!nonEmptyString(o.name)) err(`${p}.name`, 'must be a non-empty string — what the user sees')