@but212/atom-effect-jquery 0.24.1 → 0.26.0

package/dist/index.d.ts

@@ -11,8 +11,27 @@ import { ReadonlyAtom } from '@but212/atom-effect';
 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>`.
+ */
+declare type AsyncReactiveValue<T> = T | ReadonlyAtom<T | Promise<T>> | Promise<T> | (() => T | Promise<T>);
+
 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 }
 
 /**
@@ -21,21 +40,21 @@ export { batch }
  */
 export declare interface BindingOptions<T = unknown> {
     /** Binds textContent to any reactive source. */
-    text?: ReactiveValue<unknown>;
+    text?: AsyncReactiveValue<unknown>;
     /** Binds innerHTML to a reactive string source (sanitized). */
-    html?: ReactiveValue<string>;
+    html?: AsyncReactiveValue<string>;
     /** Map of class names to reactive boolean conditions. */
-    class?: Record<string, ReactiveValue<boolean>>;
+    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, ReactiveValue<PrimitiveValue>>;
+    attr?: Record<string, AsyncReactiveValue<PrimitiveValue>>;
     /** Binds DOM properties. */
-    prop?: Record<string, ReactiveValue<unknown>>;
+    prop?: Record<string, AsyncReactiveValue<unknown>>;
     /** Direct visibility control (display: none). */
-    show?: ReactiveValue<boolean>;
+    show?: AsyncReactiveValue<boolean>;
     /** Inverse visibility control. */
-    hide?: ReactiveValue<boolean>;
+    hide?: AsyncReactiveValue<boolean>;
     /**
      * Two-way binding for input values.
      * Pass an atom or a `[atom, options]` tuple.
@@ -43,6 +62,8 @@ export declare interface BindingOptions<T = unknown> {
     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>;
 }
@@ -80,6 +101,15 @@ declare class BindingRegistry {
  */
 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 { computed }
 
 export { ComputedAtom }
@@ -92,7 +122,7 @@ 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 = ReactiveValue<string | number> | [source: ReactiveValue<number>, unit: string];
+export declare type CssValue = AsyncReactiveValue<string | number> | [source: AsyncReactiveValue<number>, unit: string];
 
 export default default_2;
 
@@ -191,6 +221,16 @@ 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>>;
+
 /** Key type for Map/Set inside list.ts */
 declare type ListKey = string | number;
 
@@ -230,6 +270,12 @@ export declare interface ListOptions<T> {
 /** 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.
+ */
+declare type MaxDepth = 8;
+
 /**
  * Resolves after all pending microtask-scheduled reactive effects have flushed.
  *
@@ -249,6 +295,18 @@ declare type ListRenderResult = string | Element | DocumentFragment | JQuery;
  */
 export declare function nextTick(): Promise<void>;
 
+/**
+ * Generates a union of all valid dot-separated paths for type T.
+ */
+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.
+ */
+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.
  */
@@ -261,7 +319,7 @@ export declare type PrimitiveValue = string | number | boolean | null | undefine
  * `ComputedAtom<T>` is a structural sub-type of `ReadonlyAtom<T>`, so it is
  * already covered by `ReadonlyAtom<T>`.
  */
-export declare type ReactiveValue<T> = T | ReadonlyAtom<T>;
+export declare type ReactiveValue<T> = T | ReadonlyAtom<T> | (() => T);
 
 export { ReadonlyAtom }
 
@@ -300,6 +358,12 @@ 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.
+ */
+declare type StringKeyToNumber<S extends string> = S extends `${infer N extends number}` ? N : S;
+
 export declare interface TemplateRoute extends RouteLifecycle {
     template: string;
     render?: never;