@adobe/data-lit 0.10.30 → 0.10.32

package/src/hooks/use-effect.test.ts

@@ -0,0 +1,51 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+// @vitest-environment happy-dom
+import { describe, expect, it, vi } from "vitest";
+import { useEffect } from "./use-effect.js";
+import { createHost, render, unmount } from "./test-host.test-utils.js";
+
+describe("useEffect", () => {
+    it("runs synchronously on the first render with the host as this", () => {
+        const host = createHost();
+        let self: unknown;
+        render(host, () => useEffect(function (this: unknown) { self = this; }, []));
+        expect(self).toBe(host);
+    });
+
+    it("skips equal dependencies and reruns changed ones, cleaning up first", () => {
+        const host = createHost();
+        const calls: string[] = [];
+        const effect = (n: number) => () => {
+            calls.push(`setup ${n}`);
+            return () => calls.push(`cleanup ${n}`);
+        };
+        render(host, () => useEffect(effect(1), [1]));
+        render(host, () => useEffect(effect(1), [1]));
+        render(host, () => useEffect(effect(2), [2]));
+        expect(calls).toEqual(["setup 1", "cleanup 1", "setup 2"]);
+    });
+
+    it("runs once with the default dependencies", () => {
+        const host = createHost();
+        const effect = vi.fn();
+        render(host, () => useEffect(effect));
+        render(host, () => useEffect(effect));
+        expect(effect).toHaveBeenCalledTimes(1);
+    });
+
+    it("runs the new effect when the previous cleanup throws", () => {
+        const host = createHost();
+        const next = vi.fn();
+        render(host, () => useEffect(() => () => { throw new Error("cleanup failed"); }, [1]));
+        expect(() => render(host, () => useEffect(next, [2]))).toThrow("cleanup failed");
+        expect(next).toHaveBeenCalledTimes(1);
+    });
+
+    it("runs its cleanup on unmount", () => {
+        const host = createHost();
+        const cleanup = vi.fn();
+        render(host, () => useEffect(() => cleanup, []));
+        unmount(host);
+        expect(cleanup).toHaveBeenCalledTimes(1);
+    });
+});

package/src/hooks/use-effect.ts

@@ -13,7 +13,10 @@ export function useEffect<T extends Component>(callback: EffectCallback, depende
     const oldHookState = component.hooks[hookIndex] as EffectHookState | undefined;
     const rerunEffect = !oldHookState || !equalsShallow(dependencies, oldHookState.dependencies);
     if (rerunEffect) {
-        oldHookState?.dispose?.();
-        component.hooks[hookIndex] = { dispose: callback.call(component) ?? undefined, dependencies };
+        try {
+            oldHookState?.dispose?.();
+        } finally {
+            component.hooks[hookIndex] = { dispose: callback.call(component) ?? undefined, dependencies };
+        }
     }
 }

package/src/hooks/use-element.test.ts

@@ -0,0 +1,82 @@
+// @vitest-environment happy-dom
+import { afterEach, describe, expect, it } from "vitest";
+import { LitElement, html, nothing } from "lit";
+import { attachDecorator } from "./attach-decorator.js";
+import { withHooks } from "./with-hooks.js";
+import { useElement } from "./use-element.js";
+
+class SelectorProbe extends LitElement {
+    selector = "span";
+    shadowMatch = false;
+    found: Element | null = null;
+
+    constructor() {
+        super();
+        attachDecorator(this, "render", withHooks);
+    }
+
+    render() {
+        this.found = useElement(this.selector);
+        return html`${this.shadowMatch ? html`<span class="shadow"></span>` : nothing}<slot></slot>`;
+    }
+}
+customElements.define("use-element-probe", SelectorProbe);
+
+const flushMutations = () => new Promise<void>(resolve => setTimeout(resolve));
+
+async function mount(...children: Element[]): Promise<SelectorProbe> {
+    const element = document.createElement("use-element-probe") as SelectorProbe;
+    element.append(...children);
+    document.body.append(element);
+    await element.updateComplete;
+    return element;
+}
+
+afterEach(async () => {
+    document.body.replaceChildren();
+    await flushMutations();
+});
+
+describe("useElement(selector)", () => {
+    it("returns an existing light-DOM match on the first render", async () => {
+        const span = document.createElement("span");
+        const element = await mount(span);
+        expect(element.found).toBe(span);
+    });
+
+    it("renders when a match is inserted and when it is removed", async () => {
+        const element = await mount();
+        expect(element.found).toBeNull();
+
+        const span = document.createElement("span");
+        element.append(span);
+        await flushMutations();
+        await element.updateComplete;
+        expect(element.found).toBe(span);
+
+        span.remove();
+        await flushMutations();
+        await element.updateComplete;
+        expect(element.found).toBeNull();
+    });
+
+    it("re-queries when the selector changes", async () => {
+        const element = await mount(document.createElement("span"));
+        element.selector = "button";
+        element.requestUpdate();
+        await element.updateComplete;
+        expect(element.found).toBeNull();
+    });
+
+    it("prefers a shadow-root match over a light-DOM match", async () => {
+        const light = document.createElement("span");
+        const element = document.createElement("use-element-probe") as SelectorProbe;
+        element.shadowMatch = true;
+        element.append(light);
+        document.body.append(element);
+        await element.updateComplete;
+        await flushMutations();
+        await element.updateComplete;
+        expect(element.found).toBe(element.shadowRoot?.querySelector(".shadow"));
+    });
+});

package/src/hooks/use-element.ts

@@ -6,78 +6,35 @@ import { useState } from "./use-state.js";
 
 /**
  * Hook that returns the currently active component.
- * If a querySelector is provided, it dynamically observes for child elements
- * matching the selector and triggers rerender when found.
+ * If a querySelector is provided, it returns the first match in the component's
+ * shadow root, then its light DOM. The match is re-queried on every render and
+ * whenever either tree's children change; a changed match requests a render.
  */
 export function useElement<K extends keyof HTMLElementTagNameMap>(querySelector: K): HTMLElementTagNameMap[K] | null
+export function useElement<T extends Element = HTMLElement>(querySelector: string): T | null
 export function useElement<T = HTMLElement>(): T
 export function useElement<T = HTMLElement>(querySelector?: string): T | null {
     const component = Component_stack.active();
-    
-    // If no querySelector provided, return the active component
+
     if (!querySelector) {
         return component as unknown as T;
     }
 
-    // Use state to track the found element
-    const [foundElement, setFoundElement] = useState<T | null>(null);
-    
+    const host = component as unknown as HTMLElement;
+    const find = () => (host.shadowRoot?.querySelector(querySelector) ?? host.querySelector(querySelector)) as T | null;
+    const [, setFoundElement] = useState<T | null>(null);
+    const foundElement = find();
+    setFoundElement(foundElement);
+
     useEffect(() => {
-        const element = component as unknown as HTMLElement;
-        
-        // Check if element already exists
-        const existingElement = element.querySelector(querySelector) as T | null;
-        if (existingElement) {
-            setFoundElement(existingElement);
-            return;
-        }
-        
-        // Set up MutationObserver to watch for new child elements
-        const observer = new MutationObserver((mutations) => {
-            for (const mutation of mutations) {
-                if (mutation.type === 'childList') {
-                    // Check if any added nodes match the selector
-                    for (const node of mutation.addedNodes) {
-                        if (node.nodeType === Node.ELEMENT_NODE) {
-                            const element = node as Element;
-                            // Check if the added node itself matches
-                            if (element.matches(querySelector)) {
-                                setFoundElement(element as T);
-                                observer.disconnect();
-                                return;
-                            }
-                            // Check if any descendant matches
-                            const descendant = element.querySelector(querySelector) as T | null;
-                            if (descendant) {
-                                setFoundElement(descendant);
-                                observer.disconnect();
-                                return;
-                            }
-                        }
-                    }
-                }
-            }
-        });
-        
-        // Start observing both element and shadowRoot
-        for (const observe of [element.shadowRoot, element]) {
-            if (observe) {
-                observer.observe(observe, {
-                    childList: true,
-                    subtree: true
-                });
+        const observer = new MutationObserver(() => setFoundElement(find()));
+        for (const root of [host.shadowRoot, host]) {
+            if (root) {
+                observer.observe(root, { childList: true, subtree: true });
             }
         }
-        observer.observe(element.shadowRoot ?? element, {
-            childList: true,
-            subtree: true
-        });
-        
-        // Cleanup function
-        return () => {
-            observer.disconnect();
-        };
+        return () => observer.disconnect();
     }, [querySelector]);
-    
+
     return foundElement;
 }

package/src/hooks/use-memo.test.ts

@@ -0,0 +1,66 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+// @vitest-environment happy-dom
+import { describe, expect, it, vi } from "vitest";
+import { useMemo } from "./use-memo.js";
+import { createHost, render, unmount } from "./test-host.test-utils.js";
+
+describe("useMemo", () => {
+    it("returns the cached value while dependencies are equal", () => {
+        const host = createHost();
+        const calculate = vi.fn(() => ({}));
+        const first = render(host, () => useMemo(calculate, [1, "a"]));
+        expect(render(host, () => useMemo(calculate, [1, "a"]))).toBe(first);
+        expect(calculate).toHaveBeenCalledTimes(1);
+    });
+
+    it("recalculates when a dependency changes", () => {
+        const host = createHost();
+        render(host, () => useMemo(() => 1, [1]));
+        expect(render(host, () => useMemo(() => 2, [2]))).toBe(2);
+    });
+
+    it("calculates once with the default dependencies", () => {
+        const host = createHost();
+        const calculate = vi.fn(() => 1);
+        render(host, () => useMemo(calculate));
+        render(host, () => useMemo(calculate));
+        expect(calculate).toHaveBeenCalledTimes(1);
+    });
+
+    it.each([undefined, null, 0, false])("caches the falsy result %s", result => {
+        const host = createHost();
+        const calculate = vi.fn(() => result);
+        render(host, () => useMemo(calculate, []));
+        expect(render(host, () => useMemo(calculate, []))).toBe(result);
+        expect(calculate).toHaveBeenCalledTimes(1);
+    });
+
+    it("retries a calculation that threw", () => {
+        const host = createHost();
+        expect(() => render(host, () => useMemo(() => { throw new Error("failed"); }, []))).toThrow("failed");
+        expect(render(host, () => useMemo(() => 1, []))).toBe(1);
+    });
+
+    it("never requests a render", () => {
+        const host = createHost();
+        render(host, () => useMemo(() => 1, [1]));
+        render(host, () => useMemo(() => 2, [2]));
+        expect(host.requestUpdate).not.toHaveBeenCalled();
+    });
+
+    it("keeps independent memos per slot", () => {
+        const host = createHost();
+        const read = (n: number) => [useMemo(() => `a${n}`, [n]), useMemo(() => "b", [])];
+        render(host, () => read(1));
+        expect(render(host, () => read(2))).toEqual(["a2", "b"]);
+    });
+
+    it("recalculates after an unmount", () => {
+        const host = createHost();
+        const calculate = vi.fn(() => 1);
+        render(host, () => useMemo(calculate, []));
+        unmount(host);
+        render(host, () => useMemo(calculate, []));
+        expect(calculate).toHaveBeenCalledTimes(2);
+    });
+});

package/src/hooks/use-memo.ts

@@ -1,16 +1,21 @@
 // © 2026 Adobe. MIT License. See /LICENSE for details.
 
-import { useEffect } from "./use-effect.js";
-import { useState } from "./use-state.js";
+import { equalsShallow } from "@adobe/data/equals-shallow";
+import { Component_stack } from "./component/stack.js";
 
-export function useMemo<T>(calculateValue: () => T, dependencies: unknown[] = []): T {
-    const [state, setState] = useState<T | undefined>(undefined);
-    let currentValue = state;
-
-    useEffect(() => {
-        currentValue = calculateValue();
-        setState(currentValue);
-    }, dependencies);
+interface Memo<T> {
+    value: T;
+    dependencies: unknown[];
+}
 
-    return currentValue!;
+export function useMemo<T>(calculateValue: () => T, dependencies: unknown[] = []): T {
+    const component = Component_stack.active();
+    const hookIndex = component.hookIndex++;
+    const memo = component.hooks[hookIndex] as Memo<T> | undefined;
+    if (memo && equalsShallow(dependencies, memo.dependencies)) {
+        return memo.value;
+    }
+    const value = calculateValue();
+    component.hooks[hookIndex] = { value, dependencies } satisfies Memo<T>;
+    return value;
 }

package/src/hooks/use-observable-values.test.ts

@@ -0,0 +1,53 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+// @vitest-environment happy-dom
+import { describe, expect, it, vi } from "vitest";
+import { Observe } from "@adobe/data/observe";
+import { useObservableValues } from "./use-observable-values.js";
+import { createHost, render, unmount } from "./test-host.test-utils.js";
+
+describe("useObservableValues", () => {
+    it("returns undefined until every source has emitted, then all latest values", () => {
+        const host = createHost();
+        const [name, setName] = Observe.createEvent<string>();
+        const [count, setCount] = Observe.createEvent<number>();
+        const factory = () => ({ name, count });
+
+        expect(render(host, () => useObservableValues(factory))).toBeUndefined();
+        setName("a");
+        expect(render(host, () => useObservableValues(factory))).toBeUndefined();
+        setCount(1);
+        expect(render(host, () => useObservableValues(factory))).toEqual({ name: "a", count: 1 });
+        setName("b");
+        expect(render(host, () => useObservableValues(factory))).toEqual({ name: "b", count: 1 });
+        unmount(host);
+    });
+
+    it("combines sources that emit synchronously in the first render", () => {
+        const host = createHost();
+        const factory = () => ({ a: Observe.fromConstant(1), b: Observe.fromConstant("x") });
+        expect(render(host, () => useObservableValues(factory))).toEqual({ a: 1, b: "x" });
+        unmount(host);
+    });
+
+    it("calls the factory again only when dependencies change", () => {
+        const host = createHost();
+        const factory = vi.fn(() => ({ a: Observe.fromConstant(1) }));
+        render(host, () => useObservableValues(factory, [1]));
+        render(host, () => useObservableValues(factory, [1]));
+        render(host, () => useObservableValues(factory, [2]));
+        expect(factory).toHaveBeenCalledTimes(2);
+        unmount(host);
+    });
+
+    it("unsubscribes from every source on unmount", () => {
+        const host = createHost();
+        const unsubscribed = vi.fn();
+        const tracked = <T,>(value: T): Observe<T> => observer => {
+            observer(value);
+            return unsubscribed;
+        };
+        render(host, () => useObservableValues(() => ({ a: tracked(1), b: tracked(2) })));
+        unmount(host);
+        expect(unsubscribed).toHaveBeenCalledTimes(2);
+    });
+});

package/src/hooks/use-observable.test.ts

@@ -0,0 +1,63 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+// @vitest-environment happy-dom
+import { describe, expect, it, vi } from "vitest";
+import { Observe } from "@adobe/data/observe";
+import { useObservable } from "./use-observable.js";
+import { createHost, render, unmount } from "./test-host.test-utils.js";
+
+function source<T>() {
+    const [observe, notify] = Observe.createEvent<T>();
+    const subscribe = vi.fn(observe);
+    return { observable: subscribe as Observe<T>, notify, subscribe };
+}
+
+describe("useObservable", () => {
+    it("returns undefined until the source emits, then the latest value", () => {
+        const host = createHost();
+        const { observable, notify } = source<number>();
+        expect(render(host, () => useObservable(observable))).toBeUndefined();
+        notify(1);
+        notify(2);
+        expect(render(host, () => useObservable(observable))).toBe(2);
+    });
+
+    it("returns a value emitted synchronously on subscribe in the same render", () => {
+        const host = createHost();
+        const observable: Observe<number> = observer => { observer(7); return () => {}; };
+        expect(render(host, () => useObservable(observable))).toBe(7);
+    });
+
+    it("requests a render for every notification, including a repeated reference", () => {
+        const host = createHost();
+        const { observable, notify } = source<{ count: number }>();
+        const value = { count: 0 };
+        render(host, () => useObservable(observable));
+        notify(value);
+        value.count = 1;
+        notify(value);
+        expect(host.requestUpdate).toHaveBeenCalledTimes(2);
+        expect(render(host, () => useObservable(observable))).toBe(value);
+    });
+
+    it("subscribes once per source and resubscribes when the source changes", () => {
+        const host = createHost();
+        const a = source<number>();
+        const b = source<number>();
+        render(host, () => useObservable(a.observable));
+        render(host, () => useObservable(a.observable));
+        render(host, () => useObservable(b.observable));
+        a.notify(1);
+        expect(a.subscribe).toHaveBeenCalledTimes(1);
+        expect(b.subscribe).toHaveBeenCalledTimes(1);
+        expect(host.requestUpdate).not.toHaveBeenCalled();
+    });
+
+    it("unsubscribes on unmount", () => {
+        const host = createHost();
+        const { observable, notify } = source<number>();
+        render(host, () => useObservable(observable));
+        unmount(host);
+        notify(1);
+        expect(host.requestUpdate).not.toHaveBeenCalled();
+    });
+});

package/src/hooks/use-observable.ts

@@ -1,15 +1,20 @@
 // © 2026 Adobe. MIT License. See /LICENSE for details.
 
-import { useState } from "./use-state.js";
+import { Component_stack } from "./component/stack.js";
 import { useEffect } from "./use-effect.js";
+import { useRef } from "./use-ref.js";
 import { Observe } from "@adobe/data/observe";
 
+/**
+ * Subscribes to `observable` and returns its latest value. Every notification
+ * requests a render, including one that repeats the previous value or reference.
+ */
 export function useObservable<T>(observable: Observe<T>): T | undefined {
-    let [value, setValue] = useState<T | undefined>(undefined);
-    useEffect(() => {
-        return observable(newValue => {
-            setValue(value = newValue);
-        });
-    }, [observable]);
-    return value;
+    const component = Component_stack.active();
+    const latest = useRef<T | undefined>(undefined);
+    useEffect(() => observable(value => {
+        latest.current = value;
+        component.requestUpdate();
+    }), [observable]);
+    return latest.current;
 }

package/src/hooks/use-pointer-observe.test.ts

@@ -0,0 +1,59 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+// @vitest-environment happy-dom
+import { describe, expect, it } from "vitest";
+import type { Vec2 } from "@adobe/data/math";
+import { usePointerObserve } from "./use-pointer-observe.js";
+import { createHost, render, unmount, type TestHost } from "./test-host.test-utils.js";
+
+function placeAt(host: TestHost, left: number, top: number) {
+    host.getBoundingClientRect = () => ({ left, top, x: left, y: top, width: 100, height: 100, right: left + 100, bottom: top + 100, toJSON() {} });
+}
+
+const pointerMoveOver = (host: TestHost, clientX: number, clientY: number) =>
+    host.dispatchEvent(new PointerEvent("pointermove", { clientX, clientY }));
+
+describe("usePointerObserve", () => {
+    it("emits pointer positions relative to the host", () => {
+        const host = createHost();
+        placeAt(host, 10, 20);
+        const positions: Vec2[] = [];
+        render(host, () => usePointerObserve([]))(position => positions.push(position));
+
+        pointerMoveOver(host, 15, 30);
+        pointerMoveOver(host, 50, 60);
+        expect(positions).toEqual([[5, 10], [40, 40]]);
+        unmount(host);
+    });
+
+    it("returns the same stream while dependencies are equal", () => {
+        const host = createHost();
+        const first = render(host, () => usePointerObserve([1]));
+        expect(render(host, () => usePointerObserve([1]))).toBe(first);
+        expect(render(host, () => usePointerObserve([2]))).not.toBe(first);
+        unmount(host);
+    });
+
+    it("delivers to every subscriber", () => {
+        const host = createHost();
+        placeAt(host, 0, 0);
+        const observe = render(host, () => usePointerObserve([]));
+        const a: Vec2[] = [];
+        const b: Vec2[] = [];
+        observe(position => a.push(position));
+        observe(position => b.push(position));
+        pointerMoveOver(host, 1, 2);
+        expect(a).toEqual([[1, 2]]);
+        expect(b).toEqual([[1, 2]]);
+        unmount(host);
+    });
+
+    it("stops listening on unmount", () => {
+        const host = createHost();
+        placeAt(host, 0, 0);
+        const positions: Vec2[] = [];
+        render(host, () => usePointerObserve([]))(position => positions.push(position));
+        unmount(host);
+        pointerMoveOver(host, 1, 1);
+        expect(positions).toEqual([]);
+    });
+});

package/src/hooks/use-ref.test.ts

@@ -0,0 +1,50 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+// @vitest-environment happy-dom
+import { describe, expect, it } from "vitest";
+import { useRef } from "./use-ref.js";
+import { createHost, render, unmount } from "./test-host.test-utils.js";
+
+describe("useRef", () => {
+    it("returns the same ref across renders and keeps its mutations", () => {
+        const host = createHost();
+        const ref = render(host, () => useRef(1));
+        ref.current = 2;
+
+        const next = render(host, () => useRef(1));
+        expect(next).toBe(ref);
+        expect(next.current).toBe(2);
+    });
+
+    it("ignores the initial value after the first render", () => {
+        const host = createHost();
+        render(host, () => useRef("first"));
+        expect(render(host, () => useRef("second")).current).toBe("first");
+    });
+
+    it("stores a function as a value", () => {
+        const host = createHost();
+        const callback = () => 1;
+        expect(render(host, () => useRef(callback)).current).toBe(callback);
+    });
+
+    it("does not request a render when current changes", () => {
+        const host = createHost();
+        render(host, () => useRef(0)).current = 1;
+        expect(host.requestUpdate).not.toHaveBeenCalled();
+    });
+
+    it("keeps independent refs per slot and per host", () => {
+        const host = createHost();
+        const other = createHost();
+        const [a, b] = render(host, () => [useRef(0), useRef(0)]);
+        const c = render(other, () => useRef(0));
+        expect(new Set([a, b, c]).size).toBe(3);
+    });
+
+    it("starts from the initial value after an unmount", () => {
+        const host = createHost();
+        render(host, () => useRef(0)).current = 5;
+        unmount(host);
+        expect(render(host, () => useRef(0)).current).toBe(0);
+    });
+});

package/src/hooks/use-ref.ts

@@ -1,8 +1,9 @@
 // © 2026 Adobe. MIT License. See /LICENSE for details.
 
-import { useState } from "./use-state.js";
+import { Component_stack } from "./component/stack.js";
 
 export function useRef<T>(initialValue: T): { current: T } {
-    const [state] = useState({ current: initialValue });
-    return state;
+    const component = Component_stack.active();
+    const hookIndex = component.hookIndex++;
+    return component.hooks[hookIndex] ??= { current: initialValue };
 }