Skip to content

The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.

fix(ui-patterns): only initiate the command menu when it opens (#52129)

Alaister Young2193f2acdf8e
diff --git a/apps/studio/components/layouts/SQLEditorLayout/SqlEditor.Commands.test.tsx b/apps/studio/components/layouts/SQLEditorLayout/SqlEditor.Commands.test.tsx
new file mode 100644
index 00000000000..a0e673cb209
--- /dev/null
+++ b/apps/studio/components/layouts/SQLEditorLayout/SqlEditor.Commands.test.tsx
@@ -0,0 +1,240 @@
+import { QueryClient } from '@tanstack/react-query'
+import { waitFor } from '@testing-library/react'
+import type { components } from 'api-types'
+import { HttpResponse } from 'msw'
+import { useEffect, useState } from 'react'
+import { useCommandMenuOpen, useSetCommandMenuOpen } from 'ui-patterns/CommandMenu'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+import { useQueryTableCommands } from './SqlEditor.Commands'
+import { customRender } from '@/tests/lib/custom-render'
+import { addAPIMock } from '@/tests/lib/msw'
+
+const routeParams = vi.hoisted(() => {
+ const current: { ref: string } = { ref: 'default' }
+ return { current }
+})
+
+vi.mock('common', async (importOriginal) => {
+ const actual = await importOriginal<typeof import('common')>()
+ return {
+ ...actual,
+ useParams: () => routeParams.current,
+ }
+})
+
+type ProjectDetailResponse = components['schemas']['ProjectDetailResponse_Output']
+
+const PROJECT: ProjectDetailResponse = {
+ cloud_provider: 'AWS',
+ connectionString: 'postgresql://postgres:[email protected]:5432/postgres',
+ db_host: 'db.default.supabase.co',
+ dbVersion: 'supabase-postgres-15.1.0',
+ high_availability: false,
+ id: 1,
+ infra_compute_size: 'micro',
+ inserted_at: '2026-01-01T00:00:00.000Z',
+ integration_source: null,
+ is_branch_enabled: false,
+ is_physical_backups_enabled: false,
+ name: 'Test project',
+ organization_id: 1,
+ ref: 'default',
+ region: 'us-east-1',
+ restUrl: 'https://default.supabase.co',
+ status: 'ACTIVE_HEALTHY',
+ subscription_id: 'subscription-1',
+ updated_at: '2026-01-01T00:00:00.000Z',
+}
+
+const OTHER_REF = 'other-project'
+
+function tablesQueryKey(ref: string) {
+ return ['projects', ref, 'tables', { includeColumns: true }]
+}
+
+const TABLES_QUERY_KEY = tablesQueryKey('default')
+
+function projectWithRef(ref: string): ProjectDetailResponse {
+ return { ...PROJECT, ref }
+}
+
+function mockProjectDetail(response: () => Promise<Response> | Response) {
+ addAPIMock({
+ method: 'get',
+ path: '/platform/projects/:ref',
+ response,
+ })
+}
+
+function QueryTableCommands() {
+ useQueryTableCommands()
+ return null
+}
+
+// the lazy menu mounts on the open that initiates it, so the first render is already open.
+function MountWhileOpen() {
+ const setOpen = useSetCommandMenuOpen()
+ const isOpen = useCommandMenuOpen()
+ const [isReady, setIsReady] = useState(false)
+
+ useEffect(() => {
+ setOpen(true)
+ setIsReady(true)
+ }, [setOpen])
+
+ if (!isReady || !isOpen) return null
+
+ return <QueryTableCommands />
+}
+
+function renderOpenMenu() {
+ const queryClient = new QueryClient({
+ defaultOptions: { queries: { retry: false } },
+ })
+ const prefetchQuery = vi.spyOn(queryClient, 'prefetchQuery').mockResolvedValue(undefined)
+
+ customRender(<MountWhileOpen />, { queryClient })
+
+ return prefetchQuery
+}
+
+// stays mounted across open and close, unlike MountWhileOpen, which unmounts when the menu closes.
+function MenuToggle({ open }: { open: boolean }) {
+ const setOpen = useSetCommandMenuOpen()
+
+ useEffect(() => {
+ setOpen(open)
+ }, [open, setOpen])
+
+ return <QueryTableCommands />
+}
+
+function renderMountedMenu() {
+ const queryClient = new QueryClient({
+ defaultOptions: { queries: { retry: false } },
+ })
+ const prefetchQuery = vi.spyOn(queryClient, 'prefetchQuery').mockResolvedValue(undefined)
+ const view = customRender(<MenuToggle open={false} />, { queryClient })
+
+ return { prefetchQuery, ...view }
+}
+
+describe('useQueryTableCommands', () => {
+ let releaseProject = () => {}
+
+ afterEach(() => {
+ releaseProject()
+ releaseProject = () => {}
+ routeParams.current = { ref: 'default' }
+ })
+
+ it('prefetches tables when the menu mounts already open', async () => {
+ mockProjectDetail(() => HttpResponse.json<ProjectDetailResponse>(PROJECT))
+ const prefetchQuery = renderOpenMenu()
+
+ await waitFor(() => {
+ expect(prefetchQuery).toHaveBeenCalledWith(
+ expect.objectContaining({ queryKey: TABLES_QUERY_KEY })
+ )
+ })
+ })
+
+ it('prefetches tables when the project resolves after the menu opens', async () => {
+ let releaseProject = () => {}
+ const projectGate = new Promise<void>((resolve) => {
+ releaseProject = resolve
+ })
+ let didRequestProject = false
+
+ mockProjectDetail(async () => {
+ didRequestProject = true
+ await projectGate
+ return HttpResponse.json<ProjectDetailResponse>(PROJECT)
+ })
+
+ const prefetchQuery = renderOpenMenu()
+
+ try {
+ await waitFor(() => {
+ expect(didRequestProject).toBe(true)
+ })
+ expect(prefetchQuery).not.toHaveBeenCalled()
+
+ releaseProject()
+
+ await waitFor(() => {
+ expect(prefetchQuery).toHaveBeenCalledWith(
+ expect.objectContaining({ queryKey: TABLES_QUERY_KEY })
+ )
+ })
+ } finally {
+ releaseProject()
+ }
+ })
+
+ it('does not prefetch tables when the menu closes', async () => {
+ mockProjectDetail(() => HttpResponse.json<ProjectDetailResponse>(PROJECT))
+ const { prefetchQuery, rerender } = renderMountedMenu()
+
+ rerender(<MenuToggle open />)
+
+ await waitFor(() => {
+ expect(prefetchQuery).toHaveBeenCalledTimes(1)
+ })
+
+ rerender(<MenuToggle open={false} />)
+
+ expect(prefetchQuery).toHaveBeenCalledTimes(1)
+ })
+
+ it('prefetches tables again when the menu reopens', async () => {
+ mockProjectDetail(() => HttpResponse.json<ProjectDetailResponse>(PROJECT))
+ const { prefetchQuery, rerender } = renderMountedMenu()
+
+ rerender(<MenuToggle open />)
+
+ await waitFor(() => {
+ expect(prefetchQuery).toHaveBeenCalledTimes(1)
+ })
+
+ rerender(<MenuToggle open={false} />)
+ expect(prefetchQuery).toHaveBeenCalledTimes(1)
+
+ rerender(<MenuToggle open />)
+
+ await waitFor(() => {
+ expect(prefetchQuery).toHaveBeenCalledTimes(2)
+ })
+ expect(prefetchQuery).toHaveBeenLastCalledWith(
+ expect.objectContaining({ queryKey: TABLES_QUERY_KEY })
+ )
+ })
+
+ it('prefetches tables when the project changes while the menu is open', async () => {
+ addAPIMock({
+ method: 'get',
+ path: '/platform/projects/:ref',
+ response: ({ params }) =>
+ HttpResponse.json<ProjectDetailResponse>(projectWithRef(String(params.ref))),
+ })
+ const { prefetchQuery, rerender } = renderMountedMenu()
+
+ rerender(<MenuToggle open />)
+
+ await waitFor(() => {
+ expect(prefetchQuery).toHaveBeenCalledWith(
+ expect.objectContaining({ queryKey: tablesQueryKey('default') })
+ )
+ })
+
+ routeParams.current = { ref: OTHER_REF }
+ rerender(<MenuToggle open />)
+
+ await waitFor(() => {
+ expect(prefetchQuery).toHaveBeenCalledWith(
+ expect.objectContaining({ queryKey: tablesQueryKey(OTHER_REF) })
+ )
+ })
+ })
+})
diff --git a/apps/studio/components/layouts/SQLEditorLayout/SqlEditor.Commands.tsx b/apps/studio/components/layouts/SQLEditorLayout/SqlEditor.Commands.tsx
index f60eb95810b..3036bf55ab6 100644
--- a/apps/studio/components/layouts/SQLEditorLayout/SqlEditor.Commands.tsx
+++ b/apps/studio/components/layouts/SQLEditorLayout/SqlEditor.Commands.tsx
@@ -258,19 +258,30 @@ export function useQueryTableCommands(options?: CommandOptions) {
const setPage = useSetPage()
const commandMenuOpen = useCommandMenuOpen()
- const commandMenuPreviouslyOpen = useRef(commandMenuOpen)
- const commandMenuJustOpened = commandMenuOpen && !commandMenuPreviouslyOpen.current
- commandMenuPreviouslyOpen.current = commandMenuOpen
+ // the ref prefetched for this open. unset until that prefetch runs, so a
+ // menu that mounts already open still prefetches once the project exists.
+ // a new ref prefetches while the menu stays open. cleared on close.
+ const prefetchedProjectRef = useRef<string | undefined>(undefined)
const prefetchTables = usePrefetchTables({
projectRef: project?.ref,
connectionString: project?.connectionString,
})
useEffect(() => {
- if (project && commandMenuJustOpened) {
- prefetchTables(undefined, true)
+ if (!commandMenuOpen) {
+ prefetchedProjectRef.current = undefined
+ return
}
- }, [project, prefetchTables, commandMenuJustOpened])
+
+ const shouldPrefetch = prefetchedProjectRef.current !== project?.ref && !!project
+
+ if (!shouldPrefetch) {
+ return
+ }
+
+ prefetchedProjectRef.current = project?.ref
+ prefetchTables(undefined, true)
+ }, [commandMenuOpen, project, prefetchTables])
useRegisterPage(
QUERY_TABLE_PAGE_NAME,
diff --git a/packages/ui-patterns/src/CommandMenu/api/CommandProvider.navigation.test.tsx b/packages/ui-patterns/src/CommandMenu/api/CommandProvider.navigation.test.tsx
new file mode 100644
index 00000000000..20c8e0171f5
--- /dev/null
+++ b/packages/ui-patterns/src/CommandMenu/api/CommandProvider.navigation.test.tsx
@@ -0,0 +1,141 @@
+import { act, render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { CommandProvider } from './CommandProvider'
+import {
+ useCommandMenuInitiated,
+ useCommandMenuOpen,
+ useSetCommandMenuOpen,
+} from './hooks/viewHooks'
+
+type RouteHandler = (url: string, options?: { shallow?: boolean }) => void
+
+const legacyRouter = vi.hoisted(() => {
+ const handlers = new Map<string, Set<RouteHandler>>()
+
+ return {
+ events: {
+ on: (type: string, handler: RouteHandler) => {
+ handlers.set(type, (handlers.get(type) ?? new Set()).add(handler))
+ },
+ off: (type: string, handler: RouteHandler) => {
+ handlers.get(type)?.delete(handler)
+ },
+ },
+ emit(type: string, url: string, options?: { shallow?: boolean }) {
+ handlers.get(type)?.forEach((handler) => handler(url, options))
+ },
+ reset() {
+ handlers.clear()
+ },
+ }
+})
+
+vi.mock('next/compat/router', () => ({
+ useRouter: () => legacyRouter,
+}))
+
+const MenuProbe = () => {
+ const isInitiated = useCommandMenuInitiated()
+ const isOpen = useCommandMenuOpen()
+ const setOpen = useSetCommandMenuOpen()
+
+ return (
+ <>
+ <span>{isInitiated ? 'initiated' : 'idle'}</span>
+ <span>{isOpen ? 'open' : 'closed'}</span>
+ {isInitiated && <span>menu-mounted</span>}
+ <button type="button" onClick={() => setOpen(true)}>
+ Open menu
+ </button>
+ </>
+ )
+}
+
+const renderMenu = () =>
+ render(
+ <CommandProvider openKey="">
+ <MenuProbe />
+ </CommandProvider>
+ )
+
+const completeRoute = async (url: string, options?: { shallow?: boolean }) => {
+ await act(async () => {
+ legacyRouter.emit('routeChangeComplete', url, options)
+ })
+}
+
+describe('CloseOnNavigation', () => {
+ beforeEach(() => {
+ legacyRouter.reset()
+ })
+
+ it('does not initiate a never-opened menu on a real navigation', async () => {
+ renderMenu()
+
+ expect(screen.getByText('idle')).toBeInTheDocument()
+ expect(screen.queryByText('menu-mounted')).not.toBeInTheDocument()
+
+ await completeRoute('/project/ref/sql', { shallow: false })
+
+ expect(screen.getByText('idle')).toBeInTheDocument()
+ expect(screen.getByText('closed')).toBeInTheDocument()
+ expect(screen.queryByText('menu-mounted')).not.toBeInTheDocument()
+ })
+
+ it('does not initiate a never-opened menu on a shallow completion', async () => {
+ renderMenu()
+
+ await completeRoute('/project/ref/editor?schema=auth', { shallow: true })
+
+ expect(screen.getByText('idle')).toBeInTheDocument()
+ expect(screen.getByText('closed')).toBeInTheDocument()
+ expect(screen.queryByText('menu-mounted')).not.toBeInTheDocument()
+ })
+
+ it('does not initiate a never-opened menu when the completion omits shallow', async () => {
+ renderMenu()
+
+ await completeRoute('/project/ref/sql')
+
+ expect(screen.getByText('idle')).toBeInTheDocument()
+ expect(screen.getByText('closed')).toBeInTheDocument()
+ expect(screen.queryByText('menu-mounted')).not.toBeInTheDocument()
+ })
+
+ it('initiates and mounts when opened', async () => {
+ const user = userEvent.setup()
+ renderMenu()
+
+ await user.click(screen.getByRole('button', { name: 'Open menu' }))
+
+ expect(screen.getByText('initiated')).toBeInTheDocument()
+ expect(screen.getByText('open')).toBeInTheDocument()
+ expect(screen.getByText('menu-mounted')).toBeInTheDocument()
+ })
+
+ it('closes an open menu on a real navigation without unmounting it', async () => {
+ const user = userEvent.setup()
+ renderMenu()
+
+ await user.click(screen.getByRole('button', { name: 'Open menu' }))
+ await completeRoute('/project/ref/sql', { shallow: false })
+
+ expect(screen.getByText('closed')).toBeInTheDocument()
+ expect(screen.getByText('initiated')).toBeInTheDocument()
+ expect(screen.getByText('menu-mounted')).toBeInTheDocument()
+ })
+
+ it('closes an open menu on a shallow completion', async () => {
+ const user = userEvent.setup()
+ renderMenu()
+
+ await user.click(screen.getByRole('button', { name: 'Open menu' }))
+ await completeRoute('/new/org', { shallow: true })
+
+ expect(screen.getByText('closed')).toBeInTheDocument()
+ expect(screen.getByText('initiated')).toBeInTheDocument()
+ expect(screen.getByText('menu-mounted')).toBeInTheDocument()
+ })
+})
diff --git a/packages/ui-patterns/src/CommandMenu/api/CommandProvider.tsx b/packages/ui-patterns/src/CommandMenu/api/CommandProvider.tsx
index 75204df2204..dfdbf43420e 100644
--- a/packages/ui-patterns/src/CommandMenu/api/CommandProvider.tsx
+++ b/packages/ui-patterns/src/CommandMenu/api/CommandProvider.tsx
@@ -95,7 +95,7 @@ function CloseOnNavigation({ children }: PropsWithChildren) {
legacyRouter.events.on('routeChangeComplete', completeNavigation)
return () => legacyRouter.events.off('routeChangeComplete', completeNavigation)
- }, [isUsingLegacyRouting, legacyRouter])
+ }, [completeNavigation, isUsingLegacyRouting, legacyRouter])
return (
<CrossCompatRouterContext.Provider value={ctx}>{children}</CrossCompatRouterContext.Provider>
diff --git a/packages/ui-patterns/src/CommandMenu/internal/state/viewState.test.ts b/packages/ui-patterns/src/CommandMenu/internal/state/viewState.test.ts
new file mode 100644
index 00000000000..69823ea817c
--- /dev/null
+++ b/packages/ui-patterns/src/CommandMenu/internal/state/viewState.test.ts
@@ -0,0 +1,41 @@
+import { beforeEach, describe, expect, it } from 'vitest'
+
+import { initViewState } from './viewState'
+import { type IViewState } from './viewState.types'
+
+describe('viewState', () => {
+ let viewState: IViewState
+
+ beforeEach(() => {
+ viewState = initViewState()
+ })
+
+ it('does not initiate when closing a menu that was never opened', () => {
+ viewState.setOpen(false)
+
+ expect(viewState.initiated).toBe(false)
+ expect(viewState.open).toBe(false)
+ })
+
+ it('initiates and opens when set open', () => {
+ viewState.setOpen(true)
+
+ expect(viewState.initiated).toBe(true)
+ expect(viewState.open).toBe(true)
+ })
+
+ it('stays initiated after closing an opened menu', () => {
+ viewState.setOpen(true)
+ viewState.setOpen(false)
+
+ expect(viewState.initiated).toBe(true)
+ expect(viewState.open).toBe(false)
+ })
+
+ it('initiates when toggled open from closed', () => {
+ viewState.toggleOpen()
+
+ expect(viewState.initiated).toBe(true)
+ expect(viewState.open).toBe(true)
+ })
+})
diff --git a/packages/ui-patterns/src/CommandMenu/internal/state/viewState.ts b/packages/ui-patterns/src/CommandMenu/internal/state/viewState.ts
index da314189ac4..0104c833783 100644
--- a/packages/ui-patterns/src/CommandMenu/internal/state/viewState.ts
+++ b/packages/ui-patterns/src/CommandMenu/internal/state/viewState.ts
@@ -14,7 +14,11 @@ const initViewState = () => {
handleTouchEnd: () => {},
},
setOpen: (open) => {
- state.init()
+ // init mounts the lazy menu, so only an open should do it
+ if (open) {
+ state.init()
+ }
+
state.open = open
},
toggleOpen: () => {