@bolttech/form-engine-core 1.0.2-beta.2 → 1.1.0-beta.0

package/index.esm.js

@@ -404,7 +404,7 @@ const regex$1 = (value, formatters) => {
 const getTypeCard = (value, availableOptions) => {
   const rawValue = removeGaps(value === null || value === void 0 ? void 0 : value.toString());
   const types = creditCardType(rawValue);
-  const selected = (availableOptions === null || availableOptions === void 0 ? void 0 : availableOptions.length) ? types === null || types === void 0 ? void 0 : types.filter(({
+  const selected = typeof availableOptions === 'object' && availableOptions.length ? types === null || types === void 0 ? void 0 : types.filter(({
     type: id1
   }) => availableOptions.some(id2 => id2 === id1))[0] : types[0];
   return [selected, rawValue];
@@ -1641,7 +1641,7 @@ const callback = (value, validations) => {
  */
 const includes = (value, validations) => {
   if (!value || !Array.isArray(validations === null || validations === void 0 ? void 0 : validations.includes)) return false;
-  return !validations.includes.some(code => code === value || JSON.stringify(code) === value);
+  return !(validations === null || validations === void 0 ? void 0 : validations.includes.some(code => code === value || JSON.stringify(code) === value));
 };
 
 /**
@@ -2526,7 +2526,6 @@ class FormField {
     this.name = schemaComponent.name;
     this.nameToSubmit = schemaComponent.nameToSubmit;
     this.component = schemaComponent.component;
-    this.path = path;
     this.children = children;
     this.validations = cloneDeep(schemaComponent.validations);
     this.visibilityConditions = cloneDeep(schemaComponent.visibilityConditions);
@@ -2784,7 +2783,7 @@ class FormField {
     var _a;
     if (typeof errors === 'undefined' || isEqual(errors, this.errors)) return;
     this._errors = errors;
-    this.errorsList = Object.values(this.errors);
+    this.errorsList = Object.values(this.errors).filter(el => el !== undefined && el !== null);
     this.errorsString = this.errorsList.join(', ');
     /**
      * if any error receives a list of errors, set a prop for it, currently only supporting a single string
@@ -3137,7 +3136,7 @@ class FormField {
     this.propsSubject$.unsubscribe();
     this.errorSubject$.unsubscribe();
     this.apiEventQueueSubject$.unsubscribe();
-    this.dataSubject$.next({
+    !this.dataSubject$.closed && this.dataSubject$.next({
       event: 'ON_FIELD_UNMOUNT',
       fieldIndex: this.name,
       formIndex: this.formIndex
@@ -3203,6 +3202,8 @@ class FormCore {
     this.queuedFieldResetPropertyEvents = new Map();
     this.queuedInitialValues = new Map();
     this._valid = false;
+    this.stopEventsOnSubmit = false;
+    this.submitted = false;
     this.index = entry.index;
     this.schema = entry.schema;
     this.fields = new Map();
@@ -3233,6 +3234,8 @@ class FormCore {
     this.mountSubject$.subscribe(this.mountActions.bind(this));
     this.initialValues = entry.initialValues || ((_j = entry.schema) === null || _j === void 0 ? void 0 : _j.initialValues);
     this.iVars = entry.iVars || ((_k = entry.schema) === null || _k === void 0 ? void 0 : _k.iVars) || {};
+    this.stopEventsOnSubmit = (entry === null || entry === void 0 ? void 0 : entry.stopEventsOnSubmit) || false;
+    this.submitted = false;
   }
   /**
    * mock function to simulate form mount onto the adapter
@@ -3246,6 +3249,13 @@ class FormCore {
       });
     });
   }
+  /**
+   *flag utility to prevent Subjects from emitting after form submission and stopEventsOnSubmit
+   * @returns {boolean} - result of the flag utility.
+   */
+  submitChecker() {
+    return !(this.stopEventsOnSubmit && this.submitted);
+  }
   /**
    * callback function passed to field instance to notify field adapter mount status
    * once the field has all field instance properties set, this function will handle all
@@ -3704,6 +3714,9 @@ class FormCore {
           });
         }
       } else {
+        fieldInstance.emitEvents({
+          event: 'ON_FIELD_UNMOUNT'
+        });
         if (fieldInstance.persistValue) {
           this.queuedInitialValues.set(fieldInstance.name, fieldInstance.value);
         }
@@ -3970,7 +3983,6 @@ class FormCore {
         });
       } else {
         currField.children = ((_a = structElement === null || structElement === void 0 ? void 0 : structElement.children) === null || _a === void 0 ? void 0 : _a.map(el => el.name)) || (currField === null || currField === void 0 ? void 0 : currField.children) || [];
-        currField.path = path;
         currField.originalSchema = structElement;
         currField.templateSubject$ = this.templateSubject$;
       }
@@ -4067,7 +4079,7 @@ class FormCore {
   subscribeFieldEvent({
     callback
   }) {
-    const sub = this.fieldEventSubject$.pipe(groupBy(payload => `${payload.event}|${payload.fieldName}`), mergeMap(group$ => group$.pipe(debounceTime(this.config.defaultStateRefreshTimeMS)))).subscribe({
+    const sub = this.fieldEventSubject$.pipe(filter(() => this.submitChecker()), groupBy(payload => `${payload.event}|${payload.fieldName}`), mergeMap(group$ => group$.pipe(debounceTime(this.config.defaultStateRefreshTimeMS)))).subscribe({
       next: callback
     });
     return sub;
@@ -4091,7 +4103,7 @@ class FormCore {
   subscribeData(callback) {
     const sub = this.dataSubject$.pipe(filter(({
       formIndex
-    }) => this.index === formIndex), groupBy(payload => payload.event), mergeMap(group$ => group$.pipe(debounceTime(this.config.defaultStateRefreshTimeMS))), map(({
+    }) => this.index === formIndex && this.submitChecker()), groupBy(payload => payload.event), mergeMap(group$ => group$.pipe(debounceTime(this.config.defaultStateRefreshTimeMS))), map(({
       fieldIndex
     }) => ({
       field: fieldIndex,
@@ -4109,7 +4121,7 @@ class FormCore {
   subscribeOnSubmit(callback) {
     const sub = this.submitSubject$.pipe(filter(({
       formIndex
-    }) => formIndex === this.index), map(({
+    }) => formIndex === this.index && this.submitChecker()), map(({
       values
     }) => values)).subscribe({
       next: callback
@@ -4124,7 +4136,7 @@ class FormCore {
   subscribeFormValidation(callback) {
     const sub = this.formValidSubject$.pipe(filter(({
       formIndex
-    }) => this.index === formIndex), debounceTime(this.config.defaultStateRefreshTimeMS), map(() => ({
+    }) => this.index === formIndex), map(() => ({
       formIndex: this.index,
       valid: this.valid
     })), distinctUntilKeyChanged('valid'), startWith({
@@ -4150,6 +4162,7 @@ class FormCore {
       formIndex: this.index,
       values
     });
+    this.submitted = true;
   }
   /**
    * recycles all the Suscriptions, to be called from the adapter when the form leaves the page
@@ -4339,9 +4352,10 @@ class FormGroup {
       var _a, _b;
       (_a = this.forms.get(index)) === null || _a === void 0 ? void 0 : _a.submit();
       const res = (_b = this.forms.get(index)) === null || _b === void 0 ? void 0 : _b.getFormValues();
+      const formMetadata = typeof (res === null || res === void 0 ? void 0 : res.metadata) === 'object' && res.metadata !== null ? res.metadata : {};
       isValid = isValid && ((res === null || res === void 0 ? void 0 : res.isValid) || false);
       values = Object.assign(Object.assign({}, values), (res === null || res === void 0 ? void 0 : res.values) || {});
-      metadata = Object.assign(Object.assign({}, metadata), (res === null || res === void 0 ? void 0 : res.metadata) || {});
+      metadata = Object.assign(Object.assign({}, metadata), formMetadata);
       erroredFields = [...erroredFields, ...((res === null || res === void 0 ? void 0 : res.erroredFields) || [])];
     });
     isValid && callback && callback({
@@ -4384,7 +4398,7 @@ class FormGroup {
       formIndex
     }) => ids.includes(formIndex)), groupBy(({
       formIndex
-    }) => formIndex), mergeMap(group$ => group$.pipe(debounceTime(this.config.defaultStateRefreshTimeMS))), startWith({
+    }) => formIndex), mergeMap(group$ => group$.pipe(debounceTime(0))), startWith({
       fieldTrigger: null
     }), map(() => ({
       groupValid: ids.every(id => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bolttech/form-engine-core",
-  "version": "1.0.2-beta.2",
+  "version": "1.1.0-beta.0",
   "module": "./index.esm.js",
   "type": "module",
   "main": "./index.esm.js",

package/src/formatters/string.d.ts

@@ -60,7 +60,7 @@ export declare const onlyFloatNumber: (value: unknown, formatters: TFormatters)
  * console.log(trimmedValue); // Output: 'hello world'
  * ```
  */
-export declare const trim: (value: unknown, formatters: TFormatters) => unknown;
+export declare const trim: (value: unknown, formatters?: TFormatters) => unknown;
 /**
  * Truncates the input value to a specified maximum length if necessary.
  *
@@ -85,4 +85,4 @@ export declare const trim: (value: unknown, formatters: TFormatters) => unknown;
  * console.log(result); // "Short" (no truncation since input is shorter than maxLength)
  * ```
  */
-export declare const maxLength: (value: string | number, formatters: TFormatters) => string | number;
+export declare const maxLength: (value: string | number | null | undefined, formatters: TFormatters) => string | number | null | undefined;

package/src/helpers/creditCard.d.ts

@@ -67,7 +67,7 @@ export type TGetTypeCard = [ICreditCardType, string];
  * console.log(rawValue); // Output: '4111111111111111'
  * ```
  */
-export declare const getTypeCard: (value: string, availableOptions?: string[]) => TGetTypeCard;
+export declare const getTypeCard: (value: string, availableOptions?: string[] | boolean) => TGetTypeCard;
 /**
  * Formats a credit card number according to its type's gaps and lengths.
  *

package/src/helpers/helpers.d.ts

@@ -1,7 +1,6 @@
 /// <reference types="node" />
-import { TEMPLATE_AVALIABLE_SCOPES } from '../constants/constants';
 import { TApiResponsePayload } from '../types/schema';
-import { TSubscribedTemplates } from '../types/template';
+import { TSubscribedTemplates, TTemplateAvaliableScopes } from '../types/template';
 import { OutgoingHttpHeaders } from 'http2';
 /**
  * Makes an HTTP request using XMLHttpRequest.
@@ -34,7 +33,7 @@ declare function makeRequest(method: string, url: string, headers?: OutgoingHttp
  * ```
  */
 declare function extractFieldKeys(expression: string): {
-    originScopeKeys: (typeof TEMPLATE_AVALIABLE_SCOPES)[number][];
+    originScopeKeys: TTemplateAvaliableScopes[];
     originFieldKeys: string[];
     originPropertyKeys: string[];
 };

package/src/interfaces/schema.d.ts

@@ -44,7 +44,12 @@ import { TApiEvent, TFormatters, TMasks, TProps, TResetPathMethods, TResetValueM
  *   },
  *   visibilityConditions: [{ conditions: { field: 'age', value: 18 } }],
  *   resetValues: [{ field: 'age', resetTo: '' }],
- *   api: { defaultConfig: { config: { method: 'POST', url: 'https://api.example.com/submit' }, events: [{ eventName: 'ON_FORM_SUBMIT' }] } },
+ *   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: [],
@@ -54,24 +59,37 @@ import { TApiEvent, TFormatters, TMasks, TProps, TResetPathMethods, TResetValueM
  * ```
  */
 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>;
-    order?: number;
     children?: IComponentSchemaAsFormField<T>[];
 }
 /**
@@ -79,20 +97,23 @@ interface IComponentSchemaAsFormField<T> extends IComponentSchema {
  * 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.
- * @property {string} [method] - The HTTP method used to submit the form (e.g., 'POST', 'GET').
+ * @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',
- *   action: 'https://api.example.com/submit',
- *   method: 'POST',
  *   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' } }
@@ -108,5 +129,6 @@ interface IFormSchema {
     initialValues?: Record<string, unknown>;
     iVars?: Record<string, unknown>;
     components?: IComponentSchema[];
+    stopEventsOnSubmit?: boolean;
 }
 export { IFormSchema, IComponentSchema, IComponentSchemaAsFormField };

package/src/managers/field.d.ts

@@ -15,7 +15,6 @@ declare class FormField {
     name: string;
     nameToSubmit?: string;
     component: string;
-    path?: string;
     children?: string[];
     originalSchema: IComponentSchemaAsFormField<unknown>;
     validations?: TValidations;

package/src/managers/form.d.ts

@@ -2,11 +2,10 @@ import { IFormField } from './field';
 import { Subject, Subscription } from 'rxjs';
 import { IComponentSchema, IComponentSchemaAsFormField, IFormSchema } from '../interfaces/schema';
 import { TSchemaFormConfig } from '../types/schema';
-import { TSubscribedTemplates, TTemplateEvent } from '../types/template';
+import { TSubscribedTemplates, TTemplateAvaliableScopes, TTemplateEvent } from '../types/template';
 import { TEvents, TFieldEvent, TFieldValidationPayload, TFormDataPayload, TFormSubmitPayload, TFormValidationPayload, TMutationEvents } from '../types/event';
 import { TFormEntry, TFormValues } from '../types/form';
 import { TMapper } from '../types/mapper';
-import { TEMPLATE_AVALIABLE_SCOPES } from '../constants/constants';
 /**
  * Represents the core logic for managing a form, including field management, validation, and submission.
  */
@@ -45,6 +44,8 @@ declare class FormCore {
     }>;
     queuedInitialValues: Map<string, unknown>;
     _valid: boolean;
+    stopEventsOnSubmit: boolean;
+    submitted: boolean;
     /**
      * Creates an instance of FormCore.
      *
@@ -61,6 +62,11 @@ declare class FormCore {
      * mock function to simulate form mount onto the adapter
      */
     generateFields(): void;
+    /**
+     *flag utility to prevent Subjects from emitting after form submission and stopEventsOnSubmit
+     * @returns {boolean} - result of the flag utility.
+     */
+    private submitChecker;
     /**
      * callback function passed to field instance to notify field adapter mount status
      * once the field has all field instance properties set, this function will handle all
@@ -112,7 +118,7 @@ declare class FormCore {
      * @returns {unknown | undefined} The value of the property, or undefined if the field doesn't exist.
      */
     getValue({ scope, key, property, path, }: {
-        scope: (typeof TEMPLATE_AVALIABLE_SCOPES)[number];
+        scope: TTemplateAvaliableScopes;
         key: string;
         property: string;
         path: string[];

package/src/masks/generic.d.ts

@@ -35,5 +35,5 @@ import { TMasks } from '../types/schema';
  * console.log(maskedValue); // Output: 'ab***gh###'
  * ```
  */
-declare const _default: (value: string, masks: TMasks) => string;
+declare const _default: (value: string, masks: TMasks | null) => string;
 export default _default;

package/src/masks/handler.d.ts

@@ -1,2 +1,2 @@
 import { TMasks } from '../types/schema';
-export declare const masks: Record<keyof TMasks, (value: unknown, masks?: TMasks) => unknown>;
+export declare const masks: Record<keyof TMasks, (value: unknown, masks?: TMasks | null) => unknown>;

package/src/types/event.d.ts

@@ -1,15 +1,81 @@
 import { IFormField } from '../managers';
 import { TFormValues } from './form';
 /**
- * @type TEvents
+ * @type TEventEnum
  * Represents the different types of events that can occur on form fields.
+ * @property {never} ON_FIELD_MOUNT - when field mounts on page
+ * @property {never} ON_FIELD_UNMOUNT - when field unmounts on page (also triggered when form is unmounted from page)
+ * @property {never} ON_FIELD_CHANGE - when field changes value by user inout
+ * @property {never} ON_FIELD_BLUR - when field is blurred
+ * @property {never} ON_FIELD_FOCUS - when field is focused
+ * @property {never} ON_FIELD_CLICK - when field is clicked
+ * @property {never} ON_FIELD_KEYUP - when the pressing key button on field is lifted up
+ * @property {never} ON_FIELD_KEYDOWN - when a key button on field is pressed down
+ * @property {never} ON_FIELD_CLEARED - when a field was changed with a resetValues rule
+ * @property {never} ON_FORM_SUBMIT - when the form is submitted (only type="submit" buttons)
+ * @property {never} ON_FIELD_VALIDATION - when a field is validaded by a validation rule
+ * @property {never} ON_FORM_MOUNT - emitted when the form mounts
+ * @property {never} ON_API_FIELD_REQUEST - emitted when an api request from schema is called
+ * @property {never} ON_API_FIELD_RESPONSE - emitted when an api response from schema is received
  *
  * @example
  * ```typescript
  * const event: TEvents = 'ON_FIELD_CHANGE';
  * ```
  */
-type TEvents = 'ON_FIELD_MOUNT' | 'ON_FIELD_UNMOUNT' | 'ON_FIELD_CHANGE' | 'ON_FIELD_BLUR' | 'ON_FIELD_FOCUS' | 'ON_FIELD_CLICK' | 'ON_FIELD_KEYUP' | 'ON_FIELD_KEYDOWN' | 'ON_FIELD_CLEARED' | 'ON_FORM_SUBMIT' | 'ON_FIELD_VALIDATION' | 'ON_FORM_MOUNT' | 'ON_API_FIELD_REQUEST' | 'ON_API_FIELD_RESPONSE';
+type TEventEnum = {
+    ON_FIELD_MOUNT: never;
+    ON_FIELD_UNMOUNT: never;
+    ON_FIELD_CHANGE: never;
+    ON_FIELD_BLUR: never;
+    ON_FIELD_FOCUS: never;
+    ON_FIELD_CLICK: never;
+    ON_FIELD_KEYUP: never;
+    ON_FIELD_KEYDOWN: never;
+    ON_FIELD_CLEARED: never;
+    ON_FORM_SUBMIT: never;
+    ON_FIELD_VALIDATION: never;
+    ON_FORM_MOUNT: never;
+    ON_API_FIELD_REQUEST: never;
+    ON_API_FIELD_RESPONSE: never;
+};
+type TEvents = keyof TEventEnum;
+/**
+ * Represents the possible event properties for form fields callbacks.
+ * * Represents a mapping of event properties to their corresponding callback functions.
+ * @property {string} onChange - trigger bind component change event
+ * @property {string} onBlur - trigger bind component blur event
+ * @property {string} onFocus - trigger bind component focus event
+ * @property {string} onKeyDown - trigger bind component keydown event
+ * @property {string} onKeyUp - trigger bind component keyup event
+ * @property {string} onMount - triggered on field mount
+ * @property {string} onApiResponse - triggered when schema api call is completed
+ * @property {string} onApiRequest - triggered when schema api call starts
+ * @property {string} onClick - trigger bind component keyup event
+ * @property {string} onCleared - triggered when a resetValue rule apply on the target field
+ * @property {string} onUnmount - triggered when a field unmounts
+ */
+type TEventPropsEnum = {
+    onChange: never;
+    onBlur: never;
+    onFocus: never;
+    onKeyDown: never;
+    onKeyUp: never;
+    onMount: never;
+    onApiResponse: never;
+    onApiRequest: never;
+    onClick: never;
+    onCleared: never;
+    onUnmount: never;
+};
+type TEventProps = keyof TEventPropsEnum;
+type TEventDataPropsEnum = {
+    onFormMount: never;
+    onData: never;
+    onSubmit: never;
+    onValid: never;
+};
+type TEventDataProps = keyof TEventDataPropsEnum;
 /**
  * @type TMutationEvents
  * Represents the different types of events that can occur internally that triggers templating.
@@ -106,4 +172,4 @@ type TFormGroupOnValidEventPayload = {
  * Form Group onSubmit event emitted payload on callback function parameter
  */
 type TFormGroupOnSubmitEventPayload<T> = Record<string, TFormValues<T> | undefined>;
-export { TEvents, TMutationEvents, TMutationEnum, TValueChangeEvent, TFieldEvent, TFormDataPayload, TFormDataValues, TFormSubmitPayload, TFormGroupOnDataEventPayload, TFormGroupOnValidEventPayload, TFormGroupOnSubmitEventPayload, TFormValidationPayload, TFieldValidationPayload, };
+export { TEvents, TEventEnum, TEventProps, TEventPropsEnum, TEventDataProps, TEventDataPropsEnum, TMutationEvents, TMutationEnum, TValueChangeEvent, TFieldEvent, TFormDataPayload, TFormDataValues, TFormSubmitPayload, TFormGroupOnDataEventPayload, TFormGroupOnValidEventPayload, TFormGroupOnSubmitEventPayload, TFormValidationPayload, TFieldValidationPayload, };

package/src/types/mapper.d.ts

@@ -1,18 +1,13 @@
-import { TValueChangeEvent } from './event';
+import { TEventDataPropsEnum, TEventPropsEnum, TValueChangeEvent } from './event';
 import { OneOf } from './utility';
+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] - Function to get the value.
- * @property {string} [setValue] - Function to set the value.
- * @property {string} [onBlur] - Function to handle the blur event.
- * @property {string} [onClick] - Function to handle the click event.
- * @property {string} [onFocus] - Function to handle the focus event.
- * @property {string} [onKeyUp] - Function to handle the keyup event.
- * @property {string} [onKeyDown] - Function to handle the keydown event.
- * @property {string} [setErrorMessage] - Function to set the error message.
- * @property {string} [setErrorState] - Function to set the error state.
+ * @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
@@ -28,16 +23,11 @@ import { OneOf } from './utility';
  *   setErrorState: 'setErrorStateFunction'
  * };
  * ```
+ * @interface
  */
-type TComponentPropsMapping = {
+type TComponentPropsMapping = Partial<Record<TComponentPropsMappingSubset, string>> & {
     getValue?: string;
     setValue?: string;
-    onBlur?: string;
-    onClick?: string;
-    onSubmit?: string;
-    onFocus?: string;
-    onKeyUp?: string;
-    onKeyDown?: string;
     setErrorMessage?: string;
     setErrorState?: string;
 };
@@ -46,14 +36,15 @@ type TComponentPropsMapping = {
  * Represents the mapping of a component, including the component type,
  * name, events, and an optional function to handle value changes.
  *
- * @property {ElementType} component - The type of the component.
+ * @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[] = [
+ * const mappers: TMapper<ElementType>[] = [
  *  {
  *    component: InputElement,
  *    componentName: 'input',
@@ -83,6 +74,7 @@ type TComponentPropsMapping = {
  *  },
  * ];
  * ```
+ * @interface
  */
 type TMapper<T> = {
     componentName: string;

package/src/types/schema.d.ts

@@ -118,7 +118,7 @@ type TDateOperatorsValidation = '<' | '>' | '===' | '>=' | '<=' | '!==' | '!!ori
 type TConditionsValidationSet = {
     forceDefinedOrigin?: boolean;
     forceDefinedTarget?: boolean;
-    origin?: string | number | boolean;
+    origin?: string | number | boolean | null;
     condition: TDateOperatorsValidation;
     target?: string | number | boolean;
 };
@@ -398,36 +398,67 @@ type TDateValidation = {
  * ```
  */
 type TValidationMethods = {
+    /** Maximum value or length. */
     max?: number;
+    /** Minimum value or length. */
     min?: number;
+    /** Minimum value or length. */
     lessThan?: number;
+    /** Minimum value or length. */
     greaterThan?: number;
+    /** Length validation rule. */
     length?: TLengthValidation;
+    /** Indicates if the field is required. */
     required?: boolean;
+    /** Specific value to match. */
     value?: unknown;
+    /** Regular expression for validation. */
     regex?: string;
+    /** Indicates if the value should be a valid email. */
     email?: boolean;
+    /** Indicates if the value should be a valid URL. */
     url?: boolean;
+    /** Indicates if the value should contain only letters. */
     onlyLetters?: boolean;
+    /** Indicates if spaces are not allowed. */
     notAllowSpaces?: boolean;
+    /** Custom validation callback function. */
     callback?: TCallbackValidation;
+    /** Indicates if the value should be a number. */
     isNumber?: boolean;
+    /** Indicates if the value should be a boolean or a string that can be converted to a boolean. */
     bool?: boolean | string;
+    /** Indicates if the value should exist or match a specific existence condition. */
     exists?: boolean | string;
+    /** Indicates if there should be no extra spaces. */
     hasNoExtraSpaces?: boolean;
+    /** Indicates if the field should not be empty. */
     notEmpty?: boolean;
+    /** Validation rule for range between two values. */
     between?: TBetweenValidation;
+    /** Indicates if the value should be sequential. */
     sequential?: boolean;
+    /** Indicates if the value should not be repeated. */
     repeated?: boolean;
+    /** Array of values that should be included. */
     includes?: (string | number)[];
+    /** Array of valid credit card numbers. */
     isCreditCard?: string[];
+    /** Validation rule for credit card matching. */
     isCreditCodeMatch?: TCreditCardMatch;
+    /** Array of valid credit card numbers with length check. */
     isCreditCardAndLength?: string[];
+    /** Document validation rule. */
     document?: TDocumentValidation;
+    /** Conditional validation rules. */
     conditions?: TConditionsValidation;
+    /** Multiple validation rules combined with a logical rule. */
     multipleValidations?: TMultipleValidation;
+    /** Validation rule for checking if a date falls between two dates. */
     betweenDates?: TBetweenDatesValidation;
+    /** Validation rule for date values. */
     date?: TDateValidation;
+    /** Validation rule for valid date formats. */
     validDate?: TDateFormatsValidation;
 };
 /**
@@ -446,9 +477,7 @@ type TValidationMethods = {
  *   },
  * };
  */
-type TGenericValidationRule = {
-    [key: string]: TValidationMethods;
-};
+type TGenericValidationRule = Record<string, TValidationMethods>;
 /**
  * @type {TValidationMethods | TGenericValidationRule} TSchemaValidation
  * Represents the schema validation which can be either a set of validation methods or a generic validation rule.
@@ -469,6 +498,7 @@ type TGenericValidationRule = {
  *     minLength: 8,
  *   },
  * };
+ * @interface
  */
 type TSchemaValidation = TValidationMethods | TGenericValidationRule;
 /**
@@ -522,17 +552,26 @@ type TSplitterFormatterValue = {
  * ```
  */
 type TFormatters = {
+    /** Add a dot every 3 characters. */
     dotEvery3chars?: boolean;
+    /** Capitalize the value. */
     capitalize?: boolean;
+    /** Convert the value to uppercase. */
     uppercase?: boolean;
+    /** Allow only numbers. */
     onlyNumbers?: boolean;
+    /** Allow only letters. */
     onlyLetters?: boolean;
+    /** Allow only float numbers with specific precision and decimal. */
     onlyFloatNumber?: Pick<TCurrencyMask, 'precision' | 'decimal'>;
+    /** Regular expression for formatting. */
     regex?: string;
-    gapsCreditCard?: string[];
-    callback?: (value: unknown) => unknown;
+    gapsCreditCard?: string[] | boolean;
+    callback?: ((value: unknown) => unknown) | null;
     splitter?: TSplitterFormatterValue[];
+    /** Removes whitespace from both ends of this string and returns a new string, without modifying the original string. */
     trim?: boolean;
+    /** Truncates the input value to a specified maximum length if necessary. */
     maxLength?: number;
 };
 /**
@@ -612,15 +651,24 @@ type TMaskGeneric = {
  * ```
  */
 type TMasks = {
+    /** Mask for currency values. */
     currency?: TCurrencyMask;
+    /** Array of generic masks. */
     generic?: TMaskGeneric[];
-    custom?: string;
+    /** Custom mask pattern. */
+    custom?: string | null;
+    /** Mask for securing credit card values. */
     secureCreditCard?: boolean;
+    /** Mask for card values. */
     card?: boolean;
+    /** Mask for card date values. */
     cardDate?: boolean;
+    /** Mask for FEIN (Federal Employer Identification Number). */
     fein?: boolean;
+    /** Value to replace all matches. */
     replaceAll?: string | number;
-    callback?(value: unknown): string;
+    /** Custom mask callback function. */
+    callback?: (value: unknown) => string;
 };
 /**
  * @type TVisibility
@@ -645,13 +693,19 @@ type TVisibility = {
     showOnlyIfTrue?: boolean;
     validations: TSchemaValidation;
     fields: string[] | string;
-    events: Partial<TEvents>[];
+    events: TEvents[];
 };
 /**
  * @type TResetValueMethods
- * Extends TVisibility with methods to reset values.
+ * @extends TVisibility with methods to reset values.
+ * @summary schema method to reset values from event
+ * much cool such wow
+ *
+ * @property {unknown[] | unknown} resettledValue - The values to reset.
+ * @property {Partial<TEvents>[]} events - events that will react to the value reset
+ * @property {string | string[]} fields - fields that will react to the value reset
+ * @property {TSchemaValidation} validations - validations to trigger the property reset
  *
- * @property {string[] | string} resettledValue - The values to reset.
  *
  * @example
  * ```typescript
@@ -661,11 +715,32 @@ type TVisibility = {
  *   resettledValue: ['']
  * };
  * ```
+ * @interface
  */
 type TResetValueMethods = Omit<TVisibility, 'showOnlyIfTrue' | 'validations'> & {
     resettledValue: unknown[] | unknown;
     validations?: TSchemaValidation;
 };
+/**
+ * @type TResetPathMethods
+ * Method to reset some field properties other than component props or field value
+ *
+ * @property {(typeof ALLOWED_RESET_PROPS_MUTATIONS)[number]} property property to be changed, ex: api, resetValues, etc..
+ * @property {string} path path where the property to be changed is located
+ * @property {string} field field that will recieve the property change
+ * @property {unknown} resettledValue value to be replaced onto the property
+ * @property {TSchemaValidation} validations validations rules to be validated to change the property value
+ * @property {Partial<TEvents>[]} events events to listen to apply this change
+ *
+ * @example
+ * ```typescript
+ * const resetValueMethods: TResetValueMethods = {
+ *   validations: { required: true },
+ *   fields: ['fieldName'],
+ *   resettledValue: ['']
+ * };
+ * ```
+ */
 type TResetPathMethods = {
     property: (typeof ALLOWED_RESET_PROPS_MUTATIONS)[number];
     path: string;
@@ -703,15 +778,25 @@ type TResetPathMethods = {
  * ```
  */
 type TApiConfig = {
+    /** The HTTP method for the request. */
     method: 'GET' | 'POST';
+    /** The URL for the request. */
     url: string;
+    /** The body payload for the request. */
     body?: Record<string, unknown>;
+    /** The headers for the request. */
     headers?: OutgoingHttpHeaders;
+    /** Query parameters for the request. */
     queryParams?: Record<string, string>;
+    /** The path to extract the result from the response. */
     resultPath?: string;
+    /** The fallback value if the request fails. */
     fallbackValue?: unknown;
+    /** Validation conditions to execute the API call. */
     preConditions?: TSchemaValidation;
+    /** Blocks request when field validation fails. */
     blockRequestWhenInvalid?: boolean;
+    /** Custom transform callback for the request payload. */
     transform?: {
         callback(callbackPayload: {
             payload: unknown;
@@ -750,15 +835,45 @@ type TProps = Record<string, unknown>;
  *     regex: 'Value does not match the pattern',
  *   },
  * };
+ * @interface
  */
 type TValidations = {
     methods: TSchemaValidation;
-    eventMessages?: Partial<Record<TEvents, Partial<keyof TValidationMethods | (string & NonNullable<unknown>)>[]>>;
+    eventMessages?: TEventMessages;
     messages?: TErrorMessages;
 };
+/**
+ * @type TValidations
+ * Represents the validation configuration for form fields, including methods, event-specific messages, and error messages.
+ *
+ * @property {TSchemaValidation} methods - The validation methods to be applied.
+ * @property {Partial<Record<TEvents, string[]>>} eventMessages - The messages to be displayed for specific validation events.
+ * @property {TErrorMessages} messages - The general error messages for validation methods.
+ *
+ * @example
+ * ```typescript
+ * const eventMessages: {
+ *     ON_FIELD_MOUNT: ['required'],
+ *     ON_FIELD_CHANGE: ['regex', 'required'],
+ *     ON_FIELD_BLUR: ['max', 'required'],
+ *   },
+ * ```
+ * @interface
+ */
+type TEventMessages = Partial<Record<TEvents, TEventMessagesValidationMethods[]>>;
+/**
+ * @type TEventMessagesValidationMethods
+ *
+ * allowed validation methods to trigger the event messages desc
+ *
+ * @property {keyof TValidationMethods | TAnyKey;} TEventMessagesValidationMethods - allowed validation methods to trigger the event messages
+ */
+type TEventMessagesValidationMethods = keyof TValidationMethods | TAnyKey;
+type TAnyKey = string & NonNullable<unknown>;
 /**
  * @type TErrorMessages
  * Represents the error messages for different validation methods.
+ * @property {string} default - the message to display regardless the validation
  *
  * @example
  * ```typescript
@@ -768,14 +883,9 @@ type TValidations = {
  *   default: 'Default error message'
  * };
  * ```
+ * @interface
  */
-type TErrorMessages = {
-    [K in keyof TSchemaValidation]?: string;
-} & {
-    default?: string;
-} & {
-    [key: string]: string;
-};
+type TErrorMessages = Partial<Record<keyof TSchemaValidation | 'default' | (string & NonNullable<unknown>), string>>;
 /**
  * Represents an event configuration with a specific type.
  *
@@ -785,13 +895,49 @@ type TErrorMessages = {
  */
 type TEvent<T> = {
     config: T;
-    events: Partial<TEvents>[];
+    events: TEvents[];
 };
 /**
  * Represents the API event configurations.
  *
  * @property {TEvent<TApiConfig>} [defaultConfig] - The default event configuration.
  * @property {Record<string, TEvent<TApiConfig>>} [configs] - Named event configurations.
+ *
+ * @example
+ * ```typescript
+ * const apiEvent: TApiEvent = {
+ *   defaultConfig: {
+ *     config: {
+ *       method: 'POST',
+ *       url: 'https://api.example.com/data',
+ *       headers: { 'Content-Type': 'application/json' },
+ *       resultPath: 'data.results',
+ *       fallbackValue: [],
+ *       preConditions: {
+ *         required: true,
+ *       },
+ *       blockRequestWhenInvalid: true,
+ *     },
+ *     events: ['ON_FIELD_MOUNT', 'ON_FIELD_CHANGE'],
+ *   },
+ *   configs: {
+ *     example_config_name: {
+ *       config: {
+ *         method: 'POST',
+ *         url: 'https://api.example.com/data',
+ *         headers: { 'Content-Type': 'application/json' },
+ *         resultPath: 'data.results',
+ *         fallbackValue: [],
+ *         preConditions: {
+ *           required: true,
+ *         },
+ *         blockRequestWhenInvalid: true,
+ *       },
+ *       events: ['ON_FIELD_MOUNT', 'ON_FIELD_CHANGE'],
+ *     },
+ *   },
+ * };
+ * ```
  */
 type TApiEvent = {
     defaultConfig?: TEvent<TApiConfig>;
@@ -825,6 +971,7 @@ type TApiResponse = {
  * Represents the schema config structure
  *
  * @property {number} defaultAPIdebounceTimeMS - default API debounce time between request events.
+ * @property {boolean} defaultLogVerbose - flag to turn warning log messages on client.
  * @property {number} [defaultStateRefreshTimeMS] - default state refresh between events side effects.
  */
 type TSchemaFormConfig = {
@@ -832,4 +979,4 @@ type TSchemaFormConfig = {
     defaultStateRefreshTimeMS?: number;
     defaultLogVerbose?: boolean;
 };
-export { TApiConfig, TErrorMessages, TValidations, TMasks, TProps, TResetValueMethods, TResetPathMethods, TFormatters, TValidationMethods, TGenericValidationRule, TSchemaValidation, TEvent, TVisibility, TApiEvent, TApiResponsePayload, TApiResponse, TSchemaFormConfig, TLengthValidation, TCreditCardMatch, TDocumentValidation, TCallbackValidation, TBetweenValidation, TMaskGeneric, TSplitterFormatterValue, TCurrencyMask, TDateOperatorsValidation, TConditionsValidationSet, TConditionsValidation, TMultipleValidation, TAvailableValidations, TDateValidation, TBetweenDatesValidation, TDateFormatsValidation, TDateInterval, };
+export { TApiConfig, TErrorMessages, TValidations, TMasks, TProps, TResetValueMethods, TResetPathMethods, TFormatters, TValidationMethods, TGenericValidationRule, TSchemaValidation, TEvent, TVisibility, TApiEvent, TApiResponsePayload, TApiResponse, TSchemaFormConfig, TLengthValidation, TCreditCardMatch, TDocumentValidation, TCallbackValidation, TBetweenValidation, TMaskGeneric, TSplitterFormatterValue, TCurrencyMask, TDateOperatorsValidation, TConditionsValidationSet, TConditionsValidation, TMultipleValidation, TAvailableValidations, TDateValidation, TBetweenDatesValidation, TDateFormatsValidation, TDateInterval, TEventMessages, TEventMessagesValidationMethods, };

package/src/types/template.d.ts

@@ -1,11 +1,26 @@
-import { TEMPLATE_AVALIABLE_SCOPES } from '../constants/constants';
 import { TMutationEvents } from './event';
+import { TEMPLATE_AVALIABLE_SCOPES } from '../constants/constants';
+type TTemplateAvaliableScopes = (typeof TEMPLATE_AVALIABLE_SCOPES)[number];
+/**
+ * @type TTemplateAvaliableScopesEnum
+ * Represents the different types of events that can occur on form fields.
+ * @property {never} fields - scope related to field content ex: '${fields.fieldName.value}'
+ * @property {never} iVars - scope related to iVars content ex: '${iVars.test}'
+ * @property {never} form - scope related to form content ex: '${form.valid}'
+ *
+ * @example
+ * ```typescript
+ * const scope: TTemplateAvaliableScopesEnum = 'fields';
+ * ```
+ * @interface
+ */
+type TTemplateAvaliableScopesEnum = Record<TTemplateAvaliableScopes, never>;
 /**
  * @type TSubscribedTemplates
  * Represents the subscribed templates for dynamic updates.
  *
  * @property {string} originExpression - The expression to evaluate.
- * @property {(typeof TEMPLATE_AVALIABLE_SCOPES)[number][]} originScopeKeys - Origin scope of the updated template value
+ * @property {TTemplateAvaliableScopes[]} originScopeKeys - Origin scope of the updated template value
  * @property {string[]} originPropertyKeys - The properties of the origin fields.
  * @property {string[]} originFieldKeys - The keys of the origin fields.
  * @property {string} destinationKey - The key of the destination field.
@@ -27,7 +42,7 @@ import { TMutationEvents } from './event';
  */
 type TSubscribedTemplates = {
     originExpression: string;
-    originScopeKeys: (typeof TEMPLATE_AVALIABLE_SCOPES)[number][];
+    originScopeKeys: TTemplateAvaliableScopes[];
     originPropertyKeys: string[];
     originFieldKeys: string[];
     destinationKey: string;
@@ -38,13 +53,13 @@ type TSubscribedTemplates = {
  * @type TTemplateEvent
  * Represents the event occuring on templates that changes property values.
  *
- * @property {(typeof TEMPLATE_AVALIABLE_SCOPES)[number]} scope - template scope triggering the event.
+ * @property {TTemplateAvaliableScopes} scope - template scope triggering the event.
  * @property {string} key - field triggering the template refresh
  * @property {TMutationEvents} event - template event triggering the template refresh.
  */
 type TTemplateEvent = {
-    scope: (typeof TEMPLATE_AVALIABLE_SCOPES)[number];
+    scope: TTemplateAvaliableScopes;
     key?: string;
     event: TMutationEvents;
 };
-export { TSubscribedTemplates, TTemplateEvent };
+export { TSubscribedTemplates, TTemplateEvent, TTemplateAvaliableScopes, TTemplateAvaliableScopesEnum };

package/src/types/utility.d.ts

@@ -4,3 +4,6 @@ export type AllowOnly<T, K extends keyof T> = Pick<T, K> & {
 };
 export type OneOf<T, K = keyof T> = K extends keyof T ? AllowOnly<T, K> : never;
 export type TValidationHandler = Record<string, (value: unknown, validations: TValidationMethods) => boolean>;
+export type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};

package/src/validations/date.d.ts

@@ -56,7 +56,7 @@ export declare const betweenDates: (value: string, validations: TValidationMetho
  * console.log(result2); // true (date is outside the range)
  * ```
  */
-export declare const date: (value: string, validations: TValidationMethods) => boolean;
+export declare const date: (value: string | null, validations: TValidationMethods) => boolean;
 /**
  * @function validDate
  * Validates that a date string is a valid date according to the given format.

package/src/validations/list.d.ts

@@ -29,4 +29,4 @@ import { TValidationMethods } from '../types/schema';
  * console.log(isValid); // Output: true or false based on validation
  * ```
  */
-export declare const includes: (value: unknown, validations: TValidationMethods) => boolean;
+export declare const includes: (value: unknown, validations?: TValidationMethods | null) => boolean;

package/src/validations/logical.d.ts

@@ -46,7 +46,7 @@ export declare const required: (value: unknown, validations: TValidationMethods)
  * console.log(result2); // false
  * ```
  */
-export declare const bool: (_: unknown, validations: TValidationMethods) => boolean;
+export declare const bool: (_: unknown, validations: TValidationMethods | null) => boolean;
 /**
  * Validates that a value exists. Useful with iVars property.
  *

package/src/validations/string.d.ts

@@ -50,4 +50,4 @@ export declare const notEmpty: (value: unknown, validations: TValidationMethods)
  * console.log(result3); // false
  * ```
  */
-export declare const value: (value: unknown, validations: TValidationMethods) => boolean;
+export declare const value: (value: unknown, validations?: TValidationMethods) => boolean;