@ooopenlab/quiz-shared/src/component-injection-types.ts

Shared utilities and components for SuperQuiz modules

/**
 * Component Injection Types and Interfaces
 * 
 * This file defines the standard types and interfaces for the Component Injection
 * workflow in OOOPEN Lab. These types ensure consistency between AI-generated
 * components and the standard module containers.
 */

import { ComponentType as ReactComponentType, ReactNode } from 'react';

// Use React's ComponentType for consistency
type ComponentType<P = {}> = ReactComponentType<P>;

/**
 * Standard Props interface that all AI-generated components must implement
 */
export interface InjectedComponentProps {
  /** Callback function called when the component interaction is complete */
  onComplete: (result: InjectionResult) => void;
  
  /** Configuration parameters specific to the component */
  config: Record<string, any>;
  
  /** Optional theme setting */
  theme?: 'light' | 'dark' | string;
  
  /** Optional internationalization context */
  i18n?: any;
  
  /** Whether the component should be disabled */
  disabled?: boolean;
  
  /** Enable debug mode for development */
  debug?: boolean;
}

/**
 * Standard result format that injected components should return via onComplete
 */
export interface InjectionResult {
  /** Type identifier for the result */
  type: string;
  
  /** The actual result data */
  data: any;
  
  /** Timestamp when the interaction was completed */
  timestamp: number;
  
  /** Optional metadata about the interaction */
  metadata?: InjectionMetadata;
}

/**
 * Optional metadata that can be included with injection results
 */
export interface InjectionMetadata {
  /** Duration of the interaction in milliseconds */
  duration?: number;
  
  /** Number of user interactions */
  interactions?: number;
  
  /** Error information if any occurred */
  errors?: Array<{
    type: string;
    message: string;
    timestamp: number;
  }>;
  
  /** Custom tracking data */
  custom?: Record<string, any>;
}

/**
 * Configuration interface for modules that support component injection
 */
export interface ComponentInjectionConfig {
  /** Whether this module supports component injection */
  supportsInjection: boolean;
  
  /** Allowed injection component types */
  allowedComponentTypes?: string[];
  
  /** Configuration schema for injected components */
  injectionSchema?: ComponentInjectionSchema;
  
  /** Validation rules for injection results */
  resultValidation?: InjectionResultValidation;
}

/**
 * Schema definition for component injection configuration
 */
export interface ComponentInjectionSchema {
  /** Required configuration fields */
  required: string[];
  
  /** Optional configuration fields */
  optional?: string[];
  
  /** Field type definitions */
  fieldTypes: Record<string, 'string' | 'number' | 'boolean' | 'object' | 'array'>;
  
  /** Default values for optional fields */
  defaults?: Record<string, any>;
}

/**
 * Validation rules for injection results
 */
export interface InjectionResultValidation {
  /** Required fields in the result data */
  requiredFields: string[];
  
  /** Optional fields in the result data */
  optionalFields?: string[];
  
  /** Type validation for result fields */
  fieldTypes: Record<string, 'string' | 'number' | 'boolean' | 'object' | 'array'>;
  
  /** Custom validation functions */
  customValidators?: Array<(result: InjectionResult) => boolean | string>;
}

/**
 * Interface for modules that support component injection
 */
export interface ComponentInjectionModule {
  /** Component injection configuration */
  injectionConfig: ComponentInjectionConfig;
  
  /** Validate an injection result */
  validateInjectionResult(result: InjectionResult): boolean | string;
  
  /** Process an injection result into module-specific format */
  processInjectionResult(result: InjectionResult): any;
  
  /** Get the container component for injection */
  getInjectionContainer(): ComponentType<any>;
}

/**
 * Props for the container component that wraps injected components
 */
export interface InjectionContainerProps {
  /** The injected component to render */
  InjectedComponent: ComponentType<InjectedComponentProps>;
  
  /** Props to pass to the injected component */
  componentProps: InjectedComponentProps;
  
  /** Error boundary fallback component */
  ErrorFallback?: ComponentType<{ error: Error }>;
  
  /** Loading component while the injected component loads */
  LoadingComponent?: ComponentType;
  
  /** Additional container styling */
  containerClassName?: string;
  
  /** Whether to enable error boundaries */
  enableErrorBoundary?: boolean;
}

/**
 * Context for component injection workflow
 */
export interface ComponentInjectionContext {
  /** Register a new injected component */
  registerComponent: (name: string, component: ComponentType<InjectedComponentProps>) => void;
  
  /** Get a registered component by name */
  getComponent: (name: string) => ComponentType<InjectedComponentProps> | null;
  
  /** Validate component props */
  validateProps: (props: any) => boolean | string;
  
  /** Current injection configuration */
  config: ComponentInjectionConfig;
  
  /** Debug mode flag */
  debug: boolean;
}

/**
 * Factory function type for creating injected components
 */
export type InjectedComponentFactory = (
  config: Record<string, any>
) => ComponentType<InjectedComponentProps>;

/**
 * Registry entry for an injected component
 */
export interface InjectedComponentRegistryEntry {
  /** Component name/identifier */
  name: string;
  
  /** The component constructor or factory */
  component: ComponentType<InjectedComponentProps> | InjectedComponentFactory;
  
  /** Component metadata */
  metadata: {
    version: string;
    author?: string;
    description?: string;
    tags?: string[];
    created: number;
    updated: number;
  };
  
  /** Validation schema for this component */
  schema?: ComponentInjectionSchema;
  
  /** Whether this component is enabled */
  enabled: boolean;
}

/**
 * Error types that can occur during component injection
 */
export type ComponentInjectionError = 
  | 'INVALID_PROPS'
  | 'COMPONENT_NOT_FOUND'
  | 'VALIDATION_FAILED'
  | 'RUNTIME_ERROR'
  | 'SCHEMA_MISMATCH'
  | 'TIMEOUT_ERROR';

/**
 * Error object for component injection failures
 */
export interface ComponentInjectionErrorInfo {
  type: ComponentInjectionError;
  message: string;
  componentName?: string;
  timestamp: number;
  stack?: string;
  context?: Record<string, any>;
}

/**
 * Options for component injection validation
 */
export interface InjectionValidationOptions {
  /** Whether to validate props strictly */
  strictProps?: boolean;
  
  /** Whether to validate result format */
  validateResults?: boolean;
  
  /** Whether to check schema compliance */
  enforceSchema?: boolean;
  
  /** Timeout for validation operations */
  timeout?: number;
}

/**
 * Result of component injection validation
 */
export interface InjectionValidationResult {
  /** Whether validation passed */
  valid: boolean;
  
  /** Error messages if validation failed */
  errors: string[];
  
  /** Warning messages */
  warnings: string[];
  
  /** Validation context information */
  context: {
    componentName: string;
    validationTime: number;
    rulesApplied: string[];
  };
}