remote-components 0.1.0 → 0.1.2

package/dist/{component-loader-76eb1b8b.d.ts → component-loader-21865da3.d.ts}

@@ -1,6 +1,26 @@
-import { I as InternalResolveClientUrl } from './proxy-through-host-a676a522.js';
+import { R as ResolveClientUrl, I as InternalResolveClientUrl } from './proxy-through-host-a676a522.js';
 import * as react from 'react';
 
+/**
+ * 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;
+}
+/**
+ * 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.
+ */
+type LinkDescriptor = Record<string, string | boolean>;
+
 interface RemoteComponentMetadata {
     bundle: string;
     route: string;
@@ -125,11 +145,98 @@ type OnRequestHook = (url: URL, init: RequestInit, options: HookOptions) => Prom
  */
 type OnResponseHook = (url: URL, response: Response, options: HookOptions) => Promise<Response | undefined> | Response | undefined;
 
-interface RemoteComponentProps {
-    /** The src provided to the `<RemoteComponent>` component. May be relative or absolute URL. */
-    src: string;
-    /** The src converted to a URL object. For relative URLs, the VERCEL_URL is used as the origin. */
-    serverUrl: string;
+/**
+ * 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
+ * whether and how the remote component is wrapped in a shadow root.
+ */
+interface ShadowDomConfig {
+    /** Whether to isolate the remote component using a Shadow DOM wrapper. */
+    isolate?: boolean;
+    /** The Shadow DOM mode. Defaults to `'open'`. */
+    mode?: 'open' | 'closed';
+    /** Whether to include a CSS reset style in the Shadow DOM. Defaults to `false`. */
+    reset?: boolean;
+}
+/**
+ * Core configuration accepted by every host implementation.
+ *
+ * `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 {
+    /** 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. */
+    name?: string;
+    /** Intercepts fetch requests before they are sent. */
+    onRequest?: OnRequestHook;
+    /** Inspects or transforms fetch responses after they arrive. */
+    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.
+ */
+interface ClientHostConfig {
+    /** The credentials mode for the fetch request. Defaults to `'same-origin'`. */
+    credentials?: RequestCredentials;
+    /**
+     * Rewrites client-side asset URLs (scripts, stylesheets, chunks, modules, images).
+     * Return a new URL string to redirect the request (e.g. through a proxy),
+     * or `undefined` to use the original URL.
+     */
+    resolveClientUrl?: ResolveClientUrl;
+}
+/** Information provided to the `onChange` lifecycle callback. */
+interface ChangeInfo {
+    previousSrc: string | URL | null;
+    nextSrc: string | URL | null;
+    previousName: string | undefined;
+    nextName: string | undefined;
+}
+/**
+ * Lifecycle callbacks shared by host and remote component implementations.
+ *
+ * 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
+ * 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 {
+    /** 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. */
+    onLoad?: (src: string | URL) => void;
+    /** Called when an error occurs while loading or mounting the remote component. */
+    onError?: (error: unknown) => void;
+    /** Called when a different remote component is loaded into the same wrapper. */
+    onChange?: (info: ChangeInfo) => void;
+}
+
+/**
+ * Payload fields extracted from an SSR fetch response that the client-side
+ * component 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.
+ */
+interface RemoteComponentPayload {
     name: string;
     bundle: string;
     route?: string;
@@ -141,14 +248,23 @@ interface RemoteComponentProps {
         };
         buildId?: string;
     } | null;
-    scripts?: {
-        src: string;
-    }[];
-    links?: Record<string, string | boolean | undefined>[];
+    scripts?: ScriptDescriptor[];
     remoteShared?: Record<string, string>;
-    isolate?: boolean;
-    mode?: 'open' | 'closed';
-    reset?: boolean;
+}
+/**
+ * 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;
 }
@@ -184,17 +300,25 @@ interface LoaderResult {
 }
 type MountOrUnmountFunction = (el?: ShadowRoot | DocumentFragment | HTMLElement | HTMLCollection | null) => Promise<void> | void;
 
-type LoadRemoteComponentProps = Pick<RemoteComponentProps, 'name' | 'bundle' | 'route' | 'runtime' | 'data' | 'nextData' | 'scripts'> & {
+/**
+ * Props accepted by {@link loadRemoteComponent}.
+ *
+ * Extends {@link RemoteComponentPayload} (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 {
     url: URL;
     shared: Promise<Record<string, (bundle?: string) => Promise<unknown>>> | Record<string, (bundle?: string) => Promise<unknown>>;
     remoteShared: Record<string, string>;
     container?: HTMLHeadElement | ShadowRoot | null;
     rscName?: string;
     resolveClientUrl?: InternalResolveClientUrl;
-};
+}
 /**
  * Main loader function that orchestrates the component loading process
  */
 declare function loadRemoteComponent({ url, name, rscName, bundle, route, runtime, data, nextData, scripts, shared, remoteShared, container, resolveClientUrl, }: LoadRemoteComponentProps): Promise<LoaderResult>;
 
-export { GlobalScope as G, HookOptions as H, LoadRemoteComponentProps as L, MountOrUnmountFunction as M, OnRequestHook as O, RemoteComponentProps as R, OnResponseHook as a, LoaderResult as b, loadRemoteComponent as l };
+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 };

package/dist/host-config-58cdccea.d.ts

@@ -0,0 +1,87 @@
+import { ResolveClientUrl } from './internal/shared/client/proxy-through-host.js';
+import { O as OnRequestHook, a as OnResponseHook } from './types-2b26a246.js';
+
+/**
+ * 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
+ * whether and how the remote component is wrapped in a shadow root.
+ */
+interface ShadowDomConfig {
+    /** Whether to isolate the remote component using a Shadow DOM wrapper. */
+    isolate?: boolean;
+    /** The Shadow DOM mode. Defaults to `'open'`. */
+    mode?: 'open' | 'closed';
+    /** Whether to include a CSS reset style in the Shadow DOM. Defaults to `false`. */
+    reset?: boolean;
+}
+/**
+ * Core configuration accepted by every host implementation.
+ *
+ * `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 {
+    /** 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. */
+    name?: string;
+    /** Intercepts fetch requests before they are sent. */
+    onRequest?: OnRequestHook;
+    /** Inspects or transforms fetch responses after they arrive. */
+    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.
+ */
+interface ClientHostConfig {
+    /** The credentials mode for the fetch request. Defaults to `'same-origin'`. */
+    credentials?: RequestCredentials;
+    /**
+     * Rewrites client-side asset URLs (scripts, stylesheets, chunks, modules, images).
+     * Return a new URL string to redirect the request (e.g. through a proxy),
+     * or `undefined` to use the original URL.
+     */
+    resolveClientUrl?: ResolveClientUrl;
+}
+/** Information provided to the `onChange` lifecycle callback. */
+interface ChangeInfo {
+    previousSrc: string | URL | null;
+    nextSrc: string | URL | null;
+    previousName: string | undefined;
+    nextName: string | undefined;
+}
+/**
+ * Lifecycle callbacks shared by host and remote component implementations.
+ *
+ * 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
+ * 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 {
+    /** 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. */
+    onLoad?: (src: string | URL) => void;
+    /** Called when an error occurs while loading or mounting the remote component. */
+    onError?: (error: unknown) => void;
+    /** Called when a different remote component is loaded into the same wrapper. */
+    onChange?: (info: ChangeInfo) => void;
+}
+
+export { ClientHostConfig as C, HostConfig as H, ShadowDomConfig as S, HostLifecycleCallbacks as a };