@xeplr/ui-factory 1.8.2 → 1.8.4

package/src/useFactoryScreen.js

@@ -4,7 +4,8 @@ import { inputNodes, nodesForSteps, steppers, stepsOf, stepOf, resolveStep, reac
 import { validateDocument } from './validateDocument.js'
 import { initialValues, parseInput, saveState, fieldError, optionValue, recordValues, listSource, resolveBinding } from './values.js'
 import { hookMethod } from './hooks.js'
-import { useUrlSteps } from './useUrlPlaces.js'
+import { useUrlSteps, useUrlListQuery } from './useUrlPlaces.js'
+import { buttonShown, buttonDisabled } from './buttons.js'
 
 // A saved screen, running. No JSX — designs/ScreenSample.jsx draws it.
 //
@@ -58,6 +59,11 @@ import { useUrlSteps } from './useUrlPlaces.js'
  * @param onDirtyChange (dirty) → void — whether there are unsaved changes, as that changes
  * @param controls      the control registry (default: the built-ins)
  * @param hooks         a FactoryHooks (or an object with some of its methods) — get / save / delete / actions
+ * @param fetchRows     async ({ screen, node, q, filter }) → { rows, counts } — a list whose rows a function works out (rowsFrom)
+ * @param fetchRowDetails async ({ screen, node, column, id }) → [{ text, sub?, at?, open? }] — an activity cell's hover box
+ * @param pressButton   async ({ screen, button, id, note }) → { message } — a button's press, run on the server
+ * @param onButtonDone  ({ button, result, record }) → void — after a press: the host reloads what it shows
+ * @param reloadKey     anything — when it changes, every list reloads (the host heard something changed)
  * @param urlKey        where the open step of each stepper lives in the URL (`<urlKey>Steps`),
  *                      so a refresh or a shared link lands on the same step. Omitted → in memory.
  */
@@ -72,9 +78,13 @@ import { useUrlSteps } from './useUrlPlaces.js'
  *   whose default is `{previous.department_edit.values.name}` is filled from
  *   here — empty when that screen was not on this run's path.
  */
+/** How long typing in a list's search pauses before it asks. */
+const SEARCH_PAUSE_MS = 250
+
 export function useFactoryScreen({
   document: doc, record, recordKey = 'id', onSave, fetchOptions, fetchRecords, fetchRecord, onDelete, onChange, screens, loadScreen, hooks, uploadFile, fileUrl,
   onOpenRecord, onDone, onDirtyChange, params, urlKey, previous,
+  fetchRows, fetchRowDetails, pressButton, onButtonDone, reloadKey,
   link, onReady,
   controls = CONTROLS
 } = {}) {
@@ -591,20 +601,47 @@ export function useFactoryScreen({
   }, [doc, record]) // eslint-disable-line react-hooks/exhaustive-deps
 
   // ── lists ─────────────────────────────────────────────────────────────
-  const [lists, setLists] = useState({})   // node id → { loading, rows, error }
+  const [lists, setLists] = useState({})   // node id → { loading, rows, error, counts }
   const fetchRecordsRef = useRef(fetchRecords); fetchRecordsRef.current = fetchRecords
+  const fetchRowsRef = useRef(fetchRows); fetchRowsRef.current = fetchRows
   const listNodes = useMemo(() => (check.ok ? doc.nodes.filter((n) => n.type === 'list') : []), [doc, check.ok])
+  // WHAT A FUNCTION-FED LIST IS NARROWED TO — the search typed and the chip
+  // chosen. In the URL under the host's urlKey, so a refresh lands on the same
+  // rows. The search waits for a pause in typing before it asks.
+  const [listQ, setListQ] = useUrlListQuery(urlKey, 'q')
+  const [listFilter, setListFilter] = useUrlListQuery(urlKey, 'filter')
+  const [askedQ, setAskedQ] = useState(listQ)
+  useEffect(() => {
+    if (askedQ === listQ) return undefined
+    const t = setTimeout(() => setAskedQ(listQ), SEARCH_PAUSE_MS)
+    return () => clearTimeout(t)
+  }, [listQ, askedQ])
+  // A list whose text changes with time ("2h ago") asks again every so often.
+  const refreshEvery = useMemo(() => Math.min(...listNodes.map((n) => n.props.refreshEvery || Infinity)), [listNodes])
+  useEffect(() => {
+    if (!Number.isFinite(refreshEvery)) return undefined
+    const t = setInterval(() => setListVersion((v) => v + 1), refreshEvery * 1000)
+    return () => clearInterval(t)
+  }, [refreshEvery])
   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 fed = Boolean(node.props.rowsFrom)
+      setLists((l) => ({ ...l, [node.id]: { rows: l[node.id]?.rows || [], counts: l[node.id]?.counts || {}, loading: true, error: null } }))
       const run = Promise.resolve().then(() => hook('get')({
         many: true, id: null, screen: doc.id, source: src, node, document: doc,
         steps: live.current.steps,
+        query: fed ? { q: askedQ, filter: listFilter } : undefined,
         defaults: {
           get: () => {
+            // ROWS A FUNCTION WORKS OUT: the server runs the list's rowsFrom
+            // with the search and the chip, and answers { rows, counts }.
+            if (fed) {
+              if (!fetchRowsRef.current) throw new Error(`No fetchRows was provided — the list's rows come from "${node.props.rowsFrom}"`)
+              return fetchRowsRef.current({ screen: doc.id, node: node.id, q: askedQ, filter: listFilter || undefined })
+            }
             if (!fetchRecordsRef.current) throw new Error(`No fetchRecords was provided to list "${src}"`)
             // A SUB-TABLE IS THIS RECORD'S. `belongsTo` names the column on
             // those rows that points back here, and the id is this record's
@@ -620,11 +657,26 @@ export function useFactoryScreen({
         }
       }))
       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' } })) })
+        .then((out) => {
+          if (cancelled) return
+          const rows = Array.isArray(out) ? out : out && Array.isArray(out.rows) ? out.rows : []
+          const counts = out && !Array.isArray(out) && out.counts ? out.counts : {}
+          setLists((l) => ({ ...l, [node.id]: { rows, counts, loading: false, error: null } }))
+        })
+        .catch((err) => { if (!cancelled) setLists((l) => ({ ...l, [node.id]: { rows: l[node.id]?.rows || [], counts: l[node.id]?.counts || {}, loading: false, error: err.message || 'Could not load records' } })) })
     })
     return () => { cancelled = true }
-  }, [listNodes, listVersion, doc])
+  }, [listNodes, listVersion, doc, askedQ, listFilter, reloadKey]) // eslint-disable-line react-hooks/exhaustive-deps
+
+  /** What a function-fed list is narrowed to, and how to change it. */
+  const listQuery = useMemo(() => ({ q: listQ, filter: listFilter, setQ: setListQ, setFilter: setListFilter }), [listQ, listFilter, setListQ, setListFilter])
+
+  /** An activity cell's hover box: the column's function, for one row. */
+  const fetchRowDetailsRef = useRef(fetchRowDetails); fetchRowDetailsRef.current = fetchRowDetails
+  const rowDetails = useCallback((node, column, id) => {
+    if (!fetchRowDetailsRef.current) return Promise.reject(new Error('No fetchRowDetails was provided'))
+    return Promise.resolve(fetchRowDetailsRef.current({ screen: doc.id, node: node.id, column: column.field, id }))
+  }, [doc])
 
   const listFor = useCallback((node) => lists[node.id] || { rows: [], loading: false, error: null }, [lists])
 
@@ -674,7 +726,9 @@ export function useFactoryScreen({
    * open: the factory has no router, so it asks.
    */
   const openRecordRef = useRef(onOpenRecord); openRecordRef.current = onOpenRecord
-  const openEditor = useCallback(async (node, rec) => {
+  // `where`: a page opened at one part of the record — what a hover box's
+  // entry points at ({ task: 'tk_3' }), handed to onOpenRecord as params.
+  const openEditor = useCallback(async (node, rec, where) => {
     const screenId = node.props.editScreen
 
     // WHAT THE CHILD IS CALLED WITH. A sub-table's row belongs to THIS
@@ -687,7 +741,8 @@ export function useFactoryScreen({
     if (node.props.openIn === 'page') {
       if (!openRecordRef.current) throw new Error('This list opens records on a page, but no onOpenRecord was provided to go there')
       const id = rec ? rec[live.current.recordKey] : null
-      return openRecordRef.current({ screen: screenId, id, record: rec || null, source: listSource(doc, node), node, params: given })
+      const at = where && typeof where === 'object' ? where : null
+      return openRecordRef.current({ screen: screenId, id, record: rec || null, source: listSource(doc, node), node, params: given || at ? { ...(given || {}), ...(at || {}) } : given })
     }
     const base = { node, screenId, record: rec || null, document: null, loading: true, error: null, params: given }
     setPopup(base)
@@ -769,6 +824,43 @@ export function useFactoryScreen({
     return saved
   }, [])
 
+  // ── buttons ───────────────────────────────────────────────────────────
+  // A button acts on the record this screen is about: the one the host
+  // handed in, with whatever the form has changed on top. Whether each shows
+  // and is greyed out is read from it; the press runs on the server, which
+  // checks the same again on the saved record.
+  const pressRef = useRef(pressButton); pressRef.current = pressButton
+  const buttonDoneRef = useRef(onButtonDone); buttonDoneRef.current = onButtonDone
+  const [pressing, setPressing] = useState(null)        // button id on the wire
+  const [buttonNote, setButtonNote] = useState(null)    // { kind: 'done' | 'error', text, button }
+  const buttonRecord = useMemo(() => ({ ...(record || {}), ...values, [recordKey]: recordId }), [record, values, recordKey, recordId])
+  const buttonsFor = useCallback((node) => ({
+    record: buttonRecord,
+    buttons: ((node.props && node.props.buttons) || [])
+      .filter((b) => buttonShown(b, buttonRecord))
+      .map((b) => ({ ...b, disabled: buttonDisabled(b, buttonRecord) || recordId === null || recordId === undefined })),
+    pressing,
+    note: buttonNote,
+    clearNote: () => setButtonNote(null),
+    press: async (b, typed) => {
+      if (!pressRef.current) { setButtonNote({ kind: 'error', text: 'No pressButton was provided', button: b.id }); return false }
+      setPressing(b.id)
+      setButtonNote(null)
+      try {
+        const result = await pressRef.current({ screen: doc.id, button: b.id, id: recordId, note: typed })
+        setButtonNote({ kind: 'done', text: (result && result.message) || `${b.label} — done`, button: b.id })
+        setListVersion((v) => v + 1)
+        if (buttonDoneRef.current) buttonDoneRef.current({ button: b, result, record: buttonRecord })
+        return true
+      } catch (err) {
+        setButtonNote({ kind: 'error', text: err.message || `Could not ${b.label}`, button: b.id })
+        return false
+      } finally {
+        setPressing(null)
+      }
+    }
+  }), [buttonRecord, pressing, buttonNote, doc, recordId])
+
   return {
     document: doc,
     documentErrors: linkError ? [...check.errors, linkError] : check.errors,
@@ -805,6 +897,9 @@ export function useFactoryScreen({
     openRecord,
     newRecord,
     listFor,
+    listQuery,
+    rowDetails,
+    buttonsFor,
     deleteRecord,
     recordKey,
     canDelete: Boolean(onDelete) || Boolean(hooks && typeof hooks.delete === 'function'),

package/src/useUrlPlaces.js

@@ -58,3 +58,16 @@ export function useUrlTab(urlKey, first) {
   const setTab = useCallback((next) => setValue(next === first ? null : next), [setValue, first])
   return [value || first, setTab]
 }
+
+/**
+ * [value, setValue] — a list's search, or the filter chip it is on: what the
+ * person narrowed the list to, so a refresh or a shared link shows the same
+ * rows. One of each per screen. Typing and switching chips replace the
+ * history entry rather than adding one per letter.
+ */
+export function useUrlListQuery(urlKey, which) {
+  const keys = factoryUrlKeys(urlKey)
+  const [value, setValue] = useUrlState(keys ? keys[which] : which, { inUrl: Boolean(keys), replace: true })
+  const set = useCallback((next) => setValue(next === undefined || next === null || next === '' ? null : String(next)), [setValue])
+  return [value || '', set]
+}

package/src/validateDocument.js

@@ -16,6 +16,7 @@ import { DOCUMENT_KIND, DOCUMENT_VERSION } from './document.js'
 import { RESERVED_COLUMNS, MAX_IDENTIFIER } from './tableSchema.js'
 import { FIELD_PRESETS, INPUT_TYPES, presetFor } from './presets.js'
 import { isBinding } from './values.js'
+import { BUTTON_VARIANTS, COLUMN_DISPLAYS, BADGE_TONES, CONDITION_OPERATORS } from './buttons.js'
 
 const FIELD_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/
 const TABLE_NAME = /^[A-Za-z_][A-Za-z0-9_.$-]*$/
@@ -108,6 +109,8 @@ export function validateDocument(doc, controls = CONTROLS) {
 
   const ids = new Map()
   const names = new Map()
+  // A press names its button by id, so an id is unique on the whole screen.
+  const buttonIds = new Map()
 
   doc.nodes.forEach((node, i) => {
     const at = `nodes[${i}]`
@@ -175,6 +178,7 @@ export function validateDocument(doc, controls = CONTROLS) {
     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 === 'buttons') checkButtons(props, at, err, buttonIds)
     if (node.type === 'subform') checkSubform(props, doc, at, err)
     if (node.type === 'label') {
       if (typeof props.text !== 'string') err(`${at}.props.text`, 'must be a string')
@@ -401,7 +405,16 @@ 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?')
+  // ROWS A FUNCTION WORKS OUT need no table — but everything that only a
+  // function can answer (a search, chips and their counts, a hover box)
+  // needs the function.
+  const fed = props.rowsFrom !== undefined
+  if (fed && !(nonEmptyString(props.rowsFrom) && FUNCTION_NAME.test(props.rowsFrom))) err(`${at}.props.rowsFrom`, 'must be the name of a registered function (event "listRows"), e.g. "orderList"')
+  if (!fed && props.source === undefined && doc.source === undefined) err(`${at}.props.source`, 'is required when the screen has no "source" — which table should the list read? (or "rowsFrom": a function that works the rows out)')
+  checkFedList(props, fed, at, err)
+  if (props.grow !== undefined && typeof props.grow !== 'boolean') err(`${at}.props.grow`, 'must be true or false')
+  // The page grows with it, so nothing can be placed beside or under it.
+  if (props.grow && doc.nodes.length !== 1) err(`${at}.props.grow`, 'only for a list that is the screen\'s one control — the page grows with it, so nothing else has a place')
   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"')
 
   // THE LINK BACK, for a sub-table on a form: this material's
@@ -429,12 +442,143 @@ function checkList(props, doc, at, err) {
       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(', ')}`)
+      const allowed = fed ? FED_COLUMN_KEYS : ['field', 'label']
+      const extra = Object.keys(c).filter((k) => !allowed.includes(k))
+      if (extra.length) err(p, fed ? `has keys a column does not use — remove: ${extra.join(', ')}` : `only "field" and "label" are used — remove: ${extra.join(', ')} (the rest need "rowsFrom")`)
+      if (fed) checkFedColumn(c, p, err)
     })
   }
 }
 
+// What a column of a function-fed list may say: the value it sorts by
+// (`field`), the text shown for it (`text`, else the value), a second line,
+// how it is drawn, badges after it, how many more pictures, and the function
+// its hover box lists from.
+const FED_COLUMN_KEYS = ['field', 'label', 'text', 'sub', 'display', 'badges', 'more', 'details', 'sortable']
+
+/** The settings only a function-fed list has. */
+function checkFedList(props, fed, at, err) {
+  const need = (key, what) => { if (props[key] !== undefined && !fed) err(`${at}.props.${key}`, `${what} needs "rowsFrom" — a table's records have no function to ask`) }
+  need('search', 'a search box')
+  need('filters', 'filter chips')
+  need('refreshEvery', 'refreshing')
+  if (props.search !== undefined) {
+    const sp = props.search
+    if (!sp || typeof sp !== 'object' || Array.isArray(sp)) err(`${at}.props.search`, 'must be { placeholder } — the hint in the search box')
+    else if (sp.placeholder !== undefined && typeof sp.placeholder !== 'string') err(`${at}.props.search.placeholder`, 'must be a string')
+  }
+  if (props.filters !== undefined) {
+    if (!Array.isArray(props.filters)) err(`${at}.props.filters`, 'must be an array of { key, label }')
+    else {
+      const keys = new Set()
+      props.filters.forEach((f, j) => {
+        const p = `${at}.props.filters[${j}]`
+        if (!f || typeof f !== 'object') { err(p, 'must be { key, label }'); return }
+        if (!(nonEmptyString(f.key) && /^[A-Za-z0-9_-]+$/.test(f.key))) err(`${p}.key`, 'must be letters, digits, _ or - — what the function is asked for, e.g. "packed"')
+        else if (keys.has(f.key)) err(`${p}.key`, `"${f.key}" appears twice`)
+        else keys.add(f.key)
+        if (!nonEmptyString(f.label)) err(`${p}.label`, 'must be the chip\'s text, e.g. "Packed"')
+        const extra = Object.keys(f).filter((k) => k !== 'key' && k !== 'label')
+        if (extra.length) err(p, `only "key" and "label" are used — remove: ${extra.join(', ')}`)
+      })
+    }
+  }
+  if (props.refreshEvery !== undefined && !(Number.isInteger(props.refreshEvery) && props.refreshEvery >= 10 && props.refreshEvery <= 3600)) {
+    err(`${at}.props.refreshEvery`, 'must be a whole number of seconds from 10 to 3600')
+  }
+  if (props.rowOpen !== undefined && typeof props.rowOpen !== 'boolean') err(`${at}.props.rowOpen`, 'must be true or false')
+  if (props.rowOpen && !props.editScreen) err(`${at}.props.rowOpen`, 'needs "Edit in" (editScreen) — the screen a row opens in')
+  // A worked-out row is not a record of one table: nothing to delete it from,
+  // and Edit or New only with a screen to do it in.
+  if (fed && Array.isArray(props.actions)) {
+    if (props.actions.includes('delete')) err(`${at}.props.actions`, 'cannot include "delete" — rows from a function are not one table\'s records')
+    if ((props.actions.includes('edit') || props.actions.includes('new')) && !props.editScreen) err(`${at}.props.actions`, 'Edit and New need "Edit in" (editScreen) — the screen they open')
+  }
+  if (props.highlight !== undefined && !(nonEmptyString(props.highlight) && FIELD_NAME.test(props.highlight))) err(`${at}.props.highlight`, 'must be a field of the row, e.g. "isNew"')
+}
+
+function checkFedColumn(c, p, err) {
+  ;['text', 'sub', 'more'].forEach((k) => {
+    if (c[k] !== undefined && !(nonEmptyString(c[k]) && FIELD_NAME.test(c[k]))) err(`${p}.${k}`, 'must be a field of the row — letters, digits and _')
+  })
+  if (c.display !== undefined && !COLUMN_DISPLAYS.includes(c.display)) err(`${p}.display`, `must be one of: ${COLUMN_DISPLAYS.join(', ')}`)
+  if (c.more !== undefined && c.display !== 'images') err(`${p}.more`, 'only means something on an "images" column')
+  if (c.details !== undefined) {
+    if (!(nonEmptyString(c.details) && FUNCTION_NAME.test(c.details))) err(`${p}.details`, 'must be the name of a registered function (event "rowDetails")')
+    else if (c.display !== 'activity') err(`${p}.details`, 'is what an "activity" column\'s hover box lists — set display to "activity"')
+  }
+  if (c.sortable !== undefined && typeof c.sortable !== 'boolean') err(`${p}.sortable`, 'must be true or false')
+  if (c.badges !== undefined) {
+    if (!Array.isArray(c.badges)) { err(`${p}.badges`, 'must be an array of { field, label, tone? }'); return }
+    c.badges.forEach((b, k) => {
+      const bp = `${p}.badges[${k}]`
+      if (!b || typeof b !== 'object') { err(bp, 'must be { field, label, tone? }'); return }
+      if (!(nonEmptyString(b.field) && FIELD_NAME.test(b.field))) err(`${bp}.field`, 'must be a field of the row — the badge shows where it is true')
+      if (!nonEmptyString(b.label)) err(`${bp}.label`, 'must be the badge\'s text, e.g. "New"')
+      if (b.tone !== undefined && !BADGE_TONES.includes(b.tone)) err(`${bp}.tone`, `must be one of: ${BADGE_TONES.join(', ')}`)
+      const extra = Object.keys(b).filter((x) => !['field', 'label', 'tone'].includes(x))
+      if (extra.length) err(bp, `only "field", "label" and "tone" are used — remove: ${extra.join(', ')}`)
+    })
+  }
+}
+
+const BUTTON_KEYS = ['id', 'label', 'action', 'params', 'ask', 'when', 'disabledWhen', 'variant']
+const ASK_KEYS = ['title', 'message', 'note']
+
+/**
+ * A panel of buttons. Each names a function and the values it is given; the
+ * server checks the names against what is registered when the screen is
+ * published (functionProblems). Here: the shape.
+ */
+function checkButtons(props, at, err, ids) {
+  if (props.title !== undefined && typeof props.title !== 'string') err(`${at}.props.title`, 'must be a string')
+  if (!Array.isArray(props.buttons)) { err(`${at}.props.buttons`, 'must be an array of buttons — { id, label, action, params? }'); return }
+  props.buttons.forEach((b, j) => {
+    const p = `${at}.props.buttons[${j}]`
+    if (!b || typeof b !== 'object' || Array.isArray(b)) { err(p, 'must be { id, label, action, params? }'); return }
+    const extra = Object.keys(b).filter((k) => !BUTTON_KEYS.includes(k))
+    if (extra.length) err(p, `has keys a button does not use — remove: ${extra.join(', ')}`)
+    if (!(nonEmptyString(b.id) && /^[A-Za-z0-9_-]{1,60}$/.test(b.id))) err(`${p}.id`, 'must be letters, digits, _ or - — what a press names this button by, e.g. "packed"')
+    else if (ids.has(b.id)) err(`${p}.id`, `"${b.id}" is already the id of ${ids.get(b.id)} — every button on a screen needs its own`)
+    else ids.set(b.id, p)
+    if (!nonEmptyString(b.label)) err(`${p}.label`, 'must be the button\'s text, e.g. "Packed"')
+    if (!(nonEmptyString(b.action) && FUNCTION_NAME.test(b.action))) err(`${p}.action`, 'must be the name of a registered function (event "button"), e.g. "setOrderStatus"')
+    if (b.params !== undefined) {
+      if (!b.params || typeof b.params !== 'object' || Array.isArray(b.params)) err(`${p}.params`, 'must be { name: value } — what the function is given')
+      else Object.keys(b.params).forEach((k) => {
+        const v = b.params[k]
+        if (!(v === null || ['string', 'number', 'boolean'].includes(typeof v))) err(`${p}.params.${k}`, 'must be a plain value — text, a number, true or false')
+      })
+    }
+    if (b.ask !== undefined) {
+      if (!b.ask || typeof b.ask !== 'object' || Array.isArray(b.ask)) err(`${p}.ask`, 'must be { title?, message?, note? } — what the person is asked before it runs')
+      else {
+        const bad = Object.keys(b.ask).filter((k) => !ASK_KEYS.includes(k))
+        if (bad.length) err(`${p}.ask`, `only ${ASK_KEYS.map((k) => `"${k}"`).join(', ')} are used — remove: ${bad.join(', ')}`)
+        ASK_KEYS.forEach((k) => { if (b.ask[k] !== undefined && typeof b.ask[k] !== 'string') err(`${p}.ask.${k}`, 'must be a string') })
+      }
+    }
+    if (b.variant !== undefined && !BUTTON_VARIANTS.includes(b.variant)) err(`${p}.variant`, `must be one of: ${BUTTON_VARIANTS.join(', ')}`)
+    ;['when', 'disabledWhen'].forEach((k) => { if (b[k] !== undefined) checkRules(b[k], `${p}.${k}`, err) })
+  })
+}
+
+/** Conditions on the record: @xeplr/rules rules, every one of which must match. */
+function checkRules(rules, at, err) {
+  if (!Array.isArray(rules)) { err(at, 'must be an array of { field, op, value } — every one must match'); return }
+  rules.forEach((r, k) => {
+    const p = `${at}[${k}]`
+    if (!r || typeof r !== 'object') { err(p, 'must be { field, op, value }'); return }
+    if (!(nonEmptyString(r.field) && FIELD_NAME.test(r.field))) err(`${p}.field`, 'must be a field of the record, e.g. "customStatus"')
+    const op = CONDITION_OPERATORS.find((o) => o.key === r.op)
+    if (!op) { err(`${p}.op`, `must be one of: ${CONDITION_OPERATORS.map((o) => o.key).join(', ')}`); return }
+    if (!op.noValue && (r.value === undefined || r.value === null || r.value === '')) err(`${p}.value`, 'needs a value to compare with')
+    if (op.second && (r.value2 === undefined || r.value2 === null || r.value2 === '')) err(`${p}.value2`, 'needs the other end of the range')
+    const extra = Object.keys(r).filter((x) => !['field', 'op', 'value', 'value2'].includes(x))
+    if (extra.length) err(p, `only "field", "op", "value" and "value2" are used — remove: ${extra.join(', ')}`)
+  })
+}
+
 /**
  * A form inside this one. Both halves are required: a form with no link saves
  * a record belonging to nothing, and a link with no form is nothing. Itself is