@memberjunction/react-runtime 2.70.0

package/src/runtime/error-boundary.ts

@@ -0,0 +1,242 @@
+/**
+ * @fileoverview React error boundary creation utilities.
+ * Provides platform-agnostic error boundary components for React applications.
+ * @module @memberjunction/react-runtime/runtime
+ */
+
+import { ErrorBoundaryOptions, ComponentError } from '../types';
+
+/**
+ * Creates a React error boundary component class
+ * @param React - React library instance
+ * @param options - Error boundary options
+ * @returns Error boundary component class
+ */
+export function createErrorBoundary(React: any, options: ErrorBoundaryOptions = {}): any {
+  const {
+    onError,
+    fallback,
+    logErrors = true,
+    recovery = 'none'
+  } = options;
+
+  /**
+   * Error boundary component class
+   */
+  return class ErrorBoundary extends React.Component {
+    state: { hasError: boolean; error: Error | null; errorInfo: any; retryCount: number };
+
+    constructor(props: any) {
+      super(props);
+      this.state = {
+        hasError: false,
+        error: null,
+        errorInfo: null,
+        retryCount: 0
+      };
+    }
+
+    static getDerivedStateFromError(error: Error): any {
+      // Update state to trigger fallback UI
+      return { hasError: true, error };
+    }
+
+    componentDidCatch(error: Error, errorInfo: any) {
+      // Log error if enabled
+      if (logErrors) {
+        console.error('React Error Boundary caught error:', error);
+        console.error('Error Info:', errorInfo);
+      }
+
+      // Call custom error handler if provided
+      if (onError) {
+        try {
+          onError(error, errorInfo);
+        } catch (handlerError) {
+          console.error('Error in custom error handler:', handlerError);
+        }
+      }
+
+      // Update state with error details
+      this.setState({ errorInfo });
+    }
+
+    handleRetry = () => {
+      this.setState((prevState: any) => ({
+        hasError: false,
+        error: null,
+        errorInfo: null,
+        retryCount: prevState.retryCount + 1
+      }));
+    };
+
+    handleReset = () => {
+      this.setState({
+        hasError: false,
+        error: null,
+        errorInfo: null,
+        retryCount: 0
+      });
+    };
+
+    render() {
+      if (this.state.hasError) {
+        // Use custom fallback if provided
+        if (fallback) {
+          if (typeof fallback === 'function') {
+            return fallback({
+              error: this.state.error,
+              errorInfo: this.state.errorInfo,
+              retry: this.handleRetry,
+              reset: this.handleReset,
+              retryCount: this.state.retryCount
+            });
+          }
+          return fallback;
+        }
+
+        // Default error UI
+        const showRetry = recovery === 'retry' && this.state.retryCount < 3;
+        const showReset = recovery === 'reset';
+
+        return React.createElement(
+          'div',
+          {
+            style: {
+              padding: '20px',
+              backgroundColor: '#f8f8f8',
+              border: '1px solid #ddd',
+              borderRadius: '4px',
+              margin: '10px'
+            }
+          },
+          React.createElement('h2', { style: { color: '#d32f2f' } }, 'Component Error'),
+          React.createElement(
+            'p',
+            { style: { color: '#666' } },
+            'An error occurred while rendering this component.'
+          ),
+          this.state.error && React.createElement(
+            'details',
+            { style: { marginTop: '10px' } },
+            React.createElement(
+              'summary',
+              { style: { cursor: 'pointer', color: '#333' } },
+              'Error Details'
+            ),
+            React.createElement(
+              'pre',
+              {
+                style: {
+                  backgroundColor: '#f0f0f0',
+                  padding: '10px',
+                  marginTop: '10px',
+                  overflow: 'auto',
+                  fontSize: '12px'
+                }
+              },
+              this.state.error.toString(),
+              '\n\n',
+              this.state.error.stack
+            )
+          ),
+          (showRetry || showReset) && React.createElement(
+            'div',
+            { style: { marginTop: '10px' } },
+            showRetry && React.createElement(
+              'button',
+              {
+                onClick: this.handleRetry,
+                style: {
+                  padding: '8px 16px',
+                  marginRight: '10px',
+                  backgroundColor: '#1976d2',
+                  color: 'white',
+                  border: 'none',
+                  borderRadius: '4px',
+                  cursor: 'pointer'
+                }
+              },
+              `Retry (${3 - this.state.retryCount} attempts left)`
+            ),
+            showReset && React.createElement(
+              'button',
+              {
+                onClick: this.handleReset,
+                style: {
+                  padding: '8px 16px',
+                  backgroundColor: '#757575',
+                  color: 'white',
+                  border: 'none',
+                  borderRadius: '4px',
+                  cursor: 'pointer'
+                }
+              },
+              'Reset Component'
+            )
+          )
+        );
+      }
+
+      return this.props.children;
+    }
+  };
+}
+
+/**
+ * Creates a functional error boundary wrapper using React hooks
+ * @param React - React library instance
+ * @param Component - Component to wrap
+ * @param options - Error boundary options
+ * @returns Wrapped component with error boundary
+ */
+export function withErrorBoundary(React: any, Component: any, options: ErrorBoundaryOptions = {}): any {
+  const ErrorBoundaryComponent = createErrorBoundary(React, options);
+  
+  return (props: any) => {
+    return React.createElement(
+      ErrorBoundaryComponent,
+      null,
+      React.createElement(Component, props)
+    );
+  };
+}
+
+/**
+ * Formats a component error for display or logging
+ * @param error - Error to format
+ * @param componentName - Name of the component where error occurred
+ * @param phase - Phase when error occurred
+ * @returns Formatted component error
+ */
+export function formatComponentError(
+  error: Error,
+  componentName: string,
+  phase: ComponentError['phase']
+): ComponentError {
+  return {
+    message: error.message || 'Unknown error',
+    stack: error.stack,
+    componentName,
+    phase,
+    details: {
+      name: error.name,
+      timestamp: new Date().toISOString()
+    }
+  };
+}
+
+/**
+ * Creates a simple error logger for error boundaries
+ * @param componentName - Name of the component
+ * @returns Error logging function
+ */
+export function createErrorLogger(componentName: string): (error: Error, errorInfo: any) => void {
+  return (error: Error, errorInfo: any) => {
+    console.group(`🚨 React Component Error: ${componentName}`);
+    console.error('Error:', error);
+    console.error('Component Stack:', errorInfo.componentStack);
+    console.error('Props:', errorInfo.props);
+    console.groupEnd();
+  };
+}

package/src/runtime/index.ts

@@ -0,0 +1,45 @@
+/**
+ * @fileoverview Runtime module exports
+ * @module @memberjunction/react-runtime/runtime
+ */
+
+export {
+  createErrorBoundary,
+  withErrorBoundary,
+  formatComponentError,
+  createErrorLogger
+} from './error-boundary';
+
+export {
+  wrapComponent,
+  memoizeComponent,
+  lazyComponent,
+  injectProps,
+  conditionalComponent,
+  withErrorHandler,
+  portalComponent,
+  WrapperOptions
+} from './component-wrapper';
+
+export {
+  buildComponentProps,
+  normalizeCallbacks,
+  normalizeStyles,
+  validateComponentProps,
+  mergeProps,
+  createPropsTransformer,
+  wrapCallbacksWithLogging,
+  extractPropPaths,
+  PropBuilderOptions
+} from './prop-builder';
+
+export {
+  ComponentHierarchyRegistrar,
+  registerComponentHierarchy,
+  validateComponentSpec,
+  flattenComponentHierarchy,
+  countComponentsInHierarchy,
+  HierarchyRegistrationResult,
+  ComponentRegistrationError,
+  HierarchyRegistrationOptions
+} from './component-hierarchy';

package/src/runtime/prop-builder.ts

@@ -0,0 +1,290 @@
+/**
+ * @fileoverview Props builder utilities for React components.
+ * Provides utilities for constructing and validating component props.
+ * @module @memberjunction/react-runtime/runtime
+ */
+
+import { ComponentProps, ComponentCallbacks, ComponentStyles } from '../types';
+
+/**
+ * Options for building component props
+ */
+export interface PropBuilderOptions {
+  /** Validate props before building */
+  validate?: boolean;
+  /** Merge with existing props */
+  merge?: boolean;
+  /** Transform data before passing to component */
+  transformData?: (data: any) => any;
+  /** Transform state before passing to component */
+  transformState?: (state: any) => any;
+}
+
+/**
+ * Builds component props from various sources
+ * @param data - Component data
+ * @param userState - User state object
+ * @param utilities - Utility functions
+ * @param callbacks - Component callbacks
+ * @param components - Child components
+ * @param styles - Component styles
+ * @param options - Builder options
+ * @returns Built component props
+ */
+export function buildComponentProps(
+  data: any = {},
+  userState: any = {},
+  utilities: any = {},
+  callbacks: ComponentCallbacks = {},
+  components: Record<string, any> = {},
+  styles?: ComponentStyles,
+  options: PropBuilderOptions = {}
+): ComponentProps {
+  const {
+    validate = true,
+    transformData,
+    transformState
+  } = options;
+
+  // Transform data if transformer provided
+  const transformedData = transformData ? transformData(data) : data;
+  const transformedState = transformState ? transformState(userState) : userState;
+
+  // Build props object
+  const props: ComponentProps = {
+    data: transformedData,
+    userState: transformedState,
+    utilities,
+    callbacks: normalizeCallbacks(callbacks),
+    components,
+    styles: normalizeStyles(styles)
+  };
+
+  // Validate if enabled
+  if (validate) {
+    validateComponentProps(props);
+  }
+
+  return props;
+}
+
+/**
+ * Normalizes component callbacks
+ * @param callbacks - Raw callbacks object
+ * @returns Normalized callbacks
+ */
+export function normalizeCallbacks(callbacks: any): ComponentCallbacks {
+  const normalized: ComponentCallbacks = {};
+
+  // Ensure all callbacks are functions
+  if (callbacks.RefreshData && typeof callbacks.RefreshData === 'function') {
+    normalized.RefreshData = callbacks.RefreshData;
+  }
+
+  if (callbacks.OpenEntityRecord && typeof callbacks.OpenEntityRecord === 'function') {
+    normalized.OpenEntityRecord = callbacks.OpenEntityRecord;
+  }
+
+  if (callbacks.UpdateUserState && typeof callbacks.UpdateUserState === 'function') {
+    normalized.UpdateUserState = callbacks.UpdateUserState;
+  }
+
+  if (callbacks.NotifyEvent && typeof callbacks.NotifyEvent === 'function') {
+    normalized.NotifyEvent = callbacks.NotifyEvent;
+  }
+
+  return normalized;
+}
+
+/**
+ * Normalizes component styles
+ * @param styles - Raw styles object
+ * @returns Normalized styles
+ */
+export function normalizeStyles(styles?: any): any {
+  // Pass through the full styles object as-is
+  // This allows Skip components to access their full style structure
+  // including colors, typography, borders, etc.
+  return styles;
+}
+
+/**
+ * Validates component props
+ * @param props - Props to validate
+ * @throws Error if validation fails
+ */
+export function validateComponentProps(props: ComponentProps): void {
+  // Validate data
+  if (props.data === null || props.data === undefined) {
+    throw new Error('Component props.data cannot be null or undefined');
+  }
+
+  // Validate userState
+  if (props.userState === null) {
+    throw new Error('Component props.userState cannot be null');
+  }
+
+  // Validate utilities
+  if (props.utilities === null) {
+    throw new Error('Component props.utilities cannot be null');
+  }
+
+  // Validate callbacks
+  if (!props.callbacks || typeof props.callbacks !== 'object') {
+    throw new Error('Component props.callbacks must be an object');
+  }
+
+  // Validate callback functions
+  for (const [key, value] of Object.entries(props.callbacks)) {
+    if (value !== undefined && typeof value !== 'function') {
+      throw new Error(`Component callback "${key}" must be a function`);
+    }
+  }
+}
+
+/**
+ * Merges multiple prop objects
+ * @param propsList - Array of props to merge
+ * @returns Merged props
+ */
+export function mergeProps(...propsList: Partial<ComponentProps>[]): ComponentProps {
+  const merged: ComponentProps = {
+    data: {},
+    userState: {},
+    utilities: {},
+    callbacks: {},
+    components: {},
+    styles: {}
+  };
+
+  for (const props of propsList) {
+    if (props.data) {
+      merged.data = { ...merged.data, ...props.data };
+    }
+
+    if (props.userState) {
+      merged.userState = { ...merged.userState, ...props.userState };
+    }
+
+    if (props.utilities) {
+      merged.utilities = { ...merged.utilities, ...props.utilities };
+    }
+
+    if (props.callbacks) {
+      merged.callbacks = { ...merged.callbacks, ...props.callbacks };
+    }
+
+    if (props.components) {
+      merged.components = { ...merged.components, ...props.components };
+    }
+
+    if (props.styles) {
+      merged.styles = { ...merged.styles, ...props.styles };
+    }
+  }
+
+  return merged;
+}
+
+/**
+ * Creates a props transformer function
+ * @param transformations - Map of prop paths to transformer functions
+ * @returns Props transformer
+ */
+export function createPropsTransformer(
+  transformations: Record<string, (value: any) => any>
+): (props: ComponentProps) => ComponentProps {
+  return (props: ComponentProps) => {
+    const transformed = { ...props };
+
+    for (const [path, transformer] of Object.entries(transformations)) {
+      const pathParts = path.split('.');
+      let current: any = transformed;
+      
+      // Navigate to the parent of the target property
+      for (let i = 0; i < pathParts.length - 1; i++) {
+        if (!current[pathParts[i]]) {
+          current[pathParts[i]] = {};
+        }
+        current = current[pathParts[i]];
+      }
+
+      // Apply transformation
+      const lastPart = pathParts[pathParts.length - 1];
+      if (current[lastPart] !== undefined) {
+        current[lastPart] = transformer(current[lastPart]);
+      }
+    }
+
+    return transformed;
+  };
+}
+
+/**
+ * Creates a callback wrapper that adds logging
+ * @param callbacks - Original callbacks
+ * @param componentName - Component name for logging
+ * @returns Wrapped callbacks
+ */
+export function wrapCallbacksWithLogging(
+  callbacks: ComponentCallbacks,
+  componentName: string
+): ComponentCallbacks {
+  const wrapped: ComponentCallbacks = {};
+
+  if (callbacks.RefreshData) {
+    wrapped.RefreshData = () => {
+      console.log(`[${componentName}] RefreshData called`);
+      callbacks.RefreshData!();
+    };
+  }
+
+  if (callbacks.OpenEntityRecord) {
+    wrapped.OpenEntityRecord = (entityName: string, key: any) => {
+      console.log(`[${componentName}] OpenEntityRecord called:`, { entityName, key });
+      callbacks.OpenEntityRecord!(entityName, key);
+    };
+  }
+
+  if (callbacks.UpdateUserState) {
+    wrapped.UpdateUserState = (state: any) => {
+      console.log(`[${componentName}] UpdateUserState called:`, state);
+      callbacks.UpdateUserState!(state);
+    };
+  }
+
+  if (callbacks.NotifyEvent) {
+    wrapped.NotifyEvent = (event: string, data: any) => {
+      console.log(`[${componentName}] NotifyEvent called:`, { event, data });
+      callbacks.NotifyEvent!(event, data);
+    };
+  }
+
+  return wrapped;
+}
+
+/**
+ * Extracts props paths used by a component
+ * @param componentCode - Component source code
+ * @returns Array of prop paths
+ */
+export function extractPropPaths(componentCode: string): string[] {
+  const paths: string[] = [];
+  
+  // Simple regex patterns to find prop access
+  const patterns = [
+    /props\.data\.(\w+)/g,
+    /props\.userState\.(\w+)/g,
+    /props\.utilities\.(\w+)/g,
+    /props\.callbacks\.(\w+)/g
+  ];
+
+  for (const pattern of patterns) {
+    let match;
+    while ((match = pattern.exec(componentCode)) !== null) {
+      paths.push(match[0]);
+    }
+  }
+
+  return [...new Set(paths)]; // Remove duplicates
+}