@juantroconisf/lib 6.1.0 → 7.0.0

package/README.md

@@ -27,36 +27,33 @@ pnpm add @juantroconisf/lib
 import { useForm } from "@juantroconisf/lib";
 
 const MyForm = () => {
-  const { on, state, helpers } = useForm({
-    name: "Juan",
-    lines: [
-      { id: 1, amount: 10 }
-    ]
-  }, {
-    rules: {
-      name: { required: true }
+  const { on, state, helpers } = useForm(
+    {
+      name: "Juan",
+      lines: [{ id: 1, amount: 10 }],
     },
-    arrayRules: {
-      lines: {
-        amount: (item, index) => ({ min: 1 })
-      }
-    }
-  });
+    {
+      rules: {
+        name: { required: true },
+        "lines.amount": (value, state, item) => ({ min: 1 }),
+      },
+    },
+  );
 
   return (
     <form>
       {/* Scalar/Nested Registration */}
-      <Input {...on.input("name")} label="Name" />
+      <Input {...on.input("name")} label='Name' />
 
-      {/* Array Registration (By ID) */}
+      {/* Array Registration (By ID + Composite Key) */}
       {state.lines.map((line) => (
-        <Input 
-          key={line.id} 
-          {...on.input("lines", line.id, "amount")} 
-          label="Amount" 
+        <Input
+          key={line.id}
+          {...on.input("lines.amount", line.id)}
+          label='Amount'
         />
       ))}
-      
+
       <Button onClick={() => helpers.removeById("lines", 1)}>
         Remove First
       </Button>
@@ -72,26 +69,30 @@ const MyForm = () => {
 ### `useForm(initialState, options)`
 
 #### Options
-- **`rules`**: Validation rules for root/nested fields.
-- **`messages`**: Custom error messages for root/nested fields.
-- **`arrayRules`**: Validation rules for array items. Receives `(item, index)`.
-- **`arrayMessages`**: Custom error messages for array items.
-- **`arrayIdentifiers`**: Mapping of array keys to their unique ID property (defaults to `"id"`).
+
+- **`rules`**: Validation rules map. Keys can be deep paths (e.g. `user.name`, `lines.amount`). Supports functional rules `(value, state, item?, index?)`.
+- **`messages`**: Custom error messages map. Keys match rules.
+- **`arrayIdentifiers`**: Mapping of array keys (supporting dot-notation for nested arrays) to their unique ID property (defaults to `"id"`).
 
 ### The `on` Object
-Provides methods to register components with the form state. Support both scalar/nested paths and array tracking.
 
-- **`on.input(path)`** / **`on.input(arrayKey, itemId, field)`**
-- **`on.select(path)`** / **`on.select(arrayKey, itemId, field)`**
-- **`on.autocomplete(path)`** / **`on.autocomplete(arrayKey, itemId, field)`**
+Provides methods to register components with the form state. Support both scalar/nested paths and array tracking via composite keys.
+
+- **`on.input(path)`** / **`on.input(compositeKey, itemId)`** / **`on.input(arrayKey, index)`** (for primitive arrays)
+- **`on.select(path)`** / **`on.select(compositeKey, itemId)`** / **`on.select(arrayKey, index)`**
+- **`on.autocomplete(path)`** / **`on.autocomplete(compositeKey, itemId)`** / **`on.autocomplete(arrayKey, index)`**
 
 ### Helpers
+
 Utilities for common state manipulations:
+
 - **`addItem(arrayKey, item, index?)`**
 - **`removeItem(arrayKey, index)`**
 - **`removeById(arrayKey, itemId)`**
+- **`updateItem(arrayKey, index, value)`**
 - **`moveItem(arrayKey, from, to)`**
 - **`moveById(arrayKey, fromId, toId)`**
+- **`getItem(arrayKey, itemId)`**
 
 ---
 

package/dist/index.d.mts

@@ -60,7 +60,7 @@ interface FormOptions<O extends StateType> {
      * Custom property names used as unique identifiers for items in specific arrays.
      * Default is "id".
      */
-    arrayIdentifiers?: Partial<Record<ArrayKeys<O>, string>>;
+    arrayIdentifiers?: Partial<Record<ArrayPaths<O>, string>>;
 }
 type TouchedType = Map<string, boolean>;
 type ErrorsType = Map<string, NextUIError>;
@@ -72,10 +72,6 @@ interface ComponentInputProps<O extends StateType> {
     isInvalid: boolean;
     errorMessage: string;
 }
-type UXProps<O extends StateType> = Record<keyof O, {
-    isInvalid: boolean;
-    errorMessage: string;
-}>;
 /** Props returned by on.input() */
 interface ItemInputProps<V = any> extends ComponentInputProps<any> {
     onValueChange: (value: V) => void;
@@ -98,23 +94,49 @@ interface OnMethods<O extends StateType> {
     /** Registers a scalar or nested object field. */
     input<P extends AllPaths<O>>(id: P): ItemInputProps<NestedFieldValue<O, P & string>>;
     /** Registers an array element — adapts to primitive arrays (by index) or object arrays (by ID + field). */
-    input<K extends ArrayKeys<O>>(arrayKey: K, ...args: O[K] extends Record<string, any>[] ? [itemId: ItemIdType<O, K>, field: FieldPaths<ArrayElement<O[K]>>] | [itemId: ItemIdType<O, K>, field: string, index: number] : [index: number]): ItemInputProps<any>;
+    /** Registers an array element — adapts to primitive arrays (by index). */
+    input<K extends ArrayKeys<O>>(arrayKey: K, index: number): ItemInputProps<any>;
+    /** Registers an object array element's field using composite syntax "array.field". */
+    input<P extends ObjectArrayFieldPaths<O>>(compositePath: P, itemId: ItemIdType<O, GetArrayKeyFromPath<O, P>>): ItemInputProps<any>;
     /** Registers a scalar or nested object field. */
     select<P extends AllPaths<O>>(id: P): ItemSelectProps;
     /** Registers an array element — adapts to primitive arrays (by index) or object arrays (by ID + field). */
-    select<K extends ArrayKeys<O>>(arrayKey: K, ...args: O[K] extends Record<string, any>[] ? [itemId: ItemIdType<O, K>, field: FieldPaths<ArrayElement<O[K]>>] | [itemId: ItemIdType<O, K>, field: string, index: number] : [index: number]): ItemSelectProps;
+    /** Registers an array element — adapts to primitive arrays (by index). */
+    select<K extends ArrayKeys<O>>(arrayKey: K, index: number): ItemSelectProps;
+    /** Registers an object array element's field using composite syntax "array.field". */
+    select<P extends ObjectArrayFieldPaths<O>>(compositePath: P, itemId: ItemIdType<O, GetArrayKeyFromPath<O, P>>): ItemSelectProps;
     /** Registers a scalar or nested object field. */
     autocomplete<P extends AllPaths<O>>(id: P): ItemAutocompleteProps;
     /** Registers an array element — adapts to primitive arrays (by index) or object arrays (by ID + field). */
-    autocomplete<K extends ArrayKeys<O>>(arrayKey: K, ...args: O[K] extends Record<string, any>[] ? [itemId: ItemIdType<O, K>, field: FieldPaths<ArrayElement<O[K]>>] | [itemId: ItemIdType<O, K>, field: string, index: number] : [index: number]): ItemAutocompleteProps;
+    /** Registers an array element — adapts to primitive arrays (by index). */
+    autocomplete<K extends ArrayKeys<O>>(arrayKey: K, index: number): ItemAutocompleteProps;
+    /** Registers an object array element's field using composite syntax "array.field". */
+    autocomplete<P extends ObjectArrayFieldPaths<O>>(compositePath: P, itemId: ItemIdType<O, GetArrayKeyFromPath<O, P>>): ItemAutocompleteProps;
 }
 type ArrayKeys<O extends StateType> = {
     [K in keyof O]: O[K] extends any[] ? K : never;
 }[keyof O];
+/**
+ * Recursive type to find all paths to arrays in the state.
+ */
+type ArrayPaths<T> = T extends object ? {
+    [K in keyof T & string]: NonNullable<T[K]> extends (infer E)[] ? K | (E extends object ? `${K}.${ArrayPaths<E>}` : never) : NonNullable<T[K]> extends object ? NonNullable<T[K]> extends Date ? never : `${K}.${ArrayPaths<NonNullable<T[K]>>}` : never;
+}[keyof T & string] : never;
 /** Keys whose values are arrays of objects (not primitives). */
 type ObjectArrayKeys<O extends StateType> = {
     [K in keyof O]: O[K] extends Record<string, any>[] ? K : never;
 }[keyof O];
+/**
+ * Helper to get paths for fields within object arrays.
+ * Returns paths like "arrayKey.fieldName".
+ */
+type ObjectArrayFieldPaths<O extends StateType> = {
+    [K in keyof O]: O[K] extends Record<string, any>[] ? `${K & string}.${FieldPaths<ArrayElement<O[K]>>}` : never;
+}[keyof O];
+/**
+ * Helper to extract the array key from a path string like "arrayKey.field".
+ */
+type GetArrayKeyFromPath<O extends StateType, P extends string> = P extends `${infer K}.${string}` ? K extends keyof O ? O[K] extends any[] ? K : never : never : never;
 type ArrayElement<T> = T extends (infer E)[] ? E : never;
 /** Resolves the type of the identifier field for an array element (defaults to "id"). */
 type ItemIdType<O extends StateType, K extends keyof O> = "id" extends keyof ArrayElement<O[K]> ? ArrayElement<O[K]>["id"] : string | number;
@@ -179,4 +201,4 @@ interface UseFormResponse<O extends StateType> {
 
 declare function useForm<O extends StateType>(initialState: O, { rules, messages, arrayIdentifiers }?: FormOptions<O>): UseFormResponse<O>;
 
-export { type BlurFunc, type ErrorsType, type FormOptions, type HelpersFunc, type NestedChangeProps, NextUIError, type OnMethods, type StateType, type TouchedType, type UXProps, type UseFormResponse, type Validator, type ValidatorErrorMessage, type ValidatorParams, type ValidatorRule, type ValidatorTypes, type ValueChangeFunc, useForm };
+export { type BlurFunc, type ErrorsType, type FormOptions, type HelpersFunc, type NestedChangeProps, NextUIError, type OnMethods, type StateType, type TouchedType, type UseFormResponse, type Validator, type ValidatorErrorMessage, type ValidatorParams, type ValidatorRule, type ValidatorTypes, type ValueChangeFunc, useForm };

package/dist/index.d.ts

@@ -60,7 +60,7 @@ interface FormOptions<O extends StateType> {
      * Custom property names used as unique identifiers for items in specific arrays.
      * Default is "id".
      */
-    arrayIdentifiers?: Partial<Record<ArrayKeys<O>, string>>;
+    arrayIdentifiers?: Partial<Record<ArrayPaths<O>, string>>;
 }
 type TouchedType = Map<string, boolean>;
 type ErrorsType = Map<string, NextUIError>;
@@ -72,10 +72,6 @@ interface ComponentInputProps<O extends StateType> {
     isInvalid: boolean;
     errorMessage: string;
 }
-type UXProps<O extends StateType> = Record<keyof O, {
-    isInvalid: boolean;
-    errorMessage: string;
-}>;
 /** Props returned by on.input() */
 interface ItemInputProps<V = any> extends ComponentInputProps<any> {
     onValueChange: (value: V) => void;
@@ -98,23 +94,49 @@ interface OnMethods<O extends StateType> {
     /** Registers a scalar or nested object field. */
     input<P extends AllPaths<O>>(id: P): ItemInputProps<NestedFieldValue<O, P & string>>;
     /** Registers an array element — adapts to primitive arrays (by index) or object arrays (by ID + field). */
-    input<K extends ArrayKeys<O>>(arrayKey: K, ...args: O[K] extends Record<string, any>[] ? [itemId: ItemIdType<O, K>, field: FieldPaths<ArrayElement<O[K]>>] | [itemId: ItemIdType<O, K>, field: string, index: number] : [index: number]): ItemInputProps<any>;
+    /** Registers an array element — adapts to primitive arrays (by index). */
+    input<K extends ArrayKeys<O>>(arrayKey: K, index: number): ItemInputProps<any>;
+    /** Registers an object array element's field using composite syntax "array.field". */
+    input<P extends ObjectArrayFieldPaths<O>>(compositePath: P, itemId: ItemIdType<O, GetArrayKeyFromPath<O, P>>): ItemInputProps<any>;
     /** Registers a scalar or nested object field. */
     select<P extends AllPaths<O>>(id: P): ItemSelectProps;
     /** Registers an array element — adapts to primitive arrays (by index) or object arrays (by ID + field). */
-    select<K extends ArrayKeys<O>>(arrayKey: K, ...args: O[K] extends Record<string, any>[] ? [itemId: ItemIdType<O, K>, field: FieldPaths<ArrayElement<O[K]>>] | [itemId: ItemIdType<O, K>, field: string, index: number] : [index: number]): ItemSelectProps;
+    /** Registers an array element — adapts to primitive arrays (by index). */
+    select<K extends ArrayKeys<O>>(arrayKey: K, index: number): ItemSelectProps;
+    /** Registers an object array element's field using composite syntax "array.field". */
+    select<P extends ObjectArrayFieldPaths<O>>(compositePath: P, itemId: ItemIdType<O, GetArrayKeyFromPath<O, P>>): ItemSelectProps;
     /** Registers a scalar or nested object field. */
     autocomplete<P extends AllPaths<O>>(id: P): ItemAutocompleteProps;
     /** Registers an array element — adapts to primitive arrays (by index) or object arrays (by ID + field). */
-    autocomplete<K extends ArrayKeys<O>>(arrayKey: K, ...args: O[K] extends Record<string, any>[] ? [itemId: ItemIdType<O, K>, field: FieldPaths<ArrayElement<O[K]>>] | [itemId: ItemIdType<O, K>, field: string, index: number] : [index: number]): ItemAutocompleteProps;
+    /** Registers an array element — adapts to primitive arrays (by index). */
+    autocomplete<K extends ArrayKeys<O>>(arrayKey: K, index: number): ItemAutocompleteProps;
+    /** Registers an object array element's field using composite syntax "array.field". */
+    autocomplete<P extends ObjectArrayFieldPaths<O>>(compositePath: P, itemId: ItemIdType<O, GetArrayKeyFromPath<O, P>>): ItemAutocompleteProps;
 }
 type ArrayKeys<O extends StateType> = {
     [K in keyof O]: O[K] extends any[] ? K : never;
 }[keyof O];
+/**
+ * Recursive type to find all paths to arrays in the state.
+ */
+type ArrayPaths<T> = T extends object ? {
+    [K in keyof T & string]: NonNullable<T[K]> extends (infer E)[] ? K | (E extends object ? `${K}.${ArrayPaths<E>}` : never) : NonNullable<T[K]> extends object ? NonNullable<T[K]> extends Date ? never : `${K}.${ArrayPaths<NonNullable<T[K]>>}` : never;
+}[keyof T & string] : never;
 /** Keys whose values are arrays of objects (not primitives). */
 type ObjectArrayKeys<O extends StateType> = {
     [K in keyof O]: O[K] extends Record<string, any>[] ? K : never;
 }[keyof O];
+/**
+ * Helper to get paths for fields within object arrays.
+ * Returns paths like "arrayKey.fieldName".
+ */
+type ObjectArrayFieldPaths<O extends StateType> = {
+    [K in keyof O]: O[K] extends Record<string, any>[] ? `${K & string}.${FieldPaths<ArrayElement<O[K]>>}` : never;
+}[keyof O];
+/**
+ * Helper to extract the array key from a path string like "arrayKey.field".
+ */
+type GetArrayKeyFromPath<O extends StateType, P extends string> = P extends `${infer K}.${string}` ? K extends keyof O ? O[K] extends any[] ? K : never : never : never;
 type ArrayElement<T> = T extends (infer E)[] ? E : never;
 /** Resolves the type of the identifier field for an array element (defaults to "id"). */
 type ItemIdType<O extends StateType, K extends keyof O> = "id" extends keyof ArrayElement<O[K]> ? ArrayElement<O[K]>["id"] : string | number;
@@ -179,4 +201,4 @@ interface UseFormResponse<O extends StateType> {
 
 declare function useForm<O extends StateType>(initialState: O, { rules, messages, arrayIdentifiers }?: FormOptions<O>): UseFormResponse<O>;
 
-export { type BlurFunc, type ErrorsType, type FormOptions, type HelpersFunc, type NestedChangeProps, NextUIError, type OnMethods, type StateType, type TouchedType, type UXProps, type UseFormResponse, type Validator, type ValidatorErrorMessage, type ValidatorParams, type ValidatorRule, type ValidatorTypes, type ValueChangeFunc, useForm };
+export { type BlurFunc, type ErrorsType, type FormOptions, type HelpersFunc, type NestedChangeProps, NextUIError, type OnMethods, type StateType, type TouchedType, type UseFormResponse, type Validator, type ValidatorErrorMessage, type ValidatorParams, type ValidatorRule, type ValidatorTypes, type ValueChangeFunc, useForm };