@xeplr/ui-factory 1.8.0 → 1.8.2

package/README.md

@@ -573,6 +573,21 @@ run is only what the arrows need and the id of the row that was written
 that exists, arrows that point somewhere, one "otherwise" at the end, and
 nothing unreachable.
 
+### A review screen inside a workflow
+
+A screen can also be one step of an ordinary Xeplr Workflow: the run parks on it until a person answers. The workflow step says what it is handed, who answers it and with which buttons:
+
+```json
+{ "actionName": "screen-show", "kind": "wait",
+  "values": { "screen": "unmatched_review", "values": { "lines": "{steps.match.output.rows}" },
+              "assignTo": "Accounts", "buttons": [{ "key": "approve", "label": "Approve" }, { "key": "send_back", "label": "Send back" }] } }
+```
+
+- **A `table` shows what it was handed** (`rows: '{params.lines}'`, a screen input), with a tick per row; the ticked rows are the field's value (`selected`).
+- **The step's buttons replace Next** in `FlowRunner` (the first is the main one). The one pressed is sent as `action` and becomes the step's `output.action`, so its arrows branch on it.
+- **A screen with no table of its own saves nothing**: a button goes straight to the run.
+- `createFlowsApi(...).waiting()` lists every screen waiting for one of the signed-in person's roles (`GET /flows/waiting`).
+
 ### A flow and a stepper
 
 Both walk someone through something, and they answer different questions:
@@ -602,6 +617,7 @@ Both walk someone through something, and they answer different questions:
 | `stepper` | — | a journey across the top; every other control says which step it is on |
 | `label` | — | text with a heading, subheading or text preset |
 | `list` | — | saved records, with New / Edit / Delete |
+| `table` | array of the rows ticked | `minItems`, `maxItems`; `required` = at least one. Rows the screen is **handed** (`rows: '{params.lines}'`), not a table it reads; `columns` (`ref, amount`) or every key of the first row; `selectable` (a tick per row, on by default). Adds no column — see below |
 | `subform` | — | another form drawn inside this one (palette: **Form**), saving into its own table — see below |
 
 A screen is a **sheet**, centred in the space it is given and shown at its

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xeplr/ui-factory",
-  "version": "1.8.0",
+  "version": "1.8.2",
   "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/controls.js

@@ -576,6 +576,59 @@ CONTROLS.list = {
   ]
 }
 
+// A TABLE OF ROWS THE WORKFLOW HANDS THE SCREEN — the unmatched bank lines
+// a person reviews — with a tick per row. Its value is the rows ticked, under
+// its name (default `selected`), so the step's output.selected is what the
+// person chose. The rows come from a binding to the screen's inputs
+// (`rows: '{params.lines}'`), filled by the workflow step's `values`.
+//
+// Not a list: a list reads a database table; this shows what the run already
+// has, and saves nothing of its own (no column: columnForField ignores it).
+CONTROLS.table = {
+  type: 'table',
+  label: 'Table',
+  group: 'Data',
+  input: true,
+  valueType: 'array',
+  defaultSize: { w: 0.92, h: 0.42 },
+  defaults: { label: 'Rows', rows: '{params.rows}', selectable: true, columns: '' },
+  props: ['name', 'label', 'required', 'rows', 'columns', 'selectable', 'validation', 'style'],
+  validation: ['minItems', 'maxItems'],
+  styles: ['fontFamily', 'fontSize', 'color', 'background', 'borderColor', 'borderWidth', 'borderRadius'],
+  properties: [
+    FIELD_BASICS(),
+    {
+      key: 'table',
+      title: 'Rows',
+      fields: [
+        { path: 'props.rows', label: 'Rows from', type: 'text',
+          help: 'One of this screen\'s inputs, e.g. {params.lines}. The workflow step fills it.' },
+        { path: 'props.columns', label: 'Columns', type: 'text',
+          help: 'Which, in order, e.g. ref, amount, date. Blank: every column of the first row.' },
+        { path: 'props.selectable', label: 'A tick per row', type: 'checkbox',
+          help: 'The ticked rows are what this field gives the workflow.' }
+      ]
+    },
+    {
+      key: 'validation',
+      title: 'Validation',
+      fields: [
+        { path: 'props.validation.minItems', label: 'Tick at least', type: 'number' },
+        { path: 'props.validation.maxItems', label: 'Tick at most', type: 'number' }
+      ]
+    },
+    ...styleGroups(['fontFamily', 'fontSize', 'color', 'background', 'borderColor', 'borderWidth', 'borderRadius'])
+  ]
+}
+
+/** The columns a table shows: its own list, else every key of the first row. */
+export function tableColumns(p, rows) {
+  const listed = String((p && p.columns) || '').split(',').map((c) => c.trim()).filter(Boolean)
+  if (listed.length) return listed
+  const first = (rows || []).find((r) => r && typeof r === 'object')
+  return first ? Object.keys(first) : []
+}
+
 // A FORM INSIDE THIS ONE — Access's subform. Another published form, drawn
 // inline with its own fields, saving into ITS OWN table: this employee's bank
 // details. One record of it belongs to each record of this one, through

package/src/designs/ControlView.jsx

@@ -1,5 +1,5 @@
 import { useState } from 'react'
-import { LABEL_PRESETS } from '../controls.js'
+import { tableColumns, LABEL_PRESETS } from '../controls.js'
 import { stepsOf } from '../document.js'
 import ListView from './ListView.jsx'
 import { fieldStyle, labelStyle, boxStyle } from './styles.js'
@@ -13,7 +13,7 @@ import { fieldStyle, labelStyle, boxStyle } from './styles.js'
 
 const ids = (node) => `xeplr-factory-${node.id}`
 
-export default function ControlView({ node, mode = 'live', value, error, options, onChange, onBlur, disabled, list, upload, stepper, subform }) {
+export default function ControlView({ node, mode = 'live', value, error, options, onChange, onBlur, disabled, list, upload, stepper, subform, rows }) {
   const View = VIEWS[node.type]
   if (!View) {
     return <div className="xeplr-factory-unknown">Unknown control “{node.type}”</div>
@@ -34,6 +34,7 @@ export default function ControlView({ node, mode = 'live', value, error, options
       upload={upload}
       stepper={stepper}
       subform={subform}
+      rows={rows}
     />
   )
 }
@@ -459,6 +460,65 @@ function SubformView({ p, node, design, subform }) {
   )
 }
 
+// Rows the workflow handed the screen, a tick per row. The value is the rows
+// ticked. In the designer: three placeholder rows, so it reads as a table.
+function TableView({ node, p, design, value, error, onChange, disabled, rows }) {
+  const shown = design ? [{ ref: 'A1', amount: 500 }, { ref: 'A2', amount: 20 }, { ref: 'A3', amount: 75 }] : (rows || [])
+  const columns = tableColumns(p, shown)
+  const chosen = Array.isArray(value) ? value : []
+  const selectable = p.selectable !== false
+  const ticked = (row) => chosen.some((c) => c === row || JSON.stringify(c) === JSON.stringify(row))
+  const toggle = (row, on) => {
+    const rest = chosen.filter((c) => !(c === row || JSON.stringify(c) === JSON.stringify(row)))
+    onChange(on ? [...rest, row] : rest)
+  }
+  const all = shown.length > 0 && shown.every(ticked)
+  const text = boxStyle(p.style)
+  return (
+    <Field node={node} p={p} error={error}>
+      <div className="xeplr-factory-table-wrap" role="group" aria-labelledby={`${ids(node)}-label`}>
+        {shown.length === 0 ? (
+          <div className="xeplr-factory-hint">Nothing to show.</div>
+        ) : (
+          <table className="xeplr-factory-table" style={{ fontSize: text.fontSize, color: text.color }}>
+            <thead>
+              <tr>
+                {selectable && (
+                  <th className="xeplr-factory-table-tick">
+                    <input type="checkbox" aria-label="Tick every row" checked={all} disabled={disabled}
+                      onChange={(e) => onChange(e.target.checked ? shown.slice() : [])} />
+                  </th>
+                )}
+                {columns.map((c) => <th key={c}>{c}</th>)}
+              </tr>
+            </thead>
+            <tbody>
+              {shown.map((row, i) => (
+                <tr key={i} className={selectable && ticked(row) ? 'is-ticked' : undefined}>
+                  {selectable && (
+                    <td className="xeplr-factory-table-tick">
+                      <input type="checkbox" aria-label={'Row ' + (i + 1)} checked={ticked(row)} disabled={disabled}
+                        onChange={(e) => toggle(row, e.target.checked)} />
+                    </td>
+                  )}
+                  {columns.map((c) => {
+                    const v = row ? row[c] : null
+                    return <td key={c} className={typeof v === 'number' ? 'is-number' : undefined}>{v === null || v === undefined ? '' : typeof v === 'object' ? JSON.stringify(v) : String(v)}</td>
+                  })}
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        )}
+      </div>
+      {!design && selectable && shown.length > 0 && (
+        <div className="xeplr-factory-hint">{chosen.length} of {shown.length} ticked</div>
+      )}
+      {design && <div className="xeplr-factory-hint">Rows from {p.rows || '— set "Rows from"'}</div>}
+    </Field>
+  )
+}
+
 function ListControl({ node, design, list }) {
   return <ListView node={node} design={design} {...(list || {})} />
 }
@@ -478,5 +538,6 @@ export const VIEWS = {
   stepper: StepperView,
   label: LabelView,
   list: ListControl,
+  table: TableView,
   subform: SubformView
 }

package/src/designs/FlowRunnerSample.jsx

@@ -1,7 +1,8 @@
 import { useRef } from 'react'
 import ScreenSample from './ScreenSample.jsx'
 
-// A flow, running: the screen the run is parked on, and one button forward.
+// A flow, running: the screen the run is parked on, and the way forward — one
+// Next, or the step's own buttons (Approve / Send back), each saying which.
 //
 // Presentation only — everything comes from useFlowRun and useFactoryScreen.
 // "Next" saves the screen into its own table (one AJAX call, only if anything
@@ -49,8 +50,11 @@ export default function FlowRunnerSample({ run, screen, className, style, title,
           // not two that both look like the way on.
           // The id comes from the save that Next just made when there was one:
           // a new record's id has not reached the ref yet (that is a render away).
-          done: (r) => run.submit(values.current, r && r.record && r.record[screen.recordKey] != null ? r.record[screen.recordKey] : record.current),
-          doneLabel: run.sending ? 'Saving…' : 'Next'
+          done: (r, action) => run.submit(values.current, r && r.record && r.record[screen.recordKey] != null ? r.record[screen.recordKey] : record.current, action),
+          doneLabel: run.sending ? 'Saving…' : 'Next',
+          // The step's own buttons, when it has them: each is a way on.
+          doneButtons: run.buttons && run.buttons.length ? run.buttons : null,
+          sending: run.sending
         }}
       />
       <FlowValues screen={screen} values={values} record={record} />

package/src/designs/ScreenSample.jsx

@@ -30,7 +30,12 @@ const STATUS = {
 
 /** What the background save is doing, in words. */
 function SaveStatus({ ctrl }) {
-  const text = ctrl.status === 'error' ? `Not saved — ${ctrl.saveError}` : STATUS[ctrl.status]
+  // A screen with no table of its own (a review in a workflow) saves nothing,
+  // so "Unsaved changes" and "Saved" would describe something that is not
+  // happening. What still matters there is a field left wrong.
+  const keeps = Boolean(ctrl.document && ctrl.document.source)
+  const quiet = !keeps && (ctrl.status === 'pending' || ctrl.status === 'saved' || ctrl.status === 'saving')
+  const text = quiet ? '' : ctrl.status === 'error' ? `Not saved — ${ctrl.saveError}` : STATUS[ctrl.status]
   return (
     <span className={`xeplr-factory-footer-status xeplr-factory-footer-status--${ctrl.status}`} role="status" aria-live="polite">
       {text}
@@ -100,6 +105,22 @@ function StepNav({ ctrl, node, status, children }) {
  */
 function SaveButtons({ ctrl }) {
   const saving = ctrl.status === 'saving'
+  // A WORKFLOW STEP'S OWN BUTTONS (Approve / Send back): each saves what is
+  // unsaved, then moves the run on, saying which was pressed — its arrows
+  // branch on it. The first is the main one.
+  if (ctrl.doneButtons && ctrl.doneButtons.length) {
+    return (
+      <>
+        {ctrl.doneButtons.slice().reverse().map((b, i, list) => (
+          <button key={b.key} type="button" disabled={saving || ctrl.sending}
+            className={i === list.length - 1 ? 'xeplr-factory-primary' : 'xeplr-factory-secondary'}
+            onClick={() => ctrl.flush().then((r) => { if (r && r.ok) ctrl.done(r, b.key) })}>
+            {b.label}
+          </button>
+        ))}
+      </>
+    )
+  }
   if (ctrl.doneLabel) {
     return (
       <button type="button" className="xeplr-factory-primary" disabled={saving}
@@ -184,6 +205,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}
+              rows={node.type === 'table' && ctrl.rowsFor ? ctrl.rowsFor(node) : undefined}
               stepper={node.type === 'stepper' ? {
                 active: ctrl.steps.active(node.id),
                 isDisabled: (i) => ctrl.steps.isDisabled(node.id, i),

package/src/designs/factory.css

@@ -636,3 +636,12 @@
 .xeplr-factory-fd-branches p { margin: 0; color: var(--xf-muted); }
 .xeplr-factory-fd-branches ul { margin: 0; padding-left: 18px; }
 .xeplr-factory-fd-branches button { align-self: flex-start; }
+
+/* A table of rows the workflow handed the screen, a tick per row. */
+.xeplr-factory-table-wrap { overflow: auto; max-height: 100%; border: 1px solid var(--xf-border); border-radius: 6px; }
+.xeplr-factory-table { width: 100%; border-collapse: collapse; font-size: max(11px, calc(12 * var(--xf-u))); }
+.xeplr-factory-table th, .xeplr-factory-table td { text-align: left; padding: 6px 8px; border-bottom: 1px solid var(--xf-border); white-space: nowrap; }
+.xeplr-factory-table th { position: sticky; top: 0; background: var(--xeplr-bg-secondary, #fff); color: var(--xf-muted); font-weight: 600; }
+.xeplr-factory-table td.is-number { text-align: right; font-variant-numeric: tabular-nums; }
+.xeplr-factory-table tr.is-ticked td { background: var(--xeplr-accent-soft, rgba(47, 91, 211, 0.07)); }
+.xeplr-factory-table-tick { width: 28px; }

package/src/flows.js

@@ -101,7 +101,9 @@ export function createFlowsApi({ fetch: doFetch, base = '' } = {}) {
     startRun: async (key) => one(await call('POST', `/${enc(key)}/runs`)),
     loadRun: async (runId) => one(await call('GET', `/runs/${enc(runId)}`)),
     /** What the person filled in. Answers with the next screen, or that it is done. */
-    submitRun: async (runId, values, recordId) => one(await call('POST', `/runs/${enc(runId)}/submit`, { values, recordId })),
+    submitRun: async (runId, values, recordId, action) => one(await call('POST', `/runs/${enc(runId)}/submit`, action ? { values, recordId, action } : { values, recordId })),
+    /** Every screen waiting for one of the signed-in person's roles, in any workflow. */
+    waiting: () => call('GET', '/waiting'),
     /** Journeys of this flow that are still going — "in progress". */
     myRuns: (key) => call('GET', `/${enc(key)}/runs?mine=1`)
   }

package/src/useFactoryScreen.js

@@ -2,7 +2,7 @@ import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import { CONTROLS, CHOICE_TYPES } from './controls.js'
 import { inputNodes, nodesForSteps, steppers, stepsOf, stepOf, resolveStep, reachableStep, nextOpenStep } from './document.js'
 import { validateDocument } from './validateDocument.js'
-import { initialValues, parseInput, saveState, fieldError, optionValue, recordValues, listSource } from './values.js'
+import { initialValues, parseInput, saveState, fieldError, optionValue, recordValues, listSource, resolveBinding } from './values.js'
 import { hookMethod } from './hooks.js'
 import { useUrlSteps } from './useUrlPlaces.js'
 
@@ -338,6 +338,13 @@ export function useFactoryScreen({
     return out
   }, [doc.id])
 
+  // A table's rows: its binding to this screen's inputs (`{params.lines}`),
+  // filled by whoever opened it — a workflow step's values.
+  const rowsFor = useCallback((node) => {
+    const rows = resolveBinding(node && node.props ? node.props.rows : undefined, params || {}, previous)
+    return Array.isArray(rows) ? rows : []
+  }, [params, previous])
+
   const optionsFor = useCallback((node) => {
     if (node.props.data?.source === 'static') return { loading: false, items: node.props.data.options, error: null }
     return options[node.id] || { loading: false, items: [], error: null }
@@ -396,7 +403,9 @@ export function useFactoryScreen({
     if (!subsOk) { setStatus('invalid'); return { ok: false } }
     const customSave = hooksRef.current && typeof hooksRef.current.save === 'function'
     const writing = changes.current
-    if (!l.onSave && !customSave) { savedChanges.current = writing; setDirty(false); setStatus('saved'); return { ok: true } }
+    // Nothing to save to: no save given, or a screen with no table of its own
+    // (a review screen in a workflow, whose values go only to the run).
+    if ((!l.onSave || !l.source) && !customSave) { savedChanges.current = writing; setDirty(false); setStatus('saved'); return { ok: true } }
 
     setStatus('saving')
     setSaveError(null)
@@ -782,6 +791,7 @@ export function useFactoryScreen({
     setValue,
     touch,
     optionsFor,
+    rowsFor,
     done: onDone || null,
     steps: stepControl,
     visibleNodes,

package/src/useFlowRun.js

@@ -16,7 +16,8 @@ import { useCallback, useEffect, useRef, useState } from 'react'
  * @param runId      an existing run to continue — omit to start one
  * @param startRun   async (flowKey) → { runId, status, stepKey, screen }
  * @param loadRun    async (runId) → { runId, status, stepKey, screen, values, given, previous }
- * @param submitRun  async (runId, values, recordId) → { status, stepKey, screen }
+ * @param submitRun  async (runId, values, recordId, action) → { status, stepKey, screen }
+ *                   (action: the button pressed, when the step has buttons)
  * @param loadScreen async (key) → the screen document
  * @param onStep     (step) → void — told each time the run moves, for the address bar
  * @param onFinish   (run) → void — the journey is over
@@ -25,7 +26,7 @@ export function useFlowRun({ flowKey, runId, startRun, loadRun, submitRun, loadS
   // `given` is what the flow called this screen with — the step's own input,
   // resolved by the engine (see @xeplr/workflow's screen-show). A field bound
   // to {params.x} is filled from it.
-  const [state, setState] = useState({ loading: true, error: null, runId: runId || null, status: null, stepKey: null, screen: null, document: null, values: null, given: null, previous: null })
+  const [state, setState] = useState({ loading: true, error: null, runId: runId || null, status: null, stepKey: null, screen: null, document: null, values: null, given: null, previous: null, buttons: null })
   const [sending, setSending] = useState(false)
   const live = useRef({})
   live.current = { startRun, loadRun, submitRun, loadScreen, onStep, onFinish, flowKey }
@@ -45,7 +46,9 @@ export function useFlowRun({ flowKey, runId, startRun, loadRun, submitRun, loadS
       runId: run.runId, status: run.status || 'running', stepKey: run.stepKey, screen: run.screen,
       // previous: what the screens before this one saved, by screen key —
       // what {previous.<screen>.values.<field>} defaults fill from.
-      document: doc, values: run.values || null, given: run.given || null, previous: run.previous || null
+      document: doc, values: run.values || null, given: run.given || null, previous: run.previous || null,
+      // The step's buttons ([{ key, label }]); none is one Next.
+      buttons: Array.isArray(run.buttons) && run.buttons.length ? run.buttons : null
     })
     if (live.current.onStep) live.current.onStep(run)
   }, [])
@@ -73,11 +76,11 @@ export function useFlowRun({ flowKey, runId, startRun, loadRun, submitRun, loadS
    * next; `recordId` is the row the screen just saved, so later steps and
    * their arrows can refer to it.
    */
-  const submit = useCallback(async (values, recordId) => {
+  const submit = useCallback(async (values, recordId, action) => {
     if (!live.current.submitRun) throw new Error('No submitRun was provided')
     setSending(true)
     try {
-      const next = await live.current.submitRun(state.runId, values || {}, recordId)
+      const next = await live.current.submitRun(state.runId, values || {}, recordId, action)
       await open({ runId: state.runId, ...next })
     } catch (err) {
       setState((s) => ({ ...s, error: err.message || 'That could not be sent' }))

package/src/values.js

@@ -101,10 +101,10 @@ export function initialValues(doc, provided = {}, controls = CONTROLS, previous
       if (resolved !== undefined) out[name] = resolved
       else if (!isBinding(node.props.default)) out[name] = node.props.default
       else if (node.type === 'checkbox') out[name] = false
-      else if (node.type === 'multiselect') out[name] = []
+      else if (node.type === 'multiselect' || node.type === 'table') out[name] = []
     }
     else if (node.type === 'checkbox') out[name] = false
-    else if (node.type === 'multiselect') out[name] = []
+    else if (node.type === 'multiselect' || node.type === 'table') out[name] = []
   })
   return out
 }
@@ -117,6 +117,7 @@ export function initialValues(doc, provided = {}, controls = CONTROLS, previous
 export function parseInput(node, raw) {
   if (node.type === 'checkbox') return Boolean(raw)
   if (node.type === 'multiselect') return Array.isArray(raw) ? raw : fromDbValue(node, raw) || []
+  if (node.type === 'table') return Array.isArray(raw) ? raw : []
   if (raw === undefined || raw === null || raw === '') return undefined
   if (node.type === 'number') {
     const n = typeof raw === 'number' ? raw : Number(String(raw).trim())
@@ -157,6 +158,14 @@ export function fieldError(node, value, loadedOptions) {
   if (node.type === 'checkbox') {
     return p.required && value !== true ? `${label} must be ticked` : null
   }
+  // A TABLE'S VALUE is the rows ticked: required is at least one.
+  if (node.type === 'table') {
+    const ticked = Array.isArray(value) ? value : []
+    if (!ticked.length) return p.required ? `${label}: tick at least one row` : null
+    if (v.minItems != null && ticked.length < v.minItems) return `${label}: tick at least ${v.minItems}`
+    if (v.maxItems != null && ticked.length > v.maxItems) return `${label}: tick at most ${v.maxItems}`
+    return null
+  }
   if (node.type === 'multiselect') {
     const chosen = Array.isArray(value) ? value : []
     if (!chosen.length) return p.required ? `${label} is required` : null
@@ -277,7 +286,7 @@ export function recordValues(doc, record, controls = CONTROLS) {
     const v = record ? record[name] : undefined
     if (v !== undefined && v !== null) out[name] = fromDbValue(node, v)
     else if (node.type === 'checkbox') out[name] = false
-    else if (node.type === 'multiselect') out[name] = []
+    else if (node.type === 'multiselect' || node.type === 'table') out[name] = []
   })
   return out
 }