@xeplr/ui-factory 1.0.14 → 1.2.0

package/AUTHORING.md

@@ -60,7 +60,7 @@ A request for "a form for employees" is an **entity**. Every entity is the same
    ```jsx
    export class EmployeeHooks extends FactoryHooks {
      get(ctx) { return super.get(ctx) }                          // a list's rows (ctx.many), or the record Edit opens (ctx.id)
-     save(values, ctx) { return super.save(values, ctx) }        // every autosave; returns the saved record
+     save(values, ctx) { return super.save(values, ctx) }        // the Save button; returns the saved record
      delete(record, ctx) { return super.delete(record, ctx) }    // a list row, after the person confirmed
      actions(ctx) { return super.actions(ctx) }                  // extra row buttons: [{ label, onClick: (record, ctx) => … }]
    }
@@ -92,7 +92,7 @@ A request for "a form for employees" is an **entity**. Every entity is the same
 8. **Server hooks, if the request needs them.** Anything beyond storing what the form shows — a value worked out on save, a check against other records, an email afterwards, a list narrowed to the user — goes in `employee.hooks.js`, never in the screen: `save`, `get` (list and one record) and `delete`, each with `before`, `after`, `error` and `override`. Register it with `factory.init({ hooks: { employee_edit: require('./employee.hooks') } })`. `override` replaces the whole operation — rules and the other hooks included — so use it only when the generic save / get / delete does not apply at all. The `screens` command never overwrites an existing hooks file, even with `--force`. Details: the [`@xeplr/factory` README](https://www.npmjs.com/package/@xeplr/factory#hooks).
 9. **Hand over.** The person opens the screens in the designer to move, resize and restyle controls.
 
-There is **no submit button** to add: a screen saves itself as it is filled in. If the request mentions seeing or editing what was entered ("…and show the employees below"), add a `list`.
+Do **not** add a button control for saving: every screen's footer already has **Save** (an AJAX call — never a form submit) and **Cancel** where it can go back. If the request mentions seeing or editing what was entered ("…and show the employees below"), add a `list`.
 
 Changing an existing screen: edit the document's `props` directly (labels, validation, options), validate, and hand it back. Regenerate from a spec only when the layout should start over.
 
@@ -192,7 +192,7 @@ Each field:
 | `text` | `minLength`, `maxLength`, `pattern` (a regex string), `patternMessage` (shown when it fails) |
 | `textarea` | `minLength`, `maxLength` |
 | `number` | `min`, `max`, `integer` |
-| `date` | `min`, `max` — as `"YYYY-MM-DD"` |
+| `date` | `min`, `max` — as `"YYYY-MM-DD"`; `notFuture: true` (a date of birth) |
 | `datetime` | `min`, `max` — as `"YYYY-MM-DDTHH:MM"` |
 | `multiselect` | `minItems`, `maxItems` — how many may be chosen |
 | `checkbox`, `dropdown`, `radio`, `file` | none (use `required`) |
@@ -237,11 +237,35 @@ A dropdown **always saves an `id` and shows a `name`.**
 
 ## Choosing controls
 
+**Ready-made fields first.** For these, give the `type` as the ready-made
+field's key and add nothing else unless the request asks for it — the keyboard,
+pattern, message, limits and options come with it:
+
+| the request says | `type` |
+|---|---|
+| email | `email` |
+| phone, mobile | `phone` |
+| website, URL, link | `url` |
+| LinkedIn profile | `linkedin` |
+| age | `age` (whole number, 0–130) |
+| date of birth | `dateOfBirth` (never in the future) |
+| gender | `gender` (Male, Female, Others) |
+| country, nationality | `country` (ISO codes, shown by name) |
+| amount, price, salary, fee | `amount` (0 or more) |
+| percentage | `percentage` (0–100) |
+| a yes/no question to answer explicitly | `yesNo` |
+| postal code, ZIP, PIN | `postalCode` |
+
+`{ "label": "Work email", "type": "email", "required": true }` keeps the label
+and adds the rest. A field with **no type** whose label reads like one of these
+gets it anyway (`{ "label": "Age" }` is the Age field); `"type": "text"` opts out.
+Rules you give merge over the ready-made ones (`"validation": { "max": 120 }`).
+
 | the request says | use |
 |---|---|
-| a name, title, email, phone, code | `text` (add a `pattern` for email/phone/code formats) |
+| a name, title, code | `text` (add a `pattern` for a code format) |
 | notes, description, address, comments | `textarea` |
-| amount, salary, quantity, age | `number` (`integer: true` for counts) |
+| quantity, score, count | `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` |

package/README.md

@@ -1,6 +1,6 @@
 # @xeplr/ui-factory
 
-**Design data-entry screens, save them as JSON, run them as working forms.** Drag controls onto a canvas, set their labels, validation, options, fonts and colours. The same document renders as a live form in your app that **saves itself** as it is filled in, with a list of the saved records to open, edit or delete.
+**Design data-entry screens, save them as JSON, run them as working forms.** Drag controls onto a canvas, set their labels, validation, options, fonts and colours. The same document renders as a live form in your app, saved by its **Save** button over AJAX, with a list of the saved records to open, edit or delete.
 
 It is built to work with Claude: ask for *"a form for employees with name, email, department and start date"*, and Claude creates **two screens** — an employee **list** and an **add / edit** form that the list's Edit and New open in a popup — plus the two pages that show them. A person then refines either one in the designer.
 
@@ -44,10 +44,10 @@ Most internal apps are a long tail of forms, and every one of them is hand-built
 ## Install
 
 ```sh
-npm i @xeplr/ui-factory @xeplr/ui-canvas @xeplr/ui-table @tanstack/react-table
+npm i @xeplr/ui-factory @xeplr/ui-canvas @xeplr/ui-table @tanstack/react-table react-router-dom
 ```
 
-Peer dependencies: `react ^18 || ^19`, [`@xeplr/ui-canvas`](https://www.npmjs.com/package/@xeplr/ui-canvas) (the canvas the builder places controls on) and [`@xeplr/ui-table`](https://www.npmjs.com/package/@xeplr/ui-table) (lists of saved records). Your bundler must compile JSX and import CSS from the package (Vite does both).
+Peer dependencies: `react ^18 || ^19`, [`@xeplr/ui-canvas`](https://www.npmjs.com/package/@xeplr/ui-canvas) (the canvas the builder places controls on), [`@xeplr/ui-table`](https://www.npmjs.com/package/@xeplr/ui-table) (lists of saved records) and `react-router-dom ^6 || ^7` (imported by [`@xeplr/ui-utils`](https://www.npmjs.com/package/@xeplr/ui-utils)' `useUrlState`, a dependency, for the URL state below; with no router above, everything stays in memory). Your bundler must compile JSX and import CSS from the package (Vite does both).
 
 ## The builder
 
@@ -57,7 +57,7 @@ import { FactoryBuilder } from '@xeplr/ui-factory'
 <div style={{ height: '100vh' }}>
   <FactoryBuilder
     document={screen}                                  // omit to start a new one
-    onSave={async (doc) => api.saveScreen(doc)}        // your storage — called automatically
+    onSave={async (doc) => api.saveScreen(doc)}        // your storage — called when Save is pressed
     listTables={async () => api.listTables()}          // for "Saves to", lists and table dropdowns
     fetchOptions={async ({ table }) => api.options(table)}  // Preview with real options
     fetchRecords={async ({ source }) => api.records(source)} // Preview with real records
@@ -70,6 +70,21 @@ import { FactoryBuilder } from '@xeplr/ui-factory'
 - Select a control to set its label, field name, placeholder, required, default, validation, and — for a dropdown — where its options come from.
 - **Every look is a property:** font, size, weight, italic, alignment, text colour, background, border colour/width, corner radius — and for an input, its label's size, weight and colour.
 - With nothing selected, the panel shows the **screen**: the table it saves to, its width, and the font and colours every control inherits.
+
+**Nothing saves itself — here, or anywhere else in this package.** The bar says
+*Unsaved changes* and offers **Save**; that is the only thing that writes the
+draft, so trying a layout out and walking away leaves the saved screen as it
+was. Closing the tab with unsaved work asks first.
+
+It used to save 800ms after every edit, and that was wrong twice over: there
+was no such thing as trying something out, and no moment at which anybody said
+"this is right" — and a field is invalid *while it is being built*, so the
+autosave met half-made work and reported it as an error nobody asked for.
+`autosaveDelay` is still accepted and ignored, so a host passing it is not
+broken.
+
+**Publish still saves first**, because publishing what is on screen is the one
+thing it must never get wrong.
 - **No Save button.** Edits are saved (as a draft) a moment after you stop, whenever the screen is valid; problems are marked on the controls that have them until they are fixed.
 - **Publish** (when `onPublish` is given) makes the draft the version everyone sees and changes its table to match. If removed fields would drop columns, it asks first — "Publishing removes `phone` — 1,240 saved values" — with **Remove and publish** / **Cancel**. Unsafe changes (narrowing a field) are refused with the reason.
 - **`lockedNames`**: fields that are already columns of the table. Their names are read-only, because renaming one would leave its data behind.
@@ -92,7 +107,11 @@ import { FactoryScreen } from '@xeplr/ui-factory'
 />
 ```
 
-**There is no submit.** The screen saves itself in the background (one AJAX call to your `onSave`) a moment after a change, once the entered values are acceptable. Until then it says what is missing — "Fill in the required fields to save" — and a field's message appears once the person has been in it. The first save of a new record creates it: return the saved record and its `id` makes every later save an update.
+**Save is a button and an AJAX call — never a form submit.** Nothing is written while the person types: the footer says "Unsaved changes" until they press **Save**, which makes one call to your `onSave`. There is no `<form>` post and Enter saves nothing. If something is missing, Save marks every field that needs attention instead of sending. The first save of a new record creates it: return the saved record and its `id` makes every later save an update.
+
+- With `onDone` (a page, or the list's popup), the footer has **Cancel** and **Save**. Save saves and then calls `onDone`. Cancel calls `onDone` without saving, asking first if anything is unsaved. Without `onDone` (a form embedded in a page) there is Save alone, and it shows "Saved".
+- Leaving with unsaved changes asks first: Cancel, the popup's ×/Escape, a list-on-the-form opening another record, and closing or reloading the tab. **In-app navigation (a side-rail click) is the host router's to guard** — `ctrl.dirty` / `onDirtyChange(dirty)` say when there is something to lose.
+- `useFactoryScreen` returns `save()` (the button), `dirty`, `confirmDiscard()` and `flush()` (save only if unsaved — what a flow's Next does). `AUTOSAVE_DELAY` and `autosaveDelay` are gone.
 
 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.
 
@@ -143,7 +162,7 @@ const taskHooks = new TaskHooks()
 | method | default | ctx |
 |---|---|---|
 | `get(ctx)` | `fetchRecords` for a list, `fetchRecord` for the record Edit opens | `many`, `id`, `screen`, `source` |
-| `save(values, ctx)` | `onSave` — on every autosave; return the saved record | `id`, `isNew`, `screen`, `source` |
+| `save(values, ctx)` | `onSave` — when Save is pressed; return the saved record | `id`, `isNew`, `screen`, `source` |
 | `delete(record, ctx)` | `onDelete`, after the person confirmed | `id`, `screen`, `source` |
 | `actions(ctx)` | `[]` — extra row buttons `{ label, onClick(record, ctx) }` beside Edit / Delete | `screen`, `refresh()` |
 
@@ -153,7 +172,7 @@ Rules that must hold belong in the server's hooks; the browser only shapes what
 
 ### Lists of saved records
 
-A **List** control shows the records of the table the screen saves to (or another), in `@xeplr/ui-table`, with the columns you tick. Its **Edit in** names the edit screen: **Edit** and **New** open that screen in a popup, where it saves itself and the list refreshes behind it.
+A **List** control shows the records of the table the screen saves to (or another), in `@xeplr/ui-table`, with the columns you tick. Its **Edit in** names the edit screen: **Edit** and **New** open that screen in a popup: its Save saves, closes the popup and refreshes the list; Cancel closes it unsaved.
 
 **Opens in: a page of its own** sends them to a page in your app instead. The factory has no router, so it asks — `onOpenRecord` on the list's screen, and `onDone` on the page, which draws a **Done** button that saves what is pending and calls it:
 
@@ -178,6 +197,47 @@ import schemaHandler from '@xeplr/schema-handler'          // CommonJS: default
 const clean = schemaHandler.applySchema(formSchema(screen), req.body)   // throws ValidationError listing each field
 ```
 
+## Your screens, inside someone else's designer
+
+`@xeplr/ui-workflow`'s flow designer has a **Screen** step, and it asks its
+host two things: which screens exist and what each one hands back, and how to
+design one without leaving the flow. It cannot answer either itself — it
+carries a screen key and knows nothing else about forms, on purpose, so an app
+with a different screen system is not locked out.
+
+This package answers both, in one hook:
+
+```jsx
+import { useScreenSource, FactoryBuilder } from '@xeplr/ui-factory'
+
+const { screens, screenEditor } = useScreenSource(factory, { Builder: FactoryBuilder })
+<WorkflowDesigner screens={screens} screenEditor={screenEditor} … />
+```
+
+- **`screens`** is `[{ key, name, fields }]`. `fields` comes from
+  `inputNodes(doc)` — this package's own answer to "which nodes hold a value"
+  — so a label or a stepper is never offered as a field, and a control type
+  added here reaches every app without one of them being edited. Names arrive
+  first and fields follow, so the menu is usable while documents load; a
+  document that will not load leaves its screen choosable without fields.
+- **`screenEditor`** is the body of the designer's modal: the builder, on the
+  form that step shows, or on a new one it makes (`screenKey: null` → name it
+  → `createEntity`). **Publishing** is what fires `onDone({ key, name, fields })`,
+  because a draft changes nothing anybody can run — and that is what tells the
+  flow the form's new shape, so a field added there appears in every step that
+  shows that form.
+
+**Why this is a package and not four lines in your app.** It used to be the
+latter, and that is a bug: an app is generated once and then lives its own
+life, so glue copied into it can never be fixed centrally. An app scaffolded
+last month would keep the old version forever, and a control added here would
+never reach it. Anything every app would write identically belongs on this
+side of the line — `@xeplr/cli`'s generated `FlowDesigner.jsx` is two props,
+and its test suite fails if the glue reappears in the app.
+
+The pure half is `screenSource.js` — `describeScreen`, `loadScreens`,
+`keyFromName`, `editScreenOf` — testable with no React and no server.
+
 ## Flows — screens, one after another
 
 A screen is a form; a **flow** is the journey across several of them. Design it
@@ -207,7 +267,7 @@ that does — Xeplr Workflow — so a run remembers where it got to: a journey c
 be left and picked up later, by someone else, on another day. Without such a
 service there are no flows; the factory has no engine of its own, on purpose.
 
-**Each screen still saves itself, into its own table.** What travels with the
+**Each screen still saves into its own table** — the flow's **Next** saves what is unsaved (one AJAX call) and then moves on. What travels with the
 run is only what the arrows need and the id of the row that was written
 (`recordId`), so the data is exactly where it would be without a flow.
 
@@ -231,10 +291,10 @@ Both walk someone through something, and they answer different questions:
 
 | type | value | validation |
 |---|---|---|
-| `text` | string | `minLength`, `maxLength`, `pattern`, `patternMessage` |
+| `text` | string | `minLength`, `maxLength`, `pattern`, `patternMessage` — and `inputType` (`text`, `email`, `tel`, `url`): the phone keyboard and autofill |
 | `textarea` | string | `minLength`, `maxLength` |
 | `number` | number | `min`, `max`, `integer` |
-| `date` | `"YYYY-MM-DD"` | `min`, `max` |
+| `date` | `"YYYY-MM-DD"` | `min`, `max`, `notFuture` (on or before today, whenever it is filled in) |
 | `datetime` | `"YYYY-MM-DDTHH:MM"` | `min`, `max` |
 | `checkbox` | boolean | `required` = must be ticked |
 | `dropdown` | option id | — |
@@ -245,10 +305,68 @@ Both walk someone through something, and they answer different questions:
 | `label` | — | text with a heading, subheading or text preset |
 | `list` | — | saved records, with New / Edit / Delete |
 
-A screen is a **sheet**: it paints its own surface, so a screen designed in
-dark ink stays readable inside a dark app. Give the screen a `background` in
-its own style to change it, or set `--xeplr-factory-paper` on the host for all
-of them.
+A screen is a **sheet**, centred in the space it is given and shown at its
+design width: an elevated card in the app's theme (`--xeplr-bg-tertiary`, with
+`--xeplr-border-primary` round it) — white in a light app, the lighter grey in
+a dark one, with inputs in the theme's input colours. A screen whose style sets
+its own `color` / `background` keeps them everywhere, input boxes included, so
+dark ink on paper is never shown on a dark theme's input. Set
+`--xeplr-factory-paper` on the host to change every sheet. A screen with no
+fields (only lists) draws **no** sheet — the list is its own card.
+
+Under the fields sits **one footer**, inset to line up with them: Back and
+Next, then "Step 2 of 3" with the save status under it ("Unsaved changes",
+"Saved"), then Cancel and Save. A screen without steps has the status, Cancel
+and Save alone.
+
+A **list** is a single card, as tall as its rows: the title and + New sit in
+the table's own toolbar, paging appears only when there is more than one page,
+and "Nothing saved yet." shows under the title when there are no rows.
+
+### Ready-made fields
+
+Twelve fields nobody should have to design twice, in the builder's palette under
+**Common fields**: Email, Phone, LinkedIn profile, Website, Age, Date of birth,
+Gender (Male, Female, Others), Country, Amount, Percentage, Yes / No, Postal code.
+
+| field | made of | what it sets |
+|---|---|---|
+| Email / Phone / Website / LinkedIn profile | `text` | `inputType` (email, tel, url keyboards), a `pattern` with a plain-English message, a placeholder, a `maxLength` |
+| Postal code | `text` | letters, digits, spaces and `-`, up to 10 |
+| Age | `number` | a whole number, 0–130 |
+| Amount / Percentage | `number` | 0 or more / 0–100 |
+| Date of birth | `date` | `notFuture` |
+| Gender / Yes / No | `radio`, side by side | its options |
+| Country | `dropdown` | every country — stored as its ISO code (`IN`), shown by name |
+
+A ready-made field is **not a new control**: its settings are copied into an
+ordinary one, where they stay editable, and `props.preset` remembers where it
+came from. Changing the catalogue never changes a form already made with it.
+The rules are the field's own, so the server enforces them like any others.
+
+**Any field can change kind at any time** — the panel's **Field type**, at the
+top, lists the controls and the ready-made fields. The label, name, position,
+step and required are kept; whatever does not carry over is said ("Not carried
+over: the pattern"). A name that is already a column is never changed.
+
+**Forgot?** A plain field whose label reads like a ready-made one ("LinkedIn
+URL" as a text box) gets an offer in its panel — **Make it LinkedIn profile** /
+**Keep as is** — and the builder's bar counts them ("1 suggestion"). They never
+stop a save or a publish; **Keep as is** sets `preset: false` and stops asking.
+
+**When the column has to follow.** A change of kind that stays text (text →
+LinkedIn) publishes as usual. One that changes the column's kind (text → Age,
+a number) is a **conversion**: publishing first checks every saved value, across
+every company. If any will not fit, nothing changes and the publish says which
+("`age` has 1 saved value that cannot become integer ("forty")"). If all fit,
+it asks — **Convert and publish** — and then converts, blanks becoming empty.
+A timestamp → date, or a dropdown moved to another table, is still refused.
+
+In code: `FIELD_PRESETS`, `presetFor`, `presetProps`, `suggestPreset(label)`,
+`presetHints(doc)`, `convertField(doc, id, target, controls, { lockedNames })`,
+and `conversionFor(table, from, to)` / `planTableChange(…, { confirmConvert })`.
+The builder hook adds `convertControl(id, target)` and `hints`; `publish(confirmDrop,
+confirmConvert)`.
 
 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.
 
@@ -304,8 +422,7 @@ same for a screen with more than one (`ctx.steps.disable('approval', stepperId)`
 learns which branch it is on. "Step 2 of 4" counts only the steps that apply.
 
 **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,
+saved, whichever step is showing — Save can be pressed on any step. **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
@@ -369,6 +486,26 @@ npx xeplr-factory controls                   # controls, props and rules
 
 Layout is **proportional**, like `@xeplr/ui-canvas` dashboards: `x` and `w` are fractions of the width, `y` and `h` fractions of a page (`width × aspect`). The screen is shown at its design `width`; on a narrower display everything — positions and text — scales down together.
 
+## Where you are lives in the URL: `urlKey`
+
+The control whose properties are open, the step a stepper is open at, and the flow step being edited are places a person navigates to. Give a controller (or its ready-made page) a `urlKey` and they are written to the URL's query, so a refresh or a shared link lands on them again:
+
+| controller / page | key | holds | history |
+|---|---|---|---|
+| `useFactoryBuilder` / `<FactoryBuilder>` | `<urlKey>Selected` | the id of the one selected control | opening or closing its properties adds an entry (Back closes them); moving to another control replaces it |
+| `useFactoryBuilder` / `<FactoryBuilder>` | `<urlKey>Steps` | the step each stepper is open at: `stepperId:index`, comma-separated, step 0 left out | replaces |
+| `useFactoryScreen` / `<FactoryScreen>`, `<FlowRunner>` | `<urlKey>Steps` | as above | replaces |
+| `useFlowBuilder` / `<FlowBuilder>` | `<urlKey>Selected` | the key of the selected flow step | as for a control |
+
+```jsx
+<FactoryBuilder urlKey="form" document={doc} onSave={save} />    // ?formSelected=email&formSteps=stepper:1
+```
+
+- **The key is the host's, never a default.** A builder, its Preview and a list's Edit popup can share a page, and the host has keys of its own, so nothing is written to the URL without a `urlKey` — give each its own. **Without one the state stays in memory**, as before. The Preview and the Edit popup are never given one.
+- **A multi-selection is not a place.** Several controls selected is a working set for Delete and Duplicate, not somewhere a person goes, so it stays in memory and the URL then names nothing. Only a single selection — the one whose properties are open — is in the URL.
+- **Ids, found again.** The selected control is looked up in the document; one that is not there selects nothing. A document handed in after mounting keeps the URL's control, so a host that loads the screen late still lands on it. A step past the last is pulled back to the last, and steppers not in the document (a screen still loading) are left alone.
+- The rule is in `src/urlState.js` (`factoryUrlKeys`, `encodeSteps`, `decodeSteps`, `replacesHistory`, `selectionPlace`); the hooks that keep it are `src/useUrlPlaces.js`.
+
 ## Three ways to use it
 
 1. **Ready-made** — `<FactoryBuilder>` and `<FactoryScreen>`.
@@ -377,7 +514,9 @@ Layout is **proportional**, like `@xeplr/ui-canvas` dashboards: `x` and `w` are
 
 ## Theming
 
-Styles are namespaced `.xeplr-factory-*` and read the xeplr theme variables with light fallbacks: `--xeplr-accent`, `--xeplr-text`, `--xeplr-muted`, `--xeplr-border`, `--xeplr-surface`, `--xeplr-danger`, `--xeplr-input-bg`, `--xeplr-input-border`.
+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.
+
+Buttons, steps and list actions all show hover, a visible press, and a keyboard-only focus ring.
 
 ## Try it
 
@@ -393,16 +532,22 @@ src/
   controls.js            ─ the control registry: palette, property panel contract, rules
   document.js            ─ create and edit screen documents
   validateDocument.js    ─ the document checker
-  values.js              ─ values, validation, autosave readiness, records and list columns, formSchema
+  values.js              ─ values, validation, whether Save can go out, records and list columns, formSchema
   generate.js            ─ screenFromSpec, screensFromSpec (list + edit), entity names
   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)
+  presets.js             ─ ready-made fields (Email, Age, Gender…), changing a field's kind, label suggestions
+  tableSchema.js         ─ a form → its table; the publish plan (create / add / widen / confirmed drops and conversions)
   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 })
+  screenSource.js        ─ this app's screens as another designer wants them: describeScreen, loadScreens, keyFromName, editScreenOf (React-free)
   model.js               ─ everything above, React-free
   useFactoryBuilder.js   ─ builder controller
   useFactoryScreen.js    ─ screen controller
-  designs/               ─ BuilderSample, ScreenSample, ControlView, ListView, Palette, PropertyPanel, styles.js, factory.css
+  useFlowBuilder.js      ─ flow designer controller
+  urlState.js            ─ the URL keys and values for selection and steps (React-free)
+  useUrlPlaces.js        ─ useUrlSteps, useUrlSelection: those places, in the URL or in memory
+  useScreenSource.js     ─ { screens, screenEditor } for @xeplr/ui-workflow's Screen step
+  designs/               ─ BuilderSample, ScreenSample, ScreenEditorSample, ControlView, ListView, Palette, PropertyPanel, styles.js, factory.css
   pages.jsx              ─ FactoryBuilder, FactoryScreen
 bin/xeplr-factory.js     ─ screens / generate / validate / controls / schema
 examples/                ─ employee.entity.json and what `screens` makes of it
@@ -415,6 +560,8 @@ dev/                     ─ the stand-in app for `npm run dev` (not published)
 npm test
 ```
 
+`test/urlState.test.js` covers the URL state: the key format, and the three controllers reading their places back from a real `MemoryRouter` and being clicked through in memory, rendered with `react-dom/server`.
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xeplr/ui-factory",
-  "version": "1.0.14",
+  "version": "1.2.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",
@@ -48,7 +48,8 @@
     "@tanstack/react-table": "^8.0.0",
     "@xeplr/ui-canvas": "^1.0.2",
     "@xeplr/ui-table": "^1.0.6",
-    "react": "^18.0.0 || ^19.0.0"
+    "react": "^18.0.0 || ^19.0.0",
+    "react-router-dom": "^6.0.0 || ^7.0.0"
   },
   "devDependencies": {
     "@tanstack/react-table": "^8.21.3",
@@ -58,6 +59,10 @@
     "@xeplr/ui-table": "^1.0.6",
     "react": "^19.2.4",
     "react-dom": "^19.2.4",
+    "react-router-dom": "^7.18.4",
     "vite": "^7.3.1"
+  },
+  "dependencies": {
+    "@xeplr/ui-utils": "^1.1.2"
   }
 }

package/src/controls.js

@@ -164,11 +164,14 @@ export const CONTROLS = {
     valueType: 'string',
     defaultSize: { w: 0.44, h: 0.08 },
     defaults: { label: 'Text' },
-    props: ['name', 'label', 'placeholder', 'required', 'default', 'validation', 'style'],
+    // inputType: the box's keyboard and autofill — text, email, tel, url.
+    props: ['name', 'label', 'preset', 'placeholder', 'required', 'default', 'validation', 'inputType', 'style'],
     validation: ['minLength', 'maxLength', 'pattern', 'patternMessage'],
     styles: INPUT_STYLES,
     properties: [
-      FIELD_BASICS([PLACEHOLDER, { path: 'props.default', label: 'Default value', type: 'text' }]),
+      FIELD_BASICS([PLACEHOLDER, { path: 'props.default', label: 'Default value', type: 'text' }, { path: 'props.inputType', label: 'Keyboard', type: 'select', options: [
+        { value: 'text', label: 'Text' }, { value: 'email', label: 'Email' }, { value: 'tel', label: 'Phone' }, { value: 'url', label: 'Web address' }
+      ], help: 'What a phone shows to type with, and what autofill offers' }]),
       {
         key: 'validation',
         title: 'Validation',
@@ -191,7 +194,7 @@ export const CONTROLS = {
     valueType: 'string',
     defaultSize: { w: 0.92, h: 0.18 },
     defaults: { label: 'Notes' },
-    props: ['name', 'label', 'placeholder', 'required', 'default', 'validation', 'style'],
+    props: ['name', 'label', 'preset', 'placeholder', 'required', 'default', 'validation', 'style'],
     validation: ['minLength', 'maxLength'],
     styles: INPUT_STYLES,
     properties: [
@@ -216,7 +219,7 @@ export const CONTROLS = {
     valueType: 'number',
     defaultSize: { w: 0.44, h: 0.08 },
     defaults: { label: 'Number' },
-    props: ['name', 'label', 'placeholder', 'required', 'default', 'validation', 'style'],
+    props: ['name', 'label', 'preset', 'placeholder', 'required', 'default', 'validation', 'style'],
     validation: ['min', 'max', 'integer'],
     styles: INPUT_STYLES,
     properties: [
@@ -242,8 +245,10 @@ export const CONTROLS = {
     valueType: 'date',
     defaultSize: { w: 0.44, h: 0.08 },
     defaults: { label: 'Date' },
-    props: ['name', 'label', 'required', 'default', 'validation', 'style'],
-    validation: ['min', 'max'],
+    props: ['name', 'label', 'preset', 'required', 'default', 'validation', 'style'],
+    // notFuture: on or before TODAY, whenever the form is filled in (a date of
+    // birth) — a fixed `max` would go stale.
+    validation: ['min', 'max', 'notFuture'],
     styles: INPUT_STYLES,
     properties: [
       FIELD_BASICS([{ path: 'props.default', label: 'Default value', type: 'date' }]),
@@ -252,7 +257,8 @@ export const CONTROLS = {
         title: 'Validation',
         fields: [
           { path: 'props.validation.min', label: 'Earliest', type: 'date' },
-          { path: 'props.validation.max', label: 'Latest', type: 'date' }
+          { path: 'props.validation.max', label: 'Latest', type: 'date' },
+          { path: 'props.validation.notFuture', label: 'Not in the future', type: 'toggle' }
         ]
       },
       ...styleGroups(INPUT_STYLES)
@@ -268,7 +274,7 @@ export const CONTROLS = {
     defaultSize: { w: 0.44, h: 0.05 },
     defaults: { label: 'Checkbox', default: false },
     // `required` on a checkbox means it must be ticked — "I accept".
-    props: ['name', 'label', 'required', 'default', 'style'],
+    props: ['name', 'label', 'preset', 'required', 'default', 'style'],
     validation: [],
     styles: ['fontFamily', 'fontSize', 'fontWeight', 'fontStyle', 'color'],
     properties: [
@@ -286,7 +292,7 @@ export const CONTROLS = {
     valueType: null,
     defaultSize: { w: 0.44, h: 0.08 },
     defaults: { label: 'Dropdown', placeholder: 'Select…', data: { source: 'static', options: [] } },
-    props: ['name', 'label', 'placeholder', 'required', 'default', 'data', 'style'],
+    props: ['name', 'label', 'preset', 'placeholder', 'required', 'default', 'data', 'style'],
     validation: [],
     styles: INPUT_STYLES.filter((k) => k !== 'textAlign'),
     properties: [
@@ -311,7 +317,7 @@ export const CONTROLS = {
     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'],
+    props: ['name', 'label', 'preset', 'required', 'default', 'data', 'layout', 'style'],
     validation: [],
     styles: INPUT_STYLES.filter((k) => k !== 'textAlign'),
     properties: [
@@ -338,7 +344,7 @@ export const CONTROLS = {
     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'],
+    props: ['name', 'label', 'preset', 'required', 'data', 'layout', 'validation', 'style'],
     validation: ['minItems', 'maxItems'],
     styles: INPUT_STYLES.filter((k) => k !== 'textAlign'),
     properties: [
@@ -371,7 +377,7 @@ export const CONTROLS = {
     valueType: 'date',
     defaultSize: { w: 0.44, h: 0.08 },
     defaults: { label: 'Date and time' },
-    props: ['name', 'label', 'required', 'default', 'validation', 'style'],
+    props: ['name', 'label', 'preset', 'required', 'default', 'validation', 'style'],
     validation: ['min', 'max'],
     styles: INPUT_STYLES,
     properties: [
@@ -397,7 +403,7 @@ export const CONTROLS = {
     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'],
+    props: ['name', 'label', 'preset', 'required', 'accept', 'maxSize', 'style'],
     validation: [],
     styles: INPUT_STYLES.filter((k) => k !== 'textAlign'),
     properties: [