@tanstack/react-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 { UseHotkeyCommonOptions } from "./useHotkey.js";
 import { AppHotkeys, AppHotkeysStore, CustomHotkeys, HotkeyChordRecorderOptions, HotkeySequenceRecorderOptions } from "@tanstack/hotkeys";
 import React, { ReactNode } from "react";
+import { HotkeysProviderScopeProps } from "@tanstack/hotkeys/adapter";
 //#region src/HotkeysProvider.d.ts
 export interface HotkeysProviderOptions {
   /**
@@ -13,9 +14,12 @@ export interface HotkeysProviderOptions {
 }
 interface HotkeysContextValue {
   appHotkeysStore: AppHotkeysStore | null;
+  /** Merged with every ancestor provider's defaults, including `hotkey.scope`. */
   defaultOptions: HotkeysProviderOptions;
+  /** Whether this provider and every ancestor are enabled. */
+  enabled: boolean;
 }
-export interface HotkeysProviderProps<T extends AppHotkeys = AppHotkeys> {
+export interface HotkeysProviderProps<T extends AppHotkeys = AppHotkeys> extends HotkeysProviderScopeProps {
   children: ReactNode;
   /**
    * Every app hotkey, from `defineAppHotkeys`. Listed by `useAppHotkeyList`
@@ -29,11 +33,16 @@ export interface HotkeysProviderProps<T extends AppHotkeys = AppHotkeys> {
   customHotkeys?: CustomHotkeys<T> | null;
   /** Called with the custom hotkeys after every change, ready to save. */
   onCustomHotkeysChange?: (customHotkeys: CustomHotkeys<T>) => 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,8 +55,19 @@ export interface HotkeysProviderProps<T extends AppHotkeys = AppHotkeys> {
  *   <App />
  * </HotkeysProvider>
  * ```
+ *
+ * @example
+ * ```tsx
+ * function EditDialog() {
+ *   return (
+ *     <HotkeysProvider scope="edit-dialog" exclusive={{ allow: ['global'] }}>
+ *       <DialogBody />
+ *     </HotkeysProvider>
+ *   )
+ * }
+ * ```
  */
-export declare function HotkeysProvider<T extends AppHotkeys = AppHotkeys>({ children, appHotkeys, customHotkeys, onCustomHotkeysChange, defaultOptions }: HotkeysProviderProps<T>): React.JSX.Element;
+export declare function HotkeysProvider<T extends AppHotkeys = AppHotkeys>({ children, appHotkeys, customHotkeys, onCustomHotkeysChange, defaultOptions, scope, exclusive, enabled }: HotkeysProviderProps<T>): React.JSX.Element;
 export declare function useHotkeysContext(): HotkeysContextValue | null;
 export declare function useDefaultHotkeysOptions(): HotkeysProviderOptions;
 //#endregion

package/dist/HotkeysProvider.js

@@ -1,12 +1,22 @@
 import { AppHotkeysStore, publishAppHotkeysStore } from "@tanstack/hotkeys";
 import React, { createContext, useContext, useEffect, useMemo, useState } from "react";
+import { activateHotkeysProviderScope, getHotkeysProviderScopeKey, mergeHotkeysProviderDefaults } from "@tanstack/hotkeys/adapter";
 
 //#region src/HotkeysProvider.tsx
 const HotkeysContext = createContext(null);
 const DEFAULT_OPTIONS = {};
+const NO_PARENT = {
+	appHotkeysStore: null,
+	defaultOptions: DEFAULT_OPTIONS,
+	enabled: true
+};
 /**
 * 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
@@ -19,12 +29,34 @@ const DEFAULT_OPTIONS = {};
 *   <App />
 * </HotkeysProvider>
 * ```
+*
+* @example
+* ```tsx
+* function EditDialog() {
+*   return (
+*     <HotkeysProvider scope="edit-dialog" exclusive={{ allow: ['global'] }}>
+*       <DialogBody />
+*     </HotkeysProvider>
+*   )
+* }
+* ```
 */
-function HotkeysProvider({ children, appHotkeys, customHotkeys, onCustomHotkeysChange, defaultOptions = DEFAULT_OPTIONS }) {
+function HotkeysProvider({ children, appHotkeys, customHotkeys, onCustomHotkeysChange, defaultOptions = DEFAULT_OPTIONS, scope, exclusive = false, enabled = true }) {
+	const parent = useContext(HotkeysContext) ?? NO_PARENT;
 	const [store] = useState(() => appHotkeys ? new AppHotkeysStore(appHotkeys, {
 		customHotkeys,
 		onCustomHotkeysChange
 	}) : null);
+	const active = parent.enabled && enabled;
+	const scopeKey = getHotkeysProviderScopeKey({
+		scope,
+		exclusive,
+		active,
+		parent: parent.defaultOptions.hotkey?.scope
+	});
+	useEffect(() => {
+		return scopeKey ? activateHotkeysProviderScope(scopeKey) : void 0;
+	}, [scopeKey]);
 	useEffect(() => {
 		store?.setOptions({ onCustomHotkeysChange });
 	}, [store, onCustomHotkeysChange]);
@@ -36,9 +68,16 @@ function HotkeysProvider({ children, appHotkeys, customHotkeys, onCustomHotkeysC
 		return publishAppHotkeysStore(store);
 	}, [store]);
 	const contextValue = useMemo(() => ({
-		appHotkeysStore: store,
-		defaultOptions
-	}), [store, defaultOptions]);
+		appHotkeysStore: store ?? parent.appHotkeysStore,
+		defaultOptions: mergeHotkeysProviderDefaults(parent.defaultOptions, defaultOptions, scope),
+		enabled: active
+	}), [
+		store,
+		parent,
+		defaultOptions,
+		scope,
+		active
+	]);
 	return /* @__PURE__ */ React.createElement(HotkeysContext.Provider, { value: contextValue }, children);
 }
 function useHotkeysContext() {

package/dist/useAppHotkeys.d.ts

@@ -7,8 +7,8 @@ import { AppHotkey, AppHotkeyListItem, CustomHotkeys, Hotkey, RegisteredAppHotke
  *
  * @example
  * ```tsx
- * const hotkeys = useAppHotkeys()
- * useHotkey(hotkeys['doc.save'], () => save())
+ * const appHotkeys = useAppHotkeys()
+ * useHotkey(appHotkeys['doc.save'], () => save())
  * ```
  */
 export declare function useAppHotkeys(): RegisteredAppHotkeys;
@@ -60,7 +60,7 @@ export interface UseCustomHotkeysResult {
  * ```tsx
  * const { setCustomHotkey, findConflicts } = useCustomHotkeys()
  * const recorder = useHotkeyRecorder({
- *   maxSteps: 3,
+ *   maxSteps: Infinity,
  *   validate: (hotkey) =>
  *     findConflicts('doc.save', hotkey).length === 0 || 'Already in use',
  *   onRecord: (hotkey) => setCustomHotkey('doc.save', hotkey),

package/dist/useAppHotkeys.js

@@ -14,8 +14,8 @@ function useRequiredStore(hook) {
 *
 * @example
 * ```tsx
-* const hotkeys = useAppHotkeys()
-* useHotkey(hotkeys['doc.save'], () => save())
+* const appHotkeys = useAppHotkeys()
+* useHotkey(appHotkeys['doc.save'], () => save())
 * ```
 */
 function useAppHotkeys() {
@@ -57,7 +57,7 @@ function useAppHotkeyList() {
 * ```tsx
 * const { setCustomHotkey, findConflicts } = useCustomHotkeys()
 * const recorder = useHotkeyRecorder({
-*   maxSteps: 3,
+*   maxSteps: Infinity,
 *   validate: (hotkey) =>
 *     findConflicts('doc.save', hotkey).length === 0 || 'Already in use',
 *   onRecord: (hotkey) => setCustomHotkey('doc.save', hotkey),

package/dist/useHotkey.d.ts

@@ -1,4 +1,4 @@
-import { AppHotkey, HotkeyCallback, RegisterableHotkey } from "@tanstack/hotkeys";
+import { AppHotkey, HotkeyCallback, HotkeyCallbackContextFor, RegisterableHotkey } from "@tanstack/hotkeys";
 import { AdapterAppHotkeyOptions, AdapterChordOptions, AdapterCommonOptions, AdapterHotkeyOptions, AdapterOptionsFor, AdapterSequenceOptions } from "@tanstack/hotkeys/adapter";
 //#region src/useHotkey.d.ts
 /** A React ref, element, document, or window to listen on. */
@@ -37,7 +37,7 @@ export type UseAppHotkeyOptions<T extends AppHotkey = AppHotkey> = AdapterAppHot
  * Options merge in this order: provider defaults, app hotkey declaration,
  * call-site options.
  *
- * @param hotkey - A chord string, RawHotkey object, sequence, or app hotkey
+ * @param hotkey - A chord string, RawHotkeyChord object, sequence, or app hotkey
  * @param callback - The function to call when the hotkey is pressed
  * @param options - Options for the hotkey behavior
  *
@@ -55,11 +55,11 @@ export type UseAppHotkeyOptions<T extends AppHotkey = AppHotkey> = AdapterAppHot
  * @example
  * ```tsx
  * function Toolbar() {
- *   const hotkeys = useAppHotkeys()
- *   useHotkey(hotkeys['doc.save'], () => save())
+ *   const appHotkeys = useAppHotkeys()
+ *   useHotkey(appHotkeys['doc.save'], () => save())
  * }
  * ```
  */
 export declare function useHotkey<T extends AppHotkey>(hotkey: T, callback: HotkeyCallback, options?: UseAppHotkeyOptions<T>): void;
-export declare function useHotkey<T extends RegisterableHotkey>(hotkey: T, callback: HotkeyCallback, options?: UseHotkeyOptionsFor<T>): void;
+export declare function useHotkey<const T extends RegisterableHotkey>(hotkey: T, callback: HotkeyCallback<HotkeyCallbackContextFor<T>>, options?: UseHotkeyOptionsFor<T>): void;
 //#endregion

package/dist/useHotkeyRecorder.d.ts

@@ -48,7 +48,7 @@ export interface ReactHotkeyRecorder<THotkey extends Hotkey = Hotkey> {
  * @example
  * ```tsx
  * const recorder = useHotkeyRecorder({
- *   maxSteps: 3,
+ *   maxSteps: Infinity,
  *   onRecord: (hotkey) => setShortcut(hotkey), // 'Mod+S' or ['G', 'H']
  * })
  * ```

package/package.json

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