@tanstack/preact-hotkeys 0.11.0 → 0.12.1

package/dist/useHotkeys.cjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"useHotkeys.cjs","names":["useDefaultHotkeysOptions","isRef"],"sources":["../src/useHotkeys.ts"],"sourcesContent":["import { useEffect, useRef } from 'preact/hooks'\nimport {\n  detectPlatform,\n  getHotkeyManager,\n  normalizeRegisterableHotkey,\n} from '@tanstack/hotkeys'\nimport { useDefaultHotkeysOptions } from './HotkeysProvider'\nimport { isRef } from './utils'\nimport type { UseHotkeyOptions } from './useHotkey'\nimport type {\n  Hotkey,\n  HotkeyCallback,\n  HotkeyRegistrationHandle,\n  RegisterableHotkey,\n} from '@tanstack/hotkeys'\n\n/**\n * A single hotkey definition for use with `useHotkeys`.\n */\nexport interface UseHotkeyDefinition {\n  /** The hotkey string (e.g., 'Mod+S', 'Escape') or RawHotkey object */\n  hotkey: RegisterableHotkey\n  /** The function to call when the hotkey is pressed */\n  callback: HotkeyCallback\n  /** Per-hotkey options (merged on top of commonOptions) */\n  options?: UseHotkeyOptions\n}\n\n/**\n * Preact hook for registering multiple keyboard hotkeys at once.\n *\n * Uses the singleton HotkeyManager for efficient event handling.\n * Accepts a dynamic array of hotkey definitions, making it safe to use\n * with variable-length lists without violating the rules of hooks.\n *\n * Options are merged in this order:\n * HotkeysProvider defaults < commonOptions < per-definition options\n *\n * Callbacks and options are synced on every render to avoid stale closures.\n *\n * @param hotkeys - Array of hotkey definitions to register\n * @param commonOptions - Shared options applied to all hotkeys (overridden by per-definition options).\n *   Per-row `enabled: false` still registers that hotkey: `HotkeyManager` suppresses execution only (the row\n *   stays in the store and appears in TanStack Hotkeys devtools). Toggling `enabled` updates the existing handle\n *   via `setOptions` (no unregister/re-register churn).\n *\n * @example\n * ```tsx\n * function Editor() {\n *   useHotkeys([\n *     { hotkey: 'Mod+S', callback: () => save() },\n *     { hotkey: 'Mod+Z', callback: () => undo() },\n *     { hotkey: 'Escape', callback: () => close() },\n *   ])\n * }\n * ```\n *\n * @example\n * ```tsx\n * function MenuShortcuts({ items }) {\n *   // Dynamic hotkeys from data -- safe because it's a single hook call\n *   useHotkeys(\n *     items.map((item) => ({\n *       hotkey: item.shortcut,\n *       callback: item.action,\n *       options: { enabled: item.enabled },\n *     })),\n *     { preventDefault: true },\n *   )\n * }\n * ```\n */\nexport function useHotkeys(\n  hotkeys: Array<UseHotkeyDefinition>,\n  commonOptions: UseHotkeyOptions = {},\n): void {\n  type RegistrationRecord = {\n    handle: HotkeyRegistrationHandle\n    target: Document | HTMLElement | Window\n  }\n\n  const defaultOptions = useDefaultHotkeysOptions().hotkey\n  const manager = getHotkeyManager()\n  const platform =\n    commonOptions.platform ?? defaultOptions?.platform ?? detectPlatform()\n\n  const registrationsRef = useRef<Map<string, RegistrationRecord>>(new Map())\n  const hotkeysRef = useRef(hotkeys)\n  const hotkeyStringsRef = useRef<Array<Hotkey>>([])\n  const commonOptionsRef = useRef(commonOptions)\n  const defaultOptionsRef = useRef(defaultOptions)\n  const managerRef = useRef(manager)\n\n  const hotkeyStrings = hotkeys.map((def) =>\n    normalizeRegisterableHotkey(def.hotkey, platform),\n  )\n\n  hotkeysRef.current = hotkeys\n  hotkeyStringsRef.current = hotkeyStrings\n  commonOptionsRef.current = commonOptions\n  defaultOptionsRef.current = defaultOptions\n  managerRef.current = manager\n\n  useEffect(() => {\n    const prevRegistrations = registrationsRef.current\n    const nextRegistrations = new Map<string, RegistrationRecord>()\n\n    const rows: Array<{\n      registrationKey: string\n      def: (typeof hotkeysRef.current)[number]\n      hotkeyStr: Hotkey\n      mergedOptions: UseHotkeyOptions\n      resolvedTarget: Document | HTMLElement | Window\n    }> = []\n\n    for (let i = 0; i < hotkeysRef.current.length; i++) {\n      const def = hotkeysRef.current[i]!\n      const hotkeyStr = hotkeyStringsRef.current[i]!\n      const mergedOptions = {\n        ...defaultOptionsRef.current,\n        ...commonOptionsRef.current,\n        ...def.options,\n      } as UseHotkeyOptions\n\n      const resolvedTarget = isRef(mergedOptions.target)\n        ? mergedOptions.target.current\n        : (mergedOptions.target ??\n          (typeof document !== 'undefined' ? document : null))\n\n      if (!resolvedTarget) {\n        continue\n      }\n\n      const registrationKey = `${i}:${hotkeyStr}`\n      rows.push({\n        registrationKey,\n        def,\n        hotkeyStr,\n        mergedOptions,\n        resolvedTarget,\n      })\n    }\n\n    const nextKeys = new Set(rows.map((r) => r.registrationKey))\n\n    for (const [key, record] of prevRegistrations) {\n      if (!nextKeys.has(key) && record.handle.isActive) {\n        record.handle.unregister()\n      }\n    }\n\n    for (const row of rows) {\n      const { registrationKey, def, hotkeyStr, mergedOptions, resolvedTarget } =\n        row\n\n      const existing = prevRegistrations.get(registrationKey)\n      if (existing?.handle.isActive && existing.target === resolvedTarget) {\n        // Publish callback/options only after commit, never during render.\n        existing.handle.callback = def.callback\n        const { target: _target, ...optionsWithoutTarget } = mergedOptions\n        existing.handle.setOptions(optionsWithoutTarget)\n        nextRegistrations.set(registrationKey, existing)\n        continue\n      }\n\n      if (existing?.handle.isActive) {\n        existing.handle.unregister()\n      }\n\n      const handle = managerRef.current.register(hotkeyStr, def.callback, {\n        ...mergedOptions,\n        target: resolvedTarget,\n      })\n      nextRegistrations.set(registrationKey, {\n        handle,\n        target: resolvedTarget,\n      })\n    }\n\n    registrationsRef.current = nextRegistrations\n  })\n\n  useEffect(() => {\n    return () => {\n      for (const { handle } of registrationsRef.current.values()) {\n        if (handle.isActive) {\n          handle.unregister()\n        }\n      }\n      registrationsRef.current = new Map()\n    }\n  }, [])\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwEA,SAAgB,WACd,SACA,gBAAkC,EAAE,EAC9B;CAMN,MAAM,iBAAiBA,kDAA0B,CAAC;CAClD,MAAM,mDAA4B;CAClC,MAAM,WACJ,cAAc,YAAY,gBAAgB,mDAA4B;CAExE,MAAM,4DAA2D,IAAI,KAAK,CAAC;CAC3E,MAAM,sCAAoB,QAAQ;CAClC,MAAM,4CAAyC,EAAE,CAAC;CAClD,MAAM,4CAA0B,cAAc;CAC9C,MAAM,6CAA2B,eAAe;CAChD,MAAM,sCAAoB,QAAQ;CAElC,MAAM,gBAAgB,QAAQ,KAAK,2DACL,IAAI,QAAQ,SAAS,CAClD;AAED,YAAW,UAAU;AACrB,kBAAiB,UAAU;AAC3B,kBAAiB,UAAU;AAC3B,mBAAkB,UAAU;AAC5B,YAAW,UAAU;AAErB,mCAAgB;EACd,MAAM,oBAAoB,iBAAiB;EAC3C,MAAM,oCAAoB,IAAI,KAAiC;EAE/D,MAAM,OAMD,EAAE;AAEP,OAAK,IAAI,IAAI,GAAG,IAAI,WAAW,QAAQ,QAAQ,KAAK;GAClD,MAAM,MAAM,WAAW,QAAQ;GAC/B,MAAM,YAAY,iBAAiB,QAAQ;GAC3C,MAAM,gBAAgB;IACpB,GAAG,kBAAkB;IACrB,GAAG,iBAAiB;IACpB,GAAG,IAAI;IACR;GAED,MAAM,iBAAiBC,oBAAM,cAAc,OAAO,GAC9C,cAAc,OAAO,UACpB,cAAc,WACd,OAAO,aAAa,cAAc,WAAW;AAElD,OAAI,CAAC,eACH;GAGF,MAAM,kBAAkB,GAAG,EAAE,GAAG;AAChC,QAAK,KAAK;IACR;IACA;IACA;IACA;IACA;IACD,CAAC;;EAGJ,MAAM,WAAW,IAAI,IAAI,KAAK,KAAK,MAAM,EAAE,gBAAgB,CAAC;AAE5D,OAAK,MAAM,CAAC,KAAK,WAAW,kBAC1B,KAAI,CAAC,SAAS,IAAI,IAAI,IAAI,OAAO,OAAO,SACtC,QAAO,OAAO,YAAY;AAI9B,OAAK,MAAM,OAAO,MAAM;GACtB,MAAM,EAAE,iBAAiB,KAAK,WAAW,eAAe,mBACtD;GAEF,MAAM,WAAW,kBAAkB,IAAI,gBAAgB;AACvD,OAAI,UAAU,OAAO,YAAY,SAAS,WAAW,gBAAgB;AAEnE,aAAS,OAAO,WAAW,IAAI;IAC/B,MAAM,EAAE,QAAQ,SAAS,GAAG,yBAAyB;AACrD,aAAS,OAAO,WAAW,qBAAqB;AAChD,sBAAkB,IAAI,iBAAiB,SAAS;AAChD;;AAGF,OAAI,UAAU,OAAO,SACnB,UAAS,OAAO,YAAY;GAG9B,MAAM,SAAS,WAAW,QAAQ,SAAS,WAAW,IAAI,UAAU;IAClE,GAAG;IACH,QAAQ;IACT,CAAC;AACF,qBAAkB,IAAI,iBAAiB;IACrC;IACA,QAAQ;IACT,CAAC;;AAGJ,mBAAiB,UAAU;GAC3B;AAEF,mCAAgB;AACd,eAAa;AACX,QAAK,MAAM,EAAE,YAAY,iBAAiB,QAAQ,QAAQ,CACxD,KAAI,OAAO,SACT,QAAO,YAAY;AAGvB,oBAAiB,0BAAU,IAAI,KAAK;;IAErC,EAAE,CAAC"}

package/dist/useHotkeys.d.cts

@@ -1,63 +0,0 @@
-import { UseHotkeyOptions } from "./useHotkey.cjs";
-import { HotkeyCallback, RegisterableHotkey } from "@tanstack/hotkeys";
-
-//#region src/useHotkeys.d.ts
-/**
- * A single hotkey definition for use with `useHotkeys`.
- */
-interface UseHotkeyDefinition {
-  /** The hotkey string (e.g., 'Mod+S', 'Escape') or RawHotkey object */
-  hotkey: RegisterableHotkey;
-  /** The function to call when the hotkey is pressed */
-  callback: HotkeyCallback;
-  /** Per-hotkey options (merged on top of commonOptions) */
-  options?: UseHotkeyOptions;
-}
-/**
- * Preact hook for registering multiple keyboard hotkeys at once.
- *
- * Uses the singleton HotkeyManager for efficient event handling.
- * Accepts a dynamic array of hotkey definitions, making it safe to use
- * with variable-length lists without violating the rules of hooks.
- *
- * Options are merged in this order:
- * HotkeysProvider defaults < commonOptions < per-definition options
- *
- * Callbacks and options are synced on every render to avoid stale closures.
- *
- * @param hotkeys - Array of hotkey definitions to register
- * @param commonOptions - Shared options applied to all hotkeys (overridden by per-definition options).
- *   Per-row `enabled: false` still registers that hotkey: `HotkeyManager` suppresses execution only (the row
- *   stays in the store and appears in TanStack Hotkeys devtools). Toggling `enabled` updates the existing handle
- *   via `setOptions` (no unregister/re-register churn).
- *
- * @example
- * ```tsx
- * function Editor() {
- *   useHotkeys([
- *     { hotkey: 'Mod+S', callback: () => save() },
- *     { hotkey: 'Mod+Z', callback: () => undo() },
- *     { hotkey: 'Escape', callback: () => close() },
- *   ])
- * }
- * ```
- *
- * @example
- * ```tsx
- * function MenuShortcuts({ items }) {
- *   // Dynamic hotkeys from data -- safe because it's a single hook call
- *   useHotkeys(
- *     items.map((item) => ({
- *       hotkey: item.shortcut,
- *       callback: item.action,
- *       options: { enabled: item.enabled },
- *     })),
- *     { preventDefault: true },
- *   )
- * }
- * ```
- */
-declare function useHotkeys(hotkeys: Array<UseHotkeyDefinition>, commonOptions?: UseHotkeyOptions): void;
-//#endregion
-export { UseHotkeyDefinition, useHotkeys };
-//# sourceMappingURL=useHotkeys.d.cts.map

package/dist/useHotkeys.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"useHotkeys.js","names":[],"sources":["../src/useHotkeys.ts"],"sourcesContent":["import { useEffect, useRef } from 'preact/hooks'\nimport {\n  detectPlatform,\n  getHotkeyManager,\n  normalizeRegisterableHotkey,\n} from '@tanstack/hotkeys'\nimport { useDefaultHotkeysOptions } from './HotkeysProvider'\nimport { isRef } from './utils'\nimport type { UseHotkeyOptions } from './useHotkey'\nimport type {\n  Hotkey,\n  HotkeyCallback,\n  HotkeyRegistrationHandle,\n  RegisterableHotkey,\n} from '@tanstack/hotkeys'\n\n/**\n * A single hotkey definition for use with `useHotkeys`.\n */\nexport interface UseHotkeyDefinition {\n  /** The hotkey string (e.g., 'Mod+S', 'Escape') or RawHotkey object */\n  hotkey: RegisterableHotkey\n  /** The function to call when the hotkey is pressed */\n  callback: HotkeyCallback\n  /** Per-hotkey options (merged on top of commonOptions) */\n  options?: UseHotkeyOptions\n}\n\n/**\n * Preact hook for registering multiple keyboard hotkeys at once.\n *\n * Uses the singleton HotkeyManager for efficient event handling.\n * Accepts a dynamic array of hotkey definitions, making it safe to use\n * with variable-length lists without violating the rules of hooks.\n *\n * Options are merged in this order:\n * HotkeysProvider defaults < commonOptions < per-definition options\n *\n * Callbacks and options are synced on every render to avoid stale closures.\n *\n * @param hotkeys - Array of hotkey definitions to register\n * @param commonOptions - Shared options applied to all hotkeys (overridden by per-definition options).\n *   Per-row `enabled: false` still registers that hotkey: `HotkeyManager` suppresses execution only (the row\n *   stays in the store and appears in TanStack Hotkeys devtools). Toggling `enabled` updates the existing handle\n *   via `setOptions` (no unregister/re-register churn).\n *\n * @example\n * ```tsx\n * function Editor() {\n *   useHotkeys([\n *     { hotkey: 'Mod+S', callback: () => save() },\n *     { hotkey: 'Mod+Z', callback: () => undo() },\n *     { hotkey: 'Escape', callback: () => close() },\n *   ])\n * }\n * ```\n *\n * @example\n * ```tsx\n * function MenuShortcuts({ items }) {\n *   // Dynamic hotkeys from data -- safe because it's a single hook call\n *   useHotkeys(\n *     items.map((item) => ({\n *       hotkey: item.shortcut,\n *       callback: item.action,\n *       options: { enabled: item.enabled },\n *     })),\n *     { preventDefault: true },\n *   )\n * }\n * ```\n */\nexport function useHotkeys(\n  hotkeys: Array<UseHotkeyDefinition>,\n  commonOptions: UseHotkeyOptions = {},\n): void {\n  type RegistrationRecord = {\n    handle: HotkeyRegistrationHandle\n    target: Document | HTMLElement | Window\n  }\n\n  const defaultOptions = useDefaultHotkeysOptions().hotkey\n  const manager = getHotkeyManager()\n  const platform =\n    commonOptions.platform ?? defaultOptions?.platform ?? detectPlatform()\n\n  const registrationsRef = useRef<Map<string, RegistrationRecord>>(new Map())\n  const hotkeysRef = useRef(hotkeys)\n  const hotkeyStringsRef = useRef<Array<Hotkey>>([])\n  const commonOptionsRef = useRef(commonOptions)\n  const defaultOptionsRef = useRef(defaultOptions)\n  const managerRef = useRef(manager)\n\n  const hotkeyStrings = hotkeys.map((def) =>\n    normalizeRegisterableHotkey(def.hotkey, platform),\n  )\n\n  hotkeysRef.current = hotkeys\n  hotkeyStringsRef.current = hotkeyStrings\n  commonOptionsRef.current = commonOptions\n  defaultOptionsRef.current = defaultOptions\n  managerRef.current = manager\n\n  useEffect(() => {\n    const prevRegistrations = registrationsRef.current\n    const nextRegistrations = new Map<string, RegistrationRecord>()\n\n    const rows: Array<{\n      registrationKey: string\n      def: (typeof hotkeysRef.current)[number]\n      hotkeyStr: Hotkey\n      mergedOptions: UseHotkeyOptions\n      resolvedTarget: Document | HTMLElement | Window\n    }> = []\n\n    for (let i = 0; i < hotkeysRef.current.length; i++) {\n      const def = hotkeysRef.current[i]!\n      const hotkeyStr = hotkeyStringsRef.current[i]!\n      const mergedOptions = {\n        ...defaultOptionsRef.current,\n        ...commonOptionsRef.current,\n        ...def.options,\n      } as UseHotkeyOptions\n\n      const resolvedTarget = isRef(mergedOptions.target)\n        ? mergedOptions.target.current\n        : (mergedOptions.target ??\n          (typeof document !== 'undefined' ? document : null))\n\n      if (!resolvedTarget) {\n        continue\n      }\n\n      const registrationKey = `${i}:${hotkeyStr}`\n      rows.push({\n        registrationKey,\n        def,\n        hotkeyStr,\n        mergedOptions,\n        resolvedTarget,\n      })\n    }\n\n    const nextKeys = new Set(rows.map((r) => r.registrationKey))\n\n    for (const [key, record] of prevRegistrations) {\n      if (!nextKeys.has(key) && record.handle.isActive) {\n        record.handle.unregister()\n      }\n    }\n\n    for (const row of rows) {\n      const { registrationKey, def, hotkeyStr, mergedOptions, resolvedTarget } =\n        row\n\n      const existing = prevRegistrations.get(registrationKey)\n      if (existing?.handle.isActive && existing.target === resolvedTarget) {\n        // Publish callback/options only after commit, never during render.\n        existing.handle.callback = def.callback\n        const { target: _target, ...optionsWithoutTarget } = mergedOptions\n        existing.handle.setOptions(optionsWithoutTarget)\n        nextRegistrations.set(registrationKey, existing)\n        continue\n      }\n\n      if (existing?.handle.isActive) {\n        existing.handle.unregister()\n      }\n\n      const handle = managerRef.current.register(hotkeyStr, def.callback, {\n        ...mergedOptions,\n        target: resolvedTarget,\n      })\n      nextRegistrations.set(registrationKey, {\n        handle,\n        target: resolvedTarget,\n      })\n    }\n\n    registrationsRef.current = nextRegistrations\n  })\n\n  useEffect(() => {\n    return () => {\n      for (const { handle } of registrationsRef.current.values()) {\n        if (handle.isActive) {\n          handle.unregister()\n        }\n      }\n      registrationsRef.current = new Map()\n    }\n  }, [])\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwEA,SAAgB,WACd,SACA,gBAAkC,EAAE,EAC9B;CAMN,MAAM,iBAAiB,0BAA0B,CAAC;CAClD,MAAM,UAAU,kBAAkB;CAClC,MAAM,WACJ,cAAc,YAAY,gBAAgB,YAAY,gBAAgB;CAExE,MAAM,mBAAmB,uBAAwC,IAAI,KAAK,CAAC;CAC3E,MAAM,aAAa,OAAO,QAAQ;CAClC,MAAM,mBAAmB,OAAsB,EAAE,CAAC;CAClD,MAAM,mBAAmB,OAAO,cAAc;CAC9C,MAAM,oBAAoB,OAAO,eAAe;CAChD,MAAM,aAAa,OAAO,QAAQ;CAElC,MAAM,gBAAgB,QAAQ,KAAK,QACjC,4BAA4B,IAAI,QAAQ,SAAS,CAClD;AAED,YAAW,UAAU;AACrB,kBAAiB,UAAU;AAC3B,kBAAiB,UAAU;AAC3B,mBAAkB,UAAU;AAC5B,YAAW,UAAU;AAErB,iBAAgB;EACd,MAAM,oBAAoB,iBAAiB;EAC3C,MAAM,oCAAoB,IAAI,KAAiC;EAE/D,MAAM,OAMD,EAAE;AAEP,OAAK,IAAI,IAAI,GAAG,IAAI,WAAW,QAAQ,QAAQ,KAAK;GAClD,MAAM,MAAM,WAAW,QAAQ;GAC/B,MAAM,YAAY,iBAAiB,QAAQ;GAC3C,MAAM,gBAAgB;IACpB,GAAG,kBAAkB;IACrB,GAAG,iBAAiB;IACpB,GAAG,IAAI;IACR;GAED,MAAM,iBAAiB,MAAM,cAAc,OAAO,GAC9C,cAAc,OAAO,UACpB,cAAc,WACd,OAAO,aAAa,cAAc,WAAW;AAElD,OAAI,CAAC,eACH;GAGF,MAAM,kBAAkB,GAAG,EAAE,GAAG;AAChC,QAAK,KAAK;IACR;IACA;IACA;IACA;IACA;IACD,CAAC;;EAGJ,MAAM,WAAW,IAAI,IAAI,KAAK,KAAK,MAAM,EAAE,gBAAgB,CAAC;AAE5D,OAAK,MAAM,CAAC,KAAK,WAAW,kBAC1B,KAAI,CAAC,SAAS,IAAI,IAAI,IAAI,OAAO,OAAO,SACtC,QAAO,OAAO,YAAY;AAI9B,OAAK,MAAM,OAAO,MAAM;GACtB,MAAM,EAAE,iBAAiB,KAAK,WAAW,eAAe,mBACtD;GAEF,MAAM,WAAW,kBAAkB,IAAI,gBAAgB;AACvD,OAAI,UAAU,OAAO,YAAY,SAAS,WAAW,gBAAgB;AAEnE,aAAS,OAAO,WAAW,IAAI;IAC/B,MAAM,EAAE,QAAQ,SAAS,GAAG,yBAAyB;AACrD,aAAS,OAAO,WAAW,qBAAqB;AAChD,sBAAkB,IAAI,iBAAiB,SAAS;AAChD;;AAGF,OAAI,UAAU,OAAO,SACnB,UAAS,OAAO,YAAY;GAG9B,MAAM,SAAS,WAAW,QAAQ,SAAS,WAAW,IAAI,UAAU;IAClE,GAAG;IACH,QAAQ;IACT,CAAC;AACF,qBAAkB,IAAI,iBAAiB;IACrC;IACA,QAAQ;IACT,CAAC;;AAGJ,mBAAiB,UAAU;GAC3B;AAEF,iBAAgB;AACd,eAAa;AACX,QAAK,MAAM,EAAE,YAAY,iBAAiB,QAAQ,QAAQ,CACxD,KAAI,OAAO,SACT,QAAO,YAAY;AAGvB,oBAAiB,0BAAU,IAAI,KAAK;;IAErC,EAAE,CAAC"}

package/dist/useKeyHold.cjs

@@ -1,53 +0,0 @@
-let _tanstack_hotkeys = require("@tanstack/hotkeys");
-let _tanstack_preact_store = require("@tanstack/preact-store");
-
-//#region src/useKeyHold.ts
-/**
-* Preact hook that returns whether a specific key is currently being held.
-*
-* This hook uses `useSelector` from `@tanstack/preact-store` to subscribe
-* to the global KeyStateTracker and uses a selector to determine if
-* the specified key is held.
-*
-* @param key - The key to check (e.g., 'Shift', 'Control', 'A')
-* @returns True if the key is currently held down
-*
-* @example
-* ```tsx
-* function ShiftIndicator() {
-*   const isShiftHeld = useKeyHold('Shift')
-*
-*   return (
-*     <div style={{ opacity: isShiftHeld ? 1 : 0.5 }}>
-*       {isShiftHeld ? 'Shift is pressed!' : 'Press Shift'}
-*     </div>
-*   )
-* }
-* ```
-*
-* @example
-* ```tsx
-* function ModifierIndicators() {
-*   const ctrl = useKeyHold('Control')
-*   const shift = useKeyHold('Shift')
-*   const alt = useKeyHold('Alt')
-*
-*   return (
-*     <div>
-*       <span style={{ opacity: ctrl ? 1 : 0.3 }}>Ctrl</span>
-*       <span style={{ opacity: shift ? 1 : 0.3 }}>Shift</span>
-*       <span style={{ opacity: alt ? 1 : 0.3 }}>Alt</span>
-*     </div>
-*   )
-* }
-* ```
-*/
-function useKeyHold(key) {
-	const tracker = (0, _tanstack_hotkeys.getKeyStateTracker)();
-	const normalizedKey = key.toLowerCase();
-	return (0, _tanstack_preact_store.useSelector)(tracker.store, (state) => state.heldKeys.some((heldKey) => heldKey.toLowerCase() === normalizedKey));
-}
-
-//#endregion
-exports.useKeyHold = useKeyHold;
-//# sourceMappingURL=useKeyHold.cjs.map

package/dist/useKeyHold.cjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"useKeyHold.cjs","names":[],"sources":["../src/useKeyHold.ts"],"sourcesContent":["import { useSelector } from '@tanstack/preact-store'\nimport { getKeyStateTracker } from '@tanstack/hotkeys'\nimport type { IndividualKey } from '@tanstack/hotkeys'\n\n/**\n * Preact hook that returns whether a specific key is currently being held.\n *\n * This hook uses `useSelector` from `@tanstack/preact-store` to subscribe\n * to the global KeyStateTracker and uses a selector to determine if\n * the specified key is held.\n *\n * @param key - The key to check (e.g., 'Shift', 'Control', 'A')\n * @returns True if the key is currently held down\n *\n * @example\n * ```tsx\n * function ShiftIndicator() {\n *   const isShiftHeld = useKeyHold('Shift')\n *\n *   return (\n *     <div style={{ opacity: isShiftHeld ? 1 : 0.5 }}>\n *       {isShiftHeld ? 'Shift is pressed!' : 'Press Shift'}\n *     </div>\n *   )\n * }\n * ```\n *\n * @example\n * ```tsx\n * function ModifierIndicators() {\n *   const ctrl = useKeyHold('Control')\n *   const shift = useKeyHold('Shift')\n *   const alt = useKeyHold('Alt')\n *\n *   return (\n *     <div>\n *       <span style={{ opacity: ctrl ? 1 : 0.3 }}>Ctrl</span>\n *       <span style={{ opacity: shift ? 1 : 0.3 }}>Shift</span>\n *       <span style={{ opacity: alt ? 1 : 0.3 }}>Alt</span>\n *     </div>\n *   )\n * }\n * ```\n */\nexport function useKeyHold(key: IndividualKey): boolean {\n  const tracker = getKeyStateTracker()\n  const normalizedKey = key.toLowerCase()\n\n  return useSelector(tracker.store, (state) =>\n    state.heldKeys.some((heldKey) => heldKey.toLowerCase() === normalizedKey),\n  )\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4CA,SAAgB,WAAW,KAA6B;CACtD,MAAM,qDAA8B;CACpC,MAAM,gBAAgB,IAAI,aAAa;AAEvC,gDAAmB,QAAQ,QAAQ,UACjC,MAAM,SAAS,MAAM,YAAY,QAAQ,aAAa,KAAK,cAAc,CAC1E"}

package/dist/useKeyHold.d.cts

@@ -1,47 +0,0 @@
-import { IndividualKey } from "@tanstack/hotkeys";
-
-//#region src/useKeyHold.d.ts
-/**
- * Preact hook that returns whether a specific key is currently being held.
- *
- * This hook uses `useSelector` from `@tanstack/preact-store` to subscribe
- * to the global KeyStateTracker and uses a selector to determine if
- * the specified key is held.
- *
- * @param key - The key to check (e.g., 'Shift', 'Control', 'A')
- * @returns True if the key is currently held down
- *
- * @example
- * ```tsx
- * function ShiftIndicator() {
- *   const isShiftHeld = useKeyHold('Shift')
- *
- *   return (
- *     <div style={{ opacity: isShiftHeld ? 1 : 0.5 }}>
- *       {isShiftHeld ? 'Shift is pressed!' : 'Press Shift'}
- *     </div>
- *   )
- * }
- * ```
- *
- * @example
- * ```tsx
- * function ModifierIndicators() {
- *   const ctrl = useKeyHold('Control')
- *   const shift = useKeyHold('Shift')
- *   const alt = useKeyHold('Alt')
- *
- *   return (
- *     <div>
- *       <span style={{ opacity: ctrl ? 1 : 0.3 }}>Ctrl</span>
- *       <span style={{ opacity: shift ? 1 : 0.3 }}>Shift</span>
- *       <span style={{ opacity: alt ? 1 : 0.3 }}>Alt</span>
- *     </div>
- *   )
- * }
- * ```
- */
-declare function useKeyHold(key: IndividualKey): boolean;
-//#endregion
-export { useKeyHold };
-//# sourceMappingURL=useKeyHold.d.cts.map

package/dist/useKeyHold.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"useKeyHold.js","names":[],"sources":["../src/useKeyHold.ts"],"sourcesContent":["import { useSelector } from '@tanstack/preact-store'\nimport { getKeyStateTracker } from '@tanstack/hotkeys'\nimport type { IndividualKey } from '@tanstack/hotkeys'\n\n/**\n * Preact hook that returns whether a specific key is currently being held.\n *\n * This hook uses `useSelector` from `@tanstack/preact-store` to subscribe\n * to the global KeyStateTracker and uses a selector to determine if\n * the specified key is held.\n *\n * @param key - The key to check (e.g., 'Shift', 'Control', 'A')\n * @returns True if the key is currently held down\n *\n * @example\n * ```tsx\n * function ShiftIndicator() {\n *   const isShiftHeld = useKeyHold('Shift')\n *\n *   return (\n *     <div style={{ opacity: isShiftHeld ? 1 : 0.5 }}>\n *       {isShiftHeld ? 'Shift is pressed!' : 'Press Shift'}\n *     </div>\n *   )\n * }\n * ```\n *\n * @example\n * ```tsx\n * function ModifierIndicators() {\n *   const ctrl = useKeyHold('Control')\n *   const shift = useKeyHold('Shift')\n *   const alt = useKeyHold('Alt')\n *\n *   return (\n *     <div>\n *       <span style={{ opacity: ctrl ? 1 : 0.3 }}>Ctrl</span>\n *       <span style={{ opacity: shift ? 1 : 0.3 }}>Shift</span>\n *       <span style={{ opacity: alt ? 1 : 0.3 }}>Alt</span>\n *     </div>\n *   )\n * }\n * ```\n */\nexport function useKeyHold(key: IndividualKey): boolean {\n  const tracker = getKeyStateTracker()\n  const normalizedKey = key.toLowerCase()\n\n  return useSelector(tracker.store, (state) =>\n    state.heldKeys.some((heldKey) => heldKey.toLowerCase() === normalizedKey),\n  )\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4CA,SAAgB,WAAW,KAA6B;CACtD,MAAM,UAAU,oBAAoB;CACpC,MAAM,gBAAgB,IAAI,aAAa;AAEvC,QAAO,YAAY,QAAQ,QAAQ,UACjC,MAAM,SAAS,MAAM,YAAY,QAAQ,aAAa,KAAK,cAAc,CAC1E"}

package/dist/utils.cjs

@@ -1,12 +0,0 @@
-
-//#region src/utils.ts
-/**
-* Type guard to check if a value is a Preact ref-like object.
-*/
-function isRef(value) {
-	return value !== null && typeof value === "object" && "current" in value;
-}
-
-//#endregion
-exports.isRef = isRef;
-//# sourceMappingURL=utils.cjs.map

package/dist/utils.cjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"utils.cjs","names":[],"sources":["../src/utils.ts"],"sourcesContent":["import type { RefObject } from 'preact'\n\n/**\n * Type guard to check if a value is a Preact ref-like object.\n */\nexport function isRef(value: unknown): value is RefObject<HTMLElement | null> {\n  return value !== null && typeof value === 'object' && 'current' in value\n}\n"],"mappings":";;;;;AAKA,SAAgB,MAAM,OAAwD;AAC5E,QAAO,UAAU,QAAQ,OAAO,UAAU,YAAY,aAAa"}

package/dist/utils.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"utils.js","names":[],"sources":["../src/utils.ts"],"sourcesContent":["import type { RefObject } from 'preact'\n\n/**\n * Type guard to check if a value is a Preact ref-like object.\n */\nexport function isRef(value: unknown): value is RefObject<HTMLElement | null> {\n  return value !== null && typeof value === 'object' && 'current' in value\n}\n"],"mappings":";;;;AAKA,SAAgB,MAAM,OAAwD;AAC5E,QAAO,UAAU,QAAQ,OAAO,UAAU,YAAY,aAAa"}

package/src/HotkeysProvider.tsx

@@ -1,56 +0,0 @@
-import { createContext } from 'preact'
-import { useContext, useMemo } from 'preact/hooks'
-import type { ComponentChildren } from 'preact'
-import type {
-  HotkeyRecorderOptions,
-  HotkeySequenceRecorderOptions,
-} from '@tanstack/hotkeys'
-import type { UseHotkeyOptions } from './useHotkey'
-import type { UseHotkeySequenceOptions } from './useHotkeySequence'
-
-export interface HotkeysProviderOptions {
-  hotkey?: Partial<UseHotkeyOptions>
-  hotkeyRecorder?: Partial<HotkeyRecorderOptions>
-  hotkeySequenceRecorder?: Partial<HotkeySequenceRecorderOptions>
-  hotkeySequence?: Partial<UseHotkeySequenceOptions>
-}
-
-interface HotkeysContextValue {
-  defaultOptions: HotkeysProviderOptions
-}
-
-const HotkeysContext = createContext<HotkeysContextValue | null>(null)
-
-export interface HotkeysProviderProps {
-  children: ComponentChildren
-  defaultOptions?: HotkeysProviderOptions
-}
-
-const DEFAULT_OPTIONS: HotkeysProviderOptions = {}
-
-export function HotkeysProvider({
-  children,
-  defaultOptions = DEFAULT_OPTIONS,
-}: HotkeysProviderProps) {
-  const contextValue: HotkeysContextValue = useMemo(
-    () => ({
-      defaultOptions,
-    }),
-    [defaultOptions],
-  )
-
-  return (
-    <HotkeysContext.Provider value={contextValue}>
-      {children}
-    </HotkeysContext.Provider>
-  )
-}
-
-export function useHotkeysContext() {
-  return useContext(HotkeysContext)
-}
-
-export function useDefaultHotkeysOptions() {
-  const context = useContext(HotkeysContext)
-  return context?.defaultOptions ?? {}
-}

package/src/index.ts

@@ -1,18 +0,0 @@
-// Re-export everything from the core package
-export * from '@tanstack/hotkeys'
-
-// provider
-export * from './HotkeysProvider'
-
-// Preact-specific exports
-export * from './useHotkey'
-export * from './useHotkeys'
-export * from './useHeldKeys'
-export * from './useHeldKeyCodes'
-export * from './useKeyHold'
-export * from './useHotkeySequence'
-export * from './useHotkeySequences'
-export * from './useHotkeyRecorder'
-export * from './useHotkeyRegistrations'
-export * from './useHotkeySequenceRecorder'
-export * from './useHotkeyHint'

package/src/useHeldKeyCodes.ts

@@ -1,33 +0,0 @@
-import { useSelector } from '@tanstack/preact-store'
-import { getKeyStateTracker } from '@tanstack/hotkeys'
-
-/**
- * Preact hook that returns a map of currently held key names to their physical `event.code` values.
- *
- * This is useful for debugging which physical key was pressed (e.g. distinguishing
- * left vs right Shift via "ShiftLeft" / "ShiftRight").
- *
- * @returns Record mapping normalized key names to their `event.code` values
- *
- * @example
- * ```tsx
- * function KeyDebugDisplay() {
- *   const heldKeys = useHeldKeys()
- *   const heldCodes = useHeldKeyCodes()
- *
- *   return (
- *     <div>
- *       {heldKeys.map((key) => (
- *         <kbd key={key}>
- *           {key} <small>{heldCodes[key]}</small>
- *         </kbd>
- *       ))}
- *     </div>
- *   )
- * }
- * ```
- */
-export function useHeldKeyCodes(): Record<string, string> {
-  const tracker = getKeyStateTracker()
-  return useSelector(tracker.store, (state) => state.heldCodes)
-}

package/src/useHeldKeys.ts

@@ -1,29 +0,0 @@
-import { useSelector } from '@tanstack/preact-store'
-import { getKeyStateTracker } from '@tanstack/hotkeys'
-
-/**
- * Preact hook that returns an array of currently held keyboard keys.
- *
- * This hook uses `useSelector` from `@tanstack/preact-store` to subscribe
- * to the global KeyStateTracker and updates whenever keys are pressed
- * or released.
- *
- * @returns Array of currently held key names
- *
- * @example
- * ```tsx
- * function KeyDisplay() {
- *   const heldKeys = useHeldKeys()
- *
- *   return (
- *     <div>
- *       Currently pressed: {heldKeys.join(' + ') || 'None'}
- *     </div>
- *   )
- * }
- * ```
- */
-export function useHeldKeys(): Array<string> {
-  const tracker = getKeyStateTracker()
-  return useSelector(tracker.store, (state) => state.heldKeys)
-}

package/src/useHotkey.ts

@@ -1,191 +0,0 @@
-import { useEffect, useRef } from 'preact/hooks'
-import {
-  detectPlatform,
-  getHotkeyManager,
-  normalizeRegisterableHotkey,
-} from '@tanstack/hotkeys'
-import { useDefaultHotkeysOptions } from './HotkeysProvider'
-import { isRef } from './utils'
-import type { RefObject } from 'preact'
-import type {
-  HotkeyCallback,
-  HotkeyOptions,
-  HotkeyRegistrationHandle,
-  RegisterableHotkey,
-} from '@tanstack/hotkeys'
-
-export interface UseHotkeyOptions extends Omit<HotkeyOptions, 'target'> {
-  /**
-   * The DOM element to attach the event listener to.
-   * Can be a Preact ref, direct DOM element, or null.
-   * Defaults to document.
-   */
-  target?:
-    | RefObject<HTMLElement | null>
-    | HTMLElement
-    | Document
-    | Window
-    | null
-}
-
-/**
- * Preact hook for registering a keyboard hotkey.
- *
- * Uses the singleton HotkeyManager for efficient event handling.
- * The callback receives both the keyboard event and a context object
- * containing the hotkey string and parsed hotkey.
- *
- * This hook syncs the callback and options on every render to avoid
- * stale closures. This means
- * callbacks that reference Preact state will always have access to
- * the latest values.
- *
- * @param hotkey - The hotkey string (e.g., 'Mod+S', 'Escape') or RawHotkey object (supports `mod` for cross-platform)
- * @param callback - The function to call when the hotkey is pressed
- * @param options - Options for the hotkey behavior. `enabled: false` keeps the registration (visible in devtools)
- *   and only suppresses firing; the hook updates the existing handle instead of unregistering.
- *
- * @example
- * ```tsx
- * function SaveButton() {
- *   const [count, setCount] = useState(0)
- *
- *   // Callback always has access to latest count value
- *   useHotkey('Mod+S', (event, { hotkey }) => {
- *     console.log(`Save triggered, count is ${count}`)
- *     handleSave()
- *   })
- *
- *   return <button onClick={() => setCount(c => c + 1)}>Count: {count}</button>
- * }
- * ```
- *
- * @example
- * ```tsx
- * function Modal({ isOpen, onClose }) {
- *   // enabled option is synced on every render
- *   useHotkey('Escape', () => {
- *     onClose()
- *   }, { enabled: isOpen })
- *
- *   if (!isOpen) return null
- *   return <div className="modal">...</div>
- * }
- * ```
- *
- * @example
- * ```tsx
- * function Editor() {
- *   const editorRef = useRef<HTMLDivElement>(null)
- *
- *   // Scoped to a specific element
- *   useHotkey('Mod+S', () => {
- *     save()
- *   }, { target: editorRef })
- *
- *   return <div ref={editorRef}>...</div>
- * }
- * ```
- */
-export function useHotkey(
-  hotkey: RegisterableHotkey,
-  callback: HotkeyCallback,
-  options: UseHotkeyOptions = {},
-): void {
-  const mergedOptions = {
-    ...useDefaultHotkeysOptions().hotkey,
-    ...options,
-  } as UseHotkeyOptions
-
-  const manager = getHotkeyManager()
-
-  // Stable ref for registration handle
-  const registrationRef = useRef<HotkeyRegistrationHandle | null>(null)
-
-  // Refs to capture current values for use in effect without adding dependencies
-  const callbackRef = useRef(callback)
-  const optionsRef = useRef(mergedOptions)
-  const managerRef = useRef(manager)
-
-  // Update refs on every render
-  callbackRef.current = callback
-  optionsRef.current = mergedOptions
-  managerRef.current = manager
-
-  // Track previous target and hotkey to detect changes requiring re-registration
-  const prevTargetRef = useRef<HTMLElement | Document | Window | null>(null)
-  const prevHotkeyRef = useRef<string | null>(null)
-
-  // Normalize to hotkey string
-  const platform = mergedOptions.platform ?? detectPlatform()
-  const hotkeyString = normalizeRegisterableHotkey(hotkey, platform)
-
-  // Extract options without target (target is handled separately)
-  const { target: _target, ...optionsWithoutTarget } = mergedOptions
-
-  useEffect(() => {
-    // Resolve target inside the effect so refs are already attached after mount
-    const resolvedTarget = isRef(optionsRef.current.target)
-      ? optionsRef.current.target.current
-      : (optionsRef.current.target ??
-        (typeof document !== 'undefined' ? document : null))
-
-    // Skip if no valid target (SSR or ref still null)
-    if (!resolvedTarget) {
-      if (registrationRef.current?.isActive) {
-        registrationRef.current.unregister()
-        registrationRef.current = null
-      }
-      prevTargetRef.current = null
-      prevHotkeyRef.current = null
-      return
-    }
-
-    // Check if we need to re-register (target or hotkey changed)
-    const targetChanged =
-      prevTargetRef.current !== null && prevTargetRef.current !== resolvedTarget
-    const hotkeyChanged =
-      prevHotkeyRef.current !== null && prevHotkeyRef.current !== hotkeyString
-
-    // If we have an active registration and target/hotkey changed, unregister first
-    if (registrationRef.current?.isActive && (targetChanged || hotkeyChanged)) {
-      registrationRef.current.unregister()
-      registrationRef.current = null
-    }
-
-    // Register if needed (no active registration)
-    // Use refs to access current values without adding them to dependencies
-    if (!registrationRef.current || !registrationRef.current.isActive) {
-      registrationRef.current = managerRef.current.register(
-        hotkeyString,
-        callbackRef.current,
-        {
-          ...optionsRef.current,
-          target: resolvedTarget,
-        },
-      )
-    }
-
-    // Update tracking refs
-    prevTargetRef.current = resolvedTarget
-    prevHotkeyRef.current = hotkeyString
-  })
-
-  useEffect(() => {
-    // Cleanup on unmount
-    return () => {
-      if (registrationRef.current?.isActive) {
-        registrationRef.current.unregister()
-        registrationRef.current = null
-      }
-    }
-  }, [])
-
-  // Publish option changes after commit, never during render.
-  useEffect(() => {
-    if (registrationRef.current?.isActive) {
-      registrationRef.current.callback = callback
-      registrationRef.current.setOptions(optionsWithoutTarget)
-    }
-  })
-}

package/src/useHotkeyHint.ts

@@ -1,19 +0,0 @@
-import { useSelector } from '@tanstack/preact-store'
-import { getKeyStateTracker, matchesHeldModifiers } from '@tanstack/hotkeys'
-import type { HeldModifierOptions, RegisterableHotkey } from '@tanstack/hotkeys'
-
-/**
- * Returns a boolean indicating whether held modifiers reveal this shortcut.
- * Only visibility changes from held-key updates cause a rerender.
- * Uses the nonempty-subset/AltGr rules of `matchesHeldModifiers`; `exact` requires
- * every modifier. Combine with the action's enabled state before showing a badge.
- * This helper does not register a shortcut or check whether its target is focused.
- */
-export function useHotkeyHint(
-  hotkey: RegisterableHotkey,
-  options: HeldModifierOptions = {},
-): boolean {
-  return useSelector(getKeyStateTracker().store, (state) =>
-    matchesHeldModifiers(hotkey, state.heldKeys, options),
-  )
-}