@adobe/data-lit 0.10.31 → 0.10.32

package/src/hooks/component/hooks-controller.cleanup.test.ts

@@ -0,0 +1,65 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { ReactiveController } from "lit";
+import type { Component } from "./component.js";
+import { installHooksController } from "./hooks-controller.js";
+
+afterEach(() => {
+    vi.unstubAllGlobals();
+});
+
+/** Disconnects a host and returns its finalization, captured instead of queued. */
+function disconnect(hooks: { dispose?: () => void }[]) {
+    const controllers: ReactiveController[] = [];
+    const host = Object.assign(new EventTarget(), {
+        isConnected: false,
+        hooks,
+        hookIndex: hooks.length,
+        updatedListeners: new Set<() => void>(),
+        requestUpdate: vi.fn(),
+        addController: (controller: ReactiveController) => controllers.push(controller),
+    }) as Component & EventTarget;
+    let finalize!: () => void;
+    vi.stubGlobal("queueMicrotask", (callback: () => void) => { finalize = callback; });
+    installHooksController(host);
+    controllers[0].hostDisconnected?.();
+    return { host, finalize };
+}
+
+describe("installHooksController cleanup failures", () => {
+    it("disposes every hook and resets slots when a disposer throws", () => {
+        const later = vi.fn();
+        const { host, finalize } = disconnect([
+            { dispose: () => { throw new Error("first failed"); } },
+            { dispose: later },
+        ]);
+
+        expect(finalize).toThrow("first failed");
+        expect(later).toHaveBeenCalledTimes(1);
+        expect(host.hooks).toEqual([]);
+        expect(host.hookIndex).toBe(0);
+    });
+
+    it("reports multiple disposer failures together", () => {
+        const { finalize } = disconnect([
+            { dispose: () => { throw new Error("a"); } },
+            { dispose: () => { throw new Error("b"); } },
+        ]);
+        let caught: unknown;
+        try {
+            finalize();
+        } catch (error) {
+            caught = error;
+        }
+        expect(caught).toBeInstanceOf(AggregateError);
+        expect((caught as AggregateError).errors.map(error => (error as Error).message)).toEqual(["a", "b"]);
+    });
+
+    it("does not dispose a hook twice after a failed finalization", () => {
+        const dispose = vi.fn(() => { throw new Error("failed"); });
+        const { finalize } = disconnect([{ dispose }]);
+        expect(finalize).toThrow();
+        expect(finalize).not.toThrow();
+        expect(dispose).toHaveBeenCalledTimes(1);
+    });
+});

package/src/hooks/component/hooks-controller.ts

@@ -20,17 +20,27 @@ function isReactiveHost(host: Component): host is ReactiveHost {
  * Finalize a host: dispose every hook slot's cleanup and clear the slots so the
  * next render re-initializes from scratch. Only slots that expose a `dispose`
  * function (effects, subscriptions) are torn down; value slots (state, memo,
- * ref) are simply dropped.
+ * ref) are simply dropped. Every disposer runs even if an earlier one throws;
+ * the failures are rethrown afterwards.
  */
 function finalizeHooks(host: Component): void {
     const { hooks } = host;
-    if (hooks) {
-        for (const hook of hooks) {
+    host.hooks = [];
+    host.hookIndex = 0;
+    const errors: unknown[] = [];
+    for (const hook of hooks ?? []) {
+        try {
             (hook as { dispose?: () => void } | undefined)?.dispose?.();
+        } catch (error) {
+            errors.push(error);
         }
     }
-    host.hooks = [];
-    host.hookIndex = 0;
+    if (errors.length === 1) {
+        throw errors[0];
+    }
+    if (errors.length > 1) {
+        throw new AggregateError(errors, "Hook cleanup failed");
+    }
 }
 
 /**

package/src/hooks/component/stack.test.ts

@@ -0,0 +1,37 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, expect, it } from "vitest";
+import type { Component } from "./component.js";
+import { Component_stack } from "./stack.js";
+
+const createComponent = () => ({ hookIndex: 5 }) as unknown as Component;
+
+describe("Component_stack", () => {
+    it("makes the most recently pushed component active and restores the previous one on pop", () => {
+        const outer = createComponent();
+        const inner = createComponent();
+        Component_stack.push(outer);
+        Component_stack.push(inner);
+        expect(Component_stack.active()).toBe(inner);
+        Component_stack.pop();
+        expect(Component_stack.active()).toBe(outer);
+        Component_stack.pop();
+        expect(Component_stack.active()).toBeUndefined();
+    });
+
+    it("resets the hook cursor and creates the slot array on push", () => {
+        const component = createComponent();
+        Component_stack.push(component);
+        Component_stack.pop();
+        expect(component.hookIndex).toBe(0);
+        expect(component.hooks).toEqual([]);
+    });
+
+    it("keeps existing hook slots on push", () => {
+        const component = createComponent();
+        const hooks = [1, 2];
+        component.hooks = hooks;
+        Component_stack.push(component);
+        Component_stack.pop();
+        expect(component.hooks).toBe(hooks);
+    });
+});

package/src/hooks/test-host.test-utils.ts

@@ -0,0 +1,43 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { vi } from "vitest";
+import type { Component } from "./component/component.js";
+import { Component_stack } from "./component/stack.js";
+
+export type TestHost = HTMLElement & Component;
+
+/** A detached element that hooks can render into; `requestUpdate` is a mock. */
+export function createHost(): TestHost {
+    return Object.assign(document.createElement("div"), {
+        hookIndex: 0,
+        hooks: [] as unknown[],
+        updatedListeners: new Set<() => void>(),
+        requestUpdate: vi.fn(),
+    }) as unknown as TestHost;
+}
+
+export function render<T>(host: Component, hooks: () => T): T {
+    Component_stack.push(host);
+    try {
+        return hooks();
+    } finally {
+        Component_stack.pop();
+    }
+}
+
+/** Disposes and clears every hook slot, as a genuine unmount does. */
+export function unmount(host: Component): void {
+    for (const hook of host.hooks) {
+        (hook as { dispose?: () => void } | undefined)?.dispose?.();
+    }
+    host.hooks = [];
+    host.hookIndex = 0;
+}
+
+const pointer = (type: string, clientX: number, pointerId: number, button = 0) =>
+    new PointerEvent(type, { clientX, clientY: 0, pointerId, button, bubbles: true });
+
+export const pointerDown = (target: EventTarget, x = 0, pointerId = 1, button = 0) =>
+    target.dispatchEvent(pointer("pointerdown", x, pointerId, button));
+export const pointerMove = (x: number, pointerId = 1) => window.dispatchEvent(pointer("pointermove", x, pointerId));
+export const pointerUp = (x: number, pointerId = 1) => window.dispatchEvent(pointer("pointerup", x, pointerId));
+export const pointerCancel = (pointerId = 1) => window.dispatchEvent(pointer("pointercancel", 0, pointerId));

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

@@ -0,0 +1,88 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+// @vitest-environment happy-dom
+import { describe, expect, it, vi } from "vitest";
+import { useConnected } from "./use-connected.js";
+import { createHost, render, unmount, type TestHost } from "./test-host.test-utils.js";
+
+const connected = (host: TestHost) => host.dispatchEvent(new Event("connected"));
+const disconnected = (host: TestHost) => host.dispatchEvent(new Event("disconnected"));
+
+function mountConnected(host: TestHost) {
+    document.body.append(host);
+    return host;
+}
+
+describe("useConnected", () => {
+    it("runs setup immediately when the host is already connected", () => {
+        const host = mountConnected(createHost());
+        const setup = vi.fn();
+        render(host, () => useConnected(setup));
+        expect(setup).toHaveBeenCalledTimes(1);
+        unmount(host);
+        host.remove();
+    });
+
+    it("waits for the connected edge when the host is detached", () => {
+        const host = createHost();
+        const setup = vi.fn();
+        render(host, () => useConnected(setup));
+        expect(setup).not.toHaveBeenCalled();
+        connected(host);
+        expect(setup).toHaveBeenCalledTimes(1);
+        unmount(host);
+    });
+
+    it("tears down on each disconnect and sets up again on each connect", () => {
+        const host = createHost();
+        const events: string[] = [];
+        render(host, () => useConnected(() => {
+            events.push("setup");
+            return () => events.push("teardown");
+        }));
+        connected(host);
+        connected(host);
+        disconnected(host);
+        disconnected(host);
+        connected(host);
+        expect(events).toEqual(["setup", "teardown", "setup"]);
+        unmount(host);
+    });
+
+    it("uses the latest callback on the next connect without re-subscribing", () => {
+        const host = createHost();
+        const first = vi.fn();
+        const second = vi.fn();
+        render(host, () => useConnected(first));
+        render(host, () => useConnected(second));
+        connected(host);
+        expect(first).not.toHaveBeenCalled();
+        expect(second).toHaveBeenCalledTimes(1);
+        unmount(host);
+    });
+
+    it("re-runs setup when dependencies change while connected", () => {
+        const host = mountConnected(createHost());
+        const events: string[] = [];
+        const callback = (n: number) => () => {
+            events.push(`setup ${n}`);
+            return () => events.push(`teardown ${n}`);
+        };
+        render(host, () => useConnected(callback(1), [1]));
+        render(host, () => useConnected(callback(2), [2]));
+        expect(events).toEqual(["setup 1", "teardown 1", "setup 2"]);
+        unmount(host);
+        host.remove();
+    });
+
+    it("tears down and stops listening on unmount", () => {
+        const host = createHost();
+        const teardown = vi.fn();
+        const setup = vi.fn(() => teardown);
+        render(host, () => useConnected(setup));
+        connected(host);
+        unmount(host);
+        connected(host);
+        expect(teardown).toHaveBeenCalledTimes(1);
+        expect(setup).toHaveBeenCalledTimes(1);
+    });
+});

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

@@ -0,0 +1,69 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+// @vitest-environment happy-dom
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { vi } from "vitest";
+import { useDebounce } from "./use-debounce.js";
+import { createHost, render, unmount } from "./test-host.test-utils.js";
+
+beforeEach(() => {
+    vi.useFakeTimers();
+});
+
+afterEach(() => {
+    vi.useRealTimers();
+});
+
+describe("useDebounce", () => {
+    it("returns the initial value immediately", () => {
+        const host = createHost();
+        expect(render(host, () => useDebounce("a", 100))).toBe("a");
+    });
+
+    it("returns a new value only after the delay", () => {
+        const host = createHost();
+        render(host, () => useDebounce("a", 100));
+        render(host, () => useDebounce("b", 100));
+
+        vi.advanceTimersByTime(99);
+        expect(render(host, () => useDebounce("b", 100))).toBe("a");
+        vi.advanceTimersByTime(1);
+        expect(render(host, () => useDebounce("b", 100))).toBe("b");
+        expect(host.requestUpdate).toHaveBeenCalledTimes(1);
+        unmount(host);
+    });
+
+    it("restarts the delay on each change and keeps only the last value", () => {
+        const host = createHost();
+        render(host, () => useDebounce("a", 100));
+        render(host, () => useDebounce("b", 100));
+        vi.advanceTimersByTime(60);
+        render(host, () => useDebounce("c", 100));
+        vi.advanceTimersByTime(60);
+        expect(render(host, () => useDebounce("c", 100))).toBe("a");
+        vi.advanceTimersByTime(40);
+        expect(render(host, () => useDebounce("c", 100))).toBe("c");
+        unmount(host);
+    });
+
+    it("restarts the delay when the delay changes", () => {
+        const host = createHost();
+        render(host, () => useDebounce("a", 100));
+        render(host, () => useDebounce("b", 100));
+        vi.advanceTimersByTime(50);
+        render(host, () => useDebounce("b", 200));
+        vi.advanceTimersByTime(150);
+        expect(render(host, () => useDebounce("b", 200))).toBe("a");
+        vi.advanceTimersByTime(50);
+        expect(render(host, () => useDebounce("b", 200))).toBe("b");
+        unmount(host);
+    });
+
+    it("cancels the pending update on unmount", () => {
+        const host = createHost();
+        render(host, () => useDebounce("a", 100));
+        render(host, () => useDebounce("b", 100));
+        unmount(host);
+        vi.advanceTimersByTime(100);
+        expect(host.requestUpdate).not.toHaveBeenCalled();
+    });
+});

package/src/hooks/use-drag-generator.test.ts

@@ -0,0 +1,67 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+// @vitest-environment happy-dom
+import { describe, expect, it, vi } from "vitest";
+import { useDragGenerator } from "./use-drag-generator.js";
+import type { DragState } from "./use-drag-observe.js";
+import { createHost, pointerCancel, pointerDown, pointerMove, pointerUp, render, unmount } from "./test-host.test-utils.js";
+
+async function collectTypes(generator: AsyncGenerator<DragState>): Promise<DragState["type"][]> {
+    const types: DragState["type"][] = [];
+    for await (const value of generator) types.push(value.type);
+    return types;
+}
+
+describe("useDragGenerator", () => {
+    it("calls back once per drag with the start event and a generator that ends with the drag", async () => {
+        const host = createHost();
+        const callback = vi.fn();
+        render(host, () => useDragGenerator({}, [], callback));
+        pointerDown(host);
+        pointerMove(20);
+        pointerUp(30);
+
+        expect(callback).toHaveBeenCalledTimes(1);
+        const [generator, startEvent] = callback.mock.calls[0];
+        expect(startEvent).toBeInstanceOf(PointerEvent);
+        expect((startEvent as PointerEvent).clientX).toBe(20);
+        expect(await collectTypes(generator)).toEqual(expect.arrayContaining(["move", "end"]));
+        unmount(host);
+    });
+
+    it("ends the generator when the drag is cancelled", async () => {
+        const host = createHost();
+        const callback = vi.fn();
+        render(host, () => useDragGenerator({}, [], callback));
+        pointerDown(host);
+        pointerMove(20);
+        pointerCancel();
+
+        const types = await collectTypes(callback.mock.calls[0][0]);
+        expect(types.at(-1)).toBe("cancel");
+        unmount(host);
+    });
+
+    it("starts a new generator for each drag", () => {
+        const host = createHost();
+        const callback = vi.fn();
+        render(host, () => useDragGenerator({}, [], callback));
+        for (const x of [20, 40]) {
+            pointerDown(host);
+            pointerMove(x);
+            pointerUp(x);
+        }
+        expect(callback).toHaveBeenCalledTimes(2);
+        expect(callback.mock.calls[0][0]).not.toBe(callback.mock.calls[1][0]);
+        unmount(host);
+    });
+
+    it("stops calling back after unmount", () => {
+        const host = createHost();
+        const callback = vi.fn();
+        render(host, () => useDragGenerator({}, [], callback));
+        unmount(host);
+        pointerDown(host);
+        pointerMove(20);
+        expect(callback).not.toHaveBeenCalled();
+    });
+});

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

@@ -0,0 +1,74 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+// @vitest-environment happy-dom
+import { describe, expect, it } from "vitest";
+import { useDragObserve, type DragState } from "./use-drag-observe.js";
+import { createHost, pointerCancel, pointerDown, pointerMove, pointerUp, render, unmount } from "./test-host.test-utils.js";
+
+describe("useDragObserve", () => {
+    it("emits start, move, and end with positions and deltas", () => {
+        const host = createHost();
+        const events: DragState[] = [];
+        render(host, () => useDragObserve({}, []))(event => events.push(event));
+        pointerDown(host);
+        pointerMove(20);
+        pointerUp(30);
+
+        expect(events.map(event => event.type)).toEqual(["start", "move", "end"]);
+        expect(events[0].type === "start" && events[0].event).toBeInstanceOf(PointerEvent);
+        expect(events[1]).toEqual({ type: "move", position: [20, 0], delta: [20, 0] });
+        expect(events[2]).toEqual({ type: "end", position: [30, 0], delta: [30, 0] });
+        unmount(host);
+    });
+
+    it("emits cancel when the pointer is cancelled", () => {
+        const host = createHost();
+        const types: DragState["type"][] = [];
+        render(host, () => useDragObserve({}, []))(event => types.push(event.type));
+        pointerDown(host);
+        pointerMove(20);
+        pointerCancel();
+        expect(types).toEqual(["start", "move", "cancel"]);
+        unmount(host);
+    });
+
+    it("returns the same stream across renders and delivers drag events to it", () => {
+        const host = createHost();
+        const first = render(host, () => useDragObserve({}, []));
+        const second = render(host, () => useDragObserve({}, []));
+        expect(second).toBe(first);
+
+        const types: DragState["type"][] = [];
+        second(event => types.push(event.type));
+        pointerDown(host);
+        pointerMove(20);
+        pointerUp(20);
+        expect(types).toEqual(["start", "move", "end"]);
+        unmount(host);
+    });
+
+    it("returns a new stream when dependencies change", () => {
+        const host = createHost();
+        const first = render(host, () => useDragObserve({}, [1]));
+        const second = render(host, () => useDragObserve({}, [2]));
+        expect(second).not.toBe(first);
+
+        const types: DragState["type"][] = [];
+        second(event => types.push(event.type));
+        pointerDown(host);
+        pointerMove(20);
+        pointerUp(20);
+        expect(types).toEqual(["start", "move", "end"]);
+        unmount(host);
+    });
+
+    it("applies minDragDistance", () => {
+        const host = createHost();
+        const types: DragState["type"][] = [];
+        render(host, () => useDragObserve({ minDragDistance: 50 }, []))(event => types.push(event.type));
+        pointerDown(host);
+        pointerMove(20);
+        pointerUp(20);
+        expect(types).toEqual([]);
+        unmount(host);
+    });
+});

package/src/hooks/use-drag-observe.ts

@@ -2,6 +2,7 @@
 
 import { DraggableProps, useDraggable } from './use-draggable.js';
 import { useElement } from './use-element.js';
+import { useMemo } from './use-memo.js';
 import { Observe } from '@adobe/data/observe';
 import { Vec2 } from '@adobe/data/math';
 
@@ -37,7 +38,7 @@ export type DragState = DragStart | DragMove | DragEnd;
  * @returns
  */
 export function useDragObserve(props: DragObserveProps, dependencies: unknown[]) {
-    const [dragState, setDragState] = Observe.createEvent<DragState>();
+    const [dragState, setDragState] = useMemo(() => Observe.createEvent<DragState>(), dependencies);
     const element = useElement();
     useDraggable(element,
         {

package/src/hooks/use-drag-transaction.test.ts

@@ -0,0 +1,109 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+// @vitest-environment happy-dom
+import { describe, expect, it } from "vitest";
+import type { AsyncArgsProvider } from "@adobe/data/ecs";
+import { useDragTransaction } from "./use-drag-transaction.js";
+import type { DragEnd, DragMove } from "./use-drag-observe.js";
+import { createHost, pointerCancel, pointerDown, pointerMove, pointerUp, render, unmount } from "./test-host.test-utils.js";
+
+type Args = { x: number };
+
+function mountTransaction(update: (drag: DragMove | DragEnd) => Args | void = drag => ({ x: drag.position[0] })) {
+    const host = createHost();
+    const providers: AsyncArgsProvider<Args>[] = [];
+    render(host, () => useDragTransaction<Args>({ transaction: provider => { providers.push(provider); }, update }, []));
+    const args = (index = 0) => providers[index]() as AsyncGenerator<Args>;
+    return { host, providers, args };
+}
+
+async function collect(generator: AsyncGenerator<Args>): Promise<Args[]> {
+    const values: Args[] = [];
+    for await (const value of generator) values.push(value);
+    return values;
+}
+
+describe("useDragTransaction", () => {
+    it("yields move and end arguments and completes at the end", async () => {
+        const { host, args } = mountTransaction();
+        pointerDown(host);
+        pointerMove(20);
+        pointerUp(50);
+        expect(await collect(args())).toEqual([{ x: 20 }, { x: 50 }]);
+        unmount(host);
+    });
+
+    it("skips drags for which update returns nothing and still completes", async () => {
+        const { host, args } = mountTransaction(drag => (drag.type === "move" ? { x: drag.position[0] } : undefined));
+        pointerDown(host);
+        pointerMove(20);
+        pointerUp(50);
+        expect(await collect(args())).toEqual([{ x: 20 }]);
+        unmount(host);
+    });
+
+    it("rejects a pending read when the drag is cancelled", async () => {
+        const { host, args } = mountTransaction();
+        pointerDown(host);
+        pointerMove(20);
+        const generator = args();
+        expect(await generator.next()).toEqual({ done: false, value: { x: 20 } });
+
+        const pending = generator.next();
+        pointerCancel();
+        await expect(pending).rejects.toThrow("Drag cancelled");
+        unmount(host);
+    });
+
+    it("rejects a pending read when unmounted mid-drag", async () => {
+        const { host, args } = mountTransaction();
+        pointerDown(host);
+        pointerMove(20);
+        const generator = args();
+        await generator.next();
+
+        const pending = generator.next();
+        unmount(host);
+        await expect(pending).rejects.toThrow("Drag cancelled");
+    });
+
+    it("starts one transaction per drag", async () => {
+        const { host, providers, args } = mountTransaction();
+        pointerDown(host);
+        pointerMove(20);
+        pointerUp(20);
+        pointerDown(host);
+        pointerMove(40);
+        pointerUp(40);
+        expect(providers).toHaveLength(2);
+        expect(await collect(args(1))).toEqual([{ x: 40 }, { x: 40 }]);
+        unmount(host);
+    });
+
+    it("does not start a transaction for a press below the drag threshold", () => {
+        const { host, providers } = mountTransaction();
+        pointerDown(host);
+        pointerUp(2);
+        expect(providers).toHaveLength(0);
+        unmount(host);
+    });
+
+    it("lets an async transaction settle after cancellation without an unhandled rejection", async () => {
+        const host = createHost();
+        let settled: Promise<void> | undefined;
+        render(host, () => useDragTransaction<Args>({
+            transaction: provider => {
+                settled = (async () => {
+                    for await (const _ of provider() as AsyncGenerator<Args>) { /* consume */ }
+                })();
+                return settled;
+            },
+            update: drag => ({ x: drag.position[0] }),
+        }, []));
+        pointerDown(host);
+        pointerMove(20);
+        pointerCancel();
+        await expect(settled).rejects.toThrow("Drag cancelled");
+        await new Promise(resolve => setTimeout(resolve));
+        unmount(host);
+    });
+});