@juantroconisf/lib 11.3.0 → 11.5.0

package/README.md

@@ -131,6 +131,16 @@ Arrays of objects are tracked by item `id` (configurable via `arrayIdentifiers`)
 </Button>;
 ```
 
+### Deeply Nested Arrays (N-Level Depth)
+
+If your schema contains arrays inside objects inside arrays (infinite depth), you can pass a variadic sequence of arguments alternating between structural paths and array IDs (or indexes).
+
+```tsx
+// Schema: items[].form_response.input_values[].value
+<Input {...on.input("items", itemId, "form_response.input_values", inputId, "value")} label="Deep Value" />
+```
+The library dynamically traverses your state, mapping IDs securely to their array indices natively, regardless of depth.
+
 ---
 
 ## The `on` API — Component Bindings
@@ -142,17 +152,17 @@ Each `on.*` method returns a set of props that you spread directly onto a HeroUI
 - **Error display** — `isInvalid` and `errorMessage` from the schema
 - **Required indicator** — `isRequired` derived from `.required()` in your schema
 
-All methods support both **scalar/nested** paths and **array item** paths (composite `"array.field"` + `itemId`).
+All methods support **scalar/nested** paths, standard **array item** paths (composite `"array.field"` + `itemId`), and **variadic sequences** for N-level deep structures.
 
 | Method                            | HeroUI Component    | Key props returned                              |
 | --------------------------------- | ------------------- | ----------------------------------------------- |
-| `on.input(path, [itemId])`        | `Input`, `Textarea` | `value: string`, `onValueChange(string)`        |
-| `on.numberInput(path, [itemId])`  | `NumberInput`       | `value: number`, `onValueChange(number)`        |
-| `on.select(path, [itemId])`       | `Select`            | `selectedKeys`, `onSelectionChange`             |
-| `on.autocomplete(path, [itemId])` | `Autocomplete`      | `selectedKey`, `onSelectionChange`              |
-| `on.checkbox(path, [itemId])`     | `Checkbox`          | `isSelected: boolean`, `onValueChange(boolean)` |
-| `on.switch(path, [itemId])`       | `Switch`            | `isSelected: boolean`, `onValueChange(boolean)` |
-| `on.radio(path, [itemId])`        | `RadioGroup`        | `value: string`, `onValueChange(string)`        |
+| `on.input(...args)`               | `Input`, `Textarea` | `value: string`, `onValueChange(string)`        |
+| `on.numberInput(...args)`         | `NumberInput`       | `value: number`, `onValueChange(number)`        |
+| `on.select(...args)`              | `Select`            | `selectedKeys`, `onSelectionChange`             |
+| `on.autocomplete(...args)`        | `Autocomplete`      | `selectedKey`, `onSelectionChange`              |
+| `on.checkbox(...args)`            | `Checkbox`          | `isSelected: boolean`, `onValueChange(boolean)` |
+| `on.switch(...args)`              | `Switch`            | `isSelected: boolean`, `onValueChange(boolean)` |
+| `on.radio(...args)`               | `RadioGroup`        | `value: string`, `onValueChange(string)`        |
 
 > **Why separate methods?** Each HeroUI component has a different prop contract (e.g. `isSelected` vs `value`, `onSelectionChange` vs `onValueChange`). Separate methods give accurate intellisense for each component.
 

package/dist/index.d.mts

@@ -133,10 +133,14 @@ interface OnMethods<O extends StateType> {
     input<P extends ObjectArrayFieldPaths<O>>(compositePath: P, itemId: string | number): ItemInputProps<any>;
     /** Registers a primitive array element by index. */
     input<K extends ArrayPaths<O>>(arrayKey: K, index: number): ItemInputProps<any>;
+    /** Registers a deeply nested field using variadic path segments. */
+    input(...args: any[]): ItemInputProps<any>;
     /** Registers a numeric field for NumberInput. */
     numberInput<P extends AllPaths<O>>(id: P): ItemNumberInputProps;
     /** Registers a numeric field within an object array element. */
     numberInput<P extends ObjectArrayFieldPaths<O>>(compositePath: P, itemId: string | number): ItemNumberInputProps;
+    /** Registers a deeply nested numeric field using variadic path segments. */
+    numberInput(...args: any[]): ItemNumberInputProps;
     /** Registers a scalar or nested object field. */
     select<P extends AllPaths<O>>(id: P): ItemSelectProps;
     /** Registers a complete array field for multi-selection. */
@@ -145,24 +149,34 @@ interface OnMethods<O extends StateType> {
     select<P extends ObjectArrayFieldPaths<O>>(compositePath: P, itemId: string | number): ItemSelectProps;
     /** Registers a primitive array element by index. */
     select<K extends ArrayPaths<O>>(arrayKey: K, index: number): ItemSelectProps;
+    /** Registers a deeply nested field using variadic path segments. */
+    select(...args: any[]): ItemSelectProps;
     /** Registers a scalar or nested object field. */
     autocomplete<P extends AllPaths<O>>(id: P): ItemAutocompleteProps;
     /** Registers an object array element's field using composite syntax "array.field". */
     autocomplete<P extends ObjectArrayFieldPaths<O>>(compositePath: P, itemId: string | number): ItemAutocompleteProps;
     /** Registers a primitive array element by index. */
     autocomplete<K extends ArrayPaths<O>>(arrayKey: K, index: number): ItemAutocompleteProps;
+    /** Registers a deeply nested field using variadic path segments. */
+    autocomplete(...args: any[]): ItemAutocompleteProps;
     /** Registers a boolean field for Checkbox. */
     checkbox<P extends AllPaths<O>>(id: P): ItemToggleProps;
     /** Registers a boolean field within an object array element for Checkbox. */
     checkbox<P extends ObjectArrayFieldPaths<O>>(compositePath: P, itemId: string | number): ItemToggleProps;
+    /** Registers a deeply nested boolean field using variadic path segments. */
+    checkbox(...args: any[]): ItemToggleProps;
     /** Registers a boolean field for Switch. */
     switch<P extends AllPaths<O>>(id: P): ItemToggleProps;
     /** Registers a boolean field within an object array element for Switch. */
     switch<P extends ObjectArrayFieldPaths<O>>(compositePath: P, itemId: string | number): ItemToggleProps;
+    /** Registers a deeply nested boolean field using variadic path segments. */
+    switch(...args: any[]): ItemToggleProps;
     /** Registers a string field for RadioGroup. */
     radio<P extends AllPaths<O>>(id: P): ItemRadioGroupProps;
     /** Registers a string field within an object array element for RadioGroup. */
     radio<P extends ObjectArrayFieldPaths<O>>(compositePath: P, itemId: string | number): ItemRadioGroupProps;
+    /** Registers a deeply nested string field using variadic path segments. */
+    radio(...args: any[]): ItemRadioGroupProps;
 }
 /**
  * Recursive type to find all paths to arrays in the state.

package/dist/index.d.ts

@@ -133,10 +133,14 @@ interface OnMethods<O extends StateType> {
     input<P extends ObjectArrayFieldPaths<O>>(compositePath: P, itemId: string | number): ItemInputProps<any>;
     /** Registers a primitive array element by index. */
     input<K extends ArrayPaths<O>>(arrayKey: K, index: number): ItemInputProps<any>;
+    /** Registers a deeply nested field using variadic path segments. */
+    input(...args: any[]): ItemInputProps<any>;
     /** Registers a numeric field for NumberInput. */
     numberInput<P extends AllPaths<O>>(id: P): ItemNumberInputProps;
     /** Registers a numeric field within an object array element. */
     numberInput<P extends ObjectArrayFieldPaths<O>>(compositePath: P, itemId: string | number): ItemNumberInputProps;
+    /** Registers a deeply nested numeric field using variadic path segments. */
+    numberInput(...args: any[]): ItemNumberInputProps;
     /** Registers a scalar or nested object field. */
     select<P extends AllPaths<O>>(id: P): ItemSelectProps;
     /** Registers a complete array field for multi-selection. */
@@ -145,24 +149,34 @@ interface OnMethods<O extends StateType> {
     select<P extends ObjectArrayFieldPaths<O>>(compositePath: P, itemId: string | number): ItemSelectProps;
     /** Registers a primitive array element by index. */
     select<K extends ArrayPaths<O>>(arrayKey: K, index: number): ItemSelectProps;
+    /** Registers a deeply nested field using variadic path segments. */
+    select(...args: any[]): ItemSelectProps;
     /** Registers a scalar or nested object field. */
     autocomplete<P extends AllPaths<O>>(id: P): ItemAutocompleteProps;
     /** Registers an object array element's field using composite syntax "array.field". */
     autocomplete<P extends ObjectArrayFieldPaths<O>>(compositePath: P, itemId: string | number): ItemAutocompleteProps;
     /** Registers a primitive array element by index. */
     autocomplete<K extends ArrayPaths<O>>(arrayKey: K, index: number): ItemAutocompleteProps;
+    /** Registers a deeply nested field using variadic path segments. */
+    autocomplete(...args: any[]): ItemAutocompleteProps;
     /** Registers a boolean field for Checkbox. */
     checkbox<P extends AllPaths<O>>(id: P): ItemToggleProps;
     /** Registers a boolean field within an object array element for Checkbox. */
     checkbox<P extends ObjectArrayFieldPaths<O>>(compositePath: P, itemId: string | number): ItemToggleProps;
+    /** Registers a deeply nested boolean field using variadic path segments. */
+    checkbox(...args: any[]): ItemToggleProps;
     /** Registers a boolean field for Switch. */
     switch<P extends AllPaths<O>>(id: P): ItemToggleProps;
     /** Registers a boolean field within an object array element for Switch. */
     switch<P extends ObjectArrayFieldPaths<O>>(compositePath: P, itemId: string | number): ItemToggleProps;
+    /** Registers a deeply nested boolean field using variadic path segments. */
+    switch(...args: any[]): ItemToggleProps;
     /** Registers a string field for RadioGroup. */
     radio<P extends AllPaths<O>>(id: P): ItemRadioGroupProps;
     /** Registers a string field within an object array element for RadioGroup. */
     radio<P extends ObjectArrayFieldPaths<O>>(compositePath: P, itemId: string | number): ItemRadioGroupProps;
+    /** Registers a deeply nested string field using variadic path segments. */
+    radio(...args: any[]): ItemRadioGroupProps;
 }
 /**
  * Recursive type to find all paths to arrays in the state.

package/dist/index.js

@@ -98,6 +98,21 @@ function removeCompositeKeysByPrefix(map, prefix) {
   }
   return result;
 }
+function setNestedValue(state, dotPath, value) {
+  const keys = dotPath.split(".");
+  const copy = { ...state };
+  let current = copy;
+  for (let i = 0; i < keys.length - 1; i++) {
+    if (Array.isArray(current[keys[i]])) {
+      current[keys[i]] = [...current[keys[i]]];
+    } else {
+      current[keys[i]] = { ...current[keys[i]] };
+    }
+    current = current[keys[i]];
+  }
+  current[keys[keys.length - 1]] = value;
+  return copy;
+}
 
 // src/hooks/useForm.tsx
 var import_react3 = require("@heroui/react");
@@ -219,7 +234,7 @@ function useComponentLanguage() {
 }
 
 // src/hooks/useForm.utils.ts
-function resolveFieldData(args, state, getIndex, getNestedValue2) {
+function resolveFieldData(args, state, getIndex, getNestedValue2, getRule, validationSchema) {
   const argCount = args.length;
   if (argCount === 1) {
     const id = args[0];
@@ -314,6 +329,49 @@ function resolveFieldData(args, state, getIndex, getNestedValue2) {
       nestedField: field
     };
   }
+  if (argCount >= 5) {
+    let current = state;
+    const compositeKeyParts = [];
+    const fieldPathParts = [];
+    const realPathParts = [];
+    let currentPath = "";
+    const parts = args.flatMap(
+      (arg) => typeof arg === "string" ? arg.split(".") : [arg]
+    );
+    for (const part of parts) {
+      let isArrayContext = Array.isArray(current);
+      if (!isArrayContext && getRule && validationSchema) {
+        const currentFieldPath = fieldPathParts.filter(Boolean).join(".");
+        const rule = getRule(currentFieldPath, validationSchema);
+        if (rule && rule.type === "array") {
+          isArrayContext = true;
+        }
+      }
+      if (isArrayContext) {
+        let indexNum = getIndex(currentPath, part);
+        if (indexNum === void 0 && typeof part === "number") {
+          indexNum = part;
+        }
+        if (indexNum === void 0) return null;
+        compositeKeyParts.push(String(part));
+        realPathParts.push(String(indexNum));
+        current = current?.[indexNum];
+      } else {
+        compositeKeyParts.push(String(part));
+        fieldPathParts.push(String(part));
+        realPathParts.push(String(part));
+        currentPath = realPathParts.join(".");
+        current = current?.[part];
+      }
+    }
+    return {
+      type: "deep" /* Deep */,
+      compositeKey: compositeKeyParts.join(".").replace(/\.\./g, "."),
+      fieldPath: fieldPathParts.filter(Boolean).join("."),
+      realPath: realPathParts.join("."),
+      value: current
+    };
+  }
   return null;
 }
 
@@ -598,6 +656,8 @@ function useForm(schema, {
           parentArr[pIndex] = pItem;
           nextState = { ...nextState, [parentKey]: parentArr };
         }
+      } else if (type === "deep" /* Deep */) {
+        nextState = setNestedValue(nextState, resolution.realPath, finalValue);
       }
       setState(nextState);
       validateField(
@@ -659,7 +719,9 @@ function useForm(schema, {
           args,
           stateRef.current,
           getIndex,
-          getNestedValue
+          getNestedValue,
+          getRule,
+          validationSchema
         );
         if (!data) return {};
         return {
@@ -673,7 +735,9 @@ function useForm(schema, {
           args,
           stateRef.current,
           getIndex,
-          getNestedValue
+          getNestedValue,
+          getRule,
+          validationSchema
         );
         if (!data) return {};
         const isArray = Array.isArray(data.value);
@@ -691,7 +755,9 @@ function useForm(schema, {
           args,
           stateRef.current,
           getIndex,
-          getNestedValue
+          getNestedValue,
+          getRule,
+          validationSchema
         );
         if (!data) return {};
         return {
@@ -708,7 +774,9 @@ function useForm(schema, {
           args,
           stateRef.current,
           getIndex,
-          getNestedValue
+          getNestedValue,
+          getRule,
+          validationSchema
         );
         if (!data) return {};
         return {
@@ -722,7 +790,9 @@ function useForm(schema, {
           args,
           stateRef.current,
           getIndex,
-          getNestedValue
+          getNestedValue,
+          getRule,
+          validationSchema
         );
         if (!data) return {};
         return {
@@ -736,7 +806,9 @@ function useForm(schema, {
           args,
           stateRef.current,
           getIndex,
-          getNestedValue
+          getNestedValue,
+          getRule,
+          validationSchema
         );
         if (!data) return {};
         return {
@@ -750,7 +822,9 @@ function useForm(schema, {
           args,
           stateRef.current,
           getIndex,
-          getNestedValue
+          getNestedValue,
+          getRule,
+          validationSchema
         );
         if (!data) return {};
         return {
@@ -760,7 +834,7 @@ function useForm(schema, {
         };
       }
     }),
-    [createHandlers, getIndex, handleFieldChange]
+    [createHandlers, getIndex, handleFieldChange, getRule, validationSchema]
   );
   const helpers = (0, import_react2.useMemo)(
     () => ({
@@ -911,7 +985,7 @@ function useForm(schema, {
       );
       if (data) handleFieldChange(data, value);
     },
-    [getIndex, handleFieldChange]
+    [getIndex, handleFieldChange, getRule, validationSchema]
   );
   const arrayItemChange = (0, import_react2.useCallback)(
     ({
@@ -927,7 +1001,7 @@ function useForm(schema, {
       );
       if (data) handleFieldChange(data, value);
     },
-    [getIndex, handleFieldChange]
+    [getIndex, handleFieldChange, getRule, validationSchema]
   );
   const scalarOnSelectionChange = (0, import_react2.useCallback)(
     (id, val) => {
@@ -958,7 +1032,7 @@ function useForm(schema, {
       );
       if (data) handleFieldChange(data, fixed);
     },
-    [getIndex, handleFieldChange]
+    [getIndex, handleFieldChange, getRule, validationSchema]
   );
   const onFormSubmit = (0, import_react2.useCallback)(
     (fn) => (e) => {

package/dist/index.mjs

@@ -72,6 +72,21 @@ function removeCompositeKeysByPrefix(map, prefix) {
   }
   return result;
 }
+function setNestedValue(state, dotPath, value) {
+  const keys = dotPath.split(".");
+  const copy = { ...state };
+  let current = copy;
+  for (let i = 0; i < keys.length - 1; i++) {
+    if (Array.isArray(current[keys[i]])) {
+      current[keys[i]] = [...current[keys[i]]];
+    } else {
+      current[keys[i]] = { ...current[keys[i]] };
+    }
+    current = current[keys[i]];
+  }
+  current[keys[keys.length - 1]] = value;
+  return copy;
+}
 
 // src/hooks/useForm.tsx
 import { Form } from "@heroui/react";
@@ -193,7 +208,7 @@ function useComponentLanguage() {
 }
 
 // src/hooks/useForm.utils.ts
-function resolveFieldData(args, state, getIndex, getNestedValue2) {
+function resolveFieldData(args, state, getIndex, getNestedValue2, getRule, validationSchema) {
   const argCount = args.length;
   if (argCount === 1) {
     const id = args[0];
@@ -288,6 +303,49 @@ function resolveFieldData(args, state, getIndex, getNestedValue2) {
       nestedField: field
     };
   }
+  if (argCount >= 5) {
+    let current = state;
+    const compositeKeyParts = [];
+    const fieldPathParts = [];
+    const realPathParts = [];
+    let currentPath = "";
+    const parts = args.flatMap(
+      (arg) => typeof arg === "string" ? arg.split(".") : [arg]
+    );
+    for (const part of parts) {
+      let isArrayContext = Array.isArray(current);
+      if (!isArrayContext && getRule && validationSchema) {
+        const currentFieldPath = fieldPathParts.filter(Boolean).join(".");
+        const rule = getRule(currentFieldPath, validationSchema);
+        if (rule && rule.type === "array") {
+          isArrayContext = true;
+        }
+      }
+      if (isArrayContext) {
+        let indexNum = getIndex(currentPath, part);
+        if (indexNum === void 0 && typeof part === "number") {
+          indexNum = part;
+        }
+        if (indexNum === void 0) return null;
+        compositeKeyParts.push(String(part));
+        realPathParts.push(String(indexNum));
+        current = current?.[indexNum];
+      } else {
+        compositeKeyParts.push(String(part));
+        fieldPathParts.push(String(part));
+        realPathParts.push(String(part));
+        currentPath = realPathParts.join(".");
+        current = current?.[part];
+      }
+    }
+    return {
+      type: "deep" /* Deep */,
+      compositeKey: compositeKeyParts.join(".").replace(/\.\./g, "."),
+      fieldPath: fieldPathParts.filter(Boolean).join("."),
+      realPath: realPathParts.join("."),
+      value: current
+    };
+  }
   return null;
 }
 
@@ -572,6 +630,8 @@ function useForm(schema, {
           parentArr[pIndex] = pItem;
           nextState = { ...nextState, [parentKey]: parentArr };
         }
+      } else if (type === "deep" /* Deep */) {
+        nextState = setNestedValue(nextState, resolution.realPath, finalValue);
       }
       setState(nextState);
       validateField(
@@ -633,7 +693,9 @@ function useForm(schema, {
           args,
           stateRef.current,
           getIndex,
-          getNestedValue
+          getNestedValue,
+          getRule,
+          validationSchema
         );
         if (!data) return {};
         return {
@@ -647,7 +709,9 @@ function useForm(schema, {
           args,
           stateRef.current,
           getIndex,
-          getNestedValue
+          getNestedValue,
+          getRule,
+          validationSchema
         );
         if (!data) return {};
         const isArray = Array.isArray(data.value);
@@ -665,7 +729,9 @@ function useForm(schema, {
           args,
           stateRef.current,
           getIndex,
-          getNestedValue
+          getNestedValue,
+          getRule,
+          validationSchema
         );
         if (!data) return {};
         return {
@@ -682,7 +748,9 @@ function useForm(schema, {
           args,
           stateRef.current,
           getIndex,
-          getNestedValue
+          getNestedValue,
+          getRule,
+          validationSchema
         );
         if (!data) return {};
         return {
@@ -696,7 +764,9 @@ function useForm(schema, {
           args,
           stateRef.current,
           getIndex,
-          getNestedValue
+          getNestedValue,
+          getRule,
+          validationSchema
         );
         if (!data) return {};
         return {
@@ -710,7 +780,9 @@ function useForm(schema, {
           args,
           stateRef.current,
           getIndex,
-          getNestedValue
+          getNestedValue,
+          getRule,
+          validationSchema
         );
         if (!data) return {};
         return {
@@ -724,7 +796,9 @@ function useForm(schema, {
           args,
           stateRef.current,
           getIndex,
-          getNestedValue
+          getNestedValue,
+          getRule,
+          validationSchema
         );
         if (!data) return {};
         return {
@@ -734,7 +808,7 @@ function useForm(schema, {
         };
       }
     }),
-    [createHandlers, getIndex, handleFieldChange]
+    [createHandlers, getIndex, handleFieldChange, getRule, validationSchema]
   );
   const helpers = useMemo(
     () => ({
@@ -885,7 +959,7 @@ function useForm(schema, {
       );
       if (data) handleFieldChange(data, value);
     },
-    [getIndex, handleFieldChange]
+    [getIndex, handleFieldChange, getRule, validationSchema]
   );
   const arrayItemChange = useCallback(
     ({
@@ -901,7 +975,7 @@ function useForm(schema, {
       );
       if (data) handleFieldChange(data, value);
     },
-    [getIndex, handleFieldChange]
+    [getIndex, handleFieldChange, getRule, validationSchema]
   );
   const scalarOnSelectionChange = useCallback(
     (id, val) => {
@@ -932,7 +1006,7 @@ function useForm(schema, {
       );
       if (data) handleFieldChange(data, fixed);
     },
-    [getIndex, handleFieldChange]
+    [getIndex, handleFieldChange, getRule, validationSchema]
   );
   const onFormSubmit = useCallback(
     (fn) => (e) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juantroconisf/lib",
-  "version": "11.3.0",
+  "version": "11.5.0",
   "description": "A form validation library for HeroUI.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",