@bodil/dom 0.1.0

package/src/dom.ts

@@ -0,0 +1,456 @@
+import { assertNever, isNullish, unreachable } from "@bodil/core/assert";
+import { toDisposable } from "@bodil/core/disposable";
+import type { ReactiveController, ReactiveControllerHost } from "lit";
+import type { OptionalKeysOf } from "type-fest";
+
+import type { Pixels } from "./css";
+import { contains } from "./geometry";
+
+/**
+ * Given the name of a custom DOM element registered in
+ * {@link Window.customElements}, test whether an object is an instance of that
+ * element.
+ *
+ * The element must also be declared in {@link HTMLElementTagNameMap} for the
+ * type checker to follow along.
+ */
+export function isElement<Name extends keyof HTMLElementTagNameMap>(
+    name: Name,
+    item: unknown,
+): item is HTMLElementTagNameMap[Name] {
+    const constructor = customElements.get(name);
+    return constructor === undefined ? false : item instanceof constructor;
+}
+
+/**
+ * Call {@link window.requestAnimationFrame} with the provided callback and return a
+ * {@link Disposable} which will cancel the request when disposed.
+ */
+export function animationFrame(fn: (time: number) => void): Disposable {
+    // @ts-ignore requestAnimationFrame is only available in browser contexts
+    let id: number | null = globalThis.requestAnimationFrame((time) => {
+        id = null;
+        fn(time);
+        disposable[Symbol.dispose]();
+    });
+    const disposable = toDisposable(() => {
+        if (id !== null) {
+            // @ts-ignore cancelAnimationFrame is only available in browser contexts
+            globalThis.cancelAnimationFrame(id);
+        }
+    });
+    return disposable;
+}
+
+/**
+ * Return a promise which will resolve when the next animation frame happens.
+ */
+export function awaitFrame(): Promise<void> {
+    return new Promise((resolve) => animationFrame(() => resolve()));
+}
+
+export function intersectionObserver(
+    element: Element,
+    callback: IntersectionObserverCallback,
+    options?: IntersectionObserverInit,
+): Disposable {
+    let observer: ResizeObserver | undefined = new IntersectionObserver(callback, options);
+    observer.observe(element);
+    return toDisposable(() => {
+        observer?.disconnect();
+        observer = undefined;
+    });
+}
+
+export function resizeObserver(
+    element: Element,
+    callback: ResizeObserverCallback,
+    options?: ResizeObserverOptions,
+): Disposable {
+    let observer: ResizeObserver | undefined = new ResizeObserver(callback);
+    observer.observe(element, options);
+    return toDisposable(() => {
+        observer?.disconnect();
+        observer = undefined;
+    });
+}
+
+export function visibilityObserver(
+    element: Element,
+    callback: (oldState: boolean, newState: boolean) => void,
+): Disposable {
+    let oldState = false;
+    return intersectionObserver(element, (entries) => {
+        const newState = entries[0].isIntersecting;
+        if (oldState !== newState) {
+            callback(oldState, newState);
+        }
+        oldState = newState;
+    });
+}
+
+export class DOMIterator extends Iterator<Node> {
+    private currentNode: Node | null;
+    private goingForward = true;
+
+    constructor(startNode: Node | null) {
+        super();
+        this.currentNode = startNode;
+    }
+
+    reverse(): this {
+        this.goingForward = !this.goingForward;
+        return this;
+    }
+
+    skip(): this {
+        this.next();
+        return this;
+    }
+
+    next(): IteratorResult<Node> {
+        if (this.currentNode === null) {
+            return { done: true, value: undefined };
+        }
+        const resultNode = this.currentNode;
+        this.currentNode = this.goingForward
+            ? this.currentNode.nextSibling
+            : this.currentNode.previousSibling;
+        return { done: false, value: resultNode };
+    }
+}
+
+export function childElements(parent: Element | DocumentFragment | null): IteratorObject<Element> {
+    if (parent === null) {
+        return Iterator.from([]);
+    }
+    const iter = function* () {
+        let el = parent.firstElementChild;
+        while (el !== null) {
+            yield el;
+            el = el.nextElementSibling;
+        }
+    };
+    return Iterator.from(iter());
+}
+
+/** Test whether the user has asked for reduced motion. */
+export function prefersReducedMotion(): boolean {
+    return window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+}
+
+/**
+ * Animates an element using keyframes. Returns a promise that resolves after
+ * the animation completes or gets cancelled.
+ */
+export function animateTo(
+    el: HTMLElement,
+    keyframes: Array<Keyframe>,
+    options?: KeyframeAnimationOptions,
+): Promise<void> {
+    return new Promise((resolve) => {
+        if (options?.duration === Infinity) {
+            throw new Error("Promise-based animations must be finite.");
+        }
+
+        const animation = el.animate(keyframes, {
+            ...options,
+            duration: prefersReducedMotion() ? 0 : options!.duration,
+        });
+
+        animation.addEventListener("cancel", () => resolve(), { once: true });
+        animation.addEventListener("finish", () => resolve(), { once: true });
+    });
+}
+
+/**
+ * Stops all active animations on the target element. Returns a promise that
+ * resolves after all animations are cancelled.
+ */
+export async function stopAnimations(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 });
+                animation.cancel();
+            });
+        }),
+    );
+}
+
+/**
+ * Wait for any animations running on the element to complete.
+ */
+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 });
+            });
+        }),
+    );
+}
+
+/**
+ * Check if any animations are currently active on an element.
+ */
+export function isAnimating(el: HTMLElement): boolean {
+    function findParent(el: HTMLElement): HTMLElement | undefined {
+        if (!isNullish(el.parentElement)) {
+            return el.parentElement;
+        }
+        if (el.parentNode instanceof ShadowRoot && el.parentNode.host instanceof HTMLElement) {
+            return el.parentNode.host;
+        }
+        return undefined;
+    }
+    const path = [el];
+    let current: HTMLElement | undefined = el;
+    while ((current = findParent(current))) {
+        path.push(current);
+    }
+    return path.some((item) => item.getAnimations().length > 0);
+}
+
+export function findEventTarget<T extends EventTarget>(
+    e: Event,
+    predicate: (target: EventTarget) => target is T,
+): T | null {
+    const path = e.composedPath();
+    while (true) {
+        const target = path.pop();
+        if (target === undefined) {
+            return null;
+        }
+        if (predicate(target)) {
+            return target;
+        }
+    }
+}
+
+/**
+ * Dig through shadow roots to find the actual element that currently has focus.
+ * If nothing has focus in or below the given root, return undefined.
+ */
+export function findActiveElement(
+    root: Document | ShadowRoot | null = document,
+): Element | undefined {
+    return activeElementPath(root)?.pop();
+}
+
+/**
+ * As {@link findActiveElement}, but returns a list of the active elements as
+ * seen by each {@link Document} and {@link ShadowRoot} down to the actually
+ * active element.
+ */
+export function activeElementPath(
+    root: Document | ShadowRoot | null = document,
+): Array<Element> | undefined {
+    if (root === null) {
+        return undefined;
+    }
+    const path = [];
+    let currentRoot = root;
+    while (true) {
+        const element = currentRoot.activeElement;
+        if (element === null) {
+            return undefined;
+        }
+        path.push(element);
+        if (element.shadowRoot !== null && element.shadowRoot.activeElement !== null) {
+            currentRoot = element.shadowRoot;
+        } else {
+            return path;
+        }
+    }
+}
+
+/**
+ * Find the first ancestor of the given `child` element matching the provided
+ * `predicate` function, walking up through shadow root boundaries.
+ */
+export function findAncestor<T extends Element>(
+    child: Element | null | undefined,
+    predicate: (el: Element) => el is T,
+): T | undefined;
+export function findAncestor(
+    child: Element | null | undefined,
+    predicate: (el: Element) => boolean,
+): Element | undefined;
+export function findAncestor(
+    child: Element | null | undefined,
+    predicate: (el: Element) => boolean,
+): Element | undefined {
+    if (isNullish(child)) {
+        return undefined;
+    }
+    function nextParent(child: Element): Element | undefined {
+        const node = child.parentNode;
+        if (node instanceof Element) {
+            return node;
+        }
+        if (node instanceof ShadowRoot) {
+            return node.host;
+        }
+        return undefined;
+    }
+    let parent = nextParent(child);
+    while (parent !== undefined) {
+        if (predicate(parent)) {
+            return parent;
+        }
+        parent = nextParent(parent);
+    }
+    return undefined;
+}
+
+export function isEditor(element: Element | null | undefined): boolean {
+    if (isNullish(element)) {
+        return false;
+    }
+    return (
+        element instanceof HTMLInputElement ||
+        element instanceof HTMLTextAreaElement ||
+        element.getAttribute("contenteditable") === "true"
+    );
+}
+
+export type ScrollAlign = "start" | "end" | "center" | "fit";
+export type ScrollToItemOptions = {
+    viewport: HTMLElement;
+    axis: "horizontal" | "vertical";
+    align: ScrollAlign;
+    behavior?: ScrollBehavior;
+    padStart?: Pixels;
+    padEnd?: Pixels;
+};
+
+const scrollToItemOptionsDefault: Required<
+    Pick<ScrollToItemOptions, OptionalKeysOf<ScrollToItemOptions>>
+> = {
+    behavior: "auto",
+    padStart: 0,
+    padEnd: 0,
+};
+
+export function scrollToItem(el: HTMLElement, scrollToItemOptions: ScrollToItemOptions): void {
+    const options: Required<ScrollToItemOptions> = {
+        ...scrollToItemOptionsDefault,
+        ...scrollToItemOptions,
+    };
+
+    if (options.behavior === "auto") {
+        options.behavior = prefersReducedMotion() ? "instant" : "smooth";
+    }
+
+    const horiz = options.axis === "horizontal";
+    const getTop = horiz ? (rect: DOMRect) => rect.left : (rect: DOMRect) => rect.top;
+    const getBottom = horiz ? (rect: DOMRect) => rect.right : (rect: DOMRect) => rect.bottom;
+    const getHeight = horiz ? (rect: DOMRect) => rect.width : (rect: DOMRect) => rect.height;
+
+    const viewRect = options.viewport.getBoundingClientRect();
+    const childRect = el.getBoundingClientRect();
+    const childTop = getTop(childRect) - getTop(viewRect);
+    const align = options.align;
+    let top = 0;
+    if (align === "start" || getHeight(childRect) > getHeight(viewRect)) {
+        top = childTop - options.padStart;
+    } else if (align === "end") {
+        top = childTop + getHeight(childRect) - getHeight(viewRect) + options.padEnd;
+    } else if (align === "center") {
+        top = childTop + getHeight(childRect) / 2 - getHeight(viewRect) / 2;
+    } else if (align === "fit") {
+        if (contains(childRect, viewRect)) {
+            return;
+        }
+        if (getTop(childRect) < getTop(viewRect)) {
+            return scrollToItem(el, { ...options, align: "start" });
+        }
+        if (getBottom(childRect) > getBottom(viewRect)) {
+            return scrollToItem(el, { ...options, align: "end" });
+        }
+        return unreachable();
+    } else {
+        assertNever(align);
+    }
+    if (horiz) {
+        options.viewport.scroll({
+            left: top + options.viewport.scrollLeft,
+            behavior: options.behavior,
+        });
+    } else {
+        options.viewport.scroll({
+            top: top + options.viewport.scrollTop,
+            behavior: options.behavior,
+        });
+    }
+}
+
+// HasSlotController nicked largely verbatim from Shoelace
+// https://github.com/shoelace-style/shoelace/blob/next/src/internal/slot.ts
+export class HasSlotController implements ReactiveController {
+    host: ReactiveControllerHost & Element;
+    slotNames: Array<string> = [];
+
+    constructor(host: ReactiveControllerHost & Element, ...slotNames: Array<string>) {
+        (this.host = host).addController(this);
+        this.slotNames = slotNames;
+    }
+
+    private hasDefaultSlot() {
+        return [...this.host.childNodes].some((node) => {
+            if (node.nodeType === node.TEXT_NODE && node.textContent!.trim() !== "") {
+                return true;
+            }
+
+            if (node.nodeType === node.ELEMENT_NODE) {
+                const el = node as HTMLElement;
+                const tagName = el.tagName.toLowerCase();
+
+                // Ignore visually hidden elements since they aren't rendered
+                if (tagName === "sl-visually-hidden") {
+                    return false;
+                }
+
+                // If it doesn't have a slot attribute, it's part of the default slot
+                if (!el.hasAttribute("slot")) {
+                    return true;
+                }
+            }
+
+            return false;
+        });
+    }
+
+    private hasNamedSlot(name: string) {
+        return this.host.querySelector(`:scope > [slot="${name}"]`) !== null;
+    }
+
+    test(slotName: string) {
+        return slotName === "[default]" ? this.hasDefaultSlot() : this.hasNamedSlot(slotName);
+    }
+
+    hostConnected() {
+        this.host.shadowRoot!.addEventListener("slotchange", this.handleSlotChange);
+    }
+
+    hostDisconnected() {
+        this.host.shadowRoot!.removeEventListener("slotchange", this.handleSlotChange);
+    }
+
+    handleSlotChange = (event: Event) => {
+        const slot = event.target as HTMLSlotElement;
+
+        if (
+            (this.slotNames.includes("[default]") && !slot.name) ||
+            (slot.name && this.slotNames.includes(slot.name))
+        ) {
+            this.host.requestUpdate();
+        }
+    };
+}

package/src/emitter.ts

@@ -0,0 +1,32 @@
+export type CustomEventTypes<T extends keyof HTMLElementEventMap> = {
+    [Key in T]: HTMLElementEventMap[Key] extends CustomEvent<infer D> ? D : never;
+};
+
+export class EmitterElement extends HTMLElement {
+    emits!: { [K in keyof HTMLElementEventMap]?: never };
+
+    emit<
+        M extends CustomEventTypes<keyof this["emits"] & keyof HTMLElementEventMap>,
+        K extends Extract<keyof M, string>,
+        D extends M[K],
+    >(name: K, detail?: D, options?: EventInit): CustomEvent<D> {
+        const event = new CustomEvent(name, {
+            bubbles: true,
+            composed: true,
+            detail,
+            ...(options ?? {}),
+        });
+        this.dispatchEvent(event);
+        return event;
+    }
+
+    emitEvent<
+        K extends keyof this["emits"] & keyof HTMLElementEventMap,
+        E extends HTMLElementEventMap[K],
+        C extends new (type: string, ...args: Args) => E,
+        Args extends Array<any>,
+    >(name: K, constructor: C, ...args: Args) {
+        const event = new constructor(name, ...args);
+        this.dispatchEvent(event);
+    }
+}

package/src/event.test.ts

@@ -0,0 +1,22 @@
+import { expect, expectTypeOf, test } from "vitest";
+
+import { eventListener } from "./event";
+
+test("eventListener", () => {
+    const button = document.createElement("button");
+    let clicked = 0;
+    const listener = eventListener(button, "click", (e) => {
+        expectTypeOf(e).toEqualTypeOf<PointerEvent>();
+        expect(e.target).toBe(button);
+        clicked++;
+    });
+    expect(clicked).toBe(0);
+    button.click();
+    expect(clicked).toBe(1);
+    listener[Symbol.dispose]();
+    button.click();
+    expect(clicked).toBe(1);
+
+    // @ts-expect-error: unknown event should be a type error
+    eventListener(button, "chaos with Ed Miliband", () => {})[Symbol.dispose]();
+});

package/src/event.ts

@@ -0,0 +1,74 @@
+/**
+ * Utility types for DOM events.
+ * @module
+ */
+
+import { toDisposable } from "@bodil/core/disposable";
+import type { Present } from "@bodil/core/types";
+
+/**
+ * An interface a type can extend to associate a map of event names to event
+ * types with itself, in the style of `HTMLElementEventMap` et al. This allows
+ * the type system to discover the events available for a specific
+ * {@link EventTarget} descendant.
+ *
+ * If you need to implement this for a class you're defining, you need to add
+ * `__events!: MyEventMap` as a property on the class.
+ */
+export interface DeclareEvents<Events> extends EventTarget {
+    __events: Events;
+}
+
+/**
+ * Get the `Events` type associated with a type that extends
+ * {@linkcode DeclareEvents}`<Events>`.
+ *
+ * Using it on a type that doesn't extend {@link DeclareEvents} results in a
+ * type error.
+ */
+export type EventMapFor<T extends DeclareEvents<unknown>> = Present<T["__events"]>;
+
+/**
+ * Get the `Events` type associated with a type that extends
+ * {@linkcode DeclareEvents}`<Events>`.
+ *
+ * A type that doesn't extend {@link DeclareEvents} resolves to an object which
+ * will accept all string keys.
+ */
+export type ExtractEventMap<T> =
+    T extends DeclareEvents<infer Events> ? Events : { [key: string]: Event };
+
+declare global {
+    interface AbortSignal extends DeclareEvents<AbortSignalEventMap> {}
+    interface Animation extends DeclareEvents<AnimationEventMap> {}
+    interface BroadcastChannel extends DeclareEvents<BroadcastChannelEventMap> {}
+    interface Document extends DeclareEvents<DocumentEventMap> {}
+    interface EventSource extends DeclareEvents<EventSourceEventMap> {}
+    interface HTMLBodyElement extends DeclareEvents<HTMLBodyElementEventMap> {}
+    interface HTMLElement extends DeclareEvents<HTMLElementEventMap> {}
+    interface MessagePort extends DeclareEvents<MessagePortEventMap> {}
+    interface ShadowRoot extends DeclareEvents<ShadowRootEventMap> {}
+    interface SVGElement extends DeclareEvents<SVGElementEventMap> {}
+    interface SVGSVGElement extends DeclareEvents<SVGSVGElementEventMap> {}
+    interface WebSocket extends DeclareEvents<WebSocketEventMap> {}
+    interface Window extends DeclareEvents<WindowEventMap> {}
+    interface Worker extends DeclareEvents<WorkerEventMap> {}
+}
+
+/**
+ * Attach an event listener to an {@link EventTarget} and return a
+ * {@link Disposable} which will remove the listener when disposed.
+ */
+export function eventListener<
+    T extends EventTarget,
+    M extends ExtractEventMap<T>,
+    K extends keyof M & string,
+>(
+    target: T,
+    type: K,
+    callback: (e: M[K]) => any,
+    options?: AddEventListenerOptions | boolean,
+): Disposable {
+    target.addEventListener(type, callback as EventListener, options);
+    return toDisposable(() => target.removeEventListener(type, callback as EventListener));
+}