@xeplr/ui-factory 1.0.14 → 1.2.0

package/src/screenSource.js

@@ -0,0 +1,91 @@
+// WHAT A FLOW NEEDS TO KNOW ABOUT THIS APP'S SCREENS.
+//
+// @xeplr/ui-workflow's designer offers a Screen step, and asks its host two
+// things: which screens exist, and what each one hands back when somebody
+// submits it. It cannot answer either itself — it carries a screen key and
+// knows nothing else about forms, on purpose, so that an app with a different
+// screen system is not locked out.
+//
+// This is @xeplr/factory's answer, ONCE. It used to be written out in the app:
+// list the screens, load each document, filter the nodes that hold a value,
+// map them to names and types. That is the same twenty lines in every app the
+// CLI scaffolds, hand-copied, drifting apart the first time a control type is
+// added here — which is exactly the kind of code that should not be in an
+// application at all.
+//
+// Pure: no React. The hook around it is useScreenSource.js.
+
+import { inputNodes } from './document.js'
+
+/**
+ * A screen document → what the designer needs.
+ *
+ * `inputNodes` is this package's own answer to "which nodes hold a value", so
+ * a label, a stepper or a divider is never offered as a field — and a control
+ * type added later is included here without anybody editing an app.
+ */
+export function describeScreen(doc) {
+  if (!doc || !doc.id) return null
+  return {
+    key: doc.id,
+    name: doc.name || doc.id,
+    fields: inputNodes(doc).map(function (n) {
+      return { name: n.id, type: n.type }
+    })
+  }
+}
+
+/** A listing row → the same shape, before its document has been read. */
+export function screenStub(row) {
+  if (!row) return null
+  var key = row.screenKey || row.id || row.key
+  if (!key) return null
+  return { key: key, name: row.name || key }
+}
+
+/**
+ * Every screen, with its fields.
+ *
+ * TWO PASSES, because the second is slow and the first is what makes the menu
+ * usable: `onList` is called with the names as soon as they arrive, and the
+ * result resolves once each document has been read. A document that will not
+ * load leaves its screen in the list WITHOUT fields — choosable, with its
+ * output typed by hand, rather than missing.
+ *
+ * @param api     a createFactoryApi() instance
+ * @param onList  optional, called with the names-only list first
+ */
+export async function loadScreens(api, onList) {
+  var rows = await api.listScreens()
+  var stubs = (rows || []).map(screenStub).filter(Boolean)
+  if (onList) onList(stubs)
+
+  return Promise.all(stubs.map(async function (stub) {
+    try {
+      return describeScreen(await api.loadScreen(stub.key)) || stub
+    } catch (err) {
+      return stub
+    }
+  }))
+}
+
+/** "Leave request" → "leave_request": what a new form is keyed by. */
+export function keyFromName(label) {
+  return String(label == null ? '' : label)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '_')
+    .replace(/^_+|_+$/g, '')
+}
+
+/**
+ * The screen a new entity's FORM half is, from what createEntity answered.
+ *
+ * Read off the response rather than spelled out here: the naming is this
+ * package's and may not stay "<key>_edit", and an app guessing it would break
+ * quietly the day it changes.
+ */
+export function editScreenOf(made, fallbackKey) {
+  var edit = made && made.edit
+  if (edit && typeof edit === 'object') return edit.id || edit.screenKey || fallbackKey
+  return edit || fallbackKey
+}

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/urlState.js

@@ -0,0 +1,71 @@
+// WHERE YOU ARE LIVES IN THE URL — the pure half, no React.
+//
+// The step a stepper is open at, and the control (or flow step) whose
+// properties are open, are places a person navigates to: a refresh or a
+// shared link must land on them again. This file is how they are named in the
+// URL's query; useUrlPlaces.js reads and writes them.
+//
+// THE KEYS ARE THE HOST'S. A builder, a running screen and the preview inside
+// the builder can share one page, and the host app has keys of its own, so a
+// hook writes the URL only when given a `urlKey`. Without one it keeps the
+// same values in memory, exactly as before.
+
+/**
+ * The query keys under a host's `urlKey`, or null (in memory).
+ *   factoryUrlKeys('form') → { steps: 'formSteps', selected: 'formSelected' }
+ */
+export function factoryUrlKeys(urlKey) {
+  if (!urlKey) return null
+  return { steps: `${urlKey}Steps`, selected: `${urlKey}Selected` }
+}
+
+/**
+ * Which step each stepper is open at → one query value. Step 0 is where a
+ * stepper starts, so it is left out — a screen on its first steps has a
+ * clean URL. Ids are URI-encoded, so one holding ':' or ',' splits back.
+ *   { s1: 2, s2: 0 } → 's1:2'
+ */
+export function encodeSteps(open) {
+  return Object.keys(open || {})
+    .filter((id) => Number.isInteger(open[id]) && open[id] > 0)
+    .map((id) => `${encodeURIComponent(id)}:${open[id]}`)
+    .join(',') || null
+}
+
+/** The query value back to { stepper id: index }; anything unreadable is dropped. */
+export function decodeSteps(value) {
+  const open = {}
+  if (!value || typeof value !== 'string') return open
+  value.split(',').forEach((pair) => {
+    const at = pair.lastIndexOf(':')
+    if (at <= 0) return
+    if (!/^\d+$/.test(pair.slice(at + 1))) return
+    const index = Number(pair.slice(at + 1))
+    let id
+    try { id = decodeURIComponent(pair.slice(0, at)) } catch { return }
+    open[id] = index
+  })
+  return open
+}
+
+/**
+ * Selecting adds a history entry when it opens or closes the properties
+ * (nothing → something, something → nothing), so Back closes them; moving
+ * from one selected thing to another is a switch and replaces the entry.
+ */
+export function replacesHistory(previous, next) {
+  const had = previous !== null && previous !== undefined && previous !== ''
+  const has = next !== null && next !== undefined && next !== ''
+  return had && has
+}
+
+/**
+ * A multi-selection is NOT a place: it is a working set for Delete or
+ * Duplicate, not somewhere a person goes. Only a single selection — the one
+ * whose properties are open — is named in the URL.
+ *   one id → that id      none, or several → null
+ */
+export function selectionPlace(ids) {
+  const list = ids ? [...ids] : []
+  return list.length === 1 ? list[0] : null
+}

package/src/useFactoryBuilder.js

@@ -6,6 +6,9 @@ import {
   removeNodes
 } from './document.js'
 import { validateDocument } from './validateDocument.js'
+import { presetFor, presetProps, presetGroup, presetHints, convertField } from './presets.js'
+import { useUrlSteps, useUrlSelection } from './useUrlPlaces.js'
+import { selectionPlace } from './urlState.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
@@ -35,10 +38,29 @@ import { validateDocument } from './validateDocument.js'
  *                    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)
+ * @param urlKey      where the selected control and the open steps live in the URL:
+ *                    `<urlKey>Selected` and `<urlKey>Steps`, so a refresh or a shared
+ *                    link lands on the same control. Omitted → kept in memory.
  */
-export function useFactoryBuilder({ document: given, name, onSave, onChange, onPublish, listTables, screens, lockedNames, controls = CONTROLS, autosaveDelay = 800 } = {}) {
+export function useFactoryBuilder({ document: given, name, onSave, onChange, onPublish, listTables, screens, lockedNames, controls = CONTROLS, autosaveDelay = 800, urlKey } = {}) {
   const [doc, setDoc] = useState(() => given || createScreen({ name }))
-  const [selected, setSelected] = useState(() => new Set())
+
+  // ── selection ─────────────────────────────────────────────────────────
+  // ONE selected control is a place — its properties are open — so it is
+  // named in the URL (by id, found again in the document). Several selected
+  // is a working set for Delete or Duplicate, not a place: it stays here, and
+  // the URL then names nothing.
+  const [placeId, selectPlace] = useUrlSelection(urlKey)
+  const [several, setSeveral] = useState(null)
+  const placeNode = placeId === null ? null : doc.nodes.find((n) => String(n.id) === placeId) || null
+  const placeNodeId = placeNode ? placeNode.id : null
+  const selected = useMemo(() => several || new Set(placeNodeId === null ? [] : [placeNodeId]), [several, placeNodeId])
+  const selectedRef = useRef(selected); selectedRef.current = selected
+  const setSelected = useCallback((next) => {
+    const ids = [...((typeof next === 'function' ? next(selectedRef.current) : next) || [])]
+    setSeveral(ids.length > 1 ? new Set(ids) : null)
+    selectPlace(selectionPlace(ids))
+  }, [selectPlace])
   const [dirty, setDirty] = useState(false)
   const [saving, setSaving] = useState(false)
   const [saveError, setSaveError] = useState(null)
@@ -56,7 +78,10 @@ export function useFactoryBuilder({ document: given, name, onSave, onChange, onP
     if (JSON.stringify(given) === JSON.stringify(docRef.current)) return
     docRef.current = given
     setDoc(given)
-    setSelected(new Set())
+    // A multi-selection belongs to the old document. The URL's control is
+    // kept: a host that loads the screen after mounting hands it in here, and
+    // the link's control is found in it — or, if it is not there, nothing is.
+    setSeveral(null)
     setDirty(false)
   }, [given])
 
@@ -103,7 +128,7 @@ export function useFactoryBuilder({ document: given, name, onSave, onChange, onP
   // Which step of each stepper is open on the canvas. Everything dropped while
   // a step is open belongs to that step, and the canvas shows only that step —
   // so one screen holds as many little screens as it has steps.
-  const [openSteps, setOpenSteps] = useState({})
+  const [openSteps, setOpenSteps] = useUrlSteps(urlKey)
   const stepperNodes = useMemo(() => steppers(doc, controls), [doc, controls])
   const [building, setBuilding] = useState(null)      // the stepper being built
   const activeStepper = stepperNodes.find((n) => n.id === building) || stepperNodes[stepperNodes.length - 1] || null
@@ -112,7 +137,7 @@ export function useFactoryBuilder({ document: given, name, onSave, onChange, onP
   const goToStep = useCallback((id, index) => {
     setBuilding(id)
     setOpenSteps((o) => ({ ...o, [id]: index }))
-  }, [])
+  }, [setOpenSteps])
 
   /** The step a new control lands on: the one open on the stepper being built. */
   const dropStep = useCallback(() => (
@@ -124,30 +149,51 @@ 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
     })
     if (added) setSelected(new Set([added.id]))
     return added
-  }, [update, controls, dropStep])
+  }, [update, controls, dropStep, setSelected])
 
   const moveControl = useCallback((id, patch) => update((d) => moveNode(d, id, patch)), [update])
 
   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
+  /**
+   * 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 removeSelected = useCallback(() => {
     const ids = [...selectedRef.current]
     if (!ids.length) return
     update((d) => removeNodes(d, ids))
     setSelected(new Set())
-  }, [update])
+  }, [update, setSelected])
 
   /** Everything selected moves to a copy, just below the original. */
   const duplicateSelected = useCallback(() => {
@@ -168,10 +214,12 @@ export function useFactoryBuilder({ document: given, name, onSave, onChange, onP
       return next
     })
     setSelected(new Set(created))
-  }, [update, controls])
+  }, [update, controls, setSelected])
 
   // ── 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 +259,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 +278,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 +295,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 +309,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 +322,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 +353,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 +379,8 @@ export function useFactoryBuilder({ document: given, name, onSave, onChange, onP
     },
     visibleNodes,
     setProperty,
+    convertControl,
+    hints,
     removeSelected,
     duplicateSelected,
     tables,