@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
package/llms-theme.txt ADDED
@@ -0,0 +1,32 @@
1
+ # Apex UI 主题与样式定制
2
+
3
+ 普通组件使用先读 [组件索引](./llms.txt)。只有调整主题、尺寸或状态样式时才需要本指南和组件的 tokens.txt;主文档与 llms-full.txt 不包含 Token 定义明细。
4
+
5
+ ## 主题切换
6
+
7
+ 应用入口全局引入一次 `@apexhub/apex-ui-react/style.css`,使用 `ApexProvider` 的 `theme="light"` 或 `theme="dark"` 切换主题。Provider 的默认值、完整示例和 API 见 [ApexProvider](./src/apex-provider/llm.txt)。不要根据其他组件库推断额外的 theme 配置字段。
8
+
9
+ 组件 Token 通常引用 `--apex-*` 语义变量;切换主题后,同一个引用可以解析为不同颜色。明细中的 `var(...)` 是 CSS 定义表达式,不是浏览器最终计算值。
10
+
11
+ ## 优先使用的定制方式
12
+
13
+ 1. 先使用组件公开的尺寸、类型和状态属性,具体属性名以该组件 API 为准。
14
+ 2. 全局换肤优先覆盖 Alias 语义变量,例如 `--apex-fill-brand-primary`、`--apex-text-brand-primary`。业务覆盖样式在组件库 `style.css` 之后加载。
15
+ 3. 只有需要单个组件的细节调整时,再读取该组件的 tokens.txt。按公开样式属性和 `data-slot` 定位实际节点,不要假设每个组件都有 `classNames` 或相同的 DOM 结构。
16
+
17
+ 亮色 Alias 基线定义在 `:root`,暗色覆盖位于 `[data-theme='dark']`。局部覆盖只对相应 DOM 子树生效;不要仅在业务容器上设置 `data-theme` 来代替 Provider 的主题切换。
18
+
19
+ ## 如何理解 Token 明细
20
+
21
+ - 仅列出设计 Token 源中已定义、且被组件样式使用的组件变量。组件内部计算变量、测量值以及第三方库运行时变量不作为可定制 Token 输出。
22
+ - 用途栏来自实际消费变量的 CSS 属性;经过局部变量转接时追踪到最终属性。这说明它参与哪些样式,不表示在所有模式下都会生效。
23
+ - 定义作用域保留尺寸、变体、状态和媒体条件。相同名称可以有多条定义,不存在脱离作用域的统一默认值。
24
+ - 包含组件 CSS 对已定义 Token 的局部覆盖。实际结果由匹配的选择器、层叠顺序、继承和当前主题共同决定。
25
+ - 作用域用于解释当前版本的定义位置,不是建议复制内部类名,也不保证内部选择器跨版本稳定。明细列出的是定制参考,不是新增的 React Props。
26
+ - 保留 `var(--apex-...)` 等引用,避免将某次计算得到的色值或尺寸固化到业务代码。
27
+
28
+ ## 浮层与验证
29
+
30
+ Modal、Select 等 Portal 浮层可能不在触发器的 DOM 子树内。`ApexProvider` 会同步主题模式,但业务容器上自定义的变量不保证自动复制到浮层。使用该组件公开的浮层样式入口,在实际浮层节点验证覆盖效果。
31
+
32
+ 完成定制后检查 light/dark、不同尺寸及涉及的 hover/disabled 等状态;在浏览器 Computed 面板确认变量的最终值。升级组件库时优先使用已安装版本的文档,重新核对所用变量与覆盖范围。
package/llms.txt ADDED
@@ -0,0 +1,59 @@
1
+ # Apex UI · React
2
+
3
+ > 开源 React 组件库,基于 Radix UI 与设计 Token,支持主题切换与微前端隔离。本文件按 [llms.txt 规范](https://llmstxt.org/) 组织,供 LLM/AI 助手直接消费。
4
+
5
+ 安装:`pnpm add @apexhub/apex-ui-react`。导入:`import { Button } from "@apexhub/apex-ui-react"`,并引入样式 `import "@apexhub/apex-ui-react/style.css"`。
6
+
7
+ 版本:`1.2.2`(当前源码快照)。要求 React `>=19.0.0`、React DOM `>=19.0.0`;DatePicker / RangePicker 使用 Dayjs `^1.11.0`。
8
+
9
+ 先读取本索引定位组件,再按需读取单组件文档;跨组件任务再使用全量文档。以安装版本对应的 API、导出类型和完整示例为准,不要套用 antd 的默认值或推测未导出的 API。
10
+
11
+ ## Components
12
+
13
+ - [Alert](./src/alert/llm.txt): Alert:需要在当前页面内展示操作结果、风险提示或补充说明,且信息应持续可见时。 导出:Alert。
14
+ - [ApexProvider](./src/apex-provider/llm.txt): ApexProvider:在应用或微前端子应用最外层包裹,确保组件库 Token、主题、滚动条样式在整个组件树生效。 导出:ApexProvider, useConfig。
15
+ - [AutoComplete](./src/auto-complete/llm.txt): AutoComplete:为自由文本输入提供历史记录、关键词或搜索建议。没有匹配建议时,输入内容仍会保留。 导出:AutoComplete。
16
+ - [Avatar](./src/avatar/llm.txt): Avatar:需要展示用户、团队或业务实体的缩略标识,且空间有限时。 导出:Avatar, AvatarGroup。
17
+ - [Breadcrumb](./src/breadcrumb/llm.txt): Breadcrumb:页面层级较深,用户需要知道「当前在哪」并快速返回上级时。 导出:Breadcrumb, BreadcrumbLink, BreadcrumbSeparatorIcon, isBreadcrumbSeparatorItem。
18
+ - [Button](./src/button/llm.txt): Button:标记一个或多个操作(提交、确认、跳转等)时。 导出:Button。
19
+ - [Card](./src/card/llm.txt): Card:需要将一组相关信息收纳在带边框的容器内,与页面背景区分时。 导出:Card。
20
+ - [Cascader](./src/cascader/llm.txt): Cascader:选项具有清晰的层级关系(省市区、分类目录等),需要从根到叶逐级选择时。 导出:Cascader。
21
+ - [Checkbox](./src/checkbox/llm.txt): Checkbox:用户可从多个选项中任选零个、一个或多个时(与 Radio 互斥单选相对)。 导出:Checkbox, CheckboxGroup。
22
+ - [Collapse](./src/collapse/llm.txt): Collapse:页面信息量大,需要将次要内容默认折叠、按需展开时。 导出:Collapse。
23
+ - [DatePicker](./src/date-picker/llm.txt): DatePicker:用户需要选择单个日期或日期范围,且精确到日、周、月、季、年等不同粒度时。 导出:DatePicker, RangePicker。
24
+ - [Divider](./src/divider/llm.txt): Divider:需要在区块之间做视觉分隔、区分内容层次时。 导出:Divider。
25
+ - [Drawer](./src/drawer/llm.txt): Drawer:需要从屏幕边缘滑出面板展示详情、表单或临时任务,且保留原页面上下文时。 导出:Drawer。
26
+ - [Dropdown](./src/dropdown/llm.txt): Dropdown:在触发器附近展示一组快捷操作或菜单项时。 导出:Dropdown。
27
+ - [Form](./src/form/llm.txt): Form:需要收集、校验并提交一组结构化字段数据时。 导出:Form, FormItem, useForm。
28
+ - [Grid](./src/grid/llm.txt): Grid:页面区块需要按 24 栅格划分宽度与响应式列数时。 导出:Col, Row, useBreakpoint。
29
+ - [Image](./src/image/llm.txt): Image:需要以缩略图形式展示图片,并支持点击放大预览时。 导出:Image。
30
+ - [Input](./src/input/llm.txt): Input:需要通过键盘录入单行或多行文本内容时。 导出:Input。
31
+ - [InputNumber](./src/input-number/llm.txt): InputNumber:需要录入有上下界的数值,并支持步进增减时。 导出:InputNumber。
32
+ - [Layout](./src/layout/llm.txt): Layout:搭建后台页面的 Header、侧栏、内容区与 Footer 等整体结构时。 导出:Layout, LayoutSiderDrawerBody, LayoutSiderDrawerHeader, LayoutSiderMenuCollapsed, LayoutSiderMenuMaximized。
33
+ - [Menu](./src/menu/llm.txt): Menu:侧栏持久导航,需要在图标 rail 与展开列表之间切换时。 导出:isKeySelected, Menu。
34
+ - [Message](./src/message/llm.txt): Message:操作结果的轻量全局反馈(成功、失败、警告、进行中等)时。 导出:message。
35
+ - [Modal](./src/modal/llm.txt): Modal:需要用户阅读并确认、取消或提交,且应暂时阻断当前页面操作时。 导出:Modal。
36
+ - [Notification](./src/notification/llm.txt): Notification:操作完成后的全局反馈,需要用户注意到但不必立即处理时。 导出:notification。
37
+ - [Pagination](./src/pagination/llm.txt): Pagination:数据量较大、需要分批次浏览列表或表格时。 导出:Pagination。
38
+ - [Popover](./src/popover/llm.txt): Popover:需要在触发元素旁展示标题 + 正文,且正文内可包含链接、按钮等可交互元素时。 导出:Popover。
39
+ - [Progress](./src/progress/llm.txt): Progress:需要向用户展示任务、上传、加载等操作的完成百分比时。 导出:Progress。
40
+ - [Radio](./src/radio/llm.txt): Radio:用户必须从多个互斥选项中选择一个时(如性别、配送方式)。 导出:Radio, RadioGroup, RadioIndicator。
41
+ - [Rate](./src/rate/llm.txt): Rate:需要对服务、内容或商品进行星级评价时。 导出:Rate, StarFilled。
42
+ - [Select](./src/select/llm.txt): Select:选项来自预设列表,需要从其中选择一个或多个值时。 导出:Select。
43
+ - [Skeleton](./src/skeleton/llm.txt): Skeleton:页面、卡片或表格数据仍在加载,需要先稳定布局并降低等待感时。 导出:Skeleton。
44
+ - [Spin](./src/spin/llm.txt): Spin:局部区域正在加载数据,需要覆盖指示器且不阻断整页时。 导出:Spin。
45
+ - [Steps](./src/steps/llm.txt): Steps:分步表单、向导、下单流程等需要展示当前所处阶段时。 导出:Steps。
46
+ - [Switch](./src/switch/llm.txt): Switch:需要立即生效的开关型设置(如启用通知、暗色模式)时。 导出:Switch, SwitchRoot, SwitchThumb。
47
+ - [Table](./src/table/llm.txt): Table:需要以行列形式展示、浏览结构化数据(列表、台账、报表)时。 导出:Table, TableSummary。
48
+ - [Tabs](./src/tabs/llm.txt): Tabs:需要在同一页面区域内切换多组相关内容,且各面板互斥展示时。 导出:Tabs。
49
+ - [Tag](./src/tag/llm.txt): Tag:需要标记状态、分类、属性等短文本信息时(如「进行中」「VIP」)。 导出:Tag。
50
+ - [Tooltip](./src/tooltip/llm.txt): Tooltip:图标按钮、缩写、截断文本等需要补充说明时。 导出:Tooltip。
51
+ - [Tree](./src/tree/llm.txt): Tree:需要展示具有父子层级关系的数据(目录、组织架构、权限树等)时。 导出:Tree。
52
+ - [TreeSelect](./src/tree-select/llm.txt): TreeSelect:表单中需要从层级数据里选取一个或多个节点时(部门、分类、地区等)。 导出:TreeSelect。
53
+ - [Typography](./src/typography/llm.txt): Typography:需要按设计字阶展示标题(`Title`)、正文(`Text`)或段落(`Paragraph`)时。 导出:Typography, TypographyParagraph, TypographyText, TypographyTitle。
54
+ - [Upload](./src/upload/llm.txt): Upload:需要将本地文件上传到服务端,并展示上传进度与结果列表时。 导出:canPreviewFile, configureUploadLimits, formatFileSize, getFileExtension, getFileFormatIconName, getFileKind, getFilePreviewKind, getFilePreviewUrl, getUploadLimits, isDocumentFile, isImageFile, resetUploadLimits, UPLOAD_DEFAULT_MAX_COUNT, UPLOAD_DEFAULT_MAX_FILE_SIZE, UPLOAD_LIST_IGNORE, Upload。
55
+
56
+ ## Optional
57
+
58
+ - [全量组件文档(单文件)](./llms-full.txt)
59
+ - [主题与样式定制](./llms-theme.txt): 仅在换肤或覆盖变量时读取;各组件 Token 明细从对应组件文档进入,不包含在全量组件文档中。
package/package.json CHANGED
@@ -1,6 +1,121 @@
1
1
  {
2
2
  "name": "@apexhub/apex-ui-react",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "1.2.2",
4
+ "description": "Apex UI React components — accessible, composable UI built on Radix UI",
5
+ "license": "MIT",
6
+ "keywords": [
7
+ "react",
8
+ "components",
9
+ "ui",
10
+ "component-library",
11
+ "typescript",
12
+ "radix-ui",
13
+ "apex-ui"
14
+ ],
15
+ "type": "module",
16
+ "main": "./dist/index.cjs",
17
+ "module": "./dist/index.mjs",
18
+ "types": "./dist/index.d.ts",
19
+ "exports": {
20
+ ".": {
21
+ "types": "./dist/index.d.ts",
22
+ "import": "./dist/index.mjs",
23
+ "require": "./dist/index.cjs",
24
+ "default": "./dist/index.mjs"
25
+ },
26
+ "./style.css": "./dist/style.css",
27
+ "./locale/zh_CN": {
28
+ "types": "./dist/locale/zh_CN.d.ts",
29
+ "import": "./dist/locale/zh_CN.mjs",
30
+ "require": "./dist/locale/zh_CN.cjs",
31
+ "default": "./dist/locale/zh_CN.mjs"
32
+ },
33
+ "./locale/en_US": {
34
+ "types": "./dist/locale/en_US.d.ts",
35
+ "import": "./dist/locale/en_US.mjs",
36
+ "require": "./dist/locale/en_US.cjs",
37
+ "default": "./dist/locale/en_US.mjs"
38
+ },
39
+ "./llms.txt": "./dist/llms.txt",
40
+ "./llms-full.txt": "./dist/llms-full.txt",
41
+ "./llms-theme.txt": "./dist/llms-theme.txt",
42
+ "./llm/*": "./dist/llm/*"
43
+ },
44
+ "files": [
45
+ "dist",
46
+ "llms.txt",
47
+ "llms-full.txt",
48
+ "llms-theme.txt",
49
+ "src/**/llm.txt",
50
+ "src/**/tokens.txt"
51
+ ],
52
+ "sideEffects": [
53
+ "**/*.css",
54
+ "dist/style.css"
55
+ ],
56
+ "publishConfig": {
57
+ "access": "public",
58
+ "registry": "https://registry.npmjs.org/"
59
+ },
60
+ "size-limit": [
61
+ {
62
+ "path": "dist/index.mjs",
63
+ "limit": "100 KB",
64
+ "gzip": true
65
+ },
66
+ {
67
+ "path": "dist/style.css",
68
+ "limit": "20 KB",
69
+ "gzip": true
70
+ }
71
+ ],
72
+ "dependencies": {
73
+ "@floating-ui/react-dom": "^2.0.0",
74
+ "@headless-tree/core": "^1.7.0",
75
+ "@headless-tree/react": "^1.7.0",
76
+ "@headlessui/react": "^2.2.0",
77
+ "@tanstack/form-core": "^1.0.0",
78
+ "@tanstack/react-form": "^1.0.0",
79
+ "@tanstack/react-table": "^8.21.3",
80
+ "@tanstack/react-virtual": "^3.13.12",
81
+ "class-variance-authority": "^0.7.1",
82
+ "clsx": "^2.1.1",
83
+ "radix-ui": "^1.4.3"
84
+ },
85
+ "peerDependencies": {
86
+ "dayjs": "^1.11.0",
87
+ "react": ">=19.0.0",
88
+ "react-dom": ">=19.0.0"
89
+ },
90
+ "devDependencies": {
91
+ "@size-limit/preset-small-lib": "^11.0.0",
92
+ "@storybook/react-vite": "^10.4.0",
93
+ "@testing-library/jest-dom": "^6.9.1",
94
+ "@testing-library/react": "^16.3.2",
95
+ "@testing-library/user-event": "^14.6.1",
96
+ "@types/react": "^19.0.7",
97
+ "@types/react-dom": "^19.0.3",
98
+ "@vitejs/plugin-react": "^4.3.4",
99
+ "dayjs": "^1.11.0",
100
+ "jsdom": "^29.1.1",
101
+ "react": "^19.0.0",
102
+ "react-dom": "^19.0.0",
103
+ "size-limit": "^11.0.0",
104
+ "storybook": "^10.4.0",
105
+ "typescript": "^5.7.3",
106
+ "vite": "^6.0.11",
107
+ "vite-plugin-dts": "^4.4.0",
108
+ "vitest": "^3.0.7",
109
+ "@apex-ui/core": "0.1.0",
110
+ "@apex-ui/theme": "0.1.0"
111
+ },
112
+ "scripts": {
113
+ "build": "vite build",
114
+ "dev": "vite build --watch",
115
+ "clean": "rm -rf dist",
116
+ "typecheck": "tsc --noEmit -p tsconfig.typecheck.json && tsc -p tsconfig.source.json",
117
+ "test": "vitest run",
118
+ "test:watch": "vitest",
119
+ "size": "size-limit"
120
+ }
6
121
  }
@@ -0,0 +1,167 @@
1
+ # Alert
2
+
3
+ > Alert:需要在当前页面内展示操作结果、风险提示或补充说明,且信息应持续可见时。
4
+
5
+ 包:`@apexhub/apex-ui-react`;版本:`1.2.2`(当前源码快照,发布状态以安装包版本为准)。
6
+
7
+ 公开导出:`Alert`。
8
+
9
+ 以下 API 属于 Apex UI;不要据 antd 的同名组件推断额外属性或默认值。默认值列的空缺表示未声明,不代表 `false`。
10
+
11
+ ## 快速开始
12
+
13
+ ```tsx
14
+ import { Alert } from '@apexhub/apex-ui-react'
15
+
16
+ import '@apexhub/apex-ui-react/style.css'
17
+
18
+ export default () => <Alert type="info" title="这是一条提示" style={{ width: 560 }} />
19
+ ```
20
+
21
+ ## 何时使用
22
+
23
+ - 需要在当前页面内展示操作结果、风险提示或补充说明,且信息应持续可见时。
24
+ - 需要区分 info / success / warning / error 等语义,并可选图标、说明文字与右侧操作时。
25
+ - 若需全局短暂弹出、自动消失的通知,请使用 Message 或 Notification,而非 Alert。
26
+
27
+ ## API
28
+
29
+ 仅使用类型定义支持的属性;原生属性、ref 目标和事件签名因组件而异。关联类型用于解释字段结构;只有「导出类型」中的名称可从包根导入。
30
+
31
+ ### Alert
32
+
33
+ | 属性 | 说明 | 类型 | 必填 | 默认值 |
34
+ | --- | --- | --- | --- | --- |
35
+ | type | 语义变体 | `"info" \| "success" \| "warning" \| "error"` | 否 | `'info'` |
36
+ | title | 主标题 | `React.ReactNode` | 否 | — |
37
+ | description | 说明文本;未传时为单层文本布局 | `React.ReactNode` | 否 | — |
38
+ | showIcon | 是否显示左侧图标 | `boolean` | 否 | `true` |
39
+ | icon | 自定义图标;未传时根据 `type` 渲染内置语义 icon | `React.ReactNode` | 否 | — |
40
+ | closable | 是否显示关闭按钮 | `boolean` | 否 | `false` |
41
+ | onClose | 点击关闭按钮时触发 | `React.MouseEventHandler<HTMLButtonElement>` | 否 | — |
42
+ | action | 右侧操作区 | `React.ReactNode` | 否 | — |
43
+ | ref | React 19 ref-as-prop | `React.Ref<HTMLDivElement>` | 否 | — |
44
+ | className | 根节点 class | `string` | 否 | — |
45
+
46
+ ### AlertType
47
+
48
+ Alert 语义类型
49
+
50
+ ```typescript
51
+ type AlertType = 'info' | 'success' | 'warning' | 'error'
52
+ ```
53
+
54
+ ### 导出类型
55
+
56
+ 另可从 `@apexhub/apex-ui-react` 导入:`AlertProps`(与上文子类型配合使用)。
57
+
58
+ ## 代码演示
59
+
60
+ ### 含说明文字
61
+
62
+ 通过 `description` 展示补充说明,形成标题 + 正文双层结构。
63
+
64
+ ```tsx
65
+ import { Alert } from '@apexhub/apex-ui-react'
66
+
67
+ export default () => (
68
+ <Alert
69
+ type="success"
70
+ title="操作成功"
71
+ description="你的更改已保存,可在列表中查看最新数据。"
72
+ style={{ width: 560 }}
73
+ />
74
+ )
75
+ ```
76
+
77
+ ### 语义类型
78
+
79
+ 通过 `type` 切换 info、success、warning、error 四种语义,图标与配色随之变化。
80
+
81
+ ```tsx
82
+ import { Alert } from '@apexhub/apex-ui-react'
83
+
84
+ const types = ['info', 'success', 'warning', 'error'] as const
85
+
86
+ export default () => (
87
+ <div style={{ display: 'flex', flexDirection: 'column', gap: 12 }}>
88
+ {types.map((type) => (
89
+ <Alert key={type} type={type} title={`${type} 提示`} style={{ width: 560 }} />
90
+ ))}
91
+ </div>
92
+ )
93
+ ```
94
+
95
+ ### 可关闭
96
+
97
+ `closable` 为 true 时显示关闭按钮;点击后组件隐藏并触发 关闭事件。
98
+
99
+ ```tsx
100
+ import { Alert } from '@apexhub/apex-ui-react'
101
+
102
+ export default () => <Alert type="warning" title="可关闭的警告" closable style={{ width: 560 }} />
103
+ ```
104
+
105
+ ### 操作区
106
+
107
+ 通过 `action` 在右侧放置操作按钮或链接。示例使用 `text-secondary` 的 medium 按钮;关闭控件使用 medium 图标按钮。
108
+
109
+ ```tsx
110
+ import { Alert, Button } from '@apexhub/apex-ui-react'
111
+
112
+ export default () => (
113
+ <Alert
114
+ type="error"
115
+ title="提交失败"
116
+ description="网络异常,请稍后重试。"
117
+ action={
118
+ <Button variant="text-secondary" size="medium">
119
+ 重试
120
+ </Button>
121
+ }
122
+ style={{ width: 560 }}
123
+ />
124
+ )
125
+ ```
126
+
127
+ ## DOM 结构
128
+
129
+ 源码声明的静态 `data-slot`:`alert-icon`、`alert`、`alert-content`、`alert-title`、`alert-description`、`alert-action`、`alert-close`。具体节点随模式和状态出现,不表示固定嵌套顺序。
130
+
131
+ ## 样式定制
132
+
133
+ 优先使用本组件公开的尺寸、类型和状态属性。换肤与变量覆盖方式见 [主题指南](../../llms-theme.txt)。
134
+
135
+ 需要定制具体样式时再读取 [Token 明细](./tokens.txt),其中包含用途、定义值及适用作用域。常规组件使用无需加载该文件。
136
+
137
+ ## FAQ
138
+
139
+ ### 为什么用 `title` 而不是 antd 的 `message`?
140
+
141
+ Apex Alert 使用 `title` 作为主标题字段,语义更清晰,也与 Message 组件命名区分。迁移 antd 代码时请将 `message` 改为 `title`。
142
+
143
+
144
+ ### 默认会显示图标吗?
145
+
146
+ 会。`showIcon` 默认为 `true`;若只需纯文本提示,可设 `showIcon={false}` 或传入自定义 `icon`。
147
+
148
+
149
+
150
+ ### 关闭后还会占位置吗?
151
+
152
+ 点击关闭后组件内部会隐藏;若需同步更新外部状态,请在 `onClose` 中自行处理(例如卸载父级条件渲染)。
153
+
154
+
155
+
156
+ ### 可以用 `children` 传入内容吗?
157
+
158
+ 不可以。Alert 内容请通过 `title` 与 `description` 传入,不支持 `children`,避免与说明文字语义重叠。
159
+
160
+
161
+ ### 支持 banner 通栏模式吗?
162
+
163
+ 当前版本不支持 `banner` 通栏布局;若需页面顶部横幅提示,请用自定义布局包裹 Alert 或等待后续版本。
164
+
165
+ ### 有 outlined / filled 等 variant 吗?
166
+
167
+ 没有。v1 仅提供默认视觉一套样式;需要更多形态请通过 `className` 自行扩展。
@@ -0,0 +1,44 @@
1
+ # Alert Token 明细
2
+
3
+ 包:`@apexhub/apex-ui-react`;版本:`1.2.2`(当前源码快照)。
4
+
5
+ 按需读取:[组件用法](./llm.txt) · [主题与覆盖规则](../../llms-theme.txt)。
6
+
7
+ 以下组件变量在设计 Token 源中已定义,并被组件或其共享样式使用;不包含仅在实现中声明的临时变量。用途来自实际 CSS 属性,不是对外新增的 Props。
8
+
9
+ 定义值依赖所列尺寸、变体、状态和媒体作用域;Alias 引用还会随 light/dark 主题改变。它们不是统一默认值或最终计算值。作用域用于解释定义位置,不代表内部选择器是稳定的定制 API。
10
+
11
+ | Token | 用途(CSS 属性) | 定义值 | 定义作用域 |
12
+ | --- | --- | --- | --- |
13
+ | `--alert-fill-default` | `background-color` | `var(--apex-fill-brand-alpha-secondary)` | `.apex-alert.apex-brand-alert` |
14
+ | `--alert-fill-default` | `background-color` | `var(--apex-fill-error-alpha-secondary)` | `.apex-alert.apex-error-alert` |
15
+ | `--alert-fill-default` | `background-color` | `var(--apex-fill-success-alpha-secondary)` | `.apex-alert.apex-success-alert` |
16
+ | `--alert-fill-default` | `background-color` | `var(--apex-fill-warning-alpha-secondary)` | `.apex-alert.apex-warning-alert` |
17
+ | `--alert-icon-default` | `color` | `var(--apex-icon-brand-primary)` | `.apex-alert.apex-brand-alert` |
18
+ | `--alert-icon-default` | `color` | `var(--apex-icon-error-primary)` | `.apex-alert.apex-error-alert` |
19
+ | `--alert-icon-default` | `color` | `var(--apex-icon-warning-primary)` | `.apex-alert.apex-warning-alert` |
20
+ | `--alert-icon-icon` | `font-size`、`height`、`width` | `var(--apex-icon-24)` | `.apex-alert.apex-default-alert` |
21
+ | `--alert-icon-success` | `color` | `var(--apex-icon-success-primary)` | `.apex-alert.apex-success-alert` |
22
+ | `--alert-radius-radius` | `border-radius` | `var(--apex-radius-8)` | `.apex-alert.apex-default-alert` |
23
+ | `--alert-size-width` | `max-width` | `var(--apex-size-1120)` | `.apex-alert.apex-default-alert` |
24
+ | `--alert-spacing-gap-icon-text` | `gap` | `var(--apex-spacing-12)` | `.apex-alert.apex-default-alert` |
25
+ | `--alert-spacing-gap-title-caption` | `gap` | `var(--apex-spacing-0)` | `.apex-alert.apex-default-alert` |
26
+ | `--alert-spacing-padding-x` | `padding` | `var(--apex-spacing-16)` | `.apex-alert.apex-default-alert` |
27
+ | `--alert-spacing-padding-y` | `padding` | `var(--apex-spacing-8)` | `.apex-alert.apex-default-alert` |
28
+ | `--alert-stroke-default` | `border` | `var(--apex-fill-brand-primary)` | `.apex-alert.apex-brand-alert` |
29
+ | `--alert-stroke-default` | `border` | `var(--apex-fill-error-primary)` | `.apex-alert.apex-error-alert` |
30
+ | `--alert-stroke-default` | `border` | `var(--apex-fill-success-primary)` | `.apex-alert.apex-success-alert` |
31
+ | `--alert-stroke-default` | `border` | `var(--apex-fill-warning-primary)` | `.apex-alert.apex-warning-alert` |
32
+ | `--alert-stroke-stroke` | `border` | `var(--apex-border-08)` | `.apex-alert.apex-default-alert` |
33
+ | `--alert-text-body` | `color` | `var(--apex-text-neutral-primary)` | `.apex-alert.apex-brand-alert` |
34
+ | `--alert-text-body` | `color` | `var(--apex-text-neutral-primary)` | `.apex-alert.apex-error-alert` |
35
+ | `--alert-text-body` | `color` | `var(--apex-text-neutral-primary)` | `.apex-alert.apex-success-alert` |
36
+ | `--alert-text-body` | `color` | `var(--apex-text-neutral-primary)` | `.apex-alert.apex-warning-alert` |
37
+ | `--alert-text-caption` | `color` | `var(--apex-text-neutral-secondary)` | `.apex-alert.apex-brand-alert` |
38
+ | `--alert-text-caption` | `color` | `var(--apex-text-neutral-secondary)` | `.apex-alert.apex-error-alert` |
39
+ | `--alert-text-caption` | `color` | `var(--apex-text-neutral-secondary)` | `.apex-alert.apex-success-alert` |
40
+ | `--alert-text-caption` | `color` | `var(--apex-text-neutral-secondary)` | `.apex-alert.apex-warning-alert` |
41
+ | `--alert-text-title` | `color` | `var(--apex-text-neutral-primary)` | `.apex-alert.apex-brand-alert` |
42
+ | `--alert-text-title` | `color` | `var(--apex-text-neutral-primary)` | `.apex-alert.apex-error-alert` |
43
+ | `--alert-text-title` | `color` | `var(--apex-text-neutral-primary)` | `.apex-alert.apex-success-alert` |
44
+ | `--alert-text-title` | `color` | `var(--apex-text-neutral-primary)` | `.apex-alert.apex-warning-alert` |