@xeplr/ui-factory 1.0.1 → 1.0.3

package/AUTHORING.md

@@ -4,26 +4,75 @@ This guide is for whoever **writes** a screen definition — usually Claude, fro
 
 ## The workflow
 
-1. **Write a spec** — a short list of what is on the screen, in reading order. Do not write coordinates.
-2. **Generate** the screen document from it:
+A request for "a form for employees" is an **entity**, and an entity is **two screens**: a list, and an add / edit form the list opens in a popup.
+
+1. **Write an entity spec** — the entity's name and its fields, in reading order. Do not write coordinates.
+2. **Generate** both screens and their pages:
    ```sh
-   npx xeplr-factory generate spec.json -o screen.json
+   npx xeplr-factory screens employee.entity.json -o src/screens/employee
    ```
-   or in code: `screenFromSpec(spec)` from `@xeplr/ui-factory/model`.
-3. **Validate** — `generate` already refuses a bad spec, but check any document you edited by hand:
+   This writes `employee-list.screen.json`, `employee-edit.screen.json`, `EmployeeList.jsx`, `EditEmployee.jsx` and an empty `employee.hooks.js`. Wire the two pages into the app's menu next to two `<FactoryBuilder>` pages for designing them (Screen · List, Screen · Edit, Designer · List, Designer · Edit). It refuses to overwrite existing files — they may have been refined in the designer — unless given `--force`.
+
+   A single screen that is not an entity (a settings form, say) uses `npx xeplr-factory generate spec.json -o screen.json` with the screen spec below.
+3. **The table comes from Publish.** Records live in a **real table** — `employees`, one column per field — never in JSON, and there are no migration files to write: **publishing** the edit screen creates its table (`CREATE TABLE`, a column per field, real foreign keys for table dropdowns, the standard `id` / `isActive` / `mtId1–4` / audit columns), and publishing a later version changes it:
+   - a new field → `ADD COLUMN`; a wider text or number → `ALTER COLUMN … TYPE`
+   - narrowing, or a different kind of value → **refused**; tell the person why
+   - a **removed field drops its column and all its data** — Publish asks the person to confirm first, showing how many values would go. Never confirm a drop on their behalf.
+   - a column not created by a screen, or still used by another company's screen, is never dropped
+
+   Publish a table that others point at first: `departments` before `employees`. To preview the SQL without applying it: `npx xeplr-factory migration employee-edit.screen.json`.
+
+   **Never rename a field that is already a column** (the designer locks those names) — it would drop the old column and its data and start an empty one.
+4. **Validate** — `screens` and `generate` already refuse a bad spec, but check any document you edited by hand:
    ```sh
    npx xeplr-factory validate screen.json
    ```
    Every problem names a path (`nodes[3].props.data.table`) and what belongs there. Fix and re-run until it prints `ok`.
-4. **Hand the document to the app.** The app stores it and opens it in `<FactoryBuilder>`, where the person moves, resizes and adjusts controls.
+5. **Save and publish.** Save the screens as drafts, then publish — edit screens of referenced tables first. Publishing changes the table; if it would drop columns it returns them for the person to confirm.
+6. **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).
+7. **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`.
 
 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.
 
-## The spec
+## The entity spec
+
+```json
+{
+  "entity": "employee",
+  "fields": [
+    { "label": "First name", "required": true },
+    { "label": "Last name", "required": true },
+    { "label": "Work email", "required": true,
+      "validation": { "pattern": "^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$", "patternMessage": "Enter a valid email address" } },
+    { "label": "Department", "type": "dropdown", "table": "departments", "required": true },
+    { "label": "Start date", "type": "date", "required": true }
+  ],
+  "listColumns": ["firstName", "lastName", "departmentId", "startDate"]
+}
+```
+
+| key | meaning |
+|---|---|
+| `entity` | **required** — singular, e.g. `"employee"`, `"leave request"` |
+| `plural` | when the plural is irregular, e.g. `"people"` (default: `entity` + s / es / ies) |
+| `source` | the table records are saved in (default: the plural, snake_cased — `employees`) |
+| `fields` | **required** — the edit form's fields, exactly as in the screen spec below |
+| `listColumns` | the list's columns: field names, or `{ "field", "label" }` (default: the first five fields). Pick the few that identify a record |
+
+A dropdown reading another table stores that row's id, so its field (and column) is named for it: "Department" becomes `departmentId`, a foreign key to `departments.id`. The other table needs an `id` and a `name` column — create that entity first.
+| `columns` | `1` or `2` — the edit form's layout (default `2`) |
+| `pageSize`, `actions`, `width`, `style` | as below |
+
+Names are derived once and agree everywhere: ids `employee_list` / `employee_edit`, files `employee-*.screen.json`, components `EmployeeList` / `EditEmployee`, table `employees`.
+
+## The screen spec
 
 ```json
 {
   "name": "New employee",
+  "source": "employees",
   "columns": 2,
   "fields": [
     { "label": "First name", "required": true, "validation": { "maxLength": 80 } },
@@ -38,20 +87,21 @@ Changing an existing screen: edit the document's `props` directly (labels, valid
     { "label": "Remote", "type": "checkbox" },
     { "label": "Notes", "type": "textarea", "validation": { "maxLength": 1000 } }
   ],
-  "submit": "Create employee",
-  "reset": "Clear"
+  "list": { "title": "Employees" }
 }
 ```
 
 | key | meaning |
 |---|---|
 | `name` | **required** — the screen's title |
+| `source` | the table records are saved to, e.g. `"employees"` — use the app's real table name |
 | `id` | document id; defaults to the name in snake_case |
 | `columns` | `1` or `2` (default `2`) |
 | `heading` | `true` (default) puts the name at the top; a string uses that text; `false` for none |
 | `fields` | **required** — in reading order |
-| `submit` | submit button label (default `"Save"`); `false` for none |
-| `reset` | reset button label; omit for none |
+| `list` | `true`, or `{ title, source, columns: [{ field, label }], pageSize, actions: ["new","edit","delete"] }` — saved records below the fields |
+| `width` | design width in px (default `800`) |
+| `style` | screen-wide defaults: `{ fontFamily, fontSize, color, background }` |
 
 Each field:
 
@@ -68,6 +118,7 @@ Each field:
 | `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 |
 | `text`, `variant` | `label` only — `variant` is `heading`, `subheading` (default for a section) or `text` |
+| `style` | how it looks — see Styles |
 
 ## Validation rules
 
@@ -81,6 +132,35 @@ Each field:
 
 Anything else is rejected, with the list of what is allowed.
 
+## Styles
+
+Every control takes `style`. Sizes are **pixels at the screen's `width`**.
+
+| key | controls | value |
+|---|---|---|
+| `fontFamily` | all | a CSS font family, e.g. `"Georgia, serif"` |
+| `fontSize` | all | 8–96 |
+| `fontWeight` | all but list | 300, 400, 500, 600, 700, 800 |
+| `fontStyle` | all but list | `"normal"` or `"italic"` |
+| `textAlign` | text, textarea, number, date, label | `"left"`, `"center"`, `"right"` |
+| `color` | all | `#rgb` or `#rrggbb` |
+| `background`, `borderColor` | inputs (not checkbox), label, list | `#rgb`, `#rrggbb` or `"transparent"` |
+| `borderWidth` | inputs (not checkbox), label, list | 0–10 |
+| `borderRadius` | inputs (not checkbox), label, list | 0–40 |
+| `labelFontSize`, `labelFontWeight`, `labelColor` | inputs (not checkbox) | the label above the field |
+
+Only style when the request asks for a look ("make the heading blue", "bigger labels"); otherwise leave the defaults.
+
+## Lists
+
+For an entity, `screens` makes the list for you. By hand: a `list` shows the saved records of the screen's `source` (or its own `source`) with **New**, **Edit** and **Delete**; `editScreen` names the screen those open in a popup. Columns default to every field; name the few that identify a record instead:
+
+```json
+{ "title": "Employees", "columns": [{ "field": "firstName", "label": "First name" }, { "field": "departmentId", "label": "Department" }] }
+```
+
+A list needs a table: set the screen's `source` or the list's own.
+
 ## Dropdowns
 
 A dropdown **always saves an `id` and shows a `name`.**
@@ -109,7 +189,7 @@ Keep labels short and in sentence case ("Start date", not "START DATE:"). Mark o
 {
   "kind": "xeplr-screen", "version": 1,
   "id": "new_employee", "name": "New employee",
-  "units": "fraction", "aspect": 1,
+  "units": "fraction", "aspect": 1, "width": 800,
   "nodes": [
     { "id": "firstName", "type": "text", "x": 0.04, "y": 0.15, "w": 0.4475, "h": 0.08, "z": 2,
       "props": { "label": "First name", "name": "firstName", "required": true } }
@@ -121,9 +201,18 @@ Keep labels short and in sentence case ("Start date", not "START DATE:"). Mark o
 - Node `id`s are unique; input `props.name`s are unique and match `^[A-Za-z_][A-Za-z0-9_]*$`.
 - `props` allowed per control: `npx xeplr-factory controls`.
 
+## Field names are column names
+
+- camelCase, as generated from the label: `firstName`, `startDate`, `departmentId`.
+- Not a standard column: `id`, `isActive`, `mtId1`–`mtId4`, `recordCreatedDate`, `recordModifiedDate`, `recordCreatedBy`, `recordModifiedBy`.
+- At most 63 characters.
+- Choose them as if naming a database column — because you are.
+
 ## Commands
 
 ```sh
+npx xeplr-factory screens <entity.json|-> [-o <dir>] [--force] # entity → list + edit screens and pages
+npx xeplr-factory migration <edit.screen.json> [--from <previous.screen.json>]   # preview a table's SQL (Publish applies it)
 npx xeplr-factory generate <spec.json|-> [-o <screen.json>]   # spec → document
 npx xeplr-factory validate <screen.json|->                    # exit 1 with every problem listed
 npx xeplr-factory controls                                     # controls, props, validation rules

package/README.md

@@ -1,8 +1,26 @@
 # @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 and options, and save. The same document renders as a live form in your app.
+**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.
 
-It is built to work with Claude: ask for *"a form for a new employee with name, email, department and start date"*, Claude drafts the screen, and a person refines it in the builder.
+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.
+
+## One entity, two screens, four pages
+
+| page | what it is |
+|---|---|
+| **Screen · List** | `EmployeeList.jsx` — the saved employees; **New** and **Edit** open the edit screen in a popup, **Delete** removes a row |
+| **Screen · Edit** | `EditEmployee.jsx` — the add / edit form, on its own page (the same screen the popup shows) |
+| **Designer · List** | `<FactoryBuilder document={employeeList} />` — its title, columns, actions, look |
+| **Designer · Edit** | `<FactoryBuilder document={employeeEdit} />` — its fields, validation, options, look |
+
+```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
+```
+
+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`.)
 
@@ -16,13 +34,15 @@ Most internal apps are a long tail of forms, and every one of them is hand-built
 
 **The factory never has a database.** Your app stores screen documents and supplies the rows dropdowns read. The factory draws, edits and validates.
 
+**Records live in real tables** — `employees`, one column per field — never in JSON, so `select * from employees` and ordinary reporting just work. **Publishing** a screen creates or changes its table directly: new fields add columns, and a removed field drops its column and data only after you confirm. [`@xeplr/factory`](https://www.npmjs.com/package/@xeplr/factory) is the server package that does it, saves screens (draft / publish) and reads and writes those tables with the screen's own validation. `createFactoryApi({ fetch })` connects the components to it.
+
 ## Install
 
 ```sh
-npm i @xeplr/ui-factory @xeplr/ui-canvas
+npm i @xeplr/ui-factory @xeplr/ui-canvas @xeplr/ui-table @tanstack/react-table
 ```
 
-Peer dependencies: `react ^18 || ^19` and [`@xeplr/ui-canvas`](https://www.npmjs.com/package/@xeplr/ui-canvas) (the canvas the builder places controls on). 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) 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).
 
 ## The builder
 
@@ -32,9 +52,10 @@ 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
-    listTables={async () => api.listTables()}          // offered for "dropdown from a table"
-    fetchOptions={async ({ table }) => api.options(table)}  // enables Preview with real options
+    onSave={async (doc) => api.saveScreen(doc)}        // your storage — called automatically
+    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
   />
 </div>
 ```
@@ -42,7 +63,11 @@ import { FactoryBuilder } from '@xeplr/ui-factory'
 - Drag controls from the palette onto the screen, or click one to add it at the bottom.
 - Move, resize, align with guides; drag a box to select several; <kbd>Delete</kbd> removes, <kbd>Ctrl/⌘ D</kbd> duplicates.
 - Select a control to set its label, field name, placeholder, required, default, validation, and — for a dropdown — where its options come from.
-- **Save** checks the whole screen first; problems are shown on the controls that have them, and `onSave` is only called with a valid document.
+- **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.
+- **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.
 
 ## The screen
 
@@ -51,14 +76,30 @@ import { FactoryScreen } from '@xeplr/ui-factory'
 
 <FactoryScreen
   document={screen}
-  values={employee}                                   // optional: the record being edited
+  record={employee}                                   // optional: open an existing record
+  onSave={async (values, { id, source }) => api.save(source, id, values)}  // returns the saved record, with its id
+  fetchRecords={async ({ source }) => api.records(source)}
+  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)}
-  onSubmit={async (values) => api.saveEmployee(values)}
+  screens={{ employee_edit: editScreen }}             // what a list's Edit / New open in a popup
 />
 ```
 
+**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.
+
+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).
 
+### 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. **Delete** removes a row after a confirmation. Dropdown columns show names, not ids — read from the edit screen's fields.
+
+The edit screen comes from `screens` (`{ id → document }`) or your `loadScreen(id)`. A list on a form with no **Edit in** opens rows in that form's own fields instead.
+
+`@xeplr/ui-table` reads the xeplr theme tokens (`--xeplr-bg-*`, `--xeplr-text-*`, `--xeplr-border-*`) and defaults to a dark look; define them for a light app.
+
 On your server, check the submission against the same rules with [`@xeplr/schema-handler`](https://www.npmjs.com/package/@xeplr/schema-handler):
 
 ```js
@@ -78,8 +119,10 @@ const clean = schemaHandler.applySchema(formSchema(screen), req.body)   // throw
 | `date` | `"YYYY-MM-DD"` | `min`, `max` |
 | `checkbox` | boolean | `required` = must be ticked |
 | `dropdown` | option id | — |
-| `label` | — | heading, subheading or text |
-| `button` | — | submit or reset |
+| `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
 
@@ -107,14 +150,18 @@ const screen = screenFromSpec({
     { label: 'Department', type: 'dropdown', table: 'departments', required: true },
     { label: 'Employment type', type: 'dropdown', options: ['Full time', 'Part time'] },
     { label: 'Start date', type: 'date' }
-  ]
+  ],
+  source: 'employees',
+  list: true
 })
 ```
 
 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 generate spec.json -o screen.json
+npx xeplr-factory screens entity.json -o dir   # an entity → list + edit screens and pages
+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
 npx xeplr-factory controls                   # controls, props and rules
 ```
@@ -127,7 +174,8 @@ npx xeplr-factory controls                   # controls, props and rules
 {
   "kind": "xeplr-screen", "version": 1,
   "id": "new_employee", "name": "New employee",
-  "units": "fraction", "aspect": 1,
+  "source": "employees",
+  "units": "fraction", "aspect": 1, "width": 800,
   "nodes": [
     { "id": "firstName", "type": "text", "x": 0.04, "y": 0.15, "w": 0.4475, "h": 0.08, "z": 2,
       "props": { "label": "First name", "name": "firstName", "required": true, "validation": { "maxLength": 80 } } }
@@ -135,7 +183,7 @@ 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`). Text and controls scale with it, so a screen looks the same at any width.
+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.
 
 ## Three ways to use it
 
@@ -151,7 +199,7 @@ Styles are namespaced `.xeplr-factory-*` and read the xeplr theme variables with
 
 ```sh
 npm install
-npm run dev     # http://localhost:19006 — builder + saved screen, with an in-memory stand-in app
+npm run dev     # http://localhost:19006 — Screen · List / Edit and Designer · List / Edit for the example employee, records kept in localStorage
 ```
 
 ## Files
@@ -161,15 +209,18 @@ 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              ─ initial values, parsing, field validation, formSchema
-  generate.js            ─ screenFromSpec
+  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
+  tableSchema.js         ─ a form → its table; the publish plan (create / add / widen / confirmed drops)
+  remote.js              ─ createFactoryApi: the calls to @xeplr/factory's routes
   model.js               ─ everything above, React-free
   useFactoryBuilder.js   ─ builder controller
   useFactoryScreen.js    ─ screen controller
-  designs/               ─ BuilderSample, ScreenSample, ControlView, Palette, PropertyPanel, factory.css
+  designs/               ─ BuilderSample, ScreenSample, ControlView, ListView, Palette, PropertyPanel, styles.js, factory.css
   pages.jsx              ─ FactoryBuilder, FactoryScreen
-bin/xeplr-factory.js     ─ generate / validate / controls / schema
-examples/                ─ new-employee spec and screen
+bin/xeplr-factory.js     ─ screens / generate / validate / controls / schema
+examples/                ─ employee.entity.json and what `screens` makes of it
 dev/                     ─ the stand-in app for `npm run dev` (not published)
 ```
 

package/bin/xeplr-factory.js

@@ -5,6 +5,9 @@
 // turn a short spec into a laid-out document, and check a document before
 // handing it to an app, with errors precise enough to fix without guessing.
 //
+//   xeplr-factory screens entity.json [-o dir]           an entity → list + edit screens, their .jsx pages, a hooks stub
+//   xeplr-factory migration edit.screen.json [--from previous.screen.json] [-o migrations/]
+//                                                        the SQL that makes the table match the form
 //   xeplr-factory generate spec.json [-o screen.json]   spec → laid-out document
 //   xeplr-factory validate screen.json                   check a document (exit 1 on problems)
 //   xeplr-factory controls                               the controls and their props
@@ -12,13 +15,18 @@
 //
 // "-" as the file reads stdin.
 
-import { readFileSync, writeFileSync } from 'node:fs'
+import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync } from 'node:fs'
+import path from 'node:path'
 import { CONTROLS } from '../src/controls.js'
 import { screenFromSpec } from '../src/generate.js'
+import { scaffoldEntity } from '../src/scaffold.js'
+import { migrationFor, nextMigrationName } from '../src/tableSchema.js'
 import { validateDocument } from '../src/validateDocument.js'
 import { formSchema } from '../src/values.js'
 
 const USAGE = `usage:
+  xeplr-factory screens <entity.json|-> [-o <dir>] [--force]
+  xeplr-factory migration <edit.screen.json> [--from <previous.screen.json>] [-o <migrations dir>]
   xeplr-factory generate <spec.json|-> [-o <out.json>]
   xeplr-factory validate <screen.json|->
   xeplr-factory controls
@@ -62,6 +70,68 @@ switch (cmd) {
     break
   }
 
+  case 'screens': {
+    if (!args[0]) fail(USAGE, 2)
+    const o = args.indexOf('-o')
+    const dir = o !== -1 ? args[o + 1] : '.'
+    const force = args.includes('--force')
+    let result
+    try {
+      result = scaffoldEntity(readJson(args[0]))
+    } catch (err) {
+      fail(err.message)
+    }
+    // The hooks file is the app's own code — kept as it is, even with --force.
+    const hooksFile = Object.keys(result.files).find((f) => f.endsWith('.hooks.js'))
+    const keptHooks = hooksFile && existsSync(path.join(dir, hooksFile)) ? hooksFile : null
+    const writing = Object.keys(result.files).filter((f) => f !== keptHooks)
+    const targets = writing.map((f) => path.join(dir, f))
+    // Never overwrite a screen someone has since refined in the designer.
+    const existing = targets.filter((t) => existsSync(t))
+    if (existing.length && !force) fail(`would overwrite ${existing.join(', ')} — pass --force to replace them`)
+    mkdirSync(dir, { recursive: true })
+    writing.forEach((f) => writeFileSync(path.join(dir, f), result.files[f]))
+    process.stderr.write(`wrote ${targets.join(', ')}\n`)
+    if (keptHooks) process.stderr.write(`kept ${path.join(dir, keptHooks)} — it is your code\n`)
+    process.stderr.write(`list screen "${result.list.id}" opens "${result.edit.id}" for Edit / New; both use table "${result.edit.source}"\n`)
+    break
+  }
+
+  case 'migration': {
+    if (!args[0]) fail(USAGE, 2)
+    const f = args.indexOf('--from')
+    const o = args.indexOf('-o')
+    const next = readJson(args[0])
+    const previous = f !== -1 ? readJson(args[f + 1]) : null
+    for (const [label, doc] of [['screen', next], ['--from screen', previous]]) {
+      if (!doc) continue
+      const { ok, errors } = validateDocument(doc)
+      if (!ok) fail(`the ${label} is not valid — run validate first (${errors.length} problems)`)
+    }
+    let result
+    try {
+      result = migrationFor(previous, next)
+    } catch (err) {
+      fail(err.message)
+    }
+    if (result.empty) {
+      process.stderr.write(`"${result.table}" already matches the form — no migration needed\n`)
+      if (result.diff.unused.length) process.stderr.write(`(columns no longer on the screen, kept: ${result.diff.unused.map((c) => c.name).join(', ')})\n`)
+      break
+    }
+    if (o !== -1) {
+      const dir = args[o + 1]
+      const existing = existsSync(dir) ? readdirSync(dir).filter((x) => x.endsWith('.sql')) : []
+      const file = path.join(dir, nextMigrationName(existing, result.table, result.diff.create))
+      mkdirSync(dir, { recursive: true })
+      writeFileSync(file, result.sql)
+      process.stderr.write(`wrote ${file}\n`)
+    } else {
+      process.stdout.write(result.sql)
+    }
+    break
+  }
+
   case 'validate': {
     if (!args[0]) fail(USAGE, 2)
     const { ok, errors } = validateDocument(readJson(args[0]))
@@ -80,6 +150,7 @@ switch (cmd) {
       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`)
+      if (c.styles && c.styles.length) process.stdout.write(`          style: ${c.styles.join(', ')}\n`)
     })
     break
   }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@xeplr/ui-factory",
-  "version": "1.0.1",
-  "description": "Design data-entry screens on @xeplr/ui-canvas, save them as JSON, render them as working forms — built for Claude to draft and people to refine",
+  "version": "1.0.3",
+  "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",
   "exports": {
@@ -45,13 +45,17 @@
     "access": "public"
   },
   "peerDependencies": {
+    "@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"
   },
   "devDependencies": {
+    "@tanstack/react-table": "^8.21.3",
     "@vitejs/plugin-react": "^5.2.0",
     "@xeplr/schema-handler": "^1.0.5",
     "@xeplr/ui-canvas": "^1.0.1",
+    "@xeplr/ui-table": "^1.0.6",
     "react": "^19.2.4",
     "react-dom": "^19.2.4",
     "vite": "^7.3.1"