@openmrs/esm-form-engine-lib 2.1.0-pre.1565 → 2.1.0-pre.1577

package/src/components/sidebar/useCurrentActivePage.test.ts

@@ -0,0 +1,222 @@
+import { useCurrentActivePage } from './useCurrentActivePage';
+import { scrollIntoView } from '../../utils/form-helper';
+import { renderHook } from '@testing-library/react';
+import { act } from 'react';
+import { type FormPage } from '../../types';
+
+jest.mock('../../utils/form-helper', () => ({
+  scrollIntoView: jest.fn(),
+}));
+
+describe('useCurrentActivePage', () => {
+  const mockPages = [
+    { id: 'page-1', label: 'Page 1', isHidden: false },
+    { id: 'page-2', label: 'Page 2', isHidden: false },
+    {
+      id: 'page-3',
+      label: 'Page 3',
+      isHidden: false,
+    },
+    { id: 'page-4', label: 'Page 4', isHidden: false },
+    { id: 'page-5', label: 'Hidden Page', isHidden: true },
+  ] as Array<FormPage>;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    jest.useFakeTimers();
+  });
+
+  afterEach(() => {
+    jest.clearAllTimers();
+    jest.useRealTimers();
+  });
+
+  describe('Initialization', () => {
+    it('should initialize with default page when available and not hidden', () => {
+      const { result } = renderHook(() =>
+        useCurrentActivePage({
+          pages: mockPages,
+          defaultPage: 'Page 2',
+          activePages: [],
+          evaluatedPagesVisibility: true,
+        }),
+      );
+
+      expect(result.current.currentActivePage).toBe('page-2');
+      expect(scrollIntoView).toHaveBeenCalledWith('page-2');
+    });
+
+    it('should initialize with first visible page when default page is hidden', () => {
+      const { result } = renderHook(() =>
+        useCurrentActivePage({
+          pages: mockPages,
+          defaultPage: 'Hidden Page',
+          activePages: [],
+          evaluatedPagesVisibility: true,
+        }),
+      );
+
+      expect(result.current.currentActivePage).toBe('page-1');
+    });
+
+    it('should not initialize until evaluatedPagesVisibility is true', () => {
+      const { result, rerender } = renderHook(
+        ({ evaluated }) =>
+          useCurrentActivePage({
+            pages: mockPages,
+            defaultPage: 'Page 1',
+            activePages: [],
+            evaluatedPagesVisibility: evaluated,
+          }),
+        { initialProps: { evaluated: false } },
+      );
+
+      expect(result.current.currentActivePage).toBeNull();
+
+      rerender({ evaluated: true });
+      expect(result.current.currentActivePage).toBe('page-1');
+    });
+
+    it('should handle empty pages array', () => {
+      const { result } = renderHook(() =>
+        useCurrentActivePage({
+          pages: [],
+          defaultPage: 'Page 1',
+          activePages: [],
+          evaluatedPagesVisibility: true,
+        }),
+      );
+
+      expect(result.current.currentActivePage).toBeNull();
+      expect(scrollIntoView).not.toHaveBeenCalled();
+    });
+
+    it('should handle all hidden pages', () => {
+      const allHiddenPages = mockPages.map((page) => ({ ...page, isHidden: true }));
+      const { result } = renderHook(() =>
+        useCurrentActivePage({
+          pages: allHiddenPages,
+          defaultPage: 'Page 1',
+          activePages: [],
+          evaluatedPagesVisibility: true,
+        }),
+      );
+
+      expect(result.current.currentActivePage).toBeNull();
+    });
+  });
+
+  describe('Waypoint Interaction', () => {
+    it('should ignore Waypoint updates during initial phase', () => {
+      const { result } = renderHook(() =>
+        useCurrentActivePage({
+          pages: mockPages,
+          defaultPage: 'Page 1',
+          activePages: ['page-2'],
+          evaluatedPagesVisibility: true,
+        }),
+      );
+
+      expect(result.current.currentActivePage).toBe('page-1');
+
+      // Fast-forward halfway through the lock timeout
+      act(() => {
+        jest.advanceTimersByTime(250);
+      });
+
+      // Should still be on initial page
+      expect(result.current.currentActivePage).toBe('page-1');
+    });
+
+    it('should respect Waypoint updates after initial phase', () => {
+      const { result, rerender } = renderHook(() =>
+        useCurrentActivePage({
+          pages: mockPages,
+          defaultPage: 'Page 1',
+          activePages: ['page-2'],
+          evaluatedPagesVisibility: true,
+        }),
+      );
+
+      // Fast-forward past the lock timeout
+      act(() => {
+        jest.advanceTimersByTime(500);
+      });
+
+      // Update active pages
+      rerender({
+        pages: mockPages,
+        defaultPage: 'Page 1',
+        activePages: ['page-2'],
+        evaluatedPagesVisibility: true,
+      });
+
+      expect(result.current.currentActivePage).toBe('page-2');
+    });
+
+    it('should select topmost visible page when multiple pages are visible', () => {
+      const { result } = renderHook(() =>
+        useCurrentActivePage({
+          pages: mockPages,
+          defaultPage: 'Page 1',
+          activePages: ['page-2', 'page-1', 'page-3'],
+          evaluatedPagesVisibility: true,
+        }),
+      );
+
+      // Fast-forward past the lock timeout
+      act(() => {
+        jest.advanceTimersByTime(500);
+      });
+
+      expect(result.current.currentActivePage).toBe('page-1');
+    });
+  });
+
+  describe('User Interaction', () => {
+    it('should handle page requests and scroll to requested page', () => {
+      const { result } = renderHook(() =>
+        useCurrentActivePage({
+          pages: mockPages,
+          defaultPage: 'Page 1',
+          activePages: ['page-1'],
+          evaluatedPagesVisibility: true,
+        }),
+      );
+
+      act(() => {
+        result.current.requestPage('page-2');
+      });
+
+      expect(result.current.currentActivePage).toBe('page-2');
+      expect(scrollIntoView).toHaveBeenCalledWith('page-2');
+    });
+
+    it('should maintain requested page if visible, even when other pages become visible', () => {
+      const { result, rerender } = renderHook(() =>
+        useCurrentActivePage({
+          pages: mockPages,
+          defaultPage: 'Page 1',
+          activePages: ['page-2'],
+          evaluatedPagesVisibility: true,
+        }),
+      );
+
+      // Request a specific page
+      act(() => {
+        result.current.requestPage('page-2');
+      });
+
+      // Update active pages to include multiple pages
+      rerender({
+        pages: mockPages,
+        defaultPage: 'Page 1',
+        activePages: ['page-1', 'page-2', 'page-3'],
+        evaluatedPagesVisibility: true,
+      });
+
+      // Should maintain the requested page
+      expect(result.current.currentActivePage).toBe('page-2');
+    });
+  });
+});

package/src/components/sidebar/useCurrentActivePage.ts

@@ -0,0 +1,137 @@
+import { useState, useEffect, useCallback, useRef } from 'react';
+import { type FormPage } from '../../types';
+import { scrollIntoView } from '../../utils/form-helper';
+
+interface UseCurrentActivePageProps {
+  pages: FormPage[];
+  defaultPage: string;
+  activePages: string[];
+  evaluatedPagesVisibility: boolean;
+}
+
+interface UseCurrentActivePageResult {
+  currentActivePage: string | null;
+  requestPage: (pageId: string) => void;
+}
+
+/**
+ * Hook to manage the currently active page in a form sidebar.
+ *
+ * This implementation includes a locking mechanism to handle a specific limitation with Waypoint:
+ * When dealing with short forms where multiple pages are visible in the viewport simultaneously,
+ * Waypoint's initial visibility detection can be unpredictable. It might:
+ * 1. Report pages in a different order than their DOM position
+ * 2. Miss reporting some visible pages in the first few renders
+ * 3. Report visibility events before our desired initial scroll position is established
+ *
+ * The locking mechanism (isInitialPhaseRef) prevents these early Waypoint events from
+ * overriding our intended initial page selection. Without this lock:
+ * - The form might initially select the first page
+ * - But then immediately jump to a different page due to Waypoint's visibility events
+ * - This creates a jarring user experience where the form appears to "jump" during initialization
+ *
+ * The lock is released either:
+ * 1. Automatically after a timeout (allowing for initial render and scroll stabilization)
+ * 2. Immediately when the user explicitly interacts with the form
+ */
+export const useCurrentActivePage = ({
+  pages,
+  defaultPage,
+  activePages,
+  evaluatedPagesVisibility,
+}: UseCurrentActivePageProps): UseCurrentActivePageResult => {
+  const [currentActivePage, setCurrentActivePage] = useState<string | null>(null);
+  const [isInitialized, setIsInitialized] = useState(false);
+  const [requestedPage, setRequestedPage] = useState<string | null>(null);
+  const isInitialPhaseRef = useRef(true);
+
+  // Initialize the active page
+  useEffect(() => {
+    if (isInitialized || !evaluatedPagesVisibility) return;
+
+    const initializePage = () => {
+      // Try to find and set the default page
+      const defaultPageObject = pages.find(({ label }) => label === defaultPage);
+
+      if (defaultPageObject && !defaultPageObject.isHidden) {
+        setCurrentActivePage(defaultPageObject.id);
+        scrollIntoView(defaultPageObject.id);
+      } else {
+        // Fall back to first visible page
+        const firstVisiblePage = pages.find((page) => !page.isHidden);
+        if (firstVisiblePage) {
+          setCurrentActivePage(firstVisiblePage.id);
+        }
+      }
+    };
+
+    initializePage();
+    setIsInitialized(true);
+  }, [pages, defaultPage, evaluatedPagesVisibility, isInitialized]);
+
+  useEffect(() => {
+    let initialLockTimeout = null;
+    // Lock out Waypoint updates for 200ms to allow for:
+    // 1. Initial render completion
+    // 2. Scroll position establishment
+    // 3. Waypoint to complete its initial visibility detection
+    if (isInitialized) {
+      initialLockTimeout = setTimeout(() => {
+        isInitialPhaseRef.current = false;
+      }, 200);
+    }
+
+    // Cleanup
+    return () => {
+      if (initialLockTimeout) {
+        clearTimeout(initialLockTimeout);
+      }
+    };
+  }, [isInitialized]);
+
+  // Handle active pages updates from viewport visibility
+  useEffect(() => {
+    if (isInitialPhaseRef.current) return;
+
+    let clearRequestTimeout: NodeJS.Timeout | null = null;
+
+    // If there's a requested page and it's visible, keep it active
+    if (requestedPage && activePages.includes(requestedPage)) {
+      setCurrentActivePage(requestedPage);
+      clearRequestTimeout = setTimeout(() => {
+        setRequestedPage(null);
+      }, 100);
+      return;
+    }
+
+    // If there's no requested page, use the topmost visible page
+    if (!requestedPage && activePages.length > 0) {
+      const topVisiblePage = activePages.reduce((top, current) => {
+        const topIndex = pages.findIndex((page) => page.id === top);
+        const currentIndex = pages.findIndex((page) => page.id === current);
+        return topIndex < currentIndex ? top : current;
+      });
+
+      setCurrentActivePage(topVisiblePage);
+    }
+
+    return () => {
+      if (clearRequestTimeout) {
+        clearTimeout(clearRequestTimeout);
+      }
+    };
+  }, [activePages, requestedPage, pages]);
+
+  // Handle page requests
+  const requestPage = useCallback((pageId: string) => {
+    isInitialPhaseRef.current = false; // Release the lock on explicit user interaction
+    setRequestedPage(pageId);
+    setCurrentActivePage(pageId);
+    scrollIntoView(pageId);
+  }, []);
+
+  return {
+    currentActivePage,
+    requestPage,
+  };
+};

package/src/components/sidebar/usePageObserver.ts

@@ -0,0 +1,45 @@
+import { useState, useEffect } from 'react';
+import { type FormPage } from '../../types';
+import { pageObserver } from './page-observer';
+
+interface PageObserverState {
+  pages: FormPage[];
+  pagesWithErrors: string[];
+  activePages: string[];
+  evaluatedPagesVisibility: boolean;
+  hasMultiplePages: boolean | null;
+}
+
+export const usePageObserver = () => {
+  const [state, setState] = useState<PageObserverState>({
+    pages: [],
+    pagesWithErrors: [],
+    activePages: [],
+    evaluatedPagesVisibility: false,
+    hasMultiplePages: null,
+  });
+
+  useEffect(() => {
+    const subscriptions = [
+      pageObserver.getScrollablePagesObservable().subscribe((pages) => {
+        setState((prev) => ({ ...prev, pages, hasMultiplePages: pages.length > 1 }));
+      }),
+
+      pageObserver.getPagesWithErrorsObservable().subscribe((errors) => {
+        setState((prev) => ({ ...prev, pagesWithErrors: Array.from(errors) }));
+      }),
+
+      pageObserver.getActivePagesObservable().subscribe((activePages) => {
+        setState((prev) => ({ ...prev, activePages: Array.from(activePages) }));
+      }),
+
+      pageObserver.getEvaluatedPagesVisibilityObservable().subscribe((evaluated) => {
+        setState((prev) => ({ ...prev, evaluatedPagesVisibility: evaluated }));
+      }),
+    ];
+
+    return () => subscriptions.forEach((sub) => sub.unsubscribe());
+  }, []);
+
+  return state;
+};

package/src/form-engine.component.tsx

@@ -5,7 +5,6 @@ import { isEmpty, useFormJson } from '.';
 import FormProcessorFactory from './components/processor-factory/form-processor-factory.component';
 import Loader from './components/loaders/loader.component';
 import { usePatientData } from './hooks/usePatientData';
-import { useWorkspaceLayout } from './hooks/useWorkspaceLayout';
 import { FormFactoryProvider } from './provider/form-factory-provider';
 import classNames from 'classnames';
 import styles from './form-engine.scss';
@@ -17,6 +16,9 @@ import { init, teardown } from './lifecycle';
 import { reportError } from './utils/error-utils';
 import { moduleName } from './globals';
 import { useFormCollapse } from './hooks/useFormCollapse';
+import Sidebar from './components/sidebar/sidebar.component';
+import { useFormWorkspaceSize } from './hooks/useFormWorkspaceSize';
+import { usePageObserver } from './components/sidebar/usePageObserver';
 
 interface FormEngineProps {
   patientUUID: string;
@@ -33,9 +35,6 @@ interface FormEngineProps {
   markFormAsDirty?: (isDirty: boolean) => void;
 }
 
-// TODOs:
-// - Implement sidebar
-// - Conditionally render the button set
 const FormEngine = ({
   formJson,
   patientUUID,
@@ -56,18 +55,15 @@ const FormEngine = ({
   const sessionDate = useMemo(() => {
     return new Date();
   }, []);
-  const workspaceLayout = useWorkspaceLayout(ref);
+  const workspaceSize = useFormWorkspaceSize(ref);
   const { patient, isLoadingPatient } = usePatientData(patientUUID);
   const [isLoadingDependencies, setIsLoadingDependencies] = useState(false);
-  const [showSidebar, setShowSidebar] = useState(false);
   const [isSubmitting, setIsSubmitting] = useState(false);
   const [isFormDirty, setIsFormDirty] = useState(false);
   const sessionMode = !isEmpty(mode) ? mode : !isEmpty(encounterUUID) ? 'edit' : 'enter';
   const { isFormExpanded, hideFormCollapseToggle } = useFormCollapse(sessionMode);
+  const { hasMultiplePages } = usePageObserver();
 
-  // TODO: Updating this prop triggers a rerender of the entire form. This means whenever we scroll into a new page, the form is rerendered.
-  // Figure out a way to avoid this. Maybe use a ref with an observer instead of a state?
-  const [currentPage, setCurrentPage] = useState('');
   const {
     formJson: refinedFormJson,
     isLoading: isLoadingFormJson,
@@ -75,16 +71,24 @@ const FormEngine = ({
   } = useFormJson(formUUID, formJson, encounterUUID, formSessionIntent);
 
   const showPatientBanner = useMemo(() => {
-    return patient && workspaceLayout !== 'minimized' && mode !== 'embedded-view';
-  }, [patient, mode, workspaceLayout]);
+    return patient && workspaceSize === 'ultra-wide' && mode !== 'embedded-view';
+  }, [patient, mode, workspaceSize]);
 
   const showButtonSet = useMemo(() => {
-    // if (mode === 'embedded-view') {
-    //   return false;
-    // }
-    // return workspaceLayout === 'minimized' || (workspaceLayout === 'maximized' && scrollablePages.size <= 1);
-    return true;
-  }, [mode, workspaceLayout]);
+    if (mode === 'embedded-view' || isLoadingDependencies || hasMultiplePages === null) {
+      return false;
+    }
+
+    return ['narrow', 'wider'].includes(workspaceSize) || !hasMultiplePages;
+  }, [mode, workspaceSize, isLoadingDependencies, hasMultiplePages]);
+
+  const showSidebar = useMemo(() => {
+    if (mode === 'embedded-view' || isLoadingDependencies || hasMultiplePages === null) {
+      return false;
+    }
+
+    return ['extra-wide', 'ultra-wide'].includes(workspaceSize) && hasMultiplePages;
+  }, [workspaceSize, isLoadingDependencies, hasMultiplePages]);
 
   useEffect(() => {
     reportError(formError, t('errorLoadingFormSchema', 'Error loading form schema'));
@@ -116,7 +120,7 @@ const FormEngine = ({
           sessionMode={sessionMode}
           sessionDate={sessionDate}
           formJson={refinedFormJson}
-          workspaceLayout={workspaceLayout}
+          workspaceLayout={workspaceSize === 'ultra-wide' ? 'maximized' : 'minimized'}
           location={session?.sessionLocation}
           provider={session?.currentProvider}
           visit={visit}
@@ -130,8 +134,7 @@ const FormEngine = ({
             handleClose: () => {},
           }}
           hideFormCollapseToggle={hideFormCollapseToggle}
-          setIsFormDirty={setIsFormDirty}
-          setCurrentPage={setCurrentPage}>
+          setIsFormDirty={setIsFormDirty}>
           <div className={styles.formContainer}>
             {isLoadingDependencies && (
               <div className={styles.linearActivity}>
@@ -139,7 +142,16 @@ const FormEngine = ({
               </div>
             )}
             <div className={styles.formContent}>
-              {showSidebar && <div>{/* Side bar goes here */}</div>}
+              {showSidebar && (
+                <Sidebar
+                  isFormSubmitting={isSubmitting}
+                  sessionMode={mode}
+                  defaultPage={formJson.defaultPage}
+                  onCancel={onCancel}
+                  handleClose={handleClose}
+                  hideFormCollapseToggle={hideFormCollapseToggle}
+                />
+              )}
               <div className={styles.formContentInner}>
                 {showPatientBanner && <PatientBanner patient={patient} hideActionsOverflow />}
                 {refinedFormJson.markdown && (
@@ -160,7 +172,7 @@ const FormEngine = ({
                       onClick={() => {
                         onCancel && onCancel();
                         handleClose && handleClose();
-                        // TODO: hideFormCollapseToggle();
+                        hideFormCollapseToggle();
                       }}>
                       {mode === 'view' ? t('close', 'Close') : t('cancel', 'Cancel')}
                     </Button>

package/src/hooks/useEvaluateFormFieldExpressions.ts

@@ -13,6 +13,8 @@ export const useEvaluateFormFieldExpressions = (
 ) => {
   const { formFields, patient, sessionMode } = factoryContext;
   const [evaluatedFormJson, setEvaluatedFormJson] = useState(factoryContext.formJson);
+  const [evaluatedPagesVisibility, setEvaluatedPagesVisibility] = useState(false);
+
   const evaluatedFields = useMemo(() => {
     return formFields?.map((field) => {
       const fieldNode: FormNode = { value: field, type: 'field' };
@@ -127,9 +129,10 @@ export const useEvaluateFormFieldExpressions = (
       });
     });
     setEvaluatedFormJson(updateFormSectionReferences(factoryContext.formJson));
+    setEvaluatedPagesVisibility(true);
   }, [factoryContext.formJson, formFields]);
 
-  return { evaluatedFormJson, evaluatedFields };
+  return { evaluatedFormJson, evaluatedFields, evaluatedPagesVisibility };
 };
 
 // helpers

package/src/hooks/useFormStateHelpers.ts

@@ -1,7 +1,7 @@
 import { type Dispatch, useCallback } from 'react';
 import { type FormField, type FormSchema } from '../types';
 import { type Action } from '../components/renderer/form/state';
-import cloneDeep from 'lodash/cloneDeep';
+import { cloneDeep } from 'lodash-es';
 import { updateFormSectionReferences } from '../utils/common-utils';
 
 export function useFormStateHelpers(dispatch: Dispatch<Action>, formFields: FormField[]) {

package/src/hooks/useFormWorkspaceSize.test.ts

@@ -0,0 +1,117 @@
+import { renderHook } from '@testing-library/react';
+import { useFormWorkspaceSize } from './useFormWorkspaceSize';
+import { act } from 'react';
+
+// Mock the pxToRem utility
+jest.mock('../utils/common-utils', () => ({
+  pxToRem: (px: number) => px / 16, // Simulate px to rem conversion (1rem = 16px)
+}));
+
+// Mock ResizeObserver with callback ref
+let resizeCallback: (entries: any[]) => void;
+class ResizeObserverMock {
+  constructor(callback: (entries: any[]) => void) {
+    resizeCallback = callback;
+  }
+  observe = jest.fn();
+  unobserve = jest.fn();
+  disconnect = jest.fn();
+}
+
+global.ResizeObserver = ResizeObserverMock as any;
+
+describe('useFormWorkspaceSize', () => {
+  let ref: { current: HTMLDivElement | null };
+  let parentElement: HTMLDivElement;
+
+  beforeEach(() => {
+    // Create DOM elements
+    parentElement = document.createElement('div');
+    const element = document.createElement('div');
+    parentElement.appendChild(element);
+    // ref
+    ref = { current: element };
+
+    // Mock offsetWidth getter
+    Object.defineProperty(parentElement, 'offsetWidth', {
+      configurable: true,
+      value: 400,
+    });
+  });
+
+  afterEach(() => {
+    jest.clearAllMocks();
+  });
+
+  const setParentWidth = (width: number) => {
+    Object.defineProperty(parentElement, 'offsetWidth', {
+      configurable: true,
+      value: width,
+    });
+    if (typeof resizeCallback !== 'function') {
+      return;
+    }
+    // Trigger resize callback
+    act(() => {
+      resizeCallback([{ target: parentElement }]);
+    });
+  };
+
+  it('should return "narrow" for width <= 26.25rem (420px)', () => {
+    setParentWidth(420);
+    const { result } = renderHook(() => useFormWorkspaceSize(ref));
+    expect(result.current).toBe('narrow');
+  });
+
+  it('should return "wider" for width <= 32.25rem (516px)', () => {
+    setParentWidth(516);
+    const { result } = renderHook(() => useFormWorkspaceSize(ref));
+    expect(result.current).toBe('wider');
+  });
+
+  it('should return "extra-wide" for width <= 48.25rem (772px)', () => {
+    setParentWidth(772);
+    const { result } = renderHook(() => useFormWorkspaceSize(ref));
+    expect(result.current).toBe('extra-wide');
+  });
+
+  it('should return "ultra-wide" for width > 48.25rem (772px)', () => {
+    setParentWidth(1000);
+    const { result } = renderHook(() => useFormWorkspaceSize(ref));
+    expect(result.current).toBe('ultra-wide');
+  });
+
+  it('should handle null ref', () => {
+    const nullRef = { current: null };
+    const { result } = renderHook(() => useFormWorkspaceSize(nullRef));
+    expect(result.current).toBe('narrow');
+  });
+
+  it('should update size when container width changes', () => {
+    const { result } = renderHook(() => useFormWorkspaceSize(ref));
+
+    // Start with narrow
+    act(() => {
+      setParentWidth(400);
+    });
+    expect(result.current).toBe('narrow');
+
+    // Change to wider
+    act(() => {
+      setParentWidth(516);
+    });
+    expect(result.current).toBe('wider');
+
+    // Change to extra-wide
+    act(() => {
+      setParentWidth(772);
+    });
+    expect(result.current).toBe('extra-wide');
+
+    // Change to ultra-wide
+    act(() => {
+      setParentWidth(1000);
+    });
+    expect(result.current).toBe('ultra-wide');
+  });
+});