@xeplr/cli 0.1.7 → 0.1.9

package/bin/xeplr.js

@@ -54,7 +54,14 @@ async function main() {
 
   var session = prompt.createSession();
   try {
-    var answers = await questions.collect(session, argv[1] && argv[1].indexOf('--') !== 0 ? argv[1] : undefined);
+    // A folder that already has something in it is refused NOW, before a
+    // single question is asked — not after the database password.
+    var argName = argv[1] && argv[1].indexOf('--') !== 0 ? argv[1] : undefined;
+    if (argName && generate.isOccupied(path.resolve(process.cwd(), argName))) {
+      console.error('\n  ' + path.resolve(process.cwd(), argName) + ' already exists and is not empty.\n');
+      return 1;
+    }
+    var answers = await questions.collect(session, argName);
     console.log(plan.describe(answers));
 
     var go = await session.confirm('  Create it?', true);

package/lib/generate/index.js

@@ -226,7 +226,7 @@ function walk(dir) {
  * @returns {{ written: string[] }}
  */
 function generate(answers, target) {
-  if (fs.existsSync(target) && fs.readdirSync(target).length > 0) {
+  if (isOccupied(target)) {
     throw new Error(target + ' already exists and is not empty.');
   }
 
@@ -270,4 +270,9 @@ function generate(answers, target) {
   return { written: written.sort() };
 }
 
-module.exports = { generate: generate, substitutions: substitutions, fill: fill };
+/** A folder that exists and has something in it — generating there could overwrite work. */
+function isOccupied(target) {
+  return fs.existsSync(target) && fs.readdirSync(target).length > 0;
+}
+
+module.exports = { isOccupied: isOccupied, generate: generate, substitutions: substitutions, fill: fill };

package/package.json

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

package/templates/CLAUDE.md

@@ -7,7 +7,7 @@ Read `api/node_modules/@xeplr/ui-factory/AUTHORING.md` for what screens, hooks a
 
 ## Create a new UI
 
-A new UI is a **form**: a list, and an add / edit form it opens in a popup, saved in its own table. Use the singular for `<form>` (`farming_department`), the plural for the page (`FarmingDepartments`).
+A new UI is a **form**: a list, and an add / edit form it opens — on a page of its own (like Tasks) or in a popup — saved in its own table. Use the singular for `<form>` (`farming_department`), the plural for the page (`FarmingDepartments`).
 
 Create every file below — the hooks and the model run the defaults (`super`) until the request needs more.
 
@@ -32,18 +32,28 @@ Then change only what the request asks for:
 | the request says… | change |
 |---|---|
 | a field, label, rule, dropdown, layout, colour | the screen JSON → validate → publish in Configure UI → Forms (or, never published yet, restart the API) |
-| hide / filter rows on screen, an extra button on each row, fill in a value before saving | front-end hooks — `ui/src/pages/Edit<Form>.jsx` |
+| hide / filter rows on screen, an extra button on each row, fill in a value before saving, check something before Next moves on | front-end hooks — `ui/src/pages/Edit<Form>.jsx` (`get`, `save`, `delete`, `actions`, `step`) |
 | must / only if / check against / email when / only managers see | server hooks — `api/screens/<form>/<form>.hooks.js` |
 | store as / convert / comma-separated ↔ array / work out X from Y | server model — `api/screens/<form>/<form>.model.js` |
 | a query in your own server code | `factory.table('<forms table>')` — this company, active rows, the model applied |
 
 **Without code:** Super Admin can also make a form in **Configure UI → Forms** (settings menu, top right): New form (label + key) → design → Publish → Add to menu. It gets no page, hooks or model files; add them with the steps above when it needs them.
 
+### The controls a field can be
+
+`text` (default), `textarea`, `number`, `date`, `datetime`, `checkbox`, `dropdown`, `radio`, `multiselect`, `file`, plus `stepper` and `label`. The sample uses every one — read `api/screens/task/task.entity.json` for how each is written. Three are worth knowing about:
+
+- **`multiselect`** — several ids in ONE text column, comma separated, and an array in your code. An option's id may not contain a comma.
+- **`file`** — the column holds the **path**, never the file. Say which extensions (`"accept": ".pdf,.docx"`) and how large (`"maxSize": 10`, in MB); the API enforces both, by extension, and keeps the file under `FACTORY_FILES_DIR`. Uploading needs `multer` in `api/` (already in package.json).
+- **`stepper`** — a journey across the top. Every other field says which step it is on (`"step": "Planning"`), and one without a `step` shows on every step. `step(ctx)` in the front-end hooks runs before each move.
+
+**A list opens its form on a page or in a popup** — `"openIn": "page"` in the entity spec, or Configure UI → Forms → the list. A page needs `onOpenRecord` on the list's page (where to navigate) and `onDone` on the form's page (where Done goes back to): `Tasks.jsx` and `EditTask.jsx` show both, with routes `/tasks/new` and `/tasks/:id` in `App.jsx`.
+
 **Keys and labels.** A form's key names its screens and table and never changes once published; its label is the screens' name. A menu item's key (`menus.name`) is what `drawerItems` matches; its label is what the rail shows, renamed in Configure UI → Menu. Code only ever uses keys.
 
 ### The prompt
 
-> Create a new UI for **farming departments**. One record is a farming department with: **Name** (required), **Region** (dropdown: North, South, East, West), **Area in acres** (number, at least 0), **Started on** (date), **Notes** (long text). Show Name, Region and Area in the list. Follow "Create a new UI" in CLAUDE.md.
+> Create a new UI for **farming departments**. One record is a farming department with: **Name** (required), **Region** (dropdown: North, South, East, West), **Area in acres** (number, at least 0), **Started on** (date), **Certifications** (choose several: Organic, Fair trade, Rainforest), **Inspection at** (date and time), **Licence** (file: .pdf or .jpg), **Notes** (long text). Show Name, Region and Area in the list. Follow "Create a new UI" in CLAUDE.md.
 
 Replace the bold parts. Add behaviour in the same message if you want it — "a Mark active button on each row", "Region is required when Area is over 100", "store tags as an array".
 

package/templates/README.md

@@ -24,7 +24,7 @@ Open http://localhost:__UI_PORT__ and sign in as `__ADMIN_EMAIL__`.
 ## What is in it
 
 - **Sign-in** — login, register, password reset, profile, and the admin screens for users, roles and permissions (`@xeplr/auth`, `@xeplr/ui-account`).
-- **Tasks** — a sample built from screens: a list, and a form it opens in a popup, saved into an ordinary `tasks` table.
+- **Tasks** — a sample built from screens: a list, and a form it opens on a page of its own, saved into an ordinary `tasks` table. The form is filled in over three steps and uses every control there is — text, a dropdown, radio buttons, a tick box, a date, a date and time, several tags at once, and a file.
 - **Configure UI** — in the settings menu, for Super Admin: every form (make one, design it, publish it, add it to the side rail) and the side rail itself (rename, reorder, hide).
 
 ## Create a new UI

package/templates/api/README.md

@@ -25,6 +25,7 @@ The API (`@xeplr/base-apis`) and the sign-in service (`@xeplr/auth`), with this
 | `routes/index.js` | this app's own routes — every data address under `/api` |
 | `routes/access.js` | who may design and publish forms (Super Admin) |
 | `screens/` | the forms this app ships with: per form, its spec, list and edit screens, server hooks and model — registered in `screens/index.js` |
+| `uploads/` | what people attach through a form's **file** field (`FACTORY_FILES_DIR`). Never committed, and never served: a file comes back only through the API's own route, which checks the caller the way reading a record does |
 | `migrations/` | hand-written SQL for tables no form owns |
 | `migrations-auth/` | this app's rows in the sign-in database — menus (by key), permissions |
 | `models/` | models for hand-written tables |

package/templates/api/bin/www

@@ -61,7 +61,15 @@ async function start() {
   // The screens, their hooks and their models. A hooks file with a typo
   // ("beforeSave") or a malformed model stops startup here, rather than
   // silently never running.
-  await factory.init({ knex: knex, hooks: screens.hooks, models: screens.models });
+  // filesDir: where a form's file field puts what people upload. Nothing is
+  // served from it — a file comes back only through the factory's own route,
+  // which checks the caller the way reading a record does.
+  await factory.init({
+    knex: knex,
+    hooks: screens.hooks,
+    models: screens.models,
+    filesDir: process.env.FACTORY_FILES_DIR
+  });
 
   // Screens never published yet are published now, creating their tables.
   // Ones already published are left alone — Configure UI → Forms owns them.

package/templates/api/development.env.tpl

@@ -56,3 +56,22 @@ AUTH_SUPER_ADMIN_PASSWORD=__ADMIN_PASSWORD__
 # email template can carry a token as a value but cannot build an address.
 AUTH_ACTIVATION_URL=http://localhost:__UI_PORT__/auth/activate
 AUTH_INVITE_URL=http://localhost:__UI_PORT__/auth/accept-invite
+
+# ── Uploaded files ──
+# Where a form's FILE field puts what people upload. The path is what the
+# record stores; the file itself is served only through the API's own route,
+# which checks the caller the way reading a record does. Relative to api/.
+FACTORY_FILES_DIR=./uploads/factory
+
+# ── Email (optional) ──
+# Without it sign-in works, but activation, invite and password-reset links
+# cannot be sent. The sign-in service checks it at start and says so in its
+# banner: "email ✓ smtp — host:587, connected" or "✗ NOT WORKING — reason".
+# Providers: smtp | brevo | aws | azure — see @xeplr/utils' README.
+# EMAIL_PROVIDER=smtp
+# SMTP_HOST=
+# SMTP_PORT=587
+# SMTP_USER=
+# SMTP_PASS=
+# SMTP_FROM=
+# (smtp also needs `npm install nodemailer` in this folder)

package/templates/api/gitignore.tpl

@@ -1,2 +1,4 @@
 node_modules/
 logs/
+# Files people upload through a form's file field (FACTORY_FILES_DIR).
+uploads/

package/templates/api/package.json

@@ -20,14 +20,15 @@
     "@xeplr/auth": "^1.1.4",
     "@xeplr/base-apis": "^2.0.0",
     "@xeplr/db": "^1.0.6",
-    "@xeplr/factory": "^1.0.5",
-    "@xeplr/ui-factory": "^1.0.5",
+    "@xeplr/factory": "^1.0.6",
+    "@xeplr/ui-factory": "^1.0.11",
     "@xeplr/utils": "^1.0.11",
     "dotenv": "^17.4.2",
-    "express": "^5.2.0"
+    "express": "^5.2.0",
+    "multer": "^2.0.2"
   },
   "devDependencies": {
     "dotenv-cli": "^8.0.0",
-    "@xeplr/cli": "^0.1.0"
+    "@xeplr/cli": "^0.1.8"
   }
 }

package/templates/api/screens/task/task-edit.screen.json

@@ -20,14 +20,40 @@
         "variant": "heading"
       }
     },
+    {
+      "id": "stepper",
+      "type": "stepper",
+      "x": 0.04,
+      "y": 0.15,
+      "w": 0.92,
+      "h": 0.09,
+      "z": 2,
+      "props": {
+        "steps": [
+          {
+            "key": "the_task",
+            "label": "The task"
+          },
+          {
+            "key": "planning",
+            "label": "Planning"
+          },
+          {
+            "key": "attachment",
+            "label": "Attachment"
+          }
+        ],
+        "showNumbers": true
+      }
+    },
     {
       "id": "title",
       "type": "text",
       "x": 0.04,
-      "y": 0.15,
-      "w": 0.4475,
+      "y": 0.28,
+      "w": 0.92,
       "h": 0.08,
-      "z": 2,
+      "z": 3,
       "props": {
         "label": "Title",
         "required": true,
@@ -35,16 +61,20 @@
           "maxLength": 200
         },
         "name": "title"
+      },
+      "step": {
+        "of": "stepper",
+        "index": 0
       }
     },
     {
       "id": "status",
       "type": "dropdown",
-      "x": 0.5125,
-      "y": 0.15,
+      "x": 0.04,
+      "y": 0.4,
       "w": 0.4475,
       "h": 0.08,
-      "z": 3,
+      "z": 4,
       "props": {
         "label": "Status",
         "placeholder": "Select…",
@@ -67,35 +97,175 @@
         },
         "required": true,
         "name": "status"
+      },
+      "step": {
+        "of": "stepper",
+        "index": 0
       }
     },
     {
-      "id": "dueDate",
-      "type": "date",
-      "x": 0.04,
-      "y": 0.27,
+      "id": "priority",
+      "type": "radio",
+      "x": 0.5125,
+      "y": 0.4,
       "w": 0.4475,
-      "h": 0.08,
-      "z": 4,
+      "h": 0.065,
+      "z": 5,
       "props": {
-        "label": "Due date",
-        "name": "dueDate"
+        "label": "Priority",
+        "data": {
+          "source": "static",
+          "options": [
+            {
+              "id": "low",
+              "name": "Low"
+            },
+            {
+              "id": "normal",
+              "name": "Normal"
+            },
+            {
+              "id": "high",
+              "name": "High"
+            }
+          ]
+        },
+        "layout": "horizontal",
+        "name": "priority"
+      },
+      "step": {
+        "of": "stepper",
+        "index": 0
       }
     },
     {
       "id": "description",
       "type": "textarea",
       "x": 0.04,
-      "y": 0.39,
+      "y": 0.52,
       "w": 0.92,
       "h": 0.18,
-      "z": 5,
+      "z": 6,
       "props": {
         "label": "Description",
         "validation": {
           "maxLength": 1000
         },
         "name": "description"
+      },
+      "step": {
+        "of": "stepper",
+        "index": 0
+      }
+    },
+    {
+      "id": "dueDate",
+      "type": "date",
+      "x": 0.04,
+      "y": 0.28,
+      "w": 0.4475,
+      "h": 0.08,
+      "z": 7,
+      "props": {
+        "label": "Due date",
+        "name": "dueDate"
+      },
+      "step": {
+        "of": "stepper",
+        "index": 1
+      }
+    },
+    {
+      "id": "remindAt",
+      "type": "datetime",
+      "x": 0.5125,
+      "y": 0.28,
+      "w": 0.4475,
+      "h": 0.08,
+      "z": 8,
+      "props": {
+        "label": "Remind at",
+        "name": "remindAt"
+      },
+      "step": {
+        "of": "stepper",
+        "index": 1
+      }
+    },
+    {
+      "id": "tags",
+      "type": "multiselect",
+      "x": 0.04,
+      "y": 0.4,
+      "w": 0.92,
+      "h": 0.065,
+      "z": 9,
+      "props": {
+        "label": "Tags",
+        "data": {
+          "source": "static",
+          "options": [
+            {
+              "id": "bug",
+              "name": "Bug"
+            },
+            {
+              "id": "feature",
+              "name": "Feature"
+            },
+            {
+              "id": "chore",
+              "name": "Chore"
+            },
+            {
+              "id": "customer",
+              "name": "Customer"
+            }
+          ]
+        },
+        "layout": "horizontal",
+        "name": "tags"
+      },
+      "step": {
+        "of": "stepper",
+        "index": 1
+      }
+    },
+    {
+      "id": "blocked",
+      "type": "checkbox",
+      "x": 0.04,
+      "y": 0.505,
+      "w": 0.4475,
+      "h": 0.05,
+      "z": 10,
+      "props": {
+        "label": "Blocked",
+        "default": false,
+        "name": "blocked"
+      },
+      "step": {
+        "of": "stepper",
+        "index": 1
+      }
+    },
+    {
+      "id": "attachment",
+      "type": "file",
+      "x": 0.04,
+      "y": 0.28,
+      "w": 0.92,
+      "h": 0.1,
+      "z": 11,
+      "props": {
+        "label": "Attachment",
+        "accept": ".pdf,.png,.jpg,.jpeg,.docx,.xlsx",
+        "maxSize": 10,
+        "name": "attachment"
+      },
+      "step": {
+        "of": "stepper",
+        "index": 2
       }
     }
   ],

package/templates/api/screens/task/task-list.screen.json

@@ -23,6 +23,7 @@
           "edit",
           "delete"
         ],
+        "openIn": "page",
         "editScreen": "task_edit",
         "columns": [
           {
@@ -33,9 +34,17 @@
             "field": "status",
             "label": "Status"
           },
+          {
+            "field": "priority",
+            "label": "Priority"
+          },
           {
             "field": "dueDate",
             "label": "Due date"
+          },
+          {
+            "field": "tags",
+            "label": "Tags"
           }
         ]
       }

package/templates/api/screens/task/task.entity.json

@@ -1,10 +1,91 @@
 {
   "entity": "task",
+  "columns": 2,
+  "openIn": "page",
   "fields": [
-    { "label": "Title", "required": true, "validation": { "maxLength": 200 } },
-    { "label": "Status", "type": "dropdown", "options": ["To do", "In progress", "Done"], "required": true },
-    { "label": "Due date", "type": "date" },
-    { "label": "Description", "type": "textarea", "validation": { "maxLength": 1000 } }
+    {
+      "type": "stepper",
+      "steps": [
+        "The task",
+        "Planning",
+        "Attachment"
+      ]
+    },
+    {
+      "label": "Title",
+      "step": "The task",
+      "required": true,
+      "validation": {
+        "maxLength": 200
+      },
+      "width": "full"
+    },
+    {
+      "label": "Status",
+      "type": "dropdown",
+      "options": [
+        "To do",
+        "In progress",
+        "Done"
+      ],
+      "required": true
+    },
+    {
+      "label": "Priority",
+      "type": "radio",
+      "options": [
+        "Low",
+        "Normal",
+        "High"
+      ],
+      "layout": "horizontal"
+    },
+    {
+      "label": "Description",
+      "type": "textarea",
+      "validation": {
+        "maxLength": 1000
+      }
+    },
+    {
+      "label": "Due date",
+      "type": "date",
+      "step": "Planning"
+    },
+    {
+      "label": "Remind at",
+      "type": "datetime"
+    },
+    {
+      "label": "Tags",
+      "type": "multiselect",
+      "options": [
+        "Bug",
+        "Feature",
+        "Chore",
+        "Customer"
+      ],
+      "layout": "horizontal",
+      "width": "full"
+    },
+    {
+      "label": "Blocked",
+      "type": "checkbox"
+    },
+    {
+      "label": "Attachment",
+      "type": "file",
+      "step": "Attachment",
+      "accept": ".pdf,.png,.jpg,.jpeg,.docx,.xlsx",
+      "maxSize": 10,
+      "width": "full"
+    }
   ],
-  "listColumns": ["title", "status", "dueDate"]
+  "listColumns": [
+    "title",
+    "status",
+    "priority",
+    "dueDate",
+    "tags"
+  ]
 }

package/templates/ui/README.md

@@ -17,7 +17,7 @@ npm run build     # → dist/
 | `src/App.jsx` | routes, the side rail (`drawerItems`) and the settings menu (`settingsOverrides`) — **by key**, never by label |
 | `src/menu.js` | every menu key this app uses; forms added to the menu are `form:<key>` |
 | `src/api/factory.js` | the calls to the API's forms routes |
-| `src/pages/Tasks.jsx` | the sample list; `EditTask.jsx` holds the task form's **front-end hooks** (`TaskHooks extends FactoryHooks` — every method calls `super`) |
+| `src/pages/Tasks.jsx` | the sample list. It opens records on a **page** (`onOpenRecord` → `/tasks/new`, `/tasks/:id`), and `EditTask.jsx` is that page — it also holds the task form's **front-end hooks** (`TaskHooks extends FactoryHooks` — every method calls `super`, including `step`, run before a stepper moves) and sends **Done** back to the list |
 | `src/pages/ConfigureUI.jsx` | Configure UI (Super Admin): `Forms.jsx` and `MenuSettings.jsx` tabs; `FormDesigner.jsx` designs one form |
 | `src/pages/FormRecords.jsx` | opens any published form — what a form added to the menu links to |
 

package/templates/ui/package.json

@@ -10,9 +10,9 @@
   },
   "dependencies": {
     "@tanstack/react-table": "^8.21.3",
-    "@xeplr/ui-account": "^1.0.7",
+    "@xeplr/ui-account": "^1.0.9",
     "@xeplr/ui-canvas": "^1.0.2",
-    "@xeplr/ui-factory": "^1.0.5",
+    "@xeplr/ui-factory": "^1.0.11",
     "@xeplr/ui-table": "^1.0.6",
     "react": "^19.2.4",
     "react-dom": "^19.2.4",

package/templates/ui/src/App.jsx

@@ -3,6 +3,7 @@ import { Routes, Route, Outlet, Navigate, useNavigate } from 'react-router-dom'
 import { authRoutes, authPath, NavPage, ProtectedRoute, useAccess } from '@xeplr/ui-account'
 import Home from './pages/Home.jsx'
 import Tasks from './pages/Tasks.jsx'
+import EditTask from './pages/EditTask.jsx'
 import ConfigureUI from './pages/ConfigureUI.jsx'
 import { FORM_MENU_PREFIX } from './menu.js'
 import FormDesigner from './pages/FormDesigner.jsx'
@@ -105,6 +106,9 @@ __MT_SELECT_ROUTE__
         <Route path="/" element={<Navigate to="/home" replace />} />
         <Route path="/home" element={<Home />} />
         <Route path="/tasks" element={<Tasks />} />
+        {/* The task list opens its form on a page — see Tasks.jsx's onOpenRecord. */}
+        <Route path="/tasks/new" element={<EditTask />} />
+        <Route path="/tasks/:id" element={<EditTask />} />
         <Route path="/forms/:form" element={<FormRecords />} />
         <Route path="/configure" element={<ConfigureUI />} />
         <Route path="/configure/forms/:form/design/:part" element={<FormDesigner />} />

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

@@ -4,6 +4,7 @@
 // module holds its HOOKS, used by this page, by the Tasks list and by the
 // popup the list opens.
 import { useEffect, useState } from 'react'
+import { useNavigate, useParams } from 'react-router-dom'
 import { FactoryScreen, FactoryHooks } from '@xeplr/ui-factory'
 import { factory } from '../api/factory.js'
 
@@ -35,6 +36,15 @@ export class TaskHooks extends FactoryHooks {
     return super.delete(record, ctx)
   }
 
+  /**
+   * Before a stepper moves — Next, Back, or a click on the bar.
+   * Return false to stay where you are, or a step number to go there instead.
+   * The step's own required fields are checked before this runs.
+   */
+  step(ctx) {
+    return super.step(ctx)
+  }
+
   /** Extra row buttons beside Edit / Delete: [{ label, onClick: (record, ctx) => … }]. ctx.refresh() reloads. */
   actions(ctx) {
     return super.actions(ctx)
@@ -43,15 +53,41 @@ export class TaskHooks extends FactoryHooks {
 
 export const taskHooks = new TaskHooks()
 
-/** The task form on a page of its own: <EditTask /> for a new task, <EditTask record={task} /> for one. */
+/**
+ * The task form on a page of its own — /tasks/new, or /tasks/:id for a task
+ * that exists. The list sends people here (its "Opens in" is a page), and
+ * Done brings them back.
+ *
+ * There is no Save button: the form saves itself a moment after each change.
+ * Done only waits for anything still in flight, then leaves.
+ */
 export default function EditTask({ record }) {
+  const { id } = useParams()
+  const navigate = useNavigate()
   const [screen, setScreen] = useState(null)
+  const [task, setTask] = useState(record || null)
   const [error, setError] = useState(null)
 
   useEffect(() => {
     factory.loadScreen('task_edit').then(setScreen, (e) => setError(e.message))
   }, [])
 
+  // The record as it is NOW, through the server's get hooks — not a copy the
+  // list happened to have.
+  useEffect(() => {
+    if (record || !id || id === 'new') return
+    factory.fetchRecord({ screen: 'task_edit', id }).then(setTask, (e) => setError(e.message))
+  }, [id, record])
+
   if (error) return <div className="app-error">Could not load the task form — {error}</div>
-  return screen ? <FactoryScreen document={screen} record={record} {...factory.screenProps} hooks={taskHooks} /> : null
+  if (!screen || (id && id !== 'new' && !task)) return null
+  return (
+    <FactoryScreen
+      document={screen}
+      record={task}
+      {...factory.screenProps}
+      hooks={taskHooks}
+      onDone={() => navigate('/tasks')}
+    />
+  )
 }

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

@@ -1,11 +1,14 @@
-// THE SAMPLE — a list of tasks. New and Edit open the task form in a popup,
-// where it saves itself as you type; there is no Save button.
+// THE SAMPLE — a list of tasks. New and Edit open the task form on a PAGE of
+// its own, where it saves itself as you type; there is no Save button, and
+// Done goes back here. (A list can open its form in a popup instead: Configure
+// UI → Forms → the list → Opens in.)
 //
 // Nothing about tasks is written in this file. The list and the form are
 // SCREENS, designed in Configure UI → Forms and stored by the API; this page only
 // loads the published "task_list" and hands it the calls it needs — and the
 // task hooks (EditTask.jsx), which the popup uses too.
 import { useEffect, useState } from 'react'
+import { useNavigate } from 'react-router-dom'
 import { FactoryScreen } from '@xeplr/ui-factory'
 import { factory } from '../api/factory.js'
 import TasksHelp from './TasksHelp.jsx'
@@ -14,6 +17,7 @@ import { taskHooks } from './EditTask.jsx'
 export default function Tasks() {
   const [screen, setScreen] = useState(null)
   const [error, setError] = useState(null)
+  const navigate = useNavigate()
 
   useEffect(() => {
     factory.loadScreen('task_list').then(setScreen, (e) => setError(e.message))
@@ -24,7 +28,15 @@ export default function Tasks() {
       <div className="app-page-main">
         {error && <div className="app-error">Could not load the task list — {error}</div>}
         {/* loadScreen lets the list's Edit / New fetch "task_edit" when first opened. */}
-        {screen && <FactoryScreen document={screen} {...factory.screenProps} hooks={taskHooks} />}
+        {screen && (
+          <FactoryScreen
+            document={screen}
+            {...factory.screenProps}
+            hooks={taskHooks}
+            // The list opens records on a page, so it asks this app where to go.
+            onOpenRecord={({ id }) => navigate(id ? `/tasks/${id}` : '/tasks/new')}
+          />
+        )}
       </div>
       <TasksHelp />
     </div>

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

@@ -5,7 +5,7 @@ import { useState } from 'react'
 // and find.
 
 // The same prompt as in CLAUDE.md. Replace the form and its fields.
-const PROMPT = 'Create a new UI for farming departments. One record is a farming department with: Name (required), Region (dropdown: North, South, East, West), Area in acres (number, at least 0), Started on (date), Notes (long text). Show Name, Region and Area in the list. Follow "Create a new UI" in CLAUDE.md.'
+const PROMPT = 'Create a new UI for farming departments. One record is a farming department with: Name (required), Region (dropdown: North, South, East, West), Area in acres (number, at least 0), Started on (date), Certifications (choose several: Organic, Fair trade, Rainforest), Inspection at (date and time), Licence (file: .pdf or .jpg), Notes (long text). Show Name, Region and Area in the list. Follow "Create a new UI" in CLAUDE.md.'
 
 export default function TasksHelp() {
   const [copied, setCopied] = useState(false)
@@ -37,10 +37,18 @@ export default function TasksHelp() {
 
       <h3>This page is an example</h3>
       <p>
-        A task has a title, a status, a due date and a description. Neither the
-        list nor the form is written by hand — both are <strong>screens</strong>,
-        and the tasks are saved in an ordinary <code>tasks</code> table with one
-        column per field.
+        A task is filled in over three steps — the task, planning, an
+        attachment — and shows every kind of control there is: text, a
+        dropdown, radio buttons, a tick box, dates, a date and time, several
+        tags at once, and a file. Neither the list nor the form is written by
+        hand: both are <strong>screens</strong>, and a task is saved in an
+        ordinary <code>tasks</code> table with one column per field. The file
+        itself is kept outside the database, and its column holds the path.
+      </p>
+      <p>
+        <strong>New</strong> and <strong>Edit</strong> open the form on a page
+        of its own, and <strong>Done</strong> comes back here. A list can open
+        it in a popup instead — that is its <strong>Opens in</strong> setting.
       </p>
 
       <h3>Change it</h3>
@@ -51,7 +59,7 @@ export default function TasksHelp() {
         new column as you publish.
       </p>
 
-      <h3>Or by hand</h3>
+      <h3>Or without code</h3>
       <p>
         <strong>Configure UI → Forms → New form</strong>: label and key, design,
         publish, add to menu — no code. The full steps for a form with its own page, hooks and