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('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) + }) +}) 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..71fe049eb --- /dev/null +++ b/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, + 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 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() + }) + }) +}