@specverse/engine-realize 3.5.3

package/libs/instance-factories/views/templates/react/react-component-generator.ts

@@ -0,0 +1,533 @@
+/**
+ * React Component Generator
+ *
+ * Extends BaseComponentGenerator to generate React/TypeScript components.
+ * Outputs .tsx files with proper imports, hooks, types, and JSX.
+ *
+ * Features:
+ * - TypeScript with strict typing
+ * - React hooks (useState, useEffect)
+ * - JSX component rendering
+ * - Adapter integration (shadcn, MUI, antd)
+ * - Proper file structure and exports
+ */
+
+import {
+  BaseComponentGenerator,
+  ViewSpec,
+  StateDefinition,
+  EventDefinition,
+  GeneratorConfig
+} from '../shared/base-generator.js';
+import { getSyntaxPattern } from '../shared/syntax-mapper.js';
+import { extractComponentTypes } from '../shared/base-generator.js';
+import type { ComponentAdapter } from '../shared/adapter-types.js';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * React-specific generator configuration
+ */
+export interface ReactGeneratorConfig extends GeneratorConfig {
+  framework: 'react';
+  target: 'shadcn' | 'mui' | 'antd';
+  typescript: boolean;
+  strictMode?: boolean;
+  includeComments?: boolean;
+}
+
+/**
+ * React component props interface
+ */
+export interface ReactComponentProps {
+  [key: string]: any;
+}
+
+// ============================================================================
+// React Component Generator
+// ============================================================================
+
+/**
+ * Generates React/TypeScript components from SpecVerse view specifications
+ *
+ * Output structure:
+ * ```tsx
+ * import React, { useState, useEffect } from 'react';
+ * import { Button } from '@/components/ui/button';
+ *
+ * interface {ComponentName}Props {
+ *   // ... props
+ * }
+ *
+ * export function {ComponentName}({ ...props }: {ComponentName}Props) {
+ *   // State declarations
+ *   const [count, setCount] = useState(0);
+ *
+ *   // Event handlers
+ *   const handleClick = () => { ... };
+ *
+ *   // Component tree
+ *   return (
+ *     <div>
+ *       <Button onClick={handleClick}>Click me</Button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export class ReactComponentGenerator extends BaseComponentGenerator {
+  private readonly reactConfig: ReactGeneratorConfig;
+
+  constructor(adapter: ComponentAdapter, config: ReactGeneratorConfig) {
+    super(adapter, config);
+    this.reactConfig = config;
+  }
+
+  // ============================================================================
+  // Abstract Method Implementations
+  // ============================================================================
+
+  /**
+   * Generate React imports
+   */
+  protected generateImports(viewSpec: ViewSpec): string {
+    const imports: string[] = [];
+
+    // React core imports
+    const reactImports = this.getReactCoreImports(viewSpec);
+    if (reactImports) {
+      imports.push(reactImports);
+    }
+
+    // Component library imports
+    const componentTypes = extractComponentTypes(viewSpec.components);
+    const componentImports = this.getComponentImports(componentTypes);
+    imports.push(...componentImports);
+
+    return imports.join('\n');
+  }
+
+  /**
+   * Generate complete React component
+   */
+  protected generateComponent(parts: {
+    name: string;
+    imports: string;
+    state: string;
+    events: string;
+    components: string;
+  }): string {
+    const lines: string[] = [];
+
+    // File header comment
+    if (this.reactConfig.includeComments) {
+      lines.push(`/**`);
+      lines.push(` * ${parts.name} Component`);
+      lines.push(` * Generated by SpecVerse`);
+      lines.push(` */`);
+      lines.push('');
+    }
+
+    // Imports
+    lines.push(parts.imports);
+    lines.push('');
+
+    // Props interface
+    const propsInterface = this.generatePropsInterface(parts.name);
+    if (propsInterface) {
+      lines.push(propsInterface);
+      lines.push('');
+    }
+
+    // Component function
+    lines.push(this.generateComponentFunction(parts));
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Generate state declarations using React hooks
+   */
+  protected generateState(state: Record<string, StateDefinition>): string {
+    const stateDeclarations: string[] = [];
+
+    for (const [name, def] of Object.entries(state)) {
+      const declaration = getSyntaxPattern('stateDeclaration', 'react', {
+        name,
+        Name: this.capitalize(name),
+        type: def.type,
+        initial: JSON.stringify(def.initial)
+      });
+
+      if (this.reactConfig.includeComments && def.description) {
+        stateDeclarations.push(`  // ${def.description}`);
+      }
+
+      stateDeclarations.push(`  ${declaration}`);
+    }
+
+    return stateDeclarations.join('\n');
+  }
+
+  /**
+   * Generate event handlers
+   */
+  protected generateEvents(events: Record<string, EventDefinition>): string {
+    const eventHandlers: string[] = [];
+
+    for (const [name, def] of Object.entries(events)) {
+      const handler = getSyntaxPattern('eventHandler', 'react', {
+        Name: this.capitalize(name),
+        params: def.params || '',
+        body: def.body
+      });
+
+      if (this.reactConfig.includeComments && def.description) {
+        eventHandlers.push(`  // ${def.description}`);
+      }
+
+      eventHandlers.push(`  ${handler}`);
+    }
+
+    return eventHandlers.join('\n\n');
+  }
+
+  /**
+   * Get file extension (.tsx for React/TypeScript)
+   */
+  public getFileExtension(): string {
+    return this.reactConfig.typescript ? '.tsx' : '.jsx';
+  }
+
+  /**
+   * Get additional files (styles, types, etc.)
+   */
+  public getAdditionalFiles(viewSpec: ViewSpec): Record<string, string> {
+    const files: Record<string, string> = {};
+
+    // Optional: Generate separate types file
+    if (this.reactConfig.typescript && this.reactConfig.strictMode) {
+      files[`${viewSpec.name}.types.ts`] = this.generateTypesFile(viewSpec);
+    }
+
+    return files;
+  }
+
+  // ============================================================================
+  // React-Specific Helper Methods
+  // ============================================================================
+
+  /**
+   * Get React core imports (useState, useEffect, etc.)
+   */
+  private getReactCoreImports(viewSpec: ViewSpec): string {
+    const hooks: string[] = [];
+
+    // Add useState if component has state
+    if (viewSpec.state && Object.keys(viewSpec.state).length > 0) {
+      hooks.push('useState');
+    }
+
+    // Add useEffect if needed (detect lifecycle needs)
+    // For now, simplified - could be enhanced based on view spec analysis
+    if (this.needsUseEffect(viewSpec)) {
+      hooks.push('useEffect');
+    }
+
+    if (hooks.length > 0) {
+      // Generate: import React, { useState, useEffect } from 'react';
+      return `import React, { ${hooks.join(', ')} } from 'react';`;
+    }
+
+    return `import React from 'react';`;
+  }
+
+  /**
+   * Get component library imports
+   */
+  private getComponentImports(componentTypes: Set<string>): string[] {
+    const imports: string[] = [];
+    const importMap: Map<string, string[]> = new Map();
+
+    // Group components by their import source
+    for (const type of componentTypes) {
+      const adapterComponent = this.adapter.components[type];
+      if (adapterComponent && adapterComponent.import) {
+        // Parse import to group by source
+        const importMatch = adapterComponent.import.match(/from ['"](.+)['"]/);
+        if (importMatch) {
+          const source = importMatch[1];
+          const componentMatch = adapterComponent.import.match(/import \{ (.+) \}/);
+          if (componentMatch) {
+            const componentName = componentMatch[1];
+            if (!importMap.has(source)) {
+              importMap.set(source, []);
+            }
+            importMap.get(source)!.push(componentName);
+          }
+        }
+      }
+    }
+
+    // Generate grouped imports
+    for (const [source, components] of importMap) {
+      imports.push(getSyntaxPattern('libraryImport', 'react', {
+        exports: components.join(', '),
+        library: source
+      }));
+    }
+
+    return imports;
+  }
+
+  /**
+   * Generate props interface for TypeScript
+   */
+  private generatePropsInterface(componentName: string): string | null {
+    if (!this.reactConfig.typescript) {
+      return null;
+    }
+
+    // For now, generate empty interface (can be enhanced based on view spec)
+    const lines: string[] = [];
+
+    if (this.reactConfig.includeComments) {
+      lines.push(`/**`);
+      lines.push(` * Props for ${componentName} component`);
+      lines.push(` */`);
+    }
+
+    lines.push(`interface ${componentName}Props {`);
+    lines.push(`  // Component props will be added here`);
+    lines.push(`}`);
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Generate main component function
+   */
+  private generateComponentFunction(parts: {
+    name: string;
+    state: string;
+    events: string;
+    components: string;
+  }): string {
+    const lines: string[] = [];
+
+    // Function signature
+    const propsParam = this.reactConfig.typescript
+      ? `props: ${parts.name}Props`
+      : 'props';
+
+    lines.push(`export function ${parts.name}(${propsParam}) {`);
+
+    // State declarations
+    if (parts.state) {
+      lines.push(parts.state);
+      lines.push('');
+    }
+
+    // Event handlers
+    if (parts.events) {
+      lines.push(parts.events);
+      lines.push('');
+    }
+
+    // Return JSX
+    lines.push('  return (');
+    lines.push('    <div className="specverse-view">');
+
+    // Indent component tree
+    const indentedComponents = parts.components
+      .split('\n')
+      .map(line => line ? `      ${line}` : '')
+      .join('\n');
+
+    lines.push(indentedComponents);
+    lines.push('    </div>');
+    lines.push('  );');
+    lines.push('}');
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Generate separate types file
+   */
+  private generateTypesFile(viewSpec: ViewSpec): string {
+    const lines: string[] = [];
+
+    lines.push(`/**`);
+    lines.push(` * Type definitions for ${viewSpec.name}`);
+    lines.push(` * Generated by SpecVerse`);
+    lines.push(` */`);
+    lines.push('');
+
+    // State types
+    if (viewSpec.state) {
+      lines.push(`export interface ${viewSpec.name}State {`);
+      for (const [name, def] of Object.entries(viewSpec.state)) {
+        if (def.description) {
+          lines.push(`  /** ${def.description} */`);
+        }
+        lines.push(`  ${name}: ${def.type};`);
+      }
+      lines.push(`}`);
+      lines.push('');
+    }
+
+    // Event handler types
+    if (viewSpec.events) {
+      for (const [name, def] of Object.entries(viewSpec.events)) {
+        const handlerName = `${this.capitalize(name)}Handler`;
+        const params = def.params || '';
+
+        if (def.description) {
+          lines.push(`/** ${def.description} */`);
+        }
+
+        lines.push(`export type ${handlerName} = (${params}) => void;`);
+        lines.push('');
+      }
+    }
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Check if component needs useEffect hook
+   */
+  private needsUseEffect(viewSpec: ViewSpec): boolean {
+    // Simplified heuristic - could be enhanced
+    // Check if any event has mount/unmount keywords
+    if (viewSpec.events) {
+      const eventNames = Object.keys(viewSpec.events).map(e => e.toLowerCase());
+      return eventNames.some(name =>
+        name.includes('mount') ||
+        name.includes('init') ||
+        name.includes('load')
+      );
+    }
+    return false;
+  }
+
+  /**
+   * Capitalize first letter of string
+   */
+  private capitalize(str: string): string {
+    return str.charAt(0).toUpperCase() + str.slice(1);
+  }
+
+  // ============================================================================
+  // React-Specific Component Rendering
+  // ============================================================================
+
+  /**
+   * Override to add React-specific rendering hints
+   */
+  protected renderAdapterComponent(
+    type: string,
+    properties: Record<string, any>,
+    children: string | undefined,
+    context: any
+  ): string {
+    // Add React-specific className if not present
+    if (!properties.className && type !== 'container') {
+      properties.className = `specverse-${type}`;
+    }
+
+    // Call parent implementation
+    return super.renderAdapterComponent(type, properties, children, context);
+  }
+}
+
+// ============================================================================
+// Factory Function
+// ============================================================================
+
+/**
+ * Create a ReactComponentGenerator instance
+ *
+ * @param adapter - Component adapter (shadcn, mui, antd)
+ * @param config - Generator configuration
+ * @returns ReactComponentGenerator instance
+ */
+export function createReactGenerator(
+  adapter: ComponentAdapter,
+  config?: Partial<ReactGeneratorConfig>
+): ReactComponentGenerator {
+  const defaultConfig: ReactGeneratorConfig = {
+    framework: 'react',
+    target: 'shadcn',
+    typescript: true,
+    strictMode: false,
+    includeComments: true,
+    maxDepth: 3,
+    enableWarnings: true
+  };
+
+  const finalConfig = { ...defaultConfig, ...config } as ReactGeneratorConfig;
+
+  return new ReactComponentGenerator(adapter, finalConfig);
+}
+
+// ============================================================================
+// Convenience Functions
+// ============================================================================
+
+/**
+ * Generate React component from view spec (one-liner)
+ *
+ * @param viewSpec - View specification
+ * @param adapter - Component adapter
+ * @param options - Optional configuration
+ * @returns Generated component code
+ */
+export function generateReactComponent(
+  viewSpec: ViewSpec,
+  adapter: ComponentAdapter,
+  options?: Partial<ReactGeneratorConfig>
+): string {
+  const generator = createReactGenerator(adapter, options);
+  const result = generator.generate(viewSpec);
+
+  if (result.warnings.length > 0) {
+    console.warn('Generation warnings:', result.warnings);
+  }
+
+  return result.code;
+}
+
+/**
+ * Generate React component with all additional files
+ *
+ * @param viewSpec - View specification
+ * @param adapter - Component adapter
+ * @param options - Optional configuration
+ * @returns Map of filename to content
+ */
+export function generateReactComponentFiles(
+  viewSpec: ViewSpec,
+  adapter: ComponentAdapter,
+  options?: Partial<ReactGeneratorConfig>
+): Map<string, string> {
+  const generator = createReactGenerator(adapter, options);
+  const result = generator.generate(viewSpec);
+
+  const files = new Map<string, string>();
+
+  // Main component file
+  const ext = generator.getFileExtension();
+  files.set(`${viewSpec.name}${ext}`, result.code);
+
+  // Additional files (types, styles, etc.)
+  const additionalFiles = generator.getAdditionalFiles(viewSpec);
+  for (const [filename, content] of Object.entries(additionalFiles)) {
+    files.set(filename, content);
+  }
+
+  return files;
+}