@modern-js/main-doc 2.69.4 → 3.0.0-alpha.0

package/docs/zh/guides/topic-detail/model/use-model.mdx

@@ -1,248 +0,0 @@
-# 使用 Model
-
-## 在组件内使用
-
-### 作为全局状态使用
-
-通过 `useModel` 可以获取 Model 的 State、Actions 等。当 Model 的 State 通过 Actions 进行修改后，任何其他使用了该 Model 的组件，都会自动重新渲染。
-
-在 [快速上手](/guides/topic-detail/model/quick-start) 的计数器案例中，我们已经演示了 `useModel` 的使用，不再重复。
-
-`useModel` 支持传入多个 Model，多个 Model 的 State 和 Actions 会进行合并后作为返回结果。例如：
-
-```ts
-const fooModel = model('foo').define({
-  state: {
-    value: 1,
-  },
-  actions: {
-    add(state) {
-      state += 1;
-    },
-  },
-});
-
-const barModel = model('bar').define({
-  state: {
-    title: 'bar',
-  },
-  actions: {
-    set(state, payload) {
-      state.title = payload;
-    },
-  },
-});
-
-const [state, actions] = useModel([fooModel, barModel]);
-// 或
-const [state, actions] = useModel(fooModel, barModel);
-```
-
-`state` 和 `actions` 的值分别为：
-
-```ts
-state = {
-  value: 1,
-  title: 'bar',
-};
-
-actions = {
-  add(state) {
-    state += 1;
-  },
-  set(state, payload) {
-    state.title = payload;
-  },
-};
-```
-
-`useModel` 还支持对 State 和 Actions 做 selector 操作，实现对 State 和 Actions 的筛选或重命名，例如：
-
-```ts
-const fooModel = model('foo').define({
-  state: {
-    value: 1,
-  },
-  actions: {
-    add(state) {
-      state += 1;
-    },
-  },
-});
-
-const barModel = model('bar').define({
-  state: {
-    value: 'bar',
-  },
-  actions: {
-    set(state, payload) {
-      state.value = payload;
-    },
-  },
-});
-
-const [state, actions] = useModel(
-  [fooModel, barModel],
-  (fooState, barState) => ({
-    fooValue: fooState.value,
-    barValue: barState.value,
-  }), // stateSelector
-  (fooActions, barActions) => ({ add: fooActions.add }), // actionsSelector
-);
-```
-
-我们通过 `stateSelector` ，把 `fooModel` 和 `barModel` 中重名的状态做了命名修改，通过 `actionsSelector` ，过滤掉了 `barModel` 的 Actions。
-
-如果只需要设置 `actionsSelector`，可以把 `stateSelector` 设置为 `undefined`，作为参数占位。例如：
-
-```ts
-const [state, actions] = useModel(
-  [fooModel, barModel],
-  undefined,
-  (fooActions, barActions) => ({ add: fooActions.add }), // actionsSelector
-);
-```
-
-### 作为静态状态使用
-
-通过 `useStaticModel` 获取 Model ，将 Model 中的状态作为静态状态使用。可以保证组件每次访问到的 Model 的 State 都是最新值，但是 Model 的 State 的变化，并不会引起当前组件的重新渲染。
-
-:::info
-`useStaticModel` 的使用方式和 `useModel` 完全一致。
-
-:::
-
-考虑下面一种场景，有一个组件 Input 负责用户输入，另外一个组件 Search 负责根据用户的输入信息，在点击查询按钮后执行查询操作，我们不希望用户输入过程中的状态变化引起 Search 重新渲染，这时候就可以使用 `useStaticModel`：
-
-```ts
-import { useStaticModel } from '@modern-js/runtime/model';
-
-function Search() {
-  // 这里注意不要解构 state
-  const [state] = useStaticModel(searchModel);
-
-  return (
-    <div>
-      <button
-        onClick={async () => {
-          const result = await mockSearch(state.input);
-          console.log(result);
-        }}
-      >
-        Search
-      </button>
-    </div>
-  );
-}
-```
-
-:::warning 注意
-不要解构 `useStaticModel` 返回的 `state`，例如改成如下写法：
-`const [{input}] = useStaticModel(searchModel);`
-将始终获取到 Input 的初始值。
-
-:::
-
-`useStaticModel` 还适合和 [react-three-fiber](https://github.com/pmndrs/react-three-fiber) 等动画库一起使用，因为在动画组件 UI 里绑定会快速变化的状态，容易引起[性能问题](https://docs.pmnd.rs/react-three-fiber/advanced/pitfalls#never-bind-fast-state-reactive)。这种情况就可以选择使用 `useStaticModel`，它只会订阅状态，但不会引起视图组件的重新渲染。下面是一个简化示例：
-
-```ts
-function ThreeComponent() {
-  const [state, actions] = useStaticModel(modelA);
-
-  useFrame(() => {
-    state.value; // 假设初始化为 0
-    actions.setValue(1);
-    state.value; // 这里会得到1
-  });
-}
-```
-
-使用 React 的 refs 也可以实现类似效果，其实 `useStaticModel` 内部也使用到了 refs。不过直接 `useStaticModel` 有助于将状态的管理逻辑从组件中解耦，统一收敛到 Model 层。
-
-完整的示例代码可以在[这里](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/runtime-api/static-model)查看。
-
-### 作为局部状态使用
-
-通过 `useLocalModel` 获取 Model ，将 Model 中的状态作为局部状态使用。此时 Model State 的变化，只会引起当前组件的重新渲染，但是不会引起其他使用了该 Model 的组件重新渲染。效果和通过 React 的 `useState` 管理状态类似，但是可以将状态的管理逻辑从组件中解耦，统一收敛到 Model 层。
-
-:::info
-`useLocalModel` 的使用方式和 `useModel` 完全一致。
-
-:::
-
-例如，我们修改计数器应用的代码，添加一个有局部状态的计数器组件 `LocalCounter`：
-
-```ts
-import { useLocalModel } from '@modern-js/runtime/model';
-
-function LocalCounter() {
-  const [state, actions] = useLocalModel(countModel);
-
-  return (
-    <div>
-      <div>local counter: {state.value}</div>
-      <button onClick={() => actions.add()}>add</button>
-    </div>
-  );
-}
-```
-
-分别点击 `Counter` 和 `LocalCounter` 的 `add` 按钮，两者的状态互不影响：
-
-![local-model](https://lf3-static.bytednsdoc.com/obj/eden-cn/eueh7vhojuh/modern/local-model.gif)
-
-完整的示例代码可以在[这里](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/runtime-api/local-model)查看。
-
-## 在组件外使用
-
-在实际业务场景中，有时候我们需要在 React 组件外使用 Model，例如在工具函数中访问 State、执行 Actions 等。这个时候，我们就需要使用 Store。 Store 是一个底层概念，一般情况下用户接触不到，它负责存储和管理整个应用的状态。Reduck 的 Store 基于 [Redux 的 Store](https://redux.js.org/api/store) 实现，增加了 Reduck 特有的 API，如 `use` 。
-
-首先，在组件内调用 `useStore` 获取当前应用使用的 `store` 对象，并挂载到组件外的变量上：
-
-```ts
-let store; // 组件外部 `store` 对象的引用
-function setStore(s) {
-  store = s;
-}
-function getStore() {
-  return store;
-}
-
-function Counter() {
-  const [state] = useModel(countModel);
-  const store = useStore();
-  // 通过 useMemo 避免不必要的重复设置
-  useMemo(() => {
-    setStore(store);
-  }, [store]);
-
-  return (
-    <div>
-      <div>counter: {state.value}</div>
-    </div>
-  );
-}
-```
-
-通过 `store.use` 可以获取 Model 对象，`store.use` 的用法同 `useModel` 相同。以计数器应用为例，我们在组件树外，每 1s 对计数器值
-执行自增操作：
-
-```ts
-setInterval(() => {
-  const store = getStore();
-  const [, actions] = store.use(countModel);
-  actions.add();
-}, 1000);
-```
-
-完整的示例代码可以在[这里](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/runtime-api/counter-model-outof-react)查看。
-
-:::info
-如果是通过 [`createStore`](/apis/app/runtime/model/create-store) 手动创建的 Store 对象，无需通过 `useStore` 在组件内获取，即可直接使用。
-
-:::
-
-:::info 补充信息
-本节涉及的 API 的详细定义，请参考[这里](/apis/app/runtime/model/model_)。
-
-:::

package/docs/zh/guides/topic-detail/model/use-out-of-modernjs.mdx

@@ -1,46 +0,0 @@
-# 单独使用 Reduck
-
-在 Modern.js 以外，单独集成 Reduck 使用时，主要需要做以下修改：
-
-1. 安装 Reduck 相关包
-
-在项目中安装 Reduck 包：`@modern-js-reduck/react`。
-
-2. API 导入包名
-
-在 Modern.js 中使用时，Reduck 导出 API 的包名为：`@modern-js/runtime/model`。单独使用 Reduck 时，导出包名为：`@modern-js-reduck/react`。
-
-3. 包裹 `Provider` 组件
-
-Modern.js 自动在应用的入口组件上，包裹了用于注入 Reduck 全局 Store 的 [`Provider`](/apis/app/runtime/model/Provider) 组件。单独使用 Reduck 时，需要手动完成。
-
-示例：
-
-```tsx
-// 根组件
-const Root = () => {
-  return (
-    <Provider>
-      {/* 应用入口组件 */}
-      <App />
-    </Provider>
-  );
-};
-```
-
-4. 功能配置
-
-在 Modern.js 中使用时，可以通过 [`runtime.state`](/configure/app/runtime/state) 对 Reduck 功能进行配置。单独使用时，需要通过 [`Provider`](/apis/app/runtime/model/Provider) 的 `config` 或 `store` 参数配置。
-
-示例：
-
-```tsx
-const Root = () => {
-  return (
-    {/* 关闭 Redux DevTools */}
-    <Provider config={{ devTools: false }}>
-      <App />
-    </Provider>
-  )
-}
-```

package/docs/zh/plugin/official/cli-plugins/plugin-swc.mdx

@@ -1,351 +0,0 @@
----
-sidebar_position: 2
----
-
-# SWC 插件
-
-:::warning
-**当前文档中的 SWC 功能已停止迭代**，我们更推荐使用 Rspack + SWC 的方案。
-
-请参考[「使用 Rspack」](/guides/advanced-features/rspack-start.html)了解更多。
-
-:::
-
-import SWC from '@site-docs/components/swc.mdx';
-
-<SWC />
-
-## 适用场景
-
-在使用 SWC 插件之前，请先了解一下 SWC 插件的适用场景和局限性，以明确你的项目是否需要使用 SWC 插件。
-
-### Rspack 场景
-
-如果你的项目中已经使用了 Rspack 作为打包工具，那么你不需要接入 SWC 插件，因为 Rspack 默认会使用 SWC 进行转译和压缩，各个 SWC 编译能力可以开箱即用。
-
-如果你使用 Rspack 时配置了当前的 SWC 插件，它将不会产生任何效果。
-
-### Babel 插件
-
-如果你的项目需要注册一些自定义的 Babel 插件，由于 SWC 替代了 Babel 作为转译工具，因此使用 SWC 后，你将无法注册和使用 Babel 插件。
-
-对于大部分常见的 Babel 插件，你可以在 SWC 中找到对应的替代品，比如：
-
-- `@babel/preset-env`: 使用 [presetEnv](#presetenv) 代替。
-- `@babel/preset-react`: 使用 [presetReact](#presetreact) 代替。
-- `babel-plugin-import`：使用 [source.transformImport](/configure/app/source/transform-import) 代替。
-- `babel-plugin-lodash`：使用 [extensions.lodash](#extensionslodash) 代替。
-- `@emotion/babel-plugin`：使用 [extensions.emotion](#extensionsemotion) 代替。
-- `babel-plugin-styled-components`：使用 [extensions.styledComponents](#extensionsstyledcomponents) 代替。
-- `@babel/plugin-react-transform-remove-prop-types`: 使用 [reactUtils.removePropTypes](#extensionsreactutils) 代替。
-
-如果你使用了 SWC 尚未支持的 Babel 插件能力，在切换到 SWC 编译后，将无法再使用它们。你可以到 [swc-plugins](https://github.com/web-infra-dev/swc-plugins) 仓库下通过 issues 进行反馈，我们会评估是否需要内置支持。
-
-### 产物体积
-
-在使用 SWC 来代替 [terser](https://github.com/terser/terser) 和 [cssnano](https://github.com/cssnano/cssnano) 进行代码压缩时，构建产物的体积可能会出现少量变化。在 JavaScript 代码压缩方面，SWC 的压缩率是优于 terser 的；在 CSS 代码压缩方面，SWC 的压缩率稍逊于 cssnano。
-
-对于压缩工具之间的详细对比，可以参考 [minification-benchmarks](https://github.com/privatenumber/minification-benchmarks)。
-
-## 快速开始
-
-### 在 Modern.js 框架中使用
-
-Modern.js 框架对 SWC 插件进行了封装，你可以通过以下方式来使用：
-
-import EnableSWC from '@site-docs/components/enableSwc.mdx';
-
-<EnableSWC />
-
-That's it! 现在你可以在项目中无缝使用 SWC 的转译和压缩能力了。
-
-## 配置
-
-- **类型：**
-
-```ts
-type PluginConfig =
-  | ObjPluginConfig
-  | ((
-      config: ObjPluginConfig,
-      utils: { mergeConfig: typeof lodash.merge; setConfig: typeof lodash.set },
-    ) => ObjPluginConfig | void);
-
-// SwcOptions 为 swc 配置项 https://swc.rs/docs/configuration/compilation
-interface ObjPluginConfig extends SwcOptions {
-  presetReact?: ReactConfig;
-  presetEnv?: EnvConfig;
-  jsMinify?: boolean | JsMinifyOptions;
-  cssMinify?: boolean | CssMinifyOptions;
-  extensions?: Extensions;
-  overrides?: Overrides;
-}
-```
-
-插件配置在 SWC 配置的基础上，为了简化部分深层配置和为提高开发体验，进行了部分拓展，例如当使用对象形式配置时，可以使用 `presetReact` 以及 `presetEnv` 快速配置 react 以及语法降级相关功能，另外不属于插件特有的配置也会直接透传给 swc。
-
-当使用函数形式配置时，则会传入插件内部产出的默认配置，可以对其进行修改或返回新的配置。
-
-### presetReact
-
-- **类型：** SWC 中的 [react](https://swc.rs/docs/configuration/compilation#jsctransformreact) 配置。
-
-对标 `@babel/preset-react`。传入的值会与默认配置进行合并。
-
-插件默认会自动根据你的 `react` 版本确定 `runtime` 字段，如果 `react` 版本大于 17.0.0，会设置成 `automatic`，否则设置成 `classic`。
-
-### presetEnv
-
-- **类型：** SWC 中的 [presetEnv](https://swc.rs/docs/configuration/supported-browsers#options)。
-
-对标 `@babel/preset-env`。传入的值会与默认配置进行合并。
-默认配置为:
-
-```ts
-{
-  targets: '', // 自动从项目中获取 browserslist
-  mode: 'usage',
-}
-```
-
-### jsMinify
-
-- **类型：** `boolean` 或者 [terser 中的 compress 配置](https://terser.org/docs/api-reference.html#compress-options)。
-- **默认值：** `{ compress: {}, mangle: true }`。
-
-如果配置 `false` 将不会使用 SWC 的压缩能力，配置 `true` 会启用默认压缩配置，如果配置是对象，则会与默认配置进行合并。
-
-### cssMinify
-
-- **类型：** `boolean`
-- **默认值：** `true`
-
-是否启用 SWC 对 CSS 文件进行压缩，若启用会使得 CSS 压缩性能提高，但压缩率会略微降低。
-
-### overrides
-
-- **类型：**
-
-```ts
-interface Overrides extends SwcOptions {
-  test: RegExp;
-  include: RegExp[];
-  exclude: RegExp[];
-}
-```
-
-- **默认值：** `undefined`
-
-对指定文件运用另外的配置。例如需要对 `foo.ts` 的语法降级成 ie 11，则可以如下配置：
-
-```ts
-{
-  test: /foo.ts/,
-  env: { targets: 'ie 11' }
-}
-```
-
-该配置会与默认配置进行合并，并且不会影响到其他文件。
-
-### extensions
-
-- **类型：** `Object`
-
-`extensions` 包含了从 Babel 移植过来的一些插件能力。
-
-#### extensions.reactUtils
-
-- **类型：**
-
-```ts
-type ReactUtilsOptions = {
-  autoImportReact?: boolean;
-  removeEffect?: boolean;
-  removePropTypes?: {
-    mode?: 'remove' | 'unwrap' | 'unsafe-wrap';
-    removeImport?: boolean;
-    ignoreFilenames?: string[];
-    additionalLibraries?: string[];
-    classNameMatchers?: string[];
-  };
-};
-```
-
-一些用于 `React` 的工具，包括以下配置项:
-
-**reactUtils.autoImportReact**
-
-- **类型：** `boolean`
-
-自动引入 `React`, `import React from 'react'`，用于 `jsx` 转换使用 `React.createElement`。
-
-**reactUtils.removeEffect**
-
-- **类型：** `boolean`
-
-移除 `useEffect` 调用。
-
-**reactUtils.removePropTypes**
-
-- **类型：**
-
-```ts
-type RemovePropTypesOptions = {
-  mode?: 'remove' | 'unwrap' | 'unsafe-wrap';
-  removeImport?: boolean;
-  ignoreFilenames?: string[];
-  additionalLibraries?: string[];
-  classNameMatchers?: string[];
-};
-```
-
-移除 `React` 组件在运行时的类型判断。移植自 [@babel/plugin-react-transform-remove-prop-types](https://github.com/oliviertassinari/babel-plugin-transform-react-remove-prop-types)。
-
-相应配置和 `@babel/plugin-react-transform-remove-prop-types` 插件保持一致。
-
-#### extensions.lodash
-
-- **类型：**
-
-```ts
-type LodashOptions = {
-  cwd?: string;
-  ids?: string[];
-};
-```
-
-- **默认值：**
-
-```ts
-const defaultOptions = {
-  cwd: process.cwd(),
-  ids: ['lodash', 'lodash-es'],
-};
-```
-
-移植自 [babel-plugin-lodash](https://github.com/lodash/babel-plugin-lodash)，用于自动将 Lodash 的引用转换为按需引入，从而减少打包后的 Lodash 代码大小。
-
-```ts
-// Input
-import { get, throttle } from 'lodash';
-
-// Output
-import get from 'lodash/get';
-import throttle from 'lodash/throttle';
-```
-
-#### extensions.styledComponents
-
-- **类型：**
-
-```ts
-boolean | {
-  displayName?: boolean; // 默认开发模式开启, 生产模式关闭,
-  ssr?: boolean; // 默认开启
-  fileName?: boolean; // 默认开启
-  topLevelImportPaths?: string[]; // 默认空
-  meaninglessFileNames?: string[]; // 默认为 ["index"].
-  cssProp?: boolean; // 默认开启
-  namespace?: string; // 默认空
-};
-```
-
-由 Next.js 团队移植自 [babel-plugin-styled-components](https://github.com/styled-components/babel-plugin-styled-components)。
-
-#### extensions.emotion
-
-- **类型：**
-
-```ts
-boolean | {
-  sourceMap?: boolean, // 默认开启
-  autoLabel?: 'never' | 'dev-only' | 'always', // 默认 'dev-only'
-  // 默认 '[local]'.
-  // 允许的值为: `[local]` `[filename]` 以及 `[dirname]`
-  // 只有当 autoLabel 设置成 'dev-only' 或者 'always' 才会生效.
-  // 该配置允许你定义结果标签的格式，该格式的组成是字符串以及可以由方括号包裹字符串作为变量
-  // 例如对于 "my-classname--[local]"，其中的 [local] 会被替换成相应的变量
-  labelFormat?: string,
-  // 默认值 undefined.
-  // 该配置允许让编译器知道哪一个引入需要进行转换，所以如果你重导出了 emotion
-  // 的导出，你仍然可以使用该插件进行转换
-  importMap?: {
-    [packageName: string]: {
-      [exportName: string]: {
-        canonicalImport?: [string, string],
-        styledBaseImport?: [string, string],
-      }
-    }
-  },
-},
-```
-
-由 Next.js 团队移植自 [@emotion/babel-plugin](https://www.npmjs.com/package/@emotion/babel-plugin)。
-
-#### extensions.pluginImport
-
-:::tip
-Modern.js 提供了 [source.transformImport](/configure/app/source/transform-import) 配置项，因此你不需要手动配置 `extensions.pluginImport`。
-:::
-
-移植自 [babel-plugin-import](https://github.com/umijs/babel-plugin-import)，配置选项保持一致。
-
-一些配置可以传入函数，例如 `customName`，`customStyleName` 等，这些 JavaScript 函数会由 Rust 通过 Node-API 调用，这种调用会造成一些性能劣化。
-
-简单的函数逻辑其实可以通过模版语言来代替，因此`customName`，`customStyleName` 等这些配置除了可以传入函数，也可以传入字符串作为模版来代替函数，提高性能。
-
-我们以下面代码为例说明:
-
-```ts
-import { MyButton as Btn } from 'foo';
-```
-
-添加以下配置：
-
-```ts
-PluginSWC({
-  extensions: {
-    pluginImport: [
-      {
-        libraryName: 'foo',
-        customName: 'foo/es/{{ member }}',
-      },
-    ],
-  },
-});
-```
-
-其中的 `{{ member }}` 会被替换为相应的引入成员，转换后:
-
-```ts
-import Btn from 'foo/es/MyButton';
-```
-
-可以看出配置 `customName: "foo/es/{{ member }}"` 的效果等同于配置 `` customName: (member) => `foo/es/${member}`  ``，但是不会有 Node-API 的调用开销。
-
-这里使用到的模版是 [handlebars](https://handlebarsjs.com)，模版配置中还内置了一些有用的辅助工具，还是以上面的导入语句为例，配置成：
-
-```ts
-PluginSWC({
-  extensions: {
-    pluginImport: [
-      {
-        libraryName: 'foo',
-        customName: 'foo/es/{{ kebabCase member }}',
-      },
-    ],
-  },
-});
-```
-
-会转换成下面的结果:
-
-```ts
-import Btn from 'foo/es/my-button';
-```
-
-除了 `kebabCase` 以外还有 `camelCase`，`snakeCase`，`upperCase`，`lowerCase` 可以使用。
-
-## 限制
-
-不支持 `@babel/plugin-transform-runtime` 以及其他自定义的 Babel 插件。

package/docs/zh/plugin/official/cli-plugins/plugin-tailwind.mdx

@@ -1,5 +0,0 @@
-# Tailwind CSS 插件
-
-Tailwind CSS 是一个以 Utility Class 为基础的 CSS 框架和设计系统，可以快速地为组件添加常用样式，同时支持主题样式的灵活扩展。
-
-详细内容可以参考 [使用 Tailwind CSS](/guides/basic-features/css/tailwindcss)。

package/docs/zh/plugin/official/rsbuild-plugins/_meta.json

@@ -1 +0,0 @@
-["plugin-esbuild"]