@aithe/aithe-ui 26.2.2 → 26.3.1

package/docs/api/basic/button.md

@@ -1,38 +1,66 @@
 # AitheButton / AitheButton 按钮
 
-> Button component with multiple visual types, sizes, and states.
-> 按钮组件，支持多种视觉类型、尺寸和状态。
+> Button component with multiple visual types, sizes, and states. When `href` is set, renders as an `<a>` element for native link behavior.
+> 按钮组件，支持多种视觉类型、尺寸和状态。设置 `href` 后渲染为 `<a>` 元素以获得原生链接行为。
 
 ## Slots / 插槽
 
-| Name | Description (EN) | Description (CN) |
-|------|-------------------|-------------------|
-| (default) | Default slot for button label. | 默认插槽，用于按钮标签。 |
-| prefix | Icon or content before the label. | 标签前的图标或内容。 |
-| suffix | Icon or content after the label. | 标签后的图标或内容。 |
+| Name      | Description (EN)                  | Description (CN)         |
+| --------- | --------------------------------- | ------------------------ |
+| (default) | Default slot for button label.    | 默认插槽，用于按钮标签。 |
+| prefix    | Icon or content before the label. | 标签前的图标或内容。     |
+| suffix    | Icon or content after the label.  | 标签后的图标或内容。     |
 
 ## Properties / 属性
 
-| Name | Type | Default | Description (EN) | Description (CN) |
-|------|------|---------|-------------------|-------------------|
-| type | `'primary' \| 'default' \| 'dashed' \| 'text' \| 'link'` | `'default'` | Visual type of the button. | 按钮的视觉类型。 |
-| size | `'small' \| 'medium' \| 'large'` | `'medium'` | Size scale of the button. | 按钮的尺寸规格。 |
-| title | `string` | `''` | Display title (shown as tooltip). | 显示标题（作为工具提示）。 |
-| icon | `string` | `''` | Icon name to display before the label. | 在标签前显示的图标名称。 |
-| disabled | `boolean` | `false` | Whether the button is disabled. | 按钮是否禁用。 |
-| loading | `boolean` | `false` | Whether the button shows a loading spinner. | 按钮是否显示加载旋转器。 |
-| danger | `boolean` | `false` | Whether the button uses danger styling. | 按钮是否使用危险样式。 |
-| block | `boolean` | `false` | Whether the button spans the full width of its container. | 按钮是否占满容器宽度。 |
+| Name     | Type                                                     | Default     | Description (EN)                                                                      | Description (CN)                                          |
+| -------- | -------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------- | --------------------------------------------------------- |
+| variant  | `'default' \| 'primary' \| 'danger' \| 'success' \| 'warning' \| 'neutral'` | `'default'` | Color intent of the button. Controls emphasis and semantic color.                     | 按钮的颜色意图。控制强调程度和语义色。                    |
+| type     | `'default' \| 'dashed' \| 'text' \| 'link'`              | `'default'` | Appearance style of the button.                                                       | 按钮的外观风格。                                          |
+| size     | `'small' \| 'medium' \| 'large'`                         | `'medium'`  | Size scale of the button.                                                             | 按钮的尺寸规格。                                          |
+| title    | `string`                                                 | `''`        | Display title (shown as tooltip).                                                     | 显示标题（作为工具提示）。                                |
+| icon     | `string`                                                 | `''`        | Icon name to display before the label.                                                | 在标签前显示的图标名称。                                  |
+| disabled | `boolean`                                                | `false`     | Whether the button is disabled.                                                       | 按钮是否禁用。                                            |
+| loading  | `boolean`                                                | `false`     | Whether the button shows a loading spinner.                                           | 按钮是否显示加载旋转器。                                  |
+| block    | `boolean`                                                | `false`     | Whether the button spans the full width of its container.                             | 按钮是否占满容器宽度。                                    |
+| href     | `string`                                                 | `''`        | Link URL. When set, the button renders as an `<a>` element with native link behavior. | 链接地址。设置后按钮渲染为 `<a>` 元素，具有原生链接行为。 |
+| target   | `string`                                                 | `''`        | Link target attribute (e.g. `_blank`). Only applies when `href` is set.               | 链接 target 属性（如 `_blank`）。仅在设置 `href` 时生效。 |
 
 ## Events / 事件
 
-| Name | Detail | Description (EN) | Description (CN) |
-|------|--------|-------------------|-------------------|
-| aithe-click | `{ originalEvent: MouseEvent }` | Emitted when the button is clicked (not when disabled/loading). | 按钮被点击时发出（禁用/加载时不发出）。 |
+| Name        | Detail                          | Cancelable | Description (EN)                                                                                                                                     | Description (CN)                                                                                    |
+| ----------- | ------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| aithe-click | `{ originalEvent: MouseEvent }` | Yes        | Emitted when the button is clicked (not when disabled/loading). When `href` is set, navigation runs by default; call `preventDefault()` to suppress. | 按钮被点击时发出（禁用/加载时不发出）。设置 `href` 后默认执行导航；调用 `preventDefault()` 可阻止。 |
 
 ## Examples / 示例
 
+### Basic buttons / 基础按钮
+
+```html
+<aithe-button variant="primary" size="medium" title="Submit form" icon="check">Submit</aithe-button>
+<aithe-button variant="danger" loading>Deleting...</aithe-button>
+<aithe-button type="dashed">Dashed</aithe-button>
+<aithe-button type="text">Text</aithe-button>
+<aithe-button type="link">Link</aithe-button>
+```
+
+### Link button / 链接按钮
+
 ```html
-<aithe-button type="primary" size="medium" title="Submit form" icon="check">Submit</aithe-button>
-<aithe-button type="danger" loading>Deleting...</aithe-button>
-```
+<aithe-button variant="primary" href="/dashboard">Go to Dashboard</aithe-button>
+<aithe-button href="https://example.com" target="_blank">External Link</aithe-button>
+```
+
+No event listener is required — the component navigates to `href` internally by default.
+
+无需监听事件 — 组件默认在内部导航到 `href`。
+
+### Custom click handling (prevent default navigation) / 自定义点击处理（阻止默认导航）
+
+```js
+const button = document.querySelector('aithe-button');
+button.addEventListener('aithe-click', (e) => {
+  e.preventDefault();
+  console.log('Click intercepted, navigation suppressed');
+});
+```

package/docs/api/basic/icon.md

@@ -2,6 +2,8 @@
 
 > Vector icon entry for the Aithe UI icon system. Renders an SVG glyph from the built-in icon map based on the `name` property. All icons use a 24×24 viewBox, stroke-based rendering with `stroke-width: 1.8`, and inherit color via `currentColor`.
 > 矢量图标组件，用于 Aithe UI 图标系统。根据 `name` 属性从内置图标映射中渲染 SVG 图形。所有图标使用 24×24 视口，基于描边渲染（stroke-width: 1.8），颜色继承 currentColor。
+>
+> For `auto` and `url` types, rendering is delegated to `IconUtil.render`. Size presets are resolved via `IconUtil.resolveSize` against `ICON_SIZE_MAP`. `auto` 和 `url` 类型委托给 `IconUtil.render` 渲染。尺寸预设通过 `IconUtil.resolveSize` 结合 `ICON_SIZE_MAP` 解析。
 
 ## Slots / 插槽
 
@@ -13,9 +15,9 @@
 
 | Name | Type | Default | Description (EN) | Description (CN) |
 |------|------|---------|-------------------|-------------------|
-| name | `string` | `'sparkles'` | Icon glyph name from the built-in map. If the name is not found, renders an empty SVG. | 内置图标名称。若名称不存在，渲染空 SVG。 |
+| name | `string` | `'sparkles'` | Icon glyph name or extended format. Supports built-in names (e.g. `sparkles`), or extended `(type)value` syntax. See [Extended Name Format](#extended-name-format--扩展名称格式) below. | 图标名称或扩展格式。支持内置名称或扩展 `(type)value` 语法。详见下方扩展名称格式。 |
 | color | `string` | `''` | Custom stroke/fill color. When empty, falls back to `currentColor` (inherits from parent). | 自定义颜色。为空时继承父元素 currentColor。 |
-| size | `string` | `'md'` | Icon size. Accepts preset aliases (`sm` → 14px, `md` → 18px, `lg` → 22px) or any explicit CSS value (e.g. `"32px"`, `"2rem"`). Bare numbers get `px` appended. | 图标尺寸。支持预设别名（sm→14px, md→18px, lg→22px）或显式 CSS 值。纯数字自动追加 px。 |
+| size | `string` | `'md'` | Icon size. Accepts preset aliases or any explicit CSS value. Resolved via `IconUtil.resolveSize` against `ICON_SIZE_MAP`. See [Size Presets](#size-presets--尺寸预设) below. | 图标尺寸。支持预设别名或显式 CSS 值。通过 `IconUtil.resolveSize` 结合 `ICON_SIZE_MAP` 解析。详见下方尺寸预设。 |
 
 ## Events / 事件
 
@@ -27,16 +29,23 @@
 
 | Variable | Default | Description (EN) | Description (CN) |
 |----------|---------|-------------------|-------------------|
-| `--aithe-icon-size` | `18px` | Controls the SVG width/height. Set dynamically from the `size` property. | 控制 SVG 宽高。由 `size` 属性动态设置。 |
+| `--aithe-icon-size` | `20px` | Controls the SVG width/height. Set dynamically from the `size` property. | 控制 SVG 宽高。由 `size` 属性动态设置。 |
 | `--aithe-icon-color` | `currentColor` | Controls the host `color` which cascades to `stroke: currentColor`. | 控制宿主 `color`，级联至 `stroke: currentColor`。 |
 
 ## Size Presets / 尺寸预设
 
 | Preset | Pixel Value | Description (EN) | Description (CN) |
 |--------|-------------|-------------------|-------------------|
-| `sm` | 14px | Small icon for inline text or tight layouts. | 小图标，用于行内文本或紧凑布局。 |
-| `md` | 18px | Default medium icon. | 默认中等图标。 |
-| `lg` | 22px | Large icon for headings or standalone display. | 大图标，用于标题或独立展示。 |
+| `xs` | 12px | Extra small for dense inline text. | 超小，用于紧凑行内文本。 |
+| `sm` | 16px | Small icon for inline text or tight layouts. | 小图标，用于行内文本或紧凑布局。 |
+| `md` | 20px | Default medium icon. | 默认中等图标。 |
+| `lg` | 24px | Large icon for headings or standalone display. | 大图标，用于标题或独立展示。 |
+| `xl` | 28px | Extra large for section headers. | 超大，用于章节标题。 |
+| `2xl` | 32px | Double extra large. | 2 倍超大。 |
+| `3xl` | 48px | Triple extra large for hero areas. | 3 倍超大，用于主视觉区域。 |
+| `4xl` | 64px | 4× extra large. | 4 倍超大。 |
+| `5xl` | 96px | 5× extra large. | 5 倍超大。 |
+| `6xl` | 128px | Maximum preset for large displays. | 最大预设，用于大屏展示。 |
 
 You can also pass any valid CSS dimension (e.g. `"32px"`, `"2rem"`, `"24"` → `24px`).
 也可以传入任意合法 CSS 尺寸值（如 `"32px"`、`"2rem"`、`"24"` → `24px`）。
@@ -174,8 +183,27 @@ You can also pass any valid CSS dimension (e.g. `"32px"`, `"2rem"`, `"24"` → `
 - **Stroke-based**: `fill: none`, `stroke: currentColor`, `stroke-width: 1.8`, `stroke-linecap: round`, `stroke-linejoin: round`.
 - **Unknown name**: If `name` does not match any entry in the icon map, the SVG renders with no glyph (empty).
 - **Slot override**: Content placed in the default slot replaces the built-in glyph entirely.
+- **Delegated types**: `auto` and `url` types are delegated to `IconUtil.render` for unified rendering.
+- **Size resolution**: Size presets are resolved via `IconUtil.resolveSize` against `ICON_SIZE_MAP`.
+- **Remote image fallback**: When a `(url)` / `(share)` / `(remote)` image fails to load, the alt text first character is shown as a placeholder. If no alt text is provided, no fallback is displayed.
+- **Extended format**: See [Extended Name Format](#extended-name-format--扩展名称格式).
 
-所有图标在 `<svg viewBox="0 0 24 24">` 内渲染。基于描边：fill: none, stroke: currentColor, stroke-width: 1.8。未知名称渲染空 SVG。默认插槽内容覆盖内置图形。
+ 所有图标在 `<svg viewBox="0 0 24 24">` 内渲染。基于描边：fill: none, stroke: currentColor, stroke-width: 1.8。未知名称渲染空 SVG。默认插槽内容覆盖内置图形。`auto` 和 `url` 类型委托给 `IconUtil.render` 统一渲染。尺寸预设通过 `IconUtil.resolveSize` 结合 `ICON_SIZE_MAP` 解析。远程图片加载失败时显示 alt 首字符占位（无 alt 则不显示）。
+
+## Extended Name Format / 扩展名称格式
+
+The `name` property supports an extended syntax: `(type)value`. This allows `<aithe-icon>` to render not only built-in SVG glyphs but also auto-generated text avatars and remote images.
+`name` 属性支持扩展语法 `(type)value`，使 `<aithe-icon>` 不仅能渲染内置 SVG 图形，还能渲染文本首字母头像和远程图片。
+
+| Format | Type | Description (EN) | Description (CN) |
+|--------|------|-------------------|-------------------|
+| `sparkles` | `class` | Bare name — built-in SVG icon (default). | 裸名称 — 内置 SVG 图标（默认）。 |
+| `(class)sparkles` | `class` | Explicit built-in SVG icon. | 显式指定内置 SVG 图标。 |
+| `(auto)User Name` | `auto` | Auto-generate from the first character of the text. | 取文本首字符自动生成图标。 |
+| `(url)https://example.com/icon.svg` | `url` | Load icon from a URL via `<img>`. | 通过 URL 加载图标。 |
+| `(url)https://example.com/icon.svg\|Alt` | `url` | Load from URL with alt fallback. Shows "A" on load failure. | 从 URL 加载，带 alt 占位，加载失败时显示 "A"。 |
+| `(share)https://example.com/icon.svg` | `share` | Alias for `url`. | `url` 的别名。 |
+| `(remote)https://example.com/icon.svg` | `remote` | Alias for `url`. | `url` 的别名。 |
 
 ## Examples / 示例
 
@@ -190,9 +218,16 @@ You can also pass any valid CSS dimension (e.g. `"32px"`, `"2rem"`, `"24"` → `
 ### Size presets / 尺寸预设
 
 ```html
+<aithe-icon name="search" size="xs"></aithe-icon>
 <aithe-icon name="search" size="sm"></aithe-icon>
 <aithe-icon name="search" size="md"></aithe-icon>
 <aithe-icon name="search" size="lg"></aithe-icon>
+<aithe-icon name="search" size="xl"></aithe-icon>
+<aithe-icon name="search" size="2xl"></aithe-icon>
+<aithe-icon name="search" size="3xl"></aithe-icon>
+<aithe-icon name="search" size="4xl"></aithe-icon>
+<aithe-icon name="search" size="5xl"></aithe-icon>
+<aithe-icon name="search" size="6xl"></aithe-icon>
 <aithe-icon name="search" size="32px"></aithe-icon>
 ```
 
@@ -242,4 +277,25 @@ You can also pass any valid CSS dimension (e.g. `"32px"`, `"2rem"`, `"24"` → `
     <path d="M8 12l4 4 4-8"></path>
   </svg>
 </aithe-icon>
-```
+```
+
+### Extended format: auto-generated text / 扩展格式：文本首字母
+
+```html
+<aithe-icon name="(auto)User Name" size="md"></aithe-icon>
+<aithe-icon name="(auto)A" size="lg"></aithe-icon>
+```
+
+### Extended format: remote image / 扩展格式：远程图片
+
+```html
+<aithe-icon name="(url)https://example.com/icon.svg" size="md"></aithe-icon>
+<aithe-icon name="(share)https://example.com/icon.svg" size="lg"></aithe-icon>
+```
+
+### Extended format: remote image with alt fallback / 扩展格式：远程图片带 alt 占位
+
+```html
+<aithe-icon name="(url)https://example.com/icon.svg|User" size="md"></aithe-icon>
+<aithe-icon name="(url)https://example.com/icon.svg|A" size="lg"></aithe-icon>
+```

package/docs/api/basic/tag.md

@@ -5,30 +5,37 @@
 
 ## Slots / 插槽
 
-| Name | Description (EN) | Description (CN) |
-|------|-------------------|-------------------|
-| (default) | Default slot for tag label text. | 标签文本内容。 |
+| Name      | Description (EN)                 | Description (CN) |
+| --------- | -------------------------------- | ---------------- |
+| (default) | Default slot for tag label text. | 标签文本内容。   |
 
 ## Properties / 属性
 
-| Name | Type | Default | Description (EN) | Description (CN) |
-|------|------|---------|-------------------|-------------------|
-| type | `'primary' \| 'success' \| 'warning' \| 'danger' \| 'default'` | `'default'` | Tag color variant. | 标签颜色类型。 |
-| closable | `boolean` | `false` | Whether the tag shows a close button. Clicking it animates and removes the tag from DOM. | 是否显示关闭按钮。点击后动画移除标签。 |
-| selectable | `boolean` | `false` | Whether the tag can be toggled (selected/unselected). | 是否可选中切换。 |
-| selected | `boolean` | `false` | Whether the tag is currently selected. | 当前是否选中。 |
-| rounded | `'sm' \| 'md' \| 'lg' \| 'full'` | `'full'` | Border-radius preset. | 圆角预设。 |
-| disabled | `boolean` | `false` | Whether the tag is disabled. | 是否禁用。 |
+| Name       | Type                                                                        | Default     | Description (EN)                                                                         | Description (CN)                                    |
+| ---------- | --------------------------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------- | --------------------------------------------------- |
+| variant    | `'default' \| 'primary' \| 'success' \| 'warning' \| 'danger' \| 'neutral'` | `'default'` | Color intent of the tag. Inherited from `AitheElement`. Controls semantic color.         | 标签的颜色意图。继承自 `AitheElement`。控制语义色。 |
+| type       | `'primary' \| 'success' \| 'warning' \| 'danger' \| 'default'`              | `'success'` | _(Deprecated)_ Tag color variant. Use `variant` instead.                                 | _(已废弃)_ 标签颜色类型。请使用 `variant` 代替。    |
+| size       | `'sm' \| 'md' \| 'lg'`                                                      | `'sm'`      | Size preset of the tag.                                                                  | 标签的尺寸预设。                                    |
+| closable   | `boolean`                                                                   | `false`     | Whether the tag shows a close button. Clicking it animates and removes the tag from DOM. | 是否显示关闭按钮。点击后动画移除标签。              |
+| selectable | `boolean`                                                                   | `false`     | Whether the tag can be toggled (selected/unselected).                                    | 是否可选中切换。                                    |
+| selected   | `boolean`                                                                   | `false`     | Whether the tag is currently selected.                                                   | 当前是否选中。                                      |
+| rounded    | `'sm' \| 'md' \| 'lg' \| 'full'`                                            | `'full'`    | Border-radius preset.                                                                    | 圆角预设。                                          |
+| disabled   | `boolean`                                                                   | `false`     | Whether the tag is disabled.                                                             | 是否禁用。                                          |
 
 ## Events / 事件
 
-| Name | Detail | Description (EN) | Description (CN) |
-|------|--------|-------------------|-------------------|
-| aithe-change | `{ selected }` | Emitted when selectable tag is toggled. | 选中状态变更时触发。 |
-| aithe-close | — | Emitted when the close button is clicked, before the tag is removed from DOM. | 关闭按钮点击时触发，在标签从 DOM 移除之前。 |
+| Name         | Detail         | Description (EN)                                                              | Description (CN)                            |
+| ------------ | -------------- | ----------------------------------------------------------------------------- | ------------------------------------------- |
+| aithe-change | `{ selected }` | Emitted when selectable tag is toggled.                                       | 选中状态变更时触发。                        |
+| aithe-close  | —              | Emitted when the close button is clicked, before the tag is removed from DOM. | 关闭按钮点击时触发，在标签从 DOM 移除之前。 |
 
 ## Examples / 示例
 
 ```html
-<aithe-tag type="primary" closable>Selectable Tag</aithe-tag>
-```
+<aithe-tag variant="primary" closable>Selectable Tag</aithe-tag>
+<aithe-tag variant="success">Success</aithe-tag>
+<aithe-tag variant="warning">Warning</aithe-tag>
+<aithe-tag variant="danger">Danger</aithe-tag>
+<aithe-tag size="sm">Small</aithe-tag>
+<aithe-tag size="lg">Large</aithe-tag>
+```

package/docs/api/data/box-table.md

@@ -0,0 +1,73 @@
+# AitheBoxTable / AitheBoxTable 盒子表格
+
+> Dual-mode table/box data display with sorting, selection, and box grid view.
+> 双模式表格/盒子数据展示，支持排序、选择和盒子网格视图。
+
+AitheBoxTable extends AitheTable with a `mode` property. When `mode="table"`, it behaves like a standard table. When `mode="box"`, it renders records as a grid of cards using box layout.
+AitheBoxTable 扩展 AitheTable，增加 `mode` 属性。当 `mode="table"` 时，行为与标准表格一致。当 `mode="box"` 时，使用盒子布局将记录渲染为卡片网格。
+
+## Column Box Mapping / 列 Box 映射
+
+In box mode, columns with a `box` property map their data to the corresponding box slot:
+
+| box value | Box slot | Description |
+|-----------|----------|-------------|
+| `"name"` | Name/title region | 主标签/标题区域 |
+| `"status"` | Status indicator | 状态指示器区域 |
+| `"tags"` | Tags region | 标签区域 |
+| `"content"` | Content region | 内容区域 |
+| `"actions"` | Actions region | 操作按钮区域 |
+
+## Properties / 属性
+
+| Name | Type | Default | Description (EN) | Description (CN) |
+|------|------|---------|-------------------|-------------------|
+| mode | 'table' \| 'box' | 'table' | Display mode: "table" for standard table view, "box" for box grid view. | 显示模式："table" 为标准表格视图，"box" 为盒子网格视图。 |
+| boxCols | Number | 3 | Number of box columns in box mode (1–12). | 盒子模式下每行显示的盒子数（1–12）。 |
+
+All properties from `aithe-table` are also inherited (see [Table API](table.md)).
+所有 `aithe-table` 的属性也继承自（参见 [Table API](table.md)）。
+
+## Events / 事件
+
+| Name | Detail | Description (EN) | Description (CN) |
+|------|--------|-------------------|-------------------|
+| aithe-sort-change | { sortKey, sortOrder } | Emitted when a sortable column header is clicked. | 可排序列头被点击时触发。 |
+| aithe-selection-change | { selectionSet } | Emitted when row selection changes. | 行选择变更时触发。 |
+| aithe-row-click | { record, rowIndex } | Emitted when a box is clicked. | 点击 box 时触发。 |
+
+## Examples / 示例
+
+### Basic box mode / 基本盒子模式
+
+```html
+<aithe-box-table
+  mode="box"
+  box-cols="3"
+  columns='[{"id":"name","title":"Module","box":"name"},{"id":"owner","title":"Owner","box":"tags"},{"id":"status","title":"Status","box":"status"}]'
+  data='[{"id":1,"name":"Theme Engine","owner":"Design Systems","status":"Ready"},{"id":2,"name":"Component API","owner":"Frontend Platform","status":"Review"}]'
+></aithe-box-table>
+```
+
+### Box mode with selection / 盒子模式 + 选择
+
+```html
+<aithe-box-table
+  mode="box"
+  box-cols="3"
+  selectable="multi"
+  .selectionSet=${mySet}
+  columns='[{"id":"name","title":"Module","box":"name"},{"id":"status","title":"Status","box":"status"}]'
+  data='[{"id":1,"name":"Theme Engine","status":"Ready"},{"id":2,"name":"Component API","status":"Review"}]'
+></aithe-box-table>
+```
+
+### Table mode (standard) / 表格模式（标准）
+
+```html
+<aithe-box-table
+  mode="table"
+  columns='[{"id":"name","title":"Name","sortable":true},{"id":"owner","title":"Owner"}]'
+  data='[{"name":"Alice","owner":"Team A"},{"name":"Bob","owner":"Team B"}]'
+></aithe-box-table>
+```

package/docs/api/data/dropdown.md

@@ -0,0 +1,74 @@
+# AitheDropdown / AitheDropdown 下拉菜单
+
+> Dropdown menu with nested submenus, keyboard navigation, and hover/click triggers.
+> Internally uses `<aithe-tree-menu>` for menu rendering.
+> 下拉菜单，支持嵌套子菜单、键盘导航和悬停/点击触发。内部使用 `<aithe-tree-menu>` 渲染菜单。
+
+## Slots / 插槽
+
+| Name      | Description (EN)                      | Description (CN) |
+| --------- | ------------------------------------- | ---------------- |
+| (default) | Default slot for the trigger element. | 触发元素内容。   |
+
+## Properties / 属性
+
+| Name      | Type                                                       | Default        | Description (EN)                                                                                   | Description (CN)                                                      |
+| --------- | ---------------------------------------------------------- | -------------- | -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| trigger   | 'click' \| 'hover'                                         | 'click'        | Trigger mode: click or hover.                                                                      | 触发方式：点击或悬停。                                                |
+| title     | `string`                                                   | `''`           | Display title (shown as tooltip).                                                                  | 显示标题（作为工具提示）。                                            |
+| icon      | `string`                                                   | `''`           | Icon name to display before the trigger slot content.                                              | 在触发器插槽内容前显示的图标名称。                                    |
+| itemsJson | String                                                     | ''             | JSON string of dropdown menu items.                                                                | 下拉菜单项的 JSON 字符串。                                            |
+| items     | AitheTreeNodeMeta[]                                        | []             | Array of dropdown menu item objects. Each item supports `icon` and `variant` (AitheVariant) fields. | 下拉菜单项对象数组。每项支持 `icon` 和 `variant`（AitheVariant）字段。 |
+| placement | 'bottom-start' \| 'bottom-end' \| 'top-start' \| 'top-end' | 'bottom-start' | Dropdown panel placement. Auto-adapts to viewport.                                                 | 下拉面板位置。自动适应视口。                                          |
+| item-filter | `AitheTreeNodeFilter \| null` | 内置默认值 | Filter callback for menu items. Return `true` to show, `false` to hide. Defaults to `(item) => item.hasPermission !== false` — items with `hasPermission: false` are hidden. Useful for permission control. | 菜单项过滤回调。返回 `true` 显示，`false` 隐藏。默认值为 `(item) => item.hasPermission !== false` — 设置 `hasPermission: false` 的项会被隐藏。适用于权限控制。 |
+| offset    | `number`                                                   | 8              | Pixel gap between anchor and dropdown panel.                                                       | 锚点与下拉面板之间的像素间距。                                        |
+
+## Events / 事件
+
+| Name              | Detail             | Description (EN)                      | Description (CN)     |
+| ----------------- | ------------------ | ------------------------------------- | -------------------- |
+| aithe-select      | `{ value, item }` | Emitted when a menu item is selected. Propagated from the inner `<aithe-tree-menu>` (composed event). `value` is the item's `id`, `item` is the full `AitheTreeNodeMeta` object. | 菜单项选中时触发。由内部 `<aithe-tree-menu>` 透传（composed 事件）。`value` 为项的 `id`，`item` 为完整的 `AitheTreeNodeMeta` 对象。 |
+| aithe-dropdown-change | { open }           | Emitted when open state changes.      | 开关状态变更时触发。 |
+
+## Item Fields / 菜单项字段
+
+| Field    | Type                | Description (EN)                                                                                                      | Description (CN)                                                           |
+| -------- | ------------------- | --------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| label    | `string`            | Display text. Used as i18n fallback when `i18n` is set.                                                               | 显示文本。设置 `i18n` 时作为缺省值。                                       |
+| id       | `string`            | Unique value emitted on select.                                                                                       | 选择时发出的唯一值。                                                       |
+| type     | `'item' \| 'divider' \| 'theme'` | Node type: `item` (default), `divider` (visual separator), `theme` (embedded theme picker).              | 节点类型：`item`（默认）、`divider`（视觉分隔线）、`theme`（嵌入主题选择器）。 |
+| disabled | `boolean`           | Whether the item is non-interactive.                                                                                  | 是否不可交互。                                                             |
+| variant  | AitheVariant        | Visual variant / semantic color for the item.                                                                         | 项的视觉变体/语义色。                                                      |
+| shortcut | `string`            | Keyboard shortcut hint.                                                                                               | 键盘快捷键提示。                                                           |
+| icon     | `string`            | Icon name rendered before the label via aithe-icon.                                                                   | 通过 aithe-icon 在标签前渲染的图标名称。                                   |
+| children | AitheTreeNodeMeta[] | Nested sub-menu items.                                                                                                | 嵌套子菜单项。                                                             |
+| i18n     | `string`            | i18n translation key. When set, `t(i18n, label)` is used to translate the label; `label` serves as the default value. | 国际化翻译键。设置后通过 `t(i18n, label)` 翻译 label，`label` 作为缺省值。 |
+
+## Examples / 示例
+
+### Basic usage / 基础用法
+
+```html
+<aithe-dropdown
+  trigger="click"
+  title="Actions"
+  icon="menu"
+  items='[{"id":"a","label":"Action"},{"id":"b","label":"Another"}]'
+>
+  <button>Menu</button>
+</aithe-dropdown>
+```
+
+### With i18n / 国际化
+
+```html
+<aithe-dropdown
+  items='[{"id":"a","label":"Action","i18n":"app.menu.action"},{"id":"b","label":"Another","i18n":"app.menu.another"}]'
+>
+  <button>Menu</button>
+</aithe-dropdown>
+```
+
+When `i18n` is set, the component automatically translates the label via `t(i18n, label)`. The `label` field serves as the fallback default value when the translation key is not found.
+
+设置 `i18n` 后，组件自动通过 `t(i18n, label)` 翻译 label。`label` 字段作为翻译键未找到时的缺省值。

package/docs/api/data/metrics-group.md

@@ -0,0 +1,120 @@
+# AitheMetricsGroup / AitheMetricsGroup 业务指标组
+
+> Container that groups multiple `<aithe-metrics>` children with configurable layout direction and gap.
+> 业务指标组容器，以水平或垂直方向排列多个 `<aithe-metrics>` 子元素，支持自定义间距。
+
+## Import / 引入
+
+```ts
+import '@aithe/aithe-ui/components/data/metrics-group';
+```
+
+## Description / 描述
+
+`<aithe-metrics-group>` is a flex container that lays out its `<aithe-metrics>` children in either a horizontal row or vertical column. The `gap` property controls spacing between items. It is designed for use inside `<aithe-dashboard-panel>` or any card context where multiple metrics need to be grouped together.
+
+`<aithe-metrics-group>` 是一个 flex 容器，将其 `<aithe-metrics>` 子元素按水平行或垂直列排列。`gap` 属性控制项之间的间距。设计用于 `<aithe-dashboard-panel>` 内部或任何需要将多个指标组合在一起的卡片场景。
+
+## Slots / 插槽
+
+| Name      | Description (EN)                              | Description (CN)                 |
+| --------- | --------------------------------------------- | -------------------------------- |
+| (default) | One or more `<aithe-metrics>` elements.       | 一个或多个 `<aithe-metrics>` 元素。 |
+
+## CSS Parts / CSS 部件
+
+| Name      | Description (EN)                          | Description (CN)       |
+| --------- | ----------------------------------------- | ---------------------- |
+| container | The flex container wrapping the metrics.  | 包裹指标的 flex 容器。 |
+
+## Properties / 属性
+
+| Name      | Type                                             | Default        | Attribute   | Description (EN)                                                       | Description (CN)                          |
+| --------- | ------------------------------------------------ | -------------- | ----------- | ---------------------------------------------------------------------- | ----------------------------------------- |
+| direction | `'horizontal' \| 'vertical'`                     | `'horizontal'` | `direction` | Layout direction of the metrics group.                                 | 指标组的排列方向。                        |
+| gap       | `number`                                         | `16`           | `gap`       | Gap between metrics items, in pixels.                                  | 指标项之间的间距，单位为像素。            |
+| align     | `'left' \| 'center' \| 'right'`                  | `'left'`       | `align`     | Alignment of items within the group (only effective when vertical).    | 指标项在组内的对齐方式（仅在垂直时生效）。|
+| data      | `MetricsData \| MetricsData[] \| null`           | `null`         | —           | Data-driven mode: auto-renders children. Single object wraps to array. | 数据驱动模式：自动渲染子元素。单个对象自动转为数组。 |
+| params    | `MetricsGroupParams`                             | `{}`           | —           | Generic config object. Overrides `direction`, `gap`, `align` for overlapping keys. | 通用配置对象。同名键覆盖 `direction`/`gap`/`align`。 |
+
+## Usage / 用法
+
+### Horizontal Group / 水平排列
+
+```html
+<aithe-metrics-group direction="horizontal" gap="32">
+  <aithe-metrics label="Users" value="1,024" variant="primary"></aithe-metrics>
+  <aithe-metrics label="Revenue" value="$42.5K" variant="success"></aithe-metrics>
+  <aithe-metrics label="Errors" value="3" variant="danger"></aithe-metrics>
+</aithe-metrics-group>
+```
+
+### Vertical Group / 垂直排列
+
+```html
+<aithe-metrics-group direction="vertical" gap="12">
+  <aithe-metrics label="CPU Usage" value="23%" variant="neutral"></aithe-metrics>
+  <aithe-metrics label="Memory" value="1.2 GB" variant="neutral"></aithe-metrics>
+  <aithe-metrics label="Disk" value="45% Used" variant="warning"></aithe-metrics>
+</aithe-metrics-group>
+```
+
+### Vertical Alignment / 垂直对齐方式
+
+```html
+<aithe-metrics-group direction="vertical" gap="8" align="left">
+  <aithe-metrics label="Left Aligned" value="100" variant="primary"></aithe-metrics>
+  <aithe-metrics label="Left Aligned" value="200" variant="success"></aithe-metrics>
+</aithe-metrics-group>
+
+<aithe-metrics-group direction="vertical" gap="8" align="center">
+  <aithe-metrics label="Centered" value="100" variant="primary"></aithe-metrics>
+  <aithe-metrics label="Centered" value="200" variant="success"></aithe-metrics>
+</aithe-metrics-group>
+
+<aithe-metrics-group direction="vertical" gap="8" align="right">
+  <aithe-metrics label="Right Aligned" value="100" variant="primary"></aithe-metrics>
+  <aithe-metrics label="Right Aligned" value="200" variant="success"></aithe-metrics>
+</aithe-metrics-group>
+```
+
+### Inside Dashboard Panel / 在仪表盘面板中使用
+
+```html
+<aithe-dashboard-panel panel-id="stats" x="0" y="0" w="4" h="3" label="Statistics">
+  <aithe-metrics-group direction="vertical" gap="4" style="padding:8px;">
+    <aithe-metrics label="Active Users" value="1,024" variant="primary"></aithe-metrics>
+    <aithe-metrics label="New Today" value="47" variant="neutral"></aithe-metrics>
+  </aithe-metrics-group>
+</aithe-dashboard-panel>
+```
+
+### Data-driven / 数据驱动
+
+```html
+<aithe-metrics-group direction="horizontal" gap="24" id="my-metrics"></aithe-metrics-group>
+<script>
+  document.getElementById('my-metrics').items = [
+    { label: 'Users', value: '1,024', variant: 'primary', showDivider: true },
+    { label: 'Revenue', value: '$42.5K', variant: 'success', showDivider: true },
+    { label: 'Errors', value: '3', variant: 'danger' },
+  ];
+</script>
+```
+
+### Data-driven with params / params 覆盖
+
+```html
+<aithe-metrics-group id="my-metrics-2"></aithe-metrics-group>
+<script>
+  const el = document.getElementById('my-metrics-2');
+  el.params = { direction: 'horizontal', gap: 24 };
+  el.data = [
+    { label: 'Users', value: '1,024', variant: 'primary' },
+    { label: 'Revenue', value: '$42.5K', variant: 'success' },
+  ];
+</script>
+```
+
+> `data` accepts both a single `MetricsData` object and an array; a single object is automatically wrapped into a one-element array.
+> `data` 支持单个 `MetricsData` 对象或数组，传入单个对象时自动转为单元素数组。