@but212/atom-effect-jquery 0.26.0 → 0.27.0

package/dist/index.d.ts

@@ -12,8 +12,9 @@ import { untracked } from '@but212/atom-effect';
 import { WritableAtom } from '@but212/atom-effect';
 
 /**
- * Represents a value that can be a synchronous `ReactiveValue<T>`,
- * a `Promise<T>`, or an Atom yielding `T | Promise<T>`.
+ * 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).
  */
 declare type AsyncReactiveValue<T> = T | ReadonlyAtom<T | Promise<T>> | Promise<T> | (() => T | Promise<T>);
 
@@ -21,50 +22,23 @@ export { atom }
 
 /**
  * Creates a two-way "lens" for a specific property path on an object-based atom.
- * Optimized for performance using structural sharing and equality guards.
- *
- * This "fake" atom allows fine-grained binding to deep properties of a
- * monolithic state atom without extra memory or complex computed logic.
- *
- * @param atom The source atom containing the object.
- * @param path Dot-separated path to the property (e.g. 'user.profile.name').
- * @returns A WritableAtom that reads from and writes to the specified path.
  */
 export declare function atomLens<T extends object, P extends Paths<T>>(atom: WritableAtom<T>, path: P): WritableAtom<PathValue<T, P>>;
 
 export { batch }
 
-/**
- * Configuration options for `atomBind`.
- * @template T Type of the value for two-way binding (`val` field).
- */
 export declare interface BindingOptions<T = unknown> {
-    /** Binds textContent to any reactive source. */
     text?: AsyncReactiveValue<unknown>;
-    /** Binds innerHTML to a reactive string source (sanitized). */
     html?: AsyncReactiveValue<string>;
-    /** Map of class names to reactive boolean conditions. */
     class?: Record<string, AsyncReactiveValue<boolean>>;
-    /** Map of CSS properties to reactive values or [value, unit] tuples. */
     css?: CssBindings;
-    /** Binds attributes with consistent primitive constraints. */
     attr?: Record<string, AsyncReactiveValue<PrimitiveValue>>;
-    /** Binds DOM properties. */
     prop?: Record<string, AsyncReactiveValue<unknown>>;
-    /** Direct visibility control (display: none). */
     show?: AsyncReactiveValue<boolean>;
-    /** Inverse visibility control. */
     hide?: AsyncReactiveValue<boolean>;
-    /**
-     * Two-way binding for input values.
-     * Pass an atom or a `[atom, options]` tuple.
-     */
     val?: WritableAtom<T> | [atom: WritableAtom<T>, options: ValOptions<T>];
-    /** Two-way binding for checkboxes and radio buttons. */
     checked?: WritableAtom<boolean>;
-    /** Fully automated two-way form binding using name attributes. */
     form?: WritableAtom<T extends object ? T : unknown>;
-    /** Event listeners with automatic batched execution and lifecycle-bound cleanup. */
     on?: Record<string, (e: JQuery.Event) => void>;
 }
 
@@ -85,8 +59,26 @@ declare class BindingRegistry {
     markIgnored(node: Node): void;
     isIgnored(node: Node): boolean;
     private getOrCreateRecord;
+    /**
+     * 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.
+     */
     setComponentCleanup(el: Element, fn: (() => void) | undefined): void;
     hasBind(el: Element): boolean;
     cleanup(el: Element | Node): void;
@@ -94,34 +86,19 @@ declare class BindingRegistry {
     cleanupTree(el: Element | Node): void;
 }
 
-/**
- * A function that initializes logic on a jQuery element and returns an optional cleanup function.
- * `P` defaults to `Record<string, unknown>` for convenience. Use `P = Record<string, never>`
- * for strictly no-props components.
- */
 export declare type ComponentFn<P = Record<string, unknown>> = ($el: JQuery, props: P) => EffectResult;
 
 /**
  * Composes an existing lens with a sub-path to create a deeper lens.
- *
- * @param lens The parent lens.
- * @param path Sub-path relative to the parent lens.
- * @returns A new lens pointing to the deeper path.
  */
-export declare function composeLens<T extends object, P extends Paths<T>>(lens: WritableAtom<T>, path: P): WritableAtom<PathValue<T, P>>;
+export declare const composeLens: <T extends object, P extends Paths<T>>(lens: WritableAtom<T>, path: P) => WritableAtom<PathValue<T, P>>;
 
 export { computed }
 
 export { ComputedAtom }
 
-/**
- * CSS bindings map property names to CSS values.
- */
 export declare type CssBindings = Record<string, CssValue>;
 
-/**
- * CSS value: either a direct reactive value or a numeric tuple of [source, unit].
- */
 export declare type CssValue = AsyncReactiveValue<string | number> | [source: AsyncReactiveValue<number>, unit: string];
 
 export default default_2;
@@ -139,15 +116,8 @@ export declare function disablejQueryOverrides(): void;
 
 export { effect }
 
-/**
- * Cleanup function returned by effects or components.
- */
 export declare type EffectCleanup = () => void;
 
-/**
- * Result of a reactive factory or component mount.
- * Returns `void` (no cleanup) or an `EffectCleanup` function.
- */
 export declare type EffectResult = undefined | EffectCleanup;
 
 /**
@@ -162,41 +132,17 @@ export declare type EffectResult = undefined | EffectCleanup;
  */
 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> {
-    /** Initial value before the first fetch resolves. */
     defaultValue: T;
-    /** HTTP method (default: 'GET'). */
     method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS' | (string & {});
-    /** HTTP headers. */
     headers?: Record<string, string>;
-    /** Transforms the raw response into T. */
     transform?: (raw: unknown) => T;
-    /** Additional `$.ajax` settings. Can be a getter function for reactive data tracking. */
     ajaxOptions?: JQuery.AjaxSettings | (() => JQuery.AjaxSettings);
-    /** Error callback. */
     onError?: (err: unknown) => void;
-    /** Whether to fetch immediately (default: true). */
     eager?: boolean;
 }
 
@@ -204,120 +150,71 @@ 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>;
+/** Checks if a given value is a reactive node (Atom or Computed). */
+export declare const isReactive: (v: unknown) => v is ReadonlyAtom<unknown>;
 
-/**
- * Helper to extract keys of T whose values extend V.
- * Used to ensure `key` property refers to valid ID-like values.
- */
 declare type KeysOfType<T, V> = {
     [K in keyof T]: T[K] extends V ? K : never;
 }[keyof T];
 
 /**
  * Creates a lens factory bound to a specific atom.
- * Eliminates the need to pass the atom reference on every call.
- *
- * @example
- * const lens = lensFor(userAtom);
- * const email = lens('settings.notifications.email'); // WritableAtom<boolean>
  */
-export declare function lensFor<T extends object>(atom: WritableAtom<T>): <P extends Paths<T>>(path: P) => WritableAtom<PathValue<T, P>>;
+export declare const lensFor: <T extends object>(atom: WritableAtom<T>) => <P extends Paths<T>>(path: P) => WritableAtom<PathValue<T, P>>;
 
-/** Key type for Map/Set inside list.ts */
 declare type ListKey = string | number;
 
-/** Key extractor function signature. */
 declare type ListKeyFn<T> = (item: T, index: number) => ListKey;
 
-/**
- * Configuration options for `atomList`.
- */
 export declare interface ListOptions<T> {
-    /**
-     * Key to track items. Must be a property name whose value is a string|number,
-     * or a key extractor function.
-     */
     key: KeysOfType<T, ListKey> | ListKeyFn<T>;
-    /** Render function for each item. */
     render: (item: T, index: number) => ListRenderResult;
-    /** 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. */
     onRemove?: ($el: JQuery) => Promise<void> | void;
-    /** Content to show when the list is empty. */
     empty?: ListRenderResult;
-    /** Delegated event handlers attached to the container. */
     events?: Record<string, (item: T, index: number, e: JQuery.TriggeredEvent) => void>;
-    /**
-     * Custom equality checker to determine if an item has changed.
-     * Defaults to `shallowEqual`. If it returns false, the item is re-rendered (unless `update` is provided).
-     */
     isEqual?: (a: T, b: T) => boolean;
 }
 
-/** Possible return types for render() / empty */
 declare type ListRenderResult = string | Element | DocumentFragment | JQuery;
 
-/**
- * Maximum recursion depth for path generation.
- * Prevents TypeScript compiler from hitting recursion limits on deeply nested types.
- */
+/** Max recursion depth for dot-paths. */
 declare type MaxDepth = 8;
 
+/** Resolves after microtask effects flush. Fast Promise-based scheduling. */
+export declare const nextTick: () => Promise<void>;
+
 /**
- * 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.
+ * Generates a union of all possible dot-separated paths for a given type T.
  *
- * 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.
+ * Used for `atomLens` to provide IDE autocomplete and type safety when
+ * zooming into deeply nested reactive objects.
  *
- * **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>;
-
-/**
- * Generates a union of all valid dot-separated paths for type T.
+ * @example
+ * type User = { profile: { name: string } };
+ * type P = Paths<User>; // "profile" | "profile.name"
  */
 export declare type Paths<T, D extends unknown[] = []> = D['length'] extends MaxDepth ? never : T extends object ? {
     [K in keyof T & (string | number)]-?: `${K}` | (T[K] extends object ? `${K}.${Paths<T[K], [...D, 1]>}` : never);
 }[keyof T & (string | number)] : never;
 
 /**
- * Extracts the value type at path P within type T.
+ * Resolves the type of a value at a specific dot-path P within type T.
+ *
+ * Works in tandem with `Paths<T>` to ensure that lensed atoms have
+ * the correct inferred type for the member they point to.
  */
 export declare type PathValue<T, P extends string> = P extends `${infer K}.${infer Rest}` ? StringKeyToNumber<K> extends keyof T ? PathValue<T[StringKeyToNumber<K> & keyof T], Rest> : never : StringKeyToNumber<P> extends keyof T ? T[StringKeyToNumber<P> & keyof T] : never;
 
-/**
- * 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>`.
+ * 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)
  */
 export declare type ReactiveValue<T> = T | ReadonlyAtom<T> | (() => T);
 
@@ -345,7 +242,6 @@ export declare interface RouteConfig {
 
 export declare type RouteDefinition = TemplateRoute | RenderRoute;
 
-/** Shared route lifecycle hooks. */
 export declare interface RouteLifecycle {
     onEnter?: (params: Record<string, string>, router: Router) => Record<string, string> | undefined;
     onLeave?: (router: Router) => boolean | undefined;
@@ -358,10 +254,7 @@ export declare interface Router {
     destroy: () => void;
 }
 
-/**
- * Helper to convert a numeric string to a number type, otherwise returns the string.
- * Used for array indexing in paths.
- */
+/** Helper to convert numeric string to number for array indexing. */
 declare type StringKeyToNumber<S extends string> = S extends `${infer N extends number}` ? N : S;
 
 export declare interface TemplateRoute extends RouteLifecycle {
@@ -373,18 +266,18 @@ export declare interface TemplateRoute extends RouteLifecycle {
 export { untracked }
 
 /**
- * Configuration options for `atomVal`.
+ * Options for `atomVal`, `atomChecked`, and `atomForm` bindings.
  */
 export declare interface ValOptions<T> {
-    /** Delay in milliseconds before syncing DOM input to Atom. */
+    /** Debounce duration in milliseconds for DOM -> Atom sync. Defaults to 0. */
     debounce?: number;
-    /** DOM event to trigger sync (default: 'input'). */
+    /** jQuery event name(s) to listen to. Defaults to "input". */
     event?: string;
-    /** Parser to convert string input to Atom type T. */
+    /** Custom function to parse DOM string to atom type T. */
     parse?: (v: string) => T;
-    /** Formatter to convert Atom type T to string for DOM display. */
+    /** Custom function to format atom type T to DOM string. */
     format?: (v: T) => string;
-    /** Custom equality check for comparing parsed values. Defaults to Object.is. */
+    /** Custom equality check to prevent redundant atom updates. */
     equal?: EqualFn<T>;
 }