@aithe/aithe-ui 26.2.2

package/docs/changelog/VERSION_26.2.2.md

@@ -0,0 +1,608 @@
+# Aithe UI 26.2.2 版本详细说明
+
+## 版本信息
+
+- **版本号**: 26.2.2
+- **发布日期**: 2026-05-09
+- **版本类型**: 基线版本
+- **版本描述**: 2026年第2季度第2个月版本 - 基础组件库完整发布
+
+## 版本变更记录
+
+### Issue 26.2.2.4 — Feature / i18n (2026-05-12)
+
+1. 新增国际化（i18n）核心框架：`src/core/i18n/`，支持 `en-US` / `zh-CN` 两种语言（BCP 47 标准）
+2. 新增 `aithe-locale-switch` 语言切换组件（主题分类），基于 dropdown 浮层模式
+3. 19 个含硬编码文本的组件全部接入 `t()` 翻译函数
+4. 核心库与应用层翻译分离：`registerAitheTranslations()` 支持用户注册自定义翻译资源
+5. Demo / API 应用均集成 i18n，顶栏提供语言切换入口
+6. 修复 SonarQube 问题：S6551（模板字面量占位符）、S2933（readonly 修饰符）、S1854（无用赋值）、S1481（未使用变量）、S3776（认知复杂度）
+7. 为所有新增/修改代码添加中英文双语注释
+8. 新增 API 文档：`docs/api/theme/locale-switch.md`
+
+### Issue 26.2.2.3 — Quality / Bug Fix (2026-05-11)
+
+1. 新增 ESLint + Prettier 代码质量工具链，配置 SonarJS 规则集
+2. 修复所有 ESLint errors 和 warnings（嵌套三元表达式、未使用导入、慢正则、嵌套模板字面量）
+3. 为所有箭头函数类属性添加 `readonly` 修饰符（SonarQube S2933）
+4. 修复 Badge 组件角标无法显示、定位偏移、value=0 行为错误等 Bug
+5. 修正 Badge 示例代码属性名错误（`count` → `value`）
+6. 全量 Prettier 格式化
+
+### Issue 26.2.2.2 — Feature (2026-05-11)
+
+1. 新增 `aithe-theme-picker` 主题选择器组件
+2. 新增 `aithe-theme-preview` 主题预览组件
+3. 内置主题从 4 个扩展至 22 个（Light 系 11 个 + Dark 系 11 个）
+4. `aithe-dropdown` 从 feedback 分类迁移至 navigation 分类
+5. Blue 主题从 Dark 系调整为 Light 系
+
+### Issue 26.2.2.1 — Patch (2026-05-11)
+
+1. 数据驱动组件唯一标识字段统一为 `id`（`key`/`value` → `id`）
+2. 数据驱动组件意图属性统一为 `intent`（`style` → `intent`）
+3. `aithe-tree-menu` 新增 `direction` 属性，支持水平布局
+4. `aithe-timeline` / `aithe-timeline-item` 从 layout 迁移至 data 分类
+5. 新增 `aithe-table-column` 子组件
+6. 新增 `aithe-tree-menu` 组件
+
+---
+
+## 概述
+
+Aithe UI 26.2.2 是项目的第一个正式发布版本，提供了完整的 Web Components 组件库，包含 79 个可复用的 UI 组件（含 26.2.2.1~.4 新增的 5 个组件）。本版本基于 Lit 3.x 构建，采用现代 Web 标准，支持跨框架使用。
+
+## 核心特性
+
+### 1. 跨框架兼容性
+
+- **Web Components 标准**: 所有组件均基于 Custom Elements v1 标准
+- **框架无关**: 可在 React、Vue、Angular、Svelte 及原生 JavaScript 中使用
+- **Shadow DOM**: 每个组件都有独立的样式作用域，避免样式冲突
+- **自定义事件**: 统一的事件命名规范 (`aithe-*` 前缀)
+
+### 2. 多主题系统
+
+- **内置主题**: 22 种预设主题（Light 系 11 个 + Dark 系 11 个）
+- **主题选择器**: `aithe-theme-picker` 组件，支持分组展示、色点预览、键盘导航
+- **主题预览**: `aithe-theme-preview` 组件，支持局部预览 + 确认应用全局主题
+- **主题切换**: 支持全局主题切换和单个组件主题覆盖
+- **CSS 自定义属性**: 基于 CSS 变量的主题系统，易于扩展
+- **持久化存储**: 主题选择自动保存到 localStorage
+
+### 3. 无障碍访问
+
+- **ARIA 属性**: 所有组件都包含适当的 ARIA 语义
+- **键盘导航**: 支持完整的键盘操作
+- **焦点管理**: 合理的焦点顺序和焦点陷阱
+- **屏幕阅读器支持**: 优化的屏幕阅读器体验
+
+### 4. 企业级功能
+
+- **表单验证**: 内置表单验证系统
+- **数据表格**: 支持排序、分页、选择的数据表格
+- **布局系统**: 基于 24 栅格的响应式布局
+- **国际化准备**: 支持多语言文本的结构设计
+
+### 5. 国际化（i18n）
+
+- **核心框架**: `src/core/i18n/` 模块，提供 `t()` 翻译函数、语言注册、语言切换订阅
+- **内置语言**: `en-US`（英语）、`zh-CN`（简体中文），遵循 BCP 47 标准
+- **语言切换组件**: `aithe-locale-switch`，基于 dropdown 浮层模式，支持键盘导航
+- **用户扩展**: `registerAitheTranslations()` 支持应用层注册自定义翻译资源
+- **持久化存储**: 语言选择自动保存到 localStorage，兼容旧版 `'en'`/`'zh'` 值自动迁移
+
+## 组件详细列表
+
+### 基础组件 (12个)
+
+#### 1. `<aithe-button>` - 按钮
+
+- **类型**: primary、default、dashed、text、link
+- **尺寸**: small、medium、large
+- **状态**: loading、disabled、danger
+- **特性**: 图标支持、块级显示、自定义事件
+
+#### 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>` - 芯片
+
+- **功能**: 紧凑的可选择标签
+- **特性**: 可关闭、可选择、多种颜色
+
+### 布局组件 (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>` - 固钉
+
+- **功能**: 滚动时固定元素
+- **特性**: 偏移量、目标容器、回调事件
+
+### 导航组件 (8个)
+
+#### 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>` - 回到顶部
+
+- **功能**: 滚动到页面顶部
+- **特性**: 可见阈值、自定义位置、动画
+
+#### 30. `<aithe-dropdown>` - 下拉菜单
+
+- **功能**: 下拉菜单容器
+- **特性**: 触发方式、位置、禁用状态
+- **备注**: 26.2.2.2 从 feedback 分类迁移至 navigation 分类
+
+### 表单组件 (16个)
+
+#### 32. `<aithe-checkbox>` - 复选框
+
+- **功能**: 单个复选框
+- **特性**: 中间状态、禁用、自定义标签
+
+#### 33. `<aithe-checkbox-group>` - 复选框组
+
+- **功能**: 多个复选框组合
+- **特性**: 方向、最大选择数、全选
+
+#### 34. `<aithe-radio>` - 单选框
+
+- **功能**: 单个单选框
+- **特性**: 禁用状态、自定义标签
+
+#### 35. `<aithe-radio-group>` - 单选框组
+
+- **功能**: 多个单选框组合
+- **特性**: 方向、按钮样式、禁用状态
+
+#### 36. `<aithe-select>` - 选择器
+
+- **模式**: 单选、多选、标签模式
+- **特性**: 搜索、过滤、远程数据、分组
+
+#### 37. `<aithe-switch>` - 开关
+
+- **功能**: 开关切换
+- **特性**: 大小、加载状态、自定义内容
+
+#### 38. `<aithe-color-picker>` - 颜色选择器
+
+- **模式**: 简单、高级
+- **特性**: 预设颜色、透明度、格式输出
+
+#### 39. `<aithe-combobox>` - 组合框
+
+- **功能**: 可搜索的下拉框
+- **特性**: 自动完成、远程搜索、多选
+
+#### 40. `<aithe-date-picker>` - 日期选择器
+
+- **类型**: 日期、周、月、年、范围
+- **特性**: 快捷选择、禁用日期、自定义格式
+
+#### 41. `<aithe-time-picker>` - 时间选择器
+
+- **功能**: 时间选择
+- **特性**: 步长、格式、禁用时间
+
+#### 42. `<aithe-slider>` - 滑块
+
+- **类型**: 单滑块、范围滑块
+- **特性**: 步长、标记点、垂直模式
+
+#### 43. `<aithe-rate>` - 评分
+
+- **功能**: 星级评分
+- **特性**: 半星、自定义图标、只读
+
+#### 44. `<aithe-form>` - 表单
+
+- **功能**: 表单容器
+- **特性**: 验证、布局、提交处理
+
+#### 45. `<aithe-form-item>` - 表单项
+
+- **功能**: 表单字段包装器
+- **特性**: 标签、验证信息、布局
+
+#### 46. `<aithe-upload>` - 上传
+
+- **模式**: 点击上传、拖拽上传
+- **特性**: 多文件、限制、预览、自定义请求
+
+#### 47. `<aithe-transfer>` - 穿梭框
+
+- **功能**: 双列表数据转移
+- **特性**: 搜索、分页、自定义渲染
+
+### 反馈组件 (9个)
+
+#### 31. `<aithe-dialog>` - 对话框
+
+- **功能**: 模态对话框
+- **特性**: 标题、内容、操作按钮、关闭控制
+
+#### 32. `<aithe-modal>` - 模态框
+
+- **功能**: 轻量级模态框
+- **特性**: 多种尺寸、全屏、自定义内容
+
+#### 33. `<aithe-drawer>` - 抽屉
+
+- **位置**: 上、下、左、右
+- **特性**: 大小、标题、遮罩、关闭控制
+
+#### 34. `<aithe-tooltip>` - 工具提示
+
+- **位置**: 12 个方向
+- **特性**: 延迟显示、主题、自定义内容
+
+#### 35. `<aithe-popover>` - 弹出框
+
+- **功能**: 点击触发的弹出内容
+- **特性**: 触发方式、位置、箭头
+
+#### 36. `<aithe-toast>` - 轻提示
+
+- **类型**: 成功、警告、错误、信息
+- **特性**: 自动关闭、位置、自定义持续时间
+
+#### 37. `<aithe-alert>` - 警告提示
+
+- **类型**: 成功、信息、警告、错误
+- **特性**: 可关闭、图标、描述
+
+#### 38. `<aithe-notification>` - 通知提醒框
+
+- **功能**: 全局通知
+- **特性**: 位置、持续时间、自定义按钮
+
+#### 39. `<aithe-loading>` - 加载中
+
+- **类型**: 全屏、容器、内联
+- **特性**: 自定义文本、延迟显示
+
+### 数据展示组件 (9个)
+
+#### 40. `<aithe-table>` - 表格
+
+- **功能**: 数据表格
+- **特性**: 排序、筛选、分页、选择、虚拟滚动
+
+#### 41. `<aithe-table-column>` - 表格列
+
+- **功能**: 声明式表格列定义
+- **特性**: 字段映射、排序、对齐、宽度
+- **备注**: 26.2.2.1 新增
+
+#### 42. `<aithe-tabs>` - 标签页
+
+- **类型**: 线型、卡片型
+- **特性**: 位置、大小、可关闭、懒加载
+
+#### 43. `<aithe-tab-pane>` - 标签页面板
+
+- **功能**: 单个标签页内容
+- **特性**: 禁用、懒加载、图标
+
+#### 44. `<aithe-tree>` - 树形控件
+
+- **功能**: 层级数据展示
+- **特性**: 选择、展开、搜索、拖拽
+
+#### 45. `<aithe-tree-menu>` - 树形菜单
+
+- **功能**: 基于 Tree 数据的菜单导航
+- **特性**: 递归渲染、意图着色、垂直/水平布局
+- **备注**: 26.2.2.1 新增
+
+#### 46. `<aithe-timeline>` - 时间线
+
+- **模式**: 垂直、水平
+- **特性**: 自定义节点、颜色、图标、数据驱动模式
+- **备注**: 26.2.2.1 从 layout 分类迁移至 data 分类
+
+#### 47. `<aithe-timeline-item>` - 时间线项
+
+- **功能**: 单个时间线节点
+- **特性**: 时间、内容、状态
+
+#### 48. `<aithe-pagination>` - 分页
+
+- **功能**: 数据分页
+- **特性**: 大小选择、快速跳转、简洁模式
+
+### 展示组件 (4个)
+
+#### 49. `<aithe-carousel>` - 走马灯
+
+- **功能**: 轮播图
+- **特性**: 自动播放、指示器、箭头、切换效果
+
+#### 50. `<aithe-comparison>` - 对比
+
+- **功能**: 前后对比滑块
+- **特性**: 方向、手柄样式、标签
+
+#### 51. `<aithe-animated-image>` - 动画图片
+
+- **功能**: 带动画的图片显示
+- **特性**: 缩放、平移、加载动画
+
+#### 52. `<aithe-markdown>` - Markdown 渲染
+
+- **功能**: Markdown 内容渲染
+- **特性**: 语法高亮、自定义渲染器
+
+### 进度组件 (4个)
+
+#### 53. `<aithe-progress-bar>` - 进度条
+
+- **类型**: 线型、环形、仪表盘
+- **特性**: 颜色、条纹动画、自定义文本
+
+#### 54. `<aithe-progress-ring>` - 环形进度条
+
+- **功能**: 环形进度显示
+- **特性**: 大小、宽度、颜色渐变
+
+#### 55. `<aithe-spinner>` - 加载旋转器
+
+- **类型**: 旋转、脉冲、波浪
+- **特性**: 大小、颜色、速度
+
+#### 56. `<aithe-skeleton>` - 骨架屏
+
+- **功能**: 内容加载占位
+- **特性**: 动画、自定义行数、形状
+
+### 容器组件 (4个)
+
+#### 57. `<aithe-callout>` - 提示框
+
+- **类型**: 信息、成功、警告、错误
+- **特性**: 图标、标题、可关闭
+
+#### 58. `<aithe-details>` - 详情
+
+- **功能**: 可展开的详情区域
+- **特性**: 摘要、展开状态、禁用
+
+#### 59. `<aithe-scroller>` - 滚动容器
+
+- **功能**: 自定义滚动区域
+- **特性**: 虚拟滚动、懒加载、滚动事件
+
+#### 60. `<aithe-split-panel>` - 分割面板
+
+- **方向**: 水平、垂直
+- **特性**: 可调整大小、最小最大限制
+
+### 主题组件 (3个)
+
+#### 61. `<aithe-theme-picker>` - 主题选择器
+
+- **功能**: 主题选择器，支持 Light/Dark 分组展示
+- **特性**: 色点预览、键盘导航、`aithe-theme-change` 事件
+- **备注**: 26.2.2.2 新增
+
+#### 62. `<aithe-theme-preview>` - 主题预览
+
+- **功能**: 主题预览面板，支持局部预览 + 确认应用全局主题
+- **特性**: 工具栏、预览区、`aithe-theme-apply` 事件
+- **备注**: 26.2.2.2 新增
+
+#### 63. `<aithe-locale-switch>` - 语言切换
+
+- **功能**: 语言切换器，支持 en-US / zh-CN 切换
+- **特性**: 浮层下拉、键盘导航、`aithe-locale-change` 事件
+- **备注**: 26.2.2.4 新增
+
+## 技术架构
+
+### 核心基类
+
+- **AitheElement**: 所有组件的基类，提供统一的属性、事件和样式管理
+- **主题系统**: 基于 CSS 自定义属性的主题切换机制
+- **工具函数**: DOM 操作、事件处理、验证工具
+
+### 样式系统
+
+- **设计令牌**: 统一的颜色、间距、字体、阴影等设计变量
+- **响应式**: 基于 CSS 媒体查询的响应式设计
+- **主题切换**: 通过 CSS 类名切换主题
+
+### 构建系统
+
+- **Vite**: 快速的开发服务器和构建工具
+- **TypeScript**: 完整的类型定义支持
+- **Lit 3.x**: 现代 Web Components 开发框架
+
+### 代码质量工具链
+
+- **ESLint**: 代码静态分析，集成 `typescript-eslint`、`eslint-plugin-lit`、`eslint-plugin-wc`、`eslint-plugin-sonarjs`、`eslint-config-prettier`，使用 flat config 格式
+- **Prettier**: 代码格式化，统一缩进、引号、行宽等风格
+- **npm 脚本**: `lint` / `lint:fix` / `format` / `format:fix`
+
+## 安装和使用
+
+### 安装
+
+```bash
+npm install aithe-ui
+```
+
+### 基本使用
+
+```javascript
+import 'aithe-ui';
+
+// 在 HTML 中使用
+<aithe-button type="primary" size="medium">
+  点击我
+</aithe-button>;
+```
+
+### 主题设置
+
+```javascript
+import { setAitheTheme } from 'aithe-ui';
+
+// 设置全局主题
+setAitheTheme('dark');
+```
+
+## 浏览器支持
+
+- 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 团队