@bolttech/form-engine-core 1.0.1-beta.2 → 1.0.1

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/managers/formGroup.d.ts

@@ -7,16 +7,18 @@ import { TFormDataPayload, TFormGroupOnDataEventPayload, TFormGroupOnSubmitEvent
 /**
  * Represents a group that manages multiple forms.
  */
-declare class FormGroup {
+declare class FormGroup<ComponentElementType> {
     forms: Map<string, TFormCore>;
     config: Required<TSchemaFormConfig>;
     dataSubject$: Subject<TFormDataPayload>;
     formValidSubject$: Subject<TFormValidationPayload>;
     submitSubject$: Subject<TFormSubmitPayload<unknown>>;
+    mappers?: TMapper<ComponentElementType>[];
     /**
      * Creates an instance of FormGroup.
      */
     constructor(entry?: {
+        mappers?: TMapper<ComponentElementType>[];
         config?: TSchemaFormConfig;
     });
     /**
@@ -104,5 +106,5 @@ declare class FormGroup {
     }): import("rxjs").Subscription;
     destroy: () => void;
 }
-type TFormGroup = FormGroup;
+type TFormGroup<T> = FormGroup<T>;
 export { TFormGroup, FormGroup };

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/masks/string.d.ts

@@ -66,6 +66,8 @@ export declare const replaceAll: (value: string | number, masks: TMasks) => unkn
  *
  * const formattedValue = currency(config.value, config.masks);
  * console.log(formattedValue); // Output: '9.876,54 €'
+ *
+ * PS: To unCurrency this value, usage onlyFloatNumber formatter
  * ```
  */
 export declare const currency: (value: string | number, masks: TMasks) => 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.
@@ -83,15 +149,16 @@ type TFormValidationPayload = {
 type TFieldValidationPayload = {
     fieldTrigger: string;
 };
+type TFormDataValues<T> = {
+    formId: string;
+    formField: string;
+    values?: TFormValues<T>;
+};
 /**
  * @type TFormGroupOnDataEventPayload
  * Form Group onData event emitted payload on callback function parameter
  */
-type TFormGroupOnDataEventPayload<T> = Record<string, {
-    formId: string;
-    formField: string;
-    values?: TFormValues<T>;
-}>;
+type TFormGroupOnDataEventPayload<T> = Record<string, TFormDataValues<T>>;
 /**
  * @type TFormGroupOnValidEventPayload
  * Form Group onValid event emitted payload on callback function parameter
@@ -105,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, 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;