@bolttech/form-engine-core 1.0.0-beta.9 → 1.0.1-beta.0

package/package.json

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

package/src/constants/constants.d.ts

@@ -4,7 +4,7 @@ declare const TEMPLATE_REGEX_STRING_CONCATENATION_DETECTOR: RegExp;
 declare const TEMPLATE_REGEX_DELIMITATOR: RegExp;
 declare const TEMPLATE_REGEX_OPERATOR_SPLITTER: RegExp;
 declare const TEMPLATE_REGEX_OPERATOR_MATCHER: RegExp;
-declare const TEMPLATE_AVALIABLE_SCOPES: readonly ["fields", "iVars"];
+declare const TEMPLATE_AVALIABLE_SCOPES: readonly ["fields", "iVars", "form"];
 declare const ALLOWED_RESET_PROPS_MUTATIONS: ("api" | "apiSchema" | "props" | "validations" | "visibilityConditions" | "resetValues")[];
 declare const DEFAULT_LOG_VERBOSE = false;
 export { DEFAULT_API_DEBOUNCE_TIME, DEFAULT_STATE_REFRESH_TIME, DEFAULT_LOG_VERBOSE, TEMPLATE_REGEX_STRING_CONCATENATION_DETECTOR, TEMPLATE_REGEX_DELIMITATOR, TEMPLATE_REGEX_OPERATOR_SPLITTER, TEMPLATE_REGEX_OPERATOR_MATCHER, TEMPLATE_AVALIABLE_SCOPES, ALLOWED_RESET_PROPS_MUTATIONS, };

package/src/interfaces/schema.d.ts

@@ -15,6 +15,8 @@ import { TApiEvent, TFormatters, TMasks, TProps, TResetPathMethods, TResetValueM
  * @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
@@ -45,7 +47,9 @@ import { TApiEvent, TFormatters, TMasks, TProps, TResetPathMethods, TResetValueM
  *   api: { defaultConfig: { config: { method: 'POST', url: 'https://api.example.com/submit' }, events: [{ eventName: 'ON_FORM_SUBMIT' }] } },
  *   formatters: { capitalize: true },
  *   masks: { currency: { align: 'left', decimal: '.', precision: 2, prefix: '$', thousands: ',' } },
- *   children: []
+ *   children: [],
+ *   visibility: true,
+ *   persistValue: true,
  * };
  * ```
  */
@@ -63,6 +67,7 @@ interface IComponentSchema {
     masks?: TMasks;
     children?: IComponentSchema[];
     visibility?: boolean;
+    persistValue?: boolean;
 }
 interface IComponentSchemaAsFormField<T> extends IComponentSchema {
     mapper?: TMapper<T>;

package/src/managers/field.d.ts

@@ -1,8 +1,8 @@
-import { Observable, Subject, Subscription } from 'rxjs';
+import { Subject, Subscription } from 'rxjs';
 import { TApiConfig, TApiEvent, TApiResponse, TErrorMessages, TFormatters, TMasks, TResetPathMethods, TResetValueMethods, TSchemaFormConfig, TValidations, TVisibility } from '../types/schema';
 import { IComponentSchema, IComponentSchemaAsFormField } from '../interfaces/schema';
 import { IState } from '../interfaces/state';
-import { TEvents, TFieldEvent, TFormValidationPayload, TValueChangeEvent } from '../types/event';
+import { TEvents, TFieldEvent, TFieldValidationPayload, TFormDataPayload, TValueChangeEvent } from '../types/event';
 import { TMapper } from '../types/mapper';
 import { SafeSubject } from '../helpers/SafeSubject';
 import { TTemplateEvent } from '../types/template';
@@ -11,6 +11,7 @@ import { TFormValues } from '../types/form';
  * Represents a form field with observables for managing form state, validations, and API requests.
  */
 declare class FormField {
+    formIndex: string;
     name: string;
     nameToSubmit?: string;
     component: string;
@@ -21,7 +22,6 @@ declare class FormField {
     visibilityConditions?: TVisibility[];
     resetValues?: TResetValueMethods[];
     resetPropertyValues?: TResetPathMethods[];
-    errorMessages?: TErrorMessages;
     apiSchema?: TApiEvent;
     formatters?: TFormatters;
     masks?: TMasks;
@@ -44,19 +44,14 @@ declare class FormField {
     valueSubject$: SafeSubject<Record<string, unknown>>;
     valueSubscription$: Subscription;
     visibilitySubject$: SafeSubject<boolean>;
-    apiSubject$: SafeSubject<TApiResponse>;
     fieldEventSubject$: Subject<TFieldEvent>;
     apiEventQueueSubject$: SafeSubject<{
         event: TEvents;
     }>;
-    fieldState$: Observable<IState>;
     fieldStateSubscription$: Subscription;
     templateSubject$: Subject<TTemplateEvent>;
-    dataSubject$: Subject<{
-        key: string;
-        event: TEvents;
-    }>;
-    formValidNotification$: Subject<Pick<TFormValidationPayload, 'fieldTrigger'>>;
+    dataSubject$: Subject<TFormDataPayload>;
+    fieldValidNotification$: Subject<TFieldValidationPayload>;
     mountSubject$: Subject<{
         key: string;
         status: boolean;
@@ -76,6 +71,7 @@ declare class FormField {
     getFormValues: () => TFormValues<unknown>;
     valueChangeEvent: TValueChangeEvent;
     submitEvent: () => void;
+    persistValue?: boolean;
     /**
      * Creates an instance of FormField.
      *
@@ -94,7 +90,8 @@ declare class FormField {
      * @param {TMapper<unknown>} options.mapper, - component generic mapper containing render parameters for adapters
      * @param {() => TFormValues<unknown>} options.getFormValues, - form instance function that builds onData parameter payload from fields
      */
-    constructor({ schemaComponent, config, path, children, validateVisibility, resetValue, resetProperty, templateSubject$, fieldEventSubject$, dataSubject$, formValidNotification$, mountSubject$, mapper, getFormValues, submitEvent, visibility, }: {
+    constructor({ formIndex, schemaComponent, config, path, children, validateVisibility, resetValue, resetProperty, templateSubject$, fieldEventSubject$, dataSubject$, fieldValidNotification$, mountSubject$, mapper, getFormValues, submitEvent, visibility, persistValue, }: {
+        formIndex: string;
         schemaComponent: IComponentSchema;
         config?: TSchemaFormConfig;
         path?: string;
@@ -114,11 +111,8 @@ declare class FormField {
         submitEvent: () => void;
         templateSubject$: Subject<TTemplateEvent>;
         fieldEventSubject$: Subject<TFieldEvent>;
-        dataSubject$: Subject<{
-            key: string;
-            event: TEvents;
-        }>;
-        formValidNotification$: Subject<Pick<TFormValidationPayload, 'fieldTrigger'>>;
+        dataSubject$: Subject<TFormDataPayload>;
+        fieldValidNotification$: Subject<TFieldValidationPayload>;
         mountSubject$: Subject<{
             key: string;
             status: boolean;
@@ -126,6 +120,7 @@ declare class FormField {
         mapper: TMapper<unknown>;
         getFormValues: () => TFormValues<unknown>;
         visibility?: boolean;
+        persistValue?: boolean;
     });
     /**
      * method to initialize all recycled Subjects and initialize Observers on field instance creation or rerender
@@ -193,6 +188,14 @@ declare class FormField {
      * @returns {boolean} - The validity status of the form field.
      */
     get valid(): boolean;
+    /**
+     * triggers field valid notification to handle the form instance valid notification
+     *
+     * Note: since form unmount can occur before field unmount, this subject might already be closed by form instance
+     * quick workaround is to check if the subject is already closed before emitting
+     * if form instance onValid or template form.valid doesn't work properly, might be due to this workaround
+     */
+    triggerFieldValidNotification(): void;
     /**
      * Retrieves the error messages associated with the form field.
      *
@@ -218,7 +221,10 @@ declare class FormField {
      */
     set api(response: TApiResponse);
     /**
-     * Retrieves the mounted status of the field.
+     * notifies templates and event binded field configurations that a request starts it's processing
+     */
+    notifyApiRequest(): void;
+    /** Retrieves the mounted status of the field.
      *
      * @returns {boolean} - the mounted status of the field.
      */

package/src/managers/form.d.ts

@@ -3,7 +3,7 @@ import { Subject, Subscription } from 'rxjs';
 import { IComponentSchema, IComponentSchemaAsFormField, IFormSchema } from '../interfaces/schema';
 import { TSchemaFormConfig } from '../types/schema';
 import { TSubscribedTemplates, TTemplateEvent } from '../types/template';
-import { TEvents, TFieldEvent, TFormValidationPayload, TMutationEvents } from '../types/event';
+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';
@@ -11,22 +11,21 @@ import { TEMPLATE_AVALIABLE_SCOPES } from '../constants/constants';
  * Represents the core logic for managing a form, including field management, validation, and submission.
  */
 declare class FormCore {
+    index: string;
     schema?: IFormSchema;
     fields: Map<string, IFormField>;
     private _iVars;
     templateSubject$: Subject<TTemplateEvent>;
     templateSubscription$: Subscription;
-    submitSubject$: Subject<TFormValues<any>>;
+    submitSubject$: Subject<TFormSubmitPayload<unknown>>;
     mountSubject$: Subject<{
         key: string;
         status: boolean;
     }>;
     fieldEventSubject$: Subject<TFieldEvent>;
-    dataSubject$: Subject<{
-        key: string;
-        event: TEvents;
-    }>;
-    formValidNotification$: Subject<Pick<TFormValidationPayload, 'fieldTrigger'>>;
+    dataSubject$: Subject<TFormDataPayload>;
+    formValidSubject$: Subject<TFormValidationPayload>;
+    fieldValidNotification$: Subject<TFieldValidationPayload>;
     subscribedTemplates: TSubscribedTemplates[];
     action?: string;
     method?: string;
@@ -45,6 +44,7 @@ declare class FormCore {
         value: unknown;
     }>;
     queuedInitialValues: Map<string, unknown>;
+    _valid: boolean;
     /**
      * Creates an instance of FormCore.
      *
@@ -92,11 +92,12 @@ declare class FormCore {
      */
     set iVars(payload: Record<string, unknown>);
     /**
-     * Checks if the form is valid by validating all form fields.
+     * Validates all form fields and sets the form valid flag
      *
-     * @returns {boolean} True if the form is valid; otherwise, false.
      */
-    get isValid(): boolean;
+    validateForm(): boolean;
+    get valid(): boolean;
+    set valid(valid: boolean);
     /**
      * Subscribes to templates for dynamic updates.
      */
@@ -250,9 +251,10 @@ declare class FormCore {
      * @param fieldSchema
      * @param mapperElement
      */
-    addField({ fieldSchema, mapperElement, }: {
+    addField({ fieldSchema, mapperElement, path, }: {
         fieldSchema: IComponentSchema;
         mapperElement?: TMapper<unknown>;
+        path?: string;
     }): void;
     /**
      * function to be called from the adapter to remove a field when a field is removed from it

package/src/managers/formGroup.d.ts

@@ -1,14 +1,18 @@
-import { TFormValues } from '../types/form';
+import { Subject } from 'rxjs';
+import { TFormEntry, TFormValues } from '../types/form';
 import { TMapper } from '../types/mapper';
 import { TFormCore } from './form';
 import { TSchemaFormConfig } from '../types/schema';
-import { TFormGroupOnDataEventPayload, TFormGroupOnSubmitEventPayload, TFormGroupOnValidEventPayload } from '../types/event';
+import { TFormDataPayload, TFormGroupOnDataEventPayload, TFormGroupOnSubmitEventPayload, TFormGroupOnValidEventPayload, TFormSubmitPayload, TFormValidationPayload } from '../types/event';
 /**
  * Represents a group that manages multiple forms.
  */
 declare class FormGroup {
     forms: Map<string, TFormCore>;
     config: Required<TSchemaFormConfig>;
+    dataSubject$: Subject<TFormDataPayload>;
+    formValidSubject$: Subject<TFormValidationPayload>;
+    submitSubject$: Subject<TFormSubmitPayload<unknown>>;
     /**
      * Creates an instance of FormGroup.
      */
@@ -32,9 +36,9 @@ declare class FormGroup {
      * @param {string} options.key - The key associated with the form instance.
      * @param {TFormCore} options.formInstance - The instance of the form to add.
      */
-    addForm({ key, formInstance }: {
+    addForm({ key, params }: {
         key: string;
-        formInstance: TFormCore;
+        params: TFormEntry;
     }): void;
     /**
      * Retrieves a form instance from the form group.

package/src/types/event.d.ts

@@ -9,7 +9,7 @@ import { TFormValues } from './form';
  * const event: TEvents = 'ON_FIELD_CHANGE';
  * ```
  */
-type TEvents = 'ON_FIELD_MOUNT' | '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_RESPONSE';
+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 TMutationEvents
  * Represents the different types of events that can occur internally that triggers templating.
@@ -19,7 +19,7 @@ type TEvents = 'ON_FIELD_MOUNT' | 'ON_FIELD_CHANGE' | 'ON_FIELD_BLUR' | 'ON_FIEL
  * const event: TMutationEvents = 'ON_VALUE';
  * ```
  */
-type TMutationEvents = 'ON_VALUE' | 'ON_PROPS' | 'ON_VISIBILITY' | 'ON_API' | 'ON_IVARS' | 'ON_FIELDS' | 'ON_RESET';
+type TMutationEvents = 'ON_VALUE' | 'ON_PROPS' | 'ON_VISIBILITY' | 'ON_API_REQUEST' | 'ON_API_RESPONSE' | 'ON_IVARS' | 'ON_FIELDS' | 'ON_RESET' | 'ON_FORM';
 declare enum TMutationEnum {
     ON_VALUE = "value",
     ON_PROPS = "props",
@@ -51,14 +51,38 @@ type TFieldEvent = {
     fieldName: string;
     fieldInstance?: IFormField;
 };
+/**
+ * @type TFormDataPayload
+ * Event emitted to formGroup instance to capture onData form events
+ */
+type TFormDataPayload = {
+    formIndex: string;
+    fieldIndex: string;
+    event: TEvents;
+};
+/**
+ * @type TFormSubmitPayload
+ * Event emitted to formGroup instance to capture onSubmit form events
+ */
+type TFormSubmitPayload<T> = {
+    formIndex: string;
+    values: TFormValues<T>;
+};
 /**
  * @type TFormValidationPayload
  * Form onValid event emmited payload on callback function parameter
  */
 type TFormValidationPayload = {
-    fieldTrigger: string;
+    formIndex: string;
     valid: boolean;
 };
+/**
+ * @type TFieldValidationPayload
+ * field event emmited payload on field validation
+ */
+type TFieldValidationPayload = {
+    fieldTrigger: string;
+};
 /**
  * @type TFormGroupOnDataEventPayload
  * Form Group onData event emitted payload on callback function parameter
@@ -81,4 +105,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, TFormGroupOnDataEventPayload, TFormGroupOnValidEventPayload, TFormGroupOnSubmitEventPayload, TFormValidationPayload, };
+export { TEvents, TMutationEvents, TMutationEnum, TValueChangeEvent, TFieldEvent, TFormDataPayload, TFormSubmitPayload, TFormGroupOnDataEventPayload, TFormGroupOnValidEventPayload, TFormGroupOnSubmitEventPayload, TFormValidationPayload, TFieldValidationPayload, };

package/src/types/form.d.ts

@@ -1,5 +1,7 @@
+import { Subject } from 'rxjs';
 import { IFormSchema } from '../interfaces/schema';
 import { TMapper } from './mapper';
+import { TFormDataPayload, TFormSubmitPayload, TFormValidationPayload } from './event';
 /**
  * @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.
@@ -30,6 +32,9 @@ type TFormValues<T> = {
  * @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
@@ -43,5 +48,8 @@ type TFormValues<T> = {
 type TFormEntry = Omit<IFormSchema, 'components'> & {
     schema?: IFormSchema;
     mappers?: TMapper<unknown>[];
+    dataSubject$?: Subject<TFormDataPayload>;
+    formValidSubject$?: Subject<TFormValidationPayload>;
+    submitSubject$?: Subject<TFormSubmitPayload<unknown>>;
 };
 export { TFormValues, TFormEntry };

package/src/types/schema.d.ts

@@ -667,7 +667,7 @@ type TResetValueMethods = Omit<TVisibility, 'showOnlyIfTrue' | 'validations'> &
     validations?: TSchemaValidation;
 };
 type TResetPathMethods = {
-    property: typeof ALLOWED_RESET_PROPS_MUTATIONS[number];
+    property: (typeof ALLOWED_RESET_PROPS_MUTATIONS)[number];
     path: string;
     field: string;
     resettledValue: unknown;
@@ -816,6 +816,10 @@ type TApiResponsePayload = {
 type TApiResponse = {
     default: TApiResponsePayload;
     named?: Record<string, TApiResponsePayload>;
+    apiState: {
+        loading: boolean;
+        lastEvent?: TEvents;
+    };
 };
 /**
  * Represents the schema config structure