@cxl/keyboard 1.0.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: [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)
+-   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,5 +1,4 @@
-/// <amd-module name="@cxl/keyboard" />
-interface Key {
+interface __dts_0_Key {
     ctrlKey: boolean;
     altKey: boolean;
     shiftKey: boolean;
@@ -11,7 +10,7 @@ interface Key {
  * 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.
@@ -42,23 +41,38 @@ export interface KeyboardOptions {
 /**
  * The `KeyboardLayout` interface describes how a keyboard layout should be structured internally.
  */
-export interface KeyboardLayout {
+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>;
-    /**
-     * Maps the representation of keys when combined with the alt key.
-     */
-    translate(ev: Key): string;
+    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
@@ -77,16 +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;
-export declare function parseKey(key: string, layout?: 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": "1.0.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,92 +0,0 @@
-/// <amd-module name="@cxl/keyboard" />
-interface 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 {
-    /**
-     * 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;
-}
-/**
- * The `KeyboardLayout` interface describes how a keyboard layout should be structured internally.
- */
-export 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>;
-    /**
-     * 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>;
-/**
- * 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;
-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).
- * 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 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.js

@@ -1,233 +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',
-};
-const 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: '/',
-};
-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();
-        },
-    },
-};
-/**
- * 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, { translate }) {
-    const key = ev.key;
-    if (!key ||
-        key === 'Shift' ||
-        key === 'Alt' ||
-        key === 'Meta' ||
-        key === 'Control' ||
-        (key === 'Dead' && !ev.altKey))
-        return '';
-    const ch = translate(ev);
-    let result;
-    if (ev.ctrlKey)
-        result = 'ctrl';
-    if (ev.altKey)
-        result = result ? result + '+alt' : 'alt';
-    if (ev.shiftKey)
-        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;
-    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();
-        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 });
-}
-// 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']);
-}
-function newKey() {
-    return {
-        ctrlKey: false,
-        shiftKey: false,
-        metaKey: false,
-        altKey: false,
-        key: '',
-        code: '',
-    };
-}
-/**
- * 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, shiftMap }) {
-    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 {
-            const shifted = shiftMap[ch];
-            if (shifted) {
-                event.key = shifted;
-                event.shiftKey = true;
-            }
-            else
-                event.key = ch;
-        }
-        if (match[2] !== '+') {
-            sequence.push(event);
-            event = newKey();
-        }
-    }
-    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).
- * 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 newLayout = augmentLayout(layout);
-    const sequence = _parseKey(key, newLayout);
-    return sequence.map(key => keyboardEventToString(key, newLayout)).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"},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

@@ -1,91 +0,0 @@
-interface 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 {
-    /**
-     * 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;
-}
-/**
- * The `KeyboardLayout` interface describes how a keyboard layout should be structured internally.
- */
-export 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>;
-    /**
-     * 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>;
-/**
- * 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;
-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).
- * 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"},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/test.d.ts

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