@formality-ui/core 0.0.0

package/dist/index.d.ts

@@ -0,0 +1,1182 @@
+/**
+ * ConditionDescriptor - Defines a single condition rule
+ *
+ * Conditions control disabled, visible, and setValue behaviors based on
+ * form state. Each condition has a trigger (when/selectWhen), optional
+ * matchers (is/truthy), and actions (disabled/visible/set/selectSet).
+ */
+interface ConditionDescriptor {
+    /**
+     * Simple field reference trigger
+     * Example: "client" - triggers when client field has a value
+     */
+    when?: string;
+    /**
+     * Expression or function trigger
+     * Example: "client.id > 5" or ({ fields }) => fields.client?.value?.id > 5
+     */
+    selectWhen?: SelectValue<boolean>;
+    /**
+     * Exact value match
+     * When true, condition matches if trigger value === is value
+     */
+    is?: unknown;
+    /**
+     * Truthy/falsy check
+     * true: matches if trigger is truthy
+     * false: matches if trigger is falsy
+     */
+    truthy?: boolean;
+    /**
+     * Set disabled state
+     * Multiple conditions use OR logic (any true = disabled)
+     */
+    disabled?: boolean;
+    /**
+     * Set visible state
+     * Multiple conditions use AND logic (any false = hidden)
+     */
+    visible?: boolean;
+    /**
+     * Set static value when condition matches
+     * Last matching condition wins
+     */
+    set?: unknown;
+    /**
+     * Set dynamic value from expression or function
+     * Last matching condition wins
+     */
+    selectSet?: SelectValue;
+    /**
+     * Explicit field subscriptions for function-based conditions
+     * REQUIRED when using functions in selectWhen or selectSet
+     */
+    subscribesTo?: string[];
+}
+/**
+ * ConditionResult - Result of evaluating all conditions for a field/group
+ *
+ * Contains the resolved disabled/visible states and any setValue operation.
+ */
+interface ConditionResult {
+    /**
+     * Resolved disabled state
+     * undefined = no condition set disabled
+     * true = at least one condition set disabled: true
+     */
+    disabled: boolean | undefined;
+    /**
+     * Resolved visible state
+     * undefined = no condition set visible
+     * true = all conditions with visible set it to true
+     * false = at least one condition set visible: false
+     */
+    visible: boolean | undefined;
+    /**
+     * Value to set (from last matching set/selectSet condition)
+     * undefined = no condition set a value
+     */
+    setValue: unknown | undefined;
+    /** Was any condition's disabled action evaluated */
+    hasDisabledCondition: boolean;
+    /** Was any condition's visible action evaluated */
+    hasVisibleCondition: boolean;
+    /** Was any condition's set/selectSet action evaluated */
+    hasSetCondition: boolean;
+}
+
+/**
+ * ValidationResult - Result from a validator function
+ *
+ * true | undefined = valid
+ * false = invalid (use generic/default message)
+ * string = invalid with custom message
+ * { type, message? } = invalid with type key for error message lookup
+ */
+type ValidationResult = true | false | string | undefined | {
+    type: string;
+    message?: string;
+};
+/**
+ * ValidatorFunction - Inline validator signature
+ *
+ * @param value - The field value to validate
+ * @param formValues - All form values for cross-field validation
+ * @returns Validation result (sync or async)
+ */
+type ValidatorFunction = (value: unknown, formValues: Record<string, unknown>) => ValidationResult | Promise<ValidationResult>;
+/**
+ * ValidatorSpec - Validator specification
+ *
+ * Can be:
+ * - string: Named validator lookup from provider
+ * - function: Inline validator
+ * - array: Multiple validators run in sequence
+ */
+type ValidatorSpec = string | ValidatorFunction | Array<string | ValidatorFunction>;
+/**
+ * ValidatorFactory - Factory function for parameterized validators
+ *
+ * Example: minLength(5) returns a ValidatorFunction
+ */
+type ValidatorFactory<TArgs = unknown> = (args: TArgs) => ValidatorFunction;
+/**
+ * ValidatorsConfig - Named validators configuration
+ *
+ * Values can be direct validators or validator factories
+ */
+interface ValidatorsConfig {
+    [name: string]: ValidatorFunction | ValidatorFactory;
+}
+/**
+ * ErrorMessagesConfig - Error message templates by type key
+ *
+ * Used to resolve error messages from validation result types
+ */
+interface ErrorMessagesConfig {
+    [type: string]: string;
+}
+
+/**
+ * FieldError - Error object for a field
+ */
+interface FieldError {
+    /** Error type identifier (e.g., 'required', 'pattern', 'validate') */
+    type: string;
+    /** Human-readable error message */
+    message?: string;
+}
+/**
+ * FieldState - Current state of a single field
+ *
+ * Used in expressions and condition evaluation.
+ */
+interface FieldState {
+    /** Current field value */
+    value: unknown;
+    /** Has the field been touched (focused then blurred) */
+    isTouched: boolean;
+    /** Has the value changed from default */
+    isDirty: boolean;
+    /** Is async validation currently running */
+    isValidating: boolean;
+    /** Current validation error (if any) */
+    error?: FieldError;
+    /** Inverse of valid state for convenience */
+    invalid: boolean;
+    /** Map of subscriber field names watching this field */
+    watchers?: Record<string, boolean>;
+}
+/**
+ * FormState - Complete form state
+ *
+ * Available in all expression evaluations and conditions.
+ */
+interface FormState {
+    /** Map of field names to their current states */
+    fields: Record<string, FieldState>;
+    /** Original record passed to Form (for expression access) */
+    record?: Record<string, unknown>;
+    /** Map of field names to their errors */
+    errors: Record<string, FieldError | undefined>;
+    /** Initial/default values for all fields */
+    defaultValues: Record<string, unknown>;
+    /** Map of touched field names */
+    touchedFields: Record<string, boolean>;
+    /** Map of dirty field names */
+    dirtyFields: Record<string, boolean>;
+    /** Has any field been modified */
+    isDirty: boolean;
+    /** Has any field been touched */
+    isTouched: boolean;
+    /** Are all fields valid */
+    isValid: boolean;
+    /** Is form submission in progress */
+    isSubmitting: boolean;
+    /**
+     * Field-level props context for expression evaluation
+     * Only available in field-level expressions (e.g., selectProps)
+     */
+    props?: {
+        /** Current field name - allows expressions like "props.name" */
+        name: string;
+        /** Additional field-specific props */
+        [key: string]: unknown;
+    };
+}
+
+/**
+ * SelectValue - The core polymorphic type for all select* properties
+ *
+ * CRITICAL: When using functions, automatic field inference is NOT possible.
+ * You MUST provide explicit `subscribesTo` to declare dependencies.
+ */
+type SelectValue<TReturn = unknown> = string | SelectFunction<TReturn> | {
+    [key: string]: SelectValue;
+} | SelectValue[];
+/**
+ * SelectFunction - Callback signature for function-based select values
+ *
+ * @param formState - Current form state with fields, record, errors, etc.
+ * @param methods - Form methods (framework-specific, typed as unknown for core)
+ * @returns The computed value
+ *
+ * IMPORTANT: When using SelectFunction, you MUST specify subscribesTo
+ * because automatic dependency inference cannot analyze function bodies.
+ */
+type SelectFunction<TReturn = unknown> = (formState: FormState, methods: unknown) => TReturn;
+/**
+ * InputConfig - Configuration for an input component type
+ *
+ * This defines how a particular input type (e.g., textField, switch, autocomplete)
+ * behaves across all forms.
+ */
+interface InputConfig<TValue = unknown> {
+    /** The React component to render */
+    component: unknown;
+    /** Default value for this input type (e.g., '' for text, false for switch) */
+    defaultValue: TValue;
+    /** Debounce milliseconds for validation/auto-save. false = immediate, number = delay */
+    debounce?: number | false;
+    /** Prop name for passing value to component (default: 'value') */
+    inputFieldProp?: string;
+    /** For complex values (objects), which property contains the actual value */
+    valueField?: string;
+    /** Transform field name for submission (e.g., 'client' → 'clientId') */
+    getSubmitField?: (fieldName: string) => string;
+    /** Transform user input to form value. String = named parser, function = inline */
+    parser?: string | ((value: unknown) => TValue);
+    /** Transform form value to display value. String = named formatter, function = inline */
+    formatter?: string | ((value: TValue) => unknown);
+    /** Type-level validation (runs after field-level validator) */
+    validator?: ValidatorSpec;
+    /** Template component wrapper for consistent styling */
+    template?: unknown;
+    /** Default props for this input type */
+    props?: Record<string, unknown>;
+}
+/**
+ * FieldConfig - Configuration for a specific field instance
+ *
+ * This defines field-level behavior including conditions, validation,
+ * and dynamic props.
+ */
+interface FieldConfig {
+    /** Input type key (resolves to InputConfig) */
+    type?: string;
+    /** Human-readable label (static) */
+    label?: string;
+    /** Alias for label (legacy support) */
+    title?: string;
+    /** Static disabled state (can be overridden by conditions) */
+    disabled?: boolean;
+    /** Static hidden state (can be overridden by conditions) */
+    hidden?: boolean;
+    /** Display order for config-driven rendering (lower = earlier) */
+    order?: number;
+    /** Key to use when reading initial value from record (defaults to field name) */
+    recordKey?: string;
+    /** React Hook Form RegisterOptions (required, min, max, pattern, etc.) */
+    rules?: Record<string, unknown>;
+    /** Field-level validation (runs before type-level validator) */
+    validator?: ValidatorSpec;
+    /** Static props merged before selectProps */
+    props?: Record<string, unknown>;
+    /** Dynamic props evaluated against form state */
+    selectProps?: SelectValue<Record<string, unknown>>;
+    /** Condition descriptors for disabled/visible/setValue behaviors */
+    conditions?: ConditionDescriptor[];
+    /** Explicit field subscriptions (REQUIRED when using functions in selectProps) */
+    subscribesTo?: string[];
+    /** Pass field state to component (value, error, touched, etc.) */
+    provideState?: boolean;
+    /** Pass subscribed field states to component */
+    passSubscriptions?: boolean;
+    /** Prop name for subscribed states (default: 'state') */
+    passSubscriptionsAs?: string;
+}
+/**
+ * FormFieldsConfig - Map of field names to their configurations
+ */
+type FormFieldsConfig = Record<string, FieldConfig>;
+/**
+ * GroupConfig - Configuration for a FieldGroup
+ */
+interface GroupConfig {
+    /** Conditions for group-level disabled/visible state */
+    conditions?: ConditionDescriptor[];
+    /** Explicit subscriptions for function-based conditions */
+    subscribesTo?: string[];
+}
+/**
+ * FormConfig - Form-level configuration
+ *
+ * Overrides provider settings and applies to all fields in the form.
+ */
+interface FormConfig {
+    /**
+     * Input type overrides - can be object OR function
+     * Function form allows dynamic modification based on all available inputs
+     */
+    inputs?: Record<string, Partial<InputConfig>> | ((allInputs: Record<string, InputConfig>) => Record<string, Partial<InputConfig>>);
+    /** Named field groups with their conditions */
+    groups?: Record<string, GroupConfig>;
+    /** Static default props for all fields in this form */
+    defaultFieldProps?: Record<string, unknown>;
+    /** Dynamic default props evaluated per-field */
+    selectDefaultFieldProps?: SelectValue;
+    /** Static form title */
+    title?: string;
+    /** Dynamic form title evaluated against form state */
+    selectTitle?: SelectValue<string>;
+}
+/**
+ * FormalityProviderConfig - Global provider configuration
+ *
+ * Sets up input types, transformers, validators, and global defaults.
+ */
+interface FormalityProviderConfig {
+    /** Input type definitions */
+    inputs: Record<string, InputConfig>;
+    /** Named formatters for value → display transformation */
+    formatters?: Record<string, (value: unknown) => unknown>;
+    /** Named parsers for input → value transformation */
+    parsers?: Record<string, (value: unknown) => unknown>;
+    /** Named validators and validator factories */
+    validators?: ValidatorsConfig;
+    /** Error message templates by type key */
+    errorMessages?: ErrorMessagesConfig;
+    /** Default template for all inputs */
+    defaultInputTemplate?: unknown;
+    /** Named templates for specific input types */
+    inputTemplates?: Record<string, unknown>;
+    /** Default prop name for passSubscriptions (default: 'state') */
+    defaultSubscriptionPropName?: string;
+    /** Static default props for all fields */
+    defaultFieldProps?: Record<string, unknown>;
+    /** Dynamic default props evaluated per-field */
+    selectDefaultFieldProps?: SelectValue;
+}
+/**
+ * InputTemplateProps - Props passed to input template components
+ */
+interface InputTemplateProps {
+    /** The input component to render */
+    Field: unknown;
+    /** Merged props to pass to the component */
+    fieldProps: Record<string, unknown>;
+    /** Current field state */
+    fieldState: Record<string, unknown>;
+    /** Current form state */
+    formState: FormState;
+}
+
+/**
+ * Evaluation context type
+ */
+type EvaluationContext = Record<string, unknown>;
+/**
+ * Evaluate a string expression against a context object
+ *
+ * @param expr - Expression string (e.g., "client.id", "client && signed")
+ * @param context - Evaluation context with field values
+ * @returns The evaluated result
+ *
+ * @example
+ * evaluate("client.id", { client: { id: 5 } }) // → 5
+ * evaluate("client && signed", { client: { id: 5 }, signed: true }) // → true
+ * evaluate("signed ? 'Yes' : 'No'", { signed: true }) // → 'Yes'
+ */
+declare function evaluate(expr: string, context: EvaluationContext): unknown;
+/**
+ * Evaluate a SelectValue descriptor
+ *
+ * Handles string expressions, objects with nested expressions, and arrays.
+ * Does NOT handle functions - those must be handled by the framework adapter.
+ *
+ * @param descriptor - The SelectValue to evaluate
+ * @param context - Evaluation context
+ * @returns The evaluated result
+ */
+declare function evaluateDescriptor(descriptor: unknown, context: EvaluationContext): unknown;
+/**
+ * Clear the expression AST cache
+ * Useful for testing or memory management
+ */
+declare function clearExpressionCache(): void;
+
+/**
+ * Qualified prefixes that should NOT be auto-transformed
+ */
+declare const QUALIFIED_PREFIXES: readonly ["fields", "record", "errors", "defaultValues", "touchedFields", "dirtyFields", "props"];
+/**
+ * JavaScript keywords to skip during field inference
+ */
+declare const KEYWORDS: readonly ["true", "false", "null", "undefined", "typeof", "instanceof", "new", "this", "if", "else", "return"];
+/**
+ * Symbol to identify field state proxies for unwrapping in expressions
+ */
+declare const FIELD_PROXY_MARKER: unique symbol;
+/**
+ * Symbol to get the raw value from a field proxy
+ */
+declare const FIELD_PROXY_VALUE: unique symbol;
+/**
+ * Create a proxy for a field state that:
+ * - Returns field state properties (isTouched, isDirty, etc.) when accessed
+ * - Delegates unknown properties to value[prop] for object values
+ * - Coerces to the value for primitive operations
+ *
+ * This allows both:
+ * - `client` and `client.value` to return the same thing
+ * - `client.isTouched` to return the touched state
+ * - `client.id` to return value.id (for object values)
+ */
+declare function createFieldStateProxy(fieldState: FieldState | {
+    value: unknown;
+}): unknown;
+/**
+ * Check if a value is a field state proxy
+ */
+declare function isFieldProxy(value: unknown): boolean;
+/**
+ * Unwrap a field proxy to get its primitive value for boolean/comparison contexts
+ */
+declare function unwrapFieldProxy(value: unknown): unknown;
+/**
+ * Build evaluation context for form-level expressions
+ *
+ * Implements Dual Context Mapping:
+ * - Provides field values at BOTH qualified (fields.client.value) AND unqualified (client) levels
+ * - Qualified paths take precedence on name collision
+ *
+ * @param fields - Map of field names to field states
+ * @param record - Original record passed to form
+ * @param errors - Map of field names to errors
+ * @param defaultValues - Initial/default values for fields
+ * @param touchedFields - Map of touched field names
+ * @param dirtyFields - Map of dirty field names
+ * @returns Evaluation context object
+ */
+declare function buildFormContext(fields: Record<string, FieldState>, record?: Record<string, unknown>, errors?: Record<string, FieldError | undefined>, defaultValues?: Record<string, unknown>, touchedFields?: Record<string, boolean>, dirtyFields?: Record<string, boolean>): Record<string, unknown>;
+/**
+ * Build evaluation context for field-level expressions
+ *
+ * Extends form context with field-specific props (including field name).
+ * This enables expressions like "props.name" to resolve to the current field name.
+ *
+ * @param formState - Complete form state
+ * @param fieldName - Current field name (added to props.name)
+ * @param additionalProps - Additional props to merge
+ * @returns Evaluation context object
+ */
+declare function buildFieldContext(formState: FormState, fieldName: string, additionalProps?: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Field state input for building evaluation context
+ */
+interface FieldStateForContext {
+    value: unknown;
+    isTouched?: boolean;
+    isDirty?: boolean;
+    isValidating?: boolean;
+    error?: unknown;
+    invalid?: boolean;
+}
+/**
+ * Build a minimal evaluation context from field values
+ *
+ * Used when you only have raw values (not full FieldState objects).
+ * Useful for condition evaluation with watched values.
+ *
+ * @param fieldValues - Map of field names to their current values
+ * @param record - Optional record for record.* access
+ * @param props - Optional props for props.* access
+ * @param fieldStates - Optional full field states with metadata (isTouched, isDirty, etc.)
+ * @returns Evaluation context object
+ */
+declare function buildEvaluationContext(fieldValues: Record<string, unknown>, record?: Record<string, unknown>, props?: Record<string, unknown>, fieldStates?: Record<string, FieldStateForContext>): Record<string, unknown>;
+
+/**
+ * Extract field names from an expression string
+ *
+ * Scans the expression for unqualified identifiers that represent field names.
+ * Skips JavaScript keywords. Qualified prefixes (fields, record, props, etc.)
+ * are only skipped when followed by a dot.
+ *
+ * @param expr - Expression string to analyze
+ * @returns Array of unique field names referenced
+ *
+ * @example
+ * inferFieldsFromExpression("client.id") // → ["client"]
+ * inferFieldsFromExpression("client && signed") // → ["client", "signed"]
+ * inferFieldsFromExpression("record.name") // → [] (qualified path)
+ * inferFieldsFromExpression("true && false") // → [] (keywords)
+ * inferFieldsFromExpression("fields === null") // → ["fields"] (not followed by dot)
+ */
+declare function inferFieldsFromExpression(expr: string): string[];
+/**
+ * Extract field dependencies from a SelectValue descriptor
+ *
+ * Recursively processes string expressions, objects, and arrays.
+ * Does NOT analyze function bodies - those require explicit subscribesTo.
+ *
+ * @param descriptor - SelectValue to analyze (string, object, array, or function)
+ * @returns Array of unique field names referenced
+ *
+ * @example
+ * inferFieldsFromDescriptor("client.id") // → ["client"]
+ * inferFieldsFromDescriptor({ queryParams: "client.id", filter: "signed" }) // → ["client", "signed"]
+ * inferFieldsFromDescriptor(["client", "contact.name"]) // → ["client", "contact"]
+ * inferFieldsFromDescriptor(() => {}) // → [] (functions need explicit subscribesTo)
+ */
+declare function inferFieldsFromDescriptor(descriptor: unknown): string[];
+
+/**
+ * Field state with metadata for expression evaluation
+ */
+interface FieldStateInput {
+    value: unknown;
+    isTouched?: boolean;
+    isDirty?: boolean;
+    isValidating?: boolean;
+    error?: unknown;
+    invalid?: boolean;
+}
+/**
+ * Input for condition evaluation
+ */
+interface EvaluateConditionsInput {
+    /** Array of conditions to evaluate */
+    conditions: ConditionDescriptor[];
+    /** Map of field names to their current values */
+    fieldValues: Record<string, unknown>;
+    /** Optional: Full field states with metadata (isTouched, isDirty, etc.) */
+    fieldStates?: Record<string, FieldStateInput>;
+    /** Original record passed to form */
+    record?: Record<string, unknown>;
+    /** Additional props for expression context */
+    props?: Record<string, unknown>;
+}
+/**
+ * Evaluate all conditions for a field/group
+ *
+ * Implements the condition evaluation rules:
+ * - disabled: OR logic (any true = true)
+ * - visible: AND logic (any false = false)
+ * - setValue: last matching condition wins
+ *
+ * @param input - Evaluation input with conditions and state
+ * @returns Result with resolved disabled, visible, and setValue states
+ *
+ * @example
+ * const result = evaluateConditions({
+ *   conditions: [
+ *     { when: 'signed', is: false, disabled: true },
+ *     { when: 'archived', truthy: true, visible: false },
+ *   ],
+ *   fieldValues: { signed: false, archived: true },
+ * });
+ * // result.disabled === true (signed is false, matches first condition)
+ * // result.visible === false (archived is truthy, matches second condition)
+ */
+declare function evaluateConditions(input: EvaluateConditionsInput): ConditionResult;
+/**
+ * Evaluate a single condition's match (without applying actions)
+ *
+ * Useful for checking if a condition would match without computing results.
+ *
+ * @param condition - The condition to check
+ * @param fieldValues - Map of field names to their current values
+ * @param record - Optional record for expression context
+ * @param props - Optional props for expression context
+ * @returns true if the condition matches
+ */
+declare function conditionMatches(condition: ConditionDescriptor, fieldValues: Record<string, unknown>, record?: Record<string, unknown>, props?: Record<string, unknown>): boolean;
+/**
+ * Merge condition results from multiple sources (e.g., group + field)
+ *
+ * Follows the same cumulative logic:
+ * - disabled: OR logic
+ * - visible: AND logic
+ * - setValue: later source wins
+ *
+ * @param results - Array of condition results to merge
+ * @returns Merged result
+ */
+declare function mergeConditionResults(results: ConditionResult[]): ConditionResult;
+/**
+ * Extract field dependencies from an array of conditions
+ *
+ * Collects 'when' field references and infers dependencies from
+ * 'selectWhen' and 'selectSet' expressions. Used for automatic subscription.
+ *
+ * @param conditions - Array of condition descriptors
+ * @returns Array of unique field names referenced
+ *
+ * @example
+ * inferFieldsFromConditions([
+ *   { when: 'client', disabled: true },
+ *   { selectWhen: 'signed && approved', visible: true },
+ * ])
+ * // → ['client', 'signed', 'approved']
+ */
+declare function inferFieldsFromConditions(conditions: ConditionDescriptor[]): string[];
+
+/**
+ * Run a validator specification against a value
+ *
+ * Supports:
+ * - string: Named validator lookup
+ * - function: Inline validator
+ * - array: Multiple validators in sequence (short-circuits on first failure)
+ *
+ * @param spec - Validator specification
+ * @param value - Value to validate
+ * @param formValues - All form values for cross-field validation
+ * @param namedValidators - Named validators config from provider
+ * @returns Validation result (may be a Promise)
+ *
+ * @example
+ * // Named validator
+ * runValidator('required', '', {}, validators)
+ *
+ * // Inline validator
+ * runValidator((val) => val ? true : 'Required', '', {})
+ *
+ * // Multiple validators
+ * runValidator(['required', 'email'], '', {}, validators)
+ */
+declare function runValidator(spec: ValidatorSpec, value: unknown, formValues: Record<string, unknown>, namedValidators?: ValidatorsConfig): Promise<ValidationResult>;
+/**
+ * Run validator synchronously (for validators known to be sync)
+ *
+ * @param spec - Validator specification
+ * @param value - Value to validate
+ * @param formValues - All form values
+ * @param namedValidators - Named validators config
+ * @returns Validation result
+ */
+declare function runValidatorSync(spec: ValidatorSpec, value: unknown, formValues: Record<string, unknown>, namedValidators?: ValidatorsConfig): ValidationResult;
+/**
+ * Check if a validation result indicates success
+ *
+ * @param result - Validation result to check
+ * @returns true if valid, false if invalid
+ */
+declare function isValid(result: ValidationResult): boolean;
+/**
+ * Combine multiple validators into a single validator function
+ *
+ * @param validators - Array of validator specs to combine
+ * @param namedValidators - Named validators config
+ * @returns Combined validator function
+ */
+declare function composeValidators(validators: ValidatorSpec[], namedValidators?: ValidatorsConfig): ValidatorFunction;
+/**
+ * Create a required validator
+ *
+ * @returns Validator function that checks for non-empty values
+ */
+declare function required(): ValidatorFunction;
+/**
+ * Create a minLength validator factory
+ *
+ * @param length - Minimum length
+ * @returns Validator function
+ */
+declare function minLength(length: number): ValidatorFunction;
+/**
+ * Create a maxLength validator factory
+ *
+ * @param length - Maximum length
+ * @returns Validator function
+ */
+declare function maxLength(length: number): ValidatorFunction;
+/**
+ * Create a pattern validator factory
+ *
+ * @param pattern - RegExp pattern to match
+ * @param message - Custom error message
+ * @returns Validator function
+ */
+declare function pattern(pattern: RegExp, message?: string): ValidatorFunction;
+
+/**
+ * Resolve an error message from a validation result
+ *
+ * Handles all ValidationResult types:
+ * - true/undefined → undefined (valid, no message)
+ * - false → lookup 'invalid' in errorMessages or use default
+ * - string → use string directly as message
+ * - { type, message? } → use message or lookup type in errorMessages
+ *
+ * @param result - Validation result to resolve
+ * @param errorMessages - Error message templates by type key
+ * @returns Error message string or undefined if valid
+ *
+ * @example
+ * resolveErrorMessage(false, {}) // → 'Invalid value'
+ * resolveErrorMessage('Custom error', {}) // → 'Custom error'
+ * resolveErrorMessage({ type: 'required' }, { required: 'This is required' }) // → 'This is required'
+ */
+declare function resolveErrorMessage(result: ValidationResult, errorMessages?: ErrorMessagesConfig): string | undefined;
+/**
+ * Format a validation type key into a human-readable message
+ *
+ * @param type - Type key (e.g., 'required', 'minLength')
+ * @returns Formatted message
+ *
+ * @example
+ * formatTypeAsMessage('required') // → 'Required'
+ * formatTypeAsMessage('minLength') // → 'Min length'
+ * formatTypeAsMessage('maxLength') // → 'Max length'
+ */
+declare function formatTypeAsMessage(type: string): string;
+/**
+ * Create an error messages config with default messages
+ *
+ * @param overrides - Custom error messages to merge with defaults
+ * @returns Complete error messages config
+ */
+declare function createErrorMessages(overrides?: ErrorMessagesConfig): ErrorMessagesConfig;
+/**
+ * Extract error type from a validation result
+ *
+ * @param result - Validation result
+ * @returns Error type string or undefined if valid
+ */
+declare function getErrorType(result: ValidationResult): string | undefined;
+/**
+ * Create a validation error object
+ *
+ * @param type - Error type
+ * @param message - Error message (optional, will be resolved from errorMessages)
+ * @param errorMessages - Error messages config
+ * @returns Error object with type and message
+ */
+declare function createValidationError(type: string, message?: string, errorMessages?: ErrorMessagesConfig): {
+    type: string;
+    message: string;
+};
+
+/**
+ * Parser function type
+ * Transforms user input into form value
+ */
+type ParserFunction = (value: unknown) => unknown;
+/**
+ * Formatter function type
+ * Transforms form value into display value
+ */
+type FormatterFunction = (value: unknown) => unknown;
+/**
+ * Parser specification - can be a named parser or inline function
+ */
+type ParserSpec = string | ParserFunction;
+/**
+ * Formatter specification - can be a named formatter or inline function
+ */
+type FormatterSpec = string | FormatterFunction;
+/**
+ * Named parsers configuration
+ */
+type ParsersConfig = Record<string, ParserFunction>;
+/**
+ * Named formatters configuration
+ */
+type FormattersConfig = Record<string, FormatterFunction>;
+/**
+ * Parse an input value using a parser specification
+ *
+ * Used on onChange to transform user input into form value.
+ *
+ * @param value - Raw input value from component
+ * @param parserSpec - Parser specification (name or function)
+ * @param namedParsers - Named parsers config from provider
+ * @returns Parsed value for form state
+ *
+ * @example
+ * // Named parser
+ * parse("42.69", "float", { float: v => parseFloat(String(v)) || 0 })
+ * // → 42.69
+ *
+ * // Inline parser
+ * parse("42.69", v => parseFloat(String(v)) || 0)
+ * // → 42.69
+ */
+declare function parse(value: unknown, parserSpec?: ParserSpec, namedParsers?: ParsersConfig): unknown;
+/**
+ * Format a form value using a formatter specification
+ *
+ * Used on render to transform form value into display value.
+ *
+ * @param value - Form state value
+ * @param formatterSpec - Formatter specification (name or function)
+ * @param namedFormatters - Named formatters config from provider
+ * @returns Formatted value for display
+ *
+ * @example
+ * // Named formatter
+ * format(42.69, "float", { float: v => typeof v === 'number' ? v.toFixed(2) : '' })
+ * // → "42.69"
+ *
+ * // Inline formatter
+ * format(42.69, v => typeof v === 'number' ? v.toFixed(2) : '')
+ * // → "42.69"
+ */
+declare function format(value: unknown, formatterSpec?: FormatterSpec, namedFormatters?: FormattersConfig): unknown;
+/**
+ * Extract the actual value from a complex object using valueField
+ *
+ * Used for autocomplete/select components that store objects but need to
+ * extract a specific property for submission.
+ *
+ * @param value - Complex value (object or primitive)
+ * @param valueField - Property name to extract
+ * @returns Extracted value or original value if not applicable
+ *
+ * @example
+ * extractValueField({ id: 5, name: "Acme" }, "id")
+ * // → 5
+ *
+ * extractValueField("simple", "id")
+ * // → "simple" (no extraction needed)
+ */
+declare function extractValueField(value: unknown, valueField?: string): unknown;
+/**
+ * Transform a field name for submission
+ *
+ * Used for fields that need a different name in the submitted data.
+ * Example: "client" field with getSubmitField → "clientId"
+ *
+ * @param fieldName - Original field name
+ * @param getSubmitField - Transform function
+ * @returns Transformed field name
+ *
+ * @example
+ * transformFieldName("client", name => `${name}Id`)
+ * // → "clientId"
+ */
+declare function transformFieldName(fieldName: string, getSubmitField?: (name: string) => string): string;
+/**
+ * Create a float parser with configurable behavior
+ *
+ * @param fallback - Value to return on parse failure (default: 0)
+ * @returns Parser function
+ */
+declare function createFloatParser(fallback?: number): ParserFunction;
+/**
+ * Create a float formatter with configurable precision
+ *
+ * @param precision - Number of decimal places (default: 2)
+ * @returns Formatter function
+ */
+declare function createFloatFormatter(precision?: number): FormatterFunction;
+/**
+ * Create an integer parser
+ *
+ * @param fallback - Value to return on parse failure (default: 0)
+ * @returns Parser function
+ */
+declare function createIntParser(fallback?: number): ParserFunction;
+/**
+ * Create a trim parser that removes whitespace
+ *
+ * @returns Parser function
+ */
+declare function createTrimParser(): ParserFunction;
+/**
+ * Create default parsers config
+ *
+ * @returns Standard parsers config
+ */
+declare function createDefaultParsers(): ParsersConfig;
+/**
+ * Create default formatters config
+ *
+ * @returns Standard formatters config
+ */
+declare function createDefaultFormatters(): FormattersConfig;
+
+/**
+ * Deep merge two objects, with the second object taking precedence
+ *
+ * @param base - Base object
+ * @param override - Override object (takes precedence)
+ * @returns Merged object
+ */
+declare function deepMerge<T extends object>(base: T, override: Partial<T> | undefined): T;
+/**
+ * Merge input configurations from multiple sources
+ *
+ * Priority order (highest to lowest):
+ * 1. Form-level inputs
+ * 2. Provider-level inputs
+ *
+ * @param providerInputs - Provider input configs
+ * @param formInputs - Form input configs (or function to transform)
+ * @returns Merged input configs
+ */
+declare function mergeInputConfigs(providerInputs: Record<string, InputConfig>, formInputs?: FormConfig['inputs']): Record<string, InputConfig>;
+/**
+ * Resolve input config for a specific type
+ *
+ * @param type - Input type key
+ * @param inputs - Merged input configs
+ * @param defaultType - Default type if specified type not found
+ * @returns Input config or undefined
+ */
+declare function resolveInputConfig(type: string, inputs: Record<string, InputConfig>, defaultType?: string): InputConfig | undefined;
+/**
+ * Resolve field type from multiple sources
+ *
+ * Priority order (highest to lowest):
+ * 1. Component prop type
+ * 2. Field config type
+ * 3. Default type ('textField')
+ *
+ * @param componentType - Type from component props
+ * @param fieldConfig - Field configuration
+ * @param defaultType - Default type
+ * @returns Resolved type
+ */
+declare function resolveFieldType(componentType?: string, fieldConfig?: FieldConfig, defaultType?: string): string;
+/**
+ * Merge static props from multiple configuration layers
+ *
+ * Priority order (highest to lowest):
+ * 1. Component props (from JSX)
+ * 2. Field config selectProps (evaluated separately)
+ * 3. Field config props
+ * 4. Input config props
+ * 5. Form-level selectDefaultFieldProps (evaluated separately)
+ * 6. Form-level defaultFieldProps
+ * 7. Provider-level selectDefaultFieldProps (evaluated separately)
+ * 8. Provider-level defaultFieldProps
+ *
+ * NOTE: This function only merges STATIC props. Dynamic props (selectProps,
+ * selectDefaultFieldProps) must be evaluated and merged separately.
+ *
+ * @param layers - Configuration layers from lowest to highest priority
+ * @returns Merged static props
+ */
+declare function mergeStaticProps(...layers: Array<Record<string, unknown> | undefined>): Record<string, unknown>;
+/**
+ * Merge all field props following the priority order
+ *
+ * This is the main props merging function that combines:
+ * - Static props from config layers
+ * - Evaluated dynamic props
+ * - Core field props
+ *
+ * @param options - All props sources
+ * @returns Final merged props
+ */
+declare function mergeFieldProps(options: {
+    providerDefaultFieldProps?: Record<string, unknown>;
+    providerSelectDefaultFieldProps?: Record<string, unknown>;
+    formDefaultFieldProps?: Record<string, unknown>;
+    formSelectDefaultFieldProps?: Record<string, unknown>;
+    inputProps?: Record<string, unknown>;
+    fieldConfigProps?: Record<string, unknown>;
+    selectProps?: Record<string, unknown>;
+    componentProps?: Record<string, unknown>;
+    coreProps?: Record<string, unknown>;
+}): Record<string, unknown>;
+/**
+ * Create a merged configuration context
+ *
+ * Combines provider and form configs into a single context object
+ * for use during field rendering.
+ *
+ * @param providerConfig - Provider configuration
+ * @param formConfig - Form configuration
+ * @returns Merged configuration context
+ */
+declare function createConfigContext(providerConfig: FormalityProviderConfig, formConfig?: FormConfig): {
+    inputs: Record<string, InputConfig>;
+    formatters: Record<string, (value: unknown) => unknown>;
+    parsers: Record<string, (value: unknown) => unknown>;
+    validators: Record<string, unknown>;
+    errorMessages: Record<string, string>;
+    defaultFieldProps: Record<string, unknown>;
+    selectDefaultFieldProps: unknown;
+};
+
+/**
+ * Resolve the initial value for a field
+ *
+ * Priority order (highest to lowest):
+ * 1. defaultValues[fieldName] (from Form props)
+ * 2. record[recordKey] (using recordKey if specified, else fieldName)
+ * 3. inputConfig.defaultValue (from input type definition)
+ *
+ * @param fieldName - Field name
+ * @param fieldConfig - Field configuration
+ * @param inputConfig - Input type configuration
+ * @param record - Record data passed to form
+ * @param defaultValues - Default values passed to form
+ * @returns Resolved initial value
+ *
+ * @example
+ * // Field with recordKey mapping
+ * resolveInitialValue(
+ *   'client',
+ *   { recordKey: 'selectedClient' },
+ *   { defaultValue: null },
+ *   { selectedClient: { id: 5 } },
+ *   {}
+ * )
+ * // → { id: 5 }
+ *
+ * // Field with explicit defaultValue
+ * resolveInitialValue(
+ *   'status',
+ *   {},
+ *   { defaultValue: 'pending' },
+ *   {},
+ *   { status: 'active' }
+ * )
+ * // → 'active' (defaultValues takes precedence)
+ */
+declare function resolveInitialValue(fieldName: string, fieldConfig?: FieldConfig, inputConfig?: InputConfig, record?: Record<string, unknown>, defaultValues?: Record<string, unknown>): unknown;
+/**
+ * Resolve initial values for all fields in a configuration
+ *
+ * @param fieldConfigs - Map of field names to configurations
+ * @param inputs - Map of input types to configurations
+ * @param record - Record data passed to form
+ * @param defaultValues - Default values passed to form
+ * @returns Map of field names to initial values
+ */
+declare function resolveAllInitialValues(fieldConfigs: Record<string, FieldConfig>, inputs: Record<string, InputConfig>, record?: Record<string, unknown>, defaultValues?: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Check if a value is considered "empty" for default value purposes
+ *
+ * @param value - Value to check
+ * @returns true if value is empty
+ */
+declare function isEmptyValue(value: unknown): boolean;
+/**
+ * Get the default value for an input type
+ *
+ * Falls back to common defaults based on type name if not specified.
+ *
+ * @param inputConfig - Input configuration
+ * @param typeName - Input type name (for fallback logic)
+ * @returns Default value
+ */
+declare function getInputDefaultValue(inputConfig?: InputConfig, typeName?: string): unknown;
+/**
+ * Merge record data with form default values
+ *
+ * Record values take precedence over defaults for non-empty values.
+ *
+ * @param record - Record data (may have partial data)
+ * @param defaults - Default values
+ * @returns Merged values
+ */
+declare function mergeRecordWithDefaults(record?: Record<string, unknown>, defaults?: Record<string, unknown>): Record<string, unknown>;
+
+/**
+ * Convert a camelCase or PascalCase field name to a human-readable label
+ *
+ * @param fieldName - The field name to humanize
+ * @returns Human-readable label
+ *
+ * @example
+ * humanizeLabel("clientContact") // → "Client Contact"
+ * humanizeLabel("minGrossMarginPercent") // → "Min Gross Margin Percent"
+ * humanizeLabel("CCIP/CCOP") // → "CCIP/CCOP" (preserved)
+ * humanizeLabel("firstName") // → "First Name"
+ * humanizeLabel("HTMLParser") // → "Html Parser"
+ * humanizeLabel("userID") // → "User Id"
+ */
+declare function humanizeLabel(fieldName: string): string;
+/**
+ * Resolve the label for a field
+ *
+ * Priority order (highest to lowest):
+ * 1. Component prop (label from JSX props)
+ * 2. Field config props.label
+ * 3. Evaluated selectProps.label
+ * 4. Field config label
+ * 5. Field config title (legacy alias)
+ * 6. Auto-generated from field name
+ *
+ * @param fieldName - Field name
+ * @param fieldConfig - Field configuration
+ * @param evaluatedSelectProps - Pre-evaluated selectProps
+ * @param componentProps - Props from JSX
+ * @returns Resolved label string
+ */
+declare function resolveLabel(fieldName: string, fieldConfig?: FieldConfig, evaluatedSelectProps?: Record<string, unknown>, componentProps?: Record<string, unknown>): string;
+/**
+ * Resolve the title for a form
+ *
+ * @param formTitle - Static form title
+ * @param evaluatedSelectTitle - Pre-evaluated selectTitle
+ * @returns Resolved title string or undefined
+ */
+declare function resolveFormTitle(formTitle?: string, evaluatedSelectTitle?: unknown): string | undefined;
+/**
+ * Check if a label is auto-generated (matches the humanized field name)
+ *
+ * @param fieldName - Field name
+ * @param label - Current label
+ * @returns true if label appears to be auto-generated
+ */
+declare function isAutoGeneratedLabel(fieldName: string, label: string): boolean;
+/**
+ * Create a label with a unit suffix
+ *
+ * @param baseLabel - Base label text
+ * @param unit - Unit to append (e.g., '%', '$', 'kg')
+ * @returns Label with unit in parentheses
+ *
+ * @example
+ * createLabelWithUnit("Min Gross Margin", "%") // → "Min Gross Margin (%)"
+ * createLabelWithUnit("Weight", "kg") // → "Weight (kg)"
+ */
+declare function createLabelWithUnit(baseLabel: string, unit: string): string;
+/**
+ * Extract the base label and unit from a label with unit suffix
+ *
+ * @param label - Label potentially containing unit
+ * @returns Object with base label and optional unit
+ *
+ * @example
+ * parseLabelWithUnit("Min Gross Margin (%)") // → { base: "Min Gross Margin", unit: "%" }
+ * parseLabelWithUnit("Client Contact") // → { base: "Client Contact", unit: undefined }
+ */
+declare function parseLabelWithUnit(label: string): {
+    base: string;
+    unit?: string;
+};
+/**
+ * Sort fields by their order property
+ *
+ * @param fieldNames - Array of field names
+ * @param fieldConfigs - Map of field configs
+ * @returns Sorted array of field names
+ */
+declare function sortFieldsByOrder(fieldNames: string[], fieldConfigs: Record<string, FieldConfig>): string[];
+/**
+ * Get fields that are not in the declared set
+ *
+ * @param allFields - All field names from config
+ * @param declaredFields - Set of explicitly declared field names
+ * @returns Array of unused field names
+ */
+declare function getUnusedFields(allFields: string[], declaredFields: Set<string>): string[];
+/**
+ * Get ordered unused fields
+ *
+ * @param allFields - All field names from config
+ * @param declaredFields - Set of explicitly declared field names
+ * @param fieldConfigs - Map of field configs
+ * @returns Sorted array of unused field names
+ */
+declare function getOrderedUnusedFields(allFields: string[], declaredFields: Set<string>, fieldConfigs: Record<string, FieldConfig>): string[];
+
+export { type ConditionDescriptor, type ConditionResult, type ErrorMessagesConfig, type EvaluateConditionsInput, type EvaluationContext, FIELD_PROXY_MARKER, FIELD_PROXY_VALUE, type FieldConfig, type FieldError, type FieldState, type FieldStateInput, type FormConfig, type FormFieldsConfig, type FormState, type FormalityProviderConfig, type FormatterFunction, type FormatterSpec, type FormattersConfig, type GroupConfig, type InputConfig, type InputTemplateProps, KEYWORDS, type ParserFunction, type ParserSpec, type ParsersConfig, QUALIFIED_PREFIXES, type SelectFunction, type SelectValue, type ValidationResult, type ValidatorFactory, type ValidatorFunction, type ValidatorSpec, type ValidatorsConfig, buildEvaluationContext, buildFieldContext, buildFormContext, clearExpressionCache, composeValidators, conditionMatches, createConfigContext, createDefaultFormatters, createDefaultParsers, createErrorMessages, createFieldStateProxy, createFloatFormatter, createFloatParser, createIntParser, createLabelWithUnit, createTrimParser, createValidationError, deepMerge, evaluate, evaluateConditions, evaluateDescriptor, extractValueField, format, formatTypeAsMessage, getErrorType, getInputDefaultValue, getOrderedUnusedFields, getUnusedFields, humanizeLabel, inferFieldsFromConditions, inferFieldsFromDescriptor, inferFieldsFromExpression, isAutoGeneratedLabel, isEmptyValue, isFieldProxy, isValid, maxLength, mergeConditionResults, mergeFieldProps, mergeInputConfigs, mergeRecordWithDefaults, mergeStaticProps, minLength, parse, parseLabelWithUnit, pattern, required, resolveAllInitialValues, resolveErrorMessage, resolveFieldType, resolveFormTitle, resolveInitialValue, resolveInputConfig, resolveLabel, runValidator, runValidatorSync, sortFieldsByOrder, transformFieldName, unwrapFieldProxy };