antd-overlay 0.2.0 → 0.4.0

package/docs/ai/contracts.json

@@ -6,12 +6,14 @@
     "imperative-open-close-overlay",
     "update-overlay-props-via-controller",
     "global-overlay-hosting-via-provider",
-    "async-custom-ok-auto-close-on-resolve"
+    "async-custom-ok-auto-close-on-resolve",
+    "imperative-tour-open-close",
+    "imperative-await-overlay-result-via-promise"
   ],
   "constraints": [
     {
       "code": "PROVIDER_REQUIRED",
-      "rule": "useGlobalModal/useGlobalDrawer/useGlobalOverlay 必须在 AntdOverlayProvider 作用域内调用"
+      "rule": "useGlobalModal/useGlobalDrawer/useGlobalTour/useGlobalOverlay 必须在 AntdOverlayProvider 作用域内调用"
     },
     {
       "code": "OVERLAY_COMPONENT_CONTRACT",
@@ -20,6 +22,14 @@
     {
       "code": "UPDATE_SHALLOW_MERGE",
       "rule": "controller.update 使用浅合并，不进行深层对象合并"
+    },
+    {
+      "code": "PROMISE_RESOLVES_WITH_INPUT",
+      "rule": "usePromise* 系列：外层 Promise 解析为 customOk 的入参（value），不是 customOk 的返回值"
+    },
+    {
+      "code": "TOUR_NO_PROMISE_API",
+      "rule": "Tour 仅提供 useTour/useGlobalTour/generateUseTourHook，不提供 usePromiseTour"
     }
   ],
   "errorSemantics": [
@@ -40,6 +50,18 @@
       "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": {
@@ -53,6 +75,22 @@
     },
     "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; /* 用户取消 */"
+    },
+    "localTour": {
+      "providerRequired": false,
+      "snippet": "const [openTour, holder] = useTour(Component); openTour({ steps });"
+    },
+    "globalTour": {
+      "providerRequired": true,
+      "snippet": "const openTour = useGlobalTour(Component); openTour({ steps });"
     }
   },
   "docs": {

package/docs/ai/quick-reference.md

@@ -69,6 +69,80 @@ controller.close();
 
 ## 5) 最小规则清单
 
-- 使用 `useGlobalModal/useGlobalDrawer/useGlobalOverlay` 时，必须存在 `AntdOverlayProvider`
+- 使用 `useGlobalModal/useGlobalDrawer/useGlobalTour/useGlobalOverlay` 时，必须存在 `AntdOverlayProvider`
 - 自定义组件需要消费 `open` 与 `customClose`
 - 覆盖层确认动作优先通过 `customOk` 触发，避免自行关闭与业务状态不同步
+
+## 6) Tour 模式（不含 Promise）
+
+```tsx
+import { Tour } from 'antd';
+import { useTour, CustomTourProps } from 'antd-overlay';
+
+const GuideTour: React.FC<CustomTourProps> = ({ customClose, customOk, ...props }) => {
+  void customClose;
+  void customOk;
+  return <Tour {...props} />;
+};
+
+function Page() {
+  const targetRef = React.useRef<HTMLButtonElement>(null);
+  const [openTour, holder] = useTour(GuideTour);
+
+  return (
+    <>
+      <button
+        ref={targetRef}
+        onClick={() =>
+          openTour({
+            steps: [{ title: 'Guide', description: 'Step content', target: () => targetRef.current }],
+          })
+        }
+      >
+        open
+      </button>
+      {holder}
+    </>
+  );
+}
+```
+
+Tour 没有关闭动画完成回调，`useTour/useGlobalTour` 默认关闭即卸载。不要生成 `usePromiseTour`；当前公共 API 不提供 Promise Tour。
+
+## 7) 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,7 +1,7 @@
 {
   "name": "antd-overlay",
-  "version": "0.2.0",
-  "description": "Ant Design Modal/Drawer 命令式调用方案",
+  "version": "0.4.0",
+  "description": "Ant Design Modal/Drawer/Tour 命令式调用方案",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -25,6 +25,7 @@
     "antd",
     "modal",
     "drawer",
+    "tour",
     "overlay",
     "react",
     "hooks",