@aithe/aithe-ui 26.2.2 → 26.3.1

package/docs/guide.md

@@ -66,8 +66,12 @@ element.addEventListener('aithe-change', (e) => {
 | `aithe-confirm`       | 确认操作时     | —                               |
 | `aithe-cancel`        | 取消操作时     | —                               |
 | `aithe-open-change`   | 展开/收起时    | `{ open: boolean }`             |
+| `aithe-dropdown-change` | 下拉开关状态变更时 | `{ open: boolean }`        |
 | `aithe-clear`         | 清除时         | —                               |
 | `aithe-theme-change`  | 主题变更时     | `{ theme: string }`             |
+| `aithe-shape-change`  | 形状风格变更时 | `{ shape: string }`             |
+| `aithe-shadow-change` | 阴影风格变更时 | `{ shadow: string }`            |
+| `aithe-typo-change`   | 排版风格变更时 | `{ typo: string }`              |
 | `aithe-locale-change` | 语言变更时     | `{ locale: AitheLocale }`       |
 
 ### 在 Lit 中监听
@@ -181,6 +185,195 @@ select.addEventListener('aithe-change', (e) => {
 
 ---
 
+## 语法高亮（Syntax Highlighting）
+
+Aithe UI 内置自研语法高亮引擎 `SyntaxRegistry`，无需第三方依赖，支持多语言注册和自定义规则扩展。
+
+### 内置语言
+
+引擎内置 37 种语言支持：JavaScript、TypeScript、C、C++、Java、HTML、XML、JSON、JSON Lines、YAML、Markdown、Python、Ruby、Bash、CSS、SQL、Rust、Go、Kotlin、Swift、JSX、TSX、Vue、Svelte、WebAssembly、Dockerfile、Makefile、CMake、LaTeX、F#、PowerShell、Perl、Lua、Scala、Dart、R、Objective-C。
+
+### 基本用法
+
+```typescript
+import { SyntaxRegistry } from '@aithe/aithe-ui';
+
+const code = `function greet(name) {\n  return "Hello, " + name;\n}`;
+
+// 按语言高亮
+const html = SyntaxRegistry.highlightByLanguage(code, 'javascript');
+```
+
+### 注册自定义语言
+
+```typescript
+import { SyntaxRegistry } from '@aithe/aithe-ui';
+
+SyntaxRegistry.register({
+  langId: 'python',
+  name: 'Python',
+  rules: [
+    { pattern: /(#.*$)/gm, className: 'hl-comment', order: 1 },
+    {
+      pattern: /\b(def|class|return|if|elif|else|for|while)\b/g,
+      className: 'hl-keyword',
+      order: 2,
+    },
+    { pattern: /\b(\d+\.?\d*)\b/g, className: 'hl-number', order: 3 },
+    { pattern: /("(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*')/g, className: 'hl-string', order: 4 },
+  ],
+});
+```
+
+### 颜色定制
+
+通过 CSS 变量覆盖高亮颜色：
+
+```css
+:root {
+  --aithe-code-keyword: #c678dd;
+  --aithe-code-string: #98c379;
+  --aithe-code-comment: #5c6370;
+}
+```
+
+> 完整文档见 [语法高亮引擎](highlight.md)。
+
+---
+
+## Markdown 渲染 / Markdown Rendering
+
+Aithe UI 内置零依赖的 Markdown 解析与渲染引擎，采用插件架构，提供从轻量标签到完整文档渲染的全链路支持。
+
+### 渲染组件对比
+
+| 组件                      | 解析器                 | 适用场景                 | 支持语法                                               |
+| ------------------------- | ---------------------- | ------------------------ | ------------------------------------------------------ |
+| `<aithe-label>`           | `SimpleMarkdownParser` | 标签、描述、表单提示     | 加粗、删除线、行内代码、内部链接、Emoji、图标          |
+| `<aithe-markdown>`        | `FullMarkdownParser`   | 文档渲染、文章展示       | 完整 GFM（标题、代码块、表格、引用、列表、任务列表等） |
+| `<aithe-markdown-editor>` | `FullMarkdownParser`   | Markdown 编辑 + 实时预览 | 同 `aithe-markdown`，含编辑器与可配置预览策略          |
+
+### AitheLabel — 轻量标签渲染
+
+```html
+<aithe-label content="**Bold** and `code` :check: 已完成"></aithe-label>
+<aithe-label content="[内部链接](/page)" size="sm"></aithe-label>
+```
+
+### AitheMarkdown — 完整文档渲染
+
+```html
+<aithe-markdown content="# 标题\n\n- 列表项\n- [x] 已完成任务"></aithe-markdown>
+```
+
+### AitheMarkdownEditor — Markdown 编辑与预览
+
+```html
+<aithe-markdown-editor
+  value="# Hello"
+  show-toolbar
+  preview-strategy='{"updateSeconds":1}'
+></aithe-markdown-editor>
+```
+
+### 链接安全机制
+
+所有渲染组件默认阻止外部链接（http/https/ftp/绝对路径），防止导航到站外。通过 `linkHooks` 属性可自定义策略：
+
+```javascript
+const md = document.querySelector('aithe-markdown');
+md.linkHooks = [(url) => (url.startsWith('https://internal.example.com') ? url : '')];
+```
+
+### 代码块渲染
+
+Markdown 中的围栏代码块被渲染为功能完整的 `<aithe-code-editor>` 组件，自带语法高亮、行号、工具栏、主题选择和复制功能：
+
+````markdown
+```ts
+const msg: string = 'Hello';
+```
+````
+
+````
+
+### 使用底层解析器
+
+```ts
+import { SimpleMarkdownParser, FullMarkdownParser, plugins } from '@aithe/aithe-ui';
+
+// 简易解析器（行内子集）
+const simple = new SimpleMarkdownParser();
+simple.parse('**bold** `code`'); // '<strong>bold</strong> <code>code</code>'
+
+// 完整解析器（GFM）
+const full = new FullMarkdownParser();
+full.parse('# Title\n\n> Quote'); // '<h1>Title</h1><blockquote>Quote</blockquote>'
+
+// 使用单个插件
+const parser = new MarkdownParser().use(plugins.boldPlugin);
+parser.parse('**bold**'); // '<strong>bold</strong>'
+
+// 自定义 link hooks
+const parser = new FullMarkdownParser();
+parser.addLinkHook((url) => url.startsWith('/') ? url : '');
+````
+
+> 完整文档见 [Markdown 模块](markdown.md)。
+
+---
+
+## 代码编辑器（Code Editor）
+
+`<aithe-code-editor>` 是一个基于 Lit + TypeScript 的代码编辑器 Web Component，内置语法高亮，无需第三方依赖。
+
+### 基本用法
+
+```html
+<aithe-code-editor language="javascript"></aithe-code-editor>
+```
+
+### 带工具栏
+
+```html
+<aithe-code-editor language="typescript" show-toolbar></aithe-code-editor>
+```
+
+### 只读展示
+
+```html
+<aithe-code-editor language="json" readonly value='{"key": "value"}'></aithe-code-editor>
+```
+
+### 属性
+
+| 属性           | 类型      | 默认值       | 说明               |
+| -------------- | --------- | ------------ | ------------------ |
+| `value`        | `string`  | `''`         | 编辑器内容         |
+| `language`     | `string`  | `javascript` | 语法高亮语言       |
+| `readonly`     | `boolean` | `false`      | 是否只读           |
+| `line-numbers` | `boolean` | `true`       | 是否显示行号       |
+| `placeholder`  | `string`  | `''`         | 空状态占位符       |
+| `show-toolbar` | `boolean` | `false`      | 是否显示工具栏     |
+| `show-theme`   | `boolean` | `true`       | 是否显示主题选择器 |
+| `show-preview` | `boolean` | `false`      | 是否显示预览面板   |
+
+### 事件
+
+| 事件名                      | 说明               |
+| --------------------------- | ------------------ |
+| `aithe-input`               | 内容变化时触发     |
+| `aithe-language-change`     | 切换语言时触发     |
+| `aithe-line-numbers-change` | 行号显示切换时触发 |
+| `aithe-fullscreen-change`   | 全屏模式切换时触发 |
+| `aithe-copy`                | 复制代码后触发     |
+| `aithe-theme-change`        | 主题变更时触发     |
+| `aithe-preview-toggle`      | 预览面板切换时触发 |
+
+> 完整组件文档见 [code-editor.md](api/display/code-editor.md)。
+
+---
+
 ## 数据驱动组件
 
 部分组件支持通过属性传入数据，而非 DOM 子元素：
@@ -189,7 +382,7 @@ select.addEventListener('aithe-change', (e) => {
 | ---------------- | ------------ | ---------------- | ------------------- |
 | `aithe-select`   | `options`    | `optionsJson`    | `AitheSelectOption` |
 | `aithe-combobox` | `options`    | `optionsJson`    | `ComboboxOption`    |
-| `aithe-dropdown` | `items`      | `itemsJson`      | `AitheDropdownItem` |
+| `aithe-dropdown` | `items`      | `itemsJson`      | `AitheTreeNodeMeta` |
 | `aithe-table`    | `data`       | `dataJson`       | —                   |
 | `aithe-tree`     | `data`       | `dataJson`       | `AitheTreeNodeMeta` |
 | `aithe-transfer` | `dataSource` | `dataSourceJson` | `TransferItem`      |
@@ -198,7 +391,7 @@ select.addEventListener('aithe-change', (e) => {
 
 ### 数据项通用字段
 
-所有数据驱动组件的标识字段统一为 `id`，意图字段统一为 `intent`：
+所有数据驱动组件的标识字段统一为 `id`，变体字段统一为 `intent`：
 
 ```ts
 interface AitheSelectOption {
@@ -207,7 +400,7 @@ interface AitheSelectOption {
   disabled?: boolean;
   description?: string;
   icon?: string;
-  intent?: AitheIntent;
+  intent?: AitheVariant;
 }
 ```
 
@@ -274,6 +467,574 @@ aithe-button {
 
 ---
 
+## 形状风格（Shape Style）
+
+Aithe UI 提供全局形状风格管理，控制所有组件的圆角视觉风格。形状风格与颜色主题正交——任意主题可与任意形状风格自由组合。
+
+### 内置形状风格
+
+| 形状名    | 说明             | 控件圆角特征                       | 容器圆角特征               |
+| --------- | ---------------- | ---------------------------------- | -------------------------- |
+| `sharp`   | 直角             | 0px                                | 0px                        |
+| `smooth`  | 微圆角           | 2–8px                              | 2–8px                      |
+| `rounded` | 标准圆角（默认） | 6–20px                             | 6–20px                     |
+| `rounder` | 大圆角           | 10–28px                            | 10–28px                    |
+| `pill`    | 胶囊             | 999px（控件全圆）                  | 10–28px（容器保守值）      |
+| `circle`  | 圆形             | 50%（控件圆形）                    | 10–28px（容器保守值）      |
+| `chamfer` | 斜切角           | 不对称 px 值（如 0px 8px 0px 8px） | 同控件值                   |
+| `organic` | 有机曲线         | 不对称百分比（30%–70%）            | 不对称 px 值（温和有机感） |
+
+> **关键约束**：`pill`、`circle`、`organic` 三种极端形状仅对**控件类组件**（button、input、tag 等）生效；**容器类组件**（card、dialog、table、dashboard-panel 等）使用保守值，避免布局变形。
+
+### 切换形状风格
+
+```ts
+import { aitheUI } from '@aithe/aithe-ui';
+
+// 切换到胶囊形状（自动持久化到 localStorage）
+aitheUI.setShape('pill');
+
+// 切换但不持久化
+aitheUI.setShape('pill', false);
+
+// 获取当前形状风格
+const shape = aitheUI.getShape(); // 'pill'
+```
+
+### 订阅形状风格变更
+
+```ts
+import { aitheUI } from '@aithe/aithe-ui';
+
+const unsubscribe = aitheUI.onShapeChange(() => {
+  console.log('Shape changed to:', aitheUI.getShape());
+});
+
+// 取消订阅
+unsubscribe();
+```
+
+### 使用形状选择器组件
+
+```html
+<aithe-shape-picker></aithe-shape-picker>
+```
+
+### 使用主题预览组件
+
+`aithe-theme-preview` 同时包含主题选择器和形状选择器，预览区局部生效，点击"应用主题"按钮将主题和形状同时应用到全局：
+
+```html
+<aithe-theme-preview></aithe-theme-preview>
+```
+
+### 双轨圆角 Token 体系
+
+形状风格通过两套独立的 CSS 变量控制圆角：
+
+| Token 系列                   | 作用域     | 包含级别                       |
+| ---------------------------- | ---------- | ------------------------------ |
+| `--aithe-radius-*`           | 控件类组件 | `sm`、`md`、`lg`、`xl`、`full` |
+| `--aithe-container-radius-*` | 容器类组件 | `sm`、`md`、`lg`、`xl`、`full` |
+
+### 设置形状风格
+
+```ts
+import { aitheUI } from '@aithe/aithe-ui';
+
+aitheUI.setShape('rounded');
+```
+
+### CSS 变量
+
+形状风格通过 CSS 变量设置在 `:root` 的 inline style 上，可在 CSS 中据此调整样式：
+
+```css
+/* 手动覆盖圆角变量 */
+:root {
+  --aithe-radius-md: 12px;
+  --aithe-container-radius-lg: 16px;
+}
+```
+
+---
+
+## 布局密度（Layout Density）
+
+Aithe UI 提供全局布局密度管理，影响组件间距、尺寸等视觉密度参数。
+
+### 内置布局密度
+
+| 密度名    | 说明         |
+| --------- | ------------ |
+| `compact` | 紧凑布局     |
+| `medium`  | 默认中等布局 |
+| `wide`    | 宽松布局     |
+
+### 切换布局密度
+
+```ts
+import { aitheUI } from '@aithe/aithe-ui';
+
+// 切换到紧凑布局（自动持久化到 localStorage）
+aitheUI.setLayout('compact');
+
+// 获取当前布局密度
+const layout = aitheUI.getLayout(); // 'compact'
+```
+
+### 订阅布局密度变更
+
+```ts
+import { aitheUI } from '@aithe/aithe-ui';
+
+const unsubscribe = aitheUI.onLayoutChange(() => {
+  console.log('Layout changed to:', aitheUI.getLayout());
+});
+
+// 取消订阅
+unsubscribe();
+```
+
+### 初始化布局密度
+
+```ts
+import { aitheUI } from '@aithe/aithe-ui';
+
+aitheUI.setLayout('compact');
+```
+
+### CSS 变量
+
+布局密度通过 `data-aithe-layout` 属性设置在 `<html>` 上，可在 CSS 中据此调整样式：
+
+```css
+html[data-aithe-layout='compact'] {
+  --aithe-space-3: 6px;
+  --aithe-space-4: 8px;
+}
+
+html[data-aithe-layout='wide'] {
+  --aithe-space-3: 14px;
+  --aithe-space-4: 20px;
+}
+```
+
+---
+
+## 排版风格（Typography）
+
+Aithe UI 提供全局排版风格管理，控制字号层级、字重、行高、字间距、段落间距等排版参数。排版风格与颜色主题、形状风格、阴影风格正交——任意主题可与任意排版风格自由组合。
+
+排版体系作为四大核心风格维度之一（色彩、形状、阴影、排版），统一管控字号层级、字重、行高、字间距、段落间距、标题间距等排版参数。所有组件文字尺寸、文本间距、布局留白均严格遵循排版规范变量，禁止硬编码固定数值。全局 `:root` 定义通用排版风格变量，组件 `:host` 继承并局部适配。
+
+### 内置排版风格（4 种）
+
+| 排版名     | 说明         | 视觉特征                                                                    |
+| ---------- | ------------ | --------------------------------------------------------------------------- |
+| `minimal`  | 极简         | 3 级以内层级，宽松间距，高行高，呼吸感与秩序感，禁止密集排布                |
+| `business` | 商务（默认） | 完整清晰层级，标题层级差明确，列表数据严格对齐，规整分段，适合高效扫读      |
+| `luxury`   | 轻奢         | 宽松字间距与行高，段落留白充裕，字重对比营造节奏，轻盈有序，精致阅读感      |
+| `compact`  | 紧凑信息流   | 高信息密度，字号行高间距偏小，摘要限制 1–3 行截断，最小化间距，高屏幕承载量 |
+
+#### 极简风格（minimal）
+
+文字层级控制在 3 级以内，标题与正文间距宽松，段落间距显著大于行间距，文本严格基线对齐，禁止密集排布；正文行高舒适，超长文本按需截断，同一区域文本数量克制，整体排版追求呼吸感与秩序感，无多余文字层级。
+
+#### 商务风格（business）
+
+文字层级完整清晰，标题层级差明确，正文字号与行高统一规范；列表、数据类内容严格对齐，关键信息突出排版，辅助文本弱化处理；段落结构规整，分段逻辑清晰，支持多行文本自适应，保证长时间高效扫读与信息核对。
+
+#### 轻奢风格（luxury）
+
+标题字间距与行高偏宽松，正文字号适中、行高舒展；信息点间距充足，排版对称均衡，段落留白充裕；以短句为主，避免大段密集文本，通过字重对比营造节奏，整体轻盈有序，强调精致阅读感。
+
+#### 紧凑信息流（compact）
+
+高信息密度，字号、行高、间距统一偏小；标题优先单行展示，正文摘要限制 1–3 行并自动截断；模块内外间距最小化，文本统一左对齐与基线对齐；辅助信息紧凑排布，图片与文字间距极窄，所有条目排版结构高度一致，提升一屏承载量。
+
+### 切换排版风格
+
+```ts
+import { aitheUI } from '@aithe/aithe-ui';
+
+// 切换到极简排版（自动持久化到 localStorage）
+aitheUI.setTypo('minimal');
+
+// 切换但不持久化
+aitheUI.setTypo('minimal', false);
+
+// 获取当前排版风格
+const typo = aitheUI.getTypo(); // 'minimal'
+```
+
+### 订阅排版风格变更
+
+```ts
+import { aitheUI } from '@aithe/aithe-ui';
+
+const unsubscribe = aitheUI.onTypoChange(() => {
+  console.log('Typo changed to:', aitheUI.getTypo());
+});
+
+// 取消订阅
+unsubscribe();
+```
+
+### 使用排版选择器组件
+
+```html
+<aithe-typo-picker></aithe-typo-picker>
+```
+
+### 使用主题预览组件
+
+`aithe-theme-preview` 同时包含主题选择器、形状选择器、阴影选择器和排版选择器，预览区局部生效，点击"应用主题"按钮将主题、形状、阴影和排版同时应用到全局：
+
+```html
+<aithe-theme-preview></aithe-theme-preview>
+```
+
+### 排版 Token 体系
+
+排版风格通过覆盖以下组件已使用的 CSS 变量实现切换：
+
+| Token 系列                              | 说明           |
+| --------------------------------------- | -------------- |
+| `--aithe-font-size-xs`                  | 超小字号       |
+| `--aithe-font-size-sm`                  | 小字号         |
+| `--aithe-font-size-md`                  | 中字号（默认） |
+| `--aithe-font-size-lg`                  | 大字号         |
+| `--aithe-font-size-xl`                  | 特大字号       |
+| `--aithe-font-size-2xl`                 | 超大字号       |
+| `--aithe-font-weight-regular`           | 常规字重       |
+| `--aithe-font-weight-medium`            | 中等字重       |
+| `--aithe-font-weight-semibold`          | 半粗字重       |
+| `--aithe-font-weight-bold`              | 粗体字重       |
+| `--aithe-line-height-tight`             | 紧凑行高       |
+| `--aithe-line-height-base`              | 基础行高       |
+| `--aithe-line-height-loose`             | 宽松行高       |
+| `--aithe-space-1` ~ `--aithe-space-10`  | 数字刻度间距   |
+| `--aithe-space-xs` ~ `--aithe-space-xl` | 语义间距别名   |
+| `--aithe-control-height-sm`             | 小控件高度     |
+| `--aithe-control-height-md`             | 中控件高度     |
+| `--aithe-control-height-lg`             | 大控件高度     |
+
+### 各风格 Token 值对比
+
+#### 字号
+
+| Token                   | minimal | business | luxury | compact |
+| ----------------------- | ------- | -------- | ------ | ------- |
+| `--aithe-font-size-xs`  | 12px    | 12px     | 11px   | 11px    |
+| `--aithe-font-size-sm`  | 14px    | 13px     | 13px   | 12px    |
+| `--aithe-font-size-md`  | 15px    | 14px     | 15px   | 13px    |
+| `--aithe-font-size-lg`  | 18px    | 16px     | 18px   | 14px    |
+| `--aithe-font-size-xl`  | 22px    | 20px     | 24px   | 16px    |
+| `--aithe-font-size-2xl` | 32px    | 28px     | 36px   | 20px    |
+
+#### 字重
+
+| Token                          | minimal | business | luxury | compact |
+| ------------------------------ | ------- | -------- | ------ | ------- |
+| `--aithe-font-weight-regular`  | 400     | 400      | 400    | 400     |
+| `--aithe-font-weight-medium`   | 500     | 500      | 500    | 500     |
+| `--aithe-font-weight-semibold` | 600     | 600      | 500    | 600     |
+| `--aithe-font-weight-bold`     | 700     | 700      | 600    | 700     |
+
+#### 行高
+
+| Token                       | minimal | business | luxury | compact |
+| --------------------------- | ------- | -------- | ------ | ------- |
+| `--aithe-line-height-tight` | 1.25    | 1.25     | 1.3    | 1.15    |
+| `--aithe-line-height-base`  | 1.7     | 1.5      | 1.7    | 1.35    |
+| `--aithe-line-height-loose` | 1.9     | 1.7      | 1.9    | 1.5     |
+
+#### 间距（数字刻度）
+
+| Token              | minimal | business | luxury | compact |
+| ------------------ | ------- | -------- | ------ | ------- |
+| `--aithe-space-1`  | 4px     | 4px      | 4px    | 2px     |
+| `--aithe-space-2`  | 8px     | 8px      | 8px    | 4px     |
+| `--aithe-space-3`  | 14px    | 12px     | 14px   | 8px     |
+| `--aithe-space-4`  | 18px    | 16px     | 20px   | 12px    |
+| `--aithe-space-5`  | 22px    | 20px     | 24px   | 16px    |
+| `--aithe-space-6`  | 28px    | 24px     | 30px   | 20px    |
+| `--aithe-space-7`  | 36px    | 32px     | 38px   | 24px    |
+| `--aithe-space-8`  | 44px    | 40px     | 48px   | 32px    |
+| `--aithe-space-9`  | 52px    | 48px     | 56px   | 40px    |
+| `--aithe-space-10` | 68px    | 64px     | 72px   | 48px    |
+
+#### 控件高度
+
+| Token                       | minimal | business | luxury | compact |
+| --------------------------- | ------- | -------- | ------ | ------- |
+| `--aithe-control-height-sm` | 32px    | 32px     | 34px   | 28px    |
+| `--aithe-control-height-md` | 40px    | 40px     | 42px   | 36px    |
+| `--aithe-control-height-lg` | 48px    | 48px     | 50px   | 44px    |
+
+### CSS 变量
+
+排版风格通过 CSS 变量设置在 `:root` 的 inline style 上，可在 CSS 中据此调整样式：
+
+```css
+/* 手动覆盖排版变量 */
+:root {
+  --aithe-font-size-md: 16px;
+  --aithe-line-height-base: 1.8;
+}
+```
+
+---
+
+## 路由（Router）
+
+Aithe UI 提供轻量、零依赖的前端路由模块，适配 Lit 组件模型与响应式更新机制。
+
+### 基本用法
+
+```ts
+import { Router } from '@aithe/aithe-ui';
+
+const router = new Router({
+  mode: 'history',
+  routes: [
+    { path: '/', component: 'home-page' },
+    { path: '/about', component: 'about-page' },
+    { path: '/user/:id', component: 'user-page' },
+    { path: '*', component: 'not-found-page' },
+  ],
+});
+router.start();
+```
+
+### 路由模式
+
+| 模式      | 说明                                         |
+| --------- | -------------------------------------------- |
+| `history` | 使用 HTML5 History API（默认，需服务端配置） |
+| `hash`    | 使用 URL hash（`#/path`），无需服务端配置    |
+
+```ts
+// hash 模式
+const router = new Router({ mode: 'hash', routes: [...] });
+```
+
+### 路由容器 `<aithe-page>`
+
+`<aithe-page>` 连接到 `Router` 实例，监听路由变更并动态渲染匹配的组件：
+
+```html
+<aithe-page .router="${router}"></aithe-page>
+```
+
+设置 404 回退组件：
+
+```html
+<aithe-page .router="${router}" not-found-component="not-found-page"></aithe-page>
+```
+
+### 页面组件中访问路由参数
+
+路由匹配时，`<aithe-page>` 会将路由信息作为属性传递给渲染的组件：
+
+```ts
+import { LitElement, html } from 'lit';
+import { customElement, property } from 'lit/decorators.js';
+
+@customElement('user-page')
+export class UserPage extends LitElement {
+  @property({ type: Object }) params: Record<string, string> = {};
+  @property({ type: Object }) query: Record<string, string> = {};
+
+  render() {
+    return html`
+      <p>User ID: ${this.params.id}</p>
+    `;
+  }
+}
+```
+
+| 传递属性    | 类型                     | 说明               |
+| ----------- | ------------------------ | ------------------ |
+| `.params`   | `Record<string, string>` | 路径参数           |
+| `.query`    | `Record<string, string>` | 查询参数           |
+| `.route`    | `RouteConfig \| null`    | 匹配的路由配置     |
+| `.location` | `RouteLocation`          | 完整的路由位置对象 |
+
+### 编程式导航
+
+```ts
+// 导航到新页面
+await router.navigate('/user/42');
+
+// 替换当前历史记录
+await router.replace('/login');
+
+// 前进/后退
+router.back();
+router.forward();
+```
+
+### 路由守卫
+
+```ts
+// 添加路由守卫（返回 false 阻止导航）
+const removeGuard = router.addGuard((to, from) => {
+  if (to.path.startsWith('/admin') && !isLoggedIn()) {
+    return false;
+  }
+  return true;
+});
+
+// 移除守卫
+removeGuard();
+```
+
+### 订阅路由变更
+
+```ts
+const unsubscribe = router.onChange((location) => {
+  console.log('Route changed:', location.path, location.params);
+});
+
+// 取消订阅
+unsubscribe();
+```
+
+### 动态路由与通配符
+
+```ts
+const routes = [
+  // 静态路由
+  { path: '/home', component: 'home-page' },
+
+  // 动态路由（:id 为路径参数）
+  { path: '/user/:id', component: 'user-page' },
+
+  // 通配符（匹配所有未命中的路径）
+  { path: '*', component: 'not-found-page' },
+];
+```
+
+### 路由元数据
+
+```ts
+const routes = [
+  {
+    path: '/dashboard',
+    component: 'dashboard-page',
+    meta: { title: 'Dashboard', requiresAuth: true },
+  },
+];
+
+// 在守卫或组件中访问
+router.addGuard((to) => {
+  if (to.route?.meta?.requiresAuth && !isLoggedIn()) {
+    router.navigate('/login');
+    return false;
+  }
+  return true;
+});
+```
+
+---
+
+## DataHub 数据中间层
+
+Aithe UI 内置 DataHub 数据中间层，提供统一的请求调度、缓存、去重、幂等防护、Mock 支持和 Loading 状态管理。
+
+### 基本用法
+
+```ts
+import dataHub from '@aithe/aithe-ui';
+
+// 查询请求（自动缓存+去重）
+const res = await dataHub.request('/order/query', { orderId: '123' });
+console.log(res.data);
+
+// 提交请求（自动幂等防护）
+const res = await dataHub.request('/order/submit', { items: [] });
+
+// Mock 模式
+const res = await dataHub.request(
+  '/order/query',
+  {},
+  {
+    mock: true,
+    mockData: { list: [], total: 0 },
+  },
+);
+```
+
+### 策略自动识别
+
+DataHub 根据 URL 最后一个路径段自动识别请求策略：
+
+| 策略     | 识别关键字             | 缓存 | 去重 | 幂等防护 |
+| -------- | ---------------------- | ---- | ---- | -------- |
+| `query`  | `query`、`list`、`get` | ✅   | ✅   | ❌       |
+| `submit` | 其他                   | ❌   | ❌   | ✅       |
+
+### 拦截器
+
+```ts
+// 请求拦截器（注入 Token）
+dataHub.setRequestInterceptor((req) => {
+  const token = getToken();
+  if (token) {
+    req.options.headers = { ...req.options.headers, Authorization: `Bearer ${token}` };
+  }
+  return req;
+});
+
+// 响应拦截器
+dataHub.setResponseInterceptor((res, req) => {
+  return res;
+});
+
+// 全局错误处理
+dataHub.setErrorHandler((error, req) => {
+  console.error(`[DataHub] ${error.code}: ${error.message}`);
+  if (error.status === 401) {
+    redirectToLogin();
+  }
+});
+```
+
+### APIStyle 业务协议解析
+
+DataHub 支持通过 APIStyle 机制自动处理请求体包装和响应解包：
+
+```ts
+import dataHub from '@aithe/aithe-ui';
+
+// 启用 default 风格：请求体自动包装为 { data: ... }
+// 响应自动解包，code !== 'Ok' 时自动抛出 DataHubError
+dataHub.setAPIStyle('default');
+
+const data = await dataHub.request('/order/query', { orderId: '123' });
+console.log(data); // 直接获取业务数据，无需 .data
+```
+
+内置 `default`（标准 `{ code, message, data }` 协议）和 `k8s`（Kubernetes 状态协议）两种风格，也支持自定义实现 `DataHubAPIStyle` 接口。
+
+### Loading 状态
+
+```ts
+// 订阅全局 Loading 变更
+const unsubscribe = dataHub.onLoadingChange((loading) => {
+  console.log('Loading:', loading);
+});
+
+// 查询指定 URL 是否加载中
+dataHub.isLoading('/order/query');
+```
+
+> 完整的 DataHub 文档见 [DataHub 数据中间层](datahub.md)。
+
+---
+
 ## 无障碍（Accessibility）
 
 所有组件内置 ARIA 语义和键盘导航支持：
@@ -298,7 +1059,7 @@ aithe-button {
 Aithe UI 使用 TypeScript 编写，提供完整的类型定义：
 
 ```ts
-import type { AitheButton, AitheSelectOption, AitheLocale } from 'aithe-ui';
+import type { AitheButton, AitheSelectOption, AitheLocale } from '@aithe/aithe-ui';
 
 // 组件属性类型
 const options: AitheSelectOption[] = [
@@ -307,7 +1068,7 @@ const options: AitheSelectOption[] = [
 ];
 
 // 主题类型
-import type { AitheBuiltinTheme, AitheThemeName } from 'aithe-ui';
+import type { AitheBuiltinTheme, AitheThemeName } from '@aithe/aithe-ui';
 const theme: AitheBuiltinTheme = 'dark';
 
 // i18n 类型
@@ -318,9 +1079,76 @@ const locale: AitheLocale = 'zh-CN';
 
 ---
 
+## Filter 数据格式化
+
+Aithe UI 内置轻量 Filter 数据格式化框架，支持声明式过滤器表达式，零第三方依赖。
+
+### 基本用法
+
+```ts
+import { filterFactory } from '@aithe/aithe-ui';
+
+// 单个过滤器
+filterFactory.format(123.456, 'amount');        // "123.46"
+
+// 带参数的过滤器
+filterFactory.format('2024-01-15', 'date yyyy/MM/dd');  // "2024/01/15"
+
+// 链式过滤
+filterFactory.format(null, 'date yyyy/MM/dd | empty');  // "--"
+```
+
+### 内置过滤器
+
+| 注册名 | 说明 | 示例 |
+|--------|------|------|
+| `amount` | 金额保留两位小数 | `123.4` → `123.40` |
+| `date` | 日期格式化 | `'2024-01-15'` → `2024/01/15` |
+| `empty` | 空值替换为 `--` | `null` → `--` |
+| `bytes` | 字节数格式化 | `1024` → `1.00 KiB` |
+| `timeAgo` | 时间友好显示 | `5 minutes ago` |
+
+### 在组件中使用
+
+```html
+<!-- metrics 使用 filter -->
+<aithe-metrics label="Revenue" value="1234.5" filter="amount"></aithe-metrics>
+
+<!-- table-column 使用 filter -->
+<aithe-table .data=${records}>
+  <aithe-table-column id="price" title="Price" filter="amount"></aithe-table-column>
+  <aithe-table-column id="createdAt" title="Created" filter="date yyyy/MM/dd"></aithe-table-column>
+</aithe-table>
+```
+
+### 自定义过滤器
+
+```ts
+import type { Filter } from '@aithe/aithe-ui';
+import { filterFactory } from '@aithe/aithe-ui';
+
+class PhoneFilter implements Filter<string, string> {
+  apply(value: string): string {
+    if (value == null || value.length !== 11) return value;
+    return `${value.slice(0, 3)}****${value.slice(7)}`;
+  }
+}
+
+filterFactory.register('phone', PhoneFilter);
+filterFactory.format('13812345678', 'phone');  // "138****5678"
+```
+
+> 完整文档见 [Filter 数据格式化](filter.md)。
+
+---
+
 ## 下一步
 
-- [主题系统](theming.md) — 22 种内置主题、自定义主题
+- [主题系统](theming.md) — 25 种内置主题、8 种形状风格、9 种阴影风格、4 种排版风格、自定义主题
 - [国际化](i18n.md) — 多语言支持、自定义翻译
+- [DataHub 数据中间层](datahub.md) — 请求调度、缓存、去重、Mock
+- [语法高亮引擎](highlight.md) — 自研语法高亮引擎，多语言注册与自定义规则
+- [Markdown 模块](markdown.md) — 零依赖 Markdown 解析与渲染引擎
+- [Filter 数据格式化](filter.md) — 声明式过滤器表达式，零依赖数据格式化
 - [框架集成](framework-integration.md) — React / Vue / Angular / Svelte
-- [API 参考](api/summary.md) — 全部组件详细 API
+- [API 参考](api/summary.md) — 全部 100 个组件详细 API