@memberjunction/ng-react 2.70.0

package/README.md

@@ -0,0 +1,253 @@
+# @memberjunction/ng-react
+
+Angular components for hosting React components in MemberJunction applications. This package provides a seamless bridge between Angular and React, allowing you to use React components within your Angular applications.
+
+## Overview
+
+The `@memberjunction/ng-react` package enables Angular applications to render React components dynamically. It handles all the complexity of loading React, compiling JSX, managing component lifecycles, and bridging Angular/React data flow.
+
+## Features
+
+- **Dynamic React Component Rendering**: Compile and render React components from source code
+- **Automatic Dependency Loading**: Loads React, ReactDOM, and Babel from CDN
+- **Component Registry**: Manages compiled components with namespace support
+- **Error Boundaries**: Comprehensive error handling for React components
+- **Two-Way Data Binding**: Seamless data flow between Angular and React
+- **TypeScript Support**: Full type safety with TypeScript definitions
+
+## Installation
+
+```bash
+npm install @memberjunction/ng-react
+```
+
+## Basic Usage
+
+### 1. Import the Module
+
+```typescript
+import { MJReactModule } from '@memberjunction/ng-react';
+
+@NgModule({
+  imports: [
+    CommonModule,
+    MJReactModule
+  ]
+})
+export class YourModule { }
+```
+
+### 2. Use in Templates
+
+```html
+<mj-react-component
+  [component]="componentSpec"
+  [data]="componentData"
+  [state]="componentState"
+  [utilities]="utilities"
+  [styles]="styles"
+  (stateChange)="onStateChange($event)"
+  (componentEvent)="onComponentEvent($event)"
+  (refreshData)="onRefreshData()"
+  (openEntityRecord)="onOpenEntityRecord($event)">
+</mj-react-component>
+```
+
+### 3. Component Controller
+
+```typescript
+import { Component } from '@angular/core';
+import { SkipComponentRootSpec } from '@memberjunction/skip-types';
+
+@Component({
+  selector: 'app-example',
+  template: `
+    <mj-react-component
+      [component]="reactComponent"
+      [data]="data">
+    </mj-react-component>
+  `
+})
+export class ExampleComponent {
+  reactComponent: SkipComponentRootSpec = {
+    componentName: 'MyReactComponent',
+    componentCode: `
+      function MyReactComponent({ data, callbacks }) {
+        return (
+          <div>
+            <h1>Hello, {data.name}!</h1>
+            <button onClick={() => callbacks.RefreshData()}>
+              Refresh
+            </button>
+          </div>
+        );
+      }
+    `
+  };
+
+  data = {
+    name: 'World'
+  };
+}
+```
+
+## Component Props
+
+React components receive the following props:
+
+```typescript
+interface ComponentProps {
+  data: any;              // Data passed from Angular
+  userState: any;         // Component state managed by Angular
+  utilities: any;         // Utility functions
+  callbacks: {            // Callbacks to Angular
+    RefreshData: () => void;
+    OpenEntityRecord: (entityName: string, key: any) => void;
+    UpdateUserState: (state: any) => void;
+    NotifyEvent: (event: string, data: any) => void;
+  };
+  components?: Record<string, any>;  // Child components
+  styles?: ComponentStyles;          // Style configuration
+}
+```
+
+## Advanced Features
+
+### Component Hierarchies
+
+```typescript
+const componentSpec: SkipComponentRootSpec = {
+  componentName: 'ParentComponent',
+  componentCode: '...',
+  childComponents: [
+    {
+      componentName: 'ChildComponent1',
+      componentCode: '...'
+    },
+    {
+      componentName: 'ChildComponent2',
+      componentCode: '...'
+    }
+  ]
+};
+```
+
+### Custom Styles
+
+```typescript
+const styles: SkipComponentStyles = {
+  colors: {
+    primary: '#5B4FE9',
+    secondary: '#64748B'
+  },
+  typography: {
+    fontFamily: 'Inter, sans-serif'
+  }
+};
+```
+
+### State Management
+
+```typescript
+// In your Angular component
+onStateChange(event: StateChangeEvent) {
+  console.log(`State ${event.path} changed to:`, event.value);
+  // Update your Angular component state
+}
+
+// In your React component
+function MyComponent({ userState, callbacks }) {
+  const updateState = () => {
+    callbacks.UpdateUserState({
+      counter: userState.counter + 1
+    });
+  };
+  
+  return <button onClick={updateState}>Count: {userState.counter}</button>;
+}
+```
+
+## Services
+
+### ScriptLoaderService
+
+Manages loading of external scripts and CSS:
+
+```typescript
+constructor(private scriptLoader: ScriptLoaderService) {}
+
+async loadCustomLibrary() {
+  const lib = await this.scriptLoader.loadScript(
+    'https://cdn.example.com/lib.js',
+    'MyLibrary'
+  );
+}
+```
+
+### ReactBridgeService
+
+Manages React instances and roots:
+
+```typescript
+constructor(private reactBridge: ReactBridgeService) {}
+
+async checkReactStatus() {
+  const isReady = this.reactBridge.isReady();
+  const rootCount = this.reactBridge.getActiveRootsCount();
+}
+```
+
+### AngularAdapterService
+
+Provides access to the React runtime:
+
+```typescript
+constructor(private adapter: AngularAdapterService) {}
+
+async compileCustomComponent() {
+  const result = await this.adapter.compileComponent({
+    componentName: 'CustomComponent',
+    componentCode: '...'
+  });
+}
+```
+
+## Error Handling
+
+The component automatically wraps React components in error boundaries:
+
+```typescript
+onComponentEvent(event: ReactComponentEvent) {
+  if (event.type === 'error') {
+    console.error('React component error:', event.payload);
+    // Handle error in Angular
+  }
+}
+```
+
+## Performance Considerations
+
+1. **Component Caching**: Compiled components are cached automatically
+2. **Lazy Loading**: React libraries are loaded on-demand
+3. **Change Detection**: Uses OnPush strategy for optimal performance
+4. **Resource Cleanup**: Automatic cleanup of React roots on destroy
+
+## Browser Support
+
+- Chrome (latest)
+- Firefox (latest)
+- Safari (latest)
+- Edge (latest)
+
+## Dependencies
+
+This package requires:
+- Angular 18+
+- React 18+
+- @memberjunction/react-runtime
+- @memberjunction/skip-types
+- @memberjunction/core
+
+## License
+
+See the main MemberJunction LICENSE file in the repository root.

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @fileoverview Entry point for @memberjunction/ng-react package
+ * @module @memberjunction/ng-react
+ */
+export * from './public-api';

package/dist/index.js

@@ -0,0 +1,6 @@
+/**
+ * @fileoverview Entry point for @memberjunction/ng-react package
+ * @module @memberjunction/ng-react
+ */
+export * from './public-api';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,cAAc,cAAc,CAAC","sourcesContent":["/**\n * @fileoverview Entry point for @memberjunction/ng-react package\n * @module @memberjunction/ng-react\n */\n\nexport * from './public-api';"]}

package/dist/lib/cdn-urls.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @fileoverview CDN URLs for external React and related dependencies.
+ * These URLs are used to load React ecosystem libraries in the browser.
+ * @module @memberjunction/ng-react
+ */
+/**
+ * CDN URLs for external dependencies
+ * These can be configured via environment variables in the future
+ */
+export declare const CDN_URLS: {
+    BABEL_STANDALONE: string;
+    REACT: string;
+    REACT_DOM: string;
+    DAYJS: string;
+    ANTD_JS: string;
+    ANTD_CSS: string;
+    REACT_BOOTSTRAP_JS: string;
+    BOOTSTRAP_CSS: string;
+    D3_JS: string;
+    CHART_JS: string;
+    LODASH_JS: string;
+};

package/dist/lib/cdn-urls.js

@@ -0,0 +1,28 @@
+/**
+ * @fileoverview CDN URLs for external React and related dependencies.
+ * These URLs are used to load React ecosystem libraries in the browser.
+ * @module @memberjunction/ng-react
+ */
+/**
+ * CDN URLs for external dependencies
+ * These can be configured via environment variables in the future
+ */
+export const CDN_URLS = {
+    // Core React dependencies
+    BABEL_STANDALONE: 'https://unpkg.com/@babel/standalone@7/babel.min.js',
+    REACT: 'https://unpkg.com/react@18/umd/react.production.min.js',
+    REACT_DOM: 'https://unpkg.com/react-dom@18/umd/react-dom.production.min.js',
+    // Ant Design dependencies
+    DAYJS: 'https://unpkg.com/dayjs@1.11.10/dayjs.min.js',
+    // UI Libraries - Using UMD builds that work with global React
+    ANTD_JS: 'https://unpkg.com/antd@5.12.8/dist/antd.js',
+    ANTD_CSS: 'https://unpkg.com/antd@5.12.8/dist/reset.css',
+    REACT_BOOTSTRAP_JS: 'https://unpkg.com/react-bootstrap@2.9.1/dist/react-bootstrap.js',
+    BOOTSTRAP_CSS: 'https://cdn.jsdelivr.net/npm/bootstrap@5.3.2/dist/css/bootstrap.min.css',
+    // Data Visualization
+    D3_JS: 'https://cdnjs.cloudflare.com/ajax/libs/d3/7.8.5/d3.min.js',
+    CHART_JS: 'https://cdnjs.cloudflare.com/ajax/libs/Chart.js/4.4.0/chart.umd.js',
+    // Utilities
+    LODASH_JS: 'https://cdnjs.cloudflare.com/ajax/libs/lodash.js/4.17.21/lodash.min.js'
+};
+//# sourceMappingURL=cdn-urls.js.map

package/dist/lib/cdn-urls.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cdn-urls.js","sourceRoot":"","sources":["../../src/lib/cdn-urls.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB,0BAA0B;IAC1B,gBAAgB,EAAE,oDAAoD;IACtE,KAAK,EAAE,wDAAwD;IAC/D,SAAS,EAAE,gEAAgE;IAE3E,0BAA0B;IAC1B,KAAK,EAAE,8CAA8C;IAErD,8DAA8D;IAC9D,OAAO,EAAE,4CAA4C;IACrD,QAAQ,EAAE,8CAA8C;IACxD,kBAAkB,EAAE,iEAAiE;IACrF,aAAa,EAAE,yEAAyE;IAExF,qBAAqB;IACrB,KAAK,EAAE,2DAA2D;IAClE,QAAQ,EAAE,oEAAoE;IAE9E,YAAY;IACZ,SAAS,EAAE,wEAAwE;CACpF,CAAC","sourcesContent":["/**\n * @fileoverview CDN URLs for external React and related dependencies.\n * These URLs are used to load React ecosystem libraries in the browser.\n * @module @memberjunction/ng-react\n */\n\n/**\n * CDN URLs for external dependencies\n * These can be configured via environment variables in the future\n */\nexport const CDN_URLS = {\n  // Core React dependencies\n  BABEL_STANDALONE: 'https://unpkg.com/@babel/standalone@7/babel.min.js',\n  REACT: 'https://unpkg.com/react@18/umd/react.production.min.js',\n  REACT_DOM: 'https://unpkg.com/react-dom@18/umd/react-dom.production.min.js',\n  \n  // Ant Design dependencies\n  DAYJS: 'https://unpkg.com/dayjs@1.11.10/dayjs.min.js',\n  \n  // UI Libraries - Using UMD builds that work with global React\n  ANTD_JS: 'https://unpkg.com/antd@5.12.8/dist/antd.js',\n  ANTD_CSS: 'https://unpkg.com/antd@5.12.8/dist/reset.css',\n  REACT_BOOTSTRAP_JS: 'https://unpkg.com/react-bootstrap@2.9.1/dist/react-bootstrap.js',\n  BOOTSTRAP_CSS: 'https://cdn.jsdelivr.net/npm/bootstrap@5.3.2/dist/css/bootstrap.min.css',\n  \n  // Data Visualization\n  D3_JS: 'https://cdnjs.cloudflare.com/ajax/libs/d3/7.8.5/d3.min.js',\n  CHART_JS: 'https://cdnjs.cloudflare.com/ajax/libs/Chart.js/4.4.0/chart.umd.js',\n  \n  // Utilities\n  LODASH_JS: 'https://cdnjs.cloudflare.com/ajax/libs/lodash.js/4.17.21/lodash.min.js'\n};"]}

package/dist/lib/components/mj-react-component.component.d.ts

@@ -0,0 +1,109 @@
+/**
+ * @fileoverview Angular component that hosts React components with proper memory management.
+ * Provides a bridge between Angular and React ecosystems in MemberJunction applications.
+ * @module @memberjunction/ng-react
+ */
+import { EventEmitter, ElementRef, AfterViewInit, OnDestroy, ChangeDetectorRef } from '@angular/core';
+import { SkipComponentRootSpec, SkipComponentStyles } from '@memberjunction/skip-types';
+import { ReactBridgeService } from '../services/react-bridge.service';
+import { AngularAdapterService } from '../services/angular-adapter.service';
+import * as i0 from "@angular/core";
+/**
+ * Event emitted by React components
+ */
+export interface ReactComponentEvent {
+    type: string;
+    payload: any;
+}
+/**
+ * State change event emitted when component state updates
+ */
+export interface StateChangeEvent {
+    path: string;
+    value: any;
+}
+/**
+ * Angular component that hosts React components with proper memory management.
+ * This component provides a bridge between Angular and React, allowing React components
+ * to be used seamlessly within Angular applications.
+ */
+export declare class MJReactComponent implements AfterViewInit, OnDestroy {
+    private reactBridge;
+    private adapter;
+    private cdr;
+    component: SkipComponentRootSpec;
+    private _data;
+    set data(value: any);
+    get data(): any;
+    private _state;
+    set state(value: any);
+    get state(): any;
+    utilities: any;
+    styles?: Partial<SkipComponentStyles>;
+    stateChange: EventEmitter<StateChangeEvent>;
+    componentEvent: EventEmitter<ReactComponentEvent>;
+    refreshData: EventEmitter<void>;
+    openEntityRecord: EventEmitter<{
+        entityName: string;
+        recordId: string;
+    }>;
+    container: ElementRef<HTMLDivElement>;
+    private reactRoot;
+    private compiledComponent;
+    private destroyed$;
+    private currentState;
+    isInitialized: boolean;
+    private isRendering;
+    private pendingRender;
+    hasError: boolean;
+    constructor(reactBridge: ReactBridgeService, adapter: AngularAdapterService, cdr: ChangeDetectorRef);
+    ngAfterViewInit(): Promise<void>;
+    ngOnDestroy(): void;
+    /**
+     * Convert SkipComponentStyles to ComponentStyles
+     * @param skipStyles - Skip component styles
+     * @returns Component styles for React runtime
+     */
+    private convertStyles;
+    /**
+     * Initialize the React component
+     */
+    private initializeComponent;
+    /**
+     * Register all components in the hierarchy
+     */
+    private registerComponentHierarchy;
+    /**
+     * Render the React component
+     */
+    private renderComponent;
+    /**
+     * Create callbacks for the React component
+     */
+    private createCallbacks;
+    /**
+     * Handle React component errors
+     */
+    private handleReactError;
+    /**
+     * Clean up resources
+     */
+    private cleanup;
+    /**
+     * Public method to refresh the component
+     * @param newData - Optional new data to merge
+     */
+    refresh(newData?: any): void;
+    /**
+     * Public method to update state programmatically
+     * @param path - State path to update
+     * @param value - New value
+     */
+    updateState(path: string, value: any): void;
+    /**
+     * Deep equality check that handles null/undefined properly
+     */
+    private isEqual;
+    static ɵfac: i0.ɵɵFactoryDeclaration<MJReactComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<MJReactComponent, "mj-react-component", never, { "component": { "alias": "component"; "required": false; }; "data": { "alias": "data"; "required": false; }; "state": { "alias": "state"; "required": false; }; "utilities": { "alias": "utilities"; "required": false; }; "styles": { "alias": "styles"; "required": false; }; }, { "stateChange": "stateChange"; "componentEvent": "componentEvent"; "refreshData": "refreshData"; "openEntityRecord": "openEntityRecord"; }, never, never, false, never>;
+}