@bodil/dom 0.1.10 → 0.2.1

package/src/decorators/attribute.test.ts

@@ -9,14 +9,12 @@ import { html, nothing } from "lit";
 test("@attribute", async () => {
     @customElement("attribute-test-class")
     class AttributeTestClass extends Component {
-        @attribute accessor wibble: string | undefined = "Joe";
-        @attribute({ type: Number, reflect: true }) accessor wobble: number | undefined = 1;
-        @attribute({ type: Boolean, reflect: true }) accessor noMeansNo: boolean | undefined =
-            false;
-        @attribute({ name: "wolp", reactive: false, reflect: true }) accessor welp:
-            | string
-            | undefined = "Joe";
-        @attribute({ reflect: false }) accessor hide: string | undefined = "no";
+        @attribute accessor wibble: string | null = "Joe";
+        @attribute({ type: Number, reflect: true }) accessor wobble: number | null = 1;
+        @attribute({ type: Boolean, reflect: true }) accessor noMeansNo: boolean | null = false;
+        @attribute({ name: "wolp", reactive: false, reflect: true }) accessor welp: string | null =
+            "Joe";
+        @attribute({ reflect: false }) accessor hide: string | null = "no";
     }
 
     const t = document.createElement("attribute-test-class") as AttributeTestClass;
@@ -32,17 +30,17 @@ test("@attribute", async () => {
     expect(t.getAttribute("wibble")).toBe("Mike");
     expect(wibble.get()).toBe("Mike");
     t.removeAttribute("wibble");
-    expect(t.wibble).toBeUndefined();
+    expect(t.wibble).toBeNull();
     expect(t.getAttribute("wibble")).toBeNull();
-    expect(wibble.get()).toBe(undefined);
+    expect(wibble.get()).toBe(null);
     t.setAttribute("wibble", "Robert");
     expect(t.wibble).toBe("Robert");
     expect(t.getAttribute("wibble")).toBe("Robert");
     expect(wibble.get()).toBe("Robert");
-    t.wibble = undefined;
-    expect(t.wibble).toBeUndefined();
+    t.wibble = null;
+    expect(t.wibble).toBeNull();
     expect(t.getAttribute("wibble")).toBeNull();
-    expect(wibble.get()).toBe(undefined);
+    expect(wibble.get()).toBe(null);
 
     expect(t.wobble).toBe(1);
     expect(t.getAttribute("wobble")).toBe("1");
@@ -133,7 +131,7 @@ test("@attribute init ordering", async () => {
     class AttributeInitTestClass extends Component {
         @attribute accessor movieStar = "Joe";
 
-        @attribute accessor foo: string | undefined;
+        @attribute accessor foo: string | null = null;
 
         #wibble = "Joe";
         @attributeGetter get wibble(): string {
@@ -209,3 +207,32 @@ test("subcomponent attributes are initialised properly", async () => {
         `<subcomp-init-sub attr1="Mike" attr2="Mike" attr3="Mike" attr4="Mike"></subcomp-init-sub>`,
     );
 });
+
+test("@attributeGetter is reactive", async () => {
+    @customElement("reactive-getter")
+    class ReactiveGetter extends Component {
+        @attribute({ type: Boolean }) accessor disabled = false;
+        @attributeGetter({ type: Number, reactive: true }) get tabindex(): number {
+            return this.disabled ? -1 : 0;
+        }
+    }
+
+    const t = document.createElement("reactive-getter") as ReactiveGetter;
+    // document.body.append(t);
+    // await t.updateComplete;
+
+    expect(t.getAttribute("disabled")).toBeNull();
+    expect(t.tabindex).toBe(0);
+    // Attributes won't update until we yield, so yield.
+    await Promise.resolve();
+    expect(t.getAttribute("tabindex")).toBe("0");
+
+    t.disabled = true;
+
+    expect(t.getAttribute("disabled")).not.toBeNull();
+    // change should be immediately reflected in the computed property
+    expect(t.tabindex).toBe(-1);
+    // but attributes will only update after a yield
+    await Promise.resolve();
+    expect(t.getAttribute("tabindex")).toBe("-1");
+});

package/src/decorators/attribute.ts

@@ -1,6 +1,6 @@
 /* eslint-disable @typescript-eslint/unified-signatures */
 
-import { isDeepEqual, isNullish, unreachable } from "@bodil/core/assert";
+import { assertNever, isDeepEqual, isNullish, unreachable } from "@bodil/core/assert";
 import { None, Some, type Option } from "@bodil/opt";
 import { Signal } from "@bodil/signal";
 
@@ -54,21 +54,21 @@ export function toAttribute(value: unknown, type: AttributeType): string | null
     }
 }
 
-export function fromAttribute(value: string | null, type: typeof Number): number | undefined;
+export function fromAttribute(value: string | null, type: typeof Number): number | null;
 export function fromAttribute(value: string | null, type: typeof Boolean): boolean;
-export function fromAttribute(value: string | null, type: typeof String): string | undefined;
+export function fromAttribute(value: string | null, type: typeof String): string | null;
 export function fromAttribute(
     value: string | null,
     type: AttributeType,
-): string | number | boolean | undefined;
+): string | number | boolean | null;
 export function fromAttribute(
     value: string | null,
     type: AttributeType,
-): string | number | boolean | undefined {
+): string | number | boolean | null {
     switch (type) {
         case Number: {
-            const num = value === null ? undefined : Number(value);
-            if (num !== undefined && Number.isNaN(num)) {
+            const num = value === null ? null : Number(value);
+            if (num !== null && Number.isNaN(num)) {
                 throw new TypeError(
                     `numeric attribute value ${JSON.stringify(value)} parsed as NaN`,
                 );
@@ -78,7 +78,7 @@ export function fromAttribute(
         case Boolean:
             return value !== null;
         case String:
-            return value ?? undefined;
+            return value ?? null;
         default:
             unreachable();
     }
@@ -109,22 +109,22 @@ type AttributeDecoratorFunction<C, T> =
     | ClassSetterDecoratorFunction<C, T>;
 
 // Getter with number type
-export function attributeGetter<C extends Component, T extends number | undefined>(
+export function attributeGetter<C extends Component, T extends number | null>(
     options: AttributeOptions & { type: typeof Number },
 ): ClassGetterDecoratorFunction<C, T>;
 
 // Getter with boolean type
-export function attributeGetter<C extends Component, T extends boolean | undefined>(
+export function attributeGetter<C extends Component, T extends boolean | null>(
     options: AttributeOptions & { type: typeof Boolean },
 ): ClassGetterDecoratorFunction<C, T>;
 
 // Getter with string type
-export function attributeGetter<C extends Component, T extends string | undefined>(
+export function attributeGetter<C extends Component, T extends string | null>(
     options: AttributeOptions,
 ): ClassGetterDecoratorFunction<C, T>;
 
 // Getter with no options
-export function attributeGetter<C extends Component, T extends string | undefined>(
+export function attributeGetter<C extends Component, T extends string | null>(
     value: ClassGetterDecoratorTarget<C, T>,
     context: ClassGetterDecoratorContext<C, T>,
 ): ClassGetterDecoratorResult<C, T>;
@@ -138,22 +138,22 @@ export function attributeGetter<C extends Component, T>(
 }
 
 // Setter with number type
-export function attributeSetter<C extends Component, T extends number | undefined>(
+export function attributeSetter<C extends Component, T extends number | null>(
     options: AttributeOptions & { type: typeof Number },
 ): ClassSetterDecoratorFunction<C, T>;
 
 // Setter with boolean type
-export function attributeSetter<C extends Component, T extends boolean | undefined>(
+export function attributeSetter<C extends Component, T extends boolean | null>(
     options: AttributeOptions & { type: typeof Boolean },
 ): ClassSetterDecoratorFunction<C, T>;
 
 // Setter with string type
-export function attributeSetter<C extends Component, T extends string | undefined>(
+export function attributeSetter<C extends Component, T extends string | null>(
     options: AttributeOptions,
 ): ClassSetterDecoratorFunction<C, T>;
 
 // Setter with no options
-export function attributeSetter<C extends Component, T extends string | undefined>(
+export function attributeSetter<C extends Component, T extends string | null>(
     value: ClassSetterDecoratorTarget<C, T>,
     context: ClassSetterDecoratorContext<C, T>,
 ): ClassSetterDecoratorResult<C, T>;
@@ -167,27 +167,27 @@ export function attributeSetter<C extends Component, T>(
 }
 
 // Accessor with number type
-export function attribute<C extends Component, T extends number | undefined>(
+export function attribute<C extends Component, T extends number | null>(
     options: AttributeOptions & { type: typeof Number },
 ): ClassAccessorDecoratorFunction<C, T>;
 
 // Accessor with boolean type
-export function attribute<C extends Component, T extends boolean | undefined>(
+export function attribute<C extends Component, T extends boolean | null>(
     options: AttributeOptions & { type: typeof Boolean },
 ): ClassAccessorDecoratorFunction<C, T>;
 
 // Accessor with string type
-export function attribute<C extends Component, T extends string | undefined>(
+export function attribute<C extends Component, T extends string | null>(
     options: AttributeOptions,
 ): ClassAccessorDecoratorFunction<C, T>;
 
 // Accessor with no options
-export function attribute<C extends Component, T extends string | undefined>(
+export function attribute<C extends Component, T extends string | null>(
     value: ClassAccessorDecoratorTarget<C, T>,
     context: ClassAccessorDecoratorContext<C, T>,
 ): ClassAccessorDecoratorResult<C, T>;
 
-export function attribute<C extends Component, T extends string | number | boolean | undefined>(
+export function attribute<C extends Component, T extends string | number | boolean | null>(
     valueOrOptions?: AttributeDecoratorTarget<C, T> | AttributeOptions,
     context?: AttributeDecoratorContext<C, T>,
 ): AttributeDecoratorResult<C, T> | AttributeDecoratorFunction<C, T> {
@@ -234,16 +234,21 @@ export function attribute<C extends Component, T extends string | number | boole
             return accessor(options, context, value as ClassAccessorDecoratorTarget<C, T>);
         }
 
-        // ensure getters/setters aren't configured with reactive or reflect
-        if (options.reactive) {
-            throw new TypeError(
-                `Getter/setter attributes cannot be declared with reactive: true (on ${JSON.stringify(context.name)})`,
-            );
-        }
-
         if (context.kind === "setter") {
+            // ensure setters aren't configured with reactive
+            if (options.reactive) {
+                throw new TypeError(
+                    `Setter attributes cannot be declared with reactive: true (on ${JSON.stringify(context.name)})`,
+                );
+            }
             return setter(options, value as ClassSetterDecoratorTarget<C, T>);
         }
+
+        if (context.kind === "getter") {
+            return getter(options, context, value as ClassGetterDecoratorTarget<C, T>);
+        }
+
+        assertNever(context);
     };
 }
 
@@ -260,6 +265,29 @@ function syncAttribute<C extends Component, T>(
     }
 }
 
+function getter<C extends Component, T>(
+    options: AttributeConfig,
+    context: ClassGetterDecoratorContext<C, T>,
+    getter: ClassGetterDecoratorTarget<C, T>,
+): ClassGetterDecoratorResult<C, T> {
+    if (options.reactive) {
+        const getSig = (obj: Component) =>
+            signalForObject(obj, context.name, () => {
+                const sig = Signal.computed(getter.bind(obj));
+                // FIXME this leaks when obj isn't explicitly disposed
+                obj.use(
+                    Signal.effect(() => {
+                        syncAttribute(obj, options, sig.get());
+                    }),
+                );
+                return sig;
+            }) as Signal.Computed<T>;
+        return function (this: C): T {
+            return getSig(this).get();
+        };
+    }
+}
+
 function setter<C extends Component, T>(
     options: AttributeConfig,
     setter: ClassSetterDecoratorTarget<C, T>,

package/src/decorators/require.test.ts

@@ -11,7 +11,7 @@ test("@require", async () => {
     @customElement("require-test-class")
     class RequireTestClass extends Component {
         @require @reactive foo?: string;
-        @require @attribute accessor bar: string | undefined;
+        @require @attribute accessor bar: string | null = null;
 
         protected override initialised() {
             inits++;

package/src/dom.test.ts

@@ -0,0 +1,23 @@
+import { html } from "lit";
+import { expect, test } from "vitest";
+
+import { findDescendants } from "./dom";
+import { testHTML } from "./test";
+
+test("findDescendants", async () => {
+    const root = await testHTML(html`
+        <p>foo</p>
+        <div><p>bar</p></div>
+        <article>
+            <div>
+                <p>baz</p>
+                <p>gazonk</p>
+            </div>
+        </article>
+    `);
+    expect(
+        findDescendants(root, (el) => el instanceof HTMLParagraphElement)
+            .map((el) => el.innerText)
+            .toArray(),
+    ).toEqual(["foo", "bar", "baz", "gazonk"]);
+});

package/src/dom.ts

@@ -3,12 +3,13 @@
  * @module
  */
 
-import { assertNever, isNullish, unreachable } from "@bodil/core/assert";
-import { toDisposable } from "@bodil/core/disposable";
+import { assertNever, isEmpty, isNullish, unreachable } from "@bodil/core/assert";
+import { DisposableContext, toDisposable } from "@bodil/core/disposable";
 import type { ReactiveController, ReactiveControllerHost } from "lit";
 import type { OptionalKeysOf } from "type-fest";
 
 import type { Pixels } from "./css";
+import { eventListener } from "./event";
 import { contains } from "./geometry";
 
 /**
@@ -129,20 +130,26 @@ export class DOMIterator extends Iterator<Node> {
 }
 
 /**
- * Get an iterator over the child elements of an {@link Element} or {@link DocumentFragment}.
+ * Return all descendants of `root` which match the `predicate` function.
  */
-export function childElements(parent: Element | DocumentFragment | null): IteratorObject<Element> {
-    if (parent === null) {
+export function findDescendants<T extends Element>(
+    root: Element | DocumentFragment | null,
+    predicate: (child: Element) => child is T,
+): IteratorObject<T>;
+export function findDescendants(
+    root: Element | DocumentFragment | null,
+    predicate: (child: Element) => boolean,
+): IteratorObject<Element>;
+export function findDescendants(
+    root: Element | DocumentFragment | null,
+    predicate: (child: Element) => boolean,
+): IteratorObject<Element> {
+    if (root === null) {
         return Iterator.from([]);
     }
-    const iter = function* () {
-        let el = parent.firstElementChild;
-        while (el !== null) {
-            yield el;
-            el = el.nextElementSibling;
-        }
-    };
-    return Iterator.from(iter());
+    return Iterator.from(root.children).flatMap((el) =>
+        predicate(el) ? [el, ...findDescendants(el, predicate)] : findDescendants(el, predicate),
+    );
 }
 
 /** Test whether the user has asked for reduced motion. */
@@ -199,9 +206,17 @@ export async function animationEnd(el: HTMLElement): Promise<void> {
     await Promise.all(
         el.getAnimations().map((animation) => {
             return new Promise((resolve) => {
-                const handleAnimationEvent = () => requestAnimationFrame(resolve);
-                animation.addEventListener("cancel", () => handleAnimationEvent(), { once: true });
-                animation.addEventListener("finish", () => handleAnimationEvent(), { once: true });
+                const context = new DisposableContext();
+                const handleAnimationEvent = () => {
+                    context.dispose();
+                    requestAnimationFrame(resolve);
+                };
+                context.use(
+                    eventListener(animation, "cancel", handleAnimationEvent, { once: true }),
+                );
+                context.use(
+                    eventListener(animation, "finish", handleAnimationEvent, { once: true }),
+                );
             });
         }),
     );
@@ -421,6 +436,30 @@ export function scrollToItem(el: HTMLElement, scrollToItemOptions: ScrollToItemO
     }
 }
 
+const ids: Record<string, number> = {};
+
+function freshID(tagName: string): number {
+    const next = ids[tagName] ?? 1;
+    ids[tagName] = next + 1;
+    return next;
+}
+
+/**
+ * Assign a unique ID to the target element.
+ *
+ * Returns the ID that was assigned.
+ *
+ * If the target element already has an `id` attribute, this will not be
+ * overwritten.
+ */
+export function applyUniqueID(target: HTMLElement): string {
+    if (isEmpty(target.id)) {
+        const name = target.tagName.toLowerCase();
+        target.id = `${name}-${freshID(name)}`;
+    }
+    return target.id;
+}
+
 // HasSlotController nicked largely verbatim from Shoelace
 // https://github.com/shoelace-style/shoelace/blob/next/src/internal/slot.ts
 /**

package/src/emitter.ts

@@ -69,6 +69,8 @@ export class EmitterElement extends HTMLElement {
      * class MyElement extends EmitterElement {
      *     emits!: Emits<"my-event" | "my-other-event";
      * }
+     *
+     * @category Events
      */
     emits!: { [K in keyof HTMLElementEventMap]?: never };
 
@@ -76,6 +78,8 @@ export class EmitterElement extends HTMLElement {
      * Emit a custom event with the given name and detail.
      *
      * Event init options default to `{ bubbles: true, composed: true }`.
+     *
+     * @category Events
      */
     emit<
         M extends CustomEventTypes<keyof this["emits"] & keyof HTMLElementEventMap>,
@@ -101,6 +105,8 @@ export class EmitterElement extends HTMLElement {
      * @example
      * this.emitEvent("click", MouseEvent, { button: 2 });
      * // emits: new MouseEvent("click", { button: 2 });
+     *
+     * @category Events
      */
     emitEvent<
         K extends keyof this["emits"] & keyof HTMLElementEventMap,

package/src/index.ts

@@ -9,5 +9,6 @@ import * as dom from "./dom";
 import * as event from "./event";
 import * as geometry from "./geometry";
 import * as signal from "./signal";
+import * as test from "./test";
 
-export { component, css, dom, event, geometry, signal };
+export { component, css, dom, event, geometry, signal, test };

package/src/test.ts

@@ -0,0 +1,38 @@
+/**
+ * Tools for testing web components.
+ * @module
+ */
+
+import { render } from "lit";
+
+import { Component } from "./component";
+
+/**
+ * Render a Lit template and wait for any {@link Component}s inside it to
+ * stabilise before returning the {@link HTMLElement} containing the rendered
+ * template.
+ *
+ * The root element is also a {@link Disposable} which will remove itself from
+ * the DOM and dispose its {@link Component}s when disposed.
+ *
+ * @example
+ * using root = await testHTML(html`<my-component></my-component>`);
+ * expect(root.querySelector("my-component")).toBeInstanceOf(MyComponent);
+ */
+export async function testHTML(template: unknown): Promise<HTMLElement & Disposable> {
+    const root = document.createElement("section") as HTMLElement & Disposable;
+    document.body.append(root);
+    render(template, root, { host: root });
+    root[Symbol.dispose] = () => {
+        Iterator.from(root.children)
+            .filter((el) => el instanceof Component)
+            .forEach((comp) => comp[Symbol.dispose]());
+        root.remove();
+    };
+    await Promise.all(
+        Iterator.from(root.children)
+            .filter((el) => el instanceof Component)
+            .map((el) => el.hasStabilised),
+    );
+    return root;
+}

package/src/decorators/connect.test.ts

@@ -1,119 +0,0 @@
-import { sleep } from "@bodil/core/async";
-import { Signal } from "@bodil/signal";
-import { customElement } from "lit/decorators.js";
-import { expect, test } from "vitest";
-
-import { Component, connect, connectEffect } from "../component";
-import type { ConnectFunction } from "./connect";
-
-test("@connect", () => {
-    let methodConnected = 0,
-        methodDisconnected = 0;
-    let fieldConnected = 0,
-        fieldDisconnected = 0;
-
-    @customElement("connected-test-class")
-    class ConnectedTestClass extends Component {
-        @connect onConnected() {
-            methodConnected++;
-            return () => {
-                methodDisconnected++;
-            };
-        }
-
-        @connect field: ConnectFunction = () => {
-            fieldConnected++;
-            return () => {
-                fieldDisconnected++;
-            };
-        };
-    }
-
-    const c = document.createElement("connected-test-class") as ConnectedTestClass;
-    expect(methodConnected).toBe(0);
-    expect(methodDisconnected).toBe(0);
-    expect(fieldConnected).toEqual(methodConnected);
-    expect(fieldDisconnected).toEqual(methodDisconnected);
-    document.body.append(c);
-    expect(methodConnected).toBe(1);
-    expect(methodDisconnected).toBe(0);
-    expect(fieldConnected).toEqual(methodConnected);
-    expect(fieldDisconnected).toEqual(methodDisconnected);
-    c.remove();
-    expect(methodConnected).toBe(1);
-    expect(methodDisconnected).toBe(1);
-    expect(fieldConnected).toEqual(methodConnected);
-    expect(fieldDisconnected).toEqual(methodDisconnected);
-    document.body.append(c);
-    expect(methodConnected).toBe(2);
-    expect(methodDisconnected).toBe(1);
-    expect(fieldConnected).toEqual(methodConnected);
-    expect(fieldDisconnected).toEqual(methodDisconnected);
-    c.remove();
-    expect(methodConnected).toBe(2);
-    expect(methodDisconnected).toBe(2);
-    expect(fieldConnected).toEqual(methodConnected);
-    expect(fieldDisconnected).toEqual(methodDisconnected);
-});
-
-test("@connectEffect", async () => {
-    let methodRun = 0,
-        methodDisposed = 0;
-    let fieldRun = 0,
-        fieldDisposed = 0;
-    const signal = Signal.from(1);
-
-    @customElement("connect-effect-test-class")
-    class ConnectEffectTestClass extends Component {
-        @connectEffect onConnected() {
-            methodRun += signal.get();
-            return () => {
-                methodDisposed++;
-            };
-        }
-
-        @connectEffect field: ConnectFunction = () => {
-            fieldRun += signal.get();
-            return () => {
-                fieldDisposed++;
-            };
-        };
-    }
-
-    const c = document.createElement("connect-effect-test-class") as ConnectEffectTestClass;
-    expect(methodRun).toBe(0);
-    expect(methodDisposed).toBe(0);
-    expect(fieldRun).toEqual(methodRun);
-    expect(fieldDisposed).toEqual(methodDisposed);
-    document.body.append(c);
-    await c.updateComplete;
-    expect(methodRun).toBe(1);
-    expect(methodDisposed).toBe(0);
-    expect(fieldRun).toEqual(methodRun);
-    expect(fieldDisposed).toEqual(methodDisposed);
-    c.remove();
-    expect(methodRun).toBe(1);
-    expect(methodDisposed).toBe(1);
-    expect(fieldRun).toEqual(methodRun);
-    expect(fieldDisposed).toEqual(methodDisposed);
-    document.body.append(c);
-    expect(methodRun).toBe(2);
-    expect(methodDisposed).toBe(1);
-    expect(fieldRun).toEqual(methodRun);
-    expect(fieldDisposed).toEqual(methodDisposed);
-    signal.set(2);
-    // wait for the effect to run
-    await sleep(1);
-    // run should be bumped by 2, the new value of the signal, and
-    // disposed should be bumped by 1 because the previous effect is
-    // disposed.
-    expect(methodRun).toBe(4);
-    expect(methodDisposed).toBe(2);
-    expect(fieldRun).toEqual(methodRun);
-    expect(fieldDisposed).toEqual(methodDisposed);
-    c.remove();
-    expect(methodRun).toBe(4);
-    expect(methodDisposed).toBe(3);
-    expect(fieldRun).toEqual(methodRun);
-    expect(fieldDisposed).toEqual(methodDisposed);
-});