@canvas-components/react-components 0.3.19 → 0.3.20

package/README.md

@@ -25,6 +25,8 @@ pnpm add @canvas-components/react-components react@^16.8 react-dom@^16.8
 
 ```tsx
 import {
+  ReactHomeOutlined,
+  ReactIcon,
   ReactPopconfirm,
   ReactPopup,
   ReactTransition,
@@ -32,30 +34,100 @@ import {
 
 function Demo() {
   return (
-    <ReactPopconfirm
-      title="确认删除这条记录？"
-      description="删除后不可恢复"
-      onConfirm={() => console.log("confirmed")}
-    >
-      <button type="button">删除</button>
-    </ReactPopconfirm>
+    <>
+      <ReactIcon name="HomeOutlined" size={20} aria-label="首页" />
+      <ReactHomeOutlined size={20} aria-hidden="true" />
+      <ReactPopconfirm
+        title="确认删除这条记录？"
+        description="删除后不可恢复"
+        onConfirm={() => console.log("confirmed")}
+      >
+        <button type="button">删除</button>
+      </ReactPopconfirm>
+    </>
   );
 }
 ```
 
+### 表单组件
+
+组件可作为受控输入使用，也可以放进普通 HTML 表单或 `ReactForm` 中。以下示例组合文本框、可搜索选择器、日期选择器、复选框、按钮和确认气泡：
+
+```tsx
+import { useState } from "react";
+import {
+  ReactButton,
+  ReactCheckbox,
+  ReactDatePicker,
+  ReactFlex,
+  ReactInput,
+  ReactPopconfirm,
+  ReactSelect,
+} from "@canvas-components/react-components";
+
+export function ProfileForm() {
+  const [name, setName] = useState("林晨");
+  const [team, setTeam] = useState("design");
+  const [date, setDate] = useState("2026-10-18");
+  const [subscribed, setSubscribed] = useState(true);
+
+  return (
+    <form onSubmit={(event) => event.preventDefault()}>
+      <label>
+        姓名
+        <ReactInput value={name} onChange={(event) => setName(event.currentTarget.value)} />
+      </label>
+      <label>
+        团队
+        <ReactSelect
+          value={team}
+          showSearch
+          options={[
+            { value: "design", label: "设计团队" },
+            { value: "engineering", label: "研发团队" },
+          ]}
+          onChange={setTeam}
+        />
+      </label>
+      <ReactDatePicker value={date} onChange={setDate} />
+      <ReactCheckbox
+        checked={subscribed}
+        onChange={(event) => setSubscribed(event.currentTarget.checked)}
+      >
+        接收团队动态
+      </ReactCheckbox>
+      <ReactFlex gap={8}>
+        <ReactButton type="primary" htmlType="submit">保存</ReactButton>
+        <ReactPopconfirm title="确认删除？" onConfirm={() => setName("")}>
+          <ReactButton danger>删除</ReactButton>
+        </ReactPopconfirm>
+      </ReactFlex>
+    </form>
+  );
+}
+```
+
+文档站「React Components」目录为每个组件提供了独立示例，包含组件用途、属性说明和可复制的 JSX 用法；图标目录也列出全部具名图标。
+
 ## 组件列表
 
-### 输入与选择
+### 表单与选择
 
 - `ReactInput`
 - `ReactNumberInput`
 - `ReactInputNumber`
-- `ReactCheckbox`
-- `ReactRadio`
-- `ReactSelect`
-- `ReactColorPicker`
-- `ReactTextArea`
-- `ReactForm`
+- `ReactInputRange`
+- `ReactCheckbox`
+- `ReactRadio`
+- `ReactSelect`
+- `ReactAutoComplete`
+- `ReactCascader`
+- `ReactTreeSelect`
+- `ReactColorPicker`
+- `ReactTextArea`
+- `ReactForm`
+
+`ReactNumberInput` 和 `ReactInputRange` 默认不使用鼠标滚轮调整数值；需要该行为时传入 `changeOnWheel`，例如 `<ReactNumberInput value={count} onChange={setCount} changeOnWheel />`。
 
 ### 日期时间
 
@@ -69,21 +141,47 @@ function Demo() {
 - `ReactQuarterPicker`
 - `ReactYearPicker`
 
-### 展示与交互
+### 弹层与反馈
 
 - `ReactPopup`
+- `ReactDropdown`
+- `ReactModal`
+- `ReactDrawer`
 - `ReactPopconfirm`
+- `ReactTooltip`
 - `ReactTransition`
+- `reactMessage`
+
+### 展示、布局与交互
+
 - `ReactPagination`
 - `ReactVirtualList`
-- `ReactImagePreview`
-- `ReactButton`
-- `ReactFlex` / `ReactRow` / `ReactCol`
-- `ReactTooltip`
-- `reactMessage`
+- `ReactWaterfall`
+- `ReactResizablePanels`
+- `ReactImagePreview`
+- `ReactButton`
+- `ReactIcon` 与 831 个 Ant Design 风格具名 SVG 图标（例如 `ReactHomeOutlined`）
+- `ReactFlex` / `ReactRow` / `ReactCol`
+- `ReactFilterPanel`
 
 ## 属性说明
 
+### `ReactDropdown`
+
+```tsx
+<ReactDropdown
+  items={[
+    { key: "json", label: "导出 JSON" },
+    { key: "pdf", label: "导出 PDF", description: "实验性功能" },
+  ]}
+  onSelect={(key) => exportFile(key)}
+>
+  导出
+</ReactDropdown>
+```
+
+`children` 可省略；只传 `icon` 时触发按钮显示居中的图标，建议同时通过 `triggerProps` 提供 `aria-label`。菜单项支持禁用、图标、说明、拖拽事件和指针进入事件。可用 `open`、`defaultOpen`、`onOpenChange` 控制展开状态；支持方向键、Home、End 和 Esc。
+
 ### `ReactPopupProps`
 
 | 属性 | 类型 | 说明 |
@@ -173,3 +271,23 @@ function Demo() {
 ## 说明
 
 这个包的导出面比较大，输入类组件大多保持接近原生表单语义；如果需要精确字段，请优先查看对应组件的 `Props` 类型定义。
+
+图标组件使用包内自包含的 SVG 路径数据，不需要安装 Ant Design 或图标数据包。图标名称、尺寸、颜色、旋转和加载动画由 `ReactIconProps` 提供；也可以直接使用 `ReactHomeOutlined` 等具名组件。SVG 路径数据的上游许可和版权信息见随包发布的 `THIRD_PARTY_NOTICES.md`。
+
+### 通用折叠面板
+
+`ReactCollapsePanel` 使用现有方向图标，支持鼠标及 Enter / 空格展开折叠。折叠时保留内容节点和输入草稿。
+
+```tsx
+<ReactCollapsePanel title="位置与尺寸" defaultOpen>
+  <ReactInput placeholder="输入名称" />
+</ReactCollapsePanel>
+```
+
+通过 `open` 与 `onOpenChange` 控制展开状态；`disabled` 禁止切换，`contentClassName` 可定制内容区样式。默认收起。
+
+### 通用拖拽排序
+
+`ReactSortableList` 统一提供与 ListTable 工具栏列排序一致的浮动行、实时让位动画、边缘自动滚动和全屏浮层。通过 `items`（包含 `key`、`parentKey`、`label`）、`renderItem(item, handleProps)` 和 `onOrderChange(parentKey, orderedKeys)` 接入；把 `handleProps` 传给使用现有图标的拖拽手柄。`scrollContainerRef` 指向滚动容器，`disabled` 禁止拖拽，`dragThreshold` 默认 4px。Esc、失焦和指针取消会丢弃排序，放下才提交一次顺序。后续拖拽排序统一复用此组件。
+
+大量节点可传入 `virtual={{ height: 360, itemHeight: 34, overscan: 6 }}` 启用固定行高虚拟列表；组件使用内部滚动容器自动滚动，拖拽命中按完整列表计算，包含尚未挂载的节点。

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,30 @@
+# 第三方版权声明
+
+## Ant Design Icons
+
+本包通过 `@canvas-components/icons` 使用 Ant Design Icons 项目的 SVG 图标路径数据。许可声明随共享图标包发布。
+
+```text
+MIT LICENSE
+
+Copyright (c) 2018-present Ant UED, https://xtech.antfin.com/
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+```