@adobe/data-lit 0.9.11

package/src/decorators/require-service.ts

@@ -0,0 +1,20 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+export function requireService() {
+    return function (
+        target: any,
+        propertyKey: string,
+        descriptor: PropertyDescriptor
+    ) {
+        const originalRender = descriptor.value;
+
+        descriptor.value = function (this: any) {
+            if (!this.service) {
+                return null;
+            }
+            return originalRender.call(this);
+        };
+
+        return descriptor;
+    };
+} 

package/src/elements/application-element.ts

@@ -0,0 +1,42 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { LitElement } from 'lit';
+import { property } from 'lit/decorators.js';
+import { attachDecorator, withHooks } from '../hooks/index.js';
+import { iterateSelfAndAncestors } from '../functions/index.js';
+import { Service, isService } from '@adobe/data/service';
+
+export class ApplicationElement<MainService extends Service> extends LitElement {
+  @property({ type: Object, reflect: false })
+  service!: MainService;
+
+  constructor() {
+    super();
+    attachDecorator(this, 'render', withHooks);
+  }
+
+  connectedCallback(): void {
+    super.connectedCallback();
+
+    if (!this.service) {
+      const service = this.findAncestorService();
+      if (service) {
+        this.service = service;
+      }
+    }
+  }
+
+  protected findAncestorService(): MainService | void {
+    for (const element of iterateSelfAndAncestors(this)) {
+      const { service } = element as Partial<ApplicationElement<MainService>>;
+      if (isService(service)) {
+        return service;
+      }
+    }
+  }
+
+  public override render() {
+    throw new Error('render function must be overridden');
+  }
+
+}

package/src/elements/application-host.ts

@@ -0,0 +1,43 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+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>;
+   }
+}
+
+@customElement(tagName)
+export class ApplicationHost<MainService extends Service = Service> extends LitElement {
+   static styles = css`
+        :host {
+            display: flex;
+            flex: 1 1 auto;
+        }
+    `;
+
+   @property()
+   createService!: () => Promise<MainService>;
+
+   @property({})
+   renderElement!: () => TemplateResult;
+
+   @property({ attribute: false })
+   public service!: MainService;
+
+   override async connectedCallback() {
+      super.connectedCallback();
+      this.service = await this.createService();
+   }
+
+   override render() {
+      return this.service ? this.renderElement() : nothing;
+   }
+
+}

package/src/elements/database-element.ts

@@ -0,0 +1,42 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { LitElement } from 'lit';
+import { property } from 'lit/decorators.js';
+import { iterateSelfAndAncestors } from '../functions/index.js';
+import { Database } from '@adobe/data/ecs';
+import { attachDecorator, withHooks } from '../index.js';
+
+export abstract class DatabaseElement<P extends Database.Plugin> extends LitElement {
+
+  @property({ type: Object, reflect: false })
+  service!: Database.Plugin.ToDatabase<P>;
+
+  constructor() {
+    super();
+    attachDecorator(this, 'render', withHooks);
+  }
+
+  abstract get plugin(): P;
+
+  connectedCallback(): void {
+    if (!this.service) {
+      const service = this.findAncestorDatabase();
+      this.service = (service?.extend(this.plugin) ?? Database.create(this.plugin)) as unknown as Database.Plugin.ToDatabase<P>;
+    }
+    super.connectedCallback();
+  }
+
+  protected findAncestorDatabase(): Database | void {
+    for (const element of iterateSelfAndAncestors(this)) {
+      const { service } = element as Partial<DatabaseElement<any>>;
+      if (Database.is(service)) {
+        return service;
+      }
+    }
+  }
+
+  public override render() {
+    throw new Error('render function must be overridden');
+  }
+
+}

package/src/elements/index.ts

@@ -0,0 +1,5 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+export * from "./application-host.js";
+export * from "./application-element.js";
+export * from "./database-element.js";

package/src/functions/index.ts

@@ -0,0 +1,3 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+export * from "./iterate-self-and-ancestors.js";

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

@@ -0,0 +1,23 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+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
+            current = current.assignedSlot;
+        } else if (current.parentNode instanceof Element) {
+            // Move up to the parent node if it is an element
+            current = current.parentNode;
+        } else if ((current.getRootNode() as ShadowRoot).host) {
+            // Move to the host element if we're at a shadow root
+            current = (current.getRootNode() as ShadowRoot).host;
+        } else {
+            // If no more ancestors, stop the iteration
+            current = null;
+        }
+    }
+}

package/src/hooks/attach-decorator.ts

@@ -0,0 +1,32 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+/**
+ * Attacheds a decorator to a method on an object and reassigns the resulting value back to the object.
+ */
+export function attachDecorator<T, K extends keyof T>(
+    obj: T,
+    property: K,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- This is a generic type
+    decorator: (target: any, propertyKey: string, descriptor: TypedPropertyDescriptor<T[K]>) => PropertyDescriptor
+): void {
+    // Get the descriptor of the property
+    let descriptor = Object.getOwnPropertyDescriptor(obj, property);
+
+    if (!descriptor) {
+        if (!obj[property]) {
+            throw new Error(`Property ${property.toString()} does not exist on object`);
+        }
+        descriptor = {
+            value: obj[property],
+            writable: true,
+            enumerable: true,
+            configurable: true,
+        };
+    }
+
+    // Apply the decorator to the descriptor
+    const decoratedDescriptor = decorator(obj, String(property), descriptor);
+
+    // Reassign the decorated method back to the object
+    obj[property] = decoratedDescriptor.value;
+}

package/src/hooks/component/component.ts

@@ -0,0 +1,12 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+export interface Component extends EventTarget {
+    /**
+     * Is this component active and connected to the containing dom?
+     */
+    readonly isConnected: boolean;
+    hookIndex: number
+    hooks: any[]
+    updatedListeners: Set<() => void>
+    requestUpdate(): void
+}

package/src/hooks/component/stack.ts

@@ -0,0 +1,19 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import type { Component } from "./component.js";
+
+const activeComponentStack: Component[] = [];
+export const Component_stack = {
+    active(): Component {
+        return activeComponentStack[activeComponentStack.length - 1]!;
+    },
+    push(component: Component) {
+        component.hookIndex = 0;
+        component.hooks ??= [];
+        activeComponentStack.push(component)
+    },
+    pop() {
+        activeComponentStack.pop()
+    }
+} as const;
+

package/src/hooks/index.ts

@@ -0,0 +1,21 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+export * from "./component/component.js";
+export * from "./component/stack.js";
+export * from "./use-state.js";
+export * from "./use-effect.js";
+export * from "./use-connected.js";
+export * from "./use-memo.js";
+export * from "./use-ref.js";
+export * from "./use-observable-values.js";
+export * from "./use-observable.js";
+export * from "./use-window-event.js";
+export * from "./use-resize-observer.js";
+export * from "./use-debounce.js";
+export * from "./use-element.js";
+export * from "./with-hooks.js";
+export * from "./attach-decorator.js";
+export * from "./use-drag-transaction.js";
+export * from "./use-drag-observe.js";
+export * from "./use-draggable.js";
+export * from "./use-updated.js";

package/src/hooks/use-connected.ts

@@ -0,0 +1,41 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import type { EffectCallback } from "./use-effect.js";
+import { useEffect } from "./use-effect.js";
+import { Component_stack } from "./component/stack.js";
+
+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;
+        }
+    }
+
+    //  TODO
+    if (component.isConnected) {
+        onConnect();
+    }
+
+    useEffect(() => {
+        component.addEventListener("connected", onConnect);
+        component.addEventListener("disconnected", onDisconnect);
+
+        return () => {
+            component.removeEventListener("connected", onConnect);
+            component.removeEventListener("disconnected", onDisconnect);
+
+            onDisconnect();
+        }
+
+    }, dependencies);
+}

package/src/hooks/use-debounce.ts

@@ -0,0 +1,26 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { useEffect } from "./use-effect.js";
+import { useState } from "./use-state.js";
+
+/**
+ * Hook to debounce a value. Returns the debounced value after the specified delay.
+ * 
+ * @param value - The value to debounce
+ * @param delay - Delay in milliseconds before updating the debounced value
+ * @returns The debounced value
+ */
+export function useDebounce<T>(value: T, delay: number): T {
+    const [debouncedValue, setDebouncedValue] = useState(value);
+
+    useEffect(() => {
+        const timeoutId = window.setTimeout(() => {
+            setDebouncedValue(value);
+        }, delay);
+
+        return () => clearTimeout(timeoutId);
+    }, [value, delay]);
+
+    return debouncedValue;
+}
+

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

@@ -0,0 +1,59 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { DraggableProps, useDraggable } from './use-draggable.js';
+import { useElement } from './use-element.js';
+import { Observe } from '@adobe/data/observe';
+import { Vec2 } from '@adobe/data/math';
+
+export type DragObserveProps = Pick<
+    DraggableProps,
+    'minDragDistance' | 'dragCursor' | 'addPlaceholder' | 'stopPropagation'
+>;
+export type DragStart = {
+    readonly type: 'start' | 'cancel';
+};
+export type DragMove = {
+    readonly type: 'move';
+    readonly delta: Vec2;
+    readonly position: Vec2;
+};
+export type DragEnd = {
+    readonly type: 'end';
+    readonly delta: Vec2;
+    readonly position: Vec2;
+};
+export type DragState = DragStart | DragMove | DragEnd;
+
+/**
+ * This hook creates a drag observe function that can be used to observe the drag state of an element.
+ * This is normally not used directly, but rather through the `useDragTransaction` hook.
+ * @param props
+ * @returns
+ */
+export function useDragObserve(props: DragObserveProps, dependencies: unknown[]) {
+    const [dragState, setDragState] = Observe.createEvent<DragState>();
+    const element = useElement();
+    useDraggable(element,
+        {
+            ...props,
+            onDragStart: _e => {
+                setDragState({ type: 'start' });
+            },
+            onDrag: (_e, position, delta) => {
+                setDragState({
+                    type: 'move',
+                    position,
+                    delta,
+                });
+            },
+            onDragEnd: (_e, position, delta) => {
+                setDragState({ type: 'end', position, delta });
+            },
+            onDragCancel: () => {
+                setDragState({ type: 'cancel' });
+            },
+        },
+        dependencies
+    );
+    return dragState;
+}

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

@@ -0,0 +1,46 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { DragEnd, DragMove, DragObserveProps, 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';
+
+export type DragTransactionProps<T> = DragObserveProps & {
+    transaction: (asyncArgs: AsyncArgsProvider<T>) => void;
+    update: (drag: DragMove | DragEnd) => T | void;
+};
+
+export function useDragTransaction<T>(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 => {
+            if (value.type === 'start') {
+                startDragTransaction();
+            }
+        });
+    }, dependencies);
+}

package/src/hooks/use-draggable.ts

@@ -0,0 +1,112 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { Vec2 } from '@adobe/data/math';
+import { useEffect } from './use-effect.js';
+
+function toCssUnitString(value: number): string {
+    return `${value}px`;
+}
+
+export interface DraggableProps {
+    //  onDragStart should return the initial position of the element
+    onDragStart: (e: PointerEvent) => Vec2 | void;
+    onDrag: (e: PointerEvent, newPosition: Vec2, delta: Vec2) => void;
+    onDragEnd?: (e: PointerEvent, newPosition: Vec2, delta: Vec2) => void;
+    /**
+     * Called if this hook is destroyed before the drag is completed.
+     */
+    onDragCancel?: () => void;
+    minDragDistance?: number;
+    dragCursor?: string;
+    addPlaceholder?: boolean;
+    stopPropagation?: boolean;
+}
+
+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.
+        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 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 (dragStartOffset) {
+                notify(e, props.onDrag);
+            }
+            if (stopPropagation) e.stopPropagation();
+        }
+        function cleanup() {
+            // eslint-disable-next-line @typescript-eslint/no-use-before-define
+            window.removeEventListener('pointerup', onPointerUp);
+            window.removeEventListener('pointermove', onPointerMove);
+            if (dragCursor) {
+                element.style.cursor = originalCursor;
+            }
+            if (placeholder) {
+                placeholder.remove();
+                placeholder = null;
+            }
+        }
+        function onPointerUp(e: PointerEvent) {
+            cleanup();
+            if (dragStartOffset && props.onDragEnd) {
+                notify(e, props.onDragEnd);
+            }
+            if (stopPropagation) e.stopPropagation();
+            downPosition = null;
+            dragStartOffset = null;
+        }
+        function onPointerDown(e: PointerEvent) {
+            // Only start drag transaction for left mouse button clicks
+            if (e.button !== 0) return;
+
+            window.addEventListener('pointermove', onPointerMove);
+            window.addEventListener('pointerup', onPointerUp);
+            downPosition = [e.clientX, e.clientY];
+            if (stopPropagation) e.stopPropagation();
+        }
+
+        element?.addEventListener('pointerdown', onPointerDown);
+        return () => {
+            element?.removeEventListener('pointerdown', onPointerDown);
+            if (downPosition) {
+                cleanup();
+            }
+            if (dragStartOffset) {
+                props.onDragCancel?.();
+            }
+        };
+    }, [element, ...(dependencies ?? [])]);
+}

package/src/hooks/use-effect.ts

@@ -0,0 +1,19 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { equalsShallow } from "@adobe/data/equals-shallow";
+import type { Component } from "./component/component.js"
+import { Component_stack } from "./component/stack.js";
+
+export type EffectCallback = () => (void | (() => void))
+type EffectHookState = { dispose?: () => void, dependencies: unknown[] };
+
+export function useEffect<T extends Component>(callback: EffectCallback, dependencies: unknown[] = []) {
+    const component = Component_stack.active() as T;
+    const hookIndex = component.hookIndex++;
+    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 };
+    }
+}

package/src/hooks/use-element.ts

@@ -0,0 +1,83 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { Component_stack } from "./component/stack.js";
+import { useEffect } from "./use-effect.js";
+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.
+ */
+export function useElement<K extends keyof HTMLElementTagNameMap>(querySelector: K): HTMLElementTagNameMap[K] | 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);
+    
+    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
+                });
+            }
+        }
+        observer.observe(element.shadowRoot ?? element, {
+            childList: true,
+            subtree: true
+        });
+        
+        // Cleanup function
+        return () => {
+            observer.disconnect();
+        };
+    }, [querySelector]);
+    
+    return foundElement;
+}