@memberjunction/react-runtime 2.70.0

package/src/runtime/component-hierarchy.ts

@@ -0,0 +1,346 @@
+/**
+ * @fileoverview Component hierarchy registration utilities for MemberJunction React Runtime.
+ * Provides functionality to register a hierarchy of components from Skip component specifications.
+ * @module @memberjunction/react-runtime/hierarchy
+ */
+
+import { 
+  CompilationResult,
+  CompileOptions,
+  ComponentStyles,
+  RuntimeContext
+} from '../types';
+import { ComponentCompiler } from '../compiler';
+import { ComponentRegistry } from '../registry';
+
+import { ComponentSpec } from '../registry/component-resolver';
+
+/**
+ * Result of a hierarchy registration operation
+ */
+export interface HierarchyRegistrationResult {
+  success: boolean;
+  registeredComponents: string[];
+  errors: ComponentRegistrationError[];
+  warnings: string[];
+}
+
+/**
+ * Error information for component registration
+ */
+export interface ComponentRegistrationError {
+  componentName: string;
+  error: string;
+  phase: 'compilation' | 'registration' | 'validation';
+}
+
+/**
+ * Options for hierarchy registration
+ */
+export interface HierarchyRegistrationOptions {
+  /** Component styles to apply to all components */
+  styles?: ComponentStyles;
+  /** Namespace for component registration */
+  namespace?: string;
+  /** Version for component registration */
+  version?: string;
+  /** Whether to continue on errors */
+  continueOnError?: boolean;
+  /** Whether to override existing components */
+  allowOverride?: boolean;
+}
+
+/**
+ * Utility class for registering component hierarchies
+ */
+export class ComponentHierarchyRegistrar {
+  constructor(
+    private compiler: ComponentCompiler,
+    private registry: ComponentRegistry,
+    private runtimeContext: RuntimeContext
+  ) {}
+
+  /**
+   * Registers a complete component hierarchy from a root specification
+   * @param rootSpec - The root component specification
+   * @param options - Registration options
+   * @returns Registration result with details about success/failures
+   */
+  async registerHierarchy(
+    rootSpec: ComponentSpec,
+    options: HierarchyRegistrationOptions = {}
+  ): Promise<HierarchyRegistrationResult> {
+    const {
+      styles,
+      namespace = 'Global',
+      version = 'v1',
+      continueOnError = true,
+      allowOverride = true
+    } = options;
+
+    const registeredComponents: string[] = [];
+    const errors: ComponentRegistrationError[] = [];
+    const warnings: string[] = [];
+
+    // Register the root component
+    const rootResult = await this.registerSingleComponent(
+      rootSpec,
+      { styles, namespace, version, allowOverride }
+    );
+
+    if (rootResult.success) {
+      registeredComponents.push(rootSpec.componentName);
+    } else {
+      errors.push(rootResult.error!);
+      if (!continueOnError) {
+        return { success: false, registeredComponents, errors, warnings };
+      }
+    }
+
+    // Register child components recursively
+    const childComponents = rootSpec.childComponents || rootSpec.components || [];
+    if (childComponents.length > 0) {
+      const childResult = await this.registerChildComponents(
+        childComponents,
+        { styles, namespace, version, continueOnError, allowOverride },
+        registeredComponents,
+        errors,
+        warnings
+      );
+    }
+
+    return {
+      success: errors.length === 0,
+      registeredComponents,
+      errors,
+      warnings
+    };
+  }
+
+  /**
+   * Registers a single component from a specification
+   * @param spec - Component specification
+   * @param options - Registration options
+   * @returns Registration result for this component
+   */
+  async registerSingleComponent(
+    spec: ComponentSpec,
+    options: {
+      styles?: ComponentStyles;
+      namespace?: string;
+      version?: string;
+      allowOverride?: boolean;
+    }
+  ): Promise<{ success: boolean; error?: ComponentRegistrationError }> {
+    const { styles, namespace = 'Global', version = 'v1', allowOverride = true } = options;
+
+    try {
+      // Skip if no component code
+      if (!spec.componentCode) {
+        return {
+          success: true,
+          error: undefined
+        };
+      }
+
+      // Check if component already exists
+      const existingComponent = this.registry.get(spec.componentName, namespace, version);
+      if (existingComponent && !allowOverride) {
+        return {
+          success: false,
+          error: {
+            componentName: spec.componentName,
+            error: `Component already registered in ${namespace}/${version}`,
+            phase: 'registration'
+          }
+        };
+      }
+
+      // Compile the component
+      const compileOptions: CompileOptions = {
+        componentName: spec.componentName,
+        componentCode: spec.componentCode,
+        styles
+      };
+
+      const compilationResult = await this.compiler.compile(compileOptions);
+
+      if (!compilationResult.success) {
+        return {
+          success: false,
+          error: {
+            componentName: spec.componentName,
+            error: compilationResult.error?.message || 'Unknown compilation error',
+            phase: 'compilation'
+          }
+        };
+      }
+
+      // Create component factory
+      const componentFactory = compilationResult.component!.component(this.runtimeContext, styles);
+
+      // Register the component
+      this.registry.register(
+        spec.componentName,
+        componentFactory.component,
+        namespace,
+        version
+      );
+
+      return { success: true };
+
+    } catch (error) {
+      return {
+        success: false,
+        error: {
+          componentName: spec.componentName,
+          error: error instanceof Error ? error.message : String(error),
+          phase: 'registration'
+        }
+      };
+    }
+  }
+
+  /**
+   * Recursively registers child components
+   * @param children - Array of child component specifications
+   * @param options - Registration options
+   * @param registeredComponents - Array to track registered components
+   * @param errors - Array to collect errors
+   * @param warnings - Array to collect warnings
+   */
+  private async registerChildComponents(
+    children: ComponentSpec[],
+    options: HierarchyRegistrationOptions,
+    registeredComponents: string[],
+    errors: ComponentRegistrationError[],
+    warnings: string[]
+  ): Promise<void> {
+    for (const child of children) {
+      // Register this child
+      const childResult = await this.registerSingleComponent(child, {
+        styles: options.styles,
+        namespace: options.namespace,
+        version: options.version,
+        allowOverride: options.allowOverride
+      });
+
+      if (childResult.success) {
+        if (child.componentCode) {
+          registeredComponents.push(child.componentName);
+        }
+      } else {
+        errors.push(childResult.error!);
+        if (!options.continueOnError) {
+          return;
+        }
+      }
+
+      // Register nested children recursively
+      const nestedChildren = child.childComponents || child.components || [];
+      if (nestedChildren.length > 0) {
+        await this.registerChildComponents(
+          nestedChildren,
+          options,
+          registeredComponents,
+          errors,
+          warnings
+        );
+      }
+    }
+  }
+}
+
+/**
+ * Convenience function to register a component hierarchy
+ * @param rootSpec - The root component specification
+ * @param compiler - Component compiler instance
+ * @param registry - Component registry instance
+ * @param runtimeContext - Runtime context with React and other libraries
+ * @param options - Registration options
+ * @returns Registration result
+ */
+export async function registerComponentHierarchy(
+  rootSpec: ComponentSpec,
+  compiler: ComponentCompiler,
+  registry: ComponentRegistry,
+  runtimeContext: RuntimeContext,
+  options: HierarchyRegistrationOptions = {}
+): Promise<HierarchyRegistrationResult> {
+  const registrar = new ComponentHierarchyRegistrar(compiler, registry, runtimeContext);
+  return registrar.registerHierarchy(rootSpec, options);
+}
+
+/**
+ * Validates a component specification before registration
+ * @param spec - Component specification to validate
+ * @returns Array of validation errors (empty if valid)
+ */
+export function validateComponentSpec(spec: ComponentSpec): string[] {
+  const errors: string[] = [];
+
+  if (!spec.componentName) {
+    errors.push('Component specification must have a componentName');
+  }
+
+  // If componentCode is provided, do basic validation
+  if (spec.componentCode) {
+    if (typeof spec.componentCode !== 'string') {
+      errors.push(`Component code for ${spec.componentName} must be a string`);
+    }
+    if (spec.componentCode.trim().length === 0) {
+      errors.push(`Component code for ${spec.componentName} cannot be empty`);
+    }
+  }
+
+  // Validate child components recursively
+  const children = spec.childComponents || spec.components || [];
+  children.forEach((child, index) => {
+    const childErrors = validateComponentSpec(child);
+    childErrors.forEach(error => {
+      errors.push(`Child ${index} (${child.componentName || 'unnamed'}): ${error}`);
+    });
+  });
+
+  return errors;
+}
+
+/**
+ * Flattens a component hierarchy into a list of all components
+ * @param rootSpec - The root component specification
+ * @returns Array of all component specifications in the hierarchy
+ */
+export function flattenComponentHierarchy(rootSpec: ComponentSpec): ComponentSpec[] {
+  const components: ComponentSpec[] = [rootSpec];
+  
+  const children = rootSpec.childComponents || rootSpec.components || [];
+  children.forEach(child => {
+    components.push(...flattenComponentHierarchy(child));
+  });
+
+  return components;
+}
+
+/**
+ * Counts the total number of components in a hierarchy
+ * @param rootSpec - The root component specification
+ * @param includeEmpty - Whether to include components without code
+ * @returns Total component count
+ */
+export function countComponentsInHierarchy(
+  rootSpec: ComponentSpec,
+  includeEmpty: boolean = false
+): number {
+  let count = 0;
+  
+  if (includeEmpty || rootSpec.componentCode) {
+    count = 1;
+  }
+
+  const children = rootSpec.childComponents || rootSpec.components || [];
+  children.forEach(child => {
+    count += countComponentsInHierarchy(child, includeEmpty);
+  });
+
+  return count;
+}

package/src/runtime/component-wrapper.ts

@@ -0,0 +1,249 @@
+/**
+ * @fileoverview React component wrapper utilities.
+ * Provides HOCs and utilities for wrapping components with additional functionality.
+ * @module @memberjunction/react-runtime/runtime
+ */
+
+import { ComponentProps, ComponentLifecycle } from '../types';
+
+/**
+ * Options for wrapping a component
+ */
+export interface WrapperOptions {
+  /** Component display name */
+  displayName?: string;
+  /** Enable performance monitoring */
+  enableProfiling?: boolean;
+  /** Enable props logging */
+  logProps?: boolean;
+  /** Lifecycle hooks */
+  lifecycle?: ComponentLifecycle;
+  /** Default props */
+  defaultProps?: Partial<ComponentProps>;
+}
+
+/**
+ * Wraps a React component with additional functionality
+ * @param React - React library instance
+ * @param Component - Component to wrap
+ * @param options - Wrapper options
+ * @returns Wrapped component
+ */
+export function wrapComponent(React: any, Component: any, options: WrapperOptions = {}): any {
+  const {
+    displayName,
+    enableProfiling = false,
+    logProps = false,
+    lifecycle = {},
+    defaultProps = {}
+  } = options;
+
+  // Create wrapper component
+  const WrappedComponent = React.forwardRef((props: any, ref: any) => {
+    const mergedProps = { ...defaultProps, ...props };
+
+    // Log props if enabled
+    React.useEffect(() => {
+      if (logProps) {
+        console.log(`[${displayName || Component.name}] Props:`, mergedProps);
+      }
+    }, [mergedProps]);
+
+    // Lifecycle: beforeMount
+    React.useEffect(() => {
+      if (lifecycle.beforeMount) {
+        lifecycle.beforeMount();
+      }
+
+      // Lifecycle: afterMount
+      if (lifecycle.afterMount) {
+        lifecycle.afterMount();
+      }
+
+      // Lifecycle: beforeUnmount
+      return () => {
+        if (lifecycle.beforeUnmount) {
+          lifecycle.beforeUnmount();
+        }
+      };
+    }, []);
+
+    // Lifecycle: beforeUpdate/afterUpdate
+    const prevPropsRef = React.useRef(mergedProps);
+    React.useEffect(() => {
+      const prevProps = prevPropsRef.current;
+      
+      if (lifecycle.beforeUpdate) {
+        lifecycle.beforeUpdate(prevProps, mergedProps);
+      }
+
+      // Schedule afterUpdate
+      if (lifecycle.afterUpdate) {
+        Promise.resolve().then(() => {
+          lifecycle.afterUpdate!(prevProps, mergedProps);
+        });
+      }
+
+      prevPropsRef.current = mergedProps;
+    });
+
+    // Render with profiling if enabled
+    if (enableProfiling && React.Profiler) {
+      return React.createElement(
+        React.Profiler,
+        {
+          id: displayName || Component.name || 'WrappedComponent',
+          onRender: (id: string, phase: string, actualDuration: number) => {
+            console.log(`[Profiler] ${id} (${phase}): ${actualDuration.toFixed(2)}ms`);
+          }
+        },
+        React.createElement(Component, { ...mergedProps, ref })
+      );
+    }
+
+    return React.createElement(Component, { ...mergedProps, ref });
+  });
+
+  // Set display name
+  WrappedComponent.displayName = displayName || `Wrapped(${Component.displayName || Component.name || 'Component'})`;
+
+  return WrappedComponent;
+}
+
+/**
+ * Creates a memoized version of a component
+ * @param React - React library instance
+ * @param Component - Component to memoize
+ * @param propsAreEqual - Optional comparison function
+ * @returns Memoized component
+ */
+export function memoizeComponent(
+  React: any,
+  Component: any,
+  propsAreEqual?: (prevProps: any, nextProps: any) => boolean
+): any {
+  return React.memo(Component, propsAreEqual);
+}
+
+/**
+ * Creates a lazy-loaded component
+ * @param React - React library instance
+ * @param loader - Function that returns a promise resolving to the component
+ * @param fallback - Optional loading fallback
+ * @returns Lazy component
+ */
+export function lazyComponent(
+  React: any,
+  loader: () => Promise<{ default: any }>,
+  fallback?: any
+): any {
+  const LazyComponent = React.lazy(loader);
+
+  if (fallback) {
+    return (props: any) => React.createElement(
+      React.Suspense,
+      { fallback },
+      React.createElement(LazyComponent, props)
+    );
+  }
+
+  return LazyComponent;
+}
+
+/**
+ * Injects additional props into a component
+ * @param React - React library instance
+ * @param Component - Component to inject props into
+ * @param injectedProps - Props to inject
+ * @returns Component with injected props
+ */
+export function injectProps(React: any, Component: any, injectedProps: any): any {
+  return React.forwardRef((props: any, ref: any) => {
+    const mergedProps = { ...injectedProps, ...props };
+    return React.createElement(Component, { ...mergedProps, ref });
+  });
+}
+
+/**
+ * Creates a component that renders conditionally
+ * @param React - React library instance
+ * @param Component - Component to render conditionally
+ * @param condition - Condition function or boolean
+ * @param fallback - Optional fallback component
+ * @returns Conditional component
+ */
+export function conditionalComponent(
+  React: any,
+  Component: any,
+  condition: boolean | ((props: any) => boolean),
+  fallback?: any
+): any {
+  return (props: any) => {
+    const shouldRender = typeof condition === 'function' ? condition(props) : condition;
+    
+    if (shouldRender) {
+      return React.createElement(Component, props);
+    }
+    
+    return fallback || null;
+  };
+}
+
+/**
+ * Creates a component with default error handling
+ * @param React - React library instance
+ * @param Component - Component to wrap
+ * @param errorHandler - Error handling function
+ * @returns Component with error handling
+ */
+export function withErrorHandler(
+  React: any,
+  Component: any,
+  errorHandler: (error: Error) => void
+): any {
+  return class extends React.Component {
+    componentDidCatch(error: Error, errorInfo: any) {
+      errorHandler(error);
+    }
+
+    render() {
+      return React.createElement(Component, this.props);
+    }
+  };
+}
+
+/**
+ * Creates a portal wrapper component
+ * @param React - React library instance
+ * @param ReactDOM - ReactDOM library instance
+ * @param Component - Component to render in portal
+ * @param container - DOM container element or selector
+ * @returns Portal component
+ */
+export function portalComponent(
+  React: any,
+  ReactDOM: any,
+  Component: any,
+  container: Element | string
+): any {
+  return (props: any) => {
+    const [mountNode, setMountNode] = React.useState(null as Element | null);
+
+    React.useEffect(() => {
+      const node = typeof container === 'string'
+        ? document.querySelector(container)
+        : container;
+      
+      setMountNode(node);
+    }, []);
+
+    if (!mountNode || !ReactDOM.createPortal) {
+      return null;
+    }
+
+    return ReactDOM.createPortal(
+      React.createElement(Component, props),
+      mountNode
+    );
+  };
+}