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

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) => {
-    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 到末位时回绕到开头
-    }
-  });
+  trapFocus(panel, () => props.open()); // Tab 焦点陷阱：与 modal 共用同一份实现
   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) => {
-    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 到末位时回绕到开头
-    }
-  });
+  trapFocus(box, () => props.open()); // Tab 焦点陷阱：与 drawer 共用同一份实现
   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 到末位回绕到开头
+    }
+  });
+}