@xeplr/ui-factory 1.0.1 → 1.0.2

package/src/designs/styles.js

@@ -0,0 +1,59 @@
+// A control's `props.style` → CSS.
+//
+// Sizes are PIXELS at the screen's design width. `--xf-u` is one such pixel: a
+// real pixel at the design width or wider, less on a narrower screen (see
+// factory.css). So text stays exactly the size somebody chose, and only ever
+// shrinks to keep the layout's proportions.
+
+const u = (n) => `calc(${n} * var(--xf-u))`
+
+/** Wrapper-level: the font the whole control uses. */
+export function fieldStyle(style) {
+  const s = style || {}
+  return clean({ fontFamily: s.fontFamily })
+}
+
+/** The label above an input. */
+export function labelStyle(style) {
+  const s = style || {}
+  return clean({
+    fontSize: s.labelFontSize != null ? u(s.labelFontSize) : undefined,
+    fontWeight: s.labelFontWeight,
+    color: s.labelColor
+  })
+}
+
+/** The input box itself, or a label control's text block. */
+export function boxStyle(style) {
+  const s = style || {}
+  return clean({
+    fontSize: s.fontSize != null ? u(s.fontSize) : undefined,
+    fontWeight: s.fontWeight,
+    fontStyle: s.fontStyle,
+    textAlign: s.textAlign,
+    color: s.color,
+    background: s.background,
+    borderColor: s.borderColor,
+    borderWidth: s.borderWidth != null ? `${s.borderWidth}px` : undefined,
+    borderStyle: s.borderWidth != null ? 'solid' : undefined,
+    borderRadius: s.borderRadius != null ? u(s.borderRadius) : undefined
+  })
+}
+
+/** The screen's defaults, on its container: what every control inherits. */
+export function screenStyle(doc) {
+  const s = doc.style || {}
+  return clean({
+    '--xf-width': doc.width,
+    '--xf-font': s.fontSize,
+    fontFamily: s.fontFamily,
+    color: s.color,
+    background: s.background
+  })
+}
+
+function clean(obj) {
+  const out = {}
+  Object.keys(obj).forEach((k) => { if (obj[k] !== undefined && obj[k] !== null && obj[k] !== '') out[k] = obj[k] })
+  return out
+}

package/src/document.js

@@ -5,7 +5,10 @@
 //   {
 //     kind: 'xeplr-screen', version: 1,
 //     id: 'new_employee', name: 'New employee',
+//     source?: 'employees',          ← the table records are saved to (the app's)
 //     units: 'fraction', aspect: 1,
+//     width: 800,                    ← design width in px: styles are px at this width
+//     style?: { fontFamily, fontSize, color, background },   ← screen-wide defaults
 //     nodes: [ { id, type, x, y, w, h, z?, groupId?, props } ]
 //   }
 //
@@ -22,29 +25,44 @@ import { getAtPath, setAtPath } from './propertyPath.js'
 export const DOCUMENT_KIND = 'xeplr-screen'
 export const DOCUMENT_VERSION = 1
 export const DEFAULT_ASPECT = 1
+/** Px. Styles are sizes at this width; narrower shrinks them, wider never grows them. */
+export const DEFAULT_WIDTH = 800
 
 /** Space kept around and between controls, as fractions. */
 export const MARGIN = 0.04
 export const GAP = 0.025
 
 /** A new, empty screen. */
-export function createScreen({ name, id, aspect } = {}) {
+export function createScreen({ name, id, aspect, width, source, style } = {}) {
   const title = String(name || 'Untitled screen').trim() || 'Untitled screen'
-  return {
+  const doc = {
     kind: DOCUMENT_KIND,
     version: DOCUMENT_VERSION,
     id: id || slugify(title, '_') || 'screen',
     name: title,
     units: 'fraction',
     aspect: aspect > 0 ? aspect : DEFAULT_ASPECT,
+    width: width > 0 ? width : DEFAULT_WIDTH,
     nodes: []
   }
+  if (source) doc.source = source
+  if (style && Object.keys(style).length) doc.style = style
+  return doc
 }
 
 export function renameScreen(doc, name) {
   return { ...doc, name: String(name == null ? '' : name) }
 }
 
+/**
+ * Sets a SCREEN property by path — `source`, `width`, `style.fontSize`. A blank
+ * value removes the key, like a control's properties.
+ */
+export function setScreenProperty(doc, path, value) {
+  if (path === 'nodes' || path.startsWith('nodes.')) throw new Error('setScreenProperty cannot change nodes')
+  return setAtPath(doc, path, value)
+}
+
 /**
  * Adds a control of `type`. Placed at `at` ({ x, y } — the drop point, as the
  * control's top-left) or, without one, below everything already on the screen.
@@ -87,10 +105,19 @@ export function moveNode(doc, id, patch) {
  * name is still the one made for it: a dropdown dropped as "Dropdown" and
  * relabelled "Location" should save as `location`, not `dropdown`. A name
  * someone typed is theirs, and is left alone.
+ *
+ * A LOCKED name — one that is already a column of the table — never changes:
+ * not by typing, and not by following the label. Renaming it would start a new
+ * empty column and strand the saved data in the old one.
+ *
+ * @param options.lockedNames  field names that are columns already
  */
-export function setNodeProperty(doc, id, path, value, controls = CONTROLS) {
+export function setNodeProperty(doc, id, path, value, controls = CONTROLS, options = {}) {
   const node = doc.nodes.find((n) => n.id === id)
-  const followLabel = path === 'props.label' && node && controls[node.type]?.input && isAutoName(node, controls)
+  const locked = options.lockedNames ? new Set(options.lockedNames) : null
+  const isLocked = Boolean(node && locked && locked.has(node.props?.name))
+  if (path === 'props.name' && isLocked) return doc
+  const followLabel = path === 'props.label' && node && !isLocked && controls[node.type]?.input && isAutoName(node, controls)
   let next = mapNode(doc, id, (n) => {
     const updated = setAtPath(n, path, value)
     // setAtPath prunes an emptied object; `props` itself must always exist.

package/src/generate.js

@@ -24,15 +24,15 @@
 // there it is edited like any other.
 
 import { CONTROLS } from './controls.js'
-import { createScreen, addControl, MARGIN, GAP, slugify } from './document.js'
+import { createScreen, addControl, MARGIN, GAP, slugify, camelName } from './document.js'
 import { assertValidDocument } from './validateDocument.js'
 
 /** Heights by control, as page fractions (a page is as tall as it is wide). */
 export const SPEC_HEIGHTS = {
   text: 0.08, number: 0.08, date: 0.08, dropdown: 0.08,
   textarea: 0.18,
-  checkbox: 0.06,
-  button: 0.07,
+  checkbox: 0.05,
+  list: 0.42,
   label: { heading: 0.07, subheading: 0.055, text: 0.045 }
 }
 
@@ -42,8 +42,9 @@ export const SPEC_HEIGHTS = {
  */
 export const ROW_GAP = 0.04
 
-const FIELD_KEYS = ['type', 'label', 'name', 'required', 'placeholder', 'default', 'validation', 'data', 'options', 'table', 'width', 'text', 'variant']
-const SPEC_KEYS = ['name', 'id', 'columns', 'heading', 'fields', 'submit', 'reset', 'aspect']
+const FIELD_KEYS = ['type', 'label', 'name', 'required', 'placeholder', 'default', 'validation', 'data', 'options', 'table', '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']
 
 /**
  * @param spec
@@ -55,8 +56,13 @@ const SPEC_KEYS = ['name', 'id', 'columns', 'heading', 'fields', 'submit', 'rese
  *             default?, validation?, width?: 'half'|'full' }
  *             dropdown: options: ['Full time', …] or [{ id, name }]  —or—  table: 'departments'
  *             section heading: { type: 'label', text, variant?: 'subheading' }
- *   submit?   button label (default 'Save'); false for no submit button
- *   reset?    reset button label; omitted/false for none
+ *   source?   the table records are saved to, e.g. 'employees'
+ *   width?    design width in px (default 800) — style sizes are px at this width
+ *   style?    screen-wide defaults: { fontFamily, fontSize, color, background }
+ *   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.
  */
 export function screenFromSpec(spec, controls = CONTROLS) {
   if (!spec || typeof spec !== 'object') throw new Error('screenFromSpec: spec must be an object')
@@ -66,7 +72,7 @@ export function screenFromSpec(spec, controls = CONTROLS) {
   const columns = spec.columns === undefined ? 2 : spec.columns
   if (columns !== 1 && columns !== 2) throw new Error('screenFromSpec: spec.columns must be 1 or 2')
 
-  let doc = createScreen({ name: spec.name, id: spec.id, aspect: spec.aspect })
+  let doc = createScreen({ name: spec.name, id: spec.id, aspect: spec.aspect, width: spec.width, source: spec.source, style: spec.style })
   const full = 1 - 2 * MARGIN
   const colW = round((full - (columns - 1) * GAP) / columns)
   let y = MARGIN
@@ -75,7 +81,7 @@ export function screenFromSpec(spec, controls = CONTROLS) {
 
   const place = (type, props, width) => {
     const h = heightOf(type, props)
-    const isFull = width === 'full' || columns === 1 || type === 'textarea' || type === 'label'
+    const isFull = width === 'full' || columns === 1 || type === 'textarea' || type === 'label' || type === 'list'
     if (isFull) {
       if (col > 0) { y += rowH + ROW_GAP; col = 0; rowH = 0 }
       ;({ document: doc } = addControl(doc, type, { at: { x: MARGIN, y: round(y) }, size: { w: round(full), h }, props }, controls))
@@ -105,34 +111,35 @@ export function screenFromSpec(spec, controls = CONTROLS) {
 
   if (col > 0) { y += rowH + ROW_GAP; col = 0; rowH = 0 }
 
-  // One row of buttons, left-aligned. Narrow on purpose: a full-width Save
-  // reads as a banner, not a button.
-  const buttons = []
-  if (spec.submit !== false) buttons.push({ label: typeof spec.submit === 'string' ? spec.submit : 'Save', action: 'submit' })
-  if (spec.reset) buttons.push({ label: typeof spec.reset === 'string' ? spec.reset : 'Reset', action: 'reset' })
-  const buttonW = 0.18
-  buttons.forEach((props, i) => {
-    const at = { x: round(MARGIN + i * (buttonW + GAP)), y: round(y) }
-    ;({ document: doc } = addControl(doc, 'button', { at, size: { w: buttonW, h: SPEC_HEIGHTS.button }, props }, controls))
-  })
+  if (spec.list) {
+    const list = spec.list === true ? {} : spec.list
+    if (typeof list !== 'object') throw new Error('screenFromSpec: spec.list must be true or an object')
+    unknownKeys(list, LIST_KEYS, 'spec.list')
+    const props = { title: 'Saved records', pageSize: 10, actions: ['new', 'edit', 'delete'], ...list }
+    place('list', props, 'full')
+  }
 
   return assertValidDocument(doc, controls)
 }
 
 function propsFromField(type, field, at) {
   if (type === 'label') {
-    return { text: field.text ?? field.label ?? '', variant: field.variant || 'subheading' }
-  }
-  if (type === 'button') {
-    return { label: field.label || 'Save', action: 'submit' }
+    const props = { text: field.text ?? field.label ?? '', variant: field.variant || 'subheading' }
+    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 }
-  ;['name', 'required', 'placeholder', 'default', 'validation'].forEach((k) => {
+  ;['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 (type === 'dropdown') props.data = dataFromField(field, at)
+  if (type === 'dropdown') {
+    props.data = dataFromField(field, at)
+    // A dropdown reading another table stores that row's id: name the column
+    // for what it holds — "Department" → departmentId, a foreign key.
+    if (props.data.source === 'table' && props.name === undefined) props.name = camelName(field.label) + 'Id'
+  }
   else if (field.options || field.table || field.data) throw new Error(`screenFromSpec: ${at} — options/table/data only apply to a dropdown`)
   return props
 }
@@ -165,3 +172,107 @@ function unknownKeys(obj, allowed, at) {
 function round(v) {
   return Math.round(v * 10000) / 10000
 }
+
+// ── an entity: a LIST screen and an EDIT screen ──────────────────────────
+//
+// "Create a form for employees" is two screens, not one:
+//
+//   employee_list  — the saved employees, in a list; Edit and New open…
+//   employee_edit  — …the add / edit form, in a popup (or on its own page)
+//
+// The list names the edit screen (`editScreen`), which is the only link
+// between them; both save to and read from the same table.
+
+const ENTITY_KEYS = ['entity', 'plural', 'source', 'fields', 'columns', 'listColumns', 'pageSize', 'actions', 'width', 'style', 'aspect']
+
+/**
+ * @param spec
+ *   entity       singular name, e.g. "employee" (required)
+ *   plural?      e.g. "employees" (default: entity + "s")
+ *   source?      table records are saved in (default: plural, snake_cased)
+ *   fields       the edit form's fields — exactly as screenFromSpec
+ *   columns?     1 or 2 — the edit form's layout (default 2)
+ *   listColumns? [{ field, label }] or ["firstName", …] — the list's columns
+ *                (default: up to the first 5 fields)
+ *   pageSize?, actions?, width?, style?
+ * @returns {{ list, edit }} two checked screen documents
+ */
+export function screensFromSpec(spec, controls = CONTROLS) {
+  if (!spec || typeof spec !== 'object') throw new Error('screensFromSpec: spec must be an object')
+  unknownKeys(spec, ENTITY_KEYS, 'spec')
+  if (!spec.entity || typeof spec.entity !== 'string') throw new Error('screensFromSpec: spec.entity is required, e.g. "employee"')
+  const names = entityNames(spec.entity, spec.plural)
+  const source = spec.source || names.table
+
+  const edit = screenFromSpec({
+    name: `Add / edit ${names.singular}`,
+    id: `${names.key}_edit`,
+    source,
+    columns: spec.columns,
+    fields: spec.fields,
+    width: spec.width,
+    style: spec.style,
+    aspect: spec.aspect
+  }, controls)
+
+  const fieldNodes = edit.nodes.filter((n) => controls[n.type]?.input)
+  const byName = Object.fromEntries(fieldNodes.map((n) => [n.props.name, n]))
+  let listColumns
+  if (Array.isArray(spec.listColumns) && spec.listColumns.length) {
+    listColumns = spec.listColumns.map((c, i) => {
+      const field = typeof c === 'string' ? c : c && c.field
+      if (!byName[field]) throw new Error(`screensFromSpec: spec.listColumns[${i}] "${field}" is not a field of the edit form — one of: ${Object.keys(byName).join(', ')}`)
+      return { field, label: (typeof c === 'object' && c.label) || byName[field].props.label }
+    })
+  } else {
+    listColumns = fieldNodes.slice(0, 5).map((n) => ({ field: n.props.name, label: n.props.label }))
+  }
+
+  let list = createScreen({ name: names.pluralTitle, id: `${names.key}_list`, source, width: spec.width, style: spec.style, aspect: spec.aspect })
+  ;({ document: list } = addControl(list, 'list', {
+    at: { x: MARGIN, y: MARGIN },
+    size: { w: round(1 - 2 * MARGIN), h: 0.8 },
+    props: {
+      title: names.pluralTitle,
+      editScreen: edit.id,
+      columns: listColumns,
+      pageSize: spec.pageSize || 10,
+      actions: spec.actions || ['new', 'edit', 'delete']
+    }
+  }, controls))
+
+  return { list: assertValidDocument(list, controls), edit }
+}
+
+/**
+ * "employee" → the names the pair uses everywhere, so the ids, files, table and
+ * components always agree.
+ */
+export function entityNames(entity, plural) {
+  const words = String(entity).trim().replace(/[^A-Za-z0-9]+/g, ' ').trim().split(/\s+/).filter(Boolean)
+  if (!words.length) throw new Error('entity must contain letters or digits')
+  const pluralWords = plural
+    ? String(plural).trim().replace(/[^A-Za-z0-9]+/g, ' ').trim().split(/\s+/).filter(Boolean)
+    : [...words.slice(0, -1), pluralise(words[words.length - 1])]
+  const lower = (ws) => ws.map((w) => w.toLowerCase())
+  const pascal = (ws) => ws.map((w) => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase()).join('')
+  return {
+    singular: lower(words).join(' '),                     // "employee"
+    pluralTitle: capitalise(lower(pluralWords).join(' ')), // "Employees"
+    key: lower(words).join('_'),                          // "employee"  → ids employee_list / employee_edit
+    file: lower(words).join('-'),                         // "employee"  → employee-list.screen.json
+    table: lower(pluralWords).join('_'),                  // "employees"
+    listComponent: `${pascal(words)}List`,                // "EmployeeList"
+    editComponent: `Edit${pascal(words)}`                 // "EditEmployee"
+  }
+}
+
+function pluralise(word) {
+  if (/[^aeiou]y$/i.test(word)) return word.slice(0, -1) + 'ies'
+  if (/(s|x|z|ch|sh)$/i.test(word)) return word + 'es'
+  return word + 's'
+}
+
+function capitalise(s) {
+  return s.charAt(0).toUpperCase() + s.slice(1)
+}

package/src/index.js

@@ -10,10 +10,10 @@ export * from './model.js'
 
 // Controllers
 export { useFactoryBuilder } from './useFactoryBuilder.js'
-export { useFactoryScreen, normaliseOptions } from './useFactoryScreen.js'
+export { useFactoryScreen, normaliseOptions, AUTOSAVE_DELAY } from './useFactoryScreen.js'
 
 // Designs
-export { BuilderSample, ScreenSample, ControlView, VIEWS, Palette, DRAG_TYPE, PropertyPanel, EDITORS } from './designs/index.js'
+export { BuilderSample, ScreenSample, ListView, ScreenModal, ControlView, VIEWS, Palette, DRAG_TYPE, PropertyPanel, EDITORS } from './designs/index.js'
 
 // Ready-made
 export { FactoryBuilder, FactoryScreen } from './pages.jsx'

package/src/model.js

@@ -3,13 +3,19 @@
 //
 //   import { screenFromSpec, validateDocument, formSchema } from '@xeplr/ui-factory/model'
 
-export { CONTROLS, OPTION_ID, OPTION_LABEL, LABEL_VARIANTS, BUTTON_ACTIONS, controlGroups, withControls } from './controls.js'
+export { CONTROLS, OPTION_ID, OPTION_LABEL, LABEL_VARIANTS, LABEL_PRESETS, LIST_ACTIONS, STYLE_KEYS, SCREEN_STYLE_KEYS, FONT_FAMILIES, controlGroups, withControls } from './controls.js'
 export {
-  DOCUMENT_KIND, DOCUMENT_VERSION, DEFAULT_ASPECT, MARGIN, GAP,
-  createScreen, renameScreen, addControl, moveNode, setNodeProperty, getNodeProperty, removeNodes,
+  DOCUMENT_KIND, DOCUMENT_VERSION, DEFAULT_ASPECT, DEFAULT_WIDTH, MARGIN, GAP,
+  createScreen, renameScreen, setScreenProperty, addControl, moveNode, setNodeProperty, getNodeProperty, removeNodes,
   inputNodes, readingOrder, contentBottom, camelName, slugify, uniqueFieldName, nextPosition
 } from './document.js'
 export { validateDocument, assertValidDocument } from './validateDocument.js'
-export { formSchema, initialValues, parseInput, validateValues, fieldError, sameId, optionValue } from './values.js'
-export { screenFromSpec, SPEC_HEIGHTS, ROW_GAP } from './generate.js'
+export { formSchema, initialValues, parseInput, validateValues, fieldError, sameId, optionValue, saveState, recordValues, displayValue, listColumns, listSource } from './values.js'
+export { screenFromSpec, screensFromSpec, entityNames, SPEC_HEIGHTS, ROW_GAP } from './generate.js'
+export { scaffoldEntity } from './scaffold.js'
 export { getAtPath, setAtPath } from './propertyPath.js'
+export { createFactoryApi } from './remote.js'
+export {
+  STANDARD_COLUMNS, RESERVED_COLUMNS, MAX_IDENTIFIER,
+  columnForField, tableForScreen, columnSql, widening, diffTables, migrationFor, nextMigrationName
+} from './tableSchema.js'

package/src/pages.jsx

@@ -1,16 +1,20 @@
 import { useFactoryBuilder } from './useFactoryBuilder.js'
 import { useFactoryScreen } from './useFactoryScreen.js'
-import { BuilderSample, ScreenSample } from './designs/index.js'
+import { BuilderSample, ScreenSample, ScreenModal } from './designs/index.js'
 
 /**
- * The builder, ready-made.
+ * The builder, ready-made. Saves itself — there is no Save button.
  *
  * @prop document     the screen to edit (omit for a new one)
  * @prop name         name for a new screen
- * @prop onSave       async (document) → void — the app stores it; only called with a valid document
+ * @prop onSave       async (document) → void — called automatically after edits, only with a valid document
  * @prop onChange     (document) → void — every edit
- * @prop listTables   async () → [{ id, name }] | string[] — for "dropdown from a table"
- * @prop fetchOptions async ({ table }) → [{ id, name }] — enables Preview with real options
+ * @prop onPublish    async (document) → { version } — shows a Publish button; throw to refuse, with `detail` to show (e.g. the migration to run)
+ * @prop listTables   async () → [{ id, name }] | string[] — for "Saves to", lists and table dropdowns
+ * @prop fetchOptions async ({ table }) → [{ id, name }] — Preview with real options
+ * @prop fetchRecords async ({ source }) → records — Preview with real records
+ * @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)
  */
 export function FactoryBuilder(props) {
@@ -21,22 +25,68 @@ export function FactoryBuilder(props) {
       className={props.className}
       style={props.style}
       renderPreview={(doc) => (
-        <FactoryScreen document={doc} fetchOptions={props.fetchOptions} controls={props.controls} />
+        // Preview never writes: onSave/onDelete are left out on purpose.
+        <FactoryScreen
+          document={doc}
+          fetchOptions={props.fetchOptions}
+          fetchRecords={props.fetchRecords}
+          screens={Object.fromEntries((props.screens || []).filter((s) => s.document).map((s) => [s.id, s.document]))}
+          controls={props.controls}
+        />
       )}
     />
   )
 }
 
 /**
- * A saved screen, running.
+ * A saved screen, running. Saves itself in the background — there is no submit.
  *
  * @prop document     a screen document (an invalid one renders its problems, loudly)
+ * @prop record       the record to open (omit for a new one)
+ * @prop recordKey    the id field on a record (default 'id')
+ * @prop onSave       async (values, { id, source, document }) → the saved record, with its id
  * @prop fetchOptions async ({ table }) → [{ id, name }] — rows for table dropdowns
- * @prop onSubmit     async (values, { document }) → void
- * @prop values       starting values, e.g. the record being edited
+ * @prop fetchRecords async ({ source }) → records — rows for lists
+ * @prop onDelete     async ({ id, source, record }) → void
+ * @prop onChange     (values) → void
+ * @prop screens      { id → document } — the screens a list's Edit / New open in a popup
+ * @prop loadScreen   async (id) → document — for screens not in `screens`
  * @prop controls     control registry (default: built-ins)
  */
 export function FactoryScreen(props) {
   const ctrl = useFactoryScreen(props)
-  return <ScreenSample ctrl={ctrl} className={props.className} style={props.style} />
+  return (
+    <ScreenSample
+      ctrl={ctrl}
+      className={props.className}
+      style={props.style}
+      renderPopup={(popup) => (
+        <ScreenModal
+          title={popup.document ? popup.document.name : 'Loading…'}
+          width={popup.document ? popup.document.width : undefined}
+          onClose={ctrl.closeEditor}
+        >
+          {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.
+            <FactoryScreen
+              key={`${popup.screenId}:${popup.record ? popup.record[ctrl.recordKey] : 'new'}`}
+              document={popup.document}
+              record={popup.record}
+              recordKey={props.recordKey}
+              onSave={ctrl.popupSave}
+              fetchOptions={props.fetchOptions}
+              fetchRecords={props.fetchRecords}
+              onDelete={props.onDelete}
+              screens={props.screens}
+              loadScreen={props.loadScreen}
+              controls={props.controls}
+            />
+          )}
+        </ScreenModal>
+      )}
+    />
+  )
 }

package/src/remote.js

@@ -0,0 +1,57 @@
+// The browser side of @xeplr/factory: every call FactoryScreen and
+// FactoryBuilder need, as requests to its routes. Records live in REAL tables
+// in the app's database; this only sends and receives.
+//
+//   import { authFetch } from '@xeplr/ui-account'
+//   const factory = createFactoryApi({ fetch: authFetch })
+//   <FactoryScreen document={screen} {...factory.screenProps} />
+//   <FactoryBuilder document={screen} {...factory.builderProps} lockedNames={…} />
+//
+// Responses are xeplr's { code, message, error, dataArray }.
+
+/**
+ * @param options.fetch  a fetch that adds auth and tenant headers (e.g. @xeplr/ui-account's authFetch)
+ * @param options.base   prefix before /factory, if the router is mounted elsewhere (default '')
+ */
+export function createFactoryApi({ fetch: doFetch, base = '' } = {}) {
+  if (typeof doFetch !== 'function') throw new Error('createFactoryApi: pass { fetch } — usually authFetch from @xeplr/ui-account')
+
+  async function call(method, path, body) {
+    const res = await doFetch(`${base}/factory${path}`, {
+      method,
+      headers: body === undefined ? undefined : { 'Content-Type': 'application/json' },
+      body: body === undefined ? undefined : JSON.stringify(body)
+    })
+    let json = null
+    try { json = await res.json() } catch (_) { /* not JSON — reported below */ }
+    if (!res.ok) {
+      const err = new Error((json && json.message) || `${method} ${path} failed (${res.status})`)
+      err.status = res.status
+      err.fields = json && json.error && json.error.fields
+      err.detail = json && json.dataArray && json.dataArray[0] && json.dataArray[0].migration
+      throw err
+    }
+    return json ? json.dataArray : []
+  }
+  const one = (rows) => (Array.isArray(rows) ? rows[0] : rows)
+  const enc = encodeURIComponent
+
+  const api = {
+    // screens
+    listScreens: () => call('GET', '/screens'),
+    loadScreen: async (key) => one(await call('GET', `/screens/${enc(key)}`)).document,
+    loadDraft: async (key) => one(await call('GET', `/screens/${enc(key)}?draft=true`)),
+    saveDraft: (doc) => call('PUT', `/screens/${enc(doc.id)}/draft`, { document: doc }),
+    publish: async (doc) => one(await call('POST', `/screens/${enc(doc.id)}/publish`)),
+    listTables: () => call('GET', '/tables'),
+
+    // records
+    fetchRecords: ({ screen }) => call('GET', `/records/${enc(screen)}`),
+    onSave: async (values, { id, screen }) => one(await call('POST', `/records/${enc(screen)}/save`, { id, values })),
+    onDelete: ({ id, screen }) => call('POST', `/records/${enc(screen)}/delete`, { id }),
+    fetchOptions: ({ table }) => call('GET', `/options/${enc(table)}`)
+  }
+  api.screenProps = { loadScreen: api.loadScreen, onSave: api.onSave, fetchRecords: api.fetchRecords, onDelete: api.onDelete, fetchOptions: api.fetchOptions }
+  api.builderProps = { onSave: api.saveDraft, onPublish: api.publish, listTables: api.listTables, fetchOptions: api.fetchOptions, fetchRecords: api.fetchRecords }
+  return api
+}

package/src/scaffold.js

@@ -0,0 +1,73 @@
+// THE FILES an entity becomes in an app.
+//
+// Asked for "a form for employees", Claude produces two screens and two
+// pages that show them:
+//
+//   employee-list.screen.json   EmployeeList.jsx   — the list; Edit / New open a popup
+//   employee-edit.screen.json   EditEmployee.jsx   — the add / edit form, also a page on its own
+//
+// The pages are thin on purpose: a screen document and the app's data calls,
+// nothing else. Changing what a screen shows is editing its JSON in the
+// designer, never these files.
+//
+// Pure: returns { path → contents }. Writing them is the caller's (the CLI).
+
+import { screensFromSpec, entityNames } from './generate.js'
+
+/**
+ * @param spec  as screensFromSpec
+ * @returns {{ files: Object<string, string>, names, list, edit }}
+ */
+export function scaffoldEntity(spec, controls) {
+  const { list, edit } = screensFromSpec(spec, controls)
+  const names = entityNames(spec.entity, spec.plural)
+  const listJson = `${names.file}-list.screen.json`
+  const editJson = `${names.file}-edit.screen.json`
+
+  const files = {
+    [listJson]: JSON.stringify(list, null, 2) + '\n',
+    [editJson]: JSON.stringify(edit, null, 2) + '\n',
+    [`${names.listComponent}.jsx`]: listPage(names, listJson, editJson, list, edit),
+    [`${names.editComponent}.jsx`]: editPage(names, editJson, edit)
+  }
+  return { files, names, list, edit }
+}
+
+function listPage(n, listJson, editJson, list, edit) {
+  return `import { FactoryScreen } from '@xeplr/ui-factory'
+import listScreen from './${listJson}'
+import editScreen from './${editJson}'
+
+// ${n.pluralTitle} — the saved ${list.source}, with New / Edit / Delete.
+// Edit and New open "${edit.name}" (${edit.id}) in a popup.
+//
+// \`api\` is the app's data calls — the factory never touches a database:
+//   onSave(values, { id, source })  → the saved record, with its id
+//   fetchRecords({ source })        → records
+//   onDelete({ id, source, record })
+//   fetchOptions({ table })         → [{ id, name }] for dropdowns
+export default function ${n.listComponent}({ api }) {
+  return (
+    <FactoryScreen
+      document={listScreen}
+      screens={{ [editScreen.id]: editScreen }}
+      {...api}
+    />
+  )
+}
+`
+}
+
+function editPage(n, editJson, edit) {
+  return `import { FactoryScreen } from '@xeplr/ui-factory'
+import editScreen from './${editJson}'
+
+// ${edit.name} — saves itself as it is filled in; there is no 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
+export default function ${n.editComponent}({ api, record }) {
+  return <FactoryScreen document={editScreen} record={record} {...api} />
+}
+`
+}