@w-lfpup/wctk 0.1.1 → 0.2.2

package/.github/workflows/browsers.macos.json

@@ -0,0 +1,51 @@
+{
+	"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

@@ -0,0 +1,37 @@
+{
+	"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,4 +1,4 @@
-name: Builds
+name: Tests
 
 on:
     push:
@@ -11,8 +11,17 @@ jobs:
         runs-on: ubuntu-latest
         steps:
             - uses: actions/checkout@v6
-            - uses: actions/setup-node@v4
+            - uses: actions/setup-node@v6
             - name: Install
               run: npm ci
-            - name: Format
-              run: npm run format
+            - 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/README.md

@@ -1,37 +1,50 @@
 # Wctk-JS
 
-A web component tool kit without dependencies.
+An SSR friendly (w)eb(c)omponent (t)ool (k)it 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
 
-A half-dozen controllers help developers:
+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).
+
+Four (4) controllers help developers:
 
-- create [shadow dom](./docs/wc.md)
+- manage [shadow dom](./docs/wc.md) and [form values](./docs/wc.md#adopted-stylesheets-and-form-values)
 - render on the [microtask queue](./docs/microtask.md)
 - listen for [events](./docs/events.md)
-- [subscribe](./docs/subscription.md) to external data stores
-- manage [form values](./docs/wc.md#adopted-stylesheets-and-form-values)
-- [query](./docs/query_selector.md) the shadow dom
-- [bind](./docs/bind.md) functions to elements
+- cache selector [queries](./docs/query_selector.md)
 
-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.
-
-There are no base classes, decorators, or mixins.
+Controllers are flexible and not restricted to webcomponents. The can be used on any `HTMLElement`.
 
 ## Install
 
+Install directly from github.
+
+```bash
+npm install --save-dev https://github.com/w-lfpup/wctk-js/
+```
+
 Install with npm.
 
 ```bash
 npm install --save-dev @w-lfpup/wctk
 ```
 
-Or install directly from github.
+## Create a webcomponent
 
-```bash
-npm install --save-dev https://github.com/w-lfpup/wctk-js/
+Add a `Wc` controller to a custom element with only one line
+
+```ts
+import { Wc } from "wctk";
+
+class MyElement extends HTMLElement {
+	#wc = new Wc({ host: this });
+}
+
+customElements.define("my-element", MyElement);
 ```
 
 ## Examples
@@ -44,6 +57,20 @@ The following examples demonstrate several common SSR use cases:
 - a [stopwatch](https://w-lfpup.github.io/wctk-js/examples/stopwatch/) with initial state in the Shadow DOM ([code](https://github.com/w-lfpup/wctk-js/tree/main/examples/stopwatch/)).
 - a [form associated](https://w-lfpup.github.io/wctk-js/examples/form_associated/) element ([code](https://github.com/w-lfpup/wctk-js/tree/main/examples/form_associated/)).
 
+## 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
+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?
+
 ## License
 
 `Wctk-js` is released under the BSD-3 Clause License.

package/dist/events.d.ts

@@ -1,22 +1,21 @@
-interface GenericEventListener<E> {
+interface GenericEventListener<E extends Event> {
     (evt: E): void;
 }
-interface GenericEventListenerObject<E> {
+interface GenericEventListenerObject<E extends Event> {
     handleEvent(object: E): void;
 }
-type GenericCallbacks<E> = GenericEventListener<E> | GenericEventListenerObject<E>;
+type GenericCallbacks<E extends Event> = GenericEventListener<E> | GenericEventListenerObject<E>;
 type EventMap = Partial<{
     [Property in keyof GlobalEventHandlersEventMap]: GenericCallbacks<GlobalEventHandlersEventMap[Property]>;
-}>;
+}> | Record<string, EventListenerOrEventListenerObject>;
 interface EventElementInterface {
     addEventListener: Element["addEventListener"];
     removeEventListener: Element["removeEventListener"];
 }
 export interface EventParamsInterface {
-    callbacks: EventMap;
+    listeners: EventMap;
     connected?: boolean;
-    host: EventElementInterface;
-    target?: EventElementInterface;
+    target: EventElementInterface;
 }
 export interface EventsInterface {
     connect(): void;

package/dist/events.js

@@ -1,11 +1,11 @@
 export class Events {
     #connected = false;
-    #callbacks = [];
+    #listeners = [];
     #target;
     constructor(params) {
-        const { host, target, callbacks, connected } = params;
-        this.#target = target ?? host;
-        this.#callbacks = getBoundCallbacks(host, callbacks);
+        const { target, listeners, connected } = params;
+        this.#target = target;
+        this.#listeners = Object.entries(listeners);
         if (connected)
             this.connect();
     }
@@ -13,30 +13,16 @@ export class Events {
         if (this.#connected)
             return;
         this.#connected = true;
-        for (let [name, callback] of this.#callbacks) {
-            this.#target.addEventListener(name, callback);
+        for (let [name, listener] of this.#listeners) {
+            this.#target.addEventListener(name, listener);
         }
     }
     disconnect() {
         if (!this.#connected)
             return;
         this.#connected = false;
-        for (let [name, callback] of this.#callbacks) {
-            this.#target.removeEventListener(name, callback);
+        for (let [name, listener] of this.#listeners) {
+            this.#target.removeEventListener(name, listener);
         }
     }
 }
-function getBoundCallbacks(host, callbacks) {
-    let boundCallbacks = [];
-    for (let [name, callback] of Object.entries(callbacks)) {
-        if (callback instanceof Function &&
-            !callback.hasOwnProperty("prototype")) {
-            callback = callback.bind(host);
-        }
-        boundCallbacks.push([
-            name,
-            callback,
-        ]);
-    }
-    return boundCallbacks;
-}

package/dist/microtask.d.ts

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

package/dist/microtask.js

@@ -1,23 +1,19 @@
 export class Microtask {
     #queued = false;
     #callback;
-    constructor(params) {
-        let { host, callback } = params;
-        this.queue = this.queue.bind(this);
+    constructor(callback) {
         this.#callback = callback;
-        if (callback instanceof Function &&
-            !callback.hasOwnProperty("prototype")) {
-            this.#callback = callback.bind(host);
-        }
     }
-    queue() {
+    queue = this.#queue.bind(this);
+    #queue() {
         if (this.#queued)
             return;
         this.#queued = true;
-        // could this be a bound function? less function creation
-        queueMicrotask(() => {
-            this.#queued = false;
-            this.#callback();
-        });
+        window.queueMicrotask(this.#microtask);
+    }
+    #microtask = this.#unboundMicrotask.bind(this);
+    #unboundMicrotask() {
+        this.#queued = false;
+        this.#callback();
     }
 }

package/dist/mod.d.ts

@@ -1,6 +1,4 @@
-export * from "./bind.js";
 export * from "./events.js";
 export * from "./microtask.js";
-export * from "./subscription.js";
 export * from "./query_selector.js";
 export * from "./wc.js";

package/dist/mod.js

@@ -1,6 +1,4 @@
-export * from "./bind.js";
 export * from "./events.js";
 export * from "./microtask.js";
-export * from "./subscription.js";
 export * from "./query_selector.js";
 export * from "./wc.js";

package/dist/query_selector.d.ts

@@ -1,14 +1,11 @@
-export interface QuerySelectorParamsInterface {
-    parent: ParentNode;
-}
 export interface QuerySelectorInterface {
     querySelector(name: string): Element | undefined;
-    querySelectorAll(name: string): Element[] | undefined;
+    querySelectorAll(name: string): Element[];
     deleteAll(): void;
 }
 export declare class QuerySelector implements QuerySelectorInterface {
     #private;
-    constructor(params: QuerySelectorParamsInterface);
+    constructor(parentNode: ParentNode);
     querySelector(selector: string): Element | undefined;
     querySelectorAll(selector: string): Element[];
     deleteAll(): void;

package/dist/query_selector.js

@@ -1,25 +1,27 @@
 export class QuerySelector {
     #queries = new Map();
-    #params;
-    constructor(params) {
-        this.#params = params;
+    #queryAlls = new Map();
+    #parentNode;
+    constructor(parentNode) {
+        this.#parentNode = parentNode;
     }
     querySelector(selector) {
-        return getQuery(this.#params, this.#queries, selector)[0];
+        if (this.#queries.has(selector))
+            return this.#queries.get(selector);
+        let query = this.#parentNode.querySelector(selector) ?? undefined;
+        this.#queries.set(selector, query);
+        return query;
     }
     querySelectorAll(selector) {
-        return getQuery(this.#params, this.#queries, selector);
+        let results = this.#queryAlls.get(selector);
+        if (results)
+            return results;
+        let query = Array.from(this.#parentNode.querySelectorAll(selector));
+        this.#queryAlls.set(selector, query);
+        return query;
     }
     deleteAll() {
         this.#queries = new Map();
+        this.#queryAlls = new Map();
     }
 }
-function getQuery(params, queries, selector) {
-    const { parent } = params;
-    let results = queries.get(selector);
-    if (!results) {
-        results = Array.from(parent.querySelectorAll(selector));
-        queries.set(selector, results);
-    }
-    return results;
-}

package/dist/subscription.d.ts

@@ -5,7 +5,6 @@ export interface SubscriptionInterface {
     disconnect(): void;
 }
 export interface SubscriptionParamsInterface<E, A> {
-    host: Object;
     callback: E;
     connected?: boolean;
     subscribe: Subscribe<E, A>;

package/dist/subscription.js

@@ -1,26 +1,18 @@
 export class Subscription {
-    #callback;
+    #params;
     #affect;
-    #subscribe;
-    #unsubscribe;
     constructor(params) {
-        let { host, callback, connected, subscribe, unsubscribe } = params;
-        this.#subscribe = subscribe;
-        this.#unsubscribe = unsubscribe;
-        this.#callback = callback;
-        if (callback instanceof Function &&
-            !callback.hasOwnProperty("prototype")) {
-            this.#callback = callback.bind(host);
-        }
-        if (connected)
+        this.#params = params;
+        if (this.#params.connected)
             this.connect();
     }
     connect() {
+        let { callback, subscribe } = this.#params;
         if (!this.#affect)
-            this.#affect = this.#subscribe(this.#callback);
+            this.#affect = subscribe(callback);
     }
     disconnect() {
         if (this.#affect)
-            this.#unsubscribe(this.#affect);
+            this.#params.unsubscribe(this.#affect);
     }
 }

package/dist/wc.d.ts

@@ -2,13 +2,13 @@ export interface WcElementInterface {
     attachInternals: HTMLElement["attachInternals"];
     attachShadow: Element["attachShadow"];
 }
-type FormDataArguments = Parameters<ElementInternals["setFormValue"]>;
+type FormValueArgs = Parameters<ElementInternals["setFormValue"]>;
 export interface WcParamsInterface {
     host: WcElementInterface;
     adoptedStyleSheets?: CSSStyleSheet[];
     shadowRootInit?: ShadowRootInit;
-    formValue?: FormDataArguments[0];
-    formState?: FormDataArguments[1];
+    formValue?: FormValueArgs[0];
+    formState?: FormValueArgs[1];
 }
 export interface WcInterface {
     readonly declarative: boolean;
@@ -27,7 +27,7 @@ export declare class Wc implements WcInterface {
     set adoptedStyleSheets(stylesheets: CSSStyleSheet[]);
     checkValidity(): boolean;
     reportValidity(): boolean;
-    setFormValue(value: FormDataArguments[0], state?: FormDataArguments[1]): void;
+    setFormValue(value: FormValueArgs[0], state?: FormValueArgs[1]): void;
     setValidity(flags?: ValidityStateFlags, message?: string, anchor?: HTMLElement): void;
 }
 export {};

package/dist/wc.js

@@ -2,22 +2,20 @@ const shadowRootInitFallback = {
     mode: "closed",
 };
 export class Wc {
-    #declarative = true;
+    #declarative = false;
     #internals;
     #shadowRoot;
     constructor(params) {
         let { adoptedStyleSheets, host, formState, formValue, shadowRootInit } = params;
         this.#internals = host.attachInternals();
-        let { shadowRoot } = this.#internals;
-        if (shadowRoot) {
-            this.#shadowRoot = shadowRoot;
+        if (this.#internals.shadowRoot) {
+            this.#declarative = true;
+            this.#shadowRoot = this.#internals.shadowRoot;
         }
         else {
-            this.#declarative = false;
             this.#shadowRoot = host.attachShadow(shadowRootInit ?? shadowRootInitFallback);
         }
-        if (adoptedStyleSheets)
-            this.adoptedStyleSheets = adoptedStyleSheets;
+        this.adoptedStyleSheets = adoptedStyleSheets ?? [];
         if (formValue)
             this.setFormValue(formValue, formState);
     }

package/docs/events.md

@@ -1,32 +1,27 @@
 # Events Controller
 
-Add event listeners to web components.
+Add event listeners to webcomponents.
 
 ## How to use
 
-Add an `Events` controller to a web component. Use a params object on instantiation.
+Add an `Events` controller to a webcomponent. Use a params object on instantiation.
 
 ### Params
 
-An Events `params` object has four properties:
+An Events `params` object has three properties:
 
 ```ts
 interface EventParams {
-	callbacks: Record<string, EventListenerOrEventListenerObject>;
 	connected?: boolean;
-	host: Node;
-	target?: Node;
+	listeners: Record<string, EventListenerOrEventListenerObject>;
+	target: EventTarget;
 }
 ```
 
-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.
+The `Events` controller adds event listeners on a `target` node.
 
 The `target` node can be a shadowRoot, a document, or the custom element itself.
 
-If the `target` property is undefined, the `host` property is used as a fallback.
-
 ### Controller
 
 Here is an example of using the `Events` controller.
@@ -38,11 +33,10 @@ 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,
+		listeners: {
+			click: this.#onClick.bind(this),
+			keydown: this.#onKeyDown.bind(this),
 		},
 	});
 
@@ -66,9 +60,9 @@ class MyElement extends HTMLElement {
 }
 ```
 
-### Shortcut life cycle methods
+### Shortcut life-cycle methods
 
-In the example below, the `connected` property is set to true and callbacks are immediately added to the `target`.
+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";
@@ -76,12 +70,11 @@ import { Events, Wc } from "wctk";
 class MyElement extends HTMLElement {
 	#wc = new Wc({ this: host });
 	#ec = new Events({
-		host: this,
-		target: this.#wc.shadowRoot,
 		connected: true,
-		callbacks: {
-			click: this.#onClick,
-			keydown: this.#onKeyDown,
+		target: this.#wc.shadowRoot,
+		listeners: {
+			click: this.#onClick.bind(this),
+			keydown: this.#onKeyDown.bind(this),
 		},
 	});
 

package/docs/microtask.md

@@ -4,7 +4,7 @@ Add callbacks to the `microtask queue`.
 
 ## How to use
 
-Add a `Microtask` controller to a web component. Provide a callback.
+Add a `Microtask` controller to a webcomponent. Provide a callback.
 
 Call `Microtask.queue()` to push the callback to the microtask queue.
 
@@ -16,10 +16,7 @@ import { Microtask } from "wctk";
 class MyElement extends HTMLElement {
 	static observedAttributes = ["width"];
 
-	#rc = new Microtask({
-		host: this,
-		callback: this.#render,
-	});
+	#rc = new Microtask(this.#render.bind(this));
 
 	#render() {
 		// update DOM here!
@@ -32,4 +29,4 @@ class MyElement extends HTMLElement {
 }
 ```
 
-The `Microtask.queue()` method can be called multiple times per event loop but the callback will only be called _once_ per microtask in the event loop.
+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

@@ -4,7 +4,7 @@ Lazily map selector queries.
 
 ## How to use
 
-Add a `QuerySelector` controller to a web component.
+Add a `QuerySelector` controller to a webcomponent.
 
 ```html
 <my-element>
@@ -21,10 +21,7 @@ import { QuerySelector } from "wctk";
 
 class MyElement extends HTMLElement {
 	#wc = new Wc({ host: this });
-
-	#qc = new QuerySelector({
-		parent: this.#wc.shadowRoot,
-	});
+	#qc = new QuerySelector(this.#wc.shadowRoot);
 
 	showcaseApi() {
 		// first Element or undefined

package/docs/wc.md

@@ -1,10 +1,10 @@
 # Wc Controller
 
-Build a web component.
+Build a webcomponent.
 
 ## How to use
 
-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";
@@ -16,7 +16,7 @@ class MyElement extends HTMLElement {
 
 ## 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.
+The `Wc` controller interfaces with core web componet APIs like adopted stylesheets and form values.
 
 ```ts
 class MyElement extends HTMLElement {

package/examples/counter/index.html

@@ -14,7 +14,7 @@
 	</head>
 	<body>
 		<main>
-			<!-- web component -->
+			<!-- webcomponent -->
 			<counter-wc>
 				<template shadowrootmode="closed">
 					<button decrease>-</button>