feat(devtools): add openAsModal to use the panel over app modal dialogs

.changeset/open-as-modal.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/devtools': minor
+---
+
+Add the `openAsModal` config option. A dialog opened with `dialog.showModal()` makes the devtools inert. With this option, the open panel moves on top of such a dialog and takes input, and the app dialog is inert until the panel closes. Open the panel with the open hotkey while the dialog is open.

docs/configuration.md

@@ -71,6 +71,12 @@ type KeyboardKey = ModifierKey | (string & {});
 { requireUrlFlag: boolean }
 ```
 
+- `openAsModal` - Moves the open panel on top of a modal dialog of your app. A dialog that you open with `dialog.showModal()` makes the rest of the page inert, the devtools included. While the panel is on top, your dialog is inert. Close the panel to use your dialog again. The trigger is inert while your dialog is open, so open the panel with the open hotkey. The default is `false`.
+
+```ts
+{ openAsModal: boolean }
+```
+
 - `triggerImage` - The image used for the dev tools trigger
 
 ```ts

e2e/apps/react-vite/src/main.tsx

@@ -12,10 +12,24 @@ function App() {
     <>
       <h1>devtools e2e host</h1>
       <input data-testid="text-input" placeholder="type here" />
+      <button
+        data-testid="open-app-dialog"
+        onClick={() =>
+          document.querySelector<HTMLDialogElement>('#app-dialog')!.showModal()
+        }
+      >
+        open app dialog
+      </button>
+      <dialog id="app-dialog" data-testid="app-dialog">
+        <button data-testid="app-dialog-button">inside app dialog</button>
+      </dialog>
       <TanStackDevtools
         config={{
           theme: 'dark',
           requireUrlFlag: new URLSearchParams(location.search).has('gated'),
+          openAsModal: new URLSearchParams(location.search).has(
+            'open-as-modal',
+          ),
         }}
         plugins={[
           {

e2e/apps/react-vite/tests/open-as-modal.spec.ts

@@ -0,0 +1,128 @@
+import { test, expect } from '@playwright/test'
+import { DevtoolsPage, SELECTORS } from '@tanstack/devtools-e2e'
+import type { Page } from '@playwright/test'
+
+// See hotkey.spec.ts: dispatch the exact keydown events of Control+~.
+async function pressOpenHotkey(page: Page) {
+  await page.evaluate(() => {
+    window.dispatchEvent(
+      new KeyboardEvent('keydown', { key: 'Control', ctrlKey: true }),
+    )
+    window.dispatchEvent(
+      new KeyboardEvent('keydown', { key: '~', ctrlKey: true }),
+    )
+    window.dispatchEvent(new KeyboardEvent('keyup', { key: '~' }))
+    window.dispatchEvent(new KeyboardEvent('keyup', { key: 'Control' }))
+  })
+}
+
+/** Whether a click at the center of the close button reaches it. */
+async function closeButtonTakesClicks(page: Page) {
+  const box = await page.getByTestId(SELECTORS.closeButton).boundingBox()
+  return page.evaluate(
+    ([x, y]) =>
+      document
+        .elementFromPoint(x!, y!)
+        ?.closest('[data-testid="tsd-close-button"]') != null,
+    [box!.x + box!.width / 2, box!.y + box!.height / 2],
+  )
+}
+
+test.describe('openAsModal', () => {
+  test('the open panel takes input on top of a modal app dialog', async ({
+    page,
+  }) => {
+    const dt = new DevtoolsPage(page)
+    await dt.goto('/?open-as-modal')
+    await expect(dt.trigger()).toBeVisible()
+    await page.getByTestId('open-app-dialog').click()
+    await expect(page.getByTestId('app-dialog')).toBeVisible()
+
+    await pressOpenHotkey(page)
+    await dt.expectOpen()
+    await expect(
+      page.locator('dialog:modal > [data-testid="tanstack_devtools"]'),
+    ).toHaveCount(1)
+    expect(await closeButtonTakesClicks(page)).toBe(true)
+
+    await dt.closeViaButton()
+    await expect(dt.panel()).toHaveAttribute('data-open', 'false')
+    await expect(
+      page.locator('dialog [data-testid="tanstack_devtools"]'),
+    ).toHaveCount(0)
+    // The app dialog takes input again.
+    await page.getByTestId('app-dialog-button').click()
+    await expect(page.getByTestId('app-dialog-button')).toBeFocused()
+  })
+
+  test('Escape closes the panel and keeps the app dialog open', async ({
+    page,
+  }) => {
+    const dt = new DevtoolsPage(page)
+    await dt.goto('/?open-as-modal')
+    await expect(dt.trigger()).toBeVisible()
+    await page.getByTestId('open-app-dialog').click()
+    await pressOpenHotkey(page)
+    await dt.expectOpen()
+
+    await page.keyboard.press('Escape')
+    await expect(dt.panel()).toHaveAttribute('data-open', 'false')
+    await expect(page.getByTestId('app-dialog')).toBeVisible()
+    await expect(
+      page.locator('dialog [data-testid="tanstack_devtools"]'),
+    ).toHaveCount(0)
+  })
+
+  test('stays on top when the app opens another modal dialog', async ({
+    page,
+  }) => {
+    const dt = new DevtoolsPage(page)
+    await dt.goto('/?open-as-modal')
+    await expect(dt.trigger()).toBeVisible()
+    await page.getByTestId('open-app-dialog').click()
+    await pressOpenHotkey(page)
+    await dt.expectOpen()
+
+    await page.evaluate(() => {
+      const second = document.createElement('dialog')
+      second.textContent = 'second app dialog'
+      document.body.append(second)
+      second.showModal()
+    })
+
+    await expect.poll(() => closeButtonTakesClicks(page)).toBe(true)
+  })
+
+  test('releases the page when an open app dialog is removed', async ({
+    page,
+  }) => {
+    const dt = new DevtoolsPage(page)
+    await dt.goto('/?open-as-modal')
+    await expect(dt.trigger()).toBeVisible()
+    await page.getByTestId('open-app-dialog').click()
+    await pressOpenHotkey(page)
+    await dt.expectOpen()
+
+    // Removed without close(), as when a component unmounts.
+    await page.evaluate(() => document.querySelector('#app-dialog')!.remove())
+
+    await expect(
+      page.locator('dialog [data-testid="tanstack_devtools"]'),
+    ).toHaveCount(0)
+    await expect(page.getByTestId('text-input')).toBeEditable()
+    await page.getByTestId('text-input').fill('works')
+  })
+
+  test('without the option, a modal app dialog blocks the panel', async ({
+    page,
+  }) => {
+    const dt = new DevtoolsPage(page)
+    await dt.goto('/')
+    await expect(dt.trigger()).toBeVisible()
+    await page.getByTestId('open-app-dialog').click()
+
+    await pressOpenHotkey(page)
+    await dt.expectOpen()
+    expect(await closeButtonTakesClicks(page)).toBe(false)
+  })
+})

packages/devtools/src/context/devtools-store.ts

@@ -110,6 +110,14 @@ export type DevtoolsStore = {
      * @default "tanstack-devtools"
      */
     urlFlag: string
+    /**
+     * Whether the open panel moves on top of a modal dialog of the app
+     * (`dialog.showModal()`), which otherwise makes the dev tools inert.
+     * While the panel is on top, the app dialog is inert. Open the panel with
+     * the open hotkey, because the trigger is inert while the dialog is open.
+     * @default false
+     */
+    openAsModal: boolean
     /**
      * The theme of the dev tools
      * @default "dark"
@@ -196,6 +204,7 @@ export const initialState: DevtoolsStore = {
     inspectHotkey: ['Shift', 'Alt', 'CtrlOrMeta'],
     requireUrlFlag: false,
     urlFlag: 'tanstack-devtools',
+    openAsModal: false,
     theme:
       typeof window !== 'undefined' &&
       typeof window.matchMedia !== 'undefined' &&

packages/devtools/src/devtools.tsx

@@ -12,6 +12,7 @@ import {
   createTheme,
 } from './context/use-devtools-context'
 import { createDisableTabbing } from './hooks/use-disable-tabbing'
+import { createModalHost } from './hooks/use-modal-host'
 import { TANSTACK_DEVTOOLS } from './utils/storage'
 import { getHotkeyPermutations } from './utils/hotkey'
 import { Trigger } from './components/trigger'
@@ -150,6 +151,7 @@ export default function DevTools() {
     onCleanup(() => window.removeEventListener('keydown', onKeyDown))
   })
   createDisableTabbing(isOpen)
+  createModalHost(() => settings().openAsModal, rootEl, isOpen)
   createEffect(() => {
     const element = rootEl()
     if (element) {

packages/devtools/src/hooks/use-modal-host.ts

@@ -0,0 +1,98 @@
+import { createEffect, onCleanup } from 'solid-js'
+import type { Accessor } from 'solid-js'
+
+/**
+ * A modal dialog of the app (`dialog.showModal()`) makes the rest of the page
+ * inert, the devtools included, and no z-index or popover gets past that: only
+ * the content of the topmost modal dialog takes input.
+ *
+ * While the panel is open and the app has a modal dialog open, this moves the
+ * devtools root into a modal dialog of its own, shown on top of the app's. It
+ * moves the root back when the panel or the app dialog closes. The app dialog
+ * is inert in the meantime.
+ */
+export function createModalHost(
+  enabled: Accessor<boolean>,
+  root: Accessor<HTMLElement | undefined>,
+  isOpen: Accessor<boolean>,
+) {
+  createEffect(() => {
+    const element = root()
+    if (!enabled() || !element) return
+
+    const doc = element.ownerDocument
+    const host = doc.createElement('dialog')
+    // A zero-size box: the devtools are `position: fixed`, so they still lay
+    // out against the viewport.
+    host.style.cssText =
+      'position:fixed;inset:0;width:0;height:0;max-width:none;max-height:none;margin:0;padding:0;border:0;overflow:visible;background:transparent'
+    // Escape closes the panel through the devtools' own keydown handler, which
+    // also closes this dialog. Without preventDefault the browser then sends
+    // the same Escape to the app dialog and closes it too. The capture phase
+    // on the window sees the key wherever the focus is.
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (host.open && event.key === 'Escape') event.preventDefault()
+    }
+    doc.defaultView?.addEventListener('keydown', onKeyDown, true)
+    // The dialog must never close by itself, or the root stays hidden in it.
+    host.addEventListener('cancel', (event) => event.preventDefault())
+    let home: Node | null = null
+
+    const sync = () => {
+      const wanted =
+        isOpen() &&
+        Array.from(doc.querySelectorAll('dialog')).some(
+          (dialog) => dialog !== host && dialog.matches(':modal'),
+        )
+      if (wanted) {
+        if (host.open) return
+        home = element.parentNode
+        host.append(element)
+        doc.body.append(host)
+        host.showModal()
+      } else if (host.open) {
+        host.close()
+        home?.appendChild(element)
+        host.remove()
+      }
+    }
+
+    // `showModal()` and `close()` toggle the `open` attribute. Removing an open
+    // dialog from the page is a child list change instead.
+    const observer = new MutationObserver((records) => {
+      // An app dialog shown after the host goes on top of it. Showing the host
+      // again puts the host back on top.
+      const appModalShown = records.some(
+        (record) =>
+          record.type === 'attributes' &&
+          record.target !== host &&
+          (record.target as Element).matches('dialog:modal'),
+      )
+      if (host.open && appModalShown) {
+        host.close()
+        host.showModal()
+        return
+      }
+      sync()
+    })
+    observer.observe(doc.documentElement, {
+      subtree: true,
+      childList: true,
+      attributeFilter: ['open'],
+    })
+    createEffect(() => {
+      isOpen()
+      sync()
+    })
+
+    onCleanup(() => {
+      doc.defaultView?.removeEventListener('keydown', onKeyDown, true)
+      observer.disconnect()
+      if (host.open) {
+        host.close()
+        home?.appendChild(element)
+      }
+      host.remove()
+    })
+  })
+}