@aithe/aithe-ui 26.2.3 → 26.3.2

package/docs/datahub.md

@@ -664,8 +664,11 @@ interface DataHubRequestOptions {
   skipCache?: boolean;
   skipDedup?: boolean;
   skipIdempotent?: boolean;
+  forceDedup?: boolean; // 强制启用去重，无视 URL 命名约定
+  forceCache?: boolean; // 强制启用缓存，无视 URL 命名约定
   mock?: boolean;
   mockData?: unknown;
+  mockPath?: string; // Mock JSON 文件路径，加载本地 mock 数据文件
   mockDelay?: number; // 默认 300
   traceId?: string;
   adapter?: string;
@@ -827,6 +830,6 @@ export async function getDashboardStats(options?: DataHubRequestOptions) {
 ## 下一步
 
 - [使用指南](guide.md) — 组件通用 API、事件、插槽
-- [主题系统](theming.md) — 22 种内置主题、自定义主题
+- [主题系统](theming.md) — 25 种内置主题、自定义主题
 - [国际化](i18n.md) — 多语言支持、自定义翻译
 - [API 参考](api/summary.md) — 全部组件详细 API

package/docs/filter.md

@@ -0,0 +1,332 @@
+# Filter 数据格式化 / Data Formatting with Filters
+
+> Aithe UI 内置轻量 Filter 数据格式化框架，支持声明式过滤器表达式，零第三方依赖。
+> Aithe UI provides a lightweight filter-based data formatting framework with declarative filter expressions and zero third-party dependencies.
+
+---
+
+## 概述 / Overview
+
+Filter 模块提供了一套统一的**数据格式化方案**，通过声明式的过滤器表达式对数据进行格式化处理。核心特性：
+
+- **声明式表达式**：如 `"amount"`、`"date yyyy/MM/dd"`、`"date yyyy/MM/dd | empty"`
+- **链式处理**：多个过滤器通过 `|` 串联，前一个输出作为后一个输入
+- **内置过滤器**：金额、日期、空值替换、字节数、时间友好显示
+- **可扩展**：通过 `FilterFactory.register()` 注册自定义过滤器
+- **组件集成**：`<aithe-metrics>` 和 `<aithe-table-column>` 原生支持 `filter` 属性
+
+---
+
+## 快速开始 / Quick Start
+
+```ts
+import { filterFactory } from '@aithe/aithe-ui';
+
+// 单个过滤器
+filterFactory.format(123.456, 'amount');        // "123.46"
+
+// 带参数的过滤器
+filterFactory.format('2024-01-15', 'date yyyy/MM/dd');  // "2024/01/15"
+
+// 链式过滤
+filterFactory.format('2024-01-15', 'date yyyy/MM/dd | empty');  // "2024/01/15"
+filterFactory.format(null, 'date yyyy/MM/dd | empty');          // "--"
+```
+
+---
+
+## 内置过滤器 / Built-in Filters
+
+### amount — 金额格式化
+
+保留两位小数，非数字返回 `--`。
+
+| 输入 | 输出 |
+|------|------|
+| `123.4` | `123.40` |
+| `"100"` | `100.00` |
+| `null` | `--` |
+| `"abc"` | `--` |
+
+```ts
+filterFactory.format(123.4, 'amount');  // "123.40"
+```
+
+### date — 日期格式化
+
+支持 `Date` 对象、时间戳（毫秒）、日期字符串。默认格式 `yyyy-MM-dd HH:mm:ss`，支持自定义格式。
+
+| 参数 | 说明 | 默认值 |
+|------|------|--------|
+| `format` | 日期格式字符串 | `yyyy-MM-dd HH:mm:ss` |
+
+**格式占位符**：
+
+| 占位符 | 含义 | 示例 |
+|--------|------|------|
+| `yyyy` | 四位年份 | 2024 |
+| `MM` | 两位月份 | 01 |
+| `dd` | 两位日期 | 15 |
+| `HH` | 两位小时 | 09 |
+| `mm` | 两位分钟 | 05 |
+| `ss` | 两位秒数 | 30 |
+
+```ts
+filterFactory.format(new Date('2024-01-15'), 'date');               // "2024-01-15 08:00:00"
+filterFactory.format('2024-01-15', 'date yyyy/MM/dd');              // "2024/01/15"
+filterFactory.format(1705305600000, 'date yyyy-MM-dd');             // "2024-01-15"
+filterFactory.format(null, 'date yyyy/MM/dd');                      // "--"
+```
+
+### empty — 空值替换
+
+将 `null`、`undefined`、空字符串、`NaN` 替换为指定文本。
+
+| 参数 | 说明 | 默认值 |
+|------|------|--------|
+| `placeholder` | 替换文本 | `--` |
+
+```ts
+filterFactory.format(null, 'empty');          // "--"
+filterFactory.format(undefined, 'empty');      // "--"
+filterFactory.format('', 'empty');             // "--"
+filterFactory.format('hello', 'empty');        // "hello"
+filterFactory.format(null, 'empty N/A');       // "N/A"
+```
+
+### bytes — 字节数格式化
+
+将字节数转换为可读的大小字符串，支持 IEC（1024 进制）和 SI（1000 进制）两种标准。
+
+| 参数 | 说明 | 默认值 |
+|------|------|--------|
+| `base` | 进制标准：`1024`（IEC）或 `1000`（SI） | `1024` |
+
+**IEC 标准（默认）**：
+
+| 输入 | 输出 |
+|------|------|
+| `500` | `500 B` |
+| `1024` | `1.00 KiB` |
+| `1536` | `1.50 KiB` |
+| `1048576` | `1.00 MiB` |
+| `1073741824` | `1.00 GiB` |
+
+**SI 标准**：
+
+| 输入 | 输出 |
+|------|------|
+| `1000` | `1.00 KB` |
+| `1000000` | `1.00 MB` |
+
+```ts
+filterFactory.format(1024, 'bytes');              // "1.00 KiB"
+filterFactory.format(1000, 'bytes 1000');          // "1.00 KB"
+filterFactory.format(1536, 'bytes');               // "1.50 KiB"
+filterFactory.format(1048576, 'bytes 1024');       // "1.00 MiB"
+```
+
+### timeAgo — 时间友好显示
+
+根据输入时间与当前时间的差值，按规则输出友好文案。超过 1 年显示 `yyyy-MM-dd` 格式日期。
+
+| 时间差 | 输出示例 |
+|--------|----------|
+| < 1 分钟 | `just now` |
+| < 1 小时 | `5 minutes ago` / `in 5 minutes` |
+| < 1 天 | `3 hours ago` / `in 3 hours` |
+| < 1 月 | `2 days ago` / `in 2 days` |
+| < 1 年 | `1 month ago` / `in 1 month` |
+| >= 1 年 | `2025-03-15` |
+
+> 文案通过国际化系统 `t()` 实现，支持 `zh-CN` / `en-US` 切换。
+
+```ts
+filterFactory.format(Date.now() - 300000, 'timeAgo');   // "5 minutes ago"
+filterFactory.format(Date.now() + 600000, 'timeAgo');   // "in 10 minutes"
+filterFactory.format('2025-03-15', 'timeAgo');           // "2025-03-15"
+```
+
+---
+
+## 过滤器表达式语法 / Filter Expression Syntax
+
+过滤器表达式支持以下格式：
+
+| 格式 | 说明 | 示例 |
+|------|------|------|
+| `name` | 仅过滤器名 | `"amount"` |
+| `name arg1 arg2` | 过滤器名 + 参数 | `"date yyyy/MM/dd"` |
+| `name1 \| name2` | 链式过滤 | `"date yyyy/MM/dd \| empty"` |
+
+### 链式过滤规则
+
+多个过滤器通过 `|` 分隔，从左到右依次执行，前一个过滤器的输出作为后一个过滤器的输入。
+
+```ts
+// 先格式化日期，再对空值做兜底
+filterFactory.format(null, 'date yyyy/MM/dd | empty');  // "--"
+filterFactory.format('2024-01-15', 'date yyyy/MM/dd | empty');  // "2024/01/15"
+```
+
+---
+
+## 在组件中使用 / Usage in Components
+
+### `<aithe-metrics>`
+
+通过 `filter` 属性或 `data.filter` / `params.filter` 设置过滤器表达式：
+
+```html
+<!-- 属性模式 -->
+<aithe-metrics label="Revenue" value="1234.5" filter="amount"></aithe-metrics>
+
+<!-- 数据驱动模式 -->
+<aithe-metrics data='{"label":"Revenue","value":"1234.5","filter":"amount"}'></aithe-metrics>
+```
+
+优先级：`data.filter` > `params.filter` > 无过滤。
+
+### `<aithe-table-column>`
+
+通过 `filter` 属性设置过滤器表达式，对列单元格值进行格式化：
+
+```html
+<aithe-table .data=${records}>
+  <aithe-table-column id="price" title="Price" filter="amount"></aithe-table-column>
+  <aithe-table-column id="createdAt" title="Created" filter="date yyyy/MM/dd"></aithe-table-column>
+  <aithe-table-column id="size" title="Size" filter="bytes"></aithe-table-column>
+</aithe-table>
+```
+
+优先级：`cellRenderer` > `filter` > 原始值。
+
+### 数据驱动模式（`AitheTableColumnMeta`）
+
+```ts
+const columns = [
+  { id: 'price', title: 'Price', filter: 'amount' },
+  { id: 'createdAt', title: 'Created', filter: 'date yyyy/MM/dd' },
+  { id: 'size', title: 'Size', filter: 'bytes' },
+];
+```
+
+---
+
+## 编程式使用 / Programmatic Usage
+
+### 直接格式化
+
+```ts
+import { filterFactory } from '@aithe/aithe-ui';
+
+filterFactory.format(123.456, 'amount');               // "123.46"
+filterFactory.format('2024-01-15', 'date yyyy/MM/dd'); // "2024/01/15"
+filterFactory.format(1024, 'bytes');                   // "1.00 KiB"
+```
+
+### 获取过滤器实例
+
+```ts
+const amountFilter = filterFactory.get('amount');
+amountFilter?.apply(123.456);  // "123.46"
+```
+
+### 解析表达式
+
+```ts
+filterFactory.parse('date yyyy/MM/dd | empty');
+// [
+//   { name: 'date', args: ['yyyy/MM/dd'] },
+//   { name: 'empty', args: [] },
+// ]
+```
+
+### 序列化表达式
+
+```ts
+filterFactory.stringify([
+  { name: 'date', args: ['yyyy/MM/dd'] },
+  { name: 'empty', args: [] },
+]);
+// "date yyyy/MM/dd | empty"
+```
+
+---
+
+## 自定义过滤器 / Custom Filters
+
+### 实现 Filter 接口
+
+所有过滤器需实现 `Filter<T, R>` 接口：
+
+```ts
+import type { Filter } from '@aithe/aithe-ui';
+import { filterFactory } from '@aithe/aithe-ui';
+
+// 实现接口（无状态，参数通过 apply 变参传入）
+class PhoneFilter implements Filter<string, string> {
+  apply(value: string): string {
+    if (value == null || value.length !== 11) return value;
+    return `${value.slice(0, 3)}****${value.slice(7)}`;
+  }
+}
+
+// 注册
+filterFactory.register('phone', PhoneFilter);
+
+// 使用
+filterFactory.format('13812345678', 'phone');  // "138****5678"
+```
+
+### 设计约束
+
+- **无状态**：过滤器实例不持有状态，所有参数通过 `apply(value, ...args)` 传入
+- **单例复用**：注册时实例化一次并缓存，后续复用同一实例
+- **参数传递**：表达式中的参数通过 `apply` 的变参传入
+
+---
+
+## 类型定义 / Type Definitions
+
+```ts
+/** 过滤器接口 */
+interface Filter<T = unknown, R = unknown> {
+  apply(value: T, ...args: string[]): R;
+}
+
+/** 过滤器表达式解析结果 */
+interface FilterExpression {
+  name: string;
+  args: string[];
+}
+
+/** 过滤器链配置 */
+type FilterConfig = string | FilterExpression;
+```
+
+---
+
+## API 参考 / API Reference
+
+### FilterFactory
+
+| 方法 | 签名 | 说明 |
+|------|------|------|
+| `register` | `(name: string, ctor: new () => Filter): void` | 注册过滤器 |
+| `get` | `(name: string): Filter \| null` | 获取过滤器实例 |
+| `has` | `(name: string): boolean` | 检查过滤器是否已注册 |
+| `names` | `(): string[]` | 获取所有已注册的过滤器名称 |
+| `format` | `(value: T, config: FilterConfig): unknown` | 使用表达式直接格式化值 |
+| `parse` | `(config: FilterConfig): FilterExpression[]` | 解析过滤器表达式 |
+| `stringify` | `(expressions: FilterExpression[]): string` | 序列化表达式列表 |
+
+### 内置过滤器
+
+| 注册名 | 类 | 说明 |
+|--------|-----|------|
+| `amount` | `AmountFilter` | 金额保留两位小数 |
+| `date` | `DateFilter` | 日期格式化 |
+| `empty` | `EmptyFilter` | 空值替换 |
+| `bytes` | `BytesFilter` | 字节数格式化 |
+| `timeAgo` | `TimeAgoFilter` | 时间友好显示 |

package/docs/framework-integration.md

@@ -565,6 +565,6 @@ if (typeof globalThis !== 'undefined') {
 
 - [快速上手](quickstart.md) — 安装和基本使用
 - [使用指南](guide.md) — 组件通用 API
-- [主题系统](theming.md) — 22 种内置主题
+- [主题系统](theming.md) — 25 种内置主题
 - [国际化](i18n.md) — 多语言支持
-- [API 参考](api/summary.md) — 全部 83 个组件详细 API
+- [API 参考](api/summary.md) — 全部 103 个组件详细 API

package/docs/guide.md

@@ -66,6 +66,7 @@ element.addEventListener('aithe-change', (e) => {
 | `aithe-confirm`       | 确认操作时     | —                               |
 | `aithe-cancel`        | 取消操作时     | —                               |
 | `aithe-open-change`   | 展开/收起时    | `{ open: boolean }`             |
+| `aithe-dropdown-change` | 下拉开关状态变更时 | `{ open: boolean }`        |
 | `aithe-clear`         | 清除时         | —                               |
 | `aithe-theme-change`  | 主题变更时     | `{ theme: string }`             |
 | `aithe-shape-change`  | 形状风格变更时 | `{ shape: string }`             |
@@ -170,7 +171,7 @@ select.addEventListener('aithe-change', (e) => {
 <aithe-select .options=${myOptions}></aithe-select>
 
 <!-- 原生 JS -->
-<select.options = myOptions;
+select.options = myOptions;
 ```
 
 ### JSON 字符串属性
@@ -294,8 +295,6 @@ const msg: string = 'Hello';
 ```
 ````
 
-````
-
 ### 使用底层解析器
 
 ```ts
@@ -316,7 +315,7 @@ parser.parse('**bold**'); // '<strong>bold</strong>'
 // 自定义 link hooks
 const parser = new FullMarkdownParser();
 parser.addLinkHook((url) => url.startsWith('/') ? url : '');
-````
+```
 
 > 完整文档见 [Markdown 模块](markdown.md)。
 
@@ -399,10 +398,13 @@ interface AitheSelectOption {
   disabled?: boolean;
   description?: string;
   icon?: string;
-  intent?: AitheVariant;
+  variant?: AitheVariant;
+  group?: string;
 }
 ```
 
+`group` 字段用于选项分组显示：当 `aithe-select` 或 `aithe-combobox` 的 `options` 中任一选项携带 `group` 字段时，所有选项按 `group` 聚合，每组前置分组标题，组内选项缩进显示。未携带 `group` 字段的选项归入无标题分组；无任何 `group` 字段时回退为扁平列表渲染。
+
 ---
 
 ## 样式定制
@@ -1078,6 +1080,69 @@ const locale: AitheLocale = 'zh-CN';
 
 ---
 
+## Filter 数据格式化
+
+Aithe UI 内置轻量 Filter 数据格式化框架，支持声明式过滤器表达式，零第三方依赖。
+
+### 基本用法
+
+```ts
+import { filterFactory } from '@aithe/aithe-ui';
+
+// 单个过滤器
+filterFactory.format(123.456, 'amount');        // "123.46"
+
+// 带参数的过滤器
+filterFactory.format('2024-01-15', 'date yyyy/MM/dd');  // "2024/01/15"
+
+// 链式过滤
+filterFactory.format(null, 'date yyyy/MM/dd | empty');  // "--"
+```
+
+### 内置过滤器
+
+| 注册名 | 说明 | 示例 |
+|--------|------|------|
+| `amount` | 金额保留两位小数 | `123.4` → `123.40` |
+| `date` | 日期格式化 | `'2024-01-15'` → `2024/01/15` |
+| `empty` | 空值替换为 `--` | `null` → `--` |
+| `bytes` | 字节数格式化 | `1024` → `1.00 KiB` |
+| `timeAgo` | 时间友好显示 | `5 minutes ago` |
+
+### 在组件中使用
+
+```html
+<!-- metrics 使用 filter -->
+<aithe-metrics label="Revenue" value="1234.5" filter="amount"></aithe-metrics>
+
+<!-- table-column 使用 filter -->
+<aithe-table .data=${records}>
+  <aithe-table-column id="price" title="Price" filter="amount"></aithe-table-column>
+  <aithe-table-column id="createdAt" title="Created" filter="date yyyy/MM/dd"></aithe-table-column>
+</aithe-table>
+```
+
+### 自定义过滤器
+
+```ts
+import type { Filter } from '@aithe/aithe-ui';
+import { filterFactory } from '@aithe/aithe-ui';
+
+class PhoneFilter implements Filter<string, string> {
+  apply(value: string): string {
+    if (value == null || value.length !== 11) return value;
+    return `${value.slice(0, 3)}****${value.slice(7)}`;
+  }
+}
+
+filterFactory.register('phone', PhoneFilter);
+filterFactory.format('13812345678', 'phone');  // "138****5678"
+```
+
+> 完整文档见 [Filter 数据格式化](filter.md)。
+
+---
+
 ## 下一步
 
 - [主题系统](theming.md) — 25 种内置主题、8 种形状风格、9 种阴影风格、4 种排版风格、自定义主题
@@ -1085,5 +1150,6 @@ const locale: AitheLocale = 'zh-CN';
 - [DataHub 数据中间层](datahub.md) — 请求调度、缓存、去重、Mock
 - [语法高亮引擎](highlight.md) — 自研语法高亮引擎，多语言注册与自定义规则
 - [Markdown 模块](markdown.md) — 零依赖 Markdown 解析与渲染引擎
+- [Filter 数据格式化](filter.md) — 声明式过滤器表达式，零依赖数据格式化
 - [框架集成](framework-integration.md) — React / Vue / Angular / Svelte
-- [API 参考](api/summary.md) — 全部 85 个组件详细 API
+- [API 参考](api/summary.md) — 全部 103 个组件详细 API

package/docs/i18n.md

@@ -284,8 +284,6 @@ aitheUI.t('app.greeting', 'Hello, {name}!', { name: 'Alice' }); // 'Hello, Alice
 aitheUI.t('app.itemCount', '{count} items', { count: 5 }); // '5 items'
 ```
 
-翻译值也兼容函数类型，函数会在无参情况下被调用：
-
 ---
 
 ## 持久化
@@ -329,7 +327,7 @@ aitheUI.t('app.itemCount', '{count} items', { count: 5 }); // '5 items'
 
 ## 下一步
 
-- [主题系统](theming.md) — 22 种内置主题
+- [主题系统](theming.md) — 25 种内置主题
 - [使用指南](guide.md) — 组件通用 API
 - [框架集成](framework-integration.md) — React / Vue / Angular / Svelte
-- [API 参考](api/summary.md) — 全部 83 个组件详细 API
+- [API 参考](api/summary.md) — 全部 103 个组件详细 API

package/docs/issue/26.3.1/issue_26.3.1.0.md

@@ -0,0 +1,84 @@
+# Issue 26.3.1.0
+
+## 版本信息
+
+- **版本号**: 26.3.1.0
+- **基线版本**: 26.3.1
+- **类型**: 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-tree-menu` 的 `aithe-select` 事件 detail | `{ value: string }` | `{ value: string, item: AitheTreeNodeMeta }` |
+| `aithe-dropdown` 的 `aithe-select` 事件 | 组件 re-emit，detail 含 `{ item, path, id }` | 不再 re-emit，事件由 `aithe-tree-menu` 的 `composed: true` 自动穿透，detail 为 `{ value, item }` |
+| `aithe-sidebar` 的 `aithe-select` 事件 | 组件 re-emit | 不再 re-emit，事件由 `aithe-tree-menu` 的 `composed: true` 自动穿透 |
+| `aithe-tree-menu.selectItem` 参数 | `key: string` | `item: AitheTreeNodeMeta` |
+| `src/components/navigation/dropdown.ts` | 存在（旧版 dropdown） | 删除 |
+
+## 变更内容
+
+### 新增
+
+- **`aithe-tree-menu` 的 `collapsible` 属性** — 布尔属性，控制树菜单是否支持伸缩切换
+- **`aithe-tree-menu` 的 `collapsed` 属性** — 布尔属性（reflect），控制树菜单当前是否收起
+- **`aithe-tree-menu` 的 `collapsed-width` 属性** — 收起时的宽度，默认 `64px`
+- **`aithe-tree-menu` 的 `expanded-width` 属性** — 展开时的宽度，默认 `260px`
+- **`aithe-tree-menu` 的 `renderIcon` 方法** — 统一渲染图标逻辑，collapsed 无图标时显示首字母 fallback（`.fallback-icon` 样式）
+- **`aithe-tree-menu` collapsed 样式** — `:host([collapsed])` 下隐藏 `.item-label`/`.group-toggle-text`/`.arrow`；按钮居中；子菜单 `padding-left: 0`、`position: relative`、`z-index` 溢出显示
+- **`aithe-tree-menu` 选中背景内缩** — `.item.active` 增加 `padding: var(--aithe-space-1) var(--aithe-space-3)` 和 `margin: 0`
+- **`aithe-tree-menu` 宽度过渡动画** — `:host` 增加 `transition: width` 动画
+
+### 修改
+
+#### aithe-tree-menu 伸缩与事件改造
+
+- **`src/components/data/tree-menu.ts`** — 新增 `collapsible`/`collapsed`/`collapsedWidth`/`expandedWidth` 四个属性；`selectItem` 参数从 `key: string` 改为 `item: AitheTreeNodeMeta`，事件 detail 从 `{ value }` 改为 `{ value, item }`；新增 `renderIcon` 方法统一图标渲染逻辑；`handleDocumentPointer` 仅 horizontal 模式点击外部关闭；`renderItems` 中 group-toggle 和 leaf item 均改用 `renderIcon`；leaf item 标签包裹 `<span class="item-label">`；group-toggle 文本包裹 `<span class="group-toggle-text">`；collapsed 时按钮增加 `title` 属性；新增 `applyWidth` 方法和 `updated` 中监听 `collapsed`/`expandedWidth`/`collapsedWidth` 变化
+
+#### aithe-sidebar 改用 aithe-tree-menu
+
+- **`src/components/framework/sidebar.ts`** — 移除 `expanded` 状态、`collectKeys`/`isGroupActive`/`toggleExpand`/`selectItem`/`renderIcon`/`renderItems` 方法；移除 `.menu`/`.item`/`.item-icon`/`.fallback-icon`/`.item-label`/`.item.active`/`.group-toggle`/`.group-toggle-label`/`.group-toggle-icon`/`.group-toggle-text`/`.arrow`/`.children` 等大量 CSS 样式；center 区域改为 `<aithe-tree-menu>` 组件，传入 `items`/`active`/`expandAll`/`collapsible`/`collapsed`/`itemFilter`/`collapsedWidth`/`expandedWidth`；`handleTreeSelect` 仅更新 `this.active`；`:host([collapsed])` 增加 `overflow: visible`；`:host([collapsed]) .center` 增加 `overflow: visible`；移除 `classMap`/`translateNodeLabel` 导入
+
+#### aithe-dropdown 移除 findItemById
+
+- **`src/components/data/dropdown.ts`** — `handleTreeSelect` 不再 re-emit，仅关闭面板；移除 `findItemById` 递归方法；导入路径从相对路径改为 `@core/` 别名
+- **`src/components/navigation/dropdown.ts`** — 删除旧版 dropdown 文件
+
+#### aithe-theme-switch 用 item.category 替代遍历
+
+- **`src/components/theme/theme-switch.ts`** — `buildThemeMenu` 中 theme 组子项添加 `category: 'theme'`；shadow/shape/typo 子项分别添加 `category` 字段；`handleTreeSelect` 直接从 `item.category` 读取分类，移除遍历 `themeMenu`/`shadowMenu`/`shapeMenu`/`typoMenu` 的逻辑
+
+#### aithe-admin-layout 移除 findMenuNode
+
+- **`src/apps/admin/components/admin-layout.ts`** — `handleSidebarSelect` 直接使用 `e.detail.item` 替代 `findMenuNode` 递归查找；移除 `findMenuNode` 方法；`fetchMenuData` 调用加 `void`；`router.navigate` 调用加 `void`
+
+#### Admin 仪表盘取数修复
+
+- **`src/apps/admin/pages/dashboard-page.ts`** — 新增 `abortController` 属性；`fetchStats` 中每次请求前 abort 上一次、创建新 `AbortController`、传入 `signal`；请求后检查 `aborted` 跳过；双重解包防御（`res.data` 仍有 `data` 嵌套时自动解包）；`disconnectedCallback` 中 abort；loading URL 匹配从 `includes` 改为 `endsWith`
+
+#### 文档更新
+
+- **`docs/api/data/tree-menu.md`** — 新增 `collapsible`/`collapsed`/`collapsed-width`/`expanded-width` 属性文档；`itemRenderer` 说明；collapsed 模式行为说明；`aithe-select` 事件 detail 更新为 `{ value, item }`；事件传播说明（`composed: true`）
+- **`docs/api/data/dropdown.md`** — `aithe-select` 事件 detail 更新为 `{ value, item }`
+- **`docs/api/framework/sidebar.md`** — 新增 composed 透传说明
+- **`docs/api/theme/theme-switch.md`** — `category` 来自 `item.category` 说明
+
+### 删除
+
+- **`src/components/navigation/dropdown.ts`** — 删除旧版 dropdown 文件（已迁移至 `src/components/data/dropdown.ts`）
+- **`aithe-sidebar` 自有菜单渲染逻辑** — 移除 `renderItems`/`renderIcon`/`toggleExpand`/`selectItem`/`isGroupActive`/`collectKeys`/`expanded` 状态及对应 CSS 样式
+- **`aithe-dropdown` 的 `findItemById` 方法** — 移除递归查找方法
+- **`aithe-admin-layout` 的 `findMenuNode` 方法** — 移除递归查找方法

package/docs/issue/26.3.1/issue_26.3.1.1.md

@@ -0,0 +1,72 @@
+# Issue 26.3.1.1
+
+## 版本信息
+
+- **版本号**: 26.3.1.1
+- **基线版本**: 26.3.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`：移除冗余类型断言 `as AitheBuiltinTheme`；移除未使用的 `AitheBuiltinTheme` 导入
+   - `form-item.ts`：合并 `querySelector` 泛型与类型断言，移除中间变量
+   - `affix.ts` / `back-top.ts`：移除 `removeEventListener` 中多余的 `as EventListener` 断言
+   - `theme-preview.ts`：`value` 属性类型由 `AitheBuiltinTheme | string` 简化为 `string`；移除未使用的 `AitheBuiltinTheme` 导入
+   - `theme-switch.ts`：移除 `as ThemeCategory` 冗余类型断言
+   - `dedup.ts`：`data` 参数移除多余的 `| undefined` 联合类型
+   - `LoggerCore.ts`：移除 `payload as unknown[]` 冗余类型断言
+   - `index.ts`（i18n）：移除 `raw as AitheLocale` 冗余类型断言
+   - `plugins.ts`：所有 `String.match()` 替换为 `RegExp.exec()`
+
+## 破坏性变更
+
+| 变更项 | 旧值 | 新值 |
+|--------|------|------|
+| `AitheSidebarItemFilter` 类型名 | `AitheSidebarItemFilter` | `AitheTreeNodeFilter` |
+| `aithe-tree-menu.itemFilter` 默认值 | `null`（不过滤） | `(item) => item.hasPermission !== false`（过滤 `hasPermission: false` 的项） |
+
+## 变更内容
+
+### 新增
+
+- **`aithe-dropdown.itemFilter` 属性** — `src/components/data/dropdown.ts` 新增 `itemFilter: AitheTreeNodeFilter | null` 属性，透传给内部 `<aithe-tree-menu>`，支持上层使用者定制菜单项过滤
+- **`RawInlineNode` 类型** — `src/core/markdown/types.ts` 新增 `raw-inline` 节点类型定义，用于列表项内行内文本的二次解析
+- **`_resolveRawInlines` 方法** — `src/core/markdown/parser.ts` 新增私有方法，递归遍历 AST 将 `raw-inline` 节点解析为行内 AST 节点（粗体、链接等）
+- **`span` 节点渲染** — `src/core/markdown/parser.ts` `renderAst` 新增 `span` 类型处理，渲染子节点
+- **粗体 CSS 样式** — `src/components/display/markdown.ts` 新增 `.md-strong` 样式，`font-weight: 700`
+
+### 修改
+
+- **`src/core/types.ts`** — `AitheSidebarItemFilter` 类型重命名为 `AitheTreeNodeFilter`，JSDoc 同步更新
+- **`src/components/data/tree-menu.ts`** — 属性类型 `AitheSidebarItemFilter` → `AitheTreeNodeFilter`；`renderItems` 中 `itemFilter` 默认值改为 `(item) => item.hasPermission !== false`，当未设置自定义 filter 时自动过滤 `hasPermission: false` 的节点；`updated` 中 `collapsed`/`expandedWidth`/`collapsedWidth` 条件合并；`render` 中移除冗余的 `applyWidth` 调用（已由 `updated` 处理）
+- **`src/components/framework/sidebar.ts`** — 属性类型 `AitheSidebarItemFilter` → `AitheTreeNodeFilter`
+- **`src/components/data/dropdown.ts`** — 导入新增 `AitheTreeNodeFilter` 类型；模板中透传 `.itemFilter` 给内部 `<aithe-tree-menu>`
+- **`src/core/markdown/parser.ts`** — `parseBlocks` 末尾调用 `_resolveRawInlines`；`renderAst` 中 `paragraph` 渲染增加 `<p class="md-p">` 包裹；新增 `span` 节点渲染
+- **`src/core/markdown/plugins.ts`** — `listPlugin` 和 `taskListPlugin` 中列表项文本节点类型由 `text` 改为 `raw-inline`，以支持行内解析；所有 `String.match()` 替换为 `RegExp.exec()`（Sonar 规则 `prefer-regexp-exec`）
+- **`src/components/framework/dashboard.ts`** — CSS `border-radius` 使用 `--aithe-container-radius-lg` 替代 `--aithe-radius-lg`
+- **`src/components/display/markdown.ts`** — 新增 `.md-strong` CSS 样式
+- **`publish.js`** — Windows 平台兼容，spawn 增加 `shell: process.platform === 'win32'` 选项
+- **Sonar 技术债务修复**：
+  - **`src/apps/demo/pages/code.ts`** — LaTeX 字符串改用 `String.raw` 模板字面量，消除转义反斜杠
+  - **`src/components/display/code-editor.ts`** — 移除冗余类型断言 `as AitheBuiltinTheme` 及未使用的 `AitheBuiltinTheme` 导入
+  - **`src/components/form/form-item.ts`** — 合并 `querySelector` 泛型与类型断言，移除中间变量 `typedControl`
+  - **`src/components/layout/affix.ts`** — 移除 `removeEventListener` 中多余的 `as EventListener` 断言
+  - **`src/components/navigation/back-top.ts`** — 同上
+  - **`src/components/theme/theme-preview.ts`** — `value` 属性类型由 `AitheBuiltinTheme | string` 简化为 `string`；移除未使用的 `AitheBuiltinTheme` 导入
+  - **`src/components/theme/theme-switch.ts`** — 移除 `as ThemeCategory` 冗余类型断言
+  - **`src/core/datahub/utils/dedup.ts`** — `data` 参数移除多余的 `| undefined` 联合类型
+  - **`src/core/logger/LoggerCore.ts`** — 移除 `payload as unknown[]` 冗余类型断言
+  - **`src/styles/i18n/index.ts`** — 移除 `raw as AitheLocale` 冗余类型断言
+- **`docs/api/data/tree-menu.md`** — `item-filter` 属性 Default 改为"内置默认值"，描述补充默认过滤逻辑；Data Item Fields 新增 `hasPermission` 字段
+- **`docs/api/framework/sidebar.md`** — 同上
+- **`docs/api/data/dropdown.md`** — Properties 表格新增 `item-filter` 属性行