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

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