@w-lfpup/wctk 0.2.3 → 0.2.5

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

@@ -1,11 +1,14 @@
 # Wctk-JS
 
-An SSR friendly (w)eb(c)omponent (t)ool (k)it without dependencies.
+An SSR friendly webcomponent 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)
+[![Tests](https://github.com/w-lfpup/wctk-js/actions/workflows/tests.yml/badge.svg)](https://github.com/w-lfpup/wctk-js/actions/workflows/tests.yml)
 
 ## About
 
+The `wctk` is a collection of bare-metal facades over web 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).
@@ -17,25 +20,23 @@ Four (4) controllers help developers:
 - listen for [events](./docs/events.md)
 - cache selector [queries](./docs/query_selector.md)
 
-Controllers are flexible and not restricted to webcomponents. The can be used on any `HTMLElement`.
-
 ## Install
 
-Install directly from github.
+Install from npm:
 
 ```bash
-npm install --save-dev https://github.com/w-lfpup/wctk-js/
+npm install --save-dev @w-lfpup/wctk
 ```
 
-Install with npm.
+Install directly from github:
 
 ```bash
-npm install --save-dev @w-lfpup/wctk
+npm install --save-dev https://github.com/w-lfpup/wctk-js/
 ```
 
 ## Create a webcomponent
 
-Add a `Wc` controller to a custom element with only one line
+Add a `Wc` controller to a custom element.
 
 ```ts
 import { Wc } from "wctk";
@@ -59,15 +60,12 @@ 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
 can pick up what the HTML threw down with interactive SSR friendly webcomponents.
 
-Templating is not provided. You can use lit-html or react or vue. But first consider the majority
+Templating is not provided. But before you reach for lit-html or vue or react, consider the majority
 of components only have a few moving pieces. Do you really need templating for that custom button?
 Do you really need a flux-pattern for that checkbox?
 

package/dist/events.d.ts

@@ -5,7 +5,7 @@ interface GenericEventListenerObject<E extends Event> extends EventListenerObjec
     handleEvent(object: E): void;
 }
 type GenericCallbacks<E extends Event> = GenericEventListener<E> | GenericEventListenerObject<E>;
-type EventMaps = DocumentEventMap & GlobalEventHandlersEventMap & ElementEventMap;
+type EventMaps = DocumentEventMap & HTMLElementEventMap;
 type ListenerMap = Partial<{
     [Property in keyof EventMaps]: GenericCallbacks<EventMaps[Property]>;
 }> | Record<string, EventListenerOrEventListenerObject>;
@@ -14,8 +14,8 @@ interface EventElementInterface {
     removeEventListener: Element["removeEventListener"];
 }
 export interface EventParamsInterface {
-    listeners: ListenerMap;
     connected?: boolean;
+    listeners: ListenerMap;
     target: EventElementInterface;
 }
 export interface EventsInterface {

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.3",
+	"version": "0.2.5",
 	"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

@@ -12,9 +12,7 @@ type GenericCallbacks<E extends Event> =
 	| GenericEventListener<E>
 	| GenericEventListenerObject<E>;
 
-type EventMaps = DocumentEventMap &
-	GlobalEventHandlersEventMap &
-	ElementEventMap;
+type EventMaps = DocumentEventMap & HTMLElementEventMap;
 
 type ListenerMap =
 	| Partial<{
@@ -32,8 +30,8 @@ interface EventElementInterface {
 }
 
 export interface EventParamsInterface {
-	listeners: ListenerMap;
 	connected?: boolean;
+	listeners: ListenerMap;
 	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/.github/workflows/browsers.macos.json

@@ -1,51 +0,0 @@
-{
-	"jackrabbit_url": "http://127.0.0.1:4000",
-	"runAsynchronusly": false,
-	"webdrivers": [
-		{
-			"command": "safaridriver -p 4001",
-			"title": "Safari",
-			"timeout_ms": 30000,
-			"webdriver_url": "http://localhost:4001"
-		},
-		{
-			"command": "$GECKOWEBDRIVER/geckodriver -p 4001",
-			"title": "Firefox",
-			"timeout_ms": 30000,
-			"webdriver_url": "http://127.0.0.1:4001",
-			"capabilities": {
-				"alwaysMatch": {
-					"moz:firefoxOptions": {
-						"args": ["-headless"]
-					}
-				}
-			}
-		},
-		{
-			"command": "$CHROMEWEBDRIVER/chromedriver --port=4001",
-			"title": "Chrome",
-			"timeout_ms": 30000,
-			"webdriver_url": "http://localhost:4001",
-			"capabilities": {
-				"alwaysMatch": {
-					"goog:chromeOptions": {
-						"args": ["--headless"]
-					}
-				}
-			}
-		},
-		{
-			"command": "$EDGEWEBDRIVER/msedgedriver --port=4001",
-			"title": "Edge",
-			"timeout_ms": 30000,
-			"webdriver_url": "http://localhost:4001",
-			"capabilities": {
-				"alwaysMatch": {
-					"ms:edgeOptions": {
-						"args": ["--headless"]
-					}
-				}
-			}
-		}
-	]
-}

package/.github/workflows/browsers.ubuntu.json

@@ -1,37 +0,0 @@
-{
-	"jackrabbit_url": "http://127.0.0.1:4000",
-	"runAsynchronusly": false,
-	"webdrivers": [
-		{
-			"title": "Firefox",
-			"command": "$GECKOWEBDRIVER/geckodriver -p 4001",
-			"timeout_ms": 30000,
-			"webdriver_url": "http://localhost:4001",
-			"capabilities": {
-				"alwaysMatch": {
-					"moz:firefoxOptions": {
-						"args": ["-headless"]
-					}
-				}
-			}
-		},
-		{
-			"title": "Chrome",
-			"command": "$CHROMEWEBDRIVER/chromedriver --port=4005",
-			"timeout_ms": 30000,
-			"webdriver_url": "http://localhost:4005",
-			"capabilities": {
-				"alwaysMatch": {
-					"goog:chromeOptions": {
-						"args": [
-							"--headless",
-							"--disbale-gpu",
-							"--disable-dev-shm-usage",
-							"--start-maximized"
-						]
-					}
-				}
-			}
-		}
-	]
-}

package/.github/workflows/builds.yml

@@ -1,27 +0,0 @@
-name: Tests
-
-on:
-    push:
-        branches: ["main"]
-    pull_request:
-        branches: ["main"]
-
-jobs:
-    build_and_test:
-        runs-on: ubuntu-latest
-        steps:
-            - uses: actions/checkout@v6
-            - uses: actions/setup-node@v6
-            - name: Install
-              run: npm ci
-            - name: Test browsers
-              run: npx jackrabbit_webdriver .github/workflows/browsers.ubuntu.json tests/dist/mod.js
-    build_and_test_macos:
-        runs-on: macos-latest
-        steps:
-            - uses: actions/checkout@v6
-            - uses: actions/setup-node@v6
-            - name: Install
-              run: npm ci
-            - name: Test browsers
-              run: npx jackrabbit_webdriver .github/workflows/browsers.macos.json tests/dist/mod.js

package/.prettierignore

@@ -1,5 +0,0 @@
-dist/
-
-*.html
-*.js
-package-lock.json

package/.prettierrc

@@ -1,5 +0,0 @@
-{
-	"trailingComma": "all",
-	"useTabs": true,
-	"tabWidth": 4
-}

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>