antd-overlay 0.1.2 → 0.2.0

package/README.md

@@ -137,6 +137,23 @@ function GlobalUsage() {
 
 `openModal(...)` 返回 `OverlayController`：可调用 `update` 传入要更新的字段（与当前已保存的 props 及 Hook 的 `defaultProps` **浅合并**，同名键以本次 `update` 入参为准）、`close` 关闭（会尊重动画配置）。
 
+`customOk` 关闭语义（适用于 `useOverlay` / `useModal` / `useDrawer`）：
+
+- 同步回调正常返回：自动关闭覆盖层
+- 异步回调 `Promise resolve`：在 Promise 完成后自动关闭覆盖层
+- 异步回调 `Promise reject` 或同步抛错：保持覆盖层打开，并将错误透传给调用方
+
+## AI 使用指引
+
+为提高代码助手（Cursor/Copilot/Claude Code 等）对本库的调用正确率，建议优先读取以下文档：
+
+- `docs/ai/quick-reference.md`：最短调用路径与最小示例
+- `docs/ai/constraints.md`：前置条件、行为约束与错误语义
+- `docs/ai/api-manifest.json`：机器可读 API 清单
+- `docs/ai/contracts.json`：能力、约束、错误语义和推荐模板
+
+若 AI 生成的是全局 Hook（`useGlobalModal`、`useGlobalDrawer`、`useGlobalOverlay`）用法，务必同时生成 `AntdOverlayProvider` 包裹代码。
+
 ## API
 
 ### Provider
@@ -238,10 +255,12 @@ const [openOverlay, holder] = useOverlay(MyOverlay, {
 interface CustomOverlayProps<T = any, R = void> {
   open?: boolean;
   customClose: () => void;
-  customOk?: (value: T) => R;
+  customOk?: (value: T) => R | Promise<R>;
 }
 ```
 
+如需本地验证异步行为，可运行 demo 中的 `AsyncCustomOkDemo`（包含 Overlay / Modal / Drawer 的异步成功与失败场景）。
+
 #### `CustomModalProps<T, R>` / `CustomDrawerProps<T, R>`
 
 分别为 `ModalProps` / `DrawerProps` 与 `CustomOverlayProps` 的交叉类型。

package/docs/ai/api-manifest.json

@@ -0,0 +1,162 @@
+{
+  "name": "antd-overlay",
+  "manifestVersion": "1.0.0",
+  "docsVersion": "0.1.2",
+  "entrypoint": "antd-overlay",
+  "symbols": [
+    {
+      "name": "AntdOverlayProvider",
+      "kind": "component",
+      "signature": "AntdOverlayProvider(props: { children; defaultModalProps?; defaultDrawerProps? })",
+      "params": [
+        { "name": "children", "required": true, "type": "React.ReactNode" },
+        { "name": "defaultModalProps", "required": false, "type": "Partial<ModalProps>" },
+        { "name": "defaultDrawerProps", "required": false, "type": "Partial<DrawerProps>" }
+      ],
+      "returns": "JSX.Element",
+      "preconditions": [],
+      "failureScenarios": [],
+      "recommendedDoc": "docs/ai/quick-reference.md"
+    },
+    {
+      "name": "useModal",
+      "kind": "hook",
+      "signature": "useModal<T>(Component, options?) => [openModal, holder]",
+      "params": [
+        { "name": "Component", "required": true, "type": "React.FC<T extends CustomModalProps>" },
+        { "name": "options", "required": false, "type": "UseModalOptions<T>" }
+      ],
+      "returns": "[OverlayOpener<T>, React.ReactNode]",
+      "preconditions": [],
+      "failureScenarios": [
+        {
+          "code": "INVALID_OVERLAY_CONTRACT",
+          "when": "传入组件未正确消费 open/customClose 导致行为异常"
+        }
+      ],
+      "recommendedDoc": "docs/ai/quick-reference.md"
+    },
+    {
+      "name": "useGlobalModal",
+      "kind": "hook",
+      "signature": "useGlobalModal<T>(Component, options?) => openModal",
+      "params": [
+        { "name": "Component", "required": true, "type": "React.FC<T extends CustomModalProps>" },
+        { "name": "options", "required": false, "type": "UseModalOptions<T>" }
+      ],
+      "returns": "OverlayOpener<T>",
+      "preconditions": ["必须在 AntdOverlayProvider 作用域中调用"],
+      "failureScenarios": [
+        {
+          "code": "PROVIDER_REQUIRED",
+          "when": "在 AntdOverlayProvider 外部调用 useGlobalModal"
+        }
+      ],
+      "recommendedDoc": "docs/ai/constraints.md"
+    },
+    {
+      "name": "useDrawer",
+      "kind": "hook",
+      "signature": "useDrawer<T>(Component, options?) => [openDrawer, holder]",
+      "params": [
+        { "name": "Component", "required": true, "type": "React.FC<T extends CustomDrawerProps>" },
+        { "name": "options", "required": false, "type": "UseDrawerOptions<T>" }
+      ],
+      "returns": "[OverlayOpener<T>, React.ReactNode]",
+      "preconditions": [],
+      "failureScenarios": [
+        {
+          "code": "INVALID_OVERLAY_CONTRACT",
+          "when": "传入组件未正确消费 open/customClose 导致行为异常"
+        }
+      ],
+      "recommendedDoc": "docs/ai/quick-reference.md"
+    },
+    {
+      "name": "useGlobalDrawer",
+      "kind": "hook",
+      "signature": "useGlobalDrawer<T>(Component, options?) => openDrawer",
+      "params": [
+        { "name": "Component", "required": true, "type": "React.FC<T extends CustomDrawerProps>" },
+        { "name": "options", "required": false, "type": "UseDrawerOptions<T>" }
+      ],
+      "returns": "OverlayOpener<T>",
+      "preconditions": ["必须在 AntdOverlayProvider 作用域中调用"],
+      "failureScenarios": [
+        {
+          "code": "PROVIDER_REQUIRED",
+          "when": "在 AntdOverlayProvider 外部调用 useGlobalDrawer"
+        }
+      ],
+      "recommendedDoc": "docs/ai/constraints.md"
+    },
+    {
+      "name": "useOverlay",
+      "kind": "hook",
+      "signature": "useOverlay<T>(Component, options?) => [openOverlay, holder]",
+      "params": [
+        { "name": "Component", "required": true, "type": "React.FC<T extends CustomOverlayProps>" },
+        { "name": "options", "required": false, "type": "UseOverlayOptions<T>" }
+      ],
+      "returns": "[OverlayOpener<T>, React.ReactNode]",
+      "preconditions": [],
+      "failureScenarios": [],
+      "recommendedDoc": "docs/ai/quick-reference.md"
+    },
+    {
+      "name": "useGlobalOverlay",
+      "kind": "hook",
+      "signature": "useGlobalOverlay<T>(Component, options?) => openOverlay",
+      "params": [
+        { "name": "Component", "required": true, "type": "React.FC<T extends CustomOverlayProps>" },
+        { "name": "options", "required": false, "type": "UseOverlayOptions<T>" }
+      ],
+      "returns": "OverlayOpener<T>",
+      "preconditions": ["必须在 AntdOverlayProvider 作用域中调用"],
+      "failureScenarios": [
+        {
+          "code": "PROVIDER_REQUIRED",
+          "when": "在 AntdOverlayProvider 外部调用 useGlobalOverlay"
+        }
+      ],
+      "recommendedDoc": "docs/ai/constraints.md"
+    },
+    {
+      "name": "generateUseModalHook",
+      "kind": "factory",
+      "signature": "generateUseModalHook<T>(Component) => { useModal, useGlobalModal }",
+      "params": [
+        { "name": "Component", "required": true, "type": "React.FC<T extends CustomModalProps>" }
+      ],
+      "returns": "{ useModal(options?), useGlobalModal(options?) }",
+      "preconditions": [],
+      "failureScenarios": [],
+      "recommendedDoc": "README.md"
+    },
+    {
+      "name": "generateUseDrawerHook",
+      "kind": "factory",
+      "signature": "generateUseDrawerHook<T>(Component) => { useDrawer, useGlobalDrawer }",
+      "params": [
+        { "name": "Component", "required": true, "type": "React.FC<T extends CustomDrawerProps>" }
+      ],
+      "returns": "{ useDrawer(options?), useGlobalDrawer(options?) }",
+      "preconditions": [],
+      "failureScenarios": [],
+      "recommendedDoc": "README.md"
+    },
+    {
+      "name": "generateUseOverlayHook",
+      "kind": "factory",
+      "signature": "generateUseOverlayHook<T>(Component, defaultOptions?) => { useOverlay, useGlobalOverlay }",
+      "params": [
+        { "name": "Component", "required": true, "type": "React.FC<T extends CustomOverlayProps>" },
+        { "name": "defaultOptions", "required": false, "type": "UseOverlayOptions<T>" }
+      ],
+      "returns": "{ useOverlay(options?), useGlobalOverlay(options?) }",
+      "preconditions": [],
+      "failureScenarios": [],
+      "recommendedDoc": "README.md"
+    }
+  ]
+}

package/docs/ai/constraints.md

@@ -0,0 +1,58 @@
+# antd-overlay Constraints and Error Semantics
+
+本文件定义 AI 调用时应优先遵守的约束，避免生成“看起来正确但运行失败”的代码。
+
+## Provider 约束
+
+### 约束
+
+- `useGlobalOverlay`
+- `useGlobalModal`
+- `useGlobalDrawer`
+
+以上 Hook 必须在 `AntdOverlayProvider` 作用域内调用。
+
+### 失败语义
+
+- 错误语义码：`PROVIDER_REQUIRED`
+- 触发条件：在 Provider 外调用任一全局 Hook
+- 建议修复：将应用入口包裹 `AntdOverlayProvider`
+
+## 组件契约约束
+
+### 最小必需字段
+
+自定义覆盖层组件必须实现 `CustomOverlayProps` 的关键字段：
+
+- `open?: boolean`
+- `customClose: () => void`
+- `customOk?: (value) => any | Promise<any>`
+
+### 失败语义
+
+- 错误语义码：`INVALID_OVERLAY_CONTRACT`
+- 触发条件：组件不消费 `open/customClose`，导致显示或关闭行为异常
+- 建议修复：将 UI 组件的显隐/关闭事件绑定到 `open/customClose`
+
+## 行为语义约束
+
+### customOk
+
+- 同步成功返回：自动关闭
+- Promise resolve：异步完成后自动关闭
+- throw / Promise reject：保持打开并透传错误
+
+错误语义码：`CUSTOM_OK_REJECTED`
+
+### update
+
+- `controller.update(next)` 是浅合并更新，不是深合并
+- 合并优先级：`defaultProps` < 之前 props < 本次 `update`
+
+错误语义码：`UPDATE_SHALLOW_MERGE`
+
+## AI 生成代码建议
+
+- 优先生成 `useModal` 或 `useDrawer`，仅在通用组件时使用 `useOverlay`
+- 使用全局 Hook 时必须同时输出 Provider 包裹代码
+- 避免在 `customOk` 内重复手动 `close`，除非明确要覆盖默认关闭时机

package/docs/ai/contracts.json

@@ -0,0 +1,63 @@
+{
+  "name": "antd-overlay-ai-contracts",
+  "version": "1.0.0",
+  "package": "antd-overlay",
+  "capabilities": [
+    "imperative-open-close-overlay",
+    "update-overlay-props-via-controller",
+    "global-overlay-hosting-via-provider",
+    "async-custom-ok-auto-close-on-resolve"
+  ],
+  "constraints": [
+    {
+      "code": "PROVIDER_REQUIRED",
+      "rule": "useGlobalModal/useGlobalDrawer/useGlobalOverlay 必须在 AntdOverlayProvider 作用域内调用"
+    },
+    {
+      "code": "OVERLAY_COMPONENT_CONTRACT",
+      "rule": "自定义组件必须消费 open 与 customClose，且 customOk 应由确认行为触发"
+    },
+    {
+      "code": "UPDATE_SHALLOW_MERGE",
+      "rule": "controller.update 使用浅合并，不进行深层对象合并"
+    }
+  ],
+  "errorSemantics": [
+    {
+      "code": "PROVIDER_REQUIRED",
+      "type": "runtime-throw",
+      "trigger": "全局 Hook 在 Provider 外调用",
+      "fix": "在应用入口包裹 AntdOverlayProvider"
+    },
+    {
+      "code": "CUSTOM_OK_REJECTED",
+      "type": "behavior",
+      "trigger": "customOk 抛错或 Promise reject",
+      "result": "覆盖层保持打开，错误透传"
+    },
+    {
+      "code": "UPDATE_SHALLOW_MERGE",
+      "type": "behavior",
+      "trigger": "调用 controller.update",
+      "result": "defaultProps < prevProps < nextProps（浅合并）"
+    }
+  ],
+  "recommendedTemplates": {
+    "globalModal": {
+      "providerRequired": true,
+      "snippet": "const openModal = useGlobalModal(Component); openModal({ ...props });"
+    },
+    "localModal": {
+      "providerRequired": false,
+      "snippet": "const [openModal, holder] = useModal(Component); openModal({ ...props });"
+    },
+    "controllerUpdate": {
+      "snippet": "const controller = openModal(init); controller.update(next); controller.close();"
+    }
+  },
+  "docs": {
+    "quickReference": "docs/ai/quick-reference.md",
+    "constraints": "docs/ai/constraints.md",
+    "apiManifest": "docs/ai/api-manifest.json"
+  }
+}

package/docs/ai/quick-reference.md

@@ -0,0 +1,74 @@
+# antd-overlay AI Quick Reference
+
+本文件面向代码助手与自动化 Agent，提供最短可执行调用路径。
+
+## 1) 全局调用（推荐跨组件场景）
+
+前置条件：应用根节点已包裹 `AntdOverlayProvider`。
+
+```tsx
+import { AntdOverlayProvider, useGlobalModal, CustomModalProps } from 'antd-overlay';
+import { Modal } from 'antd';
+
+interface ConfirmModalProps extends CustomModalProps<void> {
+  titleText: string;
+}
+
+const ConfirmModal: React.FC<ConfirmModalProps> = ({ open, customClose, customOk, titleText }) => (
+  <Modal open={open} title={titleText} onCancel={customClose} onOk={() => customOk?.()}>
+    Confirm?
+  </Modal>
+);
+
+function AppRoot() {
+  return (
+    <AntdOverlayProvider>
+      <Page />
+    </AntdOverlayProvider>
+  );
+}
+
+function Page() {
+  const openConfirm = useGlobalModal(ConfirmModal);
+  return <button onClick={() => openConfirm({ titleText: 'Delete item' })}>Open</button>;
+}
+```
+
+## 2) 局部调用（需要 holder）
+
+适用场景：覆盖层只在当前组件内管理，不依赖全局 Provider。
+
+```tsx
+import { useModal } from 'antd-overlay';
+
+function LocalPage() {
+  const [openConfirm, holder] = useModal(ConfirmModal);
+
+  return (
+    <>
+      <button onClick={() => openConfirm({ titleText: 'Local confirm' })}>Open</button>
+      {holder}
+    </>
+  );
+}
+```
+
+## 3) 控制器模式（update / close）
+
+```tsx
+const controller = openConfirm({ titleText: 'Step 1' });
+controller.update({ titleText: 'Step 2' });
+controller.close();
+```
+
+## 4) customOk 语义（必须遵守）
+
+- 同步返回（不抛错）：自动关闭覆盖层
+- Promise resolve：Promise 完成后自动关闭
+- throw 或 Promise reject：保持打开，错误继续抛给调用方
+
+## 5) 最小规则清单
+
+- 使用 `useGlobalModal/useGlobalDrawer/useGlobalOverlay` 时，必须存在 `AntdOverlayProvider`
+- 自定义组件需要消费 `open` 与 `customClose`
+- 覆盖层确认动作优先通过 `customOk` 触发，避免自行关闭与业务状态不同步

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "antd-overlay",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Ant Design Modal/Drawer 命令式调用方案",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -11,10 +11,15 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
-    }
+    },
+    "./ai/api-manifest.json": "./docs/ai/api-manifest.json",
+    "./ai/contracts.json": "./docs/ai/contracts.json",
+    "./ai/quick-reference.md": "./docs/ai/quick-reference.md",
+    "./ai/constraints.md": "./docs/ai/constraints.md"
   },
   "files": [
-    "dist"
+    "dist",
+    "docs/ai"
   ],
   "keywords": [
     "antd",
@@ -65,6 +70,7 @@
     "format": "prettier --write .",
     "format:check": "prettier --check .",
     "typecheck": "tsc --noEmit",
+    "validate:ai-docs": "node ./scripts/validate-ai-docs.mjs",
     "changeset": "changeset",
     "version-packages": "changeset version",
     "release": "pnpm build && changeset publish"