{"_id":"@amarajs/plugin-events","_rev":"3-8423f4ead0a32b3173bea68ac88d8ed0","name":"@amarajs/plugin-events","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@amarajs/plugin-events","amdName":"AmaraEvents","version":"0.1.0","description":"Provides custom DOM-based events for AmaraJS web applications and middleware.","jsnext:main":"src/index.js","main":"dist/amara-plugin-events.js","umd:main":"dist/amara-plugin-events.umd.js","scripts":{"bump":"standard-version","testonly":"mocha --compilers js:babel-register test/**/*.js","lint":"eslint src test","test":"flow && npm run lint && npm run testonly","build":"npm-run-all clean -p rollup:* -p minify:* -s size","clean":"rimraf dist && mkdirp dist","rollup:cjs":"rollup -c rollup.config.js -f cjs -n AmaraEvents src/index.js -o dist/amara-plugin-events.js","rollup:umd":"rollup -c rollup.config.js -f umd -n AmaraEvents src/index.js -o dist/amara-plugin-events.umd.js","minify:cjs":"uglifyjs dist/amara-plugin-events.js -cm toplevel -o dist/amara-plugin-events.min.js -p relative --source-map dist/amara-plugin-events.min.js.map","minify:umd":"uglifyjs dist/amara-plugin-events.umd.js -cm -o dist/amara-plugin-events.umd.min.js -p relative --source-map dist/amara-plugin-events.umd.min.js.map","size":"strip-json-comments --no-whitespace dist/amara-plugin-events.min.js | gzip-size | pretty-bytes","release":"npm run build -s && npm run bump && git push --follow-tags origin master && npm publish"},"keywords":["amara","amarajs","core"],"authors":["Dan Barnes <amarajs.framework@gmail.com>"],"repository":{"type":"git","url":"git+https://github.com/amarajs/plugin-events.git"},"license":"MIT","files":["src","dist"],"eslintConfig":{"parser":"babel-eslint","extends":"eslint:recommended","env":{"browser":true,"mocha":true,"node":true,"es6":true},"globals":{"expect":true},"rules":{"no-cond-assign":0}},"devDependencies":{"babel-core":"^6.9.1","babel-eslint":"^7.1.1","babel-plugin-transform-flow-strip-types":"^6.21.0","babel-preset-es2015":"^6.9.0","babel-preset-stage-0":"^6.5.0","babel-register":"^6.9.0","chai":"^3.5.0","documentation":"^4.0.0-beta4","eslint":"^3.13.1","flow-bin":"^0.38.0","gzip-size-cli":"^1.0.0","jsdom":"^11.6.2","mkdirp":"^0.5.1","mocha":"^3.2.0","npm-run-all":"^2.1.1","pretty-bytes-cli":"^2.0.0","rimraf":"^2.5.2","rollup":"^0.41.4","rollup-plugin-buble":"^0.15.0","rollup-plugin-flow":"^1.1.1","sinon":"^1.17.4","sinon-chai":"^2.8.0","standard-version":"^4.0.0","strip-json-comments-cli":"^1.0.1","uglify-js":"^2.6.2"},"gitHead":"1f077f4e69a8dcd90e51299fcd786122e6a99c3f","bugs":{"url":"https://github.com/amarajs/plugin-events/issues"},"homepage":"https://github.com/amarajs/plugin-events#readme","_id":"@amarajs/plugin-events@0.1.0","_npmVersion":"5.6.0","_nodeVersion":"8.9.4","_npmUser":{"name":"amarajs-dan","email":"amarajs.framework@gmail.com"},"dist":{"integrity":"sha512-whHKfA64cyX6bxlSw0v6XvRVZdHQGLwhY68YIcL9O/7yeUOR6d2QzIJmLVSGRCwZ68gwB6AkDRvjrQMStntaRw==","shasum":"19618660a19e9f7657f934d8a09b7bc4a7eddccb","tarball":"https://registry.npmjs.org/@amarajs/plugin-events/-/plugin-events-0.1.0.tgz","fileCount":10,"unpackedSize":53780,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEQCIFm1C7t5jfOIVTlBsmIKYfW+e07FS2ubyygVsn4gOnBfAiB8FoT0YzMzbxvgrqmMbOBt8NzcGDEvuMX3BX445U94fg=="}]},"maintainers":[{"name":"amarajs-dan","email":"amarajs.framework@gmail.com"}],"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/plugin-events_0.1.0_1522618262548_0.4571629412425626"},"_hasShrinkwrap":false},"0.1.1":{"name":"@amarajs/plugin-events","amdName":"AmaraEvents","version":"0.1.1","description":"Provides custom DOM-based events for AmaraJS web applications and middleware.","jsnext:main":"src/index.js","main":"dist/amara-plugin-events.js","umd:main":"dist/amara-plugin-events.umd.js","scripts":{"bump":"standard-version","testonly":"mocha --compilers js:babel-register test/**/*.js","lint":"eslint src test","test":"flow && npm run lint && npm run testonly","build":"npm-run-all clean -p rollup:* -p minify:* -s size","clean":"rimraf dist && mkdirp dist","rollup:cjs":"rollup -c rollup.config.js -f cjs -n AmaraEvents src/index.js -o dist/amara-plugin-events.js","rollup:umd":"rollup -c rollup.config.js -f umd -n AmaraEvents src/index.js -o dist/amara-plugin-events.umd.js","minify:cjs":"uglifyjs dist/amara-plugin-events.js -cm toplevel -o dist/amara-plugin-events.min.js -p relative --source-map dist/amara-plugin-events.min.js.map","minify:umd":"uglifyjs dist/amara-plugin-events.umd.js -cm -o dist/amara-plugin-events.umd.min.js -p relative --source-map dist/amara-plugin-events.umd.min.js.map","size":"strip-json-comments --no-whitespace dist/amara-plugin-events.min.js | gzip-size | pretty-bytes","release":"npm run build -s && npm run bump && git push --follow-tags origin master && npm publish"},"keywords":["amara","amarajs","core"],"authors":["Dan Barnes <amarajs.framework@gmail.com>"],"repository":{"type":"git","url":"git+https://github.com/amarajs/plugin-events.git"},"license":"MIT","files":["src","dist"],"eslintConfig":{"parser":"babel-eslint","extends":"eslint:recommended","env":{"browser":true,"mocha":true,"node":true,"es6":true},"globals":{"expect":true},"rules":{"no-cond-assign":0}},"devDependencies":{"babel-core":"^6.9.1","babel-eslint":"^7.1.1","babel-plugin-transform-flow-strip-types":"^6.21.0","babel-preset-es2015":"^6.9.0","babel-preset-stage-0":"^6.5.0","babel-register":"^6.9.0","chai":"^3.5.0","documentation":"^4.0.0-beta4","eslint":"^3.13.1","flow-bin":"^0.38.0","gzip-size-cli":"^1.0.0","jsdom":"^11.6.2","mkdirp":"^0.5.1","mocha":"^3.2.0","npm-run-all":"^2.1.1","pretty-bytes-cli":"^2.0.0","rimraf":"^2.5.2","rollup":"^0.41.4","rollup-plugin-buble":"^0.15.0","rollup-plugin-flow":"^1.1.1","sinon":"^1.17.4","sinon-chai":"^2.8.0","standard-version":"^4.0.0","strip-json-comments-cli":"^1.0.1","uglify-js":"^2.6.2"},"gitHead":"b097569b697207807bb2d2626c357abaf15e7b90","bugs":{"url":"https://github.com/amarajs/plugin-events/issues"},"homepage":"https://github.com/amarajs/plugin-events#readme","_id":"@amarajs/plugin-events@0.1.1","_npmVersion":"5.6.0","_nodeVersion":"8.9.4","_npmUser":{"name":"amarajs-dan","email":"amarajs.framework@gmail.com"},"dist":{"integrity":"sha512-3isr33dNv3WTzBnUIHeHskfyfz7pbeVoVVd4tuzY4tYAyg2Jj3FLgYMnKziRXB1jMjKZpjt5lzqaugtb4URiqg==","shasum":"c5646e62818d69482e273ac840bc4999dee00270","tarball":"https://registry.npmjs.org/@amarajs/plugin-events/-/plugin-events-0.1.1.tgz","fileCount":10,"unpackedSize":54361,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJa0gYoCRA9TVsSAnZWagAADtYP/imgcnDJq0OJ/HBGLjzS\nfJrVLR1n/81UuC2pTniSHj331APF9JTrCDh9G4YwJr5RWTFkL7pjL6f4gvLl\nY7ka5DuWawUkCQUtttU0C6vD401i7UlQ60ro4S5F6t7tsaJU98lRAeuQWpK4\nCzNH910E/HjJRg7YxpehhU7ORBZyOeJfeDqjvWi069COxO0gsfkAI91dupBz\nmcmXbmDWQG7QaCejR8BQyaz76o2JxW0cDCVGBRtd6WW0/HclUhbwrJ46aoN7\n6NmVvr5gdu6DD3Uqipp7kDfNxMzcRRHlygZi975j+wxReKS34GCvVdArOWNt\neujmtTsKnfjg/xznylNjjEvDDul35L0bGTeJ1HS46BjozGoVWQ4M7A1Z0Tcu\nt//ijI59mhWZY0R+3bB5Z/x5jOs57/gMv30ndiJIM531rru3G56wFhngE56P\nKdDWRGgQHRGaXfg74hVkC1CzJ2kMD1p1IKIayMCV3GWArKd9pNVvu6VlpvJo\nKv++OawXFNfcRar2qISIQbzcPHKx10HwlZAKRrZ21u0A+oqKe2vbAsUuUa+y\nupnEoAfAb+L6PucVJO3UZ4mnJeOgwm7tIyd+y0I3MCKToLjxocvocd7ydmPX\nKCBPstMGiJSYKtzlbx5R3JsMNgUMbJWTMkPGqN0C/WPd46+u43N9iV5xLydg\nK1Jf\r\n=I2sQ\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEYCIQD4P/UPJTRGrG7cVBL4ZoT4YZ23LGpKYYZuxAWIbYAa7wIhANPaZ8YMA2oz1dfW9HLhNOqMJd1nqUD8QgJnCY3E6ERM"}]},"maintainers":[{"name":"amarajs-dan","email":"amarajs.framework@gmail.com"}],"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/plugin-events_0.1.1_1523713575514_0.20387227548518094"},"_hasShrinkwrap":false}},"time":{"created":"2018-04-01T21:31:02.500Z","0.1.0":"2018-04-01T21:31:02.655Z","modified":"2022-04-04T13:43:43.304Z","0.1.1":"2018-04-14T13:46:15.722Z"},"maintainers":[{"name":"amarajs-dan","email":"amarajs.framework@gmail.com"}],"description":"Provides custom DOM-based events for AmaraJS web applications and middleware.","homepage":"https://github.com/amarajs/plugin-events#readme","keywords":["amara","amarajs","core"],"repository":{"type":"git","url":"git+https://github.com/amarajs/plugin-events.git"},"bugs":{"url":"https://github.com/amarajs/plugin-events/issues"},"license":"MIT","readme":"## [@amarajs/plugin-events](https://github.com/amarajs/plugin-events)\n\nPlugin middleware for AmaraJS to add events to DOM nodes dynamically.\n\n### Installation\n\n`npm install --save @amarajs/plugin-events`\n\n### Usage\n\n```javascript\nimport Amara from '@amarajs/core';\nimport AmaraEvents from '@amarajs/plugin-events';\nimport AmaraBrowser from '@amarajs/plugin-engine-browser';\nconst amara = new Amara([\n    AmaraEvents(),\n    AmaraBrowser()\n]);\n```\n\n### Feature Type\n\nThe `@amarajs/plugin-events` middleware allows you to create features of type `\"events\"`.\n\n#### Return Values\n\nFor `{type: \"events\"}` features, your apply function should return a map of event names to handler functions. You can also use CSS selectors (for [event delegation](https://davidwalsh.name/event-delegate)) in your key names:\n\n```javascript\namara.add({\n    type: 'events',\n    targets: ['main'],\n    apply: () => ({\n        'click': (e) => {\n            console.log('click bubbled up to main');\n            e.preventDefault();\n            e.stopPropagation();\n        },\n        'click div.active': (e) => {\n            console.log('click fired on a <div class=\"active\"> child');\n            e.preventDefault();\n            e.stopPropagation();\n        },\n        'click a[href^=\"#\"], span[link]': (e) => {\n            console.log('click fired on a child internal anchor -or- <span link>');\n            e.preventDefault();\n            e.stopPropagation();\n        }\n    })\n});\n```\n\n### Dispatching Actions as Events\n\nEvent handlers can dispatch an `action` as if it were a DOM event. In this case, the action `\"type\"` will be used as the event name. These actions will bubble up the DOM like real events, so they can be handled by any interested parent nodes:\n\n```javascript\namara.add({\n    type: 'events',\n    targets: ['#save'],\n    apply: () => ({\n        click: (e) => {\n            // dispatch an action as if it\n            // were a custom DOM event:\n            e.dispatch(saveUserData());\n            e.stopPropagation();\n            e.preventDefault();\n        }\n    })\n});\n```\n\nIf an action is allowed to bubble all the way up to the node that was used to bootstrap your `amara` instance, then the `@amarajs/plugin-events` middleware will dispatch the action through AmaraJS, ensuring any other middleware that you registered has a chance to handle the action accordingly.\n\nThis enables contextual interception and modification of actions before they reach your middleware. For example, you could prevent an action from being dispatched to your [`@amarajs/plugin-redux`](https://github.com/amarajs/plugin-redux) middleware by simply stopping its propagation:\n\n```javascript\namara.add({\n    type: 'events',\n    targets: ['main'],\n    args: { saving: ({state}) => state.saving }\n    apply: ({saving}) => ({\n        // don't save user data if a\n        // save is already in progress\n        'save-user-data': (e) => {\n            saving && e.stopPropagation();\n        }\n    })\n});\n```\n\n### Lifecycle Events\n\nThere are a few special events you can register handlers for. These events will fire at specific moments you may want to tap into.\n\n__NOTE:__ These events cannot be delegated. They will only fire on the target the feature applies to &mdash; they will _not_ bubble up the DOM to any parent nodes.\n\n#### `\"amara:add\"`\n\nThis event fires the first time an `\"events\"` feature targets the specified DOM node. It is _not_ fired when the target is first inserted into the DOM.\n\n```javascript\namara.add({\n    type: 'events',\n    target: ['main'],\n    apply: () => ({\n        'amara:add': (e) => {\n            console.log('first \"events\" feature has been added to <main>');\n            console.log('this handler will never fire again');\n        }\n    })\n});\n```\n\nNote that AmaraJS waits to apply all newly added features until the end of the current stack frame. That means if you registered another `'amara:add'` handler to the same target within the current frame, it would also be invoked (in the order it was registered with your `amara` instance).\n\nHowever, if you added an `'amara:add'` handler _after_ another `'events'` feature had already been applied to the same target, then it would NOT be invoked:\n\n```javascript\n// assume a previous 'events' feature was already added to main\nsetTimeout(() => {\n    amara.add({\n        type: 'events',\n        target: ['main'],\n        apply: () => ({\n            'amara:add': (e) => {\n                console.log('this will never fire');\n            }\n        })\n    });\n});\n```\n\n#### `\"amara:remove\"`\n\nThis event fires when the target is detached or removed from the DOM. For that reason, you will not have access to the full ancestor DOM tree in `e.target`:\n\n```javascript\namara.add({\n    type: 'events',\n    targets: ['main'],\n    apply: () => ({\n        'amara:remove': (e) => {\n            // e.target (<main>) has been removed from the DOM\n            console.log(e.target.parentElement) // may not exist\n        }\n    });\n});\n```\n\nYou may be wondering: Why does `amara:remove` fire when a node is removed from the DOM but `amara:add` only fires the first time an `\"events\"` feature is registered for the given target?\n\nBecause event delegation isn't allowed for the built-in `amara:*` lifecycle events &mdash; in other words, because we don't bubble these special events &mdash; there is no reason to dispatch an `amara:add` event on a node that has no `\"events\"` features targeting it.\n\nHowever, we still wanted to provide developers with an opportunity to \"bootstrap\" a given target node. For that reason, the first time you add an `\"events\"` feature to a given target, we will be sure to invoke an `amara:add` event you can hook into.\n\nIf you want a feature to _always_ run the first time is is created, but never more than once, use the `'amara:apply'` lifecycle (see below) and wrap your apply method in a utility method like lodash's `_.once`.\n\n#### `\"amara:apply\"`\n\nThis event fires every time the AmaraJS engine believes a target's `\"events\"` features need to be re-applied. These handlers are a great place to dynamically modify your targets based on changing `args` values:\n\n```javascript\namara.add({\n    type: 'events',\n    targets: ['#items'],\n    args: { activeItem: ({state}) => state.activeItem },\n    apply: ({ activeItem }) => ({\n        'amara:apply': (e) => {\n            // update the active list item every time activeItem changes\n            if (activeItem)\n                e.target.setAttribute('aria-activedescendant', activeItem.id);\n            else\n                e.target.removeAttribute('aria-activedescendant');\n        }\n    })\n});\n```\n\n### KeyboardEvent Helpers\n\nTo make dealing with keyboard events easier, any `keydown`, `keyup`, or `keypress` handler can specify one or more [key values](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values) after the event name:\n\n```javascript\namara.add({\n    type: 'events',\n    targets: ['input[type=\"text\"]'],\n    apply: () => ({\n        'keydown.enter': (e) => {\n            e.preventDefault();\n            e.stopPropagation();\n            e.dispatch(search(e.target.value));\n        }\n    })\n});\n```\n\nYou can also handle delegated events:\n\n```javascript\namara.add({\n    type: 'events',\n    targets: ['main'],\n    apply: () => ({\n        'keydown.enter input[type=\"text\"]': (e) => {\n            e.preventDefault();\n            e.stopPropagation();\n            e.dispatch(search(e.target.value));\n        }\n    })\n});\n```\n\nAnd a single handler for one or more possible keys:\n\n```javascript\namara.add({\n    type: 'events',\n    targets: ['main'],\n    apply: () => ({\n        'keydown.enter.space': (e) => {\n            e.preventDefault();\n            e.stopPropagation();\n            e.dispatch(activate(e.target.value));\n        }\n    })\n});\n```\n\nTo handle spacebar, use `\"space\"` as your key name:\n\n```javascript\namara.add({\n    type: 'events',\n    targets: ['#todos'],\n    apply: () => ({\n        'keydown.space .todo': (e) => {\n            e.preventDefault();\n            e.stopPropagation();\n            e.dispatch(toggle(e.target.id));\n        }\n    })\n});\n```\n\n### MouseEvent Helpers\n\nAny `mousedown` or `mouseup` handler can specify one or more [button values](https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent/button) after the event name:\n\n```javascript\namara.add({\n    type: 'events',\n    targets: ['input[type=\"text\"]'],\n    apply: () => ({\n        'mousedown.2': (e) => {\n            e.preventDefault();\n            e.stopPropagation();\n            e.dispatch(showContextMenu());\n        }\n    })\n});\n```\n\nYou can use the following friendly names rather than numeric values:\n\nbutton | number | friendly name\n--- | --- | ---\nprimary button | 0 | `\"left\"`\nauxiliary button | 1 | `\"middle\"` or `\"wheel\"`\nsecondary button | 2 | `\"right\"`\n\n```javascript\namara.add({\n    type: 'events',\n    targets: ['input[type=\"text\"]'],\n    apply: () => ({\n        'mousedown.right': (e) => {\n            e.preventDefault();\n            e.stopPropagation();\n            e.dispatch(showContextMenu());\n        }\n    })\n});\n```\n\nJust as with `KeyboardEvent`s, you can use these helpers with delegation and also combine multiple helpers together, in which case the handler will be invoked when any of those mouse buttons is pressed.\n\n### Applying Multiple Results to the Same Target\n\nIf multiple `{type: \"events\"}` features target the same DOM, the handlers will be added in the order the features were applied. The same handler (by reference) can be added to the same event type multiple times.\n\n### Customization\n\nThis plugin has no customization options.\n\n### Contributing\n\nIf you have a feature request, please create a new issue so the community can discuss it.\n\nIf you find a defect, please submit a bug report that includes a working link to reproduce the problem (for example, using [this fiddle](https://jsfiddle.net/04f3v2x4/)). Of course, pull requests to fix open issues are always welcome!\n\n### License\n\nThe MIT License (MIT)\n\nCopyright (c) Dan Barnes\n\nPermission 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:\n\nThe above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.\n\nTHE 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.\n","readmeFilename":"README.md"}