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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openmrs/esm-patient-common-lib",
-  "version": "11.3.1-patch.9310",
+  "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/form-entry/form-entry.ts

@@ -28,5 +28,6 @@ export interface FormRendererProps {
   preFilledQuestions?: Record<string, string>;
   launchChildWorkspace?: Workspace2DefinitionProps['launchChildWorkspace'];
   closeWorkspace?: Workspace2DefinitionProps['closeWorkspace'];
+  closeWorkspaceWithSavedChanges?: () => void;
   setHasUnsavedChanges?(hasUnsavedChanges: boolean);
 }

package/src/index.ts

@@ -4,6 +4,7 @@ export * from './dashboards/createDashboardLink';
 export * from './empty-state';
 export * from './error-state';
 export * from './form-entry/form-entry';
+export * from './results';
 export * from './launchStartVisitPrompt';
 export * from './offline/visit';
 export * from './orders';

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 };
 }
 
 export function postOrder(body: OrderPost, abortController?: AbortController) {
-  return openmrsFetch(`${restBaseUrl}/order`, {
+  return openmrsFetch<Order>(`${restBaseUrl}/order`, {
     method: 'POST',
     signal: abortController?.signal,
     headers: { 'Content-Type': 'application/json' },

package/src/orders/showOrderSuccessToast.ts

@@ -1,28 +1,86 @@
-import { showSnackbar } from '@openmrs/esm-framework';
-import { type TFunction } from 'i18next';
+import { showSnackbar, translateFrom } from '@openmrs/esm-framework';
 import { type OrderBasketItem } from './types';
 
-export function showOrderSuccessToast(t: TFunction, patientOrderItems: OrderBasketItem[]) {
-  const orderedString = patientOrderItems
-    .filter((item) => ['NEW', 'RENEW'].includes(item.action))
-    .map((item) => item.display)
-    .join(', ');
-  const updatedString = patientOrderItems
-    .filter((item) => item.action === 'REVISE')
-    .map((item) => item.display)
-    .join(', ');
-  const discontinuedString = patientOrderItems
-    .filter((item) => item.action === 'DISCONTINUE')
-    .map((item) => item.display)
-    .join(', ');
+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: t('orderCompleted', 'Placed orders'),
-    subtitle:
-      (orderedString && `${t('ordered', 'Placed order for')} ${orderedString}. `) +
-      (updatedString && `${t('updated', 'Updated')} ${updatedString}. `) +
-      (discontinuedString && `${t('discontinued', 'Discontinued')} ${discontinuedString}.`),
+    title,
+    subtitle: subtitleParts.join(' '),
   });
 }

package/src/orders/types/order.ts

@@ -47,8 +47,6 @@ export interface OrderBasketItem {
   action: OrderAction;
   display: string;
   uuid?: string;
-  orderer?: string;
-  careSetting?: string;
   orderError?: Error & {
     responseBody?: {
       error?: {
@@ -118,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>;
@@ -129,7 +127,7 @@ export interface Order {
   action: OrderAction;
   asNeeded: boolean;
   asNeededCondition?: string;
-  autoExpireDate: string;
+  autoExpireDate?: string | null;
   brandName?: string;
   careSetting: OpenmrsResource;
   commentToFulfiller: string;
@@ -137,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;
+  drug: Drug | null;
+  duration: number | null;
+  durationUnits: OpenmrsResource | null;
   encounter: Encounter;
-  frequency: OpenmrsResource;
+  frequency: OpenmrsResource | null;
   instructions?: string | null;
-  numRefills: number;
+  numRefills: number | null;
   orderNumber: string;
   orderReason: string | null;
   orderReasonNonCoded: string | null;
@@ -169,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;
 
@@ -211,10 +209,15 @@ export interface OrderType {
 
 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 {
@@ -226,21 +229,21 @@ export interface OrderBasketExtensionProps {
 
 export interface DrugOrderBasketItem extends OrderBasketItem {
   drug: Drug;
-  unit: DosingUnit;
+  unit: DosingUnit | null;
   commonMedicationName: string;
-  dosage: number;
-  frequency: MedicationFrequency;
-  route: MedicationRoute;
-  quantityUnits: QuantityUnit;
-  patientInstructions: string;
+  dosage: number | null;
+  frequency: MedicationFrequency | null;
+  route: MedicationRoute | null;
+  quantityUnits: QuantityUnit | null;
+  patientInstructions: string | null;
   asNeeded: boolean;
-  asNeededCondition: string;
+  asNeededCondition: string | null;
   startDate: Date | string;
-  durationUnit: DurationUnit;
+  durationUnit: DurationUnit | null;
   duration: number | null;
   pillsDispensed: number | null;
   numRefills: number | null;
-  indication: string;
+  indication: string | null;
   isFreeTextDosage: boolean;
   freeTextDosage: string;
   previousOrder?: string;
@@ -308,6 +311,7 @@ export interface TestOrderBasketItem extends OrderBasketItem {
 
 export interface OrderBasketWindowProps {
   encounterUuid: string;
+  onOrderBasketSubmitted?: (encounterUuid: string, postedOrders: Array<Order>) => void;
 }
 
 export interface ExportedOrderBasketWindowProps {
@@ -319,4 +323,5 @@ export interface ExportedOrderBasketWindowProps {
   patientUuid: string;
   visitContext: Visit;
   mutateVisitContext: () => void;
+  onOrderBasketSubmitted?: (encounterUuid: string, postedOrders: Array<Order>) => void;
 }

package/src/orders/useMutatePatientOrders.ts

@@ -1,6 +1,6 @@
-import { restBaseUrl } from '@openmrs/esm-framework';
 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.
@@ -12,9 +12,13 @@ export function useMutatePatientOrders(patientUuid: string) {
   const { mutate } = useSWRConfig();
   const mutateOrders = useCallback(
     () =>
-      mutate((key) => {
-        return typeof key === 'string' && key.startsWith(`${restBaseUrl}/order?patient=${patientUuid}`);
-      }),
+      mutate(
+        (key) => {
+          return typeof key === 'string' && key.startsWith(`${restBaseUrl}/order?patient=${patientUuid}`);
+        },
+        undefined,
+        { revalidate: true },
+      ),
     [patientUuid, mutate],
   );
 

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(

package/src/orders/useOrders.ts

@@ -15,6 +15,9 @@ export const drugCustomRepresentation =
   'frequency:ref,asNeeded,asNeededCondition,quantity,quantityUnits:ref,numRefills,dosingInstructions,' +
   'duration,durationUnits:ref,route:ref,brandName,dispenseAsWritten)';
 
+export const orderCustomRepresentation =
+  'custom:(uuid,display,orderNumber,accessionNumber,patient,concept,action,careSetting,previousOrder,dateActivated,scheduledDate,dateStopped,autoExpireDate,encounter:(uuid,display,visit),orderer:ref,orderReason,orderReasonNonCoded,orderType,urgency,instructions,commentToFulfiller,fulfillerStatus)';
+
 export function usePatientOrders(
   patientUuid: string,
   status?: Status,
@@ -23,10 +26,11 @@ export function usePatientOrders(
   endDate?: string,
 ) {
   const { mutate } = useSWRConfig();
+  const activeStatusParams = status === 'ACTIVE' ? '&excludeCanceledAndExpired=true' : '';
   const baseOrdersUrl =
     startDate && endDate
-      ? `${restBaseUrl}/order?patient=${patientUuid}&careSetting=${careSettingUuid}&v=default&activatedOnOrAfterDate=${startDate}&activatedOnOrBeforeDate=${endDate}`
-      : `${restBaseUrl}/order?patient=${patientUuid}&careSetting=${careSettingUuid}&v=default&status=${status}`;
+      ? `${restBaseUrl}/order?patient=${patientUuid}&careSetting=${careSettingUuid}&v=${orderCustomRepresentation}&activatedOnOrAfterDate=${startDate}&activatedOnOrBeforeDate=${endDate}&excludeDiscontinueOrders=true${activeStatusParams}`
+      : `${restBaseUrl}/order?patient=${patientUuid}&careSetting=${careSettingUuid}&v=${orderCustomRepresentation}&status=${status}&excludeDiscontinueOrders=true`;
   const ordersUrl = orderType ? `${baseOrdersUrl}&orderTypes=${orderType}` : baseOrdersUrl;
 
   const { data, error, isLoading, isValidating } = useSWR<FetchResponse<PatientOrderFetchResponse>, Error>(
@@ -36,8 +40,12 @@ export function usePatientOrders(
 
   const mutateOrders = useCallback(
     () =>
-      mutate((key) => typeof key === 'string' && key.startsWith(`${restBaseUrl}/order?patient=${patientUuid}`), data),
-    [data, mutate, patientUuid],
+      mutate(
+        (key) => typeof key === 'string' && key.startsWith(`${restBaseUrl}/order?patient=${patientUuid}`),
+        undefined,
+        { revalidate: true },
+      ),
+    [mutate, patientUuid],
   );
 
   const orders = useMemo(
@@ -63,6 +71,19 @@ export function getDrugOrderByUuid(orderUuid: string) {
   return openmrsFetch<Order>(`${restBaseUrl}/order/${orderUuid}?v=${drugCustomRepresentation}`);
 }
 
+export function useDrugOrderByUuid(orderUuid: string) {
+  const { data, error, isLoading } = useSWR<FetchResponse<Order>, Error>(
+    orderUuid ? `${restBaseUrl}/order/${orderUuid}?v=${drugCustomRepresentation}` : null,
+    openmrsFetch,
+  );
+
+  return {
+    data: data?.data ?? null,
+    error,
+    isLoading,
+  };
+}
+
 // See the Urgency enum in https://github.com/openmrs/openmrs-core/blob/492dcd35b85d48730bd19da48f6db146cc882c22/api/src/main/java/org/openmrs/Order.java
 export const priorityOptions: PriorityOption[] = [
   { value: 'ROUTINE', label: translateFrom(patientChartAppModuleName, 'Routine') },

package/src/results/helpers.test.ts

@@ -0,0 +1,123 @@
+import { type ReferenceRanges } from '../types';
+import { exist, formatReferenceRange, assessValue } from './helpers';
+
+describe('exist', () => {
+  it('returns true when all values are defined', () => {
+    expect(exist(1, 2, 3)).toBe(true);
+    expect(exist(0)).toBe(true);
+    expect(exist('')).toBe(true);
+  });
+
+  it('returns false when any value is null or undefined', () => {
+    expect(exist(null)).toBe(false);
+    expect(exist(undefined)).toBe(false);
+    expect(exist(1, null, 3)).toBe(false);
+    expect(exist(1, undefined)).toBe(false);
+  });
+
+  it('returns true for empty arguments', () => {
+    expect(exist()).toBe(true);
+  });
+});
+
+describe('formatReferenceRange', () => {
+  it('returns formatted range with en-dash', () => {
+    expect(formatReferenceRange({ lowNormal: 35, hiNormal: 147 })).toBe('35 – 147');
+  });
+
+  it('appends units from ranges object', () => {
+    expect(formatReferenceRange({ lowNormal: 35, hiNormal: 147, units: 'U/L' })).toBe('35 – 147 U/L');
+  });
+
+  it('appends units from parameter when ranges.units is absent', () => {
+    expect(formatReferenceRange({ lowNormal: 35, hiNormal: 147 }, 'mg/dL')).toBe('35 – 147 mg/dL');
+  });
+
+  it('prefers ranges.units over the units parameter', () => {
+    expect(formatReferenceRange({ lowNormal: 35, hiNormal: 147, units: 'U/L' }, 'mg/dL')).toBe('35 – 147 U/L');
+  });
+
+  it('returns -- when ranges is null', () => {
+    expect(formatReferenceRange(null)).toBe('--');
+  });
+
+  it('returns -- when lowNormal or hiNormal is missing', () => {
+    expect(formatReferenceRange({ lowNormal: 35 })).toBe('--');
+    expect(formatReferenceRange({ hiNormal: 147 })).toBe('--');
+    expect(formatReferenceRange({})).toBe('--');
+  });
+
+  it('handles zero values correctly', () => {
+    expect(formatReferenceRange({ lowNormal: 0, hiNormal: 10 })).toBe('0 – 10');
+  });
+});
+
+describe('assessValue', () => {
+  const fullRanges: ReferenceRanges = {
+    lowAbsolute: 0,
+    lowCritical: 10,
+    lowNormal: 35,
+    hiNormal: 100,
+    hiCritical: 150,
+    hiAbsolute: 200,
+  };
+
+  it('returns NORMAL for values within range', () => {
+    expect(assessValue(50, fullRanges)).toBe('NORMAL');
+    expect(assessValue(70, fullRanges)).toBe('NORMAL');
+  });
+
+  it('returns NORMAL for NaN', () => {
+    expect(assessValue(NaN, fullRanges)).toBe('NORMAL');
+  });
+
+  it('returns HIGH when value exceeds hiNormal', () => {
+    expect(assessValue(101, fullRanges)).toBe('HIGH');
+    expect(assessValue(149, fullRanges)).toBe('HIGH');
+  });
+
+  it('returns CRITICALLY_HIGH when value reaches hiCritical (inclusive)', () => {
+    expect(assessValue(150, fullRanges)).toBe('CRITICALLY_HIGH');
+    expect(assessValue(175, fullRanges)).toBe('CRITICALLY_HIGH');
+  });
+
+  it('returns OFF_SCALE_HIGH when value reaches hiAbsolute (inclusive)', () => {
+    expect(assessValue(200, fullRanges)).toBe('OFF_SCALE_HIGH');
+    expect(assessValue(999, fullRanges)).toBe('OFF_SCALE_HIGH');
+  });
+
+  it('returns LOW when value is below lowNormal', () => {
+    expect(assessValue(34, fullRanges)).toBe('LOW');
+    expect(assessValue(11, fullRanges)).toBe('LOW');
+  });
+
+  it('returns CRITICALLY_LOW when value reaches lowCritical (inclusive)', () => {
+    expect(assessValue(10, fullRanges)).toBe('CRITICALLY_LOW');
+    expect(assessValue(5, fullRanges)).toBe('CRITICALLY_LOW');
+  });
+
+  it('returns OFF_SCALE_LOW when value reaches lowAbsolute (inclusive)', () => {
+    expect(assessValue(0, fullRanges)).toBe('OFF_SCALE_LOW');
+    expect(assessValue(-5, fullRanges)).toBe('OFF_SCALE_LOW');
+  });
+
+  // Boundary behavior: normal thresholds are exclusive, critical/absolute are inclusive
+  it('treats values at hiNormal as NORMAL (exclusive)', () => {
+    expect(assessValue(100, fullRanges)).toBe('NORMAL');
+  });
+
+  it('treats values at lowNormal as NORMAL (exclusive)', () => {
+    expect(assessValue(35, fullRanges)).toBe('NORMAL');
+  });
+
+  it('works with only normal thresholds', () => {
+    const normalOnly: ReferenceRanges = { lowNormal: 35, hiNormal: 100 };
+    expect(assessValue(50, normalOnly)).toBe('NORMAL');
+    expect(assessValue(101, normalOnly)).toBe('HIGH');
+    expect(assessValue(34, normalOnly)).toBe('LOW');
+  });
+
+  it('returns NORMAL when no thresholds are provided', () => {
+    expect(assessValue(50, {})).toBe('NORMAL');
+  });
+});

package/src/results/helpers.ts

@@ -0,0 +1,63 @@
+import { type OBSERVATION_INTERPRETATION, type ReferenceRanges } from '../types';
+
+/**
+ * Checks if all provided values exist (are not null or undefined).
+ */
+export function exist(...args: unknown[]): boolean {
+  return args.every((y) => y !== null && y !== undefined);
+}
+
+/**
+ * Formats reference range as a string with optional units.
+ * Uses en-dash (–) for range separator.
+ *
+ * @param ranges - The reference ranges object
+ * @param units - Optional units string to append
+ * @returns Formatted string like "35 – 147 U/L" or "--" if no valid range
+ */
+export function formatReferenceRange(ranges: ReferenceRanges | null, units?: string): string {
+  if (!ranges) return '--';
+  const { lowNormal, hiNormal } = ranges;
+  const displayUnits = ranges.units || units || '';
+  if (exist(lowNormal, hiNormal)) {
+    return `${lowNormal} – ${hiNormal}${displayUnits ? ` ${displayUnits}` : ''}`;
+  }
+  return '--';
+}
+
+/**
+ * Determines the interpretation of a lab value based on reference ranges.
+ * Returns the appropriate interpretation level based on the value's
+ * relationship to normal, critical, and absolute thresholds.
+ *
+ * @param value - The numeric lab result value
+ * @param ranges - The reference ranges to compare against
+ * @returns The interpretation category
+ */
+export function assessValue(value: number, ranges: ReferenceRanges): OBSERVATION_INTERPRETATION {
+  if (isNaN(value)) {
+    return 'NORMAL';
+  }
+  // Critical and absolute thresholds use inclusive (>=, <=) comparisons
+  // because values at those boundaries should be flagged for clinical safety.
+  // Normal thresholds use exclusive (>, <) so values at the boundary are still normal.
+  if (exist(ranges.hiAbsolute) && value >= ranges.hiAbsolute!) {
+    return 'OFF_SCALE_HIGH';
+  }
+  if (exist(ranges.hiCritical) && value >= ranges.hiCritical!) {
+    return 'CRITICALLY_HIGH';
+  }
+  if (exist(ranges.hiNormal) && value > ranges.hiNormal!) {
+    return 'HIGH';
+  }
+  if (exist(ranges.lowAbsolute) && value <= ranges.lowAbsolute!) {
+    return 'OFF_SCALE_LOW';
+  }
+  if (exist(ranges.lowCritical) && value <= ranges.lowCritical!) {
+    return 'CRITICALLY_LOW';
+  }
+  if (exist(ranges.lowNormal) && value < ranges.lowNormal!) {
+    return 'LOW';
+  }
+  return 'NORMAL';
+}

package/src/results/index.ts

@@ -0,0 +1,3 @@
+export * from './helpers';
+export * from './useReferenceRanges';
+export { ReferenceRangeDisplay } from './reference-range-display.component';

package/src/results/reference-range-display.component.tsx

@@ -0,0 +1,25 @@
+import React from 'react';
+import { useTranslation } from 'react-i18next';
+import { type ReferenceRanges } from '../types';
+import { formatReferenceRange } from './helpers';
+import styles from './results.scss';
+
+interface ReferenceRangeDisplayProps {
+  ranges: ReferenceRanges | null;
+  units?: string;
+}
+
+/**
+ * Displays a formatted reference range with units.
+ * Shows "N/A" when no valid range is available.
+ */
+export const ReferenceRangeDisplay: React.FC<ReferenceRangeDisplayProps> = ({ ranges, units }) => {
+  const { t } = useTranslation();
+  const formatted = formatReferenceRange(ranges, units);
+
+  if (formatted === '--') {
+    return <span className={styles.noRange}>{t('notApplicable', 'N/A')}</span>;
+  }
+
+  return <span className={styles.referenceRange}>{formatted}</span>;
+};

package/src/results/results.scss

@@ -0,0 +1,11 @@
+@use '@carbon/colors';
+@use '@carbon/type';
+@use '@openmrs/esm-styleguide/src/vars' as *;
+
+.referenceRange {
+  @include type.type-style('body-compact-01');
+}
+
+.noRange {
+  color: colors.$gray-50;
+}

package/src/results/useReferenceRanges.ts

@@ -0,0 +1,72 @@
+import { useMemo } from 'react';
+import useSWR from 'swr';
+import { openmrsFetch, restBaseUrl, type FetchResponse } from '@openmrs/esm-framework';
+import { type ReferenceRanges } from '../types';
+
+interface ReferenceRangeResponse {
+  uuid: string;
+  concept: string;
+  lowNormal?: number;
+  hiNormal?: number;
+  lowAbsolute?: number;
+  hiAbsolute?: number;
+  lowCritical?: number;
+  hiCritical?: number;
+  units?: string;
+}
+
+export interface UseReferenceRangesResult {
+  ranges: Map<string, ReferenceRanges>;
+  isLoading: boolean;
+  error: Error | undefined;
+  mutate: () => void;
+}
+
+/**
+ * Fetches patient-specific reference ranges for given concepts.
+ * Uses the /conceptreferencerange REST API endpoint.
+ *
+ * @param patientUuid - The UUID of the patient (optional; when absent, no request is made)
+ * @param conceptUuids - Array of concept UUIDs to fetch ranges for
+ * @returns Object containing ranges map, loading state, error, and mutate function
+ */
+export function useReferenceRanges(
+  patientUuid: string | undefined,
+  conceptUuids: Array<string>,
+): UseReferenceRangesResult {
+  const conceptList = conceptUuids.filter(Boolean).join(',');
+  const apiUrl =
+    patientUuid && conceptList
+      ? `${restBaseUrl}/conceptreferencerange?patient=${patientUuid}&concept=${conceptList}&v=full`
+      : null;
+
+  const { data, error, isLoading, mutate } = useSWR<FetchResponse<{ results: Array<ReferenceRangeResponse> }>, Error>(
+    apiUrl,
+    openmrsFetch,
+  );
+
+  const rangesMap = useMemo(() => {
+    const map = new Map<string, ReferenceRanges>();
+    data?.data?.results?.forEach((range) => {
+      if (range.concept) {
+        map.set(range.concept, {
+          lowNormal: range.lowNormal,
+          hiNormal: range.hiNormal,
+          lowAbsolute: range.lowAbsolute,
+          hiAbsolute: range.hiAbsolute,
+          lowCritical: range.lowCritical,
+          hiCritical: range.hiCritical,
+          units: range.units,
+        });
+      }
+    });
+    return map;
+  }, [data]);
+
+  return {
+    ranges: rangesMap,
+    isLoading,
+    error,
+    mutate,
+  };
+}

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

@@ -16,7 +16,7 @@ const patientChartStore = createGlobalStore<PatientChartStore>(patientChartStore
   mutateVisitContext: null,
 });
 
-const patientCharStoreActions = {
+const patientChartStoreActions = {
   setPatient(_, patient: fhir.Patient) {
     return { patient, patientUuid: patient?.id ?? null };
   },
@@ -33,11 +33,11 @@ const patientCharStoreActions = {
  * the clinical forms workspace in the ward app)
  * should have the patient / visitContext explicitly passed in as props.
  *
- * As a safety feature, this hook requires the the patientUuid as the input, and only
+ * As a safety feature, this hook requires the patientUuid as the input, and only
  * returns the actual store values if input patientUuid matches that in the store.
  */
 export function usePatientChartStore(patientUuid: string) {
-  const store = useStoreWithActions(patientChartStore, patientCharStoreActions);
+  const store = useStoreWithActions(patientChartStore, patientChartStoreActions);
   if (store.patientUuid === patientUuid) {
     return store;
   } else {

package/src/types/test-results.ts

@@ -39,8 +39,19 @@ export type OBSERVATION_INTERPRETATION =
   | 'LOW'
   | 'CRITICALLY_LOW'
   | 'OFF_SCALE_LOW'
+  // Legacy sentinel for "no data"; avoid new usage and prefer undefined instead.
   | '--';
 
+export interface ReferenceRanges {
+  hiAbsolute?: number;
+  hiCritical?: number;
+  hiNormal?: number;
+  lowAbsolute?: number;
+  lowCritical?: number;
+  lowNormal?: number;
+  units?: string;
+}
+
 export interface ExternalOverviewProps {
   patientUuid: string;
   filter: (filterProps: PanelFilterProps) => boolean;

package/src/visit/revalidation-utils.test.ts

@@ -2,6 +2,7 @@ import {
   invalidateVisitHistory,
   invalidatePatientEncounters,
   invalidateVisitAndEncounterData,
+  invalidateCurrentVisit,
 } from './revalidation-utils';
 
 const mockMutate = jest.fn();
@@ -95,4 +96,30 @@ describe('revalidation-utils', () => {
       expect(encounterMatcherFn('/ws/rest/v1/encounter?patient=test-patient-123&v=custom')).toBe(true);
     });
   });
+
+  describe('invalidateCurrentVisit', () => {
+    it('should invalidate only current visit keys', () => {
+      const patientUuid = 'test-patient-123';
+
+      invalidateCurrentVisit(mockMutate, patientUuid);
+
+      expect(mockMutate).toHaveBeenCalledTimes(1);
+      expect(mockMutate).toHaveBeenCalledWith(expect.any(Function));
+
+      const matcherFn = mockMutate.mock.calls[0][0];
+
+      // Should match current visit key (includeInactive=false)
+      expect(matcherFn('/ws/rest/v1/visit?patient=test-patient-123&v=custom&includeInactive=false')).toBe(true);
+
+      // Should not match other visit keys
+      expect(matcherFn('/ws/rest/v1/visit?patient=test-patient-123&v=custom&includeInactive=true')).toBe(false);
+      expect(
+        matcherFn('/ws/rest/v1/visit?patient=test-patient-123&v=custom&limit=10&startIndex=0&totalCount=true'),
+      ).toBe(false);
+      expect(matcherFn('/ws/rest/v1/visit/test-patient-123')).toBe(false);
+
+      // Should not match encounter keys
+      expect(matcherFn('/ws/rest/v1/encounter?patient=test-patient-123&v=custom')).toBe(false);
+    });
+  });
 });

package/src/visit/revalidation-utils.ts

@@ -81,6 +81,24 @@ export function invalidatePatientEncounters(mutate: KeyedMutator<unknown>, patie
   });
 }
 
+/**
+ * Invalidates only the current (active) visit cache for a specific patient.
+ *
+ * This refreshes components using useVisit without triggering the visit revalidation cascade.
+ *
+ * @param mutate - SWR mutate function from useSWRConfig()
+ * @param patientUuid - Patient UUID to target current visit data for
+ */
+export function invalidateCurrentVisit(mutate: KeyedMutator<unknown>, patientUuid: string): void {
+  mutate((key) => {
+    return (
+      typeof key === 'string' &&
+      key.includes(`${restBaseUrl}/visit?patient=${patientUuid}`) &&
+      key.includes('includeInactive=false')
+    );
+  });
+}
+
 /**
  * Combination utility that invalidates both visit history and encounter data.
  *

package/src/visit/visit-mutations.ts

@@ -30,7 +30,7 @@ export function useOptimisticVisitMutations(patientUuid: string) {
     (visitUuid: string, updates: Partial<Visit>) => {
       // Update current visit SWR cache if it matches
       if (visitContext?.uuid === visitUuid) {
-        mutateVisitContext();
+        mutateVisitContext?.();
       }
 
       // Update visit lists across all hooks using regex pattern matching
@@ -82,7 +82,7 @@ export function useOptimisticVisitMutations(patientUuid: string) {
 
       // If deleted visit was current, revalidate current visit to get new state
       if (visitContext?.uuid === visitUuid) {
-        mutateVisitContext();
+        mutateVisitContext?.();
       }
     },
     [visitContext, mutateVisitContext, mutate, patientUuid],

package/src/workspaces.ts

@@ -21,8 +21,10 @@ export interface PatientChartWorkspaceActionButtonProps {
   groupProps: PatientWorkspaceGroupProps;
 }
 
-export interface PatientWorkspace2DefinitionProps<WorkspaceProps extends Object, WindowProps extends Object>
-  extends Workspace2DefinitionProps<WorkspaceProps, WindowProps, PatientWorkspaceGroupProps> {}
+export type PatientWorkspace2DefinitionProps<
+  WorkspaceProps extends object,
+  WindowProps extends object,
+> = Workspace2DefinitionProps<WorkspaceProps, WindowProps, PatientWorkspaceGroupProps>;
 
 export function launchPatientChartWithWorkspaceOpen({
   patientUuid,
@@ -45,7 +47,7 @@ export function useLaunchWorkspaceRequiringVisit<T extends object>(patientUuid:
     (workspaceProps?: T, windowProps?: any, groupProps?: any) => {
       startVisitIfNeeded().then((didStartVisit) => {
         if (didStartVisit) {
-          launchWorkspace2(workspaceName, workspaceProps, windowProps);
+          launchWorkspace2(workspaceName, workspaceProps, windowProps, groupProps);
         }
       });
     },