@bodil/dom 0.1.9 → 0.2.0

package/src/component.ts

@@ -1,4 +1,9 @@
-import { isIterable, isNullish } from "@bodil/core/assert";
+/**
+ * Web component base class.
+ * @module
+ */
+
+import { isNullish, present } from "@bodil/core/assert";
 import { DisposableContext, toDisposable, type Disposifiable } from "@bodil/core/disposable";
 import { Signal } from "@bodil/signal";
 import {
@@ -9,6 +14,8 @@ import {
     unsafeCSS,
     type CSSResult,
     type CSSResultOrNative,
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    type html,
     type ReactiveController,
     type ReactiveControllerHost,
     type RenderOptions,
@@ -22,10 +29,9 @@ import {
     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 { findDescendants } from "./dom";
 import { EmitterElement } from "./emitter";
 import { eventListener } from "./event";
 import { scheduler } from "./scheduler";
@@ -47,12 +53,6 @@ export {
     type AttributeGetterSetterOptions,
     type AttributeType,
 } from "./decorators/attribute";
-export {
-    connect,
-    connectEffect,
-    type ConnectFunction,
-    type ConnectFunctionReturnValue,
-} from "./decorators/connect";
 export { reactive } from "./decorators/reactive";
 export { require } from "./decorators/require";
 export { EmitterElement } from "./emitter";
@@ -67,6 +67,8 @@ export type UpdateConfig = {
 
 const finalised = Symbol("finalised");
 
+export type Disposables = Disposifiable | Iterable<Disposifiable | undefined> | undefined | void;
+
 export type Deps = Array<typeof HTMLElement>;
 
 export type CSSStyleSpec = CSSResult | CSSStyleSheet | string;
@@ -77,6 +79,10 @@ function processCSSStyleSpec(spec: CSSStyleSpec) {
     return getCompatibleStyle(typeof spec === "string" ? unsafeCSS(spec) : spec);
 }
 
+/**
+ * Error thrown when a {@link Component.render} method causes infinite
+ * re-renders.
+ */
 export class ComponentUpdateLoopError extends Error {
     constructor(message?: string, options?: ErrorOptions) {
         super(message, options);
@@ -84,14 +90,49 @@ export class ComponentUpdateLoopError extends Error {
     }
 }
 
+/**
+ * Base class for web components.
+ */
 export abstract class Component
     extends EmitterElement
     implements ReactiveControllerHost, Disposable
 {
+    /**
+     * Declare the web components this element will be using.
+     *
+     * This is a convenient place to make sure these web components will be
+     * defined when your component is rendered. It has no effect otherwise.
+     *
+     * @example
+     * class MyComponent extends Component {
+     *     static deps: Deps = [ MySubcomponent, MyOtherSubcomponent ];
+     * }
+     */
     static deps: Deps = [];
+
+    /**
+     * Declare CSS style sheets which will be installed for this web component.
+     *
+     * Style sheets can be either {@link CSSStyleSheet} objects,
+     * Lit template {@link CSSResult}s, or strings.
+     *
+     * If a superclass also declares the `styles` property, this list will be
+     * appended to the superclass's list.
+     *
+     * @example
+     * class MyComponent extends Component {
+     *     static styles = css`
+     *         :host {
+     *             border: 2px solid red;
+     *         }
+     *     `;
+     * }
+     */
     static styles?: CSSStyleSpecDeclaration;
+
     static shadowRootOptions: ShadowRootInit = { mode: "open" };
-    static initialisers = new Set<() => void>();
+
+    private static initialisers = new Set<() => void>();
 
     /** @ignore */
     protected static attributeConfig = new Map<string, AttributeConfig>();
@@ -106,6 +147,7 @@ export abstract class Component
 
     readonly #controllers = new Set<ReactiveController>();
     readonly #connectedContext = new DisposableContext();
+    readonly #finalCleanupContext = new DisposableContext();
     #dirty = false;
     #isUpdatePending = false;
     #updateSignal?: Signal.Computed<void>;
@@ -120,29 +162,59 @@ export abstract class Component
 
     readonly renderRoot: ShadowRoot | HTMLElement = this.createRenderRoot();
 
+    /**
+     * True if this component had scheduled an update which has not yet started.
+     */
     get isUpdatePending(): boolean {
         return this.#isUpdatePending;
     }
+
     get updateComplete(): Promise<boolean> {
         return this.#updateResult.promise;
     }
+
+    /**
+     * A {@link Promise} which resolves when this component has completed its
+     * first update and considers itself stabilised, according to the
+     * {@link Component.stabilise} method.
+     *
+     * By default, a component considers itself stabilised when all of its
+     * children which are also {@link Component}s are reporting as stabilised.
+     */
     get hasStabilised(): Promise<void> {
         return this.#stabilised.promise;
     }
 
-    #abortController = new AbortController();
+    /**
+     * An {@link AbortSignal} which will trigger when this component is
+     * disconnected from the DOM.
+     *
+     * This can be passed along to asynchronous tasks such as {@link fetch}
+     * initiated by this component, which will then be aborted automatically if
+     * the component is removed from the DOM.
+     */
     get abortSignal(): AbortSignal {
         return this.#abortController.signal;
     }
+    #abortController = new AbortController();
 
-    static addInitialiser(init: () => void) {
+    /**
+     * Register a function which will be executed whenever an instance of this
+     * class is constructed.
+     */
+    static addInitialiser(init: (this: Component) => void) {
         if (!Object.hasOwn(this, "initialisers")) {
             this.initialisers = new Set();
         }
         this.initialisers.add(init);
     }
 
-    static get observedAttributes(): Array<string> {
+    /**
+     * A list of the attributes this element has declared.
+     * @see https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements#responding_to_attribute_changes
+     * @internal
+     */
+    static get observedAttributes(): ReadonlyArray<string> {
         this.finalise();
         return this.attributeConfig.keys().toArray();
     }
@@ -181,6 +253,7 @@ export abstract class Component
         }
     }
 
+    /** @ignore */
     constructor() {
         super();
 
@@ -190,7 +263,7 @@ export abstract class Component
         const fields = this.constructor[Symbol.metadata]?.[reactiveFields] ?? [];
         for (const field of fields as Iterable<string | symbol>) {
             const sig = signalForObject(this, field, () =>
-                Signal(undefined, { equals: Object.is }),
+                Signal.from(undefined, { equals: Object.is }),
             ) as Signal.State<unknown>;
             Object.defineProperty(this, field, {
                 get() {
@@ -230,20 +303,12 @@ export abstract class Component
         }
     }
 
-    protected connectedCallback() {
+    private connectedCallback() {
         this.#connectedContext.dispose();
         this.#controllers.forEach((c) => c.hostConnected?.());
         this.#rootPart?.setConnected(true);
 
-        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.connected();
 
         this.useWhileConnected(
             Signal.effect(() => {
@@ -261,12 +326,13 @@ export abstract class Component
         this.requestUpdate();
     }
 
-    protected disconnectedCallback() {
+    private disconnectedCallback() {
         if (this.#updateSignal !== undefined) {
             this.#updateSignalWatcher.unwatch(this.#updateSignal);
             this.#updateSignal = undefined;
         }
         this.#isUpdatePending = false;
+        this.disconnected();
         this.#abortController.abort(
             new DOMException(`${this.tagName} element disconnected`, "AbortError"),
         );
@@ -276,6 +342,9 @@ export abstract class Component
         this.#connectedContext.dispose();
     }
 
+    /**
+     * @internal
+     */
     setAttributeQuietly(name: string, value: string | null) {
         this.#ignoreAttributeUpdates++;
         if (value === null) {
@@ -286,6 +355,9 @@ export abstract class Component
         this.#ignoreAttributeUpdates--;
     }
 
+    /**
+     * @internal
+     */
     protected attributeChangedCallback(
         name: string,
         old: string | null,
@@ -297,15 +369,23 @@ export abstract class Component
         const attrConfig = (this.constructor as typeof Component).attributeConfig.get(name);
         if (attrConfig !== undefined) {
             const value = fromAttribute(valueString, attrConfig.type);
-            this[attrConfig.property as keyof this] = value as any;
+            try {
+                this[attrConfig.property as keyof this] = value as any;
+                // Silently swallow any write errors.
+            } catch (_e) {}
         }
     }
 
-    $signal<K extends keyof this & string, V extends this[K]>(prop: K): Signal<V> {
+    /**
+     * Typedoc does *not* like this type signature. TODO figure out how to
+     * document it properly.
+     * @ignore
+     */
+    $signal<K extends keyof this & string, V extends this[K]>(prop: K): Signal.Computed<V> {
         const _value = this[prop];
         return signalForObject(this, prop, () => {
             throw new TypeError(`Object has no reactive property ${JSON.stringify(prop)}`);
-        }) as Signal<V>;
+        }) as Signal.Computed<V>;
     }
 
     addController(controller: ReactiveController) {
@@ -319,6 +399,16 @@ export abstract class Component
         this.#controllers.delete(controller);
     }
 
+    /**
+     * Create the component's render root.
+     *
+     * By default, this creates a {@link ShadowRoot} and attaches it to the
+     * component.
+     *
+     * If you don't want to use a shadow DOM, you can override this method to
+     * just `return this`, which causes the component's contents to render as
+     * direct children of the component itself.
+     */
     protected createRenderRoot(): HTMLElement | ShadowRoot {
         const renderRoot =
             this.shadowRoot ??
@@ -328,6 +418,9 @@ export abstract class Component
         return renderRoot;
     }
 
+    /**
+     * Ask this component to update itself.
+     */
     requestUpdate(opts?: UpdateConfig) {
         this.#dirty = true;
 
@@ -341,7 +434,9 @@ export abstract class Component
         }
     }
 
-    #hasRequiredProperties?: Signal.Computed<boolean>;
+    /**
+     * @internal
+     */
     hasRequiredProperties(): Signal.Computed<boolean> {
         if (this.#hasRequiredProperties === undefined) {
             const requiredProperties = (this.constructor as typeof Component).requiredProperties;
@@ -349,9 +444,7 @@ export abstract class Component
                 () => {
                     return requiredProperties.size === 0
                         ? true
-                        : requiredProperties
-                              .keys()
-                              .every((key) => (this as any)[key] !== undefined);
+                        : requiredProperties.keys().every((key) => !isNullish((this as any)[key]));
                 },
                 // every signal update is relevant, even if the signal value doesn't
                 // change, because the required values probably did.
@@ -360,7 +453,9 @@ export abstract class Component
         }
         return this.#hasRequiredProperties;
     }
+    #hasRequiredProperties?: Signal.Computed<boolean>;
 
+    /** @internal */
     protected async performUpdate() {
         if (!this.isConnected || !this.isUpdatePending) {
             return;
@@ -418,6 +513,7 @@ export abstract class Component
         }
     }
 
+    /** @internal */
     protected update() {
         if (this.#updateSignal !== undefined) {
             this.#updateSignalWatcher.unwatch(this.#updateSignal);
@@ -430,17 +526,23 @@ export abstract class Component
         this.#updateSignal.get();
     }
 
+    /**
+     * Return an iterator over this component's children which are also
+     * {@link Component}s.
+     */
     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);
+        return findDescendants(root, (el) => el instanceof Component);
     }
 
+    /**
+     * Return a {@link Promise} which resolves when this component considers
+     * itself to have stabilised.
+     *
+     * The default implementation waits for any children which are also
+     * {@link Component}s to report that they have also stabilised.
+     */
     protected async stabilise(): Promise<void> {
         // wait for children to stabilise
         const children = this.findChildComponents();
@@ -448,41 +550,112 @@ export abstract class Component
         await Promise.all(children.map((child) => child.hasStabilised)).catch(console.error);
     }
 
+    /**
+     * This lifecycle callback is called each time this component is connected
+     * to the DOM.
+     */
+    protected connected(): void {
+        //
+    }
+
+    /**
+     * This lifecycle callback is called each time this component is
+     * disconnected from the DOM.
+     */
+    protected disconnected(): void {
+        //
+    }
+
+    /**
+     * This lifecycle callback is called each time an update has completed.
+     */
     protected updated(): void {
-        // called when an update has completed
+        //
     }
 
+    /**
+     * This lifecycle callback is called after the component's first update has
+     * completed, and before {@link Component.updated}.
+     */
     protected firstUpdated() {
-        // called when the first update has completed, and before
-        // {@link Component.updated}.
+        //
     }
 
+    /**
+     * This lifecycle callback is called when the component considers itself
+     * stabilised after its first update.
+     *
+     * @see {@link Component.hasStabilised}
+     */
     protected stabilised() {
-        // called when the component has stabilised after its first update
+        //
     }
 
+    /**
+     * This lifecycle callback is called every time a property decorated with
+     * the @{@link require} decorator has changed, but only when every property
+     * marked as such is not `undefined`.
+     */
     protected initialised() {
-        // called when a property marked `@require` has changed and every
-        // such property is non-`undefined`.
+        //
     }
 
+    /**
+     * This lifecycle callback is called the first time every property decorated
+     * with @{@link require} has been defined, and before
+     * {@link Component.initialised}.
+     */
     protected firstInitialised() {
-        // called the first time all properties marked `@require` become
-        // defined, and before {@link Component.initialised}.
+        //
     }
 
+    /**
+     * Render the component's contents.
+     *
+     * This function should return a Lit [renderable
+     * value](https://lit.dev/docs/templates/expressions/#child-expressions),
+     * usually an {@link html} template.
+     *
+     * @example
+     * class MyComponent extends Component {
+     *     protected override render() {
+     *         return html`
+     *             <h1>Hello Joe!</h1>
+     *         `;
+     *     }
+     * }
+     */
     protected render(): unknown {
         return nothing;
     }
 
-    [Symbol.dispose]() {
+    [Symbol.dispose](): void {
         for (const child of this.findChildComponents()) {
             child[Symbol.dispose]();
         }
+        this.remove();
         this.disconnectedCallback();
         (this.#rootPart as any)?._$clear?.();
         this.#rootPart = undefined;
-        this.remove();
+        this.#finalCleanupContext.dispose();
+    }
+
+    /**
+     * Register a {@link Disposable} for automatic disposal when this component
+     * is disposed.
+     */
+    use(disposifiable: undefined): undefined;
+    use(disposifiable: null): null;
+    use(disposifiable: Disposifiable): Disposable;
+    use(disposifiable: Disposifiable | undefined): Disposable | undefined;
+    use(disposifiable: Disposifiable | null | undefined): Disposable | null | undefined;
+    use(disposifiable: Disposifiable | null | undefined): Disposable | null | undefined {
+        if (isNullish(disposifiable)) {
+            return disposifiable;
+        }
+        const disposable = toDisposable(disposifiable);
+        this.#finalCleanupContext.use(disposable);
+        return disposable;
     }
 
     /**
@@ -501,6 +674,11 @@ export abstract class Component
      *     this.useWhileConnected(this.on("click", this.handleClick.bind(this)));
      * }
      */
+    useWhileConnected(
+        disposifiable: Disposifiable,
+        secondDisposable: Disposifiable,
+        ...disposifiables: Array<Disposifiable>
+    ): Array<Disposable>;
     useWhileConnected(disposifiable: undefined): undefined;
     useWhileConnected(disposifiable: null): null;
     useWhileConnected(disposifiable: Disposifiable): Disposable;
@@ -510,7 +688,15 @@ export abstract class Component
     ): Disposable | null | undefined;
     useWhileConnected(
         disposifiable: Disposifiable | null | undefined,
-    ): Disposable | null | undefined {
+        ...disposifiables: Array<Disposifiable>
+    ): Array<Disposable> | Disposable | null | undefined {
+        if (disposifiables.length > 0) {
+            return [disposifiable, ...disposifiables].map((d) => {
+                const disposable = toDisposable(present(d));
+                this.#connectedContext.use(disposable);
+                return disposable;
+            });
+        }
         if (isNullish(disposifiable)) {
             return disposifiable;
         }
@@ -541,6 +727,27 @@ export abstract class Component
         return this.shadowRoot?.activeElement ?? this.querySelector(":focus");
     }
 
+    /**
+     * Find the first element in the component's {@link Component.renderRoot}
+     * matching the provided CSS selector.
+     *
+     * If you need to query the component's direct child elements instead, use
+     * {@link Component.querySlot}.
+     *
+     * If you were looking for Lit's `@query` decorator, use this as a getter
+     * instead, as in the example below.
+     *
+     * @example
+     * class MyComponent extends Component {
+     *     get button(): HTMLButtonElement {
+     *         return this.query("button");
+     *     }
+     *
+     *     protected override render() {
+     *         return html`<button>I am a button</button>`;
+     *     }
+     * }
+     */
     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>(
@@ -555,6 +762,30 @@ export abstract class Component
         return this.renderRoot.querySelector(selector);
     }
 
+    /**
+     * Find all elements in the component's {@link Component.renderRoot}
+     * matching the provided CSS selector.
+     *
+     * If you need to query the component's direct child elements instead, use
+     * {@link Component.querySlot}.
+     *
+     * If you were looking for Lit's `@queryAll` decorator, use this as a getter
+     * instead, as in the example below.
+     *
+     * @example
+     * class MyComponent extends Component {
+     *     get buttons(): NodeListOf<HTMLButtonElement> {
+     *         return this.queryAll("button");
+     *     }
+     *
+     *     protected override render() {
+     *         return html`
+     *             <button>I am a button</button>
+     *             <button>I am also a button</button>
+     *         `;
+     *     }
+     * }
+     */
     queryAll<El extends keyof HTMLElementTagNameMap>(
         selector: El,
     ): NodeListOf<HTMLElementTagNameMap[El]>;
@@ -573,6 +804,13 @@ export abstract class Component
         return this.renderRoot.querySelectorAll(selector);
     }
 
+    /**
+     * Find the elements attached to a given slot on this component, according
+     * to the provided {@link QuerySlotOptions}.
+     *
+     * If you include `reactive: true` in your query, the result will be a
+     * signal which updates with the contents of the slot.
+     */
     querySlot(
         options: QuerySlotOptions & { nodes: true; reactive: true },
     ): Signal.Computed<Array<Node>>;
@@ -600,11 +838,9 @@ export abstract class Component
     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]>;
@@ -637,9 +873,9 @@ export abstract class Component
             return query(slotEl);
         }
         const sig = getOrSetSignal(this, query, () => {
-            const sig = Signal(query(slotEl), { equals: listsEqual });
+            const sig = Signal.from(query(slotEl), { equals: listsEqual });
             this.addController(new SlotChangeController(this, slot, sig, query));
-            return sig.readOnly();
+            return sig.readOnly;
         });
         return sig;
     }

package/src/css.ts

@@ -1,3 +1,8 @@
+/**
+ * CSS manipulation tools.
+ * @module
+ */
+
 import { assert } from "@bodil/core/assert";
 import { None, Option, Some } from "@bodil/opt";