@xeplr/cli 0.1.1

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

@@ -0,0 +1,70 @@
+// 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.
+export default function TasksHelp() {
+  return (
+    <aside className="app-help">
+      <div className="app-help-badge">Sample</div>
+      <h2>This page is an example</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.
+      </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>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.
+        </li>
+        <li>
+          A new menu entry is remembered for ten minutes. Restart the sign-in
+          service if you want it immediately.
+        </li>
+      </ul>
+    </aside>
+  )
+}

package/templates/ui/src/useTasksController.js

@@ -0,0 +1,83 @@
+// CONTROLLER LAYER — state and handlers, no JSX.
+//
+// The same split the @xeplr/ui-* libraries use. A different design can import
+// this hook and render the fields however it likes; the behaviour below is
+// unchanged by that, which is what makes a rebrand safe.
+import { useCallback, useEffect, useState } from 'react'
+import { listTasks, saveTasks, deleteTasks } from './api/tasks.js'
+
+const EMPTY = { title: '', description: '', status: 'todo', dueDate: '' }
+
+export function useTasksController() {
+  const [tasks, setTasks] = useState([])
+  const [form, setForm] = useState(EMPTY)
+  const [editingId, setEditingId] = useState(null)
+  const [busy, setBusy] = useState(false)
+  const [error, setError] = useState(null)
+
+  const refresh = useCallback(async () => {
+    try {
+      setTasks(await listTasks())
+      setError(null)
+    } catch (e) {
+      setError(e.message)
+    }
+  }, [])
+
+  useEffect(() => { refresh() }, [refresh])
+
+  const setField = useCallback((name, value) => {
+    setForm((f) => ({ ...f, [name]: value }))
+  }, [])
+
+  const edit = useCallback((task) => {
+    setEditingId(task.id)
+    setForm({
+      title: task.title || '',
+      description: task.description || '',
+      status: task.status || 'todo',
+      // The API returns a full timestamp; a date input wants just the day.
+      dueDate: task.dueDate ? String(task.dueDate).slice(0, 10) : ''
+    })
+  }, [])
+
+  const cancel = useCallback(() => {
+    setEditingId(null)
+    setForm(EMPTY)
+  }, [])
+
+  const submit = useCallback(async (e) => {
+    if (e) e.preventDefault()
+    setBusy(true)
+    try {
+      // An entry with no id is a create; with one, an update. Same call.
+      const entry = { ...form, dueDate: form.dueDate || null }
+      if (editingId) entry.id = editingId
+      await saveTasks([entry])
+      cancel()
+      await refresh()
+      setError(null)
+    } catch (e2) {
+      // The API refuses on the model's own jsonSchema and names the field, so
+      // showing its message beats inventing our own.
+      setError(e2.message)
+    } finally {
+      setBusy(false)
+    }
+  }, [form, editingId, cancel, refresh])
+
+  const remove = useCallback(async (id) => {
+    setBusy(true)
+    try {
+      await deleteTasks([id])
+      if (editingId === id) cancel()
+      await refresh()
+    } catch (e) {
+      setError(e.message)
+    } finally {
+      setBusy(false)
+    }
+  }, [editingId, cancel, refresh])
+
+  return { tasks, form, setField, submit, edit, cancel, remove, editingId, busy, error, refresh }
+}

package/templates/ui/vite.config.js

@@ -0,0 +1,50 @@
+import { defineConfig, loadEnv } from 'vite'
+import react from '@vitejs/plugin-react'
+
+// EVERY API PREFIX THIS APP CALLS.
+//
+// A path missing from this list does NOT fail loudly — Vite falls through to
+// the SPA and serves index.html, so the fetch succeeds and the JSON parse is
+// what breaks: `Unexpected token '<'`. Adding a route to the backend is only
+// half of shipping an endpoint; it has to be listed here too.
+const API_PATHS = [
+  '/health',
+  '/whoami',
+  // Every data address lives under /api, so a PAGE path and a DATA path can
+  // never collide. Without that split, adding '/tasks' here shadowed the UI's
+  // own /tasks page — opening it showed raw JSON instead of the app.
+  '/api'
+]
+
+export default defineConfig(({ mode }) => {
+  // Prefix '' so plain names load, not just VITE_-prefixed ones. These are dev
+  // server settings, not values shipped to the browser.
+  const env = loadEnv(mode, process.cwd(), '')
+
+  // NO PORT LITERALS. A hardcoded fallback is a second answer to a question
+  // .env already answers, and it is the one that wins when the file is missing
+  // — exactly when you want to be told rather than quietly served elsewhere.
+  const port = Number(env.UI_PORT)
+  const authUrl = env.AUTH_URL
+  const apiUrl = env.API_URL
+  if (!port || !authUrl || !apiUrl) {
+    throw new Error('ui/.env must set UI_PORT, AUTH_URL and API_URL')
+  }
+
+  const proxy = {
+    // Only the real network calls (/auth/api/*), NOT bare /auth — that prefix
+    // is also used by client-side routes (/auth/login, /auth/profile), which
+    // must fall through to Vite's SPA index.html rather than the auth backend.
+    '/auth/api': authUrl
+  }
+  API_PATHS.forEach((p) => { proxy[p] = apiUrl })
+
+  return {
+    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'] },
+    server: { port, strictPort: true, proxy },
+    preview: { port, strictPort: true }
+  }
+})