@tanstack/solid-hotkeys 0.4.1 → 0.5.0

package/README.md

@@ -58,7 +58,7 @@ Type-safe keyboard shortcuts for the web. Template-string bindings, parsed objec
 > - [**Solid Hotkeys**](https://tanstack.com/hotkeys/latest/docs/framework/solid/reference)
 > - [**Angular Hotkeys**](https://tanstack.com/hotkeys/latest/docs/framework/angular/reference)
 > - [**Vue Hotkeys**](https://tanstack.com/hotkeys/latest/docs/framework/vue/reference)
-> - Svelte Hotkeys – needs a contributor!
+> - [**Svelte Hotkeys**](https://tanstack.com/hotkeys/latest/docs/framework/svelte/reference)
 
 ## Get Involved
 

package/dist/createHotkeys.cjs

@@ -0,0 +1,110 @@
+const require_HotkeysProvider = require('./HotkeysProvider.cjs');
+let _tanstack_hotkeys = require("@tanstack/hotkeys");
+let solid_js = require("solid-js");
+
+//#region src/createHotkeys.ts
+/**
+* SolidJS primitive 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.
+*
+* Options are merged in this order:
+* HotkeysProvider defaults < commonOptions < per-definition options
+*
+* @param hotkeys - Array of hotkey definitions, or accessor returning them
+* @param commonOptions - Shared options applied to all hotkeys, or accessor
+*
+* @example
+* ```tsx
+* function Editor() {
+*   createHotkeys([
+*     { hotkey: 'Mod+S', callback: () => save() },
+*     { hotkey: 'Mod+Z', callback: () => undo() },
+*     { hotkey: 'Escape', callback: () => close() },
+*   ])
+* }
+* ```
+*
+* @example
+* ```tsx
+* function MenuShortcuts(props) {
+*   createHotkeys(
+*     () => props.items.map((item) => ({
+*       hotkey: item.shortcut,
+*       callback: item.action,
+*       options: { enabled: item.enabled },
+*     })),
+*     { preventDefault: true },
+*   )
+* }
+* ```
+*/
+function createHotkeys(hotkeys, commonOptions = {}) {
+	const defaultOptions = require_HotkeysProvider.useDefaultHotkeysOptions();
+	const manager = (0, _tanstack_hotkeys.getHotkeyManager)();
+	const registrations = /* @__PURE__ */ new Map();
+	(0, solid_js.onCleanup)(() => {
+		for (const { handle } of registrations.values()) if (handle.isActive) handle.unregister();
+		registrations.clear();
+	});
+	(0, solid_js.createEffect)(() => {
+		const resolvedHotkeys = typeof hotkeys === "function" ? hotkeys() : hotkeys;
+		const resolvedCommonOptions = typeof commonOptions === "function" ? commonOptions() : commonOptions;
+		const nextKeys = /* @__PURE__ */ new Set();
+		const prepared = [];
+		for (let i = 0; i < resolvedHotkeys.length; i++) {
+			const def = resolvedHotkeys[i];
+			const resolvedDefOptions = def.options ?? {};
+			const mergedOptions = {
+				...defaultOptions.hotkey,
+				...resolvedCommonOptions,
+				...resolvedDefOptions
+			};
+			const platform = mergedOptions.platform ?? (0, _tanstack_hotkeys.detectPlatform)();
+			const hotkeyString = typeof def.hotkey === "string" ? def.hotkey : (0, _tanstack_hotkeys.formatHotkey)((0, _tanstack_hotkeys.rawHotkeyToParsedHotkey)(def.hotkey, platform));
+			const resolvedTarget = "target" in mergedOptions ? mergedOptions.target ?? null : typeof document !== "undefined" ? document : null;
+			if (!resolvedTarget) continue;
+			const registrationKey = `${i}:${hotkeyString}`;
+			nextKeys.add(registrationKey);
+			prepared.push({
+				registrationKey,
+				def,
+				mergedOptions,
+				hotkeyString,
+				resolvedTarget
+			});
+		}
+		for (const [key, record] of [...registrations.entries()]) if (!nextKeys.has(key)) {
+			if (record.handle.isActive) record.handle.unregister();
+			registrations.delete(key);
+		}
+		for (const p of prepared) {
+			const existing = registrations.get(p.registrationKey);
+			if (existing?.handle.isActive && existing.target === p.resolvedTarget) {
+				existing.handle.callback = p.def.callback;
+				const { target: _target, ...optionsWithoutTarget } = p.mergedOptions;
+				existing.handle.setOptions(optionsWithoutTarget);
+				continue;
+			}
+			if (existing) {
+				if (existing.handle.isActive) existing.handle.unregister();
+				registrations.delete(p.registrationKey);
+			}
+			const { target: _target, ...optionsWithoutTarget } = p.mergedOptions;
+			const handle = manager.register(p.hotkeyString, p.def.callback, {
+				...optionsWithoutTarget,
+				target: p.resolvedTarget
+			});
+			registrations.set(p.registrationKey, {
+				handle,
+				target: p.resolvedTarget
+			});
+		}
+	});
+}
+
+//#endregion
+exports.createHotkeys = createHotkeys;
+//# sourceMappingURL=createHotkeys.cjs.map

package/dist/createHotkeys.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"createHotkeys.cjs","names":["useDefaultHotkeysOptions"],"sources":["../src/createHotkeys.ts"],"sourcesContent":["import { createEffect, onCleanup } from 'solid-js'\nimport {\n  detectPlatform,\n  formatHotkey,\n  getHotkeyManager,\n  rawHotkeyToParsedHotkey,\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: Hotkey =\n        typeof def.hotkey === 'string'\n          ? def.hotkey\n          : (formatHotkey(\n              rawHotkeyToParsedHotkey(def.hotkey, platform),\n            ) as Hotkey)\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":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkEA,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,eACJ,OAAO,IAAI,WAAW,WAClB,IAAI,4FAEsB,IAAI,QAAQ,SAAS,CAC9C;GAEP,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.d.cts

@@ -0,0 +1,57 @@
+import { CreateHotkeyOptions } from "./createHotkey.cjs";
+import { HotkeyCallback, RegisterableHotkey } from "@tanstack/hotkeys";
+
+//#region src/createHotkeys.d.ts
+/**
+ * A single hotkey definition for use with `createHotkeys`.
+ */
+interface CreateHotkeyDefinition {
+  /** 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?: CreateHotkeyOptions;
+}
+/**
+ * SolidJS primitive 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.
+ *
+ * Options are merged in this order:
+ * HotkeysProvider defaults < commonOptions < per-definition options
+ *
+ * @param hotkeys - Array of hotkey definitions, or accessor returning them
+ * @param commonOptions - Shared options applied to all hotkeys, or accessor
+ *
+ * @example
+ * ```tsx
+ * function Editor() {
+ *   createHotkeys([
+ *     { hotkey: 'Mod+S', callback: () => save() },
+ *     { hotkey: 'Mod+Z', callback: () => undo() },
+ *     { hotkey: 'Escape', callback: () => close() },
+ *   ])
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * function MenuShortcuts(props) {
+ *   createHotkeys(
+ *     () => props.items.map((item) => ({
+ *       hotkey: item.shortcut,
+ *       callback: item.action,
+ *       options: { enabled: item.enabled },
+ *     })),
+ *     { preventDefault: true },
+ *   )
+ * }
+ * ```
+ */
+declare function createHotkeys(hotkeys: Array<CreateHotkeyDefinition> | (() => Array<CreateHotkeyDefinition>), commonOptions?: CreateHotkeyOptions | (() => CreateHotkeyOptions)): void;
+//#endregion
+export { CreateHotkeyDefinition, createHotkeys };
+//# sourceMappingURL=createHotkeys.d.cts.map

package/dist/createHotkeys.d.ts

@@ -0,0 +1,57 @@
+import { CreateHotkeyOptions } from "./createHotkey.js";
+import { HotkeyCallback, RegisterableHotkey } from "@tanstack/hotkeys";
+
+//#region src/createHotkeys.d.ts
+/**
+ * A single hotkey definition for use with `createHotkeys`.
+ */
+interface CreateHotkeyDefinition {
+  /** 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?: CreateHotkeyOptions;
+}
+/**
+ * SolidJS primitive 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.
+ *
+ * Options are merged in this order:
+ * HotkeysProvider defaults < commonOptions < per-definition options
+ *
+ * @param hotkeys - Array of hotkey definitions, or accessor returning them
+ * @param commonOptions - Shared options applied to all hotkeys, or accessor
+ *
+ * @example
+ * ```tsx
+ * function Editor() {
+ *   createHotkeys([
+ *     { hotkey: 'Mod+S', callback: () => save() },
+ *     { hotkey: 'Mod+Z', callback: () => undo() },
+ *     { hotkey: 'Escape', callback: () => close() },
+ *   ])
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * function MenuShortcuts(props) {
+ *   createHotkeys(
+ *     () => props.items.map((item) => ({
+ *       hotkey: item.shortcut,
+ *       callback: item.action,
+ *       options: { enabled: item.enabled },
+ *     })),
+ *     { preventDefault: true },
+ *   )
+ * }
+ * ```
+ */
+declare function createHotkeys(hotkeys: Array<CreateHotkeyDefinition> | (() => Array<CreateHotkeyDefinition>), commonOptions?: CreateHotkeyOptions | (() => CreateHotkeyOptions)): void;
+//#endregion
+export { CreateHotkeyDefinition, createHotkeys };
+//# sourceMappingURL=createHotkeys.d.ts.map

package/dist/createHotkeys.js

@@ -0,0 +1,110 @@
+import { useDefaultHotkeysOptions } from "./HotkeysProvider.js";
+import { detectPlatform, formatHotkey, getHotkeyManager, rawHotkeyToParsedHotkey } from "@tanstack/hotkeys";
+import { createEffect, onCleanup } from "solid-js";
+
+//#region src/createHotkeys.ts
+/**
+* SolidJS primitive 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.
+*
+* Options are merged in this order:
+* HotkeysProvider defaults < commonOptions < per-definition options
+*
+* @param hotkeys - Array of hotkey definitions, or accessor returning them
+* @param commonOptions - Shared options applied to all hotkeys, or accessor
+*
+* @example
+* ```tsx
+* function Editor() {
+*   createHotkeys([
+*     { hotkey: 'Mod+S', callback: () => save() },
+*     { hotkey: 'Mod+Z', callback: () => undo() },
+*     { hotkey: 'Escape', callback: () => close() },
+*   ])
+* }
+* ```
+*
+* @example
+* ```tsx
+* function MenuShortcuts(props) {
+*   createHotkeys(
+*     () => props.items.map((item) => ({
+*       hotkey: item.shortcut,
+*       callback: item.action,
+*       options: { enabled: item.enabled },
+*     })),
+*     { preventDefault: true },
+*   )
+* }
+* ```
+*/
+function createHotkeys(hotkeys, commonOptions = {}) {
+	const defaultOptions = useDefaultHotkeysOptions();
+	const manager = getHotkeyManager();
+	const registrations = /* @__PURE__ */ new Map();
+	onCleanup(() => {
+		for (const { handle } of registrations.values()) if (handle.isActive) handle.unregister();
+		registrations.clear();
+	});
+	createEffect(() => {
+		const resolvedHotkeys = typeof hotkeys === "function" ? hotkeys() : hotkeys;
+		const resolvedCommonOptions = typeof commonOptions === "function" ? commonOptions() : commonOptions;
+		const nextKeys = /* @__PURE__ */ new Set();
+		const prepared = [];
+		for (let i = 0; i < resolvedHotkeys.length; i++) {
+			const def = resolvedHotkeys[i];
+			const resolvedDefOptions = def.options ?? {};
+			const mergedOptions = {
+				...defaultOptions.hotkey,
+				...resolvedCommonOptions,
+				...resolvedDefOptions
+			};
+			const platform = mergedOptions.platform ?? detectPlatform();
+			const hotkeyString = typeof def.hotkey === "string" ? def.hotkey : formatHotkey(rawHotkeyToParsedHotkey(def.hotkey, platform));
+			const resolvedTarget = "target" in mergedOptions ? mergedOptions.target ?? null : typeof document !== "undefined" ? document : null;
+			if (!resolvedTarget) continue;
+			const registrationKey = `${i}:${hotkeyString}`;
+			nextKeys.add(registrationKey);
+			prepared.push({
+				registrationKey,
+				def,
+				mergedOptions,
+				hotkeyString,
+				resolvedTarget
+			});
+		}
+		for (const [key, record] of [...registrations.entries()]) if (!nextKeys.has(key)) {
+			if (record.handle.isActive) record.handle.unregister();
+			registrations.delete(key);
+		}
+		for (const p of prepared) {
+			const existing = registrations.get(p.registrationKey);
+			if (existing?.handle.isActive && existing.target === p.resolvedTarget) {
+				existing.handle.callback = p.def.callback;
+				const { target: _target, ...optionsWithoutTarget } = p.mergedOptions;
+				existing.handle.setOptions(optionsWithoutTarget);
+				continue;
+			}
+			if (existing) {
+				if (existing.handle.isActive) existing.handle.unregister();
+				registrations.delete(p.registrationKey);
+			}
+			const { target: _target, ...optionsWithoutTarget } = p.mergedOptions;
+			const handle = manager.register(p.hotkeyString, p.def.callback, {
+				...optionsWithoutTarget,
+				target: p.resolvedTarget
+			});
+			registrations.set(p.registrationKey, {
+				handle,
+				target: p.resolvedTarget
+			});
+		}
+	});
+}
+
+//#endregion
+export { createHotkeys };
+//# sourceMappingURL=createHotkeys.js.map

package/dist/createHotkeys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createHotkeys.js","names":[],"sources":["../src/createHotkeys.ts"],"sourcesContent":["import { createEffect, onCleanup } from 'solid-js'\nimport {\n  detectPlatform,\n  formatHotkey,\n  getHotkeyManager,\n  rawHotkeyToParsedHotkey,\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: Hotkey =\n        typeof def.hotkey === 'string'\n          ? def.hotkey\n          : (formatHotkey(\n              rawHotkeyToParsedHotkey(def.hotkey, platform),\n            ) as Hotkey)\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":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkEA,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,eACJ,OAAO,IAAI,WAAW,WAClB,IAAI,SACH,aACC,wBAAwB,IAAI,QAAQ,SAAS,CAC9C;GAEP,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/index.cjs

@@ -1,6 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 const require_HotkeysProvider = require('./HotkeysProvider.cjs');
 const require_createHotkey = require('./createHotkey.cjs');
+const require_createHotkeys = require('./createHotkeys.cjs');
 const require_createHeldKeys = require('./createHeldKeys.cjs');
 const require_createHeldKeyCodes = require('./createHeldKeyCodes.cjs');
 const require_createKeyHold = require('./createKeyHold.cjs');
@@ -13,6 +14,7 @@ exports.createHeldKeys = require_createHeldKeys.createHeldKeys;
 exports.createHotkey = require_createHotkey.createHotkey;
 exports.createHotkeyRecorder = require_createHotkeyRecorder.createHotkeyRecorder;
 exports.createHotkeySequence = require_createHotkeySequence.createHotkeySequence;
+exports.createHotkeys = require_createHotkeys.createHotkeys;
 exports.createKeyHold = require_createKeyHold.createKeyHold;
 exports.useDefaultHotkeysOptions = require_HotkeysProvider.useDefaultHotkeysOptions;
 exports.useHotkeysContext = require_HotkeysProvider.useHotkeysContext;

package/dist/index.d.cts

@@ -1,9 +1,10 @@
 import { CreateHotkeyOptions, createHotkey } from "./createHotkey.cjs";
 import { CreateHotkeySequenceOptions, createHotkeySequence } from "./createHotkeySequence.cjs";
 import { HotkeysProvider, HotkeysProviderOptions, HotkeysProviderProps, useDefaultHotkeysOptions, useHotkeysContext } from "./HotkeysProvider.cjs";
+import { CreateHotkeyDefinition, createHotkeys } from "./createHotkeys.cjs";
 import { createHeldKeys } from "./createHeldKeys.cjs";
 import { createHeldKeyCodes } from "./createHeldKeyCodes.cjs";
 import { createKeyHold } from "./createKeyHold.cjs";
 import { SolidHotkeyRecorder, createHotkeyRecorder } from "./createHotkeyRecorder.cjs";
 export * from "@tanstack/hotkeys";
-export { CreateHotkeyOptions, CreateHotkeySequenceOptions, HotkeysProvider, HotkeysProviderOptions, HotkeysProviderProps, SolidHotkeyRecorder, createHeldKeyCodes, createHeldKeys, createHotkey, createHotkeyRecorder, createHotkeySequence, createKeyHold, useDefaultHotkeysOptions, useHotkeysContext };
+export { CreateHotkeyDefinition, CreateHotkeyOptions, CreateHotkeySequenceOptions, HotkeysProvider, HotkeysProviderOptions, HotkeysProviderProps, SolidHotkeyRecorder, createHeldKeyCodes, createHeldKeys, createHotkey, createHotkeyRecorder, createHotkeySequence, createHotkeys, createKeyHold, useDefaultHotkeysOptions, useHotkeysContext };

package/dist/index.d.ts

@@ -1,9 +1,10 @@
 import { CreateHotkeyOptions, createHotkey } from "./createHotkey.js";
 import { CreateHotkeySequenceOptions, createHotkeySequence } from "./createHotkeySequence.js";
 import { HotkeysProvider, HotkeysProviderOptions, HotkeysProviderProps, useDefaultHotkeysOptions, useHotkeysContext } from "./HotkeysProvider.js";
+import { CreateHotkeyDefinition, createHotkeys } from "./createHotkeys.js";
 import { createHeldKeys } from "./createHeldKeys.js";
 import { createHeldKeyCodes } from "./createHeldKeyCodes.js";
 import { createKeyHold } from "./createKeyHold.js";
 import { SolidHotkeyRecorder, createHotkeyRecorder } from "./createHotkeyRecorder.js";
 export * from "@tanstack/hotkeys";
-export { CreateHotkeyOptions, CreateHotkeySequenceOptions, HotkeysProvider, HotkeysProviderOptions, HotkeysProviderProps, SolidHotkeyRecorder, createHeldKeyCodes, createHeldKeys, createHotkey, createHotkeyRecorder, createHotkeySequence, createKeyHold, useDefaultHotkeysOptions, useHotkeysContext };
+export { CreateHotkeyDefinition, CreateHotkeyOptions, CreateHotkeySequenceOptions, HotkeysProvider, HotkeysProviderOptions, HotkeysProviderProps, SolidHotkeyRecorder, createHeldKeyCodes, createHeldKeys, createHotkey, createHotkeyRecorder, createHotkeySequence, createHotkeys, createKeyHold, useDefaultHotkeysOptions, useHotkeysContext };

package/dist/index.js

@@ -1,5 +1,6 @@
 import { HotkeysProvider, useDefaultHotkeysOptions, useHotkeysContext } from "./HotkeysProvider.js";
 import { createHotkey } from "./createHotkey.js";
+import { createHotkeys } from "./createHotkeys.js";
 import { createHeldKeys } from "./createHeldKeys.js";
 import { createHeldKeyCodes } from "./createHeldKeyCodes.js";
 import { createKeyHold } from "./createKeyHold.js";
@@ -8,4 +9,4 @@ import { createHotkeyRecorder } from "./createHotkeyRecorder.js";
 
 export * from "@tanstack/hotkeys"
 
-export { HotkeysProvider, createHeldKeyCodes, createHeldKeys, createHotkey, createHotkeyRecorder, createHotkeySequence, createKeyHold, useDefaultHotkeysOptions, useHotkeysContext };
+export { HotkeysProvider, createHeldKeyCodes, createHeldKeys, createHotkey, createHotkeyRecorder, createHotkeySequence, createHotkeys, createKeyHold, useDefaultHotkeysOptions, useHotkeysContext };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/solid-hotkeys",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "SolidJS adapter for TanStack Hotkeys",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -43,13 +43,13 @@
   ],
   "dependencies": {
     "@tanstack/solid-store": "^0.9.2",
-    "@tanstack/hotkeys": "0.4.1"
+    "@tanstack/hotkeys": "0.4.2"
   },
   "devDependencies": {
     "@solidjs/testing-library": "^0.8.10",
     "@testing-library/jest-dom": "^6.9.1",
     "solid-js": "^1.9.11",
-    "vite-plugin-solid": "^2.11.10"
+    "vite-plugin-solid": "^2.11.11"
   },
   "peerDependencies": {
     "solid-js": ">=1.7.0"

package/src/createHotkeys.ts

@@ -0,0 +1,188 @@
+import { createEffect, onCleanup } from 'solid-js'
+import {
+  detectPlatform,
+  formatHotkey,
+  getHotkeyManager,
+  rawHotkeyToParsedHotkey,
+} from '@tanstack/hotkeys'
+import { useDefaultHotkeysOptions } from './HotkeysProvider'
+import type { CreateHotkeyOptions } from './createHotkey'
+import type {
+  Hotkey,
+  HotkeyCallback,
+  HotkeyRegistrationHandle,
+  RegisterableHotkey,
+} from '@tanstack/hotkeys'
+
+/**
+ * A single hotkey definition for use with `createHotkeys`.
+ */
+export interface CreateHotkeyDefinition {
+  /** 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?: CreateHotkeyOptions
+}
+
+/**
+ * SolidJS primitive 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.
+ *
+ * Options are merged in this order:
+ * HotkeysProvider defaults < commonOptions < per-definition options
+ *
+ * @param hotkeys - Array of hotkey definitions, or accessor returning them
+ * @param commonOptions - Shared options applied to all hotkeys, or accessor
+ *
+ * @example
+ * ```tsx
+ * function Editor() {
+ *   createHotkeys([
+ *     { hotkey: 'Mod+S', callback: () => save() },
+ *     { hotkey: 'Mod+Z', callback: () => undo() },
+ *     { hotkey: 'Escape', callback: () => close() },
+ *   ])
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * function MenuShortcuts(props) {
+ *   createHotkeys(
+ *     () => props.items.map((item) => ({
+ *       hotkey: item.shortcut,
+ *       callback: item.action,
+ *       options: { enabled: item.enabled },
+ *     })),
+ *     { preventDefault: true },
+ *   )
+ * }
+ * ```
+ */
+export function createHotkeys(
+  hotkeys:
+    | Array<CreateHotkeyDefinition>
+    | (() => Array<CreateHotkeyDefinition>),
+  commonOptions: CreateHotkeyOptions | (() => CreateHotkeyOptions) = {},
+): void {
+  type RegistrationRecord = {
+    handle: HotkeyRegistrationHandle
+    target: Document | HTMLElement | Window
+  }
+
+  const defaultOptions = useDefaultHotkeysOptions()
+  const manager = getHotkeyManager()
+
+  const registrations = new Map<string, RegistrationRecord>()
+
+  // Clean up only when this component/scope disposes — not before every effect
+  // re-run. An inner `onCleanup` inside `createEffect` runs whenever reactive
+  // deps change (e.g. dynamic hotkey list), which unregistered every hotkey and
+  // re-registered them, flooding the manager store and could freeze the tab.
+  onCleanup(() => {
+    for (const { handle } of registrations.values()) {
+      if (handle.isActive) {
+        handle.unregister()
+      }
+    }
+    registrations.clear()
+  })
+
+  createEffect(() => {
+    const resolvedHotkeys = typeof hotkeys === 'function' ? hotkeys() : hotkeys
+    const resolvedCommonOptions =
+      typeof commonOptions === 'function' ? commonOptions() : commonOptions
+
+    const nextKeys = new Set<string>()
+    const prepared: Array<{
+      registrationKey: string
+      def: CreateHotkeyDefinition
+      mergedOptions: CreateHotkeyOptions
+      hotkeyString: Hotkey
+      resolvedTarget: Document | HTMLElement | Window
+    }> = []
+
+    for (let i = 0; i < resolvedHotkeys.length; i++) {
+      const def = resolvedHotkeys[i]!
+      const resolvedDefOptions = def.options ?? {}
+
+      const mergedOptions = {
+        ...defaultOptions.hotkey,
+        ...resolvedCommonOptions,
+        ...resolvedDefOptions,
+      } as CreateHotkeyOptions
+
+      const platform = mergedOptions.platform ?? detectPlatform()
+      const hotkeyString: Hotkey =
+        typeof def.hotkey === 'string'
+          ? def.hotkey
+          : (formatHotkey(
+              rawHotkeyToParsedHotkey(def.hotkey, platform),
+            ) as Hotkey)
+
+      const resolvedTarget =
+        'target' in mergedOptions
+          ? (mergedOptions.target ?? null)
+          : typeof document !== 'undefined'
+            ? document
+            : null
+
+      if (!resolvedTarget) {
+        continue
+      }
+
+      const registrationKey = `${i}:${hotkeyString}`
+      nextKeys.add(registrationKey)
+      prepared.push({
+        registrationKey,
+        def,
+        mergedOptions,
+        hotkeyString,
+        resolvedTarget,
+      })
+    }
+
+    // Drop stale keys first so list index shifts don't briefly double-register
+    // the same hotkey+target (conflictBehavior: 'warn' + devtools can loop).
+    for (const [key, record] of [...registrations.entries()]) {
+      if (!nextKeys.has(key)) {
+        if (record.handle.isActive) {
+          record.handle.unregister()
+        }
+        registrations.delete(key)
+      }
+    }
+
+    for (const p of prepared) {
+      const existing = registrations.get(p.registrationKey)
+      if (existing?.handle.isActive && existing.target === p.resolvedTarget) {
+        existing.handle.callback = p.def.callback
+        const { target: _target, ...optionsWithoutTarget } = p.mergedOptions
+        existing.handle.setOptions(optionsWithoutTarget)
+        continue
+      }
+
+      if (existing) {
+        if (existing.handle.isActive) {
+          existing.handle.unregister()
+        }
+        registrations.delete(p.registrationKey)
+      }
+
+      const { target: _target, ...optionsWithoutTarget } = p.mergedOptions
+      const handle = manager.register(p.hotkeyString, p.def.callback, {
+        ...optionsWithoutTarget,
+        target: p.resolvedTarget,
+      })
+      registrations.set(p.registrationKey, {
+        handle,
+        target: p.resolvedTarget,
+      })
+    }
+  })
+}

package/src/index.ts

@@ -6,6 +6,7 @@ export * from './HotkeysProvider'
 
 // SolidJS-specific primitives
 export * from './createHotkey'
+export * from './createHotkeys'
 export * from './createHeldKeys'
 export * from './createHeldKeyCodes'
 export * from './createKeyHold'