docs: update docs for v2 (IDuxFE#1757)

packages/site/src/docs/CustomizeTheme.zh.md

@@ -295,7 +295,7 @@ token `getter` 只会在第一次注册成功的时候实际执行，因此不
 
 ### IxThemeProvider
 
-详情请参考 [Tooltip](/components/theme/zh).
+详情请参考 [ThemeProvider](/components/theme/zh).
 
 ### 基础Token
 
@@ -572,22 +572,75 @@ token `getter` 只会在第一次注册成功的时候实际执行，因此不
 
 如果由于某些限制无法使用 IxThemeProvider，我们在打包产物中增加了不同主题下的全部 `css` 变量，可以直接在项目中引入这些变量并针对性覆盖。
 
+可以将全量的变量直接引入到项目中：
+
+```ts
+// 引入默认主题全量变量
+import '@idux/components/default.full.css'
+
+// 引入暗黑主题全量变量
+import '@idux/components/dark.full.css'
+
+// 引入pro组件默认主题全量变量
+import '@idux/pro/default.full.css'
+
+// 引入pro组件暗黑主题全量变量
+import '@idux/pro/dark.full.css'
+```
+
+在按需引入的场景中，需要首先引入全局token对应的变量：
+
 ```ts
 // 引入默认主题全局变量
 import '@idux/components/default.css'
 
 // 引入暗黑主题全局变量
 import '@idux/components/dark.css'
+```
 
-// 引入默认主题全量变量
-import '@idux/components/default.full.css'
+然后，可以选择使用 `unplugin-vue-components` 来按需引入主题变量：
 
-// 引入暗黑主题全量变量
-import '@idux/components/dark.full.css'
+- Vite:
+
+```ts
+// vite.config
+import { IduxResolver } from 'unplugin-vue-components/resolvers'
+import Components from 'unplugin-vue-components/vite'
+
+// https://vitejs.dev/config/
+export default defineConfig({
+  plugins: [
+    /* ... */
+    Components({
+      resolvers: [IduxResolver({ importStyle: 'css', importStyleTheme: 'default' })],
+    }),
+  ]
+})
+```
 
+- Webpack:
+
+```ts
+// webpack.config
+import { IduxResolver } from 'unplugin-vue-components/resolvers'
+import Components from 'unplugin-vue-components/webpack'
+
+module.exports = {
+  plugins: [
+    /* ... */
+    Components({
+      resolvers: [IduxResolver({ importStyle: 'css', importStyleTheme: 'default' })],
+    }),
+  ]
+}
+```
+
+或者可以手动引入组件的css变量
+
+```ts
 // 引入默认主题组件变量
-import '@idux/components/button/theme/default.css'
+import '@idux/components/button/theme/default'
 
 // 引入暗黑主题组件变量
-import '@idux/components/button/theme/default.css'
+import '@idux/components/button/theme/dark'
 ```

packages/site/src/docs/Faq.zh.md

@@ -1,14 +1,14 @@
 ---
 category: docs
 title: 常见问题
-order: 10
+order: 11
 ---
 
 ## 本地和官方文档的样式不一致？
 
 请确认是否正确引入了组件样式，请参考: [快速上手](/docs/getting-started/zh) 和 [定制主题](/docs/customize-theme/zh) 进行一些必要的配置。
 
-需要强调的是，在没有特殊需求的情况下，请使用组件库提供的 reset 样式，`"@idux/components/style/core/reset.default.css"`。如果没有引入它，务必确认是否提供了必要的全局样式，参见[#1194](https://github.com/IDuxFE/idux/issues/1194)。
+需要强调的是，在没有特殊需求的情况下，请使用组件库提供的 reset 样式，`"@idux/components/style/core/reset.css"`。如果没有引入它，务必确认是否提供了必要的全局样式，参见[#1194](https://github.com/IDuxFE/idux/issues/1194)。
 
 ## 无法通过 `useModal` 创建弹窗组件？(`useMessage`, `useDrawer`...)
 

packages/site/src/docs/GettingStarted.zh.md

@@ -51,14 +51,13 @@ npm install @idux/cdk @idux/components @idux/pro
 // idux.ts
 import { type App } from "vue";
 
-// 示例导入的是 default 主题，如果需要使用其他主题或者定制主题，请参考定制主题的文档
 // 如果需要 css 按需加载，移除下面 2 行代码
-import "@idux/components/default.full.css";
-import "@idux/pro/default.css";
+import "@idux/components/index.full.css";
+import "@idux/pro/index.css";
 // 如果需要 css 按需加载，则按需添加下面的代码
 // import "@idux/cdk/index.css";
-// import "@idux/components/style/core/reset.default.css";
-// import "@idux/components/style/core/reset-scroll.default.css";
+// import "@idux/components/style/core/reset.css";
+// import "@idux/components/style/core/reset-scroll.css";
 
 // 如果需要 js 按需加载，移除下面 3 行代码
 import IduxCdk from "@idux/cdk";
@@ -79,8 +78,6 @@ const loadIconDynamically = (iconName: string) => {
 };
 
 const customConfig = { icon: { loadIconDynamically } }
-// 如果是 seer 主题
-// customConfig = merge(seerConfig, { icon: { loadIconDynamically } })
 const globalConfig = createGlobalConfig(customConfig)
 
 const install = (app: App): void => {
@@ -124,6 +121,30 @@ export default defineConfig({
 });
 ```
 
+### 引入Provider
+
+#### IxThemeProvider
+
+在 Idux v2 版本中，我们增加了 `IxThemeProvider` 来管理主题配置并动态插入主题css变量，因此需要在 `vue` 应用的最外围包裹使用 `IxThemeProvider`。
+
+例如，可以在 App.vue 中这样写：
+
+```html
+<template>
+  <IxThemeProvider>
+    <div class="app-wrapper">
+      ...
+    </div>
+  </IxThemeProvider>
+</template>
+```
+
+在不配置 `presetTheme` 的情况下，默认使用 `default` 主题，如果有主题定制或动态主题的需求，请查看 [定制主题](/docs/customize-theme/zh)
+
+#### 其他Provider
+
+如果有需求使用 `useMessage` 等 API，需要根据实际情况引入其他的 `Provider`，详情请查看具体组件文档。
+
 ### 类型提示
 
 我们提供了所有组件的类型定义，你可以参考下面的代码进行导入类型声明。
@@ -160,7 +181,7 @@ npm run dev
 
 当你只用到 `@idux` 的部分组件且比较在意包体积大小时，可以只加载用到的组件。
 
-推荐**仅按需加载 js 代码**，css 代码无需按需加载, 首先你需要修改 `idux.ts` 中的代码。
+首先你需要修改 `idux.ts` 中的代码。
 
 ```diff
 - import IduxCdk from "@idux/cdk";
@@ -173,6 +194,48 @@ const install = (app: App): void => {
 };
 ```
 
+之后需要引入 `cdk` 的样式文件，再根据需求引入 `reset` 样式
+
+```ts
+import "@idux/cdk/index.css";
+import "@idux/components/style/core/reset.css";
+import "@idux/components/style/core/reset-scroll.css";
+```
+
+需要特别注意的是，在按需引入的场景下，`reset` 样式在编译之后的引入顺序可能在组件样式之后，因此可能会导致组件样式异常。
+这种情况下，需要将 `reset` 样式放在 `public` 目录下在 `index.html` 中引入，也可以通过其他方式解决，我们推荐使用 `vite-plugin-static-copy` 来处理这两个样式
+
+```ts
+// vite.config.ts
+import { viteStaticCopy } from "vite-plugin-static-copy";
+
+// https://vitejs.dev/config/
+export default defineConfig({
+  plugins: [
+    ...
+    viteStaticCopy({
+      targets: [
+        {
+          src: "./node_modules/@idux/components/style/core/reset*.css",
+          dest: "assets",
+        },
+      ],
+    }),
+  ],
+});
+```
+
+```html
+<html>
+  <head>
+    ...
+    <link rel="stylesheet" href="/assets/reset.css" />
+    <link rel="stylesheet" href="/assets/reset-scroll.css" />
+  </head>
+  ...
+</html>
+```
+
 然后可以选择以下任意一种方式进行加载组件代码。
 
 - Vite:
@@ -188,7 +251,8 @@ export default defineConfig({
     /* ... */
     Components({
       resolvers: [IduxResolver()],
-      // 可以通过指定 `importStyle` 来按需加载 css 或 less 代码, 也支持不同的主题
+      // 可以通过指定 `importStyle` 来按需加载 css 或 less 代码
+      // 主题默认会通过 IxThemeProvider 自动插入，但如果使用 IxThemeProvider，可以配置 `importStyleTheme` 来引入组件的 css 变量
       // 别忘了修改 idux.ts 中的样式导入代码
       // resolvers: [IduxResolver({ importStyle: 'css', importStyleTheme: 'default' })],
     }),
@@ -218,7 +282,7 @@ module.exports = {
 ```ts
 // App.vue or other components
 import { IxButton } from "@idux/components/button"
-import "@idux/components/button/style_css"
+import "@idux/components/button/style"
 ```
 
 ## 其他

packages/site/src/docs/GlobalConfig.zh.md

@@ -20,15 +20,13 @@ order: 3
 // main.ts
 import { createApp } from 'vue'
 import { merge } from 'lodash-es'
-import { createGlobalConfig, seerConfig } from '@idux/components/config'
+import { createGlobalConfig } from '@idux/components/config'
 
 const loadIconDynamically = (iconName: string) => {
   return fetch(`/idux-icons/${iconName}.svg`).then(res => res.text())
 }
 
 const customConfig = { icon: { loadIconDynamically } }
-// 如果是 seer 主题
-// customConfig = merge(seerConfig, { icon: { loadIconDynamically } })
 const globalConfig = createGlobalConfig(customConfig)
 
 createApp(App).use(globalConfig)

packages/site/src/docs/V1ToV2.zh.md

@@ -0,0 +1,102 @@
+---
+category: docs
+title: 从 V1 到 V2
+order: 10
+---
+
+这个文档可以帮助你快速从 `1.x` 版本升级到 `2.x` 版本。
+
+## 2.0 的变化
+
+### typography 被移除
+
+由于 `typography` 是我们早期开发的组件，其功能甚是简陋，且不符合设计规范的，我们在 `2.0` 的初期将它移除了，请不要再使用。
+
+后续我们可能会根据设计需要提供更完整的 `typography` 支持，但是暂时没有计划。
+
+### 设计规范被重新整理
+
+在 `1.x` 版本的开发期间，我们很无奈得经历了一阶段没有设计师参与的开发，因此导致我们的设计并不规范。
+
+在我们得到了设计师的支持之后，设计规范逐渐产生，我们也在那之后提供了一套名为 `seer` 的主题，但原本的默认主题并没有设计规范支持。
+
+在 `2.0` 之后，我们彻底放弃了原先 `default` 主题的支持，并将 `seer` 作为当前的默认主题，全局配置中暴露的 `seerConfig` 也被移除并归并到了默认配置。
+
+并且，我们根据设计规范产出了完整的设计token, 基于这些token对组件库的样式进行了大规模的重构，这也是 `2.0` 发布的最大原因。
+
+### 新的动态主题机制
+
+在 `1.x` 和 `0.x` 版本的初期，我们支持了一套以 `less` 变量为基础的主题变量，但是这些变量的定义太过于随意以至于并不能真正实现主题自定义而最终无法维护。
+
+在 `1.x` 的后面阶段，我们初步整理了少量的 `css` 变量作为主题支持，但是受限于技术债务，并没有能够让其真正发挥作用。
+
+在 `2.0` 版本中，我们支持了整套的基于设计token的动态主题方案，使用 `ThemeProvider` 替代了原先的 `less` 和 `css` 变量，并将原先 `css` 变量彻底移除，`less` 变量大部分移除并不推荐使用。
+
+受益于新的主题机制，动态的主题切换不再需要手动替换 `css` 文件，更不需要前期的主题打包，一切都通过 `javascript` 变量来控制，并且我们建立了相对完整的主题变量派生逻辑，使得替换基础变量就可以达到自定义新主题的效果。
+
+另外，在新的主题机制中，我们使主题的嵌套和局部覆盖变成了可能。
+
+总结：
+
+- 原有的 `css` 变量被全部移除，`less` 变量被大部分移除并不推荐使用。
+- 需要在项目中引入 `IxThemeProvider` 并包裹项目根组件
+
+### 样式入口改变
+
+由于不需要原有的主题方案，原有的 `@idux/components/{default,seer}.css`、`@idux/components/{default,seer}.full.css`、 `*/style/themes` 下的内容被全部移除，`pro` 组件同理。
+
+现在样式的入口改为 `@idux/components/index.css` 和 `@idux/components/index.full.css`，`pro` 组件同理。
+
+组件按需引入的样式入口改为了 `*/style/index.js` 和 `*/style/index_css.js`。
+
+为了兼容某些不希望使用 `IxThemeProvider` 的场景，我们将全部的主题变量预先打包了，并放在了项目中，详情请参考 [定制主题](/docs/customize-theme/zh#FAQ)
+
+## 升级准备
+
+### 移除废弃的API支持
+
+在 1.x 的开发过程中，我们逐渐发现一些 API 的定义并不合理，我们将这些 API 标记为了 `deprecated`，这些 API 在 `2.0` 的正式版将不再支持，请替换成推荐的 API。
+
+注意： 2.0 的正式版之前我们暂时不会移除这些 API，只有 `IxTag` 的 `color` 被移除了，因为它影响了后面的设计。
+
+## 开始升级
+
+### 保存现在的代码
+
+由于升级过程中可能会遇到问题，请用 `git` 保留现有的代码，避免代码丢失。
+
+### 升级组件库
+
+升级到最新的 `2.0` 组件库
+
+### 去除less变量的引用
+
+除了 `@idux-prefix`，请去掉所有的 `less` 变量的引用。
+
+### 去除原有css变量的引用
+
+原有的 `css` 变量已经被全部移除，如果需要使用新的主题变量，请参考 [定制主题](/docs/customize-theme/zh)
+
+### 修改样式入口
+
+根据上述的描述替换样式入口文件。
+
+### 引入 IxThemeProvider
+
+使用 `IxThemeProvider` 包裹项目根组件。
+
+### 根据需要定制主题
+
+如果新的默认主题不符合项目的设计规范，请根据 [定制主题](/docs/customize-theme/zh) 中的 token 列表修改主题变量
+
+需要注意的是，基础token中的 `fontSize` 仅作为字体大小梯度变量生成的token，实际的字体大小会使用 `fontSizeSm`，这一点可能会在后期更改，例如提供一个 `fontSizeText` token。
+
+### 修改手动按需引入的代码
+
+如果是通过 `unplugin-vue-components`，则无需更改。
+
+### 测试
+
+请不要忽略升级之后的测试环节！请不要忽略升级之后的测试环节！请不要忽略升级之后的测试环节！
+
+我们在 `2.0` 的发布阶段经过了相对完整的测试，但由于项目中的复杂场景以及升级过程中的问题，仍可能出现bug，请不要让组件库的升级导致实际的损失！