@fulgurjs/federation 5.0.3 → 5.1.0

package/dist/react-adapter.d.ts

@@ -0,0 +1,117 @@
+import { ComponentType, ReactNode, Component, ErrorInfo, Ref } from 'react';
+import { PageRouteLike } from './pages.js';
+import { R as ResolvedHostPage, H as HostPagesCoreOptions } from './host-pages-core-DLfMeDrO.js';
+
+interface LoadRemoteOptions {
+    shareScope?: string;
+    retries?: number;
+    fallbackModule?: () => any;
+}
+
+/**
+ * React 适配层：remoteComponent() / useLoadRemote() / RemoteErrorBoundary /
+ * createReactHostPages()。只接收加载函数，不静态引用运行时内核（同 vue-adapter 形态，
+ * dist/react.js 由构建脚本绑定 loadRemote 后再导出）。
+ *
+ * 语义要点（README React 章节的实现依据）：
+ * - remoteComponent：工厂与页面表声明零加载副作用；首次渲染才 loadRemote；
+ *   加载状态机自带 pending/error/ready 三态，不用 React.lazy——lazy 的失败 Promise
+ *   会缓存在实例上，仅重置错误边界无法恢复，必须重建加载尝试。retry 以受控 attempt
+ *   计数触发（不在普通 render 中重建加载器，组件本地状态不因重渲染反复重置）。
+ * - timeout 是本次组件加载等待上限（适配层实现），不取消 loadRemote 的共享请求，
+ *   不修改远程入口配置超时；迟到的成功/失败一律丢弃，不产生未处理 rejection。
+ *   retry 对已成功缓存的模块不重新下载（运行时缓存），只重走生命周期（onSession 按代次去重）。
+ * - 渲染期异常由内置 RemoteRenderBoundary 捕获，与网络/导出错误分开记录与展示；
+ *   ErrorBoundary 不捕获事件处理器与任意异步回调（React 边界语义，README 已声明）。
+ * - 代码全部 createElement（无 JSX）：适配器自身不依赖 jsx-runtime，减少共享子路径面。
+ */
+
+type LoadRemoteFn = (spec: string, opts?: LoadRemoteOptions) => Promise<any>;
+/** 渲染函数形态的错误占位：(error, retry) => ReactNode；与 remoteComponent.error 一致 */
+type RemoteErrorFallback = (error: unknown, retry: () => void) => ReactNode;
+interface ReactRemoteComponentOptions {
+    /** 本次加载 pending 时的占位（区别于失败占位）；默认 null */
+    fallback?: ReactNode;
+    /** 加载失败或子树渲染错误的展示；默认内置中文占位（错误码+根因+修法+重试） */
+    error?: ReactNode | RemoteErrorFallback;
+    /** 透传现行 loadRemote 的重试选项（0-10 整数），不另叠自动重试 */
+    retries?: number;
+    /** 本次组件加载等待上限 ms；不提供则沿用 loadRemote 自身超时。不取消已发出的共享请求 */
+    timeout?: number;
+}
+interface RemoteErrorBoundaryProps {
+    children?: ReactNode;
+    /** 错误占位：节点或 ({ error, reset }) 渲染函数；默认内置中文占位 */
+    fallback?: ReactNode | ((args: {
+        error: unknown;
+        reset: () => void;
+    }) => ReactNode);
+    /** 渲染异常回调（error + React componentStack 信息） */
+    onError?: (error: unknown, info: ErrorInfo) => void;
+    /** 任一项变化时重置边界状态（受控重试的常用形态：传 [retryEpoch]） */
+    resetKeys?: readonly unknown[];
+}
+interface BoundaryState {
+    error: unknown | null;
+}
+/**
+ * 页面级错误边界：只捕获传到它的子树渲染错误。remoteComponent 内置边界已处理自身错误，
+ * 外层边界看不到内层已消费的异常。reset 只重置边界状态；子组件若持有失败缓存
+ * （如 React.lazy），还需要由调用方重建加载尝试（remoteComponent 的 retry 已含两者）。
+ */
+declare class RemoteErrorBoundary extends Component<RemoteErrorBoundaryProps, BoundaryState> {
+    state: BoundaryState;
+    static getDerivedStateFromError(error: unknown): BoundaryState;
+    componentDidCatch(error: unknown, info: ErrorInfo): void;
+    componentDidUpdate(prev: RemoteErrorBoundaryProps): void;
+    readonly reset: () => void;
+    render(): ReactNode;
+}
+declare function createRemoteComponent(loadRemote: LoadRemoteFn): <P = Record<string, unknown>>(spec: string, opts?: ReactRemoteComponentOptions) => ComponentType<P & {
+    ref?: Ref<unknown>;
+}>;
+interface UseLoadRemoteOptions {
+    /** 透传 loadRemote 的 shareScope */
+    shareScope?: string;
+    /** 透传 loadRemote 的重试次数（0-10 整数） */
+    retries?: number;
+    /**
+     * 用户显式配置的失败兜底模块（透传 loadRemote.fallbackModule）：配置后加载失败返回
+     * 兜底值而不写 error。这是显式声明的行为，不是静默成功——README 已说明。
+     */
+    fallbackModule?: () => any;
+}
+interface UseLoadRemoteResult<Module = any> {
+    /** 加载成功后的模块命名空间；未成功时 undefined */
+    data: Module | undefined;
+    /** 失败原因；无错误时恒为 undefined（统一空值） */
+    error: unknown;
+    /** 是否有请求在途 */
+    loading: boolean;
+    /** 重新走一次加载生命周期；已成功的模块经运行时缓存不会重新下载。Promise<void> 正常结束（不抛） */
+    reload: () => Promise<void>;
+}
+declare function createUseLoadRemote(loadRemote: LoadRemoteFn): <Module = any>(spec: string, opts?: UseLoadRemoteOptions) => UseLoadRemoteResult<Module>;
+interface ReactHostPagesOptions extends HostPagesCoreOptions {
+    /** 每次页面模块实际加载尝试前执行（同步或异步）；宿主在此提供最新 context */
+    beforeLoad?: () => void | Promise<void>;
+    /** 页面加载 pending 占位（同 remoteComponent.fallback） */
+    fallback?: ReactNode;
+    /** 页面加载/渲染错误占位（同 remoteComponent.error） */
+    error?: ReactNode | RemoteErrorFallback;
+    /** 透传 loadRemote 重试（0-10 整数） */
+    retries?: number;
+    /** 单次页面组件加载等待上限 ms（同 remoteComponent.timeout） */
+    timeout?: number;
+}
+interface ReactHostPages {
+    /** 原页面记录 */
+    pages: PageRouteLike[];
+    /** 路径 → 页面解析（base 前缀、最长前缀、参数解码、R1–R5 语义与 Vue 完全一致） */
+    resolve(path: string): ResolvedHostPage | null;
+    /** 按 spec 取页面组件（同 spec 同登录代次复用；新非空 sessionKey 到来时重建以触发 onSession） */
+    component<P = Record<string, unknown>>(spec: string): ComponentType<P>;
+}
+declare function createReactHostPages(options: ReactHostPagesOptions, loadRemote: LoadRemoteFn): ReactHostPages;
+
+export { type ReactHostPages, type ReactHostPagesOptions, type ReactRemoteComponentOptions, RemoteErrorBoundary, type RemoteErrorBoundaryProps, type RemoteErrorFallback, ResolvedHostPage, type UseLoadRemoteOptions, type UseLoadRemoteResult, createReactHostPages, createRemoteComponent, createUseLoadRemote };

package/dist/react-adapter.js

@@ -0,0 +1,292 @@
+import {
+  cleanCompName,
+  createHostPagesCore,
+  noRenderableExportError,
+  readSessionKey,
+  shouldResetSessionCache
+} from "./chunk-4PLNAYZX.js";
+import "./chunk-TSXZ7TWA.js";
+
+// src/react-adapter.ts
+import {
+  Component,
+  createElement,
+  forwardRef,
+  useCallback,
+  useEffect,
+  useRef,
+  useState
+} from "react";
+var ERROR_STYLE = {
+  padding: "16px",
+  border: "1px solid #fde2e2",
+  borderRadius: "4px",
+  background: "#fef0f0",
+  color: "#c45656",
+  fontSize: "13px",
+  lineHeight: "1.6",
+  boxSizing: "border-box"
+};
+var TITLE_STYLE = { margin: "0 0 4px", fontWeight: 600 };
+var MESSAGE_STYLE = { margin: "0 0 8px", wordBreak: "break-all" };
+var FIX_STYLE = { margin: "0 0 8px" };
+var DefaultErrorView = function FulgurjsRemoteError({ error, retry, phase }) {
+  const err = error;
+  const code = err?.code ?? "UNKNOWN";
+  const message = err?.message ?? String(error ?? "unknown error");
+  return createElement("div", { style: ERROR_STYLE, "data-fulgurjs-error": code }, [
+    createElement(
+      "p",
+      { key: "t", style: TITLE_STYLE },
+      phase === "load" ? `\u8FDC\u7A0B\u7EC4\u4EF6\u52A0\u8F7D\u5931\u8D25\uFF08\u9519\u8BEF\u7801 ${code}\uFF09` : `\u8FDC\u7A0B\u7EC4\u4EF6\u6E32\u67D3\u51FA\u9519\uFF08\u9519\u8BEF\u7801 ${code}\uFF09`
+    ),
+    createElement("p", { key: "m", style: MESSAGE_STYLE }, message),
+    createElement("p", { key: "f", style: FIX_STYLE }, phase === "render" ? "\u4FEE\u6CD5\uFF1A\u67E5\u770B\u6D4F\u89C8\u5668 console \u4E2D\u7684\u7EC4\u4EF6\u8C03\u7528\u6808\u5B9A\u4F4D\u8FDC\u7A0B\u7EC4\u4EF6\u5185\u90E8\u7684\u6E32\u67D3\u5F02\u5E38\uFF08\u9519\u8BEF\u629B\u81EA\u8FDC\u7A0B\u4EE3\u7801\u672C\u8EAB\uFF0C\u4E0E\u7F51\u7EDC\u52A0\u8F7D\u65E0\u5173\uFF09\u3002" : "\u4FEE\u6CD5\uFF1A\u2460 \u6838\u5BF9 spec \u7684\u300C\u8FDC\u7A0B\u540D/expose \u540D\u300D\u4E0E\u8FDC\u7A0B\u5E94\u7528 exposes \u662F\u5426\u4E00\u81F4\uFF08MFU-006/008\uFF09\uFF1B\u2461 \u6838\u5BF9 remotes \u5730\u5740\u7AEF\u53E3\u4E0E\u8FDC\u7A0B\u670D\u52A1\u53EF\u8FBE\u6027\uFF08MFU-001\uFF09\uFF1B\u2462 \u67E5\u770B window \u7684 fulgurjs:error \u4E8B\u4EF6\u4E0E console \u540C\u6E90\u9519\u8BEF\u5B9A\u4F4D\u6839\u56E0\u3002"),
+    createElement("button", { key: "r", onClick: retry, type: "button" }, "\u91CD\u8BD5")
+  ]);
+};
+function isValidComponentType(v) {
+  if (typeof v === "function") return true;
+  if (v !== null && typeof v === "object" && typeof v.$$typeof === "symbol") return true;
+  return false;
+}
+function assertAdapterOptions(source, opts) {
+  if (opts.retries !== void 0 && (typeof opts.retries !== "number" || !Number.isInteger(opts.retries) || opts.retries < 0 || opts.retries > 10)) {
+    throw new Error(
+      `[fulgurjs] ${source} \u7684 retries \u914D\u7F6E\u65E0\u6548\uFF1A\u5F53\u524D\u4E3A ${String(opts.retries)}\uFF0C\u5E94\u4E3A 0 \u5230 10 \u7684\u6574\u6570\u3002\u8BF7\u4FEE\u6B63\u9009\u9879\u3002`
+    );
+  }
+  if (opts.timeout !== void 0 && (typeof opts.timeout !== "number" || !Number.isFinite(opts.timeout) || opts.timeout <= 0)) {
+    throw new Error(
+      `[fulgurjs] ${source} \u7684 timeout \u914D\u7F6E\u65E0\u6548\uFF1A\u5F53\u524D\u4E3A ${String(opts.timeout)}\uFF0C\u5E94\u4E3A\u5927\u4E8E 0 \u7684\u6709\u9650\u6BEB\u79D2\u6570\u3002\u8BF7\u4FEE\u6B63\u9009\u9879\u3002`
+    );
+  }
+}
+function renderErrorNode(errorOpt, error, retry, phase) {
+  if (typeof errorOpt === "function") return errorOpt(error, retry);
+  if (errorOpt !== void 0) return errorOpt;
+  return createElement(DefaultErrorView, { error, retry, phase });
+}
+var RemoteErrorBoundary = class extends Component {
+  state = { error: null };
+  static getDerivedStateFromError(error) {
+    return { error };
+  }
+  componentDidCatch(error, info) {
+    console.error("[fulgurjs] \u8FDC\u7A0B\u7EC4\u4EF6\u6E32\u67D3\u5F02\u5E38\uFF08RemoteErrorBoundary \u6355\u83B7\uFF09\uFF1A", error, info?.componentStack ?? "");
+    this.props.onError?.(error, info);
+  }
+  componentDidUpdate(prev) {
+    if (this.state.error !== null && !shallowArrayEq(prev.resetKeys, this.props.resetKeys)) {
+      this.reset();
+    }
+  }
+  reset = () => {
+    this.setState({ error: null });
+  };
+  render() {
+    if (this.state.error !== null) {
+      const f = this.props.fallback;
+      if (typeof f === "function") return f({ error: this.state.error, reset: this.reset });
+      if (f !== void 0) return f;
+      return renderErrorNode(void 0, this.state.error, this.reset, "render");
+    }
+    return this.props.children;
+  }
+};
+function shallowArrayEq(a, b) {
+  if (a === b) return true;
+  if (!a || !b || a.length !== b.length) return false;
+  return a.every((v, i) => v === b[i]);
+}
+function RemoteLoader({ spec, opts, loadRemote, beforeLoad, attempt, retry, passthrough, fwdRef }) {
+  const [state, setState] = useState({ phase: "pending" });
+  const latest = useRef({ passthrough, fwdRef });
+  latest.current = { passthrough, fwdRef };
+  useEffect(() => {
+    let cancelled = false;
+    let settled = false;
+    let timer;
+    const gen = attempt;
+    const commit = (next) => {
+      if (cancelled || settled || gen !== attempt) return;
+      settled = true;
+      setState(next);
+    };
+    setState({ phase: "pending" });
+    const run = (async () => {
+      await beforeLoad?.();
+      return loadRemote(spec, { retries: opts.retries });
+    })();
+    run.catch(() => {
+    });
+    const race = opts.timeout === void 0 ? run : Promise.race([
+      run,
+      new Promise((_, reject) => {
+        timer = setTimeout(() => {
+          reject(new Error(
+            `[fulgurjs] \u8FDC\u7A0B\u7EC4\u4EF6 "${spec}" \u52A0\u8F7D\u7B49\u5F85\u8D85\u8FC7 ${opts.timeout} \u6BEB\u79D2\uFF08\u9002\u914D\u5C42 timeout\uFF09\u3002\u8BE5\u8D85\u65F6\u53EA\u7ED3\u675F\u672C\u6B21\u7B49\u5F85\uFF0C\u4E0D\u53D6\u6D88\u5DF2\u53D1\u51FA\u7684\u5171\u4EAB\u8BF7\u6C42\uFF1B\u53EF\u70B9\u51FB\u91CD\u8BD5\u5EFA\u7ACB\u65B0\u7684\u52A0\u8F7D\u5C1D\u8BD5\u3002`
+          ));
+        }, opts.timeout);
+      })
+    ]);
+    race.then(
+      (ns) => {
+        if (timer !== void 0) clearTimeout(timer);
+        const inner = ns?.default ?? ns;
+        if (!isValidComponentType(inner)) {
+          commit({ phase: "error", error: noRenderableExportError(spec, inner) });
+          return;
+        }
+        commit({ phase: "ready", Comp: inner });
+      },
+      (err) => {
+        if (timer !== void 0) clearTimeout(timer);
+        commit({ phase: "error", error: err });
+      }
+    );
+    return () => {
+      cancelled = true;
+      if (timer !== void 0) clearTimeout(timer);
+    };
+  }, [attempt]);
+  if (state.phase === "pending") return opts.fallback ?? null;
+  if (state.phase === "error") return renderErrorNode(opts.error, state.error, retry, "load");
+  const Comp = state.Comp;
+  const merged = fwdRef === void 0 ? latest.current.passthrough : { ...latest.current.passthrough, ref: latest.current.fwdRef };
+  return createElement(Comp, merged);
+}
+var RemoteRenderBoundary = class extends Component {
+  state = { error: null };
+  static getDerivedStateFromError(error) {
+    return { error };
+  }
+  componentDidCatch(error, info) {
+    console.error("[fulgurjs] \u8FDC\u7A0B\u7EC4\u4EF6\u6E32\u67D3\u5F02\u5E38\uFF08remoteComponent \u5185\u7F6E\u8FB9\u754C\uFF09\uFF1A", error, info?.componentStack ?? "");
+  }
+  retry = () => {
+    this.props.onRetry();
+  };
+  render() {
+    return this.props.render(this.state.error, this.retry);
+  }
+};
+function buildRemoteComponent(spec, opts, loadRemote, beforeLoad) {
+  const displayName = cleanCompName(spec);
+  function RemoteRoot(props) {
+    const [attempt, setAttempt] = useState(0);
+    const retry = useCallback(() => setAttempt((a) => a + 1), []);
+    const { __fulgurjsRef, ...rest } = props;
+    const passthrough = rest;
+    return createElement(
+      RemoteRenderBoundary,
+      {
+        key: attempt,
+        onRetry: retry,
+        render: (boundaryError) => boundaryError !== null ? renderErrorNode(opts.error, boundaryError, retry, "render") : createElement(RemoteLoader, {
+          spec,
+          opts,
+          loadRemote,
+          beforeLoad,
+          attempt,
+          retry,
+          passthrough,
+          fwdRef: __fulgurjsRef
+        })
+      }
+    );
+  }
+  RemoteRoot.displayName = displayName;
+  const Wrapped = forwardRef(
+    (props, ref) => createElement(RemoteRoot, { ...props, __fulgurjsRef: ref })
+  );
+  Wrapped.displayName = displayName;
+  return Wrapped;
+}
+function createRemoteComponent(loadRemote) {
+  return function remoteComponent(spec, opts = {}) {
+    assertAdapterOptions(`remoteComponent("${spec}")`, opts);
+    return buildRemoteComponent(spec, opts, loadRemote);
+  };
+}
+function createUseLoadRemote(loadRemote) {
+  return function useLoadRemote(spec, opts = {}) {
+    assertAdapterOptions(`useLoadRemote("${spec}")`, opts);
+    const { shareScope, retries, fallbackModule } = opts;
+    const [data, setData] = useState(void 0);
+    const [error, setError] = useState(void 0);
+    const [loading, setLoading] = useState(true);
+    const reqGen = useRef(0);
+    const optsRef = useRef(opts);
+    optsRef.current = opts;
+    useEffect(() => {
+      const gen = ++reqGen.current;
+      let cancelled = false;
+      const isCurrent = () => gen === reqGen.current && !cancelled;
+      setData(void 0);
+      setError(void 0);
+      setLoading(true);
+      loadRemote(spec, { shareScope, retries, fallbackModule }).then(
+        (ns) => {
+          if (!isCurrent()) return;
+          setData(ns);
+          setLoading(false);
+        },
+        (err) => {
+          if (!isCurrent()) return;
+          setError(err);
+          setLoading(false);
+        }
+      );
+      return () => {
+        cancelled = true;
+      };
+    }, [spec, shareScope, retries, fallbackModule, loadRemote]);
+    const reload = useCallback(async () => {
+      const gen = ++reqGen.current;
+      setLoading(true);
+      setError(void 0);
+      const o = optsRef.current;
+      try {
+        const ns = await loadRemote(spec, { shareScope: o.shareScope, retries: o.retries, fallbackModule: o.fallbackModule });
+        if (gen === reqGen.current) {
+          setData(ns);
+          setLoading(false);
+        }
+      } catch (err) {
+        if (gen === reqGen.current) {
+          setError(err);
+          setLoading(false);
+        }
+      }
+    }, [spec, loadRemote]);
+    return { data, error, loading, reload };
+  };
+}
+function createReactHostPages(options, loadRemote) {
+  const { beforeLoad, fallback, error, retries, timeout } = options;
+  assertAdapterOptions("createReactHostPages()", { retries, timeout });
+  const core = createHostPagesCore(options);
+  let cacheSession;
+  const compCache = /* @__PURE__ */ new Map();
+  const component = (spec) => {
+    const sessionKey = readSessionKey();
+    if (shouldResetSessionCache(sessionKey, cacheSession)) {
+      compCache.clear();
+      cacheSession = sessionKey;
+    }
+    let comp = compCache.get(spec);
+    if (!comp) {
+      comp = buildRemoteComponent(spec, { fallback, error, retries, timeout }, loadRemote, beforeLoad);
+      compCache.set(spec, comp);
+    }
+    return comp;
+  };
+  return { pages: core.pages, resolve: core.resolve, component };
+}
+export {
+  RemoteErrorBoundary,
+  createReactHostPages,
+  createRemoteComponent,
+  createUseLoadRemote
+};