idea-react 3.0.0-beta.1 → 3.0.0-beta.3

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 (89) hide show
  1. package/AGENTS.md +12 -3
  2. package/ReadMe.md +34 -6
  3. package/dist/index.d.mts +313 -230
  4. package/dist/index.d.ts +313 -230
  5. package/dist/index.js +16 -16
  6. package/dist/index.mjs +15 -15
  7. package/dist/style.css +0 -3
  8. package/package.json +13 -13
  9. package/source/Accordion.tsx +61 -37
  10. package/source/Alert.tsx +30 -15
  11. package/source/Avatar.tsx +55 -50
  12. package/source/Badge.tsx +16 -16
  13. package/source/Breadcrumb.tsx +36 -22
  14. package/source/Button.tsx +63 -69
  15. package/source/ButtonGroup.tsx +21 -25
  16. package/source/Card.tsx +67 -59
  17. package/source/Carousel/index.tsx +22 -21
  18. package/source/CloseButton.tsx +20 -15
  19. package/source/Collapse.tsx +74 -19
  20. package/source/Drawer.tsx +40 -17
  21. package/source/Extension/ClickBoundary.tsx +24 -5
  22. package/source/Extension/CodeBlock.tsx +64 -0
  23. package/source/Extension/Countdown.tsx +21 -9
  24. package/source/Extension/Editor.tsx +53 -18
  25. package/source/Extension/EditorHTML.tsx +7 -3
  26. package/source/Extension/HorizontalMarquee/index.tsx +69 -45
  27. package/source/Extension/Icon.tsx +15 -14
  28. package/source/Extension/Loading.tsx +20 -17
  29. package/source/Extension/MonthCalendar.tsx +26 -10
  30. package/source/Extension/OverlayBox.tsx +28 -15
  31. package/source/Extension/PageNav.tsx +16 -7
  32. package/source/Extension/ScrollNav/Scroller.tsx +21 -5
  33. package/source/Extension/ScrollNav/index.tsx +32 -7
  34. package/source/Extension/Select.tsx +12 -11
  35. package/source/Extension/SpinnerButton.tsx +19 -24
  36. package/source/Extension/TableSpinner.tsx +10 -14
  37. package/source/Extension/TextTruncate/index.tsx +17 -13
  38. package/source/Extension/Time.tsx +7 -5
  39. package/source/Extension/TimeDistance.tsx +22 -18
  40. package/source/Extension/Timeline/index.tsx +37 -34
  41. package/source/Extension/TypeEcho/Content.tsx +79 -14
  42. package/source/Extension/TypeEcho/index.tsx +13 -5
  43. package/source/Extension/UserRank/Address.tsx +17 -15
  44. package/source/Extension/UserRank/index.tsx +79 -84
  45. package/source/Extension/VerticalMarquee/index.tsx +14 -16
  46. package/source/Extension/ZodiacBar.tsx +40 -32
  47. package/source/Form/Adorn.tsx +30 -32
  48. package/source/Form/Checkbox.tsx +9 -5
  49. package/source/Form/ChipInput.tsx +9 -5
  50. package/source/Form/Chips.tsx +41 -39
  51. package/source/Form/Combobox.tsx +80 -61
  52. package/source/Form/Control.tsx +53 -58
  53. package/source/Form/DatePicker.tsx +74 -65
  54. package/source/Form/Feedback.tsx +18 -19
  55. package/source/Form/FloatingLabel.tsx +16 -19
  56. package/source/Form/InputGroup.tsx +27 -26
  57. package/source/Form/OTP.tsx +30 -12
  58. package/source/Form/Primitives.tsx +47 -39
  59. package/source/Form/Radio.tsx +25 -22
  60. package/source/Form/Range.tsx +30 -12
  61. package/source/Form/Switch.tsx +73 -48
  62. package/source/Form/inputProps.ts +184 -0
  63. package/source/Grid.tsx +67 -59
  64. package/source/Image.tsx +10 -6
  65. package/source/ListGroup.tsx +57 -69
  66. package/source/Menu.tsx +128 -66
  67. package/source/NativeDialog/index.tsx +51 -29
  68. package/source/Nav.tsx +46 -46
  69. package/source/NavOverflow/index.tsx +26 -10
  70. package/source/Navbar.tsx +60 -55
  71. package/source/Pagination.tsx +63 -69
  72. package/source/Placeholder.tsx +47 -43
  73. package/source/Polymorphic.ts +57 -0
  74. package/source/Popover.tsx +34 -31
  75. package/source/Progress/index.tsx +59 -54
  76. package/source/ScrollSpy/index.tsx +48 -33
  77. package/source/Spinner.tsx +27 -23
  78. package/source/Stack.tsx +25 -0
  79. package/source/Stepper.tsx +46 -40
  80. package/source/Tab.tsx +40 -27
  81. package/source/Table.tsx +53 -42
  82. package/source/Toast.tsx +62 -47
  83. package/source/ToggleButton.tsx +65 -54
  84. package/source/Toggler.tsx +17 -8
  85. package/source/Tooltip.tsx +31 -29
  86. package/source/index.ts +2 -0
  87. package/tsconfig.json +2 -2
  88. package/source/Extension/CodeBlock/index.tsx +0 -58
  89. package/source/Extension/CodeBlock/style.module.css +0 -3
package/AGENTS.md CHANGED
@@ -183,6 +183,12 @@ export class MyComponent extends ObservedComponent<MyComponentProps> {
183
183
  - 向子组件透传时只解构需要特殊处理的 props,其余用 `...this.props` 展开,不逐项转发。
184
184
  - 多个组件共享的属性定义在基础模块,组件通过 `extends`、`Omit` 或类型别名复用,不从组件文件再导出基础模块的类型。
185
185
  - 没有成员声明体的 `interface` 改用 `type` 与交叉类型表达。
186
+ - 单根节点组件复用 `source/Polymorphic.ts` 的泛型与组合机制支持 `as`,透传目标组件属性;
187
+ 片段或多根节点组件不强行添加包装节点,类组件的 `ref` 保持实例语义。
188
+ 类组件显式声明 `declare readonly props: PolymorphicClassProps<T, Props>`,避免 React 的
189
+ `Readonly` 映射丢失目标属性的联合类型;内部按需使用类型收窄 getter。
190
+ - 用通用组件替换原生元素或已有组件时,使用 `as` 指定原元素/组件,并保留其语义、属性、事件和行为;不因替换标签而丢失原有能力。优先复用组件已有的属性透传,避免重复包装。
191
+ - 表单组件的原生控件属性直接暴露为组件顶层 props,不封装在 `inputProps` 等嵌套对象中。
186
192
  - 组件 Props 优先用 `Pick`/`Omit`/`extends` 复用已有类型,不重复声明;按外观、内容、状态、行为的顺序分组排列。
187
193
  - JSX 属性按 `as`、HTML 通用静态属性、组件专属属性、状态属性、回调属性排序;相同键值的 props 可用对象字面量简写后展开。
188
194
  - 同一模块的类型与值合并为一条 import,不拆成 `import type` 与 `import` 两条。
@@ -200,10 +206,13 @@ export class MyComponent extends ObservedComponent<MyComponentProps> {
200
206
  - 文档站使用 ViNext,保留 MDX 支持并以纯 SSG 导出;部署静态文件,不依赖运行时服务器。
201
207
  - 文档站页面参考上游设计,但品牌使用 **Idea React**,版本、许可证、安装命令、链接及其它文案
202
208
  均以本项目实际情况为准;保留必要的上游版权和许可证声明。
209
+ - 同步上游文档时保留正文主题、章节顺序、示例覆盖与必要资源;逐段将说明和示例改写为本项目真实 API,仅删除确实不适用的内容,不将完整指南大幅缩写成 quick start。文档示例只使用本库实际导出的包路径、组件能力和已验证的官方链接。
210
+ - 文案中的缩写使用全大写形式(如 NPM、CSS)。
211
+ - 修改导航分类或路由命名时,同步更新页面标题、导航、页脚、站点链接和所有引用;确认新路由真实存在,并全局清理旧名称及失效路径。
203
212
  - 页面格式以简洁、可读为准:文档可用 MDX,非文档页(包括首页)在能减少缩进时也可用
204
213
  MDX,不强制非文档页只能使用 TSX 或 MDX。
205
214
  - 跨页面共享的导航栏等结构放在公共布局中,不重复写入单个页面。
206
- - 上游来源与版权许可说明集中在网站公共页脚,不在各篇组件文档重复。
215
+ - 上游来源与版权许可说明集中在网站公共页脚,不在各篇组件文档重复,也不添加指向上游单页源码的链接。
207
216
  - MDX 中的大段静态文本优先使用 Markdown,而非嵌套的 JSX 文本块。
208
217
  - 从 `unpkg.com` 引入 Bootstrap CSS,严禁使用 Tailwind CSS 及其插件、配置和工具类。
209
218
  - 能用 [Bootstrap 6 CSS 工具类][4] 的样式不写自定义 CSS;
@@ -216,7 +225,7 @@ export class MyComponent extends ObservedComponent<MyComponentProps> {
216
225
  - Markdown 正文中的链接采用文末数字引用:正文写 `[text][number]`,文末写 `[number]: URL`;图片链接同样使用引用形式。行末链接(如组件列表项)无需改为文末引用,可保留 `[text](URL)`。
217
226
  - 每篇文档的数字引用按首次出现顺序从 1 连续编号;重复链接复用同一编号,修改后同步整理正文与定义,移除未使用定义,不留跳号、重复或悬空引用。
218
227
  - 组件目录优先列出上游标准组件,再列扩展组件。
219
- - 静态站搜索优先采用最简单可用的方案,自动索引导出内容,不维护手写页面清单,不为索引格式或具体技术额外引入不必要的服务和框架。
228
+ - 静态站搜索优先采用最简单可用的方案,开发与生产共用 MDX 源码索引器并通过同一 JSON 地址加载,不依赖编译后的 HTML,不维护手写页面清单,不为索引格式或具体技术额外引入不必要的服务和框架。
220
229
 
221
230
  ## 测试与验证
222
231
 
@@ -241,7 +250,7 @@ pnpm build -r
241
250
  - `test` 使用 Node.js 原生 runner,需要 Node.js 22.18+,并做 TypeScript 检查。Lint 与格式检查针对本次修改文件运行。
242
251
  - 根目录 `pnpm build` 构建 TypeDoc、旧预览站与组件发布包;现有根构建、发布部署仍使用 `docs/`,不能将其误当作 ViNext 文档工作区的构建或部署。
243
252
  - 文档工作区单独构建,只部署 `document/dist/client/`;部署到子目录前配置 `document/next.config.ts` 的 `basePath`,并验证静态资源、搜索索引和结果链接。
244
- - 搜索索引在导出 HTML 后生成;验证搜索时先构建,再预览静态产物。
253
+ - 开发模式按请求从当前 MDX 文档生成搜索索引;生产模式用同一索引器生成静态 JSON,生产搜索需构建后预览静态产物。
245
254
  - 浏览器验证包括键盘交互、主题恢复、错误弹窗、失败后重试与不同视口;文档站不依赖 Node.js 或 Worker 运行时。
246
255
 
247
256
  ## 发布维护
package/ReadMe.md CHANGED
@@ -12,10 +12,11 @@ A **[React][1] advanced components library** based on [TypeScript][2] & [Bootstr
12
12
 
13
13
  ## Versions
14
14
 
15
- | SemVer | status | ES decorator | MobX |
16
- | :----: | :----------: | :----------: | :---------: |
17
- | `>=2` | ✅developing | stage-3 | `>=6.11` |
18
- | `<2` | ❌deprecated | stage-2 | `>=4 <6.11` |
15
+ | SemVer | status | ES decorator | MobX | Bootstrap |
16
+ | :------: | :----------: | :----------: | :---------: | :-------: |
17
+ | `>=3` | ✅developing | stage-3 | `>=6.11` | v6 |
18
+ | `>=2 <3` | ❌deprecated | stage-3 | `>=6.11` | v5 |
19
+ | `<2` | ❌deprecated | stage-2 | `>=4 <6.11` | v5 |
19
20
 
20
21
  ## Content
21
22
 
@@ -76,7 +77,7 @@ A **[React][1] advanced components library** based on [TypeScript][2] & [Bootstr
76
77
  ### Extension components
77
78
 
78
79
  1. [Click Boundary](source/Extension/ClickBoundary.tsx)
79
- 2. [Code Block](source/Extension/CodeBlock/)
80
+ 2. [Code Block](source/Extension/CodeBlock.tsx)
80
81
  3. [Countdown](source/Extension/Countdown.tsx)
81
82
  4. [Dialog](source/Extension/Dialog.tsx)
82
83
  5. [Editor](source/Extension/Editor.tsx)
@@ -136,7 +137,7 @@ For the current alpha release, use `idea-react@next` instead of `idea-react`.
136
137
  rel="stylesheet"
137
138
  href="https://unpkg.com/bootstrap@6.0.0-alpha.1/dist/css/bootstrap.min.css"
138
139
  />
139
- <link rel="stylesheet" href="https://unpkg.com/bootstrap-icons@1.13.1/font/bootstrap-icons.css" />
140
+ <link rel="stylesheet" href="https://unpkg.com/bootstrap-icons@1.13.2/font/bootstrap-icons.css" />
140
141
  <link rel="stylesheet" href="https://unpkg.com/animate.css@4.1.1/animate.min.css" />
141
142
  <link rel="stylesheet" href="https://unpkg.com/idea-react/dist/index.css" />
142
143
  ```
@@ -157,6 +158,33 @@ Compatible with MobX 6/7:
157
158
  }
158
159
  ```
159
160
 
161
+ ### Polymorphic roots
162
+
163
+ Components with a single root support `as`, accepting an HTML tag or another React component:
164
+
165
+ ```tsx
166
+ import { ComponentPropsWithRef, FC } from 'react';
167
+ import { Button, Card, PolymorphicProps } from 'idea-react';
168
+
169
+ const RouterLink: FC<ComponentPropsWithRef<'a'> & { to: string }> = ({ to, ...props }) => (
170
+ <a {...props} href={to} />
171
+ );
172
+
173
+ type LinkCardProps = PolymorphicProps<typeof RouterLink, { theme?: 'primary' }>;
174
+
175
+ <Card as="article">Article content</Card>;
176
+
177
+ <Button as={RouterLink} to="/docs" variant="solid" theme="primary">
178
+ Documentation
179
+ </Button>;
180
+ ```
181
+
182
+ The target's additional props are inferred and forwarded, including required props and compatible
183
+ refs. Component-specific props keep their existing meaning and take precedence on name collisions.
184
+ Without `as`, the default markup and props stay unchanged. Class component refs still refer to the
185
+ component instance. Behavioral components require compatible root elements; custom roots must forward
186
+ their DOM props and refs. Components that render fragments or multiple roots do not support `as`.
187
+
160
188
  ### Dialog
161
189
 
162
190
  ```tsx