test(ui): usePresence 补真 node 环境用例

Author: Aparencia

app/src/ui/primitives/usePresence.node.test.ts

@@ -0,0 +1,71 @@
+/**
+ * @ai-context usePresence.node.test.ts — **真 node 环境**（**无** jsdom 环境指令）的守卫用例
+ * （批 0-D Task 6 评审 Important ① 补充）。
+ *
+ * Why 单开一个文件：`usePresence.test.tsx` 是 jsdom（`renderHook` 需要 `document`），那里只能把
+ * `matchMedia` **桩成 `undefined`** 来模拟"无 matchMedia"，**覆盖不到** `getMediaQueryList()` 的第一道
+ * 守卫 `typeof window === "undefined"`（真 node 环境根本不存在 `window`）。而计划 Task 6 的验收项明写
+ * 「**node 环境下不抛错**」⇒ 本文件就是那条验收的机器判据（评审者独立探针 `tmp/review-t6/node-guard-probe.mjs`
+ * 已先证明可行，本文件把它固化成随 CI 跑的用例）。
+ *
+ * 手段：`react-dom/server` 的 `renderToString` —— node 无 DOM，`@testing-library/react` 用不了；但 SSR 会
+ * 跑完**渲染阶段**（含 `useState` 的惰性初始化，那正是媒体查询的读取点）。断言全部落在渲染产物上（不靠
+ * 外部变量捕获，避免 TS 控制流把捕获变量收窄成 `never`）。
+ * **局限（诚实标注）**：SSR **不执行 `useEffect`** ⇒ 本文件只覆盖渲染路径；effect 路径的守卫由
+ * 「`getMediaQueryList()` 是模块内唯一读取点、且自带两道守卫」这一点保证（`useReducedMotion` 的 effect 也调它）。
+ *
+ * 副作用：无（纯内存渲染；不写磁盘、不发请求、不挂计时器）。
+ * 边界：**不得**加 jsdom 环境指令（仓规写法是 `@` + `vitest-environment` + 环境名）—— 加了就退化回 jsdom，
+ * 两道守卫里的第一道 `typeof window === "undefined"` 测不到。⚠️ **该指令是「全文件文本扫描」的**：
+ * 连注释里写出完整指令串都会被 vitest 当成指令识别（本文件初版就因此在 jsdom 下跑、`typeof window` 变成
+ * `object`）⇒ 本文件刻意**不出现**该指令串（本段只用拆开的写法指代它）。
+ * 本文件是 `.ts`（SSR 渲染无需 JSX），故用 `createElement` 而不是 JSX 语法。
+ */
+import { createElement } from "react";
+import type { ReactElement } from "react";
+import { renderToString } from "react-dom/server";
+import { describe, expect, it } from "vitest";
+import { usePresence } from "./usePresence";
+
+/** 把 hook 的返回值全部摊到 DOM 属性上（`renderToString` 不允许外部捕获，属性即观测面） */
+function Probe({ open }: { open: boolean }): ReactElement {
+  const presence = usePresence(open);
+  return createElement("i", {
+    "data-phase": presence.phase,
+    "data-mounted": String(presence.mounted),
+    "data-reduced": String(presence.reducedMotion),
+    "data-handler": typeof presence.onTransitionEnd,
+  });
+}
+
+describe("真 node 环境（无 window / document）：usePresence 不抛错", () => {
+  it("环境事实：本文件确实跑在无 DOM 的 node 环境（否则下面的守卫分支根本没被测到）", () => {
+    expect(typeof window).toBe("undefined");
+    expect(typeof document).toBe("undefined");
+  });
+
+  it("open=true：renderToString 不抛错；reducedMotion=false（守卫按「不命中」处理，不是抛错）", () => {
+    const html = renderToString(createElement(Probe, { open: true }));
+    expect(html).toContain('data-reduced="false"');
+    expect(html).toContain('data-mounted="true"');
+    expect(html).toContain('data-phase="enter"');
+    expect(html, "onTransitionEnd 即使是纯逻辑件也必须可用（T7 挂它，不需要 DOM）").toContain(
+      'data-handler="function"',
+    );
+  });
+
+  it("open=false：不抛错；初始态即终态（mounted=false / phase='exit'）", () => {
+    const html = renderToString(createElement(Probe, { open: false }));
+    expect(html).toContain('data-reduced="false"');
+    expect(html).toContain('data-mounted="false"');
+    expect(html).toContain('data-phase="exit"');
+  });
+
+  it("自定义 reducedMotionQuery 在 node 下同样不抛错（查询串照传，只是读不到环境）", () => {
+    function Custom(): ReactElement {
+      const presence = usePresence(true, { reducedMotionQuery: "(prefers-contrast: more)" });
+      return createElement("i", { "data-reduced": String(presence.reducedMotion) });
+    }
+    expect(renderToString(createElement(Custom, {}))).toContain('data-reduced="false"');
+  });
+});

app/src/ui/primitives/usePresence.test.tsx

@@ -12,6 +12,7 @@
  *   ② open 假→真 enter→entered   → "open 假→真：…"
  *   ③ 已 entered 后真→假         → "已 entered 后 open 真→假：…"
  *   ④ 本节点 transitionend 卸载  → "出场期间收到本节点 transitionend：…"
+ *   ④' 未进场就关闭（表外边界④） → "进场未完成（下一 tick 未到）就关闭：…"
  *   ⑤ 出场期间反向（可中断可反向）→ "出场期间 open 又回 true：…"
  *   ⑥ 兜底计时器到点卸载         → "没有 transitionend 时兜底到点卸载：…" + "默认兜底窗口…"
  *   ⑦ reducedMotion=true 直跳终态 → "reducedMotion 命中：…"
@@ -137,6 +138,17 @@ describe("状态机（计划 Task 6 表 9 行逐行）", () => {
     expect(vi.getTimerCount(), "transitionend 到达后兜底计时器应被清掉").toBe(0);
   });
 
+  it("④' 进场未完成（下一 tick 未到）就关闭：不排退场窗口、清掉进场计时器、立即卸载", () => {
+    const { result, rerender } = setup(false);
+    rerender({ open: true });
+    expect(result.current.phase).toBe("enter");
+    expect(vi.getTimerCount(), "此时只有「下一 tick 进球」计时器在跑").toBe(1);
+    rerender({ open: false });
+    expect(result.current.mounted, "一次绘制都没发生过 ⇒ 没有可退的场，直接卸载").toBe(false);
+    expect(result.current.phase).toBe("exit");
+    expect(vi.getTimerCount(), "既不排退场窗口，也必须清掉进场计时器").toBe(0);
+  });
+
   it("⑥ 没有 transitionend 时兜底到点卸载（reduced-motion 下永不触发 transitionend 的防线）", () => {
     // 注入 exitMs/timeoutSlackMs ⇒ 兜底窗口可测、不真 sleep
     const { result, rerender } = setup(true, { exitMs: 1000, timeoutSlackMs: 20 });

app/src/ui/primitives/usePresence.ts

@@ -36,6 +36,13 @@ export type PresencePhase = "enter" | "entered" | "exit";
  * `transitionend` 事件的**最小结构契约**。React 的 `TransitionEvent<T>` 结构上满足它
  * （`target` / `currentTarget` 都赋给 `unknown`），故消费方可直接 `onTransitionEnd={onTransitionEnd}`；
  * 测试也用普通对象构造事件 —— 不需要真元素、不需要真过渡（类型层断言见 `usePresence.test.tsx`）。
+ *
+ * **为什么不需要 `propertyName`**：本 hook 只判两件事 ——「是不是本节点自己的过渡」（`target ===
+ * currentTarget`）与「当前相位是不是 `exit`」，而"哪个属性结束了"由**同元素等时长**对冲：Modal /
+ * ConfirmDialog / Toast 的进出场属性都写在**同一个元素**上、时长同取 `--ed-dur-overlay-*` /
+ * `--ed-dur-toast-*`，故任一属性的 `transitionend` 都等价于「本节点退场结束」，多接一个字段只会让
+ * 消费方的类型面更脏。⚠️ 若将来出现「同元素多属性、时长不等」的场景（例如遮罩与面板分开计时），
+ * 才需要把 `propertyName` 纳入契约 —— 那时须连 T7/T9 的挂载点一起改（本注释就是那条触发条件）。
  */
 export interface TransitionEndLike {
   readonly target: unknown;