@bodil/dom 0.1.8 → 0.1.10

package/dist/component.d.ts

@@ -1,3 +1,7 @@
+/**
+ * Web component base class.
+ * @module
+ */
 import { type Disposifiable } from "@bodil/core/disposable";
 import { Signal } from "@bodil/signal";
 import { type CSSResult, type CSSResultOrNative, type ReactiveController, type ReactiveControllerHost, type RenderOptions } from "lit";
@@ -21,15 +25,51 @@ export type Deps = Array<typeof HTMLElement>;
 export type CSSStyleSpec = CSSResult | CSSStyleSheet | string;
 export type CSSStyleSpecArray = Array<CSSStyleSpec | CSSStyleSpecArray>;
 export type CSSStyleSpecDeclaration = CSSStyleSpec | CSSStyleSpecArray;
+/**
+ * Error thrown when a {@link Component.render} method causes infinite
+ * re-renders.
+ */
 export declare class ComponentUpdateLoopError extends Error {
     constructor(message?: string, options?: ErrorOptions);
 }
+/**
+ * Base class for web components.
+ */
 export declare abstract class Component extends EmitterElement implements ReactiveControllerHost, Disposable {
     #private;
+    /**
+     * 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;
-    static initialisers: Set<() => void>;
+    private static initialisers;
     /** @ignore */
     protected static attributeConfig: Map<string, AttributeConfig>;
     /** @ignore */
@@ -40,33 +80,155 @@ export declare abstract class Component extends EmitterElement implements Reacti
     renderOptions: RenderOptions;
     emits: object;
     readonly renderRoot: ShadowRoot | HTMLElement;
+    /**
+     * True if this component had scheduled an update which has not yet started.
+     */
     get isUpdatePending(): boolean;
     get updateComplete(): Promise<boolean>;
+    /**
+     * 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>;
+    /**
+     * 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;
-    static addInitialiser(init: () => void): void;
-    static get observedAttributes(): Array<string>;
+    /**
+     * Register a function which will be executed whenever an instance of this
+     * class is constructed.
+     */
+    static addInitialiser(init: (this: Component) => void): void;
+    /**
+     * 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>;
     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;
+    /**
+     * @internal
+     */
     setAttributeQuietly(name: string, value: string | null): void;
+    /**
+     * @internal
+     */
     protected attributeChangedCallback(name: string, old: string | null, valueString: string | null): void;
-    $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>;
     addController(controller: ReactiveController): void;
     removeController(controller: ReactiveController): void;
+    /**
+     * 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;
+    /**
+     * Ask this component to update itself.
+     */
     requestUpdate(opts?: UpdateConfig): void;
+    /**
+     * @internal
+     */
     hasRequiredProperties(): Signal.Computed<boolean>;
+    /** @internal */
     protected performUpdate(): Promise<void>;
+    /** @internal */
     protected update(): void;
+    /**
+     * Return an iterator over this component's children which are also
+     * {@link Component}s.
+     */
     protected findChildComponents(root?: Element | ShadowRoot): IteratorObject<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 stabilise(): Promise<void>;
+    /**
+     * This lifecycle callback is called each time an update has completed.
+     */
     protected updated(): void;
+    /**
+     * This lifecycle callback is called after the component's first update has
+     * completed, and before {@link Component.updated}.
+     */
     protected firstUpdated(): void;
+    /**
+     * This lifecycle callback is called when the component considers itself
+     * stabilised after its first update.
+     *
+     * @see {@link Component.hasStabilised}
+     */
     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`.
+     */
     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}.
+     */
     protected firstInitialised(): void;
+    /**
+     * 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;
     [Symbol.dispose](): void;
     /**
@@ -102,18 +264,70 @@ export declare abstract class Component extends EmitterElement implements Reacti
      * element. Otherwise, return null.
      */
     getFocusedElement(): Element | null;
+    /**
+     * 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>(selector: El): MathMLElementTagNameMap[El] | null;
     /** @deprecated */
     query<El extends keyof HTMLElementDeprecatedTagNameMap>(selector: El): HTMLElementDeprecatedTagNameMap[El] | null;
     query(selector: string): Element | null;
+    /**
+     * 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]>;
     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>;
+    /**
+     * 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;
@@ -152,12 +366,10 @@ export declare abstract class Component extends EmitterElement implements Reacti
     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]>;

package/dist/component.js

@@ -1,3 +1,7 @@
+/**
+ * Web component base class.
+ * @module
+ */
 var _a;
 import { isIterable, isNullish } from "@bodil/core/assert";
 import { DisposableContext, toDisposable } from "@bodil/core/disposable";
@@ -22,13 +26,31 @@ const finalised = Symbol("finalised");
 function processCSSStyleSpec(spec) {
     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, options) {
         super(message, options);
         this.name = "ComponentUpdateLoopError";
     }
 }
+/**
+ * Base class for web components.
+ */
 export class Component extends EmitterElement {
+    /**
+     * 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 { this.deps = []; }
     static { this.shadowRootOptions = { mode: "open" }; }
     static { this.initialisers = new Set(); }
@@ -52,25 +74,53 @@ export class Component extends EmitterElement {
     #initialised;
     #viewTransitionRequested;
     #ignoreAttributeUpdates;
+    /**
+     * True if this component had scheduled an update which has not yet started.
+     */
     get isUpdatePending() {
         return this.#isUpdatePending;
     }
     get updateComplete() {
         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() {
         return this.#stabilised.promise;
     }
-    #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() {
         return this.#abortController.signal;
     }
+    #abortController;
+    /**
+     * Register a function which will be executed whenever an instance of this
+     * class is constructed.
+     */
     static addInitialiser(init) {
         if (!Object.hasOwn(this, "initialisers")) {
             this.initialisers = new Set();
         }
         this.initialisers.add(init);
     }
+    /**
+     * 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() {
         this.finalise();
         return this.attributeConfig.keys().toArray();
@@ -106,6 +156,7 @@ export class Component extends EmitterElement {
             }
         }
     }
+    /** @ignore */
     constructor() {
         super();
         this.renderOptions = { host: this };
@@ -125,7 +176,7 @@ export class Component extends EmitterElement {
         // set up reactive fields, because decorators can't do this themselves
         const fields = this.constructor[Symbol.metadata]?.[reactiveFields] ?? [];
         for (const field of fields) {
-            const sig = signalForObject(this, field, () => Signal(undefined, { equals: Object.is }));
+            const sig = signalForObject(this, field, () => Signal.from(undefined, { equals: Object.is }));
             Object.defineProperty(this, field, {
                 get() {
                     return sig.get();
@@ -160,6 +211,13 @@ 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?.());
@@ -185,6 +243,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);
@@ -197,6 +262,9 @@ export class Component extends EmitterElement {
         this.#controllers.forEach((c) => c.hostDisconnected?.());
         this.#connectedContext.dispose();
     }
+    /**
+     * @internal
+     */
     setAttributeQuietly(name, value) {
         this.#ignoreAttributeUpdates++;
         if (value === null) {
@@ -207,6 +275,9 @@ export class Component extends EmitterElement {
         }
         this.#ignoreAttributeUpdates--;
     }
+    /**
+     * @internal
+     */
     attributeChangedCallback(name, old, valueString) {
         if (this.#ignoreAttributeUpdates > 0 || old === valueString) {
             return;
@@ -217,6 +288,11 @@ export class Component extends EmitterElement {
             this[attrConfig.property] = value;
         }
     }
+    /**
+     * Typedoc does *not* like this type signature. TODO figure out how to
+     * document it properly.
+     * @ignore
+     */
     $signal(prop) {
         const _value = this[prop];
         return signalForObject(this, prop, () => {
@@ -232,6 +308,16 @@ export class Component extends EmitterElement {
     removeController(controller) {
         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.
+     */
     createRenderRoot() {
         const renderRoot = this.shadowRoot ??
             this.attachShadow(this.constructor.shadowRootOptions);
@@ -239,6 +325,9 @@ export class Component extends EmitterElement {
         this.renderOptions.renderBefore ??= renderRoot.firstChild;
         return renderRoot;
     }
+    /**
+     * Ask this component to update itself.
+     */
     requestUpdate(opts) {
         this.#dirty = true;
         if (opts?.viewTransition === true) {
@@ -250,7 +339,9 @@ export class Component extends EmitterElement {
             scheduler(this);
         }
     }
-    #hasRequiredProperties;
+    /**
+     * @internal
+     */
     hasRequiredProperties() {
         if (this.#hasRequiredProperties === undefined) {
             const requiredProperties = this.constructor.requiredProperties;
@@ -267,6 +358,8 @@ export class Component extends EmitterElement {
         }
         return this.#hasRequiredProperties;
     }
+    #hasRequiredProperties;
+    /** @internal */
     async performUpdate() {
         if (!this.isConnected || !this.isUpdatePending) {
             return;
@@ -320,6 +413,7 @@ export class Component extends EmitterElement {
             }
         }
     }
+    /** @internal */
     update() {
         if (this.#updateSignal !== undefined) {
             this.#updateSignalWatcher.unwatch(this.#updateSignal);
@@ -331,6 +425,10 @@ export class Component extends EmitterElement {
         this.#updateSignalWatcher.watch(this.#updateSignal);
         this.#updateSignal.get();
     }
+    /**
+     * Return an iterator over this component's children which are also
+     * {@link Component}s.
+     */
     findChildComponents(root = this.renderRoot) {
         let all = childElements(root).toArray();
         const top = [...all];
@@ -339,30 +437,73 @@ export class Component extends EmitterElement {
         }
         return Iterator.from(all).filter((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.
+     */
     async stabilise() {
         // 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);
     }
+    /**
+     * This lifecycle callback is called each time an update has completed.
+     */
     updated() {
-        // called when an update has completed
+        //
     }
+    /**
+     * This lifecycle callback is called after the component's first update has
+     * completed, and before {@link Component.updated}.
+     */
     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}
+     */
     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`.
+     */
     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}.
+     */
     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>
+     *         `;
+     *     }
+     * }
+     */
     render() {
         return nothing;
     }
@@ -425,9 +566,9 @@ export class Component extends EmitterElement {
             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;
     }