@bodil/dom 0.1.9 → 0.2.0

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";
@@ -7,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";
@@ -17,19 +20,56 @@ 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>;
 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,35 +80,162 @@ 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();
-    protected connectedCallback(): void;
-    protected disconnectedCallback(): void;
+    private connectedCallback;
+    private disconnectedCallback;
+    /**
+     * @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 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;
+    /**
+     * 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;
+    /**
+     * 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;
     /**
      * Attach a {@link Disposable} to the component's connected/disconnected
      * lifecycle state.
@@ -85,6 +252,7 @@ export declare abstract class Component extends EmitterElement implements Reacti
      *     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;
@@ -102,18 +270,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 +372,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]>;