refactor useHotkey to make more sense

Author: KevinVandy

package.json

@@ -8,7 +8,7 @@
   "packageManager": "pnpm@10.28.2",
   "type": "module",
   "scripts": {
-    "build": "nx affected --skip-nx-cache --targets=build --exclude=examples/**",
+    "build": "nx affected --skip-nx-cache --targets=build --exclude=examples/** && size-limit",
     "build:all": "nx run-many --targets=build --exclude=examples/**",
     "build:core": "nx run-many --targets=build --projects=packages/keys",
     "changeset": "changeset",
@@ -36,6 +36,12 @@
     "test:types": "nx affected --targets=test:types --exclude=examples/**",
     "watch": "pnpm run build:all && nx watch --all -- pnpm run build:all"
   },
+  "size-limit": [
+    {
+      "path": "packages/keys/dist/index.js",
+      "limit": "8 KB"
+    }
+  ],
   "nx": {
     "includedScripts": [
       "test:docs",
@@ -46,6 +52,7 @@
   "devDependencies": {
     "@changesets/cli": "^2.29.8",
     "@faker-js/faker": "^10.2.0",
+    "@size-limit/preset-small-lib": "^12.0.0",
     "@svitejs/changesets-changelog-github-compact": "^1.2.0",
     "@tanstack/eslint-config": "0.3.4",
     "@tanstack/typedoc-config": "0.3.3",
@@ -62,6 +69,7 @@
     "prettier-plugin-svelte": "^3.4.1",
     "publint": "^0.3.17",
     "sherif": "^1.10.0",
+    "size-limit": "^12.0.0",
     "tinyglobby": "^0.2.15",
     "tsdown": "^0.20.1",
     "typescript": "5.9.3",

packages/keys/src/index.ts

@@ -30,6 +30,7 @@ export type {
   SequenceOptions,
   // Registration types
   HotkeyRegistration,
+  HotkeyRegistrationHandle,
 } from './types'
 
 // =============================================================================

packages/keys/src/manager.ts

@@ -7,8 +7,24 @@ import type {
   HotkeyCallbackContext,
   HotkeyOptions,
   HotkeyRegistration,
+  HotkeyRegistrationHandle,
 } from './types'
 
+/**
+ * Default options for hotkey registration.
+ */
+const defaultHotkeyOptions: Omit<
+  Required<HotkeyOptions>,
+  'platform' | 'target'
+> = {
+  preventDefault: false,
+  stopPropagation: false,
+  eventType: 'keydown',
+  requireReset: false,
+  enabled: true,
+  ignoreInputs: true,
+}
+
 let registrationIdCounter = 0
 
 /**
@@ -79,18 +95,35 @@ export class HotkeyManager {
   }
 
   /**
-   * Registers a hotkey handler.
+   * Registers a hotkey handler and returns a handle for updating the registration.
+   *
+   * The returned handle allows updating the callback and options without
+   * re-registering, which is useful for avoiding stale closures in React.
    *
    * @param hotkey - The hotkey string to listen for
    * @param callback - The function to call when the hotkey is pressed
    * @param options - Options for the hotkey behavior
-   * @returns A function to unregister the hotkey
+   * @returns A handle for managing the registration
+   *
+   * @example
+   * ```ts
+   * const handle = manager.register('Mod+S', callback, { preventDefault: true })
+   *
+   * // Update callback without re-registering (avoids stale closures)
+   * handle.callback = newCallback
+   *
+   * // Update options
+   * handle.setOptions({ enabled: false })
+   *
+   * // Unregister when done
+   * handle.unregister()
+   * ```
    */
   register(
     hotkey: Hotkey,
     callback: HotkeyCallback,
     options: HotkeyOptions = {},
-  ): () => void {
+  ): HotkeyRegistrationHandle {
     const id = generateId()
     const platform = options.platform ?? this.platform
     const parsedHotkey = parseHotkey(hotkey, platform)
@@ -105,12 +138,7 @@ export class HotkeyManager {
       parsedHotkey,
       callback,
       options: {
-        preventDefault: false,
-        stopPropagation: false,
-        eventType: 'keydown',
-        requireReset: false,
-        enabled: true,
-        ignoreInputs: true,
+        ...defaultHotkeyOptions,
         ...options,
         platform,
       },
@@ -129,9 +157,37 @@ export class HotkeyManager {
     // Ensure listeners are attached for this target
     this.ensureListenersForTarget(target)
 
-    return () => {
-      this.unregister(id)
+    // Create and return the handle
+    const manager = this
+    const handle: HotkeyRegistrationHandle = {
+      get id() {
+        return id
+      },
+      unregister: () => {
+        manager.unregister(id)
+      },
+      get callback() {
+        const reg = manager.registrations.get(id)
+        return reg?.callback ?? callback
+      },
+      set callback(newCallback: HotkeyCallback) {
+        const reg = manager.registrations.get(id)
+        if (reg) {
+          reg.callback = newCallback
+        }
+      },
+      setOptions: (newOptions: Partial<HotkeyOptions>) => {
+        const reg = manager.registrations.get(id)
+        if (reg) {
+          reg.options = { ...reg.options, ...newOptions }
+        }
+      },
+      get isActive() {
+        return manager.registrations.has(id)
+      },
     }
+
+    return handle
   }
 
   /**
@@ -443,11 +499,18 @@ export class HotkeyManager {
 
   /**
    * Checks if a specific hotkey is registered.
+   *
+   * @param hotkey - The hotkey string to check
+   * @param target - Optional target element to match (if provided, both hotkey and target must match)
+   * @returns True if a matching registration exists
    */
-  isRegistered(hotkey: Hotkey): boolean {
+  isRegistered(hotkey: Hotkey, target?: HTMLElement | Document | Window): boolean {
     for (const registration of this.registrations.values()) {
       if (registration.hotkey === hotkey) {
-        return true
+        // If target is specified, both must match
+        if (target === undefined || registration.target === target) {
+          return true
+        }
       }
     }
     return false

packages/keys/src/types.ts

@@ -462,3 +462,52 @@ export interface HotkeyRegistration {
   /** The resolved target element for this registration */
   target: HTMLElement | Document | Window
 }
+
+/**
+ * A handle returned from HotkeyManager.register() that allows updating
+ * the callback and options without re-registering the hotkey.
+ *
+ * This pattern is similar to TanStack Pacer's Debouncer, where the function
+ * and options can be synced on every render to avoid stale closures.
+ *
+ * @example
+ * ```ts
+ * const handle = manager.register('Mod+S', callback, options)
+ *
+ * // Update callback without re-registering (avoids stale closures)
+ * handle.callback = newCallback
+ *
+ * // Update options without re-registering
+ * handle.setOptions({ enabled: false })
+ *
+ * // Check if still active
+ * if (handle.isActive) {
+ *   // ...
+ * }
+ *
+ * // Unregister when done
+ * handle.unregister()
+ * ```
+ */
+export interface HotkeyRegistrationHandle {
+  /** Unique identifier for this registration */
+  readonly id: string
+
+  /** Unregister this hotkey */
+  unregister: () => void
+
+  /**
+   * The callback function. Can be set directly to update without re-registering.
+   * This avoids stale closures when the callback references React state.
+   */
+  callback: HotkeyCallback
+
+  /**
+   * Update options (merged with existing options).
+   * Useful for updating `enabled`, `preventDefault`, etc. without re-registering.
+   */
+  setOptions: (options: Partial<HotkeyOptions>) => void
+
+  /** Check if this registration is still active (not unregistered) */
+  readonly isActive: boolean
+}