@openmrs/esm-dispensing-app 1.0.1-pre.99 → 1.1.0

package/README.md

@@ -5,6 +5,40 @@
 This repository is for the OpenMRS Dispensing App. For more information, please see the
 [Design Documentation](https://wiki.openmrs.org/display/projects/Dispensing+Design+Components).
 
+## Required Configuration
+
+The Dispensing ESM requires the "HL7-MedicationDispenseStatus" concept source and FHIR concept source, as well as "Medication Dispense Status" value/concept set, to be installed in your OpenMRS instance to properly map dispensing statuses.
+
+References to the Iniz files that install these concept sources can be found here:
+
+https://github.com/openmrs/openmrs-distro-referenceapplication/blob/main/distro/configuration/conceptsources/conceptsources-core_data.csv#L24
+
+https://openmrs.slack.com/archives/C02P790SM7X/p1692380047339679?thread_ts=1692338258.965499&cid=C02P790SM7X
+
+The Medication Dispense Status value set can be found here:
+
+https://app.openconceptlab.org/#/search/?q=medication+dispense+status
+
+It also is bundled in the "DrugDispense" OCL package provided by the Reference Application:
+
+https://github.com/openmrs/openmrs-distro-referenceapplication/tree/main/distro/configuration/ocl
+
+The "DrugDispense" also provides the default value sets for the "Substitution Type", "Substitution Reason", and "Medication Dispense Status Reason".
+
+The "Substitution Type" and "Substitution Reason" value sets define the valid answers for both the equivalent questions when substituting a drug.  The "Medication Dispense Status Reason" provides the default answers for both the "Reason for Pause" and "Reason for Close" questions.
+
+All of these can be customized via the config-schema, see: https://github.com/openmrs/openmrs-esm-dispensing-app/blob/main/src/config-schema.ts
+
+## Required privileges
+
+Note that following privileges need to be installed and assigned to roles:
+
+* "Task: dispensing.create.dispense" - Allows user to Dispense Medication
+* "Task: dispensing.create.dispense.andModifyDetails" - Allows user to modify the Quantity, Drug, Formulation and Dose Instructions (from the values specified in the Order / Medication Request) when Dispensing
+* "Task: dispensing.edit.dispense" - Allows user to edit an existing Medication Dispense
+* "Task: dispensing.delete.dispense" - Allows user to delete an existing Medication Dispense 
+* "Task: dispensing.delete.dispense.ifCreator" - Allows user to delete an existing Medication Dispense, *but only* if they created it originally
+
 ## Running this code
 
 ```sh
@@ -30,3 +64,4 @@ For more information, please see the
 
 In particular, the [Setup](https://openmrs.github.io/openmrs-esm-core/#/getting_started/setup)
 section can help you get started developing microfrontends in general.
+

package/jest.config.js

@@ -0,0 +1,15 @@
+module.exports = {
+  transform: {
+    "^.+\\.tsx?$": "@swc/jest",
+  },
+  transformIgnorePatterns: ["/node_modules/(?!@openmrs)"],
+  moduleNameMapper: {
+    "@openmrs/esm-framework": "@openmrs/esm-framework/mock",
+    "\\.(s?css)$": "identity-obj-proxy",
+    "^lodash-es/(.*)$": "lodash/$1",
+    "^uuid$": "<rootDir>/node_modules/uuid/dist/index.js",
+    dexie: require.resolve("dexie"),
+  },
+  setupFilesAfterEnv: ["<rootDir>/src/setup-tests.ts"],
+  testEnvironment: "jsdom",
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openmrs/esm-dispensing-app",
-  "version": "1.0.1-pre.99",
+  "version": "1.1.0",
   "license": "MPL-2.0",
   "description": "Medication dispensing application",
   "browser": "dist/openmrs-esm-dispensing-app.js",
@@ -13,11 +13,11 @@
     "analyze": "webpack --mode=production --env.analyze=true",
     "prettier": "prettier --write \"src/**/*.{ts,tsx}\"",
     "lint": "eslint src --ext js,jsx,ts,tsx",
-    "test": "jest --config jest.config.json",
+    "test": "jest --config jest.config.js",
     "typescript": "tsc",
     "verify": "concurrently 'yarn:lint' 'yarn:test' 'yarn:typescript'",
     "coverage": "yarn test --coverage",
-    "prepare": "husky install"
+    "postinstall": "husky install"
   },
   "browserslist": [
     "extends browserslist-config-openmrs"
@@ -41,17 +41,16 @@
     "url": "https://github.com/openmrs/openmrs-esm-dispensing/issues"
   },
   "dependencies": {
-    "@carbon/react": "^1.9.0",
+    "@carbon/react": "1.12.0",
     "lodash-es": "^4.17.15",
-    "swr": "^1.3.0"
+    "swr": "^2.1.0"
   },
   "peerDependencies": {
-    "@openmrs/esm-framework": "4.x",
+    "@openmrs/esm-framework": "*",
     "dayjs": "1.x",
     "react": "18.x",
     "react-dom": "18.x",
     "react-i18next": "11.x",
-    "react-router-dom": "6.x",
     "rxjs": "6.x"
   },
   "devDependencies": {
@@ -70,10 +69,12 @@
     "@types/webpack-env": "^1.16.0",
     "@typescript-eslint/parser": "^4.26.0",
     "concurrently": "^6.2.0",
+    "dayjs": "1.x",
     "eslint": "^7.27.0",
     "eslint-config-prettier": "^8.3.0",
     "eslint-config-ts-react-important-stuff": "^3.0.0",
     "eslint-plugin-prettier": "^3.4.0",
+    "eslint-plugin-unused-imports": "^2.0.0",
     "husky": "^6.0.0",
     "identity-obj-proxy": "^3.0.0",
     "jest": "^28.1.2",
@@ -87,6 +88,8 @@
     "react-i18next": "^11.7.0",
     "react-router-dom": "^6.3.0",
     "rxjs": "^6.5.4",
-    "typescript": "^4.3.2"
-  }
-}
+    "typescript": "^4.3.2",
+    "webpack": "^5.88.0"
+  },
+  "packageManager": "yarn@3.6.0"
+}

package/src/components/action-buttons.component.test.tsx

@@ -0,0 +1,244 @@
+import { render } from "@testing-library/react";
+import React from "react";
+import ActionButtons from "./action-buttons.component";
+import { MedicationRequest, MedicationRequestStatus } from "../types";
+import { useConfig } from "@openmrs/esm-framework";
+
+const mockedUseConfig = useConfig as jest.Mock;
+const mockPatientUuid = "558494fe-5850-4b34-a3bf-06550334ba4a";
+const mockEncounterUuid = "7aee7123-9e50-4f72-a636-895d77a63e98";
+
+describe("Action Buttons Component tests", () => {
+  beforeEach(() => {
+    mockedUseConfig.mockReturnValue({
+      medicationRequestExpirationPeriodInDays: 90,
+      actionButtons: {
+        pauseButton: {
+          enabled: true,
+        },
+        closeButton: {
+          enabled: true,
+        },
+      },
+      dispenseBehavior: {
+        allowModifyingPrescription: false,
+        restrictTotalQuantityDispensed: false,
+      },
+    });
+  });
+
+  test("component should render dispense button if active medication", () => {
+    // status = active, and validity period start set to current datetime
+    const medicationRequest: MedicationRequest = {
+      resourceType: "MedicationRequest",
+      id: "d4f69a68-1171-4e47-8693-478df18daf40",
+      meta: {
+        lastUpdated: "2023-01-24T19:02:04.000-05:00",
+      },
+      status: MedicationRequestStatus.active,
+      intent: "order",
+      priority: "routine",
+      medicationReference: {
+        reference: "Medication/c8d3444c-41a4-48d3-9ec1-811fe7b27d99",
+        type: "Medication",
+        display: "Ascorbic acid (Vitamin C), 250mg tablet",
+      },
+      subject: {
+        reference: "Patient/558494fe-5850-4b34-a3bf-06550334ba4a",
+        type: "Patient",
+        display: "Dylan, Bob (ZL EMR ID: Y2CK2G)",
+      },
+      encounter: {
+        reference: "Encounter/7aee7123-9e50-4f72-a636-895d77a63e98",
+        type: "Encounter",
+      },
+      requester: {
+        reference: "Practitioner/19e06fb0-22ea-4dd4-aafd-da14c14a1487",
+        type: "Practitioner",
+        identifier: {
+          value: "MAADH",
+        },
+        display: "Goodrich, Mark (Identifier: MAADH)",
+      },
+      dosageInstruction: [
+        {
+          text: "test",
+          timing: {
+            repeat: {
+              duration: 6,
+              durationUnit: "d",
+            },
+            code: {
+              coding: [
+                {
+                  code: "37328251-6759-4270-8a2e-8cab2c0b315b",
+                  display: "OD (once daily)",
+                },
+                {
+                  system: "http://snomed.info/sct",
+                  code: "229797004",
+                  display: "OD (once daily)",
+                },
+              ],
+              text: "OD (once daily)",
+            },
+          },
+          asNeededBoolean: false,
+          route: {
+            coding: [
+              {
+                code: "46aaaca8-1f21-410a-aac9-67bfcc1fd577",
+                display: "Oral",
+              },
+              {
+                system: "http://snomed.info/sct",
+                code: "26643006",
+                display: "Oral",
+              },
+            ],
+            text: "Oral",
+          },
+          doseAndRate: [
+            {
+              doseQuantity: {
+                value: 5.0,
+                unit: "Ampule(s)",
+                system: "http://snomed.info/sct",
+                code: "413516001",
+              },
+            },
+          ],
+        },
+      ],
+      dispenseRequest: {
+        validityPeriod: {
+          start: new Date().toISOString(),
+        },
+        numberOfRepeatsAllowed: 8,
+        quantity: {
+          value: 7.0,
+          unit: "Application",
+          system: "http://snomed.info/sct",
+          code: "413568008",
+        },
+      },
+    };
+
+    const { getByText, container } = render(
+      <ActionButtons
+        patientUuid={mockPatientUuid}
+        encounterUuid={mockEncounterUuid}
+        medicationRequestBundle={{ request: medicationRequest, dispenses: [] }}
+      />
+    );
+    expect(getByText("Dispense")).toBeInTheDocument();
+  });
+
+  // status = active, but validity period start time years in the past
+  test("component should not render dispense button if expired medication", () => {
+    // status = active, and validity period start set to current datetime
+    const medicationRequest: MedicationRequest = {
+      resourceType: "MedicationRequest",
+      id: "d4f69a68-1171-4e47-8693-478df18daf40",
+      meta: {
+        lastUpdated: "2023-01-24T19:02:04.000-05:00",
+      },
+      status: MedicationRequestStatus.active,
+      intent: "order",
+      priority: "routine",
+      medicationReference: {
+        reference: "Medication/c8d3444c-41a4-48d3-9ec1-811fe7b27d99",
+        type: "Medication",
+        display: "Ascorbic acid (Vitamin C), 250mg tablet",
+      },
+      subject: {
+        reference: "Patient/558494fe-5850-4b34-a3bf-06550334ba4a",
+        type: "Patient",
+        display: "Dylan, Bob (ZL EMR ID: Y2CK2G)",
+      },
+      encounter: {
+        reference: "Encounter/7aee7123-9e50-4f72-a636-895d77a63e98",
+        type: "Encounter",
+      },
+      requester: {
+        reference: "Practitioner/19e06fb0-22ea-4dd4-aafd-da14c14a1487",
+        type: "Practitioner",
+        identifier: {
+          value: "MAADH",
+        },
+        display: "Goodrich, Mark (Identifier: MAADH)",
+      },
+      dosageInstruction: [
+        {
+          text: "test",
+          timing: {
+            repeat: {
+              duration: 6,
+              durationUnit: "d",
+            },
+            code: {
+              coding: [
+                {
+                  code: "37328251-6759-4270-8a2e-8cab2c0b315b",
+                  display: "OD (once daily)",
+                },
+                {
+                  system: "http://snomed.info/sct",
+                  code: "229797004",
+                  display: "OD (once daily)",
+                },
+              ],
+              text: "OD (once daily)",
+            },
+          },
+          asNeededBoolean: false,
+          route: {
+            coding: [
+              {
+                code: "46aaaca8-1f21-410a-aac9-67bfcc1fd577",
+                display: "Oral",
+              },
+              {
+                system: "http://snomed.info/sct",
+                code: "26643006",
+                display: "Oral",
+              },
+            ],
+            text: "Oral",
+          },
+          doseAndRate: [
+            {
+              doseQuantity: {
+                value: 5.0,
+                unit: "Ampule(s)",
+                system: "http://snomed.info/sct",
+                code: "413516001",
+              },
+            },
+          ],
+        },
+      ],
+      dispenseRequest: {
+        validityPeriod: {
+          start: "2019-01-24T19:02:04.000-05:00",
+        },
+        numberOfRepeatsAllowed: 8,
+        quantity: {
+          value: 7.0,
+          unit: "Application",
+          system: "http://snomed.info/sct",
+          code: "413568008",
+        },
+      },
+    };
+
+    const { queryByText, container } = render(
+      <ActionButtons
+        patientUuid={mockPatientUuid}
+        encounterUuid={mockEncounterUuid}
+        medicationRequestBundle={{ request: medicationRequest, dispenses: [] }}
+      />
+    );
+    expect(queryByText("Dispense")).not.toBeInTheDocument();
+  });
+});

package/src/components/action-buttons.component.tsx

@@ -0,0 +1,137 @@
+import React from "react";
+import { Button } from "@carbon/react";
+import { useConfig, useSession } from "@openmrs/esm-framework";
+import styles from "./action-buttons.scss";
+import { useTranslation } from "react-i18next";
+import {
+  MedicationDispenseStatus,
+  MedicationRequestBundle,
+  MedicationRequestStatus,
+} from "../types";
+import { PharmacyConfig } from "../config-schema";
+import { launchOverlay } from "../hooks/useOverlay";
+import {
+  computeMedicationRequestStatus,
+  computeQuantityRemaining,
+  getMostRecentMedicationDispenseStatus,
+} from "../utils";
+import DispenseForm from "../forms/dispense-form.component";
+import { initiateMedicationDispenseBody } from "../medication-dispense/medication-dispense.resource";
+import PauseDispenseForm from "../forms/pause-dispense-form.component";
+import CloseDispenseForm from "../forms/close-dispense-form.component";
+
+interface ActionButtonsProps {
+  medicationRequestBundle: MedicationRequestBundle;
+  patientUuid: string;
+  encounterUuid: string;
+}
+
+const ActionButtons: React.FC<ActionButtonsProps> = ({
+  medicationRequestBundle,
+  patientUuid,
+  encounterUuid,
+}) => {
+  const { t } = useTranslation();
+  const config = useConfig() as PharmacyConfig;
+  const session = useSession();
+  const mostRecentMedicationDispenseStatus: MedicationDispenseStatus =
+    getMostRecentMedicationDispenseStatus(medicationRequestBundle.dispenses);
+  const medicationRequestStatus = computeMedicationRequestStatus(
+    medicationRequestBundle.request,
+    config.medicationRequestExpirationPeriodInDays
+  );
+  const dispensable =
+    medicationRequestStatus === MedicationRequestStatus.active &&
+    mostRecentMedicationDispenseStatus !== MedicationDispenseStatus.declined;
+
+  const pauseable =
+    config.actionButtons.pauseButton.enabled &&
+    medicationRequestStatus === MedicationRequestStatus.active &&
+    mostRecentMedicationDispenseStatus !== MedicationDispenseStatus.on_hold &&
+    mostRecentMedicationDispenseStatus !== MedicationDispenseStatus.declined;
+
+  const closeable =
+    config.actionButtons.closeButton.enabled &&
+    medicationRequestStatus === MedicationRequestStatus.active &&
+    mostRecentMedicationDispenseStatus !== MedicationDispenseStatus.declined;
+
+  let quantityRemaining = null;
+  if (config.dispenseBehavior.restrictTotalQuantityDispensed) {
+    quantityRemaining = computeQuantityRemaining(medicationRequestBundle);
+  }
+
+  return (
+    <div className={styles.actionBtns}>
+      {dispensable ? (
+        <Button
+          kind="primary"
+          onClick={() =>
+            launchOverlay(
+              t("dispensePrescription", "Dispense prescription"),
+              <DispenseForm
+                patientUuid={patientUuid}
+                encounterUuid={encounterUuid}
+                medicationDispense={initiateMedicationDispenseBody(
+                  medicationRequestBundle.request,
+                  session,
+                  true
+                )}
+                medicationRequestBundle={medicationRequestBundle}
+                quantityRemaining={quantityRemaining}
+                mode="enter"
+              />
+            )
+          }
+        >
+          {t("dispense", "Dispense")}
+        </Button>
+      ) : null}
+      {pauseable ? (
+        <Button
+          kind="secondary"
+          onClick={() =>
+            launchOverlay(
+              t("pausePrescription", "Pause prescription"),
+              <PauseDispenseForm
+                patientUuid={patientUuid}
+                encounterUuid={encounterUuid}
+                medicationDispense={initiateMedicationDispenseBody(
+                  medicationRequestBundle.request,
+                  session,
+                  false
+                )}
+                mode="enter"
+              />
+            )
+          }
+        >
+          {t("pause", "Pause")}
+        </Button>
+      ) : null}
+      {closeable ? (
+        <Button
+          kind="danger"
+          onClick={() =>
+            launchOverlay(
+              t("closePrescription", "Close prescription"),
+              <CloseDispenseForm
+                patientUuid={patientUuid}
+                encounterUuid={encounterUuid}
+                medicationDispense={initiateMedicationDispenseBody(
+                  medicationRequestBundle.request,
+                  session,
+                  false
+                )}
+                mode="enter"
+              />
+            )
+          }
+        >
+          {t("close", "Close")}
+        </Button>
+      ) : null}
+    </div>
+  );
+};
+
+export default ActionButtons;

package/src/components/action-buttons.scss

@@ -0,0 +1,5 @@
+.actionBtns {
+  float: right;
+  margin-left: 1rem;
+  margin-top: 2rem;
+}

package/src/components/medication-card.component.test.tsx

@@ -0,0 +1,40 @@
+import { render } from "@testing-library/react";
+import React from "react";
+import { MedicationReferenceOrCodeableConcept } from "../types";
+import MedicationCard from "./medication-card.component";
+
+describe("Medication Card Component tests", () => {
+  test("component should render medication card without edit action button", () => {
+    const medication: MedicationReferenceOrCodeableConcept = {
+      medicationReference: {
+        display: "Some Medication",
+        reference: "",
+        type: "",
+      },
+    };
+
+    const { getByText, container } = render(
+      <MedicationCard medication={medication} />
+    );
+    expect(getByText("Some Medication")).toBeInTheDocument();
+    expect(container.querySelector("svg")).not.toBeInTheDocument();
+  });
+
+  test("component should render medication card with edit action button", () => {
+    const medication: MedicationReferenceOrCodeableConcept = {
+      medicationReference: {
+        display: "Some Medication",
+        reference: "",
+        type: "",
+      },
+    };
+
+    const action = () => 0;
+
+    const { getByText, container } = render(
+      <MedicationCard medication={medication} editAction={action} />
+    );
+    expect(getByText("Some Medication")).toBeInTheDocument();
+    expect(container.querySelector("svg")).toBeInTheDocument();
+  });
+});

package/src/components/medication-card.component.tsx

@@ -1,27 +1,20 @@
 import React from "react";
 import { Tile } from "@carbon/react";
-import { Medication } from "../types";
+import { Edit } from "@carbon/react/icons";
+import { MedicationReferenceOrCodeableConcept } from "../types";
 import styles from "./medication-card.scss";
-import { useTranslation } from "react-i18next";
-
-// TODO this will probably need a fair amount of updates to allow editing
+import { getMedicationDisplay } from "../utils";
 
 const MedicationCard: React.FC<{
-  medication: Medication;
-}> = ({ medication }) => {
-  const { t } = useTranslation();
-
+  medication: MedicationReferenceOrCodeableConcept;
+  editAction?: Function;
+}> = ({ medication, editAction }) => {
   return (
     <Tile className={styles.medicationTile}>
-      <div>
-        <p className={styles.medicationName}>
-          <strong>
-            {medication.medicationReference
-              ? medication.medicationReference.display
-              : medication?.medicationCodeableConcept.text}
-          </strong>
-        </p>
-      </div>
+      <p className={styles.medicationName}>
+        <strong>{getMedicationDisplay(medication)}</strong>
+      </p>
+      {editAction && <Edit onClick={editAction} />}
     </Tile>
   );
 };

package/src/components/medication-card.scss

@@ -3,11 +3,14 @@
 @import "~@openmrs/esm-styleguide/src/vars";
 
 .medicationTile {
+  display: flex;
+  flex-direction: row;
+  justify-content: space-between;
   width: 100%;
   margin: 2px 0 8px;
-  padding: 0 48px 0 8px;
+  padding: 0 8px 0 8px;
   background-color: #fff;
-  border-left: 4px solid #007d79;
+  border-left: 4px solid var(--brand-03);
   color: $text-02;
   margin-bottom: 1rem !important;
 }

package/src/components/medication-dispense-review.scss

@@ -5,6 +5,7 @@
 .medicationDispenseReviewContainer {
   display: flex;
   flex-direction: column;
+  padding-bottom: 10px;
 
   :global(.cds--css-grid) {
     padding-left:0 !important;
@@ -19,6 +20,14 @@
   gap: spacing.$spacing-05;
 }
 
+.substitutionReason {
+  width:100%;
+}
+
+.substitutionType {
+  width: 100%;
+}
+
 .productiveHeading02 {
   color: $color-gray-70;
   @include type.type-style('productive-heading-02');