effector-forms/dist-types/index.d.ts

Effector form state factory

// Generated by dts-bundle-generator v6.7.0

import { Domain, Event, Store } from 'effector';

export declare type InitFieldValue<Value> = () => Value;
/**
 * Trigger that will be used to validate the form or field
 */
export declare type ValidationEvent = "submit" | "blur" | "change";
/**
 * See {@link Rule}
 */
export declare type ValidationResult = {
	isValid: boolean;
	errorText?: string;
};
/**
 * A function that takes a field value, a form value
 * and an external store.
 * Returns boolean or {@link ValidationResult | ValidationResult}
 */
export declare type Validator<Value, Form = any, Source = any> = (value: Value, form?: Form, source?: Source) => boolean | ValidationResult;
export declare type ValidationError<Value = any> = {
	rule: string;
	value: Value;
	errorText?: string;
};
/**
 * Validation rule that is passed to the
 * {@link FieldConfig | field} configuration
 */
export declare type Rule<Value, Form = any, Source = any> = {
	/**
	 * The name of the validation rule. Used to
	 * determine which rule exactly threw an error.
	 * For example required, email, etc.
	 */
	name: string;
	/**
	 * Optional field with the error text.
	 * This text will also be passed to the
	 * error {@link ValidationError object}
	 */
	errorText?: string;
	/**
	 * Optional field to which you can pass an external store
	 * if it is needed to validate the field. This store is passed to
	 * validator in the third argument
	 */
	source?: Store<Source>;
	/**
	 * A function that takes a field value, a form value
	 * and an external store.
	 * Returns boolean or {@link ValidationResult | ValidationResult}
	 */
	validator: Validator<Value, Form, Source>;
};
export declare type FieldData<Value> = {
	value: Value;
	errors: ValidationError<Value>[];
	firstError: ValidationError<Value> | null;
	isValid: boolean;
	isDirty: boolean;
	isTouched: boolean;
};
export declare type FieldUnitShape<Value> = {
	value: Store<Value>;
	initValue: Store<Value>;
	isValid: Store<boolean>;
	isDirty: Store<boolean>;
	touched: Store<boolean>;
	errors: Store<ValidationError<Value>[]>;
	firstError: Store<ValidationError<Value> | null>;
	errorText: Store<string>;
	onChange: Event<Value>;
	onBlur: Event<void>;
	addError: Event<{
		rule: string;
		errorText?: string;
	}>;
	validate: Event<void>;
	reset: Event<void>;
	resetErrors: Event<void>;
	resetValue: Event<void>;
};
export declare type Field<Value> = {
	name: string;
	$initValue: Store<Value>;
	$value: Store<Value>;
	$errors: Store<ValidationError<Value>[]>;
	$firstError: Store<ValidationError<Value> | null>;
	$errorText: Store<string>;
	$isValid: Store<boolean>;
	$isDirty: Store<boolean>;
	$isTouched: Store<boolean>;
	$touched: Store<boolean>;
	$field: Store<FieldData<Value>>;
	onChange: Event<Value>;
	changed: Event<Value>;
	onBlur: Event<void>;
	addError: Event<{
		rule: string;
		errorText?: string;
	}>;
	validate: Event<void>;
	reset: Event<void>;
	set: Event<Value>;
	resetErrors: Event<void>;
	resetValue: Event<void>;
	filter?: Store<boolean> | FilterFunc<Value>;
	"@@unitShape": () => FieldUnitShape<Value>;
};
export declare type FilterFunc<Value> = (value: Value) => boolean;
export declare type RuleResolver<Value = any, Form = any> = (value: Value, form: Form) => Rule<Value, Form, void>[];
/**
 * External units KV. By default,
 * each field unit is created when the {@link createForm | factory} is
 * called. If you pass a unit here, it will be used
 * instead of creating a new unit
 */
export declare type ExternalFieldUnits<Value> = {
	$value?: Store<Value>;
	$errors?: Store<ValidationError<Value>[]>;
	$isTouched?: Store<boolean>;
	$initValue?: Store<Value>;
	onChange?: Event<Value>;
	changed?: Event<Value>;
	onBlur?: Event<void>;
	addError?: Event<{
		rule: string;
		errorText?: string;
	}>;
	validate?: Event<void>;
	resetValue?: Event<void>;
	reset?: Event<void>;
	resetErrors?: Event<void>;
};
/**
 * field configuration object
 *
 */
export declare type FieldConfig<Value> = {
	/**
	 * initial value. The type of this value is used to
	 * infer the type of the field. You can pass a function
	 * that returns an initial value. This function will be called
	 * once when the form is created
	 */
	init: Value | InitFieldValue<Value>;
	/**
	 * An array of validation rules.
	 * You can also pass a function instead of
	 * an array and define validation rules dynamically.
	 * This function will be called at the moment of validation
	 * and will take a field value and form value
	 */
	rules?: Rule<Value>[] | RuleResolver<Value, any>;
	/**
	 * A store or function that filters a field change
	 * when the onChange event is called.
	 * The value of the field changes only
	 * if the function returns true
	 */
	filter?: Store<boolean> | FilterFunc<Value>;
	/**
	 * Array of field-specific validation triggers
	 */
	validateOn?: ValidationEvent[];
	/**
	 * External units KV.
	 */
	units?: ExternalFieldUnits<Value>;
};
export declare type AnyFields = {
	[key: string]: Field<any>;
};
/**
 * KV containing form values
 */
export declare type AnyFormValues = {
	[key: string]: any;
};
export declare type FormValues<Fields extends AnyFields> = {
	[K in keyof Fields]: Fields[K] extends Field<infer U> ? U : never;
};
export declare type FormFieldConfigs<Values extends AnyFormValues> = {
	[K in keyof Values]: FieldConfig<Values[K]>;
};
export declare type FormFields<Values extends AnyFormValues> = {
	[K in keyof Values]: Field<Values[K]>;
};
export declare type AddErrorPayload = {
	field: string;
	rule: string;
	errorText?: string;
};
/**
 * External units KV. By default,
 * each form unit is created when the {@link createForm | factory} is
 * called. If you pass a unit here, it will be used
 * instead of creating a new unit
 */
export declare type ExternalFormUnits<Values extends AnyFormValues> = {
	submit?: Event<void>;
	validate?: Event<void>;
	addErrors?: Event<AddErrorPayload[]>;
	reset?: Event<void>;
	resetValues?: Event<void>;
	resetTouched?: Event<void>;
	resetErrors?: Event<void>;
	formValidated?: Event<Values>;
	setInitialForm?: Event<Partial<AnyFormValues>>;
	setForm?: Event<Partial<AnyFormValues>>;
};
/**
 * The object that is passed to the {@link createForm | createForm} factory
 *
 * @example
 *
 * ```ts
 * const $passwordMinLength = createStore(3)
 *
 * form = createForm({
 *    fields: {
 *      username: {
 *         init: "",
 *         rules: [
 *            {
 *              name: "required",
 *              validator: (value) => Boolean(value),
 *            }
 *         ],
 *      },
 *      password: {
 *         init: "",
 *         validateOn: ["change"],
 *         rules: [
 *            {
 *               name: "required",
 *               validator: (value) => Boolean(value),
 *            },
 *            {
 *               name: "minLength",
 *               source: $passwordMinLength,
 *               validator: (password, form, minLength) => ({
 *                  isValid: password.length > minLength,
 *                  errorText: `The password field must be longer than ${minLength} characters`
 *               })
 *            }
 *         ]
 *      },
 *      confirm: {
 *         init: "",
 *         validateOn: ["change"],
 *         rules: [
 *            {
 *              name: "required",
 *              validator: (value) => Boolean(value),
 *            },
 *            {
 *              name: "matchPassword",
 *              validator: (confirm, { password }) => ({
 *                 isValid: confirm === password,
 *                 errorText: "Doesn't match the password"
 *              }),
 *            }
 *         ]
 *      }
 *    },
 *    validateOn: ["submit"]
 * })
 * ```
 */
export declare type FormConfig<Values extends AnyFormValues> = {
	/**
	 * The keys of the object are the names of the fields,
	 * and the values are the {@link FieldConfig | FieldConfig}
	 */
	fields: FormFieldConfigs<Values>;
	/**
	 * If you pass a domain into this field,
	 * all units of the form will be in this domain
	 */
	domain?: Domain;
	/**
	 * If store is passed the `formValidated` event will be called
	 * then the value of store will be true
	 */
	filter?: Store<boolean>;
	/**
	 * Trigger that will be used to validate the form.
	 */
	validateOn?: ValidationEvent[];
	/**
	 * External units KV.
	 */
	units?: ExternalFormUnits<Values>;
};
export declare type FormUnitShape<Values extends AnyFormValues> = {
	isValid: Store<boolean>;
	isDirty: Store<boolean>;
	touched: Store<boolean>;
	submit: Event<void>;
	validate: Event<void>;
	reset: Event<void>;
	addErrors: Event<AddErrorPayload[]>;
	setForm: Event<Partial<Values>>;
	setInitialForm: Event<Partial<Values>>;
	resetTouched: Event<void>;
	resetValues: Event<void>;
	resetErrors: Event<void>;
	formValidated: Event<Values>;
};
export declare type Form<Values extends AnyFormValues> = {
	fields: FormFields<Values>;
	$values: Store<Values>;
	$eachValid: Store<boolean>;
	$isValid: Store<boolean>;
	$isDirty: Store<boolean>;
	$touched: Store<boolean>;
	$meta: Store<{
		isValid: boolean;
		isDirty: boolean;
		touched: boolean;
	}>;
	submit: Event<void>;
	validate: Event<void>;
	reset: Event<void>;
	addErrors: Event<AddErrorPayload[]>;
	set: Event<Partial<Values>>;
	setForm: Event<Partial<Values>>;
	setInitialForm: Event<Partial<Values>>;
	resetTouched: Event<void>;
	resetValues: Event<void>;
	resetErrors: Event<void>;
	formValidated: Event<Values>;
	"@@unitShape": () => FormUnitShape<Values>;
};
/**
 * This is the main factory in the library that creates
 * the forms shape according to the given configuration.
 *
 * Do not try to pass a type in the Values generic! Form types are inferred automatically from the passed "fields" object
 *
 * @param config - The form configuration object
 * @returns The shape of effector units
 * @example
 *
 * ```ts
 * const form = createForm({
 *      fields: {
 *          username: {
 *              init: "",
 *              rules: [
 *                  {
 *                      name: "required",
 *                      validator: (value: string) => Boolean(value)
 *                  }
 *              ]
 *          },
 *          bio: {
 *              init: "",
 *              rules: []
 *          }
 *      },
 *      validateOn: ["change"],
 * })
 * ```
 * @group Factories
 */
export declare function createForm<Values extends AnyFormValues>(config: FormConfig<Values>): Form<Values>;
export declare type ErrorTextMap = {
	[key: string]: string;
};
export declare type AddErrorPayload = {
	rule: string;
	errorText?: string;
};
export declare type ConnectedField<Value> = {
	name: string;
	value: Value;
	errors: ValidationError<Value>[];
	firstError: ValidationError<Value> | null;
	hasError: () => boolean;
	onChange: (v: Value) => Value;
	onBlur: (v: void) => void;
	errorText: (map?: ErrorTextMap) => string;
	addError: (p: AddErrorPayload) => AddErrorPayload;
	validate: (v: void) => void;
	isValid: boolean;
	isDirty: boolean;
	isTouched: boolean;
	touched: boolean;
	reset: (v: void) => void;
	set: (v: Value) => Value;
	resetErrors: (v: void) => void;
};
export declare type ConnectedFields<Values extends AnyFormValues> = {
	[K in keyof Values]: ConnectedField<Values[K]>;
};
/**
 * @group Hooks
 */
export declare function useField<Value>(field: Field<Value>): ConnectedField<Value>;
export declare type Result<Values extends AnyFormValues> = {
	fields: ConnectedFields<Values>;
	values: Values;
	hasError: (fieldName?: keyof Values) => boolean;
	eachValid: boolean;
	isValid: boolean;
	isDirty: boolean;
	isTouched: boolean;
	touched: boolean;
	errors: (fieldName: keyof Values) => (ValidationError<Values[typeof fieldName]>[]);
	error: (fieldName: keyof Values) => (ValidationError<Values[typeof fieldName]>) | null;
	errorText: (fieldName: keyof Values, map?: ErrorTextMap) => string;
	submit: (p: void) => void;
	reset: (p: void) => void;
	setForm: (p: Partial<Values>) => Partial<Values>;
	set: (p: Partial<Values>) => Partial<Values>;
	formValidated: (p: Values) => Values;
};
/**
 * @group Hooks
 */
export declare function useForm<Values extends AnyFormValues>(form: Form<Values>): Result<Values>;

export {};