@xfe-repo/web-components 1.6.1 → 1.7.0

package/skills/references/CInput.md

@@ -0,0 +1,196 @@
+# CInput
+
+> 增强版 Input 输入框，在 antd Input 基础上默认启用失焦自动 trim，适用于表单场景防止用户输入前后空格。
+
+## 导入
+
+```tsx
+import { CInput } from '@xfe-repo/web-components'
+import type { CInputProps, CTextAreaProps, CSearchProps } from '@xfe-repo/web-components'
+```
+
+## 基本用法
+
+```tsx
+import { CInput } from '@xfe-repo/web-components'
+import { Form } from 'antd'
+
+function MyForm() {
+  return (
+    <Form>
+      <Form.Item name="name" label="名称">
+        <CInput placeholder="失焦时自动去除首尾空格" />
+      </Form.Item>
+    </Form>
+  )
+}
+```
+
+### 搜索栏标准用法
+
+在 SearchForm/SearchList 中使用 CInput 作为搜索输入（最高频场景）：
+
+```tsx
+<SearchForm form={form} filter={filter} onFinish={onFinish}>
+  <Form.Item name="orderNo" label="订单号">
+    <CInput placeholder="请输入" allowClear style={{ width: 200 }} />
+  </Form.Item>
+  <Form.Item name="productName" label="商品名">
+    <CInput placeholder="请输入" allowClear style={{ width: 200 }} />
+  </Form.Item>
+</SearchForm>
+```
+
+> 💡 搜索栏中 CInput 的标准 prop 组合：`placeholder` + `allowClear` + `style={{ width: N }}`。`autoTrim` 默认启用，无需手动设置。
+
+> 💡 常用 prop 补充：`suffix` 添加单位后缀（如 `suffix="元"` 或 `suffix="%"`），`readOnly` + `variant="borderless"` 实现只读展示。
+
+## 进阶用法
+
+### 禁用自动 trim
+
+```tsx
+<CInput autoTrim={false} placeholder="不会自动去除空格" />
+```
+
+### 使用 TextArea 子组件
+
+```tsx
+<CInput.TextArea rows={4} placeholder="多行输入，同样支持 autoTrim" />
+```
+
+### 使用 Search 子组件
+
+Search 子组件在 `onSearch` 回调中也会自动 trim 搜索值。
+
+```tsx
+<CInput.Search placeholder="搜索" onSearch={(value) => console.log('已 trim 的搜索值:', value)} />
+```
+
+### CInput.Group 区间表达式
+
+用 disabled CInput 作为数学符号分隔符，构建价格/数量区间输入：
+
+```tsx
+<CInput.Group compact>
+  <CInput placeholder="[" disabled style={{ width: 30 }} />
+  <Form.Item name="priceMin" noStyle>
+    <InputNumber style={{ width: 100 }} placeholder="最低" />
+  </Form.Item>
+  <CInput placeholder="～" disabled style={{ width: 36 }} />
+  <Form.Item name="priceMax" noStyle>
+    <InputNumber style={{ width: 100 }} placeholder="最高" />
+  </Form.Item>
+  <CInput placeholder=")" disabled style={{ width: 30 }} />
+</CInput.Group>
+```
+
+### 扫码输入场景
+
+仓库扫码场景的标准 prop 组合：
+
+```tsx
+<CInput placeholder="扫描可获得 / 手动输入" autoFocus autoComplete="off" allowClear />
+```
+
+> 💡 扫码场景必须设置 `autoComplete="off"` 禁用浏览器自动填充，`autoFocus` 自动聚焦方便操作。
+
+### Space.Compact 组合输入
+
+Select + CInput 组成复合输入（如"链接类型 + URL"）：
+
+```tsx
+<Space.Compact>
+  <Form.Item name="linkType" noStyle>
+    <Select
+      style={{ width: 120 }}
+      options={[
+        { label: '商品链接', value: 'product' },
+        { label: '外部链接', value: 'external' },
+      ]}
+    />
+  </Form.Item>
+  <Form.Item name="linkUrl" noStyle>
+    <CInput placeholder="请输入链接" style={{ width: 300 }} />
+  </Form.Item>
+</Space.Compact>
+```
+
+### 登录场景
+
+```tsx
+<CInput prefix={<PhoneOutlined />} placeholder="手机号" maxLength={11} />
+<CInput prefix={<LockOutlined />} type="password" placeholder="验证码" />
+```
+
+### CInput.TextArea 标准用法
+
+```tsx
+<Form.Item name="remark" label="备注">
+  <CInput.TextArea rows={4} maxLength={200} showCount placeholder="请输入" />
+</Form.Item>
+```
+
+> 💡 TextArea 标准组合：`rows`（展示行数）+ `maxLength`（字符限制）+ `showCount`（显示已输入字数）。
+
+## Props
+
+### CInputProps
+
+```typescript
+export interface CInputProps extends InputProps {
+  /** 是否在失焦时自动去掉首尾空格，默认 true */
+  autoTrim?: boolean
+}
+```
+
+| 属性          | 类型         | 必填 | 默认值 | 说明                         |
+| ------------- | ------------ | ---- | ------ | ---------------------------- |
+| autoTrim      | `boolean`    | 否   | `true` | 是否在失焦时自动去除首尾空格 |
+| ...inputProps | `InputProps` | 否   | -      | 所有 antd Input 属性         |
+
+### CTextAreaProps
+
+```typescript
+export interface CTextAreaProps extends TextAreaProps {
+  autoTrim?: boolean
+}
+```
+
+### CSearchProps
+
+```typescript
+export interface CSearchProps extends SearchProps {
+  autoTrim?: boolean
+}
+```
+
+## 子组件
+
+| 子组件            | 类型                                        | 说明                                   |
+| ----------------- | ------------------------------------------- | -------------------------------------- |
+| `CInput.TextArea` | `ForwardRefExoticComponent<CTextAreaProps>` | 多行输入框，支持 autoTrim              |
+| `CInput.Search`   | `ForwardRefExoticComponent<CSearchProps>`   | 搜索输入框，onSearch 回调也会自动 trim |
+| `CInput.Group`    | `typeof Input.Group`                        | 直接透传 antd 的 Input.Group           |
+
+## 常见陷阱
+
+- ❌ 在 Form 中使用原生 `Input`，用户输入 `" 张三 "` 提交时带空格：
+  ```tsx
+  <Form.Item name="name">
+    <Input /> {/* 不会自动 trim */}
+  </Form.Item>
+  ```
+- ✅ 使用 `CInput` 替代，失焦时自动 trim 并通过 onChange 同步到 Form：
+  ```tsx
+  <Form.Item name="name">
+    <CInput /> {/* 失焦时自动 trim，Form 值同步更新 */}
+  </Form.Item>
+  ```
+
+## 相关组件
+
+| 场景     | 组件           | 说明                                     |
+| -------- | -------------- | ---------------------------------------- |
+| 搜索表单 | `SearchForm`   | 表单容器，内部可使用 CInput 作为输入组件 |
+| 隐私字段 | `PrivacyField` | 展示脱敏数据，非输入场景                 |

package/skills/references/CTable.md

@@ -0,0 +1,274 @@
+# CTable
+
+> 增强表格组件，基于 antd Table 扩展了拖拽排序功能，通过 `enableDrag` 一键切换普通表格和可排序表格。
+
+## 导入
+
+```tsx
+import { CTable, getCTable } from '@xfe-repo/web-components'
+import type { CTableProps, TableDragEndEvent } from '@xfe-repo/web-components'
+
+// dashboard 项目标准别名
+import { CTable as TypeTable } from '@xfe-repo/web-components'
+```
+
+## 基本用法
+
+普通表格模式，与 antd Table 完全一致：
+
+```tsx
+import { CTable } from '@xfe-repo/web-components'
+
+function MyPage() {
+  const columns = [
+    { title: '名称', dataIndex: 'name' },
+    { title: '年龄', dataIndex: 'age' },
+  ]
+
+  return <CTable dataSource={data} columns={columns} rowKey="id" />
+}
+```
+
+### 直接泛型用法
+
+无需 `getCTable` 工厂函数，直接使用泛型参数：
+
+```tsx
+<CTable<UserRecord> dataSource={users} columns={columns} rowKey="id" />
+```
+
+### TypeTable 别名 + JSX Column 模式
+
+dashboard 项目约定使用 `TypeTable` 别名，配合 JSX Column 声明列：
+
+```tsx
+import { CTable as TypeTable } from '@xfe-repo/web-components'
+
+function OrderList({ tableProps }: { tableProps: CTableProps<OrderItem> }) {
+  return (
+    <TypeTable<OrderItem> {...tableProps} rowKey="orderNo">
+      <TypeTable.Column<OrderItem> title="订单号" render={renderOrderNo} align="center" />
+      <TypeTable.Column<OrderItem> title="金额" render={renderPrice} align="center" />
+      <TypeTable.Column<OrderItem> title="操作" render={renderAction} align="right" />
+    </TypeTable>
+  )
+}
+```
+
+> 💡 `TypeTable` 只是 `CTable` 的别名，功能完全一致。使用 JSX Column 方式可以获得更好的 TypeScript 类型推导。
+
+## 进阶用法
+
+### 拖拽排序
+
+开启 `enableDrag` 后自动切换为拖拽排序表格，需要提供 `onSortEnd` 回调和 `CTable.DragHandle` 拖拽手柄：
+
+```tsx
+import { CTable } from '@xfe-repo/web-components'
+import type { TableDragEndEvent } from '@xfe-repo/web-components'
+import { arrayMove } from '@dnd-kit/sortable'
+
+function SortableTable() {
+  const [data, setData] = useState(initialData)
+
+  const columns = [
+    {
+      title: '排序',
+      width: 60,
+      render: () => <CTable.DragHandle />,
+    },
+    { title: '名称', dataIndex: 'name' },
+    { title: '描述', dataIndex: 'description' },
+  ]
+
+  const handleSortEnd = (event: TableDragEndEvent) => {
+    const { active, over } = event
+    if (active.id !== over?.id) {
+      const oldIndex = data.findIndex((i) => i.id === active.id)
+      const newIndex = data.findIndex((i) => i.id === over?.id)
+      setData(arrayMove(data, oldIndex, newIndex))
+    }
+  }
+
+  return <CTable enableDrag dataSource={data} columns={columns} rowKey="id" onSortEnd={handleSortEnd} />
+}
+```
+
+### 行选择（rowSelection）
+
+```tsx
+const [selectedRowKeys, setSelectedRowKeys] = useState<string[]>([])
+
+const rowSelection = {
+  selectedRowKeys,
+  onChange: (keys: string[]) => setSelectedRowKeys(keys),
+}
+
+<CTable
+  dataSource={dataSource}
+  columns={columns}
+  rowKey="id"
+  rowSelection={rowSelection}
+/>
+
+// 获取选中项
+<Button onClick={() => handleBatch(selectedRowKeys)}>
+  批量操作（{selectedRowKeys.length}）
+</Button>
+```
+
+### 使用 CTable.Column 声明列
+
+```tsx
+<CTable dataSource={data} rowKey="id">
+  <CTable.Column title="名称" dataIndex="name" />
+  <CTable.Column title="年龄" dataIndex="age" />
+</CTable>
+```
+
+### 使用 getCTable 获得泛型类型推导
+
+`getCTable<T>()` 返回带有完整类型推导的 CTable 组件：
+
+```tsx
+import { getCTable } from '@xfe-repo/web-components'
+
+interface UserRecord {
+  id: number
+  name: string
+  age: number
+}
+
+const UserTable = getCTable<UserRecord>()
+
+function MyPage() {
+  return (
+    <UserTable
+      dataSource={users}
+      columns={[
+        { title: '名称', dataIndex: 'name' }, // dataIndex 有类型提示
+        { title: '年龄', dataIndex: 'age' },
+      ]}
+      rowKey="id"
+    />
+  )
+}
+```
+
+## Props
+
+```typescript
+export type CTableProps<T> = SortTableProps<T> & {
+  enableDrag?: boolean
+}
+
+export type SortTableProps<T> = TableProps<T> & {
+  onSortEnd?: (event: TableDragEndEvent) => void
+  /** @deprecated 拼写兼容，后续请统一使用 onSortEnd */
+  onShortEnd?: (event: TableDragEndEvent) => void
+}
+```
+
+| 属性          | 类型                                 | 必填         | 默认值  | 说明                                     |
+| ------------- | ------------------------------------ | ------------ | ------- | ---------------------------------------- |
+| enableDrag    | `boolean`                            | 否           | `false` | 是否启用拖拽排序模式                     |
+| onSortEnd     | `(event: TableDragEndEvent) => void` | 否           | -       | 拖拽排序结束回调（仅 enableDrag 时生效） |
+| onShortEnd    | `(event: TableDragEndEvent) => void` | 否           | -       | ⚠️ 已废弃，`onSortEnd` 的拼写兼容        |
+| rowKey        | `string \| ((record: T) => string)`  | 是（拖拽时） | -       | 行唯一标识，拖拽模式下必须提供           |
+| ...tableProps | `TableProps<T>`                      | 否           | -       | 所有 antd Table 属性                     |
+
+## 导出类型
+
+```typescript
+// 拖拽事件类型（来自 @dnd-kit/core 的 DragEndEvent）
+export type TableDragEndEvent = DragEndEvent
+```
+
+## 子组件
+
+| 子组件              | 说明                                                   |
+| ------------------- | ------------------------------------------------------ |
+| `CTable.Column`     | antd Table.Column，用于 JSX 声明列                     |
+| `CTable.DragHandle` | 拖拽手柄按钮，渲染 HolderOutlined 图标，`cursor: move` |
+
+### CTable.DragHandle
+
+拖拽手柄组件，无需传入 Props，自动从 DraggableRow 上下文获取拖拽监听器。只能在 `enableDrag` 模式下的列 `render` 中使用。
+
+```tsx
+{
+  title: '排序',
+  width: 60,
+  render: () => <CTable.DragHandle />,
+}
+```
+
+## 工厂函数
+
+### getCTable\<T\>()
+
+返回带有泛型的 CTable 组件，包含 `Column` 和 `DragHandle` 子组件：
+
+```typescript
+function getCTable<T extends object>(): FC<CTableProps<T>> & {
+  Column: FC<ColumnProps<T>>
+  DragHandle: typeof DragHandle
+  [key: string]: any
+}
+```
+
+## 常见陷阱
+
+- ❌ 开启 `enableDrag` 但未提供 `rowKey`——拖拽排序依赖 rowKey 生成排序标识：
+  ```tsx
+  <CTable enableDrag dataSource={data} columns={columns} />
+  // 运行时错误：无法识别拖拽行
+  ```
+- ✅ 拖拽模式下必须提供 `rowKey`：
+
+  ```tsx
+  <CTable enableDrag dataSource={data} columns={columns} rowKey="id" />
+  ```
+
+- ❌ 使用 `onShortEnd` 回调——这是一个拼写错误的遗留 API，已被标记为 `@deprecated`
+- ✅ 使用 `onSortEnd` 替代
+
+- ❌ 在非 `enableDrag` 模式下使用 `CTable.DragHandle`——手柄依赖 DraggableRow 上下文
+- ✅ `DragHandle` 仅在 `enableDrag={true}` 时使用
+
+- ❌ 拖拽模式下忘记用 `arrayMove` 等工具重排数据——`onSortEnd` 只提供事件，不会自动修改 dataSource
+- ✅ 在 `onSortEnd` 中手动更新 dataSource 顺序
+
+- ❌ 在组件函数体内调用 `getCTable`，每次 render 创建新实例导致闪烁：
+  ```tsx
+  function MyComponent() {
+    const TypedTable = getCTable<ItemType>() // ❌ 每次 render 都重建
+    return <TypedTable ... />
+  }
+  ```
+- ✅ 在模块顶层调用，或直接使用 `<CTable<T>>`：
+  ```tsx
+  const TypedTable = getCTable<ItemType>() // ✅ 模块顶层，只创建一次
+  function MyComponent() {
+    return <TypedTable ... />
+  }
+  // 或者直接：
+  function MyComponent() {
+    return <CTable<ItemType> ... /> // ✅ 推荐
+  }
+  ```
+
+## 使用提示
+
+> 💡 超过半数场景传 `pagination={false}` 禁用内置分页（使用外部分页组件或 Redux 分页逻辑）。
+
+> 💡 拖拽序号列常见写法：`render: (_, __, index) => <Space><CTable.DragHandle />{index + 1}</Space>`
+
+> 💡 列排序：`{ sorter: true, sortOrder: sortedInfo.order }` 配合 `onChange` 回调处理排序。
+
+## 相关组件
+
+| 场景         | 组件                  | 说明                         |
+| ------------ | --------------------- | ---------------------------- |
+| 通用表格配置 | `getCommonTableProps` | 提供预设的表格公共 Props     |
+| 搜索列表     | `SearchList`          | 集成搜索表单和分页的列表组件 |

package/skills/references/CVideo.md

@@ -0,0 +1,94 @@
+# CVideo
+
+> 视频播放器组件，基于 video.js 封装，支持 MP4 和 HLS (m3u8) 格式，附带弹窗播放高阶组件。
+
+## 导入
+
+```tsx
+import { CVideo, WithCVideoModal } from '@xfe-repo/web-components'
+```
+
+## 基本用法
+
+```tsx
+import { CVideo } from '@xfe-repo/web-components'
+
+function VideoPlayer() {
+  return <CVideo src="https://example.com/video.mp4" width={640} height={360} />
+}
+```
+
+## 进阶用法
+
+### 弹窗播放
+
+使用 `WithCVideoModal` 包裹触发元素，点击后弹窗播放视频。
+
+```tsx
+import { WithCVideoModal } from '@xfe-repo/web-components'
+import { Button } from 'antd'
+
+function VideoPreview() {
+  return (
+    <WithCVideoModal videoSrc="https://example.com/video.mp4" title="视频预览" width={640} height={360}>
+      <Button>播放视频</Button>
+    </WithCVideoModal>
+  )
+}
+```
+
+### 播放 HLS 流
+
+```tsx
+<CVideo src="https://example.com/stream.m3u8" />
+```
+
+## Props
+
+### CVideoProps
+
+```typescript
+interface CVideoProps {
+  src: string
+  width?: number
+  height?: number
+}
+```
+
+| 属性   | 类型     | 必填 | 默认值 | 说明                         |
+| ------ | -------- | ---- | ------ | ---------------------------- |
+| src    | `string` | 是   | -      | 视频地址，支持 .mp4 和 .m3u8 |
+| width  | `number` | 否   | `320`  | 播放器宽度                   |
+| height | `number` | 否   | `320`  | 播放器高度                   |
+
+### WithCVideoModalProps
+
+```typescript
+interface WithCVideoModalProps {
+  children: ReactElement
+  videoSrc: string
+  title?: string
+  width?: number
+  height?: number
+}
+```
+
+| 属性     | 类型           | 必填 | 默认值       | 说明                         |
+| -------- | -------------- | ---- | ------------ | ---------------------------- |
+| children | `ReactElement` | 是   | -            | 触发元素，点击后打开视频弹窗 |
+| videoSrc | `string`       | 是   | -            | 视频地址                     |
+| title    | `string`       | 否   | `'视频切片'` | 弹窗标题                     |
+| width    | `number`       | 否   | `480`        | 视频播放器宽度               |
+| height   | `number`       | 否   | `320`        | 视频播放器高度               |
+
+## 常见陷阱
+
+- ❌ `src` 为空字符串时，组件会显示 "请检查视频地址" 文本而非空白
+- ✅ 在传入前判断 src 是否有效，避免展示提示文本
+
+## 相关组件
+
+| 场景     | 组件        | 说明                                    |
+| -------- | ----------- | --------------------------------------- |
+| 弹窗容器 | `WithModal` | WithCVideoModal 内部基于 WithModal 实现 |
+| 图片展示 | `OSSImage`  | 图片场景使用 OSSImage                   |

package/skills/references/Clock.md

@@ -0,0 +1,53 @@
+# Clock
+
+> 实时时钟组件，每秒更新一次，支持自定义格式化字符串。
+
+## 导入
+
+```tsx
+import { Clock, formatClock } from '@xfe-repo/web-components'
+import type { ClockProps } from '@xfe-repo/web-components'
+```
+
+## 基本用法
+
+```tsx
+import { Clock } from '@xfe-repo/web-components'
+
+function Header() {
+  return <Clock />  {/* 输出：3月15日 14:30:05 */}
+}
+```
+
+## 进阶用法
+
+### 自定义格式
+
+```tsx
+<Clock formatStr="HH:MM:SS" />         {/* 14:30:05 */}
+<Clock formatStr="mm/DD HH:MM" />      {/* 3/15 14:30 */}
+```
+
+## Props
+
+```typescript
+export interface ClockProps {
+  formatStr?: string
+  className?: string
+}
+```
+
+| 属性      | 类型     | 必填 | 默认值                | 说明                                     |
+| --------- | -------- | ---- | --------------------- | ---------------------------------------- |
+| formatStr | `string` | 否   | `'mm月DD日 HH:MM:SS'` | 格式化字符串，支持 mm/DD/HH/MM/SS 占位符 |
+| className | `string` | 否   | -                     | 自定义 className                         |
+
+## 导出类型
+
+### formatClock
+
+```typescript
+export const formatClock: (date: Date, formatStr?: string) => string
+```
+
+独立的格式化函数，可在非组件场景使用。