@xeplr/ui-factory 1.8.6 → 1.8.7

package/AUTHORING.md

@@ -241,6 +241,8 @@ A button is **a registered function and its parameters** — never code. Several
 ] } }
 ```
 
+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

package/README.md

@@ -434,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 |
@@ -447,6 +447,30 @@ 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,
@@ -517,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
@@ -538,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`
 
@@ -1086,7 +1118,8 @@ src/
   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
@@ -1105,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/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/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`.
 
@@ -1114,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. 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.
+`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.6",
+  "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

@@ -104,10 +104,12 @@ export function askFile(button) {
 
 /**
  * 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.
+ * 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) {
-  const input = { ...((button && button.params) || {}) }
+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()
   }
@@ -115,6 +117,68 @@ export function buttonInput(button, note, files) {
   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)
@@ -171,10 +235,17 @@ export function paramProblems(button, inputSchema) {
     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'
 
@@ -591,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: [
@@ -624,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

@@ -2,6 +2,7 @@ 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,
@@ -63,19 +64,30 @@ export default function ButtonsView({ node, design, panel }) {
           onCancel={() => { setAsking(null); panel.clearNote() }}
           upload={(file) => panel.upload(file, asking)}
           readFile={panel.readFile}
-          onConfirm={async (typed, files) => { if (await panel.press(asking, typed, files)) setAsking(null) }}
+          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, a note and files when it takes them. */
-function AskDialog({ button, busy, error, onCancel, onConfirm, upload, readFile }) {
+/** "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(() => {
@@ -95,6 +107,34 @@ function AskDialog({ button, busy, error, onCancel, onConfirm, upload, readFile
         </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>
@@ -120,7 +160,7 @@ function AskDialog({ button, busy, error, onCancel, onConfirm, upload, readFile
         </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, files)} disabled={busy || missing}>
+          <button type="button" className={button.variant === 'danger' ? 'xeplr-factory-danger' : 'xeplr-factory-primary'} onClick={confirm} disabled={busy || missing}>
             {busy ? 'Working…' : button.label}
           </button>
         </footer>

package/src/designs/FedList.jsx

@@ -2,6 +2,7 @@ import { useEffect, useRef, useState } from 'react'
 import { createPortal } from 'react-dom'
 import { XeplrTable } from '@xeplr/ui-table'
 import { boxStyle, fieldStyle } from './styles.js'
+import { DATE_PRESETS, customRange, isDay } from '../listRange.js'
 
 // A LIST WHOSE ROWS A FUNCTION WORKS OUT (rowsFrom) — live, in @xeplr/ui-table.
 //
@@ -11,9 +12,10 @@ import { boxStyle, fieldStyle } from './styles.js'
 // renderer. What this file draws is only how: a second line, badges, the
 // pictures, an activity line with its hover box.
 //
-// Above the rows: the search box and the filter chips, each chip with the
-// count the function gave it. Presentation only — the query, the rows and
-// what a click does arrive as props.
+// Above the rows: a date range and KPI cards (a dashboard), then the search
+// box and the filter chips, each card and chip with the count the function
+// gave it. A card is a filter too: a click shows its rows, another lets go.
+// Presentation only — the query, the rows and what a click does arrive as props.
 
 const OPEN_DELAY_MS = 250
 const CLOSE_DELAY_MS = 200
@@ -66,8 +68,37 @@ export default function FedList({ node, list, query, onOpen, rowDetails, recordK
     if (marker) open(rows[Number(marker.getAttribute('data-xf-row'))])
   }
 
+  const kpis = Array.isArray(p.kpis) ? p.kpis : []
+  const kpiCounts = list.kpis || {}
+  const range = query.rangeFor ? query.rangeFor(node) : null
+
   return (
     <div className="xeplr-factory-list xeplr-factory-list--fed" style={style}>
+      {(range || kpis.length > 0) && (
+        <div className="xeplr-factory-dash">
+          {range && <RangePicker label={p.dateRange.label} range={range} onChange={query.setDates} />}
+          {kpis.length > 0 && (
+            <div className="xeplr-factory-kpis" role="group" aria-label={p.title ? `${p.title} at a glance` : 'At a glance'}>
+              {kpis.map((k) => {
+                const on = query.kpi === k.key
+                const n = kpiCounts[k.key]
+                return (
+                  <button
+                    key={k.key}
+                    type="button"
+                    aria-pressed={on}
+                    className={`xeplr-factory-kpi xeplr-factory-kpi--${k.tone || 'accent'}${on ? ' is-on' : ''}`}
+                    onClick={() => query.setKpi(on ? '' : k.key)}
+                  >
+                    <span className="xeplr-factory-kpi-count">{n === undefined ? '—' : n}</span>
+                    <span className="xeplr-factory-kpi-label">{k.label}</span>
+                  </button>
+                )
+              })}
+            </div>
+          )}
+        </div>
+      )}
       <div className="xeplr-factory-list-tools">
         {p.title && <span className="xeplr-factory-list-title">{p.title}</span>}
         {p.search && p.search.placeholder && (
@@ -102,7 +133,7 @@ export default function FedList({ node, list, query, onOpen, rowDetails, recordK
         {list.error && <span className="xeplr-factory-error-inline" role="alert">{list.error}</span>}
       </div>
       {rows.length === 0
-        ? !list.loading && !list.error && <div className="xeplr-factory-list-empty">{query.q ? 'Nothing matches that search.' : 'Nothing here yet.'}</div>
+        ? !list.loading && !list.error && <div className="xeplr-factory-list-empty">{query.q || query.kpi || (range && range.from) ? 'Nothing matches.' : 'Nothing here yet.'}</div>
         : (
           <div className={'xeplr-factory-fed-table' + (open ? ' is-openable' : '')} onClick={openFromRow}>
             <XeplrTable
@@ -121,6 +152,41 @@ export default function FedList({ node, list, query, onOpen, rowDetails, recordK
   )
 }
 
+/** From–To: a preset, or two days typed. Whatever is chosen is kept as one value. */
+function RangePicker({ label, range, onChange }) {
+  const custom = !range.preset
+  const [from, setFrom] = useState(range.from)
+  const [to, setTo] = useState(range.to)
+  useEffect(() => { setFrom(range.from); setTo(range.to) }, [range.from, range.to])
+  const typed = (f, t) => {
+    setFrom(f); setTo(t)
+    if ((f === '' || isDay(f)) && (t === '' || isDay(t)) && !(f && t && f > t)) onChange(customRange(f, t))
+  }
+  return (
+    <div className="xeplr-factory-range" role="group" aria-label={label ? `${label} between` : 'Dates'}>
+      {label && <span className="xeplr-factory-range-label">{label}</span>}
+      <select
+        className="xeplr-factory-range-preset"
+        aria-label={label ? `${label}: range` : 'Range'}
+        value={custom ? 'custom' : range.preset}
+        onChange={(e) => onChange(e.target.value === 'custom' ? customRange(range.from, range.to) : e.target.value)}
+      >
+        {DATE_PRESETS.map((o) => <option key={o.value} value={o.value}>{o.label}</option>)}
+        <option value="custom">Between…</option>
+      </select>
+      {(custom || range.from || range.to) && (
+        <span className="xeplr-factory-range-days">
+          <input type="date" className="xeplr-factory-range-day" aria-label="From" value={from} max={to || undefined}
+                 onChange={(e) => typed(e.target.value, to)} />
+          <span aria-hidden="true">–</span>
+          <input type="date" className="xeplr-factory-range-day" aria-label="To" value={to} min={from || undefined}
+                 onChange={(e) => typed(from, e.target.value)} />
+        </span>
+      )}
+    </div>
+  )
+}
+
 /** One cell: the server's text, and how this column draws it. */
 function Cell({ column: c, row, index, first, open, details, onOpenAt }) {
   const value = row[c.field]

package/src/designs/PropertyPanel.jsx

@@ -644,6 +644,26 @@ function ToggleEditor({ id, field, value, onChange }) {
   )
 }
 
+/** A list's date range: none, or where it starts and what the dates are. */
+function DateRangeEditor({ id, field, value, onChange }) {
+  const r = value && typeof value === 'object' ? value : null
+  return (
+    <div className="xeplr-factory-prop-stack">
+      <select id={id} className="xeplr-factory-prop-input" value={r ? (r.default || 'all') : ''} onChange={(e) => {
+        const v = e.target.value
+        onChange(v === '' ? undefined : { ...(r || {}), default: v })
+      }}>
+        <option value="">— none —</option>
+        {(field.presets || []).map((o) => <option key={o.value} value={o.value}>Starts at: {o.label}</option>)}
+      </select>
+      {r && (
+        <input className="xeplr-factory-prop-input" type="text" value={r.label || ''} placeholder='What the dates are, e.g. "Placed"'
+               onChange={(e) => { const next = { ...r, label: e.target.value }; if (!next.label) delete next.label; onChange(next) }} />
+      )}
+    </div>
+  )
+}
+
 function SelectEditor({ id, field, value, onChange }) {
   // Style selects may be unset ("inherit"); numeric option values stay numbers.
   const optional = String(field.path || '').includes('.style.') || String(field.path || '').startsWith('style.')
@@ -982,6 +1002,11 @@ 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>}
+                <AskFieldsEditor
+                  value={b.ask.fields}
+                  inputs={schema.filter((f) => f.name !== NOTE_INPUT && f.name !== FILES_INPUT && !(b.params && Object.prototype.hasOwnProperty.call(b.params, f.name)))}
+                  onChange={(fields) => edit(i, { ask: clean({ ...b.ask, fields }) })}
+                />
                 {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>}
@@ -1005,6 +1030,55 @@ function ButtonsEditor({ value, onChange, functions }) {
 
 const VARIANT_LABELS = { default: 'Ordinary', primary: 'Main', danger: 'Undo / remove' }
 
+/**
+ * The values a button's press asks for (`ask.fields`) — a parcel's size before
+ * Packed. Each is one of the function's inputs the screen does not give.
+ */
+function AskFieldsEditor({ value, inputs, onChange }) {
+  const fields = Array.isArray(value) ? value : []
+  const set = (next) => onChange(next.length ? next : undefined)
+  const edit = (j, patch) => set(fields.map((f, k) => {
+    if (k !== j) return f
+    const next = { ...f, ...patch }
+    Object.keys(next).forEach((key) => { if (next[key] === undefined || next[key] === '' || next[key] === false) delete next[key] })
+    return next
+  }))
+  const free = inputs.filter((f) => !fields.some((a) => a.name === f.name))
+  const typeOf = (f) => (f && f.type === 'number' ? 'number' : 'text')
+  if (!inputs.length && !fields.length) return null
+  return (
+    <div className="xeplr-factory-rows-editor">
+      <div className="xeplr-factory-prop-label">Asks for</div>
+      {fields.map((f, j) => (
+        <fieldset key={f.name || j} className="xeplr-factory-rows-editor-card">
+          <legend>{f.label || f.name}</legend>
+          <RowTools i={j} count={fields.length} onMove={(to) => set(move(fields, j, to))} onRemove={() => set(fields.filter((_, k) => k !== j))} />
+          <MiniField label="Input"><input className="xeplr-factory-prop-input" value={f.name} readOnly /></MiniField>
+          <MiniField label="Label"><input className="xeplr-factory-prop-input" value={f.label || ''} onChange={(e) => edit(j, { label: e.target.value })} /></MiniField>
+          <MiniField label="Unit" help='e.g. "in", "kg"'><input className="xeplr-factory-prop-input" value={f.unit || ''} maxLength={12} onChange={(e) => edit(j, { unit: e.target.value })} /></MiniField>
+          {f.type === 'number' && (
+            <MiniField label="At least"><input className="xeplr-factory-prop-input" type="number" value={f.min ?? ''} onChange={(e) => edit(j, { min: e.target.value === '' ? undefined : Number(e.target.value) })} /></MiniField>
+          )}
+          <MiniField label="Starts from" help="A field of the record — asked again, it shows the last value"><input className="xeplr-factory-prop-input" value={f.fill || ''} onChange={(e) => edit(j, { fill: e.target.value })} /></MiniField>
+          <label className="xeplr-factory-toggle">
+            <input type="checkbox" checked={Boolean(f.required)} onChange={(e) => edit(j, { required: e.target.checked })} />
+            <span>Required</span>
+          </label>
+        </fieldset>
+      ))}
+      {free.length > 0 && (
+        <select className="xeplr-factory-prop-input" value="" aria-label="Ask for another input" onChange={(e) => {
+          const f = free.find((x) => x.name === e.target.value)
+          if (f) set([...fields, { name: f.name, label: f.label || f.name, type: typeOf(f) }])
+        }}>
+          <option value="">+ Ask for…</option>
+          {free.map((f) => <option key={f.name} value={f.name}>{f.label || f.name}</option>)}
+        </select>
+      )}
+    </div>
+  )
+}
+
 /**
  * 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".
@@ -1168,6 +1242,7 @@ export const EDITORS = {
   toggle: ToggleEditor,
   toggleValue: ToggleValueEditor,
   select: SelectEditor,
+  dateRange: DateRangeEditor,
   font: FontEditor,
   color: ColorEditor,
   table: TableEditor,

package/src/designs/factory.css

@@ -323,6 +323,34 @@
    Search and chips over the rows; every cell is text the server wrote. */
 .xeplr-factory-list--fed { overflow: hidden; }
 .xeplr-factory-list--fed .xeplr-table-container { border: none; border-radius: 0; background: transparent; }
+/* A dashboard over the rows: the date range, then a card per KPI — a count,
+   and a filter (pressed: its rows). */
+.xeplr-factory-dash { display: flex; flex-direction: column; gap: 12px; padding: 14px; border-bottom: 1px solid var(--xf-border); }
+.xeplr-factory-range { display: flex; flex-wrap: wrap; align-items: center; gap: 8px; color: var(--xf-ink); }
+.xeplr-factory-range-label { font-weight: 600; }
+.xeplr-factory-range-days { display: inline-flex; align-items: center; gap: 6px; color: var(--xf-muted); }
+.xeplr-factory-range-preset, .xeplr-factory-range-day {
+  font: inherit; color: var(--xf-ink); background: var(--xf-field-bg); border: 1px solid var(--xf-field-border);
+  border-radius: 8px; padding: 6px 10px; min-height: 36px; box-sizing: border-box;
+}
+.xeplr-factory-kpis { display: grid; grid-template-columns: repeat(auto-fit, minmax(150px, 1fr)); gap: 10px; }
+.xeplr-factory-kpi {
+  --xf-kpi: var(--xf-accent);
+  display: flex; flex-direction: column; align-items: flex-start; gap: 2px; text-align: left; cursor: pointer;
+  font: inherit; color: var(--xf-ink); background: var(--xf-field-bg);
+  border: 1px solid var(--xf-border); border-left: 4px solid var(--xf-kpi); border-radius: 10px; padding: 12px 14px;
+}
+.xeplr-factory-kpi:hover { background: var(--xf-hover); }
+.xeplr-factory-kpi:focus-visible { outline: none; box-shadow: 0 0 0 3px color-mix(in srgb, var(--xf-kpi) 35%, transparent); }
+.xeplr-factory-kpi.is-on { background: color-mix(in srgb, var(--xf-kpi) 12%, var(--xf-field-bg)); border-color: var(--xf-kpi); }
+.xeplr-factory-kpi--success { --xf-kpi: var(--xf-good); }
+.xeplr-factory-kpi--warning { --xf-kpi: var(--xf-warn); }
+.xeplr-factory-kpi--danger { --xf-kpi: var(--xf-danger); }
+.xeplr-factory-kpi--muted { --xf-kpi: var(--xf-muted); }
+.xeplr-factory-kpi-count { font-size: 1.9em; font-weight: 700; line-height: 1.1; font-variant-numeric: tabular-nums; }
+.xeplr-factory-kpi-label { color: var(--xf-muted); font-size: .92em; }
+.xeplr-factory-kpi.is-on .xeplr-factory-kpi-label { color: var(--xf-ink); }
+
 .xeplr-factory-list-tools {
   display: flex; flex-wrap: wrap; align-items: center; gap: 10px; padding: 12px 14px;
   border-bottom: 1px solid var(--xf-border);
@@ -417,6 +445,15 @@ button.xeplr-factory-activity-item:hover, button.xeplr-factory-activity-item:foc
   color: var(--xf-ink); background: var(--xf-field-bg); border: 1px solid var(--xf-field-border);
 }
 .xeplr-factory-ask-note { resize: vertical; min-height: 80px; }
+.xeplr-factory-ask-fields { display: grid; grid-template-columns: repeat(auto-fit, minmax(120px, 1fr)); gap: 10px 12px; }
+.xeplr-factory-ask-value { display: flex; align-items: center; gap: 6px; }
+.xeplr-factory-ask-input {
+  flex: 1 1 auto; min-width: 0; font: inherit; color: var(--xf-ink); background: var(--xf-field-bg);
+  border: 1px solid var(--xf-field-border); border-radius: 8px; padding: 7px 10px; box-sizing: border-box;
+}
+.xeplr-factory-ask-input[aria-invalid] { border-color: var(--xf-danger); }
+.xeplr-factory-ask-unit { color: var(--xf-muted); white-space: nowrap; min-width: 1.6em; }
+.xeplr-factory-ask-field-error { color: var(--xf-danger); font-size: .88em; }
 .xeplr-factory-ask-note:focus, .xeplr-factory-list-search:focus { outline: none; border-color: var(--xf-accent); box-shadow: 0 0 0 3px color-mix(in srgb, var(--xf-accent) 25%, transparent); }
 .xeplr-factory-ask-error { margin: 0; color: var(--xf-danger); }
 .xeplr-factory-ask-foot { display: flex; justify-content: flex-end; gap: 8px; padding: 12px 18px 16px; }
@@ -863,11 +900,18 @@ button.xeplr-factory-activity-item:hover, button.xeplr-factory-activity-item:foc
 /* Function-fed lists and buttons on a phone: the search takes the width, chips
    scroll in a row, and every button is a thumb-sized target. */
 @media (max-width: 640px) {
-  .xeplr-factory-list-search, .xeplr-factory-ask-note { font-size: max(16px, 1em); min-height: 44px; }
+  .xeplr-factory-list-search, .xeplr-factory-ask-note, .xeplr-factory-ask-input { font-size: max(16px, 1em); min-height: 44px; }
+  .xeplr-factory-ask-fields { grid-template-columns: repeat(2, minmax(0, 1fr)); }
   .xeplr-factory-list-search { flex-basis: 100%; max-width: none; }
   .xeplr-factory-ask-foot button { flex: 1; min-height: 44px; }
   .xeplr-factory-chips { flex-wrap: nowrap; overflow-x: auto; max-width: 100%; padding-bottom: 2px; }
   .xeplr-factory-chip { min-height: 36px; }
+  .xeplr-factory-kpis { grid-template-columns: repeat(2, minmax(0, 1fr)); }
+  .xeplr-factory-range-preset, .xeplr-factory-range-day { font-size: max(16px, 1em); min-height: 44px; }
+  .xeplr-factory-range-preset { flex: 1 1 100%; }
+  .xeplr-factory-range-days { flex: 1 1 100%; min-width: 0; }
+  /* A date box's own width is the browser's; let the row decide instead. */
+  .xeplr-factory-range-day { flex: 1 1 0; min-width: 0; width: 0; }
   .xeplr-factory-button { min-height: 44px; flex: 1 1 auto; }
   .xeplr-factory-buttons-note { flex-basis: 100%; }
   .xeplr-factory-ask .xeplr-factory-modal-body { padding: 4px 16px 8px; }

package/src/listRange.js

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

package/src/model.js

@@ -17,7 +17,7 @@ export { SCREEN_EVENTS, SCREEN_EVENT_KEYS, DECIDE_EVENT, FUNCTION_NAME, screenFu
 // 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, FILES_INPUT, CONDITION_OPERATORS,
-  conditionMet, buttonShown, buttonDisabled, buttonPressed, screenButtons, buttonById, buttonInput, askFile, askFileProblem, nodeFunctions, paramProblems, optionValues
+  conditionMet, buttonShown, buttonDisabled, buttonPressed, screenButtons, buttonById, buttonInput, askFile, askFileProblem, askFields, askFieldStart, askFieldValues, ASK_FIELD_TYPES, nodeFunctions, paramProblems, optionValues
 } from './buttons.js'
 // Which pages are drawn from documents and which are web only (ui/pages.json).
 export { checkInventory, routesIn, pageWarnings, webOnlyMenus } from './pagesInventory.js'
@@ -43,3 +43,5 @@ export {
   addTransition, setTransition, removeTransition, firstStep, reachableSteps, layoutFlow, validateFlow, describeWhen,
   arrowTargets, navigationOf, setNavigation
 } from './flow.js'
+// A function-fed list's date range: presets → days, and what a day is.
+export { DATE_PRESETS, DATE_PRESET_VALUES, resolveRange, customRange, isDay, dayOf } from './listRange.js'

package/src/remote.js

@@ -132,14 +132,15 @@ export function createFactoryApi({ fetch: doFetch, fetchFile, base = '' } = {})
 
     // ROWS A FUNCTION WORKS OUT, for a list with rowsFrom: { rows, counts }.
     // Only what the person typed goes with it — the function is the screen's.
-    fetchRows: async ({ screen, node, q, filter }) => one(await call('GET', `/rows/${enc(screen)}${query({ node, q, filter })}`)),
+    fetchRows: async ({ screen, node, q, filter, kpi, from, to }) => one(await call('GET', `/rows/${enc(screen)}${query({ node, q, filter, kpi, from, to })}`)),
     // An activity cell's hover box for one row.
     fetchRowDetails: ({ screen, node, column, id }) => call('GET', `/rows/${enc(screen)}/details${query({ node, column, id })}`),
     // A button's press on one record → { button, message, output }. The
     // server reads the button — its function and parameters — from the
     // published screen; the request names it and carries the note.
-    pressButton: async ({ screen, button, id, note, files }) => one(await call('POST', `/buttons/${enc(screen)}/${enc(button)}`, {
-      id, ...(note ? { note } : {}), ...(Array.isArray(files) && files.length ? { files } : {})
+    pressButton: async ({ screen, button, id, note, files, values }) => one(await call('POST', `/buttons/${enc(screen)}/${enc(button)}`, {
+      id, ...(note ? { note } : {}), ...(Array.isArray(files) && files.length ? { files } : {}),
+      ...(values && Object.keys(values).length ? { values } : {})
     })),
     // A file a button's ask.file takes, stored before the press; the press
     // then names it by the path this answers with.

package/src/urlState.js

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

package/src/useFactoryScreen.js

@@ -6,6 +6,7 @@ import { initialValues, parseInput, saveState, fieldError, optionValue, recordVa
 import { hookMethod } from './hooks.js'
 import { useUrlSteps, useUrlListQuery } from './useUrlPlaces.js'
 import { buttonShown, buttonDisabled, buttonPressed } from './buttons.js'
+import { resolveRange, dayOf } from './listRange.js'
 
 // A saved screen, running. No JSX — designs/ScreenSample.jsx draws it.
 //
@@ -59,9 +60,9 @@ import { buttonShown, buttonDisabled, buttonPressed } from './buttons.js'
  * @param onDirtyChange (dirty) → void — whether there are unsaved changes, as that changes
  * @param controls      the control registry (default: the built-ins)
  * @param hooks         a FactoryHooks (or an object with some of its methods) — get / save / delete / actions
- * @param fetchRows     async ({ screen, node, q, filter }) → { rows, counts } — a list whose rows a function works out (rowsFrom)
+ * @param fetchRows     async ({ screen, node, q, filter, kpi, from, to }) → { rows, counts, kpis } — a list whose rows a function works out (rowsFrom)
  * @param fetchRowDetails async ({ screen, node, column, id }) → [{ text, sub?, at?, open? }] — an activity cell's hover box
- * @param pressButton   async ({ screen, button, id, note, files }) → { message } — a button's press, run on the server
+ * @param pressButton   async ({ screen, button, id, note, files, values }) → { message } — a button's press, run on the server
  * @param uploadButtonFile async (file, { screen, button }) → { path } — a file a button's `ask.file` takes, stored before the press
  * @param readFile      async (path) → Blob — an attached file's bytes: a picture's preview (no preview without it)
  * @param onButtonDone  ({ button, result, record }) → void — after a press: the host reloads what it shows
@@ -612,6 +613,15 @@ export function useFactoryScreen({
   // rows. The search waits for a pause in typing before it asks.
   const [listQ, setListQ] = useUrlListQuery(urlKey, 'q')
   const [listFilter, setListFilter] = useUrlListQuery(urlKey, 'filter')
+  // A dashboard's KPI card (clicked: its rows) and date range (a preset, or
+  // "from..to"), in the URL too. The range is turned into days when asked.
+  const [listKpi, setListKpi] = useUrlListQuery(urlKey, 'kpi')
+  const [listDates, setListDates] = useUrlListQuery(urlKey, 'dates')
+  const rangeFor = useCallback((node) => {
+    const r = node && node.props && node.props.dateRange
+    if (!r) return null
+    return resolveRange(listDates || r.default || 'all', dayOf(new Date()), r.default || 'all')
+  }, [listDates])
   const [askedQ, setAskedQ] = useState(listQ)
   useEffect(() => {
     if (askedQ === listQ) return undefined
@@ -635,14 +645,21 @@ export function useFactoryScreen({
       const run = Promise.resolve().then(() => hook('get')({
         many: true, id: null, screen: doc.id, source: src, node, document: doc,
         steps: live.current.steps,
-        query: fed ? { q: askedQ, filter: listFilter } : undefined,
+        query: fed ? { q: askedQ, filter: listFilter, kpi: listKpi, ...(rangeFor(node) || {}) } : undefined,
         defaults: {
           get: () => {
             // ROWS A FUNCTION WORKS OUT: the server runs the list's rowsFrom
             // with the search and the chip, and answers { rows, counts }.
             if (fed) {
               if (!fetchRowsRef.current) throw new Error(`No fetchRows was provided — the list's rows come from "${node.props.rowsFrom}"`)
-              return fetchRowsRef.current({ screen: doc.id, node: node.id, q: askedQ, filter: listFilter || undefined })
+              const range = rangeFor(node)
+              const kpis = Array.isArray(node.props.kpis) ? node.props.kpis : []
+              return fetchRowsRef.current({
+                screen: doc.id, node: node.id, q: askedQ, filter: listFilter || undefined,
+                kpi: kpis.some((k) => k.key === listKpi) ? listKpi : undefined,
+                from: range && range.from ? range.from : undefined,
+                to: range && range.to ? range.to : undefined
+              })
             }
             if (!fetchRecordsRef.current) throw new Error(`No fetchRecords was provided to list "${src}"`)
             // A SUB-TABLE IS THIS RECORD'S. `belongsTo` names the column on
@@ -663,15 +680,21 @@ export function useFactoryScreen({
           if (cancelled) return
           const rows = Array.isArray(out) ? out : out && Array.isArray(out.rows) ? out.rows : []
           const counts = out && !Array.isArray(out) && out.counts ? out.counts : {}
-          setLists((l) => ({ ...l, [node.id]: { rows, counts, loading: false, error: null } }))
+          const kpis = out && !Array.isArray(out) && out.kpis ? out.kpis : {}
+          setLists((l) => ({ ...l, [node.id]: { rows, counts, kpis, loading: false, error: null } }))
         })
         .catch((err) => { if (!cancelled) setLists((l) => ({ ...l, [node.id]: { rows: l[node.id]?.rows || [], counts: l[node.id]?.counts || {}, loading: false, error: err.message || 'Could not load records' } })) })
     })
     return () => { cancelled = true }
-  }, [listNodes, listVersion, doc, askedQ, listFilter, reloadKey]) // eslint-disable-line react-hooks/exhaustive-deps
+  }, [listNodes, listVersion, doc, askedQ, listFilter, listKpi, rangeFor, reloadKey]) // eslint-disable-line react-hooks/exhaustive-deps
 
   /** What a function-fed list is narrowed to, and how to change it. */
-  const listQuery = useMemo(() => ({ q: listQ, filter: listFilter, setQ: setListQ, setFilter: setListFilter }), [listQ, listFilter, setListQ, setListFilter])
+  const listQuery = useMemo(() => ({
+    q: listQ, filter: listFilter, setQ: setListQ, setFilter: setListFilter,
+    kpi: listKpi, setKpi: setListKpi,
+    // The range a list shows (its own default until one is chosen), and choosing one.
+    rangeFor, setDates: setListDates
+  }), [listQ, listFilter, setListQ, setListFilter, listKpi, setListKpi, rangeFor, setListDates])
 
   /** An activity cell's hover box: the column's function, for one row. */
   const fetchRowDetailsRef = useRef(fetchRowDetails); fetchRowDetailsRef.current = fetchRowDetails
@@ -853,12 +876,12 @@ export function useFactoryScreen({
       if (!out || !out.path) throw new Error('The upload did not answer with the stored file')
       return out
     },
-    press: async (b, typed, files) => {
+    press: async (b, typed, files, values) => {
       if (!pressRef.current) { setButtonNote({ kind: 'error', text: 'No pressButton was provided', button: b.id }); return false }
       setPressing(b.id)
       setButtonNote(null)
       try {
-        const result = await pressRef.current({ screen: doc.id, button: b.id, id: recordId, note: typed, files })
+        const result = await pressRef.current({ screen: doc.id, button: b.id, id: recordId, note: typed, files, values })
         setButtonNote({ kind: 'done', text: (result && result.message) || `${b.label} — done`, button: b.id })
         setListVersion((v) => v + 1)
         if (buttonDoneRef.current) buttonDoneRef.current({ button: b, result, record: buttonRecord })

package/src/validateDocument.js

@@ -13,10 +13,11 @@
 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, FILE_SOURCES, IMAGE_EXTENSIONS, MAX_FILES } from './controls.js'
 import { DOCUMENT_KIND, DOCUMENT_VERSION } from './document.js'
+import { DATE_PRESET_VALUES } from './listRange.js'
 import { RESERVED_COLUMNS, MAX_IDENTIFIER } from './tableSchema.js'
 import { FIELD_PRESETS, INPUT_TYPES, presetFor } from './presets.js'
 import { isBinding } from './values.js'
-import { BUTTON_VARIANTS, COLUMN_DISPLAYS, BADGE_TONES, CONDITION_OPERATORS } from './buttons.js'
+import { BUTTON_VARIANTS, COLUMN_DISPLAYS, BADGE_TONES, CONDITION_OPERATORS, ASK_FIELD_TYPES, NOTE_INPUT, FILES_INPUT } from './buttons.js'
 
 const FIELD_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/
 const TABLE_NAME = /^[A-Za-z_][A-Za-z0-9_.$-]*$/
@@ -508,6 +509,35 @@ function checkFedList(props, fed, at, err) {
       })
     }
   }
+  need('kpis', 'KPI cards')
+  need('dateRange', 'a date range')
+  if (props.kpis !== undefined) {
+    if (!Array.isArray(props.kpis)) err(`${at}.props.kpis`, 'must be an array of { key, label, tone? }')
+    else {
+      const keys = new Set()
+      props.kpis.forEach((k, j) => {
+        const p = `${at}.props.kpis[${j}]`
+        if (!k || typeof k !== 'object') { err(p, 'must be { key, label, tone? }'); return }
+        if (!(nonEmptyString(k.key) && /^[A-Za-z0-9_-]+$/.test(k.key))) err(`${p}.key`, 'must be letters, digits, _ or - — what the function is asked for, e.g. "open"')
+        else if (keys.has(k.key)) err(`${p}.key`, `"${k.key}" appears twice`)
+        else keys.add(k.key)
+        if (!nonEmptyString(k.label)) err(`${p}.label`, 'must be the card\'s text, e.g. "Open"')
+        if (k.tone !== undefined && !BADGE_TONES.includes(k.tone)) err(`${p}.tone`, `must be one of: ${BADGE_TONES.join(', ')}`)
+        const extra = Object.keys(k).filter((x) => !['key', 'label', 'tone'].includes(x))
+        if (extra.length) err(p, `only "key", "label" and "tone" are used — remove: ${extra.join(', ')}`)
+      })
+    }
+  }
+  if (props.dateRange !== undefined) {
+    const d = props.dateRange
+    if (!d || typeof d !== 'object' || Array.isArray(d)) err(`${at}.props.dateRange`, 'must be { label?, default? } — the range the function is asked for')
+    else {
+      const extra = Object.keys(d).filter((x) => x !== 'label' && x !== 'default')
+      if (extra.length) err(`${at}.props.dateRange`, `only "label" and "default" are used — remove: ${extra.join(', ')}`)
+      if (d.label !== undefined && typeof d.label !== 'string') err(`${at}.props.dateRange.label`, 'must be a string, e.g. "Placed"')
+      if (d.default !== undefined && !DATE_PRESET_VALUES.includes(d.default)) err(`${at}.props.dateRange.default`, `must be one of: ${DATE_PRESET_VALUES.join(', ')}`)
+    }
+  }
   if (props.refreshEvery !== undefined && !(Number.isInteger(props.refreshEvery) && props.refreshEvery >= 10 && props.refreshEvery <= 3600)) {
     err(`${at}.props.refreshEvery`, 'must be a whole number of seconds from 10 to 3600')
   }
@@ -557,6 +587,36 @@ const ASK_FILE_KEYS = ['label', 'required', 'accept', 'maxSize', 'multiple', 'ma
  * server checks the names against what is registered when the screen is
  * published (functionProblems). Here: the shape.
  */
+const ASK_FIELD_KEYS = ['name', 'label', 'type', 'unit', 'required', 'min', 'max', 'fill']
+
+/** A button's `ask.fields`: the values a press asks for, each reaching the function under its name. */
+function checkAskFields(fields, params, at, err) {
+  if (!Array.isArray(fields)) { err(at, 'must be a list of { name, label, type, unit?, required?, min?, max?, fill? }'); return }
+  const seen = new Set()
+  fields.forEach((f, i) => {
+    const p = `${at}[${i}]`
+    if (!f || typeof f !== 'object' || Array.isArray(f)) { err(p, 'must be { name, label, type, … }'); return }
+    const bad = Object.keys(f).filter((k) => !ASK_FIELD_KEYS.includes(k))
+    if (bad.length) err(p, `only ${ASK_FIELD_KEYS.map((k) => `"${k}"`).join(', ')} are used — remove: ${bad.join(', ')}`)
+    if (!(nonEmptyString(f.name) && /^[A-Za-z][A-Za-z0-9_]{0,62}$/.test(f.name))) err(`${p}.name`, 'must be letters, digits or _ — what the function receives it as, e.g. "lengthIn"')
+    else if (seen.has(f.name)) err(`${p}.name`, `"${f.name}" is asked twice`)
+    else if (f.name === NOTE_INPUT || f.name === FILES_INPUT) err(`${p}.name`, `"${f.name}" is the note's or the files' own name — use ask.note or ask.file`)
+    else if (params && Object.prototype.hasOwnProperty.call(params, f.name)) err(`${p}.name`, `"${f.name}" is already one of the button's parameters — the screen gives it, so nobody should be asked`)
+    else seen.add(f.name)
+    if (!nonEmptyString(f.label)) err(`${p}.label`, 'must be what the person sees, e.g. "Length"')
+    if (!ASK_FIELD_TYPES.includes(f.type)) err(`${p}.type`, `must be one of: ${ASK_FIELD_TYPES.join(', ')}`)
+    if (f.unit !== undefined && !(typeof f.unit === 'string' && f.unit.length <= 12)) err(`${p}.unit`, 'must be a short text, e.g. "in" or "kg"')
+    if (f.required !== undefined && typeof f.required !== 'boolean') err(`${p}.required`, 'must be true or false')
+    ;['min', 'max'].forEach((k) => {
+      if (f[k] === undefined) return
+      if (f.type !== 'number') err(`${p}.${k}`, 'is for a number field')
+      else if (!Number.isFinite(f[k])) err(`${p}.${k}`, 'must be a number')
+    })
+    if (Number.isFinite(f.min) && Number.isFinite(f.max) && f.min > f.max) err(`${p}.min`, 'is more than max')
+    if (f.fill !== undefined && !(nonEmptyString(f.fill) && /^[A-Za-z_][A-Za-z0-9_]*$/.test(f.fill))) err(`${p}.fill`, 'must be a field of the record, e.g. "parcelLengthIn"')
+  })
+}
+
 function checkAskFile(f, at, err) {
   if (!f || typeof f !== 'object' || Array.isArray(f)) { err(at, 'must be { label?, accept, maxSize?, multiple?, maxFiles?, source?, required? } — the file a press takes'); return }
   const bad = Object.keys(f).filter((k) => !ASK_FILE_KEYS.includes(k))
@@ -591,10 +651,11 @@ function checkButtons(props, at, err, ids) {
     if (b.ask !== undefined) {
       if (!b.ask || typeof b.ask !== 'object' || Array.isArray(b.ask)) err(`${p}.ask`, 'must be { title?, message?, note? } — what the person is asked before it runs')
       else {
-        const bad = Object.keys(b.ask).filter((k) => !ASK_KEYS.includes(k) && k !== 'file')
-        if (bad.length) err(`${p}.ask`, `only ${[...ASK_KEYS, 'file'].map((k) => `"${k}"`).join(', ')} are used — remove: ${bad.join(', ')}`)
+        const bad = Object.keys(b.ask).filter((k) => !ASK_KEYS.includes(k) && k !== 'file' && k !== 'fields')
+        if (bad.length) err(`${p}.ask`, `only ${[...ASK_KEYS, 'file', 'fields'].map((k) => `"${k}"`).join(', ')} are used — remove: ${bad.join(', ')}`)
         ASK_KEYS.forEach((k) => { if (b.ask[k] !== undefined && typeof b.ask[k] !== 'string') err(`${p}.ask.${k}`, 'must be a string') })
         if (b.ask.file !== undefined) checkAskFile(b.ask.file, `${p}.ask.file`, err)
+        if (b.ask.fields !== undefined) checkAskFields(b.ask.fields, b.params, `${p}.ask.fields`, err)
       }
     }
     if (b.variant !== undefined && !BUTTON_VARIANTS.includes(b.variant)) err(`${p}.variant`, `must be one of: ${BUTTON_VARIANTS.join(', ')}`)