@abgov/react-components 6.6.1 → 6.7.0-alpha.1

package/index.mjs

@@ -3884,6 +3884,19 @@ const GoabFilterChip = ({
     }
   );
 };
+function dispatch(el, eventName, detail, opts) {
+  if (!el) {
+    console.error("dispatch element is null");
+    return;
+  }
+  el.dispatchEvent(
+    new CustomEvent(eventName, {
+      composed: true,
+      bubbles: opts == null ? void 0 : opts.bubbles,
+      detail
+    })
+  );
+}
 function relay(el, eventName, data, opts) {
   if (!el) {
     console.error("dispatch element is null");
@@ -3906,6 +3919,7 @@ class PublicFormController {
     __publicField(this, "state");
     __publicField(this, "_formData");
     __publicField(this, "_formRef");
+    __publicField(this, "_isCompleting", false);
     this.type = type;
   }
   // Obtain reference to the form element
@@ -4089,6 +4103,70 @@ class PublicFormController {
       operation: "remove"
     });
   }
+  /**
+   * Completes the form and triggers the onComplete callback.
+   * This method should be used when you want to complete a form without navigating to a summary page.
+   *
+   * @important Developers must validate the form before calling this method.
+   *
+   * @example
+   * // Validate first, then complete
+   * const [isValid] = this.validate(e, "firstName", [
+   *   requiredValidator("First name is required.")
+   * ]);
+   * if (isValid) {
+   *   this.complete();
+   * }
+   * @returns void
+   */
+  complete() {
+    if (!this._formRef) {
+      console.error("complete: form ref is not set");
+      return;
+    }
+    if (this._isCompleting) {
+      console.warn("complete: completion already in progress");
+      return;
+    }
+    this._isCompleting = true;
+    relay(this._formRef, "fieldset::submit", null, { bubbles: true });
+    this._isCompleting = false;
+  }
+  /**
+   * Completes a subform and returns control to the parent form.
+   * This method should be used when working with subforms that need to complete without a summary page.
+   *
+   * @important Developers must validate the subform before calling this method.
+   *
+   * @example
+   * // Validate first, then complete the subform
+   * const [isValid] = this._childFormController.validate(e, "fullName", [
+   *   requiredValidator("Please enter the dependent's full name.")
+   * ]);
+   * if (isValid) {
+   *   this._childFormController.completeSubform();
+   * }
+   * @returns void
+   */
+  completeSubform() {
+    if (!this._formRef) {
+      console.error("completeSubform: form ref is not set");
+      return;
+    }
+    if (this._isCompleting) {
+      console.warn("completeSubform: completion already in progress");
+      return;
+    }
+    const formRef = this._formRef;
+    this._isCompleting = true;
+    const stateChangeHandler = (e) => {
+      formRef.removeEventListener("_stateChange", stateChangeHandler);
+      dispatch(formRef, "_complete", {}, { bubbles: true });
+      this._isCompleting = false;
+    };
+    formRef.addEventListener("_stateChange", stateChangeHandler);
+    dispatch(formRef, "_continue", null, { bubbles: true });
+  }
   // removes any data collected that doesn't correspond with the final history path
   clean(data) {
     return data.history.reduce((acc, fieldsetId) => {
@@ -4192,6 +4270,12 @@ function usePublicFormController(type = "details") {
   const getStateList = useCallback(() => {
     return controllerRef.current.getStateList();
   }, []);
+  const complete = useCallback(() => {
+    controllerRef.current.complete();
+  }, []);
+  const completeSubform = useCallback(() => {
+    controllerRef.current.completeSubform();
+  }, []);
   return {
     state,
     init,
@@ -4201,6 +4285,8 @@ function usePublicFormController(type = "details") {
     validate,
     getStateValue,
     getStateList,
+    complete,
+    completeSubform,
     controller: controllerRef.current
   };
 }