@cxl/keyboard 0.1.0 → 1.1.0

package/README.md

@@ -2,16 +2,15 @@
 	
 [![npm version](https://badge.fury.io/js/%40cxl%2Fkeyboard.svg)](https://badge.fury.io/js/%40cxl%2Fkeyboard)
 
-Keyboard Handling Library
+Lightweight module for handling keyboard input on HTML elements with customizable layouts and configurable key sequence timing. Provides utilities to parse, normalize, and translate key events into standardized string representations, with support for modifier keys and platform-specific conventions.
 
 ## Project Details
 
--   Branch Version: [0.1.0](https://npmjs.com/package/@cxl/keyboard/v/0.1.0)
--   License: UNLICENSED
--   Documentation: [Link](https://cxlio.github.io/cxl/keyboard)
--   Report Issues: [Github](https://github.com/cxlio/cxl/issues)
+-   Branch Version: [1.1.0](https://npmjs.com/package/@cxl/keyboard/v/1.1.0)
+-   License: GPL-3.0
+-   Documentation: [Link](https://cxlio.github.io/docs/@cxl/keyboard)
+-   Report Issues: [Github](https://github.com/cxlio/open/issues)
 
 ## Installation
 
 	npm install @cxl/keyboard
-

package/index.bundle.js

@@ -0,0 +1 @@
+var L=typeof window<"u"?window.navigator:{language:"en-US",platform:"nodejs"},A=/Mac|iPod|iPhone|iPad/,C=/(shift|ctrl|control|alt|option|meta|command|cmd|mod|[^\s+]+)(\s*\+|\s)?/g,D={"?":"/",">":".","<":",",'"':"'",":":";","{":"[","}":"]","|":"\\","~":"`","+":"=",_:"-","!":"1","@":"2","#":"3",$:"4","%":"5","^":"6","&":"7","*":"8","(":"9",")":"0"},M={ArrowUp:"up",ArrowDown:"down",ArrowLeft:"left",ArrowRight:"right",Escape:"esc",Space:"space",Backquote:"`",Minus:"-",Equal:"=",BracketLeft:"[",BracketRight:"]",Quote:"'",Backslash:"\\",Apostrophe:"'",Semicolon:";",Comma:",",Period:".",Slash:"/"},d={shiftMap:D,translate({code:e,key:o}){let r=M[e];return r||(e.startsWith("Key")?e.slice(3).toLowerCase():e.startsWith("Digit")?e.slice(5):o.toLowerCase())}},q={"en-US":d};function k(e,{translate:o,altName:r,modName:i}){let n=e.key;if(!n||n==="Shift"||n==="Alt"||n==="Meta"||n==="Control"||n==="Dead"&&!e.altKey)return"";let s=o(e),t;return e.ctrlKey&&(t="ctrl"),e.altKey&&(t=t?t+"+"+r:r),e.shiftKey&&(t=t?t+"+shift":"shift"),e.metaKey&&(t=t?t+"+"+i:i),t?t+"+"+s:s}function P({element:e,onKey:o,delay:r,layout:i,capture:n}){let s=r===void 0?250:r,t=[],a=0,f=!1;i??=h();let S=m(i);function p(c){if(f||c.isComposing||c.keyCode===229||c.getModifierState("AltGraph"))return;let l=k(c,S),u=Date.now();if(!l)return;u-a<s?t.push(l):t=[l];let y=t.slice(0);do{if(o(y.join(" "),t)!==!1){c.stopPropagation(),c.preventDefault(),u=0;break}y.shift()}while(y.length);a=u}function K(){f=!0,t=[],a=0}function w(){f=!1}return e.addEventListener("compositionstart",K,{capture:n}),e.addEventListener("compositionend",w,{capture:n}),e.addEventListener("keydown",p,{capture:n}),()=>{e.removeEventListener("compositionstart",K,{capture:n}),e.removeEventListener("compositionend",w,{capture:n}),e.removeEventListener("keydown",p,{capture:n})}}function h(){return q[L.language]??d}function g(){return{ctrlKey:!1,shiftKey:!1,metaKey:!1,altKey:!1,key:"",code:""}}function E(e,{modKey:o,shiftMap:r}){let i=[],n,s=g();for(;n=C.exec(e.toLowerCase());){let t=n[1]??"";if(t==="shift")s.shiftKey=!0;else if(t==="ctrl"||t==="control")s.ctrlKey=!0;else if(t==="alt"||t==="option")s.altKey=!0;else if(t==="meta"||t==="cmd"||t==="command")s.metaKey=!0;else if(t==="mod")s[o]=!0;else{let a=r[t];a?(s.key=a,s.shiftKey=!0):s.key=t}n[2]!=="+"&&(i.push(s),s=g())}return i}function m(e){let o=A.test(L.platform);return{...d,modKey:o?"metaKey":"ctrlKey",altName:o?"option":"alt",modName:o?"cmd":"meta",...e}}function x(e,o=h()){return E(e,m(o))}function b(e,o=h()){let r=m(o);return E(e,r).map(n=>k(n,r)).join(" ")}export{q as KeyboardLayoutData,d as enUsKeyboardLayout,P as handleKeyboard,b as normalize,x as parseKey};

package/index.d.ts

@@ -1,16 +1,16 @@
-/// <amd-module name="@cxl/keyboard" />
-interface Key {
+interface __dts_0_Key {
     ctrlKey: boolean;
     altKey: boolean;
     shiftKey: boolean;
     metaKey: boolean;
     key: string;
+    code: string;
 }
 /**
  * The `KeyboardOptions` interface defines the configuration needed to handle keyboard interactions with
  * a specific HTML element.
  */
-export interface KeyboardOptions {
+interface KeyboardOptions {
     /**
      * Specifies the HTML element on which keyboard events are captured.
      * This element will receive focus and listen for key events.
@@ -38,12 +38,41 @@ export interface KeyboardOptions {
      */
     capture?: boolean;
 }
-export interface KeyboardLayout {
-    shiftedKeys: string[];
-    shiftMap: Record<string, string>;
-    modKey: 'metaKey' | 'ctrlKey';
+/**
+ * The `KeyboardLayout` interface describes how a keyboard layout should be structured internally.
+ */
+interface KeyboardLayout {
+    /**
+     * A mapping of shifted keys to their non-shifted counterparts, used to accurately
+     * interpret which character a shifted key press represents.
+     */
+    shiftMap?: Record<string, string | undefined>;
+    /**
+     * Indicates whether the 'meta' or 'ctrl' key is the primary modifier used for commands,
+     * differing based on the operating system (e.g., 'metaKey' for macOS).
+     */
+    modKey?: 'metaKey' | 'ctrlKey';
+    altName?: 'option' | 'alt';
+    modName?: 'meta' | 'cmd';
+    /**
+     * Describes a function that translates a `Key` object (representing a keyboard event) to a character string.
+     */
+    translate?(ev: __dts_0_Key): string;
 }
-export declare const KeyboardLayoutData: Record<string, KeyboardLayout>;
+declare const enUsKeyboardLayout: {
+    shiftMap: Record<string, string | undefined>;
+    /**
+     * The `translate` method converts a `Key` event into a string representation.
+     * Firstly, it checks the `TranslateKey` map for special keys (like arrows or space),
+     * which have predefined string values. For keys corresponding to
+     * alphabet letters and numbers, the method derives the letter from
+     * the key `code`, ensuring it's lowercase for uniformity.
+     * If none of these match, it defaults to using the `key` property,
+     * which allows handling other miscellaneous keys gracefully.
+     */
+    translate({ code, key }: __dts_0_Key): string;
+};
+declare const KeyboardLayoutData: Record<string, KeyboardLayout>;
 /**
  * The `handleKeyboard` function sets up event listeners to handle keyboard events on a given HTML element.
  * It accepts a  configuration object (`KeyboardOptions`) which includes the target HTML element, a callback
@@ -62,25 +91,16 @@ export declare const KeyboardLayoutData: Record<string, KeyboardLayout>;
  *   browser actions.
  * @return A cleanup function that removes the event listener.
  */
-export declare function handleKeyboard({ element, onKey, delay, layout, capture, }: KeyboardOptions): () => void;
-/**
- * This function, `parseKey`, takes a key combination string and splits it into a sequence of `Key` objects.
- * It uses regular  expressions to identify each part of the key combination, accounting for modifier keys
- * like 'shift', 'ctrl', 'alt', 'meta', and 'mod', the latter being dependent on the `modKey` from the
- * `KeyboardLayout` (either 'ctrlKey' or 'metaKey' depending on the platform). For non-modifier keys, it
- * checks if the `shiftKey` is active and if the key should be shifted using the `shiftMap`. This logic
- * ensures the function captures accurate key state details in preparation for further handling like matching
- * key sequences in the `handleKeyboard` function.
- */
-export declare function parseKey(key: string, { modKey, shiftedKeys, shiftMap }?: KeyboardLayout): Key[];
+declare function handleKeyboard({ element, onKey, delay, layout, capture, }: KeyboardOptions): () => void;
+declare function parseKey(key: string, layout?: KeyboardLayout): __dts_0_Key[];
 /**
  * Converts a string representing a key combination into a normalized string format.
  * This function takes a `key` string and an optional `layout` object (defaults to the user's layout).
+ *
  * It uses `parseKey` to break the key combination into individual `Key` objects, each representing
  * a parsed key press. It then converts each `Key` object back to a string using `keyboardEventToString`,
- * considering the layout's details like `shiftedKeys` and `shiftMap`. The resulting
- * strings are concatenated with spaces and returned as the normalized form. This is useful
+ * considering the layout's details. This is useful
  * for ensuring consistent representation of key sequences across different keyboard layouts.
  */
-export declare function normalize(key: string, layout?: KeyboardLayout): string;
-export {};
+declare function normalize(key: string, layout?: KeyboardLayout): string;
+export { handleKeyboard, parseKey, normalize, KeyboardOptions, KeyboardLayout, enUsKeyboardLayout, KeyboardLayoutData };

package/package.json

@@ -1,26 +1,23 @@
 {
   "name": "@cxl/keyboard",
-  "version": "0.1.0",
-  "description": "Keyboard Handling Library",
-  "license": "UNLICENSED",
+  "version": "1.1.0",
+  "description": "Lightweight module for handling keyboard input on HTML elements with customizable layouts and configurable key sequence timing. Provides utilities to parse, normalize, and translate key events into standardized string representations, with support for modifier keys and platform-specific conventions.",
+  "license": "GPL-3.0",
   "files": [
     "*.js",
     "*.d.ts",
     "*.css",
-    "amd/*.js",
-    "amd/*.d.ts",
-    "mjs/*.js",
-    "mjs/*.d.ts",
-    "LICENSE",
+    "LICENSE.md",
     "*.md"
   ],
-  "main": "index.js",
-  "browser": "amd/index.js",
-  "homepage": "https://cxlio.github.io/cxl/keyboard",
-  "bugs": "https://github.com/cxlio/cxl/issues",
+  "main": "./index.bundle.js",
+  "browser": "./index.bundle.js",
+  "homepage": "https://cxlio.github.io/docs/@cxl/keyboard",
+  "bugs": "https://github.com/cxlio/open/issues",
   "repository": {
     "type": "git",
-    "url": "https://github.com/cxlio/cxl.git",
+    "url": "https://github.com/cxlio/open.git",
     "directory": "keyboard"
-  }
+  },
+  "type": "module"
 }

package/amd/index.d.ts

@@ -1,86 +0,0 @@
-/// <amd-module name="@cxl/keyboard" />
-interface Key {
-    ctrlKey: boolean;
-    altKey: boolean;
-    shiftKey: boolean;
-    metaKey: boolean;
-    key: string;
-}
-/**
- * The `KeyboardOptions` interface defines the configuration needed to handle keyboard interactions with
- * a specific HTML element.
- */
-export interface KeyboardOptions {
-    /**
-     * Specifies the HTML element on which keyboard events are captured.
-     * This element will receive focus and listen for key events.
-     */
-    element: HTMLElement;
-    /**
-     * A callback function that processes key events. It receives the current key being pressed
-     * and the sequence of keys accumulated so far. It returns `true` or `false` to indicate whether
-     * the sequence was consumed.
-     */
-    onKey: (key: string, sequence: string[]) => boolean;
-    /**
-     * The time in milliseconds to wait between key presses before resetting the sequence.
-     * Defaults to 250ms if not provided, ensuring thoughtful key sequences rather than accidental key presses.
-     */
-    delay?: number;
-    /**
-     * Optional parameter to specify a custom `KeyboardLayout`.
-     * Defaults to 'en-US' if not provided. This affects how key combinations and modifier keys are interpreted.
-     */
-    layout?: KeyboardLayout;
-    /**
-     * Boolean indicating whether to capture key events in the capture phase.
-     * This determines when the event listener reacts in the event propagation flow.
-     */
-    capture?: boolean;
-}
-export interface KeyboardLayout {
-    shiftedKeys: string[];
-    shiftMap: Record<string, string>;
-    modKey: 'metaKey' | 'ctrlKey';
-}
-export declare const KeyboardLayoutData: Record<string, KeyboardLayout>;
-/**
- * The `handleKeyboard` function sets up event listeners to handle keyboard events on a given HTML element.
- * It accepts a  configuration object (`KeyboardOptions`) which includes the target HTML element, a callback
- * `onKey` to handle keyboard sequences, a `delay` for typing sequence recognition, an optional keyboard
- * layout, and an optional capture mode for events.
- *
- * - Defaults the delay to 250ms if not specified, using this delay to determine when to treat subsequent
- *   key presses as part of the same sequence or a new one.
- * - Determines the keyboard layout, either from the provided options or defaults, which affects how keys
- *   (especially with modifiers) are interpreted.
- * - Adds a `keydown` event listener to the provided element, allowing modification of event behavior such
- *   as propagation and default handling based on the `onKey` callback result.
- * - Builds a key sequence based on timing and calls the `onKey` handler with the assembled sequence,
- *   stopping event propagation based on handler response.
- * - The handler uses the sequence to manage shortcuts and performs preventative measures against default
- *   browser actions.
- * @return A cleanup function that removes the event listener.
- */
-export declare function handleKeyboard({ element, onKey, delay, layout, capture, }: KeyboardOptions): () => void;
-/**
- * This function, `parseKey`, takes a key combination string and splits it into a sequence of `Key` objects.
- * It uses regular  expressions to identify each part of the key combination, accounting for modifier keys
- * like 'shift', 'ctrl', 'alt', 'meta', and 'mod', the latter being dependent on the `modKey` from the
- * `KeyboardLayout` (either 'ctrlKey' or 'metaKey' depending on the platform). For non-modifier keys, it
- * checks if the `shiftKey` is active and if the key should be shifted using the `shiftMap`. This logic
- * ensures the function captures accurate key state details in preparation for further handling like matching
- * key sequences in the `handleKeyboard` function.
- */
-export declare function parseKey(key: string, { modKey, shiftedKeys, shiftMap }?: KeyboardLayout): Key[];
-/**
- * Converts a string representing a key combination into a normalized string format.
- * This function takes a `key` string and an optional `layout` object (defaults to the user's layout).
- * It uses `parseKey` to break the key combination into individual `Key` objects, each representing
- * a parsed key press. It then converts each `Key` object back to a string using `keyboardEventToString`,
- * considering the layout's details like `shiftedKeys` and `shiftMap`. The resulting
- * strings are concatenated with spaces and returned as the normalized form. This is useful
- * for ensuring consistent representation of key sequences across different keyboard layouts.
- */
-export declare function normalize(key: string, layout?: KeyboardLayout): string;
-export {};

package/amd/index.js

@@ -1 +0,0 @@
-define("@cxl/keyboard",["require","exports"],(function(e,t){"use strict";Object.defineProperty(t,"__esModule",{value:!0}),t.KeyboardLayoutData=void 0,t.handleKeyboard=function({element:e,onKey:a,delay:n,layout:r,capture:s}){const y=void 0===n?250:n,l=o.language;let c=[],f=0;const d=r||t.KeyboardLayoutData[l]||t.KeyboardLayoutData["en-US"];function u(e){const t=i(e,d);let o=Date.now();if(!t)return;o-f<y?c.push(t):c=[t];const n=c.slice(0);do{if(!1!==a(n.join(" "),c)){e.stopPropagation(),e.preventDefault(),o=0;break}n.shift()}while(n.length);f=o}return e.addEventListener("keydown",u,{capture:s}),()=>e.removeEventListener("keydown",u,{capture:s})},t.parseKey=y,t.normalize=function(e,t=s()){return y(e,t).map((e=>i(e,t))).join(" ")};const o="undefined"!=typeof window?window.navigator:{language:"en-US",platform:"nodejs"},a=/(shift|ctrl|control|alt|option|meta|command|cmd|mod|[^\s+]+)(\s*\+|\s)?/g,n={"/":"?",".":">",",":"<","'":'"',";":":","[":"{","]":"}","\\":"|","`":"~","=":"+","-":"_",1:"!",2:"@",3:"#",4:"$",5:"%",6:"^",7:"&",8:"*",9:"(",0:")"};t.KeyboardLayoutData={"en-US":{shiftedKeys:Object.values(n),shiftMap:n,modKey:/Mac|iPod|iPhone|iPad/.test(o.platform)?"metaKey":"ctrlKey"}};const r={ArrowUp:"up",ArrowDown:"down",ArrowLeft:"left",ArrowRight:"right",Escape:"esc"," ":"space"};function i(e,{shiftedKeys:t}){const o=e.key;if(!o||"Shift"===o||"Alt"===o||"Meta"===o||"Control"===o)return"";const a=r[o]||o.toLowerCase();let n;return e.ctrlKey&&(n="ctrl"),e.altKey&&(n=n?n+"+alt":"alt"),e.shiftKey&&!t.includes(a)&&(n=n?n+"+shift":"shift"),e.metaKey&&(n=n?n+"+meta":"meta"),n?n+"+"+a:a}function s(){return t.KeyboardLayoutData[o?.language]||t.KeyboardLayoutData["en-US"]}function y(e,{modKey:t,shiftedKeys:o,shiftMap:n}=s()){const r=[];let i,y={ctrlKey:!1,shiftKey:!1,metaKey:!1,altKey:!1,key:""};for(;i=a.exec(e.toLowerCase());){const e=i[1];if("shift"===e)y.shiftKey=!0;else if("ctrl"===e||"control"===e)y.ctrlKey=!0;else if("alt"===e||"option"===e)y.altKey=!0;else if("meta"===e||"cmd"===e||"command"===e)y.metaKey=!0;else if("mod"===e)y[t]=!0;else if(y.key=e,y.shiftKey)if(o.includes(e))y.shiftKey=!1;else{const t=n[e];t&&(y.key=t,y.shiftKey=!1)}"+"!==i[2]&&(r.push(y),y={ctrlKey:!1,shiftKey:!1,metaKey:!1,altKey:!1,key:""})}return r}}));

package/index.js

@@ -1,198 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.KeyboardLayoutData = void 0;
-exports.handleKeyboard = handleKeyboard;
-exports.parseKey = parseKey;
-exports.normalize = normalize;
-///<amd-module name="@cxl/keyboard"/>
-const navigator = typeof window !== 'undefined'
-    ? window.navigator
-    : { language: 'en-US', platform: 'nodejs' };
-const IS_MAC = /Mac|iPod|iPhone|iPad/;
-const PARSE_KEY = /(shift|ctrl|control|alt|option|meta|command|cmd|mod|[^\s+]+)(\s*\+|\s)?/g;
-const SHIFT_MAP = {
-    '/': '?',
-    '.': '>',
-    ',': '<',
-    "'": '"',
-    ';': ':',
-    '[': '{',
-    ']': '}',
-    '\\': '|',
-    '`': '~',
-    '=': '+',
-    '-': '_',
-    '1': '!',
-    '2': '@',
-    '3': '#',
-    '4': '$',
-    '5': '%',
-    '6': '^',
-    '7': '&',
-    '8': '*',
-    '9': '(',
-    '0': ')',
-};
-exports.KeyboardLayoutData = {
-    'en-US': {
-        shiftedKeys: Object.values(SHIFT_MAP),
-        shiftMap: SHIFT_MAP,
-        modKey: IS_MAC.test(navigator.platform) ? 'metaKey' : 'ctrlKey',
-    },
-};
-const TranslateKey = {
-    ArrowUp: 'up',
-    ArrowDown: 'down',
-    ArrowLeft: 'left',
-    ArrowRight: 'right',
-    Escape: 'esc',
-    ' ': 'space',
-};
-/**
- * This function converts a `Key` event into a string representation, encoding modifier keys
- * (ctrl, alt, shift, meta) and the key itself. It checks each modifier key flag in the `Key`
- * object, constructing a result string with '+' separators. Non-modifier keys are lowercased
- * and looked up in `TranslateKey` for a more readable name. If the key itself is a shifted
- * character (not included in `shiftedKeys`), 'shift' is added to the modifiers. This string
- * format is useful for handling complex keyboard shortcuts consistently across different layouts.
- */
-function keyboardEventToString(ev, { shiftedKeys }) {
-    const key = ev.key;
-    if (!key ||
-        key === 'Shift' ||
-        key === 'Alt' ||
-        key === 'Meta' ||
-        key === 'Control')
-        return '';
-    const ch = TranslateKey[key] || key.toLowerCase();
-    let result;
-    if (ev.ctrlKey)
-        result = 'ctrl';
-    if (ev.altKey)
-        result = result ? result + '+alt' : 'alt';
-    if (ev.shiftKey && !shiftedKeys.includes(ch))
-        result = result ? result + '+shift' : 'shift';
-    if (ev.metaKey)
-        result = result ? result + '+meta' : 'meta';
-    return result ? result + '+' + ch : ch;
-}
-/**
- * The `handleKeyboard` function sets up event listeners to handle keyboard events on a given HTML element.
- * It accepts a  configuration object (`KeyboardOptions`) which includes the target HTML element, a callback
- * `onKey` to handle keyboard sequences, a `delay` for typing sequence recognition, an optional keyboard
- * layout, and an optional capture mode for events.
- *
- * - Defaults the delay to 250ms if not specified, using this delay to determine when to treat subsequent
- *   key presses as part of the same sequence or a new one.
- * - Determines the keyboard layout, either from the provided options or defaults, which affects how keys
- *   (especially with modifiers) are interpreted.
- * - Adds a `keydown` event listener to the provided element, allowing modification of event behavior such
- *   as propagation and default handling based on the `onKey` callback result.
- * - Builds a key sequence based on timing and calls the `onKey` handler with the assembled sequence,
- *   stopping event propagation based on handler response.
- * - The handler uses the sequence to manage shortcuts and performs preventative measures against default
- *   browser actions.
- * @return A cleanup function that removes the event listener.
- */
-function handleKeyboard({ element, onKey, delay, layout, capture, }) {
-    const D = delay === undefined ? 250 : delay;
-    const locale = navigator.language;
-    let sequence = [];
-    let lastT = 0;
-    const newLayout = layout || exports.KeyboardLayoutData[locale] || exports.KeyboardLayoutData['en-US'];
-    function handler(ev) {
-        const k = keyboardEventToString(ev, newLayout);
-        let t = Date.now();
-        if (!k)
-            return;
-        if (t - lastT < D)
-            sequence.push(k);
-        else
-            sequence = [k];
-        const seq = sequence.slice(0);
-        do {
-            if (onKey(seq.join(' '), sequence) !== false) {
-                ev.stopPropagation();
-                ev.preventDefault();
-                t = 0;
-                break;
-            }
-            seq.shift();
-        } while (seq.length);
-        lastT = t;
-    }
-    element.addEventListener('keydown', handler, { capture });
-    return () => element.removeEventListener('keydown', handler, { capture });
-}
-function getDefaultLayout() {
-    return (exports.KeyboardLayoutData[navigator?.language] || exports.KeyboardLayoutData['en-US']);
-}
-function newKey() {
-    return {
-        ctrlKey: false,
-        shiftKey: false,
-        metaKey: false,
-        altKey: false,
-        key: '',
-    };
-}
-/**
- * This function, `parseKey`, takes a key combination string and splits it into a sequence of `Key` objects.
- * It uses regular  expressions to identify each part of the key combination, accounting for modifier keys
- * like 'shift', 'ctrl', 'alt', 'meta', and 'mod', the latter being dependent on the `modKey` from the
- * `KeyboardLayout` (either 'ctrlKey' or 'metaKey' depending on the platform). For non-modifier keys, it
- * checks if the `shiftKey` is active and if the key should be shifted using the `shiftMap`. This logic
- * ensures the function captures accurate key state details in preparation for further handling like matching
- * key sequences in the `handleKeyboard` function.
- */
-function parseKey(key, { modKey, shiftedKeys, shiftMap } = getDefaultLayout()) {
-    const sequence = [];
-    let match;
-    let event = newKey();
-    while ((match = PARSE_KEY.exec(key.toLowerCase()))) {
-        const ch = match[1];
-        if (ch === 'shift')
-            event.shiftKey = true;
-        else if (ch === 'ctrl' || ch === 'control')
-            event.ctrlKey = true;
-        else if (ch === 'alt' || ch === 'option')
-            event.altKey = true;
-        else if (ch === 'meta' || ch === 'cmd' || ch === 'command')
-            event.metaKey = true;
-        else if (ch === 'mod')
-            event[modKey] = true;
-        else {
-            event.key = ch;
-            if (event.shiftKey) {
-                if (shiftedKeys.includes(ch)) {
-                    event.shiftKey = false;
-                }
-                else {
-                    const shifted = shiftMap[ch];
-                    if (shifted) {
-                        event.key = shifted;
-                        event.shiftKey = false;
-                    }
-                }
-            }
-        }
-        if (match[2] !== '+') {
-            sequence.push(event);
-            event = newKey();
-        }
-    }
-    return sequence;
-}
-/**
- * Converts a string representing a key combination into a normalized string format.
- * This function takes a `key` string and an optional `layout` object (defaults to the user's layout).
- * It uses `parseKey` to break the key combination into individual `Key` objects, each representing
- * a parsed key press. It then converts each `Key` object back to a string using `keyboardEventToString`,
- * considering the layout's details like `shiftedKeys` and `shiftMap`. The resulting
- * strings are concatenated with spaces and returned as the normalized form. This is useful
- * for ensuring consistent representation of key sequences across different keyboard layouts.
- */
-function normalize(key, layout = getDefaultLayout()) {
-    const sequence = parseKey(key, layout);
-    return sequence.map(key => keyboardEventToString(key, layout)).join(' ');
-}

package/index.min.js

@@ -1 +0,0 @@
-"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),exports.KeyboardLayoutData=void 0,exports.handleKeyboard=handleKeyboard,exports.parseKey=parseKey,exports.normalize=normalize;const navigator="undefined"!=typeof window?window.navigator:{language:"en-US",platform:"nodejs"},IS_MAC=/Mac|iPod|iPhone|iPad/,PARSE_KEY=/(shift|ctrl|control|alt|option|meta|command|cmd|mod|[^\s+]+)(\s*\+|\s)?/g,SHIFT_MAP={"/":"?",".":">",",":"<","'":'"',";":":","[":"{","]":"}","\\":"|","`":"~","=":"+","-":"_",1:"!",2:"@",3:"#",4:"$",5:"%",6:"^",7:"&",8:"*",9:"(",0:")"};exports.KeyboardLayoutData={"en-US":{shiftedKeys:Object.values(SHIFT_MAP),shiftMap:SHIFT_MAP,modKey:IS_MAC.test(navigator.platform)?"metaKey":"ctrlKey"}};const TranslateKey={ArrowUp:"up",ArrowDown:"down",ArrowLeft:"left",ArrowRight:"right",Escape:"esc"," ":"space"};function keyboardEventToString(e,{shiftedKeys:t}){const o=e.key;if(!o||"Shift"===o||"Alt"===o||"Meta"===o||"Control"===o)return"";const a=TranslateKey[o]||o.toLowerCase();let n;return e.ctrlKey&&(n="ctrl"),e.altKey&&(n=n?n+"+alt":"alt"),e.shiftKey&&!t.includes(a)&&(n=n?n+"+shift":"shift"),e.metaKey&&(n=n?n+"+meta":"meta"),n?n+"+"+a:a}function handleKeyboard({element:e,onKey:t,delay:o,layout:a,capture:n}){const r=void 0===o?250:o,s=navigator.language;let i=[],y=0;const l=a||exports.KeyboardLayoutData[s]||exports.KeyboardLayoutData["en-US"];function d(e){const o=keyboardEventToString(e,l);let a=Date.now();if(!o)return;a-y<r?i.push(o):i=[o];const n=i.slice(0);do{if(!1!==t(n.join(" "),i)){e.stopPropagation(),e.preventDefault(),a=0;break}n.shift()}while(n.length);y=a}return e.addEventListener("keydown",d,{capture:n}),()=>e.removeEventListener("keydown",d,{capture:n})}function getDefaultLayout(){return exports.KeyboardLayoutData[navigator?.language]||exports.KeyboardLayoutData["en-US"]}function newKey(){return{ctrlKey:!1,shiftKey:!1,metaKey:!1,altKey:!1,key:""}}function parseKey(e,{modKey:t,shiftedKeys:o,shiftMap:a}=getDefaultLayout()){const n=[];let r,s=newKey();for(;r=PARSE_KEY.exec(e.toLowerCase());){const e=r[1];if("shift"===e)s.shiftKey=!0;else if("ctrl"===e||"control"===e)s.ctrlKey=!0;else if("alt"===e||"option"===e)s.altKey=!0;else if("meta"===e||"cmd"===e||"command"===e)s.metaKey=!0;else if("mod"===e)s[t]=!0;else if(s.key=e,s.shiftKey)if(o.includes(e))s.shiftKey=!1;else{const t=a[e];t&&(s.key=t,s.shiftKey=!1)}"+"!==r[2]&&(n.push(s),s=newKey())}return n}function normalize(e,t=getDefaultLayout()){return parseKey(e,t).map((e=>keyboardEventToString(e,t))).join(" ")}

package/mjs/index.d.ts

@@ -1,85 +0,0 @@
-interface Key {
-    ctrlKey: boolean;
-    altKey: boolean;
-    shiftKey: boolean;
-    metaKey: boolean;
-    key: string;
-}
-/**
- * The `KeyboardOptions` interface defines the configuration needed to handle keyboard interactions with
- * a specific HTML element.
- */
-export interface KeyboardOptions {
-    /**
-     * Specifies the HTML element on which keyboard events are captured.
-     * This element will receive focus and listen for key events.
-     */
-    element: HTMLElement;
-    /**
-     * A callback function that processes key events. It receives the current key being pressed
-     * and the sequence of keys accumulated so far. It returns `true` or `false` to indicate whether
-     * the sequence was consumed.
-     */
-    onKey: (key: string, sequence: string[]) => boolean;
-    /**
-     * The time in milliseconds to wait between key presses before resetting the sequence.
-     * Defaults to 250ms if not provided, ensuring thoughtful key sequences rather than accidental key presses.
-     */
-    delay?: number;
-    /**
-     * Optional parameter to specify a custom `KeyboardLayout`.
-     * Defaults to 'en-US' if not provided. This affects how key combinations and modifier keys are interpreted.
-     */
-    layout?: KeyboardLayout;
-    /**
-     * Boolean indicating whether to capture key events in the capture phase.
-     * This determines when the event listener reacts in the event propagation flow.
-     */
-    capture?: boolean;
-}
-export interface KeyboardLayout {
-    shiftedKeys: string[];
-    shiftMap: Record<string, string>;
-    modKey: 'metaKey' | 'ctrlKey';
-}
-export declare const KeyboardLayoutData: Record<string, KeyboardLayout>;
-/**
- * The `handleKeyboard` function sets up event listeners to handle keyboard events on a given HTML element.
- * It accepts a  configuration object (`KeyboardOptions`) which includes the target HTML element, a callback
- * `onKey` to handle keyboard sequences, a `delay` for typing sequence recognition, an optional keyboard
- * layout, and an optional capture mode for events.
- *
- * - Defaults the delay to 250ms if not specified, using this delay to determine when to treat subsequent
- *   key presses as part of the same sequence or a new one.
- * - Determines the keyboard layout, either from the provided options or defaults, which affects how keys
- *   (especially with modifiers) are interpreted.
- * - Adds a `keydown` event listener to the provided element, allowing modification of event behavior such
- *   as propagation and default handling based on the `onKey` callback result.
- * - Builds a key sequence based on timing and calls the `onKey` handler with the assembled sequence,
- *   stopping event propagation based on handler response.
- * - The handler uses the sequence to manage shortcuts and performs preventative measures against default
- *   browser actions.
- * @return A cleanup function that removes the event listener.
- */
-export declare function handleKeyboard({ element, onKey, delay, layout, capture, }: KeyboardOptions): () => void;
-/**
- * This function, `parseKey`, takes a key combination string and splits it into a sequence of `Key` objects.
- * It uses regular  expressions to identify each part of the key combination, accounting for modifier keys
- * like 'shift', 'ctrl', 'alt', 'meta', and 'mod', the latter being dependent on the `modKey` from the
- * `KeyboardLayout` (either 'ctrlKey' or 'metaKey' depending on the platform). For non-modifier keys, it
- * checks if the `shiftKey` is active and if the key should be shifted using the `shiftMap`. This logic
- * ensures the function captures accurate key state details in preparation for further handling like matching
- * key sequences in the `handleKeyboard` function.
- */
-export declare function parseKey(key: string, { modKey, shiftedKeys, shiftMap }?: KeyboardLayout): Key[];
-/**
- * Converts a string representing a key combination into a normalized string format.
- * This function takes a `key` string and an optional `layout` object (defaults to the user's layout).
- * It uses `parseKey` to break the key combination into individual `Key` objects, each representing
- * a parsed key press. It then converts each `Key` object back to a string using `keyboardEventToString`,
- * considering the layout's details like `shiftedKeys` and `shiftMap`. The resulting
- * strings are concatenated with spaces and returned as the normalized form. This is useful
- * for ensuring consistent representation of key sequences across different keyboard layouts.
- */
-export declare function normalize(key: string, layout?: KeyboardLayout): string;
-export {};

package/mjs/index.js

@@ -1 +0,0 @@
-const navigator="undefined"!=typeof window?window.navigator:{language:"en-US",platform:"nodejs"},IS_MAC=/Mac|iPod|iPhone|iPad/,PARSE_KEY=/(shift|ctrl|control|alt|option|meta|command|cmd|mod|[^\s+]+)(\s*\+|\s)?/g,SHIFT_MAP={"/":"?",".":">",",":"<","'":'"',";":":","[":"{","]":"}","\\":"|","`":"~","=":"+","-":"_",1:"!",2:"@",3:"#",4:"$",5:"%",6:"^",7:"&",8:"*",9:"(",0:")"};export const KeyboardLayoutData={"en-US":{shiftedKeys:Object.values(SHIFT_MAP),shiftMap:SHIFT_MAP,modKey:IS_MAC.test(navigator.platform)?"metaKey":"ctrlKey"}};const TranslateKey={ArrowUp:"up",ArrowDown:"down",ArrowLeft:"left",ArrowRight:"right",Escape:"esc"," ":"space"};function keyboardEventToString(e,{shiftedKeys:t}){const o=e.key;if(!o||"Shift"===o||"Alt"===o||"Meta"===o||"Control"===o)return"";const a=TranslateKey[o]||o.toLowerCase();let n;return e.ctrlKey&&(n="ctrl"),e.altKey&&(n=n?n+"+alt":"alt"),e.shiftKey&&!t.includes(a)&&(n=n?n+"+shift":"shift"),e.metaKey&&(n=n?n+"+meta":"meta"),n?n+"+"+a:a}export function handleKeyboard({element:e,onKey:t,delay:o,layout:a,capture:n}){const r=void 0===o?250:o,i=navigator.language;let s=[],y=0;const l=a||KeyboardLayoutData[i]||KeyboardLayoutData["en-US"];function f(e){const o=keyboardEventToString(e,l);let a=Date.now();if(!o)return;a-y<r?s.push(o):s=[o];const n=s.slice(0);do{if(!1!==t(n.join(" "),s)){e.stopPropagation(),e.preventDefault(),a=0;break}n.shift()}while(n.length);y=a}return e.addEventListener("keydown",f,{capture:n}),()=>e.removeEventListener("keydown",f,{capture:n})}function getDefaultLayout(){return KeyboardLayoutData[navigator?.language]||KeyboardLayoutData["en-US"]}function newKey(){return{ctrlKey:!1,shiftKey:!1,metaKey:!1,altKey:!1,key:""}}export function parseKey(e,{modKey:t,shiftedKeys:o,shiftMap:a}=getDefaultLayout()){const n=[];let r,i=newKey();for(;r=PARSE_KEY.exec(e.toLowerCase());){const e=r[1];if("shift"===e)i.shiftKey=!0;else if("ctrl"===e||"control"===e)i.ctrlKey=!0;else if("alt"===e||"option"===e)i.altKey=!0;else if("meta"===e||"cmd"===e||"command"===e)i.metaKey=!0;else if("mod"===e)i[t]=!0;else if(i.key=e,i.shiftKey)if(o.includes(e))i.shiftKey=!1;else{const t=a[e];t&&(i.key=t,i.shiftKey=!1)}"+"!==r[2]&&(n.push(i),i=newKey())}return n}export function normalize(e,t=getDefaultLayout()){return parseKey(e,t).map((e=>keyboardEventToString(e,t))).join(" ")}

package/test.d.ts

@@ -1,2 +0,0 @@
-declare const _default: import("@cxl/spec").Test;
-export default _default;