my-hotkeys 0.0.1

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2024 Itai Tenenbaum
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE

package/README.md

@@ -0,0 +1,271 @@
+![Build Status](https://github.com/taitulism/hotkey/actions/workflows/node-ci.yml/badge.svg)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+
+my-hotkeys
+==========
+Keyboard shorcuts.
+
+Install
+-------
+```sh
+$ npm install my-hotkeys
+```
+
+Basic Usage
+-----------
+
+```js
+import {hotkeys} from 'my-hotkeys`;
+```
+```js
+const hk = hotkeys();
+
+// bind one:
+hk.bind('a', doSomething);
+
+// or multiple:
+hk.bind({
+	'a': doSomething,
+	'ctrl-a': doSomethingElse,
+	'ctrl-alt-3': doAnotherThing,
+});
+
+hk.unbind('a'); // removes a hotkey
+
+hk.unmount(); // removes the instance's event listener
+hk.mount(); // adds the instance's event listener
+
+hk.destruct(); // removes all hotkeys and the event listener
+```
+
+Index
+-----
+* [Creating an instance](#creating-an-instance)
+* [Binding / Unbinding Keys](#binding--unbinding-keys)
+* [Mount/Unmount the event listener](#mountunmount-the-event-listener)
+* [Hotkeys Strings](#hotkeys-strings)
+* [Destruction](#destruction)
+
+
+## Creating an instance
+There are two ways to get a `Hotkeys` instance:
+1. By calling `hotkeys` creator function (lowercased "h")
+2. By the `Hotkeys` constructor (uppercased "H")
+
+```js
+import {hotkeys} from 'my-hotkeys`;
+
+const hk = hotkeys();
+```
+or:
+```js
+import {Hotkeys} from 'my-hotkeys`;
+
+const hk = new Hotkeys();
+```
+
+The difference between them is that `hotkeys` creator function also mounts the event listener on creation and doesn't have the ignore function argument (yet). When using the constructor you need to call `.mount()` manually (see [`.mount()`](#mount) below) and you can also set an ignore function.
+
+Both accept an optional argument as the context element (`HTMLElement | Document`). This would be the element that listens to the keyboard events. Defaults to `document`.
+```js
+const hk = hotkeys(elmOrDoc);
+// => internally: elmOrDoc.addEventListener()...
+```
+
+> **⚠ Non-browser environments:** You might need to pass in the runtime's `document` object as the constructor argument.
+
+### Ignore Function
+By default, the `Hotkeys` instance ignores key presses if the `event.target` element is:
+* `<input>`
+* `<select>`
+* `<textarea>`
+* `[contenteditable="true"]`
+
+You can pass the constructor your own ignore function as the second argument. This function gets called on every `keydown` event with the `event` object. Return a truthy value to ignore the key press or a falsy value for continue executing the hotkey.
+
+```js
+const hk = new Hotkeys(document, (ev: KeyboardEvent) =>
+	ev.target === mySpecialElement);
+```
+
+
+## Binding / Unbinding Keys
+
+### .bind()
+* `.bind(hotkey, callback)` - hotkey string, callback
+* `.bind({hotkey: callback})` - an object of `{hotkey:callback}`
+
+Adds keyboard shortcuts. Does **not** add an event listener.
+
+```js
+hk.bind('a', doSomething);
+hk.bind('b', doSomethingElse);
+
+// or:
+
+hk.bind({
+  'a': doSomething,
+  'b': doSomethingElse,
+});
+```
+
+Each hotkey can be bound once:
+```js
+hk.bind('a', doSomething);
+hk.bind('a', doSomethingElse); // -> throws Error
+```
+
+Callback functions are called with the keyboard event as their only argument:
+```js
+function doSomething (ev: KeyboardEvent) {...}
+```
+
+### .unbind()
+* `.unbind(hotkey)` - hotkey string
+* `.unbind([hotkey...])` - an array of hotkey strings
+
+Removes keyboard shortcuts. Does **not** remove the event listener.
+
+```js
+hk.unbind('a');
+hk.unbind('b');
+
+// or:
+
+hk.unbind(['a', 'b']);
+```
+
+### .unbindAll()
+Unbinds all hotkeys. Does **not** remove the event listener.
+
+```js
+hk.bind('A', doSomething);
+
+hk.unbindAll();
+
+hk.bind('B', doSomethingElse);
+```
+
+## Mount/Unmount the event listener
+Each `Hotkeys` instance can only have one `keydown` keyboard event listener. The event listener is attached to the context element passed in construction. Defaults to `document`.
+
+* `.mount()` - Attaches the event listener to the context element.
+* `.unmount()` - Dettaches the event listener from the context element.
+
+```js
+const hk = new Hotkeys(myMenu);
+
+hk.bind('Q', doSomething);
+
+// user presses "Q" but nothing happens
+
+hk.mount(); // => internally: myMenu.addEventListener()...
+
+// user presses "Q" and `doSomething` is called
+
+hk.unmount();
+
+// user presses "Q" but nothing happens
+```
+
+Using the creator function mounts the event listener for you:
+```js
+const hk = hotkeys(); //  <---- also mounts
+
+hk.bind('Q', doSomething);
+
+// user presses "Q" and `doSomething` is called
+
+hk.unmount();
+
+// user presses "Q" but nothing happens
+```
+
+
+## Hotkeys Strings
+Currently, `my-hotkeys` supports the classic/standard/canonical way of binding keys: there are modifier keys (`Control`, `Alt`, `Shift`, `Meta`) and all the rest ("regular" keys).
+
+A hotkey string can be a single regular key, with or without modifiers.
+
+Modifier keys cannot be hotkeys without a regular key, i.e. `.bind('ctrl-alt')` will not work.
+
+You can also bind by `event.code` or by symbols like `?`.
+
+### Delimiter
+The delimiter character is `-`, not configurable (yet?). If you want to bind `-` as a hotkey - use its alias: "Minus" (e.g. `'ctrl-minus'`).
+
+### Examples:
+```js
+hk.bind({
+	'a': doSomething,
+	'ctrl-a': doSomething,
+	'ctrl-alt-a': doSomething,
+	'?': showHelp, // by symbol that may require shift
+})
+```
+
+Hotkeys are case insensitive:
+```js
+hk.bind('ctrl-a', doSomething)
+// Same as:
+hk.bind('Ctrl-A', doSomething)
+```
+
+But not when you bind by a key id (`event.code`): 
+```js
+// event.code is case sensitive
+hk.bind('Numpad8', doSomething)
+```
+
+### Aliases
+Some keys have aliases for better readability or just for convenience.
+
+> Aliases are case insensitive.
+
+### Modifier Aliases:
+| Key     | Alias   |
+|---------|---------|
+| Control | Ctrl    |
+| Meta    | Cmd     |
+| Meta    | Command |
+
+### Regular Key Aliases:
+| Key        | Alias        |
+|------------|--------------|
+| ArrowUp    | Up           |
+| ArrowDown  | Down         |
+| ArrowLeft  | Left         |
+| ArrowRight | Right        |
+|            | Space        |
+| +          | Plus         |
+| -          | Minus        |
+| =          | Equal        |
+| _          | Underscore   |
+| '          | Quote        |
+| '          | Singlequote  |
+| "          | Quotes       |
+| "          | Doublequotes |
+| `          | Backquote    |
+| ~          | Tilde        |
+| \\         | Backslash    |
+| Insert     | Ins          |
+| Delete     | Del          |
+| Escape     | Esc          |
+| PageUp     | PgUp         |
+| PageDown   | PgDn         |
+
+
+## Destruction
+Call `.destruct()` when its context element leaves the DOM. It will remove all of the instance's hotkeys and event listeners by calling `.unmount()` and `.unbindAll()`. 
+
+```js
+const hk = new Hotkeys();
+
+hk.bind('A', doSomething);
+hk.mount();
+
+// ...
+
+hk.destruct();
+```

package/dist/browser/hotkeys.min.js

@@ -0,0 +1,2 @@
+/*! my-hotkeys v0.0.1 | MIT License | © Itai Tenenbaum 2024 | git+https://github.com/taitulism/my-hotkeys */
+var hotkeys=function(t){"use strict";function e(t,e){const n=e-t.length;return n>0?t+" ".repeat(n):t}const n={"[":"BracketLeft","]":"BracketRight",";":"Semicolon","'":"Quote","\\":"Backslash",",":"Comma","`":"Backquote","=":"Equal","-":"Minus",".":"Period","/":"Slash"},i={up:"ArrowUp",down:"ArrowDown",left:"ArrowLeft",right:"ArrowRight",space:" ",plus:"+",minus:"-",equal:"=",underscore:"_",quote:"'",singlequote:"'",quotes:'"',doublequotes:'"',backquote:"`",tilde:"~",backslash:"\\",ins:"Insert",del:"Delete",esc:"Escape",pgup:"PageUp",pgdn:"PageDown"},o="Control",s="Meta",r={Control:1,Alt:2,Shift:4,Meta:8},h={control:o,ctrl:o,alt:"Alt",shift:"Shift",meta:s,cmd:s,command:s},c={0:"_",1:"C",2:"A",3:"CA",4:"S",5:"CS",6:"AS",7:"CAS",8:"M",9:"CM",10:"AM",11:"CAM",12:"SM",13:"CSM",14:"ASM",15:"CASM"},u=t=>1===t.length&&/[a-zA-Z]/.test(t),f=t=>t in h;const a=t=>{const e=t.toLowerCase();return u(t)?e:(t=>t in i)(e)?i[e]:t};function d(t){if("-"===t)return{targetKey:"-",unifiedModifier:"_"};!function(t){if(!t)throw new Error("Invalid Hotkey: Empty String");if(t.startsWith("-")||t.endsWith("-")||/--/.test(t))throw new Error(`Invalid Hotkey: "${t}"`)}(t);const e=t.split("-"),n=a(e.pop()),i=function(t){if(0===t.length)return"_";const e=function(){const t={};return function(e){return!(e in t)&&(t[e]=void 0,!0)}}();let n=0;for(let i=0;i<t.length;i++){const o=t[i].toLowerCase();if(!f(o))throw new Error(`Unknown Modifier: "${o}"`);{const t=h[o],i=r[t];e(i)&&(n+=i)}}return c[n]}(e);return{targetKey:n,unifiedModifier:i,withShift:i.includes("S")}}const l=["INPUT","TEXTAREA","SELECT"],y=t=>{const{target:e}=t;if(!(e&&e instanceof HTMLElement))return!1;return l.includes(e.tagName)||e.isContentEditable};class k{constructor(t=document,i=y){this.ctxElm=t,this.ignoreFn=i,this.hotkeys=new Map,this.debugMode=!1,this.addHotkey=(t,e,i)=>{const{targetKey:o,unifiedModifier:s,withShift:r}=t;if(this.hotkeys.has(o)){const t=this.hotkeys.get(o);if(t[s])throw new Error(`Duplicated hotkey: "${i}"`);t[s]=e}else this.hotkeys.set(o,{[s]:e});if(r&&o in n){const t=n[o];this.addHotkey({targetKey:t,unifiedModifier:s},e,i)}},this.removeHotkey=t=>{const{targetKey:e,unifiedModifier:i,withShift:o}=t;if(!this.hotkeys.has(e))throw new Error("No Such Hotkey");{const t=this.hotkeys.get(e);if(t[i]&&(delete t[i],0===Object.keys(t).length&&this.hotkeys.delete(e)),o&&e in n){const t=n[e];this.removeHotkey({targetKey:t,unifiedModifier:i})}}},this.keydownHandler=t=>{this.debugMode&&function(t){const{type:n,code:i,key:o,ctrlKey:s,altKey:r,shiftKey:h,metaKey:c}=t,u=s||r||h||c,f=("keydown"===n?"🔻":"🔼")+e(o,7),a=`| id:${i} `,d=e((u?"[ ":"")+`${s?"ctrl ":""}${r?"alt ":""}${h?"shift ":""}${c?"meta ":""}`+(u?"]":""),21);console.log(f,d,a)}(t);const{key:n}=t;if(n in r)return;if(this.ignoreFn?.(t))return;const i=function(t,e){const{key:n,code:i,shiftKey:o}=t,s=u(n)?n.toLowerCase():n;if(e.has(s))return e.get(s);if(e.has(i))return e.get(i);if(o&&(t=>(t=>t.startsWith("Dig"))(t)||(t=>t.startsWith("Num")&&/\d$/.test(t))(t))(i)){const t=(t=>t[t.length-1])(i);if(e.has(t))return e.get(t)}}(t,this.hotkeys);if(!i)return;const o=function(t){const{ctrlKey:e,altKey:n,shiftKey:i,metaKey:o}=t;let s=0;return e&&(s+=r.Control),n&&(s+=r.Alt),i&&(s+=r.Shift),o&&(s+=r.Meta),c[s]}(t);if(i[o])i[o]?.(t);else if(i===this.hotkeys.get(n)&&(t=>t.shiftKey&&(t=>1===t.key.length)(t)&&!t.code.startsWith("Num"))(t)){const e=i[o.replace("S","")||"_"];e?.(t)}}}bind(t,e){if("string"==typeof t){const n=d(t);this.addHotkey(n,e,t)}else{const e=Object.entries(t);for(const[t,n]of e)this.bind(t,n)}return this}unbind(t){if("string"==typeof t){const e=d(t);this.removeHotkey(e)}else t.forEach((t=>this.unbind(t)));return this}unbindAll(){return this.hotkeys.clear(),this}mount(){return this.ctxElm.addEventListener("keydown",this.keydownHandler),this}unmount(){return this.ctxElm.removeEventListener("keydown",this.keydownHandler),this}destruct(){return this.unmount(),this.unbindAll(),this}}return t.Hotkeys=k,t.ModifierAliases=h,t.Modifiers=r,t.UnifiedModifiersMap=c,t.hotkeys=function(t=document){return new k(t).mount()},t}({});

package/dist/esm/hotkeys.esm.d.ts

@@ -0,0 +1,111 @@
+declare const SymbolIDs: {
+    readonly '[': "BracketLeft";
+    readonly ']': "BracketRight";
+    readonly ';': "Semicolon";
+    readonly '\'': "Quote";
+    readonly '\\': "Backslash";
+    readonly ',': "Comma";
+    readonly '`': "Backquote";
+    readonly '=': "Equal";
+    readonly '-': "Minus";
+    readonly '.': "Period";
+    readonly '/': "Slash";
+};
+type ISymbol = keyof typeof SymbolIDs;
+type SymbolKeyID = typeof SymbolIDs[ISymbol];
+declare const Aliases: {
+    readonly up: "ArrowUp";
+    readonly down: "ArrowDown";
+    readonly left: "ArrowLeft";
+    readonly right: "ArrowRight";
+    readonly space: " ";
+    readonly plus: "+";
+    readonly minus: "-";
+    readonly equal: "=";
+    readonly underscore: "_";
+    readonly quote: "'";
+    readonly singlequote: "'";
+    readonly quotes: "\"";
+    readonly doublequotes: "\"";
+    readonly backquote: "`";
+    readonly tilde: "~";
+    readonly backslash: "\\";
+    readonly ins: "Insert";
+    readonly del: "Delete";
+    readonly esc: "Escape";
+    readonly pgup: "PageUp";
+    readonly pgdn: "PageDown";
+};
+type Alias = keyof typeof Aliases;
+type AliasValue = typeof Aliases[Alias];
+
+type ContextElement = HTMLElement | Document;
+type KeyHandler = (ev: KeyboardEvent) => void;
+type IgnoreFn = (ev: KeyboardEvent) => boolean;
+declare const Modifiers: {
+    readonly Control: 1;
+    readonly Alt: 2;
+    readonly Shift: 4;
+    readonly Meta: 8;
+};
+type Modifier = keyof typeof Modifiers;
+declare const ModifierAliases: {
+    readonly control: "Control";
+    readonly ctrl: "Control";
+    readonly alt: "Alt";
+    readonly shift: "Shift";
+    readonly meta: "Meta";
+    readonly cmd: "Meta";
+    readonly command: "Meta";
+};
+type ModifierAlias = keyof typeof ModifierAliases;
+declare const UnifiedModifiersMap: {
+    readonly 0: "_";
+    readonly 1: "C";
+    readonly 2: "A";
+    readonly 3: "CA";
+    readonly 4: "S";
+    readonly 5: "CS";
+    readonly 6: "AS";
+    readonly 7: "CAS";
+    readonly 8: "M";
+    readonly 9: "CM";
+    readonly 10: "AM";
+    readonly 11: "CAM";
+    readonly 12: "SM";
+    readonly 13: "CSM";
+    readonly 14: "ASM";
+    readonly 15: "CASM";
+};
+type UniModSum = keyof typeof UnifiedModifiersMap;
+type UnifiedModifier = typeof UnifiedModifiersMap[UniModSum];
+type CombinationHandlers = {
+    [K in UnifiedModifier]?: KeyHandler;
+};
+type ParsedTargetKey = AliasValue | SymbolKeyID | string;
+type ParsedHotKey = {
+    targetKey: ParsedTargetKey;
+    unifiedModifier: UnifiedModifier;
+    withShift?: boolean;
+};
+
+declare function hotkeys(ctxElm?: ContextElement): Hotkeys;
+declare class Hotkeys {
+    ctxElm: ContextElement;
+    private ignoreFn;
+    hotkeys: Map<string, CombinationHandlers>;
+    debugMode: boolean;
+    constructor(ctxElm?: ContextElement, ignoreFn?: IgnoreFn);
+    private addHotkey;
+    private removeHotkey;
+    bind(hotkey: string, handlerFn: KeyHandler): Hotkeys;
+    bind(hotkey: Record<string, KeyHandler>): Hotkeys;
+    unbind(hotkey: string | Array<string>): this;
+    unbindAll(): this;
+    private keydownHandler;
+    mount(): this;
+    unmount(): this;
+    destruct(): this;
+}
+
+export { type CombinationHandlers, type ContextElement, Hotkeys, type IgnoreFn, type KeyHandler, type Modifier, type ModifierAlias, ModifierAliases, Modifiers, type ParsedHotKey, type ParsedTargetKey, type UniModSum, type UnifiedModifier, UnifiedModifiersMap, hotkeys };