@tempots/dom 36.0.1 → 37.0.0

package/README.md

@@ -101,6 +101,26 @@ const button = html.button(
 )
 ```
 
+### Delegated Events
+
+For containers with many similar children (e.g., lists rendered with `ForEach`), use `delegate` to attach a single event listener on the container instead of one per child:
+
+```typescript
+import { html, delegate, ForEach, prop } from '@tempots/dom'
+
+const items = prop(['Apple', 'Banana', 'Cherry'])
+
+html.ul(
+  delegate.click('li', (event) => {
+    const li = (event.target as Element).closest('li')!
+    console.log('Clicked:', li.textContent)
+  }),
+  ForEach(items, (item) => html.li(item))
+)
+```
+
+`delegate` uses the same proxy pattern as `on` — all standard events are available. It matches children using `Element.closest()` with a CSS selector. Non-bubbling events (`focus`, `blur`, `mouseenter`, `mouseleave`) should use `on` instead.
+
 ### Conditional Rendering
 
 Render content conditionally:
@@ -131,6 +151,33 @@ const items = prop(['Apple', 'Banana', 'Cherry'])
 const list = html.ul(ForEach(items, item => html.li(item)))
 ```
 
+### Keyed Lists
+
+When list items have stable identities (e.g., database IDs), use `KeyedForEach` for efficient reconciliation. Unlike `ForEach` which tracks items by index, `KeyedForEach` tracks items by a user-provided key function — reusing both DOM nodes and signal identities across reorders:
+
+```typescript
+import { html, KeyedForEach, prop } from '@tempots/dom'
+
+const todos = prop([
+  { id: 1, text: 'Buy groceries' },
+  { id: 2, text: 'Walk the dog' },
+  { id: 3, text: 'Read a book' },
+])
+
+const list = html.ul(
+  KeyedForEach(
+    todos,
+    (todo) => todo.id,                    // key function
+    (todo, pos) => html.li(               // item renderer
+      todo.map((t) => t.text)
+    ),
+    () => html.hr()                       // optional separator
+  )
+)
+```
+
+When `todos` is reordered, `KeyedForEach` moves existing DOM elements instead of recreating them. Each item receives a `KeyedPosition` with fully reactive position fields (`index`, `counter`, `isFirst`, `isLast`, `isEven`, `isOdd`) that update automatically when items move.
+
 ### Storage-Backed Props
 
 Tempo provides helpers that persist reactive state to Web Storage through `storedProp`,

package/dom/browser-context.d.ts

@@ -1,4 +1,5 @@
 import { Clear, ProviderMark, Providers } from '../types/domain';
+import { Primitive } from '@tempots/core';
 import { DOMContext, HandlerOptions } from './dom-context';
 import { HeadlessContext } from './headless-context';
 /**
@@ -105,7 +106,7 @@ export declare class BrowserContext implements DOMContext {
      * @param namespace - The namespace URI to create the element in, or `undefined` to create a standard HTML element.
      * @returns The newly created element.
      */
-    readonly createElement: (tagName: string, namespace: string | undefined) => HTMLElement;
+    createElement(tagName: string, namespace: string | undefined): HTMLElement;
     /**
      * Creates a new child element and appends it to the current element, returning a new context.
      *
@@ -128,47 +129,52 @@ export declare class BrowserContext implements DOMContext {
      * @param namespace - The namespace URI for the element, or undefined for HTML elements
      * @returns A new DOMContext focused on the newly created child element
      */
-    readonly makeChildElement: (tagName: string, namespace: string | undefined) => DOMContext;
+    makeChildElement(tagName: string, namespace: string | undefined): DOMContext;
     /**
      * Creates a new text node with the specified text content.
      * @param text - The text content for the new text node.
      * @returns A new `Text` node with the specified text content.
      */
-    readonly createText: (text: string) => Text;
+    createText(text: Primitive): Text;
     /**
      * Creates a new text node with the specified text content and appends it to the current element.
-     * @param text - The text content for the new text node.
+     * @param text - The text content for the new text node. Primitives are coerced to strings by the DOM.
      * @returns A new `DOMContext` with a reference to the new text node.
      */
-    readonly makeChildText: (text: string) => DOMContext;
+    makeChildText(text: Primitive): DOMContext;
     /**
      * Sets the text content of the current element.
-     * @param text - The text content to set.
+     * @param text - The text content to set. Primitives are coerced to strings by the DOM.
      */
-    readonly setText: (text: string) => void;
+    setText(text: Primitive): void;
     /**
      * Gets the text content of the current element or text node.
      * @returns The text content of the current element or text node.
      */
-    readonly getText: () => string;
+    getText(): string;
     /**
-     * Creates a new `DOMContext` with a reference to a newly created text node.
-     * The text node is appended or inserted to the current `DOMContext`.
+     * Creates a new `DOMContext` with a reference to a newly created Comment node.
+     * The Comment node is appended or inserted to the current `DOMContext`.
      * The new `DOMContext` with the reference is returned.
      */
-    readonly makeRef: () => DOMContext;
+    makeRef(): DOMContext;
+    /**
+     * Creates a lightweight Comment marker node and appends/inserts it.
+     * Used as boundary references for keyed list items and conditional renderables.
+     */
+    makeMarker(): DOMContext;
     /**
      * Appends or inserts a child node to the element, depending on whether a reference node is provided.
      *
      * @param child - The child node to append or insert.
      */
-    readonly appendOrInsert: (child: Node) => void;
+    appendOrInsert(child: Node): void;
     /**
      * Creates a new `DOMContext` instance with the provided `element`.
      * @param element - The DOM element to use in the new `DOMContext` instance.
      * @returns A new `DOMContext` instance with the provided `element`.
      */
-    readonly withElement: (element: HTMLElement) => BrowserContext;
+    withElement(element: HTMLElement): BrowserContext;
     /**
      * Creates a portal to render content in a different part of the DOM tree.
      *
@@ -213,14 +219,14 @@ export declare class BrowserContext implements DOMContext {
      * @returns A new DOMContext focused on the portal target element
      * @throws {Error} When the selector doesn't match any element in the document
      */
-    readonly makePortal: (selector: string | HTMLElement) => DOMContext;
+    makePortal(selector: string | HTMLElement): DOMContext;
     /**
      * Creates a new `DOMContext` instance with the specified reference.
      *
-     * @param reference - The optional `Text` node to use as the reference for the new `DOMContext`.
+     * @param reference - The optional `Node` to use as the reference for the new `DOMContext`.
      * @returns A new `DOMContext` instance with the specified reference.
      */
-    readonly withReference: (reference: Text | undefined) => DOMContext;
+    withReference(reference: Node | undefined): DOMContext;
     /**
      * Sets a provider for the given provider mark.
      *
@@ -228,7 +234,7 @@ export declare class BrowserContext implements DOMContext {
      * @param value - The provider to set for the given mark.
      * @returns A new `DOMContext` instance with the specified provider.
      */
-    readonly setProvider: <T>(mark: ProviderMark<T>, value: T, onUse: undefined | (() => void)) => DOMContext;
+    setProvider<T>(mark: ProviderMark<T>, value: T, onUse: undefined | (() => void)): DOMContext;
     /**
      * Retrieves a provider for the given provider mark.
      *
@@ -236,26 +242,26 @@ export declare class BrowserContext implements DOMContext {
      * @returns The provider for the given mark.
      * @throws Throws `ProviderNotFoundError` if the provider for the given mark is not found.
      */
-    readonly getProvider: <T>(mark: ProviderMark<T>) => {
+    getProvider<T>(mark: ProviderMark<T>): {
         value: T;
         onUse: (() => void) | undefined;
     };
-    readonly clear: (removeTree: boolean) => void;
+    clear(removeTree: boolean): void;
     /**
      * Adds classes to the element.
      * @param tokens - The class names to add.
      */
-    readonly addClasses: (tokens: string[]) => void;
+    addClasses(tokens: string[]): void;
     /**
      * Removes classes from the element.
      * @param tokens - The class names to remove.
      */
-    readonly removeClasses: (tokens: string[]) => void;
+    removeClasses(tokens: string[]): void;
     /**
      * Gets the classes of the element.
      * @returns The classes of the element.
      */
-    readonly getClasses: () => string[];
+    getClasses(): string[];
     /**
      * Adds an event listener to the element.
      * @param event - The event to listen for.
@@ -263,43 +269,50 @@ export declare class BrowserContext implements DOMContext {
      * @param options - The options for the event listener.
      * @returns A function to remove the event listener.
      */
-    readonly on: <E>(event: string, listener: (event: E, ctx: BrowserContext) => void, options?: HandlerOptions) => Clear;
+    on<E>(event: string, listener: (event: E, ctx: BrowserContext) => void, options?: HandlerOptions): Clear;
     /**
      * Returns `true` if the context is a browser DOM context.
      * @returns `true` if the context is a browser DOM context.
      * @deprecated Use `isBrowser()` instead.
      */
-    readonly isBrowserDOM: () => this is BrowserContext;
+    isBrowserDOM(): this is BrowserContext;
     /**
      * Returns `true` if the context is a browser context.
      * @returns `true` if the context is a browser context.
      */
-    readonly isBrowser: () => this is BrowserContext;
+    isBrowser(): this is BrowserContext;
     /**
      * Returns `true` if the context is a headless DOM context.
      * @returns `true` if the context is a headless DOM context.
      */
-    readonly isHeadlessDOM: () => this is HeadlessContext;
+    isHeadlessDOM(): this is HeadlessContext;
     /**
      * Returns `true` if the context is a headless context.
      * @returns `true` if the context is a headless context.
      */
-    readonly isHeadless: () => this is HeadlessContext;
+    isHeadless(): this is HeadlessContext;
     /**
      * Sets the style of the element.
      * @param name - The name of the style to set.
      * @param value - The value of the style to set.
      */
-    readonly setStyle: (name: string, value: string) => void;
+    setStyle(name: string, value: string): void;
     /**
      * Gets the style of the element.
      * @param name - The name of the style to get.
      * @returns The value of the style.
      */
-    readonly getStyle: (name: string) => string;
-    readonly makeAccessors: (name: string) => {
+    getStyle(name: string): string;
+    makeAccessors(name: string): {
         get: () => any;
         set: (value: unknown) => void;
     };
-    readonly getWindow: () => Window & typeof globalThis;
+    getWindow(): Window & typeof globalThis;
+    moveRangeBefore(startRef: DOMContext, endRef: DOMContext, targetRef: DOMContext): void;
+    removeRange(startRef: DOMContext, endRef: DOMContext): void;
+    removeAllBefore(ref: DOMContext): void;
+    private _detachedParent;
+    private _detachedNext;
+    detach(): void;
+    reattach(): void;
 }

package/dom/dom-context.d.ts

@@ -1,5 +1,5 @@
 import { Clear, ProviderMark } from '../types/domain';
-import { makeProviderMark } from '@tempots/core';
+import { Primitive, makeProviderMark } from '@tempots/core';
 import { BrowserContext } from './browser-context';
 import { HeadlessContext } from './headless-context';
 export { makeProviderMark };
@@ -37,12 +37,12 @@ export interface DOMContext {
      * @param text - The text content for the new text node.
      * @returns A new `DOMContext` with a reference to the new text node.
      */
-    makeChildText(text: string): DOMContext;
+    makeChildText(text: Primitive): DOMContext;
     /**
      * Sets the text content of the current element.
      * @param text - The text content to set.
      */
-    setText(text: string): void;
+    setText(text: Primitive): void;
     /**
      * Gets the text content of the current element or text node.
      * @returns The text content of the current element or text node.
@@ -144,4 +144,38 @@ export interface DOMContext {
         get(): unknown;
         set(value: unknown): void;
     };
+    /**
+     * Moves a range of sibling nodes (from `startRef` to `endRef` inclusive)
+     * before `targetRef`. All three refs must be children of the same parent element.
+     *
+     * Used by `KeyedForEach` to reorder keyed items without recreating DOM nodes.
+     *
+     * @param startRef - The context whose reference marks the start of the range.
+     * @param endRef - The context whose reference marks the end of the range.
+     * @param targetRef - The context before which the range will be inserted.
+     */
+    moveRangeBefore(startRef: DOMContext, endRef: DOMContext, targetRef: DOMContext): void;
+    /**
+     * Removes all sibling nodes between `startRef` and `endRef` (inclusive).
+     * Used for bulk removal of keyed entries.
+     */
+    removeRange(startRef: DOMContext, endRef: DOMContext): void;
+    /**
+     * Creates a lightweight marker node (Comment node) as a boundary reference.
+     */
+    makeMarker(): DOMContext;
+    /**
+     * Removes all sibling nodes before the given reference marker in one
+     * operation. Used as a fast path for clearing entire lists.
+     */
+    removeAllBefore(ref: DOMContext): void;
+    /**
+     * Detaches the context's container element from the live DOM tree.
+     * Use before bulk insertions to avoid incremental layout recalculations.
+     */
+    detach(): void;
+    /**
+     * Re-attaches the container element after a detach.
+     */
+    reattach(): void;
 }

package/dom/headless-context.d.ts

@@ -1,4 +1,4 @@
-import { Prop } from '@tempots/core';
+import { Primitive, Prop } from '@tempots/core';
 import { ProviderMark, Clear, Providers } from '../types/domain';
 import { BrowserContext } from './browser-context';
 import { DOMContext, HandlerOptions } from './dom-context';
@@ -24,11 +24,11 @@ declare abstract class HeadlessBase {
     private readonly properties;
     readonly children: HeadlessNode[];
     constructor(parent: HeadlessBase | undefined);
-    readonly isElement: () => this is HeadlessBase;
-    readonly isText: () => this is HeadlessText;
-    readonly getText: () => string;
-    readonly removeChild: (child: HeadlessNode) => void;
-    readonly remove: () => void;
+    isElement(): this is HeadlessBase;
+    isText(): this is HeadlessText;
+    getText(): string;
+    removeChild(child: HeadlessNode): void;
+    remove(): void;
     abstract isPortal(): this is HeadlessPortal;
     /**
      * Generates HTML output as an async stream of string chunks.
@@ -39,32 +39,32 @@ declare abstract class HeadlessBase {
      * @yields String chunks of HTML content.
      */
     abstract toHTMLStream(options?: StreamOptions): AsyncGenerator<string>;
-    readonly getPortals: () => HeadlessPortal[];
-    readonly elements: () => HeadlessBase[];
+    getPortals(): HeadlessPortal[];
+    elements(): HeadlessBase[];
     abstract toHTML(): string;
-    readonly hasInnerHTML: () => boolean;
-    readonly getInnerHTML: () => string;
-    readonly getInnerText: () => string;
-    readonly hasInnerText: () => boolean;
-    readonly hasChildren: () => boolean;
-    readonly hasClasses: () => boolean;
-    readonly hasStyles: () => boolean;
-    readonly hasAttributes: () => boolean;
-    readonly hasHandlers: () => boolean;
-    readonly hasRenderableProperties: () => boolean;
-    readonly getById: (id: string) => HeadlessBase | undefined;
-    readonly trigger: <E>(event: string, detail: E) => void;
-    readonly click: () => void;
-    readonly on: <E>(event: string, listener: (event: E, ctx: HeadlessContext) => void, ctx: HeadlessContext, options?: HandlerOptions) => Clear;
-    readonly addClasses: (tokens: string[]) => void;
-    readonly removeClasses: (tokens: string[]) => void;
-    readonly getClasses: () => string[];
-    readonly getAttributes: () => [string, unknown][];
-    readonly getVisibleAttributes: () => (["class", string[]] | ["style", string | Record<string, string>] | [string, string])[];
-    readonly setStyle: (name: string, value: string) => void;
-    readonly getStyle: (name: string) => string;
-    readonly getStyles: () => Record<string, string>;
-    readonly makeAccessors: (name: string) => {
+    hasInnerHTML(): boolean;
+    getInnerHTML(): string;
+    getInnerText(): string;
+    hasInnerText(): boolean;
+    hasChildren(): boolean;
+    hasClasses(): boolean;
+    hasStyles(): boolean;
+    hasAttributes(): boolean;
+    hasHandlers(): boolean;
+    hasRenderableProperties(): boolean;
+    getById(id: string): HeadlessBase | undefined;
+    trigger<E>(event: string, detail: E): void;
+    click(): void;
+    on<E>(event: string, listener: (event: E, ctx: HeadlessContext) => void, ctx: HeadlessContext, options?: HandlerOptions): Clear;
+    addClasses(tokens: string[]): void;
+    removeClasses(tokens: string[]): void;
+    getClasses(): string[];
+    getAttributes(): [string, unknown][];
+    getVisibleAttributes(): (["class", string[]] | ["style", string | Record<string, string>] | [string, string])[];
+    setStyle(name: string, value: string): void;
+    getStyle(name: string): string;
+    getStyles(): Record<string, string>;
+    makeAccessors(name: string): {
         get(): unknown;
         set(value: unknown): void;
     };
@@ -73,13 +73,13 @@ export declare class HeadlessElement extends HeadlessBase {
     readonly tagName: string;
     readonly namespace: string | undefined;
     constructor(tagName: string, namespace: string | undefined, parent: HeadlessBase | undefined);
-    readonly isPortal: () => this is HeadlessPortal;
+    isPortal(): this is HeadlessPortal;
     /**
      * Builds the attributes string for this element.
      * Returns an object containing the attributes string and any innerHTML value.
      */
-    private readonly buildAttributesString;
-    readonly toHTML: (generatePlaceholders?: boolean) => string;
+    private buildAttributesString;
+    toHTML(generatePlaceholders?: boolean): string;
     /**
      * Generates HTML output as an async stream of string chunks.
      * Yields the opening tag, then each child's content, then the closing tag.
@@ -92,14 +92,14 @@ export declare class HeadlessElement extends HeadlessBase {
 export declare class HeadlessPortal extends HeadlessBase {
     readonly selector: string | HTMLElement;
     constructor(selector: string | HTMLElement, parent: HeadlessBase | undefined);
-    readonly isPortal: () => this is HeadlessPortal;
-    readonly toHTML: () => string;
+    isPortal(): this is HeadlessPortal;
+    toHTML(): string;
     /**
      * Portals don't render inline - they render at their target selector.
      * This method yields nothing for the inline position.
      */
     toHTMLStream(options?: StreamOptions): AsyncGenerator<string>;
-    readonly contentToHTML: (generatePlaceholders?: boolean) => string;
+    contentToHTML(generatePlaceholders?: boolean): string;
     /**
      * Streams the portal's content HTML.
      * Unlike toHTMLStream, this yields the actual content for rendering at the target location.
@@ -113,10 +113,10 @@ export declare class HeadlessText {
     text: string;
     readonly id: string;
     constructor(text: string);
-    readonly isElement: () => this is HeadlessElement;
-    readonly isText: () => this is HeadlessText;
-    readonly getText: () => string;
-    readonly toHTML: () => string;
+    isElement(): this is HeadlessElement;
+    isText(): this is HeadlessText;
+    getText(): string;
+    toHTML(): string;
     /**
      * Streams the text content as a single chunk.
      *
@@ -135,13 +135,14 @@ export declare class HeadlessContext implements DOMContext {
     readonly container: HeadlessContainer;
     readonly providers: Providers;
     constructor(element: HeadlessBase, reference: HeadlessNode | undefined, container: HeadlessContainer, providers: Providers);
-    readonly appendOrInsert: (element: HeadlessNode) => void;
-    readonly makeChildElement: (tagName: string, namespace: string | undefined) => DOMContext;
-    readonly makeChildText: (text: string) => DOMContext;
-    readonly setText: (text: string) => void;
-    readonly getText: () => string;
-    readonly makeRef: () => DOMContext;
-    readonly makePortal: (selector: string | HTMLElement) => DOMContext;
+    appendOrInsert(element: HeadlessNode): void;
+    makeChildElement(tagName: string, namespace: string | undefined): DOMContext;
+    makeChildText(text: Primitive): DOMContext;
+    setText(text: Primitive): void;
+    getText(): string;
+    makeRef(): DOMContext;
+    makeMarker(): DOMContext;
+    makePortal(selector: string | HTMLElement): DOMContext;
     /**
      * Sets a provider for the given provider mark.
      *
@@ -149,25 +150,30 @@ export declare class HeadlessContext implements DOMContext {
      * @param value - The provider to set for the given mark.
      * @returns A new `DOMContext` instance with the specified provider.
      */
-    readonly setProvider: <T>(mark: ProviderMark<T>, value: T, onUse: undefined | (() => void)) => DOMContext;
-    readonly getProvider: <T>(mark: ProviderMark<T>) => {
+    setProvider<T>(mark: ProviderMark<T>, value: T, onUse: undefined | (() => void)): DOMContext;
+    getProvider<T>(mark: ProviderMark<T>): {
         value: T;
         onUse: (() => void) | undefined;
     };
-    readonly clear: (removeTree: boolean) => void;
-    readonly on: <E>(event: string, listener: (event: E, ctx: HeadlessContext) => void) => Clear;
-    readonly addClasses: (tokens: string[]) => void;
-    readonly removeClasses: (tokens: string[]) => void;
-    readonly getClasses: () => string[];
-    readonly isBrowserDOM: () => this is BrowserContext;
-    readonly isBrowser: () => this is BrowserContext;
-    readonly isHeadlessDOM: () => this is HeadlessContext;
-    readonly isHeadless: () => this is HeadlessContext;
-    readonly setStyle: (name: string, value: string) => void;
-    readonly getStyle: (name: string) => string;
-    readonly makeAccessors: (name: string) => {
+    clear(removeTree: boolean): void;
+    on<E>(event: string, listener: (event: E, ctx: HeadlessContext) => void): Clear;
+    addClasses(tokens: string[]): void;
+    removeClasses(tokens: string[]): void;
+    getClasses(): string[];
+    isBrowserDOM(): this is BrowserContext;
+    isBrowser(): this is BrowserContext;
+    isHeadlessDOM(): this is HeadlessContext;
+    isHeadless(): this is HeadlessContext;
+    setStyle(name: string, value: string): void;
+    getStyle(name: string): string;
+    makeAccessors(name: string): {
         get(): unknown;
         set(value: unknown): void;
     };
+    moveRangeBefore(startRef: DOMContext, endRef: DOMContext, targetRef: DOMContext): void;
+    removeRange(startRef: DOMContext, endRef: DOMContext): void;
+    removeAllBefore(ref: DOMContext): void;
+    detach(): void;
+    reattach(): void;
 }
 export {};