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

package/package.json

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

@@ -0,0 +1,6 @@
+declare const DEFAULT_API_DEBOUNCE_TIME = 1000;
+declare const DEFAULT_STATE_REFRESH_TIME = 100;
+declare const TEMPLATE_REGEX_DELIMITATOR: RegExp;
+declare const TEMPLATE_REGEX_OPERATOR_SPLITTER: RegExp;
+declare const TEMPLATE_REGEX_OPERATOR_MATCHER: RegExp;
+export { DEFAULT_API_DEBOUNCE_TIME, DEFAULT_STATE_REFRESH_TIME, TEMPLATE_REGEX_DELIMITATOR, TEMPLATE_REGEX_OPERATOR_SPLITTER, TEMPLATE_REGEX_OPERATOR_MATCHER };

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/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.
@@ -6,10 +7,10 @@ import { TApiEvent, TErrorMessages, TEvent, TFormatters, TMasks, TProps, TResetV
  * @property {string} component - The type of component (e.g., 'input', 'button').
  * @property {TProps} props - The properties of the component.
  * @property {string} name - The name of the component.
- * @property {TEvent<TValidationMethods>} [validations] - The validation methods for the component.
+ * @property {string} nameToSubmit - The name of the field when submit values (optional).
+ * @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.
@@ -21,10 +22,26 @@ import { TApiEvent, TErrorMessages, TEvent, TFormatters, TMasks, TProps, TResetV
  *   component: 'input',
  *   props: { type: 'text', placeholder: 'Enter your name' },
  *   name: 'name',
- *   validations: { config: { required: true }, events: [{ eventName: 'ON_FIELD_BLUR' }] },
+ *   nameToSubmit: 'applicant.firstName',
+ *   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: ',' } },
@@ -36,15 +53,20 @@ interface IComponentSchema {
     component: string;
     props?: TProps;
     name: string;
-    validations?: TEvent<TValidationMethods>;
+    nameToSubmit?: string;
+    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.
@@ -80,4 +102,4 @@ interface IFormSchema {
     iVars?: Record<string, unknown>;
     components?: IComponentSchema[];
 }
-export { IFormSchema, IComponentSchema };
+export { IFormSchema, IComponentSchema, IComponentSchemaAsFormField };

package/src/interfaces/state.d.ts

@@ -1,27 +1,22 @@
-import { TApiResponse } from '../types/schema';
 /**
  * @interface IState
  * Represents the state of a form component.
  *
  * @property {string[]} errors - The list of error messages.
  * @property {boolean} visibility - The visibility state of the component.
- * @property {TApiResponse} apiResponse - The API response data.
  * @property {Record<string, unknown>} props - The properties of the component.
  *
  * @example
  * ```typescript
  * const state: IState = {
- *   errors: ['This field is required.'],
  *   visibility: true,
- *   apiResponse: { default: { response: null } },
  *   props: { type: 'text', value: 'John' }
  * };
  * ```
  */
 interface IState {
-    errors: string[];
     visibility: boolean;
-    apiResponse: TApiResponse;
     props: Record<string, unknown>;
+    errors: Record<string, unknown>;
 }
 export { IState };

package/src/managers/field.d.ts

@@ -1,18 +1,21 @@
 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, TMutationEvents, TValueChangeEvent } from '../types/event';
+import { TEvents, TFieldEvent, TMutationEvents, TValueChangeEvent } from '../types/event';
 import { TMapper } from '../types/mapper';
+import { SafeSubject } from '../helpers/SafeSubject';
 /**
  * Represents a form field with observables for managing form state, validations, and API requests.
  */
 declare class FormField {
     name: string;
+    nameToSubmit?: string;
     component: string;
     path?: string;
-    children: string[];
-    validations?: TEvent<TValidationMethods>;
+    children?: string[];
+    originalSchema: IComponentSchemaAsFormField<unknown>;
+    validations?: TValidations;
     visibilityConditions?: TVisibility[];
     resetValues?: TResetValueMethods[];
     errorMessages?: TErrorMessages;
@@ -20,28 +23,27 @@ declare class FormField {
     formatters?: TFormatters;
     masks?: TMasks;
     valuePropName?: string;
-    errorMessagePropName?: string;
     initialValue?: unknown;
     config: Required<TSchemaFormConfig>;
     mapper: TMapper<unknown>;
+    errorsString: string;
+    errorsList: string[];
     private _props;
     private _value;
     private _stateValue;
     private _metadata;
     private _visibility;
     private _errors;
-    private _errorsString;
     private _api;
     private _valid;
-    propsSubject$: Subject<Record<string, unknown>>;
-    errorSubject$: Subject<string[]>;
-    valueSubject$: Subject<unknown>;
-    visibilitySubject$: Subject<boolean>;
-    apiSubject$: Subject<TApiResponse>;
-    apiResponseSubject$: Subject<{
-        key: string;
-    }>;
-    apiEventQueueSubject$: Subject<{
+    private _mounted;
+    propsSubject$: SafeSubject<Record<string, unknown>>;
+    errorSubject$: SafeSubject<Record<string, unknown>>;
+    valueSubject$: SafeSubject<Record<string, unknown>>;
+    visibilitySubject$: SafeSubject<boolean>;
+    apiSubject$: SafeSubject<TApiResponse>;
+    fieldEventSubject$: Subject<TFieldEvent>;
+    apiEventQueueSubject$: SafeSubject<{
         event: TEvents;
     }>;
     fieldState$: Observable<IState>;
@@ -76,11 +78,11 @@ declare class FormField {
      * @param {unknown} [options.initialValue] - The initial value of the form field.
      * @param {Subject<{ key: string }>} options.templateSubject$ - A subject for template updates.
      */
-    constructor({ schemaComponent, config, path, children, validateVisibility, resetValue, initialValue, templateSubject$, apiResponseSubject$, dataSubject$, mapper, }: {
+    constructor({ schemaComponent, config, path, children, validateVisibility, resetValue, initialValue, templateSubject$, fieldEventSubject$, dataSubject$, mapper, }: {
         schemaComponent: IComponentSchema;
         config?: TSchemaFormConfig;
         path?: string;
-        children: string[];
+        children?: string[];
         validateVisibility: (payload: {
             event: TEvents;
             key: string;
@@ -94,9 +96,7 @@ declare class FormField {
             key: string;
             event: TMutationEvents;
         }>;
-        apiResponseSubject$: Subject<{
-            key: string;
-        }>;
+        fieldEventSubject$: Subject<TFieldEvent>;
         dataSubject$: Subject<{
             key: string;
             event: TEvents;
@@ -107,21 +107,6 @@ declare class FormField {
      * method to initialize all recycled Subjects and initialize Observers on field instance creation or rerender
      */
     initializeObservers(): void;
-    /**
-     * Observable function to emit api events debounced and distinct for each event type,
-     * avoiding previous events being cancelled by new events if they occur inside the debounce time interval
-     *
-     * @param {(event: { event: TEvents }) => TEvents} keyExtractor function that will pass the event key to the groupBy operator
-     * @param {number} debounceTimeMs time to wait for each individual event emmited
-     * @returns
-     */
-    debounceDistinct(keyExtractor: (event: {
-        event: TEvents;
-    }) => TEvents, debounceTimeMs: number): (source$: Observable<{
-        event: TEvents;
-    }>) => Observable<{
-        event: TEvents;
-    }>;
     /**
      * Retrieves the properties associated with the form field.
      *
@@ -137,16 +122,10 @@ declare class FormField {
     /**
      * Retrieves the current state value of the form field.
      *
-     * @returns {unknown} - The current state value of the form field.
+     * @returns {Record<string,unknown>} - The current state value of the form field.
      */
-    get stateValue(): unknown;
+    get stateValue(): Record<string, unknown>;
     get metadata(): unknown;
-    /**
-     * Retrieves the concatenated string of errors associated with the form field.
-     *
-     * @returns {string} - The concatenated string of errors.
-     */
-    get errorsString(): string;
     /**
      * Retrieves the current value of the form field.
      *
@@ -205,15 +184,12 @@ declare class FormField {
      * Mounts the form field by initializing necessary subjects and combining their streams.
      *
      * @param {object} mountOpts - Adapter mount options.
-     * @param {string} prop.valuePropName - Adapter value property name.
-     * @param {(event: unknown) => unknown} prop.valueChangeEvent - Adapter change event handler function
      * @param {(value: unknown) => unknown} prop.valueSubscription - Adapter value change function
      * @param {(payload: Partial<IState>) => unknown} prop.propsSubscription - Adapter prop change function
-     * @param {string} prop.errorMessagePropName - error message property name to set errors onto component
      * @returns {void}
      */
     mountField({ valueSubscription, propsSubscription, }: {
-        valueSubscription: (value: unknown) => void;
+        valueSubscription: (value: Record<string, unknown>) => void;
         propsSubscription: (payload: Partial<IState>) => void;
     }): void;
     /**
@@ -224,10 +200,7 @@ declare class FormField {
      * @returns {void}
      */
     emitValue(prop: {
-        value: unknown | {
-            _value: unknown;
-            _stateValue: unknown;
-        };
+        value: unknown;
         event: TEvents;
     }): void;
     /**
@@ -248,10 +221,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,9 +1,9 @@
 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 { TEvents, TMutationEvents } from '../types/event';
+import { TEvents, TFieldEvent, TMutationEvents } from '../types/event';
 import { TFormEntry, TFormValues } from '../types/form';
 import { TMapper } from '../types/mapper';
 /**
@@ -18,21 +18,17 @@ declare class FormCore {
         key: string;
         event: TMutationEvents;
     }>;
-    submitSubject$: Subject<TFormValues>;
-    apiResponseSubject$: Subject<{
-        key: string;
-    }>;
+    submitSubject$: Subject<TFormValues<Record<string, unknown>>>;
+    fieldEventSubject$: Subject<TFieldEvent>;
     dataSubject$: Subject<{
         key: string;
         event: TEvents;
     }>;
-    dataCallbackSubscription$: Subscription;
     subscribedTemplates: TSubscribedTemplates[];
     action?: string;
     method?: string;
-    config?: TSchemaFormConfig;
-    mappers: TMapper<unknown>[];
-    onSubmit?: (data: TFormValues) => void;
+    config: Required<TSchemaFormConfig>;
+    mappers: Map<string, TMapper<unknown>>;
     /**
      * Creates an instance of FormCore.
      *
@@ -42,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'>);
@@ -68,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;
-    }) => void): void;
     /**
      * Gets the value of a property from a field.
      *
@@ -115,7 +102,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.
      *
@@ -123,7 +110,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.
      *
@@ -142,15 +129,6 @@ declare class FormCore {
         key: string;
         event: TMutationEvents;
     }): void;
-    /**
-     * Refreshes api observed fields.
-     *
-     * @param {object} options - Options for refreshing api.
-     * @param {string} options.key - The key of the field triggering the update.
-     */
-    refreshApi({ key }: {
-        key: string;
-    }): string;
     /**
      * Validates and collects the names of form fields in the provided schema structure.
      *
@@ -183,19 +161,31 @@ declare class FormCore {
         event: TEvents;
         key: string;
     }): void;
+    /**
+     * Adds a field onto the form instance regardless there is a schema or not
+     *
+     * @param fieldSchema
+     */
+    addField({ fieldSchema, mapperElement, }: {
+        fieldSchema: IComponentSchema;
+        mapperElement?: TMapper<unknown>;
+    }): void;
+    removeField({ key }: {
+        key: string;
+    }): void;
     /**
      * Serializes the schema structure to create form fields.
      *
      * @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.
      *
@@ -215,7 +205,19 @@ declare class FormCore {
      *
      * @returns {TFormValues} The current form values.
      */
-    getFormValues(): TFormValues;
+    getFormValues(): TFormValues<Record<string, unknown>>;
+    subscribeFieldEvent({ callback, }: {
+        callback: (payload: TFieldEvent) => void;
+    }): Subscription;
+    /**
+     *
+     * @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): Subscription;
+    subscribeOnSubmit(callback: (payload: TFormValues<Record<string, unknown>>) => void): Subscription;
     /**
      * Submits the form by triggering form field events and invoking the onSubmit callback.
      */

package/src/managers/formGroup.d.ts

@@ -1,4 +1,5 @@
 import { TFormValues } from '../types/form';
+import { TMapper } from '../types/mapper';
 import { TFormCore } from './form';
 /**
  * Represents a group that manages multiple forms.
@@ -9,6 +10,16 @@ declare class FormGroup {
      * Creates an instance of FormGroup.
      */
     constructor();
+    /**
+     * Creates an empty form with given index
+     *
+     * @param {string} options.index
+     * @param {TMapper<unknown>} options.mappers
+     */
+    createFormWithIndex({ index, mappers, }: {
+        index: string;
+        mappers?: TMapper<unknown>[];
+    }): void;
     /**
      * Adds a form instance to the form group.
      *
@@ -29,7 +40,7 @@ declare class FormGroup {
      */
     getForm({ key }: {
         key: string;
-    }): import("./form").FormCore | undefined;
+    }): TFormCore | undefined;
     /**
      * Removes a form instance from the form group.
      *
@@ -39,6 +50,16 @@ declare class FormGroup {
     removeForm({ key }: {
         key: string;
     }): void;
+    /**
+     * removes a field given a form and field index
+     *
+     * @param {string} options.formIndex
+     * @param {string} options.fieldIndex
+     */
+    removeField({ formIndex, fieldIndex, }: {
+        formIndex: string;
+        fieldIndex: string;
+    }): void;
     /**
      * Checks if the specified key already exists in the form group.
      *
@@ -58,7 +79,15 @@ declare class FormGroup {
      * @param {string[]} indexes form indexes to be submitted
      * @returns
      */
-    submitMultipleFormsByIndex(indexes: string[]): TFormValues;
+    submitMultipleFormsByIndex<T>(indexes: string[], callback?: (payload: TFormValues<T>) => void): void;
+    onDataSubscription({ ids, callback, }: {
+        ids: string[];
+        callback: (payload: Record<string, {
+            formId: string;
+            formField: string;
+            values?: TFormValues<Record<string, unknown>>;
+        }>) => void;
+    }): import("rxjs").Subscription;
 }
 type TFormGroup = FormGroup;
 export { TFormGroup, FormGroup };

package/src/types/event.d.ts

@@ -1,3 +1,4 @@
+import { IFormField } from '../managers';
 /**
  * @type TEvents
  * Represents the different types of events that can occur on form fields.
@@ -40,4 +41,9 @@ declare enum TMutationEnum {
 type TValueChangeEvent = (value: unknown, opts?: {
     props: Record<string, unknown>;
 }) => void;
-export { TEvents, TMutationEvents, TMutationEnum, TValueChangeEvent };
+type TFieldEvent = {
+    event: TEvents;
+    fieldName: string;
+    fieldInstance?: IFormField;
+};
+export { TEvents, TMutationEvents, TMutationEnum, TValueChangeEvent, TFieldEvent };

package/src/types/form.d.ts

@@ -1,10 +1,10 @@
 import { IFormSchema } from '../interfaces/schema';
 import { TMapper } from './mapper';
 /**
- * @type TFormValues
- * Represents the values and state of a form.
+ * @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.
  *
- * @property {Record<string, unknown>} values - The current values of the form fields.
+ * @property {Generic Type} values - The current values of the form fields.
  * @property {string[]} erroredFields - A list of field names that have errors.
  * @property {boolean} isValid - Indicates whether the form is valid.
  *
@@ -17,8 +17,8 @@ import { TMapper } from './mapper';
  * };
  * ```
  */
-type TFormValues = {
-    values: Record<string, unknown>;
+type TFormValues<T> = {
+    values: T;
     erroredFields: string[];
     isValid: boolean;
 };
@@ -41,11 +41,6 @@ type TFormValues = {
  */
 type TFormEntry = Omit<IFormSchema, 'components'> & {
     schema?: IFormSchema;
-    onSubmit?: (data: TFormValues) => void;
-    onData?: (payload: {
-        field: string;
-        data: TFormValues;
-    }) => void;
-    mappers: TMapper<unknown>[];
+    mappers?: TMapper<unknown>[];
 };
 export { TFormValues, TFormEntry };