keyboard-i18n/dist/index.d.ts

Internationalization and localization utils for keyboard shortcuts

import { KeyboardLayoutMap } from 'keyboard-layout-map';

/**
 * Some common event.code (KeyboardEvent.code) values that can be use in keyboard shortcuts.
 *
 * {@link https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_code_values}
 */

declare type KeyboardEventCode = 'AltLeft' | 'AltRight' | 'ArrowDown' | 'ArrowLeft' | 'ArrowRight' | 'ArrowUp' | 'Backquote' | 'Backslash' | 'Backspace' | 'BracketLeft' | 'BracketRight' | 'CapsLock' | 'Comma' | 'ContextMenu' | 'ControlLeft' | 'ControlRight' | 'Delete' | 'Digit0' | 'Digit1' | 'Digit2' | 'Digit3' | 'Digit4' | 'Digit5' | 'Digit6' | 'Digit7' | 'Digit8' | 'Digit9' | 'End' | 'Enter' | 'Equal' | 'Escape' | 'F1' | 'F10' | 'F11' | 'F12' | 'F2' | 'F3' | 'F4' | 'F5' | 'F6' | 'F7' | 'F8' | 'F9' | 'Home' | 'Insert' | 'IntlBackslash' | 'IntlRo' | 'IntlYen' | 'KeyA' | 'KeyB' | 'KeyC' | 'KeyD' | 'KeyE' | 'KeyF' | 'KeyG' | 'KeyH' | 'KeyI' | 'KeyJ' | 'KeyK' | 'KeyL' | 'KeyM' | 'KeyN' | 'KeyO' | 'KeyP' | 'KeyQ' | 'KeyR' | 'KeyS' | 'KeyT' | 'KeyU' | 'KeyV' | 'KeyW' | 'KeyX' | 'KeyY' | 'KeyZ' | 'MetaLeft' | 'MetaRight' | 'Minus' | 'PageDown' | 'PageUp' | 'Period' | 'Quote' | 'Semicolon' | 'ShiftLeft' | 'ShiftRight' | 'Slash' | 'Space' | 'Tab';
/**
 * Some common event.key (KeyboardEvent.key) values that can be use in keyboard shortcuts.
 *
 * {@link https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_key_values}
 */
declare type KeyboardEventKey = 'Alt' | 'CapsLock' | 'Control' | 'Meta' | 'Shift' | '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | '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' | 'F1' | 'F2' | 'F3' | 'F4' | 'F5' | 'F6' | 'F7' | 'F8' | 'F9' | 'F10' | 'F11' | 'F12' | '!' | '@' | '#' | '$' | '%' | '^' | '&' | '*' | '(' | ')' | '_' | '+' | '[' | ']' | ':' | ';' | '<' | '>' | ',' | '.' | '?' | '~' | '`' | '|' | '\\' | '/' | '=' | '-' | "'" | '"' | 'Enter' | 'Tab' | ' ' | 'ArrowDown' | 'ArrowLeft' | 'ArrowRight' | 'ArrowUp' | 'End' | 'Home' | 'PageDown' | 'PageUp' | 'Backspace' | 'Cut' | 'Delete' | 'Escape';
interface KeyboardEventLike {
    altKey: boolean;
    ctrlKey: boolean;
    metaKey: boolean;
    shiftKey: boolean;
    key: string;
    code: string;
    isComposing?: boolean;
}
/**
 * Key modifiers for a keyboard shortcut.
 *
 * - "mod": Command on macOS and Ctrl on Windows
 * - "ctrl": Control on macOS and Ctrl on Windows
 * - "alt": Option on macOS and Alt on Windows
 * - "meta": Command on macOS and Win on Windows
 * - "shift": Shift
 */
type KeyboardModifier = 'mod' | 'ctrl' | 'alt' | 'meta' | 'shift';
type KeyboardShortcutPrefix = '' | `${KeyboardModifier}+` | `${KeyboardModifier}+${KeyboardModifier}+` | `${KeyboardModifier}+${KeyboardModifier}+${KeyboardModifier}+`;
/**
 * A string that represents a keyboard shortcut.
 *
 * Examples:
 *
 * - "Escape"
 * - "ctrl+a"
 * - "mod+shift+Slash"
 * - "alt+KeyA"
 * - "shift+ArrowUp"
 */
type KeyboardShortcut = `${KeyboardShortcutPrefix}${KeyboardEventKey}` | `${KeyboardShortcutPrefix}${KeyboardEventCode}`;
/**
 * A object that represents a parsed keyboard shortcut based on current
 * platform.
 */
interface ParsedKeyboardShortcut {
    target: KeyboardEventCode | KeyboardEventKey;
    alt: boolean;
    ctrl: boolean;
    shift: boolean;
    meta: boolean;
}
/**
 * A function that localizes a keyboard shortcut.
 */
type Localizer = (shortcut: ParsedKeyboardShortcut, layout: KeyboardLayoutMap) => ParsedKeyboardShortcut;
interface Options {
    /**
     * Whether the current platform is Apple systems. It will be detected
     * automatically if not provided.
     */
    isAppleOS?: boolean;
    /**
     * The keyboard layout to use. It will be detected automatically if not
     * provided.
     */
    layout?: KeyboardLayoutMap;
    /**
     * The function to use for localizing the shortcut. Defaults to
     * {@link defaultLocalizer}
     */
    localizer?: Localizer;
}

/**
 * Returns a function that checks if an keyboard event matches the keyboard shortcut.
 */
declare function createChecker<E extends KeyboardEventLike = KeyboardEvent>(
/**
 * The keyboard shortcut to check.
 */
shortcut: KeyboardShortcut, 
/**
 * Options for checking the keyboard shortcut.
 */
options?: Options): (event: E) => boolean;

/**
 * Returns a function that formats a keyboard shortcut as an array of strings.
 */
declare function createFormatter(
/**
 * The keyboard shortcut to format.
 */
shortcut: KeyboardShortcut, 
/**
 * Options for formatting the keyboard shortcut.
 */
options?: Options): () => string[];

/**
 * Returns a keyboard event handler that can be used to handle keyboard shortcuts.
 */
declare function createHandler<E extends KeyboardEventLike = KeyboardEvent>(
/**
 * The keyboard shortcut to check.
 */
shortcut: KeyboardShortcut | KeyboardShortcut[], 
/**
 * The callback function to run when the keyboard shortcut matches.
 */
callback: (event: E) => void, 
/**
 * Options for checking the keyboard shortcut.
 */
options?: Options): (event: E) => void;

/**
 * The default localizer.
 */
declare const defaultLocalizer: Localizer;

export { type KeyboardEventCode, type KeyboardEventKey, type KeyboardEventLike, type KeyboardModifier, type KeyboardShortcut, type Localizer, type Options, type ParsedKeyboardShortcut, createChecker, createFormatter, createHandler, defaultLocalizer };