feat: migrate to hotkeys

.changeset/many-squids-watch.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/devtools': minor
+---
+
+Migrate to TanStack Hotkeys

.gitignore

@@ -58,4 +58,5 @@ vite.config.ts.timestamp-*
 .angular
 .nitro
 .sonda
-*settings.local.json
+*settings.local.json
+.claude/worktrees/*

docs/configuration.md

@@ -41,22 +41,18 @@ The `config` object is mainly focused around user interaction with the devtools
 { panelLocation: 'top' | 'bottom' }
 ```
 
-- `openHotkey` - The hotkey set to open the devtools
+- `openHotkey` - The hotkey to open the devtools. Uses the [`Hotkey`](https://tanstack.com/hotkeys) type from `@tanstack/hotkeys` (e.g. `"Control+\``"`, `"Mod+D"`). `Mod` maps to Command on macOS and Control on Windows/Linux.
 
 ```ts
-type ModifierKey = 'Alt' | 'Control' | 'Meta' | 'Shift' | 'CtrlOrMeta';
-type KeyboardKey = ModifierKey | (string & {});
+import type { Hotkey } from '@tanstack/hotkeys'
 
-{ openHotkey: Array<KeyboardKey> }
+{ openHotkey: Hotkey }
 ```
 
-- `inspectHotkey` - The hotkey set to open the source inspector
+- `inspectHotkey` - The hotkey to open the source inspector. Uses [TanStack Hotkeys](https://tanstack.com/hotkeys) string format (e.g. `"Mod+Shift"`). `Mod` maps to Command on macOS and Control on Windows/Linux.
 
 ```ts
-type ModifierKey = 'Alt' | 'Control' | 'Meta' | 'Shift' | 'CtrlOrMeta';
-type KeyboardKey = ModifierKey | (string & {});
-
-{ inspectHotkey: Array<KeyboardKey> }
+{ inspectHotkey: string }
 ```
 
 - `requireUrlFlag` - Requires a flag present in the url to enable devtools

docs/reference/interfaces/tanstackdevtoolsinit.md

@@ -18,7 +18,8 @@ optional config: Partial<{
   customTrigger: (el, props) => void;
   defaultOpen: boolean;
   hideUntilHover: boolean;
-  openHotkey: KeyboardKey[];
+  openHotkey: Hotkey;
+  inspectHotkey: string;
   panelLocation: "top" | "bottom";
   position: TriggerPosition;
   requireUrlFlag: boolean;

packages/devtools/package.json

@@ -60,11 +60,11 @@
   },
   "dependencies": {
     "@solid-primitives/event-listener": "^2.4.3",
-    "@solid-primitives/keyboard": "^1.3.3",
     "@solid-primitives/resize-observer": "^2.1.3",
     "@tanstack/devtools-client": "workspace:*",
     "@tanstack/devtools-event-bus": "workspace:*",
     "@tanstack/devtools-ui": "workspace:*",
+    "@tanstack/solid-hotkeys": "^0.3.0",
     "clsx": "^2.1.1",
     "goober": "^2.1.16",
     "solid-js": "^1.9.9"

packages/devtools/src/components/source-inspector.tsx

@@ -1,11 +1,12 @@
 import { createEffect, createMemo, createSignal } from 'solid-js'
 import { createStore } from 'solid-js/store'
 import { createElementSize } from '@solid-primitives/resize-observer'
-import { useKeyDownList } from '@solid-primitives/keyboard'
+import { createHeldKeys } from '@tanstack/solid-hotkeys'
 import { createEventListener } from '@solid-primitives/event-listener'
 
 import { useDevtoolsSettings } from '../context/use-devtools-context'
-import { isHotkeyCombinationPressed } from '../utils/hotkey'
+import { initialState } from '../context/devtools-store'
+import { isHotkeyHeld } from '../utils/hotkey'
 
 export const SourceInspector = () => {
   const { settings } = useDevtoolsSettings()
@@ -28,10 +29,12 @@ export const SourceInspector = () => {
     setMousePosition({ x: e.clientX, y: e.clientY })
   })
 
-  const downList = useKeyDownList()
+  const heldKeys = createHeldKeys()
 
   const isHighlightingKeysHeld = createMemo(() => {
-    return isHotkeyCombinationPressed(downList(), settings().inspectHotkey)
+    const hotkey =
+      settings().inspectHotkey || initialState.settings.inspectHotkey
+    return isHotkeyHeld(heldKeys(), hotkey)
   })
 
   createEffect(() => {

packages/devtools/src/context/devtools-store.ts

@@ -1,17 +1,7 @@
+import type { Hotkey } from '@tanstack/solid-hotkeys'
 import type { TabName } from '../tabs'
 import type { TanStackDevtoolsPlugin } from './devtools-context'
 
-type ModifierKey = 'Alt' | 'Control' | 'Meta' | 'Shift' | 'CtrlOrMeta'
-type KeyboardKey = ModifierKey | (string & {})
-export type { ModifierKey, KeyboardKey }
-export const keyboardModifiers: Array<ModifierKey> = [
-  'Alt',
-  'Control',
-  'Meta',
-  'Shift',
-  'CtrlOrMeta',
-]
-
 type TriggerPosition =
   | 'top-left'
   | 'top-right'
@@ -48,15 +38,19 @@ export type DevtoolsStore = {
      */
     panelLocation: 'top' | 'bottom'
     /**
-     * The hotkey to open the dev tools
-     * @default ["Control", "~"]
+     * The hotkey to open the dev tools.
+     * Uses TanStack Hotkeys string format (e.g. "Mod+S", "Control+`").
+     * "Mod" maps to Command on macOS and Control on Windows/Linux.
+     * @default "Control+`"
      */
-    openHotkey: Array<KeyboardKey>
+    openHotkey: Hotkey
     /**
-     * The hotkey to open the source inspector
-     * @default ["Shift", "Alt", "CtrlOrMeta"]
+     * The hotkey to open the source inspector.
+     * Uses TanStack Hotkeys string format (e.g. "Mod+Shift").
+     * "Mod" maps to Command on macOS and Control on Windows/Linux.
+     * @default "Mod+Alt+Shift"
      */
-    inspectHotkey: Array<KeyboardKey>
+    inspectHotkey: string
     /**
      * Whether to require the URL flag to open the dev tools
      * @default false
@@ -99,8 +93,8 @@ export const initialState: DevtoolsStore = {
     hideUntilHover: false,
     position: 'bottom-right',
     panelLocation: 'bottom',
-    openHotkey: ['Control', '~'],
-    inspectHotkey: ['Shift', 'Alt', 'CtrlOrMeta'],
+    openHotkey: 'Control+`',
+    inspectHotkey: 'Mod+Alt+Shift',
     requireUrlFlag: false,
     urlFlag: 'tanstack-devtools',
     theme:

packages/devtools/src/devtools.tsx

@@ -1,5 +1,5 @@
 import { Show, createEffect, createSignal, onCleanup } from 'solid-js'
-import { createShortcut } from '@solid-primitives/keyboard'
+import { createHotkey } from '@tanstack/solid-hotkeys'
 import { Portal } from 'solid-js/web'
 import { ThemeContextProvider } from '@tanstack/devtools-ui'
 import { devtoolsEventClient } from '@tanstack/devtools-client'
@@ -12,7 +12,6 @@ import {
 } from './context/use-devtools-context'
 import { useDisableTabbing } from './hooks/use-disable-tabbing'
 import { TANSTACK_DEVTOOLS } from './utils/storage'
-import { getHotkeyPermutations } from './utils/hotkey'
 import { Trigger } from './components/trigger'
 import { MainPanel } from './components/main-panel'
 import { ContentPanel } from './components/content-panel'
@@ -164,30 +163,24 @@ export default function DevTools() {
       el?.style.setProperty('--tsrd-font-size', fontSize)
     }
   })
-  createEffect(() => {
-    const isEditableTarget = (element: Element | null) => {
-      if (!element || !(element instanceof HTMLElement)) return false
-      if (element.isContentEditable) return true
-      const tagName = element.tagName
-      if (
-        tagName === 'INPUT' ||
-        tagName === 'TEXTAREA' ||
-        tagName === 'SELECT'
-      ) {
-        return true
-      }
-      return element.getAttribute('role') === 'textbox'
+  const isEditableTarget = (element: Element | null) => {
+    if (!element || !(element instanceof HTMLElement)) return false
+    if (element.isContentEditable) return true
+    const tagName = element.tagName
+    if (tagName === 'INPUT' || tagName === 'TEXTAREA' || tagName === 'SELECT') {
+      return true
     }
+    return element.getAttribute('role') === 'textbox'
+  }
 
-    const permutations = getHotkeyPermutations(settings().openHotkey)
-
-    for (const permutation of permutations) {
-      createShortcut(permutation, () => {
-        if (isEditableTarget(document.activeElement)) return
-        toggleOpen()
-      })
-    }
-  })
+  createHotkey(
+    () => settings().openHotkey,
+    () => {
+      if (isEditableTarget(document.activeElement)) return
+      toggleOpen()
+    },
+    { preventDefault: false, stopPropagation: false },
+  )
 
   const { theme } = useTheme()
 

packages/devtools/src/tabs/hotkey-config.tsx

@@ -1,72 +1,70 @@
 import { Show } from 'solid-js'
 import { Button, Input } from '@tanstack/devtools-ui'
 
-import { uppercaseFirstLetter } from '../utils/sanitize'
 import { useStyles } from '../styles/use-styles'
-import type { KeyboardKey } from '../context/devtools-store'
+import type { Key, Modifier } from '@tanstack/solid-hotkeys'
 
-interface HotkeyConfigProps {
+interface HotkeyConfigProps<T extends string = string> {
   title: string
   description: string
-  hotkey: Array<KeyboardKey>
-  modifiers: Array<KeyboardKey>
-  onHotkeyChange: (hotkey: Array<KeyboardKey>) => void
+  hotkey: T | null | undefined
+  modifiers: Array<Modifier>
+  onHotkeyChange: (hotkey: T) => void
 }
 
-const MODIFIER_DISPLAY_NAMES: Record<KeyboardKey, string> = {
+const MODIFIER_DISPLAY_NAMES: Partial<Record<Modifier, string>> = {
   Shift: 'Shift',
   Alt: 'Alt',
-  Meta: 'Meta',
+  Mod: 'Ctrl Or Cmd',
   Control: 'Control',
-  CtrlOrMeta: 'Ctrl Or Meta',
+  Command: 'Command',
 }
 
-export const HotkeyConfig = (props: HotkeyConfigProps) => {
+/** Splits a hotkey string like "Mod+Shift+A" into its parts */
+const parseHotkeyParts = (
+  hotkey: string | null | undefined,
+  modifiers: Array<Modifier>,
+): { activeModifiers: Array<Modifier>; key: string } => {
+  if (typeof hotkey !== 'string' || !hotkey)
+    return { activeModifiers: [], key: '' }
+  const parts = hotkey.split('+').map((p) => p.trim())
+  const modifierStrings: Array<string> = modifiers
+  const activeModifiers = parts.filter((p): p is Modifier =>
+    modifierStrings.includes(p),
+  )
+  const keyParts = parts.filter((p) => !modifierStrings.includes(p))
+  return { activeModifiers, key: keyParts.join('+') }
+}
+
+/** Joins modifiers and key back into a hotkey string */
+const buildHotkeyString = (
+  modifiers: Array<Modifier>,
+  key: Key | string,
+): string => {
+  const parts: Array<string> = [...modifiers]
+  if (key) parts.push(key)
+  return parts.join('+')
+}
+
+export const HotkeyConfig = <T extends string>(props: HotkeyConfigProps<T>) => {
   const styles = useStyles()
 
-  const toggleModifier = (modifier: KeyboardKey) => {
-    if (props.hotkey.includes(modifier)) {
-      props.onHotkeyChange(props.hotkey.filter((key) => key !== modifier))
+  const parsed = () => parseHotkeyParts(props.hotkey, props.modifiers)
+
+  const toggleModifier = (modifier: Modifier) => {
+    const { activeModifiers, key } = parsed()
+    let newModifiers: Array<Modifier>
+    if (activeModifiers.includes(modifier)) {
+      newModifiers = activeModifiers.filter((m) => m !== modifier)
     } else {
-      const existingModifiers = props.hotkey.filter((key) =>
-        props.modifiers.includes(key as any),
-      )
-      const otherKeys = props.hotkey.filter(
-        (key) => !props.modifiers.includes(key as any),
-      )
-      props.onHotkeyChange([...existingModifiers, modifier, ...otherKeys])
+      newModifiers = [...activeModifiers, modifier]
     }
-  }
-
-  const getNonModifierValue = () => {
-    return props.hotkey
-      .filter((key) => !props.modifiers.includes(key as any))
-      .join('+')
+    props.onHotkeyChange(buildHotkeyString(newModifiers, key) as T)
   }
 
   const handleKeyInput = (input: string) => {
-    const makeModifierArray = (key: string) => {
-      if (key.length === 1) return [uppercaseFirstLetter(key)]
-      const modifiersArray: Array<string> = []
-      for (const character of key) {
-        const newLetter = uppercaseFirstLetter(character)
-        if (!modifiersArray.includes(newLetter)) modifiersArray.push(newLetter)
-      }
-      return modifiersArray
-    }
-
-    const hotkeyModifiers = props.hotkey.filter((key) =>
-      props.modifiers.includes(key as any),
-    )
-    const newKeys = input
-      .split('+')
-      .flatMap((key) => makeModifierArray(key))
-      .filter(Boolean)
-    props.onHotkeyChange([...hotkeyModifiers, ...newKeys])
-  }
-
-  const getDisplayHotkey = () => {
-    return props.hotkey.join(' + ')
+    const { activeModifiers } = parsed()
+    props.onHotkeyChange(buildHotkeyString(activeModifiers, input) as T)
   }
 
   return (
@@ -78,7 +76,7 @@ export const HotkeyConfig = (props: HotkeyConfigProps) => {
             <Button
               variant="success"
               onclick={() => toggleModifier(modifier)}
-              outline={!props.hotkey.includes(modifier)}
+              outline={!parsed().activeModifiers.includes(modifier)}
             >
               {MODIFIER_DISPLAY_NAMES[modifier] || modifier}
             </Button>
@@ -88,10 +86,10 @@ export const HotkeyConfig = (props: HotkeyConfigProps) => {
       <Input
         description="Use '+' to combine keys (e.g., 'a+b' or 'd'). This will be used with the enabled modifiers from above"
         placeholder="a"
-        value={getNonModifierValue()}
+        value={parsed().key}
         onChange={handleKeyInput}
       />
-      Final shortcut is: {getDisplayHotkey()}
+      Final shortcut is: {props.hotkey}
     </div>
   )
 }

packages/devtools/src/tabs/settings-tab.tsx

@@ -19,13 +19,13 @@ import {
 import { useDevtoolsSettings } from '../context/use-devtools-context'
 import { useStyles } from '../styles/use-styles'
 import { HotkeyConfig } from './hotkey-config'
-import type { KeyboardKey } from '../context/devtools-store'
+import type { Modifier } from '@tanstack/solid-hotkeys'
 
 export const SettingsTab = () => {
   const { setSettings, settings } = useDevtoolsSettings()
   const styles = useStyles()
 
-  const modifiers: Array<KeyboardKey> = ['CtrlOrMeta', 'Alt', 'Shift']
+  const modifiers: Array<Modifier> = ['Mod', 'Alt', 'Shift']
 
   return (
     <MainPanel withPadding>