@xeplr/ui-factory 1.0.5 → 1.0.7

package/src/designs/ControlView.jsx

@@ -1,4 +1,6 @@
+import { useState } from 'react'
 import { LABEL_PRESETS } from '../controls.js'
+import { stepsOf } from '../document.js'
 import ListView from './ListView.jsx'
 import { fieldStyle, labelStyle, boxStyle } from './styles.js'
 
@@ -11,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 }) {
+export default function ControlView({ node, mode = 'live', value, error, options, onChange, onBlur, disabled, list, upload, stepper }) {
   const View = VIEWS[node.type]
   if (!View) {
     return <div className="xeplr-factory-unknown">Unknown control “{node.type}”</div>
@@ -29,6 +31,8 @@ export default function ControlView({ node, mode = 'live', value, error, options
       onBlur={onBlur || (() => {})}
       disabled={design || disabled}
       list={list}
+      upload={upload}
+      stepper={stepper}
     />
   )
 }
@@ -37,7 +41,7 @@ function Field({ node, p, error, children, inline }) {
   return (
     <div className={`xeplr-factory-field${inline ? ' xeplr-factory-field--inline' : ''}${error ? ' has-error' : ''}`} style={fieldStyle(p.style)}>
       {!inline && (
-        <label className="xeplr-factory-label" htmlFor={ids(node)} style={labelStyle(p.style)}>
+        <label className="xeplr-factory-label" id={`${ids(node)}-label`} htmlFor={ids(node)} style={labelStyle(p.style)}>
           {p.label}{p.required && <span className="xeplr-factory-required" aria-hidden="true"> *</span>}
         </label>
       )}
@@ -168,6 +172,197 @@ function DropdownView({ node, p, design, value, error, options, onChange, onBlur
   )
 }
 
+/** The options a group control shows: typed in, or loaded from a table. */
+function groupItems(p, design, options) {
+  const data = p.data || {}
+  return data.source === 'static' ? (data.options || []) : (design ? [] : options.items)
+}
+
+/** What the designer shows in place of options it cannot load on the canvas. */
+function OptionsHint({ data }) {
+  const n = (data.options || []).length
+  return (
+    <div className="xeplr-factory-hint">
+      {data.source === 'table'
+        ? (data.table ? `from table ${data.table}` : 'no table chosen')
+        : `${n} option${n === 1 ? '' : 's'}`}
+    </div>
+  )
+}
+
+function RadioView({ node, p, design, value, error, options, onChange, onBlur, disabled }) {
+  const items = groupItems(p, design, options)
+  const text = boxStyle(p.style)
+  return (
+    <Field node={node} p={p} error={error || (!design && options.error) || null}>
+      <div className={`xeplr-factory-group xeplr-factory-group--${p.layout === 'horizontal' ? 'horizontal' : 'vertical'}`} role="radiogroup" aria-labelledby={`${ids(node)}-label`}>
+        {items.map((o) => (
+          <label key={String(o.id)} className="xeplr-factory-option" style={{ fontSize: text.fontSize, fontWeight: text.fontWeight, fontStyle: text.fontStyle, color: text.color }}>
+            <input
+              type="radio"
+              name={p.name}
+              value={String(o.id)}
+              checked={value !== undefined && value !== null && String(value) === String(o.id)}
+              disabled={disabled || (!design && options.loading)}
+              tabIndex={disabled ? -1 : undefined}
+              onChange={() => onChange(o.id)}
+              onBlur={onBlur}
+            />
+            <span>{o.name}</span>
+          </label>
+        ))}
+      </div>
+      {design && <OptionsHint data={p.data || {}} />}
+      {!design && options.loading && <div className="xeplr-factory-hint">Loading…</div>}
+    </Field>
+  )
+}
+
+function MultiselectView({ node, p, design, value, error, options, onChange, onBlur, disabled }) {
+  const items = groupItems(p, design, options)
+  const chosen = Array.isArray(value) ? value : []
+  const text = boxStyle(p.style)
+  const toggle = (id, on) => {
+    const next = chosen.filter((v) => String(v) !== String(id))
+    onChange(on ? [...next, id] : next)
+  }
+  return (
+    <Field node={node} p={p} error={error || (!design && options.error) || null}>
+      <div className={`xeplr-factory-group xeplr-factory-group--${p.layout === 'horizontal' ? 'horizontal' : 'vertical'}`} role="group" aria-labelledby={`${ids(node)}-label`}>
+        {items.map((o) => (
+          <label key={String(o.id)} className="xeplr-factory-option" style={{ fontSize: text.fontSize, fontWeight: text.fontWeight, fontStyle: text.fontStyle, color: text.color }}>
+            <input
+              type="checkbox"
+              name={p.name}
+              value={String(o.id)}
+              checked={chosen.some((v) => String(v) === String(o.id))}
+              disabled={disabled || (!design && options.loading)}
+              tabIndex={disabled ? -1 : undefined}
+              onChange={(e) => toggle(o.id, e.target.checked)}
+              onBlur={onBlur}
+            />
+            <span>{o.name}</span>
+          </label>
+        ))}
+      </div>
+      {design && <OptionsHint data={p.data || {}} />}
+      {!design && options.loading && <div className="xeplr-factory-hint">Loading…</div>}
+    </Field>
+  )
+}
+
+function DatetimeView({ node, p, value, error, onChange, onBlur, disabled }) {
+  const v = p.validation || {}
+  return (
+    <Field node={node} p={p} error={error}>
+      <input
+        className="xeplr-factory-input"
+        type="datetime-local"
+        min={v.min}
+        max={v.max}
+        value={value ?? ''}
+        onChange={(e) => onChange(e.target.value)}
+        {...inputProps(node, p, error, disabled, onBlur)}
+      />
+    </Field>
+  )
+}
+
+/**
+ * A file field holds the stored file's PATH, not the file. Picking one uploads
+ * it straight away (`upload`, supplied by the screen) and what comes back is
+ * the value that is saved with the record.
+ */
+function FileView({ node, p, design, value, error, onChange, onBlur, disabled, upload }) {
+  const [busy, setBusy] = useState(false)
+  const [failed, setFailed] = useState(null)
+  const accept = p.accept || ''
+  const choose = async (file) => {
+    if (!file || !upload) return
+    setFailed(null)
+    setBusy(true)
+    try {
+      const out = await upload(file, node)
+      onChange(out && out.path ? out.path : undefined)
+    } catch (e) {
+      setFailed(e && e.message ? e.message : 'The file could not be uploaded')
+    } finally {
+      setBusy(false)
+      onBlur()
+    }
+  }
+  return (
+    <Field node={node} p={p} error={error || failed}>
+      {value
+        ? (
+          <div className="xeplr-factory-file">
+            <span className="xeplr-factory-file-name" title={String(value)}>{fileName(value)}</span>
+            <button type="button" className="xeplr-factory-file-clear" disabled={disabled} onClick={() => { onChange(undefined); onBlur() }}>Remove</button>
+          </div>
+        )
+        : (
+          <input
+            className="xeplr-factory-input xeplr-factory-file-input"
+            type="file"
+            accept={accept}
+            disabled={disabled || busy}
+            onChange={(e) => { const f = e.target.files && e.target.files[0]; e.target.value = ''; choose(f) }}
+            {...inputProps(node, p, error, disabled || busy, onBlur)}
+          />
+        )}
+      {busy && <div className="xeplr-factory-hint">Uploading…</div>}
+      {!busy && !value && (design || accept) && (
+        <div className="xeplr-factory-hint">{accept || 'any file'}{p.maxSize ? ` · up to ${p.maxSize} MB` : ''}</div>
+      )}
+    </Field>
+  )
+}
+
+/** The name at the end of a stored path, for showing what is attached. */
+export function fileName(path) {
+  const s = String(path)
+  const cut = s.slice(s.lastIndexOf('/') + 1)
+  // Stored names start with the id that keeps them apart: "a1b2c3__report.pdf".
+  const sep = cut.indexOf('__')
+  return sep === -1 ? cut : cut.slice(sep + 2)
+}
+
+/**
+ * The journey across the top: a circle per step, the ones behind it done. It is
+ * the same bar on the canvas and on a live screen — clicking a step opens it,
+ * which in the builder is how you get at that step's controls.
+ */
+function StepperView({ node, p, design, stepper }) {
+  const steps = stepsOf(node)
+  const active = stepper && Number.isInteger(stepper.active) ? stepper.active : 0
+  const go = stepper && stepper.onStep
+  const text = boxStyle(p.style)
+  return (
+    <div className="xeplr-factory-stepper" style={{ ...fieldStyle(p.style), ...text }}>
+      <ol className="xeplr-factory-steps">
+        {steps.map((s, i) => {
+          const state = i === active ? 'is-active' : i < active ? 'is-done' : ''
+          return (
+            <li key={s.key} className={`xeplr-factory-step ${state}`} aria-current={i === active ? 'step' : undefined}>
+              <button
+                type="button"
+                className="xeplr-factory-step-button"
+                // On the canvas a press must still be able to drag the control,
+                // so the step is taken on click, never on mousedown.
+                onClick={(e) => { if (go) { e.stopPropagation(); go(i) } }}
+                tabIndex={design ? -1 : undefined}
+              >
+                <span className="xeplr-factory-step-mark" aria-hidden="true">{i < active ? '✓' : (p.showNumbers === false ? '' : i + 1)}</span>
+                <span className="xeplr-factory-step-label">{s.label}</span>
+              </button>
+            </li>
+          )
+        })}
+      </ol>
+    </div>
+  )
+}
+
 function LabelView({ p }) {
   const variant = p.variant || 'text'
   const preset = LABEL_PRESETS[variant] || LABEL_PRESETS.text
@@ -194,6 +389,11 @@ export const VIEWS = {
   date: DateView,
   checkbox: CheckboxView,
   dropdown: DropdownView,
+  radio: RadioView,
+  multiselect: MultiselectView,
+  datetime: DatetimeView,
+  file: FileView,
+  stepper: StepperView,
   label: LabelView,
   list: ListControl
 }

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-group { display: flex; gap: calc(6 * var(--xf-u)) calc(16 * var(--xf-u)); overflow: auto; min-height: 0; }
+.xeplr-factory-group--vertical { flex-direction: column; }
+.xeplr-factory-group--horizontal { flex-direction: row; flex-wrap: wrap; align-items: center; }
+.xeplr-factory-option { display: flex; align-items: center; gap: calc(8 * var(--xf-u)); cursor: pointer; color: var(--xf-ink); }
+.xeplr-factory-option 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 ───────────────────────────────────────────────────────────────