@tanstack/octane-hotkeys 0.3.0 → 0.4.0

package/dist/HotkeysProvider.d.ts

@@ -1,25 +1,46 @@
-import { HotkeyOptions, HotkeyRecorderOptions, HotkeySequenceRecorderOptions, SequenceOptions } from "@tanstack/hotkeys";
+import { UseHotkeyCommonOptions } from "./useHotkey.js";
+import { AppHotkeys, AppHotkeysStore, CustomHotkeys, HotkeyChordRecorderOptions, HotkeySequenceRecorderOptions } from "@tanstack/hotkeys";
 //#region src/HotkeysProvider.d.ts
 export interface DefaultHotkeysOptions {
-  hotkey?: HotkeyOptions;
-  hotkeySequence?: SequenceOptions;
-  hotkeyRecorder?: Partial<HotkeyRecorderOptions>;
-  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 {
+  defaultOptions: DefaultHotkeysOptions;
+  appHotkeysStore: AppHotkeysStore | null;
 }
 export type HotkeysProviderOptions = DefaultHotkeysOptions;
 export interface HotkeysProviderProps {
   children?: unknown;
   defaultOptions?: HotkeysProviderOptions;
+  /**
+   * Every app hotkey, from `defineAppHotkeys`. Read when the provider first
+   * renders; listed by `useAppHotkeyList` whether or not they are registered.
+   */
+  appHotkeys?: AppHotkeys;
+  /**
+   * Starting custom hotkeys, such as saved data. Read once; the provider owns
+   * the state afterwards. Invalid entries are ignored with a warning.
+   */
+  customHotkeys?: CustomHotkeys | null;
+  /** Called with the custom hotkeys after every change, ready to save. */
+  onCustomHotkeysChange?: (customHotkeys: CustomHotkeys) => void;
 }
 /** Reads the nearest provider, or null outside a provider. */
-export declare function useHotkeysContext(): {
-  defaultOptions: DefaultHotkeysOptions;
-} | null;
+export declare function useHotkeysContext(): HotkeysContextValue | null;
 /** Reads the nearest provider's defaults, or an empty object. */
 export declare function useDefaultHotkeysOptions(): DefaultHotkeysOptions;
-/** Sets registration and recorder defaults for descendant components. */
-export declare function HotkeysProvider({ children, defaultOptions }: HotkeysProviderProps): import("octane").ElementDescriptor<{
-  value: DefaultHotkeysOptions;
+/** Sets defaults, app hotkeys, and custom hotkeys for descendant components. */
+export declare function HotkeysProvider({ children, defaultOptions, appHotkeys, customHotkeys, onCustomHotkeysChange }: 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;
+  };
   children: unknown;
 }>;
 //#endregion

package/dist/HotkeysProvider.js

@@ -1,20 +1,36 @@
-import { createContext, createElement, useContext } from "octane";
+import { subSlot } from "./internal.js";
+import { AppHotkeysStore, publishAppHotkeysStore } from "@tanstack/hotkeys";
+import { createContext, createElement, useContext, useLayoutEffect, useRef } from "octane";
 
 //#region src/HotkeysProvider.ts
 const HotkeysContext = createContext(null);
 /** Reads the nearest provider, or null outside a provider. */
 function useHotkeysContext() {
-	const defaultOptions = useContext(HotkeysContext);
-	return defaultOptions === null ? null : { defaultOptions };
+	return useContext(HotkeysContext);
 }
 /** Reads the nearest provider's defaults, or an empty object. */
 function useDefaultHotkeysOptions() {
-	return useContext(HotkeysContext) ?? {};
+	return useContext(HotkeysContext)?.defaultOptions ?? {};
 }
-/** Sets registration and recorder defaults for descendant components. */
-function HotkeysProvider({ children, defaultOptions = {} }) {
+/** Sets defaults, app hotkeys, and custom hotkeys for descendant components. */
+function HotkeysProvider({ children, defaultOptions = {}, appHotkeys, customHotkeys, onCustomHotkeysChange }) {
+	const callbackRef = useRef(onCustomHotkeysChange, subSlot(void 0, "provider-callback"));
+	callbackRef.current = onCustomHotkeysChange;
+	const storeRef = useRef(void 0, subSlot(void 0, "provider-store"));
+	storeRef.current ??= appHotkeys ? new AppHotkeysStore(appHotkeys, {
+		customHotkeys,
+		onCustomHotkeysChange: (custom) => callbackRef.current?.(custom)
+	}) : null;
+	const store = storeRef.current;
+	useLayoutEffect(() => {
+		if (appHotkeys) store?.setAppHotkeys(appHotkeys);
+	}, [store, appHotkeys], subSlot(void 0, "provider-declarations"));
+	useLayoutEffect(() => store ? publishAppHotkeysStore(store) : void 0, [store], subSlot(void 0, "provider-publish"));
 	return createElement(HotkeysContext, {
-		value: defaultOptions,
+		value: {
+			defaultOptions,
+			appHotkeysStore: store
+		},
 		children
 	});
 }

package/dist/index.d.ts

@@ -1,16 +1,13 @@
+import { UseAppHotkeyOptions, UseHotkeyChordOptions, UseHotkeyCommonOptions, UseHotkeyOptions, UseHotkeyOptionsFor, UseHotkeySequenceOptions, UseHotkeyTarget, useHotkey } from "./useHotkey.js";
 import { DefaultHotkeysOptions, HotkeysProvider, HotkeysProviderOptions, HotkeysProviderProps, useDefaultHotkeysOptions, useHotkeysContext } from "./HotkeysProvider.js";
-import { useHotkeys } from "./useHotkeys.js";
-import { useHotkey } from "./useHotkey.js";
-import { useHotkeySequences } from "./useHotkeySequences.js";
-import { useHotkeySequence } from "./useHotkeySequence.js";
+import { UseHotkeyDefinition, useHotkeys } from "./useHotkeys.js";
 import { useHeldKeys } from "./useHeldKeys.js";
 import { useHeldKeyCodes } from "./useHeldKeyCodes.js";
 import { useKeyHold } from "./useKeyHold.js";
 import { useHotkeyHint } from "./useHotkeyHint.js";
-import { HotkeyRegistrationsResult, OctaneHotkeyRecorder, OctaneHotkeySequenceRecorder } from "./types.js";
+import { HotkeyRegistrationsResult, OctaneHotkeyRecorder, UseCustomHotkeysResult } from "./types.js";
 import { useHotkeyRegistrations } from "./useHotkeyRegistrations.js";
 import { useHotkeyRecorder } from "./useHotkeyRecorder.js";
-import { useHotkeySequenceRecorder } from "./useHotkeySequenceRecorder.js";
-import { HotkeyDefinition, HotkeySequenceDefinition } from "@tanstack/hotkeys/adapter";
+import { useAppHotkeyList, useAppHotkeys, useCustomHotkeys } from "./useAppHotkeys.js";
 export * from "@tanstack/hotkeys";
-export { type DefaultHotkeysOptions, type HotkeyDefinition, HotkeyRegistrationsResult, type HotkeySequenceDefinition, HotkeysProvider, type HotkeysProviderOptions, type HotkeysProviderProps, OctaneHotkeyRecorder, OctaneHotkeySequenceRecorder, useDefaultHotkeysOptions, useHeldKeyCodes, useHeldKeys, useHotkey, useHotkeyHint, useHotkeyRecorder, useHotkeyRegistrations, useHotkeySequence, useHotkeySequenceRecorder, useHotkeySequences, useHotkeys, useHotkeysContext, useKeyHold };
+export { type DefaultHotkeysOptions, HotkeyRegistrationsResult, HotkeysProvider, type HotkeysProviderOptions, type HotkeysProviderProps, OctaneHotkeyRecorder, 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 { useHotkeys } from "./useHotkeys.js";
 import { useHotkey } from "./useHotkey.js";
-import { useHotkeySequences } from "./useHotkeySequences.js";
-import { useHotkeySequence } from "./useHotkeySequence.js";
 import { useHeldKeys } from "./useHeldKeys.js";
 import { useHeldKeyCodes } from "./useHeldKeyCodes.js";
 import { useKeyHold } from "./useKeyHold.js";
 import { useHotkeyHint } from "./useHotkeyHint.js";
 import { useHotkeyRegistrations } from "./useHotkeyRegistrations.js";
 import { useHotkeyRecorder } from "./useHotkeyRecorder.js";
-import { useHotkeySequenceRecorder } from "./useHotkeySequenceRecorder.js";
+import { useAppHotkeyList, useAppHotkeys, useCustomHotkeys } from "./useAppHotkeys.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/internal.js

@@ -1,4 +1,4 @@
-import { useSelector } from "@tanstack/octane-store";
+import { Store, useSelector } from "@tanstack/octane-store";
 
 //#region src/internal.ts
 const subSlotCache = /* @__PURE__ */ new Map();
@@ -30,6 +30,15 @@ function splitSlot(args) {
 	return [slot === void 0 ? args : args.slice(0, -1), slot];
 }
 const select = useSelector;
+const NO_APP_HOTKEYS = new Store(null);
+/**
+* Re-renders when the provider's app hotkeys or custom hotkeys change and
+* returns the provider's store.
+*/
+function useAppHotkeysStore(store, slot) {
+	select(store?.store ?? NO_APP_HOTKEYS, (value) => value, void 0, slot);
+	return store;
+}
 
 //#endregion
-export { select, splitSlot, subSlot };
+export { select, splitSlot, subSlot, useAppHotkeysStore };

package/dist/types.d.ts

@@ -1,38 +1,41 @@
-import { Hotkey, HotkeyRegistrationView, HotkeySequence, SequenceRegistrationView } from "@tanstack/hotkeys";
+import { AppHotkey, CustomHotkeys, Hotkey, HotkeyRegistrationView, HotkeySequence, RegisteredAppHotkeys } from "@tanstack/hotkeys";
 //#region src/types.d.ts
 /** Recording state and controls owned by the containing component. */
-export interface OctaneHotkeyRecorder {
+export interface OctaneHotkeyRecorder<THotkey extends Hotkey = Hotkey> {
   /** Whether the recorder is listening for a shortcut. */
   isRecording: boolean;
-  /** The last recorded binding, including brackets for physical codes. */
-  recordedHotkey: Hotkey | null;
+  /** Chords captured so far in a multi-step recording. */
+  steps: HotkeySequence;
+  /** The last committed hotkey, including brackets for physical codes. */
+  recordedHotkey: THotkey | null;
   /** Start a new recording session. */
   startRecording: () => void;
   /** Stop and clear recorder state without calling onRecord or onCancel. */
   stopRecording: () => void;
   /** Stop, clear recorder state, and call onCancel. */
   cancelRecording: () => void;
-}
-/** Sequence recording state and controls. */
-export interface OctaneHotkeySequenceRecorder {
-  /** Whether the recorder is listening for chords. */
-  isRecording: boolean;
-  /** Chords captured in the current session. */
-  steps: HotkeySequence;
-  /** The last committed sequence. */
-  recordedSequence: HotkeySequence | null;
-  /** Start a new recording session. */
-  startRecording: () => void;
-  /** Stop without committing or calling onCancel. */
-  stopRecording: () => void;
-  /** Discard the current session and call onCancel. */
-  cancelRecording: () => void;
-  /** Commit the current steps. Does nothing when no steps are recorded. */
+  /** Commit the current steps (multi-step recordings). */
   commitRecording: () => void;
 }
-/** Live registration views from the shared hotkey and sequence managers. */
+/** Live registration views from the shared hotkey manager. */
 export interface HotkeyRegistrationsResult {
+  /** Every registration, chords and sequences. Narrow each view with `kind`. */
   hotkeys: Array<HotkeyRegistrationView>;
-  sequences: Array<SequenceRegistrationView>;
+}
+/** 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>;
 }
 //#endregion

package/dist/useAppHotkeys.d.ts

@@ -0,0 +1,21 @@
+import { UseCustomHotkeysResult } from "./types.js";
+import { AppHotkeyListItem, 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.
+ */
+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'`.
+ */
+export declare function useAppHotkeyList(): Array<AppHotkeyListItem<RegisteredAppHotkeys[keyof RegisteredAppHotkeys]>>;
+/**
+ * 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.
+ */
+export declare function useCustomHotkeys(): UseCustomHotkeysResult;
+//#endregion

package/dist/useAppHotkeys.js

@@ -0,0 +1,31 @@
+import { subSlot, useAppHotkeysStore } from "./internal.js";
+import { useHotkeysContext } from "./HotkeysProvider.js";
+import { useHotkeyRegistrations } from "./useHotkeyRegistrations.js";
+
+//#region src/useAppHotkeys.ts
+function useRequiredStore(name, slot) {
+	const store = useAppHotkeysStore(useHotkeysContext()?.appHotkeysStore ?? null, subSlot(slot, `${name}-store`));
+	if (!store) throw new Error(`${name} requires a HotkeysProvider with appHotkeys`);
+	return store;
+}
+function useAppHotkeys(slot) {
+	return useRequiredStore("useAppHotkeys", slot).appHotkeys;
+}
+function useAppHotkeyList(slot) {
+	const store = useRequiredStore("useAppHotkeyList", slot);
+	const registrations = useHotkeyRegistrations(subSlot(slot, "registrations"));
+	return store.getList(registrations.hotkeys);
+}
+function useCustomHotkeys(slot) {
+	const store = useRequiredStore("useCustomHotkeys", slot);
+	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,5 +1,25 @@
-import { HotkeyCallback, HotkeyOptions, RegisterableHotkey } from "@tanstack/hotkeys";
+import { AppHotkey, HotkeyCallback, RegisterableHotkey, Target } from "@tanstack/hotkeys";
+import { AdapterAppHotkeyOptions, AdapterChordOptions, AdapterCommonOptions, AdapterHotkeyOptions, AdapterOptionsFor, AdapterSequenceOptions } from "@tanstack/hotkeys/adapter";
 //#region src/useHotkey.d.ts
-/** Registers one shortcut. Callback and options are refreshed after every commit. */
-export declare function useHotkey(hotkey: RegisterableHotkey, callback: HotkeyCallback, options?: HotkeyOptions): void;
+/** The element to listen on. A `null` target skips registration until it is set. */
+export type UseHotkeyTarget = Target | 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>;
+/** Call-site options for an app hotkey, typed by its declared default kind. */
+export type UseAppHotkeyOptions<T extends AppHotkey = AppHotkey> = AdapterAppHotkeyOptions<T, UseHotkeyTarget>;
+/**
+ * Registers one hotkey: a chord such as `'Mod+S'`, a sequence such as
+ * `['G', 'G']`, or an app hotkey from `defineAppHotkeys`. The callback and
+ * 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;
 //#endregion

package/dist/useHotkey.js

@@ -6,8 +6,9 @@ function useHotkey(hotkey, callback, ...rest) {
 	const [args, slot] = splitSlot(rest);
 	useHotkeys([{
 		hotkey,
-		callback
-	}], args[0], subSlot(slot, "hotkey"));
+		callback,
+		options: args[0]
+	}], void 0, subSlot(slot, "hotkey"));
 }
 
 //#endregion

package/dist/useHotkeyHint.d.ts

@@ -1,5 +1,9 @@
-import { HeldModifierOptions, RegisterableHotkey } from "@tanstack/hotkeys";
+import { AppHotkey, HeldModifierOptions, RegisterableHotkey } from "@tanstack/hotkeys";
 //#region src/useHotkeyHint.d.ts
-/** Reports whether held modifiers reveal a shortcut hint. */
-export declare function useHotkeyHint(hotkey: RegisterableHotkey, options?: HeldModifierOptions): boolean;
+/**
+ * Reports whether held modifiers reveal a shortcut hint. A sequence reveals
+ * its hint from its first step, and an app hotkey uses its effective hotkey
+ * (false while unbound).
+ */
+export declare function useHotkeyHint(hotkey: RegisterableHotkey | AppHotkey, options?: HeldModifierOptions): boolean;
 //#endregion

package/dist/useHotkeyHint.js

@@ -1,10 +1,13 @@
-import { select, splitSlot, subSlot } from "./internal.js";
-import { getKeyStateTracker, matchesHeldModifiers } from "@tanstack/hotkeys";
+import { select, splitSlot, subSlot, useAppHotkeysStore } from "./internal.js";
+import { useHotkeysContext } from "./HotkeysProvider.js";
+import { getKeyStateTracker, isAppHotkey, matchesHeldModifiers, resolveAppHotkey } from "@tanstack/hotkeys";
 
 //#region src/useHotkeyHint.ts
 function useHotkeyHint(hotkey, ...rest) {
 	const [args, slot] = splitSlot(rest);
-	return select(getKeyStateTracker().store, (state) => matchesHeldModifiers(hotkey, state.heldKeys, args[0]), void 0, subSlot(slot, "hint"));
+	const store = useAppHotkeysStore(useHotkeysContext()?.appHotkeysStore ?? null, subSlot(slot, "app-hotkeys"));
+	const resolved = isAppHotkey(hotkey) ? resolveAppHotkey(hotkey, store).hotkey : hotkey;
+	return select(getKeyStateTracker().store, (state) => resolved !== null && matchesHeldModifiers(resolved, state.heldKeys, args[0]), void 0, subSlot(slot, "hint"));
 }
 
 //#endregion

package/dist/useHotkeyRecorder.d.ts

@@ -1,6 +1,13 @@
 import { OctaneHotkeyRecorder } from "./types.js";
-import { HotkeyRecorderOptions } from "@tanstack/hotkeys";
+import { HotkeyChord, HotkeyChordRecorderOptions, HotkeySequenceRecorderOptions } from "@tanstack/hotkeys";
 //#region src/useHotkeyRecorder.d.ts
-/** Records a shortcut and destroys the recorder on unmount. */
-export declare function useHotkeyRecorder(options: HotkeyRecorderOptions): OctaneHotkeyRecorder;
+/**
+ * Records a shortcut and destroys the recorder on unmount. With the default
+ * `maxSteps: 1`, the first valid chord is recorded. With a larger `maxSteps`,
+ * each chord adds a step; the recording commits on Enter (unless
+ * `commitKeys: 'none'`), after `idleTimeoutMs`, or at `maxSteps`, and
+ * `onRecord` receives a chord (one step) or a sequence.
+ */
+export declare function useHotkeyRecorder(options: HotkeyChordRecorderOptions): OctaneHotkeyRecorder<HotkeyChord>;
+export declare function useHotkeyRecorder(options: HotkeySequenceRecorderOptions): OctaneHotkeyRecorder;
 //#endregion

package/dist/useHotkeyRecorder.js

@@ -1,5 +1,5 @@
-import { useDefaultHotkeysOptions } from "./HotkeysProvider.js";
 import { select, subSlot } from "./internal.js";
+import { useDefaultHotkeysOptions } from "./HotkeysProvider.js";
 import { HotkeyRecorder } from "@tanstack/hotkeys";
 import { useLayoutEffect, useRef } from "octane";
 
@@ -20,7 +20,8 @@ function useHotkeyRecorder(options, slot) {
 		...select(recorder.store, (value) => value, void 0, subSlot(slot, "state")),
 		startRecording: () => recorder.start(),
 		stopRecording: () => recorder.stop(),
-		cancelRecording: () => recorder.cancel()
+		cancelRecording: () => recorder.cancel(),
+		commitRecording: () => recorder.commit()
 	};
 }
 

package/dist/useHotkeyRegistrations.d.ts

@@ -1,5 +1,5 @@
 import { HotkeyRegistrationsResult } from "./types.js";
 //#region src/useHotkeyRegistrations.d.ts
-/** Reads public registration snapshots from both managers. */
+/** Reads public snapshots of every registration, chords and sequences. */
 export declare function useHotkeyRegistrations(): HotkeyRegistrationsResult;
 //#endregion

package/dist/useHotkeyRegistrations.js

@@ -1,12 +1,9 @@
 import { select, subSlot } from "./internal.js";
-import { getHotkeyManager, getSequenceManager, toHotkeyRegistrationView } from "@tanstack/hotkeys";
+import { getHotkeyManager, toHotkeyRegistrationView } from "@tanstack/hotkeys";
 
 //#region src/useHotkeyRegistrations.ts
 function useHotkeyRegistrations(slot) {
-	return {
-		hotkeys: select(getHotkeyManager().registrations, (state) => Array.from(state.values()).map(toHotkeyRegistrationView), void 0, subSlot(slot, "hotkeys")),
-		sequences: select(getSequenceManager().registrations, (state) => Array.from(state.values()), void 0, subSlot(slot, "sequences"))
-	};
+	return { hotkeys: select(getHotkeyManager().registrations, (state) => Array.from(state.values()).map(toHotkeyRegistrationView), void 0, subSlot(slot, "hotkeys")) };
 }
 
 //#endregion

package/dist/useHotkeys.d.ts

@@ -1,6 +1,16 @@
-import { HotkeyOptions } from "@tanstack/hotkeys";
-import { HotkeyDefinition } from "@tanstack/hotkeys/adapter";
+import { UseHotkeyCommonOptions, UseHotkeyTarget } from "./useHotkey.js";
+import { AdapterHotkeyDefinition } from "@tanstack/hotkeys/adapter";
 //#region src/useHotkeys.d.ts
-/** Registers a changing list of shortcuts after commit and releases it on unmount. */
-export declare function useHotkeys(definitions: Array<HotkeyDefinition>, options?: HotkeyOptions): void;
+/**
+ * One hotkey for `useHotkeys`. Chords accept `requireReset`; sequences accept
+ * `timeout`; hotkeys of unknown kind accept only shared options.
+ */
+export type UseHotkeyDefinition = AdapterHotkeyDefinition<UseHotkeyTarget>;
+/**
+ * Registers a changing list of hotkeys (chords, sequences, and app hotkeys)
+ * after commit and releases it on unmount. Options merge in this order:
+ * provider defaults, app hotkey declaration, common options, per-hotkey
+ * options. Unbound app hotkeys and empty sequences register nothing.
+ */
+export declare function useHotkeys(definitions: ReadonlyArray<UseHotkeyDefinition>, options?: UseHotkeyCommonOptions): void;
 //#endregion

package/dist/useHotkeys.js

@@ -1,20 +1,24 @@
-import { useDefaultHotkeysOptions } from "./HotkeysProvider.js";
-import { splitSlot, subSlot } from "./internal.js";
+import { splitSlot, subSlot, useAppHotkeysStore } from "./internal.js";
+import { useHotkeysContext } from "./HotkeysProvider.js";
 import { useLayoutEffect, useRef } from "octane";
-import { createHotkeyBindings } from "@tanstack/hotkeys/adapter";
+import { createHotkeyBindings, prepareHotkeyDefinitions } from "@tanstack/hotkeys/adapter";
 
 //#region src/useHotkeys.ts
 function useHotkeys(definitions, ...rest) {
 	const [args, slot] = splitSlot(rest);
-	const options = {
-		...useDefaultHotkeysOptions().hotkey,
-		...args[0]
-	};
+	const context = useHotkeysContext();
+	const appHotkeysStore = useAppHotkeysStore(context?.appHotkeysStore ?? null, subSlot(slot, "app-hotkeys"));
+	const commonOptions = args[0];
 	const ref = useRef(null, subSlot(slot, "bindings"));
 	ref.current ??= createHotkeyBindings();
 	const bindings = ref.current;
 	useLayoutEffect(() => {
-		bindings.update(definitions, options);
+		bindings.update(prepareHotkeyDefinitions(definitions, {
+			appHotkeysStore,
+			defaults: context?.defaultOptions.hotkey,
+			commonOptions,
+			resolveTarget: (target) => target
+		}));
 	}, null, subSlot(slot, "update"));
 	useLayoutEffect(() => () => bindings.destroy(), [], subSlot(slot, "cleanup"));
 }

package/package.json

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

package/dist/useHotkeySequence.d.ts

@@ -1,5 +0,0 @@
-import { HotkeyCallback, HotkeySequence, SequenceOptions } from "@tanstack/hotkeys";
-//#region src/useHotkeySequence.d.ts
-/** Registers one multi-chord shortcut. Empty sequences do not register. */
-export declare function useHotkeySequence(sequence: HotkeySequence, callback: HotkeyCallback, options?: SequenceOptions): void;
-//#endregion

package/dist/useHotkeySequence.js

@@ -1,14 +0,0 @@
-import { splitSlot, subSlot } from "./internal.js";
-import { useHotkeySequences } from "./useHotkeySequences.js";
-
-//#region src/useHotkeySequence.ts
-function useHotkeySequence(sequence, callback, ...rest) {
-	const [args, slot] = splitSlot(rest);
-	useHotkeySequences([{
-		sequence,
-		callback
-	}], args[0], subSlot(slot, "sequence"));
-}
-
-//#endregion
-export { useHotkeySequence };

package/dist/useHotkeySequenceRecorder.d.ts

@@ -1,6 +0,0 @@
-import { OctaneHotkeySequenceRecorder } from "./types.js";
-import { HotkeySequenceRecorderOptions } from "@tanstack/hotkeys";
-//#region src/useHotkeySequenceRecorder.d.ts
-/** Records a sequence, including live steps and explicit commit/cancel controls. */
-export declare function useHotkeySequenceRecorder(options: HotkeySequenceRecorderOptions): OctaneHotkeySequenceRecorder;
-//#endregion

package/dist/useHotkeySequenceRecorder.js

@@ -1,29 +0,0 @@
-import { useDefaultHotkeysOptions } from "./HotkeysProvider.js";
-import { select, subSlot } from "./internal.js";
-import { HotkeySequenceRecorder } from "@tanstack/hotkeys";
-import { useLayoutEffect, useRef } from "octane";
-
-//#region src/useHotkeySequenceRecorder.ts
-function useHotkeySequenceRecorder(options, slot) {
-	const merged = {
-		...useDefaultHotkeysOptions().hotkeySequenceRecorder,
-		...options
-	};
-	const ref = useRef(null, subSlot(slot, "recorder"));
-	ref.current ??= new HotkeySequenceRecorder(merged);
-	const recorder = ref.current;
-	useLayoutEffect(() => {
-		recorder.setOptions(merged);
-	}, null, subSlot(slot, "options"));
-	useLayoutEffect(() => () => recorder.destroy(), [], subSlot(slot, "cleanup"));
-	return {
-		...select(recorder.store, (value) => value, void 0, subSlot(slot, "state")),
-		startRecording: () => recorder.start(),
-		stopRecording: () => recorder.stop(),
-		cancelRecording: () => recorder.cancel(),
-		commitRecording: () => recorder.commit()
-	};
-}
-
-//#endregion
-export { useHotkeySequenceRecorder };

package/dist/useHotkeySequences.d.ts

@@ -1,6 +0,0 @@
-import { SequenceOptions } from "@tanstack/hotkeys";
-import { HotkeySequenceDefinition } from "@tanstack/hotkeys/adapter";
-//#region src/useHotkeySequences.d.ts
-/** Registers a changing list of sequences and releases it on unmount. */
-export declare function useHotkeySequences(definitions: Array<HotkeySequenceDefinition>, options?: SequenceOptions): void;
-//#endregion

package/dist/useHotkeySequences.js

@@ -1,23 +0,0 @@
-import { useDefaultHotkeysOptions } from "./HotkeysProvider.js";
-import { splitSlot, subSlot } from "./internal.js";
-import { useLayoutEffect, useRef } from "octane";
-import { createHotkeySequenceBindings } from "@tanstack/hotkeys/adapter";
-
-//#region src/useHotkeySequences.ts
-function useHotkeySequences(definitions, ...rest) {
-	const [args, slot] = splitSlot(rest);
-	const options = {
-		...useDefaultHotkeysOptions().hotkeySequence,
-		...args[0]
-	};
-	const ref = useRef(null, subSlot(slot, "bindings"));
-	ref.current ??= createHotkeySequenceBindings();
-	const bindings = ref.current;
-	useLayoutEffect(() => {
-		bindings.update(definitions, options);
-	}, null, subSlot(slot, "update"));
-	useLayoutEffect(() => () => bindings.destroy(), [], subSlot(slot, "cleanup"));
-}
-
-//#endregion
-export { useHotkeySequences };