@specverse/engines 4.1.30 → 4.2.0

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);
+}
+`;
+}

package/libs/instance-factories/applications/templates/react-starter/html-to-jsx.ts

@@ -0,0 +1,334 @@
+/**
+ * HTML → JSX transformer for ReactAppStarter
+ *
+ * Input: HTML strings produced by the canonical Tailwind adapter
+ * (`@specverse/runtime/views/tailwind`). Output: JSX-safe source
+ * that can be dropped between JSX tags in a .tsx template.
+ *
+ * Scope is deliberately narrow:
+ *  - Controlled input — only the adapter's output shape matters.
+ *  - String transformer with a small tokenizer, not a full HTML parser.
+ *  - No SVG / MathML / script / style tags.
+ *
+ * If the adapter ever produces markup outside this scope, extend the
+ * ATTRIBUTE_RENAMES map / VOID_ELEMENTS set + add a focused test,
+ * don't broaden the tokenizer into a general HTML parser.
+ *
+ * See: README.md ("The html-to-jsx transformer — scope").
+ */
+
+/**
+ * HTML void elements — must be self-closing in JSX.
+ */
+const VOID_ELEMENTS = new Set([
+  'area', 'base', 'br', 'col', 'embed', 'hr', 'img',
+  'input', 'link', 'meta', 'source', 'track', 'wbr',
+]);
+
+/**
+ * HTML attribute → JSX attribute renames. JSX is case-sensitive and
+ * camelCases several HTML attribute names. Only lists the ones the
+ * Tailwind adapter actually emits.
+ */
+const ATTRIBUTE_RENAMES: Record<string, string> = {
+  class: 'className',
+  for: 'htmlFor',
+  tabindex: 'tabIndex',
+  readonly: 'readOnly',
+  maxlength: 'maxLength',
+  minlength: 'minLength',
+  colspan: 'colSpan',
+  rowspan: 'rowSpan',
+  autofocus: 'autoFocus',
+  autocomplete: 'autoComplete',
+  cellpadding: 'cellPadding',
+  cellspacing: 'cellSpacing',
+  enctype: 'encType',
+  usemap: 'useMap',
+  accesskey: 'accessKey',
+  contenteditable: 'contentEditable',
+  spellcheck: 'spellCheck',
+  crossorigin: 'crossOrigin',
+  srcset: 'srcSet',
+  srcdoc: 'srcDoc',
+};
+
+/**
+ * Convert an HTML string to JSX-safe source.
+ *
+ * Idempotent on already-JSX-shaped input.
+ */
+export function htmlToJsx(html: string): string {
+  if (!html) return '';
+
+  const tokens = tokenize(html);
+  return tokens.map(transformToken).join('');
+}
+
+// ──────────────────────────────────────────────────────────────────────
+// Tokenizer
+// ──────────────────────────────────────────────────────────────────────
+
+type Token =
+  | { kind: 'text'; value: string }
+  | { kind: 'tag'; raw: string; tagName: string; isClosing: boolean; isSelfClosed: boolean };
+
+/**
+ * Split an HTML string into text and tag tokens. Quoted attribute
+ * values never close a tag, even if they contain '>'. The adapter
+ * does not emit unbalanced quotes, so a simple state machine is
+ * sufficient.
+ */
+function tokenize(input: string): Token[] {
+  const tokens: Token[] = [];
+  let i = 0;
+  const n = input.length;
+
+  while (i < n) {
+    const ch = input[i];
+    if (ch === '<') {
+      // Start of tag. Consume until the matching '>', respecting quotes.
+      const tagStart = i;
+      i++; // consume '<'
+
+      let quote: '"' | "'" | null = null;
+      while (i < n) {
+        const c = input[i];
+        if (quote) {
+          if (c === quote) quote = null;
+          i++;
+          continue;
+        }
+        if (c === '"' || c === "'") {
+          quote = c;
+          i++;
+          continue;
+        }
+        if (c === '>') {
+          i++; // include the '>'
+          break;
+        }
+        i++;
+      }
+
+      const raw = input.slice(tagStart, i);
+      const isClosing = raw.startsWith('</');
+      const isSelfClosed = raw.endsWith('/>');
+      const tagName = parseTagName(raw);
+      tokens.push({ kind: 'tag', raw, tagName, isClosing, isSelfClosed });
+    } else {
+      // Text until the next '<'.
+      const textStart = i;
+      while (i < n && input[i] !== '<') i++;
+      tokens.push({ kind: 'text', value: input.slice(textStart, i) });
+    }
+  }
+
+  return tokens;
+}
+
+function parseTagName(tagRaw: string): string {
+  // Handles '<foo', '</foo', '<foo ', '<foo/>', '<foo>' etc.
+  const m = tagRaw.match(/^<\/?([a-zA-Z][a-zA-Z0-9-]*)/);
+  return m ? m[1].toLowerCase() : '';
+}
+
+// ──────────────────────────────────────────────────────────────────────
+// Transformation
+// ──────────────────────────────────────────────────────────────────────
+
+function transformToken(token: Token): string {
+  if (token.kind === 'text') {
+    // Adapter output never contains raw '{' or '}' in text nodes in
+    // the current implementation. If that changes, escape them here
+    // via `{'{'}` / `{'}'}`. Flagged for future: a regression test
+    // in view-emitter.test.ts that feeds a spec containing literal
+    // braces and expects them round-tripped.
+    return token.value;
+  }
+
+  return transformTag(token.raw, token.tagName, token.isClosing, token.isSelfClosed);
+}
+
+/**
+ * Transform a single tag: rename attributes, self-close if void.
+ *
+ * Works inside-out: split into `<`, open-portion, attributes, close-portion, `>`.
+ * We only rewrite attribute NAMES (identifier tokens at attribute start),
+ * never attribute values or text. The tokenizer guarantees we see the
+ * full tag as one unit.
+ */
+function transformTag(
+  raw: string,
+  tagName: string,
+  isClosing: boolean,
+  isSelfClosed: boolean
+): string {
+  if (isClosing) {
+    // '</div>' — nothing to rewrite
+    return raw;
+  }
+
+  // Split the tag into the tag-name section and the attributes section.
+  // Strip the leading '<' and trailing '>' or '/>'.
+  const inner = isSelfClosed
+    ? raw.slice(1, -2).trimEnd()
+    : raw.slice(1, -1);
+
+  // Separate tag name from attributes. The tag name is the first word.
+  const nameMatch = inner.match(/^([a-zA-Z][a-zA-Z0-9-]*)(.*)$/s);
+  if (!nameMatch) return raw;
+
+  const elementName = nameMatch[1];
+  const attrsSection = nameMatch[2];
+
+  // Parse attributes into structured form, rename names, re-serialise.
+  // This guarantees we never rewrite anything inside an attribute value.
+  const attrs = parseAttributes(attrsSection);
+  const renamedAttrs = attrs.map(renameAttribute);
+  const rebuiltAttrs = serializeAttributes(renamedAttrs);
+
+  const shouldSelfClose = VOID_ELEMENTS.has(tagName) && !isSelfClosed;
+
+  if (shouldSelfClose || isSelfClosed) {
+    return `<${elementName}${rebuiltAttrs} />`;
+  }
+  return `<${elementName}${rebuiltAttrs}>`;
+}
+
+// ──────────────────────────────────────────────────────────────────────
+// Attribute tokenizer
+// ──────────────────────────────────────────────────────────────────────
+
+interface Attribute {
+  name: string;
+  /** undefined = boolean attribute, no value. */
+  value?: string;
+  /** How the original source quoted the value — preserve on output. */
+  quote?: '"' | "'";
+}
+
+/**
+ * Parse the attributes section of a tag (the substring after the tag
+ * name, before the closing `>` or `/>`) into a list of attributes.
+ * Whitespace is consumed between attributes; values inside quotes are
+ * opaque.
+ */
+function parseAttributes(section: string): Attribute[] {
+  const attrs: Attribute[] = [];
+  let i = 0;
+  const n = section.length;
+
+  while (i < n) {
+    // Skip whitespace
+    while (i < n && /\s/.test(section[i])) i++;
+    if (i >= n) break;
+
+    // Read name (letters, digits, hyphens, colons for namespaced attrs)
+    const nameStart = i;
+    while (i < n && /[a-zA-Z0-9:_-]/.test(section[i])) i++;
+    if (i === nameStart) {
+      // Nothing we recognise — advance to avoid infinite loop
+      i++;
+      continue;
+    }
+    const name = section.slice(nameStart, i);
+
+    // Look for '=value' or end-of-attr
+    // Skip whitespace before '='
+    let j = i;
+    while (j < n && /\s/.test(section[j])) j++;
+    if (j >= n || section[j] !== '=') {
+      // Boolean attribute (e.g. `readonly`, `disabled`)
+      attrs.push({ name });
+      continue;
+    }
+    // Consume '=' and optional whitespace
+    i = j + 1;
+    while (i < n && /\s/.test(section[i])) i++;
+    if (i >= n) {
+      // Malformed: attribute with '=' and no value. Treat as boolean.
+      attrs.push({ name });
+      break;
+    }
+
+    // Read value — quoted or unquoted
+    const vc = section[i];
+    if (vc === '"' || vc === "'") {
+      const quote = vc as '"' | "'";
+      i++; // skip opening quote
+      const valStart = i;
+      while (i < n && section[i] !== quote) i++;
+      const value = section.slice(valStart, i);
+      if (i < n) i++; // skip closing quote
+      attrs.push({ name, value, quote });
+    } else {
+      // Unquoted value — run until whitespace or '/' or '>'
+      const valStart = i;
+      while (i < n && !/[\s/>]/.test(section[i])) i++;
+      const value = section.slice(valStart, i);
+      attrs.push({ name, value });
+    }
+  }
+
+  return attrs;
+}
+
+/** Apply HTML→JSX name rewrite and, for `style`, value conversion. */
+function renameAttribute(attr: Attribute): Attribute {
+  const lower = attr.name.toLowerCase();
+  const newName = ATTRIBUTE_RENAMES[lower] ?? attr.name;
+
+  if (lower === 'style' && attr.value !== undefined) {
+    return { name: newName, value: cssStringToJsxObject(attr.value), quote: undefined };
+  }
+
+  return { ...attr, name: newName };
+}
+
+/**
+ * Serialise a list of attributes back into source form. Preserves the
+ * original quote style. A value of `{{ ... }}` (already a JSX object
+ * expression) is emitted unquoted (no surrounding `"`); it's already
+ * valid JSX syntax.
+ */
+function serializeAttributes(attrs: Attribute[]): string {
+  if (attrs.length === 0) return '';
+  const parts = attrs.map(attr => {
+    if (attr.value === undefined) return ` ${attr.name}`;
+    if (attr.value.startsWith('{{') && attr.value.endsWith('}}')) {
+      // JSX expression like {{ color: 'red' }} — no quotes.
+      return ` ${attr.name}=${attr.value}`;
+    }
+    const q = attr.quote ?? '"';
+    return ` ${attr.name}=${q}${attr.value}${q}`;
+  });
+  return parts.join('');
+}
+
+// ──────────────────────────────────────────────────────────────────────
+// CSS → JSX style object
+// ──────────────────────────────────────────────────────────────────────
+
+function cssStringToJsxObject(css: string): string {
+  const declarations = css
+    .split(';')
+    .map(d => d.trim())
+    .filter(d => d.length > 0);
+
+  if (declarations.length === 0) return '{{}}';
+
+  const entries = declarations
+    .map(decl => {
+      const colonIdx = decl.indexOf(':');
+      if (colonIdx === -1) return null;
+      const prop = decl.slice(0, colonIdx).trim();
+      const value = decl.slice(colonIdx + 1).trim();
+      const camelProp = prop.replace(/-([a-z])/g, (_m, c) => c.toUpperCase());
+      const escapedValue = value.replace(/'/g, "\\'");
+      return `${camelProp}: '${escapedValue}'`;
+    })
+    .filter((e): e is string => e !== null);
+
+  return `{{ ${entries.join(', ')} }}`;
+}