@w-lfpup/wctk 0.1.0 → 0.1.1

package/.github/workflows/{build_and_test.yml → builds.yml}

@@ -1,4 +1,4 @@
-name: Build and Test
+name: Builds
 
 on:
     push:
@@ -10,7 +10,7 @@ jobs:
     build_and_test:
         runs-on: ubuntu-latest
         steps:
-            - uses: actions/checkout@v5
+            - uses: actions/checkout@v6
             - uses: actions/setup-node@v4
             - name: Install
               run: npm ci

package/README.md

@@ -1,6 +1,8 @@
 # Wctk-JS
 
-A web component tool kit.
+A web component tool kit without dependencies.
+
+[![Builds](https://github.com/w-lfpup/wctk-js/actions/workflows/builds.yml/badge.svg)](https://github.com/w-lfpup/wctk-js/actions/workflows/builds.yml)
 
 ## About
 
@@ -14,11 +16,9 @@ A half-dozen controllers help developers:
 - [query](./docs/query_selector.md) the shadow dom
 - [bind](./docs/bind.md) functions to elements
 
-All features are compositional and built to support [declarative shadow dom](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM#declaratively_with_html) SSR.
-
-There are no base classes or decorators.
+All features are compositional and built to support [declarative shadow dom](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM#declaratively_with_html) and SSR.
 
-`Wctk-js` even supports `#private` methods as callbacks, fully encapsulating a web component's API (aside from required [lifecycle methods](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements#custom_element_lifecycle_callbacks)).
+There are no base classes, decorators, or mixins.
 
 ## Install
 

package/dist/events.d.ts

@@ -1,17 +1,26 @@
-export type Callbacks = Array<[string, EventListenerOrEventListenerObject]>;
-export interface EventsInterface {
-    connect(): void;
-    disconnect(): void;
+interface GenericEventListener<E> {
+    (evt: E): void;
 }
-export interface EventElementInterface {
-    addEventListener: EventTarget["addEventListener"];
-    removeEventListener: EventTarget["removeEventListener"];
+interface GenericEventListenerObject<E> {
+    handleEvent(object: E): void;
+}
+type GenericCallbacks<E> = GenericEventListener<E> | GenericEventListenerObject<E>;
+type EventMap = Partial<{
+    [Property in keyof GlobalEventHandlersEventMap]: GenericCallbacks<GlobalEventHandlersEventMap[Property]>;
+}>;
+interface EventElementInterface {
+    addEventListener: Element["addEventListener"];
+    removeEventListener: Element["removeEventListener"];
 }
 export interface EventParamsInterface {
-    host: EventElementInterface;
+    callbacks: EventMap;
     connected?: boolean;
+    host: EventElementInterface;
     target?: EventElementInterface;
-    callbacks: Callbacks;
+}
+export interface EventsInterface {
+    connect(): void;
+    disconnect(): void;
 }
 export declare class Events implements EventsInterface {
     #private;
@@ -19,3 +28,4 @@ export declare class Events implements EventsInterface {
     connect(): void;
     disconnect(): void;
 }
+export {};

package/dist/events.js

@@ -28,12 +28,15 @@ export class Events {
 }
 function getBoundCallbacks(host, callbacks) {
     let boundCallbacks = [];
-    for (let [name, callback] of callbacks) {
+    for (let [name, callback] of Object.entries(callbacks)) {
         if (callback instanceof Function &&
             !callback.hasOwnProperty("prototype")) {
             callback = callback.bind(host);
         }
-        boundCallbacks.push([name, callback]);
+        boundCallbacks.push([
+            name,
+            callback,
+        ]);
     }
     return boundCallbacks;
 }

package/dist/wc.js

@@ -6,18 +6,20 @@ export class Wc {
     #internals;
     #shadowRoot;
     constructor(params) {
-        let { host, shadowRootInit, adoptedStyleSheets, formValue, formState } = params;
+        let { adoptedStyleSheets, host, formState, formValue, shadowRootInit } = params;
         this.#internals = host.attachInternals();
         let { shadowRoot } = this.#internals;
-        if (!shadowRoot) {
+        if (shadowRoot) {
+            this.#shadowRoot = shadowRoot;
+        }
+        else {
             this.#declarative = false;
-            shadowRoot = host.attachShadow(shadowRootInit ?? shadowRootInitFallback);
+            this.#shadowRoot = host.attachShadow(shadowRootInit ?? shadowRootInitFallback);
         }
-        this.#shadowRoot = shadowRoot;
-        if (formValue)
-            this.setFormValue(formValue, formState);
         if (adoptedStyleSheets)
             this.adoptedStyleSheets = adoptedStyleSheets;
+        if (formValue)
+            this.setFormValue(formValue, formState);
     }
     get declarative() {
         return this.#declarative;

package/docs/events.md

@@ -1,6 +1,6 @@
 # Events Controller
 
-Add methods as event listener callbacks.
+Add event listeners to web components.
 
 ## How to use
 
@@ -12,14 +12,14 @@ An Events `params` object has four properties:
 
 ```ts
 interface EventParams {
-	host: Node;
-	callbacks: Array<[string, EventListener]>;
+	callbacks: Record<string, EventListenerOrEventListenerObject>;
 	connected?: boolean;
+	host: Node;
 	target?: Node;
 }
 ```
 
-The `Events` controller binds a set of `callbacks` to a `host`.
+The `Events` controller binds a record of `callbacks` to a `host`.
 
 Afterwards, the `Events` controller adds the callbacks as event listeners on a `target` node.
 
@@ -36,20 +36,21 @@ import { Events, Wc } from "wctk";
 
 class MyElement extends HTMLElement {
 	#wc = new Wc({ this: host });
+
 	#ec = new Events({
 		host: this,
 		target: this.#wc.shadowRoot,
-		callbacks: [
-			["click", this.#onClick],
-			["keydown", this.#onKeyDown],
-		],
+		callbacks: {
+			click: this.#onClick,
+			keydown: this.#onKeyDown,
+		},
 	});
 
 	#onClick(e: PointerEvent) {
 		// do something with pointer events here!
 	}
 
-	#onKeyDown(e: KeyEvent) {
+	#onKeyDown(e: KeyboardEvent) {
 		// do something with key events here!
 	}
 
@@ -78,10 +79,10 @@ class MyElement extends HTMLElement {
 		host: this,
 		target: this.#wc.shadowRoot,
 		connected: true,
-		callbacks: [
-			["click", this.#onClick],
-			["keydown", this.#onKeyDown],
-		],
+		callbacks: {
+			click: this.#onClick,
+			keydown: this.#onKeyDown,
+		},
 	});
 
 	#onClick(e: PointerEvent) {

package/docs/query_selector.md

@@ -21,6 +21,7 @@ import { QuerySelector } from "wctk";
 
 class MyElement extends HTMLElement {
 	#wc = new Wc({ host: this });
+
 	#qc = new QuerySelector({
 		parent: this.#wc.shadowRoot,
 	});

package/docs/wc.md

@@ -4,9 +4,7 @@ Build a web component.
 
 ## How to use
 
-Add a `Wc` controller to a custom element.
-
-One line is all it takes.
+Add a `Wc` controller to a custom element with only one line
 
 ```ts
 import { Wc } from "wctk";
@@ -18,7 +16,7 @@ class MyElement extends HTMLElement {
 
 ## Adopted stylesheets and form values
 
-The `Wc` controller is also a facade for core web componet APIs like adopted stylesheets and form values.
+The `Wc` controller is also a facade for fast access to core web componet APIs like adopted stylesheets and form values.
 
 ```ts
 class MyElement extends HTMLElement {

package/examples/counter/mod.js

@@ -1,17 +1,19 @@
-import { Wc, Events } from "wctk";
 /*
     Custom Element with state and interactivity.
 */
+import { Wc, Events } from "wctk";
 class Counter extends HTMLElement {
     #wc = new Wc({ host: this });
     #ev = new Events({
         host: this,
         target: this.#wc.shadowRoot,
         connected: true,
-        callbacks: [["click", this.#clickHandler]],
+        callbacks: {
+            click: this.#onClick,
+        },
     });
     #state = getStateFromDOM(this.#wc.shadowRoot);
-    #clickHandler(e) {
+    #onClick(e) {
         if (!this.#state)
             return;
         let increment = getIncrement(e);

package/examples/counter/mod.ts

@@ -1,3 +1,7 @@
+/*
+	Custom Element with state and interactivity.
+*/
+
 import { Wc, Events } from "wctk";
 
 interface State {
@@ -5,9 +9,6 @@ interface State {
 	count: number;
 }
 
-/*
-	Custom Element with state and interactivity.
-*/
 class Counter extends HTMLElement {
 	#wc = new Wc({ host: this });
 
@@ -15,12 +16,14 @@ class Counter extends HTMLElement {
 		host: this,
 		target: this.#wc.shadowRoot,
 		connected: true,
-		callbacks: [["click", this.#clickHandler]],
+		callbacks: {
+			click: this.#onClick,
+		},
 	});
 
 	#state?: State = getStateFromDOM(this.#wc.shadowRoot);
 
-	#clickHandler(e: Event) {
+	#onClick(e: PointerEvent) {
 		if (!this.#state) return;
 
 		let increment = getIncrement(e);
@@ -31,7 +34,7 @@ class Counter extends HTMLElement {
 	}
 }
 
-function getStateFromDOM(shadowRoot: ShadowRoot) {
+function getStateFromDOM(shadowRoot: ShadowRoot): State | undefined {
 	let slot = shadowRoot.querySelector("slot");
 	if (slot)
 		for (let el of slot.assignedNodes()) {

package/examples/form_associated/text_input.js

@@ -1,7 +1,7 @@
-import { Wc, Events } from "wctk";
 /*
     Form associated custom element.
 */
+import { Wc, Events } from "wctk";
 export class TextInput extends HTMLElement {
     static formAssociated = true;
     #wc = new Wc({ host: this });
@@ -9,7 +9,9 @@ export class TextInput extends HTMLElement {
         host: this,
         target: this.#wc.shadowRoot,
         connected: true,
-        callbacks: [["change", this.#changeHandler]],
+        callbacks: {
+            change: this.#changeHandler,
+        },
     });
     #changeHandler(event) {
         let { target } = event;

package/examples/form_associated/text_input.ts

@@ -1,8 +1,9 @@
-import { Wc, Events } from "wctk";
-
 /*
 	Form associated custom element.
 */
+
+import { Wc, Events } from "wctk";
+
 export class TextInput extends HTMLElement {
 	static formAssociated = true;
 
@@ -11,10 +12,12 @@ export class TextInput extends HTMLElement {
 		host: this,
 		target: this.#wc.shadowRoot,
 		connected: true,
-		callbacks: [["change", this.#changeHandler]],
+		callbacks: {
+			change: this.#changeHandler,
+		},
 	});
 
-	#changeHandler(event: Event) {
+	#changeHandler(event: Event): void {
 		let { target } = event;
 		if (target instanceof HTMLInputElement)
 			this.#wc.setFormValue(target.value);

package/examples/stopwatch/mod.js

@@ -1,8 +1,23 @@
 import { Stopwatch } from "./stopwatch.js";
 customElements.define("stopwatch-wc", Stopwatch);
 const stopwatch = document.querySelector("stopwatch-wc");
+let receipt;
+function draw(timestamp) {
+    if (!stopwatch)
+        return;
+    receipt = requestAnimationFrame(draw);
+    stopwatch.update(timestamp);
+}
+function start() {
+    if (!stopwatch)
+        return;
+    requestAnimationFrame(draw);
+}
+function pause() {
+    cancelAnimationFrame(receipt);
+}
 document.addEventListener("click", function (e) {
     if (stopwatch && e.target instanceof HTMLButtonElement) {
-        e.target.hasAttribute("start") ? stopwatch.start() : stopwatch.pause();
+        e.target.hasAttribute("start") ? start() : pause();
     }
 });

package/examples/stopwatch/mod.ts

@@ -1,11 +1,27 @@
 import { Stopwatch } from "./stopwatch.js";
 
 customElements.define("stopwatch-wc", Stopwatch);
-
 const stopwatch = document.querySelector<Stopwatch>("stopwatch-wc");
 
+let receipt: number;
+function draw(timestamp: DOMHighResTimeStamp) {
+	if (!stopwatch) return;
+
+	receipt = requestAnimationFrame(draw);
+	stopwatch.update(timestamp);
+}
+
+function start() {
+	if (!stopwatch) return;
+	requestAnimationFrame(draw);
+}
+
+function pause() {
+	cancelAnimationFrame(receipt);
+}
+
 document.addEventListener("click", function (e: Event) {
 	if (stopwatch && e.target instanceof HTMLButtonElement) {
-		e.target.hasAttribute("start") ? stopwatch.start() : stopwatch.pause();
+		e.target.hasAttribute("start") ? start() : pause();
 	}
 });

package/examples/stopwatch/stopwatch.js

@@ -1,35 +1,23 @@
-import { Wc, Microtask } from "wctk";
 /*
     Custom Element with performant and "asynchronous" renders
     on the microtask queue.
 */
-export class Stopwatch extends HTMLElement {
+import { Wc, Microtask } from "wctk";
+class Stopwatch extends HTMLElement {
     #wc = new Wc({ host: this });
     #rc = new Microtask({ host: this, callback: this.#render });
-    #boundUpdate = this.#update.bind(this);
     #state = getStateFromShadowDOM(this.#wc.shadowRoot);
-    #render() {
-        if (this.#state)
-            this.#state.el.textContent = this.#state.count.toFixed(2);
-    }
-    #update(timestamp) {
-        if (!this.#state)
+    update(timestamp) {
+        if (!this.#state || timestamp < this.#state.prevTimestamp)
             return;
-        this.#state.receipt = requestAnimationFrame(this.#boundUpdate);
         this.#state.count += (timestamp - this.#state.prevTimestamp) * 0.001;
         this.#state.prevTimestamp = timestamp;
         // push render to microtask queue
         this.#rc.queue();
     }
-    start() {
-        if (!this.#state || this.#state?.receipt)
-            return;
-        this.#state.receipt = requestAnimationFrame(this.#boundUpdate);
-        this.#state.prevTimestamp = performance.now();
-    }
-    pause() {
-        if (this.#state && this.#state.receipt)
-            this.#state.receipt = cancelAnimationFrame(this.#state.receipt);
+    #render() {
+        if (this.#state)
+            this.#state.el.textContent = this.#state.count.toFixed(2);
     }
 }
 function getStateFromShadowDOM(shadowRoot) {
@@ -43,3 +31,4 @@ function getStateFromShadowDOM(shadowRoot) {
         };
     }
 }
+export { Stopwatch };

package/examples/stopwatch/stopwatch.ts

@@ -1,4 +1,9 @@
-import { Bind, Wc, Microtask } from "wctk";
+/*
+	Custom Element with performant and "asynchronous" renders
+	on the microtask queue.
+*/
+
+import { Wc, Microtask } from "wctk";
 
 interface State {
 	receipt: number | void;
@@ -7,26 +12,14 @@ interface State {
 	el: HTMLSpanElement;
 }
 
-/*
-	Custom Element with performant and "asynchronous" renders
-	on the microtask queue.
-*/
-export class Stopwatch extends HTMLElement {
+class Stopwatch extends HTMLElement {
 	#wc = new Wc({ host: this });
 	#rc = new Microtask({ host: this, callback: this.#render });
 
-	#boundUpdate = this.#update.bind(this);
 	#state?: State = getStateFromShadowDOM(this.#wc.shadowRoot);
 
-	#render() {
-		if (this.#state)
-			this.#state.el.textContent = this.#state.count.toFixed(2);
-	}
-
-	#update(timestamp: DOMHighResTimeStamp) {
-		if (!this.#state) return;
-
-		this.#state.receipt = requestAnimationFrame(this.#boundUpdate);
+	update(timestamp: DOMHighResTimeStamp) {
+		if (!this.#state || timestamp < this.#state.prevTimestamp) return;
 
 		this.#state.count += (timestamp - this.#state.prevTimestamp) * 0.001;
 		this.#state.prevTimestamp = timestamp;
@@ -35,16 +28,9 @@ export class Stopwatch extends HTMLElement {
 		this.#rc.queue();
 	}
 
-	start() {
-		if (!this.#state || this.#state?.receipt) return;
-
-		this.#state.receipt = requestAnimationFrame(this.#boundUpdate);
-		this.#state.prevTimestamp = performance.now();
-	}
-
-	pause() {
-		if (this.#state && this.#state.receipt)
-			this.#state.receipt = cancelAnimationFrame(this.#state.receipt);
+	#render() {
+		if (this.#state)
+			this.#state.el.textContent = this.#state.count.toFixed(2);
 	}
 }
 
@@ -59,3 +45,5 @@ function getStateFromShadowDOM(shadowRoot: ShadowRoot): State | undefined {
 		};
 	}
 }
+
+export { Stopwatch };

package/package.json

@@ -4,9 +4,9 @@
 	"main": "dist/mod.js",
 	"description": "A bare-metal web component toolkit",
 	"license": "BSD-3-Clause",
-	"version": "0.1.0",
+	"version": "0.1.1",
 	"scripts": {
-		"prepare": "npm run build && npm run build:examples",
+		"prepare": "npm run build",
 		"build": "npx tsc --project ./src",
 		"build:examples": "npx tsc --project ./examples",
 		"format": "prettier --write ./"

package/src/events.ts

@@ -1,20 +1,38 @@
-export type Callbacks = Array<[string, EventListenerOrEventListenerObject]>;
+interface GenericEventListener<E> {
+	(evt: E): void;
+}
 
-export interface EventsInterface {
-	connect(): void;
-	disconnect(): void;
+interface GenericEventListenerObject<E> {
+	handleEvent(object: E): void;
 }
 
-export interface EventElementInterface {
-	addEventListener: EventTarget["addEventListener"];
-	removeEventListener: EventTarget["removeEventListener"];
+type GenericCallbacks<E> =
+	| GenericEventListener<E>
+	| GenericEventListenerObject<E>;
+
+type EventMap = Partial<{
+	[Property in keyof GlobalEventHandlersEventMap]: GenericCallbacks<
+		GlobalEventHandlersEventMap[Property]
+	>;
+}>;
+
+type Callbacks = Array<[string, EventListenerOrEventListenerObject]>;
+
+interface EventElementInterface {
+	addEventListener: Element["addEventListener"];
+	removeEventListener: Element["removeEventListener"];
 }
 
 export interface EventParamsInterface {
-	host: EventElementInterface;
+	callbacks: EventMap;
 	connected?: boolean;
+	host: EventElementInterface;
 	target?: EventElementInterface;
-	callbacks: Callbacks;
+}
+
+export interface EventsInterface {
+	connect(): void;
+	disconnect(): void;
 }
 
 export class Events implements EventsInterface {
@@ -50,9 +68,9 @@ export class Events implements EventsInterface {
 	}
 }
 
-function getBoundCallbacks(host: Object, callbacks: Callbacks): Callbacks {
+function getBoundCallbacks(host: Object, callbacks: EventMap): Callbacks {
 	let boundCallbacks: Callbacks = [];
-	for (let [name, callback] of callbacks) {
+	for (let [name, callback] of Object.entries(callbacks)) {
 		if (
 			callback instanceof Function &&
 			!callback.hasOwnProperty("prototype")
@@ -60,7 +78,10 @@ function getBoundCallbacks(host: Object, callbacks: Callbacks): Callbacks {
 			callback = callback.bind(host);
 		}
 
-		boundCallbacks.push([name, callback]);
+		boundCallbacks.push([
+			name,
+			callback as EventListenerOrEventListenerObject,
+		]);
 	}
 
 	return boundCallbacks;

package/src/wc.ts

@@ -32,21 +32,22 @@ export class Wc implements WcInterface {
 	#shadowRoot: ShadowRoot;
 
 	constructor(params: WcParamsInterface) {
-		let { host, shadowRootInit, adoptedStyleSheets, formValue, formState } =
-			params;
+		let { adoptedStyleSheets, host, formState, formValue, shadowRootInit } = params;
+
 		this.#internals = host.attachInternals();
 
 		let { shadowRoot } = this.#internals;
-		if (!shadowRoot) {
+		if (shadowRoot) {
+			this.#shadowRoot = shadowRoot;
+		} else {
 			this.#declarative = false;
-			shadowRoot = host.attachShadow(
+			this.#shadowRoot = host.attachShadow(
 				shadowRootInit ?? shadowRootInitFallback,
 			);
 		}
-		this.#shadowRoot = shadowRoot;
 
-		if (formValue) this.setFormValue(formValue, formState);
 		if (adoptedStyleSheets) this.adoptedStyleSheets = adoptedStyleSheets;
+		if (formValue) this.setFormValue(formValue, formState);
 	}
 
 	get declarative(): boolean {