@bolttech/form-engine 3.0.1-beta.6 → 3.0.1

package/package.json

@@ -1,14 +1,17 @@
 {
   "name": "@bolttech/form-engine",
-  "version": "3.0.1-beta.6",
+  "version": "3.0.1",
   "description": "A react adapter for bolttech form engine",
+  "dependencies": {
+    "@bolttech/form-engine-core": "^1.0.1"
+  },
+  "peerDependencies": {
+    "react": "19.1.1",
+    "react-dom": "19.1.1",
+    "react-router-dom": "6.11.2"
+  },
   "module": "./index.esm.js",
   "type": "module",
   "main": "./index.esm.js",
-  "dependencies": {
-    "@bolttech/form-engine-core": "0.0.2-beta.6",
-    "react": "18.2.0",
-    "rxjs": "7.8.1"
-  },
-  "peerDependencies": {}
-}
+  "types": "./index.d.ts"
+}

package/src/components/AsFormField/AsFormField.type.d.ts

@@ -3,7 +3,7 @@ import { ElementType, PropsWithChildren } from 'react';
 /**
  * AsFormField props, inherits all schema field implementation except the children
  * property and has mappers property to pass a custom component, that will be a ReactNode
- * @see {@link IComponentSchemaWithMapper}
+ * @see {@link IComponentSchemaAsFormField}
  */
 type TAsFormFieldProps = PropsWithChildren<Omit<IComponentSchemaAsFormField<ElementType>, 'children'>>;
 export type { TAsFormFieldProps };

package/src/components/AsFormFieldBuilder/AsFormFieldBuilder.type.d.ts

@@ -1,4 +1,4 @@
-import { IComponentSchema, TFieldEvent, TMapper } from '@bolttech/form-engine-core';
+import { IComponentSchema, TFieldEvent, TMapper, OneOf } from '@bolttech/form-engine-core';
 import { ElementType, PropsWithChildren } from 'react';
 import { TFieldWrapper } from '../../types';
 /**
@@ -11,10 +11,13 @@ import { TFieldWrapper } from '../../types';
  * @see {@link TMapper}
  * @see {@link IComponentSchema}
  * @see {@link TFieldWrapper}
+ * @interface
  */
-type TAsFormFieldBuilderProps = PropsWithChildren<Omit<IComponentSchema, 'children' | 'component' | 'name'> & Required<TFieldWrapper> & {
-    mapper: TMapper<ElementType>;
-    visibility?: boolean;
+type TAsFormFieldBuilderProps = PropsWithChildren<Omit<IComponentSchema, 'component' | 'children' | 'name'> & Required<TFieldWrapper> & {
     onSelected?: (data: TFieldEvent) => void;
-}>;
+    formMounted?: boolean;
+} & OneOf<{
+    mapper: TMapper<ElementType>;
+    component: string;
+}>>;
 export type { TAsFormFieldBuilderProps };

package/src/components/AsFormFieldRepeater/AsFormFieldRepeater.d.ts

@@ -0,0 +1,10 @@
+import { ReactNode } from 'react';
+import { TAsFormFieldRepeaterProps } from './AsFormFieldRepeater.type';
+/**
+ * Adapter do manage repeated list elements on form
+ *
+ * @param {TAsFormFieldRepeaterProps} props Repeater properties to configure the elements repeater
+ * @returns {ReactElement}
+ */
+declare const AsFormFieldRepeater: ({ RepeaterComponent, addFieldName, removeFieldName, existingElements, initialElements, stateUpdater, formPrefix, RepeaterFooter, }: TAsFormFieldRepeaterProps) => ReactNode;
+export default AsFormFieldRepeater;

package/src/components/AsFormFieldRepeater/AsFormFieldRepeater.type.d.ts

@@ -0,0 +1,49 @@
+import { TFormGroupOnDataEventPayload, OneOf } from '@bolttech/form-engine-core';
+import { ElementType } from 'react';
+type TRepeaterProps = {
+    formIndex: string;
+    index: number;
+};
+type TRepeaterFooterProps = Pick<TRepeaterProps, 'formIndex'>;
+/**
+ * AsFormFieldRepeater props needed to build a repeater to build forms
+ * @property {ElementType<TRepeaterProps>} RepeaterComponent element to use as repeater
+ * @property {string} addFieldName field name button that will add an element on a position on a repeater
+ * @property {string} removeFieldName field name button that will remove an element on a position on a repeater
+ * @property {Record<string, unknown>[]} existingElements elements to restore a repeater list
+ * @property {number} initialElements elements to be pre-rendered when the form is presented
+ * @property {(payload: TFormGroupOnDataEventPayload<unknown>) => void} stateUpdater similar to onData for the group of form managed by the repeater
+ * @property {string} formPrefix prefix to use on the repeated forms ex: (person- will go person-1, person-2, ...)
+ * @property {ElementType<TRepeaterFooterProps>} RepeaterFooter component with a button that will add an element to the bottom of the list
+ * @see {@link TMapper}
+ * @see {@link IComponentSchema}
+ * @see {@link TFieldWrapper}
+ * @interface
+ * @example
+ * ```typescript
+ * import { AsFormFieldRepeater } from '@bolttech/form-engine';
+ *
+ * <AsFormFieldRepeater
+ *   RepeaterComponent={FormElement}
+ *   RepeaterFooter={FormElementFooter}
+ *   addFieldName="addForm"
+ *   removeFieldName="removeForm"
+ *   formPrefix="insured"
+ *   stateUpdater={(payload) => {
+ *     console.log(payload);
+ *   }}
+ * />
+ * ```
+ */
+type TAsFormFieldRepeaterProps = {
+    RepeaterComponent: ElementType<TRepeaterProps>;
+    addFieldName?: string;
+    removeFieldName?: string;
+    stateUpdater?: (payload: TFormGroupOnDataEventPayload<unknown>) => void;
+    formPrefix?: string;
+    RepeaterFooter: ElementType<TRepeaterFooterProps>;
+} & OneOf<{
+    existingElements?: Record<string, unknown>[];
+    initialElements?: number;
+}>;
+export type { TAsFormFieldRepeaterProps, TRepeaterProps, TRepeaterFooterProps };

package/src/components/FieldWrapper/FieldWrapper.d.ts

@@ -7,5 +7,5 @@ import { TFieldWrapperProps } from './FieldWrapper.type';
  * @param {TFieldWrapperProps} param FieldWrapper params
  * @returns {ReactElement}
  */
-declare const FieldWrapper: ({ name, formIndex, children, props, context, }: TFieldWrapperProps) => ReactElement;
+declare const FieldWrapper: ({ name, formIndex, children, props, context, mounted, mapper, visibility, component, }: TFieldWrapperProps) => ReactElement;
 export default FieldWrapper;

package/src/components/FieldWrapper/FieldWrapper.type.d.ts

@@ -1,7 +1,7 @@
-import { PropsWithChildren } from 'react';
+import { ElementType, PropsWithChildren } from 'react';
 import { TFieldWrapper } from '../../types';
 import { TFormContext } from '../../context/FormGroupContext';
-import { FormField } from '@bolttech/form-engine-core';
+import { FormField, TMapper } from '@bolttech/form-engine-core';
 /**
  * Represents the props for a field wrapper component, including children.
  *
@@ -13,6 +13,10 @@ import { FormField } from '@bolttech/form-engine-core';
 type TFieldWrapperProps = PropsWithChildren<TFieldWrapper & {
     props?: Record<string, unknown>;
     context?: TFormContext | null;
+    mounted?: boolean;
+    mapper?: TMapper<ElementType>;
+    component?: string;
+    visibility?: boolean;
 }>;
 /**
  * Represents the props for rendering a field wrapper component, including children.
@@ -24,5 +28,6 @@ type TFieldWrapperProps = PropsWithChildren<TFieldWrapper & {
 type TFieldWrapperComponentRenderProps = PropsWithChildren<{
     props: Record<string, unknown>;
     fieldInstance?: FormField;
+    mapper?: TMapper<ElementType>;
 }>;
 export type { TFieldWrapperProps, TFieldWrapperComponentRenderProps };

package/src/components/Form/Form.d.ts

@@ -1,9 +1,9 @@
-import { ReactElement } from 'react';
+import { PropsWithChildren, ReactElement } from 'react';
 import { TFormProps } from './Form.type';
 /**
  *
  * @param {TFormProps} param form properties initializor
  * @returns {ReactElement}
  */
-declare function Form<T>({ schema, index, initialValues, iVars, action, method, onSubmit, onFormMount, onData, onBlur, onChange, onApiResponse, onClick, onFocus, onKeyDown, onKeyUp, onMount, onValid, children, }: TFormProps<T>): ReactElement;
+declare function Form<T>({ schema, index, initialValues, iVars, action, method, config, onSubmit, onFormMount, onData, onBlur, onChange, onApiResponse, onClick, onFocus, onKeyDown, onKeyUp, onMount, onValid, stopEventsOnSubmit, children, }: PropsWithChildren<TFormProps<T>>): ReactElement;
 export default Form;

package/src/components/Form/Form.type.d.ts

@@ -1,11 +1,17 @@
 import { TFormEntry } from '@bolttech/form-engine-core';
-import { PropsWithChildren } from 'react';
 import { TEventsCallbackProps } from '../../types';
 /**
  * Form props, inherits the form instance constructor implementation except the mapper
  * along with all event callback register props shared with other implementations
  * @see {@link TFormEntry}
  * @see {@link TEventsCallbackProps}
+ * @interface
+ * @example
+ * ```typescript
+ * import { Form } from '@bolttech/form-engine';
+ *
+ * <Form index={'foo'} schema={schema} onData={console.log} />
+ * ```
  */
-type TFormProps<T> = PropsWithChildren<Omit<TFormEntry, 'mappers'> & TEventsCallbackProps<T>>;
+type TFormProps<T> = Omit<TFormEntry, 'mappers' | 'dataSubject$' | 'formValidSubject$' | 'submitSubject$'> & TEventsCallbackProps<T>;
 export type { TFormProps };

package/src/components/index.d.ts

@@ -1,3 +1,4 @@
 export { default as Form } from './Form/Form';
 export { default as AsFormField } from './AsFormField/AsFormField';
 export { default as AsFormFieldBuilder } from './AsFormFieldBuilder/AsFormFieldBuilder';
+export { default as AsFormFieldRepeater } from './AsFormFieldRepeater/AsFormFieldRepeater';

package/src/context/FormGroupContext.type.d.ts

@@ -1,4 +1,4 @@
-import { FormCore, TFormCore, TFormGroup, TMapper, TSchemaFormConfig } from '@bolttech/form-engine-core';
+import { FormCore, TFormEntry, TFormGroup, TFormValues, TMapper, TSchemaFormConfig } from '@bolttech/form-engine-core';
 import { ElementType } from 'react';
 /**
  * Represents the context for managing forms within a form group.
@@ -12,13 +12,33 @@ import { ElementType } from 'react';
  * @property {function(): void} printFormGroupInstance - Prints the form group instance.
  * @property {function(string[]): TFormValues} submitMultipleFormsByIndex - Submits multiple forms by their indexes and returns the form values.
  * @property {boolean} debugMode - Indicates if debug mode is active.
- * @property {boolean} active - Indicates if the form context is active.
+ * @property {boolean} active - Indicates if the form context is active (if the context provider is defined above).
+ *
+ * @example
+ * ```typescript
+ * import React from 'react';
+ * import { useFormGroupContext } from '@bolttech/form-engine';
+ *
+ * const FormComponent = (): React.ReactElement => {
+ *   const {
+ *     addForm,
+ *     removeForm,
+ *     getForm,
+ *     printFormGroupInstance,
+ *     submitMultipleFormsByIndex,
+ *     debugMode
+ *   } = useFormGroupContext();
+ *
+ *   // (...)
+ * };
+ * ```
+ *
  */
 type TFormContext = {
     addFormWithIndex: (index: string) => void;
     addForm: (payload: {
         key: string;
-        formInstance: TFormCore;
+        params: TFormEntry;
     }) => void;
     getForm: (payload: {
         key: string;
@@ -26,10 +46,10 @@ type TFormContext = {
     removeForm: (payload: {
         key: string;
     }) => void;
-    formGroupInstance: TFormGroup;
+    formGroupInstance: TFormGroup<ElementType>;
     mappers?: TMapper<ElementType>[];
     printFormGroupInstance: () => void;
-    submitMultipleFormsByIndex: (indexes: string[]) => void;
+    submitMultipleFormsByIndex: <T>(indexes: string[], callback?: (payload: TFormValues<T>) => void) => void;
     debugMode: boolean;
     active: boolean;
     config?: TSchemaFormConfig;
@@ -39,6 +59,16 @@ type TFormContext = {
  *
  * @property {TMapper<ElementType>[]} [mappers] - Optional array of mappers for elements.
  * @property {boolean} [debugMode] - Optional flag indicating if debug mode should be enabled.
+ * @property {TSchemaFormConfig} config - Optional config settings for debounce times and client logging
+ *
+ * * @example
+ * ```tsx
+ * import { FormGroupContextProvider } from '@bolttech/form-engine';
+ *
+ * <FormGroupContextProvider mappers={mappers} debugMode={true}>
+ *   {children}
+ * </FormGroupContextProvider>
+ * ```
  */
 type TFormContextProvider = {
     mappers?: TMapper<ElementType>[];

package/src/generators/formBuilder.d.ts

@@ -1,26 +1,9 @@
-import { ElementType, ReactNode } from 'react';
-import { IFormField, IComponentSchemaAsFormField } from '@bolttech/form-engine-core';
-/**
- * recursive function to transform form fields from a form instance into
- * a react component tree
- *
- * @param {Map<string,IFormField>} param.fields form instance field Map
- * @param {string} param.prevPath previous field path to track the tree branch creation
- * @param {string} param.formIndex form index to aid field identification onto the FieldWrapper
- * @returns {ReactNode}
- */
-declare const BuildTree: ({ fields, prevPath, formIndex, }: {
-    fields: Map<string, IFormField>;
-    prevPath?: string | undefined;
+import { ElementType } from 'react';
+import { TMapper, IComponentSchema } from '@bolttech/form-engine-core';
+declare const BuildSchemaAsFields: ({ components, mappers, formIndex, mountedForm, }: {
+    components?: IComponentSchema[];
+    mappers?: TMapper<ElementType>[];
     formIndex: string;
-}) => ReactNode;
-/**
- * function to transform AsFormField elements onto a JSON schema
- *
- * @param param.children ReactNode children elements
- * @returns {IComponentSchema[] | null | undefined}
- */
-declare const BuildAsFormFieldTree: ({ children, }: {
-    children?: ReactNode;
-}) => IComponentSchemaAsFormField<ElementType>[] | null | undefined;
-export { BuildTree, BuildAsFormFieldTree };
+    mountedForm: boolean;
+}) => import("react/jsx-runtime").JSX.Element[] | undefined;
+export { BuildSchemaAsFields };

package/src/helpers/helpers.d.ts

@@ -1,7 +1,7 @@
-import { TEvents } from '@bolttech/form-engine-core';
-import { TEventProps } from '../types';
+import { TEventProps, TEvents } from '@bolttech/form-engine-core';
 /**
  * events mapping to aid function callback binding
  */
 declare const eventsMapping: Partial<Record<TEvents, TEventProps>>;
-export { eventsMapping };
+declare const uniqueIdGen: () => string;
+export { eventsMapping, uniqueIdGen };

package/src/helpers/mapper.d.ts

@@ -2,6 +2,7 @@ import { TValueChangeEvent } from '@bolttech/form-engine-core';
 declare const defaultChangeEvent: TValueChangeEvent;
 declare const checkedChangeEvent: TValueChangeEvent;
 declare const valueChangeEvent: TValueChangeEvent;
+declare const numberInputChangeEvent: TValueChangeEvent;
 declare const datepickerChangeEvent: TValueChangeEvent;
 declare const dropdownChangeEvent: TValueChangeEvent;
-export { defaultChangeEvent, checkedChangeEvent, valueChangeEvent, datepickerChangeEvent, dropdownChangeEvent, };
+export { defaultChangeEvent, checkedChangeEvent, valueChangeEvent, numberInputChangeEvent, datepickerChangeEvent, dropdownChangeEvent, };

package/src/hooks/useForm/useForm.d.ts

@@ -1,7 +1,6 @@
-/// <reference types="react" />
 import { TUseFormProps } from './useForm.type';
 /**
  * Hook to register events callback functions
  */
-declare function useForm<T>({ id, onData, onSubmit, onFormMount, onValid, ...rest }: TUseFormProps<T>, deps?: React.DependencyList): void;
+declare function useForm<T>({ id, index, onData, onSubmit, onFormMount, onValid, iVars, initialValues, stopEventsOnSubmit, ...rest }: TUseFormProps<T>, deps?: React.DependencyList): void;
 export default useForm;

package/src/hooks/useForm/useForm.type.d.ts

@@ -1,12 +1,16 @@
+import { TFormEntry, OneOf } from '@bolttech/form-engine-core';
 import { TEventsCallbackProps } from '../../types';
 /**
  * Represents the properties for the useForm hook, including an ID and event callback properties.
  *
- * @property {string} id - The unique identifier for the form.
+ * @property {string} id - The unique identifier for the form. Deprecated, use 'index' instead
+ * @property {string} index - The unique identifier for the form.
  *
  * @see {@link TEventsCallbackProps}
+ * @interface
  */
-type TUseFormProps<T> = {
+type TUseFormProps<T> = Pick<TFormEntry, 'index' | 'initialValues' | 'iVars' | 'stopEventsOnSubmit'> & TEventsCallbackProps<T> & OneOf<{
     id: string;
-} & TEventsCallbackProps<T>;
+    index: string;
+}>;
 export type { TUseFormProps };

package/src/hooks/useFormGroup/useFormGroup.d.ts

@@ -1,7 +1,3 @@
-import { TFormGroupOnDataEventPayload, TFormGroupOnValidEventPayload } from '@bolttech/form-engine-core';
-declare const useFormGroup: ({ ids, onData, onValid, }: {
-    ids: string[];
-    onData?: ((payload: TFormGroupOnDataEventPayload<Record<string, unknown>>) => void) | undefined;
-    onValid?: ((payload: TFormGroupOnValidEventPayload) => void) | undefined;
-}, deps?: React.DependencyList) => void;
+import { TUseFormGroup } from './useFormGroup.type';
+declare function useFormGroup<T>({ ids, onData, onValid, onSubmit }: TUseFormGroup<T>, deps?: React.DependencyList): void;
 export default useFormGroup;

package/src/hooks/useFormGroup/useFormGroup.type.d.ts

@@ -0,0 +1,17 @@
+import { TFormGroupOnDataEventPayload, TFormGroupOnSubmitEventPayload, TFormGroupOnValidEventPayload } from '@bolttech/form-engine-core';
+/**
+ * Represents the properties for the useFormGroup hook, including a list of ID's and event callback properties.
+ *
+ * @property {string} ids - The unique identifier for the forms.
+ * @property {payload: TFormGroupOnDataEventPayload<T>} onData - callback event occurring when a value is changing via input or logic.
+ * @property {payload: TFormGroupOnValidEventPayload} onData - callback event occurring when validation status changes on the form.
+ * @property {payload: TFormGroupOnSubmitEventPayload<T>} onData - event occurring when form submission is trigger.
+ *
+ */
+type TUseFormGroup<T> = {
+    ids: string[];
+    onData?: (payload: TFormGroupOnDataEventPayload<T>) => void;
+    onValid?: (payload: TFormGroupOnValidEventPayload) => void;
+    onSubmit?: (payload: TFormGroupOnSubmitEventPayload<T>) => void;
+};
+export type { TUseFormGroup };

package/src/types/index.d.ts

@@ -1,4 +1,4 @@
-import { TFieldEvent, TFormValidationPayload, TFormValues } from '@bolttech/form-engine-core';
+import { TEventProps, TFieldEvent, TFormValidationPayload, TFormValues, TEventDataProps } from '@bolttech/form-engine-core';
 /**
  * Represents a field wrapper containing the name of the field and its index in the form.
  *
@@ -9,10 +9,6 @@ type TFieldWrapper = {
     name: string;
     formIndex: string;
 };
-/**
- * Represents the possible event properties for form fields callbacks.
- */
-type TEventProps = 'onChange' | 'onBlur' | 'onFocus' | 'onKeyDown' | 'onKeyUp' | 'onMount' | 'onApiResponse' | 'onClick';
 /**
  * Represents the content inside onData payload action.
  */
@@ -21,12 +17,16 @@ type TFormData<T> = {
     data: TFormValues<T>;
 };
 /**
- * Represents a mapping of event properties to their corresponding callback functions.
+ *
+ * @property {(payload: TFormValues<T>) => void} onFormMount - triggered when form mounts
+ * @property {(payload: TFormValues<T>) => void} onData - triggered when any field change value
+ * @property {(payload: TFormValues<T>) => void} onSubmit - triggered when submit button is pressed
+ * @property {(payload: TFormValues<T>) => void} onValid - triggered when form valid status changes
+ * @interface
+ *
  */
-type TEventsCallbackProps<T> = Partial<Record<TEventProps, ((payload: TFieldEvent) => void) | null | undefined>> & {
-    onFormMount?: (payload: TFormValues<T>) => void;
-    onData?: (payload: TFormData<T>) => void;
-    onSubmit?: (payload: TFormValues<T>) => void;
-    onValid?: (payload: TFormValidationPayload) => void;
-};
-export { TFieldWrapper, TEventProps, TEventsCallbackProps, TFormData };
+type TEventsCallbackProps<T> = Partial<Record<TEventProps, ((payload: TFieldEvent) => void) | null | undefined>> & Partial<Record<Extract<TEventDataProps, 'onFormMount' | 'onSubmit'>, (payload: TFormValues<T>) => void>> & Partial<Record<Extract<TEventDataProps, 'onData'>, (payload: {
+    field: string;
+    data: TFormValues<T>;
+}) => void>> & Partial<Record<Extract<TEventDataProps, 'onValid'>, (payload: TFormValidationPayload) => void>>;
+export { TFieldWrapper, TEventsCallbackProps, TFormData };