@bodil/dom 0.1.10 → 0.2.1

package/dist/emitter.d.ts

@@ -67,6 +67,8 @@ export declare class EmitterElement extends HTMLElement {
      * class MyElement extends EmitterElement {
      *     emits!: Emits<"my-event" | "my-other-event";
      * }
+     *
+     * @category Events
      */
     emits: {
         [K in keyof HTMLElementEventMap]?: never;
@@ -75,6 +77,8 @@ export declare class EmitterElement extends HTMLElement {
      * Emit a custom event with the given name and detail.
      *
      * Event init options default to `{ bubbles: true, composed: true }`.
+     *
+     * @category Events
      */
     emit<M extends CustomEventTypes<keyof this["emits"] & keyof HTMLElementEventMap>, K extends Extract<keyof M, string>, D extends M[K]>(name: K, detail?: D, options?: EventInit): CustomEvent<D>;
     /**
@@ -86,6 +90,8 @@ export declare class EmitterElement extends HTMLElement {
      * @example
      * this.emitEvent("click", MouseEvent, { button: 2 });
      * // emits: new MouseEvent("click", { button: 2 });
+     *
+     * @category Events
      */
     emitEvent<K extends keyof this["emits"] & keyof HTMLElementEventMap, E extends HTMLElementEventMap[K], C extends new (type: string, ...args: Args) => E, Args extends Array<any>>(name: K, constructor: C, ...args: Args): E;
 }

package/dist/emitter.js

@@ -27,6 +27,8 @@ export class EmitterElement extends HTMLElement {
      * Emit a custom event with the given name and detail.
      *
      * Event init options default to `{ bubbles: true, composed: true }`.
+     *
+     * @category Events
      */
     emit(name, detail, options) {
         const event = new CustomEvent(name, {
@@ -47,6 +49,8 @@ export class EmitterElement extends HTMLElement {
      * @example
      * this.emitEvent("click", MouseEvent, { button: 2 });
      * // emits: new MouseEvent("click", { button: 2 });
+     *
+     * @category Events
      */
     emitEvent(name, constructor, ...args) {
         const event = new constructor(name, ...args);

package/dist/emitter.js.map

@@ -1 +1 @@
-{"version":3,"file":"emitter.js","sourceRoot":"","sources":["../src/emitter.ts"],"names":[],"mappings":"AAuCA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,OAAO,cAAe,SAAQ,WAAW;IAW3C;;;;OAIG;IACH,IAAI,CAIF,IAAO,EAAE,MAAU,EAAE,OAAmB;QACtC,MAAM,KAAK,GAAG,IAAI,WAAW,CAAC,IAAI,EAAE;YAChC,OAAO,EAAE,IAAI;YACb,QAAQ,EAAE,IAAI;YACd,MAAM;YACN,GAAG,CAAC,OAAO,IAAI,EAAE,CAAC;SACrB,CAAC,CAAC;QACH,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;QAC1B,OAAO,KAAK,CAAC;IACjB,CAAC;IAED;;;;;;;;;OASG;IACH,SAAS,CAKP,IAAO,EAAE,WAAc,EAAE,GAAG,IAAU;QACpC,MAAM,KAAK,GAAG,IAAI,WAAW,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,CAAC;QAC7C,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;QAC1B,OAAO,KAAK,CAAC;IACjB,CAAC;CACJ"}
+{"version":3,"file":"emitter.js","sourceRoot":"","sources":["../src/emitter.ts"],"names":[],"mappings":"AAuCA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,OAAO,cAAe,SAAQ,WAAW;IAa3C;;;;;;OAMG;IACH,IAAI,CAIF,IAAO,EAAE,MAAU,EAAE,OAAmB;QACtC,MAAM,KAAK,GAAG,IAAI,WAAW,CAAC,IAAI,EAAE;YAChC,OAAO,EAAE,IAAI;YACb,QAAQ,EAAE,IAAI;YACd,MAAM;YACN,GAAG,CAAC,OAAO,IAAI,EAAE,CAAC;SACrB,CAAC,CAAC;QACH,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;QAC1B,OAAO,KAAK,CAAC;IACjB,CAAC;IAED;;;;;;;;;;;OAWG;IACH,SAAS,CAKP,IAAO,EAAE,WAAc,EAAE,GAAG,IAAU;QACpC,MAAM,KAAK,GAAG,IAAI,WAAW,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,CAAC;QAC7C,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;QAC1B,OAAO,KAAK,CAAC;IACjB,CAAC;CACJ"}

package/dist/index.d.ts

@@ -8,4 +8,5 @@ import * as dom from "./dom";
 import * as event from "./event";
 import * as geometry from "./geometry";
 import * as signal from "./signal";
-export { component, css, dom, event, geometry, signal };
+import * as test from "./test";
+export { component, css, dom, event, geometry, signal, test };

package/dist/index.js

@@ -8,5 +8,6 @@ import * as dom from "./dom";
 import * as event from "./event";
 import * as geometry from "./geometry";
 import * as signal from "./signal";
-export { component, css, dom, event, geometry, signal };
+import * as test from "./test";
+export { component, css, dom, event, geometry, signal, test };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,SAAS,MAAM,aAAa,CAAC;AACzC,OAAO,KAAK,GAAG,MAAM,OAAO,CAAC;AAC7B,OAAO,KAAK,GAAG,MAAM,OAAO,CAAC;AAC7B,OAAO,KAAK,KAAK,MAAM,SAAS,CAAC;AACjC,OAAO,KAAK,QAAQ,MAAM,YAAY,CAAC;AACvC,OAAO,KAAK,MAAM,MAAM,UAAU,CAAC;AAEnC,OAAO,EAAE,SAAS,EAAE,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,SAAS,MAAM,aAAa,CAAC;AACzC,OAAO,KAAK,GAAG,MAAM,OAAO,CAAC;AAC7B,OAAO,KAAK,GAAG,MAAM,OAAO,CAAC;AAC7B,OAAO,KAAK,KAAK,MAAM,SAAS,CAAC;AACjC,OAAO,KAAK,QAAQ,MAAM,YAAY,CAAC;AACvC,OAAO,KAAK,MAAM,MAAM,UAAU,CAAC;AACnC,OAAO,KAAK,IAAI,MAAM,QAAQ,CAAC;AAE/B,OAAO,EAAE,SAAS,EAAE,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC"}

package/dist/test.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Tools for testing web components.
+ * @module
+ */
+/**
+ * Render a Lit template and wait for any {@link Component}s inside it to
+ * stabilise before returning the {@link HTMLElement} containing the rendered
+ * template.
+ *
+ * The root element is also a {@link Disposable} which will remove itself from
+ * the DOM and dispose its {@link Component}s when disposed.
+ *
+ * @example
+ * using root = await testHTML(html`<my-component></my-component>`);
+ * expect(root.querySelector("my-component")).toBeInstanceOf(MyComponent);
+ */
+export declare function testHTML(template: unknown): Promise<HTMLElement & Disposable>;

package/dist/test.js

@@ -0,0 +1,34 @@
+/**
+ * Tools for testing web components.
+ * @module
+ */
+import { render } from "lit";
+import { Component } from "./component";
+/**
+ * Render a Lit template and wait for any {@link Component}s inside it to
+ * stabilise before returning the {@link HTMLElement} containing the rendered
+ * template.
+ *
+ * The root element is also a {@link Disposable} which will remove itself from
+ * the DOM and dispose its {@link Component}s when disposed.
+ *
+ * @example
+ * using root = await testHTML(html`<my-component></my-component>`);
+ * expect(root.querySelector("my-component")).toBeInstanceOf(MyComponent);
+ */
+export async function testHTML(template) {
+    const root = document.createElement("section");
+    document.body.append(root);
+    render(template, root, { host: root });
+    root[Symbol.dispose] = () => {
+        Iterator.from(root.children)
+            .filter((el) => el instanceof Component)
+            .forEach((comp) => comp[Symbol.dispose]());
+        root.remove();
+    };
+    await Promise.all(Iterator.from(root.children)
+        .filter((el) => el instanceof Component)
+        .map((el) => el.hasStabilised));
+    return root;
+}
+//# sourceMappingURL=test.js.map

package/dist/test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"test.js","sourceRoot":"","sources":["../src/test.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,KAAK,CAAC;AAE7B,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,QAAiB;IAC5C,MAAM,IAAI,GAAG,QAAQ,CAAC,aAAa,CAAC,SAAS,CAA6B,CAAC;IAC3E,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC3B,MAAM,CAAC,QAAQ,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IACvC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,GAAG,EAAE;QACxB,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC;aACvB,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,YAAY,SAAS,CAAC;aACvC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QAC/C,IAAI,CAAC,MAAM,EAAE,CAAC;IAClB,CAAC,CAAC;IACF,MAAM,OAAO,CAAC,GAAG,CACb,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC;SACvB,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,YAAY,SAAS,CAAC;SACvC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,aAAa,CAAC,CACrC,CAAC;IACF,OAAO,IAAI,CAAC;AAChB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bodil/dom",
-  "version": "0.1.10",
+  "version": "0.2.1",
   "description": "DOM and web component tools",
   "homepage": "https://codeberg.org/bodil/dom",
   "repository": {
@@ -56,40 +56,46 @@
         "types": "./dist/signal.d.ts",
         "import": "./dist/signal.js"
       }
+    },
+    "./test": {
+      "import": {
+        "types": "./dist/test.d.ts",
+        "import": "./dist/test.js"
+      }
     }
   },
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@bodil/core": "^0.5.2",
-    "@bodil/opt": "^0.4.3",
-    "@bodil/signal": "^0.5.1",
+    "@bodil/core": "^0.5.3",
+    "@bodil/opt": "^1.0.0",
+    "@bodil/signal": "^0.5.2",
     "lit": "^3.3.2",
-    "type-fest": "^5.3.1"
+    "type-fest": "^5.4.4"
   },
   "devDependencies": {
     "@eslint/eslintrc": "^3.3.3",
-    "@eslint/js": "^9.39.2",
-    "@ianvs/prettier-plugin-sort-imports": "^4.7.0",
-    "@typescript-eslint/eslint-plugin": "^8.52.0",
-    "@typescript-eslint/parser": "^8.52.0",
+    "@eslint/js": "^10.0.1",
+    "@ianvs/prettier-plugin-sort-imports": "^4.7.1",
+    "@typescript-eslint/eslint-plugin": "^8.56.0",
+    "@typescript-eslint/parser": "^8.56.0",
     "@typhonjs-typedoc/ts-lib-docs": "^2024.12.25",
-    "@vitest/browser-playwright": "^4.0.16",
-    "@vitest/coverage-v8": "^4.0.16",
-    "eslint": "^9.39.2",
+    "@vitest/browser-playwright": "^4.0.18",
+    "@vitest/coverage-v8": "^4.0.18",
+    "eslint": "^10.0.1",
     "eslint-config-prettier": "^10.1.8",
-    "eslint-plugin-jsdoc": "^61.5.0",
-    "globals": "^17.0.0",
-    "happy-dom": "^20.0.11",
+    "eslint-plugin-jsdoc": "^62.7.0",
+    "globals": "^17.3.0",
+    "happy-dom": "^20.7.0",
     "npm-run-all2": "^8.0.4",
-    "prettier": "^3.7.4",
-    "typedoc": "^0.28.15",
+    "prettier": "^3.8.1",
+    "typedoc": "^0.28.17",
     "typedoc-plugin-extras": "^4.0.1",
-    "typedoc-plugin-mdn-links": "^5.0.10",
+    "typedoc-plugin-mdn-links": "^5.1.1",
     "typedoc-theme-fresh": "^0.2.3",
     "typescript": "^5.9.3",
-    "vitest": "^4.0.16"
+    "vitest": "^4.0.18"
   },
   "prettier": {
     "editorconfig": true,

package/src/component.ts

@@ -3,7 +3,7 @@
  * @module
  */
 
-import { isIterable, isNullish } from "@bodil/core/assert";
+import { isNullish, present } from "@bodil/core/assert";
 import { DisposableContext, toDisposable, type Disposifiable } from "@bodil/core/disposable";
 import { Signal } from "@bodil/signal";
 import {
@@ -29,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";
@@ -54,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";
@@ -74,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;
@@ -112,6 +107,8 @@ export abstract class Component
      * class MyComponent extends Component {
      *     static deps: Deps = [ MySubcomponent, MyOtherSubcomponent ];
      * }
+     *
+     * @category Declarations
      */
     static deps: Deps = [];
 
@@ -132,9 +129,14 @@ export abstract class Component
      *         }
      *     `;
      * }
+     *
+     * @category Declarations
      */
     static styles?: CSSStyleSpecDeclaration;
 
+    /**
+     * @category Advanced
+     */
     static shadowRootOptions: ShadowRootInit = { mode: "open" };
 
     private static initialisers = new Set<() => void>();
@@ -147,11 +149,20 @@ export abstract class Component
     protected static requiredProperties = new Set<string | symbol>();
     private static [finalised] = true;
 
+    /**
+     * @category Advanced
+     */
     renderOptions: RenderOptions = { host: this };
+
+    /**
+     * {@inheritDoc EmitterElement.emits}
+     * @category Declarations
+     */
     emits!: object;
 
     readonly #controllers = new Set<ReactiveController>();
     readonly #connectedContext = new DisposableContext();
+    readonly #finalCleanupContext = new DisposableContext();
     #dirty = false;
     #isUpdatePending = false;
     #updateSignal?: Signal.Computed<void>;
@@ -164,15 +175,23 @@ export abstract class Component
     #viewTransitionRequested = false;
     #ignoreAttributeUpdates: number;
 
+    /**
+     * @category Advanced
+     */
     readonly renderRoot: ShadowRoot | HTMLElement = this.createRenderRoot();
 
     /**
      * True if this component had scheduled an update which has not yet started.
+     *
+     * @category Render
      */
     get isUpdatePending(): boolean {
         return this.#isUpdatePending;
     }
 
+    /**
+     * @category Render
+     */
     get updateComplete(): Promise<boolean> {
         return this.#updateResult.promise;
     }
@@ -184,6 +203,8 @@ export abstract class Component
      *
      * 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> {
         return this.#stabilised.promise;
@@ -196,6 +217,8 @@ export abstract class Component
      * 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 {
         return this.#abortController.signal;
@@ -205,6 +228,8 @@ export abstract class Component
     /**
      * Register a function which will be executed whenever an instance of this
      * class is constructed.
+     *
+     * @category Advanced
      */
     static addInitialiser(init: (this: Component) => void) {
         if (!Object.hasOwn(this, "initialisers")) {
@@ -307,27 +332,12 @@ export abstract class Component
         }
     }
 
-    /**
-     * 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() {
+    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(() => {
@@ -345,19 +355,13 @@ export abstract class Component
         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.
-     */
-    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"),
         );
@@ -394,7 +398,10 @@ 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) {}
         }
     }
 
@@ -410,6 +417,11 @@ export abstract class Component
         }) as 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) {
         this.#controllers.add(controller);
         if (this.renderRoot !== undefined && this.isConnected) {
@@ -417,6 +429,10 @@ export abstract class Component
         }
     }
 
+    /**
+     * Removes a controller from the host.
+     * @category Advanced
+     */
     removeController(controller: ReactiveController) {
         this.#controllers.delete(controller);
     }
@@ -430,6 +446,8 @@ export abstract class 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.
+     *
+     * @category Advanced
      */
     protected createRenderRoot(): HTMLElement | ShadowRoot {
         const renderRoot =
@@ -440,8 +458,27 @@ export abstract class Component
         return renderRoot;
     }
 
+    /**
+     * Add a style sheet to the component's shadow root.
+     *
+     * @category Advanced
+     */
+    addStyleSheet(spec: CSSStyleSpecDeclaration) {
+        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 as Array<unknown>).flat(Infinity) as Array<CSSStyleSpec>)
+                : [spec]
+        ).map(processCSSStyleSpec);
+        adoptStyles(this.renderRoot, sheets);
+    }
+
     /**
      * Ask this component to update itself.
+     *
+     * @category Render
      */
     requestUpdate(opts?: UpdateConfig) {
         this.#dirty = true;
@@ -466,9 +503,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.
@@ -553,16 +588,13 @@ export abstract class Component
     /**
      * Return an iterator over this component's children which are also
      * {@link Component}s.
+     *
+     * @category Queries
      */
     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);
     }
 
     /**
@@ -571,6 +603,8 @@ export abstract class Component
      *
      * The default implementation waits for any children which are also
      * {@link Component}s to report that they have also stabilised.
+     *
+     * @category Render
      */
     protected async stabilise(): Promise<void> {
         // wait for children to stabilise
@@ -579,8 +613,27 @@ 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.
+     * @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 {
         //
@@ -589,6 +642,7 @@ export abstract class Component
     /**
      * This lifecycle callback is called after the component's first update has
      * completed, and before {@link Component.updated}.
+     * @category Lifecycle
      */
     protected firstUpdated() {
         //
@@ -599,6 +653,7 @@ export abstract class Component
      * stabilised after its first update.
      *
      * @see {@link Component.hasStabilised}
+     * @category Lifecycle
      */
     protected stabilised() {
         //
@@ -608,6 +663,7 @@ export abstract class Component
      * 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() {
         //
@@ -617,6 +673,7 @@ export abstract class Component
      * 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() {
         //
@@ -637,19 +694,42 @@ export abstract class Component
      *         `;
      *     }
      * }
+     *
+     * @category Render
      */
     protected render(): unknown {
         return nothing;
     }
 
-    [Symbol.dispose]() {
+    /** @internal */
+    [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.
+     * @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;
+    use(disposifiable: Disposifiable | null | undefined): Disposable | null | undefined {
+        if (isNullish(disposifiable)) {
+            return disposifiable;
+        }
+        const disposable = toDisposable(disposifiable);
+        this.#finalCleanupContext.use(disposable);
+        return disposable;
     }
 
     /**
@@ -667,7 +747,13 @@ export abstract class Component
      *     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;
@@ -677,7 +763,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;
         }
@@ -690,6 +784,7 @@ export abstract class Component
      * 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,
@@ -703,6 +798,7 @@ export abstract class Component
      * 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 {
         return this.shadowRoot?.activeElement ?? this.querySelector(":focus");
@@ -728,6 +824,7 @@ export abstract class Component
      *         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;
@@ -766,6 +863,7 @@ export abstract class Component
      *         `;
      *     }
      * }
+     * @category Queries
      */
     queryAll<El extends keyof HTMLElementTagNameMap>(
         selector: El,
@@ -791,6 +889,7 @@ export abstract class Component
      *
      * 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; reactive: true },