@but212/atom-effect-jquery 0.30.0 → 0.31.0

package/dist/index.d.ts

@@ -5,12 +5,28 @@ import { ReadonlyAtom } from '@but212/atom-effect';
 import { WritableAtom } from '@but212/atom-effect';
 
 /**
- * An extension of ReactiveValue that also supports Promises and async functions.
- * The binding system automatically handles the promise lifecycle, showing the
- * latest resolved value and ignoring stale ones (race condition protection).
+ * Extension of ReactiveValue that permits Promises.
+ * Used primarily for CSS and Attribute bindings that might rely on async fetching.
  */
 declare type AsyncReactiveValue<T> = T | ReadonlyAtom<T | Promise<T>> | Promise<T> | (() => T | Promise<T>);
 
+export declare interface AtomNavOptions {
+    target: string | JQuery<HTMLElement> | HTMLElement;
+    selector?: string;
+    headers?: Record<string, string>;
+    onBeforeLoad?: (url: string) => boolean | undefined | Promise<boolean | undefined>;
+    onMount?: ($container: JQuery, url: string) => void;
+    onUnmount?: ($container: JQuery, oldUrl: string) => void;
+    onError?: (err: unknown, url: string) => boolean | undefined;
+    scrollToTop?: boolean;
+    syncTitle?: boolean;
+    window?: Window & typeof globalThis;
+}
+
+/**
+ * Central DSL for declarative jQuery bindings.
+ * Maps reactive sources to specific DOM manipulation strategies.
+ */
 export declare interface BindingOptions<T = unknown> {
     text?: AsyncReactiveValue<unknown> | [source: AsyncReactiveValue<unknown>, formatter: (v: unknown) => string];
     html?: AsyncReactiveValue<string>;
@@ -30,51 +46,49 @@ export declare interface BindingOptions<T = unknown> {
 }
 
 /**
- * Central registry mapping DOM elements to their reactive binding records.
+ * Manages the lifecycle of reactive bindings and component effects.
  *
- * Design goals:
- * - Zero memory leaks: all collections use WeakMap/WeakSet keyed by Element.
- * - Minimal allocations in the hot tracking path.
- * - O(bound-descendants) cleanup via a single querySelectorAll pass.
+ * Safety Rationale:
+ * - Uses WeakMap for records to avoid holding strong references that prevent GC.
+ * - Uses WeakSet for node flags (kept/ignored) to ensure the registry doesn't leak
+ *   memory even for nodes that were "lost" without a cleanup call.
  */
 declare class BindingRegistry {
     private records;
     private preservedNodes;
     private ignoredNodes;
+    /** Mark a node to preserve its effects even if detached from the DOM (e.g., jQuery .detach()). */
     keep(node: Node): void;
     isKept(node: Node): boolean;
+    /** Temporary flag to block redundant cleanup cycles for the same node. */
     markIgnored(node: Node): void;
     isIgnored(node: Node): boolean;
     private getOrCreateRecord;
+    private addCleanup;
+    /** Registers a reactive effect instance to be disposed when the element is removed. */
+    trackEffect(element: Element, reactiveEffect: EffectObject): void;
+    /** Registers a generic cleanup closure to be executed when the element is removed. */
+    trackCleanup(element: Element, cleanupFunction: () => void): void;
+    /** Sets the optional teardown function returned by a mounted component. */
+    setComponentCleanup(element: Element, teardownFunction: (() => void) | undefined): void;
+    hasBind(element: Element): boolean;
     /**
-     * Registers a reactive effect with an element's record.
-     * Effects are automatically disposed when the element is removed from the DOM.
-     *
-     * @param el - The DOM element to bind the effect to.
-     * @param fx - The reactive effect instance.
-     */
-    trackEffect(el: Element, fx: EffectObject): void;
-    /**
-     * Registers an arbitrary cleanup function with an element's record.
-     * Cleanups are executed when the element is removed from the DOM.
-     *
-     * @param el - The DOM element to bind the cleanup to.
-     * @param fn - The cleanup function (e.g., event unbinding, timer clear).
-     */
-    trackCleanup(el: Element, fn: () => void): void;
-    /**
-     * Assigns a component-level cleanup function (e.g., from atomMount).
-     * Unlike generic cleanups, there can only be one component cleanup per element.
+     * Performs the actual destruction of all resources bound to the node.
+     * This clears the record, removes the tracking CSS class, and executes all callbacks.
      */
-    setComponentCleanup(el: Element, fn: (() => void) | undefined): void;
-    hasBind(el: Element): boolean;
-    cleanup(el: Node): void;
-    cleanupDescendants(el: Element | DocumentFragment | ShadowRoot): void;
-    cleanupTree(el: Node): void;
+    cleanup(node: Node): void;
+    cleanupDescendants(root: Element | DocumentFragment | ShadowRoot): void;
+    /** Destroys the reactive state of the element and its entire sub-tree. */
+    cleanupTree(node: Node): void;
 }
 
+/** Definition for a mountable component that manages its own lifecycle. */
 export declare type ComponentFn<P = Record<string, unknown>> = ($el: JQuery, props: P) => EffectResult;
 
+declare interface ComponentLifecycle {
+    unmount: EffectCleanup;
+}
+
 export { ComputedAtom }
 
 export declare type CssBindings = Record<string, CssValue>;
@@ -83,47 +97,46 @@ export declare type CssValue = AsyncReactiveValue<string | number> | [source: As
 
 export default default_2;
 
-/**
- * Stops all MutationObservers started by `enableAutoCleanup`.
- */
 export declare function disableAutoCleanup(): void;
 
-/**
- * Restores all jQuery methods patched by `enablejQueryOverrides()`.
- * Primarily useful in test environments to reset state between suites.
- */
+/** Restores original jQuery prototype methods to their clean state. */
 export declare function disablejQueryOverrides(): void;
 
 export declare type EffectCleanup = () => void;
 
-export declare type EffectResult = undefined | EffectCleanup;
+export declare type EffectResult = undefined | EffectCleanup | ComponentLifecycle;
 
 /**
- * Starts observing `root` for removed elements and automatically disposes
- * their reactive bindings when they leave the DOM.
- *
- * Supports Element, ShadowRoot, and DocumentFragment roots.
- * Multiple roots can be observed concurrently (e.g. for Micro-Frontends).
+ * Requirement: Native browser operations (like el.innerHTML = '') bypass jQuery hooks.
+ * This observer serves as a safety net, detecting removed nodes that missed the
+ * patched jQuery .remove() or .empty() calls.
  */
 export declare function enableAutoCleanup(root: Element | ShadowRoot | DocumentFragment): void;
 
+/**
+ * Globally overrides specific jQuery prototype methods to automate library behavior.
+ *
+ * Responsibilities:
+ * 1. Auto-Batching: Wraps all event handlers in 'batch()' to prevent UI jitter.
+ * 2. Lifecycle Sync: Hooking .remove()/.empty() to stop reactive effects on deleted elements.
+ * 3. Persistence: Hooking .detach() to preserve effects when nodes are moved temporarily.
+ * 4. Identity Management: Uses a WeakMap so .off(originalFn) still works correctly.
+ */
 export declare function enablejQueryOverrides(): void;
 
 export declare type EqualFn<T> = (a: T, b: T) => boolean;
 
 export declare interface FetchOptions<T> {
     defaultValue: T;
+    name?: string;
     method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS' | (string & {});
     headers?: Record<string, string>;
-    transform?: (raw: unknown) => T;
+    transform?: (raw: unknown, xhr: JQuery.jqXHR) => T;
     ajaxOptions?: JQuery.AjaxSettings | (() => JQuery.AjaxSettings);
     onError?: (err: unknown) => void;
     eager?: boolean;
 }
 
-/**
- * Options for `atomForm` binding.
- */
 declare interface FormOptions<T> extends ValOptions<T> {
     /** Custom function to transform field value based on path before atomic sync. */
     transform?: (path: string, value: unknown) => unknown;
@@ -131,19 +144,16 @@ declare interface FormOptions<T> extends ValOptions<T> {
     onChange?: (path: string, value: unknown) => void;
 }
 
-/** Checks if a given value is a reactive node (Atom or Computed). */
-export declare const isReactive: (v: unknown) => v is ReadonlyAtom<unknown>;
-
-declare type KeysOfType<T, V> = {
-    [K in keyof T]: T[K] extends V ? K : never;
-}[keyof T];
-
 declare type ListKey = string | number;
 
 declare type ListKeyFn<T> = (item: T, index: number) => ListKey;
 
+/**
+ * Configuration for high-performance list reconciliation.
+ * Uses 'key' for identity tracking to minimize DOM churn.
+ */
 export declare interface ListOptions<T> {
-    key: KeysOfType<T, ListKey> | ListKeyFn<T>;
+    key: keyof T | ListKeyFn<T>;
     render: (item: T, index: number) => ListRenderResult;
     bind?: ($el: JQuery, item: T, index: number) => void;
     update?: ($el: JQuery, item: T, index: number) => void;
@@ -156,16 +166,17 @@ export declare interface ListOptions<T> {
 
 declare type ListRenderResult = string | Element | DocumentFragment | JQuery;
 
-/** Resolves after microtask effects flush. Fast Promise-based scheduling. */
+/**
+ * Returns a promise that resolves after the next reactive tick.
+ * Useful for waiting until all pending effects have updated the DOM.
+ */
 export declare const nextTick: () => Promise<void>;
 
 export declare type PrimitiveValue = string | number | boolean | null | undefined;
 
 /**
- * Represents a value that can be tracked by the reactive system.
- * - T: Static value (one-time bind)
- * - ReadonlyAtom<T>: Reactive value (updates DOM when atom changes)
- * - () => T: Reactive function (updates DOM when any atom read inside changes)
+ * Flexible value container.
+ * Supports raw T, reactive Atoms, or functional getters for deferred execution.
  */
 export declare type ReactiveValue<T> = T | ReadonlyAtom<T> | (() => T);
 
@@ -173,15 +184,10 @@ export { ReadonlyAtom }
 
 export declare const registry: BindingRegistry;
 
-export declare interface RenderRoute extends RouteLifecycle {
-    render: (container: HTMLElement, route: string, params: Record<string, string>, onUnmount: (cleanupFn: () => void) => void, router: Router) => void;
-    template?: never;
-}
-
 export declare interface RouteConfig {
-    target: string;
-    default: string;
-    routes: Record<string, RouteDefinition>;
+    target: string | JQuery<HTMLElement> | HTMLElement;
+    default?: string;
+    routes?: Record<string, RouteDefinition>;
     mode?: 'hash' | 'history';
     basePath?: string;
     notFound?: string;
@@ -191,39 +197,31 @@ export declare interface RouteConfig {
     afterTransition?: (from: string, to: string) => void;
 }
 
-export declare type RouteDefinition = TemplateRoute | RenderRoute;
+export declare interface RouteDefinition extends RouteLifecycle {
+    template?: string;
+    render?: (container: HTMLElement, route: string, params: Record<string, string>, onUnmount: (cleanupFn: () => void) => void, router: Router) => void;
+    onMount?: ($content: JQuery, onUnmount: (cleanupFn: () => void) => void, router: Router) => void;
+}
 
 export declare interface RouteLifecycle {
-    onEnter?: (params: Record<string, string>, router: Router) => Record<string, string> | undefined;
+    onEnter?: (params: Record<string, string>, router: Router) => Record<string, string> | undefined | false;
     onLeave?: (router: Router) => boolean | undefined;
+    title?: string;
 }
 
 export declare interface Router {
     currentRoute: ReadonlyAtom<string>;
     queryParams: ReadonlyAtom<Record<string, string>>;
+    params: ReadonlyAtom<Record<string, string>>;
     navigate: (route: string) => void;
     destroy: () => void;
 }
 
-export declare interface TemplateRoute extends RouteLifecycle {
-    template: string;
-    render?: never;
-    onMount?: ($content: JQuery, onUnmount: (cleanupFn: () => void) => void, router: Router) => void;
-}
-
-/**
- * Options for `atomVal`, `atomChecked`, and `atomForm` bindings.
- */
 export declare interface ValOptions<T> {
-    /** Debounce duration in milliseconds for DOM -> Atom sync. Defaults to 0. */
     debounce?: number;
-    /** jQuery event name(s) to listen to. Defaults to "input". */
     event?: string;
-    /** Custom function to parse DOM string to atom type T. */
     parse?: (v: string) => T;
-    /** Custom function to format atom type T to DOM string. */
     format?: (v: T) => string;
-    /** Custom equality check to prevent redundant atom updates. */
     equal?: EqualFn<T>;
 }