(feat) More flexible system for setting the current visit (supports O…

…3-1895) (#724)

README.md

@@ -79,59 +79,77 @@ Verification of the existing packages can also be done in one step using `yarn`:
 yarn verify
 ```
 
-### Running
-
-#### The app shell and the framework
+### Running the app shell and the framework
 
 ```sh
 yarn run:shell
 ```
 
 `run:shell` will run the latest version of the shell and the framework only.
 
-#### The frontend modules in `apps`
+### Running the frontend modules in `apps`
 
 ```sh
 yarn run:omrs develop --sources packages/apps/<app folder>
 ```
 
 This will allow you to develop the app similar to the experience of developing other apps.
 
-#### The tooling
+### Running the tooling
 
 ```sh
 cd packages/tooling/openmrs
 yarn build
 ./dist/cli.js
 ```
 
-#### The tests
+### Testing
 
 Run `yarn test` in the directory containing the package you want to test.
 
 Run `yarn lerna run test` to run all the tests in this repository.
 
-#### Linking the framework
+### Linking the framework
 
 If you want to try out changes to a framework library, you will
 probably want to `yarn link` or `npm link` it into a frontend module.
 Note that even though frontend modules import from `@openmrs/esm-framework`,
-the package you need to link is the sub-library; e.g., if you are trying
-to test changes in `packages/framework/esm-api`, you will need to link
-`@openmrs/esm-api`.
-
-In order to get your local version of that package to be served in your local
-dev server, you will need to link the app shell as well, and to build it.
-
-##### Example
-To set up to develop `@openmrs/esm-api` in a dev server for
-the patient chart:
-
-1. Navigate to the patient chart repository. Execute
-`yarn link /path/to/esm-core/packages/framework/esm-api` and then run
-`yarn link /path/to/esm-corepackages/shell/esm-app-shell`.
-2. In packages/shell/esm-app-shell, run `yarn build:development --watch` to ensure that the built app shell is updated with your changes and available to the patient chart.
-Then run your patient chart dev server as usual.
+the package you need to link is the sub-library; for example, if you are trying
+to test changes in `packages/framework/esm-api`, you will need to link it:
+
+```
+yarn link path/to/openmrs-esm-core/packages/framework/esm-framework
+yarn link path/to/openmrs-esm-core/packages/framework/esm-api
+```
+
+This satisfies the build tooling, but we must do one more step to get the frontend
+to load these dependencies at runtime
+(see docs on [Runtime Dependencies](https://o3-dev.docs.openmrs.org/#/main/deps)).
+Here, there are two options.
+
+#### Method 1: Using the frontend dev server
+
+In order to get your local version of the core packages to be served in your local
+dev server, you will need to link the tooling as well.
+
+`yarn link /path/to/esm-core/packages/tooling/openmrs`.
+
+In packages/shell/esm-app-shell, run `yarn build:development --watch` to ensure that the built app shell is updated with your changes and available to the patient chart.
+Then run your patient chart dev server as usual, with `yarn start`.
+
+If you're not able to get this working, try the 
+
+#### Method 2: Using import map overrides
+
+Read the [dev documentation](https://o3-dev.docs.openmrs.org/#/getting_started/setup?id=import-map-overrides)
+about import map overrides if you have not already.
+
+In `esm-core`, start the app shell with `yarn run:shell`. Then, in the patient chart
+repository, `cd` into whatever packages you are working on and run `yarn serve`
+from there. Then use the import map override tool in the browser to tell the frontend
+to load your local patient chart packages.
+
+#### Once it's working
 
 Please note that this will result in entries being added to the package.json file
 in the `resolutions` field. These changes must be undone before creating your PR,

packages/framework/esm-api/src/shared-api-objects/visit-utils.ts

@@ -8,6 +8,7 @@ import {
   UpdateVisitPayload,
   Visit,
 } from "../types";
+import { getGlobalStore } from "@openmrs/esm-state";
 
 export const defaultVisitCustomRepresentation =
   "custom:(uuid,encounters:(uuid,encounterDatetime," +
@@ -18,6 +19,41 @@ export const defaultVisitCustomRepresentation =
   "attributes:(uuid,display,attributeType:(name,datatypeClassname,uuid),value)," +
   "location:(uuid,name,display),startDatetime,stopDatetime)";
 
+export interface VisitStoreState {
+  patientUuid: string | null;
+  manuallySetVisitUuid: string | null;
+}
+
+const initialState = getVisitLocalStorage() || {
+  patientUuid: null,
+  manuallySetVisitUuid: null,
+};
+export function getVisitStore() {
+  return getGlobalStore<VisitStoreState>("visit", initialState);
+}
+
+export function setCurrentVisit(patientUuid: string, visitUuid: string) {
+  getVisitStore().setState({ patientUuid, manuallySetVisitUuid: visitUuid });
+}
+
+getVisitStore().subscribe((state) => {
+  setVisitLocalStorage(state);
+});
+
+function setVisitLocalStorage(value: VisitStoreState) {
+  localStorage.setItem("openmrs:visitStoreState", JSON.stringify(value));
+}
+
+function getVisitLocalStorage(): VisitStoreState | null {
+  try {
+    return JSON.parse(
+      localStorage.getItem("openmrs:visitStoreState") || "null"
+    );
+  } catch (e) {
+    return null;
+  }
+}
+
 export function getVisitsForPatient(
   patientUuid: string,
   abortController: AbortController,
@@ -72,6 +108,7 @@ export function updateVisit(
   });
 }
 
+/** @deprecated */
 export const getStartedVisit = new BehaviorSubject<VisitItem | null>(null);
 
 export interface VisitItem {

packages/framework/esm-framework/docs/API.md

@@ -13,13 +13,15 @@
 - [getLoggedInUser](API.md#getloggedinuser)
 - [getSessionLocation](API.md#getsessionlocation)
 - [getSessionStore](API.md#getsessionstore)
+- [getVisitStore](API.md#getvisitstore)
 - [getVisitTypes](API.md#getvisittypes)
 - [getVisitsForPatient](API.md#getvisitsforpatient)
 - [makeUrl](API.md#makeurl)
 - [openmrsFetch](API.md#openmrsfetch)
 - [openmrsObservableFetch](API.md#openmrsobservablefetch)
 - [refetchCurrentUser](API.md#refetchcurrentuser)
 - [saveVisit](API.md#savevisit)
+- [setCurrentVisit](API.md#setcurrentvisit)
 - [setSessionLocation](API.md#setsessionlocation)
 - [toLocationObject](API.md#tolocationobject)
 - [toVisitTypeObject](API.md#tovisittypeobject)
@@ -634,7 +636,7 @@ ___
 
 #### Defined in
 
-[packages/framework/esm-api/src/shared-api-objects/visit-utils.ts:12](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-api/src/shared-api-objects/visit-utils.ts#L12)
+[packages/framework/esm-api/src/shared-api-objects/visit-utils.ts:13](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-api/src/shared-api-objects/visit-utils.ts#L13)
 
 ___
 
@@ -652,9 +654,11 @@ ___
 
 • `Const` **getStartedVisit**: `BehaviorSubject`<``null`` \| [`VisitItem`](interfaces/VisitItem.md)\>
 
+**`deprecated`**
+
 #### Defined in
 
-[packages/framework/esm-api/src/shared-api-objects/visit-utils.ts:75](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-api/src/shared-api-objects/visit-utils.ts#L75)
+[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)
 
 ___
 
@@ -971,6 +975,20 @@ ___
 
 ___
 
+### getVisitStore
+
+▸ **getVisitStore**(): `StoreApi`<[`VisitStoreState`](interfaces/VisitStoreState.md)\>
+
+#### Returns
+
+`StoreApi`<[`VisitStoreState`](interfaces/VisitStoreState.md)\>
+
+#### 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)
+
+___
+
 ### getVisitTypes
 
 ▸ **getVisitTypes**(): `Observable`<[`VisitType`](interfaces/VisitType.md)[]\>
@@ -1003,7 +1021,7 @@ ___
 
 #### Defined in
 
-[packages/framework/esm-api/src/shared-api-objects/visit-utils.ts:21](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-api/src/shared-api-objects/visit-utils.ts#L21)
+[packages/framework/esm-api/src/shared-api-objects/visit-utils.ts:57](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-api/src/shared-api-objects/visit-utils.ts#L57)
 
 ___
 
@@ -1197,7 +1215,28 @@ ___
 
 #### Defined in
 
-[packages/framework/esm-api/src/shared-api-objects/visit-utils.ts:46](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-api/src/shared-api-objects/visit-utils.ts#L46)
+[packages/framework/esm-api/src/shared-api-objects/visit-utils.ts:82](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-api/src/shared-api-objects/visit-utils.ts#L82)
+
+___
+
+### setCurrentVisit
+
+▸ **setCurrentVisit**(`patientUuid`, `visitUuid`): `void`
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `patientUuid` | `string` |
+| `visitUuid` | `string` |
+
+#### Returns
+
+`void`
+
+#### Defined in
+
+[packages/framework/esm-api/src/shared-api-objects/visit-utils.ts:35](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-api/src/shared-api-objects/visit-utils.ts#L35)
 
 ___
 
@@ -1280,7 +1319,7 @@ ___
 
 #### Defined in
 
-[packages/framework/esm-api/src/shared-api-objects/visit-utils.ts:60](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-api/src/shared-api-objects/visit-utils.ts#L60)
+[packages/framework/esm-api/src/shared-api-objects/visit-utils.ts:96](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-api/src/shared-api-objects/visit-utils.ts#L96)
 
 ___
 
@@ -1354,7 +1393,7 @@ ___
 
 ### useVisit
 
-▸ **useVisit**(`patientUuid`): `VisitReturnType`
+▸ **useVisit**(`patientUuid`): [`VisitReturnType`](interfaces/VisitReturnType.md)
 
 This React hook returns a visit object. If the `patientUuid` is provided
 as a parameter, then the currentVisit, error and mutate function
@@ -1368,13 +1407,13 @@ for that patient visit is returned.
 
 #### Returns
 
-`VisitReturnType`
+[`VisitReturnType`](interfaces/VisitReturnType.md)
 
 Object {`error` `isValidating`, `currentVisit`, `mutate`}
 
 #### Defined in
 
-[packages/framework/esm-react-utils/src/useVisit.ts:29](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-react-utils/src/useVisit.ts#L29)
+[packages/framework/esm-react-utils/src/useVisit.ts:32](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-react-utils/src/useVisit.ts#L32)
 
 ___
 

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:86](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-api/src/shared-api-objects/visit-utils.ts#L86)
+[packages/framework/esm-api/src/shared-api-objects/visit-utils.ts:123](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-api/src/shared-api-objects/visit-utils.ts#L123)
 
 ___
 
@@ -28,7 +28,7 @@ ___
 
 #### Defined in
 
-[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)
+[packages/framework/esm-api/src/shared-api-objects/visit-utils.ts:124](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-api/src/shared-api-objects/visit-utils.ts#L124)
 
 ___
 
@@ -38,4 +38,4 @@ ___
 
 #### Defined in
 
-[packages/framework/esm-api/src/shared-api-objects/visit-utils.ts:85](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-api/src/shared-api-objects/visit-utils.ts#L85)
+[packages/framework/esm-api/src/shared-api-objects/visit-utils.ts:122](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-api/src/shared-api-objects/visit-utils.ts#L122)

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:91](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-api/src/shared-api-objects/visit-utils.ts#L91)
+[packages/framework/esm-api/src/shared-api-objects/visit-utils.ts:128](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-api/src/shared-api-objects/visit-utils.ts#L128)
 
 ___
 
@@ -27,4 +27,4 @@ ___
 
 #### Defined in
 
-[packages/framework/esm-api/src/shared-api-objects/visit-utils.ts:92](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-api/src/shared-api-objects/visit-utils.ts#L92)
+[packages/framework/esm-api/src/shared-api-objects/visit-utils.ts:129](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-api/src/shared-api-objects/visit-utils.ts#L129)

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:81](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-api/src/shared-api-objects/visit-utils.ts#L81)
+[packages/framework/esm-api/src/shared-api-objects/visit-utils.ts:118](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-api/src/shared-api-objects/visit-utils.ts#L118)
 
 ___
 
@@ -29,7 +29,7 @@ ___
 
 #### Defined in
 
-[packages/framework/esm-api/src/shared-api-objects/visit-utils.ts:78](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-api/src/shared-api-objects/visit-utils.ts#L78)
+[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)
 
 ___
 
@@ -39,7 +39,7 @@ ___
 
 #### Defined in
 
-[packages/framework/esm-api/src/shared-api-objects/visit-utils.ts:80](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-api/src/shared-api-objects/visit-utils.ts#L80)
+[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)
 
 ___
 
@@ -49,4 +49,4 @@ ___
 
 #### Defined in
 
-[packages/framework/esm-api/src/shared-api-objects/visit-utils.ts:79](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-api/src/shared-api-objects/visit-utils.ts#L79)
+[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)