@but212/atom-effect-jquery 0.30.1 → 0.32.0

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,29 @@
+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 containing the state model.
+ * @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>, 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,EAML,KAAK,YAAY,EAClB,MAAM,qBAAqB,CAAC;AAI7B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AA0S3C;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,MAAM,EACvC,IAAI,EAAE,eAAe,EACrB,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC,EACrB,OAAO,GAAE,WAAW,CAAC,OAAO,CAAM,GACjC,IAAI,CAGN"}

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,61 @@
+import { EffectObject, ListKey } from '../../types';
+/**
+ * Manages the reconciliation state and lifecycle for the `$.fn.atomList` binding.
+ *
+ * This context tracks historical DOM nodes and keys to enable efficient diffing.
+ * Its primary responsibility is coordinating asynchronous item removals (e.g., animations)
+ * while ensuring that elements reused in the same cycle are not accidentally destroyed.
+ *
+ * @internal
+ */
+export declare class ListContext<T> {
+    readonly $container: JQuery;
+    readonly containerSelector: string;
+    readonly onRemove: (($el: JQuery) => Promise<void> | void) | undefined;
+    private _oldKeys;
+    private _oldItems;
+    private _oldNodes;
+    private readonly _removingKeys;
+    private _emptyEl;
+    private readonly _keyToIndex;
+    fx?: EffectObject;
+    constructor($container: JQuery, containerSelector: string, onRemove: (($el: JQuery) => Promise<void> | void) | undefined);
+    get oldKeys(): ListKey[];
+    set oldKeys(v: ListKey[]);
+    get oldItems(): T[];
+    set oldItems(v: T[]);
+    get oldNodes(): (Element | JQuery<HTMLElement> | undefined)[];
+    set oldNodes(v: (Element | JQuery<HTMLElement> | undefined)[]);
+    get removingKeys(): Set<ListKey>;
+    get keyToIndex(): Map<ListKey, number>;
+    get $emptyEl(): JQuery<HTMLElement> | null;
+    set $emptyEl(v: JQuery<HTMLElement> | null);
+    /**
+     * Retrieves the index of a key, supporting string-to-number normalization.
+     *
+     * Reason: DOM attributes (like `data-atom-key`) are always returned as strings,
+     * but the internal `_keyToIndex` map might use numbers.
+     */
+    getIndex(key: ListKey | string): number | undefined;
+    /**
+     * Orchestrates the physical removal of an element from the DOM.
+     *
+     * Logic:
+     * 1. If `onRemove` returns a Promise, it waits for completion (e.g., a fade-out animation).
+     * 2. Constraint: Before calling `.remove()`, it checks if the element has been "resurrected"
+     *    (assigned a new `data-atom-key`) by a subsequent render cycle.
+     */
+    scheduleRemoval(k: ListKey, $el: JQuery): void;
+    /**
+     * Marks a key as "removing" and initiates the removal sequence.
+     *
+     * Note: The `data-atom-key` attribute is cleared immediately to prevent the reconciler
+     * from finding this "ghost" element via DOM lookups while animations are still running.
+     */
+    removeItem(k: ListKey, $el: JQuery): void;
+    /**
+     * Performs full cleanup of the list state and event listeners.
+     */
+    dispose(): 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;;;;;;;;GAQG;AACH,qBAAa,WAAW,CAAC,CAAC;aAWN,UAAU,EAAE,MAAM;aAClB,iBAAiB,EAAE,MAAM;aACzB,QAAQ,EAAE,CAAC,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,SAAS;IAZ/E,OAAO,CAAC,QAAQ,CAAiB;IACjC,OAAO,CAAC,SAAS,CAAW;IAC5B,OAAO,CAAC,SAAS,CAAwC;IACzD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAsB;IACpD,OAAO,CAAC,QAAQ,CAAuB;IACvC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA8B;IAEnD,EAAE,CAAC,EAAE,YAAY,CAAC;gBAGP,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;IAG/E,IAAI,OAAO,cAEV;IACD,IAAI,OAAO,CAAC,CAAC,WAAA,EAEZ;IACD,IAAI,QAAQ,QAEX;IACD,IAAI,QAAQ,CAAC,CAAC,KAAA,EAEb;IACD,IAAI,QAAQ,kDAEX;IACD,IAAI,QAAQ,CAAC,CAAC,+CAAA,EAEb;IACD,IAAI,YAAY,iBAEf;IACD,IAAI,UAAU,yBAEb;IACD,IAAI,QAAQ,+BAEX;IACD,IAAI,QAAQ,CAAC,CAAC,4BAAA,EAEb;IAED;;;;;OAKG;IACH,QAAQ,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS;IAWnD;;;;;;;OAOG;IACH,eAAe,CAAC,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAiB9C;;;;;OAKG;IACH,UAAU,CAAC,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAMzC;;OAEG;IACH,OAAO,IAAI,IAAI;CAShB"}

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

@@ -0,0 +1,32 @@
+import { ListKeyFn, ListOptions } from '../../types';
+import { ListContext } from './context';
+import { PreparedDiff } from './types';
+/**
+ * Generates a reconciliation plan by calculating the difference between the
+ * current list state and the new item set.
+ *
+ * Logic: This function implements a double-ended diffing algorithm to identify
+ * reusable DOM nodes, new entries, and required replacements. It optimizes
+ * performance by isolating the "dirty" range — skipping unchanged items at
+ * both the head and tail of the list.
+ *
+ * When to use:
+ * - Internal orchestration of DOM mutations for the `atomList` binding.
+ *
+ * @param ctx - The current list context containing historical DOM state.
+ * @param items - The new set of items to render.
+ * @param itemCount - The total number of new items.
+ * @param getKey - A function to derive a unique key for each item.
+ * @param update - An optional callback used to patch existing DOM nodes.
+ * @param isEqual - An optional equality comparator for items.
+ * @returns A detailed diff plan used to execute DOM updates.
+ *
+ * @example
+ * ```typescript
+ * const diff = buildIndices(context, nextItems, nextItems.length, getKey, onUpdate, onEqual);
+ * ```
+ *
+ * @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,EAAa,KAAK,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;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,CA6HjB"}

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

@@ -0,0 +1,63 @@
+import { ListOptions } from '../../types';
+import { ListContext } from './context';
+import { PlaceCallbacks, PreparedDiff } from './types';
+/**
+ * A low-level DOM utility for inserting elements before a specific reference node.
+ *
+ * This helper supports both raw `Element` instances and jQuery collections,
+ * ensuring consistent insertion behavior regardless of the input type.
+ *
+ * @param elOrJq - The element or jQuery collection to insert.
+ * @param nextNode - The reference node to insert before. If null, appends to the container.
+ * @param container - The parent container element.
+ * @internal
+ */
+export declare function insertOrAppend(elOrJq: Element | JQuery | undefined, nextNode: Node | null, container: Element): void;
+/**
+ * Orchestrates the cleanup of a list container and the rendering of empty placeholders.
+ *
+ * Logic: If an `onRemove` callback is provided, the function performs asynchronous
+ * removals for each item to allow for exit animations. Otherwise, it executes a
+ * destructive `empty()` on the container for efficiency.
+ *
+ * When to use:
+ * - To reset a list container during reconciliation or when the data source becomes empty.
+ *
+ * @param ctx - The list context containing historical state.
+ * @param itemCount - The number of items in the new data set.
+ * @param $container - The jQuery-wrapped container.
+ * @param empty - The template or element to display when the list is empty.
+ * @internal
+ */
+export declare function handleEmpty<T>(ctx: ListContext<T>, itemCount: number, $container: JQuery, empty: ListOptions<T>['empty']): void;
+/**
+ * Transforms items into DOM handles based on the reconciliation plan.
+ *
+ * Optimization: If all items utilize string templates and the list is undergoing
+ * an initial render (cold start), the function returns sanitized HTML fragments
+ * for direct `innerHTML` injection, bypassing the overhead of individual jQuery
+ * object construction.
+ *
+ * When to use:
+ * - Internal processing of new items within the `atomList` lifecycle.
+ *
+ * @param diff - The prepared diff plan.
+ * @param options - Configuration options for the list.
+ * @param isInitial - Indicates whether this is the first render of the list.
+ * @returns An array of sanitized HTML strings if the fast-path is applicable; otherwise null.
+ * @internal
+ */
+export declare function renderItems<T>(diff: PreparedDiff<T>, options: ListOptions<T>, isInitial: boolean): string[] | null;
+/**
+ * Identifies and removes items that are no longer present in the reactive data set.
+ *
+ * Logic: Iterates through the historical key set and triggers the removal
+ * lifecycle for any key that is not found in the new state.
+ *
+ * @param ctx - The list context containing historical state.
+ * @param diff - The prepared diff plan.
+ * @internal
+ */
+export declare function cleanupRemoved<T>(ctx: ListContext<T>, diff: PreparedDiff<T>): void;
+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;AAC7C,OAAO,EAAa,KAAK,cAAc,EAAE,KAAK,YAAY,EAAE,MAAM,SAAS,CAAC;AAG5E;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,EACpC,QAAQ,EAAE,IAAI,GAAG,IAAI,EACrB,SAAS,EAAE,OAAO,GACjB,IAAI,CAUN;AAED;;;;;;;;;;;;;;;GAeG;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;;;;;;;;;;;;;;;;GAgBG;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,CA+CjB;AAmBD;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,GAAG,EAAE,WAAW,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,IAAI,CASlF;AA0BD,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,CA8EN"}

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

@@ -0,0 +1,2 @@
+export {};
+//# 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":""}

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

@@ -0,0 +1,93 @@
+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];
+/**
+ * A reconciliation plan generated by the diffing algorithm.
+ *
+ * Logic: This interface provides index-based buffers and metadata required by
+ * the DOM synchronizer to perform atomic mutations with minimal overhead.
+ *
+ * @internal
+ */
+export interface PreparedDiff<T> {
+    /** The collection of unique keys for the new item set. */
+    newKeys: ListKey[];
+    /** The collection of data items for the new state. */
+    newItems: T[];
+    /** A set containing all unique keys used for duplicate detection. */
+    newKeySet: Set<ListKey>;
+    /** A map of new indices to their corresponding indices in the previous state. */
+    newIndices: number[];
+    /** The reconciliation state assigned to each item. */
+    newStates: ItemState[];
+    /** The current DOM handles (Element or jQuery) for each item. */
+    newNodes: (Element | JQuery | undefined)[];
+    /**
+     * A collection of items that require new DOM construction or HTML parsing
+     * during this rendering cycle.
+     */
+    toRender: {
+        key: ListKey;
+        item: T;
+        index: number;
+    }[];
+    /** The starting index of the "dirty" middle section after prefix optimization. */
+    startIndex: number;
+    /** The ending index of the "dirty" section relative to the old list state. */
+    oldEndIndex: number;
+    /** The ending index of the "dirty" section relative to the new list state. */
+    newEndIndex: number;
+}
+/**
+ * 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;
+}
+//# 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;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,0DAA0D;IAC1D,OAAO,EAAE,OAAO,EAAE,CAAC;IACnB,sDAAsD;IACtD,QAAQ,EAAE,CAAC,EAAE,CAAC;IACd,qEAAqE;IACrE,SAAS,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;IACxB,iFAAiF;IACjF,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,sDAAsD;IACtD,SAAS,EAAE,SAAS,EAAE,CAAC;IACvB,iEAAiE;IACjE,QAAQ,EAAE,CAAC,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC,EAAE,CAAC;IAE3C;;;OAGG;IACH,QAAQ,EAAE;QAAE,GAAG,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,CAAC,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAErD,kFAAkF;IAClF,UAAU,EAAE,MAAM,CAAC;IACnB,8EAA8E;IAC9E,WAAW,EAAE,MAAM,CAAC;IACpB,8EAA8E;IAC9E,WAAW,EAAE,MAAM,CAAC;CACrB;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"}

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.
+ *
+ * @param $el - The element or collection to normalize.
+ * @returns A standard jQuery object.
+ * @internal
+ */
+export declare function wrap($el: Element | JQuery<Element>): JQuery;
+/**
+ * Assigns or removes a stable reactive identifier on a DOM node or collection.
+ *
+ * Logic: The `data-atom-key` attribute serves as the primary stable identifier
+ * for DOM nodes within the list reconciliation engine. This allows the diffing
+ * algorithm to perform O(N) re-ordering and node reuse, avoiding the overhead
+ * of positional comparisons.
+ *
+ * @param node - The DOM element, Node, or jQuery collection.
+ * @param key - The unique string key to assign, or null to remove the identifier.
+ * @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.
+ *
+ * Caution: This method must be executed before an element is permanently detached
+ * from the DOM or replaced. Failure to do so may result in "zombie" reactive
+ * effects remaining in the registry, leading to significant memory leaks.
+ *
+ * @param node - The root element or jQuery collection to clean up.
+ * @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;;;;;;GAMG;AACH,wBAAgB,IAAI,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,MAAM,CAE3D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,GAAG,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAoBlF;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAYzD"}

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"}

package/dist/constants.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Centralized repository for library-wide constants, defaults, and error templates.
+ *
+ * Logic: Subsystem Organization
+ * Consolidates global prefixes, defaults, and error templates into logical
+ * namespaces. This organization ensures consistency across the library and
+ * provides a central location for modifying system behavior.
+ *
+ * @internal
+ */
+/** Constants for the core reactive engine. @internal */
+export declare const SYSTEM_CORE: {
+    readonly ERRORS: {
+        readonly EFFECT_DISPOSE_ERROR: (i?: string) => string;
+    };
+};
+/** Configuration and error templates for the routing subsystem. @internal */
+export declare const SYSTEM_ROUTE: {
+    readonly PREFIX: "[atom-route]";
+    readonly DEFAULTS: Readonly<{
+        readonly mode: "hash";
+        readonly basePath: "";
+        readonly autoBindLinks: false;
+        readonly activeClass: "active";
+    }>;
+    readonly ERRORS: {
+        readonly NOT_FOUND: (n: string) => string;
+        readonly TEMPLATE_NOT_FOUND: (s: string) => string;
+        readonly TARGET_NOT_FOUND: (s: string) => string;
+        readonly MALFORMED_URI: (r: string) => string;
+    };
+};
+/** Configuration and error templates for reactive bindings. @internal */
+export declare const SYSTEM_BINDING: {
+    readonly PREFIX: "[atom-binding]";
+    readonly INPUT_DEFAULTS: Readonly<{
+        readonly event: "input change";
+        readonly debounce: 0;
+    }>;
+    readonly VALID_INPUT_TAGS: readonly ["input", "select", "textarea"];
+    readonly ERRORS: {
+        readonly INVALID_INPUT_ELEMENT: (t: string) => string;
+        readonly MISSING_SOURCE: (m: string) => string;
+        readonly MISSING_CONDITION: (m: string) => string;
+        readonly UPDATER_ERROR: (d: string, s?: boolean) => string;
+        readonly CLEANUP_ERROR: (i?: string) => string;
+        readonly PARSE_ERROR: (d?: string) => string;
+    };
+};
+/**
+ * Constants for the security and sanitization engine.
+ *
+ * Logic: Sanitization Schema
+ * Defines the properties and URI protocols considered inherently dangerous.
+ * These constants form the basis of the library's XSS and DOM Clobbering
+ * prevention strategy.
+ *
+ * @internal
+ */
+export declare const SYSTEM_SECURITY: {
+    /** Property names that are blocked to prevent XSS and property hijacking. */
+    readonly DANGEROUS_PROPS: readonly ["innerHTML", "outerHTML", "srcdoc", "__proto__", "constructor", "prototype"];
+    /** Attributes that must be validated for dangerous URI protocols. */
+    readonly URL_PROPS: readonly ["src", "href", "action", "formaction", "data", "poster", "background", "cite", "longdesc", "profile", "usemap", "classid", "codebase", "xlink:href"];
+    /** Pattern for identifying malicious URI protocols. */
+    readonly DANGEROUS_PROTOCOL_PATTERN: "(?:javascript|vbscript)";
+    readonly ERRORS: {
+        readonly UNSAFE_CONTENT: () => string;
+        readonly BLOCKED_CSS_VALUE: (p: string) => string;
+        readonly BLOCKED_EVENT_HANDLER: (n: string) => string;
+        readonly BLOCKED_PROTOCOL: (n: string) => string;
+        readonly BLOCKED_PROP: (n: string) => string;
+    };
+};
+/** Error templates for list rendering. @internal */
+export declare const SYSTEM_LIST: {
+    readonly PREFIX: "[atom-list]";
+    readonly ERRORS: {
+        readonly DUPLICATE_KEY: (k: string | number, i: number) => string;
+    };
+};
+/** Error templates for component mounting. @internal */
+export declare const SYSTEM_MOUNT: {
+    readonly PREFIX: "[atom-mount]";
+    readonly ERRORS: {
+        readonly ERROR: (n?: string) => string;
+        readonly CLEANUP_ERROR: (n?: string) => string;
+    };
+};
+/** Error templates for Web Components. @internal */
+export declare const SYSTEM_COMPONENT: {
+    readonly PREFIX: "[atom-component]";
+    readonly ATTRS: {
+        readonly BIND: "data-aej-bind";
+        readonly PART: "data-aej-part";
+        readonly LEGACY_BIND: "data-bind";
+    };
+    readonly ERRORS: {
+        readonly NOT_REGISTERED: (tagName: string) => string;
+    };
+};
+/** Defaults for the visual debug system. @internal */
+export declare const SYSTEM_DEBUG: {
+    readonly DEFAULTS: {
+        readonly HIGHLIGHT_DURATION_MS: 500;
+    };
+};
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AAEH,wDAAwD;AACxD,eAAO,MAAM,WAAW;;4CAEO,MAAM;;CAE3B,CAAC;AAEX,6EAA6E;AAC7E,eAAO,MAAM,YAAY;;;;;;;;;gCASN,MAAM;yCACG,MAAM;uCACR,MAAM;oCACT,MAAM;;CAEnB,CAAC;AAEX,yEAAyE;AACzE,eAAO,MAAM,cAAc;;;;;;;;4CAOI,MAAM;qCACb,MAAM;wCACH,MAAM;oCACV,MAAM,MAAM,OAAO;qCAClB,MAAM;mCACR,MAAM;;CAElB,CAAC;AAEX;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe;IAC1B,6EAA6E;;IAS7E,qEAAqE;;IAiBrE,uDAAuD;;;;wCAI9B,MAAM;4CACF,MAAM;uCACX,MAAM;mCACV,MAAM;;CAElB,CAAC;AAEX,oDAAoD;AACpD,eAAO,MAAM,WAAW;;;oCAGD,MAAM,GAAG,MAAM,KAAK,MAAM;;CAEvC,CAAC;AAEX,wDAAwD;AACxD,eAAO,MAAM,YAAY;;;6BAGT,MAAM;qCACE,MAAM;;CAEpB,CAAC;AAEX,oDAAoD;AACpD,eAAO,MAAM,gBAAgB;;;;;;;;2CAQC,MAAM;;CAE1B,CAAC;AAEX,sDAAsD;AACtD,eAAO,MAAM,YAAY;;;;CAIf,CAAC"}