@w-lfpup/wctk 0.1.0

package/.github/workflows/build_and_test.yml

@@ -0,0 +1,18 @@
+name: Build and Test
+
+on:
+    push:
+        branches: ["main"]
+    pull_request:
+        branches: ["main"]
+
+jobs:
+    build_and_test:
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v5
+            - uses: actions/setup-node@v4
+            - name: Install
+              run: npm ci
+            - name: Format
+              run: npm run format

package/.prettierignore

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

package/.prettierrc

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

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2024, Taylor Vann
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,49 @@
+# Wctk-JS
+
+A web component tool kit.
+
+## About
+
+A half-dozen controllers help developers:
+
+- 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 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.
+
+`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)).
+
+## Install
+
+Install with npm.
+
+```bash
+npm install --save-dev @w-lfpup/wctk
+```
+
+Or install directly from github.
+
+```bash
+npm install --save-dev https://github.com/w-lfpup/wctk-js/
+```
+
+## Examples
+
+### SSR (server side rendering)
+
+The following examples demonstrate several common SSR use cases:
+
+- a [counter](https://w-lfpup.github.io/wctk-js/examples/counter/) with initial state in the DOM ([code](https://github.com/w-lfpup/wctk-js/tree/main/examples/counter/)).
+- 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/)).
+
+## License
+
+`Wctk-js` is released under the BSD-3 Clause License.

package/dist/bind.d.ts

@@ -0,0 +1,7 @@
+export interface BindParamsInterface {
+    host: Object;
+    callbacks: Function[];
+}
+export declare class Bind {
+    constructor(params: BindParamsInterface);
+}

package/dist/bind.js

@@ -0,0 +1,14 @@
+export class Bind {
+    constructor(params) {
+        let { host, callbacks } = params;
+        for (let callback of callbacks) {
+            // do not bind and replace already bound functions
+            if (callback instanceof Function &&
+                !callback.hasOwnProperty("prototype")) {
+                let { name } = callback;
+                if (!name.startsWith("#"))
+                    host[name] = callback.bind(host);
+            }
+        }
+    }
+}

package/dist/events.d.ts

@@ -0,0 +1,21 @@
+export type Callbacks = Array<[string, EventListenerOrEventListenerObject]>;
+export interface EventsInterface {
+    connect(): void;
+    disconnect(): void;
+}
+export interface EventElementInterface {
+    addEventListener: EventTarget["addEventListener"];
+    removeEventListener: EventTarget["removeEventListener"];
+}
+export interface EventParamsInterface {
+    host: EventElementInterface;
+    connected?: boolean;
+    target?: EventElementInterface;
+    callbacks: Callbacks;
+}
+export declare class Events implements EventsInterface {
+    #private;
+    constructor(params: EventParamsInterface);
+    connect(): void;
+    disconnect(): void;
+}

package/dist/events.js

@@ -0,0 +1,39 @@
+export class Events {
+    #connected = false;
+    #callbacks = [];
+    #target;
+    constructor(params) {
+        const { host, target, callbacks, connected } = params;
+        this.#target = target ?? host;
+        this.#callbacks = getBoundCallbacks(host, callbacks);
+        if (connected)
+            this.connect();
+    }
+    connect() {
+        if (this.#connected)
+            return;
+        this.#connected = true;
+        for (let [name, callback] of this.#callbacks) {
+            this.#target.addEventListener(name, callback);
+        }
+    }
+    disconnect() {
+        if (!this.#connected)
+            return;
+        this.#connected = false;
+        for (let [name, callback] of this.#callbacks) {
+            this.#target.removeEventListener(name, callback);
+        }
+    }
+}
+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

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

package/dist/microtask.js

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

package/dist/mod.d.ts

@@ -0,0 +1,6 @@
+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

@@ -0,0 +1,6 @@
+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

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

package/dist/query_selector.js

@@ -0,0 +1,25 @@
+export class QuerySelector {
+    #queries = new Map();
+    #params;
+    constructor(params) {
+        this.#params = params;
+    }
+    querySelector(selector) {
+        return getQuery(this.#params, this.#queries, selector)[0];
+    }
+    querySelectorAll(selector) {
+        return getQuery(this.#params, this.#queries, selector);
+    }
+    deleteAll() {
+        this.#queries = 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

@@ -0,0 +1,19 @@
+export type Subscribe<E, A> = (cb: E) => A;
+export type Unsubscribe<A> = (affect: A) => void;
+export interface SubscriptionInterface {
+    connect(): void;
+    disconnect(): void;
+}
+export interface SubscriptionParamsInterface<E, A> {
+    host: Object;
+    callback: E;
+    connected?: boolean;
+    subscribe: Subscribe<E, A>;
+    unsubscribe: Unsubscribe<A>;
+}
+export declare class Subscription<E, A> implements SubscriptionInterface {
+    #private;
+    constructor(params: SubscriptionParamsInterface<E, A>);
+    connect(): void;
+    disconnect(): void;
+}

package/dist/subscription.js

@@ -0,0 +1,26 @@
+export class Subscription {
+    #callback;
+    #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.connect();
+    }
+    connect() {
+        if (!this.#affect)
+            this.#affect = this.#subscribe(this.#callback);
+    }
+    disconnect() {
+        if (this.#affect)
+            this.#unsubscribe(this.#affect);
+    }
+}

package/dist/wc.d.ts

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

package/dist/wc.js

@@ -0,0 +1,46 @@
+const shadowRootInitFallback = {
+    mode: "closed",
+};
+export class Wc {
+    #declarative = true;
+    #internals;
+    #shadowRoot;
+    constructor(params) {
+        let { host, shadowRootInit, adoptedStyleSheets, formValue, formState } = params;
+        this.#internals = host.attachInternals();
+        let { shadowRoot } = this.#internals;
+        if (!shadowRoot) {
+            this.#declarative = false;
+            shadowRoot = host.attachShadow(shadowRootInit ?? shadowRootInitFallback);
+        }
+        this.#shadowRoot = shadowRoot;
+        if (formValue)
+            this.setFormValue(formValue, formState);
+        if (adoptedStyleSheets)
+            this.adoptedStyleSheets = adoptedStyleSheets;
+    }
+    get declarative() {
+        return this.#declarative;
+    }
+    get shadowRoot() {
+        return this.#shadowRoot;
+    }
+    get adoptedStyleSheets() {
+        return this.#shadowRoot.adoptedStyleSheets ?? [];
+    }
+    set adoptedStyleSheets(stylesheets) {
+        this.#shadowRoot.adoptedStyleSheets = stylesheets;
+    }
+    checkValidity() {
+        return this.#internals.checkValidity();
+    }
+    reportValidity() {
+        return this.#internals.reportValidity();
+    }
+    setFormValue(value, state) {
+        this.#internals.setFormValue(value, state);
+    }
+    setValidity(flags, message, anchor) {
+        this.#internals.setValidity(flags, message, anchor);
+    }
+}

package/docs/bind.md

@@ -0,0 +1,26 @@
+# Bind Controller
+
+Bind functions to objects.
+
+This utility is mainly designed to avoid using the constructor.
+
+## How to use
+
+Add a `Bind` controller to a web component.
+
+Add a list of methods on instantiation. The methods cannot be `#private`.
+
+```ts
+import { Bind } from "wctk";
+
+class MyElement extends HTMLElement {
+	#bc = new Bind({
+		host: this,
+		callbacks: [this.elementCallback],
+	};
+
+	elementCallback(e: KeyboardEvent) {
+		// This function can be passed as a callback to event listeners now!
+	}
+}
+```

package/docs/events.md

@@ -0,0 +1,99 @@
+# Events Controller
+
+Add methods as event listener callbacks.
+
+## How to use
+
+Add an `Events` controller to a web component. Use a params object on instantiation.
+
+### Params
+
+An Events `params` object has four properties:
+
+```ts
+interface EventParams {
+	host: Node;
+	callbacks: Array<[string, EventListener]>;
+	connected?: boolean;
+	target?: Node;
+}
+```
+
+The `Events` controller binds a set of `callbacks` to a `host`.
+
+Afterwards, the `Events` controller adds the callbacks as 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.
+
+```ts
+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],
+		],
+	});
+
+	#onClick(e: PointerEvent) {
+		// do something with pointer events here!
+	}
+
+	#onKeyDown(e: KeyEvent) {
+		// 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 callbacks are immediately added to the `target`.
+
+```ts
+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],
+		],
+	});
+
+	#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

@@ -0,0 +1,35 @@
+# Microtask Controller
+
+Add callbacks to the `microtask queue`.
+
+## How to use
+
+Add a `Microtask` controller to a web component. 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({
+		host: this,
+		callback: this.#render,
+	});
+
+	#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_ per microtask in the event loop.

package/docs/query_selector.md

@@ -0,0 +1,39 @@
+# QuerySelector Controller
+
+Lazily map selector queries.
+
+## How to use
+
+Add a `QuerySelector` controller to a web component.
+
+```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({
+		parent: 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();
+	}
+}
+```