@rmc-toolkit/react 0.1.0 → 0.2.3

package/README.md

@@ -0,0 +1,86 @@
+# @rmc-toolkit/react
+
+React adapter for [Runtime Module Composition](https://runtime-module-composition.dev). Two factories, for two different slice conventions — pick the one matching how your slices are written, not both for the same slice. Both take your app's own already-resolved `React` instance rather than importing one themselves, so this package never bundles a second, conflicting copy of React.
+
+## Install
+
+```bash
+npm install @rmc-toolkit/react @rmc-toolkit/core react
+```
+
+## Quick example
+
+**Slices share the `mount()`/`unmount()` convention:** use `createReactAdapter`, which wraps the resolve/import/mount lifecycle in a `useRuntimeHost` hook:
+
+```ts
+// src/rmc-adapter.ts
+import React from "react";
+import { createReactAdapter } from "@rmc-toolkit/react";
+
+export const { useRuntimeHost } = createReactAdapter(React);
+```
+
+```tsx
+// App.tsx
+import { useLocation } from "react-router-dom";
+import { useRuntimeHost } from "./rmc-adapter";
+import { manifest } from "./runtime-composition.manifest";
+
+function App() {
+  const location = useLocation();
+  const { ref, status } = useRuntimeHost<HTMLElement>(location.pathname, { manifest });
+
+  return (
+    <div className="app-shell">
+      <SiteHeader loading={status.type === "loading"} />
+      <main ref={ref} />
+      <SiteFooter />
+    </div>
+  );
+}
+```
+
+**Slices are plain default-exported components (not `mount()`/`unmount()`):** use `createDynamicModuleBoundary` instead:
+
+```tsx
+// src/rmc-adapter.ts
+import React from "react";
+import { createDynamicModuleBoundary } from "@rmc-toolkit/react";
+
+export const { DynamicModuleBoundary } = createDynamicModuleBoundary(React);
+```
+
+```tsx
+// RouteSlot.tsx
+import { resolveRoute } from "@rmc-toolkit/core";
+import { DynamicModuleBoundary } from "./rmc-adapter";
+import { manifest } from "./runtime-composition.manifest";
+
+export function RouteSlot() {
+  const match = resolveRoute(manifest, window.location.pathname);
+  if (!match) return null;
+
+  return (
+    <DynamicModuleBoundary
+      specifier={match.specifier}
+      context={{ route: match, manifest }}
+      fallback={<div>Loading...</div>}
+      errorFallback={<div>Unable to load this section.</div>}
+    />
+  );
+}
+```
+
+## What's in here
+
+- `createReactAdapter(React)` → `{ useRuntimeHost }` — a hook wrapping `createRuntimeHostObservable`'s resolve/import/mount/unmount lifecycle, with loading/error status.
+- `createDynamicModuleBoundary(React)` → `{ DynamicModuleBoundary }` — a `Suspense` + error-boundary component around `React.lazy()`-loading a slice's default-exported component.
+
+Full signatures and behavior for both: [API Reference](https://runtime-module-composition.dev/api-reference/#react-adapter-rmc-toolkitreact).
+
+## Documentation
+
+- [Getting Started](https://runtime-module-composition.dev/getting-started/) — install and wire up a host + slice end to end
+- [API Reference](https://runtime-module-composition.dev/api-reference/#react-adapter-rmc-toolkitreact)
+- [Technical Implementation](https://runtime-module-composition.dev/technical-implementation/) — the architecture and failure modes behind the pattern
+- [Multi-Framework Demo](https://runtime-module-composition.dev/demo/) — a full, runnable reference implementation, including a React slice

package/dist/create-dynamic-module-boundary.d.ts

@@ -0,0 +1,13 @@
+import type * as ReactNamespace from "react";
+import { type DynamicImporter, type RuntimeModuleContext } from "@rmc-toolkit/core";
+export type DynamicModuleBoundaryProps = {
+    specifier: string;
+    context?: RuntimeModuleContext;
+    fallback?: ReactNamespace.ReactNode;
+    errorFallback?: ReactNamespace.ReactNode;
+    importer?: DynamicImporter;
+};
+export declare const createDynamicModuleBoundary: (React: typeof ReactNamespace) => {
+    DynamicModuleBoundary: (props: DynamicModuleBoundaryProps) => ReactNamespace.ReactElement;
+};
+//# sourceMappingURL=create-dynamic-module-boundary.d.ts.map

package/dist/create-dynamic-module-boundary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-dynamic-module-boundary.d.ts","sourceRoot":"","sources":["../src/create-dynamic-module-boundary.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,cAAc,MAAM,OAAO,CAAC;AAC7C,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,oBAAoB,EAC1B,MAAM,mBAAmB,CAAC;AAM3B,MAAM,MAAM,0BAA0B,GAAG;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,oBAAoB,CAAC;IAC/B,QAAQ,CAAC,EAAE,cAAc,CAAC,SAAS,CAAC;IACpC,aAAa,CAAC,EAAE,cAAc,CAAC,SAAS,CAAC;IACzC,QAAQ,CAAC,EAAE,eAAe,CAAC;CAC5B,CAAC;AAYF,eAAO,MAAM,2BAA2B,GACtC,OAAO,OAAO,cAAc,KAC3B;IACD,qBAAqB,EAAE,CAAC,KAAK,EAAE,0BAA0B,KAAK,cAAc,CAAC,YAAY,CAAC;CAiF3F,CAAC"}

package/dist/create-dynamic-module-boundary.js

@@ -0,0 +1,65 @@
+import { importModule, } from "@rmc-toolkit/core";
+const defaultImporter = importModule;
+// This file is intentionally `.ts`, not `.tsx`: with "jsx": "react-jsx" in
+// tsconfig.json, any JSX syntax in a file makes the compiler auto-inject a
+// runtime `import ... from "react/jsx-runtime"` that never appears in source.
+// That import would be just as unreconcilable with a host app's own React
+// instance as the top-level `import React from "react"` this factory is
+// fixing. So every element below is built with React.createElement(...)
+// (exactly what JSX desugars to) using the React namespace passed in as a
+// parameter, never a module-level import of "react" as a value.
+export const createDynamicModuleBoundary = (React) => {
+    // ErrorBoundary is redefined on every createDynamicModuleBoundary call
+    // rather than hoisted out as a module-level class: it extends the
+    // injected `React.Component`, and React class instances/statics
+    // (getDerivedStateFromError, etc.) are only valid against the exact
+    // React copy they were built from. Threading a second DI parameter
+    // through just for this base class would be over-engineering -- these
+    // factories are called once per host app at module scope, so redefining
+    // the class here has no meaningful runtime cost.
+    class ErrorBoundary extends React.Component {
+        state = { error: null };
+        static getDerivedStateFromError(error) {
+            return { error };
+        }
+        render() {
+            if (this.state.error) {
+                return this.props.fallback;
+            }
+            return this.props.children;
+        }
+    }
+    const DynamicModuleBoundary = ({ specifier, context, fallback = null, errorFallback = null, importer = defaultImporter, }) => {
+        // Memoized by specifier/importer: React.lazy() must return the same
+        // component type across renders, or React treats it as a brand-new
+        // component and remounts (re-suspending) on every parent re-render.
+        const LazyModule = React.useMemo(() => React.lazy(async () => {
+            const loadedModule = (await importer(specifier));
+            return loadedModule;
+        }), [specifier, importer]);
+        const moduleProps = context === undefined
+            ? {}
+            : { context };
+        // Equivalent to:
+        // <React.Suspense fallback={fallback}>
+        //   <ErrorBoundary fallback={errorFallback}>
+        //     <LazyModule {...moduleProps} />
+        //   </ErrorBoundary>
+        // </React.Suspense>
+        //
+        // `children` is passed inside ErrorBoundary's props object (rather than
+        // as a third createElement argument) to satisfy TypeScript's overload
+        // resolution, since ErrorBoundary's props type declares `children` as
+        // required -- it is the same substitution JSX itself performs, not an
+        // accidental extra prop.
+        return React.createElement(React.Suspense, { fallback }, React.createElement(ErrorBoundary, {
+            // Keyed by specifier so switching modules mounts a fresh
+            // ErrorBoundary instance instead of reusing one still holding a
+            // previous module's error state.
+            key: specifier,
+            fallback: errorFallback,
+            children: React.createElement(LazyModule, moduleProps),
+        }));
+    };
+    return { DynamicModuleBoundary };
+};

package/dist/create-react-adapter.d.ts

@@ -0,0 +1,11 @@
+import type * as ReactNamespace from "react";
+import { type RuntimeHostObservableOptions, type RuntimeHostStatus } from "@rmc-toolkit/core";
+export type UseRuntimeHostOptions = Omit<RuntimeHostObservableOptions, "target">;
+export type UseRuntimeHostResult<T extends Element> = {
+    ref: ReactNamespace.RefObject<T | null>;
+    status: RuntimeHostStatus;
+};
+export declare const createReactAdapter: (React: typeof ReactNamespace) => {
+    useRuntimeHost<T extends Element>(path: string, options: UseRuntimeHostOptions): UseRuntimeHostResult<T>;
+};
+//# sourceMappingURL=create-react-adapter.d.ts.map

package/dist/create-react-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-react-adapter.d.ts","sourceRoot":"","sources":["../src/create-react-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,cAAc,MAAM,OAAO,CAAC;AAC7C,OAAO,EAGL,KAAK,4BAA4B,EACjC,KAAK,iBAAiB,EACvB,MAAM,mBAAmB,CAAC;AAE3B,MAAM,MAAM,qBAAqB,GAAG,IAAI,CAAC,4BAA4B,EAAE,QAAQ,CAAC,CAAC;AAEjF,MAAM,MAAM,oBAAoB,CAAC,CAAC,SAAS,OAAO,IAAI;IACpD,GAAG,EAAE,cAAc,CAAC,SAAS,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IACxC,MAAM,EAAE,iBAAiB,CAAC;CAC3B,CAAC;AAQF,eAAO,MAAM,kBAAkB,GAC7B,OAAO,OAAO,cAAc,KAC3B;IACD,cAAc,CAAC,CAAC,SAAS,OAAO,EAC9B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,qBAAqB,GAC7B,oBAAoB,CAAC,CAAC,CAAC,CAAC;CAoD5B,CAAC"}

package/dist/create-react-adapter.js

@@ -0,0 +1,45 @@
+import { createRuntimeHostObservable, } from "@rmc-toolkit/core";
+// Shared reference, not an inline `{ type: "idle" }` literal: useSyncExternalStore
+// compares getSnapshot()'s return value by reference and treats any change as "the
+// store changed". A fresh object on every call (before the observable exists) would
+// look like a change on every render and cause an infinite re-render loop.
+const idleStatus = { type: "idle" };
+export const createReactAdapter = (React) => {
+    const useRuntimeHost = (path, options) => {
+        const ref = React.useRef(null);
+        const observableRef = React.useRef(null);
+        React.useEffect(() => {
+            if (!ref.current) {
+                return;
+            }
+            const observable = createRuntimeHostObservable({ ...options, target: ref.current });
+            observableRef.current = observable;
+            return () => {
+                void observable.destroy();
+                observableRef.current = null;
+            };
+        }, []);
+        // Relies on React running a component's effects in declaration order on mount:
+        // the creation effect above must run first and populate observableRef.current
+        // before this effect's initial run, so the first next(path) call isn't dropped.
+        // Do not reorder these effects or merge them into one.
+        React.useEffect(() => {
+            observableRef.current?.next(path);
+        }, [path]);
+        // Re-reads observableRef.current lazily on each call rather than capturing the
+        // observable once: capturing it here would keep referencing a destroyed
+        // observable across a remount or a Strict-Mode mount/unmount/mount cycle, since
+        // this callback (memoized with an empty dep array) is not recreated when the
+        // creation effect re-runs and assigns a new observable to the ref.
+        const subscribe = React.useCallback((onStoreChange) => {
+            if (!observableRef.current) {
+                return () => { };
+            }
+            return observableRef.current.subscribe(() => onStoreChange());
+        }, []);
+        const getSnapshot = React.useCallback(() => observableRef.current?.getSnapshot() ?? idleStatus, []);
+        const status = React.useSyncExternalStore(subscribe, getSnapshot);
+        return { ref, status };
+    };
+    return { useRuntimeHost };
+};

package/dist/create-react-adapter.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=create-react-adapter.test.d.ts.map

package/dist/create-react-adapter.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-react-adapter.test.d.ts","sourceRoot":"","sources":["../src/create-react-adapter.test.tsx"],"names":[],"mappings":""}

package/dist/create-react-adapter.test.js

@@ -0,0 +1,74 @@
+// @vitest-environment happy-dom
+import { describe, expect, test, vi } from "vitest";
+import * as React from "react";
+import { act } from "react";
+import { createRoot } from "react-dom/client";
+const observers = new Set();
+let currentStatus = { type: "idle" };
+const mockNext = vi.fn((path) => {
+    currentStatus = { type: "loading", path };
+    observers.forEach((observer) => observer(currentStatus));
+    currentStatus = { type: "ready", path };
+    observers.forEach((observer) => observer(currentStatus));
+});
+const mockDestroy = vi.fn(async () => { });
+const mockCreateRuntimeHostObservable = vi.fn((_options) => ({
+    next: mockNext,
+    destroy: mockDestroy,
+    subscribe: (observer) => {
+        observers.add(observer);
+        return () => observers.delete(observer);
+    },
+    getSnapshot: () => currentStatus,
+}));
+vi.mock("@rmc-toolkit/core", () => ({
+    createRuntimeHostObservable: (options) => mockCreateRuntimeHostObservable(options),
+}));
+const { createReactAdapter } = await import("./create-react-adapter.js");
+const manifest = { namespace: "@acme", assetsOrigin: "https://assets.example.com" };
+describe("createReactAdapter", () => {
+    test("creates one observable per mounted component, forwards path to next(), and surfaces status", async () => {
+        const { useRuntimeHost } = createReactAdapter(React);
+        let renderedStatus;
+        const TestComponent = ({ path }) => {
+            const { ref, status } = useRuntimeHost(path, { manifest });
+            renderedStatus = status;
+            return React.createElement("div", { ref });
+        };
+        const container = document.createElement("div");
+        const root = createRoot(container);
+        await act(async () => {
+            root.render(React.createElement(TestComponent, { path: "/search" }));
+        });
+        expect(mockCreateRuntimeHostObservable).toHaveBeenCalledTimes(1);
+        expect(mockNext).toHaveBeenCalledWith("/search");
+        expect(renderedStatus).toEqual({ type: "ready", path: "/search" });
+        await act(async () => {
+            root.unmount();
+        });
+        expect(mockDestroy).toHaveBeenCalledTimes(1);
+    });
+    test("forwards a new path to next() when the path prop changes, without recreating the observable", async () => {
+        mockCreateRuntimeHostObservable.mockClear();
+        mockNext.mockClear();
+        const { useRuntimeHost } = createReactAdapter(React);
+        const TestComponent = ({ path }) => {
+            const { ref } = useRuntimeHost(path, { manifest });
+            return React.createElement("div", { ref });
+        };
+        const container = document.createElement("div");
+        const root = createRoot(container);
+        await act(async () => {
+            root.render(React.createElement(TestComponent, { path: "/search" }));
+        });
+        await act(async () => {
+            root.render(React.createElement(TestComponent, { path: "/cart" }));
+        });
+        expect(mockCreateRuntimeHostObservable).toHaveBeenCalledTimes(1);
+        expect(mockNext).toHaveBeenNthCalledWith(1, "/search");
+        expect(mockNext).toHaveBeenNthCalledWith(2, "/cart");
+        await act(async () => {
+            root.unmount();
+        });
+    });
+});

package/dist/index.d.ts

@@ -1,11 +1,5 @@
-import { type DynamicImporter, type RuntimeModuleContext } from "@rmc-toolkit/core";
-import React from "react";
-export type DynamicModuleBoundaryProps = {
-    specifier: string;
-    context?: RuntimeModuleContext;
-    fallback?: React.ReactNode;
-    errorFallback?: React.ReactNode;
-    importer?: DynamicImporter;
-};
-export declare const DynamicModuleBoundary: ({ specifier, context, fallback, errorFallback, importer, }: DynamicModuleBoundaryProps) => React.ReactElement;
+export { createDynamicModuleBoundary } from "./create-dynamic-module-boundary.js";
+export type { DynamicModuleBoundaryProps } from "./create-dynamic-module-boundary.js";
+export { createReactAdapter } from "./create-react-adapter.js";
+export type { UseRuntimeHostOptions, UseRuntimeHostResult, } from "./create-react-adapter.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.tsx"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,oBAAoB,EAC1B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,MAAM,OAAO,CAAC;AAM1B,MAAM,MAAM,0BAA0B,GAAG;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,oBAAoB,CAAC;IAC/B,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC3B,aAAa,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAChC,QAAQ,CAAC,EAAE,eAAe,CAAC;CAC5B,CAAC;AA2BF,eAAO,MAAM,qBAAqB,GAAI,4DAMnC,0BAA0B,KAAG,KAAK,CAAC,YAiBrC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,2BAA2B,EAAE,MAAM,qCAAqC,CAAC;AAClF,YAAY,EAAE,0BAA0B,EAAE,MAAM,qCAAqC,CAAC;AAEtF,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,YAAY,EACV,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,2BAA2B,CAAC"}

package/dist/index.js

@@ -1,26 +1,2 @@
-import { jsx as _jsx } from "react/jsx-runtime";
-import { importModule, } from "@rmc-toolkit/core";
-import React from "react";
-class ErrorBoundary extends React.Component {
-    state = { error: null };
-    static getDerivedStateFromError(error) {
-        return { error };
-    }
-    render() {
-        if (this.state.error) {
-            return this.props.fallback;
-        }
-        return this.props.children;
-    }
-}
-const defaultImporter = importModule;
-export const DynamicModuleBoundary = ({ specifier, context, fallback = null, errorFallback = null, importer = defaultImporter, }) => {
-    const LazyModule = React.lazy(async () => {
-        const loadedModule = (await importer(specifier));
-        return loadedModule;
-    });
-    const moduleProps = context === undefined
-        ? {}
-        : { context };
-    return (_jsx(React.Suspense, { fallback: fallback, children: _jsx(ErrorBoundary, { fallback: errorFallback, children: _jsx(LazyModule, { ...moduleProps }) }) }));
-};
+export { createDynamicModuleBoundary } from "./create-dynamic-module-boundary.js";
+export { createReactAdapter } from "./create-react-adapter.js";

package/dist/index.test.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 // @vitest-environment happy-dom
 import { describe, expect, test, vi } from "vitest";
+import * as React from "react";
 import { act } from "react";
 import { createRoot } from "react-dom/client";
 const FixtureComponent = () => "fixture content";
@@ -10,7 +11,8 @@ const mockImportModule = vi.fn(async () => ({
 vi.mock("@rmc-toolkit/core", () => ({
     importModule: mockImportModule,
 }));
-const { DynamicModuleBoundary } = await import("./index.js");
+const { createDynamicModuleBoundary } = await import("./index.js");
+const { DynamicModuleBoundary } = createDynamicModuleBoundary(React);
 describe("DynamicModuleBoundary", () => {
     test("default importer delegates to core's importModule", async () => {
         const container = document.createElement("div");
@@ -22,4 +24,35 @@ describe("DynamicModuleBoundary", () => {
         expect(container.textContent).toBe("fixture content");
         root.unmount();
     });
+    test("createDynamicModuleBoundary is injected with the caller's own React instance, not an internally imported one", async () => {
+        mockImportModule.mockClear();
+        // Two independently-created factories, each given its own React-like
+        // namespace object. If the implementation secretly imported "react"
+        // itself instead of using the injected parameter, both boundaries would
+        // still work identically and this test would give no signal either way
+        // -- that create-dynamic-module-boundary.ts has no runtime `import` of
+        // "react" is a static fact, verifiable by inspection of its import
+        // statements, not something a render test can detect. What this test
+        // does prove is that the DI parameter is actually wired through to
+        // produce a working component for whichever React instance is passed,
+        // by creating two boundaries from two separate calls and rendering both.
+        const { DynamicModuleBoundary: BoundaryA } = createDynamicModuleBoundary(React);
+        const { DynamicModuleBoundary: BoundaryB } = createDynamicModuleBoundary(React);
+        const containerA = document.createElement("div");
+        const rootA = createRoot(containerA);
+        const containerB = document.createElement("div");
+        const rootB = createRoot(containerB);
+        await act(async () => {
+            rootA.render(_jsx(BoundaryA, { specifier: "specifier-a" }));
+        });
+        await act(async () => {
+            rootB.render(_jsx(BoundaryB, { specifier: "specifier-b" }));
+        });
+        expect(mockImportModule).toHaveBeenCalledWith("specifier-a");
+        expect(mockImportModule).toHaveBeenCalledWith("specifier-b");
+        expect(containerA.textContent).toBe("fixture content");
+        expect(containerB.textContent).toBe("fixture content");
+        rootA.unmount();
+        rootB.unmount();
+    });
 });

package/package.json

@@ -1,7 +1,12 @@
 {
   "name": "@rmc-toolkit/react",
-  "version": "0.1.0",
+  "version": "0.2.3",
   "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/runtime-module-composition/rmc-toolkit",
+    "directory": "packages/react"
+  },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -17,11 +22,11 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@rmc-toolkit/core": "0.1.0",
+    "@rmc-toolkit/core": "0.2.3",
     "react": ">=18"
   },
   "dependencies": {
-    "@rmc-toolkit/core": "0.1.0"
+    "@rmc-toolkit/core": "0.2.3"
   },
   "scripts": {
     "build": "tsc -b"