@memberjunction/react-runtime 2.98.0 → 2.100.0

package/.turbo/turbo-build.log

@@ -1,30 +1,25 @@
 
-> @memberjunction/react-runtime@2.98.0 build
+> @memberjunction/react-runtime@2.100.0 build
 > npm run build:node && npm run build:umd
 
 
-> @memberjunction/react-runtime@2.98.0 build:node
+> @memberjunction/react-runtime@2.100.0 build:node
 > tsc
 
 
-> @memberjunction/react-runtime@2.98.0 build:umd
+> @memberjunction/react-runtime@2.100.0 build:umd
 > webpack --config webpack.umd.config.js
 
 [BABEL] Note: The code generator has deoptimised the styling of /home/runner/work/MJ/MJ/packages/MJCoreEntities/dist/generated/entity_subclasses.js as it exceeds the max of 500KB.
-asset runtime.umd.js 1.93 MiB [emitted] [minimized] [big] (name: main) 1 related asset
-runtime modules 344 bytes 2 modules
-modules by path ../../../node_modules/ 1.01 MiB 237 modules
-modules by path ../../MJGlobal/ 174 KiB
-  modules by path ../../MJGlobal/node_modules/uuid/dist/commonjs-browser/*.js 35 KiB 21 modules
-  modules by path ../../MJGlobal/dist/ 139 KiB 14 modules
-modules by path ../../MJCore/ 644 KiB 31 modules
-modules by path ./dist/ 361 KiB 25 modules
-modules by path ../../MJCoreEntities/dist/ 2.05 MiB
-  modules by path ../../MJCoreEntities/dist/custom/*.js 245 KiB 15 modules
-  modules by path ../../MJCoreEntities/dist/custom/ResourcePermissions/*.js 46.9 KiB 3 modules
-  + 3 modules
-modules by path ../../InteractiveComponents/dist/*.js 36.8 KiB
-  ../../InteractiveComponents/dist/index.js 1.21 KiB [built] [code generated]
-  ../../InteractiveComponents/dist/data-requirements.js 79 bytes [built] [code generated]
-  + 8 modules
-webpack 5.92.1 compiled successfully in 114094 ms
+asset runtime.umd.js 2.27 MiB [emitted] [minimized] [big] (name: main) 1 related asset
+orphan modules 513 KiB [orphan] 123 modules
+runtime modules 1010 bytes 5 modules
+modules by path ../../ 4.61 MiB
+  modules by path ../../../node_modules/ 1.62 MiB 258 modules
+  modules by path ../../MJGlobal/ 174 KiB 35 modules
+  modules by path ../../MJCore/ 644 KiB 31 modules
+  modules by path ../../GraphQLDataProvider/ 111 KiB 22 modules
+  modules by path ../../MJCoreEntities/dist/ 2.05 MiB 21 modules
+  modules by path ../../InteractiveComponents/dist/*.js 36.8 KiB 10 modules
+modules by path ./dist/ 469 KiB 28 modules
+webpack 5.92.1 compiled successfully in 136339 ms

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @memberjunction/react-runtime
 
+## 2.100.0
+
+### Patch Changes
+
+- 6dfe03c: tweaks
+- Updated dependencies [5f76e3a]
+- Updated dependencies [b3132ec]
+- Updated dependencies [ffc2c1a]
+  - @memberjunction/core@2.100.0
+  - @memberjunction/graphql-dataprovider@2.100.0
+  - @memberjunction/core-entities@2.100.0
+  - @memberjunction/interactive-component-types@2.100.0
+  - @memberjunction/global@2.100.0
+
+## 2.99.0
+
+### Patch Changes
+
+- 5af2d74: updates to react runtime
+- Updated dependencies [eb7677d]
+- Updated dependencies [8bbb0a9]
+  - @memberjunction/core-entities@2.99.0
+  - @memberjunction/core@2.99.0
+  - @memberjunction/interactive-component-types@2.99.0
+  - @memberjunction/global@2.99.0
+
 ## 2.98.0
 
 ### Minor Changes

package/README.md

@@ -33,9 +33,104 @@ import * as Babel from '@babel/standalone';
 
 // Create runtime with Babel instance
 const runtime = createReactRuntime(Babel);
+
+// The runtime now includes the unified ComponentManager
+const { compiler, registry, resolver, manager } = runtime;
+```
+
+## NEW: Unified ComponentManager (Recommended)
+
+The ComponentManager is a new unified API that simplifies component loading by handling fetching, compilation, registration, and caching in a single, efficient operation. It eliminates duplicate work and provides better performance.
+
+### Why Use ComponentManager?
+
+- **Single API**: One method handles everything - no need to coordinate multiple components
+- **Efficient**: Automatically prevents duplicate fetching and compilation
+- **Smart Caching**: Multi-level caching with automatic invalidation
+- **Registry Tracking**: Built-in usage tracking for licensing compliance
+- **Better Error Handling**: Comprehensive error reporting with phases
+
+### Loading a Component Hierarchy
+
+```typescript
+import { ComponentSpec } from '@memberjunction/interactive-component-types';
+
+const componentSpec: ComponentSpec = {
+  name: 'Dashboard',
+  location: 'registry',
+  registry: 'SkipAI',
+  namespace: 'analytics',
+  version: '1.0.0',
+  dependencies: [
+    { name: 'Chart', location: 'registry', registry: 'SkipAI' },
+    { name: 'Grid', location: 'embedded', code: '...' }
+  ]
+};
+
+// Load the entire hierarchy with one call
+const result = await runtime.manager.loadHierarchy(componentSpec, {
+  contextUser: currentUser,
+  defaultNamespace: 'Global',
+  defaultVersion: 'latest',
+  returnType: 'both'
+});
+
+if (result.success) {
+  // Everything is loaded and ready
+  const rootComponent = result.rootComponent;
+  const resolvedSpec = result.resolvedSpec;
+  
+  console.log(`Loaded ${result.loadedComponents.length} components`);
+  console.log(`Stats:`, result.stats);
+}
+```
+
+### Loading a Single Component
+
+```typescript
+// For simple single component loading
+const result = await runtime.manager.loadComponent(componentSpec, {
+  contextUser: currentUser,
+  forceRefresh: false, // Use cache if available
+  trackUsage: true     // Track usage for licensing
+});
+
+if (result.success) {
+  const component = result.component;
+  const wasFromCache = result.fromCache;
+}
+```
+
+### Configuration Options
+
+```typescript
+const runtime = createReactRuntime(Babel, {
+  manager: {
+    debug: true,                  // Enable debug logging
+    maxCacheSize: 100,            // Max cached specs
+    cacheTTL: 3600000,           // 1 hour cache TTL
+    enableUsageTracking: true,    // Track registry usage
+    dependencyBatchSize: 5,       // Parallel dependency loading
+    fetchTimeout: 30000          // 30 second timeout
+  }
+});
 ```
 
-### Compiling a Component
+### Cache Management
+
+```typescript
+// Clear all caches
+runtime.manager.clearCache();
+
+// Get cache statistics
+const stats = runtime.manager.getCacheStats();
+console.log(`Cached specs: ${stats.fetchCacheSize}`);
+console.log(`Usage notifications: ${stats.notificationsCount}`);
+```
+
+## Legacy Approach (Still Supported)
+
+### Compiling a Component (Old Way)
 
 ```typescript
 const componentCode = `
@@ -421,6 +516,81 @@ const removed = runtime.registry.cleanup();
 console.log(`Removed ${removed} unused components`);
 ```
 
+### External Registry Components
+
+The React Runtime supports loading components from external registries through the `ComponentRegistryService`:
+
+```typescript
+// Component specs can reference external registries
+const componentSpec = {
+  name: 'DataGrid',
+  location: 'registry',
+  registry: 'MJ',  // Registry name (globally unique)
+  namespace: 'core/ui',
+  version: 'latest',
+  // ... other spec fields
+};
+
+// The runtime will:
+// 1. Look up the registry by name in ComponentRegistries
+// 2. Fetch the component via GraphQL/MJServer
+// 3. Calculate SHA-256 hash of the spec for cache validation
+// 4. Compile and cache the component
+```
+
+#### GraphQL Client Configuration
+
+The `ComponentRegistryService` requires a GraphQL client for fetching from external registries. It supports two configuration approaches:
+
+1. **Automatic Fallback** (Recommended): If no client is explicitly provided, the service automatically creates a `GraphQLComponentRegistryClient` using `Metadata.Provider`
+   ```typescript
+   // No explicit client needed - will create one from Metadata.Provider
+   const registryService = ComponentRegistryService.getInstance(compiler, context);
+   // The service will automatically:
+   // 1. Check if a client was provided
+   // 2. If not, dynamically import @memberjunction/graphql-dataprovider
+   // 3. Create a GraphQLComponentRegistryClient with Metadata.Provider
+   // 4. Cache and reuse this client for subsequent calls
+   ```
+
+2. **Explicit Client**: Provide a custom GraphQL client that implements `IComponentRegistryClient`
+   ```typescript
+   // Custom client implementation
+   const customClient: IComponentRegistryClient = {
+     GetRegistryComponent: async (params) => { /* ... */ }
+   };
+   
+   // Pass during creation
+   const registryService = ComponentRegistryService.getInstance(
+     compiler, context, debug, customClient
+   );
+   
+   // Or set later
+   registryService.setGraphQLClient(customClient);
+   ```
+
+The automatic fallback ensures external registry fetching works out-of-the-box in MemberJunction environments where `Metadata.Provider` is configured. The dynamic import approach allows the React runtime to function even when `@memberjunction/graphql-dataprovider` is not available.
+
+#### Component Caching with SHA-256 Validation
+
+The runtime uses SHA-256 hashing to ensure cached components are up-to-date:
+
+```typescript
+// When fetching external components:
+// 1. Fetch spec from registry
+// 2. Calculate SHA-256 hash using Web Crypto API
+// 3. Compare with cached component's hash
+// 4. Recompile only if spec has changed
+
+// Note: Requires secure context (HTTPS or localhost)
+// Web Crypto API is used for consistent hashing across environments
+```
+
+#### Registry Types
+
+- **Local Registry** (`registry` field undefined): Components stored in local database
+- **External Registry** (`registry` field defined): Components fetched from remote registries via MJServer
+
 ## Configuration
 
 ### Compiler Configuration

package/dist/compiler/component-compiler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"component-compiler.d.ts","sourceRoot":"","sources":["../../src/compiler/component-compiler.ts"],"names":[],"mappings":"AAOA,OAAO,EACL,cAAc,EAEd,iBAAiB,EACjB,cAAc,EAGf,MAAM,UAAU,CAAC;AAyBlB,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,gBAAgB,CAAiC;IACzD,OAAO,CAAC,gBAAgB,CAAW;IACnC,OAAO,CAAC,aAAa,CAAM;gBAMf,MAAM,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC;IAS5C,gBAAgB,CAAC,KAAK,EAAE,GAAG,GAAG,IAAI;IAS5B,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAyElE,OAAO,CAAC,kBAAkB;IAmC1B,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAkC;IAEjE,OAAO,CAAC,iBAAiB;YAqRX,qBAAqB;YAqJrB,UAAU;IA+BxB,OAAO,CAAC,UAAU;IAyElB,OAAO,CAAC,sBAAsB;IA0E9B,OAAO,CAAC,sBAAsB;IAiE9B,OAAO,CAAC,mBAAmB;IAU3B,OAAO,CAAC,kBAAkB;IAY1B,OAAO,CAAC,cAAc;IAgBtB,OAAO,CAAC,cAAc;IAmBtB,OAAO,CAAC,sBAAsB;IAa9B,UAAU,IAAI,IAAI;IAQlB,YAAY,IAAI,MAAM;IAQtB,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,cAAc,CAAC,GAAG,IAAI;CAGpD"}
+{"version":3,"file":"component-compiler.d.ts","sourceRoot":"","sources":["../../src/compiler/component-compiler.ts"],"names":[],"mappings":"AAOA,OAAO,EACL,cAAc,EAEd,iBAAiB,EACjB,cAAc,EAGf,MAAM,UAAU,CAAC;AA0BlB,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,gBAAgB,CAAiC;IACzD,OAAO,CAAC,gBAAgB,CAAW;IACnC,OAAO,CAAC,aAAa,CAAM;gBAMf,MAAM,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC;IAS5C,gBAAgB,CAAC,KAAK,EAAE,GAAG,GAAG,IAAI;IAS5B,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,iBAAiB,CAAC;IA2ElE,OAAO,CAAC,kBAAkB;IAmC1B,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAkC;IAEjE,OAAO,CAAC,iBAAiB;YA2RX,qBAAqB;YAiKrB,UAAU;IA+BxB,OAAO,CAAC,UAAU;IA0ElB,OAAO,CAAC,sBAAsB;IAkI9B,OAAO,CAAC,sBAAsB;IAiE9B,OAAO,CAAC,mBAAmB;IAU3B,OAAO,CAAC,kBAAkB;IAY1B,OAAO,CAAC,cAAc;IAgBtB,OAAO,CAAC,cAAc;IAmBtB,OAAO,CAAC,sBAAsB;IAa9B,UAAU,IAAI,IAAI;IAQlB,YAAY,IAAI,MAAM;IAQtB,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,cAAc,CAAC,GAAG,IAAI;CAGpD"}

package/dist/compiler/component-compiler.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ComponentCompiler = void 0;
 const library_registry_1 = require("../utilities/library-registry");
 const library_loader_1 = require("../utilities/library-loader");
+const component_unwrapper_1 = require("../utilities/component-unwrapper");
 const DEFAULT_COMPILER_CONFIG = {
     babel: {
         presets: ['react'],
@@ -39,7 +40,7 @@ class ComponentCompiler {
             this.validateCompileOptions(options);
             const loadedLibraries = await this.loadRequiredLibraries(options.libraries, options.allLibraries);
             const transpiledCode = this.transpileComponent(options.componentCode, options.componentName, options);
-            const componentFactory = this.createComponentFactory(transpiledCode, options.componentName, loadedLibraries);
+            const componentFactory = this.createComponentFactory(transpiledCode, options.componentName, loadedLibraries, options);
             const compiledComponent = {
                 factory: componentFactory,
                 id: this.generateComponentId(options.componentName),
@@ -54,7 +55,8 @@ class ComponentCompiler {
                 success: true,
                 component: compiledComponent,
                 duration: Date.now() - startTime,
-                size: transpiledCode.length
+                size: transpiledCode.length,
+                loadedLibraries: loadedLibraries
             };
         }
         catch (error) {
@@ -144,13 +146,19 @@ class ComponentCompiler {
       function createComponent(
         React, ReactDOM, 
         useState, useEffect, useCallback, useMemo, useRef, useContext, useReducer, useLayoutEffect,
-        libraries, styles, console, components
+        libraries, styles, console, components,
+        unwrapLibraryComponent, unwrapLibraryComponents, unwrapAllLibraryComponents
       ) {
         if (!React)
             console.log('[React-Runtime-JS] React is not defined');
         if (!ReactDOM)
             console.log('[React-Runtime-JS] ReactDOM is not defined');
 
+        // Make unwrap functions available with legacy names for backward compatibility
+        const unwrapComponent = unwrapLibraryComponent;
+        const unwrapComponents = unwrapLibraryComponents;
+        const unwrapAllComponents = unwrapAllLibraryComponents;
+        
         // Code for ${componentName}
         ${componentCode}
         
@@ -369,6 +377,14 @@ class ComponentCompiler {
                 console.warn(`⚠️ Invalid library entry detected (missing name):`, lib);
                 return false;
             }
+            if (lib.name === 'unknown' || lib.name === 'null' || lib.name === 'undefined') {
+                console.warn(`⚠️ Filtering out invalid library with name '${lib.name}':`, lib);
+                return false;
+            }
+            if (!lib.globalVariable || lib.globalVariable === 'undefined' || lib.globalVariable === 'null') {
+                console.warn(`⚠️ Filtering out library '${lib.name}' with invalid globalVariable:`, lib.globalVariable);
+                return false;
+            }
             const libNameLower = lib.name.toLowerCase();
             if (libNameLower === 'react' || libNameLower === 'reactdom') {
                 console.warn(`⚠️ Library '${lib.name}' is automatically loaded by the React runtime and should not be requested separately`);
@@ -522,17 +538,52 @@ class ComponentCompiler {
             document.head.appendChild(script);
         });
     }
-    createComponentFactory(transpiledCode, componentName, loadedLibraries) {
+    createComponentFactory(transpiledCode, componentName, loadedLibraries, options) {
         try {
-            const factoryCreator = new Function('React', 'ReactDOM', 'useState', 'useEffect', 'useCallback', 'useMemo', 'useRef', 'useContext', 'useReducer', 'useLayoutEffect', 'libraries', 'styles', 'console', 'components', `${transpiledCode}; return createComponent;`);
+            const factoryCreator = new Function('React', 'ReactDOM', 'useState', 'useEffect', 'useCallback', 'useMemo', 'useRef', 'useContext', 'useReducer', 'useLayoutEffect', 'libraries', 'styles', 'console', 'components', 'unwrapLibraryComponent', 'unwrapLibraryComponents', 'unwrapAllLibraryComponents', `${transpiledCode}; return createComponent;`);
             return (context, styles = {}, components = {}) => {
                 const { React, ReactDOM, libraries = {} } = context;
+                if (!React) {
+                    console.error('🔴 CRITICAL: React is NULL in createComponentFactory!');
+                    console.error('Context provided:', context);
+                    console.error('Context keys:', Object.keys(context));
+                    throw new Error('React is null in runtime context when creating component factory');
+                }
+                if (!React.useState || !React.useEffect) {
+                    console.error('🔴 CRITICAL: React hooks are missing!');
+                    console.error('React object keys:', React ? Object.keys(React) : 'React is null');
+                    console.error('useState:', typeof React?.useState);
+                    console.error('useEffect:', typeof React?.useEffect);
+                }
                 const mergedLibraries = { ...libraries };
+                const specLibraryNames = new Set((options.libraries || []).map((lib) => lib.globalVariable).filter(Boolean));
                 loadedLibraries.forEach((value, key) => {
-                    mergedLibraries[key] = value;
+                    if (specLibraryNames.has(key)) {
+                        mergedLibraries[key] = value;
+                    }
+                    else if (this.config.debug) {
+                        console.log(`⚠️ Filtering out dependency-only library: ${key}`);
+                    }
                 });
-                const createComponentFn = factoryCreator(React, ReactDOM, React.useState, React.useEffect, React.useCallback, React.useMemo, React.useRef, React.useContext, React.useReducer, React.useLayoutEffect, mergedLibraries, styles, console, components);
-                const Component = createComponentFn(React, ReactDOM, React.useState, React.useEffect, React.useCallback, React.useMemo, React.useRef, React.useContext, React.useReducer, React.useLayoutEffect, mergedLibraries, styles, console, components);
+                const boundUnwrapLibraryComponent = (lib, name) => (0, component_unwrapper_1.unwrapLibraryComponent)(lib, name, this.config.debug);
+                const boundUnwrapLibraryComponents = (lib, ...names) => (0, component_unwrapper_1.unwrapLibraryComponents)(lib, ...names, this.config.debug);
+                const boundUnwrapAllLibraryComponents = (lib) => (0, component_unwrapper_1.unwrapAllLibraryComponents)(lib, this.config.debug);
+                let createComponentFn;
+                try {
+                    createComponentFn = factoryCreator(React, ReactDOM, React.useState, React.useEffect, React.useCallback, React.useMemo, React.useRef, React.useContext, React.useReducer, React.useLayoutEffect, mergedLibraries, styles, console, components, boundUnwrapLibraryComponent, boundUnwrapLibraryComponents, boundUnwrapAllLibraryComponents);
+                }
+                catch (error) {
+                    console.error('🔴 CRITICAL: Error calling factoryCreator with React hooks!');
+                    console.error('Error:', error?.message || error);
+                    console.error('React is:', React);
+                    console.error('React type:', typeof React);
+                    if (React) {
+                        console.error('React.useState:', typeof React.useState);
+                        console.error('React.useEffect:', typeof React.useEffect);
+                    }
+                    throw new Error(`Failed to create component factory: ${error?.message || error}`);
+                }
+                const Component = createComponentFn(React, ReactDOM, React.useState, React.useEffect, React.useCallback, React.useMemo, React.useRef, React.useContext, React.useReducer, React.useLayoutEffect, mergedLibraries, styles, console, components, boundUnwrapLibraryComponent, boundUnwrapLibraryComponents, boundUnwrapAllLibraryComponents);
                 return Component;
             };
         }