@bolttech/form-engine-core 1.0.10 → 1.1.0

package/src/interfaces/schema.d.ts

@@ -0,0 +1,161 @@
+import { TMapper } from '../types/mapper';
+import { TApiEvent, TFormatters, TMasks, TProps, TResetPathMethods, TResetValueMethods, TSchemaFormConfig, TValidations, TVisibility } from '../types/schema';
+/**
+ * @interface IComponentSchema
+ * Represents the schema for a component within a form.
+ *
+ * @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 {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 {TApiEvent} [api] - The API configuration for the component.
+ * @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
+ * const schema: IComponentSchema = {
+ *   component: 'input',
+ *   props: { type: 'text', placeholder: 'Enter your name' },
+ *   name: 'name',
+ *   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: '' }],
+ *   api: {
+ *     defaultConfig: {
+ *       config: { method: 'POST', url: 'https://api.example.com/submit' },
+ *       events: [{ eventName: 'ON_FIELD_BLUR' }]
+ *     }
+ *   },
+ *   formatters: { capitalize: true },
+ *   masks: { currency: { align: 'left', decimal: '.', precision: 2, prefix: '$', thousands: ',' } },
+ *   children: [],
+ *   visibility: true,
+ *   persistValue: true,
+ * };
+ * ```
+ */
+interface IComponentSchema {
+    /** The type of component (e.g., 'input', 'button'). */
+    component: string;
+    /** The properties of the component. */
+    props?: TProps;
+    /** The name of the component. */
+    name: string;
+    /** The name of the field when submit values. */
+    nameToSubmit?: string;
+    /** The validation methods for the component. */
+    validations?: TValidations;
+    /** The API configuration for the component. */
+    api?: TApiEvent;
+    /** The visibility conditions for the component. */
+    visibilityConditions?: TVisibility[];
+    /** The reset value methods for the component. */
+    resetValues?: TResetValueMethods[];
+    /** The reset property values for the component. */
+    resetPropertyValues?: TResetPathMethods[];
+    /** The formatters for the component. */
+    formatters?: TFormatters;
+    /** The masks for the component. */
+    masks?: TMasks;
+    /** The child components. */
+    children?: IComponentSchema[];
+    /** Visibility status the component will mount (to avoid SSR blinking) */
+    visibility?: boolean;
+    /** Check this if you want the last visible value to be restored after a visiblity schema rule applied  */
+    persistValue?: boolean;
+}
+interface IComponentSchemaAsFormField<T> extends IComponentSchema {
+    mapper?: TMapper<T>;
+    children?: IComponentSchemaAsFormField<T>[];
+}
+/**
+ * @interface IFormSchema
+ * Represents the schema for a form.
+ *
+ * @property {string} index - The unique index or identifier for the form.
+ * @property {string} [action] - The URL to which the form data will be submitted. (experimental)
+ * @property {string} [method] - The HTTP method used to submit the form (e.g., 'POST', 'GET') (experimental).
+ * @property {Record<string, unknown>} [initialValues] - The initial values for the form fields.
+ * @property {Record<string, unknown>} [iVars] - Dynamic key value pairs that change from any external source
+ * @property {IComponentSchema[]} [components] - The list of components included in the form.
+ * @property {boolean} [stopEventsOnSubmit] - stop all the events declared as callback on useForm/Form once form is submitted
+ * @property {TSchemaFormConfig} [config] - form configurations to change event debouncers and debugging tools
+ *
+ * @example
+ * ```typescript
+ * const formSchema: IFormSchema = {
+ *   index: 'userForm',
+ *   initialValues: { name: '', email: '' },
+ *   iVars: iVarsState,
+ *   config: {
+ *     defaultLogVerbose: true
+ *   },
+ *   components: [
+ *     { component: 'input', name: 'name', props: { placeholder: 'Enter your name' } },
+ *     { component: 'input', name: 'email', props: { placeholder: 'Enter your email' } }
+ *   ]
+ * };
+ * ```
+ */
+interface IFormSchema {
+    index: string;
+    action?: string;
+    method?: string;
+    config?: TSchemaFormConfig;
+    initialValues?: Record<string, unknown>;
+    iVars?: Record<string, unknown>;
+    components?: IComponentSchema[];
+    stopEventsOnSubmit?: boolean;
+    /** Pre-fetched API response data for SSR. Keys are field names, values contain the API responses to hydrate. */
+    prefetchedData?: Record<string, TPrefetchedFieldData>;
+}
+/**
+ * Represents pre-fetched API data for a single field.
+ * Used to hydrate API response caches during SSR so templates referencing API data resolve correctly.
+ *
+ * @property {unknown} [defaultResponse] - The pre-fetched response for the field's default API config.
+ * @property {Record<string, unknown>} [namedResponses] - Pre-fetched responses for named API configs.
+ *
+ * @example
+ * ```typescript
+ * const prefetchedData = {
+ *   countryField: {
+ *     defaultResponse: [{ id: 'BR', label: 'Brazil' }, { id: 'US', label: 'United States' }],
+ *   },
+ *   stateField: {
+ *     namedResponses: { statesByCountry: [{ id: 'SP', label: 'São Paulo' }] },
+ *   },
+ * };
+ * ```
+ */
+interface TPrefetchedFieldData {
+    /** The pre-fetched response for the field's default API config. */
+    defaultResponse?: unknown;
+    /** Pre-fetched responses keyed by named API config name. */
+    namedResponses?: Record<string, unknown>;
+}
+export { IFormSchema, IComponentSchema, IComponentSchemaAsFormField, TPrefetchedFieldData };

package/src/interfaces/state.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @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 {Record<string, unknown>} props - The properties of the component.
+ *
+ * @example
+ * ```typescript
+ * const state: IState = {
+ *   visibility: true,
+ *   props: { type: 'text', value: 'John' }
+ * };
+ * ```
+ */
+interface IState {
+    visibility: boolean;
+    props: Record<string, unknown>;
+    errors: Record<string, unknown>;
+}
+export { IState };

package/src/lite.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Lite entry point for form-engine-core.
+ *
+ * This entry point excludes credit-card and document validation modules,
+ * reducing bundle size for consumers who don't need them.
+ *
+ * To add credit card support:
+ *   import '@bolttech/form-engine-core/credit-card';
+ *
+ * To add document validation support:
+ *   import '@bolttech/form-engine-core/document';
+ *
+ * @example
+ * ```typescript
+ * import { FormCore, FormGroup } from '@bolttech/form-engine-core/lite';
+ * import '@bolttech/form-engine-core/credit-card'; // optional
+ * ```
+ */
+export * from './types/event';
+export * from './types/form';
+export * from './types/schema';
+export * from './types/template';
+export * from './types/mapper';
+export * from './types/utility';
+export * from './interfaces/schema';
+export * from './interfaces/state';
+export * from './managers/form';
+export * from './managers/formGroup';
+export * from './managers/field';
+export { registerValidations, registerFormatters, registerMasks, validationRegistry, formatterRegistry, maskRegistry } from './registry';

package/src/managers/field.d.ts

@@ -0,0 +1,339 @@
+import { Subject, Subscription, BehaviorSubject } 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, TFieldValidationPayload, TFormDataPayload, TValueChangeEvent } from '../types/event';
+import { TMapper } from '../types/mapper';
+import { SafeSubject } from '../helpers/SafeSubject';
+import { TTemplateEvent } from '../types/template';
+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;
+    children?: string[];
+    originalSchema: IComponentSchemaAsFormField<unknown>;
+    validations?: TValidations;
+    visibilityConditions?: TVisibility[];
+    resetValues?: TResetValueMethods[];
+    resetPropertyValues?: TResetPathMethods[];
+    apiSchema?: TApiEvent;
+    formatters?: TFormatters;
+    masks?: TMasks;
+    valuePropName?: string;
+    config: Required<TSchemaFormConfig>;
+    mapper: TMapper<unknown>;
+    errorsString: string;
+    errorsList: string[];
+    private _props;
+    private _adapterProps;
+    private _value;
+    private _stateValue;
+    private _metadata;
+    private _visibility;
+    private _errors;
+    private _api;
+    private _valid;
+    private _mounted;
+    propsSubject$: SafeSubject<Record<string, unknown>>;
+    errorSubject$: SafeSubject<Record<string, unknown>>;
+    valueSubject$: SafeSubject<Record<string, unknown>>;
+    valueSubscription$: Subscription;
+    visibilitySubject$: SafeSubject<boolean>;
+    fieldEventSubject$: Subject<TFieldEvent>;
+    apiEventQueueSubject$: SafeSubject<{
+        event: TEvents;
+    }>;
+    fieldStateSubscription$: Subscription;
+    templateSubject$: Subject<TTemplateEvent>;
+    dataSubject$: Subject<TFormDataPayload>;
+    fieldValidNotification$: Subject<TFieldValidationPayload>;
+    mountSubject$: Subject<{
+        key: string;
+        status: boolean;
+    }>;
+    formValuesStateSubject$: BehaviorSubject<TFormValues<unknown>>;
+    validateVisibility: (payload: {
+        event: TEvents;
+        key: string;
+    }) => void;
+    resetValue: (payload: {
+        event: TEvents;
+        key: string;
+    }) => void;
+    resetProperty: (payload: {
+        event: TEvents;
+        key: string;
+    }) => void;
+    getFormValues: () => TFormValues<unknown>;
+    valueChangeEvent: TValueChangeEvent;
+    submitEvent: () => void;
+    persistValue?: boolean;
+    /**
+     * Creates an instance of 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.
+     * @param {Function} options.resetValue - A function to reset the field value.
+     * @param {Function} options.resetProperty - A function to reset a field property.
+     * @param {Subject<{ key: string }>} options.templateSubject$ - A subject for template updates.
+     * @param {Subject<TFieldEvent>} options.fieldEventSubject$, - Subject for basic event mapped field emissions, except onData to form instance
+     * @param {Subject<{ key: string; event: TEvents }>} options.dataSubject$, - Subject to emit onData events to form instance
+     * @param {Subject<{ key: string }>} options.formValidNotification$, - Subject to emit field valid change to form instance
+     * @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({ formIndex, schemaComponent, config, children, validateVisibility, resetValue, resetProperty, templateSubject$, fieldEventSubject$, dataSubject$, fieldValidNotification$, mountSubject$, mapper, formValuesStateSubject$, submitEvent, visibility, persistValue, }: {
+        formIndex: string;
+        schemaComponent: IComponentSchema;
+        config?: TSchemaFormConfig;
+        path?: string;
+        children?: string[];
+        validateVisibility: (payload: {
+            event: TEvents;
+            key: string;
+        }) => void;
+        resetValue: (payload: {
+            event: TEvents;
+            key: string;
+        }) => void;
+        resetProperty: (payload: {
+            event: TEvents;
+            key: string;
+        }) => void;
+        submitEvent: () => void;
+        templateSubject$: Subject<TTemplateEvent>;
+        fieldEventSubject$: Subject<TFieldEvent>;
+        dataSubject$: Subject<TFormDataPayload>;
+        fieldValidNotification$: Subject<TFieldValidationPayload>;
+        mountSubject$: Subject<{
+            key: string;
+            status: boolean;
+        }>;
+        formValuesStateSubject$: BehaviorSubject<TFormValues<unknown>>;
+        mapper: TMapper<unknown>;
+        visibility?: boolean;
+        persistValue?: 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;
+    /**
+     * Retrieves the raw props sent from the adapter.
+     *
+     * @returns {string} - raw props from the adapter
+     */
+    get adapterProps(): string;
+    /**
+     * compares adapter props changes and emits the change if they effectively changed
+     * preventing an emission from the adapter of the same props that can overwrite other prop
+     * changes via templating
+     */
+    set adapterProps(props: Record<string, unknown>);
+    /**
+     * Retrieves the properties associated with the form field.
+     *
+     * @returns {Record<string, unknown>} - The properties of the form field.
+     */
+    get props(): Record<string, unknown>;
+    /**
+     * Sets the properties of the form field and notifies subscribers about the change.
+     *
+     * @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.
+     *
+     * @returns {Record<string,unknown>} - The current state value of the form field.
+     */
+    get stateValue(): Record<string, unknown>;
+    get metadata(): unknown;
+    /**
+     * Retrieves the current value of the form field.
+     *
+     * @returns {unknown} - The current value of the form field.
+     */
+    get value(): unknown;
+    /**
+     * Sets the value of the form field and notifies subscribers about the change.
+     *
+     * @param {unknown} value - The new value to be set.
+     */
+    set value(value: unknown);
+    /**
+     * Retrieves the visibility status of the form field.
+     *
+     * @returns {boolean} - The visibility status of the form field.
+     */
+    get visibility(): boolean;
+    /**
+     * Sets the visibility status of the form field and notifies subscribers about the change.
+     *
+     * @param {boolean} visible - The new visibility status to be set.
+     */
+    set visibility(visible: boolean);
+    /**
+     * sets valid field state and notifies form instance via formValidNotification$
+     */
+    set valid(valid: boolean);
+    /**
+     * Retrieves the validity status of the form field.
+     *
+     * @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.
+     *
+     * @returns {TErrorMessages} - The error messages associated with the form field.
+     */
+    get errors(): TErrorMessages;
+    /**
+     * Sets the error messages associated with the form field and notifies subscribers about the change.
+     *
+     * @param {TErrorMessages} errors - The new error messages to be set.
+     */
+    set errors(errors: TErrorMessages);
+    /**
+     * Retrieves the API response data associated with the form field.
+     *
+     * @returns {TApiResponse} - The API response data associated with the form field.
+     */
+    get api(): TApiResponse;
+    /**
+     * Sets the API response data associated with the form field and notifies subscribers about the change.
+     *
+     * @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.
+     *
+     * @param {object} mountOpts - Adapter mount options.
+     * @param {(value: unknown) => unknown} prop.valueSubscription - Adapter value change function
+     * @param {(payload: Partial<IState>) => unknown} prop.propsSubscription - Adapter prop change function
+     * @returns {void}
+     */
+    mountField({ valueSubscription, propsSubscription, }: {
+        valueSubscription: (value: Record<string, unknown>) => void;
+        propsSubscription: (payload: Partial<IState>) => void;
+    }): void;
+    /**
+     * Sets the value of the form field and emits associated events.
+     *
+     * @param {unknown} prop.value - The new value to be set.
+     * @param {TEvents} prop.event - The event associated with setting the value.
+     * @returns {void}
+     */
+    emitValue(prop: {
+        value: unknown;
+        event: TEvents;
+    }): void;
+    /**
+     * Emits events to trigger field-related actions such as validation, visibility checks, value resets, and API requests.
+     *
+     * @param {TEvents} event - The event type that triggers the field actions.
+     * @returns {void}
+     */
+    emitEvents({ event }: {
+        event: TEvents;
+    }): void;
+    /**
+     * Sets the validity state of the field based on the provided validation rules and triggers error message updates.
+     *
+     * @param {TEvents} event - The event type associated with the field action.
+     * @returns {void}
+     */
+    setFieldValidity({ event }: {
+        event: TEvents;
+    }): void;
+    /**
+     * Formats the field value using the specified formatters, if available.
+     *
+     * @param {unknown} value - The value to be formatted.
+     * @returns {unknown} - The formatted value.
+     */
+    formatValue(value: unknown): unknown;
+    /**
+     * Masks the field value using the specified masks, if available.
+     *
+     * @param {unknown} value - The value to be masked.
+     * @returns {unknown} - The masked value.
+     */
+    maskValue(value: unknown): unknown;
+    checkApiRequestValidations(config: TApiConfig): boolean;
+    /**
+     * Makes an API request based on the field's API configuration and event type, updating the field's API response data.
+     *
+     * @param {TEvents} event - The event type associated with the API request.
+     * @returns {Promise<void>}
+     */
+    apiRequest({ event }: {
+        event: TEvents;
+    }): Promise<void>;
+    /**
+     * Unsubscribes from all subject subscriptions associated with the field, cleaning up resources.
+     *
+     * @returns {void}
+     */
+    destroyField(): void;
+    /**
+     * Subscribes to changes in the field state and executes the provided callback function.
+     *
+     * @param {Function} callback - The callback function to be executed when the field state changes.
+     * @returns {void}
+     */
+    subscribeState(callback: (payload: Partial<IState>) => void): void;
+    /**
+     * Subscribes to changes in the field value and executes the provided callback function.
+     *
+     * @param {Function} callback - The callback function to be executed when the field value changes.
+     * @returns {void}
+     */
+    subscribeValue(callback: (value: unknown) => void): void;
+}
+type IFormField = FormField;
+export { IFormField, FormField };