@bolttech/form-engine-core 1.0.0-beta.7 → 1.0.0-beta.9

package/index.esm.js

@@ -2563,6 +2563,8 @@ class FormField {
   }
   /**
    * 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() {
     var _a;
@@ -2624,6 +2626,12 @@ class FormField {
       event: 'ON_PROPS'
     });
   }
+  /**
+   * 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) {
     if (Array.isArray(props)) {
       return props.filter(el => typeof el === 'string' && el.includes('${') ? false : true).map(el => FormField.filterProps(el));
@@ -2804,12 +2812,24 @@ class FormField {
       event: 'ON_API_FIELD_RESPONSE'
     });
   }
+  /**
+   * Retrieves the mounted status of the field.
+   *
+   * @returns {boolean} - the mounted status of the field.
+   */
   get mounted() {
     return this._mounted;
   }
+  /**
+   * 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) {
     if (typeof mountedStatus === 'undefined' || mountedStatus === this.mounted) return;
     this._mounted = mountedStatus;
+    this.initializeObservers();
     this.mountSubject$.next({
       key: this.name,
       status: this.mounted
@@ -2827,9 +2847,9 @@ class FormField {
     valueSubscription,
     propsSubscription
   }) {
+    this.mounted = true;
     this.subscribeValue(valueSubscription);
     this.subscribeState(propsSubscription);
-    this.mounted = true;
     this.valueSubject$.next(this.stateValue);
     this.propsSubject$.next(this.props);
     this.visibilitySubject$.next(this.visibility);
@@ -3125,7 +3145,7 @@ class FormCore {
    * @param {((payload: {field: string;data: TFormValues;}) => void) | undefined} [entry.onData] - A callback function to handle data emission.
    */
   constructor(entry) {
-    var _a, _b, _c, _d, _e, _f, _g, _h, _j;
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k;
     this.templateSubscription$ = new Subscription();
     this.mappers = new Map();
     this.queuedFieldVisibilityEvents = new Map();
@@ -3136,13 +3156,12 @@ class FormCore {
     this.fields = new Map();
     this.action = entry.action || ((_a = entry.schema) === null || _a === void 0 ? void 0 : _a.action);
     this.method = entry.method || ((_b = entry.schema) === null || _b === void 0 ? void 0 : _b.method);
-    this._iVars = entry.iVars || ((_c = entry.schema) === null || _c === void 0 ? void 0 : _c.iVars) || {};
     this.config = {
-      defaultAPIdebounceTimeMS: Number((_d = entry.config) === null || _d === void 0 ? void 0 : _d.defaultAPIdebounceTimeMS) ? Number((_e = entry.config) === null || _e === void 0 ? void 0 : _e.defaultAPIdebounceTimeMS) : DEFAULT_API_DEBOUNCE_TIME,
-      defaultStateRefreshTimeMS: Number((_f = entry.config) === null || _f === void 0 ? void 0 : _f.defaultStateRefreshTimeMS) ? Number((_g = entry.config) === null || _g === void 0 ? void 0 : _g.defaultStateRefreshTimeMS) : DEFAULT_STATE_REFRESH_TIME,
-      defaultLogVerbose: ((_h = entry.config) === null || _h === void 0 ? void 0 : _h.defaultLogVerbose) ? entry.config.defaultLogVerbose : DEFAULT_LOG_VERBOSE
+      defaultAPIdebounceTimeMS: Number((_c = entry.config) === null || _c === void 0 ? void 0 : _c.defaultAPIdebounceTimeMS) ? Number((_d = entry.config) === null || _d === void 0 ? void 0 : _d.defaultAPIdebounceTimeMS) : DEFAULT_API_DEBOUNCE_TIME,
+      defaultStateRefreshTimeMS: Number((_e = entry.config) === null || _e === void 0 ? void 0 : _e.defaultStateRefreshTimeMS) ? Number((_f = entry.config) === null || _f === void 0 ? void 0 : _f.defaultStateRefreshTimeMS) : DEFAULT_STATE_REFRESH_TIME,
+      defaultLogVerbose: ((_g = entry.config) === null || _g === void 0 ? void 0 : _g.defaultLogVerbose) ? entry.config.defaultLogVerbose : DEFAULT_LOG_VERBOSE
     };
-    (_j = entry.mappers) === null || _j === void 0 ? void 0 : _j.map(mapper => {
+    (_h = entry.mappers) === null || _h === void 0 ? void 0 : _h.map(mapper => {
       this.mappers.set(mapper.componentName, mapper);
     });
     this.schema && FormCore.checkIndexes(this.schema.components);
@@ -3153,44 +3172,46 @@ class FormCore {
     this.mountSubject$ = new Subject();
     this.formValidNotification$ = new Subject();
     this.subscribedTemplates = [];
-    // this.schema && this.serializeStructure(this.schema.components);
-    // this.schema && this.subscribeTemplates();
     this.templateSubscription$ = this.templateSubject$.subscribe(this.refreshTemplates.bind(this));
     this.mountSubject$.subscribe(this.mountActions.bind(this));
-    // this.templateSubject$.next({
-    //   scope: 'iVars',
-    //   event: 'ON_IVARS',
-    // });
-    /*
-    only emits event ON_FIELD_MOUNT if does not have initialValue, if has initialValue, initialValues class property setter will
-    emit the value along with ON_FIELD_MOUNT event
-    */
-    // const initialValues = entry.initialValues || entry.schema?.initialValues;
-    // this.fields.forEach((field, key) => {
-    //   if (
-    //     !initialValues ||
-    //     (initialValues && !Object.keys(initialValues).includes(key))
-    //   ) {
-    //     const propValue = field?.props?.[field?.valuePropName || ''];
-    //     !field?.value &&
-    //       field?.emitValue({
-    //         value:
-    //           typeof propValue === 'string' && !propValue.includes('${')
-    //             ? propValue
-    //             : '',
-    //         event: 'ON_FIELD_MOUNT',
-    //       });
-    //   }
-    //   this.refreshTemplates({ scope: 'fields', key, event: 'ON_FIELDS' });
-    // });
-    // this.setInitialValues(initialValues);
+    this.initialValues = entry.initialValues || ((_j = entry.schema) === null || _j === void 0 ? void 0 : _j.initialValues);
+    this.iVars = entry.iVars || ((_k = entry.schema) === null || _k === void 0 ? void 0 : _k.iVars) || {};
+  }
+  /**
+   * mock function to simulate form mount onto the adapter
+   */
+  generateFields() {
+    this.schema && this.serializeStructure(this.schema.components);
+    this.fields.forEach(field => {
+      field.mountField({
+        valueSubscription: () => null,
+        propsSubscription: () => null
+      });
+    });
   }
+  /**
+   * callback function passed to field instance to notify field adapter mount status
+   * once the field has all field instance properties set, this function will handle all
+   * field routines
+   *
+   * @param { string } entry.key field unique identifier
+   * @param { boolean } entry.status mount status notified from field
+   */
   mountActions({
-    status,
-    key
+    key,
+    status
   }) {
     var _a;
     if (status) {
+      const field = this.fields.get(key);
+      if (!field) {
+        /*
+        @TODO check a better way to handle nested fields unmounted by visiblity conditions from a parent
+        since they are dependent on adapter field recycling runtimes
+        */
+        this.config.defaultLogVerbose && console.log(`field ${key} was mounted but since it's parent has some visibility condition the field was already removed`);
+        return;
+      }
       this.subscribeTemplates();
       this.refreshTemplates({
         scope: 'fields',
@@ -3201,7 +3222,6 @@ class FormCore {
         event: 'ON_IVARS'
       });
       if (!this.queuedInitialValues.has(key)) {
-        const field = this.fields.get(key);
         const propValue = (_a = field === null || field === void 0 ? void 0 : field.props) === null || _a === void 0 ? void 0 : _a[(field === null || field === void 0 ? void 0 : field.valuePropName) || ''];
         !(field === null || field === void 0 ? void 0 : field.value) ? field.emitValue({
           value: typeof propValue === 'string' && !propValue.includes('${') ? propValue : '',
@@ -3213,6 +3233,11 @@ class FormCore {
       this.checkFieldEventQueues(key);
     }
   }
+  /**
+   * initialValues setter to handle field values set externally from the adapter
+   *
+   * @param { Record<string, unknown> | undefined } payload initialValues to set onto fields
+   */
   set initialValues(payload) {
     if (payload) {
       Object.keys(payload).forEach(key => {
@@ -3815,25 +3840,12 @@ class FormCore {
       submitEvent: this.submit.bind(this),
       visibility: fieldSchema.visibility
     }));
-    // this.subscribeTemplates();
-    // this.refreshTemplates({
-    //   scope: 'fields',
-    //   event: 'ON_FIELDS',
-    // });
-    // // if (!this.queuedInitialValues.has(fieldSchema.name)) {
-    // //   const field = this.fields.get(fieldSchema.name);
-    // //   const propValue = field?.props?.[field?.valuePropName || ''];
-    // //   !field?.value &&
-    // //     field?.emitValue({
-    // //       value:
-    // //         typeof propValue === 'string' && !propValue.includes('${')
-    // //           ? propValue
-    // //           : '',
-    // //       event: 'ON_FIELD_MOUNT',
-    // //     });
-    // // }
-    // this.checkFieldEventQueues(fieldSchema.name);
   }
+  /**
+   * function to be called from the adapter to remove a field when a field is removed from it
+   *
+   * @param {{ key: string }} entry.key
+   */
   removeField({
     key
   }) {
@@ -3980,6 +3992,12 @@ class FormCore {
       isValid: this.isValid
     };
   }
+  /**
+   * function to be called to events sent from the adapter
+   *
+   * @param {{callback: (payload: TFieldEvent) => void}} entry.callback callback function from the adapter
+   * @returns
+   */
   subscribeFieldEvent({
     callback
   }) {
@@ -3988,6 +4006,12 @@ class FormCore {
     });
     return sub;
   }
+  /**
+   * to be called from the adapter when the form mounts
+   *
+   * @param {(payload: TFormValues<T>) => void} callback
+   * @returns Subscription
+   */
   subscribeOnMount(callback) {
     const sub = this.mountSubject$.pipe(map(() => this.getFormValues())).subscribe({
       next: callback
@@ -4009,13 +4033,19 @@ class FormCore {
     });
     return sub;
   }
+  /**
+   * method to register a callback function to be called when the form is valid
+   *
+   * @param {(payload: TFormValues<T>) => void} callback callback function to call when the submit action occurs
+   */
   subscribeOnSubmit(callback) {
-    const sub = this.submitSubject$.pipe(map(() => this.getFormValues())).subscribe({
+    const sub = this.submitSubject$.subscribe({
       next: callback
     });
     return sub;
   }
   /**
+   * method to check whenever the validity status of the form changes, only emits on status change
    *
    * @param {(payload: TFormValidationPayload) => void} callback callback function to call onValid
    */
@@ -4043,8 +4073,10 @@ class FormCore {
     const values = this.getFormValues();
     this.submitSubject$.next(values);
   }
+  /**
+   * recycles all the Suscriptions, to be called from the adapter when the form leaves the page
+   */
   destroy() {
-    console.log('removing form');
     this.submitSubject$.unsubscribe();
     this.templateSubscription$.unsubscribe();
     this.fieldEventSubject$.unsubscribe();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bolttech/form-engine-core",
-  "version": "1.0.0-beta.7",
+  "version": "1.0.0-beta.9",
   "module": "./index.esm.js",
   "type": "module",
   "main": "./index.esm.js",

package/src/managers/field.d.ts

@@ -129,6 +129,8 @@ declare class FormField {
     });
     /**
      * 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;
     /**
@@ -143,6 +145,12 @@ declare class FormField {
      * @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.
@@ -209,7 +217,18 @@ declare class FormField {
      * @param {TApiResponse} response - The new API response data to be set.
      */
     set api(response: TApiResponse);
+    /**
+     * 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.

package/src/managers/form.d.ts

@@ -57,10 +57,27 @@ declare class FormCore {
      * @param {((payload: {field: string;data: TFormValues;}) => void) | undefined} [entry.onData] - A callback function to handle data emission.
      */
     constructor(entry: TFormEntry & Omit<IFormSchema, 'components'>);
-    mountActions({ status, key }: {
+    /**
+     * mock function to simulate form mount onto the adapter
+     */
+    generateFields(): void;
+    /**
+     * callback function passed to field instance to notify field adapter mount status
+     * once the field has all field instance properties set, this function will handle all
+     * field routines
+     *
+     * @param { string } entry.key field unique identifier
+     * @param { boolean } entry.status mount status notified from field
+     */
+    mountActions({ key, status }: {
         key: string;
         status: boolean;
     }): void;
+    /**
+     * initialValues setter to handle field values set externally from the adapter
+     *
+     * @param { Record<string, unknown> | undefined } payload initialValues to set onto fields
+     */
     set initialValues(payload: Record<string, unknown> | undefined);
     /**
      * Retrieves the internal variables (iVars) of the form.
@@ -237,6 +254,11 @@ declare class FormCore {
         fieldSchema: IComponentSchema;
         mapperElement?: TMapper<unknown>;
     }): void;
+    /**
+     * function to be called from the adapter to remove a field when a field is removed from it
+     *
+     * @param {{ key: string }} entry.key
+     */
     removeField({ key }: {
         key: string;
     }): void;
@@ -273,9 +295,21 @@ declare class FormCore {
      * @returns {TFormValues} The current form values.
      */
     getFormValues<T>(): TFormValues<T>;
+    /**
+     * function to be called to events sent from the adapter
+     *
+     * @param {{callback: (payload: TFieldEvent) => void}} entry.callback callback function from the adapter
+     * @returns
+     */
     subscribeFieldEvent({ callback, }: {
         callback: (payload: TFieldEvent) => void;
     }): Subscription;
+    /**
+     * to be called from the adapter when the form mounts
+     *
+     * @param {(payload: TFormValues<T>) => void} callback
+     * @returns Subscription
+     */
     subscribeOnMount<T>(callback: (payload: TFormValues<T>) => void): Subscription;
     /**
      *
@@ -285,8 +319,14 @@ declare class FormCore {
         field: string;
         data: TFormValues<T>;
     }) => void): Subscription;
+    /**
+     * method to register a callback function to be called when the form is valid
+     *
+     * @param {(payload: TFormValues<T>) => void} callback callback function to call when the submit action occurs
+     */
     subscribeOnSubmit<T>(callback: (payload: TFormValues<T>) => void): Subscription;
     /**
+     * method to check whenever the validity status of the form changes, only emits on status change
      *
      * @param {(payload: TFormValidationPayload) => void} callback callback function to call onValid
      */
@@ -295,6 +335,9 @@ declare class FormCore {
      * Submits the form by triggering form field events and invoking the onSubmit callback.
      */
     submit<T>(): void;
+    /**
+     * recycles all the Suscriptions, to be called from the adapter when the form leaves the page
+     */
     destroy(): void;
 }
 type TFormCore = FormCore;