@tanstack/octane-hotkeys 0.4.5 → 0.5.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,5 +1,6 @@
 import { UseHotkeyCommonOptions } from "./useHotkey.js";
 import { AppHotkeys, AppHotkeysStore, CustomHotkeys, HotkeyChordRecorderOptions, HotkeySequenceRecorderOptions } from "@tanstack/hotkeys";
+import { HotkeysProviderScopeProps } from "@tanstack/hotkeys/adapter";
 //#region src/HotkeysProvider.d.ts
 export interface DefaultHotkeysOptions {
   /**
@@ -11,12 +12,16 @@ export interface DefaultHotkeysOptions {
   hotkeyRecorder?: Partial<Omit<HotkeyChordRecorderOptions & HotkeySequenceRecorderOptions, 'maxSteps' | 'onRecord' | 'validate'>>;
 }
 interface HotkeysContextValue {
+  /** Merged with every ancestor provider's defaults, including `hotkey.scope`. */
   defaultOptions: DefaultHotkeysOptions;
   appHotkeysStore: AppHotkeysStore | null;
+  /** Whether this provider and every ancestor are enabled. */
+  enabled: boolean;
 }
 export type HotkeysProviderOptions = DefaultHotkeysOptions;
-export interface HotkeysProviderProps {
+export interface HotkeysProviderProps extends HotkeysProviderScopeProps {
   children?: unknown;
+  /** Merged with the parent provider's defaults. */
   defaultOptions?: HotkeysProviderOptions;
   /**
    * Every app hotkey, from `defineAppHotkeys`. Read when the provider first
@@ -35,11 +40,18 @@ export interface HotkeysProviderProps {
 export declare function useHotkeysContext(): HotkeysContextValue | null;
 /** Reads the nearest provider's defaults, or an empty object. */
 export declare function useDefaultHotkeysOptions(): DefaultHotkeysOptions;
-/** Sets defaults, app hotkeys, and custom hotkeys for descendant components. */
-export declare function HotkeysProvider({ children, defaultOptions, appHotkeys, customHotkeys, onCustomHotkeysChange }: HotkeysProviderProps): import("octane").ElementDescriptor<{
+/**
+ * Sets defaults, app hotkeys, and custom hotkeys for descendant components.
+ *
+ * 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.
+ */
+export declare function HotkeysProvider({ children, defaultOptions, appHotkeys, customHotkeys, onCustomHotkeysChange, scope, exclusive, enabled }: HotkeysProviderProps): import("octane").ElementDescriptor<{
   value: {
     defaultOptions: DefaultHotkeysOptions;
     appHotkeysStore: AppHotkeysStore<Readonly<Record<string, import("@tanstack/hotkeys").AppHotkey<string, import("@tanstack/hotkeys").HotkeyChord | import("@tanstack/hotkeys").HotkeySequence | null>>>> | null;
+    enabled: boolean;
   };
   children: unknown;
 }>;

package/dist/HotkeysProvider.js

@@ -1,6 +1,7 @@
 import { subSlot } from "./internal.js";
 import { AppHotkeysStore, publishAppHotkeysStore } from "@tanstack/hotkeys";
 import { createContext, createElement, useContext, useLayoutEffect, useRef } from "octane";
+import { activateHotkeysProviderScope, getHotkeysProviderScopeKey, mergeHotkeysProviderDefaults } from "@tanstack/hotkeys/adapter";
 
 //#region src/HotkeysProvider.ts
 const HotkeysContext = createContext(null);
@@ -12,8 +13,15 @@ function useHotkeysContext() {
 function useDefaultHotkeysOptions() {
 	return useContext(HotkeysContext)?.defaultOptions ?? {};
 }
-/** Sets defaults, app hotkeys, and custom hotkeys for descendant components. */
-function HotkeysProvider({ children, defaultOptions = {}, appHotkeys, customHotkeys, onCustomHotkeysChange }) {
+/**
+* Sets defaults, app hotkeys, and custom hotkeys for descendant components.
+*
+* 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.
+*/
+function HotkeysProvider({ children, defaultOptions, appHotkeys, customHotkeys, onCustomHotkeysChange, scope, exclusive, enabled = true }) {
+	const parent = useContext(HotkeysContext);
 	const callbackRef = useRef(onCustomHotkeysChange, subSlot(void 0, "provider-callback"));
 	callbackRef.current = onCustomHotkeysChange;
 	const storeRef = useRef(void 0, subSlot(void 0, "provider-store"));
@@ -26,10 +34,19 @@ function HotkeysProvider({ children, defaultOptions = {}, appHotkeys, customHotk
 		if (appHotkeys) store?.setAppHotkeys(appHotkeys);
 	}, [store, appHotkeys], subSlot(void 0, "provider-declarations"));
 	useLayoutEffect(() => store ? publishAppHotkeysStore(store) : void 0, [store], subSlot(void 0, "provider-publish"));
+	const active = (parent?.enabled ?? true) && enabled;
+	const scopeKey = getHotkeysProviderScopeKey({
+		scope,
+		exclusive,
+		active,
+		parent: parent?.defaultOptions.hotkey?.scope
+	});
+	useLayoutEffect(() => scopeKey ? activateHotkeysProviderScope(scopeKey) : void 0, [scopeKey], subSlot(void 0, "provider-scope"));
 	return createElement(HotkeysContext, {
 		value: {
-			defaultOptions,
-			appHotkeysStore: store
+			defaultOptions: mergeHotkeysProviderDefaults(parent?.defaultOptions, defaultOptions, scope),
+			appHotkeysStore: store ?? parent?.appHotkeysStore ?? null,
+			enabled: active
 		},
 		children
 	});

package/dist/useHotkey.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/useHotkey.d.ts
 /** The element to listen on. A `null` target skips registration until it is set. */
@@ -21,5 +21,5 @@ export type UseAppHotkeyOptions<T extends AppHotkey = AppHotkey> = AdapterAppHot
  * options are refreshed after every commit.
  */
 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/octane-hotkeys",
-  "version": "0.4.5",
+  "version": "0.5.0",
   "description": "Octane adapter for TanStack Hotkeys",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -33,7 +33,7 @@
     "dist"
   ],
   "dependencies": {
-    "@tanstack/hotkeys": "0.15.1",
+    "@tanstack/hotkeys": "0.16.0",
     "@tanstack/octane-store": "^0.13.0"
   },
   "devDependencies": {