iter(g43): select/menu/popover/image 的 Esc 接入统一弹层栈

.ua/backlog.json

@@ -701,5 +701,7 @@
       "status": "done",
       "notes": "自补：组件补充；新增 sec-pagination 演示区块"
     }
+  ,
+    { "id": "g43", "title": "select/menu/popover/image 的 Esc 接入统一弹层栈", "motivation": "四个弹层组件各自监听 document 的 Esc：多层叠加（如 popover 内再开 image 预览）时一次 Esc 全部关闭，与 modal/drawer 的 pushOverlay 栈行为不一致", "acceptance": "四个组件展开期入 Esc 栈、收起即释放；多层叠加时 Esc 后进先出逐层关闭；焦点归还触发器；npm run check 全绿", "status": "done", "notes": "自补：一致性修复；复用 overlay.ts 的 pushOverlay 栈" }
   ]
 }

packages/skin/ui/src/image.ts

@@ -1,4 +1,5 @@
 import { h } from '@ui-arch/frame';
+import { pushOverlay } from './overlay.js';
 import type { ImageProps } from './types.js';
 
 /*** 图片：缩略图展示，点击 / 回车打开遮罩大图预览（Esc 或点击遮罩关闭），加载失败自动落占位；样式只消费 --ua-* 令牌 ***/
@@ -24,6 +25,7 @@ export function image(props: ImageProps): HTMLElement {
 
 /*** 打开全屏遮罩预览层；关闭时自清理、解绑键盘并归还焦点 ***/
 function openViewer(src: string, alt?: string): void {
+  let releaseEsc: (() => void) | null = null; // Esc 栈注销函数：预览层占一层，关闭即释放
   const prev = document.activeElement as HTMLElement | null; // 焦点归还目标
   const mask = h(
     'div',
@@ -31,12 +33,11 @@ function openViewer(src: string, alt?: string): void {
     h('img', { class: 'ua-image-full', src, alt: alt ?? '' }),
   );
   const close = () => {
-    mask.remove(); // 卫语句式自清理：遮罩移除 + 键盘解绑 + 焦点归还
+    mask.remove(); // 自清理：遮罩移除 + 出 Esc 栈 + 焦点归还
-    document.removeEventListener('keydown', onKey);
+    releaseEsc?.();
     prev?.focus?.();
   };
-  const onKey = (e: KeyboardEvent) => { if (e.key !== 'Escape') return; e.stopPropagation(); close(); }; // 预览层 Esc 自关，不连带关外层
   mask.addEventListener('click', close);
-  document.addEventListener('keydown', onKey);
+  releaseEsc = pushOverlay(close); // 入 Esc 栈：预览层压在最上面，Esc 先关它
   document.body.appendChild(mask);
 }

packages/skin/ui/src/menu.ts

@@ -1,11 +1,13 @@
 import { effect, h, signal } from '@ui-arch/frame';
 import type { MenuItem, MenuProps } from './types.js';
 import { flip } from './position.js';
+import { pushOverlay } from './overlay.js';
 
 /*** 下拉菜单：触发器 + 自绘弹层，项支持禁用 / 危险 / 分隔线；点项 / 点外部 / Esc 关闭，↑↓ 环形导航 + Home/End 跳转 + 键入快跳 ***/
 export function menu(props: MenuProps): HTMLElement {
   // —— 状态集中声明 ——
   const open = signal(false);              // 弹层开合
+  let releaseEsc: (() => void) | null = null; // Esc 栈注销函数：展开期间占一层，收起即释放
   const place = signal<'top' | 'bottom'>('bottom'); // 实际生效方位：打开时按视口空间自动翻转
   const focusables: HTMLButtonElement[] = []; // 可聚焦项（跳过分隔线与禁用项），供键盘导航
   const labels: string[] = [];             // 与 focusables 平行的条目文案，供键入快跳
@@ -72,12 +74,6 @@ export function menu(props: MenuProps): HTMLElement {
   };
 
   root.addEventListener('keydown', (e: KeyboardEvent) => {
-    if (e.key === 'Escape') {
-      e.stopPropagation();                 // 只关本层：不再冒泡去关外层的弹窗/抽屉
-      open(false);
-      trigger.focus();                     // 收起后焦点回到触发器，键盘流不断
-      return;
-    }
     if (e.key === 'Home' && open()) { e.preventDefault(); focusables[0]?.focus(); return; } // Home 跳首项
     if (e.key === 'End' && open()) { e.preventDefault(); focusables[focusables.length - 1]?.focus(); return; } // End 跳末项
     if (e.key !== 'ArrowDown' && e.key !== 'ArrowUp') {
@@ -100,7 +96,14 @@ export function menu(props: MenuProps): HTMLElement {
     open(false);                                 // 点外部收起
   });
 
-  effect(() => open()); // 建立依赖，保证开合信号生效
+  effect(() => {
+    if (open()) {
+      releaseEsc ??= pushOverlay(() => { open(false); trigger.focus(); }); // 入 Esc 栈：与弹窗/抽屉共用同一套逐层关闭
+    } else {
+      releaseEsc?.();
+      releaseEsc = null;
+    }
+  });
   effect(() => { if (open()) place(flip(trigger, pop, 'bottom')); }); // 每次打开重算方位：空间不足自动翻转
   return root;
 }

packages/skin/ui/src/popover.ts

@@ -1,6 +1,7 @@
 import { effect, h, signal } from '@ui-arch/frame';
 import type { PopoverProps } from './types.js';
 import { flip } from './position.js';
+import { pushOverlay } from './overlay.js';
 
 let seq = 0; // 全局自增序号：保证每个弹层 id 唯一，供 aria-controls 关联
 
@@ -8,6 +9,7 @@ let seq = 0; // 全局自增序号：保证每个弹层 id 唯一，供 aria-con
 export function popover(props: PopoverProps, trigger: HTMLElement): HTMLElement {
   // —— 状态集中声明 ——
   const open = signal(false);      // 弹层显隐
+  let releaseEsc: (() => void) | null = null; // Esc 栈注销函数：展开期间占一层，收起即释放
   const place = signal(props.placement ?? 'bottom'); // 实际生效方位：打开时按视口空间自动翻转
   const id = `ua-pop-${++seq}`;    // 弹层唯一 id
   let timer: number | null = null; // hover 模式下的出入场计时器
@@ -52,13 +54,16 @@ export function popover(props: PopoverProps, trigger: HTMLElement): HTMLElement
     });
   }
   root.addEventListener('keydown', (e: KeyboardEvent) => {
-    if (e.key !== 'Escape' || !open()) return; // 卫语句：未展开时 Esc 不处理
-    e.stopPropagation();                       // 只关本层，避免连带关闭外层弹窗
-    setOpen(false);
-    trigger.focus();                           // 收起后焦点回触发器
   });
   document.addEventListener('click', () => setOpen(false)); // 点外部收起（弹层内已阻止冒泡）
-  effect(() => { if (open()) place(flip(trigger, panel, props.placement ?? 'bottom')); }); // 每次打开重算方位：空间不足自动翻转
+  effect(() => {
+    if (open()) {
+      releaseEsc ??= pushOverlay(() => { setOpen(false); trigger.focus(); }); // 入 Esc 栈：与弹窗/抽屉共用同一套逐层关闭
+    } else {
+      releaseEsc?.();
+      releaseEsc = null;
+    }
+  });
 
   return root;
 }

packages/skin/ui/src/select.ts

@@ -1,6 +1,7 @@
 import { effect, h, signal } from '@ui-arch/frame';
 import type { SelectProps } from './types.js';
 import { flip } from './position.js';
+import { pushOverlay } from './overlay.js';
 
 /*** 下拉选择：自绘弹层替代原生 select，value 信号双向绑定；searchable 时弹层顶部带搜索框，支持 ↑↓/Home/End 导航与 Esc 关闭 ***/
 export function select(props: SelectProps): HTMLElement {
@@ -10,6 +11,7 @@ export function select(props: SelectProps): HTMLElement {
   const query = signal('');                   // 搜索关键字（仅 searchable 时使用）
   const value = props.value ?? signal('');    // 选中值；未传信号则内部持有
 
+  let releaseEsc: (() => void) | null = null; // Esc 栈注销函数：展开期间占一层，收起即释放
   const labels = props.options.map((o) => o.label); // 文案缓存，供搜索与键入快跳共用
   const labelOf = (v: string) => props.options.find((o) => o.value === v)?.label ?? '';
   const current = () => labelOf(value()); // 触发器显示文案（响应式）
@@ -87,7 +89,6 @@ export function select(props: SelectProps): HTMLElement {
   };
 
   root.addEventListener('keydown', (e: KeyboardEvent) => {
-    if (e.key === 'Escape') { e.stopPropagation(); open(false); trigger.focus(); return; } // Esc 只关本层并回焦触发器
     const list = visibleIdx();
     if (e.key === 'ArrowDown' || e.key === 'ArrowUp') {
       e.preventDefault(); // 阻止页面滚动
@@ -122,6 +123,14 @@ export function select(props: SelectProps): HTMLElement {
       requestAnimationFrame(() => search.focus()); // 搜索模式：打开即聚焦输入框
     }
   });
+  effect(() => {
+    if (open()) {
+      releaseEsc ??= pushOverlay(() => { open(false); trigger.focus(); }); // 入 Esc 栈：与弹窗/抽屉共用同一套逐层关闭
+    } else {
+      releaseEsc?.();
+      releaseEsc = null;
+    }
+  });
   effect(() => { if (open()) place(flip(trigger, pop, 'bottom')); }); // 每次打开重算方位：空间不足自动翻转
   return root;
 }