@specverse/engines 4.1.28 → 4.2.0

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), metadata fields second (muted).
+ * The outer card + actions live in `skeletons/detail.tsx.template`.
+ *
+ * Unlike list view, the interior here is mostly label→value pairs, not
+ * a table. We use `<dl>` / `<dt>` / `<dd>` directly rather than routing
+ * through a specific atomic component — the field-list shape isn't one
+ * of the adapter's atomic components, and forcing it through a `card`
+ * adapter would add structure without clarifying anything in the
+ * generated code.
+ *
+ * BelongsTo relationships: today we emit the raw FK id. A future pass
+ * will resolve FK → entity display name (matches runtime's
+ * getEntityDisplayName). Marked with a TODO comment in the output so
+ * users inspecting the generated file see the hook.
+ */
+
+import { METADATA_FIELDS } from '@specverse/runtime/views/core';
+import type { EmitContext, ModelSpec } from './view-emitter.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 {
+  const { business, metadata } = partitionFields(context.model);
+  const belongsTo = extractBelongsTo(context.model);
+
+  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 {
+    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('  {/* TODO: resolve FK ids → related entity display names.');
+    lines.push('      See @specverse/runtime/views/core/entity-display for the');
+    lines.push('      canonical resolver, or load the related record in a hook. */}');
+    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(...renderField({ name: `${rel}Id`, label: humanize(rel) }, { muted: false }));
+    }
+    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): { business: Field[]; metadata: Field[] } {
+  const attrs = Object.keys(model.attributes ?? {});
+  const business: Field[] = [];
+  const metadata: Field[] = [];
+  for (const name of attrs) {
+    const field = { name, label: humanize(name) };
+    if (METADATA_FIELD_NAMES.has(name)) {
+      metadata.push(field);
+    } else {
+      business.push(field);
+    }
+  }
+  return { business, metadata };
+}
+
+/**
+ * Extract belongsTo relationship names from the model. Returns e.g.
+ * `['author']` for a Post that `belongsTo Author`. The skeleton's
+ * item already has `authorId` as a scalar field — we surface it
+ * explicitly in its own section so the generated UI separates "this
+ * entity's data" from "related entities."
+ */
+function extractBelongsTo(model: ModelSpec): string[] {
+  const rels = model.relationships ?? {};
+  const out: string[] = [];
+  for (const [name, def] of Object.entries(rels)) {
+    const d = def as { type?: string };
+    if (d?.type === 'belongsTo') out.push(name);
+  }
+  return out;
+}
+
+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();
+}

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

@@ -0,0 +1,306 @@
+/**
+ * Form-view body composer for ReactAppStarter
+ *
+ * Emits one <label>+<input> pair per editable attribute of the model.
+ * Input type is inferred from the attribute's type + constraints
+ * (mirrors the canonical mapping in
+ * `entities/src/core/views/inference/component-mappings.json`, minus
+ * the atomic-component indirection).
+ *
+ * Auto-generated fields (id, timestamps, `auto=...` markers) are
+ * omitted — the backend assigns them.
+ *
+ * Relationship fields (belongsTo) are emitted as plain-text inputs
+ * for the FK column with a TODO comment. Wiring them to a proper
+ * dropdown requires a hook that loads the related list at form render
+ * time; deferred to a later pass. The inline TODO is the hook for
+ * users who want to upgrade.
+ */
+
+import { METADATA_FIELDS } from '@specverse/runtime/views/core';
+import type { EmitContext, ModelSpec } from './view-emitter.js';
+
+/**
+ * Attribute names the backend always generates — never render as
+ * inputs. Sourced from the pattern library's metadata set; any
+ * attribute with `auto=...` or category=metadata is additionally
+ * skipped via per-field checks in `selectFormFields` below.
+ */
+const AUTO_GENERATED_FIELD_NAMES = new Set(METADATA_FIELDS);
+
+/**
+ * Compose the form body as JSX-safe source. Dropped at `{{BODY}}`.
+ */
+export function composeFormBody(context: EmitContext): string {
+  const belongsTo = extractBelongsTo(context.model);
+  // FK columns shadowed by a belongsTo relationship are emitted in the
+  // belongsTo section with a nicer label ("Author" instead of
+  // "Author Id") — skip them in the main loop so we don't render twice.
+  const shadowedFKs = new Set(belongsTo.map(rel => `${rel}Id`));
+  const fields = selectFormFields(context.model, shadowedFKs);
+
+  const lines: string[] = [];
+  lines.push('<div className="space-y-4">');
+
+  if (fields.length === 0 && belongsTo.length === 0) {
+    lines.push('  <p className="text-sm text-gray-400">No editable fields for this model.</p>');
+    lines.push('</div>');
+    return lines.join('\n');
+  }
+
+  for (const field of fields) {
+    lines.push(...renderInput(field));
+  }
+
+  if (belongsTo.length > 0) {
+    lines.push('');
+    lines.push('  {/* TODO: swap these text inputs for <select>s that load the related');
+    lines.push('      entities. See useEntitiesQuery(TargetModel) in the runtime hooks. */}');
+    for (const rel of belongsTo) {
+      lines.push(...renderInput({
+        name: `${rel}Id`,
+        label: humanize(rel),
+        type: 'String',
+        required: true,
+      }));
+    }
+  }
+
+  lines.push('</div>');
+  return lines.join('\n');
+}
+
+// ──────────────────────────────────────────────────────────────────────
+// Field selection
+// ──────────────────────────────────────────────────────────────────────
+
+interface FieldInfo {
+  name: string;
+  label: string;
+  type: string;
+  required: boolean;
+  values?: string[];    // enum options if present
+  isLongString?: boolean;
+  auto?: boolean;
+}
+
+function selectFormFields(
+  model: ModelSpec,
+  skip: Set<string> = new Set()
+): FieldInfo[] {
+  const out: FieldInfo[] = [];
+  const attrs = model.attributes ?? {};
+  for (const [name, rawDef] of Object.entries(attrs)) {
+    if (AUTO_GENERATED_FIELD_NAMES.has(name)) continue;
+    if (skip.has(name)) continue;
+
+    const def = rawDef as AttributeShape;
+    if (def?.auto) continue;
+
+    // Heuristic: parse a type like "String required unique" to detect
+    // convention-string shapes. We prefer the structured fields if
+    // they're present.
+    const type = (def?.type ?? parseTypeFromConvention(def)) ?? 'String';
+    const required = def?.required === true || hasConventionFlag(def, 'required');
+    const values = def?.values as string[] | undefined;
+    const maxLength = def?.maxLength ?? def?.max as number | undefined;
+    const isLongString =
+      typeof maxLength === 'number' && maxLength > 100;
+
+    out.push({
+      name,
+      label: humanize(name),
+      type: normalizeType(type),
+      required,
+      values,
+      isLongString,
+    });
+  }
+  return out;
+}
+
+/** Structured attribute object from the parsed spec. */
+interface AttributeShape {
+  type?: string;
+  required?: boolean;
+  unique?: boolean;
+  auto?: string;
+  values?: string[];
+  maxLength?: number;
+  max?: number;
+  [k: string]: unknown;
+}
+
+function parseTypeFromConvention(def: unknown): string | undefined {
+  // Convention form: "String required unique"
+  if (typeof def === 'string') {
+    const first = def.trim().split(/\s+/)[0];
+    return first;
+  }
+  return undefined;
+}
+
+function hasConventionFlag(def: unknown, flag: string): boolean {
+  if (typeof def === 'string') {
+    return def.split(/\s+/).includes(flag);
+  }
+  return false;
+}
+
+function normalizeType(type: string): string {
+  // Strip any trailing modifiers from a compact convention-string form.
+  return type.replace(/[^A-Za-z].*$/, '');
+}
+
+function extractBelongsTo(model: ModelSpec): string[] {
+  const rels = model.relationships ?? {};
+  const out: string[] = [];
+  for (const [name, def] of Object.entries(rels)) {
+    if ((def as { type?: string })?.type === 'belongsTo') out.push(name);
+  }
+  return out;
+}
+
+// ──────────────────────────────────────────────────────────────────────
+// Input rendering
+// ──────────────────────────────────────────────────────────────────────
+
+const INPUT_CLS =
+  'w-full rounded border border-gray-300 px-3 py-2 text-sm ' +
+  'focus:outline-none focus:ring-2 focus:ring-blue-500 ' +
+  'dark:border-gray-600 dark:bg-gray-800 dark:text-gray-100';
+
+const LABEL_CLS = 'block text-sm font-medium text-gray-700 dark:text-gray-300 mb-1';
+
+function renderInput(field: FieldInfo): string[] {
+  const requiredMark = field.required ? ' *' : '';
+  const reqAttr = field.required ? ' required' : '';
+
+  // Enum → <select>
+  if (field.values && field.values.length > 0) {
+    const options = field.values
+      .map(v => `      <option value="${escapeAttr(v)}">${escapeText(v)}</option>`)
+      .join('\n');
+    return [
+      '  <div>',
+      `    <label className="${LABEL_CLS}" htmlFor="${field.name}">${field.label}${requiredMark}</label>`,
+      `    <select`,
+      `      id="${field.name}"`,
+      `      className="${INPUT_CLS}"`,
+      `      value={String((formData as any).${field.name} ?? '')}`,
+      `      onChange={e => handleChange('${field.name}', e.target.value)}${reqAttr}`,
+      `    >`,
+      `      <option value="">— choose —</option>`,
+      options,
+      `    </select>`,
+      '  </div>',
+    ];
+  }
+
+  // Long-string / Text → <textarea>
+  if (field.type === 'Text' || field.isLongString) {
+    return [
+      '  <div>',
+      `    <label className="${LABEL_CLS}" htmlFor="${field.name}">${field.label}${requiredMark}</label>`,
+      `    <textarea`,
+      `      id="${field.name}"`,
+      `      className="${INPUT_CLS}"`,
+      `      rows={4}`,
+      `      value={String((formData as any).${field.name} ?? '')}`,
+      `      onChange={e => handleChange('${field.name}', e.target.value)}${reqAttr}`,
+      `    />`,
+      '  </div>',
+    ];
+  }
+
+  // Boolean → checkbox
+  if (field.type === 'Boolean') {
+    return [
+      '  <div>',
+      `    <label className="inline-flex items-center gap-2">`,
+      `      <input`,
+      `        id="${field.name}"`,
+      `        type="checkbox"`,
+      `        checked={Boolean((formData as any).${field.name})}`,
+      `        onChange={e => handleChange('${field.name}', e.target.checked)}`,
+      `      />`,
+      `      <span className="text-sm text-gray-700 dark:text-gray-300">${field.label}${requiredMark}</span>`,
+      `    </label>`,
+      '  </div>',
+    ];
+  }
+
+  const inputType = mapInputType(field.type);
+  return [
+    '  <div>',
+    `    <label className="${LABEL_CLS}" htmlFor="${field.name}">${field.label}${requiredMark}</label>`,
+    `    <input`,
+    `      id="${field.name}"`,
+    `      type="${inputType}"`,
+    `      className="${INPUT_CLS}"`,
+    `      value={String((formData as any).${field.name} ?? '')}`,
+    `      onChange={e => handleChange('${field.name}', ${coerceOnChange(field.type)})}${reqAttr}`,
+    `    />`,
+    '  </div>',
+  ];
+}
+
+/** Scalar SpecVerse type → HTML input type attribute. */
+function mapInputType(type: string): string {
+  switch (type) {
+    case 'Integer':
+    case 'Float':
+    case 'Number':
+    case 'Money':
+      return 'number';
+    case 'DateTime':
+      return 'datetime-local';
+    case 'Date':
+      return 'date';
+    case 'Email':
+      return 'email';
+    case 'URL':
+      return 'url';
+    case 'String':
+    case 'UUID':
+    default:
+      return 'text';
+  }
+}
+
+/**
+ * JSX snippet for the onChange handler's second argument — coerces
+ * the string value to the right shape for the field. The user can
+ * edit this; defaults are a reasonable starter.
+ */
+function coerceOnChange(type: string): string {
+  switch (type) {
+    case 'Integer':
+    case 'Number':
+      return "e.target.value === '' ? undefined : Number(e.target.value)";
+    case 'Float':
+    case 'Money':
+      return "e.target.value === '' ? undefined : parseFloat(e.target.value)";
+    default:
+      return 'e.target.value';
+  }
+}
+
+// ──────────────────────────────────────────────────────────────────────
+// Small helpers
+// ──────────────────────────────────────────────────────────────────────
+
+function humanize(name: string): string {
+  return name
+    .replace(/([A-Z])/g, ' $1')
+    .replace(/^./, c => c.toUpperCase())
+    .trim();
+}
+
+function escapeAttr(s: string): string {
+  return s.replace(/"/g, '&quot;');
+}
+
+function escapeText(s: string): string {
+  return s.replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}

package/libs/instance-factories/applications/templates/react-starter/helpers-emitter.ts

@@ -0,0 +1,60 @@
+/**
+ * Helpers emitter for ReactAppStarter
+ *
+ * Returns the source of small utility files that generated projects
+ * use. Inlined into `src/lib/` at realize time rather than imported
+ * from `@specverse/runtime` — Factory B's defining trait is that the
+ * generated code has no @specverse/* runtime dependency.
+ */
+
+/**
+ * Source of `src/lib/entity-display.ts`.
+ *
+ * Mirrors `getEntityDisplayName` from
+ * `@specverse/runtime/views/core/entity-display`. Used by:
+ * - The FK-resolution TODO in detail-view output (users who upgrade
+ *   the plain-FK display to a resolved display name import this).
+ * - Any user-written code that wants to label a record.
+ */
+export function emitEntityDisplay(): string {
+  return `/**
+ * Pick the best human-readable label for an entity.
+ *
+ * Walks a prioritized list of candidate fields. Falls back to a
+ * truncated id if none match. Inlined into this project by
+ * @specverse/realize (ReactAppStarter); edit freely — nothing in
+ * the factory's regeneration will clobber your edits.
+ */
+export function getEntityDisplayName(entity: Record<string, unknown> | null | undefined): string {
+  if (!entity) return '';
+
+  const candidates = ['name', 'title', 'displayName', 'label', 'username', 'email'];
+  for (const key of candidates) {
+    const value = entity[key];
+    if (typeof value === 'string' && value.trim().length > 0) {
+      return value;
+    }
+  }
+
+  const id = entity.id;
+  if (typeof id === 'string') {
+    return id.length > 8 ? id.slice(0, 8) + '…' : id;
+  }
+  return id != null ? String(id) : '';
+}
+
+/**
+ * Map an entity id to the display name of the record with that id in
+ * a provided list. Handy for resolving belongsTo FK columns in
+ * list / detail views.
+ */
+export function resolveEntityDisplayName(
+  id: unknown,
+  records: ReadonlyArray<Record<string, unknown>>
+): string {
+  if (id == null) return '';
+  const match = records.find(r => r.id === id);
+  return match ? getEntityDisplayName(match) : String(id);
+}
+`;
+}