//#region src/hotkey.d.ts
/**
 * All supported modifier key names, including aliases.
 * - Control/Ctrl: The Control key
 * - Shift: The Shift key
 * - Alt/Option: The Alt key (Option on macOS)
 * - Command/Cmd: The Command key (macOS only)
 * - CommandOrControl/Mod: Command on macOS, Control on other platforms
 */
type Modifier = 'Control' | 'Ctrl' | 'Shift' | 'Alt' | 'Option' | 'Command' | 'Cmd' | 'CommandOrControl' | 'Mod';
/**
 * Canonical modifier names that map to KeyboardEvent properties.
 */
type CanonicalModifier = 'Control' | 'Shift' | 'Alt' | 'Meta';
/**
 * Letter keys A-Z (case-insensitive in matching).
 */
type LetterKey = 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G' | 'H' | 'I' | 'J' | 'K' | 'L' | 'M' | 'N' | 'O' | 'P' | 'Q' | 'R' | 'S' | 'T' | 'U' | 'V' | 'W' | 'X' | 'Y' | 'Z';
/**
 * Number keys 0-9.
 */
type NumberKey = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9';
/**
 * Function keys F1-F12.
 */
type FunctionKey = 'F1' | 'F2' | 'F3' | 'F4' | 'F5' | 'F6' | 'F7' | 'F8' | 'F9' | 'F10' | 'F11' | 'F12';
/**
 * Navigation keys for cursor movement.
 */
type NavigationKey = 'ArrowUp' | 'ArrowDown' | 'ArrowLeft' | 'ArrowRight' | 'Home' | 'End' | 'PageUp' | 'PageDown';
/**
 * Editing and special keys.
 */
type EditingKey = 'Enter' | 'Escape' | 'Space' | 'Tab' | 'Backspace' | 'Delete';
/**
 * Punctuation keys commonly used in keyboard shortcuts.
 * These are the literal characters as they appear in KeyboardEvent.key
 * (layout-dependent, typically US keyboard layout).
 */
type PunctuationKey = '/' | '[' | ']' | '\\' | '=' | '-' | ',' | '.' | ';' | '`';
/**
 * Keys that don't change their value when Shift is pressed.
 * These keys produce the same `KeyboardEvent.key` value whether Shift is held or not.
 *
 * Excludes NumberKey (Shift+1 produces '!' on US layout) and PunctuationKey
 * (Shift+',' produces '<' on US layout).
 *
 * Used in hotkey type definitions to prevent layout-dependent issues when Shift
 * is part of the modifier combination.
 */
type NonPunctuationKey = LetterKey | NumberKey | EditingKey | NavigationKey | FunctionKey;
/**
 * All supported non-modifier keys.
 */
type Key = NonPunctuationKey | PunctuationKey;
/**
 * Includes both modifier keys and regular keys.
 */
type IndividualKey = CanonicalModifier | Key;
/**
 * Single modifier + key combinations.
 * Uses canonical modifiers (4) + Mod (1) = 5 modifiers.
 * Shift combinations exclude PunctuationKey to avoid layout-dependent issues.
 *
 * The `Mod` modifier is platform-adaptive:
 * - **macOS**: Resolves to `Meta` (Command key ⌘)
 * - **Windows/Linux**: Resolves to `Control` (Ctrl key)
 *
 * This enables cross-platform hotkey definitions that automatically adapt to the platform.
 * For example, `Mod+S` becomes `Command+S` on Mac and `Ctrl+S` on Windows/Linux.
 */
type SingleModifierHotkey = `Control+${Key}` | `Alt+${Key}` | `Shift+${NonPunctuationKey}` | `Meta+${Key}` | `Mod+${Key}`;
/**
 * Two modifier + key combinations.
 * Shift combinations exclude Numbers and PunctuationKeys to avoid layout-dependent issues.
 *
 * **Platform-adaptive `Mod` combinations:**
 * - `Mod+Alt` and `Mod+Shift` are included (safe on all platforms)
 * - `Mod+Control` and `Mod+Meta` are excluded because they create duplicate modifiers:
 *   - `Mod+Control` duplicates `Control` on Windows/Linux (Mod = Control)
 *   - `Mod+Meta` duplicates `Meta` on macOS (Mod = Meta)
 */
type TwoModifierHotkey = `Control+Alt+${Key}` | `Control+Shift+${NonPunctuationKey}` | `Control+Meta+${Key}` | `Alt+Shift+${NonPunctuationKey}` | `Alt+Meta+${Key}` | `Shift+Meta+${NonPunctuationKey}` | `Mod+Alt+${Key}` | `Mod+Shift+${NonPunctuationKey}`;
/**
 * Three modifier + key combinations.
 * Shift combinations exclude Numbers and PunctuationKeys to avoid layout-dependent issues.
 *
 * **Platform-adaptive `Mod` combinations:**
 * - `Mod+Alt+Shift` is included (safe on all platforms)
 * - `Mod+Control+Shift` and `Mod+Shift+Meta` are excluded because they create duplicate modifiers:
 *   - `Mod+Control+Shift` duplicates `Control` on Windows/Linux (Mod = Control)
 *   - `Mod+Shift+Meta` duplicates `Meta` on macOS (Mod = Meta)
 */
type ThreeModifierHotkey = `Control+Alt+Shift+${NonPunctuationKey}` | `Control+Alt+Meta+${Key}` | `Control+Shift+Meta+${NonPunctuationKey}` | `Alt+Shift+Meta+${NonPunctuationKey}` | `Mod+Alt+Shift+${NonPunctuationKey}`;
/**
 * Four modifier + key combinations.
 * Shift combinations exclude Numbers and PunctuationKeys to avoid layout-dependent issues.
 *
 * Only the canonical `Control+Alt+Shift+Meta` combination is included.
 *
 * **Why no `Mod` combinations?**
 * Since `Mod` resolves to either `Control` (Windows/Linux) or `Meta` (macOS), any
 * four-modifier combination with `Mod` would create duplicate modifiers on one platform.
 * For example:
 * - `Mod+Control+Alt+Shift` → duplicates `Control` on Windows/Linux
 * - `Mod+Alt+Shift+Meta` → duplicates `Meta` on macOS
 */
type FourModifierHotkey = `Control+Alt+Shift+Meta+${NonPunctuationKey}`;
/**
 * A type-safe hotkey string.
 *
 * Provides autocomplete for:
 * - All single keys (letters, numbers, function keys, navigation, editing, punctuation)
 * - Single modifier + common key (Control+S, Mod+A, Mod+/, etc.)
 * - Two modifiers + common key (Mod+Shift+S, Control+Alt+A, etc.)
 * - Three modifiers + common key (Control+Alt+Shift+A, Mod+Alt+Shift+S, etc.)
 * - Four modifiers + common key (Control+Alt+Shift+Meta+A, etc.)
 *
 * ## Modifier Names
 *
 * Use canonical modifier names:
 * - `Control` (not Ctrl) - The Control key
 * - `Alt` (not Option) - The Alt key (Option on macOS)
 * - `Meta` (not Command/Cmd) - The Meta/Command key (macOS only)
 * - `Shift` - The Shift key
 *
 * ## Platform-Adaptive `Mod` Modifier
 *
 * The `Mod` modifier is a special platform-adaptive modifier that automatically resolves
 * to the "primary modifier" on each platform:
 *
 * - **macOS**: `Mod` → `Meta` (Command key ⌘)
 * - **Windows/Linux**: `Mod` → `Control` (Ctrl key)
 *
 * This enables cross-platform hotkey definitions that work correctly on all platforms
 * without platform-specific code. The `Mod` modifier is resolved at runtime based on
 * the detected platform.
 *
 * **When to use `Mod` vs platform-specific modifiers:**
 * - Use `Mod` for cross-platform shortcuts (e.g., `Mod+S` for save)
 * - Use `Meta` or `Control` when you need platform-specific behavior
 * - Use `Mod` when you want your shortcuts to follow platform conventions automatically
 *
 * **Limitations:**
 * - `Mod+Control` and `Mod+Meta` combinations are not allowed (they create duplicate
 *   modifiers on one platform)
 * - In four-modifier combinations, only canonical modifiers are allowed (no `Mod`)
 *
 * @example
 * ```ts
 * // Cross-platform shortcuts (recommended)
 * const save: Hotkey = 'Mod+S'           // Command+S on Mac, Ctrl+S on Windows/Linux
 * const saveAs: Hotkey = 'Mod+Shift+S'   // Command+Shift+S on Mac, Ctrl+Shift+S elsewhere
 * const comment: Hotkey = 'Mod+/'       // Command+/ on Mac, Ctrl+/ elsewhere
 *
 * // Platform-specific shortcuts
 * const macOnly: Hotkey = 'Meta+S'       // Command+S on Mac only
 * const windowsOnly: Hotkey = 'Control+S' // Ctrl+S on Windows/Linux only
 * ```
 */
type Hotkey = Key | SingleModifierHotkey | TwoModifierHotkey | ThreeModifierHotkey | FourModifierHotkey;
/**
 * A parsed representation of a hotkey string.
 *
 * This interface provides a flexible fallback when the `Hotkey` type doesn't
 * fit your use case. You can pass a `ParsedHotkey` directly to hotkey functions
 * instead of a hotkey string, allowing for more dynamic or complex scenarios
 * that aren't covered by the type-safe `Hotkey` union.
 *
 * @example
 * ```ts
 * // Type-safe hotkey string
 * useHotkey('Mod+S', handler)
 *
 * // Fallback: parsed hotkey for dynamic scenarios
 * const parsed = parseHotkey(userInput)
 * useHotkey(parsed, handler) // Works even if userInput isn't in Hotkey type
 * ```
 */
interface ParsedHotkey {
  /** The non-modifier key (e.g., 'S', 'Escape', 'F1', '/', '['). Can be any string for flexibility. */
  key: Key | (string & {});
  /** Whether the Control key is required */
  ctrl: boolean;
  /** Whether the Shift key is required */
  shift: boolean;
  /** Whether the Alt key is required */
  alt: boolean;
  /** Whether the Meta (Command) key is required */
  meta: boolean;
  /** List of canonical modifier names that are required, in canonical order */
  modifiers: Array<CanonicalModifier>;
}
/**
 * A raw hotkey object for programmatic registration.
 *
 * Like `ParsedHotkey` but without `modifiers` (derived from booleans)
 * and with optional modifier booleans (default to `false` when omitted).
 * Use with `HotkeyManager.register()` and `useHotkey()` when you prefer
 * object form over a string.
 *
 * The `mod` modifier is platform-adaptive: Command on macOS, Control on Windows/Linux.
 * Pass `platform` when converting to ParsedHotkey (e.g., via `options.platform`).
 *
 * @example
 * ```ts
 * useHotkey({ key: 'S', mod: true }, handler)             // Mod+S (cross-platform)
 * useHotkey({ key: 'S', ctrl: true }, handler)            // Control+S
 * useHotkey({ key: 'Escape' }, handler)                   // Escape (no modifiers)
 * useHotkey({ key: 'A', shift: true, meta: true }, handler) // Shift+Meta+A
 * useHotkey({ key: 'S', mod: true, shift: true }, handler)  // Mod+Shift+S
 * ```
 */
interface RawHotkey {
  /** The non-modifier key (e.g., 'S', 'Escape', 'F1'). */
  key: Key | (string & {});
  /** Platform-adaptive modifier: Command on macOS, Control on Windows/Linux. Defaults to false. */
  mod?: boolean;
  /** Whether the Control key is required. Defaults to false. */
  ctrl?: boolean;
  /** Whether the Shift key is required. Defaults to false. */
  shift?: boolean;
  /** Whether the Alt key is required. Defaults to false. */
  alt?: boolean;
  /** Whether the Meta (Command) key is required. Defaults to false. */
  meta?: boolean;
}
/**
 * A hotkey that can be passed to `HotkeyManager.register()` and `useHotkey()`.
 * Either a type-safe string (`Hotkey`) or a raw object (`RawHotkey`).
 */
type RegisterableHotkey = Hotkey | RawHotkey;
/**
 * Options for formatting hotkeys for display.
 */
interface FormatDisplayOptions {
  /** The target platform. Defaults to auto-detection. */
  platform?: 'mac' | 'windows' | 'linux';
  /** Whether to use symbols for the display. Defaults to true. */
  useSymbols?: boolean;
  /** Override the separator between display tokens. Defaults to platform-specific formatting when null/undefined. */
  separatorToken?: string | null;
}
/**
 * Result of validating a hotkey string.
 */
interface ValidationResult {
  /** Whether the hotkey is valid (can still have warnings) */
  valid: boolean;
  /** Warning messages about potential issues */
  warnings: Array<string>;
  /** Error messages about invalid syntax */
  errors: Array<string>;
}
/**
 * Context passed to hotkey callbacks along with the keyboard event.
 */
interface HotkeyCallbackContext {
  /** The original hotkey string that was registered */
  hotkey: Hotkey;
  /** The parsed representation of the hotkey */
  parsedHotkey: ParsedHotkey;
}
/**
 * Callback function type for hotkey handlers.
 *
 * @param event - The keyboard event that triggered the hotkey
 * @param context - Additional context including the hotkey and parsed hotkey
 *
 * @example
 * ```ts
 * const handler: HotkeyCallback = (event, { hotkey, parsedHotkey }) => {
 *   console.log(`Hotkey ${hotkey} was pressed`)
 *   console.log(`Modifiers:`, parsedHotkey.modifiers)
 * }
 * ```
 */
type HotkeyCallback = (event: KeyboardEvent, context: HotkeyCallbackContext) => void;
/**
 * Metadata for hotkey and sequence registrations.
 * Includes `name` and `description` by default. Extend via declaration merging:
 *
 * @example
 * ```ts
 * declare module '@tanstack/hotkeys' {
 *   interface HotkeyMeta {
 *     category?: string
 *     icon?: string
 *   }
 * }
 * ```
 */
interface HotkeyMeta {
  /** Human-readable name for this hotkey (e.g., "Save Document") */
  name?: string;
  /** Description of what this hotkey does */
  description?: string;
}
//#endregion
export { CanonicalModifier, EditingKey, FormatDisplayOptions, FunctionKey, Hotkey, HotkeyCallback, HotkeyCallbackContext, HotkeyMeta, IndividualKey, Key, LetterKey, Modifier, NavigationKey, NumberKey, ParsedHotkey, PunctuationKey, RawHotkey, RegisterableHotkey, ValidationResult };
//# sourceMappingURL=hotkey.d.ts.map