@xeplr/ui-factory 1.0.5 → 1.0.7

package/AUTHORING.md

@@ -168,15 +168,20 @@ Each field:
 | key | meaning |
 |---|---|
 | `label` | **required** for inputs — shown above the field |
-| `type` | `text` (default), `textarea`, `number`, `date`, `checkbox`, `dropdown`, or `label` for a section heading |
+| `type` | `text` (default), `textarea`, `number`, `date`, `datetime`, `checkbox`, `dropdown`, `radio`, `multiselect`, `file`, `stepper`, or `label` for a section heading |
 | `name` | the key the value is saved under; defaults to the label in camelCase (`"Date of birth"` → `dateOfBirth`) |
 | `required` | `true` to require a value (a checkbox must be ticked) |
 | `placeholder` | text, textarea, number, dropdown |
 | `default` | starting value — a string, a number, `true`/`false`, or a date as `"YYYY-MM-DD"` |
 | `validation` | see below |
 | `width` | `"full"` to take the whole row in a two-column form (textareas and labels always do) |
-| `options` | dropdown: `["Full time", "Part time"]` (ids are made from the names: `full_time`) or `[{ "id": "ft", "name": "Full time" }]` |
-| `table` | dropdown: read options from this table in the app's database |
+| `options` | dropdown, radio, multiselect: `["Full time", "Part time"]` (ids are made from the names: `full_time`) or `[{ "id": "ft", "name": "Full time" }]` |
+| `table` | dropdown, radio, multiselect: read options from this table in the app's database |
+| `layout` | radio, multiselect: `"vertical"` (default) or `"horizontal"` |
+| `accept` | file: the extensions it takes, e.g. `".pdf,.docx"` |
+| `steps` | stepper: `["Connect", "Transform", "Review"]` — at least two |
+| `step` | which step this field is on: the step's label, or its number from 1. Needs a `stepper` earlier in `fields`; without a `step` a field shows on every step |
+| `maxSize` | file: the largest file in megabytes (default 10) |
 | `text`, `variant` | `label` only — `variant` is `heading`, `subheading` (default for a section) or `text` |
 | `style` | how it looks — see Styles |
 
@@ -188,7 +193,9 @@ Each field:
 | `textarea` | `minLength`, `maxLength` |
 | `number` | `min`, `max`, `integer` |
 | `date` | `min`, `max` — as `"YYYY-MM-DD"` |
-| `checkbox`, `dropdown` | none (use `required`) |
+| `datetime` | `min`, `max` — as `"YYYY-MM-DDTHH:MM"` |
+| `multiselect` | `minItems`, `maxItems` — how many may be chosen |
+| `checkbox`, `dropdown`, `radio`, `file` | none (use `required`) |
 
 Anything else is rejected, with the list of what is allowed.
 
@@ -236,10 +243,14 @@ A dropdown **always saves an `id` and shows a `name`.**
 | notes, description, address, comments | `textarea` |
 | amount, salary, quantity, age | `number` (`integer: true` for counts) |
 | a date — birth, start, due | `date` |
+| an appointment, a deadline with a time, when something happened | `datetime` |
 | yes/no, agree, active, remote | `checkbox` |
-| one of a known set | `dropdown` with `options` |
+| one of a known set | `dropdown` with `options` — a `radio` group when there are two or three and they should all be visible |
 | one of the app's records | `dropdown` with `table` |
+| several of a set — tags, skills, days | `multiselect` |
+| a document, a contract, a spreadsheet, a photo | `file` with `accept` (`".pdf,.docx"`) |
 | a section title between groups | `{ "type": "label", "text": "…", "variant": "subheading" }` |
+| a long form people work through in stages | a `stepper`, then `step` on each field |
 
 Keep labels short and in sentence case ("Start date", not "START DATE:"). Mark only what the request needs as required.
 

package/README.md

@@ -15,11 +15,16 @@ It is built to work with Claude: ask for *"a form for employees with name, email
 
 ```sh
 npx xeplr-factory screens employee.entity.json -o src/screens/employee
-#  employee-list.screen.json   EmployeeList.jsx
-#  employee-edit.screen.json   EditEmployee.jsx
-#  employee.hooks.js           server hooks for its records: save / get / delete × before / after / error / override
+#  employee-list.screen.json   EmployeeList.jsx     the list page — uses EditEmployee.jsx's hooks
+#  employee-edit.screen.json   EditEmployee.jsx     the form page, holding the FRONT-END hooks (EmployeeHooks extends FactoryHooks)
+#  employee.hooks.js           SERVER hooks: save / get / delete × before / after / error / override
+#  employee.model.js           SERVER model: EmployeeModel extends FactoryModel — getters / setters for values
 ```
 
+`--no-pages` leaves out the two `.jsx` (for an app whose pages live elsewhere). `--force` replaces only the screen JSON: the pages, hooks and model are your code and are always kept.
+
+**Rules:** records live in real tables, never JSON · a form's **key** (`employee`) names its screens and table and never changes once published; its **label** (the screens' name) is renamed any time · rules that must hold go in server hooks, never front-end hooks.
+
 See [examples/](./examples) for exactly what it writes.
 
 (The package name on npm is `@xeplr/ui-factory` — the GitHub repo and folder are named `xeplr-ui-factory`.)
@@ -82,6 +87,7 @@ import { FactoryScreen } from '@xeplr/ui-factory'
   fetchRecord={async ({ screen, id }) => api.record(screen, id)}   // optional: Edit loads the record fresh
   onDelete={async ({ id, source }) => api.remove(source, id)}
   fetchOptions={async ({ table }) => api.options(table)}
+  uploadFile={async (file, { screen, field }) => api.upload(file, screen, field)}  // a file field: → { path }
   screens={{ employee_edit: editScreen }}             // what a list's Edit / New open in a popup
 />
 ```
@@ -90,7 +96,23 @@ import { FactoryScreen } from '@xeplr/ui-factory'
 
 If `onSave` throws an error with `fields: [{ field, message }]` (what `createFactoryApi` does with the server's 422 — a rule, or a hook's `reject`), each message shows on its field until that field is changed.
 
-Values arrive typed: numbers as numbers, checkboxes as booleans, dates as `"YYYY-MM-DD"`, and a dropdown as the option's own `id` (a table's numeric id stays a number).
+Values arrive typed: numbers as numbers, checkboxes as booleans, dates as `"YYYY-MM-DD"`, a date and time as `"YYYY-MM-DDTHH:MM"`, a dropdown or radio group as the option's own `id` (a table's numeric id stays a number), a multi-select as an **array** of ids, and a file as the stored file's **path**.
+
+### Where each value is kept
+
+A record is columns in a real table, never JSON — so the two types that are not
+one scalar have a rule of their own:
+
+* **Multi-select** — every chosen id in ONE `text` column, joined by commas. An
+  option id may therefore not contain a comma; the checker refuses one that
+  does. `toDbValue` / `fromDbValue` do the conversion, and both the browser and
+  the server use them, so it is written once.
+* **File** — the column holds the path the upload answered with, not the file.
+  The file itself is stored by `@xeplr/factory` and read back through its
+  authenticated route; nothing is ever served without a check.
+* **Date and time** — a `timestamp` column, read back as text so no timezone can
+  move the moment. A `date` column may be widened to `timestamp` on publish
+  (the day becomes midnight); the reverse is refused, as it would lose the time.
 
 ### Front-end hooks
 
@@ -154,16 +176,45 @@ const clean = schemaHandler.applySchema(formSchema(screen), req.body)   // throw
 | `textarea` | string | `minLength`, `maxLength` |
 | `number` | number | `min`, `max`, `integer` |
 | `date` | `"YYYY-MM-DD"` | `min`, `max` |
+| `datetime` | `"YYYY-MM-DDTHH:MM"` | `min`, `max` |
 | `checkbox` | boolean | `required` = must be ticked |
 | `dropdown` | option id | — |
+| `radio` | option id | — |
+| `multiselect` | array of option ids | `minItems`, `maxItems` |
+| `file` | the stored file's path | `accept` (extensions), `maxSize` (MB) |
+| `stepper` | — | a journey across the top; every other control says which step it is on |
 | `label` | — | text with a heading, subheading or text preset |
 | `list` | — | saved records, with New / Edit / Delete |
 
 Every control also takes `style` — see [AUTHORING.md](./AUTHORING.md#styles) for the keys. Sizes are pixels at the screen's design `width` (default 800): a screen is shown at that size, never stretched, and scaled down only on a narrower display.
 
-### Dropdown options
+### Steps
+
+A **stepper** turns one screen into several: a bar of steps across the top, and
+one step's controls showing at a time. Type the steps as one line — `Connect,
+Transform, Review` — and **click a step on the canvas to build it**: what you
+drop while it is open belongs to it, and the canvas shows only that step. A
+control can be put on *every* step instead (a heading, a list), which is what
+one with no step means.
+
+```json
+{ "id": "n7", "type": "stepper", "props": { "steps": [{ "key": "connect", "label": "Connect" }, { "key": "review", "label": "Review" }] } }
+{ "id": "n8", "type": "text", "step": { "of": "n7", "index": 0 }, "props": { "name": "host", "label": "Host" } }
+```
+
+`step` sits on the **node**, beside `x`/`y`/`w`/`h` — not in `props`. The
+document stays flat, so a control is still moved, styled, checked and saved
+exactly as before; the step only decides when it is on screen. Renaming a step
+keeps its `key`, so the controls on it stay where they are.
+
+**A step is not a separate form.** Every field is a column, is checked, and is
+saved, whichever step is showing — a screen still saves itself as it is filled
+in. **Next** holds at a step whose own fields are not filled in, and says which,
+rather than moving on and leaving a problem behind where nobody is looking.
+
+### Options: dropdown, radio group, multi-select
 
-A dropdown **always saves an `id` and shows a `name`**, from either source:
+All three **save an `id` and show a `name`**, from either source:
 
 ```json
 { "source": "static", "options": [{ "id": "ft", "name": "Full time" }, { "id": "pt", "name": "Part time" }] }
@@ -196,7 +247,7 @@ const screen = screenFromSpec({
 It lays the fields out as a tidy one- or two-column form and returns a checked document. The same is available on the command line:
 
 ```sh
-npx xeplr-factory screens entity.json -o dir   # an entity → list + edit screens and pages
+npx xeplr-factory screens entity.json -o dir   # an entity → list + edit screens, pages, server hooks + model  (--no-pages, --force)
 npx xeplr-factory migration edit.screen.json   # preview the SQL Publish would run
 npx xeplr-factory generate spec.json -o screen.json   # one screen from a spec
 npx xeplr-factory validate screen.json      # every problem, with its path
@@ -248,9 +299,10 @@ src/
   validateDocument.js    ─ the document checker
   values.js              ─ values, validation, autosave readiness, records and list columns, formSchema
   generate.js            ─ screenFromSpec, screensFromSpec (list + edit), entity names
-  scaffold.js            ─ an entity → its screen JSON, .jsx pages and hooks stub
+  scaffold.js            ─ an entity → its screen JSON, .jsx pages (with front-end hooks), server hooks + model stubs
+  hooks.js               ─ FactoryHooks: get / save / delete / actions — extend and call super
   tableSchema.js         ─ a form → its table; the publish plan (create / add / widen / confirmed drops)
-  remote.js              ─ createFactoryApi: the calls to @xeplr/factory's routes
+  remote.js              ─ createFactoryApi({ fetch }): the calls to @xeplr/factory's routes — fetch may be window.fetch or @xeplr/ui-account's authFetch (which returns parsed bodies); includes createEntity({ key, label })
   model.js               ─ everything above, React-free
   useFactoryBuilder.js   ─ builder controller
   useFactoryScreen.js    ─ screen controller

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xeplr/ui-factory",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "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

@@ -101,6 +101,60 @@ const FIELD_BASICS = (extra) => ({
 
 const PLACEHOLDER = { path: 'props.placeholder', label: 'Placeholder', type: 'text' }
 
+/**
+ * A multi-select keeps its chosen ids in ONE text column, joined by this. An
+ * option id may therefore not contain it — the document checker refuses one
+ * that does, rather than letting a value split itself in two on the way back.
+ */
+export const MULTI_SEPARATOR = ','
+
+/** The controls whose value is chosen from options — static, or a table's rows. */
+export const CHOICE_TYPES = ['dropdown', 'radio', 'multiselect']
+
+/** How a group of options is laid out — one per line, or side by side. */
+export const LAYOUTS = ['vertical', 'horizontal']
+
+const LAYOUT = { path: 'props.layout', label: 'Arrangement', type: 'select', options: [
+  { value: 'vertical', label: 'One per line' },
+  { value: 'horizontal', label: 'Side by side' }
+] }
+
+/**
+ * What a file field may accept, as EXTENSIONS. Extensions, not MIME types,
+ * because that is how people describe a file ("a PDF", "a spreadsheet") and
+ * how the server checks it — a browser's reported type is the sender's word
+ * for it, and can be anything.
+ */
+export const FILE_KINDS = {
+  document: { label: 'Documents', accept: '.pdf,.doc,.docx,.odt,.rtf,.txt' },
+  pdf: { label: 'PDF only', accept: '.pdf' },
+  spreadsheet: { label: 'Spreadsheets', accept: '.xls,.xlsx,.csv,.ods' },
+  image: { label: 'Images', accept: '.png,.jpg,.jpeg,.gif,.webp,.svg' },
+  any: { label: 'Any of the above', accept: '.pdf,.doc,.docx,.odt,.rtf,.txt,.xls,.xlsx,.csv,.ods,.png,.jpg,.jpeg,.gif,.webp,.svg' }
+}
+
+/** An extension list as one string → the same list, cleaned and lower-cased. */
+export function acceptList(accept) {
+  return String(accept || '')
+    .split(',')
+    .map((s) => s.trim().toLowerCase())
+    .filter(Boolean)
+    .map((s) => (s.startsWith('.') ? s : '.' + s))
+}
+
+/**
+ * A STEP a control belongs to, on the node itself (beside x/y/w/h/z) rather
+ * than in its props: it is not something the control does, it is where the
+ * control is. A node with no `step` is on the screen whatever step is showing
+ * — a heading, a list, the stepper itself.
+ *
+ *   node.step = { of: '<the stepper node's id>', index: 0 }
+ */
+export const STEP_LIMIT = 12
+
+/** Largest upload a file field may take, in bytes. */
+export const MAX_FILE_MB = 200
+
 export const CONTROLS = {
   text: {
     type: 'text',
@@ -248,6 +302,143 @@ export const CONTROLS = {
     ]
   },
 
+  radio: {
+    type: 'radio',
+    label: 'Radio group',
+    group: 'Inputs',
+    input: true,
+    // One of the options' ids — a table's may be numbers, like a dropdown.
+    valueType: null,
+    defaultSize: { w: 0.44, h: 0.14 },
+    defaults: { label: 'Choose one', data: { source: 'static', options: [] }, layout: 'vertical' },
+    props: ['name', 'label', 'required', 'default', 'data', 'layout', 'style'],
+    validation: [],
+    styles: INPUT_STYLES.filter((k) => k !== 'textAlign'),
+    properties: [
+      FIELD_BASICS(),
+      {
+        key: 'data',
+        title: 'Options',
+        fields: [
+          { path: 'props.data', label: 'Options come from', type: 'dataSource' },
+          LAYOUT
+        ]
+      },
+      ...styleGroups(INPUT_STYLES.filter((k) => k !== 'textAlign'))
+    ]
+  },
+
+  multiselect: {
+    type: 'multiselect',
+    label: 'Multi-select',
+    group: 'Inputs',
+    input: true,
+    // Several ids. Stored in ONE text column, joined by commas — which is why
+    // an option's id may not contain one (the document checker says so).
+    valueType: 'array',
+    defaultSize: { w: 0.44, h: 0.18 },
+    defaults: { label: 'Choose any', data: { source: 'static', options: [] }, layout: 'vertical' },
+    props: ['name', 'label', 'required', 'data', 'layout', 'validation', 'style'],
+    validation: ['minItems', 'maxItems'],
+    styles: INPUT_STYLES.filter((k) => k !== 'textAlign'),
+    properties: [
+      FIELD_BASICS(),
+      {
+        key: 'data',
+        title: 'Options',
+        fields: [
+          { path: 'props.data', label: 'Options come from', type: 'dataSource' },
+          LAYOUT
+        ]
+      },
+      {
+        key: 'validation',
+        title: 'Validation',
+        fields: [
+          { path: 'props.validation.minItems', label: 'Choose at least', type: 'number' },
+          { path: 'props.validation.maxItems', label: 'Choose at most', type: 'number' }
+        ]
+      },
+      ...styleGroups(INPUT_STYLES.filter((k) => k !== 'textAlign'))
+    ]
+  },
+
+  datetime: {
+    type: 'datetime',
+    label: 'Date & time',
+    group: 'Inputs',
+    input: true,
+    valueType: 'date',
+    defaultSize: { w: 0.44, h: 0.08 },
+    defaults: { label: 'Date and time' },
+    props: ['name', 'label', 'required', 'default', 'validation', 'style'],
+    validation: ['min', 'max'],
+    styles: INPUT_STYLES,
+    properties: [
+      FIELD_BASICS([{ path: 'props.default', label: 'Default value', type: 'datetime' }]),
+      {
+        key: 'validation',
+        title: 'Validation',
+        fields: [
+          { path: 'props.validation.min', label: 'Earliest', type: 'datetime' },
+          { path: 'props.validation.max', label: 'Latest', type: 'datetime' }
+        ]
+      },
+      ...styleGroups(INPUT_STYLES)
+    ]
+  },
+
+  file: {
+    type: 'file',
+    label: 'File upload',
+    group: 'Inputs',
+    input: true,
+    // The value is the stored file's path, as the upload answered with it.
+    valueType: 'string',
+    defaultSize: { w: 0.44, h: 0.1 },
+    defaults: { label: 'File', accept: FILE_KINDS.document.accept, maxSize: 10 },
+    props: ['name', 'label', 'required', 'accept', 'maxSize', 'style'],
+    validation: [],
+    styles: INPUT_STYLES.filter((k) => k !== 'textAlign'),
+    properties: [
+      FIELD_BASICS(),
+      {
+        key: 'file',
+        title: 'File',
+        fields: [
+          { path: 'props.accept', label: 'Allowed types', type: 'accept', help: 'Extensions, comma separated — the server refuses anything else' },
+          { path: 'props.maxSize', label: 'Largest size (MB)', type: 'number', min: 1, max: 200 }
+        ]
+      },
+      ...styleGroups(INPUT_STYLES.filter((k) => k !== 'textAlign'))
+    ]
+  },
+
+  stepper: {
+    type: 'stepper',
+    label: 'Stepper',
+    group: 'Content',
+    input: false,
+    defaultSize: { w: 0.92, h: 0.09 },
+    // Steps are typed as one line — "Connect, Transform, Review" — because
+    // that is how someone describes them. Each becomes { key, label }.
+    defaults: { steps: [{ key: 'step_1', label: 'Step 1' }, { key: 'step_2', label: 'Step 2' }], showNumbers: true },
+    props: ['steps', 'showNumbers', 'style'],
+    validation: [],
+    styles: ['fontFamily', 'fontSize', 'fontWeight', 'color', 'background', 'borderColor', 'borderWidth', 'borderRadius'],
+    properties: [
+      {
+        key: 'steps',
+        title: 'Steps',
+        fields: [
+          { path: 'props.steps', label: 'Steps', type: 'steps', help: 'One line, separated by commas. Click a step on the canvas to build it.' },
+          { path: 'props.showNumbers', label: 'Number the steps', type: 'toggle' }
+        ]
+      },
+      ...styleGroups(['fontFamily', 'fontSize', 'fontWeight', 'color', 'background', 'borderColor', 'borderWidth', 'borderRadius'])
+    ]
+  },
+
   label: {
     type: 'label',
     label: 'Label',

package/src/designs/BuilderSample.jsx

@@ -117,11 +117,36 @@ export default function BuilderSample({ ctrl, renderPreview, className, style })
             onDragOver={(e) => { if ([...e.dataTransfer.types].includes(DRAG_TYPE)) { e.preventDefault(); e.dataTransfer.dropEffect = 'copy' } }}
             onDrop={onDrop}
           >
+            {ctrl.steps.building && (
+              <div className="xeplr-factory-building" style={{ maxWidth: doc.width }}>
+                <span className="xeplr-factory-building-what">Building</span>
+                {ctrl.steps.labels(ctrl.steps.building).map((s2, i) => (
+                  <button
+                    key={s2.key}
+                    type="button"
+                    className={'xeplr-factory-building-step' + (i === ctrl.steps.active(ctrl.steps.building) ? ' is-active' : '')}
+                    onClick={() => ctrl.steps.go(ctrl.steps.building, i)}
+                  >
+                    {s2.label}
+                  </button>
+                ))}
+                {ctrl.selectedNode && ctrl.selectedNode.type !== 'stepper' && (
+                  <label className="xeplr-factory-building-every">
+                    <input
+                      type="checkbox"
+                      checked={!ctrl.steps.of(ctrl.selectedNode)}
+                      onChange={(e) => ctrl.steps.set(ctrl.selectedNode.id, e.target.checked ? null : { of: ctrl.steps.building, index: ctrl.steps.active(ctrl.steps.building) })}
+                    />
+                    <span>Show the selected control on every step</span>
+                  </label>
+                )}
+              </div>
+            )}
             <div className="xeplr-factory-frame" style={{ maxWidth: doc.width }}>
               <XeplrCanvas
                 className="xeplr-factory-canvas"
                 style={screenStyle(doc)}
-                items={doc.nodes}
+                items={ctrl.visibleNodes}
                 units="fraction"
                 pageAspect={doc.aspect}
                 features={{ resize: true, marquee: true }}
@@ -131,11 +156,20 @@ export default function BuilderSample({ ctrl, renderPreview, className, style })
                 minSizeFor={() => ({ minWidth: 16, minHeight: 12 })}
                 renderItem={(node, { selected }) => (
                   <div className={`xeplr-factory-design-node${ctrl.errorsByNode[node.id] ? ' has-error' : ''}${selected ? ' is-selected' : ''}`}>
-                    <ControlView node={node} mode="design" list={node.type === 'list' ? { doc } : undefined} />
+                    <ControlView
+                      node={node}
+                      mode="design"
+                      list={node.type === 'list' ? { doc } : undefined}
+                      // Clicking a step on the canvas OPENS it: the canvas then
+                      // shows that step's controls, and what you drop joins them.
+                      stepper={node.type === 'stepper' ? { active: ctrl.steps.active(node.id), onStep: (i) => ctrl.steps.go(node.id, i) } : undefined}
+                    />
                   </div>
                 )}
-                underlay={doc.nodes.length === 0 && (
-                  <div className="xeplr-factory-empty">Drag controls here from the left</div>
+                underlay={ctrl.visibleNodes.length === 0 && (
+                  <div className="xeplr-factory-empty">
+                    {doc.nodes.length === 0 ? 'Drag controls here from the left' : 'This step is empty — drop a control to start it'}
+                  </div>
                 )}
               />
             </div>