@xeplr/ui-factory 1.0.6 → 1.0.8

package/src/designs/PropertyPanel.jsx

@@ -1,6 +1,6 @@
 import { getAtPath } from '../propertyPath.js'
 import { slugify, inputNodes } from '../document.js'
-import { FONT_FAMILIES, STYLE_KEYS, SCREEN_STYLE_KEYS, LIST_ACTIONS } from '../controls.js'
+import { FONT_FAMILIES, STYLE_KEYS, SCREEN_STYLE_KEYS, LIST_ACTIONS, FILE_KINDS } from '../controls.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
@@ -152,6 +152,39 @@ function DateEditor({ id, value, onChange }) {
   return <input id={id} className="xeplr-factory-prop-input" type="date" value={value ?? ''} onChange={(e) => onChange(e.target.value)} />
 }
 
+function DatetimeEditor({ id, value, onChange }) {
+  return <input id={id} className="xeplr-factory-prop-input" type="datetime-local" value={value ?? ''} onChange={(e) => onChange(e.target.value)} />
+}
+
+/**
+ * Which files a file field takes: one of the everyday sets, or a list typed
+ * out. The list is what is saved either way — the sets are a way in, not a
+ * second setting to keep in step.
+ */
+function AcceptEditor({ id, value, onChange }) {
+  const kind = Object.keys(FILE_KINDS).find((k) => FILE_KINDS[k].accept === value)
+  return (
+    <div className="xeplr-factory-prop-stack">
+      <select
+        id={id}
+        className="xeplr-factory-prop-input"
+        value={kind || '__custom'}
+        onChange={(e) => { const k = e.target.value; if (k !== '__custom') onChange(FILE_KINDS[k].accept) }}
+      >
+        {Object.entries(FILE_KINDS).map(([k, f]) => <option key={k} value={k}>{f.label}</option>)}
+        <option value="__custom">Just these…</option>
+      </select>
+      <input
+        className="xeplr-factory-prop-input"
+        type="text"
+        value={value ?? ''}
+        placeholder=".pdf,.docx"
+        onChange={(e) => onChange(e.target.value === '' ? undefined : e.target.value)}
+      />
+    </div>
+  )
+}
+
 /** A font family: the common ones, or anything typed. */
 function FontEditor({ id, value, onChange }) {
   const known = FONT_FAMILIES.some((f) => f.value === value)
@@ -384,11 +417,48 @@ function StaticOptions({ data, onChange, errors }) {
   )
 }
 
+/**
+ * The steps, as one line: "Connect, Transform, Review". A step KEEPS ITS KEY
+ * while it is renamed — the controls on it point at the key — so editing the
+ * line matches by position, and only a step that is added or removed changes
+ * which controls are shown.
+ */
+function StepsEditor({ id, value, onChange }) {
+  const steps = Array.isArray(value) ? value : []
+  return (
+    <input
+      id={id}
+      className="xeplr-factory-prop-input"
+      type="text"
+      value={steps.map((s) => s.label).join(', ')}
+      placeholder="Connect, Transform, Review"
+      onChange={(e) => {
+        const labels = e.target.value.split(',').map((t) => t.trim()).filter(Boolean)
+        onChange(labels.map((label, i) => ({
+          key: steps[i] ? steps[i].key : uniqueStepKey(steps, slugify(label, '_') || `step_${i + 1}`),
+          label
+        })))
+      }}
+    />
+  )
+}
+
+function uniqueStepKey(steps, base) {
+  const taken = new Set(steps.map((s) => s.key))
+  if (!taken.has(base)) return base
+  let n = 2
+  while (taken.has(`${base}_${n}`)) n++
+  return `${base}_${n}`
+}
+
 export const EDITORS = {
   text: TextEditor,
   textarea: TextareaEditor,
   number: NumberEditor,
   date: DateEditor,
+  datetime: DatetimeEditor,
+  accept: AcceptEditor,
+  steps: StepsEditor,
   toggle: ToggleEditor,
   toggleValue: ToggleValueEditor,
   select: SelectEditor,

package/src/designs/ScreenSample.jsx

@@ -1,6 +1,7 @@
 import ControlView from './ControlView.jsx'
 import { contentBottom, inputNodes, MARGIN } from '../document.js'
 import { screenStyle } from './styles.js'
+import { CHOICE_TYPES } from '../controls.js'
 
 // A saved screen, drawn. Presentation only — everything comes from
 // useFactoryScreen.
@@ -21,6 +22,28 @@ const STATUS = {
   invalid: 'Fix the highlighted fields to save'
 }
 
+/**
+ * Back and Next, under the page. Next holds at a step whose own fields are not
+ * filled in — and shows why, rather than moving on and leaving a problem
+ * behind on a step nobody is looking at.
+ */
+function StepNav({ ctrl, node }) {
+  const at = ctrl.steps.active(node.id)
+  const last = ctrl.steps.count(node.id) - 1
+  const unfinished = ctrl.steps.fieldsOn(node.id, at).filter((n) => ctrl.allErrors[n.props.name])
+  const go = (to) => {
+    if (to > at && unfinished.length) { unfinished.forEach((n) => ctrl.touch(n)); return }
+    ctrl.steps.go(node.id, Math.min(Math.max(to, 0), last))
+  }
+  return (
+    <div className="xeplr-factory-stepnav">
+      <button type="button" className="xeplr-factory-secondary" onClick={() => go(at - 1)} disabled={at === 0}>Back</button>
+      <span className="xeplr-factory-stepnav-where">Step {at + 1} of {last + 1}</span>
+      <button type="button" className="xeplr-factory-primary" onClick={() => go(at + 1)} disabled={at === last}>Next</button>
+    </div>
+  )
+}
+
 export default function ScreenSample({ ctrl, className, style, renderPopup }) {
   const { document: doc } = ctrl
 
@@ -36,7 +59,10 @@ export default function ScreenSample({ ctrl, className, style, renderPopup }) {
   }
 
   const aspect = doc.aspect
-  const pageHeight = (contentBottom(doc) + MARGIN) * aspect * 100
+  // Only what the open steps show — the page is as tall as the step being
+  // filled in, not as tall as every step stacked up.
+  const shown = ctrl.visibleNodes && ctrl.visibleNodes.length ? ctrl.visibleNodes : doc.nodes
+  const pageHeight = (contentBottom(doc, shown) + MARGIN) * aspect * 100
   const fieldNodes = inputNodes(doc)
   const statusText = ctrl.status === 'error' ? `Not saved — ${ctrl.saveError}` : STATUS[ctrl.status]
   // A screen with no fields of its own (a list screen) has nothing to save.
@@ -61,7 +87,7 @@ export default function ScreenSample({ ctrl, className, style, renderPopup }) {
         noValidate
         aria-label={doc.name}
       >
-        {[...doc.nodes].sort((a, b) => (a.z || 0) - (b.z || 0)).map((node) => (
+        {[...shown].sort((a, b) => (a.z || 0) - (b.z || 0)).map((node) => (
           <div
             key={node.id}
             className={`xeplr-factory-node xeplr-factory-node--${node.type}`}
@@ -77,7 +103,9 @@ export default function ScreenSample({ ctrl, className, style, renderPopup }) {
               mode="live"
               value={node.props?.name ? ctrl.values[node.props.name] : undefined}
               error={node.props?.name ? ctrl.errors[node.props.name] : undefined}
-              options={node.type === 'dropdown' ? ctrl.optionsFor(node) : undefined}
+              options={CHOICE_TYPES.includes(node.type) ? ctrl.optionsFor(node) : undefined}
+              upload={node.type === 'file' ? ctrl.upload : undefined}
+              stepper={node.type === 'stepper' ? { active: ctrl.steps.active(node.id), onStep: (i) => ctrl.steps.go(node.id, i) } : undefined}
               onChange={(raw) => ctrl.setValue(node, raw)}
               onBlur={() => ctrl.touch(node)}
               list={node.type === 'list' ? {
@@ -100,6 +128,9 @@ export default function ScreenSample({ ctrl, className, style, renderPopup }) {
           </div>
         ))}
       </form>
+      {ctrl.steps.nodes.map((node) => (
+        <StepNav key={node.id} ctrl={ctrl} node={node} />
+      ))}
       {ctrl.popup && renderPopup && renderPopup(ctrl.popup, ctrl)}
     </div>
   )

package/src/designs/factory.css

@@ -71,6 +71,64 @@
 .xeplr-factory-check { display: flex; align-items: center; gap: calc(8 * var(--xf-u)); cursor: pointer; font-weight: 500; }
 .xeplr-factory-check input { width: calc(18 * var(--xf-u)); height: calc(18 * var(--xf-u)); min-width: 12px; min-height: 12px; margin: 0; accent-color: var(--xf-accent); }
 
+/* ── option groups (radio, multi-select) ───────────────────────────────────
+   The group scrolls rather than spilling over the control below it, so a long
+   list of options cannot cover the next field. */
+.xeplr-factory-choices { display: flex; gap: calc(6 * var(--xf-u)) calc(16 * var(--xf-u)); overflow: auto; min-height: 0; }
+.xeplr-factory-choices--vertical { flex-direction: column; }
+.xeplr-factory-choices--horizontal { flex-direction: row; flex-wrap: wrap; align-items: center; }
+.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 {
+  flex: none; border: 1px solid var(--xf-border); background: var(--xf-surface); 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;
+}
+.xeplr-factory-file-clear:hover { color: var(--xf-ink); border-color: var(--xf-accent); }
+.xeplr-factory-file-input { padding: calc(5 * var(--xf-u)); }
+
+/* ── stepper ──────────────────────────────────────────────────────────────
+   The journey across the top: a circle per step, joined by a line. The line is
+   drawn behind the circles, from the middle of one to the middle of the next. */
+.xeplr-factory-stepper { display: flex; align-items: center; width: 100%; height: 100%; overflow: hidden; }
+.xeplr-factory-steps { display: flex; align-items: flex-start; width: 100%; margin: 0; padding: 0; list-style: none; }
+.xeplr-factory-step { flex: 1; position: relative; min-width: 0; text-align: center; }
+.xeplr-factory-step + .xeplr-factory-step::before {
+  content: ''; position: absolute; top: calc(13 * var(--xf-u)); right: 50%; left: -50%; height: 2px;
+  background: var(--xf-border);
+}
+.xeplr-factory-step.is-active::before, .xeplr-factory-step.is-done::before { background: var(--xf-accent); }
+.xeplr-factory-step-button {
+  position: relative; display: flex; flex-direction: column; align-items: center; gap: calc(4 * var(--xf-u));
+  width: 100%; padding: 0; border: none; background: none; color: var(--xf-muted); font: inherit; cursor: pointer;
+}
+.xeplr-factory-step-mark {
+  display: flex; align-items: center; justify-content: center;
+  width: calc(26 * var(--xf-u)); height: calc(26 * var(--xf-u)); min-width: 18px; min-height: 18px;
+  border-radius: 50%; background: var(--xf-border); color: var(--xf-ink); font-weight: 600;
+}
+.xeplr-factory-step-label { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; max-width: 100%; }
+.xeplr-factory-step.is-active .xeplr-factory-step-mark,
+.xeplr-factory-step.is-done .xeplr-factory-step-mark { background: var(--xf-accent); color: #fff; }
+.xeplr-factory-step.is-active .xeplr-factory-step-button { color: var(--xf-accent); font-weight: 600; }
+
+/* Back / Next, under the page. */
+.xeplr-factory-stepnav { display: flex; align-items: center; gap: 12px; padding: 10px 0; }
+.xeplr-factory-stepnav-where { flex: 1; text-align: center; color: var(--xf-muted); font-size: 12px; }
+
+/* Which step the builder is on. */
+.xeplr-factory-building { display: flex; align-items: center; flex-wrap: wrap; gap: 8px; margin: 0 auto 8px; padding: 6px 0; }
+.xeplr-factory-building-what { color: var(--xf-muted); font-size: 12px; font-weight: 600; text-transform: uppercase; letter-spacing: 0.06em; }
+.xeplr-factory-building-step {
+  border: 1px solid var(--xf-border); background: var(--xf-surface); color: var(--xf-muted);
+  border-radius: 999px; padding: 3px 10px; font: inherit; font-size: 12px; cursor: pointer;
+}
+.xeplr-factory-building-step.is-active { border-color: var(--xf-accent); color: var(--xf-accent); font-weight: 600; }
+.xeplr-factory-building-every { display: flex; align-items: center; gap: 6px; margin-left: auto; color: var(--xf-muted); font-size: 12px; }
+
 /* A label's size and weight are inline — its preset, overridden by its style. */
 .xeplr-factory-text { margin: 0; color: var(--xf-ink); height: 100%; overflow: hidden; line-height: 1.25; box-sizing: border-box; }
 .xeplr-factory-text--text { color: var(--xf-muted); }
@@ -144,6 +202,11 @@
 .xeplr-factory-palette-item:hover { border-color: var(--xf-accent); }
 .xeplr-factory-palette-icon { width: 14px; height: 10px; border: 1.5px solid var(--xf-muted); border-radius: 2px; flex: 0 0 auto; }
 .xeplr-factory-palette-icon--checkbox { width: 10px; }
+.xeplr-factory-palette-icon--radio { border-radius: 50%; width: 11px; height: 11px; }
+.xeplr-factory-palette-icon--multiselect { height: 11px; background: repeating-linear-gradient(to bottom, var(--xf-muted) 0 2px, transparent 2px 5px); border: none; }
+.xeplr-factory-palette-icon--datetime { border-top-width: 3px; }
+.xeplr-factory-palette-icon--file { border-radius: 2px; border-top: 3px solid var(--xf-muted); height: 12px; width: 10px; }
+.xeplr-factory-palette-icon--stepper { height: 8px; border-radius: 999px; background: linear-gradient(to right, var(--xf-muted) 0 30%, transparent 30%); border: none; }
 .xeplr-factory-palette-icon--label { border: none; border-top: 2px solid var(--xf-muted); border-bottom: 2px solid var(--xf-muted); height: 6px; }
 .xeplr-factory-palette-icon--list { height: 12px; background: repeating-linear-gradient(to bottom, var(--xf-muted) 0 1.5px, transparent 1.5px 4px); border: none; }
 .xeplr-factory-palette-icon--textarea { height: 14px; }
@@ -184,6 +247,8 @@
   border: 1px solid var(--xf-border); border-radius: 5px; background: #fff; color: var(--xf-ink, #1a1a19);
 }
 .xeplr-factory-prop.has-error .xeplr-factory-prop-input { border-color: var(--xf-danger); }
+/* An editor made of two inputs — a set to pick from, and the list it fills in. */
+.xeplr-factory-prop-stack { display: flex; flex-direction: column; gap: 5px; }
 .xeplr-factory-prop-help { margin-top: 3px; color: var(--xf-muted); font-size: 11px; line-height: 1.4; }
 .xeplr-factory-prop-error { margin-top: 3px; color: var(--xf-danger); font-size: 11px; }
 .xeplr-factory-panel-errors { margin-top: 8px; padding: 8px; border-radius: 6px; color: var(--xf-danger); background: color-mix(in srgb, var(--xf-danger) 7%, transparent); font-size: 11px; }

package/src/document.js

@@ -68,7 +68,7 @@ export function setScreenProperty(doc, path, value) {
  * control's top-left) or, without one, below everything already on the screen.
  * Returns { document, node }.
  */
-export function addControl(doc, type, { at, props, size } = {}, controls = CONTROLS) {
+export function addControl(doc, type, { at, props, size, step } = {}, controls = CONTROLS) {
   const def = controls[type]
   if (!def) throw new Error(`Unknown control type "${type}"`)
   const dims = { ...def.defaultSize, ...size }
@@ -88,9 +88,73 @@ export function addControl(doc, type, { at, props, size } = {}, controls = CONTR
     z: nextZ(doc),
     props: merged
   }
+  // Dropped while a step is open: the control belongs to that step. A stepper
+  // never belongs to itself.
+  if (step && type !== 'stepper') node.step = { of: step.of, index: step.index }
   return { document: { ...doc, nodes: [...doc.nodes, node] }, node }
 }
 
+// ── steps ────────────────────────────────────────────────────────────────
+// A stepper shows one step at a time, and every other control says which step
+// it belongs to. The document stays FLAT — nothing is nested — so a control is
+// still moved, styled and checked exactly as it was; `step` only decides when
+// it is on screen.
+
+/** Every stepper on the screen, in reading order. */
+export function steppers(doc, controls = CONTROLS) {
+  return (doc.nodes || []).filter((n) => n.type === 'stepper' && controls[n.type])
+}
+
+/** A stepper's steps, always as [{ key, label }]. */
+export function stepsOf(node) {
+  return (node && node.props && Array.isArray(node.props.steps) ? node.props.steps : []).map((s, i) => ({
+    key: (s && s.key) || `step_${i + 1}`,
+    label: (s && s.label) || `Step ${i + 1}`
+  }))
+}
+
+/** Which step a node is on, or null for "every step". */
+export function stepOf(node) {
+  const step = node && node.step
+  return step && typeof step.of === 'string' && Number.isInteger(step.index) ? step : null
+}
+
+/**
+ * Puts a node on a step — or on none, with `null`, which shows it whatever
+ * step is open.
+ */
+export function setNodeStep(doc, id, step) {
+  return mapNode(doc, id, (n) => {
+    const next = { ...n }
+    if (step === null || step === undefined) delete next.step
+    else next.step = { of: step.of, index: step.index }
+    return next
+  })
+}
+
+/**
+ * The nodes to show, given which step each stepper is open at.
+ * @param active  { [stepper node id]: index } — missing means its first step
+ */
+export function nodesForSteps(doc, active = {}, controls = CONTROLS) {
+  const open = (id) => (Number.isInteger(active[id]) ? active[id] : 0)
+  const byId = new Map((doc.nodes || []).map((n) => [n.id, n]))
+  const shown = (node, seen) => {
+    const step = stepOf(node)
+    if (!step) return true
+    const owner = byId.get(step.of)
+    // A step of a stepper that is gone shows nothing: the control is orphaned,
+    // and the checker says so rather than the screen quietly losing it.
+    if (!owner || owner.type !== 'stepper') return false
+    if (step.index !== open(owner.id)) return false
+    // A stepper inside another stepper's step is only open when that one is.
+    if (seen.has(owner.id)) return false
+    seen.add(owner.id)
+    return shown(owner, seen)
+  }
+  return (doc.nodes || []).filter((n) => shown(n, new Set()))
+}
+
 /** Merges a geometry patch — what the canvas reports on drop. */
 export function moveNode(doc, id, patch) {
   const geometry = {}
@@ -160,8 +224,8 @@ export function readingOrder(nodes) {
 }
 
 /** Where the lowest control ends, as a page fraction. */
-export function contentBottom(doc) {
-  return doc.nodes.reduce((max, n) => Math.max(max, (n.y || 0) + (n.h || 0)), 0)
+export function contentBottom(doc, nodes) {
+  return (nodes || doc.nodes).reduce((max, n) => Math.max(max, (n.y || 0) + (n.h || 0)), 0)
 }
 
 // ── naming ───────────────────────────────────────────────────────────────

package/src/generate.js

@@ -23,14 +23,17 @@
 // The result is an ordinary document, checked before it is returned; from
 // there it is edited like any other.
 
-import { CONTROLS } from './controls.js'
-import { createScreen, addControl, MARGIN, GAP, slugify, camelName } from './document.js'
+import { CONTROLS, CHOICE_TYPES } from './controls.js'
+import { createScreen, addControl, MARGIN, GAP, slugify, camelName, stepsOf } from './document.js'
 import { assertValidDocument } from './validateDocument.js'
 
 /** Heights by control, as page fractions (a page is as tall as it is wide). */
 export const SPEC_HEIGHTS = {
-  text: 0.08, number: 0.08, date: 0.08, dropdown: 0.08,
+  text: 0.08, number: 0.08, date: 0.08, datetime: 0.08, dropdown: 0.08,
+  file: 0.1, stepper: 0.09,
   textarea: 0.18,
+  // A group is as tall as its options make it — see heightOf().
+  radio: 0.14, multiselect: 0.18,
   checkbox: 0.05,
   list: 0.42,
   label: { heading: 0.07, subheading: 0.055, text: 0.045 }
@@ -42,7 +45,7 @@ export const SPEC_HEIGHTS = {
  */
 export const ROW_GAP = 0.04
 
-const FIELD_KEYS = ['type', 'label', 'name', 'required', 'placeholder', 'default', 'validation', 'data', 'options', 'table', 'width', 'text', 'variant', 'style']
+const FIELD_KEYS = ['type', 'label', 'name', 'required', 'placeholder', 'default', 'validation', 'data', 'options', 'table', 'layout', 'accept', 'maxSize', 'step', 'steps', 'showNumbers', 'width', 'text', 'variant', 'style']
 const SPEC_KEYS = ['name', 'id', 'source', 'columns', 'heading', 'fields', 'list', 'aspect', 'width', 'style']
 const LIST_KEYS = ['title', 'source', 'columns', 'pageSize', 'actions', 'style']
 
@@ -79,20 +82,48 @@ export function screenFromSpec(spec, controls = CONTROLS) {
   let col = 0
   let rowH = 0
 
+  // A stepper on the screen, and where each of its steps starts: every step is
+  // laid out from just under the bar, so they sit on top of one another rather
+  // than running down a page as long as all of them put together.
+  let stepper = null
+  let stepTop = 0
+  let step = null
+
   const place = (type, props, width) => {
     const h = heightOf(type, props)
-    const isFull = width === 'full' || columns === 1 || type === 'textarea' || type === 'label' || type === 'list'
+    const isFull = width === 'full' || columns === 1 || type === 'textarea' || type === 'label' || type === 'list' || type === 'stepper'
+    let node
     if (isFull) {
       if (col > 0) { y += rowH + ROW_GAP; col = 0; rowH = 0 }
-      ;({ document: doc } = addControl(doc, type, { at: { x: MARGIN, y: round(y) }, size: { w: round(full), h }, props }, controls))
+      ;({ document: doc, node } = addControl(doc, type, { at: { x: MARGIN, y: round(y) }, size: { w: round(full), h }, props, step }, controls))
       y += h + ROW_GAP
-      return
+    } else {
+      const x = MARGIN + col * (colW + GAP)
+      ;({ document: doc, node } = addControl(doc, type, { at: { x: round(x), y: round(y) }, size: { w: colW, h }, props, step }, controls))
+      rowH = Math.max(rowH, h)
+      col++
+      if (col === columns) { y += rowH + ROW_GAP; col = 0; rowH = 0 }
+    }
+    if (type === 'stepper') {
+      stepper = node
+      stepTop = y
+      step = { of: node.id, index: 0 }
     }
-    const x = MARGIN + col * (colW + GAP)
-    ;({ document: doc } = addControl(doc, type, { at: { x: round(x), y: round(y) }, size: { w: colW, h }, props }, controls))
-    rowH = Math.max(rowH, h)
-    col++
-    if (col === columns) { y += rowH + ROW_GAP; col = 0; rowH = 0 }
+    return node
+  }
+
+  /** Move the layout to a step: back to the top, under the bar. */
+  const openStep = (which) => {
+    const steps = stepsOf(stepper)
+    const index = typeof which === 'number' ? which - 1 : steps.findIndex((s) => s.key === which || s.label === which)
+    if (index < 0 || index >= steps.length) {
+      throw new Error(`screenFromSpec: step ${JSON.stringify(which)} is not one of ${steps.map((s) => s.label).join(', ')}`)
+    }
+    if (step && step.index === index) return
+    step = { of: stepper.id, index }
+    y = stepTop
+    col = 0
+    rowH = 0
   }
 
   if (spec.heading !== false) {
@@ -106,6 +137,10 @@ export function screenFromSpec(spec, controls = CONTROLS) {
     const type = field.type || 'text'
     if (!controls[type]) throw new Error(`screenFromSpec: ${at}.type "${type}" is not a control — one of: ${Object.keys(controls).join(', ')}`)
     if (field.width !== undefined && field.width !== 'half' && field.width !== 'full') throw new Error(`screenFromSpec: ${at}.width must be "half" or "full"`)
+    if (field.step !== undefined) {
+      if (!stepper) throw new Error(`screenFromSpec: ${at}.step needs a stepper before it — { "type": "stepper", "steps": [...] }`)
+      openStep(field.step)
+    }
     place(type, propsFromField(type, field, at), field.width)
   })
 
@@ -123,6 +158,18 @@ export function screenFromSpec(spec, controls = CONTROLS) {
 }
 
 function propsFromField(type, field, at) {
+  if (type === 'stepper') {
+    const steps = field.steps
+    if (!Array.isArray(steps) || steps.length < 2) throw new Error(`screenFromSpec: ${at} is a stepper — give it steps: ["Connect", "Transform", …]`)
+    const props = {
+      steps: steps.map((s, i) => (typeof s === 'string'
+        ? { key: slugify(s, '_') || `step_${i + 1}`, label: s }
+        : s))
+    }
+    if (field.showNumbers !== undefined) props.showNumbers = field.showNumbers
+    if (field.style) props.style = field.style
+    return props
+  }
   if (type === 'label') {
     const props = { text: field.text ?? field.label ?? '', variant: field.variant || 'subheading' }
     if (field.style) props.style = field.style
@@ -134,17 +181,23 @@ function propsFromField(type, field, at) {
     if (field[k] !== undefined) props[k] = field[k]
   })
   if (type === 'dropdown' && props.placeholder === undefined) props.placeholder = 'Select…'
-  if (type === 'dropdown') {
-    props.data = dataFromField(field, at)
-    // A dropdown reading another table stores that row's id: name the column
+  if (CHOICE_TYPES.includes(type)) {
+    props.data = dataFromField(field, at, type)
+    if (field.layout !== undefined && type !== 'dropdown') props.layout = field.layout
+    // A field reading another table stores that row's id: name the column
     // for what it holds — "Department" → departmentId, a foreign key.
-    if (props.data.source === 'table' && props.name === undefined) props.name = camelName(field.label) + 'Id'
+    if (props.data.source === 'table' && props.name === undefined && type !== 'multiselect') props.name = camelName(field.label) + 'Id'
+  }
+  else if (field.options || field.table || field.data) throw new Error(`screenFromSpec: ${at} — options/table/data only apply to ${CHOICE_TYPES.join(', ')}`)
+  if (type === 'file') {
+    ;['accept', 'maxSize'].forEach((k) => { if (field[k] !== undefined) props[k] = field[k] })
+  } else if (field.accept !== undefined || field.maxSize !== undefined) {
+    throw new Error(`screenFromSpec: ${at} — accept/maxSize only apply to a file`)
   }
-  else if (field.options || field.table || field.data) throw new Error(`screenFromSpec: ${at} — options/table/data only apply to a dropdown`)
   return props
 }
 
-function dataFromField(field, at) {
+function dataFromField(field, at, type) {
   if (field.data) return field.data
   if (field.table) return { source: 'table', table: field.table }
   if (Array.isArray(field.options)) {
@@ -155,15 +208,26 @@ function dataFromField(field, at) {
         : o))
     }
   }
-  throw new Error(`screenFromSpec: ${at} is a dropdown — give it options: [...] or table: "<name>"`)
+  throw new Error(`screenFromSpec: ${at} is a ${type} — give it options: [...] or table: "<name>"`)
 }
 
 function heightOf(type, props) {
   const h = SPEC_HEIGHTS[type]
   if (type === 'label') return h[props.variant] || h.text
+  // A group of options grows with them: the label, then a line per option
+  // (or one line for all of them, side by side).
+  if (type === 'radio' || type === 'multiselect') {
+    const n = props.data?.source === 'static' ? (props.data.options || []).length : 4
+    const lines = props.layout === 'horizontal' ? 1 : Math.max(n, 1)
+    return round(LABEL_H + lines * OPTION_H)
+  }
   return h || 0.08
 }
 
+/** A field's label, and one option, as page fractions. */
+const LABEL_H = 0.035
+const OPTION_H = 0.03
+
 function unknownKeys(obj, allowed, at) {
   const extra = Object.keys(obj).filter((k) => !allowed.includes(k))
   if (extra.length) throw new Error(`screenFromSpec: ${at} has unknown key(s) ${extra.join(', ')} — allowed: ${allowed.join(', ')}`)

package/src/model.js

@@ -3,14 +3,15 @@
 //
 //   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, 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, 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,
-  inputNodes, readingOrder, contentBottom, camelName, slugify, uniqueFieldName, nextPosition
+  inputNodes, readingOrder, contentBottom, camelName, slugify, uniqueFieldName, nextPosition,
+  steppers, stepsOf, stepOf, setNodeStep, nodesForSteps
 } from './document.js'
 export { validateDocument, assertValidDocument } from './validateDocument.js'
-export { formSchema, initialValues, parseInput, validateValues, fieldError, sameId, optionValue, saveState, recordValues, displayValue, listColumns, listSource } from './values.js'
+export { formSchema, initialValues, parseInput, validateValues, fieldError, sameId, optionValue, chooseable, saveState, recordValues, displayValue, fileLabel, 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/remote.js

@@ -43,6 +43,27 @@ export function createFactoryApi({ fetch: doFetch, base = '' } = {}) {
     return res && Array.isArray(res.dataArray) ? res.dataArray : []
   }
 
+  /**
+   * The same call, with a body the browser must describe itself (a FormData's
+   * multipart boundary). Nothing sets Content-Type here — see authFetch.
+   */
+  async function send(method, path, body) {
+    let res
+    try {
+      res = await doFetch(`${base}/factory${path}`, { method, body })
+    } catch (err) {
+      if (err && err.body !== undefined && err.status) throw failure(method, path, err.status, err.body, err.message)
+      throw err
+    }
+    if (res && typeof res.json === 'function' && typeof res.ok === 'boolean') {
+      let json = null
+      try { json = await res.json() } catch (_) { /* not JSON — reported below */ }
+      if (!res.ok) throw failure(method, path, res.status, json)
+      return json ? json.dataArray : []
+    }
+    return res && Array.isArray(res.dataArray) ? res.dataArray : []
+  }
+
   function failure(method, path, status, json, fallback) {
     const err = new Error((json && json.message) || fallback || `${method} ${path} failed (${status})`)
     err.status = status
@@ -77,9 +98,18 @@ export function createFactoryApi({ fetch: doFetch, base = '' } = {}) {
     fetchRecord: async ({ screen, id }) => one(await call('GET', `/records/${enc(screen)}/${enc(id)}`)),
     onSave: async (values, { id, screen }) => one(await call('POST', `/records/${enc(screen)}/save`, { id, values })),
     onDelete: ({ id, screen }) => call('POST', `/records/${enc(screen)}/delete`, { id }),
-    fetchOptions: ({ table }) => call('GET', `/options/${enc(table)}`)
+    fetchOptions: ({ table }) => call('GET', `/options/${enc(table)}`),
+
+    // 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.
+    uploadFile: async (file, { screen, field }) => {
+      const form = new FormData()
+      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('/')}`
   }
-  api.screenProps = { loadScreen: api.loadScreen, onSave: api.onSave, fetchRecords: api.fetchRecords, fetchRecord: api.fetchRecord, onDelete: api.onDelete, fetchOptions: api.fetchOptions }
+  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 }
   api.builderProps = { onSave: api.saveDraft, onPublish: api.publish, listTables: api.listTables, fetchOptions: api.fetchOptions, fetchRecords: api.fetchRecords }
   return api
 }

package/src/tableSchema.js

@@ -51,10 +51,11 @@ export const MAX_IDENTIFIER = 63
 
 const TEXT_DEFAULT_LENGTH = 255
 const OPTION_MIN_LENGTH = 50
+const FILE_PATH_LENGTH = 255
 
 /**
  * The column a field is stored in.
- * @returns {{ name, type: 'varchar'|'text'|'integer'|'numeric'|'date'|'boolean', length?, references?, notNull?, default? }}
+ * @returns {{ name, type: 'varchar'|'text'|'integer'|'numeric'|'date'|'timestamp'|'boolean', length?, references?, notNull?, default? }}
  */
 export function columnForField(node) {
   const p = node.props || {}
@@ -69,9 +70,18 @@ export function columnForField(node) {
       return { ...base, type: v.integer ? 'integer' : 'numeric' }
     case 'date':
       return { ...base, type: 'date' }
+    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 }
+    case 'multiselect':
+      // Every chosen id in one text column, separated by commas.
+      return { ...base, type: 'text' }
     case 'checkbox':
       return { ...base, type: 'boolean', notNull: true, default: 'false' }
-    case 'dropdown': {
+    case 'dropdown':
+    case 'radio': {
       const data = p.data || {}
       if (data.source === 'table') {
         // A real foreign key to the other entity's id.
@@ -118,6 +128,8 @@ export function widening(from, to) {
   }
   if (from.type === 'varchar' && to.type === 'text') return { ok: true }
   if (from.type === 'integer' && to.type === 'numeric') return { ok: true }
+  // A date becomes that day at midnight; the other way round would lose the time.
+  if (from.type === 'date' && to.type === 'timestamp') return { ok: true }
   return { ok: false, reason: `${describe(from)} → ${describe(to)} is a different kind of value` }
 }
 
@@ -250,6 +262,8 @@ export function columnFromDatabase(c) {
     case 'int4': return { ...base, type: 'integer' }
     case 'numeric': return { ...base, type: 'numeric' }
     case 'date': return { ...base, type: 'date' }
+    case 'timestamp':
+    case 'timestamptz': return { ...base, type: 'timestamp' }
     case 'bool': return { ...base, type: 'boolean' }
     // Anything else (a timestamp, a bigint someone chose) is not a type a field
     // makes — so any change to it is refused rather than guessed at.