@xeplr/ui-factory 1.8.5 → 1.8.7

package/src/listRange.js

@@ -0,0 +1,85 @@
+// A FUNCTION-FED LIST'S DATE RANGE AND KPI CARDS — the parts of a dashboard.
+//
+//   "dateRange": { "label": "Placed", "default": "last30" },
+//   "kpis": [{ "key": "ordered", "label": "Not started" }, { "key": "open", "label": "Open" }, …]
+//
+// The range is one value, kept in the URL as it was chosen — a preset
+// ("last30") or two days ("2026-10-01..2026-10-31") — and turned into the
+// two days the function is asked for (`from`, `to`, both included) on the day
+// it is asked: "last 30 days" opened tomorrow is tomorrow's last 30 days.
+//
+// A KPI card is a count the function works out for the range, and a filter:
+// clicking one asks for its rows (`kpi`), clicking it again lets go. What
+// each card counts is the function's to decide — the document names them.
+//
+// Pure: no React, no requests.
+
+/** The ranges a person can pick without typing two dates. */
+export const DATE_PRESETS = [
+  { value: 'today', label: 'Today' },
+  { value: 'yesterday', label: 'Yesterday' },
+  { value: 'last7', label: 'Last 7 days' },
+  { value: 'last30', label: 'Last 30 days' },
+  { value: 'thisMonth', label: 'This month' },
+  { value: 'lastMonth', label: 'Last month' },
+  { value: 'all', label: 'All time' }
+]
+
+export const DATE_PRESET_VALUES = DATE_PRESETS.map((p) => p.value)
+
+const DAY = /^\d{4}-\d{2}-\d{2}$/
+
+/** Whether a string is a real day, "YYYY-MM-DD". */
+export function isDay(s) {
+  if (typeof s !== 'string' || !DAY.test(s)) return false
+  const d = new Date(s + 'T00:00:00Z')
+  return !Number.isNaN(d.getTime()) && d.toISOString().slice(0, 10) === s
+}
+
+/** A Date's own calendar day where it is — "YYYY-MM-DD". */
+export function dayOf(date) {
+  const d = date instanceof Date ? date : new Date(date)
+  const pad = (n) => String(n).padStart(2, '0')
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`
+}
+
+function addDays(day, n) {
+  const d = new Date(day + 'T00:00:00Z')
+  d.setUTCDate(d.getUTCDate() + n)
+  return d.toISOString().slice(0, 10)
+}
+
+/**
+ * A range as it is kept → the days it means: { from, to, preset } — from/to
+ * empty for "all time". `today` is "YYYY-MM-DD" (the caller's own day).
+ * Anything unreadable falls back to `fallback` (the list's default), so an old
+ * or mistyped link opens the usual range rather than an error.
+ */
+export function resolveRange(value, today, fallback = 'all') {
+  const v = typeof value === 'string' ? value : ''
+  if (v.includes('..')) {
+    const [from, to] = v.split('..')
+    if ((from === '' || isDay(from)) && (to === '' || isDay(to)) && !(from && to && from > to)) return { from, to, preset: null }
+    return resolveRange(fallback, today, 'all')
+  }
+  const month = today.slice(0, 7)
+  switch (v) {
+    case 'today': return { from: today, to: today, preset: v }
+    case 'yesterday': { const y = addDays(today, -1); return { from: y, to: y, preset: v } }
+    case 'last7': return { from: addDays(today, -6), to: today, preset: v }
+    case 'last30': return { from: addDays(today, -29), to: today, preset: v }
+    case 'thisMonth': return { from: month + '-01', to: today, preset: v }
+    case 'lastMonth': {
+      const firstThis = month + '-01'
+      const lastPrev = addDays(firstThis, -1)
+      return { from: lastPrev.slice(0, 7) + '-01', to: lastPrev, preset: v }
+    }
+    case 'all': return { from: '', to: '', preset: 'all' }
+    default: return v === fallback ? { from: '', to: '', preset: 'all' } : resolveRange(fallback, today, 'all')
+  }
+}
+
+/** Two days typed → how the range is kept. */
+export function customRange(from, to) {
+  return `${from || ''}..${to || ''}`
+}

package/src/model.js

@@ -3,7 +3,7 @@
 //
 //   import { screenFromSpec, validateDocument, formSchema } from '@xeplr/ui-factory/model'
 
-export { CONTROLS, OPTION_ID, OPTION_LABEL, LABEL_VARIANTS, LABEL_PRESETS, LIST_ACTIONS, STYLE_KEYS, SCREEN_STYLE_KEYS, FONT_FAMILIES, LAYOUTS, CHOICE_TYPES, STEP_LIMIT, MULTI_SEPARATOR, FILE_KINDS, MAX_FILE_MB, acceptList, controlGroups, withControls } from './controls.js'
+export { CONTROLS, OPTION_ID, OPTION_LABEL, LABEL_VARIANTS, LABEL_PRESETS, LIST_ACTIONS, STYLE_KEYS, SCREEN_STYLE_KEYS, FONT_FAMILIES, LAYOUTS, CHOICE_TYPES, STEP_LIMIT, MULTI_SEPARATOR, FILE_KINDS, MAX_FILE_MB, IMAGE_EXTENSIONS, FILE_SOURCES, MAX_FILES, isImageFile, filePicker, acceptList, controlGroups, withControls } from './controls.js'
 export {
   DOCUMENT_KIND, DOCUMENT_VERSION, DEFAULT_ASPECT, DEFAULT_WIDTH, MARGIN, GAP,
   createScreen, renameScreen, setScreenProperty, addControl, moveNode, setNodeProperty, getNodeProperty, removeNodes,
@@ -16,12 +16,12 @@ export { validateDocument, assertValidDocument } from './validateDocument.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
+  BUTTON_EVENT, LIST_ROWS_EVENT, ROW_DETAILS_EVENT, BUTTON_VARIANTS, COLUMN_DISPLAYS, BADGE_TONES, NOTE_INPUT, FILES_INPUT, CONDITION_OPERATORS,
+  conditionMet, buttonShown, buttonDisabled, buttonPressed, screenButtons, buttonById, buttonInput, askFile, askFileProblem, askFields, askFieldStart, askFieldValues, ASK_FIELD_TYPES, 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 { formSchema, initialValues, parseInput, validateValues, fieldError, sameId, optionValue, chooseable, saveState, recordValues, displayValue, fileLabel, isMultiFile, toDbValue, fromDbValue, listColumns, listSource } from './values.js'
 export { screenFromSpec, screensFromSpec, entityNames, SPEC_HEIGHTS, ROW_GAP } from './generate.js'
 export { scaffoldEntity } from './scaffold.js'
 export { getAtPath, setAtPath } from './propertyPath.js'
@@ -43,3 +43,5 @@ export {
   addTransition, setTransition, removeTransition, firstStep, reachableSteps, layoutFlow, validateFlow, describeWhen,
   arrowTargets, navigationOf, setNavigation
 } from './flow.js'
+// A function-fed list's date range: presets → days, and what a day is.
+export { DATE_PRESETS, DATE_PRESET_VALUES, resolveRange, customRange, isDay, dayOf } from './listRange.js'

package/src/pages.jsx

@@ -65,6 +65,8 @@ export function FactoryBuilder(props) {
  * @prop fetchRecord  async ({ screen, id }) → record — Edit loads the record fresh
  * @prop onDelete     async ({ id, source, record }) → void
  * @prop onChange     (values) → void
+ * @prop uploadFile   async (file, { screen, field }) → { path } — a file field's upload
+ * @prop readFile     async (path) → Blob — an attached file's bytes, for a picture's preview
  * @prop screens      { id → document } — the screens a list's Edit / New open in a popup
  * @prop loadScreen   async (id) → document — for screens not in `screens`
  * @prop controls     control registry (default: built-ins)
@@ -107,6 +109,7 @@ export function FactoryScreen(props) {
           onDelete={props.onDelete}
           uploadFile={props.uploadFile}
           fileUrl={props.fileUrl}
+          readFile={props.readFile}
           screens={props.screens}
           loadScreen={props.loadScreen}
           controls={props.controls}
@@ -138,6 +141,10 @@ export function FactoryScreen(props) {
               fetchRecord={props.fetchRecord}
               fetchRecords={props.fetchRecords}
               onDelete={props.onDelete}
+              // A file field in the popup uploads like one on the page.
+              uploadFile={props.uploadFile}
+              fileUrl={props.fileUrl}
+              readFile={props.readFile}
               screens={props.screens}
               loadScreen={props.loadScreen}
               controls={props.controls}

package/src/remote.js

@@ -3,7 +3,7 @@
 // in the app's database; this only sends and receives.
 //
 //   import { authFetch } from '@xeplr/ui-account'
-//   const factory = createFactoryApi({ fetch: authFetch })
+//   const factory = createFactoryApi({ fetch: authFetch, fetchFile: authFetchFile })
 //   <FactoryScreen document={screen} {...factory.screenProps} />
 //   <FactoryBuilder document={screen} {...factory.builderProps} lockedNames={…} />
 //
@@ -12,10 +12,13 @@
 /**
  * @param options.fetch  a fetch that adds auth and tenant headers (e.g. @xeplr/ui-account's authFetch)
  * @param options.base   prefix before /factory, if the router is mounted elsewhere (default '')
+ * @param options.fetchFile  (url) → Blob, signed like `fetch` (@xeplr/ui-account's authFetchFile):
+ *                       how an attached picture is read back for its preview. Without it
+ *                       a file field shows names only — an <img> cannot send the token.
  */
 import { createChildTable } from './masters.js'
 
-export function createFactoryApi({ fetch: doFetch, base = '' } = {}) {
+export function createFactoryApi({ fetch: doFetch, fetchFile, base = '' } = {}) {
   if (typeof doFetch !== 'function') throw new Error('createFactoryApi: pass { fetch } — usually authFetch from @xeplr/ui-account')
 
   // Two kinds of fetch are accepted, because both are what apps have:
@@ -129,13 +132,23 @@ export function createFactoryApi({ fetch: doFetch, base = '' } = {}) {
 
     // 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 })}`)),
+    fetchRows: async ({ screen, node, q, filter, kpi, from, to }) => one(await call('GET', `/rows/${enc(screen)}${query({ node, q, filter, kpi, from, to })}`)),
     // 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 })),
+    pressButton: async ({ screen, button, id, note, files, values }) => one(await call('POST', `/buttons/${enc(screen)}/${enc(button)}`, {
+      id, ...(note ? { note } : {}), ...(Array.isArray(files) && files.length ? { files } : {}),
+      ...(values && Object.keys(values).length ? { values } : {})
+    })),
+    // A file a button's ask.file takes, stored before the press; the press
+    // then names it by the path this answers with.
+    uploadButtonFile: async (file, { screen, button }) => {
+      const form = new FormData()
+      form.append('file', file)
+      return one(await send('POST', `/buttons/${enc(screen)}/${enc(button)}/files`, form))
+    },
 
     // 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.
@@ -144,10 +157,12 @@ export function createFactoryApi({ fetch: doFetch, base = '' } = {}) {
       form.append('file', file)
       return one(await send('POST', `/files/${enc(screen)}/${enc(field)}`, form))
     },
-    fileUrl: (path) => `${base}/factory/files/${String(path).split('/').map(enc).join('/')}`
+    fileUrl: (path) => `${base}/factory/files/${String(path).split('/').map(enc).join('/')}`,
+    // An attached file's bytes (a picture's preview), when the host said how.
+    readFile: typeof fetchFile === 'function' ? (path) => fetchFile(api.fileUrl(path)) : undefined
   }
-  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 }
+  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, readFile: api.readFile,
+    fetchRows: api.fetchRows, fetchRowDetails: api.fetchRowDetails, pressButton: api.pressButton, uploadButtonFile: api.uploadButtonFile }
   // 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.

package/src/tableSchema.js

@@ -88,8 +88,10 @@ export function columnForField(node) {
     case 'datetime':
       return { ...base, type: 'timestamp' }
     case 'file':
-      // The stored file's path, as the upload answered with it.
-      return { ...base, type: 'varchar', length: FILE_PATH_LENGTH }
+      // The stored file's path, as the upload answered with it — several of
+      // them, comma separated, in a text column (varchar → text is a widening,
+      // so turning "several files" on keeps what is saved).
+      return p.multiple ? { ...base, type: 'text' } : { ...base, type: 'varchar', length: FILE_PATH_LENGTH }
     case 'multiselect':
       // Every chosen id in one text column, separated by commas.
       return { ...base, type: 'text' }

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', q: 'formQ', filter: 'formFilter' }
+ *   factoryUrlKeys('form') → { steps: 'formSteps', selected: 'formSelected', tab: 'formTab', q: 'formQ', filter: 'formFilter', kpi: 'formKpi', dates: 'formDates' }
  */
 export function factoryUrlKeys(urlKey) {
   if (!urlKey) return null
-  return { steps: `${urlKey}Steps`, selected: `${urlKey}Selected`, tab: `${urlKey}Tab`, q: `${urlKey}Q`, filter: `${urlKey}Filter` }
+  return { steps: `${urlKey}Steps`, selected: `${urlKey}Selected`, tab: `${urlKey}Tab`, q: `${urlKey}Q`, filter: `${urlKey}Filter`, kpi: `${urlKey}Kpi`, dates: `${urlKey}Dates` }
 }
 
 /**

package/src/useFactoryScreen.js

@@ -6,6 +6,7 @@ import { initialValues, parseInput, saveState, fieldError, optionValue, recordVa
 import { hookMethod } from './hooks.js'
 import { useUrlSteps, useUrlListQuery } from './useUrlPlaces.js'
 import { buttonShown, buttonDisabled, buttonPressed } from './buttons.js'
+import { resolveRange, dayOf } from './listRange.js'
 
 // A saved screen, running. No JSX — designs/ScreenSample.jsx draws it.
 //
@@ -59,9 +60,11 @@ import { buttonShown, buttonDisabled, buttonPressed } from './buttons.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 fetchRows     async ({ screen, node, q, filter, kpi, from, to }) → { rows, counts, kpis } — 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 pressButton   async ({ screen, button, id, note, files, values }) → { message } — a button's press, run on the server
+ * @param uploadButtonFile async (file, { screen, button }) → { path } — a file a button's `ask.file` takes, stored before the press
+ * @param readFile      async (path) → Blob — an attached file's bytes: a picture's preview (no preview without it)
  * @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`),
@@ -82,9 +85,9 @@ import { buttonShown, buttonDisabled, buttonPressed } from './buttons.js'
 const SEARCH_PAUSE_MS = 250
 
 export function useFactoryScreen({
-  document: doc, record, recordKey = 'id', onSave, fetchOptions, fetchRecords, fetchRecord, onDelete, onChange, screens, loadScreen, hooks, uploadFile, fileUrl,
+  document: doc, record, recordKey = 'id', onSave, fetchOptions, fetchRecords, fetchRecord, onDelete, onChange, screens, loadScreen, hooks, uploadFile, fileUrl, readFile,
   onOpenRecord, onDone, onDirtyChange, params, urlKey, previous,
-  fetchRows, fetchRowDetails, pressButton, onButtonDone, reloadKey,
+  fetchRows, fetchRowDetails, pressButton, uploadButtonFile, onButtonDone, reloadKey,
   link, onReady,
   controls = CONTROLS
 } = {}) {
@@ -610,6 +613,15 @@ export function useFactoryScreen({
   // rows. The search waits for a pause in typing before it asks.
   const [listQ, setListQ] = useUrlListQuery(urlKey, 'q')
   const [listFilter, setListFilter] = useUrlListQuery(urlKey, 'filter')
+  // A dashboard's KPI card (clicked: its rows) and date range (a preset, or
+  // "from..to"), in the URL too. The range is turned into days when asked.
+  const [listKpi, setListKpi] = useUrlListQuery(urlKey, 'kpi')
+  const [listDates, setListDates] = useUrlListQuery(urlKey, 'dates')
+  const rangeFor = useCallback((node) => {
+    const r = node && node.props && node.props.dateRange
+    if (!r) return null
+    return resolveRange(listDates || r.default || 'all', dayOf(new Date()), r.default || 'all')
+  }, [listDates])
   const [askedQ, setAskedQ] = useState(listQ)
   useEffect(() => {
     if (askedQ === listQ) return undefined
@@ -633,14 +645,21 @@ export function useFactoryScreen({
       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,
+        query: fed ? { q: askedQ, filter: listFilter, kpi: listKpi, ...(rangeFor(node) || {}) } : 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 })
+              const range = rangeFor(node)
+              const kpis = Array.isArray(node.props.kpis) ? node.props.kpis : []
+              return fetchRowsRef.current({
+                screen: doc.id, node: node.id, q: askedQ, filter: listFilter || undefined,
+                kpi: kpis.some((k) => k.key === listKpi) ? listKpi : undefined,
+                from: range && range.from ? range.from : undefined,
+                to: range && range.to ? range.to : 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
@@ -661,15 +680,21 @@ export function useFactoryScreen({
           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 } }))
+          const kpis = out && !Array.isArray(out) && out.kpis ? out.kpis : {}
+          setLists((l) => ({ ...l, [node.id]: { rows, counts, kpis, 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, askedQ, listFilter, reloadKey]) // eslint-disable-line react-hooks/exhaustive-deps
+  }, [listNodes, listVersion, doc, askedQ, listFilter, listKpi, rangeFor, 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])
+  const listQuery = useMemo(() => ({
+    q: listQ, filter: listFilter, setQ: setListQ, setFilter: setListFilter,
+    kpi: listKpi, setKpi: setListKpi,
+    // The range a list shows (its own default until one is chosen), and choosing one.
+    rangeFor, setDates: setListDates
+  }), [listQ, listFilter, setListQ, setListFilter, listKpi, setListKpi, rangeFor, setListDates])
 
   /** An activity cell's hover box: the column's function, for one row. */
   const fetchRowDetailsRef = useRef(fetchRowDetails); fetchRowDetailsRef.current = fetchRowDetails
@@ -830,6 +855,7 @@ export function useFactoryScreen({
   // 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 buttonUploadRef = useRef(uploadButtonFile); buttonUploadRef.current = uploadButtonFile
   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 }
@@ -842,12 +868,20 @@ export function useFactoryScreen({
     pressing,
     note: buttonNote,
     clearNote: () => setButtonNote(null),
-    press: async (b, typed) => {
+    readFile: readFile || null,
+    // A file the button's ask.file takes: stored first, its path sent with the press.
+    upload: async (file, b) => {
+      if (!buttonUploadRef.current) throw new Error('No uploadButtonFile was provided, so this button cannot take a file')
+      const out = await buttonUploadRef.current(file, { screen: doc.id, button: b.id })
+      if (!out || !out.path) throw new Error('The upload did not answer with the stored file')
+      return out
+    },
+    press: async (b, typed, files, values) => {
       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 })
+        const result = await pressRef.current({ screen: doc.id, button: b.id, id: recordId, note: typed, files, values })
         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 })
@@ -859,7 +893,7 @@ export function useFactoryScreen({
         setPressing(null)
       }
     }
-  }), [buttonRecord, pressing, buttonNote, doc, recordId])
+  }), [buttonRecord, pressing, buttonNote, doc, recordId, readFile])
 
   return {
     document: doc,
@@ -889,6 +923,7 @@ export function useFactoryScreen({
     visibleNodes,
     upload,
     fileUrl,
+    readFile: readFile || null,
     flush,
     save: runSave,
     saveNow: runSave,

package/src/useFilePreview.js

@@ -0,0 +1,40 @@
+import { useEffect, useState } from 'react'
+import { isImageFile } from './controls.js'
+
+// A STORED PICTURE, SHOWN. Attachments come back only through the factory's
+// signed route, which an <img src> cannot call — so the bytes are fetched
+// (`readFile`, the host's signed fetch) and shown from a local object URL,
+// released when the path changes or the field goes away. No JSX.
+
+/**
+ * @param path      a stored path, as the upload answered with it
+ * @param readFile  async (path) → Blob, or nothing (then: no preview)
+ * @returns {{ url, failed }} — url is null until loaded, for a non-picture,
+ *          or without readFile
+ */
+export function useFilePreview(path, readFile) {
+  const [state, setState] = useState({ url: null, failed: false })
+  const wanted = Boolean(path && readFile && isImageFile(path))
+
+  useEffect(() => {
+    if (!wanted) { setState({ url: null, failed: false }); return undefined }
+    let gone = false
+    let url = null
+    Promise.resolve()
+      .then(() => readFile(path))
+      .then((blob) => {
+        if (gone) return
+        url = URL.createObjectURL(blob)
+        setState({ url, failed: false })
+      })
+      .catch(() => { if (!gone) setState({ url: null, failed: true }) })
+    return () => {
+      gone = true
+      if (url) URL.revokeObjectURL(url)
+    }
+    // readFile is the host's function; a new one each render must not refetch.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [path, wanted])
+
+  return state
+}

package/src/validateDocument.js

@@ -11,12 +11,13 @@
 // fields writing the same key — looks like a data problem to whoever uses it.
 
 import { SCREEN_EVENT_KEYS, FUNCTION_NAME } from './events.js'
-import { CONTROLS, LABEL_VARIANTS, LIST_ACTIONS, STYLE_KEYS, SCREEN_STYLE_KEYS, LAYOUTS, MULTI_SEPARATOR, MAX_FILE_MB, STEP_LIMIT, acceptList } from './controls.js'
+import { CONTROLS, LABEL_VARIANTS, LIST_ACTIONS, STYLE_KEYS, SCREEN_STYLE_KEYS, LAYOUTS, MULTI_SEPARATOR, MAX_FILE_MB, STEP_LIMIT, acceptList, FILE_SOURCES, IMAGE_EXTENSIONS, MAX_FILES } from './controls.js'
 import { DOCUMENT_KIND, DOCUMENT_VERSION } from './document.js'
+import { DATE_PRESET_VALUES } from './listRange.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'
+import { BUTTON_VARIANTS, COLUMN_DISPLAYS, BADGE_TONES, CONDITION_OPERATORS, ASK_FIELD_TYPES, NOTE_INPUT, FILES_INPUT } from './buttons.js'
 
 const FIELD_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/
 const TABLE_NAME = /^[A-Za-z_][A-Za-z0-9_.$-]*$/
@@ -281,19 +282,44 @@ function checkStep(node, doc, at, err) {
 
 /** A file field: which extensions it takes, and how big a file may be. */
 function checkFile(props, at, err) {
-  if (props.accept !== undefined) {
-    if (typeof props.accept !== 'string') err(`${at}.props.accept`, 'must be a string of extensions, e.g. ".pdf,.docx"')
+  checkFileRules(props, `${at}.props`, err)
+}
+
+/**
+ * A file's rules — a file field's props, or a button's `ask.file`: what it
+ * takes, how large, how many, and from where. `at` is where they sit.
+ */
+function checkFileRules(rules, at, err) {
+  if (rules.accept !== undefined) {
+    if (typeof rules.accept !== 'string') err(`${at}.accept`, 'must be a string of extensions, e.g. ".pdf,.docx"')
     else {
-      const list = acceptList(props.accept)
-      if (!list.length) err(`${at}.props.accept`, 'names no extension — ".pdf,.docx", or leave it out for any file')
+      const list = acceptList(rules.accept)
+      if (!list.length) err(`${at}.accept`, 'names no extension — ".pdf,.docx", or leave it out for any file')
       list.forEach((x) => {
-        if (!EXTENSION.test(x)) err(`${at}.props.accept`, `"${x}" is not an extension — letters and digits after a dot, e.g. ".xlsx"`)
+        if (!EXTENSION.test(x)) err(`${at}.accept`, `"${x}" is not an extension — letters and digits after a dot, e.g. ".xlsx"`)
       })
     }
   }
-  if (props.maxSize !== undefined) {
-    if (!(Number.isFinite(props.maxSize) && props.maxSize > 0 && props.maxSize <= MAX_FILE_MB)) {
-      err(`${at}.props.maxSize`, `must be a number of megabytes from 1 to ${MAX_FILE_MB}`)
+  if (rules.maxSize !== undefined) {
+    if (!(Number.isFinite(rules.maxSize) && rules.maxSize > 0 && rules.maxSize <= MAX_FILE_MB)) {
+      err(`${at}.maxSize`, `must be a number of megabytes from 1 to ${MAX_FILE_MB}`)
+    }
+  }
+  if (rules.multiple !== undefined && typeof rules.multiple !== 'boolean') err(`${at}.multiple`, 'must be true or false')
+  if (rules.maxFiles !== undefined) {
+    if (!(Number.isInteger(rules.maxFiles) && rules.maxFiles >= 1 && rules.maxFiles <= MAX_FILES)) err(`${at}.maxFiles`, `must be a whole number of files from 1 to ${MAX_FILES}`)
+    else if (!rules.multiple) err(`${at}.maxFiles`, 'is for several files — turn on "multiple", or remove it')
+  }
+  if (rules.source !== undefined) {
+    const sources = FILE_SOURCES.map((s) => s.value)
+    if (!sources.includes(rules.source)) err(`${at}.source`, `must be one of: ${sources.join(', ')}`)
+    else if (rules.source === 'camera') {
+      // A camera takes pictures: a field that also takes PDFs could never be
+      // filled the way it says, and one that takes no images at all is wrong.
+      const list = typeof rules.accept === 'string' ? acceptList(rules.accept) : []
+      if (!list.length || list.some((x) => !IMAGE_EXTENSIONS.includes(x))) {
+        err(`${at}.accept`, `a camera takes photos — with "source": "camera", the allowed types must be images only (${IMAGE_EXTENSIONS.join(',')})`)
+      }
     }
   }
 }
@@ -483,6 +509,35 @@ function checkFedList(props, fed, at, err) {
       })
     }
   }
+  need('kpis', 'KPI cards')
+  need('dateRange', 'a date range')
+  if (props.kpis !== undefined) {
+    if (!Array.isArray(props.kpis)) err(`${at}.props.kpis`, 'must be an array of { key, label, tone? }')
+    else {
+      const keys = new Set()
+      props.kpis.forEach((k, j) => {
+        const p = `${at}.props.kpis[${j}]`
+        if (!k || typeof k !== 'object') { err(p, 'must be { key, label, tone? }'); return }
+        if (!(nonEmptyString(k.key) && /^[A-Za-z0-9_-]+$/.test(k.key))) err(`${p}.key`, 'must be letters, digits, _ or - — what the function is asked for, e.g. "open"')
+        else if (keys.has(k.key)) err(`${p}.key`, `"${k.key}" appears twice`)
+        else keys.add(k.key)
+        if (!nonEmptyString(k.label)) err(`${p}.label`, 'must be the card\'s text, e.g. "Open"')
+        if (k.tone !== undefined && !BADGE_TONES.includes(k.tone)) err(`${p}.tone`, `must be one of: ${BADGE_TONES.join(', ')}`)
+        const extra = Object.keys(k).filter((x) => !['key', 'label', 'tone'].includes(x))
+        if (extra.length) err(p, `only "key", "label" and "tone" are used — remove: ${extra.join(', ')}`)
+      })
+    }
+  }
+  if (props.dateRange !== undefined) {
+    const d = props.dateRange
+    if (!d || typeof d !== 'object' || Array.isArray(d)) err(`${at}.props.dateRange`, 'must be { label?, default? } — the range the function is asked for')
+    else {
+      const extra = Object.keys(d).filter((x) => x !== 'label' && x !== 'default')
+      if (extra.length) err(`${at}.props.dateRange`, `only "label" and "default" are used — remove: ${extra.join(', ')}`)
+      if (d.label !== undefined && typeof d.label !== 'string') err(`${at}.props.dateRange.label`, 'must be a string, e.g. "Placed"')
+      if (d.default !== undefined && !DATE_PRESET_VALUES.includes(d.default)) err(`${at}.props.dateRange.default`, `must be one of: ${DATE_PRESET_VALUES.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')
   }
@@ -524,12 +579,55 @@ function checkFedColumn(c, p, err) {
 
 const BUTTON_KEYS = ['id', 'label', 'action', 'params', 'ask', 'when', 'disabledWhen', 'pressedWhen', 'variant']
 const ASK_KEYS = ['title', 'message', 'note']
+// A button's `ask.file`: the file a press takes — a file field's rules, plus its label and required.
+const ASK_FILE_KEYS = ['label', 'required', 'accept', 'maxSize', 'multiple', 'maxFiles', 'source']
 
 /**
  * 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.
  */
+const ASK_FIELD_KEYS = ['name', 'label', 'type', 'unit', 'required', 'min', 'max', 'fill']
+
+/** A button's `ask.fields`: the values a press asks for, each reaching the function under its name. */
+function checkAskFields(fields, params, at, err) {
+  if (!Array.isArray(fields)) { err(at, 'must be a list of { name, label, type, unit?, required?, min?, max?, fill? }'); return }
+  const seen = new Set()
+  fields.forEach((f, i) => {
+    const p = `${at}[${i}]`
+    if (!f || typeof f !== 'object' || Array.isArray(f)) { err(p, 'must be { name, label, type, … }'); return }
+    const bad = Object.keys(f).filter((k) => !ASK_FIELD_KEYS.includes(k))
+    if (bad.length) err(p, `only ${ASK_FIELD_KEYS.map((k) => `"${k}"`).join(', ')} are used — remove: ${bad.join(', ')}`)
+    if (!(nonEmptyString(f.name) && /^[A-Za-z][A-Za-z0-9_]{0,62}$/.test(f.name))) err(`${p}.name`, 'must be letters, digits or _ — what the function receives it as, e.g. "lengthIn"')
+    else if (seen.has(f.name)) err(`${p}.name`, `"${f.name}" is asked twice`)
+    else if (f.name === NOTE_INPUT || f.name === FILES_INPUT) err(`${p}.name`, `"${f.name}" is the note's or the files' own name — use ask.note or ask.file`)
+    else if (params && Object.prototype.hasOwnProperty.call(params, f.name)) err(`${p}.name`, `"${f.name}" is already one of the button's parameters — the screen gives it, so nobody should be asked`)
+    else seen.add(f.name)
+    if (!nonEmptyString(f.label)) err(`${p}.label`, 'must be what the person sees, e.g. "Length"')
+    if (!ASK_FIELD_TYPES.includes(f.type)) err(`${p}.type`, `must be one of: ${ASK_FIELD_TYPES.join(', ')}`)
+    if (f.unit !== undefined && !(typeof f.unit === 'string' && f.unit.length <= 12)) err(`${p}.unit`, 'must be a short text, e.g. "in" or "kg"')
+    if (f.required !== undefined && typeof f.required !== 'boolean') err(`${p}.required`, 'must be true or false')
+    ;['min', 'max'].forEach((k) => {
+      if (f[k] === undefined) return
+      if (f.type !== 'number') err(`${p}.${k}`, 'is for a number field')
+      else if (!Number.isFinite(f[k])) err(`${p}.${k}`, 'must be a number')
+    })
+    if (Number.isFinite(f.min) && Number.isFinite(f.max) && f.min > f.max) err(`${p}.min`, 'is more than max')
+    if (f.fill !== undefined && !(nonEmptyString(f.fill) && /^[A-Za-z_][A-Za-z0-9_]*$/.test(f.fill))) err(`${p}.fill`, 'must be a field of the record, e.g. "parcelLengthIn"')
+  })
+}
+
+function checkAskFile(f, at, err) {
+  if (!f || typeof f !== 'object' || Array.isArray(f)) { err(at, 'must be { label?, accept, maxSize?, multiple?, maxFiles?, source?, required? } — the file a press takes'); return }
+  const bad = Object.keys(f).filter((k) => !ASK_FILE_KEYS.includes(k))
+  if (bad.length) err(at, `only ${ASK_FILE_KEYS.map((k) => `"${k}"`).join(', ')} are used — remove: ${bad.join(', ')}`)
+  if (f.label !== undefined && typeof f.label !== 'string') err(`${at}.label`, 'must be a string')
+  if (f.required !== undefined && typeof f.required !== 'boolean') err(`${at}.required`, 'must be true or false')
+  // The server checks an upload against these, so there must be something to check.
+  if (f.accept === undefined) err(`${at}.accept`, 'is required — the extensions it takes, e.g. ".png,.jpg,.jpeg" (the server refuses anything else)')
+  checkFileRules(f, at, err)
+}
+
 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 }
@@ -553,9 +651,11 @@ function checkButtons(props, at, err, ids) {
     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(', ')}`)
+        const bad = Object.keys(b.ask).filter((k) => !ASK_KEYS.includes(k) && k !== 'file' && k !== 'fields')
+        if (bad.length) err(`${p}.ask`, `only ${[...ASK_KEYS, 'file', 'fields'].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.ask.file !== undefined) checkAskFile(b.ask.file, `${p}.ask.file`, err)
+        if (b.ask.fields !== undefined) checkAskFields(b.ask.fields, b.params, `${p}.ask.fields`, err)
       }
     }
     if (b.variant !== undefined && !BUTTON_VARIANTS.includes(b.variant)) err(`${p}.variant`, `must be one of: ${BUTTON_VARIANTS.join(', ')}`)