@digihmis/esm-primary-navigation-app 1.0.0

package/src/components/change-language/change-language.modal.tsx

@@ -0,0 +1,115 @@
+import classNames from 'classnames';
+import React, { useCallback, useMemo, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+import { capitalize } from 'lodash-es';
+import {
+  Button,
+  Checkbox,
+  InlineLoading,
+  ModalBody,
+  ModalFooter,
+  ModalHeader,
+  RadioButton,
+  RadioButtonGroup,
+} from '@carbon/react';
+import { useAbortController, useSession } from '@openmrs/esm-framework';
+import { updateSessionLocale, updateUserProperties } from './change-language.resource';
+import styles from './change-language.scss';
+
+interface ChangeLanguageModalProps {
+  close(): void;
+}
+
+export default function ChangeLanguageModal({ close }: ChangeLanguageModalProps) {
+  const { t } = useTranslation();
+  const session = useSession();
+  const user = session?.user;
+  const allowedLocales = session?.allowedLocales ?? [];
+  const [selectedLocale, setSelectedLocale] = useState(session?.locale);
+  const [shouldChangeDefaultLocale, setShouldChangeDefaultLocale] = useState(true);
+  const [isChangingLanguage, setIsChangingLanguage] = useState(false);
+  const ac = useAbortController();
+
+  const handleSubmit = useCallback(() => {
+    setIsChangingLanguage(true);
+
+    if (selectedLocale && selectedLocale !== session?.locale) {
+      const formattedLocale = selectedLocale.replace(/-/gi, '_');
+      if (shouldChangeDefaultLocale) {
+        updateUserProperties(
+          user.uuid,
+          {
+            ...(user.userProperties ?? {}),
+            defaultLocale: formattedLocale,
+          },
+          ac,
+        );
+      } else {
+        updateSessionLocale(formattedLocale, ac);
+      }
+    }
+  }, [user.userProperties, user.uuid, selectedLocale, shouldChangeDefaultLocale]);
+
+  const languageNames = useMemo(
+    () =>
+      Object.fromEntries(
+        allowedLocales.map((locale) => [locale, new Intl.DisplayNames([locale], { type: 'language' }).of(locale)]),
+      ),
+    [allowedLocales],
+  );
+
+  return (
+    <>
+      <ModalHeader closeModal={close} title={t('changeLanguage', 'Change language')} />
+      <ModalBody>
+        <div className={styles.languageOptionsContainer}>
+          <RadioButtonGroup
+            valueSelected={selectedLocale}
+            orientation="vertical"
+            name="Language options"
+            onChange={(locale) => setSelectedLocale(locale.toString())}
+          >
+            {allowedLocales.map((locale, i) => (
+              <RadioButton
+                className={styles.languageRadioButton}
+                key={`locale-option-${locale}-${i}`}
+                id={`locale-option-${locale}-${i}`}
+                name={locale}
+                labelText={capitalize(languageNames[locale])}
+                value={locale}
+              />
+            ))}
+          </RadioButtonGroup>
+        </div>
+      </ModalBody>
+      <div className={classNames('cds--layer-two', styles.updateDefaultLocaleContainer)} role="region">
+        <Checkbox
+          id={`change-default-locale`}
+          labelText={t('changeDefaultLocale', 'Save as my default language')}
+          checked={shouldChangeDefaultLocale}
+          onChange={(_, { checked }) => setShouldChangeDefaultLocale(checked)}
+        />
+        <p className={classNames(styles.updateDefaultLocaleExplainer)}>
+          {t('changeDefaultLocaleExplanation', 'Leave this unchecked to change language for this session only')}
+        </p>
+      </div>
+      <ModalFooter>
+        <Button kind="secondary" onClick={close}>
+          {t('cancel', 'Cancel')}
+        </Button>
+        <Button
+          className={styles.submitButton}
+          disabled={isChangingLanguage || selectedLocale === session?.locale}
+          type="submit"
+          onClick={handleSubmit}
+        >
+          {isChangingLanguage ? (
+            <InlineLoading description={t('changingLanguage', 'Changing language') + '...'} />
+          ) : (
+            <span>{t('change', 'Change')}</span>
+          )}
+        </Button>
+      </ModalFooter>
+    </>
+  );
+}

package/src/components/change-language/change-language.resource.ts

@@ -0,0 +1,35 @@
+import { openmrsFetch, restBaseUrl } from '@openmrs/esm-framework/src/internal';
+
+export type PostUserProperties = (
+  userUuid: string,
+  userProperties: Record<string, string>,
+  abortController?: AbortController,
+) => Promise<void>;
+
+export async function updateUserProperties(
+  userUuid: string,
+  userProperties: Record<string, string>,
+  abortController?: AbortController,
+): Promise<void> {
+  await openmrsFetch(`${restBaseUrl}/user/${userUuid}`, {
+    method: 'POST',
+    body: { userProperties },
+    headers: { 'Content-Type': 'application/json' },
+    signal: abortController?.signal,
+  });
+
+  // Force the reload of the page to ensure all data coming from the backend is fetched in the newly set locale.
+  window.location.reload();
+}
+
+export async function updateSessionLocale(locale: string, abortController?: AbortController): Promise<void> {
+  await openmrsFetch(`${restBaseUrl}/session`, {
+    method: 'POST',
+    body: { locale },
+    headers: { 'Content-Type': 'application/json' },
+    signal: abortController?.signal,
+  });
+
+  // Force the reload of the page to ensure all data coming from the backend is fetched in the newly set locale.
+  window.location.reload();
+}

package/src/components/change-language/change-language.scss

@@ -0,0 +1,59 @@
+@use '@carbon/layout';
+@use '@carbon/type';
+@use '@openmrs/esm-styleguide/src/vars' as *;
+
+.primaryNavContainer {
+  height: var(--omrs-topnav-height);
+}
+
+.languageOptionsContainer {
+  display: flex;
+  flex-direction: column;
+  padding-bottom: layout.$spacing-05;
+  max-height: 28rem;
+  overflow-y: auto;
+  overflow-x: hidden;
+  padding-right: layout.$spacing-03; /* Prevent scrollbar overlap */
+
+  &::-webkit-scrollbar {
+    width: 8px;
+  }
+
+  &::-webkit-scrollbar-track {
+    background: transparent;
+  }
+
+  &::-webkit-scrollbar-thumb {
+    background: #888;
+    border-radius: 4px;
+  }
+}
+
+.languageRadioButton {
+  display: flex;
+  height: layout.$spacing-09;
+  align-items: center;
+  @include type.type-style('body-compact-01');
+}
+
+.updateDefaultLocaleContainer {
+  padding-top: layout.$spacing-03;
+  padding-left: layout.$spacing-05;
+  padding-right: layout.$spacing-05;
+  padding-bottom: layout.$spacing-06;
+}
+
+.updateDefaultLocaleExplainer {
+  @include type.type-style('body-compact-01');
+  color: $text-02;
+}
+
+.submitButton {
+  :global(.cds--inline-loading) {
+    min-height: layout.$spacing-05 !important;
+  }
+
+  :global(.cds--inline-loading__text) {
+    font-size: unset !important;
+  }
+}

package/src/components/change-language/change-language.test.tsx

@@ -0,0 +1,107 @@
+import React from 'react';
+import userEvent from '@testing-library/user-event';
+import { render, screen } from '@testing-library/react';
+import { type LoggedInUser, type Session, useSession } from '@openmrs/esm-framework';
+import ChangeLanguageModal from './change-language.modal';
+
+const mockUser = {
+  uuid: 'uuid',
+  userProperties: {
+    defaultLocale: 'fr',
+  },
+};
+
+const mockUpdateUserProperties = jest.fn((...args) => Promise.resolve());
+const mockUpdateSessionLocale = jest.fn((...args) => Promise.resolve());
+const mockUseSession = jest.mocked(useSession);
+
+jest.mock('./change-language.resource', () => ({
+  updateUserProperties: (...args) => mockUpdateUserProperties(...args),
+  updateSessionLocale: (...args) => mockUpdateSessionLocale(...args),
+}));
+
+describe(`Change Language Modal`, () => {
+  beforeEach(() => {
+    mockUseSession.mockReturnValue({
+      authenticated: true,
+      user: mockUser as unknown as LoggedInUser,
+      allowedLocales: ['en', 'fr', 'it', 'pt'],
+      locale: 'fr',
+    } as Session);
+  });
+
+  it('should correctly displays all allowed locales', () => {
+    render(<ChangeLanguageModal close={jest.fn()} />);
+
+    expect(screen.getByRole('radio', { name: /english/i })).toBeInTheDocument();
+    expect(screen.getByRole('radio', { name: /français/i })).toBeInTheDocument();
+    expect(screen.getByRole('radio', { name: /italiano/i })).toBeInTheDocument();
+    expect(screen.getByRole('radio', { name: /português/i })).toBeInTheDocument();
+  });
+
+  it('should close the modal when the cancel button is clicked', async () => {
+    const user = userEvent.setup();
+    const mockClose = jest.fn();
+
+    render(<ChangeLanguageModal close={mockClose} />);
+
+    await user.click(screen.getByRole('button', { name: /cancel/i }));
+    expect(mockClose).toHaveBeenCalled();
+  });
+
+  it('should change user locale when the submit button is clicked', async () => {
+    const user = userEvent.setup();
+
+    render(<ChangeLanguageModal close={jest.fn()} />);
+
+    expect(screen.getByRole('radio', { name: /français/i })).toBeChecked();
+
+    await user.click(screen.getByRole('radio', { name: /english/i }));
+    await user.click(screen.getByRole('button', { name: /change/i }));
+
+    expect(mockUpdateUserProperties).toHaveBeenCalledWith(mockUser.uuid, { defaultLocale: 'en' }, expect.anything());
+  });
+
+  it('should show a loading indicator in the submit button while language change is in progress', async () => {
+    const user = userEvent.setup();
+    mockUpdateUserProperties.mockImplementation(() => new Promise(() => {}));
+
+    render(<ChangeLanguageModal close={jest.fn()} />);
+
+    await user.click(screen.getByRole('radio', { name: /english/i }));
+    await user.click(screen.getByRole('button', { name: /change/i }));
+
+    expect(screen.getByText(/changing language.../i)).toBeInTheDocument();
+  });
+
+  it('should display the "Save as my default language" checkbox checked by default', () => {
+    render(<ChangeLanguageModal close={jest.fn()} />);
+
+    const checkbox = screen.getByRole('checkbox', { name: /Save as my default language/i });
+    expect(checkbox).toBeChecked();
+  });
+
+  it('should call updateSessionLocale when checkbox is unchecked and user changes locale', async () => {
+    const user = userEvent.setup();
+
+    render(<ChangeLanguageModal close={jest.fn()} />);
+
+    // Uncheck the checkbox to only update session locale
+    const checkbox = screen.getByRole('checkbox', { name: /Save as my default language/i });
+    await user.click(checkbox);
+
+    // Change locale
+    await user.click(screen.getByRole('radio', { name: /english/i }));
+    await user.click(screen.getByRole('button', { name: /change/i }));
+
+    expect(mockUpdateSessionLocale).toHaveBeenCalledWith('en', expect.anything());
+    expect(mockUpdateUserProperties).not.toHaveBeenCalled();
+  });
+
+  it('should disable submit button when selected locale is same as current locale', () => {
+    render(<ChangeLanguageModal close={jest.fn()} />);
+
+    const submitButton = screen.getByRole('button', { name: /change/i });
+    expect(submitButton).toBeDisabled();
+  });
+});

package/src/components/dashboard/dashboard.component.tsx

@@ -0,0 +1,104 @@
+import React, { useContext, useMemo } from 'react';
+import { BrowserRouter } from 'react-router-dom';
+import { useTranslation } from 'react-i18next';
+import { InlineNotification } from '@carbon/react';
+import {
+  ComponentContext,
+  DashboardExtension,
+  getCoreTranslation,
+  useConfig,
+  openmrsComponentDecorator,
+  type OpenmrsReactComponentProps,
+  Type,
+} from '@openmrs/esm-framework/src/internal';
+
+export const dashboardConfigSchema = {
+  title: {
+    _description: 'The display string for this dashboard',
+    _default: 'My Dashboard',
+    _type: Type.String,
+  },
+  path: {
+    _description: 'The URL fragment this link points to',
+    _default: '',
+    _type: Type.String,
+  },
+  icon: {
+    _description: 'The icons for the navigation menu',
+    _default: '',
+    _type: Type.String,
+  },
+  moduleName: {
+    _description: 'The module which the extension should be loaded into',
+    _default: '',
+    _type: Type.String,
+  },
+};
+
+export interface DashboardConfig {
+  path: string;
+  title: string;
+  icon: string;
+  moduleName: string;
+}
+
+interface DashboardProps {
+  basePath: string;
+  moduleName?: string;
+}
+
+export default function Dashboard({ basePath, moduleName }: DashboardProps) {
+  const componentContext = useContext(ComponentContext);
+  const module = moduleName ?? componentContext.extension?.extensionSlotModuleName ?? componentContext.moduleName;
+
+  const Component = useMemo(
+    () =>
+      openmrsComponentDecorator<OpenmrsReactComponentProps>({
+        moduleName: module,
+        featureName: 'dashboard',
+      })(() => <DashboardInternal basePath={basePath} />),
+    [basePath, module],
+  );
+
+  return (
+    <BrowserRouter>
+      <Component
+        _extensionContext={{
+          extensionId: componentContext.extension?.extensionId,
+          extensionSlotName: componentContext.extension?.extensionSlotName,
+          extensionSlotModuleName: module,
+        }}
+      />
+    </BrowserRouter>
+  );
+}
+
+// t('noPathInDashboardExtension', 'Cannot render the dashboard extension without the property "path" being set in the configuration schema')
+function DashboardInternal({ basePath }: { basePath: string }) {
+  const { t } = useTranslation('@openmrs/esm-primary-navigation-app');
+  const config = useConfig<DashboardConfig>();
+
+  if (!config.path) {
+    return (
+      <InlineNotification
+        kind="error"
+        subtitle={t(
+          'noPathInDashboardExtension',
+          `Cannot render the dashboard extension without the property "path" being set in the configuration schema`,
+        )}
+        title={getCoreTranslation('error')}
+      />
+    );
+  }
+
+  // config.icon is a free-form string from the config schema; DashboardExtension types
+  // it as a fixed icon-id union, so narrow it to the prop's expected type.
+  return (
+    <DashboardExtension
+      path={config.path}
+      title={config.title}
+      basePath={basePath}
+      icon={config.icon as React.ComponentProps<typeof DashboardExtension>['icon']}
+    />
+  );
+}

package/src/components/generic-link/generic-link.component.tsx

@@ -0,0 +1,25 @@
+import React from 'react';
+import { ConfigurableLink, Type, useConfig, validators } from '@openmrs/esm-framework';
+
+export const genericLinkConfigSchema = {
+  title: {
+    _default: 'New Link',
+    _type: Type.String,
+  },
+  target: {
+    _default: '#',
+    _type: Type.String,
+    _description: 'The URL to link to.',
+    _validators: [validators.isUrl],
+  },
+};
+
+export interface GenericLinkConfig {
+  title: string;
+  target: string;
+}
+
+export default function GenericLink() {
+  const config = useConfig<GenericLinkConfig>();
+  return <ConfigurableLink to={config.target}>{config.title}</ConfigurableLink>;
+}

package/src/components/logo/logo.component.tsx

@@ -0,0 +1,28 @@
+import React from 'react';
+import { interpolateUrl, useConfig } from '@openmrs/esm-framework';
+import { type ConfigSchema } from '../../config-schema';
+import styles from './logo.scss';
+
+const Logo: React.FC = () => {
+  const { logo } = useConfig<ConfigSchema>();
+
+  const handleImageError = (e: React.SyntheticEvent<HTMLImageElement>) => {
+    console.error('Failed to load logo image:', e);
+  };
+
+  return (
+    <>
+      {logo?.src ? (
+        <img alt={logo.alt} className={styles.logo} onError={handleImageError} src={interpolateUrl(logo.src)} />
+      ) : logo?.name ? (
+        logo.name
+      ) : (
+        <svg aria-label="OpenMRS Logo" role="img" width={110} height={40}>
+          <use href="#omrs-logo-white" />
+        </svg>
+      )}
+    </>
+  );
+};
+
+export default Logo;

package/src/components/logo/logo.scss

@@ -0,0 +1,11 @@
+.logo {
+  display: flex;
+  align-items: center;
+  width: auto;
+  max-width: 300px;
+  height: 40px;
+  overflow: hidden;
+  position: relative;
+  object-fit: cover;
+  object-position: left;
+}

package/src/components/logo/logo.test.tsx

@@ -0,0 +1,79 @@
+import React from 'react';
+import userEvent from '@testing-library/user-event';
+import { render, screen } from '@testing-library/react';
+import { useConfig } from '@openmrs/esm-framework';
+import { type ConfigSchema } from '../../config-schema';
+import Logo from './logo.component';
+
+// FIXME: Figure out why I can't annotate this mock like so: jest.mocked(useConfig<ConfigSchema>);
+const mockUseConfig = jest.mocked(useConfig);
+
+describe('Logo', () => {
+  it('should display the OpenMRS logo by default', () => {
+    const mockConfig = { logo: { src: null, alt: null, name: null } };
+    mockUseConfig.mockReturnValue(mockConfig as ConfigSchema);
+
+    render(<Logo />);
+
+    const logo = screen.getByRole('img');
+
+    expect(logo).toBeInTheDocument();
+    expect(logo).toContainHTML('svg');
+  });
+
+  it('should display name', () => {
+    const mockConfig = {
+      logo: { src: null, alt: null, name: 'Some weird EMR', link: null },
+      externalRefLinks: null,
+    };
+
+    mockUseConfig.mockReturnValue(mockConfig as ConfigSchema);
+
+    render(<Logo />);
+
+    expect(screen.getByText(/Some weird EMR/i)).toBeInTheDocument();
+  });
+
+  it('should display image logo', () => {
+    const mockConfig = {
+      logo: {
+        src: 'https://someimage.png',
+        alt: 'alternative text',
+        name: null,
+      },
+    };
+
+    mockUseConfig.mockReturnValue(mockConfig);
+
+    render(<Logo />);
+
+    const logo = screen.getByRole('img');
+
+    expect(logo).toBeInTheDocument();
+    expect(logo).toHaveAttribute('alt');
+  });
+
+  it('should handle image load errors', () => {
+    const user = userEvent.setup();
+    const consoleSpy = jest.spyOn(console, 'error').mockImplementation();
+    const mockConfig = {
+      logo: {
+        src: 'invalid-image.png',
+        alt: 'alt text',
+        name: null,
+      },
+    };
+
+    mockUseConfig.mockReturnValue(mockConfig);
+
+    render(<Logo />);
+
+    const img = screen.getByRole('img');
+
+    const errorEvent = new Event('error');
+    img.dispatchEvent(errorEvent);
+
+    expect(consoleSpy).toHaveBeenCalledWith('Failed to load logo image:', expect.any(Object));
+    consoleSpy.mockRestore();
+  });
+});

package/src/components/nav-group/nav-group.component.tsx

@@ -0,0 +1,52 @@
+import React, { useContext } from 'react';
+import { useTranslation } from 'react-i18next';
+import { Accordion, AccordionItem } from '@carbon/react';
+import { ComponentContext, ExtensionSlot, useConfig, Type } from '@openmrs/esm-framework/src/internal';
+
+export const navGroupFeatureName = 'Nav Group';
+
+export const navGroupConfigSchema = {
+  title: {
+    _type: Type.String,
+    _description: 'The title of the nav group.',
+    _default: 'My Group',
+  },
+  slotName: {
+    _type: Type.String,
+    _description: 'The name of the slot to create, which links can be added to.',
+    _default: '',
+  },
+  isExpanded: {
+    _type: Type.Boolean,
+    _description: 'The boolean to determine whether the nav group is expanded or not.',
+    _default: false,
+  },
+};
+
+export interface NavGroupConfig {
+  title: string;
+  slotName: string;
+  isExpanded?: boolean;
+}
+
+interface NavGroupProps {
+  basePath?: string;
+}
+
+export function NavGroup({ basePath }: NavGroupProps) {
+  const componentContext = useContext(ComponentContext);
+
+  const { t } = useTranslation();
+  const { title, isExpanded, slotName } = useConfig<NavGroupConfig>();
+
+  return (
+    <Accordion>
+      <AccordionItem open={isExpanded} title={t(title)}>
+        <ExtensionSlot
+          name={slotName ?? `nav-group-${title}`}
+          state={{ basePath, moduleName: componentContext.extension?.extensionSlotModuleName }}
+        />
+      </AccordionItem>
+    </Accordion>
+  );
+}

package/src/components/navbar/app-menu-button.component.tsx

@@ -0,0 +1,43 @@
+import { HeaderGlobalAction } from '@carbon/react';
+import { CloseIcon, SwitcherIcon, useAssignedExtensions, useOnClickOutside } from '@openmrs/esm-framework';
+import classNames from 'classnames';
+import React, { useMemo } from 'react';
+import { useTranslation } from 'react-i18next';
+import AppMenuPanel from '../navbar-header-panels/app-menu-panel.component';
+import styles from './navbar.scss';
+import { type MenuButtonProps } from './types';
+
+/**
+ * This component displays the app menu button and the menu itself (when toggled on)
+ */
+const AppMenuButton: React.FC<MenuButtonProps> = ({ isActivePanel, togglePanel, hidePanel }) => {
+  const appMenuItems = useAssignedExtensions('app-menu-slot');
+  const showAppMenu = useMemo(() => appMenuItems.length > 0, [appMenuItems.length]);
+  const { t } = useTranslation();
+  const appMenuRef = useOnClickOutside<HTMLDivElement>(hidePanel('appMenu'), isActivePanel('appMenu'));
+
+  return (
+    showAppMenu && (
+      <div ref={appMenuRef} className={styles.panelWrapper}>
+        <HeaderGlobalAction
+          aria-label={t('AppMenuTooltip', 'App Menu')}
+          aria-labelledby="App Menu"
+          className={classNames({
+            [styles.headerGlobalBarButton]: isActivePanel('appMenu'),
+            [styles.activePanel]: !isActivePanel('appMenu'),
+          })}
+          isActive={isActivePanel('appMenu')}
+          onClick={() => {
+            togglePanel('appMenu');
+          }}
+          tooltipAlignment="end"
+        >
+          {isActivePanel('appMenu') ? <CloseIcon size={20} /> : <SwitcherIcon size={20} />}
+        </HeaderGlobalAction>
+        <AppMenuPanel expanded={isActivePanel('appMenu')} hidePanel={hidePanel('appMenu')} />
+      </div>
+    )
+  );
+};
+
+export default AppMenuButton;