@tanstack/react-hotkeys 0.13.0 → 0.14.1

package/dist/HotkeysProvider.d.ts

@@ -1,22 +1,53 @@
-import { UseHotkeyOptions } from "./useHotkey.js";
-import { UseHotkeySequenceOptions } from "./useHotkeySequence.js";
-import { HotkeyRecorderOptions, HotkeySequenceRecorderOptions } from "@tanstack/hotkeys";
+import { UseHotkeyCommonOptions } from "./useHotkey.js";
+import { AppHotkeys, AppHotkeysStore, CustomHotkeys, HotkeyChordRecorderOptions, HotkeySequenceRecorderOptions } from "@tanstack/hotkeys";
 import React, { ReactNode } from "react";
 //#region src/HotkeysProvider.d.ts
 export interface HotkeysProviderOptions {
-  hotkey?: Partial<UseHotkeyOptions>;
-  hotkeyRecorder?: Partial<HotkeyRecorderOptions>;
-  hotkeySequence?: Partial<UseHotkeySequenceOptions>;
-  hotkeySequenceRecorder?: Partial<HotkeySequenceRecorderOptions>;
+  /**
+   * Defaults for every hotkey registered by `useHotkey` and `useHotkeys`.
+   * `requireReset` applies to chords and `timeout` applies to sequences.
+   */
+  hotkey?: UseHotkeyCommonOptions;
+  /** Defaults for every `useHotkeyRecorder`. */
+  hotkeyRecorder?: Partial<Omit<HotkeyChordRecorderOptions & HotkeySequenceRecorderOptions, 'maxSteps' | 'onRecord' | 'validate'>>;
 }
 interface HotkeysContextValue {
+  appHotkeysStore: AppHotkeysStore | null;
   defaultOptions: HotkeysProviderOptions;
 }
-export interface HotkeysProviderProps {
+export interface HotkeysProviderProps<T extends AppHotkeys = AppHotkeys> {
   children: ReactNode;
+  /**
+   * Every app hotkey, from `defineAppHotkeys`. Listed by `useAppHotkeyList`
+   * whether or not their components have mounted.
+   */
+  appHotkeys?: T;
+  /**
+   * Starting custom hotkeys, such as saved data. Read once; the provider owns
+   * the state afterwards. Invalid entries are ignored with a warning.
+   */
+  customHotkeys?: CustomHotkeys<T> | null;
+  /** Called with the custom hotkeys after every change, ready to save. */
+  onCustomHotkeysChange?: (customHotkeys: CustomHotkeys<T>) => void;
   defaultOptions?: HotkeysProviderOptions;
 }
-export declare function HotkeysProvider({ children, defaultOptions }: HotkeysProviderProps): React.JSX.Element;
+/**
+ * Provides default options, app hotkeys, and the user's custom hotkeys.
+ *
+ * @example
+ * ```tsx
+ * <HotkeysProvider
+ *   appHotkeys={appHotkeys}
+ *   customHotkeys={JSON.parse(localStorage.getItem('hotkeys') ?? '{}')}
+ *   onCustomHotkeysChange={(custom) =>
+ *     localStorage.setItem('hotkeys', JSON.stringify(custom))
+ *   }
+ * >
+ *   <App />
+ * </HotkeysProvider>
+ * ```
+ */
+export declare function HotkeysProvider<T extends AppHotkeys = AppHotkeys>({ children, appHotkeys, customHotkeys, onCustomHotkeysChange, defaultOptions }: HotkeysProviderProps<T>): React.JSX.Element;
 export declare function useHotkeysContext(): HotkeysContextValue | null;
 export declare function useDefaultHotkeysOptions(): HotkeysProviderOptions;
 //#endregion

package/dist/HotkeysProvider.js

@@ -1,17 +1,51 @@
-import React, { createContext, useContext, useMemo } from "react";
+import { AppHotkeysStore, publishAppHotkeysStore } from "@tanstack/hotkeys";
+import React, { createContext, useContext, useEffect, useMemo, useState } from "react";
 
 //#region src/HotkeysProvider.tsx
 const HotkeysContext = createContext(null);
 const DEFAULT_OPTIONS = {};
-function HotkeysProvider({ children, defaultOptions = DEFAULT_OPTIONS }) {
-	const contextValue = useMemo(() => ({ defaultOptions }), [defaultOptions]);
+/**
+* Provides default options, app hotkeys, and the user's custom hotkeys.
+*
+* @example
+* ```tsx
+* <HotkeysProvider
+*   appHotkeys={appHotkeys}
+*   customHotkeys={JSON.parse(localStorage.getItem('hotkeys') ?? '{}')}
+*   onCustomHotkeysChange={(custom) =>
+*     localStorage.setItem('hotkeys', JSON.stringify(custom))
+*   }
+* >
+*   <App />
+* </HotkeysProvider>
+* ```
+*/
+function HotkeysProvider({ children, appHotkeys, customHotkeys, onCustomHotkeysChange, defaultOptions = DEFAULT_OPTIONS }) {
+	const [store] = useState(() => appHotkeys ? new AppHotkeysStore(appHotkeys, {
+		customHotkeys,
+		onCustomHotkeysChange
+	}) : null);
+	useEffect(() => {
+		store?.setOptions({ onCustomHotkeysChange });
+	}, [store, onCustomHotkeysChange]);
+	useEffect(() => {
+		if (appHotkeys) store?.setAppHotkeys(appHotkeys);
+	}, [store, appHotkeys]);
+	useEffect(() => {
+		if (!store) return;
+		return publishAppHotkeysStore(store);
+	}, [store]);
+	const contextValue = useMemo(() => ({
+		appHotkeysStore: store,
+		defaultOptions
+	}), [store, defaultOptions]);
 	return /* @__PURE__ */ React.createElement(HotkeysContext.Provider, { value: contextValue }, children);
 }
 function useHotkeysContext() {
 	return useContext(HotkeysContext);
 }
 function useDefaultHotkeysOptions() {
-	return useContext(HotkeysContext)?.defaultOptions ?? {};
+	return useContext(HotkeysContext)?.defaultOptions ?? DEFAULT_OPTIONS;
 }
 
 //#endregion

package/dist/_appHotkeysStore.js

@@ -0,0 +1,17 @@
+import { useHotkeysContext } from "./HotkeysProvider.js";
+import { Store, useSelector } from "@tanstack/react-store";
+
+//#region src/_appHotkeysStore.ts
+const NO_APP_HOTKEYS = new Store(null);
+/**
+* The provider's app hotkeys store, re-rendering when app hotkeys or custom
+* hotkeys change. Null outside a provider with `appHotkeys`.
+*/
+function useAppHotkeysStoreState() {
+	const store = useHotkeysContext()?.appHotkeysStore ?? null;
+	useSelector(store?.store ?? NO_APP_HOTKEYS, (state) => state);
+	return store;
+}
+
+//#endregion
+export { useAppHotkeysStoreState };

package/dist/index.d.ts

@@ -1,14 +1,12 @@
-import { UseHotkeyOptions, useHotkey } from "./useHotkey.js";
-import { UseHotkeySequenceOptions, useHotkeySequence } from "./useHotkeySequence.js";
+import { UseAppHotkeyOptions, UseHotkeyChordOptions, UseHotkeyCommonOptions, UseHotkeyOptions, UseHotkeyOptionsFor, UseHotkeySequenceOptions, UseHotkeyTarget, useHotkey } from "./useHotkey.js";
 import { HotkeysProvider, HotkeysProviderOptions, HotkeysProviderProps, useDefaultHotkeysOptions, useHotkeysContext } from "./HotkeysProvider.js";
 import { UseHotkeyDefinition, useHotkeys } from "./useHotkeys.js";
+import { ReactHotkeyRecorder, useHotkeyRecorder } from "./useHotkeyRecorder.js";
+import { useHotkeyRegistrations } from "./useHotkeyRegistrations.js";
+import { useHotkeyHint } from "./useHotkeyHint.js";
+import { UseCustomHotkeysResult, useAppHotkeyList, useAppHotkeys, useCustomHotkeys } from "./useAppHotkeys.js";
 import { useHeldKeys } from "./useHeldKeys.js";
 import { useHeldKeyCodes } from "./useHeldKeyCodes.js";
 import { useKeyHold } from "./useKeyHold.js";
-import { UseHotkeySequenceDefinition, useHotkeySequences } from "./useHotkeySequences.js";
-import { ReactHotkeyRecorder, useHotkeyRecorder } from "./useHotkeyRecorder.js";
-import { HotkeyRegistrationsResult, useHotkeyRegistrations } from "./useHotkeyRegistrations.js";
-import { ReactHotkeySequenceRecorder, useHotkeySequenceRecorder } from "./useHotkeySequenceRecorder.js";
-import { useHotkeyHint } from "./useHotkeyHint.js";
 export * from "@tanstack/hotkeys";
-export { HotkeyRegistrationsResult, HotkeysProvider, HotkeysProviderOptions, HotkeysProviderProps, ReactHotkeyRecorder, ReactHotkeySequenceRecorder, UseHotkeyDefinition, UseHotkeyOptions, UseHotkeySequenceDefinition, UseHotkeySequenceOptions, useDefaultHotkeysOptions, useHeldKeyCodes, useHeldKeys, useHotkey, useHotkeyHint, useHotkeyRecorder, useHotkeyRegistrations, useHotkeySequence, useHotkeySequenceRecorder, useHotkeySequences, useHotkeys, useHotkeysContext, useKeyHold };
+export { HotkeysProvider, HotkeysProviderOptions, HotkeysProviderProps, ReactHotkeyRecorder, UseAppHotkeyOptions, UseCustomHotkeysResult, UseHotkeyChordOptions, UseHotkeyCommonOptions, UseHotkeyDefinition, UseHotkeyOptions, UseHotkeyOptionsFor, UseHotkeySequenceOptions, UseHotkeyTarget, useAppHotkeyList, useAppHotkeys, useCustomHotkeys, useDefaultHotkeysOptions, useHeldKeyCodes, useHeldKeys, useHotkey, useHotkeyHint, useHotkeyRecorder, useHotkeyRegistrations, useHotkeys, useHotkeysContext, useKeyHold };

package/dist/index.js

@@ -1,16 +1,14 @@
 import { HotkeysProvider, useDefaultHotkeysOptions, useHotkeysContext } from "./HotkeysProvider.js";
-import { useHotkey } from "./useHotkey.js";
 import { useHotkeys } from "./useHotkeys.js";
-import { useHeldKeys } from "./useHeldKeys.js";
-import { useHeldKeyCodes } from "./useHeldKeyCodes.js";
-import { useKeyHold } from "./useKeyHold.js";
-import { useHotkeySequence } from "./useHotkeySequence.js";
-import { useHotkeySequences } from "./useHotkeySequences.js";
+import { useHotkey } from "./useHotkey.js";
 import { useHotkeyRecorder } from "./useHotkeyRecorder.js";
 import { useHotkeyRegistrations } from "./useHotkeyRegistrations.js";
-import { useHotkeySequenceRecorder } from "./useHotkeySequenceRecorder.js";
 import { useHotkeyHint } from "./useHotkeyHint.js";
+import { useAppHotkeyList, useAppHotkeys, useCustomHotkeys } from "./useAppHotkeys.js";
+import { useHeldKeys } from "./useHeldKeys.js";
+import { useHeldKeyCodes } from "./useHeldKeyCodes.js";
+import { useKeyHold } from "./useKeyHold.js";
 
 export * from "@tanstack/hotkeys"
 
-export { HotkeysProvider, useDefaultHotkeysOptions, useHeldKeyCodes, useHeldKeys, useHotkey, useHotkeyHint, useHotkeyRecorder, useHotkeyRegistrations, useHotkeySequence, useHotkeySequenceRecorder, useHotkeySequences, useHotkeys, useHotkeysContext, useKeyHold };
+export { HotkeysProvider, useAppHotkeyList, useAppHotkeys, useCustomHotkeys, useDefaultHotkeysOptions, useHeldKeyCodes, useHeldKeys, useHotkey, useHotkeyHint, useHotkeyRecorder, useHotkeyRegistrations, useHotkeys, useHotkeysContext, useKeyHold };

package/dist/useAppHotkeys.d.ts

@@ -0,0 +1,71 @@
+import { AppHotkey, AppHotkeyListItem, CustomHotkeys, Hotkey, RegisteredAppHotkeys } from "@tanstack/hotkeys";
+//#region src/useAppHotkeys.d.ts
+/**
+ * Returns the effective app hotkeys from `HotkeysProvider`, typed by
+ * `Register`: each declaration with the user's custom hotkey applied.
+ * Pass an entry to `useHotkey` or `useHotkeys` to register it.
+ *
+ * @example
+ * ```tsx
+ * const hotkeys = useAppHotkeys()
+ * useHotkey(hotkeys['doc.save'], () => save())
+ * ```
+ */
+export declare function useAppHotkeys(): RegisteredAppHotkeys;
+/**
+ * Lists every app hotkey with its live status, in declaration order, for
+ * cheat sheets and settings screens. App hotkeys whose components have not
+ * mounted are `'inactive'`; those without a hotkey are `'unbound'`.
+ *
+ * @example
+ * ```tsx
+ * function CheatSheet() {
+ *   const items = useAppHotkeyList()
+ *   return (
+ *     <ul>
+ *       {items.map(({ appHotkey, status }) => (
+ *         <li key={appHotkey.id} data-status={status}>
+ *           {appHotkey.meta?.name}:{' '}
+ *           {appHotkey.hotkey ? formatForDisplay(appHotkey.hotkey) : 'Unassigned'}
+ *         </li>
+ *       ))}
+ *     </ul>
+ *   )
+ * }
+ * ```
+ */
+export declare function useAppHotkeyList(): Array<AppHotkeyListItem<RegisteredAppHotkeys[keyof RegisteredAppHotkeys]>>;
+/** Custom hotkey state and actions returned by `useCustomHotkeys`. */
+export interface UseCustomHotkeysResult {
+  /** The user's hotkeys that differ from the defaults. */
+  customHotkeys: CustomHotkeys;
+  /**
+   * Sets the user's hotkey for an app hotkey. `null` unbinds it.
+   * Returns conflicting app hotkeys; when any exist, nothing changes.
+   */
+  setCustomHotkey: (id: keyof RegisteredAppHotkeys & string, hotkey: Hotkey | null) => Array<AppHotkey>;
+  /** Restores the default hotkey for an app hotkey. */
+  resetCustomHotkey: (id: keyof RegisteredAppHotkeys & string) => void;
+  /** Restores every default hotkey. */
+  resetCustomHotkeys: () => void;
+  /** Other app hotkeys that would collide if `id` used `hotkey`. */
+  findConflicts: (id: keyof RegisteredAppHotkeys & string, hotkey: Hotkey) => Array<AppHotkey>;
+}
+/**
+ * Reads and changes the user's custom hotkeys. Changes apply to every
+ * registered app hotkey immediately and are passed to the provider's
+ * `onCustomHotkeysChange`, ready to save.
+ *
+ * @example
+ * ```tsx
+ * const { setCustomHotkey, findConflicts } = useCustomHotkeys()
+ * const recorder = useHotkeyRecorder({
+ *   maxSteps: 3,
+ *   validate: (hotkey) =>
+ *     findConflicts('doc.save', hotkey).length === 0 || 'Already in use',
+ *   onRecord: (hotkey) => setCustomHotkey('doc.save', hotkey),
+ * })
+ * ```
+ */
+export declare function useCustomHotkeys(): UseCustomHotkeysResult;
+//#endregion

package/dist/useAppHotkeys.js

@@ -0,0 +1,79 @@
+import { useAppHotkeysStoreState } from "./_appHotkeysStore.js";
+import { useHotkeyRegistrations } from "./useHotkeyRegistrations.js";
+
+//#region src/useAppHotkeys.ts
+function useRequiredStore(hook) {
+	const store = useAppHotkeysStoreState();
+	if (!store) throw new Error(`${hook} requires a HotkeysProvider with an appHotkeys prop`);
+	return store;
+}
+/**
+* Returns the effective app hotkeys from `HotkeysProvider`, typed by
+* `Register`: each declaration with the user's custom hotkey applied.
+* Pass an entry to `useHotkey` or `useHotkeys` to register it.
+*
+* @example
+* ```tsx
+* const hotkeys = useAppHotkeys()
+* useHotkey(hotkeys['doc.save'], () => save())
+* ```
+*/
+function useAppHotkeys() {
+	return useRequiredStore("useAppHotkeys").appHotkeys;
+}
+/**
+* Lists every app hotkey with its live status, in declaration order, for
+* cheat sheets and settings screens. App hotkeys whose components have not
+* mounted are `'inactive'`; those without a hotkey are `'unbound'`.
+*
+* @example
+* ```tsx
+* function CheatSheet() {
+*   const items = useAppHotkeyList()
+*   return (
+*     <ul>
+*       {items.map(({ appHotkey, status }) => (
+*         <li key={appHotkey.id} data-status={status}>
+*           {appHotkey.meta?.name}:{' '}
+*           {appHotkey.hotkey ? formatForDisplay(appHotkey.hotkey) : 'Unassigned'}
+*         </li>
+*       ))}
+*     </ul>
+*   )
+* }
+* ```
+*/
+function useAppHotkeyList() {
+	const store = useRequiredStore("useAppHotkeyList");
+	const registrations = useHotkeyRegistrations();
+	return store.getList(registrations);
+}
+/**
+* Reads and changes the user's custom hotkeys. Changes apply to every
+* registered app hotkey immediately and are passed to the provider's
+* `onCustomHotkeysChange`, ready to save.
+*
+* @example
+* ```tsx
+* const { setCustomHotkey, findConflicts } = useCustomHotkeys()
+* const recorder = useHotkeyRecorder({
+*   maxSteps: 3,
+*   validate: (hotkey) =>
+*     findConflicts('doc.save', hotkey).length === 0 || 'Already in use',
+*   onRecord: (hotkey) => setCustomHotkey('doc.save', hotkey),
+* })
+* ```
+*/
+function useCustomHotkeys() {
+	const store = useRequiredStore("useCustomHotkeys");
+	return {
+		customHotkeys: store.customHotkeys,
+		setCustomHotkey: (id, hotkey) => store.setCustomHotkey(id, hotkey),
+		resetCustomHotkey: (id) => store.resetCustomHotkey(id),
+		resetCustomHotkeys: () => store.resetCustomHotkeys(),
+		findConflicts: (id, hotkey) => store.findConflicts(id, hotkey)
+	};
+}
+
+//#endregion
+export { useAppHotkeyList, useAppHotkeys, useCustomHotkeys };

package/dist/useHotkey.d.ts

@@ -1,71 +1,65 @@
-import { HotkeyCallback, HotkeyOptions, RegisterableHotkey } from "@tanstack/hotkeys";
+import { AppHotkey, HotkeyCallback, RegisterableHotkey } from "@tanstack/hotkeys";
+import { AdapterAppHotkeyOptions, AdapterChordOptions, AdapterCommonOptions, AdapterHotkeyOptions, AdapterOptionsFor, AdapterSequenceOptions } from "@tanstack/hotkeys/adapter";
 //#region src/useHotkey.d.ts
-export interface UseHotkeyOptions extends Omit<HotkeyOptions, 'target'> {
-  /**
-   * The DOM element to attach the event listener to.
-   * Can be a React ref, direct DOM element, or null.
-   * Defaults to document.
-   */
-  target?: React.RefObject<HTMLElement | null> | HTMLElement | Document | Window | null;
-}
+/** A React ref, element, document, or window to listen on. */
+export type UseHotkeyTarget = React.RefObject<HTMLElement | null> | HTMLElement | Document | Window | null;
+/** Options shared by chords and sequences. */
+export type UseHotkeyOptions = AdapterHotkeyOptions<UseHotkeyTarget>;
+/** Options for a chord such as `'Mod+S'`. */
+export type UseHotkeyChordOptions = AdapterChordOptions<UseHotkeyTarget>;
+/** Options for a sequence such as `['G', 'G']`. */
+export type UseHotkeySequenceOptions = AdapterSequenceOptions<UseHotkeyTarget>;
+/** Options applied to every hotkey, such as provider defaults. Each applies to the kinds that support it. */
+export type UseHotkeyCommonOptions = AdapterCommonOptions<UseHotkeyTarget>;
+/** The options type for a hotkey: chord options for chords, sequence options for sequences. */
+export type UseHotkeyOptionsFor<T extends RegisterableHotkey> = AdapterOptionsFor<T, UseHotkeyTarget>;
 /**
- * React hook for registering a keyboard hotkey.
+ * Options for an app hotkey at the call site. `meta` comes from the declaration.
+ * Kind-specific options follow the declared default: `requireReset` for a chord,
+ * `timeout` for a sequence, both for an app hotkey without a default. If the
+ * user rebinds it to the other kind, options for the old kind no longer apply.
+ */
+export type UseAppHotkeyOptions<T extends AppHotkey = AppHotkey> = AdapterAppHotkeyOptions<T, UseHotkeyTarget>;
+/**
+ * React hook for registering a hotkey: a chord such as `'Mod+S'`, a sequence
+ * such as `['G', 'G']`, or an app hotkey from `defineAppHotkeys`.
  *
- * Uses the singleton HotkeyManager for efficient event handling.
- * The callback receives both the keyboard event and a context object
- * containing the hotkey string and parsed hotkey.
+ * Uses the singleton HotkeyManager for efficient event handling. The callback
+ * and options sync on every render, so callbacks that reference React state
+ * always see the latest values. `enabled: false` keeps the registration
+ * (visible in devtools) and only suppresses firing.
  *
- * This hook syncs the callback and options on every render to avoid
- * stale closures. This means
- * callbacks that reference React state will always have access to
- * the latest values.
+ * Chords accept `requireReset`; sequences accept `timeout`. A one-step
+ * sequence registers as its chord. An app hotkey uses its effective hotkey
+ * from `HotkeysProvider` (including the user's custom hotkey) and its declared
+ * meta and options, and registers nothing while unbound.
  *
- * @param hotkey - The hotkey string (e.g., 'Mod+S', 'Escape') or RawHotkey object (supports `mod` for cross-platform)
+ * 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 callback - The function to call when the hotkey is pressed
- * @param options - Options for the hotkey behavior. `enabled: false` keeps the registration (visible in devtools)
- *   and only suppresses firing; the hook updates the existing handle instead of unregistering.
+ * @param options - Options for the hotkey behavior
  *
  * @example
  * ```tsx
- * function SaveButton() {
+ * function Editor() {
  *   const [count, setCount] = useState(0)
  *
- *   // Callback always has access to latest count value
- *   useHotkey('Mod+S', (event, { hotkey }) => {
- *     console.log(`Save triggered, count is ${count}`)
- *     handleSave()
- *   })
- *
- *   return <button onClick={() => setCount(c => c + 1)}>Count: {count}</button>
- * }
- * ```
- *
- * @example
- * ```tsx
- * function Modal({ isOpen, onClose }) {
- *   // enabled option is synced on every render
- *   useHotkey('Escape', () => {
- *     onClose()
- *   }, { enabled: isOpen })
- *
- *   if (!isOpen) return null
- *   return <div className="modal">...</div>
+ *   useHotkey('Mod+S', () => save(count))
+ *   useHotkey(['G', 'G'], () => scrollToTop(), { timeout: 500 })
+ *   useHotkey('Escape', () => close(), { enabled: isOpen })
  * }
  * ```
  *
  * @example
  * ```tsx
- * function Editor() {
- *   const editorRef = useRef<HTMLDivElement>(null)
- *
- *   // Scoped to a specific element
- *   useHotkey('Mod+S', () => {
- *     save()
- *   }, { target: editorRef })
- *
- *   return <div ref={editorRef}>...</div>
+ * function Toolbar() {
+ *   const hotkeys = useAppHotkeys()
+ *   useHotkey(hotkeys['doc.save'], () => save())
  * }
  * ```
  */
-export declare function useHotkey(hotkey: RegisterableHotkey, callback: HotkeyCallback, options?: UseHotkeyOptions): void;
+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;
 //#endregion

package/dist/useHotkey.js

@@ -1,124 +1,12 @@
-import { useDefaultHotkeysOptions } from "./HotkeysProvider.js";
-import { isRef } from "./utils.js";
-import { detectPlatform, getHotkeyManager, normalizeRegisterableHotkey } from "@tanstack/hotkeys";
-import { useEffect, useRef } from "react";
+import { useHotkeys } from "./useHotkeys.js";
 
 //#region src/useHotkey.ts
-/**
-* React hook for registering a keyboard hotkey.
-*
-* Uses the singleton HotkeyManager for efficient event handling.
-* The callback receives both the keyboard event and a context object
-* containing the hotkey string and parsed hotkey.
-*
-* This hook syncs the callback and options on every render to avoid
-* stale closures. This means
-* callbacks that reference React state will always have access to
-* the latest values.
-*
-* @param hotkey - The hotkey string (e.g., 'Mod+S', 'Escape') or RawHotkey object (supports `mod` for cross-platform)
-* @param callback - The function to call when the hotkey is pressed
-* @param options - Options for the hotkey behavior. `enabled: false` keeps the registration (visible in devtools)
-*   and only suppresses firing; the hook updates the existing handle instead of unregistering.
-*
-* @example
-* ```tsx
-* function SaveButton() {
-*   const [count, setCount] = useState(0)
-*
-*   // Callback always has access to latest count value
-*   useHotkey('Mod+S', (event, { hotkey }) => {
-*     console.log(`Save triggered, count is ${count}`)
-*     handleSave()
-*   })
-*
-*   return <button onClick={() => setCount(c => c + 1)}>Count: {count}</button>
-* }
-* ```
-*
-* @example
-* ```tsx
-* function Modal({ isOpen, onClose }) {
-*   // enabled option is synced on every render
-*   useHotkey('Escape', () => {
-*     onClose()
-*   }, { enabled: isOpen })
-*
-*   if (!isOpen) return null
-*   return <div className="modal">...</div>
-* }
-* ```
-*
-* @example
-* ```tsx
-* function Editor() {
-*   const editorRef = useRef<HTMLDivElement>(null)
-*
-*   // Scoped to a specific element
-*   useHotkey('Mod+S', () => {
-*     save()
-*   }, { target: editorRef })
-*
-*   return <div ref={editorRef}>...</div>
-* }
-* ```
-*/
-function useHotkey(hotkey, callback, options = {}) {
-	const mergedOptions = {
-		...useDefaultHotkeysOptions().hotkey,
-		...options
-	};
-	const manager = getHotkeyManager();
-	const registrationRef = useRef(null);
-	const callbackRef = useRef(callback);
-	const optionsRef = useRef(mergedOptions);
-	const managerRef = useRef(manager);
-	callbackRef.current = callback;
-	optionsRef.current = mergedOptions;
-	managerRef.current = manager;
-	const prevTargetRef = useRef(null);
-	const prevHotkeyRef = useRef(null);
-	const platform = mergedOptions.platform ?? detectPlatform();
-	const hotkeyString = normalizeRegisterableHotkey(hotkey, platform);
-	const { target: _target, ...optionsWithoutTarget } = mergedOptions;
-	useEffect(() => {
-		const resolvedTarget = isRef(optionsRef.current.target) ? optionsRef.current.target.current : optionsRef.current.target ?? (typeof document !== "undefined" ? document : null);
-		if (!resolvedTarget) {
-			if (registrationRef.current?.isActive) {
-				registrationRef.current.unregister();
-				registrationRef.current = null;
-			}
-			prevTargetRef.current = null;
-			prevHotkeyRef.current = null;
-			return;
-		}
-		const targetChanged = prevTargetRef.current !== null && prevTargetRef.current !== resolvedTarget;
-		const hotkeyChanged = prevHotkeyRef.current !== null && prevHotkeyRef.current !== hotkeyString;
-		if (registrationRef.current?.isActive && (targetChanged || hotkeyChanged)) {
-			registrationRef.current.unregister();
-			registrationRef.current = null;
-		}
-		if (!registrationRef.current || !registrationRef.current.isActive) registrationRef.current = managerRef.current.register(hotkeyString, callbackRef.current, {
-			...optionsRef.current,
-			target: resolvedTarget
-		});
-		prevTargetRef.current = resolvedTarget;
-		prevHotkeyRef.current = hotkeyString;
-	});
-	useEffect(() => {
-		return () => {
-			if (registrationRef.current?.isActive) {
-				registrationRef.current.unregister();
-				registrationRef.current = null;
-			}
-		};
-	}, []);
-	useEffect(() => {
-		if (registrationRef.current?.isActive) {
-			registrationRef.current.callback = callback;
-			registrationRef.current.setOptions(optionsWithoutTarget);
-		}
-	});
+function useHotkey(hotkey, callback, options) {
+	useHotkeys([{
+		hotkey,
+		callback,
+		options
+	}]);
 }
 
 //#endregion

package/dist/useHotkeyHint.d.ts

@@ -1,11 +1,13 @@
-import { HeldModifierOptions, RegisterableHotkey } from "@tanstack/hotkeys";
+import { AppHotkey, HeldModifierOptions, RegisterableHotkey } from "@tanstack/hotkeys";
 //#region src/useHotkeyHint.d.ts
 /**
  * Returns a boolean indicating whether held modifiers reveal this shortcut.
  * Only visibility changes from held-key updates cause a rerender.
  * Uses the nonempty-subset/AltGr rules of `matchesHeldModifiers`; `exact` requires
- * every modifier. Combine with the action's enabled state before showing a badge.
- * This helper does not register a shortcut or check whether its target is focused.
+ * every modifier. A sequence reveals its hint from its first step, and an app
+ * hotkey uses its effective hotkey (false while unbound). Combine with the
+ * action's enabled state before showing a badge. This helper does not register
+ * a shortcut or check whether its target is focused.
  */
-export declare function useHotkeyHint(hotkey: RegisterableHotkey, options?: HeldModifierOptions): boolean;
+export declare function useHotkeyHint(hotkey: RegisterableHotkey | AppHotkey, options?: HeldModifierOptions): boolean;
 //#endregion

package/dist/useHotkeyHint.js

@@ -1,4 +1,5 @@
-import { getKeyStateTracker, matchesHeldModifiers } from "@tanstack/hotkeys";
+import { useAppHotkeysStoreState } from "./_appHotkeysStore.js";
+import { getKeyStateTracker, isAppHotkey, matchesHeldModifiers, resolveAppHotkey } from "@tanstack/hotkeys";
 import { useSelector } from "@tanstack/react-store";
 
 //#region src/useHotkeyHint.ts
@@ -6,11 +7,15 @@ import { useSelector } from "@tanstack/react-store";
 * Returns a boolean indicating whether held modifiers reveal this shortcut.
 * Only visibility changes from held-key updates cause a rerender.
 * Uses the nonempty-subset/AltGr rules of `matchesHeldModifiers`; `exact` requires
-* every modifier. Combine with the action's enabled state before showing a badge.
-* This helper does not register a shortcut or check whether its target is focused.
+* every modifier. A sequence reveals its hint from its first step, and an app
+* hotkey uses its effective hotkey (false while unbound). Combine with the
+* action's enabled state before showing a badge. This helper does not register
+* a shortcut or check whether its target is focused.
 */
 function useHotkeyHint(hotkey, options = {}) {
-	return useSelector(getKeyStateTracker().store, (state) => matchesHeldModifiers(hotkey, state.heldKeys, options));
+	const store = useAppHotkeysStoreState();
+	const resolved = isAppHotkey(hotkey) ? resolveAppHotkey(hotkey, store).hotkey : hotkey;
+	return useSelector(getKeyStateTracker().store, (state) => resolved !== null && matchesHeldModifiers(resolved, state.heldKeys, options));
 }
 
 //#endregion