@mherman22/esm-act-app 1.0.1-pre.22

package/src/act-home/care-cascade.component.tsx

@@ -0,0 +1,77 @@
+import React, { useMemo } from 'react';
+import dayjs from 'dayjs';
+import { useTranslation } from 'react-i18next';
+import { InlineNotification, SkeletonText } from '@carbon/react';
+import { formatDate, toOmrsIsoString, useConfig } from '@openmrs/esm-framework';
+import { type Config } from '../config-schema';
+import { ScreenAccess } from '../access/screen-access.component';
+import { useReportDataset } from '../reports/report-dataset.resource';
+import { ActHomeCard } from './act-home-card.component';
+import styles from './care-cascade.scss';
+
+function Cascade() {
+  const { t } = useTranslation();
+  const { careCascade } = useConfig<Config>();
+  // The reports app runs a date as that day's midnight, so the counts match the report run for today.
+  const today = useMemo(() => dayjs().startOf('day'), []);
+  const { rows, isLoading, error } = useReportDataset(careCascade.report, { endDate: toOmrsIsoString(today.toDate()) });
+  // The cascade descriptor names its columns step and patients, one row per step.
+  const byStep = new Map(rows.map((row) => [String(row.step), Number(row.patients)]));
+  const steps = careCascade.steps
+    .filter((step) => byStep.has(step))
+    .map((step) => ({ step, patients: byStep.get(step) }));
+  const largest = Math.max(0, ...steps.map((row) => row.patients));
+
+  return (
+    <ActHomeCard
+      title={t('careCascade', 'Care cascade')}
+      link={{ label: t('report', 'Report'), to: careCascade.reportUrl }}
+    >
+      {error ? (
+        <InlineNotification
+          kind="error"
+          lowContrast
+          hideCloseButton
+          title={t('couldNotLoadCareCascade', 'Could not load the care cascade')}
+        />
+      ) : isLoading ? (
+        <div data-testid="cascade-loading">
+          <SkeletonText paragraph lineCount={4} />
+        </div>
+      ) : steps.length ? (
+        <>
+          <div className={styles.steps}>
+            {steps.map((row) => (
+              <div key={row.step} data-testid="cascade-step" className={styles.step}>
+                <span>{row.step}</span>
+                <span className={styles.track}>
+                  <span
+                    data-testid="cascade-bar"
+                    className={styles.bar}
+                    style={{ width: `${largest ? Math.round((row.patients / largest) * 100) : 0}%` }}
+                  />
+                </span>
+                <span className={styles.count}>{row.patients}</span>
+              </div>
+            ))}
+          </div>
+          <p className={styles.asOf}>
+            {t('cascadeReportDate', 'Report date: {{date}}', {
+              date: formatDate(today.toDate(), { time: false, noToday: true }),
+            })}
+          </p>
+        </>
+      ) : (
+        <p className={styles.empty}>{t('noCareCascadeData', 'No care cascade data')}</p>
+      )}
+    </ActHomeCard>
+  );
+}
+
+export default function CareCascade() {
+  return (
+    <ScreenAccess screen="home">
+      <Cascade />
+    </ScreenAccess>
+  );
+}

package/src/act-home/care-cascade.scss

@@ -0,0 +1,42 @@
+@use '@carbon/layout';
+@use '@carbon/type';
+@use '@openmrs/esm-styleguide/src/vars' as *;
+
+.steps {
+  display: flex;
+  flex-direction: column;
+  gap: layout.$spacing-03;
+}
+
+.step {
+  @include type.type-style('body-compact-01');
+  display: grid;
+  grid-template-columns: 12rem 1fr 3rem;
+  align-items: center;
+  gap: layout.$spacing-04;
+}
+
+.track {
+  height: layout.$spacing-05;
+}
+
+.bar {
+  display: block;
+  height: 100%;
+  @include brand-01(background-color);
+}
+
+.count {
+  @include type.type-style('heading-compact-01');
+  text-align: right;
+}
+
+.asOf {
+  @include type.type-style('helper-text-01');
+  margin-top: layout.$spacing-04;
+  color: $text-02;
+}
+
+.empty {
+  @include type.type-style('body-compact-01');
+}

package/src/act-home/care-cascade.test.tsx

@@ -0,0 +1,128 @@
+import React from 'react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import { homePrivilege, signInWith } from '../access/sign-in.test-helper';
+import { useReportDataset } from '../reports/report-dataset.resource';
+import CareCascade from './care-cascade.component';
+
+vi.mock('../reports/report-dataset.resource', () => ({ useReportDataset: vi.fn() }));
+const mockUseReportDataset = vi.mocked(useReportDataset);
+
+const cascade = [
+  { step_order: 1, step: 'Active', patients: 20 },
+  { step_order: 2, step: 'Prescribed Prophylaxis', patients: 17 },
+  { step_order: 3, step: 'Oral', patients: 2 },
+  { step_order: 4, step: 'BPG', patients: 15 },
+  { step_order: 5, step: 'Initiated BPG', patients: 11 },
+  { step_order: 6, step: 'Adherent', patients: 0 },
+];
+
+function dataset(value: Partial<ReturnType<typeof useReportDataset>>) {
+  mockUseReportDataset.mockReturnValue({ columns: [], rows: [], isLoading: false, error: undefined, ...value });
+}
+
+describe('CareCascade', () => {
+  beforeEach(async () => {
+    window.getOpenmrsSpaBase = () => '/openmrs/spa/';
+    await signInWith([homePrivilege]);
+  });
+
+  it('draws the configured steps of the cascade report, in the configured order, with their counts', () => {
+    dataset({ rows: cascade });
+
+    render(<CareCascade />);
+
+    const steps = screen.getAllByTestId('cascade-step');
+    expect(steps.map((step) => step.textContent)).toEqual([
+      'Active20',
+      'Prescribed Prophylaxis17',
+      'Initiated BPG11',
+      'Adherent0',
+    ]);
+  });
+
+  it('leaves out a configured step the report does not return', async () => {
+    await signInWith([homePrivilege], {
+      careCascade: { report: 'r', reportUrl: '${openmrsSpaBase}/reports', steps: ['Active', 'Covered today'] },
+    });
+    dataset({ rows: cascade });
+
+    render(<CareCascade />);
+
+    expect(screen.getAllByTestId('cascade-step').map((step) => step.textContent)).toEqual(['Active20']);
+  });
+
+  it('sizes each bar against the largest step', () => {
+    dataset({ rows: cascade });
+
+    render(<CareCascade />);
+
+    const widths = screen.getAllByTestId('cascade-bar').map((bar) => bar.style.width);
+    expect(widths).toEqual(['100%', '85%', '55%', '0%']);
+  });
+
+  it('evaluates the configured report up to the start of today, as the reports app runs it for today', () => {
+    vi.useFakeTimers({ now: new Date(2026, 8, 28, 10, 30) });
+    dataset({ rows: cascade });
+
+    render(<CareCascade />);
+
+    vi.useRealTimers();
+    const [report, params] = mockUseReportDataset.mock.calls.at(-1);
+    expect(report).toBe('9c6751ae-65fc-5f25-9aa6-8c65cb1dff68');
+    expect(new Date(params.endDate).getTime()).toBe(new Date(2026, 8, 28).getTime());
+  });
+
+  it('evaluates the report set in the config', async () => {
+    await signInWith([homePrivilege], {
+      careCascade: { report: 'RHD Care Cascade', reportUrl: '${openmrsSpaBase}/reports', steps: ['Active'] },
+    });
+    dataset({ rows: cascade });
+
+    render(<CareCascade />);
+
+    expect(mockUseReportDataset.mock.calls.at(-1)[0]).toBe('RHD Care Cascade');
+  });
+
+  it('links to the full report', () => {
+    dataset({ rows: cascade });
+
+    render(<CareCascade />);
+
+    expect(screen.getByRole('link', { name: /report/i })).toHaveAttribute('href', '/openmrs/spa/reports');
+  });
+
+  it('says so when the report has no rows', () => {
+    dataset({ rows: [] });
+
+    render(<CareCascade />);
+
+    expect(screen.getByText('No care cascade data')).toBeInTheDocument();
+  });
+
+  it('says so when the report cannot be evaluated', () => {
+    dataset({ error: new Error('Server responded with 404') });
+
+    render(<CareCascade />);
+
+    expect(screen.getByText('Could not load the care cascade')).toBeInTheDocument();
+    expect(screen.queryByTestId('cascade-step')).not.toBeInTheDocument();
+  });
+
+  it('shows a placeholder while the report runs', () => {
+    dataset({ isLoading: true });
+
+    render(<CareCascade />);
+
+    expect(screen.getByTestId('cascade-loading')).toBeInTheDocument();
+  });
+
+  it('is hidden from a user without the ACT home privilege', async () => {
+    await signInWith(['View Patient Flags']);
+    dataset({ rows: cascade });
+
+    render(<CareCascade />);
+
+    expect(screen.queryByText('Care cascade')).not.toBeInTheDocument();
+  });
+});

package/src/act-home/quick-actions.component.tsx

@@ -0,0 +1,32 @@
+import React from 'react';
+import { useTranslation } from 'react-i18next';
+import { Add, ArrowUpRight, Search } from '@carbon/react/icons';
+import { ConfigurableLink, useConfig } from '@openmrs/esm-framework';
+import { type Config } from '../config-schema';
+import { ScreenAccess } from '../access/screen-access.component';
+import styles from './quick-actions.scss';
+
+export default function QuickActions() {
+  const { t } = useTranslation();
+  const { quickActions } = useConfig<Config>();
+  const actions = [
+    { label: t('registerPatient', 'Register patient'), to: quickActions.registerPatientUrl, Icon: Add },
+    { label: t('enterProphylaxis', 'Enter prophylaxis'), to: quickActions.enterProphylaxisUrl, Icon: ArrowUpRight },
+    { label: t('findPatient', 'Find a patient'), to: quickActions.findPatientUrl, Icon: Search },
+  ];
+
+  return (
+    <ScreenAccess screen="home">
+      <div className={styles.actions}>
+        {actions.map(({ label, to, Icon }) => (
+          <ConfigurableLink key={label} to={to} className={styles.action}>
+            <span className={styles.icon}>
+              <Icon size={20} />
+            </span>
+            {label}
+          </ConfigurableLink>
+        ))}
+      </div>
+    </ScreenAccess>
+  );
+}

package/src/act-home/quick-actions.scss

@@ -0,0 +1,32 @@
+@use '@carbon/layout';
+@use '@carbon/type';
+@use '@openmrs/esm-styleguide/src/vars' as *;
+
+.actions {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(14rem, 1fr));
+  gap: layout.$spacing-05;
+}
+
+.action {
+  @include type.type-style('heading-compact-02');
+  display: flex;
+  align-items: center;
+  gap: layout.$spacing-05;
+  padding: layout.$spacing-05;
+  background-color: $ui-01;
+  border: 1px solid $ui-03;
+  color: $ui-05;
+  text-decoration: none;
+
+  &:hover {
+    background-color: $ui-02;
+  }
+}
+
+.icon {
+  display: flex;
+  padding: layout.$spacing-03;
+  @include brand-01(background-color);
+  color: $ui-01;
+}

package/src/act-home/quick-actions.test.tsx

@@ -0,0 +1,51 @@
+import React from 'react';
+import { beforeEach, describe, expect, it } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import { type Config } from '../config-schema';
+import { homePrivilege, signInWith } from '../access/sign-in.test-helper';
+import QuickActions from './quick-actions.component';
+
+const defaultQuickActions: Config['quickActions'] = {
+  registerPatientUrl: '${openmrsSpaBase}/patient-registration',
+  enterProphylaxisUrl: '${openmrsSpaBase}/forms',
+  findPatientUrl: '${openmrsSpaBase}/search',
+};
+
+describe('QuickActions', () => {
+  beforeEach(async () => {
+    window.getOpenmrsSpaBase = () => '/openmrs/spa/';
+    await signInWith([homePrivilege]);
+  });
+
+  it('links register patient, enter prophylaxis and find a patient to their screens', () => {
+    render(<QuickActions />);
+
+    expect(screen.getByRole('link', { name: /register patient/i })).toHaveAttribute(
+      'href',
+      '/openmrs/spa/patient-registration',
+    );
+    expect(screen.getByRole('link', { name: /enter prophylaxis/i })).toHaveAttribute('href', '/openmrs/spa/forms');
+    expect(screen.getByRole('link', { name: /find a patient/i })).toHaveAttribute('href', '/openmrs/spa/search');
+  });
+
+  it('uses the links set in the config', async () => {
+    await signInWith([homePrivilege], {
+      quickActions: { ...defaultQuickActions, enterProphylaxisUrl: '${openmrsSpaBase}/forms/prophylaxis' },
+    });
+
+    render(<QuickActions />);
+
+    expect(screen.getByRole('link', { name: /enter prophylaxis/i })).toHaveAttribute(
+      'href',
+      '/openmrs/spa/forms/prophylaxis',
+    );
+  });
+
+  it('is hidden from a user without the ACT home privilege', async () => {
+    await signInWith(['View Patient Flags']);
+
+    render(<QuickActions />);
+
+    expect(screen.queryByRole('link')).not.toBeInTheDocument();
+  });
+});

package/src/act-home/worklist-tiles.component.tsx

@@ -0,0 +1,69 @@
+import React from 'react';
+import { useTranslation } from 'react-i18next';
+import { InlineNotification, SkeletonText } from '@carbon/react';
+import { ConfigurableLink } from '@openmrs/esm-framework';
+import { ScreenAccess } from '../access/screen-access.component';
+import { ActHomeCard } from './act-home-card.component';
+import { type RhdFlagList, useRhdFlagLists } from '../rhd-flags/rhd-flag-lists.resource';
+import styles from './worklist-tiles.scss';
+
+const patientListsUrl = '${openmrsSpaBase}/home/patient-lists';
+
+function WorklistTile({ list }: { list: RhdFlagList }) {
+  const content = (
+    <div
+      data-testid="worklist-tile"
+      data-priority={list.priority}
+      className={`${styles.tile} ${styles[list.priority]}`}
+    >
+      <span className={styles.count}>{list.memberCount}</span>
+      <span className={styles.name}>{list.flagName}</span>
+    </div>
+  );
+  return list.cohortUuid ? (
+    <ConfigurableLink to={`${patientListsUrl}/${list.cohortUuid}`} className={styles.link}>
+      {content}
+    </ConfigurableLink>
+  ) : (
+    content
+  );
+}
+
+function Worklists() {
+  const { t } = useTranslation();
+  const { lists, isLoading, error } = useRhdFlagLists();
+  const riskFirst = [...lists.filter((l) => l.priority === 'risk'), ...lists.filter((l) => l.priority !== 'risk')];
+
+  return (
+    <ActHomeCard title={t('worklists', 'Worklists')} link={{ label: t('allLists', 'All lists'), to: patientListsUrl }}>
+      {error ? (
+        <InlineNotification
+          kind="error"
+          lowContrast
+          hideCloseButton
+          title={t('couldNotLoadWorklists', 'Could not load the worklists')}
+        />
+      ) : isLoading ? (
+        <div data-testid="worklists-loading">
+          <SkeletonText paragraph lineCount={3} />
+        </div>
+      ) : lists.length === 0 ? (
+        <p className={styles.empty}>{t('noRhdFlagLists', 'No RHD flag lists found')}</p>
+      ) : (
+        <div className={styles.tiles}>
+          {riskFirst.map((list) => (
+            <WorklistTile key={list.flagName} list={list} />
+          ))}
+        </div>
+      )}
+    </ActHomeCard>
+  );
+}
+
+export default function WorklistTiles() {
+  return (
+    <ScreenAccess screen="home">
+      <Worklists />
+    </ScreenAccess>
+  );
+}

package/src/act-home/worklist-tiles.scss

@@ -0,0 +1,50 @@
+@use '@carbon/colors';
+@use '@carbon/layout';
+@use '@carbon/type';
+@use '@openmrs/esm-styleguide/src/vars' as *;
+
+.tiles {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(11rem, 1fr));
+  gap: layout.$spacing-04;
+}
+
+.link {
+  color: inherit;
+  text-decoration: none;
+}
+
+.tile {
+  display: flex;
+  flex-direction: column;
+  gap: layout.$spacing-02;
+  height: 100%;
+  padding: layout.$spacing-04;
+  background-color: $ui-01;
+  border: 1px solid $ui-03;
+  border-top-width: layout.$spacing-02;
+}
+
+.link .tile:hover {
+  background-color: $ui-03;
+}
+
+.risk {
+  border-top-color: colors.$red-60;
+}
+
+.dataQuality {
+  border-top-color: colors.$orange-40;
+}
+
+.count {
+  @include type.type-style('heading-05');
+}
+
+.name {
+  @include type.type-style('body-compact-01');
+}
+
+.empty {
+  @include type.type-style('body-compact-01');
+}

package/src/act-home/worklist-tiles.test.tsx

@@ -0,0 +1,133 @@
+import React from 'react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { render, screen, within } from '@testing-library/react';
+import { homePrivilege, signInWith } from '../access/sign-in.test-helper';
+import { type RhdFlagList, useRhdFlagLists } from '../rhd-flags/rhd-flag-lists.resource';
+import WorklistTiles from './worklist-tiles.component';
+
+vi.mock('../rhd-flags/rhd-flag-lists.resource', () => ({ useRhdFlagLists: vi.fn() }));
+const mockUseRhdFlagLists = vi.mocked(useRhdFlagLists);
+
+const list = (flagName: string, memberCount: number, priority: RhdFlagList['priority'], cohortUuid: string | null) => ({
+  flagName,
+  memberCount,
+  priority,
+  cohortUuid,
+});
+
+const demoLists: Array<RhdFlagList> = [
+  list('RHD prophylaxis overdue', 4, 'risk', 'overdue'),
+  list('RHD lost to follow-up', 1, 'risk', 'lost'),
+  list('RHD prophylaxis not prescribed', 2, 'dataQuality', 'not-prescribed'),
+  list('RHD INR target missing', 2, 'dataQuality', 'inr'),
+  list('RHD 30-day follow-up due', 3, 'dataQuality', 'follow-up'),
+  list('RHD perfusion issues not recorded', 1, 'dataQuality', 'perfusion'),
+  list('RHD site infection not recorded', 1, 'dataQuality', 'infection'),
+  list('RHD bacterial sepsis not recorded', 2, 'dataQuality', 'sepsis'),
+  list('RHD delivery outcome overdue', 1, 'dataQuality', 'delivery'),
+  list('RHD death not recorded on patient', 0, 'dataQuality', 'death'),
+];
+
+function lists(value: Partial<ReturnType<typeof useRhdFlagLists>>) {
+  mockUseRhdFlagLists.mockReturnValue({ lists: [], isLoading: false, error: undefined, ...value });
+}
+
+describe('WorklistTiles', () => {
+  beforeEach(async () => {
+    window.getOpenmrsSpaBase = () => '/openmrs/spa/';
+    await signInWith([homePrivilege]);
+  });
+
+  it('shows one tile per list with its count, opening the list in Patient lists', () => {
+    lists({ lists: demoLists });
+
+    render(<WorklistTiles />);
+
+    const tiles = screen.getAllByTestId('worklist-tile');
+    expect(tiles.map((tile) => tile.textContent)).toEqual(demoLists.map((l) => `${l.memberCount}${l.flagName}`));
+    expect(screen.getByRole('link', { name: /RHD prophylaxis overdue/ })).toHaveAttribute(
+      'href',
+      '/openmrs/spa/home/patient-lists/overdue',
+    );
+    expect(screen.getByRole('link', { name: /all lists/i })).toHaveAttribute('href', '/openmrs/spa/home/patient-lists');
+  });
+
+  it('puts the risk lists first, each group in the order the lists come', () => {
+    lists({ lists: [demoLists[2], demoLists[0], demoLists[3], demoLists[1]] });
+
+    render(<WorklistTiles />);
+
+    expect(screen.getAllByTestId('worklist-tile').map((tile) => tile.textContent)).toEqual([
+      '4RHD prophylaxis overdue',
+      '1RHD lost to follow-up',
+      '2RHD prophylaxis not prescribed',
+      '2RHD INR target missing',
+    ]);
+  });
+
+  it('marks risk lists and missing data lists apart', () => {
+    lists({ lists: demoLists });
+
+    render(<WorklistTiles />);
+
+    const [overdue, , notPrescribed] = screen.getAllByTestId('worklist-tile');
+    expect(overdue).toHaveAttribute('data-priority', 'risk');
+    expect(notPrescribed).toHaveAttribute('data-priority', 'dataQuality');
+  });
+
+  it('shows 0 for a list with no members, still opening the list', () => {
+    lists({ lists: demoLists });
+
+    render(<WorklistTiles />);
+
+    expect(screen.getAllByTestId('worklist-tile').at(-1)).toHaveTextContent('0RHD death not recorded on patient');
+    expect(screen.getByRole('link', { name: /RHD death not recorded on patient/ })).toHaveAttribute(
+      'href',
+      '/openmrs/spa/home/patient-lists/death',
+    );
+  });
+
+  it('shows 0 without a link for a configured flag that has no list yet', () => {
+    lists({ lists: [list('RHD new flag', 0, 'dataQuality', null)] });
+
+    render(<WorklistTiles />);
+
+    expect(screen.getByTestId('worklist-tile')).toHaveTextContent('0RHD new flag');
+    expect(screen.queryByRole('link', { name: /RHD new flag/ })).not.toBeInTheDocument();
+  });
+
+  it('says so when there are no RHD flag lists', () => {
+    lists({ lists: [] });
+
+    render(<WorklistTiles />);
+
+    expect(screen.getByText('No RHD flag lists found')).toBeInTheDocument();
+    expect(screen.queryByTestId('worklist-tile')).not.toBeInTheDocument();
+  });
+
+  it('says so when the lists cannot be loaded', () => {
+    lists({ error: new Error('Server responded with 403') });
+
+    render(<WorklistTiles />);
+
+    expect(screen.getByText('Could not load the worklists')).toBeInTheDocument();
+    expect(screen.queryByTestId('worklist-tile')).not.toBeInTheDocument();
+  });
+
+  it('shows placeholders while the lists load', () => {
+    lists({ isLoading: true });
+
+    render(<WorklistTiles />);
+
+    expect(screen.getByTestId('worklists-loading')).toBeInTheDocument();
+  });
+
+  it('is hidden from a user without the ACT home privilege', async () => {
+    await signInWith(['View Patient Flags']);
+    lists({ lists: demoLists });
+
+    render(<WorklistTiles />);
+
+    expect(screen.queryByText('Worklists')).not.toBeInTheDocument();
+  });
+});