feat: add global Esc stack for consistent modal handling

- Introduced `grModalEscStack` to centralize Esc key handling for modals across different render trees.
- Updated `GrModal` to integrate with the new Esc stack, ensuring only the topmost modal is closed on Esc.
- Added unit tests for `grModalEscStack` to validate behavior in various edge cases.

Author: fureev

packages/granularity/src/components/GrModal/GrModal.vue

@@ -11,13 +11,19 @@
  *   `DialogTitle` / `DialogDescription` (связь через `aria-labelledby` /
  *   `aria-describedby` ставится HeadlessUI автоматически).
  *
- * Esc обрабатывается штатно через событие `@close` у HeadlessUI `<Dialog>`,
- * чтобы не конфликтовать с его внутренней логикой. Источник закрытия
- * различается через ref `closeReasonRef`.
+ * Esc обрабатывается через общий стек открытых модалок (`grModalEscStack`):
+ * единый capture-обработчик на `window` закрывает только верхнюю (последнюю
+ * открытую) модалку и опережает window-обработчик Escape HeadlessUI. Это
+ * чинит кейс, когда поверх `GrModal` открыт диалог `useDialogService` (другое
+ * дерево рендера): Esc закрывает именно верхний диалог, а не нижнее окно.
+ * Клик по оверлею (backdrop) по-прежнему идёт через `@close` HeadlessUI;
+ * источник закрытия различается через ref `closeReason`.
  */
 import { computed, onBeforeUnmount, ref, watch } from 'vue'
 import { Dialog, DialogDescription, DialogPanel, DialogTitle, TransitionChild, TransitionRoot } from '@headlessui/vue'
 
+import { pushGrModalEsc, removeGrModalEsc } from './grModalEscStack'
+
 import {
   type GrModalSize,
   getGrModalPanelClass,
@@ -78,6 +84,25 @@ function onRootKeydown(event: KeyboardEvent): void {
   if (event.key === 'Escape') closeReason.value = 'esc'
 }
 
+// ————— Esc-стек: гарантирует, что Esc закрывает именно верхнюю (последнюю
+// открытую) модалку, даже если окна живут в разных деревьях рендера
+// (например, диалоги `useDialogService` поверх `GrModal`).
+let escEntryId: number | null = null
+
+function registerEsc(): void {
+  if (escEntryId !== null) return
+  escEntryId = pushGrModalEsc({
+    shouldClose: () => props.closeOnEsc,
+    close,
+  })
+}
+
+function unregisterEsc(): void {
+  if (escEntryId === null) return
+  removeGrModalEsc(escEntryId)
+  escEntryId = null
+}
+
 function onOverlayPointerDown(): void {
   closeReason.value = 'backdrop'
 }
@@ -104,13 +129,22 @@ function unlockBodyScroll(): void {
 watch(
   () => props.modelValue,
   (value) => {
-    if (value) lockBodyScroll()
-    else unlockBodyScroll()
+    if (value) {
+      lockBodyScroll()
+      registerEsc()
+    }
+    else {
+      unlockBodyScroll()
+      unregisterEsc()
+    }
   },
   { immediate: true },
 )
 
-onBeforeUnmount(unlockBodyScroll)
+onBeforeUnmount(() => {
+  unlockBodyScroll()
+  unregisterEsc()
+})
 
 </script>
 

packages/granularity/src/components/GrModal/__tests__/grModalEscStack.test.ts

@@ -0,0 +1,75 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+import {
+  pushGrModalEsc,
+  removeGrModalEsc,
+  resetGrModalEscStack,
+} from '../grModalEscStack'
+
+function pressEscape(): KeyboardEvent {
+  const event = new KeyboardEvent('keydown', {
+    key: 'Escape',
+    bubbles: true,
+    cancelable: true,
+  })
+  window.dispatchEvent(event)
+  return event
+}
+
+describe('granularity/GrModal grModalEscStack (unit)', () => {
+  afterEach(() => {
+    resetGrModalEscStack()
+  })
+
+  it('Esc закрывает только верхнюю (последнюю зарегистрированную) модалку', () => {
+    const closeBottom = vi.fn()
+    const closeTop = vi.fn()
+
+    pushGrModalEsc({ shouldClose: () => true, close: closeBottom })
+    pushGrModalEsc({ shouldClose: () => true, close: closeTop })
+
+    pressEscape()
+
+    expect(closeTop).toHaveBeenCalledTimes(1)
+    expect(closeBottom).not.toHaveBeenCalled()
+  })
+
+  it('после закрытия верхней модалки Esc адресуется следующей по стеку', () => {
+    const closeBottom = vi.fn()
+    const closeTop = vi.fn()
+
+    pushGrModalEsc({ shouldClose: () => true, close: closeBottom })
+    const topId = pushGrModalEsc({ shouldClose: () => true, close: closeTop })
+
+    pressEscape()
+    removeGrModalEsc(topId)
+    pressEscape()
+
+    expect(closeTop).toHaveBeenCalledTimes(1)
+    expect(closeBottom).toHaveBeenCalledTimes(1)
+  })
+
+  it('Esc гасится (preventDefault), но не закрывает верхнюю модалку при shouldClose=false', () => {
+    const closeBottom = vi.fn()
+    const closeTop = vi.fn()
+
+    pushGrModalEsc({ shouldClose: () => true, close: closeBottom })
+    pushGrModalEsc({ shouldClose: () => false, close: closeTop })
+
+    const event = pressEscape()
+
+    expect(closeTop).not.toHaveBeenCalled()
+    expect(closeBottom).not.toHaveBeenCalled()
+    expect(event.defaultPrevented).toBe(true)
+  })
+
+  it('после опустошения стека обработчик снимается и Esc игнорируется', () => {
+    const close = vi.fn()
+    const id = pushGrModalEsc({ shouldClose: () => true, close })
+    removeGrModalEsc(id)
+
+    pressEscape()
+
+    expect(close).not.toHaveBeenCalled()
+  })
+})

packages/granularity/src/components/GrModal/grModalEscStack.ts

@@ -0,0 +1,83 @@
+/**
+ * grModalEscStack — общий стек открытых `GrModal` для корректной обработки Esc.
+ *
+ * Зачем нужен:
+ * HeadlessUI вешает обработчик Escape на `window` у каждого открытого `<Dialog>`.
+ * Когда модалки рендерятся в разных деревьях приложения (например, диалоги
+ * `useDialogService` монтируются отдельным `render()` в `document.body`), их
+ * HeadlessUI-стек не общий, и каждый `<Dialog>` считает себя верхним. В итоге
+ * Esc перехватывает обработчик той модалки, что смонтирована раньше (нижней),
+ * а реально верхнее окно (последнее открытое) остаётся.
+ *
+ * Решение: единый capture-обработчик на `window`, который срабатывает раньше
+ * обработчиков HeadlessUI, гасит событие (`stopImmediatePropagation`) и
+ * закрывает только верхнюю (последнюю зарегистрированную) модалку. Так Esc
+ * всегда адресуется верхнему окну независимо от дерева рендера.
+ */
+
+export interface GrModalEscEntry {
+  /** Уникальный id зарегистрированной модалки. */
+  id: number
+  /** Должна ли модалка закрываться по Esc (реактивный геттер `closeOnEsc`). */
+  shouldClose: () => boolean
+  /** Закрыть модалку (эмит `update:modelValue=false`). */
+  close: () => void
+}
+
+const stack: GrModalEscEntry[] = []
+let listening = false
+let nextId = 1
+
+function handleKeydown(event: KeyboardEvent): void {
+  if (event.key !== 'Escape') return
+  if (stack.length === 0) return
+
+  // Верхняя модалка — последняя зарегистрированная.
+  const top = stack[stack.length - 1]
+
+  // Перехватываем Esc раньше HeadlessUI и нижних модалок: даже если верхнее
+  // окно не закрывается (`closeOnEsc=false`), событие не должно «проваливаться»
+  // к нижним окнам.
+  event.preventDefault()
+  event.stopPropagation()
+  if (typeof event.stopImmediatePropagation === 'function')
+    event.stopImmediatePropagation()
+
+  if (top.shouldClose()) top.close()
+}
+
+function startListening(): void {
+  if (listening) return
+  if (typeof window === 'undefined') return
+  // Capture-фаза, чтобы опередить window-обработчик Escape HeadlessUI.
+  window.addEventListener('keydown', handleKeydown, true)
+  listening = true
+}
+
+function stopListening(): void {
+  if (!listening) return
+  if (typeof window === 'undefined') return
+  window.removeEventListener('keydown', handleKeydown, true)
+  listening = false
+}
+
+/** Регистрирует открытую модалку как верхнюю и возвращает её id. */
+export function pushGrModalEsc(entry: Omit<GrModalEscEntry, 'id'>): number {
+  const id = nextId++
+  stack.push({ ...entry, id })
+  startListening()
+  return id
+}
+
+/** Снимает модалку со стека (при закрытии или размонтировании). */
+export function removeGrModalEsc(id: number): void {
+  const index = stack.findIndex(item => item.id === id)
+  if (index >= 0) stack.splice(index, 1)
+  if (stack.length === 0) stopListening()
+}
+
+/** Тестовая/служебная очистка стека. */
+export function resetGrModalEscStack(): void {
+  stack.splice(0, stack.length)
+  stopListening()
+}