@w-lfpup/wctk 0.1.0 → 0.2.1

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

@@ -0,0 +1,27 @@
+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/README.md

@@ -1,24 +1,23 @@
 # Wctk-JS
 
-A web component tool kit.
+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.
 
-- create [shadow dom](./docs/wc.md)
-- 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
+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).
 
-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.
+Four (4) controllers help developers:
 
-There are no base classes or decorators.
+- 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)
+- cache selector [queries](./docs/query_selector.md)
 
-`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)).
+All controllers (aside from the WC controller) are extremely flexible and not restricted to web components. The can be used on any `HTMLElement`.
 
 ## Install
 
@@ -34,6 +33,20 @@ Or install directly from github.
 npm install --save-dev https://github.com/w-lfpup/wctk-js/
 ```
 
+## Create a Web Component
+
+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
 
 ### SSR (server side rendering)
@@ -44,6 +57,18 @@ 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
+
+If you know vanilla javascript and the DOM you are good to go.
+
+The majority of components only have a few moving pieces. Do you really need templating or flux-patterns
+or tree-walks for your super cool custom button? Do you really need a framework for that checkbox?
+
+The `wctk` is a collection of bare-metal facades over vanilla browser apis. They provide the basics for events, reactivity, and forms.
+
+AFAIK `wctk` is the ONLY web component library built with SSR and declarative shadow dom in mind. Developers
+can pick-up what the HTML threw down and immediately create interactive SSR friendly web components.
+
 ## License
 
 `Wctk-js` is released under the BSD-3 Clause License.

package/dist/events.d.ts

@@ -1,17 +1,25 @@
-export type Callbacks = Array<[string, EventListenerOrEventListenerObject]>;
-export interface EventsInterface {
-    connect(): void;
-    disconnect(): void;
+interface GenericEventListener<E> {
+    (evt: E): 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]>;
+}>;
+interface EventElementInterface {
+    addEventListener: Element["addEventListener"];
+    removeEventListener: Element["removeEventListener"];
 }
 export interface EventParamsInterface {
-    host: EventElementInterface;
+    listeners: EventMap;
     connected?: boolean;
-    target?: EventElementInterface;
-    callbacks: Callbacks;
+    target: EventElementInterface;
+}
+export interface EventsInterface {
+    connect(): void;
+    disconnect(): void;
 }
 export declare class Events implements EventsInterface {
     #private;
@@ -19,3 +27,4 @@ export declare class Events implements EventsInterface {
     connect(): void;
     disconnect(): void;
 }
+export {};

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,27 +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 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;
+    queue: () => void;
+    constructor(callback: Callback);
 }
+export {};

package/dist/microtask.js

@@ -1,16 +1,11 @@
 export class Microtask {
     #queued = false;
     #callback;
-    constructor(params) {
-        let { host, callback } = params;
-        this.queue = this.queue.bind(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() {
         if (this.#queued)
             return;
         this.#queued = true;

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,22 @@ const shadowRootInitFallback = {
     mode: "closed",
 };
 export class Wc {
-    #declarative = true;
+    #declarative = false;
     #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) {
-            this.#declarative = false;
-            shadowRoot = host.attachShadow(shadowRootInit ?? shadowRootInitFallback);
+        if (this.#internals.shadowRoot) {
+            this.#declarative = true;
+            this.#shadowRoot = this.#internals.shadowRoot;
         }
-        this.#shadowRoot = shadowRoot;
+        else {
+            this.#shadowRoot = host.attachShadow(shadowRootInit ?? shadowRootInitFallback);
+        }
+        this.adoptedStyleSheets = adoptedStyleSheets ?? [];
         if (formValue)
             this.setFormValue(formValue, formState);
-        if (adoptedStyleSheets)
-            this.adoptedStyleSheets = adoptedStyleSheets;
     }
     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,16 +12,15 @@ An Events `params` object has four properties:
 
 ```ts
 interface EventParams {
-	host: Node;
-	callbacks: Array<[string, EventListener]>;
+	listeners: Record<string, EventListenerOrEventListenerObject>;
 	connected?: boolean;
-	target?: Node;
+	target: EventTarget;
 }
 ```
 
-The `Events` controller binds a set of `callbacks` to a `host`.
+The `Events` controller binds a record of `listeners` to a `host`.
 
-Afterwards, the `Events` controller adds the callbacks as event listeners on a `target` node.
+Afterwards, the `Events` controller adds the listeners as event listeners on a `target` node.
 
 The `target` node can be a shadowRoot, a document, or the custom element itself.
 
@@ -36,20 +35,20 @@ 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],
-		],
+		listeners: {
+			click: this.#onClick.bind(this),
+			keydown: this.#onKeyDown.bind(this),
+		},
 	});
 
 	#onClick(e: PointerEvent) {
 		// do something with pointer events here!
 	}
 
-	#onKeyDown(e: KeyEvent) {
+	#onKeyDown(e: KeyboardEvent) {
 		// do something with key events here!
 	}
 
@@ -67,7 +66,7 @@ class MyElement extends HTMLElement {
 
 ### 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";
@@ -75,13 +74,12 @@ 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],
-		],
+		listeners: {
+			click: this.#onClick.bind(this),
+			keydown: this.#onKeyDown.bind(this),
+		},
 	});
 
 	#onClick(e: PointerEvent) {

package/docs/microtask.md

@@ -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_ at the tail end of the event loop during the microtaskqueue phase.

package/docs/query_selector.md

@@ -21,9 +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

@@ -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 interfaces with core web componet APIs like adopted stylesheets and form values.
 
 ```ts
 class MyElement extends HTMLElement {