@xeplr/ui-factory 1.2.0 → 1.3.0

package/README.md

@@ -197,6 +197,166 @@ import schemaHandler from '@xeplr/schema-handler'          // CommonJS: default
 const clean = schemaHandler.applySchema(formSchema(screen), req.body)   // throws ValidationError listing each field
 ```
 
+## Identifier — the number or code a record is known by
+
+Every record already has a key: 25 characters, made on save, never an
+auto-increment and never a sequence. It is unique, stable and completely
+unquotable — nobody reads one over the phone.
+
+So **Identifier** is a control, in the palette beside Text. A type rather
+than a flag on a text box, because everything about it follows from choosing
+it — the column, who fills it in, and whether it is on the form at all:
+
+| How it is made | column | filled by | on the form |
+|---|---|---|---|
+| **A code** — `CMP-7K3QF9` | `varchar(24) UNIQUE` | the server, on first save | shown, read-only |
+| **A number** — 1, 2, 3 | `integer GENERATED BY DEFAULT AS IDENTITY … UNIQUE` | the database, as the row is inserted | not drawn until it exists |
+
+- **A counted number is not on a new form.** It does not exist until the row
+  does, so there is nothing to show but an empty box — and an empty box that
+  never fills in is a question the form appears to be asking and is not.
+- **A code is random, not counted.** A sequential one needs a counter bumped
+  in the insert's transaction, or two saves take the same number, and it still
+  shows gaps when a save fails after the number is taken. Its alphabet drops
+  O, I and S — one of each confusable pair, so 0, 1 and 5 stay usable: the
+  point of a code is surviving a phone call.
+- **Assigned by the server**, checked for a clash inside the insert's own
+  transaction — random is not unique, and a code that was free a moment ago is
+  not a promise.
+- **Neither ever changes.** Both are left out of an update entirely, not
+  cleared: a record whose reference changes is a reference nobody can use.
+- **Never demanded.** A rule on an identifier would refuse the very save that
+  produces it. A value that arrives with the record — an import carrying real
+  numbers — is kept, which is why the identity is `BY DEFAULT` and not
+  `ALWAYS`.
+
+`GENERATED BY DEFAULT AS IDENTITY` is built on the **server**: the browser
+sends a screen document and never SQL. `tableSchema.js` is part of
+`@xeplr/ui-factory/model`, which `@xeplr/factory` imports in Node — sharing
+the rules is not shipping SQL to a browser.
+
+## A sub-table: rows that belong to one record
+
+This material's characteristics, this order's lines. Put a **List** on the
+form and give it two things:
+
+```
+Records from   material_characteristics   [ New table… ]
+Belonging to   materialId
+```
+
+**The link is what makes it a sub-table.** Without it, a list of another
+table shows every row in the app and **New** saves a row belonging to
+nothing. With it:
+
+- the grid shows only rows whose `materialId` is this material — and **none**
+  while the record is unsaved, because a record that does not exist yet owns
+  nothing, and showing the whole table there is how somebody edits another
+  record's lines;
+- **New** hands the child screen this material's id, as `params` — the same
+  mechanism a flow's Screen step uses — so the field is filled in and hidden,
+  and nobody is asked which material they are adding a line to.
+
+**New table…** makes the child there and then — two screens, published, with
+the link column on them and declared as an input — and **opens its designer
+over the page**, because a sub-table is made for the fields it will hold and
+`Name` / `Value` are only a guess at those. Publishing in there sets this
+list's columns and closes it; closing without publishing leaves a working
+table with the two fields it was made with.
+
+It sets *Records from* and *Belonging to* together, because a table without
+its link is a list of everybody's rows and a link without a table is nothing
+— neither half is a state worth being able to reach. The table list is
+re-fetched at the same time, or the picker would be blank for a table made a
+moment ago, and a picker whose value is not among its options shows nothing
+at all.
+
+**Its columns follow its table.** A list of another table is described by
+that table's rows, not by the screen it sits on — offering the material's
+fields for a list of characteristics ticks four columns that are blank in
+every row. Changing *Records from* clears the chosen columns and the link,
+because a field name from the old table is a header over an empty column, and
+leaving it there reads as the designer not having noticed the change.
+
+**A list is not a dropdown.** Its rows are records people create, so there is
+no "typed list" alternative the way there is for a dropdown's options. If
+what you want is *tags* — several values picked from a fixed set — that is a
+**Multi-select** pointing at a master, and the chosen ids live in one column
+of the record. Making it a sub-table means a two-table design for what is
+really one column.
+
+## Masters — the lists the rest of the app points at
+
+Departments, statuses, countries, categories. Mark a form as a master in its
+design (select nothing on the canvas → **This is a master**), and say what a
+picker should show for one of its records:
+
+```js
+{ master: true, labelField: 'name' }     // on the form's own document
+```
+
+**Made, not designed.** Every application repeats the same three things —
+a name, an order of its own, and the master it belongs to — so a master is
+created outright rather than drawn:
+
+```js
+import { createMaster } from '@xeplr/ui-factory'
+
+await createMaster(factory, { name: 'States', parent: { table: 'countries', label: 'Country' } })
+// → states_edit + states_list, marked as a master, published
+```
+
+- **Name** is required: a master row with no name is a blank line in every
+  dropdown that points at it.
+- **Sort order** is not: Low / Medium / High is never alphabetical, but most
+  lists are fine, and a number somebody must invent for every row is a tax on
+  adding one.
+- **Belongs to** is a dropdown on the parent master, required when there is
+  one — a state in no country is a row nothing can use. A master is never
+  offered as its own parent.
+
+It is **published** on creation, which is the one place doing that on
+somebody's behalf is right: a master that is a draft has no table, so nothing
+can point at it and nobody can add a row, which is all a master is for.
+
+Named in the plural, stored in the singular: *Departments* makes the entity
+`department` and the table `departments`. Without that step `entityNames`
+would make `departmentses`, which is noticed only once the table exists and
+then cannot be renamed.
+
+**A flag on a form, not a kind of form.** A master has a table, a list, an
+edit screen and permissions like anything else; a separate type would be two
+things that behave the same until they do not, and every feature after it
+would have to ask which one it is holding. The flag adds a fact; a type adds
+a fork.
+
+`labelField` is said once, here, rather than on every dropdown that points at
+this form — thirty dropdowns should not each be told that a department is
+shown by its name.
+
+`useScreenSource` returns `masters` alongside `screens`: one entry per FORM
+(`{ key, name, labelField, edit, list, source }`), gathered by `masterForms`,
+so an app's admin section renders a list and groups nothing itself. That is
+what `@xeplr/cli` generates as Configure UI → **Masters**.
+
+They are gathered in the admin section rather than scattered through the side
+rail because that is what they are — reference data somebody maintains
+occasionally. The rail stays for the work.
+
+**And they are what a dropdown offers first.** A field's *where its options
+come from* now reads:
+
+```
+Masters        Departments, Statuses, Countries      ← named, first
+Other tables   complaints, employees, pod_items      ← still there, below
+```
+
+`/factory/tables` marks and names them (`@xeplr/factory`'s
+`tablesForPicker`), so the picker groups rather than guesses. Two `<optgroup>`s
+in a plain `<select>`, not a combobox: typing jumps to an option in every
+browser, which is the searching anybody wants here, and a widget of our own
+would have to reimplement the keyboard to match.
+
 ## Your screens, inside someone else's designer
 
 `@xeplr/ui-workflow`'s flow designer has a **Screen** step, and it asks its
@@ -516,6 +676,8 @@ The control whose properties are open, the step a stepper is open at, and the fl
 
 Styles are namespaced `.xeplr-factory-*` and read `@xeplr/ui-account`'s theme variables (theme.css), each with a light fallback: `--xeplr-accent`, `--xeplr-accent-text`, `--xeplr-text-primary`, `--xeplr-text-secondary`, `--xeplr-border-primary`, `--xeplr-bg-primary` (the builder's plane), `--xeplr-bg-tertiary` (sheets, panels, popups), `--xeplr-bg-hover`, `--xeplr-bg-overlay`, `--xeplr-input-bg`, `--xeplr-input-border`, `--xeplr-success`, `--xeplr-warning`, `--xeplr-danger`. The screen, builder and popup follow the app's light or dark theme with the @xeplr/ui-table inside them — never a white sheet in a dark app.
 
+Every dropdown the factory draws — on a screen, in the builder's panels, in the flow designer — has the factory's own ∨ arrow, set in from the right edge with room kept for it, in `--xeplr-text-secondary`. It is styled here, inside the factory's own containers, so an app gets it without adding CSS of its own. A dropdown's **Background** is applied as a background colour, so it never removes the arrow.
+
 Buttons, steps and list actions all show hover, a visible press, and a keyboard-only focus ring.
 
 ## Try it

package/bin/xeplr-factory.js

@@ -151,7 +151,8 @@ switch (cmd) {
     Object.values(CONTROLS).forEach((c) => {
       process.stdout.write(`${c.type.padEnd(9)} ${c.label}${c.input ? ` — value: ${c.valueType || 'option id'}` : ''}\n`)
       process.stdout.write(`          props: ${c.props.join(', ')}\n`)
-      if (c.validation.length) process.stdout.write(`          validation: ${c.validation.join(', ')}\n`)
+      // Not every control has rules to break — an identifier has none.
+      if (c.validation && c.validation.length) process.stdout.write(`          validation: ${c.validation.join(', ')}\n`)
       if (c.styles && c.styles.length) process.stdout.write(`          style: ${c.styles.join(', ')}\n`)
     })
     break

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xeplr/ui-factory",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Design data-entry screens on @xeplr/ui-canvas, save them as JSON, run them as auto-saving forms with lists of saved records — built for Claude to draft and people to refine",
   "type": "module",
   "main": "src/index.js",

package/src/controls.js

@@ -99,6 +99,8 @@ const FIELD_BASICS = (extra) => ({
   ]
 })
 
+
+
 const PLACEHOLDER = { path: 'props.placeholder', label: 'Placeholder', type: 'text' }
 
 /**
@@ -237,6 +239,57 @@ export const CONTROLS = {
     ]
   },
 
+  /**
+   * AN IDENTIFIER — the number or code this record is known by.
+   *
+   * A TYPE, not a flag on a text box, because everything about it follows
+   * from choosing it: what the column is, who fills it in, and whether it is
+   * on the form at all. Drop it on, say how it is made, and the rest is
+   * decided.
+   *
+   *   auto    the database counts — 1, 2, 3. Nobody types it and nobody sees
+   *           it while the record is new, because it does not exist yet: the
+   *           database assigns it as the row is inserted. Not drawn on a live
+   *           form at all.
+   *   code    the server assigns CMP-7K3QF9 on the first save. Shown, because
+   *           this is the one people quote to each other — and read-only,
+   *           because changing it later would break every quote of it.
+   *
+   * The record's own 25-character key is untouched and still what everything
+   * points at. This is the identifier PEOPLE use.
+   */
+  id: {
+    type: 'id',
+    label: 'Identifier',
+    group: 'Inputs',
+    input: true,
+    valueType: 'string',
+    defaultSize: { w: 0.28, h: 0.08 },
+    defaults: { label: 'Reference', idKind: 'code' },
+    props: ['name', 'label', 'idKind', 'codePrefix', 'style'],
+    // Nothing to break: nobody types an identifier, so there is no rule it
+    // could fail. Declared anyway, because every control answers the same
+    // questions (see the contract in test/model.test.js).
+    validation: [],
+    styles: INPUT_STYLES,
+    properties: [
+      {
+        key: 'field',
+        title: 'Field',
+        fields: [
+          { path: 'props.label', label: 'Label', type: 'text' },
+          { path: 'props.name', label: 'Field name', type: 'text', help: 'The key this value is saved under' },
+          { path: 'props.idKind', label: 'How it is made', type: 'select', options: [
+            { value: 'code', label: 'A code — CMP-7K3QF9' },
+            { value: 'auto', label: 'A number, counted by the database — 1, 2, 3' }
+          ], help: 'A counted number is never shown on the form: it exists only once the row does.' },
+          { path: 'props.codePrefix', label: 'Starts with', type: 'text', help: 'CMP → CMP-7K3QF9. Codes only, and optional.' }
+        ]
+      },
+      ...styleGroups(INPUT_STYLES)
+    ]
+  },
+
   date: {
     type: 'date',
     label: 'Date',
@@ -488,7 +541,7 @@ CONTROLS.list = {
   // PAGE of the app's own (openIn: 'page', which calls onOpenRecord and lets
   // the app navigate). Without one, Edit opens the row in this screen's own
   // fields (a list on a form).
-  props: ['title', 'source', 'editScreen', 'openIn', 'columns', 'pageSize', 'actions', 'style'],
+  props: ['title', 'source', 'belongsTo', 'editScreen', 'openIn', 'columns', 'pageSize', 'actions', 'style'],
   validation: [],
   styles: ['fontFamily', 'fontSize', 'color', 'background', 'borderColor', 'borderWidth', 'borderRadius'],
   properties: [
@@ -497,7 +550,14 @@ CONTROLS.list = {
       title: 'List',
       fields: [
         { path: 'props.title', label: 'Title', type: 'text' },
-        { path: 'props.source', label: 'Records from', type: 'table', help: 'Blank → the table this screen saves to' },
+        { path: 'props.source', label: 'Records from', type: 'listTable', help: 'Blank → the table this screen saves to' },
+        // THE LINK BACK. A sub-table on a form — this material's
+        // characteristics, this order's lines — is rows of another table that
+        // belong to THIS record. Without it a list of another table shows
+        // every row in the app, and New saves a row belonging to nothing.
+        { path: 'props.belongsTo', label: 'Belonging to', type: 'text',
+          help: 'The column on those records that points back at this one, e.g. materialId. ' +
+                'It is filled in automatically on New and never shown.' },
         { path: 'props.editScreen', label: 'Edit in', type: 'screen', help: 'The screen Edit and New open' },
         { path: 'props.openIn', label: 'Opens in', type: 'select', options: [
           { value: 'popup', label: 'A popup' },

package/src/designs/BuilderSample.jsx

@@ -3,6 +3,8 @@ import { XeplrCanvas } from '@xeplr/ui-canvas'
 import ControlView from './ControlView.jsx'
 import Palette, { DRAG_TYPE } from './Palette.jsx'
 import PropertyPanel from './PropertyPanel.jsx'
+import { ScreenEditorSample } from './ScreenEditorSample.jsx'
+import { useFactoryBuilder } from '../useFactoryBuilder.js'
 import { screenStyle } from './styles.js'
 import { presetFor } from '../presets.js'
 
@@ -118,6 +120,37 @@ export default function BuilderSample({ ctrl, renderPreview, className, style })
         )}
       </header>
 
+      {/* THE CHILD, DESIGNED WHERE IT WAS MADE.
+          A sub-table is made for the fields it will hold, and the two it is
+          created with are a guess at those. Going to find the new form
+          afterwards means going with the thought already lost. Publishing in
+          here sets this list's columns and closes it. */}
+      {ctrl.designingChild && screenApi && (
+        <div className="xeplr-factory-modal-backdrop" onMouseDown={() => ctrl.closeChild(null)}>
+          <div
+            className="xeplr-factory-modal xeplr-factory-modal--wide"
+            role="dialog"
+            aria-modal="true"
+            aria-label={'Design ' + ctrl.designingChild.name}
+            onMouseDown={(e) => e.stopPropagation()}
+          >
+            <header className="xeplr-factory-modal-head">
+              <strong>{ctrl.designingChild.name}</strong>
+              <span className="xeplr-factory-modal-spacer" />
+              <button type="button" className="xeplr-factory-secondary" onClick={() => ctrl.closeChild(null)}>Done</button>
+            </header>
+            <div className="xeplr-factory-modal-body">
+              <ScreenEditorSample
+                api={screenApi}
+                Builder={NestedBuilder}
+                screenKey={ctrl.designingChild.screenKey}
+                onDone={(screen) => ctrl.closeChild(screen)}
+              />
+            </div>
+          </div>
+        </div>
+      )}
+
       {ctrl.publishResult && ctrl.publishResult.confirm && (
         <div className="xeplr-factory-publish is-confirm" role="alertdialog" aria-label="Confirm changes to saved data">
           <div className="xeplr-factory-confirm-text">
@@ -240,7 +273,20 @@ export default function BuilderSample({ ctrl, renderPreview, className, style })
             tables={ctrl.tables}
             screens={ctrl.screens}
             lockedNames={ctrl.lockedNames}
-            onChange={(path, value) => ctrl.setProperty(ctrl.selectedNode.id, path, value)}
+            onChange={(path, value) => (
+              // A list's table is not an ordinary property: changing it makes
+              // the chosen columns and the link meaningless, and leaving them
+              // behind is what reads as the panel not noticing. See
+              // setListSource.
+              ctrl.selectedNode.type === 'list' && path === 'props.source'
+                ? ctrl.setListSource(ctrl.selectedNode.id, value)
+                : ctrl.setProperty(ctrl.selectedNode.id, path, value)
+            )}
+            // A list pointed at a table that does not exist yet can make one
+            // — with the link back to this screen's record already on it —
+            // so nobody has to leave the designer, go and build a form, and
+            // come back to remember what they were doing.
+            onMakeChildTable={ctrl.makeChildTable}
             onConvert={(target) => ctrl.convertControl(ctrl.selectedNode.id, target)}
             hint={ctrl.selectedNode ? ctrl.hints.find((h) => h.nodeId === ctrl.selectedNode.id) : null}
             onScreenChange={ctrl.setScreen}

package/src/designs/ControlView.jsx

@@ -73,6 +73,41 @@ const TEXT_INPUT = {
   url: { type: 'url', autoComplete: 'url', inputMode: 'url' }
 }
 
+/**
+ * AN IDENTIFIER — the number or code this record is known by.
+ *
+ * Never typed, either way, so there is nothing to type into. What differs is
+ * whether it is on the form at all:
+ *
+ *   code   shown. This is the one people quote to each other, so they need to
+ *          see it — read-only, because changing it later breaks every quote.
+ *   auto   NOT SHOWN on a live form. The database assigns it as the row is
+ *          inserted, so on a new record there is nothing to show but an empty
+ *          box, and an empty box that never fills in is a question the form
+ *          appears to be asking and is not. Once the row exists it is worth
+ *          seeing, so a saved record shows it.
+ *
+ * On the DESIGN canvas both are drawn, or there would be nothing to select
+ * and nothing to configure.
+ */
+function IdView({ node, p, value, design }) {
+  const counted = p.idKind === 'auto'
+  if (counted && !design && (value === undefined || value === null || value === '')) return null
+
+  return (
+    <Field node={node} p={p}>
+      <input
+        className="xeplr-factory-input"
+        type="text"
+        value={value ?? ''}
+        readOnly
+        disabled
+        placeholder={counted ? 'Numbered when saved' : 'Given when saved'}
+      />
+    </Field>
+  )
+}
+
 function TextView({ node, p, value, error, onChange, onBlur, disabled }) {
   const kind = TEXT_INPUT[p.inputType] || { type: 'text' }
   return (
@@ -395,6 +430,7 @@ function ListControl({ node, design, list }) {
 }
 
 export const VIEWS = {
+  id: IdView,
   text: TextView,
   textarea: TextareaView,
   number: NumberView,

package/src/designs/ListView.jsx

@@ -11,7 +11,9 @@ import { boxStyle, fieldStyle } from './styles.js'
 
 export default function ListView({ node, doc, design, list, onEdit, onDelete, onNew, currentId, recordKey = 'id', canDelete, fieldNodes, optionsFor, extraActions = [] }) {
   const p = node.props || {}
-  const columns = listColumns(doc, node)
+  // The rows are passed in because a list of ANOTHER table has no other
+  // description of itself — see listColumns.
+  const columns = listColumns(doc, node, undefined, (list && list.rows) || [])
   const actions = p.actions || ['new', 'edit', 'delete']
   const style = { ...fieldStyle(p.style), ...boxStyle(p.style) }