@xeplr/ui-factory 1.0.1 → 1.0.2

package/src/tableSchema.js

@@ -0,0 +1,225 @@
+// A FORM IS A REAL TABLE.
+//
+// Records are never stored as JSON: every entity has its own table, and every
+// field of its edit screen is a column of that table, named exactly as the
+// field. `select * from employees` is how you read them, and reporting is plain
+// SQL.
+//
+// This file derives that table from a screen and writes the migration that
+// gets the database there — the first time a CREATE TABLE, after that only what
+// changed. The migrations are ordinary files in the app's migrations folder,
+// written (usually by Claude) and reviewed like any other; nothing here touches
+// a database.
+//
+// Conventions are the xeplr ones (see xeplr-bi 0066_dashboard_groups.sql):
+// varchar(25) ids, quoted camelCase columns, isActive for soft delete, mtId1–4
+// for tenancy, recordCreated/Modified Date/By for audit.
+//
+// ── CHANGES THAT ARE SAFE, AND CHANGES THAT ARE REFUSED ──────────────────
+//   new field                 ADD COLUMN
+//   wider (varchar 80 → 120, varchar → text, integer → numeric)   ALTER TYPE
+//   narrower, or a different type (text → number)   REFUSED — data would be
+//                             lost or rejected; write that migration by hand
+//   field removed             column KEPT, reported as unused — dropping data
+//                             is a deliberate migration, never a side effect
+//   field renamed             seen as a NEW column beside an unused old one, with
+//                             the data left behind — which is why a field's name is
+//                             locked once its table exists (see the builder's
+//                             lockedNames). A real rename is a manual migration.
+
+import { CONTROLS } from './controls.js'
+import { inputNodes } from './document.js'
+
+/** Columns every entity table has, in this order. Fields may not use these names. */
+export const STANDARD_COLUMNS = [
+  { name: 'id', sql: 'varchar(25) PRIMARY KEY' },
+  { name: 'isActive', sql: 'boolean DEFAULT true' },
+  { name: 'mtId1', sql: 'varchar(25)' },
+  { name: 'mtId2', sql: 'varchar(25)' },
+  { name: 'mtId3', sql: 'varchar(25)' },
+  { name: 'mtId4', sql: 'varchar(25)' },
+  { name: 'recordCreatedDate', sql: 'timestamp DEFAULT now()' },
+  { name: 'recordModifiedDate', sql: 'timestamp DEFAULT now()' },
+  { name: 'recordCreatedBy', sql: 'varchar(25)' },
+  { name: 'recordModifiedBy', sql: 'varchar(25)' }
+]
+
+export const RESERVED_COLUMNS = STANDARD_COLUMNS.map((c) => c.name)
+
+/** Postgres truncates identifiers past this — two long fields would collide silently. */
+export const MAX_IDENTIFIER = 63
+
+const TEXT_DEFAULT_LENGTH = 255
+const OPTION_MIN_LENGTH = 50
+
+/**
+ * The column a field is stored in.
+ * @returns {{ name, type: 'varchar'|'text'|'integer'|'numeric'|'date'|'boolean', length?, references?, notNull?, default? }}
+ */
+export function columnForField(node) {
+  const p = node.props || {}
+  const v = p.validation || {}
+  const base = { name: p.name, label: p.label }
+  switch (node.type) {
+    case 'text':
+      return { ...base, type: 'varchar', length: v.maxLength || TEXT_DEFAULT_LENGTH }
+    case 'textarea':
+      return { ...base, type: 'text' }
+    case 'number':
+      return { ...base, type: v.integer ? 'integer' : 'numeric' }
+    case 'date':
+      return { ...base, type: 'date' }
+    case 'checkbox':
+      return { ...base, type: 'boolean', notNull: true, default: 'false' }
+    case 'dropdown': {
+      const data = p.data || {}
+      if (data.source === 'table') {
+        // A real foreign key to the other entity's id.
+        return { ...base, type: 'varchar', length: 25, references: data.table }
+      }
+      const longest = (data.options || []).reduce((m, o) => Math.max(m, String(o.id).length), 0)
+      return { ...base, type: 'varchar', length: Math.max(OPTION_MIN_LENGTH, longest) }
+    }
+    default:
+      return null
+  }
+}
+
+/**
+ * The table an edit screen saves to.
+ * @returns {{ table, columns }} — columns are the fields, in reading order
+ */
+export function tableForScreen(doc, controls = CONTROLS) {
+  if (!doc || !doc.source) throw new Error('The screen has no "source" — which table does it save to?')
+  const columns = inputNodes(doc, controls).map(columnForField).filter(Boolean)
+  if (!columns.length) throw new Error(`Screen "${doc.id}" has no fields, so it defines no table columns — generate the migration from the edit screen`)
+  return { table: doc.source, columns }
+}
+
+export function columnSql(col) {
+  const type = col.type === 'varchar' ? `varchar(${col.length})` : col.type
+  const parts = [type]
+  if (col.references) parts.push(`REFERENCES ${q(col.references)}("id")`)
+  if (col.notNull) parts.push('NOT NULL')
+  if (col.default !== undefined) parts.push(`DEFAULT ${col.default}`)
+  return parts.join(' ')
+}
+
+/** Is changing `from` to `to` safe for data already in the column? */
+export function widening(from, to) {
+  if (from.references || to.references) {
+    if (from.references !== to.references) return { ok: false, reason: `it points at "${from.references || 'no table'}" and would point at "${to.references || 'no table'}"` }
+  }
+  if (from.type === to.type) {
+    if (from.type !== 'varchar') return { ok: true, same: true }
+    if (to.length === from.length) return { ok: true, same: true }
+    if (to.length > from.length) return { ok: true }
+    return { ok: false, reason: `varchar(${from.length}) → varchar(${to.length}) would cut longer values` }
+  }
+  if (from.type === 'varchar' && to.type === 'text') return { ok: true }
+  if (from.type === 'integer' && to.type === 'numeric') return { ok: true }
+  return { ok: false, reason: `${describe(from)} → ${describe(to)} is a different kind of value` }
+}
+
+/**
+ * What it takes to go from the table as it was to the table as the screen now
+ * describes it.
+ * @param before  { table, columns } or null for a new table
+ * @returns {{ create, add, alter, unused, refused, same }}
+ */
+export function diffTables(before, after) {
+  if (before && before.table !== after.table) {
+    return { create: false, add: [], alter: [], unused: [], same: false, refused: [{ column: null, reason: `the screen now saves to "${after.table}" instead of "${before.table}" — moving records to another table is a manual migration` }] }
+  }
+  if (!before) return { create: true, add: after.columns, alter: [], unused: [], refused: [], same: false }
+  const was = Object.fromEntries(before.columns.map((c) => [c.name, c]))
+  const now = Object.fromEntries(after.columns.map((c) => [c.name, c]))
+  const add = []
+  const alter = []
+  const refused = []
+  after.columns.forEach((c) => {
+    const old = was[c.name]
+    if (!old) { add.push(c); return }
+    const w = widening(old, c)
+    if (!w.ok) refused.push({ column: c.name, reason: w.reason })
+    else if (!w.same) alter.push({ from: old, to: c })
+  })
+  const unused = before.columns.filter((c) => !now[c.name])
+  return { create: false, add, alter, unused, refused, same: !add.length && !alter.length && !unused.length && !refused.length }
+}
+
+/**
+ * The migration SQL from one version of an edit screen to the next.
+ * @param previous  the edit screen as last migrated, or null
+ * @param next      the edit screen now
+ * @returns {{ sql, diff, table, empty }} — throws if a change is refused
+ */
+export function migrationFor(previous, next, controls = CONTROLS) {
+  const after = tableForScreen(next, controls)
+  const before = previous ? tableForScreen(previous, controls) : null
+  const diff = diffTables(before, after)
+  if (diff.refused.length) {
+    const e = new Error(`Cannot migrate "${after.table}" safely:\n` + diff.refused.map((r) => `  ${r.column ? `"${r.column}": ` : ''}${r.reason}`).join('\n'))
+    e.refused = diff.refused
+    throw e
+  }
+  if (diff.same || (!diff.create && !diff.add.length && !diff.alter.length)) {
+    return { sql: '', diff, table: after.table, empty: true }
+  }
+
+  const t = after.table
+  const lines = []
+  const header = [
+    `-- ${diff.create ? 'Create' : 'Update'} "${t}" for screen "${next.id}" (${next.name}).`,
+    '--',
+    '-- Written from the screen by @xeplr/ui-factory: one column per field, named'
+  , '-- exactly as the field. Review before applying.'
+  ]
+  if (diff.unused.length) {
+    header.push('--', `-- Kept, no longer on the screen (drop by hand if the data is not needed): ${diff.unused.map((c) => `"${c.name}"`).join(', ')}`)
+  }
+  lines.push(...header, '')
+
+  if (diff.create) {
+    const cols = [...STANDARD_COLUMNS.slice(0, 1), ...after.columns.map((c) => ({ name: c.name, sql: columnSql(c), label: c.label })), ...STANDARD_COLUMNS.slice(1)]
+    const width = Math.max(...cols.map((c) => c.name.length)) + 2
+    lines.push(`CREATE TABLE IF NOT EXISTS ${q(t)} (`)
+    cols.forEach((c, i) => {
+      const comma = i < cols.length - 1 ? ',' : ''
+      const note = c.label ? `  -- ${c.label}` : ''
+      lines.push(`  ${q(c.name).padEnd(width)} ${c.sql}${comma}${note}`)
+    })
+    lines.push(');', '')
+    lines.push(`CREATE INDEX IF NOT EXISTS ${q(`${t}_mt_index`)} ON ${q(t)} ("mtId1", "mtId2");`)
+    after.columns.filter((c) => c.references).forEach((c) => {
+      lines.push(`CREATE INDEX IF NOT EXISTS ${q(`${t}_${c.name}_index`)} ON ${q(t)} (${q(c.name)});`)
+    })
+  } else {
+    diff.add.forEach((c) => {
+      lines.push(`ALTER TABLE ${q(t)} ADD COLUMN IF NOT EXISTS ${q(c.name)} ${columnSql(c)};  -- ${c.label}`)
+      if (c.references) lines.push(`CREATE INDEX IF NOT EXISTS ${q(`${t}_${c.name}_index`)} ON ${q(t)} (${q(c.name)});`)
+    })
+    diff.alter.forEach(({ from, to }) => {
+      const type = to.type === 'varchar' ? `varchar(${to.length})` : to.type
+      lines.push(`ALTER TABLE ${q(t)} ALTER COLUMN ${q(to.name)} TYPE ${type};  -- was ${describe(from)}`)
+    })
+  }
+  return { sql: lines.join('\n') + '\n', diff, table: t, empty: false }
+}
+
+/** Next migration file name in a folder of NNNN_*.sql files. */
+export function nextMigrationName(existingFiles, table, create) {
+  const top = (existingFiles || []).reduce((m, f) => {
+    const n = /^(\d+)_/.exec(f)
+    return n ? Math.max(m, Number(n[1])) : m
+  }, 0)
+  return `${String(top + 1).padStart(4, '0')}_factory_${table}_${create ? 'create' : 'update'}.sql`
+}
+
+function describe(c) {
+  return c.type === 'varchar' ? `varchar(${c.length})` : c.type
+}
+
+function q(identifier) {
+  return `"${String(identifier).replace(/"/g, '""')}"`
+}

package/src/useFactoryBuilder.js

@@ -1,7 +1,7 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import { CONTROLS, controlGroups } from './controls.js'
 import {
-  createScreen, renameScreen, addControl as addControlTo, moveNode, setNodeProperty,
+  createScreen, renameScreen, setScreenProperty, addControl as addControlTo, moveNode, setNodeProperty,
   removeNodes
 } from './document.js'
 import { validateDocument } from './validateDocument.js'
@@ -14,36 +14,47 @@ import { validateDocument } from './validateDocument.js'
 // the `document` it is handed and gives the result to `onSave`. A document
 // handed in LATER (Claude regenerated the screen, another record was opened)
 // replaces what is being edited.
+//
+// NO SAVE BUTTON. Every edit is saved a moment after the last one, whenever the
+// screen is valid; while it is not, the problems are shown and nothing is sent.
 
 /**
  * @param document    the screen to edit; omitted → a new empty screen
  * @param name        the name for a new screen (when no document)
- * @param onSave      async (document) → void; called only with a valid document
+ * @param onSave      async (document) → void; called automatically, only with a valid document
+ * @param autosaveDelay ms of quiet after the last edit before saving (default 800)
  * @param onChange    (document) → void; every edit, for hosts that autosave or preview
  * @param listTables  async () → [{ id, name }] | string[]; offered in a dropdown's
  *                    "from a table" picker. Omitted → table sources can still be typed.
+ * @param screens     [{ id, name, document? }] — other screens, offered for a list's "Edit in";
+ *                    with its document, a list screen can pick columns from its fields
+ * @param lockedNames field names that are already columns of the table — they cannot be renamed
+ * @param onPublish   async (document) → { version } — makes the saved draft the version everyone sees.
+ *                    It may refuse (e.g. the table is missing columns) by throwing; the message is shown.
  * @param controls    the control registry (default: the built-ins)
  */
-export function useFactoryBuilder({ document: given, name, onSave, onChange, listTables, controls = CONTROLS } = {}) {
+export function useFactoryBuilder({ document: given, name, onSave, onChange, onPublish, listTables, screens, lockedNames, controls = CONTROLS, autosaveDelay = 800 } = {}) {
   const [doc, setDoc] = useState(() => given || createScreen({ name }))
   const [selected, setSelected] = useState(() => new Set())
   const [dirty, setDirty] = useState(false)
   const [saving, setSaving] = useState(false)
   const [saveError, setSaveError] = useState(null)
-  const [showErrors, setShowErrors] = useState(false)
+  const [savedAt, setSavedAt] = useState(null)
   const docRef = useRef(doc); docRef.current = doc
 
-  // A NEW document from outside replaces the draft. Compared by identity: the
-  // host re-rendering with the same object must not throw away edits.
+  // A NEW document from outside replaces the draft. Not a new OBJECT: a host
+  // that re-reads what it just saved hands back the same screen as a fresh
+  // object on every autosave, and replacing the draft with it would drop the
+  // selection each time. Only different content replaces what is being edited.
   const lastGiven = useRef(given)
   useEffect(() => {
     if (!given || given === lastGiven.current) return
     lastGiven.current = given
+    if (JSON.stringify(given) === JSON.stringify(docRef.current)) return
     docRef.current = given
     setDoc(given)
     setSelected(new Set())
     setDirty(false)
-    setShowErrors(false)
   }, [given])
 
   // Every edit goes through here. It works on a REF of the current document,
@@ -82,6 +93,8 @@ export function useFactoryBuilder({ document: given, name, onSave, onChange, lis
 
   // ── edits ─────────────────────────────────────────────────────────────
   const rename = useCallback((value) => update((d) => renameScreen(d, value)), [update])
+  /** A screen property by path — `source`, `width`, `style.fontSize`. */
+  const setScreen = useCallback((path, value) => update((d) => setScreenProperty(d, path, value)), [update])
 
   /** Adds a control and selects it, so its properties are open straight away. */
   const addControl = useCallback((type, at) => {
@@ -97,7 +110,8 @@ export function useFactoryBuilder({ document: given, name, onSave, onChange, lis
 
   const moveControl = useCallback((id, patch) => update((d) => moveNode(d, id, patch)), [update])
 
-  const setProperty = useCallback((id, path, value) => update((d) => setNodeProperty(d, id, path, value, controls)), [update, controls])
+  const lockedRef = useRef(lockedNames); lockedRef.current = lockedNames
+  const setProperty = useCallback((id, path, value) => update((d) => setNodeProperty(d, id, path, value, controls, { lockedNames: lockedRef.current })), [update, controls])
 
   const selectedRef = useRef(selected); selectedRef.current = selected
   const removeSelected = useCallback(() => {
@@ -144,24 +158,75 @@ export function useFactoryBuilder({ document: given, name, onSave, onChange, lis
   }, [validation, doc.nodes])
 
   const onSaveRef = useRef(onSave); onSaveRef.current = onSave
+  const savingRef = useRef(false)
   const save = useCallback(async () => {
-    setShowErrors(true)
-    setSaveError(null)
-    if (!validation.ok) return { ok: false, errors: validation.errors }
+    const current = docRef.current
+    const check = validateDocument(current, controls)
+    if (!check.ok) return { ok: false, errors: check.errors }
     if (!onSaveRef.current) return { ok: false, errors: [{ path: '', message: 'No onSave was provided' }] }
+    if (savingRef.current) return { ok: false, busy: true }
+    savingRef.current = true
     setSaving(true)
+    setSaveError(null)
     try {
-      await onSaveRef.current(doc)
-      setDirty(false)
-      setShowErrors(false)
+      await onSaveRef.current(current)
+      // Only clean if nothing changed while the save was out.
+      if (docRef.current === current) setDirty(false)
+      setSavedAt(new Date())
       return { ok: true }
     } catch (err) {
       setSaveError(err.message || 'Could not save')
       return { ok: false, errors: [{ path: '', message: err.message }] }
     } finally {
+      savingRef.current = false
       setSaving(false)
     }
-  }, [doc, validation])
+  }, [controls])
+
+  // AUTOSAVE: a quiet moment after the last edit, if the screen is valid.
+  useEffect(() => {
+    if (!dirty || !validation.ok || !onSaveRef.current) return undefined
+    const t = setTimeout(save, autosaveDelay)
+    return () => clearTimeout(t)
+  }, [doc, dirty, validation.ok, save, autosaveDelay, saving])
+
+  // PUBLISH: the draft becomes the next version — what screens actually show.
+  // Deliberate, unlike saving: a half-finished design must not reach everyone
+  // filling the form in.
+  const onPublishRef = useRef(onPublish); onPublishRef.current = onPublish
+  const [publishing, setPublishing] = useState(false)
+  const [publishResult, setPublishResult] = useState(null)   // { ok, message, version?, detail? }
+  const publish = useCallback(async () => {
+    if (!onPublishRef.current) return { ok: false }
+    const check = validateDocument(docRef.current, controls)
+    if (!check.ok) {
+      const r = { ok: false, message: `Fix ${check.errors.length} problem${check.errors.length === 1 ? '' : 's'} before publishing` }
+      setPublishResult(r)
+      return r
+    }
+    setPublishing(true)
+    setPublishResult(null)
+    try {
+      const saved = await save()
+      if (!saved.ok && !saved.busy) throw new Error((saved.errors && saved.errors[0] && saved.errors[0].message) || 'Could not save the draft')
+      const res = await onPublishRef.current(docRef.current)
+      const r = { ok: true, version: res && res.version, message: res && res.version ? `Published version ${res.version}` : 'Published' }
+      setPublishResult(r)
+      return r
+    } catch (err) {
+      const r = { ok: false, message: err.message || 'Could not publish', detail: err.detail }
+      setPublishResult(r)
+      return r
+    } finally {
+      setPublishing(false)
+    }
+  }, [controls, save])
+
+  const status = saveError ? 'error'
+    : saving ? 'saving'
+    : !validation.ok ? 'invalid'
+    : dirty ? 'pending'
+    : savedAt ? 'saved' : 'idle'
 
   // ── keyboard: Delete / Backspace removes, Cmd/Ctrl+D duplicates ────────
   useEffect(() => {
@@ -192,18 +257,27 @@ export function useFactoryBuilder({ document: given, name, onSave, onChange, lis
     selectedNode,
     selectedControl: selectedNode ? controls[selectedNode.type] : null,
     rename,
+    setScreen,
     addControl,
     moveControl,
     setProperty,
     removeSelected,
     duplicateSelected,
     tables,
+    screens: screens || [],
+    lockedNames: lockedNames || [],
     validation,
     errorsByNode,
-    showErrors,
     dirty,
     saving,
     saveError,
-    save
+    savedAt,
+    status,
+    save,
+    canPublish: Boolean(onPublish),
+    publish,
+    publishing,
+    publishResult,
+    clearPublishResult: () => setPublishResult(null)
   }
 }