@xeplr/ui-factory 1.8.5 → 1.8.7

package/AUTHORING.md

@@ -241,7 +241,9 @@ A button is **a registered function and its parameters** — never code. Several
 ] } }
 ```
 
-Register the function with `event: 'button'` and an `inputSchema` (with `options` for the values allowed, and a `note` input if a button asks for one). `when` / `disabledWhen` are `@xeplr/rules` rules on the record. Publishing refuses parameters the function does not take. See the README's "Buttons".
+A button that needs values typed first (a parcel's size before Packed) gets `ask.fields` — `[{ name, label, type: "number" | "text", unit, required, min, max, fill }]` — and its function takes each `name`. A list with KPI cards over it gets `kpis: [{ key, label, tone? }]` and `dateRange: { label, default: "last30" }`; its `listRows` function returns `kpis: { key: count }` and reads `ctx.query.kpi`, `from`, `to`.
+
+Register the function with `event: 'button'` and an `inputSchema` (with `options` for the values allowed, a `note` input if a button asks for one, and a `files` input if its `ask.file` takes photos or documents — `{ "accept": ".png,.jpg,.jpeg", "multiple": true, "source": "any" }`, the same rules as a file field). `when` / `disabledWhen` are `@xeplr/rules` rules on the record. Publishing refuses parameters the function does not take. See the README's "Buttons".
 
 ## When the document cannot say it
 
@@ -292,6 +294,8 @@ Rules you give merge over the ready-made ones (`"validation": { "max": 120 }`).
 | one of the app's records | `dropdown` with `table` |
 | several of a set — tags, skills, days | `multiselect` |
 | a document, a contract, a spreadsheet, a photo | `file` with `accept` (`".pdf,.docx"`) |
+| several photos, several documents | `file` with `multiple: true` (and `maxFiles`) — the value is a list of paths |
+| a photo taken now, at the door / on site | `file` with `source: "camera"` and images in `accept` — the phone opens its camera |
 | a section title between groups | `{ "type": "label", "text": "…", "variant": "subheading" }` |
 | a long form people work through in stages | a `stepper`, then `step` on each field |
 

package/README.md

@@ -103,6 +103,7 @@ import { FactoryScreen } from '@xeplr/ui-factory'
   onDelete={async ({ id, source }) => api.remove(source, id)}
   fetchOptions={async ({ table }) => api.options(table)}
   uploadFile={async (file, { screen, field }) => api.upload(file, screen, field)}  // a file field: → { path }
+  readFile={async (path) => api.fileBlob(path)}       // optional: a stored picture's bytes, for its thumbnail
   screens={{ employee_edit: editScreen }}             // what a list's Edit / New open in a popup
 />
 ```
@@ -115,7 +116,7 @@ import { FactoryScreen } from '@xeplr/ui-factory'
 
 If `onSave` throws an error with `fields: [{ field, message }]` (what `createFactoryApi` does with the server's 422 — a rule, or a hook's `reject`), each message shows on its field until that field is changed.
 
-Values arrive typed: numbers as numbers, checkboxes as booleans, dates as `"YYYY-MM-DD"`, a date and time as `"YYYY-MM-DDTHH:MM"`, a dropdown or radio group as the option's own `id` (a table's numeric id stays a number), a multi-select as an **array** of ids, and a file as the stored file's **path**.
+Values arrive typed: numbers as numbers, checkboxes as booleans, dates as `"YYYY-MM-DD"`, a date and time as `"YYYY-MM-DDTHH:MM"`, a dropdown or radio group as the option's own `id` (a table's numeric id stays a number), a multi-select as an **array** of ids, and a file as the stored file's **path** (a field with `multiple`: an **array** of paths).
 
 ### On a phone
 
@@ -143,7 +144,10 @@ one scalar have a rule of their own:
   the server use them, so it is written once.
 * **File** — the column holds the path the upload answered with, not the file.
   The file itself is stored by `@xeplr/factory` and read back through its
-  authenticated route; nothing is ever served without a check.
+  authenticated route; nothing is ever served without a check. A field with
+  `multiple` keeps its paths in one `text` column, joined by commas, like a
+  multi-select (a stored path has no comma in it); turning `multiple` on is a
+  widening, so a path already saved reads back as a list of one.
 * **Date and time** — a `timestamp` column, read back as text so no timezone can
   move the moment. A `date` column may be widened to `timestamp` on publish
   (the day becomes midnight); the reverse is refused, as it would lose the time.
@@ -430,7 +434,7 @@ actions.register({
 | `label` | the button's text |
 | `action` | the registered function (event `button`) |
 | `params` | the values it is given — plain values, checked against its `inputSchema` (`options` = the values allowed) at publish |
-| `ask` | asked first: `title`, `message`, and `note` — the label of a note box, whose text reaches the function as `note` (it must take one) |
+| `ask` | asked first: `title`, `message`, `note` — the label of a note box, whose text reaches the function as `note` (it must take one) — `fields` (values to type, below) and `file` (photos or documents, below) |
 | `when` | shown only when every rule matches the record |
 | `disabledWhen` | greyed out when every rule matches |
 | `pressedWhen` | drawn as the **current choice** (filled, `aria-pressed`) when every rule matches — the status an order is at. Give it the same rules as `disabledWhen` when choosing it again would change nothing |
@@ -443,6 +447,76 @@ Rules are [`@xeplr/rules`](https://www.npmjs.com/package/@xeplr/rules) rules —
 - **What happens next is the host's.** The panel shows the function's `message`; `onButtonDone({ button, result, record })` lets the page reload what it shows. Lists on the same screen reload by themselves.
 - **In the builder**, picking a function lists the parameters it takes — a dropdown where it names the values allowed — so nobody types a status by hand. Functions come from `listFunctions` (`createFactoryApi`'s `builderProps` has it).
 
+### A button that asks for values — `ask.fields`
+
+Packed asks for the parcel's size, for the courier:
+
+```json
+{ "id": "packed", "label": "Packed", "action": "setOrderStatus", "params": { "status": "packed" },
+  "ask": { "title": "Change status to “Packed”?", "fields": [
+    { "name": "lengthIn", "label": "Length", "type": "number", "unit": "in", "required": true, "min": 0.1, "fill": "parcelLengthIn" },
+    { "name": "weightKg", "label": "Weight", "type": "number", "unit": "kg", "required": true, "min": 0.01, "fill": "parcelWeightKg" }
+  ] } }
+```
+
+| field key | |
+|---|---|
+| `name` | what the function receives it as — one of its `inputSchema` inputs, never one of the button's `params`, `note` or `files` |
+| `label`, `unit` | what the person sees: "Length", "in" |
+| `type` | `number` (a number keyboard on a phone; the value arrives as a number) or `text` |
+| `required`, `min`, `max` | checked in the dialog **and on the server**, by the same `askFieldValues` |
+| `fill` | a field of the record the dialog starts from — asked again, it shows what was given last time |
+
+- The press sends them as `values`; the server checks them against the **published** button and hands them to the function with its `params` — which always win, so a value typed cannot change what the screen says the button does.
+- Publishing refuses a field the function does not take, or takes as another type. A required input the button asks for is not "missing" from its `params`.
+- In the builder: **Asks for** under the button's Ask first, listing the function's inputs the button does not already give.
+
+### A button that takes files — `ask.file`
+
+A press can carry photos or documents: the button's `ask` gets a file picker,
+with a file field's own rules.
+
+```json
+{ "id": "proof", "label": "Delivered", "action": "markDelivered", "params": { "status": "delivered" },
+  "ask": { "title": "Proof of delivery", "note": "Note (optional)",
+           "file": { "label": "Photos", "accept": ".png,.jpg,.jpeg", "maxSize": 10, "multiple": true, "maxFiles": 5, "source": "any", "required": true } } }
+```
+
+```js
+actions.register({
+  name: 'markDelivered', event: 'button',
+  inputSchema: [{ name: 'status', type: 'string', required: true }, { name: 'files', type: 'array' }, { name: 'note', type: 'string' }],
+  execute: async ({ input, system }) => {
+    // input.files: the stored paths. system.files: [{ path, name, size, fullPath }] — read the bytes from fullPath.
+  }
+})
+```
+
+- **Each file is stored before the press** — `POST /factory/buttons/:screen/:button/files`, checked against `ask.file`'s `accept` and `maxSize` — and the press sends the stored paths as `files`.
+- **The server takes only files stored for this button, by this person, in this company** — a path typed by hand, or another button's, is refused. It also checks `required`, `multiple` and `maxFiles` again.
+- `accept` is required: the server must have something to check an upload against.
+- The function must take `files` (in its `inputSchema`); publishing refuses a button whose function does not. The builder shows the file settings only for a function that does.
+- Host: pass `uploadButtonFile` (`createFactoryApi`'s `screenProps` has it).
+
+## Files: gallery, camera, several
+
+A file field — and a button's `ask.file` — says **what** it wants; the device
+decides how to get it. The same document works in a desktop browser, a phone
+browser, an installed web app and, later, a phone app.
+
+| prop | |
+|---|---|
+| `accept` | the extensions it takes — the server refuses anything else |
+| `maxSize` | megabytes, per file |
+| `source` | `any` (default): the device's own picker — on a phone, one menu of **Camera, Photos and Files**. `camera`: the camera opens straight away, for a photo taken now (`capture="environment"`); `accept` must then be images only |
+| `multiple` | holds several files — the value is an array of paths |
+| `maxFiles` | with `multiple`: at most this many (up to 20) |
+
+- **Pictures show as thumbnails.** An `<img>` cannot send the sign-in token, so a stored picture is read back through `readFile(path) → Blob` and shown from an object URL. `createFactoryApi({ fetch: authFetch, fetchFile: authFetchFile })` (both from `@xeplr/ui-account`) gives `screenProps.readFile`; without it a field shows names only.
+- **Several files**: chosen together, they upload one by one and each is added as it lands, so a refusal of the third keeps the first two. Remove takes one away.
+- `filePicker(props)` → `{ accept, multiple, capture }` is the one place that turns these props into a picker — a phone app's renderer reads the same.
+- iPhone photos are HEIC. iOS hands a photo over as JPEG when the picker does not ask for HEIC, so `.heic` is not in the Images list — not yet checked on a real iPhone.
+
 ## A list whose rows a function works out — `rowsFrom`
 
 A list reads one table's records. When the rows are **worked out** — an
@@ -467,9 +541,10 @@ filter chips and the count on each:
 
 ```js
 actions.register({ name: 'orderList', event: 'listRows', execute: async (ctx) => {
-  // ctx.query = { q, filter } — what was typed, and the chip (always one of the list's own)
+  // ctx.query = { q, filter, kpi, from, to } — what was typed, the chip (always one of the list's own),
+  //   the KPI card clicked (one of the list's own, or ''), and the date range's days ('YYYY-MM-DD', '' = open)
   // ctx.user, ctx.tenant, ctx.db(table), ctx.knex
-  return { rows: [...], counts: { all: 41, packed: 6 } }
+  return { rows: [...], counts: { all: 41, packed: 6 }, kpis: { ordered: 5, open: 12, delivered: 30, total: 47 } }
 } })
 actions.register({ name: 'orderActivity', event: 'rowDetails', execute: async (ctx) =>
   // ctx.id — the row; ctx.column
@@ -488,11 +563,18 @@ actions.register({ name: 'orderActivity', event: 'rowDetails', execute: async (c
 | `sortable` | `false` for a column whose header should not sort |
 
 - **The search and the chip live in the URL** under the screen's `urlKey` (`<urlKey>Q`, `<urlKey>Filter`), so a refresh shows the same rows. The search waits for a pause in typing.
+- **A dashboard over the rows** — `dateRange` and `kpis`:
+  ```json
+  "dateRange": { "label": "Placed", "default": "last30" },
+  "kpis": [{ "key": "ordered", "label": "Not started", "tone": "warning" }, { "key": "open", "label": "Open" },
+           { "key": "delivered", "label": "Delivered", "tone": "success" }, { "key": "total", "label": "Total orders", "tone": "muted" }]
+  ```
+  A From–To range (presets: `today`, `yesterday`, `last7`, `last30`, `thisMonth`, `lastMonth`, `all`, or two days typed) and a card per KPI showing the count the function returned in `kpis`. **Clicking a card shows its rows** (`ctx.query.kpi`); clicking it again lets go. The range and the card live in the URL (`<urlKey>Dates` — `last30` or `2026-10-01..2026-10-31` — and `<urlKey>Kpi`), and a preset is turned into days on the day it is asked, so "last 30 days" stays the last 30 days. What a card counts, and which date the range is about, are the function's to decide; every count should be for the range. On a phone the cards are two to a row. Both need `rowsFrom`.
 - **`refreshEvery`** (seconds, 10–3600) asks again — for text that changes with time. **`reloadKey`** on `<FactoryScreen>` reloads every list when it changes (the host heard something happen).
 - **`grow`** (a list that is its screen's **one** control) lets the page grow with the rows on a desktop, instead of the list scrolling inside the box it was placed in — a full-page list like Orders. Phones always flow.
 - **`rowOpen`** makes a click anywhere on a row open it (the first cell is also a button, for the keyboard); **`highlight`** marks rows whose field is true.
 - **Rows that are worked out are not a table's records**: no Delete, and Edit / New only with an `editScreen`.
-- Routes: `GET /factory/rows/:screen` (`?node=&q=&filter=`) and `/factory/rows/:screen/details` (`?node=&column=&id=`) — see `@xeplr/factory`.
+- Routes: `GET /factory/rows/:screen` (`?node=&q=&filter=&kpi=&from=&to=`) and `/factory/rows/:screen/details` (`?node=&column=&id=`) — see `@xeplr/factory`.
 
 ## Web-only pages — `ui/pages.json`
 
@@ -786,7 +868,7 @@ Both walk someone through something, and they answer different questions:
 | `dropdown` | option id | — |
 | `radio` | option id | — |
 | `multiselect` | array of option ids | `minItems`, `maxItems` |
-| `file` | the stored file's path | `accept` (extensions), `maxSize` (MB) |
+| `file` | the stored file's path — or, with `multiple`, an array of them | `accept` (extensions), `maxSize` (MB), `multiple`, `maxFiles`, `source` (`any` / `camera`); see [Files: gallery, camera, several](#files-gallery-camera-several) |
 | `stepper` | — | a journey across the top; every other control says which step it is on |
 | `label` | — | text with a heading, subheading or text preset |
 | `list` | — | saved records, with New / Edit / Delete — or rows a function works out (`rowsFrom`), with search, filter chips and counts; see above |
@@ -1030,21 +1112,23 @@ src/
   hooks.js               ─ FactoryHooks: get / save / delete / actions — extend and call super
   presets.js             ─ ready-made fields (Email, Age, Gender…), changing a field's kind, label suggestions
   tableSchema.js         ─ a form → its table; the publish plan (create / add / widen / confirmed drops and conversions)
-  remote.js              ─ createFactoryApi({ fetch }): the calls to @xeplr/factory's routes — fetch may be window.fetch or @xeplr/ui-account's authFetch (which returns parsed bodies); includes createEntity({ key, label })
+  remote.js              ─ createFactoryApi({ fetch, fetchFile }): the calls to @xeplr/factory's routes — fetch may be window.fetch or @xeplr/ui-account's authFetch (which returns parsed bodies); includes createEntity({ key, label })
   screenSource.js        ─ this app's screens as another designer wants them: describeScreen, loadScreens, keyFromName, editScreenOf (React-free)
   model.js               ─ everything above, React-free
   useFactoryBuilder.js   ─ builder controller
   useFactoryScreen.js    ─ screen controller
   useFlowBuilder.js      ─ flow designer controller
-  buttons.js             ─ buttons and function-fed lists: conditions, what a press sends, functionProblems' checks (React-free)
+  buttons.js             ─ buttons and function-fed lists: conditions, what a press sends, asked values (askFieldValues), functionProblems' checks (React-free)
+  listRange.js           ─ a list's date range: presets → days (resolveRange) (React-free)
   pagesInventory.js      ─ ui/pages.json: routesIn, pageWarnings, webOnlyMenus (React-free)
   urlState.js            ─ the URL keys and values for selection and steps (React-free)
   useUrlPlaces.js        ─ useUrlSteps, useUrlSelection: those places, in the URL or in memory
   useScreenSource.js     ─ { screens, screenEditor } for @xeplr/ui-workflow's Screen step
-  designs/               ─ BuilderSample, ScreenSample, ScreenEditorSample, ControlView, ListView, FedList, ButtonsView, Palette, PropertyPanel, styles.js, factory.css
+  useFilePreview.js      ─ a stored picture as an object URL, through readFile
+  designs/               ─ BuilderSample, ScreenSample, ScreenEditorSample, ControlView, ListView, FedList, ButtonsView, FileField, Palette, PropertyPanel, styles.js, factory.css
   pages.jsx              ─ FactoryBuilder, FactoryScreen
 bin/xeplr-factory.js     ─ screens / generate / validate / controls / schema / pages
-examples/                ─ employee.entity.json and what `screens` makes of it; orders-board and order-actions (a function-fed list, buttons)
+examples/                ─ employee.entity.json and what `screens` makes of it; orders-board and order-actions (a function-fed list, buttons — one takes photos); delivery-photos (several pictures, camera only)
 dev/                     ─ the stand-in app for `npm run dev` (not published)
 ```
 
@@ -1054,7 +1138,7 @@ dev/                     ─ the stand-in app for `npm run dev` (not published)
 npm test
 ```
 
-`test/buttons.test.js` covers buttons and function-fed lists in the document: what the checker refuses, when a button shows or is greyed out, what a press sends (the document's parameters, never the request's), and `functionProblems` against a registry. `test/cli.test.js` includes `pages`.
+`test/buttons.test.js` covers buttons and function-fed lists in the document: what the checker refuses, when a button shows or is greyed out, what a press sends (the document's parameters, never the request's), and `functionProblems` against a registry. `test/cli.test.js` includes `pages`. `test/dashboard.test.js` covers a list's date range and KPI cards, and a button that asks for values. `test/files.test.js` covers files: several in one field (the value, its column, its checks), camera only, and a button whose press takes files.
 
 `test/urlState.test.js` covers the URL state: the key format, and the three controllers reading their places back from a real `MemoryRouter` and being clicked through in memory, rendered with `react-dom/server`.
 
@@ -1063,7 +1147,7 @@ npx playwright install chromium-headless-shell   # once
 npm run test:phone
 ```
 
-`test/phone.check.js` opens the dev app (`dev/`) in a real browser at 360, 390 and 430px wide and holds every screen to the phone rules: the page never scrolls sideways; fields are one per row, full width, in reading order, none overlapping; inputs are 16px or larger and 44px tall; the footer's buttons are 44px and on screen; a list's row buttons are on screen without scrolling the table; a popup fills the screen. At 1280px it checks that the designed layout is untouched. On the Orders page it checks the function-fed list and buttons at phone sizes (16px / 44px search, chips on screen, an "ask first" that fills the screen) and, at 1280px, that they work: search and chips narrow the rows and the counts, the hover box lists entries, a row opens, a press with a note changes the order and greys its button out, and Confirm COD gives way to Undo. It is not part of `npm test` — it needs a browser and starts a dev server — so run it before releasing anything that changes how a screen is drawn. The list checks use the `@xeplr/ui-table` installed here.
+`test/phone.check.js` opens the dev app (`dev/`) in a real browser at 360, 390 and 430px wide and holds every screen to the phone rules: the page never scrolls sideways; fields are one per row, full width, in reading order, none overlapping; inputs are 16px or larger and 44px tall; the footer's buttons are 44px and on screen; a list's row buttons are on screen without scrolling the table; a popup fills the screen. At 1280px it checks that the designed layout is untouched. On the Orders page it checks the function-fed list and buttons at phone sizes (16px / 44px search, chips on screen, an "ask first" that fills the screen) and, at 1280px, that they work: search and chips narrow the rows and the counts, the hover box lists entries, a row opens, a press with a note changes the order and greys its button out, and Confirm COD gives way to Undo. It checks the dashboard (KPI cards two to a row on a phone, a card showing its rows and letting go, a range narrowing the counts) and Packed asking for the parcel's size (nothing sent without it, numbers reaching the function). On the Photos page it checks the pickers (several images; the back camera for camera only), the thumbnails, Remove, and a button whose press takes a photo end to end. It is not part of `npm test` — it needs a browser and starts a dev server — so run it before releasing anything that changes how a screen is drawn. The list checks use the `@xeplr/ui-table` installed here.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xeplr/ui-factory",
-  "version": "1.8.5",
+  "version": "1.8.7",
   "description": "Design data-entry screens on @xeplr/ui-canvas, save them as JSON, run them as auto-saving forms with lists of saved records — built for Claude to draft and people to refine",
   "type": "module",
   "main": "src/index.js",

package/src/buttons.js

@@ -46,6 +46,13 @@ export const BADGE_TONES = ['accent', 'success', 'warning', 'danger', 'muted']
 /** The name a button's note reaches its function under. */
 export const NOTE_INPUT = 'note'
 
+/**
+ * The name a button's files reach its function under: the stored paths, as a
+ * list, when the button's `ask.file` takes them. The function reads the bytes
+ * through `system.files` (each with its full path on disk).
+ */
+export const FILES_INPUT = 'files'
+
 /** Operators a button's condition can use: every one that compares a single value. */
 export const CONDITION_OPERATORS = OPERATORS.filter((o) => !o.needsRows)
 
@@ -89,15 +96,101 @@ export function buttonById(doc, id) {
   return screenButtons(doc).find((b) => b.button && b.button.id === id) || null
 }
 
-/** What a press sends the function: the document's parameters, and the person's note when it asks for one. */
-export function buttonInput(button, note) {
-  const input = { ...((button && button.params) || {}) }
+/** The file a button's press takes (`ask.file`), or null when it takes none. */
+export function askFile(button) {
+  const f = button && button.ask && button.ask.file
+  return f && typeof f === 'object' ? f : null
+}
+
+/**
+ * What a press sends the function: the document's parameters, the person's
+ * note when it asks for one, the stored files when it takes them, and the
+ * values its `ask.fields` asked for (already checked: askFieldValues).
+ */
+export function buttonInput(button, note, files, values) {
+  // The person's answers first: the document's own parameters always win.
+  const input = { ...((values && typeof values === 'object') ? values : {}), ...((button && button.params) || {}) }
   if (button && button.ask && button.ask.note && note !== undefined && note !== null && String(note).trim() !== '') {
     input[NOTE_INPUT] = String(note).trim()
   }
+  if (askFile(button) && Array.isArray(files) && files.length) input[FILES_INPUT] = files.slice()
   return input
 }
 
+/** The kinds of value a button's `ask.fields` can ask for. */
+export const ASK_FIELD_TYPES = ['number', 'text']
+
+/** Longest text an ask field takes. */
+export const MAX_ASK_TEXT = 500
+
+/**
+ * The values a button's press asks the person for (`ask.fields`) — a parcel's
+ * length, width, height and weight before Packed:
+ *
+ *   "ask": { "fields": [
+ *     { "name": "lengthIn", "label": "Length", "type": "number", "unit": "in", "required": true, "min": 0.1, "fill": "parcelLengthIn" } ] }
+ *
+ * Each reaches the function under its `name`, which its inputSchema must take.
+ * `fill` names a field of the record the dialog starts from, so asking again
+ * shows what was given last time.
+ */
+export function askFields(button) {
+  const f = button && button.ask && button.ask.fields
+  return Array.isArray(f) ? f.filter((x) => x && typeof x === 'object' && x.name) : []
+}
+
+/** What the dialog starts each field with: the record's `fill` field, or empty. */
+export function askFieldStart(field, record) {
+  const v = field.fill && record ? record[field.fill] : undefined
+  return v === undefined || v === null ? '' : String(v)
+}
+
+/**
+ * The values given for a button's `ask.fields`, checked and typed:
+ * { values: { name: value }, errors: [{ field, message }] }. Typed text is
+ * what both sides receive — "12.5" from a box — and a number field's value is
+ * a number. Anything not asked for is dropped. Both the dialog and the server
+ * use it, so a value refused in one is refused in the other.
+ */
+export function askFieldValues(button, given) {
+  const values = {}
+  const errors = []
+  const raw = given && typeof given === 'object' && !Array.isArray(given) ? given : {}
+  askFields(button).forEach((f) => {
+    const label = f.label || f.name
+    const v = raw[f.name]
+    const empty = v === undefined || v === null || String(v).trim() === ''
+    if (empty) {
+      if (f.required) errors.push({ field: f.name, message: `${label} is required` })
+      return
+    }
+    if (f.type === 'number') {
+      const n = typeof v === 'number' ? v : Number(String(v).trim())
+      if (!Number.isFinite(n)) { errors.push({ field: f.name, message: `${label} must be a number` }); return }
+      if (f.min !== undefined && n < f.min) { errors.push({ field: f.name, message: `${label} must be at least ${f.min}` }); return }
+      if (f.max !== undefined && n > f.max) { errors.push({ field: f.name, message: `${label} must be at most ${f.max}` }); return }
+      values[f.name] = n
+      return
+    }
+    const t = String(v).trim()
+    if (t.length > MAX_ASK_TEXT) { errors.push({ field: f.name, message: `${label} can be at most ${MAX_ASK_TEXT} characters` }); return }
+    values[f.name] = t
+  })
+  return { values, errors }
+}
+
+/** Why the files given to a press are not what its `ask.file` takes — or null. */
+export function askFileProblem(button, files) {
+  const f = askFile(button)
+  const list = Array.isArray(files) ? files : []
+  if (!f) return list.length ? 'This button takes no files' : null
+  const label = f.label || 'A file'
+  if (!list.length) return f.required ? `${label} is required` : null
+  if (!f.multiple && list.length > 1) return `${label}: one file only`
+  if (f.multiple && f.maxFiles && list.length > f.maxFiles) return `${label}: at most ${f.maxFiles} files`
+  return null
+}
+
 /**
  * The functions a screen's CONTROLS name, as [{ event, name, at }] — a list's
  * rows, a column's hover box, each button. `at` is where in the document, so
@@ -141,9 +234,18 @@ export function paramProblems(button, inputSchema) {
   schema.forEach((f) => {
     if (!f || !f.name || !f.required || f.default !== undefined) return
     if (f.name === NOTE_INPUT && button && button.ask && button.ask.note) return
+    if (f.name === FILES_INPUT && askFile(button)) return
+    if (askFields(button).some((a) => a.name === f.name && a.required)) return
     if (params[f.name] === undefined || params[f.name] === null || params[f.name] === '') problems.push(`needs "${f.name}"`)
   })
   if (button && button.ask && button.ask.note && !byName.has(NOTE_INPUT)) problems.push(`asks for a note, but takes no "${NOTE_INPUT}"`)
+  if (askFile(button) && !byName.has(FILES_INPUT)) problems.push(`asks for a file, but takes no "${FILES_INPUT}"`)
+  askFields(button).forEach((a) => {
+    const f = byName.get(a.name)
+    if (!f) { problems.push(`asks for "${a.name}", but takes no "${a.name}"`); return }
+    const want = a.type === 'number' ? 'number' : 'string'
+    if (f.type && f.type !== want) problems.push(`asks for "${a.name}" as ${a.type === 'number' ? 'a number' : 'text'}, but it takes ${f.type}`)
+  })
   return problems
 }
 

package/src/controls.js

@@ -12,6 +12,8 @@
 // (width × the screen's aspect). See document.js.
 
 /** A dropdown binds `id` and shows `name` — always. */
+import { DATE_PRESETS } from './listRange.js'
+
 export const OPTION_ID = 'id'
 export const OPTION_LABEL = 'name'
 
@@ -139,6 +141,44 @@ export const FILE_KINDS = {
   any: { label: 'Any of the above', accept: '.pdf,.doc,.docx,.odt,.rtf,.txt,.xls,.xlsx,.csv,.ods,.png,.jpg,.jpeg,.gif,.webp,.svg' }
 }
 
+/** The extensions a picture can have — what a preview is drawn for, and all a camera field takes. */
+export const IMAGE_EXTENSIONS = acceptList(FILE_KINDS.image.accept)
+
+/**
+ * Where a file field's files come from. `any` is the device's own choice —
+ * on a phone that is Camera, Photos and Files in one menu; `camera` opens the
+ * camera straight away (a photo taken now, not one from the gallery).
+ */
+export const FILE_SOURCES = [
+  { value: 'any', label: 'Files, gallery or camera' },
+  { value: 'camera', label: 'Camera only' }
+]
+
+/** Most files one field can hold. */
+export const MAX_FILES = 20
+
+/** Whether a stored path (or a file name) is a picture — by its extension, as the server checks. */
+export function isImageFile(name) {
+  const s = String(name || '').toLowerCase()
+  const dot = s.lastIndexOf('.')
+  return dot !== -1 && IMAGE_EXTENSIONS.includes(s.slice(dot))
+}
+
+/**
+ * What a file picker is asked for, from a file field's props — the one place
+ * that turns `accept`, `multiple` and `source` into a picker. The web reads it
+ * as <input type="file"> attributes; a phone app reads the same three.
+ */
+export function filePicker(props) {
+  const p = props || {}
+  const camera = p.source === 'camera'
+  return {
+    accept: p.accept || '',
+    multiple: Boolean(p.multiple) && !camera,
+    capture: camera ? 'environment' : undefined
+  }
+}
+
 /** An extension list as one string → the same list, cleaned and lower-cased. */
 export function acceptList(accept) {
   return String(accept || '')
@@ -456,11 +496,13 @@ export const CONTROLS = {
     label: 'File upload',
     group: 'Inputs',
     input: true,
-    // The value is the stored file's path, as the upload answered with it.
+    // The value is the stored file's path, as the upload answered with it —
+    // or, with `multiple`, a list of them (one text column, comma separated,
+    // like a multi-select: a stored path has no comma in it).
     valueType: 'string',
     defaultSize: { w: 0.44, h: 0.1 },
     defaults: { label: 'File', accept: FILE_KINDS.document.accept, maxSize: 10 },
-    props: ['name', 'label', 'preset', 'required', 'accept', 'maxSize', 'style'],
+    props: ['name', 'label', 'preset', 'required', 'accept', 'maxSize', 'multiple', 'maxFiles', 'source', 'style'],
     validation: [],
     styles: INPUT_STYLES.filter((k) => k !== 'textAlign'),
     properties: [
@@ -470,7 +512,10 @@ export const CONTROLS = {
         title: 'File',
         fields: [
           { path: 'props.accept', label: 'Allowed types', type: 'accept', help: 'Extensions, comma separated — the server refuses anything else' },
-          { path: 'props.maxSize', label: 'Largest size (MB)', type: 'number', min: 1, max: 200 }
+          { path: 'props.maxSize', label: 'Largest size (MB)', type: 'number', min: 1, max: 200 },
+          { path: 'props.source', label: 'Take from', type: 'select', options: FILE_SOURCES, help: 'Camera only: a photo taken now — the allowed types must be images' },
+          { path: 'props.multiple', label: 'Several files', type: 'toggle' },
+          { path: 'props.maxFiles', label: 'At most (files)', type: 'number', min: 1, max: MAX_FILES, help: 'With several files' }
         ]
       },
       ...styleGroups(INPUT_STYLES.filter((k) => k !== 'textAlign'))
@@ -548,7 +593,7 @@ CONTROLS.list = {
   // rowsFrom: rows a registered function works out (event "listRows") —
   // with its search box, filter chips and their counts — instead of one
   // table's records. See buttons.js.
-  props: ['title', 'source', 'belongsTo', 'editScreen', 'openIn', 'columns', 'pageSize', 'actions', 'rowsFrom', 'search', 'filters', 'refreshEvery', 'rowOpen', 'highlight', 'grow', 'style'],
+  props: ['title', 'source', 'belongsTo', 'editScreen', 'openIn', 'columns', 'pageSize', 'actions', 'rowsFrom', 'search', 'filters', 'kpis', 'dateRange', 'refreshEvery', 'rowOpen', 'highlight', 'grow', 'style'],
   validation: [],
   styles: ['fontFamily', 'fontSize', 'color', 'background', 'borderColor', 'borderWidth', 'borderRadius'],
   properties: [
@@ -581,6 +626,9 @@ CONTROLS.list = {
           help: 'A function of the app that works the rows out — instead of reading one table. Blank → the table above.' },
         { path: 'props.search.placeholder', label: 'Search box hint', type: 'text', help: 'Blank → no search box. Needs "Rows from".' },
         { path: 'props.filters', label: 'Filter chips', type: 'filters', help: 'The first is where the list starts. The function counts each.' },
+        { path: 'props.kpis', label: 'KPI cards', type: 'filters', help: 'Counts above the table, for the date range. A click shows that card\'s rows; another click lets go. The function counts each.' },
+        { path: 'props.dateRange', label: 'Date range', type: 'dateRange', presets: DATE_PRESETS,
+          help: 'A From–To range above the table, starting at the one chosen here. The function is asked for its rows and counts in it.' },
         { path: 'props.refreshEvery', label: 'Refresh every (seconds)', type: 'number', help: 'For rows whose text changes with time, like "2h ago". Blank → never.' },
         { path: 'props.rowOpen', label: 'A click on a row opens it', type: 'toggle' },
         { path: 'props.highlight', label: 'Mark rows where', type: 'text', help: 'A field of the row; a row where it is true is marked — "isNew".' },

package/src/designs/ButtonsView.jsx

@@ -1,13 +1,17 @@
 import { useEffect, useRef, useState } from 'react'
 import { createPortal } from 'react-dom'
 import { boxStyle, fieldStyle } from './styles.js'
+import FileField from './FileField.jsx'
+import { askFields, askFieldStart, askFieldValues } from '../buttons.js'
 
 // A PANEL OF BUTTONS. Each runs a function of the app on the server, with the
 // parameters the screen gives it; which ones show, and which are greyed out,
 // the controller works out from the record (useFactoryScreen.buttonsFor).
 //
-// A button that asks first opens a small dialog: its message, and a note box
-// when it takes a note. Presentation only — the press is the controller's.
+// A button that asks first opens a small dialog: its message, a note box when
+// it takes a note, and a file picker when it takes files (`ask.file` — on a
+// phone, the gallery or the camera). Presentation only — the press, and the
+// upload, are the controller's.
 //
 // On the canvas (design) the buttons are drawn as they will look, inert.
 
@@ -58,17 +62,33 @@ export default function ButtonsView({ node, design, panel }) {
           busy={panel.pressing === asking.id}
           error={note && note.kind === 'error' && note.button === asking.id ? note.text : null}
           onCancel={() => { setAsking(null); panel.clearNote() }}
-          onConfirm={async (typed) => { if (await panel.press(asking, typed)) setAsking(null) }}
+          upload={(file) => panel.upload(file, asking)}
+          readFile={panel.readFile}
+          record={panel.record}
+          onConfirm={async (typed, files, values) => { if (await panel.press(asking, typed, files, values)) setAsking(null) }}
         />
       )}
     </div>
   )
 }
 
-/** "Change status to Packed?" — the button's message, and a note when it takes one. */
-function AskDialog({ button, busy, error, onCancel, onConfirm }) {
+/** "Change status to Packed?" — the button's message, its fields, a note and files when it takes them. */
+function AskDialog({ button, busy, error, onCancel, onConfirm, upload, readFile, record }) {
   const ask = button.ask || {}
+  const file = ask.file && typeof ask.file === 'object' ? ask.file : null
+  const fields = askFields(button)
   const [typed, setTyped] = useState('')
+  const [files, setFiles] = useState([])
+  // Each asked value starts from the record (`fill`): asked again, it shows what was given last.
+  const [given, setGiven] = useState(() => Object.fromEntries(fields.map((f) => [f.name, askFieldStart(f, record)])))
+  const [shown, setShown] = useState({})          // field → message, after a try
+  const confirm = () => {
+    const out = askFieldValues(button, given)
+    if (out.errors.length) { setShown(Object.fromEntries(out.errors.map((e) => [e.field, e.message]))); return }
+    setShown({})
+    onConfirm(typed, files, out.values)
+  }
+  const missing = Boolean(file && file.required && !files.length)
   const ref = useRef(null)
   useEffect(() => {
     ref.current?.focus()
@@ -87,17 +107,60 @@ function AskDialog({ button, busy, error, onCancel, onConfirm }) {
         </header>
         <div className="xeplr-factory-modal-body">
           {ask.message && <p className="xeplr-factory-ask-message">{ask.message}</p>}
+          {fields.length > 0 && (
+            <div className="xeplr-factory-ask-fields">
+              {fields.map((f) => {
+                const fid = `${titleId}-${f.name}`
+                return (
+                  <div key={f.name} className="xeplr-factory-ask-field">
+                    <label className="xeplr-factory-ask-label" htmlFor={fid}>{f.label}{f.required ? ' *' : ''}</label>
+                    <span className="xeplr-factory-ask-value">
+                      <input
+                        id={fid}
+                        className="xeplr-factory-ask-input"
+                        type={f.type === 'number' ? 'number' : 'text'}
+                        inputMode={f.type === 'number' ? 'decimal' : undefined}
+                        step={f.type === 'number' ? 'any' : undefined}
+                        min={f.min} max={f.max}
+                        value={given[f.name] ?? ''}
+                        aria-invalid={shown[f.name] ? true : undefined}
+                        aria-describedby={shown[f.name] ? `${fid}-error` : undefined}
+                        onChange={(e) => { const v = e.target.value; setGiven((g) => ({ ...g, [f.name]: v })); setShown((m) => ({ ...m, [f.name]: undefined })) }}
+                      />
+                      {f.unit && <span className="xeplr-factory-ask-unit">{f.unit}</span>}
+                    </span>
+                    {shown[f.name] && <span className="xeplr-factory-ask-field-error" id={`${fid}-error`} role="alert">{shown[f.name]}</span>}
+                  </div>
+                )
+              })}
+            </div>
+          )}
           {ask.note && (
             <label className="xeplr-factory-ask-field" htmlFor={`${titleId}-note`}>
               <span className="xeplr-factory-ask-label">{ask.note}</span>
               <textarea id={`${titleId}-note`} className="xeplr-factory-ask-note" rows={3} maxLength={1000} value={typed} onChange={(e) => setTyped(e.target.value)} />
             </label>
           )}
+          {file && (
+            <div className="xeplr-factory-ask-field">
+              <span className="xeplr-factory-ask-label" id={`${titleId}-file`}>{file.label || (file.multiple ? 'Files' : 'File')}{file.required ? ' *' : ''}</span>
+              <FileField
+                id={`${titleId}-files`}
+                rules={file}
+                files={files}
+                onChange={setFiles}
+                upload={upload}
+                readFile={readFile}
+                disabled={busy}
+                inputProps={{ 'aria-labelledby': `${titleId}-file`, 'aria-required': file.required ? true : undefined }}
+              />
+            </div>
+          )}
           {error && <p className="xeplr-factory-ask-error" role="alert">{error}</p>}
         </div>
         <footer className="xeplr-factory-ask-foot">
           <button type="button" className="xeplr-factory-secondary" onClick={onCancel} disabled={busy}>Cancel</button>
-          <button type="button" className={button.variant === 'danger' ? 'xeplr-factory-danger' : 'xeplr-factory-primary'} onClick={() => onConfirm(typed)} disabled={busy}>
+          <button type="button" className={button.variant === 'danger' ? 'xeplr-factory-danger' : 'xeplr-factory-primary'} onClick={confirm} disabled={busy || missing}>
             {busy ? 'Working…' : button.label}
           </button>
         </footer>