w-lfpup · taylor-vann · May 23, 2026 · May 23, 2026 · May 23, 2026 · May 23, 2026
diff --git a/README.md b/README.md
@@ -0,0 +1,144 @@
+# react-superaction
+
+Turn the virtual-dom into a declarative event-bus.
+
+(a port of [superaction](https://github.com/w-lfpup/superaction-js) for React)
+
+## Install
+
+Install via npm.
+
+```sh
+npm install --save-dev @w-lfpup/react-superaction
+```
+
+Or install directly from github.
+
+```sh
+npm install --save-dev https://github.com/w-lfpup/react-superaction
+```
+
+## Setup
+
+Add a `SuperActionProvider` component to broadcast action events.
+
+The `SuperActionProvider` component below listens for click events. React developers can access action events.
+
+```tsx
+import React from "react";
+import ReactDOM from "react-dom/client";
+import { SuperActionProvider } from "@w-lfpup/react-superaction";
+import { App } from "./App.js";
+
+let eventNames: string[] = ["click"];
+
+let rootEl = document.querySelector("##root")!;
+const root = ReactDOM.createRoot(rootEl);
+root.render(
+	<SuperActionProvider eventNames={eventNames}>
+		<Counter />
+	</SuperActionProvider>,
+);
+```
+
+## Declare
+
+Add an attribute with the pattern `event-=action`.
+
+```html
+<button click-="increment">+</button>
+```
+
+Now the button dispatches ActionEvents when clicked. 
+
+## Listen
+
+The `useSuperAction` hook connects action events to react-land.
+
+```tsx
+import React, { useState } from "react";
+import { ActionInterface, useSuperAction } from "@w-lfpup/react-superaction";
+
+export function Counter() {
+	let [count, setCount] = useState(0);
+
+	useSuperAction((action: ActionInterface) => {
+		if ("increment" === action.type) setCount(count + 1);
+	});
+
+	return <button click-="increment">{count</button>
+}
+```
+
+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
+
+```ts
+let { type, event, target, formData } = action;
+```
+
+Form data is available when an action event originates from a element.
+
+## 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](https://www.w3.org/TR/uievents/#events-uievents). Which is a lot of events!
+
+Consider the following example:
+
+```html
+<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:
+
+```html
+<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()`
+
+## License
+
+React-superaction is released under the BSD-3 Clause License.
diff --git a/examples/counter/bundle.js b/examples/counter/bundle.js
@@ -30281,7 +30281,6 @@ class SuperAction {
     }
     #dispatch = this.#unboundDispatch.bind(this);
     #unboundDispatch(event) {
-        console.log(event);
         let { type, currentTarget, target } = event;
         if (!currentTarget)
             return;

diff --git a/examples/form/bundle.js b/examples/form/bundle.js
@@ -30281,7 +30281,6 @@ class SuperAction {
     }
     #dispatch = this.#unboundDispatch.bind(this);
     #unboundDispatch(event) {
-        console.log(event);
         let { type, currentTarget, target } = event;
         if (!currentTarget)
             return;
@@ -30341,7 +30340,7 @@ function useSuperAction(cb) {
         cb(action);
 }
 
-function CustomForm() {
+function Form() {
     let [formAsJSON, setFormAsJSON] = reactExports.useState("");
     useSuperAction((action) => {
         let { type, formData } = action;
@@ -30365,5 +30364,5 @@ let rootEl = document.querySelector("#root");
 if (rootEl) {
     const root = ReactDOM.createRoot(rootEl);
     root.render(React.createElement(SuperActionProvider, { eventNames: eventNames },
-        React.createElement(CustomForm, null)));
+        React.createElement(Form, null)));
 }
diff --git a/examples/form/custom_form.js → examples/form/form.js b/examples/form/custom_form.js → examples/form/form.js
@@ -1,6 +1,6 @@
 import React, { useState } from "react";
 import { useSuperAction } from "../../dist/mod.js";
-export function CustomForm() {
+export function Form() {
     let [formAsJSON, setFormAsJSON] = useState("");
     useSuperAction((action) => {
         let { type, formData } = action;

diff --git a/examples/form/custom_form.tsx → examples/form/form.tsx b/examples/form/custom_form.tsx → examples/form/form.tsx
@@ -2,7 +2,7 @@ import React, { useState } from "react";
 import { useSuperAction, useAction } from "../../dist/mod.js";
 import { ActionInterface } from "@w-lfpup/superaction";
 
-export function CustomForm() {
+export function Form() {
 	let [formAsJSON, setFormAsJSON] = useState<string>("");
 
 	useSuperAction((action: ActionInterface) => {

diff --git a/examples/form/root.js b/examples/form/root.js
@@ -1,11 +1,11 @@
 import React from "react";
 import ReactDOM from "react-dom/client";
 import { SuperActionProvider } from "../../dist/mod.js";
-import { CustomForm } from "./custom_form.js";
+import { Form } from "./form.js";
 let eventNames = ["submit"];
 let rootEl = document.querySelector("#root");
 if (rootEl) {
     const root = ReactDOM.createRoot(rootEl);
     root.render(React.createElement(SuperActionProvider, { eventNames: eventNames },
-        React.createElement(CustomForm, null)));
+        React.createElement(Form, null)));
 }
diff --git a/examples/form/root.tsx b/examples/form/root.tsx
@@ -1,7 +1,7 @@
 import React from "react";
 import ReactDOM from "react-dom/client";
 import { SuperActionProvider } from "../../dist/mod.js";
-import { CustomForm } from "./custom_form.js";
+import { Form } from "./form.js";
 
 let eventNames: string[] = ["submit"];
 
@@ -10,7 +10,7 @@ if (rootEl) {
 	const root = ReactDOM.createRoot(rootEl);
 	root.render(
 		<SuperActionProvider eventNames={eventNames}>
-			<CustomForm />
+			<Form />
 		</SuperActionProvider>,
 	);
 }
diff --git a/package.json b/package.json
@@ -1,6 +1,10 @@
 {
-	"name": "react-superaction",
+	"name": "@w-lfpup/react-superaction",
 	"type": "module",
+	"main": "dist/mod.js",
+	"description": "Turn the virtual-dom into a declarative event-bus",
+	"license": "BSD-3-Clause",
+	"version": "0.1.0",
 	"scripts": {
 		"build": "npm run build:core && npm run build:examples",
 		"build:core": "npx tsc --project src/",
@@ -22,5 +26,9 @@
 		"react-dom": "^19.2.6",
 		"rollup": "^4.60.4",
 		"typescript": "^6.0.3"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/w-lfpup/react-superaction.git"
 	}
 }
diff --git a/src/hook.tsx b/src/hook.tsx
@@ -16,7 +16,6 @@ export function useSuperAction(cb: Cb) {
 	if (action) cb(action);
 }
 
-// single action hook useAction("howdy")
 export function useAction(type: string, cb: Cb): ActionInterface | undefined {
 	let action = useContext(SuperContext);
 	let [prevAction, setPrevAction] = useState<ActionInterface | undefined>(