@bolttech/form-engine-core 1.0.10 → 1.1.0

package/src/types/event.d.ts

@@ -0,0 +1,175 @@
+import { IFormField } from '../managers';
+import { TFormValues } from './form';
+/**
+ * @type TEventEnum
+ * Represents the different types of events that can occur on form fields.
+ * @property {never} ON_FIELD_MOUNT - when field mounts on page
+ * @property {never} ON_FIELD_UNMOUNT - when field unmounts on page (also triggered when form is unmounted from page)
+ * @property {never} ON_FIELD_CHANGE - when field changes value by user inout
+ * @property {never} ON_FIELD_BLUR - when field is blurred
+ * @property {never} ON_FIELD_FOCUS - when field is focused
+ * @property {never} ON_FIELD_CLICK - when field is clicked
+ * @property {never} ON_FIELD_KEYUP - when the pressing key button on field is lifted up
+ * @property {never} ON_FIELD_KEYDOWN - when a key button on field is pressed down
+ * @property {never} ON_FIELD_CLEARED - when a field was changed with a resetValues rule
+ * @property {never} ON_FORM_SUBMIT - when the form is submitted (only type="submit" buttons)
+ * @property {never} ON_FIELD_VALIDATION - when a field is validaded by a validation rule
+ * @property {never} ON_FORM_MOUNT - emitted when the form mounts
+ * @property {never} ON_API_FIELD_REQUEST - emitted when an api request from schema is called
+ * @property {never} ON_API_FIELD_RESPONSE - emitted when an api response from schema is received
+ *
+ * @example
+ * ```typescript
+ * const event: TEvents = 'ON_FIELD_CHANGE';
+ * ```
+ */
+type TEventEnum = {
+    ON_FIELD_MOUNT: never;
+    ON_FIELD_UNMOUNT: never;
+    ON_FIELD_CHANGE: never;
+    ON_FIELD_BLUR: never;
+    ON_FIELD_FOCUS: never;
+    ON_FIELD_CLICK: never;
+    ON_FIELD_KEYUP: never;
+    ON_FIELD_KEYDOWN: never;
+    ON_FIELD_CLEARED: never;
+    ON_FORM_SUBMIT: never;
+    ON_FIELD_VALIDATION: never;
+    ON_FORM_MOUNT: never;
+    ON_API_FIELD_REQUEST: never;
+    ON_API_FIELD_RESPONSE: never;
+};
+type TEvents = keyof TEventEnum;
+/**
+ * Represents the possible event properties for form fields callbacks.
+ * * Represents a mapping of event properties to their corresponding callback functions.
+ * @property {string} onChange - trigger bind component change event
+ * @property {string} onBlur - trigger bind component blur event
+ * @property {string} onFocus - trigger bind component focus event
+ * @property {string} onKeyDown - trigger bind component keydown event
+ * @property {string} onKeyUp - trigger bind component keyup event
+ * @property {string} onMount - triggered on field mount
+ * @property {string} onApiResponse - triggered when schema api call is completed
+ * @property {string} onApiRequest - triggered when schema api call starts
+ * @property {string} onClick - trigger bind component keyup event
+ * @property {string} onCleared - triggered when a resetValue rule apply on the target field
+ * @property {string} onUnmount - triggered when a field unmounts
+ */
+type TEventPropsEnum = {
+    onChange: never;
+    onBlur: never;
+    onFocus: never;
+    onKeyDown: never;
+    onKeyUp: never;
+    onMount: never;
+    onApiResponse: never;
+    onApiRequest: never;
+    onClick: never;
+    onCleared: never;
+    onUnmount: never;
+};
+type TEventProps = keyof TEventPropsEnum;
+type TEventDataPropsEnum = {
+    onFormMount: never;
+    onData: never;
+    onSubmit: never;
+    onValid: never;
+};
+type TEventDataProps = keyof TEventDataPropsEnum;
+/**
+ * @type TMutationEvents
+ * Represents the different types of events that can occur internally that triggers templating.
+ *
+ * @example
+ * ```typescript
+ * const event: TMutationEvents = 'ON_VALUE';
+ * ```
+ */
+type TMutationEvents = 'ON_VALUE' | 'ON_PROPS' | 'ON_VISIBILITY' | 'ON_API_REQUEST' | 'ON_API_RESPONSE' | 'ON_IVARS' | 'ON_FIELDS' | 'ON_RESET' | 'ON_FORM';
+declare enum TMutationEnum {
+    ON_VALUE = "value",
+    ON_PROPS = "props",
+    ON_VISIBILITY = "visibility",
+    ON_API = "api",
+    ON_IVARS = "iVars",
+    ON_FIELDS = "fields"
+}
+/**
+ * @type TValueChangeEvent
+ * Represents the custom change handle function to perform value changes.
+ *
+ * @example
+ * ```typescript
+ * handleChangeEvent (value, opts) {
+ *   return value
+ * }
+ * ```
+ */
+type TValueChangeEvent = (value: unknown, opts?: {
+    props: Record<string, unknown>;
+}) => void;
+/**
+ * @type TFieldEvent
+ * Event emitted on all basic form events, except onData
+ */
+type TFieldEvent = {
+    event: TEvents;
+    fieldName: string;
+    fieldInstance?: IFormField;
+};
+/**
+ * @type TFormDataPayload
+ * Event emitted to formGroup instance to capture onData form events
+ */
+type TFormDataPayload = {
+    formIndex: string;
+    fieldIndex: string;
+    event: TEvents;
+};
+/**
+ * @type TFormSubmitPayload
+ * Event emitted to formGroup instance to capture onSubmit form events
+ */
+type TFormSubmitPayload<T> = {
+    formIndex: string;
+    values: TFormValues<T>;
+};
+/**
+ * @type TFormValidationPayload
+ * Form onValid event emmited payload on callback function parameter
+ */
+type TFormValidationPayload = {
+    formIndex: string;
+    valid: boolean;
+};
+/**
+ * @type TFieldValidationPayload
+ * field event emmited payload on field validation
+ */
+type TFieldValidationPayload = {
+    fieldTrigger: string;
+};
+type TFormDataValues<T> = {
+    formId: string;
+    formField: string;
+    values?: TFormValues<T>;
+};
+/**
+ * @type TFormGroupOnDataEventPayload
+ * Form Group onData event emitted payload on callback function parameter
+ */
+type TFormGroupOnDataEventPayload<T> = Record<string, TFormDataValues<T>>;
+/**
+ * @type TFormGroupOnValidEventPayload
+ * Form Group onValid event emitted payload on callback function parameter
+ */
+type TFormGroupOnValidEventPayload = {
+    groupValid: boolean;
+    forms: Record<string, boolean>;
+};
+/**
+ * @type TFormGroupOnSubmitEventPayload
+ * Form Group onSubmit event emitted payload on callback function parameter
+ */
+type TFormGroupOnSubmitEventPayload<T> = Record<string, TFormValues<T> | undefined>;
+export { TEvents, TEventEnum, TEventProps, TEventPropsEnum, TEventDataProps, TEventDataPropsEnum, TMutationEvents, TMutationEnum, TValueChangeEvent, TFieldEvent, TFormDataPayload, TFormDataValues, TFormSubmitPayload, TFormGroupOnDataEventPayload, TFormGroupOnValidEventPayload, TFormGroupOnSubmitEventPayload, TFormValidationPayload, TFieldValidationPayload, };

package/src/types/form.d.ts

@@ -0,0 +1,55 @@
+import { Subject } from 'rxjs';
+import { IFormSchema } from '../interfaces/schema';
+import { TMapper } from './mapper';
+import { TFormDataPayload, TFormSubmitPayload, TFormValidationPayload } from './event';
+/**
+ * @type TFormValues<T>
+ * Represents the values and state of a form. It has a generic type that allows the importer to determine which type values key will return.
+ *
+ * @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.
+ *
+ * @example
+ * ```typescript
+ * const formValues: TFormValues = {
+ *   values: { name: 'John', age: 30 },
+ *   erroredFields: ['email'],
+ *   isValid: false
+ * };
+ * ```
+ */
+type TFormValues<T> = {
+    values: T;
+    metadata: unknown;
+    erroredFields: string[];
+    isValid: boolean;
+};
+/**
+ * @type TFormEntry
+ * Represents the entry configuration for a form.
+ *
+ * @property {IFormSchema} [schema] - The schema defining the structure and behavior of the form.
+ * @property {Record<string, unknown>} [initialValues] - The initial values for the form fields.
+ * @property {(data: TFormValues) => void} [onSubmit] - Callback function to handle form submission.
+ * @property {Subject<TFormDataPayload>} [dataSubject$] - data subject passed from formGroup instance
+ * @property {Subject<TFormValidationPayload>} [formValidSubject$] - formValid subject passed from formGroup instance
+ * @property {Subject<TFormSubmitPayload<unknown>>} [submitSubject$] - submit subject passed from formGroup instance
+ *
+ * @example
+ * ```typescript
+ * const formEntry: TFormEntry = {
+ *   schema: [{ component: 'input', props: {}, name: 'name' }],
+ *   initialValues: { name: 'John' },
+ *   onSubmit: (data) => { console.log(data); }
+ * };
+ * ```
+ */
+type TFormEntry = Omit<IFormSchema, 'components'> & {
+    schema?: IFormSchema;
+    mappers?: TMapper<unknown>[];
+    dataSubject$?: Subject<TFormDataPayload>;
+    formValidSubject$?: Subject<TFormValidationPayload>;
+    submitSubject$?: Subject<TFormSubmitPayload<unknown>>;
+};
+export { TFormValues, TFormEntry };

package/src/types/mapper.d.ts

@@ -0,0 +1,87 @@
+import { TEventDataPropsEnum, TEventPropsEnum, TValueChangeEvent } from './event';
+import { OneOf } from './utility';
+type TComponentPropsMappingSubset = keyof (Pick<TEventPropsEnum, 'onBlur' | 'onChange' | 'onFocus' | 'onKeyDown' | 'onKeyUp' | 'onClick'> & Pick<TEventDataPropsEnum, 'onSubmit'>);
+/**
+ * @type TComponentPropsMapping
+ * Represents the mapping of component properties for various events and actions.
+ * @property {string} [getValue] - component function name to get the value.
+ * @property {string} [setValue] - component function name to set the value.
+ * @property {string} [setErrorMessage] - component function name to set the error message.
+ * @property {string} [setErrorState] - component function name to set the error state.
+ *
+ * @example
+ * ```typescript
+ * const componentProps: TComponentPropsMapping = {
+ *   getValue: 'getValueFunction',
+ *   setValue: 'setValueFunction',
+ *   onBlur: 'handleBlur',
+ *   onClick: 'handleClick',
+ *   onFocus: 'handleFocus',
+ *   onKeyUp: 'handleKeyUp',
+ *   onKeyDown: 'handleKeyDown',
+ *   setErrorMessage: 'setErrorMessageFunction',
+ *   setErrorState: 'setErrorStateFunction'
+ * };
+ * ```
+ * @interface
+ */
+type TComponentPropsMapping = Partial<Record<TComponentPropsMappingSubset, string>> & {
+    getValue?: string;
+    setValue?: string;
+    setErrorMessage?: string;
+    setErrorState?: string;
+};
+/**
+ * @type TMapper
+ * Represents the mapping of a component, including the component type,
+ * name, events, and an optional function to handle value changes.
+ *
+ * @property {ElementType} component - The component that will represent the input.
+ * * @property {ElementType} asynccomponent - The component that will represent the input but dynamically imported (suspense/lazy).
+ * @property {string} componentName - The name of the component.
+ * @property {TComponentPropsMapping} [events] - Mapping event properties for the component.
+ * @property {TValueChangeEvent} [valueChangeEvent] - Optional function to handle value changes.
+ *
+ * @example
+ * ```typescript
+ * const mappers: TMapper<ElementType>[] = [
+ *  {
+ *    component: InputElement,
+ *    componentName: 'input',
+ *    events: {
+ *      getValue: 'onChange2',
+ *      onBlur: 'onBlur2',
+ *      onFocus: 'onFocus2',
+ *    }
+ *  },
+ *  {
+ *    component: Container,
+ *    componentName: 'row',
+ *  },
+ *  {
+ *    component: Dropdown,
+ *    componentName: 'dropdown',
+ *    valueChangeEvent: (event: {
+ *      id: string;
+ *      label: string;
+ *      value: string;
+ *    }) => ({ _value: event.value, _stateValue: event.id }),
+ *  },
+ *  {
+ *    component: DatePicker,
+ *    componentName: 'datepicker',
+ *    valueChangeEvent: (event: string) => event,
+ *  },
+ * ];
+ * ```
+ * @interface
+ */
+type TMapper<T> = {
+    componentName: string;
+    events?: TComponentPropsMapping;
+    valueChangeEvent?: TValueChangeEvent;
+} & OneOf<{
+    component: T;
+    asynccomponent: T;
+}>;
+export { TMapper, TComponentPropsMapping };