@bodil/dom 0.1.0

package/src/component.ts

@@ -0,0 +1,607 @@
+import { assert, isIterable, isNullish, present } from "@bodil/core/assert";
+import { DisposableContext, toDisposable, type Disposifiable } from "@bodil/core/disposable";
+import { Signal } from "@bodil/signal";
+import {
+    adoptStyles,
+    getCompatibleStyle,
+    nothing,
+    render,
+    unsafeCSS,
+    type CSSResult,
+    type CSSResultOrNative,
+    type ReactiveController,
+    type ReactiveControllerHost,
+    type RenderOptions,
+    type RootPart,
+} from "lit";
+import type { Constructor } from "type-fest";
+
+import {
+    attributeConfig,
+    detectAttributeType,
+    fromAttribute,
+    toAttribute,
+    type AttributeConfig,
+} from "./decorators/attribute";
+import { connectedJobs } from "./decorators/connect";
+import { reactiveFields, signalForObject } from "./decorators/reactive";
+import { requiredProperties } from "./decorators/require";
+import { childElements } from "./dom";
+import { EmitterElement } from "./emitter";
+import { eventListener } from "./event";
+import { scheduler } from "./scheduler";
+import {
+    findSlot,
+    getOrSetQuery,
+    getOrSetSignal,
+    SlotChangeController,
+    type QuerySlotOptions,
+} from "./slot";
+
+export type { ReactiveController, ReactiveControllerHost } from "lit";
+export { attribute, type AttributeOptions } from "./decorators/attribute";
+export {
+    connect,
+    connectEffect,
+    type ConnectFunction,
+    type ConnectFunctionReturnValue,
+} from "./decorators/connect";
+export { reactive } from "./decorators/reactive";
+export { require } from "./decorators/require";
+export type { QuerySlotOptions } from "./slot";
+export type { CustomEventTypes } from "./emitter";
+
+(Symbol as any).metadata ??= Symbol.for("Symbol.metadata");
+
+export type UpdateConfig = {
+    viewTransition?: boolean;
+};
+
+function listsEqual<A>(as: Array<A>, bs: Array<A>): boolean {
+    return as.length === bs.length && as.every((a, index) => Object.is(a, bs[index]));
+}
+
+const finalised = Symbol("finalised");
+
+export type Deps = Array<typeof HTMLElement>;
+
+export type Declare<A extends keyof HTMLElementEventMap> = { [K in A]: never };
+
+export type ExtendSuper<C extends Component, A extends keyof HTMLElementEventMap> = {
+    [K in keyof C["emits"] | A]: never;
+};
+
+export type Emits<C> = C extends Component ? keyof C["emits"] : never;
+
+export type CSSStyleSpec = CSSResult | CSSStyleSheet | string;
+export type CSSStyleSpecArray = Array<CSSStyleSpec | CSSStyleSpecArray>;
+export type CSSStyleSpecDeclaration = CSSStyleSpec | CSSStyleSpecArray;
+
+function processCSSStyleSpec(spec: CSSStyleSpec) {
+    return getCompatibleStyle(typeof spec === "string" ? unsafeCSS(spec) : spec);
+}
+
+export abstract class Component
+    extends EmitterElement
+    implements ReactiveControllerHost, Disposable
+{
+    static deps: Deps = [];
+    static styles?: CSSStyleSpecDeclaration;
+    static shadowRootOptions: ShadowRootInit = { mode: "open" };
+    static initialisers = new Set<() => void>();
+
+    /** @ignore */
+    protected static attributeConfig = new Map<string, AttributeConfig>();
+    /** @ignore */
+    protected static elementStyles: Array<CSSResultOrNative> = [];
+    /** @ignore */
+    protected static requiredProperties = new Set<string | symbol>();
+    private static [finalised] = true;
+
+    renderOptions: RenderOptions = { host: this };
+    emits!: object;
+
+    readonly #controllers = new Set<ReactiveController>();
+    readonly #connectedContext = new DisposableContext();
+    #isUpdatePending = false;
+    #updateSignal?: Signal.Computed<void>;
+    readonly #updateSignalWatcher = new Signal.subtle.Watcher(() => this.requestUpdate());
+    #updateResult = Promise.withResolvers<boolean>();
+    readonly #stabilised = Promise.withResolvers<void>();
+    #rootPart?: RootPart;
+    #firstUpdate = false;
+    #initialised = false;
+    #viewTransitionRequested = false;
+
+    readonly renderRoot: ShadowRoot | HTMLElement = this.createRenderRoot();
+
+    get isUpdatePending(): boolean {
+        return this.#isUpdatePending;
+    }
+    get updateComplete(): Promise<boolean> {
+        return this.#updateResult.promise;
+    }
+    get hasStabilised(): Promise<void> {
+        return this.#stabilised.promise;
+    }
+
+    #abortController = new AbortController();
+    get abortSignal(): AbortSignal {
+        return this.#abortController.signal;
+    }
+
+    static addInitialiser(init: () => void) {
+        if (!Object.hasOwn(this, "initialisers")) {
+            this.initialisers = new Set();
+        }
+        this.initialisers.add(init);
+    }
+
+    static get observedAttributes(): Array<string> {
+        this.finalise();
+        return this.attributeConfig.keys().toArray();
+    }
+
+    private static finalise() {
+        if (!Object.hasOwn(this, finalised)) {
+            this[finalised] = true;
+            const parent = Object.getPrototypeOf(this) as typeof Component;
+            parent.finalise();
+
+            this.attributeConfig = new Map([
+                ...parent.attributeConfig,
+                ...((this[Symbol.metadata]?.[attributeConfig] as Map<string, AttributeConfig>) ??
+                    []),
+            ]);
+            this.requiredProperties = new Set([
+                ...parent.requiredProperties,
+                ...((this[Symbol.metadata]?.[requiredProperties] as Set<string | symbol>) ?? []),
+            ]);
+            this.initialisers = new Set([...parent.initialisers, ...this.initialisers]);
+            this.elementStyles = [...parent.elementStyles];
+            if (Object.hasOwn(this, "styles")) {
+                if (Array.isArray(this.styles)) {
+                    const sheets = new Set(
+                        (this.styles as Array<unknown>)
+                            .flat(Infinity)
+                            .reverse() as Array<CSSStyleSpec>,
+                    );
+                    for (const sheet of sheets) {
+                        this.elementStyles.unshift(processCSSStyleSpec(sheet));
+                    }
+                } else if (this.styles !== undefined) {
+                    this.elementStyles.push(processCSSStyleSpec(this.styles));
+                }
+            }
+        }
+    }
+
+    constructor() {
+        super();
+
+        // set up reactive fields, because decorators can't do this themselves
+        for (const field of (this.constructor[Symbol.metadata]?.[reactiveFields] as Set<
+            string | symbol
+        >) ?? []) {
+            const sig = signalForObject(this, field, () =>
+                Signal(undefined, { equals: Object.is }),
+            ) as Signal.State<unknown>;
+            Object.defineProperty(this, field, {
+                get() {
+                    return sig.get();
+                },
+                set(value) {
+                    sig.set(value);
+                },
+                enumerable: true,
+                configurable: true,
+            });
+        }
+
+        // run initialisers
+        for (const init of (this.constructor as typeof Component).initialisers) {
+            init.call(this);
+        }
+
+        this.#initialised = false;
+    }
+
+    protected connectedCallback() {
+        this.#connectedContext.dispose();
+        this.#controllers.forEach((c) => c.hostConnected?.());
+        this.#rootPart?.setConnected(true);
+
+        for (const [key, config] of (
+            this.constructor as typeof Component
+        ).attributeConfig.entries()) {
+            if (config.reflect) {
+                this.syncAttribute(key, config);
+            }
+        }
+
+        for (const job of connectedJobs(this)) {
+            const result = job.call(this);
+            const items = isNullish(result)
+                ? Iterator.from<Disposifiable>([])
+                : isIterable(result)
+                  ? Iterator.from(result)
+                  : Iterator.from([result]);
+            items.filter((i) => i !== undefined).forEach(this.useWhileConnected.bind(this));
+        }
+
+        this.useWhileConnected(
+            Signal.effect(() => {
+                if (this.hasRequiredProperties().get()) {
+                    if (!this.#initialised) {
+                        this.#initialised = true;
+                        this.firstInitialised();
+                    }
+                    this.initialised();
+                    this.requestUpdate();
+                }
+            }),
+        );
+
+        this.requestUpdate();
+    }
+
+    protected disconnectedCallback() {
+        if (this.#updateSignal !== undefined) {
+            this.#updateSignalWatcher.unwatch(this.#updateSignal);
+            this.#updateSignal = undefined;
+        }
+        this.#isUpdatePending = false;
+        this.#abortController.abort(
+            new DOMException(`${this.tagName} element disconnected`, "AbortError"),
+        );
+        this.#abortController = new AbortController();
+        this.#rootPart?.setConnected(false);
+        this.#controllers.forEach((c) => c.hostDisconnected?.());
+        this.#connectedContext.dispose();
+    }
+
+    protected attributeChangedCallback(
+        name: string,
+        old: string | null,
+        valueString: string | null,
+    ) {
+        if (old === valueString) {
+            return;
+        }
+        const attrConfig = (this.constructor as typeof Component).attributeConfig.get(name);
+        assert(attrConfig !== undefined);
+        const value = fromAttribute(
+            valueString,
+            present(
+                attrConfig.type,
+                `@attribute decorator for ${this.constructor.name}.${name} needs a type declaration, eg. @attribute({type: String})`,
+            ),
+        );
+        this[attrConfig.property as keyof this] = value as any;
+    }
+
+    private syncAttribute(name: string, config?: AttributeConfig) {
+        if (this.isConnected) {
+            config ??= (this.constructor as typeof Component).attributeConfig.get(name);
+            assert(config !== undefined);
+            if (config.reflect) {
+                const realValue = this[config.property as keyof this];
+                config.type ??= detectAttributeType(realValue);
+                const value = toAttribute(realValue, present(config.type));
+                const oldValue = this.getAttribute(name);
+                if (value !== oldValue) {
+                    if (value === null) {
+                        this.removeAttribute(name);
+                    } else {
+                        this.setAttribute(name, value);
+                    }
+                }
+            }
+        }
+    }
+
+    $signal<K extends keyof this & string, V extends this[K]>(prop: K): Signal<V> {
+        const _value = this[prop];
+        return signalForObject(this, prop, () => {
+            throw new TypeError(`Object has no reactive property ${JSON.stringify(prop)}`);
+        }) as Signal<V>;
+    }
+
+    addController(controller: ReactiveController) {
+        this.#controllers.add(controller);
+        if (this.renderRoot !== undefined && this.isConnected) {
+            controller.hostConnected?.();
+        }
+    }
+
+    removeController(controller: ReactiveController) {
+        this.#controllers.delete(controller);
+    }
+
+    protected createRenderRoot(): HTMLElement | ShadowRoot {
+        const renderRoot =
+            this.shadowRoot ??
+            this.attachShadow((this.constructor as typeof Component).shadowRootOptions);
+        adoptStyles(renderRoot, [...(this.constructor as typeof Component).elementStyles]);
+        this.renderOptions.renderBefore ??= renderRoot.firstChild;
+        return renderRoot;
+    }
+
+    requestUpdate(opts?: UpdateConfig) {
+        if (opts?.viewTransition === true) {
+            this.#viewTransitionRequested = true;
+        }
+        if (!this.isUpdatePending && this.isConnected && this.#initialised) {
+            this.#isUpdatePending = true;
+            this.#updateResult = Promise.withResolvers();
+            scheduler(this);
+        }
+    }
+
+    #hasRequiredProperties?: Signal.Computed<boolean>;
+    hasRequiredProperties(): Signal.Computed<boolean> {
+        if (this.#hasRequiredProperties === undefined) {
+            const requiredProperties = (this.constructor as typeof Component).requiredProperties;
+            this.#hasRequiredProperties = Signal.computed(
+                () => {
+                    return requiredProperties.size === 0
+                        ? true
+                        : requiredProperties
+                              .keys()
+                              .every((key) => (this as any)[key] !== undefined);
+                },
+                // every signal update is relevant, even if the signal value doesn't
+                // change, because the required values probably did.
+                { equals: () => false },
+            );
+        }
+        return this.#hasRequiredProperties;
+    }
+
+    protected async performUpdate() {
+        let didFirstUpdate = false;
+        const runUpdate = () => {
+            this.#controllers.forEach((c) => c.hostUpdate?.());
+            this.update();
+            this.#controllers.forEach((c) => c.hostUpdated?.());
+            if (!this.#firstUpdate) {
+                this.#firstUpdate = true;
+                this.firstUpdated();
+                didFirstUpdate = true;
+            }
+            this.updated();
+        };
+
+        if (!this.isConnected || !this.isUpdatePending) {
+            return;
+        }
+        try {
+            if (
+                this.#viewTransitionRequested &&
+                typeof document.startViewTransition === "function"
+            ) {
+                this.#viewTransitionRequested = false;
+                await document.startViewTransition(runUpdate).finished;
+            } else {
+                runUpdate();
+            }
+            this.#updateResult.resolve(true);
+            this.#isUpdatePending = false;
+            if (didFirstUpdate) {
+                await this.stabilise();
+                this.stabilised();
+                this.#stabilised.resolve();
+            }
+        } catch (e) {
+            this.#updateResult.reject(e);
+            this.#isUpdatePending = false;
+            if (didFirstUpdate) {
+                this.#stabilised.reject(e);
+            }
+        }
+    }
+
+    protected update() {
+        if (this.#updateSignal !== undefined) {
+            this.#updateSignalWatcher.unwatch(this.#updateSignal);
+        }
+        this.#updateSignal = Signal.computed(() => {
+            this.renderOptions.isConnected = this.isConnected;
+            this.#rootPart = render(this.render(), this.renderRoot, this.renderOptions);
+        });
+        this.#updateSignalWatcher.watch(this.#updateSignal);
+        this.#updateSignal.get();
+    }
+
+    protected findChildComponents(
+        root: Element | ShadowRoot = this.renderRoot,
+    ): IteratorObject<Component> {
+        let all: Array<Element> = childElements(root).toArray();
+        const top = [...all];
+        for (const el of top) {
+            all = [...all, ...this.findChildComponents(el)];
+        }
+        return Iterator.from(all).filter((el) => el instanceof Component);
+    }
+
+    protected async stabilise(): Promise<void> {
+        // wait for children to stabilise
+        const children = this.findChildComponents();
+        // eslint-disable-next-line no-console
+        await Promise.all(children.map((child) => child.hasStabilised)).catch(console.error);
+    }
+
+    protected updated(): void {
+        // called when an update has completed
+    }
+
+    protected firstUpdated() {
+        // called when the first update has completed, and before
+        // {@link Component.updated}.
+    }
+
+    protected stabilised() {
+        // called when the component has stabilised after its first update
+    }
+
+    protected initialised() {
+        // called when a property marked `@require` has changed and every
+        // such property is non-`undefined`.
+    }
+
+    protected firstInitialised() {
+        // called the first time all properties marked `@require` become
+        // defined, and before {@link Component.initialised}.
+    }
+
+    protected render(): unknown {
+        return nothing;
+    }
+
+    [Symbol.dispose]() {
+        for (const child of this.findChildComponents()) {
+            child[Symbol.dispose]();
+        }
+        this.disconnectedCallback();
+        (this.#rootPart as any)?._$clear?.();
+        this.#rootPart = undefined;
+        this.remove();
+    }
+
+    useWhileConnected(disposifiable: undefined): undefined;
+    useWhileConnected(disposifiable: null): null;
+    useWhileConnected(disposifiable: Disposifiable): Disposable;
+    useWhileConnected(disposifiable: Disposifiable | undefined): Disposable | undefined;
+    useWhileConnected(
+        disposifiable: Disposifiable | null | undefined,
+    ): Disposable | null | undefined;
+    useWhileConnected(
+        disposifiable: Disposifiable | null | undefined,
+    ): Disposable | null | undefined {
+        if (isNullish(disposifiable)) {
+            return disposifiable;
+        }
+        const disposable = toDisposable(disposifiable);
+        this.#connectedContext.use(disposable);
+        return disposable;
+    }
+
+    on<K extends keyof HTMLElementEventMap>(
+        type: K,
+        callback: (event: HTMLElementEventMap[K]) => void,
+        options?: AddEventListenerOptions | boolean,
+    ): Disposable {
+        return eventListener(this as Component, type, callback, options);
+    }
+
+    /**
+     * If an element that is either inside this element's shadow root or is a
+     * child of this element (ie. slotted) currently has focus, return that
+     * element. Otherwise, return null.
+     */
+    getFocusedElement(): Element | null {
+        return this.shadowRoot?.activeElement ?? this.querySelector(":focus");
+    }
+
+    query<El extends keyof HTMLElementTagNameMap>(selector: El): HTMLElementTagNameMap[El] | null;
+    query<El extends keyof SVGElementTagNameMap>(selector: El): SVGElementTagNameMap[El] | null;
+    query<El extends keyof MathMLElementTagNameMap>(
+        selector: El,
+    ): MathMLElementTagNameMap[El] | null;
+    /** @deprecated */
+    query<El extends keyof HTMLElementDeprecatedTagNameMap>(
+        selector: El,
+    ): HTMLElementDeprecatedTagNameMap[El] | null;
+    query(selector: string): Element | null;
+    query(selector: string): Element | null {
+        return this.renderRoot.querySelector(selector);
+    }
+
+    queryAll<El extends keyof HTMLElementTagNameMap>(
+        selector: El,
+    ): NodeListOf<HTMLElementTagNameMap[El]>;
+    queryAll<El extends keyof SVGElementTagNameMap>(
+        selector: El,
+    ): NodeListOf<SVGElementTagNameMap[El]>;
+    queryAll<El extends keyof MathMLElementTagNameMap>(
+        selector: El,
+    ): NodeListOf<MathMLElementTagNameMap[El]>;
+    /** @deprecated */
+    queryAll<El extends keyof HTMLElementDeprecatedTagNameMap>(
+        selector: El,
+    ): NodeListOf<HTMLElementDeprecatedTagNameMap[El]>;
+    queryAll(selector: string): NodeListOf<Element>;
+    queryAll(selector: string): NodeListOf<Element> {
+        return this.renderRoot.querySelectorAll(selector);
+    }
+
+    querySlot(
+        options: QuerySlotOptions & { nodes: true; reactive: true },
+    ): Signal.Computed<Array<Node>>;
+    querySlot(options: QuerySlotOptions & { nodes: true }): Array<Node>;
+    querySlot<T>(
+        options: QuerySlotOptions & { reactive: true; instanceOf: Constructor<T> },
+    ): Signal.Computed<Array<T>>;
+    querySlot(options: QuerySlotOptions & { reactive: true }): Signal.Computed<Array<Element>>;
+    querySlot<T>(options: QuerySlotOptions & { instanceOf: Constructor<T> }): Array<T>;
+    querySlot<El extends keyof HTMLElementTagNameMap>(
+        options: QuerySlotOptions & { reactive: true; selector: El },
+    ): Signal.Computed<Array<HTMLElementTagNameMap[El]>>;
+    querySlot<El extends keyof HTMLElementTagNameMap>(
+        options: QuerySlotOptions & { selector: El },
+    ): Array<HTMLElementTagNameMap[El]>;
+    querySlot<El extends keyof SVGElementTagNameMap>(
+        options: QuerySlotOptions & { reactive: true; selector: El },
+    ): Signal.Computed<Array<SVGElementTagNameMap[El]>>;
+    querySlot<El extends keyof SVGElementTagNameMap>(
+        options: QuerySlotOptions & { selector: El },
+    ): Array<SVGElementTagNameMap[El]>;
+    querySlot<El extends keyof MathMLElementTagNameMap>(
+        options: QuerySlotOptions & { reactive: true; selector: El },
+    ): Signal.Computed<Array<MathMLElementTagNameMap[El]>>;
+    querySlot<El extends keyof MathMLElementTagNameMap>(
+        options: QuerySlotOptions & { selector: El },
+    ): Array<MathMLElementTagNameMap[El]>;
+    /** @deprecated */
+    querySlot<El extends keyof HTMLElementDeprecatedTagNameMap>(
+        options: QuerySlotOptions & { reactive: true; selector: El },
+    ): Signal.Computed<Array<HTMLElementDeprecatedTagNameMap[El]>>;
+    /** @deprecated */
+    querySlot<El extends keyof HTMLElementDeprecatedTagNameMap>(
+        options: QuerySlotOptions & { selector: El },
+    ): Array<HTMLElementDeprecatedTagNameMap[El]>;
+    querySlot(options?: QuerySlotOptions): Array<Element>;
+    querySlot(
+        options?: QuerySlotOptions,
+    ):
+        | Array<Node>
+        | Array<Element>
+        | Signal.Computed<Array<Node>>
+        | Signal.Computed<Array<Element>> {
+        const { slot, selector, instanceOf, nodes, reactive } = options ?? {};
+        const query = getOrSetQuery(this, options ?? {}, () => (slotEl: HTMLSlotElement | null) => {
+            const elements = isNullish(slotEl)
+                ? []
+                : nodes === true
+                  ? slotEl.assignedNodes(options)
+                  : slotEl.assignedElements(options);
+            const selectedElements =
+                selector !== undefined && nodes !== true
+                    ? (elements as Array<Element>).filter((node) => node.matches(selector))
+                    : elements;
+            return instanceOf !== undefined
+                ? selectedElements.filter((el) => el instanceof instanceOf)
+                : selectedElements;
+        });
+        const slotEl = findSlot(this, slot);
+        if (reactive !== true) {
+            return query(slotEl);
+        }
+        const sig = getOrSetSignal(this, query, () => {
+            const sig = Signal(query(slotEl), { equals: listsEqual });
+            this.addController(new SlotChangeController(this, slot, sig, query));
+            return sig.readOnly();
+        });
+        return sig;
+    }
+}

package/src/css.ts

@@ -0,0 +1,69 @@
+import { assert } from "@bodil/core/assert";
+import { None, Option, Some } from "@bodil/opt";
+
+export type Pixels = number;
+
+/**
+ * Get a computed CSS property for an element.
+ */
+export function getComputedProperty(element: Element, property: string): Option<string> {
+    return Option.from(window.getComputedStyle(element)?.getPropertyValue(property));
+}
+
+const NUMBER_MATCHER = /^(?<number>[+-]?\d+(?:[.]\d+)?(?:e\d+)?)(?<unit>[a-zA-Z]+)$/;
+
+function parseWithUnit(value: string): Option<{ number: number; unit: string }> {
+    const match = NUMBER_MATCHER.exec(value.trim());
+    if (match?.groups === undefined) {
+        return None;
+    }
+    assert(match.groups.number !== undefined);
+    assert(match.groups.unit !== undefined);
+    const number = Number.parseFloat(match.groups.number);
+    if (Number.isNaN(number)) {
+        return None;
+    }
+    return Some({ number, unit: match.groups.unit });
+}
+
+/**
+ * Parse a CSS size value with units into pixels.
+ */
+export function parseSize(value: string): Option<Pixels> {
+    return parseWithUnit(value).chain(({ number, unit }) => {
+        switch (unit) {
+            case "px":
+                return Some(number);
+            case "cm":
+                return Some((number * 96) / 2.54);
+            case "mm":
+                return Some((number * 96) / 0.254);
+            case "Q":
+                return Some((number * 96) / 0.0635);
+            case "in":
+                return Some(number * 96);
+            case "pc":
+                return Some((number * 96) / 6);
+            case "pt":
+                return Some((number * 96) / 72);
+            default:
+                return None;
+        }
+    });
+}
+
+/**
+ * Parse a CSS time value with units into milliseconds.
+ */
+export function parseTime(value: string): Option<number> {
+    return parseWithUnit(value).chain(({ number, unit }) => {
+        switch (unit) {
+            case "ms":
+                return Some(number);
+            case "s":
+                return Some(number * 1000);
+            default:
+                return None;
+        }
+    });
+}