@w-lfpup/wctk 0.2.2 → 0.2.4

package/LICENSE

@@ -1,6 +1,6 @@
 BSD 3-Clause License
 
-Copyright (c) 2024, Taylor Vann
+Copyright (c) 2024, Brian Taylor Vann
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions are met:

package/README.md

@@ -6,6 +6,9 @@ An SSR friendly (w)eb(c)omponent (t)ool (k)it without dependencies.
 
 ## About
 
+The `wctk` is a collection of bare-metal facades over vanilla browser apis. They provide the basics for
+events, reactivity, and forms.
+
 There are no base classes, decorators, or mixins.
 
 All features are compositional and designed for SSR and [declarative shadow dom](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM#declaratively_with_html).
@@ -59,9 +62,6 @@ The following examples demonstrate several common SSR use cases:
 
 ## Design Goals
 
-The `wctk` is a collection of bare-metal facades over vanilla browser apis. They provide the basics for
-events, reactivity, and forms.
-
 If you know vanilla javascript and the DOM you are good to go.
 
 The `wctk` is designed with SSR and declarative shadow dom in mind. Developers

package/dist/events.d.ts

@@ -1,19 +1,20 @@
 interface GenericEventListener<E extends Event> {
     (evt: E): void;
 }
-interface GenericEventListenerObject<E extends Event> {
+interface GenericEventListenerObject<E extends Event> extends EventListenerObject {
     handleEvent(object: E): void;
 }
 type GenericCallbacks<E extends Event> = GenericEventListener<E> | GenericEventListenerObject<E>;
-type EventMap = Partial<{
-    [Property in keyof GlobalEventHandlersEventMap]: GenericCallbacks<GlobalEventHandlersEventMap[Property]>;
+type EventMaps = DocumentEventMap & GlobalEventHandlersEventMap & ElementEventMap;
+type ListenerMap = Partial<{
+    [Property in keyof EventMaps]: GenericCallbacks<EventMaps[Property]>;
 }> | Record<string, EventListenerOrEventListenerObject>;
 interface EventElementInterface {
     addEventListener: Element["addEventListener"];
     removeEventListener: Element["removeEventListener"];
 }
 export interface EventParamsInterface {
-    listeners: EventMap;
+    listeners: ListenerMap;
     connected?: boolean;
     target: EventElementInterface;
 }

package/dist/microtask.d.ts

@@ -1,10 +1,12 @@
 export interface MicrotaskInterface {
     queue(): void;
 }
-type Callback = () => void;
+interface Callback {
+    (): void;
+}
 export declare class Microtask implements MicrotaskInterface {
     #private;
-    constructor(callback: Callback);
     queue: () => void;
+    constructor(callback: Callback);
 }
 export {};

package/dist/microtask.js

@@ -1,17 +1,17 @@
 export class Microtask {
     #queued = false;
     #callback;
+    #microtask = this.#unboundMicrotask.bind(this);
+    queue = this.#queue.bind(this);
     constructor(callback) {
         this.#callback = callback;
     }
-    queue = this.#queue.bind(this);
     #queue() {
         if (this.#queued)
             return;
         this.#queued = true;
         window.queueMicrotask(this.#microtask);
     }
-    #microtask = this.#unboundMicrotask.bind(this);
     #unboundMicrotask() {
         this.#queued = false;
         this.#callback();

package/dist/query_selector.js

@@ -13,11 +13,11 @@ export class QuerySelector {
         return query;
     }
     querySelectorAll(selector) {
-        let results = this.#queryAlls.get(selector);
-        if (results)
-            return results;
-        let query = Array.from(this.#parentNode.querySelectorAll(selector));
-        this.#queryAlls.set(selector, query);
+        let query = this.#queryAlls.get(selector);
+        if (!query) {
+            query = Array.from(this.#parentNode.querySelectorAll(selector));
+            this.#queryAlls.set(selector, query);
+        }
         return query;
     }
     deleteAll() {

package/dist/wc.js

@@ -8,13 +8,10 @@ export class Wc {
     constructor(params) {
         let { adoptedStyleSheets, host, formState, formValue, shadowRootInit } = params;
         this.#internals = host.attachInternals();
-        if (this.#internals.shadowRoot) {
-            this.#declarative = true;
-            this.#shadowRoot = this.#internals.shadowRoot;
-        }
-        else {
-            this.#shadowRoot = host.attachShadow(shadowRootInit ?? shadowRootInitFallback);
-        }
+        this.#declarative = null !== this.#internals.shadowRoot;
+        this.#shadowRoot =
+            this.#internals.shadowRoot ??
+                host.attachShadow(shadowRootInit ?? shadowRootInitFallback);
         this.adoptedStyleSheets = adoptedStyleSheets ?? [];
         if (formValue)
             this.setFormValue(formValue, formState);

package/package.json

@@ -4,7 +4,7 @@
 	"main": "dist/mod.js",
 	"description": "A bare-metal webcomponent toolkit",
 	"license": "BSD-3-Clause",
-	"version": "0.2.2",
+	"version": "0.2.4",
 	"scripts": {
 		"prepare": "npm run build",
 		"build": "npm run build:src && npm run build:tests && npm run build:examples",
@@ -15,13 +15,13 @@
 		"test:browsers": "npx jackrabbit_webdriver jr.json tests/dist/mod.js",
 		"format": "prettier --write ./"
 	},
-	"devDependencies": {
-		"@w-lfpup/jackrabbit": "^0.3.2",
-		"prettier": "^3.8.3",
-		"typescript": "^6.0.2"
-	},
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/w-lfpup/wctk-js.git"
+	},
+	"devDependencies": {
+		"@w-lfpup/jackrabbit": "^0.3.3",
+		"prettier": "^3.8.4",
+		"typescript": "^6.0.3"
 	}
 }

package/src/events.ts

@@ -2,7 +2,9 @@ interface GenericEventListener<E extends Event> {
 	(evt: E): void;
 }
 
-interface GenericEventListenerObject<E extends Event> {
+interface GenericEventListenerObject<
+	E extends Event,
+> extends EventListenerObject {
 	handleEvent(object: E): void;
 }
 
@@ -10,10 +12,14 @@ type GenericCallbacks<E extends Event> =
 	| GenericEventListener<E>
 	| GenericEventListenerObject<E>;
 
-type EventMap =
+type EventMaps = DocumentEventMap &
+	GlobalEventHandlersEventMap &
+	ElementEventMap;
+
+type ListenerMap =
 	| Partial<{
-			[Property in keyof GlobalEventHandlersEventMap]: GenericCallbacks<
-				GlobalEventHandlersEventMap[Property]
+			[Property in keyof EventMaps]: GenericCallbacks<
+				EventMaps[Property]
 			>;
 	  }>
 	| Record<string, EventListenerOrEventListenerObject>;
@@ -26,7 +32,7 @@ interface EventElementInterface {
 }
 
 export interface EventParamsInterface {
-	listeners: EventMap;
+	listeners: ListenerMap;
 	connected?: boolean;
 	target: EventElementInterface;
 }

package/src/microtask.ts

@@ -2,17 +2,20 @@ export interface MicrotaskInterface {
 	queue(): void;
 }
 
-type Callback = () => void;
+interface Callback {
+	(): void;
+}
 
 export class Microtask implements MicrotaskInterface {
 	#queued = false;
 	#callback: Callback;
+	#microtask = this.#unboundMicrotask.bind(this);
+	queue = this.#queue.bind(this);
 
 	constructor(callback: Callback) {
 		this.#callback = callback;
 	}
 
-	queue = this.#queue.bind(this);
 	#queue() {
 		if (this.#queued) return;
 		this.#queued = true;
@@ -20,7 +23,6 @@ export class Microtask implements MicrotaskInterface {
 		window.queueMicrotask(this.#microtask);
 	}
 
-	#microtask = this.#unboundMicrotask.bind(this);
 	#unboundMicrotask() {
 		this.#queued = false;
 		this.#callback();

package/src/query_selector.ts

@@ -18,15 +18,17 @@ export class QuerySelector implements QuerySelectorInterface {
 
 		let query = this.#parentNode.querySelector(selector) ?? undefined;
 		this.#queries.set(selector, query);
+
 		return query;
 	}
 
 	querySelectorAll(selector: string): Element[] {
-		let results = this.#queryAlls.get(selector);
-		if (results) return results;
+		let query = this.#queryAlls.get(selector);
+		if (!query) {
+			query = Array.from(this.#parentNode.querySelectorAll(selector));
+			this.#queryAlls.set(selector, query);
+		}
 
-		let query = Array.from(this.#parentNode.querySelectorAll(selector));
-		this.#queryAlls.set(selector, query);
 		return query;
 	}
 

package/src/wc.ts

@@ -36,15 +36,10 @@ export class Wc implements WcInterface {
 			params;
 
 		this.#internals = host.attachInternals();
-
-		if (this.#internals.shadowRoot) {
-			this.#declarative = true;
-			this.#shadowRoot = this.#internals.shadowRoot;
-		} else {
-			this.#shadowRoot = host.attachShadow(
-				shadowRootInit ?? shadowRootInitFallback,
-			);
-		}
+		this.#declarative = null !== this.#internals.shadowRoot;
+		this.#shadowRoot =
+			this.#internals.shadowRoot ??
+			host.attachShadow(shadowRootInit ?? shadowRootInitFallback);
 
 		this.adoptedStyleSheets = adoptedStyleSheets ?? [];
 		if (formValue) this.setFormValue(formValue, formState);

package/docs/events.md

@@ -1,93 +0,0 @@
-# Events Controller
-
-Add event listeners to webcomponents.
-
-## How to use
-
-Add an `Events` controller to a webcomponent. Use a params object on instantiation.
-
-### Params
-
-An Events `params` object has three properties:
-
-```ts
-interface EventParams {
-	connected?: boolean;
-	listeners: Record<string, EventListenerOrEventListenerObject>;
-	target: EventTarget;
-}
-```
-
-The `Events` controller adds event listeners on a `target` node.
-
-The `target` node can be a shadowRoot, a document, or the custom element itself.
-
-### Controller
-
-Here is an example of using the `Events` controller.
-
-```ts
-import { Events, Wc } from "wctk";
-
-class MyElement extends HTMLElement {
-	#wc = new Wc({ this: host });
-
-	#ec = new Events({
-		target: this.#wc.shadowRoot,
-		listeners: {
-			click: this.#onClick.bind(this),
-			keydown: this.#onKeyDown.bind(this),
-		},
-	});
-
-	#onClick(e: PointerEvent) {
-		// do something with pointer events here!
-	}
-
-	#onKeyDown(e: KeyboardEvent) {
-		// do something with key events here!
-	}
-
-	// lifecycle method
-	connectedCallback() {
-		this.#ec.connect();
-	}
-
-	// lifecycle method
-	disconnectedCallback() {
-		this.#ec.disconnect();
-	}
-}
-```
-
-### Shortcut life-cycle methods
-
-In the example below, the `connected` property is set to true and listeners are immediately added to the `target`.
-
-```ts
-import { Events, Wc } from "wctk";
-
-class MyElement extends HTMLElement {
-	#wc = new Wc({ this: host });
-	#ec = new Events({
-		connected: true,
-		target: this.#wc.shadowRoot,
-		listeners: {
-			click: this.#onClick.bind(this),
-			keydown: this.#onKeyDown.bind(this),
-		},
-	});
-
-	#onClick(e: PointerEvent) {
-		// do something with pointer events here!
-	}
-
-	#onKeyDown(e: KeyEvent) {
-		// do something with key events here!
-	}
-}
-```
-
-### More complex interactions
-
-If your component requires more complex declarative interactions, consider [superaction](https://github.com/w-lfpup/superaction-js/)

package/docs/microtask.md

@@ -1,32 +0,0 @@
-# Microtask Controller
-
-Add callbacks to the `microtask queue`.
-
-## How to use
-
-Add a `Microtask` controller to a webcomponent. Provide a callback.
-
-Call `Microtask.queue()` to push the callback to the microtask queue.
-
-In the example below, a `Microtask` controller queues a render when the `width` attribute changes.
-
-```ts
-import { Microtask } from "wctk";
-
-class MyElement extends HTMLElement {
-	static observedAttributes = ["width"];
-
-	#rc = new Microtask(this.#render.bind(this));
-
-	#render() {
-		// update DOM here!
-	}
-
-	// lifecycle method
-	attributeChangedCallback() {
-		this.#rc.queue();
-	}
-}
-```
-
-The `Microtask.queue()` method can be called multiple times per event loop but the callback will only be called _once_ during the microtaskqueue phase of the event-loop.

package/docs/query_selector.md

@@ -1,37 +0,0 @@
-# QuerySelector Controller
-
-Lazily map selector queries.
-
-## How to use
-
-Add a `QuerySelector` controller to a webcomponent.
-
-```html
-<my-element>
-	<template shadowrootmode="closed">
-		<span greeting>UwU</span>
-	</template>
-</my-element>
-```
-
-Every query is cached. Call `<QuerySelector>.deleteAll()` to reset the cache (helpful after a new render).
-
-```ts
-import { QuerySelector } from "wctk";
-
-class MyElement extends HTMLElement {
-	#wc = new Wc({ host: this });
-	#qc = new QuerySelector(this.#wc.shadowRoot);
-
-	showcaseApi() {
-		// first Element or undefined
-		let greeting = this.#qc.querySelector("[greeting]");
-
-		// Element[]
-		let greetings = this.#qc.querySelectorAll("[greeting]");
-
-		// create new cache
-		this.#qc.deleteAll();
-	}
-}
-```

package/docs/wc.md

@@ -1,55 +0,0 @@
-# Wc Controller
-
-Build a webcomponent.
-
-## How to use
-
-Add a `Wc` controller to a custom element:
-
-```ts
-import { Wc } from "wctk";
-
-class MyElement extends HTMLElement {
-	#wc = new Wc({ host: this });
-}
-```
-
-## Adopted stylesheets and form values
-
-The `Wc` controller interfaces with core web componet APIs like adopted stylesheets and form values.
-
-```ts
-class MyElement extends HTMLElement {
-	#wc = new Wc({
-		host: this,
-		// https://developer.mozilla.org/en-US/docs/Web/API/Element/attachShadow#options
-		shadowRootInit: { mode: "open" },
-		adoptedStyleSheets: [],
-		formValue: "^_^",
-		formState: ":3",
-	});
-
-	showcaseApi() {
-		// true if declarative shadow dom is present
-		this.#wc.delcarative;
-
-		// https://developer.mozilla.org/en-US/docs/Web/API/ShadowRoot
-		this.#wc.shadowRoot;
-
-		// https://developer.mozilla.org/en-US/docs/Web/API/ShadowRoot/adoptedStyleSheets
-		this.#wc.adopedStylesheets;
-
-		// https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/setFormValue
-		this.#wc.setFormValue(value, state);
-
-		// https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/checkValidity
-		this.#wc.checkValidity();
-
-		// https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/reportValidity
-		this.#wc.reportValidity();
-
-		// https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/setValidity
-		this.#wc.setValidity(flags, message);
-	}
-}
-```

package/examples/counter/index.html

@@ -1,30 +0,0 @@
-<!DOCTYPE html>
-<html lang="en-us">
-	<head>
-		<meta charset=utf-8>
-		<meta name=viewport content="width=device-width, initial-scale=1">
-		<script type="importmap">
-			{
-				"imports": {
-					"wctk": "../../dist/mod.js"
-				}
-			}
-		</script>
-		<script src="./mod.js" type=module></script>
-	</head>
-	<body>
-		<main>
-			<!-- webcomponent -->
-			<counter-wc>
-				<template shadowrootmode="closed">
-					<button decrease>-</button>
-					<slot></slot>
-					<button increase>+</button>				
-				</template>
-
-				<!-- DOM content -->
-				<span>42</span>
-			</counter-wc>
-		</main>
-	</body>
-</html>

package/examples/counter/mod.js

@@ -1,37 +0,0 @@
-import { Wc, Events } from "wctk";
-class Counter extends HTMLElement {
-    #wc = new Wc({ host: this });
-    #ev = new Events({
-        connected: true,
-        target: this.#wc.shadowRoot,
-        listeners: {
-            click: this.#clickHandler.bind(this),
-        },
-    });
-    #state = getStateFromDOM(this.#wc.shadowRoot);
-    #clickHandler(e) {
-        let increment = getIncrement(e);
-        if (increment) {
-            this.#state.count += increment;
-            let el = this.#state.el;
-            if (el)
-                el.textContent = this.#state.count.toString();
-        }
-    }
-}
-function getStateFromDOM(shadowRoot) {
-    let slot = shadowRoot.querySelector("slot");
-    let el;
-    if (slot)
-        for (let slotted of slot.assignedNodes()) {
-            if (slotted instanceof HTMLSpanElement)
-                el = slotted;
-        }
-    return { el, count: parseInt(el?.textContent ?? "0") };
-}
-function getIncrement(e) {
-    if (e.target instanceof HTMLButtonElement) {
-        return e.target.hasAttribute("increase") ? 1 : -1;
-    }
-}
-customElements.define("counter-wc", Counter);

package/examples/counter/mod.ts

@@ -1,52 +0,0 @@
-/*
-	Custom Element with state and interactivity.
-*/
-
-import { Wc, Events } from "wctk";
-
-interface State {
-	el: HTMLSpanElement | undefined;
-	count: number;
-}
-
-class Counter extends HTMLElement {
-	#wc = new Wc({ host: this });
-
-	#ev = new Events({
-		connected: true,
-		target: this.#wc.shadowRoot,
-		listeners: {
-			click: this.#clickHandler.bind(this),
-		},
-	});
-
-	#state: State = getStateFromDOM(this.#wc.shadowRoot);
-
-	#clickHandler(e: PointerEvent) {
-		let increment = getIncrement(e);
-		if (increment) {
-			this.#state.count += increment;
-			let el = this.#state.el;
-			if (el) el.textContent = this.#state.count.toString();
-		}
-	}
-}
-
-function getStateFromDOM(shadowRoot: ShadowRoot): State {
-	let slot = shadowRoot.querySelector("slot");
-	let el: HTMLSpanElement | undefined;
-	if (slot)
-		for (let slotted of slot.assignedNodes()) {
-			if (slotted instanceof HTMLSpanElement) el = slotted;
-		}
-
-	return { el, count: parseInt(el?.textContent ?? "0") };
-}
-
-function getIncrement(e: Event) {
-	if (e.target instanceof HTMLButtonElement) {
-		return e.target.hasAttribute("increase") ? 1 : -1;
-	}
-}
-
-customElements.define("counter-wc", Counter);

package/examples/form_associated/index.html

@@ -1,31 +0,0 @@
-<!DOCTYPE html>
-<html lang="en-us">
-	<head>
-		<meta charset=utf-8>
-		<meta name=viewport content="width=device-width, initial-scale=1">
-		<script type="importmap">
-			{
-				"imports": {
-					"wctk": "../../dist/mod.js"
-				}
-			}
-		</script>
-		<script src="./mod.js" type=module></script>
-	</head>
-	<body>
-		<main>
-			<form>
-				<!-- html component input -->
-				<input name="html_element">
-				<!-- custom element input -->
-				<text-input name="web_component">
-					<template shadowrootmode="closed">
-						<input>
-					</template>
-				</text-input>
-				<button type="submit">submit !</button>
-			</form>
-			<pre results></pre>
-		</main>
-	</body>
-</html>

package/examples/form_associated/mod.js

@@ -1,11 +0,0 @@
-import { TextInput } from "./text_input.js";
-customElements.define("text-input", TextInput);
-const results = document.querySelector("[results]");
-document.addEventListener("submit", function (e) {
-    if (!(e.target instanceof HTMLFormElement))
-        return;
-    e.preventDefault();
-    let formdata = new FormData(e.target);
-    if (results)
-        results.textContent = JSON.stringify(Object.fromEntries(formdata), undefined, " ");
-});

package/examples/form_associated/mod.ts

@@ -1,20 +0,0 @@
-import { TextInput } from "./text_input.js";
-
-customElements.define("text-input", TextInput);
-
-const results = document.querySelector("[results]");
-
-document.addEventListener("submit", function (e: SubmitEvent) {
-	if (!(e.target instanceof HTMLFormElement)) return;
-
-	e.preventDefault();
-
-	let formdata: FormData = new FormData(e.target);
-
-	if (results)
-		results.textContent = JSON.stringify(
-			Object.fromEntries(formdata),
-			undefined,
-			" ",
-		);
-});