@para-ui/core 5.0.0-beta.12 → 5.0.0-beta.13

package/Form/component.json

@@ -0,0 +1,161 @@
+{
+    "name": "Form",
+    "category": "Data Entry",
+    "description": "基于配置的高性能表单组件",
+    "semantic": {
+        "intent": [
+            "数据录入",
+            "数据编辑",
+            "数据校验"
+        ],
+        "useCases": [
+            "登录注册",
+            "配置设置",
+            "信息填写"
+        ],
+        "riskLevel": "high"
+    },
+    "variants": {
+        "horizontal": {
+            "meaning": "水平布局表单"
+        },
+        "vertical": {
+            "meaning": "垂直布局表单"
+        }
+    },
+    "states": [
+        "loading",
+        "submitting",
+        "error"
+    ],
+    "idealProps": {
+        "configList": {
+            "type": "configListProps",
+            "description": "表单项配置数组（`type configListProps = Array<FormItemProps>`，src/Form/index.tsx:20 已 export）。**FormItemProps 核心字段（完整见 docs/view/form/api.ts apiDataFormItemProps）**：\n• `name: string`（必填，唯一标识；onChange / backData 的 key 都对应该值）\n• `label: string | ((props: FormItemProps) => ReactNode)`（显示文案）\n• `InputType: 'default' | 'number' | 'textarea' | 'select' | 'radioGroup' | 'checkGroup' | 'switch' | 'file' | FC<ItemTypeProps>`（⚠️ 控件类型用 **InputType**，不是 type；type 是布局覆盖）\n• `defaultValue: any`（字段初始值；backData[name] 优先级更高）\n• `rules: { validate: { required?, maxlength?, minLength?, pattern?, [customKey]? }, message: { [key]: string } }`（⚠️ **注意大小写**：`maxlength` 小写 l；`minLength` 驼峰 L——src 命名不一致，写错会导致校验规则被忽略）\n• `list: Array<{label, name?|value?}>`（radioGroup/checkGroup 子项用 `name`；select 子项用 `value`）\n• `disabled: boolean`（单项禁用）\n• `hide: boolean`（隐藏该项）\n• `hideError: boolean`（隐藏该项内置 error UI）\n• `type: 'vertical' | 'horizontal'`（单项布局覆盖；与顶层 type 同名，仅控制布局，不影响控件类型）"
+        },
+        "backData": {
+            "type": "{ [name: string]: any }",
+            "description": "整表回填数据。比 configList 中每项的 defaultValue 优先级更高；切换到该新对象会刷新表单。常配合 form.refreshForm(undefined, newBackData) 实现『换数据源』场景"
+        },
+        "type": {
+            "type": "enum",
+            "values": [
+                "vertical",
+                "horizontal"
+            ],
+            "default": "horizontal",
+            "description": "**布局类型**（vertical=竖 / horizontal=横）；configList 中每项的 `type` 字段可覆盖顶层布局。⚠️ **此处 type 仅控制布局，与控件类型无关**——控件类型用 FormItemProps.`InputType`（default/select/radioGroup 等）"
+        },
+        "disabled": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否全局禁用所有 FormItem 输入控件——对所有 InputType（default/textarea/number/file/switch/select/radioGroup/checkGroup/自定义函数）都生效，FormItem 内部把顶层 disabled 透传给每项。disabled 期间用户交互被屏蔽，onChange 不触发；不影响 form.current.check / reset / clear 等命令式调用"
+        },
+        "onChange": {
+            "type": "function",
+            "signature": "(name: string, value: any) => void",
+            "description": "表单值改变回调——任意字段（任意 InputType）变化都触发。**name 参数 = 对应 configList 该项的 `name` 字段值**；value 为该字段当前值。**触发时机**：input 类等价 onInput 实时（非 onBlur）；select/radioGroup/checkGroup 在用户选中瞬时；switch 在 toggle 瞬时。**初始 backData 注入不触发 onChange**（仅用户交互或 form.current.refreshForm 才触发）。该回调不携带校验状态，需校验请用 form.current.check?.()"
+        },
+        "form": {
+            "type": "React.MutableRefObject<FormRefObject>",
+            "description": "**命令式 ref**——通过 form.current 调用 check / reset / clear / refreshForm / getValidValues 等方法。**FormRefObject 字段完整列表**（DEFECT-001/002）：check（校验，**返回 false | { [name]: any }**——失败返 false 不抛错；**成功返回的对象 key = configList 每项的 `name` 字段值**，扁平结构非嵌套）/ reset（重置到初始 backData/defaultValue）/ clear（清空全部或指定字段，签名 `(name?: string | string[]) => void`）/ items（{ [name]: ItemTypeProps }）/ values / refreshForm / refData / getValidValues（过滤 hide=true 与未通过校验的字段）。docs/view/form/api.ts 末尾 RefObject 表列出全部字段。**5.x 仅整表 check，无 checkField(name) 单字段校验 API**——逐字段实时校验需在父组件用 onChange 桥接 + 业务方复刻 validate 逻辑。**FormRefObject 已公开 export**（Form-DEFECT-001 起），通过 `import { FormRefObject } from '@para-ui/core'` 或 `import { FormRefObject } from '@para-ui/core/Form'` 获取精确类型；推荐声明：`const formRef = useRef<FormRefObject>({} as FormRefObject)`"
+        },
+        "getCheckForm": {
+            "type": "function",
+            "signature": "(checkFrom: Function) => void",
+            "description": "**与 form ref 是同一能力的双通路（DEFECT-005）**。回调式：组件挂载后调用 getCheckForm(check) 把 check 函数交给父组件。**推荐统一用 form ref**——getCheckForm 是历史回调式 API"
+        },
+        "getForcedRefresh": {
+            "type": "function",
+            "signature": "(setConfigHook: (configList: configListProps, bData?: { [name: string]: any }) => void) => void",
+            "description": "强制刷新配置回调（src/Form/index.tsx:96-102 interface 实证）：组件挂载后将内部 setConfig 方法交给父组件；父组件可通过 setConfigHook(newConfigList, newBackData) 命令式刷新整个表单结构和回填数据。⚠️ **推荐改用 form ref.refreshForm**——getForcedRefresh 是历史 API，与 form ref 功能重叠"
+        },
+        "disOnlySpace": {
+            "type": "boolean",
+            "description": "是否禁止纯空格提交（src/Form/index.tsx:111 interface 实证）：true 时 rules.validate.required + 纯空格内容也会校验失败"
+        },
+        "className": {
+            "type": "string",
+            "description": "表单容器自定义类名（src/Form/index.tsx:122 interface 实证）"
+        },
+        "labelWidth": {
+            "type": "number",
+            "description": "Label 区块宽度，仅在顶层 type='vertical' 时生效（src/Form/index.tsx:131 interface 实证）"
+        }
+    },
+    "do": [
+        "使用 configList 进行配置化开发以减少模版代码",
+        "利用 form ref 进行手动校验和数据获取（推荐 form 单一通路而非 getCheckForm 双通路）",
+        "提交场景：`const values = formRef.current.check?.(); if (!values) return; submit(values);`——check 校验失败返 false，不抛错",
+        "重置场景：调用 form.current.reset?.() 而非 refreshForm(schema, {})（DEFECT-002 reset 是真实存在的 API）",
+        "FormItem 字段默认值用 FormItemProps.defaultValue（DEFECT-003 已实现，docs api.ts apiDataFormItemProps 已补）",
+        "**FormItemProps.list 子项 key 命名按 InputType 选用**（DEFECT-008 + src 实证）：radioGroup / checkGroup 用 `{ label, name }`（用户选中产生的值 = name）；select 用 `{ label, value }`（用户选中产生的值 = value）",
+        "**rules.validate 合法 key**（src/FormItem/index.tsx:54-60 实证）：`required` / **`maxlength`**（小写 L）/ **`minLength`**（驼峰 L，与 maxlength 命名不一致是 src 现状）/ `pattern` / `disOnlySpace` / 任意自定义 key（值为 `(item, val) => boolean | string`）。message 中 key 与 validate key 一一对应",
+        "需要把同步 `check()` 包成 Promise 时：`async () => { const v = formRef.current.check?.(); return v || null; }`——失败返 null 而非 reject，避免业务方两套错误处理（参见 codeString.ts asyncCheckDemo）",
+        "需要逐字段实时校验：用顶层 onChange 桥接（任意字段变化都触发）+ 业务方在父组件复刻一份 validate 逻辑——5.x 没有 checkField(name) 单字段校验 API",
+        "需要父组件接管错误显示（服务端 / 异步校验）：更新 configList 对应项的 `errorMessage` 字段注入自定义错误文案（FormItem 优先展示此值，check() 内部错误被覆盖）；清除时传 `errorMessage: ''` 或 `undefined`。若需彻底隐藏内置 error UI 改用外部渲染，则配合 `hideError: true` + 父组件自定义 UI（议题 discussions/Form-error-takeover.md）"
+    ],
+    "dont": [
+        "在 render 中动态改变 configList 结构（应保持引用稳定）",
+        "混用受控和非受控模式",
+        "不要假设 check() 失败抛异常或返回 undefined——失败时返回 false（DEFECT-006）",
+        "不要既传 form 又传 getCheckForm 混用双通路（DEFECT-005）——选 form 即可",
+        "**不要在 select 子项里用 `{ label, name }`**——select 内部读 `value` 字段，用 name 会导致选中后 onChange 不传值；checkGroup/radioGroup 反过来要用 name 不能用 value（DEFECT-008 + src 实证）",
+        "**不要在 rules.validate 中把 maxlength 写成 maxLength（驼峰 L）或把 minLength 写成 minlength（小写 L）**——src 字段名严格匹配，写错会导致校验规则被忽略；不一致是 src 现状",
+        "不要假设 onChange 触发时携带校验状态——onChange 仅传 (name, value)，校验状态需主动调 form.current.check?.()",
+        "不要假设初始 backData 注入触发 onChange——src 实证仅用户交互或 form.current.refreshForm 触发"
+    ],
+    "events": {
+        "onChange": {
+            "signature": "(name: string, value: any) => void",
+            "asyncSupported": false,
+            "examples": [
+                "任意 FormItem 字段值变化时触发，name 是 configList 该项的 name 字段值",
+                "input 类等价 onInput 实时触发，select/radioGroup 在选中瞬时，switch 在 toggle 瞬时",
+                "桥接逐字段实时校验：拿到 (name, value) 后调 formRef.current.check?.() 触发整表校验"
+            ],
+            "commonMistakes": [
+                "假设回调签名是 (e, value) 类似 antd → 实际只有 (name, value) 两个参数",
+                "在 onChange 里直接做副作用而不通过 setState（破坏受控模式）",
+                "假设初始 backData 注入会触发 onChange → 不会，仅用户交互或 refreshForm 触发",
+                "假设 onChange 携带校验状态 → 不携带，需主动调 check?.()"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "FormRefObject 必须显式声明类型，否则 ref.current 推断为 unknown",
+            "wrong": "const formRef = useRef(null); formRef.current.check();  // 报 unknown 类型错",
+            "right": "import { FormRefObject } from '@para-ui/core'; const formRef = useRef<FormRefObject>({} as FormRefObject);"
+        },
+        {
+            "issue": "FormItem 控件类型字段叫 InputType 不是 type（type 是布局覆盖）",
+            "wrong": "configList: [{ name: 'age', label: '年龄', type: 'number' }]  // type 在这里是布局,不是控件",
+            "right": "configList: [{ name: 'age', label: '年龄', InputType: 'number' }]"
+        },
+        {
+            "issue": "rules.validate 字段名大小写不一致（src 现状）",
+            "wrong": "rules: { validate: { maxLength: 10, minlength: 2 } }  // 写错被忽略",
+            "right": "rules: { validate: { maxlength: 10, minLength: 2 } }  // 注意：maxlength 小写 L，minLength 驼峰 L"
+        },
+        {
+            "issue": "list 子项的 key 名称按 InputType 选用",
+            "wrong": "InputType: 'select', list: [{ label: 'A', name: 'a' }]  // select 读 value,name 被忽略",
+            "right": "InputType: 'select' → list: [{ label: 'A', value: 'a' }] // radioGroup/checkGroup 反过来用 name"
+        },
+        {
+            "issue": "check() 返回类型是 false | object,不是 boolean 也不抛异常",
+            "wrong": "const ok = formRef.current.check?.(); if (!ok) throw new Error('fail');  // ok 是 false | object",
+            "right": "const values = formRef.current.check?.(); if (!values) return; submit(values);  // false 表失败,object 表成功并含字段值"
+        },
+        {
+            "issue": "configList 不接受 undefined (TS2345),空状态用 '' 或 []",
+            "wrong": "<Form configList={someUndefined} />  // 触发 TS2345: Argument of type 'undefined' is not assignable to '\"\" | FormItemProps[]'",
+            "right": "<Form configList={someValue || []} />  // 或 configList=''"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Form",
+        "adapter": null
+    }
+}

package/FormItem/component.json

@@ -0,0 +1,171 @@
+{
+    "name": "FormItem",
+    "category": "Data Entry",
+    "description": "表单项,通常作 FieldForm 子组件使用,形成\"校验/收集值/提交\"链路。可独立用但脱离 FieldForm 时不会自动校验。需 FormItem 自渲染控件请用 InputType prop。",
+    "semantic": {
+        "intent": [
+            "字段包装",
+            "表单控制"
+        ],
+        "useCases": [
+            "表单字段",
+            "校验绑定",
+            "布局控制"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "default": {
+            "meaning": "默认样式"
+        }
+    },
+    "states": [
+        "default",
+        "error",
+        "validating"
+    ],
+    "idealProps": {
+        "name": {
+            "type": "string",
+            "description": "字段名（**仅 string，不支持 array 路径写法**）。需在 Form/FieldForm 上下文中保持唯一；不要传 `['user','address','city']`——会触发 TS2322。\n\n**字符串点路径协议**：`name` 可以写成 `'user.address.city'` 形式（TS 合法，不报错），但 FormItem 和 Form 均**不解析点路径**——表单聚合值是 `{ 'user.address.city': value }`（扁平 key，含字面量点），而**不是** `{ user: { address: { city: value } } }`（深度嵌套对象）。点路径字段可以正常传值、校验、回填，仅聚合 key 保持原字符串。这与 antd / rc-field-form 的 `name=['a','b','c']` 深度路径解析行为**不同**——本组件不做路径解析，只做 key 直传。若业务提交需要深度嵌套对象，在提交前自行将扁平结果转换（如 `{ 'user.address.city': 'Beijing' }` → `{ user: { address: { city: 'Beijing' } } }`），或改用 `FieldForm.Item`（支持 `name={['user','address','city']}` 数组路径）。"
+        },
+        "label": {
+            "type": "string | (props: FormItemProps) => ReactNode",
+            "description": "标签文案；可传字符串或函数式渲染。**不支持 null**——传 label={null} 会触发 TS2322。要『无 label』请使用 hideLabel。"
+        },
+        "hideLabel": {
+            "type": "boolean",
+            "default": false,
+            "description": "隐藏 label 区块（连同 label 占位一起去掉）。这是『无 label 字段』的正确写法。"
+        },
+        "rules": {
+            "type": "ruleType",
+            "description": "校验规则。**这是单个对象不是数组**（与 antd 的 rules: Rule[] 不同）。结构为 `{ validate: { required, maxlength, minLength, pattern, min, max, disOnlySpace, [自定义key]: fn }, message?: { required: '...', pattern: '...' } }`。 message 与 validate 中的 key 一一对应。校验函数签名 `(item, val, intl) => true | string`：返回 true 表示通过、返回字符串表示报错文案。**⚠️ 重要：脱离 FieldForm 独立使用时，rules 不会自动触发校验**——rules 仅渲染必填红星等视觉提示，required/pattern 等不会在 children 失焦/变更时执行；完整校验链路必须配合 FieldForm 上下文。"
+        },
+        "InputType": {
+            "type": "'default' | 'select' | 'switch' | 'textarea' | 'number' | 'file' | 'radioGroup' | 'checkGroup' | 'comboSelect' | ReactNode | FC",
+            "description": "FormItem 自动渲染输入控件的类型；不传 children 时按此类型渲染对应 paraui 组件。传 children 时 InputType 不生效（外部受控）。"
+        },
+        "inputProps": {
+            "type": "Record<string, any>",
+            "description": "InputType 渲染的内部控件透传 props（如 placeholder、options 等）。"
+        },
+        "type": {
+            "type": "'horizontal' | 'vertical'",
+            "values": [
+                "horizontal",
+                "vertical"
+            ],
+            "default": "'horizontal'",
+            "description": "label 与表单项的横纵布局。"
+        },
+        "labelWidth": {
+            "type": "number",
+            "description": "label 区块宽度（仅 type='vertical' 时生效）。"
+        },
+        "tips": {
+            "type": "string",
+            "description": "label 旁的 tooltip 提示文案。"
+        },
+        "hideError": {
+            "type": "boolean",
+            "default": false,
+            "description": "隐藏校验错误提示（不影响校验逻辑本身）。"
+        },
+        "defaultValue": {
+            "type": "any",
+            "description": "默认值。会被 FieldForm 的回填数据 backData 覆盖。"
+        },
+        "disabled": {
+            "type": "boolean",
+            "description": "InputType 渲染的控件是否禁用（仅自动渲染场景生效）。"
+        },
+        "change": {
+            "type": "(value: any) => void",
+            "description": "值变化回调（仅 InputType 自动渲染场景由内部 ItemType 触发；外部 children 受控时不会自动触发——需自己监听）。"
+        },
+        "children": {
+            "type": "ReactNode",
+            "description": "自定义渲染输入控件——FormItem **不会自动注入 value/onChange**，使用方需自行受控。传了 children 时 InputType 自动渲染分支会被跳过。"
+        },
+        "errorMessage": {
+            "type": "string",
+            "description": "**脱离 FieldForm 独立使用时的受控错误文案（父组件接管 pattern）**。独立使用时 FormItem 不会自动触发 rules 校验——rules 仅渲染必填红星。错误文案必须由父组件主动驱动：① 父组件自行执行校验逻辑（如在 onBlur 中判断）；② 把校验结果写入 `errorMessage` prop（非空字符串 → 显示错误外壳；`''`/`null`/`undefined` → 清除错误状态）。不要同时传 `error` 或 `helperText`——独立使用场景统一用 `errorMessage`。"
+        },
+        "hide": {
+            "type": "boolean",
+            "description": "是否隐藏该表单项（src/FormItem/index.tsx:109 interface 实证）。hide=true 时 FormItem 不渲染（不占位），且 form.current.check() 和 form.current.getValidValues() 会跳过该字段。**与 CSS display:none 不同**——hide=true 时字段值不参与校验也不出现在提交结果中"
+        },
+        "className": {
+            "type": "string",
+            "description": "表单项容器自定义类名（src/FormItem/index.tsx:170 interface 实证）"
+        },
+        "itemType": {
+            "type": "'default' | 'select' | 'switch' | 'textarea' | 'number' | 'file' | 'radioGroup' | 'checkGroup' | 'comboSelect' | ReactNode | FC",
+            "description": "InputType 的别名（src/FormItem/index.tsx:74 interface 实证：itemType 与 InputType 同义，src 内部两者都检查）。**推荐用 InputType**——itemType 是历史命名，两者功能完全相同"
+        }
+    },
+    "do": [
+        "把 FormItem 作为 FieldForm 的子组件使用——形成完整的校验 + 提交链路",
+        "字段名仅传 string；嵌套字段在 FieldForm 层面用 schema 表达",
+        "校验规则用 paraui 自有 schema：`{ validate: { required: true, minLength: 8 }, message: { required: '请输入', minLength: '至少 8 位' } }`，不要传 `[{ required, message }]` 数组形式（会触发 TS2559）",
+        "无 label 字段使用 `hideLabel` 而不是 `label={null}`",
+        "需要自定义控件时把控件放在 children；需要自动渲染时用 InputType + inputProps",
+        "脱离 FieldForm 独立使用时:由父组件管理 children 的 value/onChange + 在父组件主动调用业务校验函数,把校验结果写入 FormItem 的 `errorMessage` prop 受控显示"
+    ],
+    "dont": [
+        "不要嵌套 FormItem",
+        "不要传 `name={['user', 'address', 'city']}`——name 仅 string",
+        "不要传 `label={null}`——会触发 TS2322；要无 label 用 `hideLabel`",
+        "不要按 antd 风格写 `rules={[{ required: true, message: '...' }]}`——会触发 TS2559；本组件 rules 是单对象 ruleType",
+        "不要假设 FormItem 自动给 children cloneElement 注入 value/onChange——本组件不做注入",
+        "不要期望 FormItem 在脱离 FieldForm 时自动触发 rules.validate.required 等校验——独立模式下 rules 仅作类型描述,业务校验需父组件主动驱动"
+    ],
+    "events": {
+        "change": {
+            "signature": "(value: any) => void",
+            "asyncSupported": false,
+            "examples": [
+                "change={(val) => setValue(val)} — 仅 InputType 自动渲染场景由内部 ItemType 触发；外部 children 受控时不会自动触发",
+                "InputType='select' 时 change 在用户选中选项时触发，value 为选中项的 value 字段值",
+                "InputType='switch' 时 change 在用户 toggle 时触发，value 为布尔值 true/false"
+            ],
+            "commonMistakes": [
+                "传了 children 还期望 change 自动触发——children 受控时 ItemType 不渲染，change 永不触发，需在 children 中自己监听",
+                "假设 change 签名与 onChange 相同是 (e) => void 原生事件——实际签名是 (value: any) => void，直接是值而非 event",
+                "脱离 FieldForm 独立使用时期望 change 携带字段名——change 只传 value，字段名需父组件通过 name 自行关联"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "FormItem.name 只接受 string，不能传数组路径",
+            "wrong": "const fieldName: string[] = ['user', 'address']; <FormItem name={fieldName} /> // TS2322 string[] 不能赋给 string",
+            "right": "<FormItem name='user.address' /> // 点路径字符串是合法的 string，但不会被解析为嵌套对象，聚合 key 保持原字符串形态"
+        },
+        {
+            "issue": "rules 是单对象不是数组——antd 风格写法 rules={[{required}]} 触发 TS2559",
+            "wrong": "<FormItem name='email' rules={[{ required: true, message: '必填' }]} /> // TS2559: Type '...[]' has no properties in common with ruleType",
+            "right": "<FormItem name='email' rules={{ validate: { required: true }, message: { required: '必填' } }} />"
+        },
+        {
+            "issue": "label 不支持传 null，要无 label 应用 hideLabel",
+            "wrong": "<FormItem name='code' label={null} /> // TS2322: Type 'null' is not assignable to 'string | (props: FormItemProps) => ReactNode'",
+            "right": "<FormItem name='code' hideLabel /> // 正确隐藏 label 区块"
+        },
+        {
+            "issue": "InputType 和 itemType 同时存在时，src 优先取 InputType（itemType 是别名）",
+            "wrong": "// 同时传两个不同值，期望 itemType 生效\n<FormItem name='x' itemType='select' InputType='default' /> // InputType 优先，select 不生效",
+            "right": "// 统一用 InputType，itemType 是历史别名\n<FormItem name='x' InputType='select' />"
+        },
+        {
+            "issue": "select 子项的 list 字段用 value，radioGroup/checkGroup 用 name——混用导致选中后 change 不传值",
+            "wrong": "InputType='select' list={[{label: 'A', name: 'a'}]} // select 读 value 字段，name 被忽略",
+            "right": "InputType='select' list={[{label: 'A', value: 'a'}]} // 而 radioGroup/checkGroup 用 name 字段"
+        }
+    ],
+    "mapping": {
+        "realComponent": "FormItem",
+        "adapter": null
+    }
+}

package/FunctionModal/component.json

@@ -0,0 +1,197 @@
+{
+    "name": "FunctionModal",
+    "category": "Feedback",
+    "description": "函数式弹窗(命令式 Modal)。**通过 React Hook + Promise 工作,不是命令式静态方法**。典型场景:确认对话框、信息提示、错误警告、表单二次确认。**关键:必须先用 FunctionModalProvider 包裹应用根节点,然后在子组件用 useModal() Hook 拿到调用函数,调用返回 Promise<boolean>**",
+    "semantic": {
+        "intent": [
+            "命令式确认弹窗",
+            "Promise 驱动的对话流",
+            "全局唯一挂载点的临时 Modal"
+        ],
+        "useCases": [
+            "确认删除 / 重要操作前的二次确认",
+            "成功 / 失败 / 警告等系统通知",
+            "异步操作前的用户确认(checkFunction 拦截)",
+            "需要自动关闭 / 超时关闭的提示弹窗(getClose)"
+        ],
+        "riskLevel": "normal"
+    },
+    "protocolSummary": "**Hook + Provider + Promise 三件套**。不是 `FunctionModal({...})` 命令式调用!正确流程:\n1. 应用根节点用 `<FunctionModalProvider>{App}</FunctionModalProvider>` 包裹(挂载点,无之则 useModal 拿到 reject Promise)\n2. 子组件 `const modal = useModal();` 拿到调用函数\n3. `modal({ title, content, ... })` 触发,返回 `Promise<boolean>`(确认=true,取消=false)\n4. 用 `.then(ok => ...)` 或 `await modal({...})` 拿用户选择\n5. **不要传 onOk / onCancel**——FDialog 内部已硬接管点击事件,外部回调会被忽略(常见误解 M1)",
+    "controlledChannels": {
+        "openApi": {
+            "entryPoint": "import FunctionModal, { FunctionModalProvider } from '@para-ui/core/FunctionModal'",
+            "defaultExport": "FunctionModal 的 default export 实际就是 useModal —— 写 `import { useModal } from '@para-ui/core/FunctionModal'` 或 `import useModal from '@para-ui/core/FunctionModal'` 等效",
+            "callPattern": "const modal = useModal(); await modal({ title, content }); // 不是 FunctionModal({...})!",
+            "returnValue": "Promise<boolean> —— 用户点确定 resolve(true),点取消 / 关闭按钮 resolve(false)(除非 disCatchOnCancel=true 强制 true)"
+        },
+        "providerSetup": {
+            "where": "应用根节点(App.tsx / index.tsx),通常和路由 Provider 同层",
+            "code": "<FunctionModalProvider><App /></FunctionModalProvider>",
+            "ifMissing": "useModal() 返回的函数实际是 Promise.reject —— 调用任何 modal({...}) 都立即 reject,且无 UI 弹出"
+        },
+        "closeAllApi": {
+            "import": "import { useClose } from '@para-ui/core/FunctionModal'",
+            "signature": "const closeAll = useClose(); closeAll(); // 关闭页面上所有 FunctionModal 实例",
+            "useCase": "路由切换 / 全局登出时清空所有遗留弹窗"
+        }
+    },
+    "variants": {
+        "default": {
+            "meaning": "默认样式(无 variant 切换)"
+        }
+    },
+    "states": [
+        "open",
+        "closed"
+    ],
+    "idealProps": {
+        "title": {
+            "type": "string",
+            "description": "弹窗标题(注意 type 是 string,不是 ReactNode—— FDialog 内部把它当 string 传给底层 Modal)"
+        },
+        "content": {
+            "type": "ReactElement",
+            "description": "弹窗主体内容(可以是任意 JSX),与 context 字段二选一(context 是早期遗留命名,优先用 content)"
+        },
+        "context": {
+            "type": "ReactElement",
+            "description": "等价于 content(早期命名遗留),如果同时传 content 和 context,content 优先"
+        },
+        "size": {
+            "type": "enum",
+            "values": [
+                "sm",
+                "md",
+                "lg",
+                "auto",
+                "fullScreen"
+            ],
+            "default": "md",
+            "description": "弹窗尺寸,透传给底层 Modal 组件"
+        },
+        "checkFunction": {
+            "type": "() => boolean | Promise<boolean>",
+            "description": "**用户点确定按钮时先执行此函数,返回 true 才真正关闭弹窗 + resolve(true);返回 false 不关闭(可用于表单校验失败拦截)**。支持异步:return await api.validate()",
+            "useCase": "异步校验、二次拦截、表单提交前的服务端检查"
+        },
+        "getClose": {
+            "type": "(close: Function) => void",
+            "description": "**回调拿到这个弹窗实例的 close 方法**。用法:`getClose: (close) => { setTimeout(() => close(), 3000); }` 实现定时自动关闭。close 调用等价于用户点取消(resolve(false),除非 disCatchOnCancel)",
+            "useCase": "成功提示自动消失 / 外部主动关闭单个实例(不影响其他弹窗)"
+        },
+        "disCatchOnCancel": {
+            "type": "boolean",
+            "default": false,
+            "description": "**默认 false**:取消 / 关闭按钮触发 resolve(false)。设为 true:取消也 resolve(true)(异常关闭仍按确认处理)",
+            "useCase": "非常用,默认就够"
+        },
+        "ModalProps": {
+            "type": "ModalProps",
+            "description": "透传给底层 Modal 组件的完整 props,用于调整 mask / okText / cancelText / okButtonProps 等。**注意**:Modal 的 onClose / onOk / onCancel 已被 FDialog 硬接管,在 ModalProps 里写也无效"
+        }
+    },
+    "commonMisconceptions": {
+        "M1": {
+            "wrong": "把 FunctionModal 当 antd 的 Modal.confirm() 命令式静态方法用: `FunctionModal({ title, content, onOk })` 直接调用",
+            "result": "**TS 报错 TS2554 'Expected 0 arguments, but got 1'**——FunctionModal 的 default export 是 useModal Hook(无参函数),不接受参数。R20-R23 ai-test 100% fail 都是这个原因",
+            "fix": "改用 Hook 模式: `const modal = useModal(); modal({title, content})`。完整流程见 protocolSummary + completeExample"
+        },
+        "M2": {
+            "wrong": "在 modalOptions 里传 onOk / onCancel: `modal({ title, content, onOk: handleOk, onCancel: handleCancel })`",
+            "result": "**外部传的 onOk / onCancel 被 FDialog 内部硬覆盖**(`onCancel={() => onClose(listIndex)}` 强制接管),回调不触发。R20-R23 报告里 4 个 high 困惑都是这个",
+            "fix": "用 Promise 返回值: `modal({title, content}).then(ok => ok ? handleOk() : handleCancel())` 或 `const ok = await modal({...}); if (ok) handleOk(); else handleCancel();`"
+        },
+        "M3": {
+            "wrong": "忘记在应用根节点挂 `<FunctionModalProvider>`,直接在某个子组件用 useModal()",
+            "result": "**useModal() 拿到的是 Promise.reject 函数**——任何 modal({...}) 调用都立即 reject,且无 UI 弹出,且无报错(Promise reject 默认静默)",
+            "fix": "在 App.tsx 或 index.tsx 顶层加 `<FunctionModalProvider>{children}</FunctionModalProvider>` 包裹"
+        },
+        "M4": {
+            "wrong": "想要弹窗自动关闭就给 modalOptions 加 duration / autoClose 字段: `modal({ title, content, duration: 3000 })`",
+            "result": "**modalOptions 没有 duration / autoClose 字段**——TS 报错或字段被忽略",
+            "fix": "用 getClose 拿到 close handle 后自己定时: `modal({ title, content, getClose: (close) => setTimeout(close, 3000) })`(见 completeExample 的自动关闭用例)"
+        },
+        "M5": {
+            "wrong": "把 title 传 ReactNode: `modal({ title: <span>富文本</span>, content: ... })`",
+            "result": "title 的类型签名是 string,传 ReactNode 会渲染异常或 TS 报错",
+            "fix": "title 只用纯字符串。富文本标题放到 content 顶部用大字号样式区分"
+        }
+    },
+    "completeExample": "// 1. App 根节点挂 Provider (一次性)\n// App.tsx\nimport { FunctionModalProvider } from '@para-ui/core/FunctionModal';\nconst App: React.FC = () => (\n    <FunctionModalProvider>\n        <YourRoutesAndPages />\n    </FunctionModalProvider>\n);\n\n// 2. 子组件用 useModal + Promise\nimport useModal from '@para-ui/core/FunctionModal';\nimport Button from '@para-ui/core/Button';\n\nconst DeleteButton: React.FC<{ onConfirm: () => void }> = ({ onConfirm }) => {\n    const modal = useModal();\n    const handleClick = async () => {\n        const ok = await modal({\n            title: '确认删除',\n            content: <span>此操作不可恢复,确定要删除吗?</span>,\n            size: 'sm'\n        });\n        if (ok) onConfirm();\n        // 不需要 else 分支,取消时无操作\n    };\n    return <Button danger onClick={handleClick}>删除</Button>;\n};\n\n// 3. 进阶:自动关闭 + 异步校验\nconst AdvancedDemo: React.FC = () => {\n    const modal = useModal();\n    const showAutoClose = () => {\n        modal({\n            title: '操作成功',\n            content: '3 秒后自动关闭',\n            getClose: (close) => setTimeout(close, 3000)\n        });\n    };\n    const showWithCheck = async () => {\n        const ok = await modal({\n            title: '提交订单',\n            content: '提交后需调用支付接口',\n            checkFunction: async () => {\n                const result = await api.validatePayment();\n                return result.canProceed; // false 时弹窗不关闭\n            }\n        });\n        if (ok) console.log('支付成功');\n    };\n    return (\n        <>\n            <Button onClick={showAutoClose}>成功提示</Button>\n            <Button onClick={showWithCheck}>带校验的确认</Button>\n        </>\n    );\n};",
+    "do": [
+        "**先在 App 根节点挂 `<FunctionModalProvider>` 一次**,然后在任何子组件用 useModal()",
+        "**用 Promise 返回值拿用户选择**:`const ok = await modal({...})` 或 `modal({...}).then(ok => ...)`",
+        "异步校验拦截关闭:用 `checkFunction: async () => boolean`",
+        "自动关闭:`getClose: (close) => setTimeout(close, ms)`",
+        "全局清空所有弹窗:`const closeAll = useClose(); closeAll();`(路由切换时调用)"
+    ],
+    "dont": [
+        "**不要**直接调用 `FunctionModal({title, ...})`——它是 Hook,不是命令式函数(M1)",
+        "**不要**传 onOk / onCancel——内部硬接管,不会触发(M2)",
+        "**不要**忘记挂 FunctionModalProvider——会导致 Promise 静默 reject(M3)",
+        "**不要**期望 modalOptions 有 duration / autoClose 字段——用 getClose 实现(M4)",
+        "**不要**给 title 传 ReactNode——title 类型是 string(M5)",
+        "复杂表单场景请用 Modal 直接控制 open/close,不要用 FunctionModal"
+    ],
+    "events": {
+        "useModal": {
+            "signature": "() => (options: modalOptions) => Promise<boolean>",
+            "asyncSupported": true,
+            "examples": [
+                "const modal = useModal(); const ok = await modal({ title: '确认删除', content: <span>操作不可撤销</span> }); if (ok) doDelete(); — 标准 await 用法",
+                "modal({ title: '提示', content: '操作完成', getClose: (close) => setTimeout(close, 3000) }) — 自动关闭不需要等待 Promise",
+                "const ok = await modal({ title: '提交', content: '...', checkFunction: async () => await api.validate() }); — checkFunction 拦截异步校验"
+            ],
+            "commonMistakes": [
+                "直接调用 FunctionModal({...}) 而不是先 useModal() 再调用——FunctionModal default export 是 Hook 本身，不是可调用函数",
+                "在 modalOptions 里传 onOk/onCancel 期望回调——FDialog 内部硬接管，回调不触发，应用 Promise 返回值",
+                "忘记在 App 根节点挂 <FunctionModalProvider>——useModal() 返回的函数是 Promise.reject，调用时立即 reject 且无 UI"
+            ]
+        },
+        "useClose": {
+            "signature": "() => () => void",
+            "asyncSupported": false,
+            "examples": [
+                "const closeAll = useClose(); closeAll(); — 关闭当前页面所有 FunctionModal 实例",
+                "路由切换时调用：useEffect(() => { return () => closeAll(); }, [pathname]); — 离开页面清空遗留弹窗",
+                "登出时全局清空：const closeAll = useClose(); onLogout(() => closeAll());"
+            ],
+            "commonMistakes": [
+                "期望 useClose 关闭单个弹窗——useClose 关闭所有实例，关闭单个需用 getClose 拿到单实例 close 函数",
+                "在 FunctionModalProvider 外部调用 useClose——useClose 内部引用 setState 模块变量，Provider 未挂载时 setState 为 undefined，调用报错",
+                "多次调用 useClose() 拿多个 closeAll 函数——结果等价，均是同一 setState 引用"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "FunctionModal default export 是 useModal Hook，不能当命令式函数直接调用",
+            "wrong": "import FunctionModal from '@para-ui/core/FunctionModal'; FunctionModal({ title: '确认', content: <p>内容</p> }); // TS2554: Expected 0 arguments, but got 1",
+            "right": "import useModal from '@para-ui/core/FunctionModal'; const modal = useModal(); await modal({ title: '确认', content: <p>内容</p> });"
+        },
+        {
+            "issue": "modalOptions.title 类型是 string，不是 ReactNode，传 JSX 会报 TS 错误",
+            "wrong": "modal({ title: <span>富文本<b>标题</b></span>, content: <p>内容</p> }); // title 类型签名是 string",
+            "right": "modal({ title: '标题', content: <><h3>富文本标题</h3><p>内容</p></> }); // 把富文本放到 content 顶部"
+        },
+        {
+            "issue": "checkFunction 返回 false 不关闭弹窗，但异步返回 void/undefined 等同于 falsy 也不关闭",
+            "wrong": "checkFunction={async () => { await doSomething(); }} // 没有 return，隐式返回 undefined → 弹窗不关闭",
+            "right": "checkFunction={async () => { await doSomething(); return true; }} // 明确 return true 才关闭"
+        },
+        {
+            "issue": "modalOptions 不包含 duration/autoClose 字段——自动关闭需用 getClose 回调",
+            "wrong": "modal({ title: '成功', content: '已保存', duration: 2000 }); // TS2353: duration does not exist in type modalOptions",
+            "right": "modal({ title: '成功', content: '已保存', getClose: (close) => setTimeout(close, 2000) }); // 用 getClose + setTimeout 实现"
+        },
+        {
+            "issue": "useModal 在 FunctionModalProvider 外部调用返回的函数立即 reject，无 UI 弹出",
+            "wrong": "// 忘记在 App 根包 Provider，子组件直接用 useModal\nconst modal = useModal(); modal({...}); // 静默 reject，Promise rejected 但没有 catch 不报错",
+            "right": "// App.tsx 包 Provider 后子组件才能正常用\n<FunctionModalProvider><App /></FunctionModalProvider>"
+        }
+    ],
+    "mapping": {
+        "realComponent": "FunctionModal",
+        "adapter": null
+    }
+}