@specverse/engines 4.1.28 → 4.2.0

package/libs/instance-factories/applications/templates/react-starter/__tests__/starter-generators.test.ts

@@ -0,0 +1,114 @@
+import { describe, it, expect } from 'vitest';
+import * as ts from 'typescript';
+import { generate as generateAppTsx } from '../app-tsx-generator.js';
+import { generate as generatePackageJson } from '../package-json-generator.js';
+
+function assertValidTsx(source: string, label: string): void {
+  const result = ts.transpileModule(source, {
+    compilerOptions: {
+      jsx: ts.JsxEmit.Preserve,
+      target: ts.ScriptTarget.ES2022,
+      module: ts.ModuleKind.ESNext,
+      moduleResolution: ts.ModuleResolutionKind.Bundler,
+      strict: false,
+    },
+    reportDiagnostics: true,
+  });
+  const errors = result.diagnostics?.filter(d => d.category === ts.DiagnosticCategory.Error) ?? [];
+  if (errors.length > 0) {
+    const message = errors
+      .map(d => ts.flattenDiagnosticMessageText(d.messageText, '\n'))
+      .join('\n');
+    throw new Error(`${label} failed to parse:\n${message}\n\n--- source ---\n${source}`);
+  }
+}
+
+describe('app-tsx-generator', () => {
+  it('produces valid TSX with one branch per model and view type', async () => {
+    const source = await generateAppTsx({
+      spec: {
+        models: {
+          Post: { name: 'Post', attributes: {} },
+          Author: { name: 'Author', attributes: {} },
+        },
+      },
+    });
+    assertValidTsx(source, 'App.tsx');
+    // One nav section per model
+    expect(source).toContain('Post');
+    expect(source).toContain('Author');
+    // One import per (model, view) pair — 2 models × 4 view types = 8 imports
+    const importLines = source.match(/^import \{ \w+View \} from '\.\/views\//gm) ?? [];
+    expect(importLines.length).toBe(8);
+    // Navigation wiring
+    expect(source).toContain("select('Post', 'list')");
+    expect(source).toContain("select('Author', 'dashboard')");
+  });
+
+  it('handles an empty spec gracefully', async () => {
+    const source = await generateAppTsx({ spec: { models: {}, views: {} } });
+    assertValidTsx(source, 'App.tsx (empty spec)');
+    expect(source).toContain('No models in this spec.');
+    // Still renders a QueryClientProvider
+    expect(source).toContain('QueryClientProvider');
+  });
+
+  it('uses @tanstack/react-query, not @specverse/runtime', async () => {
+    const source = await generateAppTsx({
+      spec: { models: { Post: { name: 'Post', attributes: {} } } },
+    });
+    expect(source).not.toContain('@specverse/runtime');
+    expect(source).toContain('@tanstack/react-query');
+  });
+});
+
+describe('package-json-generator', () => {
+  it('omits @specverse/runtime from dependencies', async () => {
+    const json = await generatePackageJson({ spec: { name: 'test' } });
+    const pkg = JSON.parse(json);
+    const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+    expect(allDeps['@specverse/runtime']).toBeUndefined();
+    expect(allDeps['@specverse/engines']).toBeUndefined();
+    expect(allDeps['@specverse/types']).toBeUndefined();
+  });
+
+  it('includes the deps the emitted views actually need', async () => {
+    const json = await generatePackageJson({ spec: { name: 'test' } });
+    const pkg = JSON.parse(json);
+    expect(pkg.dependencies).toMatchObject({
+      react: expect.any(String),
+      'react-dom': expect.any(String),
+      '@tanstack/react-query': expect.any(String),
+    });
+    expect(pkg.devDependencies).toMatchObject({
+      typescript: expect.any(String),
+      vite: expect.any(String),
+      tailwindcss: expect.any(String),
+    });
+  });
+
+  it('slugifies the app name', async () => {
+    const json = await generatePackageJson({
+      spec: { metadata: { name: 'My Fancy App!' } },
+    });
+    const pkg = JSON.parse(json);
+    expect(pkg.name).toBe('my-fancy-app');
+  });
+
+  it('falls back to a default name when none is provided', async () => {
+    const json = await generatePackageJson({ spec: {} });
+    const pkg = JSON.parse(json);
+    expect(pkg.name).toBe('specverse-starter-app');
+  });
+
+  it('parses as valid JSON with the expected shape', async () => {
+    const json = await generatePackageJson({ spec: { name: 'test' } });
+    const pkg = JSON.parse(json);
+    expect(pkg.type).toBe('module');
+    expect(pkg.scripts).toMatchObject({
+      dev: 'vite',
+      build: 'tsc && vite build',
+      preview: 'vite preview',
+    });
+  });
+});

package/libs/instance-factories/applications/templates/react-starter/__tests__/view-emitter.test.ts

@@ -0,0 +1,107 @@
+import { describe, it, expect } from 'vitest';
+import * as ts from 'typescript';
+import { emitView, type EmitContext, type ModelSpec, type ViewSpec } from '../view-emitter.js';
+
+/**
+ * Build a minimal context. The `renderBody` is a stub that returns a
+ * fixed Tailwind table — the point of these tests is the emitter
+ * orchestration + substitutions + JSX validity, not the body's content.
+ * Parity with the real Tailwind adapter is covered by Phase 3 (P3).
+ */
+function makeContext(overrides: Partial<EmitContext> = {}): EmitContext {
+  const defaultModel: ModelSpec = {
+    name: 'Post',
+    attributes: {
+      id: { type: 'UUID', required: true },
+      title: { type: 'String', required: true },
+      body: { type: 'Text', required: false },
+    },
+  };
+
+  const defaultView: ViewSpec = {
+    type: 'list',
+    model: 'Post',
+  };
+
+  return {
+    view: defaultView,
+    viewName: 'PostListView',
+    model: defaultModel,
+    modelSchemas: { Post: defaultModel },
+    // renderBody returns JSX-ready source that will be injected verbatim
+    // into {{BODY}}. NOT raw HTML — that's the composer's job.
+    renderBody: () =>
+      '<table className="w-full"><thead><tr><th className="px-4 py-2">Title</th></tr></thead>' +
+      '<tbody><tr><td className="px-4 py-2">Example</td></tr></tbody></table>',
+    ...overrides,
+  };
+}
+
+function assertValidTsx(source: string, label: string): void {
+  const result = ts.transpileModule(source, {
+    compilerOptions: {
+      jsx: ts.JsxEmit.Preserve,
+      target: ts.ScriptTarget.ES2022,
+      module: ts.ModuleKind.ESNext,
+      moduleResolution: ts.ModuleResolutionKind.Bundler,
+      strict: false,
+    },
+    reportDiagnostics: true,
+  });
+  const errors = result.diagnostics?.filter(d => d.category === ts.DiagnosticCategory.Error) ?? [];
+  if (errors.length > 0) {
+    const message = errors
+      .map(d => ts.flattenDiagnosticMessageText(d.messageText, '\n'))
+      .join('\n');
+    throw new Error(`${label} failed to parse as TSX:\n${message}\n\n--- source ---\n${source}`);
+  }
+}
+
+describe('emitView — list', () => {
+  it('produces TSX that parses cleanly', () => {
+    const context = makeContext();
+    const source = emitView(context);
+    assertValidTsx(source, 'emitted list view');
+  });
+
+  it('substitutes model names into the skeleton', () => {
+    const source = emitView(makeContext());
+    expect(source).toContain('PostListView');                  // component name
+    expect(source).toContain('usePostsQuery');                 // generated hook name
+    expect(source).toContain('useDeletePostMutation');         // generated hook name
+    expect(source).toContain("Search posts…");                 // pluralized lowercase
+    expect(source).toContain('+ New Post');                    // action button label
+    expect(source).toContain('No posts yet.');                 // empty state
+  });
+
+  it('substitutes a non-trivial plural correctly', () => {
+    const m: ModelSpec = { name: 'Category', attributes: {} };
+    const source = emitView(makeContext({
+      model: m,
+      view: { type: 'list', model: 'Category' },
+      viewName: 'CategoryListView',
+      modelSchemas: { Category: m },
+    }));
+    expect(source).toContain('CategoryListView');
+    expect(source).toContain('useCategoriesQuery');     // "Category" → "Categories"
+    expect(source).toContain('Search categories…');
+  });
+
+  it('injects the rendered body at {{BODY}}', () => {
+    const source = emitView(makeContext({
+      renderBody: () => '<table className="my-table"><tbody><tr><td>Custom</td></tr></tbody></table>',
+    }));
+    expect(source).toContain('<table className="my-table">');
+    expect(source).toContain('Custom');
+    // The placeholder itself should be gone.
+    expect(source).not.toContain('{{BODY}}');
+    // All other placeholders should be gone too.
+    expect(source).not.toMatch(/\{\{[A-Z_]+\}\}/);
+  });
+
+  it('throws for an unknown view type', () => {
+    expect(() =>
+      emitView(makeContext({ view: { type: 'unknown-type-xyz' } }))
+    ).toThrow(/No skeleton registered/);
+  });
+});

package/libs/instance-factories/applications/templates/react-starter/__tests__/views-generator.test.ts

@@ -0,0 +1,139 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import * as ts from 'typescript';
+import { generate, type ExpandedSpec } from '../views-generator.js';
+
+function makeSpec(): ExpandedSpec {
+  return {
+    models: {
+      Post: {
+        name: 'Post',
+        attributes: {
+          id: { type: 'UUID', required: true, auto: 'uuid4' },
+          title: { type: 'String', required: true },
+          body: { type: 'Text', required: false },
+        },
+      },
+      Author: {
+        name: 'Author',
+        attributes: {
+          id: { type: 'UUID', required: true, auto: 'uuid4' },
+          name: { type: 'String', required: true },
+        },
+      },
+    },
+    views: {},
+  };
+}
+
+function assertValidTsx(source: string, label: string): void {
+  const result = ts.transpileModule(source, {
+    compilerOptions: {
+      jsx: ts.JsxEmit.Preserve,
+      target: ts.ScriptTarget.ES2022,
+      module: ts.ModuleKind.ESNext,
+      moduleResolution: ts.ModuleResolutionKind.Bundler,
+      strict: false,
+    },
+    reportDiagnostics: true,
+  });
+  const errors = result.diagnostics?.filter(d => d.category === ts.DiagnosticCategory.Error) ?? [];
+  if (errors.length > 0) {
+    const message = errors
+      .map(d => ts.flattenDiagnosticMessageText(d.messageText, '\n'))
+      .join('\n');
+    throw new Error(`${label} failed to parse as TSX:\n${message}\n\n--- source ---\n${source}`);
+  }
+}
+
+describe('views-generator.generate', () => {
+  it('emits 4 view files per model plus the helpers file', async () => {
+    const files = await generate({ spec: makeSpec() });
+    const paths = Object.keys(files);
+    expect(paths).toContain('src/views/PostListView.tsx');
+    expect(paths).toContain('src/views/PostDetailView.tsx');
+    expect(paths).toContain('src/views/PostFormView.tsx');
+    expect(paths).toContain('src/views/PostDashboardView.tsx');
+    expect(paths).toContain('src/views/AuthorListView.tsx');
+    expect(paths).toContain('src/views/AuthorDetailView.tsx');
+    expect(paths).toContain('src/views/AuthorFormView.tsx');
+    expect(paths).toContain('src/views/AuthorDashboardView.tsx');
+    expect(paths).toContain('src/lib/entity-display.ts');
+    // 2 models × 4 view types + 1 helper = 9 files.
+    expect(paths.length).toBe(9);
+  });
+
+  it('every emitted view file parses as valid TSX', async () => {
+    const files = await generate({ spec: makeSpec() });
+    for (const [path, source] of Object.entries(files)) {
+      if (path.endsWith('.tsx')) assertValidTsx(source, path);
+    }
+  });
+
+  it('uses a user-declared view spec in preference to a synthesized default', async () => {
+    const spec: ExpandedSpec = {
+      models: {
+        Post: {
+          name: 'Post',
+          attributes: {
+            id: { type: 'UUID', auto: 'uuid4' },
+            title: { type: 'String', required: true },
+          },
+        },
+      },
+      views: {
+        PostListView: {
+          type: 'list',
+          model: 'Post',
+          uiComponents: {
+            customTable: {
+              type: 'table',
+              properties: {
+                columns: ['SUPER CUSTOM COLUMN'],
+              },
+            },
+          },
+        },
+      },
+    };
+    const files = await generate({ spec });
+    const out = files['src/views/PostListView.tsx'];
+    // The user's custom column header is not directly visible because
+    // the current composer ignores user uiComponents (it infers
+    // columns from the model). But the view spec flows through — if
+    // we later teach the composer to honour uiComponents, this test
+    // anchors the contract.
+    expect(out).toBeDefined();
+    expect(out).toContain('export function PostListView');
+  });
+
+  it('warns on specialist view types and skips them', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    try {
+      const spec: ExpandedSpec = {
+        models: {
+          Post: { name: 'Post', attributes: { id: { auto: 'uuid4' }, title: {} } },
+        },
+        views: {
+          PostBoardView: { type: 'board', model: 'Post' },
+          PostTimelineView: { type: 'timeline', model: 'Post' },
+        },
+      };
+      const files = await generate({ spec });
+      expect(files['src/views/PostBoardView.tsx']).toBeUndefined();
+      expect(files['src/views/PostTimelineView.tsx']).toBeUndefined();
+      expect(warn).toHaveBeenCalled();
+      const warning = warn.mock.calls[0][0] as string;
+      expect(warning).toContain('Skipped');
+      expect(warning).toContain('board');
+      expect(warning).toContain('timeline');
+    } finally {
+      warn.mockRestore();
+    }
+  });
+
+  it('handles an empty models map gracefully', async () => {
+    const files = await generate({ spec: { models: {}, views: {} } });
+    // Only the helpers file is emitted; no view files.
+    expect(Object.keys(files)).toEqual(['src/lib/entity-display.ts']);
+  });
+});

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

@@ -0,0 +1,141 @@
+/**
+ * App.tsx generator for ReactAppStarter
+ *
+ * Generates a simple App shell that routes between the emitted view
+ * components. Not using react-router — the starter output is
+ * deliberately low-magic. Users can add routing when they need
+ * URL-level view selection; for now, internal state drives it.
+ *
+ * Output:
+ *  - sidebar nav listing every (model × view-type)
+ *  - a main area rendering the selected view
+ *  - QueryClientProvider at the root
+ */
+
+import type { ExpandedSpec } from './views-generator.js';
+
+export interface AppGeneratorContext {
+  spec: ExpandedSpec;
+  manifest?: unknown;
+}
+
+export async function generate(context: AppGeneratorContext): Promise<string> {
+  const models = Object.keys(context.spec.models ?? {});
+  const imports = buildImports(models);
+  const navEntries = buildNavEntries(models);
+  const viewSwitch = buildViewSwitch(models);
+
+  return `/**
+ * App.tsx — generated by @specverse/realize (ReactAppStarter)
+ *
+ * Safe to edit. Edits are preserved across regeneration via content
+ * hashing. This is a minimal shell: a sidebar listing every
+ * (model, view-type) plus a main area that renders the selection.
+ * Swap in react-router or your preferred routing library when the
+ * app needs URL-driven navigation.
+ */
+import { useState } from 'react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+${imports}
+
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: { staleTime: 5 * 60 * 1000, retry: 1 },
+  },
+});
+
+type Selection = {
+  model: string;
+  view: 'list' | 'detail' | 'form' | 'dashboard';
+  entityId?: string | number;
+};
+
+function Inner() {
+  const [selection, setSelection] = useState<Selection>(${models.length > 0 ? `{ model: '${models[0]}', view: 'list' }` : `{ model: '', view: 'list' }`});
+
+  const select = (model: string, view: Selection['view']) =>
+    setSelection({ model, view });
+
+  return (
+    <div className="min-h-screen flex bg-gray-50 dark:bg-gray-950">
+      <aside className="w-64 shrink-0 border-r border-gray-200 dark:border-gray-800 bg-white dark:bg-gray-900">
+        <div className="p-4 border-b border-gray-200 dark:border-gray-800">
+          <h1 className="text-lg font-semibold text-gray-900 dark:text-gray-100">App</h1>
+        </div>
+        <nav className="p-2 space-y-4">
+${navEntries}
+        </nav>
+      </aside>
+
+      <main className="flex-1 overflow-auto">
+${viewSwitch}
+      </main>
+    </div>
+  );
+}
+
+export default function App() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <Inner />
+    </QueryClientProvider>
+  );
+}
+`;
+}
+
+// ──────────────────────────────────────────────────────────────────────
+// Helpers
+// ──────────────────────────────────────────────────────────────────────
+
+function buildImports(models: string[]): string {
+  return models.flatMap(m => [
+    `import { ${m}ListView } from './views/${m}ListView';`,
+    `import { ${m}DetailView } from './views/${m}DetailView';`,
+    `import { ${m}FormView } from './views/${m}FormView';`,
+    `import { ${m}DashboardView } from './views/${m}DashboardView';`,
+  ]).join('\n');
+}
+
+function buildNavEntries(models: string[]): string {
+  if (models.length === 0) {
+    return '          <p className="text-sm text-gray-400 px-2">No models in this spec.</p>';
+  }
+  return models.map(m => `          <div>
+            <div className="px-2 pb-1 text-xs font-semibold uppercase tracking-wider text-gray-500 dark:text-gray-400">
+              ${m}
+            </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>
+          </div>`).join('\n');
+}
+
+function navButtonCls(_view: string): string {
+  return (
+    'block w-full text-left rounded px-2 py-1 text-sm ' +
+    'text-gray-700 hover:bg-gray-100 ' +
+    'dark:text-gray-300 dark:hover:bg-gray-800'
+  );
+}
+
+function buildViewSwitch(models: string[]): string {
+  if (models.length === 0) {
+    return '        <p className="p-6 text-sm text-gray-400">No models — add one to your .specly file and run <code>spv realize</code>.</p>';
+  }
+  const branches = models.flatMap(m => [
+    `        {selection.model === '${m}' && selection.view === 'list' && (
+          <${m}ListView onSelect={item => setSelection({ model: '${m}', view: 'detail', entityId: (item as any).id })} onCreate={() => setSelection({ model: '${m}', view: 'form' })} />
+        )}`,
+    `        {selection.model === '${m}' && selection.view === 'detail' && selection.entityId !== undefined && (
+          <${m}DetailView entityId={selection.entityId} onEdit={item => setSelection({ model: '${m}', view: 'form', entityId: (item as any).id })} onBack={() => setSelection({ model: '${m}', view: 'list' })} onDeleted={() => setSelection({ model: '${m}', view: 'list' })} />
+        )}`,
+    `        {selection.model === '${m}' && selection.view === 'form' && (
+          <${m}FormView mode={selection.entityId ? 'update' : 'create'} entityId={selection.entityId} onSuccess={() => setSelection({ model: '${m}', view: 'list' })} onCancel={() => setSelection({ model: '${m}', view: 'list' })} />
+        )}`,
+    `        {selection.model === '${m}' && selection.view === 'dashboard' && (
+          <${m}DashboardView onSelect={item => setSelection({ model: '${m}', view: 'detail', entityId: (item as any).id })} />
+        )}`,
+  ]);
+  return branches.join('\n');
+}

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

@@ -0,0 +1,174 @@
+/**
+ * Dashboard-view body composer for ReactAppStarter
+ *
+ * Minimal starter-kit dashboard: metric cards derived from the list
+ * query (total count; enum-field breakdowns if the model has a status-
+ * like attribute), plus a compact preview of recent records.
+ *
+ * Aggregation / charts are deferred — they need backend endpoints
+ * (`/api/posts/metrics`, `/api/posts/by-month`, …) that the starter
+ * kit doesn't assume. TODO comments flag the extension points.
+ */
+
+import { METADATA_FIELDS } from '@specverse/runtime/views/core';
+import type { EmitContext, ModelSpec } from './view-emitter.js';
+
+const METADATA_FIELD_NAMES = new Set(METADATA_FIELDS);
+
+export function composeDashboardBody(context: EmitContext): string {
+  const modelName = context.model.name;
+  const previewColumns = inferPreviewColumns(context.model);
+  const enumFields = inferEnumFields(context.model);
+
+  const lines: string[] = [];
+
+  // ── Metrics row ────────────────────────────────────────────────────
+  lines.push('<div className="grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-4">');
+  lines.push(...renderTotalCard(modelName));
+  for (const enumField of enumFields) {
+    lines.push(...renderEnumBreakdownCard(enumField));
+  }
+  if (enumFields.length === 0) {
+    lines.push(...renderPlaceholderCard());
+  }
+  lines.push('</div>');
+
+  // ── TODO: aggregation metrics ──────────────────────────────────────
+  lines.push('');
+  lines.push('{/* TODO: add aggregation metrics (averages / sums / time series)');
+  lines.push('    by adding backend endpoints and per-metric hooks. Wire them in');
+  lines.push('    alongside the count cards above. */}');
+
+  // ── Recent-items preview ───────────────────────────────────────────
+  lines.push('');
+  lines.push('<div className="rounded-lg border border-gray-200 bg-white dark:border-gray-700 dark:bg-gray-900">');
+  lines.push('  <div className="border-b border-gray-200 dark:border-gray-700 px-6 py-3">');
+  lines.push('    <h3 className="text-sm font-semibold text-gray-700 dark:text-gray-200 uppercase tracking-wider">');
+  lines.push(`      Recent ${humanize(modelName)}s`);
+  lines.push('    </h3>');
+  lines.push('  </div>');
+
+  if (previewColumns.length === 0) {
+    lines.push('  <div className="px-6 py-4 text-sm text-gray-400">No displayable fields.</div>');
+  } else {
+    lines.push('  <table className="min-w-full divide-y divide-gray-200 dark:divide-gray-700">');
+    lines.push('    <thead>');
+    lines.push('      <tr>');
+    for (const col of previewColumns) {
+      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>`
+      );
+    }
+    lines.push('      </tr>');
+    lines.push('    </thead>');
+    lines.push('    <tbody className="divide-y divide-gray-200 dark:divide-gray-700">');
+    lines.push('      {preview.map((item, idx) => (');
+    lines.push('        <tr');
+    lines.push('          key={idx}');
+    lines.push('          onClick={() => onSelect?.(item)}');
+    lines.push('          className="hover:bg-gray-50 dark:hover:bg-gray-800 cursor-pointer"');
+    lines.push('        >');
+    for (const col of previewColumns) {
+      lines.push(
+        `          <td className="px-6 py-4 text-sm text-gray-700 dark:text-gray-300">` +
+        `{String((item as any).${col} ?? '')}</td>`
+      );
+    }
+    lines.push('        </tr>');
+    lines.push('      ))}');
+    lines.push('      {preview.length === 0 && (');
+    lines.push(`        <tr><td colSpan={${previewColumns.length}} className="px-6 py-4 text-sm text-gray-400">No records yet.</td></tr>`);
+    lines.push('      )}');
+    lines.push('    </tbody>');
+    lines.push('  </table>');
+  }
+  lines.push('</div>');
+
+  return lines.join('\n');
+}
+
+// ──────────────────────────────────────────────────────────────────────
+// Card rendering
+// ──────────────────────────────────────────────────────────────────────
+
+function renderTotalCard(modelName: string): string[] {
+  const pluralLower = humanize(modelName).toLowerCase() + 's';
+  return [
+    '  <div className="rounded-lg border border-gray-200 bg-white p-6 shadow-sm dark:border-gray-700 dark:bg-gray-900">',
+    '    <p className="text-xs font-medium uppercase tracking-wide text-gray-500 dark:text-gray-400">',
+    `      Total ${pluralLower}`,
+    '    </p>',
+    '    <p className="mt-2 text-3xl font-semibold text-gray-900 dark:text-gray-100">',
+    '      {items.length}',
+    '    </p>',
+    '  </div>',
+  ];
+}
+
+function renderEnumBreakdownCard(field: EnumField): string[] {
+  // One card per enum value — shows count of records where the field
+  // equals that value.
+  const cards: string[] = [];
+  for (const value of field.values) {
+    cards.push(
+      '  <div className="rounded-lg border border-gray-200 bg-white p-6 shadow-sm dark:border-gray-700 dark:bg-gray-900">',
+      '    <p className="text-xs font-medium uppercase tracking-wide text-gray-500 dark:text-gray-400">',
+      `      ${humanize(field.name)}: ${humanize(value)}`,
+      '    </p>',
+      '    <p className="mt-2 text-3xl font-semibold text-gray-900 dark:text-gray-100">',
+      `      {items.filter((i: any) => i.${field.name} === ${JSON.stringify(value)}).length}`,
+      '    </p>',
+      '  </div>',
+    );
+  }
+  return cards;
+}
+
+function renderPlaceholderCard(): string[] {
+  return [
+    '  <div className="rounded-lg border border-dashed border-gray-300 p-6 text-sm text-gray-400 dark:border-gray-600">',
+    '    Add a metric here — e.g. a sum, average, or time-windowed count.',
+    '  </div>',
+  ];
+}
+
+// ──────────────────────────────────────────────────────────────────────
+// Field inference
+// ──────────────────────────────────────────────────────────────────────
+
+interface EnumField {
+  name: string;
+  values: string[];
+}
+
+function inferEnumFields(model: ModelSpec): EnumField[] {
+  const out: EnumField[] = [];
+  const attrs = model.attributes ?? {};
+  for (const [name, rawDef] of Object.entries(attrs)) {
+    const def = rawDef as { values?: string[] };
+    const values = def?.values;
+    if (Array.isArray(values) && values.length > 0 && values.length <= 6) {
+      out.push({ name, values });
+    }
+  }
+  // Cap: one enum breakdown in the card row to avoid card sprawl. The
+  // remaining enum fields stay available in the list view; users can
+  // promote more breakdowns manually.
+  return out.slice(0, 1);
+}
+
+function inferPreviewColumns(model: ModelSpec): string[] {
+  const attrs = model.attributes ?? {};
+  return Object.keys(attrs)
+    .filter(n => !METADATA_FIELD_NAMES.has(n))
+    .slice(0, 4);   // cap to keep the table readable
+}
+
+function humanize(name: string): string {
+  return name
+    .replace(/([A-Z])/g, ' $1')
+    .replace(/^./, c => c.toUpperCase())
+    .trim();
+}