@worktif/purei/dist/src/context/forms/forms.context.d.ts

Work TIF Material UI Theme Provider and Customization Suite for React applications with dark mode support and dynamic color schemes

import * as React from 'react';
import { Context } from 'react';
import { Maybe, Nullable } from '../../types';
import { FormError } from './form.error';
export type FormBuilderSchema = {
    form: FormBuilderField[];
};
export declare enum FormFieldType {
    Text = "text",
    Checkbox = "checkbox"
}
/**
 * @todo: define the range of values
 */
export type FormFieldValue = any;
export declare enum FormFieldValidationType {
    MaxLength = "max-length",
    MinLength = "min-length",
    Alphabetically = "alphabetically",
    ShouldExist = "should-exist",
    Email = "email",
    Password = "password",
    Numerical = "numerical"
}
export type FormFieldValidation = {
    [FormFieldValidationType.MaxLength]?: number;
    [FormFieldValidationType.MinLength]?: number;
    [FormFieldValidationType.Alphabetically]?: boolean;
    [FormFieldValidationType.Numerical]?: boolean;
    [FormFieldValidationType.ShouldExist]?: boolean;
    [FormFieldValidationType.Email]?: boolean;
    [FormFieldValidationType.Password]?: number;
};
type FormBuilderMessages = {
    validation?: Maybe<{
        [FormFieldValidationType.MaxLength]?: string;
        [FormFieldValidationType.MinLength]?: string;
        [FormFieldValidationType.Alphabetically]?: string;
        [FormFieldValidationType.Numerical]?: string;
        [FormFieldValidationType.ShouldExist]?: string;
        [FormFieldValidationType.Email]?: string;
        [FormFieldValidationType.Password]?: string;
    }>;
};
export type FormBuilderField = {
    type: FormFieldType;
    value: Maybe<FormFieldValue>;
    name: string;
    validation: Maybe<FormFieldValidation>;
    messages?: Maybe<FormBuilderMessages>;
};
export type FormValidationOperationOptions = {
    type: FormFieldValidationType;
    constraint: Maybe<boolean | string | number>;
    value: any;
    message: Maybe<string>;
};
export type FormFieldItem = {
    type: FormFieldValidationType;
    constraint: FormFieldValidation;
    value: FormError | unknown;
};
export type FormArrayIndex = number;
export type FormContextValueItem = {
    [fieldName: string]: Nullable<any> | FormFieldItem;
};
export type FormContextValue = {
    value: Maybe<FormContextValueItem[]>;
    setValue: (value: any, index?: FormArrayIndex) => void;
    getFieldValue: (fieldName: string, index?: FormArrayIndex) => any;
    setFieldValue: (fieldName: string, value: any, index?: FormArrayIndex) => void;
    isError: (fieldName: string, index?: FormArrayIndex) => boolean;
    getError: (fieldName: string, index?: FormArrayIndex) => Maybe<string>;
    setFormValue: (value: Maybe<FormContextValueItem | FormContextValueItem[]>, isProcess?: Maybe<boolean>, index?: FormArrayIndex) => void;
    getValue: (fields?: string[], index?: FormArrayIndex) => Maybe<FormContextValueItem>;
    hasError: (index?: FormArrayIndex) => boolean;
    setSchema: (schema: FormBuilderSchema[]) => void;
    composeSchema: (schema: FormBuilderSchema[], body?: any) => void;
    isSubmit: (index?: FormArrayIndex) => boolean;
    setSubmit: (submit: boolean, index?: FormArrayIndex) => void;
    isFormProcess: (index?: FormArrayIndex) => boolean;
    setFormProcess: (isProcess: boolean, index?: FormArrayIndex) => void;
    setChange: (isChange: boolean, index?: FormArrayIndex) => void;
    change: (index?: FormArrayIndex) => boolean;
    i18nSchema: Maybe<{
        [i18nKey: string]: string;
    }>;
};
export declare const FormsContext: Context<FormContextValue>;
/**
 * Represents the properties used in a component or function, including child components and internationalization support.
 *
 * @typedef {Object} Props
 * @property {*} children - The child elements or components to render.
 * @property {Maybe<{ [i18nKey: string]: string }>} i18nSchema - Optional internationalization schema object that maps keys to localized strings. Note: This property is intended for future integration with the internal @worktif/purei18n package for internationalization purposes.
 * @todo Compose an internal @worktif/purei18n package for internationalization support.
 */
type Props = {
    children: any;
    i18nSchema: Maybe<{
        [i18nKey: string]: string;
    }>;
};
/**
 * FormProvider is a React functional component that manages and provides form state
 * and functionality to its children. This includes form values, schemas, submission
 * state, change tracking, validation, and error management.
 *
 * Props:
 * - `children` (ReactNode): Components that will be rendered within the context of the FormProvider.
 * - `i18nSchema` (any): Optional schema for internationalization-related configurations.
 *
 * Features and State Management:
 * - Manages the form values and enables updates to individual field values or the entire form.
 * - Tracks the state of form submission and whether the form is currently being processed.
 * - Maintains a schema to compose and validate form input definitions.
 * - Tracks form change states to determine if any fields have been modified.
 * - Provides form-level and field-level error management, including error retrieval and validation.
 *
 * Key Methods:
 * - `setChange`: Updates the change state of a specific form array item.
 * - `change`: Checks if any indexed form array item has changed.
 * - `isSubmit`: Determines if the form or a specific form array item has been submitted.
 * - `setSubmit`: Sets the submission state for the form or a specific array item.
 * - `isFormProcess`: Checks if a specific form array item is being processed.
 * - `setFormProcess`: Marks an array item as processed or not.
 * - `setSubmitElements`: Sets the submit state for every element in the form schema.
 * - `isElementSubmit`: Checks if a specific form array element is in a submitted state.
 * - `setElementSubmit`: Marks a specific form array item as submitted or not.
 * - `composeSchema`: Initializes form schema and composes initial form value states.
 * - `setFormValue`: Updates the form values, applies on-the-fly validation, and handles the processing state.
 * - `getValue`: Retrieves specific field values or all values of an array item.
 * - `setFieldValue`: Updates the value of a specific field within a form array item.
 * - `hasError`: Checks if the form or a specific array item has any validation errors.
 * - `getError`: Retrieves the error message for a specific field in a form array item.
 *
 * Provides a context for managing and sharing form state and related operations
 * between components within its hierarchy. Ideal for complex forms with potentially
 * dynamic fields and logic.
 *
 *  * @todo: different forms on the single page required the categorisation of the form ssr.handler, so that the context should define an object of any state value where the property name is a form category
 */
export declare const FormProvider: React.FC<Props>;
export {};