@but212/atom-effect-jquery 0.31.0 → 0.32.1

package/dist/bindings/chainable.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=chainable.d.ts.map

package/dist/bindings/chainable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chainable.d.ts","sourceRoot":"","sources":["../../src/bindings/chainable.ts"],"names":[],"mappings":""}

package/dist/bindings/form.d.ts

@@ -0,0 +1,33 @@
+import { WritableAtom } from '@but212/atom-effect';
+import { FormOptions } from '../types';
+/**
+ * Establishes a two-way reactive binding between a `<form>` and an object atom.
+ *
+ * When to use:
+ * - Recommended for synchronizing standard HTML forms with complex, nested
+ *   reactive state objects.
+ * - Suitable for scenarios requiring declarative validation integrated with
+ *   browser-native APIs.
+ *
+ * @param form - The target form element to bind.
+ * @param atom - A writable atom or an array of atoms.
+ *               Logic: Polymorphic Input
+ *               If an array is provided, it is merged via `mergeLenses`.
+ *               Note: When merging, later atoms in the array override
+ *               properties with the same path from earlier atoms.
+ * @param options - Configuration for transformations and reactive validation.
+ *
+ * @example
+ * ```typescript
+ * const user = $.atom({ profile: { name: 'Alice' }, items: [] });
+ *
+ * $.bindForm($('form')[0], user, {
+ *   validation: {
+ *     'profile.name': (v) => v ? true : 'Name is required'
+ *   },
+ *   onChange: (path, val) => console.log(`${path} changed to ${val}`)
+ * });
+ * ```
+ */
+export declare function bindForm<T extends object>(form: HTMLFormElement, atom: WritableAtom<T> | WritableAtom<unknown>[], options?: FormOptions<unknown>): void;
+//# sourceMappingURL=form.d.ts.map

package/dist/bindings/form.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"form.d.ts","sourceRoot":"","sources":["../../src/bindings/form.ts"],"names":[],"mappings":"AAAA,OAAO,EASL,KAAK,YAAY,EAClB,MAAM,qBAAqB,CAAC;AAI7B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAmZ3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,MAAM,EACvC,IAAI,EAAE,eAAe,EACrB,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,YAAY,CAAC,OAAO,CAAC,EAAE,EAC/C,OAAO,GAAE,WAAW,CAAC,OAAO,CAAM,GACjC,IAAI,CAIN"}

package/dist/bindings/input-binding.d.ts

@@ -0,0 +1,31 @@
+import { EffectObject, ValOptions, WritableAtom } from '../types';
+/**
+ * Applies a two-way reactive binding to a form input element.
+ *
+ * This function handles text inputs, textareas, and select menus, ensuring
+ * stability during IME composition and maintaining cursor positions during
+ * background state updates.
+ *
+ * When to use:
+ * - To synchronize a form control with a `WritableAtom` state.
+ * - To implement debounced or custom-formatted input fields.
+ *
+ * @param $element - The jQuery collection containing the target form element.
+ * @param atom - The writable atom to synchronize with.
+ * @param options - Configuration for debouncing, event triggers, and data transformation.
+ * @returns A handle containing the reactive effect and a cleanup function.
+ *
+ * @example
+ * ```typescript
+ * const name = atom('John');
+ * const { cleanup } = applyInputBinding($('#name-input'), name, {
+ *   debounce: 200,
+ *   format: (v) => v.toUpperCase()
+ * });
+ * ```
+ */
+export declare function applyInputBinding<T>($element: JQuery, atom: WritableAtom<T>, options: ValOptions<T>): {
+    reactiveEffect: EffectObject;
+    cleanup: () => void;
+};
+//# sourceMappingURL=input-binding.d.ts.map

package/dist/bindings/input-binding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"input-binding.d.ts","sourceRoot":"","sources":["../../src/bindings/input-binding.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AA+QtE;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EACjC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC,EACrB,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC,GACrB;IAAE,cAAc,EAAE,YAAY,CAAC;IAAC,OAAO,EAAE,MAAM,IAAI,CAAA;CAAE,CAMvD"}

package/dist/bindings/list/context.d.ts

@@ -0,0 +1,82 @@
+import { EffectObject, ListKey } from '../../types';
+/**
+ * Represents the state of a single list item at a point in time.
+ * Used by the reconciler to calculate moves, updates, and removals.
+ */
+export interface ListSnapshot<T> {
+    key: ListKey;
+    item: T;
+    /** The actual DOM element or JQuery wrapper currently representing this item. */
+    node?: Element | JQuery | undefined;
+}
+/**
+ * Persistent state for the `$.fn.atomList` binding.
+ *
+ * WHY:
+ * Reactive lists require a stable reference to track historical DOM nodes across
+ * multiple rendering cycles. Using a POJO (Plain Old JavaScript Object) ensures
+ * state is decoupled from logic, following a functional "Relation Function" pattern.
+ *
+ * @internal
+ */
+export interface ListContext<T> {
+    /** Sequential snapshot of the previous render state. */
+    snapshots: ListSnapshot<T>[];
+    /** Keys currently undergoing asynchronous exit animations. */
+    readonly removingKeys: Set<ListKey>;
+    /** Cached reference to the placeholder element shown when the list is empty. */
+    $emptyEl: JQuery | null;
+    /** Inverse lookup for O(1) index retrieval from a key. */
+    keyToIndex: Map<ListKey, number>;
+    /** The reactive effect controlling this list. Needed to check disposal state during async tasks. */
+    fx?: EffectObject;
+    /** Target container element. */
+    readonly $container: JQuery;
+    /** Selector for the container. */
+    readonly containerSelector: string;
+    /** Optional removal lifecycle hook. */
+    readonly onRemove: (($el: JQuery) => Promise<void> | void) | undefined;
+}
+/**
+ * Factory to initialize a new ListContext.
+ */
+export declare function createListContext<T>($container: JQuery, containerSelector: string, onRemove: (($el: JQuery) => Promise<void> | void) | undefined): ListContext<T>;
+/**
+ * Retrieves the index of a key, handling string-to-number normalization.
+ *
+ * WHY: DOM `data-atom-key` attributes are always strings. If the original
+ * atom keys were numbers, a direct Map lookup will fail.
+ *
+ * @internal
+ */
+export declare function getListIndex<T>(ctx: ListContext<T>, key: ListKey | string): number | undefined;
+/**
+ * Marks a key as "in transit" and starts the removal lifecycle.
+ * @internal
+ */
+export declare function removeListItem<T>(ctx: ListContext<T>, k: ListKey, $el: JQuery): void;
+/**
+ * Initiates the physical removal of an element.
+ *
+ * PERFORMANCE: Allocation-free path for synchronous removals.
+ * Closures are only created if `onRemove` returns a Promise.
+ * @internal
+ */
+export declare function scheduleListItemRemoval<T>(ctx: ListContext<T>, k: ListKey, $el: JQuery): void;
+/**
+ * Finalizes DOM removal and state cleanup.
+ *
+ * GUARD: If an element is "resurrected" (reused for a new key) during the
+ * asynchronous removal delay, this method aborts to prevent accidental destruction.
+ * @internal
+ */
+export declare function commitListItemRemoval<T>(ctx: ListContext<T>, k: ListKey, $el: JQuery): void;
+/**
+ * Full cleanup of state and DOM references.
+ *
+ * GC: Reuses the `snapshots` array instance (length = 0) to reduce
+ * memory fragmentation on high-frequency list swaps.
+ * @internal
+ */
+export declare function disposeListContext<T>(ctx: ListContext<T>): void;
+//# sourceMappingURL=context.d.ts.map

package/dist/bindings/list/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../../src/bindings/list/context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAGrD;;;GAGG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,GAAG,EAAE,OAAO,CAAC;IACb,IAAI,EAAE,CAAC,CAAC;IACR,iFAAiF;IACjF,IAAI,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC;CACrC;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,wDAAwD;IACxD,SAAS,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC;IAC7B,8DAA8D;IAC9D,QAAQ,CAAC,YAAY,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;IACpC,gFAAgF;IAChF,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,0DAA0D;IAC1D,UAAU,EAAE,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IACjC,oGAAoG;IACpG,EAAE,CAAC,EAAE,YAAY,CAAC;IAClB,gCAAgC;IAChC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,kCAAkC;IAClC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,uCAAuC;IACvC,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,SAAS,CAAC;CACxE;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EACjC,UAAU,EAAE,MAAM,EAClB,iBAAiB,EAAE,MAAM,EACzB,QAAQ,EAAE,CAAC,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,SAAS,GAC5D,WAAW,CAAC,CAAC,CAAC,CAUhB;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,GAAG,EAAE,WAAW,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAW9F;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,GAAG,EAAE,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAIpF;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,GAAG,EAAE,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAS7F;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,GAAG,EAAE,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAY3F;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,GAAG,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,IAAI,CAM/D"}

package/dist/bindings/list/diff.d.ts

@@ -0,0 +1,24 @@
+import { ListKeyFn, ListOptions } from '../../types';
+import { ListContext } from './context';
+import { PreparedDiff } from './types';
+/**
+ * Generates a reconciliation plan between the previous and next state of a list.
+ *
+ * When to use:
+ * - Internal orchestration of DOM mutations for the `atomList` binding.
+ *
+ * Performance:
+ * - O(N) time complexity.
+ * - Best case: O(1) for pure appends/prepends via head/tail fast-forwarding.
+ *
+ * @param ctx - Persistent state containing historical DOM and keys.
+ * @param items - The new data array from the source atom.
+ *
+ * @example
+ * const diff = buildIndices(ctx, nextItems, nextItems.length, getKey, update, isEqual);
+ * // diff.slots now contains the mapping instructions for each index.
+ *
+ * @internal
+ */
+export declare function buildIndices<T>(ctx: ListContext<T>, items: T[], itemCount: number, getKey: ListKeyFn<T>, update: ListOptions<T>['update'], isEqual: ListOptions<T>['isEqual']): PreparedDiff<T>;
+//# sourceMappingURL=diff.d.ts.map

package/dist/bindings/list/diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff.d.ts","sourceRoot":"","sources":["../../../src/bindings/list/diff.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAW,SAAS,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAE/D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAA4B,KAAK,YAAY,EAAE,MAAM,SAAS,CAAC;AAEtE;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAC5B,GAAG,EAAE,WAAW,CAAC,CAAC,CAAC,EACnB,KAAK,EAAE,CAAC,EAAE,EACV,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,EACpB,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,EAChC,OAAO,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,GACjC,YAAY,CAAC,CAAC,CAAC,CAyHjB"}

package/dist/bindings/list/dom.d.ts

@@ -0,0 +1,50 @@
+import { ListOptions } from '../../types';
+import { ListContext } from './context';
+import { PlaceCallbacks, PreparedDiff } from './types';
+/**
+ * Inserts elements before a reference node with zero-allocation for jQuery collections.
+ *
+ * Why:
+ * - Directly iterates over JQuery objects to avoid `.get()` or `Array.from()` array allocations.
+ * - Handles polymorphic inputs (Element | JQuery) to keep the caller's logic simple.
+ */
+export declare function insertOrAppend(elOrJq: Element | JQuery | undefined, nextNode: Node | null, container: Element): void;
+/**
+ * Resets the container or renders an empty placeholder.
+ *
+ * Why:
+ * - Decouples destructive cleanup (`.empty()`) from animated cleanup (`removeItem`).
+ * - Ensures the historical context is cleared only after the DOM reflects the empty state.
+ */
+export declare function handleEmpty<T>(ctx: ListContext<T>, itemCount: number, $container: JQuery, empty: ListOptions<T>['empty']): void;
+/**
+ * Transforms items into DOM nodes or sanitized HTML strings.
+ *
+ * Performance:
+ * - Provides a "Cold Start" optimization: returns raw HTML strings for initial render
+ *   to allow direct `innerHTML` injection, bypassing jQuery construction overhead.
+ *
+ * Why:
+ * - String parsing is batched (`batchSanitize`) to reduce sanitization engine overhead.
+ */
+export declare function renderItems<T>(diff: PreparedDiff<T>, options: ListOptions<T>, isInitial: boolean): string[] | null;
+/**
+ * Triggers removal lifecycle for items missing in the new data set.
+ *
+ * When to use:
+ * - Called during the diffing phase before new items are placed.
+ */
+export declare function cleanupRemoved<T>(ctx: ListContext<T>): void;
+/**
+ * Positions items in the DOM and executes lifecycle callbacks.
+ *
+ * Logic:
+ * 1. Initial Render: Replaces entire innerHTML or appends via DocumentFragment.
+ * 2. Reconciliation: Moves existing nodes or inserts new ones based on the diff plan.
+ *
+ * Performance:
+ * - Uses a reverse loop for reconciliation to maintain DOM order with minimal moves.
+ * - Uses `switch` instead of a handler Map to avoid object allocation in the hot loop.
+ */
+export declare function placeItems<T>(ctx: ListContext<T>, diff: PreparedDiff<T>, container: Element, callbacks: PlaceCallbacks<T>, htmlFragments: string[] | null): void;
+//# sourceMappingURL=dom.d.ts.map

package/dist/bindings/list/dom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dom.d.ts","sourceRoot":"","sources":["../../../src/bindings/list/dom.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAG3C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAE7C,OAAO,EAAa,KAAK,cAAc,EAAE,KAAK,YAAY,EAAE,MAAM,SAAS,CAAC;AAG5E;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,EACpC,QAAQ,EAAE,IAAI,GAAG,IAAI,EACrB,SAAS,EAAE,OAAO,GACjB,IAAI,CAYN;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAC3B,GAAG,EAAE,WAAW,CAAC,CAAC,CAAC,EACnB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,GAC7B,IAAI,CA8BN;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAC3B,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC,EACrB,OAAO,EAAE,WAAW,CAAC,CAAC,CAAC,EACvB,SAAS,EAAE,OAAO,GACjB,MAAM,EAAE,GAAG,IAAI,CAuEjB;AAcD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,GAAG,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,IAAI,CAQ3D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAC1B,GAAG,EAAE,WAAW,CAAC,CAAC,CAAC,EACnB,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC,EACrB,SAAS,EAAE,OAAO,EAClB,SAAS,EAAE,cAAc,CAAC,CAAC,CAAC,EAC5B,aAAa,EAAE,MAAM,EAAE,GAAG,IAAI,GAC7B,IAAI,CA0GN"}

package/dist/bindings/list/index.d.ts

@@ -0,0 +1,19 @@
+import { EffectObject, ListOptions, ReadonlyAtom } from '../../types';
+import { ListContext } from './context';
+/**
+ * Internal engine for list reconciliation.
+ *
+ * When to use:
+ * - Coordinates the full lifecycle: Empty state -> Diffing -> Rendering -> DOM placement.
+ *
+ * Boundary:
+ * - Uses `untracked` to ensure DOM mutations don't accidentally trigger parent effects.
+ * - Relies on `ListContext` for state persistence across render cycles.
+ *
+ * @internal
+ */
+export declare function applyListBinding<T>(element: HTMLElement, source: ReadonlyAtom<T[]>, options: ListOptions<T>): {
+    fx: EffectObject;
+    ctx: ListContext<T>;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/bindings/list/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/bindings/list/index.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAsB,WAAW,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE3F,OAAO,EAAuD,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AAalG;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAChC,OAAO,EAAE,WAAW,EACpB,MAAM,EAAE,YAAY,CAAC,CAAC,EAAE,CAAC,EACzB,OAAO,EAAE,WAAW,CAAC,CAAC,CAAC,GACtB;IAAE,EAAE,EAAE,YAAY,CAAC;IAAC,GAAG,EAAE,WAAW,CAAC,CAAC,CAAC,CAAA;CAAE,CAiD3C"}

package/dist/bindings/list/types.d.ts

@@ -0,0 +1,100 @@
+import { ListKey, ListKeyFn, ListOptions } from '../../types';
+export type { ListKey, ListKeyFn };
+/**
+ * Enumeration of lifecycle flags representing the reconciliation status of a list item.
+ *
+ * These flags are used by the internal DOM synchronizer to determine the minimum
+ * required action (skipping, patching, or re-rendering) for each element.
+ *
+ * When to use:
+ * - Internal orchestration of DOM updates within the `atomList` binding engine.
+ *
+ * @internal
+ */
+export declare const ItemState: {
+    /**
+     * Logic: The item's key and data are identical to the previous state.
+     * Optimization: No DOM manipulation is required; this is the fastest execution path.
+     */
+    readonly Unchanged: 0;
+    /**
+     * Logic: The key has been identified in the previous state, but its position
+     * or data may require a patch or an update callback execution.
+     */
+    readonly Existing: number;
+    /**
+     * Logic: The item's key was not found in the previous state.
+     * Action: A fresh DOM node must be created and inserted.
+     */
+    readonly New: number;
+    /**
+     * Logic: The key matched, but the item's data has changed and no custom
+     * `update` callback was provided by the user.
+     * Action: Requires a full destruction of the existing node followed by a
+     * re-creation to ensure the DOM accurately reflects the new data.
+     */
+    readonly ForceReplace: number;
+};
+export type ItemState = (typeof ItemState)[keyof typeof ItemState];
+/**
+ * Represents a single item's reconciliation state and metadata.
+ *
+ * @internal
+ */
+export interface DiffSlot<T> {
+    /** The unique key for the item. */
+    key: ListKey;
+    /** The current data item. */
+    item: T;
+    /** The assigned reconciliation state. */
+    state: ItemState;
+    /** The index in the previous state, or -1 if new. */
+    oldIndex: number;
+    /** The index in the new state. */
+    targetIndex: number;
+    /** The current DOM handle. */
+    node: Element | JQuery | undefined;
+}
+/**
+ * A reconciliation plan generated by the diffing algorithm.
+ *
+ * Logic: This interface provides a unified table of item slots and metadata
+ * required by the DOM synchronizer to perform atomic mutations.
+ *
+ * @internal
+ */
+export interface PreparedDiff<T> {
+    /** The unified collection of item slots. */
+    slots: DiffSlot<T>[];
+    /**
+     * A collection of slots that require new DOM construction or HTML parsing.
+     */
+    toRender: DiffSlot<T>[];
+}
+/**
+ * A collection of user-provided lifecycle hooks and event configurations.
+ *
+ * @internal
+ */
+export interface PlaceCallbacks<T> {
+    /** Invoked once when an element is first bound to a reactive item. */
+    bind?: (($el: JQuery, item: T, index: number) => void) | undefined;
+    /** Invoked on subsequent updates when item data changes. */
+    update?: (($el: JQuery, item: T, index: number) => void) | undefined;
+    /** Invoked when a new item is physically added to the DOM. */
+    onAdd?: (($el: JQuery) => void) | undefined;
+    /** Invoked to manage the removal of an item, supporting asynchronous transitions. */
+    onRemove?: ListOptions<T>['onRemove'] | undefined;
+    /** Delegated event listeners for the list container. */
+    events?: ListOptions<T>['events'] | undefined;
+}
+/**
+ * Normalization table for delegated event listeners.
+ * @internal
+ */
+export interface EventBinding {
+    type: string;
+    selector: string;
+    callback: Function;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/bindings/list/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/bindings/list/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAE/D,YAAY,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC;AAEnC;;;;;;;;;;GAUG;AACH,eAAO,MAAM,SAAS;IACpB;;;OAGG;;IAGH;;;OAGG;;IAGH;;;OAGG;;IAGH;;;;;OAKG;;CAEK,CAAC;AAEX,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,OAAO,SAAS,CAAC,CAAC;AAEnE;;;;GAIG;AACH,MAAM,WAAW,QAAQ,CAAC,CAAC;IACzB,mCAAmC;IACnC,GAAG,EAAE,OAAO,CAAC;IACb,6BAA6B;IAC7B,IAAI,EAAE,CAAC,CAAC;IACR,yCAAyC;IACzC,KAAK,EAAE,SAAS,CAAC;IACjB,qDAAqD;IACrD,QAAQ,EAAE,MAAM,CAAC;IACjB,kCAAkC;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,8BAA8B;IAC9B,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC;CACpC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,4CAA4C;IAC5C,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;IACrB;;OAEG;IACH,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;CACzB;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC;IAC/B,sEAAsE;IACtE,IAAI,CAAC,EAAE,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;IACnE,4DAA4D;IAC5D,MAAM,CAAC,EAAE,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;IACrE,8DAA8D;IAC9D,KAAK,CAAC,EAAE,CAAC,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;IAC5C,qFAAqF;IACrF,QAAQ,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,SAAS,CAAC;IAClD,wDAAwD;IACxD,MAAM,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,SAAS,CAAC;CAC/C;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,QAAQ,CAAC;CACpB"}

package/dist/bindings/list/utils.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Normalizes a raw DOM element or a jQuery collection into a standard jQuery object.
+ *
+ * Logic: Polymorphic Input
+ * Supports both raw Element for single operations and JQuery collections for bulk
+ * processing, ensuring consistent API behavior.
+ *
+ * @internal
+ */
+export declare function wrap($el: Element | JQuery<Element>): JQuery;
+/**
+ * Assigns or removes a stable reactive identifier on a DOM node or collection.
+ *
+ * @param node - The target DOM element or collection.
+ * @param key - Unique string key for identification, or null to remove.
+ * @internal
+ */
+export declare function setAtomKey(node: Element | Node | JQuery, key: string | null): void;
+/**
+ * Performs a deep recursive cleanup of reactive resources associated with a DOM tree.
+ *
+ * Constraint: Teardown Order
+ * Must be executed before an element is permanently detached or replaced.
+ *
+ * Caution: Memory Leak
+ * Failure to call this results in "zombie" reactive effects remaining in the
+ * global registry, leading to significant memory growth over time.
+ *
+ * @param node - The root element or collection to purge from the registry.
+ * @internal
+ */
+export declare function cleanupNodes(node: Element | JQuery): void;
+//# sourceMappingURL=utils.d.ts.map

package/dist/bindings/list/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../src/bindings/list/utils.ts"],"names":[],"mappings":"AAGA;;;;;;;;GAQG;AACH,wBAAgB,IAAI,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,MAAM,CAG3D;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,GAAG,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAgClF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAczD"}

package/dist/bindings/mount.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=mount.d.ts.map

package/dist/bindings/mount.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mount.d.ts","sourceRoot":"","sources":["../../src/bindings/mount.ts"],"names":[],"mappings":""}

package/dist/bindings/unified.d.ts

@@ -0,0 +1,135 @@
+import { AsyncReactiveValue, BindingOptions, CssValue, PrimitiveValue, ValOptions, WritableAtom } from '../types';
+/**
+ * Binds the text content of an element to a reactive source.
+ *
+ * When to use:
+ * - To synchronize labels or counts with an atom without the risk of XSS.
+ *
+ * @param element - The target HTMLElement.
+ * @param value - The reactive source atom or computed.
+ * @param formatter - An optional function to format the value before display.
+ * @internal
+ */
+export declare function bindText<T = unknown>(element: HTMLElement, value: AsyncReactiveValue<T>, formatter?: (value: T) => string): void;
+/**
+ * Binds the HTML content of an element to a reactive source.
+ *
+ * Logic: To prevent memory leaks from detached nodes, all reactive bindings
+ * within the element's descendants are automatically cleaned up via the
+ * registry before the `innerHTML` is overwritten.
+ *
+ * Caution: Even with sanitization, rendering user-provided HTML remains a
+ * security risk. Prefer `bindText` whenever possible.
+ *
+ * When to use:
+ * - To render trusted templates or rich text containing formatting tags.
+ *
+ * @param element - The target HTMLElement.
+ * @param value - The reactive source containing the HTML string.
+ * @internal
+ */
+export declare function bindHtml(element: HTMLElement, value: AsyncReactiveValue<string>): void;
+/**
+ * Binds a set of CSS classes to reactive conditions.
+ *
+ * Logic: Token Management
+ * - Supports space-separated class names within keys.
+ * - Active tokens are tracked in a `Set` to ensure classes are only removed
+ *   if no other active definition within the map requires them.
+ *
+ * @param element - The target HTMLElement.
+ * @param classMap - A record mapping class names to reactive boolean conditions.
+ * @internal
+ */
+export declare function bindClass(element: HTMLElement, classMap: Record<string, AsyncReactiveValue<boolean>>): void;
+/**
+ * Binds inline CSS styles to reactive sources.
+ *
+ * Security: Dangerous CSS values (e.g., `url()` containing javascript: protocols)
+ * are blocked to prevent XSS and style-based injection attacks.
+ *
+ * @param element - The target HTMLElement.
+ * @param cssMap - A record mapping style properties to reactive values.
+ * @internal
+ */
+export declare function bindCss(element: HTMLElement, cssMap: Record<string, CssValue>): void;
+/**
+ * Binds HTML attributes to reactive sources.
+ *
+ * Logic: Attribute Transformation Pipeline
+ * Implements a unified transformation flow for different attribute categories:
+ * - Boolean Attributes: Automatically removed when the condition is `false`.
+ * - ARIA Attributes: Boolean values are mapped to 'true'/'false' strings.
+ * - Standard Attributes: Values are coerced to strings.
+ *
+ * Security: Protocol Validation
+ * Validates 'href' and 'src' attributes against dangerous URL protocols to
+ * mitigate potential XSS vectors.
+ *
+ * @param element - The target HTMLElement.
+ * @param attrMap - A record mapping attribute names to reactive values.
+ * @internal
+ */
+export declare function bindAttr(element: HTMLElement, attrMap: Record<string, AsyncReactiveValue<PrimitiveValue>>): void;
+/**
+ * Binds DOM properties directly to reactive sources.
+ *
+ * Security: Blocks sensitive properties (e.g., `innerHTML`, event handlers)
+ * and validates URL-based properties to prevent prototype pollution or XSS.
+ *
+ * @param element - The target HTMLElement.
+ * @param propMap - A record mapping property names to reactive values.
+ * @internal
+ */
+export declare function bindProp(element: HTMLElement, propMap: Record<string, AsyncReactiveValue<unknown>>): void;
+/**
+ * Manages element visibility based on a reactive condition.
+ *
+ * Logic: Layout Preservation
+ * Transitions between 'visible' and 'hidden' states while preserving the
+ * element's original 'display' mode (e.g., flex, grid) when restored.
+ *
+ * @param element - The target HTMLElement.
+ * @param condition - The reactive boolean condition governing visibility.
+ * @param invert - If true, hides the element when the condition is met.
+ * @internal
+ */
+export declare function bindVisibility(element: HTMLElement, condition: AsyncReactiveValue<boolean>, invert: boolean): void;
+/**
+ * Binds a form control's value to a writable atom.
+ *
+ * When to use:
+ * - To implement two-way synchronization for inputs, selects, and textareas.
+ *
+ * @param element - The form control element.
+ * @param atom - The writable atom to synchronize with.
+ * @param options - Configuration for debouncing and transformation.
+ * @internal
+ */
+export declare function bindVal(element: HTMLElement, atom: WritableAtom<unknown>, options?: ValOptions<unknown>): void;
+/**
+ * Binds a checkbox or radio button's checked state to a writable atom.
+ *
+ * @param element - The target input element.
+ * @param atom - The writable atom to synchronize with the checked state.
+ * @internal
+ */
+export declare function bindChecked(element: HTMLElement, atom: WritableAtom<boolean>): void;
+/**
+ * Binds a mapping of event listeners to an element.
+ *
+ * @param element - The target HTMLElement.
+ * @param eventMap - A record mapping event names to handler functions.
+ * @internal
+ */
+export declare function bindEvents(element: HTMLElement, eventMap: NonNullable<BindingOptions['on']>): void;
+/**
+ * Binds a single event listener to an element.
+ *
+ * @param element - The target HTMLElement.
+ * @param event - The name of the event.
+ * @param handler - The handler function to execute.
+ * @internal
+ */
+export declare function bindOn(element: HTMLElement, event: string, handler: (event: JQuery.TriggeredEvent) => void): void;
+//# sourceMappingURL=unified.d.ts.map

package/dist/bindings/unified.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unified.d.ts","sourceRoot":"","sources":["../../src/bindings/unified.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EACV,kBAAkB,EAClB,cAAc,EACd,QAAQ,EACR,cAAc,EAEd,UAAU,EACV,YAAY,EACb,MAAM,SAAS,CAAC;AAqCjB;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CAAC,CAAC,GAAG,OAAO,EAClC,OAAO,EAAE,WAAW,EACpB,KAAK,EAAE,kBAAkB,CAAC,CAAC,CAAC,EAC5B,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,MAAM,GAC/B,IAAI,CAeN;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,kBAAkB,CAAC,MAAM,CAAC,GAAG,IAAI,CAgBtF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CACvB,OAAO,EAAE,WAAW,EACpB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,OAAO,CAAC,CAAC,GACpD,IAAI,CA6BN;AAED;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,GAAG,IAAI,CA8BpF;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,QAAQ,CACtB,OAAO,EAAE,WAAW,EACpB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,cAAc,CAAC,CAAC,GAC1D,IAAI,CA8CN;AAED;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CACtB,OAAO,EAAE,WAAW,EACpB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,OAAO,CAAC,CAAC,GACnD,IAAI,CAwBN;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,WAAW,EACpB,SAAS,EAAE,kBAAkB,CAAC,OAAO,CAAC,EACtC,MAAM,EAAE,OAAO,GACd,IAAI,CAuBN;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,OAAO,CACrB,OAAO,EAAE,WAAW,EACpB,IAAI,EAAE,YAAY,CAAC,OAAO,CAAC,EAC3B,OAAO,GAAE,UAAU,CAAC,OAAO,CAAM,GAChC,IAAI,CAeN;AAsBD;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,YAAY,CAAC,OAAO,CAAC,GAAG,IAAI,CAgCnF;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CACxB,OAAO,EAAE,WAAW,EACpB,QAAQ,EAAE,WAAW,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,GAC1C,IAAI,CAIN;AAED;;;;;;;GAOG;AACH,wBAAgB,MAAM,CACpB,OAAO,EAAE,WAAW,EACpB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,cAAc,KAAK,IAAI,GAC9C,IAAI,CAIN"}