@specverse/engines 4.1.30 → 4.2.1

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

@@ -0,0 +1,383 @@
+/**
+ * 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 <select> dropdowns
+ * backed by the related model's list query. The corresponding hook
+ * calls and imports are wired by view-emitter via the RELATED_HOOKS /
+ * RELATED_IMPORTS substitutions — this composer only emits the JSX
+ * that consumes the `${relName}Options` variable.
+ */
+
+import { METADATA_FIELDS } from '@specverse/runtime/views/core';
+import type { EmitContext, ModelSpec } from './view-emitter.js';
+import { extractBelongsToTargets, type BelongsToRel } from './belongs-to.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 = extractBelongsToTargets(context.model);
+  // FK columns shadowed by a belongsTo relationship are emitted in the
+  // belongsTo section as <select>s — skip them in the main loop so we
+  // don't render both a plain-text input and a dropdown for the same
+  // column.
+  const shadowedFKs = new Set(belongsTo.map(rel => `${rel.name}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));
+  }
+
+  for (const rel of belongsTo) {
+    lines.push(...renderRelationshipSelect(rel));
+  }
+
+  lines.push('</div>');
+  return lines.join('\n');
+}
+
+/**
+ * Emit a <select> dropdown for a belongsTo relationship. The options
+ * array (`${relName}Options`) is populated by the hook call wired in
+ * via view-emitter's RELATED_HOOKS substitution. Labels use
+ * `getEntityDisplayName` so users see human names instead of UUIDs.
+ */
+function renderRelationshipSelect(rel: BelongsToRel): string[] {
+  const fkName = `${rel.name}Id`;
+  const varName = `${rel.name}Options`;
+  const label = humanize(rel.name);
+
+  return [
+    '  <div>',
+    `    <label className="${LABEL_CLS}" htmlFor="${fkName}">${label} *</label>`,
+    `    <select`,
+    `      id="${fkName}"`,
+    `      className="${INPUT_CLS}"`,
+    `      value={String((formData as any).${fkName} ?? '')}`,
+    `      onChange={e => handleChange('${fkName}', e.target.value)} required`,
+    `    >`,
+    `      <option value="">— choose —</option>`,
+    `      {${varName}.map((opt: any) => (`,
+    `        <option key={opt.id} value={opt.id}>{getEntityDisplayName(opt)}</option>`,
+    `      ))}`,
+    `    </select>`,
+    '  </div>',
+  ];
+}
+
+// ──────────────────────────────────────────────────────────────────────
+// 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 ?? {};
+  const lifecycleStates = extractLifecycleStates(model);
+
+  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 declaredValues = def?.values as string[] | undefined;
+    // Lifecycle-backed attributes: if the model declares a lifecycle
+    // with the same name as this attribute, the attribute's valid
+    // values are the lifecycle states. Matches the FK rule's spirit —
+    // any attribute whose legal values are declared elsewhere in the
+    // spec should render as a <select>, not free text.
+    const lifecycleValues = lifecycleStates.get(name);
+    const values = declaredValues ?? lifecycleValues;
+    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;
+}
+
+/**
+ * Map from attribute name → list of lifecycle states, extracted from
+ * the model's `lifecycles` section. Supports both the convention-string
+ * shape (`flow: "a -> b -> c"`) and structured (`states: ["a", ...]`).
+ *
+ * Example:
+ *   lifecycles:
+ *     status:
+ *       flow: "planning -> active -> completed -> archived"
+ * returns { status → ['planning', 'active', 'completed', 'archived'] }
+ */
+function extractLifecycleStates(model: ModelSpec): Map<string, string[]> {
+  const out = new Map<string, string[]>();
+  const lifecycles = (model as ModelSpec & { lifecycles?: Record<string, unknown> }).lifecycles ?? {};
+
+  for (const [name, rawDef] of Object.entries(lifecycles)) {
+    if (!rawDef || typeof rawDef !== 'object') continue;
+    // The parser normalizes lifecycles into a rich structured form:
+    //   { flow: "a -> b -> c",
+    //     states: [{ name: "a" }, { name: "b" }, { name: "c" }],
+    //     transitions: [...],
+    //     initialState: "a" }
+    // Also support the pre-normalization shape (states as plain strings,
+    // or just a flow string) so the composer works on raw specs too.
+    const def = rawDef as {
+      flow?: string;
+      states?: Array<string | { name?: string; id?: string }>;
+    };
+
+    if (Array.isArray(def.states) && def.states.length > 0) {
+      const names = def.states
+        .map(s => (typeof s === 'string' ? s : s?.name ?? s?.id ?? ''))
+        .filter(Boolean);
+      if (names.length > 0) {
+        out.set(name, names);
+        continue;
+      }
+    }
+
+    if (typeof def.flow === 'string') {
+      // Split on -> with optional whitespace. Also accept commas as a
+      // fallback separator so a state list like "a, b, c" still works.
+      const states = def.flow
+        .split(/\s*(?:->|,)\s*/)
+        .map(s => s.trim())
+        .filter(Boolean);
+      if (states.length > 0) out.set(name, states);
+    }
+  }
+  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].*$/, '');
+}
+
+// (`extractBelongsTo` was removed — the shared helper in
+// `./belongs-to.ts` returns both the relationship name AND the target
+// model so view-emitter can wire the hook call for each dropdown.)
+
+// ──────────────────────────────────────────────────────────────────────
+// 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,66 @@
+/**
+ * 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 / dashboard views.
+ *
+ * Typed as \`readonly unknown[]\` so callers can pass arrays of
+ * specific model types (e.g. \`User[]\`) without needing to cast; the
+ * runtime check on \`.id\` narrows safely.
+ */
+export function resolveEntityDisplayName(
+  id: unknown,
+  records: readonly unknown[]
+): string {
+  if (id == null) return '';
+  const match = records.find((r): r is Record<string, unknown> =>
+    typeof r === 'object' && r !== null && (r as { id?: unknown }).id === id
+  );
+  return match ? getEntityDisplayName(match) : String(id);
+}
+`;
+}