@specverse/engines 4.1.30 → 4.2.1

package/dist/libs/instance-factories/applications/templates/react-starter/belongs-to.js

@@ -0,0 +1,40 @@
+function extractBelongsToTargets(model) {
+  const rels = model.relationships ?? {};
+  const out = [];
+  for (const [name, rawDef] of Object.entries(rels)) {
+    const parsed = parseBelongsTo(rawDef);
+    if (parsed) out.push({ name, target: parsed });
+  }
+  return out;
+}
+function parseBelongsTo(def) {
+  if (typeof def === "string") {
+    const parts = def.trim().split(/\s+/);
+    if (parts[0] === "belongsTo" && parts[1]) return parts[1];
+    return null;
+  }
+  if (def && typeof def === "object") {
+    const o = def;
+    if (o.type === "belongsTo") {
+      return o.target || o.to || o.model || o.targetModel || null;
+    }
+  }
+  return null;
+}
+function pluralize(s) {
+  if (/[^aeiou]y$/i.test(s)) return s.slice(0, -1) + "ies";
+  if (/(s|x|z|ch|sh)$/i.test(s)) return s + "es";
+  return s + "s";
+}
+function buildFKMap(model) {
+  const map = /* @__PURE__ */ new Map();
+  for (const rel of extractBelongsToTargets(model)) {
+    map.set(`${rel.name}Id`, rel);
+  }
+  return map;
+}
+export {
+  buildFKMap,
+  extractBelongsToTargets,
+  pluralize
+};

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

@@ -0,0 +1,129 @@
+import { METADATA_FIELDS } from "@specverse/runtime/views/core";
+import { buildFKMap } from "./belongs-to.js";
+const METADATA_FIELD_NAMES = new Set(METADATA_FIELDS);
+function composeDashboardBody(context) {
+  const modelName = context.model.name;
+  const previewColumns = inferPreviewColumns(context.model);
+  const enumFields = inferEnumFields(context.model);
+  const fkMap = buildFKMap(context.model);
+  const lines = [];
+  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>");
+  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. */}");
+  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");
+}
+function renderTotalCard(modelName) {
+  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) {
+  const cards = [];
+  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() {
+  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 \u2014 e.g. a sum, average, or time-windowed count.",
+    "  </div>"
+  ];
+}
+function inferEnumFields(model) {
+  const out = [];
+  const attrs = model.attributes ?? {};
+  for (const [name, rawDef] of Object.entries(attrs)) {
+    const def = rawDef;
+    const values = def?.values;
+    if (Array.isArray(values) && values.length > 0 && values.length <= 6) {
+      out.push({ name, values });
+    }
+  }
+  return out.slice(0, 1);
+}
+function inferPreviewColumns(model) {
+  const attrs = model.attributes ?? {};
+  const attrCols = Object.keys(attrs).filter((n) => !METADATA_FIELD_NAMES.has(n));
+  const fkCols = [...buildFKMap(model).keys()].filter((k) => !attrCols.includes(k));
+  return [...fkCols, ...attrCols].slice(0, Math.max(5, fkCols.length + 1));
+}
+function humanize(name) {
+  return name.replace(/([A-Z])/g, " $1").replace(/^./, (c) => c.toUpperCase()).trim();
+}
+export {
+  composeDashboardBody
+};

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

@@ -0,0 +1,80 @@
+import { METADATA_FIELDS } from "@specverse/runtime/views/core";
+import { extractBelongsToTargets } from "./belongs-to.js";
+const METADATA_FIELD_NAMES = new Set(METADATA_FIELDS);
+function composeDetailBody(context) {
+  const belongsTo = extractBelongsToTargets(context.model);
+  const fkExcludes = new Set(belongsTo.map((r) => `${r.name}Id`));
+  const { business, metadata } = partitionFields(context.model, fkExcludes);
+  const lines = [];
+  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");
+}
+function partitionFields(model, exclude = /* @__PURE__ */ new Set()) {
+  const attrs = Object.keys(model.attributes ?? {});
+  const business = [];
+  const metadata = [];
+  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 };
+}
+function renderRelationshipField(rel) {
+  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, opts) {
+  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) {
+  return name.replace(/([A-Z])/g, " $1").replace(/^./, (c) => c.toUpperCase()).trim();
+}
+export {
+  composeDetailBody
+};

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

@@ -0,0 +1,217 @@
+import { METADATA_FIELDS } from "@specverse/runtime/views/core";
+import { extractBelongsToTargets } from "./belongs-to.js";
+const AUTO_GENERATED_FIELD_NAMES = new Set(METADATA_FIELDS);
+function composeFormBody(context) {
+  const belongsTo = extractBelongsToTargets(context.model);
+  const shadowedFKs = new Set(belongsTo.map((rel) => `${rel.name}Id`));
+  const fields = selectFormFields(context.model, shadowedFKs);
+  const lines = [];
+  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");
+}
+function renderRelationshipSelect(rel) {
+  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="">\u2014 choose \u2014</option>`,
+    `      {${varName}.map((opt: any) => (`,
+    `        <option key={opt.id} value={opt.id}>{getEntityDisplayName(opt)}</option>`,
+    `      ))}`,
+    `    </select>`,
+    "  </div>"
+  ];
+}
+function selectFormFields(model, skip = /* @__PURE__ */ new Set()) {
+  const out = [];
+  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;
+    if (def?.auto) continue;
+    const type = def?.type ?? parseTypeFromConvention(def) ?? "String";
+    const required = def?.required === true || hasConventionFlag(def, "required");
+    const declaredValues = def?.values;
+    const lifecycleValues = lifecycleStates.get(name);
+    const values = declaredValues ?? lifecycleValues;
+    const maxLength = def?.maxLength ?? def?.max;
+    const isLongString = typeof maxLength === "number" && maxLength > 100;
+    out.push({
+      name,
+      label: humanize(name),
+      type: normalizeType(type),
+      required,
+      values,
+      isLongString
+    });
+  }
+  return out;
+}
+function extractLifecycleStates(model) {
+  const out = /* @__PURE__ */ new Map();
+  const lifecycles = model.lifecycles ?? {};
+  for (const [name, rawDef] of Object.entries(lifecycles)) {
+    if (!rawDef || typeof rawDef !== "object") continue;
+    const def = rawDef;
+    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") {
+      const states = def.flow.split(/\s*(?:->|,)\s*/).map((s) => s.trim()).filter(Boolean);
+      if (states.length > 0) out.set(name, states);
+    }
+  }
+  return out;
+}
+function parseTypeFromConvention(def) {
+  if (typeof def === "string") {
+    const first = def.trim().split(/\s+/)[0];
+    return first;
+  }
+  return void 0;
+}
+function hasConventionFlag(def, flag) {
+  if (typeof def === "string") {
+    return def.split(/\s+/).includes(flag);
+  }
+  return false;
+}
+function normalizeType(type) {
+  return type.replace(/[^A-Za-z].*$/, "");
+}
+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) {
+  const requiredMark = field.required ? " *" : "";
+  const reqAttr = field.required ? " required" : "";
+  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="">\u2014 choose \u2014</option>`,
+      options,
+      `    </select>`,
+      "  </div>"
+    ];
+  }
+  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>"
+    ];
+  }
+  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>"
+  ];
+}
+function mapInputType(type) {
+  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";
+  }
+}
+function coerceOnChange(type) {
+  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";
+  }
+}
+function humanize(name) {
+  return name.replace(/([A-Z])/g, " $1").replace(/^./, (c) => c.toUpperCase()).trim();
+}
+function escapeAttr(s) {
+  return s.replace(/"/g, "&quot;");
+}
+function escapeText(s) {
+  return s.replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+export {
+  composeFormBody
+};

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

@@ -0,0 +1,51 @@
+function emitEntityDisplay() {
+  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 \u2014 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) + '\u2026' : 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);
+}
+`;
+}
+export {
+  emitEntityDisplay
+};