@xeplr/ui-factory 1.8.3 → 1.8.5

package/src/model.js

@@ -13,7 +13,14 @@ export {
 } from './document.js'
 export { validateDocument, assertValidDocument } from './validateDocument.js'
 // A screen's events: functions picked by name, run on the server.
-export { SCREEN_EVENTS, SCREEN_EVENT_KEYS, DECIDE_EVENT, FUNCTION_NAME, screenFunctions, missingFunctions, setEvent, functionsFor } from './events.js'
+export { SCREEN_EVENTS, SCREEN_EVENT_KEYS, DECIDE_EVENT, FUNCTION_NAME, screenFunctions, missingFunctions, functionProblems, setEvent, functionsFor } from './events.js'
+// Buttons and lists whose rows a function works out — names and values only.
+export {
+  BUTTON_EVENT, LIST_ROWS_EVENT, ROW_DETAILS_EVENT, BUTTON_VARIANTS, COLUMN_DISPLAYS, BADGE_TONES, NOTE_INPUT, CONDITION_OPERATORS,
+  conditionMet, buttonShown, buttonDisabled, buttonPressed, screenButtons, buttonById, buttonInput, nodeFunctions, paramProblems, optionValues
+} from './buttons.js'
+// Which pages are drawn from documents and which are web only (ui/pages.json).
+export { checkInventory, routesIn, pageWarnings, webOnlyMenus } from './pagesInventory.js'
 export { formSchema, initialValues, parseInput, validateValues, fieldError, sameId, optionValue, chooseable, saveState, recordValues, displayValue, fileLabel, toDbValue, fromDbValue, listColumns, listSource } from './values.js'
 export { screenFromSpec, screensFromSpec, entityNames, SPEC_HEIGHTS, ROW_GAP } from './generate.js'
 export { scaffoldEntity } from './scaffold.js'

package/src/pagesInventory.js

@@ -0,0 +1,91 @@
+// WHICH PAGES WORK EVERYWHERE, AND WHICH ARE WEB ONLY.
+//
+// A page drawn from screen documents (a form's list, a flow's screens, a list
+// fed by a function, a panel of buttons) can be drawn by anything that reads
+// a document — a phone app included. A page written by hand in React cannot:
+// it is the browser's alone.
+//
+// Writing one is allowed. Doing it without anyone knowing is what this file
+// is for. Each app keeps an inventory, ui/pages.json:
+//
+//   {
+//     "routes": ["src/App.jsx"],
+//     "documents": [{ "path": "/orders", "menu": "Orders", "screen": "orders_board" }],
+//     "webOnly":   [{ "path": "/home", "menu": "Home", "reason": "The dashboard's cards are hand-written" }]
+//   }
+//
+// and `xeplr-factory pages` WARNS — it never refuses — about every web-only
+// page, and about every route the inventory does not mention. The menu key
+// lets a settings screen tag that menu item "Web only".
+//
+// Pure: no React, no file system. The CLI reads the files.
+
+/** Whatever is wrong with the inventory itself, as [{ path, message }]. */
+export function checkInventory(inv) {
+  const errors = []
+  const err = (path, message) => errors.push({ path, message })
+  if (!inv || typeof inv !== 'object' || Array.isArray(inv)) { err('', 'must be an object: { routes, documents, webOnly }'); return errors }
+  if (inv.routes !== undefined && !(Array.isArray(inv.routes) && inv.routes.every((r) => typeof r === 'string' && r))) err('routes', 'must be the files that declare the routes, e.g. ["src/App.jsx"]')
+  ;['documents', 'webOnly'].forEach((list) => {
+    if (inv[list] === undefined) return
+    if (!Array.isArray(inv[list])) { err(list, 'must be an array of { path, … }'); return }
+    inv[list].forEach((p, i) => {
+      const at = `${list}[${i}]`
+      if (!p || typeof p !== 'object') { err(at, 'must be { path, … }'); return }
+      if (typeof p.path !== 'string' || !p.path.startsWith('/')) err(`${at}.path`, 'must be a route path, e.g. "/orders/:orderId"')
+      if (p.menu !== undefined && (typeof p.menu !== 'string' || !p.menu)) err(`${at}.menu`, 'must be the menu key it is under, e.g. "Orders"')
+      if (list === 'webOnly' && !(typeof p.reason === 'string' && p.reason.trim())) err(`${at}.reason`, 'is required — say why it is hand-written, so the next person knows what it would take to make it a document')
+    })
+  })
+  const seen = new Map()
+  ;[...(inv.documents || []), ...(inv.webOnly || [])].forEach((p) => {
+    if (!p || typeof p.path !== 'string') return
+    if (seen.has(p.path)) err('', `"${p.path}" is listed twice`)
+    seen.set(p.path, true)
+  })
+  return errors
+}
+
+/**
+ * The route paths a routes file declares: every <Route path="…">, except
+ * redirects (an element that is a <Navigate>) and the catch-all "*".
+ */
+export function routesIn(source) {
+  const out = []
+  const re = /<Route\b[^>]*?\bpath=(?:"([^"]+)"|'([^']+)'|\{\s*["'`]([^"'`]+)["'`]\s*\})[^>]*>/g
+  let m
+  while ((m = re.exec(String(source || '')))) {
+    const path = m[1] || m[2] || m[3]
+    if (!path || path === '*') continue
+    if (/element=\{\s*<Navigate\b/.test(m[0])) continue
+    out.push(path)
+  }
+  return [...new Set(out)]
+}
+
+/**
+ * The warnings for an app: each web-only page, and each route nobody
+ * listed. [{ kind: 'webOnly' | 'unlisted' | 'gone' | 'inventory', path, message }]
+ */
+export function pageWarnings(inv, routes) {
+  const warnings = checkInventory(inv).map((e) => ({ kind: 'inventory', path: e.path, message: `pages.json ${e.path ? e.path + ' ' : ''}${e.message}` }))
+  const docs = new Set(((inv && inv.documents) || []).map((p) => p && p.path))
+  const web = ((inv && inv.webOnly) || []).filter((p) => p && p.path)
+  web.forEach((p) => warnings.push({ kind: 'webOnly', path: p.path, message: `${p.path} is web only — it will not be in a phone app. ${p.reason || ''}`.trim() }))
+  const listed = new Set([...docs, ...web.map((p) => p.path)])
+  ;(routes || []).forEach((r) => {
+    if (!listed.has(r)) warnings.push({ kind: 'unlisted', path: r, message: `${r} is not in pages.json — say whether it is drawn from documents ("documents") or hand-written ("webOnly", with the reason)` })
+  })
+  // A listed page the routes no longer have: the inventory is out of date.
+  if (routes) listed.forEach((p) => { if (!routes.includes(p)) warnings.push({ kind: 'gone', path: p, message: `${p} is in pages.json but no route declares it any more — remove it` }) })
+  return warnings
+}
+
+/** { menu key → why } for the menu items whose page is web only — a settings screen tags them. */
+export function webOnlyMenus(inv) {
+  const out = {}
+  ;((inv && inv.webOnly) || []).forEach((p) => {
+    if (p && p.menu && !out[p.menu]) out[p.menu] = p.reason || 'Hand-written for the browser'
+  })
+  return out
+}

package/src/remote.js

@@ -83,6 +83,10 @@ export function createFactoryApi({ fetch: doFetch, base = '' } = {}) {
   }
   const one = (rows) => (Array.isArray(rows) ? rows[0] : rows)
   const enc = encodeURIComponent
+  const query = (params) => {
+    const pairs = Object.entries(params).filter(([, v]) => v !== undefined && v !== null && v !== '')
+    return pairs.length ? '?' + pairs.map(([k, v]) => `${enc(k)}=${enc(v)}`).join('&') : ''
+  }
 
   const api = {
     // screens
@@ -123,6 +127,16 @@ export function createFactoryApi({ fetch: doFetch, base = '' } = {}) {
     onDelete: ({ id, screen }) => call('POST', `/records/${enc(screen)}/delete`, { id }),
     fetchOptions: ({ table }) => call('GET', `/options/${enc(table)}`),
 
+    // ROWS A FUNCTION WORKS OUT, for a list with rowsFrom: { rows, counts }.
+    // Only what the person typed goes with it — the function is the screen's.
+    fetchRows: async ({ screen, node, q, filter }) => one(await call('GET', `/rows/${enc(screen)}${query({ node, q, filter })}`)),
+    // An activity cell's hover box for one row.
+    fetchRowDetails: ({ screen, node, column, id }) => call('GET', `/rows/${enc(screen)}/details${query({ node, column, id })}`),
+    // A button's press on one record → { button, message, output }. The
+    // server reads the button — its function and parameters — from the
+    // published screen; the request names it and carries the note.
+    pressButton: async ({ screen, button, id, note }) => one(await call('POST', `/buttons/${enc(screen)}/${enc(button)}`, note ? { id, note } : { id })),
+
     // A file field's upload. The answer's `path` is what the record stores;
     // the file itself is read back through the same route, with auth.
     uploadFile: async (file, { screen, field }) => {
@@ -132,11 +146,12 @@ export function createFactoryApi({ fetch: doFetch, base = '' } = {}) {
     },
     fileUrl: (path) => `${base}/factory/files/${String(path).split('/').map(enc).join('/')}`
   }
-  api.screenProps = { loadScreen: api.loadScreen, onSave: api.onSave, fetchRecords: api.fetchRecords, fetchRecord: api.fetchRecord, onDelete: api.onDelete, fetchOptions: api.fetchOptions, uploadFile: api.uploadFile, fileUrl: api.fileUrl }
+  api.screenProps = { loadScreen: api.loadScreen, onSave: api.onSave, fetchRecords: api.fetchRecords, fetchRecord: api.fetchRecord, onDelete: api.onDelete, fetchOptions: api.fetchOptions, uploadFile: api.uploadFile, fileUrl: api.fileUrl,
+    fetchRows: api.fetchRows, fetchRowDetails: api.fetchRowDetails, pressButton: api.pressButton }
   // makeChildTable: a list on a form can make the table it is about to point
   // at — rows belonging to this record — without leaving the designer. A
   // server act, which is why the builder is given it rather than doing it.
-  api.builderProps = { onSave: api.saveDraft, onPublish: api.publish, listTables: api.listTables, fetchOptions: api.fetchOptions, fetchRecords: api.fetchRecords, makeChildTable: function (spec) { return createChildTable(api, spec) },
+  api.builderProps = { onSave: api.saveDraft, onPublish: api.publish, listTables: api.listTables, listFunctions: api.listFunctions, fetchOptions: api.fetchOptions, fetchRecords: api.fetchRecords, makeChildTable: function (spec) { return createChildTable(api, spec) },
     // The builder designs a child table in place, which needs the same calls
     // this api already makes — handed over rather than rebuilt.
     screenApi: api }

package/src/urlState.js

@@ -12,11 +12,11 @@
 
 /**
  * The query keys under a host's `urlKey`, or null (in memory).
- *   factoryUrlKeys('form') → { steps: 'formSteps', selected: 'formSelected', tab: 'formTab' }
+ *   factoryUrlKeys('form') → { steps: 'formSteps', selected: 'formSelected', tab: 'formTab', q: 'formQ', filter: 'formFilter' }
  */
 export function factoryUrlKeys(urlKey) {
   if (!urlKey) return null
-  return { steps: `${urlKey}Steps`, selected: `${urlKey}Selected`, tab: `${urlKey}Tab` }
+  return { steps: `${urlKey}Steps`, selected: `${urlKey}Selected`, tab: `${urlKey}Tab`, q: `${urlKey}Q`, filter: `${urlKey}Filter` }
 }
 
 /**

package/src/useFactoryBuilder.js

@@ -1,4 +1,5 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
+import { useFunctionCatalog } from './useFunctionCatalog.js'
 import { CONTROLS, controlGroups } from './controls.js'
 import {
   createScreen, renameScreen, setScreenProperty, addControl as addControlTo, moveNode, setNodeProperty, setNodeStep,
@@ -28,6 +29,9 @@ import { selectionPlace } from './urlState.js'
  * @param onSave      async (document) → void; called automatically, only with a valid document
  * @param autosaveDelay ms of quiet after the last edit before saving (default 800)
  * @param onChange    (document) → void; every edit, for hosts that autosave or preview
+ * @param listFunctions async () → [{ name, event, description, inputSchema }] — the app's
+ *                    registered functions, offered to a list's "Rows from", a column's
+ *                    hover box and each button (with the parameters it takes)
  * @param listTables  async () → [{ id, name }] | string[]; offered in a dropdown's
  *                    "from a table" picker. Omitted → table sources can still be typed.
  * @param screens     [{ id, name, document? }] — other screens, offered for a list's "Edit in";
@@ -57,7 +61,7 @@ function linkNameFor(doc) {
   return singular.replace(/_([a-z])/g, function (_, c) { return c.toUpperCase() }) + 'Id'
 }
 
-export function useFactoryBuilder({ document: given, name, onSave, onChange, onPublish, listTables, makeChildTable, screens, lockedNames, controls = CONTROLS, autosaveDelay = 800, urlKey } = {}) {
+export function useFactoryBuilder({ document: given, name, onSave, onChange, onPublish, listTables, listFunctions, makeChildTable, screens, lockedNames, controls = CONTROLS, autosaveDelay = 800, urlKey } = {}) {
   const [doc, setDoc] = useState(() => given || createScreen({ name }))
 
   // ── selection ─────────────────────────────────────────────────────────
@@ -139,6 +143,9 @@ export function useFactoryBuilder({ document: given, name, onSave, onChange, onP
     return () => { cancelled = true }
   }, [hasListTables, tableRound])
 
+  // ── the app's functions, for what a list's rows and a button run ──────
+  const functions = useFunctionCatalog({ listFunctions })
+
   // ── edits ─────────────────────────────────────────────────────────────
   const rename = useCallback((value) => update((d) => renameScreen(d, value)), [update])
   /** A screen property by path — `source`, `width`, `style.fontSize`. */
@@ -485,6 +492,7 @@ export function useFactoryBuilder({ document: given, name, onSave, onChange, onP
     removeSelected,
     duplicateSelected,
     tables,
+    functions,
     screens: screens || [],
     lockedNames: lockedNames || [],
     validation,

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, buttonPressed } 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, pressed: buttonPressed(b, buttonRecord), 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', 'pressedWhen', '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', 'pressedWhen'].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