houser-js-utils/dist/KeyboardUtils.mjs.map

A comprehensive collection of TypeScript utility functions for common development tasks including array manipulation, string processing, date handling, random number generation, validation, and much more.

{"version":3,"file":"KeyboardUtils.mjs","sources":["../src/KeyboardUtils.ts"],"sourcesContent":["/**\n * @module KeyboardUtils\n * @description A collection of utility functions for keyboard event handling, key detection, and input management.\n * @example\n * ```typescript\n * import { KeyboardUtils } from 'houser-js-utils';\n *\n * // Check if key is pressed\n * const isEnter = KeyboardUtils.isEnterKey(event);\n *\n * // Handle keyboard shortcuts\n * KeyboardUtils.onKeyboardShortcut('Ctrl+S', () => saveDocument());\n *\n * // Get key combination\n * const combo = KeyboardUtils.getKeyCombo(event); // \"Ctrl+Shift+A\"\n * ```\n */\n\n/**\n * Type for keyboard key categories\n */\nexport type KeyCategory =\n  | \"alphanumeric\"\n  | \"arrow\"\n  | \"function\"\n  | \"modifier\"\n  | \"navigation\"\n  | \"numeric\"\n  | \"punctuation\"\n  | \"special\";\n\n/**\n * Type for keyboard event types\n */\nexport type KeyboardEventType = \"keydown\" | \"keyup\" | \"keypress\";\n\nexport const KeyboardUtils = {\n  /**\n   * Gets the category of a keyboard key\n   * @param key - The key to categorize\n   * @returns The category of the key\n   *\n   * @example\n   * ```typescript\n   * const category = KeyboardUtils.getKeyCategory('a'); // 'alphanumeric'\n   * const arrowCategory = KeyboardUtils.getKeyCategory('ArrowUp'); // 'arrow'\n   * const modifierCategory = KeyboardUtils.getKeyCategory('Control'); // 'modifier'\n   * ```\n   */\n  getKeyCategory(key: string): KeyCategory {\n    if (this.isAlphanumericKey(key)) return \"alphanumeric\";\n    if (this.isArrowKey({ key } as KeyboardEvent)) return \"arrow\";\n    if (this.isFunctionKey(key)) return \"function\";\n    if (this.isModifierKey({ key } as KeyboardEvent)) return \"modifier\";\n    if (this.isNavigationKey(key)) return \"navigation\";\n    if (this.isPunctuationKey(key)) return \"punctuation\";\n    return \"special\";\n  },\n\n  /**\n   * Gets the key combination string for a keyboard event (e.g., \"Ctrl+Shift+A\")\n   * @param event - The keyboard event to analyze\n   * @returns A string representing the key combination\n   *\n   * @example\n   * ```typescript\n   * // For a Ctrl+Shift+A event\n   * const combo = KeyboardUtils.getKeyCombination(event); // 'Ctrl+Shift+A'\n   *\n   * // For a single key press\n   * const singleKey = KeyboardUtils.getKeyCombination(event); // 'A'\n   * ```\n   */\n  getKeyCombination(event: KeyboardEvent): string {\n    const modifiers: string[] = [];\n\n    if (event.ctrlKey) modifiers.push(\"Ctrl\");\n    if (event.altKey) modifiers.push(\"Alt\");\n    if (event.shiftKey) modifiers.push(\"Shift\");\n    if (event.metaKey) modifiers.push(\"Meta\");\n\n    const key = event.key.length === 1 ? event.key.toUpperCase() : event.key;\n\n    return modifiers.length > 0 ? `${modifiers.join(\"+\")}+${key}` : key;\n  },\n\n  /**\n   * Checks if the given keyboard event is for an alphanumeric key\n   * @param key - The key to check\n   * @returns True if the key is alphanumeric\n   *\n   * @example\n   * ```typescript\n   * const isAlpha = KeyboardUtils.isAlphanumericKey('a'); // true\n   * const isNum = KeyboardUtils.isAlphanumericKey('1'); // true\n   * const isSpecial = KeyboardUtils.isAlphanumericKey('@'); // false\n   * ```\n   */\n  isAlphanumericKey(key: string): boolean {\n    return /^[a-zA-Z0-9]$/.test(key);\n  },\n\n  /**\n   * Checks if the given keyboard event is for an arrow key\n   * @param event - The keyboard event to check\n   * @returns True if the event is for an arrow key\n   *\n   * @example\n   * ```typescript\n   * const isArrow = KeyboardUtils.isArrowKey(event); // true for ArrowUp, ArrowDown, etc.\n   * ```\n   */\n  isArrowKey(event: KeyboardEvent): boolean {\n    return [\"ArrowUp\", \"ArrowDown\", \"ArrowLeft\", \"ArrowRight\"].includes(\n      event.key\n    );\n  },\n\n  /**\n   * Checks if the given keyboard event is for the Backspace key\n   * @param event - The keyboard event to check\n   * @returns True if the event is for the Backspace key\n   *\n   * @example\n   * ```typescript\n   * const isBackspace = KeyboardUtils.isBackspaceKey(event); // true for Backspace key\n   * ```\n   */\n  isBackspaceKey(event: KeyboardEvent): boolean {\n    return event.key === \"Backspace\" || event.keyCode === 8;\n  },\n\n  /**\n   * Checks if the given keyboard event is for the Delete key\n   * @param event - The keyboard event to check\n   * @returns True if the event is for the Delete key\n   *\n   * @example\n   * ```typescript\n   * const isDelete = KeyboardUtils.isDeleteKey(event); // true for Delete key\n   * ```\n   */\n  isDeleteKey(event: KeyboardEvent): boolean {\n    return event.key === \"Delete\" || event.keyCode === 46;\n  },\n\n  /**\n   * Checks if the given keyboard event is for the Enter key\n   * @param event - The keyboard event to check\n   * @returns True if the event is for the Enter key\n   *\n   * @example\n   * ```typescript\n   * const isEnter = KeyboardUtils.isEnterKey(event); // true for Enter key\n   * ```\n   */\n  isEnterKey(event: KeyboardEvent): boolean {\n    return (\n      event.key === \"Enter\" || event.keyCode === 13 || event.charCode === 13\n    );\n  },\n\n  /**\n   * Checks if the given keyboard event is for the Escape key\n   * @param event - The keyboard event to check\n   * @returns True if the event is for the Escape key\n   *\n   * @example\n   * ```typescript\n   * const isEscape = KeyboardUtils.isEscapeKey(event); // true for Escape key\n   * ```\n   */\n  isEscapeKey(event: KeyboardEvent): boolean {\n    return event.key === \"Escape\" || event.keyCode === 27;\n  },\n\n  /**\n   * Checks if the given keyboard event is for a function key (F1-F12)\n   * @param key - The key to check\n   * @returns True if the key is a function key\n   *\n   * @example\n   * ```typescript\n   * const isFunction = KeyboardUtils.isFunctionKey('F1'); // true\n   * const isNotFunction = KeyboardUtils.isFunctionKey('A'); // false\n   * ```\n   */\n  isFunctionKey(key: string): boolean {\n    return /^F[1-9]|F1[0-2]$/.test(key);\n  },\n\n  /**\n   * Checks if the given keyboard event is for a modifier key\n   * @param event - The keyboard event to check\n   * @returns True if the event is for a modifier key\n   *\n   * @example\n   * ```typescript\n   * const isModifier = KeyboardUtils.isModifierKey(event); // true for Control, Alt, Shift, Meta\n   * ```\n   */\n  isModifierKey(event: KeyboardEvent): boolean {\n    return [\"Control\", \"Alt\", \"Shift\", \"Meta\"].includes(event.key);\n  },\n\n  /**\n   * Checks if the given keyboard event is for a navigation key\n   * @param key - The key to check\n   * @returns True if the key is a navigation key\n   *\n   * @example\n   * ```typescript\n   * const isNav = KeyboardUtils.isNavigationKey('Home'); // true\n   * const isNotNav = KeyboardUtils.isNavigationKey('A'); // false\n   * ```\n   */\n  isNavigationKey(key: string): boolean {\n    return [\n      \"Home\",\n      \"End\",\n      \"PageUp\",\n      \"PageDown\",\n      \"ArrowUp\",\n      \"ArrowDown\",\n      \"ArrowLeft\",\n      \"ArrowRight\",\n    ].includes(key);\n  },\n\n  /**\n   * Checks if the given keyboard event is for a numeric key\n   * @param key - The key to check\n   * @returns True if the key is numeric\n   *\n   * @example\n   * ```typescript\n   * const isNum = KeyboardUtils.isNumericKey('1'); // true\n   * const isNotNum = KeyboardUtils.isNumericKey('A'); // false\n   * ```\n   */\n  isNumericKey(key: string): boolean {\n    return /^[0-9]$/.test(key);\n  },\n\n  /**\n   * Checks if the given keyboard event is for a punctuation key\n   * @param key - The key to check\n   * @returns True if the key is punctuation\n   *\n   * @example\n   * ```typescript\n   * const isPunct = KeyboardUtils.isPunctuationKey('!'); // true\n   * const isNotPunct = KeyboardUtils.isPunctuationKey('A'); // false\n   * ```\n   */\n  isPunctuationKey(key: string): boolean {\n    return /^[!@#$%^&*()_+\\-=\\[\\]{};':\"\\\\|,.<>\\/?]$/.test(key);\n  },\n\n  /**\n   * Checks if the given keyboard event is for the Space key\n   * @param event - The keyboard event to check\n   * @returns True if the event is for the Space key\n   *\n   * @example\n   * ```typescript\n   * const isSpace = KeyboardUtils.isSpaceKey(event); // true for Space key\n   * ```\n   */\n  isSpaceKey(event: KeyboardEvent): boolean {\n    return event.key === \" \" || event.keyCode === 32;\n  },\n\n  /**\n   * Checks if the given keyboard event is for the Tab key\n   * @param event - The keyboard event to check\n   * @returns True if the event is for the Tab key\n   *\n   * @example\n   * ```typescript\n   * const isTab = KeyboardUtils.isTabKey(event); // true for Tab key\n   * ```\n   */\n  isTabKey(event: KeyboardEvent): boolean {\n    return event.key === \"Tab\" || event.keyCode === 9;\n  },\n\n  /**\n   * Simulates a click event on the target element when Enter key is pressed\n   * @param event - The keyboard event to handle\n   *\n   * @example\n   * ```typescript\n   * // Add to a button's keydown event\n   * button.addEventListener('keydown', (event) => {\n   *   KeyboardUtils.simulateClickOnEnter(event);\n   * });\n   * ```\n   */\n  simulateClickOnEnter(event: KeyboardEvent): void {\n    if (this.isEnterKey(event)) {\n      (event.target as HTMLElement).click();\n    }\n  },\n\n  /**\n   * Stops the default action and prevents event propagation\n   * @param event - The keyboard event to handle\n   *\n   * @example\n   * ```typescript\n   * // Prevent default behavior and stop propagation\n   * element.addEventListener('keydown', (event) => {\n   *   KeyboardUtils.stopEvent(event);\n   * });\n   * ```\n   */\n  stopEvent(event: KeyboardEvent): void {\n    event.preventDefault();\n    event.stopPropagation();\n  },\n};\n"],"names":[],"mappings":"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"}