@bathiran212/esm-patient-chart-app 7.0.0

package/src/patient-chart/chart-review/dashboard-view.component.tsx

@@ -0,0 +1,85 @@
+import React, { useEffect, useMemo, useState } from 'react';
+import classNames from 'classnames';
+import { useMatch } from 'react-router-dom';
+import { useTranslation } from 'react-i18next';
+import { launchWorkspace2, Extension, ExtensionSlot, useExtensionSlotMeta } from '@openmrs/esm-framework';
+import { launchStartVisitPrompt } from '@openmrs/esm-patient-common-lib';
+import { dashboardPath } from '../../constants';
+import styles from './dashboard-view.scss';
+
+/**
+ * The layout mode dictates the width occuppied by the chart dashboard widgets.
+ * - In 'contained' mode, the dashboard widgets are displayed in a centered
+ * container with a fixed width (max-width: 60rem).
+ * - In 'anchored' mode, the dashboard widgets expand to occupy the entire width
+ * of the chart dashboard
+ */
+export type LayoutMode = 'contained' | 'anchored';
+
+export interface DashboardConfig {
+  slot: string;
+  title: string | (() => string | Promise<string>);
+  path: string;
+  hideDashboardTitle?: boolean;
+  layoutMode?: LayoutMode;
+  moduleName: string;
+}
+
+interface DashboardViewProps {
+  dashboard: DashboardConfig;
+  patientUuid: string;
+  patient: fhir.Patient;
+}
+
+export function DashboardView({ dashboard, patientUuid, patient }: DashboardViewProps) {
+  const widgetMetas = useExtensionSlotMeta(dashboard.slot);
+  const { t } = useTranslation();
+  const {
+    params: { view },
+  } = useMatch(dashboardPath);
+
+  const state = useMemo(
+    () => ({
+      basePath: view,
+      patient,
+      patientUuid,
+      launchWorkspace2,
+      launchStartVisitPrompt,
+      launchAppointmentForm: () => {
+        launchWorkspace2('patient-chart-appointments-form-workspace', {}, {}, { patientUuid, patient });
+      },
+    }),
+    [patient, patientUuid, view],
+  );
+
+  const [resolvedTitle, setResolvedTitle] = useState<string | undefined>();
+
+  useEffect(() => {
+    if (typeof dashboard?.title === 'function') {
+      Promise.resolve(dashboard.title()).then(setResolvedTitle);
+    } else if (typeof dashboard?.title === 'string') {
+      setResolvedTitle(dashboard.title);
+    } else {
+      setResolvedTitle(undefined);
+    }
+  }, [dashboard]);
+
+  return (
+    <>
+      <ExtensionSlot state={state} name="top-of-all-patient-dashboards-slot" />
+      {!dashboard.hideDashboardTitle && resolvedTitle && <h1 className={styles.dashboardTitle}>{t(resolvedTitle)}</h1>}
+      <div className={styles.dashboardContainer}>
+        <ExtensionSlot key={dashboard.slot} name={dashboard.slot} className={styles.dashboard}>
+          {(extension) => {
+            const { fullWidth = false } = widgetMetas[extension.id] || {};
+            return (
+              <div className={classNames(styles.extension, fullWidth && styles.fullWidth)}>
+                <Extension state={state} className={styles.extensionWrapper} />
+              </div>
+            );
+          }}
+        </ExtensionSlot>
+      </div>
+    </>
+  );
+}

package/src/patient-chart/chart-review/dashboard-view.scss

@@ -0,0 +1,84 @@
+@use '@carbon/layout';
+@use '@carbon/type';
+
+.dashboardTitle {
+  @include type.type-style('heading-03');
+  margin: layout.$spacing-05 0 layout.$spacing-05 1.3125rem;
+}
+
+.dashboard {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  grid-auto-rows: auto;
+  grid-gap: 1.3125rem;
+  margin: 1.3125rem;
+  // Hide empty extension wrappers when components return null
+  // This prevents empty space in the grid when supplementary widgets have no data
+  > :has([data-extension-id='immunization-detailed-history-card']:empty) {
+    display: none;
+  }
+}
+
+// See https://zpl.io/lrlmdq0 for the Visits dashboard design
+[data-extension-slot-name='patient-chart-encounters-dashboard-slot'],
+// See https://zpl.io/RmMXrDE for the Test Results dashboard design
+[data-extension-slot-name='patient-chart-test-results-dashboard-slot'] {
+  margin: 0 layout.$spacing-05;
+}
+
+.dashboardContainer:not(:has([data-extension-slot-name='patient-chart-attachments-dashboard-slot'])) {
+  container-name: dashboard;
+  container-type: inline-size;
+}
+
+// When the dashboard's width is less than or equal to 68.25rem (1100px),
+// the layout should switch to a single column. This adjustment ensures
+// proper rendering when the workspace area is opened.
+@container dashboard (width <= 68.25rem) {
+  .dashboard {
+    grid-template-columns: 1fr;
+  }
+}
+
+.extensionWrapper {
+  > * {
+    height: 100%;
+    display: flex;
+    flex-direction: column;
+  }
+}
+
+.extension:only-child {
+  grid-column: 1 / -1;
+}
+
+.fullWidth {
+  grid-column: 1 / -1;
+}
+
+:global(.omrs-breakpoint-lt-desktop) .dashboard {
+  grid-template-columns: 1fr;
+}
+
+:global(.omrs-breakpoint-lt-tablet) .container {
+  margin: 5px;
+  overflow-x: auto;
+  justify-content: center;
+}
+
+:global(.omrs-breakpoint-lt-tablet) .dashboard {
+  display: flex;
+  flex-direction: column;
+  flex-wrap: wrap;
+}
+
+:global(.omrs-breakpoint-lt-tablet) .dashboard > div {
+  margin: layout.$spacing-01 0px;
+}
+
+// Overriding styles for RTL support
+html[dir='rtl'] {
+  .dashboardTitle {
+    margin: layout.$spacing-05 1.3125rem layout.$spacing-05 0;
+  }
+}

package/src/patient-chart/patient-chart.component.tsx

@@ -0,0 +1,71 @@
+import { ExtensionSlot, useLeftNav } from '@openmrs/esm-framework';
+import classNames from 'classnames';
+import React, { useMemo, useState } from 'react';
+import { useParams } from 'react-router-dom';
+import { spaBasePath } from '../constants';
+import Loader from '../loader/loader.component';
+import ChartReview from '../patient-chart/chart-review/chart-review.component';
+import SideMenuPanel from '../side-nav/side-menu.component';
+import { type LayoutMode } from './chart-review/dashboard-view.component';
+import styles from './patient-chart.scss';
+import { usePatientChartPatientAndVisit } from './patient-chart.resources';
+
+const PatientChart: React.FC = () => {
+  const { patientUuid, view: encodedView } = useParams();
+
+  // specify key to ensure that WrapPatientChart instance is re-created
+  // when we switch patient
+  return <WrappedPatientChart key={patientUuid} patientUuid={patientUuid} encodedView={encodedView} />;
+};
+
+interface WrappedPatientChartProps {
+  patientUuid: string;
+  encodedView: string;
+}
+
+const WrappedPatientChart: React.FC<WrappedPatientChartProps> = ({ patientUuid, encodedView }) => {
+  const view = decodeURIComponent(encodedView);
+  const [layoutMode, setLayoutMode] = useState<LayoutMode>();
+  const state = usePatientChartPatientAndVisit(patientUuid);
+  const { isLoadingPatient, patient } = state;
+
+  const leftNavBasePath = useMemo(() => spaBasePath.replace(':patientUuid', patientUuid), [patientUuid]);
+
+  useLeftNav({ name: 'patient-chart-dashboard-slot', basePath: leftNavBasePath });
+
+  return (
+    <>
+      <SideMenuPanel />
+      <main className={classNames('omrs-main-content', styles.chartContainer)}>
+        <>
+          <div className={classNames(styles.innerChartContainer)}>
+            {isLoadingPatient ? (
+              <Loader />
+            ) : (
+              <>
+                <aside>
+                  <ExtensionSlot name="patient-header-slot" state={state} />
+                  <ExtensionSlot name="patient-info-slot" state={state} className={styles.patientInfoSlot} />
+                </aside>
+                <div className={styles.grid}>
+                  <div
+                    className={classNames(styles.chartReview, { [styles.widthContained]: layoutMode == 'contained' })}
+                  >
+                    <ChartReview
+                      patient={patient}
+                      patientUuid={patientUuid}
+                      view={view}
+                      setDashboardLayoutMode={setLayoutMode}
+                    />
+                  </div>
+                </div>
+              </>
+            )}
+          </div>
+        </>
+      </main>
+    </>
+  );
+};
+
+export default PatientChart;

package/src/patient-chart/patient-chart.resources.test.ts

@@ -0,0 +1,238 @@
+import { renderHook, waitFor } from '@testing-library/react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { launchWorkspaceGroup2, usePatient, useVisit, type Visit } from '@openmrs/esm-framework';
+import { usePatientChartStore } from '@openmrs/esm-patient-common-lib';
+import { mockFhirPatient } from '__mocks__';
+import { usePatientChartPatientAndVisit } from './patient-chart.resources';
+
+// TODO: remove once openmrs-esm-core ships launchWorkspaceGroup2 in the framework mock
+vi.mock('@openmrs/esm-framework', async () => {
+  const actual = (await vi.importActual('@openmrs/esm-framework')) as object;
+  return { ...actual, launchWorkspaceGroup2: vi.fn() };
+});
+
+vi.mock('@openmrs/esm-patient-common-lib', () => ({
+  usePatientChartStore: vi.fn(),
+}));
+
+const mockLaunchWorkspaceGroup = vi.mocked(launchWorkspaceGroup2);
+const mockUsePatient = vi.mocked(usePatient);
+const mockUseVisit = vi.mocked(useVisit);
+const mockUsePatientChartStore = vi.mocked(usePatientChartStore);
+
+const mutateVisitContext = vi.fn();
+const setPatient = vi.fn();
+const setVisitContext = vi.fn();
+
+const visitA = { uuid: 'visit-a', patient: { uuid: mockFhirPatient.id } } as Visit;
+const visitB = { uuid: 'visit-b', patient: { uuid: mockFhirPatient.id } } as Visit;
+const patientB = { ...mockFhirPatient, id: 'patient-b' };
+
+function mockNoActiveVisitForPatientSwitch() {
+  mockUsePatient.mockImplementation((patientUuid) => ({
+    isLoading: false,
+    patient: patientUuid === patientB.id ? patientB : mockFhirPatient,
+    patientUuid,
+    error: null,
+  }));
+  mockUseVisit.mockImplementation(() => ({
+    activeVisit: null,
+    mutate: mutateVisitContext,
+    isValidating: false,
+    error: null,
+    currentVisit: null,
+    currentVisitIsRetrospective: false,
+    isLoading: false,
+  }));
+  mockUsePatientChartStore.mockImplementation((patientUuid) => ({
+    patientUuid,
+    patient: patientUuid === patientB.id ? patientB : mockFhirPatient,
+    visitContext: null,
+    mutateVisitContext: null,
+    setPatient,
+    setVisitContext,
+  }));
+}
+
+describe('usePatientChartPatientAndVisit', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockLaunchWorkspaceGroup.mockResolvedValue(true);
+    mockUsePatient.mockReturnValue({
+      isLoading: false,
+      patient: mockFhirPatient,
+      patientUuid: mockFhirPatient.id,
+      error: null,
+    });
+    mockUsePatientChartStore.mockReturnValue({
+      patientUuid: mockFhirPatient.id,
+      patient: mockFhirPatient,
+      visitContext: null,
+      mutateVisitContext: null,
+      setPatient,
+      setVisitContext,
+    });
+  });
+
+  it('relaunches the patient-chart workspace group when the visit context changes', async () => {
+    let activeVisit = visitA;
+    mockUseVisit.mockImplementation(() => ({
+      activeVisit,
+      mutate: mutateVisitContext,
+      isValidating: false,
+      error: null,
+      currentVisit: null,
+      currentVisitIsRetrospective: false,
+      isLoading: false,
+    }));
+
+    const { rerender } = renderHook(() => usePatientChartPatientAndVisit(mockFhirPatient.id));
+
+    await waitFor(() => expect(mockLaunchWorkspaceGroup).toHaveBeenCalledTimes(1));
+    expect(mockLaunchWorkspaceGroup).toHaveBeenLastCalledWith(
+      'patient-chart',
+      expect.objectContaining({
+        patient: mockFhirPatient,
+        patientUuid: mockFhirPatient.id,
+        visitContext: visitA,
+        mutateVisitContext,
+      }),
+    );
+
+    activeVisit = visitB;
+    rerender();
+
+    await waitFor(() => expect(mockLaunchWorkspaceGroup).toHaveBeenCalledTimes(2));
+    expect(mockLaunchWorkspaceGroup).toHaveBeenLastCalledWith(
+      'patient-chart',
+      expect.objectContaining({
+        patient: mockFhirPatient,
+        patientUuid: mockFhirPatient.id,
+        visitContext: visitB,
+        mutateVisitContext,
+      }),
+    );
+  });
+
+  it('does not relaunch when the same visit UUID is returned with new object references', async () => {
+    let activeVisit: Visit = visitA;
+    mockUseVisit.mockImplementation(() => ({
+      activeVisit,
+      mutate: mutateVisitContext,
+      isValidating: false,
+      error: null,
+      currentVisit: null,
+      currentVisitIsRetrospective: false,
+      isLoading: false,
+    }));
+
+    const { rerender } = renderHook(() => usePatientChartPatientAndVisit(mockFhirPatient.id));
+
+    await waitFor(() => expect(mockLaunchWorkspaceGroup).toHaveBeenCalledTimes(1));
+
+    // Same UUID, new object reference — mimics SWR revalidation
+    activeVisit = { ...visitA, stopDatetime: '2026-05-26T00:00:00.000Z' } as Visit;
+    rerender();
+
+    // Wait for the effect to fire before asserting the launch count didn't increase
+    await waitFor(() => expect(setVisitContext).toHaveBeenCalledTimes(2));
+    expect(mockLaunchWorkspaceGroup).toHaveBeenCalledTimes(1);
+  });
+
+  it('relaunches when the patient changes and neither patient has an active visit', async () => {
+    mockNoActiveVisitForPatientSwitch();
+
+    const { rerender } = renderHook(({ patientUuid }) => usePatientChartPatientAndVisit(patientUuid), {
+      initialProps: { patientUuid: mockFhirPatient.id },
+    });
+
+    await waitFor(() => expect(mockLaunchWorkspaceGroup).toHaveBeenCalledTimes(1));
+    expect(mockLaunchWorkspaceGroup).toHaveBeenLastCalledWith(
+      'patient-chart',
+      expect.objectContaining({ patientUuid: mockFhirPatient.id, visitContext: null }),
+    );
+
+    rerender({ patientUuid: patientB.id });
+
+    await waitFor(() => expect(setVisitContext).toHaveBeenCalledTimes(2));
+    await waitFor(() => expect(mockLaunchWorkspaceGroup).toHaveBeenCalledTimes(2));
+    expect(mockLaunchWorkspaceGroup).toHaveBeenLastCalledWith(
+      'patient-chart',
+      expect.objectContaining({ patientUuid: patientB.id, visitContext: null }),
+    );
+  });
+
+  it('launches the latest patient after a previous launch resolves', async () => {
+    let patientUuid = mockFhirPatient.id;
+    let resolveFirstLaunch!: (value: boolean) => void;
+    const firstLaunch = new Promise<boolean>((resolve) => {
+      resolveFirstLaunch = resolve;
+    });
+
+    mockLaunchWorkspaceGroup.mockReturnValueOnce(firstLaunch).mockResolvedValue(true);
+    mockNoActiveVisitForPatientSwitch();
+
+    const { rerender } = renderHook(() => usePatientChartPatientAndVisit(patientUuid));
+
+    await waitFor(() => expect(mockLaunchWorkspaceGroup).toHaveBeenCalledTimes(1));
+    expect(mockLaunchWorkspaceGroup).toHaveBeenLastCalledWith(
+      'patient-chart',
+      expect.objectContaining({ patientUuid: mockFhirPatient.id, visitContext: null }),
+    );
+
+    patientUuid = patientB.id;
+    rerender();
+
+    await waitFor(() => expect(setVisitContext).toHaveBeenCalledTimes(2));
+    expect(mockLaunchWorkspaceGroup).toHaveBeenCalledTimes(1);
+
+    resolveFirstLaunch(true);
+
+    await waitFor(() => expect(mockLaunchWorkspaceGroup).toHaveBeenCalledTimes(2));
+    expect(mockLaunchWorkspaceGroup).toHaveBeenLastCalledWith(
+      'patient-chart',
+      expect.objectContaining({ patientUuid: patientB.id, visitContext: null }),
+    );
+  });
+
+  it('launches the latest visit context after a previous launch resolves', async () => {
+    let activeVisit = visitA;
+    let resolveFirstLaunch!: (value: boolean) => void;
+    const firstLaunch = new Promise<boolean>((resolve) => {
+      resolveFirstLaunch = resolve;
+    });
+
+    mockLaunchWorkspaceGroup.mockReturnValueOnce(firstLaunch).mockResolvedValue(true);
+    mockUseVisit.mockImplementation(() => ({
+      activeVisit,
+      mutate: mutateVisitContext,
+      isValidating: false,
+      error: null,
+      currentVisit: null,
+      currentVisitIsRetrospective: false,
+      isLoading: false,
+    }));
+
+    const { rerender } = renderHook(() => usePatientChartPatientAndVisit(mockFhirPatient.id));
+
+    await waitFor(() => expect(mockLaunchWorkspaceGroup).toHaveBeenCalledTimes(1));
+    expect(mockLaunchWorkspaceGroup).toHaveBeenLastCalledWith(
+      'patient-chart',
+      expect.objectContaining({ visitContext: visitA }),
+    );
+
+    activeVisit = visitB;
+    rerender();
+
+    await waitFor(() => expect(setVisitContext).toHaveBeenCalledTimes(2));
+    expect(mockLaunchWorkspaceGroup).toHaveBeenCalledTimes(1);
+
+    resolveFirstLaunch(true);
+
+    await waitFor(() => expect(mockLaunchWorkspaceGroup).toHaveBeenCalledTimes(2));
+    expect(mockLaunchWorkspaceGroup).toHaveBeenLastCalledWith(
+      'patient-chart',
+      expect.objectContaining({ visitContext: visitB }),
+    );
+  });
+});