@aithe/aithe-ui 26.2.2 → 26.2.3

package/docs/i18n.md

@@ -1,6 +1,6 @@
 # 国际化 / Internationalization (i18n)
 
-Aithe UI 内置国际化支持，提供 `en-US` 和 `zh-CN` 两种语言（BCP 47 标准），并支持应用层注册自定义翻译。
+Aithe UI 内置国际化支持，提供 `en-US`、`zh-CN`、`zh-TW`、`zh-HK`、`ja-JP`、`ko-KR`、`es-ES`、`pt-BR`、`fr-FR`、`de-DE` 十种内置语言（BCP 47 标准），并支持通过 `aitheUI.registerLocale()` 合并追加自定义翻译。
 
 ---
 
@@ -9,64 +9,85 @@ Aithe UI 内置国际化支持，提供 `en-US` 和 `zh-CN` 两种语言（BCP 4
 ### 切换语言
 
 ```ts
-import { setAitheLocale, getAitheLocale } from 'aithe-ui';
+import { aitheUI } from '@aithe/aithe-ui';
 
 // 切换到中文
-setAitheLocale('zh-CN');
+aitheUI.setLocale('zh-CN');
 
 // 切换到英文
-setAitheLocale('en-US');
+aitheUI.setLocale('en-US');
 
 // 获取当前语言
-const locale = getAitheLocale(); // 'zh-CN'
+const locale = aitheUI.getLocale(); // 'zh-CN'
 ```
 
 ### 使用语言切换组件
 
 ```html
+<!-- 显示所有已注册语言 / Show all registered locales -->
 <aithe-locale-switch></aithe-locale-switch>
+
+<!-- 仅显示指定语言 / Show only specified locales -->
+<aithe-locale-switch locales='["en-US","zh-CN","ja-JP"]'></aithe-locale-switch>
 ```
 
+`locales` 属性接受 JSON 数组字符串，用于限定下拉菜单中显示的语言子集。为空时显示所有已注册语言。
+
 ---
 
 ## 核心 API
 
-### `setAitheLocale(locale, persist?)`
+推荐通过 `aitheUI` 实例统一管理语言设置：
+
+### `aitheUI.setLocale(locale, persist?)`
 
 切换当前语言，默认持久化到 `localStorage`。
 
 ```ts
-setAitheLocale('zh-CN'); // 切换并持久化
-setAitheLocale('en-US', false); // 切换但不持久化
+aitheUI.setLocale('zh-CN'); // 切换并持久化
+aitheUI.setLocale('en-US', false); // 切换但不持久化
 ```
 
-### `getAitheLocale()`
+### `aitheUI.getLocale()`
 
 获取当前语言标识。
 
 ```ts
-const locale = getAitheLocale(); // 'en-US' | 'zh-CN'
+const locale = aitheUI.getLocale(); // AitheLocale (e.g. 'en-US')
 ```
 
-### `t(key, ...args)`
+### `t(key, dft?, params?)`
 
-翻译函数，根据 key 获取当前语言的翻译文本。支持插值函数和 `en-US` 回退。
+翻译函数，根据 key 获取当前语言的翻译文本。支持缺省值和 `{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 本身)
+| 参数     | 类型                              | 必填 | 说明                                                                                        |
+| -------- | --------------------------------- | ---- | ------------------------------------------------------------------------------------------- |
+| `key`    | `string`                          | 是   | 翻译键                                                                                      |
+| `dft`    | `string`                          | 否   | 缺省值。当 key 为空时直接返回缺省值（或空字符串）；当无法找到翻译值时返回缺省值（而非 key） |
+| `params` | `Record<string, string \| number>` | 否   | `{key}` 占位符替换参数                                                                      |
+
+```ts
+import { aitheUI } from '@aithe/aithe-ui';
+
+aitheUI.t('basic.empty.defaultText'); // 'No data' (en-US) / '暂无数据' (zh-CN)
+aitheUI.t('form.rate.ariaLabel', 'Rate {index}', { index: 3 }); // 'Rate 3'
+aitheUI.t('nonexistent.key'); // 'nonexistent.key' (回退到 key 本身)
+aitheUI.t('nonexistent.key', 'Fallback'); // 'Fallback' (使用缺省值)
+aitheUI.t('', 'Default when key is empty'); // 'Default when key is empty'
+aitheUI.t(''); // '' (key 为空且无缺省值时返回空字符串)
 ```
 
-### `onAitheLocaleChange(fn)`
+> **注意**：占位符使用 `{key}` 格式，`params` 中的值会替换翻译字符串中对应的 `{key}`。未提供的占位符会保留原样。
+
+### `aitheUI.onLocaleChange(fn)`
 
 订阅语言变更事件，返回取消订阅函数。
 
 ```ts
-const unsubscribe = onAitheLocaleChange(() => {
-  console.log('Locale changed to:', getAitheLocale());
+const unsubscribe = aitheUI.onLocaleChange(() => {
+  console.log('Locale changed to:', aitheUI.getLocale());
   // 在此更新 UI
 });
 
@@ -74,37 +95,68 @@ const unsubscribe = onAitheLocaleChange(() => {
 unsubscribe();
 ```
 
-### `initAitheLocale(defaultLocale?)`
+### `aitheUI.registerLocale(locale, translations)`
 
-初始化语言（从 `localStorage` 恢复或使用默认值）。通常由 `initializeAitheUI()` 自动调用，无需手动调用。
+合并追加翻译条目到已有语言。适用于应用层注册自定义翻译，不会替换已有的翻译条目。
 
 ```ts
-initAitheLocale('en-US'); // 默认 en-US，有存储值则恢复
+aitheUI.registerLocale('ja-JP', {
+  'basic.empty.defaultText': 'データなし',
+  'theme.light': 'ライト',
+  'theme.dark': 'ダーク',
+});
 ```
 
+### `aitheUI.getLocales()`
+
+获取所有已注册的 locale 标识列表。
+
+```ts
+const locales = aitheUI.getLocales(); // ['en-US', 'zh-CN', 'zh-TW', 'zh-HK', 'ja-JP', 'ko-KR', 'es-ES', 'pt-BR', 'fr-FR', 'de-DE']
+```
+
+---
+
+## 类型定义
+
+### `AitheBuiltinLocale`
+
+内置 BCP 47 locale 标识：`'en-US' | 'zh-CN' | 'zh-TW' | 'zh-HK' | 'ja-JP' | 'ko-KR' | 'es-ES' | 'pt-BR' | 'fr-FR' | 'de-DE'`。
+
+### `AitheLocale`
+
+BCP 47 locale 标识，支持扩展：`AitheBuiltinLocale | (string & {})`。所有接受 locale 参数的 API 均使用此类型。
+
 ---
 
 ## 应用层翻译注册
 
-核心库翻译与应用层翻译分离。应用通过 `registerAitheTranslations()` 注册自己的翻译键，不会污染核心库。
+核心库翻译与应用层翻译分离。应用通过 `aitheUI.registerLocale()` 注册自己的翻译键，不会污染核心库。
 
 ### 注册翻译
 
 ```ts
-import { registerAitheTranslations } from 'aithe-ui';
+import { registerAitheTranslations } from '@aithe/aithe-ui';
 
 // 注册英文翻译
 registerAitheTranslations('en-US', {
   'app.brand': 'My App',
   'app.welcome': 'Welcome to My App',
-  'app.userCount': (count: unknown) => `${count} users online`,
+  'app.userCount': '{count} users online',
 });
 
 // 注册中文翻译
 registerAitheTranslations('zh-CN', {
   'app.brand': '我的应用',
   'app.welcome': '欢迎使用我的应用',
-  'app.userCount': (count: unknown) => `${count} 位用户在线`,
+  'app.userCount': '{count} 位用户在线',
+});
+
+// 注册日文翻译
+registerAitheTranslations('ja-JP', {
+  'app.brand': 'マイアプリ',
+  'app.welcome': 'アプリへようこそ',
+  'app.userCount': '{count} 人のユーザーがオンライン',
 });
 ```
 
@@ -112,18 +164,17 @@ registerAitheTranslations('zh-CN', {
 
 ```ts
 import { LitElement, html } from 'lit';
-import { customElement, state } from 'lit/decorators.js';
-import { t, onAitheLocaleChange } from 'aithe-ui';
+import { customElement } from 'lit/decorators.js';
+import { aitheUI, t } from '@aithe/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++;
+    this.unsubscribeLocale = aitheUI.onLocaleChange(() => {
+      this.requestUpdate();
     });
   }
 
@@ -133,10 +184,9 @@ export class MyApp extends LitElement {
   }
 
   render() {
-    void this.localeVersion; // 触发 Lit 响应式更新
     return html`
-      <h1>${t('app.welcome')}</h1>
-      <p>${t('app.userCount', 42)}</p>
+      <h1>${aitheUI.t('app.welcome')}</h1>
+      <p>${aitheUI.t('app.userCount', '{count} users online', { count: 42 })}</p>
     `;
   }
 }
@@ -151,36 +201,44 @@ src/
 ├── i18n/
 │   ├── en-US.ts    # 英文翻译
 │   ├── zh-CN.ts    # 中文翻译
+│   ├── zh-TW.ts    # 繁體中文（台灣）翻譯
+│   ├── zh-HK.ts    # 繁體中文（香港）翻譯
+│   ├── ja-JP.ts    # 日本語翻訳
+│   ├── ko-KR.ts    # 한국어 번역
+│   ├── es-ES.ts    # Español
+│   ├── pt-BR.ts    # Português Brasileiro
+│   ├── fr-FR.ts    # Français
+│   ├── de-DE.ts    # Deutsch
 │   └── index.ts    # 注册入口
 ```
 
 ```ts
 // src/i18n/en-US.ts
-export const appEn: Record<string, import('aithe-ui').AitheTranslationValue> = {
+export const appEn: Record<string, string> = {
   'app.brand': 'My App',
   'app.welcome': 'Welcome',
 };
 
 // src/i18n/zh-CN.ts
-export const appZh: Record<string, import('aithe-ui').AitheTranslationValue> = {
+export const appZh: Record<string, string> = {
   'app.brand': '我的应用',
   'app.welcome': '欢迎',
 };
 
 // src/i18n/index.ts
-import { registerAitheTranslations } from 'aithe-ui';
+import { aitheUI } from '@aithe/aithe-ui';
 import { appEn } from './en-US';
 import { appZh } from './zh-CN';
 
 export function registerAppTranslations(): void {
-  registerAitheTranslations('en-US', appEn);
-  registerAitheTranslations('zh-CN', appZh);
+  aitheUI.registerLocale('en-US', appEn);
+  aitheUI.registerLocale('zh-CN', appZh);
 }
 ```
 
 ```ts
 // 应用入口
-import 'aithe-ui';
+import '@aithe/aithe-ui';
 import { registerAppTranslations } from './i18n';
 
 registerAppTranslations();
@@ -192,73 +250,80 @@ 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`                  |
+| 前缀             | 范围      | 示例                                       |
+| ---------------- | --------- | ------------------------------------------ |
+| `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`         |
+| `body.*`         | 框架-主体 | `body.switchLayout`, `body.layout.compact` |
+| `sidebar.*`      | 框架-侧栏 | `sidebar.collapse`, `sidebar.expand`       |
+| `theme.*`        | 主题组件  | `theme.light`                              |
+| `localeSwitch.*` | 语言切换  | `localeSwitch.label`                       |
 
 应用层翻译键建议使用自己的前缀（如 `app.*`），避免与核心键冲突。
 
 ---
 
-## 插值函数
+## 插值
 
-翻译值支持插值函数，用于动态文本：
+翻译值支持 `{key}` 占位符插值，用于动态文本：
 
 ```ts
 // 注册
-registerAitheTranslations('en-US', {
-  'app.greeting': (name: unknown) => `Hello, ${name}!`,
-  'app.itemCount': (count: unknown) => `${count} items`,
+aitheUI.registerLocale('en-US', {
+  'app.greeting': 'Hello, {name}!',
+  'app.itemCount': '{count} items',
 });
 
 // 使用
-t('app.greeting', 'Alice'); // 'Hello, Alice!'
-t('app.itemCount', 5); // '5 items'
+aitheUI.t('app.greeting', 'Hello, {name}!', { name: 'Alice' }); // 'Hello, Alice!'
+aitheUI.t('app.itemCount', '{count} items', { count: 5 }); // '5 items'
 ```
 
+翻译值也兼容函数类型，函数会在无参情况下被调用：
+
 ---
 
-## 兼容性
+## 持久化
 
-### 旧版 locale 值迁移
+语言选择自动保存到 `localStorage`（键名 `aithe-locale`），页面刷新后自动恢复。
 
-`initAitheLocale()` 自动将 `localStorage` 中的旧值映射：
+---
 
-| 旧值   | 新值      |
-| ------ | --------- |
-| `'en'` | `'en-US'` |
-| `'zh'` | `'zh-CN'` |
+## 已国际化组件
 
-### 持久化
+以下 24 个组件的硬编码文本已接入 `t()` 翻译函数：
 
-语言选择自动保存到 `localStorage`（键名 `aithe-locale`），页面刷新后自动恢复。
+| 分类       | 组件                                                        |
+| ---------- | ----------------------------------------------------------- |
+| 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                                                     |
+| Framework  | body, sidebar                                               |
+| Theme      | theme-switch, theme-picker, theme-preview, shape-picker, shadow-picker, locale-switch |
+
+其余 59 个组件不包含用户可见的硬编码字符串（仅包含结构性 HTML/CSS 或通过属性传入文本），无需国际化。
 
 ---
 
-## 已国际化组件
+## 事件
 
-以下 19 个组件的硬编码文本已接入 `t()` 翻译函数：
+### `aithe-locale-change`
 
-| 分类       | 组件                                                |
-| ---------- | --------------------------------------------------- |
-| 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                         |
+`<aithe-locale-switch>` 组件在选择语言时发出此事件。调用 `event.preventDefault()` 可阻止内置切换逻辑。
 
-其余 60 个组件不包含用户可见的硬编码字符串（仅包含结构性 HTML/CSS 或通过属性传入文本），无需国际化。
+| 属性         | 说明                            |
+| ------------ | ------------------------------- |
+| `detail`     | `{ locale: string }` 被选语言   |
+| `cancelable` | `true`，支持 `preventDefault()` |
 
 ---
 
@@ -267,3 +332,4 @@ t('app.itemCount', 5); // '5 items'
 - [主题系统](theming.md) — 22 种内置主题
 - [使用指南](guide.md) — 组件通用 API
 - [框架集成](framework-integration.md) — React / Vue / Angular / Svelte
+- [API 参考](api/summary.md) — 全部 83 个组件详细 API

package/docs/issue/AGENTS.md

@@ -0,0 +1,22 @@
+# docs/issue/ — 问题追踪文档
+
+## 概述
+
+记录每个 Issue（迭代/补丁）的详细变更内容，用于追踪版本间的增量修改。
+
+## 目录结构
+
+| 文件                 | 说明                |
+| -------------------- | ------------------- |
+| `issue_{version}.md` | 各 Issue 的变更文档 |
+
+## 文档格式
+
+Issue 文档包含：版本信息、变更概述、破坏性变更、变更内容（新增/修改/删除）。
+
+## 关键约定
+
+- **这些文件是历史记录，禁止修改已发布的 Issue 文档**
+- Issue 版本号格式：`基线版本.补丁号`（如 `26.2.3.1`）
+- 破坏性变更必须明确标注旧值和新值
+- 变更内容按 新增 / 修改 / 删除 分类

package/docs/issue/issue_26.2.3.1.md

@@ -0,0 +1,45 @@
+# Issue 26.2.3.1
+
+## 版本信息
+
+- **版本号**: 26.2.3.1
+- **基线版本**: 26.2.3
+- **类型**: Patch
+- **日期**: 2026-05-13
+
+## 变更概述
+
+1. 新增 `--aithe-color-text-on-primary` 设计令牌，统一主色背景上的文字颜色
+2. 组件内硬编码 `color: white` / `color: #fff` 替换为 `var(--aithe-color-text-on-primary, #ffffff)`
+3. `aithe-menu-item` 新增 `collapsed` 属性，支持侧边栏折叠模式
+4. `aithe-sub-menu` 新增 collapsed 模式渲染分支，折叠时仅显示图标按钮
+5. `src/index.ts` 新增 3 个导出：`core/anchored-overlay`、`core/floating`、`core/styles`
+6. `apps/` 目录迁移至 `src/apps/`，修复 VSCode 因 `rootDir: "src"` 导致的类型检查错误
+
+## 破坏性变更
+
+| 变更项         | 旧值               | 新值                   |
+| -------------- | ------------------ | ---------------------- |
+| 应用目录路径   | `apps/`            | `src/apps/`            |
+| Demo 入口路径  | `apps/demo/app.ts` | `src/apps/demo/app.ts` |
+| API 入口路径   | `apps/api/app.ts`  | `src/apps/api/app.ts`  |
+| 应用间导航链接 | `/apps/...`        | `/src/apps/...`        |
+
+## 变更内容
+
+### 新增
+
+- **`--aithe-color-text-on-primary` 设计令牌** — 22 个主题文件全部新增此 CSS 变量，用于主色（primary）背景上的文字颜色。cyan 主题值为 `#1a1a2e`（深色文字适配浅色主色），其余 21 个主题值为 `#ffffff`
+- **`aithe-menu-item` collapsed 模式** — 新增 `collapsed` 布尔属性，折叠时隐藏文字标签仅保留图标，通过 `data-collapsed` dataset 和 `.collapsed` CSS 类控制样式，`connectedCallback` 和 `updated` 生命周期中联动处理
+- **`aithe-sub-menu` collapsed 模式** — 新增折叠渲染分支，collapsed 时仅显示图标按钮（`.collapsed-children` 容器），子菜单以弹出面板形式展示，`open` 状态与折叠模式联动
+- **3 个核心模块导出** — `src/index.ts` 新增导出 `core/anchored-overlay`、`core/floating`、`core/styles`，供外部直接引用
+
+### 修改
+
+- **硬编码文字颜色替换为设计令牌** — 9 个组件中的 `color: white` / `color: #fff` 替换为 `var(--aithe-color-text-on-primary, #ffffff)`，涉及：avatar、badge、button、pagination、tabs、tree-menu（3 处）、dialog、menu-item（2 处）、steps、theme-preview
+- **`apps/` 目录迁移至 `src/apps/`** — 将 `apps/` 整体迁移至 `src/apps/`，所有 TypeScript 文件中的相对导入路径同步更新（`../../src/` → `../../`，`../../../src/` → `../../../`），`src/apps/api/pages/docs.ts` 中 docs markdown 导入路径多加一层 `../`
+- **配置文件适配** — `tsconfig.json` 移除 `apps/**/*.ts` include 条目；`vite.config.ts` 更新 open 路径；`vite.demo.config.ts` 更新 entry 路径；`vite.api.config.ts` 更新 entry 和 open 路径；`index.html` 更新 script src 路径；`package.json` 简化 lint/format 脚本
+
+### 删除
+
+- **根目录 `apps/` 目录** — 因迁移至 `src/apps/`，原 `apps/` 目录移除

package/docs/issue/issue_26.2.3.10.md

@@ -0,0 +1,81 @@
+# Issue 26.2.3.10
+
+## 版本信息
+
+- **版本号**: 26.2.3.10
+- **基线版本**: 26.2.3
+- **类型**: Feature
+- **日期**: 2026-05-23
+
+## 变更概述
+
+1. **Dashboard 仪表盘组件** — 新增 `<aithe-dashboard>` 拖拽式仪表盘组件和 `<aithe-dashboard-panel>` 面板卡片组件，支持格子布局、拖拽排列、面板调整大小、状态持久化和全屏模式
+2. **Theme Picker icon-only 模式** — 5 个风格选择器组件（theme-picker、shape-picker、shadow-picker、typo-picker、locale-switch）新增 `icon-only` 属性，支持仅显示图标和箭头的紧凑模式
+3. **SonarQube 代码质量修复** — 批量修复 forEach→for…of（S7891）、window→globalThis（S7764）、readonly 修饰、dataset 访问（S7761）、反转三元表达式（S7735）、冗余 String() 包装等合规问题
+4. **AitheForm 导出方式调整** — 从命名导出改为默认导出
+5. **AitheLocale 类型增强** — 使用 unique symbol 替代 `string & {}` 模式，提升类型安全性
+
+## 破坏性变更
+
+| 变更项                 | 旧值                                                                                    | 新值                                                                          |
+| ---------------------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| `AitheForm` 导出方式   | `export class AitheForm`（命名导出）                                                    | `export default AitheForm`（默认导出），命名导出已移除                        |
+| `AitheLocale` 类型定义 | `AitheBuiltinLocale \| (string & {})`                                                   | `AitheBuiltinLocale \| (string & { readonly [AITHE_CUSTOM_LOCALE]?: never })` |
+| Admin 路由类型导出     | `export { type RouteConfig, type RouteLocation }` from `src/apps/admin/router/index.ts` | 已移除，应从 `@core/router` 导入                                              |
+
+## 变更内容
+
+### 新增
+
+- **`src/components/framework/dashboard.ts`** — `<aithe-dashboard>` 拖拽式仪表盘组件，支持 CSS Grid 布局、内置工具栏（锁定/可见性/重置/全屏/主题选择）、面板拖拽交换与网格吸附、面板边缘调整大小、重叠检测与自动重排、localStorage 状态持久化、全屏模式、局部主题切换、移动端响应式堆叠
+- **`src/components/framework/dashboard-panel.ts`** — `<aithe-dashboard-panel>` 仪表盘面板卡片组件，支持拖拽头部移动、8 方向调整大小（data-edge + dataset）、关闭/最大化、锁定、可见性控制；发射 8 个自定义事件（aithe-panel-close/drag-start/drag/drag-end/maximize/resize-start/resize/resize-end）
+- **`docs/api/framework/dashboard.md`** — `<aithe-dashboard>` API 文档：插槽、CSS Parts、属性、事件、DashboardPanelState 接口、用法示例
+- **`docs/api/framework/dashboard-panel.md`** — `<aithe-dashboard-panel>` API 文档：插槽、CSS Parts、属性、事件、用法示例
+- **`src/components/theme/locale-switch.ts`** — 新增 `icon-only` 属性，支持仅图标紧凑模式
+- **`src/components/theme/shadow-picker.ts`** — 新增 `icon-only` 属性，支持仅图标紧凑模式
+- **`src/components/theme/shape-picker.ts`** — 新增 `icon-only` 属性，支持仅图标紧凑模式
+- **`src/components/theme/theme-picker.ts`** — 新增 `icon-only` 属性，支持仅图标紧凑模式
+- **`src/components/theme/typo-picker.ts`** — 新增 `icon-only` 属性，支持仅图标紧凑模式
+- **`CONTRIBUTING.md`** — 新增代码规范第 12 条：Data attributes should be accessed using ".dataset"(S7761)
+
+### 修改
+
+#### 新功能集成
+
+- **`src/index.ts`** — 新增导出 `@components/framework/dashboard` 和 `@components/framework/dashboard-panel`
+- **`docs/api/summary.md`** — Framework 组件表新增 Dashboard 和 Dashboard Panel 行
+- **`src/apps/api/demo-data.ts`** — 新增 `framework-dashboard` 和 `framework-dashboard-panel` demo 数据
+- **`src/apps/api/pages/docs.ts`** — 新增 dashboard 和 dashboard-panel API 文档页面入口
+- **`src/apps/admin/pages/dashboard-page.ts`** — 使用 `<aithe-dashboard>` + `<aithe-dashboard-panel>` 替换原有 CSS Grid + `aithe-card` 布局
+- **`src/apps/admin/router/index.ts`** — `routes` 改为 `export const`；移除 `RouteConfig`/`RouteLocation` 类型导出
+
+#### i18n 扩展
+
+- **`src/apps/api/i18n/*.ts`**（10 个文件）— 新增 `api.framework.dashboard` 和 `api.framework.dashboardPanel` 翻译键
+- **`src/styles/i18n/locales/*.ts`**（10 个文件）— 移除冗余 `String()` 包装：`form.rate.ariaLabel` 和 `form.formItem.required` 插值函数
+
+#### SonarQube 合规修复
+
+- **forEach → for…of（S7891）** — `src/apps/api/pages/docs.ts`、`src/components/data/table.ts`、`src/components/data/tabs.ts`、`src/components/data/timeline.ts`、`src/components/form/form.ts`、`src/components/form/radio-group.ts`、`src/components/form/transfer.ts`、`src/components/navigation/menu.ts`、`src/components/navigation/sub-menu.ts`、`src/core/datahub/core/adapter/FetchAdapter.ts`、`src/core/datahub/utils/loading.ts`、`src/styles/i18n/index.ts`、`src/styles/theme/index.ts`
+- **window → globalThis（S7764）** — `src/components/feedback/notification.ts`（3 处）、`src/components/feedback/toast.ts`（3 处）、`src/components/framework/log-panel.ts`（4 处）
+- **readonly 修饰** — `src/components/data/tabs.ts`、`src/components/feedback/modal.ts`（3 处）、`src/components/feedback/popover.ts`、`src/components/feedback/tooltip.ts`、`src/components/form/radio-group.ts`、`src/components/form/select.ts`（3 处）、`src/components/framework/log-panel.ts`、`src/components/framework/sidebar.ts`
+- **反转三元表达式修复（S7735）** — `src/components/data/table.ts`（`getRecordKey`）、`src/core/datahub/core/DataHubCore.ts`（`performance.now` 降级逻辑）
+- **冗余 String() 移除** — `src/components/framework/log-panel.ts`（2 处 `String(d)` → `d`）
+
+#### 类型与代码质量
+
+- **`src/components/form/form.ts`** — 命名导出改为默认导出；`querySelectorAll` 使用泛型参数替代类型断言
+- **`src/components/navigation/menu.ts`** — `querySelectorAll` 使用泛型参数替代类型断言
+- **`src/styles/i18n/index.ts`** — `AitheLocale` 类型使用 unique symbol 替代 `string & {}`；`listeners.forEach` → `for…of`
+- **`src/core/router/index.ts`** — `.replace()` → `.replaceAll()` 全局正则替换
+- **`src/core/datahub/utils/idempotent.ts`** — `data: unknown | undefined` → `data: unknown`（移除冗余联合类型）
+- **`src/styles/shadow/index.ts`** — 导出语句移至文件顶部
+- **`src/styles/shape/index.ts`** — 导出语句移至文件顶部
+- **`src/styles/typo/index.ts`** — 导出语句移至文件顶部
+- **`src/components/theme/locale-switch.ts`** — 修复 import 格式化（`t,type` → `t, type`）
+- **`src/components/theme/shadow-picker.ts`** — 移除多余空行
+- **`src/components/theme/typo-picker.ts`** — 移除多余空行
+
+### 删除
+
+无。

package/docs/issue/issue_26.2.3.11.md

@@ -0,0 +1,87 @@
+# Issue 26.2.3.11
+
+## 版本信息
+
+- **版本号**: 26.2.3.11
+- **基线版本**: 26.2.3
+- **类型**: Feature
+- **日期**: 2026-05-26
+
+## 变更概述
+
+1. **Autoform 自动表单组件** — 新增 `<aithe-autoform>` JSON 配置驱动的自动渲染表单组件和 `<aithe-autoform-item>` 表单项组件，支持 13 种内置控件类型、自定义控件注册表（FormRegistry）、实时校验和提交校验
+2. **Dashboard Demo 页面** — 新增 Dashboard 独立 demo 页面，包含基础、锁定、无工具栏、自定义内容、状态持久化、紧凑网格 6 个示例
+3. **Demo/API 文档布局增强** — docs-viewer 和 demo-editor 新增 `layout` 属性支持 `vertical` 布局模式，Dashboard 和 Autoform demo 使用垂直布局
+4. **SonarQube 代码质量修复** — replace→replaceAll（S7781）、移除冗余类型断言（S4325）、forEach→for…of（S7891）、readonly 修饰
+5. **Input/Textarea/Combobox/Select 样式修复** — 修复输入类控件对齐、padding、focus 样式和 disabled 状态显示问题
+6. **Radio Group 同步机制重构** — 从 `@queryAssignedElements` 改为 `querySelectorAll` 动态查询，修复 checked 状态同步问题
+
+## 破坏性变更
+
+| 变更项                         | 旧值                                           | 新值                                                  |
+| ------------------------------ | ---------------------------------------------- | ----------------------------------------------------- |
+| `AitheTypoName` 类型定义       | `AitheBuiltinTypo \| (string & {})`            | `AitheBuiltinTypo \| string`                          |
+| `AitheLayoutName` 类型定义     | `AitheBuiltinLayout \| (string & {})`          | `AitheBuiltinLayout \| string`                        |
+| `AitheShadowName` 类型定义     | `AitheBuiltinShadow \| (string & {})`          | `AitheBuiltinShadow \| string`                        |
+| `AitheShapeName` 类型定义      | `AitheBuiltinShape \| (string & {})`           | `AitheBuiltinShape \| string`                         |
+| `AitheThemeName` 类型定义      | `AitheBuiltinTheme \| (string & {})`           | `AitheBuiltinTheme \| string`                         |
+| `AitheVariant` 类型定义        | `'primary' \| … \| 'neutral' \| (string & {})` | `'primary' \| … \| 'neutral' \| string`               |
+| `<aithe-combobox>` 默认宽度    | `width: min(100%, 320px)`                      | `width: 100%`                                         |
+| `<aithe-input>` .field 对齐    | `align-items: center`                          | `align-items: stretch`                                |
+| `<aithe-input>` .field padding | 使用 CSS 变量（`--aithe-space-*`）             | 固定像素值（sm: 4px 8px, md: 6px 12px, lg: 8px 16px） |
+| `<aithe-select>` .trigger 显示 | `display: inline-flex`                         | `display: flex`                                       |
+
+## 变更内容
+
+### 新增
+
+- **`src/components/form/autoform.ts`** — `<aithe-autoform>` JSON 配置驱动的自动渲染表单组件，支持 `fields`（JSON 字符串）、`validate-on-change`、`submit-text`、`loading` 属性；提供 `validate()`、`getValues()`、`reset()` 方法；发射 `aithe-validate`、`aithe-submit`、`aithe-change` 事件；默认插槽可替换内置提交按钮
+- **`src/components/form/autoform-item.ts`** — `<aithe-autoform-item>` 表单项容器组件，三段式布局（header + control + footer），支持 13 种内置控件类型（input/textarea/select/radio/checkbox/switch/number/slider/rate/color-picker/date-picker/time-picker/combobox）和 FormRegistry 自定义控件；支持 required/pattern 校验和实时校验
+- **`src/core/autoform/index.ts`** — `FormRegistry` 自定义控件类型注册表，提供 `register()`、`unregister()`、`get()`、`has()`、`types()` 静态方法；定义 `FormControlDefinition`、`FormControlContext`、`FormControlRenderer` 类型
+- **`docs/api/form/autoform.md`** — `<aithe-autoform>` API 文档：插槽、属性、方法、事件、支持的字段类型、FormRegistry 自定义控件注册表、注册示例
+- **`src/apps/demo/pages/autoform.ts`** — Autoform 独立 demo 页面，包含基础表单项、选择类控件、高级控件、表单校验、禁用状态、完整表单示例 6 个示例
+- **`src/apps/demo/pages/dashboard.ts`** — Dashboard 独立 demo 页面，包含基础仪表盘、锁定仪表盘、无工具栏仪表盘、自定义面板内容、状态持久化、紧凑网格 6 个示例
+- **`src/utils/utils.ts`** — 新增 `safeStringify()` 工具函数，安全地将任意值转换为 JSON 字符串，三级降级策略（格式化序列化 → 无格式序列化 → String() 兜底）
+- **`CONTRIBUTING.md`** — 新增代码规范第 13 条：Strings should use "replaceAll()" instead of "replace()" with global regex（S7781）；第 14 条：Redundant casts and non-null assertions should be avoided（S4325）
+
+### 修改
+
+#### 新功能集成
+
+- **`src/index.ts`** — 新增导出 `@components/form/autoform`、`@components/form/autoform-item`、`@core/autoform`
+- **`docs/api/summary.md`** — Form 组件表新增 Autoform 行
+- **`src/apps/api/demo-data.ts`** — 新增 `form-autoform` demo 数据；demoMap 和 getDemoData 返回类型新增 `layout` 字段；Dashboard demo 数据新增 `layout: 'vertical'`
+- **`src/apps/api/docs-viewer.ts`** — `DocEntry` 接口新增 `layout?: 'horizontal' | 'vertical'` 属性；demo 区域新增 `.demo-body.vertical` 样式（单列垂直布局）
+- **`src/apps/api/pages/docs.ts`** — 新增 autoform API 文档页面入口
+- **`src/apps/demo/app.ts`** — 新增 dashboard 和 autoform demo 页面
+- **`src/apps/demo/editor.ts`** — `DemoExample` 接口新增 `layout` 属性；demo 区域新增 `.body.vertical` 样式
+
+#### i18n 扩展
+
+- **`src/styles/i18n/index.ts`** — 新增 `form.autoform.submit` 和 `form.autoform.patternMismatch` 翻译键类型；`AitheLocale` 类型格式化换行
+- **`src/styles/i18n/locales/*.ts`**（10 个文件）— 新增 `form.autoform.submit` 和 `form.autoform.patternMismatch` 翻译键
+- **`src/apps/api/i18n/*.ts`**（10 个文件）— 新增 `api.form.autoform` 翻译键
+- **`src/apps/demo/i18n/*.ts`**（10 个文件）— 新增 `demo.dashboard.*` 和 `demo.autoform.*` 翻译键（Dashboard 6 个示例 + Autoform 6 个示例）
+
+#### SonarQube 合规修复
+
+- **replace → replaceAll（S7781）** — `src/components/display/markdown.ts`（5 处 `.replace()` → `.replaceAll()`）
+- **移除冗余类型断言（S4325）** — `src/styles/types.ts`（6 处 `(string & {})` → `string`）；`src/styles/theme/index.ts`、`src/styles/shape/index.ts`、`src/styles/shadow/index.ts`、`src/styles/typo/index.ts`、`src/styles/layout/index.ts`（移除 `as Aithe*Name` 断言）；`src/components/theme/theme-preview.ts`（3 处移除 `as Aithe*Name` 断言）；`src/components/data/table.ts`（移除 `as AitheVariant` 断言）；`src/utils/validation.ts`（`String(value ?? '')` → `(value ?? '').trim()`）
+- **forEach → for…of（S7891）** — `src/components/display/markdown.ts`（`lines.forEach` → `for…of`）
+- **readonly 修饰** — `src/components/framework/dashboard-panel.ts`（6 处方法属性添加 `readonly`）
+
+#### 组件样式与行为修复
+
+- **`src/components/basic/input.ts`** — `.field` 对齐从 `center` 改为 `stretch`；padding 从 CSS 变量改为固定像素值；prefix/suffix 间距从 CSS 变量改为固定像素值；`input` 新增 `margin: 0; padding: 0px; line-height: inherit`；新增 `input:focus` 样式
+- **`src/components/basic/textarea.ts`** — `.field` 改为 `display: flex; flex-direction: column`；padding 调整；`textarea` 新增 `border: none !important`；新增 `textarea:focus` 样式
+- **`src/components/form/combobox.ts`** — 默认宽度从 `min(100%, 320px)` 改为 `100%`；`.control` 从 `inline-flex` 改为 `flex`；padding 从 CSS 变量改为固定像素值；新增 `transition` 过渡动画；新增 `.control.disabled` 样式；`input` 新增 `min-width: 0; margin: 0; padding: 0; line-height: inherit` 和 `!important` 修复；新增 `input::placeholder` 和 `input:focus` 样式；使用 `classMap` 动态添加 disabled 类名
+- **`src/components/form/select.ts`** — `.trigger` 从 `display: inline-flex` 改为 `display: flex`
+- **`src/components/form/radio-group.ts`** — 从 `@queryAssignedElements` 改为 `querySelectorAll` 动态查询子 radio；新增 `firstUpdated` 生命周期调用 `syncChildren`；`syncChildren` 中新增同步 `input.checked` 状态
+- **`src/components/form/radio.ts`** — `handleChange` 中新增 `input.checked = checked` 确保原生 checked 状态正确
+- **`src/components/data/table.ts`** — 排序比较使用 `toSortableString()` 替代 `String()`；`getRecordKey` 使用 `safeStringify()` 替代 `String()`；单元格渲染对 object 类型使用 `JSON.stringify()` 替代隐式转换
+- **`src/components/framework/log-panel.ts`** — 使用 `safeStringify()` 替代内联 `JSON.stringify` try-catch；`LOG_LEVEL_LABEL[level]!` 移除非空断言
+- **`src/components/navigation/menu.ts`** — `querySelectorAll<AitheSubMenu>('aithe-sub-menu')` 泛型参数从 `AitheMenuItem` 修正为 `AitheSubMenu`
+
+### 删除
+
+无。