@bolttech/form-engine-core 0.0.1-beta.9 → 0.0.2-beta.1

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@bolttech/form-engine-core",
-  "version": "0.0.1-beta.9",
+  "version": "0.0.2-beta.01",
   "module": "./index.esm.js",
   "type": "module",
   "main": "./index.esm.js",
   "dependencies": {
     "@gaignoux/currency": "1.1.0",
-    "credit-card-type": "10.0.0",
+    "credit-card-type": "10.0.1",
     "lodash": "4.17.21",
     "rxjs": "7.8.1"
   },

package/src/constants/constants.d.ts

@@ -1,3 +1,8 @@
 declare const DEFAULT_API_DEBOUNCE_TIME = 1000;
 declare const DEFAULT_STATE_REFRESH_TIME = 100;
-export { DEFAULT_API_DEBOUNCE_TIME, DEFAULT_STATE_REFRESH_TIME };
+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"];
+export { DEFAULT_API_DEBOUNCE_TIME, DEFAULT_STATE_REFRESH_TIME, TEMPLATE_REGEX_STRING_CONCATENATION_DETECTOR, TEMPLATE_REGEX_DELIMITATOR, TEMPLATE_REGEX_OPERATOR_SPLITTER, TEMPLATE_REGEX_OPERATOR_MATCHER, TEMPLATE_AVALIABLE_SCOPES, };

package/src/helpers/SafeSubject.d.ts

@@ -0,0 +1,11 @@
+import { Subject } from 'rxjs';
+/**
+ * Custom RXJS Subject to gracefully handle errors on unsubscribed Subjects
+ * that were unmounted due to adapter external handling such as visibility
+ */
+declare class SafeSubject<T> extends Subject<T> {
+    private isMounted;
+    constructor(isMounted: () => boolean);
+    next(value: T): void;
+}
+export { SafeSubject };

package/src/helpers/helpers.d.ts

@@ -1,4 +1,5 @@
 /// <reference types="node" />
+import { TEMPLATE_AVALIABLE_SCOPES } from '../constants/constants';
 import { TSubscribedTemplates } from '../types/template';
 import { OutgoingHttpHeaders } from 'http2';
 /**
@@ -32,6 +33,7 @@ declare function makeRequest(method: string, url: string, headers?: OutgoingHttp
  * ```
  */
 declare function extractFieldKeys(expression: string): {
+    originScopeKeys: (typeof TEMPLATE_AVALIABLE_SCOPES)[number][];
     originFieldKeys: string[];
     originPropertyKeys: string[];
 };
@@ -60,27 +62,5 @@ declare function extractFieldKeys(expression: string): {
  * // expressions will contain an array of objects with origin expressions, field keys, and destination paths.
  * ```
  */
-declare function traverseObject(obj: any, path?: string): TSubscribedTemplates[];
-/**
- * Encapsulates in a given object, at a given path the provided value
- *
- * @example
- * ORIGINAL object
- *
- * encapsulateIn({maintain: 'spread_me'}, 'a.b.c','test')
- *
- * RESULT
- *
- * {
- *  maintain: 'spread_me',
- *    c: 'test
- *  }
- * }
- *
- * @param origin - The original object where the new value will be appended
- * @param path - The path at which the new value will be placed
- * @param value - The new value
- * @returns One new object with the new value at the provided path merged with the given object
- */
-declare const encapsulateIn: (origin: Record<string, unknown>, path: string, value: unknown) => Record<string, unknown>;
-export { makeRequest, traverseObject, extractFieldKeys, encapsulateIn };
+declare function traverseObject(element: any, path?: string): TSubscribedTemplates[];
+export { makeRequest, traverseObject, extractFieldKeys };

package/src/helpers/validation.d.ts

@@ -0,0 +1,27 @@
+import { TSchemaValidation, TValidationMethods } from '../types/schema';
+import { TValidationHandler } from '../types/utility';
+/**
+ * @internal
+ * Handles the validation of a given value based on specified validation methods and rules.
+ *
+ * @param {string | number | boolean | unknown} value - The value to be validated.
+ * @param {TSchemaValidation} validations - The schema validations to be applied.
+ * @param {TValidationHandler} methods - The validation handler methods.
+ * @param {keyof TValidationMethods} key - The specific key of the validation method to be used.
+ * @returns {boolean} - Returns true if the value passes the validation, otherwise false.
+ *
+ * @example
+ * const value = 'example@example.com';
+ * const validations = {
+ *   required: true,
+ *   customName: { email: true }
+ * };
+ * const methods = {
+ *   email: (value) => /\S+@\S+\.\S+/.test(value)
+ * };
+ * const key = 'required';
+ *
+ * const isValid = handleValidation(value, validations, methods, key);
+ * console.log(isValid); // Output: true
+ */
+export default function handleValidation(value: string | number | boolean | unknown, validations: TSchemaValidation, methods: TValidationHandler, key: keyof TValidationMethods): boolean;

package/src/interfaces/schema.d.ts

@@ -1,4 +1,5 @@
-import { TApiEvent, TErrorMessages, TEvent, TFormatters, TMasks, TProps, TResetValueMethods, TSchemaFormConfig, TValidationMethods, TVisibility } from '../types/schema';
+import { TMapper } from '../types/mapper';
+import { TApiEvent, TFormatters, TMasks, TProps, TResetValueMethods, TSchemaFormConfig, TValidations, TVisibility } from '../types/schema';
 /**
  * @interface IComponentSchema
  * Represents the schema for a component within a form.
@@ -7,10 +8,9 @@ import { TApiEvent, TErrorMessages, TEvent, TFormatters, TMasks, TProps, TResetV
  * @property {TProps} props - The properties of the component.
  * @property {string} name - The name of the component.
  * @property {string} nameToSubmit - The name of the field when submit values (optional).
- * @property {TEvent<TValidationMethods>} [validations] - The validation methods for the component.
+ * @property {TValidations} [validations] - The validation methods for the component.
  * @property {TVisibility[]} [visibilityConditions] - The visibility conditions for the component.
  * @property {TResetValueMethods[]} [resetValues] - The reset value methods for the component.
- * @property {TErrorMessages} [errorMessages] - The error messages for the component.
  * @property {TApiEvent} [api] - The API configuration for the component.
  * @property {TFormatters} [formatters] - The formatters for the component.
  * @property {TMasks} [masks] - The masks for the component.
@@ -23,10 +23,25 @@ import { TApiEvent, TErrorMessages, TEvent, TFormatters, TMasks, TProps, TResetV
  *   props: { type: 'text', placeholder: 'Enter your name' },
  *   name: 'name',
  *   nameToSubmit: 'applicant.firstName',
- *   validations: { config: { required: true }, events: [{ eventName: 'ON_FIELD_BLUR' }] },
+ *   validations: {
+ *     methods: {
+ *       required: true,
+ *       regex: '^([0-9]+)*$',
+ *       max: 5,
+ *     },
+ *     eventMessages: {
+ *       ON_FIELD_MOUNT: ['required'],
+ *       ON_FIELD_CHANGE: ['regex', 'required'],
+ *       ON_FIELD_BLUR: ['max', 'required'],
+ *     },
+ *     messages: {
+ *       default: 'This field is required',
+ *       regex: 'Only numbers are available.',
+ *       max: 'Max of 5',
+ *     },
+ *   },
  *   visibilityConditions: [{ conditions: { field: 'age', value: 18 } }],
  *   resetValues: [{ field: 'age', resetTo: '' }],
- *   errorMessages: { required: 'This field is required.' },
  *   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: ',' } },
@@ -39,15 +54,19 @@ interface IComponentSchema {
     props?: TProps;
     name: string;
     nameToSubmit?: string;
-    validations?: TEvent<TValidationMethods>;
+    validations?: TValidations;
     api?: TApiEvent;
     visibilityConditions?: TVisibility[];
     resetValues?: TResetValueMethods[];
-    errorMessages?: TErrorMessages;
     formatters?: TFormatters;
     masks?: TMasks;
     children?: IComponentSchema[];
 }
+interface IComponentSchemaAsFormField<T> extends IComponentSchema {
+    mapper?: TMapper<T>;
+    order?: number;
+    children?: IComponentSchemaAsFormField<T>[];
+}
 /**
  * @interface IFormSchema
  * Represents the schema for a form.
@@ -83,4 +102,4 @@ interface IFormSchema {
     iVars?: Record<string, unknown>;
     components?: IComponentSchema[];
 }
-export { IFormSchema, IComponentSchema };
+export { IFormSchema, IComponentSchema, IComponentSchemaAsFormField };

package/src/managers/field.d.ts

@@ -1,9 +1,11 @@
 import { Observable, Subject, Subscription } from 'rxjs';
-import { TApiConfig, TApiEvent, TApiResponse, TErrorMessages, TEvent, TFormatters, TMasks, TResetValueMethods, TSchemaFormConfig, TValidationMethods, TVisibility } from '../types/schema';
-import { IComponentSchema } from '../interfaces/schema';
+import { TApiConfig, TApiEvent, TApiResponse, TErrorMessages, TFormatters, TMasks, TResetValueMethods, TSchemaFormConfig, TValidations, TVisibility } from '../types/schema';
+import { IComponentSchema, IComponentSchemaAsFormField } from '../interfaces/schema';
 import { IState } from '../interfaces/state';
-import { TEvents, TFieldEvent, TMutationEvents, TValueChangeEvent } from '../types/event';
+import { TEvents, TFieldEvent, TValueChangeEvent } from '../types/event';
 import { TMapper } from '../types/mapper';
+import { SafeSubject } from '../helpers/SafeSubject';
+import { TTemplateEvent } from '../types/template';
 /**
  * Represents a form field with observables for managing form state, validations, and API requests.
  */
@@ -13,8 +15,8 @@ declare class FormField {
     component: string;
     path?: string;
     children?: string[];
-    originalSchema: IComponentSchema;
-    validations?: TEvent<TValidationMethods>;
+    originalSchema: IComponentSchemaAsFormField<unknown>;
+    validations?: TValidations;
     visibilityConditions?: TVisibility[];
     resetValues?: TResetValueMethods[];
     errorMessages?: TErrorMessages;
@@ -35,21 +37,20 @@ declare class FormField {
     private _errors;
     private _api;
     private _valid;
-    propsSubject$: Subject<Record<string, unknown>>;
-    errorSubject$: Subject<Record<string, unknown>>;
-    valueSubject$: Subject<Record<string, unknown>>;
-    visibilitySubject$: Subject<boolean>;
-    apiSubject$: Subject<TApiResponse>;
+    private _mounted;
+    propsSubject$: SafeSubject<Record<string, unknown>>;
+    errorSubject$: SafeSubject<Record<string, unknown>>;
+    valueSubject$: SafeSubject<Record<string, unknown>>;
+    valueSubscription$: Subscription;
+    visibilitySubject$: SafeSubject<boolean>;
+    apiSubject$: SafeSubject<TApiResponse>;
     fieldEventSubject$: Subject<TFieldEvent>;
-    apiEventQueueSubject$: Subject<{
+    apiEventQueueSubject$: SafeSubject<{
         event: TEvents;
     }>;
     fieldState$: Observable<IState>;
     fieldStateSubscription$: Subscription;
-    templateSubject$: Subject<{
-        key: string;
-        event: TMutationEvents;
-    }>;
+    templateSubject$: Subject<TTemplateEvent>;
     dataSubject$: Subject<{
         key: string;
         event: TEvents;
@@ -90,10 +91,7 @@ declare class FormField {
             key: string;
         }) => void;
         initialValue?: unknown;
-        templateSubject$: Subject<{
-            key: string;
-            event: TMutationEvents;
-        }>;
+        templateSubject$: Subject<TTemplateEvent>;
         fieldEventSubject$: Subject<TFieldEvent>;
         dataSubject$: Subject<{
             key: string;
@@ -219,10 +217,6 @@ declare class FormField {
     setFieldValidity({ event }: {
         event: TEvents;
     }): void;
-    /**
-     * WIP expensive function to get updated field validity on each event
-     */
-    updateValidityFlag(): void;
     /**
      * Formats the field value using the specified formatters, if available.
      *

package/src/managers/form.d.ts

@@ -1,11 +1,12 @@
 import { IFormField } from './field';
 import { Subject, Subscription } from 'rxjs';
-import { IComponentSchema, IFormSchema } from '../interfaces/schema';
+import { IComponentSchema, IComponentSchemaAsFormField, IFormSchema } from '../interfaces/schema';
 import { TSchemaFormConfig } from '../types/schema';
-import { TSubscribedTemplates } from '../types/template';
+import { TSubscribedTemplates, TTemplateEvent } from '../types/template';
 import { TEvents, TFieldEvent, 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.
  */
@@ -14,23 +15,20 @@ declare class FormCore {
     fields: Map<string, IFormField>;
     initialValues?: Record<string, unknown>;
     private _iVars;
-    templateSubject$: Subject<{
-        key: string;
-        event: TMutationEvents;
-    }>;
-    submitSubject$: Subject<TFormValues<Record<string, unknown>>>;
+    templateSubject$: Subject<TTemplateEvent>;
+    templateSubscription$: Subscription;
+    submitSubject$: Subject<TFormValues<any>>;
+    mountSubject$: Subject<TFormValues<any>>;
     fieldEventSubject$: Subject<TFieldEvent>;
     dataSubject$: Subject<{
         key: string;
         event: TEvents;
     }>;
-    dataCallbackSubscription$: Subscription;
     subscribedTemplates: TSubscribedTemplates[];
     action?: string;
     method?: string;
     config: Required<TSchemaFormConfig>;
-    mappers?: TMapper<unknown>[];
-    onSubmit?: (data: TFormValues<Record<string, unknown>>) => void;
+    mappers: Map<string, TMapper<unknown>>;
     /**
      * Creates an instance of FormCore.
      *
@@ -40,7 +38,6 @@ declare class FormCore {
      * @param {string} [entry.action] - The action attribute of the form.
      * @param {string} [entry.method] - The method attribute of the form.
      * @param {IFormSchema.iVars} [entry.iVars] - The internal variables of the form.
-     * @param {(data: TFormValues) => void} [entry.onSubmit] - A callback function to handle form submission.
      * @param {((payload: {field: string;data: TFormValues;}) => void) | undefined} [entry.onData] - A callback function to handle data emission.
      */
     constructor(entry: TFormEntry & Omit<IFormSchema, 'components'>);
@@ -66,14 +63,6 @@ declare class FormCore {
      * Subscribes to templates for dynamic updates.
      */
     subscribeTemplates(): void;
-    /**
-     *
-     * @param {(payload: { field: string; data: TFormValues }) => void} callback callback function to call on data
-     */
-    subscribeData(callback: (payload: {
-        field: string;
-        data: TFormValues<Record<string, unknown>>;
-    }) => void): void;
     /**
      * Gets the value of a property from a field.
      *
@@ -83,7 +72,8 @@ declare class FormCore {
      * @param {string[]} options.path - The path to the property if it's nested.
      * @returns {unknown | undefined} The value of the property, or undefined if the field doesn't exist.
      */
-    getValue({ key, property, path, }: {
+    getValue({ scope, key, property, path, }: {
+        scope: (typeof TEMPLATE_AVALIABLE_SCOPES)[number];
         key: string;
         property: string;
         path: string[];
@@ -103,7 +93,7 @@ declare class FormCore {
         key: string;
         property: string;
         path: string[];
-        originKey: string;
+        originKey?: string;
         value: unknown;
         event: TMutationEvents;
     }): void;
@@ -113,7 +103,7 @@ declare class FormCore {
      * @param {string} expression - The expression containing parameters.
      * @returns {string[]} An array of extracted parameters.
      */
-    extractParams(expression: string): string[];
+    extractParams(expression: string): unknown[];
     /**
      * Replaces expressions marked by ${...} in the expression string with the provided values.
      *
@@ -121,7 +111,7 @@ declare class FormCore {
      * @param {string[]} values - The values to be inserted into the marked expressions.
      * @returns {string} The expression string with the replacements made.
      */
-    replaceExpression(expression: string, values: string[]): string;
+    replaceExpression(expression: string, values: unknown[]): string;
     /**
      * Checks if an expression string contains string concatenation within a marked expression.
      *
@@ -136,10 +126,7 @@ declare class FormCore {
      * @param {string} options.key - The key of the field triggering the update.
      * @param {TMutationEvents} options.event - Internal event descriptor to handle templating.
      */
-    refreshTemplates({ key, event }: {
-        key: string;
-        event: TMutationEvents;
-    }): void;
+    refreshTemplates({ key, event }: TTemplateEvent): void;
     /**
      * Validates and collects the names of form fields in the provided schema structure.
      *
@@ -150,6 +137,15 @@ declare class FormCore {
      * @private
      */
     private static checkIndexes;
+    /**
+     * @internal
+     * Update field visibility accordingly.
+     *
+     * @param {string} field - Field name to be updated.
+     * @param {boolean} hasError - Condition to be used as visibility.
+     * @param {boolean|undefined} showOnlyIfTrue - Flag to be considered when update field visibility. If it's true, then considered error, if it's false, always considered the opposite.
+     */
+    private setFieldVisibility;
     /**
      * Validates visibility conditions for a given event and updates field visibility accordingly.
      *
@@ -161,6 +157,14 @@ declare class FormCore {
         event: TEvents;
         key: string;
     }): void;
+    /**
+     * @internal
+     * Update field value and emit change and cleared event.
+     *
+     * @param {string} key - Field name to be updated.
+     * @param {unknown} value - Value to be inserted into field.
+     */
+    private setResetFieldValue;
     /**
      * Resets field values based on reset conditions defined in the schema.
      *
@@ -176,6 +180,7 @@ declare class FormCore {
      * Adds a field onto the form instance regardless there is a schema or not
      *
      * @param fieldSchema
+     * @param mapperElement
      */
     addField({ fieldSchema, mapperElement, }: {
         fieldSchema: IComponentSchema;
@@ -190,13 +195,13 @@ declare class FormCore {
      * @param {IComponentSchema[]} [struct] - The schema structure to serialize.
      * @param {string} [path] - The path of the parent component.
      */
-    serializeStructure(struct?: IComponentSchema[], path?: string): void;
+    serializeStructure(struct?: IComponentSchemaAsFormField<unknown>[], path?: string): void;
     /**
      * Refreshes form fields based on changes in the schema structure.
      *
      * @param {IComponentSchema[]} struct - The updated schema structure.
      */
-    refreshFields(struct: IComponentSchema[]): void;
+    refreshFields(struct: IComponentSchemaAsFormField<unknown>[]): void;
     /**
      * Gets a form field by its key.
      *
@@ -216,14 +221,28 @@ declare class FormCore {
      *
      * @returns {TFormValues} The current form values.
      */
-    getFormValues(): TFormValues<Record<string, unknown>>;
+    getFormValues<T>(): TFormValues<T>;
     subscribeFieldEvent({ callback, }: {
         callback: (payload: TFieldEvent) => void;
     }): Subscription;
+    subscribeOnMount<T>(callback: (payload: TFormValues<T>) => void): Subscription;
+    /**
+     *
+     * @param {(payload: { field: string; data: TFormValues }) => void} callback callback function to call on data
+     */
+    subscribeData<T>(callback: (payload: {
+        field: string;
+        data: TFormValues<T>;
+    }) => void): Subscription;
+    subscribeOnSubmit<T>(callback: (payload: TFormValues<T>) => void): Subscription;
+    /**
+     * Submits the form by triggering form field events and invoking the onSubmit callback.
+     */
+    mounted<T>(): void;
     /**
      * Submits the form by triggering form field events and invoking the onSubmit callback.
      */
-    submit(): void;
+    submit<T>(): void;
     destroy(): void;
 }
 type TFormCore = FormCore;

package/src/managers/formGroup.d.ts

@@ -79,7 +79,15 @@ declare class FormGroup {
      * @param {string[]} indexes form indexes to be submitted
      * @returns
      */
-    submitMultipleFormsByIndex<T>(indexes: string[]): TFormValues<T>;
+    submitMultipleFormsByIndex<T>(indexes: string[], callback?: (payload: TFormValues<T>) => void): void;
+    onDataSubscription<T>({ ids, callback, }: {
+        ids: string[];
+        callback: (payload: Record<string, {
+            formId: string;
+            formField: string;
+            values?: TFormValues<T>;
+        }>) => void;
+    }): import("rxjs").Subscription;
 }
 type TFormGroup = FormGroup;
 export { TFormGroup, FormGroup };

package/src/types/event.d.ts

@@ -8,7 +8,7 @@ import { IFormField } from '../managers';
  * 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_FORM_SUBMIT' | 'ON_API_FIELD_RESPONSE';
+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_FORM_MOUNT' | 'ON_API_FIELD_RESPONSE';
 /**
  * @type TMutationEvents
  * Represents the different types of events that can occur internally that triggers templating.
@@ -46,4 +46,4 @@ type TFieldEvent = {
     fieldName: string;
     fieldInstance?: IFormField;
 };
-export { TEvents, TMutationEvents, TMutationEnum, TValueChangeEvent, TFieldEvent };
+export { TEvents, TMutationEvents, TMutationEnum, TValueChangeEvent, TFieldEvent, };

package/src/types/form.d.ts

@@ -41,11 +41,6 @@ type TFormValues<T> = {
  */
 type TFormEntry = Omit<IFormSchema, 'components'> & {
     schema?: IFormSchema;
-    onSubmit?: <T>(data: TFormValues<T>) => void;
-    onData?: <T>(payload: {
-        field: string;
-        data: TFormValues<T>;
-    }) => void;
     mappers?: TMapper<unknown>[];
 };
 export { TFormValues, TFormEntry };