@xeplr/ui-factory 1.2.0 → 1.3.0

package/src/values.js

@@ -46,12 +46,46 @@ export function formSchema(doc, controls = CONTROLS) {
 }
 
 /** Each input's starting value: the caller's, else the control's default. */
+/**
+ * A VALUE WITH A TOKEN IS A BINDING; a plain value is a literal.
+ *
+ * `{params.complaintId}` in a field's default means "whatever this screen was
+ * called with" — the same brace this product uses in a workflow step, a
+ * condition and a report. Nothing is marked on the field: the brace says it.
+ *
+ * Unknown, or called with nothing, resolves to undefined — the field is then
+ * empty and the person fills it in, which is what the same form does when
+ * somebody opens it on its own. A form that will not open is worse than a
+ * question nobody expected.
+ *
+ * Whole-value only. `{params.a}-{params.b}` is not a value a form field takes,
+ * and splicing text is a formula's job, not a form's.
+ */
+export function resolveBinding(value, params) {
+  if (typeof value !== 'string') return value
+  const m = /^\{params\.([A-Za-z_][\w]*)\}$/.exec(value.trim())
+  if (!m) return value
+  return params ? params[m[1]] : undefined
+}
+
+/** Is this what somebody typed, or a reference to an input? */
+export function isBinding(value) {
+  return typeof value === 'string' && /^\{params\.[A-Za-z_][\w]*\}$/.test(value.trim())
+}
+
 export function initialValues(doc, provided = {}, controls = CONTROLS) {
   const out = {}
   inputNodes(doc, controls).forEach((node) => {
     const name = node.props.name
     if (provided[name] !== undefined) out[name] = provided[name]
-    else if (node.props.default !== undefined) out[name] = node.props.default
+    else if (node.props.default !== undefined) {
+      // A default may be a binding to one of the screen's own inputs.
+      const resolved = resolveBinding(node.props.default, provided)
+      if (resolved !== undefined) out[name] = resolved
+      else if (!isBinding(node.props.default)) out[name] = node.props.default
+      else if (node.type === 'checkbox') out[name] = false
+      else if (node.type === 'multiselect') out[name] = []
+    }
     else if (node.type === 'checkbox') out[name] = false
     else if (node.type === 'multiselect') out[name] = []
   })
@@ -98,6 +132,11 @@ export function fieldError(node, value, loadedOptions) {
   const label = p.label || p.name
   const v = p.validation || {}
 
+  // AN IDENTIFIER IS NOT SOMEBODY'S TO FILL IN. The server assigns a code on
+  // first save and the database counts a number, so a rule here would refuse
+  // the very save that produces the value.
+  if (node.type === 'id') return null
+
   if (node.type === 'checkbox') {
     return p.required && value !== true ? `${label} must be ticked` : null
   }
@@ -234,8 +273,28 @@ export function listSource(doc, node) {
 }
 
 /** A list's columns: the ones chosen, else the screen's fields in reading order. */
-export function listColumns(doc, node, controls = CONTROLS) {
+export function listColumns(doc, node, controls = CONTROLS, rows) {
   if (node && Array.isArray(node.props?.columns) && node.props.columns.length) return node.props.columns
+
+  // A LIST OF ANOTHER TABLE HAS NOTHING TO DO WITH THIS SCREEN'S FIELDS.
+  //
+  // A sub-table — this material's characteristics — holds rows of a different
+  // shape entirely, so falling back to this screen's fields shows four empty
+  // columns named after the material. The rows themselves are the only
+  // description to hand, so they are what it reads.
+  const foreign = node && node.props && node.props.source && doc && node.props.source !== doc.source
+  if (foreign) {
+    const first = (rows || []).find((r) => r && typeof r === 'object')
+    if (first) {
+      return Object.keys(first)
+        // Neither is a column anybody asked to see: one is the row's handle,
+        // the other is the record it belongs to, which is the list itself.
+        .filter((k) => k !== 'id' && k !== (node.props.belongsTo || ''))
+        .map((k) => ({ field: k, label: k }))
+    }
+    return []
+  }
+
   return inputNodes(doc, controls).map((n) => ({ field: n.props.name, label: n.props.label || n.props.name }))
 }
 
@@ -299,3 +358,60 @@ export function fromDbValue(node, value) {
   }
   return value
 }
+
+// ── a code people can read out ──────────────────────────────────────────
+//
+// The record's own id is a 25-character key made on save. It is unique,
+// stable and completely unquotable: nobody reads one over the phone, writes
+// one on a form, or finds a complaint by it. So a field can be marked
+// GENERATED, and gets a short code instead — CMP-7K3QF9.
+//
+// RANDOM, not sequential. A counted number (CMP-0001) needs a counter bumped
+// in the same transaction as the insert, or two people saving at once take
+// the same one; and it still shows gaps whenever a save fails after the
+// number was taken, which somebody then has to explain. A random code has
+// neither problem, at the cost of not telling you the fifth from the five
+// hundredth — which is what the record's date is for.
+
+/**
+ * The alphabet, minus the characters people mistake for each other.
+ *
+ * ONE OF EACH PAIR SURVIVES, which is the whole trick: O and I and S are
+ * gone, so 0, 1 and 5 are unambiguous and can stay. Dropping both halves
+ * would cost a third of the alphabet to solve a problem already solved.
+ *
+ * The point of this code is that it survives being read aloud, written down
+ * and typed back in.
+ */
+var CODE_ALPHABET = '23456789ABCDEFGHJKLMNPQRTUVWXYZ'
+
+/** The fields a screen generates a code for. */
+export function codeFields(doc, controls = CONTROLS) {
+  return inputNodes(doc, controls).filter((n) => n.type === 'id' && (n.props || {}).idKind !== 'auto')
+}
+
+/**
+ * The identifiers the DATABASE fills in — a counted number. They are never
+ * sent on an insert: the column is an identity, so mentioning it at all would
+ * be claiming a number nobody chose.
+ */
+export function countedFields(doc, controls = CONTROLS) {
+  return inputNodes(doc, controls).filter((n) => n.type === 'id' && (n.props || {}).idKind === 'auto')
+}
+
+/**
+ * One code. `prefix` is what makes it recognisable at a glance — a complaint
+ * is CMP-…, a purchase order is PO-… — and is optional.
+ *
+ * Six characters from 31 is about 900 million codes, which is not a
+ * guarantee: whoever writes one is expected to check it is free and try
+ * again, which is cheap and has to be done in the database anyway.
+ */
+export function generateCode(prefix, length = 6) {
+  let out = ''
+  for (let i = 0; i < length; i++) {
+    out += CODE_ALPHABET[Math.floor(Math.random() * CODE_ALPHABET.length)]
+  }
+  const head = String(prefix || '').trim().toUpperCase().replace(/[^A-Z0-9]+/g, '')
+  return head ? head + '-' + out : out
+}