@remcostoeten/use-shortcut 1.3.0 → 2.0.0

package/dist/index.d.mts

@@ -1,10 +1,22 @@
+/** Supported runtime OS identifiers used by formatter and parser normalization. */
+declare const OS: {
+    readonly MAC: "mac";
+    readonly WINDOWS: "windows";
+    readonly LINUX: "linux";
+};
+type PlatformType = (typeof OS)[keyof typeof OS];
+/** Public platform constant alias (`Platform.MAC`, `Platform.WINDOWS`, `Platform.LINUX`). */
 declare const Platform: {
     readonly MAC: "mac";
     readonly WINDOWS: "windows";
     readonly LINUX: "linux";
 };
-type PlatformType = (typeof Platform)[keyof typeof Platform];
+/**
+ * Detect the current OS platform for modifier normalization and display formatting.
+ * Result is memoized for the page lifecycle.
+ */
 declare function detectPlatform(): PlatformType;
+/** Canonical modifier token names used internally across parsing/formatting. */
 declare const ModifierKey: {
     readonly META: "meta";
     readonly CTRL: "ctrl";
@@ -12,9 +24,13 @@ declare const ModifierKey: {
     readonly SHIFT: "shift";
 };
 type ModifierKeyType = (typeof ModifierKey)[keyof typeof ModifierKey];
+/** Alias map from user-facing modifier tokens to canonical modifier keys. */
 declare const ModifierAliases: Record<string, ModifierKeyType>;
+/** Alias map from human shortcut key tokens to `KeyboardEvent.key`-compatible values. */
 declare const SpecialKeyMap: Record<string, string>;
+/** Platform-specific display labels/symbols for modifier keys. */
 declare const ModifierDisplaySymbols: Record<PlatformType, Record<ModifierKeyType, string>>;
+/** Platform-specific canonical order for modifier rendering and combo normalization. */
 declare const ModifierDisplayOrder: Record<PlatformType, ModifierKeyType[]>;
 
 /** Lowercase letter keys a-z */
@@ -77,7 +93,9 @@ type ExceptPredicate = (event: KeyboardEvent) => boolean;
  * - "disabled" - Skip when focused element is disabled
  */
 type ExceptPreset = "input" | "editable" | "typing" | "modal" | "disabled";
+/** Scope selector used to enable/disable subsets of shortcuts at runtime. */
 type ShortcutScope = string | string[];
+/** Conflict metadata emitted when two registered shortcuts overlap. */
 type ShortcutConflict = {
     combo: string;
     existingCombo: string;
@@ -97,8 +115,6 @@ type HandlerOptions = {
     description?: string;
     /** Disable this specific shortcut */
     disabled?: boolean;
-    /** Limit shortcut to a specific DOM element */
-    scope?: HTMLElement | null;
     /** Conditions to skip the shortcut */
     except?: ExceptPreset | ExceptPreset[] | ExceptPredicate;
     /** Required named scopes that must be active */
@@ -152,13 +168,13 @@ type ModifierChain<Used extends Partial<ModifierFlags>> = {
     mod: Used["cmd"] extends true ? never : ModifierChain<Used & {
         cmd: true;
     }>;
-    key: <K extends ActionKey>(key: K) => KeyChain<Used, K>;
+    key: <K extends ActionKey>(key: K) => KeyChain<K>;
     in: (scopes: ShortcutScope) => ModifierChain<Used>;
 };
 /**
  * Chain state after calling `.key()` - ready to attach a handler
  */
-type KeyChain<Used extends Partial<ModifierFlags>, Key extends string> = {
+type KeyChain<Key extends string> = {
     /** Attach a handler to this shortcut */
     on: (handler: ShortcutHandler, options?: HandlerOptions) => ShortcutResult;
     /** Attach a handler with inline options */
@@ -166,20 +182,21 @@ type KeyChain<Used extends Partial<ModifierFlags>, Key extends string> = {
         handler: ShortcutHandler;
     }) => ShortcutResult;
     /** Add exception conditions before attaching handler */
-    except: (condition: ExceptPreset | ExceptPreset[] | ExceptPredicate) => KeyChainWithExcept<Used, Key>;
+    except: (condition: ExceptPreset | ExceptPreset[] | ExceptPredicate) => KeyChainWithExcept<Key>;
     /** Add required named scopes */
-    in: (scopes: ShortcutScope) => KeyChain<Used, Key>;
+    in: (scopes: ShortcutScope) => KeyChain<Key>;
     /** Add the next step in a sequence */
-    then: <K extends ActionKey | string>(key: K) => KeyChain<Used, `${Key} ${K}`>;
+    then: <K extends ActionKey | string>(key: K) => KeyChain<`${Key} ${K}`>;
 };
 /**
  * Chain state after calling `.except()` - ready to attach handler
  */
-type KeyChainWithExcept<Used extends Partial<ModifierFlags>, Key extends string> = {
+type KeyChainWithExcept<Key extends string> = {
     on: (handler: ShortcutHandler, options?: Omit<HandlerOptions, "except">) => ShortcutResult;
-    in: (scopes: ShortcutScope) => KeyChainWithExcept<Used, Key>;
-    then: <K extends ActionKey | string>(key: K) => KeyChainWithExcept<Used, `${Key} ${K}`>;
+    in: (scopes: ShortcutScope) => KeyChainWithExcept<Key>;
+    then: <K extends ActionKey | string>(key: K) => KeyChainWithExcept<`${Key} ${K}`>;
 };
+/** Options for `ShortcutBuilder.record()` and low-level recording flows. */
 type ShortcutRecordingOptions = {
     target?: HTMLElement | Window | null;
     eventType?: "keydown" | "keyup";
@@ -204,7 +221,7 @@ type ShortcutBuilder = ModifierChain<EmptyModifiers> & {
     mod: ModifierChain<{
         cmd: true;
     }>;
-    key: <K extends ActionKey>(key: K) => KeyChain<EmptyModifiers, K>;
+    key: <K extends ActionKey>(key: K) => KeyChain<K>;
     /** Set required scopes for upcoming chain calls */
     in: (scopes: ShortcutScope) => ShortcutBuilder;
     /** Update active scopes at runtime */
@@ -247,22 +264,6 @@ type UseShortcutOptions = {
     /** Global event filter; return false to skip all shortcuts for the event */
     eventFilter?: (event: KeyboardEvent) => boolean;
 };
-type ShortcutMapEntry = {
-    keys: string | string[];
-    handler: ShortcutHandler;
-    options?: HandlerOptions;
-};
-type ShortcutMap = Record<string, ShortcutMapEntry>;
-type ShortcutMapResult<T extends ShortcutMap = ShortcutMap> = {
-    [K in keyof T]: ShortcutResult;
-};
-type ShortcutGroup = {
-    add: (...results: ShortcutResult[]) => void;
-    addMany: (results: ShortcutResult[] | Record<string, ShortcutResult>) => void;
-    unbindAll: () => void;
-    clear: () => void;
-    getResults: () => ShortcutResult[];
-};
 
 /**
  * Parse a shortcut string into its components
@@ -284,13 +285,6 @@ declare function parseShortcut(shortcut: string): ParsedShortcut;
  * @returns Array of parsed shortcuts
  */
 declare function parseShortcuts(shortcuts: string | string[]): ParsedShortcut[];
-/**
- * Extract modifier state from a keyboard event
- *
- * @param event - The keyboard event
- * @returns Object with meta, ctrl, alt, shift boolean flags
- */
-declare function getModifiersFromEvent(event: KeyboardEvent): ModifierState;
 /**
  * Check if a keyboard event matches a parsed shortcut
  *
@@ -322,45 +316,22 @@ declare function matchesAnyShortcut(event: KeyboardEvent, parsedShortcuts: Parse
  * ```
  */
 declare function formatShortcut(shortcut: string, platform?: PlatformType): string;
-/**
- * Get the modifier key symbols for a platform
- *
- * @param platform - Optional platform override (default: auto-detect)
- * @returns Object mapping modifier keys to display symbols
- *
- * @example
- * ```ts
- * getModifierSymbols("mac") // { meta: "⌘", ctrl: "⌃", alt: "⌥", shift: "⇧" }
- * ```
- */
-declare function getModifierSymbols(platform?: PlatformType): Record<ModifierKeyType, string>;
 
-declare function registerShortcutMap<T extends ShortcutMap>(builder: ShortcutBuilder, shortcutMap: T): ShortcutMapResult<T>;
 /**
  * React hook for registering chainable keyboard shortcuts
  *
  * @param options - Configuration options for the hook
  * @returns A chainable shortcut builder (`$`)
- */
-declare function useShortcut(options?: UseShortcutOptions): ShortcutBuilder;
-/**
- * Bulk registration helper for shortcut maps.
- */
-declare function useShortcutMap<T extends ShortcutMap>(shortcutMap: T, options?: UseShortcutOptions): ShortcutMapResult<T>;
-/**
- * Create a shortcut builder for non-React usage
- *
- * Unlike `useShortcut`, this does not auto-cleanup - you must call `.unbind()` manually.
  *
- * @param options - Configuration options
- * @returns A chainable shortcut builder
- */
-declare function createShortcut(options?: UseShortcutOptions): ShortcutBuilder;
-/**
- * Bulk registration helper for non-React usage.
+ * @example
+ * ```ts
+ * const $ = useShortcut({ activeScopes: ["editor"] })
+ * $.mod.key("s").on((event) => {
+ *   event.preventDefault()
+ *   saveDocument()
+ * })
+ * ```
  */
-declare function createShortcutMap<T extends ShortcutMap>(shortcutMap: T, options?: UseShortcutOptions): ShortcutMapResult<T>;
-declare function createShortcutGroup(): ShortcutGroup;
-declare function useShortcutGroup(): ShortcutGroup;
+declare function useShortcut(options?: UseShortcutOptions): ShortcutBuilder;
 
-export { type ActionKey, type AlphaKey, type ExceptPredicate, type ExceptPreset, type FunctionKey, type HandlerOptions, type KeyChain, ModifierAliases, type ModifierChain, ModifierDisplayOrder, ModifierDisplaySymbols, type ModifierFlags, ModifierKey, type ModifierName, type ModifierState, type NavigationKey, type NumericKey, type ParsedShortcut, Platform, type ShortcutBuilder, type ShortcutConflict, type ShortcutGroup, type ShortcutHandler, type ShortcutMap, type ShortcutMapEntry, type ShortcutMapResult, type ShortcutRecordingOptions, type ShortcutResult, type ShortcutScope, type SpecialKey, SpecialKeyMap, type SymbolKey, type UseShortcutOptions, createShortcut, createShortcutGroup, createShortcutMap, detectPlatform, formatShortcut, getModifierSymbols, getModifiersFromEvent, matchesAnyShortcut, matchesShortcut, parseShortcut, parseShortcuts, registerShortcutMap, useShortcut, useShortcutGroup, useShortcutMap };
+export { type ActionKey, type AlphaKey, type ExceptPredicate, type ExceptPreset, type FunctionKey, type HandlerOptions, type KeyChain, ModifierAliases, type ModifierChain, ModifierDisplayOrder, ModifierDisplaySymbols, type ModifierFlags, ModifierKey, type ModifierName, type ModifierState, type NavigationKey, type NumericKey, type ParsedShortcut, Platform, type ShortcutBuilder, type ShortcutConflict, type ShortcutHandler, type ShortcutRecordingOptions, type ShortcutResult, type ShortcutScope, type SpecialKey, SpecialKeyMap, type SymbolKey, type UseShortcutOptions, detectPlatform, formatShortcut, matchesAnyShortcut, matchesShortcut, parseShortcut, parseShortcuts, useShortcut };

package/dist/index.d.ts

@@ -1,10 +1,22 @@
+/** Supported runtime OS identifiers used by formatter and parser normalization. */
+declare const OS: {
+    readonly MAC: "mac";
+    readonly WINDOWS: "windows";
+    readonly LINUX: "linux";
+};
+type PlatformType = (typeof OS)[keyof typeof OS];
+/** Public platform constant alias (`Platform.MAC`, `Platform.WINDOWS`, `Platform.LINUX`). */
 declare const Platform: {
     readonly MAC: "mac";
     readonly WINDOWS: "windows";
     readonly LINUX: "linux";
 };
-type PlatformType = (typeof Platform)[keyof typeof Platform];
+/**
+ * Detect the current OS platform for modifier normalization and display formatting.
+ * Result is memoized for the page lifecycle.
+ */
 declare function detectPlatform(): PlatformType;
+/** Canonical modifier token names used internally across parsing/formatting. */
 declare const ModifierKey: {
     readonly META: "meta";
     readonly CTRL: "ctrl";
@@ -12,9 +24,13 @@ declare const ModifierKey: {
     readonly SHIFT: "shift";
 };
 type ModifierKeyType = (typeof ModifierKey)[keyof typeof ModifierKey];
+/** Alias map from user-facing modifier tokens to canonical modifier keys. */
 declare const ModifierAliases: Record<string, ModifierKeyType>;
+/** Alias map from human shortcut key tokens to `KeyboardEvent.key`-compatible values. */
 declare const SpecialKeyMap: Record<string, string>;
+/** Platform-specific display labels/symbols for modifier keys. */
 declare const ModifierDisplaySymbols: Record<PlatformType, Record<ModifierKeyType, string>>;
+/** Platform-specific canonical order for modifier rendering and combo normalization. */
 declare const ModifierDisplayOrder: Record<PlatformType, ModifierKeyType[]>;
 
 /** Lowercase letter keys a-z */
@@ -77,7 +93,9 @@ type ExceptPredicate = (event: KeyboardEvent) => boolean;
  * - "disabled" - Skip when focused element is disabled
  */
 type ExceptPreset = "input" | "editable" | "typing" | "modal" | "disabled";
+/** Scope selector used to enable/disable subsets of shortcuts at runtime. */
 type ShortcutScope = string | string[];
+/** Conflict metadata emitted when two registered shortcuts overlap. */
 type ShortcutConflict = {
     combo: string;
     existingCombo: string;
@@ -97,8 +115,6 @@ type HandlerOptions = {
     description?: string;
     /** Disable this specific shortcut */
     disabled?: boolean;
-    /** Limit shortcut to a specific DOM element */
-    scope?: HTMLElement | null;
     /** Conditions to skip the shortcut */
     except?: ExceptPreset | ExceptPreset[] | ExceptPredicate;
     /** Required named scopes that must be active */
@@ -152,13 +168,13 @@ type ModifierChain<Used extends Partial<ModifierFlags>> = {
     mod: Used["cmd"] extends true ? never : ModifierChain<Used & {
         cmd: true;
     }>;
-    key: <K extends ActionKey>(key: K) => KeyChain<Used, K>;
+    key: <K extends ActionKey>(key: K) => KeyChain<K>;
     in: (scopes: ShortcutScope) => ModifierChain<Used>;
 };
 /**
  * Chain state after calling `.key()` - ready to attach a handler
  */
-type KeyChain<Used extends Partial<ModifierFlags>, Key extends string> = {
+type KeyChain<Key extends string> = {
     /** Attach a handler to this shortcut */
     on: (handler: ShortcutHandler, options?: HandlerOptions) => ShortcutResult;
     /** Attach a handler with inline options */
@@ -166,20 +182,21 @@ type KeyChain<Used extends Partial<ModifierFlags>, Key extends string> = {
         handler: ShortcutHandler;
     }) => ShortcutResult;
     /** Add exception conditions before attaching handler */
-    except: (condition: ExceptPreset | ExceptPreset[] | ExceptPredicate) => KeyChainWithExcept<Used, Key>;
+    except: (condition: ExceptPreset | ExceptPreset[] | ExceptPredicate) => KeyChainWithExcept<Key>;
     /** Add required named scopes */
-    in: (scopes: ShortcutScope) => KeyChain<Used, Key>;
+    in: (scopes: ShortcutScope) => KeyChain<Key>;
     /** Add the next step in a sequence */
-    then: <K extends ActionKey | string>(key: K) => KeyChain<Used, `${Key} ${K}`>;
+    then: <K extends ActionKey | string>(key: K) => KeyChain<`${Key} ${K}`>;
 };
 /**
  * Chain state after calling `.except()` - ready to attach handler
  */
-type KeyChainWithExcept<Used extends Partial<ModifierFlags>, Key extends string> = {
+type KeyChainWithExcept<Key extends string> = {
     on: (handler: ShortcutHandler, options?: Omit<HandlerOptions, "except">) => ShortcutResult;
-    in: (scopes: ShortcutScope) => KeyChainWithExcept<Used, Key>;
-    then: <K extends ActionKey | string>(key: K) => KeyChainWithExcept<Used, `${Key} ${K}`>;
+    in: (scopes: ShortcutScope) => KeyChainWithExcept<Key>;
+    then: <K extends ActionKey | string>(key: K) => KeyChainWithExcept<`${Key} ${K}`>;
 };
+/** Options for `ShortcutBuilder.record()` and low-level recording flows. */
 type ShortcutRecordingOptions = {
     target?: HTMLElement | Window | null;
     eventType?: "keydown" | "keyup";
@@ -204,7 +221,7 @@ type ShortcutBuilder = ModifierChain<EmptyModifiers> & {
     mod: ModifierChain<{
         cmd: true;
     }>;
-    key: <K extends ActionKey>(key: K) => KeyChain<EmptyModifiers, K>;
+    key: <K extends ActionKey>(key: K) => KeyChain<K>;
     /** Set required scopes for upcoming chain calls */
     in: (scopes: ShortcutScope) => ShortcutBuilder;
     /** Update active scopes at runtime */
@@ -247,22 +264,6 @@ type UseShortcutOptions = {
     /** Global event filter; return false to skip all shortcuts for the event */
     eventFilter?: (event: KeyboardEvent) => boolean;
 };
-type ShortcutMapEntry = {
-    keys: string | string[];
-    handler: ShortcutHandler;
-    options?: HandlerOptions;
-};
-type ShortcutMap = Record<string, ShortcutMapEntry>;
-type ShortcutMapResult<T extends ShortcutMap = ShortcutMap> = {
-    [K in keyof T]: ShortcutResult;
-};
-type ShortcutGroup = {
-    add: (...results: ShortcutResult[]) => void;
-    addMany: (results: ShortcutResult[] | Record<string, ShortcutResult>) => void;
-    unbindAll: () => void;
-    clear: () => void;
-    getResults: () => ShortcutResult[];
-};
 
 /**
  * Parse a shortcut string into its components
@@ -284,13 +285,6 @@ declare function parseShortcut(shortcut: string): ParsedShortcut;
  * @returns Array of parsed shortcuts
  */
 declare function parseShortcuts(shortcuts: string | string[]): ParsedShortcut[];
-/**
- * Extract modifier state from a keyboard event
- *
- * @param event - The keyboard event
- * @returns Object with meta, ctrl, alt, shift boolean flags
- */
-declare function getModifiersFromEvent(event: KeyboardEvent): ModifierState;
 /**
  * Check if a keyboard event matches a parsed shortcut
  *
@@ -322,45 +316,22 @@ declare function matchesAnyShortcut(event: KeyboardEvent, parsedShortcuts: Parse
  * ```
  */
 declare function formatShortcut(shortcut: string, platform?: PlatformType): string;
-/**
- * Get the modifier key symbols for a platform
- *
- * @param platform - Optional platform override (default: auto-detect)
- * @returns Object mapping modifier keys to display symbols
- *
- * @example
- * ```ts
- * getModifierSymbols("mac") // { meta: "⌘", ctrl: "⌃", alt: "⌥", shift: "⇧" }
- * ```
- */
-declare function getModifierSymbols(platform?: PlatformType): Record<ModifierKeyType, string>;
 
-declare function registerShortcutMap<T extends ShortcutMap>(builder: ShortcutBuilder, shortcutMap: T): ShortcutMapResult<T>;
 /**
  * React hook for registering chainable keyboard shortcuts
  *
  * @param options - Configuration options for the hook
  * @returns A chainable shortcut builder (`$`)
- */
-declare function useShortcut(options?: UseShortcutOptions): ShortcutBuilder;
-/**
- * Bulk registration helper for shortcut maps.
- */
-declare function useShortcutMap<T extends ShortcutMap>(shortcutMap: T, options?: UseShortcutOptions): ShortcutMapResult<T>;
-/**
- * Create a shortcut builder for non-React usage
- *
- * Unlike `useShortcut`, this does not auto-cleanup - you must call `.unbind()` manually.
  *
- * @param options - Configuration options
- * @returns A chainable shortcut builder
- */
-declare function createShortcut(options?: UseShortcutOptions): ShortcutBuilder;
-/**
- * Bulk registration helper for non-React usage.
+ * @example
+ * ```ts
+ * const $ = useShortcut({ activeScopes: ["editor"] })
+ * $.mod.key("s").on((event) => {
+ *   event.preventDefault()
+ *   saveDocument()
+ * })
+ * ```
  */
-declare function createShortcutMap<T extends ShortcutMap>(shortcutMap: T, options?: UseShortcutOptions): ShortcutMapResult<T>;
-declare function createShortcutGroup(): ShortcutGroup;
-declare function useShortcutGroup(): ShortcutGroup;
+declare function useShortcut(options?: UseShortcutOptions): ShortcutBuilder;
 
-export { type ActionKey, type AlphaKey, type ExceptPredicate, type ExceptPreset, type FunctionKey, type HandlerOptions, type KeyChain, ModifierAliases, type ModifierChain, ModifierDisplayOrder, ModifierDisplaySymbols, type ModifierFlags, ModifierKey, type ModifierName, type ModifierState, type NavigationKey, type NumericKey, type ParsedShortcut, Platform, type ShortcutBuilder, type ShortcutConflict, type ShortcutGroup, type ShortcutHandler, type ShortcutMap, type ShortcutMapEntry, type ShortcutMapResult, type ShortcutRecordingOptions, type ShortcutResult, type ShortcutScope, type SpecialKey, SpecialKeyMap, type SymbolKey, type UseShortcutOptions, createShortcut, createShortcutGroup, createShortcutMap, detectPlatform, formatShortcut, getModifierSymbols, getModifiersFromEvent, matchesAnyShortcut, matchesShortcut, parseShortcut, parseShortcuts, registerShortcutMap, useShortcut, useShortcutGroup, useShortcutMap };
+export { type ActionKey, type AlphaKey, type ExceptPredicate, type ExceptPreset, type FunctionKey, type HandlerOptions, type KeyChain, ModifierAliases, type ModifierChain, ModifierDisplayOrder, ModifierDisplaySymbols, type ModifierFlags, ModifierKey, type ModifierName, type ModifierState, type NavigationKey, type NumericKey, type ParsedShortcut, Platform, type ShortcutBuilder, type ShortcutConflict, type ShortcutHandler, type ShortcutRecordingOptions, type ShortcutResult, type ShortcutScope, type SpecialKey, SpecialKeyMap, type SymbolKey, type UseShortcutOptions, detectPlatform, formatShortcut, matchesAnyShortcut, matchesShortcut, parseShortcut, parseShortcuts, useShortcut };