@xeplr/ui-factory 1.0.6 → 1.0.8

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')

package/src/values.js

@@ -11,7 +11,7 @@
 // them. validateValues() below applies the same rules in the browser, with
 // messages written for the person filling the form in rather than for a log.
 
-import { CONTROLS } from './controls.js'
+import { CONTROLS, MULTI_SEPARATOR } from './controls.js'
 import { inputNodes } from './document.js'
 
 /** schema-handler field schema for the screen's inputs, in reading order. */
@@ -24,7 +24,9 @@ export function formSchema(doc, controls = CONTROLS) {
     if (p.label) field.description = p.label
     if (p.required) field.required = true
     if (p.default !== undefined) field.default = p.default
-    if (node.type === 'dropdown' && p.data?.source === 'static') {
+    // A multi-select's value is an array, so schema-handler's `options` (which
+    // compares one value) cannot check it — chooseable(node) does, on both sides.
+    if ((node.type === 'dropdown' || node.type === 'radio') && p.data?.source === 'static') {
       field.options = p.data.options.map((o) => o.id)
     }
     const v = p.validation && { ...p.validation }
@@ -44,6 +46,7 @@ export function initialValues(doc, provided = {}, controls = CONTROLS) {
     if (provided[name] !== undefined) out[name] = provided[name]
     else if (node.props.default !== undefined) out[name] = node.props.default
     else if (node.type === 'checkbox') out[name] = false
+    else if (node.type === 'multiselect') out[name] = []
   })
   return out
 }
@@ -55,12 +58,13 @@ export function initialValues(doc, provided = {}, controls = CONTROLS) {
  */
 export function parseInput(node, raw) {
   if (node.type === 'checkbox') return Boolean(raw)
+  if (node.type === 'multiselect') return Array.isArray(raw) ? raw : fromDbValue(node, raw) || []
   if (raw === undefined || raw === null || raw === '') return undefined
   if (node.type === 'number') {
     const n = typeof raw === 'number' ? raw : Number(String(raw).trim())
     return Number.isFinite(n) ? n : raw   // left as typed; validation says why
   }
-  if (node.type === 'dropdown') return raw
+  if (node.type === 'dropdown' || node.type === 'radio') return raw
   return String(raw)
 }
 
@@ -90,6 +94,15 @@ export function fieldError(node, value, loadedOptions) {
   if (node.type === 'checkbox') {
     return p.required && value !== true ? `${label} must be ticked` : null
   }
+  if (node.type === 'multiselect') {
+    const chosen = Array.isArray(value) ? value : []
+    if (!chosen.length) return p.required ? `${label} is required` : null
+    if (v.minItems != null && chosen.length < v.minItems) return `${label}: choose at least ${v.minItems}`
+    if (v.maxItems != null && chosen.length > v.maxItems) return `${label}: choose at most ${v.maxItems}`
+    const allowed = chooseable(node, loadedOptions)
+    if (allowed && chosen.some((c) => !allowed.some((o) => sameId(o.id, c)))) return `${label} has a choice that is no longer offered`
+    return null
+  }
   if (value === undefined || value === null || value === '') {
     return p.required ? `${label} is required` : null
   }
@@ -119,8 +132,18 @@ export function fieldError(node, value, loadedOptions) {
       if (v.max && day > v.max) return `${label} must be on or before ${v.max}`
       return null
     }
-    case 'dropdown': {
-      const opts = p.data?.source === 'static' ? p.data.options : loadedOptions
+    case 'datetime': {
+      if (typeof value !== 'string' || Number.isNaN(Date.parse(value))) return `${label} must be a date and time`
+      // ISO strings compare correctly as text, and comparing text keeps a
+      // timezone from shifting the moment that was typed in.
+      const at = value.slice(0, 16)
+      if (v.min && at < v.min.slice(0, 16)) return `${label} must be at or after ${v.min.replace('T', ' ')}`
+      if (v.max && at > v.max.slice(0, 16)) return `${label} must be at or before ${v.max.replace('T', ' ')}`
+      return null
+    }
+    case 'dropdown':
+    case 'radio': {
+      const opts = chooseable(node, loadedOptions)
       if (Array.isArray(opts) && !opts.some((o) => sameId(o.id, value))) return `${label} must be one of the options`
       return null
     }
@@ -129,6 +152,13 @@ export function fieldError(node, value, loadedOptions) {
   }
 }
 
+/** The options a choice field offers: its own list, or the loaded rows. */
+export function chooseable(node, loadedOptions) {
+  const data = node.props.data || {}
+  const opts = data.source === 'static' ? data.options : loadedOptions
+  return Array.isArray(opts) ? opts : null
+}
+
 /**
  * <select> hands back a string, while a table's ids may be numbers. The id is
  * matched loosely and then saved in the OPTION's own type — see optionValue.
@@ -176,8 +206,9 @@ export function recordValues(doc, record, controls = CONTROLS) {
   inputNodes(doc, controls).forEach((node) => {
     const name = node.props.name
     const v = record ? record[name] : undefined
-    if (v !== undefined && v !== null) out[name] = node.type === 'date' && typeof v === 'string' ? v.slice(0, 10) : v
+    if (v !== undefined && v !== null) out[name] = fromDbValue(node, v)
     else if (node.type === 'checkbox') out[name] = false
+    else if (node.type === 'multiselect') out[name] = []
   })
   return out
 }
@@ -200,10 +231,58 @@ export function displayValue(node, value, options) {
   if (value === undefined || value === null || value === '') return ''
   if (!node) return typeof value === 'object' ? JSON.stringify(value) : value
   if (node.type === 'checkbox') return value ? 'Yes' : 'No'
-  if (node.type === 'dropdown') {
-    const opts = node.props.data?.source === 'static' ? node.props.data.options : options
-    const hit = (opts || []).find((o) => sameId(o.id, value))
-    return hit ? hit.name : String(value)
+  if (node.type === 'file') return fileLabel(value)
+  if (node.type === 'datetime') return String(value).replace('T', ' ').slice(0, 16)
+  if (node.type === 'dropdown' || node.type === 'radio') return optionName(node, value, options)
+  if (node.type === 'multiselect') {
+    return (fromDbValue(node, value) || []).map((v) => optionName(node, v, options)).join(', ')
+  }
+  return value
+}
+
+function optionName(node, value, options) {
+  const opts = node.props.data?.source === 'static' ? node.props.data.options : options
+  const hit = (opts || []).find((o) => sameId(o.id, value))
+  return hit ? hit.name : String(value)
+}
+
+/** The name at the end of a stored file path, without the id that keeps it apart. */
+export function fileLabel(path) {
+  const s = String(path)
+  const cut = s.slice(s.lastIndexOf('/') + 1)
+  const sep = cut.indexOf('__')
+  return sep === -1 ? cut : cut.slice(sep + 2)
+}
+
+// ── the database boundary ────────────────────────────────────────────────
+// Two types do not go into their column as they are read: a multi-select is
+// several ids in one text column, and a date-and-time comes back as the
+// database wrote it. Both sides of the wire use these, so the conversion is
+// written once.
+
+/** A screen value → what its column stores. */
+export function toDbValue(node, value) {
+  if (value === undefined || value === null) return value
+  if (node.type === 'multiselect') {
+    const list = Array.isArray(value) ? value : [value]
+    return list.length ? list.map((v) => String(v)).join(MULTI_SEPARATOR) : null
+  }
+  return value
+}
+
+/** What a column holds → the screen's value. */
+export function fromDbValue(node, value) {
+  if (value === undefined || value === null) return value
+  if (node.type === 'multiselect') {
+    if (Array.isArray(value)) return value
+    const s = String(value)
+    return s === '' ? [] : s.split(MULTI_SEPARATOR).filter((x) => x !== '')
+  }
+  if (node.type === 'date') return typeof value === 'string' ? value.slice(0, 10) : value
+  if (node.type === 'datetime') {
+    // "2026-09-16 14:30:00" or an ISO string → what <input type="datetime-local"> shows.
+    const s = value instanceof Date ? value.toISOString() : String(value)
+    return s.replace(' ', 'T').slice(0, 16)
   }
   return value
 }