@but212/atom-effect-jquery 0.21.2 → 0.22.0

package/dist/index.d.ts

@@ -5,6 +5,8 @@ import { ComputedAtom } from '@but212/atom-effect';
 import { default as default_2 } from 'jquery';
 import { effect } from '@but212/atom-effect';
 import { EffectObject } from '@but212/atom-effect';
+import { isAtom } from '@but212/atom-effect';
+import { isComputed } from '@but212/atom-effect';
 import { ReadonlyAtom } from '@but212/atom-effect';
 import { untracked } from '@but212/atom-effect';
 import { WritableAtom } from '@but212/atom-effect';
@@ -16,40 +18,54 @@ export { batch }
 /**
  * Configuration options for `atomBind`.
  */
-export declare interface BindingOptions<T> {
-    text?: ReactiveValue<T>;
+export declare interface BindingOptions {
+    /** Binds textContent to any reactive source (usually string/number). */
+    text?: ReactiveValue<unknown>;
+    /** Binds innerHTML to a reactive string source (sanitized). */
     html?: ReactiveValue<string>;
+    /** Map of class names to reactive boolean conditions. */
     class?: Record<string, ReactiveValue<boolean>>;
+    /** Map of CSS properties to reactive values or [value, unit] tuples. */
     css?: CssBindings;
-    attr?: Record<string, ReactiveValue<string | boolean | null>>;
-    prop?: Record<string, ReactiveValue<T>>;
+    /** Binds attributes with consistent primitive constraints. */
+    attr?: Record<string, ReactiveValue<PrimitiveValue>>;
+    /** Binds DOM properties. */
+    prop?: Record<string, ReactiveValue<unknown>>;
+    /** Direct visibility control (display: none). */
     show?: ReactiveValue<boolean>;
+    /** Inverse visibility control. */
     hide?: ReactiveValue<boolean>;
-    val?: WritableAtom<T> | [atom: WritableAtom<T>, options: ValOptions<T>];
+    /**
+     * Two-way binding for input values.
+     * Pass a bare atom or a `[atom, options]` tuple to customise parse/format/debounce.
+     */
+    val?: WritableAtom<unknown> | [atom: WritableAtom<unknown>, options: ValOptions<unknown>];
+    /** Two-way binding for checkboxes and radio buttons. */
     checked?: WritableAtom<boolean>;
+    /** Event listeners with automatic batched execution and lifecycle-bound cleanup. */
     on?: Record<string, (e: JQuery.Event) => void>;
 }
 
 /**
- * Binding Registry
+ * Central registry mapping DOM elements to their reactive binding records.
  *
- * Highly optimized for performance:
- * - Uses WeakMap for zero-leak DOM associations.
- * - Minimal allocations in the tracking path.
- * - Efficient tree traversal for cleanup.
+ * 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.
  */
 declare class BindingRegistry {
     private records;
-    private boundElements;
     private preservedNodes;
     private ignoredNodes;
     keep(node: Node): void;
     isKept(node: Node): boolean;
     markIgnored(node: Node): void;
     isIgnored(node: Node): boolean;
-    private _getOrCreateRecord;
+    private getOrCreateRecord;
     trackEffect(el: Element, fx: EffectObject): void;
     trackCleanup(el: Element, fn: () => void): void;
+    setComponentCleanup(el: Element, fn: (() => void) | undefined): void;
     hasBind(el: Element): boolean;
     cleanup(el: Element): void;
     cleanupDescendants(el: Element): void;
@@ -58,8 +74,11 @@ declare class BindingRegistry {
 
 /**
  * Functional Component type.
+ * A function that initializes logic on a jQuery element and returns an optional cleanup function.
+ * `P` defaults to `object` (empty props) — use `P = Record<string, never>` for strictly no-props
+ * components.
  */
-export declare type ComponentFn<P = {}> = ($el: JQuery, props: P) => undefined | (() => void);
+export declare type ComponentFn<P = object> = ($el: JQuery, props: P) => EffectResult;
 
 export { computed }
 
@@ -68,119 +87,313 @@ export { ComputedAtom }
 /**
  * CSS bindings map property names to CSS values.
  */
-declare type CssBindings = Record<string, CssValue>;
+export declare type CssBindings = Record<string, CssValue>;
 
 /**
- * CSS value: either a direct reactive value or a tuple of [source, unit].
- * Named type provides clear bone structure for CSS binding configurations.
+ * CSS value: either a direct reactive value or a numeric tuple of [source, unit].
+ *
+ * The tuple form `[source, unit]` only accepts numeric sources because appending
+ * a unit suffix to a string value (e.g. `"100%" + "px"`) is semantically
+ * meaningless. Use `ReactiveValue<string>` directly when the full CSS value is
+ * already a string (e.g. `fontFamilyAtom`).
  */
-declare type CssValue = ReactiveValue<string | number> | [source: ReactiveValue<string | number>, unit: string];
+export declare type CssValue = ReactiveValue<string | number> | [source: ReactiveValue<number>, unit: string];
 
 export default default_2;
 
+/**
+ * Stops the MutationObserver 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.
+ */
+export declare function disablejQueryOverrides(): void;
+
 export { effect }
 
-export declare function enableAutoCleanup(root?: Element): void;
+/**
+ * Cleanup function returned by effects or components.
+ */
+export declare type EffectCleanup = () => void;
 
 /**
- * Patches jQuery methods to integrate with the reactive system.
+ * Result of a reactive factory or component mount.
+ */
+export declare type EffectResult = undefined | EffectCleanup;
+
+/**
+ * Starts observing `root` for removed elements and automatically disposes
+ * their reactive bindings when they leave the DOM.
+ *
+ * The `root` parameter is required (no default) to make the caller explicit
+ * about which subtree is being observed — `document.body` can be null if the
+ * script runs before the body is parsed.
+ *
+ * Idempotent: calling more than once with the same root before
+ * `disableAutoCleanup` has no effect. Calling with a different root while
+ * already active emits a warning and returns without re-observing.
+ */
+export declare function enableAutoCleanup(root: Element): void;
+
+/**
+ * Patches jQuery's `.on()`, `.off()`, `.remove()`, `.empty()`, and `.detach()`
+ * to integrate with the reactive system:
+ * - Event handlers are wrapped in `batch()` for efficient atom flushing.
+ * - DOM removal triggers reactive binding cleanup.
+ * - `.detach()` preserves bindings for re-attachment.
+ *
+ * Idempotent — calling more than once has no effect.
+ * Call `disablejQueryOverrides()` to restore original methods.
  */
 export declare function enablejQueryOverrides(): void;
 
+/**
+ * Generic equality predicate shared by `ValOptions` and any future consumer.
+ * Extracted as a named type to avoid duplicating the inline function signature.
+ */
+export declare type EqualFn<T> = (a: T, b: T) => boolean;
+
+/**
+ * Configuration options for `atomFetch`.
+ */
+export declare interface FetchOptions<T> {
+    /**
+     * Value exposed by the atom before the first fetch resolves.
+     * Also returned while a subsequent fetch is in flight.
+     */
+    defaultValue: T;
+    /**
+     * HTTP method forwarded to `$.ajax` (default: `'GET'`).
+     * Takes precedence over the same field in `ajaxOptions`.
+     * Accepts any string for non-standard methods; common values are
+     * auto-completed: `'GET'`, `'POST'`, `'PUT'`, `'PATCH'`, `'DELETE'`.
+     */
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS' | (string & {});
+    /**
+     * HTTP headers forwarded to `$.ajax`.
+     * Takes precedence over the same field in `ajaxOptions`.
+     */
+    headers?: Record<string, string>;
+    /**
+     * Transforms the raw `$.ajax` response into `T`.
+     *
+     * When omitted the raw response is cast to `T` with no runtime validation.
+     * Provide this function whenever the server response shape is not
+     * guaranteed to match `T` at runtime.
+     */
+    transform?: (raw: unknown) => T;
+    /**
+     * Additional `$.ajax` settings.
+     * Top-level fields (`url`, `method`, `headers`) always override the same
+     * fields here, so avoid duplicating them to prevent silent conflicts.
+     */
+    ajaxOptions?: JQuery.AjaxSettings;
+    /**
+     * Called when the fetch fails with a non-abort error.
+     * Receives the raw rejection value from `$.ajax`.
+     * Does not suppress the error — the computed atom still enters its error
+     * state and `hasError` becomes true.
+     */
+    onError?: (err: unknown) => void;
+    /**
+     * When `true` (default), the first fetch starts immediately on creation.
+     * When `false`, the fetch is deferred until `atom.value` is first accessed.
+     */
+    eager?: boolean;
+}
+
+export { isAtom }
+
+export { isComputed }
+
+/**
+ * Checks if a given value is a reactive node (Atom or Computed).
+ *
+ * `isAtom` returns `true` for both plain atoms and computed atoms because
+ * `ComputedAtomImpl` carries `ATOM_BRAND` in addition to `COMPUTED_BRAND`.
+ * A separate `isComputed` check would therefore be redundant.
+ */
+export declare function isReactive(value: unknown): value is ReadonlyAtom<unknown>;
+
 /**
  * Configuration options for `atomList`.
  */
 export declare interface ListOptions<T> {
+    /** Key to track items (property name or extractor function). */
     key: keyof T | ((item: T, index: number) => string | number);
+    /** Render function for each item. */
     render: (item: T, index: number) => string | Element | DocumentFragment | JQuery;
+    /** Optional post-render binding logic. */
     bind?: ($el: JQuery, item: T, index: number) => void;
+    /** Optional update logic when item data changes but DOM is reused. */
     update?: ($el: JQuery, item: T, index: number) => void;
+    /** Lifecycle hook: called when an element is added to the list. */
     onAdd?: ($el: JQuery) => void;
+    /** Lifecycle hook: called when an element is about to be removed. Supports async transitions. */
     onRemove?: ($el: JQuery) => Promise<void> | void;
+    /** Content to show when the list is empty. */
     empty?: string | Element | DocumentFragment | JQuery;
 }
 
 /**
- * Represents a value that can be either dynamic (Atom/Computed) or static.
+ * Resolves after all pending microtask-scheduled reactive effects have flushed.
+ *
+ * Implementation uses `setTimeout(0)` (a macrotask) which always runs after
+ * the current microtask queue is drained. This is intentional: core's
+ * scheduler enqueues effects as microtasks, so by the time the macrotask
+ * fires, all pending reactive propagation for the current turn is complete.
+ *
+ * Note: browsers may enforce a minimum 4 ms delay for nested `setTimeout`
+ * calls. For unit tests this is typically not an issue. If sub-millisecond
+ * resolution is needed, use `Promise.resolve()` directly to wait for a single
+ * microtask tick instead.
+ *
+ * **Caveats**: A single `await nextTick()` covers one reactive propagation
+ * wave. Chains of computed → effect → atom → effect may require multiple
+ * awaits — one per propagation step.
+ */
+export declare function nextTick(): Promise<void>;
+
+/**
+ * Values allowed for DOM properties and attributes.
+ */
+export declare type PrimitiveValue = string | number | boolean | null | undefined;
+
+/**
+ * Represents a value that can be either a reactive node (Atom or Computed)
+ * or a plain static value of the same type.
+ *
+ * `ComputedAtom<T>` is a structural sub-type of `ReadonlyAtom<T>`, so it is
+ * already covered by `ReadonlyAtom<T>` — listing it separately would be
+ * redundant and misleading.
  */
-declare type ReactiveValue<T> = T | ReadonlyAtom<T> | ComputedAtom<T>;
+export declare type ReactiveValue<T> = T | ReadonlyAtom<T>;
 
 export { ReadonlyAtom }
 
 export declare const registry: BindingRegistry;
 
 /**
- * Route using a custom render function.
+ * Route that renders content via a custom function.
  */
-declare interface RenderRoute extends RouteLifecycle {
-    /** Custom render function */
+export declare interface RenderRoute extends RouteLifecycle {
+    /** Custom render function providing full control over the container DOM. */
     render: (container: HTMLElement, route: string, params: Record<string, string>) => void;
     template?: never;
 }
 
 /**
- * Configuration for $.route()
+ * Configuration for `$.route()`.
  */
 export declare interface RouteConfig {
-    /** Target element selector for rendering route content */
+    /** CSS selector of the element into which route content is rendered. */
     target: string;
-    /** Default route name */
+    /** Route name used when the URL has no explicit route segment. */
     default: string;
-    /** Route definitions map */
+    /** Map of route names to their definitions. */
     routes: Record<string, RouteDefinition>;
-    /** Routing mode. 'hash' uses location.hash, 'history' uses pushState. Default: 'hash' */
+    /**
+     * Routing strategy. Default: `'hash'`.
+     * - `'hash'`    — reads/writes `location.hash` (`#routeName`).
+     * - `'history'` — reads/writes `location.pathname` via `history.pushState`.
+     */
     mode?: 'hash' | 'history';
-    /** Base path for history mode (e.g., '/app'). Ignored in hash mode. Default: '' */
+    /**
+     * Path prefix stripped from `location.pathname` in history mode.
+     * A trailing slash is normalized away internally.
+     * Has no effect in hash mode.
+     */
     basePath?: string;
-    /** Route name to use for 404/not found */
+    /** Route name to render when the requested route is not found (404 fallback). */
     notFound?: string;
-    /** Automatically bind links with data-route attribute */
+    /**
+     * When `true`, clicks on `[data-route]` elements are intercepted and
+     * handled via `navigate()` instead of triggering a full page load.
+     * Default: `false`.
+     */
     autoBindLinks?: boolean;
-    /** CSS class to add to active links */
+    /**
+     * CSS class added to `[data-route]` links that match the current route.
+     * Also sets `aria-current="page"` on the active link.
+     * Default: `'active'`.
+     */
     activeClass?: string;
-    /** Called before transitioning between routes */
+    /**
+     * Called before each route transition.
+     * `from` is `''` on the very first render (no previous route).
+     */
     beforeTransition?: (from: string, to: string) => void;
-    /** Called after transitioning between routes */
+    /**
+     * Called after each route transition completes.
+     * `from` is `''` on the very first render (no previous route).
+     */
     afterTransition?: (from: string, to: string) => void;
 }
 
 /**
  * Route definition for a single route.
- * Either template OR render must be provided, but not both.
+ * Exactly one of `template` or `render` must be provided.
+ *
+ * Use `isTemplateRoute` / `isRenderRoute` from `utils.ts` for safe narrowing
+ * instead of direct property access.
  */
 export declare type RouteDefinition = TemplateRoute | RenderRoute;
 
 /**
- * Shared route lifecycle hooks.
+ * Shared route lifecycle hooks available on every route definition.
  */
-declare interface RouteLifecycle {
-    /** Called when entering this route. Can return additional params. */
+export declare interface RouteLifecycle {
+    /**
+     * Called when entering this route. May return additional params to merge
+     * into the params object passed to `render` / `onMount`.
+     */
     onEnter?: (params: Record<string, string>) => Record<string, string> | undefined;
-    /** Called when leaving this route. Return false to prevent navigation. */
+    /**
+     * Called when leaving this route.
+     * Return `false` to block navigation; returning `void` (or nothing) allows it.
+     */
     onLeave?: () => boolean | undefined;
+    /** Called when the same route is re-activated with new query parameters. */
+    onParamsChange?: (params: Record<string, string>) => void;
 }
 
 /**
- * Router instance returned by $.route()
+ * Router instance returned by `$.route()`.
+ *
+ * `currentRoute` and `queryParams` reflect the current URL state reactively:
+ * - In `'hash'` mode, `queryParams` is parsed from the query string after `?`
+ *   in the hash fragment (e.g., `#home?page=2` → `{ page: '2' }`).
+ * - In `'history'` mode, `queryParams` is parsed from `location.search`.
  */
 export declare interface Router {
-    /** Reactive atom containing current route name */
-    currentRoute: WritableAtom<string>;
-    /** Navigate to a different route */
+    /**
+     * Reactive atom containing the current route name.
+     * Read-only — use `navigate()` to change routes so that the URL stays in sync.
+     */
+    currentRoute: ReadonlyAtom<string>;
+    /**
+     * Reactive atom containing the current query parameters as a plain object.
+     * Updated automatically on URL changes; reset to `{}` on programmatic navigation.
+     */
+    queryParams: ReadonlyAtom<Record<string, string>>;
+    /** Navigate programmatically to the named route. */
     navigate: (route: string) => void;
-    /** Cleanup and destroy the router */
+    /** Destroy the router, removing all event listeners and reactive effects. */
     destroy: () => void;
 }
 
 /**
- * Route using a template selector.
+ * Route that renders content by cloning a `<template>` element.
  */
-declare interface TemplateRoute extends RouteLifecycle {
-    /** Template selector (e.g., '#tmpl-home') */
+export declare interface TemplateRoute extends RouteLifecycle {
+    /** CSS selector for a `<template>` element (e.g., `'#tmpl-home'`). */
     template: string;
     render?: never;
+    /** Called after template content is appended to the container. */
+    onMount?: ($content: JQuery) => void;
 }
 
 export { untracked }
@@ -188,13 +401,17 @@ export { untracked }
 /**
  * Configuration options for `atomVal`.
  */
-declare interface ValOptions<T> {
+export declare interface ValOptions<T> {
+    /** Delay in milliseconds before syncing DOM input to Atom. */
     debounce?: number;
+    /** DOM event to trigger sync (default: 'input'). */
     event?: string;
+    /** Parser to convert string input to Atom type T. */
     parse?: (v: string) => T;
+    /** Formatter to convert Atom type T to string for DOM display. */
     format?: (v: T) => string;
     /** Custom equality check for comparing parsed values. Defaults to Object.is. */
-    equal?: (a: T, b: T) => boolean;
+    equal?: EqualFn<T>;
 }
 
 export { WritableAtom }