@xeplr/ui-factory 1.3.0 → 1.4.0

package/README.md

@@ -285,6 +285,44 @@ what you want is *tags* — several values picked from a fixed set — that is a
 of the record. Making it a sub-table means a two-table design for what is
 really one column.
 
+## A form inside a form
+
+This employee's bank details; this department's contact. Access calls it a
+subform. Put a **Form** (palette, Data) on the screen and give it two things:
+
+```
+Form        Bank details          ← any published form with fields of its own
+Linked by   employeeId            ← the field on THAT form pointing back here
+```
+
+```json
+{ "id": "n9", "type": "subform", "props": { "title": "Bank details", "screen": "bank_detail_edit", "belongsTo": "employeeId" } }
+```
+
+- **It is drawn as itself**, inline — its own fields, its own layout — and its
+  records stay in **its own table**. Nothing of it is a column of this one.
+- **One record of it per record of this one.** It reads the row whose link
+  field equals this record's `id` (the same server filter as a sub-table:
+  `belongsTo` + `belongsToId`). A record not saved yet has none, so it opens
+  empty. Several records of it is a **List**, not this.
+- **One Save.** Its changes are this form's "Unsaved changes". Save checks
+  both first — an invalid subform keeps this record from being written too —
+  then saves this record (so a new one has an id), then the subform with that
+  id in its link field. If the subform fails after this record saved, the
+  status says so and names it. A subform nobody touched is not saved: an
+  empty row is not worth one.
+- **The link field is never shown or asked for** on the subform — it is filled
+  in on save. The form must HAVE that field (a dropdown on this form's table,
+  usually): one that does not is refused out loud, with what to change, rather
+  than saving a record that belongs to nothing.
+- **A form cannot contain itself**, and a form shown inside another cannot be
+  deleted until it is removed there (`DELETE /factory/screens/:key` says where).
+
+Controller: the embedded screen is a second `useFactoryScreen` with `link`
+(the link field's name) and `onReady` (it hands the host `{ validate, dirty,
+save, name }`). `FactoryScreen` wires both; a custom design gets `subformFor(node)`,
+`registerSubform(id, api)` and `subformDirty(id, dirty)` from the host's controller.
+
 ## Masters — the lists the rest of the app points at
 
 Departments, statuses, countries, categories. Mark a form as a master in its
@@ -464,6 +502,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 |
+| `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
 design width: an elevated card in the app's theme (`--xeplr-bg-tertiary`, with

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xeplr/ui-factory",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "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

@@ -572,6 +572,41 @@ CONTROLS.list = {
   ]
 }
 
+// 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
+// `belongsTo` — the column on that form pointing back here, as on a sub-table
+// list. Several records of it is a List, not this.
+//
+// Nothing of it is stored in this screen's table: it is not an input, so it
+// adds no column. Save writes this record first, then the subform's, with
+// this record's id in its link column.
+CONTROLS.subform = {
+  type: 'subform',
+  label: 'Form',
+  group: 'Data',
+  input: false,
+  defaultSize: { w: 0.92, h: 0.32 },
+  defaults: { title: '' },
+  props: ['title', 'screen', 'belongsTo', 'style'],
+  validation: [],
+  styles: ['borderColor', 'borderWidth', 'borderRadius'],
+  properties: [
+    {
+      key: 'subform',
+      title: 'Form',
+      fields: [
+        { path: 'props.title', label: 'Title', type: 'text', help: 'Shown above it. Blank → none' },
+        { path: 'props.screen', label: 'Form', type: 'form', help: 'The published form drawn here, saving into its own table' },
+        { path: 'props.belongsTo', label: 'Linked by', type: 'text',
+          help: 'The field on that form that points back at this record, e.g. employeeId. ' +
+                'Filled in on save and never shown.' }
+      ]
+    },
+    ...styleGroups(['borderColor', 'borderWidth', 'borderRadius'])
+  ]
+}
+
 export const LABEL_VARIANTS = ['heading', 'subheading', 'text']
 
 /** The sizes a label preset starts from, in px at the design width. */

package/src/designs/ControlView.jsx

@@ -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 }) {
+export default function ControlView({ node, mode = 'live', value, error, options, onChange, onBlur, disabled, list, upload, stepper, subform }) {
   const View = VIEWS[node.type]
   if (!View) {
     return <div className="xeplr-factory-unknown">Unknown control “{node.type}”</div>
@@ -33,6 +33,7 @@ export default function ControlView({ node, mode = 'live', value, error, options
       list={list}
       upload={upload}
       stepper={stepper}
+      subform={subform}
     />
   )
 }
@@ -425,6 +426,39 @@ function LabelView({ p }) {
   )
 }
 
+/**
+ * A form inside this one.
+ *
+ * On a running screen, its title and then the form itself — drawn by the page
+ * (`subform.render`), because a design never mounts a controller; until it
+ * has loaded, or when it cannot, that is said in the space it will take.
+ *
+ * On the builder's canvas, what it will draw and how it is linked — never the
+ * form itself, which is another screen's to design.
+ */
+function SubformView({ p, node, design, subform }) {
+  if (!design && subform) {
+    const sub = subform.sub
+    return (
+      <div className="xeplr-factory-subform" style={boxStyle(p.style)}>
+        {p.title && <div className="xeplr-factory-subform-title">{p.title}</div>}
+        {sub.error && <div className="xeplr-factory-invalid" role="alert">{sub.error}</div>}
+        {!sub.error && !sub.document && <div className="xeplr-factory-hint">Loading…</div>}
+        {!sub.error && sub.document && subform.render && subform.render(node, sub)}
+      </div>
+    )
+  }
+  return (
+    <div className="xeplr-factory-subform xeplr-factory-subform--design" style={boxStyle(p.style)}>
+      {p.title && <div className="xeplr-factory-subform-title">{p.title}</div>}
+      <div className="xeplr-factory-subform-what">
+        {p.screen ? <>Form <code>{p.screen}</code></> : 'Choose a form'}
+        {p.belongsTo ? <>, linked by <code>{p.belongsTo}</code></> : ', and the field that links it'}
+      </div>
+    </div>
+  )
+}
+
 function ListControl({ node, design, list }) {
   return <ListView node={node} design={design} {...(list || {})} />
 }
@@ -443,5 +477,6 @@ export const VIEWS = {
   file: FileView,
   stepper: StepperView,
   label: LabelView,
-  list: ListControl
+  list: ListControl,
+  subform: SubformView
 }

package/src/designs/PropertyPanel.jsx

@@ -550,6 +550,24 @@ function ScreenEditor({ id, value, onChange, screens, doc }) {
   return <input id={id} className="xeplr-factory-prop-input xeplr-factory-mono" type="text" placeholder="employee_edit" value={value ?? ''} onChange={(e) => onChange(e.target.value.trim() || undefined)} />
 }
 
+/**
+ * A form to draw inside this one: the screens with fields of their own (a list
+ * screen has nothing to fill in), never this one — a form cannot hold itself.
+ */
+function FormEditor({ id, value, onChange, screens, doc }) {
+  const forms = (screens || []).filter((s) => (!doc || s.id !== doc.id)
+    && (!s.document || (s.document.nodes || []).some((n) => n.props && n.props.name)))
+  if (forms.length) {
+    return (
+      <select id={id} className="xeplr-factory-prop-input" value={value ?? ''} onChange={(e) => onChange(e.target.value || undefined)}>
+        <option value="">— choose a form</option>
+        {forms.map((s) => <option key={s.id} value={s.id}>{s.name}</option>)}
+      </select>
+    )
+  }
+  return <input id={id} className="xeplr-factory-prop-input xeplr-factory-mono" type="text" placeholder="bank_details_edit" value={value ?? ''} onChange={(e) => onChange(e.target.value.trim() || undefined)} />
+}
+
 const ACTION_LABELS = { new: 'New — add a record', edit: 'Edit — open a row for editing', delete: 'Delete — remove a row' }
 
 function ActionsEditor({ value, onChange }) {
@@ -732,6 +750,7 @@ export const EDITORS = {
   color: ColorEditor,
   table: TableEditor,
   screen: ScreenEditor,
+  form: FormEditor,
   columns: ColumnsEditor,
   listTable: ListTableEditor,
   actions: ActionsEditor,

package/src/designs/ScreenSample.jsx

@@ -124,7 +124,7 @@ function SaveButtons({ ctrl }) {
   )
 }
 
-export default function ScreenSample({ ctrl, className, style, renderPopup }) {
+export default function ScreenSample({ ctrl, className, style, renderPopup, renderSubform }) {
   const { document: doc } = ctrl
 
   if (ctrl.documentErrors.length) {
@@ -147,20 +147,23 @@ export default function ScreenSample({ ctrl, className, style, renderPopup }) {
   // A screen with no fields of its own (a list screen) has nothing to save —
   // and no sheet: its list is the card (factory.css, --bare).
   const hasFields = fieldNodes.length > 0
-  const status = hasFields ? <SaveStatus ctrl={ctrl} /> : null
+  // A form inside another has no footer of its own: the host's Save saves it.
+  const footer = !ctrl.embedded
+  const status = hasFields && footer ? <SaveStatus ctrl={ctrl} /> : null
+  // Nor a <form> of its own — one form inside another is not valid HTML.
+  const Page = ctrl.embedded ? 'div' : 'form'
   const steppers = ctrl.steps.nodes
 
   return (
     <div
-      className={'xeplr-factory-screen' + (hasFields ? '' : ' xeplr-factory-screen--bare') + (className ? ' ' + className : '')}
+      className={'xeplr-factory-screen' + (hasFields ? '' : ' xeplr-factory-screen--bare') + (ctrl.embedded ? ' xeplr-factory-screen--embedded' : '') + (className ? ' ' + className : '')}
       style={{ maxWidth: doc.width, '--xf-margin': `${MARGIN * 100}%`, ...screenStyle(doc), ...style }}
     >
-      <form
+      <Page
         className="xeplr-factory-page"
         style={{ height: `${pageHeight}cqw` }}
         // Never a submit: Enter posts nothing and saves nothing. Save is a button.
-        onSubmit={(e) => e.preventDefault()}
-        noValidate
+        {...(ctrl.embedded ? { role: 'group' } : { onSubmit: (e) => e.preventDefault(), noValidate: true })}
         aria-label={doc.name}
       >
         {[...shown].sort((a, b) => (a.z || 0) - (b.z || 0)).map((node) => (
@@ -206,19 +209,22 @@ export default function ScreenSample({ ctrl, className, style, renderPopup }) {
                 onDelete: (rec) => ctrl.deleteRecord(node, rec).catch((err) => window.alert(err.message || 'Could not delete')),
                 onNew: () => (node.props.editScreen ? ctrl.openEditor(node, null) : (ctrl.confirmDiscard() && ctrl.newRecord()))
               } : undefined}
+              // A form inside this one: the page draws it (renderSubform).
+              subform={node.type === 'subform' ? { sub: ctrl.subformFor(node), render: renderSubform } : undefined}
             />
           </div>
         ))}
-      </form>
+      </Page>
       {steppers.map((node, i) => {
         const last = i === steppers.length - 1
         return (
+          // An embedded form keeps its Back and Next; only Save is the host's.
           <StepNav key={node.id} ctrl={ctrl} node={node} status={last ? status : null}>
-            {last && (hasFields || ctrl.doneLabel) && <SaveButtons ctrl={ctrl} />}
+            {last && footer && (hasFields || ctrl.doneLabel) && <SaveButtons ctrl={ctrl} />}
           </StepNav>
         )
       })}
-      {!steppers.length && (hasFields || ctrl.doneLabel) && (
+      {footer && !steppers.length && (hasFields || ctrl.doneLabel) && (
         <div className="xeplr-factory-footer">
           <div className="xeplr-factory-footer-mid">{status}</div>
           <SaveButtons ctrl={ctrl} />

package/src/designs/factory.css

@@ -241,6 +241,19 @@
 .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); }
 
+/* ── a form inside a form ────────────────────────────────────────────────
+   The inner form is drawn as itself, without its own sheet or footer: it is
+   part of this page, and its Save is this page's Save. Its box scrolls when
+   the form is taller than the space it was given. */
+.xeplr-factory-subform { display: flex; flex-direction: column; gap: 8px; width: 100%; height: 100%; box-sizing: border-box; overflow: auto; }
+.xeplr-factory-subform-title { font-weight: 600; font-size: 1.05em; color: var(--xf-ink); }
+.xeplr-factory-screen--embedded { border: none; border-radius: 0; background: none; }
+.xeplr-factory-subform--design {
+  justify-content: center; align-items: center; text-align: center; padding: 12px;
+  border: 1px dashed var(--xf-border); border-radius: 10px; color: var(--xf-muted);
+}
+.xeplr-factory-subform-what code { color: var(--xf-ink); }
+
 /* ── list ───────────────────────────────────────────────────────────────── */
 .xeplr-factory-list {
   display: flex; flex-direction: column; width: 100%; box-sizing: border-box; overflow: auto;
@@ -335,6 +348,7 @@
 .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--subform { border-style: double; border-width: 3px; height: 11px; }
 .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; }
 

package/src/pages.jsx

@@ -79,6 +79,32 @@ export function FactoryScreen(props) {
       ctrl={ctrl}
       className={props.className}
       style={props.style}
+      // A form inside this one: the same component again, saving into its own
+      // table, checked and saved by this one's Save (see useFactoryScreen).
+      // Keyed by the form, never by this record's id — a new record's first
+      // save changes that id while the subform is being saved.
+      renderSubform={(node, sub) => (
+        <FactoryScreen
+          key={`${node.id}:${sub.document.id}`}
+          document={sub.document}
+          record={sub.record || undefined}
+          link={node.props.belongsTo}
+          onReady={(api) => ctrl.registerSubform(node.id, api)}
+          onDirtyChange={(d) => ctrl.subformDirty(node.id, d)}
+          recordKey={props.recordKey}
+          onSave={props.onSave}
+          fetchOptions={props.fetchOptions}
+          fetchRecord={props.fetchRecord}
+          fetchRecords={props.fetchRecords}
+          onDelete={props.onDelete}
+          uploadFile={props.uploadFile}
+          fileUrl={props.fileUrl}
+          screens={props.screens}
+          loadScreen={props.loadScreen}
+          controls={props.controls}
+          hooks={props.hooks}
+        />
+      )}
       renderPopup={(popup) => (
         <ScreenModal
           title={popup.document ? popup.document.name : 'Loading…'}

package/src/useFactoryScreen.js

@@ -29,6 +29,15 @@ import { useUrlSteps } from './useUrlPlaces.js'
 // A list whose `editScreen` names another screen opens that screen in a popup
 // for Edit and New. The screen comes from `screens` ({ id → document }) or the
 // host's `loadScreen(id)`. The list refreshes as the popup saves.
+//
+// ── A FORM INSIDE THIS ONE (subform) ─────────────────────────────────────
+// A `subform` node draws another published form inline, saving into its own
+// table. The view renders it as a second useFactoryScreen with `link` (the
+// field on it pointing back here) and `onReady`, through which it hands this
+// one a handle: validate / dirty / save. One Save writes THIS record first —
+// so a new one has an id — then every subform with changes, with that id in
+// its link field. An untouched subform is not saved: it is one optional
+// record, and an empty one is not worth a row.
 
 /**
  * @param document      a valid screen document
@@ -62,9 +71,23 @@ import { useUrlSteps } from './useUrlPlaces.js'
 export function useFactoryScreen({
   document: doc, record, recordKey = 'id', onSave, fetchOptions, fetchRecords, fetchRecord, onDelete, onChange, screens, loadScreen, hooks, uploadFile, fileUrl,
   onOpenRecord, onDone, onDirtyChange, params, urlKey,
+  link, onReady,
   controls = CONTROLS
 } = {}) {
   const check = useMemo(() => validateDocument(doc, controls), [doc, controls])
+  // EMBEDDED AS A SUBFORM: `link` is the field pointing back at the record
+  // this sits in. It is never shown and never asked for — the host fills it
+  // in on save — so it is left out of what is checked here, and a form
+  // without that field is a mistake said out loud, not a record saved
+  // belonging to nothing.
+  const embedded = Boolean(link)
+  const checkDoc = useMemo(
+    () => (embedded && check.ok ? { ...doc, nodes: doc.nodes.filter((n) => !(n.props && n.props.name === link)) } : doc),
+    [doc, link, embedded, check.ok]
+  )
+  const linkError = embedded && check.ok && !inputNodes(doc, controls).some((n) => n.props.name === link)
+    ? { path: '', message: `"${doc.name || doc.id}" has no field "${link}" — add it, or change "Linked by" on the form this is placed in` }
+    : null
   // Read at call time, so a new hooks object never re-runs loads by itself.
   const hooksRef = useRef(hooks); hooksRef.current = hooks
   const hook = (name) => hookMethod(hooksRef.current, name)
@@ -139,7 +162,7 @@ export function useFactoryScreen({
 
   // Latest of everything a save needs, read at the moment it runs.
   const live = useRef({})
-  live.current = { doc, values, recordId, touched, source, onSave, controls, recordKey }
+  live.current = { doc, checkDoc, values, recordId, touched, source, onSave, controls, recordKey }
 
   // ── options for table dropdowns, fetched once per table ───────────────
   const [options, setOptions] = useState({})   // node id → { loading, items, error }
@@ -180,7 +203,10 @@ export function useFactoryScreen({
   // have branches; which of them apply is the app's to say, from its hooks.
   const [disabledSteps, setDisabledSteps] = useState({})
   const stepperNodes = useMemo(() => (check.ok ? steppers(doc, controls) : []), [check.ok, doc, controls])
-  const visibleNodes = useMemo(() => (check.ok ? nodesForSteps(doc, openSteps, controls) : []), [check.ok, doc, openSteps, controls])
+  const visibleNodes = useMemo(
+    () => (check.ok ? nodesForSteps(doc, openSteps, controls).filter((n) => !(embedded && n.props && n.props.name === link)) : []),
+    [check.ok, doc, openSteps, controls, embedded, link]
+  )
 
   // A screen whose steps changed under it (a field moved to another step, a
   // step removed) must not stay open at a step that is gone. Steppers this
@@ -320,26 +346,50 @@ export function useFactoryScreen({
   }, [options])
   live.current.loadedItems = loadedItems
 
-  const state = useMemo(() => (check.ok ? saveState(doc, values, touched, loadedItems, controls) : { canSave: false, status: 'invalid', errors: {}, shown: {} }),
-    [check.ok, doc, values, touched, loadedItems, controls])
+  const state = useMemo(() => (check.ok ? saveState(checkDoc, values, touched, loadedItems, controls) : { canSave: false, status: 'invalid', errors: {}, shown: {} }),
+    [check.ok, checkDoc, values, touched, loadedItems, controls])
+
+  // ── subforms: the handles they hand over, and which hold changes ──────
+  const subApis = useRef({})          // node id → { validate, dirty, save, name }
+  const subDirty = useRef(new Set())  // node ids of subforms with unsaved changes
+  const [subVersion, setSubVersion] = useState(0)
+  const registerSubform = useCallback((id, api) => {
+    if (api) subApis.current[id] = api
+    else { delete subApis.current[id]; subDirty.current.delete(id) }
+  }, [])
 
   // ── saving ────────────────────────────────────────────────────────────
   const inFlight = useRef(null)     // the promise of the save running now
 
-  /** Save — what the Save button does. One AJAX call; never on its own. */
-  const runSave = useCallback(async () => {
+  /**
+   * Is it fit to save? Says what is missing on every field — including the
+   * ones nobody has been in yet — because pressing Save is the moment to.
+   */
+  const checkNow = useCallback(() => {
+    const l = live.current
+    const st = saveState(l.checkDoc, l.values, l.touched, l.loadedItems, l.controls)
+    if (st.canSave) return { ok: true }
+    const t = new Set([...l.touched, ...Object.keys(st.errors)])
+    live.current.touched = t
+    setTouched(t)
+    setStatus('invalid')
+    return { ok: false, errors: st.errors }
+  }, [])
+
+  /**
+   * Save — what the Save button does. One AJAX call; never on its own.
+   * `extra` is merged into what is sent: a subform's link, from its host.
+   */
+  const runSave = useCallback(async (extra) => {
     if (inFlight.current) return inFlight.current
     const l = live.current
-    const st = saveState(l.doc, l.values, l.touched, l.loadedItems, l.controls)
-    if (!st.canSave) {
-      // Pressing Save is the moment to say what is missing — on every field,
-      // including the ones nobody has been in yet.
-      const t = new Set([...l.touched, ...Object.keys(st.errors)])
-      live.current.touched = t
-      setTouched(t)
-      setStatus('invalid')
-      return { ok: false, errors: st.errors }
-    }
+    // A subform with changes is checked BEFORE anything is written, so a bad
+    // bank account never leaves an employee saved without one.
+    const subs = Object.entries(subApis.current).filter(([id]) => subDirty.current.has(id))
+    const subsOk = subs.map(([, api]) => api.validate()).every(Boolean)
+    const own = checkNow()
+    if (!own.ok) return own
+    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 } }
@@ -349,13 +399,14 @@ export function useFactoryScreen({
     const task = (async () => {
       try {
         const meta = { id: l.recordId, source: l.source, screen: l.doc.id, document: l.doc }
-        const saved = await hook('save')(l.values, {
+        const vals = extra ? { ...l.values, ...extra } : l.values
+        const saved = await hook('save')(vals, {
           ...meta,
           isNew: l.recordId === null || l.recordId === undefined,
           // Save is where an app usually learns which branch it is on, so it
           // can switch steps off from here as well as from step().
           steps: live.current.steps,
-          defaults: { save: (vals) => (l.onSave ? l.onSave(vals, meta) : undefined) }
+          defaults: { save: (v) => (l.onSave ? l.onSave(v, meta) : undefined) }
         })
         // A new record's first save creates it; its id makes the next save an update.
         if (saved && typeof saved === 'object' && saved[l.recordKey] !== undefined && saved[l.recordKey] !== null) {
@@ -363,7 +414,28 @@ export function useFactoryScreen({
           live.current.recordId = saved[l.recordKey]
         }
         savedChanges.current = writing
-        const still = changes.current !== writing
+
+        // THEN THE SUBFORMS, each with this record's id in its link field.
+        // One that fails leaves this record saved and says which did not.
+        if (subs.length) {
+          const failed = []
+          for (const [id, api] of subs) {
+            const r = await api.save(live.current.recordId)
+            if (!r || !r.ok) failed.push(`${api.name()}${r && r.error && r.error.message ? ` (${r.error.message})` : ''}`)
+            // Read from the subform itself, now — its own report of being
+            // clean arrives after this function has decided what to say.
+            else if (!api.dirty()) subDirty.current.delete(id)
+          }
+          setSubVersion((v) => v + 1)
+          if (failed.length) {
+            setDirty(true)
+            setSaveError(`this record was saved, but ${failed.join(', ')} was not`)
+            setStatus('error')
+            return { ok: false, record: saved }
+          }
+        }
+
+        const still = changes.current !== writing || subDirty.current.size > 0
         setDirty(still)
         setSavedAt(new Date())
         setListVersion((v) => v + 1)
@@ -386,21 +458,45 @@ export function useFactoryScreen({
     })()
     inFlight.current = task
     return task
+  }, [setDirty, checkNow])
+
+  /** A subform's changes are this form's unsaved changes too. */
+  const subformDirty = useCallback((id, d) => {
+    if (d) subDirty.current.add(id)
+    else subDirty.current.delete(id)
+    setDirty(changes.current !== savedChanges.current || subDirty.current.size > 0)
+    if (d) setStatus('pending')
   }, [setDirty])
 
+  const unsaved = () => changes.current !== savedChanges.current || subDirty.current.size > 0
+
   /** Save if there is anything unsaved — what a flow's Next does before moving on. */
   const flush = useCallback(async () => {
     if (inFlight.current) await inFlight.current
-    if (changes.current !== savedChanges.current) return runSave()
+    if (unsaved()) return runSave()
     return { ok: true }
-  }, [runSave])
+  }, [runSave])                                               // eslint-disable-line react-hooks/exhaustive-deps
+
+  // EMBEDDED: hand the host what it needs to check and save this form as part
+  // of its own Save. Read through refs, so the handle never goes stale.
+  const onReadyRef = useRef(onReady); onReadyRef.current = onReady
+  useEffect(() => {
+    if (!onReadyRef.current) return undefined
+    onReadyRef.current({
+      validate: () => checkNow().ok,
+      dirty: () => changes.current !== savedChanges.current,
+      save: (ownerId) => runSave({ [link]: ownerId }),
+      name: () => live.current.doc.name || live.current.doc.id
+    })
+    return () => { if (onReadyRef.current) onReadyRef.current(null) }
+  }, [runSave, checkNow, link])
 
   /**
    * May the person leave? True when nothing is unsaved, or when they agree to
    * lose it. Cancel, the popup's × and opening another record all ask this.
    */
   const confirmDiscard = useCallback(() => {
-    if (changes.current === savedChanges.current) return true
+    if (!unsaved()) return true
     // eslint-disable-next-line no-alert
     return typeof window === 'undefined' || window.confirm('Discard your unsaved changes?')
   }, [])
@@ -467,6 +563,8 @@ export function useFactoryScreen({
     setSaveError(null)
     setServerErrors({})
     setStatus('idle')
+    // Its subforms are this record's, so they are read again for it.
+    setSubVersion((v) => v + 1)
   }, [startValues, recordKey, setDirty])
 
   const newRecord = useCallback(() => openRecord(null), [openRecord])
@@ -602,6 +700,49 @@ export function useFactoryScreen({
     }
   }, [])
 
+  // ── subforms: the form each draws, and this record's row of it ────────
+  //
+  // Read when the screen opens, when another record is opened, and after a
+  // Save — never just because the id changed, or a new record's first save
+  // would re-read an empty row over the subform it is in the middle of saving.
+  const [subforms, setSubforms] = useState({})   // node id → { loading, error, document, record }
+  const subformNodes = useMemo(() => (check.ok ? doc.nodes.filter((n) => n.type === 'subform') : []), [doc, check.ok])
+  useEffect(() => {
+    if (!subformNodes.length) return undefined
+    let cancelled = false
+    subformNodes.forEach((node) => {
+      const screenId = node.props.screen
+      setSubforms((m) => ({ ...m, [node.id]: { ...(m[node.id] || {}), loading: true, error: null } }))
+      ;(async () => {
+        let found = screensRef.current && screensRef.current[screenId]
+        if (!found && loadScreenRef.current) found = await loadScreenRef.current(screenId)
+        if (!found) throw new Error(`Form "${screenId}" was not provided — pass it in \`screens\` or supply loadScreen`)
+        const ownerId = live.current.recordId
+        // Nothing to read for a record that is not saved yet: it owns nothing.
+        if (ownerId === null || ownerId === undefined) return { document: found, record: null }
+        const rows = await hook('get')({
+          many: true, id: null, screen: screenId, source: found.source || null, node, document: found,
+          defaults: {
+            get: () => {
+              if (!fetchRecordsRef.current) throw new Error(`No fetchRecords was provided to read "${screenId}"`)
+              return fetchRecordsRef.current({
+                source: found.source || null, screen: screenId, node,
+                belongsTo: node.props.belongsTo, belongsToId: ownerId
+              })
+            }
+          }
+        })
+        return { document: found, record: Array.isArray(rows) && rows.length ? rows[0] : null }
+      })().then(
+        (got) => { if (!cancelled) setSubforms((m) => ({ ...m, [node.id]: { loading: false, error: null, ...got } })) },
+        (err) => { if (!cancelled) setSubforms((m) => ({ ...m, [node.id]: { ...(m[node.id] || {}), loading: false, error: err.message || 'Could not load the form' } })) }
+      )
+    })
+    return () => { cancelled = true }
+  }, [subformNodes, subVersion])                              // eslint-disable-line react-hooks/exhaustive-deps
+
+  const subformFor = useCallback((node) => subforms[node.id] || { loading: true, error: null, document: null, record: null }, [subforms])
+
   const closeEditor = useCallback(() => {
     setPopup(null)
     setListVersion((v) => v + 1)
@@ -617,7 +758,11 @@ export function useFactoryScreen({
 
   return {
     document: doc,
-    documentErrors: check.errors,
+    documentErrors: linkError ? [...check.errors, linkError] : check.errors,
+    embedded,
+    subformFor,
+    registerSubform,
+    subformDirty,
     popup,
     fieldsFor,
     openEditor,

package/src/validateDocument.js

@@ -162,6 +162,7 @@ export function validateDocument(doc, controls = CONTROLS) {
     if (node.type === 'stepper') checkSteps(props, at, err)
     checkStep(node, doc, at, err)
     if (node.type === 'list') checkList(props, doc, at, err)
+    if (node.type === 'subform') checkSubform(props, doc, at, err)
     if (node.type === 'label') {
       if (typeof props.text !== 'string') err(`${at}.props.text`, 'must be a string')
       if (props.variant !== undefined && !LABEL_VARIANTS.includes(props.variant)) err(`${at}.props.variant`, `must be one of: ${LABEL_VARIANTS.join(', ')}`)
@@ -417,6 +418,20 @@ function checkList(props, doc, at, err) {
   }
 }
 
+/**
+ * A form inside this one. Both halves are required: a form with no link saves
+ * a record belonging to nothing, and a link with no form is nothing. Itself is
+ * refused — a form containing itself draws forever.
+ */
+function checkSubform(props, doc, at, err) {
+  if (props.title !== undefined && typeof props.title !== 'string') err(`${at}.props.title`, 'must be a string')
+  if (!(nonEmptyString(props.screen) && SCREEN_ID.test(props.screen))) err(`${at}.props.screen`, 'is required — the id of the form drawn here, e.g. "bank_details_edit"')
+  else if (props.screen === doc.id) err(`${at}.props.screen`, 'cannot be this screen — a form cannot contain itself')
+  if (!(nonEmptyString(props.belongsTo) && /^[A-Za-z_][\w]*$/.test(props.belongsTo))) {
+    err(`${at}.props.belongsTo`, 'is required — the field on that form pointing back at this record, e.g. "employeeId"')
+  }
+}
+
 function nonEmptyString(v) {
   return typeof v === 'string' && v.trim() !== ''
 }