@adobe/data-lit 0.10.30 → 0.10.32

package/src/hooks/use-resize-observer.test.ts

@@ -0,0 +1,114 @@
+// @vitest-environment happy-dom
+import { afterEach, describe, it, expect, vi } from "vitest";
+import { LitElement, html } from "lit";
+import { attachDecorator } from "./attach-decorator.js";
+import { withHooks } from "./with-hooks.js";
+import { useMemo } from "./use-memo.js";
+import { useResizeObserver } from "./use-resize-observer.js";
+import { useState } from "./use-state.js";
+
+class ResizeProbeElement extends LitElement {
+    renders = 0;
+    offset = 0;
+    widths: number[] = [];
+    calculateCallback = vi.fn((setWidth: (value: number) => void) => setWidth);
+
+    constructor() {
+        super();
+        attachDecorator(this, "render", withHooks);
+    }
+
+    render() {
+        this.renders++;
+        const [width, setWidth] = useState(0);
+        const memoizedSetter = useMemo(() => this.calculateCallback(setWidth), [setWidth]);
+        const offset = this.offset;
+        useResizeObserver(info => {
+            this.widths.push(info.width + offset);
+            memoizedSetter(Math.floor(info.width + offset));
+        });
+        return html`<span>${width}</span>`;
+    }
+}
+customElements.define("resize-state-probe", ResizeProbeElement);
+
+function mockResizeObserver() {
+    const observers: { emit: (width: number) => void; observe: ReturnType<typeof vi.fn>; disconnect: ReturnType<typeof vi.fn> }[] = [];
+    vi.stubGlobal("ResizeObserver", class {
+        observe = vi.fn();
+        disconnect = vi.fn();
+
+        constructor(callback: ResizeObserverCallback) {
+            observers.push({
+                emit: width => callback([
+                    { contentRect: { width, height: 20 } } as ResizeObserverEntry,
+                ], this as unknown as ResizeObserver),
+                observe: this.observe,
+                disconnect: this.disconnect,
+            });
+        }
+    });
+    return observers;
+}
+
+afterEach(async () => {
+    document.body.replaceChildren();
+    await new Promise<void>(resolve => queueMicrotask(resolve));
+    vi.unstubAllGlobals();
+});
+
+describe("useResizeObserver with state", () => {
+    it("keeps one observer, uses the latest inline callback, and skips unchanged widths", async () => {
+        const observers = mockResizeObserver();
+        const element = document.createElement("resize-state-probe") as ResizeProbeElement;
+        document.body.appendChild(element);
+        await element.updateComplete;
+        const observer = observers[0];
+        expect(observer.observe).toHaveBeenCalledExactlyOnceWith(element);
+
+        observer.emit(100.2);
+        await element.updateComplete;
+        expect(element.shadowRoot?.textContent).toBe("100");
+        expect(element.renders).toBe(2);
+        expect(observers).toHaveLength(1);
+        expect(observer.disconnect).not.toHaveBeenCalled();
+        expect(element.calculateCallback).toHaveBeenCalledTimes(1);
+
+        const requestUpdate = vi.spyOn(element, "requestUpdate");
+        observer.emit(100.8);
+        await element.updateComplete;
+        expect(requestUpdate).not.toHaveBeenCalled();
+        expect(element.renders).toBe(2);
+
+        element.offset = 10;
+        element.requestUpdate();
+        await element.updateComplete;
+        observer.emit(200);
+        await element.updateComplete;
+        expect(element.widths).toEqual([100.2, 100.8, 210]);
+        expect(element.shadowRoot?.textContent).toBe("210");
+        expect(observers).toHaveLength(1);
+        expect(observer.disconnect).not.toHaveBeenCalled();
+        expect(element.calculateCallback).toHaveBeenCalledTimes(1);
+    });
+
+    it("disconnects on unmount and creates fresh state and observer on remount", async () => {
+        const observers = mockResizeObserver();
+        const element = document.createElement("resize-state-probe") as ResizeProbeElement;
+        document.body.appendChild(element);
+        await element.updateComplete;
+        observers[0].emit(100);
+        await element.updateComplete;
+
+        element.remove();
+        await new Promise<void>(resolve => queueMicrotask(resolve));
+        expect(observers[0].disconnect).toHaveBeenCalledTimes(1);
+
+        document.body.appendChild(element);
+        await element.updateComplete;
+        expect(element.shadowRoot?.textContent).toBe("0");
+        expect(observers).toHaveLength(2);
+        expect(observers[1].observe).toHaveBeenCalledExactlyOnceWith(element);
+        expect(element.calculateCallback).toHaveBeenCalledTimes(2);
+    });
+});

package/src/hooks/use-resize-observer.ts

@@ -2,6 +2,7 @@
 
 import { useEffect } from "./use-effect.js";
 import { useElement } from "./use-element.js";
+import { useRef } from "./use-ref.js";
 
 export interface ResizeInfo {
     width: number;
@@ -17,15 +18,17 @@ export interface ResizeInfo {
  */
 export function useResizeObserver(onResize: (info: ResizeInfo) => void) {
     const element = useElement();
+    const latestCallback = useRef(onResize);
+    latestCallback.current = onResize;
 
     useEffect(() => {
         const observer = new ResizeObserver(entries => {
             for (const entry of entries) {
                 const { width, height } = entry.contentRect;
-                onResize({ width, height, entry });
+                latestCallback.current({ width, height, entry });
             }
         });
         observer.observe(element);
         return () => observer.disconnect();
-    }, [element, onResize]);
+    }, [element]);
 } 

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

@@ -0,0 +1,108 @@
+import { describe, it, expect, vi } from "vitest";
+import type { Component } from "./component/component.js";
+import { Component_stack } from "./component/stack.js";
+import { useState } from "./use-state.js";
+
+function createHost(): Component {
+    return Object.assign(new EventTarget(), {
+        isConnected: true,
+        hookIndex: 0,
+        hooks: [],
+        updatedListeners: new Set<() => void>(),
+        requestUpdate: vi.fn(),
+    });
+}
+
+function render<T>(host: Component, callback: () => T): T {
+    Component_stack.push(host);
+    try {
+        return callback();
+    } finally {
+        Component_stack.pop();
+    }
+}
+
+describe("useState", () => {
+    it("keeps the setter stable across renders and updates", () => {
+        const host = createHost();
+        const [, setValue] = render(host, () => useState(0));
+        expect(render(host, () => useState(0))[1]).toBe(setValue);
+
+        setValue(1);
+
+        const [value, nextSetter] = render(host, () => useState(0));
+        expect(value).toBe(1);
+        expect(nextSetter).toBe(setValue);
+        expect(host.requestUpdate).toHaveBeenCalledTimes(1);
+    });
+
+    it.each([0, NaN, null, undefined, "value", false, {}, []])(
+        "does not request an update for an Object.is-equal value: %s",
+        initial => {
+            const host = createHost();
+            const [, setValue] = render(host, () => useState(initial));
+
+            setValue(initial);
+            setValue(initial);
+
+            expect(host.requestUpdate).not.toHaveBeenCalled();
+        },
+    );
+
+    it("compares against the latest value before another render", () => {
+        const host = createHost();
+        const [, setValue] = render(host, () => useState(0));
+
+        setValue(1);
+        setValue(1);
+        setValue(2);
+
+        expect(host.requestUpdate).toHaveBeenCalledTimes(2);
+        expect(render(host, () => useState(0))[0]).toBe(2);
+    });
+
+    it("distinguishes positive and negative zero", () => {
+        const host = createHost();
+        const [, setValue] = render(host, () => useState(0));
+
+        setValue(-0);
+
+        expect(host.requestUpdate).toHaveBeenCalledTimes(1);
+        expect(render(host, () => useState(0))[0]).toBe(-0);
+    });
+
+    it.each([null, undefined])("initializes a nullish value only once: %s", initial => {
+        const host = createHost();
+        const initialize = vi.fn(() => initial);
+
+        render(host, () => useState(initialize));
+        render(host, () => useState(initialize));
+
+        expect(initialize).toHaveBeenCalledTimes(1);
+    });
+
+    it.each([null, undefined])("preserves a nullish update: %s", nextValue => {
+        const host = createHost();
+        const [, setValue] = render(host, () => useState<number | null | undefined>(1));
+
+        setValue(nextValue);
+
+        expect(render(host, () => useState(1))[0]).toBe(nextValue);
+    });
+
+    it("keeps state slots and hosts independent", () => {
+        const host = createHost();
+        const otherHost = createHost();
+        const read = () => [useState(0), useState(10)] as const;
+        const [first, second] = render(host, read);
+        const [other] = render(otherHost, read);
+
+        first[1](1);
+
+        expect(render(host, read).map(([value]) => value)).toEqual([1, 10]);
+        expect(render(otherHost, read).map(([value]) => value)).toEqual([0, 10]);
+        expect(first[1]).not.toBe(second[1]);
+        expect(first[1]).not.toBe(other[1]);
+        expect(otherHost.requestUpdate).not.toHaveBeenCalled();
+    });
+});

package/src/hooks/use-state.ts

@@ -2,18 +2,23 @@
 
 import { Component_stack } from "./component/stack.js";
 
+interface State<T> {
+    value: T;
+    setValue: (value: T) => void;
+}
+
 export function useState<T>(initializer: () => T): [T, (value: T) => void]
 export function useState<T>(initialValue: T): [T, (value: T) => void]
-export function useState<T>(initial: () => T) {
+export function useState<T>(initial: T | (() => T)): [T, (value: T) => void] {
     const component = Component_stack.active();
     const hookIndex = component.hookIndex++;
-    const value = component.hooks[hookIndex] ??= (typeof initial === "function" ? initial() : initial);
-    return [
-        value,
-        (newValue: T) => {
-            component.hooks[hookIndex] = newValue;
+    const state: State<T> = component.hooks[hookIndex] ??= {
+        value: typeof initial === "function" ? (initial as () => T)() : initial,
+        setValue: (newValue: T) => {
+            if (Object.is(state.value, newValue)) return;
+            state.value = newValue;
             component.requestUpdate();
-        }
-    ];
-
+        },
+    };
+    return [state.value, state.setValue];
 }

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

@@ -0,0 +1,98 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+// @vitest-environment happy-dom
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { LitElement, html } from "lit";
+import { attachDecorator } from "./attach-decorator.js";
+import { withHooks } from "./with-hooks.js";
+import { useUpdated, type UpdateEventHost } from "./use-updated.js";
+import { createHost, render } from "./test-host.test-utils.js";
+
+class UpdatedProbe extends LitElement {
+    listeners: (() => void)[] = [];
+    dependency = 0;
+    originalUpdated = vi.fn();
+
+    constructor() {
+        super();
+        attachDecorator(this, "render", withHooks);
+    }
+
+    override updated() {
+        this.originalUpdated();
+    }
+
+    render() {
+        for (const listener of this.listeners) {
+            useUpdated(listener, [this.dependency]);
+        }
+        return html``;
+    }
+}
+customElements.define("use-updated-probe", UpdatedProbe);
+
+async function mount(...listeners: (() => void)[]) {
+    const element = document.createElement("use-updated-probe") as UpdatedProbe;
+    element.listeners = listeners;
+    document.body.append(element);
+    await element.updateComplete;
+    return element;
+}
+
+afterEach(async () => {
+    document.body.replaceChildren();
+    await Promise.resolve();
+});
+
+describe("useUpdated", () => {
+    it("calls the listener after every update, after the element's own updated", async () => {
+        const calls: string[] = [];
+        const element = await mount(() => calls.push("listener"));
+        expect(calls).toEqual(["listener"]);
+        element.originalUpdated.mockImplementation(() => calls.push("updated"));
+        calls.length = 0;
+
+        element.requestUpdate();
+        await element.updateComplete;
+        expect(calls).toEqual(["updated", "listener"]);
+    });
+
+    it("calls multiple listeners in registration order through one wrapper", async () => {
+        const calls: string[] = [];
+        const element = await mount(() => calls.push("a"), () => calls.push("b"));
+        calls.length = 0;
+        element.requestUpdate();
+        await element.updateComplete;
+        expect(calls).toEqual(["a", "b"]);
+        expect(element.originalUpdated).toHaveBeenCalledTimes(2);
+    });
+
+    it("replaces the listener when dependencies change", async () => {
+        const first = vi.fn();
+        const second = vi.fn();
+        const element = await mount(first);
+        element.listeners = [second];
+        element.dependency = 1;
+        element.requestUpdate();
+        await element.updateComplete;
+        first.mockClear();
+        second.mockClear();
+
+        element.requestUpdate();
+        await element.updateComplete;
+        expect(first).not.toHaveBeenCalled();
+        expect(second).toHaveBeenCalledTimes(1);
+    });
+
+    it("removes the listener on unmount", async () => {
+        const element = await mount(() => {});
+        const listeners = (element as unknown as UpdateEventHost).updateListeners;
+        expect(listeners.size).toBe(1);
+        element.remove();
+        await Promise.resolve();
+        expect(listeners.size).toBe(0);
+    });
+
+    it("throws for a host without an updated method", () => {
+        expect(() => render(createHost(), () => useUpdated(() => {}))).toThrow("does not have an updated method");
+    });
+});

package/src/hooks/use-window-event.test.ts

@@ -0,0 +1,61 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+// @vitest-environment happy-dom
+import { describe, expect, it, vi } from "vitest";
+import { useWindowEvent } from "./use-window-event.js";
+import { createHost, render, unmount } from "./test-host.test-utils.js";
+
+describe("useWindowEvent", () => {
+    it("listens on window with the callback from the factory", () => {
+        const host = createHost();
+        const listener = vi.fn();
+        render(host, () => useWindowEvent("resize", () => listener, []));
+        window.dispatchEvent(new Event("resize"));
+        expect(listener).toHaveBeenCalledTimes(1);
+        unmount(host);
+    });
+
+    it("keeps the first callback while factory dependencies are equal", () => {
+        const host = createHost();
+        const first = vi.fn();
+        const second = vi.fn();
+        render(host, () => useWindowEvent("resize", () => first, [1]));
+        render(host, () => useWindowEvent("resize", () => second, [1]));
+        window.dispatchEvent(new Event("resize"));
+        expect(first).toHaveBeenCalledTimes(1);
+        expect(second).not.toHaveBeenCalled();
+        unmount(host);
+    });
+
+    it("replaces the callback when factory dependencies change", () => {
+        const host = createHost();
+        const first = vi.fn();
+        const second = vi.fn();
+        render(host, () => useWindowEvent("resize", () => first, [1]));
+        render(host, () => useWindowEvent("resize", () => second, [2]));
+        window.dispatchEvent(new Event("resize"));
+        expect(first).not.toHaveBeenCalled();
+        expect(second).toHaveBeenCalledTimes(1);
+        unmount(host);
+    });
+
+    it("moves its listener when the event name changes", () => {
+        const host = createHost();
+        const received: string[] = [];
+        const listener = (event: Event) => received.push(event.type);
+        render(host, () => useWindowEvent("resize", () => listener, []));
+        render(host, () => useWindowEvent("scroll", () => listener, []));
+        window.dispatchEvent(new Event("resize"));
+        window.dispatchEvent(new Event("scroll"));
+        expect(received).toEqual(["scroll"]);
+        unmount(host);
+    });
+
+    it("removes its listener on unmount", () => {
+        const host = createHost();
+        const listener = vi.fn();
+        render(host, () => useWindowEvent("resize", () => listener, []));
+        unmount(host);
+        window.dispatchEvent(new Event("resize"));
+        expect(listener).not.toHaveBeenCalled();
+    });
+});

package/src/hooks/use-window-event.ts

@@ -12,5 +12,5 @@ export function useWindowEvent<K extends keyof WindowEventMap>(
     useEffect(() => {
         window.addEventListener(event, callback);
         return () => window.removeEventListener(event, callback);
-    }, [callback]);
+    }, [event, callback]);
 }

package/src/hooks/with-hooks.test.ts

@@ -0,0 +1,45 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+// @vitest-environment happy-dom
+import { describe, expect, it, vi } from "vitest";
+import type { ReactiveController } from "lit";
+import { Component_stack } from "./component/stack.js";
+import { withHooks } from "./with-hooks.js";
+import { createHost } from "./test-host.test-utils.js";
+
+function wrap<Args extends unknown[], Return>(method: (...args: Args) => Return) {
+    return withHooks({}, "render", { value: method }).value!;
+}
+
+describe("withHooks", () => {
+    it("makes the host active during the call and forwards arguments and return value", () => {
+        const host = createHost();
+        const render = wrap(function (this: unknown, a: number, b: number) {
+            expect(Component_stack.active()).toBe(this);
+            return a + b;
+        });
+        expect(render.call(host, 1, 2)).toBe(3);
+        expect(Component_stack.active()).toBeUndefined();
+    });
+
+    it("resets the hook cursor before each call", () => {
+        const host = createHost();
+        host.hookIndex = 4;
+        const render = wrap(() => Component_stack.active().hookIndex);
+        expect(render.call(host)).toBe(0);
+    });
+
+    it("restores the stack when the method throws", () => {
+        const host = createHost();
+        const render = wrap(() => { throw new Error("render failed"); });
+        expect(() => render.call(host)).toThrow("render failed");
+        expect(Component_stack.active()).toBeUndefined();
+    });
+
+    it("installs the lifecycle controller once on a reactive host", () => {
+        const host = Object.assign(createHost(), { addController: vi.fn((_: ReactiveController) => {}) });
+        const render = wrap(() => {});
+        render.call(host);
+        render.call(host);
+        expect(host.addController).toHaveBeenCalledTimes(1);
+    });
+});

package/src/index.test.ts

@@ -0,0 +1,26 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+// @vitest-environment happy-dom
+import { describe, expect, it } from "vitest";
+import * as dataLit from "./index.js";
+
+describe("@adobe/data-lit public exports", () => {
+    it.each([
+        "useState", "useEffect", "useConnected", "useMemo", "useRef", "useObservable", "useObservableValues",
+        "useWindowEvent", "useResizeObserver", "useDebounce", "useElement", "useUpdated", "usePointerObserve",
+        "useDraggable", "useDragObserve", "useDragGenerator", "useDragTransaction",
+        "withHooks", "attachDecorator", "installHooksController",
+        "ApplicationHost", "ApplicationElement", "DatabaseElement",
+        "applyDecorator", "applyServiceDecorators", "requireService",
+    ])("exports the function %s", name => {
+        expect(typeof (dataLit as Record<string, unknown>)[name]).toBe("function");
+    });
+
+    it("exports the component stack and the Template helpers", () => {
+        expect(typeof dataLit.Component_stack.active).toBe("function");
+        expect(typeof dataLit.Template.from).toBe("function");
+    });
+
+    it("registers the application-host element", () => {
+        expect(customElements.get("application-host")).toBe(dataLit.ApplicationHost);
+    });
+});

package/src/public-types.type-test.ts

@@ -0,0 +1,17 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+/**
+ * Compile-time tests for public element and hook declarations.
+ */
+
+/* eslint-disable @typescript-eslint/no-unused-vars */
+
+import { ApplicationHost } from "./elements/application-host.js";
+import { useElement } from "./hooks/use-element.js";
+
+const _hostTag = (): ApplicationHost => document.createElement("application-host");
+
+const _tagSelector = (): HTMLButtonElement | null => useElement("button");
+const _cssSelector = (): HTMLElement | null => useElement(".target");
+const _typedCssSelector = (): HTMLInputElement | null => useElement<HTMLInputElement>("input.name");
+const _component = (): HTMLElement => useElement();

package/tsconfig.json

@@ -7,5 +7,6 @@
     "types": []
   },
   "include": ["src/**/*"],
+  "exclude": ["src/**/*.test.ts", "src/**/*.test-utils.ts", "src/**/*.type-test.ts"],
   "references": []
 }

package/tsconfig.test.json

@@ -0,0 +1,9 @@
+{
+  // Type-checks all of src, including the runtime and compile-time tests the build excludes.
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "composite": false,
+    "noEmit": true
+  },
+  "exclude": []
+}