@xeplr/ui-factory 1.8.4 → 1.8.6

package/src/designs/PropertyPanel.jsx

@@ -3,8 +3,8 @@ import { getAtPath } from '../propertyPath.js'
 import { FIELD_PRESETS, presetFor } from '../presets.js'
 import { slugify, inputNodes, paramsText, screenParams } from '../document.js'
 import { isBinding, previousBinding } from '../values.js'
-import { FONT_FAMILIES, STYLE_KEYS, SCREEN_STYLE_KEYS, LIST_ACTIONS, FILE_KINDS } from '../controls.js'
-import { BUTTON_VARIANTS, COLUMN_DISPLAYS, BADGE_TONES, CONDITION_OPERATORS, NOTE_INPUT, optionValues } from '../buttons.js'
+import { FONT_FAMILIES, STYLE_KEYS, SCREEN_STYLE_KEYS, LIST_ACTIONS, FILE_KINDS, FILE_SOURCES, MAX_FILES } from '../controls.js'
+import { BUTTON_VARIANTS, COLUMN_DISPLAYS, BADGE_TONES, CONDITION_OPERATORS, NOTE_INPUT, FILES_INPUT, optionValues } from '../buttons.js'
 
 // The selected control's properties, GENERATED from its entry in controls.js:
 // each field there names a path and an editor type, and this file owns only
@@ -941,6 +941,7 @@ function ButtonsEditor({ value, onChange, functions }) {
         const fn = pick.find((f) => f.name === b.action) || null
         const schema = (fn && fn.inputSchema) || []
         const takesNote = schema.some((f) => f.name === NOTE_INPUT)
+        const takesFiles = schema.some((f) => f.name === FILES_INPUT)
         return (
           <fieldset key={i} className="xeplr-factory-rows-editor-card">
             <legend>{b.label || `Button ${i + 1}`}</legend>
@@ -961,7 +962,7 @@ function ButtonsEditor({ value, onChange, functions }) {
               </select>
             </MiniField>
             {fn && fn.description && <div className="xeplr-factory-prop-help">{fn.description}</div>}
-            {schema.filter((f) => f.name !== NOTE_INPUT).map((f) => (
+            {schema.filter((f) => f.name !== NOTE_INPUT && f.name !== FILES_INPUT).map((f) => (
               <MiniField key={f.name} label={(f.label || f.name) + (f.required && f.default === undefined ? ' *' : '')} help={f.description}>
                 <ParamInput field={f} value={b.params ? b.params[f.name] : undefined} onChange={(v) => {
                   const params = { ...(b.params || {}) }
@@ -981,10 +982,14 @@ function ButtonsEditor({ value, onChange, functions }) {
                 {takesNote
                   ? <MiniField label="Note box label" help="Blank → no note box"><input className="xeplr-factory-prop-input" value={b.ask.note || ''} placeholder="Reason (optional)" onChange={(e) => edit(i, { ask: clean({ ...b.ask, note: e.target.value }) })} /></MiniField>
                   : fn && <div className="xeplr-factory-prop-help">{fn.name} takes no note.</div>}
+                {takesFiles
+                  ? <AskFileEditor value={b.ask.file} onChange={(file) => edit(i, { ask: clean({ ...b.ask, file }) })} />
+                  : b.ask.file && <div className="xeplr-factory-prop-help">{fn ? fn.name : 'This function'} takes no files — the picker will be refused when publishing.</div>}
               </>
             )}
             <ConditionsEditor label="Shows when" value={b.when} onChange={(v) => edit(i, { when: v })} />
             <ConditionsEditor label="Greyed out when" value={b.disabledWhen} onChange={(v) => edit(i, { disabledWhen: v })} />
+            <ConditionsEditor label="Shown as the current choice when" value={b.pressedWhen} onChange={(v) => edit(i, { pressedWhen: v })} />
             <MiniField label="Look">
               <select className="xeplr-factory-prop-input" value={b.variant || 'default'} onChange={(e) => edit(i, { variant: e.target.value === 'default' ? undefined : e.target.value })}>
                 {BUTTON_VARIANTS.map((v) => <option key={v} value={v}>{VARIANT_LABELS[v]}</option>)}
@@ -1000,6 +1005,51 @@ function ButtonsEditor({ value, onChange, functions }) {
 
 const VARIANT_LABELS = { default: 'Ordinary', primary: 'Main', danger: 'Undo / remove' }
 
+/**
+ * The file a button's press takes (`ask.file`): a file field's rules, set the
+ * same way. Offered only when the function takes "files".
+ */
+function AskFileEditor({ value, onChange }) {
+  const f = value && typeof value === 'object' ? value : null
+  const set = (patch) => {
+    const next = { ...f, ...patch }
+    Object.keys(next).forEach((k) => { if (next[k] === undefined || next[k] === '' || next[k] === false) delete next[k] })
+    if (!next.multiple) delete next.maxFiles
+    onChange(next)
+  }
+  return (
+    <>
+      <label className="xeplr-factory-toggle">
+        <input type="checkbox" checked={Boolean(f)} onChange={(e) => onChange(e.target.checked ? { label: 'Photo', accept: FILE_KINDS.image.accept } : undefined)} />
+        <span>Asks for a file</span>
+      </label>
+      {f && (
+        <>
+          <MiniField label="File box label"><input className="xeplr-factory-prop-input" value={f.label || ''} onChange={(e) => set({ label: e.target.value })} /></MiniField>
+          <MiniField label="Allowed types"><AcceptEditor value={f.accept} onChange={(accept) => set({ accept })} /></MiniField>
+          <MiniField label="Take from">
+            <select className="xeplr-factory-prop-input" value={f.source || 'any'} onChange={(e) => set({ source: e.target.value === 'any' ? undefined : e.target.value })}>
+              {FILE_SOURCES.map((o) => <option key={o.value} value={o.value}>{o.label}</option>)}
+            </select>
+          </MiniField>
+          <MiniField label="Largest size (MB)"><input className="xeplr-factory-prop-input" type="number" min={1} max={200} value={f.maxSize ?? ''} onChange={(e) => set({ maxSize: e.target.value === '' ? undefined : Number(e.target.value) })} /></MiniField>
+          <label className="xeplr-factory-toggle">
+            <input type="checkbox" checked={Boolean(f.multiple)} onChange={(e) => set({ multiple: e.target.checked })} />
+            <span>Several files</span>
+          </label>
+          {f.multiple && (
+            <MiniField label="At most (files)"><input className="xeplr-factory-prop-input" type="number" min={1} max={MAX_FILES} value={f.maxFiles ?? ''} onChange={(e) => set({ maxFiles: e.target.value === '' ? undefined : Number(e.target.value) })} /></MiniField>
+          )}
+          <label className="xeplr-factory-toggle">
+            <input type="checkbox" checked={Boolean(f.required)} onChange={(e) => set({ required: e.target.checked })} />
+            <span>Required</span>
+          </label>
+        </>
+      )}
+    </>
+  )
+}
+
 /** One parameter's value: a dropdown when the function names the values allowed. */
 function ParamInput({ field, value, onChange }) {
   const allowed = optionValues(field.options)

package/src/designs/ScreenSample.jsx

@@ -220,6 +220,7 @@ export default function ScreenSample({ ctrl, className, style, renderPopup, rend
               error={node.props?.name ? ctrl.errors[node.props.name] : undefined}
               options={CHOICE_TYPES.includes(node.type) ? ctrl.optionsFor(node) : undefined}
               upload={node.type === 'file' ? ctrl.upload : undefined}
+              readFile={node.type === 'file' ? ctrl.readFile : undefined}
               rows={node.type === 'table' && ctrl.rowsFor ? ctrl.rowsFor(node) : undefined}
               stepper={node.type === 'stepper' ? {
                 active: ctrl.steps.active(node.id),

package/src/designs/factory.css

@@ -157,15 +157,40 @@
 .xeplr-factory-choice { display: flex; align-items: center; gap: calc(8 * var(--xf-u)); cursor: pointer; color: var(--xf-ink); }
 .xeplr-factory-choice input { width: calc(16 * var(--xf-u)); height: calc(16 * var(--xf-u)); min-width: 11px; min-height: 11px; margin: 0; accent-color: var(--xf-accent); }
 
-/* ── file ─────────────────────────────────────────────────────────────────── */
-.xeplr-factory-file { display: flex; align-items: center; gap: calc(8 * var(--xf-u)); min-width: 0; }
-.xeplr-factory-file-name { flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; color: var(--xf-ink); }
-.xeplr-factory-file-clear {
+/* ── file ───────────────────────────────────────────────────────────────────
+   What the field holds — a row per file, a thumbnail for a picture — and,
+   while it has room, the picker: a box that looks like the other inputs, the
+   real <input type="file"> laid over it, invisible, so a tap opens the
+   device's own picker (on a phone: Photos, Camera, Files). */
+.xeplr-factory-files { display: flex; flex-direction: column; gap: calc(6 * var(--xf-u, 1px)); min-width: 0; min-height: 0; overflow: auto; }
+.xeplr-factory-files-list { list-style: none; margin: 0; padding: 0; display: flex; flex-direction: column; gap: calc(4 * var(--xf-u, 1px)); }
+.xeplr-factory-files-item { display: flex; align-items: center; gap: calc(8 * var(--xf-u, 1px)); min-width: 0; }
+.xeplr-factory-files-thumb {
+  flex: none; width: calc(40 * var(--xf-u, 1px)); height: calc(40 * var(--xf-u, 1px)); min-width: 28px; min-height: 28px;
+  object-fit: cover; border-radius: calc(4 * var(--xf-u, 1px)); border: 1px solid var(--xf-field-border); background: var(--xf-field-bg);
+}
+.xeplr-factory-files-icon {
+  flex: none; width: calc(40 * var(--xf-u, 1px)); height: calc(40 * var(--xf-u, 1px)); min-width: 28px; min-height: 28px;
+  display: inline-flex; align-items: center; justify-content: center; border-radius: calc(4 * var(--xf-u, 1px));
+  border: 1px solid var(--xf-field-border); background: var(--xf-field-bg);
+}
+.xeplr-factory-files-name { flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; color: var(--xf-ink); }
+.xeplr-factory-files-remove {
   flex: none; border: 1px solid var(--xf-field-border); background: var(--xf-field-bg); color: var(--xf-muted);
-  border-radius: calc(6 * var(--xf-u)); padding: calc(3 * var(--xf-u)) calc(8 * var(--xf-u)); cursor: pointer; font: inherit;
+  border-radius: calc(6 * var(--xf-u, 1px)); padding: calc(3 * var(--xf-u, 1px)) calc(8 * var(--xf-u, 1px)); cursor: pointer; font: inherit;
 }
-.xeplr-factory-file-clear:hover { color: var(--xf-ink); border-color: var(--xf-accent); }
-.xeplr-factory-file-input { padding: calc(5 * var(--xf-u)); }
+.xeplr-factory-files-remove:hover { color: var(--xf-ink); border-color: var(--xf-accent); }
+.xeplr-factory-files-add {
+  position: relative; display: flex; align-items: center; justify-content: center; flex: none;
+  min-height: calc(34 * var(--xf-u, 1px)); padding: calc(5 * var(--xf-u, 1px)) calc(10 * var(--xf-u, 1px)); box-sizing: border-box;
+  border: 1px dashed var(--xf-field-border); border-radius: calc(6 * var(--xf-u, 1px)); background: var(--xf-field-bg);
+  color: var(--xf-ink); cursor: pointer;
+}
+.xeplr-factory-files-add:hover, .xeplr-factory-files-add:focus-within { border-color: var(--xf-accent); }
+.xeplr-factory-files-add--off { cursor: default; opacity: .6; }
+.xeplr-factory-files-input { position: absolute; inset: 0; width: 100%; height: 100%; opacity: 0; cursor: inherit; margin: 0; }
+.xeplr-factory-files-add-label { white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+.xeplr-factory-files-error { color: var(--xf-danger); font-size: .9em; white-space: normal; }
 
 /* ── stepper ──────────────────────────────────────────────────────────────
    The journey across the top: a circle per step, joined by a line. The line
@@ -372,6 +397,10 @@ button.xeplr-factory-activity-item:hover, button.xeplr-factory-activity-item:foc
 .xeplr-factory-button--danger { color: var(--xf-danger); border-color: color-mix(in srgb, var(--xf-danger) 55%, var(--xf-border)); }
 .xeplr-factory-button--danger:hover:not(:disabled) { background: color-mix(in srgb, var(--xf-danger) 10%, transparent); }
 .xeplr-factory-buttons--design .xeplr-factory-button { cursor: inherit; }
+/* The current choice (pressedWhen): filled, and never faded — greyed out is
+   "unavailable", which the current status is not. */
+.xeplr-factory-button--pressed,
+.xeplr-factory-button--pressed:disabled { color: var(--xf-accent-ink); background: var(--xf-accent); border-color: var(--xf-accent); opacity: 1; }
 .xeplr-factory-buttons-note {
   display: inline-flex; align-items: center; gap: 6px; font-size: .9em; padding: 4px 6px 4px 10px; border-radius: 6px;
   color: var(--xf-good); background: color-mix(in srgb, var(--xf-good) 10%, transparent);
@@ -800,7 +829,9 @@ button.xeplr-factory-activity-item:hover, button.xeplr-factory-activity-item:foc
      the smallest target a thumb hits reliably. */
   .xeplr-factory-input { --xf-min-font: 16px; font-size: max(16px, 1em); flex: none; min-height: 44px; }
   .xeplr-factory-textarea { min-height: 112px; }
-  .xeplr-factory-file-input { min-height: 0; }
+  .xeplr-factory-files { overflow: visible; }
+  .xeplr-factory-files-add { min-height: 44px; }
+  .xeplr-factory-files-thumb, .xeplr-factory-files-icon { width: 48px; height: 48px; }
   /* In the flow now: a message may push the next field down, and wraps
      rather than being cut off at the edge of a narrow screen. */
   .xeplr-factory-error { position: static; white-space: normal; }
@@ -808,7 +839,7 @@ button.xeplr-factory-activity-item:hover, button.xeplr-factory-activity-item:foc
   .xeplr-factory-check input { width: 22px; height: 22px; }
   .xeplr-factory-choice input { width: 20px; height: 20px; }
   .xeplr-factory-choices { overflow: visible; }
-  .xeplr-factory-file-clear { min-height: 40px; padding-inline: 14px; }
+  .xeplr-factory-files-remove { min-height: 40px; padding-inline: 14px; }
   .xeplr-factory-text { height: auto; overflow: visible; }
   .xeplr-factory-stepper { height: auto; }
   .xeplr-factory-list { max-height: none; }

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, 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, 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'

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:
@@ -135,7 +138,16 @@ export function createFactoryApi({ fetch: doFetch, base = '' } = {}) {
     // 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 }) => one(await call('POST', `/buttons/${enc(screen)}/${enc(button)}`, {
+      id, ...(note ? { note } : {}), ...(Array.isArray(files) && files.length ? { files } : {})
+    })),
+    // 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 +156,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/useFactoryScreen.js

@@ -5,7 +5,7 @@ import { validateDocument } from './validateDocument.js'
 import { initialValues, parseInput, saveState, fieldError, optionValue, recordValues, listSource, resolveBinding } from './values.js'
 import { hookMethod } from './hooks.js'
 import { useUrlSteps, useUrlListQuery } from './useUrlPlaces.js'
-import { buttonShown, buttonDisabled } from './buttons.js'
+import { buttonShown, buttonDisabled, buttonPressed } from './buttons.js'
 
 // A saved screen, running. No JSX — designs/ScreenSample.jsx draws it.
 //
@@ -61,7 +61,9 @@ import { buttonShown, buttonDisabled } from './buttons.js'
  * @param hooks         a FactoryHooks (or an object with some of its methods) — get / save / delete / actions
  * @param fetchRows     async ({ screen, node, q, filter }) → { rows, counts } — a list whose rows a function works out (rowsFrom)
  * @param fetchRowDetails async ({ screen, node, column, id }) → [{ text, sub?, at?, open? }] — an activity cell's hover box
- * @param pressButton   async ({ screen, button, id, note }) → { message } — a button's press, run on the server
+ * @param pressButton   async ({ screen, button, id, note, files }) → { 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 +84,9 @@ import { buttonShown, buttonDisabled } 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
 } = {}) {
@@ -830,6 +832,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 }
@@ -838,16 +841,24 @@ export function useFactoryScreen({
     record: buttonRecord,
     buttons: ((node.props && node.props.buttons) || [])
       .filter((b) => buttonShown(b, buttonRecord))
-      .map((b) => ({ ...b, disabled: buttonDisabled(b, buttonRecord) || recordId === null || recordId === undefined })),
+      .map((b) => ({ ...b, pressed: buttonPressed(b, buttonRecord), disabled: buttonDisabled(b, buttonRecord) || recordId === null || recordId === undefined })),
     pressing,
     note: buttonNote,
     clearNote: () => setButtonNote(null),
-    press: async (b, typed) => {
+    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) => {
       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 })
         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 +870,7 @@ export function useFactoryScreen({
         setPressing(null)
       }
     }
-  }), [buttonRecord, pressing, buttonNote, doc, recordId])
+  }), [buttonRecord, pressing, buttonNote, doc, recordId, readFile])
 
   return {
     document: doc,
@@ -889,6 +900,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,7 +11,7 @@
 // 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 { RESERVED_COLUMNS, MAX_IDENTIFIER } from './tableSchema.js'
 import { FIELD_PRESETS, INPUT_TYPES, presetFor } from './presets.js'
@@ -281,19 +281,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(',')})`)
+      }
     }
   }
 }
@@ -522,14 +547,27 @@ function checkFedColumn(c, p, err) {
   }
 }
 
-const BUTTON_KEYS = ['id', 'label', 'action', 'params', 'ask', 'when', 'disabledWhen', 'variant']
+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.
  */
+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,13 +591,14 @@ 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')
+        if (bad.length) err(`${p}.ask`, `only ${[...ASK_KEYS, 'file'].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.variant !== undefined && !BUTTON_VARIANTS.includes(b.variant)) err(`${p}.variant`, `must be one of: ${BUTTON_VARIANTS.join(', ')}`)
-    ;['when', 'disabledWhen'].forEach((k) => { if (b[k] !== undefined) checkRules(b[k], `${p}.${k}`, err) })
+    ;['when', 'disabledWhen', 'pressedWhen'].forEach((k) => { if (b[k] !== undefined) checkRules(b[k], `${p}.${k}`, err) })
   })
 }