@aithe/aithe-ui 26.2.2 → 26.3.1

package/docs/changelog/VERSION_26.3.1.md

@@ -0,0 +1,966 @@
+# Aithe UI 26.3.1 版本详细说明
+
+## 版本信息
+
+- **版本号**: 26.3.1
+- **发布日期**: 2026-08-06
+- **最新子版本**: 26.3.1.7
+- **版本类型**: 功能版本
+- **版本描述**: 2026年第3季度第1个月版本 — 组件功能增强与质量提升
+
+## 版本变更记录
+
+### Issue 26.3.1.7 — Quality / Bug Fix (2026-08-06)
+
+1. **DataHub 错误处理增强** — HTTP 非 2xx 错误响应优先用 APIStyle 解析响应体，提取业务错误信息（code/message），避免丢失后端返回的友好错误描述；`DataHubError` 新增 `data` 字段携带原始响应体
+2. **K8s APIStyle 错误响应支持** — `k8sStyle.onResponse` 新增对 K8s `Status` 对象（`{kind:"Status", status:"Failure", message, reason, code}`）的识别，正确解析非 2xx 错误响应的 `reason`/`message`
+3. **DataHub 导入路径规范化** — datahub 模块内 5 个文件的 `../` 跨目录相对路径导入统一改为 `@core/datahub/*` 别名导入，符合 `src/core/AGENTS.md` 规范
+4. **Filter 测试导入路径规范化** — `filter/__tests__/index.test.ts` 的相对路径导入改为 `@core/filter/*` 别名导入
+5. **SSR 环境适配** — `<aithe-log-panel>`、`<aithe-affix>`、`<aithe-back-top>`、`<aithe-theme-switch>` 4 个组件的 `window` 引用改为 `globalThis`，兼容非浏览器环境
+6. **API 文档补充** — 新增 `<aithe-log-panel>`、`<aithe-desc-item>`、`<aithe-autoform-item>` 3 个组件的 API 文档；更新 `summary.md` 索引
+
+### Issue 26.3.1.6 — Quality / Bug Fix (2026-07-02)
+
+1. **CSS 自定义属性统一** — 将组件中使用的 CSS 自定义属性从旧命名规范迁移到新规范（`--aithe-duration-normal` → `--aithe-duration-base`/`--aithe-duration-slow`，`--aithe-container-radius` → `--aithe-container-radius-md`，`--aithe-border-radius-md` → `--aithe-radius-md`，`--aithe-font-mono` → `--aithe-font-family-mono`）
+2. **CSS 变量新增** — `global.css.ts` 新增 `--aithe-font-size-base`/`--aithe-font-size-3xl`/`--aithe-font-size-4xl`/`--aithe-font-size-5xl` 字体尺寸变量
+3. **主题系统增强** — 所有 24 个主题统一新增 `--aithe-fill-1`/`--aithe-fill-2`/`--aithe-color-surface-hover`/`--aithe-color-text-secondary`/`--aithe-color-bg-muted`/`--aithe-color-bg-hover`/`--aithe-color-border-subtle`/`--aithe-primary-6-rgb` 8 个 CSS 变量
+4. **`<aithe-desc>` 样式重构** — 移除 `desc-cell-label` 的 `padding`，改用 flex 居中；移除 `desc-item` 的 `padding`；`desc-cell-content` 的 `background` 移除回退值
+5. **`<aithe-mini-box>` 样式修复** — hover 背景色移除嵌套的 `--aithe-color-bg-hover` 回退
+6. **`<aithe-autoform-item>` 颜色修正** — `box-shadow` 中的 `--aithe-primary-6-rgb` 回退值从 `59, 130, 246` 改为 `77, 141, 255`
+7. **`<aithe-sidebar>` 导入增强** — 新增 `browserEnv` 导入
+8. **`<aithe-element>` JSDoc 更新** — 类注释补充浏览器环境检测说明
+9. **`AitheUI` 类增强** — 新增 `_ua` 私有字段和 10 个浏览器环境检测 getter（`isMobile`/`isAndroid`/`isIOS`/`isChrome`/`isEdge`/`isWechat`/`isWindows`/`isMacOS`/`isRealMobile`/`isChromeEmulator`/`supportsTouch`）
+
+### Issue 26.3.1.5 — Feature (2026-06-30)
+
+1. **`<aithe-tabs>` 组件增强** — 修复 line 模式边框重复、修复 button 模式 icon 前景色、新增 `max-visible-tabs` 溢出折叠、新增 `extra` 具名插槽、溢出菜单改用 `<aithe-select>` 组件、提取 `renderTab` 方法、代码注释全面增强（9 个 CSS Parts、10 个 CSS 自定义属性）
+2. **`<aithe-tab-pane>` 注释增强** — 所有属性扩展为多行双语注释，补充 JSDoc 标签
+3. **`<aithe-table>` 列固定优化** — 选择列 `selection-cell` 改为 `position: sticky` 固定左侧、新增 `has-fixed` 属性控制 `table` 的 `min-width: max-content`、修复斑马纹行固定列背景色
+4. **`<aithe-desc>` 描述列表重构** — 布局算法从 label+content 合并单元格改为独立 grid 列、新增 `content`/`filter` 属性支持过滤器、`label-width` 默认值改为 `150px`、移除 `desc-item` 的 `labelWidth` 属性、边框样式重构
+5. **`<aithe-desc-item>` 属性扩展** — 新增 `content` 和 `filter` 属性，支持直接传入值并应用过滤器
+6. **`<aithe-box-table>` 卡片表格重构** — 移除自建卡片 DOM，改用 `<aithe-brief-box>` 组件渲染卡片、移除 `content` 列插槽、`boxCols=0` 时改为自适应流式布局
+7. **`<aithe-detail-box>` 插槽动态隐藏** — 新增 `_hasContent`/`_hasActions` 状态，空插槽自动 `hidden`，添加 `@slotchange` 监听
+8. **`<aithe-brief-box>` 操作区样式修复** — `brief-actions` 改为 `align-items: stretch`，新增 `::slotted` 样式支持垂直排列
+9. **`<aithe-tag>` 注释增强** — 补充 JSDoc 标签
+10. **Demo 页面增强** — `data.ts` 新增 7 个 tabs 演示示例
+11. **国际化扩展** — 11 种语言新增 `data.tabs.moreTabsAriaLabel` 翻译键
+12. **SonarQube 代码质量修复** — `<aithe-desc>` 提取 `_getItemContent`/`_findNextPosition`/`_markOccupied` 消除 S3358/S3776 告警；`<aithe-desc-item>` 提取 `renderContent` 消除 S3358 告警
+13. **`AitheSelectableType` 类型重构** — 从 `boolean | 'single'` 改为 `'none' | 'multi' | 'single'` 纯字符串枚举，消除混合返回类型告警；`<aithe-table>` 移除自定义 converter；Box 组件族 `selectable` 从 `Boolean` 统一为 `AitheSelectableType`
+
+### Issue 26.3.1.4 — Feature (2026-06-26)
+
+1. **`<aithe-table>` 六项新功能** — 列固定（`fixed`）、列宽拖拽调整（`resizable`）、列拖拽排序（`draggable`）、loading 加载占位、行单选模式（`selectable="single"`）、键盘导航（ArrowDown/ArrowUp/空格/Enter）
+2. **`<aithe-button>` variant 重构** — 废弃 `danger` 属性，统一使用 `variant` 属性控制按钮危险样式
+3. **`<aithe-tag>` 尺寸系统与 variant 重构** — 新增 `size` 属性（sm/md/lg），`type` 标记为 `@deprecated`，推荐使用 `variant`；移除 `min-height` 硬编码
+4. **`<aithe-table-column>` 属性扩展** — 新增 `fixed`、`resizable`、`draggable`、`min-width`、`box` 属性；`cellRenderer` 签名变更为 `(key, value, record)`
+5. **类型系统增强** — 新增 `AitheSelectableType`、`AitheColumnFixed`、`AitheDataRenderer`、`AitheDataProvider` 类型
+6. **`<aithe-box-table>` 导出** — 新增 `box-table` 组件导出，支持卡片式布局模式
+7. **Display 组件系列** — 新增 `mini-box`、`brief-box`、`detail-box`、`profile`、`desc`、`desc-item` 六个 display 组件导出
+8. **API 应用 Demo 页** — 新增 `docs` 页面，11 种语言 i18n 翻译，`demo-data.ts` 增强
+9. **Demo 页面增强** — `data.ts` 新增 7 个 table 示例（固定列、调整宽度、拖拽排序、loading、单选、键盘导航、box-table）；`display.ts` 新增 225 行 display 示例
+10. **SonarQube 代码质量修复** — 修复 `table.ts`、`profile.ts`、`box-table.ts`、`desc.ts` 中的 S3358、S6660、S1128、S7761、S4325、S3776、S1854、S2156 等 15+ 项告警；更新 `CONTRIBUTING.md` 新增 8 条规则
+
+### Issue 26.3.1.3 — Feature (2026-06-23)
+
+1. **`<aithe-autoform>` 增强** — 新增 `initial-values` 属性支持外部初始值覆盖 `dft`；新增 `show-submit` 属性控制内置提交按钮显隐；新增 `submit()` 方法编程触发提交；操作区改用 `<aithe-button-group>` 包裹 slot 和内置按钮
+2. **`<aithe-anchored-overlay>` 含入块偏移修正** — 修复 `position:fixed` 面板在 `transform`/`filter` 等祖先元素内定位偏移的问题，通过临时设置 `left:0;top:0` 测量含入块偏移量并补偿
+3. **事件名统一** — `<aithe-dropdown>`、`<aithe-popover>`、`<aithe-tooltip>`、`<aithe-select>` 的开关状态变更事件由 `aithe-open-change` 统一为 `aithe-dropdown-change`
+4. **原生事件冒泡控制** — `<aithe-input>`、`<aithe-textarea>`、`<aithe-code-editor>`、`<aithe-combobox>` 在原生事件处理器中调用 `event.stopPropagation()`，防止原生事件逃逸到组件外部
+5. **文档与注释同步更新** — 更新 `autoform.ts`/`anchored-overlay.ts` JSDoc；更新 `docs/autoform.md`/`docs/api/form/autoform.md`；更新 6 个 AGENTS.md
+
+### Issue 26.3.1.2 — Feature (2026-06-18)
+
+1. **Filter 数据格式化框架** — 新增轻量 Filter 模块，支持声明式过滤器表达式，零第三方依赖；内置 5 种过滤器（金额、日期、空值替换、字节数、时间友好显示）；支持链式过滤和自定义扩展
+2. **`<aithe-metrics>` 集成 filter** — `MetricsData` 接口新增 `filter` 字段，支持通过 `data.filter` / `params.filter` 设置过滤器表达式格式化指标值
+3. **`<aithe-table-column>` 集成 filter** — 新增 `filter` 属性，支持对列单元格值进行格式化，优先级：`cellRenderer` > `filter` > 原始值
+4. **`<aithe-table>` 集成 filter** — `syncSlotColumns` 同步 `filter` 到列元数据；`renderCell` 新增 filter 格式化逻辑
+5. **`<aithe-modal>` / `<aithe-drawer>` transform 定位修复** — 将 `transform` 动画从 `.panel` 移至内部 `.panel-inner` 包装层，避免破坏内部 `fixed` 定位子元素的参考系
+6. **`MockAdapter` 增强** — 新增 `mockPath` 支持，可通过 URL 加载远程 Mock 数据文件
+7. **国际化扩展** — `zh-CN` / `en-US` 新增 `filter.timeAgo.*` 翻译键（共 18 条），支持时间友好显示的本地化文案
+8. **测试框架集成** — 安装 `vitest@^4.1.6`，新增 `vitest.config.ts` 配置，添加 `test` / `test:watch` 脚本；Filter 模块 38 个测试用例全部通过
+9. **文档同步更新** — 新增 `docs/filter.md`（完整 Filter 模块文档）；更新 `docs/guide.md`（新增 Filter 数据格式化章节）；更新 `metrics.md`、`table.md`、`table-column.md` API 文档（新增 `filter` 字段说明）
+
+### Issue 26.3.1.1 — Feature (2026-06-16)
+
+1. **`AitheSidebarItemFilter` 类型重命名** — 改为 `AitheTreeNodeFilter`，语义更通用，适用于所有树形菜单组件的过滤场景
+2. **`aithe-tree-menu` 默认权限过滤** — 新增内置 `itemFilter` 默认值，检查 `item.hasPermission !== false`，支持通过 `hasPermission` 字段控制菜单项显隐
+3. **`aithe-dropdown` 新增 `itemFilter` 属性** — 透传给内部 `<aithe-tree-menu>`，支持上层使用者定制菜单项过滤
+4. **`Markdown`解析器增强** — 新增 `RawInlineNode` 类型和 `_resolveRawInlines` 方法，支持列表项内行内解析（粗体、链接等）；`paragraph` 渲染增加 `md-p` CSS 类；新增 `span` 节点类型渲染；新增粗体 CSS 样式
+5. **`Dashboard CSS` 变量修复** — `border-radius` 使用 `--aithe-container-radius-lg` 替代硬编码 `--aithe-radius-lg`
+6. **`publish.js` 跨平台兼容** — Windows 平台下 spawn 增加 `shell: true` 选项
+7. **文档同步更新** — `aithe-tree-menu`、`aithe-sidebar`、`aithe-dropdown` API 文档更新 `item-filter` 属性描述，新增 `hasPermission` 字段说明
+8. **Sonar 技术债务清理** — 共修复 11 处 Sonar 问题：`code.ts` LaTeX 字符串改用 `String.raw`；`code-editor.ts` 移除冗余类型断言；`form-item.ts` 合并 `querySelector` 泛型；`affix.ts`/`back-top.ts` 移除多余 `as EventListener` 断言；`theme-preview.ts`/`theme-switch.ts` 移除冗余类型断言；`dedup.ts`/`LoggerCore.ts`/`index.ts` 移除冗余断言；`plugins.ts` 所有 `String.match()` 替换为 `RegExp.exec()`
+
+### Issue 26.3.1.0 — Feature (2026-06-15)
+
+1. **aithe-tree-menu 伸缩功能** — 新增 `collapsible`、`collapsed`、`collapsed-width`、`expanded-width` 属性，支持侧边栏收起/展开场景；collapsed 状态下隐藏标签和箭头、按钮居中、无图标时显示首字母 fallback；子菜单无浮层效果，正常向下展开
+2. **aithe-sidebar 改用 aithe-tree-menu** — 移除自有菜单渲染逻辑（`renderItems`/`renderIcon`/`toggleExpand`/`selectItem`/`isGroupActive`/`collectKeys` 等），center 区域改用 `<aithe-tree-menu>` 组件；`handleTreeSelect` 仅更新 `this.active`，不再 re-emit（事件 `composed: true` 自动穿透 shadow DOM）
+3. **aithe-dropdown 移除 findItemById** — `handleTreeSelect` 仅关闭面板，不再 re-emit；移除 `findItemById` 递归方法；删除 `src/components/navigation/dropdown.ts` 旧文件
+4. **aithe-theme-switch 用 item.category 替代遍历** — `buildThemeMenu` 给每个子项添加 `category` 字段；`handleTreeSelect` 直接从 `item.category` 读取分类，替代遍历菜单数组
+5. **aithe-admin-layout 移除 findMenuNode** — `handleSidebarSelect` 直接使用事件中的 `item` 对象，移除 `findMenuNode` 递归方法
+6. **aithe-tree-menu 选中背景内缩** — `.item.active` 增加 `padding` 和 `margin`，选中背景不铺满
+7. **aithe-tree-menu selectItem 改为接收 AitheTreeNodeMeta** — `aithe-select` 事件 detail 从 `{ value }` 改为 `{ value, item }`
+8. **Admin 仪表盘取数修复** — `fetchStats` 增加 `AbortController` 防竞态、`disconnectedCallback` 中 abort、loading URL 匹配从 `includes` 改为 `endsWith`、双重解包防御
+9. **文档同步更新** — tree-menu.md、dropdown.md、sidebar.md、theme-switch.md 更新
+
+---
+
+## 概述
+
+Aithe UI 26.3.1 是 2026 年第 3 季度第 1 个月版本，聚焦于组件功能增强与质量提升。本版本在 26.2.3 基线版本的基础上，完成了树形菜单伸缩与事件改造、Filter 数据格式化框架、Table 六项新功能、Autoform 增强、Tabs 溢出折叠、Display 组件系列新增、主题 CSS 变量统一、DataHub 错误处理增强、SSR 环境适配等核心改进，并新增了 7 个 display 组件和 1 个 data 组件。组件数量从 90 个扩展至 98 个。
+
+**26.3.1.7 子版本** 聚焦于 DataHub 错误处理增强（HTTP 非 2xx 错误响应优先用 APIStyle 解析、K8s Status 对象识别）、DataHub/Filter 导入路径规范化、SSR 环境适配（4 个组件 `window` → `globalThis`）、API 文档补充（log-panel/desc-item/autoform-item）。
+
+**26.3.1.6 子版本** 聚焦于 CSS 自定义属性统一（旧命名规范迁移到新规范）、主题系统增强（24 个主题统一新增 8 个 CSS 变量）、`AitheUI` 类浏览器环境检测（10 个 getter）、样式修复。
+
+**26.3.1.5 子版本** 聚焦于 `<aithe-tabs>` 溢出折叠与样式修复、`<aithe-desc>` 描述列表重构（独立 grid 列布局）、`<aithe-box-table>` 卡片表格重构（改用 `<aithe-brief-box>`）、`AitheSelectableType` 类型重构（纯字符串枚举）。
+
+**26.3.1.4 子版本** 聚焦于 `<aithe-table>` 六项新功能（列固定/列宽拖拽/列拖拽排序/loading/单选/键盘导航）、`<aithe-button>` variant 重构、`<aithe-tag>` 尺寸系统、7 个新组件导出、SonarQube 代码质量修复。
+
+**26.3.1.3 子版本** 聚焦于 `<aithe-autoform>` 增强（initial-values/show-submit/submit()）、`<aithe-anchored-overlay>` 含入块偏移修正、事件名统一（`aithe-open-change` → `aithe-dropdown-change`）、原生事件冒泡控制。
+
+**26.3.1.2 子版本** 聚焦于 Filter 数据格式化框架（5 种内置过滤器）、组件集成 filter（metrics/table/table-column）、modal/drawer transform 定位修复、测试框架集成（vitest）。
+
+**26.3.1.1 子版本** 聚焦于 `AitheSidebarItemFilter` → `AitheTreeNodeFilter` 重命名、`aithe-tree-menu` 默认权限过滤、Markdown 解析器增强、Sonar 技术债务清理。
+
+**26.3.1.0 子版本** 聚焦于 `aithe-tree-menu` 伸缩功能、`aithe-sidebar` 改用 `aithe-tree-menu`、`aithe-dropdown` 移除 `findItemById`、`aithe-theme-switch` 用 `item.category` 替代遍历、`aithe-admin-layout` 移除 `findMenuNode`、Admin 仪表盘取数修复。
+
+## 核心特性
+
+### 1. 树形菜单伸缩与事件改造
+
+- **`aithe-tree-menu` 伸缩功能**: 新增 `collapsible`/`collapsed`/`collapsed-width`/`expanded-width` 四个属性，支持侧边栏收起/展开场景
+- **`aithe-sidebar` 改用 `aithe-tree-menu`**: 移除自有菜单渲染逻辑，center 区域改用 `<aithe-tree-menu>` 组件，事件通过 `composed: true` 自动穿透 shadow DOM
+- **`aithe-dropdown` 移除 `findItemById`**: `handleTreeSelect` 仅关闭面板，不再 re-emit
+- **`aithe-theme-switch` 用 `item.category` 替代遍历**: `buildThemeMenu` 给每个子项添加 `category` 字段
+- **`aithe-admin-layout` 移除 `findMenuNode`**: `handleSidebarSelect` 直接使用事件中的 `item` 对象
+- **`aithe-tree-menu` 选中背景内缩**: `.item.active` 增加 `padding` 和 `margin`
+- **`aithe-tree-menu.selectItem` 参数变更**: 从 `key: string` 改为 `item: AitheTreeNodeMeta`，事件 detail 从 `{ value }` 改为 `{ value, item }`
+- **`AitheSidebarItemFilter` → `AitheTreeNodeFilter`**: 类型重命名，语义更通用
+- **`aithe-tree-menu` 默认权限过滤**: 内置 `itemFilter` 默认值检查 `item.hasPermission !== false`
+- **`aithe-dropdown` 新增 `itemFilter` 属性**: 透传给内部 `<aithe-tree-menu>`
+
+### 2. Filter 数据格式化框架
+
+- **轻量 Filter 模块**: `src/core/filter/` 目录下新建 4 个核心文件（types.ts/builtins.ts/factory.ts/index.ts），零第三方依赖
+- **5 种内置过滤器**: `AmountFilter`（金额保留两位小数）、`DateFilter`（日期格式化）、`EmptyFilter`（空值替换）、`BytesFilter`（字节数格式化，IEC/SI 双标准）、`TimeAgoFilter`（时间友好显示）
+- **链式表达式解析**: 支持 `"date yyyy/MM/dd | empty"` 链式过滤
+- **`FilterFactory` 工厂类**: 提供 `register`/`get`/`has`/`names`/`format`/`parse`/`stringify` 方法
+- **组件集成**: `<aithe-metrics>`、`<aithe-table-column>`、`<aithe-table>`、`<aithe-desc>`、`<aithe-desc-item>` 均支持 filter 属性
+- **测试覆盖**: 38 个测试用例全部通过
+
+### 3. Table 六项新功能
+
+- **列固定（`fixed`）**: 使用 `position: sticky` + `left`/`right` 偏移计算，支持固定列阴影指示器
+- **列宽拖拽调整（`resizable`）**: document 级别 mousemove/mouseup 监听，新增 `aithe-column-resize` 事件
+- **列拖拽排序（`draggable`）**: 5px 拖拽阈值，新增 `aithe-column-reorder` 事件
+- **loading 加载占位**: 半透明遮罩层 + 旋转 spinner + shimmer 动画占位行，支持 `loading` 具名插槽
+- **行单选模式（`selectable="single"`）**: 单选使用 radio input，隐藏全选 checkbox
+- **键盘导航**: ArrowDown/ArrowUp 移动焦点行；空格切换选中；Enter 触发行点击；`_scrollRowIntoView` 自动滚动
+- **列固定优化**: 选择列 `selection-cell` 固定左侧，`has-fixed` 属性控制 `table` 的 `min-width: max-content`，修复斑马纹行固定列背景色
+
+### 4. Autoform 增强
+
+- **`initial-values` 属性**: 支持外部初始值覆盖 `dft`
+- **`show-submit` 属性**: 控制内置提交按钮显隐，默认 `true`
+- **`submit()` 方法**: 编程触发表单校验和提交
+- **操作区重构**: 改用 `<aithe-button-group>` 包裹 slot 和内置按钮，slot 与内置按钮共存
+
+### 5. Tabs 溢出折叠
+
+- **`max-visible-tabs` 属性**: tab 数量超出时自动折叠到溢出下拉菜单
+- **`extra` 具名插槽**: 使用 `margin-left: auto` 推至右侧
+- **溢出菜单**: 改用 `<aithe-select>` 组件
+- **样式修复**: 修复 line 模式边框重复、修复 button 模式 icon 前景色
+
+### 6. Display 组件系列
+
+- **`<aithe-mini-box>`**: 迷你卡片组件
+- **`<aithe-brief-box>`**: 简要卡片组件，支持 name/status/tags/actions slot
+- **`<aithe-detail-box>`**: 详情卡片组件，空插槽自动隐藏
+- **`<aithe-profile>`**: 个人资料组件
+- **`<aithe-desc>`**: 描述列表组件，独立 grid 列布局，支持 `content`/`filter` 属性
+- **`<aithe-desc-item>`**: 描述列表项组件，支持 `content`/`filter` 属性
+- **`<aithe-box-table>`**: 卡片式表格组件，改用 `<aithe-brief-box>` 渲染卡片
+
+### 7. 事件名统一
+
+- **`aithe-open-change` → `aithe-dropdown-change`**: `<aithe-dropdown>`、`<aithe-popover>`、`<aithe-tooltip>`、`<aithe-select>` 的开关状态变更事件统一
+- **原生事件冒泡控制**: `<aithe-input>`、`<aithe-textarea>`、`<aithe-code-editor>`、`<aithe-combobox>` 在原生事件处理器中调用 `event.stopPropagation()`
+
+### 8. 主题系统增强
+
+- **CSS 自定义属性统一**: 旧命名规范迁移到新规范（`--aithe-duration-normal` → `--aithe-duration-base`/`--aithe-duration-slow`，`--aithe-container-radius` → `--aithe-container-radius-md`，`--aithe-border-radius-md` → `--aithe-radius-md`，`--aithe-font-mono` → `--aithe-font-family-mono`）
+- **24 个主题统一新增 8 个 CSS 变量**: `--aithe-fill-1`/`--aithe-fill-2`/`--aithe-color-surface-hover`/`--aithe-color-text-secondary`/`--aithe-color-bg-muted`/`--aithe-color-bg-hover`/`--aithe-color-border-subtle`/`--aithe-primary-6-rgb`
+- **字体尺寸变量**: `global.css.ts` 新增 `--aithe-font-size-base`/`--aithe-font-size-3xl`/`--aithe-font-size-4xl`/`--aithe-font-size-5xl`
+
+### 9. AitheUI 浏览器环境检测
+
+- **`_ua` 私有字段**: 构造时缓存 `navigator.userAgent`
+- **10 个 getter**: `isMobile`/`isAndroid`/`isIOS`/`isChrome`/`isEdge`/`isWechat`/`isWindows`/`isMacOS`/`isRealMobile`/`isChromeEmulator`/`supportsTouch`
+
+### 10. DataHub 错误处理增强
+
+- **HTTP 非 2xx 错误响应**: 优先用 APIStyle 解析响应体，提取业务错误信息（code/message）
+- **`DataHubError` 新增 `data` 字段**: 携带原始响应体
+- **K8s APIStyle 错误响应支持**: `k8sStyle.onResponse` 新增对 K8s `Status` 对象的识别
+- **`MockAdapter` 增强**: 新增 `mockPath` 支持，可通过 URL 加载远程 Mock 数据文件
+
+### 11. 类型系统增强
+
+- **`AitheSelectableType`**: 从 `boolean | 'single'` 重构为 `'none' | 'multi' | 'single'` 纯字符串枚举
+- **`AitheColumnFixed`**: 列固定类型
+- **`AitheDataRenderer`**: 数据渲染器类型，`cellRenderer` 签名变更为 `(key, value, record)`
+- **`AitheDataProvider`**: 数据提供者类型
+- **`AitheTreeNodeFilter`**: 从 `AitheSidebarItemFilter` 重命名
+
+### 12. SSR 环境适配
+
+- **`window` → `globalThis`**: `<aithe-log-panel>`、`<aithe-affix>`、`<aithe-back-top>`、`<aithe-theme-switch>` 4 个组件兼容非浏览器环境
+
+### 13. 测试框架集成
+
+- **Vitest**: 安装 `vitest@^4.1.6`，新增 `vitest.config.ts` 配置，添加 `test` / `test:watch` 脚本
+- **Filter 模块测试**: 38 个测试用例全部通过
+
+### 14. SonarQube 代码质量修复
+
+- **26.3.1.1**: 修复 11 处 Sonar 问题（`String.raw`、冗余类型断言、`RegExp.exec()`）
+- **26.3.1.4**: 修复 15+ 项告警（S3358、S6660、S1128、S7761、S4325、S3776、S1854、S2156），更新 `CONTRIBUTING.md` 新增 8 条规则
+- **26.3.1.5**: `<aithe-desc>` 提取 `_getItemContent`/`_findNextPosition`/`_markOccupied` 消除 S3358/S3776 告警；`<aithe-desc-item>` 提取 `renderContent` 消除 S3358 告警
+
+### 15. Markdown 解析器增强
+
+- **`RawInlineNode` 类型**: 支持列表项内行内解析（粗体、链接等）
+- **`_resolveRawInlines` 方法**: 递归遍历 AST 将 `raw-inline` 节点解析为行内 AST 节点
+- **`span` 节点渲染**: 新增 `span` 类型处理
+- **粗体 CSS 样式**: `.md-strong` 样式，`font-weight: 700`
+
+### 16. 定位修复
+
+- **`<aithe-anchored-overlay>` 含入块偏移修正**: 修复 `position:fixed` 面板在 `transform`/`filter` 等祖先元素内定位偏移的问题
+- **`<aithe-modal>` / `<aithe-drawer>` transform 定位修复**: 将 `transform` 动画从 `.panel` 移至内部 `.panel-inner` 包装层
+
+## 破坏性变更汇总
+
+| 变更项 | 旧值 | 新值 | Issue |
+|--------|------|------|-------|
+| `aithe-tree-menu` 的 `aithe-select` 事件 detail | `{ value: string }` | `{ value: string, item: AitheTreeNodeMeta }` | 26.3.1.0 |
+| `aithe-dropdown` 的 `aithe-select` 事件 | 组件 re-emit，detail 含 `{ item, path, id }` | 不再 re-emit，事件由 `aithe-tree-menu` 的 `composed: true` 自动穿透，detail 为 `{ value, item }` | 26.3.1.0 |
+| `aithe-sidebar` 的 `aithe-select` 事件 | 组件 re-emit | 不再 re-emit，事件由 `aithe-tree-menu` 的 `composed: true` 自动穿透 | 26.3.1.0 |
+| `aithe-tree-menu.selectItem` 参数 | `key: string` | `item: AitheTreeNodeMeta` | 26.3.1.0 |
+| `src/components/navigation/dropdown.ts` | 存在（旧版 dropdown） | 删除 | 26.3.1.0 |
+| `AitheSidebarItemFilter` 类型名 | `AitheSidebarItemFilter` | `AitheTreeNodeFilter` | 26.3.1.1 |
+| `aithe-tree-menu.itemFilter` 默认值 | `null`（不过滤） | `(item) => item.hasPermission !== false`（过滤 `hasPermission: false` 的项） | 26.3.1.1 |
+| `<aithe-dropdown>` 开关状态事件名 | `aithe-open-change` | `aithe-dropdown-change` | 26.3.1.3 |
+| `<aithe-popover>` 开关状态事件名 | `aithe-open-change` | `aithe-dropdown-change` | 26.3.1.3 |
+| `<aithe-tooltip>` 开关状态事件名 | `aithe-open-change` | `aithe-dropdown-change` | 26.3.1.3 |
+| `<aithe-select>` 开关状态事件名 | `aithe-open-change` | `aithe-dropdown-change` | 26.3.1.3 |
+| `<aithe-autoform>` slot 行为 | 传入 slot 内容时替换内置提交按钮 | slot 与内置按钮共存，通过 `show-submit` 控制显隐 | 26.3.1.3 |
+| `AitheTableColumnMeta.render` 签名 | `(value, record, rowIndex)` | `(key, value, record)` — 移除 `rowIndex`，新增 `key` 参数 | 26.3.1.4 |
+| `AitheTableColumn.cellRenderer` 签名 | `(value, record, rowIndex)` | `(key, value, record)` — 同上 | 26.3.1.4 |
+| `<aithe-button>` `danger` 属性 | 独立 `@property` | 废弃，改用 `variant="danger"` | 26.3.1.4 |
+| `<aithe-table>` `selectedKeys` 状态 | `string[]` | `selectionSet: Set<string>` | 26.3.1.4 |
+| `<aithe-table>` `aithe-selection-change` 事件载荷 | `{ selectedKeys }` | `{ selectionSet }` | 26.3.1.4 |
+| `<aithe-table>` `renderCell` 方法签名 | `(column, record, rowIndex)` | `(column, record)` — 移除 `rowIndex` 参数 | 26.3.1.4 |
+| `<aithe-desc-item>` `labelWidth` 属性 | 独立 `@property` | 已移除（使用父级 `aithe-desc` 的 `label-width` 统一控制） | 26.3.1.5 |
+| `<aithe-desc>` `labelWidth` 默认值 | `''`（空字符串） | `'150px'` | 26.3.1.5 |
+| `AitheSelectableType` 类型定义 | `boolean \| 'single'` | `'none' \| 'multi' \| 'single'` — 统一为字符串枚举，默认值 `'none'` | 26.3.1.5 |
+| `<aithe-table>` `selectable` 属性默认值 | `false` | `'none'` | 26.3.1.5 |
+| `<aithe-mini-box>` / `<aithe-brief-box>` / `<aithe-detail-box>` `selectable` 属性 | `Boolean`（`true`/`false`） | `AitheSelectableType`（`'none'`/`'multi'`/`'single'`） | 26.3.1.5 |
+
+## 组件详细列表
+
+### 基础组件 (12个)
+
+#### 1. `<aithe-button>` - 按钮
+
+- **类型**: primary、default、dashed、text、link
+- **尺寸**: small、medium、large
+- **状态**: loading、disabled
+- **特性**: 图标支持、块级显示、自定义事件
+- **备注**: 26.3.1.4 废弃 `danger` 属性，改用 `variant="danger"`
+
+#### 2. `<aithe-button-group>` - 按钮组
+
+- **功能**: 按钮组合布局
+- **特性**: 统一间距、对齐方式
+
+#### 3. `<aithe-icon>` - 图标
+
+- **功能**: 矢量图标显示
+- **特性**: 内置图标库、自定义图标、尺寸控制
+
+#### 4. `<aithe-input>` - 输入框
+
+- **类型**: text、password、number、email 等
+- **特性**: 验证状态、前缀后缀、清除按钮
+- **备注**: 26.3.1.3 `handleInput` 和 `handleChange` 中增加 `event.stopPropagation()`
+
+#### 5. `<aithe-textarea>` - 文本域
+
+- **功能**: 多行文本输入
+- **特性**: 自动高度调整、字数统计
+- **备注**: 26.3.1.3 `handleInput` 和 `handleChange` 中增加 `event.stopPropagation()`
+
+#### 6. `<aithe-card>` - 卡片
+
+- **结构**: 标题、内容、操作区域
+- **特性**: 阴影、边框、悬停效果
+
+#### 7. `<aithe-tag>` - 标签
+
+- **类型**: 默认、可关闭、可选择
+- **特性**: 多种颜色、圆角样式
+- **备注**: 26.3.1.4 新增 `size` 属性（sm/md/lg），`type` 标记为 `@deprecated`，推荐使用 `variant`；移除 `min-height` 硬编码
+
+#### 8. `<aithe-badge>` - 徽章
+
+- **类型**: 数字、圆点、状态
+- **特性**: 最大值显示、自定义内容
+
+#### 9. `<aithe-avatar>` - 头像
+
+- **类型**: 图片、文字、图标
+- **特性**: 尺寸控制、形状、组头像
+
+#### 10. `<aithe-divider>` - 分割线
+
+- **方向**: 水平、垂直
+- **特性**: 文字位置、虚线样式
+
+#### 11. `<aithe-empty>` - 空状态
+
+- **功能**: 数据为空时的占位显示
+- **特性**: 自定义图标、描述、操作按钮
+
+#### 12. `<aithe-chip>` - 芯片
+
+- **功能**: 紧凑的可选择标签
+- **特性**: 可关闭、可选择、多种颜色
+
+### 布局组件 (10个)
+
+#### 13. `<aithe-container>` - 容器
+
+- **类型**: fluid、fixed、full
+- **特性**: 响应式断点、内边距控制
+
+#### 14. `<aithe-row>` - 行
+
+- **功能**: 24 栅格系统的行容器
+- **特性**: 栅格间隔、对齐方式、换行控制
+
+#### 15. `<aithe-col>` - 列
+
+- **功能**: 24 栅格系统的列
+- **特性**: 响应式断点、偏移、排序
+
+#### 16. `<aithe-flex>` - 弹性布局
+
+- **功能**: 快速弹性布局容器
+- **特性**: 方向、对齐、换行、间距
+
+#### 17. `<aithe-space>` - 间距
+
+- **功能**: 子元素等间距布局
+- **特性**: 方向、大小、对齐
+
+#### 18. `<aithe-page-container>` - 页面容器
+
+- **功能**: 标准页面外壳
+- **特性**: 标题区域、内容区域、页脚区域
+
+#### 19. `<aithe-page>` - 页面
+
+- **功能**: 完整页面布局
+- **特性**: 头部、侧边栏、内容区、页脚
+
+#### 20. `<aithe-collapse>` - 折叠面板
+
+- **类型**: 手风琴、多展开
+- **特性**: 边框样式、图标位置
+
+#### 21. `<aithe-collapse-item>` - 折叠项
+
+- **功能**: 单个可折叠面板
+- **特性**: 标题、内容、禁用状态
+
+#### 22. `<aithe-affix>` - 固钉
+
+- **功能**: 滚动时固定元素
+- **特性**: 偏移量、目标容器、回调事件
+- **备注**: 26.3.1.7 `window.addEventListener/removeEventListener` → `globalThis`
+
+### 导航组件 (6个)
+
+#### 23. `<aithe-menu>` - 菜单
+
+- **模式**: 垂直、水平、内联
+- **特性**: 主题、选中状态、展开控制
+
+#### 24. `<aithe-menu-item>` - 菜单项
+
+- **功能**: 单个菜单项
+- **特性**: 图标、禁用状态、选中状态
+
+#### 25. `<aithe-sub-menu>` - 子菜单
+
+- **功能**: 可展开的子菜单
+- **特性**: 标题、图标、展开状态
+
+#### 26. `<aithe-breadcrumb>` - 面包屑
+
+- **功能**: 页面层级导航
+- **特性**: 分隔符、最大显示数量
+
+#### 27. `<aithe-breadcrumb-item>` - 面包屑项
+
+- **功能**: 单个面包屑项
+- **特性**: 链接、分隔符、当前项
+
+#### 28. `<aithe-steps>` - 步骤条
+
+- **方向**: 水平、垂直
+- **特性**: 当前步骤、状态、自定义图标
+
+#### 29. `<aithe-back-top>` - 回到顶部
+
+- **功能**: 滚动到页面顶部
+- **特性**: 可见阈值、自定义位置、动画
+- **备注**: 26.3.1.7 `window.scrollY`/`window.scrollTo` → `globalThis`
+
+### 表单组件 (18个)
+
+#### 30. `<aithe-checkbox>` - 复选框
+
+- **功能**: 单个复选框
+- **特性**: 中间状态、禁用、自定义标签
+
+#### 31. `<aithe-checkbox-group>` - 复选框组
+
+- **功能**: 多个复选框组合
+- **特性**: 方向、最大选择数、全选
+
+#### 32. `<aithe-radio>` - 单选框
+
+- **功能**: 单个单选框
+- **特性**: 禁用状态、自定义标签
+
+#### 33. `<aithe-radio-group>` - 单选框组
+
+- **功能**: 多个单选框组合
+- **特性**: 方向、按钮样式、禁用状态
+
+#### 34. `<aithe-select>` - 选择器
+
+- **模式**: 单选、多选、标签模式
+- **特性**: 搜索、过滤、远程数据、分组
+- **备注**: 26.3.1.3 开关状态事件名从 `aithe-open-change` 改为 `aithe-dropdown-change`
+
+#### 35. `<aithe-switch>` - 开关
+
+- **功能**: 开关切换
+- **特性**: 大小、加载状态、自定义内容
+
+#### 36. `<aithe-color-picker>` - 颜色选择器
+
+- **模式**: 简单、高级
+- **特性**: 预设颜色、透明度、格式输出
+
+#### 37. `<aithe-combobox>` - 组合框
+
+- **功能**: 可搜索的下拉框
+- **特性**: 自动完成、远程搜索、多选
+- **备注**: 26.3.1.3 `handleInput` 中增加 `event.stopPropagation()`
+
+#### 38. `<aithe-date-picker>` - 日期选择器
+
+- **类型**: 日期、周、月、年、范围
+- **特性**: 快捷选择、禁用日期、自定义格式
+
+#### 39. `<aithe-time-picker>` - 时间选择器
+
+- **功能**: 时间选择
+- **特性**: 步长、格式、禁用时间
+
+#### 40. `<aithe-slider>` - 滑块
+
+- **类型**: 单滑块、范围滑块
+- **特性**: 步长、标记点、垂直模式
+
+#### 41. `<aithe-rate>` - 评分
+
+- **功能**: 星级评分
+- **特性**: 半星、自定义图标、只读
+
+#### 42. `<aithe-form>` - 表单
+
+- **功能**: 表单容器
+- **特性**: 验证、布局、提交处理
+
+#### 43. `<aithe-form-item>` - 表单项
+
+- **功能**: 表单字段包装器
+- **特性**: 标签、验证信息、布局
+
+#### 44. `<aithe-upload>` - 上传
+
+- **模式**: 点击上传、拖拽上传
+- **特性**: 多文件、限制、预览、自定义请求
+
+#### 45. `<aithe-transfer>` - 穿梭框
+
+- **功能**: 双列表数据转移
+- **特性**: 搜索、分页、自定义渲染
+
+#### 46. `<aithe-autoform>` - 自动表单
+
+- **功能**: JSON 配置驱动的自动渲染表单组件
+- **特性**: 13 种内置控件类型、自定义控件注册表、实时校验和提交校验
+- **备注**: 26.3.1.3 新增 `initial-values`/`show-submit` 属性、`submit()` 方法；操作区改用 `<aithe-button-group>`
+
+#### 47. `<aithe-autoform-item>` - 自动表单项
+
+- **功能**: 表单项容器组件，三段式布局（header + control + footer）
+- **备注**: 26.3.1.6 `box-shadow` 中 `--aithe-primary-6-rgb` 回退值修正
+
+### 反馈组件 (9个)
+
+#### 48. `<aithe-dialog>` - 对话框
+
+- **功能**: 模态对话框
+- **特性**: 标题、内容、操作按钮、关闭控制
+
+#### 49. `<aithe-modal>` - 模态框
+
+- **功能**: 轻量级模态框
+- **特性**: 多种尺寸、全屏、自定义内容
+- **备注**: 26.3.1.2 `transform` 动画从 `.panel` 移至内部 `.panel-inner` 包装层
+
+#### 50. `<aithe-drawer>` - 抽屉
+
+- **位置**: 上、下、左、右
+- **特性**: 大小、标题、遮罩、关闭控制
+- **备注**: 26.3.1.2 `transform` 动画从 `.panel` 移至内部 `.panel-inner` 包装层
+
+#### 51. `<aithe-tooltip>` - 工具提示
+
+- **位置**: 12 个方向
+- **特性**: 延迟显示、主题、自定义内容
+- **备注**: 26.3.1.3 开关状态事件名从 `aithe-open-change` 改为 `aithe-dropdown-change`
+
+#### 52. `<aithe-popover>` - 弹出框
+
+- **功能**: 点击触发的弹出内容
+- **特性**: 触发方式、位置、箭头
+- **备注**: 26.3.1.3 开关状态事件名从 `aithe-open-change` 改为 `aithe-dropdown-change`
+
+#### 53. `<aithe-toast>` - 轻提示
+
+- **类型**: 成功、警告、错误、信息
+- **特性**: 自动关闭、位置、自定义持续时间
+
+#### 54. `<aithe-alert>` - 警告提示
+
+- **类型**: 成功、信息、警告、错误
+- **特性**: 可关闭、图标、描述
+
+#### 55. `<aithe-notification>` - 通知提醒框
+
+- **功能**: 全局通知
+- **特性**: 位置、持续时间、自定义按钮
+
+#### 56. `<aithe-loading>` - 加载中
+
+- **类型**: 全屏、容器、内联
+- **特性**: 自定义文本、延迟显示
+
+### 数据展示组件 (13个)
+
+#### 57. `<aithe-table>` - 表格
+
+- **功能**: 数据表格
+- **特性**: 排序、筛选、分页、选择、虚拟滚动
+- **备注**: 26.3.1.2 集成 filter；26.3.1.4 新增列固定、列宽拖拽调整、列拖拽排序、loading 加载占位、行单选模式、键盘导航；`selectedKeys` → `selectionSet`；`renderCell` 签名移除 `rowIndex`；26.3.1.5 `selectable` 默认值 `false` → `'none'`；选择列固定左侧
+
+#### 58. `<aithe-table-column>` - 表格列
+
+- **功能**: 声明式表格列定义
+- **特性**: 字段映射、排序、对齐、宽度
+- **备注**: 26.3.1.2 新增 `filter` 属性；26.3.1.4 新增 `fixed`/`resizable`/`draggable`/`min-width`/`box` 属性；`cellRenderer` 签名变更为 `(key, value, record)`
+
+#### 59. `<aithe-tabs>` - 标签页
+
+- **类型**: 线型、卡片型
+- **特性**: 位置、大小、可关闭、懒加载
+- **备注**: 26.3.1.5 新增 `max-visible-tabs` 溢出折叠、`extra` 具名插槽；修复 line 模式边框重复、button 模式 icon 前景色
+
+#### 60. `<aithe-tab-pane>` - 标签页面板
+
+- **功能**: 单个标签页内容
+- **特性**: 禁用、懒加载、图标
+- **备注**: 26.3.1.5 注释增强，所有属性扩展为多行双语注释
+
+#### 61. `<aithe-tree>` - 树形控件
+
+- **功能**: 层级数据展示
+- **特性**: 选择、展开、搜索、拖拽
+
+#### 62. `<aithe-tree-menu>` - 树形菜单
+
+- **功能**: 基于 Tree 数据的菜单导航
+- **特性**: 递归渲染、意图着色、垂直/水平布局
+- **备注**: 26.3.1.0 新增 `collapsible`/`collapsed`/`collapsed-width`/`expanded-width` 属性；`selectItem` 参数从 `key: string` 改为 `item: AitheTreeNodeMeta`；事件 detail 从 `{ value }` 改为 `{ value, item }`；选中背景内缩；26.3.1.1 `itemFilter` 默认值改为 `(item) => item.hasPermission !== false`
+
+#### 63. `<aithe-timeline>` - 时间线
+
+- **模式**: 垂直、水平
+- **特性**: 自定义节点、颜色、图标、数据驱动模式
+
+#### 64. `<aithe-timeline-item>` - 时间线项
+
+- **功能**: 单个时间线节点
+- **特性**: 时间、内容、状态
+
+#### 65. `<aithe-pagination>` - 分页
+
+- **功能**: 数据分页
+- **特性**: 大小选择、快速跳转、简洁模式
+
+#### 66. `<aithe-dropdown>` - 下拉菜单
+
+- **功能**: 下拉菜单容器
+- **特性**: 触发方式、位置、禁用状态
+- **备注**: 26.3.1.0 移除 `findItemById`，`handleTreeSelect` 不再 re-emit；26.3.1.1 新增 `itemFilter` 属性；26.3.1.3 开关状态事件名从 `aithe-open-change` 改为 `aithe-dropdown-change`
+
+#### 67. `<aithe-metrics>` - 指标
+
+- **功能**: 指标展示组件，支持标签和数值展示
+- **特性**: 自定义标签、数值、趋势指示
+- **备注**: 26.3.1.2 `MetricsData` 接口新增 `filter` 字段
+
+#### 68. `<aithe-metrics-group>` - 指标组
+
+- **功能**: 分组指标容器
+- **特性**: 水平/垂直排列、分组展示
+
+#### 69. `<aithe-box-table>` - 卡片表格 *(26.3.1.4 新增)*
+
+- **功能**: 卡片式表格组件
+- **特性**: 卡片布局、选择模式
+- **备注**: 26.3.1.5 重构为改用 `<aithe-brief-box>` 渲染卡片，移除自建卡片 DOM
+
+### 展示组件 (13个)
+
+#### 70. `<aithe-carousel>` - 走马灯
+
+- **功能**: 轮播图
+- **特性**: 自动播放、指示器、箭头、切换效果
+
+#### 71. `<aithe-comparison>` - 对比
+
+- **功能**: 前后对比滑块
+- **特性**: 方向、手柄样式、标签
+
+#### 72. `<aithe-animated-image>` - 动画图片
+
+- **功能**: 带动画的图片显示
+- **特性**: 缩放、平移、加载动画
+
+#### 73. `<aithe-markdown>` - Markdown 渲染
+
+- **功能**: Markdown 内容渲染
+- **特性**: 语法高亮、自定义渲染器
+- **备注**: 26.3.1.1 Markdown 解析器增强，新增 `RawInlineNode`/`_resolveRawInlines`/`span` 节点渲染
+
+#### 74. `<aithe-code-editor>` - 代码编辑器
+
+- **功能**: 代码显示与编辑组件
+- **特性**: 语法高亮（38 种语言）、行号显示、一键复制、代码折叠
+- **备注**: 26.3.1.3 `handleInput` 中增加 `e.stopPropagation()`
+
+#### 75. `<aithe-markdown-editor>` - Markdown 编辑器
+
+- **功能**: Markdown 编辑与实时预览
+- **特性**: 分屏模式、实时预览
+
+#### 76. `<aithe-label>` - 标签
+
+- **功能**: 标签展示组件
+- **特性**: filled/outlined 变体、多种颜色、可移除、图标支持
+
+#### 77. `<aithe-mini-box>` - 迷你卡片 *(26.3.1.4 新增)*
+
+- **功能**: 迷你卡片组件
+- **特性**: 紧凑布局、选择模式
+- **备注**: 26.3.1.5 `selectable` 从 `Boolean` 改为 `AitheSelectableType`；26.3.1.6 hover 背景色移除嵌套回退
+
+#### 78. `<aithe-brief-box>` - 简要卡片 *(26.3.1.4 新增)*
+
+- **功能**: 简要卡片组件
+- **特性**: name/status/tags/actions slot、选择模式
+- **备注**: 26.3.1.5 `selectable` 从 `Boolean` 改为 `AitheSelectableType`；操作区样式修复
+
+#### 79. `<aithe-detail-box>` - 详情卡片 *(26.3.1.4 新增)*
+
+- **功能**: 详情卡片组件
+- **特性**: content/actions slot、空插槽自动隐藏
+- **备注**: 26.3.1.5 新增 `_hasContent`/`_hasActions` 状态，空插槽自动 `hidden`；`selectable` 从 `Boolean` 改为 `AitheSelectableType`
+
+#### 80. `<aithe-profile>` - 个人资料 *(26.3.1.4 新增)*
+
+- **功能**: 个人资料组件
+- **特性**: 头像、信息展示
+
+#### 81. `<aithe-desc>` - 描述列表 *(26.3.1.4 新增)*
+
+- **功能**: 描述列表组件
+- **特性**: 水平/垂直布局、独立 grid 列、`content`/`filter` 属性
+- **备注**: 26.3.1.5 布局算法重构（独立 grid 列）、`label-width` 默认值改为 `150px`；26.3.1.6 样式重构
+
+#### 82. `<aithe-desc-item>` - 描述列表项 *(26.3.1.4 新增)*
+
+- **功能**: 描述列表项组件
+- **特性**: `content`/`filter` 属性
+- **备注**: 26.3.1.5 新增 `content`/`filter` 属性，移除 `labelWidth` 属性；26.3.1.6 样式清理
+
+### 进度组件 (4个)
+
+#### 83. `<aithe-progress-bar>` - 进度条
+
+- **类型**: 线型、环形、仪表盘
+- **特性**: 颜色、条纹动画、自定义文本
+
+#### 84. `<aithe-progress-ring>` - 环形进度条
+
+- **功能**: 环形进度显示
+- **特性**: 大小、宽度、颜色渐变
+
+#### 85. `<aithe-spinner>` - 加载旋转器
+
+- **类型**: 旋转、脉冲、波浪
+- **特性**: 大小、颜色、速度
+
+#### 86. `<aithe-skeleton>` - 骨架屏
+
+### 容器组件 (4个)
+
+#### 87. `<aithe-callout>` - 提示框
+
+- **类型**: 信息、成功、警告、错误
+- **特性**: 图标、标题、可关闭
+
+#### 88. `<aithe-details>` - 详情
+
+- **功能**: 可展开的详情区域
+- **特性**: 摘要、展开状态、禁用
+
+#### 89. `<aithe-scroller>` - 滚动容器
+
+- **功能**: 自定义滚动区域
+- **特性**: 虚拟滚动、懒加载、滚动事件
+
+#### 90. `<aithe-split-panel>` - 分割面板
+
+### 主题组件 (7个)
+
+#### 91. `<aithe-theme-picker>` - 主题选择器
+
+- **功能**: 主题选择器，支持 Light/Dark 分组展示
+- **特性**: 色点预览、键盘导航、`aithe-theme-change` 事件
+
+#### 92. `<aithe-theme-preview>` - 主题预览
+
+- **功能**: 主题预览面板，支持局部预览 + 确认应用全局主题
+- **特性**: 工具栏、预览区、`aithe-theme-apply` 事件
+
+#### 93. `<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` 事件
+
+#### 94. `<aithe-shadow-picker>` - 阴影选择器
+
+- **功能**: 阴影风格选择器，支持 9 种内置阴影风格切换
+- **特性**: 浮层下拉、图标预览、i18n 支持、`placement` 属性控制弹出方向
+
+#### 95. `<aithe-typo-picker>` - 排版风格选择器
+
+- **功能**: 排版风格选择器，支持 4 种内置排版风格切换（minimal/business/luxury/compact）
+- **特性**: 浮层下拉、图标预览、i18n 支持、`placement` 属性控制弹出方向
+
+#### 96. `<aithe-shape-picker>` - 形状风格选择器
+
+- **功能**: 形状风格选择器，支持 8 种内置形状风格切换
+- **特性**: 委托 `<aithe-tree-menu>` 渲染、预览缩略图、键盘导航
+
+#### 97. `<aithe-theme-switch>` - 统一外观切换器
+
+- **功能**: 统一外观切换器组件，一键切换主题/形状/阴影/排版
+- **特性**: 整合 theme-picker、shape-picker、shadow-picker、typo-picker 为一体
+- **备注**: 26.3.1.0 用 `item.category` 替代遍历；26.3.1.7 `window` → `globalThis`
+
+### 框架组件 (3个)
+
+#### 98. `<aithe-sidebar>` - 侧边栏
+
+- **功能**: 侧边栏组件
+- **特性**: 菜单导航、伸缩模式
+- **备注**: 26.3.1.0 改用 `<aithe-tree-menu>` 组件，移除自有菜单渲染逻辑；26.3.1.1 `AitheSidebarItemFilter` → `AitheTreeNodeFilter`；26.3.1.6 新增 `browserEnv` 导入
+
+#### 99. `<aithe-dashboard>` - 仪表盘
+
+- **功能**: 拖拽式仪表盘组件
+- **特性**: CSS Grid 布局、面板拖拽交换、面板调整大小、状态持久化
+- **备注**: 26.3.1.1 CSS `border-radius` 使用 `--aithe-container-radius-lg`；26.3.1.6 `--aithe-duration-normal` → `--aithe-duration-slow`/`--aithe-duration-base`
+
+#### 100. `<aithe-log-panel>` - 日志面板
+
+- **功能**: 日志可视化面板
+- **特性**: overlay/inline 布局、级别过滤、搜索、复制
+- **备注**: 26.3.1.7 `window.innerHeight` → `globalThis.innerHeight`
+
+## 技术架构
+
+### 核心基类
+
+- **AitheElement**: 所有组件的基类，提供统一的属性、事件和样式管理
+- **主题系统**: 基于 CSS 自定义属性的主题切换机制
+- **工具函数**: DOM 操作、事件处理、验证工具
+- **浏览器环境检测**: `AitheUI` 类新增 10 个浏览器环境检测 getter（26.3.1.6 新增）
+
+### 样式系统
+
+- **设计令牌**: 统一的颜色、间距、字体、阴影等设计变量
+- **CSS 自定义属性统一**: 旧命名规范迁移到新规范（26.3.1.6）
+- **24 个主题统一新增 8 个 CSS 变量**: `--aithe-fill-1`/`--aithe-fill-2`/`--aithe-color-surface-hover`/`--aithe-color-text-secondary`/`--aithe-color-bg-muted`/`--aithe-color-bg-hover`/`--aithe-color-border-subtle`/`--aithe-primary-6-rgb`（26.3.1.6）
+- **字体尺寸变量**: `--aithe-font-size-base`/`--aithe-font-size-3xl`/`--aithe-font-size-4xl`/`--aithe-font-size-5xl`（26.3.1.6）
+- **响应式**: 基于 CSS 媒体查询的响应式设计
+- **主题切换**: 通过 CSS 类名切换主题
+
+### Filter 数据格式化框架
+
+- **轻量模块**: `src/core/filter/`，零第三方依赖（26.3.1.2 新增）
+- **5 种内置过滤器**: AmountFilter、DateFilter、EmptyFilter、BytesFilter、TimeAgoFilter
+- **链式表达式**: 支持 `"date yyyy/MM/dd | empty"` 链式过滤
+- **`FilterFactory` 工厂类**: `register`/`get`/`has`/`names`/`format`/`parse`/`stringify`
+- **组件集成**: `<aithe-metrics>`、`<aithe-table-column>`、`<aithe-table>`、`<aithe-desc>`、`<aithe-desc-item>`
+
+### DataHub 数据中间层
+
+- **错误处理增强**: HTTP 非 2xx 错误响应优先用 APIStyle 解析响应体（26.3.1.7）
+- **K8s APIStyle 错误响应支持**: `k8sStyle.onResponse` 新增对 K8s `Status` 对象的识别（26.3.1.7）
+- **`DataHubError` 新增 `data` 字段**: 携带原始响应体（26.3.1.7）
+- **`MockAdapter` 增强**: 新增 `mockPath` 支持（26.3.1.2）
+- **导入路径规范化**: datahub 模块内 `../` 跨目录相对路径统一改为 `@core/datahub/*` 别名（26.3.1.7）
+
+### 构建系统
+
+- **Vite**: 快速的开发服务器和构建工具
+- **TypeScript**: 完整的类型定义支持
+- **Lit 3.x**: 现代 Web Components 开发框架
+- **tsc-alias**: 构建后自动替换 `.d.ts` 中的别名为相对路径
+- **litExternalPlugin**: Vite 插件将 lit 标记为外部依赖
+- **Vitest**: 测试框架，`vitest@^4.1.6`（26.3.1.2 新增）
+
+### 路径别名体系
+
+- **`@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**: 单元测试框架（26.3.1.2 新增）
+- **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>;
+```
+
+### 主题、形状、阴影设置
+
+```javascript
+import { aitheUI } from 'aithe-ui';
+
+// 设置全局主题
+aitheUI.setTheme('dark');
+
+// 设置形状风格
+aitheUI.setShape('rounded');
+
+// 设置阴影风格
+aitheUI.setShadow('neumorphism');
+```
+
+### Filter 数据格式化
+
+```javascript
+import { filterFactory } from 'aithe-ui';
+
+// 注册自定义过滤器
+filterFactory.register('myFilter', {
+  name: 'myFilter',
+  apply: (value) => `¥${value}`,
+});
+
+// 在组件中使用
+// <aithe-table-column filter="amount"></aithe-table-column>
+// <aithe-metrics .data=${{ label: '金额', value: 1234.5, filter: 'amount' }}></aithe-metrics>
+```
+
+## 浏览器支持
+
+- Chrome 61+
+- Firefox 63+
+- Safari 10.1+
+- Edge 79+
+- iOS Safari 10.3+
+- Android Chrome 61+
+
+## 性能特点
+
+- **Tree-shaking 支持**: 支持按需导入
+- **零运行时依赖**: 仅依赖 Lit 库
+- **轻量级**: 组件按需加载
+- **服务端渲染友好**: 支持 SSR/SSG（26.3.1.7 增强）
+
+## 后续版本规划
+
+### 26.3.x (2026年第3季度)
+
+- 组件性能优化
+- 新增高级表单组件
+- 单元测试覆盖率提升
+
+### 26.4.x (2026年第4季度)
+
+- 响应式布局增强
+- 动画系统改进
+- 开发者工具集成
+- 主题定制工具
+
+## 许可证
+
+MIT License - Archest 团队