@aithe/aithe-ui 26.2.2 → 26.3.1

package/docs/api/data/tree-menu.md

@@ -5,36 +5,44 @@
 
 ## Slots / 插槽
 
-| Name | Description (EN) | Description (CN) |
-|------|-------------------|-------------------|
-| — | — | No slots (content driven by `items` property). | 无插槽（内容由 items 属性控制）。 |
+| Name | Description (EN) | Description (CN)                               |
+| ---- | ---------------- | ---------------------------------------------- | 
+| —    | No slots (content driven by `items` property). | 无插槽（内容由 items 属性控制）。 |
 
 ## Properties / 属性
 
-| Name | Type | Default | Description (EN) | Description (CN) |
-|------|------|---------|-------------------|-------------------|
-| items | String (JSON) | `''` | JSON string of tree menu items (maps to `items` HTML attribute). | 树菜单项的 JSON 字符串（映射到 `items` HTML 属性）。 |
-| items | `AitheTreeNodeMeta[]` | `[]` | Array of tree menu items (prefer this in JS). | 树菜单项数组（在 JS 中优先使用）。 |
-| active | `string` | `''` | Active (selected) menu item value. | 当前选中的菜单项值。 |
-| expandAll | Boolean | false | Whether all nodes are expanded by default. | 是否默认展开所有节点。 |
+| Name      | Type                       | Default    | Description (EN)                                                                                               | Description (CN)                                                             |
+| --------- | -------------------------- | ---------- | -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| items     | String (JSON)              | `''`       | JSON string of tree menu items (maps to `items` HTML attribute).                                               | 树菜单项的 JSON 字符串（映射到 `items` HTML 属性）。                         |
+| items     | `AitheTreeNodeMeta[]`      | `[]`       | Array of tree menu items (prefer this in JS).                                                                  | 树菜单项数组（在 JS 中优先使用）。                                           |
+| active    | `string`                   | `''`       | Active (selected) menu item value.                                                                             | 当前选中的菜单项值。                                                         |
+| expandAll | Boolean                    | false      | Whether all nodes are expanded by default.                                                                     | 是否默认展开所有节点。                                                       |
 | direction | 'vertical' \| 'horizontal' | 'vertical' | Layout direction. Vertical stacks items; horizontal arranges top-level items in a row with dropdown sub-menus. | 布局方向。垂直堆叠菜单项；水平将顶级菜单项排列为一行，子菜单以下拉方式展开。 |
+| collapsible | Boolean                  | false      | Whether the tree menu supports collapse/expand toggle.                                                         | 树菜单是否支持伸缩切换。                                                     |
+| collapsed   | Boolean                  | false      | Whether the tree menu is currently collapsed.                                                                  | 树菜单当前是否收起。                                                         |
+| collapsed-width | String                | `'64px'`   | Width when collapsed (CSS value).                                                                              | 收起时的宽度。                                                               |
+| expanded-width  | String                | `'260px'`  | Width when expanded (CSS value).                                                                               | 展开时的宽度。                                                               |
+| 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` 的项会被隐藏。适用于权限控制。 |
+| item-renderer | `((item: AitheTreeNodeMeta) => TemplateResult \| nothing) \| null` | `null` | Custom item renderer. When provided, called for each leaf item; its return value replaces the default icon/label rendering inside the button. Useful for custom previews (color dots, shape previews, etc.). | 自定义 item 渲染器。提供后，每个叶子项调用此函数，返回值替换按钮内默认的图标/标签渲染。适用于自定义预览（颜色圆点、形状预览等）。 |
 
 ## Events / 事件
 
-| Name | Detail | Description (EN) | Description (CN) |
-|------|--------|-------------------|-------------------|
-| aithe-select | `{ value }` | Emitted when a menu item is selected. | 菜单项选中时触发。 |
+| Name         | Detail      | Description (EN)                      | Description (CN)   |
+| ------------ | ----------- | ------------------------------------- | ------------------ |
+| aithe-select | `{ value, item }` | Emitted when a menu item is selected. `value` is the item's `id`, `item` is the full `AitheTreeNodeMeta` object. The event is composed and bubbles, so it will propagate through shadow DOM boundaries of ancestor components (e.g. `<aithe-sidebar>`, `<aithe-dropdown>`). | 菜单项选中时触发。`value` 为项的 `id`，`item` 为完整的 `AitheTreeNodeMeta` 对象。事件为 composed 且冒泡，会穿透祖先组件（如 `<aithe-sidebar>`、`<aithe-dropdown>`）的 shadow DOM 边界。 |
 
 ## Data Item Fields / 数据项字段
 
-| Field | Type | Description (EN) | Description (CN) |
-|-------|------|-------------------|-------------------|
-| label | `string` | Display text of the menu item. | 菜单项的显示文本。 |
-| id | `string` | Unique value identifying this node. | 节点唯一标识值。 |
-| icon | `string` | Icon name rendered before the label via aithe-icon. | 通过 aithe-icon 在标签前渲染的图标名称。 |
-| disabled | `boolean` | Whether the menu item is non-interactive. | 是否禁用菜单项。 |
-| intent | `AitheIntent` | Visual intent / semantic color for the node. | 节点的视觉意图/语义色。 |
-| children | `AitheTreeNodeMeta[]` | Nested sub-menu items. | 嵌套子菜单项。 |
+| Field    | Type                  | Description (EN)                                                                                                      | Description (CN)                                                           |
+| -------- | --------------------- | --------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| label    | `string`              | Display text of the menu item. Used as i18n fallback when `i18n` is set.                                              | 菜单项的显示文本。设置 `i18n` 时作为缺省值。                               |
+| id       | `string`              | Unique value identifying this node.                                                                                   | 节点唯一标识值。                                                           |
+| icon     | `string`              | Icon name rendered before the label via aithe-icon.                                                                   | 通过 aithe-icon 在标签前渲染的图标名称。                                   |
+| disabled | `boolean`             | Whether the menu item is non-interactive.                                                                             | 是否禁用菜单项。                                                           |
+| hasPermission | `boolean`         | Permission flag. When set to `false`, the item is hidden by the default `itemFilter`.                                 | 权限标记。设为 `false` 时，默认 `itemFilter` 会隐藏该项。                  |
+| variant   | `AitheVariant`        | Visual variant / semantic color for the node.                                                                         | 节点的视觉变体/语义色。                                                    |
+| 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 / 示例
 
@@ -56,3 +64,87 @@
   active="dashboard"
 ></aithe-tree-menu>
 ```
+
+### With i18n / 国际化
+
+```html
+<aithe-tree-menu
+  items='[{"label":"Dashboard","id":"dashboard","icon":"home","i18n":"app.menu.dashboard"},{"label":"Settings","id":"settings","icon":"settings","i18n":"app.menu.settings","children":[{"label":"Profile","id":"profile","i18n":"app.menu.profile"},{"label":"Security","id":"security","i18n":"app.menu.security"}]}]'
+  active="dashboard"
+></aithe-tree-menu>
+```
+
+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` 字段作为翻译键未找到时的缺省值。
+
+### Permission-based filtering / 基于权限的菜单过滤
+
+Use `itemFilter` to control which menu items are visible based on the current user's roles/permissions. The callback receives the item metadata and nesting depth (0 = top-level).
+
+使用 `itemFilter` 根据当前用户角色/权限控制菜单项可见性。回调接收菜单项元数据和嵌套深度（0 = 顶层）。
+
+```js
+const menu = document.querySelector('aithe-tree-menu');
+menu.itemFilter = (item, depth) => {
+  // Hide "Settings" for non-admin users
+  if (item.id === 'settings' && !currentUser.roles.includes('admin')) {
+    return false;
+  }
+  return true;
+};
+```
+
+```html
+<aithe-tree-menu
+  .items="${menuItems}"
+  active="dashboard"
+></aithe-tree-menu>
+```
+
+### Collapsible mode / 伸缩模式
+
+When `collapsible` is set, the menu can toggle between expanded and collapsed states. In collapsed mode, only icons are shown (centered), labels and arrows are hidden, and sub-menus expand inline without floating panels. If an item has no icon, the first letter of its label is shown as a fallback.
+
+设置 `collapsible` 后，菜单可在展开和收起状态间切换。收起模式下仅显示图标（居中），标签和箭头隐藏，子菜单以内联方式展开而非浮层。若项无图标，则显示标签首字母作为回退。
+
+```html
+<aithe-tree-menu
+  collapsible
+  collapsed
+  collapsed-width="64px"
+  expanded-width="260px"
+  .items="${menuItems}"
+  active="dashboard"
+></aithe-tree-menu>
+```
+
+### Custom item renderer / 自定义项渲染器
+
+Use `itemRenderer` to render custom content (e.g. color dots, shape previews) inside each leaf item's button, replacing the default icon/label rendering.
+
+使用 `itemRenderer` 在每个叶子项的按钮内渲染自定义内容（如颜色圆点、形状预览），替换默认的图标/标签渲染。
+
+```js
+const menu = document.querySelector('aithe-tree-menu');
+menu.itemRenderer = (item) => {
+  if (item.color) {
+    return html`<span style="display:inline-block;width:12px;height:12px;border-radius:50%;background:${item.color}"></span>`;
+  }
+  return nothing;
+};
+```
+
+### Event propagation / 事件传播
+
+The `aithe-select` event is composed (`composed: true`) and bubbles (`bubbles: true`), so it automatically propagates through shadow DOM boundaries. When `<aithe-tree-menu>` is used inside container components like `<aithe-sidebar>` or `<aithe-dropdown>`, listeners on the container will receive the event directly — no re-emission is needed.
+
+`aithe-select` 事件为 composed 且冒泡，会自动穿透 shadow DOM 边界。当 `<aithe-tree-menu>` 在 `<aithe-sidebar>` 或 `<aithe-dropdown>` 等容器组件内使用时，监听容器即可直接接收事件，无需重新发射。
+
+```js
+// Listen on sidebar — receives tree-menu's aithe-select directly
+// 监听 sidebar — 直接接收 tree-menu 的 aithe-select
+document.querySelector('aithe-sidebar').addEventListener('aithe-select', (e) => {
+  console.log(e.detail.value, e.detail.item);
+});
+```

package/docs/api/data/tree.md

@@ -5,41 +5,44 @@
 
 ## Slots / 插槽
 
-| Name | Description (EN) | Description (CN) |
-|------|-------------------|-------------------|
-| — | — | No slots (content driven by `data` property). | 无插槽（内容由 data 属性控制）。 |
+| Name | Description (EN)                              | Description (CN)                              |
+| ---- |-----------------------------------------------| --------------------------------------------- | 
+| —    | No slots (content driven by `data` property). | 无插槽（内容由 data 属性控制）。 |
 
 ## Properties / 属性
 
-| Name | Type | Default | Description (EN) | Description (CN) |
-|------|------|---------|-------------------|-------------------|
-| data | String | '[]' | JSON string of tree node data. Each node supports `icon` and `intent` (AitheIntent) fields. | 树节点数据的 JSON 字符串。每个节点支持 `icon` 和 `intent`（AitheIntent）字段。 |
-| title | `string` | `''` | Display title (shown as tooltip). | 显示标题（作为工具提示）。 |
-| icon | `string` | `''` | Icon name to display before the tree title. | 在树标题前显示的图标名称。 |
-| checkable | Boolean | false | Whether nodes show checkboxes for selection. | 节点是否显示复选框以供选择。 |
-| expandAll | Boolean | false | Whether all nodes are expanded by default. | 是否默认展开所有节点。 |
-| renderer | Function | undefined | Custom renderer function for tree nodes. Receives a TreeNode and returns a TemplateResult. | 树节点的自定义渲染函数。接收 TreeNode 并返回 TemplateResult。 |
+| Name      | Type     | Default   | Description (EN)                                                                             | Description (CN)                                                                |
+| --------- | -------- | --------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| data      | String   | '[]'      | JSON string of tree node data. Each node supports `icon` and `variant` (AitheVariant) fields. | 树节点数据的 JSON 字符串。每个节点支持 `icon` 和 `variant`（AitheVariant）字段。 |
+| title     | `string` | `''`      | Display title (shown as tooltip).                                                            | 显示标题（作为工具提示）。                                                      |
+| icon      | `string` | `''`      | Icon name to display before the tree title.                                                  | 在树标题前显示的图标名称。                                                      |
+| checkable | Boolean  | false     | Whether nodes show checkboxes for selection.                                                 | 节点是否显示复选框以供选择。                                                    |
+| expandAll | Boolean  | false     | Whether all nodes are expanded by default.                                                   | 是否默认展开所有节点。                                                          |
+| renderer  | Function | undefined | Custom renderer function for tree nodes. Receives a TreeNode and returns a TemplateResult.   | 树节点的自定义渲染函数。接收 TreeNode 并返回 TemplateResult。                   |
 
 ## Events / 事件
 
-| Name | Detail | Description (EN) | Description (CN) |
-|------|--------|-------------------|-------------------|
-| aithe-check | { checked } | Emitted when a checkbox is toggled. | 复选框切换时触发。 |
-| aithe-node-click | { node } | Emitted when a node label is clicked. | 节点标签被点击时触发。 |
+| Name             | Detail      | Description (EN)                      | Description (CN)       |
+| ---------------- | ----------- | ------------------------------------- | ---------------------- |
+| aithe-check      | { checked } | Emitted when a checkbox is toggled.   | 复选框切换时触发。     |
+| aithe-node-click | { node }    | Emitted when a node label is clicked. | 节点标签被点击时触发。 |
 
 ## Data Node Fields / 数据节点字段
 
-| Field | Type | Description (EN) | Description (CN) |
-|-------|------|-------------------|-------------------|
-| label | `string` | Display text of the node. | 节点的显示文本。 |
-| id | `string` | Unique identifier of the node. | 节点的唯一标识。 |
-| children | `AitheTreeNodeMeta[]` | Nested child nodes. | 嵌套子节点。 |
-| disabled | `boolean` | Whether the node is non-interactive. | 是否不可交互。 |
-| icon | `string` | Icon name rendered before the label via aithe-icon. | 通过 aithe-icon 在标签前渲染的图标名称。 |
-| intent | `AitheIntent` | Visual intent / semantic color for the node label. | 节点标签的视觉意图/语义色。 |
+| Field    | Type                  | Description (EN)                                                                                                      | Description (CN)                                                           |
+| -------- | --------------------- | --------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| label    | `string`              | Display text of the node. Used as i18n fallback when `i18n` is set.                                                   | 节点的显示文本。设置 `i18n` 时作为缺省值。                                 |
+| id       | `string`              | Unique identifier of the node.                                                                                        | 节点的唯一标识。                                                           |
+| children | `AitheTreeNodeMeta[]` | Nested child nodes.                                                                                                   | 嵌套子节点。                                                               |
+| disabled | `boolean`             | Whether the node is non-interactive.                                                                                  | 是否不可交互。                                                             |
+| icon     | `string`              | Icon name rendered before the label via aithe-icon.                                                                   | 通过 aithe-icon 在标签前渲染的图标名称。                                   |
+| variant   | `AitheVariant`        | Visual variant / semantic color for the node label.                                                                   | 节点标签的视觉变体/语义色。                                                |
+| 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-tree
   data='[{"label":"Root","id":"root","children":[{"label":"Child","id":"child"}]}]'
@@ -48,4 +51,18 @@
   checkable
   expand-all
 ></aithe-tree>
-```
+```
+
+### With i18n / 国际化
+
+```html
+<aithe-tree
+  data='[{"label":"Root","id":"root","i18n":"app.tree.root","children":[{"label":"Child","id":"child","i18n":"app.tree.child"}]}]'
+  checkable
+  expand-all
+></aithe-tree>
+```
+
+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/display/box.md

@@ -0,0 +1,66 @@
+# AitheBox / AitheBox 记录容器
+
+> The Box component family provides structured record display layouts. `AitheMiniBox` serves as the base class, providing region-based layout with named slots. The box only defines layout structure — all content is provided via named slots, with no data binding.
+> Box 组件族提供结构化记录展示布局。`AitheMiniBox` 作为基类，提供基于区域的布局和具名插槽。Box 只定义布局结构——所有内容通过具名插槽提供，无数据绑定。
+
+## Import / 引入
+
+```ts
+import '@aithe/aithe-ui/components/display/mini-box';
+// or
+import '@aithe/aithe-ui/components/display/brief-box';
+// or
+import '@aithe/aithe-ui/components/display/detail-box';
+```
+
+## Description / 描述
+
+The Box component family includes three variants, each implementing a distinct layout strategy:
+
+- `<aithe-mini-box>` — single horizontal row (compact list view)
+- `<aithe-brief-box>` — three rows with description and vertically spanning checkbox/actions
+- `<aithe-detail-box>` — two-column split with left metadata and right actions
+
+All content is provided via named slots. The box only defines layout structure — it does not bind data.
+
+Box 组件族包含三种变体，每种实现不同的布局策略：
+
+- `<aithe-mini-box>` — 单行水平布局（紧凑列表视图）
+- `<aithe-brief-box>` — 三行布局，含描述和垂直贯穿的 checkbox/actions
+- `<aithe-detail-box>` — 左右分栏布局，左侧元数据、右侧操作
+
+所有内容通过具名插槽提供。Box 只定义布局结构——不绑定数据。
+
+## Common Slots / 公共插槽
+
+| Name      | Description (EN)                                                    | Description (CN)               |
+| --------- | ------------------------------------------------------------------- | ------------------------------ |
+| select    | Selection control region (e.g. radio).                              | 选择控件区域（如单选框）。     |
+| checkbox  | Checkbox region.                                                    | 复选框区域。                   |
+| name      | Primary label / title region.                                       | 主标签/标题区域。              |
+| tags      | Tags region.                                                        | 标签区域。                     |
+| status    | Status indicator region.                                            | 状态指示器区域。               |
+| actions   | Action buttons region.                                              | 操作按钮区域。                 |
+| content   | Expandable content region.                                          | 可展开的内容区域。             |
+| (default) | Default slot, rendered inside the content region.                   | 默认插槽，渲染在内容区域内。   |
+
+## Common Properties / 公共属性
+
+| Name     | Type      | Default | Attribute  | Description (EN)                           | Description (CN)          |
+| -------- | --------- | ------- | ---------- | ------------------------------------------ | ------------------------- |
+| selected | `boolean` | `false` | `selected` | Whether the box is selected.               | box 是否被选中。          |
+| expanded | `boolean` | `false` | `expanded` | Whether the content region is expanded.    | 内容区域是否展开。        |
+
+## Common Events / 公共事件
+
+| Name              | Detail | Cancelable | Description (EN)               | Description (CN)        |
+| ----------------- | ------ | ---------- | ------------------------------ | ----------------------- |
+| `aithe-box-click` | `{}`   | No         | Fired when the box is clicked. | 点击 box 时触发。       |
+
+## Variants / 变体
+
+See the individual variant pages for layout details and usage examples:
+
+- [AitheMiniBox](mini-box.md)
+- [AitheBriefBox](brief-box.md)
+- [AitheDetailBox](detail-box.md)

package/docs/api/display/brief-box.md

@@ -0,0 +1,73 @@
+# AitheBriefBox / AitheBriefBox 简要记录
+
+> Three-row brief record display with description and vertically spanning checkbox/actions regions. All content is provided via named slots.
+> 三行简要记录展示，含描述行和垂直贯穿的 checkbox/actions 区域。所有内容通过具名插槽提供。
+
+## Import / 引入
+
+```ts
+import '@aithe/aithe-ui/components/data/brief-box';
+```
+
+## Description / 描述
+
+`<aithe-brief-box>` renders a three-row layout: the first row contains select, name, tags, and status; the second row shows the content; the third row is the expandable default slot region. The checkbox and actions regions span vertically across all rows. All content is provided via named slots.
+
+`<aithe-brief-box>` 渲染三行布局：第一行包含 select、name、tags 和 status；第二行显示内容；第三行是可展开的默认插槽区域。checkbox 和 actions 区域垂直贯穿所有行。所有内容通过具名插槽提供。
+
+## Slots / 插槽
+
+| Name      | Description (EN)                                                    | Description (CN)               |
+| --------- | ------------------------------------------------------------------- | ------------------------------ |
+| select    | Selection control region (e.g. radio).                              | 选择控件区域（如单选框）。     |
+| checkbox  | Checkbox region (spans vertically).                                 | 复选框区域（垂直贯穿）。       |
+| name      | Primary label / title region.                                       | 主标签/标题区域。              |
+| tags      | Tags region.                                                        | 标签区域。                     |
+| status    | Status indicator region.                                            | 状态指示器区域。               |
+| actions   | Action buttons region (spans vertically).                           | 操作按钮区域（垂直贯穿）。     |
+| content   | Expandable content region.                                          | 可展开的内容区域。             |
+| (default) | Default slot, rendered inside the content region.                   | 默认插槽，渲染在内容区域内。   |
+
+## CSS Parts / CSS 部件
+
+| Name    | Description (EN)                    | Description (CN)     |
+| ------- | ----------------------------------- | -------------------- |
+| select  | The select region container.        | 选择区域容器。       |
+| checkbox| The checkbox region container.      | 复选框区域容器。     |
+| name    | The name region container.          | 名称区域容器。       |
+| tags    | The tags region container.          | 标签区域容器。       |
+| status  | The status region container.        | 状态区域容器。       |
+| actions | The actions region container.       | 操作区域容器。       |
+| content | The content region container.       | 内容区域容器。       |
+
+## Properties / 属性
+
+Inherits all properties from `AitheMiniBox`. See [AitheMiniBox](mini-box.md) for details.
+
+## Events / 事件
+
+Inherits all events from `AitheMiniBox`. See [AitheMiniBox](mini-box.md) for details.
+
+## Usage / 用法
+
+### Basic / 基础用法
+
+```html
+<aithe-brief-box>
+  <aithe-profile slot="name" title="Project Alpha" desc="Frontend application" icon="app"></aithe-profile>
+  <span slot="status">Active</span>
+  <span slot="tags"><aithe-tag>frontend</aithe-tag></span>
+  <span slot="actions"><aithe-button size="sm">Edit</aithe-button></span>
+</aithe-brief-box>
+```
+
+### With Checkbox / 带复选框
+
+```html
+<aithe-brief-box selectable>
+  <aithe-profile slot="name" title="Project Alpha" desc="Frontend application" icon="app"></aithe-profile>
+  <span slot="status">Active</span>
+  <span slot="tags"><aithe-tag>frontend</aithe-tag></span>
+  <span slot="actions"><aithe-button size="sm">Edit</aithe-button></span>
+</aithe-brief-box>
+```