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

.ua/backlog.json

@@ -572,6 +572,14 @@
       "acceptance": "var(--ua-*) 必须是 tokens.css 已定义或组件自设变量，否则 verify 失败；ua tokens / llms-full 令牌清单统一取 tokens.css（补全字号与复合间距）；npm run check 全绿",
       "status": "done",
       "notes": "自补：门禁改进；负向测试 var(--ua-color-textt) 已被拦截"
+    },
+    {
+      "id": "g27",
+      "title": "弹层 Esc 栈：多弹层只关最上层",
+      "motivation": "modal 与 drawer 各自往 document 挂 keydown，叠加打开时一次 Esc 会把所有弹层全关；实例销毁也不摘监听",
+      "acceptance": "modal/drawer 共用 overlay.ts 的 Esc 栈，后开先关；栈空自动摘全局监听；npm run check 全绿",
+      "status": "open",
+      "notes": "自补：既有组件可用性细节"
     }
   ]
 }

.ua/index.json

@@ -1,6 +1,6 @@
 {
   "$schema": "ui-arch-registry-index/0.1",
-  "generatedAt": "2026-10-26T03:34:43.829Z",
+  "generatedAt": "2026-10-26T03:37:32.721Z",
   "repoRoot": ".",
   "packages": [
     {
@@ -1399,9 +1399,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 焦点锁在弹窗内，关闭自动把焦点还给打开前的元素"
             ]
           },
           {
@@ -1454,7 +1455,7 @@
             "steps": [
               "创建布尔信号 open = signal(false)，传给 drawer；其余参数为面板内容子节点",
               "打开后从侧边滑出：placement: 'right'（默认）或 'left'，width 控制宽度（窄屏自动收到 92vw）",
-              "点遮罩、× 或按 Esc 关闭并写回 false；打开时焦点落在面板首个可交互元素",
+              "点遮罩、× 或按 Esc 关闭并写回 false；打开时焦点落在面板首个可交互元素，Esc 只关最上层弹层",
               "底部操作按钮放进 footer；与 modal 的分工：modal 是强打断的确认，drawer 保留主视图上下文做详情/编辑",
               "面板内容与 modal 一样接受任意 DOM 与响应式函数"
             ]

llms-full.txt

@@ -1,6 +1,6 @@
 # @ui-arch 组件库 Agent 文档（无图形版）
 
-> 自动生成于 2026-10-26T03:34:43.829Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
+> 自动生成于 2026-10-26T03:37:32.721Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
 > 组件 = 普通函数，传 props 返回 DOM；状态用 signal 双向绑定：读 signal() 写 signal(v)。
 
 ## 快速上手
@@ -797,9 +797,10 @@ const open = signal(false); modal({ title: '确认操作', open, onClose: () =>
 
 1. 创建布尔信号 open = signal(false)，弹窗初始隐藏
 2. 把 open 传给 modal，其余参数为弹窗内容子节点
-3. 打开：open(true)；关闭：open(false)，点遮罩或 × 会自动写回 false
+3. 打开：open(true)；关闭：open(false)，点遮罩、× 或 Esc 会自动写回 false；多弹层叠加时 Esc 只关最上层（后开先关）
 4. 入场自带遮罩淡入 + 弹窗上浮动画
 5. 底部操作按钮放进 footer（如取消/确定），需要更宽内容用 size: 'lg'，窄确认框用 'sm'
+6. 打开后 Tab 焦点锁在弹窗内，关闭自动把焦点还给打开前的元素
 
 现场演示：apps/docs/demo.html#sec-tabs-modal
 
@@ -825,7 +826,7 @@ const open = signal(false); drawer({ title: '详情', open, width: 360, onClose:
 
 1. 创建布尔信号 open = signal(false)，传给 drawer；其余参数为面板内容子节点
 2. 打开后从侧边滑出：placement: 'right'（默认）或 'left'，width 控制宽度（窄屏自动收到 92vw）
-3. 点遮罩、× 或按 Esc 关闭并写回 false；打开时焦点落在面板首个可交互元素
+3. 点遮罩、× 或按 Esc 关闭并写回 false；打开时焦点落在面板首个可交互元素，Esc 只关最上层弹层
 4. 底部操作按钮放进 footer；与 modal 的分工：modal 是强打断的确认，drawer 保留主视图上下文做详情/编辑
 5. 面板内容与 modal 一样接受任意 DOM 与响应式函数
 

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) {
+    } else {
-      lastFocus.focus(); // 关闭时归还焦点
+      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) {
+    } else {
-      lastFocus.focus(); // 关闭时归还焦点
+      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 与响应式函数"
         ]