From e39ca1211935ca2eb95a2df71cee4ee317e9d811 Mon Sep 17 00:00:00 2001
From: chibongho <cbho@pih.org>
Date: Fri, 14 Jun 2024 09:02:47 -0400
Subject: [PATCH] (feat) O3-3416 make useVisit() take in optional custom
 representation (#1042)

---
 .../apps/esm-login-app/translations/en.json   |  1 -
 .../src/shared-api-objects/visit-utils.ts     | 11 ++-
 packages/framework/esm-framework/docs/API.md  | 97 ++++++++++++++-----
 .../esm-framework/docs/enums/VisitMode.md     |  6 +-
 .../esm-framework/docs/enums/VisitStatus.md   |  4 +-
 .../docs/interfaces/VisitItem.md              |  8 +-
 .../docs/interfaces/VisitStoreState.md        |  4 +-
 .../framework/esm-react-utils/src/useVisit.ts |  7 +-
 8 files changed, 94 insertions(+), 44 deletions(-)

diff --git a/packages/apps/esm-login-app/translations/en.json b/packages/apps/esm-login-app/translations/en.json
index c0cc196ba..9026532d8 100644
--- a/packages/apps/esm-login-app/translations/en.json
+++ b/packages/apps/esm-login-app/translations/en.json
@@ -1,7 +1,6 @@
 {
   "back": "Back",
   "backToUserNameIconLabel": "Back to username",
-  "cancel": "Cancel",
   "change": "Change",
   "continue": "Continue",
   "errorLoadingLoginLocations": "Error loading login locations",
diff --git a/packages/framework/esm-api/src/shared-api-objects/visit-utils.ts b/packages/framework/esm-api/src/shared-api-objects/visit-utils.ts
index 228ad6b13..729358a29 100644
--- a/packages/framework/esm-api/src/shared-api-objects/visit-utils.ts
+++ b/packages/framework/esm-api/src/shared-api-objects/visit-utils.ts
@@ -7,13 +7,16 @@ import type { FetchResponse, NewVisitPayload, UpdateVisitPayload, Visit } from '
 import { getGlobalStore } from '@openmrs/esm-state';
 
 export const defaultVisitCustomRepresentation =
-  'custom:(uuid,encounters:(uuid,encounterDatetime,' +
+  'custom:(uuid,display,voided,indication,startDatetime,stopDatetime,' +
+  'encounters:(uuid,display,encounterDatetime,' +
   'form:(uuid,name),location:ref,' +
-  'encounterType:ref,encounterProviders:(uuid,display,' +
-  'provider:(uuid,display))),patient:(uuid,uuid),' +
+  'encounterType:ref,' +
+  'encounterProviders:(uuid,display,' +
+  'provider:(uuid,display))),' +
+  'patient:(uuid,display),' +
   'visitType:(uuid,name,display),' +
   'attributes:(uuid,display,attributeType:(name,datatypeClassname,uuid),value),' +
-  'location:(uuid,name,display),startDatetime,stopDatetime)';
+  'location:(uuid,name,display))';
 
 export interface VisitStoreState {
   patientUuid: string | null;
diff --git a/packages/framework/esm-framework/docs/API.md b/packages/framework/esm-framework/docs/API.md
index e6adc2bc0..cbf5e4604 100644
--- a/packages/framework/esm-framework/docs/API.md
+++ b/packages/framework/esm-framework/docs/API.md
@@ -228,8 +228,10 @@
 - [canAccessStorage](API.md#canaccessstorage)
 - [daysIntoYear](API.md#daysintoyear)
 - [displayName](API.md#displayname)
+- [formatPatientName](API.md#formatpatientname)
 - [formattedName](API.md#formattedname)
 - [getDefaultsFromConfigSchema](API.md#getdefaultsfromconfigschema)
+- [getPatientName](API.md#getpatientname)
 - [isSameDay](API.md#issameday)
 - [isVersionSatisfied](API.md#isversionsatisfied)
 - [retry](API.md#retry)
@@ -981,7 +983,7 @@ ___
 
 #### Defined in
 
-[packages/framework/esm-api/src/shared-api-objects/visit-utils.ts:100](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-api/src/shared-api-objects/visit-utils.ts#L100)
+[packages/framework/esm-api/src/shared-api-objects/visit-utils.ts:103](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-api/src/shared-api-objects/visit-utils.ts#L103)
 
 ___
 
@@ -1959,7 +1961,7 @@ ___
 
 #### Defined in
 
-[packages/framework/esm-api/src/shared-api-objects/visit-utils.ts:27](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-api/src/shared-api-objects/visit-utils.ts#L27)
+[packages/framework/esm-api/src/shared-api-objects/visit-utils.ts:30](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-api/src/shared-api-objects/visit-utils.ts#L30)
 
 ___
 
@@ -1995,7 +1997,7 @@ ___
 
 #### Defined in
 
-[packages/framework/esm-api/src/shared-api-objects/visit-utils.ts:51](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-api/src/shared-api-objects/visit-utils.ts#L51)
+[packages/framework/esm-api/src/shared-api-objects/visit-utils.ts:54](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-api/src/shared-api-objects/visit-utils.ts#L54)
 
 ___
 
@@ -2196,7 +2198,7 @@ ___
 
 #### Defined in
 
-[packages/framework/esm-api/src/shared-api-objects/visit-utils.ts:73](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-api/src/shared-api-objects/visit-utils.ts#L73)
+[packages/framework/esm-api/src/shared-api-objects/visit-utils.ts:76](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-api/src/shared-api-objects/visit-utils.ts#L76)
 
 ___
 
@@ -2217,7 +2219,7 @@ ___
 
 #### Defined in
 
-[packages/framework/esm-api/src/shared-api-objects/visit-utils.ts:31](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-api/src/shared-api-objects/visit-utils.ts#L31)
+[packages/framework/esm-api/src/shared-api-objects/visit-utils.ts:34](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-api/src/shared-api-objects/visit-utils.ts#L34)
 
 ___
 
@@ -2342,7 +2344,7 @@ ___
 
 #### Defined in
 
-[packages/framework/esm-api/src/shared-api-objects/visit-utils.ts:84](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-api/src/shared-api-objects/visit-utils.ts#L84)
+[packages/framework/esm-api/src/shared-api-objects/visit-utils.ts:87](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-api/src/shared-api-objects/visit-utils.ts#L87)
 
 ___
 
@@ -2471,7 +2473,7 @@ ___
 
 ### useVisit
 
-▸ **useVisit**(`patientUuid`): [`VisitReturnType`](interfaces/VisitReturnType.md)
+▸ **useVisit**(`patientUuid`, `representation?`): [`VisitReturnType`](interfaces/VisitReturnType.md)
 
 This React hook returns visit information if the patient UUID is not null. There are
 potentially two relevant visits at a time: "active" and "current".
@@ -2491,9 +2493,10 @@ API call is in progress. `mutate` refreshes the data from both API calls.
 
 #### Parameters
 
-| Name | Type | Description |
-| :------ | :------ | :------ |
-| `patientUuid` | `string` | Unique patient identifier `string` |
+| Name | Type | Default value | Description |
+| :------ | :------ | :------ | :------ |
+| `patientUuid` | `string` | `undefined` | Unique patient identifier `string` |
+| `representation` | `string` | `defaultVisitCustomRepresentation` | The custom representation of the visit |
 
 #### Returns
 
@@ -2501,7 +2504,7 @@ API call is in progress. `mutate` refreshes the data from both API calls.
 
 #### Defined in
 
-[packages/framework/esm-react-utils/src/useVisit.ts:41](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-react-utils/src/useVisit.ts#L41)
+[packages/framework/esm-react-utils/src/useVisit.ts:42](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-react-utils/src/useVisit.ts#L42)
 
 ___
 
@@ -6266,32 +6269,27 @@ ___
 
 ▸ **displayName**(`patient`): `string`
 
-Gets the formatted display name for a patient.
-
-The display name will be taken from the patient's 'usual' name,
-or may fall back to the patient's 'official' name.
+**`deprecated`** Use `getPatientName`
 
 #### Parameters
 
-| Name | Type | Description |
-| :------ | :------ | :------ |
-| `patient` | `Patient` | The patient details in FHIR format. |
+| Name | Type |
+| :------ | :------ |
+| `patient` | `Patient` |
 
 #### Returns
 
 `string`
 
-The patient's display name or an empty string if name is not present.
-
 #### Defined in
 
-[packages/framework/esm-utils/src/patient-helpers.ts:14](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-utils/src/patient-helpers.ts#L14)
+[packages/framework/esm-utils/src/patient-helpers.ts:20](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-utils/src/patient-helpers.ts#L20)
 
 ___
 
-### formattedName
+### formatPatientName
 
-▸ **formattedName**(`name`): `string`
+▸ **formatPatientName**(`name`): `string`
 
 Get a formatted display string for an FHIR name.
 
@@ -6309,7 +6307,29 @@ The formatted display name or an empty string if name is undefined.
 
 #### Defined in
 
-[packages/framework/esm-utils/src/patient-helpers.ts:24](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-utils/src/patient-helpers.ts#L24)
+[packages/framework/esm-utils/src/patient-helpers.ts:29](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-utils/src/patient-helpers.ts#L29)
+
+___
+
+### formattedName
+
+▸ **formattedName**(`name`): `string`
+
+**`deprecated`** Use `formatPatientName`
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `name` | `undefined` \| `HumanName` |
+
+#### Returns
+
+`string`
+
+#### Defined in
+
+[packages/framework/esm-utils/src/patient-helpers.ts:35](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-utils/src/patient-helpers.ts#L35)
 
 ___
 
@@ -6348,6 +6368,33 @@ need to override some of the default values.
 
 ___
 
+### getPatientName
+
+▸ **getPatientName**(`patient`): `string`
+
+Gets the formatted display name for a patient.
+
+The display name will be taken from the patient's 'usual' name,
+or may fall back to the patient's 'official' name.
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `patient` | `Patient` | The patient details in FHIR format. |
+
+#### Returns
+
+`string`
+
+The patient's display name or an empty string if name is not present.
+
+#### Defined in
+
+[packages/framework/esm-utils/src/patient-helpers.ts:14](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-utils/src/patient-helpers.ts#L14)
+
+___
+
 ### isSameDay
 
 ▸ **isSameDay**(`firstDate`, `secondDate`): `boolean`
@@ -6466,7 +6513,7 @@ the preferred name for the patient, or undefined if no acceptable name could be
 
 #### Defined in
 
-[packages/framework/esm-utils/src/patient-helpers.ts:47](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-utils/src/patient-helpers.ts#L47)
+[packages/framework/esm-utils/src/patient-helpers.ts:57](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-utils/src/patient-helpers.ts#L57)
 
 ___
 
diff --git a/packages/framework/esm-framework/docs/enums/VisitMode.md b/packages/framework/esm-framework/docs/enums/VisitMode.md
index d9d0b3471..d4fdb34d3 100644
--- a/packages/framework/esm-framework/docs/enums/VisitMode.md
+++ b/packages/framework/esm-framework/docs/enums/VisitMode.md
@@ -18,7 +18,7 @@
 
 #### Defined in
 
-[packages/framework/esm-api/src/shared-api-objects/visit-utils.ts:111](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-api/src/shared-api-objects/visit-utils.ts#L111)
+[packages/framework/esm-api/src/shared-api-objects/visit-utils.ts:114](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-api/src/shared-api-objects/visit-utils.ts#L114)
 
 ___
 
@@ -28,7 +28,7 @@ ___
 
 #### Defined in
 
-[packages/framework/esm-api/src/shared-api-objects/visit-utils.ts:112](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-api/src/shared-api-objects/visit-utils.ts#L112)
+[packages/framework/esm-api/src/shared-api-objects/visit-utils.ts:115](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-api/src/shared-api-objects/visit-utils.ts#L115)
 
 ___
 
@@ -38,4 +38,4 @@ ___
 
 #### Defined in
 
-[packages/framework/esm-api/src/shared-api-objects/visit-utils.ts:110](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-api/src/shared-api-objects/visit-utils.ts#L110)
+[packages/framework/esm-api/src/shared-api-objects/visit-utils.ts:113](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-api/src/shared-api-objects/visit-utils.ts#L113)
diff --git a/packages/framework/esm-framework/docs/enums/VisitStatus.md b/packages/framework/esm-framework/docs/enums/VisitStatus.md
index a49d4281a..ac160bf2a 100644
--- a/packages/framework/esm-framework/docs/enums/VisitStatus.md
+++ b/packages/framework/esm-framework/docs/enums/VisitStatus.md
@@ -17,7 +17,7 @@
 
 #### Defined in
 
-[packages/framework/esm-api/src/shared-api-objects/visit-utils.ts:116](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-api/src/shared-api-objects/visit-utils.ts#L116)
+[packages/framework/esm-api/src/shared-api-objects/visit-utils.ts:119](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-api/src/shared-api-objects/visit-utils.ts#L119)
 
 ___
 
@@ -27,4 +27,4 @@ ___
 
 #### Defined in
 
-[packages/framework/esm-api/src/shared-api-objects/visit-utils.ts:117](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-api/src/shared-api-objects/visit-utils.ts#L117)
+[packages/framework/esm-api/src/shared-api-objects/visit-utils.ts:120](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-api/src/shared-api-objects/visit-utils.ts#L120)
diff --git a/packages/framework/esm-framework/docs/interfaces/VisitItem.md b/packages/framework/esm-framework/docs/interfaces/VisitItem.md
index c12c499dc..7add1f769 100644
--- a/packages/framework/esm-framework/docs/interfaces/VisitItem.md
+++ b/packages/framework/esm-framework/docs/interfaces/VisitItem.md
@@ -19,7 +19,7 @@
 
 #### Defined in
 
-[packages/framework/esm-api/src/shared-api-objects/visit-utils.ts:106](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-api/src/shared-api-objects/visit-utils.ts#L106)
+[packages/framework/esm-api/src/shared-api-objects/visit-utils.ts:109](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-api/src/shared-api-objects/visit-utils.ts#L109)
 
 ___
 
@@ -29,7 +29,7 @@ ___
 
 #### Defined in
 
-[packages/framework/esm-api/src/shared-api-objects/visit-utils.ts:103](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-api/src/shared-api-objects/visit-utils.ts#L103)
+[packages/framework/esm-api/src/shared-api-objects/visit-utils.ts:106](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-api/src/shared-api-objects/visit-utils.ts#L106)
 
 ___
 
@@ -39,7 +39,7 @@ ___
 
 #### Defined in
 
-[packages/framework/esm-api/src/shared-api-objects/visit-utils.ts:105](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-api/src/shared-api-objects/visit-utils.ts#L105)
+[packages/framework/esm-api/src/shared-api-objects/visit-utils.ts:108](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-api/src/shared-api-objects/visit-utils.ts#L108)
 
 ___
 
@@ -49,4 +49,4 @@ ___
 
 #### Defined in
 
-[packages/framework/esm-api/src/shared-api-objects/visit-utils.ts:104](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-api/src/shared-api-objects/visit-utils.ts#L104)
+[packages/framework/esm-api/src/shared-api-objects/visit-utils.ts:107](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-api/src/shared-api-objects/visit-utils.ts#L107)
diff --git a/packages/framework/esm-framework/docs/interfaces/VisitStoreState.md b/packages/framework/esm-framework/docs/interfaces/VisitStoreState.md
index f97e26270..098993301 100644
--- a/packages/framework/esm-framework/docs/interfaces/VisitStoreState.md
+++ b/packages/framework/esm-framework/docs/interfaces/VisitStoreState.md
@@ -17,7 +17,7 @@
 
 #### Defined in
 
-[packages/framework/esm-api/src/shared-api-objects/visit-utils.ts:20](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-api/src/shared-api-objects/visit-utils.ts#L20)
+[packages/framework/esm-api/src/shared-api-objects/visit-utils.ts:23](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-api/src/shared-api-objects/visit-utils.ts#L23)
 
 ___
 
@@ -27,4 +27,4 @@ ___
 
 #### Defined in
 
-[packages/framework/esm-api/src/shared-api-objects/visit-utils.ts:19](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-api/src/shared-api-objects/visit-utils.ts#L19)
+[packages/framework/esm-api/src/shared-api-objects/visit-utils.ts:22](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-api/src/shared-api-objects/visit-utils.ts#L22)
diff --git a/packages/framework/esm-react-utils/src/useVisit.ts b/packages/framework/esm-react-utils/src/useVisit.ts
index 7d5a18f0a..a1df18f5f 100644
--- a/packages/framework/esm-react-utils/src/useVisit.ts
+++ b/packages/framework/esm-react-utils/src/useVisit.ts
@@ -37,13 +37,14 @@ export interface VisitReturnType {
  * API call is in progress. `mutate` refreshes the data from both API calls.
  *
  * @param patientUuid Unique patient identifier `string`
+ * @param representation The custom representation of the visit
  */
-export function useVisit(patientUuid: string): VisitReturnType {
+export function useVisit(patientUuid: string, representation = defaultVisitCustomRepresentation): VisitReturnType {
   const { patientUuid: visitStorePatientUuid, manuallySetVisitUuid } = useStore(getVisitStore());
   // Ignore the visit store data if it is not for this patient
   const retrospectiveVisitUuid = patientUuid && visitStorePatientUuid == patientUuid ? manuallySetVisitUuid : null;
-  const activeVisitUrlSuffix = `?patient=${patientUuid}&v=${defaultVisitCustomRepresentation}&includeInactive=false`;
-  const retrospectiveVisitUrlSuffix = `/${retrospectiveVisitUuid}`;
+  const activeVisitUrlSuffix = `?patient=${patientUuid}&v=${representation}&includeInactive=false`;
+  const retrospectiveVisitUrlSuffix = `/${retrospectiveVisitUuid}?v=${representation}`;
 
   const {
     data: activeData,