The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.
TypeScript aialternativeauthdatabasedenoembeddingsexamplefirebasenextjsoauth2pgvectorpostgispostgrespostgresqlpostgrestrealtimesupabasevectorswebsockets
feat: new shortcuts hook with registrations (#44954)
Ali Waseem3ed436de747a
diff --git a/apps/studio/components/grid/components/common/Hooks.tsx b/apps/studio/components/grid/components/common/Hooks.tsxindex 2e081fa49cc..ef2fe369e31 100644--- a/apps/studio/components/grid/components/common/Hooks.tsx+++ b/apps/studio/components/grid/components/common/Hooks.tsx@@ -7,6 +7,10 @@ function includes(array: string[], element: string) {/*** Hook for listening on key events.*+ * @deprecated Use `useShortcut` from `state/shortcuts/useShortcut` instead.+ * The new hook reads from a central registry, respects user preferences, and+ * can surface shortcuts in the Cmd+P command menu.+ ** @param {Object|Map} keyMap Key names mapped to event handlers. If a key name exists, its* default behavior will be suppressed.* @param {Array} whitelistNodes If target element is in the whitelist nodes array, will notdiff --git a/apps/studio/components/interfaces/App/CommandMenu/CommandMenu.utils.ts b/apps/studio/components/interfaces/App/CommandMenu/CommandMenu.utils.tsindex d203281c9d2..832332f31c7 100644--- a/apps/studio/components/interfaces/App/CommandMenu/CommandMenu.utils.ts+++ b/apps/studio/components/interfaces/App/CommandMenu/CommandMenu.utils.ts@@ -7,4 +7,5 @@ export const COMMAND_MENU_SECTIONS = {SQL: 'SQL Editor',DATABASE: 'Database',INTEGRATIONS: 'Integrations',+ SHORTCUTS: 'Shortcuts',} as constdiff --git a/apps/studio/hooks/ui/useHotKey.ts b/apps/studio/hooks/ui/useHotKey.tsindex 60dbe097c6a..cedb801e180 100644--- a/apps/studio/hooks/ui/useHotKey.ts+++ b/apps/studio/hooks/ui/useHotKey.ts@@ -1,14 +1,24 @@import { useEffect } from 'react'import { useLatest } from 'react-use'-// [Joshen] Refactor: Remove dependencies, and just make this into a single definition+/**+ * @deprecated Use `useShortcut` from `state/shortcuts/useShortcut` instead.+ * It reads from a central shortcut registry (`SHORTCUT_DEFINITIONS`) and+ * integrates with the user's enable/disable preferences + the Cmd+P command menu.+ *+ * Migration:+ * 1. Add an entry to `state/shortcuts/registry.ts` with a unique ID, label, and sequence.+ * 2. Replace `useHotKey(cb, 'k', { shift: true })` with+ * `useShortcut(SHORTCUT_IDS.YOUR_ID, cb)`.+ */function useHotKey(callback: (e: KeyboardEvent) => void,key: string,options?: { enabled?: boolean; shift?: boolean }): void/**- * @deprecated The `dependencies` parameter is deprecated. Use the overload without dependencies instead.+ * @deprecated Use `useShortcut` from `state/shortcuts/useShortcut` instead.+ * The `dependencies` parameter is also deprecated in this legacy hook.*/function useHotKey(callback: (e: KeyboardEvent) => void,diff --git a/apps/studio/package.json b/apps/studio/package.jsonindex 9da24a7d95a..ba7532a05d6 100644--- a/apps/studio/package.json+++ b/apps/studio/package.json@@ -67,6 +67,7 @@"@supabase/shared-types": "0.1.88","@supabase/sql-to-rest": "^0.1.6","@supabase/supabase-js": "catalog:",+ "@tanstack/react-hotkeys": "^0.9.1","@tanstack/react-query": "^5.0.0","@tanstack/react-query-devtools": "^5.0.0","@tanstack/react-table": "^8.21.3",diff --git a/apps/studio/state/shortcuts/registry.ts b/apps/studio/state/shortcuts/registry.tsnew file mode 100644index 00000000000..be08a32d51c--- /dev/null+++ b/apps/studio/state/shortcuts/registry.ts@@ -0,0 +1,46 @@+import { ShortcutDefinition } from './types'++/**+ * The canonical list of shortcut IDs. Add new shortcuts here first, then+ * register them in `SHORTCUT_DEFINITIONS` below.+ *+ * ID convention: `"<surface>.<action>"` in kebab-case, e.g. `"results.copy-markdown"`.+ * The `<surface>` groups related shortcuts (sql-editor, table-editor, results, etc).+ */+export const SHORTCUT_IDS = {+ RESULTS_COPY_MARKDOWN: 'results.copy-markdown',+} as const++/**+ * Union of all valid shortcut IDs. Use this as the `id` parameter type on any+ * hook or util that takes a shortcut reference.+ */+export type ShortcutId = (typeof SHORTCUT_IDS)[keyof typeof SHORTCUT_IDS]++/**+ * The shortcut registry — every shortcut the app knows about, keyed by+ * `ShortcutId`. The `Record` type ensures this map stays exhaustive: adding a+ * new entry to `SHORTCUT_IDS` without a matching definition here is a type error.+ *+ * See `ShortcutDefinition` for the shape of each entry.+ *+ * @example+ * // Add a new shortcut:+ * // 1. Add to SHORTCUT_IDS:+ * // SQL_EDITOR_RUN: 'sql-editor.run'+ * // 2. Add to SHORTCUT_DEFINITIONS:+ * // [SHORTCUT_IDS.SQL_EDITOR_RUN]: {+ * // id: SHORTCUT_IDS.SQL_EDITOR_RUN,+ * // label: 'Run query',+ * // sequence: ['Mod+Enter'],+ * // }+ * // 3. Use in a component:+ * // useShortcut(SHORTCUT_IDS.SQL_EDITOR_RUN, runQuery)+ */+export const SHORTCUT_DEFINITIONS: Record<ShortcutId, ShortcutDefinition> = {+ [SHORTCUT_IDS.RESULTS_COPY_MARKDOWN]: {+ id: SHORTCUT_IDS.RESULTS_COPY_MARKDOWN,+ label: 'Copy results as Markdown',+ sequence: ['Mod+Shift+M'],+ },+}diff --git a/apps/studio/state/shortcuts/state.ts b/apps/studio/state/shortcuts/state.tsnew file mode 100644index 00000000000..e2e97dce815--- /dev/null+++ b/apps/studio/state/shortcuts/state.ts@@ -0,0 +1,51 @@+import { LOCAL_STORAGE_KEYS } from 'common'+import { useCallback } from 'react'++import type { ShortcutId } from './registry'+import { DisabledShortcuts } from './types'+import { useLocalStorageQuery } from '@/hooks/misc/useLocalStorage'++const STORAGE_KEY = LOCAL_STORAGE_KEYS.SHORTCUT_STORAGE_KEY++const DEFAULT_DISABLED: DisabledShortcuts = {}++export function useShortcutPreferences() {+ const [disabled, setDisabled] = useLocalStorageQuery<DisabledShortcuts>(+ STORAGE_KEY,+ DEFAULT_DISABLED+ )++ const setShortcutEnabled = useCallback(+ (id: ShortcutId, enabled: boolean) => {+ setDisabled((prev) => {+ if (enabled) {+ const { [id]: _removed, ...rest } = prev+ return rest+ }+ return { ...prev, [id]: true }+ })+ },+ [setDisabled]+ )++ const resetShortcut = useCallback(+ (id: ShortcutId) => {+ setDisabled((prev) => {+ const { [id]: _removed, ...rest } = prev+ return rest+ })+ },+ [setDisabled]+ )++ const resetAllShortcuts = useCallback(() => {+ setDisabled(DEFAULT_DISABLED)+ }, [setDisabled])++ return {+ disabled,+ setShortcutEnabled,+ resetShortcut,+ resetAllShortcuts,+ }+}diff --git a/apps/studio/state/shortcuts/types.ts b/apps/studio/state/shortcuts/types.tsnew file mode 100644index 00000000000..8ee1cd3249b--- /dev/null+++ b/apps/studio/state/shortcuts/types.ts@@ -0,0 +1,80 @@+import { HotkeySequence } from '@tanstack/react-hotkeys'++export type DisabledShortcuts = Record<string, boolean>++/**+ * Runtime options for a shortcut. Used in two places:+ *+ * 1. On a `ShortcutDefinition` in the registry — acts as the default options+ * whenever the shortcut is mounted via `useShortcut`.+ * 2. As the third argument to `useShortcut(id, callback, options)` — lets the+ * call site override the registry defaults for a specific mount.+ *+ * Caller options take priority over registry defaults, which take priority over+ * the hard-coded fallbacks listed on each field below.+ */+export interface ShortcutOptions {+ /**+ * Whether the shortcut is live. Defaults to `true`.+ *+ * Conjunctive with the user's global enable/disable preference: if the user+ * has disabled a shortcut in Account → Preferences, passing `enabled: true`+ * here will NOT re-enable it. Use this to gate the shortcut on local+ * conditions (e.g. `enabled: hasUnsavedChanges`).+ */+ enabled?: boolean++ /**+ * Maximum time in milliseconds between consecutive keys in a multi-step+ * sequence. Defaults to `undefined`, which falls through to TanStack's+ * library default (1000ms).+ *+ * Only meaningful for multi-step sequences like `['G', 'G']`. Single-step+ * shortcuts ignore this.+ */+ timeout?: number++ /**+ * When `true`, the shortcut also appears as an entry in the Cmd+P command+ * menu (under the "Shortcuts" section) for as long as the hook is mounted.+ * The entry's label comes from `ShortcutDefinition.label` and the keybind+ * is rendered from `ShortcutDefinition.sequence`.+ *+ * Defaults to `false` — opt-in per call site so Cmd+P doesn't fill up with+ * context-specific shortcuts that only make sense in certain views.+ */+ registerInCommandMenu?: boolean+}++/**+ * A single entry in the shortcut registry. Every shortcut the app uses must+ * have a matching definition in `SHORTCUT_DEFINITIONS`.+ *+ * The registry is the single source of truth for:+ * - the keybind (`sequence`) — used by the hotkey listener AND the Cmd+P badge+ * - the human-readable `label` — shown in Cmd+P and in the preferences UI+ * - per-shortcut default `options` — overridable per call site+ */+export interface ShortcutDefinition {+ /** Stable unique identifier. Must match the key used in `SHORTCUT_IDS`. */+ id: string++ /** Human-readable label shown in the command menu and preferences UI. */+ label: string++ /**+ * Keybind as a TanStack Hotkeys sequence — an array of one or more hotkey+ * strings. Single-step: `['Mod+Shift+M']`. Multi-step (chord): `['G', 'G']`.+ *+ * Use `Mod` for the platform modifier (⌘ on macOS, Ctrl elsewhere). Supports+ * `Shift`, `Alt`, `Ctrl` (literal), named keys (`Enter`, `Escape`, arrows),+ * and single character keys.+ */+ sequence: HotkeySequence++ /**+ * Default runtime options applied when the shortcut is mounted. Each field+ * is overridable by the caller of `useShortcut`.+ */+ options?: ShortcutOptions+}diff --git a/apps/studio/state/shortcuts/useIsShortcutEnabled.ts b/apps/studio/state/shortcuts/useIsShortcutEnabled.tsnew file mode 100644index 00000000000..7518418d7d4--- /dev/null+++ b/apps/studio/state/shortcuts/useIsShortcutEnabled.ts@@ -0,0 +1,20 @@+import type { ShortcutId } from './registry'+import { useShortcutPreferences } from './state'++/**+ * Reactive check for whether a shortcut is currently enabled for the user.+ *+ * Subscribes the calling component to the shortcut preferences query so it+ * re-renders when the user toggles this shortcut in Account → Preferences.+ *+ * For one-off, non-reactive checks outside render (event handlers, module-level+ * code), use the plain `isShortcutEnabled(id)` function from `./state` instead.+ *+ * @example+ * const isEnabled = useIsShortcutEnabled(SHORTCUT_IDS.AI_ASSISTANT_TOGGLE)+ * return <Tooltip>{isEnabled && <KeyboardShortcut keys={['Meta', 'I']} />}</Tooltip>+ */+export function useIsShortcutEnabled(id: ShortcutId): boolean {+ const { disabled } = useShortcutPreferences()+ return !disabled[id]+}diff --git a/apps/studio/state/shortcuts/useShortcut.tsx b/apps/studio/state/shortcuts/useShortcut.tsxnew file mode 100644index 00000000000..c5a9faab23e--- /dev/null+++ b/apps/studio/state/shortcuts/useShortcut.tsx@@ -0,0 +1,94 @@+import { useHotkeySequence } from '@tanstack/react-hotkeys'+import { Fragment, useCallback } from 'react'+import { KeyboardShortcut } from 'ui'+import { useRegisterCommands } from 'ui-patterns/CommandMenu'++import { SHORTCUT_DEFINITIONS, type ShortcutId } from './registry'+import type { ShortcutOptions } from './types'+import { useIsShortcutEnabled } from './useIsShortcutEnabled'+import { COMMAND_MENU_SECTIONS } from '@/components/interfaces/App/CommandMenu/CommandMenu.utils'+import useLatest from '@/hooks/misc/useLatest'++const hotkeyToKeys = (hotkey: string): string[] =>+ hotkey.split('+').map((part) => (part === 'Mod' ? 'Meta' : part))++/**+ * Subscribe to a registered keyboard shortcut.+ *+ * Looks up the shortcut's `sequence` and `label` from `SHORTCUT_DEFINITIONS`,+ * wires up a global hotkey listener via `@tanstack/react-hotkeys`, and+ * (optionally) registers the shortcut as an entry in the Cmd+P command menu+ * under the "Shortcuts" section for as long as the hook is mounted.+ *+ * Option resolution priority (highest first):+ * 1. `options` passed to this hook+ * 2. `def.options` from the registry entry+ * 3. Hard-coded fallbacks (`enabled: true`, `timeout: undefined`, `registerInCommandMenu: false`)+ *+ * `enabled` is ANDed with the user's global enable/disable preference — if the+ * user has disabled the shortcut in Preferences, it won't fire even if the+ * caller or registry say `enabled: true`.+ *+ * @param id The registered shortcut to bind to. See `SHORTCUT_IDS`.+ * @param callback Runs when the sequence matches. Always calls the latest+ * reference — no stale closure issues.+ * @param options Per-mount overrides. See `ShortcutOptions`.+ *+ * @example+ * useShortcut(SHORTCUT_IDS.RESULTS_COPY_MARKDOWN, handleCopy)+ *+ * @example+ * // Surface in Cmd+P while this component is mounted:+ * useShortcut(SHORTCUT_IDS.SQL_EDITOR_RUN, runQuery, {+ * registerInCommandMenu: true,+ * })+ *+ * @example+ * // Gate on local state — disables hotkey AND hides Cmd+P entry when false:+ * useShortcut(SHORTCUT_IDS.SAVE, handleSave, {+ * enabled: hasUnsavedChanges,+ * registerInCommandMenu: true,+ * })+ */+export function useShortcut(id: ShortcutId, callback: () => void, options?: ShortcutOptions) {+ const def = SHORTCUT_DEFINITIONS[id]++ // Handle override for the shortcut+ const globallyEnabled = useIsShortcutEnabled(id)+ const callerEnabled = options?.enabled ?? def.options?.enabled ?? true+ const enabled = globallyEnabled && callerEnabled+ const timeout = options?.timeout ?? def.options?.timeout ?? undefined++ useHotkeySequence(def.sequence, callback, { enabled, timeout })++ // Handle overrides for command menu+ const enabledInCommandMenu = enabled && (options?.registerInCommandMenu ?? false)+ const depsInCommandMenu = [enabled, def.label]+ const callbackRef = useLatest(callback)+ const stableAction = useCallback(() => callbackRef.current(), [callbackRef])++ useRegisterCommands(+ COMMAND_MENU_SECTIONS.SHORTCUTS,+ [+ {+ id,+ name: def.label,+ action: stableAction,+ badge: () => (+ <div className="flex items-center gap-1">+ {def.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: depsInCommandMenu,+ }+ )+}diff --git a/packages/common/constants/local-storage.ts b/packages/common/constants/local-storage.tsindex 34ae866c281..2f37b3dc6be 100644--- a/packages/common/constants/local-storage.ts+++ b/packages/common/constants/local-storage.ts@@ -80,6 +80,9 @@ export const LOCAL_STORAGE_KEYS = {// api keys view switcher for new and legacy api keysAPI_KEYS_VIEW: (ref: string) => `supabase-api-keys-view-${ref}`,+ // Shortcut preferences+ SHORTCUT_STORAGE_KEY: 'supabase-shortcut-preferences',+LAST_VISITED_ORGANIZATION: 'last-visited-organization',// user impersonation selector previous searchesdiff --git a/pnpm-lock.yaml b/pnpm-lock.yamlindex 33f27f05861..7de592f0234 100644--- a/pnpm-lock.yaml+++ b/pnpm-lock.yaml@@ -933,7 +933,7 @@ importers:version: 1.1.3(@types/[email protected])(@types/[email protected])([email protected]([email protected]))([email protected])'@sentry/nextjs':specifier: 'catalog:'- version: 10.27.0(@opentelemetry/[email protected](@opentelemetry/[email protected]))(@opentelemetry/[email protected](@opentelemetry/[email protected]))(@opentelemetry/[email protected](@opentelemetry/[email protected]))([email protected])([email protected](@opentelemetry/[email protected])(@playwright/[email protected])([email protected]([email protected]))([email protected])([email protected]))([email protected])([email protected])([email protected]([email protected]))+ version: 10.27.0(@opentelemetry/[email protected](@opentelemetry/[email protected]))(@opentelemetry/[email protected](@opentelemetry/[email protected]))(@opentelemetry/[email protected](@opentelemetry/[email protected]))([email protected])([email protected](@babel/[email protected]([email protected]))(@opentelemetry/[email protected])(@playwright/[email protected])([email protected]([email protected]))([email protected])([email protected]))([email protected])([email protected])([email protected]([email protected]))'@std/path':specifier: npm:@jsr/std__path@^1.0.8version: '@jsr/[email protected]'@@ -967,6 +967,9 @@ importers:'@supabase/supabase-js':specifier: 'catalog:'version: 2.103.2+ '@tanstack/react-hotkeys':+ specifier: ^0.9.1'@tanstack/react-query':specifier: ^5.0.0version: 5.83.0([email protected])@@ -1086,7 +1089,7 @@ importers:nuqs:specifier: 2.7.1- version: 2.7.1(@tanstack/[email protected]([email protected]([email protected]))([email protected]))([email protected](@opentelemetry/[email protected])(@playwright/[email protected])([email protected]([email protected]))([email protected])([email protected]))([email protected]([email protected]([email protected]))([email protected]))([email protected])+ version: 2.7.1(@tanstack/[email protected]([email protected]([email protected]))([email protected]))([email protected](@babel/[email protected]([email protected]))(@opentelemetry/[email protected])(@playwright/[email protected])([email protected]([email protected]))([email protected])([email protected]))([email protected]([email protected]([email protected]))([email protected]))([email protected])openai:specifier: ^4.104.0@@ -8945,12 +8948,23 @@ packages:resolution: {integrity: sha512-NaOGLRrddszbQj9upGat6HG/4TKvXLvu+osAIgfxPYA+eIvYKv8GKDJOrY2D3/U9MRnKfMWD7bU4jeD4xmqyIg==}engines: {node: '>=20.19'}+ '@tanstack/[email protected]':+ resolution: {integrity: sha512-YHVO1z6wnvUCu7bg870Kv5k2D+FIuIOSIcbN0dAmTTsJ3mLMDLwcTVx0qVaq+SZp1B514JJTqGVstvUp85yIpQ==}+ engines: {node: '>=18'}+'@tanstack/[email protected]':resolution: {integrity: sha512-0M8dA+amXUkyz5cVUm/B+zSk3xkQAcuXuz5/Q/LveT4ots2rBpPTZOzd7yJa2Utsf8D2Upl5KyjhHRY+9lB/XA==}'@tanstack/[email protected]':resolution: {integrity: sha512-GtINOPjPUH0OegJExZ70UahT9ykmAhmtNVcmtdnOZbxLwT7R5OmRztR5Ahe3/Cu7LArEmR6/588tAycuaWb1xQ==}+ '@tanstack/[email protected]':+ resolution: {integrity: sha512-/qdQUUVkYAHAWRGdFXqFgWpW/S+a6OzkvxWNWKLLDHQODJlO6EPBPa073CglaafBfzig58RK07T09ET+NnZhpg==}+ engines: {node: '>=18'}+ peerDependencies:+ react: '>=16.8'+ react-dom: '>=16.8'+'@tanstack/[email protected]':resolution: {integrity: sha512-vAXJzZuBXtCQtrY3F/yUNJCV4obT/A/n81kb3+YqLbro5Z2+phdAbceO+deU3ywPw8B42oyJlp4FhO0SoivDFQ==}peerDependencies:@@ -25761,7 +25775,7 @@ snapshots:- supports-color- webpack- '@sentry/[email protected](@opentelemetry/[email protected](@opentelemetry/[email protected]))(@opentelemetry/[email protected](@opentelemetry/[email protected]))(@opentelemetry/[email protected](@opentelemetry/[email protected]))([email protected])([email protected](@opentelemetry/[email protected])(@playwright/[email protected])([email protected]([email protected]))([email protected])([email protected]))([email protected])([email protected])([email protected]([email protected]))':+ '@sentry/[email protected](@opentelemetry/[email protected](@opentelemetry/[email protected]))(@opentelemetry/[email protected](@opentelemetry/[email protected]))(@opentelemetry/[email protected](@opentelemetry/[email protected]))([email protected])([email protected](@babel/[email protected]([email protected]))(@opentelemetry/[email protected])(@playwright/[email protected])([email protected]([email protected]))([email protected])([email protected]))([email protected])([email protected])([email protected]([email protected]))':dependencies:'@opentelemetry/api': 1.9.0'@opentelemetry/semantic-conventions': 1.38.0@@ -26519,10 +26533,21 @@ snapshots:'@tanstack/[email protected]': {}+ '@tanstack/[email protected]':+ dependencies:+ '@tanstack/store': 0.9.3+'@tanstack/[email protected]': {}'@tanstack/[email protected]': {}+ dependencies:+ '@tanstack/hotkeys': 0.7.1+ react: 18.3.1+ react-dom: 18.3.1([email protected])+dependencies:'@tanstack/query-devtools': 5.90.1@@ -34199,7 +34224,7 @@ snapshots:mitt: 3.0.1next: 15.5.15(@babel/[email protected]([email protected]))(@opentelemetry/[email protected])(@playwright/[email protected])([email protected]([email protected]))([email protected])([email protected])- [email protected](@tanstack/[email protected]([email protected]([email protected]))([email protected]))([email protected](@opentelemetry/[email protected])(@playwright/[email protected])([email protected]([email protected]))([email protected])([email protected]))([email protected]([email protected]([email protected]))([email protected]))([email protected]):+ [email protected](@tanstack/[email protected]([email protected]([email protected]))([email protected]))([email protected](@babel/[email protected]([email protected]))(@opentelemetry/[email protected])(@playwright/[email protected])([email protected]([email protected]))([email protected])([email protected]))([email protected]([email protected]([email protected]))([email protected]))([email protected]):dependencies:'@standard-schema/spec': 1.0.0react: 18.3.1