iter(g45): modal/drawer/image 打开时锁定背景滚动

.ua/backlog.json

@@ -705,5 +705,7 @@
     { "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 栈" }
   ,
     { "id": "g44", "title": "accordion 标题行方向键导航", "motivation": "标题是原生 button 只有 Enter/Space，行间移动要靠 Tab 逐个跳，与 tabs/tree 的 ↑↓/Home/End 键盘约定不一致", "acceptance": "↑↓ 在标题行间环形移动、Home/End 首尾直达，均跳过禁用行；焦点不在标题行不拦截；npm run check 全绿", "status": "done", "notes": "自补：可达性对齐；复用环形回绕取模模式" }
+  ,
+    { "id": "g45", "title": "modal/drawer/image 打开时锁定背景滚动", "motivation": "模态弹层开着时背景页面仍可滚动，长页面里滚动会带着遮罩底下内容跑；非模态弹层（select/menu/popover/tooltip）不受影响", "acceptance": "overlay.ts 新增 lockScroll 引用计数：嵌套叠加只由最后一层还原 body；modal/drawer/image 预览接入，关闭即解锁；npm run check 全绿", "status": "done", "notes": "自补：缺陷修复；引用计数避免多层同开时提前解锁" }
   ]
 }

packages/skin/ui/src/drawer.ts

@@ -1,6 +1,6 @@
 import { effect, h } from '@ui-arch/frame';
 import type { DrawerProps } from './types.js';
-import { pushOverlay } from './overlay.js';
+import { lockScroll, pushOverlay } from './overlay.js';
 
 /*** 抽屉：open 信号驱动侧滑面板，点遮罩 / × / Esc 关闭；Tab 焦点陷阱 + 关闭归还焦点，与 modal 的分工是不打断主视图、可从侧边保留上下文 ***/
 export function drawer(props: DrawerProps, ...children: unknown[]): HTMLElement {
@@ -31,6 +31,7 @@ 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')); // 面板内可聚焦元素（排除禁用）
@@ -38,10 +39,13 @@ export function drawer(props: DrawerProps, ...children: unknown[]): HTMLElement
     if (props.open()) {
       lastFocus = document.activeElement as HTMLElement | null; // 记录打开前焦点
       release ??= pushOverlay(close); // 入 Esc 栈：多弹层时只关最上层
+      releaseLock ??= lockScroll(); // 模态期锁背景滚动
       (panel.querySelector('button, input, textarea') as HTMLElement | null)?.focus(); // 打开时聚焦首个可交互元素
     } else {
       release?.(); // 出 Esc 栈
       release = null;
+      releaseLock?.(); // 解锁背景滚动
+      releaseLock = null;
       lastFocus?.focus(); // 关闭时归还焦点
       lastFocus = null;
     }

packages/skin/ui/src/image.ts

@@ -1,5 +1,5 @@
 import { h } from '@ui-arch/frame';
-import { pushOverlay } from './overlay.js';
+import { lockScroll, pushOverlay } from './overlay.js';
 import type { ImageProps } from './types.js';
 
 /*** 图片：缩略图展示，点击 / 回车打开遮罩大图预览（Esc 或点击遮罩关闭），加载失败自动落占位；样式只消费 --ua-* 令牌 ***/
@@ -26,6 +26,7 @@ export function image(props: ImageProps): HTMLElement {
 /*** 打开全屏遮罩预览层；关闭时自清理、解绑键盘并归还焦点 ***/
 function openViewer(src: string, alt?: string): void {
   let releaseEsc: (() => void) | null = null; // Esc 栈注销函数：预览层占一层，关闭即释放
+  const releaseLock = lockScroll(); // 预览期锁背景滚动
   const prev = document.activeElement as HTMLElement | null; // 焦点归还目标
   const mask = h(
     'div',
@@ -35,6 +36,7 @@ function openViewer(src: string, alt?: string): void {
   const close = () => {
     mask.remove(); // 自清理：遮罩移除 + 出 Esc 栈 + 焦点归还
     releaseEsc?.();
+    releaseLock();
     prev?.focus?.();
   };
   mask.addEventListener('click', close);

packages/skin/ui/src/modal.ts

@@ -1,6 +1,6 @@
 import { effect, h } from '@ui-arch/frame';
 import type { ModalProps } from './types.js';
-import { pushOverlay } from './overlay.js';
+import { lockScroll, pushOverlay } from './overlay.js';
 
 /*** 弹窗：open 信号驱动显隐，点遮罩、× 或 Esc 触发 onClose；Tab 焦点陷阱 + 关闭归还焦点 ***/
 export function modal(props: ModalProps, ...children: unknown[]): HTMLElement {
@@ -25,6 +25,7 @@ export function modal(props: ModalProps, ...children: unknown[]): HTMLElement {
   overlay.append(box);
   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')); // 弹窗内可聚焦元素（排除禁用）
@@ -34,10 +35,13 @@ export function modal(props: ModalProps, ...children: unknown[]): HTMLElement {
     if (open) {
       lastFocus = document.activeElement as HTMLElement | null; // 记录打开前焦点
       release ??= pushOverlay(close); // 入 Esc 栈：多弹层时只关最上层
+      releaseLock ??= lockScroll(); // 模态期锁背景滚动
       (box.querySelector('button, input, textarea') as HTMLElement | null)?.focus(); // 打开时聚焦首个可交互元素
     } else {
       release?.(); // 出 Esc 栈
       release = null;
+      releaseLock?.(); // 解锁背景滚动
+      releaseLock = null;
       lastFocus?.focus(); // 关闭时归还焦点
       lastFocus = null;
     }

packages/skin/ui/src/overlay.ts

@@ -30,3 +30,16 @@ export function pushOverlay(close: () => void): () => void {
     }
   };
 }
+
+// —— 背景滚动锁：模态弹层（modal/drawer/image 预览）引用计数，全关才解锁 ——
+let locks = 0; // 活跃模态层数
+
+/*** 模态层打开时调用，返回解锁函数；嵌套叠加时只由最外层还原 body 内联样式 ***/
+export function lockScroll(): () => void {
+  if (locks === 0) document.body.style.overflow = 'hidden'; // 第一层才锁，避免相互覆盖
+  locks++;
+  return () => {
+    locks--;
+    if (locks === 0) document.body.style.overflow = ''; // 全关解锁
+  };
+}