@specverse/engines 4.2.2 → 4.3.0

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

@@ -1,189 +1,22 @@
 /**
- * Dashboard-view body composer for ReactAppStarter
+ * Dashboard-view body composer for ReactAppStarter (Phase 3)
  *
- * 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.
+ * Thin wrapper around walkPattern('dashboard-view'). The pattern
+ * registry + section resolvers (metric-cards, charts-placeholder,
+ * recent-items) decide what a dashboard view looks like; this
+ * composer just emits the resulting tree to JSX source.
  */
 
-import { METADATA_FIELDS } from '@specverse/runtime/views/core';
-import type { EmitContext, ModelSpec } from './view-emitter.js';
-import { buildFKMap } from './belongs-to.js';
-
-const METADATA_FIELD_NAMES = new Set(METADATA_FIELDS);
+import { walkPattern } from '@specverse/runtime/views/core';
+import type { EmitContext } from './view-emitter.js';
+import { emitJsxSource } from './emit-jsx-source.js';
 
 export function composeDashboardBody(context: EmitContext): string {
-  const modelName = context.model.name;
-  const previewColumns = inferPreviewColumns(context.model);
-  const enumFields = inferEnumFields(context.model);
-  const fkMap = buildFKMap(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) {
-      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">` +
-        headerLabel +
-        `</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) {
-      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">` +
-        `${expr}</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 ?? {};
-  const attrCols = Object.keys(attrs).filter(n => !METADATA_FIELD_NAMES.has(n));
-
-  // Include belongsTo FK columns so the preview shows "who does this
-  // belong to" at a glance. Matches the list-view convention.
-  const fkCols = [...buildFKMap(model).keys()].filter(k => !attrCols.includes(k));
-
-  // FKs are always useful at-a-glance, so keep them all. Cap the
-  // combined set at 5 to keep the preview table readable without
-  // crowding out the "who" columns.
-  return [...fkCols, ...attrCols].slice(0, Math.max(5, fkCols.length + 1));
-}
-
-function humanize(name: string): string {
-  return name
-    .replace(/([A-Z])/g, ' $1')
-    .replace(/^./, c => c.toUpperCase())
-    .trim();
+  const imports = new Set<string>();
+  const nodes = walkPattern('dashboard-view', {
+    model: context.model,
+    modelSchemas: context.modelSchemas as any,
+    view: context.view,
+  });
+  return emitJsxSource(nodes, { imports, indent: 6 });
 }

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

@@ -1,135 +1,23 @@
 /**
- * Detail-view body composer for ReactAppStarter
+ * Detail-view body composer for ReactAppStarter (Phase 3)
  *
- * Renders the interior of a detail view as a JSX-safe definition list:
- * business fields first (prominent), belongsTo relationships resolved
- * to display names in a dedicated section, metadata fields last (muted).
- * The outer card + actions live in `skeletons/detail.tsx.template`.
- *
- * belongsTo FK columns are resolved via `resolveEntityDisplayName`
- * using option arrays (${relName}Options) wired in by view-emitter's
- * RELATED_HOOKS substitution.
+ * Thin wrapper around walkPattern('detail-view'). Section meanings
+ * (header / main / related-lists) and the rendering of each section
+ * live in the runtime pattern registry + section resolvers
+ * (field-list, related-tables); this composer just emits the
+ * resulting tree to JSX source.
  */
 
-import { METADATA_FIELDS } from '@specverse/runtime/views/core';
-import type { EmitContext, ModelSpec } from './view-emitter.js';
-import { extractBelongsToTargets, type BelongsToRel } from './belongs-to.js';
-
-/**
- * Metadata attribute names rendered in a muted style. Sourced from
- * the canonical pattern library so both this composer and the rest
- * of the system stay in sync automatically.
- */
-const METADATA_FIELD_NAMES = new Set(METADATA_FIELDS);
+import { walkPattern } from '@specverse/runtime/views/core';
+import type { EmitContext } from './view-emitter.js';
+import { emitJsxSource } from './emit-jsx-source.js';
 
 export function composeDetailBody(context: EmitContext): string {
-  // FK columns are excluded from business so we don't emit the raw
-  // UUID next to the resolved name. They surface in the belongsTo
-  // section instead, rendered via resolveEntityDisplayName.
-  const belongsTo = extractBelongsToTargets(context.model);
-  const fkExcludes = new Set(belongsTo.map(r => `${r.name}Id`));
-  const { business, metadata } = partitionFields(context.model, fkExcludes);
-
-  const lines: string[] = [];
-  lines.push('<div className="rounded-lg border border-gray-200 bg-white p-6 dark:border-gray-700 dark:bg-gray-900">');
-
-  if (business.length > 0) {
-    lines.push('  <dl className="grid grid-cols-1 gap-4 sm:grid-cols-2">');
-    for (const field of business) {
-      lines.push(...renderField(field, { muted: false }));
-    }
-    lines.push('  </dl>');
-  } else if (belongsTo.length === 0) {
-    lines.push('  <p className="text-sm text-gray-400">No business fields defined for this model.</p>');
-  }
-
-  if (belongsTo.length > 0) {
-    lines.push('');
-    lines.push('  <dl className="mt-6 grid grid-cols-1 gap-4 sm:grid-cols-2 border-t border-gray-200 dark:border-gray-700 pt-4">');
-    for (const rel of belongsTo) {
-      lines.push(...renderRelationshipField(rel));
-    }
-    lines.push('  </dl>');
-  }
-
-  if (metadata.length > 0) {
-    lines.push('');
-    lines.push('  <dl className="mt-6 grid grid-cols-1 gap-2 sm:grid-cols-2 border-t border-gray-200 dark:border-gray-700 pt-4 text-xs text-gray-500 dark:text-gray-400">');
-    for (const field of metadata) {
-      lines.push(...renderField(field, { muted: true }));
-    }
-    lines.push('  </dl>');
-  }
-
-  lines.push('</div>');
-  return lines.join('\n');
-}
-
-interface Field {
-  name: string;
-  /** Display label; defaults to humanize(name). */
-  label?: string;
-}
-
-function partitionFields(
-  model: ModelSpec,
-  exclude: Set<string> = new Set(),
-): { business: Field[]; metadata: Field[] } {
-  const attrs = Object.keys(model.attributes ?? {});
-  const business: Field[] = [];
-  const metadata: Field[] = [];
-  for (const name of attrs) {
-    if (exclude.has(name)) continue;
-    const field = { name, label: humanize(name) };
-    if (METADATA_FIELD_NAMES.has(name)) {
-      metadata.push(field);
-    } else {
-      business.push(field);
-    }
-  }
-  return { business, metadata };
-}
-
-/**
- * Render a belongsTo row as a label + resolved display name. The
- * options array (${relName}Options) is populated by the hook call
- * wired into the detail skeleton via view-emitter's RELATED_HOOKS.
- */
-function renderRelationshipField(rel: BelongsToRel): string[] {
-  const label = humanize(rel.name);
-  const fkName = `${rel.name}Id`;
-  const optionsVar = `${rel.name}Options`;
-  return [
-    '    <div>',
-    `      <dt className="text-sm font-medium text-gray-500 dark:text-gray-400">${label}</dt>`,
-    `      <dd className="mt-1 text-sm text-gray-900 dark:text-gray-100 break-words">` +
-      `{resolveEntityDisplayName((item as any).${fkName}, ${optionsVar})}</dd>`,
-    '    </div>',
-  ];
-}
-
-function renderField(field: Field, opts: { muted: boolean }): string[] {
-  const label = field.label ?? humanize(field.name);
-  const labelCls = opts.muted
-    ? 'font-medium uppercase tracking-wide text-gray-400 dark:text-gray-500'
-    : 'text-sm font-medium text-gray-500 dark:text-gray-400';
-  const valueCls = opts.muted
-    ? 'text-gray-500 dark:text-gray-400'
-    : 'mt-1 text-sm text-gray-900 dark:text-gray-100 break-words';
-
-  return [
-    '    <div>',
-    `      <dt className="${labelCls}">${label}</dt>`,
-    `      <dd className="${valueCls}">` +
-      `{String((item as any).${field.name} ?? '')}` +
-    '</dd>',
-    '    </div>',
-  ];
-}
-
-function humanize(name: string): string {
-  return name
-    .replace(/([A-Z])/g, ' $1')
-    .replace(/^./, c => c.toUpperCase())
-    .trim();
+  const imports = new Set<string>();
+  const nodes = walkPattern('detail-view', {
+    model: context.model,
+    modelSchemas: context.modelSchemas as any,
+    view: context.view,
+  });
+  return emitJsxSource(nodes, { imports, indent: 6 });
 }

package/libs/instance-factories/applications/templates/react-starter/emit-jsx-source.ts

@@ -0,0 +1,233 @@
+/**
+ * JSX-source emitter for Factory B
+ *
+ * Consumes the pattern-walker's RenderNode tree and produces JSX
+ * text that can be written into a .tsx file. Pluggable into
+ * Factory B's per-model per-view emission; the composers are being
+ * migrated one view type at a time to use this path.
+ *
+ * Emitter is deliberately minimal:
+ * - Atomic nodes whose component is a lowercase HTML tag
+ *   (div, table, tr, td, ...) → literal JSX element with props.
+ * - Named composite nodes (capitalised — DataTable, FieldList, ...)
+ *   → treated as React component references; the emitter collects
+ *   them into the imports set so view-emitter can add the
+ *   imports at the top of the file.
+ * - Special pseudo-components (__text__, __when_empty__, __todo__)
+ *   → each handled inline.
+ *
+ * Round-trip format: the output is readable, indented JSX. Not
+ * prettier-perfect but close.
+ */
+
+import type { RenderNode } from '@specverse/runtime/views/core';
+
+export interface EmitOptions {
+  /** Set of component names referenced (composite components only,
+   *  not HTML tags). View-emitter injects these as imports at the
+   *  top of the generated .tsx file. */
+  imports: Set<string>;
+  /** Initial indent — defaults to 6 (matches the {{BODY}} placement
+   *  inside the skeleton's <form>/<div> wrapper). */
+  indent?: number;
+}
+
+/**
+ * Emit a tree of RenderNodes to JSX source. Returns the JSX text;
+ * composite component names used are written into `options.imports`.
+ */
+export function emitJsxSource(
+  nodes: RenderNode[],
+  options: EmitOptions,
+): string {
+  const indent = options.indent ?? 0;
+  return nodes.map(n => emitNode(n, indent, options.imports)).join('\n');
+}
+
+/**
+ * Width past which we break the attr list onto its own lines.
+ * Keeps short elements compact (`<th className="...">Name</th>`)
+ * while long attribute lists (an input with required + value +
+ * onChange + ...) go multi-line for readability.
+ */
+const ATTR_BREAK_WIDTH = 80;
+
+function emitNode(node: RenderNode, indent: number, imports: Set<string>): string {
+  const pad = ' '.repeat(indent);
+
+  // Pseudo-components — intercepted before the generic path.
+  if (node.component === '__text__') {
+    return `${pad}${(node.props?.text as string) ?? ''}`;
+  }
+  if (node.component === '__todo__') {
+    const msg = (node.props?.message as string) ?? 'TODO';
+    return `${pad}{/* TODO: ${msg} */}`;
+  }
+  if (node.component === '__when_empty__') {
+    const source = (node.props?.source as string) ?? 'items';
+    const inner = (node.children ?? [])
+      .map(c => emitNode(c, indent + 2, imports))
+      .join('\n');
+    return [
+      `${pad}{${source}.length === 0 && (`,
+      inner,
+      `${pad})}`,
+    ].join('\n');
+  }
+  if (node.component === '__when__') {
+    // Generic conditional render — wraps children in
+    // `{condition && (...)}`. Used by detail-view tabbed lists where
+    // each panel renders only if `relatedTab === 'X'`.
+    const condition = (node.props?.condition as string) ?? 'true';
+    const inner = (node.children ?? [])
+      .map(c => emitNode(c, indent + 2, imports))
+      .join('\n');
+    return [
+      `${pad}{${condition} && (`,
+      inner,
+      `${pad})}`,
+    ].join('\n');
+  }
+
+  const isComposite = /^[A-Z]/.test(node.component);
+  if (isComposite) imports.add(node.component);
+
+  const attrParts = formatAttrParts(node.props, node.expressions);
+  const inlineAttrs = attrParts.length > 0 ? ' ' + attrParts.join(' ') : '';
+
+  // "Compact" elements — a single short text child, or inline
+  // expression content — get attrs inline regardless of length.
+  // Readability gain (long classNames on a header don't outweigh
+  // the ceremony of multi-line attrs for a one-word label).
+  const hasInlineExpression = Boolean(
+    node.expressions?.children && (!node.children || node.children.length === 0)
+  );
+  const hasSingleTextChild = Boolean(
+    node.children?.length === 1 &&
+    node.children[0].component === '__text__' &&
+    !node.children[0].iterate
+  );
+  const isCompact = hasInlineExpression || hasSingleTextChild;
+
+  const shouldBreakAttrs = !isCompact && inlineAttrs.length > ATTR_BREAK_WIDTH;
+  const multiLineAttrs = attrParts.length > 0
+    ? '\n' + attrParts.map(a => ' '.repeat(indent + 2) + a).join('\n') + '\n' + pad
+    : '';
+  const attrs = shouldBreakAttrs ? multiLineAttrs : inlineAttrs;
+
+  // Inline-expression content: `<tag>{expr}</tag>` on one line.
+  if (hasInlineExpression) {
+    return `${pad}<${node.component}${attrs}>{${node.expressions!.children}}</${node.component}>`;
+  }
+
+  // Single-text-child shortcut: `<tag>text</tag>` on one line.
+  if (hasSingleTextChild) {
+    const text = (node.children![0].props?.text as string) ?? '';
+    return `${pad}<${node.component}${attrs}>${text}</${node.component}>`;
+  }
+
+  const bodyLines = renderChildren(node, indent + 2, imports);
+
+  // Void elements — no children allowed, self-closing.
+  if (VOID_ELEMENTS.has(node.component) && bodyLines === null) {
+    return `${pad}<${node.component}${attrs} />`;
+  }
+
+  // No children → empty element.
+  if (bodyLines === null || bodyLines === '') {
+    return `${pad}<${node.component}${attrs} />`;
+  }
+
+  // Multi-line element with nested children.
+  return [
+    `${pad}<${node.component}${attrs}>`,
+    bodyLines,
+    `${pad}</${node.component}>`,
+  ].join('\n');
+}
+
+/**
+ * Render children as a string. Respects `iterate` — wraps children
+ * in a `.map(...)` when present. Returns `null` if the node has no
+ * content at all (caller may decide to self-close).
+ */
+function renderChildren(node: RenderNode, indent: number, imports: Set<string>): string | null {
+  const pad = ' '.repeat(indent);
+  const children = node.children ?? [];
+
+  if (node.iterate) {
+    const { source, itemName, keyExpression } = node.iterate;
+    // The iterate wraps the WHOLE element-with-its-children, not
+    // just the children list. Caller (emitNode) uses the fact that
+    // `iterate` is present on the node itself; this path is
+    // unreachable in the current shape.
+    // Placeholder — iterate is handled by the parent context below.
+    return children.map(c => emitNode(c, indent, imports)).join('\n');
+  }
+
+  if (children.length === 0 && !node.expressions?.children) return null;
+  if (children.length === 0 && node.expressions?.children) return '';
+
+  return children
+    .map(c => {
+      if (c.iterate) return emitIterated(c, indent, imports);
+      return emitNode(c, indent, imports);
+    })
+    .join('\n');
+}
+
+/**
+ * Emit a node whose `iterate` produces N instances. The form is
+ * `{source.map((item, idx) => ( <element>...</element> ))}`.
+ */
+function emitIterated(node: RenderNode, indent: number, imports: Set<string>): string {
+  const pad = ' '.repeat(indent);
+  const { source, itemName, keyExpression } = node.iterate!;
+  // Strip iterate so emitNode doesn't see it and re-wrap.
+  const inner = emitNode({ ...node, iterate: undefined }, indent + 2, imports);
+  const args = keyExpression ? `(${itemName}, ${keyExpression})` : `(${itemName})`;
+  return [
+    `${pad}{${source}.map(${args} => (`,
+    inner,
+    `${pad}))}`,
+  ].join('\n');
+}
+
+/**
+ * Return each attribute as its own formatted string — caller
+ * decides whether to join with spaces (inline) or newlines
+ * (multi-line readability).
+ */
+function formatAttrParts(
+  props: Record<string, unknown> | undefined,
+  expressions: Record<string, string> | undefined,
+): string[] {
+  const parts: string[] = [];
+
+  for (const [k, v] of Object.entries(props ?? {})) {
+    if (v === undefined || v === null) continue;
+    parts.push(formatStaticProp(k, v));
+  }
+
+  for (const [k, expr] of Object.entries(expressions ?? {})) {
+    if (k === 'children') continue;   // element content, not attr
+    parts.push(`${k}={${expr}}`);
+  }
+
+  return parts;
+}
+
+function formatStaticProp(name: string, value: unknown): string {
+  if (value === true) return name;
+  if (typeof value === 'string') return `${name}=${JSON.stringify(value)}`;
+  if (typeof value === 'number' || typeof value === 'boolean') {
+    return `${name}={${value}}`;
+  }
+  return `${name}={${JSON.stringify(value)}}`;
+}
+
+// HTML void elements (no children, must self-close in JSX).
+const VOID_ELEMENTS = new Set([
+  'area', 'base', 'br', 'col', 'embed', 'hr', 'img',
+  'input', 'link', 'meta', 'source', 'track', 'wbr',
+]);