@but212/atom-effect-jquery 0.22.2 → 0.24.0

package/dist/index.d.ts

@@ -17,9 +17,10 @@ export { batch }
 
 /**
  * Configuration options for `atomBind`.
+ * @template T Type of the value for two-way binding (`val` field).
  */
-export declare interface BindingOptions {
-    /** Binds textContent to any reactive source (usually string/number). */
+export declare interface BindingOptions<T = unknown> {
+    /** Binds textContent to any reactive source. */
     text?: ReactiveValue<unknown>;
     /** Binds innerHTML to a reactive string source (sanitized). */
     html?: ReactiveValue<string>;
@@ -37,9 +38,9 @@ export declare interface BindingOptions {
     hide?: ReactiveValue<boolean>;
     /**
      * Two-way binding for input values.
-     * Pass a bare atom or a `[atom, options]` tuple to customise parse/format/debounce.
+     * Pass an atom or a `[atom, options]` tuple.
      */
-    val?: WritableAtom<unknown> | [atom: WritableAtom<unknown>, options: ValOptions<unknown>];
+    val?: WritableAtom<T> | [atom: WritableAtom<T>, options: ValOptions<T>];
     /** Two-way binding for checkboxes and radio buttons. */
     checked?: WritableAtom<boolean>;
     /** Event listeners with automatic batched execution and lifecycle-bound cleanup. */
@@ -67,18 +68,17 @@ declare class BindingRegistry {
     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;
-    cleanupTree(el: Element): void;
+    cleanup(el: Element | Node): void;
+    cleanupDescendants(el: Element | DocumentFragment | ShadowRoot): void;
+    cleanupTree(el: Element | Node): void;
 }
 
 /**
- * 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.
+ * `P` defaults to `Record<string, unknown>` for convenience. Use `P = Record<string, never>`
+ * for strictly no-props components.
  */
-export declare type ComponentFn<P = object> = ($el: JQuery, props: P) => EffectResult;
+export declare type ComponentFn<P = Record<string, unknown>> = ($el: JQuery, props: P) => EffectResult;
 
 export { computed }
 
@@ -91,18 +91,13 @@ export declare type CssBindings = Record<string, CssValue>;
 
 /**
  * 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`).
  */
 export declare type CssValue = ReactiveValue<string | number> | [source: ReactiveValue<number>, unit: string];
 
 export default default_2;
 
 /**
- * Stops the MutationObserver started by `enableAutoCleanup`.
+ * Stops all MutationObservers started by `enableAutoCleanup`.
  */
 export declare function disableAutoCleanup(): void;
 
@@ -121,6 +116,7 @@ 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;
 
@@ -128,13 +124,11 @@ export declare type EffectResult = undefined | EffectCleanup;
  * Starts observing `root` for removed elements and automatically disposes
  * their reactive bindings when they leave the DOM.
  *
+ * Multiple roots can be observed concurrently (e.g. for Micro-Frontends).
  * 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.
+ * about which subtree is being observed.
  *
- * 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.
+ * Idempotent: calling more than once with the same root has no effect.
  */
 export declare function enableAutoCleanup(root: Element): void;
 
@@ -160,48 +154,19 @@ 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.
-     */
+    /** Initial value before the first fetch resolves. */
     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'`.
-     */
+    /** HTTP method (default: 'GET'). */
     method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS' | (string & {});
-    /**
-     * HTTP headers forwarded to `$.ajax`.
-     * Takes precedence over the same field in `ajaxOptions`.
-     */
+    /** HTTP headers. */
     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.
-     */
+    /** Transforms the raw response into T. */
     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.
-     */
+    /** Additional `$.ajax` settings. Can be a getter function for reactive data tracking. */
+    ajaxOptions?: JQuery.AjaxSettings | (() => JQuery.AjaxSettings);
+    /** Error callback. */
     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.
-     */
+    /** Whether to fetch immediately (default: true). */
     eager?: boolean;
 }
 
@@ -218,26 +183,53 @@ export { isComputed }
  */
 export declare function isReactive(value: unknown): value 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];
+
+/** 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 (property name or extractor function). */
-    key: keyof T | ((item: T, index: number) => string | number);
+    /**
+     * 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) => string | Element | DocumentFragment | JQuery;
+    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. Supports async transitions. */
+    /** 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?: string | Element | DocumentFragment | JQuery;
+    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;
+
 /**
  * Resolves after all pending microtask-scheduled reactive effects have flushed.
  *
@@ -267,8 +259,7 @@ export declare type PrimitiveValue = string | number | boolean | null | undefine
  * 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.
+ * already covered by `ReadonlyAtom<T>`.
  */
 export declare type ReactiveValue<T> = T | ReadonlyAtom<T>;
 
@@ -276,124 +267,43 @@ export { ReadonlyAtom }
 
 export declare const registry: BindingRegistry;
 
-/**
- * Route that renders content via a custom 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;
+    render: (container: HTMLElement, route: string, params: Record<string, string>, onUnmount: (cleanupFn: () => void) => void, router: Router) => void;
     template?: never;
 }
 
-/**
- * Configuration for `$.route()`.
- */
 export declare interface RouteConfig {
-    /** CSS selector of the element into which route content is rendered. */
     target: string;
-    /** Route name used when the URL has no explicit route segment. */
     default: string;
-    /** Map of route names to their definitions. */
     routes: Record<string, RouteDefinition>;
-    /**
-     * Routing strategy. Default: `'hash'`.
-     * - `'hash'`    — reads/writes `location.hash` (`#routeName`).
-     * - `'history'` — reads/writes `location.pathname` via `history.pushState`.
-     */
     mode?: 'hash' | 'history';
-    /**
-     * 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 render when the requested route is not found (404 fallback). */
     notFound?: string;
-    /**
-     * 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 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 each route transition.
-     * `from` is `''` on the very first render (no previous route).
-     */
     beforeTransition?: (from: string, to: string) => void;
-    /**
-     * 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.
- * 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 available on every route definition.
- */
+/** Shared route lifecycle hooks. */
 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 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;
+    onEnter?: (params: Record<string, string>, router: Router) => Record<string, string> | undefined;
+    onLeave?: (router: Router) => boolean | undefined;
 }
 
-/**
- * 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 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;
-    /** Destroy the router, removing all event listeners and reactive effects. */
     destroy: () => void;
 }
 
-/**
- * Route that renders content by cloning a `<template>` element.
- */
 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;
+    onMount?: ($content: JQuery, onUnmount: (cleanupFn: () => void) => void, router: Router) => void;
 }
 
 export { untracked }