@openmrs/esm-patient-immunizations-app 11.3.1-patch.9310 → 11.3.1-pre.10001

package/.turbo/turbo-build.log

@@ -1,42 +1,39 @@
-Browserslist: browsers data (caniuse-lite) is 6 months old. Please run:
-  npx update-browserslist-db@latest
-  Why you should do it regularly: https://github.com/browserslist/update-db#readme
-assets by path *.js 3.58 MiB
-  assets by chunk 2.67 MiB (id hint: vendors)
-    assets by status 2.4 MiB [big]
-      asset 1268.js 1.99 MiB [emitted] [minimized] [big] (id hint: vendors) 2 related assets
-      asset 795.js 414 KiB [emitted] [minimized] [big] (id hint: vendors) 2 related assets
+assets by path *.js 3.73 MiB
+  assets by chunk 2.77 MiB (id hint: vendors)
+    assets by status 2.5 MiB [big]
+      asset 2300.js 2.1 MiB [emitted] [minimized] [big] (id hint: vendors) 2 related assets
+      asset 795.js 415 KiB [emitted] [minimized] [big] (id hint: vendors) 2 related assets
     + 8 assets
-  + 52 assets
-assets by path *.json 32 KiB
-  asset openmrs-esm-patient-immunizations-app.js.buildmanifest.json 30.9 KiB [emitted]
+  + 55 assets
+assets by path *.json 33.3 KiB
+  asset openmrs-esm-patient-immunizations-app.js.buildmanifest.json 32.2 KiB [emitted]
   asset routes.json 1.09 KiB [emitted] [from: src/routes.json] [copied]
-orphan modules 9.8 MiB [orphan] 3071 modules
+orphan modules 9.86 MiB [orphan] 3091 modules
 runtime modules 44.2 KiB 28 modules
-built modules 8.21 MiB (javascript) 420 bytes (share-init) 420 bytes (consume-shared) [built]
-  modules by path ../../node_modules/ 7.71 MiB 596 modules
-  modules by path ./ 269 KiB
-    modules by path ./translations/ 66.4 KiB 40 modules
-    modules by path ./src/ 202 KiB 13 modules
+built modules 8.43 MiB (javascript) 420 bytes (share-init) 420 bytes (consume-shared) [built]
+  modules by path ../../node_modules/ 7.88 MiB 603 modules
+  modules by path ./ 274 KiB
+    optional modules 71.1 KiB [optional] 42 modules
+    javascript modules 203 KiB 14 modules
   provide-module modules 420 bytes 10 modules
   consume-shared-module modules 420 bytes 10 modules
-  modules by path ../esm-patient-common-lib/src/ 240 KiB
-    ../esm-patient-common-lib/src/index.ts + 47 modules 111 KiB [built] [code generated]
+  modules by path ../esm-patient-common-lib/src/ 286 KiB
+    ../esm-patient-common-lib/src/index.ts + 52 modules 119 KiB [built] [code generated]
     ../../node_modules/@openmrs/webpack-config/node_modules/css-loader/dist/cjs.js??ruleSet[1].rules[2].use[1]!../../node_modules/sass-loader/dist/cjs.js??ruleSet[1].rules[2].use[2]!../esm-patient-common-lib/src/cards/card-header.scss 31.5 KiB [built] [code generated]
-    + 3 modules
+    + 4 modules
   container entry 42 bytes [built] [code generated]
 
 WARNING in asset size limit: The following asset(s) exceed the recommended size limit (244 KiB).
 This can impact web performance.
 Assets: 
-  main.js (508 KiB)
-  1268.js (1.99 MiB)
-  795.js (414 KiB)
+  main.js (509 KiB)
+  2300.js (2.1 MiB)
+  795.js (415 KiB)
 
 WARNING in entrypoint size limit: The following entrypoint(s) combined asset size exceeds the recommended limit (244 KiB). This can impact web performance.
 Entrypoints:
-  main (508 KiB)
+  main (509 KiB)
       main.js
 
 
-webpack 5.99.9 compiled with 2 warnings in 136534 ms
+webpack 5.99.9 compiled with 2 warnings in 136911 ms

package/README.md

@@ -1,4 +1,173 @@
 # esm-patient-immunizations-app
 
-The immunizations widget. It provides a tabular overview of the immunizations recorded for a patient as well as a form for recording new immunizations.
+The immunizations widget provides a visual, intuitive system for clinicians to record immunizations, track vaccination schedules, and monitor a patient's vaccination status.
 
+## Usage
+
+This module is a patient chart widget that can be added to any patient chart dashboard. It provides two main views:
+
+1. **Immunization Summary**: A detailed, collapsible table that groups immunizations by vaccine type. It provides an overview of the patient's vaccination history with expandable rows for more detail.
+   From this view, users can add new immunizations or edit/delete existing doses, which launches the immunization workspace form.
+
+2. **Immunization History**: A separate card that provides a simple, chronological list of all immunizations the patient has received.
+   This card, in conjunction with the summary view, helps clinicians track whether a patient's next scheduled dose is upcoming or overdue.
+
+## Key Features
+
+### Enhanced Immunization Form
+
+- **Comprehensive Data Entry**: A workspace form allows for recording new vaccinations with fields for:
+  - Vaccination Date
+  - Immunization (Vaccine Name)
+  - Dose Number
+  - Manufacturer
+  - Lot Number
+  - Expiration Date
+  - Next Dose Date
+  - Free-text Notes
+- **Smart Validation**: Includes checks for future dates and ensures the vaccination date is on or after the patient's birth date.
+- **Loading & Error States**: Provides clear user feedback during form submission and validation.
+
+### Detailed Summary & History
+
+- **Grouped Summary Table**: Displays a consolidated list of all vaccine types the patient has received. Each entry shows the vaccine name and details of the most recent dose.
+- **Expandable Details**: Users can expand each vaccine entry to see a detailed history for that specific vaccine, including dose number, dates, lot number, manufacturer, notes, and actions.
+- **Chronological History Card**: A separate view shows all immunization events sorted by date.
+
+### Next Dose Tracking
+
+- **Visual Indicators**: The system uses visual cues to highlight the status of upcoming vaccinations:
+  - 🔴 **Red flag**: Indicates an overdue or currently due vaccination.
+  - 🟢 **Green flag**: Indicates an upcoming vaccination.
+- **Scheduling Logic**: The `Next Dose Date` field helps clinicians plan future appointments and prevents scheduling errors (e.g., setting a next dose date before the current vaccination date).
+
+### Full Record Management
+
+- **Edit Functionality**: Allows modification of existing immunization records. The form is pre-populated with existing data, and the vaccine name is locked to maintain data integrity.
+- **Delete Functionality**: Individual immunization doses can be safely deleted after a confirmation prompt.
+- **User Feedback**: Toast notifications confirm the success or failure of create, update, and delete operations.
+
+## Configuration
+
+### Available Widgets
+
+This module registers several extensions that create the complete immunization feature. Here is a breakdown of the key widgets and how they are used:
+
+1. **Immunizations Dashboard Link (`immunization-summary-dashboard`)**: Adds the "Immunizations" link to the patient chart's side navigation menu and automatically creates a dedicated dashboard page for immunization widgets.
+
+2. **Immunization Summary Table (`immunization-details-widget`)**: The main collapsible table that groups immunizations by vaccine type. Automatically placed on the Immunizations Dashboard.
+
+3. **Immunization History Card (`immunization-detailed-history-card`)**: A chronological list of all immunizations. Automatically placed on the Immunizations Dashboard.
+
+4. **Immunization Overview Widget (`immunization-overview-widget`)**: This is a small, summary card intended for placement on other dashboards, like the main patient summary. It is **not assigned to a dashboard slot by default**.
+
+To add the overview widget to the patient summary dashboard, add the following to your `extensions.json` configuration:
+
+```json
+{
+  "name": "immunization-overview-widget",
+  "slot": "patient-chart-summary-dashboard-slot",
+  "order": 8
+}
+```
+
+### Frontend Configuration
+
+Configure the widget by setting values in your implementation's configuration file (typically `config.json` or via the System Administration module). The following parameters are available:
+
+---
+
+### Configurable Parameters Summary
+
+| Parameter                    | Type     | Description                                                                                                                  | Default           |
+| ---------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------- | ----------------- |
+| **`immunizationConceptSet`** | `string` | A UUID or concept mapping (e.g., `"CIEL:984"`) that resolves to a **concept set** containing all available vaccine concepts. | `"CIEL:984"`      |
+| **`sequenceDefinitions`**    | `array`  | Defines the **dose and booster schedules** for each vaccine. Each entry represents one vaccine and its sequence definitions. | See example below |
+
+---
+
+### Example Configuration
+
+```json
+{
+  "immunizationConceptSet": "CIEL:984",
+  "sequenceDefinitions": [
+    {
+      "vaccineConceptUuid": "783AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
+      "sequences": [
+        { "sequenceLabel": "Dose-1", "sequenceNumber": 1 },
+        { "sequenceLabel": "Dose-2", "sequenceNumber": 2 },
+        { "sequenceLabel": "Dose-3", "sequenceNumber": 3 },
+        { "sequenceLabel": "Dose-4", "sequenceNumber": 4 },
+        { "sequenceLabel": "Booster-1", "sequenceNumber": 11 },
+        { "sequenceLabel": "Booster-2", "sequenceNumber": 12 }
+      ]
+    }
+  ]
+}
+```
+
+**Note**: Replace `vaccineConceptUuid` with your actual vaccine concept UUIDs.
+
+---
+
+### Configuration Notes
+
+- **Dose numbering convention**:
+  - `1–9` → Primary doses
+  - `11–19` → Booster doses
+- If `sequenceDefinitions` is not provided, vaccines are treated as single-dose vaccines without predefined schedules.
+- `sequenceLabel` values are used as translation keys in the UI for localization.
+- You can add multiple vaccine definitions to represent your national or local immunization program.
+
+## Backend Setup Requirements
+
+The immunizations feature requires backend configuration in the OpenMRS [FHIR2 module](https://github.com/openmrs/openmrs-module-fhir2).
+
+### Required Global Properties
+
+- `fhir2.immunizationsEncounterTypeUuid` - UUID of the encounter type for immunization encounters
+- `fhir2.administeringEncounterRoleUuid` - UUID of the encounter role for the administering provider
+
+### Required Concept Mappings
+
+The following CIEL concepts must be mapped:
+
+| CIEL Code | Concept Name | Required |
+|-----------|--------------|----------|
+| CIEL:1421 | Immunization grouping concept | ✅ Required |
+| CIEL:984 | Vaccine | ✅ Required |
+| CIEL:1410 | Vaccination date | ✅ Required |
+| CIEL:1418 | Dose number | ✅ Required |
+| CIEL:1419 | Manufacturer | ✅ Required |
+| CIEL:1420 | Lot number | ✅ Required |
+| CIEL:165907 | Expiration date | ✅ Required |
+| CIEL:161011 | Free text comment | ⚠️ Optional |
+| CIEL:170000 | Date next dose | ⚠️ Optional |
+
+## Implementation Checklist
+
+### Backend Setup (Required)
+
+- [ ] Configure global property `fhir2.immunizationsEncounterTypeUuid` with encounter type UUID
+- [ ] Configure global property `fhir2.administeringEncounterRoleUuid` with encounter role UUID
+- [ ] Verify all required CIEL concept mappings exist (CIEL:1421, CIEL:984, CIEL:1410, CIEL:1418, CIEL:1419, CIEL:1420, CIEL:165907)
+- [ ] Verify optional CIEL concept mappings if using notes or next dose date features (CIEL:161011, CIEL:170000)
+
+### Frontend Setup (Required)
+
+- [ ] Configure `immunizationConceptSet` to point to your implementation's concept set for vaccines.
+- [ ] Configure `sequenceDefinitions` for all vaccines that have a multi-dose or booster schedule.
+- [ ] Set user permissions for recording and managing immunizations.
+
+### Optional Customizations
+
+- [ ] Add or modify `sequenceDefinitions` to match local or national immunization programs.
+- [ ] Add translations for custom `sequenceLabel` values if supporting multiple languages.
+
+## Key Files for Customization
+
+- **`src/config-schema.ts`**: Main configuration for vaccine concept sets and dose schedules.
+- **`src/immunizations/immunizations-detailed-summary.component.tsx`**: The main component for the immunization summary view.
+- **`src/immunizations/immunization-history-dashboard.component.tsx`**: The component for the chronological history view.
+- **`src/immunizations/immunizations-form.workspace.tsx`**: The workspace form for adding and editing immunizations.