@adobe/data 0.9.37 → 0.9.39

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/data",
-  "version": "0.9.37",
+  "version": "0.9.39",
   "description": "Adobe data oriented programming library",
   "type": "module",
   "sideEffects": false,
@@ -12,6 +12,8 @@
   "files": [
     "dist",
     "README.md",
+    "AGENTS.md",
+    "references",
     "LICENSE"
   ],
   "devDependencies": {

package/references/data-lit/README.md

@@ -0,0 +1,18 @@
+# @adobe/data-lit
+
+Lit bindings for [@adobe/data](https://www.npmjs.com/package/@adobe/data) — hooks, elements, and decorators for building reactive UIs with the @adobe/data ECS database and observables.
+
+## Install
+
+```bash
+pnpm add @adobe/data @adobe/data-lit lit
+```
+
+## Usage
+
+```typescript
+import { ApplicationHost, DatabaseElement } from "@adobe/data-lit";
+import { createDatabase } from "@adobe/data/ecs";
+```
+
+See the `data-lit-todo` sample in this repository for a full example.

package/references/data-lit/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@adobe/data-lit",
+  "version": "0.9.39",
+  "description": "Adobe data Lit bindings - hooks, elements, decorators",
+  "type": "module",
+  "private": false,
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "scripts": {
+    "build": "cp ../../LICENSE . && tsc -b",
+    "dev": "tsc -b -w",
+    "link": "pnpm build && pnpm link --global",
+    "test": "vitest --run --passWithNoTests",
+    "publish-public": "pnpm build && pnpm publish --no-git-checks --access public"
+  },
+  "dependencies": {
+    "@adobe/data": "workspace:*"
+  },
+  "peerDependencies": {
+    "lit": "^3.3.1"
+  },
+  "devDependencies": {
+    "lit": "^3.3.1",
+    "typescript": "^5.8.3",
+    "vitest": "^1.6.0"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  }
+}

package/references/data-lit/src/decorators/apply-decorator.ts

@@ -0,0 +1,26 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+export function applyDecorator(
+    target: any,
+    propertyKey: string,
+    decorator: (target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor
+) {
+    // Get the prototype chain
+    let currentPrototype = target;
+    let descriptor: PropertyDescriptor | undefined;
+
+    // Walk up the prototype chain until we find the property
+    while (currentPrototype && !descriptor) {
+        descriptor = Object.getOwnPropertyDescriptor(currentPrototype, propertyKey);
+        if (!descriptor) {
+            currentPrototype = Object.getPrototypeOf(currentPrototype);
+        }
+    }
+
+    if (!descriptor) {
+        throw new Error(`Property ${propertyKey} not found in prototype chain`);
+    }
+
+    const newDescriptor = decorator(target, propertyKey, descriptor);
+    Object.defineProperty(target, propertyKey, newDescriptor);
+} 

package/references/data-lit/src/decorators/apply-service-decorators.ts

@@ -0,0 +1,15 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { withHooks } from "../hooks/with-hooks.js";
+import { requireService } from "./require-service.js";
+import { TemplateResult } from "lit";
+
+export function applyServiceDecorators(target: any) {
+    const prototype = Object.getPrototypeOf(target);
+    const originalRender = target.render ?? prototype.render;
+    const withService = requireService()(target, 'render', {
+        value: originalRender
+    });
+    const withHooksAndService = withHooks(target, 'render', withService);
+    target.render = withHooksAndService.value as () => TemplateResult | null;
+} 

package/references/data-lit/src/decorators/index.ts

@@ -0,0 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+export * from "./apply-decorator.js";
+export * from "./apply-service-decorators.js";
+export * from "./require-service.js";

package/references/data-lit/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/references/data-lit/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/references/data-lit/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/references/data-lit/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/references/data-lit/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/references/data-lit/src/functions/index.ts

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

package/references/data-lit/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/references/data-lit/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/references/data-lit/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/references/data-lit/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/references/data-lit/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/references/data-lit/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/references/data-lit/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/references/data-lit/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/references/data-lit/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);
+}