antd-overlay 0.1.2 → 0.3.0

package/docs/ai/constraints.md

@@ -0,0 +1,83 @@
+# 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`
+
+## Promise 行为语义（usePromiseOverlay / usePromiseModal / usePromiseDrawer）
+
+### 解析规则
+
+- `customOk(value)` 同步返回 → 外层 Promise resolve **value（入参，非 customOk 返回值）**
+- `customOk(value)` 异步 resolve → 在 customOk 的 Promise 完成后 resolve(value)
+- 任何其他关闭路径（`customClose` / 蒙层 / antd 取消按钮 / 组件卸载 / 同实例再次 `openPromise` 抢占）→ resolve `undefined`
+- `customOk` 抛错或 Promise reject → Promise 以同一错误 **reject**，覆盖层 **保持打开**
+- 单次 `openPromise` 的 Promise 仅结算一次（幂等）
+- 解析时机为决策时刻，不等待关闭动画
+
+### 错误语义码
+
+- `PROMISE_RESOLVES_WITH_INPUT` — 解析值为 customOk 入参，不是返回值
+- `PROMISE_RESOLVED_ON_CLOSE` — 任意非 OK 关闭 → resolve(undefined)，不 reject
+- `PROMISE_PREEMPTED_BY_REOPEN` — 再次 open 抢占式 resolve 前一个 Promise
+- `CUSTOM_OK_REJECTED` — customOk 抛错 / reject 透传，覆盖层不关闭
+
+### AI 易错点
+
+- 不要假设关闭等同于 reject —— 取消应该用 `if (result === undefined) return;` 判断
+- 不要把 `customOk` 的返回值当成 Promise 的解析值 —— 解析值始终是入参 `value`
+- 不要为了 “等动画完成再继续” 把 `await` 之后的代码放进 `setTimeout` —— Promise 已经在决策时刻 resolve
+
+## AI 生成代码建议
+
+- 优先生成 `useModal` 或 `useDrawer`，仅在通用组件时使用 `useOverlay`
+- 业务流程中需要 `await` 用户结果时优先生成 `usePromiseModal` / `usePromiseDrawer`
+- 使用全局 Hook 时必须同时输出 Provider 包裹代码
+- 避免在 `customOk` 内重复手动 `close`，除非明确要覆盖默认关闭时机

package/docs/ai/contracts.json

@@ -0,0 +1,88 @@
+{
+  "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",
+    "imperative-await-overlay-result-via-promise"
+  ],
+  "constraints": [
+    {
+      "code": "PROVIDER_REQUIRED",
+      "rule": "useGlobalModal/useGlobalDrawer/useGlobalOverlay 必须在 AntdOverlayProvider 作用域内调用"
+    },
+    {
+      "code": "OVERLAY_COMPONENT_CONTRACT",
+      "rule": "自定义组件必须消费 open 与 customClose，且 customOk 应由确认行为触发"
+    },
+    {
+      "code": "UPDATE_SHALLOW_MERGE",
+      "rule": "controller.update 使用浅合并，不进行深层对象合并"
+    },
+    {
+      "code": "PROMISE_RESOLVES_WITH_INPUT",
+      "rule": "usePromise* 系列：外层 Promise 解析为 customOk 的入参（value），不是 customOk 的返回值"
+    }
+  ],
+  "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（浅合并）"
+    },
+    {
+      "code": "PROMISE_RESOLVED_ON_CLOSE",
+      "type": "behavior",
+      "trigger": "通过 customClose / 蒙层 / antd 取消按钮 / 组件卸载 关闭 usePromise* 系列覆盖层",
+      "result": "外层 Promise 以 undefined resolve（不 reject）"
+    },
+    {
+      "code": "PROMISE_PREEMPTED_BY_REOPEN",
+      "type": "behavior",
+      "trigger": "在前一个 Promise 未结算时再次调用同一 hook 实例的 openPromise",
+      "result": "前一个 Promise 立即以 undefined resolve，新 Promise 接管"
+    }
+  ],
+  "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();"
+    },
+    "promiseModal": {
+      "providerRequired": false,
+      "snippet": "const [openPromise, holder] = usePromiseModal(Component); const v = await openPromise({ ...props }); if (v === undefined) return; /* 用户取消 */"
+    },
+    "promiseDrawer": {
+      "providerRequired": false,
+      "snippet": "const [openPromise, holder] = usePromiseDrawer(Component); const v = await openPromise({ ...props }); if (v === undefined) return; /* 用户取消 */"
+    }
+  },
+  "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,112 @@
+# 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` 触发，避免自行关闭与业务状态不同步
+
+## 6) Promise 模式（await customOk 入参）
+
+适用场景：业务方希望在调用处直接 `await` 拿到用户的确认结果。
+
+```tsx
+import { usePromiseModal, CustomModalProps } from 'antd-overlay';
+import { Modal } from 'antd';
+
+interface ConfirmModalProps extends CustomModalProps<{ value: string }> {
+  initialValue?: string;
+}
+
+const ConfirmModal: React.FC<ConfirmModalProps> = ({ open, customClose, customOk, initialValue }) => (
+  <Modal open={open} onCancel={customClose} onOk={() => customOk?.({ value: initialValue ?? '' })}>
+    confirm
+  </Modal>
+);
+
+function Page() {
+  const [openConfirm, holder] = usePromiseModal(ConfirmModal);
+
+  const handle = async () => {
+    const result = await openConfirm({ initialValue: 'hello' });
+    if (result === undefined) return; // 用户取消 / 关闭
+    console.log(result.value);         // customOk 入参
+  };
+
+  return <>{holder}<button onClick={handle}>open</button></>;
+}
+```
+
+行为契约（同样适用于 `usePromiseDrawer` / `usePromiseOverlay` 与对应的 `useGlobalPromise*` / `generateUsePromise*Hook`）：
+
+- `customOk(value)` 同步成功 → Promise resolve **value（入参）**；异步 resolve 同理
+- 任意非 OK 关闭路径（`customClose` / 蒙层 / 取消按钮 / 组件卸载 / 同实例再次 open 抢占）→ Promise resolve `undefined`
+- `customOk` 抛错或 Promise reject → Promise 以同一错误 reject，覆盖层保持打开
+- Promise 仅结算一次（幂等）；解析时机为决策时刻，不等待关闭动画

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "antd-overlay",
-  "version": "0.1.2",
+  "version": "0.3.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"