@openmrs/esm-patient-common-lib 13.0.2-pre.12852 → 13.0.2-pre.12863

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openmrs/esm-patient-common-lib",
-  "version": "13.0.2-pre.12852",
+  "version": "13.0.2-pre.12863",
   "license": "MPL-2.0",
   "description": "Library for common patient chart components",
   "browser": "dist/openmrs-esm-patient-common-lib.js",

package/src/orders/types/order.ts

@@ -1,4 +1,5 @@
 import type { Encounter, OpenmrsResource, Visit, Workspace2DefinitionProps } from '@openmrs/esm-framework';
+import type { PatientWorkspaceWindowProps } from '../../workspaces';
 
 export interface Concept extends OpenmrsResource {
   name?: {
@@ -321,29 +322,36 @@ export interface TestOrderBasketItem extends OrderBasketItem {
   specimenSource?: string;
 }
 
-export interface OrderBasketWindowProps {
-  encounterUuid: string;
-  onOrderBasketSubmitted?: (encounterUuid: string, postedOrders: Array<Order>) => void;
-}
-
-export interface ExportedOrderBasketWindowProps {
-  encounterUuid: string;
-  drugOrderWorkspaceName: string;
-  labOrderWorkspaceName: string;
-  generalOrderWorkspaceName: string;
+/**
+ * Window props of the order basket window (`patient-chart-order-basket`), taken by the order basket
+ * and the add drug / lab / general order workspaces. In the patient chart, the patient / visit are
+ * supplied by `getPatientChartWindowProps`; other apps supply them themselves, along with the
+ * names of the child workspaces they have registered into the window.
+ */
+export interface OrderBasketWindowProps extends PatientWorkspaceWindowProps {
+  /**
+   * Names of the workspaces the order basket launches as child workspaces. Optional: if none of the
+   * three is supplied, the patient chart's own `add-drug-order`, `add-lab-order` and
+   * `orderable-concept-workspace` are used. If any is supplied, only the supplied ones are launchable,
+   * so a host can limit the basket to the order types it registered workspaces for.
+   */
+  drugOrderWorkspaceName?: string;
+  labOrderWorkspaceName?: string;
+  generalOrderWorkspaceName?: string;
   /**
    * Name of a workspace, registered by the host into the order basket window, that renders the
    * allergy form. Supplied when the order basket runs outside the patient chart so the allergy
    * "+" affordance can launch the form in the host's workspace group instead of the chart's.
    */
   allergyFormWorkspaceName?: string;
-  patient: fhir.Patient;
-  patientUuid: string;
-  visitContext: Visit;
-  mutateVisitContext: () => void;
   onOrderBasketSubmitted?: (encounterUuid: string, postedOrders: Array<Order>) => void;
   /**
    * An optional array of order type UUIDs to display. If not provided, all panels are shown.
    */
   visibleOrderPanels?: Array<string>;
 }
+
+/**
+ * @deprecated Use `OrderBasketWindowProps`.
+ */
+export type ExportedOrderBasketWindowProps = OrderBasketWindowProps;

package/src/store/patient-chart-store.ts

@@ -1,4 +1,5 @@
 import { type Actions, createGlobalStore, useStoreWithActions, type Visit } from '@openmrs/esm-framework';
+import { type PatientWorkspaceGroupProps } from '../workspaces';
 
 export interface PatientChartStore {
   patientUuid: string;
@@ -8,10 +9,16 @@ export interface PatientChartStore {
   /**
    * The uuid of the visit context the patient-chart workspace group was last launched with.
    * Note that when the visit context is changed, the workspaces group (with stale visit context)
-   * must close and reopen, and during that process its visitContext might differ from 
+   * must close and reopen, and during that process its visitContext might differ from
    * `store.visitContext`
    */
   workspaceGroupVisitUuid?: string | null;
+  /**
+   * The group props the patient-chart workspace group was last launched with. The workspace system
+   * only relaunches the group when the patient or visit uuid changes, so these objects can be older
+   * than `patient` / `visitContext` above. See `getPatientChartWindowProps`.
+   */
+  workspaceGroupProps?: PatientWorkspaceGroupProps | null;
 }
 
 const patientChartStoreName = 'patient-chart-global-store';
@@ -22,6 +29,7 @@ const patientChartStore = createGlobalStore<PatientChartStore>(patientChartStore
   visitContext: null,
   mutateVisitContext: null,
   workspaceGroupVisitUuid: null,
+  workspaceGroupProps: null,
 });
 
 const patientChartStoreActions = {
@@ -37,8 +45,28 @@ const patientChartStoreActions = {
  * Records the visit context the patient-chart workspace group was last launched with.
  * Only the patient chart should call this, after it launches its workspace group.
  */
-export function setPatientChartWorkspaceGroupVisitUuid(workspaceGroupVisitUuid: string | null) {
-  patientChartStore.setState({ workspaceGroupVisitUuid });
+export function setPatientChartWorkspaceGroupVisitUuid(
+  workspaceGroupVisitUuid: string | null,
+  workspaceGroupProps?: PatientWorkspaceGroupProps | null,
+) {
+  patientChartStore.setState(
+    workspaceGroupProps === undefined ? { workspaceGroupVisitUuid } : { workspaceGroupVisitUuid, workspaceGroupProps },
+  );
+}
+
+/**
+ * Non-reactive read of the patient chart store, for use inside callbacks (e.g. at the moment a
+ * workspace is launched). Like `usePatientChartStore`, it only returns the store values if
+ * `patientUuid` matches the patient in the store; otherwise it returns null. If `patientUuid` is
+ * omitted, it returns the store values of whichever patient the patient chart currently has open
+ * (or null if it has none).
+ */
+export function getPatientChartStoreState(patientUuid?: string): PatientChartStore | null {
+  const state = patientChartStore.getState();
+  if (patientUuid === undefined) {
+    return state.patientUuid ? state : null;
+  }
+  return state.patientUuid === patientUuid ? state : null;
 }
 
 /**
@@ -65,6 +93,7 @@ export function usePatientChartStore(patientUuid: string) {
       patientUuid: null,
       visitContext: null,
       workspaceGroupVisitUuid: null,
+      workspaceGroupProps: null,
     };
     return fakeStore;
   }

package/src/workspaces.test.ts

@@ -1,9 +1,16 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { act, renderHook } from '@testing-library/react';
-import { showModal, useFeatureFlag, type Visit } from '@openmrs/esm-framework';
+import { launchWorkspace2, showModal, useFeatureFlag, useLayoutType, type Visit } from '@openmrs/esm-framework';
 import { setPatientChartWorkspaceGroupVisitUuid, usePatientChartStore } from './store/patient-chart-store';
 import { useSystemVisitSetting } from './useSystemVisitSetting';
-import { useStartVisitIfNeeded } from './workspaces';
+import {
+  getPatientAndVisitProps,
+  getPatientChartWindowProps,
+  useActionMenuButtonLaunchProps,
+  useLaunchWorkspaceRequiringVisit,
+  useStartVisitIfNeeded,
+  useShowPatientBanner,
+} from './workspaces';
 
 vi.mock('./useSystemVisitSetting', () => ({
   useSystemVisitSetting: vi.fn(),
@@ -167,3 +174,277 @@ describe('useStartVisitIfNeeded', () => {
     await expect(promise).resolves.toBe(false);
   });
 });
+
+describe('getPatientChartWindowProps', () => {
+  const mutateVisitContext = vi.fn();
+
+  afterEach(() => {
+    const { result } = renderHook(() => usePatientChartStore(patient.id));
+    act(() => {
+      result.current.setVisitContext(null, null);
+      result.current.setPatient(null);
+      setPatientChartWorkspaceGroupVisitUuid(null, null);
+    });
+  });
+
+  it('returns the props the workspace group was launched with, not the latest store values', () => {
+    const { result } = renderHook(() => usePatientChartStore(patient.id));
+    const groupProps = {
+      patient,
+      patientUuid: patient.id,
+      visitContext: visit,
+      mutateVisitContext,
+      showPatientBanner: 'tabletOnly' as const,
+    };
+    act(() => result.current.setPatient(patient));
+    act(() => {
+      result.current.setVisitContext({ ...visit }, vi.fn());
+      setPatientChartWorkspaceGroupVisitUuid(visit.uuid, groupProps);
+    });
+
+    expect(getPatientChartWindowProps(patient.id)).toEqual({ patient, patientUuid: patient.id, visitContext: visit });
+    expect(getPatientChartWindowProps(patient.id).visitContext).toBe(visit);
+  });
+
+  it('falls back to the store values when no workspace group was launched', () => {
+    const { result } = renderHook(() => usePatientChartStore(patient.id));
+    act(() => result.current.setPatient(patient));
+    act(() => result.current.setVisitContext(visit, mutateVisitContext));
+
+    expect(getPatientChartWindowProps(patient.id)).toEqual({
+      patient,
+      patientUuid: patient.id,
+      visitContext: visit,
+    });
+  });
+
+  it('ignores group props that belong to the previous patient', () => {
+    const { result } = renderHook(() => usePatientChartStore(patient.id));
+    const previousPatientGroupProps = {
+      patient: { ...patient, id: 'previous-patient-uuid' },
+      patientUuid: 'previous-patient-uuid',
+      visitContext: visit,
+      mutateVisitContext,
+      showPatientBanner: 'tabletOnly' as const,
+    };
+    act(() => result.current.setPatient(patient));
+    act(() => setPatientChartWorkspaceGroupVisitUuid(visit.uuid, previousPatientGroupProps));
+
+    expect(getPatientChartWindowProps(patient.id)).toEqual({
+      patient,
+      patientUuid: patient.id,
+      visitContext: null,
+    });
+  });
+
+  it("does not return another patient's chart context", () => {
+    const { result } = renderHook(() => usePatientChartStore(patient.id));
+    act(() => result.current.setPatient(patient));
+    act(() => result.current.setVisitContext(visit, mutateVisitContext));
+
+    expect(getPatientChartWindowProps('other-patient-uuid')).toEqual({
+      patient: null,
+      patientUuid: 'other-patient-uuid',
+      visitContext: null,
+    });
+  });
+});
+
+describe('getPatientAndVisitProps', () => {
+  it('prefers window props over the deprecated workspace props', () => {
+    const otherPatient = { id: 'other' } as fhir.Patient;
+    expect(
+      getPatientAndVisitProps(
+        { patient, patientUuid: patient.id, visitContext: visit },
+        { patient: otherPatient, patientUuid: 'other', visitContext: null },
+      ),
+    ).toEqual({ patient, patientUuid: patient.id, visitContext: visit });
+  });
+
+  it("falls back to the patient's id when only a patient is given", () => {
+    expect(getPatientAndVisitProps({ patient, visitContext: visit }, undefined)).toEqual({
+      patient,
+      patientUuid: patient.id,
+      visitContext: visit,
+    });
+  });
+
+  it('falls back to workspace props when there are no window props', () => {
+    expect(getPatientAndVisitProps(null, { patient, patientUuid: patient.id, visitContext: visit })).toEqual({
+      patient,
+      patientUuid: patient.id,
+      visitContext: visit,
+    });
+  });
+
+  it('falls back to group props when a launch supplies neither window props nor workspace props', () => {
+    expect(getPatientAndVisitProps(null, undefined, { patient, patientUuid: patient.id, visitContext: visit })).toEqual(
+      { patient, patientUuid: patient.id, visitContext: visit },
+    );
+  });
+
+  it("doesn't mix the group's visit into a patient given by the window", () => {
+    expect(
+      getPatientAndVisitProps({ patient, patientUuid: patient.id, visitContext: null }, undefined, {
+        patient,
+        patientUuid: patient.id,
+        visitContext: visit,
+      }),
+    ).toEqual({ patient, patientUuid: patient.id, visitContext: null });
+  });
+
+  it('prefers workspace props over group props', () => {
+    const otherPatient = { id: 'other' } as fhir.Patient;
+    expect(
+      getPatientAndVisitProps(
+        undefined,
+        { patient, patientUuid: patient.id, visitContext: visit },
+        { patient: otherPatient, patientUuid: 'other', visitContext: null },
+      ),
+    ).toEqual({ patient, patientUuid: patient.id, visitContext: visit });
+  });
+});
+
+describe('useLaunchWorkspaceRequiringVisit', () => {
+  const mockLaunchWorkspace2 = vi.mocked(launchWorkspace2);
+
+  beforeEach(() => {
+    mockUseSystemVisitSetting.mockReturnValue({
+      systemVisitEnabled: false,
+      errorFetchingSystemVisitSetting: null,
+      isLoadingSystemVisitSetting: false,
+    });
+  });
+
+  afterEach(() => {
+    const { result } = renderHook(() => usePatientChartStore(patient.id));
+    act(() => {
+      result.current.setVisitContext(null, null);
+      result.current.setPatient(null);
+      setPatientChartWorkspaceGroupVisitUuid(null, null);
+    });
+    mockLaunchWorkspace2.mockClear();
+  });
+
+  it('supplies the patient chart window props, which the caller can override', async () => {
+    const { result } = renderHook(() => ({
+      store: usePatientChartStore(patient.id),
+      launch: useLaunchWorkspaceRequiringVisit(patient.id, 'some-workspace'),
+    }));
+    act(() => result.current.store.setPatient(patient));
+    act(() => result.current.store.setVisitContext(visit, null));
+
+    await act(async () => result.current.launch({ a: 1 } as any, { extra: true }));
+
+    await vi.waitFor(() => expect(mockLaunchWorkspace2).toHaveBeenCalledTimes(1));
+    expect(mockLaunchWorkspace2).toHaveBeenCalledWith(
+      'some-workspace',
+      { a: 1 },
+      { patient, patientUuid: patient.id, visitContext: visit, extra: true },
+      undefined,
+    );
+  });
+
+  it('supplies the window props of the visit started by the prompt, not the visit-less props from before it', async () => {
+    mockUseSystemVisitSetting.mockReturnValue({
+      systemVisitEnabled: true,
+      errorFetchingSystemVisitSetting: null,
+      isLoadingSystemVisitSetting: false,
+    });
+    mockUseFeatureFlag.mockReturnValue(false);
+    mockShowModal.mockReturnValue(vi.fn());
+    const groupPropsWithoutVisit = {
+      patient,
+      patientUuid: patient.id,
+      visitContext: null,
+      mutateVisitContext: null,
+      showPatientBanner: 'tabletOnly' as const,
+    };
+    const { result } = renderHook(() => ({
+      store: usePatientChartStore(patient.id),
+      launch: useActionMenuButtonLaunchProps(groupPropsWithoutVisit, 'some-workspace'),
+    }));
+    act(() => result.current.store.setPatient(patient));
+    act(() => setPatientChartWorkspaceGroupVisitUuid(null, groupPropsWithoutVisit));
+
+    // The button holds the props of the render it was clicked in, and does not wait for the launch to happen
+    expect(result.current.launch.workspaceToLaunch.windowProps.visitContext).toBeNull();
+    let shouldLaunch: Promise<boolean>;
+    act(() => {
+      shouldLaunch = result.current.launch.onBeforeWorkspaceLaunch();
+    });
+    const { onVisitStarted } = getModalProps('start-visit-dialog');
+
+    // The visit is started, and the chart relaunches its workspace group with it
+    await act(async () => {
+      result.current.store.setVisitContext(visit, null);
+      onVisitStarted();
+    });
+    expect(mockLaunchWorkspace2).not.toHaveBeenCalled();
+    const groupPropsWithVisit = {
+      patient,
+      patientUuid: patient.id,
+      visitContext: visit,
+      mutateVisitContext: null,
+      showPatientBanner: 'tabletOnly' as const,
+    };
+    await act(async () => setPatientChartWorkspaceGroupVisitUuid(visit.uuid, groupPropsWithVisit));
+
+    await expect(shouldLaunch).resolves.toBe(false);
+    await vi.waitFor(() => expect(mockLaunchWorkspace2).toHaveBeenCalledTimes(1));
+    const windowProps = mockLaunchWorkspace2.mock.calls[0][2] as Record<string, unknown>;
+    expect(windowProps).toMatchObject({ patientUuid: patient.id });
+    expect(windowProps.visitContext).toBe(visit);
+  });
+
+  it('lets the action menu button launch with its own window props when the visit did not change', async () => {
+    mockUseSystemVisitSetting.mockReturnValue({
+      systemVisitEnabled: true,
+      errorFetchingSystemVisitSetting: null,
+      isLoadingSystemVisitSetting: false,
+    });
+    const groupPropsWithVisit = {
+      patient,
+      patientUuid: patient.id,
+      visitContext: visit,
+      mutateVisitContext: null,
+      showPatientBanner: 'tabletOnly' as const,
+    };
+    const { result } = renderHook(() => ({
+      store: usePatientChartStore(patient.id),
+      launch: useActionMenuButtonLaunchProps(groupPropsWithVisit, 'some-workspace'),
+    }));
+    act(() => result.current.store.setPatient(patient));
+    act(() => result.current.store.setVisitContext(visit, null));
+    act(() => setPatientChartWorkspaceGroupVisitUuid(visit.uuid, groupPropsWithVisit));
+
+    await expect(result.current.launch.onBeforeWorkspaceLaunch()).resolves.toBe(true);
+    expect(mockLaunchWorkspace2).not.toHaveBeenCalled();
+    expect(result.current.launch.workspaceToLaunch).toMatchObject({
+      workspaceName: 'some-workspace',
+      windowProps: { patient, patientUuid: patient.id, visitContext: visit },
+    });
+  });
+});
+
+describe('useShowPatientBanner', () => {
+  const mockUseLayoutType = vi.mocked(useLayoutType);
+
+  function show(groupProps: object | null) {
+    return renderHook(() => useShowPatientBanner(groupProps)).result.current;
+  }
+
+  it("shows the banner at every width by default, as ward and other hosts' group props don't set a mode", () => {
+    mockUseLayoutType.mockReturnValue('large-desktop');
+    expect(show({})).toBe(true);
+    expect(show({ wardPatient: {} })).toBe(true);
+    expect(show(null)).toBe(true);
+  });
+
+  it("shows the banner on tablet only when the group asks for 'tabletOnly'", () => {
+    mockUseLayoutType.mockReturnValue('large-desktop');
+    expect(show({ showPatientBanner: 'tabletOnly' })).toBe(false);
+    mockUseLayoutType.mockReturnValue('tablet');
+    expect(show({ showPatientBanner: 'tabletOnly' })).toBe(true);
+  });
+});

package/src/workspaces.ts

@@ -4,10 +4,11 @@ import {
   navigate,
   showModal,
   useFeatureFlag,
+  useLayoutType,
   type Visit,
   type Workspace2DefinitionProps,
 } from '@openmrs/esm-framework';
-import { usePatientChartStore } from './store/patient-chart-store';
+import { getPatientChartStoreState, usePatientChartStore } from './store/patient-chart-store';
 import { useSystemVisitSetting } from './useSystemVisitSetting';
 
 export interface PatientWorkspaceGroupProps {
@@ -15,6 +16,136 @@ export interface PatientWorkspaceGroupProps {
   patientUuid: string;
   visitContext: Visit;
   mutateVisitContext: () => void;
+  /**
+   * When the workspaces of this group render the patient banner themselves. The patient chart has its own
+   * patient header on desktop, so every group props object it builds sets `'tabletOnly'` (required here so
+   * that a launch cannot forget it). Other apps' workspace groups don't set it, which means `'always'`.
+   * See `useShowPatientBanner`.
+   */
+  showPatientBanner: PatientBannerMode;
+}
+
+export type PatientBannerMode = 'always' | 'tabletOnly';
+
+/**
+ * The only part of the group props that workspaces shared between the patient chart and other apps
+ * may read. Other apps' workspace groups have group props of their own, so everything but this
+ * is meaningless to a shared workspace.
+ */
+export type PatientBannerGroupProps = Partial<Pick<PatientWorkspaceGroupProps, 'showPatientBanner'>>;
+
+/**
+ * What a shared workspace may read from its group props: the banner mode, and, as a last resort for
+ * launches that supply no window props, the patient / visit of the patient chart's group (see
+ * `getPatientAndVisitProps`).
+ */
+export type SharedWorkspaceGroupProps = PatientBannerGroupProps &
+  Partial<Pick<PatientWorkspaceGroupProps, 'patient' | 'patientUuid' | 'visitContext'>>;
+
+/**
+ * Whether a workspace should render the patient banner itself, as asked for by its workspace group.
+ */
+export function useShowPatientBanner(groupProps: PatientBannerGroupProps | null | undefined): boolean {
+  const isTablet = useLayoutType() === 'tablet';
+  const showPatientBanner: PatientBannerMode = groupProps?.showPatientBanner ?? 'always';
+  return showPatientBanner === 'always' || isTablet;
+}
+
+/**
+ * The window props taken by workspaces that are shared between the patient chart and other apps
+ * (ward, service queues, dispensing, ...). These workspaces never read group props: whoever opens
+ * the window supplies the patient / visit the workspace acts on. In the patient chart, use
+ * `getPatientChartWindowProps` to build them.
+ */
+export interface PatientWorkspaceWindowProps {
+  patient: fhir.Patient;
+  patientUuid: string;
+  visitContext: Visit;
+}
+
+/**
+ * Window props for the forms dashboard / form entry workspaces (window `patient-chart-clinical-forms`).
+ */
+export interface ClinicalFormsWindowProps extends PatientWorkspaceWindowProps {
+  /**
+   * Name of the form entry workspace the forms dashboard launches as a child workspace.
+   * Defaults to the patient chart's `patient-form-entry-workspace`.
+   */
+  formEntryWorkspaceName?: string;
+}
+
+/**
+ * The patient / visit props that vitals, visit notes, lab results and the visit form used to take as
+ * workspace props. They now take them as window props; the workspace-prop versions are only read
+ * as a fallback for callers that have not migrated yet.
+ * @deprecated Pass `patient` / `patientUuid` / `visitContext` as window props instead.
+ */
+export type DeprecatedPatientWorkspaceProps = Partial<
+  Pick<PatientWorkspaceWindowProps, 'patient' | 'patientUuid' | 'visitContext'>
+>;
+
+/**
+ * Reads the patient / visit a workspace acts on: window props first, falling back to the
+ * deprecated workspace props. The deprecated fallback lives here, so it can be deleted once the
+ * apps that still pass workspace props (ward, service queues, appointments, patient lists, lab app) have
+ * migrated to window props.
+ *
+ * Only if the launch supplied no patient at all (neither window props nor workspace props), the group
+ * props are used as a whole, patient and visit together. The group's visit is never mixed in with a
+ * patient given by the window, as a `visitContext` of null there means "no visit".
+ *
+ * Don't pass group props for a workspace whose `visitContext` window prop means something other than
+ * "the visit the user is working in", such as the visit form, where null means "start a new visit".
+ */
+export function getPatientAndVisitProps(
+  windowProps: Partial<PatientWorkspaceWindowProps> | null | undefined,
+  workspaceProps: DeprecatedPatientWorkspaceProps | null | undefined,
+  groupProps?: SharedWorkspaceGroupProps | null,
+): Pick<PatientWorkspaceWindowProps, 'patient' | 'patientUuid' | 'visitContext'> {
+  // Only `undefined` falls through to the next source: a null `visitContext` means "no visit"
+  const patient = windowProps?.patient !== undefined ? windowProps.patient : workspaceProps?.patient;
+  const patientUuid = windowProps?.patientUuid !== undefined ? windowProps.patientUuid : workspaceProps?.patientUuid;
+  const visitContext =
+    windowProps?.visitContext !== undefined ? windowProps.visitContext : workspaceProps?.visitContext;
+  if (patient || patientUuid) {
+    return { patient, patientUuid: patientUuid ?? patient?.id, visitContext };
+  }
+  return { patient: groupProps?.patient, patientUuid: groupProps?.patientUuid, visitContext: groupProps?.visitContext };
+}
+
+/**
+ * Converts the group props of the patient chart into window props.
+ */
+function groupPropsToWindowProps(groupProps: PatientWorkspaceGroupProps): PatientWorkspaceWindowProps {
+  const { patient, patientUuid, visitContext } = groupProps;
+  return { patient, patientUuid, visitContext };
+}
+
+/**
+ * Builds the window props the patient chart supplies when it opens a workspace window, from the
+ * group props the workspace group is currently open with. Reads the store when called (not when
+ * rendered), so call this at launch time.
+ *
+ * The group props are used rather than the latest store values because the window props of an open
+ * window are compared (shallowly) with the window props of every later launch into that window, and
+ * an incompatible launch prompts the user to close the window. The store's `patient` / `visitContext`
+ * objects are replaced on every revalidation, while the group props stay the same until the
+ * patient or visit changes, so reading the group props keeps launches compatible.
+ *
+ * If `patientUuid` is omitted, the patient the chart currently has open is used.
+ */
+export function getPatientChartWindowProps(patientUuid?: string): PatientWorkspaceWindowProps {
+  const state = getPatientChartStoreState(patientUuid);
+  // The group props are only replaced once a new group launches, so they may still belong to the
+  // previous patient right after the chart switched patients. Don't use them in that case.
+  if (state?.workspaceGroupProps && state.workspaceGroupProps.patientUuid === state.patientUuid) {
+    return groupPropsToWindowProps(state.workspaceGroupProps);
+  }
+  return {
+    patient: state?.patient ?? null,
+    patientUuid: state?.patientUuid ?? patientUuid ?? null,
+    visitContext: state?.visitContext ?? null,
+  };
 }
 
 export interface PatientChartWorkspaceActionButtonProps {
@@ -31,31 +162,90 @@ export function launchPatientChartWithWorkspaceOpen({
   workspaceName,
   dashboardName,
   additionalProps,
+  windowProps,
 }: {
   patientUuid: string;
   workspaceName: string;
   dashboardName?: string;
   additionalProps?: object;
+  /** Window props to launch the workspace with. Workspaces that need the patient or visit read them from here. */
+  windowProps?: object;
 }) {
-  launchWorkspace2(workspaceName, additionalProps);
+  launchWorkspace2(workspaceName, additionalProps, windowProps);
   navigate({ to: '${openmrsSpaBase}/patient/' + `${patientUuid}/chart` + (dashboardName ? `/${dashboardName}` : '') });
 }
 
+/**
+ * Returns a callback that launches the workspace, first prompting the user to start a visit if the
+ * patient needs one. The patient / visit window props (see `getPatientChartWindowProps`) are supplied
+ * by default; any `windowProps` passed to the callback take precedence.
+ */
 export function useLaunchWorkspaceRequiringVisit<T extends object>(patientUuid: string, workspaceName: string) {
   const startVisitIfNeeded = useStartVisitIfNeeded(patientUuid);
   const launchPatientWorkspaceCb = useCallback(
     (workspaceProps?: T, windowProps?: any, groupProps?: any) => {
       startVisitIfNeeded().then((didStartVisit) => {
         if (didStartVisit) {
-          launchWorkspace2(workspaceName, workspaceProps, windowProps, groupProps);
+          // Read at launch time: the visit may have just been started by the prompt above.
+          launchWorkspace2(
+            workspaceName,
+            workspaceProps,
+            { ...getPatientChartWindowProps(patientUuid), ...windowProps },
+            groupProps,
+          );
         }
       });
     },
-    [startVisitIfNeeded, workspaceName],
+    [startVisitIfNeeded, workspaceName, patientUuid],
   );
   return launchPatientWorkspaceCb;
 }
 
+/**
+ * Props for an `ActionMenuButton2` that opens a workspace requiring a visit, bridging the group props
+ * the button receives to the window props the workspace takes:
+ *
+ * ```tsx
+ * <ActionMenuButton2 {...useActionMenuButtonLaunchProps(groupProps, 'order-basket')} icon={...} label={...} />
+ * ```
+ *
+ * `ActionMenuButton2` launches with the `workspaceToLaunch` of the render the button was clicked in. If the
+ * user starts a visit in the prompt, the chart relaunches its workspace group and the button re-renders, but
+ * that click handler still holds the old (visit-less) props. So when the visit changed during the prompt,
+ * `onBeforeWorkspaceLaunch` launches the workspace itself with the window props read after the prompt, and
+ * returns false so the button does not launch with the stale ones.
+ *
+ * TODO: remove the second launch path once `ActionMenuButton2` can take window props that are evaluated at
+ * launch time.
+ */
+export function useActionMenuButtonLaunchProps<T extends object>(
+  groupProps: PatientWorkspaceGroupProps,
+  workspaceName: string,
+  workspaceProps?: T,
+) {
+  const { patientUuid } = groupProps;
+  const startVisitIfNeeded = useStartVisitIfNeeded(patientUuid);
+  const windowProps = groupPropsToWindowProps(groupProps);
+  const visitUuid = windowProps.visitContext?.uuid;
+
+  const onBeforeWorkspaceLaunch = useCallback(async () => {
+    if (!(await startVisitIfNeeded())) {
+      return false;
+    }
+    const currentWindowProps = getPatientChartWindowProps(patientUuid);
+    if (currentWindowProps.visitContext?.uuid === visitUuid) {
+      return true;
+    }
+    launchWorkspace2(workspaceName, workspaceProps, currentWindowProps);
+    return false;
+  }, [startVisitIfNeeded, patientUuid, visitUuid, workspaceName, workspaceProps]);
+
+  return {
+    workspaceToLaunch: { workspaceName, workspaceProps, windowProps },
+    onBeforeWorkspaceLaunch,
+  };
+}
+
 export function useStartVisitIfNeeded(patientUuid: string) {
   const { visitContext, workspaceGroupVisitUuid } = usePatientChartStore(patientUuid);
   const { systemVisitEnabled } = useSystemVisitSetting();
@@ -106,6 +296,7 @@ export function useStartVisitIfNeeded(patientUuid: string) {
               resolve(false);
             },
             onVisitStarted: resolveOnceWorkspaceGroupHasVisit,
+            patientUuid,
           });
         }
       });