@aithe/aithe-ui 26.2.3 → 26.3.2

package/docs/api/data/table.md

@@ -8,59 +8,70 @@
 AitheTable supports two column definition modes:
 AitheTable 支持两种列定义模式：
 
-| Mode | How to define | Custom rendering | Description |
-|------|---------------|------------------|-------------|
-| Data-driven | `columns` / `columns-json` attribute | Not supported | Columns defined as JSON data. Suitable for simple display. |
-| DOM-defined | `<aithe-table-column>` children | Supported via `.cellRenderer` | Columns defined as child elements. Supports custom cell rendering. |
+| Mode        | How to define                        | Custom rendering              | Description                                                        |
+| ----------- | ------------------------------------ | ----------------------------- | ------------------------------------------------------------------ |
+| Data-driven | `columns` / `columns-json` attribute | Not supported                 | Columns defined as JSON data. Suitable for simple display.         |
+| DOM-defined | `<aithe-table-column>` children      | Supported via `.cellRenderer` | Columns defined as child elements. Supports custom cell rendering. |
 
-| 模式 | 定义方式 | 自定义渲染 | 说明 |
-|------|----------|-----------|------|
-| 数据驱动 | `columns` / `columns-json` 属性 | 不支持 | 列以 JSON 数据定义，适用于简单展示。 |
-| DOM 定义 | `<aithe-table-column>` 子元素 | 支持，通过 `.cellRenderer` | 列以子元素定义，支持自定义单元格渲染。 |
+| 模式     | 定义方式                        | 自定义渲染                 | 说明                                   |
+| -------- | ------------------------------- | -------------------------- | -------------------------------------- |
+| 数据驱动 | `columns` / `columns-json` 属性 | 不支持                     | 列以 JSON 数据定义，适用于简单展示。   |
+| DOM 定义 | `<aithe-table-column>` 子元素   | 支持，通过 `.cellRenderer` | 列以子元素定义，支持自定义单元格渲染。 |
 
 ## Slots / 插槽
 
-| Name | Description (EN) | Description (CN) |
-|------|-------------------|-------------------|
+| Name      | Description (EN)                                                     | Description (CN)                                               |
+| --------- | -------------------------------------------------------------------- | -------------------------------------------------------------- |
 | (default) | Default slot for `<aithe-table-column>` children (DOM-defined mode). | 用于 `<aithe-table-column>` 子元素的默认插槽（DOM 定义模式）。 |
-| empty | Content shown when the table has no data. | 无数据时显示的内容。 |
+| empty     | Content shown when the table has no data.                            | 无数据时显示的内容。                                           |
+| loading   | Custom loading indicator content.                                    | 自定义加载指示器内容。                                         |
 
 ## Properties / 属性
 
-| Name | Type | Default | Description (EN) | Description (CN) |
-|------|------|---------|-------------------|-------------------|
-| columnsJson | String | '' | JSON string of column definitions (parsed into `columns`). Data-driven mode only. | 列定义的 JSON 字符串（解析为 `columns`）。仅数据驱动模式。 |
-| columns | AitheTableColumnMeta[] | [] | Array of column definitions (prefer this over `columnsJson` in JS). Data-driven mode only. | 列定义数组（在 JS 中优先使用此属性而非 `columnsJson`）。仅数据驱动模式。 |
-| dataJson | String | '' | JSON string of row data (parsed into `data`). | 行数据的 JSON 字符串（解析为 `data`）。 |
-| data | TableRecord[] | [] | Array of row data (prefer this over `dataJson` in JS). | 行数据数组（在 JS 中优先使用此属性而非 `dataJson`）。 |
-| rowKey | String | 'id' | Unique key field for each row. | 每行的唯一键字段。 |
-| striped | Boolean | false | Whether rows use alternating background colors. | 行是否使用交替背景色。 |
-| bordered | Boolean | true | Whether cells have vertical border lines. | 单元格是否有垂直边框线。 |
-| hoverable | Boolean | true | Whether rows highlight on hover. | 行是否在悬停时高亮。 |
-| selectable | Boolean | false | Whether rows can be selected via checkboxes. | 行是否可通过复选框选择。 |
-| sortKey | String | '' | Current sort column key. | 当前排序的列键。 |
-| sortOrder | 'asc' \| 'desc' \| '' | '' | Current sort direction. | 当前排序方向。 |
+| Name         | Type                          | Default   | Description (EN)                                                                                                                  | Description (CN)                                                                   |
+| ------------ | ----------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| columnsJson  | String                        | ''        | JSON string of column definitions (parsed into `columns`). Data-driven mode only.                                                 | 列定义的 JSON 字符串（解析为 `columns`）。仅数据驱动模式。                         |
+| columns      | AitheTableColumnMeta[]        | []        | Array of column definitions (prefer this over `columnsJson` in JS). Data-driven mode only.                                        | 列定义数组（在 JS 中优先使用此属性而非 `columnsJson`）。仅数据驱动模式。           |
+| dataJson     | String                        | ''        | JSON string of row data (parsed into `data`).                                                                                     | 行数据的 JSON 字符串（解析为 `data`）。                                            |
+| data         | TableRecord[]                 | []        | Array of row data (prefer this over `dataJson` in JS).                                                                            | 行数据数组（在 JS 中优先使用此属性而非 `dataJson`）。                              |
+| rowKey       | String                        | 'id'      | Unique key field for each row.                                                                                                    | 每行的唯一键字段。                                                                 |
+| striped      | Boolean                       | false     | Whether rows use alternating background colors.                                                                                   | 行是否使用交替背景色。                                                             |
+| bordered     | Boolean                       | true      | Whether cells have vertical border lines.                                                                                         | 单元格是否有垂直边框线。                                                           |
+| hoverable    | Boolean                       | true      | Whether rows highlight on hover.                                                                                                  | 行是否在悬停时高亮。                                                               |
+| selectable   | 'none' \| 'multi' \| 'single' | 'none'    | Row selection mode. `'none'` disables selection, `'multi'` enables checkbox multi-select, `'single'` enables radio single-select. | 行选择模式。`'none'` 不选择，`'multi'` 启用复选框多选，`'single'` 启用单选框单选。 |
+| selectionSet | Set\<string\>                 | new Set() | Shared Set instance for tracking selected row keys. Pass the same Set to multiple views to share selection state.                 | 共享的 Set 实例，用于跟踪选中的行键。将同一个 Set 传递给多个视图以共享选中状态。   |
+| sortKey      | String                        | ''        | Current sort column key.                                                                                                          | 当前排序的列键。                                                                   |
+| sortOrder    | 'asc' \| 'desc' \| ''         | ''        | Current sort direction.                                                                                                           | 当前排序方向。                                                                     |
+| loading      | Boolean                       | false     | Whether the table is in loading state. Shows a loading overlay with spinner and shimmer placeholder rows.                         | 表格是否处于加载状态。显示加载遮罩层、旋转器和 shimmer 占位行。                    |
+| loadingText  | String                        | ''        | Custom loading text displayed below the spinner.                                                                                  | 在旋转器下方显示的自定义加载文本。                                                 |
 
 ## Events / 事件
 
-| Name | Detail | Description (EN) | Description (CN) |
-|------|--------|-------------------|-------------------|
-| aithe-sort-change | { sortKey, sortOrder } | Emitted when a sortable column header is clicked. | 可排序列头被点击时触发。 |
-| aithe-selection-change | { selectedKeys } | Emitted when row selection changes. | 行选择变更时触发。 |
-| aithe-row-click | { record, rowIndex } | Emitted when a row is clicked. | 行被点击时触发。 |
+| 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 row is clicked.                                              | 行被点击时触发。                           |
+| aithe-column-resize    | { columnId, width }    | Emitted when a resizable column width is changed.                           | 可调整宽度的列宽变更时触发。               |
+| aithe-column-reorder   | { columns }            | Emitted when columns are reordered. Contains the new column id order array. | 列重新排序时触发。包含新的列 ID 顺序数组。 |
 
 ## Column Fields (Data-driven) / 列字段（数据驱动模式）
 
-| Field | Type | Description (EN) | Description (CN) |
-|-------|------|-------------------|-------------------|
-| id | `string` | Unique column key. | 唯一列键。 |
-| title | `string` | Header title. | 表头标题。 |
-| dataIndex | keyof T \| string | Property path on the data record. | 数据记录上的属性路径。 |
-| width | `string` | Fixed column width. | 固定列宽。 |
-| align | 'left' \| 'center' \| 'right' | Text alignment. | 文本对齐方式。 |
-| sortable | `boolean` | Enable client-side sorting. | 启用客户端排序。 |
-| icon | `string` | Icon name rendered in the header via aithe-icon. | 通过 aithe-icon 在表头渲染的图标名称。 |
-| variant | AitheVariant | Visual variant / semantic color for the column cells. | 列单元格的视觉变体/语义色。 |
+| Field     | Type                          | Description (EN)                                                                               | Description (CN)                                                   |
+| --------- | ----------------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
+| id        | `string`                      | Unique column key.                                                                             | 唯一列键。                                                         |
+| title     | `string`                      | Header title.                                                                                  | 表头标题。                                                         |
+| dataIndex | keyof T \| string             | Property path on the data record.                                                              | 数据记录上的属性路径。                                             |
+| width     | `string`                      | Fixed column width.                                                                            | 固定列宽。                                                         |
+| minWidth  | `string`                      | Minimum column width (for resizable columns).                                                  | 最小列宽（用于可调整宽度的列）。                                   |
+| align     | 'left' \| 'center' \| 'right' | Text alignment.                                                                                | 文本对齐方式。                                                     |
+| sortable  | `boolean`                     | Enable client-side sorting.                                                                    | 启用客户端排序。                                                   |
+| fixed     | 'left' \| 'right'             | Fixed column position. The column will stick to the left or right side with shadow indicators. | 固定列位置。列将固定在左侧或右侧，并显示阴影指示器。               |
+| resizable | `boolean`                     | Enable column width resizing via drag handle on the right edge of the header.                  | 启用通过表头右侧边缘拖拽手柄调整列宽。                             |
+| draggable | `boolean`                     | Enable column drag-to-reorder via drag handle icon in the header.                              | 启用通过表头拖拽手柄图标拖拽排序列。                               |
+| icon      | `string`                      | Icon name rendered in the header via aithe-icon.                                               | 通过 aithe-icon 在表头渲染的图标名称。                             |
+| variant   | AitheVariant                  | Visual variant / semantic color for the column cells.                                          | 列单元格的视觉变体/语义色。                                        |
+| filter    | `string`                      | Filter expression to format cell value. See [Filter](/docs/filter.md).                         | 用于格式化单元格值的过滤器表达式。参见 [Filter](/docs/filter.md)。 |
 
 ## Examples / 示例
 
@@ -71,19 +82,122 @@ AitheTable 支持两种列定义模式：
   columns-json='[{"id":"name","title":"Name","sortable":true}]'
   data-json='[{"name":"Alice"},{"name":"Bob"}]'
   striped
-  selectable
+  selectable="multi"
+></aithe-table>
+```
+
+### Data-driven mode with shared selection / 数据驱动模式 + 共享选中状态
+
+```html
+<aithe-table
+  columns-json='[{"id":"name","title":"Name","sortable":true}]'
+  data-json='[{"name":"Alice"},{"name":"Bob"}]'
+  striped
+  selectable="multi"
+  .selectionSet="${mySet}"
 ></aithe-table>
 ```
 
 ### DOM-defined mode / DOM 定义模式
 
 ```html
-<aithe-table .data=${records} striped selectable>
+<aithe-table .data="${records}" striped selectable>
   <aithe-table-column id="name" title="Name" sortable></aithe-table-column>
   <aithe-table-column id="owner" title="Owner"></aithe-table-column>
   <aithe-table-column id="status" title="Status" variant="success" sortable></aithe-table-column>
-  <aithe-table-column id="action" title="Action" align="center"
-    .cellRenderer=${(value, record, rowIndex) => html`<aithe-button type="primary" size="sm">Edit</aithe-button>`}
+  <aithe-table-column
+    id="action"
+    title="Action"
+    align="center"
+    .cellRenderer="${(key,"
+    value,
+    record)=""
+  >
+    html`
+    <aithe-button type="primary" size="sm">Edit</aithe-button>
+    `} >
+  </aithe-table-column>
+</aithe-table>
+```
+
+### Column fixed / 列固定
+
+```html
+<aithe-table .data="${records}" striped bordered selectable>
+  <aithe-table-column id="name" title="Name" fixed="left" width="160" sortable></aithe-table-column>
+  <aithe-table-column id="owner" title="Owner" width="200"></aithe-table-column>
+  <aithe-table-column id="status" title="Status" width="200" variant="success"></aithe-table-column>
+  <aithe-table-column
+    id="action"
+    title="Action"
+    fixed="right"
+    width="120"
+    align="center"
+  ></aithe-table-column>
+</aithe-table>
+```
+
+### Column resize / 列宽调整
+
+```html
+<aithe-table .data="${records}" striped bordered>
+  <aithe-table-column
+    id="name"
+    title="Name"
+    resizable
+    min-width="120"
+    width="200"
+    sortable
+  ></aithe-table-column>
+  <aithe-table-column
+    id="owner"
+    title="Owner"
+    resizable
+    min-width="100"
+    width="200"
+  ></aithe-table-column>
+  <aithe-table-column
+    id="status"
+    title="Status"
+    resizable
+    min-width="100"
+    width="200"
   ></aithe-table-column>
 </aithe-table>
-```
+```
+
+### Column reorder / 列排序
+
+```html
+<aithe-table .data="${records}" striped bordered>
+  <aithe-table-column id="name" title="Name" draggable sortable></aithe-table-column>
+  <aithe-table-column id="owner" title="Owner" draggable></aithe-table-column>
+  <aithe-table-column id="status" title="Status" draggable variant="success"></aithe-table-column>
+</aithe-table>
+```
+
+### Loading state / 加载状态
+
+```html
+<aithe-table
+  loading
+  loading-text="Loading..."
+  .data="${records}"
+  columns-json='[{"id":"name","title":"Name","sortable":true}]'
+  striped
+  selectable="multi"
+></aithe-table>
+```
+
+### Single row selection / 行单选
+
+```html
+<aithe-table
+  selectable="multi"
+  ="single"
+  .selectionSet="${mySet}"
+  .data="${records}"
+  columns-json='[{"id":"name","title":"Name","sortable":true}]'
+  striped
+></aithe-table>
+```

package/docs/api/data/tabs.md

@@ -8,6 +8,7 @@
 | Name | Description (EN) | Description (CN) |
 |------|-------------------|-------------------|
 | (default) | Default slot for `aithe-tab-pane` children. | 默认插槽，用于 `aithe-tab-pane` 子组件。 |
+| extra | Slot for extra content rendered at the end of the tab bar (e.g. action buttons). | 额外内容插槽，渲染在标签栏末尾（如操作按钮）。 |
 
 ## Properties / 属性
 
@@ -16,6 +17,7 @@
 | type | 'line' \| 'card' \| 'button' | 'line' | Visual style of the tab navigation. | 标签页导航的视觉样式。 |
 | activeKey | String | '' | Key of the currently active tab pane. | 当前活动标签页的键。 |
 | addable | Boolean | false | Whether to show an add button in the tab bar. | 是否在标签栏中显示添加按钮。 |
+| maxVisibleTabs | Number | 0 | Maximum visible tabs before overflow dropdown. `0` = no limit. | 最大可见标签页数量，超出部分折叠到下拉菜单。`0` 表示不限制。 |
 
 ## Events / 事件
 
@@ -25,11 +27,54 @@
 | aithe-tab-remove | { key } | Emitted when a closable tab is removed. | 可关闭标签页被移除时触发。 |
 | aithe-tab-add | — | Emitted when the add button is clicked. | 添加按钮被点击时触发。 |
 
+## CSS Custom Properties / CSS 自定义属性
+
+| Property | Default | Description (EN) | Description (CN) |
+|----------|---------|-------------------|-------------------|
+| --aithe-tabs-nav-gap | var(--aithe-space-2) | Gap between tab items in the nav bar. | 标签栏中标签项之间的间距。 |
+| --aithe-tabs-nav-border-color | var(--aithe-color-border) | Bottom border color of the nav bar. | 标签栏底部边框颜色。 |
+| --aithe-tabs-tab-padding | 0 var(--aithe-space-4) | Padding inside each tab button. | 标签按钮内边距。 |
+| --aithe-tabs-tab-min-height | 38px | Minimum height of each tab button. | 标签按钮最小高度。 |
+| --aithe-tabs-tab-radius | var(--aithe-radius-md) | Border radius of tab buttons. | 标签按钮圆角。 |
+| --aithe-tabs-tab-color | var(--aithe-color-text-muted) | Text color of inactive tabs. | 非活动标签文字颜色。 |
+| --aithe-tabs-tab-active-color | var(--aithe-primary-7) | Text color of active tabs (line type). | 活动标签文字颜色（line 类型）。 |
+| --aithe-tabs-tab-active-border-color | var(--aithe-primary-6) | Active indicator border color (line type). | 活动标签指示器边框颜色（line 类型）。 |
+| --aithe-tabs-tab-active-bg | var(--aithe-color-surface-elevated) | Background of active tabs (card/button type). | 活动标签背景色（card/button 类型）。 |
+| --aithe-tabs-tab-disabled-opacity | 0.48 | Opacity of disabled tabs. | 禁用标签的不透明度。 |
+
+## CSS Parts / CSS 部件
+
+| Part | Description (EN) | Description (CN) |
+|------|-------------------|-------------------|
+| nav | The tab navigation bar container. | 标签导航栏容器。 |
+| panel | The tab content panel area. | 标签内容面板区域。 |
+| tab | Individual tab button. | 单个标签按钮。 |
+| tab-active | Active tab button. | 活动标签按钮。 |
+| tab-disabled | Disabled tab button. | 禁用标签按钮。 |
+| remove-btn | Close button on closable tabs. | 可关闭标签上的关闭按钮。 |
+| add-btn | Add tab button. | 添加标签按钮。 |
+| overflow-select | Overflow dropdown select. | 溢出下拉选择器。 |
+| nav-extra | Extra content slot container. | 额外内容插槽容器。 |
+
 ## Examples / 示例
 
+### Basic usage / 基础用法
+
 ```html
 <aithe-tabs type="card" active-key="a">
   <aithe-tab-pane tab-id="a" label="Tab A">Content A</aithe-tab-pane>
   <aithe-tab-pane tab-id="b" label="Tab B">Content B</aithe-tab-pane>
 </aithe-tabs>
-```
+```
+
+### With overflow dropdown / 带溢出下拉
+
+```html
+<aithe-tabs max-visible-tabs="3" type="card" active-key="tab1">
+  <aithe-tab-pane tab-id="tab1" label="Tab 1">Content 1</aithe-tab-pane>
+  <aithe-tab-pane tab-id="tab2" label="Tab 2">Content 2</aithe-tab-pane>
+  <aithe-tab-pane tab-id="tab3" label="Tab 3">Content 3</aithe-tab-pane>
+  <aithe-tab-pane tab-id="tab4" label="Tab 4">Content 4</aithe-tab-pane>
+  <aithe-tab-pane tab-id="tab5" label="Tab 5">Content 5</aithe-tab-pane>
+</aithe-tabs>
+```

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

@@ -18,13 +18,18 @@
 | 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. | 布局方向。垂直堆叠菜单项；水平将顶级菜单项排列为一行，子菜单以下拉方式展开。 |
-| item-filter | `AitheSidebarItemFilter \| null` | `null` | Filter callback for menu items. Return `true` to show, `false` to hide. Useful for permission control. | 菜单项过滤回调。返回 `true` 显示，`false` 隐藏。适用于权限控制。 |
+| 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. | 菜单项选中时触发。 |
+| 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 / 数据项字段
 
@@ -34,6 +39,7 @@
 | 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` 作为缺省值。 |
@@ -95,3 +101,50 @@ menu.itemFilter = (item, depth) => {
   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);
+});
+```