@xeplr/ui-factory 1.0.13 → 1.1.0

package/src/tableSchema.js

@@ -18,8 +18,12 @@
 // ── CHANGES THAT ARE SAFE, AND CHANGES THAT ARE REFUSED ──────────────────
 //   new field                 ADD COLUMN
 //   wider (varchar 80 → 120, varchar → text, integer → numeric)   ALTER TYPE
-//   narrower, or a different type (text → number)   REFUSED — data would be
-//                             lost or rejected; write that migration by hand
+//   narrower, or a different type (text → number)   REFUSED in a migration file —
+//                             data would be lost or rejected; write that by hand.
+//                             On PUBLISH, a CONVERSION instead (below): the saved
+//                             values are checked first, and the column changes
+//                             only if every one of them fits, and only once the
+//                             person has confirmed
 //   field removed             column KEPT, reported as unused — dropping data
 //                             is a deliberate migration, never a side effect
 //   field renamed             seen as a NEW column beside an unused old one, with
@@ -130,6 +134,11 @@ export function widening(from, to) {
   if (from.type === 'integer' && to.type === 'numeric') return { ok: true }
   // A date becomes that day at midnight; the other way round would lose the time.
   if (from.type === 'date' && to.type === 'timestamp') return { ok: true }
+  // Not safe for ANY data, but safe for data that fits: the value checks in
+  // conversionFor() say whether this table's does.
+  if (convertible(from, to)) {
+    return { ok: false, convert: true, reason: `${describe(from)} → ${describe(to)} changes the kind of value — every saved value has to fit` }
+  }
   return { ok: false, reason: `${describe(from)} → ${describe(to)} is a different kind of value` }
 }
 
@@ -153,7 +162,7 @@ export function diffTables(before, after) {
     const old = was[c.name]
     if (!old) { add.push(c); return }
     const w = widening(old, c)
-    if (!w.ok) refused.push({ column: c.name, reason: w.reason })
+    if (!w.ok) refused.push(w.convert ? { column: c.name, reason: w.reason, convert: { from: old, to: c } } : { column: c.name, reason: w.reason })
     else if (!w.same) alter.push({ from: old, to: c })
   })
   const unused = before.columns.filter((c) => !now[c.name])
@@ -237,6 +246,85 @@ export function dropStatement(t, name) {
   return `ALTER TABLE ${q(t)} DROP COLUMN IF EXISTS ${q(name)};`
 }
 
+// ── conversions: a field that became another kind ────────────────────────
+//
+// "LinkedIn URL" typed as text and later made a number, a date, a yes/no…
+// The column can follow ONLY IF every value already saved in it fits the new
+// kind. For each conversion there are three pieces of SQL, all read-only but
+// the last:
+//
+//   check     how many saved values would NOT fit — publish refuses unless 0
+//   sample    up to five of them, to show the person what is in the way
+//   statement the ALTER, with a USING that turns each value into the new kind
+//
+// Empty text becomes NULL rather than failing: a blank box saved as '' is "no
+// value", in the new kind as in the old.
+//
+// NO "?" ANYWHERE IN THIS SQL. Hosts run it through knex.raw, which reads every
+// ? as a binding placeholder — an optional regex group spelled [+-]? silently
+// became a different pattern. Optional is spelled {0,1}.
+
+const TEXTUAL = ['varchar', 'text']
+const CONVERT_TO_FROM_TEXT = ['integer', 'numeric', 'date', 'timestamp', 'boolean']
+const TRUE_WORDS = "'true','t','yes','y','1'"
+const FALSE_WORDS = "'false','f','no','n','0'"
+
+function convertible(from, to) {
+  if (from.references || to.references) return false
+  if (TEXTUAL.includes(from.type) && CONVERT_TO_FROM_TEXT.includes(to.type)) return true
+  if (TEXTUAL.includes(to.type) && ['integer', 'numeric', 'date', 'timestamp', 'boolean', 'varchar'].includes(from.type)) return true
+  if (from.type === 'numeric' && to.type === 'integer') return true
+  return false
+}
+
+/**
+ * @returns {{ check, sample, statement }} — see above; null when the change is
+ *          not a conversion this knows how to make
+ */
+export function conversionFor(table, from, to) {
+  if (!convertible(from, to)) return null
+  const t = q(table)
+  const c = q(to.name)
+  const txt = `btrim(${c}::text)`
+  let bad
+  let using
+  if (TEXTUAL.includes(to.type)) {
+    // Anything becomes text; a varchar only if it is long enough.
+    bad = to.type === 'varchar' ? `length(${c}::text) > ${to.length}` : 'false'
+    using = `${c}::text`
+  } else if (from.type === 'numeric' && to.type === 'integer') {
+    bad = `${c} <> trunc(${c})`
+    using = `${c}::integer`
+  } else if (to.type === 'integer') {
+    bad = `${txt} <> '' AND NOT (${txt} ~ '^[+-]{0,1}[0-9]{1,9}$')`
+    using = `NULLIF(${txt}, '')::integer`
+  } else if (to.type === 'numeric') {
+    bad = `${txt} <> '' AND NOT (${txt} ~ '^[+-]{0,1}([0-9]+[.]{0,1}[0-9]*|[.][0-9]+)([eE][+-]{0,1}[0-9]+){0,1}$')`
+    using = `NULLIF(${txt}, '')::numeric`
+  } else if (to.type === 'date') {
+    bad = `${txt} <> '' AND NOT (${txt} ~ '^[0-9]{4}-[0-9]{2}-[0-9]{2}$')`
+    using = `NULLIF(${txt}, '')::date`
+  } else if (to.type === 'timestamp') {
+    bad = `${txt} <> '' AND NOT (${txt} ~ '^[0-9]{4}-[0-9]{2}-[0-9]{2}([ T][0-9]{2}:[0-9]{2}(:[0-9]{2}([.][0-9]+){0,1}){0,1}){0,1}$')`
+    using = `NULLIF(${txt}, '')::timestamp`
+  } else if (to.type === 'boolean') {
+    bad = `lower(${txt}) NOT IN (${TRUE_WORDS}, ${FALSE_WORDS}, '')`
+    using = `CASE WHEN lower(${txt}) IN (${TRUE_WORDS}) THEN true WHEN lower(${txt}) IN (${FALSE_WORDS}) THEN false ELSE NULL END`
+  }
+  const where = `${c} IS NOT NULL AND (${bad})`
+  const type = to.type === 'varchar' ? `varchar(${to.length})` : to.type
+  // A boolean field is NOT NULL DEFAULT false (columnForField): blanks become false.
+  const fill = to.notNull && to.default !== undefined
+    ? [`UPDATE ${t} SET ${c} = ${to.default} WHERE ${c} IS NULL;`, `ALTER TABLE ${t} ALTER COLUMN ${c} SET DEFAULT ${to.default};`, `ALTER TABLE ${t} ALTER COLUMN ${c} SET NOT NULL;`]
+    : []
+  return {
+    check: `SELECT count(*)::int AS n FROM ${t} WHERE ${where}`,
+    sample: `SELECT ${c}::text AS v FROM ${t} WHERE ${where} LIMIT 5`,
+    count: `SELECT count(*)::int AS n FROM ${t} WHERE ${c} IS NOT NULL`,
+    statements: [`ALTER TABLE ${t} ALTER COLUMN ${c} TYPE ${type} USING ${using};`, ...fill]
+  }
+}
+
 // ── publish: apply directly ──────────────────────────────────────────────
 //
 // Publishing a screen changes its table straight away — no migration files.
@@ -279,11 +367,19 @@ export function columnFromDatabase(c) {
  * @param options.managed      names ever published as fields on this table
  * @param options.inUse        names other published screens on this table still use
  * @param options.confirmDrop  names the person has confirmed dropping
+ * @param options.convert         true: plan conversions (the caller runs their checks).
+ *                                 OFF by default — a host that does not know about them
+ *                                 must see a refusal, not a plan it would publish
+ *                                 without running (that would skip the ALTER)
+ * @param options.confirmConvert  names the person has confirmed converting
  * @returns {{
  *   table, create,
  *   add, alter,             what will change
  *   drop,                   columns to drop: [{ name }]
  *   unconfirmed,            of those, the ones not yet confirmed — nothing runs until this is empty
+ *   convert,                columns changing kind: [{ column, from, to, check, sample, count }] —
+ *                           the host runs `check` and refuses unless it is 0 for each
+ *   unconfirmedConvert,     of those, the ones not yet confirmed — nothing runs until this is empty
  *   keep,                   columns left in place, with why: [{ name, reason }]
  *   refused,                changes that cannot be made safely: [{ column, reason }] — nothing runs
  *   statements              the SQL, in order — empty while anything is refused or unconfirmed
@@ -294,7 +390,8 @@ export function planTableChange(current, next, options = {}, controls = CONTROLS
   const managed = new Set(options.managed || [])
   const inUse = new Set(options.inUse || [])
   const confirmed = new Set(options.confirmDrop || [])
-  const plan = { table: after.table, create: false, add: [], alter: [], drop: [], unconfirmed: [], keep: [], refused: [], statements: [] }
+  const converting = new Set(options.confirmConvert || [])
+  const plan = { table: after.table, create: false, add: [], alter: [], drop: [], unconfirmed: [], convert: [], unconfirmedConvert: [], keep: [], refused: [], statements: [] }
 
   if (!current) {
     plan.create = true
@@ -309,7 +406,12 @@ export function planTableChange(current, next, options = {}, controls = CONTROLS
   const diff = diffTables({ table: after.table, columns: existing }, after)
   plan.add = diff.add
   plan.alter = diff.alter
-  plan.refused = diff.refused
+  diff.refused.forEach((r) => {
+    const how = options.convert && r.convert && conversionFor(after.table, r.convert.from, r.convert.to)
+    if (!how) { plan.refused.push({ column: r.column, reason: r.reason }); return }
+    plan.convert.push({ column: r.column, from: describe(r.convert.from), to: describe(r.convert.to), check: how.check, sample: how.sample, count: how.count, statements: how.statements })
+  })
+  plan.unconfirmedConvert = plan.convert.filter((c) => !converting.has(c.column)).map((c) => c.column)
 
   diff.unused.forEach((c) => {
     if (!managed.has(c.name)) plan.keep.push({ name: c.name, reason: 'not created by a screen — left as it is' })
@@ -318,9 +420,10 @@ export function planTableChange(current, next, options = {}, controls = CONTROLS
   })
   plan.unconfirmed = plan.drop.filter((d) => !confirmed.has(d.name)).map((d) => d.name)
 
-  if (plan.refused.length || plan.unconfirmed.length) return plan
+  if (plan.refused.length || plan.unconfirmed.length || plan.unconfirmedConvert.length) return plan
   plan.add.forEach((c) => plan.statements.push(...addStatements(after.table, c)))
   plan.alter.forEach(({ from, to }) => plan.statements.push(alterStatement(after.table, from, to)))
+  plan.convert.forEach((c) => plan.statements.push(...c.statements))
   plan.drop.forEach((d) => plan.statements.push(dropStatement(after.table, d.name)))
   return plan
 }

package/src/useFactoryBuilder.js

@@ -6,6 +6,7 @@ import {
   removeNodes
 } from './document.js'
 import { validateDocument } from './validateDocument.js'
+import { presetFor, presetProps, presetGroup, presetHints, convertField } from './presets.js'
 
 // The builder's controller: the document being edited, what is selected, and
 // every change the builder can make. No JSX — designs/BuilderSample.jsx draws
@@ -124,11 +125,18 @@ export function useFactoryBuilder({ document: given, name, onSave, onChange, onP
 
   const visibleNodes = useMemo(() => nodesForSteps(doc, openSteps, controls), [doc, openSteps, controls])
 
-  /** Adds a control and selects it, so its properties are open straight away. */
+  /**
+   * Adds a control and selects it, so its properties are open straight away.
+   * `type` may be a ready-made field — "preset:email" — which adds its control
+   * with the preset's settings already in it.
+   */
   const addControl = useCallback((type, at) => {
     let added = null
+    const preset = presetFor(type)
     update((d) => {
-      const r = addControlTo(d, type, { at, step: dropStep() }, controls)
+      const r = preset
+        ? addControlTo(d, preset.control, { at, step: dropStep(), props: presetProps(preset), size: preset.size }, controls)
+        : addControlTo(d, type, { at, step: dropStep() }, controls)
       added = r.node
       return r.document
     })
@@ -141,6 +149,21 @@ export function useFactoryBuilder({ document: given, name, onSave, onChange, onP
   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])
 
+  /**
+   * A field becomes another kind — a control type ('number') or a ready-made
+   * field ('email'). Returns what did not carry over, in words, for the panel
+   * to say ("the pattern", "the options").
+   */
+  const convertControl = useCallback((id, target) => {
+    let dropped = []
+    update((d) => {
+      const r = convertField(d, id, target, controls, { lockedNames: lockedRef.current })
+      dropped = r.dropped
+      return r.document
+    })
+    return dropped
+  }, [update, controls])
+
   const selectedRef = useRef(selected); selectedRef.current = selected
   const removeSelected = useCallback(() => {
     const ids = [...selectedRef.current]
@@ -172,6 +195,8 @@ export function useFactoryBuilder({ document: given, name, onSave, onChange, onP
 
   // ── validation + save ─────────────────────────────────────────────────
   const validation = useMemo(() => validateDocument(doc, controls), [doc, controls])
+  /** Fields that read like a ready-made one they are not. Never block anything. */
+  const hints = useMemo(() => presetHints(doc, controls), [doc, controls])
 
   /** Errors grouped by node id, for the canvas and the property panel. */
   const errorsByNode = useMemo(() => {
@@ -211,12 +236,18 @@ export function useFactoryBuilder({ document: given, name, onSave, onChange, onP
     }
   }, [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])
+  // NOTHING SAVES ITSELF. Saving is an act, and the person designing decides
+  // when they have finished — a screen that writes itself to the server a
+  // moment after every drag means there is no such thing as trying something
+  // out, and no moment at which somebody said "this is right".
+  //
+  // It also made every half-made field an error: a field is invalid while it
+  // is being built, and an autosave meets it mid-build and reports it.
+  //
+  // `save` is called by the Design's Save control (see BuilderSample), and by
+  // publish, which saves first because publishing what is on screen is the
+  // one thing it must never get wrong. `autosaveDelay` is kept as a prop and
+  // ignored, so a host passing it is not broken by this; it does nothing.
 
   // PUBLISH: the draft becomes the next version — what screens actually show.
   // Deliberate, unlike saving: a half-finished design must not reach everyone
@@ -224,7 +255,11 @@ export function useFactoryBuilder({ document: given, name, onSave, onChange, onP
   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) => {
+  /**
+   * @param confirmDrop     column names the person agreed to remove
+   * @param confirmConvert  column names the person agreed to convert to their field's new kind
+   */
+  const publish = useCallback(async (confirmDrop, confirmConvert) => {
     if (!onPublishRef.current) return { ok: false }
     const check = validateDocument(docRef.current, controls)
     if (!check.ok) {
@@ -237,7 +272,10 @@ export function useFactoryBuilder({ document: given, name, onSave, onChange, onP
     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 res = await onPublishRef.current(docRef.current, {
+        confirmDrop: Array.isArray(confirmDrop) ? confirmDrop : [],
+        confirmConvert: Array.isArray(confirmConvert) ? confirmConvert : []
+      })
       const kept = (res && res.keep) || []
       const r = {
         ok: true,
@@ -248,10 +286,12 @@ export function useFactoryBuilder({ document: given, name, onSave, onChange, onP
       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 }
+      // A removed field would drop a column, or a field that changed kind would
+      // convert one: not an error, a question.
+      const asks = (Array.isArray(err.confirm) && err.confirm.length) || (Array.isArray(err.convert) && err.convert.length)
+      const r = asks
+        ? { ok: false, confirm: err.confirm || [], convert: err.convert || [], message: err.message }
+        : { ok: false, message: err.message || 'Could not publish', detail: err.detail, wontFit: err.wontFit }
       setPublishResult(r)
       return r
     } finally {
@@ -259,10 +299,12 @@ export function useFactoryBuilder({ document: given, name, onSave, onChange, onP
     }
   }, [controls, save])
 
+  // `pending` now means "there are changes you have not saved", which is a
+  // thing to act on rather than a thing about to happen by itself.
   const status = saveError ? 'error'
     : saving ? 'saving'
     : !validation.ok ? 'invalid'
-    : dirty ? 'pending'
+    : dirty ? 'unsaved'
     : savedAt ? 'saved' : 'idle'
 
   // ── keyboard: Delete / Backspace removes, Cmd/Ctrl+D duplicates ────────
@@ -288,7 +330,12 @@ export function useFactoryBuilder({ document: given, name, onSave, onChange, onP
   return {
     document: doc,
     controls,
-    palette: useMemo(() => controlGroups(controls), [controls]),
+    // The controls, then the ready-made fields made of the ones this registry has.
+    palette: useMemo(() => {
+      const ready = presetGroup()
+      ready.controls = ready.controls.filter((c) => controls[c.icon] && controls[c.icon].input)
+      return ready.controls.length ? [...controlGroups(controls), ready] : controlGroups(controls)
+    }, [controls]),
     selected,
     setSelected,
     selectedNode,
@@ -309,6 +356,8 @@ export function useFactoryBuilder({ document: given, name, onSave, onChange, onP
     },
     visibleNodes,
     setProperty,
+    convertControl,
+    hints,
     removeSelected,
     duplicateSelected,
     tables,

package/src/useFactoryScreen.js

@@ -7,11 +7,14 @@ import { hookMethod } from './hooks.js'
 
 // A saved screen, running. No JSX — designs/ScreenSample.jsx draws it.
 //
-// ── 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.
+// ── SAVED BY A BUTTON, OVER AJAX — NEVER A FORM SUBMIT ───────────────────
+// Nothing is written while the person types. Changes are held in the form
+// ("Unsaved changes") until they press Save, which makes ONE AJAX call to the
+// host's onSave. There is no <form> post and no page reload — and no
+// background save either: a half-typed record never lands in the table. The
+// first save of a new record creates it (the host hands back its id); every
+// save after that updates the same record. Leaving with unsaved changes asks
+// first (Cancel, the popup's ×, closing the tab).
 //
 // ── THE DATABASE IS THE HOST'S ───────────────────────────────────────────
 // Everything that reads or writes data is a call the host supplies:
@@ -26,9 +29,6 @@ import { hookMethod } from './hooks.js'
 // 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 record        the record to open, e.g. { id: 7, firstName: 'Ada' } — omit for a new one
@@ -45,14 +45,14 @@ export const AUTOSAVE_DELAY = 700
  * @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 onDirtyChange (dirty) → void — whether there are unsaved changes, as that changes
  * @param controls      the control registry (default: the built-ins)
  * @param hooks         a FactoryHooks (or an object with some of its methods) — get / save / delete / actions
  */
 export function useFactoryScreen({
   document: doc, record, recordKey = 'id', onSave, fetchOptions, fetchRecords, fetchRecord, onDelete, onChange, screens, loadScreen, hooks, uploadFile, fileUrl,
-  onOpenRecord, onDone,
-  autosaveDelay = AUTOSAVE_DELAY, controls = CONTROLS
+  onOpenRecord, onDone, onDirtyChange,
+  controls = CONTROLS
 } = {}) {
   const check = useMemo(() => validateDocument(doc, controls), [doc, controls])
   // Read at call time, so a new hooks object never re-runs loads by itself.
@@ -105,7 +105,7 @@ export function useFactoryScreen({
   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 [status, setStatus] = useState('idle')    // idle | pending (unsaved changes) | saving | saved | incomplete | invalid | error
   const [saveError, setSaveError] = useState(null)
   const [savedAt, setSavedAt] = useState(null)
   const [listVersion, setListVersion] = useState(0)
@@ -113,7 +113,17 @@ export function useFactoryScreen({
   // 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.
+  // UNSAVED CHANGES: every change bumps `changes`; a save records which count
+  // it wrote. A change made while a save was on the wire stays unsaved.
+  const changes = useRef(0)
+  const savedChanges = useRef(0)
+  const [dirty, setDirtyState] = useState(false)
+  const onDirtyRef = useRef(onDirtyChange); onDirtyRef.current = onDirtyChange
+  const setDirty = useCallback((d) => {
+    setDirtyState((was) => { if (was !== d) onDirtyRef.current?.(d); return d })
+  }, [])
+
+  // 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 }
 
@@ -300,19 +310,25 @@ export function useFactoryScreen({
     [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
 
+  /** Save — what the Save button does. One AJAX call; never on its own. */
   const runSave = useCallback(async () => {
-    clearTimeout(timer.current)
-    timer.current = null
-    if (inFlight.current) { again.current = true; return inFlight.current }
+    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) { setStatus(st.status); return { ok: false, errors: st.errors } }
+    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 }
+    }
     const customSave = hooksRef.current && typeof hooksRef.current.save === 'function'
-    if (!l.onSave && !customSave) { setStatus('saved'); return { ok: true } }
+    const writing = changes.current
+    if (!l.onSave && !customSave) { savedChanges.current = writing; setDirty(false); setStatus('saved'); return { ok: true } }
 
     setStatus('saving')
     setSaveError(null)
@@ -332,9 +348,12 @@ export function useFactoryScreen({
           setRecordId(saved[l.recordKey])
           live.current.recordId = saved[l.recordKey]
         }
+        savedChanges.current = writing
+        const still = changes.current !== writing
+        setDirty(still)
         setSavedAt(new Date())
         setListVersion((v) => v + 1)
-        setStatus('saved')
+        setStatus(still ? 'pending' : 'saved')
         return { ok: true, record: saved }
       } catch (err) {
         const onFields = Array.isArray(err.fields) ? err.fields.filter((f) => f && f.field && f.message) : []
@@ -349,27 +368,36 @@ export function useFactoryScreen({
         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
-  }, [])
+  }, [setDirty])
 
-  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. */
+  /** Save if there is anything unsaved — what a flow's Next does before moving on. */
   const flush = useCallback(async () => {
-    if (timer.current || again.current) return runSave()
-    if (inFlight.current) return inFlight.current
+    if (inFlight.current) await inFlight.current
+    if (changes.current !== savedChanges.current) return runSave()
     return { ok: true }
   }, [runSave])
 
-  useEffect(() => () => clearTimeout(timer.current), [])
+  /**
+   * 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
+    // eslint-disable-next-line no-alert
+    return typeof window === 'undefined' || window.confirm('Discard your unsaved changes?')
+  }, [])
+
+  // Closing the tab or reloading with unsaved changes: the browser's own prompt.
+  useEffect(() => {
+    if (!dirty || typeof window === 'undefined') return undefined
+    const warn = (e) => { e.preventDefault(); e.returnValue = '' }
+    window.addEventListener('beforeunload', warn)
+    return () => window.removeEventListener('beforeunload', warn)
+  }, [dirty])
 
   // ── editing ───────────────────────────────────────────────────────────
   const onChangeRef = useRef(onChange); onChangeRef.current = onChange
@@ -395,8 +423,10 @@ export function useFactoryScreen({
       setTouched(t)
     }
     onChangeRef.current?.(next)
-    schedule()
-  }, [optionsFor, schedule])
+    changes.current += 1
+    setDirty(true)
+    setStatus('pending')
+  }, [optionsFor, setDirty])
 
   /** Leaving a field shows its message, even if nothing was typed. */
   const touch = useCallback((node) => {
@@ -407,9 +437,12 @@ export function useFactoryScreen({
     setTouched(t)
   }, [])
 
-  /** Open a record: whatever was pending is saved first. */
+  /** Open a record (null: a new one). Unsaved changes are dropped — ask confirmDiscard first. */
   const openRecord = useCallback(async (rec) => {
-    await flush()
+    if (inFlight.current) await inFlight.current
+    changes.current = 0
+    savedChanges.current = 0
+    setDirty(false)
     const next = startValues(rec)
     live.current.values = next
     live.current.recordId = rec ? rec[recordKey] ?? null : null
@@ -420,7 +453,7 @@ export function useFactoryScreen({
     setSaveError(null)
     setServerErrors({})
     setStatus('idle')
-  }, [flush, startValues, recordKey])
+  }, [startValues, recordKey, setDirty])
 
   const newRecord = useCallback(() => openRecord(null), [openRecord])
 
@@ -490,7 +523,6 @@ export function useFactoryScreen({
     })
     // 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)
@@ -576,7 +608,10 @@ export function useFactoryScreen({
     upload,
     fileUrl,
     flush,
+    save: runSave,
     saveNow: runSave,
+    dirty,
+    confirmDiscard,
     openRecord,
     newRecord,
     listFor,

package/src/useScreenSource.js

@@ -0,0 +1,81 @@
+// THIS APP'S SCREENS, AS ANOTHER PACKAGE'S DESIGNER WANTS THEM.
+//
+// One hook, so that using @xeplr/factory's forms inside @xeplr/ui-workflow's
+// flow designer is two props rather than a page of glue in every application:
+//
+//   const { screens, screenEditor } = useScreenSource(factory, { Builder: FactoryBuilder })
+//   <WorkflowDesigner screens={screens} screenEditor={screenEditor} … />
+//
+// It answers both questions that designer asks its host — which screens exist
+// and what each one holds, and how to design one without leaving the flow —
+// and it reloads itself when a form is published from in there, so a form
+// made inside a flow is immediately choosable in it.
+//
+// WHY HERE. The alternative was the same twenty lines copied into every app
+// the CLI scaffolds: list the screens, read each document, filter the nodes
+// that hold a value, wire a builder to publish. Copied code cannot be fixed
+// once — an app generated last month keeps that copy forever, and a control
+// type added to this package never reaches any of them.
+//
+// No JSX, like every other hook here: the element is built with
+// createElement so the file stays .js.
+
+import { createElement, useCallback, useEffect, useMemo, useState } from 'react'
+import { loadScreens } from './screenSource.js'
+import { ScreenEditorSample } from './designs/ScreenEditorSample.jsx'
+
+/**
+ * @param api  a createFactoryApi() instance
+ * @param opts { Builder, labels } — the builder component to draw, normally
+ *             FactoryBuilder. Passed in rather than imported so this hook does
+ *             not pull the whole builder into a bundle that never opens it.
+ * @returns { screens, screenEditor, reload, loading, error }
+ */
+export function useScreenSource(api, opts) {
+  opts = opts || {}
+  var Builder = opts.Builder
+  var labels = opts.labels
+
+  const [screens, setScreens] = useState([])
+  const [loading, setLoading] = useState(true)
+  const [error, setError] = useState(null)
+  const [round, setRound] = useState(0)
+
+  const reload = useCallback(() => setRound((n) => n + 1), [])
+
+  useEffect(() => {
+    let cancelled = false
+    setLoading(true)
+    // The names arrive first so the menu works while the documents are still
+    // being read — see loadScreens.
+    loadScreens(api, (stubs) => { if (!cancelled) setScreens(stubs) })
+      .then((full) => { if (!cancelled) { setScreens(full); setError(null) } })
+      // A designer that still works, minus the menu: a key can be typed.
+      .catch((e) => { if (!cancelled) { setScreens([]); setError(e.message) } })
+      .then(() => { if (!cancelled) setLoading(false) })
+    return () => { cancelled = true }
+  }, [api, round])
+
+  // The render prop @xeplr/ui-workflow calls inside its modal. Stable, so
+  // typing in the flow does not remount the builder.
+  const screenEditor = useCallback((props) => {
+    if (!Builder) return null
+    return createElement(ScreenEditorSample, {
+      api: api,
+      Builder: Builder,
+      screenKey: props.screenKey,
+      labels: labels,
+      onDone: function (screen) {
+        // Reload, so a form made in there joins the menu. The designer is
+        // also told directly, so the step is right before this lands.
+        reload()
+        if (props.onDone) props.onDone(screen)
+      }
+    })
+  }, [api, Builder, labels, reload])
+
+  return useMemo(
+    () => ({ screens, screenEditor, reload, loading, error }),
+    [screens, screenEditor, reload, loading, error]
+  )
+}