@xfe-repo/web-components 1.6.2 → 1.7.1

package/skills/xfe-web-components/references/WithModal.md

@@ -0,0 +1,328 @@
+# WithModal
+
+> 高阶弹窗组件，将触发元素和 Modal 弹窗封装为一体，点击触发元素自动打开弹窗，支持异步确认和关闭拦截。
+
+## 导入
+
+```tsx
+import { WithModal } from '@xfe-repo/web-components'
+import type { WithModalProps } from '@xfe-repo/web-components'
+```
+
+## 基本用法
+
+```tsx
+import { WithModal } from '@xfe-repo/web-components'
+import { Button } from 'antd'
+
+function MyPage() {
+  return (
+    <WithModal
+      title="编辑信息"
+      handleElement={<Button type="primary">打开弹窗</Button>}
+      onOk={async () => {
+        await saveData()
+        // 返回 void 或 true 则关闭弹窗
+      }}
+    >
+      <p>弹窗内容</p>
+    </WithModal>
+  )
+}
+```
+
+### 标准业务模式
+
+业务代码中最常用的模式 — modalProps 解构 + Form 三件套：
+
+```tsx
+import { WithModal } from '@xfe-repo/web-components'
+import { Form, Input, message } from 'antd'
+
+function EditUserModal({ children, userId }) {
+  const [form] = Form.useForm()
+
+  const handleSave = async () => {
+    const values = await form.validateFields()
+    await updateUser(userId, values)
+    message.success('保存成功')
+  }
+
+  const handleClose = () => {
+    form.resetFields()
+  }
+
+  return (
+    <WithModal title="编辑用户" style={{ minWidth: 500 }} handleElement={children} onSave={handleSave} onClose={handleClose}>
+      <Form form={form} labelCol={{ span: 5 }}>
+        <Form.Item name="name" label="姓名" rules={[{ required: true }]}>
+          <Input />
+        </Form.Item>
+        <Form.Item name="email" label="邮箱">
+          <Input />
+        </Form.Item>
+      </Form>
+    </WithModal>
+  )
+}
+
+// 使用方式：children 作为触发元素
+;<EditUserModal userId={record.id}>
+  <Button type="link">编辑</Button>
+</EditUserModal>
+```
+
+> 💡 **三件套标准流程**：`form.validateFields()` 校验 → API 提交 → `form.resetFields()` 清理。`resetFields` 必须在 `onClose` 中调用，否则再次打开弹窗时会残留上次数据。
+
+> 💡 **宽度设置**：88% 使用 `style={{ minWidth: N }}` 而非固定 `width`，常见值为 350/500/640/800/1280。使用 `minWidth` 允许内容撑开弹窗。
+
+## 进阶用法
+
+### 异步保存 + 阻止关闭
+
+`onOk`/`onSave` 返回 `false` 可阻止弹窗关闭（如表单校验失败），异步执行期间自动显示 loading。
+
+```tsx
+<WithModal
+  title="提交表单"
+  handleElement={<Button>提交</Button>}
+  onOk={async () => {
+    const valid = await form.validateFields().catch(() => false)
+    if (!valid) return false // 校验失败，阻止关闭
+
+    await submitForm()
+    message.success('提交成功')
+    // 返回 void，自动关闭弹窗
+  }}
+  onCancel={async () => {
+    if (hasUnsavedChanges) {
+      const confirmed = await confirmDiscard()
+      if (!confirmed) return false // 阻止关闭
+    }
+    // 返回 void，允许关闭
+  }}
+>
+  <Form form={form}>...</Form>
+</WithModal>
+```
+
+### 监听弹窗显隐
+
+```tsx
+<WithModal
+  title="详情"
+  handleElement={<a>查看详情</a>}
+  onVisibleChange={(visible) => {
+    if (visible) {
+      // 弹窗打开时加载数据
+      fetchDetail()
+    }
+  }}
+>
+  <DetailContent />
+</WithModal>
+```
+
+### 隐藏底部按钮
+
+```tsx
+<WithModal title="预览" handleElement={<Button>预览</Button>} showFooter={false}>
+  <ImagePreview />
+</WithModal>
+```
+
+### 受控模式（外部控制显隐）
+
+```tsx
+const [visible, setVisible] = useState(false)
+
+<WithModal
+  title="弹窗"
+  visible={visible}
+  handleElement={<Button onClick={() => setVisible(true)}>打开</Button>}
+  onCancel={() => setVisible(false)}
+>
+  <Content />
+</WithModal>
+```
+
+### 触发元素的点击拦截
+
+`handleElement` 的原始 `onClick` 若返回 `false`，则不会打开弹窗：
+
+```tsx
+<WithModal
+  title="确认"
+  handleElement={
+    <Button
+      onClick={async () => {
+        const canOpen = await checkPermission()
+        if (!canOpen) return false // 阻止弹窗打开
+      }}
+    >
+      需要权限
+    </Button>
+  }
+>
+  <Content />
+</WithModal>
+```
+
+### With{Action}Modal 封装范式
+
+推荐将每个弹窗操作封装为独立组件，统一接口为 `children + 业务props`：
+
+```tsx
+// WithEditModal.tsx
+interface WithEditModalProps {
+  children: ReactElement
+  recordId: string
+  onSuccess?: () => void
+}
+
+const WithEditModal = memo(({ children, recordId, onSuccess }: WithEditModalProps) => {
+  const [form] = Form.useForm()
+  const loading = useSelector(selectUpdateLoading)
+
+  const handleSave = async () => {
+    const values = await form.validateFields()
+    await dispatch(effectUpdate({ id: recordId, ...values }))
+    onSuccess?.()
+  }
+
+  return (
+    <WithModal
+      title="编辑"
+      handleElement={children}
+      onSave={handleSave}
+      onClose={() => form.resetFields()}
+      loading={loading}
+      style={{ minWidth: 500 }}
+    >
+      <Form form={form} labelCol={{ span: 5 }}>
+        {/* 表单内容 */}
+      </Form>
+    </WithModal>
+  )
+})
+```
+
+### 纯展示弹窗
+
+仅展示数据、无保存操作的弹窗：
+
+```tsx
+<WithModal title="订单详情" handleElement={<Button type="link">查看</Button>} showFooter={false}>
+  <Descriptions column={2}>
+    <Descriptions.Item label="订单号">{data.orderNo}</Descriptions.Item>
+    <Descriptions.Item label="金额">
+      <Currency>{data.amount}</Currency>
+    </Descriptions.Item>
+  </Descriptions>
+</WithModal>
+```
+
+### 关于 destroyOnClose
+
+WithModal 底层使用 antd Modal，默认 **不会** 在关闭时销毁子组件。如果忘记在 `onClose` 中调用 `form.resetFields()`，表单状态会泄漏到下次打开。
+
+建议：始终在 `onClose` 中调用 `form.resetFields()` 进行清理。
+
+## Props
+
+```typescript
+export type WithModalProps = Omit<ModalProps, 'onOk' | 'onCancel' | 'confirmLoading'> & {
+  visible?: boolean
+  handleElement: ReactElement
+  activeClassName?: string
+  children?: ReactNode
+  loading?: boolean
+  showFooter?: boolean
+  onSave?: () => Promise<boolean | void> | boolean | void
+  onVisibleChange?: (visible?: boolean) => Promise<boolean | void> | boolean | void
+  onClose?: () => Promise<boolean | void> | boolean | void
+  onOk?: () => Promise<boolean | void> | boolean | void
+  onCancel?: () => Promise<boolean | void> | boolean | void
+}
+```
+
+| 属性            | 类型                                                | 必填 | 默认值 | 说明                                                    |
+| --------------- | --------------------------------------------------- | ---- | ------ | ------------------------------------------------------- |
+| handleElement   | `ReactElement`                                      | 是   | -      | 触发元素，点击后打开弹窗                                |
+| visible         | `boolean`                                           | 否   | -      | 受控显隐状态（也接受 antd 的 `open`）                   |
+| showFooter      | `boolean`                                           | 否   | `true` | 是否显示底部按钮栏                                      |
+| loading         | `boolean`                                           | 否   | -      | 外部控制确认按钮 loading 状态                           |
+| activeClassName | `string`                                            | 否   | -      | 弹窗打开时附加到 handleElement 的 className             |
+| onOk            | `() => Promise<boolean \| void> \| boolean \| void` | 否   | -      | 点击确认回调，返回 `false` 阻止关闭                     |
+| onSave          | 同 onOk                                             | 否   | -      | `onOk` 的别名，两者都传时 `onOk` 优先                   |
+| onCancel        | `() => Promise<boolean \| void> \| boolean \| void` | 否   | -      | 点击取消回调，返回 `false` 阻止关闭                     |
+| onClose         | 同 onCancel                                         | 否   | -      | `onCancel` 的别名，两者都传时 `onCancel` 优先           |
+| onVisibleChange | `(visible?: boolean) => void`                       | 否   | -      | 弹窗显隐变化回调                                        |
+| children        | `ReactNode`                                         | 否   | -      | 弹窗内容                                                |
+| ...modalProps   | `ModalProps`                                        | 否   | -      | 其他 antd Modal 属性（title、width、destroyOnClose 等） |
+
+### 回调优先级
+
+| 场景     | 优先使用   | 备选      |
+| -------- | ---------- | --------- |
+| 确认操作 | `onOk`     | `onSave`  |
+| 取消操作 | `onCancel` | `onClose` |
+
+## 常见陷阱
+
+- ❌ 同时使用 `visible` 受控模式和依赖 handleElement 的内部状态管理：
+  ```tsx
+  // visible 外部状态和内部 show 状态冲突，弹窗行为不可预测
+  <WithModal visible={myVisible} handleElement={<Button>打开</Button>}>
+  ```
+- ✅ 受控模式下在 `onCancel` 中同步更新外部状态：
+
+  ```tsx
+  <WithModal
+    visible={myVisible}
+    handleElement={<Button onClick={() => setMyVisible(true)}>打开</Button>}
+    onCancel={() => setMyVisible(false)}
+  >
+  ```
+
+- ❌ `onOk` 回调中抛出异常但不处理 —— 组件会 catch 异常并阻止关闭（当作返回 `false`）：
+  ```tsx
+  onOk={async () => {
+    await api.save()  // 如果抛出异常，弹窗不会关闭
+  }}
+  ```
+- ✅ 在回调中自行处理错误：
+
+  ```tsx
+  onOk={async () => {
+    try {
+      await api.save()
+    } catch (e) {
+      message.error('保存失败')
+      return false  // 显式阻止关闭
+    }
+  }}
+  ```
+
+- ❌ 关闭弹窗后不清理表单状态，再次打开时残留旧数据：
+  ```tsx
+  <WithModal onClose={() => { /* 什么都不做 */ }}>
+  ```
+- ✅ 在 onClose 中调用 resetFields 清理：
+
+  ```tsx
+  <WithModal onClose={() => form.resetFields()}>
+  ```
+
+- ❌ 把 `confirmLoading` 传给 WithModal —— 该属性已被 Omit，不生效
+- ✅ 使用 `loading` 属性或让 onOk 的 async 自动管理 loading 状态
+
+- 💡 复杂表单弹窗建议传 `maskClosable={false}`，防止用户误点遮罩关闭导致数据丢失。
+
+## 相关组件
+
+| 场景           | 组件                    | 说明                     |
+| -------------- | ----------------------- | ------------------------ |
+| 弹窗内上传     | `EffectFileUpload`      | 在弹窗中使用文件上传     |
+| 弹窗内表单     | `EffectCategoryCascade` | 在弹窗中使用分类选择     |
+| 弹窗内范围选择 | `EffectScopeSelect`     | 在弹窗中使用商品范围选择 |

package/skills/xfe-web-components/references/WithPanel.md

@@ -0,0 +1,307 @@
+# WithPanel
+
+> 高阶侧边栏组件，将触发元素和 Drawer 抽屉封装为一体，点击触发元素自动打开面板，支持异步确认和关闭拦截。与 WithModal 设计对称。
+
+## 导入
+
+```tsx
+import { WithPanel } from '@xfe-repo/web-components'
+import type { WithPanelProps } from '@xfe-repo/web-components'
+```
+
+## 基本用法
+
+```tsx
+import { WithPanel } from '@xfe-repo/web-components'
+import { Button } from 'antd'
+
+function MyPage() {
+  return (
+    <WithPanel
+      title="编辑信息"
+      handleElement={<Button type="primary">打开面板</Button>}
+      onOk={async () => {
+        await saveData()
+        // 返回 void 或 true 则关闭面板
+      }}
+    >
+      <p>面板内容</p>
+    </WithPanel>
+  )
+}
+```
+
+### 选择面板模式
+
+最常见的使用模式 — 构建一个带搜索和多选的数据选择面板：
+
+```tsx
+import { WithPanel } from '@xfe-repo/web-components'
+import { CTable } from '@xfe-repo/web-components'
+import { Form, Input, Button } from 'antd'
+
+function SelectProductPanel({ children, onSelect }) {
+  const [form] = Form.useForm()
+  const [selectedRows, setSelectedRows] = useState([])
+
+  const rowSelection = {
+    selectedRowKeys: selectedRows.map((r) => r.id),
+    onChange: (_, rows) => setSelectedRows(rows),
+  }
+
+  const handleConfirm = () => {
+    onSelect(selectedRows)
+  }
+
+  return (
+    <WithPanel title="选择商品" width="70%" handleElement={children} onSave={handleConfirm}>
+      <Form form={form} layout="inline" onFinish={handleSearch}>
+        <Form.Item name="keyword">
+          <Input placeholder="搜索商品" />
+        </Form.Item>
+        <Button htmlType="submit" type="primary">
+          查询
+        </Button>
+      </Form>
+      <CTable dataSource={products} rowSelection={rowSelection} rowKey="id" columns={columns} pagination={false} />
+    </WithPanel>
+  )
+}
+
+// 使用
+;<SelectProductPanel onSelect={handleProductSelect}>
+  <Button>选择商品</Button>
+</SelectProductPanel>
+```
+
+## 进阶用法
+
+### 异步保存 + 阻止关闭
+
+`onOk`/`onSave` 返回 `false` 可阻止面板关闭（如表单校验失败），异步执行期间自动显示 loading。
+
+```tsx
+<WithPanel
+  title="提交表单"
+  handleElement={<Button>提交</Button>}
+  onOk={async () => {
+    const valid = await form.validateFields().catch(() => false)
+    if (!valid) return false // 校验失败，阻止关闭
+
+    await submitForm()
+    message.success('提交成功')
+    // 返回 void，自动关闭面板
+  }}
+  onCancel={async () => {
+    if (hasUnsavedChanges) {
+      const confirmed = await confirmDiscard()
+      if (!confirmed) return false // 阻止关闭
+    }
+    // 返回 void，允许关闭
+  }}
+>
+  <Form form={form}>...</Form>
+</WithPanel>
+```
+
+### 隐藏底部按钮
+
+```tsx
+<WithPanel title="预览" handleElement={<Button>预览</Button>} showFooter={false}>
+  <ImagePreview />
+</WithPanel>
+```
+
+### 受控模式（外部控制显隐）
+
+```tsx
+const [visible, setVisible] = useState(false)
+
+<WithPanel
+  title="面板"
+  open={visible}
+  handleElement={<Button onClick={() => setVisible(true)}>打开</Button>}
+  onCancel={() => setVisible(false)}
+>
+  <Content />
+</WithPanel>
+```
+
+### 触发元素的点击拦截
+
+`handleElement` 的原始 `onClick` 若返回 `false`，则不会打开面板：
+
+```tsx
+<WithPanel
+  title="确认"
+  handleElement={
+    <Button
+      onClick={async () => {
+        const canOpen = await checkPermission()
+        if (!canOpen) return false // 阻止面板打开
+      }}
+    >
+      需要权限
+    </Button>
+  }
+>
+  <Content />
+</WithPanel>
+```
+
+### 受控模式（cloneElement 注入）
+
+通过 cloneElement 将 onClick 注入到触发元素：
+
+```tsx
+const [visible, setVisible] = useState(false)
+
+<WithPanel
+  title="选择商品"
+  open={visible}
+  onClose={() => setVisible(false)}
+  handleElement={React.cloneElement(children, { onClick: () => setVisible(true) })}
+>
+  {/* 面板内容 */}
+</WithPanel>
+```
+
+### 旧版 API 与新版 API
+
+组件同时兼容旧版（`visible`/`onSave`/`onClose`/`submitText`）和新版（`open`/`onOk`/`onCancel`/`okText`）API。使用旧版 API 时，`width` 默认 `'50%'`，`maskClosable` 默认 `false`；使用新版 API 时，`width` 默认 `'100%'`，`maskClosable` 使用 Drawer 默认值。
+
+```tsx
+// 旧版 API（兼容保留）
+<WithPanel
+  visible={show}
+  submitText="保存"
+  handleElement={<Button>打开</Button>}
+  onSave={handleSave}
+  onClose={handleClose}
+>
+  ...
+</WithPanel>
+
+// 新版 API（推荐）
+<WithPanel
+  open={show}
+  okText="保存"
+  handleElement={<Button>打开</Button>}
+  onOk={handleSave}
+  onCancel={handleClose}
+>
+  ...
+</WithPanel>
+```
+
+## Props
+
+```typescript
+export type WithPanelProps = Omit<DrawerProps, 'footer' | 'onClose'> & {
+  visible?: boolean
+  handleElement: ReactElement
+  activeClassName?: string
+  children?: ReactNode
+  submitText?: string
+  okText?: string
+  cancelText?: string
+  loading?: boolean
+  showFooter?: boolean
+  onSave?: () => Promise<boolean | void> | boolean | void
+  onClose?: () => Promise<boolean | void> | boolean | void
+  onOk?: () => Promise<boolean | void> | boolean | void
+  onCancel?: () => Promise<boolean | void> | boolean | void
+}
+```
+
+| 属性            | 类型                                                | 必填 | 默认值                           | 说明                                                         |
+| --------------- | --------------------------------------------------- | ---- | -------------------------------- | ------------------------------------------------------------ |
+| handleElement   | `ReactElement`                                      | 是   | -                                | 触发元素，点击后打开面板                                     |
+| visible         | `boolean`                                           | 否   | -                                | 受控显隐状态（旧版 API，也可使用 `open`）                    |
+| open            | `boolean`                                           | 否   | -                                | 受控显隐状态（新版 API，优先级高于 `visible`）               |
+| showFooter      | `boolean`                                           | 否   | `true`                           | 是否显示底部按钮栏                                           |
+| loading         | `boolean`                                           | 否   | -                                | 外部控制确认按钮 loading 状态                                |
+| activeClassName | `string`                                            | 否   | -                                | 面板打开时附加到 handleElement 的 className                  |
+| okText          | `string`                                            | 否   | `'确定'`                         | 确认按钮文本（优先于 submitText）                            |
+| submitText      | `string`                                            | 否   | -                                | 确认按钮文本（旧版 API，被 okText 覆盖）                     |
+| cancelText      | `string`                                            | 否   | `'取消'`                         | 取消按钮文本                                                 |
+| width           | `string \| number`                                  | 否   | 旧版 `'50%'`，新版 `'100%'`      | 面板宽度                                                     |
+| maskClosable    | `boolean`                                           | 否   | 旧版 `false`，新版 Drawer 默认值 | 点击遮罩是否关闭                                             |
+| onOk            | `() => Promise<boolean \| void> \| boolean \| void` | 否   | -                                | 点击确认回调，返回 `false` 阻止关闭                          |
+| onSave          | 同 onOk                                             | 否   | -                                | `onOk` 的别名，两者都传时 `onOk` 优先                        |
+| onCancel        | `() => Promise<boolean \| void> \| boolean \| void` | 否   | -                                | 点击取消回调，返回 `false` 阻止关闭                          |
+| onClose         | 同 onCancel                                         | 否   | -                                | `onCancel` 的别名，两者都传时 `onCancel` 优先                |
+| children        | `ReactNode`                                         | 否   | -                                | 面板内容                                                     |
+| ...drawerProps  | `DrawerProps`                                       | 否   | -                                | 其他 antd Drawer 属性（title、placement、destroyOnClose 等） |
+
+### 回调优先级
+
+| 场景     | 优先使用   | 备选         |
+| -------- | ---------- | ------------ |
+| 确认操作 | `onOk`     | `onSave`     |
+| 取消操作 | `onCancel` | `onClose`    |
+| 显隐控制 | `open`     | `visible`    |
+| 按钮文本 | `okText`   | `submitText` |
+
+### 旧版 vs 新版默认值
+
+当检测到使用了旧版 API（`onSave`、`onClose`、`visible` 或 `submitText` 中任一）时：
+
+| 属性         | 旧版默认值 | 新版默认值    |
+| ------------ | ---------- | ------------- |
+| width        | `'50%'`    | `'100%'`      |
+| maskClosable | `false`    | Drawer 默认值 |
+
+## 常见陷阱
+
+- ❌ 同时使用 `visible` 受控模式和依赖 handleElement 的内部状态管理：
+  ```tsx
+  // visible/open 外部状态和内部 show 状态冲突，面板行为不可预测
+  <WithPanel visible={myVisible} handleElement={<Button>打开</Button>}>
+  ```
+- ✅ 受控模式下在 `onCancel` 中同步更新外部状态：
+
+  ```tsx
+  <WithPanel
+    open={myVisible}
+    handleElement={<Button onClick={() => setMyVisible(true)}>打开</Button>}
+    onCancel={() => setMyVisible(false)}
+  >
+  ```
+
+- ❌ `onOk` 回调中抛出异常但不处理——组件会 catch 异常并阻止关闭（当作返回 `false`）：
+  ```tsx
+  onOk={async () => {
+    await api.save()  // 如果抛出异常，面板不会关闭
+  }}
+  ```
+- ✅ 在回调中自行处理错误：
+
+  ```tsx
+  onOk={async () => {
+    try {
+      await api.save()
+    } catch (e) {
+      message.error('保存失败')
+      return false  // 显式阻止关闭
+    }
+  }}
+  ```
+
+- ❌ 不传 `onOk`/`onSave` 时期望底部出现确认按钮——确认按钮仅在 `mergedOnOk`（即 `onOk` 或 `onSave`）存在时渲染
+- ✅ 如果只需取消按钮，不传 `onOk` 即可；如果不需要任何底部按钮，使用 `showFooter={false}`
+
+- ❌ 混用旧版 API 和新版 API 导致默认值不一致
+- ✅ 统一使用新版 API（`open`/`onOk`/`onCancel`/`okText`）
+
+> 💡 可以将 props 组装为对象后展开传入：`const panelProps = { title, width, onSave }; <WithPanel {...panelProps}>`
+
+> 💡 常见 width 值：`500`、`800`（px）或 `"60%"`、`"70%"`（百分比）。
+
+## 相关组件
+
+| 场景       | 组件                    | 说明                                 |
+| ---------- | ----------------------- | ------------------------------------ |
+| 弹窗版本   | `WithModal`             | 相同设计模式，使用 Modal 而非 Drawer |
+| 面板内上传 | `EffectFileUpload`      | 在面板中使用文件上传                 |
+| 面板内表单 | `EffectCategoryCascade` | 在面板中使用分类选择                 |