@apexhub/apex-ui-react 0.0.0-stage → 1.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (185) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +37 -2
  3. package/dist/en_US.d.ts +191 -0
  4. package/dist/index.cjs +40727 -0
  5. package/dist/index.d.ts +6873 -0
  6. package/dist/index.mjs +40711 -0
  7. package/dist/llm/alert.tokens.txt +44 -0
  8. package/dist/llm/alert.txt +167 -0
  9. package/dist/llm/apex-provider.txt +369 -0
  10. package/dist/llm/auto-complete.tokens.txt +77 -0
  11. package/dist/llm/auto-complete.txt +373 -0
  12. package/dist/llm/avatar.tokens.txt +38 -0
  13. package/dist/llm/avatar.txt +199 -0
  14. package/dist/llm/breadcrumb.tokens.txt +143 -0
  15. package/dist/llm/breadcrumb.txt +251 -0
  16. package/dist/llm/button.tokens.txt +470 -0
  17. package/dist/llm/button.txt +270 -0
  18. package/dist/llm/card.tokens.txt +29 -0
  19. package/dist/llm/card.txt +118 -0
  20. package/dist/llm/cascader.tokens.txt +261 -0
  21. package/dist/llm/cascader.txt +917 -0
  22. package/dist/llm/checkbox.tokens.txt +36 -0
  23. package/dist/llm/checkbox.txt +343 -0
  24. package/dist/llm/collapse.tokens.txt +84 -0
  25. package/dist/llm/collapse.txt +330 -0
  26. package/dist/llm/date-picker.tokens.txt +171 -0
  27. package/dist/llm/date-picker.txt +428 -0
  28. package/dist/llm/divider.tokens.txt +22 -0
  29. package/dist/llm/divider.txt +161 -0
  30. package/dist/llm/drawer.tokens.txt +71 -0
  31. package/dist/llm/drawer.txt +369 -0
  32. package/dist/llm/dropdown.tokens.txt +59 -0
  33. package/dist/llm/dropdown.txt +420 -0
  34. package/dist/llm/form.tokens.txt +28 -0
  35. package/dist/llm/form.txt +341 -0
  36. package/dist/llm/grid.txt +419 -0
  37. package/dist/llm/image.tokens.txt +28 -0
  38. package/dist/llm/image.txt +428 -0
  39. package/dist/llm/input-number.tokens.txt +159 -0
  40. package/dist/llm/input-number.txt +491 -0
  41. package/dist/llm/input.tokens.txt +136 -0
  42. package/dist/llm/input.txt +424 -0
  43. package/dist/llm/layout.tokens.txt +29 -0
  44. package/dist/llm/layout.txt +298 -0
  45. package/dist/llm/menu.tokens.txt +100 -0
  46. package/dist/llm/menu.txt +687 -0
  47. package/dist/llm/message.tokens.txt +25 -0
  48. package/dist/llm/message.txt +301 -0
  49. package/dist/llm/modal.tokens.txt +96 -0
  50. package/dist/llm/modal.txt +584 -0
  51. package/dist/llm/notification.tokens.txt +79 -0
  52. package/dist/llm/notification.txt +383 -0
  53. package/dist/llm/pagination.tokens.txt +35 -0
  54. package/dist/llm/pagination.txt +217 -0
  55. package/dist/llm/popover.tokens.txt +18 -0
  56. package/dist/llm/popover.txt +233 -0
  57. package/dist/llm/progress.tokens.txt +83 -0
  58. package/dist/llm/progress.txt +279 -0
  59. package/dist/llm/radio.tokens.txt +26 -0
  60. package/dist/llm/radio.txt +385 -0
  61. package/dist/llm/rate.tokens.txt +20 -0
  62. package/dist/llm/rate.txt +241 -0
  63. package/dist/llm/select.tokens.txt +160 -0
  64. package/dist/llm/select.txt +831 -0
  65. package/dist/llm/skeleton.tokens.txt +15 -0
  66. package/dist/llm/skeleton.txt +275 -0
  67. package/dist/llm/spin.tokens.txt +21 -0
  68. package/dist/llm/spin.txt +294 -0
  69. package/dist/llm/steps.tokens.txt +30 -0
  70. package/dist/llm/steps.txt +300 -0
  71. package/dist/llm/switch.tokens.txt +38 -0
  72. package/dist/llm/switch.txt +216 -0
  73. package/dist/llm/table.tokens.txt +94 -0
  74. package/dist/llm/table.txt +1049 -0
  75. package/dist/llm/tabs.tokens.txt +78 -0
  76. package/dist/llm/tabs.txt +306 -0
  77. package/dist/llm/tag.tokens.txt +75 -0
  78. package/dist/llm/tag.txt +304 -0
  79. package/dist/llm/tooltip.tokens.txt +22 -0
  80. package/dist/llm/tooltip.txt +304 -0
  81. package/dist/llm/tree-select.tokens.txt +175 -0
  82. package/dist/llm/tree-select.txt +772 -0
  83. package/dist/llm/tree.tokens.txt +34 -0
  84. package/dist/llm/tree.txt +501 -0
  85. package/dist/llm/typography.tokens.txt +60 -0
  86. package/dist/llm/typography.txt +413 -0
  87. package/dist/llm/upload.tokens.txt +205 -0
  88. package/dist/llm/upload.txt +708 -0
  89. package/dist/llms-full.txt +16826 -0
  90. package/dist/llms-theme.txt +32 -0
  91. package/dist/llms.txt +59 -0
  92. package/dist/locale/en_US.cjs +160 -0
  93. package/dist/locale/en_US.d.ts +4 -0
  94. package/dist/locale/en_US.mjs +161 -0
  95. package/dist/locale/zh_CN.cjs +160 -0
  96. package/dist/locale/zh_CN.d.ts +4 -0
  97. package/dist/locale/zh_CN.mjs +161 -0
  98. package/dist/style.css +20095 -0
  99. package/dist/zh_CN.d.ts +191 -0
  100. package/llms-full.txt +16826 -0
  101. package/llms-theme.txt +32 -0
  102. package/llms.txt +59 -0
  103. package/package.json +118 -3
  104. package/src/alert/llm.txt +167 -0
  105. package/src/alert/tokens.txt +44 -0
  106. package/src/apex-provider/llm.txt +369 -0
  107. package/src/auto-complete/llm.txt +373 -0
  108. package/src/auto-complete/tokens.txt +77 -0
  109. package/src/avatar/llm.txt +199 -0
  110. package/src/avatar/tokens.txt +38 -0
  111. package/src/breadcrumb/llm.txt +251 -0
  112. package/src/breadcrumb/tokens.txt +143 -0
  113. package/src/button/llm.txt +270 -0
  114. package/src/button/tokens.txt +470 -0
  115. package/src/card/llm.txt +118 -0
  116. package/src/card/tokens.txt +29 -0
  117. package/src/cascader/llm.txt +917 -0
  118. package/src/cascader/tokens.txt +261 -0
  119. package/src/checkbox/llm.txt +343 -0
  120. package/src/checkbox/tokens.txt +36 -0
  121. package/src/collapse/llm.txt +330 -0
  122. package/src/collapse/tokens.txt +84 -0
  123. package/src/date-picker/llm.txt +428 -0
  124. package/src/date-picker/tokens.txt +171 -0
  125. package/src/divider/llm.txt +161 -0
  126. package/src/divider/tokens.txt +22 -0
  127. package/src/drawer/llm.txt +369 -0
  128. package/src/drawer/tokens.txt +71 -0
  129. package/src/dropdown/llm.txt +420 -0
  130. package/src/dropdown/tokens.txt +59 -0
  131. package/src/form/llm.txt +341 -0
  132. package/src/form/tokens.txt +28 -0
  133. package/src/grid/llm.txt +419 -0
  134. package/src/image/llm.txt +428 -0
  135. package/src/image/tokens.txt +28 -0
  136. package/src/input/llm.txt +424 -0
  137. package/src/input/tokens.txt +136 -0
  138. package/src/input-number/llm.txt +491 -0
  139. package/src/input-number/tokens.txt +159 -0
  140. package/src/layout/llm.txt +298 -0
  141. package/src/layout/tokens.txt +29 -0
  142. package/src/menu/llm.txt +687 -0
  143. package/src/menu/tokens.txt +100 -0
  144. package/src/message/llm.txt +301 -0
  145. package/src/message/tokens.txt +25 -0
  146. package/src/modal/llm.txt +584 -0
  147. package/src/modal/tokens.txt +96 -0
  148. package/src/notification/llm.txt +383 -0
  149. package/src/notification/tokens.txt +79 -0
  150. package/src/pagination/llm.txt +217 -0
  151. package/src/pagination/tokens.txt +35 -0
  152. package/src/popover/llm.txt +233 -0
  153. package/src/popover/tokens.txt +18 -0
  154. package/src/progress/llm.txt +279 -0
  155. package/src/progress/tokens.txt +83 -0
  156. package/src/radio/llm.txt +385 -0
  157. package/src/radio/tokens.txt +26 -0
  158. package/src/rate/llm.txt +241 -0
  159. package/src/rate/tokens.txt +20 -0
  160. package/src/select/llm.txt +831 -0
  161. package/src/select/tokens.txt +160 -0
  162. package/src/skeleton/llm.txt +275 -0
  163. package/src/skeleton/tokens.txt +15 -0
  164. package/src/spin/llm.txt +294 -0
  165. package/src/spin/tokens.txt +21 -0
  166. package/src/steps/llm.txt +300 -0
  167. package/src/steps/tokens.txt +30 -0
  168. package/src/switch/llm.txt +216 -0
  169. package/src/switch/tokens.txt +38 -0
  170. package/src/table/llm.txt +1049 -0
  171. package/src/table/tokens.txt +94 -0
  172. package/src/tabs/llm.txt +306 -0
  173. package/src/tabs/tokens.txt +78 -0
  174. package/src/tag/llm.txt +304 -0
  175. package/src/tag/tokens.txt +75 -0
  176. package/src/tooltip/llm.txt +304 -0
  177. package/src/tooltip/tokens.txt +22 -0
  178. package/src/tree/llm.txt +501 -0
  179. package/src/tree/tokens.txt +34 -0
  180. package/src/tree-select/llm.txt +772 -0
  181. package/src/tree-select/tokens.txt +175 -0
  182. package/src/typography/llm.txt +413 -0
  183. package/src/typography/tokens.txt +60 -0
  184. package/src/upload/llm.txt +708 -0
  185. package/src/upload/tokens.txt +205 -0
@@ -0,0 +1,687 @@
1
+ # Menu
2
+
3
+ > Menu:侧栏持久导航,需要在图标 rail 与展开列表之间切换时。
4
+
5
+ 包:`@apexhub/apex-ui-react`;版本:`1.2.2`(当前源码快照,发布状态以安装包版本为准)。
6
+
7
+ 公开导出:`isKeySelected`、`Menu`。
8
+
9
+ 以下 API 属于 Apex UI;不要据 antd 的同名组件推断额外属性或默认值。默认值列的空缺表示未声明,不代表 `false`。
10
+
11
+ ## 快速开始
12
+
13
+ ```tsx
14
+ import { Button, Menu, type MenuItemType } from '@apexhub/apex-ui-react'
15
+
16
+ import { useState } from 'react'
17
+
18
+ import '@apexhub/apex-ui-react/style.css'
19
+
20
+ const items: MenuItemType[] = [
21
+ { key: 'dashboard', label: '概览', icon: 'A' },
22
+ {
23
+ key: 'workspace',
24
+ label: '工作台',
25
+ icon: 'A',
26
+ children: [
27
+ { key: 'projects', label: '项目' },
28
+ { key: 'members', label: '成员' },
29
+ ],
30
+ },
31
+ { key: 'settings', label: '设置', icon: 'A' },
32
+ ]
33
+
34
+ export default () => {
35
+ const [collapsed, setCollapsed] = useState(false)
36
+
37
+ return (
38
+ <Menu
39
+ items={items}
40
+ collapsed={collapsed}
41
+ onCollapse={setCollapsed}
42
+ defaultOpenKeys={['workspace']}
43
+ defaultSelectedKeys={['projects']}
44
+ footer={
45
+ <Button type="text" onClick={() => setCollapsed((current) => !current)}>
46
+ {collapsed ? '展开菜单' : '收起菜单'}
47
+ </Button>
48
+ }
49
+ />
50
+ )
51
+ }
52
+ ```
53
+
54
+ ## 何时使用
55
+
56
+ - 侧栏持久导航,需要在图标 rail 与展开列表之间切换时。
57
+ - 需要内联子菜单展开、受控选中项或自定义顶栏/底栏时。
58
+ - 触发器旁的临时操作菜单请使用 Dropdown,不要用 Menu。
59
+
60
+ ## API
61
+
62
+ 仅使用类型定义支持的属性;原生属性、ref 目标和事件签名因组件而异。关联类型用于解释字段结构;只有「导出类型」中的名称可从包根导入。
63
+
64
+ ### Menu
65
+
66
+ | 属性 | 说明 | 类型 | 必填 | 默认值 |
67
+ | --- | --- | --- | --- | --- |
68
+ | items | 菜单树 | `MenuItemType[]` | 是 | — |
69
+ | selectable | 项是否可选中 | `boolean` | 否 | `true` |
70
+ | selectedKeys | 受控:当前选中(单选,length ≤ 1) | `string[]` | 否 | — |
71
+ | defaultSelectedKeys | 默认选中 | `string[]` | 否 | — |
72
+ | openKeys | 受控:内联子菜单展开 keys(menu-maximized 态) | `string[]` | 否 | — |
73
+ | defaultOpenKeys | 默认展开的子菜单 keys | `string[]` | 否 | — |
74
+ | theme | 颜色主题 | `"light" \| "dark"` | 否 | `'dark'` |
75
+ | header | 顶栏自定义内容;未提供时不渲染 header 节点 | `React.ReactNode` | 否 | — |
76
+ | footer | 底栏自定义内容 | `React.ReactNode` | 否 | — |
77
+ | collapsed | 受控:是否为 menu-collapsed(收窄仅 icon)态 | `boolean` | 否 | `true` |
78
+ | onCollapse | menu-collapsed ↔ menu-maximized 切换回调 | `(collapsed: boolean) => void` | 否 | — |
79
+ | inlineIndent | 内联子级缩进(px,menu-maximized 态) | `number` | 否 | `24` |
80
+ | classNames | 语义节点 class | `MenuClassNames` | 否 | — |
81
+ | styles | 语义节点内联样式 | `MenuStyles` | 否 | — |
82
+ | onSelect | 选中变化 | `(info: MenuSelectInfo) => void` | 否 | — |
83
+ | onClick | 任意项点击 | `(info: MenuClickInfo) => void` | 否 | — |
84
+ | onOpenChange | 内联子菜单展开变化 | `(openKeys: string[]) => void` | 否 | — |
85
+ | renderChild | 自定义 **子级** menu-maximized 列表项整行渲染(`depth > 0`);<br>顶层 root 项不受影响。返回节点请绑定 `domProps` 以保留选中、展开、点击等行为。 | `MenuRenderChild` | 否 | — |
86
+ | ref | 根 nav ref(React 19) | `React.Ref<HTMLElement>` | 否 | — |
87
+
88
+ ### MenuSemanticDOM
89
+
90
+ Menu 语义化 DOM
91
+
92
+ ```typescript
93
+ type MenuSemanticDOM = | 'root'
94
+ | 'body'
95
+ | 'header'
96
+ | 'footer'
97
+ | 'collapse'
98
+ | 'list'
99
+ | 'rail'
100
+ | 'flyout'
101
+ | 'item'
102
+ | 'submenu'
103
+ | 'sublist'
104
+ ```
105
+
106
+ ### MenuTheme
107
+
108
+ ```typescript
109
+ type MenuTheme = 'light' | 'dark'
110
+ ```
111
+
112
+ ### MenuItemKind
113
+
114
+ ```typescript
115
+ type MenuItemKind = 'group' | 'divider'
116
+ ```
117
+
118
+ ### MenuItemType
119
+
120
+ 菜单项;支持分组、分割线与子级内联展开
121
+
122
+ | 属性 | 说明 | 类型 | 必填 | 默认值 |
123
+ | --- | --- | --- | --- | --- |
124
+ | key | 唯一标识(必填) | `string` | 是 | — |
125
+ | label | 展示文案 | `React.ReactNode` | 否 | — |
126
+ | icon | 行首图标 | `React.ReactNode` | 否 | — |
127
+ | disabled | 禁用该项 | `boolean` | 否 | — |
128
+ | loading | 加载中(不可交互,展示 loading 样式) | `boolean` | 否 | — |
129
+ | danger | 危险样式 | `boolean` | 否 | — |
130
+ | type | 分组标题或分割线 | `"group" \| "divider"` | 否 | — |
131
+ | children | 子级;可再嵌套内联展开 | `MenuItemType[]` | 否 | — |
132
+ | onClick | 项点击 | `(info: MenuClickInfo) => void` | 否 | — |
133
+
134
+ ### MenuClickInfo
135
+
136
+ | 属性 | 说明 | 类型 | 必填 | 默认值 |
137
+ | --- | --- | --- | --- | --- |
138
+ | key | — | `string` | 是 | — |
139
+ | keyPath | — | `string[]` | 是 | — |
140
+ | domEvent | — | `React.MouseEvent<HTMLElement> \| React.KeyboardEvent<HTMLElement>` | 是 | — |
141
+
142
+ ### MenuSelectInfo
143
+
144
+ 继承:`MenuClickInfo`;本节列出新增或重声明字段。
145
+
146
+ | 属性 | 说明 | 类型 | 必填 | 默认值 |
147
+ | --- | --- | --- | --- | --- |
148
+ | selectedKeys | — | `string[]` | 是 | — |
149
+
150
+ ### MenuChildRenderInfo
151
+
152
+ `renderChild` 入参(仅非顶层子项,menu-maximized 列表)
153
+
154
+ | 属性 | 说明 | 类型 | 必填 | 默认值 |
155
+ | --- | --- | --- | --- | --- |
156
+ | item | 当前项数据 | `MenuItemType` | 是 | — |
157
+ | key | 项 key | `string` | 是 | — |
158
+ | label | 项文案(同 `item.label`) | `React.ReactNode` | 否 | — |
159
+ | icon | 项图标(同 `item.icon`) | `React.ReactNode` | 否 | — |
160
+ | selected | 是否与行高亮一致(在 selection path 上:primary 或 secondary) | `boolean` | 是 | — |
161
+ | primarySelected | 是否为 selection path 根节点(`data-selected` / primary 样式) | `boolean` | 是 | — |
162
+ | secondarySelected | 是否为 selection path 子节点(`data-selected-secondary` / secondary 样式) | `boolean` | 是 | — |
163
+ | open | 内联子菜单是否展开 | `boolean` | 是 | — |
164
+ | disabled | 是否禁用 | `boolean` | 是 | — |
165
+ | loading | 是否加载中 | `boolean` | 是 | — |
166
+ | danger | 是否危险态 | `boolean` | 是 | — |
167
+ | hasChildren | 是否有子级 | `boolean` | 是 | — |
168
+ | depth | 嵌套深度(顶层为 0;`renderChild` 仅对 depth > 0 生效) | `number` | 是 | — |
169
+ | keyPath | 从根到当前项的 key 路径 | `string[]` | 是 | — |
170
+ | domProps | 默认行交互属性,可展开到自定义根节点(如 `button`) | `Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'children'> & { 'data-slot': 'menu-item' 'data-selected'?: true 'data-selected-secondary'?: true 'data-active'?: true 'data-open'?: true 'data-danger'?: true 'data-disabled'?: true }` | 是 | — |
171
+
172
+ ### MenuRenderChild
173
+
174
+ ```typescript
175
+ type MenuRenderChild = (info: MenuChildRenderInfo) => React.ReactNode
176
+ ```
177
+
178
+ ### MenuClassNames
179
+
180
+ ```typescript
181
+ type MenuClassNames = | Partial<Record<MenuSemanticDOM, string>>
182
+ | ((info: { props: MenuProps }) => Partial<Record<MenuSemanticDOM, string>>)
183
+ ```
184
+
185
+ ### MenuStyles
186
+
187
+ ```typescript
188
+ type MenuStyles = | Partial<Record<MenuSemanticDOM, React.CSSProperties>>
189
+ | ((info: { props: MenuProps }) => Partial<Record<MenuSemanticDOM, React.CSSProperties>>)
190
+ ```
191
+
192
+ ### MenuSplitProps
193
+
194
+ 与 MenuProps 相同;Collapsed / Maximized 子实现的 props 别名。
195
+
196
+ **类型别名**:`MenuSplitProps` 即 `MenuProps`,字段见上文 `### Menu`。
197
+
198
+ 等价写法:`MenuSplitProps` ≡ `MenuProps`
199
+
200
+ ### DropdownMenuProps
201
+
202
+ Dropdown `menu` prop 用扁平列表
203
+
204
+ | 属性 | 说明 | 类型 | 必填 | 默认值 |
205
+ | --- | --- | --- | --- | --- |
206
+ | items | — | `MenuItemType[]` | 否 | — |
207
+ | selectable | 是否可选中 | `boolean` | 否 | `false` |
208
+ | selectedKeys | — | `string[]` | 否 | — |
209
+ | defaultSelectedKeys | — | `string[]` | 否 | — |
210
+
211
+ ### 导出类型
212
+
213
+ 另可从 `@apexhub/apex-ui-react` 导入:`DropdownMenuProps`、`MenuChildRenderInfo`、`MenuClickInfo`、`MenuItemKind`、`MenuItemType`、`MenuProps`、`MenuRenderChild`、`MenuSelectInfo`、`MenuSemanticDOM`、`MenuSplitProps`(与上文子类型配合使用)。
214
+
215
+ ## 代码演示
216
+
217
+ ### 子菜单面板
218
+
219
+ 侧栏 icon rail 与 Menu 面板组合:点击 rail 图标选中并展开子菜单面板,适合多应用切换场景。
220
+
221
+ ```tsx
222
+ import { Button, isKeySelected, Menu } from '@apexhub/apex-ui-react'
223
+
224
+ import { useState } from 'react'
225
+
226
+ import type { MenuItemType } from '@apexhub/apex-ui-react'
227
+
228
+ const menuItems: MenuItemType[] = [
229
+ { key: 'install', label: 'Install', icon: 'A' },
230
+ {
231
+ key: 'install-group',
232
+ label: 'Install',
233
+ icon: 'A',
234
+ children: [
235
+ {
236
+ key: 'install-a',
237
+ label: 'Install A',
238
+ icon: 'A',
239
+ children: [
240
+ {
241
+ key: 'install-a-deep',
242
+ label: 'Install Deep',
243
+ icon: 'A',
244
+ children: [
245
+ { key: 'install-a-leaf-a', label: 'Leaf A', icon: 'A' },
246
+ { key: 'install-a-leaf-b', label: 'Leaf B', icon: 'A' },
247
+ ],
248
+ },
249
+ { key: 'install-b', label: 'Install B', icon: 'A' },
250
+ ],
251
+ },
252
+ { key: 'install-b123', label: 'Install C', icon: 'A' },
253
+ ],
254
+ },
255
+ {
256
+ key: 'install-3',
257
+ label: 'Settings',
258
+ icon: 'A',
259
+ children: [
260
+ { key: 'install-c', label: 'General', icon: 'A' },
261
+ { key: 'install-c-2', label: 'Security', icon: 'A' },
262
+ ],
263
+ },
264
+ { key: 'install-4', label: 'Reports', icon: 'A' },
265
+ { key: 'install-5', label: 'Users', icon: 'A' },
266
+ { key: 'loading', loading: true, label: 'loading', icon: 'A' },
267
+ { disabled: true, key: 'disabled', label: 'disabled', icon: 'A' },
268
+ ]
269
+
270
+ const railStyle = {
271
+ display: 'flex',
272
+ flexDirection: 'column' as const,
273
+ width: 'fit-content',
274
+ height: '100%',
275
+ backgroundColor: 'var(--apex-fill-neutral-secondary)',
276
+ borderRight: 'var(--apex-border-1) solid var(--apex-stroke-neutral-tertiary)',
277
+ padding: 8,
278
+ boxSizing: 'border-box' as const,
279
+ justifyContent: 'space-between' as const,
280
+ }
281
+
282
+ export default () => {
283
+ const [selectedKeys, setSelectedKeys] = useState<string[]>([])
284
+ const [collapsed, setCollapsed] = useState(true)
285
+
286
+ return (
287
+ <div style={{ display: 'flex', height: 480, alignItems: 'stretch' }}>
288
+ <div style={railStyle}>
289
+ <div style={{ display: 'flex', flexDirection: 'column', gap: 4 }}>
290
+ {menuItems.map((item) => (
291
+ <Button
292
+ key={item.key}
293
+ type={isKeySelected(item, selectedKeys) ? 'primary' : 'text'}
294
+ size="medium"
295
+ style={{ width: 32, height: 32, padding: 0, minWidth: 0 }}
296
+ onClick={() => {
297
+ setSelectedKeys([item.key])
298
+ if (collapsed) setCollapsed(false)
299
+ }}
300
+ >
301
+ {item.icon ?? item.label?.toString().slice(0, 1)}
302
+ </Button>
303
+ ))}
304
+ </div>
305
+ {collapsed ? (
306
+ <Button
307
+ type="text"
308
+ style={{ width: 32, height: 32, padding: 0, minWidth: 0 }}
309
+ onClick={() => setCollapsed(false)}
310
+ >
311
+ {'>'}
312
+ </Button>
313
+ ) : null}
314
+ </div>
315
+ {!collapsed ? (
316
+ <Menu
317
+ items={menuItems}
318
+ collapsed={false}
319
+ selectedKeys={selectedKeys}
320
+ onSelect={({ selectedKeys: keys }) => setSelectedKeys(keys)}
321
+ footer={
322
+ <Button style={{ marginLeft: 'auto' }} onClick={() => setCollapsed(true)}>
323
+ {'<'}
324
+ </Button>
325
+ }
326
+ />
327
+ ) : null}
328
+ </div>
329
+ )
330
+ }
331
+ ```
332
+
333
+ ### 受控选中与展开
334
+
335
+ 通过 `selectedKeys`、`openKeys` 与对应回调受控管理选中项与子菜单展开状态。选中项通过键盘重新聚焦时保持选中视觉,不会叠加浏览器原生蓝色外框。
336
+
337
+ ```tsx
338
+ import { Button, Menu } from '@apexhub/apex-ui-react'
339
+
340
+ import { useState } from 'react'
341
+
342
+ import type { MenuItemType } from '@apexhub/apex-ui-react'
343
+
344
+ const menuItems: MenuItemType[] = [
345
+ { key: 'install', label: 'Install', icon: 'A' },
346
+ {
347
+ key: 'install-group',
348
+ label: 'Install',
349
+ icon: 'A',
350
+ children: [
351
+ {
352
+ key: 'install-a',
353
+ label: 'Install A',
354
+ icon: 'A',
355
+ children: [
356
+ {
357
+ key: 'install-a-deep',
358
+ label: 'Install Deep',
359
+ icon: 'A',
360
+ children: [
361
+ { key: 'install-a-leaf-a', label: 'Leaf A', icon: 'A' },
362
+ { key: 'install-a-leaf-b', label: 'Leaf B', icon: 'A' },
363
+ ],
364
+ },
365
+ { key: 'install-b', label: 'Install B', icon: 'A' },
366
+ ],
367
+ },
368
+ { key: 'install-b123', label: 'Install C', icon: 'A' },
369
+ ],
370
+ },
371
+ {
372
+ key: 'install-3',
373
+ label: 'Settings',
374
+ icon: 'A',
375
+ children: [
376
+ { key: 'install-c', label: 'General', icon: 'A' },
377
+ { key: 'install-c-2', label: 'Security', icon: 'A' },
378
+ ],
379
+ },
380
+ { key: 'install-4', label: 'Reports', icon: 'A' },
381
+ { key: 'install-5', label: 'Users', icon: 'A' },
382
+ { key: 'loading', loading: true, label: 'loading', icon: 'A' },
383
+ { disabled: true, key: 'disabled', label: 'disabled', icon: 'A' },
384
+ ]
385
+
386
+ type FlatItem = { key: string; label: string }
387
+
388
+ type PathItem = FlatItem & { ancestorKeys: string[] }
389
+
390
+ type OpenableItem = FlatItem & { keyPath: string[] }
391
+
392
+ function collectSelectableLeaves(
393
+ items: MenuItemType[],
394
+ parentPath: string[] = [],
395
+ ): PathItem[] {
396
+ return items.flatMap((item) => {
397
+ if (item.type === 'divider' || item.type === 'group') return []
398
+ if (item.children?.length) {
399
+ return collectSelectableLeaves(item.children, [...parentPath, item.key])
400
+ }
401
+ if (item.disabled) return []
402
+ return [
403
+ {
404
+ key: item.key,
405
+ label: typeof item.label === 'string' ? item.label : item.key,
406
+ ancestorKeys: parentPath,
407
+ },
408
+ ]
409
+ })
410
+ }
411
+
412
+ function collectOpenableParents(
413
+ items: MenuItemType[],
414
+ parentPath: string[] = [],
415
+ ): OpenableItem[] {
416
+ return items.flatMap((item) => {
417
+ if (!item.children?.length) return []
418
+ const keyPath = [...parentPath, item.key]
419
+ const self: OpenableItem = {
420
+ key: item.key,
421
+ label: typeof item.label === 'string' ? item.label : item.key,
422
+ keyPath,
423
+ }
424
+ return [self, ...collectOpenableParents(item.children, keyPath)]
425
+ })
426
+ }
427
+
428
+ export default () => {
429
+ const [selectedKeys, setSelectedKeys] = useState<string[]>([])
430
+ const [openKeys, setOpenKeys] = useState<string[]>([])
431
+
432
+ const selectableLeaves = collectSelectableLeaves(menuItems)
433
+ const openableParents = collectOpenableParents(menuItems)
434
+
435
+ return (
436
+ <div style={{ display: 'flex', alignItems: 'flex-start', gap: 16, minHeight: 480 }}>
437
+ <Menu
438
+ items={menuItems}
439
+ collapsed={false}
440
+ selectedKeys={selectedKeys}
441
+ onSelect={({ selectedKeys: keys }) => setSelectedKeys(keys)}
442
+ openKeys={openKeys}
443
+ onOpenChange={setOpenKeys}
444
+ />
445
+ <div
446
+ style={{
447
+ display: 'flex',
448
+ flexDirection: 'row',
449
+ gap: 8,
450
+ marginTop: 16,
451
+ maxHeight: 480,
452
+ overflow: 'auto',
453
+ }}
454
+ >
455
+ <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
456
+ {selectableLeaves.map((item) => (
457
+ <Button
458
+ key={item.key}
459
+ onClick={() => {
460
+ setSelectedKeys([item.key])
461
+ setOpenKeys((prev) => [...new Set([...prev, ...item.ancestorKeys])])
462
+ }}
463
+ >
464
+ Select {item.label}
465
+ </Button>
466
+ ))}
467
+ <Button onClick={() => setSelectedKeys([])}>Clear selection</Button>
468
+ </div>
469
+ <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
470
+ {openableParents.map((item) => (
471
+ <Button key={item.key} onClick={() => setOpenKeys(item.keyPath)}>
472
+ Open {item.label}
473
+ </Button>
474
+ ))}
475
+ <Button onClick={() => setOpenKeys([])}>Collapse all</Button>
476
+ </div>
477
+ </div>
478
+ </div>
479
+ )
480
+ }
481
+ ```
482
+
483
+ ### 自定义顶栏
484
+
485
+ 通过 `header` 与 `footer` 插槽自定义收窄与展开态的顶栏、底栏内容;展开态的顶栏沿用菜单 Token 表面样式。
486
+
487
+ ```tsx
488
+ import { Avatar, Button, Card, Dropdown, Menu, Typography } from '@apexhub/apex-ui-react'
489
+
490
+ import { useState } from 'react'
491
+
492
+ import type { MenuItemType } from '@apexhub/apex-ui-react'
493
+
494
+ const menuItems: MenuItemType[] = [
495
+ { key: 'install', label: 'Install', icon: 'A' },
496
+ {
497
+ key: 'install-group',
498
+ label: 'Install',
499
+ icon: 'A',
500
+ children: [
501
+ {
502
+ key: 'install-a',
503
+ label: 'Install A',
504
+ icon: 'A',
505
+ children: [
506
+ {
507
+ key: 'install-a-deep',
508
+ label: 'Install Deep',
509
+ icon: 'A',
510
+ children: [
511
+ { key: 'install-a-leaf-a', label: 'Leaf A', icon: 'A' },
512
+ { key: 'install-a-leaf-b', label: 'Leaf B', icon: 'A' },
513
+ ],
514
+ },
515
+ { key: 'install-b', label: 'Install B', icon: 'A' },
516
+ ],
517
+ },
518
+ { key: 'install-b123', label: 'Install C', icon: 'A' },
519
+ ],
520
+ },
521
+ {
522
+ key: 'install-3',
523
+ label: 'Settings',
524
+ icon: 'A',
525
+ children: [
526
+ { key: 'install-c', label: 'General', icon: 'A' },
527
+ { key: 'install-c-2', label: 'Security', icon: 'A' },
528
+ ],
529
+ },
530
+ { key: 'install-4', label: 'Reports', icon: 'A' },
531
+ { key: 'install-5', label: 'Users', icon: 'A' },
532
+ { key: 'loading', loading: true, label: 'loading', icon: 'A' },
533
+ { disabled: true, key: 'disabled', label: 'disabled', icon: 'A' },
534
+ ]
535
+
536
+ export default () => {
537
+ const [collapsed, setCollapsed] = useState(true)
538
+ const [profileHovered, setProfileHovered] = useState(false)
539
+
540
+ return (
541
+ <div style={{ display: 'flex', alignItems: 'flex-start', gap: 16, height: '380px' }}>
542
+ <Menu
543
+ items={menuItems}
544
+ onCollapse={setCollapsed}
545
+ collapsed={collapsed}
546
+ header={
547
+ collapsed ? (
548
+ <div
549
+ style={{
550
+ fontSize: 12,
551
+ opacity: 0.7,
552
+ display: 'flex',
553
+ justifyContent: 'center',
554
+ width: '100%',
555
+ }}
556
+ >
557
+ <Card
558
+ style={{
559
+ marginBottom: -3,
560
+ width: 'fit-content',
561
+ paddingTop: 10,
562
+ paddingBottom: 0,
563
+ border: 'none',
564
+ display: 'flex',
565
+ alignItems: 'center',
566
+ justifyContent: 'center',
567
+ }}
568
+ >
569
+ <Avatar />
570
+ </Card>
571
+ </div>
572
+ ) : (
573
+ <div
574
+ style={{
575
+ fontSize: 12,
576
+ opacity: 0.7,
577
+ display: 'flex',
578
+ justifyContent: 'start',
579
+ width: '100%',
580
+ }}
581
+ >
582
+ <Dropdown
583
+ placement="bottom"
584
+ menu={{
585
+ items: [
586
+ { key: 'logout', label: 'Logout' },
587
+ { key: 'settings', label: 'Settings' },
588
+ { key: 'report', label: 'Annual Report' },
589
+ ],
590
+ }}
591
+ trigger={['click']}
592
+ >
593
+ <div
594
+ style={{
595
+ overflow: 'hidden',
596
+ width: '100%',
597
+ padding: 0,
598
+ paddingTop: 10,
599
+ border: 'none',
600
+ height: '100%',
601
+ cursor: 'pointer',
602
+ backgroundColor: profileHovered
603
+ ? 'var(--apex-fill-neutral-tertiary)'
604
+ : undefined,
605
+ transition: 'background-color 0.15s ease',
606
+ }}
607
+ onMouseEnter={() => setProfileHovered(true)}
608
+ onMouseLeave={() => setProfileHovered(false)}
609
+ >
610
+ <Avatar />{' '}
611
+ <Typography.Text variant="caption" ellipsis>
612
+ Dan Brown
613
+ </Typography.Text>
614
+ </div>
615
+ </Dropdown>
616
+ </div>
617
+ )
618
+ }
619
+ footer={
620
+ !collapsed ? <Typography.Text variant="caption">4GB used</Typography.Text> : undefined
621
+ }
622
+ />
623
+ <Button style={{ marginTop: 15 }} onClick={() => setCollapsed(!collapsed)}>
624
+ {collapsed ? 'Expand' : 'Collapse'}
625
+ </Button>
626
+ </div>
627
+ )
628
+ }
629
+ ```
630
+
631
+ ### 自定义子项渲染
632
+
633
+ 通过 `renderChild` 自定义 menu-maximized **子级**列表项整行渲染(`depth > 0`);顶层项保持默认样式。请将 `domProps` 绑定到自定义根节点以保留选中、展开与点击行为。
634
+
635
+ ```tsx
636
+ import { Button, Menu, type MenuItemType } from '@apexhub/apex-ui-react'
637
+
638
+ const items: MenuItemType[] = [
639
+ {
640
+ key: 'workspace',
641
+ label: '工作台',
642
+ children: [
643
+ { key: 'projects', label: '项目' },
644
+ { key: 'members', label: '成员' },
645
+ ],
646
+ },
647
+ ]
648
+
649
+ export default function Example() {
650
+ return (
651
+ <Menu
652
+ items={items}
653
+ collapsed={false}
654
+ defaultOpenKeys={['workspace']}
655
+ renderChild={({ item, domProps }) => {
656
+ const { type: _type, ...buttonProps } = domProps
657
+ return (
658
+ <Button type="text" {...buttonProps}>
659
+ <span>{item.label}</span>
660
+ </Button>
661
+ )
662
+ }}
663
+ />
664
+ )
665
+ }
666
+ ```
667
+
668
+ ## DOM 结构
669
+
670
+ 源码声明的静态 `data-slot`:`menu-rail-item`、`menu-item`、`menu-sublist`、`menu`、`menu-body`、`menu-header`、`menu-rail`、`menu-list`、`menu-footer`。具体节点随模式和状态出现,不表示固定嵌套顺序。
671
+
672
+ ## 样式定制
673
+
674
+ 优先使用本组件公开的尺寸、类型和状态属性。换肤与变量覆盖方式见 [主题指南](../llms-theme.txt)。
675
+
676
+ 需要定制具体样式时再读取 [Token 明细](./menu.tokens.txt),其中包含用途、定义值及适用作用域。常规组件使用无需加载该文件。
677
+
678
+ ## FAQ
679
+
680
+ ### Menu 和 Dropdown 的菜单数据一样吗?
681
+
682
+ Dropdown 复用 `MenuItemType` 类型定义,但 UI 与交互独立:Menu 面向侧栏双形态导航,Dropdown 面向触发器旁的临时弹出菜单。
683
+
684
+
685
+ ### 为什么受控 `collapsed` 时点击 rail 没展开?
686
+
687
+ 受控用法需同时提供 `onCollapse`,在回调中更新 `collapsed` 状态,否则展开请求无法生效。