@xeplr/cli 0.1.2 → 0.1.4

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

@@ -0,0 +1,57 @@
+// THE TASK FORM — and what the task screens do in the browser.
+//
+// The form itself is the "task_edit" screen, designed on the Forms page. This
+// 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 { FactoryScreen, FactoryHooks } from '@xeplr/ui-factory'
+import { factory } from '../api/factory.js'
+
+// ── WHAT THE TASK SCREENS DO IN THE BROWSER ──────────────────────────────
+// Every method runs the default (super). Change the ones you need; leave the
+// rest as they are.
+//
+//   before    change the input, then call super
+//   after     call super, then use or change what it returns
+//   override  do not call super
+//
+// ctx.screen says which screen is calling ("task_list" or "task_edit").
+// Keep them as methods (save(values, ctx) { … }) — super does not work in
+// arrow functions. Rules that must hold belong in the server's hooks
+// (api/screens/task/task.hooks.js).
+export class TaskHooks extends FactoryHooks {
+  /** A list's rows (ctx.many), or the record Edit opens (ctx.id). */
+  get(ctx) {
+    return super.get(ctx)
+  }
+
+  /** Every autosave — keep it quick. Returns the saved record. */
+  save(values, ctx) {
+    return super.save(values, ctx)
+  }
+
+  /** A list row, after the person confirmed. */
+  delete(record, ctx) {
+    return super.delete(record, ctx)
+  }
+
+  /** Extra row buttons beside Edit / Delete: [{ label, onClick: (record, ctx) => … }]. ctx.refresh() reloads. */
+  actions(ctx) {
+    return super.actions(ctx)
+  }
+}
+
+export const taskHooks = new TaskHooks()
+
+/** The task form on a page of its own: <EditTask /> for a new task, <EditTask record={task} /> for one. */
+export default function EditTask({ record }) {
+  const [screen, setScreen] = useState(null)
+  const [error, setError] = useState(null)
+
+  useEffect(() => {
+    factory.loadScreen('task_edit').then(setScreen, (e) => setError(e.message))
+  }, [])
+
+  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
+}

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

@@ -0,0 +1,74 @@
+// DESIGN ONE FORM — its add / edit form, or its list. Move and resize fields,
+// add new ones, change labels, rules, fonts and colours.
+//
+// Edits are kept as a DRAFT automatically; nobody sees them until Publish,
+// which also changes the table to match: a new field adds a column; removing
+// one asks first, because its column and every value in it would be deleted.
+import { useCallback, useEffect, useState } from 'react'
+import { useNavigate, useParams } from 'react-router-dom'
+import { FactoryBuilder } from '@xeplr/ui-factory'
+import { factory } from '../api/factory.js'
+
+const PARTS = [
+  { part: 'form', suffix: '_edit', label: 'Form' },
+  { part: 'list', suffix: '_list', label: 'List' }
+]
+
+export default function FormDesigner() {
+  const { form, part } = useParams()
+  const navigate = useNavigate()
+  const screenKey = form + (part === 'list' ? '_list' : '_edit')
+  const [current, setCurrent] = useState(null)      // { key, document, lockedNames }
+  const [error, setError] = useState(null)
+
+  useEffect(() => {
+    let cancelled = false
+    setCurrent(null)
+    // The draft if there is one, else the published version — with the field
+    // names that are already columns, which cannot be renamed.
+    factory.loadDraft(screenKey).then(
+      (row) => { if (!cancelled) { setCurrent({ key: screenKey, document: row.document, lockedNames: row.lockedNames || [] }); setError(null) } },
+      (e) => { if (!cancelled) setError(e.message) }
+    )
+    return () => { cancelled = true }
+  }, [screenKey])
+
+  const publish = useCallback(async (doc, options) => {
+    const result = await factory.publish(doc, options)
+    const row = await factory.loadDraft(doc.id)
+    setCurrent((c) => (c && c.key === doc.id ? { ...c, lockedNames: row.lockedNames || [] } : c))
+    return result
+  }, [])
+
+  return (
+    <div className="app-designer">
+      <div className="app-designer-bar">
+        <button type="button" className="app-btn app-btn-quiet" onClick={() => navigate('/forms')}>← Forms</button>
+        <span className="app-designer-title">{current ? current.document.name : form}</span>
+        {PARTS.map((p) => (
+          <button
+            key={p.part}
+            type="button"
+            className={'app-btn app-btn-quiet' + ((part === 'list') === (p.part === 'list') ? ' is-active' : '')}
+            onClick={() => navigate('/forms/' + form + '/design/' + p.part)}
+          >
+            {p.label}
+          </button>
+        ))}
+      </div>
+      {error && <div className="app-error">{error}</div>}
+      {current && (
+        <div className="app-designer-canvas">
+          <FactoryBuilder
+            key={current.key}
+            {...factory.builderProps}
+            document={current.document}
+            lockedNames={current.lockedNames}
+            onPublish={publish}
+            screens={PARTS.map((p) => ({ id: form + p.suffix, name: p.label }))}
+          />
+        </div>
+      )}
+    </div>
+  )
+}

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

@@ -0,0 +1,24 @@
+// USE ANY FORM — its published list, with New / Edit opening the form in a
+// popup. Tasks.jsx is the same thing for one form, with a help panel beside it.
+import { useEffect, useState } from 'react'
+import { useParams } from 'react-router-dom'
+import { FactoryScreen } from '@xeplr/ui-factory'
+import { factory } from '../api/factory.js'
+
+export default function FormRecords() {
+  const { form } = useParams()
+  const [screen, setScreen] = useState(null)
+  const [error, setError] = useState(null)
+
+  useEffect(() => {
+    setScreen(null)
+    factory.loadScreen(form + '_list').then((doc) => { setScreen(doc); setError(null) }, (e) => setError(e.message))
+  }, [form])
+
+  return (
+    <div className="app-page">
+      {error && <div className="app-error">Could not open this form — {error}</div>}
+      {screen && <FactoryScreen key={form} document={screen} {...factory.screenProps} />}
+    </div>
+  )
+}

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

@@ -0,0 +1,144 @@
+// FORMS — every form in the app, for Super Admin: see them, make a new one,
+// design it, publish it, open it.
+//
+// A form is two screens: a LIST of its records, and the add / edit FORM the
+// list opens in a popup. Records live in an ordinary table named for the form
+// ("farming_departments"), created when the form is first published.
+//
+// Claude can make forms too (api/screens/, `npx xeplr-factory screens`); this
+// page is the same thing by hand.
+import { useCallback, useEffect, useState } from 'react'
+import { useNavigate } from 'react-router-dom'
+import { factory } from '../api/factory.js'
+
+/** listScreens rows → one entry per form: { key, name, source, list, edit }. */
+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 }
+    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
+    byKey.set(key, entry)
+  })
+  return [...byKey.values()].sort((a, b) => String(a.name).localeCompare(String(b.name)))
+}
+
+function state(screen) {
+  if (!screen) return { label: '—', unpublished: false }
+  if (screen.version === null) return { label: 'Not published yet', unpublished: true }
+  return { label: 'v' + screen.version + (screen.hasDraft ? ' · unpublished changes' : ''), unpublished: screen.hasDraft }
+}
+
+export default function Forms() {
+  const navigate = useNavigate()
+  const [forms, setForms] = useState(null)
+  const [error, setError] = useState(null)
+  const [notice, setNotice] = useState(null)
+  const [name, setName] = useState('')
+  const [busy, setBusy] = useState(null)
+
+  const load = useCallback(() => {
+    factory.listScreens().then((rows) => { setForms(groupForms(rows)); setError(null) }, (e) => setError(e.message))
+  }, [])
+  useEffect(load, [load])
+
+  const create = async (e) => {
+    e.preventDefault()
+    setBusy('new')
+    try {
+      const made = await factory.createEntity({ entity: name })
+      // Straight into its form, to add the fields.
+      navigate('/forms/' + made.edit.replace(/_edit$/, '') + '/design/form')
+    } catch (err) {
+      setError(err.message)
+      setBusy(null)
+    }
+  }
+
+  // The form first — publishing it creates or changes the table — then the list.
+  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)
+      load()
+    } catch (err) {
+      // Removing a field drops its column — that is confirmed in the designer,
+      // where the columns and their values are shown.
+      setError(err.confirm
+        ? 'Publishing "' + form.name + '" would remove columns and their data — open Design form and publish there to see what, and confirm.'
+        : err.message)
+    } finally {
+      setBusy(null)
+    }
+  }
+
+  return (
+    <div className="app-page app-forms">
+      <h1>Forms</h1>
+      <p className="app-page-lead">
+        Every form in the app. A new one starts with a Name field — add the rest in its design, then publish to create its table.
+      </p>
+
+      <form className="app-forms-new" onSubmit={create}>
+        <input
+          value={name}
+          onChange={(e) => setName(e.target.value)}
+          placeholder='New form — one record is a… e.g. "farming department"'
+          aria-label="New form name"
+        />
+        <button type="submit" className="app-btn" disabled={!name.trim() || busy === 'new'}>
+          {busy === 'new' ? 'Creating…' : 'New form'}
+        </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 && (
+        <table className="app-table">
+          <thead>
+            <tr><th>Name</th><th>Table</th><th>Form</th><th>List</th><th /></tr>
+          </thead>
+          <tbody>
+            {forms.map((form) => {
+              const edit = state(form.edit)
+              const list = state(form.list)
+              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><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>
+                  <td className="app-row-actions">
+                    <button className="app-btn app-btn-quiet" disabled={!canOpen} title={canOpen ? '' : 'Publish it first'} onClick={() => navigate('/forms/' + form.key)}>Open</button>
+                    {form.edit && <button className="app-btn app-btn-quiet" onClick={() => navigate('/forms/' + form.key + '/design/form')}>Design form</button>}
+                    {form.list && <button className="app-btn app-btn-quiet" onClick={() => navigate('/forms/' + form.key + '/design/list')}>Design list</button>}
+                    {(edit.unpublished || list.unpublished) && (
+                      <button className="app-btn" disabled={busy === form.key} onClick={() => publish(form)}>
+                        {busy === form.key ? 'Publishing…' : 'Publish'}
+                      </button>
+                    )}
+                  </td>
+                </tr>
+              )
+            })}
+          </tbody>
+        </table>
+      )}
+    </div>
+  )
+}

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

@@ -58,6 +58,10 @@ export default function Home() {
           <code>public/logo.svg</code> and <code>public/logo-wide.svg</code> — the
           sample logo, in the top bar and the side rail.
         </li>
+        <li>
+          <strong>Forms</strong>, in the side rail — make a new form, or change the
+          sample task screens. Publish creates or changes the table too.
+        </li>
         <li>
           <code>src/App.jsx</code> — add your own pages, and the side-rail items
           that open them.

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

@@ -1,105 +1,31 @@
-// DESIGN LAYER — presentation only. Every value and every handler comes from
-// the controller; there is no logic here to get out of step with it.
-import { useTasksController } from '../useTasksController.js'
+// 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.
+//
+// Nothing about tasks is written in this file. The list and the form are
+// SCREENS, designed on the Forms page 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 { FactoryScreen } from '@xeplr/ui-factory'
+import { factory } from '../api/factory.js'
 import TasksHelp from './TasksHelp.jsx'
-
-const STATUSES = [
-  { value: 'todo', label: 'To do' },
-  { value: 'in_progress', label: 'In progress' },
-  { value: 'done', label: 'Done' }
-]
+import { taskHooks } from './EditTask.jsx'
 
 export default function Tasks() {
-  const { tasks, form, setField, submit, edit, cancel, remove, editingId, busy, error } =
-    useTasksController()
+  const [screen, setScreen] = useState(null)
+  const [error, setError] = useState(null)
+
+  useEffect(() => {
+    factory.loadScreen('task_list').then(setScreen, (e) => setError(e.message))
+  }, [])
 
   return (
     <div className="app-page app-page-split">
       <div className="app-page-main">
-      <h1>Tasks</h1>
-      <p className="app-page-lead">
-        A sample form and list. One model, one migration, one line of routing.
-      </p>
-
-      {error && <div className="app-error">{error}</div>}
-
-      <form className="app-form" onSubmit={submit}>
-        <label className="app-field">
-          <span>Title</span>
-          <input
-            value={form.title}
-            onChange={(e) => setField('title', e.target.value)}
-            placeholder="What needs doing?"
-            required
-          />
-        </label>
-
-        <label className="app-field">
-          <span>Description</span>
-          <textarea
-            rows={2}
-            value={form.description}
-            onChange={(e) => setField('description', e.target.value)}
-            placeholder="Optional"
-          />
-        </label>
-
-        <div className="app-field-row">
-          <label className="app-field">
-            <span>Status</span>
-            <select value={form.status} onChange={(e) => setField('status', e.target.value)}>
-              {STATUSES.map((s) => <option key={s.value} value={s.value}>{s.label}</option>)}
-            </select>
-          </label>
-
-          <label className="app-field">
-            <span>Due date</span>
-            <input
-              type="date"
-              value={form.dueDate}
-              onChange={(e) => setField('dueDate', e.target.value)}
-            />
-          </label>
-        </div>
-
-        <div className="app-form-actions">
-          <button type="submit" className="app-btn" disabled={busy}>
-            {editingId ? 'Save changes' : 'Add task'}
-          </button>
-          {editingId && (
-            <button type="button" className="app-btn app-btn-quiet" onClick={cancel}>
-              Cancel
-            </button>
-          )}
-        </div>
-      </form>
-
-      <table className="app-table">
-        <thead>
-          <tr><th>Title</th><th>Status</th><th>Due</th><th /></tr>
-        </thead>
-        <tbody>
-          {tasks.length === 0 && (
-            <tr><td colSpan={4} className="app-empty">No tasks yet. Add one above.</td></tr>
-          )}
-          {tasks.map((t) => (
-            <tr key={t.id} className={editingId === t.id ? 'is-editing' : undefined}>
-              <td>
-                <strong>{t.title}</strong>
-                {t.description && <div className="app-sub">{t.description}</div>}
-              </td>
-              <td><span className={'app-tag is-' + t.status}>{t.status.replace('_', ' ')}</span></td>
-              <td>{t.dueDate ? String(t.dueDate).slice(0, 10) : '—'}</td>
-              <td className="app-row-actions">
-                <button className="app-btn app-btn-quiet" onClick={() => edit(t)}>Edit</button>
-                <button className="app-btn app-btn-quiet" onClick={() => remove(t.id)}>Delete</button>
-              </td>
-            </tr>
-          ))}
-        </tbody>
-      </table>
+        {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} />}
       </div>
-
       <TasksHelp />
     </div>
   )

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

@@ -1,64 +1,80 @@
-// The panel beside the sample form. It is here so the first thing anybody
-// builds is explained where they are looking, rather than in a document they
-// have to go and find.
+import { useState } from 'react'
+
+// The panel beside the sample. It is here so the first thing anybody builds is
+// explained where they are looking, rather than in a document they have to go
+// 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.'
+
 export default function TasksHelp() {
+  const [copied, setCopied] = useState(false)
+  const copy = () => {
+    navigator.clipboard.writeText(PROMPT).then(() => {
+      setCopied(true)
+      setTimeout(() => setCopied(false), 2000)
+    }, () => {})
+  }
+
   return (
     <aside className="app-help">
       <div className="app-help-badge">Sample</div>
-      <h2>This page is an example</h2>
+      <h2>Create your own UI with Claude</h2>
       <p>
-        A task has a title, a description, a status and a due date. Nothing here
-        is special — it is the same five pieces you will write for anything your
-        app stores. Delete it once you have your own.
+        Open Claude in this project's folder (the one with <code>api</code> and{' '}
+        <code>ui</code>) and give it this — change the name and the fields:
+      </p>
+      <pre className="app-help-prompt">{PROMPT}</pre>
+      <button type="button" className="app-btn app-btn-quiet" onClick={copy}>
+        {copied ? 'Copied' : 'Copy prompt'}
+      </button>
+      <p>
+        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". When Claude is
+        done, restart the sign-in service and the API: the menu item appears and
+        the table is created.
       </p>
 
-      <h3>Add your own, in five pieces</h3>
-      <ol className="app-help-steps">
-        <li>
-          <strong>The table</strong>
-          <code>api/migrations/0002_things.sql</code>
-          <span>Runs by itself when the API next starts.</span>
-        </li>
-        <li>
-          <strong>The model</strong>
-          <code>api/models/Thing.js</code>
-          <span>
-            Names the table and lists the fields, with the rules for each. Those
-            rules are checked on every save.
-          </span>
-        </li>
-        <li>
-          <strong>The routes</strong>
-          <code>api/routes/index.js</code>
-          <span>
-            One line — hand the model to <code>genericRoute</code> and you get
-            list, fetch, save and delete. You write none of them.
-          </span>
-        </li>
-        <li>
-          <strong>The page</strong>
-          <code>ui/src/pages/Things.jsx</code>
-          <span>
-            Plus a file for the calls and one for the form's behaviour, so a new
-            look means replacing the page only.
-          </span>
-        </li>
-        <li>
-          <strong>The menu entry</strong>
-          <code>api/migrations-auth/000N_things_menu.sql</code>
-          <span>
-            The side-rail item appears only if its name exists in the database,
-            spelled exactly the same.
-          </span>
-        </li>
-      </ol>
+      <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.
+      </p>
+
+      <h3>Change it</h3>
+      <p>
+        Open <strong>Forms</strong> in the side rail and{' '}
+        <strong>Design form</strong> on Tasks. Add a field, move one, change a
+        label or a colour — then <strong>Publish</strong>. The table gains its
+        new column as you publish.
+      </p>
+
+      <h3>Or by hand</h3>
+      <p>
+        <strong>Forms → New form</strong>: name it, design it, publish it, open
+        it — no code. The full steps for a form with its own page, hooks and
+        model are in <code>CLAUDE.md</code>, under "Create a new UI".
+      </p>
+
+      <h3>More than saving</h3>
+      <p>
+        In the browser — a value added before saving, rows filtered for display,
+        an extra button on each row: <code>ui/src/pages/EditTask.jsx</code>.
+        Every method calls <code>super</code>; change the one you need.
+      </p>
+      <p>
+        On the server — a check against other records, an email afterwards, a
+        list only managers see: <code>api/screens/task/task.hooks.js</code>.
+      </p>
 
       <h3>Two things that catch people</h3>
       <ul className="app-help-notes">
         <li>
-          Keep every data address under <code>/api</code>. Serve data at{' '}
-          <code>/things</code> and it hides the <em>page</em> at the same
-          address — you get raw data instead of your app.
+          Once a screen is published, the <em>database</em> holds its design.
+          Editing its <code>.screen.json</code> afterwards changes nothing — use
+          Forms.
         </li>
         <li>
           A new menu entry is remembered for ten minutes. Restart the sign-in

package/templates/ui/vite.config.js

@@ -43,7 +43,7 @@ export default defineConfig(({ mode }) => {
     plugins: [react()],
     // Force every import to THIS app's copy, so hook-using libraries don't
     // load twice and break the rules of hooks in ways that read as impossible.
-    resolve: { dedupe: ['react', 'react-dom', 'react-router-dom'] },
+    resolve: { dedupe: ['react', 'react-dom', 'react-router-dom', '@xeplr/ui-canvas', '@xeplr/ui-table'] },
     server: { port, strictPort: true, proxy },
     preview: { port, strictPort: true }
   }

package/templates-tenancy/api/migrations/0001_tenants.sql

@@ -0,0 +1,8 @@
+-- The tables the picker lists and adds to: __MT_LEVEL_NAMES__.
+--
+-- Deliberately plain — an id and a name. Add what your app needs (an address,
+-- a plan) with a later migration. Who may use one is NOT here: that is a
+-- membership row in the sign-in database (userTenantsMapping), made for
+-- whoever adds it.
+
+__MT_TABLES_SQL__

package/templates-tenancy/api/migrations-auth/0004_switch_menu.sql

@@ -0,0 +1,10 @@
+-- "__MT_SWITCH_NAME__" — the drawer item that goes back to the picker.
+--
+-- Public: everybody who signs in works inside one, so everybody can change it.
+-- The name must match ui/src/App.jsx's drawerItems entry EXACTLY.
+
+INSERT INTO "menus" (id, name, "menuGroup", "isPublic", "isActive", "mtId1", "recordCreatedDate", "recordModifiedDate")
+SELECT encode(gen_random_bytes(12), 'hex'), '__MT_SWITCH_NAME__', '', true, true, '*', now(), now()
+WHERE NOT EXISTS (SELECT 1 FROM "menus" WHERE name = '__MT_SWITCH_NAME__');
+
+UPDATE "menus" SET "isPublic" = true WHERE name = '__MT_SWITCH_NAME__';