@tanstack/solid-hotkeys 0.7.0 → 0.8.0
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/README.md +1 -1
- package/dist/createHotkey.cjs +1 -2
- package/dist/createHotkey.cjs.map +1 -1
- package/dist/createHotkey.js +2 -3
- package/dist/createHotkey.js.map +1 -1
- package/dist/createHotkeys.cjs +1 -1
- package/dist/createHotkeys.cjs.map +1 -1
- package/dist/createHotkeys.js +2 -2
- package/dist/createHotkeys.js.map +1 -1
- package/package.json +2 -2
- package/src/createHotkey.ts +2 -8
- package/src/createHotkeys.ts +2 -8
package/README.md
CHANGED
|
@@ -37,7 +37,7 @@
|
|
|
37
37
|
# TanStack Hotkeys
|
|
38
38
|
|
|
39
39
|
> [!NOTE]
|
|
40
|
-
> TanStack Hotkeys is
|
|
40
|
+
> TanStack Hotkeys is alpha. We are actively developing the library and are open to feedback and contributions.
|
|
41
41
|
|
|
42
42
|
Type-safe keyboard shortcuts for the web. Template-string bindings, parsed objects, a cross-platform `Mod` key, a singleton Hotkey Manager, and utilities for cheatsheet UIs—built to stay SSR-friendly.
|
|
43
43
|
|
package/dist/createHotkey.cjs
CHANGED
|
@@ -79,8 +79,7 @@ function createHotkey(hotkey, callback, options = {}) {
|
|
|
79
79
|
...defaultOptions.hotkey,
|
|
80
80
|
...resolvedOptions
|
|
81
81
|
};
|
|
82
|
-
const
|
|
83
|
-
const hotkeyString = typeof resolvedHotkey === "string" ? resolvedHotkey : (0, _tanstack_hotkeys.formatHotkey)((0, _tanstack_hotkeys.rawHotkeyToParsedHotkey)(resolvedHotkey, platform));
|
|
82
|
+
const hotkeyString = (0, _tanstack_hotkeys.normalizeRegisterableHotkey)(resolvedHotkey, mergedOptions.platform ?? (0, _tanstack_hotkeys.detectPlatform)());
|
|
84
83
|
const resolvedTarget = "target" in mergedOptions ? mergedOptions.target ?? null : typeof document !== "undefined" ? document : null;
|
|
85
84
|
if (!resolvedTarget) {
|
|
86
85
|
if (registration?.isActive) {
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"createHotkey.cjs","names":["useDefaultHotkeysOptions"],"sources":["../src/createHotkey.ts"],"sourcesContent":["import { createEffect, onCleanup } from 'solid-js'\nimport {\n detectPlatform,\n
|
|
1
|
+
{"version":3,"file":"createHotkey.cjs","names":["useDefaultHotkeysOptions"],"sources":["../src/createHotkey.ts"],"sourcesContent":["import { createEffect, onCleanup } from 'solid-js'\nimport {\n detectPlatform,\n getHotkeyManager,\n normalizeRegisterableHotkey,\n} from '@tanstack/hotkeys'\nimport { useDefaultHotkeysOptions } from './HotkeysProvider'\nimport type {\n Hotkey,\n HotkeyCallback,\n HotkeyOptions,\n HotkeyRegistrationHandle,\n RegisterableHotkey,\n} from '@tanstack/hotkeys'\n\nexport interface CreateHotkeyOptions extends Omit<HotkeyOptions, 'target'> {\n /**\n * The DOM element to attach the event listener to.\n * Can be a direct DOM element, an accessor (for reactive targets that become\n * available after mount), or null. Defaults to document.\n * When using scoped targets, pass an accessor: () => ({ target: elementSignal() })\n * so the hotkey waits for the element to be attached before registering.\n */\n target?: HTMLElement | Document | Window | null\n}\n\n/**\n * SolidJS primitive for registering a keyboard hotkey.\n *\n * Uses the singleton HotkeyManager for efficient event handling.\n * The callback receives both the keyboard event and a context object\n * containing the hotkey string and parsed hotkey.\n *\n * This primitive automatically tracks reactive dependencies and updates\n * the registration when options or the callback change.\n *\n * @param hotkey - The hotkey string (e.g., 'Mod+S', 'Escape') or RawHotkey object (supports `mod` for cross-platform)\n * @param callback - The function to call when the hotkey is pressed\n * @param options - Options for the hotkey behavior\n *\n * @example\n * ```tsx\n * function SaveButton() {\n * const [count, setCount] = createSignal(0)\n *\n * // Callback always has access to latest count value\n * createHotkey('Mod+S', (event, { hotkey }) => {\n * console.log(`Save triggered, count is ${count()}`)\n * handleSave()\n * })\n *\n * return <button onClick={() => setCount(c => c + 1)}>Count: {count()}</button>\n * }\n * ```\n *\n * @example\n * ```tsx\n * function Modal(props) {\n * // enabled option is reactive\n * createHotkey('Escape', () => {\n * props.onClose()\n * }, () => ({ enabled: props.isOpen }))\n *\n * return <Show when={props.isOpen}>\n * <div class=\"modal\">...</div>\n * </Show>\n * }\n * ```\n *\n * @example\n * ```tsx\n * function Editor() {\n * const [editorRef, setEditorRef] = createSignal<HTMLDivElement | null>(null)\n *\n * // Scoped to a specific element - use accessor so hotkey waits for ref\n * createHotkey('Mod+S', save, () => ({ target: editorRef() }))\n *\n * return <div ref={setEditorRef}>...</div>\n * }\n * ```\n */\nexport function createHotkey(\n hotkey: RegisterableHotkey | (() => RegisterableHotkey),\n callback: HotkeyCallback,\n options: CreateHotkeyOptions | (() => CreateHotkeyOptions) = {},\n): void {\n const defaultOptions = useDefaultHotkeysOptions()\n const manager = getHotkeyManager()\n\n let registration: HotkeyRegistrationHandle | null = null\n let lastHotkeyString: Hotkey | null = null\n let lastTarget: HTMLElement | Document | Window | null = null\n\n onCleanup(() => {\n if (registration?.isActive) {\n registration.unregister()\n registration = null\n }\n lastHotkeyString = null\n lastTarget = null\n })\n\n createEffect(() => {\n // Resolve reactive values\n const resolvedHotkey = typeof hotkey === 'function' ? hotkey() : hotkey\n const resolvedOptions = typeof options === 'function' ? options() : options\n\n const mergedOptions = {\n ...defaultOptions.hotkey,\n ...resolvedOptions,\n } as CreateHotkeyOptions\n\n // Normalize to hotkey string\n const platform = mergedOptions.platform ?? detectPlatform()\n const hotkeyString = normalizeRegisterableHotkey(resolvedHotkey, platform)\n\n // Resolve target: when explicitly provided (even as null), use it and skip if null.\n // When not provided, default to document. Matches React's ref handling.\n const resolvedTarget =\n 'target' in mergedOptions\n ? (mergedOptions.target ?? null)\n : typeof document !== 'undefined'\n ? document\n : null\n\n if (!resolvedTarget) {\n if (registration?.isActive) {\n registration.unregister()\n registration = null\n }\n lastHotkeyString = null\n lastTarget = null\n return\n }\n\n // Extract options without target (target is handled separately)\n const { target: _target, ...optionsWithoutTarget } = mergedOptions\n\n if (\n registration?.isActive &&\n lastHotkeyString === hotkeyString &&\n lastTarget === resolvedTarget\n ) {\n registration.callback = callback\n registration.setOptions(optionsWithoutTarget)\n return\n }\n\n if (registration?.isActive) {\n registration.unregister()\n registration = null\n }\n\n registration = manager.register(hotkeyString, callback, {\n ...optionsWithoutTarget,\n target: resolvedTarget,\n })\n\n if (registration.isActive) {\n registration.callback = callback\n registration.setOptions(optionsWithoutTarget)\n }\n\n lastHotkeyString = hotkeyString\n lastTarget = resolvedTarget\n })\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiFA,SAAgB,aACd,QACA,UACA,UAA6D,EAAE,EACzD;CACN,MAAM,iBAAiBA,kDAA0B;CACjD,MAAM,mDAA4B;CAElC,IAAI,eAAgD;CACpD,IAAI,mBAAkC;CACtC,IAAI,aAAqD;AAEzD,+BAAgB;AACd,MAAI,cAAc,UAAU;AAC1B,gBAAa,YAAY;AACzB,kBAAe;;AAEjB,qBAAmB;AACnB,eAAa;GACb;AAEF,kCAAmB;EAEjB,MAAM,iBAAiB,OAAO,WAAW,aAAa,QAAQ,GAAG;EACjE,MAAM,kBAAkB,OAAO,YAAY,aAAa,SAAS,GAAG;EAEpE,MAAM,gBAAgB;GACpB,GAAG,eAAe;GAClB,GAAG;GACJ;EAID,MAAM,kEAA2C,gBADhC,cAAc,mDAA4B,CACe;EAI1E,MAAM,iBACJ,YAAY,gBACP,cAAc,UAAU,OACzB,OAAO,aAAa,cAClB,WACA;AAER,MAAI,CAAC,gBAAgB;AACnB,OAAI,cAAc,UAAU;AAC1B,iBAAa,YAAY;AACzB,mBAAe;;AAEjB,sBAAmB;AACnB,gBAAa;AACb;;EAIF,MAAM,EAAE,QAAQ,SAAS,GAAG,yBAAyB;AAErD,MACE,cAAc,YACd,qBAAqB,gBACrB,eAAe,gBACf;AACA,gBAAa,WAAW;AACxB,gBAAa,WAAW,qBAAqB;AAC7C;;AAGF,MAAI,cAAc,UAAU;AAC1B,gBAAa,YAAY;AACzB,kBAAe;;AAGjB,iBAAe,QAAQ,SAAS,cAAc,UAAU;GACtD,GAAG;GACH,QAAQ;GACT,CAAC;AAEF,MAAI,aAAa,UAAU;AACzB,gBAAa,WAAW;AACxB,gBAAa,WAAW,qBAAqB;;AAG/C,qBAAmB;AACnB,eAAa;GACb"}
|
package/dist/createHotkey.js
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { useDefaultHotkeysOptions } from "./HotkeysProvider.js";
|
|
2
|
-
import { detectPlatform,
|
|
2
|
+
import { detectPlatform, getHotkeyManager, normalizeRegisterableHotkey } from "@tanstack/hotkeys";
|
|
3
3
|
import { createEffect, onCleanup } from "solid-js";
|
|
4
4
|
|
|
5
5
|
//#region src/createHotkey.ts
|
|
@@ -79,8 +79,7 @@ function createHotkey(hotkey, callback, options = {}) {
|
|
|
79
79
|
...defaultOptions.hotkey,
|
|
80
80
|
...resolvedOptions
|
|
81
81
|
};
|
|
82
|
-
const
|
|
83
|
-
const hotkeyString = typeof resolvedHotkey === "string" ? resolvedHotkey : formatHotkey(rawHotkeyToParsedHotkey(resolvedHotkey, platform));
|
|
82
|
+
const hotkeyString = normalizeRegisterableHotkey(resolvedHotkey, mergedOptions.platform ?? detectPlatform());
|
|
84
83
|
const resolvedTarget = "target" in mergedOptions ? mergedOptions.target ?? null : typeof document !== "undefined" ? document : null;
|
|
85
84
|
if (!resolvedTarget) {
|
|
86
85
|
if (registration?.isActive) {
|
package/dist/createHotkey.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"createHotkey.js","names":[],"sources":["../src/createHotkey.ts"],"sourcesContent":["import { createEffect, onCleanup } from 'solid-js'\nimport {\n detectPlatform,\n
|
|
1
|
+
{"version":3,"file":"createHotkey.js","names":[],"sources":["../src/createHotkey.ts"],"sourcesContent":["import { createEffect, onCleanup } from 'solid-js'\nimport {\n detectPlatform,\n getHotkeyManager,\n normalizeRegisterableHotkey,\n} from '@tanstack/hotkeys'\nimport { useDefaultHotkeysOptions } from './HotkeysProvider'\nimport type {\n Hotkey,\n HotkeyCallback,\n HotkeyOptions,\n HotkeyRegistrationHandle,\n RegisterableHotkey,\n} from '@tanstack/hotkeys'\n\nexport interface CreateHotkeyOptions extends Omit<HotkeyOptions, 'target'> {\n /**\n * The DOM element to attach the event listener to.\n * Can be a direct DOM element, an accessor (for reactive targets that become\n * available after mount), or null. Defaults to document.\n * When using scoped targets, pass an accessor: () => ({ target: elementSignal() })\n * so the hotkey waits for the element to be attached before registering.\n */\n target?: HTMLElement | Document | Window | null\n}\n\n/**\n * SolidJS primitive for registering a keyboard hotkey.\n *\n * Uses the singleton HotkeyManager for efficient event handling.\n * The callback receives both the keyboard event and a context object\n * containing the hotkey string and parsed hotkey.\n *\n * This primitive automatically tracks reactive dependencies and updates\n * the registration when options or the callback change.\n *\n * @param hotkey - The hotkey string (e.g., 'Mod+S', 'Escape') or RawHotkey object (supports `mod` for cross-platform)\n * @param callback - The function to call when the hotkey is pressed\n * @param options - Options for the hotkey behavior\n *\n * @example\n * ```tsx\n * function SaveButton() {\n * const [count, setCount] = createSignal(0)\n *\n * // Callback always has access to latest count value\n * createHotkey('Mod+S', (event, { hotkey }) => {\n * console.log(`Save triggered, count is ${count()}`)\n * handleSave()\n * })\n *\n * return <button onClick={() => setCount(c => c + 1)}>Count: {count()}</button>\n * }\n * ```\n *\n * @example\n * ```tsx\n * function Modal(props) {\n * // enabled option is reactive\n * createHotkey('Escape', () => {\n * props.onClose()\n * }, () => ({ enabled: props.isOpen }))\n *\n * return <Show when={props.isOpen}>\n * <div class=\"modal\">...</div>\n * </Show>\n * }\n * ```\n *\n * @example\n * ```tsx\n * function Editor() {\n * const [editorRef, setEditorRef] = createSignal<HTMLDivElement | null>(null)\n *\n * // Scoped to a specific element - use accessor so hotkey waits for ref\n * createHotkey('Mod+S', save, () => ({ target: editorRef() }))\n *\n * return <div ref={setEditorRef}>...</div>\n * }\n * ```\n */\nexport function createHotkey(\n hotkey: RegisterableHotkey | (() => RegisterableHotkey),\n callback: HotkeyCallback,\n options: CreateHotkeyOptions | (() => CreateHotkeyOptions) = {},\n): void {\n const defaultOptions = useDefaultHotkeysOptions()\n const manager = getHotkeyManager()\n\n let registration: HotkeyRegistrationHandle | null = null\n let lastHotkeyString: Hotkey | null = null\n let lastTarget: HTMLElement | Document | Window | null = null\n\n onCleanup(() => {\n if (registration?.isActive) {\n registration.unregister()\n registration = null\n }\n lastHotkeyString = null\n lastTarget = null\n })\n\n createEffect(() => {\n // Resolve reactive values\n const resolvedHotkey = typeof hotkey === 'function' ? hotkey() : hotkey\n const resolvedOptions = typeof options === 'function' ? options() : options\n\n const mergedOptions = {\n ...defaultOptions.hotkey,\n ...resolvedOptions,\n } as CreateHotkeyOptions\n\n // Normalize to hotkey string\n const platform = mergedOptions.platform ?? detectPlatform()\n const hotkeyString = normalizeRegisterableHotkey(resolvedHotkey, platform)\n\n // Resolve target: when explicitly provided (even as null), use it and skip if null.\n // When not provided, default to document. Matches React's ref handling.\n const resolvedTarget =\n 'target' in mergedOptions\n ? (mergedOptions.target ?? null)\n : typeof document !== 'undefined'\n ? document\n : null\n\n if (!resolvedTarget) {\n if (registration?.isActive) {\n registration.unregister()\n registration = null\n }\n lastHotkeyString = null\n lastTarget = null\n return\n }\n\n // Extract options without target (target is handled separately)\n const { target: _target, ...optionsWithoutTarget } = mergedOptions\n\n if (\n registration?.isActive &&\n lastHotkeyString === hotkeyString &&\n lastTarget === resolvedTarget\n ) {\n registration.callback = callback\n registration.setOptions(optionsWithoutTarget)\n return\n }\n\n if (registration?.isActive) {\n registration.unregister()\n registration = null\n }\n\n registration = manager.register(hotkeyString, callback, {\n ...optionsWithoutTarget,\n target: resolvedTarget,\n })\n\n if (registration.isActive) {\n registration.callback = callback\n registration.setOptions(optionsWithoutTarget)\n }\n\n lastHotkeyString = hotkeyString\n lastTarget = resolvedTarget\n })\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiFA,SAAgB,aACd,QACA,UACA,UAA6D,EAAE,EACzD;CACN,MAAM,iBAAiB,0BAA0B;CACjD,MAAM,UAAU,kBAAkB;CAElC,IAAI,eAAgD;CACpD,IAAI,mBAAkC;CACtC,IAAI,aAAqD;AAEzD,iBAAgB;AACd,MAAI,cAAc,UAAU;AAC1B,gBAAa,YAAY;AACzB,kBAAe;;AAEjB,qBAAmB;AACnB,eAAa;GACb;AAEF,oBAAmB;EAEjB,MAAM,iBAAiB,OAAO,WAAW,aAAa,QAAQ,GAAG;EACjE,MAAM,kBAAkB,OAAO,YAAY,aAAa,SAAS,GAAG;EAEpE,MAAM,gBAAgB;GACpB,GAAG,eAAe;GAClB,GAAG;GACJ;EAID,MAAM,eAAe,4BAA4B,gBADhC,cAAc,YAAY,gBAAgB,CACe;EAI1E,MAAM,iBACJ,YAAY,gBACP,cAAc,UAAU,OACzB,OAAO,aAAa,cAClB,WACA;AAER,MAAI,CAAC,gBAAgB;AACnB,OAAI,cAAc,UAAU;AAC1B,iBAAa,YAAY;AACzB,mBAAe;;AAEjB,sBAAmB;AACnB,gBAAa;AACb;;EAIF,MAAM,EAAE,QAAQ,SAAS,GAAG,yBAAyB;AAErD,MACE,cAAc,YACd,qBAAqB,gBACrB,eAAe,gBACf;AACA,gBAAa,WAAW;AACxB,gBAAa,WAAW,qBAAqB;AAC7C;;AAGF,MAAI,cAAc,UAAU;AAC1B,gBAAa,YAAY;AACzB,kBAAe;;AAGjB,iBAAe,QAAQ,SAAS,cAAc,UAAU;GACtD,GAAG;GACH,QAAQ;GACT,CAAC;AAEF,MAAI,aAAa,UAAU;AACzB,gBAAa,WAAW;AACxB,gBAAa,WAAW,qBAAqB;;AAG/C,qBAAmB;AACnB,eAAa;GACb"}
|
package/dist/createHotkeys.cjs
CHANGED
|
@@ -63,7 +63,7 @@ function createHotkeys(hotkeys, commonOptions = {}) {
|
|
|
63
63
|
...resolvedDefOptions
|
|
64
64
|
};
|
|
65
65
|
const platform = mergedOptions.platform ?? (0, _tanstack_hotkeys.detectPlatform)();
|
|
66
|
-
const hotkeyString =
|
|
66
|
+
const hotkeyString = (0, _tanstack_hotkeys.normalizeRegisterableHotkey)(def.hotkey, platform);
|
|
67
67
|
const resolvedTarget = "target" in mergedOptions ? mergedOptions.target ?? null : typeof document !== "undefined" ? document : null;
|
|
68
68
|
if (!resolvedTarget) continue;
|
|
69
69
|
const registrationKey = `${i}:${hotkeyString}`;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"createHotkeys.cjs","names":["useDefaultHotkeysOptions"],"sources":["../src/createHotkeys.ts"],"sourcesContent":["import { createEffect, onCleanup } from 'solid-js'\nimport {\n detectPlatform,\n
|
|
1
|
+
{"version":3,"file":"createHotkeys.cjs","names":["useDefaultHotkeysOptions"],"sources":["../src/createHotkeys.ts"],"sourcesContent":["import { createEffect, onCleanup } from 'solid-js'\nimport {\n detectPlatform,\n getHotkeyManager,\n normalizeRegisterableHotkey,\n} from '@tanstack/hotkeys'\nimport { useDefaultHotkeysOptions } from './HotkeysProvider'\nimport type { CreateHotkeyOptions } from './createHotkey'\nimport type {\n Hotkey,\n HotkeyCallback,\n HotkeyRegistrationHandle,\n RegisterableHotkey,\n} from '@tanstack/hotkeys'\n\n/**\n * A single hotkey definition for use with `createHotkeys`.\n */\nexport interface CreateHotkeyDefinition {\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?: CreateHotkeyOptions\n}\n\n/**\n * SolidJS primitive 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.\n *\n * Options are merged in this order:\n * HotkeysProvider defaults < commonOptions < per-definition options\n *\n * @param hotkeys - Array of hotkey definitions, or accessor returning them\n * @param commonOptions - Shared options applied to all hotkeys, or accessor\n *\n * @example\n * ```tsx\n * function Editor() {\n * createHotkeys([\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(props) {\n * createHotkeys(\n * () => props.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 createHotkeys(\n hotkeys:\n | Array<CreateHotkeyDefinition>\n | (() => Array<CreateHotkeyDefinition>),\n commonOptions: CreateHotkeyOptions | (() => CreateHotkeyOptions) = {},\n): void {\n type RegistrationRecord = {\n handle: HotkeyRegistrationHandle\n target: Document | HTMLElement | Window\n }\n\n const defaultOptions = useDefaultHotkeysOptions()\n const manager = getHotkeyManager()\n\n const registrations = new Map<string, RegistrationRecord>()\n\n // Clean up only when this component/scope disposes — not before every effect\n // re-run. An inner `onCleanup` inside `createEffect` runs whenever reactive\n // deps change (e.g. dynamic hotkey list), which unregistered every hotkey and\n // re-registered them, flooding the manager store and could freeze the tab.\n onCleanup(() => {\n for (const { handle } of registrations.values()) {\n if (handle.isActive) {\n handle.unregister()\n }\n }\n registrations.clear()\n })\n\n createEffect(() => {\n const resolvedHotkeys = typeof hotkeys === 'function' ? hotkeys() : hotkeys\n const resolvedCommonOptions =\n typeof commonOptions === 'function' ? commonOptions() : commonOptions\n\n const nextKeys = new Set<string>()\n const prepared: Array<{\n registrationKey: string\n def: CreateHotkeyDefinition\n mergedOptions: CreateHotkeyOptions\n hotkeyString: Hotkey\n resolvedTarget: Document | HTMLElement | Window\n }> = []\n\n for (let i = 0; i < resolvedHotkeys.length; i++) {\n const def = resolvedHotkeys[i]!\n const resolvedDefOptions = def.options ?? {}\n\n const mergedOptions = {\n ...defaultOptions.hotkey,\n ...resolvedCommonOptions,\n ...resolvedDefOptions,\n } as CreateHotkeyOptions\n\n const platform = mergedOptions.platform ?? detectPlatform()\n const hotkeyString = normalizeRegisterableHotkey(def.hotkey, platform)\n\n const resolvedTarget =\n 'target' in mergedOptions\n ? (mergedOptions.target ?? null)\n : typeof document !== 'undefined'\n ? document\n : null\n\n if (!resolvedTarget) {\n continue\n }\n\n const registrationKey = `${i}:${hotkeyString}`\n nextKeys.add(registrationKey)\n prepared.push({\n registrationKey,\n def,\n mergedOptions,\n hotkeyString,\n resolvedTarget,\n })\n }\n\n // Drop stale keys first so list index shifts don't briefly double-register\n // the same hotkey+target (conflictBehavior: 'warn' + devtools can loop).\n for (const [key, record] of [...registrations.entries()]) {\n if (!nextKeys.has(key)) {\n if (record.handle.isActive) {\n record.handle.unregister()\n }\n registrations.delete(key)\n }\n }\n\n for (const p of prepared) {\n const existing = registrations.get(p.registrationKey)\n if (existing?.handle.isActive && existing.target === p.resolvedTarget) {\n existing.handle.callback = p.def.callback\n const { target: _target, ...optionsWithoutTarget } = p.mergedOptions\n existing.handle.setOptions(optionsWithoutTarget)\n continue\n }\n\n if (existing) {\n if (existing.handle.isActive) {\n existing.handle.unregister()\n }\n registrations.delete(p.registrationKey)\n }\n\n const { target: _target, ...optionsWithoutTarget } = p.mergedOptions\n const handle = manager.register(p.hotkeyString, p.def.callback, {\n ...optionsWithoutTarget,\n target: p.resolvedTarget,\n })\n registrations.set(p.registrationKey, {\n handle,\n target: p.resolvedTarget,\n })\n }\n })\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiEA,SAAgB,cACd,SAGA,gBAAmE,EAAE,EAC/D;CAMN,MAAM,iBAAiBA,kDAA0B;CACjD,MAAM,mDAA4B;CAElC,MAAM,gCAAgB,IAAI,KAAiC;AAM3D,+BAAgB;AACd,OAAK,MAAM,EAAE,YAAY,cAAc,QAAQ,CAC7C,KAAI,OAAO,SACT,QAAO,YAAY;AAGvB,gBAAc,OAAO;GACrB;AAEF,kCAAmB;EACjB,MAAM,kBAAkB,OAAO,YAAY,aAAa,SAAS,GAAG;EACpE,MAAM,wBACJ,OAAO,kBAAkB,aAAa,eAAe,GAAG;EAE1D,MAAM,2BAAW,IAAI,KAAa;EAClC,MAAM,WAMD,EAAE;AAEP,OAAK,IAAI,IAAI,GAAG,IAAI,gBAAgB,QAAQ,KAAK;GAC/C,MAAM,MAAM,gBAAgB;GAC5B,MAAM,qBAAqB,IAAI,WAAW,EAAE;GAE5C,MAAM,gBAAgB;IACpB,GAAG,eAAe;IAClB,GAAG;IACH,GAAG;IACJ;GAED,MAAM,WAAW,cAAc,mDAA4B;GAC3D,MAAM,kEAA2C,IAAI,QAAQ,SAAS;GAEtE,MAAM,iBACJ,YAAY,gBACP,cAAc,UAAU,OACzB,OAAO,aAAa,cAClB,WACA;AAER,OAAI,CAAC,eACH;GAGF,MAAM,kBAAkB,GAAG,EAAE,GAAG;AAChC,YAAS,IAAI,gBAAgB;AAC7B,YAAS,KAAK;IACZ;IACA;IACA;IACA;IACA;IACD,CAAC;;AAKJ,OAAK,MAAM,CAAC,KAAK,WAAW,CAAC,GAAG,cAAc,SAAS,CAAC,CACtD,KAAI,CAAC,SAAS,IAAI,IAAI,EAAE;AACtB,OAAI,OAAO,OAAO,SAChB,QAAO,OAAO,YAAY;AAE5B,iBAAc,OAAO,IAAI;;AAI7B,OAAK,MAAM,KAAK,UAAU;GACxB,MAAM,WAAW,cAAc,IAAI,EAAE,gBAAgB;AACrD,OAAI,UAAU,OAAO,YAAY,SAAS,WAAW,EAAE,gBAAgB;AACrE,aAAS,OAAO,WAAW,EAAE,IAAI;IACjC,MAAM,EAAE,QAAQ,SAAS,GAAG,yBAAyB,EAAE;AACvD,aAAS,OAAO,WAAW,qBAAqB;AAChD;;AAGF,OAAI,UAAU;AACZ,QAAI,SAAS,OAAO,SAClB,UAAS,OAAO,YAAY;AAE9B,kBAAc,OAAO,EAAE,gBAAgB;;GAGzC,MAAM,EAAE,QAAQ,SAAS,GAAG,yBAAyB,EAAE;GACvD,MAAM,SAAS,QAAQ,SAAS,EAAE,cAAc,EAAE,IAAI,UAAU;IAC9D,GAAG;IACH,QAAQ,EAAE;IACX,CAAC;AACF,iBAAc,IAAI,EAAE,iBAAiB;IACnC;IACA,QAAQ,EAAE;IACX,CAAC;;GAEJ"}
|
package/dist/createHotkeys.js
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { useDefaultHotkeysOptions } from "./HotkeysProvider.js";
|
|
2
|
-
import { detectPlatform,
|
|
2
|
+
import { detectPlatform, getHotkeyManager, normalizeRegisterableHotkey } from "@tanstack/hotkeys";
|
|
3
3
|
import { createEffect, onCleanup } from "solid-js";
|
|
4
4
|
|
|
5
5
|
//#region src/createHotkeys.ts
|
|
@@ -63,7 +63,7 @@ function createHotkeys(hotkeys, commonOptions = {}) {
|
|
|
63
63
|
...resolvedDefOptions
|
|
64
64
|
};
|
|
65
65
|
const platform = mergedOptions.platform ?? detectPlatform();
|
|
66
|
-
const hotkeyString =
|
|
66
|
+
const hotkeyString = normalizeRegisterableHotkey(def.hotkey, platform);
|
|
67
67
|
const resolvedTarget = "target" in mergedOptions ? mergedOptions.target ?? null : typeof document !== "undefined" ? document : null;
|
|
68
68
|
if (!resolvedTarget) continue;
|
|
69
69
|
const registrationKey = `${i}:${hotkeyString}`;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"createHotkeys.js","names":[],"sources":["../src/createHotkeys.ts"],"sourcesContent":["import { createEffect, onCleanup } from 'solid-js'\nimport {\n detectPlatform,\n
|
|
1
|
+
{"version":3,"file":"createHotkeys.js","names":[],"sources":["../src/createHotkeys.ts"],"sourcesContent":["import { createEffect, onCleanup } from 'solid-js'\nimport {\n detectPlatform,\n getHotkeyManager,\n normalizeRegisterableHotkey,\n} from '@tanstack/hotkeys'\nimport { useDefaultHotkeysOptions } from './HotkeysProvider'\nimport type { CreateHotkeyOptions } from './createHotkey'\nimport type {\n Hotkey,\n HotkeyCallback,\n HotkeyRegistrationHandle,\n RegisterableHotkey,\n} from '@tanstack/hotkeys'\n\n/**\n * A single hotkey definition for use with `createHotkeys`.\n */\nexport interface CreateHotkeyDefinition {\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?: CreateHotkeyOptions\n}\n\n/**\n * SolidJS primitive 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.\n *\n * Options are merged in this order:\n * HotkeysProvider defaults < commonOptions < per-definition options\n *\n * @param hotkeys - Array of hotkey definitions, or accessor returning them\n * @param commonOptions - Shared options applied to all hotkeys, or accessor\n *\n * @example\n * ```tsx\n * function Editor() {\n * createHotkeys([\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(props) {\n * createHotkeys(\n * () => props.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 createHotkeys(\n hotkeys:\n | Array<CreateHotkeyDefinition>\n | (() => Array<CreateHotkeyDefinition>),\n commonOptions: CreateHotkeyOptions | (() => CreateHotkeyOptions) = {},\n): void {\n type RegistrationRecord = {\n handle: HotkeyRegistrationHandle\n target: Document | HTMLElement | Window\n }\n\n const defaultOptions = useDefaultHotkeysOptions()\n const manager = getHotkeyManager()\n\n const registrations = new Map<string, RegistrationRecord>()\n\n // Clean up only when this component/scope disposes — not before every effect\n // re-run. An inner `onCleanup` inside `createEffect` runs whenever reactive\n // deps change (e.g. dynamic hotkey list), which unregistered every hotkey and\n // re-registered them, flooding the manager store and could freeze the tab.\n onCleanup(() => {\n for (const { handle } of registrations.values()) {\n if (handle.isActive) {\n handle.unregister()\n }\n }\n registrations.clear()\n })\n\n createEffect(() => {\n const resolvedHotkeys = typeof hotkeys === 'function' ? hotkeys() : hotkeys\n const resolvedCommonOptions =\n typeof commonOptions === 'function' ? commonOptions() : commonOptions\n\n const nextKeys = new Set<string>()\n const prepared: Array<{\n registrationKey: string\n def: CreateHotkeyDefinition\n mergedOptions: CreateHotkeyOptions\n hotkeyString: Hotkey\n resolvedTarget: Document | HTMLElement | Window\n }> = []\n\n for (let i = 0; i < resolvedHotkeys.length; i++) {\n const def = resolvedHotkeys[i]!\n const resolvedDefOptions = def.options ?? {}\n\n const mergedOptions = {\n ...defaultOptions.hotkey,\n ...resolvedCommonOptions,\n ...resolvedDefOptions,\n } as CreateHotkeyOptions\n\n const platform = mergedOptions.platform ?? detectPlatform()\n const hotkeyString = normalizeRegisterableHotkey(def.hotkey, platform)\n\n const resolvedTarget =\n 'target' in mergedOptions\n ? (mergedOptions.target ?? null)\n : typeof document !== 'undefined'\n ? document\n : null\n\n if (!resolvedTarget) {\n continue\n }\n\n const registrationKey = `${i}:${hotkeyString}`\n nextKeys.add(registrationKey)\n prepared.push({\n registrationKey,\n def,\n mergedOptions,\n hotkeyString,\n resolvedTarget,\n })\n }\n\n // Drop stale keys first so list index shifts don't briefly double-register\n // the same hotkey+target (conflictBehavior: 'warn' + devtools can loop).\n for (const [key, record] of [...registrations.entries()]) {\n if (!nextKeys.has(key)) {\n if (record.handle.isActive) {\n record.handle.unregister()\n }\n registrations.delete(key)\n }\n }\n\n for (const p of prepared) {\n const existing = registrations.get(p.registrationKey)\n if (existing?.handle.isActive && existing.target === p.resolvedTarget) {\n existing.handle.callback = p.def.callback\n const { target: _target, ...optionsWithoutTarget } = p.mergedOptions\n existing.handle.setOptions(optionsWithoutTarget)\n continue\n }\n\n if (existing) {\n if (existing.handle.isActive) {\n existing.handle.unregister()\n }\n registrations.delete(p.registrationKey)\n }\n\n const { target: _target, ...optionsWithoutTarget } = p.mergedOptions\n const handle = manager.register(p.hotkeyString, p.def.callback, {\n ...optionsWithoutTarget,\n target: p.resolvedTarget,\n })\n registrations.set(p.registrationKey, {\n handle,\n target: p.resolvedTarget,\n })\n }\n })\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiEA,SAAgB,cACd,SAGA,gBAAmE,EAAE,EAC/D;CAMN,MAAM,iBAAiB,0BAA0B;CACjD,MAAM,UAAU,kBAAkB;CAElC,MAAM,gCAAgB,IAAI,KAAiC;AAM3D,iBAAgB;AACd,OAAK,MAAM,EAAE,YAAY,cAAc,QAAQ,CAC7C,KAAI,OAAO,SACT,QAAO,YAAY;AAGvB,gBAAc,OAAO;GACrB;AAEF,oBAAmB;EACjB,MAAM,kBAAkB,OAAO,YAAY,aAAa,SAAS,GAAG;EACpE,MAAM,wBACJ,OAAO,kBAAkB,aAAa,eAAe,GAAG;EAE1D,MAAM,2BAAW,IAAI,KAAa;EAClC,MAAM,WAMD,EAAE;AAEP,OAAK,IAAI,IAAI,GAAG,IAAI,gBAAgB,QAAQ,KAAK;GAC/C,MAAM,MAAM,gBAAgB;GAC5B,MAAM,qBAAqB,IAAI,WAAW,EAAE;GAE5C,MAAM,gBAAgB;IACpB,GAAG,eAAe;IAClB,GAAG;IACH,GAAG;IACJ;GAED,MAAM,WAAW,cAAc,YAAY,gBAAgB;GAC3D,MAAM,eAAe,4BAA4B,IAAI,QAAQ,SAAS;GAEtE,MAAM,iBACJ,YAAY,gBACP,cAAc,UAAU,OACzB,OAAO,aAAa,cAClB,WACA;AAER,OAAI,CAAC,eACH;GAGF,MAAM,kBAAkB,GAAG,EAAE,GAAG;AAChC,YAAS,IAAI,gBAAgB;AAC7B,YAAS,KAAK;IACZ;IACA;IACA;IACA;IACA;IACD,CAAC;;AAKJ,OAAK,MAAM,CAAC,KAAK,WAAW,CAAC,GAAG,cAAc,SAAS,CAAC,CACtD,KAAI,CAAC,SAAS,IAAI,IAAI,EAAE;AACtB,OAAI,OAAO,OAAO,SAChB,QAAO,OAAO,YAAY;AAE5B,iBAAc,OAAO,IAAI;;AAI7B,OAAK,MAAM,KAAK,UAAU;GACxB,MAAM,WAAW,cAAc,IAAI,EAAE,gBAAgB;AACrD,OAAI,UAAU,OAAO,YAAY,SAAS,WAAW,EAAE,gBAAgB;AACrE,aAAS,OAAO,WAAW,EAAE,IAAI;IACjC,MAAM,EAAE,QAAQ,SAAS,GAAG,yBAAyB,EAAE;AACvD,aAAS,OAAO,WAAW,qBAAqB;AAChD;;AAGF,OAAI,UAAU;AACZ,QAAI,SAAS,OAAO,SAClB,UAAS,OAAO,YAAY;AAE9B,kBAAc,OAAO,EAAE,gBAAgB;;GAGzC,MAAM,EAAE,QAAQ,SAAS,GAAG,yBAAyB,EAAE;GACvD,MAAM,SAAS,QAAQ,SAAS,EAAE,cAAc,EAAE,IAAI,UAAU;IAC9D,GAAG;IACH,QAAQ,EAAE;IACX,CAAC;AACF,iBAAc,IAAI,EAAE,iBAAiB;IACnC;IACA,QAAQ,EAAE;IACX,CAAC;;GAEJ"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@tanstack/solid-hotkeys",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.8.0",
|
|
4
4
|
"description": "SolidJS adapter for TanStack Hotkeys",
|
|
5
5
|
"author": "Tanner Linsley",
|
|
6
6
|
"license": "MIT",
|
|
@@ -43,7 +43,7 @@
|
|
|
43
43
|
],
|
|
44
44
|
"dependencies": {
|
|
45
45
|
"@tanstack/solid-store": "^0.9.2",
|
|
46
|
-
"@tanstack/hotkeys": "0.
|
|
46
|
+
"@tanstack/hotkeys": "0.6.0"
|
|
47
47
|
},
|
|
48
48
|
"devDependencies": {
|
|
49
49
|
"@solidjs/testing-library": "^0.8.10",
|
package/src/createHotkey.ts
CHANGED
|
@@ -1,9 +1,8 @@
|
|
|
1
1
|
import { createEffect, onCleanup } from 'solid-js'
|
|
2
2
|
import {
|
|
3
3
|
detectPlatform,
|
|
4
|
-
formatHotkey,
|
|
5
4
|
getHotkeyManager,
|
|
6
|
-
|
|
5
|
+
normalizeRegisterableHotkey,
|
|
7
6
|
} from '@tanstack/hotkeys'
|
|
8
7
|
import { useDefaultHotkeysOptions } from './HotkeysProvider'
|
|
9
8
|
import type {
|
|
@@ -113,12 +112,7 @@ export function createHotkey(
|
|
|
113
112
|
|
|
114
113
|
// Normalize to hotkey string
|
|
115
114
|
const platform = mergedOptions.platform ?? detectPlatform()
|
|
116
|
-
const hotkeyString
|
|
117
|
-
typeof resolvedHotkey === 'string'
|
|
118
|
-
? resolvedHotkey
|
|
119
|
-
: (formatHotkey(
|
|
120
|
-
rawHotkeyToParsedHotkey(resolvedHotkey, platform),
|
|
121
|
-
) as Hotkey)
|
|
115
|
+
const hotkeyString = normalizeRegisterableHotkey(resolvedHotkey, platform)
|
|
122
116
|
|
|
123
117
|
// Resolve target: when explicitly provided (even as null), use it and skip if null.
|
|
124
118
|
// When not provided, default to document. Matches React's ref handling.
|
package/src/createHotkeys.ts
CHANGED
|
@@ -1,9 +1,8 @@
|
|
|
1
1
|
import { createEffect, onCleanup } from 'solid-js'
|
|
2
2
|
import {
|
|
3
3
|
detectPlatform,
|
|
4
|
-
formatHotkey,
|
|
5
4
|
getHotkeyManager,
|
|
6
|
-
|
|
5
|
+
normalizeRegisterableHotkey,
|
|
7
6
|
} from '@tanstack/hotkeys'
|
|
8
7
|
import { useDefaultHotkeysOptions } from './HotkeysProvider'
|
|
9
8
|
import type { CreateHotkeyOptions } from './createHotkey'
|
|
@@ -118,12 +117,7 @@ export function createHotkeys(
|
|
|
118
117
|
} as CreateHotkeyOptions
|
|
119
118
|
|
|
120
119
|
const platform = mergedOptions.platform ?? detectPlatform()
|
|
121
|
-
const hotkeyString
|
|
122
|
-
typeof def.hotkey === 'string'
|
|
123
|
-
? def.hotkey
|
|
124
|
-
: (formatHotkey(
|
|
125
|
-
rawHotkeyToParsedHotkey(def.hotkey, platform),
|
|
126
|
-
) as Hotkey)
|
|
120
|
+
const hotkeyString = normalizeRegisterableHotkey(def.hotkey, platform)
|
|
127
121
|
|
|
128
122
|
const resolvedTarget =
|
|
129
123
|
'target' in mergedOptions
|