@aithe/aithe-ui 26.2.2

package/docs/api/form/transfer.md

@@ -0,0 +1,36 @@
+# AitheTransfer / AitheTransfer 穿梭框
+
+> Dual-list transfer component for moving items between source and target panels.
+> 双列表穿梭框组件，用于在源面板和目标面板之间移动项目。
+
+## Slots / 插槽
+
+| Name | Description (EN) | Description (CN) |
+|------|-------------------|-------------------|
+| (default) | Default slot (unused; transfer is self-contained). | 默认插槽（未使用，穿梭框为自包含组件）。 |
+
+## Properties / 属性
+
+| Name | Type | Default | Description (EN) | Description (CN) |
+|------|------|---------|-------------------|-------------------|
+| data | String | '[]' | JSON string of transfer item data. | 穿梭框项目数据的 JSON 字符串。 |
+| value | String | '[]' | JSON string of currently transferred values. | 当前已转移值的 JSON 字符串。 |
+| titles | String | '["Source","Target"]' | JSON string of panel titles [sourceTitle, targetTitle]. | 面板标题的 JSON 字符串 [源标题, 目标标题]。 |
+| searchable | Boolean | false | Whether panels support search/filter. | 是否支持面板搜索过滤。 |
+
+## Events / 事件
+
+| Name | Detail | Description (EN) | Description (CN) |
+|------|--------|-------------------|-------------------|
+| aithe-change | { value: string[] } | Emitted when items are transferred. | 项目转移时触发。 |
+
+## Examples / 示例
+
+```html
+<aithe-transfer
+  data='[{"label":"Item A","id":"a"},{"label":"Item B","id":"b"}]'
+  value='["b"]'
+  titles='["Source","Target"]'
+  searchable
+></aithe-transfer>
+```

package/docs/api/form/upload.md

@@ -0,0 +1,36 @@
+# AitheUpload / AitheUpload 上传
+
+> Local file picker with upload-like progress events.
+> 本地文件选择器，支持类上传进度事件。
+
+## Slots / 插槽
+
+| Name | Description (EN) | Description (CN) |
+|------|-------------------|-------------------|
+| (default) | Default slot for the upload trigger button label. | 上传触发按钮标签内容。 |
+
+## Properties / 属性
+
+| Name | Type | Default | Description (EN) | Description (CN) |
+|------|------|---------|-------------------|-------------------|
+| url | String | '' | Upload target URL. | 上传目标 URL。 |
+| multiple | Boolean | false | Whether multiple files can be selected. | 是否允许选择多个文件。 |
+| accept | String | '' | Accepted file types (MIME or extension). | 接受的文件类型（MIME 或扩展名）。 |
+| limit | Number | 0 | Maximum number of files allowed (0 = unlimited). | 允许的最大文件数（0 = 不限）。 |
+| disabled | Boolean | false | Whether the upload is disabled. | 是否禁用上传。 |
+
+## Events / 事件
+
+| Name | Detail | Description (EN) | Description (CN) |
+|------|--------|-------------------|-------------------|
+| aithe-change | { files } | Emitted when files are selected. | 文件选择时触发。 |
+| aithe-progress | { percent, files } | Emitted with upload progress. | 上传进度时触发。 |
+| aithe-success | { files, url } | Emitted when upload completes. | 上传完成时触发。 |
+
+## Examples / 示例
+
+```html
+<aithe-upload url="/api/upload" accept=".png,.jpg" multiple limit="3">
+  Choose files
+</aithe-upload>
+```

package/docs/api/layout/affix.md

@@ -0,0 +1,31 @@
+# AitheAffix / AitheAffix 固定
+
+> Sticky / affix wrapper that pins content to a fixed position on scroll.
+> 固定/吸顶包装器，滚动时将内容固定到指定位置。
+
+## Slots / 插槽
+
+| Name | Description (EN) | Description (CN) |
+|------|-------------------|-------------------|
+| (default) | Default slot for content to be affixed. | 需要固定的内容。 |
+
+## Properties / 属性
+
+| Name | Type | Default | Description (EN) | Description (CN) |
+|------|------|---------|-------------------|-------------------|
+| offset-top | `number` | `0` | Top offset in pixels before affixing. | 吸顶前的顶部偏移量（像素）。 |
+| target | `string` | `''` | CSS selector for the scroll container target (defaults to window). | 滚动容器目标的 CSS 选择器（默认为 window）。 |
+
+## Events / 事件
+
+| Name | Detail | Description (EN) | Description (CN) |
+|------|--------|-------------------|-------------------|
+| aithe-affix | — | Emitted when affix state changes. | 固定状态变更时触发。 |
+
+## Examples / 示例
+
+```html
+<aithe-affix offset-top="64">
+  <aithe-button>Sticky Button</aithe-button>
+</aithe-affix>
+```

package/docs/api/layout/col.md

@@ -0,0 +1,35 @@
+# AitheCol / AitheCol 列
+
+> 24-grid column item for use inside `aithe-row`.
+> 24栅格列元素，用于 aithe-row 内部。
+
+## Slots / 插槽
+
+| Name | Description (EN) | Description (CN) |
+|------|-------------------|-------------------|
+| (default) | Default slot for column content. | 列内容。 |
+
+## Properties / 属性
+
+| Name | Type | Default | Description (EN) | Description (CN) |
+|------|------|---------|-------------------|-------------------|
+| span | `number` | `24` | Number of grid columns to occupy (1–24). | 占据的栅格数（1–24）。 |
+| offset | `number` | `0` | Number of grid columns to offset from the left. | 左侧偏移的栅格数。 |
+| push | `number` | `0` | Number of grid columns to push right. | 向右推的栅格数。 |
+| pull | `number` | `0` | Number of grid columns to pull left. | 向左拉的栅格数。 |
+| flex | `string` | `''` | Custom flex value (overrides span-based width). | 自定义 flex 值（覆盖基于 span 的宽度）。 |
+
+## Events / 事件
+
+| Name | Detail | Description (EN) | Description (CN) |
+|------|--------|-------------------|-------------------|
+| — | — | No custom events. | 无自定义事件。 |
+
+## Examples / 示例
+
+```html
+<aithe-row gutter="16">
+  <aithe-col span="8" offset="4">Content</aithe-col>
+  <aithe-col span="12" flex="1 1 auto">Flexible</aithe-col>
+</aithe-row>
+```

package/docs/api/layout/collapse-item.md

@@ -0,0 +1,34 @@
+# AitheCollapseItem / AitheCollapseItem 折叠面板项
+
+> Single collapsible panel for use inside `aithe-collapse`.
+> 单个可折叠面板，用于 aithe-collapse 内部。
+
+## Slots / 插槽
+
+| Name | Description (EN) | Description (CN) |
+|------|-------------------|-------------------|
+| (default) | Default slot for panel body content. | 面板正文内容。 |
+
+## Properties / 属性
+
+| Name | Type | Default | Description (EN) | Description (CN) |
+|------|------|---------|-------------------|-------------------|
+| title | `string` | `''` | Panel header title text. | 面板标题文本。 |
+| name | `string` | `''` | Unique key identifying this panel. | 面板唯一标识键。 |
+| icon | `string` | `''` | Icon name to display before the title. Uses built-in `aithe-icon` names. | 在标题前显示的图标名称，使用 aithe-icon 内置图标名。 |
+| disabled | `boolean` | `false` | Whether the panel is disabled and cannot be toggled. | 是否禁用面板切换。 |
+| open | `boolean` | `false` | Whether the panel is currently expanded. | 是否当前展开。 |
+
+## Events / 事件
+
+| Name | Detail | Description (EN) | Description (CN) |
+|------|--------|-------------------|-------------------|
+| aithe-collapse-toggle | `{ name: string, open: boolean }` | Emitted when the panel is toggled. | 面板切换时触发。 |
+
+## Examples / 示例
+
+```html
+<aithe-collapse-item title="Details" name="detail-1" icon="info">
+  <p>Expanded content here.</p>
+</aithe-collapse-item>
+```

package/docs/api/layout/collapse.md

@@ -0,0 +1,32 @@
+# AitheCollapse / AitheCollapse 折叠面板
+
+> Accordion / multi-expand collapse container for collapsible panels.
+> 手风琴/多展开折叠容器，用于可折叠面板。
+
+## Slots / 插槽
+
+| Name | Description (EN) | Description (CN) |
+|------|-------------------|-------------------|
+| (default) | Default slot for `aithe-collapse-item` elements. | aithe-collapse-item 面板元素。 |
+
+## Properties / 属性
+
+| Name | Type | Default | Description (EN) | Description (CN) |
+|------|------|---------|-------------------|-------------------|
+| active-key | `string` | `''` | Comma-separated keys of active (expanded) panels. | 活动（展开）面板的键，逗号分隔。 |
+| accordion | `boolean` | `false` | Whether only one panel can be open at a time (accordion mode). | 是否只允许同时打开一个面板（手风琴模式）。 |
+
+## Events / 事件
+
+| Name | Detail | Description (EN) | Description (CN) |
+|------|--------|-------------------|-------------------|
+| aithe-change | `{ activeKey: string }` | Emitted when the active panel changes. | 活动面板变更时触发。 |
+
+## Examples / 示例
+
+```html
+<aithe-collapse active-key="panel-1" accordion>
+  <aithe-collapse-item title="Section A" name="panel-1">Content A</aithe-collapse-item>
+  <aithe-collapse-item title="Section B" name="panel-2">Content B</aithe-collapse-item>
+</aithe-collapse>
+```

package/docs/api/layout/container.md

@@ -0,0 +1,35 @@
+# AitheContainer / AitheContainer 容器
+
+> Top-level page layout container with configurable width, padding, and direction.
+> 顶层页面布局容器，支持配置宽度、内边距和方向。
+
+## Slots / 插槽
+
+| Name | Description (EN) | Description (CN) |
+|------|-------------------|-------------------|
+| (default) | Default slot for container content. | 容器内容。 |
+
+## Properties / 属性
+
+| Name | Type | Default | Description (EN) | Description (CN) |
+|------|------|---------|-------------------|-------------------|
+| maxWidth | `string` | `'1280px'` | Maximum width of the container (CSS value). | 容器最大宽度（CSS 值）。 |
+| padding | `string` | `'var(--aithe-space-lg)'` | Horizontal padding of the container (CSS value). | 容器水平内边距（CSS 值）。 |
+| gap | `string` | `'0'` | Gap between child elements (CSS value). | 子元素间距（CSS 值）。 |
+| fluid | `boolean` | `false` | Whether the container fills the full width without max-width constraint. | 是否填满全宽，不受最大宽度限制。 |
+| full | `boolean` | `false` | Whether the container fills the full viewport height. | 是否填满整个视口高度。 |
+| direction | `'row' \| 'column'` | `'column'` | Flex direction for child layout. | 子元素排列方向。 |
+
+## Events / 事件
+
+| Name | Detail | Description (EN) | Description (CN) |
+|------|--------|-------------------|-------------------|
+| — | — | No custom events. | 无自定义事件。 |
+
+## Examples / 示例
+
+```html
+<aithe-container max-width="960px" padding="var(--aithe-space-lg)" direction="column">
+  <p>Centered content</p>
+</aithe-container>
+```

package/docs/api/layout/flex.md

@@ -0,0 +1,36 @@
+# AitheFlex / AitheFlex 弹性布局
+
+> Quick flex layout helper with declarative properties.
+> 快速弹性布局辅助组件，支持声明式属性配置。
+
+## Slots / 插槽
+
+| Name | Description (EN) | Description (CN) |
+|------|-------------------|-------------------|
+| (default) | Default slot for flex child elements. | 弹性子元素内容。 |
+
+## Properties / 属性
+
+| Name | Type | Default | Description (EN) | Description (CN) |
+|------|------|---------|-------------------|-------------------|
+| justify | `string` | `'flex-start'` | Flex justify-content value. | flex justify-content 值。 |
+| align | `string` | `'stretch'` | Flex align-items value. | flex align-items 值。 |
+| direction | `'row' \| 'column'` | `'row'` | Flex direction. | flex 方向。 |
+| gap | `string` | `'var(--aithe-space-md)'` | Gap between flex items (CSS value). | flex 子元素间距（CSS 值）。 |
+| wrap | `'nowrap' \| 'wrap'` | `'nowrap'` | Flex wrap behavior. | flex 换行方式。 |
+| inline | `boolean` | `false` | Whether the flex container is inline. | 是否为内联弹性容器。 |
+
+## Events / 事件
+
+| Name | Detail | Description (EN) | Description (CN) |
+|------|--------|-------------------|-------------------|
+| — | — | No custom events. | 无自定义事件。 |
+
+## Examples / 示例
+
+```html
+<aithe-flex justify="center" align="middle" gap="var(--aithe-space-md)" direction="row">
+  <div>Item 1</div>
+  <div>Item 2</div>
+</aithe-flex>
+```

package/docs/api/layout/page-container.md

@@ -0,0 +1,31 @@
+# AithePageContainer / AithePageContainer 页面容器
+
+> Standard page shell with title and consistent spacing.
+> 标准页面外壳，包含标题和统一间距。
+
+## Slots / 插槽
+
+| Name | Description (EN) | Description (CN) |
+|------|-------------------|-------------------|
+| (default) | Default slot for page body content. | 页面正文内容。 |
+
+## Properties / 属性
+
+| Name | Type | Default | Description (EN) | Description (CN) |
+|------|------|---------|-------------------|-------------------|
+| title | `string` | `''` | Page title text. | 页面标题文本。 |
+| padding | `string` | `'var(--aithe-space-xl)'` | Body section padding (CSS value). | 正文区域内边距（CSS 值）。 |
+
+## Events / 事件
+
+| Name | Detail | Description (EN) | Description (CN) |
+|------|--------|-------------------|-------------------|
+| — | — | No custom events. | 无自定义事件。 |
+
+## Examples / 示例
+
+```html
+<aithe-page-container title="Dashboard" padding="var(--aithe-space-xl)">
+  <p>Page content here.</p>
+</aithe-page-container>
+```

package/docs/api/layout/page.md

@@ -0,0 +1,35 @@
+# AithePage / AithePage 页面
+
+> Full-page layout with header (title, subtitle, actions) and content area.
+> 全页布局，包含标题区（标题、副标题、操作区）和内容区。
+
+## Slots / 插槽
+
+| Name | Description (EN) | Description (CN) |
+|------|-------------------|-------------------|
+| (default) | Default slot for page body content. | 页面正文内容。 |
+| title | Custom title content (overrides `title` property). | 自定义标题内容。 |
+| subtitle | Custom subtitle content (overrides `subtitle` property). | 自定义副标题内容。 |
+| actions | Action buttons area in the header. | 标题区操作按钮区域。 |
+
+## Properties / 属性
+
+| Name | Type | Default | Description (EN) | Description (CN) |
+|------|------|---------|-------------------|-------------------|
+| title | `string` | `''` | Page title text. | 页面标题文本。 |
+| subtitle | `string` | `''` | Page subtitle text. | 页面副标题文本。 |
+
+## Events / 事件
+
+| Name | Detail | Description (EN) | Description (CN) |
+|------|--------|-------------------|-------------------|
+| — | — | No custom events. | 无自定义事件。 |
+
+## Examples / 示例
+
+```html
+<aithe-page title="Settings" subtitle="Manage your preferences">
+  <slot name="actions"><aithe-button type="primary">Save</aithe-button></slot>
+  <p>Page content here.</p>
+</aithe-page>
+```

package/docs/api/layout/row.md

@@ -0,0 +1,34 @@
+# AitheRow / AitheRow 行
+
+> 24-grid row container for grid layout system.
+> 24栅格行容器，用于栅格布局系统。
+
+## Slots / 插槽
+
+| Name | Description (EN) | Description (CN) |
+|------|-------------------|-------------------|
+| (default) | Default slot for `aithe-col` elements. | aithe-col 列元素。 |
+
+## Properties / 属性
+
+| Name | Type | Default | Description (EN) | Description (CN) |
+|------|------|---------|-------------------|-------------------|
+| gutter | `number` | `24` | Column gutter in pixels. | 列间距（像素）。 |
+| row-gap | `number` | `24` | Vertical gap between rows in pixels. | 行间距（像素）。 |
+| justify | `'start' \| 'center' \| 'end' \| 'space-between' \| 'space-around'` | `'start'` | Horizontal alignment of columns. | 列水平对齐方式。 |
+| align | `'stretch' \| 'start' \| 'center' \| 'end'` | `'stretch'` | Vertical alignment of columns. | 列垂直对齐方式。 |
+
+## Events / 事件
+
+| Name | Detail | Description (EN) | Description (CN) |
+|------|--------|-------------------|-------------------|
+| — | — | No custom events. | 无自定义事件。 |
+
+## Examples / 示例
+
+```html
+<aithe-row gutter="16" justify="space-between" align="center">
+  <aithe-col span="12">Left</aithe-col>
+  <aithe-col span="12">Right</aithe-col>
+</aithe-row>
+```

package/docs/api/layout/space.md

@@ -0,0 +1,34 @@
+# AitheSpace / AitheSpace 间距
+
+> Equal spacing helper for consistent gaps between child elements.
+> 等间距辅助组件，为子元素提供统一间距。
+
+## Slots / 插槽
+
+| Name | Description (EN) | Description (CN) |
+|------|-------------------|-------------------|
+| (default) | Default slot for spaced child elements. | 需要间距的子元素内容。 |
+
+## Properties / 属性
+
+| Name | Type | Default | Description (EN) | Description (CN) |
+|------|------|---------|-------------------|-------------------|
+| size | `string` | `'var(--aithe-space-md)'` | Gap size between items (CSS value). | 子元素间距大小（CSS 值）。 |
+| direction | `'vertical' \| 'horizontal'` | `'vertical'` | Spacing direction. | 间距方向。 |
+| align | `string` | `'stretch'` | Cross-axis alignment. | 交叉轴对齐方式。 |
+| wrap | `boolean` | `false` | Whether items wrap when overflowing. | 子元素溢出时是否换行。 |
+
+## Events / 事件
+
+| Name | Detail | Description (EN) | Description (CN) |
+|------|--------|-------------------|-------------------|
+| — | — | No custom events. | 无自定义事件。 |
+
+## Examples / 示例
+
+```html
+<aithe-space size="var(--aithe-space-md)" direction="horizontal" wrap>
+  <aithe-button>Save</aithe-button>
+  <aithe-button>Cancel</aithe-button>
+</aithe-space>
+```

package/docs/api/navigation/back-top.md

@@ -0,0 +1,29 @@
+# AitheBackTop / AitheBackTop 回到顶部
+
+> Back to top floating action button that appears after scrolling past a threshold.
+> 回到顶部浮动按钮，滚动超过阈值后出现。
+
+## Slots / 插槽
+
+| Name | Description (EN) | Description (CN) |
+|------|-------------------|-------------------|
+| (default) | Default slot for custom button content (overrides default arrow). | 自定义按钮内容（覆盖默认箭头）。 |
+
+## Properties / 属性
+
+| Name | Type | Default | Description (EN) | Description (CN) |
+|------|------|---------|-------------------|-------------------|
+| target | `string` | `''` | CSS selector for the scroll container (defaults to window). | 滚动容器的 CSS 选择器（默认为 window）。 |
+| visibility-height | `number` | `260` | Scroll threshold in pixels before the button appears. | 按钮出现前的滚动阈值（像素）。 |
+
+## Events / 事件
+
+| Name | Detail | Description (EN) | Description (CN) |
+|------|--------|-------------------|-------------------|
+| — | — | No custom events. | 无自定义事件。 |
+
+## Examples / 示例
+
+```html
+<aithe-back-top visibility-height="300" target="#scroll-container"></aithe-back-top>
+```

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

@@ -0,0 +1,32 @@
+# AitheBreadcrumbItem / AitheBreadcrumbItem 面包屑项
+
+> Single breadcrumb link or text item for use inside `aithe-breadcrumb`.
+> 单个面包文本项，用于 aithe-breadcrumb 内部。
+
+## Slots / 插槽
+
+| Name | Description (EN) | Description (CN) |
+|------|-------------------|-------------------|
+| (default) | Default slot for breadcrumb item label text. | 面包屑项标签文本。 |
+
+## Properties / 属性
+
+| Name | Type | Default | Description (EN) | Description (CN) |
+|------|------|---------|-------------------|-------------------|
+| href | `string` | `''` | Link URL for navigable breadcrumb items. | 可导航面包屑项的链接地址。 |
+| target | `string` | `''` | Link target attribute. | 链接 target 属性。 |
+| disabled | `boolean` | `false` | Whether the breadcrumb item is disabled. | 是否禁用面包屑项。 |
+| current | `boolean` | `false` | Whether this is the current (last) breadcrumb item. | 是否为当前（最后一个）面包屑项。 |
+| separator | `string` | `'/'` | Separator character (inherited from parent `aithe-breadcrumb`). | 分隔符（从父级 aithe-breadcrumb 继承）。 |
+
+## Events / 事件
+
+| Name | Detail | Description (EN) | Description (CN) |
+|------|--------|-------------------|-------------------|
+| — | — | No custom events. | 无自定义事件。 |
+
+## Examples / 示例
+
+```html
+<aithe-breadcrumb-item href="/settings" target="_self">Settings</aithe-breadcrumb-item>
+```

package/docs/api/navigation/breadcrumb.md

@@ -0,0 +1,32 @@
+# AitheBreadcrumb / AitheBreadcrumb 面包屑
+
+> Breadcrumb navigation container for showing page hierarchy.
+> 面包屑导航容器，用于展示页面层级关系。
+
+## Slots / 插槽
+
+| Name | Description (EN) | Description (CN) |
+|------|-------------------|-------------------|
+| (default) | Default slot for `aithe-breadcrumb-item` elements. | aithe-breadcrumb-item 元素。 |
+
+## Properties / 属性
+
+| Name | Type | Default | Description (EN) | Description (CN) |
+|------|------|---------|-------------------|-------------------|
+| separator | `string` | `'/'` | Separator character between breadcrumb items. | 面包屑项之间的分隔符。 |
+
+## Events / 事件
+
+| Name | Detail | Description (EN) | Description (CN) |
+|------|--------|-------------------|-------------------|
+| — | — | No custom events. | 无自定义事件。 |
+
+## Examples / 示例
+
+```html
+<aithe-breadcrumb separator="/">
+  <aithe-breadcrumb-item href="/home">Home</aithe-breadcrumb-item>
+  <aithe-breadcrumb-item href="/products">Products</aithe-breadcrumb-item>
+  <aithe-breadcrumb-item>Detail</aithe-breadcrumb-item>
+</aithe-breadcrumb>
+```

package/docs/api/navigation/dropdown.md

@@ -0,0 +1,50 @@
+# AitheDropdown / AitheDropdown 下拉菜单
+
+> Dropdown menu with nested submenus, keyboard navigation, and hover/click triggers.
+> 下拉菜单，支持嵌套子菜单、键盘导航和悬停/点击触发。
+
+## 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 | AitheDropdownItem[] | [] | Array of dropdown menu item objects. Each item supports `icon` and `intent` (AitheIntent) fields. | 下拉菜单项对象数组。每项支持 `icon` 和 `intent`（AitheIntent）字段。 |
+| placement | 'bottom-start' \| 'bottom-end' \| 'top-start' \| 'top-end' | 'bottom-start' | Dropdown panel placement. Auto-adapts to viewport. | 下拉面板位置。自动适应视口。 |
+| offset | `number` | 8 | Pixel gap between anchor and dropdown panel. | 锚点与下拉面板之间的像素间距。 |
+
+## Events / 事件
+
+| Name | Detail | Description (EN) | Description (CN) |
+|------|--------|-------------------|-------------------|
+| aithe-select | { item, path, id } | Emitted when a menu item is selected. | 菜单项选中时触发。 |
+| aithe-open-change | { open } | Emitted when open state changes. | 开关状态变更时触发。 |
+
+## Item Fields / 菜单项字段
+
+| Field | Type | Description (EN) | Description (CN) |
+|-------|------|-------------------|-------------------|
+| label | `string` | Display text. | 显示文本。 |
+| id | `string` | Unique value emitted on select. | 选择时发出的唯一值。 |
+| disabled | `boolean` | Whether the item is non-interactive. | 是否不可交互。 |
+| divider | `boolean` | Render a visual separator before this item. | 在此项前渲染视觉分隔线。 |
+| intent | AitheIntent | Visual intent / semantic color for the item. | 项的视觉意图/语义色。 |
+| shortcut | `string` | Keyboard shortcut hint. | 键盘快捷键提示。 |
+| icon | `string` | Icon name rendered before the label via aithe-icon. | 通过 aithe-icon 在标签前渲染的图标名称。 |
+| children | AitheDropdownItem[] | Nested sub-menu items. | 嵌套子菜单项。 |
+
+## Examples / 示例
+
+```html
+<aithe-dropdown trigger="click" title="Actions" icon="menu" items='[{"id":"a","label":"Action"},{"id":"b","label":"Another"}]'>
+  <button>Menu</button>
+</aithe-dropdown>
+```

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

@@ -0,0 +1,34 @@
+# AitheMenuItem / AitheMenuItem 菜单项
+
+> Leaf navigation item for `aithe-menu`.
+> aithe-menu 的叶子导航项。
+
+## Slots / 插槽
+
+| 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 继承的折叠状态。 |
+
+## Events / 事件
+
+| 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>
+```

package/docs/api/navigation/menu.md

@@ -0,0 +1,36 @@
+# AitheMenu / AitheMenu 菜单
+
+> Cross-framework navigation menu with vertical and horizontal modes.
+> 跨框架导航菜单，支持垂直和水平模式。
+
+## Slots / 插槽
+
+| Name | Description (EN) | Description (CN) |
+|------|-------------------|-------------------|
+| (default) | Default slot for `aithe-menu-item` and `aithe-sub-menu` elements. | aithe-menu-item 和 aithe-sub-menu 元素。 |
+
+## Properties / 属性
+
+| Name | Type | Default | Description (EN) | Description (CN) |
+|------|------|---------|-------------------|-------------------|
+| mode | `'horizontal' \| 'vertical'` | `'vertical'` | Menu layout mode. | 菜单布局模式。 |
+| active | `string` | `''` | Active (selected) menu item key. | 当前选中的菜单项键。 |
+| collapsed | `boolean` | `false` | Whether the menu is in collapsed state. | 菜单是否处于折叠状态。 |
+| selectable | `boolean` | `true` | Whether menu items can be selected. | 菜单项是否可选中。 |
+
+## Events / 事件
+
+| Name | Detail | Description (EN) | Description (CN) |
+|------|--------|-------------------|-------------------|
+| aithe-select | `{ active: string }` | Emitted when a menu item is selected. | 菜单项选中时触发。 |
+
+## Examples / 示例
+
+```html
+<aithe-menu mode="vertical" active="home">
+  <aithe-menu-item name="home">Home</aithe-menu-item>
+  <aithe-sub-menu title="Settings">
+    <aithe-menu-item name="profile">Profile</aithe-menu-item>
+  </aithe-sub-menu>
+</aithe-menu>
+```