@bodil/dom 0.1.10 → 0.2.1

package/dist/component.d.ts

@@ -11,7 +11,6 @@ import { EmitterElement } from "./emitter";
 import { type QuerySlotOptions } from "./slot";
 export type { ReactiveController, ReactiveControllerHost } from "lit";
 export { attribute, attributeGetter, attributeSetter, type AttributeOptions, 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";
@@ -21,6 +20,7 @@ export type UpdateConfig = {
     viewTransition?: boolean;
 };
 declare const finalised: unique symbol;
+export type Disposables = Disposifiable | Iterable<Disposifiable | undefined> | undefined | void;
 export type Deps = Array<typeof HTMLElement>;
 export type CSSStyleSpec = CSSResult | CSSStyleSheet | string;
 export type CSSStyleSpecArray = Array<CSSStyleSpec | CSSStyleSpecArray>;
@@ -47,6 +47,8 @@ export declare abstract class Component extends EmitterElement implements Reacti
      * class MyComponent extends Component {
      *     static deps: Deps = [ MySubcomponent, MyOtherSubcomponent ];
      * }
+     *
+     * @category Declarations
      */
     static deps: Deps;
     /**
@@ -66,8 +68,13 @@ export declare abstract class Component extends EmitterElement implements Reacti
      *         }
      *     `;
      * }
+     *
+     * @category Declarations
      */
     static styles?: CSSStyleSpecDeclaration;
+    /**
+     * @category Advanced
+     */
     static shadowRootOptions: ShadowRootInit;
     private static initialisers;
     /** @ignore */
@@ -77,13 +84,28 @@ export declare abstract class Component extends EmitterElement implements Reacti
     /** @ignore */
     protected static requiredProperties: Set<string | symbol>;
     private static [finalised];
+    /**
+     * @category Advanced
+     */
     renderOptions: RenderOptions;
+    /**
+     * {@inheritDoc EmitterElement.emits}
+     * @category Declarations
+     */
     emits: object;
+    /**
+     * @category Advanced
+     */
     readonly renderRoot: ShadowRoot | HTMLElement;
     /**
      * True if this component had scheduled an update which has not yet started.
+     *
+     * @category Render
      */
     get isUpdatePending(): boolean;
+    /**
+     * @category Render
+     */
     get updateComplete(): Promise<boolean>;
     /**
      * A {@link Promise} which resolves when this component has completed its
@@ -92,6 +114,8 @@ export declare abstract class Component extends EmitterElement implements Reacti
      *
      * By default, a component considers itself stabilised when all of its
      * children which are also {@link Component}s are reporting as stabilised.
+     *
+     * @category Render
      */
     get hasStabilised(): Promise<void>;
     /**
@@ -101,11 +125,15 @@ export declare abstract class Component extends EmitterElement implements Reacti
      * 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.
+     *
+     * @category Advanced
      */
     get abortSignal(): AbortSignal;
     /**
      * Register a function which will be executed whenever an instance of this
      * class is constructed.
+     *
+     * @category Advanced
      */
     static addInitialiser(init: (this: Component) => void): void;
     /**
@@ -117,22 +145,8 @@ export declare abstract class Component extends EmitterElement implements Reacti
     private static finalise;
     /** @ignore */
     constructor();
-    /**
-     * This lifecycle callback is called when the component is attached to the
-     * DOM.
-     *
-     * Generally, prefer using methods with @{@link connect} decorators to
-     * overriding this method.
-     */
-    protected connectedCallback(): void;
-    /**
-     * This lifecycle callback is called when the component is removed from the
-     * DOM.
-     *
-     * Generally, prefer using methods with @{@link connect} decorators to
-     * overriding this method.
-     */
-    protected disconnectedCallback(): void;
+    private connectedCallback;
+    private disconnectedCallback;
     /**
      * @internal
      */
@@ -147,7 +161,16 @@ export declare abstract class Component extends EmitterElement implements Reacti
      * @ignore
      */
     $signal<K extends keyof this & string, V extends this[K]>(prop: K): Signal.Computed<V>;
+    /**
+     * Adds a controller to the host, which sets up the controller's lifecycle
+     * methods to be called with the host's lifecycle.
+     * @category Advanced
+     */
     addController(controller: ReactiveController): void;
+    /**
+     * Removes a controller from the host.
+     * @category Advanced
+     */
     removeController(controller: ReactiveController): void;
     /**
      * Create the component's render root.
@@ -158,10 +181,20 @@ export declare abstract class Component extends EmitterElement implements Reacti
      * 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.
+     *
+     * @category Advanced
      */
     protected createRenderRoot(): HTMLElement | ShadowRoot;
+    /**
+     * Add a style sheet to the component's shadow root.
+     *
+     * @category Advanced
+     */
+    addStyleSheet(spec: CSSStyleSpecDeclaration): void;
     /**
      * Ask this component to update itself.
+     *
+     * @category Render
      */
     requestUpdate(opts?: UpdateConfig): void;
     /**
@@ -175,6 +208,8 @@ export declare abstract class Component extends EmitterElement implements Reacti
     /**
      * Return an iterator over this component's children which are also
      * {@link Component}s.
+     *
+     * @category Queries
      */
     protected findChildComponents(root?: Element | ShadowRoot): IteratorObject<Component>;
     /**
@@ -183,15 +218,31 @@ export declare abstract class Component extends EmitterElement implements Reacti
      *
      * The default implementation waits for any children which are also
      * {@link Component}s to report that they have also stabilised.
+     *
+     * @category Render
      */
     protected stabilise(): Promise<void>;
+    /**
+     * This lifecycle callback is called each time this component is connected
+     * to the DOM.
+     * @category Lifecycle
+     */
+    protected connected(): void;
+    /**
+     * This lifecycle callback is called each time this component is
+     * disconnected from the DOM.
+     * @category Lifecycle
+     */
+    protected disconnected(): void;
     /**
      * This lifecycle callback is called each time an update has completed.
+     * @category Lifecycle
      */
     protected updated(): void;
     /**
      * This lifecycle callback is called after the component's first update has
      * completed, and before {@link Component.updated}.
+     * @category Lifecycle
      */
     protected firstUpdated(): void;
     /**
@@ -199,18 +250,21 @@ export declare abstract class Component extends EmitterElement implements Reacti
      * stabilised after its first update.
      *
      * @see {@link Component.hasStabilised}
+     * @category Lifecycle
      */
     protected stabilised(): void;
     /**
      * 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`.
+     * @category Lifecycle
      */
     protected initialised(): void;
     /**
      * This lifecycle callback is called the first time every property decorated
      * with @{@link require} has been defined, and before
      * {@link Component.initialised}.
+     * @category Lifecycle
      */
     protected firstInitialised(): void;
     /**
@@ -228,9 +282,22 @@ export declare abstract class Component extends EmitterElement implements Reacti
      *         `;
      *     }
      * }
+     *
+     * @category Render
      */
     protected render(): unknown;
+    /** @internal */
     [Symbol.dispose](): void;
+    /**
+     * Register a {@link Disposable} for automatic disposal when this component
+     * is disposed.
+     * @category Resources
+     */
+    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;
     /**
      * Attach a {@link Disposable} to the component's connected/disconnected
      * lifecycle state.
@@ -246,7 +313,9 @@ export declare abstract class Component extends EmitterElement implements Reacti
      *     super.connectedCallback();
      *     this.useWhileConnected(this.on("click", this.handleClick.bind(this)));
      * }
+     * @category Resources
      */
+    useWhileConnected(disposifiable: Disposifiable, secondDisposable: Disposifiable, ...disposifiables: Array<Disposifiable>): Array<Disposable>;
     useWhileConnected(disposifiable: undefined): undefined;
     useWhileConnected(disposifiable: null): null;
     useWhileConnected(disposifiable: Disposifiable): Disposable;
@@ -256,12 +325,14 @@ export declare abstract class Component extends EmitterElement implements Reacti
      * Attach an event listener to an event on this component.
      *
      * @returns A {@link Disposable} to subsequently detach the event listener.
+     * @category Events
      */
     on<K extends keyof HTMLElementEventMap>(type: K, callback: (event: HTMLElementEventMap[K]) => void, options?: AddEventListenerOptions | boolean): Disposable;
     /**
      * 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.
+     * @category Queries
      */
     getFocusedElement(): Element | null;
     /**
@@ -284,6 +355,7 @@ export declare abstract class Component extends EmitterElement implements Reacti
      *         return html`<button>I am a button</button>`;
      *     }
      * }
+     * @category Queries
      */
     query<El extends keyof HTMLElementTagNameMap>(selector: El): HTMLElementTagNameMap[El] | null;
     query<El extends keyof SVGElementTagNameMap>(selector: El): SVGElementTagNameMap[El] | null;
@@ -314,6 +386,7 @@ export declare abstract class Component extends EmitterElement implements Reacti
      *         `;
      *     }
      * }
+     * @category Queries
      */
     queryAll<El extends keyof HTMLElementTagNameMap>(selector: El): NodeListOf<HTMLElementTagNameMap[El]>;
     queryAll<El extends keyof SVGElementTagNameMap>(selector: El): NodeListOf<SVGElementTagNameMap[El]>;
@@ -327,6 +400,7 @@ export declare abstract class Component extends EmitterElement implements Reacti
      *
      * If you include `reactive: true` in your query, the result will be a
      * signal which updates with the contents of the slot.
+     * @category Queries
      */
     querySlot(options: QuerySlotOptions & {
         nodes: true;

package/dist/component.js

@@ -3,21 +3,19 @@
  * @module
  */
 var _a;
-import { isIterable, isNullish } from "@bodil/core/assert";
+import { isNullish, present } from "@bodil/core/assert";
 import { DisposableContext, toDisposable } from "@bodil/core/disposable";
 import { Signal } from "@bodil/signal";
 import { adoptStyles, getCompatibleStyle, nothing, render, unsafeCSS, } from "lit";
 import { attributeConfig, fromAttribute, toAttribute, } 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";
 import { findSlot, getOrSetQuery, getOrSetSignal, listsEqual, SlotChangeController, } from "./slot";
 export { attribute, attributeGetter, attributeSetter, } from "./decorators/attribute";
-export { connect, connectEffect, } from "./decorators/connect";
 export { reactive } from "./decorators/reactive";
 export { require } from "./decorators/require";
 export { EmitterElement } from "./emitter";
@@ -50,8 +48,13 @@ export class Component extends EmitterElement {
      * class MyComponent extends Component {
      *     static deps: Deps = [ MySubcomponent, MyOtherSubcomponent ];
      * }
+     *
+     * @category Declarations
      */
     static { this.deps = []; }
+    /**
+     * @category Advanced
+     */
     static { this.shadowRootOptions = { mode: "open" }; }
     static { this.initialisers = new Set(); }
     /** @ignore */
@@ -63,6 +66,7 @@ export class Component extends EmitterElement {
     static { this[_a] = true; }
     #controllers;
     #connectedContext;
+    #finalCleanupContext;
     #dirty;
     #isUpdatePending;
     #updateSignal;
@@ -76,10 +80,15 @@ export class Component extends EmitterElement {
     #ignoreAttributeUpdates;
     /**
      * True if this component had scheduled an update which has not yet started.
+     *
+     * @category Render
      */
     get isUpdatePending() {
         return this.#isUpdatePending;
     }
+    /**
+     * @category Render
+     */
     get updateComplete() {
         return this.#updateResult.promise;
     }
@@ -90,6 +99,8 @@ export class Component extends EmitterElement {
      *
      * By default, a component considers itself stabilised when all of its
      * children which are also {@link Component}s are reporting as stabilised.
+     *
+     * @category Render
      */
     get hasStabilised() {
         return this.#stabilised.promise;
@@ -101,6 +112,8 @@ export class Component extends EmitterElement {
      * 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.
+     *
+     * @category Advanced
      */
     get abortSignal() {
         return this.#abortController.signal;
@@ -109,6 +122,8 @@ export class Component extends EmitterElement {
     /**
      * Register a function which will be executed whenever an instance of this
      * class is constructed.
+     *
+     * @category Advanced
      */
     static addInitialiser(init) {
         if (!Object.hasOwn(this, "initialisers")) {
@@ -159,9 +174,13 @@ export class Component extends EmitterElement {
     /** @ignore */
     constructor() {
         super();
+        /**
+         * @category Advanced
+         */
         this.renderOptions = { host: this };
         this.#controllers = new Set();
         this.#connectedContext = new DisposableContext();
+        this.#finalCleanupContext = new DisposableContext();
         this.#dirty = false;
         this.#isUpdatePending = false;
         this.#updateSignalWatcher = new Signal.subtle.Watcher(() => this.requestUpdate());
@@ -170,6 +189,9 @@ export class Component extends EmitterElement {
         this.#firstUpdate = false;
         this.#initialised = false;
         this.#viewTransitionRequested = false;
+        /**
+         * @category Advanced
+         */
         this.renderRoot = this.createRenderRoot();
         this.#abortController = new AbortController();
         this.#ignoreAttributeUpdates = 1;
@@ -211,26 +233,11 @@ export class Component extends EmitterElement {
             });
         }
     }
-    /**
-     * This lifecycle callback is called when the component is attached to the
-     * DOM.
-     *
-     * Generally, prefer using methods with @{@link connect} decorators to
-     * overriding this method.
-     */
     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([])
-                : isIterable(result)
-                    ? Iterator.from(result)
-                    : Iterator.from([result]);
-            items.filter((i) => i !== undefined).forEach(this.useWhileConnected.bind(this));
-        }
+        this.connected();
         this.useWhileConnected(Signal.effect(() => {
             if (this.hasRequiredProperties().get()) {
                 if (!this.#initialised) {
@@ -243,19 +250,13 @@ export class Component extends EmitterElement {
         }));
         this.requestUpdate();
     }
-    /**
-     * This lifecycle callback is called when the component is removed from the
-     * DOM.
-     *
-     * Generally, prefer using methods with @{@link connect} decorators to
-     * overriding this method.
-     */
     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"));
         this.#abortController = new AbortController();
         this.#rootPart?.setConnected(false);
@@ -285,7 +286,11 @@ export class Component extends EmitterElement {
         const attrConfig = this.constructor.attributeConfig.get(name);
         if (attrConfig !== undefined) {
             const value = fromAttribute(valueString, attrConfig.type);
-            this[attrConfig.property] = value;
+            try {
+                this[attrConfig.property] = value;
+                // Silently swallow any write errors.
+            }
+            catch (_e) { }
         }
     }
     /**
@@ -299,12 +304,21 @@ export class Component extends EmitterElement {
             throw new TypeError(`Object has no reactive property ${JSON.stringify(prop)}`);
         });
     }
+    /**
+     * Adds a controller to the host, which sets up the controller's lifecycle
+     * methods to be called with the host's lifecycle.
+     * @category Advanced
+     */
     addController(controller) {
         this.#controllers.add(controller);
         if (this.renderRoot !== undefined && this.isConnected) {
             controller.hostConnected?.();
         }
     }
+    /**
+     * Removes a controller from the host.
+     * @category Advanced
+     */
     removeController(controller) {
         this.#controllers.delete(controller);
     }
@@ -317,6 +331,8 @@ export class Component extends EmitterElement {
      * 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.
+     *
+     * @category Advanced
      */
     createRenderRoot() {
         const renderRoot = this.shadowRoot ??
@@ -325,8 +341,24 @@ export class Component extends EmitterElement {
         this.renderOptions.renderBefore ??= renderRoot.firstChild;
         return renderRoot;
     }
+    /**
+     * Add a style sheet to the component's shadow root.
+     *
+     * @category Advanced
+     */
+    addStyleSheet(spec) {
+        if (!(this.renderRoot instanceof ShadowRoot)) {
+            throw new Error("Component needs a shadow root in order to add a style sheet");
+        }
+        const sheets = (Array.isArray(spec)
+            ? spec.flat(Infinity)
+            : [spec]).map(processCSSStyleSpec);
+        adoptStyles(this.renderRoot, sheets);
+    }
     /**
      * Ask this component to update itself.
+     *
+     * @category Render
      */
     requestUpdate(opts) {
         this.#dirty = true;
@@ -348,9 +380,7 @@ export class Component extends EmitterElement {
             this.#hasRequiredProperties = Signal.computed(() => {
                 return requiredProperties.size === 0
                     ? true
-                    : requiredProperties
-                        .keys()
-                        .every((key) => this[key] !== undefined);
+                    : requiredProperties.keys().every((key) => !isNullish(this[key]));
             }, 
             // every signal update is relevant, even if the signal value doesn't
             // change, because the required values probably did.
@@ -428,14 +458,11 @@ export class Component extends EmitterElement {
     /**
      * Return an iterator over this component's children which are also
      * {@link Component}s.
+     *
+     * @category Queries
      */
     findChildComponents(root = this.renderRoot) {
-        let all = 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
@@ -443,6 +470,8 @@ export class Component extends EmitterElement {
      *
      * The default implementation waits for any children which are also
      * {@link Component}s to report that they have also stabilised.
+     *
+     * @category Render
      */
     async stabilise() {
         // wait for children to stabilise
@@ -450,8 +479,25 @@ export class Component extends EmitterElement {
         // eslint-disable-next-line no-console
         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.
+     * @category Lifecycle
+     */
+    connected() {
+        //
+    }
+    /**
+     * This lifecycle callback is called each time this component is
+     * disconnected from the DOM.
+     * @category Lifecycle
+     */
+    disconnected() {
+        //
+    }
     /**
      * This lifecycle callback is called each time an update has completed.
+     * @category Lifecycle
      */
     updated() {
         //
@@ -459,6 +505,7 @@ export class Component extends EmitterElement {
     /**
      * This lifecycle callback is called after the component's first update has
      * completed, and before {@link Component.updated}.
+     * @category Lifecycle
      */
     firstUpdated() {
         //
@@ -468,6 +515,7 @@ export class Component extends EmitterElement {
      * stabilised after its first update.
      *
      * @see {@link Component.hasStabilised}
+     * @category Lifecycle
      */
     stabilised() {
         //
@@ -476,6 +524,7 @@ export class Component extends EmitterElement {
      * 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`.
+     * @category Lifecycle
      */
     initialised() {
         //
@@ -484,6 +533,7 @@ export class Component extends EmitterElement {
      * This lifecycle callback is called the first time every property decorated
      * with @{@link require} has been defined, and before
      * {@link Component.initialised}.
+     * @category Lifecycle
      */
     firstInitialised() {
         //
@@ -503,20 +553,39 @@ export class Component extends EmitterElement {
      *         `;
      *     }
      * }
+     *
+     * @category Render
      */
     render() {
         return nothing;
     }
+    /** @internal */
     [(_a = finalised, Symbol.dispose)]() {
         for (const child of this.findChildComponents()) {
             child[Symbol.dispose]();
         }
+        this.remove();
         this.disconnectedCallback();
         this.#rootPart?._$clear?.();
         this.#rootPart = undefined;
-        this.remove();
+        this.#finalCleanupContext.dispose();
     }
-    useWhileConnected(disposifiable) {
+    use(disposifiable) {
+        if (isNullish(disposifiable)) {
+            return disposifiable;
+        }
+        const disposable = toDisposable(disposifiable);
+        this.#finalCleanupContext.use(disposable);
+        return disposable;
+    }
+    useWhileConnected(disposifiable, ...disposifiables) {
+        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;
         }
@@ -528,6 +597,7 @@ export class Component extends EmitterElement {
      * Attach an event listener to an event on this component.
      *
      * @returns A {@link Disposable} to subsequently detach the event listener.
+     * @category Events
      */
     on(type, callback, options) {
         return eventListener(this, type, callback, options);
@@ -536,6 +606,7 @@ export class Component extends EmitterElement {
      * 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.
+     * @category Queries
      */
     getFocusedElement() {
         return this.shadowRoot?.activeElement ?? this.querySelector(":focus");