@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,233 @@
1
+ # Popover
2
+
3
+ > Popover:需要在触发元素旁展示标题 + 正文,且正文内可包含链接、按钮等可交互元素时。
4
+
5
+ 包:`@apexhub/apex-ui-react`;版本:`1.2.0`(当前源码快照,发布状态以安装包版本为准)。
6
+
7
+ 公开导出:`Popover`。
8
+
9
+ 以下 API 属于 Apex UI;不要据 antd 的同名组件推断额外属性或默认值。默认值列的空缺表示未声明,不代表 `false`。
10
+
11
+ ## 快速开始
12
+
13
+ ```tsx
14
+ import { Button, Popover } from '@apexhub/apex-ui-react'
15
+
16
+ import '@apexhub/apex-ui-react/style.css'
17
+
18
+ export default () => (
19
+ <div style={{ padding: 48 }}>
20
+ <Popover title="Popover 标题" content="鼠标悬停查看 Popover">
21
+ <Button type="primary">悬停我</Button>
22
+ </Popover>
23
+ </div>
24
+ )
25
+ ```
26
+
27
+ ## 何时使用
28
+
29
+ - 需要在触发元素旁展示标题 + 正文,且正文内可包含链接、按钮等可交互元素时。
30
+ - 点击或悬停展开补充说明、快捷操作面板时。
31
+ - 树选择器、多列表单等宽面板会按内容自然展开,并在接近可用边界时自动收缩。
32
+ - 若只需单行文字提示、无交互内容,请使用 Tooltip,而不是 Popover。
33
+
34
+ ## API
35
+
36
+ 仅使用类型定义支持的属性;原生属性、ref 目标和事件签名因组件而异。关联类型用于解释字段结构;只有「导出类型」中的名称可从包根导入。
37
+
38
+ ### Popover
39
+
40
+ | 属性 | 说明 | 类型 | 必填 | 默认值 |
41
+ | --- | --- | --- | --- | --- |
42
+ | title | 浮层标题。 | `React.ReactNode \| (() => React.ReactNode)` | 否 | `undefined` |
43
+ | content | 浮层内容,可承载链接、按钮等可交互元素。 | `React.ReactNode \| (() => React.ReactNode)` | 否 | `undefined` |
44
+ | children | 触发 Popover 的子元素,要求是单个可接收事件的 React element。 | `React.ReactNode` | 是 | `undefined` |
45
+ | anchorElement | 自定义浮层定位锚点。仅改变定位与箭头指向,打开事件仍由 `children` 触发。 | `HTMLElement \| null` | 否 | `children 对应的 DOM 元素` |
46
+ | sideOffset | 浮层与定位锚点之间的距离;负值可让浮层覆盖锚点。 | `number` | 否 | `8` |
47
+ | trigger | 打开触发方式。<br>- `hover`:鼠标移入打开,移出关闭<br>- `focus`:聚焦打开,失焦关闭<br>- `click`:点击切换显隐 | `"hover" \| "focus" \| "click"` | 否 | `'hover'` |
48
+ | placement | 浮层方位。<br>- `top` / `bottom` / `left` / `right`:居中对齐<br>- `topLeft` / `topRight` / `bottomLeft` / `bottomRight`:上下方位的左右对齐<br>- `leftTop` / `leftBottom` / `rightTop` / `rightBottom`:左右方位的上下对齐 | `"top" \| "left" \| "right" \| "bottom" \| "topLeft" \| "topRight" \| "bottomLeft" \| "bottomRight" \| "leftTop" \| "leftBottom" \| "rightTop" \| "rightBottom"` | 否 | `'top'` |
49
+ | open | 受控显隐;传入后需配合 `onOpenChange` 更新。 | `boolean` | 否 | `undefined` |
50
+ | defaultOpen | 非受控初始显隐。 | `boolean` | 否 | `false` |
51
+ | onOpenChange | 显隐变化回调。 | `(open: boolean) => void` | 否 | `undefined` |
52
+ | arrow | 是否展示箭头。 | `boolean` | 否 | `true` |
53
+ | className | 浮层内容根节点类名,作用于 `data-slot="popover-content"`。 | `string` | 否 | `undefined` |
54
+ | style | 浮层内容根节点样式;禁止硬编码色值,优先使用 CSS Token。 | `React.CSSProperties` | 否 | `undefined` |
55
+ | styles | 为各语义子结构自定义内联样式(仅允许 CSS Token 等变量赋值,禁止业务硬编码色值) | `Partial<Record<PopoverSemanticDOM, React.CSSProperties>> \| ((info: { props: Readonly<PopoverProps> }) => Partial<Record<PopoverSemanticDOM, React.CSSProperties>>)` | 否 | — |
56
+ | ref | 转发到浮层内容根节点。 | `React.Ref<HTMLDivElement>` | 否 | `undefined` |
57
+
58
+ ### PopoverPlacement
59
+
60
+ ```typescript
61
+ type PopoverPlacement = | 'top'
62
+ | 'left'
63
+ | 'right'
64
+ | 'bottom'
65
+ | 'topLeft'
66
+ | 'topRight'
67
+ | 'bottomLeft'
68
+ | 'bottomRight'
69
+ | 'leftTop'
70
+ | 'leftBottom'
71
+ | 'rightTop'
72
+ | 'rightBottom'
73
+ ```
74
+
75
+ ### PopoverTrigger
76
+
77
+ ```typescript
78
+ type PopoverTrigger = 'hover' | 'focus' | 'click'
79
+ ```
80
+
81
+ ### PopoverSemanticDOM
82
+
83
+ 子结构语义,用于 `styles` 分段定制
84
+
85
+ ```typescript
86
+ type PopoverSemanticDOM = 'popup'
87
+ ```
88
+
89
+ ### 导出类型
90
+
91
+ 另可从 `@apexhub/apex-ui-react` 导入:`PopoverPlacement`、`PopoverProps`、`PopoverTrigger`(与上文子类型配合使用)。
92
+
93
+ ## 代码演示
94
+
95
+ ### 十二方位
96
+
97
+ 通过 `placement` 指定浮层相对触发器的方位,支持 12 种对齐方式。
98
+
99
+ ```tsx
100
+ import type { PopoverPlacement } from '@apexhub/apex-ui-react'
101
+
102
+ import { Button, Popover } from '@apexhub/apex-ui-react'
103
+
104
+ const placements: PopoverPlacement[] = [
105
+ 'top',
106
+ 'topLeft',
107
+ 'topRight',
108
+ 'bottom',
109
+ 'bottomLeft',
110
+ 'bottomRight',
111
+ 'left',
112
+ 'leftTop',
113
+ 'leftBottom',
114
+ 'right',
115
+ 'rightTop',
116
+ 'rightBottom',
117
+ ]
118
+
119
+ const btnStyle = { width: 80, margin: 4 } as const
120
+
121
+ export default () => (
122
+ <div style={{ padding: 48, display: 'flex', flexWrap: 'wrap', justifyContent: 'center' }}>
123
+ {placements.map((placement) => (
124
+ <Popover key={placement} placement={placement} title="标题" content="内容">
125
+ <Button type="default" style={btnStyle}>
126
+ {placement}
127
+ </Button>
128
+ </Popover>
129
+ ))}
130
+ </div>
131
+ )
132
+ ```
133
+
134
+ ### 触发方式
135
+
136
+ `trigger` 支持 `hover`、`focus`、`click` 三种单值触发方式。
137
+
138
+ ```tsx
139
+ import { Button, Popover } from '@apexhub/apex-ui-react'
140
+
141
+ const rowStyle = { display: 'flex', gap: 8, flexWrap: 'wrap' as const, padding: 48 }
142
+
143
+ export default () => (
144
+ <div style={rowStyle}>
145
+ <Popover trigger="hover" title="hover" content="鼠标悬停">
146
+ <Button type="default">hover</Button>
147
+ </Popover>
148
+ <Popover trigger="focus" title="focus" content="聚焦触发">
149
+ <Button type="default">focus</Button>
150
+ </Popover>
151
+ <Popover trigger="click" title="click" content="点击切换">
152
+ <Button type="default">click</Button>
153
+ </Popover>
154
+ </div>
155
+ )
156
+ ```
157
+
158
+ ### 受控模式
159
+
160
+ 通过 `open` 与 展开变化事件 受控管理浮层显隐。
161
+
162
+ ```tsx
163
+ import { Button, Popover } from '@apexhub/apex-ui-react'
164
+
165
+ import { useState } from 'react'
166
+
167
+ export default () => {
168
+ const [open, setOpen] = useState(false)
169
+
170
+ return (
171
+ <div style={{ padding: 48, display: 'flex', gap: 8, alignItems: 'center' }}>
172
+ <Popover
173
+ open={open}
174
+ onOpenChange={setOpen}
175
+ trigger="click"
176
+ title="受控 Popover"
177
+ content="通过外部按钮也可开关"
178
+ >
179
+ <Button type="primary">触发器</Button>
180
+ </Popover>
181
+ <Button type="default" onClick={() => setOpen((v) => !v)}>
182
+ 外部切换
183
+ </Button>
184
+ </div>
185
+ )
186
+ }
187
+ ```
188
+
189
+ ### 箭头
190
+
191
+ `arrow` 控制是否展示指向触发器的箭头,默认 `true`。
192
+
193
+ ```tsx
194
+ import { Button, Popover } from '@apexhub/apex-ui-react'
195
+
196
+ const rowStyle = { display: 'flex', gap: 8, padding: 48 }
197
+
198
+ export default () => (
199
+ <div style={rowStyle}>
200
+ <Popover arrow title="带箭头" content="默认展示箭头">
201
+ <Button type="default">有箭头</Button>
202
+ </Popover>
203
+ <Popover arrow={false} title="无箭头" content="arrow=false">
204
+ <Button type="default">无箭头</Button>
205
+ </Popover>
206
+ </div>
207
+ )
208
+ ```
209
+
210
+ ## DOM 结构
211
+
212
+ 源码声明的静态 `data-slot`:`popover-root`、`popover-trigger`、`popover-content`、`popover-title`、`popover-body`、`popover-arrow`。具体节点随模式和状态出现,不表示固定嵌套顺序。
213
+
214
+ ## 样式定制
215
+
216
+ 优先使用本组件公开的尺寸、类型和状态属性。换肤与变量覆盖方式见 [主题指南](../llms-theme.txt)。
217
+
218
+ 需要定制具体样式时再读取 [Token 明细](./popover.tokens.txt),其中包含用途、定义值及适用作用域。常规组件使用无需加载该文件。
219
+
220
+ ## FAQ
221
+
222
+ ### 为什么不支持 `trigger={['hover', 'click']}` 数组?
223
+
224
+ v1 仅支持单值触发方式,避免组合触发带来的状态复杂度;需要多种触发时请选用最接近的一种,或改用受控模式自行管理 `open`。
225
+
226
+
227
+ ### `title` 和 `content` 都为空时会怎样?
228
+
229
+ 浮层不会打开;请至少提供其一。
230
+
231
+ ### Popover 内容有固定最大宽度吗?
232
+
233
+ 没有。Popover 默认最小宽度由组件 Token 决定,内容会自然展开;运行时仅根据浮层可用空间限制最大宽度,避免超出视口或所在浮层边界。业务需要固定面板宽度时,可通过 `style`、`styles.popup` 或 `className` 设置。
@@ -0,0 +1,83 @@
1
+ # Progress Token 明细
2
+
3
+ 包:`@apexhub/apex-ui-react`;版本:`1.2.0`(当前源码快照)。
4
+
5
+ 按需读取:[组件用法](./progress.txt) · [主题与覆盖规则](../llms-theme.txt)。
6
+
7
+ 以下组件变量在设计 Token 源中已定义,并被组件或其共享样式使用;不包含仅在实现中声明的临时变量。用途来自实际 CSS 属性,不是对外新增的 Props。
8
+
9
+ 定义值依赖所列尺寸、变体、状态和媒体作用域;Alias 引用还会随 light/dark 主题改变。它们不是统一默认值或最终计算值。作用域用于解释定义位置,不代表内部选择器是稳定的定制 API。
10
+
11
+ | Token | 用途(CSS 属性) | 定义值 | 定义作用域 |
12
+ | --- | --- | --- | --- |
13
+ | `--font-fontheight` | `line-height` | `var(--apex-fontheight-20)` | `.apex-font.apex-text-cn-body-font` |
14
+ | `--font-fontheight` | `line-height` | `var(--apex-fontheight-18)` | `.apex-font.apex-text-cn-caption-font` |
15
+ | `--font-fontheight` | `line-height` | `var(--apex-fontheight-36)` | `.apex-font.apex-text-cn-heading-1-font` |
16
+ | `--font-fontheight` | `line-height` | `var(--apex-fontheight-28)` | `.apex-font.apex-text-cn-heading-2-font` |
17
+ | `--font-fontheight` | `line-height` | `var(--apex-fontheight-24)` | `.apex-font.apex-text-cn-heading-3-font` |
18
+ | `--font-fontheight` | `line-height` | `var(--apex-fontheight-24)` | `.apex-font.apex-text-cn-heading-4-font` |
19
+ | `--font-fontheight` | `line-height` | `var(--apex-fontheight-20)` | `.apex-font.apex-text-en-body-font` |
20
+ | `--font-fontheight` | `line-height` | `var(--apex-fontheight-18)` | `.apex-font.apex-text-en-caption-font` |
21
+ | `--font-fontheight` | `line-height` | `var(--apex-fontheight-36)` | `.apex-font.apex-text-en-heading-1-font` |
22
+ | `--font-fontheight` | `line-height` | `var(--apex-fontheight-28)` | `.apex-font.apex-text-en-heading-2-font` |
23
+ | `--font-fontheight` | `line-height` | `var(--apex-fontheight-24)` | `.apex-font.apex-text-en-heading-3-font` |
24
+ | `--font-fontheight` | `line-height` | `var(--apex-fontheight-24)` | `.apex-font.apex-text-en-heading-4-font` |
25
+ | `--font-fontsize` | `font-size` | `var(--apex-fontsize-14)` | `.apex-font.apex-text-cn-body-font` |
26
+ | `--font-fontsize` | `font-size` | `var(--apex-fontsize-12)` | `.apex-font.apex-text-cn-caption-font` |
27
+ | `--font-fontsize` | `font-size` | `var(--apex-fontsize-24)` | `.apex-font.apex-text-cn-heading-1-font` |
28
+ | `--font-fontsize` | `font-size` | `var(--apex-fontsize-18)` | `.apex-font.apex-text-cn-heading-2-font` |
29
+ | `--font-fontsize` | `font-size` | `var(--apex-fontsize-16)` | `.apex-font.apex-text-cn-heading-3-font` |
30
+ | `--font-fontsize` | `font-size` | `var(--apex-fontsize-16)` | `.apex-font.apex-text-cn-heading-4-font` |
31
+ | `--font-fontsize` | `font-size` | `var(--apex-fontsize-14)` | `.apex-font.apex-text-en-body-font` |
32
+ | `--font-fontsize` | `font-size` | `var(--apex-fontsize-12)` | `.apex-font.apex-text-en-caption-font` |
33
+ | `--font-fontsize` | `font-size` | `var(--apex-fontsize-24)` | `.apex-font.apex-text-en-heading-1-font` |
34
+ | `--font-fontsize` | `font-size` | `var(--apex-fontsize-18)` | `.apex-font.apex-text-en-heading-2-font` |
35
+ | `--font-fontsize` | `font-size` | `var(--apex-fontsize-16)` | `.apex-font.apex-text-en-heading-3-font` |
36
+ | `--font-fontsize` | `font-size` | `var(--apex-fontsize-16)` | `.apex-font.apex-text-en-heading-4-font` |
37
+ | `--font-fontspacing` | `letter-spacing` | `var(--apex-fontspacing-0)` | `.apex-font.apex-text-cn-body-font` |
38
+ | `--font-fontspacing` | `letter-spacing` | `var(--apex-fontspacing-0)` | `.apex-font.apex-text-cn-caption-font` |
39
+ | `--font-fontspacing` | `letter-spacing` | `var(--apex-fontspacing-0)` | `.apex-font.apex-text-cn-heading-1-font` |
40
+ | `--font-fontspacing` | `letter-spacing` | `var(--apex-fontspacing-0)` | `.apex-font.apex-text-cn-heading-2-font` |
41
+ | `--font-fontspacing` | `letter-spacing` | `var(--apex-fontspacing-8)` | `.apex-font.apex-text-cn-heading-3-font` |
42
+ | `--font-fontspacing` | `letter-spacing` | `var(--apex-fontspacing-0)` | `.apex-font.apex-text-cn-heading-4-font` |
43
+ | `--font-fontspacing` | `letter-spacing` | `var(--apex-fontspacing-1)` | `.apex-font.apex-text-en-body-font` |
44
+ | `--font-fontspacing` | `letter-spacing` | `var(--apex-fontspacing-1)` | `.apex-font.apex-text-en-caption-font` |
45
+ | `--font-fontspacing` | `letter-spacing` | `var(--apex-fontspacing-1)` | `.apex-font.apex-text-en-heading-1-font` |
46
+ | `--font-fontspacing` | `letter-spacing` | `var(--apex-fontspacing-1)` | `.apex-font.apex-text-en-heading-2-font` |
47
+ | `--font-fontspacing` | `letter-spacing` | `var(--apex-fontspacing-1)` | `.apex-font.apex-text-en-heading-3-font` |
48
+ | `--font-fontspacing` | `letter-spacing` | `var(--apex-fontspacing-1)` | `.apex-font.apex-text-en-heading-4-font` |
49
+ | `--font-fontweight` | `font-weight` | `var(--apex-fontweight-400)` | `.apex-font.apex-text-cn-body-font` |
50
+ | `--font-fontweight` | `font-weight` | `var(--apex-fontweight-400)` | `.apex-font.apex-text-cn-caption-font` |
51
+ | `--font-fontweight` | `font-weight` | `var(--apex-fontweight-600)` | `.apex-font.apex-text-cn-heading-1-font` |
52
+ | `--font-fontweight` | `font-weight` | `var(--apex-fontweight-600)` | `.apex-font.apex-text-cn-heading-2-font` |
53
+ | `--font-fontweight` | `font-weight` | `var(--apex-fontweight-600)` | `.apex-font.apex-text-cn-heading-3-font` |
54
+ | `--font-fontweight` | `font-weight` | `var(--apex-fontweight-400)` | `.apex-font.apex-text-cn-heading-4-font` |
55
+ | `--font-fontweight` | `font-weight` | `var(--apex-fontweight-400)` | `.apex-font.apex-text-en-body-font` |
56
+ | `--font-fontweight` | `font-weight` | `var(--apex-fontweight-400)` | `.apex-font.apex-text-en-caption-font` |
57
+ | `--font-fontweight` | `font-weight` | `var(--apex-fontweight-600)` | `.apex-font.apex-text-en-heading-1-font` |
58
+ | `--font-fontweight` | `font-weight` | `var(--apex-fontweight-600)` | `.apex-font.apex-text-en-heading-2-font` |
59
+ | `--font-fontweight` | `font-weight` | `var(--apex-fontweight-600)` | `.apex-font.apex-text-en-heading-3-font` |
60
+ | `--font-fontweight` | `font-weight` | `var(--apex-fontweight-400)` | `.apex-font.apex-text-en-heading-4-font` |
61
+ | `--progress-bar-brand` | `background-image`、`color` | `var(--apex-fill-brand-primary)` | `.apex-progress.apex-default-progress` |
62
+ | `--progress-bar-error` | `background-image`、`color` | `var(--apex-fill-error-primary)` | `.apex-progress.apex-default-progress` |
63
+ | `--progress-bar-success` | `background-image`、`color` | `var(--apex-fill-success-primary)` | `.apex-progress.apex-default-progress` |
64
+ | `--progress-bar-warning` | `background-image`、`color` | `var(--apex-fill-warning-primary)` | `.apex-progress.apex-default-progress` |
65
+ | `--progress-defalut-spacing-gap` | `background-image` | `var(--apex-spacing-2)` | `.apex-progress.apex-pattern-progress` |
66
+ | `--progress-defalut-spacing-width` | `background-image` | `var(--apex-size-2)` | `.apex-progress.apex-pattern-progress` |
67
+ | `--progress-fill-default` | `background-color`、`stroke` | `var(--apex-fill-neutral-quinary)` | `.apex-progress.apex-default-progress` |
68
+ | `--progress-icon-error` | `color` | `var(--apex-icon-error-primary)` | `.apex-progress.apex-default-progress` |
69
+ | `--progress-icon-icon` | `font-size` | `var(--apex-icon-16)` | `.apex-progress.apex-lg-progress` |
70
+ | `--progress-icon-icon` | `font-size` | `var(--apex-icon-16)` | `.apex-progress.apex-md-progress` |
71
+ | `--progress-icon-icon` | `font-size` | `var(--apex-icon-12)` | `.apex-progress.apex-sm-progress` |
72
+ | `--progress-icon-success` | `color` | `var(--apex-icon-success-primary)` | `.apex-progress.apex-default-progress` |
73
+ | `--progress-icon-warning` | `color` | `var(--apex-icon-warning-primary)` | `.apex-progress.apex-default-progress` |
74
+ | `--progress-radius-radius` | `border-radius` | `var(--apex-radius-2)` | `.apex-progress.apex-lg-progress` |
75
+ | `--progress-radius-radius` | `border-radius` | `var(--apex-radius-2)` | `.apex-progress.apex-md-progress` |
76
+ | `--progress-radius-radius` | `border-radius` | `var(--apex-radius-2)` | `.apex-progress.apex-sm-progress` |
77
+ | `--progress-spacing-gap` | `gap` | `var(--apex-spacing-4)` | `.apex-progress.apex-lg-progress` |
78
+ | `--progress-spacing-gap` | `gap` | `var(--apex-spacing-4)` | `.apex-progress.apex-md-progress` |
79
+ | `--progress-spacing-gap` | `gap` | `var(--apex-spacing-4)` | `.apex-progress.apex-sm-progress` |
80
+ | `--progress-spacing-height` | `height` | `var(--apex-size-12)` | `.apex-progress.apex-lg-progress` |
81
+ | `--progress-spacing-height` | `height` | `var(--apex-size-8)` | `.apex-progress.apex-md-progress` |
82
+ | `--progress-spacing-height` | `height` | `var(--apex-size-4)` | `.apex-progress.apex-sm-progress` |
83
+ | `--progress-text-default` | `color` | `var(--apex-text-neutral-primary)` | `.apex-progress.apex-default-progress` |
@@ -0,0 +1,279 @@
1
+ # Progress
2
+
3
+ > Progress:需要向用户展示任务、上传、加载等操作的完成百分比时。
4
+
5
+ 包:`@apexhub/apex-ui-react`;版本:`1.2.0`(当前源码快照,发布状态以安装包版本为准)。
6
+
7
+ 公开导出:`Progress`。
8
+
9
+ 以下 API 属于 Apex UI;不要据 antd 的同名组件推断额外属性或默认值。默认值列的空缺表示未声明,不代表 `false`。
10
+
11
+ ## 快速开始
12
+
13
+ ```tsx
14
+ import { Progress } from '@apexhub/apex-ui-react'
15
+
16
+ import '@apexhub/apex-ui-react/style.css'
17
+
18
+ export default () => (
19
+ <div style={{ width: 400 }}>
20
+ <Progress percent={50} />
21
+ </div>
22
+ )
23
+ ```
24
+
25
+ ## 何时使用
26
+
27
+ - 需要向用户展示任务、上传、加载等操作的完成百分比时。
28
+ - 需要在表格行内、列表项旁展示紧凑进度指示时,可使用 `type="mini"`。
29
+ - 若只需不确定的等待动画、无具体百分比,请使用 Spin,而不是 Progress。
30
+
31
+ ## API
32
+
33
+ 仅使用类型定义支持的属性;原生属性、ref 目标和事件签名因组件而异。关联类型用于解释字段结构;只有「导出类型」中的名称可从包根导入。
34
+
35
+ ### Progress
36
+
37
+ | 属性 | 说明 | 类型 | 必填 | 默认值 |
38
+ | --- | --- | --- | --- | --- |
39
+ | className | 自定义类名,透传到root | `string` | 否 | — |
40
+ | style | 自定义内联样式,透传到root | `React.CSSProperties` | 否 | — |
41
+ | type | 进度条类型 | `"line" \| "mini"` | 否 | `'line'` |
42
+ | size | 进度条尺寸 | `"small" \| "medium" \| "large"` | 否 | `'medium'` |
43
+ | status | 进度状态 | `"normal" \| "success" \| "exception" \| "warning"` | 否 | `'normal'` |
44
+ | showInfo | 是否显示进度数值或状态图标 | `boolean` | 否 | `true` |
45
+ | format | 内容的模板函数 | `(percent?: number, successPercent?: number) => React.ReactNode` | 否 | `(percent) => percent + '%'` |
46
+ | success | 成功进度条相关配置(颜色由 Token 决定) | `ProgressSuccessConfig` | 否 | — |
47
+ | renderPercent | 包装「主进度」段节点(line 的 indicator / mini 的 circle path)。<br>适合给剩余进度单独挂 Tooltip,而不包住整条 Progress。 | `ProgressSegmentRender` | 否 | — |
48
+ | renderSuccess | 包装「成功」段节点(`success.percent` 对应的 indicator / path)。<br>适合只给成功段挂 Tooltip;与 `renderPercent` 可同时使用。 | `ProgressSegmentRender` | 否 | — |
49
+ | percent | 进度百分比 (0-100) | `number` | 否 | `0` |
50
+
51
+ ### ProgressSuccessConfig
52
+
53
+ | 属性 | 说明 | 类型 | 必填 | 默认值 |
54
+ | --- | --- | --- | --- | --- |
55
+ | percent | 已成功部分的进度百分比 (0-100) | `number` | 否 | — |
56
+
57
+ ### ProgressSegmentRender
58
+
59
+ 包装进度条内部某个段落节点(如挂 Tooltip / Popover)。
60
+
61
+ ```typescript
62
+ type ProgressSegmentRender = (node: React.ReactElement) => React.ReactNode
63
+ ```
64
+
65
+ ### 导出类型
66
+
67
+ 另可从 `@apexhub/apex-ui-react` 导入:`ProgressProps`、`ProgressSegmentRender`(与上文子类型配合使用)。
68
+
69
+ ## 代码演示
70
+
71
+ ### 尺寸
72
+
73
+ `size` 提供 `small`、`medium`、`large` 三档,影响轨道高度与信息区图标大小。
74
+
75
+ ```tsx
76
+ import { Progress } from '@apexhub/apex-ui-react'
77
+
78
+ export default () => (
79
+ <div style={{ display: 'flex', flexDirection: 'column', gap: 16, width: 300 }}>
80
+ <Progress percent={30} size="small" />
81
+ <Progress percent={50} size="medium" />
82
+ <Progress percent={70} size="large" />
83
+ </div>
84
+ )
85
+ ```
86
+
87
+ ### 状态
88
+
89
+ `status` 控制进度条与信息区颜色;`percent` 达到 100 时默认呈现成功态。
90
+
91
+ ```tsx
92
+ import { Progress } from '@apexhub/apex-ui-react'
93
+
94
+ export default () => (
95
+ <div style={{ display: 'flex', flexDirection: 'column', gap: 16, width: 300 }}>
96
+ <Progress percent={50} status="normal" />
97
+ <Progress percent={100} status="success" />
98
+ <Progress percent={50} status="exception" />
99
+ <Progress percent={50} status="warning" />
100
+ </div>
101
+ )
102
+ ```
103
+
104
+ ### 迷你进度条
105
+
106
+ `type="mini"` 展示紧凑型进度条,适合空间受限的场景。
107
+
108
+ ```tsx
109
+ import { Progress } from '@apexhub/apex-ui-react'
110
+
111
+ export default () => (
112
+ <div style={{ width: 200 }}>
113
+ <Progress type="mini" percent={65} />
114
+ </div>
115
+ )
116
+ ```
117
+
118
+ ### 分段成功进度
119
+
120
+ 通过 `success.percent` 在轨道内叠加已成功部分;`format` 第二个参数为成功段百分比,可用于自定义文案。
121
+
122
+ 以下示例在悬停整条轨道时,于目标进度(`percent`)末端显示标记线与 Tooltip;信息区文案展示成功段百分比。段颜色通过覆盖 `--progress-fill-brand` / `--progress-fill-success` 对调(仅演示)。
123
+
124
+ ```tsx
125
+ import { Progress, Tooltip } from '@apexhub/apex-ui-react'
126
+
127
+ import React from 'react'
128
+
129
+ const OVERLAY_MS = 160
130
+
131
+ const SuccessSegmentHoverMark = () => {
132
+ const wrapRef = React.useRef<HTMLDivElement>(null)
133
+ const exitTimerRef = React.useRef(0)
134
+ const [mounted, setMounted] = React.useState(false)
135
+ const [visible, setVisible] = React.useState(false)
136
+ const [markBox, setMarkBox] = React.useState<{
137
+ left: number
138
+ top: number
139
+ height: number
140
+ } | null>(null)
141
+ const percent = 60
142
+ const successPercent = 30
143
+ const peek = 10
144
+
145
+ // Demo-only visual swap: success strip ↔ percent strip (stripe pattern preserved).
146
+ const percentStripColor = 'var(--apex-fill-success-primary)'
147
+ const successStripColor = 'var(--apex-fill-brand-primary)'
148
+
149
+ const updateMarkBox = React.useCallback(() => {
150
+ const wrap = wrapRef.current
151
+ const track = wrap?.querySelector<HTMLElement>('[data-slot="progress-track"]')
152
+ if (!wrap || !track) return
153
+
154
+ const wrapRect = wrap.getBoundingClientRect()
155
+ const trackRect = track.getBoundingClientRect()
156
+
157
+ setMarkBox({
158
+ left: trackRect.left - wrapRect.left + trackRect.width * (percent / 100) - 1,
159
+ top: trackRect.top - wrapRect.top - peek,
160
+ height: trackRect.height + peek,
161
+ })
162
+ }, [percent, peek])
163
+
164
+ const showOverlay = React.useCallback(() => {
165
+ window.clearTimeout(exitTimerRef.current)
166
+ setMounted(true)
167
+ requestAnimationFrame(() => setVisible(true))
168
+ }, [])
169
+
170
+ const hideOverlay = React.useCallback(() => {
171
+ setVisible(false)
172
+ window.clearTimeout(exitTimerRef.current)
173
+ exitTimerRef.current = window.setTimeout(() => setMounted(false), OVERLAY_MS)
174
+ }, [])
175
+
176
+ React.useEffect(() => () => window.clearTimeout(exitTimerRef.current), [])
177
+
178
+ React.useEffect(() => {
179
+ const track = wrapRef.current?.querySelector<HTMLElement>('[data-slot="progress-track"]')
180
+ if (!track) return
181
+
182
+ const onEnter = () => {
183
+ updateMarkBox()
184
+ showOverlay()
185
+ }
186
+
187
+ track.addEventListener('mouseenter', onEnter)
188
+ track.addEventListener('mouseleave', hideOverlay)
189
+ return () => {
190
+ track.removeEventListener('mouseenter', onEnter)
191
+ track.removeEventListener('mouseleave', hideOverlay)
192
+ }
193
+ }, [hideOverlay, showOverlay, updateMarkBox])
194
+
195
+ return (
196
+ <div ref={wrapRef} style={{ position: 'relative', paddingTop: peek, width: 300 }}>
197
+ <style>{`
198
+ .progress-demo-tooltip {
199
+ opacity: 0;
200
+ transition: opacity ${OVERLAY_MS}ms ease;
201
+ }
202
+ .progress-demo-tooltip--open {
203
+ opacity: 1;
204
+ }
205
+ `}</style>
206
+ <Tooltip
207
+ title={
208
+ <p
209
+ style={{ padding: 0, margin: 0, lineHeight: 0, fontSize: 12 }}
210
+ >{`目标进度:${percent}%`}</p>
211
+ }
212
+ arrow
213
+ placement="top"
214
+ open={mounted}
215
+ onOpenChange={(next) => {
216
+ if (next) showOverlay()
217
+ else hideOverlay()
218
+ }}
219
+ mouseEnterDelay={0}
220
+ color={`color-mix(in srgb, ${percentStripColor} 20%, transparent)`}
221
+ className={`progress-demo-tooltip${visible ? ' progress-demo-tooltip--open' : ''}`}
222
+ >
223
+ <span
224
+ aria-hidden
225
+ style={{
226
+ position: 'absolute',
227
+ left: markBox?.left ?? 0,
228
+ top: markBox?.top ?? 0,
229
+ width: 1,
230
+ height: markBox?.height ?? 0,
231
+ backgroundColor: percentStripColor,
232
+ opacity: visible ? 1 : 0,
233
+ transform: visible ? 'scaleY(1)' : 'scaleY(0.5)',
234
+ transformOrigin: 'bottom center',
235
+ transition: `opacity ${OVERLAY_MS}ms ease, transform ${OVERLAY_MS}ms ease`,
236
+ pointerEvents: 'none',
237
+ zIndex: 10,
238
+ }}
239
+ />
240
+ </Tooltip>
241
+ <Progress
242
+ size="large"
243
+ percent={percent}
244
+ success={{ percent: successPercent }}
245
+ format={(_percent, success) => `${success ?? 0}%`}
246
+ style={
247
+ {
248
+ '--progress-fill-brand': percentStripColor,
249
+ '--progress-fill-success': successStripColor,
250
+ } as React.CSSProperties
251
+ }
252
+ />
253
+ </div>
254
+ )
255
+ }
256
+
257
+ export default () => <SuccessSegmentHoverMark />
258
+ ```
259
+
260
+ ## DOM 结构
261
+
262
+ 源码声明的静态 `data-slot`:`progress-indicator`、`progress-success-indicator`、`progress`、`progress-container`、`progress-track`、`progress-info`。具体节点随模式和状态出现,不表示固定嵌套顺序。
263
+
264
+ ## 样式定制
265
+
266
+ 优先使用本组件公开的尺寸、类型和状态属性。换肤与变量覆盖方式见 [主题指南](../llms-theme.txt)。
267
+
268
+ 需要定制具体样式时再读取 [Token 明细](./progress.tokens.txt),其中包含用途、定义值及适用作用域。常规组件使用无需加载该文件。
269
+
270
+ ## FAQ
271
+
272
+ ### 为什么不支持 `strokeColor` 自定义颜色?
273
+
274
+ 颜色由 `status` 与 Design Token 统一管理,禁止行内硬编码色值;如需定制请覆盖组件局部 CSS Token。
275
+
276
+
277
+ ### `percent={100}` 为什么没有自动变绿?
278
+
279
+ 未显式设置 `status` 时,实现会将 100% 推导为 `success`;若手动指定了其他 `status`,以传入值为准。
@@ -0,0 +1,21 @@
1
+ # Radio Token 明细
2
+
3
+ 包:`@apexhub/apex-ui-react`;版本:`1.2.0`(当前源码快照)。
4
+
5
+ 按需读取:[组件用法](./radio.txt) · [主题与覆盖规则](../llms-theme.txt)。
6
+
7
+ 以下组件变量在设计 Token 源中已定义,并被组件或其共享样式使用;不包含仅在实现中声明的临时变量。用途来自实际 CSS 属性,不是对外新增的 Props。
8
+
9
+ 定义值依赖所列尺寸、变体、状态和媒体作用域;Alias 引用还会随 light/dark 主题改变。它们不是统一默认值或最终计算值。作用域用于解释定义位置,不代表内部选择器是稳定的定制 API。
10
+
11
+ | Token | 用途(CSS 属性) | 定义值 | 定义作用域 |
12
+ | --- | --- | --- | --- |
13
+ | `--radio-icon-icon` | `background-color`、`height`、`width` | `var(--apex-size-20)` | `.apex-radio.apex-default-radio` |
14
+ | `--radio-spacing-gap` | `gap` | `var(--apex-spacing-4)` | `.apex-radio.apex-default-radio` |
15
+ | `--radio-stoke-stroke` | `border-width` | `var(--apex-border-1)` | `.apex-radio.apex-default-radio` |
16
+ | `--radio-stroke-default` | `border-color` | `var(--apex-stroke-neutral-denary)` | `.apex-radio.apex-default-radio` |
17
+ | `--radio-stroke-disabled` | `border-color` | `var(--apex-stroke-neutral-quinary)` | `.apex-radio.apex-default-radio` |
18
+ | `--radio-stroke-hover` | `border-color` | `var(--apex-stroke-neutral-nonary)` | `.apex-radio.apex-default-radio` |
19
+ | `--radio-stroke-selected` | `background-color`、`border-color` | `var(--apex-stroke-brand-primary)` | `.apex-radio.apex-default-radio` |
20
+ | `--radio-text-default` | `color` | `var(--apex-text-neutral-primary)` | `.apex-radio.apex-default-radio` |
21
+ | `--radio-text-disabled` | `color` | `var(--apex-text-neutral-disabled)` | `.apex-radio.apex-default-radio` |