@koech/esm-core 8.0.0

package/packages/framework/esm-styleguide/src/responsive-wrapper/responsive-wrapper.component.tsx

@@ -0,0 +1,24 @@
+/** @module @category UI */
+import React from 'react';
+import { Layer } from '@carbon/react';
+import { useLayoutType } from '@openmrs/esm-react-utils';
+
+export interface ResponsiveWrapperProps {
+  children: React.ReactNode;
+}
+
+/**
+ * ResponsiveWrapper enables a responsive behavior for the component its wraps, providing a different rendering based on the current layout type.
+ * On desktop, it renders the children as is, while on a tablet, it wraps them in a Carbon Layer https://react.carbondesignsystem.com/?path=/docs/components-layer--overview component.
+ * This provides a light background for form inputs on tablets, in accordance with the design requirements.
+ */
+export const ResponsiveWrapper: React.FC<ResponsiveWrapperProps> = ({ children }) => {
+  const layout = useLayoutType();
+  const isTablet = layout === 'tablet';
+
+  if (isTablet) {
+    return <Layer>{children}</Layer>;
+  }
+
+  return <>{children}</>;
+};

package/packages/framework/esm-styleguide/src/snackbars/_snackbars.scss

@@ -0,0 +1,31 @@
+@use '@carbon/layout';
+
+.omrs-snackbars-container {
+  z-index: 9001;
+  position: fixed;
+  width: 20rem;
+  bottom: layout.$spacing-05;
+  left: layout.$spacing-05;
+  gap: layout.$spacing-03;
+  display: flex;
+  flex-direction: column;
+  align-items: flex-start;
+  justify-content: center;
+}
+
+/* Tablet */
+.omrs-breakpoint-lt-desktop {
+  .omrs-snackbars-container {
+    bottom: 5.5rem;
+  }
+}
+
+.omrs-snackbar-mounting,
+.omrs-snackbar-mounting > * {
+  padding: 0;
+}
+
+.omrs-snackbar-closing,
+.omrs-snackbar-mounting {
+  opacity: 0;
+}

package/packages/framework/esm-styleguide/src/snackbars/active-snackbar.component.tsx

@@ -0,0 +1,45 @@
+/** @module @category UI */
+import React, { useEffect, useState, useCallback } from 'react';
+import type { Subject } from 'rxjs';
+import type { SnackbarMeta } from './snackbar.component';
+import { Snackbar } from './snackbar.component';
+
+interface ActiveSnackbarProps {
+  subject: Subject<SnackbarMeta>;
+}
+
+const ActiveSnackbars: React.FC<ActiveSnackbarProps> = ({ subject }) => {
+  const [snackbars, setSnackbars] = useState<Array<SnackbarMeta>>([]);
+
+  const closeSnackbar = useCallback((snackbar) => {
+    setSnackbars((snackbars) => snackbars.filter((t) => t !== snackbar));
+  }, []);
+
+  useEffect(() => {
+    const subscription = subject.subscribe((snackbar) =>
+      setSnackbars((snackbars) => [
+        ...snackbars.filter(
+          (n) =>
+            n.subtitle !== snackbar.subtitle ||
+            n.actionButtonLabel !== snackbar.actionButtonLabel ||
+            n.onActionButtonClick !== snackbar.onActionButtonClick ||
+            n.kind !== snackbar.kind ||
+            n.title !== snackbar.title,
+        ),
+        snackbar,
+      ]),
+    );
+
+    return () => subscription.unsubscribe();
+  }, [subject]);
+
+  return (
+    <>
+      {snackbars.map((snackbar) => (
+        <Snackbar key={snackbar.id} snackbar={snackbar} closeSnackbar={() => closeSnackbar(snackbar)} />
+      ))}
+    </>
+  );
+};
+
+export default ActiveSnackbars;

package/packages/framework/esm-styleguide/src/snackbars/index.tsx

@@ -0,0 +1,45 @@
+/** @module @category UI */
+import React from 'react';
+import { createRoot } from 'react-dom/client';
+import { Subject } from 'rxjs';
+
+import type { SnackbarDescriptor, SnackbarMeta } from './snackbar.component';
+import ActiveSnackbars from './active-snackbar.component';
+
+export { type SnackbarDescriptor, type SnackbarType, type SnackbarMeta } from './snackbar.component';
+
+const snackbarsSubject = new Subject<SnackbarMeta>();
+let snackbarId = 0;
+
+/**
+ * Starts a rendering host for snack bar notifications. Should only be used by the app shell.
+ * Under normal conditions there is no need to use this function.
+ * @param target The container target that hosts the snack bar notifications.
+ */
+export function renderSnackbars(target: HTMLElement | null) {
+  if (target) {
+    const root = createRoot(target);
+    root.render(<ActiveSnackbars subject={snackbarsSubject} />);
+  }
+}
+
+function isNotEmpty(title: string) {
+  return typeof title === 'string' ? title.trim().length > 0 : false;
+}
+
+/**
+ * Displays a snack bar notification in the UI.
+ * @param snackbar The description of the snack bar to display.
+ */
+export function showSnackbar(snackbar: SnackbarDescriptor) {
+  if (snackbar && isNotEmpty(snackbar.title)) {
+    setTimeout(() => {
+      snackbarsSubject.next({
+        ...snackbar,
+        id: snackbarId++,
+      });
+    }, 0);
+  } else {
+    console.error(`showSnackbar must be called with an object having a 'title' property that is a non-empty string`);
+  }
+}

package/packages/framework/esm-styleguide/src/snackbars/snackbar.component.tsx

@@ -0,0 +1,104 @@
+/** @module @category UI */
+import React, { useCallback, useState, useEffect } from 'react';
+import classnames from 'classnames';
+import { ActionableNotification } from '@carbon/react';
+import { getCoreTranslation } from '@openmrs/esm-translations';
+import styles from './snackbar.module.scss';
+
+// Design documentation for Snackbars https://zeroheight.com/23a080e38/p/683580-notifications/t/468baf
+export interface SnackbarProps {
+  snackbar: SnackbarMeta;
+  closeSnackbar(): void;
+}
+
+export interface SnackbarDescriptor {
+  actionButtonLabel?: string;
+  isLowContrast?: boolean;
+  kind?: SnackbarType | string;
+  onActionButtonClick?: () => void;
+  progressActionLabel?: string;
+  subtitle?: React.ReactNode;
+  timeoutInMs?: number;
+  autoClose?: boolean;
+  title: string;
+}
+
+export interface SnackbarMeta extends SnackbarDescriptor {
+  id: number;
+}
+
+export type SnackbarType = 'error' | 'info' | 'info-square' | 'success' | 'warning' | 'warning-alt';
+
+export const Snackbar: React.FC<SnackbarProps> = ({ snackbar, closeSnackbar: removeSnackBarFromDom }) => {
+  const {
+    actionButtonLabel = '',
+    kind = 'success',
+    onActionButtonClick = () => {},
+    isLowContrast = kind !== 'error',
+    progressActionLabel,
+    subtitle = '',
+    timeoutInMs = 5000,
+    autoClose = kind !== 'error',
+    title,
+    id,
+    ...props
+  } = snackbar;
+
+  const [actionText, setActionText] = useState(actionButtonLabel);
+  const [applyAnimation, setApplyAnimation] = useState(true);
+  const [isClosing, setIsClosing] = useState(false);
+
+  const closeSnackbar = useCallback(() => {
+    // This is to add a slide out animation before closing the snackbar
+    // The animation lasts for 250ms, thus the timeout
+    setTimeout(removeSnackBarFromDom, 250);
+  }, [removeSnackBarFromDom]);
+
+  const onCloseSnackbar = useCallback(() => {
+    setIsClosing(true);
+    closeSnackbar();
+  }, [closeSnackbar]);
+
+  const handleActionClick = () => {
+    onActionButtonClick();
+    onCloseSnackbar();
+    if (progressActionLabel) {
+      setActionText(progressActionLabel);
+    }
+  };
+
+  useEffect(() => {
+    if (autoClose) {
+      const timeoutId = setTimeout(onCloseSnackbar, timeoutInMs);
+      return () => clearTimeout(timeoutId);
+    }
+  }, [timeoutInMs, autoClose, onCloseSnackbar]);
+
+  useEffect(() => {
+    setApplyAnimation(false);
+
+    window.setTimeout(() => {
+      setApplyAnimation(true);
+    }, 0);
+  }, []);
+
+  return (
+    <ActionableNotification
+      actionButtonLabel={actionText}
+      aria-label={getCoreTranslation('closeSnackbar', 'Close snackbar')}
+      className={classnames(styles.slideIn, {
+        [styles.animated]: applyAnimation,
+        [styles.slideOut]: isClosing,
+      })}
+      inline
+      kind={kind as SnackbarType}
+      lowContrast={isLowContrast}
+      onActionButtonClick={handleActionClick}
+      onClose={closeSnackbar}
+      statusIconDescription={getCoreTranslation('snackbarNotification', 'Snackbar notification')}
+      subtitle={subtitle}
+      title={title}
+      {...props}
+    />
+  );
+};

package/packages/framework/esm-styleguide/src/snackbars/snackbar.module.scss

@@ -0,0 +1,30 @@
+@keyframes slideInFromLeft {
+  0% {
+    transform: translateX(-100%);
+  }
+  100% {
+    transform: translateX(0);
+  }
+}
+
+@keyframes slideOutToLeft {
+  0% {
+    transform: translateX(0);
+  }
+  100% {
+    transform: translateX(-100%);
+  }
+}
+
+.animated {
+  animation-duration: 250ms;
+  animation-timing-function: ease-in-out;
+}
+
+.slideIn {
+  animation-name: slideInFromLeft;
+}
+
+.slideOut {
+  animation-name: slideOutToLeft;
+}

package/packages/framework/esm-styleguide/src/snackbars/snackbar.test.tsx

@@ -0,0 +1,89 @@
+import React from 'react';
+import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from 'vitest';
+import '@testing-library/jest-dom/vitest';
+import { act, render, screen, waitFor } from '@testing-library/react';
+import { Snackbar } from './snackbar.component';
+
+const mockCloseSnackbar = vi.fn();
+
+describe('Snackbar component', () => {
+  beforeAll(() => vi.useFakeTimers({ shouldAdvanceTime: true }));
+  afterEach(vi.runAllTimers);
+  afterAll(vi.useRealTimers);
+
+  it('renders a snackbar notification', () => {
+    renderSnackbar();
+
+    const snackbar = screen.getByRole('alertdialog', { name: /order submitted/i });
+    const closeButton = screen.getByRole('button', { name: /close snackbar/i });
+    expect(snackbar).toBeInTheDocument();
+    expect(snackbar.classList).toContainEqual(expect.stringMatching('success'));
+    expect(closeButton).toBeInTheDocument();
+  });
+
+  it('renders an error notification if kind is set to error', () => {
+    renderSnackbar({
+      snackbar: {
+        kind: 'error',
+        title: 'Error submitting order',
+        subtitle: 'Error contacting lab system. Please try again later',
+      },
+    });
+
+    const snackbar = screen.getByRole('alertdialog', { name: /error submitting order/i });
+    expect(snackbar).toBeInTheDocument();
+    expect(snackbar.classList).toContainEqual(expect.stringMatching('error'));
+    expect(screen.getByRole('button', { name: /close snackbar/i })).toBeInTheDocument();
+    expect(screen.getByText(/error contacting lab system. please try again later/i)).toBeInTheDocument();
+  });
+
+  it(
+    'automatically dismisses the snackbar after a timeout if autoClose is set to true',
+    { timeout: 2000 },
+    async () => {
+      renderSnackbar({
+        snackbar: {
+          autoClose: true,
+          timeoutInMs: 500,
+          title: 'Order submitted',
+        },
+      });
+
+      const snackbar = screen.getByRole('alertdialog', { name: /order submitted/i });
+      expect(snackbar).toBeInTheDocument();
+
+      act(() => {
+        vi.advanceTimersByTime(750);
+      });
+
+      await waitFor(() => expect(mockCloseSnackbar).toHaveBeenCalledTimes(1), { timeout: 200 });
+    },
+  );
+
+  it('renders an actionable variant of the snackbar if actionButtonLabel is provided', () => {
+    renderSnackbar({
+      snackbar: {
+        actionButtonLabel: 'Undo',
+        title: 'Order submitted',
+      },
+    });
+
+    const snackbar = screen.getByRole('alertdialog', { name: /order submitted/i });
+    const actionButton = screen.getByRole('button', { name: /undo/i });
+    expect(snackbar).toBeInTheDocument();
+    expect(actionButton).toBeInTheDocument();
+  });
+});
+
+function renderSnackbar(overrides = {}) {
+  const testProps = {
+    snackbar: {
+      id: 1,
+      autoClose: false,
+      title: 'Order submitted',
+    },
+    closeSnackbar: mockCloseSnackbar,
+  };
+
+  render(<Snackbar {...testProps} {...overrides} />);
+}

package/packages/framework/esm-styleguide/src/spinner/_spinner.scss

@@ -0,0 +1,14 @@
+body {
+  min-height: 100vh;
+  margin: 0;
+  padding: 0;
+}
+.omrs-loading-spinner {
+  display: flex;
+  flex: 1;
+  align-items: center;
+  justify-content: center;
+  > .cds--inline-loading {
+    width: auto;
+  }
+}

package/packages/framework/esm-styleguide/src/spinner/index.ts

@@ -0,0 +1,14 @@
+/** @module @category UI */
+
+export function renderLoadingSpinner(target: HTMLElement) {
+  const template = document.querySelector<HTMLTemplateElement>('template#loading-spinner');
+
+  if (template) {
+    const frag = template.content.cloneNode(true);
+    const refs = Array.prototype.map.call(frag.childNodes, (m: HTMLElement) => m);
+    target.appendChild(frag);
+    return () => refs.forEach((child: ChildNode) => child.remove());
+  }
+
+  return () => {};
+}

package/packages/framework/esm-styleguide/src/svg-utils.ts

@@ -0,0 +1,31 @@
+/* The svg container is a div that contains all the OpenMRS svgs, with
+ * an HTML id that can be referenced with the following code:
+ * <svg role="img">
+ *   <use link:href="#the-svg-id"></use>
+ * </svg>
+ *
+ * This approach is known as "svg sprites"
+ */
+const svgContainer = document.createElement('div');
+const appendContainer = () => {
+  document.body.appendChild(svgContainer);
+};
+svgContainer.id = 'omrs-svgs-container';
+svgContainer.style.display = 'none';
+
+if (document.readyState === 'complete') {
+  appendContainer();
+} else {
+  window.addEventListener('load', appendContainer);
+}
+
+export function addSvg(htmlId: string, svgString: string) {
+  const domParser = new DOMParser();
+  const dom = domParser.parseFromString(svgString, 'image/svg+xml');
+  const svgElement = dom.querySelector('svg');
+
+  if (svgElement) {
+    svgElement.id = htmlId;
+    svgContainer.appendChild(svgElement);
+  }
+}

package/packages/framework/esm-styleguide/src/test-utils.tsx

@@ -0,0 +1,19 @@
+import React, { type ReactElement } from 'react';
+import { SWRConfig } from 'swr';
+import { type RenderOptions, render } from '@testing-library/react';
+
+export const swrWrapper = ({ children }) => {
+  return (
+    <SWRConfig
+      value={{
+        dedupingInterval: 0,
+        provider: () => new Map(),
+      }}
+    >
+      {children}
+    </SWRConfig>
+  );
+};
+
+export const renderWithSwr = (ui: ReactElement, options?: Omit<RenderOptions, 'queries'>) =>
+  render(ui, { wrapper: swrWrapper, ...options });

package/packages/framework/esm-styleguide/src/toasts/_toasts.scss

@@ -0,0 +1,22 @@
+@use '@carbon/layout';
+
+.omrs-toasts-container {
+  display: flex;
+  flex-direction: column;
+  z-index: 100000;
+  position: fixed;
+  width: 20rem;
+  top: layout.$spacing-10;
+  right: layout.$spacing-05;
+  gap: layout.$spacing-03;
+}
+
+.omrs-toast-mounting,
+.omrs-toast-mounting > * {
+  padding: 0;
+}
+
+.omrs-toast-closing,
+.omrs-toast-mounting {
+  opacity: 0;
+}

package/packages/framework/esm-styleguide/src/toasts/active-toasts.component.tsx

@@ -0,0 +1,45 @@
+/** @module @category UI */
+import React, { useCallback, useEffect, useState } from 'react';
+import type { Subject } from 'rxjs';
+import type { ToastNotificationMeta } from './toast.component';
+import { Toast } from './toast.component';
+
+interface ActiveToastsProps {
+  subject: Subject<ToastNotificationMeta>;
+}
+
+const ActiveToasts: React.FC<ActiveToastsProps> = ({ subject }) => {
+  const [toasts, setToasts] = useState<Array<ToastNotificationMeta>>([]);
+
+  const closeToast = useCallback((toast) => {
+    setToasts((toasts) => toasts.filter((t) => t !== toast));
+  }, []);
+
+  useEffect(() => {
+    const subscription = subject.subscribe((toast) =>
+      setToasts((toasts) => [
+        ...toasts.filter(
+          (t) =>
+            t.description !== toast.description ||
+            t.kind !== toast.kind ||
+            t.title !== toast.title ||
+            t.actionButtonLabel !== toast.actionButtonLabel ||
+            t.onActionButtonClick !== toast.onActionButtonClick,
+        ),
+        toast,
+      ]),
+    );
+
+    return () => subscription.unsubscribe();
+  }, [subject]);
+
+  return (
+    <>
+      {toasts.map((toast) => (
+        <Toast key={toast.id} toast={toast} closeToast={() => closeToast(toast)} />
+      ))}
+    </>
+  );
+};
+
+export default ActiveToasts;

package/packages/framework/esm-styleguide/src/toasts/index.tsx

@@ -0,0 +1,52 @@
+/** @module @category UI */
+import React from 'react';
+import { createRoot } from 'react-dom/client';
+import { Subject } from 'rxjs';
+import type { ToastDescriptor, ToastNotificationMeta } from './toast.component';
+import ActiveToasts from './active-toasts.component';
+import isEmpty from 'lodash-es/isEmpty';
+
+export { type ToastDescriptor, type ToastType, type ToastNotificationMeta } from './toast.component';
+
+const toastsSubject = new Subject<ToastNotificationMeta>();
+let toastId = 0;
+
+/**
+ * Starts a rendering host for toast notifications. Should only be used by the app shell.
+ * Under normal conditions there is no need to use this function.
+ * @param target The container target that hosts the toast notifications.
+ */
+export function renderToasts(target: HTMLElement | null) {
+  if (target) {
+    const root = createRoot(target);
+    root.render(<ActiveToasts subject={toastsSubject} />);
+  }
+}
+
+function isNotEmpty(description: React.ReactNode) {
+  return typeof description === 'string'
+    ? description.trim().length > 0
+    : typeof description === 'object'
+      ? !isEmpty(description)
+      : false;
+}
+
+/**
+ * Displays a toast notification in the UI.
+ * @param toast The description of the toast to display.
+ */
+export function showToast(toast: ToastDescriptor) {
+  if (toast && isNotEmpty(toast.description)) {
+    setTimeout(() => {
+      // always use in subsequent cycle
+      toastsSubject.next({
+        ...toast,
+        id: toastId++,
+      });
+    }, 0);
+  } else {
+    console.error(
+      `showToast must be called with an object having a 'description' property that is a non-empty string or object`,
+    );
+  }
+}

package/packages/framework/esm-styleguide/src/toasts/toast.component.tsx

@@ -0,0 +1,45 @@
+/** @module @category UI */
+import React, { useCallback } from 'react';
+import { ActionableNotification } from '@carbon/react';
+
+export interface ToastProps {
+  toast: ToastNotificationMeta;
+  closeToast(): void;
+}
+
+export interface ToastDescriptor {
+  description: React.ReactNode;
+  onActionButtonClick?: () => void;
+  actionButtonLabel?: string;
+  kind?: ToastType;
+  critical?: boolean;
+  title?: string;
+}
+
+export interface ToastNotificationMeta extends ToastDescriptor {
+  id: number;
+}
+
+export type ToastType = 'error' | 'info' | 'info-square' | 'success' | 'warning' | 'warning-alt';
+
+export const Toast: React.FC<ToastProps> = ({ toast, closeToast }) => {
+  const { description, kind, critical, title, actionButtonLabel, onActionButtonClick = () => {} } = toast;
+  const handleActionClick = useCallback(() => {
+    onActionButtonClick();
+    closeToast();
+  }, [closeToast, onActionButtonClick]);
+
+  return (
+    <div>
+      <ActionableNotification
+        actionButtonLabel={actionButtonLabel}
+        kind={kind || 'info'}
+        lowContrast={critical}
+        subtitle={description}
+        title={title || ''}
+        onActionButtonClick={handleActionClick}
+        onClose={closeToast}
+      />
+    </div>
+  );
+};

package/packages/framework/esm-styleguide/src/utils.ts

@@ -0,0 +1,20 @@
+/**
+ * Array of valid values for Carbon tag's "type" attribute.
+ * Options from https://react.carbondesignsystem.com/?path=/docs/components-tag--overview
+ */
+export const carbonTagColors = [
+  'red',
+  'magenta',
+  'purple',
+  'blue',
+  'teal',
+  'cyan',
+  'gray',
+  'green',
+  'warm-gray',
+  'cool-gray',
+  'high-contrast',
+  'outline',
+] as const;
+
+export type CarbonTagColor = (typeof carbonTagColors)[number];