@adobe/data 0.9.37 → 0.9.40

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

package/references/data-lit/src/hooks/use-memo.ts

@@ -0,0 +1,16 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { useEffect } from "./use-effect.js";
+import { useState } from "./use-state.js";
+
+export function useMemo<T>(calculateValue: () => T, dependencies: unknown[] = []): T {
+    const [state, setState] = useState<T | undefined>(undefined);
+    let currentValue = state;
+
+    useEffect(() => {
+        currentValue = calculateValue();
+        setState(currentValue);
+    }, dependencies);
+
+    return currentValue!;
+}

package/references/data-lit/src/hooks/use-observable-values.ts

@@ -0,0 +1,10 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { Observe } from "@adobe/data/observe";
+import { useMemo } from "./use-memo.js";
+import { useObservable } from "./use-observable.js";
+
+export function useObservableValues<T extends Record<string, Observe<unknown>>>(factory: () => T, deps: unknown[] = []): { [K in keyof T]: T[K] extends Observe<infer U> ? U : never } | undefined {
+    const observable = useMemo(() => Observe.fromProperties(factory()), deps);
+    return useObservable(observable);
+}

package/references/data-lit/src/hooks/use-observable.ts

@@ -0,0 +1,15 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { useState } from "./use-state.js";
+import { useEffect } from "./use-effect.js";
+import { Observe } from "@adobe/data/observe";
+
+export function useObservable<T>(observable: Observe<T>): T | undefined {
+    let [value, setValue] = useState<T | undefined>(undefined);
+    useEffect(() => {
+        return observable(newValue => {
+            setValue(value = newValue);
+        });
+    }, [observable]);
+    return value;
+}

package/references/data-lit/src/hooks/use-ref.ts

@@ -0,0 +1,8 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { useState } from "./use-state.js";
+
+export function useRef<T>(initialValue: T): { current: T } {
+    const [state] = useState({ current: initialValue });
+    return state;
+}

package/references/data-lit/src/hooks/use-resize-observer.ts

@@ -0,0 +1,31 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { useEffect } from "./use-effect.js";
+import { useElement } from "./use-element.js";
+
+export interface ResizeInfo {
+    width: number;
+    height: number;
+    entry: ResizeObserverEntry;
+}
+
+/**
+ * Hook to observe element resizes. Calls callback with width, height, and the original entry
+ * when the element's size changes.
+ * 
+ * @param onResize - Callback invoked when element size changes
+ */
+export function useResizeObserver(onResize: (info: ResizeInfo) => void) {
+    const element = useElement();
+
+    useEffect(() => {
+        const observer = new ResizeObserver(entries => {
+            for (const entry of entries) {
+                const { width, height } = entry.contentRect;
+                onResize({ width, height, entry });
+            }
+        });
+        observer.observe(element);
+        return () => observer.disconnect();
+    }, [element, onResize]);
+} 

package/references/data-lit/src/hooks/use-state.ts

@@ -0,0 +1,19 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { Component_stack } from "./component/stack.js";
+
+export function useState<T>(initializer: () => T): [T, (value: T) => void]
+export function useState<T>(initialValue: T): [T, (value: T) => void]
+export function useState<T>(initial: () => T) {
+    const component = Component_stack.active();
+    const hookIndex = component.hookIndex++;
+    const value = component.hooks[hookIndex] ??= (typeof initial === "function" ? initial() : initial);
+    return [
+        value,
+        (newValue: T) => {
+            component.hooks[hookIndex] = newValue;
+            component.requestUpdate();
+        }
+    ];
+
+}

package/references/data-lit/src/hooks/use-updated.ts

@@ -0,0 +1,56 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { useElement } from "./use-element.js";
+import { useEffect } from "./use-effect.js";
+
+export interface UpdateEventHost {
+    updateListeners: Set<() => void>;
+}
+
+function hasUpdateListeners(el: unknown): el is UpdateEventHost {
+    return (
+        typeof el === 'object' &&
+        el !== null &&
+        'updateListeners' in el &&
+        el['updateListeners'] instanceof Set
+    );
+}
+
+function makeUpdateEventHost<T extends Element>(
+    el: T
+): T & UpdateEventHost {
+    if (hasUpdateListeners(el)) return el as T & UpdateEventHost;
+
+    const updateListeners = new Set<() => void>();
+    Object.defineProperty(el, 'updateListeners', {
+        value: updateListeners,
+        writable: false,
+        enumerable: false,
+    });
+
+    if (!('updated' in el)) {
+        throw new Error('Element does not have an updated method');
+    }
+
+    const element = el as unknown as T & {
+        updated: (changedProps: Map<PropertyKey, unknown>) => void;
+    } & UpdateEventHost;
+    const orig = element.updated.bind(el);
+
+    element.updated = (changedProps) => {
+        orig(changedProps);
+        for (const fn of updateListeners) fn();
+    };
+
+    return element;
+}
+
+
+export function useUpdated(listener: () => void, dependencies: unknown[] = []) {
+    const element = makeUpdateEventHost(useElement());
+    useEffect(() => {
+        element.updateListeners.add(listener);
+        return () => {
+            element.updateListeners.delete(listener);
+        }
+    }, dependencies);
+}

package/references/data-lit/src/hooks/use-window-event.ts

@@ -0,0 +1,16 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { useEffect } from "./use-effect.js";
+import { useMemo } from "./use-memo.js";
+
+export function useWindowEvent<K extends keyof WindowEventMap>(
+    event: K,
+    callbackFactory: () => (e: WindowEventMap[K]) => void,
+    deps: any[] = []
+) {
+    const callback = useMemo(callbackFactory, deps);
+    useEffect(() => {
+        window.addEventListener(event, callback);
+        return () => window.removeEventListener(event, callback);
+    }, [callback]);
+}

package/references/data-lit/src/hooks/with-hooks.ts

@@ -0,0 +1,22 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import type { Component } from "./component/component.js";
+import { Component_stack } from "./component/stack.js";
+
+export function withHooks<This extends Component, Args extends any[], Return>(
+    target: object,
+    propertyKey: string,
+    descriptor: TypedPropertyDescriptor<(this: This, ...args: Args) => Return>
+): TypedPropertyDescriptor<(this: This, ...args: Args) => Return> {
+    const originalMethod = descriptor.value!;
+    descriptor.value = function (this: This, ...args: Args): Return {
+        Component_stack.push(this);
+        try {
+            return originalMethod.apply(this, args);
+        }
+        finally {
+            Component_stack.pop();
+        }
+    }
+    return descriptor;
+}

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

@@ -0,0 +1,6 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+export * from "./hooks/index.js";
+export * from "./elements/index.js";
+export * from "./decorators/index.js";
+export type { Vec2 } from "@adobe/data/math";

package/references/data-lit/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../data/tsconfig-base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist",
+    "composite": true,
+    "types": []
+  },
+  "include": ["src/**/*"],
+  "references": []
+}

package/references/data-lit-tictactoe/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "data-lit-tictactoe",
+  "version": "0.9.40",
+  "description": "Tic-Tac-Toe sample - Lit web components with @adobe/data-lit and AgenticService",
+  "type": "module",
+  "private": true,
+  "scripts": {
+    "build": "vite build",
+    "dev": "vite",
+    "publish-public": "true"
+  },
+  "dependencies": {
+    "@adobe/data": "workspace:*",
+    "@adobe/data-lit": "workspace:*",
+    "lit": "^3.3.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.3",
+    "vite": "^5.1.1",
+    "vite-plugin-checker": "^0.12.0"
+  }
+}

package/references/data-lit-tictactoe/src/elements/tictactoe-app/tictactoe-app.css.ts

@@ -0,0 +1,11 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { css } from "lit";
+
+export const styles = css`
+  :host {
+    display: flex;
+    flex-direction: column;
+    gap: 1rem;
+  }
+`;

package/references/data-lit-tictactoe/src/elements/tictactoe-app/tictactoe-app.ts

@@ -0,0 +1,22 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { customElement } from "lit/decorators.js";
+import { html } from "lit";
+import { TictactoeElement } from "../../tictactoe-element.js";
+import { styles } from "./tictactoe-app.css.js";
+import "../tictactoe-board/tictactoe-board.js";
+import "../tictactoe-hud/tictactoe-hud.js";
+
+export const tagName = "tictactoe-app";
+
+@customElement(tagName)
+export class TictactoeApp extends TictactoeElement {
+  static styles = styles;
+
+  render() {
+    return html`
+      <tictactoe-board></tictactoe-board>
+      <tictactoe-hud></tictactoe-hud>
+    `;
+  }
+}

package/references/data-lit-tictactoe/src/elements/tictactoe-board/tictactoe-board-presentation.ts

@@ -0,0 +1,13 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { html } from "lit";
+
+export function render() {
+  return html`
+    <div class="board">
+      ${[0, 1, 2, 3, 4, 5, 6, 7, 8].map(
+        (index) => html`<tictactoe-cell .index=${index}></tictactoe-cell>`,
+      )}
+    </div>
+  `;
+}

package/references/data-lit-tictactoe/src/elements/tictactoe-board/tictactoe-board.css.ts

@@ -0,0 +1,17 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { css } from "lit";
+
+export const styles = css`
+  :host {
+    display: block;
+  }
+
+  .board {
+    display: grid;
+    grid-template-columns: repeat(3, 100px);
+    grid-template-rows: repeat(3, 100px);
+    gap: 4px;
+    width: fit-content;
+  }
+`;

package/references/data-lit-tictactoe/src/elements/tictactoe-board/tictactoe-board.ts

@@ -0,0 +1,18 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { customElement } from "lit/decorators.js";
+import { TictactoeElement } from "../../tictactoe-element.js";
+import { styles } from "./tictactoe-board.css.js";
+import * as presentation from "./tictactoe-board-presentation.js";
+import "../tictactoe-cell/tictactoe-cell.js";
+
+export const tagName = "tictactoe-board";
+
+@customElement(tagName)
+export class TictactoeBoard extends TictactoeElement {
+  static styles = styles;
+
+  render() {
+    return presentation.render();
+  }
+}

package/references/data-lit-tictactoe/src/elements/tictactoe-cell/tictactoe-cell-presentation.ts

@@ -0,0 +1,22 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { html } from "lit";
+
+export function render(args: {
+  cell: string;
+  isWinning: boolean;
+  isPlayable: boolean;
+  playMove: () => void;
+}) {
+  const { cell, isWinning, isPlayable, playMove } = args;
+  const hasMark = cell === "X" || cell === "O";
+
+  return html`
+    <div
+      class="cell ${isWinning ? "winning" : ""} ${isPlayable ? "playable" : ""}"
+      @click=${() => isPlayable && playMove()}
+    >
+      ${hasMark ? cell : ""}
+    </div>
+  `;
+}

package/references/data-lit-tictactoe/src/elements/tictactoe-cell/tictactoe-cell.css.ts

@@ -0,0 +1,31 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { css } from "lit";
+
+export const styles = css`
+  :host {
+    display: block;
+  }
+
+  .cell {
+    width: 100px;
+    height: 100px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    font-size: 48px;
+    font-weight: bold;
+    background: #1f2937;
+    border: 2px solid #6b7280;
+    color: #e5e7eb;
+    box-sizing: border-box;
+  }
+
+  .cell.playable {
+    cursor: pointer;
+  }
+
+  .cell.winning {
+    background: #2e7d32;
+  }
+`;

package/references/data-lit-tictactoe/src/elements/tictactoe-cell/tictactoe-cell.ts

@@ -0,0 +1,41 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { customElement, property } from "lit/decorators.js";
+import { useObservableValues } from "@adobe/data-lit";
+import { BoardState } from "../../types/board-state/board-state.js";
+import { TictactoeElement } from "../../tictactoe-element.js";
+import { styles } from "./tictactoe-cell.css.js";
+import * as presentation from "./tictactoe-cell-presentation.js";
+
+export const tagName = "tictactoe-cell";
+
+@customElement(tagName)
+export class TictactoeCell extends TictactoeElement {
+  static styles = styles;
+
+  @property({ type: Number })
+  declare index: number;
+
+  render() {
+    const values = useObservableValues(
+      () => ({
+        board: this.service.observe.resources.board,
+      }),
+      [],
+    );
+
+    const board = values?.board ?? "         ";
+    const cell = BoardState.getCell(board, this.index);
+    const isWinning = BoardState.isCellWinning(board, this.index);
+    const isPlayable = BoardState.isCellPlayable(board, this.index);
+
+    return presentation.render({
+      cell,
+      isWinning,
+      isPlayable,
+      playMove: () => {
+        this.service.transactions.playMove({ index: this.index });
+      },
+    });
+  }
+}

package/references/data-lit-tictactoe/src/elements/tictactoe-hud/tictactoe-hud-presentation.ts

@@ -0,0 +1,16 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { html } from "lit";
+
+export function render(args: {
+  statusText: string;
+  restartGame: () => void;
+}) {
+  const { statusText, restartGame } = args;
+  return html`
+    <div class="hud">
+      <span>${statusText}</span>
+      <button type="button" @click=${restartGame}>Restart</button>
+    </div>
+  `;
+}