fix(frontend): Drawer 焦点还原提取 useRestoreFocus + 回归测试 + DRY（CR-H11）

apps/web/lib/a11y/useRestoreFocus.test.ts

@@ -0,0 +1,65 @@
+// @vitest-environment jsdom
+import { renderHook } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+import type { RefObject } from "react";
+
+import { useRestoreFocus } from "./useRestoreFocus";
+
+const appended: HTMLElement[] = [];
+
+function mountEl<T extends HTMLElement>(el: T): T {
+  document.body.appendChild(el);
+  appended.push(el);
+  return el;
+}
+
+afterEach(() => {
+  for (const el of appended.splice(0)) el.remove();
+});
+
+describe("useRestoreFocus（CR-H11）", () => {
+  it("关闭时把焦点还给 triggerRef", () => {
+    const trigger = mountEl(document.createElement("button"));
+    const other = mountEl(document.createElement("input"));
+    const ref: RefObject<HTMLElement | null> = { current: trigger };
+
+    const { rerender } = renderHook(
+      ({ open }) => useRestoreFocus(open, ref),
+      { initialProps: { open: true } },
+    );
+
+    other.focus();
+    expect(document.activeElement).toBe(other);
+
+    rerender({ open: false });
+    expect(document.activeElement).toBe(trigger);
+  });
+
+  it("从未打开过：关闭态不抢焦点（wasOpen 门闩）", () => {
+    const trigger = mountEl(document.createElement("button"));
+    const other = mountEl(document.createElement("input"));
+    const ref: RefObject<HTMLElement | null> = { current: trigger };
+
+    renderHook(({ open }) => useRestoreFocus(open, ref), {
+      initialProps: { open: false },
+    });
+
+    other.focus();
+    expect(document.activeElement).toBe(other);
+  });
+
+  it("triggerRef 为 null / undefined 时关闭不抛错", () => {
+    const nullRef: RefObject<HTMLElement | null> = { current: null };
+    const nullCase = renderHook(
+      ({ open }) => useRestoreFocus(open, nullRef),
+      { initialProps: { open: true } },
+    );
+    expect(() => nullCase.rerender({ open: false })).not.toThrow();
+
+    const undefCase = renderHook(
+      ({ open }) => useRestoreFocus(open, undefined),
+      { initialProps: { open: true } },
+    );
+    expect(() => undefCase.rerender({ open: false })).not.toThrow();
+  });
+});

apps/web/lib/a11y/useRestoreFocus.ts

@@ -0,0 +1,24 @@
+"use client";
+
+import { useEffect, useRef, type RefObject } from "react";
+
+// 弹层（Drawer / ContextDrawer）关闭后把焦点还给触发元素（a11y 焦点管理，CR-H11）。
+// wasOpenRef 门闩：仅在「曾打开过」后的关闭才还原，避免从未打开时误抢焦点。
+// null-safe：triggerRef 或其 current 为空时静默跳过。
+export function useRestoreFocus(
+  open: boolean,
+  triggerRef?: RefObject<HTMLElement | null>,
+): void {
+  const wasOpenRef = useRef(false);
+
+  useEffect(() => {
+    if (!open) {
+      if (wasOpenRef.current) {
+        wasOpenRef.current = false;
+        triggerRef?.current?.focus();
+      }
+      return;
+    }
+    wasOpenRef.current = true;
+  }, [open, triggerRef]);
+}