From e60e80b294e20197205ac3bdb24503d3233a38e8 Mon Sep 17 00:00:00 2001
From: Twiine Enock <twiineenockfox@gmail.com>
Date: Tue, 3 Jun 2025 17:40:58 +0300
Subject: [PATCH 1/2] (feat): Enable external form Submission

---
 src/components/sidebar/sidebar.component.tsx | 52 +++++++-------
 src/form-engine.component.tsx                | 12 +++-
 src/hooks/useExternalSubmitListener.ts       | 34 +++++++++
 src/hooks/usePostSubmissionCallback.ts       | 74 ++++++++++++++++++++
 src/provider/form-factory-provider.tsx       |  4 ++
 5 files changed, 149 insertions(+), 27 deletions(-)
 create mode 100644 src/hooks/useExternalSubmitListener.ts
 create mode 100644 src/hooks/usePostSubmissionCallback.ts

diff --git a/src/components/sidebar/sidebar.component.tsx b/src/components/sidebar/sidebar.component.tsx
index 43452e8e..203dc9be 100644
--- a/src/components/sidebar/sidebar.component.tsx
+++ b/src/components/sidebar/sidebar.component.tsx
@@ -16,6 +16,7 @@ interface SidebarProps {
   onCancel: () => void;
   handleClose: () => void;
   hideFormCollapseToggle: () => void;
+  isSubmissionTriggeredExternally?: boolean;
 }
 
 const Sidebar: React.FC<SidebarProps> = ({
@@ -25,6 +26,7 @@ const Sidebar: React.FC<SidebarProps> = ({
   onCancel,
   handleClose,
   hideFormCollapseToggle,
+  isSubmissionTriggeredExternally,
 }) => {
   const { t } = useTranslation();
   const { pages, pagesWithErrors, activePages, evaluatedPagesVisibility } = usePageObserver();
@@ -53,32 +55,34 @@ const Sidebar: React.FC<SidebarProps> = ({
             requestPage={requestPage}
           />
         ))}
-      {sessionMode !== 'view' && <hr className={styles.divider} />}
+      {sessionMode !== 'view' && !isSubmissionTriggeredExternally && <hr className={styles.divider} />}
 
-      <div className={styles.sideNavActions}>
-        {sessionMode !== 'view' && (
-          <Button className={styles.saveButton} disabled={isFormSubmitting} type="submit" size={responsiveSize}>
-            {isFormSubmitting ? (
-              <InlineLoading description={t('submitting', 'Submitting') + '...'} />
-            ) : (
-              <span>{`${t('save', 'Save')}`}</span>
-            )}
+      {!isSubmissionTriggeredExternally && (
+        <div className={styles.sideNavActions}>
+          {sessionMode !== 'view' && (
+            <Button className={styles.saveButton} disabled={isFormSubmitting} type="submit" size={responsiveSize}>
+              {isFormSubmitting ? (
+                <InlineLoading description={t('submitting', 'Submitting') + '...'} />
+              ) : (
+                <span>{`${t('save', 'Save')}`}</span>
+              )}
+            </Button>
+          )}
+          <Button
+            className={classNames(styles.closeButton, {
+              [styles.topMargin]: sessionMode === 'view',
+            })}
+            kind="tertiary"
+            onClick={() => {
+              onCancel?.();
+              handleClose?.();
+              hideFormCollapseToggle();
+            }}
+            size={responsiveSize}>
+            {sessionMode === 'view' ? t('close', 'Close') : t('cancel', 'Cancel')}
           </Button>
-        )}
-        <Button
-          className={classNames(styles.closeButton, {
-            [styles.topMargin]: sessionMode === 'view',
-          })}
-          kind="tertiary"
-          onClick={() => {
-            onCancel?.();
-            handleClose?.();
-            hideFormCollapseToggle();
-          }}
-          size={responsiveSize}>
-          {sessionMode === 'view' ? t('close', 'Close') : t('cancel', 'Cancel')}
-        </Button>
-      </div>
+        </div>
+      )}
     </div>
   );
 };
diff --git a/src/form-engine.component.tsx b/src/form-engine.component.tsx
index 3fbf0a1c..9079bdcf 100644
--- a/src/form-engine.component.tsx
+++ b/src/form-engine.component.tsx
@@ -19,6 +19,7 @@ import MarkdownWrapper from './components/inputs/markdown/markdown-wrapper.compo
 import PatientBanner from './components/patient-banner/patient-banner.component';
 import Sidebar from './components/sidebar/sidebar.component';
 import styles from './form-engine.scss';
+import { useExternalSubmitListener } from './hooks/useExternalSubmitListener';
 
 interface FormEngineProps {
   patientUUID: string;
@@ -33,6 +34,7 @@ interface FormEngineProps {
   handleClose?: () => void;
   handleConfirmQuestionDeletion?: (question: Readonly<FormField>) => Promise<void>;
   markFormAsDirty?: (isDirty: boolean) => void;
+  isSubmissionTriggeredExternally?: boolean;
 }
 
 const FormEngine = ({
@@ -48,6 +50,7 @@ const FormEngine = ({
   handleClose,
   handleConfirmQuestionDeletion,
   markFormAsDirty,
+  isSubmissionTriggeredExternally = false,
 }: FormEngineProps) => {
   const { t } = useTranslation();
   const session = useSession();
@@ -107,11 +110,13 @@ const FormEngine = ({
     markFormAsDirty?.(isFormDirty);
   }, [isFormDirty]);
 
-  const handleSubmit = useCallback((e: React.FormEvent<HTMLFormElement>) => {
-    e.preventDefault();
+  const handleSubmit = useCallback((e?: React.FormEvent<HTMLFormElement>) => {
+    e?.preventDefault();
     setIsSubmitting(true);
   }, []);
 
+  useExternalSubmitListener(handleSubmit);
+
   return (
     <form ref={ref} noValidate className={classNames('cds--form', styles.form)} onSubmit={handleSubmit}>
       {isLoadingPatient || isLoadingFormJson ? (
@@ -152,6 +157,7 @@ const FormEngine = ({
                   onCancel={onCancel}
                   handleClose={handleClose}
                   hideFormCollapseToggle={hideFormCollapseToggle}
+                  isSubmissionTriggeredExternally={isSubmissionTriggeredExternally}
                 />
               )}
               <div className={styles.formContentInner}>
@@ -167,7 +173,7 @@ const FormEngine = ({
                     setIsLoadingFormDependencies={setIsLoadingDependencies}
                   />
                 </div>
-                {showBottomButtonSet && (
+                {showBottomButtonSet && !isSubmissionTriggeredExternally && (
                   <ButtonSet className={styles.minifiedButtons}>
                     <Button
                       kind="secondary"
diff --git a/src/hooks/useExternalSubmitListener.ts b/src/hooks/useExternalSubmitListener.ts
new file mode 100644
index 00000000..8868e96a
--- /dev/null
+++ b/src/hooks/useExternalSubmitListener.ts
@@ -0,0 +1,34 @@
+import { useEffect } from 'react';
+
+/**
+ * useExternalSubmitListener
+ *
+ * A custom React hook that enables triggering form submission externally via a global custom event.
+ *
+ * This is particularly useful in environments where the FormEngine
+ * is embedded inside another application or UI shell, and you need to trigger submission from outside
+ * the form (e.g., from a toolbar button, modal footer, or iframe parent).
+ *
+ * Registers a global `window` event listener that listens for a specific custom event.
+ * When the custom event is dispatched, the provided `submitFn` is invoked.
+ * Ensures proper cleanup on unmount to avoid memory leaks or duplicate submissions.
+ *
+ * @param submitFn - A function that triggers the form submission. This will be called when the event is received.
+ * @param eventName - (Optional) The name of the custom event to listen for. Defaults to `'triger-form-engine-submit'`.
+ *
+ * @example
+ * // Inside your form component
+ * useExternalSubmitListener(() => handleSubmit());
+ *
+ * // Somewhere else (e.g., external button or shell app)
+ * window.dispatchEvent(new Event('triger-form-engine-submit'));
+ */
+export function useExternalSubmitListener(submitFn: () => void, eventName = 'triger-form-engine-submit') {
+  useEffect(() => {
+    const handleSubmitWrapper = () => submitFn();
+    window.addEventListener(eventName, handleSubmitWrapper);
+    return () => {
+      window.removeEventListener(eventName, handleSubmitWrapper);
+    };
+  }, [submitFn, eventName]);
+}
diff --git a/src/hooks/usePostSubmissionCallback.ts b/src/hooks/usePostSubmissionCallback.ts
new file mode 100644
index 00000000..3c2ebbee
--- /dev/null
+++ b/src/hooks/usePostSubmissionCallback.ts
@@ -0,0 +1,74 @@
+import { useEffect, useRef, useState } from 'react';
+
+type Action = () => void;
+
+/**
+ * usePostSubmissionCallback
+ *
+ * A custom React hook that enables deferring an action until after a form is submitted.
+ *
+ * This hook listens for a custom `form-submission-complete` event (dispatched on the `window`)
+ * and allows registering a one-time callback (action) to be executed once the form has been submitted.
+ *
+ * If the form has **already been submitted** when the event is received, the action is executed immediately.
+ * If the form has **not yet been submitted**, the action is stored and executed only once `setIsFormSubmitted(true)` is called.
+ *
+ * This is useful when you want to register a follow-up action (like redirecting or showing a notification),
+ * but you need to ensure the form has finished submitting before it runs.
+ *
+ * @returns {{
+ *   setIsFormSubmitted: (submitted: boolean) => void;
+ * }} - Returns a setter to mark the form as submitted.
+ *
+ * @example
+ * const { setIsFormSubmitted } = usePostSubmissionCallback();
+ *
+ * // Later, after form submission:
+ * setIsFormSubmitted(true);
+ *
+ * // Somewhere else in the app, dispatch a custom event:
+ * window.dispatchEvent(
+ *   new CustomEvent('form-submission-complete', {
+ *     detail: { action: () => console.log('Post-submission logic executed') }
+ *   })
+ * );
+ */
+export function usePostSubmissionCallback() {
+  const [isFormSubmitted, setIsFormSubmitted] = useState(false);
+
+  const pendingActionRef = useRef<Action | null>(null);
+  const hasRunRef = useRef(false);
+
+  // Listen for the 'form-submission-complete' event and capture or invoke the action
+  useEffect(() => {
+    const handler = (event: CustomEvent) => {
+      const action = event.detail?.action;
+
+      if (typeof action === 'function') {
+        if (isFormSubmitted && !hasRunRef.current) {
+          hasRunRef.current = true;
+          action();
+        } else {
+          pendingActionRef.current = action;
+        }
+      }
+    };
+
+    window.addEventListener('form-submission-complete', handler as EventListener);
+
+    return () => {
+      window.removeEventListener('form-submission-complete', handler as EventListener);
+    };
+  }, [isFormSubmitted]);
+
+  // Execute any pending action once form is marked as submitted
+  useEffect(() => {
+    if (isFormSubmitted && pendingActionRef.current && !hasRunRef.current) {
+      hasRunRef.current = true;
+      pendingActionRef.current();
+      pendingActionRef.current = null;
+    }
+  }, [isFormSubmitted]);
+
+  return { setIsFormSubmitted };
+}
diff --git a/src/provider/form-factory-provider.tsx b/src/provider/form-factory-provider.tsx
index 019387f8..21d3703a 100644
--- a/src/provider/form-factory-provider.tsx
+++ b/src/provider/form-factory-provider.tsx
@@ -14,6 +14,7 @@ import { type FormContextProps } from './form-provider';
 import { processPostSubmissionActions, validateForm } from './form-factory-helper';
 import { useTranslation } from 'react-i18next';
 import { usePostSubmissionActions } from '../hooks/usePostSubmissionActions';
+import { usePostSubmissionCallback } from '../hooks/usePostSubmissionCallback';
 
 interface FormFactoryProviderContextProps {
   patient: fhir.Patient;
@@ -95,6 +96,8 @@ export const FormFactoryProvider: React.FC<FormFactoryProviderProps> = ({
     EncounterFormProcessor: EncounterFormProcessor,
   });
 
+  const { setIsFormSubmitted } = usePostSubmissionCallback();
+
   useEffect(() => {
     if (isSubmitting) {
       // TODO: find a dynamic way of managing the form processing order
@@ -123,6 +126,7 @@ export const FormFactoryProvider: React.FC<FormFactoryProviderProps> = ({
             if (postSubmissionHandlers) {
               await processPostSubmissionActions(postSubmissionHandlers, results, patient, sessionMode, t);
             }
+            setIsFormSubmitted(true);
             hideFormCollapseToggle();
             if (onSubmit) {
               onSubmit(results);

From 3afe8444db6b9e4cd5f87ab3cbf0954ca0c5dc20 Mon Sep 17 00:00:00 2001
From: Twiine Enock <twiineenockfox@gmail.com>
Date: Wed, 18 Jun 2025 23:31:18 +0300
Subject: [PATCH 2/2] feat: validate Active formUuid and patientUuid

---
 src/components/sidebar/sidebar.component.tsx |  8 +--
 src/form-engine.component.tsx                |  8 +--
 src/hooks/useExternalSubmitListener.ts       | 53 ++++++++++----
 src/hooks/usePostSubmissionCallback.ts       | 74 --------------------
 src/provider/form-factory-provider.tsx       |  4 --
 5 files changed, 46 insertions(+), 101 deletions(-)
 delete mode 100644 src/hooks/usePostSubmissionCallback.ts

diff --git a/src/components/sidebar/sidebar.component.tsx b/src/components/sidebar/sidebar.component.tsx
index 203dc9be..8fd6a1d7 100644
--- a/src/components/sidebar/sidebar.component.tsx
+++ b/src/components/sidebar/sidebar.component.tsx
@@ -16,7 +16,7 @@ interface SidebarProps {
   onCancel: () => void;
   handleClose: () => void;
   hideFormCollapseToggle: () => void;
-  isSubmissionTriggeredExternally?: boolean;
+  hideControls?: boolean;
 }
 
 const Sidebar: React.FC<SidebarProps> = ({
@@ -26,7 +26,7 @@ const Sidebar: React.FC<SidebarProps> = ({
   onCancel,
   handleClose,
   hideFormCollapseToggle,
-  isSubmissionTriggeredExternally,
+  hideControls,
 }) => {
   const { t } = useTranslation();
   const { pages, pagesWithErrors, activePages, evaluatedPagesVisibility } = usePageObserver();
@@ -55,9 +55,9 @@ const Sidebar: React.FC<SidebarProps> = ({
             requestPage={requestPage}
           />
         ))}
-      {sessionMode !== 'view' && !isSubmissionTriggeredExternally && <hr className={styles.divider} />}
+      {sessionMode !== 'view' && !hideControls && <hr className={styles.divider} />}
 
-      {!isSubmissionTriggeredExternally && (
+      {!hideControls && (
         <div className={styles.sideNavActions}>
           {sessionMode !== 'view' && (
             <Button className={styles.saveButton} disabled={isFormSubmitting} type="submit" size={responsiveSize}>
diff --git a/src/form-engine.component.tsx b/src/form-engine.component.tsx
index 9079bdcf..cc9bc72c 100644
--- a/src/form-engine.component.tsx
+++ b/src/form-engine.component.tsx
@@ -34,7 +34,7 @@ interface FormEngineProps {
   handleClose?: () => void;
   handleConfirmQuestionDeletion?: (question: Readonly<FormField>) => Promise<void>;
   markFormAsDirty?: (isDirty: boolean) => void;
-  isSubmissionTriggeredExternally?: boolean;
+  hideControls?: boolean;
 }
 
 const FormEngine = ({
@@ -50,7 +50,7 @@ const FormEngine = ({
   handleClose,
   handleConfirmQuestionDeletion,
   markFormAsDirty,
-  isSubmissionTriggeredExternally = false,
+  hideControls = false,
 }: FormEngineProps) => {
   const { t } = useTranslation();
   const session = useSession();
@@ -157,7 +157,7 @@ const FormEngine = ({
                   onCancel={onCancel}
                   handleClose={handleClose}
                   hideFormCollapseToggle={hideFormCollapseToggle}
-                  isSubmissionTriggeredExternally={isSubmissionTriggeredExternally}
+                  hideControls={hideControls}
                 />
               )}
               <div className={styles.formContentInner}>
@@ -173,7 +173,7 @@ const FormEngine = ({
                     setIsLoadingFormDependencies={setIsLoadingDependencies}
                   />
                 </div>
-                {showBottomButtonSet && !isSubmissionTriggeredExternally && (
+                {showBottomButtonSet && !hideControls && (
                   <ButtonSet className={styles.minifiedButtons}>
                     <Button
                       kind="secondary"
diff --git a/src/hooks/useExternalSubmitListener.ts b/src/hooks/useExternalSubmitListener.ts
index 8868e96a..4fe285c4 100644
--- a/src/hooks/useExternalSubmitListener.ts
+++ b/src/hooks/useExternalSubmitListener.ts
@@ -1,4 +1,23 @@
 import { useEffect } from 'react';
+import { createGlobalStore, getGlobalStore, useStore } from '@openmrs/esm-framework';
+
+interface SubmitEventDetail {
+  formUuid: string;
+  patientUuid: string;
+  action: string;
+}
+
+type FormSession = 'formUuid' | 'patientUuid';
+
+type InternalSubmitHandler = () => void;
+
+//State that holds the current formUuid and patientUuid.
+createGlobalStore<Record<FormSession, string>>('rfe-FormSession', {
+  formUuid: '',
+  patientUuid: '',
+});
+
+const formSessionStore = getGlobalStore('rfe-FormSession');
 
 /**
  * useExternalSubmitListener
@@ -9,26 +28,30 @@ import { useEffect } from 'react';
  * is embedded inside another application or UI shell, and you need to trigger submission from outside
  * the form (e.g., from a toolbar button, modal footer, or iframe parent).
  *
- * Registers a global `window` event listener that listens for a specific custom event.
- * When the custom event is dispatched, the provided `submitFn` is invoked.
- * Ensures proper cleanup on unmount to avoid memory leaks or duplicate submissions.
- *
- * @param submitFn - A function that triggers the form submission. This will be called when the event is received.
- * @param eventName - (Optional) The name of the custom event to listen for. Defaults to `'triger-form-engine-submit'`.
+ * The supplied `internalSubmitHandler` fires **only** when the event's `formUuid` and
+ * `patientUuid` match the values held in the global FormSession store.
  *
+ * @param internalSubmitHandler - A function that triggers the form submission. This will be called when the event is received. *
  * @example
- * // Inside your form component
  * useExternalSubmitListener(() => handleSubmit());
- *
- * // Somewhere else (e.g., external button or shell app)
- * window.dispatchEvent(new Event('triger-form-engine-submit'));
  */
-export function useExternalSubmitListener(submitFn: () => void, eventName = 'triger-form-engine-submit') {
+
+export function useExternalSubmitListener(internalSubmitHandler: InternalSubmitHandler) {
+  const { formUuid, patientUuid } = useStore(formSessionStore) as { formUuid: string; patientUuid: string };
+
   useEffect(() => {
-    const handleSubmitWrapper = () => submitFn();
-    window.addEventListener(eventName, handleSubmitWrapper);
+    const handleSubmitWrapper = (event: Event) => {
+      const customEvent = event as CustomEvent<SubmitEventDetail>;
+      const detail = customEvent.detail;
+
+      if (detail?.formUuid === formUuid && detail?.patientUuid === patientUuid) {
+        internalSubmitHandler();
+      }
+    };
+
+    window.addEventListener('rfe-form-submit-action', handleSubmitWrapper);
     return () => {
-      window.removeEventListener(eventName, handleSubmitWrapper);
+      window.removeEventListener('rfe-form-submit-action', handleSubmitWrapper);
     };
-  }, [submitFn, eventName]);
+  }, [internalSubmitHandler]);
 }
diff --git a/src/hooks/usePostSubmissionCallback.ts b/src/hooks/usePostSubmissionCallback.ts
deleted file mode 100644
index 3c2ebbee..00000000
--- a/src/hooks/usePostSubmissionCallback.ts
+++ /dev/null
@@ -1,74 +0,0 @@
-import { useEffect, useRef, useState } from 'react';
-
-type Action = () => void;
-
-/**
- * usePostSubmissionCallback
- *
- * A custom React hook that enables deferring an action until after a form is submitted.
- *
- * This hook listens for a custom `form-submission-complete` event (dispatched on the `window`)
- * and allows registering a one-time callback (action) to be executed once the form has been submitted.
- *
- * If the form has **already been submitted** when the event is received, the action is executed immediately.
- * If the form has **not yet been submitted**, the action is stored and executed only once `setIsFormSubmitted(true)` is called.
- *
- * This is useful when you want to register a follow-up action (like redirecting or showing a notification),
- * but you need to ensure the form has finished submitting before it runs.
- *
- * @returns {{
- *   setIsFormSubmitted: (submitted: boolean) => void;
- * }} - Returns a setter to mark the form as submitted.
- *
- * @example
- * const { setIsFormSubmitted } = usePostSubmissionCallback();
- *
- * // Later, after form submission:
- * setIsFormSubmitted(true);
- *
- * // Somewhere else in the app, dispatch a custom event:
- * window.dispatchEvent(
- *   new CustomEvent('form-submission-complete', {
- *     detail: { action: () => console.log('Post-submission logic executed') }
- *   })
- * );
- */
-export function usePostSubmissionCallback() {
-  const [isFormSubmitted, setIsFormSubmitted] = useState(false);
-
-  const pendingActionRef = useRef<Action | null>(null);
-  const hasRunRef = useRef(false);
-
-  // Listen for the 'form-submission-complete' event and capture or invoke the action
-  useEffect(() => {
-    const handler = (event: CustomEvent) => {
-      const action = event.detail?.action;
-
-      if (typeof action === 'function') {
-        if (isFormSubmitted && !hasRunRef.current) {
-          hasRunRef.current = true;
-          action();
-        } else {
-          pendingActionRef.current = action;
-        }
-      }
-    };
-
-    window.addEventListener('form-submission-complete', handler as EventListener);
-
-    return () => {
-      window.removeEventListener('form-submission-complete', handler as EventListener);
-    };
-  }, [isFormSubmitted]);
-
-  // Execute any pending action once form is marked as submitted
-  useEffect(() => {
-    if (isFormSubmitted && pendingActionRef.current && !hasRunRef.current) {
-      hasRunRef.current = true;
-      pendingActionRef.current();
-      pendingActionRef.current = null;
-    }
-  }, [isFormSubmitted]);
-
-  return { setIsFormSubmitted };
-}
diff --git a/src/provider/form-factory-provider.tsx b/src/provider/form-factory-provider.tsx
index 21d3703a..019387f8 100644
--- a/src/provider/form-factory-provider.tsx
+++ b/src/provider/form-factory-provider.tsx
@@ -14,7 +14,6 @@ import { type FormContextProps } from './form-provider';
 import { processPostSubmissionActions, validateForm } from './form-factory-helper';
 import { useTranslation } from 'react-i18next';
 import { usePostSubmissionActions } from '../hooks/usePostSubmissionActions';
-import { usePostSubmissionCallback } from '../hooks/usePostSubmissionCallback';
 
 interface FormFactoryProviderContextProps {
   patient: fhir.Patient;
@@ -96,8 +95,6 @@ export const FormFactoryProvider: React.FC<FormFactoryProviderProps> = ({
     EncounterFormProcessor: EncounterFormProcessor,
   });
 
-  const { setIsFormSubmitted } = usePostSubmissionCallback();
-
   useEffect(() => {
     if (isSubmitting) {
       // TODO: find a dynamic way of managing the form processing order
@@ -126,7 +123,6 @@ export const FormFactoryProvider: React.FC<FormFactoryProviderProps> = ({
             if (postSubmissionHandlers) {
               await processPostSubmissionActions(postSubmissionHandlers, results, patient, sessionMode, t);
             }
-            setIsFormSubmitted(true);
             hideFormCollapseToggle();
             if (onSubmit) {
               onSubmit(results);