@unite-us/app-create-referral 0.2.4 → 0.2.5

package/README.md

@@ -1,10 +1,19 @@
-# App Create Referral
 
 This project is intended to be used from a parent application like [unite-us/front-end](https://github.com/unite-us/front-end) or [unite-us/uniteus-emr](https://github.com/unite-us/uniteus-emr)
 
-[Technical Design Document](https://uniteus.atlassian.net/wiki/spaces/AppEng/pages/3819208813/Tech+Design+Create+Referral+Project) (in progress)
+## Table of Contents
+- [Table of Contents](#table-of-contents)
+- [Setup](#setup)
+  - [For Frontend (WebApp) Parent project](#for-frontend-webapp-parent-project)
+  - [For SmartApp (EMR) Parent project](#for-smartapp-emr-parent-project)
+- [Architecture](#architecture)
+- [Usages in parent apps](#usages-in-parent-apps)
+- [Testing](#testing)
+- [Releases](#releases)
+  - [How to update `app-create-referral` version in parent apps](#how-to-update-app-create-referral-version-in-parent-apps)
+  - [When to update the version in parent apps?](#when-to-update-the-version-in-parent-apps)
 
-### Setup
+## Setup
 To develop locally follow this steps:
 
 1- Open a command line console:
@@ -13,48 +22,233 @@ To develop locally follow this steps:
   
   $ npm i && npm link && npm run build:dist:watch
 ```
-This install the packages, create a link for this project (to be consumed from a parent app) and starts the server in watch mode, all the changes you do will trigger a rebuild and you will have the latest version)
+This installs the packages, creates a link for this project (to be consumed from a parent app) and starts the server in watch mode. Development changes will trigger a rebuild and refresh the browser.
 
-## For EMR Parent project
+### For Frontend (WebApp) Parent project
 
-The branch we are using for development is **smrt-create-referral**:
+```
+  // open a new terminal
+  // from the folder in `front-end/packages/app-client`
+  $ npm link @unite-us/app-create-referral
+  $ npm start
+```
+- Go to http://localhost:8080 and log in as a user with the `uup-459-superset-phase-2` feature flag enabled (ex: `spero@perms.test`)
+- Find the entrypoint you want to check, e.g from the Client Facesheet, click the Refer button, it should take you to the Search step and then land in the referral flow
+
+### For SmartApp (EMR) Parent project
 
 ```
+  // open a new terminal
   // from the root folder in uniteus-emr project
   $ npm i
-  $ git checkout smrt-create-referral
   $ npm link @unite-us/app-create-referral
   $ npm start
 ```
-- Go to http://localhost:8081 and log in as a user with the `hint11EhrSearchApiCutover` feature flag enabled (ex: `costanza@uniteus.com`)
-- Follow the steps to create a new referral clicking the Create Referral button.
-- Then go to [How to create a new version](#how-to-create-a-new-version)
+- Go to http://localhost:8081 and log in as a user with the `uup-459-superset-phase-2` feature flag enabled (ex: `costanza@uniteus.com`)
+- Find the entry point you want to check (e.g click the "Create Referral" button); it should take you to the Search step. Once you select program(s), click the "Added Resources" button to open the drawer and click the "Create Referrals" button to land in the referral flow.
+
+## Architecture
+
+Please find the [Technical Design Document](https://uniteus.atlassian.net/wiki/spaces/AppEng/pages/3819208813/Tech+Design+Create+Referral+Project) to know about the project.
+
+The application includes it's own Router and React Query Client. This allows us to use React Testing Library with Mock Service Workers (MswJS) for testing as an standalone app.
+
+- `__testUtils__/`: Testing utils and mock server
+- `actions/`: Custom api calls
+- `api/`: Default hooks and axios instances setup
+- `common/`: Common components (this can be merged with the components folder)
+- `components/`: Components 
+- `constants/`: Constants
+- `context/`: App Context to serve as source of truth of the data.
+- `hooks/`: Custom hooks
+- `pages/`: Pages components that relates to each route
+- `styles/`: Custom scss files
+- `utils/`: Utils functions
+
+`AppReferrals.js`:  This is the main component (entry point) of the app with the Router
+
+## Usages in parent apps
+
+The AppReferrals component is wired up in AppClient and EMR in specific routes:
+
+AppClient:
 
-## How to create a new version
+- `<Route path="referrals/2/*" component={Referrals} />`
+- Points to: https://github.com/unite-us/front-end/blob/master/packages/app-client/src/pages/referrals/2/Referrals.jsx
 
-After you are done with your changes, create a PR and **AFTER** it's merged, a Github Action will bump the version for you automatically and will create a new commit in the history, just only need to wait for the action to finish and check the commits for one that looks like this, eg:
 ```
-Automated Version Bump [skip ci] bumps version to 0.1.21
+ <AppReferrals
+    // general settings, urls needed to build the axios instances
+    appSettings={
+      {
+        env: {              
+          getAuthToken,
+          coreUrl: CORE_API,
+          employeeId: currentEmployee?.id,
+          providerId: currentEmployee?.provider.id,
+          sharesUrl: SHARES_URL,
+          consentUrl: CONSENT_APP_URL,
+        },
+        basename,
+      }
+    }
+    
+    // this will be set to the app context
+    appState={{            
+      currentEmployee,
+      currentProvider,
+      enums,
+      source: 'app-client',
+    }}
+
+    // callbacks functions invoked in specific places throughout the app
+    callbacks={{           
+      notify: {
+        error: (message) => Notifier.dispatch('error', message),
+        success: (message) => Notifier.dispatch('success', message),
+        warn: (message) => Notifier.dispatch('warning', message),
+      },
+      trackEventCallback: trackEvent,
+      consent: {
+        updateGlobalState,
+      },
+      onReferralCompleted: ({ hasOnlyOONReferrals }) => {
+        browserHistory.push({
+          pathname: hasOnlyOONReferrals ? '/dashboard/oon-cases/open' : '/dashboard/referrals/sent/all',
+        });
+      },
+      onSaveDraftReferral: () => {
+        browserHistory.push({
+          pathname: '/dashboard/referrals/sent/draft',
+        });
+      },
+      onSubmitConsent: async () => {
+        // refresh ClientHeader to refetch person to show new consent status
+        setShowHeader(false);
+        setTimeout(() => {
+          setShowHeader(true);
+        });
+      },
+      onDeselectProgram: dispatchRemoveProgram,
+      onClickSearchStep: (searchParams, selectedPrograms) => {
+        dispatchRemoveAllPrograms();
+        if (!isEmpty(selectedPrograms)) {
+          dispatchAddPrograms(selectedPrograms);
+        }
+
+        const serializedSearchParams = serializeQueryParams(omitBy(searchParams, isNil));
+        const search = serializedSearchParams ? `?${serializedSearchParams}` : '';
+
+        browserHistory.push({
+          pathname: '/referrals/create/add-resources',
+          search,
+        });
+      },
+      onClickBackFromBuilder: () => {
+        let backUrl = `/referrals/create/add-resources?person=${personId}`;
+        if (resourceListId) { backUrl += `&resource_list=${resourceListId}`; }
+
+        browserHistory.replace(`${backUrl}&from-referral=true`);
+      },
+    }}
+
+    // components as props to avoid adding dependencies inside the app-create-referral repo
+    components={{
+      consent: ConsentReferrals,
+    }}
+/>
+
+//...
 ```
-In this case, the new version is **0.1.21**
+EMR:
+- `<Route path="referrals/2/*" components={Referrals} />`
+- Points to: https://github.com/unite-us/uniteus-emr/blob/master/src/pages/%5Bsession_id%5D/2/referrals/Referrals.jsx
 
-## How to make the parent app use your new version
+In both WebApp and SmartApp, where the user navigates to the referral flow, we need to set the `selectedPrograms`, as in `SupersetSearch.jsx`
 
-You need to update the package.json in the parent app, eg: unite-us/uniteus-emr
+```
+  ...
+  const { dispatch } = useAppCreateReferralContext();
 
-for EMR: https://github.com/unite-us/uniteus-emr/blob/smrt-create-referral/package.json#L33
+  const onClickNext = () => {
+    const programsToUse = Object.keys(programToServiceTypesDict)
+        .map((id) => ({ id, services: programToServiceTypesDict[id] }));
 
- ```
-    //"@unite-us/app-create-referral": "0.1.1",
-    "@unite-us/app-create-referral": "0.1.1"
-    
- ```
-  - Open the terminal
+    // this sets the selected programs needed inside the referral flow
+    dispatch(
+      init({
+        selectedPrograms: programsToUse,
+        person: personId,
+        resourceListId,
+      }),
+    );
+
+    browserHistory.push({
+      pathname: '/referrals/2/create/builder',
+    });
+  }
+```
+
+## Testing
+
+The app uses React Testing Library and Mock Service Worker (MswJS) for unit testing and integration testing across components.
+
+`/__testUtils__/`: Includes the custom `render` using React Testing Library and the Mock Server that intercepts http requests during the tests
+
+`/pages/*/__tests__`: Each page includes a folder with the tests for the screen.
+
+Please review the existing tests and follow along to keep adding more scenarios as new features are being added.
+
+## Releases
+
+There is Github Action configured for the `main` branch that will generate a new version after a PR has been merged into `main`, usually it's the latest commit in the history for the main branch, e.g:
+```
+Automated Version Bump [skip ci] bumps version to 0.1.85
+```
+
+The new version created is `0.1.85`
+
+### How to update `app-create-referral` version in parent apps
+
+There are a few steps:
+  1. Update the dependency in the corresponding `package.json`
+  2. Install the dependencies
+  3. Create the PR to merge the new version
+
+- unite-us/front-end
+  
+  Update the `package.json`: https://github.com/unite-us/front-end/blob/master/packages/app-client/package.json
+
+  ```
+    "@unite-us/app-create-referral": "0.1.85"    
+  ```
+    - Open the terminal
+  ```
+    // from the root folder of the front-end repo, run yarn:
+    $ yarn
+  ```
+  This will update the `yarn.lock` file with the new version, your PR to bump the version should include the `package.json` and the `yarn.lock` file changes, e.g:
+  https://github.com/unite-us/front-end/pull/4522/files
+
+- unite-us/uniteus-emr
+
+  Update the `package.json`: https://github.com/unite-us/uniteus-emr/blob/master/package.json
+
+  ```
+      "@unite-us/app-create-referral": "0.1.85"    
+  ```
+    - Open the terminal
   ```
     $ npm i
   ```
-  This will update the package-lock.json with the new dependency.
-  - Create a PR in the parent project to use the new version  
+This will update the `package-lock.json` file with the new version, your PR to bump the version should include the `package.json` and the `package-lock.json` file changes, e.g:
+https://github.com/unite-us/uniteus-emr/pull/1883/files
+
+Finally, create a PR in the parent project to use the new version.
+
+### When to update the version in parent apps?
+It depends on the release cadence and the speed to verify the features by the team; one approach could be keeping the parent apps with the latest versions at all times, shipping faster but also brings the risk of "untested" features might go into production because in very small timeframes probably the tester doesn't have time to verified the feature; and any team can do a release of the parent app with a version that you still dont want to make it to production.
 
+Another more conservative approach could be to update the version only when the team is ready to test the features and ensured they will be tested in a short timeframe (before any team does a release) to avoid the risk mentioned above; this approach is potentially not as fast, but it should keep the production releases more controlled. 
 
-That's all Folks!
+It's up to the team to decide the cadence and speed of the releases.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unite-us/app-create-referral",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "main": "./dist/index.js",
   "author": "Alex Morales",
   "dependencies": {