@openmrs/esm-user-onboarding-app 4.0.0

package/src/root.component.tsx

@@ -0,0 +1,109 @@
+import React from 'react';
+import ReactJoyride, { ACTIONS, type CallBackProps, EVENTS, type Step } from 'react-joyride';
+import { useDefineAppContext } from '@openmrs/esm-framework';
+import { type TutorialContext } from './types';
+import CustomTooltip from './tooltip/tooltip.component';
+
+const RootComponent: React.FC = () => {
+
+  const [showTutorial, setShowTutorial] = React.useState(false);
+  const [steps, setSteps] = React.useState<Step[]>([]);
+  const [stepIndex, setStepIndex] = React.useState(0);
+
+  // Set steps with default step options
+  const updateSteps = (newSteps: Step[]) => {
+    setSteps(
+      newSteps.map((step) => ({
+        ...step,
+        disableBeacon: true,
+      })),
+    );
+  };
+
+  useDefineAppContext<TutorialContext>('tutorial-context', {
+    showTutorial,
+    steps,
+    setShowTutorial: (showTutorial: boolean) => setShowTutorial(showTutorial),
+    setSteps: updateSteps,
+  });
+
+  const onStepChange = (index: number) => {
+    const step = steps[index];
+    if (step.data && step.data.autoNextOn) {
+      handleAutoNext(step.data.autoNextOn, index);
+    }
+  }
+
+  const waitForTarget = (index: number) => {
+    setShowTutorial(false);
+    const interval = setInterval(() => {
+      const targetElement = document.querySelector(steps[index].target as string);
+      if (targetElement) {
+        setShowTutorial(true);
+        clearTimeout(interval);
+      }
+    }, 1000);
+
+  };
+
+  const handleAutoNext = (query: string, index: number) => {
+    const interval = setInterval(() => {
+      const targetElement = document.querySelector(query);
+      if (targetElement) {
+        setStepIndex(index + 1);
+        clearTimeout(interval);
+      }
+    }, 1000);
+  }
+
+const currentStep = steps[stepIndex];
+const overlayStyles = currentStep?.disableOverlay
+  ? { backgroundColor: 'transparent' }
+  : { height: document.body.scrollHeight };
+
+  const handleJoyrideCallback = (data: CallBackProps) => {
+    const {action, index, origin, status, type} = data;
+    switch (type) {
+      case EVENTS.TOUR_START:
+        // The target not found event is not triggered when the tour starts
+        waitForTarget(0);
+        break;
+      case EVENTS.STEP_BEFORE:
+        onStepChange(index);
+        break;
+      case EVENTS.STEP_AFTER:
+        setStepIndex(index + (action === ACTIONS.PREV ? -1 : 1));
+        break;
+      case EVENTS.TARGET_NOT_FOUND:
+        waitForTarget(index);
+        break;
+      case EVENTS.TOUR_END:
+        setStepIndex(0)
+        setShowTutorial(false);
+        break;
+    }
+  }
+
+  return (
+    <ReactJoyride
+      continuous
+      debug
+      disableScrolling
+      showProgress
+      showSkipButton
+      steps={steps}
+      stepIndex={stepIndex}
+      run={showTutorial}
+      callback={handleJoyrideCallback}
+      disableOverlayClose={true}
+      tooltipComponent={(props) => <CustomTooltip {...props} step={steps[props.index]} totalSteps={steps.length} />}
+      styles={{
+        options: {
+          zIndex: 10000,
+        },
+        overlay: overlayStyles,
+      }}
+    />
+  );
+};
+export default RootComponent;

package/src/routes.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://json.openmrs.org/routes.schema.json",
+  "backendDependencies": {
+    "fhir2": ">=1.2",
+    "webservices.rest": "^2.24.0"
+  },
+  "extensions": [
+    {
+      "name": "tutorials",
+      "slot": "help-menu-slot",
+      "component": "tutorial",
+      "online": true,
+      "offline": true
+    }
+  ],
+  "modals": [
+	{
+	  "name": "tutorial-modal",
+	  "component": "tutorialModal"
+	}
+  ],
+  "pages": [
+    {
+      "component": "root",
+      "route": true
+    }
+  ]
+}

package/src/setup-tests.ts

@@ -0,0 +1 @@
+import '@testing-library/jest-dom';

package/src/tooltip/tooltip.component.tsx

@@ -0,0 +1,73 @@
+import React from 'react';
+import { Button } from '@carbon/react';
+import { ArrowLeft, ArrowRight, Close } from '@carbon/react/icons';
+import { useTranslation } from 'react-i18next';
+import styles from './tooltip.scss';
+
+interface CustomTooltipProps {
+  continuous: boolean;
+  index: number;
+  step: any;
+  backProps: any;
+  skipProps: any;
+  primaryProps: any;
+  tooltipProps: any;
+  totalSteps: number;
+}
+
+const CustomTooltip: React.FC<CustomTooltipProps> = ({
+  continuous,
+  index,
+  step,
+  backProps,
+  primaryProps,
+  skipProps,
+  tooltipProps,
+  totalSteps,
+}) => {
+  const { t } = useTranslation();
+  const isLastStep = index === totalSteps - 1;
+
+  return (
+    <div {...tooltipProps} className={styles.tooltipcontainer}>
+      <div className={styles.tooltipheader}>
+        <div className={styles.container}>
+          <h4 className={styles.tooltiptitle}>{step.title}</h4>
+          <div className={styles.tooltipcontent}>{step.content}</div>
+        </div>
+        <Button {...skipProps} size="sm" kind="ghost" className={styles.closeButton}>
+          <Close />
+        </Button>
+      </div>
+      <div className={styles.tooltipfooter}>
+        <span className={styles.tooltipstep}>{`${index + 1} of ${totalSteps}`}</span>
+        <div className={styles.buttonContainer}>
+          {!step.hideBackButton && index > 0 && (
+            <Button {...backProps} size="sm" kind="ghost" className={styles.buttonback}>
+              <div className={styles.arrowLeft}>
+                <ArrowLeft />
+              </div>
+              {t('back', 'Back')}
+            </Button>
+          )}
+          {continuous && !step.hideNextButton && (
+            <Button {...primaryProps} size="sm" className={styles.buttonnext}>
+              {isLastStep ? (
+                <>{t('finish', 'Finish')}</>
+              ) : (
+                <>
+                  {t('next', 'Next')}
+                  <div className={styles.arrowContainer}>
+                    <ArrowRight />
+                  </div>
+                </>
+              )}
+            </Button>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+};
+
+export default CustomTooltip;

package/src/tooltip/tooltip.scss

@@ -0,0 +1,83 @@
+@use '@carbon/styles/scss/spacing';
+@use '@carbon/styles/scss/type';
+@import '~@openmrs/esm-styleguide/src/vars';
+
+.tooltipcontainer {
+  background-color: $ui-02;
+  padding: spacing.$spacing-05;
+  box-shadow: 0 0 10px rgba(0, 0, 0, 0.1);
+  max-width: 360px;
+  border-radius: spacing.$spacing-02;
+  gap: spacing.$spacing-04;
+
+  .tooltipheader {
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+    margin-bottom: spacing.$spacing-01;
+
+  .container {
+    display: flex;
+    flex-direction: column;
+    flex-grow: 1;
+  }
+
+  .tooltiptitle {
+    @include type.type-style('heading-02');
+    margin-bottom: spacing.$spacing-02;
+  }
+
+  .closeButton {
+    min-height: 16px;
+    padding: 0;
+    align-self: flex-start;
+  }
+}
+
+.tooltipcontent {
+    color: $color-gray-70;
+    @include type.type-style('body-compact-01');
+    width: 100%;
+    margin-top: spacing.$spacing-01;
+}
+
+
+  .tooltipfooter {
+    margin-top: spacing.$spacing-03;
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+
+  .tooltipstep {
+    color: $color-gray-70;
+    @include type.type-style('body-compact-01');
+  }
+
+  .buttonContainer {
+    display: flex;
+    gap: spacing.$spacing-03;
+
+  .buttonback,
+  .buttonnext {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    padding: spacing.$spacing-02;
+    width: spacing.$spacing-12;
+
+    .arrowLeft,
+    .arrowContainer {
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      margin-left: spacing.$spacing-02;
+    }
+
+    .arrowLeft svg {
+      fill: $color-blue-60-2 !important;
+      margin-right: spacing.$spacing-02;
+    }
+  }
+}
+}
+}

package/src/tutorial/modal.component.test.tsx

@@ -0,0 +1,98 @@
+import React from 'react';
+import {render, screen, waitFor} from '@testing-library/react';
+import TutorialModal from './modal.component';
+import {useAppContext, useConfig, navigate} from "@openmrs/esm-framework";
+import userEvent from '@testing-library/user-event'
+
+jest.mock('@openmrs/esm-framework', () => ({
+  useConfig: jest.fn(),
+  useAppContext: jest.fn(),
+  navigate: jest.fn(),
+}));
+
+const setShowTutorial = jest.fn();
+const setSteps = jest.fn();
+
+const mockUseAppContext = jest.mocked(useAppContext);
+const mockUseConfig = jest.mocked(useConfig);
+const mockNavigate = jest.mocked(navigate);
+
+const mockTutorialData = [
+  {
+    title: 'Basic Tutorial',
+    description: 'This Shows Basic Tutorials',
+    steps: [
+      { target: '[aria-label="OpenMRS"]', content: 'Welcome to OpenMRS' },
+      { target: '[aria-label="NavBar"]', content: 'This is the Navbar' },
+    ],
+  },
+  {
+    title: 'Patient Registration Tutorial',
+    description: 'This Shows how to register a patient in OpenMRS',
+    steps: [
+      {
+        target: '[aria-label="add-btn"]',
+        content: 'This is the Add Patient button',
+      },
+      {
+        target: '[aria-label="register-form"]',
+        content: 'This is the Registration form',
+      },
+      {
+        target: '[aria-label="register-btn"]',
+        content: 'This is the Register button',
+      },
+    ],
+  },
+];
+
+mockUseConfig.mockReturnValue({
+  tutorialData: mockTutorialData,
+});
+
+mockUseAppContext.mockReturnValue({
+  setShowTutorial,
+  setSteps,
+});
+
+describe('TutorialModal', () => {
+  afterEach(() => {
+    jest.clearAllMocks();
+    delete window.location;
+    window.location = { pathname: '/patient-registration' } as any;
+  });
+
+  test('sends correct data to the root component when walkthrough button is clicked', async () => {
+    const user = userEvent.setup();
+
+    (window as any).getOpenmrsSpaBase = jest.fn(() => '/spa-base/');
+    Object.defineProperty(window, 'location', {
+      value: {
+        pathname: '/patient-registration',
+      },
+    });
+
+    render(<TutorialModal open={true} onClose={jest.fn()}/>);
+
+    const walkthroughButton = screen.getAllByText('Walkthrough');
+    await user.click(walkthroughButton[0]);
+
+    expect(navigate).toHaveBeenCalledWith({ to: '/spa-base/home' });
+    Object.defineProperty(window.location, 'pathname', {
+      value: '/spa-base/home',
+    });
+
+    await waitFor(() => expect(setSteps).toHaveBeenCalledWith(mockTutorialData[0].steps));
+    await waitFor(() => expect(setShowTutorial).toHaveBeenCalledWith(true));
+  });
+
+  test('renders tutorials properly', async () => {
+    render(<TutorialModal open={true} onClose={jest.fn()} />);
+
+    mockTutorialData.forEach((tutorial) => {
+      expect(screen.getByText(tutorial.title)).toBeInTheDocument();
+      expect(screen.getByText(tutorial.description)).toBeInTheDocument();
+    });
+  });
+});
+

package/src/tutorial/modal.component.tsx

@@ -0,0 +1,66 @@
+import React from 'react';
+import { useTranslation } from 'react-i18next';
+import { useConfig, useAppContext, navigate } from '@openmrs/esm-framework';
+import styles from './styles.scss';
+import { type TutorialContext } from '../types';
+import { ModalHeader, ModalBody, Link } from '@carbon/react';
+import { ArrowRight } from '@carbon/react/icons';
+
+const TutorialModal = ({ open, onClose }) => {
+  const { t } = useTranslation();
+  const config = useConfig();
+  const tutorials = config.tutorialData;
+  const tutorialContext = useAppContext<TutorialContext>('tutorial-context');
+
+  const handleWalkthroughClick = (index: number) => {
+    const basePath = window.getOpenmrsSpaBase();
+    const homePath = `${basePath}home`;
+    const currentPath = window.location.pathname;
+    const tutorial = tutorials[index];
+
+    const setTutorialSteps = () => {
+      tutorialContext.setSteps(tutorial.steps);
+      tutorialContext.setShowTutorial(true);
+    };
+
+    if (currentPath === homePath) {
+      setTutorialSteps();
+    } else {
+      navigate({ to: homePath });
+
+      const intervalId = setInterval(() => {
+        if (window.location.pathname === homePath) {
+          setTutorialSteps();
+          clearInterval(intervalId);
+        }
+      }, 100);
+    }
+    onClose();
+  };
+
+  return (
+    <React.Fragment>
+      <ModalHeader closeModal={onClose} title={t('tutorial', 'Tutorial')} className={styles.modalHeader}>
+        <p className={styles.description}>
+          {t('modalDescription', 'Find walkthroughs and video tutorials on some of the core features of OpenMRS.')}
+        </p>
+      </ModalHeader>
+      <ModalBody className={styles.tutorialModal}>
+        <ul>
+          {tutorials.map((tutorial, index) => (
+            <li className={styles.tutorialItem} key={index}>
+              <h3 className={styles.tutorialTitle}>{tutorial.title}</h3>
+              <p className={styles.tutorialDescription}>{tutorial.description}</p>
+              <Link onClick={() => handleWalkthroughClick(index)} className={styles.tutorialLink} renderIcon={() => 
+                <ArrowRight aria-label="Arrow Right" />}>
+                {t('walkthrough', 'Walkthrough')}
+              </Link>
+            </li>
+          ))}
+        </ul>
+      </ModalBody>
+    </React.Fragment>
+  );
+};
+
+export default TutorialModal;

package/src/tutorial/styles.scss

@@ -0,0 +1,64 @@
+@use '@carbon/styles/scss/spacing';
+@use '@carbon/styles/scss/type';
+@use '@carbon/layout';
+@import '~@openmrs/esm-styleguide/src/vars';
+
+.description {
+  margin-bottom: spacing.$spacing-04;
+  @include type.type-style('body-compact-01');
+}
+
+.tutorialModal {
+  display: flex;
+  flex-direction: column;
+  gap: spacing.$spacing-04;
+
+  .tutorialItem {
+    border-bottom: 1px solid $ui-03;
+    padding-bottom: spacing.$spacing-02;
+
+    .tutorialTitle {
+      margin-bottom: spacing.$spacing-04;
+      @include type.type-style('heading-02');
+    }
+
+    .tutorialDescription {
+      color: $color-gray-70;
+      @include type.type-style('body-compact-01');
+    }
+
+    .tutorialLink {
+      margin-bottom: spacing.$spacing-04;
+      margin-top: spacing.$spacing-04;
+      cursor: pointer;
+    }
+  }
+}
+
+.modalHeader {
+  :global {
+    .cds--modal-close-button {
+      position: absolute;
+      inset-block-start: 0;
+      inset-inline-end: 0;
+      margin: 0;
+      margin-top: calc(-1 * #{layout.$spacing-05});
+    }
+
+    .cds--modal-close {
+      background-color: rgba(0, 0, 0, 0);
+
+      &:hover {
+        background-color: var(--cds-layer-hover);
+      }
+    }
+
+    .cds--popover--left > .cds--popover > .cds--popover-content {
+      transform: translate(-4rem, 0.85rem);
+    }
+
+    .cds--popover--left > .cds--popover > .cds--popover-caret {
+      transform: translate(-3.75rem, 1.25rem);
+    }
+  }
+}

package/src/tutorial/tutorial.tsx

@@ -0,0 +1,22 @@
+import React from 'react';
+import { useTranslation } from 'react-i18next';
+import { showModal } from '@openmrs/esm-framework';
+
+const Tutorial = () => {
+  const { t } = useTranslation();
+
+  const handleOpenModal = () => {
+    const dispose = showModal('tutorial-modal', {
+      onClose: () => dispose(),
+      size: 'sm',
+    });
+  };
+
+  return (
+    <>
+      <div onClick={handleOpenModal}>{t('tutorials', 'Tutorials')}</div>
+    </>
+  );
+};
+
+export default Tutorial;

package/src/types.ts

@@ -0,0 +1,15 @@
+import {type Step} from "react-joyride";
+
+export interface Tutorial {
+  title: string;
+  description: string;
+  steps: Step[];
+}
+
+export interface TutorialContext {
+  showTutorial: boolean;
+  steps: Step[];
+  setShowTutorial: (showTutorial: boolean) => void;
+  setSteps: (steps: Step[]) => void;
+}
+

package/translations/am.json

@@ -0,0 +1 @@
+{}

package/translations/en.json

@@ -0,0 +1,9 @@
+{
+  "back": "Back",
+  "finish": "Finish",
+  "modalDescription": "Find walkthroughs and video tutorials on some of the core features of OpenMRS.",
+  "next": "Next",
+  "tutorial": "Tutorials",
+  "walkthrough": "Walkthrough",
+  "welcome": "Welcome to OpenMRS!"
+}

package/translations/es.json

@@ -0,0 +1 @@
+{}

package/translations/fr.json

@@ -0,0 +1 @@
+{}

package/translations/he.json

@@ -0,0 +1 @@
+{}

package/translations/km.json

@@ -0,0 +1 @@
+{}

package/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "esModuleInterop": true,
+    "module": "esnext",
+    "allowSyntheticDefaultImports": true,
+    "jsx": "react",
+    "skipLibCheck": true,
+    "moduleResolution": "node",
+    "lib": [
+      "dom",
+      "es5",
+      "scripthost",
+      "es2015",
+      "es2015.promise",
+      "es2016.array.include",
+      "es2018",
+      "es2020"
+    ],
+    "resolveJsonModule": true,
+    "noEmit": true,
+    "target": "esnext"
+  }
+}

package/webpack.config.js

@@ -0,0 +1 @@
+module.exports = require('openmrs/default-webpack-config');