@xeplr/ui-factory 1.8.4 → 1.8.6

package/AUTHORING.md

@@ -241,7 +241,7 @@ 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".
+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 +292,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.
@@ -433,6 +437,7 @@ actions.register({
 | `ask` | asked first: `title`, `message`, and `note` — the label of a note box, whose text reaches the function as `note` (it must take one) |
 | `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 |
 | `variant` | `default`, `primary`, `danger` |
 
 Rules are [`@xeplr/rules`](https://www.npmjs.com/package/@xeplr/rules) rules — `{ field, op, value }`, with `eq`, `neq`, `isEmpty`, `contains`, `gt`, … — read from **the record the screen is about**: the `record` handed to `<FactoryScreen>`, with the form's own changes on top.
@@ -442,6 +447,52 @@ 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 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
@@ -785,7 +836,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 |
@@ -1029,7 +1080,7 @@ 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
@@ -1040,10 +1091,11 @@ src/
   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)
 ```
 
@@ -1053,7 +1105,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/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`.
 
@@ -1062,7 +1114,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. 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.4",
+  "version": "1.8.6",
   "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

@@ -7,6 +7,7 @@
 //
 //   { id: 'packed', label: 'Packed', action: 'setOrderStatus', params: { status: 'packed' },
 //     ask: { title: 'Change status to Packed', note: 'Reason (optional)' },
+//     pressedWhen:  [{ field: 'customStatus', op: 'eq', value: 'packed' }],
 //     disabledWhen: [{ field: 'customStatus', op: 'eq', value: 'packed' }] }
 //
 // The function lives in the app, registered with @xeplr/actions and an
@@ -45,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)
 
@@ -66,6 +74,16 @@ export function buttonDisabled(button, record) {
   return Array.isArray(rules) && rules.length > 0 && conditionMet(rules, record)
 }
 
+/**
+ * Whether a button is drawn as the CURRENT choice — the status an order is
+ * at, filled in. Usually also its disabledWhen: choosing it again changes
+ * nothing. No pressedWhen: never.
+ */
+export function buttonPressed(button, record) {
+  const rules = button && button.pressedWhen
+  return Array.isArray(rules) && rules.length > 0 && conditionMet(rules, record)
+}
+
 /** Every button on a screen, with the panel it is on. */
 export function screenButtons(doc) {
   return ((doc && doc.nodes) || [])
@@ -78,15 +96,37 @@ 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) {
+/** 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, and the stored files when it takes them.
+ */
+export function buttonInput(button, note, files) {
   const input = { ...((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
 }
 
+/** 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
@@ -130,9 +170,11 @@ 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 (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}"`)
   return problems
 }
 

package/src/controls.js

@@ -139,6 +139,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 +494,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 +510,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'))

package/src/designs/ButtonsView.jsx

@@ -1,13 +1,16 @@
 import { useEffect, useRef, useState } from 'react'
 import { createPortal } from 'react-dom'
 import { boxStyle, fieldStyle } from './styles.js'
+import FileField from './FileField.jsx'
 
 // 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.
 
@@ -37,7 +40,8 @@ export default function ButtonsView({ node, design, panel }) {
         <button
           key={b.id}
           type="button"
-          className={`xeplr-factory-button xeplr-factory-button--${b.variant || 'default'}`}
+          className={`xeplr-factory-button xeplr-factory-button--${b.variant || 'default'}${b.pressed ? ' xeplr-factory-button--pressed' : ''}`}
+          aria-pressed={b.pressedWhen ? Boolean(b.pressed) : undefined}
           disabled={b.disabled || Boolean(panel.pressing)}
           aria-busy={panel.pressing === b.id}
           onClick={() => run(b)}
@@ -57,17 +61,22 @@ 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}
+          onConfirm={async (typed, files) => { if (await panel.press(asking, typed, files)) 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, a note and files when it takes them. */
+function AskDialog({ button, busy, error, onCancel, onConfirm, upload, readFile }) {
   const ask = button.ask || {}
+  const file = ask.file && typeof ask.file === 'object' ? ask.file : null
   const [typed, setTyped] = useState('')
+  const [files, setFiles] = useState([])
+  const missing = Boolean(file && file.required && !files.length)
   const ref = useRef(null)
   useEffect(() => {
     ref.current?.focus()
@@ -92,11 +101,26 @@ function AskDialog({ button, busy, error, onCancel, onConfirm }) {
               <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={() => onConfirm(typed, files)} disabled={busy || missing}>
             {busy ? 'Working…' : button.label}
           </button>
         </footer>

package/src/designs/ControlView.jsx

@@ -3,6 +3,7 @@ import { tableColumns, LABEL_PRESETS } from '../controls.js'
 import { stepsOf } from '../document.js'
 import ListView from './ListView.jsx'
 import ButtonsView from './ButtonsView.jsx'
+import FileField from './FileField.jsx'
 import { fieldStyle, labelStyle, boxStyle } from './styles.js'
 
 // How each control LOOKS — the one renderer, used both on the builder's
@@ -14,7 +15,7 @@ import { fieldStyle, labelStyle, boxStyle } from './styles.js'
 
 const ids = (node) => `xeplr-factory-${node.id}`
 
-export default function ControlView({ node, mode = 'live', value, error, options, onChange, onBlur, disabled, list, upload, stepper, subform, rows, buttons }) {
+export default function ControlView({ node, mode = 'live', value, error, options, onChange, onBlur, disabled, list, upload, readFile, stepper, subform, rows, buttons }) {
   const View = VIEWS[node.type]
   if (!View) {
     return <div className="xeplr-factory-unknown">Unknown control “{node.type}”</div>
@@ -33,6 +34,7 @@ export default function ControlView({ node, mode = 'live', value, error, options
       disabled={design || disabled}
       list={list}
       upload={upload}
+      readFile={readFile}
       stepper={stepper}
       subform={subform}
       rows={rows}
@@ -317,51 +319,31 @@ function DatetimeView({ node, p, value, error, onChange, onBlur, disabled }) {
 }
 
 /**
- * A file field holds the stored file's PATH, not the file. Picking one uploads
- * it straight away (`upload`, supplied by the screen) and what comes back is
- * the value that is saved with the record.
+ * A file field holds the stored file's PATH, not the file — or, with
+ * `multiple`, a list of them. Picking one uploads it straight away (`upload`,
+ * supplied by the screen) and what comes back is the value saved with the
+ * record. A stored picture shows as a thumbnail when the screen can read it
+ * back (`readFile`).
  */
-function FileView({ node, p, design, value, error, onChange, onBlur, disabled, upload }) {
-  const [busy, setBusy] = useState(false)
-  const [failed, setFailed] = useState(null)
-  const accept = p.accept || ''
-  const choose = async (file) => {
-    if (!file || !upload) return
-    setFailed(null)
-    setBusy(true)
-    try {
-      const out = await upload(file, node)
-      onChange(out && out.path ? out.path : undefined)
-    } catch (e) {
-      setFailed(e && e.message ? e.message : 'The file could not be uploaded')
-    } finally {
-      setBusy(false)
-      onBlur()
-    }
-  }
+function FileView({ node, p, design, value, error, onChange, onBlur, disabled, upload, readFile }) {
+  const several = Boolean(p.multiple)
+  const files = several ? (Array.isArray(value) ? value : []) : value ? [value] : []
+  const { style, ...aria } = inputProps(node, p, error, disabled, onBlur)
   return (
-    <Field node={node} p={p} error={error || failed}>
-      {value
-        ? (
-          <div className="xeplr-factory-file">
-            <span className="xeplr-factory-file-name" title={String(value)}>{fileName(value)}</span>
-            <button type="button" className="xeplr-factory-file-clear" disabled={disabled} onClick={() => { onChange(undefined); onBlur() }}>Remove</button>
-          </div>
-        )
-        : (
-          <input
-            className="xeplr-factory-input xeplr-factory-file-input"
-            type="file"
-            accept={accept}
-            disabled={disabled || busy}
-            onChange={(e) => { const f = e.target.files && e.target.files[0]; e.target.value = ''; choose(f) }}
-            {...inputProps(node, p, error, disabled || busy, onBlur)}
-          />
-        )}
-      {busy && <div className="xeplr-factory-hint">Uploading…</div>}
-      {!busy && !value && (design || accept) && (
-        <div className="xeplr-factory-hint">{accept || 'any file'}{p.maxSize ? ` · up to ${p.maxSize} MB` : ''}</div>
-      )}
+    <Field node={node} p={p} error={error}>
+      <FileField
+        id={aria.id}
+        rules={p}
+        files={files}
+        onChange={(paths) => onChange(several ? paths : paths[0])}
+        onBlur={onBlur}
+        upload={upload ? (file) => upload(file, node) : undefined}
+        readFile={readFile}
+        disabled={disabled}
+        design={design}
+        inputProps={aria}
+        style={style}
+      />
     </Field>
   )
 }

package/src/designs/FileField.jsx

@@ -0,0 +1,99 @@
+import { useState } from 'react'
+import { filePicker, isImageFile } from '../controls.js'
+import { fileLabel } from '../values.js'
+import { useFilePreview } from '../useFilePreview.js'
+
+// THE FILES A FIELD HOLDS, AND THE PICKER THAT ADDS ONE — a file field's, and
+// a button's `ask.file`. Presentation only: what an upload is, and how a
+// stored picture is read back, are handed in.
+//
+// On a phone the picker is the phone's own: "Files, gallery or camera" opens
+// its menu (Photos, Camera, Files), "Camera only" opens the camera.
+
+/**
+ * @param rules     { accept, maxSize, multiple, maxFiles, source }
+ * @param files     the stored paths, as a list
+ * @param onChange  (paths) → void
+ * @param upload    async (File) → { path }
+ * @param readFile  async (path) → Blob — a picture's preview; names only without it
+ */
+export default function FileField({ id, rules, files, onChange, onBlur, upload, readFile, disabled, design, inputProps, style }) {
+  const [busy, setBusy] = useState(false)
+  const [failed, setFailed] = useState(null)
+  const r = rules || {}
+  const picker = filePicker(r)
+  const several = Boolean(r.multiple)
+  const list = Array.isArray(files) ? files : []
+  const full = several ? Boolean(r.maxFiles) && list.length >= r.maxFiles : list.length >= 1
+
+  // One at a time, in the order chosen: each answer is added as it lands, so a
+  // refusal of the third keeps the first two.
+  const choose = async (chosen) => {
+    if (!chosen.length || !upload) return
+    setFailed(null)
+    setBusy(true)
+    let next = list
+    try {
+      const room = several ? (r.maxFiles ? Math.max(r.maxFiles - list.length, 0) : chosen.length) : 1
+      if (chosen.length > room) setFailed(`At most ${r.maxFiles} files — the first ${room} were added`)
+      for (const file of chosen.slice(0, room)) {
+        const out = await upload(file)
+        if (out && out.path) { next = several ? [...next, out.path] : [out.path]; onChange(next) }
+      }
+    } catch (e) {
+      setFailed(e && e.message ? e.message : 'The file could not be uploaded')
+    } finally {
+      setBusy(false)
+      if (onBlur) onBlur()
+    }
+  }
+
+  const remove = (path) => { onChange(list.filter((p) => p !== path)); if (onBlur) onBlur() }
+  const hint = [r.accept || 'any file', r.maxSize ? `up to ${r.maxSize} MB` : null, several && r.maxFiles ? `at most ${r.maxFiles} files` : null].filter(Boolean).join(' · ')
+
+  return (
+    <div className="xeplr-factory-files">
+      {list.length > 0 && (
+        <ul className="xeplr-factory-files-list">
+          {list.map((path) => (
+            <FileItem key={path} path={path} readFile={readFile} disabled={disabled || busy} onRemove={() => remove(path)} />
+          ))}
+        </ul>
+      )}
+      {!full && (
+        <label className={`xeplr-factory-files-add${disabled || busy ? ' xeplr-factory-files-add--off' : ''}`} style={style}>
+          <input
+            className="xeplr-factory-files-input"
+            type="file"
+            accept={picker.accept || undefined}
+            multiple={picker.multiple || undefined}
+            capture={picker.capture}
+            disabled={disabled || busy}
+            onChange={(e) => { const chosen = Array.from(e.target.files || []); e.target.value = ''; choose(chosen) }}
+            {...(inputProps || {})}
+            id={id}
+          />
+          <span className="xeplr-factory-files-add-label">
+            {busy ? 'Uploading…' : r.source === 'camera' ? (list.length ? 'Take another photo' : 'Take a photo') : list.length ? 'Add another' : several ? 'Choose files' : 'Choose a file'}
+          </span>
+        </label>
+      )}
+      {failed && <div className="xeplr-factory-files-error" role="alert">{failed}</div>}
+      {!busy && !list.length && (design || r.accept) && <div className="xeplr-factory-hint">{hint}</div>}
+    </div>
+  )
+}
+
+function FileItem({ path, readFile, disabled, onRemove }) {
+  const preview = useFilePreview(path, readFile)
+  const picture = isImageFile(path)
+  return (
+    <li className="xeplr-factory-files-item">
+      {picture && preview.url
+        ? <img className="xeplr-factory-files-thumb" src={preview.url} alt="" />
+        : <span className="xeplr-factory-files-icon" aria-hidden="true">{picture ? '🖼' : '📄'}</span>}
+      <span className="xeplr-factory-files-name" title={fileLabel(path)}>{fileLabel(path)}</span>
+      <button type="button" className="xeplr-factory-files-remove" disabled={disabled} onClick={onRemove} aria-label={`Remove ${fileLabel(path)}`}>Remove</button>
+    </li>
+  )
+}