@rilaykit/forms 0.1.1-alpha.1 → 0.1.2

package/dist/index.d.mts

@@ -1,210 +1,1040 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { FormConfiguration, ValidationError, ValidationResult, FormFieldRow, ril, InputType, LayoutType, ValidationConfig, ConditionalConfig, FormFieldConfig } from '@rilaykit/core';
-export * from '@rilaykit/core';
-export { createZodValidator, ril } from '@rilaykit/core';
+import { ril, FieldValidationConfig, RepeatableFieldConfig, ConditionalBehavior, FormFieldConfig, FormRowEntry, FormValidationConfig, FormConfiguration, ComponentRendererBaseProps, FormBodyRendererProps, FieldConditions, FormState, ValidationError, ValidationState, FieldState, ValidationResult, RepeatableFieldItem, MonitoringConfig, FormPerformanceMetrics, FormRowRendererProps, FormFieldRow, FormSubmitButtonRendererProps } from '@rilaykit/core';
 import * as React$1 from 'react';
 import React__default from 'react';
+import * as zustand from 'zustand';
 
-interface FormProps {
-    formConfig: FormConfiguration;
-    defaultValues?: Record<string, any>;
-    onSubmit?: (data: Record<string, any>) => void | Promise<void>;
-    onFieldChange?: (fieldId: string, value: any, formData: Record<string, any>) => void;
-    className?: string;
-    children: React.ReactNode;
-}
-declare function Form({ formConfig, defaultValues, onSubmit, onFieldChange, children }: FormProps): react_jsx_runtime.JSX.Element;
-
-interface FormBodyProps {
-    className?: string;
-}
-declare function FormBody({ className }: FormBodyProps): React$1.ReactElement<any, string | React$1.JSXElementConstructor<any>>;
-
-interface FormFieldProps {
-    fieldId: string;
-    disabled?: boolean;
-    customProps?: Record<string, any>;
-    className?: string;
-}
-declare function FormField({ fieldId, disabled, customProps, className, }: FormFieldProps): react_jsx_runtime.JSX.Element | null;
-
-interface FormState {
-    values: Record<string, any>;
-    errors: Record<string, ValidationError[]>;
-    warnings: Record<string, ValidationError[]>;
-    touched: Set<string>;
-    isValidating: Set<string>;
-    isDirty: boolean;
-    isValid: boolean;
-    isSubmitting: boolean;
-}
-interface FormContextValue {
-    formState: FormState;
-    formConfig: FormConfiguration;
-    setValue: (fieldId: string, value: any) => void;
-    setError: (fieldId: string, errors: ValidationError[]) => void;
-    setWarning: (fieldId: string, warnings: ValidationError[]) => void;
-    clearError: (fieldId: string) => void;
-    clearWarning: (fieldId: string) => void;
-    markFieldTouched: (fieldId: string) => void;
-    setFieldValidating: (fieldId: string, isValidating: boolean) => void;
-    validateField: (fieldId: string, value?: any) => Promise<ValidationResult>;
-    validateAllFields: () => Promise<boolean>;
-    reset: (values?: Record<string, any>) => void;
-    submit: (event?: React__default.FormEvent) => Promise<boolean>;
-}
-interface FormProviderProps {
-    children: React__default.ReactNode;
-    formConfig: FormConfiguration;
-    defaultValues?: Record<string, any>;
-    onSubmit?: (data: Record<string, any>) => void | Promise<void>;
-    onFieldChange?: (fieldId: string, value: any, formData: Record<string, any>) => void;
-    className?: string;
-}
-declare function FormProvider({ children, formConfig, defaultValues, onSubmit, onFieldChange, className, }: FormProviderProps): react_jsx_runtime.JSX.Element;
-declare function useFormContext(): FormContextValue;
-
-interface FormRowProps {
-    row: FormFieldRow;
-    className?: string;
-}
-declare function FormRow({ row, className }: FormRowProps): React$1.ReactElement<any, string | React$1.JSXElementConstructor<any>>;
-
-interface FormSubmitButtonProps {
-    className?: string;
-    children?: React__default.ReactNode;
+/**
+ * Fluent builder for configuring repeatable field groups
+ *
+ * Used via callback in `form.addRepeatable()`:
+ * ```typescript
+ * form.create(ril, "order")
+ *   .addRepeatable("items", r => r
+ *     .add(
+ *       { id: "name", type: "text", props: { label: "Item" } },
+ *       { id: "qty", type: "number", props: { label: "Qty" } }
+ *     )
+ *     .min(1)
+ *     .max(10)
+ *     .defaultValue({ name: "", qty: 1 })
+ *   )
+ *   .build()
+ * ```
+ */
+declare class RepeatableBuilder<C extends Record<string, any>> {
+    private innerForm;
+    private _min?;
+    private _max?;
+    private _defaultValue?;
+    private _validation?;
+    constructor(config: ril<C>);
+    /**
+     * Add fields to the repeatable template
+     * Same API as form.add() — variadic ≤3 puts them on the same row
+     */
+    add<T extends keyof C & string>(...fields: FieldConfig<C, T>[]): this;
+    add<T extends keyof C & string>(fields: FieldConfig<C, T>[]): this;
+    /**
+     * Add fields each on their own row
+     */
+    addSeparateRows<T extends keyof C & string>(fields: FieldConfig<C, T>[]): this;
+    /**
+     * Set minimum number of items (defaults to 0)
+     */
+    min(value: number): this;
+    /**
+     * Set maximum number of items (unlimited if not set)
+     */
+    max(value: number): this;
+    /**
+     * Set default values for new items
+     */
+    defaultValue(value: Record<string, unknown>): this;
+    /**
+     * Set group-level validation (applied to the entire array)
+     */
+    validation(config: FieldValidationConfig): this;
+    /** @internal — called by form.addRepeatable */
+    _build(id: string): RepeatableFieldConfig;
+    /** @internal — check if the inner builder has repeatables (nesting forbidden) */
+    _hasRepeatables(): boolean;
 }
-declare function FormSubmitButton({ className, children }: FormSubmitButtonProps): React__default.ReactElement<any, string | React__default.JSXElementConstructor<any>>;
 
 /**
- * Form builder class for creating form configurations
- * Simplified API with matrix support
+ * 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
+ *   }
+ * };
+ * ```
  */
-declare class form {
+type FieldConfig<C extends Record<string, any>, T extends keyof C> = {
+    /** 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 configuration for this field */
+    validation?: FieldValidationConfig;
+    /** Conditional behavior configuration for this field */
+    conditions?: ConditionalBehavior;
+};
+/**
+ * Form builder for creating type-safe form configurations
+ *
+ * DX Notes (How to create a form):
+ * - Recommended: use the static factory
+ *
+ *   const rilConfig = ril
+ *     .create()
+ *     .addComponent('text', { name: 'Text', renderer: TextInput })
+ *     .addComponent('email', { name: 'Email', renderer: EmailInput });
+ *
+ *   const myForm = form
+ *     .create(rilConfig, 'contact-form')
+ *     .add({ id: 'firstName', type: 'text', props: { label: 'First name' } })
+ *     .add(
+ *       { id: 'email', type: 'email', props: { label: 'Email' } },
+ *       { id: 'role', type: 'text', props: { label: 'Role' } }
+ *     )
+ *     .build();
+ *
+ * - Or instantiate directly:
+ *
+ *   const myForm = new form(rilConfig, 'contact-form')
+ *     .add({ id: 'firstName', type: 'text' })
+ *     .build();
+ *
+ * Why we do not augment ril with .form():
+ * - Keep the API explicit and bundler-friendly (no prototype/module augmentation)
+ * - Better discoverability and IntelliSense via the builder class
+ *
+ * Typing & autocomplete:
+ * - Types flow from your ril configuration: once components are registered,
+ *   the `type` and `props` of `.add({ ... })` are fully typed.
+ *
+ * Adding fields:
+ * - Variadic: .add(fieldA, fieldB) => same row (max 3 per row)
+ * - Array:    .add([fieldA, fieldB]) => explicit single row
+ * - >3 fields (variadic) => split across multiple rows automatically
+ *
+ * Output of .build(): FormConfiguration<C>
+ * - id, rows, allFields, renderConfig (from ril), optional validation
+ */
+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;
-    constructor(config: ril, formId?: string);
-    static create(config: ril, formId?: string): form;
-    /**
-     * Add a single field (takes full width)
-     * @param fieldId - Unique field identifier
-     * @param componentSubType - Component subtype (e.g., 'text', 'email')
-     * @param props - Props to pass to the component
-     * @param options - Additional options
-     * @returns form instance for chaining
-     */
-    addField(fieldId: string, componentSubType: InputType | LayoutType, props?: Record<string, any>, options?: {
-        validation?: ValidationConfig;
-        conditional?: ConditionalConfig;
-    }): this;
-    /**
-     * Add multiple fields on the same row (max 3 fields)
+    /** 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 to create a new form builder
+     *
+     * Usage (recommended):
+     *
+     * const myForm = form
+     *   .create(rilConfig, 'my-form')
+     *   .add({ id: 'email', type: 'email', props: { label: 'Email' } })
+     *   .build();
+     *
+     * Why prefer this over `new form(...)`?
+     * - Clearer intent and better discoverability
+     * - Consistent with other builder APIs
+     */
+    static create<Cm extends Record<string, any> = Record<string, never>>(config: ril<Cm>, formId?: string): form<Cm>;
+    /**
+     * 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;
+    /**
+     * 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 - Row configuration options
-     * @returns form instance for chaining
-     */
-    addRowFields(fieldConfigs: Array<{
-        fieldId: string;
-        componentSubType: InputType | LayoutType;
-        props?: Record<string, any>;
-        validation?: ValidationConfig;
-        conditional?: ConditionalConfig;
-    }>, rowOptions?: {
-        spacing?: 'tight' | 'normal' | 'loose';
-        alignment?: 'start' | 'center' | 'end' | 'stretch';
-    }): this;
-    /**
-     * Add multiple fields, each on its own row
+     * @returns A complete FormFieldRow configuration
+     * @throws Error if no fields provided or more than 3 fields specified
+     *
+     * @internal
+     */
+    private createRow;
+    /**
+     * 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' });
+     * ```
+     */
+    add<T extends keyof C & string>(...fields: FieldConfig<C, T>[]): this;
+    add<T extends keyof C & string>(fields: FieldConfig<C, T>[]): this;
+    /**
+     * 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
-     * @returns form instance for chaining
+     * @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' } }
+     * ]);
+     * ```
      */
-    addFields(fieldConfigs: Array<{
-        fieldId: string;
-        componentSubType: InputType | LayoutType;
-        props?: Record<string, any>;
-        validation?: ValidationConfig;
-        conditional?: ConditionalConfig;
-    }>): this;
+    addSeparateRows<T extends keyof C & string>(fieldConfigs: FieldConfig<C, T>[]): this;
     /**
-     * Set form ID
-     * @param id - Form identifier
-     * @returns form instance for chaining
+     * Adds a repeatable field group to the form
+     *
+     * Repeatable fields allow users to add/remove instances of a group of fields
+     * at runtime (e.g., "Add another item", "Add another contact").
+     *
+     * @param id - Unique identifier for the repeatable group (cannot contain [ or ])
+     * @param configure - Callback receiving a RepeatableBuilder for fluent configuration
+     * @returns The form builder instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * builder.addRepeatable("items", r => r
+     *   .add(
+     *     { id: "name", type: "text", props: { label: "Item" } },
+     *     { id: "qty", type: "number", props: { label: "Qty" } }
+     *   )
+     *   .min(1)
+     *   .max(10)
+     *   .defaultValue({ name: "", qty: 1 })
+     * );
+     * ```
+     */
+    addRepeatable(id: string, configure: (builder: RepeatableBuilder<C>) => RepeatableBuilder<C>): this;
+    /**
+     * 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
-     * @param fieldId - Field identifier
-     * @param updates - Updates to apply
-     * @returns form instance for chaining
+     * 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;
     /**
-     * Remove a field from the form
-     * @param fieldId - Field identifier
-     * @returns form instance for chaining
+     * 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;
+    /**
+     * 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
-     * @param fieldId - Field identifier
-     * @returns Field configuration or undefined
+     * 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
-     * @returns Array of field configurations
+     * 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
-     * @returns Array of row configurations
+     * 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[];
+    getRows(): FormRowEntry[];
     /**
-     * Clear all fields and rows
-     * @returns form instance for chaining
+     * 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
-     * @param newFormId - ID for the cloned form
-     * @returns New form instance
+     * 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
+     * ]);
+     * ```
+     */
+    /**
+     * 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
+     * });
+     * ```
+     */
+    /** @deprecated Use updateField with new validation.validate property instead */
+    addFieldValidation(fieldId: string, validationConfig: any): this;
+    /**
+     * Adds conditions to a specific field by ID
+     *
+     * This method allows adding conditional behavior to a field after it has been created,
+     * useful for dynamic conditional requirements.
+     *
+     * @param fieldId - The ID of the field to add conditions to
+     * @param conditions - Conditional behavior configuration
+     * @returns The form builder instance for method chaining
+     * @throws Error if the field with the specified ID is not found
+     *
+     * @example
+     * ```typescript
+     * builder.addFieldConditions('phone', {
+     *   visible: when('contactMethod').equals('phone').build(),
+     *   required: when('contactMethod').equals('phone').build()
+     * });
+     * ```
+     */
+    addFieldConditions(fieldId: string, conditions: ConditionalBehavior): 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;
+    clone(newFormId?: string): form<C>;
     /**
-     * Validate the form configuration
-     * @returns Array of validation errors
+     * 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
-     * @returns Complete form configuration with matrix structure
+     * 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;
+    build(): FormConfiguration<C>;
     /**
-     * Export form configuration as JSON
-     * @returns JSON representation of the form
+     * 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
-     * @param json - JSON representation of the form
-     * @returns form instance for chaining
+     * 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
-     * @returns Object with 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 static fields across all rows */
         totalFields: number;
+        /** Total number of rows in the form */
         totalRows: number;
+        /** Average number of fields per row (field rows only) */
         averageFieldsPerRow: number;
+        /** Maximum number of fields in any single row */
         maxFieldsInRow: number;
+        /** Minimum number of fields in any single row */
         minFieldsInRow: number;
+        /** Total number of repeatable groups */
+        totalRepeatables: number;
+        /** Total number of fields across all repeatable templates */
+        totalRepeatableFields: number;
+    };
+}
+
+interface FormProps {
+    formConfig: FormConfiguration<any> | form<any>;
+    defaultValues?: Record<string, any>;
+    onSubmit?: (data: Record<string, any>) => void | Promise<void>;
+    onFieldChange?: (fieldId: string, value: any, formData: Record<string, any>) => void;
+    className?: string;
+    children: React.ReactNode;
+}
+declare function Form({ formConfig, defaultValues, onSubmit, onFieldChange, className, children, }: FormProps): react_jsx_runtime.JSX.Element;
+
+declare const FormBody: React__default.NamedExoticComponent<ComponentRendererBaseProps<FormBodyRendererProps>>;
+
+interface FormFieldProps {
+    fieldId: string;
+    /** Pre-resolved field config (used by RepeatableItem to skip allFields lookup) */
+    fieldConfig?: FormFieldConfig;
+    disabled?: boolean;
+    customProps?: Record<string, unknown>;
+    className?: string;
+    forceVisible?: boolean;
+}
+declare const FormField: React__default.NamedExoticComponent<FormFieldProps>;
+
+interface ConditionEvaluationResult {
+    visible: boolean;
+    disabled: boolean;
+    required: boolean;
+    readonly: boolean;
+}
+/**
+ * Hook to evaluate conditional behaviors based on form data
+ *
+ * @param conditions - The conditional behavior configuration
+ * @param formData - Current form data to evaluate against
+ * @param defaultState - Default state when no conditions are provided
+ * @returns Evaluated condition results
+ */
+declare function useConditionEvaluation(conditions?: ConditionalBehavior, formData?: Record<string, any>, defaultState?: Partial<ConditionEvaluationResult>): ConditionEvaluationResult;
+/**
+ * Hook to evaluate conditions for multiple fields at once
+ *
+ * @param fieldsWithConditions - Map of field IDs to their conditional behaviors
+ * @param formData - Current form data
+ * @returns Map of field IDs to their evaluated conditions
+ */
+declare function useMultipleConditionEvaluation(fieldsWithConditions: Record<string, ConditionalBehavior | undefined>, formData?: Record<string, any>): Record<string, ConditionEvaluationResult>;
+
+interface UseFieldConditionsLazyOptions {
+    /**
+     * The field's conditional behavior configuration
+     */
+    conditions?: ConditionalBehavior;
+    /**
+     * Whether to skip evaluation (e.g., if field has no conditions)
+     */
+    skip?: boolean;
+}
+/**
+ * Lazy condition evaluation hook with caching
+ *
+ * This hook:
+ * 1. Only evaluates conditions when called
+ * 2. Caches the result based on form values hash
+ * 3. Returns cached result if values haven't changed
+ *
+ * @param fieldId - The field ID
+ * @param options - Configuration options
+ * @returns The evaluated field conditions
+ *
+ * @example
+ * ```tsx
+ * const conditions = useFieldConditionsLazy('myField', {
+ *   conditions: fieldConfig.conditions
+ * });
+ *
+ * if (!conditions.visible) return null;
+ * ```
+ */
+declare function useFieldConditionsLazy(fieldId: string, options?: UseFieldConditionsLazyOptions): FieldConditions;
+/**
+ * Hook to create a lazy condition evaluator function
+ *
+ * This is useful when you need to evaluate conditions for multiple fields
+ * on-demand, without triggering re-renders.
+ *
+ * @returns A function that evaluates conditions for a given field
+ */
+declare function useConditionEvaluator(): (fieldId: string, conditions?: ConditionalBehavior) => FieldConditions;
+/**
+ * Hook that provides both current conditions and a way to force re-evaluation
+ */
+declare function useFieldConditionsWithRefresh(fieldId: string, conditions?: ConditionalBehavior): {
+    conditions: FieldConditions;
+    refresh: () => FieldConditions;
+};
+
+interface UseFormConditionsProps {
+    formConfig: FormConfiguration;
+    formValues: Record<string, any>;
+    /** Active repeatable item keys, keyed by repeatable ID */
+    repeatableOrder?: Record<string, string[]>;
+}
+interface UseFormConditionsReturn {
+    fieldConditions: Record<string, ConditionEvaluationResult>;
+    hasConditionalFields: boolean;
+    getFieldCondition: (fieldId: string) => ConditionEvaluationResult | undefined;
+    isFieldVisible: (fieldId: string) => boolean;
+    isFieldDisabled: (fieldId: string) => boolean;
+    isFieldRequired: (fieldId: string) => boolean;
+    isFieldReadonly: (fieldId: string) => boolean;
+}
+/**
+ * Hook to manage conditional behaviors for form fields
+ *
+ * This hook evaluates conditions for all form fields and provides
+ * convenient methods to check field states.
+ *
+ * @param props - Configuration for form conditions
+ * @returns Object containing field conditions and helper methods
+ *
+ * @example
+ * ```tsx
+ * const {
+ *   fieldConditions,
+ *   isFieldVisible,
+ *   isFieldDisabled
+ * } = useFormConditions({
+ *   formConfig,
+ *   formValues
+ * });
+ *
+ * // Check if a field should be visible
+ * if (!isFieldVisible('phoneField')) {
+ *   return null;
+ * }
+ * ```
+ */
+declare function useFormConditions({ formConfig, formValues, repeatableOrder, }: UseFormConditionsProps): UseFormConditionsReturn;
+
+interface FormStoreState extends FormState {
+    _defaultValues: Record<string, unknown>;
+    _fieldConditions: Record<string, FieldConditions>;
+    _repeatableConfigs: Record<string, RepeatableFieldConfig>;
+    _repeatableOrder: Record<string, string[]>;
+    _repeatableNextKey: Record<string, number>;
+    _setValue: (fieldId: string, value: unknown) => void;
+    _setTouched: (fieldId: string) => void;
+    _setErrors: (fieldId: string, errors: ValidationError[]) => void;
+    _clearErrors: (fieldId: string) => void;
+    _setValidationState: (fieldId: string, state: ValidationState) => void;
+    _setSubmitting: (isSubmitting: boolean) => void;
+    _reset: (values?: Record<string, unknown>) => void;
+    _setFieldConditions: (fieldId: string, conditions: FieldConditions) => void;
+    _updateIsValid: () => void;
+    _setRepeatableConfig: (id: string, config: RepeatableFieldConfig) => void;
+    _appendRepeatableItem: (repeatableId: string, defaultValue?: Record<string, unknown>) => string | null;
+    _removeRepeatableItem: (repeatableId: string, key: string) => boolean;
+    _moveRepeatableItem: (repeatableId: string, fromIndex: number, toIndex: number) => void;
+    _insertRepeatableItem: (repeatableId: string, index: number, defaultValue?: Record<string, unknown>) => string | null;
+}
+type FormStore = ReturnType<typeof createFormStore>;
+declare function createFormStore(initialValues?: Record<string, unknown>): Omit<zustand.StoreApi<FormStoreState>, "subscribe"> & {
+    subscribe: {
+        (listener: (selectedState: FormStoreState, previousSelectedState: FormStoreState) => void): () => void;
+        <U>(selector: (state: FormStoreState) => U, listener: (selectedState: U, previousSelectedState: U) => void, options?: {
+            equalityFn?: ((a: U, b: U) => boolean) | undefined;
+            fireImmediately?: boolean;
+        } | undefined): () => void;
+    };
+};
+declare const FormStoreContext: React$1.Context<(Omit<zustand.StoreApi<FormStoreState>, "subscribe"> & {
+    subscribe: {
+        (listener: (selectedState: FormStoreState, previousSelectedState: FormStoreState) => void): () => void;
+        <U>(selector: (state: FormStoreState) => U, listener: (selectedState: U, previousSelectedState: U) => void, options?: {
+            equalityFn?: ((a: U, b: U) => boolean) | undefined;
+            fireImmediately?: boolean;
+        } | undefined): () => void;
     };
+}) | null>;
+/**
+ * Get the form store from context
+ * @throws Error if used outside of FormProvider
+ */
+declare function useFormStore(): FormStore;
+/**
+ * Select a single field value - re-renders only when this field's value changes
+ */
+declare function useFieldValue<T = unknown>(fieldId: string): T;
+/**
+ * Select field errors - re-renders only when this field's errors change
+ */
+declare function useFieldErrors(fieldId: string): ValidationError[];
+/**
+ * Select field touched state - re-renders only when this field's touched state changes
+ */
+declare function useFieldTouched(fieldId: string): boolean;
+/**
+ * Select field validation state - re-renders only when this field's validation state changes
+ */
+declare function useFieldValidationState(fieldId: string): ValidationState;
+/**
+ * Select field conditions - re-renders only when this field's conditions change
+ */
+declare function useFieldConditions(fieldId: string): FieldConditions;
+/**
+ * Select complete field state - uses individual selectors to avoid object recreation
+ */
+declare function useFieldState(fieldId: string): FieldState;
+/**
+ * Select form submitting state
+ */
+declare function useFormSubmitting(): boolean;
+/**
+ * Select form valid state
+ */
+declare function useFormValid(): boolean;
+/**
+ * Select form dirty state
+ */
+declare function useFormDirty(): boolean;
+/**
+ * Select all form values - uses shallow comparison
+ */
+declare function useFormValues(): Record<string, unknown>;
+/**
+ * Select form state for submit button - minimal re-renders
+ */
+declare function useFormSubmitState(): {
+    isSubmitting: boolean;
+    isValid: boolean;
+    isDirty: boolean;
+};
+/**
+ * Select ordered keys for a repeatable field — re-renders when the order changes
+ */
+declare function useRepeatableKeys(repeatableId: string): string[];
+interface UseFieldActionsResult {
+    setValue: (value: unknown) => void;
+    setTouched: () => void;
+    setErrors: (errors: ValidationError[]) => void;
+    clearErrors: () => void;
+    setValidationState: (state: ValidationState) => void;
 }
+/**
+ * Get stable action references for a field
+ * Actions don't cause re-renders
+ */
+declare function useFieldActions(fieldId: string): UseFieldActionsResult;
+interface UseFormActionsResult {
+    setValue: (fieldId: string, value: unknown) => void;
+    setTouched: (fieldId: string) => void;
+    setErrors: (fieldId: string, errors: ValidationError[]) => void;
+    setSubmitting: (isSubmitting: boolean) => void;
+    reset: (values?: Record<string, unknown>) => void;
+    setFieldConditions: (fieldId: string, conditions: FieldConditions) => void;
+}
+/**
+ * Get stable form-level action references
+ * Actions don't cause re-renders
+ */
+declare function useFormActions(): UseFormActionsResult;
+/**
+ * Get the raw store for advanced use cases (like validation hooks)
+ */
+declare function useFormStoreApi(): FormStore;
+
+interface UseFormSubmissionWithStoreProps {
+    store: FormStore;
+    onSubmit?: (data: Record<string, unknown>) => void | Promise<void>;
+    validateForm: () => Promise<ValidationResult>;
+}
+declare function useFormSubmissionWithStore({ store, onSubmit, validateForm, }: UseFormSubmissionWithStoreProps): {
+    submit: (event?: React__default.FormEvent) => Promise<boolean>;
+};
+
+interface UseFormValidationWithStoreProps {
+    formConfig: FormConfiguration;
+    store: FormStore;
+    conditionsHelpers: Omit<UseFormConditionsReturn, 'fieldConditions'>;
+}
+declare function useFormValidationWithStore({ formConfig, store, conditionsHelpers, }: UseFormValidationWithStoreProps): {
+    validateField: (fieldId: string, value?: unknown) => Promise<ValidationResult>;
+    validateForm: () => Promise<ValidationResult>;
+};
+
+interface UseRepeatableFieldReturn {
+    items: RepeatableFieldItem[];
+    append: (defaultValue?: Record<string, unknown>) => void;
+    remove: (key: string) => void;
+    move: (fromIndex: number, toIndex: number) => void;
+    canAdd: boolean;
+    canRemove: boolean;
+    count: number;
+}
+/**
+ * Hook to manage a repeatable field group
+ *
+ * Provides the list of items and actions to add, remove, and reorder them.
+ * Each item contains scoped field configs ready for rendering.
+ *
+ * @param repeatableId - The ID of the repeatable group (as defined in addRepeatable)
+ * @returns Items, actions, and constraints
+ *
+ * @example
+ * ```tsx
+ * const { items, append, remove, canAdd, canRemove } = useRepeatableField("items");
+ *
+ * return (
+ *   <div>
+ *     {items.map(item => (
+ *       <div key={item.key}>
+ *         {item.allFields.map(field => (
+ *           <FormField key={field.id} fieldId={field.id} fieldConfig={field} />
+ *         ))}
+ *         {canRemove && <button onClick={() => remove(item.key)}>Remove</button>}
+ *       </div>
+ *     ))}
+ *     {canAdd && <button onClick={append}>Add</button>}
+ *   </div>
+ * );
+ * ```
+ */
+declare function useRepeatableField(repeatableId: string): UseRepeatableFieldReturn;
+
+interface UseFormMonitoringProps {
+    formConfig: FormConfiguration;
+    monitoring?: MonitoringConfig;
+    enabled?: boolean;
+}
+interface UseFormMonitoringReturn {
+    trackFormRender: (renderCount?: number) => void;
+    trackFormValidation: (validationErrors: number, fieldCount?: number) => void;
+    trackFormSubmission: (success: boolean, fieldCount?: number) => void;
+    trackFieldChange: (fieldId: string, componentType: string) => void;
+    startPerformanceTracking: (label: string) => void;
+    endPerformanceTracking: (label: string) => FormPerformanceMetrics | null;
+}
+declare function useFormMonitoring({ formConfig, enabled, }: UseFormMonitoringProps): UseFormMonitoringReturn;
+
+interface FormConfigContextValue {
+    formConfig: FormConfiguration;
+    conditionsHelpers: Omit<UseFormConditionsReturn, 'fieldConditions'>;
+    validateField: (fieldId: string, value?: unknown) => Promise<ValidationResult>;
+    validateForm: () => Promise<ValidationResult>;
+    submit: (event?: React__default.FormEvent) => Promise<boolean>;
+}
+/**
+ * Access form configuration and validation methods
+ */
+declare function useFormConfigContext(): FormConfigContextValue;
+interface FormProviderProps {
+    children: React__default.ReactNode;
+    formConfig: FormConfiguration;
+    defaultValues?: Record<string, unknown>;
+    onSubmit?: (data: Record<string, unknown>) => void | Promise<void>;
+    onFieldChange?: (fieldId: string, value: unknown, formData: Record<string, unknown>) => void;
+    className?: string;
+}
+declare function FormProvider({ children, formConfig, defaultValues, onSubmit, onFieldChange, className, }: FormProviderProps): react_jsx_runtime.JSX.Element;
+
+interface FormRowProps extends ComponentRendererBaseProps<FormRowRendererProps> {
+    row: FormFieldRow;
+}
+declare const FormRow: React__default.NamedExoticComponent<FormRowProps>;
+
+interface FormSubmitButtonProps extends ComponentRendererBaseProps<FormSubmitButtonRendererProps> {
+    /**
+     * Override the isSubmitting state from form context
+     * If provided, this value will be used instead of the form's isSubmitting state
+     */
+    isSubmitting?: boolean;
+}
+declare const FormSubmitButton: React__default.NamedExoticComponent<FormSubmitButtonProps>;
+
+interface RepeatableFieldProps {
+    repeatableId: string;
+    repeatableConfig: RepeatableFieldConfig;
+    className?: string;
+}
+declare const RepeatableField: React__default.NamedExoticComponent<RepeatableFieldProps>;
+
+interface RepeatableItemProps {
+    item: RepeatableFieldItem;
+    index: number;
+    total: number;
+    canRemove: boolean;
+    canMoveUp: boolean;
+    canMoveDown: boolean;
+    onRemove: () => void;
+    onMoveUp: () => void;
+    onMoveDown: () => void;
+}
+declare const RepeatableItem: React__default.NamedExoticComponent<RepeatableItemProps>;
+
+/**
+ * Converts flat store values with composite keys into structured nested data.
+ *
+ * Input (store values):
+ *   { customerName: "John", "items[k0].name": "Widget", "items[k0].qty": 2, "items[k1].name": "Gadget", "items[k1].qty": 1 }
+ *
+ * Output (structured):
+ *   { customerName: "John", items: [{ name: "Widget", qty: 2 }, { name: "Gadget", qty: 1 }] }
+ */
+declare function structureFormValues(values: Record<string, unknown>, repeatableConfigs: Record<string, RepeatableFieldConfig>, repeatableOrder: Record<string, string[]>): Record<string, unknown>;
+/**
+ * Converts structured nested data into flat store values with composite keys.
+ *
+ * Input (structured):
+ *   { customerName: "John", items: [{ name: "Widget", qty: 2 }, { name: "Gadget", qty: 1 }] }
+ *
+ * Output:
+ *   {
+ *     values: { customerName: "John", "items[k0].name": "Widget", "items[k0].qty": 2, "items[k1].name": "Gadget", "items[k1].qty": 1 },
+ *     order: { items: ["k0", "k1"] },
+ *     nextKeys: { items: 2 }
+ *   }
+ */
+declare function flattenRepeatableValues(data: Record<string, unknown>, repeatableConfigs: Record<string, RepeatableFieldConfig>): {
+    values: Record<string, unknown>;
+    order: Record<string, string[]>;
+    nextKeys: Record<string, number>;
+};
 
-export { 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, form, useFormContext };
+export { type ConditionEvaluationResult, type FieldConfig, Form, FormBody, form as FormBuilder, type FormConfigContextValue, FormField, FormProvider, type FormProviderProps, FormRow, type FormStore, FormStoreContext, type FormStoreState, FormSubmitButton, RepeatableBuilder, RepeatableField, RepeatableItem, type UseFieldActionsResult, type UseFieldConditionsLazyOptions, type UseFormActionsResult, type UseFormConditionsProps, type UseFormConditionsReturn, type UseFormMonitoringProps, type UseFormMonitoringReturn, type UseFormSubmissionWithStoreProps, type UseFormValidationWithStoreProps, type UseRepeatableFieldReturn, createFormStore, flattenRepeatableValues, form, structureFormValues, useConditionEvaluation, useConditionEvaluator, useFieldActions, useFieldConditions, useFieldConditionsLazy, useFieldConditionsWithRefresh, useFieldErrors, useFieldState, useFieldTouched, useFieldValidationState, useFieldValue, useFormActions, useFormConditions, useFormConfigContext, useFormDirty, useFormMonitoring, useFormStore, useFormStoreApi, useFormSubmissionWithStore, useFormSubmitState, useFormSubmitting, useFormValid, useFormValidationWithStore, useFormValues, useMultipleConditionEvaluation, useRepeatableField, useRepeatableKeys };