@tanstack/hotkeys 0.0.1 → 0.1.0

package/dist/constants.d.cts

@@ -0,0 +1,226 @@
+import { CanonicalModifier, EditingKey, FunctionKey, LetterKey, NavigationKey, NumberKey, PunctuationKey } from "./hotkey.cjs";
+
+//#region src/constants.d.ts
+/**
+ * Detects the current platform based on browser navigator properties.
+ *
+ * Used internally to resolve platform-adaptive modifiers like 'Mod' (Command on Mac,
+ * Control elsewhere) and for platform-specific hotkey formatting.
+ *
+ * @returns The detected platform: 'mac', 'windows', or 'linux'
+ * @remarks Defaults to 'linux' in SSR environments where navigator is undefined
+ *
+ * @example
+ * ```ts
+ * const platform = detectPlatform() // 'mac' | 'windows' | 'linux'
+ * const modifier = resolveModifier('Mod', platform) // 'Meta' on Mac, 'Control' elsewhere
+ * ```
+ */
+declare function detectPlatform(): 'mac' | 'windows' | 'linux';
+/**
+ * Canonical order for modifiers in normalized hotkey strings.
+ *
+ * Defines the standard order in which modifiers should appear when formatting
+ * hotkeys. This ensures consistent, predictable output across the library.
+ *
+ * Order: Control → Alt → Shift → Meta
+ *
+ * @example
+ * ```ts
+ * // Input: 'Shift+Control+Meta+S'
+ * // Normalized: 'Control+Alt+Shift+Meta+S' (following MODIFIER_ORDER)
+ * ```
+ */
+declare const MODIFIER_ORDER: Array<CanonicalModifier>;
+/**
+ * Set of canonical modifier key names for fast lookup.
+ *
+ * Derived from `MODIFIER_ORDER` to ensure consistency. Used to detect when
+ * a modifier is released so we can clear non-modifier keys whose keyup events
+ * may have been swallowed by the OS (e.g. macOS Cmd+key combos).
+ */
+declare const MODIFIER_KEYS: Set<string>;
+/**
+ * Maps modifier key aliases to their canonical form or platform-adaptive 'Mod'.
+ *
+ * This map allows users to write hotkeys using various aliases (e.g., 'Ctrl', 'Cmd', 'Option')
+ * which are then normalized to canonical names ('Control', 'Meta', 'Alt') or the
+ * platform-adaptive 'Mod' token.
+ *
+ * The 'Mod' and 'CommandOrControl' aliases are resolved at runtime via `resolveModifier()`
+ * based on the detected platform (Command on Mac, Control elsewhere).
+ *
+ * @remarks Case-insensitive lookups are supported via lowercase variants
+ *
+ * @example
+ * ```ts
+ * MODIFIER_ALIASES['Ctrl'] // 'Control'
+ * MODIFIER_ALIASES['Cmd'] // 'Meta'
+ * MODIFIER_ALIASES['Mod'] // 'Mod' (resolved at runtime)
+ * ```
+ */
+declare const MODIFIER_ALIASES: Record<string, CanonicalModifier | 'Mod'>;
+/**
+ * Resolves the platform-adaptive 'Mod' modifier to the appropriate canonical modifier.
+ *
+ * The 'Mod' token represents the "primary modifier" on each platform:
+ * - macOS: 'Meta' (Command key ⌘)
+ * - Windows/Linux: 'Control' (Ctrl key)
+ *
+ * This enables cross-platform hotkey definitions like 'Mod+S' that automatically
+ * map to Command+S on Mac and Ctrl+S on Windows/Linux.
+ *
+ * @param modifier - The modifier to resolve. If 'Mod', resolves based on platform.
+ * @param platform - The target platform. Defaults to auto-detection.
+ * @returns The canonical modifier name ('Control', 'Shift', 'Alt', or 'Meta')
+ *
+ * @example
+ * ```ts
+ * resolveModifier('Mod', 'mac') // 'Meta'
+ * resolveModifier('Mod', 'windows') // 'Control'
+ * resolveModifier('Control', 'mac') // 'Control' (unchanged)
+ * ```
+ */
+declare function resolveModifier(modifier: CanonicalModifier | 'Mod', platform?: 'mac' | 'windows' | 'linux'): CanonicalModifier;
+/**
+ * Set of all valid letter keys (A-Z).
+ *
+ * Used for validation and type checking. Letter keys are matched case-insensitively
+ * in hotkey matching, but normalized to uppercase in canonical form.
+ */
+declare const LETTER_KEYS: Set<LetterKey>;
+/**
+ * Set of all valid number keys (0-9).
+ *
+ * Note: Number keys are affected by Shift (Shift+1 → '!' on US layout),
+ * so they're excluded from Shift-based hotkey combinations to avoid
+ * layout-dependent behavior.
+ */
+declare const NUMBER_KEYS: Set<NumberKey>;
+/**
+ * Set of all valid function keys (F1-F12).
+ *
+ * Function keys are commonly used for system shortcuts (e.g., F12 for DevTools,
+ * Alt+F4 to close windows) and application-specific commands.
+ */
+declare const FUNCTION_KEYS: Set<FunctionKey>;
+/**
+ * Set of all valid navigation keys for cursor movement and document navigation.
+ *
+ * Includes arrow keys, Home/End (line navigation), and PageUp/PageDown (page navigation).
+ * These keys are commonly combined with modifiers for selection (Shift+ArrowUp) or
+ * navigation shortcuts (Alt+ArrowLeft for back).
+ */
+declare const NAVIGATION_KEYS: Set<NavigationKey>;
+/**
+ * Set of all valid editing and special keys.
+ *
+ * Includes keys commonly used for text editing (Enter, Backspace, Delete, Tab) and
+ * special actions (Escape, Space). These keys are frequently combined with modifiers
+ * for editor shortcuts (Mod+Enter to submit, Shift+Tab to go back).
+ */
+declare const EDITING_KEYS: Set<EditingKey>;
+/**
+ * Set of all valid punctuation keys commonly used in keyboard shortcuts.
+ *
+ * These are the literal characters as they appear in `KeyboardEvent.key` (layout-dependent,
+ * typically US keyboard layout). Common shortcuts include:
+ * - `Mod+/` - Toggle comment
+ * - `Mod+[` / `Mod+]` - Indent/outdent
+ * - `Mod+=` / `Mod+-` - Zoom in/out
+ *
+ * Note: Punctuation keys are affected by Shift (Shift+',' → '<' on US layout),
+ * so they're excluded from Shift-based hotkey combinations to avoid layout-dependent behavior.
+ */
+declare const PUNCTUATION_KEYS: Set<PunctuationKey>;
+/**
+ * Set of all valid non-modifier keys.
+ *
+ * This is the union of all key type sets (letters, numbers, function keys, navigation,
+ * editing, and punctuation). Used primarily for validation to check if a key string
+ * is recognized and will have type-safe autocomplete support.
+ *
+ * @see {@link LETTER_KEYS}
+ * @see {@link NUMBER_KEYS}
+ * @see {@link FUNCTION_KEYS}
+ * @see {@link NAVIGATION_KEYS}
+ * @see {@link EDITING_KEYS}
+ * @see {@link PUNCTUATION_KEYS}
+ */
+declare const ALL_KEYS: Set<LetterKey | NumberKey | FunctionKey | NavigationKey | EditingKey | PunctuationKey>;
+/**
+ * Normalizes a key name to its canonical form.
+ *
+ * Converts various key name formats (aliases, case variations) into the standard
+ * canonical names used throughout the library. This enables a more forgiving API
+ * where users can write keys in different ways and still get correct behavior.
+ *
+ * Normalization rules:
+ * 1. Check aliases first (e.g., 'Esc' → 'Escape', 'Del' → 'Delete')
+ * 2. Single letters → uppercase (e.g., 'a' → 'A', 's' → 'S')
+ * 3. Function keys → uppercase (e.g., 'f1' → 'F1', 'F12' → 'F12')
+ * 4. Other keys → returned as-is (already canonical or unknown)
+ *
+ * @param key - The key name to normalize (can be an alias, lowercase, etc.)
+ * @returns The canonical key name
+ *
+ * @example
+ * ```ts
+ * normalizeKeyName('esc') // 'Escape'
+ * normalizeKeyName('a') // 'A'
+ * normalizeKeyName('f1') // 'F1'
+ * normalizeKeyName('ArrowUp') // 'ArrowUp' (already canonical)
+ * ```
+ */
+declare function normalizeKeyName(key: string): string;
+/**
+ * Modifier key symbols for macOS display.
+ *
+ * Used by formatting functions to display hotkeys with macOS-style symbols
+ * (e.g., ⌘ for Command, ⌃ for Control) instead of text labels. This provides
+ * a native macOS look and feel in hotkey displays.
+ *
+ * @example
+ * ```ts
+ * MAC_MODIFIER_SYMBOLS['Meta'] // '⌘'
+ * MAC_MODIFIER_SYMBOLS['Control'] // '⌃'
+ * MAC_MODIFIER_SYMBOLS['Alt'] // '⌥'
+ * MAC_MODIFIER_SYMBOLS['Shift'] // '⇧'
+ * ```
+ */
+declare const MAC_MODIFIER_SYMBOLS: Record<CanonicalModifier, string>;
+/**
+ * Modifier key labels for Windows/Linux display.
+ *
+ * Used by formatting functions to display hotkeys with standard text labels
+ * (e.g., 'Ctrl' for Control, 'Win' for Meta/Windows key) instead of symbols.
+ * This provides a familiar Windows/Linux look and feel in hotkey displays.
+ *
+ * @example
+ * ```ts
+ * STANDARD_MODIFIER_LABELS['Control'] // 'Ctrl'
+ * STANDARD_MODIFIER_LABELS['Meta'] // 'Win'
+ * STANDARD_MODIFIER_LABELS['Alt'] // 'Alt'
+ * STANDARD_MODIFIER_LABELS['Shift'] // 'Shift'
+ * ```
+ */
+declare const STANDARD_MODIFIER_LABELS: Record<CanonicalModifier, string>;
+/**
+ * Special key symbols for display formatting.
+ *
+ * Maps certain keys to their visual symbols for better readability in hotkey displays.
+ * Used by formatting functions to show symbols like ↑ for ArrowUp or ↵ for Enter
+ * instead of text labels.
+ *
+ * @example
+ * ```ts
+ * KEY_DISPLAY_SYMBOLS['ArrowUp'] // '↑'
+ * KEY_DISPLAY_SYMBOLS['Enter'] // '↵'
+ * KEY_DISPLAY_SYMBOLS['Escape'] // 'Esc'
+ * KEY_DISPLAY_SYMBOLS['Space'] // '␣'
+ * ```
+ */
+declare const KEY_DISPLAY_SYMBOLS: Record<string, string>;
+//#endregion
+export { ALL_KEYS, EDITING_KEYS, FUNCTION_KEYS, KEY_DISPLAY_SYMBOLS, LETTER_KEYS, MAC_MODIFIER_SYMBOLS, MODIFIER_ALIASES, MODIFIER_KEYS, MODIFIER_ORDER, NAVIGATION_KEYS, NUMBER_KEYS, PUNCTUATION_KEYS, STANDARD_MODIFIER_LABELS, detectPlatform, normalizeKeyName, resolveModifier };
+//# sourceMappingURL=constants.d.cts.map

package/dist/constants.d.ts

@@ -0,0 +1,226 @@
+import { CanonicalModifier, EditingKey, FunctionKey, LetterKey, NavigationKey, NumberKey, PunctuationKey } from "./hotkey.js";
+
+//#region src/constants.d.ts
+/**
+ * Detects the current platform based on browser navigator properties.
+ *
+ * Used internally to resolve platform-adaptive modifiers like 'Mod' (Command on Mac,
+ * Control elsewhere) and for platform-specific hotkey formatting.
+ *
+ * @returns The detected platform: 'mac', 'windows', or 'linux'
+ * @remarks Defaults to 'linux' in SSR environments where navigator is undefined
+ *
+ * @example
+ * ```ts
+ * const platform = detectPlatform() // 'mac' | 'windows' | 'linux'
+ * const modifier = resolveModifier('Mod', platform) // 'Meta' on Mac, 'Control' elsewhere
+ * ```
+ */
+declare function detectPlatform(): 'mac' | 'windows' | 'linux';
+/**
+ * Canonical order for modifiers in normalized hotkey strings.
+ *
+ * Defines the standard order in which modifiers should appear when formatting
+ * hotkeys. This ensures consistent, predictable output across the library.
+ *
+ * Order: Control → Alt → Shift → Meta
+ *
+ * @example
+ * ```ts
+ * // Input: 'Shift+Control+Meta+S'
+ * // Normalized: 'Control+Alt+Shift+Meta+S' (following MODIFIER_ORDER)
+ * ```
+ */
+declare const MODIFIER_ORDER: Array<CanonicalModifier>;
+/**
+ * Set of canonical modifier key names for fast lookup.
+ *
+ * Derived from `MODIFIER_ORDER` to ensure consistency. Used to detect when
+ * a modifier is released so we can clear non-modifier keys whose keyup events
+ * may have been swallowed by the OS (e.g. macOS Cmd+key combos).
+ */
+declare const MODIFIER_KEYS: Set<string>;
+/**
+ * Maps modifier key aliases to their canonical form or platform-adaptive 'Mod'.
+ *
+ * This map allows users to write hotkeys using various aliases (e.g., 'Ctrl', 'Cmd', 'Option')
+ * which are then normalized to canonical names ('Control', 'Meta', 'Alt') or the
+ * platform-adaptive 'Mod' token.
+ *
+ * The 'Mod' and 'CommandOrControl' aliases are resolved at runtime via `resolveModifier()`
+ * based on the detected platform (Command on Mac, Control elsewhere).
+ *
+ * @remarks Case-insensitive lookups are supported via lowercase variants
+ *
+ * @example
+ * ```ts
+ * MODIFIER_ALIASES['Ctrl'] // 'Control'
+ * MODIFIER_ALIASES['Cmd'] // 'Meta'
+ * MODIFIER_ALIASES['Mod'] // 'Mod' (resolved at runtime)
+ * ```
+ */
+declare const MODIFIER_ALIASES: Record<string, CanonicalModifier | 'Mod'>;
+/**
+ * Resolves the platform-adaptive 'Mod' modifier to the appropriate canonical modifier.
+ *
+ * The 'Mod' token represents the "primary modifier" on each platform:
+ * - macOS: 'Meta' (Command key ⌘)
+ * - Windows/Linux: 'Control' (Ctrl key)
+ *
+ * This enables cross-platform hotkey definitions like 'Mod+S' that automatically
+ * map to Command+S on Mac and Ctrl+S on Windows/Linux.
+ *
+ * @param modifier - The modifier to resolve. If 'Mod', resolves based on platform.
+ * @param platform - The target platform. Defaults to auto-detection.
+ * @returns The canonical modifier name ('Control', 'Shift', 'Alt', or 'Meta')
+ *
+ * @example
+ * ```ts
+ * resolveModifier('Mod', 'mac') // 'Meta'
+ * resolveModifier('Mod', 'windows') // 'Control'
+ * resolveModifier('Control', 'mac') // 'Control' (unchanged)
+ * ```
+ */
+declare function resolveModifier(modifier: CanonicalModifier | 'Mod', platform?: 'mac' | 'windows' | 'linux'): CanonicalModifier;
+/**
+ * Set of all valid letter keys (A-Z).
+ *
+ * Used for validation and type checking. Letter keys are matched case-insensitively
+ * in hotkey matching, but normalized to uppercase in canonical form.
+ */
+declare const LETTER_KEYS: Set<LetterKey>;
+/**
+ * Set of all valid number keys (0-9).
+ *
+ * Note: Number keys are affected by Shift (Shift+1 → '!' on US layout),
+ * so they're excluded from Shift-based hotkey combinations to avoid
+ * layout-dependent behavior.
+ */
+declare const NUMBER_KEYS: Set<NumberKey>;
+/**
+ * Set of all valid function keys (F1-F12).
+ *
+ * Function keys are commonly used for system shortcuts (e.g., F12 for DevTools,
+ * Alt+F4 to close windows) and application-specific commands.
+ */
+declare const FUNCTION_KEYS: Set<FunctionKey>;
+/**
+ * Set of all valid navigation keys for cursor movement and document navigation.
+ *
+ * Includes arrow keys, Home/End (line navigation), and PageUp/PageDown (page navigation).
+ * These keys are commonly combined with modifiers for selection (Shift+ArrowUp) or
+ * navigation shortcuts (Alt+ArrowLeft for back).
+ */
+declare const NAVIGATION_KEYS: Set<NavigationKey>;
+/**
+ * Set of all valid editing and special keys.
+ *
+ * Includes keys commonly used for text editing (Enter, Backspace, Delete, Tab) and
+ * special actions (Escape, Space). These keys are frequently combined with modifiers
+ * for editor shortcuts (Mod+Enter to submit, Shift+Tab to go back).
+ */
+declare const EDITING_KEYS: Set<EditingKey>;
+/**
+ * Set of all valid punctuation keys commonly used in keyboard shortcuts.
+ *
+ * These are the literal characters as they appear in `KeyboardEvent.key` (layout-dependent,
+ * typically US keyboard layout). Common shortcuts include:
+ * - `Mod+/` - Toggle comment
+ * - `Mod+[` / `Mod+]` - Indent/outdent
+ * - `Mod+=` / `Mod+-` - Zoom in/out
+ *
+ * Note: Punctuation keys are affected by Shift (Shift+',' → '<' on US layout),
+ * so they're excluded from Shift-based hotkey combinations to avoid layout-dependent behavior.
+ */
+declare const PUNCTUATION_KEYS: Set<PunctuationKey>;
+/**
+ * Set of all valid non-modifier keys.
+ *
+ * This is the union of all key type sets (letters, numbers, function keys, navigation,
+ * editing, and punctuation). Used primarily for validation to check if a key string
+ * is recognized and will have type-safe autocomplete support.
+ *
+ * @see {@link LETTER_KEYS}
+ * @see {@link NUMBER_KEYS}
+ * @see {@link FUNCTION_KEYS}
+ * @see {@link NAVIGATION_KEYS}
+ * @see {@link EDITING_KEYS}
+ * @see {@link PUNCTUATION_KEYS}
+ */
+declare const ALL_KEYS: Set<LetterKey | NumberKey | FunctionKey | NavigationKey | EditingKey | PunctuationKey>;
+/**
+ * Normalizes a key name to its canonical form.
+ *
+ * Converts various key name formats (aliases, case variations) into the standard
+ * canonical names used throughout the library. This enables a more forgiving API
+ * where users can write keys in different ways and still get correct behavior.
+ *
+ * Normalization rules:
+ * 1. Check aliases first (e.g., 'Esc' → 'Escape', 'Del' → 'Delete')
+ * 2. Single letters → uppercase (e.g., 'a' → 'A', 's' → 'S')
+ * 3. Function keys → uppercase (e.g., 'f1' → 'F1', 'F12' → 'F12')
+ * 4. Other keys → returned as-is (already canonical or unknown)
+ *
+ * @param key - The key name to normalize (can be an alias, lowercase, etc.)
+ * @returns The canonical key name
+ *
+ * @example
+ * ```ts
+ * normalizeKeyName('esc') // 'Escape'
+ * normalizeKeyName('a') // 'A'
+ * normalizeKeyName('f1') // 'F1'
+ * normalizeKeyName('ArrowUp') // 'ArrowUp' (already canonical)
+ * ```
+ */
+declare function normalizeKeyName(key: string): string;
+/**
+ * Modifier key symbols for macOS display.
+ *
+ * Used by formatting functions to display hotkeys with macOS-style symbols
+ * (e.g., ⌘ for Command, ⌃ for Control) instead of text labels. This provides
+ * a native macOS look and feel in hotkey displays.
+ *
+ * @example
+ * ```ts
+ * MAC_MODIFIER_SYMBOLS['Meta'] // '⌘'
+ * MAC_MODIFIER_SYMBOLS['Control'] // '⌃'
+ * MAC_MODIFIER_SYMBOLS['Alt'] // '⌥'
+ * MAC_MODIFIER_SYMBOLS['Shift'] // '⇧'
+ * ```
+ */
+declare const MAC_MODIFIER_SYMBOLS: Record<CanonicalModifier, string>;
+/**
+ * Modifier key labels for Windows/Linux display.
+ *
+ * Used by formatting functions to display hotkeys with standard text labels
+ * (e.g., 'Ctrl' for Control, 'Win' for Meta/Windows key) instead of symbols.
+ * This provides a familiar Windows/Linux look and feel in hotkey displays.
+ *
+ * @example
+ * ```ts
+ * STANDARD_MODIFIER_LABELS['Control'] // 'Ctrl'
+ * STANDARD_MODIFIER_LABELS['Meta'] // 'Win'
+ * STANDARD_MODIFIER_LABELS['Alt'] // 'Alt'
+ * STANDARD_MODIFIER_LABELS['Shift'] // 'Shift'
+ * ```
+ */
+declare const STANDARD_MODIFIER_LABELS: Record<CanonicalModifier, string>;
+/**
+ * Special key symbols for display formatting.
+ *
+ * Maps certain keys to their visual symbols for better readability in hotkey displays.
+ * Used by formatting functions to show symbols like ↑ for ArrowUp or ↵ for Enter
+ * instead of text labels.
+ *
+ * @example
+ * ```ts
+ * KEY_DISPLAY_SYMBOLS['ArrowUp'] // '↑'
+ * KEY_DISPLAY_SYMBOLS['Enter'] // '↵'
+ * KEY_DISPLAY_SYMBOLS['Escape'] // 'Esc'
+ * KEY_DISPLAY_SYMBOLS['Space'] // '␣'
+ * ```
+ */
+declare const KEY_DISPLAY_SYMBOLS: Record<string, string>;
+//#endregion
+export { ALL_KEYS, EDITING_KEYS, FUNCTION_KEYS, KEY_DISPLAY_SYMBOLS, LETTER_KEYS, MAC_MODIFIER_SYMBOLS, MODIFIER_ALIASES, MODIFIER_KEYS, MODIFIER_ORDER, NAVIGATION_KEYS, NUMBER_KEYS, PUNCTUATION_KEYS, STANDARD_MODIFIER_LABELS, detectPlatform, normalizeKeyName, resolveModifier };
+//# sourceMappingURL=constants.d.ts.map