@brandup/ui 1.0.44 → 2.0.2

package/README.md

@@ -12,65 +12,514 @@ npm i @brandup/ui@latest
 
 ## UIElement
 
-`UIElement` - wrapper для `HTMLElement`, который позволяет привязать к нему свою бизнес логику.
+`UIElement` is a wrapper for `HTMLElement` that lets you attach your own business logic to it.
 
-Возможности:
-- Обработка комманд вызванных внутри `HTMLElement`, который связан с `UIElement`.
-- Обработка событий элемента `HTMLElement`, который связан с `UIElement`.
+Features:
+- Handling of commands declared in the markup of the `HTMLElement` that is bound to the `UIElement`.
+- Subscribing to events through `EventEmitter`, which `UIElement` extends.
 
-```
-abstract class UIElement {
+```ts
+abstract class UIElement extends EventEmitter {
     abstract typeName: string;
     readonly element: HTMLElement | undefined;
 
-    protected setElement(elem: HTMLElement): void;
-
-    protected defineEvent(eventName: string, eventOptions?: EventInit): void;
-    protected raiseEvent(eventName: string, eventArgs?: any): boolean;
+    static hasElement(elem: HTMLElement): boolean;
 
-    addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
-    removeEventListener(type: string, listener?: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions): void;
-    dispatchEvent(event: Event): boolean;
+    protected setElement(elem: HTMLElement): void;
 
-    registerCommand(name: string, execute: CommandDelegate, canExecute?: CommandCanExecuteDelegate): void;
+    registerCommand(name: string, execute: CommandExecuteFunction, canExecute?: CommandCanExecuteFunction): this;
     hasCommand(name: string): boolean;
-    
-    protected _onRenderElement(_elem: HTMLElement);
-    protected _onCanExecCommand(_name: string, _elem: HTMLElement): boolean;
 
-	onDestroy(callback: VoidFunction | UIElement | Element);
+    protected _onRenderElement(elem: HTMLElement): void;
+    protected _onCanExecCommand(name: string, elem: HTMLElement): boolean;
+
+    effectScope(): EffectScope;
     destroy(): void;
+
+    toString(): string;
 }
 ```
 
-## UI commands
+`UIElement` is an abstract class. A subclass sets `typeName` and binds a DOM element via `setElement`. An element can be bound only once; binding again (or binding an element that already belongs to another instance) throws an exception.
+
+```ts
+import { UIElement } from "@brandup/ui";
+
+class MyWidget extends UIElement {
+    typeName = "MyWidget";
 
-Класс UIElement позволяет регистрировать обработчики комманд, которые определяются в разметке HTML элемента.
+    constructor(elem: HTMLElement) {
+        super();
+        this.setElement(elem);
+    }
 
+    protected _onRenderElement(elem: HTMLElement) {
+        // initialize the markup
+    }
+}
 ```
-<button data-command="send">Send</button>
 
-this.registerCommand("send", (context: CommandContext) => { context.target.innerHTML = "ok"; });
+The `HTMLElement.prototype.ui` extension lets you bind a `UIElement` through a factory and returns the element itself. It is opt-in (not installed on import) — call `enableElementExtensions()` once before using it:
+
+```ts
+import { enableElementExtensions } from "@brandup/ui";
+
+enableElementExtensions();
+document.getElementById("widget")!.ui(elem => new MyWidget(elem));
 ```
 
-Так же можно регистрировать асинхронные обработчики комманд:
+The bound `UIElement` is available on the node through the `node.uielement` property.
+
+### Element bound at construction
 
+On the base `UIElement`, `element` is `HTMLElement | undefined` because the element may be bound later (an `Application`, for example, binds its element on run). When a component always receives its element in the constructor, extend `UIElementBound` instead — it binds the element immediately, so `element` is typed `HTMLElement` (never `undefined`):
+
+```ts
+import { UIElementBound } from "@brandup/ui";
+
+class MyWidget extends UIElementBound {
+    constructor(elem: HTMLElement) {
+        super("MyWidget", elem); // typeName + element
+    }
+}
+
+const w = new MyWidget(document.createElement("div"));
+w.element.focus(); // element: HTMLElement — no ?./!
 ```
+
+## UI commands
+
+`UIElement` lets you register command handlers, which are declared in the markup through the `data-command` attribute.
+
+```html
+<button data-command="send">Send</button>
+```
+
+```ts
+this.registerCommand("send", (context: CommandContext) => {
+    context.target.innerHTML = "ok";
+});
+```
+
+You can register asynchronous command handlers — just return a `Promise`:
+
+```ts
 this.registerCommand("command1-async", (context: CommandContext) => {
-	return Promise<void>(resolve => {
-		context.target.innerHTML = "Loading...";
-		const t = window.setTimeout(() => {
-			context.target.innerHTML = "Ok";
-			resolve();
-		}, 2000);
-	});
+    return new Promise<void>(resolve => {
+        context.target.innerHTML = "Loading...";
+        window.setTimeout(() => {
+            context.target.innerHTML = "Ok";
+            resolve();
+        }, 2000);
+    });
 });
 ```
 
-Команды срабатывают по событию `click`.
+The third argument, `canExecute`, lets you restrict execution of the command:
+
+```ts
+this.registerCommand(
+    "submit",
+    (context) => { /* ... */ },
+    (context) => context.target.dataset.enabled === "true"
+);
+```
+
+Commands are triggered by the `click` event. The handler is looked up by walking up the DOM from the element with the `data-command` attribute to the nearest `UIElement` in which that command is registered. The global click listener must be enabled once via `initUICommands()` — `Application` does this automatically (see [Command click handler](#command-click-handler)).
+
+While an asynchronous command is running, the **executing** CSS class is added to the target element (and removed once the `Promise` settles).
 
-Во время выполнения команды, у элемента добавляется стиль **executing**.
+Command type signatures:
+
+```ts
+type CommandExecuteFunction = (context: CommandContext) => void | Promise<void | any>;
+type CommandCanExecuteFunction = (context: CommandContext) => boolean;
+
+interface CommandContext {
+    /** HTMLElement on which the command is executed. */
+    target: HTMLElement;
+    /** UIElement in which the command handler is registered. */
+    uiElem: UIElement;
+    /** Don't stop the click event chain of target. */
+    transparent?: boolean;
+}
+
+interface CommandResult {
+    status: CommandExecStatus; // "disallow" | "already" | "success"
+    context: CommandContext;
+}
+```
+
+Before executing a command, `UIElement` triggers the `command` event with `CommandEventArgs` arguments (`{ element, name }`).
 
 ## UI Events
 
-`UIElement` extends class of `EveentEmmiter`.
+`UIElement` extends the `EventEmitter` class.
+
+```ts
+class EventEmitter<TEvents = EventMap> {
+    on<K extends keyof TEvents & string>(eventName: K, callback: TEvents[K], context?: any): this;
+    once<K extends keyof TEvents & string>(eventName: K, callback: TEvents[K], context?: any): this;
+    off<K extends keyof TEvents & string>(eventName?: K | "all" | null, callback?: TEvents[K] | EventCallbackFunc | null, context?: any | null): this;
+
+    protected listenTo(source: EventEmitter<any>, eventName: string, callback: EventCallbackFunc): this;
+    protected listenToOnce(source: EventEmitter<any>, eventName: string, callback: EventCallbackFunc): this;
+    protected stopListening(source?: EventEmitter<any>, eventName?: string, callback?: EventCallbackFunc): this;
+
+    protected trigger<K extends keyof TEvents & string>(eventName: K, ...args: Parameters<TEvents[K]>): this;
+}
+```
+
+### Typed events
+
+The optional `TEvents` type parameter is an **event map** (`{ eventName: (args) => void }`) that gives a subclass strongly-typed event names, callback signatures and `trigger` arguments. It defaults to a loose map, so untyped usage keeps working.
+
+```ts
+interface CounterEvents {
+    increment: (by: number) => void;
+    reset: () => void;
+}
+
+class Counter extends EventEmitter<CounterEvents> {
+    add(n: number) {
+        this.trigger("increment", n);   // ✅ ok
+        // this.trigger("increment", "x"); // ❌ string is not number
+        // this.trigger("nope");           // ❌ unknown event
+    }
+}
+
+const c = new Counter();
+c.on("increment", by => console.log(by.toFixed(0))); // by: number
+// c.on("unknown", () => {});                          // ❌ unknown event
+```
+
+`UIElement` is itself generic — `UIElement<TEvents>` merges `TEvents` with the built-in `command`/`rendered`/`destroy` events, so subclasses can add their own typed events:
+
+```ts
+class MyWidget extends UIElement<{ ready: () => void }> {
+    // on/trigger accept "command", "destroy" AND "ready"
+}
+```
+
+Subscribing to and unsubscribing from events:
+
+```ts
+widget.on("command", (args: CommandEventArgs) => {
+    console.log("executing", args.name);
+});
+
+// one-time handler
+widget.once("destroy", () => console.log("destroyed"));
+
+// unsubscribe (filters can be omitted — an omitted filter matches anything)
+widget.off("command");
+```
+
+The special event name `"all"` receives every triggered event.
+
+The protected `listenTo` / `listenToOnce` methods subscribe one emitter to another's events and track the subscription so it can be released via `stopListening`. On `destroy()`, all of a `UIElement`'s subscriptions are removed automatically.
+
+## UIElement lifecycle
+
+### destroy()
+
+`destroy()` cleans up the element completely:
+
+- Fires the `"destroy"` event.
+- Stops all event subscriptions.
+- **Cascades** to every nested `UIElement` found in the subtree (deepest descendants first), so you never need to destroy children manually.
+- Stops all reactive `bind`/`bindEach` effects rendered inside the element.
+- Detaches the `UIElement` from its DOM node (clears the `data-uiElement` attribute and the `uielement` property).
+
+```ts
+const parent = new ParentWidget(parentElem); // contains child UIElements
+parent.destroy(); // automatically destroys all nested UIElements too
+```
+
+### Auto-destroy on DOM removal
+
+When a bound element is removed from the document **after having been connected to it**, `destroy()` is called automatically. This works for all nested UIElements too — removing a parent node triggers the full destroy cascade.
+
+```ts
+const w = new MyWidget(elem);
+document.body.appendChild(elem);
+
+elem.remove(); // destroy() fires automatically on next microtask
+```
+
+If the element was never connected to the document (e.g. built in memory and then discarded), auto-destroy does **not** fire — only mounted-then-removed elements are watched.
+
+### Command click handler
+
+Commands are dispatched by a single global `click` listener on `window`. It is **not** registered automatically on import (so the command system can be tree-shaken away when unused) — call `initUICommands()` once during startup. It is idempotent and a no-op without a DOM. `Application.run()` (from `@brandup/ui-app`) calls it for you, so you only need it when using `UIElement` commands **without** an `Application`:
+
+```ts
+import { initUICommands, destroyUI } from "@brandup/ui";
+
+initUICommands(); // enable command handling
+// ...
+destroyUI();      // remove the listener on app teardown or HMR disposal
+```
+
+## DOM helpers
+
+> Previously published as the separate `@brandup/ui-dom` package, now merged into `@brandup/ui`.
+
+All DOM helpers are available through the `DOM` object.
+
+```ts
+import { DOM } from "@brandup/ui";
+
+const DOM = {
+    // Finding elements
+    getById<T extends HTMLElement = HTMLElement>(id: string): T | null;
+    getByClass<T extends HTMLElement = HTMLElement>(container: Element, className: string): T | null;
+    getByName<T extends HTMLElement = HTMLElement>(name: string): T | null;
+    getElementByTagName<T extends HTMLElement = HTMLElement>(container: Element, tagName: string): T | null;
+    getElementsByTagName(container: Element, tagName: string): HTMLCollectionOf<Element>;
+    queryElement<T extends HTMLElement = HTMLElement>(container: Element, query: string): T | null;
+    queryElements<T extends HTMLElement = HTMLElement>(container: Element, query: string): NodeListOf<T>;
+
+    // Navigating sibling elements
+    nextElement<T extends HTMLElement = HTMLElement>(current: Element): T | null;
+    prevElement<T extends HTMLElement = HTMLElement>(current: Element): T | null;
+    nextElementByClass<T extends HTMLElement = HTMLElement>(current: Element, className: string): T | null;
+    prevElementByClass<T extends HTMLElement = HTMLElement>(current: Element, className: string): T | null;
+
+    // CSS classes
+    addClass(container: Element | null | undefined, selectors: string, cssClass: CssClass): void;
+    removeClass(container: Element | null | undefined, selectors: string, cssClass: CssClass): void;
+
+    // Clearing
+    empty(container: Element | null | undefined): void;
+
+    // Creating elements
+    tag<T extends keyof HTMLElementTagNameMap>(tagName: T, options?: ElementOptions | null, ...children: TagChildrenLike[]): HTMLElementTagNameMap[T];
+    tag<T extends keyof HTMLElementTagNameMap>(tagName: T, firstChild: TagFirstChild, ...children: TagChildrenLike[]): HTMLElementTagNameMap[T];
+};
+```
+
+### Creating HTML elements
+
+`DOM.tag` creates an element from a tag name. The remaining arguments are children or options:
+
+- **Options** — pass `null` (no options) or an `ElementOptions` plain object as the second argument.
+- **Children** — any other value in the second position (string, number, `Element`, `Binding`, `BindingEach`, `Promise`, function, array) is treated as the **first child**, so the options argument can be omitted entirely.
+
+```ts
+// No options, no children
+DOM.tag("div");
+
+// Options object (id, class, dataset, styles, events, arbitrary attributes)
+DOM.tag("div", { class: "box", id: "main" });
+
+// null → no options, children follow
+DOM.tag("div", null, "<p>test</p>");
+
+// String as second arg → inserted as HTML child (NOT a CSS class)
+DOM.tag("div", "<b>hello</b>");
+DOM.tag("p", "plain text");
+
+// Number or boolean as second arg → text child
+DOM.tag("span", 42);
+
+// Element/UIElement child — no null needed
+DOM.tag("div", DOM.tag("span", "child"));
+DOM.tag("div", new MyWidget(DOM.tag("span")));
+
+// Multiple children
+DOM.tag("ul", null, DOM.tag("li", "1"), DOM.tag("li", "2"));
+
+// Children in an array
+DOM.tag("ul", [DOM.tag("li", "1"), DOM.tag("li", "2")]);
+
+// Factory function: receives the container element
+DOM.tag("div", (elem) => { elem.id = "x"; });
+DOM.tag("div", () => DOM.tag("span", "child"));
+
+// Promise child — appended once it resolves
+DOM.tag("div", fetch("/fragment").then(r => r.text()));
+```
+
+The full `ElementOptions` object:
+
+```ts
+interface ElementOptions {
+    id?: string;                  // id attribute
+    class?: CssClass;             // CSS class(es): a string or an array of strings
+    command?: string;             // data-command
+    dataset?: ElementData;        // arbitrary data-* attributes
+    events?: ElementEvents;       // event handlers keyed by lowercase name
+    styles?: ElementStyles;       // inline styles (Partial<CSSStyleDeclaration>)
+    [name: string]:               // any other key is a plain attribute:
+        | string | number | boolean | object | null | undefined;
+    // null → empty attribute, object → JSON.stringify, undefined → ignored
+}
+```
+
+## Reactivity
+
+A small fine-grained reactivity layer (Vue/MobX-style) with auto-tracking, plus `DOM.tag` bindings that update the DOM in place.
+
+```ts
+import { reactive, effect, computed, nextTick, untrack, bind, bindEach, DOM } from "@brandup/ui";
+```
+
+### reactive / effect / computed
+
+`reactive(obj)` returns a deep reactive proxy: reads are tracked and writes notify the effects that read them.
+
+```ts
+const state = reactive({ first: "Ada", last: "Lovelace", tags: ["math"] });
+
+// effect re-runs when any property it reads changes
+effect(() => console.log(state.first));
+
+// computed: lazily cached, recomputes only when its dependencies change
+const full = computed(() => `${state.first} ${state.last}`);
+
+state.first = "Augusta"; // schedules the effect and invalidates `full`
+```
+
+- **Deep**: nested objects and arrays are reactive (`state.tags.push(...)` is tracked).
+- **Dynamic dependencies**: an effect only depends on the properties it actually reads on its last run (`useA ? a : b` re-subscribes).
+- **Batched**: effect re-runs are coalesced on the microtask queue, so multiple synchronous writes trigger a single run. Await `nextTick()` to observe the result:
+
+```ts
+state.first = "A";
+state.last = "B";
+await nextTick(); // effects have now re-run once
+```
+
+### untrack
+
+`untrack(fn)` runs a function **without** recording any reactive reads as dependencies. Use it when you need to read reactive state inside an effect without creating a dependency on that read:
+
+```ts
+import { untrack } from "@brandup/ui";
+
+effect(() => {
+    const items = state.list;          // tracked — effect re-runs when list changes
+    const config = untrack(() => state.config); // not tracked — config changes won't re-run this effect
+    render(items, config);
+});
+```
+
+### Binding DOM with `bind`
+
+`bind(() => expr)` is a reactive `tag` child. The expression is tracked and re-rendered in place when its reactive state changes — text values reuse a text node (rendered via `textContent`, so safe from HTML injection), element/`UIElement` values swap the node.
+
+```ts
+const state = reactive({ name: "Alice", online: true });
+
+const el = DOM.tag("div", null,
+    "Hi, ", bind(() => state.name), "! ",
+    bind(() => state.online ? DOM.tag("b", null, "online") : "offline")
+);
+
+state.name = "Bob"; // the text updates on the next tick
+```
+
+### Binding an array property with `bindEach`
+
+`bindEach` is a reactive tag child — used exactly like `bind` — that renders a keyed list with minimal DOM updates. Each item is identified by a stable key; when the array changes, only new, removed, or reordered nodes are touched.
+
+```ts
+import { reactive, bindEach, bind, nextTick, DOM } from "@brandup/ui";
+
+const state = reactive({
+    users: [
+        { id: 1, name: "Alice" },
+        { id: 2, name: "Bob" },
+        { id: 3, name: "Charlie" },
+    ]
+});
+
+const list = DOM.tag("ul", "user-list",
+    bindEach(
+        () => state.users,          // reactive item source (tracked)
+        user => user.id,            // stable key — identifies each node across re-renders
+        user => DOM.tag("li", null, // render one item → Element (called once per key)
+            bind(() => user.name)   // bind() inside render for fine-grained per-item updates
+        )
+    )
+);
+```
+
+Array mutations are tracked — the list reconciles on the next tick:
+
+```ts
+state.users.push({ id: 4, name: "Diana" }); // inserts one new <li>
+state.users.splice(1, 1);                   // removes the <li> for id=2
+state.users.unshift(state.users.pop()!);    // moves last node to front, no re-render
+state.users = [{ id: 1, name: "Alice" }];   // full reassignment — removes all but id=1
+
+await nextTick(); // DOM is up to date
+```
+
+Because `render` is called **once per key** and runs **untracked**, reads inside it do not create dependencies on the list reconciler. Use `bind()` inside `render` so individual property changes update only the affected node — not the whole list:
+
+```ts
+// ✅  only the text node re-renders when user.name changes
+user => DOM.tag("li", null, bind(() => user.name))
+
+// ⚠️  name changes have no effect — render is untracked and never called again for existing keys
+user => DOM.tag("li", null, user.name)
+```
+
+The binding stops automatically once its rendered nodes leave the document — whether the container is removed or just cleared/replaced (same lifecycle as `bind`).
+
+### Disposal
+
+Bindings hold a reactive effect that must be stopped to avoid leaks. This is handled automatically in common cases:
+
+- **`UIElement.destroy()`** stops every `bind`/`bindEach` effect in the subtree and cascades to nested UIElements — no manual wiring needed.
+- A binding **stops itself** once its node has been mounted into the document and then removed from it.
+- Removing a bound element from the document also calls `destroy()` automatically (see [UIElement lifecycle](#uielement-lifecycle)).
+
+```ts
+class Widget extends UIElementBound {
+    constructor(elem: HTMLElement) {
+        super("widget", elem);
+        elem.append(DOM.tag("span", null, bind(() => state.name)));
+    }
+}
+const w = new Widget(document.createElement("div"));
+w.destroy(); // stops bind() effects, cascades to nested UIElements
+```
+
+For effects and bindings outside a `UIElement`, or to group them explicitly, use `EffectScope`:
+
+```ts
+import { effectScope } from "@brandup/ui";
+
+const scope = effectScope();
+const view = scope.run(() => DOM.tag("div", null, bind(() => state.name)));
+scope.stop(); // stops every effect/binding created inside the scope
+```
+
+`UIElement.effectScope()` returns a scope that is stopped automatically when the element is destroyed:
+
+```ts
+class Widget extends UIElementBound {
+    constructor(elem: HTMLElement) {
+        super("widget", elem);
+        this.effectScope().run(() => {
+            elem.append(DOM.tag("span", null, bind(() => state.name)));
+        });
+    }
+}
+```
+
+## Constants
+
+The names of DOM attributes, properties, and CSS classes are exported as the `UICONSTANTS` namespace:
+
+```ts
+import { UICONSTANTS } from "@brandup/ui";
+
+UICONSTANTS.ElemAttributeName;              // "uiElement"   — data attribute holding the typeName
+UICONSTANTS.ElemPropertyName;               // "uielement"   — property on the DOM element referencing the UIElement
+UICONSTANTS.CommandAttributeName;           // "command"     — data attribute of the command
+UICONSTANTS.CommandExecutingCssClassName;   // "executing"   — class applied while an async command is running
+```

package/dist/cjs/constants.js

@@ -0,0 +1,14 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+/** Default constant values used across the library. */
+const constants = {
+    ElemAttributeName: "uiElement",
+    ElemPropertyName: "uielement",
+    CommandAttributeName: "command",
+    CommandExecutingCssClassName: "executing"
+};
+
+exports.default = constants;
+//# sourceMappingURL=constants.js.map

package/dist/cjs/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sources":["../../../source/constants.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;AAYA;AACA,MAAM,SAAS,GAAgB;AAC9B,IAAA,iBAAiB,EAAE,WAAW;AAC9B,IAAA,gBAAgB,EAAE,WAAW;AAC7B,IAAA,oBAAoB,EAAE,SAAS;AAC/B,IAAA,4BAA4B,EAAE;;;;;"}

package/dist/cjs/dom/bind-each.js

@@ -0,0 +1,90 @@
+'use strict';
+
+var effect = require('../reactive/effect.js');
+var bindingCleanup = require('./binding-cleanup.js');
+
+/** A keyed-list binding produced by {@link bindEach}; handled by `appendChild` in `tag.ts`. */
+class BindingEach {
+    getItems;
+    getKey;
+    render;
+    constructor(getItems, getKey, render) {
+        this.getItems = getItems;
+        this.getKey = getKey;
+        this.render = render;
+    }
+}
+/**
+ * Create a reactive keyed-list binding for use as a {@link tag} child.
+ *
+ * The `getItems` function is tracked; the list is reconciled whenever the array
+ * changes (push, splice, reassignment, etc.). Items are matched by `getKey` so
+ * unchanged nodes stay in place — only new, removed, or reordered nodes are touched.
+ *
+ * `render` is called **once per key** and runs **untracked**. Use `bind()` inside
+ * the render function for item properties that should update independently:
+ *
+ * ⚠️ The item object passed to `render` is captured at first render for that key.
+ * Mutate items in place (`item.name = "..."`) so `bind()` reactions fire. Replacing
+ * the array with **new objects that reuse the same keys** keeps the cached node bound
+ * to the *old* object, so per-item `bind()`s won't update — change the key, or mutate
+ * the existing item, when its identity should change.
+ *
+ * @example
+ * DOM.tag("ul", null,
+ *     bindEach(() => state.users, u => u.id, u =>
+ *         DOM.tag("li", null, bind(() => u.name))
+ *     )
+ * );
+ */
+function bindEach(getItems, getKey, render) {
+    return new BindingEach(getItems, getKey, render);
+}
+/**
+ * Mount a {@link BindingEach} into `container` and start tracking.
+ * Called by `appendChild` in `tag.ts`; not intended for direct use.
+ * @internal
+ */
+function appendBindingEach(container, binding) {
+    const nodes = new Map();
+    // Anchor comment marks the start of the managed region inside the container.
+    // Using an anchor (rather than container.firstChild) lets other children coexist.
+    const anchor = document.createComment("");
+    container.append(anchor);
+    const eff = effect.effect(() => {
+        const items = binding.getItems();
+        const nextKeys = new Set();
+        for (let i = 0; i < items.length; i++)
+            nextKeys.add(binding.getKey(items[i], i));
+        // Remove nodes whose keys are no longer present
+        for (const [key, node] of nodes) {
+            if (!nextKeys.has(key)) {
+                node.remove();
+                nodes.delete(key);
+            }
+        }
+        // Insert new nodes and restore order in a single pass starting after the anchor.
+        // If the node is already at the expected position we advance; otherwise insertBefore moves it.
+        let cursor = anchor.nextSibling;
+        for (let i = 0; i < items.length; i++) {
+            const key = binding.getKey(items[i], i);
+            let node = nodes.get(key);
+            if (!node) {
+                // Render untracked so item-property reads don't create dependencies on
+                // this list effect — use bind() inside render for fine-grained updates.
+                node = effect.untrack(() => binding.render(items[i]));
+                nodes.set(key, node);
+            }
+            if (cursor !== node)
+                container.insertBefore(node, cursor);
+            else
+                cursor = cursor.nextSibling;
+        }
+    });
+    bindingCleanup.autoDisposeBinding(container, () => anchor, eff);
+}
+
+exports.BindingEach = BindingEach;
+exports.appendBindingEach = appendBindingEach;
+exports.bindEach = bindEach;
+//# sourceMappingURL=bind-each.js.map

package/dist/cjs/dom/bind-each.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bind-each.js","sources":["../../../../source/dom/bind-each.ts"],"sourcesContent":[null],"names":["effect","untrack","autoDisposeBinding"],"mappings":";;;;;AAGA;MACa,WAAW,CAAA;AAEb,IAAA,QAAA;AACA,IAAA,MAAA;AACA,IAAA,MAAA;AAHV,IAAA,WAAA,CACU,QAAmB,EACnB,MAAmD,EACnD,MAA4B,EAAA;QAF5B,IAAA,CAAA,QAAQ,GAAR,QAAQ;QACR,IAAA,CAAA,MAAM,GAAN,MAAM;QACN,IAAA,CAAA,MAAM,GAAN,MAAM;IACZ;AACJ;AAED;;;;;;;;;;;;;;;;;;;;;;AAsBG;SACa,QAAQ,CACvB,QAAmB,EACnB,MAAmD,EACnD,MAA4B,EAAA;IAE5B,OAAO,IAAI,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC;AACjD;AAEA;;;;AAIG;AACG,SAAU,iBAAiB,CAAI,SAAsB,EAAE,OAAuB,EAAA;AACnF,IAAA,MAAM,KAAK,GAAG,IAAI,GAAG,EAA4B;;;IAIjD,MAAM,MAAM,GAAG,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC;AACzC,IAAA,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC;AAExB,IAAA,MAAM,GAAG,GAAGA,aAAM,CAAC,MAAK;AACvB,QAAA,MAAM,KAAK,GAAG,OAAO,CAAC,QAAQ,EAAE;AAEhC,QAAA,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAmB;AAC3C,QAAA,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE;AACpC,YAAA,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;;QAG1C,KAAK,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,KAAK,EAAE;YAChC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE;gBACvB,IAAI,CAAC,MAAM,EAAE;AACb,gBAAA,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC;YAClB;QACD;;;AAIA,QAAA,IAAI,MAAM,GAAqB,MAAM,CAAC,WAAW;AACjD,QAAA,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE;AACtC,YAAA,MAAM,GAAG,GAAG,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;YACvC,IAAI,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC;YAEzB,IAAI,CAAC,IAAI,EAAE;;;AAGV,gBAAA,IAAI,GAAGC,cAAO,CAAC,MAAM,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AAC9C,gBAAA,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC;YACrB;YAEA,IAAI,MAAM,KAAK,IAAI;AAClB,gBAAA,SAAS,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC;;AAEpC,gBAAA,MAAM,GAAG,MAAM,CAAC,WAAW;QAC7B;AACD,IAAA,CAAC,CAAC;IAEFC,iCAAkB,CAAC,SAAS,EAAE,MAAM,MAAM,EAAE,GAAG,CAAC;AACjD;;;;;;"}