@alwatr/keyboard-shortcut 9.31.0 → 9.33.0

package/dist/main.js

@@ -1,5 +1,5 @@
-/* 📦 @alwatr/keyboard-shortcut v9.31.0 */
+/* 📦 @alwatr/keyboard-shortcut v9.33.0 */
 import{actionService as a}from"@alwatr/action";import{createLogger as l}from"@alwatr/logger";class d{logger_=l("keyboard-shortcut-service");modifierKeys__=new Set(["Control","Shift","Alt","Meta"]);editableTags__=new Set(["INPUT","TEXTAREA","SELECT"]);hasRegistered__=!1;constructor(){this.logger_.logMethod?.("constructor"),this.handleKeyDown__=this.handleKeyDown__.bind(this)}setup(){if(this.logger_.logMethod?.("setup"),this.hasRegistered__)return;if(typeof document>"u"){this.logger_.incident?.("setup","document_not_found");return}this.hasRegistered__=!0,document.addEventListener("keydown",this.handleKeyDown__,{capture:!0})}teardown(){if(this.logger_.logMethod?.("teardown"),!this.hasRegistered__)return;if(typeof document>"u")return;this.hasRegistered__=!1,document.removeEventListener("keydown",this.handleKeyDown__,{capture:!0})}handleKeyDown__(o){if(this.modifierKeys__.has(o.key))return;if(this.isEditable__(o)&&!this.hasModifier__(o))return;let s=this.buildCombo__(o);this.logger_.logMethodArgs?.("keyboard_handler",{combo:s}),a.dispatch({type:`key_${s}`})}isEditable__(o){let s=o.target;if(!(s instanceof HTMLElement))return!1;return this.editableTags__.has(s.tagName)||s.isContentEditable}hasModifier__(o){return o.ctrlKey||o.metaKey||o.altKey}buildCombo__(o){let s=[];if(o.ctrlKey||o.metaKey)s.push("ctrl");if(o.shiftKey)s.push("shift");if(o.altKey)s.push("alt");let i=o.key===" "?"space":o.key.toLowerCase();return s.push(i),s.join("_")}}var u=new d;export{u as keyboardShortcutService,d as KeyboardShortcutService};
 
-//# debugId=2945D18B490E57D964756E2164756E21
+//# debugId=3118F2268D83C88364756E2164756E21
 //# sourceMappingURL=main.js.map

package/dist/main.js.map

@@ -5,6 +5,6 @@
     "/**\n * Global keyboard-to-action bridge for Alwatr Flux.\n *\n * Listens for `keydown` on `document` and dispatches a flux action whose\n * name is derived from the pressed key combination. This lets any module\n * react to keyboard shortcuts declaratively via `onAction()` without\n * coupling to raw DOM events.\n *\n * ## Action naming convention\n *\n * The action type follows the pattern `key_<combo>` where `<combo>` is\n * built from active modifiers + key name, all **lowercase**, joined by `_`:\n *\n * | Keys pressed          | Action type              |\n * | --------------------- | ------------------------ |\n * | Escape                | `key_escape`             |\n * | Space                 | `key_space`              |\n * | Ctrl + S              | `key_ctrl_s`             |\n * | Shift + Ctrl + U      | `key_ctrl_shift_u`       |\n * | Alt + Enter           | `key_alt_enter`          |\n *\n * Modifier order is always **ctrl → shift → alt** for consistency.\n *\n * ## Usage\n *\n * ```ts\n * import {keyboardShortcutService, onAction} from '@alwatr/flux';\n *\n * // Initialize keyboard shortcut listener\n * keyboardShortcutService.setup();\n *\n * // Close drawer on Escape\n * onAction('key_escape', () => closeDrawer());\n *\n * // Save on Ctrl+S\n * onAction('key_ctrl_s', () => save());\n *\n * // Cleanup when no longer needed\n * keyboardShortcutService.teardown();\n * ```\n */\n\nimport {actionService} from '@alwatr/action';\nimport {createLogger} from '@alwatr/logger';\n\n/**\n * Service to manage global keyboard shortcut mapping and dispatching.\n *\n * Implements global `keydown` event listener on `document` in the capture phase,\n * normalizes modifier combinations, and dispatches equivalent flux actions.\n */\nexport class KeyboardShortcutService {\n  protected readonly logger_ = createLogger('keyboard-shortcut-service');\n\n  // Modifier keys that should not produce standalone actions.\n  private readonly modifierKeys__ = new Set(['Control', 'Shift', 'Alt', 'Meta']);\n\n  // Editable element tags where bare key presses (no modifier) are user input, not shortcuts.\n  private readonly editableTags__ = new Set(['INPUT', 'TEXTAREA', 'SELECT']);\n\n  private hasRegistered__ = false;\n\n  constructor() {\n    this.logger_.logMethod?.('constructor');\n    this.handleKeyDown__ = this.handleKeyDown__.bind(this);\n  }\n\n  /**\n   * Registers global event listener for `keydown` on `document`.\n   * Safe to call multiple times (idempotent).\n   *\n   * @example\n   * ```ts\n   * keyboardShortcutService.setup();\n   * ```\n   */\n  setup(): void {\n    this.logger_.logMethod?.('setup');\n    if (this.hasRegistered__) return;\n    if (typeof document === 'undefined') {\n      this.logger_.incident?.('setup', 'document_not_found');\n      return;\n    }\n    this.hasRegistered__ = true;\n    document.addEventListener('keydown', this.handleKeyDown__, {capture: true});\n  }\n\n  /**\n   * Removes global event listener for `keydown` on `document`.\n   *\n   * @example\n   * ```ts\n   * keyboardShortcutService.teardown();\n   * ```\n   */\n  teardown(): void {\n    this.logger_.logMethod?.('teardown');\n    if (!this.hasRegistered__) return;\n    if (typeof document === 'undefined') return;\n    this.hasRegistered__ = false;\n    document.removeEventListener('keydown', this.handleKeyDown__, {capture: true});\n  }\n\n  /**\n   * Global keydown event listener handler.\n   */\n  private handleKeyDown__(event: KeyboardEvent): void {\n    // Ignore standalone modifier presses — they are not actionable shortcuts.\n    if (this.modifierKeys__.has(event.key)) return;\n\n    // When focus is inside an editable element, only dispatch shortcut actions\n    // that include a real modifier (ctrl/meta/alt). Bare key presses like\n    // letters, digits, Escape, Enter, etc. are normal user input and must\n    // not be intercepted.\n    if (this.isEditable__(event) && !this.hasModifier__(event)) return;\n\n    const combo = this.buildCombo__(event);\n\n    this.logger_.logMethodArgs?.('keyboard_handler', {combo});\n\n    actionService.dispatch({type: `key_${combo}`});\n  }\n\n  /**\n   * Whether the event target is an editable element (input, textarea, select,\n   * or any element with `contenteditable`).\n   */\n  private isEditable__(event: KeyboardEvent): boolean {\n    const target = event.target;\n    if (!(target instanceof HTMLElement)) return false;\n    return this.editableTags__.has(target.tagName) || target.isContentEditable;\n  }\n\n  /**\n   * Whether the event carries at least one non-shift modifier (ctrl/meta/alt).\n   *\n   * Shift alone is not considered a modifier shortcut because Shift+Letter\n   * is normal typing (uppercase). Only ctrl/meta/alt signal an intentional\n   * keyboard shortcut.\n   */\n  private hasModifier__(event: KeyboardEvent): boolean {\n    return event.ctrlKey || event.metaKey || event.altKey;\n  }\n\n  /**\n   * Builds a normalized, deterministic combo string from a KeyboardEvent.\n   *\n   * Modifier order is fixed (ctrl → shift → alt) so the same\n   * physical combination always produces the same string regardless of\n   * the order the user pressed the modifier keys.\n   */\n  private buildCombo__(event: KeyboardEvent): string {\n    const parts: string[] = [];\n\n    if (event.ctrlKey || event.metaKey) parts.push('ctrl');\n    if (event.shiftKey) parts.push('shift');\n    if (event.altKey) parts.push('alt');\n\n    const key = event.key === ' ' ? 'space' : event.key.toLowerCase();\n    parts.push(key);\n\n    return parts.join('_');\n  }\n}\n\n/**\n * Singleton instance of KeyboardShortcutService.\n *\n * @example\n * ```ts\n * import {keyboardShortcutService} from '@alwatr/keyboard-shortcut';\n *\n * keyboardShortcutService.setup();\n * ```\n */\nexport const keyboardShortcutService = new KeyboardShortcutService();\n\n// Type augmentation — register the `key_*` pattern so any module can\n// declare specific shortcuts via ActionRecord merging.\ndeclare module '@alwatr/action' {\n  interface ActionRecord {\n    [key: `key_${string}`]: void;\n  }\n}\n"
   ],
   "mappings": ";AA0CA,wBAAQ,uBACR,uBAAQ,uBAQD,MAAM,CAAwB,CAChB,QAAU,EAAa,2BAA2B,EAGpD,eAAiB,IAAI,IAAI,CAAC,UAAW,QAAS,MAAO,MAAM,CAAC,EAG5D,eAAiB,IAAI,IAAI,CAAC,QAAS,WAAY,QAAQ,CAAC,EAEjE,gBAAkB,GAE1B,WAAW,EAAG,CACZ,KAAK,QAAQ,YAAY,aAAa,EACtC,KAAK,gBAAkB,KAAK,gBAAgB,KAAK,IAAI,EAYvD,KAAK,EAAS,CAEZ,GADA,KAAK,QAAQ,YAAY,OAAO,EAC5B,KAAK,gBAAiB,OAC1B,GAAI,OAAO,SAAa,IAAa,CACnC,KAAK,QAAQ,WAAW,QAAS,oBAAoB,EACrD,OAEF,KAAK,gBAAkB,GACvB,SAAS,iBAAiB,UAAW,KAAK,gBAAiB,CAAC,QAAS,EAAI,CAAC,EAW5E,QAAQ,EAAS,CAEf,GADA,KAAK,QAAQ,YAAY,UAAU,EAC/B,CAAC,KAAK,gBAAiB,OAC3B,GAAI,OAAO,SAAa,IAAa,OACrC,KAAK,gBAAkB,GACvB,SAAS,oBAAoB,UAAW,KAAK,gBAAiB,CAAC,QAAS,EAAI,CAAC,EAMvE,eAAe,CAAC,EAA4B,CAElD,GAAI,KAAK,eAAe,IAAI,EAAM,GAAG,EAAG,OAMxC,GAAI,KAAK,aAAa,CAAK,GAAK,CAAC,KAAK,cAAc,CAAK,EAAG,OAE5D,IAAM,EAAQ,KAAK,aAAa,CAAK,EAErC,KAAK,QAAQ,gBAAgB,mBAAoB,CAAC,OAAK,CAAC,EAExD,EAAc,SAAS,CAAC,KAAM,OAAO,GAAO,CAAC,EAOvC,YAAY,CAAC,EAA+B,CAClD,IAAM,EAAS,EAAM,OACrB,GAAI,EAAE,aAAkB,aAAc,MAAO,GAC7C,OAAO,KAAK,eAAe,IAAI,EAAO,OAAO,GAAK,EAAO,kBAUnD,aAAa,CAAC,EAA+B,CACnD,OAAO,EAAM,SAAW,EAAM,SAAW,EAAM,OAUzC,YAAY,CAAC,EAA8B,CACjD,IAAM,EAAkB,CAAC,EAEzB,GAAI,EAAM,SAAW,EAAM,QAAS,EAAM,KAAK,MAAM,EACrD,GAAI,EAAM,SAAU,EAAM,KAAK,OAAO,EACtC,GAAI,EAAM,OAAQ,EAAM,KAAK,KAAK,EAElC,IAAM,EAAM,EAAM,MAAQ,IAAM,QAAU,EAAM,IAAI,YAAY,EAGhE,OAFA,EAAM,KAAK,CAAG,EAEP,EAAM,KAAK,GAAG,EAEzB,CAYO,IAAM,EAA0B,IAAI",
-  "debugId": "2945D18B490E57D964756E2164756E21",
+  "debugId": "3118F2268D83C88364756E2164756E21",
   "names": []
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alwatr/keyboard-shortcut",
-  "version": "9.31.0",
+  "version": "9.33.0",
   "description": "Global keyboard-to-action bridge for Alwatr Flux. Listens for keydown and dispatches Flux actions based on normalized key combos.",
   "license": "MPL-2.0",
   "author": "S. Ali Mihandoost <ali.mihandoost@gmail.com> (https://ali.mihandoost.com)",
@@ -21,12 +21,12 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@alwatr/action": "9.31.0",
-    "@alwatr/logger": "9.31.0"
+    "@alwatr/action": "9.33.0",
+    "@alwatr/logger": "9.33.0"
   },
   "devDependencies": {
     "@alwatr/nano-build": "9.25.0",
-    "@alwatr/standard": "9.16.0",
+    "@alwatr/standard": "9.33.0",
     "@alwatr/type-helper": "9.14.0",
     "@happy-dom/global-registrator": "^20.10.2",
     "typescript": "^6.0.3"
@@ -70,5 +70,5 @@
     "flux",
     "typescript"
   ],
-  "gitHead": "a2bdb86945c56f8b99b6dd0f8ec714df70dfa3e5"
+  "gitHead": "ba7e63efa62c86c7845269f94c4cc9924c38ff21"
 }