@bolttech/form-engine/src/adapters/react/types.d.ts

A form engine based on form events for react projects

import React, { ReactElement } from 'react';
import { TComponent, TErrorMessages, TSchemaValidation, TSchemaValidations, TSchema, THooks, TIVars, TFormValues, TField, TChildrenOptions, TPropsMapping, TComponentPropsMapping, TScope } from '../../core/types';
import { TLoggingEvent } from '@core/events/events.types';
declare type TFormProps = {
    /**
     * Allow to set the form as read only mode.
     *
     * This will prevent any interaction with the form whatsoever
     */
    disable?: boolean;
    /**
     * Allow to specify a logical group across several forms so that we can get data with useFormGroup
     */
    group?: string;
    /**
     * Hooks to run on some life-cycles
     */
    hooks?: THooks;
    /**
     * Form id. Will default to a internal one in case not given
     */
    id?: string;
    /**
     * Internal variables. This object will be used in the global scope
     * namespace
     */
    iVars?: TIVars;
    /**
     * Form initial values. This must map into form known fields
     */
    initialValues?: Record<string, unknown>;
    /**
     * Form schema that should contain form definition
     */
    schema?: TSchema;
    /**
     * HTML autocomplete form prop
     */
    autoComplete?: string;
    /**
     * ClassName in case you want to style form
     */
    className?: string;
    /**
     *
     * Callback function that will run on each submit.
     *
     * NOTE: By default this function only runs if the form has no errors. If you
     * want different behaviour, use submitOnValidOnly and set to false
     *
     * @param form - HTML original event
     * @param values - Form generated value. Refer to its type
     */
    onSubmit?(form: React.FormEvent<HTMLFormElement>, values: TFormValues): Promise<Record<string, unknown> | void> | Record<string, unknown> | void;
    /**
     *
     * Callback function that runs on each data change.
     *
     * You can who changed the data accessing to the arguments
     *
     * @param values - Form generated values
     * @param component - The component configuration of the field that changed
     * @param field - The current state of the changing field
     */
    onData?(values: TFormValues, component?: TComponent, field?: TField): void;
    /**
     *
     * Callback function that runs on each blur.
     *
     * You can what field was blurred accessing to the arguments
     *
     * @param values - Form generated values
     * @param component - The component configuration of the field that was blurred
     * @param field - The current state of the blurred field
     */
    onBlur?(values: TFormValues, component?: TComponent, field?: TField): void;
    /**
     *
     * Callback function that runs on each focus.
     *
     * You can what field was focused accessing to the arguments
     *
     * @param values - Form generated values
     * @param component - The component configuration of the field that was focused
     * @param field - The current state of the focused field
     */
    onFocus?(values: TFormValues, component?: TComponent, field?: TField): void;
    /**
     *
     * Callback that tells you when a given field was mounted
     *
     * @param values - Form generated values
     * @param component - The component configuration of the field that was mounted
     * @param field - The current state of the mounted field
     */
    onFieldMount?(values: TFormValues, component?: TComponent, field?: TField): void;
    /**
     *
     * This callback will be fired in each step change
     *
     * @param values - Form generated values
     */
    onStep?(values: TFormValues): void;
    /**
     * Enables you to see what is happening under the hood. Subscribing the callback will enable logging
     *
     * @param log - Logging event
     */
    onLog?(log: TLoggingEvent): void;
    /**
     *
     * Notifies you about each form scope change and about who changed it
     *
     * @param scope - Form current scope with the update
     * @param namespace - The namespace that was updated
     * @param key - The key responsible for the update
     */
    onScopeChange?(scope: TScope, namespace: string, key: string): void;
    /**
     *
     * When a given field is rehydrated, this callback will be called
     *
     * @param values - Form generated values
     * @param component - The component configuration of the field that was mounted
     * @param field - The current state of the mounted field
     */
    onFieldRehydrate?(values: TFormValues, component: TComponent, field: TField): void;
    /**
     * Allows you to pass a JSX so that the form shows it before rendering your schema
     *
     * @returns JSX
     */
    renderLoading?(): ReactElement;
    /**
     * Called when the form was mounted
     *
     * @param values - Form generated values
     */
    onFormMount?(values: TFormValues): void;
    children?: ReactElement | ReactElement[];
    /**
     * Object to be used if you want to control the default values of the form.
     *
     * InitialValues will take precedence over this
     */
    formattedDataDefaults?: Record<string, unknown>;
    /**
     * Override the default form behaviour witch is to prevent submit when there is an error
     */
    submitOnValidOnly?: boolean;
    /**
     * Allows to insert a wrapper for each field or replace the field rendering
     */
    renderFieldWrapper?(component: TComponent, children: ReactElement[]): ReactElement;
    /**
     *
     * Callback function that runs on each component click.
     *
     * You can what field was clicked accessing to the arguments
     *
     * @param values - Form generated values
     * @param field - The current state of the blurred field
     */
    onClick?(values: TFormValues, field?: TField): void;
    /**
     *
     * Callback function that runs on each component after api call.
     *
     * You can capture the data after an api call and also perform validations or formatting in the field after it.
     *
     * @param values - Form generated values
     * @param component - The component configuration of the field that was focused
     * @param field - The current state of the focused field
     */
    afterApiCall?(values: TFormValues, component?: TComponent, field?: TField): void;
};
declare type TMapper = Record<string, Record<string, unknown>>;
declare type TProvider = {
    children?: ReactElement | ReactElement[] | string;
    mapper: TMapper;
    propsMapping: TPropsMapping;
};
declare type TContext = {
    mapper: TMapper;
    propsMapping: TPropsMapping;
};
declare type TChildWrapperProps = {
    children: ReactElement | ReactElement[];
    component: TComponent;
    wrapper: new () => React.Component;
    propsMapping: TComponentPropsMapping;
    formId?: string;
    onMount(values: TField): void;
    onChange(values: TField): void;
    onRehydrate(values: TField): void;
    onFocus(values: TField): void;
    onClick(values: TField): void;
    afterApiCall(values: TField): void;
    onBlur(values: TField): void;
};
declare type TFormRefActions = {
    submit(): void;
    step(index: number | string): TFormValues;
    stepForward(index?: number | string): TFormValues;
    stepBack(index?: number | string): TFormValues;
    validateForm(opts?: TChildrenOptions): TFormValues;
    values(opts: Pick<TChildrenOptions, 'scopeBlurredChildren' | 'scopeChangedChildren' | 'childrenScope'>): TFormValues;
};
declare type TUseFormProps = {
    /**
     * The if of the form you want to connect to
     */
    id?: string;
    /**
     * And array of ids of forms you want to connect to
     */
    ids?: string[];
    /**
     * Callback to be called when form validity toggled
     * @param data All the available form data
     * @param field
     */
    onValid?(data: TFormValues | Record<string, TFormValues>, field: TField): void;
    /**
     * Callback to be called when the form generates some new data
     * @param data All the available form data
     */
    onData?(data: TFormValues | Record<string, TFormValues>): void;
    /**
     * Callback to be called when the form generates some new data
     * @param data All the available form data
     */
    onClick?(data: TFormValues | Record<string, TFormValues>): void;
    /**
     * Callback to be called when the form submits
     * @param data All the available form data
     */
    onSubmit?(data: TFormValues | Record<string, TFormValues>): void;
};
declare type TUseFormGroupProps = {
    /**
     * And array of ids of forms you want to connect to
     */
    ids?: string[];
    /**
     * The if of the form group you want to merge
     */
    group?: string;
    /**
     * Callback to be called when the form generates some new data
     * @param data All the available form data
     */
    onData?(data: Record<string, TFormValues>): void;
    /**
     * Callback to be called when the form generates some new data
     * @param data All the available form data
     */
    onClick?(data: TFormValues): void;
    /**
     * Callback to be called when the form submits
     * @param data All the available form data
     */
    onSubmit?(data: Record<string, TFormValues>): void;
};
declare type THookReturn = {
    /**
     * A function that lets you start the form submission
     */
    submitForm(): void;
    /**
     * You can call this function to get all the updated form data.
     *
     * @param opts Options to configure your form data. The aggregate prop is only available on useFormGroup.
     */
    formData(opts?: TChildrenOptions & TGroupOption): TFormValues | Record<string, TFormValues>;
};
declare type TGroupOption = {
    aggregate?: boolean;
};
interface TAsFormFieldProps {
    /**
     * The component to be used as form field.
     */
    Comp: (new () => React.Component) | any;
    /**
     * Link for the TComponentPropsMapping likely props mapper from default form.
     */
    propsMapping: TComponentPropsMapping;
}
declare type TDecorator = {
    /**
     * Form id that you need to create and integrate the field.
     */
    formId?: string;
    /**
     * It's a prop that you can use to hide the component and control this state outside the component.
     */
    visibility?: boolean;
    /**
     * Name of the component similar to name prop name on TComponent type.
     * This name will be used later to correlate the field with the value, and you will be able to read it.
     */
    name: string;
    /**
     * The value of the field that you can control outside the component.
     */
    value?: any;
    /**
     * The disabled of the field that you can control outside the component.
     */
    disabled?: boolean;
    /**
     * The optionList of the field that you can control outside the component.
     * This optionList will be used to manipulated a list of elements. For example, Dropdown optionList.
     */
    optionList?: any[];
    /**
     * The onSelected of the field you can control outside the component by calling a custom function.
     * onSelected makes the data available (TField) for manipulation.
     * It is called when you mount and rehydrate the component at the first moment.
     * Also, it is called every time the component changes (onChange).
     */
    onSelected?: (data: TField) => void;
};
declare type TDecoratorProps<OriginalComponentProps = Record<string, unknown>> = OriginalComponentProps & Pick<TComponent, 'validations' | 'masks' | 'clearFields' | 'api' | 'errorMessages' | 'filter' | 'formatters' | 'visibilityConditions'> & TDecorator;
export type { TComponent, TMapper, TChildrenOptions, TFormValues, TFormRefActions, TChildWrapperProps, TContext, TFormProps, TProvider, TErrorMessages, TSchemaValidation, TSchemaValidations, TUseFormProps, TUseFormGroupProps, THookReturn, TAsFormFieldProps, TDecoratorProps, TGroupOption, };