@smals-belgium-shared/vidis-diarynote/README.md

Diary notes web component

# Vidis diary notes web component
## Context

VIDIS (Virtual Integrated Drug Information System) integrates several sources and systems:
- [Recip-e][Recip-e] prescriptions
- [Vitalink][Vitalink] / [RSW][RSW] / [RSB][RSB] medication scheme
- [Vitalink][Vitalink] / [RSW][RSW] / [RSB][RSB] diary notes
- [Farmaflux][Farmaflux] delivered medications

In order to be reused by other software vendors, the VIDIS front-end is now split into [web components][Web component explanations].
The container application will have to provide the input parameters to provision the web component with a working context.

## Prerequisites

- A supported browser [by our Web Components](https://angular.dev/reference/versions#browser-support) AND [by eHealth][Supported browsers]
- A valid VIDIS token. It could be obtained from [eHealth Token eXchange][eHealth IAM] service. This token must be refreshed periodically in order to be used by VIDIS
- Notify partners that are using REST APIs so your VIDIS tokens & clients will be trusted :
    - [Vitalink][Vitalink] & their Apigee service – Contact: vitalink-support@smals.be 
    - [Farmaflux][Farmaflux] – Contact: vidis@farmaflux.be

⚠️ IE (internet explorer) is not supported. You can include [polyfill scripts ("polyfills")](https://www.webcomponents.org/polyfills) for the browsers that you must support.


## Features

The diary notes web component allows patients and caregivers to keep detailed, organized records of health-related events, changes, or observations, which can be crucial for ongoing treatment or communication with healthcare providers.

### List of diary notes

The main view displays a list of all diary notes that have been created by the patient or caregiver. For each entry, the following key information is shown:

- **Author:** The person who wrote the note (e.g., patient, caregiver, or healthcare provider).
- **Creation Date:** The date and time when the note was created.
- **Summary of the Note:** A brief preview or summary of the note’s content, allowing users to quickly assess the subject matter of each entry without opening the full note.

### Note management

- **Delete Notes:** Users can delete notes that are no longer needed or relevant, helping to keep the diary organized and clutter-free.
- **Filtering:** The component allows users to filter notes based on specific criteria, such as:
	- **Period:** Filter notes by date range, helping users review notes from a particular timeframe (e.g., last week, last month).
	- **Author:** Users can filter notes by the author, enabling them to view entries made by a specific person (e.g., only the patient’s notes or caregiver’s notes).
	- **Roles:** Filter by roles (e.g., caregiver, patient, healthcare provider) to distinguish the perspective of different authors.
- **Sorting:** Notes can be sorted by different parameters, such as creation date or author, giving users more control over how they view the list.
- **Adding a Note:**
	- **Text-only Notes:** Users can add new diary notes by simply typing in text.
	- **Notes with Attachments:** Users can also add attachments to their notes, allowing for richer documentation (e.g., photos, reports, or scanned documents).

⚠️ **Attachment Restrictions:** Attachments have size limitations (e.g., maximum file size) and format restrictions (e.g., PDF, JPG, PNG) as explained by safes cookbook document.

## Inputs

| Name                        | Mandatory | Possible values        | Description                                                                                                                                                                                                                                                                     |
|-----------------------------|-----------|------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `language`                  | true      | `en`, `de`, `fr`, `nl` | The language holds the current language as a value, which means it can change over time if the user changes his/her preferred language. The web component adapts the translations based on the value set. The values of the language property are defined in the Language enum. |
| `configName`                | true      | `acc`, `prod`          | Name of the configuration the application and the components are being deployed to.                                                                                                                                                                                             |
| `services`                  | true      | N/A                    | Set of services to be consumed by the component. see [USAGE](#Usage).                                                                                                                                                                                                           |
| `professional`              | true      | `true`, `false`        | Indicates whether the component is being used in a professional context. If set to `true`, the `ssin` input must be provided and will be used to identify the patient. If `false`, the SSIN will be retrieved automatically from the authentication token.         |
| `ssin`                      | true      | N/A                    | The patient's SSIN. When `professional` is `false`, this value is ignored and the SSIN is extracted from the authentication token.                                                                                       |
| `offlineDataStorageEnabled` | true      | `true`, `false`        | A boolean flag indicating whether offline data storage has been enabled by the user. When true, the web component can store and retrieve data locally for offline access.                                                                                                       |
| `isOfflineAuthenticated`    | true      | `true`, `false`        | A boolean flag indicating whether the web component is being accessed from an offline state.                                                                                                                                                                                    |
| `exchangeClientId`          | false     | N/A                    | The client id used for the token exchange                                                                                                                                                                                                                                       |

## Outputs

| Name            | Type                                                  | Description                                                                                                         |
|-----------------|-------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------|
| `getTotalItems` | number                                                | Gets the number of total diary notes                                                                                |   
| `onDownload`    | { fileName: string; content: Blob; mimeType: string } | Download event diary note attachment                                                                                |  
| `onError`       | {reported: boolean}                                   | Emitted after the error dialog closes. reported is true if the user confirmed reporting the error; otherwise false. |


## Usage

```html
<!DOCTYPE html>
<html>
<head>
	<meta charset="utf-8">
	<title>Vidis diary notes web component</title>
	<meta name="viewport" content="width=device-width, initial-scale=1">
	<script type="module" src="vidis-diarynote/diarynote.js"></script>
	<link rel="stylesheet" href="vidis-diarynote/diarynote.css">
</head>
<body>
<script>
	const wc = document.createElement("vidis-diarynote");

	// Common inputs for all VIDIS web components
	// Refer to https://www.npmjs.com/package/@smals-belgium/myhealth-wc-integration for more details
	wc.language = 'en'
	wc.configName = 'acc';
	wc.services = {
		cache: {
			get: (key) => (undefined),
			set: (key, value) => {
			},
			remove: (key) => {
			}
		},
		getAccessToken: async (audience) => "TODO : the eHealth OAuth2 JWT token.",
		registerRefreshCallback: () => {
		}
	}

	// Example on how to provide extra input parameter(s), if needed / requested by the component
	// wc["attributeName"] = "myValue" 

	// Example on how to listen to output parameter(s)
	wc.addEventListener("eventName", (event) => {
		console.log(`event:`, event)
		const params = event.detail;
		console.log('param:', params);
	})

	// Example on how to listen to output parameter(s), for printing
	wc.addEventListener("onPrint", (event) => {
		console.log(`event:`, event)
		const params = event.detail;
		console.log('param:', params);

		const byteArray = new Uint8Array(atob(params.content).split('').map(char => char.charCodeAt(0)))
		const blob = new Blob([byteArray], {type: 'application/pdf'})
		const url = window.URL.createObjectURL(blob)
		window.open(url, '_blank').print()
	})

	document.body.append(wc);
</script>
</body>
</html>
```


## Versioning

This project follows [Semantic Versioning][Semver]. Each release is categorized by major, minor, and patch updates. Significant changes that may break existing integrations will be introduced with major versions. Please check [CHANGELOG.md](CHANGELOG.md) file for more info.

## Accessibility

We are committed to making our web components accessible to all users. Our components are:
- Screen reader friendly : Designed to work well with popular screen readers (Talkback / VoiceOver / ...)
- Responsive : Adapt to various screen sizes (desktop / mobile).
- Compliant: Meet [accessibility criteria][OFAC], including ARIA labels and keyboard navigation

## Customizations

The web components are build with [Angular Material][Angular Material]. The styling of it is overwritten by the “My Health” portal, by there [design kit][MHDK].

## Troubleshoots

If you encounter issues while using the web components :

- Ensure that your token is valid and hasn't expired. For assistance, contact [eHealth][eHealth IAM].
- Ensure you are using the latest version of the web components
- Ensure you are using a supported browser and that you have cleared your cache if issues persist.
- Ensure your organization, browser or device don't block calls to VIDIS API by any way.
- If none of the above, please contact mijngeneesmiddelen@riziv-inami.fgov.be / mesmedicaments@riziv-inami.fgov.be

## License

[GNU Lesser General Public License v3.0 or later](https://spdx.org/licenses/LGPL-3.0-or-later.html)

[Recip-e]: https://recip-e.be/
[Vitalink]: https://www.vitalink.be/
[RSW]: https://www.reseausantewallon.be/
[RSB]: https://brusselshealthnetwork.be/
[Farmaflux]: https://www.farmaflux.be/
[Web component explanations]: https://www.webcomponents.org/introduction
[eHealth IAM]:https://www.ehealth.fgov.be/ehealthplatform/nl/service-i.am-identity-access-management 
[MHDK]: https://www.npmjs.com/package/@myhealth-belgium/design-kit
[Angular Material]: https://material.angular.io/
[OFAC]: https://openfed.github.io/AccessibilityCheck/
[Semver]: https://docs.npmjs.com/about-semantic-versioning
[MHWCI]: https://www.npmjs.com/package/@myhealth-belgium/webcomponent-integration
[Supported browsers]: https://www.ehealth.fgov.be/nl/page/hoe-toegang-krijgen-tot-applicaties