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

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@bolttech/form-engine-core",
-  "version": "0.0.1-beta.1",
+  "version": "0.0.1-beta.11",
   "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,3 @@
+declare const DEFAULT_API_DEBOUNCE_TIME = 1000;
+declare const DEFAULT_STATE_REFRESH_TIME = 100;
+export { DEFAULT_API_DEBOUNCE_TIME, DEFAULT_STATE_REFRESH_TIME };

package/src/interfaces/schema.d.ts

@@ -1,4 +1,5 @@
-import { TApiEvent, TErrorMessages, TEvent, TFormatters, TMasks, TProps, TResetValueMethods, TValidationMethods, TVisibility } from '../types/schema';
+import { TMapper } from '../types/mapper';
+import { TApiEvent, TErrorMessages, TEvent, TFormatters, TMasks, TProps, TResetValueMethods, TSchemaFormConfig, TValidationMethods, TVisibility } from '../types/schema';
 /**
  * @interface IComponentSchema
  * Represents the schema for a component within a form.
@@ -6,6 +7,7 @@ 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 {string} nameToSubmit - The name of the field when submit values (optional).
  * @property {TEvent<TValidationMethods>} [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.
@@ -21,6 +23,7 @@ import { TApiEvent, TErrorMessages, TEvent, TFormatters, TMasks, TProps, TResetV
  *   component: 'input',
  *   props: { type: 'text', placeholder: 'Enter your name' },
  *   name: 'name',
+ *   nameToSubmit: 'applicant.firstName',
  *   validations: { config: { required: true }, events: [{ eventName: 'ON_FIELD_BLUR' }] },
  *   visibilityConditions: [{ conditions: { field: 'age', value: 18 } }],
  *   resetValues: [{ field: 'age', resetTo: '' }],
@@ -36,6 +39,7 @@ interface IComponentSchema {
     component: string;
     props?: TProps;
     name: string;
+    nameToSubmit?: string;
     validations?: TEvent<TValidationMethods>;
     api?: TApiEvent;
     visibilityConditions?: TVisibility[];
@@ -45,6 +49,11 @@ interface IComponentSchema {
     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.
@@ -75,8 +84,9 @@ interface IFormSchema {
     index: string;
     action?: string;
     method?: string;
+    config?: TSchemaFormConfig;
     initialValues?: Record<string, unknown>;
     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,17 +1,19 @@
 import { Observable, Subject, Subscription } from 'rxjs';
-import { TApiConfig, TApiEvent, TApiResponse, TErrorMessages, TEvent, TFormatters, TMasks, TResetValueMethods, TValidationMethods, TVisibility } from '../types/schema';
-import { IComponentSchema } from '../interfaces/schema';
+import { TApiConfig, TApiEvent, TApiResponse, TErrorMessages, TEvent, TFormatters, TMasks, TResetValueMethods, TSchemaFormConfig, TValidationMethods, 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';
 /**
  * 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[];
+    children?: string[];
+    originalSchema: IComponentSchemaAsFormField<unknown>;
     validations?: TEvent<TValidationMethods>;
     visibilityConditions?: TVisibility[];
     resetValues?: TResetValueMethods[];
@@ -20,26 +22,25 @@ 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>;
+    errorSubject$: Subject<Record<string, unknown>>;
+    valueSubject$: Subject<Record<string, unknown>>;
     visibilitySubject$: Subject<boolean>;
     apiSubject$: Subject<TApiResponse>;
-    apiResponseSubject$: Subject<{
-        key: string;
-    }>;
+    fieldEventSubject$: Subject<TFieldEvent>;
     apiEventQueueSubject$: Subject<{
         event: TEvents;
     }>;
@@ -67,6 +68,7 @@ declare class FormField {
      *
      * @param {object} options - Configuration options for the form field.
      * @param {IComponentSchema} options.schemaComponent - The schema definition for the form field.
+     * @param {TSchemaFormConfig} options.config - The schema default configuration for debounced actions.
      * @param {string} [options.path] - The path within the form field (used internally during recursion).
      * @param {string[]} options.children - An array of children fields names.
      * @param {Function} options.validateVisibility - A function to validate the visibility of the field.
@@ -74,10 +76,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, 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;
@@ -91,9 +94,7 @@ declare class FormField {
             key: string;
             event: TMutationEvents;
         }>;
-        apiResponseSubject$: Subject<{
-            key: string;
-        }>;
+        fieldEventSubject$: Subject<TFieldEvent>;
         dataSubject$: Subject<{
             key: string;
             event: TEvents;
@@ -104,21 +105,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.
      *
@@ -134,16 +120,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.
      *
@@ -202,15 +182,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;
     /**
@@ -221,10 +198,7 @@ declare class FormField {
      * @returns {void}
      */
     emitValue(prop: {
-        value: unknown | {
-            _value: unknown;
-            _stateValue: unknown;
-        };
+        value: unknown;
         event: TEvents;
     }): void;
     /**
@@ -245,6 +219,10 @@ 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,8 +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';
 /**
@@ -17,10 +18,8 @@ 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;
@@ -29,8 +28,9 @@ declare class FormCore {
     subscribedTemplates: TSubscribedTemplates[];
     action?: string;
     method?: string;
-    mappers: TMapper<unknown>[];
-    onSubmit?: (data: TFormValues) => void;
+    config: Required<TSchemaFormConfig>;
+    mappers: Map<string, TMapper<unknown>>;
+    onSubmit?: (data: TFormValues<Record<string, unknown>>) => void;
     /**
      * Creates an instance of FormCore.
      *
@@ -72,7 +72,7 @@ declare class FormCore {
      */
     subscribeData(callback: (payload: {
         field: string;
-        data: TFormValues;
+        data: TFormValues<Record<string, unknown>>;
     }) => void): void;
     /**
      * Gets the value of a property from a field.
@@ -113,7 +113,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 +121,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.
      *
@@ -140,15 +140,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.
      *
@@ -181,19 +172,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.
      *
@@ -213,7 +216,10 @@ declare class FormCore {
      *
      * @returns {TFormValues} The current form values.
      */
-    getFormValues(): TFormValues;
+    getFormValues(): TFormValues<Record<string, unknown>>;
+    subscribeFieldEvent({ callback, }: {
+        callback: (payload: TFieldEvent) => 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,7 @@ declare class FormGroup {
      * @param {string[]} indexes form indexes to be submitted
      * @returns
      */
-    submitMultipleFormsByIndex(indexes: string[]): TFormValues;
+    submitMultipleFormsByIndex<T>(indexes: string[]): TFormValues<T>;
 }
 type TFormGroup = FormGroup;
 export { TFormGroup, FormGroup };

package/src/managers/index.d.ts

@@ -0,0 +1,3 @@
+export * from './form';
+export * from './field';
+export * from './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,11 @@ type TFormValues = {
  */
 type TFormEntry = Omit<IFormSchema, 'components'> & {
     schema?: IFormSchema;
-    onSubmit?: (data: TFormValues) => void;
-    onData?: (payload: {
+    onSubmit?: <T>(data: TFormValues<T>) => void;
+    onData?: <T>(payload: {
         field: string;
-        data: TFormValues;
+        data: TFormValues<T>;
     }) => void;
-    mappers: TMapper<unknown>[];
+    mappers?: TMapper<unknown>[];
 };
 export { TFormValues, TFormEntry };

package/src/types/schema.d.ts

@@ -700,10 +700,11 @@ type TResetValues = Partial<Record<TEvents, TResetValueMethods[]>>;
  * const errorMessages: TErrorMessages = {
  *   required: 'This field is required.',
  *   max: 'The value cannot exceed the maximum limit.'
+ *   default: 'Default error message'
  * };
  * ```
  */
-type TErrorMessages = Partial<Record<keyof TValidationMethods, string>>;
+type TErrorMessages = Partial<Record<keyof TValidationMethods & 'default', string>>;
 /**
  * Represents an event configuration with a specific type.
  *
@@ -739,4 +740,14 @@ type TApiResponse = {
         response: unknown;
     }>;
 };
-export { TApiConfig, TErrorMessages, TResetValues, TVisibilityConditions, TValidations, TMasks, TProps, TResetValueMethods, TFormatters, TValidationMethods, TEvent, TVisibility, TApiEvent, TApiResponse, TLengthValidation, TCreditCardMatch, TDocumentValidation, TCallbackValidation, TBetweenValidation, TMaskGeneric, TSplitterFormatterValue, TCurrencyMask, TDateOperatorsValidation, TConditionsValidationSet, TConditionsValidation, TMultipleValidation, TAvailableValidations, TDateValidation, TBetweenDatesValidation, TDateFormatsValidation, TDateInterval, };
+/**
+ * Represents the schema config structure
+ *
+ * @property {number} defaultAPIdebounceTimeMS - default API debounce time between request events.
+ * @property {number} [defaultStateRefreshTimeMS] - default state refresh between events side effects.
+ */
+type TSchemaFormConfig = {
+    defaultAPIdebounceTimeMS?: number;
+    defaultStateRefreshTimeMS?: number;
+};
+export { TApiConfig, TErrorMessages, TResetValues, TVisibilityConditions, TValidations, TMasks, TProps, TResetValueMethods, TFormatters, TValidationMethods, TEvent, TVisibility, TApiEvent, TApiResponse, TSchemaFormConfig, TLengthValidation, TCreditCardMatch, TDocumentValidation, TCallbackValidation, TBetweenValidation, TMaskGeneric, TSplitterFormatterValue, TCurrencyMask, TDateOperatorsValidation, TConditionsValidationSet, TConditionsValidation, TMultipleValidation, TAvailableValidations, TDateValidation, TBetweenDatesValidation, TDateFormatsValidation, TDateInterval, };