iter(g102): 焦点陷阱下沉为共享助手

.ua/backlog.json

@@ -1172,6 +1172,14 @@
       "acceptance": "新增 anchor(props)（packages/skin/ui/src/anchor.ts，< 200 行）：items/href/title/disabled、offset 偏移量、container 内滚容器、onChange 回调；滚动按目标位置高亮并同步 aria-current，点击平滑定位 + replaceState 回写 hash，prefers-reduced-motion 下瞬移；types/manifest/index/ui.css/demo/README/AGENTS/ARCHITECTURE 同步，npm run check 全绿",
       "notes": "自补：组件补充；样式全走令牌，选出态维持低视觉比重（accent 10% 底色 + 左侧 2px 指示条）",
       "status": "done"
+    },
+    {
+      "id": "g102",
+      "title": "焦点陷阱下沉为共享助手，图片预览接上",
+      "motivation": "modal 与 drawer 各自复制了一份 25 行的 Tab 焦点陷阱（focusables + keydown 环形回绕），改一处漏一处；image 的全屏预览层是 role=dialog aria-modal，却完全没有焦点陷阱也没把焦点移进去，键盘用户 Tab 一下就穿到背后的页面",
+      "acceptance": "overlay.ts 新增 trapFocus(box, isOpen)：Tab / Shift+Tab 首尾环形，有无可用焦点与焦点在容器外的两种情况都拦回；modal / drawer 删掉本地实现改为调用（行为不变）；image 预览层补 tabindex=-1 + 打开即聚焦 + 全程锁焦点；npm run check 全绿",
+      "notes": "自补：一致性与无障碍；陷阱实现单一来源，后续新增模态层直接复用",
+      "status": "open"
     }
   ]
 }

packages/skin/ui/src/drawer.ts

@@ -1,6 +1,6 @@
 import { effect, h } from '@ui-arch/frame';
 import type { DrawerProps } from './types.js';
-import { lockScroll, pushOverlay } from './overlay.js';
+import { lockScroll, pushOverlay, trapFocus } from './overlay.js';
 
 let seq = 0; // 实例序号：给标题生成唯一 id，供 aria-labelledby 关联
 
@@ -38,9 +38,6 @@ export function drawer(props: DrawerProps, ...children: unknown[]): HTMLElement
   let lastFocus: HTMLElement | null = null; // 打开前焦点宿主，关闭时归还
   let release: (() => void) | null = null; // Esc 栈注销函数，关闭时释放
   let releaseLock: (() => void) | null = null; // 背景滚动锁解锁函数，全关才还原
-  const focusables = (): HTMLElement[] =>
-    Array.from(panel.querySelectorAll<HTMLElement>('button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'))
-      .filter((el) => !el.hasAttribute('disabled')); // 面板内可聚焦元素（排除禁用）
   effect(() => {
     if (props.open()) {
       lastFocus = document.activeElement as HTMLElement | null; // 记录打开前焦点
@@ -56,17 +53,6 @@ export function drawer(props: DrawerProps, ...children: unknown[]): HTMLElement
       lastFocus = null;
     }
   });
-  overlay.addEventListener('keydown', (e: KeyboardEvent) => {
+  trapFocus(panel, () => props.open()); // Tab 焦点陷阱：与 modal 共用同一份实现
-    if (e.key !== 'Tab' || !props.open()) return; // 仅处理打开中的 Tab
-    const els = focusables();
-    if (els.length === 0) { e.preventDefault(); return; } // 无可聚焦元素：拦截 Tab 防焦点逃逸
-    const first = els[0];
-    const last = els[els.length - 1];
-    if (e.shiftKey && (document.activeElement === first || !panel.contains(document.activeElement))) {
-      e.preventDefault(); last.focus(); // Shift+Tab 到首位时回绕到末尾
-    } else if (!e.shiftKey && (document.activeElement === last || !panel.contains(document.activeElement))) {
-      e.preventDefault(); first.focus(); // Tab 到末位时回绕到开头
-    }
-  });
   return overlay;
 }

packages/skin/ui/src/image.ts

@@ -1,5 +1,5 @@
 import { h } from '@ui-arch/frame';
-import { lockScroll, pushOverlay } from './overlay.js';
+import { lockScroll, pushOverlay, trapFocus } from './overlay.js';
 import type { ImageProps } from './types.js';
 
 /*** 图片：缩略图展示，点击 / 回车打开遮罩大图预览（Esc 或点击遮罩关闭），加载失败自动落占位；样式只消费 --ua-* 令牌 ***/
@@ -30,7 +30,7 @@ function openViewer(src: string, alt?: string): void {
   const prev = document.activeElement as HTMLElement | null; // 焦点归还目标
   const mask = h(
     'div',
-    { class: 'ua-image-mask', role: 'dialog', 'aria-modal': 'true', 'aria-label': '图片预览' },
+    { class: 'ua-image-mask', role: 'dialog', 'aria-modal': 'true', 'aria-label': '图片预览', tabindex: '-1' },
     h('img', { class: 'ua-image-full', src, alt: alt ?? '' }),
   );
   const close = () => {
@@ -41,5 +41,7 @@ function openViewer(src: string, alt?: string): void {
   };
   mask.addEventListener('click', close);
   releaseEsc = pushOverlay(close); // 入 Esc 栈：预览层压在最上面，Esc 先关它
+  trapFocus(mask, () => true); // 预览层常开：Tab 全程锁在遮罩内（层内无控件，等于整体拦截）
   document.body.appendChild(mask);
+  mask.focus(); // 焦点移入预览层，读屏与键盘都不再落在背后的页面
 }

packages/skin/ui/src/modal.ts

@@ -1,6 +1,6 @@
 import { effect, h } from '@ui-arch/frame';
 import type { ModalProps } from './types.js';
-import { lockScroll, pushOverlay } from './overlay.js';
+import { lockScroll, pushOverlay, trapFocus } from './overlay.js';
 
 let seq = 0; // 实例序号：给标题生成唯一 id，供 aria-labelledby 关联
 
@@ -31,9 +31,6 @@ export function modal(props: ModalProps, ...children: unknown[]): HTMLElement {
   let lastFocus: HTMLElement | null = null; // 打开前焦点宿主，关闭时归还
   let release: (() => void) | null = null; // Esc 栈注销函数，关闭时释放
   let releaseLock: (() => void) | null = null; // 背景滚动锁解锁函数，全关才还原
-  const focusables = (): HTMLElement[] =>
-    Array.from(box.querySelectorAll<HTMLElement>('button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'))
-      .filter((el) => !el.hasAttribute('disabled')); // 弹窗内可聚焦元素（排除禁用）
   effect(() => {
     const open = props.open();
     overlay.classList.toggle('ua-open', open); // 显隐跟随信号
@@ -51,17 +48,6 @@ export function modal(props: ModalProps, ...children: unknown[]): HTMLElement {
       lastFocus = null;
     }
   });
-  overlay.addEventListener('keydown', (e: KeyboardEvent) => {
+  trapFocus(box, () => props.open()); // Tab 焦点陷阱：与 drawer 共用同一份实现
-    if (e.key !== 'Tab' || !props.open()) return; // 仅处理打开中的 Tab
-    const els = focusables();
-    if (els.length === 0) { e.preventDefault(); return; } // 无可聚焦元素：拦截 Tab 防焦点逃逸
-    const first = els[0];
-    const last = els[els.length - 1];
-    if (e.shiftKey && (document.activeElement === first || !box.contains(document.activeElement))) {
-      e.preventDefault(); last.focus(); // Shift+Tab 到首位时回绕到末尾
-    } else if (!e.shiftKey && (document.activeElement === last || !box.contains(document.activeElement))) {
-      e.preventDefault(); first.focus(); // Tab 到末位时回绕到开头
-    }
-  });
   return overlay;
 }

packages/skin/ui/src/overlay.ts

@@ -65,3 +65,24 @@ export function lockScroll(): () => void {
     if (locks === 0) document.body.style.overflow = ''; // 全关解锁
   };
 }
+
+/*** 焦点陷阱：Tab / Shift+Tab 在容器内首尾环形循环，容器内无可用焦点时整体拦截；焦点已在容器外则按方向拉回首尾 ***/
+export function trapFocus(box: HTMLElement, isOpen: () => boolean): void {
+  box.addEventListener('keydown', (e: KeyboardEvent) => {
+    if (e.key !== 'Tab' || !isOpen()) return; // 卫语句：只处理打开中的 Tab
+    const els = Array.from(box.querySelectorAll<HTMLElement>('button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'))
+      .filter((el) => !el.hasAttribute('disabled')); // 容器内可聚焦元素（排除禁用）
+    if (!els.length) { e.preventDefault(); return; } // 卫语句：无可用焦点就整体拦截，防焦点逃逸
+    const first = els[0];
+    const last = els[els.length - 1];
+    const active = document.activeElement;
+    const outside = !box.contains(active); // 焦点落在容器外：按方向重新拉回，而不是让它继续往外跑
+    if (e.shiftKey && (active === first || outside)) {
+      e.preventDefault();
+      last.focus(); // Shift+Tab 到首位回绕到末尾
+    } else if (!e.shiftKey && (active === last || outside)) {
+      e.preventDefault();
+      first.focus(); // Tab 到末位回绕到开头
+    }
+  });
+}