react-formal/cjs/useField.d.ts

Classy HTML form management for React

/// <reference types="react" />
import { AnySchema } from 'yup';
import { Errors } from './types';
import { ValidationPathSpec } from './errorManager';
export declare function splitFieldProps<TProps extends UseFieldOptions = UseFieldOptions>({ name, type, mapFromValue, mapToValue, validates, validateOn, exclusive, noValidate, errorClass, className, onChange, onBlur, value, as, ...rest }: TProps): [UseFieldOptions, Omit<TProps, keyof UseFieldOptions>];
export declare const ValidateStrategies: {
    Change: TriggerEventConfig;
    Blur: TriggerEventConfig;
    ChangeAndBlur: TriggerEventConfig;
    BlurThenChangeAndBlur: (meta: FieldMeta) => TriggerEventConfig | TriggerEvent | null;
};
export interface UseFieldMetaOptions {
    name: string;
    as?: React.ElementType;
    type?: string;
    exclusive?: boolean;
    noValidate?: boolean;
    errorClass?: string;
    mapToValue?: MapToValue;
    mapFromValue?: MapFromValue;
    validates: Array<string | ValidationPathSpec>;
}
export interface FieldMeta {
    invalid: boolean;
    valid: boolean;
    errors: Errors;
    touched: boolean;
    schema?: AnySchema;
    errorClass?: string;
    context: any;
    /**
     * The abstract field type, either as provided by the field e.g. checkbox,
     * or derived from the field's schema, e.g. number
     */
    resolvedType: string;
    /** A valid HTML input type, only set if `nativeTagName` is 'input' */
    nativeType: string | undefined;
    /** The infered native HTML element. */
    nativeTagName: 'input' | 'select' | 'textarea';
    onError: (errors: Errors) => void;
    value: any;
    /** Updates the field value in formData, does not trigger any Validation */
    update: (nextFieldValue: unknown, ...args: any[]) => void;
    /**
     * Handle a change event for a field, updates the field value and triggers
     * validation if applicable.
     */
    onChange: (nextFieldValue: unknown, ...args: any[]) => void;
    validateOn: TriggerEventConfig;
}
export declare function useFieldMeta(opts: UseFieldMetaOptions): FieldMeta;
export type ValueMapper = (value: unknown, ...args: any[]) => any;
export type MapFromValue = string | ValueMapper | Record<string, string | ValueMapper>;
export type MapToValue = (formValue: Record<string, any>) => any;
export type TriggerEvent = 'change' | 'blur';
export type TriggerEventConfig = {
    blur?: boolean;
    change?: boolean;
};
export type ValidateOnConfig = null | TriggerEvent | TriggerEventConfig | ((meta: FieldMeta) => TriggerEventConfig | TriggerEvent | null);
export interface UseFieldOptions extends Omit<UseFieldMetaOptions, 'validates'> {
    name: string;
    value?: any;
    mapToValue?: MapToValue;
    mapFromValue?: MapFromValue;
    className?: string;
    validates?: string | string[] | null;
    validateOn?: ValidateOnConfig;
    onChange?: (...args: any[]) => any;
    onBlur?: (...args: any[]) => any;
}
export type EventHandlers = Record<string, (...args: any[]) => any>;
export type UseFieldProps<TValue = any> = {
    value: TValue;
    type?: string;
    name: string;
    multiple?: boolean;
    className?: string;
    onChange: (nextFieldValue: unknown, ...args: any[]) => any;
    onBlur: (...args: any[]) => any;
    checked?: boolean;
};
/**
 * Create a new form field for the provided name, takes the same options
 * as `Field` props.
 *
 *
 * ```jsx
 * function MyNameField(props) {
 *   const [fieldProps, meta] = useField('firstName')
 *
 *   return (
 *      <input
 *        {...fieldProps}
 *        className={meta.invalid ? 'field-error' : ''}
 *      />
 *   )
 * }
 * ```
 *
 * @param {string} name The Field name, which should be path corresponding to a specific form `value` path.
 */
declare function useField(name: string): [UseFieldProps, FieldMeta];
/**
 * Create a new form field for the provided name, takes the same options
 * as `Field` props.
 *
 * ```jsx
 * function MyNameField(props) {
 *   const [fieldProps, meta] = useField({ name: 'firstName' })
 *
 *   return (
 *      <input
 *        {...fieldProps}
 *        className={meta.invalid ? 'field-error' : ''}
 *      />
 *   )
 * }
 * ```
 *
 * @param options
 * @param {string} options.name The Field name, which should be path corresponding to a specific form `value` path.
 * @param {any=}   options.value For checkbox/boolean fields override the HTML default value for checks from `'on'`
 * @param {MapToValue=} options.mapToValue A mapper from the form value to fieldProps.value`
 * @param {(string|MapFromValue)=} options.mapFromValue A mapper from the form value to fieldProps.value`
 * @param {(string|string[]|null)=} options.validates Triggers validation for additional field paths
 * @param {('change' | 'blur' | { blur?: boolean; change?: boolean } | (meta: FieldMeta) => { blur?: boolean; change?: boolean })=} options.validateOn configure which events trigger validation.
 */
declare function useField(options: UseFieldOptions): [UseFieldProps, FieldMeta];
export default useField;