@tanstack/preact-hotkeys 0.5.0 → 0.5.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/useHotkeySequence.cjs +10 -0
- package/dist/useHotkeySequence.cjs.map +1 -1
- package/dist/useHotkeySequence.d.cts +10 -0
- package/dist/useHotkeySequence.d.ts +10 -0
- package/dist/useHotkeySequence.js +10 -0
- package/dist/useHotkeySequence.js.map +1 -1
- package/package.json +2 -2
- package/src/useHotkeySequence.ts +10 -0
|
@@ -10,6 +10,11 @@ let preact_hooks = require("preact/hooks");
|
|
|
10
10
|
* This hook allows you to register multi-key sequences like 'g g' or 'd d'
|
|
11
11
|
* that trigger when the full sequence is pressed within a timeout.
|
|
12
12
|
*
|
|
13
|
+
* Each step may include modifiers. You can chain the same modifier across
|
|
14
|
+
* steps (e.g. `Shift+R` then `Shift+T`). Modifier-only keydown events (Shift,
|
|
15
|
+
* Control, Alt, or Meta pressed alone) are ignored while matching—they do not
|
|
16
|
+
* advance the sequence or reset progress.
|
|
17
|
+
*
|
|
13
18
|
* @param sequence - Array of hotkey strings that form the sequence
|
|
14
19
|
* @param callback - Function to call when the sequence is completed
|
|
15
20
|
* @param options - Options for the sequence behavior
|
|
@@ -32,6 +37,11 @@ let preact_hooks = require("preact/hooks");
|
|
|
32
37
|
* deleteInnerWord()
|
|
33
38
|
* }, { timeout: 500 })
|
|
34
39
|
*
|
|
40
|
+
* // Same modifier on consecutive steps (bare Shift between chords is ignored)
|
|
41
|
+
* useHotkeySequence(['Shift+R', 'Shift+T'], () => {
|
|
42
|
+
* nextAction()
|
|
43
|
+
* })
|
|
44
|
+
*
|
|
35
45
|
* return <div>...</div>
|
|
36
46
|
* }
|
|
37
47
|
* ```
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"useHotkeySequence.cjs","names":["useDefaultHotkeysOptions","isRef"],"sources":["../src/useHotkeySequence.ts"],"sourcesContent":["import { useEffect, useRef } from 'preact/hooks'\nimport { formatHotkeySequence, getSequenceManager } from '@tanstack/hotkeys'\nimport { useDefaultHotkeysOptions } from './HotkeysProvider'\nimport { isRef } from './utils'\nimport type { RefObject } from 'preact'\nimport type {\n HotkeyCallback,\n HotkeyCallbackContext,\n HotkeySequence,\n SequenceOptions,\n SequenceRegistrationHandle,\n} from '@tanstack/hotkeys'\n\nexport interface UseHotkeySequenceOptions extends Omit<\n SequenceOptions,\n 'target'\n> {\n /**\n * The DOM element to attach the event listener to.\n * Can be a Preact ref, direct DOM element, or null.\n * Defaults to document.\n */\n target?:\n | RefObject<HTMLElement | null>\n | HTMLElement\n | Document\n | Window\n | null\n}\n\n/**\n * Preact hook for registering a keyboard shortcut sequence (Vim-style).\n *\n * This hook allows you to register multi-key sequences like 'g g' or 'd d'\n * that trigger when the full sequence is pressed within a timeout.\n *\n * @param sequence - Array of hotkey strings that form the sequence\n * @param callback - Function to call when the sequence is completed\n * @param options - Options for the sequence behavior\n *\n * @example\n * ```tsx\n * function VimEditor() {\n * // 'g g' to go to top\n * useHotkeySequence(['G', 'G'], () => {\n * scrollToTop()\n * })\n *\n * // 'd d' to delete line\n * useHotkeySequence(['D', 'D'], () => {\n * deleteLine()\n * })\n *\n * // 'd i w' to delete inner word\n * useHotkeySequence(['D', 'I', 'W'], () => {\n * deleteInnerWord()\n * }, { timeout: 500 })\n *\n * return <div>...</div>\n * }\n * ```\n */\nexport function useHotkeySequence(\n sequence: HotkeySequence,\n callback: HotkeyCallback,\n options: UseHotkeySequenceOptions = {},\n): void {\n const mergedOptions = {\n ...useDefaultHotkeysOptions().hotkeySequence,\n ...options,\n } as UseHotkeySequenceOptions\n\n const manager = getSequenceManager()\n\n // Stable ref for registration handle\n const registrationRef = useRef<SequenceRegistrationHandle | null>(null)\n\n // Refs to capture current values for use in effect without adding dependencies\n const callbackRef = useRef(callback)\n const optionsRef = useRef(mergedOptions)\n const managerRef = useRef(manager)\n\n // Update refs on every render\n callbackRef.current = callback\n optionsRef.current = mergedOptions\n managerRef.current = manager\n\n // Track previous target and sequence to detect changes requiring re-registration\n const prevTargetRef = useRef<HTMLElement | Document | Window | null>(null)\n const prevSequenceRef = useRef<string | null>(null)\n\n // Normalize to hotkey sequence string (join with spaces)\n const hotkeySequenceString = formatHotkeySequence(sequence)\n\n // Extract options without target (target is handled separately)\n const { target: _target, ...optionsWithoutTarget } = mergedOptions\n\n useEffect(() => {\n if (sequence.length === 0) {\n return\n }\n\n // Resolve target inside the effect so refs are already attached after mount\n const resolvedTarget = isRef(optionsRef.current.target)\n ? optionsRef.current.target.current\n : (optionsRef.current.target ??\n (typeof document !== 'undefined' ? document : null))\n\n // Skip if no valid target (SSR or ref still null)\n if (!resolvedTarget) {\n return\n }\n\n // Check if we need to re-register (target or sequence changed)\n const targetChanged =\n prevTargetRef.current !== null && prevTargetRef.current !== resolvedTarget\n const sequenceChanged =\n prevSequenceRef.current !== null &&\n prevSequenceRef.current !== hotkeySequenceString\n\n // If we have an active registration and target/sequence changed, unregister first\n if (\n registrationRef.current?.isActive &&\n (targetChanged || sequenceChanged)\n ) {\n registrationRef.current.unregister()\n registrationRef.current = null\n }\n\n // Register if needed (no active registration)\n if (!registrationRef.current || !registrationRef.current.isActive) {\n registrationRef.current = managerRef.current.register(\n sequence,\n (event, context) => callbackRef.current(event, context),\n {\n ...optionsRef.current,\n target: resolvedTarget,\n },\n )\n }\n\n // Update tracking refs\n prevTargetRef.current = resolvedTarget\n prevSequenceRef.current = hotkeySequenceString\n\n // Cleanup on unmount\n return () => {\n if (registrationRef.current?.isActive) {\n registrationRef.current.unregister()\n registrationRef.current = null\n }\n }\n }, [hotkeySequenceString, mergedOptions.enabled, sequence])\n\n // Sync callback and options on EVERY render (outside useEffect)\n if (registrationRef.current?.isActive) {\n registrationRef.current.callback = (\n event: KeyboardEvent,\n context: HotkeyCallbackContext,\n ) => callbackRef.current(event, context)\n registrationRef.current.setOptions(optionsWithoutTarget)\n }\n}\n"],"mappings":"
|
|
1
|
+
{"version":3,"file":"useHotkeySequence.cjs","names":["useDefaultHotkeysOptions","isRef"],"sources":["../src/useHotkeySequence.ts"],"sourcesContent":["import { useEffect, useRef } from 'preact/hooks'\nimport { formatHotkeySequence, getSequenceManager } from '@tanstack/hotkeys'\nimport { useDefaultHotkeysOptions } from './HotkeysProvider'\nimport { isRef } from './utils'\nimport type { RefObject } from 'preact'\nimport type {\n HotkeyCallback,\n HotkeyCallbackContext,\n HotkeySequence,\n SequenceOptions,\n SequenceRegistrationHandle,\n} from '@tanstack/hotkeys'\n\nexport interface UseHotkeySequenceOptions extends Omit<\n SequenceOptions,\n 'target'\n> {\n /**\n * The DOM element to attach the event listener to.\n * Can be a Preact ref, direct DOM element, or null.\n * Defaults to document.\n */\n target?:\n | RefObject<HTMLElement | null>\n | HTMLElement\n | Document\n | Window\n | null\n}\n\n/**\n * Preact hook for registering a keyboard shortcut sequence (Vim-style).\n *\n * This hook allows you to register multi-key sequences like 'g g' or 'd d'\n * that trigger when the full sequence is pressed within a timeout.\n *\n * Each step may include modifiers. You can chain the same modifier across\n * steps (e.g. `Shift+R` then `Shift+T`). Modifier-only keydown events (Shift,\n * Control, Alt, or Meta pressed alone) are ignored while matching—they do not\n * advance the sequence or reset progress.\n *\n * @param sequence - Array of hotkey strings that form the sequence\n * @param callback - Function to call when the sequence is completed\n * @param options - Options for the sequence behavior\n *\n * @example\n * ```tsx\n * function VimEditor() {\n * // 'g g' to go to top\n * useHotkeySequence(['G', 'G'], () => {\n * scrollToTop()\n * })\n *\n * // 'd d' to delete line\n * useHotkeySequence(['D', 'D'], () => {\n * deleteLine()\n * })\n *\n * // 'd i w' to delete inner word\n * useHotkeySequence(['D', 'I', 'W'], () => {\n * deleteInnerWord()\n * }, { timeout: 500 })\n *\n * // Same modifier on consecutive steps (bare Shift between chords is ignored)\n * useHotkeySequence(['Shift+R', 'Shift+T'], () => {\n * nextAction()\n * })\n *\n * return <div>...</div>\n * }\n * ```\n */\nexport function useHotkeySequence(\n sequence: HotkeySequence,\n callback: HotkeyCallback,\n options: UseHotkeySequenceOptions = {},\n): void {\n const mergedOptions = {\n ...useDefaultHotkeysOptions().hotkeySequence,\n ...options,\n } as UseHotkeySequenceOptions\n\n const manager = getSequenceManager()\n\n // Stable ref for registration handle\n const registrationRef = useRef<SequenceRegistrationHandle | null>(null)\n\n // Refs to capture current values for use in effect without adding dependencies\n const callbackRef = useRef(callback)\n const optionsRef = useRef(mergedOptions)\n const managerRef = useRef(manager)\n\n // Update refs on every render\n callbackRef.current = callback\n optionsRef.current = mergedOptions\n managerRef.current = manager\n\n // Track previous target and sequence to detect changes requiring re-registration\n const prevTargetRef = useRef<HTMLElement | Document | Window | null>(null)\n const prevSequenceRef = useRef<string | null>(null)\n\n // Normalize to hotkey sequence string (join with spaces)\n const hotkeySequenceString = formatHotkeySequence(sequence)\n\n // Extract options without target (target is handled separately)\n const { target: _target, ...optionsWithoutTarget } = mergedOptions\n\n useEffect(() => {\n if (sequence.length === 0) {\n return\n }\n\n // Resolve target inside the effect so refs are already attached after mount\n const resolvedTarget = isRef(optionsRef.current.target)\n ? optionsRef.current.target.current\n : (optionsRef.current.target ??\n (typeof document !== 'undefined' ? document : null))\n\n // Skip if no valid target (SSR or ref still null)\n if (!resolvedTarget) {\n return\n }\n\n // Check if we need to re-register (target or sequence changed)\n const targetChanged =\n prevTargetRef.current !== null && prevTargetRef.current !== resolvedTarget\n const sequenceChanged =\n prevSequenceRef.current !== null &&\n prevSequenceRef.current !== hotkeySequenceString\n\n // If we have an active registration and target/sequence changed, unregister first\n if (\n registrationRef.current?.isActive &&\n (targetChanged || sequenceChanged)\n ) {\n registrationRef.current.unregister()\n registrationRef.current = null\n }\n\n // Register if needed (no active registration)\n if (!registrationRef.current || !registrationRef.current.isActive) {\n registrationRef.current = managerRef.current.register(\n sequence,\n (event, context) => callbackRef.current(event, context),\n {\n ...optionsRef.current,\n target: resolvedTarget,\n },\n )\n }\n\n // Update tracking refs\n prevTargetRef.current = resolvedTarget\n prevSequenceRef.current = hotkeySequenceString\n\n // Cleanup on unmount\n return () => {\n if (registrationRef.current?.isActive) {\n registrationRef.current.unregister()\n registrationRef.current = null\n }\n }\n }, [hotkeySequenceString, mergedOptions.enabled, sequence])\n\n // Sync callback and options on EVERY render (outside useEffect)\n if (registrationRef.current?.isActive) {\n registrationRef.current.callback = (\n event: KeyboardEvent,\n context: HotkeyCallbackContext,\n ) => callbackRef.current(event, context)\n registrationRef.current.setOptions(optionsWithoutTarget)\n }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwEA,SAAgB,kBACd,UACA,UACA,UAAoC,EAAE,EAChC;CACN,MAAM,gBAAgB;EACpB,GAAGA,kDAA0B,CAAC;EAC9B,GAAG;EACJ;CAED,MAAM,qDAA8B;CAGpC,MAAM,2CAA4D,KAAK;CAGvE,MAAM,uCAAqB,SAAS;CACpC,MAAM,sCAAoB,cAAc;CACxC,MAAM,sCAAoB,QAAQ;AAGlC,aAAY,UAAU;AACtB,YAAW,UAAU;AACrB,YAAW,UAAU;CAGrB,MAAM,yCAA+D,KAAK;CAC1E,MAAM,2CAAwC,KAAK;CAGnD,MAAM,mEAA4C,SAAS;CAG3D,MAAM,EAAE,QAAQ,SAAS,GAAG,yBAAyB;AAErD,mCAAgB;AACd,MAAI,SAAS,WAAW,EACtB;EAIF,MAAM,iBAAiBC,oBAAM,WAAW,QAAQ,OAAO,GACnD,WAAW,QAAQ,OAAO,UACzB,WAAW,QAAQ,WACnB,OAAO,aAAa,cAAc,WAAW;AAGlD,MAAI,CAAC,eACH;EAIF,MAAM,gBACJ,cAAc,YAAY,QAAQ,cAAc,YAAY;EAC9D,MAAM,kBACJ,gBAAgB,YAAY,QAC5B,gBAAgB,YAAY;AAG9B,MACE,gBAAgB,SAAS,aACxB,iBAAiB,kBAClB;AACA,mBAAgB,QAAQ,YAAY;AACpC,mBAAgB,UAAU;;AAI5B,MAAI,CAAC,gBAAgB,WAAW,CAAC,gBAAgB,QAAQ,SACvD,iBAAgB,UAAU,WAAW,QAAQ,SAC3C,WACC,OAAO,YAAY,YAAY,QAAQ,OAAO,QAAQ,EACvD;GACE,GAAG,WAAW;GACd,QAAQ;GACT,CACF;AAIH,gBAAc,UAAU;AACxB,kBAAgB,UAAU;AAG1B,eAAa;AACX,OAAI,gBAAgB,SAAS,UAAU;AACrC,oBAAgB,QAAQ,YAAY;AACpC,oBAAgB,UAAU;;;IAG7B;EAAC;EAAsB,cAAc;EAAS;EAAS,CAAC;AAG3D,KAAI,gBAAgB,SAAS,UAAU;AACrC,kBAAgB,QAAQ,YACtB,OACA,YACG,YAAY,QAAQ,OAAO,QAAQ;AACxC,kBAAgB,QAAQ,WAAW,qBAAqB"}
|
|
@@ -16,6 +16,11 @@ interface UseHotkeySequenceOptions extends Omit<SequenceOptions, 'target'> {
|
|
|
16
16
|
* This hook allows you to register multi-key sequences like 'g g' or 'd d'
|
|
17
17
|
* that trigger when the full sequence is pressed within a timeout.
|
|
18
18
|
*
|
|
19
|
+
* Each step may include modifiers. You can chain the same modifier across
|
|
20
|
+
* steps (e.g. `Shift+R` then `Shift+T`). Modifier-only keydown events (Shift,
|
|
21
|
+
* Control, Alt, or Meta pressed alone) are ignored while matching—they do not
|
|
22
|
+
* advance the sequence or reset progress.
|
|
23
|
+
*
|
|
19
24
|
* @param sequence - Array of hotkey strings that form the sequence
|
|
20
25
|
* @param callback - Function to call when the sequence is completed
|
|
21
26
|
* @param options - Options for the sequence behavior
|
|
@@ -38,6 +43,11 @@ interface UseHotkeySequenceOptions extends Omit<SequenceOptions, 'target'> {
|
|
|
38
43
|
* deleteInnerWord()
|
|
39
44
|
* }, { timeout: 500 })
|
|
40
45
|
*
|
|
46
|
+
* // Same modifier on consecutive steps (bare Shift between chords is ignored)
|
|
47
|
+
* useHotkeySequence(['Shift+R', 'Shift+T'], () => {
|
|
48
|
+
* nextAction()
|
|
49
|
+
* })
|
|
50
|
+
*
|
|
41
51
|
* return <div>...</div>
|
|
42
52
|
* }
|
|
43
53
|
* ```
|
|
@@ -16,6 +16,11 @@ interface UseHotkeySequenceOptions extends Omit<SequenceOptions, 'target'> {
|
|
|
16
16
|
* This hook allows you to register multi-key sequences like 'g g' or 'd d'
|
|
17
17
|
* that trigger when the full sequence is pressed within a timeout.
|
|
18
18
|
*
|
|
19
|
+
* Each step may include modifiers. You can chain the same modifier across
|
|
20
|
+
* steps (e.g. `Shift+R` then `Shift+T`). Modifier-only keydown events (Shift,
|
|
21
|
+
* Control, Alt, or Meta pressed alone) are ignored while matching—they do not
|
|
22
|
+
* advance the sequence or reset progress.
|
|
23
|
+
*
|
|
19
24
|
* @param sequence - Array of hotkey strings that form the sequence
|
|
20
25
|
* @param callback - Function to call when the sequence is completed
|
|
21
26
|
* @param options - Options for the sequence behavior
|
|
@@ -38,6 +43,11 @@ interface UseHotkeySequenceOptions extends Omit<SequenceOptions, 'target'> {
|
|
|
38
43
|
* deleteInnerWord()
|
|
39
44
|
* }, { timeout: 500 })
|
|
40
45
|
*
|
|
46
|
+
* // Same modifier on consecutive steps (bare Shift between chords is ignored)
|
|
47
|
+
* useHotkeySequence(['Shift+R', 'Shift+T'], () => {
|
|
48
|
+
* nextAction()
|
|
49
|
+
* })
|
|
50
|
+
*
|
|
41
51
|
* return <div>...</div>
|
|
42
52
|
* }
|
|
43
53
|
* ```
|
|
@@ -10,6 +10,11 @@ import { useEffect, useRef } from "preact/hooks";
|
|
|
10
10
|
* This hook allows you to register multi-key sequences like 'g g' or 'd d'
|
|
11
11
|
* that trigger when the full sequence is pressed within a timeout.
|
|
12
12
|
*
|
|
13
|
+
* Each step may include modifiers. You can chain the same modifier across
|
|
14
|
+
* steps (e.g. `Shift+R` then `Shift+T`). Modifier-only keydown events (Shift,
|
|
15
|
+
* Control, Alt, or Meta pressed alone) are ignored while matching—they do not
|
|
16
|
+
* advance the sequence or reset progress.
|
|
17
|
+
*
|
|
13
18
|
* @param sequence - Array of hotkey strings that form the sequence
|
|
14
19
|
* @param callback - Function to call when the sequence is completed
|
|
15
20
|
* @param options - Options for the sequence behavior
|
|
@@ -32,6 +37,11 @@ import { useEffect, useRef } from "preact/hooks";
|
|
|
32
37
|
* deleteInnerWord()
|
|
33
38
|
* }, { timeout: 500 })
|
|
34
39
|
*
|
|
40
|
+
* // Same modifier on consecutive steps (bare Shift between chords is ignored)
|
|
41
|
+
* useHotkeySequence(['Shift+R', 'Shift+T'], () => {
|
|
42
|
+
* nextAction()
|
|
43
|
+
* })
|
|
44
|
+
*
|
|
35
45
|
* return <div>...</div>
|
|
36
46
|
* }
|
|
37
47
|
* ```
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"useHotkeySequence.js","names":[],"sources":["../src/useHotkeySequence.ts"],"sourcesContent":["import { useEffect, useRef } from 'preact/hooks'\nimport { formatHotkeySequence, getSequenceManager } from '@tanstack/hotkeys'\nimport { useDefaultHotkeysOptions } from './HotkeysProvider'\nimport { isRef } from './utils'\nimport type { RefObject } from 'preact'\nimport type {\n HotkeyCallback,\n HotkeyCallbackContext,\n HotkeySequence,\n SequenceOptions,\n SequenceRegistrationHandle,\n} from '@tanstack/hotkeys'\n\nexport interface UseHotkeySequenceOptions extends Omit<\n SequenceOptions,\n 'target'\n> {\n /**\n * The DOM element to attach the event listener to.\n * Can be a Preact ref, direct DOM element, or null.\n * Defaults to document.\n */\n target?:\n | RefObject<HTMLElement | null>\n | HTMLElement\n | Document\n | Window\n | null\n}\n\n/**\n * Preact hook for registering a keyboard shortcut sequence (Vim-style).\n *\n * This hook allows you to register multi-key sequences like 'g g' or 'd d'\n * that trigger when the full sequence is pressed within a timeout.\n *\n * @param sequence - Array of hotkey strings that form the sequence\n * @param callback - Function to call when the sequence is completed\n * @param options - Options for the sequence behavior\n *\n * @example\n * ```tsx\n * function VimEditor() {\n * // 'g g' to go to top\n * useHotkeySequence(['G', 'G'], () => {\n * scrollToTop()\n * })\n *\n * // 'd d' to delete line\n * useHotkeySequence(['D', 'D'], () => {\n * deleteLine()\n * })\n *\n * // 'd i w' to delete inner word\n * useHotkeySequence(['D', 'I', 'W'], () => {\n * deleteInnerWord()\n * }, { timeout: 500 })\n *\n * return <div>...</div>\n * }\n * ```\n */\nexport function useHotkeySequence(\n sequence: HotkeySequence,\n callback: HotkeyCallback,\n options: UseHotkeySequenceOptions = {},\n): void {\n const mergedOptions = {\n ...useDefaultHotkeysOptions().hotkeySequence,\n ...options,\n } as UseHotkeySequenceOptions\n\n const manager = getSequenceManager()\n\n // Stable ref for registration handle\n const registrationRef = useRef<SequenceRegistrationHandle | null>(null)\n\n // Refs to capture current values for use in effect without adding dependencies\n const callbackRef = useRef(callback)\n const optionsRef = useRef(mergedOptions)\n const managerRef = useRef(manager)\n\n // Update refs on every render\n callbackRef.current = callback\n optionsRef.current = mergedOptions\n managerRef.current = manager\n\n // Track previous target and sequence to detect changes requiring re-registration\n const prevTargetRef = useRef<HTMLElement | Document | Window | null>(null)\n const prevSequenceRef = useRef<string | null>(null)\n\n // Normalize to hotkey sequence string (join with spaces)\n const hotkeySequenceString = formatHotkeySequence(sequence)\n\n // Extract options without target (target is handled separately)\n const { target: _target, ...optionsWithoutTarget } = mergedOptions\n\n useEffect(() => {\n if (sequence.length === 0) {\n return\n }\n\n // Resolve target inside the effect so refs are already attached after mount\n const resolvedTarget = isRef(optionsRef.current.target)\n ? optionsRef.current.target.current\n : (optionsRef.current.target ??\n (typeof document !== 'undefined' ? document : null))\n\n // Skip if no valid target (SSR or ref still null)\n if (!resolvedTarget) {\n return\n }\n\n // Check if we need to re-register (target or sequence changed)\n const targetChanged =\n prevTargetRef.current !== null && prevTargetRef.current !== resolvedTarget\n const sequenceChanged =\n prevSequenceRef.current !== null &&\n prevSequenceRef.current !== hotkeySequenceString\n\n // If we have an active registration and target/sequence changed, unregister first\n if (\n registrationRef.current?.isActive &&\n (targetChanged || sequenceChanged)\n ) {\n registrationRef.current.unregister()\n registrationRef.current = null\n }\n\n // Register if needed (no active registration)\n if (!registrationRef.current || !registrationRef.current.isActive) {\n registrationRef.current = managerRef.current.register(\n sequence,\n (event, context) => callbackRef.current(event, context),\n {\n ...optionsRef.current,\n target: resolvedTarget,\n },\n )\n }\n\n // Update tracking refs\n prevTargetRef.current = resolvedTarget\n prevSequenceRef.current = hotkeySequenceString\n\n // Cleanup on unmount\n return () => {\n if (registrationRef.current?.isActive) {\n registrationRef.current.unregister()\n registrationRef.current = null\n }\n }\n }, [hotkeySequenceString, mergedOptions.enabled, sequence])\n\n // Sync callback and options on EVERY render (outside useEffect)\n if (registrationRef.current?.isActive) {\n registrationRef.current.callback = (\n event: KeyboardEvent,\n context: HotkeyCallbackContext,\n ) => callbackRef.current(event, context)\n registrationRef.current.setOptions(optionsWithoutTarget)\n }\n}\n"],"mappings":"
|
|
1
|
+
{"version":3,"file":"useHotkeySequence.js","names":[],"sources":["../src/useHotkeySequence.ts"],"sourcesContent":["import { useEffect, useRef } from 'preact/hooks'\nimport { formatHotkeySequence, getSequenceManager } from '@tanstack/hotkeys'\nimport { useDefaultHotkeysOptions } from './HotkeysProvider'\nimport { isRef } from './utils'\nimport type { RefObject } from 'preact'\nimport type {\n HotkeyCallback,\n HotkeyCallbackContext,\n HotkeySequence,\n SequenceOptions,\n SequenceRegistrationHandle,\n} from '@tanstack/hotkeys'\n\nexport interface UseHotkeySequenceOptions extends Omit<\n SequenceOptions,\n 'target'\n> {\n /**\n * The DOM element to attach the event listener to.\n * Can be a Preact ref, direct DOM element, or null.\n * Defaults to document.\n */\n target?:\n | RefObject<HTMLElement | null>\n | HTMLElement\n | Document\n | Window\n | null\n}\n\n/**\n * Preact hook for registering a keyboard shortcut sequence (Vim-style).\n *\n * This hook allows you to register multi-key sequences like 'g g' or 'd d'\n * that trigger when the full sequence is pressed within a timeout.\n *\n * Each step may include modifiers. You can chain the same modifier across\n * steps (e.g. `Shift+R` then `Shift+T`). Modifier-only keydown events (Shift,\n * Control, Alt, or Meta pressed alone) are ignored while matching—they do not\n * advance the sequence or reset progress.\n *\n * @param sequence - Array of hotkey strings that form the sequence\n * @param callback - Function to call when the sequence is completed\n * @param options - Options for the sequence behavior\n *\n * @example\n * ```tsx\n * function VimEditor() {\n * // 'g g' to go to top\n * useHotkeySequence(['G', 'G'], () => {\n * scrollToTop()\n * })\n *\n * // 'd d' to delete line\n * useHotkeySequence(['D', 'D'], () => {\n * deleteLine()\n * })\n *\n * // 'd i w' to delete inner word\n * useHotkeySequence(['D', 'I', 'W'], () => {\n * deleteInnerWord()\n * }, { timeout: 500 })\n *\n * // Same modifier on consecutive steps (bare Shift between chords is ignored)\n * useHotkeySequence(['Shift+R', 'Shift+T'], () => {\n * nextAction()\n * })\n *\n * return <div>...</div>\n * }\n * ```\n */\nexport function useHotkeySequence(\n sequence: HotkeySequence,\n callback: HotkeyCallback,\n options: UseHotkeySequenceOptions = {},\n): void {\n const mergedOptions = {\n ...useDefaultHotkeysOptions().hotkeySequence,\n ...options,\n } as UseHotkeySequenceOptions\n\n const manager = getSequenceManager()\n\n // Stable ref for registration handle\n const registrationRef = useRef<SequenceRegistrationHandle | null>(null)\n\n // Refs to capture current values for use in effect without adding dependencies\n const callbackRef = useRef(callback)\n const optionsRef = useRef(mergedOptions)\n const managerRef = useRef(manager)\n\n // Update refs on every render\n callbackRef.current = callback\n optionsRef.current = mergedOptions\n managerRef.current = manager\n\n // Track previous target and sequence to detect changes requiring re-registration\n const prevTargetRef = useRef<HTMLElement | Document | Window | null>(null)\n const prevSequenceRef = useRef<string | null>(null)\n\n // Normalize to hotkey sequence string (join with spaces)\n const hotkeySequenceString = formatHotkeySequence(sequence)\n\n // Extract options without target (target is handled separately)\n const { target: _target, ...optionsWithoutTarget } = mergedOptions\n\n useEffect(() => {\n if (sequence.length === 0) {\n return\n }\n\n // Resolve target inside the effect so refs are already attached after mount\n const resolvedTarget = isRef(optionsRef.current.target)\n ? optionsRef.current.target.current\n : (optionsRef.current.target ??\n (typeof document !== 'undefined' ? document : null))\n\n // Skip if no valid target (SSR or ref still null)\n if (!resolvedTarget) {\n return\n }\n\n // Check if we need to re-register (target or sequence changed)\n const targetChanged =\n prevTargetRef.current !== null && prevTargetRef.current !== resolvedTarget\n const sequenceChanged =\n prevSequenceRef.current !== null &&\n prevSequenceRef.current !== hotkeySequenceString\n\n // If we have an active registration and target/sequence changed, unregister first\n if (\n registrationRef.current?.isActive &&\n (targetChanged || sequenceChanged)\n ) {\n registrationRef.current.unregister()\n registrationRef.current = null\n }\n\n // Register if needed (no active registration)\n if (!registrationRef.current || !registrationRef.current.isActive) {\n registrationRef.current = managerRef.current.register(\n sequence,\n (event, context) => callbackRef.current(event, context),\n {\n ...optionsRef.current,\n target: resolvedTarget,\n },\n )\n }\n\n // Update tracking refs\n prevTargetRef.current = resolvedTarget\n prevSequenceRef.current = hotkeySequenceString\n\n // Cleanup on unmount\n return () => {\n if (registrationRef.current?.isActive) {\n registrationRef.current.unregister()\n registrationRef.current = null\n }\n }\n }, [hotkeySequenceString, mergedOptions.enabled, sequence])\n\n // Sync callback and options on EVERY render (outside useEffect)\n if (registrationRef.current?.isActive) {\n registrationRef.current.callback = (\n event: KeyboardEvent,\n context: HotkeyCallbackContext,\n ) => callbackRef.current(event, context)\n registrationRef.current.setOptions(optionsWithoutTarget)\n }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwEA,SAAgB,kBACd,UACA,UACA,UAAoC,EAAE,EAChC;CACN,MAAM,gBAAgB;EACpB,GAAG,0BAA0B,CAAC;EAC9B,GAAG;EACJ;CAED,MAAM,UAAU,oBAAoB;CAGpC,MAAM,kBAAkB,OAA0C,KAAK;CAGvE,MAAM,cAAc,OAAO,SAAS;CACpC,MAAM,aAAa,OAAO,cAAc;CACxC,MAAM,aAAa,OAAO,QAAQ;AAGlC,aAAY,UAAU;AACtB,YAAW,UAAU;AACrB,YAAW,UAAU;CAGrB,MAAM,gBAAgB,OAA+C,KAAK;CAC1E,MAAM,kBAAkB,OAAsB,KAAK;CAGnD,MAAM,uBAAuB,qBAAqB,SAAS;CAG3D,MAAM,EAAE,QAAQ,SAAS,GAAG,yBAAyB;AAErD,iBAAgB;AACd,MAAI,SAAS,WAAW,EACtB;EAIF,MAAM,iBAAiB,MAAM,WAAW,QAAQ,OAAO,GACnD,WAAW,QAAQ,OAAO,UACzB,WAAW,QAAQ,WACnB,OAAO,aAAa,cAAc,WAAW;AAGlD,MAAI,CAAC,eACH;EAIF,MAAM,gBACJ,cAAc,YAAY,QAAQ,cAAc,YAAY;EAC9D,MAAM,kBACJ,gBAAgB,YAAY,QAC5B,gBAAgB,YAAY;AAG9B,MACE,gBAAgB,SAAS,aACxB,iBAAiB,kBAClB;AACA,mBAAgB,QAAQ,YAAY;AACpC,mBAAgB,UAAU;;AAI5B,MAAI,CAAC,gBAAgB,WAAW,CAAC,gBAAgB,QAAQ,SACvD,iBAAgB,UAAU,WAAW,QAAQ,SAC3C,WACC,OAAO,YAAY,YAAY,QAAQ,OAAO,QAAQ,EACvD;GACE,GAAG,WAAW;GACd,QAAQ;GACT,CACF;AAIH,gBAAc,UAAU;AACxB,kBAAgB,UAAU;AAG1B,eAAa;AACX,OAAI,gBAAgB,SAAS,UAAU;AACrC,oBAAgB,QAAQ,YAAY;AACpC,oBAAgB,UAAU;;;IAG7B;EAAC;EAAsB,cAAc;EAAS;EAAS,CAAC;AAG3D,KAAI,gBAAgB,SAAS,UAAU;AACrC,kBAAgB,QAAQ,YACtB,OACA,YACG,YAAY,QAAQ,OAAO,QAAQ;AACxC,kBAAgB,QAAQ,WAAW,qBAAqB"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@tanstack/preact-hotkeys",
|
|
3
|
-
"version": "0.5.
|
|
3
|
+
"version": "0.5.1",
|
|
4
4
|
"description": "Preact adapter for TanStack Hotkeys",
|
|
5
5
|
"author": "Tanner Linsley",
|
|
6
6
|
"license": "MIT",
|
|
@@ -40,7 +40,7 @@
|
|
|
40
40
|
],
|
|
41
41
|
"dependencies": {
|
|
42
42
|
"@tanstack/preact-store": "^0.11.2",
|
|
43
|
-
"@tanstack/hotkeys": "0.4.
|
|
43
|
+
"@tanstack/hotkeys": "0.4.3"
|
|
44
44
|
},
|
|
45
45
|
"devDependencies": {
|
|
46
46
|
"@preact/preset-vite": "^2.10.5",
|
package/src/useHotkeySequence.ts
CHANGED
|
@@ -34,6 +34,11 @@ export interface UseHotkeySequenceOptions extends Omit<
|
|
|
34
34
|
* This hook allows you to register multi-key sequences like 'g g' or 'd d'
|
|
35
35
|
* that trigger when the full sequence is pressed within a timeout.
|
|
36
36
|
*
|
|
37
|
+
* Each step may include modifiers. You can chain the same modifier across
|
|
38
|
+
* steps (e.g. `Shift+R` then `Shift+T`). Modifier-only keydown events (Shift,
|
|
39
|
+
* Control, Alt, or Meta pressed alone) are ignored while matching—they do not
|
|
40
|
+
* advance the sequence or reset progress.
|
|
41
|
+
*
|
|
37
42
|
* @param sequence - Array of hotkey strings that form the sequence
|
|
38
43
|
* @param callback - Function to call when the sequence is completed
|
|
39
44
|
* @param options - Options for the sequence behavior
|
|
@@ -56,6 +61,11 @@ export interface UseHotkeySequenceOptions extends Omit<
|
|
|
56
61
|
* deleteInnerWord()
|
|
57
62
|
* }, { timeout: 500 })
|
|
58
63
|
*
|
|
64
|
+
* // Same modifier on consecutive steps (bare Shift between chords is ignored)
|
|
65
|
+
* useHotkeySequence(['Shift+R', 'Shift+T'], () => {
|
|
66
|
+
* nextAction()
|
|
67
|
+
* })
|
|
68
|
+
*
|
|
59
69
|
* return <div>...</div>
|
|
60
70
|
* }
|
|
61
71
|
* ```
|