@but212/atom-effect-jquery 0.31.0 → 0.32.0

package/dist/index.d.ts

@@ -1,230 +1,30 @@
-import { ComputedAtom } from '@but212/atom-effect';
-import { default as default_2 } from 'jquery';
-import { EffectObject } from '@but212/atom-effect';
-import { ReadonlyAtom } from '@but212/atom-effect';
-import { WritableAtom } from '@but212/atom-effect';
-
-/**
- * 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>;
-    class?: Record<string, AsyncReactiveValue<boolean>>;
-    css?: CssBindings;
-    attr?: Record<string, AsyncReactiveValue<PrimitiveValue>>;
-    prop?: Record<string, AsyncReactiveValue<unknown>>;
-    show?: AsyncReactiveValue<boolean>;
-    hide?: AsyncReactiveValue<boolean>;
-    val?: WritableAtom<T> | [atom: WritableAtom<T>, options: ValOptions<T>];
-    checked?: WritableAtom<boolean>;
-    form?: WritableAtom<T extends object ? T : unknown> | [
-    atom: WritableAtom<T extends object ? T : unknown>,
-    options: FormOptions<T extends object ? T : unknown>
-    ];
-    on?: Record<string, (e: JQuery.Event) => void>;
-}
-
-/**
- * Manages the lifecycle of reactive bindings and component effects.
- *
- * 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;
-    /**
-     * Performs the actual destruction of all resources bound to the node.
-     * This clears the record, removes the tracking CSS class, and executes all callbacks.
-     */
-    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>;
-
-export declare type CssValue = AsyncReactiveValue<string | number> | [source: AsyncReactiveValue<number>, unit: string];
-
-export default default_2;
-
-export declare function disableAutoCleanup(): void;
-
-/** 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 | ComponentLifecycle;
-
-/**
- * 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, xhr: JQuery.jqXHR) => T;
-    ajaxOptions?: JQuery.AjaxSettings | (() => JQuery.AjaxSettings);
-    onError?: (err: unknown) => void;
-    eager?: boolean;
-}
-
-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;
-    /** Callback triggered when a field value changes. */
-    onChange?: (path: string, value: unknown) => void;
-}
-
-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: 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;
-    onAdd?: ($el: JQuery) => void;
-    onRemove?: ($el: JQuery) => Promise<void> | void;
-    empty?: ListRenderResult;
-    events?: Record<string, (item: T, index: number, e: JQuery.TriggeredEvent) => void>;
-    isEqual?: (a: T, b: T) => boolean;
-}
-
-declare type ListRenderResult = string | Element | DocumentFragment | JQuery;
-
-/**
- * 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;
-
-/**
- * Flexible value container.
- * Supports raw T, reactive Atoms, or functional getters for deferred execution.
- */
-export declare type ReactiveValue<T> = T | ReadonlyAtom<T> | (() => T);
-
-export { ReadonlyAtom }
-
-export declare const registry: BindingRegistry;
-
-export declare interface RouteConfig {
-    target: string | JQuery<HTMLElement> | HTMLElement;
-    default?: string;
-    routes?: Record<string, RouteDefinition>;
-    mode?: 'hash' | 'history';
-    basePath?: string;
-    notFound?: string;
-    autoBindLinks?: boolean;
-    activeClass?: string;
-    beforeTransition?: (from: string, to: string) => void;
-    afterTransition?: (from: string, to: string) => void;
-}
-
-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 | 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 ValOptions<T> {
-    debounce?: number;
-    event?: string;
-    parse?: (v: string) => T;
-    format?: (v: T) => string;
-    equal?: EqualFn<T>;
-}
-
-export { WritableAtom }
-
-export { }
+import { default as $ } from 'jquery';
+import { AEJConfig } from './types';
+/**
+ * Initializes Atom-Effect jQuery with the specified configuration.
+ *
+ * This function resets the library's state according to the provided config.
+ * It is safe to call multiple times to reconfigure features at runtime.
+ *
+ * @param config - Configuration options.
+ *
+ * @warning If both `patch` and `autoCleanup` are set to `false`, you are
+ * responsible for calling `cleanup(element)` manually when
+ * elements are removed to prevent memory leaks.
+ */
+export declare function initAEJ(config?: AEJConfig): void;
+export { disablejQueryOverrides, enablejQueryOverrides } from './core/jquery-patch';
+export { disableAutoCleanup, enableAutoCleanup } from './core/registry';
+/**
+ * Performs a deep recursive cleanup on a node and its entire Shadow DOM subtrees.
+ *
+ * When to use:
+ * - Manually cleaning up an element that was removed from the DOM if autoCleanup is disabled.
+ * - Forcing a cleanup cycle on a specific container.
+ *
+ * @param element - The element to clean up.
+ */
+export declare function cleanup(element: HTMLElement | JQuery): void;
+export type { AtomComponentController, AtomNav, AtomNavOptions, BindingOptions, ComponentFn, ComputedAtom, CssBindings, CssValue, EffectCleanup, EffectResult, EqualFn, FetchError, FetchOptions, JQueryScopedSelector, ListOptions, PrimitiveValue, ReactiveValue, ReadonlyAtom, RouteConfig, RouteDefinition, RouteLifecycle, Router, ValOptions, WritableAtom, } from './types';
+export default $;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,CAAC,MAAM,QAAQ,CAAC;AAEvB,OAAO,kBAAkB,CAAC;AAC1B,OAAO,sBAAsB,CAAC;AAC9B,OAAO,iBAAiB,CAAC;AACzB,OAAO,kBAAkB,CAAC;AAC1B,OAAO,kBAAkB,CAAC;AAC1B,OAAO,kBAAkB,CAAC;AAC1B,OAAO,gBAAgB,CAAC;AACxB,OAAO,0BAA0B,CAAC;AAElC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAQzC;;;;;;;;;;;GAWG;AACH,wBAAgB,OAAO,CAAC,MAAM,GAAE,SAAc,GAAG,IAAI,CAsBpD;AASD,OAAO,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AACpF,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAExE;;;;;;;;GAQG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,GAAG,IAAI,CAM3D;AAID,YAAY,EACV,uBAAuB,EACvB,OAAO,EACP,cAAc,EACd,cAAc,EACd,WAAW,EACX,YAAY,EACZ,WAAW,EACX,QAAQ,EACR,aAAa,EACb,YAAY,EACZ,OAAO,EACP,UAAU,EACV,YAAY,EACZ,oBAAoB,EACpB,WAAW,EACX,cAAc,EACd,aAAa,EACb,YAAY,EACZ,WAAW,EACX,eAAe,EACf,cAAc,EACd,MAAM,EACN,UAAU,EACV,YAAY,GACb,MAAM,SAAS,CAAC;AAEjB,eAAe,CAAC,CAAC"}