@xeplr/cli 0.2.0 → 0.3.1

package/README.md

@@ -77,6 +77,7 @@ These are architecture decisions, not defaults to tune — each one exists becau
 | **`REDIS_PREFIX` is required and unique per app** (`api/development.env`, set to `<name>:`). | `@xeplr/auth`, `@xeplr/utils` | Two apps on one Redis under the shared default serve each other's sessions, menus and API permissions. Sign-in refuses to start without it, or with `xeplr:`. |
 | **Designing, new forms and publishing are Super Admin only.** | `api/routes/access.js`, `@xeplr/auth` menu routes | Publishing changes database tables. Every other screen route checks the permission catalog. |
 | **The browser is not a security boundary.** Front-end hooks (`ui/src/pages/Edit<Form>.jsx`) shape what people see and send; anything that must hold goes in server hooks (`api/screens/<form>/<form>.hooks.js`); data shape in the model (`<form>.model.js`). | `@xeplr/ui-factory`, `@xeplr/factory` | |
+| **Anything every app would write identically lives in a package, not in the generated app.** A generated app is a starting point that then lives its own life — glue copied into it can never be fixed centrally, so an app made last month keeps that copy forever. When the flow designer needed this app's forms as its Screen steps, the wiring went into `@xeplr/ui-factory` (`useScreenSource`) and the generated page passes two props. | `@xeplr/ui-factory`, `@xeplr/ui-workflow` | A fix or a new control type has to reach apps that already exist, and it cannot reach code that was copied into them. `test/cli.test.js` fails if the glue reappears in the generated app. |
 | **Every data address is under `/api`.** | `api/routes`, `ui/vite.config.js` | A page path and a data path must never collide. |
 | **No guessed database names or connections.** | `api/development.env` | A wrong-but-present value starts cleanly and reads as empty data. |
 | **Email is checked at start, never fatal.** The sign-in banner shows `email ✓ …` or `✗ NOT WORKING — reason`. | `@xeplr/auth` | Sign-in works without email; activation, invite and reset links cannot be sent until `EMAIL_PROVIDER` is set. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xeplr/cli",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Creates a working xeplr application — API, sign-in and UI — from a few answers.",
   "license": "MIT",
   "author": "xeppie <admin@xeplr.com>",

package/templates/api/README.md

@@ -38,4 +38,5 @@ The API (`@xeplr/base-apis`) and the sign-in service (`@xeplr/auth`), with this
 | `__PREFIX___CONNECTION`, `AUTH_DB_CONNECTION_INFO_ENCRYPTED` | the database, encrypted — `npm run db:encrypt` |
 | `DB_API`, `AUTH_DB_NAME` | the two database names — never guessed |
 | `AUTH_SUPER_ADMIN_EMAIL` / `_PASSWORD` | the first account — created once, when the sign-in database is first set up |
+| `AUTH_TENANT_HEADER` | `none`: one set of roles for everyone. A multi-tenant app names its company header (e.g. `x-company-id`), so a role made inside a company belongs to it |
 | `EMAIL_PROVIDER` and its settings | optional; without them sign-in works, but activation and reset links cannot be sent |

package/templates/api/bin/workflow

@@ -7,7 +7,7 @@
 //
 // The SAME workflow as the embedded one (../workflow.js): this app's database,
 // this app's tenancy and membership gate, the same permission checks, and the
-// same path — /api/workflow/flows — so the browser cannot tell the two apart.
+// same path — /api/workflow — so the browser cannot tell the two apart.
 // What routes /api/workflow here: ui/.env WORKFLOW_URL for Vite's dev proxy,
 // nginx in production (README, "Production").
 require('dotenv').config({ path: require('path').join(__dirname, '..', (process.env.NODE_ENV || 'development') + '.env') });
@@ -28,7 +28,7 @@ async function start() {
   // This app's tenancy levels, registered exactly as the API registers them.
   await require('../db/setup');
   var app = require('../app');
-  var flowsRouter = await require('../workflow')(app.memberGate);
+  var workflowRouter = await require('../workflow')(app.memberGate);
 
   var health = express.Router();
   health.get('/', function(req, res) { res.json({ status: 'ok', service: 'workflow' }); });
@@ -41,7 +41,7 @@ async function start() {
     middleware: app.middleware(),
     routes: {
       '/health': health,
-      '/api/workflow/flows': flowsRouter
+      '/api/workflow': workflowRouter
     }
   });
 }

package/templates/api/development.env.tpl

@@ -50,6 +50,12 @@ XEPLR_AUTH_MIGRATIONS=./node_modules/@xeplr/factory/migrations-auth,./migrations
 AUTH_SUPER_ADMIN_EMAIL=__ADMIN_EMAIL__
 AUTH_SUPER_ADMIN_PASSWORD=__ADMIN_PASSWORD__
 
+# ── Which company a role belongs to ──
+# none: this app has one set of roles for everyone. A multi-tenant app names
+# the header that carries the company id instead (e.g. x-company-id), so a
+# role made inside a company belongs to that company.
+AUTH_TENANT_HEADER=none
+
 # ── Links that go out in emails ──
 # FULLY QUALIFIED, and they point at UI pages rather than at the API. The
 # sign-in service builds these links and appends the token as ?token=... — an

package/templates/api/package.json

@@ -21,10 +21,10 @@
     "@xeplr/auth": "^1.1.4",
     "@xeplr/base-apis": "^2.0.0",
     "@xeplr/db": "^1.0.6",
-    "@xeplr/factory": "^1.0.6",
-    "@xeplr/ui-factory": "^1.0.14",
+    "@xeplr/factory": "^1.1.0",
+    "@xeplr/ui-factory": "^1.1.0",
     "@xeplr/utils": "^1.0.11",
-    "@xeplr/workflow": "^1.1.0",
+    "@xeplr/workflow": "^1.2.0",
     "dotenv": "^17.4.2",
     "express": "^5.2.0",
     "multer": "^2.0.2"

package/templates/api/production.env.example

@@ -30,6 +30,8 @@ AUTH_URL=http://127.0.0.1:__AUTH_PORT__
 XEPLR_AUTH_MIGRATIONS=./node_modules/@xeplr/factory/migrations-auth,./migrations-auth,./node_modules/@xeplr/workflow/migrations-auth
 AUTH_SUPER_ADMIN_EMAIL=
 AUTH_SUPER_ADMIN_PASSWORD=
+# none for one set of roles; a multi-tenant app names its company header, e.g. x-company-id
+AUTH_TENANT_HEADER=none
 
 # ── Public addresses (what people's browsers open) ──
 AUTH_ACTIVATION_URL=https://app.example.com/auth/activate

package/templates/api/routes/flows.js

@@ -20,24 +20,28 @@
 //                    "Start flow run"…), granted by @xeplr/workflow's
 //                    migrations-auth — in XEPLR_AUTH_MIGRATIONS.
 //
-// Mounted by routes/index.js at /api/workflow/flows, behind this app's auth gate.
+// Mounted by routes/index.js at /api/workflow, behind this app's auth gate.
+// Everything Workflow serves lives under it:
+//   /api/workflow/flows       the flows people walk through (Journey)
+//   /api/workflow/workflows   the designer's document API
+//   /api/workflow/actions     what a step can DO, for the palette
 var express = require('express');
 
 var router = express.Router();
-var flows = null;
+var workflow = null;
 
 router.use(function(req, res, next) {
   if (process.env.WORKFLOW_PORT) {
     return res.status(404).json({ message: 'Workflow runs on its own port (WORKFLOW_PORT) — route /api/workflow there (ui/.env WORKFLOW_URL, or nginx)' });
   }
   // Only before startup has finished — bin/www mounts it before listening.
-  if (!flows) return res.status(503).json({ message: 'Flows are still starting' });
-  return flows(req, res, next);
+  if (!workflow) return res.status(503).json({ message: 'Flows are still starting' });
+  return workflow(req, res, next);
 });
 
-/** bin/www hands over registerWorkflow's flowsRouter, already gated. */
-router.mount = function(flowsRouter) {
-  flows = flowsRouter;
+/** bin/www hands over registerWorkflow's router, already gated. */
+router.mount = function(workflowRouter) {
+  workflow = workflowRouter;
 };
 
 module.exports = router;

package/templates/api/routes/index.js

@@ -34,9 +34,9 @@ router.get('/whoami', function(req, res) {
 //   var { genericRoute } = require('@xeplr/base-apis');
 //   router.use('/api/things', genericRoute({ key: 'thing', model: require('../models').Thing }));
 
-// Flows: Xeplr Workflow, at /api/workflow/flows — inside this API, or on its
+// Flows: Xeplr Workflow, at /api/workflow — inside this API, or on its
 // own port with WORKFLOW_PORT (see routes/flows.js). The path is the same
 // either way: the browser never knows which.
-router.use('/api/workflow/flows', require('./flows'));
+router.use('/api/workflow', require('./flows'));
 
 module.exports = router;

package/templates/api/workflow.js

@@ -9,7 +9,14 @@
 // @xeplr/workflow's migrations-auth, which XEPLR_AUTH_MIGRATIONS loads.
 var { registerWorkflow } = require('@xeplr/workflow');
 
-/** Runs workflow's migrations, and returns its flows router — already gated. */
+/**
+ * Runs workflow's migrations and returns its ROUTER — already gated.
+ *
+ * The whole router, not just the flows facade: it carries `/flows` (the
+ * screens a person walks through) AND `/workflows` (the designer's own
+ * document API). One designer serves both — @xeplr/ui-workflow's canvas, the
+ * same one every xeplr product uses — so the app has to serve what it reads.
+ */
 module.exports = async function startWorkflow(memberGate) {
   var workflow = await registerWorkflow({
     applicationId: '__NAME__',
@@ -23,5 +30,5 @@ module.exports = async function startWorkflow(memberGate) {
     access: true,
     mtMembershipGate: memberGate
   });
-  return workflow.flowsRouter;
+  return workflow.router;
 };

package/templates/ui/package.json

@@ -11,12 +11,14 @@
   "dependencies": {
     "@tanstack/react-table": "^8.21.3",
     "@xeplr/ui-account": "^1.0.9",
-    "@xeplr/ui-canvas": "^1.0.2",
-    "@xeplr/ui-factory": "^1.0.14",
+    "@xeplr/ui-canvas": "^1.1.0",
+    "@xeplr/ui-factory": "^1.1.0",
     "@xeplr/ui-table": "^1.0.6",
     "react": "^19.2.4",
     "react-dom": "^19.2.4",
-    "react-router-dom": "^7.13.2"
+    "react-router-dom": "^7.13.2",
+    "@xeplr/ui-workflow": "^1.2.0",
+    "@xeplr/ui-utils": "^1.0.2"
   },
   "devDependencies": {
     "@vitejs/plugin-react": "^5.2.0",

package/templates/ui/src/pages/ConfigureUI.jsx

@@ -2,6 +2,9 @@
 //
 //   Forms  every UI in the app: make one, design it, publish it, open it, add it
 //          to the side rail
+//   Masters the lists the rest of the app points at — departments, statuses,
+//          countries. Ordinary forms with a flag, gathered in one place because
+//          that is what they are: reference data, not daily work
 //   Menu   the side rail's items: rename, reorder, hide
 //   Flows  forms one after another — what is filled in decides the next; run by
 //          Xeplr Workflow, and says how to connect it until it is
@@ -10,11 +13,13 @@
 // people use.
 import { useSearchParams } from 'react-router-dom'
 import Forms from './Forms.jsx'
+import Masters from './Masters.jsx'
 import MenuSettings from './MenuSettings.jsx'
 import Flows from './Flows.jsx'
 
 const TABS = [
   { id: 'forms', label: 'Forms', Page: Forms },
+  { id: 'masters', label: 'Masters', Page: Masters },
   { id: 'flows', label: 'Flows', Page: Flows },
   { id: 'menu', label: 'Menu', Page: MenuSettings }
 ]

package/templates/ui/src/pages/FlowDesigner.jsx

@@ -1,37 +1,54 @@
-// One flow, on the canvas: the published forms on the left, arrows between
-// them, and on the right what happens after the screen you picked. Saves
-// itself; Publish is what people then walk through.
-import { useEffect, useState } from 'react'
-import { useParams, Link } from 'react-router-dom'
-import { FlowBuilder } from '@xeplr/ui-factory'
-import { flows } from '../api/flows.js'
+// ONE FLOW, ON WORKFLOW'S OWN CANVAS.
+//
+// The designer is a component from @xeplr/ui-workflow — the same one BI and
+// every other xeplr product uses — dropped straight onto this page. It is not
+// a section mounted at URLs of its own: this app already has a page for it,
+// inside its own shell, and the designer renders where it is put.
+//
+// There used to be a second, screens-only builder here (@xeplr/ui-factory's
+// FlowBuilder). One designer over one engine is the point: the trigger box,
+// the condition boxes and the reference pickers are built once, and this app
+// gets them by upgrading a package.
+//
+// THIS APP'S FORMS ARE THE FLOW'S SCREENS. A step can show one and wait for
+// somebody to fill it in, and `useScreenSource` is @xeplr/ui-factory's answer
+// to the two things the designer asks its host: which screens exist (with
+// what each one hands back, so a later step can pick `title` by name) and how
+// to design one without leaving the flow. Two props, because the alternative
+// was the same twenty lines in every app — and a copy in your app could never
+// be fixed once.
+//
+// WHERE THE API IS: /api/workflow, always — the dev proxy (vite.config.js) or
+// nginx decides whether that is this API or Workflow on its own port.
+import { useParams, useNavigate } from 'react-router-dom'
+import { WorkflowDesigner } from '@xeplr/ui-workflow'
+import { useScreenSource, FactoryBuilder } from '@xeplr/ui-factory'
 import { factory } from '../api/factory.js'
 
 export default function FlowDesigner() {
   const { flow: key } = useParams()
-  const [flow, setFlow] = useState(null)
-  const [screens, setScreens] = useState([])
-  const [error, setError] = useState(null)
+  const navigate = useNavigate()
+  const { screens, screenEditor } = useScreenSource(factory, { Builder: FactoryBuilder })
 
-  useEffect(() => {
-    flows.loadFlow(key).then(setFlow, (e) => setError(e.message))
-    // A step is a FORM (an edit screen) that is published: what people will
-    // actually see, and something they can fill in.
-    factory.listScreens().then((rows) => setScreens(rows
-      .filter((s) => /_edit$/.test(s.screenKey) && s.version !== null)
-      .map((s) => ({ id: s.screenKey, name: s.name }))), () => {})
-  }, [key])
-
-  if (error) return <div className="app-page"><div className="app-error">{error}</div></div>
-  if (!flow) return null
   return (
     <div className="app-designer">
-      <div className="app-designer-bar">
-        <Link to="/configure?tab=flows">← All flows</Link>
-      </div>
-      <div className="app-designer-canvas">
-        <FlowBuilder {...flows.builderProps} flow={flow} screens={screens} loadScreen={factory.loadScreen} />
-      </div>
+      <WorkflowDesigner
+        apiBase="/api/workflow"
+        screens={screens}
+        screenEditor={screenEditor}
+        // BY KEY, because that is what this app's URLs carry:
+        // /configure/flows/leave_request. A flow is created on the Flows page
+        // with a key made from its name, and that key is how it is addressed
+        // for the rest of its life — a readable link that survives a rebuild
+        // minting new ids.
+        workflowKey={key === 'new' ? undefined : key}
+        newKind={key === 'new' ? 'workflow' : undefined}
+        // Only reachable from /configure/flows/new, which this app does not
+        // link to — the Flows page creates the flow first, so the designer
+        // always opens on one that exists.
+        onOpened={(saved) => navigate('/configure/flows/' + saved, { replace: true })}
+        onBack={() => navigate('/configure?tab=flows')}
+      />
     </div>
   )
 }

package/templates/ui/src/pages/Flows.jsx

@@ -1,15 +1,29 @@
 // CONFIGURE UI → FLOWS — every journey across the app's forms.
 //
-// A flow is screens one after another: what someone fills in on one decides
-// which comes next. It is run by Xeplr Workflow, so a journey can be left and
-// picked up later — by someone else, on another day. Design it here; open it
-// at /journey/<key>.
+// A flow is what someone is walked through: screens one after another, and
+// whatever has to happen between them. What they fill in on one decides which
+// comes next. Xeplr Workflow runs it, so a journey can be left and picked up
+// later — by someone else, on another day. Design it here; open it at
+// /journey/<key>.
 //
-// Run by @xeplr/workflow inside this app's own API and database — nothing to
-// connect.
+// A FLOW IS AN ORDINARY WORKFLOW, addressed by a key this page makes from its
+// name. It used to be created as kind 'screens', which is a workflow whose
+// steps are GENERATED from a design held in another app — and that app was
+// the screens-only builder this one replaced. The designer then had to refuse
+// to edit its own flows ("designed in Configure UI"), which is how a flow
+// became a page you could open and not change.
+//
+// So a flow is a workflow now, and every kind of step is available inside it:
+// a Screen for the part a person fills in, an Action for the email that goes
+// out after it, a Condition for where it goes next. Flows created the old way
+// still appear here and still run; the designer shows them read-only.
 import { useEffect, useState } from 'react'
 import { Link, useNavigate } from 'react-router-dom'
-import { flows } from '../api/flows.js'
+import { listWorkflows, saveWorkflow, configureWorkflowApi } from '@xeplr/ui-workflow'
+
+// The same mount the designer uses. Said here as well because this page can
+// be the first one to ask, and a base set after the first request is too late.
+configureWorkflowApi('/api/workflow')
 
 export default function Flows() {
   const [list, setList] = useState(null)
@@ -18,7 +32,7 @@ export default function Flows() {
   const [name, setName] = useState('')
   const navigate = useNavigate()
 
-  const load = () => flows.listFlows().then(setList, (e) => {
+  const load = () => listWorkflows().then(setList, (e) => {
     const off = flowsOffline(e)
     if (off) setOffline(off)
     else setError(e.message)
@@ -31,7 +45,9 @@ export default function Flows() {
     if (!label) return
     const key = label.toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_+|_+$/g, '')
     try {
-      await flows.createFlow({ key, name: label })
+      // No steps: the designer is where those come from, and it opens on the
+      // flow this creates. `key` is what every link to it uses from here on.
+      await saveWorkflow({ name: label, key, kind: 'workflow', status: 'draft' })
       navigate(`/configure/flows/${key}`)
     } catch (err) {
       setError(err.message)
@@ -62,14 +78,20 @@ export default function Flows() {
           <thead><tr><th>Flow</th><th>Key</th><th>Status</th><th>Screens</th><th /></tr></thead>
           <tbody>
             {list.map((f) => (
-              <tr key={f.key}>
+              <tr key={f.id || f.key}>
                 <td><strong>{f.name}</strong></td>
-                <td className="app-sub">{f.key}</td>
-                <td>{f.status}</td>
+                <td className="app-sub">{f.key || '—'}</td>
+                <td>{f.kind === 'screens' ? f.status + ' · read-only' : f.status}</td>
                 <td>{typeof f.steps === 'number' ? f.steps : (f.steps || []).length}</td>
                 <td className="app-row-actions">
-                  <Link to={`/configure/flows/${f.key}`}>Design</Link>
-                  {f.status === 'published' && <Link to={`/journey/${f.key}`}>Open</Link>}
+                  {f.key && <Link to={`/configure/flows/${f.key}`}>Design</Link>}
+                  {/* PUBLISHING IS A SCREENS-FLOW IDEA: there, publish is what
+                      checks the design before somebody is walked through it.
+                      A flow drawn in the designer has no such step, so it can
+                      be opened as soon as it has one. */}
+                  {(f.kind === 'screens' ? f.status === 'published' : (f.steps || []).length > 0) && f.key && (
+                    <Link to={`/journey/${f.key}`}>Open</Link>
+                  )}
                 </td>
               </tr>
             ))}

package/templates/ui/src/pages/Forms.jsx

@@ -9,27 +9,56 @@
 // Claude can make forms too — see "Create a new UI" in CLAUDE.md.
 import { useCallback, useEffect, useState } from 'react'
 import { useNavigate } from 'react-router-dom'
-import { listMenuItems, addMenuItem, removeMenuItem, useAccess } from '@xeplr/ui-account'
+import { listMenuItems, addMenuItem, removeMenuItem, useAccess, getUsers } from '@xeplr/ui-account'
+import { deleteForm } from '@xeplr/ui-factory'
+// THE APP'S OWN DIALOGS. window.confirm cannot say which button is the
+// dangerous one and looks like a different piece of software appearing over
+// this one; a red box pinned to the page stays there until something else
+// replaces it, long after it has been read.
+import { raiseConfirm, raiseSnackbar } from '@xeplr/ui-utils'
 import { factory } from '../api/factory.js'
 import { FORM_MENU_PREFIX } from '../menu.js'
 
-/** listScreens rows → one entry per form: { key, name, source, list, edit }. */
+/**
+ * listScreens rows → one entry per form.
+ *
+ * `description` and `createdBy` travel with it because of the thing that
+ * happens once more than a handful of people can make forms: three of them
+ * are called "Inspection", and the fields say what each HOLDS, never what it
+ * was for or whose it is. Deciding which to keep is otherwise guesswork.
+ */
 function groupForms(rows) {
   const byKey = new Map()
   rows.forEach((row) => {
     const m = /^(.*)_(list|edit)$/.exec(row.screenKey)
     const key = m ? m[1] : row.screenKey
-    const entry = byKey.get(key) || { key, name: null, source: null, list: null, edit: null }
+    const entry = byKey.get(key) || {
+      key, name: null, source: null, list: null, edit: null,
+      description: null, createdBy: null, createdDate: null
+    }
     if (m) entry[m[2]] = row
     else entry.edit = row
     if (m && m[2] === 'list') entry.name = row.name
     entry.name = entry.name || row.name
     entry.source = entry.source || row.source
+    entry.description = entry.description || row.description
+    // The form's own half is the one that speaks for it; a list screen is
+    // only consulted when there is no other answer.
+    if (m && m[2] === 'edit') { entry.createdBy = row.createdBy; entry.createdDate = row.createdDate }
+    entry.createdBy = entry.createdBy || row.createdBy
+    entry.createdDate = entry.createdDate || row.createdDate
     byKey.set(key, entry)
   })
   return [...byKey.values()].sort((a, b) => String(a.name).localeCompare(String(b.name)))
 }
 
+/** "3 Feb 2026" — enough to tell two forms apart, no more. */
+function madeOn(when) {
+  if (!when) return null
+  const d = new Date(when)
+  return isNaN(d) ? null : d.toLocaleDateString(undefined, { day: 'numeric', month: 'short', year: 'numeric' })
+}
+
 function state(screen) {
   if (!screen) return { label: '—', unpublished: false }
   if (screen.version === null) return { label: 'Not published yet', unpublished: true }
@@ -50,16 +79,19 @@ export default function Forms() {
   const navigate = useNavigate()
   const { refreshAccess } = useAccess()
   const [forms, setForms] = useState(null)
+  // WHO MADE EACH ONE. The screens table keeps the maker's id; the names live
+  // in the sign-in service, so they are fetched once here and matched up.
+  // Failing to get them is not an error worth showing — the date alone still
+  // tells two forms of the same name apart.
+  const [people, setPeople] = useState({})
   const [inMenu, setInMenu] = useState(new Set())
-  const [error, setError] = useState(null)
-  const [notice, setNotice] = useState(null)
   const [label, setLabel] = useState('')
   const [key, setKey] = useState('')
   const [keyEdited, setKeyEdited] = useState(false)
   const [busy, setBusy] = useState(null)
 
   const load = useCallback(() => {
-    factory.listScreens().then((rows) => { setForms(groupForms(rows)); setError(null) }, (e) => setError(e.message))
+    factory.listScreens().then((rows) => setForms(groupForms(rows)), (e) => raiseSnackbar(e.message, { design: 'error' }))
     listMenuItems().then(
       (items) => setInMenu(new Set(items.filter((m) => m.name.startsWith(FORM_MENU_PREFIX) && !m.isHidden).map((m) => m.name.slice(FORM_MENU_PREFIX.length)))),
       () => {}
@@ -67,6 +99,21 @@ export default function Forms() {
   }, [])
   useEffect(load, [load])
 
+  // Once. A name per row would be one request per form, and these change far
+  // more slowly than the page is opened.
+  useEffect(() => {
+    let cancelled = false
+    getUsers()
+      .then((rows) => {
+        if (cancelled) return
+        const by = {}
+        ;(rows || []).forEach((u) => { by[u.id] = u.name || u.email || u.id })
+        setPeople(by)
+      })
+      .catch(() => {})
+    return () => { cancelled = true }
+  }, [])
+
   const onLabel = (value) => {
     setLabel(value)
     if (!keyEdited) setKey(suggestKey(value))
@@ -79,28 +126,63 @@ export default function Forms() {
       const made = await factory.createEntity({ key: key.trim(), label: label.trim() })
       navigate('/configure/forms/' + made.key + '/design/form')
     } catch (err) {
-      setError(err.message)
+      raiseSnackbar(err.message, { design: 'error' })
       setBusy(null)
     }
   }
 
   // The form first — publishing it creates or changes the table — then the list.
+  /**
+   * Delete a form. Asked first, in the words of what will actually happen
+   * rather than "are you sure": the design goes, and the records do not
+   * unless there are none.
+   */
+  const remove = async (form) => {
+    const ok = await raiseConfirm(
+      'Its design goes. Its table and any records in it are kept unless the table is empty.',
+      {
+        title: 'Delete "' + (form.name || form.key) + '"?',
+        confirmLabel: 'Delete',
+        // Red, because it cannot be undone from here.
+        danger: true
+      }
+    )
+    if (!ok) return
+    setBusy(form.key)
+    try {
+      const out = await deleteForm(factory, form)
+      // Said plainly: somebody deleting a form expects all of it to go, and a
+      // table left behind is worth knowing about rather than discovering.
+      if (out && out.records > 0) {
+        raiseSnackbar('"' + (form.name || form.key) + '" is gone. Its table "' + out.table + '" was kept — it still holds ' +
+          out.records + ' record' + (out.records === 1 ? '' : 's') + '.', { design: 'info' })
+      } else if (out && out.tableDropped) {
+        raiseSnackbar('"' + (form.name || form.key) + '" and its empty table are gone.', { design: 'success' })
+      } else {
+        raiseSnackbar('"' + (form.name || form.key) + '" is gone.', { design: 'success' })
+      }
+      load()
+    } catch (err) {
+      raiseSnackbar(err.message, { design: 'error' })
+    } finally {
+      setBusy(null)
+    }
+  }
+
   const publish = async (form) => {
     setBusy(form.key)
-    setNotice(null)
     try {
       for (const screen of [form.edit, form.list]) {
         if (!screen || (screen.version !== null && !screen.hasDraft)) continue
         const row = await factory.loadDraft(screen.screenKey)
         await factory.publish(row.document)
       }
-      setNotice('Published "' + form.name + '"')
-      setError(null)
+      raiseSnackbar('Published "' + form.name + '"', { design: 'success' })
       load()
     } catch (err) {
-      setError(err.confirm
+      raiseSnackbar(err.confirm
         ? 'Publishing "' + form.name + '" would remove columns and their data — open Design form and publish there to see what, and confirm.'
-        : err.message)
+        : err.message, { design: 'error' })
     } finally {
       setBusy(null)
     }
@@ -112,10 +194,10 @@ export default function Forms() {
       if (inMenu.has(form.key)) await removeMenuItem(FORM_MENU_PREFIX + form.key)
       else await addMenuItem({ name: FORM_MENU_PREFIX + form.key, label: form.name })
       await refreshAccess()
-      setNotice(inMenu.has(form.key) ? 'Removed "' + form.name + '" from the menu' : 'Added "' + form.name + '" to the menu — rename or move it in the Menu tab')
+      raiseSnackbar(inMenu.has(form.key) ? 'Removed "' + form.name + '" from the menu' : 'Added "' + form.name + '" to the menu — rename or move it in the Menu tab', { design: 'success' })
       load()
     } catch (err) {
-      setError(err.message)
+      raiseSnackbar(err.message, { design: 'error' })
     } finally {
       setBusy(null)
     }
@@ -141,8 +223,6 @@ export default function Forms() {
         </button>
       </form>
 
-      {error && <div className="app-error">{error}</div>}
-      {notice && <div className="app-notice">{notice}</div>}
 
       {forms && forms.length === 0 && <p className="app-sub">No forms yet.</p>}
       {forms && forms.length > 0 && (
@@ -157,7 +237,19 @@ export default function Forms() {
               const canOpen = form.list && form.list.version !== null
               return (
                 <tr key={form.key}>
-                  <td><strong>{form.name || form.key}</strong><div className="app-sub">{form.key}</div></td>
+                  <td>
+                    <strong>{form.name || form.key}</strong>
+                    <div className="app-sub">{form.key}</div>
+                    {/* WHAT IT IS FOR, and whose it is — the two things that
+                        tell three forms of the same name apart. The date
+                        stands alone when the names cannot be fetched. */}
+                    {form.description && <div className="app-sub">{form.description}</div>}
+                    {(form.createdBy || form.createdDate) && (
+                      <div className="app-sub">
+                        {[people[form.createdBy], madeOn(form.createdDate)].filter(Boolean).join(' · ')}
+                      </div>
+                    )}
+                  </td>
                   <td><code>{form.source || '—'}</code></td>
                   <td className={edit.unpublished ? 'app-forms-pending' : undefined}>{edit.label}</td>
                   <td className={list.unpublished ? 'app-forms-pending' : undefined}>{list.label}</td>
@@ -173,6 +265,17 @@ export default function Forms() {
                         {busy === form.key ? 'Publishing…' : 'Publish'}
                       </button>
                     )}
+                    {/* The design always goes; the TABLE only when it is empty
+                        and nothing else describes it. Records are never lost
+                        to a click — @xeplr/factory refuses to drop a table
+                        with rows in it and says how many kept it. */}
+                    <button
+                      className="app-btn app-btn-quiet app-btn-danger"
+                      disabled={busy === form.key}
+                      onClick={() => remove(form)}
+                    >
+                      Delete
+                    </button>
                   </td>
                 </tr>
               )

package/templates/ui/src/pages/Masters.jsx

@@ -0,0 +1,114 @@
+// CONFIGURE UI → MASTERS — the lists the rest of the app points at.
+//
+// Departments, statuses, countries, categories: small tables that other forms
+// choose from. They are ordinary forms with a flag (Design → This is a
+// master), so they have a table, a list, an edit screen and permissions like
+// anything else — a master is a fact about a form, not a kind of form.
+//
+// They are gathered HERE rather than scattered through the side rail because
+// that is what they are: reference data somebody maintains occasionally, not
+// pages people work in daily. The rail stays for the work.
+//
+// Which forms are masters is @xeplr/ui-factory's answer (`useScreenSource`),
+// not this app's — grouping two screens into a form and reading the flag is
+// the same code in every app, and a copy here could never be fixed centrally.
+import { useState } from 'react'
+import { Link } from 'react-router-dom'
+import { useScreenSource, createMaster, possibleParents, FactoryBuilder } from '@xeplr/ui-factory'
+import { factory } from '../api/factory.js'
+
+export default function Masters() {
+  const { masters, loading, reload } = useScreenSource(factory, { Builder: FactoryBuilder })
+  const [name, setName] = useState('')
+  const [parent, setParent] = useState('')
+  const [busy, setBusy] = useState(false)
+  const [error, setError] = useState(null)
+
+  // MADE, NOT DESIGNED. A master is a name, an order and what it belongs to —
+  // the same three things every time — so it is created outright and the
+  // builder is for the day one needs a fourth field.
+  const create = async (e) => {
+    e.preventDefault()
+    if (!name.trim() || busy) return
+    setBusy(true)
+    try {
+      const owner = masters.find((m) => m.key === parent)
+      await createMaster(factory, {
+        name: name.trim(),
+        parent: owner ? { table: owner.source, label: owner.name } : null
+      })
+      setName('')
+      setParent('')
+      setError(null)
+      reload()
+    } catch (err) {
+      setError(err.message)
+    } finally {
+      setBusy(false)
+    }
+  }
+
+  if (loading) return <p className="app-sub">Loading…</p>
+
+  return (
+    <div className="app-forms">
+      <p className="app-page-lead">
+        The lists the rest of the app chooses from. A master is a name, an order of your own,
+        and — when it belongs to one — the master above it.
+      </p>
+
+      {error && <div className="app-error">{error}</div>}
+
+      <form className="app-forms-new" onSubmit={create}>
+        <label className="app-forms-field">
+          <span>New master</span>
+          <input value={name} onChange={(e) => setName(e.target.value)} placeholder="Departments" />
+        </label>
+        {/* Only worth asking once there is something to belong to. */}
+        {masters.length > 0 && (
+          <label className="app-forms-field">
+            <span>Belongs to</span>
+            <select value={parent} onChange={(e) => setParent(e.target.value)}>
+              <option value="">— nothing —</option>
+              {possibleParents(masters).map((m) => (
+                <option key={m.key} value={m.key}>{m.name}</option>
+              ))}
+            </select>
+          </label>
+        )}
+        <button type="submit" className="app-btn" disabled={!name.trim() || busy}>
+          {busy ? 'Making it…' : 'Make the master'}
+        </button>
+      </form>
+
+      {masters.length === 0 && (
+        <p className="app-sub">
+          No masters yet. Departments, statuses, countries — anything other forms point at.
+        </p>
+      )}
+
+      {masters.length > 0 && (
+        <table className="app-table">
+          <thead><tr><th>Master</th><th>Shown as</th><th>Table</th><th /></tr></thead>
+          <tbody>
+            {masters.map((m) => (
+              <tr key={m.key}>
+                <td><strong>{m.name}</strong></td>
+                {/* What a picker shows for one of its records — said once on
+                    the master, not again on every dropdown pointing at it. */}
+                <td className="app-sub">{m.labelField || '—'}</td>
+                <td className="app-sub">{m.source || '—'}</td>
+                <td className="app-row-actions">
+                  {/* Its records: the list screen is what looking at a master
+                      means. Its design is where the flag was set. */}
+                  <Link to={`/forms/${m.key}`}>Open</Link>
+                  <Link to={`/configure/forms/${m.key}/design/form`}>Design</Link>
+                </td>
+              </tr>
+            ))}
+          </tbody>
+        </table>
+      )}
+    </div>
+  )
+}