1 | # Holosun
|
2 |
|
3 | [![Release Version](https://img.shields.io/npm/v/holosun.svg)](https://www.npmjs.com/package/holosun)
|
4 | [![License](https://img.shields.io/badge/License-Apache%202-blue.svg)](https://github.com/roydukkey/holosun/blob/master/LICENSE)
|
5 |
|
6 | An events API with delegation and type declarations. Holosun is built to remain completely interoperable with the native events API.
|
7 |
|
8 | ## Usage
|
9 |
|
10 | The distribution provided at `./dist/holosun.umd.js` can be used directly in the browser, with the API begin namespaced as a `holosun` global variable.
|
11 |
|
12 | Or, use the package like any other node package:
|
13 |
|
14 | ```js
|
15 | // ES6 module syntax
|
16 | import * as holosun from 'holosun';
|
17 | import { on, off } from 'holosun';
|
18 |
|
19 | // CommonJS syntax
|
20 | const holosun = require('holosun');
|
21 | const { on, off } = require('holosun');
|
22 | ```
|
23 |
|
24 | Alteratively, importing TypeScript directly will allow transpiled code to be optimize, including only the required portions of Holosun.
|
25 |
|
26 | ```js
|
27 | import { on, off } from 'holosun/typescript';
|
28 | ```
|
29 |
|
30 | Note: this package includes a proper [ECMAScript module](#ECMAScript-Modules).
|
31 |
|
32 | ## API Summary
|
33 |
|
34 | | function | description |
|
35 | | --- | --- |
|
36 | | [`holosun.on()`](#HolosunOn) | Attach an event listener that will be called whenever a specified event type is delivered to the given target. |
|
37 | | [`holosun.one()`](#HolosunOne) | Attach an event listener that will be called once whenever each of the specified event types are delivered to the given target. |
|
38 | | [`holosun.any()`](#HolosunAny) | Attach an event listener that will be called once whenever any of the specified event types are delivered to the given target. |
|
39 | | [`holosun.off()`](#HolosunOff) | Detach event listeners of the specified event types from the given target. |
|
40 | | [`holosun.trigger()`](#HolosunTrigger) | Executes all listeners attached to the given target for the specified event types. |
|
41 |
|
42 | ## API
|
43 |
|
44 | ### holosun.on()
|
45 |
|
46 | #### `on (target, types, listener[, useCapture | options])`
|
47 | Attach an event listener that will be called whenever a specified event type is delivered to the given target.
|
48 |
|
49 | #### `on (node, selector, types, listener[, useCapture | options])`
|
50 | Attach an event listener that will be called whenever a specified event type is delivered to the given node from specific descendants.
|
51 |
|
52 | ##### Parameters
|
53 | | parameter | type | description |
|
54 | | --- | --- | --- |
|
55 | | `target` | [`EventTarget`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget) | The target on which the event listener is attached. |
|
56 | | `node` | [`Node`](https://developer.mozilla.org/en-US/docs/Web/API/Node) | The node on which the event listener is attached. |
|
57 | | `selector` | `string` | A selector string to filter the descendants of the given node that trigger the event. |
|
58 | | `types` | `string` | A case-sensitive string representing the [event type](https://developer.mozilla.org/en-US/docs/Web/Events)s to listen for. |
|
59 | | `listener` | [`EventListener`](https://developer.mozilla.org/en-US/docs/Web/API/EventListener) \|<br>[`EventListenerObject`](https://developer.mozilla.org/en-US/docs/Web/API/EventListener) \|<br>`null` | The object that receives a notification (an object that implements the [Event](https://developer.mozilla.org/en-US/docs/Web/API/Event) interface) when an event of a specified type occurs. This must be an object implementing the EventListener interface, or a function. |
|
60 | | `useCapture` | `boolean` | Whether or not events of these types will be dispatched to the registered listener before being dispatched to any target beneath it in the DOM tree. |
|
61 | | `options` | `AddEventListenerOptions` | An [options object](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#parameters) specifying characteristics about the event listener. |
|
62 |
|
63 | ##### Returns
|
64 | The provided listener when successfully attached; otherwise, `undefined`.
|
65 |
|
66 | ### holosun.one()
|
67 |
|
68 | #### `one (target, types, listener[, useCapture | options])`
|
69 | Attach an event listener that will be called once whenever each of the specified event types are delivered to the given target.
|
70 |
|
71 | #### `one (node, selector, types, listener[, useCapture | options])`
|
72 | Attach an event listener that will be called once whenever each of the specified event types are delivered to the given node from specific descendants.
|
73 |
|
74 | ##### Parameters & Returns
|
75 | Same as [`holosun.on()`](#HolosunOn).
|
76 |
|
77 | ### holosun.any()
|
78 |
|
79 | #### `any (target, types, listener[, useCapture | options])`
|
80 | Attach an event listener that will be called once whenever any of the specified event types are delivered to the given target.
|
81 |
|
82 | #### `any (node, selector, types, listener[, useCapture | options])`
|
83 | Attach an event listener that will be called once whenever any of the specified event types are delivered to the given node from specific descendants.
|
84 |
|
85 | ##### Parameters & Returns
|
86 | Same as [`holosun.on()`](#HolosunOn).
|
87 |
|
88 | ### holosun.off()
|
89 |
|
90 | #### `off (target, types)`
|
91 | Detach all event listeners of the specified event types from the given target.
|
92 |
|
93 | #### `off (target, types, listener[, useCapture | options])`
|
94 | Detach an event listener of the specified event types from the given target.
|
95 |
|
96 | #### `off (node, selector, types)`
|
97 | Detach all event listeners of the specified event types from the given node for the specified selector.
|
98 |
|
99 | #### `off (node, selector, types, listener[, useCapture | options])`
|
100 | Detach an event listener of the specified event types from the given node for the specified selector.
|
101 |
|
102 | ##### Parameters
|
103 | | parameter | type | description |
|
104 | | --- | --- | --- |
|
105 | | `target` | [`EventTarget`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget) | The target from which the event listener is detached. |
|
106 | | `node` | [`Node`](https://developer.mozilla.org/en-US/docs/Web/API/Node) | The node from which the event listener is detached. |
|
107 | | `selector` | `string` | A selector which should match the one used when attaching event listeners. |
|
108 | | `types` | `string` | A case-sensitive string representing the [event type](https://developer.mozilla.org/en-US/docs/Web/Events)s to detach. |
|
109 | | `listener` | [`EventListener`](https://developer.mozilla.org/en-US/docs/Web/API/EventListener) \|<br>[`EventListenerObject`](https://developer.mozilla.org/en-US/docs/Web/API/EventListener) \|<br>`null` | The event listener to detach from the event target. |
|
110 | | `useCapture` | `boolean` | Whether or not the EventListener to be detached is registered as a capturing listener. |
|
111 | | `options` | `EventListenerOptions` | An [options object](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/removeEventListener#parameters) specifying characteristics about the event listener. |
|
112 |
|
113 | ##### Returns
|
114 | `true` when successfully detached at least one listener; otherwise, `false`.
|
115 |
|
116 | ### holosun.trigger()
|
117 |
|
118 | #### `trigger (target, types[, options])`
|
119 | Executes all listeners attached to the given target for the specified event types.
|
120 |
|
121 | ##### Parameters
|
122 | | parameter | type | description |
|
123 | | --- | --- | --- |
|
124 | | `target` | [`EventTarget`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget) | The target on which the specified events are executed. |
|
125 | | `types` | `string` | A case-sensitive string representing the [event type](https://developer.mozilla.org/en-US/docs/Web/Events)s to execute. |
|
126 | | `options` | `EventInit` | An [options object](https://developer.mozilla.org/en-US/docs/Web/API/Event/Event#values) specifying characteristics about the triggered event. |
|
127 |
|
128 | ##### Returns
|
129 | A list of tuples, where the first value is the event type and the second is `true`; unless the event is cancelable and at least one of the event listeners, which received the event, called [`Event.preventDefault()`](https://developer.mozilla.org/en-US/docs/Web/API/Event/preventDefault), the second value is `false`.
|
130 |
|
131 | ## ECMAScript Modules
|
132 |
|
133 | This library comes with [ECMAScript Modules](https://www.ecma-international.org/ecma-262/6.0/#sec-modules) (ESM) support for Node.js versions that support it as well as bundlers like [rollup.js](https://rollupjs.org/guide/en/#tree-shaking) and [webpack](https://webpack.js.org/guides/tree-shaking/) (targeting both, Node.js and browser environments).
|
134 |
|
135 | ## CDN Builds
|
136 |
|
137 | ### ECMAScript Modules
|
138 | To load this module directly into modern browsers that [support loading ECMAScript Modules](https://caniuse.com/#feat=es6-module) you can make use of [jspm](https://jspm.org/):
|
139 |
|
140 | ```html
|
141 | <script type="module">
|
142 | import { on } from 'https://jspm.dev/holosun';
|
143 | on(document, 'click', () => {
|
144 | window.location.href = 'https://youtu.be/950sXulKXGs?t=10';
|
145 | });
|
146 | </script>
|
147 | ```
|
148 |
|
149 | ### UMD
|
150 | To load this module directly into older browsers you can use the [UMD (Universal Module Definition)](https://github.com/umdjs/umd) builds from any of the following CDNs.
|
151 |
|
152 | These CDNs all provide the entire API as a `holosun` global variable:
|
153 |
|
154 | ```html
|
155 | <script>
|
156 | holosun.on(document, 'click', () => {
|
157 | window.location.href = 'https://youtu.be/950sXulKXGs?t=10';
|
158 | });
|
159 | </script>
|
160 | ```
|
161 |
|
162 | #### Using [UNPKG](https://unpkg.com/browse/holosun/dist/)
|
163 | ```html
|
164 | <script src="https://unpkg.com/holosun@latest/dist/holosun.umd.js"></script>
|
165 | ```
|
166 |
|
167 | #### Using [jsDelivr](https://cdn.jsdelivr.net/npm/holosun@latest/dist/)
|
168 | ```html
|
169 | <script src="https://cdn.jsdelivr.net/npm/holosun@latest/dist/holosun.umd.js"></script>
|
170 | ```
|