@xeplr/ui-factory 1.0.14 → 1.2.0

package/src/designs/styles.js

@@ -40,12 +40,22 @@ export function boxStyle(style) {
   })
 }
 
-/** The screen's defaults, on its container: what every control inherits. */
+/**
+ * The screen's defaults, on its container: what every control inherits.
+ *
+ * A screen with no colours of its own follows the app's theme (factory.css).
+ * One that sets them keeps them EVERYWHERE — its ink and paper become the
+ * tokens the controls read, input boxes included — so a screen designed dark
+ * ink on white is never shown as that ink on a dark theme's input box.
+ */
 export function screenStyle(doc) {
   const s = doc.style || {}
   return clean({
     '--xf-width': doc.width,
     '--xf-font': s.fontSize,
+    '--xf-ink': s.color,
+    '--xf-surface': s.background,
+    '--xf-field-bg': s.background,
     fontFamily: s.fontFamily,
     color: s.color,
     background: s.background

package/src/generate.js

@@ -26,6 +26,7 @@
 import { CONTROLS, CHOICE_TYPES } from './controls.js'
 import { createScreen, addControl, MARGIN, GAP, slugify, camelName, stepsOf } from './document.js'
 import { assertValidDocument } from './validateDocument.js'
+import { presetFor, presetProps, suggestPreset } from './presets.js'
 
 /** Heights by control, as page fractions (a page is as tall as it is wide). */
 export const SPEC_HEIGHTS = {
@@ -45,7 +46,7 @@ export const SPEC_HEIGHTS = {
  */
 export const ROW_GAP = 0.04
 
-const FIELD_KEYS = ['type', 'label', 'name', 'required', 'placeholder', 'default', 'validation', 'data', 'options', 'table', 'layout', 'accept', 'maxSize', 'step', 'steps', 'showNumbers', 'width', 'text', 'variant', 'style']
+const FIELD_KEYS = ['type', 'preset', 'label', 'name', 'required', 'placeholder', 'default', 'validation', 'data', 'options', 'table', 'layout', 'accept', 'maxSize', 'step', 'steps', 'showNumbers', 'width', 'text', 'variant', 'style']
 const SPEC_KEYS = ['name', 'id', 'source', 'columns', 'heading', 'fields', 'list', 'aspect', 'width', 'style']
 const LIST_KEYS = ['title', 'source', 'columns', 'pageSize', 'actions', 'style']
 
@@ -58,6 +59,12 @@ const LIST_KEYS = ['title', 'source', 'columns', 'pageSize', 'actions', 'style']
  *   fields    in reading order. Each: { label, type?='text', name?, required?, placeholder?,
  *             default?, validation?, width?: 'half'|'full' }
  *             dropdown: options: ['Full time', …] or [{ id, name }]  —or—  table: 'departments'
+ *             READY-MADE: `type` may be a preset key — 'email', 'phone', 'url', 'linkedin',
+ *             'age', 'dateOfBirth', 'gender', 'country', 'amount', 'percentage', 'yesNo',
+ *             'postalCode' (presets.js) — or `preset: '<key>'`. A field with NO type and
+ *             no options is matched by its label: { label: 'Age' } is a whole number 0–130,
+ *             { label: 'LinkedIn URL' } a LinkedIn address. `type: 'text'` opts out.
+ *             Anything the field also gives (label, required, validation…) wins.
  *             section heading: { type: 'label', text, variant?: 'subheading' }
  *   source?   the table records are saved to, e.g. 'employees'
  *   width?    design width in px (default 800) — style sizes are px at this width
@@ -65,7 +72,8 @@ const LIST_KEYS = ['title', 'source', 'columns', 'pageSize', 'actions', 'style']
  *   list?     true, or { title, source, columns: [{ field, label }], pageSize, actions } —
  *             a list of the saved records below the fields, with New / Edit / Delete
  *
- * There is no submit button: a screen saves itself as it is filled in.
+ * Do not add a button control for saving: every screen already has Save (and
+ * Cancel where it can go back) in its footer — an AJAX call, never a form submit.
  */
 export function screenFromSpec(spec, controls = CONTROLS) {
   if (!spec || typeof spec !== 'object') throw new Error('screenFromSpec: spec must be an object')
@@ -134,14 +142,19 @@ export function screenFromSpec(spec, controls = CONTROLS) {
     const at = `spec.fields[${i}]`
     if (!field || typeof field !== 'object') throw new Error(`screenFromSpec: ${at} must be an object`)
     unknownKeys(field, FIELD_KEYS, at)
-    const type = field.type || 'text'
-    if (!controls[type]) throw new Error(`screenFromSpec: ${at}.type "${type}" is not a control — one of: ${Object.keys(controls).join(', ')}`)
+    // A ready-made field: named (type or preset), or recognised from a label
+    // that says nothing else about itself.
+    const bare = !field.type && !field.preset && !field.options && !field.table && !field.data
+    const preset = presetFor(field.preset) || presetFor(field.type) || (bare ? suggestPreset(field.label) : null)
+    if (field.preset && !presetFor(field.preset)) throw new Error(`screenFromSpec: ${at}.preset "${field.preset}" is not a ready-made field`)
+    const type = preset ? preset.control : (field.type || 'text')
+    if (!controls[type]) throw new Error(`screenFromSpec: ${at}.type "${type}" is not a control or a ready-made field — controls: ${Object.keys(controls).join(', ')}`)
     if (field.width !== undefined && field.width !== 'half' && field.width !== 'full') throw new Error(`screenFromSpec: ${at}.width must be "half" or "full"`)
     if (field.step !== undefined) {
       if (!stepper) throw new Error(`screenFromSpec: ${at}.step needs a stepper before it — { "type": "stepper", "steps": [...] }`)
       openStep(field.step)
     }
-    place(type, propsFromField(type, field, at), field.width)
+    place(type, preset ? withPreset(preset, propsFromField(type, { ...field, type }, at, true), field) : propsFromField(type, field, at), field.width)
   })
 
   if (col > 0) { y += rowH + ROW_GAP; col = 0; rowH = 0 }
@@ -157,7 +170,17 @@ export function screenFromSpec(spec, controls = CONTROLS) {
   return assertValidDocument(doc, controls)
 }
 
-function propsFromField(type, field, at) {
+/** A preset's props under what the field itself gave. */
+function withPreset(preset, own, field) {
+  const base = presetProps(preset)
+  const out = { ...base, ...own }
+  // Rules merge key by key: { label: 'Age', validation: { max: 120 } } keeps min and integer.
+  if (base.validation || own.validation) out.validation = { ...(base.validation || {}), ...(own.validation || {}) }
+  if (!field.label) out.label = base.label
+  return out
+}
+
+function propsFromField(type, field, at, fromPreset) {
   if (type === 'stepper') {
     const steps = field.steps
     if (!Array.isArray(steps) || steps.length < 2) throw new Error(`screenFromSpec: ${at} is a stepper — give it steps: ["Connect", "Transform", …]`)
@@ -175,13 +198,15 @@ function propsFromField(type, field, at) {
     if (field.style) props.style = field.style
     return props
   }
-  if (!field.label) throw new Error(`screenFromSpec: ${at}.label is required`)
-  const props = { label: field.label }
+  if (!field.label && !fromPreset) throw new Error(`screenFromSpec: ${at}.label is required`)
+  const props = field.label ? { label: field.label } : {}
   ;['name', 'required', 'placeholder', 'default', 'validation', 'style'].forEach((k) => {
     if (field[k] !== undefined) props[k] = field[k]
   })
-  if (type === 'dropdown' && props.placeholder === undefined) props.placeholder = 'Select…'
-  if (CHOICE_TYPES.includes(type)) {
+  if (type === 'dropdown' && props.placeholder === undefined && !fromPreset) props.placeholder = 'Select…'
+  if (CHOICE_TYPES.includes(type) && fromPreset && !field.options && !field.table && !field.data) {
+    if (field.layout !== undefined && type !== 'dropdown') props.layout = field.layout
+  } else if (CHOICE_TYPES.includes(type)) {
     props.data = dataFromField(field, at, type)
     if (field.layout !== undefined && type !== 'dropdown') props.layout = field.layout
     // A field reading another table stores that row's id: name the column

package/src/hooks.js

@@ -40,7 +40,7 @@ export class FactoryHooks {
   }
 
   /**
-   * Save — called on every autosave, so keep it quick and safe to repeat.
+   * Save — called when the person presses Save (or a flow's Next with unsaved changes).
    * @param values  what the form holds
    * @param ctx.steps  switch steps off or on as the record decides them —
    *        ctx.steps.disable('approval'), ctx.steps.enable()

package/src/index.js

@@ -10,12 +10,16 @@ export * from './model.js'
 
 // Controllers
 export { useFactoryBuilder } from './useFactoryBuilder.js'
-export { useFactoryScreen, normaliseOptions, AUTOSAVE_DELAY } from './useFactoryScreen.js'
+export { useFactoryScreen, normaliseOptions } from './useFactoryScreen.js'
+// This app's screens, shaped for another package's designer — see
+// useScreenSource.js. Two props instead of a page of glue per application.
+export { useScreenSource } from './useScreenSource.js'
+export { describeScreen, screenStub, loadScreens, keyFromName, editScreenOf } from './screenSource.js'
 export { useFlowRun } from './useFlowRun.js'
 export { useFlowBuilder, FLOW_AUTOSAVE_DELAY } from './useFlowBuilder.js'
 
 // Designs
-export { BuilderSample, ScreenSample, ListView, ScreenModal, FlowRunnerSample, FlowBuilderSample, ControlView, VIEWS, Palette, DRAG_TYPE, PropertyPanel, EDITORS } from './designs/index.js'
+export { BuilderSample, ScreenSample, ListView, ScreenModal, FlowRunnerSample, FlowBuilderSample, ScreenEditorSample, ControlView, VIEWS, Palette, DRAG_TYPE, PropertyPanel, EDITORS } from './designs/index.js'
 
 // Front-end hooks — extend FactoryHooks, override what you need, call super
 export { FactoryHooks } from './hooks.js'

package/src/model.js

@@ -19,8 +19,9 @@ export { createFactoryApi } from './remote.js'
 export {
   STANDARD_COLUMNS, RESERVED_COLUMNS, MAX_IDENTIFIER,
   columnForField, tableForScreen, columnSql, widening, diffTables, migrationFor, nextMigrationName,
-  createStatements, addStatements, alterStatement, dropStatement, columnFromDatabase, planTableChange
+  createStatements, addStatements, alterStatement, dropStatement, columnFromDatabase, planTableChange, conversionFor
 } from './tableSchema.js'
+export { FIELD_PRESETS, PATTERNS, INPUT_TYPES, presetFor, presetProps, suggestPreset, presetGroup, presetHints, convertField } from './presets.js'
 export { createFlowsApi } from './flows.js'
 export {
   FLOW_KIND, FLOW_VERSION, FLOW_END, FLOW_OPERATORS, VALUELESS_OPERATORS,

package/src/pages.jsx

@@ -1,3 +1,4 @@
+import { useRef } from 'react'
 import { useFactoryBuilder } from './useFactoryBuilder.js'
 import { useFactoryScreen } from './useFactoryScreen.js'
 import { useFlowRun } from './useFlowRun.js'
@@ -18,6 +19,7 @@ import { BuilderSample, ScreenSample, ScreenModal, FlowRunnerSample, FlowBuilder
  * @prop lockedNames  field names that are already columns of the table — shown read-only
  * @prop screens      [{ id, name, document? }] — other screens: "Edit in" choices, and Preview's popups
  * @prop controls     control registry (default: built-ins)
+ * @prop urlKey       keep the selected control and open steps in the URL (<urlKey>Selected, <urlKey>Steps)
  */
 export function FactoryBuilder(props) {
   const ctrl = useFactoryBuilder(props)
@@ -56,9 +58,19 @@ export function FactoryBuilder(props) {
  * @prop loadScreen   async (id) → document — for screens not in `screens`
  * @prop controls     control registry (default: built-ins)
  * @prop hooks        your FactoryHooks subclass (get / save / delete / actions) — also used by the popup
+ * @prop urlKey       keep the open step of each stepper in the URL (<urlKey>Steps); never passed to the popup
  */
 export function FactoryScreen(props) {
   const ctrl = useFactoryScreen(props)
+  // Whether the popup's form holds unsaved changes — its × asks before
+  // dropping them, as its Cancel does.
+  const popupDirty = useRef(false)
+  const closePopup = () => {
+    // eslint-disable-next-line no-alert
+    if (popupDirty.current && typeof window !== 'undefined' && !window.confirm('Discard your unsaved changes?')) return
+    popupDirty.current = false
+    ctrl.closeEditor()
+  }
   return (
     <ScreenSample
       ctrl={ctrl}
@@ -68,13 +80,13 @@ export function FactoryScreen(props) {
         <ScreenModal
           title={popup.document ? popup.document.name : 'Loading…'}
           width={popup.document ? popup.document.width : undefined}
-          onClose={ctrl.closeEditor}
+          onClose={closePopup}
         >
           {popup.error && <div className="xeplr-factory-invalid" role="alert">{popup.error}</div>}
           {popup.loading && <div className="xeplr-factory-hint">Loading…</div>}
           {popup.document && (
-            // The same component, one level down: the edit screen saves itself,
-            // and every save refreshes the list behind the popup.
+            // The same component, one level down. Its Save refreshes the list
+            // behind the popup and closes it; Cancel closes it unsaved.
             <FactoryScreen
               key={`${popup.screenId}:${popup.record ? popup.record[ctrl.recordKey] : 'new'}`}
               document={popup.document}
@@ -89,6 +101,8 @@ export function FactoryScreen(props) {
               loadScreen={props.loadScreen}
               controls={props.controls}
               hooks={props.hooks}
+              onDone={() => { popupDirty.current = false; ctrl.closeEditor() }}
+              onDirtyChange={(d) => { popupDirty.current = d }}
             />
           )}
         </ScreenModal>
@@ -154,6 +168,7 @@ const EMPTY_SCREEN = {
  * @prop onSave     async (flow) → void
  * @prop onPublish  async (key) → void
  * @prop onChange   (flow) → void
+ * @prop urlKey     keep the selected step in the URL (<urlKey>Selected)
  */
 export function FlowBuilder(props) {
   const ctrl = useFlowBuilder(props)

package/src/presets.js

@@ -0,0 +1,324 @@
+// READY-MADE FIELDS — an email, a phone number, an age, a gender… — so nobody
+// has to remember that a LinkedIn profile is a URL with a particular shape, or
+// that an age is a whole number between 0 and 130.
+//
+// A preset is NOT a new kind of control. It is a named set of props for one of
+// the controls that already exist (a text box with an email keyboard and an
+// email pattern; a radio group with three options), COPIED into the field when
+// it is added or chosen. So:
+//
+//   · the document stays self-describing — the server, the CLI and Claude
+//     read the rules off the field, not out of this file;
+//   · every setting stays editable afterwards, like any other field's;
+//   · changing a preset here never changes a form already made with it.
+//
+// The field remembers where it came from in `props.preset` (the key), which is
+// what the builder's "Field type" shows. `props.preset: false` means "plain on
+// purpose" — the builder stops suggesting one.
+//
+// Pure data and functions: no React. Runs in node, like controls.js.
+
+import { CONTROLS, CHOICE_TYPES } from './controls.js'
+import { camelName, uniqueFieldName } from './document.js'
+
+// ── patterns ─────────────────────────────────────────────────────────────
+// Strings, not RegExps: they are stored in the document and checked again on
+// the server (schema-handler's `pattern`), with no flags — so any case that
+// matters is spelled out.
+export const PATTERNS = {
+  email: '^[^\\s@]+@[^\\s@]+\\.[^\\s@]{2,}$',
+  // A number people can type the way they write it: +44 20 7946 0958, (555) 010-9999.
+  phone: '^\\+?[0-9][0-9 ().\\-]{5,18}[0-9]$',
+  url: '^[Hh][Tt][Tt][Pp][Ss]?://[^\\s/]+\\.[^\\s/]+(/\\S*)?$',
+  linkedin: '^[Hh][Tt][Tt][Pp][Ss]?://([a-zA-Z]{2,3}\\.)?[Ll][Ii][Nn][Kk][Ee][Dd][Ii][Nn]\\.[Cc][Oo][Mm]/(in|company|pub)/[^\\s/?#]+/?([?#]\\S*)?$',
+  postalCode: '^[A-Za-z0-9][A-Za-z0-9 \\-]{1,8}[A-Za-z0-9]$'
+}
+
+/** How a text field's box behaves on a phone keyboard, and in autofill. */
+export const INPUT_TYPES = ['text', 'email', 'tel', 'url']
+
+// ── countries ────────────────────────────────────────────────────────────
+// Stored as the ISO 3166 code (a stable id), shown by name. The names come
+// from the runtime's own Intl data, in English, when the preset is applied —
+// and are then part of the field like any options typed by hand.
+const COUNTRY_CODES = (
+  'AF AL DZ AD AO AG AR AM AU AT AZ BS BH BD BB BY BE BZ BJ BT BO BA BW BR BN BG BF BI CV KH CM CA CF TD CL CN CO KM CG CD CR CI HR CU CY CZ ' +
+  'DK DJ DM DO EC EG SV GQ ER EE SZ ET FJ FI FR GA GM GE DE GH GR GD GT GN GW GY HT HN HK HU IS IN ID IR IQ IE IL IT JM JP JO KZ KE KI KW KG ' +
+  'LA LV LB LS LR LY LI LT LU MO MG MW MY MV ML MT MH MR MU MX FM MD MC MN ME MA MZ MM NA NR NP NL NZ NI NE NG KP MK NO OM PK PW PS PA PG PY ' +
+  'PE PH PL PT PR QA RO RU RW KN LC VC WS SM ST SA SN RS SC SL SG SK SI SB SO ZA KR SS ES LK SD SR SE CH SY TW TJ TZ TH TL TG TO TT TN TR TM ' +
+  'TV UG UA AE GB US UY UZ VU VA VE VN YE ZM ZW'
+).split(' ')
+
+function countryOptions() {
+  let names = null
+  try { names = new Intl.DisplayNames(['en'], { type: 'region' }) } catch (_) { /* old runtime: codes only */ }
+  return COUNTRY_CODES
+    .map((code) => ({ id: code, name: (names && names.of(code)) || code }))
+    .sort((a, b) => a.name.localeCompare(b.name))
+}
+
+const options = (...names) => names.map((name) => ({ id: camelName(name), name }))
+
+// ── the catalogue ────────────────────────────────────────────────────────
+// Palette order. `match` is how a LABEL is recognised ("LinkedIn URL" → the
+// LinkedIn preset) — first match wins, so the specific ones come before the
+// general ones they would also match (LinkedIn before Website).
+//
+//   key       stored in props.preset — never renamed
+//   label     the palette's name for it, and the field's starting label
+//   control   the control it is made of
+//   props     what it sets on that control (copied)
+//   size?     a starting height other than the control's own
+
+export const FIELD_PRESETS = [
+  {
+    key: 'email', label: 'Email', control: 'text',
+    match: /\be-?mail\b/i,
+    props: { inputType: 'email', placeholder: 'name@example.com', validation: { maxLength: 254, pattern: PATTERNS.email, patternMessage: 'Enter an email address, like name@example.com' } }
+  },
+  {
+    key: 'phone', label: 'Phone', control: 'text',
+    match: /\b(phone|mobile|cell|telephone|whats ?app)\b|contact (no|number)/i,
+    props: { inputType: 'tel', placeholder: '+1 555 010 9999', validation: { maxLength: 20, pattern: PATTERNS.phone, patternMessage: 'Enter a phone number — digits, spaces, + ( ) and - only' } }
+  },
+  {
+    key: 'linkedin', label: 'LinkedIn profile', control: 'text',
+    match: /linked\s*-?\s*in/i,
+    props: { inputType: 'url', placeholder: 'https://www.linkedin.com/in/…', validation: { maxLength: 300, pattern: PATTERNS.linkedin, patternMessage: 'Enter a LinkedIn profile address, like https://www.linkedin.com/in/your-name' } }
+  },
+  {
+    key: 'url', label: 'Website', control: 'text',
+    match: /\b(website|web ?site|web address|url|homepage|home page|link)\b/i,
+    props: { inputType: 'url', placeholder: 'https://example.com', validation: { maxLength: 2000, pattern: PATTERNS.url, patternMessage: 'Enter a web address starting with http:// or https://' } }
+  },
+  {
+    key: 'age', label: 'Age', control: 'number',
+    match: /^\s*age\b/i,
+    props: { validation: { min: 0, max: 130, integer: true } }
+  },
+  {
+    key: 'dateOfBirth', label: 'Date of birth', control: 'date',
+    match: /\b(date of birth|birth ?date|birthday|d\.?o\.?b)\b/i,
+    props: { validation: { notFuture: true } }
+  },
+  {
+    key: 'gender', label: 'Gender', control: 'radio',
+    match: /\b(gender|sex)\b/i,
+    props: { layout: 'horizontal', data: { source: 'static', options: options('Male', 'Female', 'Others') } },
+    size: { h: 0.08 }
+  },
+  {
+    key: 'country', label: 'Country', control: 'dropdown',
+    match: /\b(country|nationality)\b/i,
+    props: () => ({ placeholder: 'Select a country…', data: { source: 'static', options: countryOptions() } })
+  },
+  {
+    key: 'amount', label: 'Amount', control: 'number',
+    match: /\b(amount|price|salary|cost|fee|budget|revenue|income|wage)\b/i,
+    props: { placeholder: '0.00', validation: { min: 0 } }
+  },
+  {
+    key: 'percentage', label: 'Percentage', control: 'number',
+    match: /percent|%/i,
+    props: { placeholder: '0–100', validation: { min: 0, max: 100 } }
+  },
+  {
+    key: 'yesNo', label: 'Yes / No', control: 'radio',
+    // Nothing to recognise it by — "Blocked?" could be a tick box as well.
+    match: null,
+    props: { layout: 'horizontal', data: { source: 'static', options: options('Yes', 'No') } },
+    size: { h: 0.08 }
+  },
+  {
+    key: 'postalCode', label: 'Postal code', control: 'text',
+    match: /\b(postal ?code|post ?code|zip( ?code)?|pin ?code)\b/i,
+    props: { validation: { maxLength: 10, pattern: PATTERNS.postalCode, patternMessage: 'Enter a postal code — letters, digits, spaces and - only' } }
+  }
+]
+
+const BY_KEY = Object.fromEntries(FIELD_PRESETS.map((p) => [p.key, p]))
+
+/** The preset with this key, or null. Accepts "preset:<key>" too — the palette's spelling. */
+export function presetFor(key) {
+  if (typeof key !== 'string') return null
+  return BY_KEY[key.startsWith('preset:') ? key.slice(7) : key] || null
+}
+
+/** A fresh copy of what a preset puts on its control (never the shared object). */
+export function presetProps(preset) {
+  const p = typeof preset === 'string' ? presetFor(preset) : preset
+  if (!p) return {}
+  const props = typeof p.props === 'function' ? p.props() : p.props
+  return { label: p.label, ...JSON.parse(JSON.stringify(props)), preset: p.key }
+}
+
+/** The preset a label reads like, or null — "LinkedIn URL" → linkedin. */
+export function suggestPreset(label) {
+  const text = String(label || '')
+  if (!text.trim()) return null
+  return FIELD_PRESETS.find((p) => p.match && p.match.test(text)) || null
+}
+
+/** The palette's "Common fields" group — shaped like controlGroups()' groups. */
+export function presetGroup() {
+  return {
+    title: 'Common fields',
+    controls: FIELD_PRESETS.map((p) => ({ type: 'preset:' + p.key, label: p.label, icon: p.control, preset: p.key }))
+  }
+}
+
+// ── changing a field's type ──────────────────────────────────────────────
+
+/** What a dropped setting is called, for the note the builder shows. */
+const SETTING_WORDS = {
+  minLength: 'min length', maxLength: 'max length', pattern: 'the pattern', patternMessage: 'the pattern message',
+  min: 'the minimum', max: 'the maximum', integer: '"whole numbers only"', minItems: 'min choices', maxItems: 'max choices',
+  notFuture: '"not in the future"', data: 'the options', default: 'the default value', placeholder: 'the placeholder',
+  layout: 'the arrangement', accept: 'the file types', maxSize: 'the size limit', inputType: 'the keyboard type'
+}
+
+/**
+ * A field becomes another kind — another control, or a preset — keeping what
+ * still makes sense: where it is, its step, its label (unless it was only the
+ * old type's own starting label), its field name (always, once it is a column;
+ * otherwise it follows the label as a new field's does), required, and every
+ * style the new control has.
+ *
+ * @param target   a control type ('number'), or a preset key ('email' / 'preset:email')
+ * @param options.lockedNames  field names that are columns already — never renamed
+ * @returns {{ document, node, dropped: string[] }} — dropped: what did not carry
+ *          over, in words ("the pattern", "the options") for the builder to say
+ */
+export function convertField(doc, id, target, controls = CONTROLS, options = {}) {
+  const node = doc.nodes.find((n) => n.id === id)
+  if (!node) throw new Error(`No control "${id}"`)
+  const from = controls[node.type]
+  if (!from || !from.input) throw new Error(`"${id}" is not a field`)
+  const preset = presetFor(target)
+  const type = preset ? preset.control : target
+  const def = controls[type]
+  if (!def || !def.input) throw new Error(`"${target}" is not a field type or a ready-made field`)
+
+  const old = node.props || {}
+  const oldPreset = presetFor(old.preset)
+  const fresh = preset ? presetProps(preset) : {}
+  const allowed = new Set(def.props)
+  const dropped = []
+  const next = {}
+
+  // The label is the person's — unless it is only what the old type started as
+  // ("Text"), or, going from one ready-made field to another, the old one's.
+  const startingLabels = [from.defaults && from.defaults.label, preset && oldPreset && oldPreset.label].filter(Boolean)
+  const keepLabel = old.label && !startingLabels.includes(old.label)
+  next.label = keepLabel ? old.label : (fresh.label || (def.defaults && def.defaults.label) || old.label)
+
+  if (old.required !== undefined) next.required = old.required
+
+  // Validation: a preset's rules replace the old ones; a plain type keeps the
+  // rules it also has.
+  const oldRules = old.validation || {}
+  const rules = {}
+  if (preset) Object.assign(rules, fresh.validation || {})
+  else Object.keys(oldRules).forEach((k) => { if (def.validation.includes(k)) rules[k] = oldRules[k] })
+  // Said out loud: every rule that did not carry over — except, going to
+  // another ready-made field, the old one's own (replaced, as expected).
+  Object.keys(oldRules).forEach((k) => {
+    if (sameValue(rules[k], oldRules[k])) return
+    if (preset && oldPreset && sameValue(oldRules[k], presetRule(oldPreset, k))) return
+    if (k === 'patternMessage' && rules.pattern === undefined && oldRules.pattern !== undefined) return   // said with the pattern
+    dropped.push(SETTING_WORDS[k] || k)
+  })
+  if (Object.keys(rules).length) next.validation = rules
+
+  // Placeholder: the preset's, unless the person wrote their own.
+  const startingPlaceholders = [from.defaults && from.defaults.placeholder, oldPreset && presetProps(oldPreset).placeholder].filter(Boolean)
+  const theirPlaceholder = old.placeholder && !startingPlaceholders.includes(old.placeholder) ? old.placeholder : null
+  if (allowed.has('placeholder')) {
+    const value = theirPlaceholder || fresh.placeholder || (def.defaults && def.defaults.placeholder)
+    if (value) next.placeholder = value
+  } else if (theirPlaceholder) dropped.push(SETTING_WORDS.placeholder)
+
+  // Options: a preset's, else the old ones if both are choice fields, else the
+  // new type's empty start.
+  if (CHOICE_TYPES.includes(type)) {
+    next.data = fresh.data || (CHOICE_TYPES.includes(node.type) && old.data) || JSON.parse(JSON.stringify(def.defaults.data))
+    if (allowed.has('layout')) next.layout = fresh.layout || old.layout || def.defaults.layout
+  } else if (old.data && ((old.data.options || []).length || old.data.source === 'table')) dropped.push(SETTING_WORDS.data)
+
+  if (fresh.inputType && allowed.has('inputType')) next.inputType = fresh.inputType
+  ;['accept', 'maxSize'].forEach((k) => {
+    if (old[k] === undefined) return
+    if (allowed.has(k)) next[k] = old[k]; else dropped.push(SETTING_WORDS[k])
+  })
+  // A default is a value of the OLD kind; it carries only to the same control.
+  if (old.default !== undefined) {
+    if (type === node.type) next.default = old.default; else dropped.push(SETTING_WORDS.default)
+  }
+  // Anything else the new control starts with (a checkbox's defaults, say).
+  Object.keys(def.defaults || {}).forEach((k) => {
+    if (next[k] === undefined && k !== 'label' && allowed.has(k)) next[k] = JSON.parse(JSON.stringify(def.defaults[k]))
+  })
+
+  if (old.style) {
+    const style = {}
+    Object.keys(old.style).forEach((k) => { if ((def.styles || []).includes(k)) style[k] = old.style[k] })
+    if (Object.keys(style).length) next.style = style
+  }
+
+  if (preset) next.preset = preset.key
+  else if (old.preset === false) next.preset = false
+
+  // The name: fixed once it is a column; otherwise it follows the label, as a
+  // new field's does, when it was only ever the generated one.
+  const locked = new Set(options.lockedNames || [])
+  const others = { ...doc, nodes: doc.nodes.filter((n) => n.id !== id) }
+  const generated = !old.name || locked.has(old.name) ? false : isGeneratedName(old, from, oldPreset)
+  next.name = !old.name ? uniqueFieldName(others, camelName(next.label) || type)
+    : generated ? uniqueFieldName(others, camelName(next.label) || type)
+    : old.name
+
+  const converted = { ...node, type, props: next }
+  return {
+    document: { ...doc, nodes: doc.nodes.map((n) => (n.id === id ? converted : n)) },
+    node: converted,
+    dropped: [...new Set(dropped)]
+  }
+}
+
+function presetRule(preset, key) {
+  const v = presetProps(preset).validation
+  return v ? v[key] : undefined
+}
+
+function sameValue(a, b) {
+  return JSON.stringify(a) === JSON.stringify(b)
+}
+
+function isGeneratedName(props, def, preset) {
+  const stem = String(props.name).replace(/\d+$/, '')
+  return stem === camelName(props.label) || stem === camelName(def.defaults && def.defaults.label) || Boolean(preset && stem === camelName(preset.label))
+}
+
+// ── suggestions ──────────────────────────────────────────────────────────
+
+/**
+ * Fields whose label reads like a ready-made field they are not — "LinkedIn
+ * URL" as a plain text box. Suggestions, never errors: they do not stop a save
+ * or a publish. A field set to `preset: false` is plain on purpose and skipped.
+ *
+ * @returns {[{ nodeId, preset, message }]}
+ */
+export function presetHints(doc, controls = CONTROLS) {
+  const out = []
+  ;(doc.nodes || []).forEach((node) => {
+    const def = controls[node.type]
+    if (!def || !def.input) return
+    const p = node.props || {}
+    if (p.preset === false || p.preset) return
+    const s = suggestPreset(p.label)
+    if (!s) return
+    out.push({ nodeId: node.id, preset: s.key, message: `"${p.label}" could be the ready-made ${s.label} field, which checks the format for you` })
+  })
+  return out
+}
+

package/src/remote.js

@@ -71,6 +71,9 @@ export function createFactoryApi({ fetch: doFetch, base = '' } = {}) {
     const extra = (json && json.dataArray && json.dataArray[0]) || {}
     // Publish: columns it would drop, waiting for a yes — and what it keeps.
     err.confirm = extra.confirm
+    // …columns changing kind, waiting for a yes; and ones whose values will not fit.
+    err.convert = extra.convert
+    err.wontFit = extra.wontFit
     err.keep = extra.keep
     err.refused = extra.refused
     if (extra.statements) err.detail = extra.statements.join('\n')
@@ -87,7 +90,10 @@ export function createFactoryApi({ fetch: doFetch, base = '' } = {}) {
     saveDraft: (doc) => call('PUT', `/screens/${enc(doc.id)}/draft`, { document: doc }),
     // Changes the screen's table directly. Rejects with err.confirm = [{ column, records }]
     // when a removed field would drop a column; call again with { confirmDrop: [names] }.
-    publish: async (doc, options) => one(await call('POST', `/screens/${enc(doc.id)}/publish`, { confirmDrop: (options && options.confirmDrop) || [] })),
+    publish: async (doc, options) => one(await call('POST', `/screens/${enc(doc.id)}/publish`, {
+      confirmDrop: (options && options.confirmDrop) || [],
+      confirmConvert: (options && options.confirmConvert) || []
+    })),
     listTables: () => call('GET', '/tables'),
     // A new form from its name: { entity, plural? } → { entity, name, source, edit, list } — both screens as drafts.
     createEntity: async (spec) => one(await call('POST', '/entities', spec)),

package/src/scaffold.js

@@ -144,7 +144,7 @@ function editPage(n, editJson, edit) {
   return `import { FactoryScreen, FactoryHooks } from '@xeplr/ui-factory'
 import editScreen from './${editJson}'
 
-// ${edit.name} — saves itself as it is filled in; there is no submit.
+// ${edit.name} — Save sends it over AJAX (one call; never a form submit).
 // Opened in a popup from ${n.listComponent}, or on its own page:
 //   <${n.editComponent} api={api} />                 a new ${n.singular}
 //   <${n.editComponent} api={api} record={row} />    an existing one
@@ -166,7 +166,7 @@ export class ${n.hooksClass} extends FactoryHooks {
     return super.get(ctx)
   }
 
-  /** Every autosave — keep it quick. Returns the saved record. */
+  /** The Save button. Returns the saved record. */
   save(values, ctx) {
     return super.save(values, ctx)
   }