@cfp-studio/plugin-react 17.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Zenc Labs Pty Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.mts

@@ -0,0 +1,12 @@
+import { FrameworkPluginFactory } from '@cfp-studio/core';
+
+/**
+ * 引入 @cfp-studio/core 包中的 FrameworkPluginFactory 类型，用于定义框架插件工厂
+ */
+
+/**
+ * 定义一个名为 reactFrameworkPlugin 的框架插件工厂对象
+ */
+declare const reactFrameworkPlugin: FrameworkPluginFactory;
+
+export { reactFrameworkPlugin as default };

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+import { FrameworkPluginFactory } from '@cfp-studio/core';
+
+/**
+ * 引入 @cfp-studio/core 包中的 FrameworkPluginFactory 类型，用于定义框架插件工厂
+ */
+
+/**
+ * 定义一个名为 reactFrameworkPlugin 的框架插件工厂对象
+ */
+declare const reactFrameworkPlugin: FrameworkPluginFactory;
+
+export { reactFrameworkPlugin as default };

package/dist/index.mjs

@@ -0,0 +1,141 @@
+import { createAnalyzer } from '@cfp-studio/analyzer-react';
+import react from '@vitejs/plugin-react';
+import { polyfillNode } from 'esbuild-plugin-polyfill-node';
+import path from 'node:path';
+import url from 'node:url';
+
+const reactImportRegExp = /import (\* as )?React[ ,]/;
+function reactImportsPlugin() {
+  return {
+    /**
+     * 插件名称，用于在 Vite 构建过程中标识此插件。
+     */
+    name: "previewjs:react-js-imports",
+    /**
+     * 转换钩子，在 Vite 处理模块时调用。
+     * 
+     * @param code - 模块的原始代码。
+     * @param id - 模块的唯一标识符，通常是文件路径。
+     * @returns 返回转换后的代码，如果不需要转换则返回原始代码。
+     */
+    async transform(code, id) {
+      if (id.includes("node_modules") || path.extname(id) !== ".js" || reactImportRegExp.test(code)) {
+        return code;
+      }
+      return `import React from 'react';${code}`;
+    }
+  };
+}
+
+const reactFrameworkPlugin = {
+  /**
+   * 插件的基本信息
+   */
+  info: {
+    /**
+     * 插件的 API 版本
+     */
+    apiVersion: 5,
+    /**
+     * 插件的名称
+     */
+    name: "@cfp-studio/plugin-react"
+  },
+  /**
+   * 检查当前项目是否与该插件兼容
+   * @param dependencies - 项目依赖项对象
+   * @returns 如果兼容返回 true，否则返回 false
+   */
+  isCompatible: async (dependencies) => {
+    const version = await dependencies.react?.readInstalledVersion();
+    if (!version) {
+      return false;
+    }
+    const [major, minor] = version.split(".").map((n) => Number.parseInt(n));
+    if (Number.isNaN(major) || Number.isNaN(minor)) {
+      return false;
+    }
+    return major >= 17 || major === 16 && minor >= 14;
+  },
+  /**
+   * 创建插件实例
+   * @param param0 - 包含根目录、读取器、日志记录器和依赖项的对象
+   * @returns 插件实例对象
+   */
+  async create({ rootDir, reader, logger, dependencies }) {
+    const __dirname = url.fileURLToPath(new URL(".", import.meta.url));
+    const analyzerPlugin = createAnalyzer({
+      rootDir,
+      reader,
+      logger
+    });
+    const previewDirPath = path.join(__dirname, "..", "preview");
+    return {
+      // 默认的包装器文件路径
+      defaultWrapperPath: "__previewjs__/Wrapper.tsx",
+      // 预览目录的路径
+      previewDirPath,
+      // 展开分析器插件实例的属性
+      ...analyzerPlugin,
+      /**
+       * 配置 Vite 的配置选项
+       * @param configuredPlugins - 已配置的 Vite 插件数组
+       * @returns Vite 配置对象
+       */
+      viteConfig: (configuredPlugins) => {
+        const hasReactPlugin = configuredPlugins.find(
+          (plugin) => plugin.name.startsWith("vite:react-")
+        );
+        return {
+          // 优化依赖项的配置
+          optimizeDeps: {
+            esbuildOptions: {
+              // 如果项目依赖中包含 next，则添加 polyfillNode 插件
+              plugins: dependencies.next ? [polyfillNode()] : []
+            }
+          },
+          // 路径解析配置
+          resolve: {
+            alias: {
+              // 将 react-native 别名映射到 react-native-web
+              "react-native": "react-native-web"
+            }
+          },
+          // Vite 插件数组
+          plugins: [
+            // 添加 reactImportsPlugin 插件
+            reactImportsPlugin(),
+            // 展开已配置的插件
+            ...configuredPlugins,
+            // 如果已配置的插件中不包含 Vite 的 React 插件，则添加 react 插件
+            ...!hasReactPlugin ? [react()] : [],
+            {
+              // 插件名称
+              name: "previewjs:update-react-import",
+              /**
+               * 转换代码的钩子函数
+               * @param code - 要转换的代码
+               * @param id - 文件的 ID
+               * @returns 转换后的代码，如果不需要转换则返回 undefined
+               */
+              async transform(code, id) {
+                if (!id.endsWith("__previewjs_internal__/renderer/index.tsx")) {
+                  return;
+                }
+                const reactVersion = Number.parseInt(
+                  await dependencies.react?.readInstalledVersion() || "0"
+                );
+                return code.replace(
+                  /__PREVIEWJS_PLUGIN_REACT_IMPORT_PATH__/g,
+                  reactVersion >= 18 ? "./render-18" : "./render-16"
+                );
+              }
+            }
+          ]
+        };
+      }
+    };
+  }
+};
+
+export { reactFrameworkPlugin as default };

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@cfp-studio/plugin-react",
+  "version": "17.1.0",
+  "license": "MIT",
+  "sideEffects": false,
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "preview"
+  ],
+  "dependencies": {
+    "@cfp-studio/analyzer-react": "^0.1.11",
+    "@vitejs/plugin-react": "4.3.4",
+    "esbuild-plugin-polyfill-node": "0.3.0"
+  },
+  "devDependencies": {
+    "@playwright/test": "1.50.1",
+    "@types/react": "18.3.18",
+    "@types/react-dom": "18.3.5",
+    "pino": "9.5.0",
+    "pino-pretty": "11.2.1",
+    "unbuild": "2.0.0",
+    "vite": "6.2.0",
+    "@cfp-studio/testing": "14.0.1",
+    "@cfp-studio/iframe": "18.0.0",
+    "@cfp-studio/core": "1.0.0",
+    "@cfp-studio/api": "16.1.0"
+  },
+  "scripts": {
+    "build": "tsc && tsc -p preview/tsconfig.json && unbuild",
+    "e2e-test": "playwright test"
+  }
+}

package/preview/error-boundary.tsx

@@ -0,0 +1,49 @@
+import type { ReactNode } from "react";
+import { Component } from "react";
+
+type ErrorBoundaryProps = {
+  renderId: number;
+  children: ReactNode;
+};
+
+let errorBoundaryInstance: ErrorBoundary | null = null;
+
+export async function expectErrorBoundary(
+  renderId: number,
+  shouldAbortRender: () => boolean
+) {
+  while (
+    !errorBoundaryInstance ||
+    errorBoundaryInstance.props.renderId !== renderId
+  ) {
+    await new Promise((resolve) => setTimeout(resolve, 100));
+    if (shouldAbortRender()) {
+      return null;
+    }
+  }
+  return errorBoundaryInstance;
+}
+
+export class ErrorBoundary extends Component<ErrorBoundaryProps> {
+  state = {
+    error: null as Error | null,
+  };
+
+  constructor(props: ErrorBoundaryProps) {
+    super(props);
+    // eslint-disable-next-line @typescript-eslint/no-this-alias
+    errorBoundaryInstance = this;
+  }
+
+  static getDerivedStateFromError(error: Error) {
+    return { error };
+  }
+
+  render() {
+    if (this.state.error) {
+      return <></>;
+    }
+
+    return this.props.children;
+  }
+}

package/preview/index.tsx

@@ -0,0 +1,95 @@
+import type { GetPropsFn, RendererLoader } from "@cfp-studio/iframe";
+import React from "react";
+import { ErrorBoundary, expectErrorBoundary } from "./error-boundary";
+// @ts-ignore
+import { render } from "__PREVIEWJS_PLUGIN_REACT_IMPORT_PATH__";
+import { rootContainer } from "./root";
+
+/**
+ * 加载渲染器的函数，用于渲染可预览的组件或故事。
+ *
+ * @param wrapperModule - 包装器模块，包含可能的包装组件。
+ * @param wrapperName - 包装器组件的名称，默认为 "Wrapper"。
+ * @param previewableModule - 包含可预览组件或故事的模块。
+ * @param previewableName - 可预览组件或故事的名称。
+ * @param renderId - 渲染的唯一标识符。
+ * @param shouldAbortRender - 一个函数，用于检查是否应中止渲染。
+ * @returns 一个对象，包含渲染函数和 JSX 工厂函数。
+ */
+export const loadRenderer: RendererLoader = async ({
+  wrapperModule,
+  wrapperName,
+  previewableModule,
+  previewableName,
+  renderId,
+  shouldAbortRender,
+}) => {
+  const isStoryModule = !!previewableModule.default?.component;
+  const Wrapper = wrapperModule?.[wrapperName || "Wrapper"] || React.Fragment;
+  const Previewable =
+    previewableModule[previewableName] ||
+    previewableModule.PreviewJsEval(
+      `try { return ${previewableName}; } catch { return null; }`
+    );
+  if (!Previewable) {
+    throw new Error(`No component or story named '${previewableName}'`);
+  }
+  const decorators = [
+    ...(Previewable.decorators || []),
+    ...(previewableModule.default?.decorators || []),
+  ];
+  const RenderComponent = isStoryModule
+    ? typeof Previewable === "function"
+      ? Previewable
+      : Previewable.render ||
+        Previewable.component ||
+        previewableModule.default?.render ||
+        previewableModule.default?.component ||
+        Previewable
+    : Previewable;
+  // biome-ignore lint/suspicious/noExplicitAny: <explanation>
+  const Renderer = (props: any) => {
+    return (
+      <ErrorBoundary renderId={renderId}>
+        <Wrapper>
+          {decorators.reduce(
+            (component, decorator) => () => decorator(component),
+            () => <RenderComponent {...props} />
+          )()}
+        </Wrapper>
+      </ErrorBoundary>
+    );
+  };
+  return {
+    render: async (getProps: GetPropsFn) => {
+      if (shouldAbortRender()) {
+        return;
+      }
+      await render(
+        <Renderer
+          {...getProps({
+            presetGlobalProps: previewableModule.default?.args || {},
+            presetProps: Previewable.args || {},
+          })}
+        />
+      );
+      if (shouldAbortRender()) {
+        return;
+      }
+      const errorBoundary = await expectErrorBoundary(
+        renderId,
+        shouldAbortRender
+      );
+      if (!errorBoundary) {
+        return;
+      }
+      if (errorBoundary.state.error) {
+        throw errorBoundary.state.error;
+      }
+      if (Previewable.play) {
+        await Previewable.play({ canvasElement: rootContainer });
+      }
+    },
+    jsxFactory: React.createElement,
+  };
+};

package/preview/render-16.tsx

@@ -0,0 +1,6 @@
+import ReactDOM from "react-dom";
+import { rootContainer } from "./root";
+
+export function render(node: JSX.Element) {
+  ReactDOM.render(node, rootContainer);
+}

package/preview/render-18.tsx

@@ -0,0 +1,11 @@
+import type { Root } from "react-dom/client";
+import { createRoot } from "react-dom/client";
+import { rootContainer } from "./root";
+
+let root: Root | null = null;
+export function render(node: JSX.Element) {
+  if (!root) {
+    root = createRoot(rootContainer);
+  }
+  root.render(node);
+}

package/preview/root.ts

@@ -0,0 +1,2 @@
+// biome-ignore lint/style/noNonNullAssertion: <explanation>
+export const rootContainer = document.getElementById("root")!;

package/preview/tsconfig.json

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