@adobe/data-lit 0.10.14 → 0.10.15

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

@@ -17,59 +17,58 @@ function isReactiveHost(host: Component): host is ReactiveHost {
 }
 
 /**
- * Dispose every effect-style hook slot and reset the hook cursor so the next
- * render re-initializes hooks from scratch. Only slots that expose a
- * `dispose` function (effects, subscriptions) are torn down; value slots
- * (state, memo, ref) are simply dropped.
+ * 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.
  */
-function disposeHooks(host: Component): void {
+function finalizeHooks(host: Component): void {
     const { hooks } = host;
     if (hooks) {
         for (const hook of hooks) {
             (hook as { dispose?: () => void } | undefined)?.dispose?.();
         }
     }
-    // Invariant: every live subscription (useEffect / useObservable / ...) exposes a
-    // `dispose` and is torn down in the loop above, so nothing should fire after this.
-    // A useState setter closure that still runs post-disconnect would write into the
-    // emptied array and requestUpdate a detached host. That signals an un-torn-down
-    // subscription (a bug at the subscription site), not something to guard here.
     host.hooks = [];
     host.hookIndex = 0;
 }
 
 /**
- * Give a hook host a real disconnect edge.
+ * Give a hook host a correct lifecycle by separating two concerns that the DOM
+ * connect/disconnect edge conflates.
  *
- * The hook model stores every effect's cleanup in `host.hooks[i].dispose`,
- * but {@link useEffect} only invokes it when dependencies change — never when
- * the element leaves the DOM. Left alone, every `useObservable` /
- * `useObservableValues` / `useEffect` subscription leaks on unmount and keeps
- * firing `requestUpdate` on a detached element. `useConnected` is likewise
- * inert because nothing dispatches the `"connected"` / `"disconnected"`
- * events it listens for.
+ * A hook host has two kinds of slot:
  *
- * This installs a single Lit {@link ReactiveController} — the one hook-friendly
- * path to a genuine `hostDisconnected` — that:
- *  - on disconnect, *schedules* (on a microtask) dispatching `"disconnected"`,
- *    disposing every hook slot, and clearing the cursor (full unmount semantics);
- *  - on connect, if a teardown is still pending it CANCELS it (the disconnect
- *    was half of a DOM move — hooks are intact, so nothing re-subscribes and no
- *    re-render is forced); otherwise it dispatches `"connected"` and, on a true
- *    reconnect, forces a re-render so the torn-down hooks re-initialize.
+ *  - **Value / subscription slots** — {@link useState}, {@link useRef},
+ *    {@link useMemo}, and effect-backed subscriptions ({@link useEffect},
+ *    {@link useObservable}, {@link useObservableValues}). These are *stateful*
+ *    and *expensive to rebuild*. They must SURVIVE a DOM move and be finalized
+ *    only when the element is genuinely gone.
+ *  - **Connectedness edges** — {@link useConnected}, the primitive for window /
+ *    document listeners, portals, drag sessions: things that track raw DOM
+ *    connectedness and must attach/detach *synchronously* on every edge.
  *
- * ## Why disposal is deferred
+ * The trap: the DOM fires `disconnectedCallback` then `connectedCallback`
+ * **synchronously, in the same task,** whenever a connected element is merely
+ * *moved* (a Lit `repeat` reorder, a list re-parenting, a drag-reorder). There
+ * is no synchronous signal that distinguishes a move from a genuine unmount, so
+ * this controller does not try to classify the edge. Instead it handles each
+ * concern with the policy that concern actually wants:
  *
- * The DOM fires `disconnectedCallback` then `connectedCallback` **synchronously,
- * in the same task,** whenever a connected element is merely *moved* — a Lit
- * `repeat` reorder, a list re-parenting, a drag-reorder. Disposing inline would
- * tear down and rebuild every subscription (re-running uncached producers) plus
- * force a re-render on every such move, with the hook state momentarily reset —
- * the studio-page lag, refresh churn, and transient empty lists on project
- * switch (FFP-111900). Deferring teardown one microtask lets a synchronous
- * reconnect distinguish a move (cancel) from a genuine unmount (let it run), so
- * a move is a no-op and only a real unmount disposes. A late reconnect (a
- * different task) is treated as unmount+remount, which is correct.
+ *  - **Edges fire synchronously, every time.** `hostConnected` /
+ *    `hostDisconnected` dispatch the `"connected"` / `"disconnected"` events
+ *    inline on every raw edge, so {@link useConnected} tears down and re-attaches
+ *    deterministically — including across a move (cheap, and exactly what a
+ *    listener/portal wants).
+ *  - **Slot finalization is deferred behind an `isConnected` re-check.** A
+ *    disconnect schedules a microtask; when it runs it disposes the slots only
+ *    if the host is STILL disconnected. A move has reconnected by then, so its
+ *    slots survive untouched — no re-subscribe, no state reset, no forced
+ *    re-render. A genuine unmount is still disconnected, so it finalizes,
+ *    preserving the unmount-leak fix.
+ *
+ * On a reconnect after a genuine finalization, the slots are empty, so the
+ * controller forces one `requestUpdate` to re-initialize them.
  *
  * It is installed lazily from inside the wrapped `render` (see {@link withHooks}),
  * which runs after `connectedCallback`, so `addController` fires `hostConnected`
@@ -87,42 +86,45 @@ export function installHooksController(host: Component): void {
     // guards against a re-entrant render re-installing a duplicate controller.
     host[HOOKS_CONTROLLER] = true;
 
-    let connectedOnce = false;
-    // True between a disconnect and its scheduled teardown. A reconnect that sees
-    // this flag set is the tail of a move and cancels the teardown.
-    let pendingDisposal = false;
+    // The slots were finalized (disposed + cleared) while the host was detached,
+    // so the next connect must re-render to re-initialize and re-subscribe them.
+    let finalized = false;
+    // A finalization microtask is already queued; don't queue a second.
+    let finalizationQueued = false;
+
     const controller: ReactiveController = {
         hostConnected() {
-            if (pendingDisposal) {
-                // Tail of a MOVE: the just-fired disconnect scheduled a teardown that
-                // has not run yet. Cancel it — the hooks are untouched, so there is
-                // nothing to re-subscribe and no reason to force a re-render.
-                pendingDisposal = false;
-                return;
-            }
-            // The "connected" / "disconnected" events are for EXTERNAL listeners only.
-            // The internal useConnected does NOT depend on them: this fires before the
-            // render body attaches any listener, so useConnected is driven by its direct
-            // isConnected check plus useEffect cleanup instead.
+            // Fire the connect edge synchronously on EVERY connect (mount / move /
+            // remount) so edge hooks (useConnected) run their setup deterministically.
             host.dispatchEvent(new Event("connected"));
-            if (connectedOnce) {
-                // Reconnect: the previous disconnect disposed and cleared every
-                // hook slot, so re-render to re-run hooks and re-subscribe.
+            if (finalized) {
+                // The host was fully finalized while detached (a genuine unmount): its
+                // slots are empty, so re-render to re-initialize and re-subscribe them.
+                finalized = false;
                 host.requestUpdate();
             }
-            connectedOnce = true;
         },
         hostDisconnected() {
-            // Defer teardown one microtask so a synchronous reconnect (a DOM move)
-            // can cancel it above. Only a genuine unmount reaches the callback.
-            pendingDisposal = true;
+            // Fire the disconnect edge synchronously on EVERY disconnect (unmount /
+            // move) so edge hooks tear down synchronously.
+            host.dispatchEvent(new Event("disconnected"));
+            // Defer slot finalization behind an isConnected re-check: a DOM move has
+            // reconnected by the time the microtask runs, so its value/subscription
+            // slots survive untouched; only a genuine unmount (still detached) is
+            // finalized. This is what keeps a move from churning subscriptions while
+            // still disposing them on a real unmount.
+            if (finalizationQueued) {
+                return;
+            }
+            finalizationQueued = true;
             queueMicrotask(() => {
-                if (!pendingDisposal) {
+                finalizationQueued = false;
+                if (host.isConnected) {
+                    // Moved / reconnected within the task — keep every slot alive.
                     return;
                 }
-                pendingDisposal = false;
-                host.dispatchEvent(new Event("disconnected"));
-                disposeHooks(host);
+                finalizeHooks(host);
+                finalized = true;
             });
         },
     };

package/src/hooks/component/hooks-lifecycle.integration.test.ts

@@ -0,0 +1,279 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+// @vitest-environment happy-dom
+import { describe, it, expect } from "vitest";
+import { LitElement, html } from "lit";
+import type { Observe } from "@adobe/data/observe";
+import { attachDecorator } from "../attach-decorator.js";
+import { withHooks } from "../with-hooks.js";
+import { useObservable } from "../use-observable.js";
+import { useState } from "../use-state.js";
+import { useConnected } from "../use-connected.js";
+import { useEffect } from "../use-effect.js";
+
+/**
+ * Real-DOM regression tests for the two-slot hook lifecycle:
+ *
+ *  - Value/subscription slots (useState, useObservable) SURVIVE a DOM move and
+ *    are finalized only on a genuine unmount (deferred `isConnected` re-check).
+ *  - Connectedness edges (useConnected) fire SYNCHRONOUSLY on every raw
+ *    connect/disconnect edge — including a move — so listener/portal/drag setup
+ *    tears down and re-attaches deterministically, with no deferral.
+ *
+ * These pin the contract that neither the 0.10.11 nuke-on-disconnect nor the
+ * 0.10.14 defer-everything controller could satisfy simultaneously.
+ */
+
+const flushMicrotasks = (): Promise<void> => new Promise(resolve => queueMicrotask(resolve));
+
+/** An Observe whose subscribe/unsubscribe churn the test can inspect. */
+function createTrackedObservable(initial = 0): {
+    observable: Observe<number>;
+    subscriberCount: () => number;
+    totalSubscribes: () => number;
+    totalUnsubscribes: () => number;
+} {
+    const subscribers = new Set<(value: number) => void>();
+    let subscribes = 0;
+    let unsubscribes = 0;
+    const observable: Observe<number> = observer => {
+        subscribes++;
+        subscribers.add(observer);
+        observer(initial);
+        return () => {
+            unsubscribes++;
+            subscribers.delete(observer);
+        };
+    };
+    return {
+        observable,
+        subscriberCount: () => subscribers.size,
+        totalSubscribes: () => subscribes,
+        totalUnsubscribes: () => unsubscribes,
+    };
+}
+
+// Module-scoped probes the element writes into, so a test can read edge/render
+// history without reaching into the element instance.
+let connectEdges: string[] = [];
+let disconnectEdges: string[] = [];
+let openResources = 0;
+let effectSetups = 0;
+let effectCleanups = 0;
+let renderCount = 0;
+let observableUnderTest: Observe<number>;
+
+class LifecycleProbeElement extends LitElement {
+    constructor() {
+        super();
+        attachDecorator(this, "render", withHooks);
+    }
+    render() {
+        renderCount++;
+        // Edge primitive: must fire synchronously on every connect/disconnect edge,
+        // and open exactly one resource per connect (balanced by its teardown).
+        useConnected(() => {
+            connectEdges.push("connect");
+            openResources++;
+            return () => {
+                disconnectEdges.push("disconnect");
+                openResources--;
+            };
+        });
+        // Plain effect slot: React-parity — cleanup on finalization/dep-change,
+        // never on a bare disconnect (so it survives a move too).
+        useEffect(() => {
+            effectSetups++;
+            return () => {
+                effectCleanups++;
+            };
+        }, []);
+        // Value slot: must survive a move (retain its number across re-parenting).
+        const [n] = useState(() => 41);
+        // Subscription slot: must survive a move (no unsubscribe/re-subscribe).
+        const value = useObservable(observableUnderTest);
+        return html`<span>${n}:${value ?? ""}</span>`;
+    }
+}
+customElements.define("lifecycle-probe-element", LifecycleProbeElement);
+
+function resetProbes(obs: Observe<number>): void {
+    connectEdges = [];
+    disconnectEdges = [];
+    openResources = 0;
+    effectSetups = 0;
+    effectCleanups = 0;
+    renderCount = 0;
+    observableUnderTest = obs;
+}
+
+describe("two-slot hook lifecycle — real DOM", () => {
+    it("useConnected fires its disconnect edge SYNCHRONOUSLY on a genuine unmount", async () => {
+        const { observable } = createTrackedObservable();
+        resetProbes(observable);
+        const el = document.createElement("lifecycle-probe-element") as LifecycleProbeElement;
+        document.body.appendChild(el);
+        await el.updateComplete;
+        expect(connectEdges).toEqual(["connect"]);
+        expect(disconnectEdges).toEqual([]);
+
+        el.remove();
+        // The edge is synchronous: no microtask flush before this assertion.
+        expect(disconnectEdges).toEqual(["disconnect"]);
+    });
+
+    it("useConnected runs setup ONCE across ordinary re-renders — no per-render leak", async () => {
+        const { observable } = createTrackedObservable();
+        resetProbes(observable);
+        const el = document.createElement("lifecycle-probe-element") as LifecycleProbeElement;
+        document.body.appendChild(el);
+        await el.updateComplete;
+        expect(connectEdges).toEqual(["connect"]);
+        expect(openResources).toBe(1);
+
+        // Ordinary re-renders (no connect/disconnect edge) re-run the hook body but
+        // must NOT re-invoke setup — the teardown handle persists across renders.
+        el.requestUpdate();
+        await el.updateComplete;
+        el.requestUpdate();
+        await el.updateComplete;
+        expect(connectEdges).toEqual(["connect"]);
+        expect(openResources).toBe(1);
+
+        // Unmount tears down exactly the one open resource — nothing leaked.
+        el.remove();
+        expect(disconnectEdges).toEqual(["disconnect"]);
+        expect(openResources).toBe(0);
+    });
+
+    it("useConnected churns disconnect→connect SYNCHRONOUSLY on a MOVE (re-parent)", async () => {
+        const { observable } = createTrackedObservable();
+        resetProbes(observable);
+        const parentA = document.createElement("div");
+        const parentB = document.createElement("div");
+        document.body.append(parentA, parentB);
+        const el = document.createElement("lifecycle-probe-element") as LifecycleProbeElement;
+        parentA.appendChild(el);
+        await el.updateComplete;
+        expect(connectEdges).toEqual(["connect"]);
+
+        // MOVE: disconnectedCallback then connectedCallback fire synchronously.
+        parentB.appendChild(el);
+        expect(el.isConnected).toBe(true);
+        // The edge primitive tore down and re-attached, synchronously and in order.
+        expect(disconnectEdges).toEqual(["disconnect"]);
+        expect(connectEdges).toEqual(["connect", "connect"]);
+    });
+
+    it("value + subscription slots SURVIVE a MOVE (state kept, no re-subscribe, no forced render)", async () => {
+        const { observable, subscriberCount, totalSubscribes, totalUnsubscribes } = createTrackedObservable();
+        resetProbes(observable);
+        const parentA = document.createElement("div");
+        const parentB = document.createElement("div");
+        document.body.append(parentA, parentB);
+        const el = document.createElement("lifecycle-probe-element") as LifecycleProbeElement;
+        parentA.appendChild(el);
+        await el.updateComplete;
+        expect(totalSubscribes()).toBe(1);
+        const rendersBeforeMove = renderCount;
+
+        parentB.appendChild(el);
+        await flushMicrotasks();
+        await el.updateComplete;
+
+        // Subscription untouched; useState value preserved; no re-render forced.
+        expect(subscriberCount()).toBe(1);
+        expect(totalSubscribes()).toBe(1);
+        expect(totalUnsubscribes()).toBe(0);
+        expect(renderCount).toBe(rendersBeforeMove);
+    });
+
+    it("finalizes on a genuine unmount — subscription disposed, no leak", async () => {
+        const { observable, subscriberCount, totalUnsubscribes } = createTrackedObservable();
+        resetProbes(observable);
+        const el = document.createElement("lifecycle-probe-element") as LifecycleProbeElement;
+        document.body.appendChild(el);
+        await el.updateComplete;
+        expect(subscriberCount()).toBe(1);
+
+        el.remove();
+        await flushMicrotasks();
+
+        expect(subscriberCount()).toBe(0);
+        expect(totalUnsubscribes()).toBe(1);
+    });
+
+    it("a genuine unmount→remount (across a task) re-initializes and re-subscribes the slots", async () => {
+        const { observable, subscriberCount, totalSubscribes } = createTrackedObservable();
+        resetProbes(observable);
+        const el = document.createElement("lifecycle-probe-element") as LifecycleProbeElement;
+        document.body.appendChild(el);
+        await el.updateComplete;
+        expect(totalSubscribes()).toBe(1);
+
+        // Unmount, let finalization run (task boundary), then remount.
+        el.remove();
+        await flushMicrotasks();
+        expect(subscriberCount()).toBe(0);
+
+        document.body.appendChild(el);
+        await el.updateComplete;
+
+        // Slots were finalized while detached, so the remount re-subscribed.
+        expect(subscriberCount()).toBe(1);
+        expect(totalSubscribes()).toBe(2);
+        // And the edge primitive reconnected.
+        expect(connectEdges.filter(e => e === "connect").length).toBe(2);
+    });
+
+    it("a genuine unmount→remount to a DIFFERENT parent (across a task) re-initializes and re-subscribes", async () => {
+        const { observable, subscriberCount, totalSubscribes } = createTrackedObservable();
+        resetProbes(observable);
+        const parentA = document.createElement("div");
+        const parentB = document.createElement("div");
+        document.body.append(parentA, parentB);
+        const el = document.createElement("lifecycle-probe-element") as LifecycleProbeElement;
+        parentA.appendChild(el);
+        await el.updateComplete;
+        expect(totalSubscribes()).toBe(1);
+
+        // Unmount from A, let finalization run, then remount under a DIFFERENT parent.
+        // The finalization gate reads `isConnected` (not "did it reconnect to the same
+        // node"), so a remount anywhere is handled uniformly.
+        el.remove();
+        await flushMicrotasks();
+        expect(subscriberCount()).toBe(0);
+
+        parentB.appendChild(el);
+        await el.updateComplete;
+
+        expect(subscriberCount()).toBe(1);
+        expect(totalSubscribes()).toBe(2);
+        expect(connectEdges.filter(e => e === "connect").length).toBe(2);
+    });
+
+    it("plain useEffect cleanup does NOT run on a MOVE, and runs (deferred) on a genuine unmount", async () => {
+        const { observable } = createTrackedObservable();
+        resetProbes(observable);
+        const parentA = document.createElement("div");
+        const parentB = document.createElement("div");
+        document.body.append(parentA, parentB);
+        const el = document.createElement("lifecycle-probe-element") as LifecycleProbeElement;
+        parentA.appendChild(el);
+        await el.updateComplete;
+        expect(effectSetups).toBe(1);
+        expect(effectCleanups).toBe(0);
+
+        // MOVE: the effect slot survives untouched — no cleanup, no re-setup.
+        parentB.appendChild(el);
+        await flushMicrotasks();
+        await el.updateComplete;
+        expect(effectSetups).toBe(1);
+        expect(effectCleanups).toBe(0);
+
+        // UNMOUNT: cleanup runs on the finalization microtask, not synchronously.
+        el.remove();
+        expect(effectCleanups).toBe(0);
+        await flushMicrotasks();
+        expect(effectCleanups).toBe(1);
+    });
+});

package/src/hooks/use-connected.ts

@@ -2,40 +2,66 @@
 
 import type { EffectCallback } from "./use-effect.js";
 import { useEffect } from "./use-effect.js";
+import { useRef } from "./use-ref.js";
 import { Component_stack } from "./component/stack.js";
 
+/**
+ * Run `callback` on every DOM connect edge and its returned teardown on every
+ * disconnect edge — the connectedness primitive for `window` / `document`
+ * listeners, portals, and drag sessions that must attach and detach
+ * *synchronously* as the host enters and leaves the DOM.
+ *
+ * The hooks controller (see `installHooksController`) dispatches the
+ * `"connected"` / `"disconnected"` events synchronously on every raw edge,
+ * including a DOM move, so a move tears the setup down and re-attaches it
+ * deterministically.
+ *
+ * Setup runs exactly ONCE per connect. The teardown handle lives in a ref that
+ * persists across renders, so ordinary re-renders (which re-run this hook body)
+ * neither re-invoke setup nor leak — the setup/teardown pair is driven only from
+ * the edge, never from the render pass. The callback is read live through a ref,
+ * so callers may pass a fresh closure on every render.
+ */
 export function useConnected(callback: EffectCallback, dependencies?: unknown[]) {
     const component = Component_stack.active();
 
-    let disconnect: (() => void) | void;
-    function onConnect() {
-        if (!disconnect) {
-            disconnect = callback();
-        }
-    }
-
-    function onDisconnect() {
-        if (disconnect) {
-            disconnect?.();
-            disconnect = undefined;
-        }
-    }
+    // Live-read the latest callback so a fresh closure each render is honored
+    // without re-registering the edge listeners.
+    const callbackRef = useRef(callback);
+    callbackRef.current = callback;
 
-    //  TODO
-    if (component.isConnected) {
-        onConnect();
-    }
+    // Persistent teardown handle: the cleanup returned by `callback` while
+    // connected, or `undefined` while disconnected. A ref (not a per-render
+    // local) so the "already connected" guard holds across renders — this is
+    // what makes setup idempotent per connect instead of per render.
+    const state = useRef<{ disconnect: (() => void) | void }>({ disconnect: undefined });
 
     useEffect(() => {
+        const onConnect = () => {
+            if (!state.current.disconnect) {
+                state.current.disconnect = callbackRef.current();
+            }
+        };
+        const onDisconnect = () => {
+            if (state.current.disconnect) {
+                state.current.disconnect();
+                state.current.disconnect = undefined;
+            }
+        };
+
+        // On first mount the controller dispatches "connected" during
+        // `addController`, before this effect attaches its listener, so run setup
+        // now if the host is already connected.
+        if (component.isConnected) {
+            onConnect();
+        }
         component.addEventListener("connected", onConnect);
         component.addEventListener("disconnected", onDisconnect);
 
         return () => {
             component.removeEventListener("connected", onConnect);
             component.removeEventListener("disconnected", onDisconnect);
-
             onDisconnect();
-        }
-
+        };
     }, dependencies);
-}
+}