@tanstack/solid-hotkeys 0.14.4 → 0.15.0

package/README.md

@@ -51,7 +51,7 @@
 # TanStack Hotkeys
 
 > [!NOTE]
-> TanStack Hotkeys is alpha. We are actively developing the library and are open to feedback and contributions.
+> TanStack Hotkeys is in beta. We are actively developing the library and are open to feedback and contributions.
 
 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.
 

package/dist/HotkeysProvider.d.ts

@@ -1,6 +1,7 @@
 import { CreateHotkeyCommonOptions } from "./createHotkey.js";
 import { AppHotkeys, AppHotkeysStore, CustomHotkeys, HotkeyChordRecorderOptions, HotkeySequenceRecorderOptions } from "@tanstack/hotkeys";
 import { JSX, ParentComponent } from "solid-js";
+import { HotkeysProviderScopeProps } from "@tanstack/hotkeys/adapter";
 //#region src/HotkeysProvider.d.ts
 export interface HotkeysProviderOptions {
   /**
@@ -13,9 +14,12 @@ export interface HotkeysProviderOptions {
 }
 interface HotkeysContextValue {
   readonly appHotkeysStore: AppHotkeysStore | null;
+  /** Merged with every ancestor provider's defaults, including `hotkey.scope`. */
   readonly defaultOptions: HotkeysProviderOptions;
+  /** Whether this provider and every ancestor are enabled. */
+  readonly enabled: boolean;
 }
-export interface HotkeysProviderProps {
+export interface HotkeysProviderProps extends HotkeysProviderScopeProps {
   children: JSX.Element;
   /**
    * Every app hotkey, from `defineAppHotkeys`. Read when the provider is
@@ -29,11 +33,16 @@ export interface HotkeysProviderProps {
   customHotkeys?: CustomHotkeys | null;
   /** Called with the custom hotkeys after every change, ready to save. */
   onCustomHotkeysChange?: (customHotkeys: CustomHotkeys) => void;
+  /** Merged with the parent provider's defaults. */
   defaultOptions?: HotkeysProviderOptions;
 }
 /**
  * Provides default options, app hotkeys, and the user's custom hotkeys.
  *
+ * Nest providers to create hotkey scopes. A nested provider inherits app
+ * hotkeys and merges default options. With `scope`, its hotkeys fire only
+ * while it is mounted and enabled; with `exclusive`, only its hotkeys fire.
+ *
  * @example
  * ```tsx
  * <HotkeysProvider
@@ -46,6 +55,13 @@ export interface HotkeysProviderProps {
  *   <App />
  * </HotkeysProvider>
  * ```
+ *
+ * @example
+ * ```tsx
+ * <HotkeysProvider scope="edit-dialog" exclusive={{ allow: ['global'] }}>
+ *   <DialogBody />
+ * </HotkeysProvider>
+ * ```
  */
 export declare const HotkeysProvider: ParentComponent<HotkeysProviderProps>;
 export declare function useHotkeysContext(): HotkeysContextValue | null;

package/dist/HotkeysProvider.js

@@ -1,6 +1,7 @@
 import { AppHotkeysStore, publishAppHotkeysStore } from "@tanstack/hotkeys";
 import { createComponent } from "solid-js/web";
-import { createContext, createEffect, onCleanup, onMount, useContext } from "solid-js";
+import { createContext, createEffect, createMemo, onCleanup, onMount, useContext } from "solid-js";
+import { activateHotkeysProviderScope, getHotkeysProviderScopeKey, mergeHotkeysProviderDefaults } from "@tanstack/hotkeys/adapter";
 
 //#region src/HotkeysProvider.tsx
 const HotkeysContext = createContext(null);
@@ -8,6 +9,10 @@ const DEFAULT_OPTIONS = {};
 /**
 * Provides default options, app hotkeys, and the user's custom hotkeys.
 *
+* Nest providers to create hotkey scopes. A nested provider inherits app
+* hotkeys and merges default options. With `scope`, its hotkeys fire only
+* while it is mounted and enabled; with `exclusive`, only its hotkeys fire.
+*
 * @example
 * ```tsx
 * <HotkeysProvider
@@ -20,8 +25,16 @@ const DEFAULT_OPTIONS = {};
 *   <App />
 * </HotkeysProvider>
 * ```
+*
+* @example
+* ```tsx
+* <HotkeysProvider scope="edit-dialog" exclusive={{ allow: ['global'] }}>
+*   <DialogBody />
+* </HotkeysProvider>
+* ```
 */
 const HotkeysProvider = (props) => {
+	const parent = useContext(HotkeysContext);
 	const store = props.appHotkeys ? new AppHotkeysStore(props.appHotkeys, {
 		customHotkeys: props.customHotkeys,
 		onCustomHotkeysChange: (custom) => props.onCustomHotkeysChange?.(custom)
@@ -32,10 +45,25 @@ const HotkeysProvider = (props) => {
 	onMount(() => {
 		if (store) onCleanup(publishAppHotkeysStore(store));
 	});
+	const active = () => (parent?.enabled ?? true) && props.enabled !== false;
+	const defaultOptions = createMemo(() => mergeHotkeysProviderDefaults(parent?.defaultOptions, props.defaultOptions, props.scope));
+	const scopeKey = createMemo(() => getHotkeysProviderScopeKey({
+		scope: props.scope,
+		exclusive: props.exclusive,
+		active: active(),
+		parent: parent?.defaultOptions.hotkey?.scope
+	}));
+	createEffect(() => {
+		const key = scopeKey();
+		if (key) onCleanup(activateHotkeysProviderScope(key));
+	});
 	const contextValue = {
-		appHotkeysStore: store,
+		appHotkeysStore: store ?? parent?.appHotkeysStore ?? null,
 		get defaultOptions() {
-			return props.defaultOptions ?? DEFAULT_OPTIONS;
+			return defaultOptions();
+		},
+		get enabled() {
+			return active();
 		}
 	};
 	return createComponent(HotkeysContext.Provider, {

package/dist/appHotkeys.d.ts

@@ -6,8 +6,8 @@ import { AppHotkey, AppHotkeyListItem, CustomHotkeys, Hotkey, RegisteredAppHotke
  *
  * @example
  * ```tsx
- * const hotkeys = useAppHotkeys()
- * createHotkey(() => hotkeys()['doc.save'], () => save())
+ * const appHotkeys = useAppHotkeys()
+ * createHotkey(() => appHotkeys()['doc.save'], () => save())
  * ```
  */
 export declare function useAppHotkeys(): () => RegisteredAppHotkeys;

package/dist/appHotkeys.js

@@ -17,8 +17,8 @@ function useRequiredStore(name) {
 *
 * @example
 * ```tsx
-* const hotkeys = useAppHotkeys()
-* createHotkey(() => hotkeys()['doc.save'], () => save())
+* const appHotkeys = useAppHotkeys()
+* createHotkey(() => appHotkeys()['doc.save'], () => save())
 * ```
 */
 function useAppHotkeys() {

package/dist/createHotkey.d.ts

@@ -1,4 +1,4 @@
-import { AppHotkey, HotkeyCallback, RegisterableHotkey, Target } from "@tanstack/hotkeys";
+import { AppHotkey, HotkeyCallback, HotkeyCallbackContextFor, RegisterableHotkey, Target } from "@tanstack/hotkeys";
 import { AdapterAppHotkeyOptions, AdapterChordOptions, AdapterCommonOptions, AdapterHotkeyOptions, AdapterOptionsFor, AdapterSequenceOptions } from "@tanstack/hotkeys/adapter";
 //#region src/createHotkey.d.ts
 /**
@@ -38,5 +38,5 @@ type MaybeAccessor<T> = T | (() => T);
  * ```
  */
 export declare function createHotkey<T extends AppHotkey>(hotkey: MaybeAccessor<T>, callback: HotkeyCallback, options?: MaybeAccessor<CreateAppHotkeyOptions<T>>): void;
-export declare function createHotkey<T extends RegisterableHotkey>(hotkey: MaybeAccessor<T>, callback: HotkeyCallback, options?: MaybeAccessor<CreateHotkeyOptionsFor<T>>): void;
+export declare function createHotkey<const T extends RegisterableHotkey>(hotkey: MaybeAccessor<T>, callback: HotkeyCallback<HotkeyCallbackContextFor<T>>, options?: MaybeAccessor<CreateHotkeyOptionsFor<T>>): void;
 //#endregion

package/dist/createHotkeyRecorder.d.ts

@@ -27,7 +27,7 @@ export interface SolidHotkeyRecorder<THotkey extends Hotkey = Hotkey> {
  * @example
  * ```tsx
  * const recorder = createHotkeyRecorder({ onRecord: setShortcut })
- * const sequenceRecorder = createHotkeyRecorder({ maxSteps: 3, onRecord: setShortcut })
+ * const sequenceRecorder = createHotkeyRecorder({ maxSteps: Infinity, onRecord: setShortcut })
  * ```
  */
 export declare function createHotkeyRecorder(options: HotkeyChordRecorderOptions): SolidHotkeyRecorder<HotkeyChord>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/solid-hotkeys",
-  "version": "0.14.4",
+  "version": "0.15.0",
   "description": "SolidJS adapter for TanStack Hotkeys",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -36,7 +36,7 @@
     "dist"
   ],
   "dependencies": {
-    "@tanstack/hotkeys": "0.15.0",
+    "@tanstack/hotkeys": "0.16.0",
     "@tanstack/solid-store": "^0.11.2"
   },
   "devDependencies": {