@cxl/keyboard 0.1.0 → 1.0.0

package/README.md

@@ -6,7 +6,7 @@ Keyboard Handling Library
 
 ## Project Details
 
--   Branch Version: [0.1.0](https://npmjs.com/package/@cxl/keyboard/v/0.1.0)
+-   Branch Version: [1.0.0](https://npmjs.com/package/@cxl/keyboard/v/1.0.0)
 -   License: UNLICENSED
 -   Documentation: [Link](https://cxlio.github.io/cxl/keyboard)
 -   Report Issues: [Github](https://github.com/cxlio/cxl/issues)

package/amd/index.d.ts

@@ -5,6 +5,7 @@ interface Key {
     shiftKey: boolean;
     metaKey: boolean;
     key: string;
+    code: string;
 }
 /**
  * The `KeyboardOptions` interface defines the configuration needed to handle keyboard interactions with
@@ -38,10 +39,24 @@ export interface KeyboardOptions {
      */
     capture?: boolean;
 }
+/**
+ * The `KeyboardLayout` interface describes how a keyboard layout should be structured internally.
+ */
 export interface KeyboardLayout {
-    shiftedKeys: string[];
-    shiftMap: Record<string, string>;
-    modKey: 'metaKey' | 'ctrlKey';
+    /**
+     * 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>;
+    /**
+     * Maps the representation of keys when combined with the alt key.
+     */
+    translate(ev: Key): string;
+    /**
+     * 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';
 }
 export declare const KeyboardLayoutData: Record<string, KeyboardLayout>;
 /**
@@ -63,16 +78,7 @@ export declare const KeyboardLayoutData: Record<string, KeyboardLayout>;
  * @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[];
+export declare function parseKey(key: string, layout?: 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).

package/amd/index.js

@@ -1 +1 @@
-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}}));
+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 c=void 0===n?250:n,y=o.language;let u=[],d=0;r||(r=t.KeyboardLayoutData[y]||t.KeyboardLayoutData["en-US"]);const f=l(r);function K(e){const t=i(e,f);let o=Date.now();if(!t)return;o-d<c?u.push(t):u=[t];const n=u.slice(0);do{if(!1!==a(n.join(" "),u)){e.stopPropagation(),e.preventDefault(),o=0;break}n.shift()}while(n.length);d=o}return e.addEventListener("keydown",K,{capture:s}),()=>e.removeEventListener("keydown",K,{capture:s})},t.parseKey=function(e,t=s()){return c(e,l(t))},t.normalize=function(e,t=s()){const o=l(t);return c(e,o).map((e=>i(e,o))).join(" ")};const o="undefined"!=typeof window?window.navigator:{language:"en-US",platform:"nodejs"},a=/Mac|iPod|iPhone|iPad/,n=/(shift|ctrl|control|alt|option|meta|command|cmd|mod|[^\s+]+)(\s*\+|\s)?/g,r={ArrowUp:"up",ArrowDown:"down",ArrowLeft:"left",ArrowRight:"right",Escape:"esc",Space:"space",Backquote:"`",Minus:"-",Equal:"=",BracketLeft:"[",BracketRight:"]",Quote:"'",Backslash:"\\",Apostrophe:"'",Semicolon:";",Comma:",",Period:".",Slash:"/"};function i(e,{translate:t}){const o=e.key;if(!o||"Shift"===o||"Alt"===o||"Meta"===o||"Control"===o||"Dead"===o&&!e.altKey)return"";const a=t(e);let n;return e.ctrlKey&&(n="ctrl"),e.altKey&&(n=n?n+"+alt":"alt"),e.shiftKey&&(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 c(e,{modKey:t,shiftMap:o}){const a=[];let r,i={ctrlKey:!1,shiftKey:!1,metaKey:!1,altKey:!1,key:"",code:""};for(;r=n.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{const t=o[e];t?(i.key=t,i.shiftKey=!0):i.key=e}"+"!==r[2]&&(a.push(i),i={ctrlKey:!1,shiftKey:!1,metaKey:!1,altKey:!1,key:"",code:""})}return a}function l(e){return{modKey:a.test(o.platform)?"metaKey":"ctrlKey",...e}}t.KeyboardLayoutData={"en-US":{shiftMap:{"?":"/",">":".","<":",",'"':"'",":":";","{":"[","}":"]","|":"\\","~":"`","+":"=",_:"-","!":"1","@":"2","#":"3",$:"4","%":"5","^":"6","&":"7","*":"8","(":"9",")":"0"},translate:({code:e,key:t})=>r[e]||(e.startsWith("Key")?e.slice(3).toLowerCase():e.startsWith("Digit")?e.slice(5):t.toLowerCase())}}}));

package/index.d.ts

@@ -5,6 +5,7 @@ interface Key {
     shiftKey: boolean;
     metaKey: boolean;
     key: string;
+    code: string;
 }
 /**
  * The `KeyboardOptions` interface defines the configuration needed to handle keyboard interactions with
@@ -38,10 +39,24 @@ export interface KeyboardOptions {
      */
     capture?: boolean;
 }
+/**
+ * The `KeyboardLayout` interface describes how a keyboard layout should be structured internally.
+ */
 export interface KeyboardLayout {
-    shiftedKeys: string[];
-    shiftMap: Record<string, string>;
-    modKey: 'metaKey' | 'ctrlKey';
+    /**
+     * 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>;
+    /**
+     * Maps the representation of keys when combined with the alt key.
+     */
+    translate(ev: Key): string;
+    /**
+     * 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';
 }
 export declare const KeyboardLayoutData: Record<string, KeyboardLayout>;
 /**
@@ -63,16 +78,7 @@ export declare const KeyboardLayoutData: Record<string, KeyboardLayout>;
  * @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[];
+export declare function parseKey(key: string, layout?: 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).

package/index.js

@@ -11,34 +11,27 @@ const navigator = typeof window !== 'undefined'
 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',
-    },
+    '?': '/',
+    '>': '.',
+    '<': ',',
+    '"': "'",
+    ':': ';',
+    '{': '[',
+    '}': ']',
+    '|': '\\',
+    '~': '`',
+    '+': '=',
+    _: '-',
+    '!': '1',
+    '@': '2',
+    '#': '3',
+    $: '4',
+    '%': '5',
+    '^': '6',
+    '&': '7',
+    '*': '8',
+    '(': '9',
+    ')': '0',
 };
 const TranslateKey = {
     ArrowUp: 'up',
@@ -46,31 +39,63 @@ const TranslateKey = {
     ArrowLeft: 'left',
     ArrowRight: 'right',
     Escape: 'esc',
-    ' ': 'space',
+    Space: 'space',
+    Backquote: '`',
+    Minus: '-',
+    Equal: '=',
+    BracketLeft: '[',
+    BracketRight: ']',
+    Quote: "'",
+    Backslash: '\\',
+    Apostrophe: "'",
+    Semicolon: ';',
+    Comma: ',',
+    Period: '.',
+    Slash: '/',
+};
+exports.KeyboardLayoutData = {
+    'en-US': {
+        shiftMap: SHIFT_MAP,
+        translate({ code, key }) {
+            const translated = TranslateKey[code];
+            if (translated)
+                return translated;
+            if (code.startsWith('Key'))
+                return code.slice(3).toLowerCase();
+            if (code.startsWith('Digit'))
+                return code.slice(5);
+            return key.toLowerCase();
+        },
+    },
 };
 /**
- * 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.
+ * The `keyboardEventToString` function converts a `Key` object to a string that represents the key combination pressed.
+ * It checks individual modifier keys (`ctrlKey`, `altKey`, `shiftKey`, and `metaKey`) and constructs a concatenated
+ * string reflecting these modifiers followed by the translated character key.
+ *
+ * Exceptions include when the `key` is 'Shift', 'Alt', 'Meta', 'Control', or 'Dead' without an `altKey`,
+ * as these are discarded (represented by an empty string). If no modifiers are pressed, it directly returns
+ * the translated character.
+ *
+ * This conversion provides a consistent way to describe key combinations as strings, essential for handling
+ * and processing keyboard shortcuts or sequences in the application.
  */
-function keyboardEventToString(ev, { shiftedKeys }) {
+function keyboardEventToString(ev, { translate }) {
     const key = ev.key;
     if (!key ||
         key === 'Shift' ||
         key === 'Alt' ||
         key === 'Meta' ||
-        key === 'Control')
+        key === 'Control' ||
+        (key === 'Dead' && !ev.altKey))
         return '';
-    const ch = TranslateKey[key] || key.toLowerCase();
+    const ch = translate(ev);
     let result;
     if (ev.ctrlKey)
         result = 'ctrl';
     if (ev.altKey)
         result = result ? result + '+alt' : 'alt';
-    if (ev.shiftKey && !shiftedKeys.includes(ch))
+    if (ev.shiftKey)
         result = result ? result + '+shift' : 'shift';
     if (ev.metaKey)
         result = result ? result + '+meta' : 'meta';
@@ -99,7 +124,8 @@ function handleKeyboard({ element, onKey, delay, layout, capture, }) {
     const locale = navigator.language;
     let sequence = [];
     let lastT = 0;
-    const newLayout = layout || exports.KeyboardLayoutData[locale] || exports.KeyboardLayoutData['en-US'];
+    layout || (layout = exports.KeyboardLayoutData[locale] || exports.KeyboardLayoutData['en-US']);
+    const newLayout = augmentLayout(layout);
     function handler(ev) {
         const k = keyboardEventToString(ev, newLayout);
         let t = Date.now();
@@ -124,6 +150,10 @@ function handleKeyboard({ element, onKey, delay, layout, capture, }) {
     element.addEventListener('keydown', handler, { capture });
     return () => element.removeEventListener('keydown', handler, { capture });
 }
+// Retrieves the default `KeyboardLayout` based on the current user's language settings from `navigator.language`.
+// Falls back to the 'en-US' layout if the user's specific language is not available in `KeyboardLayoutData`.
+// This function helps ensure that the keyboard handling can adapt to the most appropriate layout for the user,
+// facilitating the accurate interpretation of key sequences and modifiers according to locale preferences.
 function getDefaultLayout() {
     return (exports.KeyboardLayoutData[navigator?.language] || exports.KeyboardLayoutData['en-US']);
 }
@@ -134,6 +164,7 @@ function newKey() {
         metaKey: false,
         altKey: false,
         key: '',
+        code: '',
     };
 }
 /**
@@ -145,7 +176,7 @@ function newKey() {
  * 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()) {
+function _parseKey(key, { modKey, shiftMap }) {
     const sequence = [];
     let match;
     let event = newKey();
@@ -162,19 +193,13 @@ function parseKey(key, { modKey, shiftedKeys, shiftMap } = getDefaultLayout()) {
         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;
-                    }
-                }
+            const shifted = shiftMap[ch];
+            if (shifted) {
+                event.key = shifted;
+                event.shiftKey = true;
             }
+            else
+                event.key = ch;
         }
         if (match[2] !== '+') {
             sequence.push(event);
@@ -183,6 +208,15 @@ function parseKey(key, { modKey, shiftedKeys, shiftMap } = getDefaultLayout()) {
     }
     return sequence;
 }
+function augmentLayout(layout) {
+    return {
+        modKey: IS_MAC.test(navigator.platform) ? 'metaKey' : 'ctrlKey',
+        ...layout,
+    };
+}
+function parseKey(key, layout = getDefaultLayout()) {
+    return _parseKey(key, augmentLayout(layout));
+}
 /**
  * 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).
@@ -193,6 +227,7 @@ function parseKey(key, { modKey, shiftedKeys, shiftMap } = getDefaultLayout()) {
  * 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(' ');
+    const newLayout = augmentLayout(layout);
+    const sequence = _parseKey(key, newLayout);
+    return sequence.map(key => keyboardEventToString(key, newLayout)).join(' ');
 }

package/index.min.js

@@ -1 +1 @@
-"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(" ")}
+"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"},TranslateKey={ArrowUp:"up",ArrowDown:"down",ArrowLeft:"left",ArrowRight:"right",Escape:"esc",Space:"space",Backquote:"`",Minus:"-",Equal:"=",BracketLeft:"[",BracketRight:"]",Quote:"'",Backslash:"\\",Apostrophe:"'",Semicolon:";",Comma:",",Period:".",Slash:"/"};function keyboardEventToString(e,{translate:t}){const a=e.key;if(!a||"Shift"===a||"Alt"===a||"Meta"===a||"Control"===a||"Dead"===a&&!e.altKey)return"";const o=t(e);let n;return e.ctrlKey&&(n="ctrl"),e.altKey&&(n=n?n+"+alt":"alt"),e.shiftKey&&(n=n?n+"+shift":"shift"),e.metaKey&&(n=n?n+"+meta":"meta"),n?n+"+"+o:o}function handleKeyboard({element:e,onKey:t,delay:a,layout:o,capture:n}){const r=void 0===a?250:a,s=navigator.language;let i=[],y=0;o||(o=exports.KeyboardLayoutData[s]||exports.KeyboardLayoutData["en-US"]);const l=augmentLayout(o);function u(e){const a=keyboardEventToString(e,l);let o=Date.now();if(!a)return;o-y<r?i.push(a):i=[a];const n=i.slice(0);do{if(!1!==t(n.join(" "),i)){e.stopPropagation(),e.preventDefault(),o=0;break}n.shift()}while(n.length);y=o}return e.addEventListener("keydown",u,{capture:n}),()=>e.removeEventListener("keydown",u,{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:"",code:""}}function _parseKey(e,{modKey:t,shiftMap:a}){const o=[];let n,r=newKey();for(;n=PARSE_KEY.exec(e.toLowerCase());){const e=n[1];if("shift"===e)r.shiftKey=!0;else if("ctrl"===e||"control"===e)r.ctrlKey=!0;else if("alt"===e||"option"===e)r.altKey=!0;else if("meta"===e||"cmd"===e||"command"===e)r.metaKey=!0;else if("mod"===e)r[t]=!0;else{const t=a[e];t?(r.key=t,r.shiftKey=!0):r.key=e}"+"!==n[2]&&(o.push(r),r=newKey())}return o}function augmentLayout(e){return{modKey:IS_MAC.test(navigator.platform)?"metaKey":"ctrlKey",...e}}function parseKey(e,t=getDefaultLayout()){return _parseKey(e,augmentLayout(t))}function normalize(e,t=getDefaultLayout()){const a=augmentLayout(t);return _parseKey(e,a).map((e=>keyboardEventToString(e,a))).join(" ")}exports.KeyboardLayoutData={"en-US":{shiftMap:SHIFT_MAP,translate({code:e,key:t}){const a=TranslateKey[e];return a||(e.startsWith("Key")?e.slice(3).toLowerCase():e.startsWith("Digit")?e.slice(5):t.toLowerCase())}}};

package/mjs/index.d.ts

@@ -4,6 +4,7 @@ interface Key {
     shiftKey: boolean;
     metaKey: boolean;
     key: string;
+    code: string;
 }
 /**
  * The `KeyboardOptions` interface defines the configuration needed to handle keyboard interactions with
@@ -37,10 +38,24 @@ export interface KeyboardOptions {
      */
     capture?: boolean;
 }
+/**
+ * The `KeyboardLayout` interface describes how a keyboard layout should be structured internally.
+ */
 export interface KeyboardLayout {
-    shiftedKeys: string[];
-    shiftMap: Record<string, string>;
-    modKey: 'metaKey' | 'ctrlKey';
+    /**
+     * 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>;
+    /**
+     * Maps the representation of keys when combined with the alt key.
+     */
+    translate(ev: Key): string;
+    /**
+     * 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';
 }
 export declare const KeyboardLayoutData: Record<string, KeyboardLayout>;
 /**
@@ -62,16 +77,7 @@ export declare const KeyboardLayoutData: Record<string, KeyboardLayout>;
  * @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[];
+export declare function parseKey(key: string, layout?: 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).

package/mjs/index.js

@@ -1 +1 @@
-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(" ")}
+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"},TranslateKey={ArrowUp:"up",ArrowDown:"down",ArrowLeft:"left",ArrowRight:"right",Escape:"esc",Space:"space",Backquote:"`",Minus:"-",Equal:"=",BracketLeft:"[",BracketRight:"]",Quote:"'",Backslash:"\\",Apostrophe:"'",Semicolon:";",Comma:",",Period:".",Slash:"/"};export const KeyboardLayoutData={"en-US":{shiftMap:SHIFT_MAP,translate:({code:e,key:t})=>TranslateKey[e]||(e.startsWith("Key")?e.slice(3).toLowerCase():e.startsWith("Digit")?e.slice(5):t.toLowerCase())}};function keyboardEventToString(e,{translate:t}){const a=e.key;if(!a||"Shift"===a||"Alt"===a||"Meta"===a||"Control"===a||"Dead"===a&&!e.altKey)return"";const o=t(e);let n;return e.ctrlKey&&(n="ctrl"),e.altKey&&(n=n?n+"+alt":"alt"),e.shiftKey&&(n=n?n+"+shift":"shift"),e.metaKey&&(n=n?n+"+meta":"meta"),n?n+"+"+o:o}export function handleKeyboard({element:e,onKey:t,delay:a,layout:o,capture:n}){const r=void 0===a?250:a,i=navigator.language;let s=[],y=0;o||(o=KeyboardLayoutData[i]||KeyboardLayoutData["en-US"]);const l=augmentLayout(o);function u(e){const a=keyboardEventToString(e,l);let o=Date.now();if(!a)return;o-y<r?s.push(a):s=[a];const n=s.slice(0);do{if(!1!==t(n.join(" "),s)){e.stopPropagation(),e.preventDefault(),o=0;break}n.shift()}while(n.length);y=o}return e.addEventListener("keydown",u,{capture:n}),()=>e.removeEventListener("keydown",u,{capture:n})}function getDefaultLayout(){return KeyboardLayoutData[navigator?.language]||KeyboardLayoutData["en-US"]}function newKey(){return{ctrlKey:!1,shiftKey:!1,metaKey:!1,altKey:!1,key:"",code:""}}function _parseKey(e,{modKey:t,shiftMap:a}){const o=[];let n,r=newKey();for(;n=PARSE_KEY.exec(e.toLowerCase());){const e=n[1];if("shift"===e)r.shiftKey=!0;else if("ctrl"===e||"control"===e)r.ctrlKey=!0;else if("alt"===e||"option"===e)r.altKey=!0;else if("meta"===e||"cmd"===e||"command"===e)r.metaKey=!0;else if("mod"===e)r[t]=!0;else{const t=a[e];t?(r.key=t,r.shiftKey=!0):r.key=e}"+"!==n[2]&&(o.push(r),r=newKey())}return o}function augmentLayout(e){return{modKey:IS_MAC.test(navigator.platform)?"metaKey":"ctrlKey",...e}}export function parseKey(e,t=getDefaultLayout()){return _parseKey(e,augmentLayout(t))}export function normalize(e,t=getDefaultLayout()){const a=augmentLayout(t);return _parseKey(e,a).map((e=>keyboardEventToString(e,a))).join(" ")}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cxl/keyboard",
-  "version": "0.1.0",
+  "version": "1.0.0",
   "description": "Keyboard Handling Library",
   "license": "UNLICENSED",
   "files": [

package/test.js

@@ -17,29 +17,51 @@ exports.default = (0, spec_1.spec)('keyboard', s => {
             a.equal((0, index_js_1.normalize)('ctrl+shift+x'), 'ctrl+shift+x');
         });
         it.should('parse mod key', a => {
-            a.equal((0, index_js_1.normalize)('mod+x'), 'ctrl+x');
-            a.equal((0, index_js_1.normalize)('x+mod'), 'ctrl+x');
-            a.equal((0, index_js_1.normalize)('MOD+X'), 'ctrl+x');
+            const layout = {
+                ...index_js_1.KeyboardLayoutData['en-US'],
+                modKey: 'ctrlKey',
+            };
+            a.equal((0, index_js_1.normalize)('mod+x', layout), 'ctrl+x');
+            a.equal((0, index_js_1.normalize)('x+mod', layout), 'ctrl+x');
+            a.equal((0, index_js_1.normalize)('MOD+X', layout), 'ctrl+x');
+            layout.modKey = 'metaKey';
+            a.equal((0, index_js_1.normalize)('mod+x', layout), 'meta+x');
+            a.equal((0, index_js_1.normalize)('x+mod', layout), 'meta+x');
+            a.equal((0, index_js_1.normalize)('MOD+X', layout), 'meta+x');
         });
         it.should('normalize shifted keys', a => {
-            a.equal((0, index_js_1.normalize)('shift+5'), '%');
+            a.equal((0, index_js_1.normalize)('%'), 'shift+5');
             a.equal((0, index_js_1.normalize)('shift+A'), 'shift+a');
             a.equal((0, index_js_1.normalize)('shift+y'), 'shift+y');
-            a.equal((0, index_js_1.normalize)('shift+ctrl+5'), 'ctrl+%');
+            a.equal((0, index_js_1.normalize)('shift+ctrl+5'), 'ctrl+shift+5');
+            a.equal((0, index_js_1.normalize)('ctrl+%'), 'ctrl+shift+5');
         });
         it.should('handle non character keys', a => {
-            a.equal((0, index_js_1.normalize)(':'), ':');
+            a.equal((0, index_js_1.normalize)(':'), 'shift+;');
             a.equal((0, index_js_1.normalize)('/'), '/');
             a.equal((0, index_js_1.normalize)('.'), '.');
-            a.equal((0, index_js_1.normalize)('?'), '?');
-            a.equal((0, index_js_1.normalize)('shift+/'), '?');
-            a.equal((0, index_js_1.normalize)('shift+?'), '?');
-            a.equal((0, index_js_1.normalize)('ctrl+:'), 'ctrl+:');
+            a.equal((0, index_js_1.normalize)('?'), 'shift+/');
+            a.equal((0, index_js_1.normalize)('shift+/'), 'shift+/');
+            //a.equal(normalize('shift++'), 'shift+=');
+            a.equal((0, index_js_1.normalize)('shift+?'), 'shift+/');
+            a.equal((0, index_js_1.normalize)('ctrl+:'), 'ctrl+shift+;');
+            a.equal((0, index_js_1.normalize)('ctrl+shift+?'), 'ctrl+shift+/');
+            a.equal((0, index_js_1.normalize)(';'), ';');
         });
         it.should('normalize special keys with modifiers', a => {
             a.equal((0, index_js_1.normalize)('ctrl+alt+del'), 'ctrl+alt+del');
             a.equal((0, index_js_1.normalize)('ctrl+shift+esc'), 'ctrl+shift+esc');
         });
+        it.should('handle case sensitivity', a => {
+            a.equal((0, index_js_1.normalize)('CTRL+A'), 'ctrl+a');
+            a.equal((0, index_js_1.normalize)('Shift+Y'), 'shift+y');
+        });
+        /*it.should('handle complex sequences', a => {
+            a.equal(
+                normalize(' ctrl + shift + x   ctrl+y'),
+                'ctrl+shift+x ctrl+y',
+            );
+        });*/
     });
     s.test('parseKey', it => {
         it.should('correctly parse simple keys without modifiers', a => {
@@ -78,17 +100,51 @@ exports.default = (0, spec_1.spec)('keyboard', s => {
             a.equal(result[1].ctrlKey, true);
         });
         it.should('map mod key to the correct modifier', a => {
-            const defaultLayout = index_js_1.KeyboardLayoutData['en-US'];
-            const result = (0, index_js_1.parseKey)('mod+c');
+            const layout = index_js_1.KeyboardLayoutData['en-US'];
+            const result = (0, index_js_1.parseKey)('mod+c', { ...layout, modKey: 'ctrlKey' });
             a.equal(result.length, 1);
             a.equal(result[0].key, 'c');
-            a.equal(result[0][defaultLayout.modKey], true);
+            a.equal(result[0].ctrlKey, true);
+            const result2 = (0, index_js_1.parseKey)('mod+c', { ...layout, modKey: 'metaKey' });
+            a.equal(result2.length, 1);
+            a.equal(result2[0].key, 'c');
+            a.equal(result2[0].metaKey, true);
         });
         it.should('handle shifted characters correctly', a => {
             const result = (0, index_js_1.parseKey)('shift+1');
             a.equal(result.length, 1);
-            a.equal(result[0].key, '!'); // assuming shift+1 maps to '@' in shiftMap
-            a.equal(result[0].shiftKey, false);
+            a.equal(result[0].key, '1'); // assuming shift+1 maps to '@' in shiftMap
+            a.equal(result[0].shiftKey, true);
+        });
+        it.should('handle keys with special characters', a => {
+            const result = (0, index_js_1.parseKey)('ctrl+shift+1');
+            a.equal(result.length, 1);
+            a.equal(result[0].key, '1');
+            a.equal(result[0].ctrlKey, true);
+            a.equal(result[0].shiftKey, true);
+        });
+        it.should('handle unsupported modifier combinations', a => {
+            const result = (0, index_js_1.parseKey)('ctrl+alt+meta+z');
+            a.equal(result.length, 1);
+            a.equal(result[0].key, 'z');
+            a.equal(result[0].ctrlKey, true);
+            a.equal(result[0].altKey, true);
+            a.equal(result[0].metaKey, true);
+        });
+        it.should('correctly parse special character keys', a => {
+            const result = (0, index_js_1.parseKey)('ctrl+alt+!');
+            a.equal(result.length, 1);
+            a.equal(result[0].key, '1');
+            a.equal(result[0].ctrlKey, true);
+            a.equal(result[0].altKey, true);
+            a.equal(result[0].shiftKey, true);
+        });
+        it.should('handle unsupported character sequences', a => {
+            const result = (0, index_js_1.parseKey)('ctrl+alt+ctrl+z');
+            a.equal(result.length, 1);
+            a.equal(result[0].key, 'z');
+            a.equal(result[0].ctrlKey, true);
+            a.equal(result[0].altKey, true);
         });
     });
     s.test('handleKeyboard', it => {
@@ -147,5 +203,37 @@ exports.default = (0, spec_1.spec)('keyboard', s => {
             dispose();
             a.equal(off.lastEvent?.called, 1);
         });
+        it.should('handle rapid key presses correctly', (a) => {
+            const elementMock = a.element('div');
+            const on = a.spyFn(elementMock, 'addEventListener');
+            const onKeyMock = (0, spec_1.mockFn)(key => key === 'x y');
+            const dispose = (0, index_js_1.handleKeyboard)({
+                element: elementMock,
+                onKey: onKeyMock,
+                delay: 100,
+                layout: undefined,
+                capture: false,
+            });
+            const eventX = new KeyboardEvent('keydown', { key: 'x' });
+            const eventY = new KeyboardEvent('keydown', { key: 'y' });
+            a.assert(typeof on.lastEvent?.arguments[1] === 'function');
+            on.lastEvent?.arguments[1](eventX);
+            on.lastEvent?.arguments[1](eventY);
+            a.equal(onKeyMock.lastArguments?.[0], 'x y');
+            dispose();
+        });
+        it.should('verify event listener is removed on dispose', (a) => {
+            const elementMock = a.element('div');
+            const off = a.spyFn(elementMock, 'removeEventListener');
+            const dispose = (0, index_js_1.handleKeyboard)({
+                element: elementMock,
+                onKey: (0, spec_1.mockFn)(() => true),
+                delay: 100,
+                layout: undefined,
+                capture: false,
+            });
+            dispose();
+            a.equal(off.lastEvent?.called, 1);
+        });
     });
 });