@bolttech/form-engine-core 1.0.0-beta.2 → 1.0.0-beta.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bolttech/form-engine-core",
-  "version": "1.0.0-beta.2",
+  "version": "1.0.0-beta.20",
   "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

@@ -62,6 +62,7 @@ interface IComponentSchema {
     formatters?: TFormatters;
     masks?: TMasks;
     children?: IComponentSchema[];
+    visibility?: 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,18 @@ 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<{
+    dataSubject$: Subject<TFormDataPayload>;
+    fieldValidNotification$: Subject<TFieldValidationPayload>;
+    mountSubject$: Subject<{
         key: string;
-        event: TEvents;
+        status: boolean;
     }>;
-    formValidNotification$: Subject<Pick<TFormValidationPayload, 'fieldTrigger'>>;
     validateVisibility: (payload: {
         event: TEvents;
         key: string;
@@ -90,7 +89,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$, mapper, getFormValues, submitEvent, }: {
+    constructor({ formIndex, schemaComponent, config, path, children, validateVisibility, resetValue, resetProperty, templateSubject$, fieldEventSubject$, dataSubject$, fieldValidNotification$, mountSubject$, mapper, getFormValues, submitEvent, visibility, }: {
+        formIndex: string;
         schemaComponent: IComponentSchema;
         config?: TSchemaFormConfig;
         path?: string;
@@ -110,16 +110,20 @@ declare class FormField {
         submitEvent: () => void;
         templateSubject$: Subject<TTemplateEvent>;
         fieldEventSubject$: Subject<TFieldEvent>;
-        dataSubject$: Subject<{
+        dataSubject$: Subject<TFormDataPayload>;
+        fieldValidNotification$: Subject<TFieldValidationPayload>;
+        mountSubject$: Subject<{
             key: string;
-            event: TEvents;
+            status: boolean;
         }>;
-        formValidNotification$: Subject<Pick<TFormValidationPayload, 'fieldTrigger'>>;
         mapper: TMapper<unknown>;
         getFormValues: () => TFormValues<unknown>;
+        visibility?: boolean;
     });
     /**
      * method to initialize all recycled Subjects and initialize Observers on field instance creation or rerender
+     * due to some visibility conditions unmounts the field from the adapter if they are children of it and avoid
+     * emissions to unsubscribed fields
      */
     initializeObservers(): void;
     /**
@@ -134,6 +138,13 @@ declare class FormField {
      * @param {Record<string, unknown>} props - The new properties to be set.
      */
     set props(props: Record<string, unknown>);
+    /**
+     * Static function to remove templates form the component props that will be shown when
+     * the field mounts and the template routine executes, to be used on the adapter
+     *
+     * @param {unknown} props - the properties from the adapter components.
+     */
+    static filterProps(props: unknown): unknown;
     /**
      * Retrieves the current state value of the form field.
      *
@@ -175,6 +186,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.
      *
@@ -199,6 +218,22 @@ declare class FormField {
      * @param {TApiResponse} response - The new API response data to be set.
      */
     set api(response: TApiResponse);
+    /**
+     * 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.
+     */
+    get mounted(): boolean;
+    /**
+     * sets the mountedStatus and notifies the form that the field was mounted on the adapter
+     * and it's ready to be handled by the form instance
+     *
+     * @param {boolean} mountedStatus - the mounted status to be set from the mountField function.
+     */
+    set mounted(mountedStatus: boolean);
     /**
      * Mounts the form field by initializing necessary subjects and combining their streams.
      *

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,19 +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>>;
-    mountSubject$: Subject<TFormValues<any>>;
-    fieldEventSubject$: Subject<TFieldEvent>;
-    dataSubject$: Subject<{
+    submitSubject$: Subject<TFormSubmitPayload<unknown>>;
+    mountSubject$: Subject<{
         key: string;
-        event: TEvents;
+        status: boolean;
     }>;
-    formValidNotification$: Subject<Pick<TFormValidationPayload, 'fieldTrigger'>>;
+    fieldEventSubject$: Subject<TFieldEvent>;
+    dataSubject$: Subject<TFormDataPayload>;
+    formValidSubject$: Subject<TFormValidationPayload>;
+    fieldValidNotification$: Subject<TFieldValidationPayload>;
     subscribedTemplates: TSubscribedTemplates[];
     action?: string;
     method?: string;
@@ -42,6 +44,7 @@ declare class FormCore {
         value: unknown;
     }>;
     queuedInitialValues: Map<string, unknown>;
+    _valid: boolean;
     /**
      * Creates an instance of FormCore.
      *
@@ -54,7 +57,28 @@ declare class FormCore {
      * @param {((payload: {field: string;data: TFormValues;}) => void) | undefined} [entry.onData] - A callback function to handle data emission.
      */
     constructor(entry: TFormEntry & Omit<IFormSchema, 'components'>);
-    setInitialValues(payload: Record<string, unknown> | undefined): void;
+    /**
+     * mock function to simulate form mount onto the adapter
+     */
+    generateFields(): void;
+    /**
+     * 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
+     * field routines
+     *
+     * @param { string } entry.key field unique identifier
+     * @param { boolean } entry.status mount status notified from field
+     */
+    mountActions({ key, status }: {
+        key: string;
+        status: boolean;
+    }): void;
+    /**
+     * initialValues setter to handle field values set externally from the adapter
+     *
+     * @param { Record<string, unknown> | undefined } payload initialValues to set onto fields
+     */
+    set initialValues(payload: Record<string, unknown> | undefined);
     /**
      * Retrieves the internal variables (iVars) of the form.
      *
@@ -68,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.
      */
@@ -230,6 +255,11 @@ declare class FormCore {
         fieldSchema: IComponentSchema;
         mapperElement?: TMapper<unknown>;
     }): void;
+    /**
+     * function to be called from the adapter to remove a field when a field is removed from it
+     *
+     * @param {{ key: string }} entry.key
+     */
     removeField({ key }: {
         key: string;
     }): void;
@@ -266,9 +296,21 @@ declare class FormCore {
      * @returns {TFormValues} The current form values.
      */
     getFormValues<T>(): TFormValues<T>;
+    /**
+     * function to be called to events sent from the adapter
+     *
+     * @param {{callback: (payload: TFieldEvent) => void}} entry.callback callback function from the adapter
+     * @returns
+     */
     subscribeFieldEvent({ callback, }: {
         callback: (payload: TFieldEvent) => void;
     }): Subscription;
+    /**
+     * to be called from the adapter when the form mounts
+     *
+     * @param {(payload: TFormValues<T>) => void} callback
+     * @returns Subscription
+     */
     subscribeOnMount<T>(callback: (payload: TFormValues<T>) => void): Subscription;
     /**
      *
@@ -278,8 +320,14 @@ declare class FormCore {
         field: string;
         data: TFormValues<T>;
     }) => void): Subscription;
+    /**
+     * method to register a callback function to be called when the form is valid
+     *
+     * @param {(payload: TFormValues<T>) => void} callback callback function to call when the submit action occurs
+     */
     subscribeOnSubmit<T>(callback: (payload: TFormValues<T>) => void): Subscription;
     /**
+     * method to check whenever the validity status of the form changes, only emits on status change
      *
      * @param {(payload: TFormValidationPayload) => void} callback callback function to call onValid
      */
@@ -287,11 +335,10 @@ declare class FormCore {
     /**
      * Submits the form by triggering form field events and invoking the onSubmit callback.
      */
-    mounted<T>(): void;
+    submit<T>(): void;
     /**
-     * Submits the form by triggering form field events and invoking the onSubmit callback.
+     * recycles all the Suscriptions, to be called from the adapter when the form leaves the page
      */
-    submit<T>(): void;
     destroy(): void;
 }
 type TFormCore = FormCore;

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.
@@ -19,6 +21,7 @@ import { TMapper } from './mapper';
  */
 type TFormValues<T> = {
     values: T;
+    metadata: unknown;
     erroredFields: string[];
     isValid: boolean;
 };
@@ -29,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
@@ -42,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