add lazyCreateConnectedComponent (Like React.lazy but for repluggable) (#304)

bodia-uz · web-flow · commit c8561b91060b · 2025-04-16T14:44:06.000+03:00
* add `lazyCreateConnectedComponent` (Like `React.lazy` but for repluggable)

Like `React.lazy` but for components created with repluggable `createConnected` function.

* improve tests

* Update lazyCreateConnectedComponent.ts with additional jsdoc
diff --git a/packages/repluggable/src/index.ts b/packages/repluggable/src/index.ts
@@ -36,6 +36,7 @@ export { SlotRenderer, ShellRenderer } from './renderSlotComponents'
 export { invokeSlotCallbacks } from './invokeSlotCallbacks'
 
 export * from './connectWithShell'
+export * from './lazyCreateConnectedComponent'
 export { ErrorBoundary } from './errorBoundary'
 export { interceptEntryPoints, interceptEntryPointsMap } from './interceptEntryPoints'
 export { interceptAnyObject } from './interceptAnyObject'
diff --git a/packages/repluggable/src/lazyCreateConnectedComponent.ts b/packages/repluggable/src/lazyCreateConnectedComponent.ts
@@ -0,0 +1,104 @@
+import React from 'react'
+
+import { Shell } from './API'
+
+type CreateConnectedComponent<T extends React.ComponentType<any>> = (boundShell: Shell) => T
+
+export interface LazyConnectedComponent<T extends React.ComponentType<any>> extends React.LazyExoticComponent<T> {
+    /**
+     * Preloads the connected component to ensure it is ready before rendering.
+     * Useful for optimizing performance in scenarios where the component will be needed soon.
+     *
+     * @example
+     *
+     * ```ts
+     * const Component = lazyCreateConnectedComponent(shell, () => import('./AddPanel'));
+     *
+     * // preload the component
+     * onMouseHover(() => {
+     *   Component.preload();
+     * });
+     * ```
+     */
+    preload(): Promise<void>
+}
+
+/**
+ * Like `React.lazy` but for components created with repluggable `createConnected` function.
+ * @see {@link https://react.dev/reference/react/lazy React Docs}
+ *
+ * @example <caption>having `./AddPanel.tsx` - module with **default** export of createConnected function</caption>
+ * ```ts
+ * const Component = lazyCreateConnectedComponent(shell,
+ *   () => import('./AddPanel')
+ * );
+ *
+ * // `./AddPanel.tsx`
+ * export default function createConnectedAddPanel(shell: Shell) { ...}
+ * ```
+ * @example <caption>having `./AddPanel.tsx` - module with **named** export of createConnected function</caption>
+ * ```ts
+ * const Component = lazyCreateConnectedComponent(shell,
+ *   () => import('./AddPanel').then(module => module.createConnectedAddPanel)
+ * );
+ *
+ * // `./AddPanel.tsx`
+ * export function createConnectedAddPanel(shell: Shell) { ... }
+ * ```
+ */
+export function lazyCreateConnectedComponent<T extends React.ComponentType<any>>(
+    fromShell: Shell,
+    loadComponentFactory: () => Promise<{ default: CreateConnectedComponent<T> } | CreateConnectedComponent<T>>
+): LazyConnectedComponent<T> {
+    let loadComponentPromise: Promise<T>
+    async function loadComponent() {
+        loadComponentPromise ??= loadComponentFactory().then(componentFactoryModuleOrFn => {
+            const componentFactory =
+                typeof componentFactoryModuleOrFn === 'function' ? componentFactoryModuleOrFn : componentFactoryModuleOrFn?.default
+
+            if (typeof componentFactory !== 'function') {
+                throw new Error(
+                    'Expected a createConnected function or a module with a default export of one.\n' +
+                        `Received: ${typeof componentFactory}. Please ensure the module exports the correct function.`
+                )
+            }
+
+            const Component = fromShell.runLateInitializer(() => componentFactory(fromShell))
+
+            return Component
+        })
+
+        return loadComponentPromise
+    }
+
+    /**
+     * Preloads the connected component to ensure it is ready before rendering.
+     * Useful for optimizing performance in scenarios where the component will be needed soon.
+     *
+     * @example
+     *
+     * ```ts
+     * const Component = lazyCreateConnectedComponent(shell, () => import('./AddPanel'));
+     *
+     * // preload the component
+     * onMouseHover(() => {
+     *   Component.preload();
+     * });
+     * ```
+     */
+    async function preload() {
+        await loadComponent()
+    }
+
+    const LazyComponent = React.lazy<T>(async () => {
+        const Component = await loadComponent()
+
+        // NOTE: satisfy React.lazy expectation for module with default export
+        return { default: Component }
+    })
+
+    // NOTE: `Object.assign` is OK here,
+    // so disable "prefer-object-spread"
+    /* tslint:disable-next-line */
+    return Object.assign(LazyComponent, { preload })
+}
diff --git a/packages/repluggable/test/lazyCreateConnectedComponent.spec.tsx b/packages/repluggable/test/lazyCreateConnectedComponent.spec.tsx
@@ -0,0 +1,183 @@
+import React from 'react'
+
+import { lazyCreateConnectedComponent } from '../src'
+import { Shell } from '../src/API'
+import { addMockShell, collectAllTexts, connectWithShell, createAppHost, renderInHost } from '../testKit'
+
+function createFallbackTrackerComponent(label: string = 'loading...') {
+    let handleMounted: () => void
+    let handleUnmounted: () => void
+    const mountedPromise = new Promise<void>(resolve => {
+        handleMounted = resolve
+    })
+    const unmountedPromise = new Promise<void>(resolve => {
+        handleUnmounted = resolve
+    })
+
+    const Fallback: React.FC = () => {
+        React.useEffect(() => {
+            handleMounted()
+            return handleUnmounted
+        }, [])
+        return <div>{label}</div>
+    }
+
+    // NOTE: `Object.assign` is OK here,
+    // so disable "prefer-object-spread"
+    /* tslint:disable-next-line */
+  return Object.assign(Fallback, {
+        LABEL: label,
+        waitMounted: () => mountedPromise,
+        waitUnmounted: () => unmountedPromise
+    })
+}
+
+const TEXT_IN_LAZY_COMPONENT = 'HELLO FROM LAZY COMPONENT'
+
+const lazyComponentFactoryMock = (() => {
+    interface MyComponentStateProps {
+        foo: string
+    }
+
+    interface MyComponentOwnProps {
+        bar?: string
+    }
+
+    const MyComponent: React.FC<MyComponentStateProps & MyComponentOwnProps> = props => (
+        <div className="my-component">
+            {props.foo}
+            <span>{props.bar}</span>
+        </div>
+    )
+
+    const createMyComponent = (boundShell: Shell) =>
+        connectWithShell<{}, MyComponentOwnProps, MyComponentStateProps>(
+            () => ({
+                foo: TEXT_IN_LAZY_COMPONENT
+            }),
+            undefined,
+            boundShell
+        )(MyComponent)
+
+    return {
+        /**
+         * represents a module with a named export
+         * @example
+         * ```
+         * export function createMyComponent(shell: Shell) {}
+         * ```
+         */
+        loadWithNamedExport: async () => ({
+            createMyComponent
+        }),
+        /**
+         * represents a module with a default export
+         * @example
+         * ```
+         * export default function createMyComponent(shell: Shell) {}
+         * ```
+         */
+        loadWithDefaultExport: async () => ({
+            default: createMyComponent
+        })
+    }
+})()
+
+describe.each([
+    ["with 'default export' module", () => lazyComponentFactoryMock.loadWithDefaultExport()],
+    ["with 'named export' module", () => lazyComponentFactoryMock.loadWithNamedExport().then(module => module.createMyComponent)]
+])('lazyCreateConnectedComponent (loadComponentFactory %s)', (_, loadComponentFactory) => {
+    it('should create and render connected component from lazy factory', async () => {
+        const host = createAppHost([])
+        const boundShell = addMockShell(host)
+
+        const MyComponent = lazyCreateConnectedComponent(boundShell, loadComponentFactory)
+
+        const FallbackTracker = createFallbackTrackerComponent()
+
+        const { parentWrapper } = renderInHost(
+            <React.Suspense fallback={<FallbackTracker />}>
+                <MyComponent />
+            </React.Suspense>,
+            host
+        )
+
+        // Check that the component shows the fallback, while the lazy component is loading
+        expect(collectAllTexts(parentWrapper)).toContain(FallbackTracker.LABEL)
+        expect(collectAllTexts(parentWrapper)).not.toContain(TEXT_IN_LAZY_COMPONENT)
+
+        await FallbackTracker.waitUnmounted()
+
+        // Check that the component shows the loaded content
+        expect(collectAllTexts(parentWrapper)).not.toContain(FallbackTracker.LABEL)
+        expect(collectAllTexts(parentWrapper)).toContain(TEXT_IN_LAZY_COMPONENT)
+    })
+
+    it('should create and render connected componet with forwarding own props', async () => {
+        const host = createAppHost([])
+        const boundShell = addMockShell(host)
+
+        const MyComponent = lazyCreateConnectedComponent(boundShell, loadComponentFactory)
+
+        const FallbackTracker = createFallbackTrackerComponent()
+
+        const TEST_PROP = 'HELLO_FROM_PROPS'
+
+        const { parentWrapper } = renderInHost(
+            <React.Suspense fallback={<FallbackTracker />}>
+                <MyComponent bar={TEST_PROP} />
+            </React.Suspense>,
+            host
+        )
+
+        expect(collectAllTexts(parentWrapper)).not.toContain(TEST_PROP)
+
+        await FallbackTracker.waitUnmounted()
+
+        expect(collectAllTexts(parentWrapper)).toContain(TEST_PROP)
+    })
+
+    it('should call `loadComponentFactory` only after first render', async () => {
+        const host = createAppHost([])
+        const boundShell = addMockShell(host)
+
+        const loadComponentFactorySpy = jest.fn(() => loadComponentFactory())
+
+        const MyComponent = lazyCreateConnectedComponent(boundShell, loadComponentFactorySpy)
+
+        expect(loadComponentFactorySpy).not.toHaveBeenCalled()
+
+        renderInHost(
+            <React.Suspense fallback={null}>
+                <MyComponent />
+            </React.Suspense>,
+            host
+        )
+
+        expect(loadComponentFactorySpy).toHaveBeenCalled()
+    })
+
+    it('should preload component with `loadComponentFactory` on `Component.preload` call', async () => {
+        const host = createAppHost([])
+        const boundShell = addMockShell(host)
+
+        const loadComponentFactorySpy = jest.fn(() => loadComponentFactory())
+
+        const MyComponent = lazyCreateConnectedComponent(boundShell, loadComponentFactorySpy)
+
+        expect(loadComponentFactorySpy).not.toHaveBeenCalled()
+
+        MyComponent.preload()
+
+        expect(loadComponentFactorySpy).toHaveBeenCalled()
+
+        renderInHost(
+            <React.Suspense fallback={null}>
+                <MyComponent />
+            </React.Suspense>,
+            host
+        )
+
+        expect(loadComponentFactorySpy).toHaveBeenCalledTimes(1)
+    })
+})
