@specverse/engines 4.1.30 → 4.2.1

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

@@ -0,0 +1,189 @@
+/**
+ * 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';
+import { buildFKMap } from './belongs-to.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 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();
+}

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

@@ -0,0 +1,135 @@
+/**
+ * Detail-view body composer for ReactAppStarter
+ *
+ * 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.
+ */
+
+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);
+
+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();
+}