@bolttech/form-engine-core 1.1.0 → 1.1.1

package/index.d.ts

@@ -2,383 +2,77 @@ import * as rxjs from 'rxjs';
 import { Subject, BehaviorSubject, Subscription } from 'rxjs';
 import { TCurrencyLocalCode, TCurrencyCode } from '@gaignoux/currency';
 
-type AllowOnly<T, K extends keyof T> = Pick<T, K> & {
-    [P in keyof Omit<T, K>]?: never;
-};
-type OneOf<T, K = keyof T> = K extends keyof T ? AllowOnly<T, K> : never;
-type TValidationPayload = [
-    unknown,
-    TValidationMethods,
-    TFormValues<unknown>?
-];
-type TValidationHandler = Record<string, (...args: TValidationPayload) => boolean>;
+declare const TEMPLATE_AVALIABLE_SCOPES: readonly ["fields", "iVars", "form"];
+declare const ALLOWED_RESET_PROPS_MUTATIONS: (keyof Pick<IFormField, "api" | "apiSchema" | "props" | "validations" | "visibilityConditions" | "resetValues">)[];
 
-type TComponentPropsMappingSubset = keyof (Pick<TEventPropsEnum, 'onBlur' | 'onChange' | 'onFocus' | 'onKeyDown' | 'onKeyUp' | 'onClick'> & Pick<TEventDataPropsEnum, 'onSubmit'>);
+/** @virtual */
+
+type TAllowedResetPropsMutations = (typeof ALLOWED_RESET_PROPS_MUTATIONS)[number];
 /**
- * @type TComponentPropsMapping
- * Represents the mapping of component properties for various events and actions.
- * @property {string} [getValue] - component function name to get the value.
- * @property {string} [setValue] - component function name to set the value.
- * @property {string} [setErrorMessage] - component function name to set the error message.
- * @property {string} [setErrorState] - component function name to set the error state.
+ * @type TAllowedResetPropsMutationsEnum
+ * Represents the allowed properties to be changed on resetPropertyValues.
+ *
+ * @property {never} api - api property
+ * @property {never} apiSchema - apiSchema property
+ * @property {never} props - props property
+ * @property {never} validations - validations property
+ * @property {never} visibilityConditions - visibilityConditions property
+ * @property {never} resetValues - resetValues property
  *
- * @example
- * ```typescript
- * const componentProps: TComponentPropsMapping = {
- *   getValue: 'getValueFunction',
- *   setValue: 'setValueFunction',
- *   onBlur: 'handleBlur',
- *   onClick: 'handleClick',
- *   onFocus: 'handleFocus',
- *   onKeyUp: 'handleKeyUp',
- *   onKeyDown: 'handleKeyDown',
- *   setErrorMessage: 'setErrorMessageFunction',
- *   setErrorState: 'setErrorStateFunction'
- * };
- * ```
  * @interface
  */
-type TComponentPropsMapping = Partial<Record<TComponentPropsMappingSubset, string>> & {
-    getValue?: string;
-    setValue?: string;
-    setErrorMessage?: string;
-    setErrorState?: string;
-};
+type TAllowedResetPropsMutationsEnum = Record<TAllowedResetPropsMutations, never>;
 /**
- * @type TMapper
- * Represents the mapping of a component, including the component type,
- * name, events, and an optional function to handle value changes.
+ * @type TLengthValidation
+ * Represents the validation rules based on the length of the input.
  *
- * @property {ElementType} component - The component that will represent the input.
- * * @property {ElementType} asynccomponent - The component that will represent the input but dynamically imported (suspense/lazy).
- * @property {string} componentName - The name of the component.
- * @property {TComponentPropsMapping} [events] - Mapping event properties for the component.
- * @property {TValueChangeEvent} [valueChangeEvent] - Optional function to handle value changes.
+ * @property {'equal' | 'notEqual' | 'less' | 'lessOrEqual' | 'greater' | 'greaterOrEqual'} rule - The rule to apply.
+ * @property {number} target - The target value to compare against.
  *
  * @example
  * ```typescript
- * const mappers: TMapper<ElementType>[] = [
- *  {
- *    component: InputElement,
- *    componentName: 'input',
- *    events: {
- *      getValue: 'onChange2',
- *      onBlur: 'onBlur2',
- *      onFocus: 'onFocus2',
- *    }
- *  },
- *  {
- *    component: Container,
- *    componentName: 'row',
- *  },
- *  {
- *    component: Dropdown,
- *    componentName: 'dropdown',
- *    valueChangeEvent: (event: {
- *      id: string;
- *      label: string;
- *      value: string;
- *    }) => ({ _value: event.value, _stateValue: event.id }),
- *  },
- *  {
- *    component: DatePicker,
- *    componentName: 'datepicker',
- *    valueChangeEvent: (event: string) => event,
- *  },
- * ];
+ * const lengthValidation: TLengthValidation = { rule: 'greaterOrEqual', target: 8 };
  * ```
- * @interface
  */
-type TMapper<T> = {
-    componentName: string;
-    events?: TComponentPropsMapping;
-    valueChangeEvent?: TValueChangeEvent;
-} & OneOf<{
-    component: T;
-    asynccomponent: T;
-}>;
-
+type TLengthValidation = {
+    rule: 'equal' | 'notEqual' | 'less' | 'lessOrEqual' | 'greater' | 'greaterOrEqual';
+    target: number;
+};
 /**
- * @interface IComponentSchema
- * Represents the schema for a component within a form.
+ * @type TCallbackValidation
+ * A custom validation function.
  *
- * @property {string} component - The type of component (e.g., 'input', 'button').
- * @property {TProps} props - The properties of the component.
- * @property {string} name - The name of the component.
- * @property {string} nameToSubmit - The name of the field when submit values (optional).
- * @property {TValidations} [validations] - The validation methods for the component.
- * @property {TVisibility[]} [visibilityConditions] - The visibility conditions for the component.
- * @property {TResetValueMethods[]} [resetValues] - The reset value methods for the component.
- * @property {TApiEvent} [api] - The API configuration for the component.
- * @property {TFormatters} [formatters] - The formatters for the component.
- * @property {TMasks} [masks] - The masks for the component.
- * @property {IComponentSchema[]} [children] - The child components.
- * @property {boolean} visibility - visibility status the component will mount (to avoid SSR blinking)
- * @property {boolean} persistValue - check this if you want the last visible value to be restored after a visiblity schema rule applied
+ * @param {unknown} value - The value to validate.
+ * @returns {boolean} - The result of the validation.
  *
  * @example
  * ```typescript
- * const schema: IComponentSchema = {
- *   component: 'input',
- *   props: { type: 'text', placeholder: 'Enter your name' },
- *   name: 'name',
- *   nameToSubmit: 'applicant.firstName',
- *   validations: {
- *     methods: {
- *       required: true,
- *       regex: '^([0-9]+)*$',
- *       max: 5,
- *     },
- *     eventMessages: {
- *       ON_FIELD_MOUNT: ['required'],
- *       ON_FIELD_CHANGE: ['regex', 'required'],
- *       ON_FIELD_BLUR: ['max', 'required'],
- *     },
- *     messages: {
- *       default: 'This field is required',
- *       regex: 'Only numbers are available.',
- *       max: 'Max of 5',
- *     },
- *   },
- *   visibilityConditions: [{ conditions: { field: 'age', value: 18 } }],
- *   resetValues: [{ field: 'age', resetTo: '' }],
- *   api: {
- *     defaultConfig: {
- *       config: { method: 'POST', url: 'https://api.example.com/submit' },
- *       events: [{ eventName: 'ON_FIELD_BLUR' }]
- *     }
- *   },
- *   formatters: { capitalize: true },
- *   masks: { currency: { align: 'left', decimal: '.', precision: 2, prefix: '$', thousands: ',' } },
- *   children: [],
- *   visibility: true,
- *   persistValue: true,
- * };
+ * const callbackValidation: TCallbackValidation = (value) => typeof value === 'string';
  * ```
  */
-interface IComponentSchema {
-    /** The type of component (e.g., 'input', 'button'). */
-    component: string;
-    /** The properties of the component. */
-    props?: TProps;
-    /** The name of the component. */
-    name: string;
-    /** The name of the field when submit values. */
-    nameToSubmit?: string;
-    /** The validation methods for the component. */
-    validations?: TValidations;
-    /** The API configuration for the component. */
-    api?: TApiEvent;
-    /** The visibility conditions for the component. */
-    visibilityConditions?: TVisibility[];
-    /** The reset value methods for the component. */
-    resetValues?: TResetValueMethods[];
-    /** The reset property values for the component. */
-    resetPropertyValues?: TResetPathMethods[];
-    /** The formatters for the component. */
-    formatters?: TFormatters;
-    /** The masks for the component. */
-    masks?: TMasks;
-    /** The child components. */
-    children?: IComponentSchema[];
-    /** Visibility status the component will mount (to avoid SSR blinking) */
-    visibility?: boolean;
-    /** Check this if you want the last visible value to be restored after a visiblity schema rule applied  */
-    persistValue?: boolean;
-}
-interface IComponentSchemaAsFormField<T> extends IComponentSchema {
-    mapper?: TMapper<T>;
-    children?: IComponentSchemaAsFormField<T>[];
-}
+type TCallbackValidation = (value: unknown, formValues: Pick<TFormValues<unknown>, 'values' | 'metadata'>) => boolean;
 /**
- * @interface IFormSchema
- * Represents the schema for a form.
+ * @type TBetweenValidation
+ * Represents validation rules that check if a value is between a range.
  *
- * @property {string} index - The unique index or identifier for the form.
- * @property {string} [action] - The URL to which the form data will be submitted. (experimental)
- * @property {string} [method] - The HTTP method used to submit the form (e.g., 'POST', 'GET') (experimental).
- * @property {Record<string, unknown>} [initialValues] - The initial values for the form fields.
- * @property {Record<string, unknown>} [iVars] - Dynamic key value pairs that change from any external source
- * @property {IComponentSchema[]} [components] - The list of components included in the form.
- * @property {boolean} [stopEventsOnSubmit] - stop all the events declared as callback on useForm/Form once form is submitted
- * @property {TSchemaFormConfig} [config] - form configurations to change event debouncers and debugging tools
+ * @property {number} start - The start of the range.
+ * @property {number} end - The end of the range.
  *
  * @example
  * ```typescript
- * const formSchema: IFormSchema = {
- *   index: 'userForm',
- *   initialValues: { name: '', email: '' },
- *   iVars: iVarsState,
- *   config: {
- *     defaultLogVerbose: true
- *   },
- *   components: [
- *     { component: 'input', name: 'name', props: { placeholder: 'Enter your name' } },
- *     { component: 'input', name: 'email', props: { placeholder: 'Enter your email' } }
- *   ]
- * };
+ * const betweenValidation: TBetweenValidation = { start: 1, end: 10 };
  * ```
  */
-interface IFormSchema {
-    index: string;
-    action?: string;
-    method?: string;
-    config?: TSchemaFormConfig;
-    initialValues?: Record<string, unknown>;
-    iVars?: Record<string, unknown>;
-    components?: IComponentSchema[];
-    stopEventsOnSubmit?: boolean;
-    /** Pre-fetched API response data for SSR. Keys are field names, values contain the API responses to hydrate. */
-    prefetchedData?: Record<string, TPrefetchedFieldData>;
-}
+type TBetweenValidation = {
+    start: number;
+    end: number;
+};
 /**
- * Represents pre-fetched API data for a single field.
- * Used to hydrate API response caches during SSR so templates referencing API data resolve correctly.
+ * @type TCreditCardMatch
+ * Represents the options for credit card matching.
  *
- * @property {unknown} [defaultResponse] - The pre-fetched response for the field's default API config.
- * @property {Record<string, unknown>} [namedResponses] - Pre-fetched responses for named API configs.
- *
- * @example
- * ```typescript
- * const prefetchedData = {
- *   countryField: {
- *     defaultResponse: [{ id: 'BR', label: 'Brazil' }, { id: 'US', label: 'United States' }],
- *   },
- *   stateField: {
- *     namedResponses: { statesByCountry: [{ id: 'SP', label: 'São Paulo' }] },
- *   },
- * };
- * ```
- */
-interface TPrefetchedFieldData {
-    /** The pre-fetched response for the field's default API config. */
-    defaultResponse?: unknown;
-    /** Pre-fetched responses keyed by named API config name. */
-    namedResponses?: Record<string, unknown>;
-}
-
-/**
- * @type TFormValues<T>
- * Represents the values and state of a form. It has a generic type that allows the importer to determine which type values key will return.
- *
- * @property {Generic Type} values - The current values of the form fields.
- * @property {string[]} erroredFields - A list of field names that have errors.
- * @property {boolean} isValid - Indicates whether the form is valid.
- *
- * @example
- * ```typescript
- * const formValues: TFormValues = {
- *   values: { name: 'John', age: 30 },
- *   erroredFields: ['email'],
- *   isValid: false
- * };
- * ```
- */
-type TFormValues<T> = {
-    values: T;
-    metadata: unknown;
-    erroredFields: string[];
-    isValid: boolean;
-};
-/**
- * @type TFormEntry
- * Represents the entry configuration for a form.
- *
- * @property {IFormSchema} [schema] - The schema defining the structure and behavior of the form.
- * @property {Record<string, unknown>} [initialValues] - The initial values for the form fields.
- * @property {(data: TFormValues) => void} [onSubmit] - Callback function to handle form submission.
- * @property {Subject<TFormDataPayload>} [dataSubject$] - data subject passed from formGroup instance
- * @property {Subject<TFormValidationPayload>} [formValidSubject$] - formValid subject passed from formGroup instance
- * @property {Subject<TFormSubmitPayload<unknown>>} [submitSubject$] - submit subject passed from formGroup instance
- *
- * @example
- * ```typescript
- * const formEntry: TFormEntry = {
- *   schema: [{ component: 'input', props: {}, name: 'name' }],
- *   initialValues: { name: 'John' },
- *   onSubmit: (data) => { console.log(data); }
- * };
- * ```
- */
-type TFormEntry = Omit<IFormSchema, 'components'> & {
-    schema?: IFormSchema;
-    mappers?: TMapper<unknown>[];
-    dataSubject$?: Subject<TFormDataPayload>;
-    formValidSubject$?: Subject<TFormValidationPayload>;
-    submitSubject$?: Subject<TFormSubmitPayload<unknown>>;
-};
-
-declare const TEMPLATE_AVALIABLE_SCOPES: readonly ["fields", "iVars", "form"];
-declare const ALLOWED_RESET_PROPS_MUTATIONS: (keyof Pick<IFormField, "api" | "apiSchema" | "props" | "validations" | "visibilityConditions" | "resetValues">)[];
-
-/** @virtual */
-
-type TAllowedResetPropsMutations = (typeof ALLOWED_RESET_PROPS_MUTATIONS)[number];
-/**
- * @type TAllowedResetPropsMutationsEnum
- * Represents the allowed properties to be changed on resetPropertyValues.
- *
- * @property {never} api - api property
- * @property {never} apiSchema - apiSchema property
- * @property {never} props - props property
- * @property {never} validations - validations property
- * @property {never} visibilityConditions - visibilityConditions property
- * @property {never} resetValues - resetValues property
- *
- * @interface
- */
-type TAllowedResetPropsMutationsEnum = Record<TAllowedResetPropsMutations, never>;
-/**
- * @type TLengthValidation
- * Represents the validation rules based on the length of the input.
- *
- * @property {'equal' | 'notEqual' | 'less' | 'lessOrEqual' | 'greater' | 'greaterOrEqual'} rule - The rule to apply.
- * @property {number} target - The target value to compare against.
- *
- * @example
- * ```typescript
- * const lengthValidation: TLengthValidation = { rule: 'greaterOrEqual', target: 8 };
- * ```
- */
-type TLengthValidation = {
-    rule: 'equal' | 'notEqual' | 'less' | 'lessOrEqual' | 'greater' | 'greaterOrEqual';
-    target: number;
-};
-/**
- * @type TCallbackValidation
- * A custom validation function.
- *
- * @param {unknown} value - The value to validate.
- * @returns {boolean} - The result of the validation.
- *
- * @example
- * ```typescript
- * const callbackValidation: TCallbackValidation = (value) => typeof value === 'string';
- * ```
- */
-type TCallbackValidation = (value: unknown, formValues: Pick<TFormValues<unknown>, 'values' | 'metadata'>) => boolean;
-/**
- * @type TBetweenValidation
- * Represents validation rules that check if a value is between a range.
- *
- * @property {number} start - The start of the range.
- * @property {number} end - The end of the range.
- *
- * @example
- * ```typescript
- * const betweenValidation: TBetweenValidation = { start: 1, end: 10 };
- * ```
- */
-type TBetweenValidation = {
-    start: number;
-    end: number;
-};
-/**
- * @type TCreditCardMatch
- * Represents the options for credit card matching.
- *
- * @property {string} numberCard - The credit card number.
- * @property {string[]} availableOptions - The available options for matching.
+ * @property {string} numberCard - The credit card number.
+ * @property {string[]} availableOptions - The available options for matching.
  *
  * @example
  * ```typescript
@@ -2369,6 +2063,312 @@ type TFormGroupOnValidEventPayload = {
  */
 type TFormGroupOnSubmitEventPayload<T> = Record<string, TFormValues<T> | undefined>;
 
+type TComponentPropsMappingSubset = keyof (Pick<TEventPropsEnum, 'onBlur' | 'onChange' | 'onFocus' | 'onKeyDown' | 'onKeyUp' | 'onClick'> & Pick<TEventDataPropsEnum, 'onSubmit'>);
+/**
+ * @type TComponentPropsMapping
+ * Represents the mapping of component properties for various events and actions.
+ * @property {string} [getValue] - component function name to get the value.
+ * @property {string} [setValue] - component function name to set the value.
+ * @property {string} [setErrorMessage] - component function name to set the error message.
+ * @property {string} [setErrorState] - component function name to set the error state.
+ *
+ * @example
+ * ```typescript
+ * const componentProps: TComponentPropsMapping = {
+ *   getValue: 'getValueFunction',
+ *   setValue: 'setValueFunction',
+ *   onBlur: 'handleBlur',
+ *   onClick: 'handleClick',
+ *   onFocus: 'handleFocus',
+ *   onKeyUp: 'handleKeyUp',
+ *   onKeyDown: 'handleKeyDown',
+ *   setErrorMessage: 'setErrorMessageFunction',
+ *   setErrorState: 'setErrorStateFunction'
+ * };
+ * ```
+ * @interface
+ */
+type TComponentPropsMapping = Partial<Record<TComponentPropsMappingSubset, string>> & {
+    getValue?: string;
+    setValue?: string;
+    setErrorMessage?: string;
+    setErrorState?: string;
+};
+/**
+ * @type TMapper
+ * Represents the mapping of a component, including the component type,
+ * name, events, and an optional function to handle value changes.
+ *
+ * @property {ElementType} component - The component that will represent the input.
+ * * @property {ElementType} asynccomponent - The component that will represent the input but dynamically imported (suspense/lazy).
+ * @property {string} componentName - The name of the component.
+ * @property {TComponentPropsMapping} [events] - Mapping event properties for the component.
+ * @property {TValueChangeEvent} [valueChangeEvent] - Optional function to handle value changes.
+ *
+ * @example
+ * ```typescript
+ * const mappers: TMapper<ElementType>[] = [
+ *  {
+ *    component: InputElement,
+ *    componentName: 'input',
+ *    events: {
+ *      getValue: 'onChange2',
+ *      onBlur: 'onBlur2',
+ *      onFocus: 'onFocus2',
+ *    }
+ *  },
+ *  {
+ *    component: Container,
+ *    componentName: 'row',
+ *  },
+ *  {
+ *    component: Dropdown,
+ *    componentName: 'dropdown',
+ *    valueChangeEvent: (event: {
+ *      id: string;
+ *      label: string;
+ *      value: string;
+ *    }) => ({ _value: event.value, _stateValue: event.id }),
+ *  },
+ *  {
+ *    component: DatePicker,
+ *    componentName: 'datepicker',
+ *    valueChangeEvent: (event: string) => event,
+ *  },
+ * ];
+ * ```
+ * @interface
+ */
+type TMapper<T> = {
+    componentName: string;
+    events?: TComponentPropsMapping;
+    valueChangeEvent?: TValueChangeEvent;
+} & OneOf<{
+    component: T;
+    asynccomponent: T;
+}>;
+
+/**
+ * @interface IComponentSchema
+ * Represents the schema for a component within a form.
+ *
+ * @property {string} component - The type of component (e.g., 'input', 'button').
+ * @property {TProps} props - The properties of the component.
+ * @property {string} name - The name of the component.
+ * @property {string} nameToSubmit - The name of the field when submit values (optional).
+ * @property {TValidations} [validations] - The validation methods for the component.
+ * @property {TVisibility[]} [visibilityConditions] - The visibility conditions for the component.
+ * @property {TResetValueMethods[]} [resetValues] - The reset value methods for the component.
+ * @property {TApiEvent} [api] - The API configuration for the component.
+ * @property {TFormatters} [formatters] - The formatters for the component.
+ * @property {TMasks} [masks] - The masks for the component.
+ * @property {IComponentSchema[]} [children] - The child components.
+ * @property {boolean} visibility - visibility status the component will mount (to avoid SSR blinking)
+ * @property {boolean} persistValue - check this if you want the last visible value to be restored after a visiblity schema rule applied
+ *
+ * @example
+ * ```typescript
+ * const schema: IComponentSchema = {
+ *   component: 'input',
+ *   props: { type: 'text', placeholder: 'Enter your name' },
+ *   name: 'name',
+ *   nameToSubmit: 'applicant.firstName',
+ *   validations: {
+ *     methods: {
+ *       required: true,
+ *       regex: '^([0-9]+)*$',
+ *       max: 5,
+ *     },
+ *     eventMessages: {
+ *       ON_FIELD_MOUNT: ['required'],
+ *       ON_FIELD_CHANGE: ['regex', 'required'],
+ *       ON_FIELD_BLUR: ['max', 'required'],
+ *     },
+ *     messages: {
+ *       default: 'This field is required',
+ *       regex: 'Only numbers are available.',
+ *       max: 'Max of 5',
+ *     },
+ *   },
+ *   visibilityConditions: [{ conditions: { field: 'age', value: 18 } }],
+ *   resetValues: [{ field: 'age', resetTo: '' }],
+ *   api: {
+ *     defaultConfig: {
+ *       config: { method: 'POST', url: 'https://api.example.com/submit' },
+ *       events: [{ eventName: 'ON_FIELD_BLUR' }]
+ *     }
+ *   },
+ *   formatters: { capitalize: true },
+ *   masks: { currency: { align: 'left', decimal: '.', precision: 2, prefix: '$', thousands: ',' } },
+ *   children: [],
+ *   visibility: true,
+ *   persistValue: true,
+ * };
+ * ```
+ */
+interface IComponentSchema {
+    /** The type of component (e.g., 'input', 'button'). */
+    component: string;
+    /** The properties of the component. */
+    props?: TProps;
+    /** The name of the component. */
+    name: string;
+    /** The name of the field when submit values. */
+    nameToSubmit?: string;
+    /** The validation methods for the component. */
+    validations?: TValidations;
+    /** The API configuration for the component. */
+    api?: TApiEvent;
+    /** The visibility conditions for the component. */
+    visibilityConditions?: TVisibility[];
+    /** The reset value methods for the component. */
+    resetValues?: TResetValueMethods[];
+    /** The reset property values for the component. */
+    resetPropertyValues?: TResetPathMethods[];
+    /** The formatters for the component. */
+    formatters?: TFormatters;
+    /** The masks for the component. */
+    masks?: TMasks;
+    /** The child components. */
+    children?: IComponentSchema[];
+    /** Visibility status the component will mount (to avoid SSR blinking) */
+    visibility?: boolean;
+    /** Check this if you want the last visible value to be restored after a visiblity schema rule applied  */
+    persistValue?: boolean;
+}
+interface IComponentSchemaAsFormField<T> extends IComponentSchema {
+    mapper?: TMapper<T>;
+    children?: IComponentSchemaAsFormField<T>[];
+}
+/**
+ * @interface IFormSchema
+ * Represents the schema for a form.
+ *
+ * @property {string} index - The unique index or identifier for the form.
+ * @property {string} [action] - The URL to which the form data will be submitted. (experimental)
+ * @property {string} [method] - The HTTP method used to submit the form (e.g., 'POST', 'GET') (experimental).
+ * @property {Record<string, unknown>} [initialValues] - The initial values for the form fields.
+ * @property {Record<string, unknown>} [iVars] - Dynamic key value pairs that change from any external source
+ * @property {IComponentSchema[]} [components] - The list of components included in the form.
+ * @property {boolean} [stopEventsOnSubmit] - stop all the events declared as callback on useForm/Form once form is submitted
+ * @property {TSchemaFormConfig} [config] - form configurations to change event debouncers and debugging tools
+ *
+ * @example
+ * ```typescript
+ * const formSchema: IFormSchema = {
+ *   index: 'userForm',
+ *   initialValues: { name: '', email: '' },
+ *   iVars: iVarsState,
+ *   config: {
+ *     defaultLogVerbose: true
+ *   },
+ *   components: [
+ *     { component: 'input', name: 'name', props: { placeholder: 'Enter your name' } },
+ *     { component: 'input', name: 'email', props: { placeholder: 'Enter your email' } }
+ *   ]
+ * };
+ * ```
+ */
+interface IFormSchema {
+    index: string;
+    action?: string;
+    method?: string;
+    config?: TSchemaFormConfig;
+    initialValues?: Record<string, unknown>;
+    iVars?: Record<string, unknown>;
+    components?: IComponentSchema[];
+    stopEventsOnSubmit?: boolean;
+    /** Pre-fetched API response data for SSR. Keys are field names, values contain the API responses to hydrate. */
+    prefetchedData?: Record<string, TPrefetchedFieldData>;
+}
+/**
+ * Represents pre-fetched API data for a single field.
+ * Used to hydrate API response caches during SSR so templates referencing API data resolve correctly.
+ *
+ * @property {unknown} [defaultResponse] - The pre-fetched response for the field's default API config.
+ * @property {Record<string, unknown>} [namedResponses] - Pre-fetched responses for named API configs.
+ *
+ * @example
+ * ```typescript
+ * const prefetchedData = {
+ *   countryField: {
+ *     defaultResponse: [{ id: 'BR', label: 'Brazil' }, { id: 'US', label: 'United States' }],
+ *   },
+ *   stateField: {
+ *     namedResponses: { statesByCountry: [{ id: 'SP', label: 'São Paulo' }] },
+ *   },
+ * };
+ * ```
+ */
+interface TPrefetchedFieldData {
+    /** The pre-fetched response for the field's default API config. */
+    defaultResponse?: unknown;
+    /** Pre-fetched responses keyed by named API config name. */
+    namedResponses?: Record<string, unknown>;
+}
+
+/**
+ * @type TFormValues<T>
+ * Represents the values and state of a form. It has a generic type that allows the importer to determine which type values key will return.
+ *
+ * @property {Generic Type} values - The current values of the form fields.
+ * @property {string[]} erroredFields - A list of field names that have errors.
+ * @property {boolean} isValid - Indicates whether the form is valid.
+ *
+ * @example
+ * ```typescript
+ * const formValues: TFormValues = {
+ *   values: { name: 'John', age: 30 },
+ *   erroredFields: ['email'],
+ *   isValid: false
+ * };
+ * ```
+ */
+type TFormValues<T> = {
+    values: T;
+    metadata: unknown;
+    erroredFields: string[];
+    isValid: boolean;
+};
+/**
+ * @type TFormEntry
+ * Represents the entry configuration for a form.
+ *
+ * @property {IFormSchema} [schema] - The schema defining the structure and behavior of the form.
+ * @property {Record<string, unknown>} [initialValues] - The initial values for the form fields.
+ * @property {(data: TFormValues) => void} [onSubmit] - Callback function to handle form submission.
+ * @property {Subject<TFormDataPayload>} [dataSubject$] - data subject passed from formGroup instance
+ * @property {Subject<TFormValidationPayload>} [formValidSubject$] - formValid subject passed from formGroup instance
+ * @property {Subject<TFormSubmitPayload<unknown>>} [submitSubject$] - submit subject passed from formGroup instance
+ *
+ * @example
+ * ```typescript
+ * const formEntry: TFormEntry = {
+ *   schema: [{ component: 'input', props: {}, name: 'name' }],
+ *   initialValues: { name: 'John' },
+ *   onSubmit: (data) => { console.log(data); }
+ * };
+ * ```
+ */
+type TFormEntry = Omit<IFormSchema, 'components'> & {
+    schema?: IFormSchema;
+    mappers?: TMapper<unknown>[];
+    dataSubject$?: Subject<TFormDataPayload>;
+    formValidSubject$?: Subject<TFormValidationPayload>;
+    submitSubject$?: Subject<TFormSubmitPayload<unknown>>;
+};
+
+type AllowOnly<T, K extends keyof T> = Pick<T, K> & {
+    [P in keyof Omit<T, K>]?: never;
+};
+type OneOf<T, K = keyof T> = K extends keyof T ? AllowOnly<T, K> : never;
+type TValidationPayload = [
+    unknown,
+    TValidationMethods,
+    TFormValues<unknown>?
+];
+type TValidationHandler = Record<string, (...args: TValidationPayload) => boolean>;
+
 /**
  * Global mutable registries for validations, formatters, and masks.
  * Plugins (sub-path exports) can extend these at import time.