remote-components 0.1.2 → 0.2.0

package/dist/{component-loader-21865da3.d.ts → host/react.d.ts}

@@ -1,33 +1,38 @@
-import { R as ResolveClientUrl, I as InternalResolveClientUrl } from './proxy-through-host-a676a522.js';
-import * as react from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
 
 /**
- * Serialized descriptor for a `<script>` element extracted from a remote
- * component response. Used in both SSR fetch results and client-side props.
+ * Intercepts client-side URL resolution for remote component resources.
+ * Called before each asset (script, stylesheet, chunk, module, image) is fetched.
+ *
+ * Return a new URL string to redirect the fetch (e.g., through a proxy),
+ * or undefined to use the original URL.
+ *
+ * @param remoteSrc - The `src` of the remote component being loaded
+ * @param url - The asset URL about to be fetched
+ *
+ * @example
+ * // Proxy all assets from the remote's origin through the host
+ * const resolveClientUrl = (remoteSrc, url) => {
+ *   const remoteOrigin = new URL(remoteSrc).origin;
+ *   const parsed = new URL(url);
+ *   if (parsed.origin !== location.origin && parsed.origin === remoteOrigin) {
+ *     return `/rc-fetch-protected-remote?url=${encodeURIComponent(url)}`;
+ *   }
+ * };
  */
-interface ScriptDescriptor {
-    /** The script `src` URL. Empty string for inline scripts. */
-    src: string;
-    /** Inline script content (only present for scripts without a `src`). */
-    textContent?: string;
-}
+type ResolveClientUrl = (remoteSrc: string, url: string) => string | undefined;
 /**
- * Serialized descriptor for a `<link>` element extracted from a remote
- * component response. Captures all HTML attributes as key-value pairs.
- *
- * Note: the client-side parser works with live `HTMLLinkElement` objects.
- * This descriptor represents the serialized form passed between SSR and
- * client hydration.
+ * Internal bound resolver — `ResolveClientUrl` with `remoteSrc` already applied.
+ * Used by internal loaders that don't need to know the remote src.
  */
-type LinkDescriptor = Record<string, string | boolean>;
+type InternalResolveClientUrl = (url: string) => string | undefined;
 
-interface RemoteComponentMetadata {
-    bundle: string;
-    route: string;
-    runtime: 'webpack' | 'turbopack' | 'script';
-    id: string;
-    type: 'nextjs' | 'remote-component' | 'unknown';
-}
+/**
+ * Hook types for intercepting remote component fetch requests and responses.
+ *
+ * These are part of the public host configuration surface ({@link ConsumeServerConfig})
+ * and are used by both SSR and client-side host implementations.
+ */
 /**
  * Options object passed to hook functions containing abort capabilities.
  * Uses standard AbortController/AbortSignal for compatibility with Web APIs.
@@ -148,8 +153,8 @@ type OnResponseHook = (url: URL, response: Response, options: HookOptions) => Pr
 /**
  * Configuration for Shadow DOM isolation of a remote component.
  *
- * Used by both the public {@link HostConfig} (user-facing props) and
- * {@link ResolvedRemoteComponentData} (internal runtime data) to control
+ * Used by both the public {@link ConsumeRemoteComponentConfig} (user-facing props) and
+ * {@link ConsumeServerData} (internal runtime data) to control
  * whether and how the remote component is wrapped in a shadow root.
  */
 interface ShadowDomConfig {
@@ -161,18 +166,16 @@ interface ShadowDomConfig {
     reset?: boolean;
 }
 /**
- * Core configuration accepted by every host implementation.
+ * Configuration accepted by server-rendered embed hosts (e.g. the Next.js App Router
+ * `<ConsumeRemoteComponent>`). This is the minimal, serializable subset — no client-side
+ * asset fetching fields, no lifecycle callbacks.
  *
  * `src` is optional here because not every host has a source at construction
  * time (e.g. the React host during SSR hydration, or a `<remote-component>`
  * element before its `src` attribute is set). Frameworks that require `src`
  * narrow it to required in their own props type.
- *
- * Client-only fields (`credentials`, `resolveClientUrl`) live in the separate
- * {@link ClientHostConfig} interface so that server-only hosts (App Router)
- * can extend `HostConfig` directly without omitting anything.
  */
-interface HostConfig extends ShadowDomConfig {
+interface ConsumeServerConfig extends ShadowDomConfig {
     /** The source URL of the remote component. Relative or absolute. */
     src?: string | URL;
     /** Selects a named remote component when multiple are exposed on a single page. */
@@ -183,13 +186,11 @@ interface HostConfig extends ShadowDomConfig {
     onResponse?: OnResponseHook;
 }
 /**
- * Client-side host configuration that extends {@link HostConfig}.
- *
- * These fields only apply to hosts that fetch and resolve assets on the client
- * (React host, Pages Router host, HTML host). Server-only hosts like the
- * App Router server component do not need these.
+ * Client-only configuration fields — the subset of {@link ConsumeClientConfig}
+ * that applies only to client-side asset fetching. Used directly in contexts where
+ * the full server config is already present (e.g. {@link ConsumeRemoteComponentClient}).
  */
-interface ClientHostConfig {
+interface ConsumeClientOnlyConfig {
     /** The credentials mode for the fetch request. Defaults to `'same-origin'`. */
     credentials?: RequestCredentials;
     /**
@@ -199,6 +200,23 @@ interface ClientHostConfig {
      */
     resolveClientUrl?: ResolveClientUrl;
 }
+/**
+ * Configuration accepted by client-side embed hosts (React host, Pages Router host,
+ * HTML host). Extends {@link ConsumeServerConfig} with fields for
+ * client-side asset fetching (`credentials`, `resolveClientUrl`).
+ */
+interface ConsumeClientConfig extends ConsumeServerConfig, ConsumeClientOnlyConfig {
+}
+/**
+ * Complete configuration for client-side embed hosts (React host, Pages Router host).
+ * Combines {@link ConsumeClientConfig} with {@link ConsumeLifecycleCallbacks}.
+ *
+ * This is the base type for public-facing props on hosts that fetch and mount
+ * remote components on the client. The App Router server host uses only
+ * {@link ConsumeServerConfig} since RSC cannot accept function callbacks.
+ */
+interface ConsumeRemoteComponentConfig extends ConsumeClientConfig, ConsumeLifecycleCallbacks {
+}
 /** Information provided to the `onChange` lifecycle callback. */
 interface ChangeInfo {
     previousSrc: string | URL | null;
@@ -211,13 +229,13 @@ interface ChangeInfo {
  *
  * On the host side, these fire during client-side loading (the React host
  * exposes them as callback props; the HTML host dispatches DOM events).
- * On the remote side (Next.js `<RemoteComponent>` wrapper), the callbacks
+ * On the remote side (Next.js `<ExposeRemoteComponent>` wrapper), the callbacks
  * are forwarded as `data-on-*` attributes so the host can wire them up.
  *
  * Server-only components (e.g. Next.js App Router server host) do not
  * support these callbacks since they render once on the server.
  */
-interface HostLifecycleCallbacks {
+interface ConsumeLifecycleCallbacks {
     /** Called right before a new remote component load starts. */
     onBeforeLoad?: (src: string | URL) => void;
     /** Called when the remote component has been successfully loaded and mounted. */
@@ -229,14 +247,40 @@ interface HostLifecycleCallbacks {
 }
 
 /**
- * Payload fields extracted from an SSR fetch response that the client-side
- * component loader needs to hydrate or mount a remote component.
+ * Metadata embedded in the HTML response by a remote application.
+ *
+ * Extracted from a `<script type="application/json" data-remote-component>`
+ * element during both SSR parsing ({@link fetchRemoteComponent}) and
+ * client-side parsing ({@link parseRemoteComponentDocument}).
+ */
+interface RemoteComponentMetadata {
+    bundle: string;
+    route: string;
+    runtime: 'webpack' | 'turbopack' | 'script';
+    id: string;
+    type: 'nextjs' | 'remote-component' | 'unknown';
+}
+
+/**
+ * Serialized descriptor for a `<script>` element extracted from a remote
+ * component response. Used in both SSR fetch results and client-side props.
+ */
+interface ScriptDescriptor {
+    /** The script `src` URL. Empty string for inline scripts. */
+    src: string;
+    /** Inline script content (only present for scripts without a `src`). */
+    textContent?: string;
+}
+
+/**
+ * The subset of the remote component fetch response that the client-side
+ * loader needs to hydrate or mount a remote component.
  *
- * These mirror the relevant parts of `FetchRemoteComponentResponse` from the
- * SSR layer. Both {@link ResolvedRemoteComponentData} and
- * `LoadRemoteComponentProps` compose this interface.
+ * Both {@link ConsumeServerData} and {@link ConsumeLoaderProps}
+ * compose this interface — it is the shared base for the RSC→client handoff
+ * and the loader function arguments.
  */
-interface RemoteComponentPayload {
+interface ConsumeLoaderPayload {
     name: string;
     bundle: string;
     route?: string;
@@ -251,64 +295,16 @@ interface RemoteComponentPayload {
     scripts?: ScriptDescriptor[];
     remoteShared?: Record<string, string>;
 }
-/**
- * Internal runtime data for a resolved remote component.
- *
- * This is **not** the public `RemoteComponentProps` that consumers pass to
- * `<RemoteComponent>`. It represents the pre-resolved payload fields produced
- * by SSR fetching, combined with presentation config from
- * {@link ShadowDomConfig}, and consumed by the client-side renderer.
- */
-interface ResolvedRemoteComponentData extends RemoteComponentPayload, ShadowDomConfig {
-    /** The src provided to the `<RemoteComponent>` component, resolved to a string. */
-    src: string;
-    /** The src converted to a URL string. For relative URLs, the VERCEL_URL is used as the origin. */
-    serverUrl: string;
-    links?: LinkDescriptor[];
-    type?: RemoteComponentMetadata['type'];
-    children: react.ReactNode;
-}
-interface GlobalScope {
-    __DISABLE_WEBPACK_EXEC__?: Record<string, boolean>;
-    __webpack_chunk_load__?: (chunkId: string, scriptBundle?: string) => Promise<unknown> | undefined;
-    __original_webpack_chunk_load__?: (chunkId: string, scriptBundle?: string) => Promise<unknown> | undefined;
-    __webpack_require__?: (id: string) => unknown;
-    __webpack_get_script_filename__?: (id: string) => string | null | undefined;
-    __original_webpack_require__?: (id: string) => unknown;
-    __remote_webpack_require__?: Record<string, ((remoteId: string | number) => unknown) & {
-        c?: Record<string | number, {
-            id: string;
-            parents: string[];
-            children: string[];
-        }>;
-        m?: Record<string | number, (module: {
-            exports: unknown;
-        }) => void>;
-        type?: 'turbopack' | 'webpack' | 'script';
-    }>;
-    __webpack_require_type__?: RemoteComponentMetadata['runtime'];
-    __remote_shared_modules__?: Record<string, Record<string, unknown>>;
-    __remote_bundle_url__?: Record<string, string | URL>;
-    __remote_components_turbopack_chunk_loader_promise__?: Record<string, Promise<unknown>>;
-    __remote_components_turbopack_modules__?: Record<string, Record<string, unknown>>;
-    __remote_components_turbopack_global__?: Record<string, unknown>;
-    [key: string]: unknown;
-}
-interface LoaderResult {
-    component: react.ReactNode;
-    error?: Error;
-}
-type MountOrUnmountFunction = (el?: ShadowRoot | DocumentFragment | HTMLElement | HTMLCollection | null) => Promise<void> | void;
 
 /**
  * Props accepted by {@link loadRemoteComponent}.
  *
- * Extends {@link RemoteComponentPayload} (the SSR-resolved fields needed for
+ * Extends {@link ConsumeLoaderPayload} (the SSR-resolved fields needed for
  * hydration) with loader-specific fields (`url`, `shared`, `container`, etc.).
  * `remoteShared` is narrowed from optional to required (defaults to `{}` at
  * the call site).
  */
-interface LoadRemoteComponentProps extends RemoteComponentPayload {
+interface ConsumeLoaderProps extends ConsumeLoaderPayload {
     url: URL;
     shared: Promise<Record<string, (bundle?: string) => Promise<unknown>>> | Record<string, (bundle?: string) => Promise<unknown>>;
     remoteShared: Record<string, string>;
@@ -316,9 +312,55 @@ interface LoadRemoteComponentProps extends RemoteComponentPayload {
     rscName?: string;
     resolveClientUrl?: InternalResolveClientUrl;
 }
+
 /**
- * Main loader function that orchestrates the component loading process
+ * Props for the React remote component host.
+ *
+ * Extends {@link ConsumeRemoteComponentConfig} with `shared` for module sharing and
+ * `children` for loading fallback content.
+ */
+interface ConsumeRemoteComponentProps extends ConsumeRemoteComponentConfig {
+    /** Shared modules to include in the remote component's context. */
+    shared?: ConsumeLoaderProps['shared'];
+    /** Loading fallback content displayed while the remote component is being fetched. */
+    children?: React.ReactNode;
+}
+/**
+ * ConsumeRemoteComponent is a React component that fetches and renders a remote component.
+ * It supports SSR and can isolate the remote component in a shadow DOM.
+ *
+ * @param props - The properties for the remote component.
+ * @returns A React component that renders the remote component.
+ *
+ * @example
+ *
+ * Use the `<ConsumeRemoteComponent>` in your React application to consume a remote component from a remote application:
+ *
+ * ```tsx
+ * import { ConsumeRemoteComponent } from 'remote-components/host/react';
+ *
+ * export default function App() {
+ *  return (
+ *    <>
+ *      <h1>Welcome to My App</h1>
+ *      <p>This page consumes a remote component from another application.</p>
+ *      <ConsumeRemoteComponent src="/nextjs-app-remote/components/header" />
+ *    </>
+ *  );
+ * }
+ * ```
+ *
+ * To share modules, you can provide a shared module map with references to the shared modules:
+ *
+ * ```tsx
+ * <ConsumeRemoteComponent
+ *   src="/nextjs-app-remote/components/header"
+ *   shared={{
+ *     '@/components/provider': () => import('@/components/host-provider')
+ *   }}
+ * />
+ * ```
  */
-declare function loadRemoteComponent({ url, name, rscName, bundle, route, runtime, data, nextData, scripts, shared, remoteShared, container, resolveClientUrl, }: LoadRemoteComponentProps): Promise<LoaderResult>;
+declare function ConsumeRemoteComponent({ src, isolate, mode, reset, credentials, name: nameProp, shared, children, onBeforeLoad, onLoad, onError, onChange, onRequest, onResponse, resolveClientUrl: _resolveClientUrl, }: ConsumeRemoteComponentProps): react_jsx_runtime.JSX.Element;
 
-export { ClientHostConfig as C, GlobalScope as G, HostConfig as H, LoadRemoteComponentProps as L, MountOrUnmountFunction as M, OnRequestHook as O, RemoteComponentPayload as R, HostLifecycleCallbacks as a, HookOptions as b, OnResponseHook as c, LoaderResult as d, ResolvedRemoteComponentData as e, loadRemoteComponent as l };
+export { ConsumeRemoteComponent, ConsumeRemoteComponentProps, HookOptions, OnRequestHook, OnResponseHook };