@aithe/aithe-ui 26.2.3 → 26.3.2

package/docs/changelog/VERSION_26.3.2.md

@@ -0,0 +1,852 @@
+# Aithe UI 26.3.2 版本详细说明
+
+## 版本信息
+
+- **版本号**: 26.3.2
+- **发布日期**: 2026-09-11
+- **最新子版本**: 26.3.2.4
+- **版本类型**: 功能版本
+- **版本描述**: 2026年第3季度第2个月版本 — 只读视图组件、选项分组、DataHub force 选项与文档质量提升
+
+## 版本变更记录
+
+### Issue 26.3.2.4 — Quality / Bug Fix (2026-09-11)
+
+1. **`listPlugin` 列表解析器新增嵌套子列表与缩进续行支持** — 原 `listPlugin.block` 仅能解析扁平单行列表项，无法识别缩进子列表和跨行续行。重写解析逻辑：以首行确定列表类型与 `baseIndent`，逐项收集同级列表项并归集其后续缩进行，通过递归调用 `listPlugin.block` 生成嵌套 `list` AST 节点；空行后通过前瞻判断是否仍属当前列表项的缩进续行
+2. **`listPlugin.block` 认知复杂度治理** — 原实现认知复杂度 52（超过 sonarjs 上限 15），通过抽取 `collectItemSubLines`、`buildListItemChildren`、`blankLineBelongsToItem`、`lineEndsItem`、`parseSubLines` 五个独立函数分层拆解，主循环复杂度降至阈值以内，修复 ESLint `sonarjs/cognitive-complexity` 错误
+3. **`parseSubLines` 剩余行递归处理修正** — 原实现将嵌套列表解析后的 `remaining` 行直接 `join` 拍平为单一段落，导致更深一层的嵌套列表被错误扁平化；改为递归调用 `parseSubLines(remaining, parentIndent)` 正确处理多层嵌套
+4. **清理死代码与非空断言** — 删除被 `parseListItemIndented` 完全替代且无任何引用的 `parseListItem` 函数；`listPlugin.block` 内大量 `line!` 非空断言改为 `undefined` 显式判断与类型收窄
+
+### Issue 26.3.2.3 — Feature (2026-09-08)
+
+1. **`<aithe-select>` / `<aithe-combobox>` 新增选项分组能力** — 选项对象新增 `group` 字段，渲染时若任一选项携带 `group` 则自动按分组聚合输出，每组前置 `.group-header` 标题并缩进组内选项；无 `group` 字段时保持原扁平渲染，向后兼容。两个组件对称实现，select 用 `groupedOptions` getter，combobox 用 `groupedOptions()` 方法
+2. **`<aithe-autoform>` 密码字段支持明文切换** — `autoform-item` 在 `inputType="password"` 时于输入框 `slot="suffix"` 渲染 `eye`/`eyeOff` 图标按钮，点击切换 `type` 在 `password` 与 `text` 之间切换；新增 `_passwordVisible` state 与 `togglePasswordVisible()` 方法
+3. **Demo 页面同步补充示例** — `form.ts` 新增「Grouped Select & Combobox」示例（中文城市按华东/华北/华南分组、预设搜索按 Analytics/Automation 分组）；`autoform.ts` 新增 `password` 字段示例
+
+### Issue 26.3.2.2 — Feature (2026-09-03)
+
+1. **新增 `<aithe-autoview>` 只读视图组件** — 基于 `<aithe-desc>` 的轻量适配器，与 `<aithe-autoform>` 共用同一份 `FormFieldConfig` 模型，将字段值渲染为结构化描述列表。内置类型感知的只读渲染器（input/textarea 纯文本、select/radio label 反查、checkbox 标签组、switch 是/否徽章、date-picker/time-picker 格式化日期、color-picker 色块+色值、rate/slider 纯数值），支持依赖联动显隐（仅 `show`/`hide` 生效），支持通过 `ViewRegistry` 注册自定义渲染器
+2. **新增 `ViewRegistry` 只读视图注册表** — `src/core/autoform/autoview.ts` 新增与 `FormRegistry` 对称的静态注册表，定义 `ViewFieldConfig`/`ViewRenderContext`/`ViewRenderer`/`ViewControlDefinition` 类型，允许注册自定义只读渲染器扩展 autoview
+3. **`<aithe-desc>` 描述列表增强** — 新增 `border-style` 属性（`none`/`full`/`row` 三种边框样式）和 `label-background` 属性（`filled`/`none` 标签背景）；修复 `border-radius` CSS 变量名 `--aithe-radius-md` → `--aithe-container-radius-md`；`labelWidth` 默认值由 `''` 改为 `'150px'`
+4. **DataHub 新增 `forceDedup` / `forceCache` 请求选项** — 允许无视 URL 命名约定强制启用去重和缓存，适用于 URL 不以 `query`/`list`/`get` 结尾但语义为查询的 GET 请求；当 `forceDedup` 或 `forceCache` 为 true 时自动跳过幂等防护，避免并发查询请求被误判为重复提交
+5. **DataHub `request` 方法重构** — 将内联 `execute` 函数和 HTTP 错误构造逻辑抽成 `executeRequest`/`buildHttpError`/`applyResponseInterceptor` 三个独立方法，force 选项判断抽成 `isCacheable`/`isDedupable`/`shouldGuardIdempotent` 三个辅助方法，降低认知复杂度
+6. **文档与演示同步更新** — 新增 `docs/api/display/autoview.md` API 文档；`docs/api/display/desc.md` 补充 `border-style`/`label-background` 属性文档和示例；`docs/api/summary.md` 新增 autoview 条目；新增 `src/apps/demo/pages/autoview.ts` 演示页（9 个示例覆盖基础/选择/高级/联动/完整档案/空值/三种边框样式）；11 种语言 i18n 文件同步更新
+
+### Issue 26.3.2.1 — Quality / Bug Fix (2026-08-25)
+
+1. **DataHub 缓存命中响应处理修复** — 缓存命中时原本直接返回缓存对象，跳过 `APIStyle.onResponse` 转换、`isSuccess` 业务校验、全局 `config.onResponse` 拦截器三道处理，导致缓存返回的 `data` 仍是原始业务包（未解包）、业务错误被静默吞掉、全局拦截器失效。抽取统一响应处理方法 `handleResponse`，让缓存命中路径与实际请求路径走完全一致的响应处理逻辑
+2. **`<aithe-tree-menu>` 激活态样式调整** — 移除分组切换按钮 `.group-toggle.active` 的灰底背景（`--aithe-color-surface-muted`），激活态仅靠文字颜色区分；子级容器 `.children` 新增顶部内边距 `--aithe-space-2`
+3. **`<aithe-sub-menu>` 激活态样式调整** — 移除切换按钮 `.toggle.active` 的灰底背景（`--aithe-color-surface-muted`），与 `<aithe-tree-menu>` 激活态视觉风格保持一致
+
+---
+
+## 概述
+
+Aithe UI 26.3.2 是 2026 年第 3 季度第 2 个月版本，聚焦于只读视图组件新增、表单组件功能增强、DataHub 请求调度能力扩展与文档质量提升。本版本在 26.3.1 基线版本的基础上，完成了 `<aithe-autoview>` 只读视图组件、`<aithe-select>`/`<aithe-combobox>` 选项分组、`<aithe-autoform>` 密码明文切换、DataHub `forceDedup`/`forceCache` 请求选项、DataHub 缓存命中响应处理修复、`listPlugin` 嵌套子列表支持等核心改进，并新增了 1 个 display 组件。组件数量从 100 个扩展至 103 个（含 `aithe-desc-item`、`aithe-autoview`、`aithe-box-table` 纳入 README 统计）。
+
+**26.3.2.4 子版本** 聚焦于 `listPlugin` 列表解析器重写（嵌套子列表与缩进续行支持）、认知复杂度治理（抽取 5 个独立函数）、死代码清理（删除 `parseListItem`）。
+
+**26.3.2.3 子版本** 聚焦于 `<aithe-select>`/`<aithe-combobox>` 选项分组（`group` 字段自动聚合）、`<aithe-autoform>` 密码字段明文切换（`eye`/`eyeOff` 图标按钮）。
+
+**26.3.2.2 子版本** 聚焦于 `<aithe-autoview>` 只读视图组件新增（基于 `<aithe-desc>` 的轻量适配器，与 autoform 共用 FormFieldConfig 模型）、`ViewRegistry` 自定义渲染器注册表、`<aithe-desc>` 边框样式与标签背景增强、DataHub `forceDedup`/`forceCache` 请求选项、DataHub `request` 方法重构。
+
+**26.3.2.1 子版本** 聚焦于 DataHub 缓存命中响应处理修复（缓存命中路径与实际请求路径走完全一致的响应处理逻辑）、`<aithe-tree-menu>`/`<aithe-sub-menu>` 激活态样式调整（移除灰底背景）。
+
+## 核心特性
+
+### 1. `<aithe-autoview>` 只读视图组件
+
+- **JSON 驱动只读详情视图**: 与 `<aithe-autoform>` 共用同一份 `FormFieldConfig` 模型，将字段值渲染为结构化描述列表
+- **内置 8 类只读渲染器**: input/textarea（纯文本）、select/radio（label 反查）、checkbox（标签组）、switch（是/否徽章）、date-picker/time-picker（格式化日期）、color-picker（色块+色值）、rate/slider（纯数值）
+- **依赖联动显隐**: 只读模式下仅生效 `show`/`hide` 规则，`disable`/`enable`/`clear`/`update` 被忽略
+- **`ViewRegistry` 自定义渲染器**: 与 `FormRegistry` 对称的静态注册表，支持 `register`/`unregister`/`get`/`has`/`types` 方法
+- **`ViewFieldConfig` 扩展类型**: 在 `FormFieldConfig` 基础上追加 `filter`/`emptyText`/`span`/`rowspan`/`align`/`hideLabel` 可选展示属性
+- **`aithe-view-ready` 事件**: 初始渲染完成后触发，携带当前可见字段值
+- **`getValues()` 方法**: 返回所有可见字段在 `data` 中的值
+
+### 2. `<aithe-select>` / `<aithe-combobox>` 选项分组
+
+- **`group` 字段**: 选项对象新增可选 `group?: string` 字段，用于分组聚合
+- **自动分组渲染**: 任一选项携带 `group` 字段时，所有选项按 `group` 聚合（保留插入顺序），每组前置 `.group-header` 标题，组内选项缩进显示
+- **向后兼容**: 无任何 `group` 字段时回退为扁平列表渲染
+- **键盘导航兼容**: select 分组模式下用 `flatIndex++` 维护 `activeIndex` 与原键盘导航逻辑兼容
+- **对称实现**: select 用 `groupedOptions` getter，combobox 用 `groupedOptions()` 方法
+
+### 3. `<aithe-autoform>` 密码明文切换
+
+- **`inputType="password"` 支持**: `autoform-item` 在 `inputType="password"` 时于输入框 `slot="suffix"` 渲染 `eye`/`eyeOff` 图标按钮
+- **明文切换**: 点击图标按钮切换 `type` 在 `password` 与 `text` 之间，`_passwordVisible` state 记录当前状态
+- **`togglePasswordVisible()` 方法**: 切换 `_passwordVisible` 状态
+- **`resolvePasswordType()` 方法**: 根据可见状态返回 `text` 或 `password`
+
+### 4. `<aithe-desc>` 描述列表增强
+
+- **`border-style` 属性**: `none`（无边框）、`full`（外框+所有单元格分隔线）、`row`（仅行分隔线，无外框和列分隔线），默认 `none`
+- **`label-background` 属性**: `filled`（默认灰底）或 `none`（透明），配合 `border-style="row"` 可实现简洁风格
+- **`border-radius` CSS 变量修正**: `--aithe-radius-md` → `--aithe-container-radius-md`（2 处）
+- **`labelWidth` 默认值变更**: 由 `''` 改为 `'150px'`
+- **`isBordered` 判定更新**: `border || borderStyle !== 'none'`
+
+### 5. DataHub `forceDedup` / `forceCache` 请求选项
+
+- **`forceDedup` 选项**: 为 true 时无视 URL 命名约定强制启用并发去重，适用于 URL 不以 `query`/`list`/`get` 结尾但语义为查询的 GET 请求
+- **`forceCache` 选项**: 为 true 时无视 URL 命名约定强制启用结果缓存，配合 `cacheTTL` 控制有效期
+- **跳过幂等防护**: `forceDedup` 或 `forceCache` 为 true 时自动跳过幂等防护，避免并发查询请求被误判为重复提交
+- **测试覆盖**: 新增 `force-options.test.ts`，8 个用例覆盖 forceDedup 去重、forceCache 缓存命中、force 选项跳过幂等守卫等场景
+
+### 6. DataHub 缓存命中响应处理修复
+
+- **统一响应处理方法 `handleResponse`**: 封装「APIStyle `onResponse` 转换 + `isSuccess` 业务校验 + 返回业务数据」三步逻辑
+- **缓存命中路径修复**: 缓存命中时先执行全局 `config.onResponse` 拦截器，再调用 `handleResponse` 完成 APIStyle 转换与 `isSuccess` 校验
+- **消除代码重复**: 实际请求路径也替换为调用 `handleResponse`，两条路径行为完全一致
+
+### 7. DataHub `request` 方法重构
+
+- **`executeRequest<T>()`**: 从内联 `execute` 函数抽成独立方法，封装适配器调用 + 响应拦截 + HTTP 错误处理 + 统一响应处理 + 缓存写入
+- **`buildHttpError()`**: HTTP 非 2xx 错误构造逻辑抽成独立方法
+- **`applyResponseInterceptor()`**: 全局响应拦截器应用抽成独立方法（缓存命中与实际请求路径共用）
+- **`isCacheable()` / `isDedupable()` / `shouldGuardIdempotent()`**: force 选项判断抽成三个辅助方法
+
+### 8. `listPlugin` 嵌套子列表支持
+
+- **嵌套子列表解析**: 通过递归调用 `listPlugin.block` 生成嵌套 `list` AST 节点，支持多层嵌套
+- **缩进续行支持**: 列表项标记行之后的缩进行被归集为续行或子列表，空行后通过前瞻判断是否仍属当前列表项
+- **认知复杂度治理**: 抽取 `collectItemSubLines`/`buildListItemChildren`/`blankLineBelongsToItem`/`lineEndsItem`/`parseSubLines` 五个独立函数，主循环复杂度降至 sonarjs 阈值以内
+- **死代码清理**: 删除被 `parseListItemIndented` 完全替代的 `parseListItem` 函数
+
+### 9. 组件样式调整
+
+- **`<aithe-tree-menu>` 激活态**: 移除 `.group-toggle.active` 的灰底背景（`--aithe-color-surface-muted`），激活态仅靠文字颜色区分；`.children` 新增顶部内边距 `--aithe-space-2`
+- **`<aithe-sub-menu>` 激活态**: 移除 `.toggle.active` 的灰底背景，与 `<aithe-tree-menu>` 激活态视觉风格统一
+
+### 10. DataHub GET 请求 body 修复
+
+- **`defaultStyle.onRequest`**: GET 请求不发送 body，跳过 `data` 包装，避免触发 "GET request with body is unusual" 警告
+
+### 11. 文档质量提升
+
+- **组件数量修正**: `quickstart.md`/`guide.md`/`i18n.md`/`framework-integration.md`/`theming.md`/`README.md` 中 "100 个组件" 修正为 "103 个组件"
+- **`docs/autoform.md`**: 删除重复的 `### 顶层结构` 和 `FormFieldConfig` 定义；`input` 类型说明补充 `password` 明文切换
+- **`docs/datahub.md`**: `DataHubRequestOptions` 补充 `forceDedup`/`forceCache`/`mockPath` 字段
+- **`docs/markdown.md`**: `listPlugin` 描述更新为"支持嵌套子列表和缩进续行"
+- **`docs/i18n.md`**: 删除错误的"翻译值也兼容函数类型"描述
+- **`docs/guide.md`**: 修复 `<select.options` 语法错误；删除多余闭合标记；4 反引号闭合改为 3 反引号；`AitheSelectOption` 补充 `variant`/`group` 字段说明
+- **`docs/theming.md`**: 代码块闭合标记统一为 3 反引号；"83 个组件"修正为"103 个组件"
+- **issue 文件目录重组**: `docs/issue/` 下 32 个 issue 文件按基线版本拆分到 `26.2.2/`/`26.2.3/`/`26.3.1/`/`26.3.2/` 四个子目录
+
+## 破坏性变更汇总
+
+| 变更项 | 旧值 | 新值 | Issue |
+|--------|------|------|-------|
+| `aithe-desc` 的 `labelWidth` 默认值 | `''`（auto） | `'150px'` | 26.3.2.2 |
+| `aithe-desc` 的 `border-radius` CSS 变量 | `--aithe-radius-md` | `--aithe-container-radius-md` | 26.3.2.2 |
+| `aithe-desc` 的 `isBordered` 判定 | `this.border` | `this.border \|\| this.borderStyle !== 'none'` | 26.3.2.2 |
+| `listPlugin` 的 `parseListItem` 函数 | 存在 | 删除（被 `parseListItemIndented` 替代） | 26.3.2.4 |
+| `listPlugin` 的 `list-item` AST `children` | 单一 `paragraph` | `paragraph` + 嵌套节点 | 26.3.2.4 |
+| `listPlugin` 的 `list-item` AST `checked` | 透传 `item.checked` | 显式 `null` | 26.3.2.4 |
+
+## 组件详细列表
+
+### 基础组件 (12个)
+
+#### 1. `<aithe-button>` - 按钮
+
+- **类型**: primary、default、dashed、text、link
+- **尺寸**: small、medium、large
+- **状态**: loading、disabled
+- **特性**: 图标支持、块级显示、自定义事件
+
+#### 2. `<aithe-button-group>` - 按钮组
+
+- **功能**: 按钮组合布局
+- **特性**: 统一间距、对齐方式
+
+#### 3. `<aithe-icon>` - 图标
+
+- **功能**: 矢量图标显示
+- **特性**: 内置图标库、自定义图标、尺寸控制
+
+#### 4. `<aithe-input>` - 输入框
+
+- **类型**: text、password、number、email 等
+- **特性**: 验证状态、前缀后缀、清除按钮
+
+#### 5. `<aithe-textarea>` - 文本域
+
+- **功能**: 多行文本输入
+- **特性**: 自动高度调整、字数统计
+
+#### 6. `<aithe-card>` - 卡片
+
+- **结构**: 标题、内容、操作区域
+- **特性**: 阴影、边框、悬停效果
+
+#### 7. `<aithe-tag>` - 标签
+
+- **类型**: 默认、可关闭、可选择
+- **特性**: 多种颜色、圆角样式
+
+#### 8. `<aithe-badge>` - 徽章
+
+- **类型**: 数字、圆点、状态
+- **特性**: 最大值显示、自定义内容
+
+#### 9. `<aithe-avatar>` - 头像
+
+- **类型**: 图片、文字、图标
+- **特性**: 尺寸控制、形状、组头像
+
+#### 10. `<aithe-divider>` - 分割线
+
+- **方向**: 水平、垂直
+- **特性**: 文字位置、虚线样式
+
+#### 11. `<aithe-empty>` - 空状态
+
+- **功能**: 数据为空时的占位显示
+- **特性**: 自定义图标、描述、操作按钮
+
+#### 12. `<aithe-chip>` - 芯片
+
+- **功能**: 紧凑的可选择标签
+- **特性**: 可关闭、可选择、多种颜色
+
+### 布局组件 (8个)
+
+#### 13. `<aithe-container>` - 容器
+
+- **类型**: fluid、fixed、full
+- **特性**: 响应式断点、内边距控制
+
+#### 14. `<aithe-row>` - 行
+
+- **功能**: 24 栅格系统的行容器
+- **特性**: 栅格间隔、对齐方式、换行控制
+
+#### 15. `<aithe-col>` - 列
+
+- **功能**: 24 栅格系统的列
+- **特性**: 响应式断点、偏移、排序
+
+#### 16. `<aithe-flex>` - 弹性布局
+
+- **功能**: 快速弹性布局容器
+- **特性**: 方向、对齐、换行、间距
+
+#### 17. `<aithe-space>` - 间距
+
+- **功能**: 子元素等间距布局
+- **特性**: 方向、大小、对齐
+
+#### 18. `<aithe-collapse>` - 折叠面板
+
+- **类型**: 手风琴、多展开
+- **特性**: 边框样式、图标位置
+
+#### 19. `<aithe-collapse-item>` - 折叠项
+
+- **功能**: 单个可折叠面板
+- **特性**: 标题、内容、禁用状态
+
+#### 20. `<aithe-affix>` - 固钉
+
+- **功能**: 滚动时固定元素
+- **特性**: 偏移量、目标容器、回调事件
+
+### 导航组件 (7个)
+
+#### 21. `<aithe-menu>` - 菜单
+
+- **模式**: 垂直、水平、内联
+- **特性**: 主题、选中状态、展开控制
+
+#### 22. `<aithe-menu-item>` - 菜单项
+
+- **功能**: 单个菜单项
+- **特性**: 图标、禁用状态、选中状态
+
+#### 23. `<aithe-sub-menu>` - 子菜单
+
+- **功能**: 可展开的子菜单
+- **特性**: 标题、图标、展开状态
+- **备注**: 26.3.2.1 移除 `.toggle.active` 灰底背景
+
+#### 24. `<aithe-breadcrumb>` - 面包屑
+
+- **功能**: 页面层级导航
+- **特性**: 分隔符、最大显示数量
+
+#### 25. `<aithe-breadcrumb-item>` - 面包屑项
+
+- **功能**: 单个面包屑项
+- **特性**: 链接、分隔符、当前项
+
+#### 26. `<aithe-steps>` - 步骤条
+
+- **方向**: 水平、垂直
+- **特性**: 当前步骤、状态、自定义图标
+
+#### 27. `<aithe-back-top>` - 回到顶部
+
+- **功能**: 滚动到页面顶部
+- **特性**: 可见阈值、自定义位置、动画
+
+### 表单组件 (18个)
+
+#### 28. `<aithe-checkbox>` - 复选框
+
+- **功能**: 单个复选框
+- **特性**: 中间状态、禁用、自定义标签
+
+#### 29. `<aithe-checkbox-group>` - 复选框组
+
+- **功能**: 多个复选框组合
+- **特性**: 方向、最大选择数、全选
+
+#### 30. `<aithe-radio>` - 单选框
+
+- **功能**: 单个单选框
+- **特性**: 禁用状态、自定义标签
+
+#### 31. `<aithe-radio-group>` - 单选框组
+
+- **功能**: 多个单选框组合
+- **特性**: 方向、按钮样式、禁用状态
+
+#### 32. `<aithe-select>` - 选择器
+
+- **模式**: 单选、多选、标签模式
+- **特性**: 搜索、过滤、远程数据、分组
+- **备注**: 26.3.2.3 新增 `group` 字段选项分组渲染，`groupedOptions` getter + `renderOption()` 方法
+
+#### 33. `<aithe-switch>` - 开关
+
+- **功能**: 开关切换
+- **特性**: 大小、加载状态、自定义内容
+
+#### 34. `<aithe-color-picker>` - 颜色选择器
+
+- **模式**: 简单、高级
+- **特性**: 预设颜色、透明度、格式输出
+
+#### 35. `<aithe-combobox>` - 组合框
+
+- **功能**: 可搜索的下拉框
+- **特性**: 自动完成、远程搜索、多选
+- **备注**: 26.3.2.3 新增 `group` 字段选项分组渲染，`groupedOptions()` 方法 + `renderOption()` 方法
+
+#### 36. `<aithe-date-picker>` - 日期选择器
+
+- **类型**: 日期、周、月、年、范围
+- **特性**: 快捷选择、禁用日期、自定义格式
+
+#### 37. `<aithe-time-picker>` - 时间选择器
+
+- **功能**: 时间选择
+- **特性**: 步长、格式、禁用时间
+
+#### 38. `<aithe-slider>` - 滑块
+
+- **类型**: 单滑块、范围滑块
+- **特性**: 步长、标记点、垂直模式
+
+#### 39. `<aithe-rate>` - 评分
+
+- **功能**: 星级评分
+- **特性**: 半星、自定义图标、只读
+
+#### 40. `<aithe-form>` - 表单
+
+- **功能**: 表单容器
+- **特性**: 验证、布局、提交处理
+
+#### 41. `<aithe-form-item>` - 表单项
+
+- **功能**: 表单字段包装器
+- **特性**: 标签、验证信息、布局
+
+#### 42. `<aithe-upload>` - 上传
+
+- **模式**: 点击上传、拖拽上传
+- **特性**: 多文件、限制、预览、自定义请求
+
+#### 43. `<aithe-transfer>` - 穿梭框
+
+- **功能**: 双列表数据转移
+- **特性**: 搜索、分页、自定义渲染
+
+#### 44. `<aithe-autoform>` - 自动表单
+
+- **功能**: JSON 配置驱动的自动渲染表单组件
+- **特性**: 13 种内置控件类型、自定义控件注册表、实时校验和提交校验
+- **备注**: 26.3.2.3 `inputType="password"` 新增明文切换（`eye`/`eyeOff` 图标按钮）
+
+#### 45. `<aithe-autoform-item>` - 自动表单项
+
+- **功能**: 表单项容器组件，三段式布局（header + control + footer）
+- **备注**: 26.3.2.3 新增 `_passwordVisible` state、`togglePasswordVisible()`/`resolvePasswordType()` 方法
+
+### 反馈组件 (9个)
+
+#### 46. `<aithe-dialog>` - 对话框
+
+- **功能**: 模态对话框
+- **特性**: 标题、内容、操作按钮、关闭控制
+
+#### 47. `<aithe-modal>` - 模态框
+
+- **功能**: 轻量级模态框
+- **特性**: 多种尺寸、全屏、自定义内容
+
+#### 48. `<aithe-drawer>` - 抽屉
+
+- **位置**: 上、下、左、右
+- **特性**: 大小、标题、遮罩、关闭控制
+
+#### 49. `<aithe-tooltip>` - 工具提示
+
+- **位置**: 12 个方向
+- **特性**: 延迟显示、主题、自定义内容
+
+#### 50. `<aithe-popover>` - 弹出框
+
+- **功能**: 点击触发的弹出内容
+- **特性**: 触发方式、位置、箭头
+
+#### 51. `<aithe-toast>` - 轻提示
+
+- **类型**: 成功、警告、错误、信息
+- **特性**: 自动关闭、位置、自定义持续时间
+
+#### 52. `<aithe-alert>` - 警告提示
+
+- **类型**: 成功、信息、警告、错误
+- **特性**: 可关闭、图标、描述
+
+#### 53. `<aithe-notification>` - 通知提醒框
+
+- **功能**: 全局通知
+- **特性**: 位置、持续时间、自定义按钮
+
+#### 54. `<aithe-loading>` - 加载中
+
+- **类型**: 全屏、容器、内联
+- **特性**: 自定义文本、延迟显示
+
+### 数据展示组件 (13个)
+
+#### 55. `<aithe-table>` - 表格
+
+- **功能**: 数据表格
+- **特性**: 排序、筛选、分页、选择、虚拟滚动
+
+#### 56. `<aithe-table-column>` - 表格列
+
+- **功能**: 声明式表格列定义
+- **特性**: 字段映射、排序、对齐、宽度
+
+#### 57. `<aithe-tabs>` - 标签页
+
+- **类型**: 线型、卡片型
+- **特性**: 位置、大小、可关闭、懒加载
+
+#### 58. `<aithe-tab-pane>` - 标签页面板
+
+- **功能**: 单个标签页内容
+- **特性**: 禁用、懒加载、图标
+
+#### 59. `<aithe-tree>` - 树形控件
+
+- **功能**: 层级数据展示
+- **特性**: 选择、展开、搜索、拖拽
+
+#### 60. `<aithe-tree-menu>` - 树形菜单
+
+- **功能**: 基于 Tree 数据的菜单导航
+- **特性**: 递归渲染、意图着色、垂直/水平布局
+- **备注**: 26.3.2.1 移除 `.group-toggle.active` 灰底背景；`.children` 新增顶部内边距
+
+#### 61. `<aithe-timeline>` - 时间线
+
+- **模式**: 垂直、水平
+- **特性**: 自定义节点、颜色、图标、数据驱动模式
+
+#### 62. `<aithe-timeline-item>` - 时间线项
+
+- **功能**: 单个时间线节点
+- **特性**: 时间、内容、状态
+
+#### 63. `<aithe-pagination>` - 分页
+
+- **功能**: 数据分页
+- **特性**: 大小选择、快速跳转、简洁模式
+
+#### 64. `<aithe-dropdown>` - 下拉菜单
+
+- **功能**: 下拉菜单容器
+- **特性**: 触发方式、位置、禁用状态
+
+#### 65. `<aithe-metrics>` - 指标
+
+- **功能**: 指标展示组件，支持标签和数值展示
+- **特性**: 自定义标签、数值、趋势指示
+
+#### 66. `<aithe-metrics-group>` - 指标组
+
+- **功能**: 分组指标容器
+- **特性**: 水平/垂直排列、分组展示
+
+#### 67. `<aithe-box-table>` - 卡片表格
+
+- **功能**: 卡片式表格组件
+- **特性**: 卡片布局、选择模式
+
+### 展示组件 (14个)
+
+#### 68. `<aithe-carousel>` - 走马灯
+
+- **功能**: 轮播图
+- **特性**: 自动播放、指示器、箭头、切换效果
+
+#### 69. `<aithe-comparison>` - 对比
+
+- **功能**: 前后对比滑块
+- **特性**: 方向、手柄样式、标签
+
+#### 70. `<aithe-animated-image>` - 动画图片
+
+- **功能**: 带动画的图片显示
+- **特性**: 缩放、平移、加载动画
+
+#### 71. `<aithe-markdown>` - Markdown 渲染
+
+- **功能**: Markdown 内容渲染
+- **特性**: 语法高亮、自定义渲染器
+- **备注**: 26.3.2.4 `listPlugin` 新增嵌套子列表与缩进续行支持
+
+#### 72. `<aithe-code-editor>` - 代码编辑器
+
+- **功能**: 代码显示与编辑组件
+- **特性**: 语法高亮（38 种语言）、行号显示、一键复制、代码折叠
+
+#### 73. `<aithe-markdown-editor>` - Markdown 编辑器
+
+- **功能**: Markdown 编辑与实时预览
+- **特性**: 分屏模式、实时预览
+
+#### 74. `<aithe-label>` - 标签
+
+- **功能**: 标签展示组件
+- **特性**: filled/outlined 变体、多种颜色、可移除、图标支持
+
+#### 75. `<aithe-mini-box>` - 迷你卡片
+
+- **功能**: 迷你卡片组件
+- **特性**: 紧凑布局、选择模式
+
+#### 76. `<aithe-brief-box>` - 简要卡片
+
+- **功能**: 简要卡片组件
+- **特性**: name/status/tags/actions slot、选择模式
+
+#### 77. `<aithe-detail-box>` - 详情卡片
+
+- **功能**: 详情卡片组件
+- **特性**: content/actions slot、空插槽自动隐藏
+
+#### 78. `<aithe-profile>` - 个人资料
+
+- **功能**: 个人资料组件
+- **特性**: 头像、信息展示
+
+#### 79. `<aithe-desc>` - 描述列表
+
+- **功能**: 描述列表组件
+- **特性**: 水平/垂直布局、独立 grid 列、`content`/`filter` 属性
+- **备注**: 26.3.2.2 新增 `border-style`（`none`/`full`/`row`）和 `label-background`（`filled`/`none`）属性；`border-radius` CSS 变量修正；`labelWidth` 默认值改为 `'150px'`
+
+#### 80. `<aithe-desc-item>` - 描述列表项
+
+- **功能**: 描述列表项组件
+- **特性**: `content`/`filter` 属性
+
+#### 81. `<aithe-autoview>` - 自动视图 *(26.3.2.2 新增)*
+
+- **功能**: JSON 驱动的只读详情视图，`<aithe-autoform>` 的只读镜像
+- **特性**: 与 autoform 共用 `FormFieldConfig` 模型、内置 8 类只读渲染器、依赖联动显隐、`ViewRegistry` 自定义渲染器
+- **事件**: `aithe-view-ready`（初始渲染完成后触发，携带可见字段值）
+- **方法**: `getValues()`（返回所有可见字段值）
+
+### 进度组件 (4个)
+
+#### 82. `<aithe-progress-bar>` - 进度条
+
+- **类型**: 线型、环形、仪表盘
+- **特性**: 颜色、条纹动画、自定义文本
+
+#### 83. `<aithe-progress-ring>` - 环形进度条
+
+- **功能**: 环形进度显示
+- **特性**: 大小、宽度、颜色渐变
+
+#### 84. `<aithe-spinner>` - 加载旋转器
+
+- **类型**: 旋转、脉冲、波浪
+- **特性**: 大小、颜色、速度
+
+#### 85. `<aithe-skeleton>` - 骨架屏
+
+### 容器组件 (4个)
+
+#### 86. `<aithe-callout>` - 提示框
+
+- **类型**: 信息、成功、警告、错误
+- **特性**: 图标、标题、可关闭
+
+#### 87. `<aithe-details>` - 详情
+
+- **功能**: 可展开的详情区域
+- **特性**: 摘要、展开状态、禁用
+
+#### 88. `<aithe-scroller>` - 滚动容器
+
+- **功能**: 自定义滚动区域
+- **特性**: 虚拟滚动、懒加载、滚动事件
+
+#### 89. `<aithe-split-panel>` - 分割面板
+
+### 主题组件 (7个)
+
+#### 90. `<aithe-theme-picker>` - 主题选择器
+
+- **功能**: 主题选择器，支持 Light/Dark 分组展示
+- **特性**: 色点预览、键盘导航、`aithe-theme-change` 事件
+
+#### 91. `<aithe-theme-preview>` - 主题预览
+
+- **功能**: 主题预览面板，支持局部预览 + 确认应用全局主题
+- **特性**: 工具栏、预览区、`aithe-theme-apply` 事件
+
+#### 92. `<aithe-locale-switch>` - 语言切换
+
+- **功能**: 语言切换器，支持 en-US / zh-CN / zh-TW / zh-HK / ja-JP / ko-KR / es-ES / pt-BR / fr-FR / de-DE 切换
+- **特性**: 浮层下拉、键盘导航、`locales` 属性限定显示语言、`aithe-locale-change` 事件
+
+#### 93. `<aithe-shadow-picker>` - 阴影选择器
+
+- **功能**: 阴影风格选择器，支持 9 种内置阴影风格切换
+- **特性**: 浮层下拉、图标预览、i18n 支持、`placement` 属性控制弹出方向
+
+#### 94. `<aithe-typo-picker>` - 排版风格选择器
+
+- **功能**: 排版风格选择器，支持 4 种内置排版风格切换（minimal/business/luxury/compact）
+- **特性**: 浮层下拉、图标预览、i18n 支持、`placement` 属性控制弹出方向
+
+#### 95. `<aithe-shape-picker>` - 形状风格选择器
+
+- **功能**: 形状风格选择器，支持 8 种内置形状风格切换
+- **特性**: 委托 `<aithe-tree-menu>` 渲染、预览缩略图、键盘导航
+
+#### 96. `<aithe-theme-switch>` - 统一外观切换器
+
+- **功能**: 统一外观切换器组件，一键切换主题/形状/阴影/排版
+- **特性**: 整合 theme-picker、shape-picker、shadow-picker、typo-picker 为一体
+
+### 框架组件 (7个)
+
+#### 97. `<aithe-page>` - 页面
+
+- **功能**: 完整页面布局
+- **特性**: 头部、侧边栏、内容区、页脚
+
+#### 98. `<aithe-body>` - 页面主体
+
+- **功能**: 页面主体容器
+- **特性**: 布局结构、内容区域
+
+#### 99. `<aithe-header>` - 页面头部
+
+- **功能**: 页面头部组件
+- **特性**: 标题、导航、操作区域
+
+#### 100. `<aithe-sidebar>` - 侧边栏
+
+- **功能**: 侧边栏组件
+- **特性**: 菜单导航、伸缩模式
+
+#### 101. `<aithe-dashboard>` - 仪表盘
+
+- **功能**: 拖拽式仪表盘组件
+- **特性**: CSS Grid 布局、面板拖拽交换、面板调整大小、状态持久化
+
+#### 102. `<aithe-dashboard-panel>` - 仪表盘面板
+
+- **功能**: 仪表盘面板组件
+- **特性**: 面板内容、拖拽、调整大小
+
+#### 103. `<aithe-log-panel>` - 日志面板
+
+- **功能**: 日志可视化面板
+- **特性**: overlay/inline 布局、级别过滤、搜索、复制
+
+## 技术架构
+
+### 核心基类
+
+- **AitheElement**: 所有组件的基类，提供统一的属性、事件和样式管理
+- **主题系统**: 基于 CSS 自定义属性的主题切换机制
+- **工具函数**: DOM 操作、事件处理、验证工具
+
+### 样式系统
+
+- **设计令牌**: 统一的颜色、间距、字体、阴影等设计变量
+- **响应式**: 基于 CSS 媒体查询的响应式设计
+- **主题切换**: 通过 CSS 类名切换主题
+
+### Autoform / AutoView 模块
+
+- **`FormRegistry`**: 表单控件注册表，支持 13 种内置控件类型
+- **`ViewRegistry`**: 只读视图控件注册表，与 `FormRegistry` 对称（26.3.2.2 新增）
+- **`ViewFieldConfig`**: 扩展 `FormFieldConfig`，追加 `filter`/`emptyText`/`span`/`rowspan`/`align`/`hideLabel` 属性（26.3.2.2 新增）
+- **`FormRuleEngine`**: 表单规则引擎，支持 `show`/`hide`/`disable`/`enable`/`clear`/`update` 规则类型
+
+### DataHub 数据中间层
+
+- **`forceDedup` 选项**: 无视 URL 命名约定强制启用并发去重（26.3.2.2 新增）
+- **`forceCache` 选项**: 无视 URL 命名约定强制启用结果缓存（26.3.2.2 新增）
+- **缓存命中响应处理修复**: 缓存命中路径与实际请求路径走完全一致的响应处理逻辑（26.3.2.1 修复）
+- **`handleResponse` 统一方法**: 封装 APIStyle 转换 + isSuccess 校验 + 返回业务数据（26.3.2.1 新增）
+- **`executeRequest`/`buildHttpError`/`applyResponseInterceptor`**: request 方法重构拆分（26.3.2.2 新增）
+- **`isCacheable`/`isDedupable`/`shouldGuardIdempotent`**: force 选项判断辅助方法（26.3.2.2 新增）
+- **GET 请求 body 修复**: `defaultStyle.onRequest` GET 请求跳过 `data` 包装（26.3.2.2 修复）
+
+### Markdown 解析引擎
+
+- **`listPlugin` 嵌套子列表支持**: 通过递归调用 `listPlugin.block` 生成嵌套 `list` AST 节点（26.3.2.4 新增）
+- **缩进续行支持**: 列表项标记行之后的缩进行被归集为续行或子列表（26.3.2.4 新增）
+- **认知复杂度治理**: 抽取 5 个独立函数分层拆解（26.3.2.4）
+
+### 构建系统
+
+- **Vite**: 快速的开发服务器和构建工具
+- **TypeScript**: 完整的类型定义支持
+- **Lit 3.x**: 现代 Web Components 开发框架
+- **tsc-alias**: 构建后自动替换 `.d.ts` 中的别名为相对路径
+- **litExternalPlugin**: Vite 插件将 lit 标记为外部依赖
+- **Vitest**: 测试框架
+
+### 路径别名体系
+
+- **`@base/*`** → `src/base/*`
+- **`@components/*`** → `src/components/*`
+- **`@core/*`** → `src/core/*`
+- **`@styles/*`** → `src/styles/*`
+- **`@types/*`** → `src/types/*`（含裸引用 `@types`）
+- **`@utils/*`** → `src/utils/*`（含裸引用 `@utils`）
+
+### 代码质量工具链
+
+- **ESLint**: 代码静态分析，集成 `typescript-eslint`、`eslint-plugin-lit`、`eslint-plugin-wc`、`eslint-plugin-sonarjs`、`eslint-config-prettier`，使用 flat config 格式
+- **Prettier**: 代码格式化，统一缩进、引号、行宽等风格
+- **Vitest**: 单元测试框架
+- **npm 脚本**: `lint` / `lint:fix` / `format` / `format:fix` / `test` / `test:watch`
+
+## 安装和使用
+
+### 安装
+
+```bash
+npm install aithe-ui
+```
+
+### 基本使用
+
+```javascript
+import 'aithe-ui';
+
+// 在 HTML 中使用
+<aithe-button type="primary" size="medium">
+  点击我
+</aithe-button>;
+```
+
+### AutoView 只读视图
+
+```javascript
+import '@aithe/aithe-ui/components/display/autoview';
+
+// JSON 驱动的只读详情视图
+const fields = JSON.stringify([
+  { name: 'username', type: 'input', label: '用户名' },
+  { name: 'role', type: 'select', label: '角色',
+    options: [{ label: '管理员', id: 'admin' }] },
+  { name: 'active', type: 'switch', label: '状态' }
+]);
+const data = { username: '张三', role: 'admin', active: true };
+```
+
+```html
+<aithe-autoview .fields=${fields} .data=${data} column="2" border></aithe-autoview>
+```
+
+### Select / Combobox 选项分组
+
+```html
+<aithe-select
+  options='[{"label":"上海","id":"sh","group":"华东"},{"label":"杭州","id":"hz","group":"华东"},{"label":"北京","id":"bj","group":"华北"}]'
+></aithe-select>
+```
+
+### DataHub force 选项
+
+```javascript
+import { dataHub } from 'aithe-ui';
+
+// 强制启用去重（URL 不以 query/list/get 结尾但语义为查询）
+await dataHub.request('/system/roles/viewer', undefined, {
+  method: 'GET',
+  forceDedup: true,
+});
+
+// 强制启用缓存
+await dataHub.request('/system/config', undefined, {
+  method: 'GET',
+  forceCache: true,
+  cacheTTL: 60000,
+});
+```
+
+## 浏览器支持
+
+- Chrome 61+
+- Firefox 63+
+- Safari 10.1+
+- Edge 79+
+- iOS Safari 10.3+
+- Android Chrome 61+
+
+## 性能特点
+
+- **Tree-shaking 支持**: 支持按需导入
+- **零运行时依赖**: 仅依赖 Lit 库
+- **轻量级**: 组件按需加载
+- **服务端渲染友好**: 支持 SSR/SSG
+
+## 后续版本规划
+
+### 26.3.x (2026年第3季度)
+
+- 组件性能优化
+- 新增高级表单组件
+- 单元测试覆盖率提升
+
+### 26.4.x (2026年第4季度)
+
+- 响应式布局增强
+- 动画系统改进
+- 开发者工具集成
+- 主题定制工具
+
+## 许可证
+
+MIT License - Archest 团队