From 82bd84f82b84a753d071afff3e5c2a93a3bda2b2 Mon Sep 17 00:00:00 2001 From: Alem Tuzlak Date: Fri, 2 Oct 2026 16:40:34 +0200 Subject: [PATCH 1/2] feat(devtools): add openAsModal to use the panel over app modal dialogs A dialog opened with showModal() makes the rest of the page inert, the devtools included, and no z-index or popover gets past that. With `openAsModal: true`, while the panel is open and the app has a modal dialog open, the devtools root moves into a modal dialog of its own shown on top. It moves back when the panel or the app dialog closes. Escape closes only the panel: the hook prevents the browser from passing the same Escape on to the app dialog. A non-modal does not block the devtools, so it needs nothing. Fixes #369 --- .changeset/open-as-modal.md | 5 ++ docs/configuration.md | 6 ++ e2e/apps/react-vite/src/main.tsx | 14 +++ .../react-vite/tests/open-as-modal.spec.ts | 88 +++++++++++++++++++ .../devtools/src/context/devtools-store.ts | 9 ++ packages/devtools/src/devtools.tsx | 2 + packages/devtools/src/hooks/use-modal-host.ts | 79 +++++++++++++++++ 7 files changed, 203 insertions(+) create mode 100644 .changeset/open-as-modal.md create mode 100644 e2e/apps/react-vite/tests/open-as-modal.spec.ts create mode 100644 packages/devtools/src/hooks/use-modal-host.ts diff --git a/.changeset/open-as-modal.md b/.changeset/open-as-modal.md new file mode 100644 index 000000000..ef446af36 --- /dev/null +++ b/.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. diff --git a/docs/configuration.md b/docs/configuration.md index a8fe98fff..d9f9a52e4 100644 --- a/docs/configuration.md +++ b/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 diff --git a/e2e/apps/react-vite/src/main.tsx b/e2e/apps/react-vite/src/main.tsx index e30abcda6..1e5bae60f 100644 --- a/e2e/apps/react-vite/src/main.tsx +++ b/e2e/apps/react-vite/src/main.tsx @@ -12,10 +12,24 @@ function App() { <>

devtools e2e host

+ + + + { + 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('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) + }) +}) diff --git a/packages/devtools/src/context/devtools-store.ts b/packages/devtools/src/context/devtools-store.ts index 3aefe9966..2d5864d2c 100644 --- a/packages/devtools/src/context/devtools-store.ts +++ b/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' && diff --git a/packages/devtools/src/devtools.tsx b/packages/devtools/src/devtools.tsx index 54f01c6f7..8aac0c0b5 100644 --- a/packages/devtools/src/devtools.tsx +++ b/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) { diff --git a/packages/devtools/src/hooks/use-modal-host.ts b/packages/devtools/src/hooks/use-modal-host.ts new file mode 100644 index 000000000..608da700b --- /dev/null +++ b/packages/devtools/src/hooks/use-modal-host.ts @@ -0,0 +1,79 @@ +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, + root: Accessor, + isOpen: Accessor, +) { + 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 appModalOpen = Array.from(doc.querySelectorAll('dialog')).some( + (dialog) => dialog !== host && dialog.matches(':modal'), + ) + if (isOpen() && appModalOpen) { + 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. + const observer = new MutationObserver(sync) + observer.observe(doc.documentElement, { + subtree: 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() + }) + }) +} From 17321daea4340debbd1f21f19a30c0109fb6f6be Mon Sep 17 00:00:00 2001 From: Alem Tuzlak Date: Fri, 2 Oct 2026 17:44:55 +0200 Subject: [PATCH 2/2] fix(devtools): keep openAsModal on top of later dialogs and release removed ones Two cases left the devtools or the page stuck: - The app opened another modal dialog while the panel was on top. That dialog became the topmost modal and the devtools were inert behind it. The host is now shown again when an app dialog opens after it. - The app removed an open dialog without close(), for example on unmount. That is a child list change, which the observer did not watch, so the host stayed modal and the page stayed inert. The observer now watches child list changes too. --- .../react-vite/tests/open-as-modal.spec.ts | 40 +++++++++++++++++++ packages/devtools/src/hooks/use-modal-host.ts | 31 +++++++++++--- 2 files changed, 65 insertions(+), 6 deletions(-) diff --git a/e2e/apps/react-vite/tests/open-as-modal.spec.ts b/e2e/apps/react-vite/tests/open-as-modal.spec.ts index 1ab0d29eb..73f1aa104 100644 --- a/e2e/apps/react-vite/tests/open-as-modal.spec.ts +++ b/e2e/apps/react-vite/tests/open-as-modal.spec.ts @@ -73,6 +73,46 @@ test.describe('openAsModal', () => { ).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, }) => { diff --git a/packages/devtools/src/hooks/use-modal-host.ts b/packages/devtools/src/hooks/use-modal-host.ts index 608da700b..71fe049eb 100644 --- a/packages/devtools/src/hooks/use-modal-host.ts +++ b/packages/devtools/src/hooks/use-modal-host.ts @@ -39,10 +39,12 @@ export function createModalHost( let home: Node | null = null const sync = () => { - const appModalOpen = Array.from(doc.querySelectorAll('dialog')).some( - (dialog) => dialog !== host && dialog.matches(':modal'), - ) - if (isOpen() && appModalOpen) { + 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) @@ -55,10 +57,27 @@ export function createModalHost( } } - // `showModal()` and `close()` toggle the `open` attribute. - const observer = new MutationObserver(sync) + // `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(() => {