@aithe/aithe-ui 26.2.2 → 26.3.1

package/docs/quickstart.md

@@ -1,11 +1,11 @@
 # Quick Start / 快速上手
 
-Aithe UI 是基于 Lit 3.x 的 Web Components 组件库，提供 79 个可复用 UI 组件、22 种内置主题和完整的国际化支持。
+Aithe UI 是基于 Lit 3.x 的 Web Components 组件库，提供 100+ 个可复用 UI 组件、25 种内置主题、8 种形状风格、9 种阴影风格、4 种排版风格和完整的国际化支持。
 
 ## 安装
 
 ```bash
-npm install aithe-ui
+npm install @aithe/aithe-ui
 ```
 
 ## 基本使用
@@ -14,13 +14,13 @@ npm install aithe-ui
 
 ```ts
 // 导入整个库（自动注册所有组件 + 初始化主题和 i18n）
-import 'aithe-ui';
+import '@aithe/aithe-ui';
 ```
 
-仅此一行即可使用所有组件——`import 'aithe-ui'` 会自动完成：
+仅此一行即可使用所有组件——`import '@aithe/aithe-ui'` 会自动完成：
 
-- 注册全部 79 个 Custom Elements
-- 注入 22 种主题的 CSS 变量
+- 注册全部 100 个 Custom Elements
+- 注入 25 种主题的 CSS 变量
 - 初始化 i18n（默认 `en-US`）
 
 ### 2. 在 HTML 中使用组件
@@ -39,40 +39,132 @@ import 'aithe-ui';
 
 ```ts
 // 仅导入需要的组件
-import { AitheButton } from 'aithe-ui';
-import { AitheInput } from 'aithe-ui';
+import { AitheButton } from '@aithe/aithe-ui';
+import { AitheInput } from '@aithe/aithe-ui';
 ```
 
-> **注意**：按需导入时需手动调用 `initializeAitheUI()` 以注入主题和 i18n。
+### 4. 切换主题
 
 ```ts
-import { initializeAitheUI, AitheButton, AitheInput } from 'aithe-ui';
+import { aitheUI } from '@aithe/aithe-ui';
 
-initializeAitheUI(); // 必须手动调用
+// 切换到暗色主题（自动持久化到 localStorage）
+aitheUI.setTheme('dark');
 ```
 
-### 4. 切换主题
+或使用内置的统一外观切换器（整合主题、阴影、形状和排版）：
+
+```html
+<aithe-theme-switch></aithe-theme-switch>
+```
+
+### 5. 切换形状风格
+
+形状风格与颜色主题正交，可自由组合。8 种内置形状风格：`sharp`、`smooth`、`rounded`（默认）、`rounder`、`pill`、`circle`、`chamfer`、`organic`。
 
 ```ts
-import { setAitheTheme } from 'aithe-ui';
+import { aitheUI } from '@aithe/aithe-ui';
 
-// 切换到暗色主题（自动持久化到 localStorage）
-setAitheTheme('dark');
+// 切换到胶囊形状（自动持久化到 localStorage）
+aitheUI.setShape('pill');
+```
+
+或使用内置的形状选择器组件：
+
+```html
+<aithe-shape-picker></aithe-shape-picker>
+```
+
+也可使用主题预览组件同时预览和切换主题、形状、阴影和排版：
+
+```html
+<aithe-theme-preview></aithe-theme-preview>
+```
+
+> 详细的形状风格说明见 [主题系统 — 形状风格](theming.md#形状风格shape)。
+
+### 6. 切换阴影风格
+
+阴影风格与颜色主题、形状风格正交，可自由组合。9 种内置阴影风格：`flat`、`neumorphism`、`skeuomorphic`、`glassmorphism`、`cyber`、`deep`、`diffuse`、`sharp-business`、`retro`。
+
+```ts
+import { aitheUI } from '@aithe/aithe-ui';
+
+// 切换到新拟态阴影（自动持久化到 localStorage）
+aitheUI.setShadow('neumorphism');
+```
+
+或使用内置的阴影选择器组件：
+
+```html
+<aithe-shadow-picker></aithe-shadow-picker>
+```
+
+> 详细的阴影风格说明见 [主题系统 — 阴影风格](theming.md#阴影风格shadow)。
+
+### 7. 切换排版风格
+
+排版风格与颜色主题、形状风格、阴影风格正交，可自由组合。4 种内置排版风格：`minimal`（极简）、`business`（商务，默认）、`luxury`（轻奢）、`compact`（紧凑信息流）。
+
+```ts
+import { aitheUI } from '@aithe/aithe-ui';
+
+// 切换到极简排版（自动持久化到 localStorage）
+aitheUI.setTypo('minimal');
+```
+
+或使用内置的排版选择器组件：
+
+```html
+<aithe-typo-picker></aithe-typo-picker>
+```
+
+也可使用主题预览组件同时预览和切换主题、形状、阴影和排版：
+
+```html
+<aithe-theme-preview></aithe-theme-preview>
+```
+
+> 详细的排版风格说明见 [主题系统 — 排版风格](theming.md#排版风格typography)。
+
+### 8. 切换布局密度
+
+```ts
+import { aitheUI } from '@aithe/aithe-ui';
+
+// 切换到紧凑布局（自动持久化到 localStorage）
+aitheUI.setLayout('compact');
 ```
 
-或使用内置的主题选择器组件：
+内置布局密度：`compact`（紧凑）、`medium`（默认）、`wide`（宽松）。
+
+### 9. 使用路由
+
+```ts
+import { Router } from '@aithe/aithe-ui';
+
+const router = new Router({
+  mode: 'history',
+  routes: [
+    { path: '/', component: 'home-page' },
+    { path: '/user/:id', component: 'user-page' },
+    { path: '*', component: 'not-found-page' },
+  ],
+});
+router.start();
+```
 
 ```html
-<aithe-theme-picker></aithe-theme-picker>
+<aithe-page .router="${router}"></aithe-page>
 ```
 
-### 5. 切换语言
+### 10. 切换语言
 
 ```ts
-import { setAitheLocale } from 'aithe-ui';
+import { aitheUI } from '@aithe/aithe-ui';
 
 // 切换到中文（自动持久化到 localStorage）
-setAitheLocale('zh-CN');
+aitheUI.setLocale('zh-CN');
 ```
 
 或使用内置的语言切换组件：
@@ -81,6 +173,45 @@ setAitheLocale('zh-CN');
 <aithe-locale-switch></aithe-locale-switch>
 ```
 
+### 11. 使用 DataHub 数据中间层
+
+Aithe UI 内置 DataHub 数据中间层，提供统一的请求调度、缓存、去重、Mock 支持等功能：
+
+```ts
+import dataHub from '@aithe/aithe-ui';
+
+// 配置全局参数
+dataHub.updateConfig({
+  baseURL: '/api',
+  defaultTimeout: 15000,
+});
+
+// 设置请求拦截器（如注入 Token）
+dataHub.setRequestInterceptor((req) => {
+  req.options.headers = { ...req.options.headers, Authorization: `Bearer ${getToken()}` };
+  return req;
+});
+
+// 发起查询请求（自动缓存+去重）
+const res = await dataHub.request('/order/query', { orderId: '123' });
+console.log(res.data);
+
+// 发起提交请求（自动幂等防护）
+await dataHub.request('/order/submit', { items: [] });
+
+// 使用 Mock 数据（开发阶段）
+const res = await dataHub.request(
+  '/order/query',
+  {},
+  {
+    mock: true,
+    mockData: { list: [], total: 0 },
+  },
+);
+```
+
+> 完整的 DataHub 文档见 [DataHub 数据中间层](datahub.md)。
+
 ## 完整示例
 
 ```html
@@ -93,12 +224,14 @@ setAitheLocale('zh-CN');
   </head>
   <body>
     <script type="module">
-      import 'aithe-ui';
-      import { setAitheTheme, setAitheLocale } from 'aithe-ui';
-
-      // 可选：设置初始主题和语言
-      setAitheTheme('light');
-      setAitheLocale('en-US');
+      import '@aithe/aithe-ui';
+      import { aitheUI } from '@aithe/aithe-ui';
+
+      // 可选：设置初始主题、形状风格、阴影风格和排版风格
+      aitheUI.setTheme('light');
+      aitheUI.setShape('rounded');
+      aitheUI.setShadow('flat');
+      aitheUI.setTypo('business');
     </script>
 
     <aithe-button type="primary">Hello Aithe</aithe-button>
@@ -108,8 +241,9 @@ setAitheLocale('zh-CN');
 
 ## 下一步
 
-- [使用指南](guide.md) — 组件通用 API、事件、插槽
-- [主题系统](theming.md) — 22 种内置主题、自定义主题、CSS 变量
+- [使用指南](guide.md) — 组件通用 API、事件、插槽、形状风格、布局密度、路由
+- [主题系统](theming.md) — 25 种内置主题、8 种形状风格、9 种阴影风格、自定义主题、CSS 变量
 - [国际化](i18n.md) — 多语言支持、自定义翻译
+- [DataHub 数据中间层](datahub.md) — 请求调度、缓存、去重、Mock
 - [框架集成](framework-integration.md) — React / Vue / Angular / Svelte 集成
-- [API 参考](api/summary.md) — 全部 79 个组件的详细 API 文档
+- [API 参考](api/summary.md) — 全部 100 个组件的详细 API 文档