@xeplr/ui-factory 1.0.1

package/AUTHORING.md

@@ -0,0 +1,133 @@
+# Authoring screens with @xeplr/ui-factory
+
+This guide is for whoever **writes** a screen definition — usually Claude, from a request like *"make a form for a new employee with name, email, department and start date"*. A person then refines the result in the builder.
+
+## 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:
+   ```sh
+   npx xeplr-factory generate spec.json -o screen.json
+   ```
+   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:
+   ```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.
+
+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
+
+```json
+{
+  "name": "New employee",
+  "columns": 2,
+  "fields": [
+    { "label": "First name", "required": true, "validation": { "maxLength": 80 } },
+    { "label": "Last name", "required": true },
+    { "label": "Work email", "required": true,
+      "validation": { "pattern": "^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$", "patternMessage": "Enter a valid email address" } },
+    { "type": "label", "text": "Employment", "variant": "subheading" },
+    { "label": "Department", "type": "dropdown", "table": "departments", "required": true },
+    { "label": "Employment type", "type": "dropdown", "options": ["Full time", "Part time", "Contract"] },
+    { "label": "Start date", "type": "date", "required": true },
+    { "label": "Annual salary", "type": "number", "validation": { "min": 0 } },
+    { "label": "Remote", "type": "checkbox" },
+    { "label": "Notes", "type": "textarea", "validation": { "maxLength": 1000 } }
+  ],
+  "submit": "Create employee",
+  "reset": "Clear"
+}
+```
+
+| key | meaning |
+|---|---|
+| `name` | **required** — the screen's title |
+| `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 |
+
+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 |
+| `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 |
+| `text`, `variant` | `label` only — `variant` is `heading`, `subheading` (default for a section) or `text` |
+
+## Validation rules
+
+| control | rules |
+|---|---|
+| `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"` |
+| `checkbox`, `dropdown` | none (use `required`) |
+
+Anything else is rejected, with the list of what is allowed.
+
+## Dropdowns
+
+A dropdown **always saves an `id` and shows a `name`.**
+
+- **Fixed values** — `options`. Use when the choices belong to the form: employment type, yes/no/maybe, priority.
+- **A table** — `table`. Use when the choices are records the app already keeps: departments, locations, managers. The factory never queries the database: the app returns `[{ id, name }]` rows for the table. Use the app's real table name; if you do not know it, ask, or leave a fixed list and say so.
+
+## Choosing controls
+
+| the request says | use |
+|---|---|
+| a name, title, email, phone, code | `text` (add a `pattern` for email/phone/code formats) |
+| notes, description, address, comments | `textarea` |
+| amount, salary, quantity, age | `number` (`integer: true` for counts) |
+| a date — birth, start, due | `date` |
+| yes/no, agree, active, remote | `checkbox` |
+| one of a known set | `dropdown` with `options` |
+| one of the app's records | `dropdown` with `table` |
+| a section title between groups | `{ "type": "label", "text": "…", "variant": "subheading" }` |
+
+Keep labels short and in sentence case ("Start date", not "START DATE:"). Mark only what the request needs as required.
+
+## The document, if you edit it directly
+
+```json
+{
+  "kind": "xeplr-screen", "version": 1,
+  "id": "new_employee", "name": "New employee",
+  "units": "fraction", "aspect": 1,
+  "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 } }
+  ]
+}
+```
+
+- `x`, `w` are fractions of the screen width; `y`, `h` fractions of a page (with `aspect: 1`, also of the width). `x + w` must not exceed 1.
+- 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`.
+
+## Commands
+
+```sh
+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
+npx xeplr-factory schema <screen.json|->                       # the form's @xeplr/schema-handler schema
+```
+
+The `schema` output is what the app's server checks a submission against: `applySchema(formSchema(document), body)`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Xeplr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,184 @@
+# @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.
+
+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.
+
+(The package name on npm is `@xeplr/ui-factory` — the GitHub repo and folder are named `xeplr-ui-factory`.)
+
+## Why
+
+Most internal apps are a long tail of forms, and every one of them is hand-built: markup, layout, validation in the browser, validation again on the server, and dropdowns wired to tables. This turns a form into **data**:
+
+- a person — or Claude — describes the screen once;
+- the builder lets anyone move, resize and adjust it without a developer;
+- the renderer runs it, and the server checks submissions against the **same** rules.
+
+**The factory never has a database.** Your app stores screen documents and supplies the rows dropdowns read. The factory draws, edits and validates.
+
+## Install
+
+```sh
+npm i @xeplr/ui-factory @xeplr/ui-canvas
+```
+
+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).
+
+## The builder
+
+```jsx
+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
+  />
+</div>
+```
+
+- 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.
+
+## The screen
+
+```jsx
+import { FactoryScreen } from '@xeplr/ui-factory'
+
+<FactoryScreen
+  document={screen}
+  values={employee}                                   // optional: the record being edited
+  fetchOptions={async ({ table }) => api.options(table)}
+  onSubmit={async (values) => api.saveEmployee(values)}
+/>
+```
+
+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).
+
+On your server, check the submission against the same rules with [`@xeplr/schema-handler`](https://www.npmjs.com/package/@xeplr/schema-handler):
+
+```js
+import { formSchema } from '@xeplr/ui-factory/model'
+import schemaHandler from '@xeplr/schema-handler'          // CommonJS: default import in ESM,
+                                                          // or require('@xeplr/schema-handler')
+const clean = schemaHandler.applySchema(formSchema(screen), req.body)   // throws ValidationError listing each field
+```
+
+## Controls
+
+| type | value | validation |
+|---|---|---|
+| `text` | string | `minLength`, `maxLength`, `pattern`, `patternMessage` |
+| `textarea` | string | `minLength`, `maxLength` |
+| `number` | number | `min`, `max`, `integer` |
+| `date` | `"YYYY-MM-DD"` | `min`, `max` |
+| `checkbox` | boolean | `required` = must be ticked |
+| `dropdown` | option id | — |
+| `label` | — | heading, subheading or text |
+| `button` | — | submit or reset |
+
+### Dropdown options
+
+A dropdown **always saves an `id` and shows a `name`**, from either source:
+
+```json
+{ "source": "static", "options": [{ "id": "ft", "name": "Full time" }, { "id": "pt", "name": "Part time" }] }
+{ "source": "table",  "table": "departments" }
+```
+
+For a table, your `fetchOptions({ table })` returns `[{ id, name }]` — in SQL terms, `select id, name from departments`. The factory never builds or runs a query.
+
+## Drafting screens with Claude
+
+A screen can start from a **spec** — what is on it, in order — instead of coordinates:
+
+```js
+import { screenFromSpec } from '@xeplr/ui-factory/model'
+
+const screen = screenFromSpec({
+  name: 'New employee',
+  fields: [
+    { label: 'First name', required: true },
+    { label: 'Last name', required: true },
+    { label: 'Department', type: 'dropdown', table: 'departments', required: true },
+    { label: 'Employment type', type: 'dropdown', options: ['Full time', 'Part time'] },
+    { label: 'Start date', type: 'date' }
+  ]
+})
+```
+
+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 validate screen.json      # every problem, with its path
+npx xeplr-factory controls                   # controls, props and rules
+```
+
+[AUTHORING.md](./AUTHORING.md) is the full guide for writing screens: the spec, every control and rule, and how to choose between them.
+
+## The document
+
+```json
+{
+  "kind": "xeplr-screen", "version": 1,
+  "id": "new_employee", "name": "New employee",
+  "units": "fraction", "aspect": 1,
+  "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 } } }
+  ]
+}
+```
+
+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.
+
+## Three ways to use it
+
+1. **Ready-made** — `<FactoryBuilder>` and `<FactoryScreen>`.
+2. **Your own design** — `useFactoryBuilder` / `useFactoryScreen` hold all the state and actions; draw them however you like.
+3. **Model only** — `@xeplr/ui-factory/model` has no React: `screenFromSpec`, `validateDocument`, `formSchema`, `validateValues`, and the document operations (`addControl`, `moveNode`, `setNodeProperty`, …).
+
+## 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`.
+
+## Try it
+
+```sh
+npm install
+npm run dev     # http://localhost:19006 — builder + saved screen, with an in-memory stand-in app
+```
+
+## Files
+
+```
+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
+  model.js               ─ everything above, React-free
+  useFactoryBuilder.js   ─ builder controller
+  useFactoryScreen.js    ─ screen controller
+  designs/               ─ BuilderSample, ScreenSample, ControlView, Palette, PropertyPanel, factory.css
+  pages.jsx              ─ FactoryBuilder, FactoryScreen
+bin/xeplr-factory.js     ─ generate / validate / controls / schema
+examples/                ─ new-employee spec and screen
+dev/                     ─ the stand-in app for `npm run dev` (not published)
+```
+
+## Tests
+
+```sh
+npm test
+```
+
+## License
+
+MIT

package/bin/xeplr-factory.js

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+// xeplr-factory — the command-line side of @xeplr/ui-factory.
+//
+// Mostly for Claude, which drafts screens from plain-English requests: it can
+// 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 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
+//   xeplr-factory schema screen.json                     the form's @xeplr/schema-handler schema
+//
+// "-" as the file reads stdin.
+
+import { readFileSync, writeFileSync } from 'node:fs'
+import { CONTROLS } from '../src/controls.js'
+import { screenFromSpec } from '../src/generate.js'
+import { validateDocument } from '../src/validateDocument.js'
+import { formSchema } from '../src/values.js'
+
+const USAGE = `usage:
+  xeplr-factory generate <spec.json|-> [-o <out.json>]
+  xeplr-factory validate <screen.json|->
+  xeplr-factory controls
+  xeplr-factory schema <screen.json|->`
+
+function readJson(file) {
+  const text = readFileSync(file === '-' ? 0 : file, 'utf8')
+  try {
+    return JSON.parse(text)
+  } catch (err) {
+    fail(`${file === '-' ? 'stdin' : file} is not valid JSON: ${err.message}`)
+  }
+}
+
+function fail(message, code = 1) {
+  process.stderr.write(message + '\n')
+  process.exit(code)
+}
+
+function out(json, outFile) {
+  const text = JSON.stringify(json, null, 2) + '\n'
+  if (outFile) writeFileSync(outFile, text)
+  else process.stdout.write(text)
+}
+
+const [cmd, ...args] = process.argv.slice(2)
+
+switch (cmd) {
+  case 'generate': {
+    if (!args[0]) fail(USAGE, 2)
+    const o = args.indexOf('-o')
+    const outFile = o !== -1 ? args[o + 1] : null
+    let doc
+    try {
+      doc = screenFromSpec(readJson(args[0]))
+    } catch (err) {
+      fail(err.message)
+    }
+    out(doc, outFile)
+    if (outFile) process.stderr.write(`wrote ${outFile} — ${doc.nodes.length} controls\n`)
+    break
+  }
+
+  case 'validate': {
+    if (!args[0]) fail(USAGE, 2)
+    const { ok, errors } = validateDocument(readJson(args[0]))
+    if (ok) {
+      process.stdout.write('ok — valid screen document\n')
+    } else {
+      process.stdout.write(`${errors.length} problem${errors.length === 1 ? '' : 's'}:\n`)
+      errors.forEach((e) => process.stdout.write(`  ${e.path || '(document)'}: ${e.message}\n`))
+      process.exit(1)
+    }
+    break
+  }
+
+  case 'controls': {
+    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`)
+    })
+    break
+  }
+
+  case 'schema': {
+    if (!args[0]) fail(USAGE, 2)
+    const doc = readJson(args[0])
+    const { ok, errors } = validateDocument(doc)
+    if (!ok) fail(`invalid document — run validate first (${errors.length} problems)`)
+    out(formSchema(doc))
+    break
+  }
+
+  default:
+    fail(USAGE, cmd ? 2 : 0)
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "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",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./model": "./src/model.js",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "xeplr-factory": "bin/xeplr-factory.js"
+  },
+  "files": [
+    "src/",
+    "bin/",
+    "AUTHORING.md"
+  ],
+  "scripts": {
+    "dev": "vite",
+    "test": "for f in test/*.test.js; do node \"$f\" || exit 1; done"
+  },
+  "keywords": [
+    "form-builder",
+    "ui-builder",
+    "screen-designer",
+    "canvas",
+    "react",
+    "low-code",
+    "claude",
+    "xeplr"
+  ],
+  "author": "xeplr",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Xeplr/xeplr-ui-factory"
+  },
+  "homepage": "https://github.com/Xeplr/xeplr-ui-factory#readme",
+  "bugs": {
+    "url": "https://github.com/Xeplr/xeplr-ui-factory/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@xeplr/ui-canvas": "^1.0.2",
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-react": "^5.2.0",
+    "@xeplr/schema-handler": "^1.0.5",
+    "@xeplr/ui-canvas": "^1.0.1",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "vite": "^7.3.1"
+  }
+}