@rilaykit/forms 3.0.0 → 5.0.0

package/dist/index.d.mts

@@ -1,124 +1,536 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { ril, ValidationConfig, ConditionalConfig, FormFieldConfig, FormFieldRow, FormConfiguration, RendererChildrenFunction, FormBodyRendererProps, ValidationError, ValidationResult, FormRowRendererProps, FormSubmitButtonRendererProps } from '@rilaykit/core';
+import { ril, FieldValidationConfig, FormFieldConfig, FormFieldRow, FormValidationConfig, FormValidator, FormConfiguration, ComponentRendererBaseProps, FormBodyRendererProps, ValidationError, ValidationResult, FormRowRendererProps, FormSubmitButtonRendererProps } from '@rilaykit/core';
 export * from '@rilaykit/core';
-export { createZodValidator, ril } from '@rilaykit/core';
-import * as React$1 from 'react';
-import React__default from 'react';
+import React$1 from 'react';
 
+/**
+ * Configuration for a form field with type safety
+ *
+ * @template C - The component configuration map
+ * @template T - The specific component type key
+ *
+ * @example
+ * ```typescript
+ * const fieldConfig: FieldConfig<MyComponents, 'text'> = {
+ *   type: 'text',
+ *   props: { placeholder: 'Enter your name' },
+ *   validation: {
+ *     validators: [required(), minLength(2)],
+ *     validateOnChange: true,
+ *     validateOnBlur: true
+ *   }
+ * };
+ * ```
+ */
 type FieldConfig<C extends Record<string, any>, T extends keyof C> = {
-    id: string;
+    /** Unique identifier for the field. Auto-generated if not provided */
+    id?: string;
+    /** Component type from the registered components */
     type: T;
+    /** Component-specific properties */
     props?: Partial<C[T]>;
-    validation?: ValidationConfig;
-    conditional?: ConditionalConfig;
+    /** Validation configuration for this field */
+    validation?: FieldValidationConfig;
 };
-interface RowOptions {
-    spacing?: 'tight' | 'normal' | 'loose';
-    alignment?: 'start' | 'center' | 'end' | 'stretch';
-}
 /**
- * Form builder class for creating form configurations
- * Simplified API with matrix support and auto-build capability
+ * Form builder class for creating type-safe form configurations
+ *
+ * This class provides a fluent API for building forms with automatic validation,
+ * type safety, and flexible layout options. It manages field registration,
+ * row organization, and form configuration generation.
+ *
+ * @template C - Component configuration map defining available component types
+ *
+ * @example
+ * ```typescript
+ * // Create a form builder with typed components
+ * const formBuilder = form.create(rilConfig, 'user-registration')
+ *   .add({ type: 'text', props: { label: 'Name' } })
+ *   .add(
+ *     { type: 'email', props: { label: 'Email' } },
+ *     { type: 'password', props: { label: 'Password' } }
+ *   )
+ *   .build();
+ * ```
+ *
+ * @remarks
+ * - Supports up to 3 fields per row for optimal layout
+ * - Automatically generates unique IDs for fields and rows
+ * - Maintains type safety throughout the building process
  */
 declare class form<C extends Record<string, any> = Record<string, never>> {
+    /** The ril configuration instance containing component definitions */
     private config;
+    /** Array of form rows containing field configurations */
     private rows;
+    /** Unique identifier for this form */
     private formId;
-    private rowCounter;
+    /** Generator for creating unique IDs */
+    private idGenerator;
+    /** Form-level validation configuration */
+    private formValidation?;
+    /**
+     * Creates a new form builder instance
+     *
+     * @param config - The ril configuration containing component definitions
+     * @param formId - Optional unique identifier for the form. Auto-generated if not provided
+     *
+     * @example
+     * ```typescript
+     * const builder = new form(rilConfig, 'my-form');
+     * ```
+     */
     constructor(config: ril<C>, formId?: string);
+    /**
+     * Static factory method to create a new form builder
+     *
+     * @template Cm - Component configuration map
+     * @param config - The ril configuration instance
+     * @param formId - Optional form identifier
+     * @returns A new form builder instance
+     *
+     * @example
+     * ```typescript
+     * const builder = form.create(rilConfig, 'registration-form');
+     * ```
+     */
     static create<Cm extends Record<string, any> = Record<string, never>>(config: ril<Cm>, formId?: string): form<Cm>;
     /**
-     * Helper method to create a FormFieldConfig from a FieldConfig
+     * Converts a FieldConfig to a FormFieldConfig
+     *
+     * This internal method handles the transformation from the builder's field
+     * configuration format to the final form field configuration, including
+     * component lookup, prop merging, ID generation, and validation setup.
+     *
+     * The validation system combines component-level validation (defined in the component config)
+     * with field-level validation (defined in the field config). Component validators are
+     * applied first, followed by field validators.
+     *
+     * @template T - The component type
+     * @param fieldConfig - The field configuration to convert
+     * @returns A complete FormFieldConfig ready for use
+     * @throws Error if the specified component type is not registered
+     *
+     * @internal
      */
     private createFormField;
     /**
-     * Helper method to create a row with validation
+     * Creates a form row with the specified fields and options
+     *
+     * This internal method handles row creation,
+     * proper spacing, and alignment configuration.
+     *
+     * @template T - The component type
+     * @param fieldConfigs - Array of field configurations for the row
+     * @param rowOptions - Optional row layout configuration
+     * @returns A complete FormFieldRow configuration
+     * @throws Error if no fields provided or more than 3 fields specified
+     *
+     * @internal
      */
     private createRow;
     /**
-     * Add a single field using simplified FieldConfig object
+     * Universal method for adding fields to the form
+     *
+     * This is the primary method for adding fields to your form. It supports multiple
+     * usage patterns for maximum flexibility:
+     *
+     * - Single field: Creates a new row with one field
+     * - Multiple fields (≤3): Creates one row with all fields
+     * - Multiple fields (>3): Creates separate rows for each field
+     * - Array with options: Explicit control over row configuration
+     *
+     * @template T - The component type
+     * @param fields - Field configurations (variadic or array)
+     * @returns The form builder instance for method chaining
+     * @throws Error if no fields provided or invalid configuration
+     *
+     * @example
+     * ```typescript
+     * // Single field on its own row
+     * builder.add({ type: 'text', props: { label: 'Name' } });
+     *
+     * // Multiple fields on same row (max 3)
+     * builder.add(
+     *   { type: 'text', props: { label: 'First Name' } },
+     *   { type: 'text', props: { label: 'Last Name' } }
+     * );
+     *
+     * // Array syntax with row options
+     * builder.add([
+     *   { type: 'email', props: { label: 'Email' } },
+     *   { type: 'phone', props: { label: 'Phone' } }
+     * ], { spacing: 'loose', alignment: 'center' });
+     * ```
      */
-    addField<T extends keyof C & string>(fieldConfig: FieldConfig<C, T> & {
-        type: keyof C;
-    }): this;
+    add<T extends keyof C & string>(...fields: FieldConfig<C, T>[]): this;
+    add<T extends keyof C & string>(fields: FieldConfig<C, T>[]): this;
     /**
-     * Add multiple fields on the same row (max 3 fields)
+     * Adds multiple fields on separate rows
+     *
+     * This method is useful when you want to ensure each field gets its own row,
+     * regardless of the number of fields. It's an alternative to the add() method
+     * when you need explicit control over row separation.
+     *
+     * @template T - The component type
+     * @param fieldConfigs - Array of field configurations
+     * @param rowOptions - Optional row layout configuration applied to all rows
+     * @returns The form builder instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * // Each field will be on its own row
+     * builder.addSeparateRows([
+     *   { type: 'text', props: { label: 'Field 1' } },
+     *   { type: 'text', props: { label: 'Field 2' } },
+     *   { type: 'text', props: { label: 'Field 3' } }
+     * ]);
+     * ```
      */
-    addRowFields<T extends keyof C & string>(fieldConfigs: FieldConfig<C, T>[], rowOptions?: RowOptions): this;
+    addSeparateRows<T extends keyof C & string>(fieldConfigs: FieldConfig<C, T>[]): this;
     /**
-     * Add multiple fields, each on its own row
-     */
-    addFields<T extends keyof C & string>(fieldConfigs: FieldConfig<C, T>[]): this;
-    /**
-     * Set form ID
+     * Sets the form identifier
+     *
+     * @param id - The new form identifier
+     * @returns The form builder instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * builder.setId('user-profile-form');
+     * ```
      */
     setId(id: string): this;
     /**
-     * Update field configuration
+     * Updates an existing field's configuration
+     *
+     * This method allows you to modify field properties after the field has been added to the form.
+     *
+     * @param fieldId - The unique identifier of the field to update
+     * @param updates - Partial field configuration with updates to apply
+     * @returns The form builder instance for method chaining
+     * @throws Error if the field with the specified ID is not found
+     *
+     * @example
+     * ```typescript
+     * builder.updateField('email-field', {
+     *   props: { placeholder: 'Enter your email address' },
+     * });
+     * ```
      */
     updateField(fieldId: string, updates: Partial<Omit<FormFieldConfig, 'id'>>): this;
     /**
-     * Helper method to find a field by ID
+     * Finds a field by its unique identifier
+     *
+     * This internal method searches through all rows to locate a field
+     * with the specified ID.
+     *
+     * @param fieldId - The field identifier to search for
+     * @returns The field configuration if found, null otherwise
+     *
+     * @internal
      */
     private findField;
     /**
-     * Remove a field from the form
+     * Removes a field from the form
+     *
+     * This method removes the specified field and cleans up any empty rows
+     * that result from the removal. The form structure is automatically
+     * reorganized to maintain consistency.
+     *
+     * @param fieldId - The unique identifier of the field to remove
+     * @returns The form builder instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * builder.removeField('unwanted-field-id');
+     * ```
      */
     removeField(fieldId: string): this;
     /**
-     * Get field configuration by ID
+     * Retrieves a field configuration by its ID
+     *
+     * @param fieldId - The unique identifier of the field
+     * @returns The field configuration if found, undefined otherwise
+     *
+     * @example
+     * ```typescript
+     * const emailField = builder.getField('email-field');
+     * if (emailField) {
+     *   console.log('Email field props:', emailField.props);
+     * }
+     * ```
      */
     getField(fieldId: string): FormFieldConfig | undefined;
     /**
-     * Get all fields as a flat array
+     * Gets all fields as a flat array
+     *
+     * This method flattens the row structure to provide a simple array
+     * of all field configurations in the form, maintaining their order.
+     *
+     * @returns Array of all field configurations in the form
+     *
+     * @example
+     * ```typescript
+     * const allFields = builder.getFields();
+     * console.log(`Form has ${allFields.length} fields`);
+     * ```
      */
     getFields(): FormFieldConfig[];
     /**
-     * Get all rows
+     * Gets all rows in the form
+     *
+     * Returns a copy of the internal rows array to prevent external
+     * modification while allowing inspection of the form structure.
+     *
+     * @returns Array of all form rows
+     *
+     * @example
+     * ```typescript
+     * const rows = builder.getRows();
+     * console.log(`Form has ${rows.length} rows`);
+     * ```
      */
     getRows(): FormFieldRow[];
     /**
-     * Clear all fields and rows
+     * Clears all fields and rows from the form
+     *
+     * This method resets the form to an empty state and resets the ID generator
+     * to ensure clean ID generation for subsequent fields.
+     *
+     * @returns The form builder instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * builder.clear().add({ type: 'text', props: { label: 'New start' } });
+     * ```
      */
     clear(): this;
     /**
-     * Clone the current form builder
+     * Configures validation for the entire form
+     *
+     * This method sets up form-level validation that will be applied when the
+     * form is submitted or when validation is explicitly triggered. Form validators
+     * receive all form data and can perform cross-field validation.
+     *
+     * @param validationConfig - Form validation configuration
+     * @returns The form builder instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * builder.setValidation({
+     *   validators: [
+     *     (formData, context) => {
+     *       if (!formData.email && !formData.phone) {
+     *         return createErrorResult('Either email or phone is required');
+     *       }
+     *       return createSuccessResult();
+     *     }
+     *   ],
+     *   validateOnSubmit: true
+     * });
+     * ```
+     */
+    setValidation(validationConfig: FormValidationConfig): this;
+    /**
+     * Adds validators to the form-level validation
+     *
+     * This method allows adding validators to an existing validation configuration
+     * without replacing the entire configuration.
+     *
+     * @param validators - Array of form validators to add
+     * @returns The form builder instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * builder.addValidators([
+     *   customFormValidator,
+     *   anotherFormValidator
+     * ]);
+     * ```
+     */
+    addValidators(validators: FormValidator[]): this;
+    /**
+     * Adds validation to a specific field by ID
+     *
+     * This method allows adding validation to a field after it has been created,
+     * useful for dynamic validation requirements.
+     *
+     * @param fieldId - The ID of the field to add validation to
+     * @param validationConfig - Field validation configuration
+     * @returns The form builder instance for method chaining
+     * @throws Error if the field with the specified ID is not found
+     *
+     * @example
+     * ```typescript
+     * builder.addFieldValidation('email', {
+     *   validators: [required(), email()],
+     *   validateOnBlur: true
+     * });
+     * ```
+     */
+    addFieldValidation(fieldId: string, validationConfig: FieldValidationConfig): this;
+    /**
+     * Creates a deep copy of the current form builder
+     *
+     * This method creates a completely independent copy of the form builder,
+     * including all field configurations and internal state. The cloned
+     * builder can be modified without affecting the original.
+     *
+     * @param newFormId - Optional new form ID for the clone
+     * @returns A new form builder instance with copied configuration
+     *
+     * @example
+     * ```typescript
+     * const originalForm = builder.clone();
+     * const modifiedForm = builder.clone('modified-form')
+     *   .add({ type: 'text', props: { label: 'Additional field' } });
+     * ```
      */
     clone(newFormId?: string): form<C>;
     /**
-     * Validate the form configuration
+     * Checks the current form configuration for basic structural issues.
+     *
+     * @returns Array of error messages (empty if valid)
      */
     validate(): string[];
     /**
-     * Build the final form configuration with matrix support
+     * Builds the final form configuration
+     *
+     * This method creates the complete form
+     * configuration object ready for rendering. It includes all field
+     * configurations, render settings, validation configuration, and metadata.
+     *
+     * @returns Complete form configuration ready for use
+     *
+     * @example
+     * ```typescript
+     * const formConfig = builder.build();
+     * // Use formConfig with your form renderer
+     * ```
+     *
+     * @remarks
+     * The returned configuration includes:
+     * - Form ID and metadata
+     * - All rows with their field configurations
+     * - Flattened array of all fields for easy access
+     * - Component configuration reference
+     * - Render configuration for customization
+     * - Form-level validation configuration
      */
     build(): FormConfiguration;
     /**
-     * Export form configuration as JSON
+     * Exports the form configuration as JSON
+     *
+     * This method serializes the form configuration to a plain JavaScript
+     * object suitable for storage, transmission, or debugging.
+     *
+     * @returns Plain object representation of the form
+     *
+     * @example
+     * ```typescript
+     * const formJson = builder.toJSON();
+     * localStorage.setItem('savedForm', JSON.stringify(formJson));
+     * ```
      */
     toJSON(): any;
     /**
-     * Import form configuration from JSON
+     * Imports form configuration from JSON
+     *
+     * This method restores form state from a previously exported JSON
+     * configuration. It's useful for loading saved forms or restoring
+     * form state from external sources.
+     *
+     * @param json - The JSON object containing form configuration
+     * @returns The form builder instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * const savedForm = JSON.parse(localStorage.getItem('savedForm'));
+     * builder.fromJSON(savedForm);
+     * ```
+     *
+     * @remarks
+     * - Only imports basic form structure (ID and rows)
+     * - Does not validate imported configuration
+     * - Existing form content is replaced
      */
     fromJSON(json: any): this;
     /**
-     * Get form statistics
+     * Gets comprehensive statistics about the form
+     *
+     * This method provides useful metrics about the form structure,
+     * helpful for analytics, debugging, or UI display purposes.
+     *
+     * @returns Object containing form statistics
+     *
+     * @example
+     * ```typescript
+     * const stats = builder.getStats();
+     * console.log(`Form has ${stats.totalFields} fields in ${stats.totalRows} rows`);
+     * console.log(`Average fields per row: ${stats.averageFieldsPerRow.toFixed(1)}`);
+     * ```
+     *
+     * @remarks
+     * Statistics include:
+     * - Total number of fields and rows
+     * - Average fields per row
+     * - Maximum and minimum fields in any row
+     * - Useful for form complexity analysis
      */
     getStats(): {
+        /** Total number of fields across all rows */
         totalFields: number;
+        /** Total number of rows in the form */
         totalRows: number;
+        /** Average number of fields per row */
         averageFieldsPerRow: number;
+        /** Maximum number of fields in any single row */
         maxFieldsInRow: number;
+        /** Minimum number of fields in any single row */
         minFieldsInRow: number;
     };
 }
 /**
  * Factory function to create a form builder directly
+ *
+ * This is a convenience function that provides an alternative to using
+ * the class constructor or static create method. It's particularly useful
+ * for functional programming styles or when you prefer function calls
+ * over class instantiation.
+ *
+ * @template C - Component configuration map
+ * @param config - The ril configuration instance
+ * @param formId - Optional form identifier
+ * @returns A new form builder instance
+ *
+ * @example
+ * ```typescript
+ * const builder = createForm(rilConfig, 'contact-form')
+ *   .add({ type: 'text', props: { label: 'Name' } })
+ *   .add({ type: 'email', props: { label: 'Email' } });
+ * ```
  */
 declare function createForm<C extends Record<string, any>>(config: ril<C>, formId?: string): form<C>;
+/**
+ * Module augmentation to add createForm method to ril instances
+ *
+ * This declaration extends the ril interface to include the createForm
+ * method, allowing for a more integrated API experience.
+ */
 declare module '@rilaykit/core' {
     interface ril<C extends Record<string, any> = Record<string, never>> {
-        createForm(formId?: string): form<C>;
+        /**
+         * Creates a new form builder using this ril configuration
+         *
+         * @param formId - Optional form identifier
+         * @returns A new form builder instance
+         *
+         * @example
+         * ```typescript
+         * const builder = rilConfig.createForm('my-form');
+         * ```
+         */
+        form(formId?: string): form<C>;
     }
 }
 
@@ -132,12 +544,7 @@ interface FormProps {
 }
 declare function Form({ formConfig, defaultValues, onSubmit, onFieldChange, children }: FormProps): react_jsx_runtime.JSX.Element;
 
-interface FormBodyProps {
-    className?: string;
-    children?: React.ReactNode | RendererChildrenFunction<FormBodyRendererProps>;
-    renderAs?: 'default' | 'children' | boolean;
-}
-declare function FormBody({ className, children, renderAs }: FormBodyProps): string | number | boolean | React$1.ReactElement<any, string | React$1.JSXElementConstructor<any>> | Iterable<React$1.ReactNode> | null | undefined;
+declare function FormBody({ className, ...props }: ComponentRendererBaseProps<FormBodyRendererProps>): react_jsx_runtime.JSX.Element;
 
 interface FormFieldProps {
     fieldId: string;
@@ -145,32 +552,32 @@ interface FormFieldProps {
     customProps?: Record<string, any>;
     className?: string;
 }
-declare function FormField({ fieldId, disabled, customProps, className, }: FormFieldProps): react_jsx_runtime.JSX.Element | null;
+declare function FormField({ fieldId, disabled, customProps, className, }: FormFieldProps): react_jsx_runtime.JSX.Element;
 
 interface FormState {
     values: Record<string, any>;
     errors: Record<string, ValidationError[]>;
-    touched: Set<string>;
-    isValidating: Set<string>;
+    validationState: Record<string, 'idle' | 'validating' | 'valid' | 'invalid'>;
+    touched: Record<string, boolean>;
     isDirty: boolean;
-    isValid: boolean;
     isSubmitting: boolean;
+    isValid: boolean;
 }
 interface FormContextValue {
     formState: FormState;
     formConfig: FormConfiguration;
     setValue: (fieldId: string, value: any) => void;
-    setError: (fieldId: string, errors: ValidationError[]) => void;
-    clearError: (fieldId: string) => void;
-    markFieldTouched: (fieldId: string) => void;
-    setFieldValidating: (fieldId: string, isValidating: boolean) => void;
+    setFieldTouched: (fieldId: string, touched?: boolean) => void;
     validateField: (fieldId: string, value?: any) => Promise<ValidationResult>;
-    validateAllFields: () => Promise<boolean>;
+    validateForm: () => Promise<ValidationResult>;
+    isFormValid: () => boolean;
     reset: (values?: Record<string, any>) => void;
-    submit: (event?: React__default.FormEvent) => Promise<boolean>;
+    submit: (event?: React$1.FormEvent) => Promise<boolean>;
+    setError: (fieldId: string, errors: ValidationError[]) => void;
+    clearError: (fieldId: string) => void;
 }
 interface FormProviderProps {
-    children: React__default.ReactNode;
+    children: React$1.ReactNode;
     formConfig: FormConfiguration;
     defaultValues?: Record<string, any>;
     onSubmit?: (data: Record<string, any>) => void | Promise<void>;
@@ -180,19 +587,11 @@ interface FormProviderProps {
 declare function FormProvider({ children, formConfig, defaultValues, onSubmit, onFieldChange, className, }: FormProviderProps): react_jsx_runtime.JSX.Element;
 declare function useFormContext(): FormContextValue;
 
-interface FormRowProps {
+interface FormRowProps extends ComponentRendererBaseProps<FormRowRendererProps> {
     row: FormFieldRow;
-    className?: string;
-    children?: React.ReactNode | RendererChildrenFunction<FormRowRendererProps>;
-    renderAs?: 'default' | 'children' | boolean;
 }
-declare function FormRow({ row, className, children, renderAs }: FormRowProps): string | number | boolean | React$1.ReactElement<any, string | React$1.JSXElementConstructor<any>> | Iterable<React$1.ReactNode> | null | undefined;
+declare function FormRow({ row, className, ...props }: FormRowProps): react_jsx_runtime.JSX.Element;
 
-interface FormSubmitButtonProps {
-    className?: string;
-    children?: React__default.ReactNode | RendererChildrenFunction<FormSubmitButtonRendererProps>;
-    renderAs?: 'default' | 'children' | boolean;
-}
-declare function FormSubmitButton({ className, children, renderAs }: FormSubmitButtonProps): string | number | boolean | React__default.ReactElement<any, string | React__default.JSXElementConstructor<any>> | Iterable<React__default.ReactNode> | null | undefined;
+declare function FormSubmitButton({ className, ...props }: ComponentRendererBaseProps<FormSubmitButtonRendererProps>): react_jsx_runtime.JSX.Element;
 
-export { type FieldConfig, Form, FormBody, type FormBodyProps, form as FormBuilder, type FormContextValue, FormField, type FormFieldProps, type FormProps, FormProvider, type FormProviderProps, FormRow, type FormRowProps, type FormState, FormSubmitButton, type FormSubmitButtonProps, createForm, form, useFormContext };
+export { type FieldConfig, Form, FormBody, form as FormBuilder, FormField, FormProvider, FormRow, FormSubmitButton, createForm, form, useFormContext };