@adobe/data-lit 0.10.31 → 0.10.32

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

@@ -1,6 +1,6 @@
 // © 2026 Adobe. MIT License. See /LICENSE for details.
 
-import { DragEnd, DragMove, DragObserveProps, useDragObserve } from './use-drag-observe.js';
+import { DragEnd, DragMove, DragObserveProps, DragState, useDragObserve } from './use-drag-observe.js';
 import { useEffect } from "./use-effect.js";
 import type { AsyncArgsProvider } from '@adobe/data/ecs';
 import { Observe } from '@adobe/data/observe';
@@ -10,37 +10,58 @@ export type DragTransactionProps<T extends {} | null> = DragObserveProps & {
     update: (drag: DragMove | DragEnd) => T | void;
 };
 
+// Thrown into a drag's argument generator so the transaction discards its transient state.
+const dragCancelled = new Error('Drag cancelled');
+
+async function* toTransactionArgs<T extends {} | null>(
+    drags: AsyncGenerator<DragState>,
+    update: DragTransactionProps<T>['update'],
+): AsyncGenerator<T> {
+    for await (const drag of drags) {
+        if (drag.type === 'move' || drag.type === 'end') {
+            const args = update(drag);
+            if (args !== undefined) {
+                yield args;
+            }
+        }
+    }
+}
+
+/**
+ * Drives `transaction` with one argument generator per drag: each move or end
+ * yields `update(drag)` as intermediate arguments, the end commits the last
+ * arguments, and a cancellation (including unmount mid-drag) discards them.
+ */
 export function useDragTransaction<T extends {} | null>(props: DragTransactionProps<T>, dependencies: unknown[]) {
-    const { transaction, update } = props;
     const dragObserve = useDragObserve(props, dependencies);
-    const startDragTransaction = () => {
-        let done = false;
-        // we start the transaction by calling it with an async generator that will yield the args asynchronously
-        transaction(
-            // we create the async generator by mapping the dragObserve state changes to transaction args
-            () =>
-                Observe.toAsyncGenerator(
-                    // this uses the withMap function and the provided update and finish functions
-                    // any type 'start' will just be ignored and filtered out
-                    Observe.withFilter(dragObserve, value => {
-                        if (value.type === 'end') {
-                            done = true;
-                            return update(value);
-                        }
-                        if (value.type === 'move') {
-                            return update(value);
-                        }
-                    }),
-                    _value => done
-                )
-        );
-    };
-    // now we will observe the drag state and start a new transaction whenever a drag starts
     useEffect(() => {
-        return dragObserve(value => {
+        const { transaction, update } = props;
+        let active: AsyncGenerator<DragState> | undefined;
+        const cancel = () => {
+            const drags = active;
+            active = undefined;
+            drags?.throw(dragCancelled).catch(() => undefined);
+        };
+        const unobserve = dragObserve(value => {
             if (value.type === 'start') {
-                startDragTransaction();
+                cancel();
+                const drags = active = Observe.toAsyncGenerator(
+                    dragObserve,
+                    v => v.type === 'end' || v.type === 'cancel',
+                );
+                const result: unknown = transaction(() => toTransactionArgs(drags, update));
+                Promise.resolve(result).catch(error => {
+                    if (error !== dragCancelled) throw error;
+                });
+            } else if (value.type === 'end') {
+                active = undefined;
+            } else if (value.type === 'cancel') {
+                cancel();
             }
         });
+        return () => {
+            unobserve();
+            cancel();
+        };
     }, dependencies);
 }

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

@@ -0,0 +1,148 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+// @vitest-environment happy-dom
+import { describe, expect, it, vi } from "vitest";
+import type { Vec2 } from "@adobe/data/math";
+import { useDraggable, type DraggableProps } from "./use-draggable.js";
+import { createHost, pointerCancel, pointerDown, pointerMove, pointerUp, render, unmount } from "./test-host.test-utils.js";
+
+function mountDraggable(options: Partial<DraggableProps> = {}, onDragStart: () => Vec2 | void = () => {}) {
+    const host = createHost();
+    const parent = document.createElement("section");
+    parent.append(host);
+    const props = {
+        onDragStart: vi.fn(onDragStart),
+        onDrag: vi.fn(),
+        onDragEnd: vi.fn(),
+        onDragCancel: vi.fn(),
+        ...options,
+    };
+    render(host, () => useDraggable(host, props, []));
+    return { host, parent, props };
+}
+
+describe("useDraggable", () => {
+    it("offsets the start position from onDragStart and ends at the pointerup coordinates", () => {
+        const { host, props } = mountDraggable({}, () => [100, 200]);
+        pointerDown(host);
+        pointerMove(20);
+        pointerUp(50);
+
+        expect(props.onDrag).toHaveBeenCalledWith(expect.any(PointerEvent), [120, 200], [20, 0]);
+        expect(props.onDragEnd).toHaveBeenCalledWith(expect.any(PointerEvent), [150, 200], [50, 0]);
+        unmount(host);
+    });
+
+    it("starts from the element offset when onDragStart returns nothing", () => {
+        const { host, props } = mountDraggable();
+        Object.defineProperty(host, "offsetLeft", { value: 7 });
+        Object.defineProperty(host, "offsetTop", { value: 3 });
+        pointerDown(host);
+        pointerMove(20);
+        expect(props.onDrag).toHaveBeenCalledWith(expect.any(PointerEvent), [27, 3], [20, 0]);
+        pointerUp(20);
+        unmount(host);
+    });
+
+    it("starts once the pointer has moved at least minDragDistance", () => {
+        const { host, props } = mountDraggable({ minDragDistance: 5 });
+        pointerDown(host);
+        pointerMove(4);
+        expect(props.onDragStart).not.toHaveBeenCalled();
+        pointerMove(5);
+        expect(props.onDragStart).toHaveBeenCalledTimes(1);
+        pointerMove(6);
+        expect(props.onDragStart).toHaveBeenCalledTimes(1);
+        pointerUp(6);
+        unmount(host);
+    });
+
+    it("does not end or cancel a press released before the threshold", () => {
+        const { host, props } = mountDraggable();
+        pointerDown(host);
+        pointerMove(3);
+        pointerUp(3);
+        expect(props.onDragEnd).not.toHaveBeenCalled();
+        expect(props.onDragCancel).not.toHaveBeenCalled();
+        unmount(host);
+        expect(props.onDragCancel).not.toHaveBeenCalled();
+    });
+
+    it("sets the drag cursor and restores the original cursor at the end", () => {
+        const { host } = mountDraggable({ dragCursor: "move" });
+        host.style.cursor = "pointer";
+        pointerDown(host);
+        pointerMove(20);
+        expect(host.style.cursor).toBe("move");
+        pointerUp(20);
+        expect(host.style.cursor).toBe("pointer");
+        unmount(host);
+    });
+
+    it("adds a placeholder to the parent while dragging when requested", () => {
+        const { host, parent } = mountDraggable({ addPlaceholder: true });
+        pointerDown(host);
+        pointerMove(20);
+        expect(parent.children).toHaveLength(2);
+        pointerUp(20);
+        expect(parent.children).toHaveLength(1);
+        unmount(host);
+    });
+
+    it("stops propagation of its pointer events when requested", () => {
+        const { host } = mountDraggable({ stopPropagation: true });
+        const parentListener = vi.fn();
+        host.parentElement!.addEventListener("pointerdown", parentListener);
+        pointerDown(host);
+        expect(parentListener).not.toHaveBeenCalled();
+        pointerUp(0);
+        unmount(host);
+    });
+
+    it("cancels on pointercancel, restores the cursor, and stops delivering moves", () => {
+        const { host, props } = mountDraggable();
+        pointerDown(host);
+        pointerMove(20);
+        expect(host.style.cursor).toBe("grab");
+
+        pointerCancel();
+        pointerMove(30);
+        pointerUp(30);
+
+        expect(props.onDragCancel).toHaveBeenCalledTimes(1);
+        expect(props.onDrag).toHaveBeenCalledTimes(1);
+        expect(props.onDragEnd).not.toHaveBeenCalled();
+        expect(host.style.cursor).toBe("");
+        unmount(host);
+    });
+
+    it("ignores secondary buttons and other pointers", () => {
+        const { host, props } = mountDraggable();
+        pointerDown(host, 0, 1, 2);
+        pointerMove(20);
+        expect(props.onDragStart).not.toHaveBeenCalled();
+
+        pointerDown(host);
+        pointerDown(host, 0, 2);
+        pointerMove(20, 2);
+        pointerUp(20, 2);
+        expect(props.onDragStart).not.toHaveBeenCalled();
+        pointerMove(20);
+        pointerUp(20);
+        expect(props.onDragEnd).toHaveBeenCalledTimes(1);
+        unmount(host);
+    });
+
+    it("cancels an active drag on unmount and stops listening", () => {
+        const { host, props } = mountDraggable();
+        pointerDown(host);
+        pointerMove(20);
+        unmount(host);
+
+        expect(props.onDragCancel).toHaveBeenCalledTimes(1);
+        expect(host.style.cursor).toBe("");
+        pointerMove(30);
+        pointerDown(host);
+        pointerMove(60);
+        expect(props.onDrag).toHaveBeenCalledTimes(1);
+    });
+});

package/src/hooks/use-draggable.ts

@@ -25,86 +25,111 @@ export interface DraggableProps {
 export function useDraggable(element: HTMLElement, props: DraggableProps, dependencies: unknown[]) {
     const { minDragDistance = 10, dragCursor = 'grab', addPlaceholder = false, stopPropagation = false } = props;
     useEffect(() => {
-        let downPosition: Vec2 | null = null;
-        // the bounds of the element when the pointer was first pressed down.
+        const minDragDistanceSquared = minDragDistance * minDragDistance;
+        // The pointer that started the session; other pointers are ignored until it ends.
+        let pointerId: number | null = null;
+        let downPosition: Vec2 = [0, 0];
+        // The element position when the drag started, or null before the threshold is crossed.
         let dragStartOffset: Vec2 | null = null;
         let originalCursor = '';
         let placeholder: HTMLElement | null = null;
-        let movePosition: Vec2 = [0, 0];
-        function notify(e: PointerEvent, dragListener: DraggableProps["onDrag"]) {
-            const delta = Vec2.subtract(movePosition, downPosition!);
-            dragListener(e, Vec2.add(dragStartOffset!, delta), delta);
+
+        function notify(e: PointerEvent, start: Vec2, dragListener: DraggableProps["onDrag"]) {
+            const delta: Vec2 = [e.clientX - downPosition[0], e.clientY - downPosition[1]];
+            dragListener(e, Vec2.add(start, delta), delta);
+        }
+
+        function startDrag(e: PointerEvent): Vec2 {
+            const offset: Vec2 = [element.offsetLeft, element.offsetTop];
+            const start = (props.onDragStart(e) as Vec2 | undefined) ?? offset;
+            dragStartOffset = start;
+            if (dragCursor) {
+                originalCursor = element.style.cursor;
+                element.style.cursor = dragCursor;
+            }
+            // add a placeholder so the parent element doesn't change size when the element is dragged.
+            if (addPlaceholder) {
+                placeholder = document.createElement('div');
+                Object.assign(placeholder.style, {
+                    position: 'absolute',
+                    backgroundColor: 'pink',
+                    left: toCssUnitString(element.offsetLeft),
+                    top: toCssUnitString(element.offsetTop),
+                    width: toCssUnitString(element.offsetWidth),
+                    height: toCssUnitString(element.offsetHeight),
+                    visibility: 'hidden',
+                });
+                element.parentElement?.appendChild(placeholder);
+            }
+            return start;
         }
 
         function onPointerMove(e: PointerEvent) {
-            movePosition = [e.clientX, e.clientY];
-            if (Vec2.length(Vec2.subtract(movePosition, downPosition!)) >= minDragDistance) {
-                if (!dragStartOffset) {
-                    dragStartOffset = [element.offsetLeft, element.offsetTop];
-                    props.onDragStart(e);
-                    if (dragCursor) {
-                        originalCursor = element.style.cursor;
-                        element.style.cursor = dragCursor;
-                    }
-                    // add a placeholder so the parent element doesn't change size when the element is dragged.
-                    if (addPlaceholder) {
-                        placeholder = document.createElement('div');
-                        Object.assign(placeholder.style, {
-                            position: 'absolute',
-                            backgroundColor: 'pink',
-                            left: toCssUnitString(element.offsetLeft),
-                            top: toCssUnitString(element.offsetTop),
-                            width: toCssUnitString(element.offsetWidth),
-                            height: toCssUnitString(element.offsetHeight),
-                            visibility: 'hidden',
-                        });
-                        element.parentElement?.appendChild(placeholder);
-                    }
+            if (e.pointerId !== pointerId) return;
+            let start = dragStartOffset;
+            if (!start) {
+                const dx = e.clientX - downPosition[0];
+                const dy = e.clientY - downPosition[1];
+                if (dx * dx + dy * dy >= minDragDistanceSquared) {
+                    start = startDrag(e);
                 }
             }
-            if (dragStartOffset) {
-                notify(e, props.onDrag);
+            if (start) {
+                notify(e, start, props.onDrag);
             }
             if (stopPropagation) e.stopPropagation();
         }
-        function cleanup() {
+
+        /** Ends the session and restores the element; returns the drag start if a drag had started. */
+        function release(): Vec2 | null {
             // eslint-disable-next-line @typescript-eslint/no-use-before-define
             window.removeEventListener('pointerup', onPointerUp);
+            // eslint-disable-next-line @typescript-eslint/no-use-before-define
+            window.removeEventListener('pointercancel', onPointerCancel);
             window.removeEventListener('pointermove', onPointerMove);
-            if (dragCursor) {
+            const start = dragStartOffset;
+            if (start && dragCursor) {
                 element.style.cursor = originalCursor;
             }
-            if (placeholder) {
-                placeholder.remove();
-                placeholder = null;
-            }
+            placeholder?.remove();
+            placeholder = null;
+            pointerId = null;
+            dragStartOffset = null;
+            return start;
         }
+
         function onPointerUp(e: PointerEvent) {
-            cleanup();
-            if (dragStartOffset && props.onDragEnd) {
-                notify(e, props.onDragEnd);
+            if (e.pointerId !== pointerId) return;
+            const start = release();
+            if (start && props.onDragEnd) {
+                notify(e, start, props.onDragEnd);
             }
             if (stopPropagation) e.stopPropagation();
-            downPosition = null;
-            dragStartOffset = null;
         }
+
+        function onPointerCancel(e: PointerEvent) {
+            if (e.pointerId !== pointerId) return;
+            if (release()) {
+                props.onDragCancel?.();
+            }
+        }
+
         function onPointerDown(e: PointerEvent) {
             // Only start drag transaction for left mouse button clicks
-            if (e.button !== 0) return;
+            if (e.button !== 0 || pointerId !== null) return;
 
+            pointerId = e.pointerId;
+            downPosition = [e.clientX, e.clientY];
             window.addEventListener('pointermove', onPointerMove);
             window.addEventListener('pointerup', onPointerUp);
-            downPosition = [e.clientX, e.clientY];
+            window.addEventListener('pointercancel', onPointerCancel);
             if (stopPropagation) e.stopPropagation();
         }
 
         element?.addEventListener('pointerdown', onPointerDown);
         return () => {
             element?.removeEventListener('pointerdown', onPointerDown);
-            if (downPosition) {
-                cleanup();
-            }
-            if (dragStartOffset) {
+            if (pointerId !== null && release()) {
                 props.onDragCancel?.();
             }
         };

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;
 }