@w-lfpup/superaction

v0.5.1

Published

18 days ago

Turn the DOM into a declarative event-bus

0High
0Medium
0Low

taylorwolf

SuperAction-js

A hypertext extension to upgrade your HTML with a declarative eventbus.

(It's also a proof-of-concept for hyperevents-js).

Examples

Superaction is little different compared to most frontend libraries. HTML declares what actions are sent to javascript-land similar to a classic eventbus.

Check out a simple click counter (live example).

Then look at more interesting sketch example and learn how to connect UI events to an offscreen canvas (live example).

Install

Install via npm.

npm install --save-dev @w-lfpup/superaction

Or install directly from github.

npm install --save-dev https://github.com/w-lfpup/superaction-js

Setup

Create 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!

Declare

Add an attribute with the pattern event:=action. The #action event will dispatch from the host element.

<button click:="increment">+</button>

Listen

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.

Event stacking

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"

Propagation

Action events propagate similar to DOM events. Their declarative API reflects their DOM Event counterpart:

event:prevent-default
event:stop-propagation
event: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 original HTMLSubmitEvent
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()

Why #action ?

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.

License

SuperAction-js is released under the BSD-3 Clause License.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme