@adobe/data-lit 0.10.30 → 0.10.32

package/src/elements/application-host.test.ts

@@ -0,0 +1,57 @@
+// @vitest-environment happy-dom
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { html } from "lit";
+import type { Service } from "@adobe/data/service";
+import "./application-host.js";
+
+function deferred<T>() {
+    let resolve!: (value: T) => void;
+    const promise = new Promise<T>(r => { resolve = r; });
+    return { promise, resolve };
+}
+
+afterEach(() => {
+    document.body.replaceChildren();
+});
+
+describe("ApplicationHost", () => {
+    it("creates one service across a DOM move", async () => {
+        const service = { serviceName: "main" } as unknown as Service;
+        const pending = deferred<Service>();
+        const createService = vi.fn(() => pending.promise);
+        const host = document.createElement("application-host");
+        host.createService = createService;
+        host.renderElement = () => html``;
+
+        const [parentA, parentB] = [document.createElement("div"), document.createElement("div")];
+        document.body.append(parentA, parentB);
+        parentA.append(host);
+        parentB.append(host);
+        pending.resolve(service);
+        await pending.promise;
+        await host.updateComplete;
+
+        expect(createService).toHaveBeenCalledTimes(1);
+        expect(host.service).toBe(service);
+
+        parentA.append(host);
+        await host.updateComplete;
+        expect(createService).toHaveBeenCalledTimes(1);
+    });
+
+    it("retries creation after a failure", async () => {
+        const service = { serviceName: "main" } as unknown as Service;
+        const createService = vi.fn()
+            .mockRejectedValueOnce(new Error("offline"))
+            .mockResolvedValueOnce(service);
+        const host = document.createElement("application-host");
+        host.createService = createService;
+        host.renderElement = () => html``;
+
+        await expect(host.connectedCallback()).rejects.toThrow("offline");
+        await host.connectedCallback();
+
+        expect(createService).toHaveBeenCalledTimes(2);
+        expect(host.service).toBe(service);
+    });
+});

package/src/elements/application-host.ts

@@ -3,13 +3,12 @@
 import { LitElement, nothing, TemplateResult, css } from 'lit';
 import { customElement, property } from 'lit/decorators.js';
 import { Service } from '@adobe/data/service';
-import { ApplicationElement } from './application-element.js';
 
 const tagName = "application-host";
 
 declare global {
    interface HTMLElementTagNameMap {
-      'application-element': ApplicationElement<Service>;
+      'application-host': ApplicationHost;
    }
 }
 
@@ -31,9 +30,23 @@ export class ApplicationHost<MainService extends Service = Service> extends LitE
    @property({ attribute: false })
    public service!: MainService;
 
+   #pendingService?: Promise<MainService>;
+
+   /**
+    * Creates the service once per host: reconnecting, including a DOM move, reuses the
+    * service or the in-flight creation. A failed creation is retried on the next connect.
+    */
    override async connectedCallback() {
       super.connectedCallback();
-      this.service = await this.createService();
+      if (this.service) return;
+      const pending = this.#pendingService ??= this.createService();
+      try {
+         const service = await pending;
+         this.service ??= service;
+      } catch (error) {
+         if (this.#pendingService === pending) this.#pendingService = undefined;
+         throw error;
+      }
    }
 
    override render() {

package/src/elements/database-element.test.ts

@@ -0,0 +1,111 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+// @vitest-environment happy-dom
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { html } from "lit";
+import { Database } from "@adobe/data/ecs";
+import { DatabaseElement } from "./database-element.js";
+
+const rootPlugin = Database.Plugin.create({ resources: { name: { default: "root" as string } } });
+const childPlugin = Database.Plugin.create({ resources: { count: { default: 0 as number } } });
+
+class ProbeElement extends DatabaseElement<typeof childPlugin> {
+    get plugin() {
+        return childPlugin;
+    }
+    fullDatabase() {
+        return this.database;
+    }
+    override render() {
+        return html`${this.database.resources.count}`;
+    }
+}
+customElements.define("database-element-probe", ProbeElement);
+
+class UnrenderedElement extends DatabaseElement<typeof childPlugin> {
+    get plugin() {
+        return childPlugin;
+    }
+}
+customElements.define("database-element-unrendered", UnrenderedElement);
+
+const create = () => document.createElement("database-element-probe") as ProbeElement;
+const resources = (db: unknown) => (db as { resources: Record<string, unknown> }).resources;
+
+afterEach(async () => {
+    document.body.replaceChildren();
+    await Promise.resolve();
+});
+
+describe("DatabaseElement", () => {
+    it("creates its own database when no ancestor provides one", async () => {
+        const element = create();
+        document.body.append(element);
+        expect(Database.is(element.fullDatabase())).toBe(true);
+        expect(resources(element.service).count).toBe(0);
+        await element.updateComplete;
+        expect(element.shadowRoot?.textContent).toBe("0");
+    });
+
+    it("extends the nearest ancestor database with its plugin", () => {
+        const root = Database.create(rootPlugin);
+        const parent = Object.assign(document.createElement("div"), { service: root });
+        document.body.append(parent);
+        const element = create();
+        parent.append(element);
+        expect(resources(element.service).name).toBe("root");
+        expect(resources(element.service).count).toBe(0);
+    });
+
+    it("finds the database of an ancestor database element", () => {
+        const outer = create();
+        document.body.append(outer);
+        const inner = create();
+        outer.append(inner);
+        expect(inner.fullDatabase()).toBe(outer.fullDatabase());
+    });
+
+    it("skips ancestor services that are not databases", () => {
+        const parent = Object.assign(document.createElement("div"), { service: { serviceName: "other" } });
+        document.body.append(parent);
+        const element = create();
+        parent.append(element);
+        expect(Database.is(element.fullDatabase())).toBe(true);
+    });
+
+    it("keeps an injected database and requests an update when it changes", () => {
+        const injected = Database.create(childPlugin);
+        const element = create();
+        const requestUpdate = vi.spyOn(element, "requestUpdate");
+        element.service = injected;
+        expect(requestUpdate).toHaveBeenCalledWith("service", undefined);
+        document.body.append(element);
+        expect(element.fullDatabase()).toBe(injected);
+    });
+
+    it("routes a database bound before the element upgraded through the service setter", () => {
+        const injected = Database.create(childPlugin);
+        const element = document.createElement("database-element-late");
+        (element as unknown as { service: unknown }).service = injected;
+        document.body.append(element);
+
+        class LateElement extends ProbeElement {}
+        customElements.define("database-element-late", LateElement);
+        const upgraded = element as unknown as LateElement;
+        expect(Object.prototype.hasOwnProperty.call(upgraded, "service")).toBe(false);
+        expect(upgraded.fullDatabase()).toBe(injected);
+    });
+
+    it("keeps its database across a reconnect", () => {
+        const element = create();
+        document.body.append(element);
+        const database = element.fullDatabase();
+        element.remove();
+        document.body.append(element);
+        expect(element.fullDatabase()).toBe(database);
+    });
+
+    it("throws from the default render", () => {
+        const element = new UnrenderedElement();
+        expect(() => element.render()).toThrow("render function must be overridden");
+    });
+});

package/src/functions/iterate-self-and-ancestors.test.ts

@@ -0,0 +1,29 @@
+// @vitest-environment happy-dom
+import { describe, expect, it } from "vitest";
+import { iterateSelfAndAncestors } from "./iterate-self-and-ancestors.js";
+
+const tags = (element: Element) => [...iterateSelfAndAncestors(element)].map(e => e.tagName.toLowerCase());
+
+describe("iterateSelfAndAncestors", () => {
+    it("walks light-DOM parents", () => {
+        const section = document.createElement("section");
+        const span = section.appendChild(document.createElement("div")).appendChild(document.createElement("span"));
+        expect(tags(span)).toEqual(["span", "div", "section"]);
+    });
+
+    it("crosses from a shadow root to its host", () => {
+        const host = document.createElement("section");
+        const inner = host.attachShadow({ mode: "open" }).appendChild(document.createElement("article"));
+        expect(tags(inner)).toEqual(["article", "section"]);
+    });
+
+    it("follows an assigned slot through the shadow tree before the light parent", () => {
+        const host = document.createElement("section");
+        const article = host.attachShadow({ mode: "open" }).appendChild(document.createElement("article"));
+        const slot = article.appendChild(document.createElement("slot"));
+        const span = host.appendChild(document.createElement("span"));
+        Object.defineProperty(span, "assignedSlot", { value: slot });
+
+        expect(tags(span)).toEqual(["span", "slot", "article", "section"]);
+    });
+});

package/src/functions/iterate-self-and-ancestors.ts

@@ -1,13 +1,13 @@
 // © 2026 Adobe. MIT License. See /LICENSE for details.
 
+/** Yields `element` and its ancestors along the composed tree: assigned slots, parents, then shadow hosts. */
 export function* iterateSelfAndAncestors(element: Element): IterableIterator<Element> {
     let current: Element | null = element;
 
     while (current) {
         yield current;
 
-        if (current instanceof HTMLSlotElement && current.assignedSlot) {
-            // Move to the slot's parent if the current element is assigned to a slot
+        if (current.assignedSlot) {
             current = current.assignedSlot;
         } else if (current.parentNode instanceof Element) {
             // Move up to the parent node if it is an element

package/src/hooks/attach-decorator.test.ts

@@ -0,0 +1,45 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, expect, it, vi } from "vitest";
+import { attachDecorator } from "./attach-decorator.js";
+
+const double = (_target: unknown, _key: string, descriptor: PropertyDescriptor) => {
+    const original = descriptor.value as (this: unknown, ...args: unknown[]) => number;
+    return { ...descriptor, value(this: unknown, ...args: unknown[]) { return original.apply(this, args) * 2; } };
+};
+
+describe("attachDecorator", () => {
+    it("decorates an inherited method and installs it on the instance", () => {
+        class Base { value = 3; get() { return this.value; } }
+        const instance = new Base();
+        attachDecorator(instance, "get", double);
+        expect(instance.get()).toBe(6);
+        expect(Object.prototype.hasOwnProperty.call(instance, "get")).toBe(true);
+        expect(new Base().get()).toBe(3);
+    });
+
+    it("decorates an own method", () => {
+        const instance = { get: () => 2 };
+        attachDecorator(instance, "get", double);
+        expect(instance.get()).toBe(4);
+    });
+
+    it("passes the instance, property name, and current method to the decorator", () => {
+        const method = () => 1;
+        const instance = { method };
+        const decorator = vi.fn((_target: unknown, _key: string, descriptor: PropertyDescriptor) => descriptor);
+        attachDecorator(instance, "method", decorator);
+        expect(decorator).toHaveBeenCalledWith(instance, "method", expect.objectContaining({ value: method }));
+    });
+
+    it("applies repeated decorators in order", () => {
+        const instance = { get: () => 1 };
+        attachDecorator(instance, "get", double);
+        attachDecorator(instance, "get", double);
+        expect(instance.get()).toBe(4);
+    });
+
+    it("throws for a missing property", () => {
+        const instance = {} as { missing?: () => void };
+        expect(() => attachDecorator(instance, "missing", double)).toThrow("Property missing does not exist");
+    });
+});

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();
+    });
+});