@w-lfpup/wctk 0.2.1 → 0.2.3

package/README.md

@@ -17,23 +17,23 @@ Four (4) controllers help developers:
 - listen for [events](./docs/events.md)
 - cache selector [queries](./docs/query_selector.md)
 
-All controllers (aside from the WC controller) are extremely flexible and not restricted to web components. The can be used on any `HTMLElement`.
+Controllers are flexible and not restricted to webcomponents. The can be used on any `HTMLElement`.
 
 ## Install
 
-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/
 ```
 
-Or install directly from github.
+Install with npm.
 
 ```bash
-npm install --save-dev https://github.com/w-lfpup/wctk-js/
+npm install --save-dev @w-lfpup/wctk
 ```
 
-## Create a Web Component
+## Create a webcomponent
 
 Add a `Wc` controller to a custom element with only one line
 
@@ -59,15 +59,17 @@ The following examples demonstrate several common SSR use cases:
 
 ## Design Goals
 
-If you know vanilla javascript and the DOM you are good to go.
+The `wctk` is a collection of bare-metal facades over vanilla browser apis. They provide the basics for
+events, reactivity, and forms.
 
-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?
+If you know vanilla javascript and the DOM you are good to go.
 
-The `wctk` is a collection of bare-metal facades over vanilla browser apis. They provide the basics for events, reactivity, and forms.
+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.
 
-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.
+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
 

package/dist/events.d.ts

@@ -1,19 +1,20 @@
-interface GenericEventListener<E> {
+interface GenericEventListener<E extends Event> {
     (evt: E): void;
 }
-interface GenericEventListenerObject<E> {
+interface GenericEventListenerObject<E extends Event> extends EventListenerObject {
     handleEvent(object: E): void;
 }
-type GenericCallbacks<E> = GenericEventListener<E> | GenericEventListenerObject<E>;
-type EventMap = Partial<{
-    [Property in keyof GlobalEventHandlersEventMap]: GenericCallbacks<GlobalEventHandlersEventMap[Property]>;
-}>;
+type GenericCallbacks<E extends Event> = GenericEventListener<E> | GenericEventListenerObject<E>;
+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

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

package/dist/microtask.js

@@ -1,18 +1,19 @@
 export class Microtask {
     #queued = false;
     #callback;
-    queue = this.#queue.bind(this);
     constructor(callback) {
         this.#callback = callback;
     }
+    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/docs/events.md

@@ -1,31 +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 {
-	listeners: Record<string, EventListenerOrEventListenerObject>;
 	connected?: boolean;
+	listeners: Record<string, EventListenerOrEventListenerObject>;
 	target: EventTarget;
 }
 ```
 
-The `Events` controller binds a record of `listeners` to a `host`.
-
-Afterwards, the `Events` controller adds the listeners 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.
@@ -64,7 +60,7 @@ class MyElement extends HTMLElement {
 }
 ```
 
-### Shortcut life cycle methods
+### Shortcut life-cycle methods
 
 In the example below, the `connected` property is set to true and listeners are immediately added to the `target`.
 
@@ -74,8 +70,8 @@ import { Events, Wc } from "wctk";
 class MyElement extends HTMLElement {
 	#wc = new Wc({ this: host });
 	#ec = new Events({
-		target: this.#wc.shadowRoot,
 		connected: true,
+		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.
 
@@ -29,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_ at the tail end of the event loop during the microtaskqueue phase.
+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>

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";

package/examples/counter/index.html

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

package/examples/counter/mod.js

@@ -2,8 +2,8 @@ import { Wc, Events } from "wctk";
 class Counter extends HTMLElement {
     #wc = new Wc({ host: this });
     #ev = new Events({
-        target: this.#wc.shadowRoot,
         connected: true,
+        target: this.#wc.shadowRoot,
         listeners: {
             click: this.#clickHandler.bind(this),
         },

package/examples/counter/mod.ts

@@ -13,8 +13,8 @@ class Counter extends HTMLElement {
 	#wc = new Wc({ host: this });
 
 	#ev = new Events({
-		target: this.#wc.shadowRoot,
 		connected: true,
+		target: this.#wc.shadowRoot,
 		listeners: {
 			click: this.#clickHandler.bind(this),
 		},

package/examples/form_associated/text_input.js

@@ -3,8 +3,8 @@ export class TextInput extends HTMLElement {
     static formAssociated = true;
     #wc = new Wc({ host: this });
     #ev = new Events({
-        target: this.#wc.shadowRoot,
         connected: true,
+        target: this.#wc.shadowRoot,
         listeners: {
             change: this.#changeHandler.bind(this),
         },

package/examples/form_associated/text_input.ts

@@ -8,9 +8,10 @@ export class TextInput extends HTMLElement {
 	static formAssociated = true;
 
 	#wc = new Wc({ host: this });
+
 	#ev = new Events({
-		target: this.#wc.shadowRoot,
 		connected: true,
+		target: this.#wc.shadowRoot,
 		listeners: {
 			change: this.#changeHandler.bind(this),
 		},

package/examples/stopwatch/index.html

@@ -14,7 +14,7 @@
 	</head>
 	<body>
 		<main>
-			<!-- web component -->
+			<!-- webcomponent -->
 			<stopwatch-wc>
 				<template shadowrootmode="closed">
 					<!-- Shadow DOM content -->

package/examples/stopwatch/stopwatch.ts

@@ -5,7 +5,7 @@
 
 // This example uses window.requestAnimationFrame.
 // Multiple stopwatches means multiple animation frame requests.
-// This is not terribly performant but it's a quick way to get
+// This is not terribly performant but it's a quick way to retrieve
 // accurate timestamp data for a stopwatch.
 
 import { Wc, Microtask } from "wctk";

package/package.json

@@ -2,16 +2,17 @@
 	"name": "@w-lfpup/wctk",
 	"type": "module",
 	"main": "dist/mod.js",
-	"description": "A bare-metal toolkit for web components",
+	"description": "A bare-metal webcomponent toolkit",
 	"license": "BSD-3-Clause",
-	"version": "0.2.1",
+	"version": "0.2.3",
 	"scripts": {
 		"prepare": "npm run build",
 		"build": "npm run build:src && npm run build:tests && npm run build:examples",
 		"build:src": "npx tsc --project ./src",
 		"build:tests": "npx tsc --project ./tests",
 		"build:examples": "npx tsc --project ./examples",
-		"test": "npx jackrabbit_webdriver jr.json tests/dist/mod.js",
+		"test": "npm run test:browsers",
+		"test:browsers": "npx jackrabbit_webdriver jr.json tests/dist/mod.js",
 		"format": "prettier --write ./"
 	},
 	"devDependencies": {

package/src/events.ts

@@ -1,20 +1,28 @@
-interface GenericEventListener<E> {
+interface GenericEventListener<E extends Event> {
 	(evt: E): void;
 }
 
-interface GenericEventListenerObject<E> {
+interface GenericEventListenerObject<
+	E extends Event,
+> extends EventListenerObject {
 	handleEvent(object: E): void;
 }
 
-type GenericCallbacks<E> =
+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>;
 
 type Callbacks = Array<[string, EventListenerOrEventListenerObject]>;
 
@@ -24,7 +32,7 @@ interface EventElementInterface {
 }
 
 export interface EventParamsInterface {
-	listeners: EventMap;
+	listeners: ListenerMap;
 	connected?: boolean;
 	target: EventElementInterface;
 }

package/src/microtask.ts

@@ -7,20 +7,22 @@ type Callback = () => void;
 export class Microtask implements MicrotaskInterface {
 	#queued = false;
 	#callback: Callback;
-	queue = this.#queue.bind(this);
 
 	constructor(callback: Callback) {
 		this.#callback = callback;
 	}
 
+	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();
 	}
 }