@aithe/aithe-ui 26.2.2

package/docs/guide.md

@@ -0,0 +1,326 @@
+# 使用指南 / Usage Guide
+
+本文档介绍 Aithe UI 组件的通用 API 模式，包括属性、事件、插槽、样式定制等。
+
+---
+
+## 组件命名规范
+
+所有组件使用 `aithe-` 前缀，对应的类名为 `Aithe*`：
+
+| HTML 标签        | TypeScript 类 | 分类     |
+| ---------------- | ------------- | -------- |
+| `<aithe-button>` | `AitheButton` | Basic    |
+| `<aithe-input>`  | `AitheInput`  | Basic    |
+| `<aithe-select>` | `AitheSelect` | Form     |
+| `<aithe-dialog>` | `AitheDialog` | Feedback |
+| `<aithe-table>`  | `AitheTable`  | Data     |
+| ...              | ...           | ...      |
+
+完整组件列表见 [API 参考](api/summary.md)。
+
+---
+
+## 通用属性
+
+所有 Aithe 组件继承自 `AitheElement`，共享以下基础属性：
+
+| 属性       | 类型                   | 默认值      | 说明                             |
+| ---------- | ---------------------- | ----------- | -------------------------------- |
+| `variant`  | `string`               | `'default'` | 视觉变体                         |
+| `size`     | `'sm' \| 'md' \| 'lg'` | `'md'`      | 尺寸规格                         |
+| `theme`    | `string`               | `''`        | 本地主题覆盖（空则继承全局主题） |
+| `disabled` | `boolean`              | `false`     | 禁用状态                         |
+
+### 使用示例
+
+```html
+<aithe-button variant="primary" size="lg" disabled>Disabled</aithe-button>
+<aithe-input size="sm" placeholder="Small input"></aithe-input>
+```
+
+> **注意**：部分组件使用自己的语义化属性名代替通用属性。例如 `AitheButton` 使用 `type` 代替 `variant`，使用 `'small' | 'medium' | 'large'` 代替 `'sm' | 'md' | 'lg'`。具体以各组件 API 文档为准。
+
+---
+
+## 事件系统
+
+### 事件命名
+
+所有自定义事件使用 `aithe-` 前缀，且默认 **composed** 和 **bubbles**，可穿透 Shadow DOM 冒泡。
+
+```ts
+// 监听组件事件
+element.addEventListener('aithe-change', (e) => {
+  console.log(e.detail); // 事件载荷
+});
+```
+
+### 常见事件模式
+
+| 事件名                | 触发时机       | detail 载荷                     |
+| --------------------- | -------------- | ------------------------------- |
+| `aithe-change`        | 值变化时       | `{ value: new_value }`          |
+| `aithe-input`         | 输入时（实时） | `{ value: current_value }`      |
+| `aithe-click`         | 点击时         | `{ originalEvent: MouseEvent }` |
+| `aithe-confirm`       | 确认操作时     | —                               |
+| `aithe-cancel`        | 取消操作时     | —                               |
+| `aithe-open-change`   | 展开/收起时    | `{ open: boolean }`             |
+| `aithe-clear`         | 清除时         | —                               |
+| `aithe-theme-change`  | 主题变更时     | `{ theme: string }`             |
+| `aithe-locale-change` | 语言变更时     | `{ locale: AitheLocale }`       |
+
+### 在 Lit 中监听
+
+```ts
+@customElement('my-element')
+export class MyElement extends LitElement {
+  render() {
+    return html`
+      <aithe-select @aithe-change=${this.handleChange}></aithe-select>
+    `;
+  }
+
+  private handleChange(e: CustomEvent) {
+    console.log('Selected:', e.detail);
+  }
+}
+```
+
+### 在原生 JS 中监听
+
+```js
+const select = document.querySelector('aithe-select');
+select.addEventListener('aithe-change', (e) => {
+  console.log('Selected:', e.detail);
+});
+```
+
+---
+
+## 插槽（Slots）
+
+组件使用 Shadow DOM 封装样式，通过 `<slot>` 暴露内容注入点。
+
+### 默认插槽
+
+```html
+<aithe-button>按钮文本</aithe-button>
+<aithe-dialog>对话框内容</aithe-dialog>
+```
+
+### 具名插槽
+
+```html
+<aithe-button>
+  <aithe-icon slot="prefix" name="search"></aithe-icon>
+  Search
+  <aithe-icon slot="suffix" name="arrow-right"></aithe-icon>
+</aithe-button>
+
+<aithe-card>
+  <span slot="header">Card Title</span>
+  Card body content
+  <span slot="footer">Footer actions</span>
+</aithe-card>
+```
+
+### 常见插槽模式
+
+| 组件           | 默认插槽   | 具名插槽           |
+| -------------- | ---------- | ------------------ |
+| `aithe-button` | 按钮标签   | `prefix`、`suffix` |
+| `aithe-input`  | —          | `prefix`、`suffix` |
+| `aithe-card`   | 卡片正文   | `header`、`footer` |
+| `aithe-dialog` | 对话框正文 | —                  |
+| `aithe-drawer` | 抽屉正文   | —                  |
+| `aithe-menu`   | 菜单项     | —                  |
+
+---
+
+## 属性绑定
+
+### 字符串属性
+
+直接在 HTML 中设置：
+
+```html
+<aithe-button type="primary">Primary</aithe-button>
+<aithe-input placeholder="Enter text"></aithe-input>
+```
+
+### 布尔属性
+
+存在即为 `true`：
+
+```html
+<aithe-button disabled>Disabled</aithe-button>
+<aithe-input clearable></aithe-input>
+```
+
+### 对象/数组属性
+
+通过 `.` 前缀绑定（Lit 语法）或 JavaScript 设置：
+
+```html
+<!-- Lit 模板中 -->
+<aithe-select .options=${myOptions}></aithe-select>
+
+<!-- 原生 JS -->
+<select.options = myOptions;
+```
+
+### JSON 字符串属性
+
+部分数据驱动组件提供 `*Json` 属性，接受 JSON 字符串（适用于非 Lit 环境）：
+
+```html
+<aithe-select options-json='[{"label":"A","id":"a"}]'></aithe-select>
+<aithe-table columns-json='[{"field":"name","label":"Name"}]'></aithe-table>
+```
+
+---
+
+## 数据驱动组件
+
+部分组件支持通过属性传入数据，而非 DOM 子元素：
+
+| 组件             | 数据属性     | JSON 属性        | 数据项接口          |
+| ---------------- | ------------ | ---------------- | ------------------- |
+| `aithe-select`   | `options`    | `optionsJson`    | `AitheSelectOption` |
+| `aithe-combobox` | `options`    | `optionsJson`    | `ComboboxOption`    |
+| `aithe-dropdown` | `items`      | `itemsJson`      | `AitheDropdownItem` |
+| `aithe-table`    | `data`       | `dataJson`       | —                   |
+| `aithe-tree`     | `data`       | `dataJson`       | `AitheTreeNodeMeta` |
+| `aithe-transfer` | `dataSource` | `dataSourceJson` | `TransferItem`      |
+| `aithe-tabs`     | `items`      | `itemsJson`      | `AitheTabMeta`      |
+| `aithe-timeline` | `items`      | `itemsJson`      | —                   |
+
+### 数据项通用字段
+
+所有数据驱动组件的标识字段统一为 `id`，意图字段统一为 `intent`：
+
+```ts
+interface AitheSelectOption {
+  label: string;
+  id: string;
+  disabled?: boolean;
+  description?: string;
+  icon?: string;
+  intent?: AitheIntent;
+}
+```
+
+---
+
+## 样式定制
+
+### CSS 变量覆盖
+
+所有组件的视觉样式均通过 CSS 自定义属性控制，可在全局或组件级别覆盖：
+
+```css
+/* 全局覆盖 */
+:root {
+  --aithe-primary-6: #1890ff;
+  --aithe-radius-md: 6px;
+}
+
+/* 单个组件覆盖 */
+aithe-button {
+  --aithe-control-height-md: 44px;
+}
+```
+
+### Shadow DOM 穿透
+
+由于 Shadow DOM 封装，外部 CSS 选择器无法直接作用于组件内部。推荐方式：
+
+1. **CSS 变量**（推荐）— 通过 `:root` 或组件选择器覆盖 CSS 变量
+2. **CSS Parts**（部分组件支持）— 通过 `::part()` 选择器
+3. **插槽内容**— 插槽内的内容不受 Shadow DOM 限制，可正常样式化
+
+---
+
+## 表单集成
+
+### 表单验证
+
+`aithe-form` + `aithe-form-item` 提供声明式表单验证：
+
+```html
+<aithe-form>
+  <aithe-form-item label="Username" required>
+    <aithe-input name="username" required></aithe-input>
+  </aithe-form-item>
+  <aithe-form-item label="Email" required>
+    <aithe-input name="email" type="email" required></aithe-input>
+  </aithe-form-item>
+  <aithe-button type="primary">Submit</aithe-button>
+</aithe-form>
+```
+
+### 原生表单参与
+
+部分表单组件支持 `name` 属性，可参与原生表单提交：
+
+```html
+<form onsubmit="console.log(new FormData(this))">
+  <aithe-input name="username"></aithe-input>
+  <aithe-select name="role" .options="${roles}"></aithe-select>
+  <aithe-button type="primary">Submit</aithe-button>
+</form>
+```
+
+---
+
+## 无障碍（Accessibility）
+
+所有组件内置 ARIA 语义和键盘导航支持：
+
+- **ARIA 属性**：自动设置 `aria-label`、`aria-disabled`、`role` 等
+- **键盘导航**：支持 Tab、Enter、Space、Escape、方向键等
+- **焦点管理**：模态框/抽屉自动捕获焦点，关闭后恢复焦点
+- **屏幕阅读器**：所有交互元素均有适当的 ARIA 标注
+
+```html
+<!-- aria-label 自动由 i18n 系统提供 -->
+<aithe-input></aithe-input>
+
+<!-- 也可手动覆盖 -->
+<aithe-input aria-label="Search users"></aithe-input>
+```
+
+---
+
+## TypeScript 支持
+
+Aithe UI 使用 TypeScript 编写，提供完整的类型定义：
+
+```ts
+import type { AitheButton, AitheSelectOption, AitheLocale } from 'aithe-ui';
+
+// 组件属性类型
+const options: AitheSelectOption[] = [
+  { label: 'Option A', id: 'a' },
+  { label: 'Option B', id: 'b' },
+];
+
+// 主题类型
+import type { AitheBuiltinTheme, AitheThemeName } from 'aithe-ui';
+const theme: AitheBuiltinTheme = 'dark';
+
+// i18n 类型
+const locale: AitheLocale = 'zh-CN';
+```
+
+构建产物包含 `dist/index.d.ts` 类型声明文件，IDE 可自动补全。
+
+---
+
+## 下一步
+
+- [主题系统](theming.md) — 22 种内置主题、自定义主题
+- [国际化](i18n.md) — 多语言支持、自定义翻译
+- [框架集成](framework-integration.md) — React / Vue / Angular / Svelte
+- [API 参考](api/summary.md) — 全部组件详细 API

package/docs/i18n.md

@@ -0,0 +1,269 @@
+# 国际化 / Internationalization (i18n)
+
+Aithe UI 内置国际化支持，提供 `en-US` 和 `zh-CN` 两种语言（BCP 47 标准），并支持应用层注册自定义翻译。
+
+---
+
+## 快速开始
+
+### 切换语言
+
+```ts
+import { setAitheLocale, getAitheLocale } from 'aithe-ui';
+
+// 切换到中文
+setAitheLocale('zh-CN');
+
+// 切换到英文
+setAitheLocale('en-US');
+
+// 获取当前语言
+const locale = getAitheLocale(); // 'zh-CN'
+```
+
+### 使用语言切换组件
+
+```html
+<aithe-locale-switch></aithe-locale-switch>
+```
+
+---
+
+## 核心 API
+
+### `setAitheLocale(locale, persist?)`
+
+切换当前语言，默认持久化到 `localStorage`。
+
+```ts
+setAitheLocale('zh-CN'); // 切换并持久化
+setAitheLocale('en-US', false); // 切换但不持久化
+```
+
+### `getAitheLocale()`
+
+获取当前语言标识。
+
+```ts
+const locale = getAitheLocale(); // 'en-US' | 'zh-CN'
+```
+
+### `t(key, ...args)`
+
+翻译函数，根据 key 获取当前语言的翻译文本。支持插值函数和 `en-US` 回退。
+
+```ts
+import { t } from 'aithe-ui';
+
+t('basic.empty.defaultText'); // 'No data' (en-US) / '暂无数据' (zh-CN)
+t('form.rate.ariaLabel', 3, 5); // 'Rate 3 of 5' (en-US) / '评分 3 / 5' (zh-CN)
+t('nonexistent.key'); // 'nonexistent.key' (回退到 key 本身)
+```
+
+### `onAitheLocaleChange(fn)`
+
+订阅语言变更事件，返回取消订阅函数。
+
+```ts
+const unsubscribe = onAitheLocaleChange(() => {
+  console.log('Locale changed to:', getAitheLocale());
+  // 在此更新 UI
+});
+
+// 取消订阅
+unsubscribe();
+```
+
+### `initAitheLocale(defaultLocale?)`
+
+初始化语言（从 `localStorage` 恢复或使用默认值）。通常由 `initializeAitheUI()` 自动调用，无需手动调用。
+
+```ts
+initAitheLocale('en-US'); // 默认 en-US，有存储值则恢复
+```
+
+---
+
+## 应用层翻译注册
+
+核心库翻译与应用层翻译分离。应用通过 `registerAitheTranslations()` 注册自己的翻译键，不会污染核心库。
+
+### 注册翻译
+
+```ts
+import { registerAitheTranslations } from 'aithe-ui';
+
+// 注册英文翻译
+registerAitheTranslations('en-US', {
+  'app.brand': 'My App',
+  'app.welcome': 'Welcome to My App',
+  'app.userCount': (count: unknown) => `${count} users online`,
+});
+
+// 注册中文翻译
+registerAitheTranslations('zh-CN', {
+  'app.brand': '我的应用',
+  'app.welcome': '欢迎使用我的应用',
+  'app.userCount': (count: unknown) => `${count} 位用户在线`,
+});
+```
+
+### 在 Lit 组件中使用
+
+```ts
+import { LitElement, html } from 'lit';
+import { customElement, state } from 'lit/decorators.js';
+import { t, onAitheLocaleChange } from 'aithe-ui';
+
+@customElement('my-app')
+export class MyApp extends LitElement {
+  @state() private localeVersion = 0;
+  private unsubscribeLocale?: () => void;
+
+  connectedCallback(): void {
+    super.connectedCallback();
+    this.unsubscribeLocale = onAitheLocaleChange(() => {
+      this.localeVersion++;
+    });
+  }
+
+  disconnectedCallback(): void {
+    super.disconnectedCallback();
+    this.unsubscribeLocale?.();
+  }
+
+  render() {
+    void this.localeVersion; // 触发 Lit 响应式更新
+    return html`
+      <h1>${t('app.welcome')}</h1>
+      <p>${t('app.userCount', 42)}</p>
+    `;
+  }
+}
+```
+
+### 翻译文件组织
+
+推荐将应用翻译组织为独立模块：
+
+```
+src/
+├── i18n/
+│   ├── en-US.ts    # 英文翻译
+│   ├── zh-CN.ts    # 中文翻译
+│   └── index.ts    # 注册入口
+```
+
+```ts
+// src/i18n/en-US.ts
+export const appEn: Record<string, import('aithe-ui').AitheTranslationValue> = {
+  'app.brand': 'My App',
+  'app.welcome': 'Welcome',
+};
+
+// src/i18n/zh-CN.ts
+export const appZh: Record<string, import('aithe-ui').AitheTranslationValue> = {
+  'app.brand': '我的应用',
+  'app.welcome': '欢迎',
+};
+
+// src/i18n/index.ts
+import { registerAitheTranslations } from 'aithe-ui';
+import { appEn } from './en-US';
+import { appZh } from './zh-CN';
+
+export function registerAppTranslations(): void {
+  registerAitheTranslations('en-US', appEn);
+  registerAitheTranslations('zh-CN', appZh);
+}
+```
+
+```ts
+// 应用入口
+import 'aithe-ui';
+import { registerAppTranslations } from './i18n';
+
+registerAppTranslations();
+```
+
+---
+
+## 翻译键命名规范
+
+核心库翻译键按组件分类命名：
+
+| 前缀             | 范围     | 示例                                  |
+| ---------------- | -------- | ------------------------------------- |
+| `basic.*`        | 基础组件 | `basic.input.ariaLabel`               |
+| `navigation.*`   | 导航组件 | `navigation.breadcrumb.ariaLabel`     |
+| `form.*`         | 表单组件 | `form.select.placeholder`             |
+| `feedback.*`     | 反馈组件 | `feedback.modal.closeAriaLabel`       |
+| `data.*`         | 数据组件 | `data.table.emptyText`                |
+| `display.*`      | 展示组件 | `display.carousel.prevSlideAriaLabel` |
+| `container.*`    | 容器组件 | `container.details.defaultSummary`    |
+| `theme.*`        | 主题组件 | `theme.light`                         |
+| `localeSwitch.*` | 语言切换 | `localeSwitch.label`                  |
+
+应用层翻译键建议使用自己的前缀（如 `app.*`），避免与核心键冲突。
+
+---
+
+## 插值函数
+
+翻译值支持插值函数，用于动态文本：
+
+```ts
+// 注册
+registerAitheTranslations('en-US', {
+  'app.greeting': (name: unknown) => `Hello, ${name}!`,
+  'app.itemCount': (count: unknown) => `${count} items`,
+});
+
+// 使用
+t('app.greeting', 'Alice'); // 'Hello, Alice!'
+t('app.itemCount', 5); // '5 items'
+```
+
+---
+
+## 兼容性
+
+### 旧版 locale 值迁移
+
+`initAitheLocale()` 自动将 `localStorage` 中的旧值映射：
+
+| 旧值   | 新值      |
+| ------ | --------- |
+| `'en'` | `'en-US'` |
+| `'zh'` | `'zh-CN'` |
+
+### 持久化
+
+语言选择自动保存到 `localStorage`（键名 `aithe-locale`），页面刷新后自动恢复。
+
+---
+
+## 已国际化组件
+
+以下 19 个组件的硬编码文本已接入 `t()` 翻译函数：
+
+| 分类       | 组件                                                |
+| ---------- | --------------------------------------------------- |
+| Basic      | input, avatar, empty                                |
+| Navigation | breadcrumb, back-top                                |
+| Form       | select, combobox, rate, upload, transfer, form-item |
+| Feedback   | dialog, modal, drawer                               |
+| Data       | tabs, table                                         |
+| Display    | carousel, comparison                                |
+| Container  | details                                             |
+| Theme      | theme-picker, theme-preview                         |
+
+其余 60 个组件不包含用户可见的硬编码字符串（仅包含结构性 HTML/CSS 或通过属性传入文本），无需国际化。
+
+---
+
+## 下一步
+
+- [主题系统](theming.md) — 22 种内置主题
+- [使用指南](guide.md) — 组件通用 API
+- [框架集成](framework-integration.md) — React / Vue / Angular / Svelte

package/docs/issue/issue_26.2.2.1.md

@@ -0,0 +1,58 @@
+# Issue 26.2.2.1
+
+## 版本信息
+
+- **版本号**: 26.2.2.1
+- **基线版本**: 26.2.2
+- **类型**: 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-dropdown | `value` | `id` |
+| aithe-select | `value` | `id` |
+| aithe-combobox | `value` | `id` |
+| aithe-transfer | `value` | `id` |
+| aithe-table | `key` | `id` |
+| aithe-table-column | `key` | `id` |
+| aithe-tree | `value` | `id` |
+| aithe-tree-menu | `value` | `id` |
+| aithe-tab-pane | `tab-key` | `tab-id` |
+| aithe-dropdown | `style` | `intent` |
+| aithe-select | `style` | `intent` |
+| aithe-combobox | `style` | `intent` |
+| aithe-table | `style` | `intent` |
+| aithe-tree | `style` | `intent` |
+| aithe-tree-menu | `style` | `intent` |
+| aithe-dropdown 事件 aithe-select | detail `value` | detail `id` |
+
+## 变更内容
+
+### 新增
+
+- **AitheTableColumn 子组件** — 将表格列定义从纯数据驱动改为声明式子组件模式，支持在模板中直接使用 `<aithe-table-column>` 配置列，同时保留数据驱动兼容
+- **AitheTreeMenu 组件** — 基于 Tree 数据结构的菜单导航组件，支持递归渲染多级菜单、意图着色，以及垂直/水平两种布局方向（水平模式使用下拉面板展示子菜单）
+- **AitheTimeline / AitheTimelineItem（data 分类）** — 从 layout 分类迁移至 data 分类，同时增加数据驱动模式（items/itemsJson 双属性），保留原有 DOM 声明式用法
+
+### 修改
+
+- **接口字段统一为 `id`** — 将 `AitheDropdownItem`、`AitheSelectOption`、`AitheTableColumnMeta`、`AitheTreeNodeMeta`、`AitheTabMeta` 及组件本地接口（`ComboboxOption`、`TransferItem`）中的 `key`/`value` 唯一标识字段统一命名为 `id`，消除命名不一致，使所有数据驱动组件接口保持统一规范
+- **意图属性统一为 `intent`** — 将上述接口及组件中的 `style`（AitheIntent 类型）字段统一重命名为 `intent`，与组件自身的 intent 属性命名保持一致，避免语义混淆
+- **组件源码适配** — dropdown、select、combobox、transfer、table、tree、tree-menu、tabs、tab-pane 等组件内部逻辑、属性映射、CSS 类名绑定全部适配新字段名
+- **Demo 数据与文档同步更新** — API 应用和 Demo 应用中的示例数据、侧边栏条目，以及所有相关 API 文档均同步更新字段名和用法说明
+
+### 删除
+
+- **layout 分类下的旧 timeline 文件** — `src/components/layout/timeline.ts` 和 `src/components/layout/timeline-item.ts`，因组件已迁移至 data 分类，原文件移除
+- **layout 分类下的旧 timeline 文档** — `docs/api/layout/timeline.md` 和 `docs/api/layout/timeline-item.md`，对应迁移至 data 分类