{"id":17099553,"url":"https://github.com/jexordexan/keypound","last_synced_at":"2025-03-23T18:21:39.363Z","repository":{"id":84313497,"uuid":"100135140","full_name":"Jexordexan/keypound","owner":"Jexordexan","description":"A scoped key binding library using ES6","archived":false,"fork":false,"pushed_at":"2018-06-15T22:41:43.000Z","size":156,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-03-12T15:03:35.716Z","etag":null,"topics":["bindings","es6","keyboard","keymaster","keys","scope","shortcut"],"latest_commit_sha":null,"homepage":"https://jexordexan.github.io/keypound/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Jexordexan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-08-12T20:03:31.000Z","updated_at":"2021-03-16T16:45:01.000Z","dependencies_parsed_at":"2023-03-12T18:00:15.579Z","dependency_job_id":null,"html_url":"https://github.com/Jexordexan/keypound","commit_stats":{"total_commits":30,"total_committers":1,"mean_commits":30.0,"dds":0.0,"last_synced_commit":"500c3be69b423560f178df80824aaf3d550d0aad"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jexordexan%2Fkeypound","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jexordexan%2Fkeypound/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jexordexan%2Fkeypound/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jexordexan%2Fkeypound/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Jexordexan","download_url":"https://codeload.github.com/Jexordexan/keypound/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245145459,"owners_count":20568125,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bindings","es6","keyboard","keymaster","keys","scope","shortcut"],"created_at":"2024-10-14T15:10:48.003Z","updated_at":"2025-03-23T18:21:39.327Z","avatar_url":"https://github.com/Jexordexan.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Keypound.js\n\n### Scoped key binding library with context stacking and ES6 out of the box. Based on [Keymaster.js](https://github.com/madrobby/keymaster)\n[![Build Status](https://travis-ci.org/Jexordexan/keypound.svg?branch=master)](https://travis-ci.org/Jexordexan/keypound)\n\nThis is a dependency-free library aimed at making scoped key bindings in large apps a breeze.\n\nSometimes in large applications, you need the same shortcut to perform different tasks in different places. For instance, you might need the `up` and `down` arrows to move around different lists depending on where your focus was last.\n\nOften we resort to using `event.stopPropagation()` and `event.preventDefault()`, to prevent the keys from bubbling up, but we should really be creating a context stack and telling our code which context we are in, and which context will next receive events that haven't been handled.\n\n## Getting Started\n\n### Installation\n* Using `npm`:\n```bash\nnpm install keypound\n```\n* Using `yarn`:\n```bash\nyarn add keypound\n```\n\n### Creating an instance\nTo get started with keypound, you'll need to create a master instance:\n\n```javascript\n// master.js\nimport Keypound from 'keypound'\n\nconst master = new Keypound(options)\nexport default master\n```\n\n### Registering a context\nAfter creating a master instance you can import it into any module and enter your first context\n\n```javascript\n// my-module.js\n\nimport master from './master'\n\nconst context = master.enter('module-context')\n```\n### Binding to a shortcut\nOnce you've registered a context, you can start binding some shortcuts!\n\n```javascript\ncontext.on('down, tab', () =\u003e this.moveDown())\ncontext.on('up, shift + tab', () =\u003e this.moveUp())\n```\nThis will cause `moveDown` to fire anytime the down arrow or tab key is pressed.\nLikewise, `moveUp` will fire anytime the up arrow or shift-tab is pressed.\n\n### Multiple contexts\nAnytime the user enters a new context (open a modal or dialog) you tell the master instance to enter a new context and add your new bindings.\n\n```javascript\nconst modalContext = master.enter('modal-context')\n```\n\nEvery new context stacks on top of the contexts that have already been entered. All bindings are given to the context at the top of the stack (the most recent) and then fall down the stack until they are handled.\n\nOnce a shortcut is handled, it will stop cascading down the stack.\n\n### Re-entering contexts\nIf a user goes back to a previous context without exiting the current one (maybe they clicked on a different area of the app), you can re-enter that context with all the same bindings, but now it is at the top of the stack.\n\nYou do this by calling `enter()` with the same context name.\n\n```javascript\nmaster.enter('previous-context')\n```\nAfterwards, all bindings will take top priority once again.\n\n### Exiting contexts\nWhen a modal closes, you will want to remove that context from the stack entirely. There are two ways to do this.\n\n1. Exit the context from the master:\n```javascript\n  master.exit('modal-context')\n```\n2. Exit the context using the context reference:\n```javascript\n  modalContext.exit()\n```\n\n### Pausing and playing contexts\nSometimes you will need to keep a contexts spot in the stack but stop your shortcut handlers from firing.\n\nThankfully, you can call `.pause()` on your context to pause any handling, and then call `.play()` when you are ready to start responding to shortcuts again.\n\nNote: Since your handlers will not be firing, any duplicate shortcuts down the stack will still fire. To prevent this, either have your handler decide whether or not to do anything, or use the `block: true` option when creating your context for the first time.\n\n# API\nBelow are the interfaces for each object type in the library\n\n## Keypound instance\n\nYou should really only have one of these in your app. If you need more, make sure you are careful about which is responsible for what.\n\n### Constructor\n```javascript\nconst master = new Keypound(options);\n```\n\n### Options\nWhen creating a new Keypound, you can provide the following options\n```javascript\n{\n  keyEvent: 'keydown', // the event type to listen for\n  createRoot: true, // create a root context for the app\n  defaultFilter: (event, binding) =\u003e boolean, // a global function to filter events, can be overridden by each context\n}\n```\n### Methods\n* `enter(contextName, options)`\n  * returns `Context` instance used for shortcut bindings.\n* `exit(contextName)`\n  * returns `Context` instance if found, `null` if there was no match.\n* `getStackIndex(contextName)`\n  * returns `number` of where the context lies in the stack.\n\n### Context options\nWhen creating a new context, you can supply options for how shortcuts are handled:\n\n* `block: boolean`: if true, stops all shortcuts at this context, even if they have no handler.\n* `filter: (event, binding) =\u003e boolean`: Local filter for events in this context, defaults to the defualtFilter set in the master.\n\n## Context instance\n\n### Methods\n* `on(shortcut, handler, options)`\n  * `shortcut`: See Creating a shortcut\n  * `handler`: See handler\n  * `options`: any of the following\n    * `prevent: boolean`: call `event.preventDefault` if set to `true`\n* `off(shortcut)`: removes a shortcuts handler from the context.\n* `exit()`: removes the context from the master stack.\n* `pause()`: temporarily stop handlers from firing and allow shortcuts to cascade the stack.\n* `play()`: resume handling of shortcuts.\n\n### Creating a shortcut\nShortcuts are written in as `[modifiers] + [key]` combos, separated by commas.\nEverything below is a valid shortcut:\n\n* `d, control + m`\n* `alt + C`\n* `shift + p`\n* `⇧ + ⌘ + left`\n* `space, ctrl + space, alt + tab`\n* `ctrl + alt + delete`\n\n### Supported keys\nKeypound understands the following modifiers:\n`⇧`, `shift`, `option`, `⌥`, `alt`, `ctrl`, `control`, `command`, and `⌘`.\n\nThe following special keys can be used for shortcuts:\n`backspace`, `tab`, `clear`, `enter`, `return`, `esc`, `escape`, `space`,\n`up`, `down`, `left`, `right`, `home`, `end`, `pageup`, `pagedown`, `del`, `delete`\nand `f1` through `f19`.\n\n### Handler\nEach handler is given two arguments, `event` and `binding`.\n* `event`: The native `keydown` event that matched the shortcut\n* `binding`: The information associated with the binding\n  * `key`: a `number` representing the keyCode that triggered the event\n  * `mods`: a map of `KeyEvent` modifiers and a `boolean` indicating if they are required for the shortcut.\n  * `options`: any options passed to the initial binding\n  * `handler`: the callback itself\n\n## Contributing\n\nTo contribute, please fork Keypound.js, add your patch and tests for it (in the `test/specs` folder), run `npm test`, and submit a pull request.\n\n## TODO\n- More docs\n- More examples\n- Better edge-case testing\n- Filtering\n- Aliases\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjexordexan%2Fkeypound","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjexordexan%2Fkeypound","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjexordexan%2Fkeypound/lists"}