@xeplr/ui-factory 1.0.1 → 1.0.3

package/src/designs/ScreenSample.jsx

@@ -1,15 +1,27 @@
 import ControlView from './ControlView.jsx'
-import { contentBottom, MARGIN } from '../document.js'
+import { contentBottom, inputNodes, MARGIN } from '../document.js'
+import { screenStyle } from './styles.js'
 
 // A saved screen, drawn. Presentation only — everything comes from
 // useFactoryScreen.
 //
 // NO MEASURING. Positions are CSS: x and w as percentages of the width, y and h
 // in container-query units (cqw = 1% of the screen's width) times the aspect.
-// So the screen keeps exactly its proportions at any width, renders on the
-// server, and never flashes at the wrong size while a ResizeObserver catches up.
+// The screen is never wider than the width it was designed at, so what was
+// designed at 800px is shown at 800px, and only a narrower screen scales it.
+//
+// NO SUBMIT. The status line says what the background save is doing.
+
+const STATUS = {
+  idle: '',
+  pending: 'Unsaved changes…',
+  saving: 'Saving…',
+  saved: 'All changes saved',
+  incomplete: 'Fill in the required fields to save',
+  invalid: 'Fix the highlighted fields to save'
+}
 
-export default function ScreenSample({ ctrl, className, style }) {
+export default function ScreenSample({ ctrl, className, style, renderPopup }) {
   const { document: doc } = ctrl
 
   if (ctrl.documentErrors.length) {
@@ -25,13 +37,27 @@ export default function ScreenSample({ ctrl, className, style }) {
 
   const aspect = doc.aspect
   const pageHeight = (contentBottom(doc) + MARGIN) * aspect * 100
+  const fieldNodes = inputNodes(doc)
+  const statusText = ctrl.status === 'error' ? `Not saved — ${ctrl.saveError}` : STATUS[ctrl.status]
+  // A screen with no fields of its own (a list screen) has nothing to save.
+  const hasFields = fieldNodes.length > 0
 
   return (
-    <div className={'xeplr-factory-screen' + (className ? ' ' + className : '')} style={style}>
+    <div
+      className={'xeplr-factory-screen' + (className ? ' ' + className : '')}
+      style={{ maxWidth: doc.width, ...screenStyle(doc), ...style }}
+    >
+      {hasFields && (
+        <div className={`xeplr-factory-status xeplr-factory-status--${ctrl.status}`} role="status" aria-live="polite">
+          <span>{ctrl.recordId !== null && ctrl.recordId !== undefined ? 'Editing record' : 'New record'}</span>
+          <span>{statusText}</span>
+        </div>
+      )}
       <form
         className="xeplr-factory-page"
         style={{ height: `${pageHeight}cqw` }}
-        onSubmit={ctrl.submit}
+        // Enter in a field saves now rather than posting a page.
+        onSubmit={(e) => { e.preventDefault(); ctrl.saveNow() }}
         noValidate
         aria-label={doc.name}
       >
@@ -53,13 +79,27 @@ export default function ScreenSample({ ctrl, className, style }) {
               error={node.props?.name ? ctrl.errors[node.props.name] : undefined}
               options={node.type === 'dropdown' ? ctrl.optionsFor(node) : undefined}
               onChange={(raw) => ctrl.setValue(node, raw)}
-              onAction={(action) => { if (action === 'reset') ctrl.reset() }}
-              disabled={ctrl.submitting}
+              onBlur={() => ctrl.touch(node)}
+              list={node.type === 'list' ? {
+                doc,
+                list: ctrl.listFor(node),
+                fieldNodes: ctrl.fieldsFor(node),
+                optionsFor: ctrl.optionsFor,
+                currentId: ctrl.recordId,
+                recordKey: ctrl.recordKey,
+                canDelete: ctrl.canDelete,
+                // A list with an edit screen opens it in a popup; one on a form
+                // opens the row in the form's own fields.
+                onEdit: (rec) => (node.props.editScreen ? ctrl.openEditor(node, rec) : ctrl.openRecord(rec)),
+                // eslint-disable-next-line no-alert
+                onDelete: (rec) => ctrl.deleteRecord(node, rec).catch((err) => window.alert(err.message || 'Could not delete')),
+                onNew: () => (node.props.editScreen ? ctrl.openEditor(node, null) : ctrl.newRecord())
+              } : undefined}
             />
           </div>
         ))}
       </form>
-      {ctrl.submitError && <div className="xeplr-factory-submit-error" role="alert">{ctrl.submitError}</div>}
+      {ctrl.popup && renderPopup && renderPopup(ctrl.popup, ctrl)}
     </div>
   )
 }

package/src/designs/factory.css

@@ -2,14 +2,15 @@
    Colours come from the xeplr theme variables, each with a light fallback, so
    a host that defines none still gets a finished look.
 
-   ONE SIZE UNIT, --xf-u: one design pixel on an 800px-wide screen. It is in
-   container-query units, so text and controls scale with the screen exactly as
-   their positions do — the whole screen keeps its proportions at any width. */
+   ONE SIZE UNIT, --xf-u: one pixel at the screen's design width (--xf-width,
+   set from the document). At that width or wider it IS a pixel — text is
+   exactly the size chosen, and a screen never stretches. On a narrower screen
+   it shrinks, so the layout keeps its proportions. */
 
 .xeplr-factory-screen,
 .xeplr-factory-canvas {
   container-type: inline-size;
-  --xf-u: calc(100cqw / 800);
+  --xf-u: min(1px, calc(100cqw / var(--xf-width, 800)));
   --xf-accent: var(--xeplr-accent, #2563eb);
   --xf-ink: var(--xeplr-text, #1a1a19);
   --xf-muted: var(--xeplr-muted, #6b6a63);
@@ -20,6 +21,12 @@
 
 /* ── the screen ─────────────────────────────────────────────────────────── */
 .xeplr-factory-screen { position: relative; width: 100%; color: var(--xf-ink); }
+.xeplr-factory-status {
+  display: flex; justify-content: space-between; gap: 12px; min-height: 18px;
+  padding: 4px 2px 8px; font-size: 12px; color: var(--xf-muted);
+}
+.xeplr-factory-status--saved { color: var(--xeplr-status-good, #1d7a4c); }
+.xeplr-factory-status--invalid, .xeplr-factory-status--error { color: var(--xf-danger); }
 .xeplr-factory-page { position: relative; width: 100%; margin: 0; }
 .xeplr-factory-node { position: absolute; box-sizing: border-box; }
 
@@ -36,10 +43,10 @@
   position: relative;
   display: flex; flex-direction: column; gap: calc(4 * var(--xf-u));
   width: 100%; height: 100%; box-sizing: border-box;
-  font-size: max(11px, calc(14 * var(--xf-u)));
+  font-size: max(10px, calc(var(--xf-font, 14) * var(--xf-u)));
 }
 .xeplr-factory-field--inline { justify-content: center; }
-.xeplr-factory-label { font-weight: 600; font-size: max(11px, calc(13 * var(--xf-u))); color: var(--xf-ink); line-height: 1.2; }
+.xeplr-factory-label { font-weight: 600; font-size: max(10px, calc((var(--xf-font, 14) - 1) * var(--xf-u))); color: var(--xf-ink); line-height: 1.2; }
 .xeplr-factory-required { color: var(--xf-danger); }
 .xeplr-factory-input {
   flex: 1; min-height: 0; width: 100%; box-sizing: border-box;
@@ -61,20 +68,30 @@
 .xeplr-factory-check { display: flex; align-items: center; gap: calc(8 * var(--xf-u)); cursor: pointer; font-weight: 500; }
 .xeplr-factory-check input { width: calc(18 * var(--xf-u)); height: calc(18 * var(--xf-u)); min-width: 12px; min-height: 12px; margin: 0; accent-color: var(--xf-accent); }
 
-.xeplr-factory-text { margin: 0; color: var(--xf-ink); height: 100%; overflow: hidden; line-height: 1.25; }
-.xeplr-factory-text--heading { font-size: max(16px, calc(26 * var(--xf-u))); font-weight: 700; }
-.xeplr-factory-text--subheading { font-size: max(13px, calc(18 * var(--xf-u))); font-weight: 600; }
-.xeplr-factory-text--text { font-size: max(11px, calc(14 * var(--xf-u))); color: var(--xf-muted); }
+/* A label's size and weight are inline — its preset, overridden by its style. */
+.xeplr-factory-text { margin: 0; color: var(--xf-ink); height: 100%; overflow: hidden; line-height: 1.25; box-sizing: border-box; }
+.xeplr-factory-text--text { color: var(--xf-muted); }
 
-.xeplr-factory-button {
-  width: 100%; height: 100%; box-sizing: border-box; cursor: pointer;
-  padding: 0 calc(8 * var(--xf-u)); white-space: nowrap; overflow: hidden; text-overflow: ellipsis;
-  font: inherit; font-weight: 600; font-size: max(12px, calc(14 * var(--xf-u)));
-  border-radius: calc(6 * var(--xf-u)); border: 1px solid var(--xf-accent);
+/* ── list ───────────────────────────────────────────────────────────────── */
+.xeplr-factory-list {
+  display: flex; flex-direction: column; width: 100%; height: 100%; box-sizing: border-box; overflow: auto;
+  font-size: max(10px, calc(var(--xf-font, 14) * var(--xf-u)));
+  border: 1px solid var(--xf-border); border-radius: calc(8 * var(--xf-u)); background: var(--xf-surface);
+}
+.xeplr-factory-list-head { display: flex; align-items: center; gap: 10px; padding: calc(8 * var(--xf-u)) calc(10 * var(--xf-u)); border-bottom: 1px solid var(--xf-border); }
+.xeplr-factory-list-title { font-weight: 600; flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.xeplr-factory-list-new {
+  font: inherit; font-weight: 600; font-size: .9em; padding: 3px 10px; border-radius: 5px; cursor: pointer;
+  color: var(--xf-accent); background: transparent; border: 1px solid var(--xf-accent);
 }
-.xeplr-factory-button--submit { background: var(--xf-accent); color: #fff; }
-.xeplr-factory-button--reset { background: var(--xf-surface); color: var(--xf-accent); }
-.xeplr-factory-button:disabled { opacity: .6; cursor: default; }
+.xeplr-factory-list-empty { padding: 16px; color: var(--xf-muted); text-align: center; }
+.xeplr-factory-error-inline { color: var(--xf-danger); font-size: .9em; }
+.xeplr-factory-list-mock { width: 100%; border-collapse: collapse; }
+.xeplr-factory-list-mock th { text-align: left; font-weight: 600; font-size: .9em; padding: calc(6 * var(--xf-u)) calc(10 * var(--xf-u)); border-bottom: 1px solid var(--xf-border); color: var(--xf-muted); }
+.xeplr-factory-list-mock td { padding: calc(8 * var(--xf-u)) calc(10 * var(--xf-u)); border-bottom: 1px solid var(--xf-border); }
+.xeplr-factory-list-bar { display: block; height: calc(8 * var(--xf-u)); width: 70%; border-radius: 4px; background: var(--xeplr-border-secondary, #ecebe4); }
+.xeplr-factory-list .xeplr-table-row.xeplr-factory-row-open td,
+.xeplr-factory-list tr.xeplr-factory-row-open td { background: color-mix(in srgb, var(--xf-accent) 10%, transparent); }
 
 /* ── the builder ────────────────────────────────────────────────────────── */
 .xeplr-factory-builder {
@@ -107,6 +124,8 @@
 .xeplr-factory-save-error { padding: 6px 12px; color: var(--xf-danger); background: color-mix(in srgb, var(--xf-danger) 7%, transparent); font-size: 12px; }
 
 .xeplr-factory-body { flex: 1; min-height: 0; display: flex; }
+.xeplr-factory-bar-status--saved { color: var(--xeplr-status-good, #1d7a4c); }
+.xeplr-factory-bar-status--invalid, .xeplr-factory-bar-status--error { color: var(--xf-danger); }
 .xeplr-factory-preview { flex: 1; min-height: 0; overflow: auto; padding: 16px; background: var(--xeplr-plane, #f7f7f5); }
 .xeplr-factory-preview > .xeplr-factory-screen { max-width: 960px; margin: 0 auto; background: var(--xeplr-surface, #fff); border: 1px solid var(--xf-border); border-radius: 8px; }
 
@@ -123,11 +142,13 @@
 .xeplr-factory-palette-icon { width: 14px; height: 10px; border: 1.5px solid var(--xf-muted); border-radius: 2px; flex: 0 0 auto; }
 .xeplr-factory-palette-icon--checkbox { width: 10px; }
 .xeplr-factory-palette-icon--label { border: none; border-top: 2px solid var(--xf-muted); border-bottom: 2px solid var(--xf-muted); height: 6px; }
-.xeplr-factory-palette-icon--button { background: var(--xf-muted); }
+.xeplr-factory-palette-icon--list { height: 12px; background: repeating-linear-gradient(to bottom, var(--xf-muted) 0 1.5px, transparent 1.5px 4px); border: none; }
 .xeplr-factory-palette-icon--textarea { height: 14px; }
 
 /* canvas */
-.xeplr-factory-stage { flex: 1; min-width: 0; min-height: 0; display: flex; background: var(--xeplr-plane, #f7f7f5); }
+.xeplr-factory-stage { flex: 1; min-width: 0; min-height: 0; display: flex; justify-content: center; padding: 12px; box-sizing: border-box; background: var(--xeplr-plane, #f7f7f5); }
+/* Exactly the screen's design width, never wider: what you design is the size it is shown at. */
+.xeplr-factory-frame { flex: 1; min-width: 0; height: 100%; display: flex; box-shadow: 0 1px 4px rgba(0,0,0,.08); }
 .xeplr-factory-canvas {
   flex: 1; height: 100%;
   background:
@@ -175,3 +196,34 @@
 .xeplr-factory-option-error { grid-column: 1 / -1; margin-top: 0; }
 .xeplr-factory-icon-button { border: none; background: none; cursor: pointer; font-size: 16px; color: var(--xf-muted); padding: 0; }
 .xeplr-factory-add { font: inherit; font-size: 12px; background: none; border: 1px dashed var(--xf-border); border-radius: 5px; padding: 5px; width: 100%; cursor: pointer; color: var(--xf-accent); }
+
+.xeplr-factory-color { display: grid; grid-template-columns: 32px 1fr 20px; gap: 4px; align-items: center; }
+.xeplr-factory-color input[type="color"] { width: 32px; height: 28px; padding: 0; border: 1px solid var(--xf-border); border-radius: 5px; background: none; cursor: pointer; }
+.xeplr-factory-checklist { display: flex; flex-direction: column; gap: 5px; }
+.xeplr-factory-checklist .xeplr-factory-toggle { font-weight: 500; }
+
+/* ── popup ──────────────────────────────────────────────────────────────── */
+.xeplr-factory-modal-backdrop {
+  position: fixed; inset: 0; z-index: 10000; display: flex; align-items: flex-start; justify-content: center;
+  padding: 4vh 2vw; box-sizing: border-box; overflow: auto;
+  background: rgba(20, 20, 18, .45);
+}
+.xeplr-factory-modal {
+  max-width: 96vw; background: var(--xeplr-surface, #fff); color: var(--xeplr-text, #1a1a19);
+  border-radius: 10px; box-shadow: 0 12px 40px rgba(0, 0, 0, .25); outline: none;
+}
+.xeplr-factory-modal-head { display: flex; align-items: center; justify-content: space-between; padding: 10px 16px; border-bottom: 1px solid var(--xeplr-border, #e2e1d9); }
+.xeplr-factory-modal-title { font-weight: 700; font-size: 15px; }
+.xeplr-factory-modal-close { border: none; background: none; font-size: 22px; line-height: 1; cursor: pointer; color: var(--xeplr-muted, #6b6a63); padding: 2px 6px; }
+.xeplr-factory-modal-body { padding: 8px 24px 16px; }
+
+/* ── publish result ─────────────────────────────────────────────────────── */
+.xeplr-factory-publish { display: flex; align-items: flex-start; gap: 10px; padding: 8px 12px; font-size: 12.5px; border-bottom: 1px solid var(--xf-border); }
+.xeplr-factory-publish > span { flex: 1; }
+.xeplr-factory-publish.is-ok { color: var(--xeplr-status-good, #1d7a4c); background: color-mix(in srgb, var(--xeplr-status-good, #1d7a4c) 7%, transparent); }
+.xeplr-factory-publish.is-error { color: var(--xf-danger); background: color-mix(in srgb, var(--xf-danger) 7%, transparent); flex-wrap: wrap; }
+.xeplr-factory-publish-detail { flex-basis: 100%; order: 3; margin: 4px 0 0; padding: 8px; max-height: 220px; overflow: auto; font-size: 11.5px; color: var(--xeplr-text, #1a1a19); background: var(--xeplr-surface, #fff); border: 1px solid var(--xf-border); border-radius: 6px; white-space: pre; }
+.xeplr-factory-publish.is-confirm { align-items: center; color: var(--xeplr-text, #1a1a19); background: color-mix(in srgb, var(--xeplr-status-warn, #a86a00) 10%, transparent); border-bottom-color: color-mix(in srgb, var(--xeplr-status-warn, #a86a00) 40%, transparent); }
+.xeplr-factory-confirm-text { flex: 1; line-height: 1.5; }
+.xeplr-factory-confirm-text ul { margin: 4px 0; padding-left: 18px; }
+.xeplr-factory-confirm-actions { display: flex; gap: 8px; flex-shrink: 0; }

package/src/designs/index.js

@@ -2,6 +2,8 @@ import './factory.css'
 
 export { default as BuilderSample } from './BuilderSample.jsx'
 export { default as ScreenSample } from './ScreenSample.jsx'
+export { default as ListView } from './ListView.jsx'
+export { default as ScreenModal } from './ScreenModal.jsx'
 export { default as ControlView, VIEWS } from './ControlView.jsx'
 export { default as Palette, DRAG_TYPE } from './Palette.jsx'
 export { default as PropertyPanel, EDITORS } from './PropertyPanel.jsx'

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'