@aithe/aithe-ui 26.2.2 → 26.3.1

package/docs/api/framework/sidebar.md

@@ -0,0 +1,181 @@
+# AitheSidebar / AitheSidebar 侧边栏
+
+> Framework-level sidebar with three zones: top (brand), center (menu tree), bottom (action buttons).
+> 框架级侧边栏，包含三个区域：顶部（品牌）、中间（菜单树）、底部（操作按钮）。
+
+## Slots / 插槽
+
+| Name   | Description (EN)                                                   | Description (CN)                                    |
+| ------ | ------------------------------------------------------------------ | --------------------------------------------------- |
+| top    | Custom top area content (overrides `brand` and `icon` properties). | 自定义顶部区域内容（覆盖 `brand` 和 `icon` 属性）。 |
+| center | Custom center menu content (overrides data-driven menu).           | 自定义中间菜单内容（覆盖数据驱动菜单）。            |
+| bottom | Extra action buttons in the bottom bar (before built-in buttons).  | 底部栏中的额外操作按钮（在内置按钮之前渲染）。      |
+
+## CSS Parts / CSS 部件
+
+| Name   | Description (EN)      | Description (CN) |
+| ------ | --------------------- | ---------------- |
+| top    | The top container.    | 顶部容器。       |
+| center | The center container. | 中间容器。       |
+| bottom | The bottom container. | 底部容器。       |
+
+## Properties / 属性
+
+| Name              | Type                  | Default   | Description (EN)                                                                                      | Description (CN)                                               |
+| ----------------- | --------------------- | --------- | ----------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
+| brand             | `string`              | `''`      | Brand name displayed in the top zone.                                                                 | 顶部区域显示的品牌名称。                                       |
+| icon              | `string`              | `''`      | Icon name displayed before the brand in the top zone.                                                 | 顶部区域品牌前的图标名称。                                     |
+| items-json        | `string`              | `''`      | JSON string of menu items (`AitheTreeNodeMeta[]`).                                                    | 菜单项的 JSON 字符串。                                         |
+| items             | `AitheTreeNodeMeta[]` | `[]`      | Array of menu items (prefer this in JS).                                                              | 菜单项数组（在 JS 中优先使用）。                               |
+| active            | `string`              | `''`      | Active (selected) menu item value.                                                                    | 当前选中的菜单项值。                                           |
+| expand-all        | `boolean`             | `false`   | Whether all menu groups are expanded by default.                                                      | 是否默认展开所有菜单分组。                                     |
+| collapsible       | `boolean`             | `false`   | Whether the sidebar supports collapse/expand toggle.                                                  | 侧边栏是否支持伸缩切换。                                       |
+| collapsed         | `boolean`             | `false`   | Whether the sidebar is currently collapsed.                                                           | 侧边栏当前是否收起。                                           |
+| overlay           | `boolean`             | `false`   | Whether the sidebar uses overlay mode (floats above content). Auto-enabled on mobile.                 | 是否使用覆盖模式（浮在内容上方）。移动端自动启用。             |
+| header-height     | `string`              | `'56px'`  | Header height in CSS value; overlay sidebar starts below the header.                                  | Header 高度（CSS 值）；overlay 侧边栏从 header 下方开始。      |
+| mobile-breakpoint | `number`              | `768`     | Viewport width threshold (px); when ≤ this value, overlay mode is auto-enabled and sidebar collapses. | 移动端断点（像素）；视口宽度 ≤ 此值时自动启用 overlay 并收起。 |
+| expanded-width    | `string`              | `'260px'` | Sidebar width when expanded (CSS value).                                                              | 展开时的侧边栏宽度。                                           |
+| collapsed-width   | `string`              | `'64px'`  | Sidebar width when collapsed (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` 的项会被隐藏。适用于权限控制。 |
+
+## Events / 事件
+
+| Name                  | Detail                   | Cancelable | Description (EN)                                                                                        | Description (CN)                                                   |
+| --------------------- | ------------------------ | ---------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
+| aithe-select          | `{ value: string, item: AitheTreeNodeMeta }` | No         | Propagated from the inner `<aithe-tree-menu>` (composed event). Sidebar does not re-emit — listen on the sidebar element directly. `value` is the item's `id`, `item` is the full node metadata. | 由内部 `<aithe-tree-menu>` 透传（composed 事件）。sidebar 不重新发射 — 直接监听 sidebar 元素即可。`value` 为项的 `id`，`item` 为完整节点元数据。 |
+| aithe-collapse-change | `{ collapsed: boolean }` | Yes        | Emitted when sidebar collapse state is about to change. Call `preventDefault()` to suppress the toggle. | 侧边栏伸缩状态即将变更时发出。调用 `preventDefault()` 可阻止切换。 |
+
+## AitheTreeNodeMeta / 树节点元数据
+
+| Name     | Type                  | Description (EN)                                                                                                      | Description (CN)                                                           |
+| -------- | --------------------- | --------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| label    | `string`              | Display label. Used as i18n fallback when `i18n` is set.                                                              | 显示标签。设置 `i18n` 时作为缺省值。                                       |
+| id       | `string`              | Unique identifier.                                                                                                    | 节点唯一标识。                                                             |
+| icon     | `string`              | Icon name (via `aithe-icon`).                                                                                         | 图标名称。                                                                 |
+| disabled | `boolean`             | Whether the node is disabled.                                                                                         | 是否禁用节点。                                                             |
+| hasPermission | `boolean`         | Permission flag. When set to `false`, the item is hidden by the default `itemFilter`.                                 | 权限标记。设为 `false` 时，默认 `itemFilter` 会隐藏该项。                  |
+| intent   | `AitheVariant`        | Visual variant / semantic color.                                                                                      | 视觉变体/语义色。                                                          |
+| children | `AitheTreeNodeMeta[]` | Nested child nodes.                                                                                                   | 嵌套子节点。                                                               |
+| 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-sidebar
+  brand="My App"
+  icon="home"
+  items='[{"label":"Dashboard","id":"dashboard","icon":"home"},{"label":"Settings","id":"settings","icon":"settings","children":[{"label":"Profile","id":"profile"},{"label":"Security","id":"security"}]}]'
+  active="dashboard"
+></aithe-sidebar>
+```
+
+### With i18n / 国际化
+
+```html
+<aithe-sidebar
+  brand="My App"
+  icon="home"
+  .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-sidebar>
+```
+
+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. The sidebar also re-renders automatically when the locale changes.
+
+设置 `i18n` 后，组件自动通过 `t(i18n, label)` 翻译 label。`label` 字段作为翻译键未找到时的缺省值。切换语言时侧边栏会自动重新渲染。
+
+### Collapsible sidebar / 可伸缩侧边栏
+
+```html
+<aithe-sidebar
+  brand="Admin"
+  icon="grid"
+  collapsible
+  .items="${menuItems}"
+  active="home"
+></aithe-sidebar>
+```
+
+### Custom slots / 自定义插槽
+
+```html
+<aithe-sidebar collapsible>
+  <div slot="top">
+    <img src="logo.svg" alt="Logo" style="height:32px" />
+  </div>
+  <nav slot="center">
+    <aithe-menu mode="vertical" active="home">
+      <aithe-menu-item name="home" icon="home">Home</aithe-menu-item>
+      <aithe-menu-item name="settings" icon="settings">Settings</aithe-menu-item>
+    </aithe-menu>
+  </nav>
+  <button slot="bottom" type="button">⚙</button>
+</aithe-sidebar>
+```
+
+### Preventing collapse / 阻止伸缩
+
+```js
+const sidebar = document.querySelector('aithe-sidebar');
+sidebar.addEventListener('aithe-collapse-change', (e) => {
+  e.preventDefault();
+  console.log('Collapse blocked, requested:', e.detail.collapsed);
+});
+```
+
+### Mobile overlay mode / 移动端覆盖模式
+
+When the viewport width is ≤ `mobile-breakpoint` (default 768px), the sidebar automatically enters overlay mode: it collapses, floats above the content, and a floating toggle button appears in the bottom-left corner. Clicking the toggle button or the backdrop expands/collapses the sidebar.
+
+当视口宽度 ≤ `mobile-breakpoint`（默认 768px）时，侧边栏自动进入覆盖模式：收起并浮在内容上方，左下角出现悬浮切换按钮。点击按钮或遮罩区域可展开/收起侧边栏。
+
+```html
+<aithe-sidebar
+  brand="Admin"
+  collapsible
+  header-height="56px"
+  .items="${menuItems}"
+  active="home"
+></aithe-sidebar>
+```
+
+The `header-height` property ensures the overlay sidebar starts below the header instead of covering it.
+`header-height` 属性确保覆盖模式的侧边栏从 header 下方开始，而非覆盖 header。
+
+### 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 sidebar = document.querySelector('aithe-sidebar');
+sidebar.itemFilter = (item, depth) => {
+  // Hide "Settings" for non-admin users
+  if (item.id === 'settings' && !currentUser.roles.includes('admin')) {
+    return false;
+  }
+  // Hide all children under "debug" group
+  if (depth >= 2 && item.id.startsWith('debug-')) {
+    return false;
+  }
+  return true;
+};
+```
+
+```html
+<aithe-sidebar
+  brand="Admin"
+  collapsible
+  .items="${menuItems}"
+  active="home"
+></aithe-sidebar>
+```

package/docs/api/navigation/menu-item.md

@@ -1,34 +1,42 @@
 # AitheMenuItem / AitheMenuItem 菜单项
 
-> Leaf navigation item for `aithe-menu`.
-> aithe-menu 的叶子导航项。
+> Leaf navigation item for `aithe-menu`. Supports collapsed mode: when `collapsed` is true, hides the label and displays only the icon.
+> aithe-menu 的叶子导航项。支持折叠模式：当 collapsed 为 true 时，隐藏文字标签仅显示图标。
 
 ## Slots / 插槽
 
-| Name | Description (EN) | Description (CN) |
-|------|-------------------|-------------------|
+| Name      | Description (EN)                          | Description (CN) |
+| --------- | ----------------------------------------- | ---------------- |
 | (default) | Default slot for menu item label content. | 菜单项标签内容。 |
 
 ## Properties / 属性
 
-| Name | Type | Default | Description (EN) | Description (CN) |
-|------|------|---------|-------------------|-------------------|
-| name | `string` | `''` | Unique key identifying this menu item. | 菜单项唯一标识键。 |
-| title | `string` | `''` | Display title (shown as tooltip). | 显示标题（作为工具提示）。 |
-| icon | `string` | `''` | Icon name displayed before the item label. | 在项标签前显示的图标名称。 |
-| disabled | `boolean` | `false` | Whether the menu item is disabled. | 是否禁用菜单项。 |
-| active | `boolean` | `false` | Whether the menu item is currently active (selected). | 是否当前选中。 |
-| menuMode | `'horizontal' \| 'vertical'` | `'vertical'` | Inherited menu mode from parent `aithe-menu`. | 从父级 aithe-menu 继承的菜单模式。 |
-| collapsed | `boolean` | `false` | Inherited collapsed state from parent `aithe-menu`. | 从父级 aithe-menu 继承的折叠状态。 |
+| Name      | Type                         | Default      | Description (EN)                                                                                           | Description (CN)                                                     |
+| --------- | ---------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| name      | `string`                     | `''`         | Unique key identifying this menu item.                                                                     | 菜单项唯一标识键。                                                   |
+| title     | `string`                     | `''`         | Display title (shown as tooltip).                                                                          | 显示标题（作为工具提示）。                                           |
+| icon      | `string`                     | `''`         | Icon name displayed before the item label.                                                                 | 在项标签前显示的图标名称。                                           |
+| disabled  | `boolean`                    | `false`      | Whether the menu item is disabled.                                                                         | 是否禁用菜单项。                                                     |
+| active    | `boolean`                    | `false`      | Whether the menu item is currently active (selected).                                                      | 是否当前选中。                                                       |
+| menuMode  | `'horizontal' \| 'vertical'` | `'vertical'` | Inherited menu mode from parent `aithe-menu`.                                                              | 从父级 aithe-menu 继承的菜单模式。                                   |
+| collapsed | `boolean`                    | `false`      | Inherited collapsed state from parent `aithe-menu`. When true, hides the label and displays only the icon. | 从父级 aithe-menu 继承的折叠状态。为 true 时隐藏文字标签仅显示图标。 |
 
 ## Events / 事件
 
-| Name | Detail | Description (EN) | Description (CN) |
-|------|--------|-------------------|-------------------|
+| Name              | Detail             | Description (EN)                  | Description (CN)   |
+| ----------------- | ------------------ | --------------------------------- | ------------------ |
 | aithe-menu-select | `{ name: string }` | Emitted when the item is clicked. | 菜单项点击时触发。 |
 
 ## Examples / 示例
 
 ```html
 <aithe-menu-item name="dashboard" title="Dashboard" icon="home" disabled>Dashboard</aithe-menu-item>
-```
+```
+
+### Collapsed mode / 折叠模式
+
+```html
+<aithe-menu collapsed>
+  <aithe-menu-item name="dashboard" title="Dashboard" icon="home">Dashboard</aithe-menu-item>
+</aithe-menu>
+```

package/docs/api/navigation/sub-menu.md

@@ -1,32 +1,32 @@
 # AitheSubMenu / AitheSubMenu 子菜单
 
-> Nested branch (sub-menu) item for `aithe-menu` with expandable children.
-> aithe-menu 的嵌套分支（子菜单）项，支持展开子项。
+> Nested branch (sub-menu) item for `aithe-menu` with expandable children. Supports collapsed mode: when `collapsed` is true, the trigger shows only the icon and children are displayed in a popup panel.
+> aithe-menu 的嵌套分支（子菜单）项，支持展开子项。支持折叠模式：当 collapsed 为 true 时，触发器仅显示图标，子菜单以弹出面板形式展示。
 
 ## Slots / 插槽
 
-| Name | Description (EN) | Description (CN) |
-|------|-------------------|-------------------|
+| Name      | Description (EN)                                    | Description (CN)              |
+| --------- | --------------------------------------------------- | ----------------------------- |
 | (default) | Default slot for nested `aithe-menu-item` elements. | 嵌套的 aithe-menu-item 元素。 |
 
 ## Properties / 属性
 
-| Name | Type | Default | Description (EN) | Description (CN) |
-|------|------|---------|-------------------|-------------------|
-| name | `string` | `''` | Unique key identifying this sub-menu. | 子菜单唯一标识键。 |
-| title | `string` | `''` | Display title for the sub-menu trigger. | 子菜单触发器的显示标题。 |
-| icon | `string` | `''` | Icon name to display before the title. Uses built-in `aithe-icon` names. | 在标题前显示的图标名称，使用 aithe-icon 内置图标名。 |
-| disabled | `boolean` | `false` | Whether the sub-menu is disabled. | 是否禁用子菜单。 |
-| open | `boolean` | `false` | Whether the sub-menu is currently expanded. | 是否当前展开。 |
-| active | `boolean` | `false` | Whether any child item is currently active. | 是否有子项当前选中。 |
-| menuMode | `'horizontal' \| 'vertical'` | `'vertical'` | Inherited menu mode from parent `aithe-menu`. | 从父级 aithe-menu 继承的菜单模式。 |
-| collapsed | `boolean` | `false` | Inherited collapsed state from parent `aithe-menu`. | 从父级 aithe-menu 继承的折叠状态。 |
+| Name      | Type                         | Default      | Description (EN)                                                                                                                            | Description (CN)                                                                         |
+| --------- | ---------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| name      | `string`                     | `''`         | Unique key identifying this sub-menu.                                                                                                       | 子菜单唯一标识键。                                                                       |
+| title     | `string`                     | `''`         | Display title for the sub-menu trigger.                                                                                                     | 子菜单触发器的显示标题。                                                                 |
+| icon      | `string`                     | `''`         | Icon name to display before the title. Uses built-in `aithe-icon` names.                                                                    | 在标题前显示的图标名称，使用 aithe-icon 内置图标名。                                     |
+| disabled  | `boolean`                    | `false`      | Whether the sub-menu is disabled.                                                                                                           | 是否禁用子菜单。                                                                         |
+| open      | `boolean`                    | `false`      | Whether the sub-menu is currently expanded.                                                                                                 | 是否当前展开。                                                                           |
+| active    | `boolean`                    | `false`      | Whether any child item is currently active.                                                                                                 | 是否有子项当前选中。                                                                     |
+| menuMode  | `'horizontal' \| 'vertical'` | `'vertical'` | Inherited menu mode from parent `aithe-menu`.                                                                                               | 从父级 aithe-menu 继承的菜单模式。                                                       |
+| collapsed | `boolean`                    | `false`      | Inherited collapsed state from parent `aithe-menu`. When true, the trigger shows only the icon and children are displayed in a popup panel. | 从父级 aithe-menu 继承的折叠状态。为 true 时触发器仅显示图标，子菜单以弹出面板形式展示。 |
 
 ## Events / 事件
 
-| Name | Detail | Description (EN) | Description (CN) |
-|------|--------|-------------------|-------------------|
-| — | — | No custom events (toggle is handled internally). | 无自定义事件（切换由内部处理）。 |
+| Name | Detail | Description (EN)                                 | Description (CN)                 |
+| ---- | ------ | ------------------------------------------------ | -------------------------------- |
+| —    | —      | No custom events (toggle is handled internally). | 无自定义事件（切换由内部处理）。 |
 
 ## Examples / 示例
 
@@ -35,4 +35,15 @@
   <aithe-menu-item name="profile">Profile</aithe-menu-item>
   <aithe-menu-item name="security">Security</aithe-menu-item>
 </aithe-sub-menu>
-```
+```
+
+### Collapsed mode / 折叠模式
+
+```html
+<aithe-menu collapsed>
+  <aithe-sub-menu title="Settings" name="settings" icon="settings">
+    <aithe-menu-item name="profile">Profile</aithe-menu-item>
+    <aithe-menu-item name="security">Security</aithe-menu-item>
+  </aithe-sub-menu>
+</aithe-menu>
+```