@specverse/engines 4.2.0 → 4.2.2

package/dist/libs/instance-factories/applications/react-app-starter.yaml

@@ -0,0 +1,143 @@
+name: ReactAppStarter
+version: "1.0.0"
+category: view
+description: "Fully standalone React starter kit — pre-rendered view components the user can fork and extend. No @specverse/runtime dependency."
+
+metadata:
+  author: "SpecVerse Team"
+  license: "MIT"
+  tags: [react, vite, spa, frontend, starter, editable]
+  mode: starter
+
+compatibility:
+  specverse: ">=4.0.0"
+  node: ">=18.0.0"
+
+capabilities:
+  provides:
+    - "app.frontend"
+    - "ui.scaffolding"
+    - "ui.router"
+    - "ui.staticviews"
+    - "ui.staticforms"
+    - "ui.staticcomponents"
+  requires: []
+
+technology:
+  runtime: "browser"
+  language: "typescript"
+  framework: "react"
+  bundler: "vite"
+  version: "^18.2.0"
+
+dependencies:
+  # Runtime deps baked into the generated package.json.
+  # Deliberately no @specverse/runtime — the starter kit is
+  # standalone by design.
+  runtime:
+    - name: "react"
+      version: "^18.2.0"
+    - name: "react-dom"
+      version: "^18.2.0"
+    - name: "@tanstack/react-query"
+      version: "^5.0.0"
+
+  dev:
+    - name: "@types/react"
+      version: "^18.2.0"
+    - name: "@types/react-dom"
+      version: "^18.2.0"
+    - name: "typescript"
+      version: "^5.2.0"
+    - name: "vite"
+      version: "^6.0.0"
+    - name: "@vitejs/plugin-react"
+      version: "^4.2.0"
+    - name: "tailwindcss"
+      version: "^3.4.13"
+    - name: "postcss"
+      version: "^8.4.47"
+    - name: "autoprefixer"
+      version: "^10.4.20"
+
+codeTemplates:
+  # === Infrastructure reused from ReactAppRuntime ===
+  # Safe to share because these files don't embed any runtime-specific
+  # logic — just build config + entry points.
+  index-html:
+    engine: typescript
+    generator: "libs/instance-factories/applications/templates/react/index-html-generator.ts"
+    outputPattern: "{frontendDir}/index.html"
+
+  main-tsx:
+    engine: typescript
+    generator: "libs/instance-factories/applications/templates/react/main-tsx-generator.ts"
+    outputPattern: "{frontendDir}/src/main.tsx"
+
+  vite-config:
+    engine: typescript
+    generator: "libs/instance-factories/applications/templates/react/vite-config-generator.ts"
+    outputPattern: "{frontendDir}/vite.config.ts"
+
+  tsconfig:
+    engine: typescript
+    generator: "libs/instance-factories/applications/templates/react/tsconfig-generator.ts"
+    outputPattern: "{frontendDir}/tsconfig.json"
+
+  index-css:
+    engine: typescript
+    generator: "libs/instance-factories/applications/templates/react/index-css-generator.ts"
+    outputPattern: "{frontendDir}/src/index.css"
+
+  gitignore:
+    engine: typescript
+    generator: "libs/instance-factories/applications/templates/react/gitignore-generator.ts"
+    outputPattern: "{frontendDir}/.gitignore"
+
+  env-example:
+    engine: typescript
+    generator: "libs/instance-factories/applications/templates/react/env-example-generator.ts"
+    outputPattern: "{frontendDir}/.env.example"
+
+  # API wiring — starter-specific. The starter's hooks inline their
+  # own fetch transport so there is NO apiClient.ts (the runtime
+  # apiClient imports runtime-only types that this factory doesn't
+  # emit). Users wanting a shared transport layer can add one by
+  # hand; the hooks file is intentionally small enough to edit.
+  use-api-hooks:
+    engine: typescript
+    generator: "libs/instance-factories/applications/templates/react-starter/use-api-hooks-starter-generator.ts"
+    outputPattern: "{frontendDir}/src/hooks/useApi.ts"
+
+  api-types:
+    engine: typescript
+    generator: "libs/instance-factories/applications/templates/react-starter/api-types-starter-generator.ts"
+    outputPattern: "{frontendDir}/src/types/api.ts"
+
+  # === Starter-specific: emitted view components + helpers + App + package.json ===
+  # The orchestrator returns a map of {relativePath: content} covering:
+  #   src/views/*.tsx         one per (model, view-type) pair
+  #   src/lib/entity-display.ts    FK→name helper (standalone source)
+  #   src/App.tsx             simple internal-routing shell
+  #   package.json            no @specverse/runtime dep
+  #   .specverse-gen/hashes.json  content hashes for regeneration safety
+  #
+  # Regeneration safety is internal to the orchestrator: user-edited
+  # files are omitted from the returned map (so realize never sees
+  # them), and the hash manifest's per-file entries are preserved for
+  # those skipped files so a later un-edit restores regenerability.
+  starter-output:
+    engine: typescript
+    generator: "libs/instance-factories/applications/templates/react-starter/orchestrator.ts"
+    outputPattern: "{frontendDir}/"
+
+configuration:
+  projectStructure: "monorepo"
+  frontendDir: "frontend"
+  backendDir: "backend"
+
+  vite:
+    port: 5173
+    host: "localhost"
+    proxy:
+      "/api": "http://localhost:3000"

package/dist/libs/instance-factories/applications/templates/react/env-example-generator.js

@@ -2,8 +2,30 @@ import { getApiBaseUrl, getPathConfig } from "../../../shared/path-resolver.js";
 function generateEnvExample(context) {
   const pathConfig = getPathConfig(context);
   const defaultApiUrl = getApiBaseUrl(pathConfig);
-  return `# API Configuration
-# Base URL for backend API
+  return `# \u2500\u2500\u2500 Ports \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\u2500
+# Running more than one SpecVerse project at once? Each project reads
+# its own .env \u2014 copy this file to .env and bump the numbers so the
+# projects don't collide.
+#
+# Suggested ranges (shared across the ecosystem):
+#   3000-3049 : generated project backends (one per project)
+#   3050-3099 : app-demo per-spec runtime backends
+#   5173-5199 : vite frontends (one per project)
+#   9000+     : app-demo Server Manager
+
+# Backend (Fastify) port \u2014 read by \`npm run dev:backend\`.
+PORT=3000
+
+# Frontend (vite) port \u2014 read by \`npm run dev:frontend\`.
+VITE_PORT=5173
+
+# Frontend host \u2014 '0.0.0.0' if you want LAN access.
+VITE_HOST=localhost
+
+# \u2500\u2500\u2500 API wiring \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
+# Base URL for backend API. Used by the generated apiClient AND by
+# vite's dev-server proxy (so /api and /ws requests from the browser
+# are forwarded to your backend). Keep this in sync with PORT.
 VITE_API_BASE_URL=${defaultApiUrl}
 
 # API Path Prefix

package/dist/libs/instance-factories/applications/templates/react/vite-config-generator.js

@@ -6,45 +6,66 @@ function generateViteConfig(context) {
   const viteHost = configuration?.vite?.host || "localhost";
   const apiBaseUrl = getApiBaseUrl(pathConfig);
   const apiProxy = configuration?.vite?.proxy?.["/api"] || apiBaseUrl;
-  return `import { defineConfig } from 'vite';
+  return `import { defineConfig, loadEnv } from 'vite';
 import react from '@vitejs/plugin-react';
 import path from 'path';
 
-// https://vitejs.dev/config/
-export default defineConfig({
-  plugins: [react()],
-  server: {
-    port: ${vitePort},
-    host: '${viteHost}',
-    proxy: {
-      '/api': {
-        target: '${apiProxy}',
-        changeOrigin: true,
-      },
-      // WebSocket proxy \u2014 the runtime's useEntitySync hook opens
-      // ws://<host>/ws to receive entity mutation events from the
-      // backend event bus. Without this proxy the socket tries to
-      // connect to the vite dev server on /ws and fails, forcing
-      // state-sync to fall back to React Query's refetchInterval
-      // polling (usable but slow).
-      '/ws': {
-        target: '${apiProxy.replace(/^http/, "ws")}',
-        ws: true,
-        changeOrigin: true,
+/**
+ * Ports and proxy targets are env-overridable via this project's
+ * .env (and .env.local). Lets you run several SpecVerse projects
+ * side-by-side without port collisions:
+ *
+ *   # project-a/.env
+ *   PORT=3001
+ *   VITE_PORT=5174
+ *   VITE_API_BASE_URL=http://localhost:3001
+ *
+ *   # project-b/.env
+ *   PORT=3002
+ *   VITE_PORT=5175
+ *   VITE_API_BASE_URL=http://localhost:3002
+ */
+export default defineConfig(({ mode }) => {
+  const env = loadEnv(mode, process.cwd(), '');
+  const port = Number(env.VITE_PORT ?? ${vitePort});
+  const host = env.VITE_HOST ?? '${viteHost}';
+  const apiTarget = env.VITE_API_BASE_URL ?? '${apiProxy}';
+
+  return {
+    plugins: [react()],
+    server: {
+      port,
+      host,
+      proxy: {
+        '/api': {
+          target: apiTarget,
+          changeOrigin: true,
+        },
+        // WebSocket proxy \u2014 the runtime's useEntitySync hook opens
+        // ws://<host>/ws to receive entity mutation events from the
+        // backend event bus. Without this proxy the socket tries to
+        // connect to the vite dev server on /ws and fails, forcing
+        // state-sync to fall back to React Query's refetchInterval
+        // polling (usable but slow).
+        '/ws': {
+          target: apiTarget.replace(/^http/, 'ws'),
+          ws: true,
+          changeOrigin: true,
+        },
       },
     },
-  },
-  build: {
-    outDir: 'dist',
-    sourcemap: true,
-  },
-  resolve: {
-    alias: {
-      '@': path.resolve(__dirname, './src'),
+    build: {
+      outDir: 'dist',
+      sourcemap: true,
+    },
+    resolve: {
+      alias: {
+        '@': path.resolve(__dirname, './src'),
+      },
+      // Prevent React duplication when using local packages
+      dedupe: ['react', 'react-dom'],
     },
-    // Prevent React duplication when using local packages
-    dedupe: ['react', 'react-dom'],
-  },
+  };
 });
 `;
 }

package/dist/libs/instance-factories/applications/templates/react-starter/README.md

@@ -0,0 +1,211 @@
+# ReactAppStarter — Emitter Architecture
+
+**Audience**: anyone touching the view emitter for Factory B (the "starter-kit" React factory).
+
+**Companion docs**:
+- `specverse-self/docs/guides/VIEW-RENDERING-ARCHITECTURE.md` (the "one pattern library, three consumers" design)
+- `specverse-self/docs/plans/2026-04-17-UNIFIED-VIEW-RENDERING.md` (the migration plan)
+
+---
+
+## The problem this solves
+
+Factory B emits a standalone React codebase. For every view in the inferred spec (dev defaults + user-defined views), it writes a `.tsx` file the user can read, fork, and edit. The generated code:
+
+- Has no `@specverse/runtime` dependency (fully standalone).
+- Is idiomatic React with typed props, hooks, event handlers — not a big static HTML blob.
+- Renders the **same** visual output as `@specverse/runtime` renders for the same spec (verified by Phase 3 parity test P3).
+
+The tension: "idiomatic React structure" wants hand-crafted JSX. "Same visual output as runtime" wants a single rendering authority. Strategy 3 resolves this by splitting *structure* (hand-written skeleton templates) from *interior* (canonical Tailwind adapter rendering).
+
+## The three pieces
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ 1. view-emitter.ts  — orchestrator                          │
+│    Takes (viewSpec, modelSpec, expandedSpec) → .tsx string  │
+└──────────────┬───────────────────────────────┬──────────────┘
+               │                               │
+               ▼                               ▼
+┌──────────────────────────────┐  ┌─────────────────────────────────┐
+│ 2. skeletons/*.tsx.template  │  │ 3. html-to-jsx.ts  — transformer│
+│    One per view type:        │  │                                 │
+│      list.tsx.template       │  │    Converts Tailwind-HTML       │
+│      detail.tsx.template     │  │    strings from the runtime     │
+│      form.tsx.template       │  │    adapter into JSX-safe source │
+│      dashboard.tsx.template  │  │    (class→className, self-close,│
+│      + specialist types      │  │    brace escape, attribute map) │
+│                              │  │                                 │
+│    Each has a {{BODY}}       │  │    ~50-150 LoC, bounded scope   │
+│    placeholder the emitter   │  │                                 │
+│    fills with transformed    │  │                                 │
+│    JSX.                      │  │                                 │
+└──────────────────────────────┘  └─────────────────────────────────┘
+                                              ▲
+                                              │
+                                              │ renders body as HTML
+                                              │
+                        ┌─────────────────────┴──────────────────────┐
+                        │ @specverse/runtime/views/tailwind          │
+                        │  createUniversalTailwindAdapter()          │
+                        │  (the canonical build-time renderer —      │
+                        │   same code app-demo and Factory A         │
+                        │   transitively rely on at runtime)         │
+                        └────────────────────────────────────────────┘
+```
+
+## Data flow for ONE view
+
+Given an inferred `PostListView` in the expanded spec:
+
+1. **view-emitter.ts** receives `(view, model, expandedSpec)`.
+2. Picks the correct skeleton based on `view.type`: `skeletons/list.tsx.template`.
+3. Builds a render context for the pattern: `{ primaryModel: 'Post', modelSchemas: {...}, viewSpec: view, modelData: [] }` (empty data — structure only).
+4. Calls `createUniversalTailwindAdapter()` and renders the composite pattern's interior → HTML string.
+   Example output: `<table class="w-full ..."><thead><tr><th class="...">Title</th>...`.
+5. Passes that HTML through **html-to-jsx.ts** → JSX-safe source.
+   Example: `<table className="w-full ..."><thead><tr><th className="...">{/* data.map */}Title</th>...`.
+6. Substitutes `{{BODY}}` in the skeleton with the transformed JSX.
+7. Substitutes skeleton placeholders like `{{MODEL_NAME}}`, `{{PLURAL}}`, `{{PROPS_INTERFACE}}` with model-specific values.
+8. Returns the complete `.tsx` source string.
+
+The factory's realize pass calls this once per view, writes each to `frontend/src/views/{ViewName}.tsx`, updates `.specverse-gen/hashes.json`.
+
+## Why this split works
+
+- **Idiomatic outer structure** — skeletons are hand-written `.tsx.template` files, tweaked by the humans who maintain the factory. They define imports, props interfaces, hook placement, event wiring, loading states, empty states. Exactly what a human React author would write.
+- **Pattern-driven interior** — the actual markup (table header cells, row templates, form fields, badge styling) comes from the canonical Tailwind adapter. When runtime improves the pattern rendering, Factory B inherits the fix automatically — because the adapter is the single source.
+- **No full re-implementation** — we don't build a second renderer. The adapter already works for runtime; we reuse it at build time.
+
+## The html-to-jsx transformer — scope
+
+Input: HTML string with Tailwind classes. Single root element (always — the adapter always produces a containing element).
+
+Output: A JSX-safe source string that can be dropped between JSX tags.
+
+What it does:
+1. `class="..."` → `className="..."`
+2. Self-closing tags: `<img src="...">` → `<img src="..." />`
+3. Escape `{` and `}` in text content by wrapping in `{'{'}` / `{'}'}` when they appear outside attribute values.
+4. Convert `style="color: red"` to `style={{ color: 'red' }}`.
+5. Convert `for="..."` to `htmlFor="..."`.
+6. Strip any attributes that aren't valid in JSX.
+
+What it explicitly does NOT do:
+- Parse JavaScript inside the HTML (the adapter produces static HTML — no JS expressions).
+- Insert React hooks or event handlers — those live in the skeleton, not the interior.
+- Handle SVG / MathML nuances — only HTML+Tailwind.
+
+Test coverage target: feed the transformer 50 pre-captured HTML snippets from the canonical adapter output, assert the JSX output parses as valid TSX via `typescript.transpileModule`.
+
+## Skeleton template format
+
+A skeleton is a `.tsx.template` file — syntactically valid TypeScript with substitution markers. Example (sketch for `list.tsx.template`):
+
+```tsx
+/**
+ * {{MODEL_NAME}}ListView — generated by @specverse/realize (ReactAppStarter)
+ *
+ * Safe to edit. Edits are preserved across regeneration (content-hashed).
+ * Regenerate with `spv realize` or, if this file was edited, delete the
+ * file first to opt back into regeneration.
+ */
+import { useState, useMemo } from 'react';
+import { use{{PLURAL_MODEL}}Query, useDelete{{MODEL_NAME}}Mutation } from '../hooks/useApi';
+import type { {{MODEL_NAME}} } from '../types/api';
+
+interface {{MODEL_NAME}}ListViewProps {
+  onSelect?: (item: {{MODEL_NAME}}) => void;
+  onCreate?: () => void;
+}
+
+export function {{MODEL_NAME}}ListView({ onSelect, onCreate }: {{MODEL_NAME}}ListViewProps) {
+  const { data: items = [], isLoading, error } = use{{PLURAL_MODEL}}Query();
+  const deleteItem = useDelete{{MODEL_NAME}}Mutation();
+  const [searchTerm, setSearchTerm] = useState('');
+
+  const filtered = useMemo(
+    () => items.filter(item =>
+      Object.values(item).some(v => String(v).toLowerCase().includes(searchTerm.toLowerCase()))
+    ),
+    [items, searchTerm]
+  );
+
+  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>;
+
+  return (
+    <div className="p-6 space-y-4">
+      <div className="flex justify-between items-center">
+        <input
+          type="search"
+          placeholder="Search {{PLURAL_LOWER}}…"
+          value={searchTerm}
+          onChange={e => setSearchTerm(e.target.value)}
+          className="rounded border px-3 py-2 w-64"
+        />
+        <button
+          onClick={onCreate}
+          className="rounded bg-blue-600 px-4 py-2 text-white hover:bg-blue-700"
+        >
+          + New {{MODEL_NAME}}
+        </button>
+      </div>
+
+      {/* {{BODY}} — pattern-rendered table interior, JSX-transformed */}
+      {{BODY}}
+
+      {filtered.length === 0 && (
+        <div className="p-8 text-center text-gray-400">No {{PLURAL_LOWER}} yet.</div>
+      )}
+    </div>
+  );
+}
+```
+
+Substitution contract:
+- `{{MODEL_NAME}}` — PascalCase model name (e.g., `Post`).
+- `{{PLURAL_MODEL}}` — PascalCase plural (e.g., `Posts`).
+- `{{PLURAL_LOWER}}` — lowercase plural (e.g., `posts`).
+- `{{BODY}}` — exactly one substitution per skeleton, where the pattern-rendered interior goes.
+
+Substitution is plain string replacement — no template expression evaluation.
+
+## File placement
+
+```
+engines/libs/instance-factories/applications/templates/react-starter/
+├── README.md                        # this file
+├── view-emitter.ts                  # orchestrator (step 1)
+├── html-to-jsx.ts                   # transformer (step 3)
+├── skeletons/
+│   ├── list.tsx.template            # list view
+│   ├── detail.tsx.template          # detail view
+│   ├── form.tsx.template            # form view (Phase 2e)
+│   ├── dashboard.tsx.template       # dashboard (Phase 2e)
+│   └── specialist-*.tsx.template    # board/timeline/calendar (Phase 2e)
+└── __tests__/
+    ├── html-to-jsx.test.ts          # transformer unit tests
+    └── view-emitter.test.ts         # end-to-end: (spec, view) → valid TSX
+```
+
+## Build order (Phase 2a in the migration plan)
+
+1. Implement `html-to-jsx.ts` first (smallest, most testable, standalone).
+2. Write `list.tsx.template` (one view type; production-quality).
+3. Implement `view-emitter.ts` — orchestrator that wires html-to-jsx + canonical Tailwind adapter + skeleton.
+4. Integration test: take a reference spec with one model + its list view, emit, assert the `.tsx` source parses and its JSX matches the expected shape.
+5. Only after list works end-to-end: template out to detail + form + dashboard.
+
+## Open questions (inside Phase 2a)
+
+1. **Where do per-model hooks come from?** `use{{PLURAL_MODEL}}Query` and `useDelete{{MODEL_NAME}}Mutation` in the skeleton presume a generated hooks file (`src/hooks/useApi.ts`) that provides them. `ReactAppRuntime` already generates this file via `use-api-hooks-generator.ts` — Factory B should reuse that generator (shared between both factories as called out in the migration plan).
+2. **How does the skeleton address auto-generated fields (id, createdAt, etc.)?** The view should skip them in the table/form. `isAutoGeneratedField()` logic needs to be available in the generated output. Plan: emit a `src/lib/field-helpers.ts` alongside the views (inlined from the pattern library's logic, same way the runtime has it).
+3. **What happens when the view spec has `uiComponents` that the pattern library doesn't recognize?** Runtime gracefully falls back to a default table. Factory B should do the same — same fallback logic, same output.
+4. **Should the skeleton expose a slot for user-added React nodes (e.g. `<Children />` or a `prepend` prop)?** Useful for extensibility without forcing users to edit the generated file. Defer to v2 of the emitter — start with fixed skeletons.
+
+## Non-goals
+
+- No JSX AST parsing or manipulation. `html-to-jsx.ts` is a string transformer, not a compiler.
+- No server-side rendering of the React components. The emitter outputs source files; the user's Vite build bundles them.
+- No runtime customization of skeletons. A project that wants different skeletons forks the factory or the generated code.

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

@@ -0,0 +1,69 @@
+function mapAttrType(attr) {
+  const t = typeof attr === "string" ? attr.split(/\s+/)[0] : attr?.type;
+  const values = attr?.values;
+  if (Array.isArray(values) && values.length > 0) {
+    return values.map((v) => JSON.stringify(v)).join(" | ");
+  }
+  switch ((t || "").toLowerCase()) {
+    case "string":
+    case "text":
+    case "uuid":
+    case "email":
+    case "url":
+      return "string";
+    case "int":
+    case "integer":
+    case "float":
+    case "number":
+    case "decimal":
+      return "number";
+    case "boolean":
+    case "bool":
+      return "boolean";
+    case "datetime":
+    case "date":
+    case "time":
+    case "timestamp":
+      return "string";
+    case "json":
+      return "Record<string, unknown>";
+    default:
+      return "unknown";
+  }
+}
+function isRequired(attr) {
+  if (typeof attr === "string") return /\brequired\b/.test(attr);
+  return !!attr?.required;
+}
+async function generate(context) {
+  const models = context.spec.models ?? {};
+  const modelNames = Object.keys(models);
+  const header = `/**
+ * API types (ReactAppStarter)
+ *
+ * Per-model interfaces generated from the spec's model definitions.
+ * Safe to edit \u2014 extend these when your UI needs more than the spec
+ * describes (e.g. optimistic fields, denormalized joins).
+ */
+`;
+  const interfaces = modelNames.map((name) => {
+    const model = models[name] || {};
+    const attrs = model.attributes || {};
+    const attrKeys = Object.keys(attrs);
+    const fields = attrKeys.map((attrName) => {
+      const attr = attrs[attrName];
+      const tsType = mapAttrType(attr);
+      const optional = isRequired(attr) ? "" : "?";
+      return `  ${attrName}${optional}: ${tsType};`;
+    }).join("\n");
+    return `export interface ${name} {
+${fields || "  [key: string]: unknown;"}
+}`;
+  }).join("\n\n");
+  return header + "\n" + interfaces + "\n";
+}
+var stdin_default = generate;
+export {
+  stdin_default as default,
+  generate
+};

package/dist/libs/instance-factories/applications/templates/react-starter/app-tsx-generator.js

@@ -79,7 +79,7 @@ function buildNavEntries(models) {
             </div>
             <button type="button" onClick={() => select('${m}', 'list')} className="${navButtonCls("list")}">List</button>
             <button type="button" onClick={() => select('${m}', 'dashboard')} className="${navButtonCls("dashboard")}">Dashboard</button>
-            <button type="button" onClick={() => select('${m}', 'form')} className="${navButtonCls("form")}">New</button>
+            <button type="button" onClick={() => select('${m}', 'form')} className="${navButtonCls("form")}">Form</button>
           </div>`).join("\n");
 }
 function navButtonCls(_view) {

package/dist/libs/instance-factories/applications/templates/react-starter/belongs-to.js

@@ -0,0 +1,40 @@
+function extractBelongsToTargets(model) {
+  const rels = model.relationships ?? {};
+  const out = [];
+  for (const [name, rawDef] of Object.entries(rels)) {
+    const parsed = parseBelongsTo(rawDef);
+    if (parsed) out.push({ name, target: parsed });
+  }
+  return out;
+}
+function parseBelongsTo(def) {
+  if (typeof def === "string") {
+    const parts = def.trim().split(/\s+/);
+    if (parts[0] === "belongsTo" && parts[1]) return parts[1];
+    return null;
+  }
+  if (def && typeof def === "object") {
+    const o = def;
+    if (o.type === "belongsTo") {
+      return o.target || o.to || o.model || o.targetModel || null;
+    }
+  }
+  return null;
+}
+function pluralize(s) {
+  if (/[^aeiou]y$/i.test(s)) return s.slice(0, -1) + "ies";
+  if (/(s|x|z|ch|sh)$/i.test(s)) return s + "es";
+  return s + "s";
+}
+function buildFKMap(model) {
+  const map = /* @__PURE__ */ new Map();
+  for (const rel of extractBelongsToTargets(model)) {
+    map.set(`${rel.name}Id`, rel);
+  }
+  return map;
+}
+export {
+  buildFKMap,
+  extractBelongsToTargets,
+  pluralize
+};

package/dist/libs/instance-factories/applications/templates/react-starter/dashboard-body-composer.js

@@ -1,9 +1,11 @@
 import { METADATA_FIELDS } from "@specverse/runtime/views/core";
+import { buildFKMap } from "./belongs-to.js";
 const METADATA_FIELD_NAMES = new Set(METADATA_FIELDS);
 function composeDashboardBody(context) {
   const modelName = context.model.name;
   const previewColumns = inferPreviewColumns(context.model);
   const enumFields = inferEnumFields(context.model);
+  const fkMap = buildFKMap(context.model);
   const lines = [];
   lines.push('<div className="grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-4">');
   lines.push(...renderTotalCard(modelName));
@@ -32,8 +34,10 @@ function composeDashboardBody(context) {
     lines.push("    <thead>");
     lines.push("      <tr>");
     for (const col of previewColumns) {
+      const fk = fkMap.get(col);
+      const headerLabel = humanize(fk ? fk.name : col);
       lines.push(
-        `        <th className="px-6 py-3 text-left text-xs font-medium text-gray-500 dark:text-gray-400 uppercase tracking-wider">` + humanize(col) + `</th>`
+        `        <th className="px-6 py-3 text-left text-xs font-medium text-gray-500 dark:text-gray-400 uppercase tracking-wider">` + headerLabel + `</th>`
       );
     }
     lines.push("      </tr>");
@@ -46,8 +50,10 @@ function composeDashboardBody(context) {
     lines.push('          className="hover:bg-gray-50 dark:hover:bg-gray-800 cursor-pointer"');
     lines.push("        >");
     for (const col of previewColumns) {
+      const fk = fkMap.get(col);
+      const expr = fk ? `{resolveEntityDisplayName((item as any).${col}, ${fk.name}Options)}` : `{String((item as any).${col} ?? '')}`;
       lines.push(
-        `          <td className="px-6 py-4 text-sm text-gray-700 dark:text-gray-300">{String((item as any).${col} ?? '')}</td>`
+        `          <td className="px-6 py-4 text-sm text-gray-700 dark:text-gray-300">${expr}</td>`
       );
     }
     lines.push("        </tr>");
@@ -111,7 +117,9 @@ function inferEnumFields(model) {
 }
 function inferPreviewColumns(model) {
   const attrs = model.attributes ?? {};
-  return Object.keys(attrs).filter((n) => !METADATA_FIELD_NAMES.has(n)).slice(0, 4);
+  const attrCols = Object.keys(attrs).filter((n) => !METADATA_FIELD_NAMES.has(n));
+  const fkCols = [...buildFKMap(model).keys()].filter((k) => !attrCols.includes(k));
+  return [...fkCols, ...attrCols].slice(0, Math.max(5, fkCols.length + 1));
 }
 function humanize(name) {
   return name.replace(/([A-Z])/g, " $1").replace(/^./, (c) => c.toUpperCase()).trim();