@bodil/dom 0.1.9 → 0.2.0

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>,
@@ -281,7 +309,7 @@ function accessor<C extends Component, T>(
         let initValue: Option<T> = None;
         const getSig = (obj: object) =>
             signalForObject(obj, context.name, () =>
-                Signal(initValue.unwrapExact(), {
+                Signal.from(initValue.unwrapExact(), {
                     equals: Object.is,
                 }),
             ) as Signal.State<T>;

package/src/decorators/reactive.test.ts

@@ -5,7 +5,7 @@ import { Component, reactive } from "../component";
 import { customElement } from "lit/decorators.js";
 
 test("@reactive", () => {
-    const name = Signal("Joe");
+    const name = Signal.from("Joe");
     class ReactiveTestClass {
         @reactive get name(): string {
             return name.get();

package/src/decorators/reactive.ts

@@ -5,13 +5,13 @@ import type { ClassGetterDecoratorResult, ClassGetterDecoratorTarget } from "./t
 
 export const reactiveFields = Symbol("reactiveFields");
 
-const signalCache = new WeakMap<object, Record<PropertyKey, Signal<unknown>>>();
+const signalCache = new WeakMap<object, Record<PropertyKey, Signal.Any<unknown>>>();
 
 export function signalForObject(
     obj: object,
     key: string | symbol,
-    createSignal: () => Signal<unknown>,
-): Signal<unknown> {
+    createSignal: () => Signal.Any<unknown>,
+): Signal.Any<unknown> {
     let sigs = signalCache.get(obj);
     if (sigs === undefined) {
         sigs = {};
@@ -48,7 +48,7 @@ export function reactive<C extends object, T>(
         case "accessor": {
             const getSig = (obj: object) =>
                 signalForObject(obj, context.name, () =>
-                    Signal((value as ClassAccessorDecoratorTarget<unknown, T>).get.call(obj), {
+                    Signal.from((value as ClassAccessorDecoratorTarget<unknown, T>).get.call(obj), {
                         equals: Object.is,
                     }),
                 ) as Signal.State<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

@@ -1,9 +1,15 @@
-import { assertNever, isNullish, unreachable } from "@bodil/core/assert";
-import { toDisposable } from "@bodil/core/disposable";
+/**
+ * DOM manipulation tools.
+ * @module
+ */
+
+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";
 
 /**
@@ -89,6 +95,9 @@ export function visibilityObserver(
     });
 }
 
+/**
+ * An iterator for traversing siblings of a DOM node.
+ */
 export class DOMIterator extends Iterator<Node> {
     private currentNode: Node | null;
     private goingForward = true;
@@ -120,18 +129,27 @@ export class DOMIterator extends Iterator<Node> {
     }
 }
 
-export function childElements(parent: Element | DocumentFragment | null): IteratorObject<Element> {
-    if (parent === null) {
+/**
+ * Return all descendants of `root` which match the `predicate` function.
+ */
+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. */
@@ -188,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 }),
+                );
             });
         }),
     );
@@ -217,6 +243,10 @@ export function isAnimating(el: HTMLElement): boolean {
     return path.some((item) => item.getAnimations().length > 0);
 }
 
+/**
+ * Find the first {@link EventTarget} going up an {@link Event.composedPath}
+ * which matches the given `predicate`.
+ */
 export function findEventTarget<T extends EventTarget>(
     e: Event,
     predicate: (target: EventTarget) => target is T,
@@ -309,6 +339,16 @@ export function findAncestor(
     return undefined;
 }
 
+/**
+ * Test whether an {@link Element} should be considered an editor, ie. something
+ * which expects to consume `keydown` events.
+ *
+ * Use this if you have globally defined keybindings which should not be
+ * triggered when typing into an input field or other kind of editor.
+ *
+ * {@link HTMLInputElement}s, {@link HTMLTextAreaElement}s and elements with the
+ * `contenteditable` attribute set are defined as editors.
+ */
 export function isEditor(element: Element | null | undefined): boolean {
     if (isNullish(element)) {
         return false;
@@ -338,6 +378,11 @@ const scrollToItemOptionsDefault: Required<
     padEnd: 0,
 };
 
+/**
+ * Scroll an element into view.
+ *
+ * This is {@link Element.scrollIntoView} for advanced users.
+ */
 export function scrollToItem(el: HTMLElement, scrollToItemOptions: ScrollToItemOptions): void {
     const options: Required<ScrollToItemOptions> = {
         ...scrollToItemOptionsDefault,
@@ -391,8 +436,35 @@ 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
+/**
+ * A {@link ReactiveController} which tracks whether a slot is populated.
+ */
 export class HasSlotController implements ReactiveController {
     host: ReactiveControllerHost & Element;
     slotNames: Array<string> = [];

package/src/emitter.ts

@@ -62,6 +62,14 @@ export type ElementEmits<C> = C extends EmitterElement ? keyof C["emits"] : neve
  * }
  */
 export class EmitterElement extends HTMLElement {
+    /**
+     * Declares the events this element can emit.
+     *
+     * @example
+     * class MyElement extends EmitterElement {
+     *     emits!: Emits<"my-event" | "my-other-event";
+     * }
+     */
     emits!: { [K in keyof HTMLElementEventMap]?: never };
 
     /**

package/src/event.ts

@@ -16,6 +16,10 @@ import type { Present } from "@bodil/core/types";
  * `__events!: MyEventMap` as a property on the class.
  */
 export interface DeclareEvents<Events> extends EventTarget {
+    /**
+     * @internal
+     * @ignore
+     */
     __events: Events;
 }
 

package/src/geometry.ts

@@ -1,3 +1,11 @@
+/**
+ * Geometry tools.
+ * @module
+ */
+
+/**
+ * Valid types representing rectangles.
+ */
 export type Rectangle = DOMRect | Element;
 
 function rectFor(value: Rectangle): DOMRect {

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/signal.test.ts

@@ -7,7 +7,7 @@ import { Component } from "./component";
 import { watch } from "./signal";
 
 test("watch directive", async () => {
-    const counter = Signal(1);
+    const counter = Signal.from(1);
     let renders = 0;
 
     @customElement("watch-directive-test")
@@ -48,7 +48,7 @@ test("watch directive", async () => {
 });
 
 test("watch directive with mapper function", async () => {
-    const counter = Signal(1);
+    const counter = Signal.from(1);
     let renders = 0;
 
     @customElement("watch-directive-mapper-test")

package/src/signal.ts

@@ -1,3 +1,8 @@
+/**
+ * Lit directives for working with signals.
+ * @module
+ */
+
 import { defer } from "@bodil/core/async";
 import { id } from "@bodil/core/fun";
 import { Signal } from "@bodil/signal";
@@ -23,7 +28,8 @@ const hostlessWatcher = new Signal.subtle.Watcher(() => {
     }
 });
 
-class WatchDirective<T> extends AsyncDirective {
+/** @internal */
+export class WatchDirective<T> extends AsyncDirective {
     #host?: Component;
     #signal?: Signal.State<T> | Signal.Computed<T>;
     #mapper: (value: T) => unknown = id;
@@ -86,13 +92,18 @@ class WatchDirective<T> extends AsyncDirective {
     }
 }
 
+/**
+ * @internal
+ * @ignore
+ */
 export type WatchDirectiveFunction = <T>(
-    signal: Signal.State<T> | Signal.Computed<T>,
+    signal: Signal.Any<T>,
     mapFn?: (value: T) => unknown,
 ) => DirectiveResult<typeof WatchDirective<T>>;
 
 /**
  * Render a signal and subscribe to it, updating the part when the signal
  * changes independently of the host component.
+ * @function
  */
 export const watch = directive(WatchDirective) as WatchDirectiveFunction;

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;
+}