@w-lfpup/superaction

v0.2.0

Published

2 months ago

A hypertext extension to dispatch meaningful actions from UI events

0High
0Medium
0Low

taylorwolf

SuperAction-js

A hypertext extension to dispatch meaningful actions from HTML.

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,
	connected: true,
	eventNames: ["click"],
});

Now the DOM can declarativey dispatch meaningful messages from HTML to Javascript-land.

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 from the UI to javascript-land.

document.addEventListener("#action", (e) => {
	let { kind, originElement, originEvent, formData } = e.action;

	if ("increment" === action) {
		// increment something!
	}
});

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.

We can't dynamically add attribtues to elements that start with #. And in this way, some of the infinite loop risk is mitigated.

License

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

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme