A hypertext extension to upgrade your HTML with a declarative eventbus.
(For a more full-featured experience, checkout hyperevents-js).
Superaction is little different compared to most frontend libraries. HTML declares what actions are sent to javascript-land.
Check out a simple click counter (live).
Then look at more interesting sketch example that sends UI events to a worker with an offscreen canvas (live).
Install via npm.
npm install --save-dev @w-lfpup/superactionOr install directly from github.
npm install --save-dev https://github.com/w-lfpup/superaction-jsCreate a SuperAction instance to dispatch action events.
The SuperAction instance below listens for click events. Event listeners are immediately connected to the document.
import { SuperAction } from "superaction";
const _superAction = new SuperAction({
host: document,
eventNames: ["click"],
connected: true,
});Now the DOM can declarativey dispatch meaningful messages from HTML to Javascript-land because SuperAction effectively works like a classic eventbus!
Add an attribute with the pattern event:=action. The #action event will dispatch from the host element.
<button click:="increment">+</button>Now the button will dispatch an ActionEvent from the host when clicked.
Add an event listener to connect action events to javascript-land.
document.addEventListener("#action", (e) => {
let { type } = e.action;
if ("increment" === type) {
// increment something!
}
});The action object has several properties related to an action event including:
- the action
type - the original dom
event - the action event
target - associated
formData
let { type, event, target, formData } = e.action;Form data is available when action events originate from form elements.
Superaction-js listens to any DOM event that bubbles. It also dispatches all actions found along the composed path of a DOM event.
Turns out that's all UI Events. Which is a lot of events!
Consider the following example:
<body click:="A">
<div click:="B">
<button click:="C">hai :3</button>
</div>
</body>When a person clicks the button above, the order of action events is:
- Action "C"
- Action "B"
- Action "A"
Action events propagate similar to DOM events. Their declarative API reflects their DOM Event counterpart:
event:prevent-defaultevent:stop-propagationevent:stop-immediate-propagation
Consider the following example:
<body
click:="A"
click:stop-immediate-propagation>
<form
click:="B"
click:prevent-default>
<button
type=submit
click:="C">
UwU
</button>
<button
type=submit
click:="D"
click:stop-propagation>
^_^
</button>
</form>
</body>So when a person clicks the buttons above, the order of actions is:
Click button C:
- Action "C" dispatched
preventDefault()is called on the originalHTMLSubmitEvent- Action "B" dispatched
- Action propagation is stopped similar to
event.stopImmediatePropagation() - Action "A" does not dispatch
Click button D:
- Action "D" dispatched
- Action event propagation stopped similar to
event.stopPropagation()
The #action event name, specifically the #, is used to prevent cyclical event disptaches.
The browser restricts dynamically adding attribtues to elements that start with #. And in this way, some of the infinite loop risks are mitigated.
SuperAction-js is released under the BSD-3 Clause License.