@openmrs/esm-styleguide 8.0.1-pre.3581 → 8.0.1-pre.3592

package/src/empty-card/empty-card-registration.ts

@@ -0,0 +1,6 @@
+import emptyStateIllustration from './empty-data-illustration.svg';
+import { addSvg } from '../svg-utils';
+
+export function setupEmptyCard() {
+  addSvg('omrs-empty-state-illustration', emptyStateIllustration);
+}

package/src/empty-card/empty-card.component.tsx

@@ -0,0 +1,55 @@
+import React from 'react';
+import classNames from 'classnames';
+import { Button, Layer, Tile } from '@carbon/react';
+import { useLayoutType } from '@openmrs/esm-react-utils';
+import { getCoreTranslation } from '@openmrs/esm-translations';
+import { CardHeader } from '../cards';
+import styles from './empty-card.module.scss';
+
+export interface EmptyCardProps {
+  /** The name of the type of item that would be displayed here if not empty. This must be a pre-translated string. */
+  displayText: string;
+  /** The title to use for this empty component. This must be a pre-translated string. */
+  headerTitle: string;
+  /** A callback to invoke when the user tries to record a new item. */
+  launchForm?(): void;
+}
+
+const EmptyDataIllustration = ({ width = '64', height = '64' }) => {
+  return (
+    <svg width={width} height={height} viewBox="0 0 64 64">
+      <use href={`#omrs-empty-data-illustration`} />
+    </svg>
+  );
+};
+
+/**
+ * Re-usable card for displaying an empty state
+ */
+export const EmptyCard: React.FC<EmptyCardProps> = (props) => {
+  const isTablet = useLayoutType() === 'tablet';
+  const launchForm = props.launchForm;
+
+  return (
+    <Layer className={styles.layer}>
+      <Tile className={styles.tile}>
+        <CardHeader title={props.headerTitle} />
+        <EmptyDataIllustration />
+        <p className={styles.content}>
+          {getCoreTranslation('emptyStateText', 'There are no {{displayText}} to display', {
+            displayText: props.displayText,
+          })}
+        </p>
+        <p className={styles.action}>
+          {launchForm && (
+            <Button onClick={() => launchForm()} kind="ghost" size={isTablet ? 'lg' : 'sm'}>
+              {getCoreTranslation('recordNewEntry', 'Record {{ displayText }}', {
+                displayText: props.displayText,
+              })}
+            </Button>
+          )}
+        </p>
+      </Tile>
+    </Layer>
+  );
+};

package/src/empty-card/empty-card.module.scss

@@ -0,0 +1,27 @@
+@use '@carbon/layout';
+@use '@carbon/type';
+@use '../vars' as *;
+
+.action {
+  margin-bottom: layout.$spacing-03;
+}
+
+.content {
+  @include type.type-style('heading-compact-01');
+  color: $text-02;
+  margin-top: layout.$spacing-05;
+  margin-bottom: layout.$spacing-03;
+}
+
+.heading:after {
+  content: '';
+  display: block;
+  width: layout.$spacing-07;
+  padding-top: 0.188rem;
+  border-bottom: 0.375rem solid var(--brand-03);
+}
+
+.tile {
+  text-align: center;
+  border: 1px solid $ui-03;
+}

package/src/empty-card/empty-card.test.tsx

@@ -0,0 +1,58 @@
+import React from 'react';
+import { describe, expect, it, vi } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { EmptyCard } from './empty-card.component';
+
+describe('EmptyCard', () => {
+  const defaultProps = {
+    displayText: 'medications',
+    headerTitle: 'Medications',
+  };
+
+  it('renders the header title', () => {
+    render(<EmptyCard {...defaultProps} />);
+    expect(screen.getByRole('heading', { name: /medications/i })).toBeInTheDocument();
+  });
+
+  it('renders the empty state text with the display text', () => {
+    render(<EmptyCard {...defaultProps} />);
+    expect(screen.getByText(/there are no medications to display/i)).toBeInTheDocument();
+  });
+
+  it('does not render the action button when launchForm is not provided', () => {
+    render(<EmptyCard {...defaultProps} />);
+    expect(screen.queryByRole('button')).not.toBeInTheDocument();
+  });
+
+  it('renders the action button when launchForm is provided', () => {
+    const launchForm = vi.fn();
+    render(<EmptyCard {...defaultProps} launchForm={launchForm} />);
+    expect(screen.getByRole('button', { name: /record medications/i })).toBeInTheDocument();
+  });
+
+  it('calls launchForm when the action button is clicked', async () => {
+    const user = userEvent.setup();
+    const launchForm = vi.fn();
+    render(<EmptyCard {...defaultProps} launchForm={launchForm} />);
+
+    const button = screen.getByRole('button', { name: /record medications/i });
+    await user.click(button);
+
+    expect(launchForm).toHaveBeenCalledTimes(1);
+  });
+
+  it('renders with different display text', () => {
+    render(<EmptyCard displayText="allergies" headerTitle="Allergies" />);
+    expect(screen.getByRole('heading', { name: /allergies/i })).toBeInTheDocument();
+    expect(screen.getByText(/there are no allergies to display/i)).toBeInTheDocument();
+  });
+
+  it('renders the empty data illustration', () => {
+    render(<EmptyCard {...defaultProps} />);
+    // eslint-disable-next-line testing-library/no-node-access
+    const svg = document.querySelector('svg');
+    expect(svg).toBeInTheDocument();
+    expect(svg).toHaveAttribute('viewBox', '0 0 64 64');
+  });
+});

package/src/empty-card/empty-data-illustration.svg

@@ -0,0 +1,32 @@
+<svg viewBox="0 0 64 64">
+  <g fill="none" fillRule="evenodd">
+    <path
+      d="M38.133 13.186H21.947c-.768.001-1.39.623-1.39 1.391V50.55l-.186.057-3.97 1.216a.743.743 0 01-.927-.493L3.664 12.751a.742.742 0 01.492-.926l6.118-1.874 17.738-5.43 6.119-1.873a.741.741 0 01.926.492L38.076 13l.057.186z"
+      fill="#F4F4F4"
+    />
+    <path
+      d="M41.664 13L38.026 1.117A1.576 1.576 0 0036.056.07l-8.601 2.633-17.737 5.43-8.603 2.634a1.578 1.578 0 00-1.046 1.97l12.436 40.616a1.58 1.58 0 001.969 1.046l5.897-1.805.185-.057v-.194l-.185.057-5.952 1.822a1.393 1.393 0 01-1.737-.923L.247 12.682a1.39 1.39 0 01.923-1.738L9.772 8.31 27.51 2.881 36.112.247a1.393 1.393 0 011.737.923L41.47 13l.057.186h.193l-.057-.185z"
+      fill="#8D8D8D"
+    />
+    <path
+      d="M11.378 11.855a.836.836 0 01-.798-.59L9.385 7.361a.835.835 0 01.554-1.042l16.318-4.996a.836.836 0 011.042.554l1.195 3.902a.836.836 0 01-.554 1.043l-16.318 4.995a.831.831 0 01-.244.037z"
+      fill="#C6C6C6"
+    />
+    <circle fill="#C6C6C6" cx="17.636" cy="2.314" r="1.855" />
+    <circle fill="#FFF" fillRule="nonzero" cx="17.636" cy="2.314" r="1.175" />
+    <path
+      d="M55.893 53.995H24.544a.79.79 0 01-.788-.789V15.644a.79.79 0 01.788-.788h31.349a.79.79 0 01.788.788v37.562a.79.79 0 01-.788.789z"
+      fill="#F4F4F4"
+    />
+    <path
+      d="M41.47 13H21.948a1.579 1.579 0 00-1.576 1.577V52.4l.185-.057V14.577c.001-.768.623-1.39 1.391-1.39h19.581L41.471 13zm17.02 0H21.947a1.579 1.579 0 00-1.576 1.577v42.478c0 .87.706 1.576 1.576 1.577H58.49a1.579 1.579 0 001.576-1.577V14.577a1.579 1.579 0 00-1.576-1.576zm1.39 44.055c0 .768-.622 1.39-1.39 1.392H21.947c-.768-.001-1.39-.624-1.39-1.392V14.577c0-.768.622-1.39 1.39-1.39H58.49c.768 0 1.39.622 1.39 1.39v42.478z"
+      fill="#8D8D8D"
+    />
+    <path
+      d="M48.751 17.082H31.686a.836.836 0 01-.835-.835v-4.081c0-.46.374-.834.835-.835H48.75c.461 0 .834.374.835.835v4.08c0 .462-.374.835-.835.836z"
+      fill="#C6C6C6"
+    />
+    <circle fill="#C6C6C6" cx="40.218" cy="9.755" r="1.855" />
+    <circle fill="#FFF" fillRule="nonzero" cx="40.218" cy="9.755" r="1.13" />
+  </g>
+</svg>

package/src/empty-card/index.ts

@@ -0,0 +1 @@
+export { EmptyCard, type EmptyCardProps } from './empty-card.component';

package/src/error-card/error-card.component.tsx

@@ -0,0 +1,35 @@
+import React from 'react';
+import { Layer, Tile } from '@carbon/react';
+import { getCoreTranslation } from '@openmrs/esm-translations';
+import { CardHeader } from '../cards';
+import styles from './error-card.module.scss';
+
+export interface ErrorCardProps {
+  /** This is the error that triggered rendering the card. It is expected to be the error returned from `openmrsFetch()` */
+  error: any;
+  /** The title for this card. This must be a pre-translated string. */
+  headerTitle: string;
+}
+
+/**
+ * Re-usable card for displaying a fetch error
+ */
+export const ErrorCard: React.FC<ErrorCardProps> = ({ error, headerTitle }) => {
+  return (
+    <Layer>
+      <Tile className={styles.tile}>
+        <CardHeader title={headerTitle} />
+        <p className={styles.errorMessage}>
+          {getCoreTranslation('error', 'Error')} {`${error?.response?.status}: `}
+          {error?.response?.statusText}
+        </p>
+        <p className={styles.errorCopy}>
+          {getCoreTranslation(
+            'errorCopy',
+            'Sorry, there was a problem displaying this information. You can try to reload this page, or contact the site administrator and quote the error code above.',
+          )}
+        </p>
+      </Tile>
+    </Layer>
+  );
+};

package/src/error-card/error-card.module.scss

@@ -0,0 +1,21 @@
+@use '@carbon/layout';
+@use '@carbon/type';
+@use '@openmrs/esm-styleguide/src/vars' as *;
+
+.errorMessage {
+  @include type.type-style('heading-compact-02');
+
+  margin-top: 2.25rem;
+  margin-bottom: layout.$spacing-03;
+}
+
+.errorCopy {
+  margin-bottom: layout.$spacing-03;
+  @include type.type-style('body-01');
+  color: $text-02;
+}
+
+.tile {
+  text-align: center;
+  border: 1px solid $ui-03;
+}

package/src/error-card/error-card.test.tsx

@@ -0,0 +1,25 @@
+import React from 'react';
+import { describe, expect, it } from 'vitest';
+import '@testing-library/jest-dom/vitest';
+import { render, screen } from '@testing-library/react';
+import { ErrorCard } from './error-card.component';
+
+describe('ErrorCard', () => {
+  it('renders an error state widget card', () => {
+    const testError = {
+      response: {
+        status: 500,
+        statusText: 'Internal Server Error',
+      },
+    };
+    render(<ErrorCard headerTitle="appointments" error={testError} />);
+
+    expect(screen.getByRole('heading', { name: /appointments/i })).toBeInTheDocument();
+    expect(screen.getByText(/Error 500: Internal Server Error/i)).toBeInTheDocument();
+    expect(
+      screen.getByText(
+        /Sorry, there was a problem displaying this information. You can try to reload this page, or contact the site administrator and quote the error code above./i,
+      ),
+    ).toBeInTheDocument();
+  });
+});

package/src/error-card/index.ts

@@ -0,0 +1 @@
+export { ErrorCard, type ErrorCardProps } from './error-card.component';

package/src/index.ts

@@ -1,10 +1,11 @@
 import { defineConfigSchema } from '@openmrs/esm-config';
-import { setupLogo } from './logo';
-import { setupIcons } from './icons/icon-registration';
+import { registerModal } from '@openmrs/esm-extensions';
 import { setupBranding } from './brand';
 import { esmStyleGuideSchema } from './config-schema';
+import { setupEmptyCard } from './empty-card/empty-card-registration';
+import { setupIcons } from './icons/icon-registration';
+import { setupLogo } from './logo';
 import { setupPictograms } from './pictograms/pictogram-registration';
-import { registerModal } from '@openmrs/esm-extensions';
 import { getSyncLifecycle } from '@openmrs/esm-react-utils';
 import Workspace2ClosePromptModal from './workspaces2/workspace2-close-prompt.modal';
 
@@ -13,6 +14,7 @@ setupBranding();
 setupLogo();
 setupIcons();
 setupPictograms();
+setupEmptyCard();
 
 registerModal({
   name: 'workspace2-close-prompt',

package/src/internal.ts

@@ -1,9 +1,12 @@
 export * from './breakpoints';
+export * from './cards';
 export * from './config-schema';
 export * from './custom-overflow-menu';
 export * from './dashboard-extension';
 export * from './datepicker';
 export * from './diagnosis-tags';
+export * from './empty-card';
+export * from './error-card';
 export * from './error-state';
 export * from './icons/icons';
 export * from './left-nav';
@@ -13,6 +16,7 @@ export * from './notifications';
 export * from './notifications/actionable-notification.component';
 export * from './notifications/notification.component';
 export * from './page-header';
+export * from './pagination';
 export * from './patient-banner';
 export * from './patient-photo';
 export * from './pictograms/pictograms';

package/src/pagination/index.ts

@@ -0,0 +1 @@
+export * from './pagination.component';

package/src/pagination/pagination.component.tsx

@@ -0,0 +1,77 @@
+import React from 'react';
+import classNames from 'classnames';
+import { Pagination as CarbonPagination, type PaginationProps as CarbonPaginationProps } from '@carbon/react';
+import { ConfigurableLink, useLayoutType, usePaginationInfo } from '@openmrs/esm-react-utils';
+import { getCoreTranslation } from '@openmrs/esm-translations';
+import styles from './pagination.module.scss';
+
+export interface PaginationProps {
+  /** The count of current items displayed */
+  currentItems: number;
+  /** The count of total items displayed */
+  totalItems: number;
+  /** The current page number */
+  pageNumber: number;
+  /** The size of each page */
+  pageSize: number;
+  /** A callback to be called when the page changes */
+  onPageNumberChange?: CarbonPaginationProps['onChange'];
+  /** An optional URL the user should be directed to if they click on the link to see all results */
+  dashboardLinkUrl?: string;
+  /** Optional text to display instead of the default "See all" */
+  dashboardLinkLabel?: string;
+}
+
+/**
+ * Re-usable pagination bar
+ */
+export const Pagination: React.FC<PaginationProps> = ({
+  totalItems,
+  pageSize,
+  onPageNumberChange,
+  pageNumber,
+  dashboardLinkUrl,
+  currentItems,
+  dashboardLinkLabel: urlLabel,
+}) => {
+  const { pageSizes, pageItemsCount } = usePaginationInfo(pageSize, totalItems, pageNumber, currentItems);
+  const isTablet = useLayoutType() === 'tablet';
+  const itemsDisplayed = getCoreTranslation('paginationItemsCount', '{{pageItemsCount}} / {{totalItems}} items', {
+    totalItems,
+    pageItemsCount,
+  });
+
+  return (
+    <>
+      {totalItems > 0 && (
+        <div
+          className={classNames({
+            [styles.tablet]: isTablet,
+            [styles.desktop]: !isTablet,
+          })}
+        >
+          <div>
+            {itemsDisplayed}
+            {dashboardLinkUrl && (
+              <ConfigurableLink to={dashboardLinkUrl} className={styles.configurableLink}>
+                {urlLabel ?? getCoreTranslation('seeAll', 'See all')}
+              </ConfigurableLink>
+            )}
+          </div>
+          <CarbonPagination
+            className={styles.pagination}
+            page={pageNumber}
+            pageSize={pageSize}
+            pageSizes={pageSizes}
+            totalItems={totalItems}
+            onChange={onPageNumberChange}
+            pageRangeText={(_, total) =>
+              getCoreTranslation('paginationOfPages', 'of {{count}} pages', { count: total })
+            }
+            size={isTablet ? 'lg' : 'sm'}
+          />
+        </div>
+      )}
+    </>
+  );
+};

package/src/pagination/pagination.module.scss

@@ -0,0 +1,66 @@
+@use '@carbon/layout';
+@use '@carbon/type';
+@use '../vars' as *;
+
+.bodyShort01 {
+  @include type.type-style('body-compact-01');
+}
+
+.desktop,
+.tablet {
+  @include type.type-style('body-compact-01');
+  display: flex;
+  justify-content: space-between;
+  color: $text-02;
+  background-color: $ui-02;
+  padding-left: layout.$spacing-05;
+  align-items: center;
+  border-top: 1px solid $ui-03;
+}
+
+.desktop :global(.cds--pagination) {
+  min-height: 0;
+  height: layout.$spacing-07;
+  width: auto;
+  border: none;
+
+  & :global(.cds--select-input),
+  :global(.cds--btn),
+  :global(.cds--pagination__right) {
+    min-height: 0;
+    height: layout.$spacing-07;
+  }
+}
+
+.tablet :global(.cds--pagination) {
+  min-height: 0;
+  height: layout.$spacing-09;
+  width: auto;
+  border: none;
+
+  & :global(.cds--select-input),
+  :global(.cds--btn),
+  :global(.cds--pagination__right) {
+    min-height: 0;
+    height: layout.$spacing-09;
+  }
+}
+
+.configurableLink {
+  text-decoration: none;
+  @extend .bodyShort01;
+  padding: 0 layout.$spacing-03;
+}
+
+.pagination {
+  @include type.type-style('body-compact-01');
+  background-color: $ui-02;
+  color: $text-02;
+  display: flex;
+}
+
+div.pagination {
+  & > :global(.cds--pagination__left) {
+    display: none;
+  }
+}

package/src/pagination/pagination.test.tsx

@@ -0,0 +1,72 @@
+import React from 'react';
+import { describe, expect, it, vi } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { Pagination } from './pagination.component';
+
+describe('Pagination', () => {
+  const defaultProps = {
+    currentItems: 10,
+    totalItems: 100,
+    pageNumber: 1,
+    pageSize: 10,
+    onPageNumberChange: vi.fn(),
+  };
+
+  it('renders nothing when totalItems is 0', () => {
+    const { container } = render(<Pagination {...defaultProps} totalItems={0} />);
+    expect(container).toBeEmptyDOMElement();
+  });
+
+  it('renders pagination when totalItems is greater than 0', () => {
+    render(<Pagination {...defaultProps} />);
+    expect(screen.getByText(/10 \/ 100 items/i)).toBeInTheDocument();
+  });
+
+  it('displays correct items count for the first page', () => {
+    render(<Pagination {...defaultProps} pageNumber={1} currentItems={10} />);
+    expect(screen.getByText(/10 \/ 100 items/i)).toBeInTheDocument();
+  });
+
+  it('displays correct items count for a middle page', () => {
+    render(<Pagination {...defaultProps} pageNumber={5} currentItems={10} />);
+    expect(screen.getByText(/50 \/ 100 items/i)).toBeInTheDocument();
+  });
+
+  it('displays correct items count for the last page with fewer items', () => {
+    render(<Pagination {...defaultProps} totalItems={95} pageNumber={10} currentItems={5} />);
+    expect(screen.getByText(/95 \/ 95 items/i)).toBeInTheDocument();
+  });
+
+  it('renders ConfigurableLink when dashboardLinkUrl is provided', () => {
+    render(<Pagination {...defaultProps} dashboardLinkUrl="/dashboard" />);
+    expect(screen.getByRole('link', { name: /see all/i })).toBeInTheDocument();
+    expect(screen.getByRole('link', { name: /see all/i })).toHaveAttribute('href', '/dashboard');
+  });
+
+  it('uses custom label when dashboardLinkLabel is provided', () => {
+    render(<Pagination {...defaultProps} dashboardLinkUrl="/dashboard" dashboardLinkLabel="View all items" />);
+    expect(screen.getByRole('link', { name: /view all items/i })).toBeInTheDocument();
+  });
+
+  it('does not render ConfigurableLink when dashboardLinkUrl is not provided', () => {
+    render(<Pagination {...defaultProps} />);
+    expect(screen.queryByRole('link')).not.toBeInTheDocument();
+  });
+
+  it('calls onPageNumberChange when page changes', async () => {
+    const user = userEvent.setup();
+    const onPageNumberChange = vi.fn();
+    render(<Pagination {...defaultProps} onPageNumberChange={onPageNumberChange} />);
+
+    const nextButton = screen.getByRole('button', { name: /next/i });
+    await user.click(nextButton);
+
+    expect(onPageNumberChange).toHaveBeenCalled();
+  });
+
+  it('handles case when pageSize is greater than totalItems', () => {
+    render(<Pagination {...defaultProps} pageSize={50} totalItems={30} currentItems={30} />);
+    expect(screen.getByText(/30 \/ 30 items/i)).toBeInTheDocument();
+  });
+});

package/src/public.ts

@@ -1,29 +1,31 @@
+export { type StyleguideConfigObject } from './config-schema';
+export * from './cards';
+export * from './custom-overflow-menu';
+export * from './dashboard-extension';
+export * from './datepicker';
+export * from './diagnosis-tags';
+export * from './empty-card';
+export * from './error-state';
+export * from './error-card';
+export * from './icons/icons';
+export * from './left-nav';
+export * from './location-picker';
+export { showModal } from './modals';
 export { showNotification, showActionableNotification } from './notifications';
-export { type NotificationDescriptor, type InlineNotificationType } from './notifications/notification.component';
 export {
   type ActionableNotificationDescriptor,
   type ActionableNotificationType,
 } from './notifications/actionable-notification.component';
-export { showToast } from './toasts';
-export { showModal } from './modals';
-export * from './workspaces/public';
-export { type ToastDescriptor, type ToastType, type ToastNotificationMeta } from './toasts/toast.component';
-export { showSnackbar } from './snackbars';
-export { type SnackbarDescriptor, type SnackbarType, type SnackbarMeta } from './snackbars/snackbar.component';
-export * from './left-nav';
-export * from './dashboard-extension';
-export * from './error-state';
-export * from './datepicker';
-export * from './responsive-wrapper';
+export { type NotificationDescriptor, type InlineNotificationType } from './notifications/notification.component';
+export * from './page-header';
+export * from './pagination';
 export * from './patient-banner';
 export * from './patient-photo';
-export * from './custom-overflow-menu';
-export * from './icons/icons';
-export * from './page-header';
 export * from './pictograms/pictograms';
-export { type StyleguideConfigObject } from './config-schema';
-export * from './location-picker';
-export * from './diagnosis-tags';
+export * from './responsive-wrapper';
+export { showSnackbar, type SnackbarDescriptor, type SnackbarType, type SnackbarMeta } from './snackbars';
+export { showToast, type ToastDescriptor, type ToastType, type ToastNotificationMeta } from './toasts';
+export * from './workspaces/public';
 export {
   launchWorkspace2,
   launchWorkspaceGroup2,

package/src/snackbars/index.tsx

@@ -6,6 +6,8 @@ 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;
 

package/src/toasts/index.tsx

@@ -6,6 +6,8 @@ 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;