@xeplr/cli 0.1.2 → 0.1.3

package/templates/api/migrations-auth/0003_designer_menu.sql

@@ -0,0 +1,19 @@
+-- "Designer" — the drawer item for designing screens (ui/src/pages/Designer.jsx).
+--
+-- NOT public: Publish changes database tables, so only the roles that hold
+-- @xeplr/factory's design permission see the item. The API refuses everyone
+-- else anyway ("Access denied: Publish factory screen"); this keeps the menu
+-- honest about 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'), 'Designer', '', false, true, '*', now(), now()
+WHERE NOT EXISTS (SELECT 1 FROM "menus" WHERE name = 'Designer');
+
+INSERT INTO "menuRolesMapping" (id, "roleId", "menuId", "isActive", "mtId1", "recordCreatedDate", "recordModifiedDate")
+SELECT encode(gen_random_bytes(12), 'hex'), r.id, m.id, true, '*', now(), now()
+FROM "roles" r CROSS JOIN "menus" m
+WHERE r.name IN ('Super Admin', 'CompanyAdmin')
+  AND m.name = 'Designer'
+  AND NOT EXISTS (SELECT 1 FROM "menuRolesMapping" x WHERE x."roleId" = r.id AND x."menuId" = m.id);

package/templates/api/models/index.js

@@ -1,7 +1,8 @@
-// Every model this app owns. Add yours here — routes/index.js reads them from
-// this one place rather than reaching into individual files.
-var Task = require('./Task');
+// Models for tables you write by hand (see migrations/README.md) — each one a
+// class extending @xeplr/db's BaseModel, handed to genericRoute in
+// routes/index.js.
+//
+// Tables made with the Designer (screens/) need no model: @xeplr/factory saves
+// and reads them from the screen itself.
 
-module.exports = {
-  Task: Task
-};
+module.exports = {};

package/templates/api/package.json

@@ -17,9 +17,11 @@
     "start-api": "node ./bin/www"
   },
   "dependencies": {
-    "@xeplr/auth": "^1.1.0",
+    "@xeplr/auth": "^1.1.2",
     "@xeplr/base-apis": "^2.0.0",
-    "@xeplr/db": "^1.0.5",
+    "@xeplr/db": "^1.0.6",
+    "@xeplr/factory": "^1.0.3",
+    "@xeplr/utils": "^1.0.8",
     "dotenv": "^17.4.2",
     "express": "^5.2.0"
   },

package/templates/api/routes/index.js

@@ -1,6 +1,4 @@
 var express = require('express');
-var { genericRoute } = require('@xeplr/base-apis');
-var { Task } = require('../models');
 
 var router = express.Router();
 
@@ -21,26 +19,19 @@ router.get('/whoami', function(req, res) {
   res.json({ user: req.user, roles: (req.access || {}).roles || [] });
 });
 
-// ── tasks ────────────────────────────────────────────────────────────────
+// ── your data ────────────────────────────────────────────────────────────
 //
 // MOUNTED UNDER /api, and that prefix matters. The browser asks the UI's dev
 // server for BOTH its own pages and its data, and the dev server decides by
 // path which to forward. Serve data at /tasks and the UI's own /tasks page is
 // shadowed by it — opening that page shows raw JSON instead of the app.
 //
-// Keeping every data address under /api means a page path and a data path can
-// never collide, whatever either is called later.
+// Screens made in the Designer (tasks) need nothing here — @xeplr/factory
+// serves them at /api/factory/..., mounted in app.js.
 //
-// FOUR ADDRESSES FROM ONE LINE. Hand genericRoute a model and it builds:
+// A table you write by hand gets its four addresses from one line:
 //
-//   GET  /api/tasks         list, paginated  (?page=1&limit=50)
-//   GET  /api/tasks/:id     one task
-//   POST /api/tasks/save    create and update, in one transaction
-//   POST /api/tasks/delete  soft delete by ids
-//
-// No handler is written for any of them. The model's own jsonSchema is what
-// validates the incoming values, so the rules live in one place rather than
-// being restated here.
-router.use('/api/tasks', genericRoute({ key: 'task', model: Task }));
+//   var { genericRoute } = require('@xeplr/base-apis');
+//   router.use('/api/things', genericRoute({ key: 'thing', model: require('../models').Thing }));
 
 module.exports = router;

package/templates/api/screens/index.js

@@ -0,0 +1,32 @@
+// THE SCREENS THIS APP SHIPS WITH — designed with @xeplr/ui-factory.
+//
+// Each entity is two screens: a list, and the add / edit form the list opens
+// in a popup. Their records live in a REAL table named for the entity
+// ("tasks"), one column per field.
+//
+// On startup (bin/www) every screen here that has never been published is
+// published — which creates its table. After that the DATABASE holds the
+// design: change it in the app's Designer page, where Publish changes the
+// table to match. Editing a .screen.json later changes nothing for an
+// already-published screen.
+//
+// ADD AN ENTITY:
+//
+//   npx xeplr-factory screens screens/project/project.entity.json -o screens/project
+//
+// then list its two screens and its hooks below, and add a page and a menu
+// entry for it (see the UI's src/pages/Tasks.jsx and migrations-auth/).
+
+module.exports = {
+  // Publish order is worked out for you: a table before the dropdowns that
+  // point at it, lists last.
+  documents: [
+    require('./task/task-edit.screen.json'),
+    require('./task/task-list.screen.json')
+  ],
+
+  // Your own code around save / get / delete, per screen — see task/task.hooks.js.
+  hooks: {
+    task_edit: require('./task/task.hooks')
+  }
+};

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

@@ -0,0 +1,103 @@
+{
+  "kind": "xeplr-screen",
+  "version": 1,
+  "id": "task_edit",
+  "name": "Add / edit task",
+  "units": "fraction",
+  "aspect": 1,
+  "width": 800,
+  "nodes": [
+    {
+      "id": "label",
+      "type": "label",
+      "x": 0.04,
+      "y": 0.04,
+      "w": 0.92,
+      "h": 0.07,
+      "z": 1,
+      "props": {
+        "text": "Add / edit task",
+        "variant": "heading"
+      }
+    },
+    {
+      "id": "title",
+      "type": "text",
+      "x": 0.04,
+      "y": 0.15,
+      "w": 0.4475,
+      "h": 0.08,
+      "z": 2,
+      "props": {
+        "label": "Title",
+        "required": true,
+        "validation": {
+          "maxLength": 200
+        },
+        "name": "title"
+      }
+    },
+    {
+      "id": "status",
+      "type": "dropdown",
+      "x": 0.5125,
+      "y": 0.15,
+      "w": 0.4475,
+      "h": 0.08,
+      "z": 3,
+      "props": {
+        "label": "Status",
+        "placeholder": "Select…",
+        "data": {
+          "source": "static",
+          "options": [
+            {
+              "id": "to_do",
+              "name": "To do"
+            },
+            {
+              "id": "in_progress",
+              "name": "In progress"
+            },
+            {
+              "id": "done",
+              "name": "Done"
+            }
+          ]
+        },
+        "required": true,
+        "name": "status"
+      }
+    },
+    {
+      "id": "dueDate",
+      "type": "date",
+      "x": 0.04,
+      "y": 0.27,
+      "w": 0.4475,
+      "h": 0.08,
+      "z": 4,
+      "props": {
+        "label": "Due date",
+        "name": "dueDate"
+      }
+    },
+    {
+      "id": "description",
+      "type": "textarea",
+      "x": 0.04,
+      "y": 0.39,
+      "w": 0.92,
+      "h": 0.18,
+      "z": 5,
+      "props": {
+        "label": "Description",
+        "validation": {
+          "maxLength": 1000
+        },
+        "name": "description"
+      }
+    }
+  ],
+  "source": "tasks"
+}

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

@@ -0,0 +1,45 @@
+{
+  "kind": "xeplr-screen",
+  "version": 1,
+  "id": "task_list",
+  "name": "Tasks",
+  "units": "fraction",
+  "aspect": 1,
+  "width": 800,
+  "nodes": [
+    {
+      "id": "list",
+      "type": "list",
+      "x": 0.04,
+      "y": 0.04,
+      "w": 0.92,
+      "h": 0.8,
+      "z": 1,
+      "props": {
+        "title": "Tasks",
+        "pageSize": 10,
+        "actions": [
+          "new",
+          "edit",
+          "delete"
+        ],
+        "editScreen": "task_edit",
+        "columns": [
+          {
+            "field": "title",
+            "label": "Title"
+          },
+          {
+            "field": "status",
+            "label": "Status"
+          },
+          {
+            "field": "dueDate",
+            "label": "Due date"
+          }
+        ]
+      }
+    }
+  ],
+  "source": "tasks"
+}

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

@@ -0,0 +1,10 @@
+{
+  "entity": "task",
+  "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 } }
+  ],
+  "listColumns": ["title", "status", "dueDate"]
+}

package/templates/api/screens/task/task.hooks.js

@@ -0,0 +1,37 @@
+// Server hooks for task records — screen "task_edit" (and "task_list", which edits in it).
+//
+// Register with @xeplr/factory:
+//   factory.init({ knex, hooks: { task_edit: require('./task.hooks') } })
+//
+// Each operation has four hooks. Delete the ones you do not need.
+//   before(ctx)       first — save: return new values to replace them (they are then checked
+//                     against the screen's rules); get: narrow ctx.query; any: ctx.reject(message, { field })
+//   after(ctx)        once it succeeded — ctx.id, ctx.result; return a value to replace the result.
+//                     If it throws, the operation still happened (and error is told).
+//   error(ctx, err)   when the operation failed
+//   override(ctx)     does the WHOLE operation instead — no rules, no before / after / error,
+//                     no generic query. What it returns is the response.
+//
+// ctx: op, screenKey, screen, table, id, isNew (save), many (get), input (what the UI sent, read-only),
+//      values (save), previous (save / delete: the row before), result, user, tenant, knex, query (get), reject
+
+module.exports = {
+  save: {
+    // before: async function(ctx) { return ctx.values },
+    // after: async function(ctx) {},
+    // error: async function(ctx, err) {},
+    // override: async function(ctx) { return savedRecord },
+  },
+  get: {
+    // before: async function(ctx) { /* ctx.query.where(...) */ },
+    // after: async function(ctx) { return ctx.result },
+    // error: async function(ctx, err) {},
+    // override: async function(ctx) { return ctx.id ? record : records },
+  },
+  delete: {
+    // before: async function(ctx) {},
+    // after: async function(ctx) {},
+    // error: async function(ctx, err) {},
+    // override: async function(ctx) { return { id: ctx.id } },
+  }
+}

package/templates/ui/package.json

@@ -9,7 +9,11 @@
     "preview": "vite preview"
   },
   "dependencies": {
+    "@tanstack/react-table": "^8.21.3",
     "@xeplr/ui-account": "^1.0.6",
+    "@xeplr/ui-canvas": "^1.0.2",
+    "@xeplr/ui-factory": "^1.0.4",
+    "@xeplr/ui-table": "^1.0.6",
     "react": "^19.2.4",
     "react-dom": "^19.2.4",
     "react-router-dom": "^7.13.2"

package/templates/ui/src/App.jsx

@@ -3,6 +3,8 @@ import { Routes, Route, Outlet, Navigate, useNavigate } from 'react-router-dom'
 import { authRoutes, authPath, NavPage, ProtectedRoute } from '@xeplr/ui-account'
 import Home from './pages/Home.jsx'
 import Tasks from './pages/Tasks.jsx'
+import Designer from './pages/Designer.jsx'
+__MT_APP_UI_IMPORTS__
 
 // The rail is ICON-ONLY when collapsed, so a drawer item without one is
 // invisible until somebody widens the rail. Same 24x24 stroke language the
@@ -15,6 +17,15 @@ const TasksIcon = (
   </svg>
 )
 
+const DesignerIcon = (
+  <svg viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor"
+       strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+    <rect x="3" y="3" width="18" height="18" rx="2" />
+    <path d="M3 9h18M9 21V9" />
+  </svg>
+)
+
+__MT_SWITCH_ICON__
 const HomeIcon = (
   <svg viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor"
        strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
@@ -42,7 +53,10 @@ function Shell() {
   // item with no error anywhere.
   const drawerItems = useMemo(() => [
     { name: 'Home', icon: HomeIcon, clickHandler: () => navigate('/home') },
-    { name: 'Tasks', icon: TasksIcon, clickHandler: () => navigate('/tasks') }
+    { name: 'Tasks', icon: TasksIcon, clickHandler: () => navigate('/tasks') },
+    // Shown only to roles given the "Designer" menu (migrations-auth/0003).
+    { name: 'Designer', icon: DesignerIcon, clickHandler: () => navigate('/designer') },
+__MT_DRAWER_ITEM__
   ], [navigate])
 
   return (
@@ -72,10 +86,12 @@ export default function App() {
           our own chrome. */}
       {authRoutes({}, { layout: <Shell /> })}
 
-      <Route element={<ProtectedRoute><Shell /></ProtectedRoute>}>
+__MT_SELECT_ROUTE__
+      <Route element={<ProtectedRoute>__MT_GATE_OPEN__<Shell />__MT_GATE_CLOSE__</ProtectedRoute>}>
         <Route path="/" element={<Navigate to="/home" replace />} />
         <Route path="/home" element={<Home />} />
         <Route path="/tasks" element={<Tasks />} />
+        <Route path="/designer" element={<Designer />} />
       </Route>
 
       <Route path="*" element={<Navigate to="/auth/login" replace />} />

package/templates/ui/src/api/factory.js

@@ -0,0 +1,10 @@
+// MODEL LAYER — every call the screens and the Designer make, to the API's
+// @xeplr/factory routes (mounted at /api in api/app.js).
+//
+// authFetch attaches the signed-in user's token (and the active company, when
+// the app has tenancy) and returns the PARSED body. createFactoryApi accepts
+// it as it is.
+import { authFetch } from '@xeplr/ui-account'
+import { createFactoryApi } from '@xeplr/ui-factory'
+
+export const factory = createFactoryApi({ fetch: authFetch, base: '/api' })

package/templates/ui/src/index.css

@@ -273,3 +273,28 @@ body { margin: 0; }
   .app-page-split { display: block; }
   .app-help { position: static; margin-top: 28px; width: auto; }
 }
+
+/* ── Designer ─────────────────────────────────────────────────────────── */
+/* The builder fills the space it is given, so it needs a height: the page
+   below the top bar, less .main's padding. */
+.app-designer {
+  display: flex;
+  flex-direction: column;
+  height: calc(100vh - 110px);
+  min-height: 520px;
+  gap: 10px;
+}
+
+.app-designer-bar { display: flex; align-items: center; gap: 6px; flex-wrap: wrap; }
+
+.app-designer-title { font-weight: 600; margin-right: 10px; }
+
+.app-designer-bar .is-active { background: var(--xeplr-bg-secondary); }
+
+.app-designer-canvas {
+  flex: 1;
+  min-height: 0;
+  border: 1px solid var(--xeplr-border-primary);
+  border-radius: 8px;
+  overflow: hidden;
+}

package/templates/ui/src/main.jsx

@@ -3,12 +3,14 @@ import ReactDOM from 'react-dom/client'
 import { BrowserRouter } from 'react-router-dom'
 import { configure, AccessProvider, ThemeProvider } from '@xeplr/ui-account'
 import App from './App.jsx'
+__MT_UI_IMPORTS__
 import './index.css'
 import '@xeplr/ui-account/src/designs/theme.css'
 
 // Auth requests are same-origin in dev — vite proxies /auth/api to AUTH_URL
 // (see vite.config.js, which reads it from .env).
 configure('')
+__MT_UI_REGISTER__
 
 ReactDOM.createRoot(document.getElementById('root')).render(
   <React.StrictMode>

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

@@ -0,0 +1,74 @@
+// THE DESIGNER — change any screen: move and resize fields, add new ones,
+// change labels, rules, fonts and colours.
+//
+// Your edits are kept as a DRAFT automatically. Nobody else sees them until
+// you press Publish, which also changes the screen's database 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 { FactoryBuilder } from '@xeplr/ui-factory'
+import { factory } from '../api/factory.js'
+
+export default function Designer() {
+  const [screens, setScreens] = useState([])
+  const [current, setCurrent] = useState(null)      // { key, document, lockedNames }
+  const [error, setError] = useState(null)
+
+  useEffect(() => {
+    factory.listScreens().then((rows) => {
+      setScreens(rows)
+      if (rows.length) open(rows[0].screenKey)
+    }, (e) => setError(e.message))
+  }, [])                                              // eslint-disable-line react-hooks/exhaustive-deps
+
+  const open = useCallback(async (key) => {
+    try {
+      // The draft if there is one, else the published version — with the field
+      // names that are already columns, which the Designer will not let you rename.
+      const row = await factory.loadDraft(key)
+      setCurrent({ key, document: row.document, lockedNames: row.lockedNames || [] })
+      setError(null)
+    } catch (e) {
+      setError(e.message)
+    }
+  }, [])
+
+  const publish = useCallback(async (doc, options) => {
+    const result = await factory.publish(doc, options)
+    // New columns are now locked names too.
+    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">
+        <span className="app-designer-title">Designer</span>
+        {screens.map((s) => (
+          <button
+            key={s.screenKey}
+            type="button"
+            className={'app-btn app-btn-quiet' + (current && current.key === s.screenKey ? ' is-active' : '')}
+            onClick={() => open(s.screenKey)}
+          >
+            {s.name || s.screenKey}
+          </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={screens.map((s) => ({ id: s.screenKey, name: s.name || s.screenKey }))}
+          />
+        </div>
+      )}
+    </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>Designer</strong>, in the side rail — change the sample task
+          screens, or see how they are made. Publish 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,29 @@
-// 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 in the Designer page and stored by the API; this page only
+// loads the published "task_list" and hands it the calls it needs.
+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' }
-]
-
 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} />}
       </div>
-
       <TasksHelp />
     </div>
   )