@xeplr/ui-factory 1.0.1 → 1.0.2

package/src/useFactoryScreen.js

@@ -2,50 +2,91 @@ import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import { CONTROLS } from './controls.js'
 import { inputNodes } from './document.js'
 import { validateDocument } from './validateDocument.js'
-import { initialValues, parseInput, validateValues, fieldError, optionValue } from './values.js'
+import { initialValues, parseInput, saveState, fieldError, optionValue, recordValues, listSource } from './values.js'
 
-// A saved screen, running: its values, its dropdown options, validation and
-// submit. No JSX — designs/ScreenSample.jsx draws it.
+// A saved screen, running. No JSX — designs/ScreenSample.jsx draws it.
 //
-// The DATABASE IS THE HOST'S. A dropdown reading a table asks the host for its
-// rows — `fetchOptions({ table })` → [{ id, name }] — and a submit hands the
-// values to `onSubmit`. Nothing here knows where either goes.
+// ── NO SUBMIT ────────────────────────────────────────────────────────────
+// The screen saves ITSELF, in the background, a moment after the person stops
+// changing something — once what is entered is acceptable. There is no button
+// to press and no page to post. The first save of a new record creates it
+// (the host hands back its id); every save after that updates the same record.
+//
+// ── THE DATABASE IS THE HOST'S ───────────────────────────────────────────
+// Everything that reads or writes data is a call the host supplies:
+//   onSave(values, { id, source, screen, document })   → the saved record (with its id)
+//   fetchRecords({ source, screen, node })             → rows, for a list
+//   onDelete({ id, source, screen, record })
+//   fetchOptions({ table, node })              → [{ id, name }], for a table dropdown
+//
+// ── LIST → EDIT IN A POPUP ───────────────────────────────────────────────
+// A list whose `editScreen` names another screen opens that screen in a popup
+// for Edit and New. The screen comes from `screens` ({ id → document }) or the
+// host's `loadScreen(id)`. The list refreshes as the popup saves.
+
+/** Quiet time after the last change before a save goes out. */
+export const AUTOSAVE_DELAY = 700
 
 /**
  * @param document      a valid screen document
- * @param fetchOptions  async ({ table, node }) → [{ id, name }]  — for table dropdowns
- * @param onSubmit      async (values, { document }) → void
- * @param values        initial values, e.g. the record being edited
+ * @param record        the record to open, e.g. { id: 7, firstName: 'Ada' } — omit for a new one
+ * @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 fetchRecords  async ({ source, node }) → records, for lists
+ * @param onDelete      async ({ id, source, record }) → void
+ * @param onChange      (values) → void — every change, before any save
+ * @param screens       { id → document } — screens a list's Edit / New can open
+ * @param loadScreen    async (id) → document — for screens not in `screens`
+ * @param autosaveDelay ms (default 700)
  * @param controls      the control registry (default: the built-ins)
  */
-export function useFactoryScreen({ document: doc, fetchOptions, onSubmit, values: provided, controls = CONTROLS } = {}) {
+export function useFactoryScreen({
+  document: doc, record, recordKey = 'id', onSave, fetchOptions, fetchRecords, onDelete, onChange, screens, loadScreen,
+  autosaveDelay = AUTOSAVE_DELAY, controls = CONTROLS
+} = {}) {
   const check = useMemo(() => validateDocument(doc, controls), [doc, controls])
   const inputs = useMemo(() => (check.ok ? inputNodes(doc, controls) : []), [doc, controls, check.ok])
 
-  const [values, setValues] = useState(() => (check.ok ? initialValues(doc, provided, controls) : {}))
-  const [errors, setErrors] = useState({})
-  const [submitted, setSubmitted] = useState(false)
-  const [submitting, setSubmitting] = useState(false)
-  const [submitError, setSubmitError] = useState(null)
+  // A LIST SCREEN has no fields of its own; what its columns mean — that
+  // `department` is a dropdown whose 2 reads "Finance" — lives on the screen it
+  // edits in. Those fields are borrowed for display, and their table options
+  // loaded alongside this screen's own.
+  const fieldsFor = useCallback((node) => {
+    if (inputs.length || !node || !node.props.editScreen) return inputs
+    const editDoc = screens && screens[node.props.editScreen]
+    return editDoc && validateDocument(editDoc, controls).ok ? inputNodes(editDoc, controls) : []
+  }, [inputs, screens, controls])
+  const optionNodes = useMemo(() => {
+    if (!check.ok) return []
+    const borrowed = doc.nodes.filter((n) => n.type === 'list').flatMap((n) => (inputs.length ? [] : fieldsFor(n)))
+    return [...inputs, ...borrowed]
+  }, [check.ok, doc, inputs, fieldsFor])
+  const source = check.ok ? doc.source || null : null
 
-  // A different document or record starts the form over.
-  const providedRef = useRef(provided); providedRef.current = provided
-  const firstRun = useRef(true)
-  useEffect(() => {
-    if (firstRun.current) { firstRun.current = false; return }
-    if (!check.ok) return
-    setValues(initialValues(doc, providedRef.current, controls))
-    setErrors({})
-    setSubmitted(false)
-    setSubmitError(null)
-  }, [doc, provided, controls, check.ok])
+  const startValues = useCallback(
+    (rec) => (rec ? { ...initialValues(doc, {}, controls), ...recordValues(doc, rec, controls) } : initialValues(doc, {}, controls)),
+    [doc, controls]
+  )
+
+  const [values, setValues] = useState(() => (check.ok ? startValues(record) : {}))
+  const [recordId, setRecordId] = useState(() => (record ? record[recordKey] ?? null : null))
+  const [touched, setTouched] = useState(() => new Set())
+  const [status, setStatus] = useState('idle')    // idle | pending | saving | saved | incomplete | invalid | error
+  const [saveError, setSaveError] = useState(null)
+  const [savedAt, setSavedAt] = useState(null)
+  const [listVersion, setListVersion] = useState(0)
+
+  // Latest of everything a delayed save needs, read at the moment it runs.
+  const live = useRef({})
+  live.current = { doc, values, recordId, touched, source, onSave, controls, recordKey }
 
   // ── options for table dropdowns, fetched once per table ───────────────
   const [options, setOptions] = useState({})   // node id → { loading, items, error }
-  const fetchRef = useRef(fetchOptions); fetchRef.current = fetchOptions
+  const fetchOptionsRef = useRef(fetchOptions); fetchOptionsRef.current = fetchOptions
   useEffect(() => {
     let cancelled = false
-    const tableNodes = inputs.filter((n) => n.type === 'dropdown' && n.props.data?.source === 'table')
+    const tableNodes = optionNodes.filter((n) => n.type === 'dropdown' && 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()
@@ -55,8 +96,8 @@ export function useFactoryScreen({ document: doc, fetchOptions, onSubmit, values
       byTable.get(t).push(n)
     })
     byTable.forEach((nodes, table) => {
-      const run = fetchRef.current
-        ? Promise.resolve().then(() => fetchRef.current({ table, node: nodes[0] }))
+      const run = fetchOptionsRef.current
+        ? Promise.resolve().then(() => fetchOptionsRef.current({ table, node: nodes[0] }))
         : Promise.reject(new Error(`No fetchOptions was provided to read "${table}"`))
       run
         .then((rows) => {
@@ -68,9 +109,8 @@ export function useFactoryScreen({ document: doc, fetchOptions, onSubmit, values
         })
     })
     return () => { cancelled = true }
-  }, [inputs])
+  }, [optionNodes])
 
-  /** The options a dropdown shows, whichever source they come from. */
   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 }
@@ -81,69 +121,216 @@ export function useFactoryScreen({ document: doc, fetchOptions, onSubmit, values
     Object.entries(options).forEach(([id, o]) => { if (!o.loading && !o.error) map[id] = o.items })
     return map
   }, [options])
+  live.current.loadedItems = loadedItems
+
+  const state = useMemo(() => (check.ok ? saveState(doc, values, touched, loadedItems, controls) : { canSave: false, status: 'invalid', errors: {}, shown: {} }),
+    [check.ok, doc, values, touched, loadedItems, controls])
+
+  // ── saving ────────────────────────────────────────────────────────────
+  const timer = useRef(null)
+  const inFlight = useRef(null)     // the promise of the save running now
+  const again = useRef(false)       // a change arrived while it ran
+
+  const runSave = useCallback(async () => {
+    clearTimeout(timer.current)
+    timer.current = null
+    if (inFlight.current) { again.current = true; return inFlight.current }
+    const l = live.current
+    const st = saveState(l.doc, l.values, l.touched, l.loadedItems, l.controls)
+    if (!st.canSave) { setStatus(st.status); return { ok: false, errors: st.errors } }
+    if (!l.onSave) { setStatus('saved'); return { ok: true } }
+
+    setStatus('saving')
+    setSaveError(null)
+    const task = (async () => {
+      try {
+        const saved = await l.onSave(l.values, { id: l.recordId, source: l.source, screen: l.doc.id, document: l.doc })
+        // A new record's first save creates it; its id makes the next save an update.
+        if (saved && typeof saved === 'object' && saved[l.recordKey] !== undefined && saved[l.recordKey] !== null) {
+          setRecordId(saved[l.recordKey])
+          live.current.recordId = saved[l.recordKey]
+        }
+        setSavedAt(new Date())
+        setListVersion((v) => v + 1)
+        setStatus('saved')
+        return { ok: true, record: saved }
+      } catch (err) {
+        setSaveError(err.message || 'Could not save')
+        setStatus('error')
+        return { ok: false, error: err }
+      } finally {
+        inFlight.current = null
+        if (again.current) { again.current = false; schedule() }  // eslint-disable-line no-use-before-define
+      }
+    })()
+    inFlight.current = task
+    return task
+  }, [])
+
+  const schedule = useCallback(() => {
+    clearTimeout(timer.current)
+    setStatus('pending')
+    timer.current = setTimeout(runSave, autosaveDelay)
+  }, [runSave, autosaveDelay])
+
+  /** Save any pending change right away — before opening another record, say. */
+  const flush = useCallback(async () => {
+    if (timer.current || again.current) return runSave()
+    if (inFlight.current) return inFlight.current
+    return { ok: true }
+  }, [runSave])
+
+  useEffect(() => () => clearTimeout(timer.current), [])
 
   // ── editing ───────────────────────────────────────────────────────────
+  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)
-    setValues((v) => {
-      const next = { ...v }
-      if (value === undefined) delete next[node.props.name]
-      else next[node.props.name] = value
-      return next
+    const name = node.props.name
+    const next = { ...live.current.values }
+    if (value === undefined) delete next[name]
+    else next[name] = value
+    live.current.values = next
+    setValues(next)
+    if (!live.current.touched.has(name)) {
+      const t = new Set(live.current.touched); t.add(name)
+      live.current.touched = t
+      setTouched(t)
+    }
+    onChangeRef.current?.(next)
+    schedule()
+  }, [optionsFor, schedule])
+
+  /** Leaving a field shows its message, even if nothing was typed. */
+  const touch = useCallback((node) => {
+    const name = node.props.name
+    if (live.current.touched.has(name)) return
+    const t = new Set(live.current.touched); t.add(name)
+    live.current.touched = t
+    setTouched(t)
+  }, [])
+
+  /** Open a record: whatever was pending is saved first. */
+  const openRecord = useCallback(async (rec) => {
+    await flush()
+    const next = startValues(rec)
+    live.current.values = next
+    live.current.recordId = rec ? rec[recordKey] ?? null : null
+    live.current.touched = new Set()
+    setValues(next)
+    setRecordId(live.current.recordId)
+    setTouched(new Set())
+    setSaveError(null)
+    setStatus('idle')
+  }, [flush, startValues, recordKey])
+
+  const newRecord = useCallback(() => openRecord(null), [openRecord])
+
+  // A different document, or a different record handed in, starts over.
+  const firstRun = useRef(true)
+  useEffect(() => {
+    if (firstRun.current) { firstRun.current = false; return }
+    if (!check.ok) return
+    openRecord(record || null)
+  }, [doc, record]) // eslint-disable-line react-hooks/exhaustive-deps
+
+  // ── lists ─────────────────────────────────────────────────────────────
+  const [lists, setLists] = useState({})   // node id → { loading, rows, error }
+  const fetchRecordsRef = useRef(fetchRecords); fetchRecordsRef.current = fetchRecords
+  const listNodes = useMemo(() => (check.ok ? doc.nodes.filter((n) => n.type === 'list') : []), [doc, check.ok])
+  useEffect(() => {
+    if (!listNodes.length) return undefined
+    let cancelled = false
+    listNodes.forEach((node) => {
+      const src = listSource(doc, node)
+      setLists((l) => ({ ...l, [node.id]: { rows: l[node.id]?.rows || [], loading: true, error: null } }))
+      const run = fetchRecordsRef.current
+        ? Promise.resolve().then(() => fetchRecordsRef.current({ source: src, screen: doc.id, node }))
+        : Promise.reject(new Error(`No fetchRecords was provided to list "${src}"`))
+      run
+        .then((rows) => { if (!cancelled) setLists((l) => ({ ...l, [node.id]: { rows: Array.isArray(rows) ? rows : [], loading: false, error: null } })) })
+        .catch((err) => { if (!cancelled) setLists((l) => ({ ...l, [node.id]: { rows: l[node.id]?.rows || [], loading: false, error: err.message || 'Could not load records' } })) })
     })
-    // Once a submit has failed, errors follow the typing — the message goes
-    // away the moment the field is fixed, not on the next click of Save.
-    if (submitted) {
-      setErrors((e) => {
-        const msg = fieldError(node, value, loadedItems[node.id])
-        const next = { ...e }
-        if (msg) next[node.props.name] = msg
-        else delete next[node.props.name]
-        return next
-      })
+    return () => { cancelled = true }
+  }, [listNodes, listVersion, doc])
+
+  const listFor = useCallback((node) => lists[node.id] || { rows: [], loading: false, error: null }, [lists])
+
+  const onDeleteRef = useRef(onDelete); onDeleteRef.current = onDelete
+  const deleteRecord = useCallback(async (node, rec) => {
+    const id = rec ? rec[recordKey] : undefined
+    if (!onDeleteRef.current) throw new Error('No onDelete was provided')
+    await onDeleteRef.current({ id, source: listSource(doc, node), screen: doc.id, record: rec })
+    // Deleting the record that is open leaves nothing to save into.
+    if (id !== undefined && id === live.current.recordId) {
+      clearTimeout(timer.current); timer.current = null
+      await openRecord(null)
     }
-  }, [submitted, optionsFor, loadedItems])
-
-  const reset = useCallback(() => {
-    setValues(initialValues(doc, providedRef.current, controls))
-    setErrors({})
-    setSubmitted(false)
-    setSubmitError(null)
-  }, [doc, controls])
-
-  const onSubmitRef = useRef(onSubmit); onSubmitRef.current = onSubmit
-  const submit = useCallback(async (e) => {
-    e?.preventDefault?.()
-    setSubmitted(true)
-    setSubmitError(null)
-    const found = validateValues(doc, values, controls, loadedItems)
-    setErrors(found)
-    if (Object.keys(found).length) return { ok: false, errors: found }
-    if (!onSubmitRef.current) return { ok: true, values }
-    setSubmitting(true)
+    setListVersion((v) => v + 1)
+  }, [doc, recordKey, openRecord])
+
+  // ── popup: a list's Edit / New in its edit screen ─────────────────────
+  const [popup, setPopup] = useState(null)   // { node, screenId, record, document, loading, error }
+  const screensRef = useRef(screens); screensRef.current = screens
+  const loadScreenRef = useRef(loadScreen); loadScreenRef.current = loadScreen
+
+  /** Edit (a record) or New (null) in the list's edit screen. */
+  const openEditor = useCallback(async (node, rec) => {
+    const screenId = node.props.editScreen
+    const base = { node, screenId, record: rec || null, document: null, loading: true, error: null }
+    setPopup(base)
     try {
-      await onSubmitRef.current(values, { document: doc })
-      return { ok: true, values }
+      let found = screensRef.current && screensRef.current[screenId]
+      if (!found && loadScreenRef.current) found = await loadScreenRef.current(screenId)
+      if (!found) throw new Error(`Screen "${screenId}" was not provided — pass it in \`screens\` or supply loadScreen`)
+      const checked = validateDocument(found, live.current.controls)
+      if (!checked.ok) throw new Error(`Screen "${screenId}" is not valid: ${checked.errors[0].path} ${checked.errors[0].message}`)
+      setPopup((p) => (p && p.screenId === screenId ? { ...p, document: found, loading: false } : p))
     } catch (err) {
-      setSubmitError(err.message || 'Could not submit')
-      return { ok: false, error: err }
-    } finally {
-      setSubmitting(false)
+      setPopup((p) => (p && p.screenId === screenId ? { ...p, loading: false, error: err.message } : p))
     }
-  }, [doc, values, controls, loadedItems])
+  }, [])
+
+  const closeEditor = useCallback(() => {
+    setPopup(null)
+    setListVersion((v) => v + 1)
+  }, [])
+
+  /** The popup's saves go to the host's onSave, and refresh the list behind it. */
+  const onSaveRef = useRef(onSave); onSaveRef.current = onSave
+  const popupSave = useCallback(async (vals, meta) => {
+    const saved = onSaveRef.current ? await onSaveRef.current(vals, meta) : undefined
+    setListVersion((v) => v + 1)
+    return saved
+  }, [])
 
   return {
     document: doc,
     documentErrors: check.errors,
+    popup,
+    fieldsFor,
+    openEditor,
+    closeEditor,
+    popupSave,
     values,
-    errors,
+    recordId,
+    errors: state.shown,
+    allErrors: state.errors,
+    status,
+    saveError,
+    savedAt,
     setValue,
+    touch,
     optionsFor,
-    submit,
-    reset,
-    submitting,
-    submitError
+    flush,
+    saveNow: runSave,
+    openRecord,
+    newRecord,
+    listFor,
+    deleteRecord,
+    recordKey,
+    canDelete: Boolean(onDelete)
   }
 }
 

package/src/validateDocument.js

@@ -10,10 +10,15 @@
 // 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, BUTTON_ACTIONS } from './controls.js'
+import { CONTROLS, LABEL_VARIANTS, LIST_ACTIONS, STYLE_KEYS, SCREEN_STYLE_KEYS } from './controls.js'
 import { DOCUMENT_KIND, DOCUMENT_VERSION } from './document.js'
+import { RESERVED_COLUMNS, MAX_IDENTIFIER } from './tableSchema.js'
 
 const FIELD_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/
+const TABLE_NAME = /^[A-Za-z_][A-Za-z0-9_.$-]*$/
+const SCREEN_ID = /^[A-Za-z0-9_-]+$/
+const DOCUMENT_KEYS = ['kind', 'version', 'id', 'name', 'source', 'units', 'aspect', 'width', 'style', 'nodes']
+const COLOR = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i
 
 /**
  * @returns {{ ok: boolean, errors: Array<{ path: string, message: string }> }}
@@ -29,9 +34,16 @@ export function validateDocument(doc, controls = CONTROLS) {
   if (doc.kind !== DOCUMENT_KIND) err('kind', `must be "${DOCUMENT_KIND}"`)
   if (doc.version !== DOCUMENT_VERSION) err('version', `must be ${DOCUMENT_VERSION}`)
   if (!nonEmptyString(doc.id)) err('id', 'must be a non-empty string')
+  else if (!SCREEN_ID.test(doc.id)) err('id', `"${doc.id}" must contain only letters, digits, _ and -`)
   if (!nonEmptyString(doc.name)) err('name', 'must be a non-empty string — the screen\'s title, e.g. "New employee"')
   if (doc.units !== 'fraction') err('units', 'must be "fraction"')
   if (!(typeof doc.aspect === 'number' && doc.aspect > 0)) err('aspect', 'must be a number greater than 0 (1 = page as tall as it is wide)')
+  if (!(Number.isInteger(doc.width) && doc.width >= 320 && doc.width <= 1920)) err('width', 'must be a whole number of pixels from 320 to 1920 — the width the screen is designed at')
+  if (doc.source !== undefined && !(nonEmptyString(doc.source) && TABLE_NAME.test(doc.source))) err('source', 'must name the table records are saved to, e.g. "employees"')
+  checkStyle(doc.style, SCREEN_STYLE_KEYS, 'style', err, 'the screen')
+  Object.keys(doc).forEach((k) => {
+    if (!DOCUMENT_KEYS.includes(k)) err(k, `is not a screen property — allowed: ${DOCUMENT_KEYS.join(', ')}`)
+  })
   if (!Array.isArray(doc.nodes)) {
     err('nodes', 'must be an array of controls')
     return { ok: false, errors }
@@ -69,6 +81,8 @@ export function validateDocument(doc, controls = CONTROLS) {
       if (!nonEmptyString(props.name)) err(`${at}.props.name`, 'is required — the key the value is saved under')
       else if (!FIELD_NAME.test(props.name)) err(`${at}.props.name`, `"${props.name}" must start with a letter or _ and contain only letters, digits and _`)
       else if (names.has(props.name)) err(`${at}.props.name`, `"${props.name}" is already used by nodes[${names.get(props.name)}] — two fields cannot save to one key`)
+      else if (RESERVED_COLUMNS.includes(props.name)) err(`${at}.props.name`, `"${props.name}" is a standard column of every table — choose another name`)
+      else if (props.name.length > MAX_IDENTIFIER) err(`${at}.props.name`, `is ${props.name.length} characters — a column name can be at most ${MAX_IDENTIFIER}`)
       else names.set(props.name, i)
 
       if (!nonEmptyString(props.label)) err(`${at}.props.label`, 'is required — the text shown above the field')
@@ -78,15 +92,13 @@ export function validateDocument(doc, controls = CONTROLS) {
       checkValidation(node, def, at, err)
     }
 
+    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 === 'list') checkList(props, doc, at, err)
     if (node.type === 'label') {
       if (typeof props.text !== 'string') err(`${at}.props.text`, 'must be a string')
       if (props.variant !== undefined && !LABEL_VARIANTS.includes(props.variant)) err(`${at}.props.variant`, `must be one of: ${LABEL_VARIANTS.join(', ')}`)
     }
-    if (node.type === 'button') {
-      if (!nonEmptyString(props.label)) err(`${at}.props.label`, 'is required — the text on the button')
-      if (props.action !== undefined && !BUTTON_ACTIONS.includes(props.action)) err(`${at}.props.action`, `must be one of: ${BUTTON_ACTIONS.join(', ')}`)
-    }
   })
 
   return { ok: errors.length === 0, errors }
@@ -193,6 +205,62 @@ function checkDataSource(data, at, err) {
   }
 }
 
+/** `props.style` / the screen's `style`: only known keys, each in range. */
+function checkStyle(style, allowed, at, err, owner) {
+  if (style === undefined) return
+  if (!style || typeof style !== 'object' || Array.isArray(style)) { err(at, 'must be an object'); return }
+  Object.keys(style).forEach((key) => {
+    const path = `${at}.${key}`
+    const spec = STYLE_KEYS[key]
+    if (!spec || !allowed.includes(key)) {
+      err(path, `is not a style of ${owner} — allowed: ${allowed.join(', ')}`)
+      return
+    }
+    const v = style[key]
+    let ok
+    switch (spec.type) {
+      case 'number': ok = typeof v === 'number' && Number.isFinite(v) && v >= spec.min && v <= spec.max; break
+      case 'select': ok = spec.options.some((o) => o.value === v); break
+      case 'toggleValue': ok = v === 'normal' || v === spec.on; break
+      case 'color': ok = typeof v === 'string' && (COLOR.test(v) || (key !== 'color' && key !== 'labelColor' && v === 'transparent')); break
+      case 'font': ok = typeof v === 'string' && v.trim() !== '' && v.length <= 200 && !/[;{}<>]/.test(v); break
+      default: ok = true
+    }
+    if (!ok) err(path, `must be ${spec.hint}`)
+  })
+}
+
+/**
+ * A list of saved records: where they come from, which columns, which actions.
+ * With no `source` it reads the table the screen saves to, so one of the two
+ * must be set.
+ */
+function checkList(props, doc, at, err) {
+  if (props.title !== undefined && typeof props.title !== 'string') err(`${at}.props.title`, 'must be a string')
+  if (props.source !== undefined && !(nonEmptyString(props.source) && TABLE_NAME.test(props.source))) err(`${at}.props.source`, 'must name the table to list records from')
+  if (props.source === undefined && doc.source === undefined) err(`${at}.props.source`, 'is required when the screen has no "source" — which table should the list read?')
+  if (props.editScreen !== undefined && !(nonEmptyString(props.editScreen) && SCREEN_ID.test(props.editScreen))) err(`${at}.props.editScreen`, 'must be the id of the screen that edits a record, e.g. "employee_edit"')
+  if (props.pageSize !== undefined && !(Number.isInteger(props.pageSize) && props.pageSize >= 1 && props.pageSize <= 200)) err(`${at}.props.pageSize`, 'must be a whole number from 1 to 200')
+  if (props.actions !== undefined) {
+    if (!Array.isArray(props.actions)) err(`${at}.props.actions`, `must be an array of: ${LIST_ACTIONS.join(', ')}`)
+    else props.actions.forEach((a, j) => { if (!LIST_ACTIONS.includes(a)) err(`${at}.props.actions[${j}]`, `must be one of: ${LIST_ACTIONS.join(', ')}`) })
+  }
+  if (props.columns !== undefined) {
+    if (!Array.isArray(props.columns)) { err(`${at}.props.columns`, 'must be an array of { field, label }'); return }
+    const seen = new Set()
+    props.columns.forEach((c, j) => {
+      const p = `${at}.props.columns[${j}]`
+      if (!c || typeof c !== 'object') { err(p, 'must be { field, label }'); return }
+      if (!(nonEmptyString(c.field) && FIELD_NAME.test(c.field))) err(`${p}.field`, 'must be a field name — letters, digits and _')
+      else if (seen.has(c.field)) err(`${p}.field`, `"${c.field}" appears twice`)
+      else seen.add(c.field)
+      if (!nonEmptyString(c.label)) err(`${p}.label`, 'must be a non-empty string — the column heading')
+      const extra = Object.keys(c).filter((k) => k !== 'field' && k !== 'label')
+      if (extra.length) err(p, `only "field" and "label" are used — remove: ${extra.join(', ')}`)
+    })
+  }
+}
+
 function nonEmptyString(v) {
   return typeof v === 'string' && v.trim() !== ''
 }

package/src/values.js

@@ -146,3 +146,64 @@ export function optionValue(options, raw) {
 function safeRegExp(pattern) {
   try { return new RegExp(pattern) } catch (_) { return { test: () => true } }
 }
+
+// ── autosave ─────────────────────────────────────────────────────────────
+// There is no submit. A screen saves itself a moment after a change, as long
+// as what is entered is acceptable. This decides whether it can, and which
+// messages to SHOW: a field nobody has touched is not shouted at for being
+// empty — it only holds the save back.
+
+/**
+ * @param touched   Set of field names the person has changed or left
+ * @returns {{ canSave, status, errors, shown }}
+ *   status  'ready' | 'incomplete' (only untouched required fields are empty) | 'invalid'
+ *   errors  every failing field → message
+ *   shown   the ones to display now
+ */
+export function saveState(doc, values, touched, loadedOptions = {}, controls = CONTROLS) {
+  const errors = validateValues(doc, values, controls, loadedOptions)
+  const names = Object.keys(errors)
+  const shown = {}
+  names.forEach((n) => { if (touched && touched.has(n)) shown[n] = errors[n] })
+  if (!names.length) return { canSave: true, status: 'ready', errors, shown }
+  const onlyUntouched = names.every((n) => !(touched && touched.has(n)))
+  return { canSave: false, status: onlyUntouched ? 'incomplete' : 'invalid', errors, shown }
+}
+
+/** A saved record → the screen's values, for Edit. Fields the screen does not have are left out. */
+export function recordValues(doc, record, controls = CONTROLS) {
+  const out = {}
+  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
+    else if (node.type === 'checkbox') out[name] = false
+  })
+  return out
+}
+
+// ── lists ────────────────────────────────────────────────────────────────
+
+/** The table a list reads: its own, else the one the screen saves to. */
+export function listSource(doc, node) {
+  return (node && node.props && node.props.source) || doc.source || null
+}
+
+/** A list's columns: the ones chosen, else the screen's fields in reading order. */
+export function listColumns(doc, node, controls = CONTROLS) {
+  if (node && Array.isArray(node.props?.columns) && node.props.columns.length) return node.props.columns
+  return inputNodes(doc, controls).map((n) => ({ field: n.props.name, label: n.props.label || n.props.name }))
+}
+
+/** How a stored value reads in a list: a dropdown's name, not its id; Yes/No for a checkbox. */
+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)
+  }
+  return value
+}