@juantroconisf/lib 4.2.0 → 5.0.0

package/README.md

@@ -1,3 +1,100 @@
-# Changesets
+# @juantroconisf/lib
 
-Nothing to see here...
+A powerful, type-safe form management and validation library optimized for **HeroUI** (formerly NextUI).
+
+## Key Features
+
+- 🎯 **Polymorphic `on` API**: Single consistent interface for `input`, `select`, and `autocomplete`.
+- 🧩 **Deep Nesting**: Effortlessly manage complex objects with dot-notation support (e.g., `address.city`).
+- 🔢 **ID-Based Arrays**: Stable state management for dynamic lists. Items are tracked by unique identifiers, preventing state loss during reordering or deletions.
+- ⚡ **O(1) Performance**: Internal mapping for array items ensures lightning-fast updates regardless of list size.
+- 🛡️ **Total Type Safety**: Best-in-class Intellisense for paths, types, and array identifiers.
+- 🎨 **HeroUI Optimized**: Returns props ready to be spread directly onto HeroUI components (`isInvalid`, `errorMessage`, `onBlur`, etc.).
+
+---
+
+## Installation
+
+```bash
+pnpm add @juantroconisf/lib
+```
+
+---
+
+## Quick Start
+
+```tsx
+import { useForm } from "@juantroconisf/lib";
+
+const MyForm = () => {
+  const { on, state, helpers } = useForm({
+    name: "Juan",
+    lines: [
+      { id: 1, amount: 10 }
+    ]
+  }, {
+    rules: {
+      name: { required: true }
+    },
+    arrayRules: {
+      lines: {
+        amount: (item, index) => ({ min: 1 })
+      }
+    }
+  });
+
+  return (
+    <form>
+      {/* Scalar/Nested Registration */}
+      <Input {...on.input("name")} label="Name" />
+
+      {/* Array Registration (By ID) */}
+      {state.lines.map((line) => (
+        <Input 
+          key={line.id} 
+          {...on.input("lines", line.id, "amount")} 
+          label="Amount" 
+        />
+      ))}
+      
+      <Button onClick={() => helpers.removeById("lines", 1)}>
+        Remove First
+      </Button>
+    </form>
+  );
+};
+```
+
+---
+
+## API Reference
+
+### `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"`).
+
+### 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)`**
+
+### Helpers
+Utilities for common state manipulations:
+- **`addItem(arrayKey, item, index?)`**
+- **`removeItem(arrayKey, index)`**
+- **`removeById(arrayKey, itemId)`**
+- **`moveItem(arrayKey, from, to)`**
+- **`moveById(arrayKey, fromId, toId)`**
+
+---
+
+## License
+
+ISC © Juan T

package/dist/index.d.mts

@@ -38,20 +38,57 @@ type ValidatorErrorMessage = {
     [K in keyof ValidatorTypes]?: string;
 };
 
+/**
+ * Validation rules for individual fields in an array item.
+ * @template O The state type.
+ * @template K The key of the array in the state.
+ */
+type ArrayRules<O extends StateType, K extends keyof O = keyof O> = {
+    [F in FieldPaths<ArrayElement<O[K]>>]?: ValidatorParams | ((item: ArrayElement<O[K]>, index: number) => ValidatorParams);
+};
+/**
+ * Custom error messages for individual fields in an array item.
+ * @template O The state type.
+ * @template K The key of the array in the state.
+ */
+type ArrayMessages<O extends StateType, K extends keyof O = keyof O> = {
+    [F in FieldPaths<ArrayElement<O[K]>>]?: ValidatorErrorMessage;
+};
+/**
+ * Options for the useForm hook.
+ * @template O The state type.
+ */
 interface FormOptions<O extends StateType> {
-    validations?: {
+    /** Validation rules for top-level fields. */
+    rules?: {
         [key in keyof O]?: ValidatorParams;
     };
-    errorMessages?: {
+    /** Custom error messages for top-level fields. */
+    messages?: {
         [key in keyof O]?: ValidatorErrorMessage;
     };
+    /** Validation rules for items within arrays. */
+    arrayRules?: {
+        [K in ArrayKeys<O>]?: ArrayRules<O, K>;
+    };
+    /** Custom error messages for items within arrays. */
+    arrayMessages?: {
+        [K in ArrayKeys<O>]?: ArrayMessages<O, K>;
+    };
+    /**
+     * Custom property names used as unique identifiers for items in specific arrays.
+     * Default is "id".
+     */
+    arrayIdentifiers?: Partial<Record<ArrayKeys<O>, string>>;
+    /** General configuration for the form behavior. */
+    config?: {};
 }
 type TouchedType<O extends StateType> = Record<keyof O, boolean>;
 type ErrorsType<O extends StateType> = Record<keyof O, NextUIError>;
 type ValueChangeFunc<O extends StateType, K extends keyof O> = (id: K, value: O[K]) => void;
 type BlurFunc<O extends StateType> = (id: keyof O) => void;
 interface ComponentInputProps<O extends StateType> {
-    id: keyof O;
+    id: string;
     onBlur: () => void;
     isInvalid: boolean;
     errorMessage: string;
@@ -60,26 +97,87 @@ type UXProps<O extends StateType> = Record<keyof O, {
     isInvalid: boolean;
     errorMessage: string;
 }>;
-interface InputRegisterProps<O extends StateType, K extends keyof O, V extends unknown = string> extends ComponentInputProps<O> {
-    onValueChange: (value: O[K]) => void;
+/** Props returned by on.input() */
+interface ItemInputProps<V = any> extends ComponentInputProps<any> {
+    onValueChange: (value: V) => void;
     value: V;
 }
-interface SelectRegisterProps<O extends StateType> extends ComponentInputProps<O> {
+/** Props returned by on.select() */
+interface ItemSelectProps extends ComponentInputProps<any> {
     onSelectionChange: SelectProps["onSelectionChange"];
     selectedKeys: string[] | number[] | string | null;
 }
-interface AutocompleteRegisterProps<O extends StateType> extends ComponentInputProps<O> {
+/** Props returned by on.autocomplete() */
+interface ItemAutocompleteProps extends ComponentInputProps<any> {
     onSelectionChange: AutocompleteProps["onSelectionChange"];
     selectedKey: SingleSelection["selectedKey"];
 }
-interface RegisterFunc<O extends StateType> {
-    input: {
-        <K extends keyof O = keyof O>(id: K): InputRegisterProps<O, K, O[K]>;
-        <V, K extends keyof O = keyof O>(id: K): InputRegisterProps<O, K, V>;
-    };
-    select: (id: keyof O) => SelectRegisterProps<O>;
-    autocomplete: (id: keyof O) => AutocompleteRegisterProps<O>;
+/**
+ * Interface for the polymorphic 'on' method handlers.
+ */
+interface OnMethods<O extends StateType> {
+    /**
+     * Registers a standard or nested field for an input component.
+     */
+    input<P extends AllPaths<O>>(id: P): ItemInputProps<NestedFieldValue<O, P & string>>;
+    /**
+     * Registers an array item field for an input component using its unique ID.
+     */
+    input<K extends ArrayKeys<O>, F extends FieldPaths<ArrayElement<O[K]>>>(arrayKey: K, itemId: ItemIdType<O, K>, field: F): ItemInputProps<NestedFieldValue<ArrayElement<O[K]>, F & string>>;
+    /**
+     * Registers a standard or nested field for a select component.
+     */
+    select<P extends AllPaths<O>>(id: P): ItemSelectProps;
+    /**
+     * Registers an array item field for a select component using its unique ID.
+     */
+    select<K extends ArrayKeys<O>>(arrayKey: K, itemId: ItemIdType<O, K>, field: FieldPaths<ArrayElement<O[K]>>): ItemSelectProps;
+    /**
+     * Registers a standard or nested field for an autocomplete component.
+     */
+    autocomplete<P extends AllPaths<O>>(id: P): ItemAutocompleteProps;
+    /**
+     * Registers an array item field for an autocomplete component using its unique ID.
+     */
+    autocomplete<K extends ArrayKeys<O>>(arrayKey: K, itemId: ItemIdType<O, K>, field: FieldPaths<ArrayElement<O[K]>>): ItemAutocompleteProps;
+}
+type ArrayKeys<O extends StateType> = {
+    [K in keyof O]: O[K] extends any[] ? K : never;
+}[keyof O];
+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 ArrayKeys<O>> = "id" extends keyof ArrayElement<O[K]> ? ArrayElement<O[K]>["id"] : string | number;
+type NestedFieldValue<T, F extends string> = F extends `${infer First}.${infer Rest}` ? First extends keyof T ? NestedFieldValue<T[First], Rest> : any : F extends keyof T ? T[F] : any;
+type FieldPaths<T> = T extends Record<string, any> ? {
+    [K in keyof T & string]: T[K] extends any[] ? K : T[K] extends Record<string, any> ? `${K}.${FieldPaths<T[K]>}` : K;
+}[keyof T & string] : never;
+type NestedObjectPaths<O extends StateType> = {
+    [K in keyof O & string]: O[K] extends any[] ? never : O[K] extends Record<string, any> ? `${K}.${FieldPaths<O[K]>}` : never;
+}[keyof O & string];
+/** Keys whose values are not arrays and not plain objects (i.e. scalar/primitive fields). */
+type ScalarKeys<O extends StateType> = {
+    [K in keyof O]: O[K] extends any[] ? never : O[K] extends Record<string, any> ? never : K;
+}[keyof O];
+type AllPaths<O extends StateType> = ScalarKeys<O> | NestedObjectPaths<O>;
+/**
+ * Array helper functions.
+ */
+interface HelpersFunc<O extends StateType> {
+    /** Adds a new item to an array. */
+    addItem: <K extends ArrayKeys<O>>(arrayKey: K, item: ArrayElement<O[K]>, index?: number) => void;
+    /** Removes an item from an array by its index. */
+    removeItem: <K extends ArrayKeys<O>>(arrayKey: K, index: number) => void;
+    /** Removes an item from an array by its unique identifier. */
+    removeById: <K extends ArrayKeys<O>>(arrayKey: K, itemId: string | number) => void;
+    /** Moves an item within an array using indices. */
+    moveItem: <K extends ArrayKeys<O>>(arrayKey: K, from: number, to: number) => void;
+    /** Moves an item within an array using unique identifiers. */
+    moveById: <K extends ArrayKeys<O>>(arrayKey: K, fromId: string | number, toId: string | number) => void;
 }
+/**
+ * The response object from the useForm hook.
+ * @template O The state type.
+ */
 interface UseFormResponse<O extends StateType> {
     onBlur: BlurFunc<O>;
     onValueChange: ValueChangeFunc<O, keyof O>;
@@ -88,12 +186,19 @@ interface UseFormResponse<O extends StateType> {
     setState: React.Dispatch<React.SetStateAction<O>>;
     touched: TouchedType<O>;
     errors: ErrorsType<O>;
-    register: RegisterFunc<O>;
+    /** Main object to bind form elements to the state. */
+    on: OnMethods<O>;
+    /** Array manipulation helpers. */
+    helpers: HelpersFunc<O>;
+    isDirty: boolean;
+    /** Manually triggers all validations and marks all fields as touched. Returns true if any error is found. */
     hasInvalidValues: () => boolean;
+    /** Resets the form state and metadata. */
     resetForm: (preservedKeys?: (keyof O)[]) => void;
+    /** Resets the touched metadata. */
     resetTouched: (preservedKeys?: (keyof O)[]) => void;
 }
 
-declare function useForm<O extends StateType>(initialState: O, { validations, errorMessages }?: FormOptions<O>): UseFormResponse<O>;
+declare function useForm<O extends StateType>(initialState: O, { rules, messages, arrayRules, arrayMessages, arrayIdentifiers, config, }?: FormOptions<O>): UseFormResponse<O>;
 
-export { type BlurFunc, type ErrorsType, type FormOptions, type NestedChangeProps, NextUIError, type RegisterFunc, type StateType, type TouchedType, type UXProps, type UseFormResponse, type Validator, type ValidatorErrorMessage, type ValidatorParams, type ValidatorTypes, type ValueChangeFunc, useForm };
+export { type ArrayMessages, type ArrayRules, 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 ValidatorTypes, type ValueChangeFunc, useForm };

package/dist/index.d.ts

@@ -38,20 +38,57 @@ type ValidatorErrorMessage = {
     [K in keyof ValidatorTypes]?: string;
 };
 
+/**
+ * Validation rules for individual fields in an array item.
+ * @template O The state type.
+ * @template K The key of the array in the state.
+ */
+type ArrayRules<O extends StateType, K extends keyof O = keyof O> = {
+    [F in FieldPaths<ArrayElement<O[K]>>]?: ValidatorParams | ((item: ArrayElement<O[K]>, index: number) => ValidatorParams);
+};
+/**
+ * Custom error messages for individual fields in an array item.
+ * @template O The state type.
+ * @template K The key of the array in the state.
+ */
+type ArrayMessages<O extends StateType, K extends keyof O = keyof O> = {
+    [F in FieldPaths<ArrayElement<O[K]>>]?: ValidatorErrorMessage;
+};
+/**
+ * Options for the useForm hook.
+ * @template O The state type.
+ */
 interface FormOptions<O extends StateType> {
-    validations?: {
+    /** Validation rules for top-level fields. */
+    rules?: {
         [key in keyof O]?: ValidatorParams;
     };
-    errorMessages?: {
+    /** Custom error messages for top-level fields. */
+    messages?: {
         [key in keyof O]?: ValidatorErrorMessage;
     };
+    /** Validation rules for items within arrays. */
+    arrayRules?: {
+        [K in ArrayKeys<O>]?: ArrayRules<O, K>;
+    };
+    /** Custom error messages for items within arrays. */
+    arrayMessages?: {
+        [K in ArrayKeys<O>]?: ArrayMessages<O, K>;
+    };
+    /**
+     * Custom property names used as unique identifiers for items in specific arrays.
+     * Default is "id".
+     */
+    arrayIdentifiers?: Partial<Record<ArrayKeys<O>, string>>;
+    /** General configuration for the form behavior. */
+    config?: {};
 }
 type TouchedType<O extends StateType> = Record<keyof O, boolean>;
 type ErrorsType<O extends StateType> = Record<keyof O, NextUIError>;
 type ValueChangeFunc<O extends StateType, K extends keyof O> = (id: K, value: O[K]) => void;
 type BlurFunc<O extends StateType> = (id: keyof O) => void;
 interface ComponentInputProps<O extends StateType> {
-    id: keyof O;
+    id: string;
     onBlur: () => void;
     isInvalid: boolean;
     errorMessage: string;
@@ -60,26 +97,87 @@ type UXProps<O extends StateType> = Record<keyof O, {
     isInvalid: boolean;
     errorMessage: string;
 }>;
-interface InputRegisterProps<O extends StateType, K extends keyof O, V extends unknown = string> extends ComponentInputProps<O> {
-    onValueChange: (value: O[K]) => void;
+/** Props returned by on.input() */
+interface ItemInputProps<V = any> extends ComponentInputProps<any> {
+    onValueChange: (value: V) => void;
     value: V;
 }
-interface SelectRegisterProps<O extends StateType> extends ComponentInputProps<O> {
+/** Props returned by on.select() */
+interface ItemSelectProps extends ComponentInputProps<any> {
     onSelectionChange: SelectProps["onSelectionChange"];
     selectedKeys: string[] | number[] | string | null;
 }
-interface AutocompleteRegisterProps<O extends StateType> extends ComponentInputProps<O> {
+/** Props returned by on.autocomplete() */
+interface ItemAutocompleteProps extends ComponentInputProps<any> {
     onSelectionChange: AutocompleteProps["onSelectionChange"];
     selectedKey: SingleSelection["selectedKey"];
 }
-interface RegisterFunc<O extends StateType> {
-    input: {
-        <K extends keyof O = keyof O>(id: K): InputRegisterProps<O, K, O[K]>;
-        <V, K extends keyof O = keyof O>(id: K): InputRegisterProps<O, K, V>;
-    };
-    select: (id: keyof O) => SelectRegisterProps<O>;
-    autocomplete: (id: keyof O) => AutocompleteRegisterProps<O>;
+/**
+ * Interface for the polymorphic 'on' method handlers.
+ */
+interface OnMethods<O extends StateType> {
+    /**
+     * Registers a standard or nested field for an input component.
+     */
+    input<P extends AllPaths<O>>(id: P): ItemInputProps<NestedFieldValue<O, P & string>>;
+    /**
+     * Registers an array item field for an input component using its unique ID.
+     */
+    input<K extends ArrayKeys<O>, F extends FieldPaths<ArrayElement<O[K]>>>(arrayKey: K, itemId: ItemIdType<O, K>, field: F): ItemInputProps<NestedFieldValue<ArrayElement<O[K]>, F & string>>;
+    /**
+     * Registers a standard or nested field for a select component.
+     */
+    select<P extends AllPaths<O>>(id: P): ItemSelectProps;
+    /**
+     * Registers an array item field for a select component using its unique ID.
+     */
+    select<K extends ArrayKeys<O>>(arrayKey: K, itemId: ItemIdType<O, K>, field: FieldPaths<ArrayElement<O[K]>>): ItemSelectProps;
+    /**
+     * Registers a standard or nested field for an autocomplete component.
+     */
+    autocomplete<P extends AllPaths<O>>(id: P): ItemAutocompleteProps;
+    /**
+     * Registers an array item field for an autocomplete component using its unique ID.
+     */
+    autocomplete<K extends ArrayKeys<O>>(arrayKey: K, itemId: ItemIdType<O, K>, field: FieldPaths<ArrayElement<O[K]>>): ItemAutocompleteProps;
+}
+type ArrayKeys<O extends StateType> = {
+    [K in keyof O]: O[K] extends any[] ? K : never;
+}[keyof O];
+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 ArrayKeys<O>> = "id" extends keyof ArrayElement<O[K]> ? ArrayElement<O[K]>["id"] : string | number;
+type NestedFieldValue<T, F extends string> = F extends `${infer First}.${infer Rest}` ? First extends keyof T ? NestedFieldValue<T[First], Rest> : any : F extends keyof T ? T[F] : any;
+type FieldPaths<T> = T extends Record<string, any> ? {
+    [K in keyof T & string]: T[K] extends any[] ? K : T[K] extends Record<string, any> ? `${K}.${FieldPaths<T[K]>}` : K;
+}[keyof T & string] : never;
+type NestedObjectPaths<O extends StateType> = {
+    [K in keyof O & string]: O[K] extends any[] ? never : O[K] extends Record<string, any> ? `${K}.${FieldPaths<O[K]>}` : never;
+}[keyof O & string];
+/** Keys whose values are not arrays and not plain objects (i.e. scalar/primitive fields). */
+type ScalarKeys<O extends StateType> = {
+    [K in keyof O]: O[K] extends any[] ? never : O[K] extends Record<string, any> ? never : K;
+}[keyof O];
+type AllPaths<O extends StateType> = ScalarKeys<O> | NestedObjectPaths<O>;
+/**
+ * Array helper functions.
+ */
+interface HelpersFunc<O extends StateType> {
+    /** Adds a new item to an array. */
+    addItem: <K extends ArrayKeys<O>>(arrayKey: K, item: ArrayElement<O[K]>, index?: number) => void;
+    /** Removes an item from an array by its index. */
+    removeItem: <K extends ArrayKeys<O>>(arrayKey: K, index: number) => void;
+    /** Removes an item from an array by its unique identifier. */
+    removeById: <K extends ArrayKeys<O>>(arrayKey: K, itemId: string | number) => void;
+    /** Moves an item within an array using indices. */
+    moveItem: <K extends ArrayKeys<O>>(arrayKey: K, from: number, to: number) => void;
+    /** Moves an item within an array using unique identifiers. */
+    moveById: <K extends ArrayKeys<O>>(arrayKey: K, fromId: string | number, toId: string | number) => void;
 }
+/**
+ * The response object from the useForm hook.
+ * @template O The state type.
+ */
 interface UseFormResponse<O extends StateType> {
     onBlur: BlurFunc<O>;
     onValueChange: ValueChangeFunc<O, keyof O>;
@@ -88,12 +186,19 @@ interface UseFormResponse<O extends StateType> {
     setState: React.Dispatch<React.SetStateAction<O>>;
     touched: TouchedType<O>;
     errors: ErrorsType<O>;
-    register: RegisterFunc<O>;
+    /** Main object to bind form elements to the state. */
+    on: OnMethods<O>;
+    /** Array manipulation helpers. */
+    helpers: HelpersFunc<O>;
+    isDirty: boolean;
+    /** Manually triggers all validations and marks all fields as touched. Returns true if any error is found. */
     hasInvalidValues: () => boolean;
+    /** Resets the form state and metadata. */
     resetForm: (preservedKeys?: (keyof O)[]) => void;
+    /** Resets the touched metadata. */
     resetTouched: (preservedKeys?: (keyof O)[]) => void;
 }
 
-declare function useForm<O extends StateType>(initialState: O, { validations, errorMessages }?: FormOptions<O>): UseFormResponse<O>;
+declare function useForm<O extends StateType>(initialState: O, { rules, messages, arrayRules, arrayMessages, arrayIdentifiers, config, }?: FormOptions<O>): UseFormResponse<O>;
 
-export { type BlurFunc, type ErrorsType, type FormOptions, type NestedChangeProps, NextUIError, type RegisterFunc, type StateType, type TouchedType, type UXProps, type UseFormResponse, type Validator, type ValidatorErrorMessage, type ValidatorParams, type ValidatorTypes, type ValueChangeFunc, useForm };
+export { type ArrayMessages, type ArrayRules, 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 ValidatorTypes, type ValueChangeFunc, useForm };