@xeplr/ui-factory 1.0.1 → 1.0.3

package/src/validateDocument.js

@@ -10,10 +10,15 @@
 // Loud by design: a screen that half-renders — a dropdown with no options, two
 // fields writing the same key — looks like a data problem to whoever uses it.
 
-import { CONTROLS, LABEL_VARIANTS, BUTTON_ACTIONS } from './controls.js'
+import { CONTROLS, LABEL_VARIANTS, LIST_ACTIONS, STYLE_KEYS, SCREEN_STYLE_KEYS } from './controls.js'
 import { DOCUMENT_KIND, DOCUMENT_VERSION } from './document.js'
+import { RESERVED_COLUMNS, MAX_IDENTIFIER } from './tableSchema.js'
 
 const FIELD_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/
+const TABLE_NAME = /^[A-Za-z_][A-Za-z0-9_.$-]*$/
+const SCREEN_ID = /^[A-Za-z0-9_-]+$/
+const DOCUMENT_KEYS = ['kind', 'version', 'id', 'name', 'source', 'units', 'aspect', 'width', 'style', 'nodes']
+const COLOR = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i
 
 /**
  * @returns {{ ok: boolean, errors: Array<{ path: string, message: string }> }}
@@ -29,9 +34,16 @@ export function validateDocument(doc, controls = CONTROLS) {
   if (doc.kind !== DOCUMENT_KIND) err('kind', `must be "${DOCUMENT_KIND}"`)
   if (doc.version !== DOCUMENT_VERSION) err('version', `must be ${DOCUMENT_VERSION}`)
   if (!nonEmptyString(doc.id)) err('id', 'must be a non-empty string')
+  else if (!SCREEN_ID.test(doc.id)) err('id', `"${doc.id}" must contain only letters, digits, _ and -`)
   if (!nonEmptyString(doc.name)) err('name', 'must be a non-empty string — the screen\'s title, e.g. "New employee"')
   if (doc.units !== 'fraction') err('units', 'must be "fraction"')
   if (!(typeof doc.aspect === 'number' && doc.aspect > 0)) err('aspect', 'must be a number greater than 0 (1 = page as tall as it is wide)')
+  if (!(Number.isInteger(doc.width) && doc.width >= 320 && doc.width <= 1920)) err('width', 'must be a whole number of pixels from 320 to 1920 — the width the screen is designed at')
+  if (doc.source !== undefined && !(nonEmptyString(doc.source) && TABLE_NAME.test(doc.source))) err('source', 'must name the table records are saved to, e.g. "employees"')
+  checkStyle(doc.style, SCREEN_STYLE_KEYS, 'style', err, 'the screen')
+  Object.keys(doc).forEach((k) => {
+    if (!DOCUMENT_KEYS.includes(k)) err(k, `is not a screen property — allowed: ${DOCUMENT_KEYS.join(', ')}`)
+  })
   if (!Array.isArray(doc.nodes)) {
     err('nodes', 'must be an array of controls')
     return { ok: false, errors }
@@ -69,6 +81,8 @@ export function validateDocument(doc, controls = CONTROLS) {
       if (!nonEmptyString(props.name)) err(`${at}.props.name`, 'is required — the key the value is saved under')
       else if (!FIELD_NAME.test(props.name)) err(`${at}.props.name`, `"${props.name}" must start with a letter or _ and contain only letters, digits and _`)
       else if (names.has(props.name)) err(`${at}.props.name`, `"${props.name}" is already used by nodes[${names.get(props.name)}] — two fields cannot save to one key`)
+      else if (RESERVED_COLUMNS.includes(props.name)) err(`${at}.props.name`, `"${props.name}" is a standard column of every table — choose another name`)
+      else if (props.name.length > MAX_IDENTIFIER) err(`${at}.props.name`, `is ${props.name.length} characters — a column name can be at most ${MAX_IDENTIFIER}`)
       else names.set(props.name, i)
 
       if (!nonEmptyString(props.label)) err(`${at}.props.label`, 'is required — the text shown above the field')
@@ -78,15 +92,13 @@ export function validateDocument(doc, controls = CONTROLS) {
       checkValidation(node, def, at, err)
     }
 
+    checkStyle(props.style, def.styles || [], `${at}.props.style`, err, `"${node.type}"`)
     if (node.type === 'dropdown') checkDataSource(props.data, `${at}.props.data`, err)
+    if (node.type === 'list') checkList(props, doc, at, err)
     if (node.type === 'label') {
       if (typeof props.text !== 'string') err(`${at}.props.text`, 'must be a string')
       if (props.variant !== undefined && !LABEL_VARIANTS.includes(props.variant)) err(`${at}.props.variant`, `must be one of: ${LABEL_VARIANTS.join(', ')}`)
     }
-    if (node.type === 'button') {
-      if (!nonEmptyString(props.label)) err(`${at}.props.label`, 'is required — the text on the button')
-      if (props.action !== undefined && !BUTTON_ACTIONS.includes(props.action)) err(`${at}.props.action`, `must be one of: ${BUTTON_ACTIONS.join(', ')}`)
-    }
   })
 
   return { ok: errors.length === 0, errors }
@@ -193,6 +205,62 @@ function checkDataSource(data, at, err) {
   }
 }
 
+/** `props.style` / the screen's `style`: only known keys, each in range. */
+function checkStyle(style, allowed, at, err, owner) {
+  if (style === undefined) return
+  if (!style || typeof style !== 'object' || Array.isArray(style)) { err(at, 'must be an object'); return }
+  Object.keys(style).forEach((key) => {
+    const path = `${at}.${key}`
+    const spec = STYLE_KEYS[key]
+    if (!spec || !allowed.includes(key)) {
+      err(path, `is not a style of ${owner} — allowed: ${allowed.join(', ')}`)
+      return
+    }
+    const v = style[key]
+    let ok
+    switch (spec.type) {
+      case 'number': ok = typeof v === 'number' && Number.isFinite(v) && v >= spec.min && v <= spec.max; break
+      case 'select': ok = spec.options.some((o) => o.value === v); break
+      case 'toggleValue': ok = v === 'normal' || v === spec.on; break
+      case 'color': ok = typeof v === 'string' && (COLOR.test(v) || (key !== 'color' && key !== 'labelColor' && v === 'transparent')); break
+      case 'font': ok = typeof v === 'string' && v.trim() !== '' && v.length <= 200 && !/[;{}<>]/.test(v); break
+      default: ok = true
+    }
+    if (!ok) err(path, `must be ${spec.hint}`)
+  })
+}
+
+/**
+ * A list of saved records: where they come from, which columns, which actions.
+ * With no `source` it reads the table the screen saves to, so one of the two
+ * must be set.
+ */
+function checkList(props, doc, at, err) {
+  if (props.title !== undefined && typeof props.title !== 'string') err(`${at}.props.title`, 'must be a string')
+  if (props.source !== undefined && !(nonEmptyString(props.source) && TABLE_NAME.test(props.source))) err(`${at}.props.source`, 'must name the table to list records from')
+  if (props.source === undefined && doc.source === undefined) err(`${at}.props.source`, 'is required when the screen has no "source" — which table should the list read?')
+  if (props.editScreen !== undefined && !(nonEmptyString(props.editScreen) && SCREEN_ID.test(props.editScreen))) err(`${at}.props.editScreen`, 'must be the id of the screen that edits a record, e.g. "employee_edit"')
+  if (props.pageSize !== undefined && !(Number.isInteger(props.pageSize) && props.pageSize >= 1 && props.pageSize <= 200)) err(`${at}.props.pageSize`, 'must be a whole number from 1 to 200')
+  if (props.actions !== undefined) {
+    if (!Array.isArray(props.actions)) err(`${at}.props.actions`, `must be an array of: ${LIST_ACTIONS.join(', ')}`)
+    else props.actions.forEach((a, j) => { if (!LIST_ACTIONS.includes(a)) err(`${at}.props.actions[${j}]`, `must be one of: ${LIST_ACTIONS.join(', ')}`) })
+  }
+  if (props.columns !== undefined) {
+    if (!Array.isArray(props.columns)) { err(`${at}.props.columns`, 'must be an array of { field, label }'); return }
+    const seen = new Set()
+    props.columns.forEach((c, j) => {
+      const p = `${at}.props.columns[${j}]`
+      if (!c || typeof c !== 'object') { err(p, 'must be { field, label }'); return }
+      if (!(nonEmptyString(c.field) && FIELD_NAME.test(c.field))) err(`${p}.field`, 'must be a field name — letters, digits and _')
+      else if (seen.has(c.field)) err(`${p}.field`, `"${c.field}" appears twice`)
+      else seen.add(c.field)
+      if (!nonEmptyString(c.label)) err(`${p}.label`, 'must be a non-empty string — the column heading')
+      const extra = Object.keys(c).filter((k) => k !== 'field' && k !== 'label')
+      if (extra.length) err(p, `only "field" and "label" are used — remove: ${extra.join(', ')}`)
+    })
+  }
+}
+
 function nonEmptyString(v) {
   return typeof v === 'string' && v.trim() !== ''
 }

package/src/values.js

@@ -146,3 +146,64 @@ export function optionValue(options, raw) {
 function safeRegExp(pattern) {
   try { return new RegExp(pattern) } catch (_) { return { test: () => true } }
 }
+
+// ── autosave ─────────────────────────────────────────────────────────────
+// There is no submit. A screen saves itself a moment after a change, as long
+// as what is entered is acceptable. This decides whether it can, and which
+// messages to SHOW: a field nobody has touched is not shouted at for being
+// empty — it only holds the save back.
+
+/**
+ * @param touched   Set of field names the person has changed or left
+ * @returns {{ canSave, status, errors, shown }}
+ *   status  'ready' | 'incomplete' (only untouched required fields are empty) | 'invalid'
+ *   errors  every failing field → message
+ *   shown   the ones to display now
+ */
+export function saveState(doc, values, touched, loadedOptions = {}, controls = CONTROLS) {
+  const errors = validateValues(doc, values, controls, loadedOptions)
+  const names = Object.keys(errors)
+  const shown = {}
+  names.forEach((n) => { if (touched && touched.has(n)) shown[n] = errors[n] })
+  if (!names.length) return { canSave: true, status: 'ready', errors, shown }
+  const onlyUntouched = names.every((n) => !(touched && touched.has(n)))
+  return { canSave: false, status: onlyUntouched ? 'incomplete' : 'invalid', errors, shown }
+}
+
+/** A saved record → the screen's values, for Edit. Fields the screen does not have are left out. */
+export function recordValues(doc, record, controls = CONTROLS) {
+  const out = {}
+  inputNodes(doc, controls).forEach((node) => {
+    const name = node.props.name
+    const v = record ? record[name] : undefined
+    if (v !== undefined && v !== null) out[name] = node.type === 'date' && typeof v === 'string' ? v.slice(0, 10) : v
+    else if (node.type === 'checkbox') out[name] = false
+  })
+  return out
+}
+
+// ── lists ────────────────────────────────────────────────────────────────
+
+/** The table a list reads: its own, else the one the screen saves to. */
+export function listSource(doc, node) {
+  return (node && node.props && node.props.source) || doc.source || null
+}
+
+/** A list's columns: the ones chosen, else the screen's fields in reading order. */
+export function listColumns(doc, node, controls = CONTROLS) {
+  if (node && Array.isArray(node.props?.columns) && node.props.columns.length) return node.props.columns
+  return inputNodes(doc, controls).map((n) => ({ field: n.props.name, label: n.props.label || n.props.name }))
+}
+
+/** How a stored value reads in a list: a dropdown's name, not its id; Yes/No for a checkbox. */
+export function displayValue(node, value, options) {
+  if (value === undefined || value === null || value === '') return ''
+  if (!node) return typeof value === 'object' ? JSON.stringify(value) : value
+  if (node.type === 'checkbox') return value ? 'Yes' : 'No'
+  if (node.type === 'dropdown') {
+    const opts = node.props.data?.source === 'static' ? node.props.data.options : options
+    const hit = (opts || []).find((o) => sameId(o.id, value))
+    return hit ? hit.name : String(value)
+  }
+  return value
+}