@ampath/esm-dha-workflow-app 4.0.0-next.4

package/src/boxes/slot/boxes.scss

@@ -0,0 +1,29 @@
+/* General features of extension styling are controlled
+ * at the slot level. The boxes should know as little as
+ * possible about the context where they are used, so
+ * they do not set their own sizes.
+ *
+ * `> * > *` is used to target the outermost DOM node of
+ * the extension.
+ */
+ @use '@carbon/layout';
+
+.box > * > * {
+  height: layout.$spacing-10;
+  width: layout.$spacing-10;
+}
+
+.boxes {
+  margin: layout.$spacing-07 0;
+  display: flex;
+  gap: layout.$spacing-05;
+}
+
+.container {
+  max-width: 50rem;
+  margin-top: layout.$spacing-09;
+
+  > * + * {
+    margin-top: layout.$spacing-06;
+  }
+}

package/src/config-schema.ts

@@ -0,0 +1,43 @@
+import { Type, validator } from '@openmrs/esm-framework';
+
+/**
+ * This is the config schema. It expects a configuration object which
+ * looks like this:
+ *
+ * ```json
+ * { "casualGreeting": true, "whoToGreet": ["Mom"] }
+ * ```
+ *
+ * In OpenMRS Microfrontends, all config parameters are optional. Thus,
+ * all elements must have a reasonable default. A good default is one
+ * that works well with the reference application.
+ *
+ * To understand the schema below, please read the configuration system
+ * documentation:
+ *   https://openmrs.github.io/openmrs-esm-core/#/main/config
+ * Note especially the section "How do I make my module configurable?"
+ *   https://openmrs.github.io/openmrs-esm-core/#/main/config?id=im-developing-an-esm-module-how-do-i-make-it-configurable
+ * and the Schema Reference
+ *   https://openmrs.github.io/openmrs-esm-core/#/main/config?id=schema-reference
+ */
+export const configSchema = {
+  casualGreeting: {
+    _type: Type.Boolean,
+    _default: false,
+    _description: 'Whether to use a casual greeting (or a formal one).',
+  },
+  whoToGreet: {
+    _type: Type.Array,
+    _default: ['World'],
+    _description: 'Who should be greeted. Names will be separated by a comma and space.',
+    _elements: {
+      _type: Type.String,
+    },
+    _validators: [validator((v) => v.length > 0, 'At least one person must be greeted.')],
+  },
+};
+
+export type Config = {
+  casualGreeting: boolean;
+  whoToGreet: Array<string>;
+};

package/src/declarations.d.ts

@@ -0,0 +1,5 @@
+declare module '*.css';
+declare module '*.scss';
+declare module '*.png';
+
+declare type SideNavProps = object;

package/src/greeter/greeter.component.tsx

@@ -0,0 +1,42 @@
+/**
+ * This component demonstrates usage of the config object. Its structure
+ * comes from `../config-schema.ts`. For more information about the
+ * configuration system, read the docs: https://o3-docs.vercel.app/docs/configuration-system
+ */
+import React from 'react';
+import { Tile } from '@carbon/react';
+import { Trans, useTranslation } from 'react-i18next';
+import { useConfig } from '@openmrs/esm-framework';
+import { type Config } from '../config-schema';
+import styles from './greeter.scss';
+
+const Greeter: React.FC = () => {
+  const { t } = useTranslation();
+  const config: Config = useConfig();
+
+  return (
+    <div className={styles.container}>
+      <h5>{t('configSystem', 'Configuration system')}</h5>
+      <p>
+        <Trans key="configSystemExplainer">
+          The greeting shown below is driven by the configuration system. To change the configuration properties, click
+          the spanner icon in the navbar to pull up the Implementer Tools panel. Then, type <em>template</em> into the{' '}
+          <em>Search configuration</em> input. This should filter the configuration properties to show only those that
+          are relevant to this module. You can change the values of these properties and click <em>Save</em> to see the
+          changes reflected in the UI
+        </Trans>
+        .
+      </p>
+      <div className={styles.greeting}>
+        <Tile className={styles.tile}>
+          {config.casualGreeting ? <Trans key="casualGreeting">hey</Trans> : <Trans key="formalGreeting">hello</Trans>}{' '}
+          {/* t('world')  */}
+          {config.whoToGreet.join(', ')}!
+        </Tile>
+      </div>
+      <br />
+    </div>
+  );
+};
+
+export default Greeter;

package/src/greeter/greeter.scss

@@ -0,0 +1,20 @@
+@use '@carbon/layout';
+@use '@carbon/type';
+
+.container {
+  max-width: 50rem;
+
+  > * + * {
+    margin-top: layout.$spacing-05;
+  }
+}
+
+.greeting {
+  text-transform: capitalize;
+}
+
+.tile {
+  border: 1px solid lightgray;
+  max-width: 15rem;
+  @include type.type-style('heading-compact-01');
+}

package/src/greeter/greeter.test.tsx

@@ -0,0 +1,28 @@
+import React from 'react';
+import { render, screen } from '@testing-library/react';
+import { useConfig } from '@openmrs/esm-framework';
+import { Config } from '../config-schema';
+import Greeter from './greeter.component';
+
+const mockUseConfig = jest.mocked(useConfig<Config>);
+
+it('displays the expected default text', () => {
+  const config: Config = { casualGreeting: false, whoToGreet: ['World'] };
+  mockUseConfig.mockReturnValue(config);
+
+  render(<Greeter />);
+
+  expect(screen.getByText(/world/i)).toHaveTextContent('hello World!');
+});
+
+it('casually greets my friends', () => {
+  const config: Config = {
+    casualGreeting: true,
+    whoToGreet: ['Ariel', 'Barak', 'Callum'],
+  };
+  mockUseConfig.mockReturnValue(config);
+
+  render(<Greeter />);
+
+  expect(screen.getByText(/ariel/i)).toHaveTextContent('hey Ariel, Barak, Callum!');
+});

package/src/index.ts

@@ -0,0 +1,46 @@
+/**
+ * This is the entrypoint file of the application. It communicates the
+ * important features of this microfrontend to the app shell. It
+ * connects the app shell to the React application(s) that make up this
+ * microfrontend.
+ */
+import { getAsyncLifecycle, defineConfigSchema } from '@openmrs/esm-framework';
+import { configSchema } from './config-schema';
+
+const moduleName = '@ampath/esm-dha-workflow-app';
+
+const options = {
+  featureName: 'Consulation Workflow',
+  moduleName,
+};
+
+/**
+ * This tells the app shell how to obtain translation files: that they
+ * are JSON files in the directory `../translations` (which you should
+ * see in the directory structure).
+ */
+export const importTranslation = require.context('../translations', false, /.json$/, 'lazy');
+
+/**
+ * This function performs any setup that should happen at microfrontend
+ * load-time (such as defining the config schema) and then returns an
+ * object which describes how the React application(s) should be
+ * rendered.
+ */
+export function startupApp() {
+  defineConfigSchema(moduleName, configSchema);
+}
+
+/**
+ * This named export tells the app shell that the default export of `root.component.tsx`
+ * should be rendered when the route matches `root`. The full route
+ * will be `openmrsSpaBase() + 'root'`, which is usually
+ * `/openmrs/spa/root`.
+ */
+export const root = getAsyncLifecycle(() => import('./root.component'), options);
+export const registry = getAsyncLifecycle(() => import('./registry/registry.component'), options);
+
+export const workflowRegistryLink = getAsyncLifecycle(() => import('./widgets/workflow-registry-link.extension'), {
+  featureName: 'workflow-registry-link',
+  moduleName,
+});

package/src/patient-getter/patient-getter.component.tsx

@@ -0,0 +1,40 @@
+/**
+ * Components that make queries delegate the query-making logic to a
+ * `.resource.ts` function. This component leverages the`usePatient`
+ * hook to fetch a patient from the backend. When the button is clicked,
+ * the `patientName` variable is set to "test", which triggers the hook
+ * to make a request to the backend. The hook returns patient data from the
+ * request, which is then rendered in the UI. The hook also returns a boolean
+ * property called `isLoading` that is set to true while the request is being
+ * made. This component renders a loading indicator while `isLoading` is true.
+ */
+
+import React, { useState } from 'react';
+import { Button, InlineLoading, Tile } from '@carbon/react';
+import { useTranslation } from 'react-i18next';
+import { usePatient } from './patient-getter.resource';
+import styles from './patient-getter.scss';
+
+function PatientGetter() {
+  const { t } = useTranslation();
+  const [patientName, setPatientName] = useState(null);
+  const { patient, isLoading } = usePatient(patientName);
+
+  return (
+    <div className={styles.container}>
+      <h5>{t('dataFetching', 'Data fetching')}</h5>
+      <p>{t('patientGetterExplainer', 'Try clicking the button below to fetch a patient from the backend')}:</p>
+      <Button onClick={() => setPatientName('test')}>{t('getPatient', 'Get a patient named')} 'test'</Button>
+      {isLoading ? <InlineLoading description={t('loading', 'Loading') + '...'} role="progressbar" /> : null}
+      {patient ? (
+        <Tile className={styles.tile}>
+          {patient
+            ? `${patient.name[0].given} ${patient.name[0].family} / ${patient.gender} / ${patient.birthDate}`
+            : null}
+        </Tile>
+      ) : null}
+    </div>
+  );
+}
+
+export default PatientGetter;

package/src/patient-getter/patient-getter.resource.ts

@@ -0,0 +1,39 @@
+import useSWR from 'swr';
+import { fhirBaseUrl, openmrsFetch } from '@openmrs/esm-framework';
+
+/**
+ * This hook searches for a patient using the provided search term from the
+ * OpenMRS FHIR API.It leverages the useSWR hook from the SWR library
+ * https://swr.vercel.app/docs/data-fetching to fetch data. SWR provides a
+ * number of benefits over the standard React useEffect hook, including:
+ *
+ * - Fast, lightweight and reusable data fetching
+ * - Built-in cache and request deduplication
+ * - Real-time updates
+ * - Simplified error and loading state handling, and more.
+ *
+ *  We recommend using SWR for data fetching in your OpenMRS frontend modules.
+ *
+ * See the docs for the underlying fhir.js Client object: https://github.com/FHIR/fhir.js#api
+ * See the OpenMRS FHIR Module docs: https://wiki.openmrs.org/display/projects/OpenMRS+FHIR+Module
+ * See the OpenMRS REST API docs: https://rest.openmrs.org/#openmrs-rest-api
+ *
+ * @param query A patient name or ID
+ * @returns The first matching patient
+ */
+
+export function usePatient(query: string) {
+  const url = `${fhirBaseUrl}/Patient?name=${query}&_summary=data`;
+  const { data, error, isLoading } = useSWR<
+    {
+      data: { entry: Array<{ resource: fhir.Patient }> };
+    },
+    Error
+  >(query ? url : null, openmrsFetch);
+
+  return {
+    patient: data ? data?.data?.entry[0].resource : null,
+    error: error,
+    isLoading,
+  };
+}

package/src/patient-getter/patient-getter.scss

@@ -0,0 +1,16 @@
+@use '@carbon/layout';
+@use '@carbon/type';
+
+.container {
+  margin-top: layout.$spacing-09;
+
+  > * + * {
+    margin-top: layout.$spacing-06;
+  }
+}
+
+.tile {
+  border: 1px solid lightgray;
+  max-width: 20rem;
+  @include type.type-style('heading-compact-01');
+}

package/src/patient-getter/patient-getter.test.tsx

@@ -0,0 +1,40 @@
+import React from 'react';
+import { render, screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import PatientGetter from './patient-getter.component';
+
+/**
+ * This is an idiomatic mock of a backend resource. We generally mock resource fetching functions like `usePatient`, rather than mocking `fetch` or anything lower-level.
+ */
+jest.mock('./patient-getter.resource.ts', () => ({
+  usePatient: jest.fn(() => ({
+    patient: {
+      birthDate: '1997-05-21',
+      gender: 'male',
+      name: [
+        {
+          family: 'Testguy',
+          given: 'Joeboy',
+          id: 'abc123',
+        },
+      ],
+    },
+  })),
+}));
+
+it('gets a patient when the button is clicked', async () => {
+  render(<PatientGetter />);
+
+  const user = userEvent.setup();
+  const heading = screen.getByRole('heading', { name: /data fetching/i });
+  const button = screen.getByRole('button', {
+    name: /get a patient named 'test'/i,
+  });
+
+  expect(heading).toBeInTheDocument();
+  expect(button).toBeInTheDocument();
+
+  await waitFor(() => user.click(button));
+
+  expect(screen.getByText(/Joeboy Testguy \/ male \/ 1997-05-21/)).toBeInTheDocument();
+});

package/src/registry/registry.component.tsx

@@ -0,0 +1,7 @@
+import React from 'react';
+interface RegistryComponentProps {}
+const RegistryComponent: React.FC<RegistryComponentProps> = () => {
+  return <>Registry Component</>;
+};
+
+export default RegistryComponent;

package/src/resources/resources.component.tsx

@@ -0,0 +1,56 @@
+import React from 'react';
+import { ClickableTile } from '@carbon/react';
+import { ChevronRight } from '@carbon/react/icons';
+import { useTranslation } from 'react-i18next';
+import styles from './resources.scss';
+
+function Resources() {
+  const { t } = useTranslation();
+
+  return (
+    <div className={styles.resources}>
+      <h4 className={styles.heading}>{t('resources', 'Resources')}</h4>
+      <span className={styles.explainer}>{t('usefulLinks', 'Below are some links to useful resources')}:</span>
+      <div className={styles.cardsContainer}>
+        <Card
+          title={t('getStarted', 'Get started')}
+          subtitle={t('getStartedExplainer', 'Create a frontend module from this template') + '.'}
+          link="https://github.com/openmrs/openmrs-esm-home-app/generate"
+        />
+        <Card
+          title={t('frontendDocs', 'Frontend docs')}
+          subtitle={t('learnExplainer', 'Learn how to use the O3 framework') + '.'}
+          link="https://openmrs.atlassian.net/wiki/spaces/docs/pages/151093495/Introduction+to+O3+for+Developers"
+        />
+        <Card
+          title={t('designDocs', 'Design docs')}
+          subtitle={t('designDocsExplainer', 'Read the O3 design documentation') + '.'}
+          link="https://zeroheight.com/23a080e38/p/880723-introduction"
+        />
+        <Card
+          title={t('connect', 'Connect')}
+          subtitle={t('connectExplainer', 'Get in touch with the community') + '.'}
+          link="https://slack.openmrs.org/"
+        />
+      </div>
+    </div>
+  );
+}
+
+function Card({ title, subtitle, link }: { title: string; subtitle: string; link: string }) {
+  return (
+    <a href={link} target="_blank" rel="noopener noreferrer" className={styles.cardLink}>
+      <ClickableTile className={styles.card}>
+        <div className={styles.cardContent}>
+          <div className={styles.title}>
+            <h4>{title}</h4>
+            <ChevronRight />
+          </div>
+          <span className={styles.subtitle}>{subtitle}</span>
+        </div>
+      </ClickableTile>
+    </a>
+  );
+}
+
+export default Resources;

package/src/resources/resources.scss

@@ -0,0 +1,68 @@
+@use '@carbon/layout';
+@use '@carbon/type';
+
+.container {
+  padding: layout.$spacing-07;
+}
+
+.heading {
+  @include type.type-style('heading-04');
+  margin: layout.$spacing-05 0;
+}
+
+.explainer {
+  display: block;
+}
+
+.resources {
+  margin-top: layout.$spacing-10;
+  margin-bottom: layout.$spacing-09;
+
+  > * + * {
+    margin-right: layout.$spacing-05;
+  }
+}
+
+.cardsContainer {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
+  column-gap: layout.$spacing-06;
+  margin-top: layout.$spacing-07;
+  max-width: 75%;
+}
+
+.card {
+  margin: layout.$spacing-03 0;
+  display: flex;
+  align-items: center;
+
+  &:hover {
+    border: 1px solid lightgray;
+  }
+
+  svg {
+    margin-left: layout.$spacing-02;
+  }
+}
+
+.cardLink {
+  text-decoration: none;
+  color: inherit;
+  display: block;
+}
+
+.cardContent {
+  display: flex;
+  flex-direction: column;
+}
+
+.title {
+  display: flex;
+  align-items: center;
+  margin-bottom: layout.$spacing-05;
+
+  h4 {
+    @include type.type-style('heading-02');
+  }
+}
+

package/src/root.component.tsx

@@ -0,0 +1,39 @@
+/**
+ * From here, the application is pretty typical React, but with lots of
+ * support from `@openmrs/esm-framework`. Check out `Greeter` to see
+ * usage of the configuration system, and check out `PatientGetter` to
+ * see data fetching using the OpenMRS FHIR API.
+ *
+ * Check out the Config docs:
+ *   https://openmrs.github.io/openmrs-esm-core/#/main/config
+ */
+
+import React from 'react';
+import { useTranslation } from 'react-i18next';
+import { Boxes } from './boxes/slot/boxes.component';
+import Greeter from './greeter/greeter.component';
+import PatientGetter from './patient-getter/patient-getter.component';
+import Resources from './resources/resources.component';
+import styles from './root.scss';
+
+const Root: React.FC = () => {
+  const { t } = useTranslation();
+
+  return (
+    <div className={styles.container}>
+      <h3 className={styles.welcome}>{t('welcomeText', 'Welcome to the O3 Template app')}</h3>
+      <p className={styles.explainer}>
+        {t('explainer', 'The following examples demonstrate some key features of the O3 framework')}.
+      </p>
+      {/* Greeter: demonstrates the configuration system */}
+      <Greeter />
+      {/* Boxes: demonstrates the extension system */}
+      <Boxes />
+      {/* PatientGetter: demonstrates data fetching */}
+      <PatientGetter />
+      <Resources />
+    </div>
+  );
+};
+
+export default Root;

package/src/root.scss

@@ -0,0 +1,15 @@
+@use '@carbon/layout';
+@use '@carbon/type';
+
+.container {
+  padding: layout.$spacing-07;
+}
+
+.welcome {
+  @include type.type-style('heading-04');
+  margin: layout.$spacing-05 0;
+}
+
+.explainer {
+  margin-bottom: layout.$spacing-07;
+}

package/src/root.test.tsx

@@ -0,0 +1,51 @@
+/**
+ * This is the root test for this page. It simply checks that the page
+ * renders. If the components of your page are highly interdependent,
+ * (e.g., if the `Root` component had state that communicated
+ * information between `Greeter` and `PatientGetter`) then you might
+ * want to do most of your testing here. If those components are
+ * instead quite independent (as is the case in this example), then
+ * it would make more sense to test those components independently.
+ *
+ * The key thing to remember, always, is: write tests that behave like
+ * users. They should *look* for elements by their visual
+ * characteristics, *interact* with them, and (mostly) *assert* based
+ * on things that would be visually apparent to a user.
+ *
+ * To learn more about how we do testing, see the following resources:
+ *   https://o3-docs.vercel.app/docs/frontend-modules/testing
+ *   https://kentcdodds.com/blog/how-to-know-what-to-test
+ *   https://kentcdodds.com/blog/testing-implementation-details
+ *   https://kentcdodds.com/blog/common-mistakes-with-react-testing-library
+ *
+ * Kent C. Dodds is the inventor of `@testing-library`:
+ *   https://testing-library.com/docs/guiding-principles
+ */
+import React from 'react';
+import { render, screen } from '@testing-library/react';
+import { useConfig } from '@openmrs/esm-framework';
+import { Config } from './config-schema';
+import Root from './root.component';
+
+/**
+ * This is an idiomatic way of dealing with mocked files. Note that
+ * `useConfig` is already mocked; the Jest moduleNameMapper (see the
+ * Jest config) has mapped the `@openmrs/esm-framework` import to a
+ * mock file. This line just tells TypeScript that the object is, in
+ * fact, a mock, and so will have methods like `mockReturnValue`.
+ */
+const mockUseConfig = jest.mocked(useConfig<Config>);
+
+it('renders a landing page for the Home app', () => {
+  const config: Config = { casualGreeting: false, whoToGreet: ['World'] };
+  mockUseConfig.mockReturnValue(config);
+
+  render(<Root />);
+
+  expect(screen.getByRole('heading', { name: /welcome to the o3 home app/i })).toBeInTheDocument();
+  expect(screen.getByRole('heading', { name: /configuration system/i })).toBeInTheDocument();
+  expect(screen.getByRole('heading', { name: /extension system/i })).toBeInTheDocument();
+  expect(screen.getByRole('heading', { name: /data fetching/i })).toBeInTheDocument();
+  expect(screen.getByRole('heading', { name: /resources/i })).toBeInTheDocument();
+  expect(screen.getByRole('button', { name: /get a patient named 'test'/i })).toBeInTheDocument();
+});

package/src/routes.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://json.openmrs.org/routes.schema.json",
+  "backendDependencies": {},
+   "extensions": [
+    {
+      "component": "workflowRegistryLink",
+      "name": "workflow-registry-link",
+      "slot": "app-menu-slot",
+      "online": true,
+      "offline": true
+    }
+  ],
+  "pages": [
+    {
+      "component": "registry",
+      "route": "workflow"
+    }
+  ]
+}

package/src/side-nav/side-menu.scss

@@ -0,0 +1,38 @@
+@use '@carbon/layout';
+@use '@carbon/type';
+@use '@openmrs/esm-styleguide/src/vars' as *;
+
+.link > div a:nth-child(1) {
+  height: layout.$spacing-09;
+  padding: layout.$spacing-06 0 layout.$spacing-06 1.25rem;
+  color: $ui-04;
+  @extend .productiveHeading01;
+  border-left: layout.$spacing-02 solid transparent;
+}
+
+:global(.omrs-breakpoint-gt-tablet) .link > div {
+  padding-top: layout.$spacing-05;
+}
+
+:global(.omrs-breakpoint-gt-tablet) .link > div a:nth-child(1) {
+  height: layout.$spacing-07;
+  color: $ui-04;
+  padding-left: layout.$spacing-05;
+}
+
+.link > div a:nth-child(1):hover {
+  background-color: $ui-03;
+  color: $ui-05;
+  border-left: var(--brand-01);
+}
+
+.link > div a:nth-child(1):focus {
+  background-color: $ui-03;
+  outline: none;
+  color: $ui-05;
+  border-left: var(--brand-01);
+}
+
+.productiveHeading01 {
+  @include type.type-style('heading-compact-01');
+}