@pushwoosh/spa-context 3.4.0 → 3.5.0

package/RemoteComponent.d.ts

@@ -0,0 +1,23 @@
+import { type FormEvent, type ReactNode } from 'react';
+export type RemoteComponentProps = {
+    /** Import-map name of the module. */
+    module: string;
+    /** Named export of the module; must be a React component. */
+    component: string;
+    /** Rendered while the module loads. */
+    fallback?: ReactNode;
+    /** Rendered when the component throws while rendering. */
+    errorFallback?: ReactNode;
+    /** A failed import, a missing or non-component export, or a render error. */
+    onError?: (error: Error) => void;
+    /** The component has rendered. */
+    onReady?: () => void;
+    [prop: string]: unknown;
+};
+/** Renders a named export of an import-map module in the consumer's React tree, with the consumer's spaContext. */
+export declare const RemoteComponent: ({ module, component, fallback, errorFallback, onError, onReady, ...props }: RemoteComponentProps) => import("react").DetailedReactHTMLElement<{
+    style: {
+        readonly display: "contents";
+    };
+    onSubmit: (event: FormEvent) => void;
+}, HTMLElement>;

package/RemoteComponent.js

@@ -0,0 +1,58 @@
+import { createElement, useEffect } from 'react';
+import { SPAContext } from './context';
+import { DefaultErrorFallback, RemoteErrorBoundary } from './RemoteErrorBoundary';
+import { useRemoteComponent } from './useRemoteComponent';
+import { useSPAContext } from './useSPAContext';
+// No JSX here or in RemoteErrorBoundary: the CDN bundle keeps importing only `react`.
+const WRAPPER_STYLE = {
+  display: 'contents'
+};
+// A form inside the remote component, portals included, must not submit the consumer's form.
+const stopSubmit = event => event.stopPropagation();
+const Ready = ({
+  onReady
+}) => {
+  useEffect(() => {
+    onReady();
+  }, []); // eslint-disable-line react-hooks/exhaustive-deps
+  return null;
+};
+/** Renders a named export of an import-map module in the consumer's React tree, with the consumer's spaContext. */
+export const RemoteComponent = ({
+  module,
+  component,
+  fallback = null,
+  errorFallback = createElement(DefaultErrorFallback),
+  onError,
+  onReady,
+  ...props
+}) => {
+  const spaContext = useSPAContext();
+  const state = useRemoteComponent(module, component);
+  useEffect(() => {
+    if (state.status !== 'failed') return;
+    console.error(state.error);
+    onError?.(state.error);
+  }, [state]); // eslint-disable-line react-hooks/exhaustive-deps
+  let content = null;
+  if (state.status === 'loading') content = fallback;
+  if (state.status === 'ready') {
+    content = createElement(RemoteErrorBoundary, {
+      key: `${module}\n${component}`,
+      module,
+      fallback: errorFallback,
+      onError: error => onError?.(error)
+    }, createElement(SPAContext, {
+      value: spaContext
+    }, createElement(state.Component, {
+      ...props,
+      spaContext
+    })), createElement(Ready, {
+      onReady: () => onReady?.()
+    }));
+  }
+  return createElement('div', {
+    style: WRAPPER_STYLE,
+    onSubmit: stopSubmit
+  }, content);
+};

package/RemoteErrorBoundary.d.ts

@@ -0,0 +1,30 @@
+import { Component, type ErrorInfo, type ReactNode } from 'react';
+export declare const DefaultErrorFallback: () => import("react").DetailedReactHTMLElement<{
+    style: {
+        display: "flex";
+        flexDirection: "column";
+        alignItems: "center";
+        justifyContent: "center";
+        maxWidth: number;
+        margin: string;
+        padding: number;
+        textAlign: "center";
+    };
+}, HTMLElement>;
+type RemoteErrorBoundaryProps = {
+    module: string;
+    fallback: ReactNode;
+    onError: (error: Error) => void;
+    children?: ReactNode;
+};
+export declare class RemoteErrorBoundary extends Component<RemoteErrorBoundaryProps, {
+    hasError: boolean;
+}> {
+    constructor(props: RemoteErrorBoundaryProps);
+    static getDerivedStateFromError(): {
+        hasError: boolean;
+    };
+    componentDidCatch(error: Error, errorInfo: ErrorInfo): void;
+    render(): ReactNode;
+}
+export {};

package/RemoteErrorBoundary.js

@@ -0,0 +1,44 @@
+import { Component, createElement } from 'react';
+export const DefaultErrorFallback = () => createElement('div', {
+  style: {
+    display: 'flex',
+    flexDirection: 'column',
+    alignItems: 'center',
+    justifyContent: 'center',
+    maxWidth: 520,
+    margin: '64px auto',
+    padding: 24,
+    textAlign: 'center'
+  }
+}, createElement('h2', {
+  style: {
+    margin: '0 0 8px',
+    fontSize: 20,
+    fontWeight: 500
+  }
+}, 'Something went wrong'), createElement('p', {
+  style: {
+    margin: 0,
+    color: '#7C8595'
+  }
+}, 'Please refresh the page or try again later.'));
+export class RemoteErrorBoundary extends Component {
+  constructor(props) {
+    super(props);
+    this.state = {
+      hasError: false
+    };
+  }
+  static getDerivedStateFromError() {
+    return {
+      hasError: true
+    };
+  }
+  componentDidCatch(error, errorInfo) {
+    console.error(`RemoteComponent ${this.props.module} caught an error`, error, errorInfo);
+    this.props.onError(error);
+  }
+  render() {
+    return this.state.hasError ? this.props.fallback : this.props.children;
+  }
+}

package/index.d.ts

@@ -1,12 +1,15 @@
 import { stateOfVersion } from './approvals';
 import type { ApprovalState, DecidedRequest, VersionState } from './approvals';
+import { loadModule } from './loadModule';
+import { RemoteComponent, type RemoteComponentProps } from './RemoteComponent';
 import { SimpleEventEmitter } from './SimpleEventEmitter';
 import type { Environment, SPAContextType } from './types';
 import { UniversalKeyValueStore } from './UniversalKeyValueStore';
 import { useEventValue } from './useEventValue';
 import { useMemoryKey, useMemoryKeySlim } from './useMemoryKey';
+import { type RemoteComponentState, useRemoteComponent } from './useRemoteComponent';
 import { useSession } from './useSession';
 import { useSPAContext } from './useSPAContext';
-export type { Environment, SPAContextType, ApprovalState, DecidedRequest, VersionState };
-export { useSPAContext, useSession, useEventValue, useMemoryKey, useMemoryKeySlim, SimpleEventEmitter, UniversalKeyValueStore, stateOfVersion, };
+export type { Environment, SPAContextType, ApprovalState, DecidedRequest, VersionState, RemoteComponentProps, RemoteComponentState, };
+export { useSPAContext, useSession, useEventValue, useMemoryKey, useMemoryKeySlim, SimpleEventEmitter, UniversalKeyValueStore, stateOfVersion, RemoteComponent, useRemoteComponent, loadModule, };
 export declare const SPAContextProvider: import("react").Provider<SPAContextType | undefined>;

package/index.js

@@ -1,10 +1,13 @@
 import { stateOfVersion } from './approvals';
 import { SPAContext } from './context';
+import { loadModule } from './loadModule';
+import { RemoteComponent } from './RemoteComponent';
 import { SimpleEventEmitter } from './SimpleEventEmitter';
 import { UniversalKeyValueStore } from './UniversalKeyValueStore';
 import { useEventValue } from './useEventValue';
 import { useMemoryKey, useMemoryKeySlim } from './useMemoryKey';
+import { useRemoteComponent } from './useRemoteComponent';
 import { useSession } from './useSession';
 import { useSPAContext } from './useSPAContext';
-export { useSPAContext, useSession, useEventValue, useMemoryKey, useMemoryKeySlim, SimpleEventEmitter, UniversalKeyValueStore, stateOfVersion };
+export { useSPAContext, useSession, useEventValue, useMemoryKey, useMemoryKeySlim, SimpleEventEmitter, UniversalKeyValueStore, stateOfVersion, RemoteComponent, useRemoteComponent, loadModule };
 export const SPAContextProvider = SPAContext.Provider;

package/loadModule.d.ts

@@ -0,0 +1,2 @@
+/** Loads a module by import-map name through native `import()`. */
+export declare function loadModule<T = unknown>(name: string): Promise<T>;

package/loadModule.js

@@ -0,0 +1,4 @@
+/** Loads a module by import-map name through native `import()`. */
+export function loadModule(name) {
+  return import(/* webpackIgnore: true */name);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pushwoosh/spa-context",
-  "version": "3.4.0",
+  "version": "3.5.0",
   "description": "React context giving every micro-frontend its HTTP/RPC clients, session store, routing, event bus and key-value storage",
   "repository": {
     "type": "git",
@@ -15,15 +15,29 @@
     "access": "public",
     "directory": "dist"
   },
+  "pushwoosh": {
+    "cdn": {
+      "path": "spa-context",
+      "dir": "cdn-dist",
+      "importMap": [
+        "@pushwoosh/spa-context"
+      ]
+    }
+  },
   "dependencies": {
     "idb-keyval": "^6.2.2"
   },
   "devDependencies": {
     "@pushwoosh/http-client": "^2.12.0",
-    "@pushwoosh/rpc-v2-http-api-data": "^0.2.524",
+    "@pushwoosh/rpc-v2-http-api-data": "^0.2.534",
     "@pushwoosh/session-store": "^2.14.0",
     "@types/history": "^4.7.11",
-    "@types/react": "^19.3.0"
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "jsdom": "^26.1.0",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
+    "vitest": "^4.1.10"
   },
   "peerDependencies": {
     "@pushwoosh/http-client": "^2.5.0",
@@ -78,10 +92,11 @@
     "node": ">= 24"
   },
   "scripts": {
-    "build": "pushwoosh-engine lib:build",
-    "check": "pnpm run check:lint && pnpm run check:types",
+    "build": "pushwoosh-engine lib:build && `pushwoosh-engine app:command:build`",
+    "check": "pnpm run check:lint && pnpm run check:types && pnpm run test",
     "check:lint": "echo \"Run check:lint\" && NODE_ENV=production eslint ./src",
     "check:lint-fix": "echo \"Run check:lint\" && NODE_ENV=production eslint ./src --fix",
-    "check:types": "echo \"Run check:types\" && pushwoosh-engine lib:check-types"
+    "check:types": "echo \"Run check:types\" && pushwoosh-engine lib:check-types",
+    "test": "echo \"Run test\" && vitest run"
   }
 }

package/remoteExport.d.ts

@@ -0,0 +1,3 @@
+import { type ComponentType } from 'react';
+/** The export as a React component, or the error `RemoteComponent` reports when it is missing or of another shape. */
+export declare function remoteComponent(module: string, component: string, exported: unknown): ComponentType<any> | Error;

package/remoteExport.js

@@ -0,0 +1,13 @@
+const elementTypes = new Set([Symbol.for('react.memo'), Symbol.for('react.forward_ref')]);
+const isWrappedComponent = value => typeof value === 'object' && value !== null && elementTypes.has(value.$$typeof);
+/** The export as a React component, or the error `RemoteComponent` reports when it is missing or of another shape. */
+export function remoteComponent(module, component, exported) {
+  if (exported === undefined) {
+    return new Error(`RemoteComponent ${module}: the module has no export "${component}"`);
+  }
+  // A createParcelFunction factory is a function too; its .Component is what the old <Parcel> rendered.
+  if (typeof exported === 'function' && !('Component' in exported) || isWrappedComponent(exported)) {
+    return exported;
+  }
+  return new Error(`RemoteComponent ${module}: export "${component}" is not a React component ` + '(expected a function, class, memo or forwardRef; an object with .Component or a parcel factory is not supported)');
+}

package/useRemoteComponent.d.ts

@@ -0,0 +1,12 @@
+import { type ComponentType } from 'react';
+export type RemoteComponentState<P = any> = {
+    status: 'loading';
+} | {
+    status: 'ready';
+    Component: ComponentType<P>;
+} | {
+    status: 'failed';
+    error: Error;
+};
+/** Loads `component` from the import-map module `module`; a new pair drops the old result and loads again. */
+export declare function useRemoteComponent<P = any>(module: string, component: string): RemoteComponentState<P>;

package/useRemoteComponent.js

@@ -0,0 +1,38 @@
+import { useEffect, useState } from 'react';
+import { loadModule } from './loadModule';
+import { remoteComponent } from './remoteExport';
+const LOADING = {
+  status: 'loading'
+};
+const toError = error => error instanceof Error ? error : new Error(String(error));
+/** Loads `component` from the import-map module `module`; a new pair drops the old result and loads again. */
+export function useRemoteComponent(module, component) {
+  const key = `${module}\n${component}`;
+  const [loaded, setLoaded] = useState(null);
+  useEffect(() => {
+    let cancelled = false;
+    const settle = state => {
+      if (!cancelled) setLoaded({
+        key,
+        state
+      });
+    };
+    loadModule(module).then(imported => {
+      const resolved = remoteComponent(module, component, imported[component]);
+      settle(resolved instanceof Error ? {
+        status: 'failed',
+        error: resolved
+      } : {
+        status: 'ready',
+        Component: resolved
+      });
+    }, error => settle({
+      status: 'failed',
+      error: toError(error)
+    }));
+    return () => {
+      cancelled = true;
+    };
+  }, [key, module, component]);
+  return loaded?.key === key ? loaded.state : LOADING;
+}