@aithe/aithe-ui 26.2.2 → 26.2.3

package/docs/markdown.md

@@ -0,0 +1,432 @@
+# Markdown 模块 / Markdown Module
+
+Aithe UI 内置零依赖的 Markdown 解析与渲染引擎，采用插件架构设计，提供从轻量标签到完整文档渲染的全链路支持。
+
+## 架构概览 / Architecture Overview
+
+```bash
+┌─────────────────────────────────────────────────────┐
+│                    Components                        │
+│  ┌──────────┐  ┌──────────────┐  ┌────────────────┐ │
+│  │ AitheLabel│  │ AitheMarkdown│  │AitheMarkdownEditor││
+│  │ (行内子集)│  │ (完整 GFM)   │  │ (编辑器+预览)    ││
+│  └─────┬────┘  └──────┬───────┘  └───────┬────────┘ │
+└────────┼──────────────┼──────────────────┼──────────┘
+         │              │                  │
+┌────────▼──────────────▼──────────────────▼──────────┐
+│                    Parsers                            │
+│  ┌──────────────────┐  ┌──────────────────────────┐  │
+│  │SimpleMarkdownParser│  │  FullMarkdownParser      │  │
+│  │ (6 plugins)       │  │  (16 plugins)            │  │
+│  └────────┬─────────┘  └───────────┬──────────────┘  │
+│           │                        │                  │
+│           └──────────┬─────────────┘                  │
+│                 ┌────▼────┐                           │
+│                 │MarkdownParser (基类)│                 │
+│                 └────┬────┘                           │
+└──────────────────────┼──────────────────────────────┘
+                       │
+┌──────────────────────▼──────────────────────────────┐
+│                    Plugins                            │
+│  bold  italic  code  del  link  image  heading        │
+│  table  codeFence  list  taskList  blockquote         │
+│  emoji  icon  setextHeading  thematicBreak            │
+└─────────────────────────────────────────────────────┘
+```
+
+### 核心模块文件 / Core Files
+
+| 文件                           | 说明                                                                         |
+| ------------------------------ | ---------------------------------------------------------------------------- |
+| `src/core/markdown/parser.ts`  | 解析器基类 `MarkdownParser`，及 `SimpleMarkdownParser`、`FullMarkdownParser` |
+| `src/core/markdown/plugins.ts` | 所有内置插件定义（16 个 AST 插件 + emoji 映射表）                            |
+| `src/core/markdown/types.ts`   | `AstNode`、`AstPlugin`、`MarkdownLinkHook` 类型定义                          |
+| `src/core/markdown/index.ts`   | 模块统一导出入口                                                             |
+
+---
+
+## MarkdownParser — 解析器基类
+
+`MarkdownParser` 是一个基于 AST（抽象语法树）的 Markdown → HTML 转换器，采用两阶段解析架构（块级 → 行内），零外部依赖。
+
+### 构造函数
+
+```ts
+new MarkdownParser();
+```
+
+### 方法
+
+| 方法             | 签名                                 | 说明                              |
+| ---------------- | ------------------------------------ | --------------------------------- |
+| `use`            | `(plugin: AstPlugin) => this`        | 注册一个 AST 插件，支持链式调用   |
+| `addLinkHook`    | `(hook: MarkdownLinkHook) => this`   | 添加链接处理 hook，支持链式调用   |
+| `removeLinkHook` | `(hook: MarkdownLinkHook) => this`   | 移除指定的链接处理 hook           |
+| `parse`          | `(markdown: string) => string`       | 将 Markdown 文本转换为 HTML       |
+| `parseToAst`     | `(markdown: string) => DocumentNode` | 将 Markdown 文本解析为 AST 文档树 |
+
+### 解析流程
+
+`parse()` 方法内部按以下阶段顺序处理：
+
+1. **块级解析** — 遍历行数组，依次尝试各块级插件（标题、代码块、表格、引用、列表等），匹配则消费对应行并生成块级 AST 节点
+2. **段落处理** — 未被块级插件覆盖的连续文本，收集为段落节点，内部递归执行行内解析
+3. **行内解析** — 对段落文本，依次尝试各行内插件（加粗、斜体、链接等），生成行内 AST 节点
+4. **AST → HTML** — 遍历完整 AST 文档树，渲染器将各节点类型转换为对应 HTML 标签
+5. **链接 Hook** — 渲染 `link` 节点时，依次调用注册的 `linkHook`，返回空字符串则降级为纯文本
+
+### 基本用法
+
+```ts
+import { MarkdownParser, plugins } from '@core/markdown';
+
+const parser = new MarkdownParser()
+  .use(plugins.boldPlugin)
+  .use(plugins.codePlugin)
+  .use(plugins.linkPlugin);
+
+parser.parse('**bold** and `code`');
+// → '<strong class="md-strong">bold</strong> and <code class="md-code">code</code>'
+```
+
+---
+
+## SimpleMarkdownParser — 简易解析器
+
+适用于标签、描述、表单提示等轻量场景。仅支持行内语法，不处理块级结构。
+
+### 注册的插件（6 个）
+
+| 顺序 | 插件          | 语法          | 输出                         |
+| ---- | ------------- | ------------- | ---------------------------- |
+| 1    | `boldPlugin`  | `**text**`    | `<strong class="md-strong">` |
+| 2    | `codePlugin`  | `` `code` ``  | `<code class="md-code">`     |
+| 3    | `delPlugin`   | `~~text~~`    | `<del class="md-del">`       |
+| 4    | `linkPlugin`  | `[text](url)` | `<a class="md-link">`        |
+| 5    | `emojiPlugin` | `:smile:`     | Unicode Emoji                |
+| 6    | `iconPlugin`  | `:iconName:`  | `<aithe-icon>`               |
+
+### 构造函数
+
+```ts
+new SimpleMarkdownParser();
+```
+
+### 链接处理
+
+使用 `addLinkHook()` 方法注册链接处理 hook。默认行为：外部链接（http/https/ftp/绝对路径）转为纯文本。
+
+```ts
+import { SimpleMarkdownParser } from '@core/markdown';
+
+const parser = new SimpleMarkdownParser();
+parser.addLinkHook((url) => (url.startsWith('/') ? url : ''));
+parser.parse('[internal](/page) [external](https://example.com)');
+// → '<a class="md-link" href="/page">internal</a> external'
+```
+
+### 使用示例
+
+```ts
+import { SimpleMarkdownParser } from '@core/markdown';
+
+const parser = new SimpleMarkdownParser();
+parser.parse('**Bold** ~~strike~~ `code` :smile:');
+// → '<strong class="md-strong">Bold</strong> <del class="md-del">strike</del> <code class="md-code">code</code> 😄'
+```
+
+---
+
+## FullMarkdownParser — 完整解析器
+
+适用于文档渲染、文章展示等富文本场景。支持 GFM（GitHub Flavored Markdown）全语法。
+
+### 注册的插件（16 个）
+
+**Leaf blocks / 叶子块：**
+
+| 顺序 | 插件                  | 语法                    | 输出                                        |
+| ---- | --------------------- | ----------------------- | ------------------------------------------- |
+| 1    | `codeFencePlugin`     | `` ```lang````` / `~~~` | `<aithe-code-editor class="md-code-fence">` |
+| 2    | `setextHeadingPlugin` | `Title\n===`            | `<h1>` / `<h2>`                             |
+| 3    | `headingPlugin`       | `# ` ~ `###### `        | `<h1>` ~ `<h6>`                             |
+| 4    | `thematicBreakPlugin` | `---` / `***` / `___`   | `<hr class="md-hr">`                        |
+| 5    | `tablePlugin`         | `\| col1 \| col2 \|`    | `<table class="md-table">`                  |
+
+**Container blocks / 容器块：**
+
+| 顺序 | 插件               | 语法                 | 输出                                 |
+| ---- | ------------------ | -------------------- | ------------------------------------ |
+| 6    | `blockquotePlugin` | `> text`             | `<blockquote class="md-blockquote">` |
+| 7    | `taskListPlugin`   | `- [ ]` / `- [x]`    | `<li><input type="checkbox">`        |
+| 8    | `listPlugin`       | `- item` / `1. item` | `<li class="md-li">`                 |
+
+**Inlines / 行内：**
+
+| 顺序 | 插件           | 语法                | 输出                         |
+| ---- | -------------- | ------------------- | ---------------------------- |
+| 9    | `imagePlugin`  | `![alt](url)`       | `<img class="md-image">`     |
+| 10   | `linkPlugin`   | `[text](url)`       | `<a class="md-link">`        |
+| 11   | `boldPlugin`   | `**text**`          | `<strong class="md-strong">` |
+| 12   | `italicPlugin` | `*text*` / `_text_` | `<em class="md-em">`         |
+| 13   | `codePlugin`   | `` `code` ``        | `<code class="md-code">`     |
+| 14   | `delPlugin`    | `~~text~~`          | `<del class="md-del">`       |
+| 15   | `emojiPlugin`  | `:smile:`           | Unicode Emoji                |
+| 16   | `iconPlugin`   | `:iconName:`        | `<aithe-icon>`               |
+
+### 构造函数
+
+```ts
+new FullMarkdownParser();
+```
+
+### 链接处理
+
+使用 `addLinkHook()` 方法注册链接处理 hook。默认行为：外部链接（http/https/ftp/绝对路径）转为纯文本。
+
+```ts
+import { FullMarkdownParser } from '@core/markdown';
+
+const parser = new FullMarkdownParser();
+parser.addLinkHook((url) => (url.startsWith('/') ? url : ''));
+parser.parse('[internal](/page) [external](https://example.com)');
+// → '<a class="md-link" href="/page">internal</a> external'
+```
+
+### 使用示例
+
+```ts
+import { FullMarkdownParser } from '@core/markdown';
+
+const parser = new FullMarkdownParser();
+parser.parse(`# Hello\n\n**Bold** and \`code\`.`);
+// → '<h1 class="md-heading">Hello</h1><p class="md-p"><strong class="md-strong">Bold</strong> and <code class="md-code">code</code>.</p>'
+```
+
+---
+
+## 插件系统 / Plugin System
+
+### AstPlugin 接口
+
+```ts
+interface AstPlugin {
+  name: string; // 插件唯一标识
+  block?: BlockParser; // 块级解析器（接收行数组，返回块级节点列表）
+  inline?: InlineParser; // 行内解析器（接收文本，返回行内节点列表）
+}
+
+type BlockParser = (lines: string[]) => { nodes: AstNode[]; consumed: number } | null;
+
+type InlineParser = (text: string) => { nodes: AstNode[]; consumed: number } | null;
+```
+
+- `name` — 插件唯一标识，用于调试和日志
+- `block` — 块级解析器函数，接收从当前位置开始的剩余行数组，返回解析出的 AST 节点列表和消费的行数；返回 `null` 表示不匹配
+- `inline` — 行内解析器函数，接收从当前位置开始的剩余文本，返回解析出的 AST 节点列表和消费的字符数；返回 `null` 表示不匹配
+- 一个插件可同时提供 `block` 和 `inline` 解析器（如 `linkPlugin`）
+
+### MarkdownLinkHook 类型
+
+```ts
+type MarkdownLinkHook = (url: string, text: string) => string | undefined | null;
+```
+
+- 返回 `string` 时，使用该返回值作为最终 URL
+- 返回 `undefined` 或 `null` 时，传递给下一个 hook
+- 所有 hook 均返回 `undefined` 时，使用原始 URL
+- 返回空字符串时，链接被阻止，仅显示文本
+
+### 内置插件列表
+
+| 导出名                | name               | block | 说明                         |
+| --------------------- | ------------------ | ----- | ---------------------------- |
+| `headingPlugin`       | `'heading'`        | ✅    | ATX 标题 `#` ~ `######`      |
+| `setextHeadingPlugin` | `'setext-heading'` | ✅    | Setext 标题 `===` / `---`    |
+| `thematicBreakPlugin` | `'thematic-break'` | ✅    | 分隔线 `---` / `***` / `___` |
+| `codeFencePlugin`     | `'code-fence'`     | ✅    | 围栏代码块 ` ``` ` / `~~~`   |
+| `tablePlugin`         | `'table'`          | ✅    | GFM 表格                     |
+| `blockquotePlugin`    | `'blockquote'`     | ✅    | 引用块 `>`                   |
+| `listPlugin`          | `'list'`           | ✅    | 无序/有序列表                |
+| `taskListPlugin`      | `'task-list'`      | ✅    | 任务列表 `- [ ]` / `- [x]`   |
+| `boldPlugin`          | `'bold'`           | ❌    | 加粗 `**text**`              |
+| `italicPlugin`        | `'italic'`         | ❌    | 斜体 `*text*` / `_text_`     |
+| `codePlugin`          | `'code'`           | ❌    | 行内代码 `` `code` ``        |
+| `delPlugin`           | `'delete'`         | ❌    | 删除线 `~~text~~`            |
+| `linkPlugin`          | `'link'`           | ❌    | 链接 `[text](url)`           |
+| `imagePlugin`         | `'image'`          | ❌    | 图片 `![alt](url)`           |
+| `emojiPlugin`         | `'emoji'`          | ❌    | Emoji 短代码 `:smile:`       |
+| `iconPlugin`          | `'icon'`           | ❌    | Aithe 图标 `:iconName:`      |
+
+### 自定义插件
+
+```ts
+import { MarkdownParser, type AstPlugin } from '@core/markdown';
+
+const highlightPlugin: AstPlugin = {
+  name: 'highlight',
+  inline(text: string) {
+    const match = text.match(/^==(.+?)==/);
+    if (!match) return null;
+    return {
+      nodes: [{ type: 'text', value: match[1] }],
+      consumed: match[0].length,
+    };
+  },
+};
+
+const parser = new MarkdownParser().use(highlightPlugin);
+
+parser.parse('==highlighted==');
+// → 'highlighted'
+```
+
+### 自定义 link hooks
+
+```ts
+import { FullMarkdownParser } from '@core/markdown';
+
+// 只允许内部链接，外部链接转为纯文本
+const parser = new FullMarkdownParser();
+parser.addLinkHook((url) => (url.startsWith('/') ? url : ''));
+
+parser.parse('[internal](/page) [external](https://evil.com)');
+// → '<a class="md-link" href="/page">internal</a> external'
+```
+
+---
+
+## Emoji 支持 / Emoji Support
+
+内置 50+ 常用 Emoji 短代码映射。命名风格参考 GitHub Flavored Markdown 约定。
+
+| 短代码       | 结果 | 短代码      | 结果 | 短代码         | 结果 |
+| ------------ | ---- | ----------- | ---- | -------------- | ---- |
+| `:smile:`    | 😄   | `:wink:`    | 😉   | `:heart_eyes:` | 😍   |
+| `:thumbsup:` | 👍   | `:fire:`    | 🔥   | `:rocket:`     | 🚀   |
+| `:check:`    | ✅   | `:warning:` | ⚠️   | `:heart:`      | ❤️   |
+| `:star:`     | ⭐   | `:bug:`     | 🐛   | `:trophy:`     | 🏆   |
+
+> 完整映射表见 `src/core/markdown/plugins.ts` 的 `EMOJI_MAP` 常量。
+
+### Emoji 与图标插件的区分
+
+| 插件          | 匹配模式             | 示例                | 输出           |
+| ------------- | -------------------- | ------------------- | -------------- |
+| `emojiPlugin` | `:[a-z_][a-z0-9_]*:` | `:smile:` `:check:` | Unicode Emoji  |
+| `iconPlugin`  | `:[a-zA-Z]\w*:`      | `:Home:` `:Search:` | `<aithe-icon>` |
+
+两者互不冲突，emojiPlugin 优先注册，先处理小写短代码。
+
+---
+
+## 代码块渲染 / Code Block Rendering
+
+围栏代码块（` ``` ` / `~~~`）被渲染为 `<aithe-code-editor>` 组件，自带语法高亮、行号、工具栏、主题选择器、复制按钮。
+
+### 语言别名映射
+
+代码块的语言标识支持常用别名，自动映射为标准语言 ID：
+
+| 别名                | 标准 ID             | 别名               | 标准 ID | 别名 | 标准 ID |
+| ------------------- | ------------------- | ------------------ | ------- | ---- | ------- |
+| `ts` → `typescript` | `js` → `javascript` | `py` → `python`    |
+| `rb` → `ruby`       | `sh` → `bash`       | `yml` → `yaml`     |
+| `md` → `markdown`   | `rs` → `rust`       | `kt` → `kotlin`    |
+| `jsx` → `jsx`       | `tsx` → `tsx`       | `m` → `objectivec` |
+| `h` → `c`           | `hpp` → `cpp`       | `tex` → `latex`    |
+
+### 示例
+
+````markdown
+```ts
+const greeting: string = 'Hello';
+```
+````
+
+渲染结果：
+
+```html
+<aithe-code-editor
+  readonly
+  show-toolbar
+  show-theme
+  value="..."
+  language="typescript"
+  class="md-code-fence"
+></aithe-code-editor>
+```
+
+## 安全机制 / Security
+
+### XSS 防护
+
+- 解析过程中的 HTML 转义阶段，将 `& < > "` 转义为实体编码
+- 代码块内容在插件内部额外转义了 `` ` * _ ~ [ ] ( ) ! `` 等 Markdown 语法字符
+- 输出通过 `unsafeHTML` directive 注入 DOM（组件层负责使用 `unsafeHTML`）
+
+### 外部链接防护
+
+默认情况下，所有外部链接（http/https/ftp/绝对路径）被阻止，仅显示链接文本。通过 `linkHooks` 可自定义策略。
+
+### ReDoS 防护
+
+所有内置正则表达式均添加了长度限制（`{0,200}`、`{1,500}` 等），防止恶意构造的长文本导致正则表达式拒绝服务。
+
+---
+
+## 组件层 / Component Layer
+
+### AitheLabel
+
+使用 `SimpleMarkdownParser`，用于标签、描述、表单提示等轻量场景。
+
+```html
+<aithe-label content="**Bold** and `code` :smile:"></aithe-label>
+```
+
+| 属性        | 类型                 | 说明                |
+| ----------- | -------------------- | ------------------- |
+| `content`   | `string`             | Markdown 源文本     |
+| `linkHooks` | `MarkdownLinkHook[]` | 自定义链接处理 hook |
+
+> 完整文档见 [AitheLabel API](api/display/label.md)
+
+### AitheMarkdown
+
+使用 `FullMarkdownParser`，用于文档渲染、文章展示等富文本场景。
+
+```html
+<aithe-markdown content="# Hello\n**Bold** text and `code`."></aithe-markdown>
+```
+
+| 属性        | 类型                 | 默认值 | 说明                |
+| ----------- | -------------------- | ------ | ------------------- |
+| `content`   | `string`             | `''`   | Markdown 源文本     |
+| `linkHooks` | `MarkdownLinkHook[]` | —      | 自定义链接处理 hook |
+
+> 完整文档见 [AitheMarkdown API](api/display/markdown.md)
+
+### AitheMarkdownEditor
+
+基于 `aithe-code-editor` 封装的 Markdown 编辑器，语言固定为 `"markdown"`，集成实时预览。
+
+```html
+<aithe-markdown-editor value="# Hello" show-toolbar></aithe-markdown-editor>
+```
+
+| 属性              | 类型                              | 默认值   | 说明            |
+| ----------------- | --------------------------------- | -------- | --------------- |
+| `value`           | `string`                          | `''`     | Markdown 源文本 |
+| `previewStrategy` | `'auto' \| PreviewStrategyConfig` | `'auto'` | 预览刷新策略    |
+
+#### 预览策略 / Preview Strategy
+
+```ts
+interface PreviewStrategyConfig {
+  changeCount?: number; // 每 N 次变更后刷新
+  updateSeconds?: number; // 每 N 秒最多刷新一次
+}
+```
+
+> 完整文档见 [AitheMarkdownEditor API](api/display/markdown-editor.md)

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 组件库，提供 83 个可复用 UI 组件、22 种内置主题、8 种形状风格、9 种阴影风格、4 种排版风格和完整的国际化支持。
 
 ## 安装
 
 ```bash
-npm install aithe-ui
+npm install @aithe/aithe-ui
 ```
 
 ## 基本使用
@@ -14,12 +14,12 @@ npm install aithe-ui
 
 ```ts
 // 导入整个库（自动注册所有组件 + 初始化主题和 i18n）
-import 'aithe-ui';
+import '@aithe/aithe-ui';
 ```
 
-仅此一行即可使用所有组件——`import 'aithe-ui'` 会自动完成：
+仅此一行即可使用所有组件——`import '@aithe/aithe-ui'` 会自动完成：
 
-- 注册全部 79 个 Custom Elements
+- 注册全部 83 个 Custom Elements
 - 注入 22 种主题的 CSS 变量
 - 初始化 i18n（默认 `en-US`）
 
@@ -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) — 22 种内置主题、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) — 全部 83 个组件的详细 API 文档