Skip to content

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

feat(studio): keyboard shortcuts for integrations (#46348)

Ali Waseem722fe85c1659
diff --git a/apps/studio/components/interfaces/Integrations/Integration/IntegrationDetailTabShortcuts.tsx b/apps/studio/components/interfaces/Integrations/Integration/IntegrationDetailTabShortcuts.tsx
new file mode 100644
index 00000000000..a97a049d316
--- /dev/null
+++ b/apps/studio/components/interfaces/Integrations/Integration/IntegrationDetailTabShortcuts.tsx
@@ -0,0 +1,46 @@
+import { useRouter } from 'next/router'
+
+import type { IntegrationTab } from '@/components/interfaces/Integrations/Landing/useIntegrationDetail'
+import { SHORTCUT_REFERENCE_GROUPS } from '@/state/shortcuts/referenceGroups'
+import { DynamicShortcut } from '@/state/shortcuts/useDynamicShortcut'
+
+const TAB_DIGIT_KEYS = ['1', '2', '3', '4', '5', '6', '7', '8', '9'] as const
+
+/**
+ * Binds digit keys 1-9 to whichever tabs the active integration declares in
+ * its `navigation` array. Render this once per integration detail page —
+ * shared between `LegacyIntegrationPage` and the marketplace `MarketplaceDetail`
+ * since both surfaces drive off the same `tabs` shape from `useIntegrationDetail`.
+ *
+ * The dynamic shortcut registry handles per-tab label overrides ("Go to Jobs",
+ * "Go to Wrappers", etc.) so the reference sheet and Cmd+K pick up the actual
+ * tab name without us having to pre-declare every possible integration tab.
+ */
+export interface IntegrationDetailTabShortcutsProps {
+ tabs: IntegrationTab[]
+ enabled?: boolean
+}
+
+export const IntegrationDetailTabShortcuts = ({
+ tabs,
+ enabled = true,
+}: IntegrationDetailTabShortcutsProps) => {
+ const router = useRouter()
+
+ return (
+ <>
+ {tabs.slice(0, TAB_DIGIT_KEYS.length).map((tab, index) => (
+ <DynamicShortcut
+ key={tab.href}
+ id={`integration-detail.tab-${index}`}
+ sequence={[TAB_DIGIT_KEYS[index]]}
+ label={`Go to ${tab.label}`}
+ referenceGroup={SHORTCUT_REFERENCE_GROUPS.NAVIGATION_INTEGRATIONS_DETAIL}
+ enabled={enabled && !tab.active}
+ registerInCommandMenu
+ callback={() => router.push(tab.href)}
+ />
+ ))}
+ </>
+ )
+}
diff --git a/apps/studio/components/interfaces/Integrations/Marketplace/MarketplaceDetail.tsx b/apps/studio/components/interfaces/Integrations/Marketplace/MarketplaceDetail.tsx
index 58c13225e3f..1297da27598 100644
--- a/apps/studio/components/interfaces/Integrations/Marketplace/MarketplaceDetail.tsx
+++ b/apps/studio/components/interfaces/Integrations/Marketplace/MarketplaceDetail.tsx
@@ -6,6 +6,7 @@ import { Admonition } from 'ui-patterns/admonition'
import { MarketplaceDetailHero } from './MarketplaceDetailHero'
import { MarketplaceDetailTopBar } from './MarketplaceDetailTopBar'
import { OverviewTab } from './OverviewTab'
+import { IntegrationDetailTabShortcuts } from '@/components/interfaces/Integrations/Integration/IntegrationDetailTabShortcuts'
import { InstallIntegrationSheet } from '@/components/interfaces/Integrations/Integration/IntegrationOverviewTabV2/InstallIntegrationSheet/InstallIntegrationSheet'
import { InstallOAuthIntegrationButton } from '@/components/interfaces/Integrations/Integration/IntegrationOverviewTabV2/InstallIntegrationSheet/InstallOAuthIntegrationButton'
import { useIntegrationDetail } from '@/components/interfaces/Integrations/Landing/useIntegrationDetail'
@@ -84,6 +85,7 @@ export const MarketplaceDetail = () => {
return (
<>
+ <IntegrationDetailTabShortcuts tabs={tabs} />
<MarketplaceDetailTopBar
title={integration.name}
isInstalled={isInstalled}
diff --git a/apps/studio/components/interfaces/Integrations/Marketplace/MarketplaceFilterBar.tsx b/apps/studio/components/interfaces/Integrations/Marketplace/MarketplaceFilterBar.tsx
index 1123a2d8d4a..28742635421 100644
--- a/apps/studio/components/interfaces/Integrations/Marketplace/MarketplaceFilterBar.tsx
+++ b/apps/studio/components/interfaces/Integrations/Marketplace/MarketplaceFilterBar.tsx
@@ -1,4 +1,5 @@
import { ChevronDown, LayoutGrid, List, Search } from 'lucide-react'
+import type { Ref } from 'react'
import {
Button,
cn,
@@ -19,12 +20,14 @@ import {
type MarketplaceIntegrationType,
type MarketplaceSource,
} from './Marketplace.constants'
+import { onSearchInputEscape } from '@/lib/keyboard'
export type ViewMode = 'list' | 'grid'
interface MarketplaceFilterBarProps {
resultCount: number
search: string
+ searchInputRef?: Ref<HTMLInputElement>
onSearchChange: (value: string) => void
category: string | null
onCategoryChange: (value: string | null) => void
@@ -49,6 +52,7 @@ const triggerCls = 'inline-flex flex-row gap-2'
export const MarketplaceFilterBar = ({
resultCount,
search,
+ searchInputRef,
onSearchChange,
category,
onCategoryChange,
@@ -81,9 +85,11 @@ export const MarketplaceFilterBar = ({
)}
>
<Input
+ ref={searchInputRef}
value={search}
size="tiny"
onChange={(e) => onSearchChange(e.target.value)}
+ onKeyDown={onSearchInputEscape(search, onSearchChange)}
placeholder={`Search integration${resultCount === 1 ? '' : 's'}…`}
icon={<Search size={14} />}
containerClassName="w-full min-w-40 max-w-60 grow flex-1"
diff --git a/apps/studio/components/interfaces/Integrations/Marketplace/MarketplaceIndex.tsx b/apps/studio/components/interfaces/Integrations/Marketplace/MarketplaceIndex.tsx
index 5b7e271e8e3..d129289772e 100644
--- a/apps/studio/components/interfaces/Integrations/Marketplace/MarketplaceIndex.tsx
+++ b/apps/studio/components/interfaces/Integrations/Marketplace/MarketplaceIndex.tsx
@@ -1,6 +1,6 @@
import { useQuery } from '@tanstack/react-query'
import { parseAsString, parseAsStringEnum, useQueryState } from 'nuqs'
-import { useMemo } from 'react'
+import { useMemo, useRef } from 'react'
import { Button, Card, ShadowScrollArea, Table, TableBody, TableHeader } from 'ui'
import {
EmptyStatePresentational,
@@ -36,6 +36,8 @@ import { DocsButton } from '@/components/ui/DocsButton'
import { marketplaceCategoriesQueryOptions } from '@/data/marketplace/integration-categories-query'
import { useLocalStorageQuery } from '@/hooks/misc/useLocalStorage'
import { DOCS_URL } from '@/lib/constants'
+import { SHORTCUT_IDS } from '@/state/shortcuts/registry'
+import { useShortcut } from '@/state/shortcuts/useShortcut'
const MARKETPLACE_VIEW_MODE_STORAGE_KEY = 'supabase.marketplace.viewMode'
@@ -193,6 +195,18 @@ export const MarketplaceIndex = () => {
setSearch('')
}
+ const searchInputRef = useRef<HTMLInputElement>(null)
+
+ useShortcut(
+ SHORTCUT_IDS.LIST_PAGE_FOCUS_SEARCH,
+ () => {
+ searchInputRef.current?.focus()
+ searchInputRef.current?.select()
+ },
+ { label: 'Search integrations' }
+ )
+ useShortcut(SHORTCUT_IDS.LIST_PAGE_RESET_FILTERS, clearAll)
+
const activeFilters = [category, type, source].filter(Boolean)
const pageTitle = useMemo(() => {
if (activeFilters.length !== 1) return 'Integrations Marketplace'
@@ -248,6 +262,7 @@ export const MarketplaceIndex = () => {
<MarketplaceFilterBar
resultCount={filtered.length}
search={search}
+ searchInputRef={searchInputRef}
onSearchChange={(v) => setSearch(v)}
category={category}
onCategoryChange={(v) => setCategory(v)}
diff --git a/apps/studio/components/ui/GlobalShortcuts/ShortcutsReferenceSheet.test.tsx b/apps/studio/components/ui/GlobalShortcuts/ShortcutsReferenceSheet.test.tsx
index dcc6ce42910..b9897d0f93b 100644
--- a/apps/studio/components/ui/GlobalShortcuts/ShortcutsReferenceSheet.test.tsx
+++ b/apps/studio/components/ui/GlobalShortcuts/ShortcutsReferenceSheet.test.tsx
@@ -5,7 +5,7 @@ import { beforeEach, describe, expect, it, vi } from 'vitest'
import { ShortcutsReferenceSheet } from './ShortcutsReferenceSheet'
import { SHORTCUT_DEFINITIONS, SHORTCUT_IDS, type ShortcutId } from '@/state/shortcuts/registry'
-import type { ShortcutHotkeyMeta } from '@/state/shortcuts/useShortcut'
+import type { ShortcutHotkeyMeta } from '@/state/shortcuts/types'
import { customRender } from '@/tests/lib/custom-render'
const { mockUseHotkeyRegistrations } = vi.hoisted(() => ({
diff --git a/apps/studio/components/ui/GlobalShortcuts/ShortcutsReferenceSheet.tsx b/apps/studio/components/ui/GlobalShortcuts/ShortcutsReferenceSheet.tsx
index 76acfd88534..0e2f3012aa1 100644
--- a/apps/studio/components/ui/GlobalShortcuts/ShortcutsReferenceSheet.tsx
+++ b/apps/studio/components/ui/GlobalShortcuts/ShortcutsReferenceSheet.tsx
@@ -19,7 +19,7 @@ import {
SHORTCUT_REFERENCE_GROUP_ORDER,
SHORTCUT_REFERENCE_GROUPS,
} from '@/state/shortcuts/referenceGroups'
-import type { ShortcutHotkeyMeta } from '@/state/shortcuts/useShortcut'
+import type { ShortcutHotkeyMeta } from '@/state/shortcuts/types'
interface ShortcutsReferenceSheetProps {
open: boolean
diff --git a/apps/studio/state/shortcuts/referenceGroups.ts b/apps/studio/state/shortcuts/referenceGroups.ts
index 56072a19229..8fcc8039372 100644
--- a/apps/studio/state/shortcuts/referenceGroups.ts
+++ b/apps/studio/state/shortcuts/referenceGroups.ts
@@ -9,6 +9,7 @@ export const SHORTCUT_REFERENCE_GROUPS = {
NAVIGATION_REALTIME: 'navigation.realtime',
NAVIGATION_OBSERVABILITY: 'navigation.observability',
NAVIGATION_ADVISORS: 'navigation.advisors',
+ NAVIGATION_INTEGRATIONS_DETAIL: 'navigation.integrations-detail',
} as const
export const SHORTCUT_REFERENCE_GROUP_LABELS: Record<string, string> = {
@@ -22,6 +23,7 @@ export const SHORTCUT_REFERENCE_GROUP_LABELS: Record<string, string> = {
[SHORTCUT_REFERENCE_GROUPS.NAVIGATION_REALTIME]: 'Realtime Navigation',
[SHORTCUT_REFERENCE_GROUPS.NAVIGATION_OBSERVABILITY]: 'Observability Navigation',
[SHORTCUT_REFERENCE_GROUPS.NAVIGATION_ADVISORS]: 'Advisors Navigation',
+ [SHORTCUT_REFERENCE_GROUPS.NAVIGATION_INTEGRATIONS_DETAIL]: 'Integration Tabs',
}
export const SHORTCUT_REFERENCE_GROUP_ORDER = [
@@ -46,6 +48,7 @@ export const SHORTCUT_REFERENCE_GROUP_ORDER = [
'observability-page',
SHORTCUT_REFERENCE_GROUPS.NAVIGATION_ADVISORS,
'advisors-page',
+ SHORTCUT_REFERENCE_GROUPS.NAVIGATION_INTEGRATIONS_DETAIL,
'logs-preview',
'nav',
'ai-assistant',
diff --git a/apps/studio/state/shortcuts/types.ts b/apps/studio/state/shortcuts/types.ts
index 0c5f0462604..9932e501b5e 100644
--- a/apps/studio/state/shortcuts/types.ts
+++ b/apps/studio/state/shortcuts/types.ts
@@ -1,4 +1,6 @@
-import { HotkeySequence } from '@tanstack/react-hotkeys'
+import { HotkeyMeta, HotkeySequence } from '@tanstack/react-hotkeys'
+
+import { ShortcutId } from './registry'
export type DisabledShortcuts = Record<string, boolean>
@@ -130,3 +132,17 @@ export interface ShortcutDefinition {
}
export type RegistryDefinations<T extends string> = Record<T, ShortcutDefinition>
+
+/**
+ * Shape we store on each registration's `options.meta` so the Keyboard
+ * shortcuts reference sheet can read it back via `useHotkeyRegistrations()`.
+ */
+export interface ShortcutHotkeyMeta extends HotkeyMeta {
+ /**
+ * Stable identifier for the registration. `useShortcut` always sets this to
+ * a registered `ShortcutId`; `useDynamicShortcut` may pass any string so
+ * runtime-built shortcuts can flow through the same reference sheet.
+ */
+ id: ShortcutId | string
+ referenceGroup?: string
+}
diff --git a/apps/studio/state/shortcuts/useDynamicShortcut.tsx b/apps/studio/state/shortcuts/useDynamicShortcut.tsx
new file mode 100644
index 00000000000..710f845c414
--- /dev/null
+++ b/apps/studio/state/shortcuts/useDynamicShortcut.tsx
@@ -0,0 +1,128 @@
+import { useHotkeySequence, type HotkeySequence } from '@tanstack/react-hotkeys'
+import { Fragment, useCallback, useMemo } from 'react'
+import { KeyboardShortcut } from 'ui'
+import { useRegisterCommands, useSetCommandMenuOpen } from 'ui-patterns/CommandMenu'
+
+import { hotkeyToKeys } from './formatShortcut'
+import type { ShortcutHotkeyMeta, ShortcutOptions } from './types'
+import { orderShortcutCommands } from './utils'
+import { COMMAND_MENU_SECTIONS } from '@/components/interfaces/App/CommandMenu/CommandMenu.utils'
+import useLatest from '@/hooks/misc/useLatest'
+
+/**
+ * Props shared by both the hook and the `<DynamicShortcut>` component.
+ *
+ * "Dynamic" means the shortcut isn't pre-declared in `SHORTCUT_DEFINITIONS` —
+ * the call site provides the `id`, `sequence`, and `label` at mount time.
+ * Use this when the shortcut list itself is derived from data (e.g. a tab list
+ * whose count and labels vary per page).
+ *
+ * Behavior matches `useShortcut` for the surfaces a dynamic shortcut can
+ * meaningfully participate in:
+ * - Reference sheet — picks these up via the `meta` payload while mounted.
+ * - Cmd+K command menu — opt-in via `registerInCommandMenu`, same pattern
+ * and ordering as registered shortcuts.
+ *
+ * What it does *not* support, because both are keyed on static `ShortcutId`s:
+ * - User-preference toggle in Account → Preferences.
+ * - `showInSettings` rendering in the keyboard shortcuts settings page.
+ *
+ * `id` must be unique among currently-mounted shortcuts. TanStack's hotkey
+ * lib warns by default when two registrations share a `sequence`, so prefer
+ * scoping IDs by surface (e.g. `integration-detail.tab-${index}`).
+ */
+export interface DynamicShortcutProps {
+ id: string
+ sequence: HotkeySequence
+ label: string
+ callback: () => void
+ enabled?: boolean
+ referenceGroup?: string
+ registerInCommandMenu?: boolean
+ ignoreInputs?: ShortcutOptions['ignoreInputs']
+ timeout?: ShortcutOptions['timeout']
+ conflictBehavior?: ShortcutOptions['conflictBehavior']
+}
+
+export function useDynamicShortcut({
+ id,
+ sequence,
+ label,
+ callback,
+ enabled = true,
+ referenceGroup,
+ registerInCommandMenu = false,
+ ignoreInputs,
+ timeout,
+ conflictBehavior,
+}: DynamicShortcutProps) {
+ const meta = useMemo<ShortcutHotkeyMeta>(
+ () => ({ id, name: label, referenceGroup }),
+ [id, label, referenceGroup]
+ )
+
+ useHotkeySequence(sequence, callback, {
+ enabled,
+ timeout,
+ meta,
+ ...(ignoreInputs !== undefined && { ignoreInputs }),
+ ...(conflictBehavior !== undefined && { conflictBehavior }),
+ })
+
+ const enabledInCommandMenu = enabled && registerInCommandMenu
+ const callbackRef = useLatest(callback)
+ const setCommandMenuOpen = useSetCommandMenuOpen()
+ const stableAction = useCallback(() => {
+ setCommandMenuOpen(false)
+ callbackRef.current()
+ }, [callbackRef, setCommandMenuOpen])
+
+ useRegisterCommands(
+ COMMAND_MENU_SECTIONS.SHORTCUTS,
+ [
+ {
+ id,
+ name: label,
+ action: stableAction,
+ badge: () => (
+ <div className="flex items-center gap-1">
+ {sequence.map((step, i) => (
+ <Fragment key={i}>
+ {i > 0 && <span className="text-foreground-lighter text-[11px]">then</span>}
+ <KeyboardShortcut keys={hotkeyToKeys(step)} />
+ </Fragment>
+ ))}
+ </div>
+ ),
+ },
+ ],
+ {
+ enabled: enabledInCommandMenu,
+ deps: [enabled, label, sequence.join('+')],
+ orderCommands: orderShortcutCommands,
+ sectionMeta: { priority: 1 },
+ }
+ )
+}
+
+/**
+ * Renderable wrapper around `useDynamicShortcut`. Lets callers compose
+ * shortcuts inside a `.map()` over dynamic data without violating rules-of-hooks:
+ *
+ * ```tsx
+ * {tabs.map((tab, i) => (
+ * <DynamicShortcut
+ * key={tab.href}
+ * id={`integration-detail.tab-${i}`}
+ * sequence={[String(i + 1)]}
+ * label={`Go to ${tab.label}`}
+ * registerInCommandMenu
+ * callback={() => router.push(tab.href)}
+ * />
+ * ))}
+ * ```
+ */
+export function DynamicShortcut(props: DynamicShortcutProps) {
+ useDynamicShortcut(props)
+ return null
+}
diff --git a/apps/studio/state/shortcuts/useShortcut.tsx b/apps/studio/state/shortcuts/useShortcut.tsx
index 95a13308aa2..773330749c0 100644
--- a/apps/studio/state/shortcuts/useShortcut.tsx
+++ b/apps/studio/state/shortcuts/useShortcut.tsx
@@ -1,39 +1,16 @@
-import { useHotkeySequence, type HotkeyMeta } from '@tanstack/react-hotkeys'
+import { useHotkeySequence } from '@tanstack/react-hotkeys'
import { Fragment, useCallback, useMemo } from 'react'
import { KeyboardShortcut } from 'ui'
import { useRegisterCommands, useSetCommandMenuOpen } from 'ui-patterns/CommandMenu'
-import type { ICommand } from 'ui-patterns/CommandMenu/api/types'
-import { SHORTCUT_DEFINITIONS, SHORTCUT_IDS, type ShortcutId } from './registry'
-import type { ShortcutOptions } from './types'
+import { hotkeyToKeys } from './formatShortcut'
+import { SHORTCUT_DEFINITIONS, type ShortcutId } from './registry'
+import type { ShortcutHotkeyMeta, ShortcutOptions } from './types'
import { useIsShortcutEnabled } from './useIsShortcutEnabled'
+import { orderShortcutCommands } from './utils'
import { COMMAND_MENU_SECTIONS } from '@/components/interfaces/App/CommandMenu/CommandMenu.utils'
import useLatest from '@/hooks/misc/useLatest'
-/**
- * Shape we store on each registration's `options.meta` so the Keyboard
- * shortcuts reference sheet can read it back via `useHotkeyRegistrations()`.
- * The library's `HotkeyMeta` is open for declaration merging, but we don't
- * own a direct dep on `@tanstack/hotkeys`, so we keep the extension local.
- */
-export interface ShortcutHotkeyMeta extends HotkeyMeta {
- id: ShortcutId
- referenceGroup?: string
-}
-
-const hotkeyToKeys = (hotkey: string): string[] =>
- hotkey.split('+').map((part) => (part === 'Mod' ? 'Meta' : part))
-
-const orderShortcutCommands = (commands: ICommand[], commandsToInsert: ICommand[]): ICommand[] => {
- const mergedCommands = [...commands, ...commandsToInsert]
-
- return mergedCommands.sort((a, b) => {
- if (a.id === SHORTCUT_IDS.SHORTCUTS_OPEN_REFERENCE) return 1
- if (b.id === SHORTCUT_IDS.SHORTCUTS_OPEN_REFERENCE) return -1
- return 0
- })
-}
-
/**
* Subscribe to a registered keyboard shortcut.
*
diff --git a/apps/studio/state/shortcuts/utils.ts b/apps/studio/state/shortcuts/utils.ts
new file mode 100644
index 00000000000..6cd01fbabbf
--- /dev/null
+++ b/apps/studio/state/shortcuts/utils.ts
@@ -0,0 +1,22 @@
+import { ICommand } from 'ui-patterns'
+
+import { SHORTCUT_IDS } from './registry'
+
+/**
+ * Shared orderer for the Cmd+K "Shortcuts" section. Keeps the "Show all
+ * keyboard shortcuts" entry pinned to the bottom regardless of registration
+ * order; everything else is order-stable. Exported so `useDynamicShortcut`
+ * can share the same ordering behavior.
+ */
+export const orderShortcutCommands = (
+ commands: ICommand[],
+ commandsToInsert: ICommand[]
+): ICommand[] => {
+ const mergedCommands = [...commands, ...commandsToInsert]
+
+ return mergedCommands.sort((a, b) => {
+ if (a.id === SHORTCUT_IDS.SHORTCUTS_OPEN_REFERENCE) return 1
+ if (b.id === SHORTCUT_IDS.SHORTCUTS_OPEN_REFERENCE) return -1
+ return 0
+ })
+}