@xeplr/ui-factory 1.0.1

package/src/useFactoryBuilder.js

@@ -0,0 +1,209 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
+import { CONTROLS, controlGroups } from './controls.js'
+import {
+  createScreen, renameScreen, addControl as addControlTo, moveNode, setNodeProperty,
+  removeNodes
+} from './document.js'
+import { validateDocument } from './validateDocument.js'
+
+// The builder's controller: the document being edited, what is selected, and
+// every change the builder can make. No JSX — designs/BuilderSample.jsx draws
+// it, and a host with its own design can use this hook directly.
+//
+// STORAGE IS THE HOST'S. This never loads or persists anything: it starts from
+// the `document` it is handed and gives the result to `onSave`. A document
+// handed in LATER (Claude regenerated the screen, another record was opened)
+// replaces what is being edited.
+
+/**
+ * @param document    the screen to edit; omitted → a new empty screen
+ * @param name        the name for a new screen (when no document)
+ * @param onSave      async (document) → void; called only with a valid document
+ * @param onChange    (document) → void; every edit, for hosts that autosave or preview
+ * @param listTables  async () → [{ id, name }] | string[]; offered in a dropdown's
+ *                    "from a table" picker. Omitted → table sources can still be typed.
+ * @param controls    the control registry (default: the built-ins)
+ */
+export function useFactoryBuilder({ document: given, name, onSave, onChange, listTables, controls = CONTROLS } = {}) {
+  const [doc, setDoc] = useState(() => given || createScreen({ name }))
+  const [selected, setSelected] = useState(() => new Set())
+  const [dirty, setDirty] = useState(false)
+  const [saving, setSaving] = useState(false)
+  const [saveError, setSaveError] = useState(null)
+  const [showErrors, setShowErrors] = useState(false)
+  const docRef = useRef(doc); docRef.current = doc
+
+  // A NEW document from outside replaces the draft. Compared by identity: the
+  // host re-rendering with the same object must not throw away edits.
+  const lastGiven = useRef(given)
+  useEffect(() => {
+    if (!given || given === lastGiven.current) return
+    lastGiven.current = given
+    docRef.current = given
+    setDoc(given)
+    setSelected(new Set())
+    setDirty(false)
+    setShowErrors(false)
+  }, [given])
+
+  // Every edit goes through here. It works on a REF of the current document,
+  // not a state updater: an edit that needs its own result (the id of the
+  // control just added) gets it synchronously, and two edits in one event
+  // build on each other instead of both starting from the same render.
+  const onChangeRef = useRef(onChange); onChangeRef.current = onChange
+  const update = useCallback((fn) => {
+    const current = docRef.current
+    const next = fn(current)
+    if (next === current) return current
+    docRef.current = next
+    setDoc(next)
+    setDirty(true)
+    onChangeRef.current?.(next)
+    return next
+  }, [])
+
+  // ── tables for the dropdown source picker ─────────────────────────────
+  const [tables, setTables] = useState({ loading: Boolean(listTables), items: [], error: null })
+  const listTablesRef = useRef(listTables); listTablesRef.current = listTables
+  const hasListTables = Boolean(listTables)
+  useEffect(() => {
+    if (!hasListTables) return undefined
+    let cancelled = false
+    Promise.resolve()
+      .then(() => listTablesRef.current())
+      .then((rows) => {
+        if (cancelled) return
+        const items = (rows || []).map((t) => (typeof t === 'string' ? { id: t, name: t } : t))
+        setTables({ loading: false, items, error: null })
+      })
+      .catch((err) => { if (!cancelled) setTables({ loading: false, items: [], error: err.message || 'Could not list tables' }) })
+    return () => { cancelled = true }
+  }, [hasListTables])
+
+  // ── edits ─────────────────────────────────────────────────────────────
+  const rename = useCallback((value) => update((d) => renameScreen(d, value)), [update])
+
+  /** 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)
+      added = r.node
+      return r.document
+    })
+    if (added) setSelected(new Set([added.id]))
+    return added
+  }, [update, controls])
+
+  const moveControl = useCallback((id, patch) => update((d) => moveNode(d, id, patch)), [update])
+
+  const setProperty = useCallback((id, path, value) => update((d) => setNodeProperty(d, id, path, value, controls)), [update, controls])
+
+  const selectedRef = useRef(selected); selectedRef.current = selected
+  const removeSelected = useCallback(() => {
+    const ids = [...selectedRef.current]
+    if (!ids.length) return
+    update((d) => removeNodes(d, ids))
+    setSelected(new Set())
+  }, [update])
+
+  /** Everything selected moves to a copy, just below the original. */
+  const duplicateSelected = useCallback(() => {
+    const ids = [...selectedRef.current]
+    if (!ids.length) return
+    const created = []
+    update((d) => {
+      let next = d
+      ids.forEach((id) => {
+        const src = d.nodes.find((n) => n.id === id)
+        if (!src) return
+        const props = JSON.parse(JSON.stringify(src.props))
+        delete props.name
+        const r = addControlTo(next, src.type, { at: { x: src.x, y: src.y + src.h + 0.02 }, size: { w: src.w, h: src.h }, props }, controls)
+        next = r.document
+        created.push(r.node.id)
+      })
+      return next
+    })
+    setSelected(new Set(created))
+  }, [update, controls])
+
+  // ── validation + save ─────────────────────────────────────────────────
+  const validation = useMemo(() => validateDocument(doc, controls), [doc, controls])
+
+  /** Errors grouped by node id, for the canvas and the property panel. */
+  const errorsByNode = useMemo(() => {
+    const map = {}
+    validation.errors.forEach((e) => {
+      const m = /^nodes\[(\d+)\]\.?(.*)$/.exec(e.path)
+      const node = m && doc.nodes[Number(m[1])]
+      const key = node ? node.id : '_document'
+      ;(map[key] = map[key] || []).push({ ...e, field: m ? m[2] : e.path })
+    })
+    return map
+  }, [validation, doc.nodes])
+
+  const onSaveRef = useRef(onSave); onSaveRef.current = onSave
+  const save = useCallback(async () => {
+    setShowErrors(true)
+    setSaveError(null)
+    if (!validation.ok) return { ok: false, errors: validation.errors }
+    if (!onSaveRef.current) return { ok: false, errors: [{ path: '', message: 'No onSave was provided' }] }
+    setSaving(true)
+    try {
+      await onSaveRef.current(doc)
+      setDirty(false)
+      setShowErrors(false)
+      return { ok: true }
+    } catch (err) {
+      setSaveError(err.message || 'Could not save')
+      return { ok: false, errors: [{ path: '', message: err.message }] }
+    } finally {
+      setSaving(false)
+    }
+  }, [doc, validation])
+
+  // ── keyboard: Delete / Backspace removes, Cmd/Ctrl+D duplicates ────────
+  useEffect(() => {
+    function onKey(e) {
+      const t = e.target
+      const typing = t && (t.isContentEditable || /^(INPUT|TEXTAREA|SELECT)$/.test(t.tagName))
+      if (typing) return
+      if ((e.key === 'Delete' || e.key === 'Backspace') && selected.size) {
+        e.preventDefault()
+        removeSelected()
+      } else if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === 'd' && selected.size) {
+        e.preventDefault()
+        duplicateSelected()
+      }
+    }
+    window.addEventListener('keydown', onKey)
+    return () => window.removeEventListener('keydown', onKey)
+  }, [selected, removeSelected, duplicateSelected])
+
+  const selectedNode = selected.size === 1 ? doc.nodes.find((n) => selected.has(n.id)) || null : null
+
+  return {
+    document: doc,
+    controls,
+    palette: useMemo(() => controlGroups(controls), [controls]),
+    selected,
+    setSelected,
+    selectedNode,
+    selectedControl: selectedNode ? controls[selectedNode.type] : null,
+    rename,
+    addControl,
+    moveControl,
+    setProperty,
+    removeSelected,
+    duplicateSelected,
+    tables,
+    validation,
+    errorsByNode,
+    showErrors,
+    dirty,
+    saving,
+    saveError,
+    save
+  }
+}

package/src/useFactoryScreen.js

@@ -0,0 +1,155 @@
+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'
+
+// A saved screen, running: its values, its dropdown options, validation and
+// submit. 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.
+
+/**
+ * @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 controls      the control registry (default: the built-ins)
+ */
+export function useFactoryScreen({ document: doc, fetchOptions, onSubmit, values: provided, 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 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])
+
+  // ── options for table dropdowns, fetched once per table ───────────────
+  const [options, setOptions] = useState({})   // node id → { loading, items, error }
+  const fetchRef = useRef(fetchOptions); fetchRef.current = fetchOptions
+  useEffect(() => {
+    let cancelled = false
+    const tableNodes = inputs.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()
+    tableNodes.forEach((n) => {
+      const t = n.props.data.table
+      if (!byTable.has(t)) byTable.set(t, [])
+      byTable.get(t).push(n)
+    })
+    byTable.forEach((nodes, table) => {
+      const run = fetchRef.current
+        ? Promise.resolve().then(() => fetchRef.current({ table, node: nodes[0] }))
+        : Promise.reject(new Error(`No fetchOptions was provided to read "${table}"`))
+      run
+        .then((rows) => {
+          const items = normaliseOptions(rows)
+          if (!cancelled) setOptions((o) => ({ ...o, ...Object.fromEntries(nodes.map((n) => [n.id, { loading: false, items, error: null }])) }))
+        })
+        .catch((err) => {
+          if (!cancelled) setOptions((o) => ({ ...o, ...Object.fromEntries(nodes.map((n) => [n.id, { loading: false, items: [], error: err.message || 'Could not load options' }])) }))
+        })
+    })
+    return () => { cancelled = true }
+  }, [inputs])
+
+  /** 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 }
+  }, [options])
+
+  const loadedItems = useMemo(() => {
+    const map = {}
+    Object.entries(options).forEach(([id, o]) => { if (!o.loading && !o.error) map[id] = o.items })
+    return map
+  }, [options])
+
+  // ── editing ───────────────────────────────────────────────────────────
+  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
+    })
+    // 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
+      })
+    }
+  }, [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)
+    try {
+      await onSubmitRef.current(values, { document: doc })
+      return { ok: true, values }
+    } catch (err) {
+      setSubmitError(err.message || 'Could not submit')
+      return { ok: false, error: err }
+    } finally {
+      setSubmitting(false)
+    }
+  }, [doc, values, controls, loadedItems])
+
+  return {
+    document: doc,
+    documentErrors: check.errors,
+    values,
+    errors,
+    setValue,
+    optionsFor,
+    submit,
+    reset,
+    submitting,
+    submitError
+  }
+}
+
+/** Rows from the host → [{ id, name }]. Anything else on a row is ignored. */
+export function normaliseOptions(rows) {
+  return (Array.isArray(rows) ? rows : [])
+    .filter((r) => r && r.id !== undefined && r.id !== null)
+    .map((r) => ({ id: r.id, name: r.name == null ? String(r.id) : String(r.name) }))
+}

package/src/validateDocument.js

@@ -0,0 +1,202 @@
+// Checks a screen document BEFORE anything renders it, and says exactly what
+// is wrong and where.
+//
+// Two readers matter. A person saving from the builder needs to know which
+// control to fix. And Claude, which writes these documents from a plain-English
+// request, needs errors precise enough to correct its own output without
+// guessing — so every error names a path (`nodes[3].props.data.table`) and
+// what was expected there.
+//
+// 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 { DOCUMENT_KIND, DOCUMENT_VERSION } from './document.js'
+
+const FIELD_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/
+
+/**
+ * @returns {{ ok: boolean, errors: Array<{ path: string, message: string }> }}
+ */
+export function validateDocument(doc, controls = CONTROLS) {
+  const errors = []
+  const err = (path, message) => errors.push({ path, message })
+
+  if (!doc || typeof doc !== 'object' || Array.isArray(doc)) {
+    err('', 'A screen document must be an object')
+    return { ok: false, errors }
+  }
+  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')
+  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 (!Array.isArray(doc.nodes)) {
+    err('nodes', 'must be an array of controls')
+    return { ok: false, errors }
+  }
+
+  const ids = new Map()
+  const names = new Map()
+
+  doc.nodes.forEach((node, i) => {
+    const at = `nodes[${i}]`
+    if (!node || typeof node !== 'object') { err(at, 'must be an object'); return }
+
+    if (!nonEmptyString(node.id)) err(`${at}.id`, 'must be a non-empty string')
+    else if (ids.has(node.id)) err(`${at}.id`, `"${node.id}" is already used by nodes[${ids.get(node.id)}]`)
+    else ids.set(node.id, i)
+
+    const def = controls[node.type]
+    if (!def) {
+      err(`${at}.type`, `unknown control "${node.type}" — one of: ${Object.keys(controls).join(', ')}`)
+      return
+    }
+
+    checkGeometry(node, at, err)
+
+    const props = node.props
+    if (!props || typeof props !== 'object' || Array.isArray(props)) {
+      err(`${at}.props`, 'must be an object')
+      return
+    }
+    Object.keys(props).forEach((key) => {
+      if (!def.props.includes(key)) err(`${at}.props.${key}`, `is not a property of "${node.type}" — allowed: ${def.props.join(', ')}`)
+    })
+
+    if (def.input) {
+      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 names.set(props.name, i)
+
+      if (!nonEmptyString(props.label)) err(`${at}.props.label`, 'is required — the text shown above the field')
+      if (props.required !== undefined && typeof props.required !== 'boolean') err(`${at}.props.required`, 'must be true or false')
+      if (props.placeholder !== undefined && typeof props.placeholder !== 'string') err(`${at}.props.placeholder`, 'must be a string')
+      checkDefault(node, def, at, err)
+      checkValidation(node, def, at, err)
+    }
+
+    if (node.type === 'dropdown') checkDataSource(props.data, `${at}.props.data`, 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 }
+}
+
+/** Throws with every error listed. For code that must not continue with a bad document. */
+export function assertValidDocument(doc, controls) {
+  const { ok, errors } = validateDocument(doc, controls)
+  if (!ok) {
+    const e = new Error('Invalid screen document:\n' + errors.map((x) => `  ${x.path || '(document)'}: ${x.message}`).join('\n'))
+    e.errors = errors
+    throw e
+  }
+  return doc
+}
+
+function checkGeometry(node, at, err) {
+  ;['x', 'y', 'w', 'h'].forEach((k) => {
+    if (typeof node[k] !== 'number' || !Number.isFinite(node[k])) err(`${at}.${k}`, 'must be a number (a fraction — see "units")')
+  })
+  if (typeof node.x === 'number' && (node.x < 0 || node.x > 1)) err(`${at}.x`, 'must be between 0 and 1 (fraction of the width)')
+  if (typeof node.w === 'number' && (node.w <= 0 || node.w > 1)) err(`${at}.w`, 'must be greater than 0 and at most 1 (fraction of the width)')
+  if (typeof node.x === 'number' && typeof node.w === 'number' && node.x + node.w > 1.0001) err(`${at}.w`, `x + w is ${round(node.x + node.w)} — the control runs off the right edge (must be ≤ 1)`)
+  if (typeof node.y === 'number' && node.y < 0) err(`${at}.y`, 'must be 0 or more (fraction of a page)')
+  if (typeof node.h === 'number' && node.h <= 0) err(`${at}.h`, 'must be greater than 0 (fraction of a page)')
+  if (node.z !== undefined && !Number.isInteger(node.z)) err(`${at}.z`, 'must be a whole number')
+}
+
+function checkDefault(node, def, at, err) {
+  const v = node.props.default
+  if (v === undefined) return
+  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)
+  }[def.valueType]
+  if (ok && !ok()) err(`${at}.props.default`, `must be a ${def.valueType === 'date' ? 'date as "YYYY-MM-DD"' : def.valueType}`)
+}
+
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/
+
+function checkValidation(node, def, at, err) {
+  const v = node.props.validation
+  if (v === undefined) return
+  if (!v || typeof v !== 'object' || Array.isArray(v)) { err(`${at}.props.validation`, 'must be an object'); return }
+  Object.keys(v).forEach((key) => {
+    const path = `${at}.props.validation.${key}`
+    if (!def.validation.includes(key)) {
+      err(path, def.validation.length
+        ? `is not a rule for "${node.type}" — allowed: ${def.validation.join(', ')}`
+        : `"${node.type}" takes no validation rules`)
+      return
+    }
+    const val = v[key]
+    if (key === 'minLength' || key === 'maxLength') {
+      if (!(Number.isInteger(val) && val >= 0)) err(path, 'must be a whole number, 0 or more')
+    } else if (key === 'integer') {
+      if (typeof val !== 'boolean') err(path, 'must be true or false')
+    } 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 === '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"')
+    }
+  })
+  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')
+}
+
+/**
+ * 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) {
+  if (!data || typeof data !== 'object') {
+    err(at, 'is required — { "source": "static", "options": [{ "id", "name" }] } or { "source": "table", "table": "<name>" }')
+    return
+  }
+  if (data.source === 'static') {
+    if (!Array.isArray(data.options)) { err(`${at}.options`, 'must be an array of { id, name }'); return }
+    const seen = new Set()
+    data.options.forEach((o, j) => {
+      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 (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')
+      const extra = Object.keys(o).filter((k) => k !== 'id' && k !== 'name')
+      if (extra.length) err(p, `only "id" and "name" are used — remove: ${extra.join(', ')}`)
+    })
+  } else if (data.source === 'table') {
+    if (!nonEmptyString(data.table)) err(`${at}.table`, 'must name the table to read { id, name } rows from')
+    const extra = Object.keys(data).filter((k) => k !== 'source' && k !== 'table')
+    if (extra.length) err(at, `a table source takes only "table" — remove: ${extra.join(', ')}`)
+  } else {
+    err(`${at}.source`, 'must be "static" or "table"')
+  }
+}
+
+function nonEmptyString(v) {
+  return typeof v === 'string' && v.trim() !== ''
+}
+
+function round(v) {
+  return Math.round(v * 10000) / 10000
+}