iter(g27): 抽出弹层 Esc 栈，多弹层只关最上层

packages/skin/ui/src/drawer.ts

@@ -1,5 +1,6 @@
 import { effect, h } from '@ui-arch/frame';
 import type { DrawerProps } from './types.js';
+import { pushOverlay } from './overlay.js';
 
 /*** 抽屉：open 信号驱动侧滑面板，点遮罩 / × / Esc 关闭；Tab 焦点陷阱 + 关闭归还焦点，与 modal 的分工是不打断主视图、可从侧边保留上下文 ***/
 export function drawer(props: DrawerProps, ...children: unknown[]): HTMLElement {
@@ -29,15 +30,19 @@ export function drawer(props: DrawerProps, ...children: unknown[]): HTMLElement
   overlay.append(panel);
 
   let lastFocus: HTMLElement | null = null; // 打开前焦点宿主，关闭时归还
+  let release: (() => void) | null = null; // Esc 栈注销函数，关闭时释放
   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; // 记录打开前焦点
+      release ??= pushOverlay(close); // 入 Esc 栈：多弹层时只关最上层
       (panel.querySelector('button, input, textarea') as HTMLElement | null)?.focus(); // 打开时聚焦首个可交互元素
-    } else if (lastFocus) {
-      lastFocus.focus(); // 关闭时归还焦点
+    } else {
+      release?.(); // 出 Esc 栈
+      release = null;
+      lastFocus?.focus(); // 关闭时归还焦点
       lastFocus = null;
     }
   });
@@ -53,8 +58,5 @@ export function drawer(props: DrawerProps, ...children: unknown[]): HTMLElement
       e.preventDefault(); first.focus(); // Tab 到末位时回绕到开头
     }
   });
-  document.addEventListener('keydown', (e: KeyboardEvent) => {
-    if (e.key === 'Escape' && props.open()) close();
-  });
   return overlay;
 }

packages/skin/ui/src/modal.ts

@@ -1,5 +1,6 @@
 import { effect, h } from '@ui-arch/frame';
 import type { ModalProps } from './types.js';
+import { pushOverlay } from './overlay.js';
 
 /*** 弹窗：open 信号驱动显隐，点遮罩、× 或 Esc 触发 onClose；Tab 焦点陷阱 + 关闭归还焦点 ***/
 export function modal(props: ModalProps, ...children: unknown[]): HTMLElement {
@@ -23,6 +24,7 @@ export function modal(props: ModalProps, ...children: unknown[]): HTMLElement {
   );
   overlay.append(box);
   let lastFocus: HTMLElement | null = null; // 打开前焦点宿主，关闭时归还
+  let release: (() => void) | null = null; // Esc 栈注销函数，关闭时释放
   const focusables = (): HTMLElement[] =>
     Array.from(box.querySelectorAll<HTMLElement>('button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'))
       .filter((el) => !el.hasAttribute('disabled')); // 弹窗内可聚焦元素（排除禁用）
@@ -31,9 +33,12 @@ export function modal(props: ModalProps, ...children: unknown[]): HTMLElement {
     overlay.classList.toggle('ua-open', open); // 显隐跟随信号
     if (open) {
       lastFocus = document.activeElement as HTMLElement | null; // 记录打开前焦点
+      release ??= pushOverlay(close); // 入 Esc 栈：多弹层时只关最上层
       (box.querySelector('button, input, textarea') as HTMLElement | null)?.focus(); // 打开时聚焦首个可交互元素
-    } else if (lastFocus) {
-      lastFocus.focus(); // 关闭时归还焦点
+    } else {
+      release?.(); // 出 Esc 栈
+      release = null;
+      lastFocus?.focus(); // 关闭时归还焦点
       lastFocus = null;
     }
   });
@@ -49,8 +54,5 @@ export function modal(props: ModalProps, ...children: unknown[]): HTMLElement {
       e.preventDefault(); first.focus(); // Tab 到末位时回绕到开头
     }
   });
-  document.addEventListener('keydown', (e: KeyboardEvent) => {
-    if (e.key === 'Escape' && props.open()) close(); // Esc 关闭当前打开的弹窗
-  });
   return overlay;
 }

packages/skin/ui/src/overlay.ts

@@ -0,0 +1,32 @@
+/*** 弹层键盘栈：维护打开顺序，Esc 只关最上层，避免多个弹层（含嵌套）被一次全关 ***/
+
+// —— 状态集中声明 ——
+const stack: { close: () => void }[] = []; // 打开中的弹层，后进先出
+let bound = false; // 全局 keydown 监听只挂一次，栈空时摘除
+
+/*** 全局 Esc 分发：只把事件交给栈顶弹层，其余保持不动 ***/
+const onKeydown = (e: KeyboardEvent) => {
+  if (e.key !== 'Escape') return; // 卫语句：只关心 Esc
+  const top = stack[stack.length - 1];
+  if (!top) return; // 卫语句：栈空无事可做
+  e.preventDefault();
+  top.close();
+};
+
+/*** 注册一个打开的弹层，返回注销函数（弹层关闭时务必调用，否则栈不清理） ***/
+export function pushOverlay(close: () => void): () => void {
+  if (!bound) {
+    document.addEventListener('keydown', onKeydown); // 首个弹层才挂全局监听
+    bound = true;
+  }
+  const entry = { close };
+  stack.push(entry);
+  return () => {
+    const i = stack.indexOf(entry);
+    if (i >= 0) stack.splice(i, 1); // 出栈：允许非栈顶关闭
+    if (!stack.length && bound) {
+      document.removeEventListener('keydown', onKeydown); // 栈空摘监听，避免泄漏
+      bound = false;
+    }
+  };
+}

packages/skin/ui/ua.manifest.json

@@ -1270,9 +1270,10 @@
         "steps": [
           "创建布尔信号 open = signal(false)，弹窗初始隐藏",
           "把 open 传给 modal，其余参数为弹窗内容子节点",
-          "打开：open(true)；关闭：open(false)，点遮罩或 × 会自动写回 false",
+          "打开：open(true)；关闭：open(false)，点遮罩、× 或 Esc 会自动写回 false；多弹层叠加时 Esc 只关最上层（后开先关）",
           "入场自带遮罩淡入 + 弹窗上浮动画",
-          "底部操作按钮放进 footer（如取消/确定），需要更宽内容用 size: 'lg'，窄确认框用 'sm'"
+          "底部操作按钮放进 footer（如取消/确定），需要更宽内容用 size: 'lg'，窄确认框用 'sm'",
+          "打开后 Tab 焦点锁在弹窗内，关闭自动把焦点还给打开前的元素"
         ]
       },
       {
@@ -1325,7 +1326,7 @@
         "steps": [
           "创建布尔信号 open = signal(false)，传给 drawer；其余参数为面板内容子节点",
           "打开后从侧边滑出：placement: 'right'（默认）或 'left'，width 控制宽度（窄屏自动收到 92vw）",
-          "点遮罩、× 或按 Esc 关闭并写回 false；打开时焦点落在面板首个可交互元素",
+          "点遮罩、× 或按 Esc 关闭并写回 false；打开时焦点落在面板首个可交互元素，Esc 只关最上层弹层",
           "底部操作按钮放进 footer；与 modal 的分工：modal 是强打断的确认，drawer 保留主视图上下文做详情/编辑",
           "面板内容与 modal 一样接受任意 DOM 与响应式函数"
         ]