@xeplr/ui-factory 1.0.1 → 1.0.3

package/src/useFactoryBuilder.js

@@ -1,7 +1,7 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import { CONTROLS, controlGroups } from './controls.js'
 import {
-  createScreen, renameScreen, addControl as addControlTo, moveNode, setNodeProperty,
+  createScreen, renameScreen, setScreenProperty, addControl as addControlTo, moveNode, setNodeProperty,
   removeNodes
 } from './document.js'
 import { validateDocument } from './validateDocument.js'
@@ -14,36 +14,49 @@ import { validateDocument } from './validateDocument.js'
 // the `document` it is handed and gives the result to `onSave`. A document
 // handed in LATER (Claude regenerated the screen, another record was opened)
 // replaces what is being edited.
+//
+// NO SAVE BUTTON. Every edit is saved a moment after the last one, whenever the
+// screen is valid; while it is not, the problems are shown and nothing is sent.
 
 /**
  * @param document    the screen to edit; omitted → a new empty screen
  * @param name        the name for a new screen (when no document)
- * @param onSave      async (document) → void; called only with a valid document
+ * @param onSave      async (document) → void; called automatically, only with a valid document
+ * @param autosaveDelay ms of quiet after the last edit before saving (default 800)
  * @param onChange    (document) → void; every edit, for hosts that autosave or preview
  * @param listTables  async () → [{ id, name }] | string[]; offered in a dropdown's
  *                    "from a table" picker. Omitted → table sources can still be typed.
+ * @param screens     [{ id, name, document? }] — other screens, offered for a list's "Edit in";
+ *                    with its document, a list screen can pick columns from its fields
+ * @param lockedNames field names that are already columns of the table — they cannot be renamed
+ * @param onPublish   async (document, { confirmDrop }) → { version } — makes the saved draft the version
+ *                    everyone sees, and changes its table to match. Throw to refuse (the message is
+ *                    shown); throw with `confirm: [{ column, records }]` when removed fields would drop
+ *                    columns — the builder asks, and calls again with confirmDrop naming them.
  * @param controls    the control registry (default: the built-ins)
  */
-export function useFactoryBuilder({ document: given, name, onSave, onChange, listTables, controls = CONTROLS } = {}) {
+export function useFactoryBuilder({ document: given, name, onSave, onChange, onPublish, listTables, screens, lockedNames, controls = CONTROLS, autosaveDelay = 800 } = {}) {
   const [doc, setDoc] = useState(() => given || createScreen({ name }))
   const [selected, setSelected] = useState(() => new Set())
   const [dirty, setDirty] = useState(false)
   const [saving, setSaving] = useState(false)
   const [saveError, setSaveError] = useState(null)
-  const [showErrors, setShowErrors] = useState(false)
+  const [savedAt, setSavedAt] = useState(null)
   const docRef = useRef(doc); docRef.current = doc
 
-  // A NEW document from outside replaces the draft. Compared by identity: the
-  // host re-rendering with the same object must not throw away edits.
+  // A NEW document from outside replaces the draft. Not a new OBJECT: a host
+  // that re-reads what it just saved hands back the same screen as a fresh
+  // object on every autosave, and replacing the draft with it would drop the
+  // selection each time. Only different content replaces what is being edited.
   const lastGiven = useRef(given)
   useEffect(() => {
     if (!given || given === lastGiven.current) return
     lastGiven.current = given
+    if (JSON.stringify(given) === JSON.stringify(docRef.current)) return
     docRef.current = given
     setDoc(given)
     setSelected(new Set())
     setDirty(false)
-    setShowErrors(false)
   }, [given])
 
   // Every edit goes through here. It works on a REF of the current document,
@@ -82,6 +95,8 @@ export function useFactoryBuilder({ document: given, name, onSave, onChange, lis
 
   // ── edits ─────────────────────────────────────────────────────────────
   const rename = useCallback((value) => update((d) => renameScreen(d, value)), [update])
+  /** A screen property by path — `source`, `width`, `style.fontSize`. */
+  const setScreen = useCallback((path, value) => update((d) => setScreenProperty(d, path, value)), [update])
 
   /** Adds a control and selects it, so its properties are open straight away. */
   const addControl = useCallback((type, at) => {
@@ -97,7 +112,8 @@ export function useFactoryBuilder({ document: given, name, onSave, onChange, lis
 
   const moveControl = useCallback((id, patch) => update((d) => moveNode(d, id, patch)), [update])
 
-  const setProperty = useCallback((id, path, value) => update((d) => setNodeProperty(d, id, path, value, controls)), [update, controls])
+  const lockedRef = useRef(lockedNames); lockedRef.current = lockedNames
+  const setProperty = useCallback((id, path, value) => update((d) => setNodeProperty(d, id, path, value, controls, { lockedNames: lockedRef.current })), [update, controls])
 
   const selectedRef = useRef(selected); selectedRef.current = selected
   const removeSelected = useCallback(() => {
@@ -144,24 +160,84 @@ export function useFactoryBuilder({ document: given, name, onSave, onChange, lis
   }, [validation, doc.nodes])
 
   const onSaveRef = useRef(onSave); onSaveRef.current = onSave
+  const savingRef = useRef(false)
   const save = useCallback(async () => {
-    setShowErrors(true)
-    setSaveError(null)
-    if (!validation.ok) return { ok: false, errors: validation.errors }
+    const current = docRef.current
+    const check = validateDocument(current, controls)
+    if (!check.ok) return { ok: false, errors: check.errors }
     if (!onSaveRef.current) return { ok: false, errors: [{ path: '', message: 'No onSave was provided' }] }
+    if (savingRef.current) return { ok: false, busy: true }
+    savingRef.current = true
     setSaving(true)
+    setSaveError(null)
     try {
-      await onSaveRef.current(doc)
-      setDirty(false)
-      setShowErrors(false)
+      await onSaveRef.current(current)
+      // Only clean if nothing changed while the save was out.
+      if (docRef.current === current) setDirty(false)
+      setSavedAt(new Date())
       return { ok: true }
     } catch (err) {
       setSaveError(err.message || 'Could not save')
       return { ok: false, errors: [{ path: '', message: err.message }] }
     } finally {
+      savingRef.current = false
       setSaving(false)
     }
-  }, [doc, validation])
+  }, [controls])
+
+  // AUTOSAVE: a quiet moment after the last edit, if the screen is valid.
+  useEffect(() => {
+    if (!dirty || !validation.ok || !onSaveRef.current) return undefined
+    const t = setTimeout(save, autosaveDelay)
+    return () => clearTimeout(t)
+  }, [doc, dirty, validation.ok, save, autosaveDelay, saving])
+
+  // PUBLISH: the draft becomes the next version — what screens actually show.
+  // Deliberate, unlike saving: a half-finished design must not reach everyone
+  // filling the form in.
+  const onPublishRef = useRef(onPublish); onPublishRef.current = onPublish
+  const [publishing, setPublishing] = useState(false)
+  const [publishResult, setPublishResult] = useState(null)   // { ok, message, version?, detail? }
+  const publish = useCallback(async (confirmDrop) => {
+    if (!onPublishRef.current) return { ok: false }
+    const check = validateDocument(docRef.current, controls)
+    if (!check.ok) {
+      const r = { ok: false, message: `Fix ${check.errors.length} problem${check.errors.length === 1 ? '' : 's'} before publishing` }
+      setPublishResult(r)
+      return r
+    }
+    setPublishing(true)
+    setPublishResult(null)
+    try {
+      const saved = await save()
+      if (!saved.ok && !saved.busy) throw new Error((saved.errors && saved.errors[0] && saved.errors[0].message) || 'Could not save the draft')
+      const res = await onPublishRef.current(docRef.current, { confirmDrop: Array.isArray(confirmDrop) ? confirmDrop : [] })
+      const kept = (res && res.keep) || []
+      const r = {
+        ok: true,
+        version: res && res.version,
+        message: (res && res.version ? `Published version ${res.version}` : 'Published') +
+          (kept.length ? ` — kept ${kept.map((k) => k.name).join(', ')} (${kept[0].reason})` : '')
+      }
+      setPublishResult(r)
+      return r
+    } catch (err) {
+      // A removed field would drop a column: not an error, a question.
+      const r = Array.isArray(err.confirm) && err.confirm.length
+        ? { ok: false, confirm: err.confirm, message: err.message }
+        : { ok: false, message: err.message || 'Could not publish', detail: err.detail }
+      setPublishResult(r)
+      return r
+    } finally {
+      setPublishing(false)
+    }
+  }, [controls, save])
+
+  const status = saveError ? 'error'
+    : saving ? 'saving'
+    : !validation.ok ? 'invalid'
+    : dirty ? 'pending'
+    : savedAt ? 'saved' : 'idle'
 
   // ── keyboard: Delete / Backspace removes, Cmd/Ctrl+D duplicates ────────
   useEffect(() => {
@@ -192,18 +268,27 @@ export function useFactoryBuilder({ document: given, name, onSave, onChange, lis
     selectedNode,
     selectedControl: selectedNode ? controls[selectedNode.type] : null,
     rename,
+    setScreen,
     addControl,
     moveControl,
     setProperty,
     removeSelected,
     duplicateSelected,
     tables,
+    screens: screens || [],
+    lockedNames: lockedNames || [],
     validation,
     errorsByNode,
-    showErrors,
     dirty,
     saving,
     saveError,
-    save
+    savedAt,
+    status,
+    save,
+    canPublish: Boolean(onPublish),
+    publish,
+    publishing,
+    publishResult,
+    clearPublishResult: () => setPublishResult(null)
   }
 }

package/src/useFactoryScreen.js

@@ -2,50 +2,95 @@ import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import { CONTROLS } from './controls.js'
 import { inputNodes } from './document.js'
 import { validateDocument } from './validateDocument.js'
-import { initialValues, parseInput, validateValues, fieldError, optionValue } from './values.js'
+import { initialValues, parseInput, saveState, fieldError, optionValue, recordValues, listSource } from './values.js'
 
-// A saved screen, running: its values, its dropdown options, validation and
-// submit. No JSX — designs/ScreenSample.jsx draws it.
+// A saved screen, running. No JSX — designs/ScreenSample.jsx draws it.
 //
-// The DATABASE IS THE HOST'S. A dropdown reading a table asks the host for its
-// rows — `fetchOptions({ table })` → [{ id, name }] — and a submit hands the
-// values to `onSubmit`. Nothing here knows where either goes.
+// ── NO SUBMIT ────────────────────────────────────────────────────────────
+// The screen saves ITSELF, in the background, a moment after the person stops
+// changing something — once what is entered is acceptable. There is no button
+// to press and no page to post. The first save of a new record creates it
+// (the host hands back its id); every save after that updates the same record.
+//
+// ── THE DATABASE IS THE HOST'S ───────────────────────────────────────────
+// Everything that reads or writes data is a call the host supplies:
+//   onSave(values, { id, source, screen, document })   → the saved record (with its id)
+//   fetchRecords({ source, screen, node })             → rows, for a list
+//   onDelete({ id, source, screen, record })
+//   fetchOptions({ table, node })              → [{ id, name }], for a table dropdown
+//
+// ── LIST → EDIT IN A POPUP ───────────────────────────────────────────────
+// 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.
+
+/** Quiet time after the last change before a save goes out. */
+export const AUTOSAVE_DELAY = 700
 
 /**
  * @param document      a valid screen document
- * @param fetchOptions  async ({ table, node }) → [{ id, name }]  — for table dropdowns
- * @param onSubmit      async (values, { document }) → void
- * @param values        initial values, e.g. the record being edited
+ * @param record        the record to open, e.g. { id: 7, firstName: 'Ada' } — omit for a new one
+ * @param recordKey     the id field on a record (default 'id')
+ * @param onSave        async (values, { id, source, document }) → saved record | void
+ * @param fetchOptions  async ({ table, node }) → [{ id, name }]
+ * @param fetchRecords  async ({ source, node }) → records, for lists
+ * @param onDelete      async ({ id, source, record }) → void
+ * @param onChange      (values) → void — every change, before any save
+ * @param fetchRecord   async ({ screen, id }) → record — Edit loads the record fresh (through the server's get hooks)
+ * @param screens       { id → document } — screens a list's Edit / New can open
+ * @param loadScreen    async (id) → document — for screens not in `screens`
+ * @param autosaveDelay ms (default 700)
  * @param controls      the control registry (default: the built-ins)
  */
-export function useFactoryScreen({ document: doc, fetchOptions, onSubmit, values: provided, controls = CONTROLS } = {}) {
+export function useFactoryScreen({
+  document: doc, record, recordKey = 'id', onSave, fetchOptions, fetchRecords, fetchRecord, onDelete, onChange, screens, loadScreen,
+  autosaveDelay = AUTOSAVE_DELAY, controls = CONTROLS
+} = {}) {
   const check = useMemo(() => validateDocument(doc, controls), [doc, controls])
   const inputs = useMemo(() => (check.ok ? inputNodes(doc, controls) : []), [doc, controls, check.ok])
 
-  const [values, setValues] = useState(() => (check.ok ? initialValues(doc, provided, controls) : {}))
-  const [errors, setErrors] = useState({})
-  const [submitted, setSubmitted] = useState(false)
-  const [submitting, setSubmitting] = useState(false)
-  const [submitError, setSubmitError] = useState(null)
+  // A LIST SCREEN has no fields of its own; what its columns mean — that
+  // `department` is a dropdown whose 2 reads "Finance" — lives on the screen it
+  // edits in. Those fields are borrowed for display, and their table options
+  // loaded alongside this screen's own.
+  const fieldsFor = useCallback((node) => {
+    if (inputs.length || !node || !node.props.editScreen) return inputs
+    const editDoc = screens && screens[node.props.editScreen]
+    return editDoc && validateDocument(editDoc, controls).ok ? inputNodes(editDoc, controls) : []
+  }, [inputs, screens, controls])
+  const optionNodes = useMemo(() => {
+    if (!check.ok) return []
+    const borrowed = doc.nodes.filter((n) => n.type === 'list').flatMap((n) => (inputs.length ? [] : fieldsFor(n)))
+    return [...inputs, ...borrowed]
+  }, [check.ok, doc, inputs, fieldsFor])
+  const source = check.ok ? doc.source || null : null
 
-  // A different document or record starts the form over.
-  const providedRef = useRef(provided); providedRef.current = provided
-  const firstRun = useRef(true)
-  useEffect(() => {
-    if (firstRun.current) { firstRun.current = false; return }
-    if (!check.ok) return
-    setValues(initialValues(doc, providedRef.current, controls))
-    setErrors({})
-    setSubmitted(false)
-    setSubmitError(null)
-  }, [doc, provided, controls, check.ok])
+  const startValues = useCallback(
+    (rec) => (rec ? { ...initialValues(doc, {}, controls), ...recordValues(doc, rec, controls) } : initialValues(doc, {}, controls)),
+    [doc, controls]
+  )
+
+  const [values, setValues] = useState(() => (check.ok ? startValues(record) : {}))
+  const [recordId, setRecordId] = useState(() => (record ? record[recordKey] ?? null : null))
+  const [touched, setTouched] = useState(() => new Set())
+  const [status, setStatus] = useState('idle')    // idle | pending | saving | saved | incomplete | invalid | error
+  const [saveError, setSaveError] = useState(null)
+  const [savedAt, setSavedAt] = useState(null)
+  const [listVersion, setListVersion] = useState(0)
+  // Messages the SERVER put on fields — a hook's reject, a rule only it knows.
+  // Shown like the form's own, and cleared as soon as that field is changed.
+  const [serverErrors, setServerErrors] = useState({})
+
+  // Latest of everything a delayed save needs, read at the moment it runs.
+  const live = useRef({})
+  live.current = { doc, values, recordId, touched, source, onSave, controls, recordKey }
 
   // ── options for table dropdowns, fetched once per table ───────────────
   const [options, setOptions] = useState({})   // node id → { loading, items, error }
-  const fetchRef = useRef(fetchOptions); fetchRef.current = fetchOptions
+  const fetchOptionsRef = useRef(fetchOptions); fetchOptionsRef.current = fetchOptions
   useEffect(() => {
     let cancelled = false
-    const tableNodes = inputs.filter((n) => n.type === 'dropdown' && n.props.data?.source === 'table')
+    const tableNodes = optionNodes.filter((n) => n.type === 'dropdown' && n.props.data?.source === 'table')
     if (!tableNodes.length) { setOptions({}); return undefined }
     setOptions(Object.fromEntries(tableNodes.map((n) => [n.id, { loading: true, items: [], error: null }])))
     const byTable = new Map()
@@ -55,8 +100,8 @@ export function useFactoryScreen({ document: doc, fetchOptions, onSubmit, values
       byTable.get(t).push(n)
     })
     byTable.forEach((nodes, table) => {
-      const run = fetchRef.current
-        ? Promise.resolve().then(() => fetchRef.current({ table, node: nodes[0] }))
+      const run = fetchOptionsRef.current
+        ? Promise.resolve().then(() => fetchOptionsRef.current({ table, node: nodes[0] }))
         : Promise.reject(new Error(`No fetchOptions was provided to read "${table}"`))
       run
         .then((rows) => {
@@ -68,9 +113,8 @@ export function useFactoryScreen({ document: doc, fetchOptions, onSubmit, values
         })
     })
     return () => { cancelled = true }
-  }, [inputs])
+  }, [optionNodes])
 
-  /** The options a dropdown shows, whichever source they come from. */
   const optionsFor = useCallback((node) => {
     if (node.props.data?.source === 'static') return { loading: false, items: node.props.data.options, error: null }
     return options[node.id] || { loading: false, items: [], error: null }
@@ -81,69 +125,237 @@ export function useFactoryScreen({ document: doc, fetchOptions, onSubmit, values
     Object.entries(options).forEach(([id, o]) => { if (!o.loading && !o.error) map[id] = o.items })
     return map
   }, [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])
+
+  // ── saving ────────────────────────────────────────────────────────────
+  const timer = useRef(null)
+  const inFlight = useRef(null)     // the promise of the save running now
+  const again = useRef(false)       // a change arrived while it ran
+
+  const runSave = useCallback(async () => {
+    clearTimeout(timer.current)
+    timer.current = null
+    if (inFlight.current) { again.current = true; return inFlight.current }
+    const l = live.current
+    const st = saveState(l.doc, l.values, l.touched, l.loadedItems, l.controls)
+    if (!st.canSave) { setStatus(st.status); return { ok: false, errors: st.errors } }
+    if (!l.onSave) { setStatus('saved'); return { ok: true } }
+
+    setStatus('saving')
+    setSaveError(null)
+    const task = (async () => {
+      try {
+        const saved = await l.onSave(l.values, { id: l.recordId, source: l.source, screen: l.doc.id, document: l.doc })
+        // 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) {
+          setRecordId(saved[l.recordKey])
+          live.current.recordId = saved[l.recordKey]
+        }
+        setSavedAt(new Date())
+        setListVersion((v) => v + 1)
+        setStatus('saved')
+        return { ok: true, record: saved }
+      } catch (err) {
+        const onFields = Array.isArray(err.fields) ? err.fields.filter((f) => f && f.field && f.message) : []
+        if (onFields.length) {
+          setServerErrors(Object.fromEntries(onFields.map((f) => [f.field, f.message])))
+          setStatus('invalid')
+          setSaveError(null)
+        } else {
+          setSaveError(err.message || 'Could not save')
+          setStatus('error')
+        }
+        return { ok: false, error: err }
+      } finally {
+        inFlight.current = null
+        if (again.current) { again.current = false; schedule() }  // eslint-disable-line no-use-before-define
+      }
+    })()
+    inFlight.current = task
+    return task
+  }, [])
+
+  const schedule = useCallback(() => {
+    clearTimeout(timer.current)
+    setStatus('pending')
+    timer.current = setTimeout(runSave, autosaveDelay)
+  }, [runSave, autosaveDelay])
+
+  /** Save any pending change right away — before opening another record, say. */
+  const flush = useCallback(async () => {
+    if (timer.current || again.current) return runSave()
+    if (inFlight.current) return inFlight.current
+    return { ok: true }
+  }, [runSave])
+
+  useEffect(() => () => clearTimeout(timer.current), [])
 
   // ── editing ───────────────────────────────────────────────────────────
+  const onChangeRef = useRef(onChange); onChangeRef.current = onChange
   const setValue = useCallback((node, raw) => {
     let value = parseInput(node, raw)
     if (node.type === 'dropdown' && value !== undefined) value = optionValue(optionsFor(node).items, value)
-    setValues((v) => {
-      const next = { ...v }
-      if (value === undefined) delete next[node.props.name]
-      else next[node.props.name] = value
-      return next
+    const name = node.props.name
+    const next = { ...live.current.values }
+    if (value === undefined) delete next[name]
+    else next[name] = value
+    live.current.values = next
+    setValues(next)
+    setServerErrors((e) => {
+      if (!(name in e)) return e
+      const rest = { ...e }
+      delete rest[name]
+      return rest
     })
-    // Once a submit has failed, errors follow the typing — the message goes
-    // away the moment the field is fixed, not on the next click of Save.
-    if (submitted) {
-      setErrors((e) => {
-        const msg = fieldError(node, value, loadedItems[node.id])
-        const next = { ...e }
-        if (msg) next[node.props.name] = msg
-        else delete next[node.props.name]
-        return next
-      })
+    if (!live.current.touched.has(name)) {
+      const t = new Set(live.current.touched); t.add(name)
+      live.current.touched = t
+      setTouched(t)
     }
-  }, [submitted, optionsFor, loadedItems])
-
-  const reset = useCallback(() => {
-    setValues(initialValues(doc, providedRef.current, controls))
-    setErrors({})
-    setSubmitted(false)
-    setSubmitError(null)
-  }, [doc, controls])
-
-  const onSubmitRef = useRef(onSubmit); onSubmitRef.current = onSubmit
-  const submit = useCallback(async (e) => {
-    e?.preventDefault?.()
-    setSubmitted(true)
-    setSubmitError(null)
-    const found = validateValues(doc, values, controls, loadedItems)
-    setErrors(found)
-    if (Object.keys(found).length) return { ok: false, errors: found }
-    if (!onSubmitRef.current) return { ok: true, values }
-    setSubmitting(true)
+    onChangeRef.current?.(next)
+    schedule()
+  }, [optionsFor, schedule])
+
+  /** Leaving a field shows its message, even if nothing was typed. */
+  const touch = useCallback((node) => {
+    const name = node.props.name
+    if (live.current.touched.has(name)) return
+    const t = new Set(live.current.touched); t.add(name)
+    live.current.touched = t
+    setTouched(t)
+  }, [])
+
+  /** Open a record: whatever was pending is saved first. */
+  const openRecord = useCallback(async (rec) => {
+    await flush()
+    const next = startValues(rec)
+    live.current.values = next
+    live.current.recordId = rec ? rec[recordKey] ?? null : null
+    live.current.touched = new Set()
+    setValues(next)
+    setRecordId(live.current.recordId)
+    setTouched(new Set())
+    setSaveError(null)
+    setServerErrors({})
+    setStatus('idle')
+  }, [flush, startValues, recordKey])
+
+  const newRecord = useCallback(() => openRecord(null), [openRecord])
+
+  // A different document, or a different record handed in, starts over.
+  const firstRun = useRef(true)
+  useEffect(() => {
+    if (firstRun.current) { firstRun.current = false; return }
+    if (!check.ok) return
+    openRecord(record || null)
+  }, [doc, record]) // eslint-disable-line react-hooks/exhaustive-deps
+
+  // ── lists ─────────────────────────────────────────────────────────────
+  const [lists, setLists] = useState({})   // node id → { loading, rows, error }
+  const fetchRecordsRef = useRef(fetchRecords); fetchRecordsRef.current = fetchRecords
+  const listNodes = useMemo(() => (check.ok ? doc.nodes.filter((n) => n.type === 'list') : []), [doc, check.ok])
+  useEffect(() => {
+    if (!listNodes.length) return undefined
+    let cancelled = false
+    listNodes.forEach((node) => {
+      const src = listSource(doc, node)
+      setLists((l) => ({ ...l, [node.id]: { rows: l[node.id]?.rows || [], loading: true, error: null } }))
+      const run = fetchRecordsRef.current
+        ? Promise.resolve().then(() => fetchRecordsRef.current({ source: src, screen: doc.id, node }))
+        : Promise.reject(new Error(`No fetchRecords was provided to list "${src}"`))
+      run
+        .then((rows) => { if (!cancelled) setLists((l) => ({ ...l, [node.id]: { rows: Array.isArray(rows) ? rows : [], loading: false, error: null } })) })
+        .catch((err) => { if (!cancelled) setLists((l) => ({ ...l, [node.id]: { rows: l[node.id]?.rows || [], loading: false, error: err.message || 'Could not load records' } })) })
+    })
+    return () => { cancelled = true }
+  }, [listNodes, listVersion, doc])
+
+  const listFor = useCallback((node) => lists[node.id] || { rows: [], loading: false, error: null }, [lists])
+
+  const onDeleteRef = useRef(onDelete); onDeleteRef.current = onDelete
+  const deleteRecord = useCallback(async (node, rec) => {
+    const id = rec ? rec[recordKey] : undefined
+    if (!onDeleteRef.current) throw new Error('No onDelete was provided')
+    await onDeleteRef.current({ id, source: listSource(doc, node), screen: doc.id, record: rec })
+    // Deleting the record that is open leaves nothing to save into.
+    if (id !== undefined && id === live.current.recordId) {
+      clearTimeout(timer.current); timer.current = null
+      await openRecord(null)
+    }
+    setListVersion((v) => v + 1)
+  }, [doc, recordKey, openRecord])
+
+  // ── popup: a list's Edit / New in its edit screen ─────────────────────
+  const [popup, setPopup] = useState(null)   // { node, screenId, record, document, loading, error }
+  const screensRef = useRef(screens); screensRef.current = screens
+  const fetchRecordRef = useRef(fetchRecord); fetchRecordRef.current = fetchRecord
+  const loadScreenRef = useRef(loadScreen); loadScreenRef.current = loadScreen
+
+  /** Edit (a record) or New (null) in the list's edit screen. */
+  const openEditor = useCallback(async (node, rec) => {
+    const screenId = node.props.editScreen
+    const base = { node, screenId, record: rec || null, document: null, loading: true, error: null }
+    setPopup(base)
     try {
-      await onSubmitRef.current(values, { document: doc })
-      return { ok: true, values }
+      let found = screensRef.current && screensRef.current[screenId]
+      if (!found && loadScreenRef.current) found = await loadScreenRef.current(screenId)
+      if (!found) throw new Error(`Screen "${screenId}" was not provided — pass it in \`screens\` or supply loadScreen`)
+      const checked = validateDocument(found, live.current.controls)
+      if (!checked.ok) throw new Error(`Screen "${screenId}" is not valid: ${checked.errors[0].path} ${checked.errors[0].message}`)
+      // Edit opens the record as it is NOW, through the server's get hooks —
+      // not the list's copy, which may be stale or shaped for the list.
+      let fresh = rec || null
+      if (rec && fetchRecordRef.current && rec[live.current.recordKey] !== undefined) {
+        fresh = await fetchRecordRef.current({ screen: screenId, id: rec[live.current.recordKey] })
+      }
+      setPopup((p) => (p && p.screenId === screenId ? { ...p, document: found, record: fresh, loading: false } : p))
     } catch (err) {
-      setSubmitError(err.message || 'Could not submit')
-      return { ok: false, error: err }
-    } finally {
-      setSubmitting(false)
+      setPopup((p) => (p && p.screenId === screenId ? { ...p, loading: false, error: err.message } : p))
     }
-  }, [doc, values, controls, loadedItems])
+  }, [])
+
+  const closeEditor = useCallback(() => {
+    setPopup(null)
+    setListVersion((v) => v + 1)
+  }, [])
+
+  /** The popup's saves go to the host's onSave, and refresh the list behind it. */
+  const onSaveRef = useRef(onSave); onSaveRef.current = onSave
+  const popupSave = useCallback(async (vals, meta) => {
+    const saved = onSaveRef.current ? await onSaveRef.current(vals, meta) : undefined
+    setListVersion((v) => v + 1)
+    return saved
+  }, [])
 
   return {
     document: doc,
     documentErrors: check.errors,
+    popup,
+    fieldsFor,
+    openEditor,
+    closeEditor,
+    popupSave,
     values,
-    errors,
+    recordId,
+    errors: { ...state.shown, ...serverErrors },
+    allErrors: state.errors,
+    status,
+    saveError,
+    savedAt,
     setValue,
+    touch,
     optionsFor,
-    submit,
-    reset,
-    submitting,
-    submitError
+    flush,
+    saveNow: runSave,
+    openRecord,
+    newRecord,
+    listFor,
+    deleteRecord,
+    recordKey,
+    canDelete: Boolean(onDelete)
   }
 }