@openmrs/esm-patient-common-lib 11.3.1-patch.9508 → 11.3.1-pre.10001

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openmrs/esm-patient-common-lib",
-  "version": "11.3.1-patch.9508",
+  "version": "11.3.1-pre.10001",
   "license": "MPL-2.0",
   "description": "Library for common patient chart components",
   "browser": "dist/openmrs-esm-patient-common-lib.js",
@@ -30,7 +30,7 @@
   },
   "dependencies": {
     "@carbon/react": "^1.83.0",
-    "lodash-es": "^4.17.21",
+    "lodash-es": "^4.17.23",
     "uuid": "^8.3.2"
   },
   "peerDependencies": {

package/src/empty-state/empty-state.test.tsx

@@ -1,10 +1,10 @@
 import React from 'react';
 import userEvent from '@testing-library/user-event';
 import { render, screen } from '@testing-library/react';
-import { launchWorkspace } from '@openmrs/esm-framework';
+import { launchWorkspace2 } from '@openmrs/esm-framework';
 import { EmptyState } from '.';
 
-const mockLaunchWorkspace = jest.mocked(launchWorkspace);
+const mockLaunchWorkspace = jest.mocked(launchWorkspace2);
 
 describe('EmptyState', () => {
   it('renders an empty state widget card', () => {
@@ -12,7 +12,7 @@ describe('EmptyState', () => {
       <EmptyState
         headerTitle="appointments"
         displayText="appointments"
-        launchForm={() => launchWorkspace('sample-form-workspace')}
+        launchForm={() => launchWorkspace2('sample-form-workspace')}
       />,
     );
 
@@ -28,7 +28,7 @@ describe('EmptyState', () => {
       <EmptyState
         headerTitle="appointments"
         displayText="appointments"
-        launchForm={() => launchWorkspace('sample-form-workspace')}
+        launchForm={() => launchWorkspace2('sample-form-workspace')}
       />,
     );
 

package/src/form-entry/form-entry.ts

@@ -1,4 +1,4 @@
-import { type HtmlFormEntryForm } from '../types';
+import { type Encounter, type Visit, type Workspace2DefinitionProps } from '@openmrs/esm-framework';
 
 export interface FormEntryProps {
   encounterUuid?: string;
@@ -7,6 +7,27 @@ export interface FormEntryProps {
   visitTypeUuid?: string;
   visitStartDatetime?: string;
   visitStopDatetime?: string;
-  htmlForm?: HtmlFormEntryForm;
   additionalProps?: Record<string, any>;
 }
+
+/**
+ * Workspace control props are made optional to support usage in non-workspace contexts,
+ * such as the Fast Data Entry app or other standalone form zones.
+ */
+export interface FormRendererProps {
+  additionalProps?: Record<string, any>;
+  encounterUuid?: string;
+  formUuid: string;
+  patientUuid: string;
+  patient: fhir.Patient;
+  visit?: Visit;
+  visitUuid?: string;
+  hideControls?: boolean;
+  hidePatientBanner?: boolean;
+  handlePostResponse?: (encounter: Encounter) => void;
+  preFilledQuestions?: Record<string, string>;
+  launchChildWorkspace?: Workspace2DefinitionProps['launchChildWorkspace'];
+  closeWorkspace?: Workspace2DefinitionProps['closeWorkspace'];
+  closeWorkspaceWithSavedChanges?: () => void;
+  setHasUnsavedChanges?(hasUnsavedChanges: boolean);
+}

package/src/index.ts

@@ -3,8 +3,8 @@ export * from './compare';
 export * from './dashboards/createDashboardLink';
 export * from './empty-state';
 export * from './error-state';
-export * from './form-entry-interop';
 export * from './form-entry/form-entry';
+export * from './results';
 export * from './launchStartVisitPrompt';
 export * from './offline/visit';
 export * from './orders';

package/src/launchStartVisitPrompt.tsx

@@ -1,7 +1,8 @@
 import { showModal } from '@openmrs/esm-framework';
 
-export function launchStartVisitPrompt() {
+export async function launchStartVisitPrompt(onVisitStarted?: () => void) {
   const dispose = showModal('start-visit-dialog', {
     closeModal: () => dispose(),
+    onVisitStarted,
   });
 }

package/src/orders/index.ts

@@ -1,7 +1,9 @@
-export * from './useOrderBasket';
 export * from './postOrders';
-export * from './useOrders';
+export * from './showOrderSuccessToast';
 export * from './types';
+export * from './useMutatePatientOrders';
+export * from './useOrderBasket';
 export * from './useOrderableConceptSets';
+export * from './useOrders';
 export * from './useOrderType';
 export * from './useOrderTypes';

package/src/orders/postOrders.ts

@@ -1,5 +1,6 @@
 import {
   type Concept,
+  type Encounter,
   openmrsFetch,
   type OpenmrsResource,
   parseDate,
@@ -7,20 +8,28 @@ import {
   type Visit,
 } from '@openmrs/esm-framework';
 import { type OrderBasketStore, orderBasketStore } from './store';
-import type {
-  DrugOrderPost,
-  TestOrderPost,
-  ExtractedOrderErrorObject,
-  OrderBasketItem,
-  OrderErrorObject,
-  OrderPost,
-} from './types';
+import type { ExtractedOrderErrorObject, Order, OrderBasketItem, OrderErrorObject, OrderPost } from './types';
+
+function getOrdersPayloadFromOrderBasket(patientUuid: string, ordererUuid: string) {
+  const { items, postDataPrepFunctions }: OrderBasketStore = orderBasketStore.getState();
+  const patientItems = items[patientUuid];
+
+  const orders: Array<OrderPost> = [];
+  Object.entries(patientItems).forEach(([grouping, groupOrders]) => {
+    groupOrders.forEach((order) => {
+      orders.push(postDataPrepFunctions[grouping](order, patientUuid, null, ordererUuid));
+    });
+  });
+
+  return orders;
+}
 
 export async function postOrdersOnNewEncounter(
   patientUuid: string,
   orderEncounterType: string,
   currentVisit: Visit | null,
-  sessionLocationUuid: string,
+  orderLocationUuid: string,
+  ordererUuid: string,
   abortController?: AbortController,
 
   /**
@@ -29,36 +38,23 @@ export async function postOrdersOnNewEncounter(
    */
   encounterDate?: Date,
 ) {
-  const now = new Date();
-  const visitStartDate = parseDate(currentVisit?.startDatetime);
-  const visitEndDate = parseDate(currentVisit?.stopDatetime);
   if (!encounterDate) {
-    if (!currentVisit || (visitStartDate < now && (!visitEndDate || visitEndDate > now))) {
-      encounterDate = now;
+    if (currentVisit?.stopDatetime) {
+      encounterDate = parseDate(currentVisit.startDatetime);
     } else {
-      console.warn(
-        'postOrdersOnNewEncounter received an active visit that is not currently active. This is a programming error. Attempting to place the order using the visit start date.',
-      );
-      encounterDate = visitStartDate;
+      encounterDate = null;
     }
   }
 
-  const { items, postDataPrepFunctions }: OrderBasketStore = orderBasketStore.getState();
-  const patientItems = items[patientUuid];
-
-  const orders: Array<DrugOrderPost | TestOrderPost> = [];
-
-  Object.entries(patientItems).forEach(([grouping, groupOrders]) => {
-    groupOrders.forEach((order) => {
-      orders.push(postDataPrepFunctions[grouping](order, patientUuid, null));
-    });
-  });
+  const orders = getOrdersPayloadFromOrderBasket(patientUuid, ordererUuid);
 
   const encounterPostData: EncounterPost = {
     patient: patientUuid,
-    location: sessionLocationUuid,
+    location: orderLocationUuid,
     encounterType: orderEncounterType,
-    encounterDatetime: encounterDate,
+    // only specify the encounterDatetime if it's given, otherwise
+    // don't specify that let the server default it to `now`
+    ...(encounterDate ? { encounterDatetime: encounterDate } : {}),
     visit: currentVisit?.uuid,
     obs: [],
     orders,
@@ -75,53 +71,70 @@ export interface EncounterPost {
   patient: string;
   location: string;
   encounterType: string;
-  encounterDatetime: Date;
+  encounterDatetime?: Date;
   visit?: string;
   obs: ObsPayload[];
   orders: OrderPost[];
 }
 
 export async function postEncounter(encounterPostData: EncounterPost, abortController?: AbortController) {
-  return openmrsFetch<OpenmrsResource>(`${restBaseUrl}/encounter`, {
+  return openmrsFetch<Encounter>(`${restBaseUrl}/encounter`, {
     headers: {
       'Content-Type': 'application/json',
     },
     method: 'POST',
     body: encounterPostData,
     signal: abortController?.signal,
-  }).then((res) => res?.data?.uuid);
+  }).then((res) => res?.data);
 }
 
-export async function postOrders(patientUuid: string, encounterUuid: string, abortController: AbortController) {
+export async function postOrders(
+  patientUuid: string,
+  encounterUuid: string,
+  abortController: AbortController,
+  ordererUuid: string,
+) {
   const { items, postDataPrepFunctions }: OrderBasketStore = orderBasketStore.getState();
   const patientItems = items[patientUuid];
 
   const erroredItems: Array<OrderBasketItem> = [];
-  for (let grouping in patientItems) {
+  const postedOrders: Array<Order> = [];
+  const promises: Array<Promise<void>> = [];
+
+  for (const grouping in patientItems) {
     const orders = patientItems[grouping];
+    const dataPrepFn = postDataPrepFunctions[grouping];
+
+    if (typeof dataPrepFn !== 'function') {
+      console.warn(`The postDataPrep function registered for ${grouping} orders is not a function`);
+      continue;
+    }
+
     for (let i = 0; i < orders.length; i++) {
       const order = orders[i];
-      const dataPrepFn = postDataPrepFunctions[grouping];
-
-      if (typeof dataPrepFn !== 'function') {
-        console.warn(`The postDataPrep function registered for ${grouping} orders is not a function`);
-        continue;
-      }
-
-      await postOrder(dataPrepFn(order, patientUuid, encounterUuid), abortController).catch((error) => {
-        erroredItems.push({
-          ...order,
-          orderError: error,
-          extractedOrderError: extractErrorDetails(error),
+
+      const promise = postOrder(dataPrepFn(order, patientUuid, encounterUuid, ordererUuid), abortController)
+        .then((response) => {
+          postedOrders.push(response.data);
+        })
+        .catch((error) => {
+          erroredItems.push({
+            ...order,
+            orderError: error,
+            extractedOrderError: extractErrorDetails(error),
+          });
         });
-      });
+
+      promises.push(promise);
     }
   }
-  return erroredItems;
+  await Promise.allSettled(promises);
+
+  return { postedOrders, erroredItems };
 }
 
-function postOrder(body: OrderPost, abortController?: AbortController) {
-  return openmrsFetch(`${restBaseUrl}/order`, {
+export function postOrder(body: OrderPost, abortController?: AbortController) {
+  return openmrsFetch<Order>(`${restBaseUrl}/order`, {
     method: 'POST',
     signal: abortController?.signal,
     headers: { 'Content-Type': 'application/json' },

package/src/orders/showOrderSuccessToast.ts

@@ -0,0 +1,86 @@
+import { showSnackbar, translateFrom } from '@openmrs/esm-framework';
+import { type OrderBasketItem } from './types';
+
+type OrderAction = 'placed' | 'updated' | 'discontinued';
+
+function getNotificationTitle(
+  moduleName: string,
+  placedOrders: OrderBasketItem[],
+  updatedOrders: OrderBasketItem[],
+  discontinuedOrders: OrderBasketItem[],
+  activeActions: OrderAction[],
+): string {
+  if (activeActions.length > 1) {
+    return translateFrom(moduleName, 'ordersCompleted', 'Orders completed');
+  }
+
+  const action = activeActions[0];
+
+  if (action === 'placed') {
+    return placedOrders.length === 1
+      ? translateFrom(moduleName, 'orderPlaced', 'Order placed')
+      : translateFrom(moduleName, 'ordersPlaced', 'Orders placed');
+  }
+
+  if (action === 'updated') {
+    return updatedOrders.length === 1
+      ? translateFrom(moduleName, 'orderUpdated', 'Order updated')
+      : translateFrom(moduleName, 'ordersUpdated', 'Orders updated');
+  }
+
+  // action === 'discontinued'
+  return discontinuedOrders.length === 1
+    ? translateFrom(moduleName, 'orderDiscontinued', 'Order discontinued')
+    : translateFrom(moduleName, 'ordersDiscontinued', 'Orders discontinued');
+}
+
+/**
+ * Shows a success toast notification for order operations.
+ * The notification title dynamically reflects the action(s) taken (placed, updated, discontinued)
+ * and whether it's singular or plural.
+ *
+ * @param moduleName - The module name (e.g., '@openmrs/esm-patient-orders-app') to use for translations
+ * @param patientOrderItems - Array of order basket items that were processed
+ */
+export function showOrderSuccessToast(moduleName: string, patientOrderItems: OrderBasketItem[]) {
+  if (patientOrderItems.length === 0) {
+    return;
+  }
+
+  const placedOrders = patientOrderItems.filter((item) => ['NEW', 'RENEW'].includes(item.action));
+  const updatedOrders = patientOrderItems.filter((item) => item.action === 'REVISE');
+  const discontinuedOrders = patientOrderItems.filter((item) => item.action === 'DISCONTINUE');
+
+  const orderedString = placedOrders.map((item) => item.display).join(', ');
+  const updatedString = updatedOrders.map((item) => item.display).join(', ');
+  const discontinuedString = discontinuedOrders.map((item) => item.display).join(', ');
+
+  const activeActions: OrderAction[] = [
+    orderedString && 'placed',
+    updatedString && 'updated',
+    discontinuedString && 'discontinued',
+  ].filter(Boolean) as OrderAction[];
+
+  const title = getNotificationTitle(moduleName, placedOrders, updatedOrders, discontinuedOrders, activeActions);
+
+  const subtitleParts: string[] = [];
+
+  if (orderedString) {
+    subtitleParts.push(`${translateFrom(moduleName, 'orderedFor', 'Placed order for')} ${orderedString}.`);
+  }
+
+  if (updatedString) {
+    subtitleParts.push(`${translateFrom(moduleName, 'updated', 'Updated')} ${updatedString}.`);
+  }
+
+  if (discontinuedString) {
+    subtitleParts.push(`${translateFrom(moduleName, 'discontinued', 'Discontinued')} ${discontinuedString}.`);
+  }
+
+  showSnackbar({
+    isLowContrast: true,
+    kind: 'success',
+    title,
+    subtitle: subtitleParts.join(' '),
+  });
+}

package/src/orders/types/order.ts

@@ -1,4 +1,4 @@
-import type { OpenmrsResource } from '@openmrs/esm-framework';
+import type { Encounter, OpenmrsResource, Visit, Workspace2DefinitionProps } from '@openmrs/esm-framework';
 
 export interface Concept extends OpenmrsResource {
   name?: {
@@ -47,8 +47,6 @@ export interface OrderBasketItem {
   action: OrderAction;
   display: string;
   uuid?: string;
-  orderer?: string;
-  careSetting?: string;
   orderError?: Error & {
     responseBody?: {
       error?: {
@@ -71,6 +69,8 @@ export interface OrderBasketItem {
   orderType?: string;
   orderNumber?: string;
   scheduledDate?: Date;
+  encounterUuid?: string;
+  visit: Visit;
 }
 
 export type OrderUrgency = 'ROUTINE' | 'STAT' | 'ON_SCHEDULED_DATE';
@@ -116,7 +116,7 @@ export interface DrugOrderPost extends OrderPost {
   dosingInstructions?: string;
 }
 
-export interface TestOrderPost extends OrderPost {}
+export type TestOrderPost = OrderPost;
 
 export interface PatientOrderFetchResponse {
   results: Array<Order>;
@@ -127,7 +127,7 @@ export interface Order {
   action: OrderAction;
   asNeeded: boolean;
   asNeededCondition?: string;
-  autoExpireDate: string;
+  autoExpireDate?: string | null;
   brandName?: string;
   careSetting: OpenmrsResource;
   commentToFulfiller: string;
@@ -135,17 +135,17 @@ export interface Order {
   dateActivated: string;
   dateStopped?: string | null;
   dispenseAsWritten: boolean;
-  dose: number;
-  doseUnits: OpenmrsResource;
+  dose: number | null;
+  doseUnits: OpenmrsResource | null;
   dosingInstructions: string | null;
   dosingType?: 'org.openmrs.FreeTextDosingInstructions' | 'org.openmrs.SimpleDosingInstructions';
-  drug: Drug;
-  duration: number;
-  durationUnits: OpenmrsResource;
-  encounter: OpenmrsResource;
-  frequency: OpenmrsResource;
+  drug: Drug | null;
+  duration: number | null;
+  durationUnits: OpenmrsResource | null;
+  encounter: Encounter;
+  frequency: OpenmrsResource | null;
   instructions?: string | null;
-  numRefills: number;
+  numRefills: number | null;
   orderNumber: string;
   orderReason: string | null;
   orderReasonNonCoded: string | null;
@@ -167,9 +167,9 @@ export interface Order {
   };
   patient: OpenmrsResource;
   previousOrder: { uuid: string; type: string; display: string } | null;
-  quantity: number;
-  quantityUnits: OpenmrsResource;
-  route: OpenmrsResource;
+  quantity: number | null;
+  quantityUnits: OpenmrsResource | null;
+  route: OpenmrsResource | null;
   scheduleDate: null;
   urgency: OrderUrgency;
 
@@ -207,16 +207,121 @@ export interface OrderType {
   description: string;
 }
 
-export type FulfillerStatus =
-  | 'RECEIVED'
-  | 'IN_PROGRESS'
-  | 'EXCEPTION'
-  | 'ON_HOLD'
-  | 'DECLINED'
-  | 'COMPLETED';
+export type FulfillerStatus = 'RECEIVED' | 'IN_PROGRESS' | 'EXCEPTION' | 'ON_HOLD' | 'DECLINED' | 'COMPLETED';
 
+/**
+ * A function type that converts a OrderBasketItem into
+ * a POST order payload
+ */
 export type PostDataPrepFunction = (
   order: OrderBasketItem,
   patientUuid: string,
   encounterUuid: string | null,
+  orderingProviderUuid: string,
 ) => OrderPost;
+
+export interface OrderBasketExtensionProps {
+  patient: fhir.Patient;
+  launchDrugOrderForm(order?: DrugOrderBasketItem): void;
+  launchLabOrderForm(orderTypeUuid: string, order?: TestOrderBasketItem): void;
+  launchGeneralOrderForm(orderTypeUuid: string, order?: OrderBasketItem): void;
+}
+
+export interface DrugOrderBasketItem extends OrderBasketItem {
+  drug: Drug;
+  unit: DosingUnit | null;
+  commonMedicationName: string;
+  dosage: number | null;
+  frequency: MedicationFrequency | null;
+  route: MedicationRoute | null;
+  quantityUnits: QuantityUnit | null;
+  patientInstructions: string | null;
+  asNeeded: boolean;
+  asNeededCondition: string | null;
+  startDate: Date | string;
+  durationUnit: DurationUnit | null;
+  duration: number | null;
+  pillsDispensed: number | null;
+  numRefills: number | null;
+  indication: string | null;
+  isFreeTextDosage: boolean;
+  freeTextDosage: string;
+  previousOrder?: string;
+  template?: OrderTemplate;
+}
+
+export interface DrugOrderTemplate {
+  uuid: string;
+  name: string;
+  drug: Drug;
+  template: OrderTemplate;
+}
+
+export interface OrderTemplate {
+  type: string;
+  dosingType: string;
+  dosingInstructions: DosingInstructions;
+}
+
+export interface DosingInstructions {
+  dose: Array<MedicationDosage>;
+  units: Array<DosingUnit>;
+  route: Array<MedicationRoute>;
+  frequency: Array<MedicationFrequency>;
+  instructions?: Array<MedicationInstructions>;
+  durationUnits?: Array<DurationUnit>;
+  quantityUnits?: Array<QuantityUnit>;
+  asNeeded?: boolean;
+  asNeededCondition?: string;
+}
+
+export interface MedicationDosage extends Omit<CommonMedicationProps, 'value'> {
+  value: number;
+}
+
+export type MedicationFrequency = CommonMedicationValueCoded;
+
+export type MedicationRoute = CommonMedicationValueCoded;
+
+export type MedicationInstructions = CommonMedicationProps;
+
+export type DosingUnit = CommonMedicationValueCoded;
+
+export type QuantityUnit = CommonMedicationValueCoded;
+
+export type DurationUnit = CommonMedicationValueCoded;
+
+interface CommonMedicationProps {
+  value: string;
+  default?: boolean;
+}
+
+export interface CommonMedicationValueCoded extends CommonMedicationProps {
+  valueCoded: string;
+  names?: string[];
+}
+export interface TestOrderBasketItem extends OrderBasketItem {
+  testType: {
+    label: string;
+    conceptUuid: string;
+  };
+  orderReason?: string;
+  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;
+  patient: fhir.Patient;
+  patientUuid: string;
+  visitContext: Visit;
+  mutateVisitContext: () => void;
+  onOrderBasketSubmitted?: (encounterUuid: string, postedOrders: Array<Order>) => void;
+}

package/src/orders/useMutatePatientOrders.ts

@@ -0,0 +1,28 @@
+import { useCallback } from 'react';
+import { useSWRConfig } from 'swr';
+import { restBaseUrl } from '@openmrs/esm-framework';
+
+/**
+ * Returns a function which refreshes the patient orders cache. Uses SWR's mutate function.
+ * Refreshes patient orders for all kinds of orders.
+ *
+ * @param patientUuid The UUID of the patient to get an order mutate function for.
+ */
+export function useMutatePatientOrders(patientUuid: string) {
+  const { mutate } = useSWRConfig();
+  const mutateOrders = useCallback(
+    () =>
+      mutate(
+        (key) => {
+          return typeof key === 'string' && key.startsWith(`${restBaseUrl}/order?patient=${patientUuid}`);
+        },
+        undefined,
+        { revalidate: true },
+      ),
+    [patientUuid, mutate],
+  );
+
+  return {
+    mutate: mutateOrders,
+  };
+}

package/src/orders/useOrderTypes.ts

@@ -1,7 +1,7 @@
-import { type FetchResponse, openmrsFetch, restBaseUrl } from '@openmrs/esm-framework';
+import { useMemo } from 'react';
 import useSWRImmutable from 'swr/immutable';
+import { type FetchResponse, openmrsFetch, restBaseUrl } from '@openmrs/esm-framework';
 import type { OrderTypeFetchResponse } from './types';
-import { useMemo } from 'react';
 
 export function useOrderTypes() {
   const orderTypesUrl = `${restBaseUrl}/ordertype`;

package/src/orders/useOrderableConceptSets.ts

@@ -60,7 +60,7 @@ function useOrderableConceptSWR(searchTerm: string, orderableConceptSets?: Array
   };
 }
 
-export interface OrderableConcept extends OpenmrsResource {}
+export type OrderableConcept = OpenmrsResource;
 
 export function useOrderableConceptSets(searchTerm: string, orderableConcepts: Array<string>) {
   const { data, isLoading, error } = useOrderableConceptSWR(