@cfp-studio/plugin-react 17.3.0 → 17.3.2

package/preview/shims/umi.tsx

@@ -0,0 +1,580 @@
+/**
+ * `umi` / `@umijs/max` 的最小 shim（预览环境专用）。
+ *
+ * 见 `docs/spec-umijs-support.md` §4.2。**这个文件不进业务代码**，
+ * 只在预览服务器里通过 `resolve.alias` 顶替真实的 `umi` 包。
+ *
+ * ## 为什么要 shim
+ *
+ * `umi` 是**服务端 + 客户端混合**的包，直接 import 会用到 `process.platform`、
+ * `fs` 等 Node API，在浏览器里直接崩（实测：
+ * `TypeError: Cannot read properties of undefined (reading 'platform')`）。
+ *
+ * ## 设计原则
+ *
+ * 1. **渲染路径上的高频 API 给降级值**（`useModel` / `useRequest`）——
+ *    抛错会让整棵组件树渲染不出来，预览就失去意义。
+ * 2. **不在渲染路径的 API 显式抛错**（`request`）—— 静默 `undefined`
+ *    会让人以为"跑通了但没数据"，比报错更难排查。
+ * 3. **不伪造数据**：空态就是空态，不编造看起来合理的假值。
+ */
+import { type AnchorHTMLAttributes, type ReactNode, useCallback, useEffect, useMemo, useState } from "react";
+
+/** 内存版位置栈：`history.push` 后可被 `useLocation` 观察到。 */
+interface MemoryLocation {
+	pathname: string;
+	search: string;
+	hash: string;
+	state: unknown;
+}
+
+let currentLocation: MemoryLocation = { pathname: "/", search: "", hash: "", state: null };
+const locationListeners = new Set<(location: MemoryLocation) => void>();
+
+function parsePath(to: string): MemoryLocation {
+	const [beforeHash, hash = ""] = to.split("#");
+	const [pathname, search = ""] = (beforeHash ?? "/").split("?");
+	return { pathname: pathname || "/", search, hash, state: null };
+}
+
+function navigate(to: string): void {
+	currentLocation = parsePath(to);
+	for (const listener of locationListeners) {
+		listener(currentLocation);
+	}
+}
+
+export function useLocation() {
+	const [location, setLocation] = useState(currentLocation);
+	useEffect(() => {
+		locationListeners.add(setLocation);
+		return () => {
+			locationListeners.delete(setLocation);
+		};
+	}, []);
+	return location;
+}
+
+export function useNavigate() {
+	return useCallback((to: string) => {
+		navigate(to);
+	}, []);
+}
+
+/** 路由参数：预览里没有路由，恒为空对象。 */
+export function useParams(): Record<string, string> {
+	return useMemo(() => ({}) as Record<string, string>, []);
+}
+
+export function useSearchParams(): URLSearchParams {
+	return useMemo(() => new URLSearchParams(currentLocation.search), []);
+}
+
+export const history = {
+	get location() {
+		return currentLocation;
+	},
+	push: navigate,
+	replace: navigate,
+	goBack: () => undefined,
+	listen: (listener: (location: MemoryLocation) => void) => {
+		locationListeners.add(listener);
+		return () => {
+			locationListeners.delete(listener);
+		};
+	},
+};
+
+type LinkProps = AnchorHTMLAttributes<HTMLAnchorElement> & { to?: string; children?: ReactNode };
+
+/** `Link` 渲染成 `<a>`，点击被拦截（不真正导航，避免预览页跳走）。 */
+export function Link({ to = "#", children, onClick, ...rest }: LinkProps) {
+	return (
+		<a
+			{...rest}
+			href={to}
+			onClick={(event) => {
+				event.preventDefault();
+				onClick?.(event);
+				navigate(to);
+			}}
+		>
+			{children}
+		</a>
+	);
+}
+
+/** `NavLink` 与 `Link` 同构；预览里恒为「未激活」。 */
+export function NavLink({ children, ...rest }: LinkProps) {
+	return <Link {...rest}>{children}</Link>;
+}
+
+/**
+ * `useModel` —— **恒返回空对象**。
+ *
+ * P0 不猜初值（见 spec §9.1 的评审修正 2）：需要真实初值时，
+ * 由用户在 `__previewjs__/Wrapper.tsx` 里包 Provider。
+ *
+ * selector 形式 `useModel(ns, s => …)` 正常运行（对 `{}` 求值）。
+ */
+export function useModel<T = Record<string, unknown>>(
+	_namespace: string,
+	selector?: (model: Record<string, unknown>) => T,
+): T {
+	const model = useMemo(() => ({}), []);
+	return (selector ? selector(model) : model) as T;
+}
+
+/** `connect` 直通 HOC：注入空 props，不做状态映射。 */
+export function connect<T>(Component: T): T {
+	return Component;
+}
+
+/* ------------------------------------------------------------------ *
+ * 应用上下文（`@umijs/renderer-react` 的 appContext）
+ *
+ * 这几个都在**渲染路径上**，且 `@umijs/max` 的页面组件很常见 ——
+ * 缺任何一个，整个模块会因 ESM 静态导出校验直接 `SyntaxError`，组件连挂载的机会都没有。
+ * 所以统一给「结构完整、内容为空」的降级值，而不是抛错。
+ * ------------------------------------------------------------------ */
+
+/**
+ * `useAppData()` —— 返回空的应用上下文。
+ *
+ * 真实返回值包含 `routes` / `clientRoutes` / `clientLoaderData` / `pluginManager` 等。
+ * 这里只保证**字段存在且类型形状对**，不伪造路由表（组件若遍历 `routes` 会得到空循环，
+ * 而不是 `Cannot read properties of undefined`）。
+ */
+export function useAppData() {
+	return useMemo(
+		() => ({
+			routes: {} as Record<string, unknown>,
+			routeComponents: {} as Record<string, unknown>,
+			clientRoutes: [] as unknown[],
+			pluginManager: undefined as unknown,
+			clientLoaderData: {} as Record<string, unknown>,
+			serverLoaderData: {} as Record<string, unknown>,
+			preloadRoute: (_to: string) => undefined,
+			basename: "/",
+			history,
+		}),
+		[],
+	);
+}
+
+/** 当前选中的路由链：预览里没有路由，恒为空数组。 */
+export function useSelectedRoutes(): unknown[] {
+	return useMemo(() => [], []);
+}
+
+/**
+ * 当前路由的配置（`IRoute`）。
+ *
+ * 恒返回 `{}`：真实的 `path` / `component` / `routes` 都由约定式路由生成，
+ * 预览不重建那套映射（那是 `specs/0001` 应用预览的领域）。
+ */
+export function useRouteProps<T = Record<string, unknown>>(): T {
+	return useMemo(() => ({}) as T, []);
+}
+
+/**
+ * 路由上下文（`IRouteContextType`）。
+ *
+ * 注意它与 `useRouteProps()` 不同：后者是路由配置对象本身，前者是
+ * `{ route: IRoute }` 的包装 —— 组件常见写法是 `useRouteData().route`。
+ */
+export function useRouteData(): { route: Record<string, unknown> } {
+	return useMemo(() => ({ route: {} }), []);
+}
+
+/** loader 数据：三个 loader hook 都返回空态，形状对齐真实签名。 */
+export function useServerLoaderData(): { data: undefined } {
+	return useMemo(() => ({ data: undefined }), []);
+}
+
+export function useClientLoaderData(): { data: undefined } {
+	return useMemo(() => ({ data: undefined }), []);
+}
+
+/** `useLoaderData()` 直接返回数据本身（不是 `{ data }` 包装）。 */
+export function useLoaderData(): undefined {
+	return undefined;
+}
+
+/* ------------------------------------------------------------------ *
+ * react-router 转导出
+ *
+ * `@umijs/max` 的 `umi` 入口会把这些 react-router 的 API 再导出一遍。
+ * 预览不引入 react-router（它有自己的 Router 上下文），所以全部给静态降级值。
+ * ------------------------------------------------------------------ */
+
+/**
+ * `useFetcher()` —— 返回空态的 fetcher。
+ *
+ * 真实签名里 `state` 取 `"idle" | "loading" | "submitting"`，这里恒为 `idle`，
+ * 让组件的 `if (fetcher.state !== "idle") return <Spin/>` 分支走正常路径。
+ */
+export function useFetcher() {
+	return useMemo(
+		() => ({
+			state: "idle" as const,
+			data: undefined,
+			formData: undefined,
+			load: async () => undefined,
+			submit: async () => undefined,
+		}),
+		[],
+	);
+}
+
+/** `useMatch()` —— 没有路由，匹配不中，恒 `null`。 */
+export function useMatch(_pattern?: unknown): null {
+	return null;
+}
+
+/** `useResolvedPath()` —— 返回自身路径的解析结果（不解析相对路径）。 */
+export function useResolvedPath(to: string) {
+	return useMemo(() => parsePath(to), [to]);
+}
+
+/** `useRoutes()` —— 预览不渲染路由表，恒渲染 `null`。 */
+export function useRoutes(_routes?: unknown): null {
+	return null;
+}
+
+/** `useOutlet()` —— 没有嵌套路由，恒 `null`。 */
+export function useOutlet(_context?: unknown): null {
+	return null;
+}
+
+/** `useOutletContext()` —— 没有 Outlet 提供者，恒空对象。 */
+export function useOutletContext<T = Record<string, unknown>>(): T {
+	return useMemo(() => ({}) as T, []);
+}
+
+/**
+ * `<Outlet />` —— 渲染 `null`。
+ *
+ * 子路由的内容由 Umi 的 layout / 约定式路由注入，预览不重建。
+ */
+export function Outlet(): null {
+	return null;
+}
+
+/**
+ * `<Navigate />` —— 渲染 `null`，并同步内存 location。
+ *
+ * 真实行为会立刻跳转；预览里不真的导航（避免渲染期间改状态导致循环），
+ * 只把目标路径记进内存栈，让后续 `useLocation()` 能读到。
+ */
+export function Navigate({ to }: { to: string }): null {
+	useEffect(() => {
+		navigate(to);
+	}, [to]);
+	return null;
+}
+
+/** 真实导出名是 `__useFetcher`，`useFetcher` 是它无下划线的别名，两个都要给。 */
+export const __useFetcher = useFetcher;
+
+/* ------------------------------------------------------------------ *
+ * react-router 的纯函数转导出
+ *
+ * 都是无状态的工具函数，可以给出**真实语义**（不需要路由上下文），
+ * 所以这里不降级为 `undefined` —— 降级反而会让组件的输入变成期望外的值。
+ * ------------------------------------------------------------------ */
+
+/** `createSearchParams(init)` —— 与 react-router 一致，返回 `URLSearchParams`。 */
+export function createSearchParams(
+	init?: string | Record<string, string> | Array<[string, string]> | URLSearchParams,
+): URLSearchParams {
+	return new URLSearchParams(init as string | Array<[string, string]> | Record<string, string> | undefined);
+}
+
+/**
+ * `resolvePath(to, fromPathname)` —— 相对路径解析成绝对路径。
+ *
+ * 移植自 react-router 6.3 的 `resolvePath` + `resolvePathname`：
+ * 处理 `.` / `..`、空的 `pathname`（回退到 `fromPathname`）与尾斜杠保留。
+ * 返回 `{ pathname, search, hash }`，**不含** `state`。
+ */
+export function resolvePath(to: string, fromPathname = "/"): { pathname: string; search: string; hash: string } {
+	const parsed = parsePathForResolve(to);
+	const { search = "", hash = "" } = parsed;
+	// 空 `to`（或只有 search/hash）应该 **保留 `fromPathname`**，而不是回到根。
+	// `parsePath()` 把空串规整成了 `/`，所以这里要看原始 `to` 而不是解析结果。
+	const toPathname = to === "" || to.startsWith("?") || to.startsWith("#") ? "" : (to.split(/[?#]/)[0] ?? "");
+	const pathname = toPathname
+		? toPathname.startsWith("/")
+			? toPathname
+			: resolvePathname(toPathname, fromPathname)
+		: fromPathname;
+	return { pathname, search: normalizeSearch(search), hash: normalizeHash(hash) };
+}
+
+/** 本模块私有的 parsePath（不依赖 shim 的版本，避免互相 import）。 */
+function parsePathForResolve(to: string): { pathname: string; search?: string; hash?: string } {
+	const [beforeHash, hash = ""] = to.split("#");
+	const [pathname, search = ""] = (beforeHash ?? "/").split("?");
+	return { pathname: pathname || "/", search, hash };
+}
+
+/** 相对路径拼接（与 react-router 的 `resolvePathname` 同算法）。 */
+function resolvePathname(relativePath: string, fromPathname: string): string {
+	const segments = fromPathname.replace(/\/+$/, "").split("/");
+	for (const segment of relativePath.split("/")) {
+		if (segment === "..") {
+			// 保留根部的空段，让 pathname 仍以 / 开头
+			if (segments.length > 1) {
+				segments.pop();
+			}
+		} else if (segment !== ".") {
+			segments.push(segment);
+		}
+	}
+	return segments.length > 1 ? segments.join("/") : "/";
+}
+
+function normalizeSearch(search: string): string {
+	return !search || search === "?" ? "" : search.startsWith("?") ? search : `?${search}`;
+}
+
+function normalizeHash(hash: string): string {
+	return !hash || hash === "#" ? "" : hash.startsWith("#") ? hash : `#${hash}`;
+}
+
+/**
+ * `matchPath(pattern, pathname)` —— 与 react-router 6.3 语义一致。
+ *
+ * ## 为什么不能用「按 `/` 切段逐个比」的简版
+ *
+ * 简版会错三处，而且错得很难发现：
+ *
+ * 1. **返回形状**：真实返回 `{ params, pathname, pathnameBase, pattern }`，
+ *    不是 `params` 本体。写 `match?.params.id` 的组件拿到的是 `undefined`。
+ * 2. **splat 捕获**：`/files/*` 的 `*` 是**具名捕获组**（`params["*"]`），
+ *    简版直接丢掉，组件会以为匹配上了但没有尾部路径。
+ * 3. **大小写**：默认 `caseSensitive: false`，`/Users/42` 能匹配 `/users/:id`。
+ *
+ * 所以这里直接移植 react-router 的 `compilePath` / `matchPath`（MIT，
+ * 见 `react-router@6.3.0` 的 `react-router.development.js`）。
+ */
+export interface PathMatch {
+	params: Record<string, string>;
+	pathname: string;
+	pathnameBase: string;
+	pattern: { path: string; caseSensitive: boolean; end: boolean };
+}
+
+export function matchPath(
+	pattern: string | { path: string; caseSensitive?: boolean; end?: boolean },
+	pathname: string,
+): PathMatch | null {
+	const compiled =
+		typeof pattern === "string"
+			? { path: pattern, caseSensitive: false, end: true }
+			: { path: pattern.path, caseSensitive: pattern.caseSensitive ?? false, end: pattern.end ?? true };
+
+	const [matcher, paramNames] = compilePath(compiled.path, compiled.caseSensitive, compiled.end);
+	const match = pathname.match(matcher);
+	if (!match) {
+		return null;
+	}
+	const matchedPathname = match[0] as string;
+	let pathnameBase = matchedPathname.replace(/(.)\/+$/, "$1");
+	const captureGroups = match.slice(1);
+	const params: Record<string, string> = {};
+
+	paramNames.forEach((paramName, index) => {
+		// splat 的 `pathnameBase` 要用**未解码**的原始值算，所以先算再解码。
+		if (paramName === "*") {
+			const splatValue = captureGroups[index] || "";
+			pathnameBase = matchedPathname.slice(0, matchedPathname.length - splatValue.length).replace(/(.)\/+$/, "$1");
+		}
+		params[paramName] = safelyDecodeURIComponent(captureGroups[index] || "", paramName);
+	});
+
+	return { params, pathname: matchedPathname, pathnameBase, pattern: compiled };
+}
+
+/** 把路径模式编译成正则 + 参数名列表（与 react-router 同）：`^/users/([^\/]+)\/?$`。 */
+function compilePath(path: string, caseSensitive = false, end = true): [RegExp, string[]] {
+	const paramNames: string[] = [];
+	let regexpSource = `^${path
+		.replace(/\/*\*?$/, "") // 尾部的 / 与 /* 由下面单独处理
+		.replace(/^\/*/, "/") // 保证以 / 开头
+		.replace(/[\\.*+^$?{}|()[\]]/g, "\\$&") // 转义正则特殊字符
+		.replace(/:(\w+)/g, (_match, paramName: string) => {
+			paramNames.push(paramName);
+			return "([^\\/]+)";
+		})}`;
+
+	if (path.endsWith("*")) {
+		paramNames.push("*");
+		// `*` / `/*` 已经匹配了开头的 /，剩下的直接 capture；
+		// 否则不要把这个 / 算进 params["*"]。
+		regexpSource += path === "*" || path === "/*" ? "(.*)$" : "(?:\\/(.+)|\\/*)$";
+	} else if (end) {
+		regexpSource += "\\/*$"; // 匹配到末尾时忽略尾斜杠
+	} else {
+		regexpSource += "(?:(?=[.~-]|%[0-9A-F]{2})|\\b|\\/|$)";
+	}
+
+	return [new RegExp(regexpSource, caseSensitive ? undefined : "i"), paramNames];
+}
+
+/** 解码失败的 URL 段原样返回，不抛错（与 react-router 同：那里只打 warning）。 */
+function safelyDecodeURIComponent(value: string, _paramName: string): string {
+	try {
+		return decodeURIComponent(value);
+	} catch {
+		return value;
+	}
+}
+
+/**
+ * `generatePath(pattern, params)` —— 把 `:param` 与尾部 `*` 替换成实际值。
+ *
+ * 移植自 react-router 6.3：**不做 URL 编码**（中文等原样输出），
+ * 缺失参数抛错，`*` 允许为空。
+ */
+export function generatePath(pattern: string, params: Record<string, string> = {}): string {
+	return pattern
+		.replace(/:(\w+)/g, (_match, key: string) => {
+			const value = params[key];
+			// 真实实现用 `params[key] != null`（同时排除 null 与 undefined），
+			// 这里展开写，避免依赖宽松相等。
+			if (value === undefined || value === null) {
+				throw new Error(`Missing ":${key}" param`);
+			}
+			return value;
+		})
+		.replace(/\/*\*$/, () => {
+			const splat = params["*"];
+			return splat === undefined || splat === null ? "" : String(splat).replace(/^\/*/, "/");
+		});
+}
+
+/** `matchRoutes(routes, pathname)` —— 没有路由表时恒 `null`。 */ export function matchRoutes(
+	_routes?: unknown,
+	_pathname?: string,
+): null {
+	return null;
+}
+
+/**
+ * `withRouter()` —— 直通 HOC。
+ *
+ * 真实版本注入 `history` / `location` / `match`；预览没有路由上下文，
+ * 注入空值（与 `connect` 的策略一致）。
+ */
+export function withRouter<T>(Component: T): T {
+	return Component;
+}
+
+/* ------------------------------------------------------------------ *
+ * helmet / history 转导出
+ * ------------------------------------------------------------------ */
+
+/**
+ * `<Helmet>` / `<HelmetProvider>` —— 渲染子节点，不改文档头。
+ *
+ * 预览的 `document.title` 由面板控制，让组件随便改会与宿主抢控制权。
+ */
+export function Helmet({ children }: { children?: ReactNode }): ReactNode {
+	return children ?? null;
+}
+
+export function HelmetProvider({ children }: { children?: ReactNode }): ReactNode {
+	return children ?? null;
+}
+
+/**
+ * `createMemoryHistory()` —— 返回与 shim 的 `history` 同构的内存栈。
+ *
+ * 注意：真实 `history` 包的接口大得多（`block` / `go` / `createHref` 等）。
+ * 这里只提供**渲染路径上常见**的几个，未实现的显式抛错（与 `request` 同策略）。
+ */
+export function createMemoryHistory(_options?: unknown) {
+	return history;
+}
+
+export const createBrowserHistory = createMemoryHistory;
+export const createHashHistory = createMemoryHistory;
+
+/** `LinkWithPrefetch as Link` —— 真实导出名是无下划线的 prefetch 版，预览里与 `Link` 同构。 */
+export const LinkWithPrefetch = Link;
+
+/* ------------------------------------------------------------------ *
+ * 应用挂载入口
+ *
+ * 这两个是 **应用级** API（把整棵路由树挂到 DOM），组件预览永远不会调用。
+ * 仍然显式导出：ESM 是**静态**导出校验，少一个名字整个模块就 `SyntaxError`，
+ * 整个预览白屏 —— 而降级为抛错至少能给出可读的原因。
+ * ------------------------------------------------------------------ */
+
+/** `renderClient()` —— 应用级挂载，不在组件预览的职责内。 */
+export function renderClient(): never {
+	throw new Error("预览环境不提供 umi.renderClient —— 应用级渲染请用 DevBrowser（应用预览）");
+}
+
+/** `__getRoot()` —— 拿到应用根元素，同上。 */
+export function __getRoot(): never {
+	throw new Error("预览环境不提供 umi.__getRoot —— 应用级渲染请用 DevBrowser（应用预览）");
+}
+
+/**
+ * `useRequest` —— **返回空态而非抛错**。
+ *
+ * 理由（spec §4.2.1）：它是 `@umijs/max` 下最高频的 API，抛错会让几乎所有页面
+ * 组件在预览里直接崩。空态能让组件的 `if (!data) return null` 分支自然生效。
+ *
+ * 选择 `loading: false` 而非 `true`：`true` 会让组件永远停在骨架屏，
+ * 而预览的目的是看结构，不是看 loading。
+ *
+ * 注意：**不伪造数据**，`data` 恒为 `undefined`。
+ */
+let warnedUseRequestEmpty = false;
+
+export function useRequest<R = unknown>(_service: unknown, _options?: unknown) {
+	if (!warnedUseRequestEmpty && typeof console !== "undefined") {
+		// 只打一次：每次渲染都打会把控制台刷爆。
+		// 让"为什么没数据"可被发现，而不是让人误以为是 bug（spec §11 R6）。
+		warnedUseRequestEmpty = true;
+		console.debug("[cfp-preview] useRequest：预览环境返回空态");
+	}
+	return {
+		data: undefined as R | undefined,
+		error: undefined,
+		loading: false,
+		run: async () => undefined as R | undefined,
+		runAsync: async () => undefined as R | undefined,
+		refresh: async () => undefined as R | undefined,
+		refreshAsync: async () => undefined as R | undefined,
+		mutate: () => undefined,
+		cancel: () => undefined,
+	};
+}
+
+/** 其它未实现的 API：显式抛错，不做静默 `undefined`。 */
+export function request(): never {
+	throw new Error("预览环境未实现 umi.request —— 请求类逻辑请在 DevBrowser（应用预览）里验证");
+}
+
+export function useAccess(): Record<string, boolean> {
+	return {};
+}
+
+export function useIntl() {
+	return {
+		formatMessage: ({ id }: { id: string }) => id,
+	};
+}
+
+export function getLocale(): string {
+	return "zh-CN";
+}
+
+export function setLocale(): void {
+	// 预览里切语言不生效：Umi 的 locale 由运行时注入，shim 不做模拟。
+}

package/preview/tsconfig.json

@@ -1,9 +1,9 @@
 {
-  "extends": "../../../../../tsconfig.base.json",
-  "compilerOptions": {
-    "module": "ES2022",
-    "moduleResolution": "Bundler",
-    "jsx": "preserve"
-  },
-  "exclude": ["types"]
+	"extends": "../../../../../tsconfig.base.json",
+	"compilerOptions": {
+		"module": "ES2022",
+		"moduleResolution": "Bundler",
+		"jsx": "preserve"
+	},
+	"exclude": ["types"]
 }