@specverse/engines 4.1.5 → 4.1.7

package/dist/libs/instance-factories/views/templates/react/shared-utils-generator.js

@@ -0,0 +1,179 @@
+function generateSharedUtils(context) {
+  const files = [
+    { path: "field-helpers.ts", content: generateFieldHelpers() },
+    { path: "view-helpers.tsx", content: generateViewHelpers() }
+  ];
+  return { files };
+}
+function generateFieldHelpers() {
+  return `/**
+ * Field Helpers \u2014 shared utilities for field classification and display
+ * Generated by SpecVerse React factory
+ */
+
+const METADATA_FIELDS = new Set([
+  'id', 'createdAt', 'updatedAt', 'createdBy', 'updatedBy', 'deletedAt', 'version'
+]);
+
+const AUTO_PATTERNS = new Set(['now', 'uuid4', 'autoincrement', 'auto']);
+
+/**
+ * Check if a field is auto-generated (should be hidden from forms)
+ */
+export function isAutoField(name: string, attr: any): boolean {
+  if (attr?.auto && AUTO_PATTERNS.has(attr.auto)) return true;
+  if (name === 'id') return true;
+  if (METADATA_FIELDS.has(name) && attr?.type?.toLowerCase().includes('date')) return true;
+  return false;
+}
+
+/**
+ * Check if a field is metadata (shown last, styled muted)
+ */
+export function isMetadataField(name: string): boolean {
+  return METADATA_FIELDS.has(name);
+}
+
+/**
+ * Get the best display name for an entity
+ * Searches common name fields in priority order
+ */
+export function getEntityDisplayName(entity: any): string {
+  if (!entity) return 'Unknown';
+  for (const field of ['name', 'title', 'displayName', 'label', 'username', 'email', 'subject']) {
+    if (entity[field]) return String(entity[field]);
+  }
+  return entity.id ? String(entity.id).slice(0, 8) + '...' : 'Unknown';
+}
+
+/**
+ * Classify attributes into ordered groups for display
+ */
+export function classifyFields(attributes: Array<{ name: string; type: string; auto?: string; required?: boolean }>): {
+  business: typeof attributes;
+  lifecycle: typeof attributes;
+  metadata: typeof attributes;
+} {
+  const business: typeof attributes = [];
+  const lifecycle: typeof attributes = [];
+  const metadata: typeof attributes = [];
+
+  for (const attr of attributes) {
+    if (isAutoField(attr.name, attr) || isMetadataField(attr.name)) {
+      metadata.push(attr);
+    } else if (attr.name === 'status' || attr.name === 'state' || attr.name === 'phase') {
+      lifecycle.push(attr);
+    } else {
+      business.push(attr);
+    }
+  }
+
+  return { business, lifecycle, metadata };
+}
+`;
+}
+function generateViewHelpers() {
+  return `/**
+ * View Helpers \u2014 formatting, colors, and UI utilities
+ * Generated by SpecVerse React factory
+ */
+
+/**
+ * Format a value for display
+ */
+export function formatValue(value: any, type?: string): string {
+  if (value === null || value === undefined) return '\u2014';
+  if (type?.toLowerCase().includes('date') || type?.toLowerCase().includes('timestamp')) {
+    return formatDate(value);
+  }
+  if (typeof value === 'boolean') return value ? 'Yes' : 'No';
+  return String(value);
+}
+
+/**
+ * Format a date for display (relative for recent, absolute for old)
+ */
+export function formatDate(value: any): string {
+  if (!value) return '\u2014';
+  const date = new Date(value);
+  if (isNaN(date.getTime())) return String(value);
+
+  const now = new Date();
+  const diff = now.getTime() - date.getTime();
+  const minutes = Math.floor(diff / 60000);
+  const hours = Math.floor(diff / 3600000);
+  const days = Math.floor(diff / 86400000);
+
+  if (minutes < 1) return 'just now';
+  if (minutes < 60) return \`\${minutes}m ago\`;
+  if (hours < 24) return \`\${hours}h ago\`;
+  if (days < 7) return \`\${days}d ago\`;
+  return date.toLocaleDateString();
+}
+
+/**
+ * Truncate text with ellipsis
+ */
+export function truncate(text: string, max: number = 60): string {
+  if (!text || text.length <= max) return text;
+  return text.slice(0, max) + '...';
+}
+
+/**
+ * Get a Tailwind color class for a lifecycle status
+ */
+export function statusColor(status: string): { bg: string; text: string; dot: string } {
+  const s = status?.toLowerCase().replace(/[_-]/g, '') || '';
+
+  // Green states
+  if (['active', 'done', 'completed', 'approved', 'published', 'resolved'].includes(s)) {
+    return { bg: 'bg-green-50', text: 'text-green-700', dot: 'bg-green-500' };
+  }
+  // Blue states
+  if (['inprogress', 'processing', 'review', 'pending'].includes(s)) {
+    return { bg: 'bg-blue-50', text: 'text-blue-700', dot: 'bg-blue-500' };
+  }
+  // Yellow states
+  if (['draft', 'todo', 'planning', 'waiting', 'scheduled'].includes(s)) {
+    return { bg: 'bg-yellow-50', text: 'text-yellow-700', dot: 'bg-yellow-500' };
+  }
+  // Red states
+  if (['cancelled', 'rejected', 'failed', 'overdue', 'blocked'].includes(s)) {
+    return { bg: 'bg-red-50', text: 'text-red-700', dot: 'bg-red-500' };
+  }
+  // Gray states
+  if (['archived', 'closed', 'deprecated', 'inactive', 'disabled'].includes(s)) {
+    return { bg: 'bg-gray-50', text: 'text-gray-500', dot: 'bg-gray-400' };
+  }
+  // Default: indigo
+  return { bg: 'bg-indigo-50', text: 'text-indigo-700', dot: 'bg-indigo-500' };
+}
+
+/**
+ * StatusBadge component \u2014 matches app-demo's lifecycle badge styling
+ */
+export function StatusBadge({ status, variant = 'default' }: { status: string; variant?: 'default' | 'lifecycle' }) {
+  if (!status) return null;
+
+  // Lifecycle badges use purple (matching app-demo)
+  if (variant === 'lifecycle') {
+    return (
+      <span className="px-2 py-1 bg-purple-100 text-purple-700 rounded text-xs font-medium">
+        {status.replace(/[_-]/g, ' ')}
+      </span>
+    );
+  }
+
+  const colors = statusColor(status);
+  return (
+    <span className={\`inline-flex items-center gap-1.5 px-2 py-1 rounded text-xs font-medium \${colors.bg} \${colors.text}\`}>
+      <span className={\`w-1.5 h-1.5 rounded-full \${colors.dot}\`}></span>
+      {status.replace(/[_-]/g, ' ')}
+    </span>
+  );
+}
+`;
+}
+export {
+  generateSharedUtils as default
+};

package/dist/libs/instance-factories/views/templates/react/spec-json-generator.js

@@ -0,0 +1,7 @@
+function generateSpecJson(context) {
+  const { spec } = context;
+  return JSON.stringify(spec, null, 2);
+}
+export {
+  generateSpecJson as default
+};

package/dist/libs/instance-factories/views/templates/react/types-generator.js

@@ -0,0 +1,56 @@
+function generateModelTypes(context) {
+  const { model } = context;
+  if (!model) {
+    throw new Error("Model is required in template context");
+  }
+  const modelName = model.name;
+  let attributes = model.attributes || {};
+  if (Array.isArray(attributes)) {
+    const obj = {};
+    attributes.forEach((attr) => {
+      if (attr && typeof attr === "object" && attr.name) {
+        obj[attr.name] = attr;
+      } else if (Array.isArray(attr) && attr.length >= 2) {
+        obj[attr[0]] = attr[1];
+      }
+    });
+    attributes = obj;
+  }
+  const properties = Object.entries(attributes).map(([name, attr]) => {
+    const tsType = mapToTypeScript(attr.type);
+    const optional = !attr.constraints?.required ? "?" : "";
+    return `  ${name}${optional}: ${tsType};`;
+  }).join("\n");
+  return `/**
+ * ${modelName} Type Definition
+ * Auto-generated from SpecVerse model
+ */
+
+export interface ${modelName} {
+${properties}
+}
+
+export type Create${modelName}Input = Omit<${modelName}, 'id' | 'createdAt' | 'updatedAt'>;
+export type Update${modelName}Input = Partial<Create${modelName}Input>;
+`;
+}
+function mapToTypeScript(type) {
+  const typeMap = {
+    "String": "string",
+    "Integer": "number",
+    "Float": "number",
+    "Boolean": "boolean",
+    "Date": "string",
+    "DateTime": "string",
+    "Timestamp": "string",
+    "UUID": "string",
+    "Email": "string",
+    "URL": "string",
+    "JSON": "Record<string, any>",
+    "Array": "any[]"
+  };
+  return typeMap[type] || "any";
+}
+export {
+  generateModelTypes as default
+};

package/dist/libs/instance-factories/views/templates/react/views-metadata-generator.js

@@ -0,0 +1,27 @@
+function generateViewsMetadata(context) {
+  const { spec, views = [] } = context;
+  const specViews = views.length > 0 ? views : spec?.views || [];
+  const viewsArray = Array.isArray(specViews) ? specViews : Object.values(specViews);
+  const metadata = {};
+  viewsArray.forEach((viewDef) => {
+    const viewName = viewDef.name;
+    metadata[viewName] = {
+      name: viewName,
+      type: viewDef.type || "list",
+      ...viewDef.description && { description: viewDef.description },
+      model: viewDef.model,
+      // Keep as-is (string or array for multi-model views)
+      ...viewDef.uiComponents && { uiComponents: viewDef.uiComponents },
+      ...viewDef.subscriptions && viewDef.subscriptions.length > 0 && {
+        subscriptions: viewDef.subscriptions
+      },
+      routing: viewDef.routing || {
+        path: `/${viewName.toLowerCase().replace(/view$/, "")}`
+      }
+    };
+  });
+  return JSON.stringify(metadata, null, 2);
+}
+export {
+  generateViewsMetadata as default
+};

package/dist/libs/instance-factories/views/templates/react/vite-config-generator.js

@@ -0,0 +1,29 @@
+function generateViteConfig(context) {
+  const { backendPort = 3e3 } = context;
+  return `import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+
+// https://vitejs.dev/config/
+export default defineConfig({
+  plugins: [react()],
+  server: {
+    port: 5173,
+    host: true,
+    proxy: {
+      '/api': {
+        target: 'http://localhost:${backendPort}',
+        changeOrigin: true,
+        rewrite: (path) => path
+      }
+    }
+  },
+  build: {
+    outDir: 'dist',
+    sourcemap: true
+  }
+});
+`;
+}
+export {
+  generateViteConfig as default
+};

package/dist/libs/instance-factories/views/templates/runtime/runtime-view-renderer.js

@@ -0,0 +1,261 @@
+import React, { createElement, useState, useMemo } from "react";
+import {
+  BaseComponentGenerator
+} from "../shared/base-generator.js";
+import { mapProperties } from "../shared/property-mapper.js";
+import { getComponentMetadata } from "../shared/component-metadata.js";
+class RuntimeViewRenderer extends BaseComponentGenerator {
+  runtimeConfig;
+  viewContext;
+  constructor(adapter, config) {
+    super(adapter, config);
+    this.runtimeConfig = config;
+  }
+  // ============================================================================
+  // Public API - Runtime Rendering
+  // ============================================================================
+  /**
+   * Render view as React element (runtime)
+   *
+   * @param viewSpec - View specification
+   * @param context - Runtime context (state, data, handlers)
+   * @returns React element
+   */
+  renderRuntime(viewSpec, context) {
+    this.viewContext = this.initializeContext(viewSpec, context);
+    const components = this.renderComponentsRuntime(viewSpec.components);
+    return createElement(
+      "div",
+      { className: "specverse-runtime-view", "data-view": viewSpec.name },
+      components
+    );
+  }
+  /**
+   * Create a React component from view spec
+   *
+   * Returns a React component function that can be used directly
+   *
+   * @param viewSpec - View specification
+   * @returns React component function
+   */
+  createRuntimeComponent(viewSpec) {
+    const renderer = this;
+    return function RuntimeViewComponent(props) {
+      const [state, setState] = useState(
+        () => renderer.initializeState(viewSpec.state)
+      );
+      const handlers = useMemo(
+        () => renderer.createEventHandlers(viewSpec.events, state, setState),
+        [state]
+      );
+      const context = {
+        state,
+        setState: (updates) => setState((prev) => ({ ...prev, ...updates })),
+        handlers,
+        data: props.data || {}
+      };
+      return renderer.renderRuntime(viewSpec, context);
+    };
+  }
+  // ============================================================================
+  // Abstract Method Implementations (Not Used in Runtime)
+  // ============================================================================
+  generateImports(viewSpec) {
+    return "";
+  }
+  generateComponent(parts) {
+    return "";
+  }
+  generateState(state) {
+    return "";
+  }
+  generateEvents(events) {
+    return "";
+  }
+  getFileExtension() {
+    return "";
+  }
+  getAdditionalFiles(viewSpec) {
+    return {};
+  }
+  // ============================================================================
+  // Runtime-Specific Methods
+  // ============================================================================
+  /**
+   * Initialize runtime context
+   */
+  initializeContext(viewSpec, context) {
+    return {
+      state: context?.state || this.initializeState(viewSpec.state),
+      setState: context?.setState || (() => {
+      }),
+      handlers: context?.handlers || this.createEventHandlers(viewSpec.events),
+      data: context?.data || {}
+    };
+  }
+  /**
+   * Initialize state from view spec
+   */
+  initializeState(state) {
+    if (!state) return {};
+    const initialState = {};
+    for (const [name, def] of Object.entries(state)) {
+      initialState[name] = def.initial;
+    }
+    return initialState;
+  }
+  /**
+   * Create event handlers from view spec
+   */
+  createEventHandlers(events, state, setState) {
+    if (!events) return {};
+    const handlers = {};
+    for (const [name, def] of Object.entries(events)) {
+      handlers[`handle${this.capitalize(name)}`] = (...args) => {
+        if (this.runtimeConfig.debug) {
+          console.log(`[RuntimeView] Event: ${name}`, args);
+        }
+        try {
+          const fn = new Function("state", "setState", "args", def.body);
+          fn(state, setState, args);
+        } catch (error) {
+          console.error(`[RuntimeView] Event handler error (${name}):`, error);
+        }
+      };
+    }
+    return handlers;
+  }
+  /**
+   * Render components as React elements
+   */
+  renderComponentsRuntime(components) {
+    return Object.entries(components).map(
+      ([name, component]) => this.renderComponentRuntime(component, {
+        depth: 0,
+        path: [name]
+      })
+    );
+  }
+  /**
+   * Render single component as React element
+   */
+  renderComponentRuntime(component, context) {
+    if (context.depth > this.MAX_DEPTH) {
+      if (this.runtimeConfig.debug) {
+        console.warn(`[RuntimeView] Max depth exceeded at ${context.path.join(".")}`);
+      }
+      return null;
+    }
+    const metadata = getComponentMetadata(component.type);
+    if (!metadata) {
+      console.warn(`[RuntimeView] Unknown component type: ${component.type}`);
+      return null;
+    }
+    const mappedProps = component.properties ? mapProperties(component.type, component.properties, "runtime") : {};
+    const props = {
+      ...mappedProps,
+      key: context.path.join("-")
+    };
+    if (component.condition && this.viewContext) {
+      const condition = this.evaluateCondition(component.condition, this.viewContext);
+      if (!condition) return null;
+    }
+    if (component.dataSource && this.viewContext) {
+      return this.renderListRuntime(component, props, context);
+    }
+    let children = null;
+    if (component.children && component.children.length > 0) {
+      children = component.children.map(
+        (child, index) => this.renderComponentRuntime(child, {
+          ...context,
+          depth: context.depth + 1,
+          path: [...context.path, `child_${index}`]
+        })
+      );
+    }
+    const adapterComponent = this.adapter.components[component.type];
+    if (!adapterComponent) {
+      console.warn(`[RuntimeView] No adapter for component: ${component.type}`);
+      return null;
+    }
+    return this.createElementFromAdapter(component.type, props, children);
+  }
+  /**
+   * Render list of items
+   */
+  renderListRuntime(component, props, context) {
+    if (!this.viewContext) return null;
+    const dataArray = this.viewContext.data[component.dataSource];
+    if (!Array.isArray(dataArray)) {
+      console.warn(`[RuntimeView] Data source not found: ${component.dataSource}`);
+      return null;
+    }
+    const items = dataArray.map((item, index) => {
+      const itemProps = {
+        ...props,
+        ...item,
+        key: `${context.path.join("-")}-${index}`
+      };
+      return this.createElementFromAdapter(component.type, itemProps, null);
+    });
+    return createElement(React.Fragment, null, ...items);
+  }
+  /**
+   * Create React element from adapter component
+   */
+  createElementFromAdapter(type, props, children) {
+    return createElement(
+      "div",
+      {
+        ...props,
+        className: `specverse-runtime-${type} ${props.className || ""}`.trim(),
+        "data-component": type
+      },
+      children
+    );
+  }
+  /**
+   * Evaluate condition expression
+   */
+  evaluateCondition(condition, context) {
+    try {
+      const fn = new Function("state", "data", `return ${condition}`);
+      return fn(context.state, context.data);
+    } catch (error) {
+      console.error(`[RuntimeView] Condition evaluation error:`, error);
+      return false;
+    }
+  }
+  /**
+   * Capitalize first letter
+   */
+  capitalize(str) {
+    return str.charAt(0).toUpperCase() + str.slice(1);
+  }
+}
+function createRuntimeRenderer(adapter, config) {
+  const defaultConfig = {
+    framework: "runtime",
+    target: "runtime",
+    liveReload: false,
+    debug: false,
+    maxDepth: 3,
+    enableWarnings: true
+  };
+  const finalConfig = { ...defaultConfig, ...config };
+  return new RuntimeViewRenderer(adapter, finalConfig);
+}
+function renderView(viewSpec, adapter, context) {
+  const renderer = createRuntimeRenderer(adapter);
+  return renderer.renderRuntime(viewSpec, context);
+}
+function createViewComponent(viewSpec, adapter) {
+  const renderer = createRuntimeRenderer(adapter);
+  return renderer.createRuntimeComponent(viewSpec);
+}
+export {
+  RuntimeViewRenderer,
+  createRuntimeRenderer,
+  createViewComponent,
+  renderView
+};

package/dist/libs/instance-factories/views/templates/shared/adapter-types.js

@@ -0,0 +1,34 @@
+function renderProps(props) {
+  return Object.entries(props).filter(([_, value]) => value !== void 0 && value !== null).map(([key, value]) => {
+    if (typeof value === "boolean") {
+      return value ? key : "";
+    }
+    if (typeof value === "string") {
+      return `${key}="${value}"`;
+    }
+    if (typeof value === "number") {
+      return `${key}={${value}}`;
+    }
+    if (Array.isArray(value)) {
+      return `${key}={${JSON.stringify(value)}}`;
+    }
+    if (typeof value === "object") {
+      return `${key}={${JSON.stringify(value)}}`;
+    }
+    return `${key}={${value}}`;
+  }).filter(Boolean).join(" ");
+}
+function indent(code, level = 0) {
+  const spaces = "  ".repeat(level);
+  return code.split("\n").map((line) => line ? spaces + line : line).join("\n");
+}
+function wrapWithChildren(openTag, children, closeTag, indentLevel = 0) {
+  return `${openTag}
+${indent(children, indentLevel + 1)}
+${indent(closeTag, indentLevel)}`;
+}
+export {
+  indent,
+  renderProps,
+  wrapWithChildren
+};