@bodil/dom 0.1.9 → 0.1.10

package/dist/signal.test.js.map

@@ -1 +1 @@
-{"version":3,"file":"signal.test.js","sourceRoot":"","sources":["../src/signal.test.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"signal.test.js","sourceRoot":"","sources":["../src/signal.test.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bodil/dom",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "description": "DOM and web component tools",
   "homepage": "https://codeberg.org/bodil/dom",
   "repository": {
@@ -62,9 +62,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@bodil/core": "^0.4.9",
-    "@bodil/opt": "^0.4.2",
-    "@bodil/signal": "^0.3.3",
+    "@bodil/core": "^0.5.2",
+    "@bodil/opt": "^0.4.3",
+    "@bodil/signal": "^0.5.1",
     "lit": "^3.3.2",
     "type-fest": "^5.3.1"
   },
@@ -72,20 +72,22 @@
     "@eslint/eslintrc": "^3.3.3",
     "@eslint/js": "^9.39.2",
     "@ianvs/prettier-plugin-sort-imports": "^4.7.0",
-    "@typescript-eslint/eslint-plugin": "^8.51.0",
-    "@typescript-eslint/parser": "^8.51.0",
+    "@typescript-eslint/eslint-plugin": "^8.52.0",
+    "@typescript-eslint/parser": "^8.52.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",
     "eslint-config-prettier": "^10.1.8",
-    "eslint-plugin-jsdoc": "^54.7.0",
-    "globals": "^16.5.0",
+    "eslint-plugin-jsdoc": "^61.5.0",
+    "globals": "^17.0.0",
     "happy-dom": "^20.0.11",
     "npm-run-all2": "^8.0.4",
     "prettier": "^3.7.4",
     "typedoc": "^0.28.15",
     "typedoc-plugin-extras": "^4.0.1",
     "typedoc-plugin-mdn-links": "^5.0.10",
+    "typedoc-theme-fresh": "^0.2.3",
     "typescript": "^5.9.3",
     "vitest": "^4.0.16"
   },

package/src/component.ts

@@ -1,3 +1,8 @@
+/**
+ * Web component base class.
+ * @module
+ */
+
 import { isIterable, isNullish } from "@bodil/core/assert";
 import { DisposableContext, toDisposable, type Disposifiable } from "@bodil/core/disposable";
 import { Signal } from "@bodil/signal";
@@ -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,
@@ -77,6 +84,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 +95,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>();
@@ -120,29 +166,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 +257,7 @@ export abstract class Component
         }
     }
 
+    /** @ignore */
     constructor() {
         super();
 
@@ -190,7 +267,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,6 +307,13 @@ 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() {
         this.#connectedContext.dispose();
         this.#controllers.forEach((c) => c.hostConnected?.());
@@ -261,6 +345,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() {
         if (this.#updateSignal !== undefined) {
             this.#updateSignalWatcher.unwatch(this.#updateSignal);
@@ -276,6 +367,9 @@ export abstract class Component
         this.#connectedContext.dispose();
     }
 
+    /**
+     * @internal
+     */
     setAttributeQuietly(name: string, value: string | null) {
         this.#ignoreAttributeUpdates++;
         if (value === null) {
@@ -286,6 +380,9 @@ export abstract class Component
         this.#ignoreAttributeUpdates--;
     }
 
+    /**
+     * @internal
+     */
     protected attributeChangedCallback(
         name: string,
         old: string | null,
@@ -301,11 +398,16 @@ export abstract class Component
         }
     }
 
-    $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 +421,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 +440,9 @@ export abstract class Component
         return renderRoot;
     }
 
+    /**
+     * Ask this component to update itself.
+     */
     requestUpdate(opts?: UpdateConfig) {
         this.#dirty = true;
 
@@ -341,7 +456,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;
@@ -360,7 +477,9 @@ export abstract class Component
         }
         return this.#hasRequiredProperties;
     }
+    #hasRequiredProperties?: Signal.Computed<boolean>;
 
+    /** @internal */
     protected async performUpdate() {
         if (!this.isConnected || !this.isUpdatePending) {
             return;
@@ -418,6 +537,7 @@ export abstract class Component
         }
     }
 
+    /** @internal */
     protected update() {
         if (this.#updateSignal !== undefined) {
             this.#updateSignalWatcher.unwatch(this.#updateSignal);
@@ -430,6 +550,10 @@ 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> {
@@ -441,6 +565,13 @@ export abstract class Component
         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.
+     */
     protected async stabilise(): Promise<void> {
         // wait for children to stabilise
         const children = this.findChildComponents();
@@ -448,29 +579,65 @@ export abstract class Component
         await Promise.all(children.map((child) => child.hasStabilised)).catch(console.error);
     }
 
+    /**
+     * 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;
     }
@@ -541,6 +708,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 +743,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 +785,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 +819,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 +854,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";
 

package/src/decorators/attribute.ts

@@ -281,7 +281,7 @@ function accessor<C extends Component, T>(
         let initValue: Option<T> = None;
         const getSig = (obj: object) =>
             signalForObject(obj, context.name, () =>
-                Signal(initValue.unwrapExact(), {
+                Signal.from(initValue.unwrapExact(), {
                     equals: Object.is,
                 }),
             ) as Signal.State<T>;

package/src/decorators/connect.test.ts

@@ -61,7 +61,7 @@ test("@connectEffect", async () => {
         methodDisposed = 0;
     let fieldRun = 0,
         fieldDisposed = 0;
-    const signal = Signal(1);
+    const signal = Signal.from(1);
 
     @customElement("connect-effect-test-class")
     class ConnectEffectTestClass extends Component {

package/src/decorators/reactive.test.ts

@@ -5,7 +5,7 @@ import { Component, reactive } from "../component";
 import { customElement } from "lit/decorators.js";
 
 test("@reactive", () => {
-    const name = Signal("Joe");
+    const name = Signal.from("Joe");
     class ReactiveTestClass {
         @reactive get name(): string {
             return name.get();

package/src/decorators/reactive.ts

@@ -5,13 +5,13 @@ import type { ClassGetterDecoratorResult, ClassGetterDecoratorTarget } from "./t
 
 export const reactiveFields = Symbol("reactiveFields");
 
-const signalCache = new WeakMap<object, Record<PropertyKey, Signal<unknown>>>();
+const signalCache = new WeakMap<object, Record<PropertyKey, Signal.Any<unknown>>>();
 
 export function signalForObject(
     obj: object,
     key: string | symbol,
-    createSignal: () => Signal<unknown>,
-): Signal<unknown> {
+    createSignal: () => Signal.Any<unknown>,
+): Signal.Any<unknown> {
     let sigs = signalCache.get(obj);
     if (sigs === undefined) {
         sigs = {};
@@ -48,7 +48,7 @@ export function reactive<C extends object, T>(
         case "accessor": {
             const getSig = (obj: object) =>
                 signalForObject(obj, context.name, () =>
-                    Signal((value as ClassAccessorDecoratorTarget<unknown, T>).get.call(obj), {
+                    Signal.from((value as ClassAccessorDecoratorTarget<unknown, T>).get.call(obj), {
                         equals: Object.is,
                     }),
                 ) as Signal.State<T>;

package/src/dom.ts

@@ -1,3 +1,8 @@
+/**
+ * DOM manipulation tools.
+ * @module
+ */
+
 import { assertNever, isNullish, unreachable } from "@bodil/core/assert";
 import { toDisposable } from "@bodil/core/disposable";
 import type { ReactiveController, ReactiveControllerHost } from "lit";
@@ -89,6 +94,9 @@ export function visibilityObserver(
     });
 }
 
+/**
+ * An iterator for traversing siblings of a DOM node.
+ */
 export class DOMIterator extends Iterator<Node> {
     private currentNode: Node | null;
     private goingForward = true;
@@ -120,6 +128,9 @@ export class DOMIterator extends Iterator<Node> {
     }
 }
 
+/**
+ * Get an iterator over the child elements of an {@link Element} or {@link DocumentFragment}.
+ */
 export function childElements(parent: Element | DocumentFragment | null): IteratorObject<Element> {
     if (parent === null) {
         return Iterator.from([]);
@@ -217,6 +228,10 @@ export function isAnimating(el: HTMLElement): boolean {
     return path.some((item) => item.getAnimations().length > 0);
 }
 
+/**
+ * Find the first {@link EventTarget} going up an {@link Event.composedPath}
+ * which matches the given `predicate`.
+ */
 export function findEventTarget<T extends EventTarget>(
     e: Event,
     predicate: (target: EventTarget) => target is T,
@@ -309,6 +324,16 @@ export function findAncestor(
     return undefined;
 }
 
+/**
+ * Test whether an {@link Element} should be considered an editor, ie. something
+ * which expects to consume `keydown` events.
+ *
+ * Use this if you have globally defined keybindings which should not be
+ * triggered when typing into an input field or other kind of editor.
+ *
+ * {@link HTMLInputElement}s, {@link HTMLTextAreaElement}s and elements with the
+ * `contenteditable` attribute set are defined as editors.
+ */
 export function isEditor(element: Element | null | undefined): boolean {
     if (isNullish(element)) {
         return false;
@@ -338,6 +363,11 @@ const scrollToItemOptionsDefault: Required<
     padEnd: 0,
 };
 
+/**
+ * Scroll an element into view.
+ *
+ * This is {@link Element.scrollIntoView} for advanced users.
+ */
 export function scrollToItem(el: HTMLElement, scrollToItemOptions: ScrollToItemOptions): void {
     const options: Required<ScrollToItemOptions> = {
         ...scrollToItemOptionsDefault,
@@ -393,6 +423,9 @@ export function scrollToItem(el: HTMLElement, scrollToItemOptions: ScrollToItemO
 
 // HasSlotController nicked largely verbatim from Shoelace
 // https://github.com/shoelace-style/shoelace/blob/next/src/internal/slot.ts
+/**
+ * A {@link ReactiveController} which tracks whether a slot is populated.
+ */
 export class HasSlotController implements ReactiveController {
     host: ReactiveControllerHost & Element;
     slotNames: Array<string> = [];