@rilaykit/core 4.0.0 → 5.0.0

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import React from 'react';
-import { z } from 'zod';
+import * as React$1 from 'react';
+import React__default from 'react';
 
 /**
  * Main configuration class for Rilay form components and workflows
@@ -15,6 +15,20 @@ declare class ril<C> {
      * @param type - The component type (e.g., 'text', 'email', 'heading'), used as a unique identifier.
      * @param config - Component configuration without id and type
      * @returns The ril instance for chaining
+     *
+     * @example
+     * ```typescript
+     * // Component avec validation par défaut
+     * const factory = ril.create()
+     *   .addComponent('email', {
+     *     name: 'Email Input',
+     *     renderer: EmailInput,
+     *     validation: {
+     *       validators: [email('Format email invalide')],
+     *       validateOnBlur: true,
+     *     }
+     *   });
+     * ```
      */
     addComponent<NewType extends string, TProps = any>(type: NewType, config: Omit<ComponentConfig<TProps>, 'id' | 'type'>): ril<C & {
         [K in NewType]: TProps;
@@ -113,81 +127,140 @@ interface RilayLicenseConfig {
     readonly environment?: 'development' | 'production';
     readonly allowTrial?: boolean;
 }
+interface ValidationError {
+    readonly message: string;
+    readonly code?: string;
+    readonly path?: string;
+}
 interface ValidationResult {
     readonly isValid: boolean;
     readonly errors: ValidationError[];
 }
-interface ValidationError {
-    readonly code: string;
-    readonly message: string;
-    readonly path?: string[];
-}
 interface ValidationContext {
-    readonly fieldId: string;
-    readonly formData: Record<string, any>;
-    readonly fieldProps: Record<string, any>;
-    readonly touched: boolean;
-    readonly dirty: boolean;
-}
-type ValidatorFunction<TProps = any> = (value: any, context: ValidationContext, props: TProps) => ValidationResult | Promise<ValidationResult>;
-interface ValidationConfig<TProps = any> {
-    readonly validator?: ValidatorFunction<TProps>;
-    readonly debounceMs?: number;
+    readonly fieldId?: string;
+    readonly formId?: string;
+    readonly stepId?: string;
+    readonly workflowId?: string;
+    readonly allFormData?: Record<string, any>;
+    readonly stepData?: Record<string, any>;
+    readonly workflowData?: Record<string, any>;
+}
+type FieldValidator<T = any> = (value: T, context: ValidationContext) => ValidationResult | Promise<ValidationResult>;
+type FormValidator<T = Record<string, any>> = (formData: T, context: ValidationContext) => ValidationResult | Promise<ValidationResult>;
+type ValidationSchema<T = any> = {
+    parse: (value: T) => T;
+    safeParse: (value: T) => {
+        success: boolean;
+        data?: T;
+        error?: any;
+    };
+};
+interface ValidationAdapter<TSchema = any> {
+    readonly name: string;
+    readonly version?: string;
+    createFieldValidator<T>(schema: TSchema): FieldValidator<T>;
+    createFormValidator<T>(schema: TSchema): FormValidator<T>;
+}
+interface FieldValidationConfig {
+    readonly validators?: FieldValidator[];
+    readonly schema?: ValidationSchema;
     readonly validateOnChange?: boolean;
     readonly validateOnBlur?: boolean;
+    readonly debounceMs?: number;
+}
+interface FormValidationConfig {
+    readonly validators?: FormValidator[];
+    readonly schema?: ValidationSchema;
     readonly validateOnSubmit?: boolean;
-    readonly dependencies?: string[];
+    readonly validateOnStepChange?: boolean;
+}
+type ComponentRenderer<TProps = any> = (props: ComponentRenderProps<TProps>) => React__default.ReactElement;
+type RendererChildrenFunction<TProps = any> = (props: TProps) => React__default.ReactNode;
+interface ComponentRendererBaseProps<TProps = any> {
+    className?: string;
+    children?: React__default.ReactNode | RendererChildrenFunction<TProps>;
+    renderAs?: 'default' | 'children' | boolean;
+}
+interface ComponentRendererWrapperProps<TProps = any> extends Omit<ComponentRendererBaseProps<TProps>, 'className'> {
+    name: string;
+    props: TProps;
+    renderer?: RendererChildrenFunction<TProps>;
 }
-type ComponentRenderer<TProps = any> = (props: ComponentRenderProps<TProps>) => React.ReactElement;
 interface ComponentRenderProps<TProps = any> {
     id: string;
     props: TProps;
     value?: any;
     onChange?: (value: any) => void;
     onBlur?: () => void;
-    error?: ValidationError[];
-    touched?: boolean;
     disabled?: boolean;
+    error?: ValidationError[];
     isValidating?: boolean;
     [key: string]: any;
 }
-type RendererChildrenFunction<TProps = any> = (props: TProps) => React.ReactNode;
-declare function resolveRendererChildren<TProps>(children: React.ReactNode | RendererChildrenFunction<TProps> | undefined, props: TProps): React.ReactNode;
 interface ComponentConfig<TProps = any> {
     readonly id: string;
     readonly type: string;
     readonly name: string;
     readonly description?: string;
     readonly renderer: ComponentRenderer<TProps>;
-    readonly validation?: ValidationConfig<TProps>;
     readonly defaultProps?: Partial<TProps>;
     readonly useFieldRenderer?: boolean;
+    readonly validation?: FieldValidationConfig;
 }
 interface FormFieldConfig {
     readonly id: string;
     readonly componentId: string;
     readonly props: Record<string, any>;
-    readonly validation?: ValidationConfig;
-    readonly conditional?: ConditionalConfig;
+    readonly validation?: FieldValidationConfig;
 }
 interface FormFieldRow {
     readonly id: string;
     readonly fields: FormFieldConfig[];
     readonly maxColumns?: number;
-    readonly spacing?: 'tight' | 'normal' | 'loose';
-    readonly alignment?: 'start' | 'center' | 'end' | 'stretch';
 }
-interface ConditionalConfig {
-    readonly condition: (formData: Record<string, any>) => boolean;
-    readonly action: 'show' | 'hide' | 'disable' | 'require';
+interface FormConfiguration<C extends Record<string, any> = Record<string, never>> {
+    readonly id: string;
+    readonly config: ril<C>;
+    readonly rows: FormFieldRow[];
+    readonly allFields: FormFieldConfig[];
+    readonly renderConfig?: FormRenderConfig;
+    readonly validation?: FormValidationConfig;
+}
+interface FormRenderConfig {
+    readonly rowRenderer?: FormRowRenderer;
+    readonly bodyRenderer?: FormBodyRenderer;
+    readonly submitButtonRenderer?: FormSubmitButtonRenderer;
+    readonly fieldRenderer?: FieldRenderer;
+}
+interface FormComponentRendererProps {
+    children: React__default.ReactNode;
+}
+interface FormRowRendererProps {
+    row: FormFieldRow;
+    children: React__default.ReactNode;
+    className?: string;
+}
+interface FormBodyRendererProps {
+    formConfig: FormConfiguration;
+    children: React__default.ReactNode;
+    className?: string;
+}
+interface FormSubmitButtonRendererProps {
+    isSubmitting: boolean;
+    onSubmit: () => void;
+    className?: string;
+    children?: React__default.ReactNode;
 }
-interface StepLifecycleHooks {
-    readonly onBeforeEnter?: (stepData: any, allData: any, context: WorkflowContext) => Promise<void>;
-    readonly onAfterLeave?: (stepData: any, allData: any, context: WorkflowContext) => Promise<boolean>;
-    readonly onValidate?: (stepData: any, context: WorkflowContext) => Promise<ValidationResult>;
-    readonly onTransform?: (stepData: any, context: WorkflowContext) => Promise<any>;
-    readonly onError?: (error: Error, context: WorkflowContext) => Promise<void>;
+interface FieldRendererProps {
+    children: React__default.ReactNode;
+    id: string;
+    disabled?: boolean;
+    [key: string]: any;
 }
+type FormRowRenderer = RendererChildrenFunction<FormRowRendererProps>;
+type FormBodyRenderer = RendererChildrenFunction<FormBodyRendererProps>;
+type FormSubmitButtonRenderer = RendererChildrenFunction<FormSubmitButtonRendererProps>;
+type FieldRenderer = RendererChildrenFunction<FieldRendererProps>;
 interface WorkflowContext {
     readonly workflowId: string;
     readonly currentStepIndex: number;
@@ -197,80 +270,61 @@ interface WorkflowContext {
     readonly isFirstStep: boolean;
     readonly isLastStep: boolean;
     readonly visitedSteps: Set<string>;
-    readonly user?: any;
-}
-interface StepPermissions {
-    readonly requiredRoles?: string[];
-    readonly requiredPermissions?: string[];
-    readonly customGuard?: (user: any, context: WorkflowContext) => boolean | Promise<boolean>;
-}
-interface DynamicStepConfig {
-    readonly resolver: (previousData: any, context: WorkflowContext) => Promise<StepConfig[]>;
-    readonly cacheKey?: string;
-    readonly retryPolicy?: RetryPolicy;
 }
-interface RetryPolicy {
-    readonly maxRetries: number;
-    readonly delayMs: number;
-    readonly backoffMultiplier?: number;
+interface StepDataHelper {
+    /**
+     * Set data for a specific step by step ID
+     */
+    setStepData: (stepId: string, data: Record<string, any>) => void;
+    /**
+     * Set specific field values for a step
+     */
+    setStepFields: (stepId: string, fields: Record<string, any>) => void;
+    /**
+     * Get current data for a specific step
+     */
+    getStepData: (stepId: string) => Record<string, any>;
+    /**
+     * Set field value for the next step
+     */
+    setNextStepField: (fieldId: string, value: any) => void;
+    /**
+     * Set multiple fields for the next step
+     */
+    setNextStepFields: (fields: Record<string, any>) => void;
+    /**
+     * Get all workflow data
+     */
+    getAllData: () => Record<string, any>;
+    /**
+     * Get all step configurations for reference
+     */
+    getSteps: () => StepConfig[];
 }
 interface StepConfig {
     readonly id: string;
     readonly title: string;
     readonly description?: string;
     readonly formConfig: FormConfiguration;
-    readonly validation?: StepValidationConfig;
-    readonly conditional?: StepConditionalConfig;
     readonly allowSkip?: boolean;
-    readonly requiredToComplete?: boolean;
-    readonly hooks?: StepLifecycleHooks;
-    readonly permissions?: StepPermissions;
-    readonly isDynamic?: boolean;
-    readonly dynamicConfig?: DynamicStepConfig;
     readonly renderer?: CustomStepRenderer;
+    readonly onAfterValidation?: (stepData: Record<string, any>, helper: StepDataHelper, context: WorkflowContext) => void | Promise<void>;
 }
-interface StepValidationConfig {
-    readonly validator?: (stepData: Record<string, any>, allFormData: Record<string, any>, context: WorkflowContext) => ValidationResult | Promise<ValidationResult>;
-    readonly validateOnStepChange?: boolean;
-    readonly blockNextIfInvalid?: boolean;
-}
-interface StepConditionalConfig {
-    readonly condition: (formData: Record<string, any>, context: WorkflowContext) => boolean;
-    readonly action: 'show' | 'hide' | 'skip';
-}
-type CustomStepRenderer = (props: StepConfig) => React.ReactElement;
-interface WorkflowPersistenceData {
-    readonly workflowId: string;
-    readonly currentStepIndex: number;
-    readonly allData: Record<string, any>;
-    readonly metadata: {
-        readonly timestamp: number;
-        readonly version?: string;
-        readonly userId?: string;
-        readonly sessionId?: string;
-    };
-}
-interface PersistenceAdapter {
+type CustomStepRenderer = (props: StepConfig) => React__default.ReactElement;
+interface WorkflowConfig {
+    readonly id: string;
     readonly name: string;
-    save(key: string, data: WorkflowPersistenceData): Promise<void>;
-    load(key: string): Promise<WorkflowPersistenceData | null>;
-    remove(key: string): Promise<void>;
-    exists(key: string): Promise<boolean>;
-    list?(pattern?: string): Promise<string[]>;
-}
-interface PersistenceConfig {
-    readonly adapter: PersistenceAdapter;
-    readonly key?: string;
-    readonly debounceMs?: number;
-    readonly autoSave?: boolean;
-    readonly saveOnStepChange?: boolean;
-    readonly encryptionKey?: string;
-    readonly maxRetries?: number;
-    readonly retryDelayMs?: number;
-    readonly onSave?: (data: WorkflowPersistenceData) => Promise<void> | void;
-    readonly onLoad?: (data: WorkflowPersistenceData) => Promise<void> | void;
-    readonly onError?: (error: Error, operation: 'save' | 'load' | 'remove') => Promise<void> | void;
-    readonly onRetry?: (attempt: number, maxRetries: number, error: Error) => Promise<void> | void;
+    readonly description?: string;
+    readonly steps: StepConfig[];
+    readonly analytics?: WorkflowAnalytics;
+    readonly plugins?: WorkflowPlugin[];
+    readonly renderConfig?: WorkflowRenderConfig;
+}
+interface WorkflowRenderConfig {
+    readonly stepperRenderer?: WorkflowStepperRenderer;
+    readonly nextButtonRenderer?: WorkflowNextButtonRenderer;
+    readonly previousButtonRenderer?: WorkflowPreviousButtonRenderer;
+    readonly skipButtonRenderer?: WorkflowSkipButtonRenderer;
 }
 interface WorkflowAnalytics {
     readonly onWorkflowStart?: (workflowId: string, context: WorkflowContext) => void;
@@ -279,43 +333,21 @@ interface WorkflowAnalytics {
     readonly onStepStart?: (stepId: string, timestamp: number, context: WorkflowContext) => void;
     readonly onStepComplete?: (stepId: string, duration: number, data: any, context: WorkflowContext) => void;
     readonly onStepSkip?: (stepId: string, reason: string, context: WorkflowContext) => void;
-    readonly onValidationError?: (stepId: string, errors: ValidationError[], context: WorkflowContext) => void;
     readonly onError?: (error: Error, context: WorkflowContext) => void;
 }
-interface WorkflowHooks {
-    readonly onStepChange?: (from: string, to: string, context: WorkflowContext) => void;
-    readonly onDataChange?: (data: any, context: WorkflowContext) => void;
-    readonly onValidation?: (result: ValidationResult, context: WorkflowContext) => void;
-}
 interface WorkflowPlugin {
     readonly name: string;
     readonly version?: string;
     readonly install: (workflow: any) => void;
-    readonly hooks?: WorkflowHooks;
     readonly dependencies?: string[];
 }
-interface WorkflowConfig {
-    readonly id: string;
-    readonly name: string;
-    readonly description?: string;
-    readonly steps: StepConfig[];
-    readonly navigation?: NavigationConfig;
-    readonly persistence?: PersistenceConfig;
-    readonly completion?: CompletionConfig;
-    readonly analytics?: WorkflowAnalytics;
-    readonly plugins?: WorkflowPlugin[];
-    readonly renderConfig?: WorkflowRenderConfig;
-}
-interface NavigationConfig {
-    readonly allowBackNavigation?: boolean;
-    readonly allowStepSkipping?: boolean;
-    readonly showProgress?: boolean;
-    readonly customNavigation?: boolean;
-}
-interface CompletionConfig {
-    readonly onComplete?: (formData: Record<string, any>) => void | Promise<void>;
-    readonly confirmBeforeSubmit?: boolean;
-    readonly customCompletionStep?: any;
+interface WorkflowComponentRendererBaseProps {
+    children?: React__default.ReactNode;
+    className?: string;
+    currentStep: StepConfig;
+    stepData: Record<string, any>;
+    allData: Record<string, any>;
+    context: WorkflowContext;
 }
 interface WorkflowStepperRendererProps {
     readonly steps: StepConfig[];
@@ -324,96 +356,26 @@ interface WorkflowStepperRendererProps {
     readonly onStepClick?: (stepIndex: number) => void;
     readonly className?: string;
 }
-type WorkflowStepperRenderer = (props: WorkflowStepperRendererProps) => React.ReactElement;
-interface WorkflowRenderConfig {
-    readonly stepperRenderer?: WorkflowStepperRenderer;
-    readonly nextButtonRenderer?: WorkflowNextButtonRenderer;
-    readonly previousButtonRenderer?: WorkflowPreviousButtonRenderer;
-    readonly skipButtonRenderer?: WorkflowSkipButtonRenderer;
-}
-interface FormRowRendererProps {
-    row: FormFieldRow;
-    children: React.ReactNode;
-    className?: string;
-    spacing?: 'tight' | 'normal' | 'loose';
-    alignment?: 'start' | 'center' | 'end' | 'stretch';
-}
-interface FormBodyRendererProps {
-    formConfig: FormConfiguration;
-    children: React.ReactNode;
-    className?: string;
-}
-interface FormSubmitButtonRendererProps {
-    isSubmitting: boolean;
-    isValid: boolean;
-    isDirty: boolean;
-    onSubmit: () => void;
-    className?: string;
-    children?: React.ReactNode;
-}
-type FormRowRenderer = (props: FormRowRendererProps) => React.ReactElement;
-type FormBodyRenderer = (props: FormBodyRendererProps) => React.ReactElement;
-type FormSubmitButtonRenderer = (props: FormSubmitButtonRendererProps) => React.ReactElement;
-interface FieldRendererProps {
-    children: React.ReactNode;
-    id: string;
-    error?: ValidationError[];
-    touched?: boolean;
-    disabled?: boolean;
-    isValidating?: boolean;
-    [key: string]: any;
-}
-type FieldRenderer = (props: FieldRendererProps) => React.ReactElement;
-interface FormRenderConfig {
-    readonly rowRenderer?: FormRowRenderer;
-    readonly bodyRenderer?: FormBodyRenderer;
-    readonly submitButtonRenderer?: FormSubmitButtonRenderer;
-    readonly fieldRenderer?: FieldRenderer;
-}
-interface FormConfiguration<C extends Record<string, any> = Record<string, never>> {
-    readonly id: string;
-    readonly schema?: any;
-    readonly config: ril<C>;
-    readonly rows: FormFieldRow[];
-    readonly allFields: FormFieldConfig[];
-    readonly renderConfig?: FormRenderConfig;
-}
-interface WorkflowNextButtonRendererProps {
+type WorkflowNextButtonRendererProps = WorkflowComponentRendererBaseProps & {
     isLastStep: boolean;
     canGoNext: boolean;
     isSubmitting: boolean;
-    onNext: (event?: React.FormEvent) => void;
-    onSubmit: (event?: React.FormEvent) => void;
-    className?: string;
-    children?: React.ReactNode;
-    currentStep: StepConfig;
-    stepData: Record<string, any>;
-    allData: Record<string, any>;
-    context: WorkflowContext;
-}
-interface WorkflowPreviousButtonRendererProps {
+    onSubmit: (event?: React__default.FormEvent) => void;
+};
+type WorkflowPreviousButtonRendererProps = WorkflowComponentRendererBaseProps & {
     canGoPrevious: boolean;
-    onPrevious: (event?: React.FormEvent) => void;
-    className?: string;
-    children?: React.ReactNode;
-    currentStep: StepConfig;
-    stepData: Record<string, any>;
-    allData: Record<string, any>;
-    context: WorkflowContext;
-}
-interface WorkflowSkipButtonRendererProps {
+    onPrevious: (event?: React__default.FormEvent) => void;
+};
+type WorkflowSkipButtonRendererProps = WorkflowComponentRendererBaseProps & {
     canSkip: boolean;
-    onSkip: (event?: React.FormEvent) => void;
-    className?: string;
-    children?: React.ReactNode;
-    currentStep: StepConfig;
-    stepData: Record<string, any>;
-    allData: Record<string, any>;
-    context: WorkflowContext;
-}
-type WorkflowNextButtonRenderer = (props: WorkflowNextButtonRendererProps) => React.ReactElement;
-type WorkflowPreviousButtonRenderer = (props: WorkflowPreviousButtonRendererProps) => React.ReactElement;
-type WorkflowSkipButtonRenderer = (props: WorkflowSkipButtonRendererProps) => React.ReactElement;
+    onSkip: (event?: React__default.FormEvent) => void;
+};
+type WorkflowStepperRenderer = RendererChildrenFunction<WorkflowStepperRendererProps>;
+type WorkflowNextButtonRenderer = RendererChildrenFunction<WorkflowNextButtonRendererProps>;
+type WorkflowPreviousButtonRenderer = RendererChildrenFunction<WorkflowPreviousButtonRendererProps>;
+type WorkflowSkipButtonRenderer = RendererChildrenFunction<WorkflowSkipButtonRendererProps>;
+
+declare function ComponentRendererWrapper<TProps = any>({ children, renderAs, renderer, name, props: baseProps, }: ComponentRendererWrapperProps<TProps>): React$1.ReactNode;
 
 /**
  * Utility for merging partial configurations into existing objects
@@ -436,26 +398,6 @@ declare class IdGenerator {
     next(prefix: string): string;
     reset(prefix?: string): void;
 }
-/**
- * Validation error builder for consistent error handling
- */
-declare class ValidationErrorBuilder {
-    private errors;
-    add(code: string, message: string, path?: string[]): this;
-    addIf(condition: boolean, code: string, message: string, path?: string[]): this;
-    build(): ValidationError[];
-    hasErrors(): boolean;
-    clear(): this;
-}
-/**
- * Common validation patterns
- */
-declare const ValidationPatterns: {
-    hasValue: (value: any) => boolean;
-    isArray: (value: any) => value is any[];
-    arrayMinLength: (value: any[], min: number) => boolean;
-    arrayMaxLength: (value: any[], max: number) => boolean;
-};
 /**
  * Polymorphic helper for handling single items or arrays
  */
@@ -469,167 +411,416 @@ declare function deepClone<T>(obj: T): T;
  */
 declare function configureObject<T>(target: T, updates: Partial<T>, allowedKeys?: (keyof T)[]): T;
 
+declare function resolveRendererChildren<TProps>(children: React.ReactNode | RendererChildrenFunction<TProps> | undefined, props: TProps): React.ReactNode;
+
 /**
- * Create a `Zod`-based validator
- * @param schema - Zod schema to validate against
- * @returns Validator function
+ * @fileoverview Validation utilities
+ *
+ * This module provides utility functions for working with validation results,
+ * combining validators, and managing validation contexts.
  */
-declare const createZodValidator: <T>(schema: z.ZodSchema<T>) => ValidatorFunction;
+
 /**
- * Create a custom validator from a validation function
- * @param validationFn - Function that returns boolean, string, or Promise
- * @returns Validator function
+ * Creates a validation result object
+ *
+ * @param isValid - Whether the validation passed
+ * @param errors - Array of validation errors (empty if valid)
+ * @returns A complete ValidationResult object
+ *
+ * @example
+ * ```typescript
+ * const result = createValidationResult(false, [
+ *   { message: 'Email is required', code: 'REQUIRED' }
+ * ]);
+ * ```
  */
-declare const createCustomValidator: (validationFn: (value: any, context: ValidationContext) => boolean | string | Promise<boolean | string>) => ValidatorFunction;
+declare function createValidationResult(isValid: boolean, errors?: ValidationError[]): ValidationResult;
 /**
- * Combine multiple validators
- * @param validators - Array of validators to combine
- * @param mode - 'all' (all must pass) or 'any' (at least one must pass)
- * @returns Combined validator function
+ * Combines multiple validation results into a single result
+ *
+ * The combined result is valid only if all input results are valid.
+ * All errors from all results are included in the combined result.
+ *
+ * @param results - Array of ValidationResult objects to combine
+ * @returns A single ValidationResult combining all inputs
+ *
+ * @example
+ * ```typescript
+ * const combined = combineValidationResults([
+ *   emailValidator(value),
+ *   requiredValidator(value),
+ *   minLengthValidator(value)
+ * ]);
+ * ```
  */
-declare const combineValidators: (validators: ValidatorFunction[], mode?: "all" | "any") => ValidatorFunction;
+declare function combineValidationResults(results: ValidationResult[]): ValidationResult;
 /**
- * Create a conditional validator that only runs when condition is met
- * @param condition - Function to determine if validation should run
- * @param validator - Validator to run when condition is true
- * @returns Conditional validator function
+ * Runs multiple synchronous validators and combines their results
+ *
+ * @param validators - Array of validators to run
+ * @param value - The value to validate
+ * @param context - Validation context
+ * @returns Combined validation result
+ *
+ * @example
+ * ```typescript
+ * const result = runValidators([
+ *   required,
+ *   email,
+ *   minLength(5)
+ * ], emailValue, context);
+ * ```
  */
-declare const createConditionalValidator: (condition: (value: any, context: ValidationContext) => boolean, validator: ValidatorFunction) => ValidatorFunction;
+declare function runValidators<T>(validators: FieldValidator<T>[], value: T, context: ValidationContext): ValidationResult;
 /**
- * Common validation patterns
+ * Runs multiple asynchronous validators and combines their results
+ *
+ * @param validators - Array of validators to run (can be sync or async)
+ * @param value - The value to validate
+ * @param context - Validation context
+ * @returns Promise resolving to combined validation result
+ *
+ * @example
+ * ```typescript
+ * const result = await runValidatorsAsync([
+ *   required,
+ *   email,
+ *   checkEmailUnique  // async validator
+ * ], emailValue, context);
+ * ```
  */
-declare const commonValidators: {
-    /**
-     * Required field validator
-     */
-    required: (message?: string) => ValidatorFunction;
-    /**
-     * Email validation
-     */
-    email: (message?: string) => ValidatorFunction;
-    /**
-     * Minimum length validation
-     */
-    minLength: (min: number, message?: string) => ValidatorFunction;
-    /**
-     * Maximum length validation
-     */
-    maxLength: (max: number, message?: string) => ValidatorFunction;
-    /**
-     * Pattern/regex validation
-     */
-    pattern: (regex: RegExp, message?: string) => ValidatorFunction;
-    /**
-     * Number range validation
-     */
-    numberRange: (min?: number, max?: number, message?: string) => ValidatorFunction;
-    /**
-     * URL validation
-     */
-    url: (message?: string) => ValidatorFunction;
-    /**
-     * Phone number validation (basic)
-     */
-    phoneNumber: (message?: string) => ValidatorFunction;
-    /**
-     * Custom async validation with debouncing
-     */
-    asyncValidation: (asyncFn: (value: any, context: ValidationContext) => Promise<boolean | string>, debounceMs?: number) => ValidatorFunction;
-};
+declare function runValidatorsAsync<T>(validators: FieldValidator<T>[], value: T, context: ValidationContext): Promise<ValidationResult>;
 /**
- * Utility to create validation result
- * @param isValid - Whether validation passed
- * @param errors - Array of errors (optional)
- * @returns ValidationResult object
+ * Creates a validation context object
+ *
+ * @param options - Context configuration options
+ * @returns A complete ValidationContext object
+ *
+ * @example
+ * ```typescript
+ * const context = createValidationContext({
+ *   fieldId: 'email',
+ *   formId: 'registration',
+ *   allFormData: { email: 'test@example.com', name: 'John' }
+ * });
+ * ```
  */
-declare const createValidationResult: (isValid: boolean, errors?: ValidationError[]) => ValidationResult;
+declare function createValidationContext(options?: Partial<ValidationContext>): ValidationContext;
+
 /**
- * Utility to create validation error
- * @param code - Error code
- * @param message - Error message
- * @param path - Error path (optional)
- * @returns ValidationError object
+ * @fileoverview Built-in validators
+ *
+ * This module provides a comprehensive set of built-in validators for common
+ * validation scenarios. These validators follow the FieldValidator interface
+ * and can be used standalone or combined with other validators.
  */
-declare const createValidationError: (code: string, message: string, path?: string[]) => ValidationError;
 
 /**
- * LocalStorage persistence adapter
- * Perfect for client-side persistence across browser sessions
- */
-declare class LocalStorageAdapter implements PersistenceAdapter {
-    readonly name = "localStorage";
-    save(key: string, data: WorkflowPersistenceData): Promise<void>;
-    load(key: string): Promise<WorkflowPersistenceData | null>;
-    remove(key: string): Promise<void>;
-    exists(key: string): Promise<boolean>;
-    list(pattern?: string): Promise<string[]>;
-}
-/**
- * SessionStorage persistence adapter
- * Perfect for temporary persistence within a single browser session
- */
-declare class SessionStorageAdapter implements PersistenceAdapter {
-    readonly name = "sessionStorage";
-    save(key: string, data: WorkflowPersistenceData): Promise<void>;
-    load(key: string): Promise<WorkflowPersistenceData | null>;
-    remove(key: string): Promise<void>;
-    exists(key: string): Promise<boolean>;
-    list(pattern?: string): Promise<string[]>;
-}
-/**
- * In-Memory persistence adapter
- * Perfect for testing or temporary workflows
- */
-declare class MemoryAdapter implements PersistenceAdapter {
-    readonly name = "memory";
-    private storage;
-    save(key: string, data: WorkflowPersistenceData): Promise<void>;
-    load(key: string): Promise<WorkflowPersistenceData | null>;
-    remove(key: string): Promise<void>;
-    exists(key: string): Promise<boolean>;
-    list(pattern?: string): Promise<string[]>;
-    clear(): void;
-}
+ * Validates that a value is not empty, null, or undefined
+ *
+ * @param message - Custom error message (optional)
+ * @returns A FieldValidator function
+ *
+ * @example
+ * ```typescript
+ * const nameValidator = required('Name is required');
+ * ```
+ */
+declare function required(message?: string): FieldValidator;
 /**
- * Composite adapter that can use multiple adapters with fallback
- * Perfect for robust persistence with primary/backup strategies
+ * Validates minimum string length
+ *
+ * @param min - Minimum length required
+ * @param message - Custom error message (optional)
+ * @returns A FieldValidator function
+ *
+ * @example
+ * ```typescript
+ * const passwordValidator = minLength(8, 'Password must be at least 8 characters');
+ * ```
  */
-declare class CompositeAdapter implements PersistenceAdapter {
-    private primary;
-    private fallbacks;
-    readonly name = "composite";
-    constructor(primary: PersistenceAdapter, fallbacks?: PersistenceAdapter[]);
-    save(key: string, data: WorkflowPersistenceData): Promise<void>;
-    load(key: string): Promise<WorkflowPersistenceData | null>;
-    remove(key: string): Promise<void>;
-    exists(key: string): Promise<boolean>;
-    list(pattern?: string): Promise<string[]>;
-}
+declare function minLength(min: number, message?: string): FieldValidator<string>;
+/**
+ * Validates maximum string length
+ *
+ * @param max - Maximum length allowed
+ * @param message - Custom error message (optional)
+ * @returns A FieldValidator function
+ *
+ * @example
+ * ```typescript
+ * const bioValidator = maxLength(500, 'Bio must be under 500 characters');
+ * ```
+ */
+declare function maxLength(max: number, message?: string): FieldValidator<string>;
+/**
+ * Validates that a string matches a regular expression pattern
+ *
+ * @param regex - The regular expression pattern
+ * @param message - Custom error message (optional)
+ * @returns A FieldValidator function
+ *
+ * @example
+ * ```typescript
+ * const phoneValidator = pattern(/^\d{3}-\d{3}-\d{4}$/, 'Invalid phone format');
+ * ```
+ */
+declare function pattern(regex: RegExp, message?: string): FieldValidator<string>;
+/**
+ * Email validation using a comprehensive regex pattern
+ *
+ * @param message - Custom error message (optional)
+ * @returns A FieldValidator function
+ *
+ * @example
+ * ```typescript
+ * const emailValidator = email('Please enter a valid email address');
+ * ```
+ */
+declare function email(message?: string): FieldValidator<string>;
+/**
+ * URL validation using a comprehensive regex pattern
+ *
+ * @param message - Custom error message (optional)
+ * @returns A FieldValidator function
+ *
+ * @example
+ * ```typescript
+ * const websiteValidator = url('Please enter a valid URL');
+ * ```
+ */
+declare function url(message?: string): FieldValidator<string>;
+/**
+ * Validates that a value is a valid number
+ *
+ * @param message - Custom error message (optional)
+ * @returns A FieldValidator function
+ *
+ * @example
+ * ```typescript
+ * const ageValidator = number('Age must be a valid number');
+ * ```
+ */
+declare function number(message?: string): FieldValidator<string | number>;
+/**
+ * Validates minimum numeric value
+ *
+ * @param minValue - Minimum value allowed
+ * @param message - Custom error message (optional)
+ * @returns A FieldValidator function
+ *
+ * @example
+ * ```typescript
+ * const ageValidator = min(18, 'Must be at least 18 years old');
+ * ```
+ */
+declare function min(minValue: number, message?: string): FieldValidator<string | number>;
+/**
+ * Validates maximum numeric value
+ *
+ * @param maxValue - Maximum value allowed
+ * @param message - Custom error message (optional)
+ * @returns A FieldValidator function
+ *
+ * @example
+ * ```typescript
+ * const scoreValidator = max(100, 'Score cannot exceed 100');
+ * ```
+ */
+declare function max(maxValue: number, message?: string): FieldValidator<string | number>;
+/**
+ * Creates a custom validator from a validation function
+ *
+ * @param validateFn - Custom validation function
+ * @param message - Error message for failed validation
+ * @param code - Optional error code
+ * @returns A FieldValidator function
+ *
+ * @example
+ * ```typescript
+ * const evenNumberValidator = custom(
+ *   (value) => Number(value) % 2 === 0,
+ *   'Number must be even',
+ *   'NOT_EVEN'
+ * );
+ * ```
+ */
+declare function custom<T>(validateFn: (value: T, context: ValidationContext) => boolean, message: string, code?: string): FieldValidator<T>;
+/**
+ * Creates a validator that checks if a value matches another field's value
+ *
+ * @param targetFieldId - ID of the field to match against
+ * @param message - Custom error message (optional)
+ * @returns A FieldValidator function
+ *
+ * @example
+ * ```typescript
+ * const confirmPasswordValidator = matchField('password', 'Passwords must match');
+ * ```
+ */
+declare function matchField(targetFieldId: string, message?: string): FieldValidator;
+/**
+ * Creates a validator that only validates when a condition is met
+ *
+ * @param condition - Function that determines if validation should run
+ * @param validator - The validator to run conditionally
+ * @returns A FieldValidator function
+ *
+ * @example
+ * ```typescript
+ * const conditionalValidator = when(
+ *   (value, context) => context.allFormData?.userType === 'premium',
+ *   required('Premium users must provide this field')
+ * );
+ * ```
+ */
+declare function when<T>(condition: (value: T, context: ValidationContext) => boolean, validator: FieldValidator<T>): FieldValidator<T>;
+/**
+ * Creates an async custom validator from a validation function
+ *
+ * @param validateFn - Async custom validation function that returns a Promise<boolean>
+ * @param message - Error message for failed validation
+ * @param code - Optional error code
+ * @returns A FieldValidator function that returns a Promise
+ *
+ * @example
+ * ```typescript
+ * const checkEmailUnique = customAsync(
+ *   async (email) => {
+ *     const response = await fetch(`/api/check-email?email=${email}`);
+ *     const data = await response.json();
+ *     return data.isUnique;
+ *   },
+ *   'Email address is already taken',
+ *   'EMAIL_NOT_UNIQUE'
+ * );
+ * ```
+ */
+declare function async<T>(validateFn: (value: T, context: ValidationContext) => Promise<boolean>, message: string, code?: string): FieldValidator<T>;
 
 /**
- * Utility functions to create persistence configurations easily
+ * @fileoverview Validation adapters for popular validation libraries
+ *
+ * This module provides adapters that integrate popular validation libraries
+ * like Zod with Rilay's validation system. Adapters convert external schemas
+ * into Rilay validators while maintaining type safety and error handling.
  */
-declare const persistence: {
-    /**
-     * Create a localStorage-based persistence configuration
-     */
-    localStorage(options?: Partial<PersistenceConfig>): PersistenceConfig;
-    /**
-     * Create a sessionStorage-based persistence configuration
-     */
-    sessionStorage(options?: Partial<PersistenceConfig>): PersistenceConfig;
+
+/**
+ * Generic schema interface that Zod and similar libraries implement
+ */
+interface ZodLikeSchema<T = any> {
+    parse(value: unknown): T;
+    safeParse(value: unknown): {
+        success: true;
+        data: T;
+    } | {
+        success: false;
+        error: {
+            errors: Array<{
+                message: string;
+                path: (string | number)[];
+            }>;
+        };
+    };
+}
+/**
+ * Zod validation adapter that converts Zod schemas into Rilay validators
+ *
+ * This adapter provides seamless integration with Zod schemas, automatically
+ * converting Zod validation errors into Rilay ValidationError objects while
+ * preserving error messages and field paths.
+ *
+ * @example
+ * ```typescript
+ * import { z } from 'zod';
+ * import { createZodAdapter } from '@rilaykit/core';
+ *
+ * const zodAdapter = createZodAdapter();
+ * const emailValidator = zodAdapter.createFieldValidator(
+ *   z.string().email('Invalid email format')
+ * );
+ * ```
+ */
+declare class ZodValidationAdapter implements ValidationAdapter<ZodLikeSchema> {
+    readonly name = "ZodValidationAdapter";
+    readonly version = "1.0.0";
     /**
-     * Create an in-memory persistence configuration (for testing)
+     * Creates a field validator from a Zod schema
+     *
+     * @param schema - The Zod schema to convert
+     * @returns A FieldValidator function compatible with Rilay
+     *
+     * @example
+     * ```typescript
+     * const emailSchema = z.string().email();
+     * const validator = adapter.createFieldValidator(emailSchema);
+     * ```
      */
-    memory(options?: Partial<PersistenceConfig>): PersistenceConfig;
+    createFieldValidator<T>(schema: ZodLikeSchema<T>): FieldValidator<T>;
     /**
-     * Create a custom persistence configuration
+     * Creates a form validator from a Zod object schema
+     *
+     * @param schema - The Zod object schema to convert
+     * @returns A FormValidator function compatible with Rilay
+     *
+     * @example
+     * ```typescript
+     * const formSchema = z.object({
+     *   email: z.string().email(),
+     *   password: z.string().min(8)
+     * });
+     * const validator = adapter.createFormValidator(formSchema);
+     * ```
      */
-    custom(adapter: PersistenceAdapter, options?: Partial<PersistenceConfig>): PersistenceConfig;
-};
+    createFormValidator<T>(schema: ZodLikeSchema<T>): FormValidator<T>;
+}
+/**
+ * Creates a new Zod validation adapter instance
+ *
+ * @returns A configured ZodValidationAdapter instance
+ *
+ * @example
+ * ```typescript
+ * const adapter = createZodAdapter();
+ * ```
+ */
+declare function createZodAdapter(): ZodValidationAdapter;
+/**
+ * Helper function to create a field validator directly from a Zod schema
+ *
+ * This is a convenience function that creates an adapter and field validator
+ * in a single call, useful for simple use cases.
+ *
+ * @param schema - The Zod schema to convert
+ * @returns A FieldValidator function
+ *
+ * @example
+ * ```typescript
+ * import { z } from 'zod';
+ * import { zodFieldValidator } from '@rilaykit/core';
+ *
+ * const emailValidator = zodFieldValidator(z.string().email());
+ * ```
+ */
+declare function zodFieldValidator<T>(schema: ZodLikeSchema<T>): FieldValidator<T>;
 /**
- * Utility to create persistence configurations with retry logic
+ * Helper function to create a form validator directly from a Zod schema
+ *
+ * @param schema - The Zod object schema to convert
+ * @returns A FormValidator function
+ *
+ * @example
+ * ```typescript
+ * import { z } from 'zod';
+ * import { zodFormValidator } from '@rilaykit/core';
+ *
+ * const formValidator = zodFormValidator(z.object({
+ *   email: z.string().email(),
+ *   password: z.string().min(8)
+ * }));
+ * ```
  */
-declare function createResilientPersistence(primary: PersistenceAdapter, fallback?: PersistenceAdapter, options?: Partial<PersistenceConfig>): PersistenceConfig;
+declare function zodFormValidator<T>(schema: ZodLikeSchema<T>): FormValidator<T>;
 
-export { type CompletionConfig, type ComponentConfig, type ComponentRenderProps, type ComponentRenderer, CompositeAdapter, type ConditionalConfig, type CustomStepRenderer, type DynamicStepConfig, type FieldRenderer, type FieldRendererProps, type FormBodyRenderer, type FormBodyRendererProps, type FormConfiguration, type FormFieldConfig, type FormFieldRow, type FormRenderConfig, type FormRowRenderer, type FormRowRendererProps, type FormSubmitButtonRenderer, type FormSubmitButtonRendererProps, IdGenerator, LocalStorageAdapter, MemoryAdapter, type NavigationConfig, type PersistenceAdapter, type PersistenceConfig, type RendererChildrenFunction, type RetryPolicy, type RilayLicenseConfig, SessionStorageAdapter, type StepConditionalConfig, type StepConfig, type StepLifecycleHooks, type StepPermissions, type StepValidationConfig, type ValidationConfig, type ValidationContext, type ValidationError, ValidationErrorBuilder, ValidationPatterns, type ValidationResult, type ValidatorFunction, type WorkflowAnalytics, type WorkflowConfig, type WorkflowContext, type WorkflowHooks, type WorkflowNextButtonRenderer, type WorkflowNextButtonRendererProps, type WorkflowPersistenceData, type WorkflowPlugin, type WorkflowPreviousButtonRenderer, type WorkflowPreviousButtonRendererProps, type WorkflowRenderConfig, type WorkflowSkipButtonRenderer, type WorkflowSkipButtonRendererProps, type WorkflowStepperRenderer, type WorkflowStepperRendererProps, combineValidators, commonValidators, configureObject, createConditionalValidator, createCustomValidator, createResilientPersistence, createValidationError, createValidationResult, createZodValidator, deepClone, ensureUnique, mergeInto, normalizeToArray, persistence, resolveRendererChildren, ril, validateRequired };
+export { type ComponentConfig, type ComponentRenderProps, type ComponentRenderer, type ComponentRendererBaseProps, ComponentRendererWrapper, type ComponentRendererWrapperProps, type CustomStepRenderer, type FieldRenderer, type FieldRendererProps, type FieldValidationConfig, type FieldValidator, type FormBodyRenderer, type FormBodyRendererProps, type FormComponentRendererProps, type FormConfiguration, type FormFieldConfig, type FormFieldRow, type FormRenderConfig, type FormRowRenderer, type FormRowRendererProps, type FormSubmitButtonRenderer, type FormSubmitButtonRendererProps, type FormValidationConfig, type FormValidator, IdGenerator, type RendererChildrenFunction, type RilayLicenseConfig, type StepConfig, type StepDataHelper, type ValidationAdapter, type ValidationContext, type ValidationError, type ValidationResult, type ValidationSchema, type WorkflowAnalytics, type WorkflowComponentRendererBaseProps, type WorkflowConfig, type WorkflowContext, type WorkflowNextButtonRenderer, type WorkflowNextButtonRendererProps, type WorkflowPlugin, type WorkflowPreviousButtonRenderer, type WorkflowPreviousButtonRendererProps, type WorkflowRenderConfig, type WorkflowSkipButtonRenderer, type WorkflowSkipButtonRendererProps, type WorkflowStepperRenderer, type WorkflowStepperRendererProps, async, combineValidationResults, configureObject, createValidationContext, createValidationResult, createZodAdapter, custom, deepClone, email, ensureUnique, matchField, max, maxLength, mergeInto, min, minLength, normalizeToArray, number, pattern, required, resolveRendererChildren, ril, runValidators, runValidatorsAsync, url, validateRequired, when, zodFieldValidator, zodFormValidator };