@xeplr/ui-factory 1.0.1

package/src/document.js

@@ -0,0 +1,215 @@
+// THE SCREEN DOCUMENT — the metadata a screen is saved as, and every change
+// the builder makes to it. Pure and immutable: each function returns a new
+// document. No React, no storage; the consuming app stores documents.
+//
+//   {
+//     kind: 'xeplr-screen', version: 1,
+//     id: 'new_employee', name: 'New employee',
+//     units: 'fraction', aspect: 1,
+//     nodes: [ { id, type, x, y, w, h, z?, groupId?, props } ]
+//   }
+//
+// ── GEOMETRY ─────────────────────────────────────────────────────────────
+// Proportional, like the dashboards: x and w are fractions of the screen's
+// WIDTH; y and h are fractions of one PAGE, and a page is width × aspect tall.
+// With aspect 1 every number is simply a fraction of the width, so a screen
+// keeps exactly its proportions at any size. y may exceed 1 — a long form runs
+// onto a second page.
+
+import { CONTROLS } from './controls.js'
+import { getAtPath, setAtPath } from './propertyPath.js'
+
+export const DOCUMENT_KIND = 'xeplr-screen'
+export const DOCUMENT_VERSION = 1
+export const DEFAULT_ASPECT = 1
+
+/** 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 } = {}) {
+  const title = String(name || 'Untitled screen').trim() || 'Untitled screen'
+  return {
+    kind: DOCUMENT_KIND,
+    version: DOCUMENT_VERSION,
+    id: id || slugify(title, '_') || 'screen',
+    name: title,
+    units: 'fraction',
+    aspect: aspect > 0 ? aspect : DEFAULT_ASPECT,
+    nodes: []
+  }
+}
+
+export function renameScreen(doc, name) {
+  return { ...doc, name: String(name == null ? '' : name) }
+}
+
+/**
+ * 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.
+ * Returns { document, node }.
+ */
+export function addControl(doc, type, { at, props, size } = {}, controls = CONTROLS) {
+  const def = controls[type]
+  if (!def) throw new Error(`Unknown control type "${type}"`)
+  const dims = { ...def.defaultSize, ...size }
+  const pos = at ? clampPosition(at, dims) : nextPosition(doc, dims)
+  const merged = { ...clone(def.defaults), ...props }
+  if (def.input) {
+    const base = merged.name || camelName(merged.label) || type
+    merged.name = uniqueFieldName(doc, base)
+  }
+  const node = {
+    id: uniqueNodeId(doc, def.input ? merged.name : type),
+    type,
+    x: pos.x,
+    y: pos.y,
+    w: dims.w,
+    h: dims.h,
+    z: nextZ(doc),
+    props: merged
+  }
+  return { document: { ...doc, nodes: [...doc.nodes, node] }, node }
+}
+
+/** Merges a geometry patch — what the canvas reports on drop. */
+export function moveNode(doc, id, patch) {
+  const geometry = {}
+  ;['x', 'y', 'w', 'h', 'z'].forEach((k) => { if (typeof patch[k] === 'number') geometry[k] = round(patch[k]) })
+  return mapNode(doc, id, (n) => ({ ...n, ...geometry }))
+}
+
+/**
+ * Sets one property by path on a node — `props.validation.maxLength`.
+ *
+ * Renaming an input's LABEL also renames its field name, for as long as that
+ * 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.
+ */
+export function setNodeProperty(doc, id, path, value, controls = CONTROLS) {
+  const node = doc.nodes.find((n) => n.id === id)
+  const followLabel = path === 'props.label' && node && 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.
+    return updated.props ? updated : { ...updated, props: {} }
+  })
+  if (followLabel) {
+    const base = camelName(value) || node.type
+    const others = { ...next, nodes: next.nodes.filter((n) => n.id !== id) }
+    next = mapNode(next, id, (n) => ({ ...n, props: { ...n.props, name: uniqueFieldName(others, base) } }))
+  }
+  return next
+}
+
+/** Is this input's name still the one generated from its label or type? */
+function isAutoName(node, controls) {
+  const name = node.props?.name
+  if (!name) return true
+  const stem = name.replace(/\d+$/, '')
+  return stem === camelName(node.props.label) || stem === node.type || stem === camelName(controls[node.type]?.defaults?.label)
+}
+
+export function getNodeProperty(node, path) {
+  return getAtPath(node, path)
+}
+
+export function removeNodes(doc, ids) {
+  const gone = new Set(ids)
+  return { ...doc, nodes: doc.nodes.filter((n) => !gone.has(n.id)) }
+}
+
+/** The nodes that hold a value, in reading order (top to bottom, left to right). */
+export function inputNodes(doc, controls = CONTROLS) {
+  return readingOrder(doc.nodes.filter((n) => controls[n.type]?.input))
+}
+
+export function readingOrder(nodes) {
+  // Rows are compared with a little tolerance: two fields side by side are
+  // rarely at EXACTLY the same y after a drag.
+  return [...nodes].sort((a, b) => (Math.abs(a.y - b.y) > 0.02 ? a.y - b.y : a.x - b.x))
+}
+
+/** Where the lowest control ends, as a page fraction. */
+export function contentBottom(doc) {
+  return doc.nodes.reduce((max, n) => Math.max(max, (n.y || 0) + (n.h || 0)), 0)
+}
+
+// ── naming ───────────────────────────────────────────────────────────────
+
+/** "Date of birth" → "dateOfBirth". What a field is saved under. */
+export function camelName(label) {
+  const words = String(label || '')
+    .normalize('NFKD').replace(/[̀-ͯ]/g, '')
+    .replace(/[^A-Za-z0-9]+/g, ' ').trim().split(/\s+/).filter(Boolean)
+  if (!words.length) return ''
+  const name = words.map((w, i) => {
+    const lower = w.toLowerCase()
+    return i === 0 ? lower : lower.charAt(0).toUpperCase() + lower.slice(1)
+  }).join('')
+  return /^[0-9]/.test(name) ? '_' + name : name
+}
+
+export function slugify(text, sep = '-') {
+  return String(text || '')
+    .normalize('NFKD').replace(/[̀-ͯ]/g, '')
+    .toLowerCase().replace(/[^a-z0-9]+/g, sep).replace(new RegExp(`^\\${sep}+|\\${sep}+$`, 'g'), '')
+}
+
+export function uniqueFieldName(doc, base) {
+  const taken = new Set(doc.nodes.map((n) => n.props?.name).filter(Boolean))
+  return uniqueOf(base, taken)
+}
+
+function uniqueNodeId(doc, base) {
+  const taken = new Set(doc.nodes.map((n) => n.id))
+  return uniqueOf(base, taken)
+}
+
+function uniqueOf(base, taken) {
+  if (!taken.has(base)) return base
+  let i = 2
+  while (taken.has(base + i)) i++
+  return base + i
+}
+
+// ── placement ────────────────────────────────────────────────────────────
+
+/** Below everything already placed, at the left margin. */
+export function nextPosition(doc, size) {
+  const bottom = contentBottom(doc)
+  return clampPosition({ x: MARGIN, y: bottom ? bottom + GAP : MARGIN }, size)
+}
+
+function clampPosition(at, size) {
+  const w = Math.min(1, size.w)
+  return {
+    x: round(Math.min(Math.max(0, at.x), 1 - w)),
+    y: round(Math.max(0, at.y))
+  }
+}
+
+function nextZ(doc) {
+  return doc.nodes.reduce((max, n) => Math.max(max, n.z || 0), 0) + 1
+}
+
+function mapNode(doc, id, fn) {
+  let found = false
+  const nodes = doc.nodes.map((n) => {
+    if (n.id !== id) return n
+    found = true
+    return fn(n)
+  })
+  return found ? { ...doc, nodes } : doc
+}
+
+/** Four decimals: well under a pixel at any real width, and a diff stays readable. */
+export function round(v) {
+  return Math.round(v * 10000) / 10000
+}
+
+function clone(v) {
+  return v == null ? v : JSON.parse(JSON.stringify(v))
+}

package/src/generate.js

@@ -0,0 +1,167 @@
+// FROM A REQUEST TO A SCREEN.
+//
+// Screens are usually started by Claude from a plain-English request — "a form
+// for a new employee with name, email, department…" — and then adjusted by a
+// person in the builder. Writing fractional coordinates for every control by
+// hand is exactly the part of that an assistant gets subtly wrong (overlaps, a
+// field running off the edge), so this takes a SPEC — what is on the screen,
+// in order — and does the layout: a tidy one- or two-column form.
+//
+//   screenFromSpec({
+//     name: 'New employee',
+//     fields: [
+//       { label: 'First name', required: true },
+//       { label: 'Last name', required: true },
+//       { label: 'Email', validation: { pattern: '^\\S+@\\S+$', patternMessage: 'Enter a valid email' } },
+//       { label: 'Department', type: 'dropdown', table: 'departments', required: true },
+//       { label: 'Employment type', type: 'dropdown', options: ['Full time', 'Part time'] },
+//       { label: 'Start date', type: 'date' },
+//       { label: 'Notes', type: 'textarea' }
+//     ]
+//   })
+//
+// The result is an ordinary document, checked before it is returned; from
+// there it is edited like any other.
+
+import { CONTROLS } from './controls.js'
+import { createScreen, addControl, MARGIN, GAP, slugify } 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,
+  label: { heading: 0.07, subheading: 0.055, text: 0.045 }
+}
+
+/**
+ * Space between ROWS. Wider than the gap between columns: a field's error
+ * message is drawn in the space below it, and must not touch the next label.
+ */
+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']
+
+/**
+ * @param spec
+ *   name      screen title (required)
+ *   id?       document id — defaults to the name, snake_cased
+ *   columns?  1 or 2 (default 2)
+ *   heading?  true (default) puts the name at the top; a string uses that text; false for none
+ *   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'
+ *             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
+ */
+export function screenFromSpec(spec, controls = CONTROLS) {
+  if (!spec || typeof spec !== 'object') throw new Error('screenFromSpec: spec must be an object')
+  unknownKeys(spec, SPEC_KEYS, 'spec')
+  if (!spec.name || typeof spec.name !== 'string') throw new Error('screenFromSpec: spec.name is required, e.g. "New employee"')
+  if (!Array.isArray(spec.fields)) throw new Error('screenFromSpec: spec.fields must be an array')
+  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 })
+  const full = 1 - 2 * MARGIN
+  const colW = round((full - (columns - 1) * GAP) / columns)
+  let y = MARGIN
+  let col = 0
+  let rowH = 0
+
+  const place = (type, props, width) => {
+    const h = heightOf(type, props)
+    const isFull = width === 'full' || columns === 1 || type === 'textarea' || type === 'label'
+    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))
+      y += h + ROW_GAP
+      return
+    }
+    const x = MARGIN + col * (colW + GAP)
+    ;({ document: doc } = addControl(doc, type, { at: { x: round(x), y: round(y) }, size: { w: colW, h }, props }, controls))
+    rowH = Math.max(rowH, h)
+    col++
+    if (col === columns) { y += rowH + ROW_GAP; col = 0; rowH = 0 }
+  }
+
+  if (spec.heading !== false) {
+    place('label', { text: typeof spec.heading === 'string' ? spec.heading : spec.name, variant: 'heading' }, 'full')
+  }
+
+  spec.fields.forEach((field, i) => {
+    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(', ')}`)
+    if (field.width !== undefined && field.width !== 'half' && field.width !== 'full') throw new Error(`screenFromSpec: ${at}.width must be "half" or "full"`)
+    place(type, propsFromField(type, field, at), field.width)
+  })
+
+  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))
+  })
+
+  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' }
+  }
+  if (!field.label) throw new Error(`screenFromSpec: ${at}.label is required`)
+  const props = { label: field.label }
+  ;['name', 'required', 'placeholder', 'default', 'validation'].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)
+  else if (field.options || field.table || field.data) throw new Error(`screenFromSpec: ${at} — options/table/data only apply to a dropdown`)
+  return props
+}
+
+function dataFromField(field, at) {
+  if (field.data) return field.data
+  if (field.table) return { source: 'table', table: field.table }
+  if (Array.isArray(field.options)) {
+    return {
+      source: 'static',
+      options: field.options.map((o) => (typeof o === 'string'
+        ? { id: slugify(o, '_') || o, name: o }
+        : o))
+    }
+  }
+  throw new Error(`screenFromSpec: ${at} is a dropdown — give it options: [...] or table: "<name>"`)
+}
+
+function heightOf(type, props) {
+  const h = SPEC_HEIGHTS[type]
+  if (type === 'label') return h[props.variant] || h.text
+  return h || 0.08
+}
+
+function unknownKeys(obj, allowed, at) {
+  const extra = Object.keys(obj).filter((k) => !allowed.includes(k))
+  if (extra.length) throw new Error(`screenFromSpec: ${at} has unknown key(s) ${extra.join(', ')} — allowed: ${allowed.join(', ')}`)
+}
+
+function round(v) {
+  return Math.round(v * 10000) / 10000
+}

package/src/index.js

@@ -0,0 +1,19 @@
+// @xeplr/ui-factory — design data-entry screens on @xeplr/ui-canvas, save them
+// as JSON, render them as working forms.
+//
+// Three ways in, per the xeplr-ui-* convention:
+//   1. <FactoryBuilder> / <FactoryScreen> as they are
+//   2. useFactoryBuilder / useFactoryScreen with your own design
+//   3. the model alone — '@xeplr/ui-factory/model', no React, runs in node
+
+export * from './model.js'
+
+// Controllers
+export { useFactoryBuilder } from './useFactoryBuilder.js'
+export { useFactoryScreen, normaliseOptions } from './useFactoryScreen.js'
+
+// Designs
+export { BuilderSample, ScreenSample, ControlView, VIEWS, Palette, DRAG_TYPE, PropertyPanel, EDITORS } from './designs/index.js'
+
+// Ready-made
+export { FactoryBuilder, FactoryScreen } from './pages.jsx'

package/src/model.js

@@ -0,0 +1,15 @@
+// The model alone — no React, no CSS. Runs in node: a server checking a
+// submission, the CLI, tests, or Claude writing a screen.
+//
+//   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 {
+  DOCUMENT_KIND, DOCUMENT_VERSION, DEFAULT_ASPECT, MARGIN, GAP,
+  createScreen, renameScreen, 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 { getAtPath, setAtPath } from './propertyPath.js'

package/src/pages.jsx

@@ -0,0 +1,42 @@
+import { useFactoryBuilder } from './useFactoryBuilder.js'
+import { useFactoryScreen } from './useFactoryScreen.js'
+import { BuilderSample, ScreenSample } from './designs/index.js'
+
+/**
+ * The builder, ready-made.
+ *
+ * @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 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 controls     control registry (default: built-ins)
+ */
+export function FactoryBuilder(props) {
+  const ctrl = useFactoryBuilder(props)
+  return (
+    <BuilderSample
+      ctrl={ctrl}
+      className={props.className}
+      style={props.style}
+      renderPreview={(doc) => (
+        <FactoryScreen document={doc} fetchOptions={props.fetchOptions} controls={props.controls} />
+      )}
+    />
+  )
+}
+
+/**
+ * A saved screen, running.
+ *
+ * @prop document     a screen document (an invalid one renders its problems, loudly)
+ * @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 controls     control registry (default: built-ins)
+ */
+export function FactoryScreen(props) {
+  const ctrl = useFactoryScreen(props)
+  return <ScreenSample ctrl={ctrl} className={props.className} style={props.style} />
+}

package/src/propertyPath.js

@@ -0,0 +1,35 @@
+// Read and write a value by dotted path — `props.validation.maxLength`. The
+// property panel addresses every field this way, so a new property is a path in
+// controls.js and never a new setter.
+//
+// Writes are immutable: every object along the path is copied, nothing else is.
+
+export function getAtPath(obj, path) {
+  return String(path).split('.').reduce((cur, key) => (cur == null ? undefined : cur[key]), obj)
+}
+
+/**
+ * Sets `value` at `path`. A BLANK value — undefined, '' or an empty object left
+ * behind — removes the key instead, so clearing "Max length" leaves no
+ * `maxLength: ''` in the saved document for a validator to trip over.
+ */
+export function setAtPath(obj, path, value) {
+  const keys = String(path).split('.')
+  const [head, ...rest] = keys
+  const base = obj && typeof obj === 'object' ? obj : {}
+  if (!rest.length) {
+    const next = { ...base }
+    if (isBlank(value)) delete next[head]
+    else next[head] = value
+    return next
+  }
+  const child = setAtPath(base[head], rest.join('.'), value)
+  const next = { ...base }
+  if (child && typeof child === 'object' && !Array.isArray(child) && !Object.keys(child).length) delete next[head]
+  else next[head] = child
+  return next
+}
+
+function isBlank(v) {
+  return v === undefined || v === ''
+}