@specverse/engines 4.2.2 → 4.3.0

package/dist/libs/instance-factories/applications/templates/react-starter/skeletons/detail.tsx.template

@@ -4,93 +4,86 @@
  * Safe to edit. Edits are preserved across regeneration via content
  * hashing (see .specverse-gen/hashes.json). To accept an upstream
  * regeneration of this file, delete it first, then run `spv realize`.
+ *
+ * Inspection-only view: entity picker + rendered fields + related lists.
+ * All mutations (create, update, delete, evolve) live in the form view.
+ * To edit/delete, navigate to the form via the sidebar.
  */
-import { use{{PLURAL_MODEL}}Query, useDelete{{MODEL_NAME}}Mutation } from '../hooks/useApi';
+{{RELATED_TAB_IMPORT}}
+import { use{{PLURAL_MODEL}}Query } from '../hooks/useApi';
 {{RELATED_IMPORTS}}
 import type { {{MODEL_NAME}} } from '../types/api';
 
 interface {{MODEL_NAME}}DetailViewProps {
-  entityId: string | number;
-  onEdit?: (item: {{MODEL_NAME}}) => void;
-  onBack?: () => void;
-  /** Called after the delete mutation succeeds. */
-  onDeleted?: () => void;
+  /** Initial selection. When absent, the first entity in the list is shown. */
+  entityId?: string | number;
+  /** Called when the user picks a different entity from the picker. */
+  onEntityChange?: (id: string | number) => void;
+  /** Called when the user clicks a resolved belongsTo cell or a related-list
+   *  row. Wired by App.tsx to navigate to the target model's detail view. */
+  onNavigate?: (model: string, id: string | number) => void;
 }
 
 export function {{MODEL_NAME}}DetailView({
   entityId,
-  onEdit,
-  onBack,
-  onDeleted,
+  onEntityChange,
+  onNavigate,
 }: {{MODEL_NAME}}DetailViewProps) {
+  // onNavigate is referenced from walker-emitted FK cells + related-row
+  // clicks below; reference it here so TS doesn't flag it unused for
+  // models without belongsTo or hasMany.
+  void onNavigate;
   const { data: items = [], isLoading, error } = use{{PLURAL_MODEL}}Query();
-  const deleteItem = useDelete{{MODEL_NAME}}Mutation();
 {{RELATED_HOOKS}}
+{{RELATED_TAB_STATE}}
 
+  // Resolve which entity to display: explicit prop wins, else first item.
+  const activeId = entityId ?? (items[0] as any)?.id;
   const item = items.find(
-    (x: {{MODEL_NAME}}) => (x as any).id === entityId
+    (x: {{MODEL_NAME}}) => (x as any).id === activeId
   );
 
   if (isLoading) return <div className="p-4 text-gray-500">Loading…</div>;
   if (error) return <div className="p-4 text-red-600">Error loading {{PLURAL_LOWER}}: {String(error)}</div>;
-  if (!item) return <div className="p-4 text-gray-400">No {{SINGULAR_LOWER}} matching id {String(entityId)}.</div>;
-
-  const handleDelete = async () => {
-    if (!confirm('Delete this {{SINGULAR_LOWER}}?')) return;
-    try {
-      await deleteItem.mutateAsync((item as any).id);
-      onDeleted?.();
-    } catch {
-      // deleteItem.error is surfaced below
-    }
-  };
 
   return (
     <div className="p-6 space-y-4">
-      <div className="flex items-center justify-between">
-        <div className="flex items-center gap-3">
-          {onBack && (
-            <button
-              type="button"
-              onClick={onBack}
-              className="text-sm text-gray-500 hover:text-gray-700"
-            >
-              ← Back
-            </button>
-          )}
-          <h2 className="text-xl font-semibold text-gray-900 dark:text-gray-100">
-            {{MODEL_NAME}} detail
-          </h2>
-        </div>
-        <div className="flex gap-2">
-          {onEdit && (
-            <button
-              type="button"
-              onClick={() => onEdit(item)}
-              className="rounded bg-blue-600 px-4 py-2 text-sm font-medium text-white hover:bg-blue-700"
-            >
-              Edit
-            </button>
+      <div className="flex items-center gap-3">
+        <label
+          htmlFor="{{SINGULAR_LOWER}}-picker"
+          className="text-sm font-medium text-gray-700 dark:text-gray-300"
+        >
+          Select {{MODEL_NAME}}:
+        </label>
+        <select
+          id="{{SINGULAR_LOWER}}-picker"
+          value={activeId == null ? '' : String(activeId)}
+          onChange={e => onEntityChange?.(e.target.value)}
+          className="flex-1 max-w-xl rounded border border-gray-300 px-3 py-2 text-sm dark:border-gray-600 dark:bg-gray-800 dark:text-gray-100"
+        >
+          {items.length === 0 && (
+            <option value="">No {{PLURAL_LOWER}} yet</option>
           )}
-          <button
-            type="button"
-            onClick={handleDelete}
-            disabled={deleteItem.isPending}
-            className="rounded bg-red-600 px-4 py-2 text-sm font-medium text-white hover:bg-red-700 disabled:opacity-60"
-          >
-            {deleteItem.isPending ? 'Deleting…' : 'Delete'}
-          </button>
-        </div>
+          {items.map((x: {{MODEL_NAME}}) => (
+            <option key={String((x as any).id)} value={String((x as any).id)}>
+              {getEntityDisplayName(x)}
+            </option>
+          ))}
+        </select>
       </div>
 
-      {/* Pattern-rendered detail body (fields). Edit freely. */}
-      {{BODY}}
-
-      {deleteItem.isError && (
-        <div className="p-2 text-sm text-red-600">
-          Delete failed: {String(deleteItem.error)}
+      {!item && (
+        <div className="rounded-lg border border-gray-200 bg-white p-6 text-sm text-gray-400 dark:border-gray-700 dark:bg-gray-900">
+          No {{SINGULAR_LOWER}} to display.
         </div>
       )}
+
+      {item && (
+        <>
+          {/* Pattern-rendered detail body (fields + related). Edit freely. */}
+          {{BODY}}
+        </>
+      )}
     </div>
   );
 }

package/dist/libs/instance-factories/applications/templates/react-starter/skeletons/form.tsx.template

@@ -6,36 +6,56 @@
  * regeneration of this file, delete it first, then run `spv realize`.
  *
  * Controlled form. One field per non-auto-generated attribute.
- * Mode: 'create' (default) or 'update' — passed as a prop.
+ * Mode: 'create' (default) or 'update'. When the model has one or
+ * more lifecycles AND mode = 'update', an "Evolve" tab appears
+ * alongside "Edit" that drives a state transition via PATCH /:id/evolve.
  */
 import { useEffect, useState } from 'react';
 import {
   use{{PLURAL_MODEL}}Query,
   useCreate{{MODEL_NAME}}Mutation,
   useUpdate{{MODEL_NAME}}Mutation,
+  useDelete{{MODEL_NAME}}Mutation,
+{{LIFECYCLE_IMPORTS}}
 } from '../hooks/useApi';
 {{RELATED_IMPORTS}}
 import type { {{MODEL_NAME}} } from '../types/api';
+import { {{MODEL_NAME}}ListView } from './{{MODEL_NAME}}ListView';
 
 type FormMode = 'create' | 'update';
+type ActiveTab = 'edit' | 'evolve';
 
 interface {{MODEL_NAME}}FormViewProps {
   mode?: FormMode;
   /** Required in update mode. */
   entityId?: string | number;
   onSuccess?: (item: {{MODEL_NAME}}) => void;
-  onCancel?: () => void;
+  /** Called after the delete mutation succeeds. Wired by App.tsx to
+   *  navigate back to the list view. */
+  onDeleted?: () => void;
+  /** Called when the user clicks a row in the embedded
+   *  {{MODEL_NAME}}ListView below the form. Wired by App.tsx to
+   *  re-navigate to this form with `entityId` set, so clicking a
+   *  row loads that entity's data into the form for update. */
+  onSelectEntity?: (item: {{MODEL_NAME}}) => void;
 }
 
 export function {{MODEL_NAME}}FormView({
   mode = 'create',
   entityId,
   onSuccess,
-  onCancel,
+  onDeleted,
+  onSelectEntity,
 }: {{MODEL_NAME}}FormViewProps) {
+  // Referenced from the walker-emitted <{{MODEL_NAME}}ListView
+  // onSelect={onSelectEntity} /> below; void it here so strict TS
+  // doesn't flag it when body positioning elides the reference.
+  void onSelectEntity;
   const { data: items = [] } = use{{PLURAL_MODEL}}Query();
   const createItem = useCreate{{MODEL_NAME}}Mutation();
   const updateItem = useUpdate{{MODEL_NAME}}Mutation();
+  const deleteItem = useDelete{{MODEL_NAME}}Mutation();
+{{LIFECYCLE_HOOK}}
 {{RELATED_HOOKS}}
 
   const existing =
@@ -44,6 +64,8 @@ export function {{MODEL_NAME}}FormView({
       : undefined;
 
   const [formData, setFormData] = useState<Partial<{{MODEL_NAME}}>>(existing ?? {});
+  const [activeTab, setActiveTab] = useState<ActiveTab>('edit');
+{{LIFECYCLE_STATE}}
 
   // When the fetched list lands after initial render (update mode),
   // hydrate the form with the loaded entity's data.
@@ -55,6 +77,21 @@ export function {{MODEL_NAME}}FormView({
     setFormData(prev => ({ ...prev, [field]: value }) as Partial<{{MODEL_NAME}}>);
   };
 
+  const handleClear = () => {
+    setFormData(existing ?? {});
+  };
+
+  const handleDelete = async () => {
+    if (mode !== 'update' || entityId == null) return;
+    if (!confirm('Delete this {{SINGULAR_LOWER}}?')) return;
+    try {
+      await deleteItem.mutateAsync(entityId as any);
+      onDeleted?.();
+    } catch {
+      // deleteItem.error is surfaced below
+    }
+  };
+
   const handleSubmit = async (event: React.FormEvent) => {
     event.preventDefault();
     try {
@@ -71,46 +108,97 @@ export function {{MODEL_NAME}}FormView({
     }
   };
 
+{{LIFECYCLE_HANDLER}}
+
   const mutation = mode === 'create' ? createItem : updateItem;
   const submitLabel =
     mode === 'create'
       ? mutation.isPending ? 'Creating…' : 'Create {{MODEL_NAME}}'
       : mutation.isPending ? 'Updating…' : 'Update {{MODEL_NAME}}';
 
+  const hasLifecycles = {{HAS_LIFECYCLES}};
+  const showTabs = mode === 'update' && hasLifecycles;
+
   return (
-    <form onSubmit={handleSubmit} className="p-6 space-y-6">
+    <div className="p-6 space-y-6">
       <h2 className="text-xl font-semibold text-gray-900 dark:text-gray-100">
         {mode === 'create' ? 'New {{MODEL_NAME}}' : 'Edit {{MODEL_NAME}}'}
       </h2>
 
-      {/* Pattern-rendered form fields. Edit freely. */}
-      {{BODY}}
-
-      <div className="flex gap-2 border-t border-gray-200 dark:border-gray-700 pt-4">
-        <button
-          type="submit"
-          disabled={mutation.isPending}
-          className="rounded bg-blue-600 px-4 py-2 text-sm font-medium text-white hover:bg-blue-700 disabled:opacity-60"
-        >
-          {submitLabel}
-        </button>
-        {onCancel && (
+      {showTabs && (
+        <div className="flex gap-1 border-b border-gray-200 dark:border-gray-700">
           <button
             type="button"
-            onClick={onCancel}
-            className="rounded border border-gray-300 px-4 py-2 text-sm font-medium text-gray-700 hover:bg-gray-50 dark:border-gray-600 dark:text-gray-200 dark:hover:bg-gray-800"
+            onClick={() => setActiveTab('edit')}
+            className={`px-4 py-2 text-sm font-medium border-b-2 -mb-px ${activeTab === 'edit' ? 'border-blue-600 text-blue-600 dark:border-blue-400 dark:text-blue-400' : 'border-transparent text-gray-500 hover:text-gray-700 dark:text-gray-400 dark:hover:text-gray-200'}`}
           >
-            Cancel
+            Edit
+          </button>
+          <button
+            type="button"
+            onClick={() => setActiveTab('evolve')}
+            className={`px-4 py-2 text-sm font-medium border-b-2 -mb-px ${activeTab === 'evolve' ? 'border-blue-600 text-blue-600 dark:border-blue-400 dark:text-blue-400' : 'border-transparent text-gray-500 hover:text-gray-700 dark:text-gray-400 dark:hover:text-gray-200'}`}
+          >
+            Evolve
           </button>
-        )}
-      </div>
-
-      {mutation.isError && (
-        <div className="rounded border border-red-200 bg-red-50 p-3 text-sm text-red-700 dark:border-red-800 dark:bg-red-950 dark:text-red-300">
-          {mode === 'create' ? 'Create failed: ' : 'Update failed: '}
-          {String(mutation.error)}
         </div>
       )}
-    </form>
+
+      {(!showTabs || activeTab === 'edit') && (
+        <>
+          <form onSubmit={handleSubmit} className="space-y-6">
+            {/* Pattern-rendered form fields. Edit freely. */}
+{{FIELDS_BODY}}
+
+            <div className="flex gap-2">
+              <button
+                type="submit"
+                disabled={mutation.isPending}
+                className="rounded bg-blue-600 px-4 py-2 text-sm font-medium text-white hover:bg-blue-700 disabled:opacity-60"
+              >
+                {submitLabel}
+              </button>
+              {mode === 'update' && (
+                <button
+                  type="button"
+                  onClick={handleDelete}
+                  disabled={deleteItem.isPending}
+                  className="rounded bg-red-600 px-4 py-2 text-sm font-medium text-white hover:bg-red-700 disabled:opacity-60"
+                >
+                  {deleteItem.isPending ? 'Deleting…' : 'Delete'}
+                </button>
+              )}
+              <button
+                type="button"
+                onClick={handleClear}
+                disabled={mutation.isPending}
+                className="rounded border border-gray-300 px-4 py-2 text-sm font-medium text-gray-700 hover:bg-gray-100 disabled:opacity-60 dark:border-gray-600 dark:text-gray-200 dark:hover:bg-gray-800"
+              >
+                Clear
+              </button>
+            </div>
+
+            {mutation.isError && (
+              <div className="rounded border border-red-200 bg-red-50 p-3 text-sm text-red-700 dark:border-red-800 dark:bg-red-950 dark:text-red-300">
+                {mode === 'create' ? 'Create failed: ' : 'Update failed: '}
+                {String(mutation.error)}
+              </div>
+            )}
+
+            {deleteItem.isError && (
+              <div className="rounded border border-red-200 bg-red-50 p-3 text-sm text-red-700 dark:border-red-800 dark:bg-red-950 dark:text-red-300">
+                Delete failed: {String(deleteItem.error)}
+              </div>
+            )}
+          </form>
+
+          {/* Existing entities list sits outside the <form> so its
+              search input and inner interactions don't submit the form. */}
+{{EXISTING_LIST_BODY}}
+        </>
+      )}
+
+{{LIFECYCLE_PANEL}}
+    </div>
   );
 }

package/dist/libs/instance-factories/applications/templates/react-starter/skeletons/list.tsx.template

@@ -13,9 +13,15 @@ import type { {{MODEL_NAME}} } from '../types/api';
 interface {{MODEL_NAME}}ListViewProps {
   onSelect?: (item: {{MODEL_NAME}}) => void;
   onCreate?: () => void;
+  /** Called when the user clicks a resolved belongsTo cell.
+   *  Wired by App.tsx to switch to the target model's detail view. */
+  onNavigate?: (model: string, id: string | number) => void;
 }
 
-export function {{MODEL_NAME}}ListView({ onSelect, onCreate }: {{MODEL_NAME}}ListViewProps) {
+export function {{MODEL_NAME}}ListView({ onSelect, onCreate, onNavigate }: {{MODEL_NAME}}ListViewProps) {
+  // onNavigate is referenced from walker-emitted FK cells below; reference
+  // it here so TS doesn't flag it as unused for models without belongsTo.
+  void onNavigate;
   const { data: items = [], isLoading, error } = use{{PLURAL_MODEL}}Query();
   const deleteItem = useDelete{{MODEL_NAME}}Mutation();
 {{RELATED_HOOKS}}
@@ -46,15 +52,17 @@ export function {{MODEL_NAME}}ListView({ onSelect, onCreate }: {{MODEL_NAME}}Lis
           placeholder="Search {{PLURAL_LOWER}}…"
           value={searchTerm}
           onChange={e => setSearchTerm(e.target.value)}
-          className="w-64 rounded border border-gray-300 px-3 py-2 text-sm"
+          className="w-64 rounded border border-gray-300 px-3 py-2 text-sm dark:border-gray-600 dark:bg-gray-800 dark:text-gray-100"
         />
-        <button
-          type="button"
-          onClick={onCreate}
-          className="rounded bg-blue-600 px-4 py-2 text-sm font-medium text-white hover:bg-blue-700"
-        >
-          + New {{MODEL_NAME}}
-        </button>
+        {onCreate && (
+          <button
+            type="button"
+            onClick={onCreate}
+            className="rounded bg-blue-600 px-4 py-2 text-sm font-medium text-white hover:bg-blue-700"
+          >
+            + New {{MODEL_NAME}}
+          </button>
+        )}
       </div>
 
       {/* Pattern-rendered list body (table + rows). Edit freely. */}

package/dist/libs/instance-factories/applications/templates/react-starter/use-api-hooks-starter-generator.js

@@ -3,6 +3,21 @@ function pluralize(s) {
   if (/(s|x|z|ch|sh)$/.test(s)) return s + "es";
   return s + "s";
 }
+function extractLifecycles(model) {
+  const out = [];
+  const lifecycles = model?.lifecycles ?? {};
+  for (const [name, def] of Object.entries(lifecycles)) {
+    if (!def || typeof def !== "object") continue;
+    let states = [];
+    if (Array.isArray(def.states)) {
+      states = def.states.map((s) => typeof s === "string" ? s : s?.name ?? s?.id ?? "").filter(Boolean);
+    } else if (typeof def.flow === "string") {
+      states = def.flow.split(/\s*(?:->|,)\s*/).map((s) => s.trim()).filter(Boolean);
+    }
+    if (states.length > 0) out.push({ name, states });
+  }
+  return out;
+}
 async function generate(context) {
   const models = Object.keys(context.spec.models ?? {});
   const importsAndTypes = `/**
@@ -20,10 +35,13 @@ ${models.map((m) => `import type { ${m} } from '../types/api';`).join("\n")}
 const API_BASE = import.meta.env.VITE_API_BASE_URL || '';
 
 async function fetchJSON<T = unknown>(url: string, init?: RequestInit): Promise<T> {
-  const res = await fetch(url, {
-    headers: { 'Content-Type': 'application/json' },
-    ...init,
-  });
+  // Only declare Content-Type: application/json when there's actually a
+  // body. Fastify's default JSON parser rejects empty-body requests that
+  // claim JSON (FST_ERR_CTP_EMPTY_JSON_BODY) \u2014 so DELETE / GET without
+  // bodies must NOT send the header.
+  const headers: Record<string, string> = {};
+  if (init?.body != null) headers['Content-Type'] = 'application/json';
+  const res = await fetch(url, { ...init, headers: { ...headers, ...init?.headers } });
   if (!res.ok) {
     throw new Error(\`\${res.status} \${res.statusText} \u2014 \${url}\`);
   }
@@ -31,15 +49,36 @@ async function fetchJSON<T = unknown>(url: string, init?: RequestInit): Promise<
   return (await res.json()) as T;
 }
 `;
-  const hookBlocks = models.map((m) => generateModelHooks(m)).join("\n\n");
+  const hookBlocks = models.map((m) => generateModelHooks(m, context.spec.models?.[m])).join("\n\n");
   return importsAndTypes + "\n" + hookBlocks + "\n";
 }
-function generateModelHooks(model) {
+function generateModelHooks(model, modelDef) {
   const plural = pluralize(model);
   const resource = plural.toLowerCase();
-  const modelLower = model.toLowerCase();
+  const lifecycles = extractLifecycles(modelDef);
+  const hasLifecycle = lifecycles.length > 0;
+  const lifecycleBlock = hasLifecycle ? `
+export const ${model.toUpperCase()}_LIFECYCLES = ${JSON.stringify(
+    Object.fromEntries(lifecycles.map((l) => [l.name, { states: l.states }])),
+    null,
+    2
+  )} as const;
+` : "";
+  const evolveHook = hasLifecycle ? `
+export function useEvolve${model}Mutation() {
+  const qc = useQueryClient();
+  return useMutation({
+    mutationFn: ({ id, toState, lifecycleName }: { id: string | number; toState: string; lifecycleName?: string }) =>
+      fetchJSON<${model}>(\`\${API_BASE}/api/${resource}/\${id}/evolve\`, {
+        method: 'PATCH',
+        body: JSON.stringify({ toState, lifecycleName }),
+      }),
+    onSuccess: () => qc.invalidateQueries({ queryKey: ['${resource}'] }),
+  });
+}
+` : "";
   return `// \u2500\u2500\u2500 ${model} \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
-
+${lifecycleBlock}
 export function use${plural}Query() {
   return useQuery({
     queryKey: ['${resource}'],
@@ -72,7 +111,7 @@ export function useUpdate${model}Mutation() {
   return useMutation({
     mutationFn: ({ id, data }: { id: string | number; data: Partial<${model}> }) =>
       fetchJSON<${model}>(\`\${API_BASE}/api/${resource}/\${id}\`, {
-        method: 'PATCH',
+        method: 'PUT',
         body: JSON.stringify(data),
       }),
     onSuccess: () => qc.invalidateQueries({ queryKey: ['${resource}'] }),
@@ -86,7 +125,7 @@ export function useDelete${model}Mutation() {
       fetchJSON<void>(\`\${API_BASE}/api/${resource}/\${id}\`, { method: 'DELETE' }),
     onSuccess: () => qc.invalidateQueries({ queryKey: ['${resource}'] }),
   });
-}`;
+}${evolveHook}`;
 }
 var stdin_default = generate;
 export {