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

package/src/registry/registry-filters.ts

@@ -0,0 +1,81 @@
+import { useEffect, useState } from 'react';
+import { type ReportRow } from '../reports/report-dataset.resource';
+
+export interface RegistryFilters {
+  status: string;
+  cardiac: string;
+  primaryCare: string;
+  category: string;
+  bpg: string;
+  q: string;
+}
+
+const keys: Array<keyof RegistryFilters> = ['status', 'cardiac', 'primaryCare', 'category', 'bpg', 'q'];
+
+function fromUrl(): RegistryFilters {
+  const params = new URLSearchParams(window.location.search);
+  return Object.fromEntries(keys.map((key) => [key, params.get(key) ?? ''])) as unknown as RegistryFilters;
+}
+
+/** The registry's filters, kept in the page's URL so a view can be bookmarked. */
+export function useRegistryFilters() {
+  const [filters, setFilters] = useState(fromUrl);
+
+  // The URL follows the filters a moment after typing stops, as each write reroutes every single-spa app.
+  useEffect(() => {
+    const timer = setTimeout(() => {
+      const params = new URLSearchParams(window.location.search);
+      keys.forEach((key) => (filters[key] ? params.set(key, filters[key]) : params.delete(key)));
+      const url = `${window.location.pathname}${params.size ? `?${params}` : ''}`;
+      if (url !== `${window.location.pathname}${window.location.search}`) {
+        window.history.replaceState(window.history.state, '', url);
+      }
+    }, 300);
+    return () => clearTimeout(timer);
+  }, [filters]);
+
+  // Following the Registry link again resets its URL, and with it the filters.
+  useEffect(() => {
+    // Other apps' URL changes reach here too; filters that are unchanged keep the page where it is.
+    const reread = () =>
+      setFilters((current) => {
+        const next = fromUrl();
+        return keys.every((key) => current[key] === next[key]) ? current : next;
+      });
+    window.addEventListener('popstate', reread);
+    return () => window.removeEventListener('popstate', reread);
+  }, []);
+
+  const update = (change: Partial<RegistryFilters>) => setFilters((current) => ({ ...current, ...change }));
+  return [filters, update] as const;
+}
+
+export function filterRegistry(rows: Array<ReportRow>, filters: RegistryFilters) {
+  const q = filters.q.trim().toLowerCase();
+  return rows.filter(
+    (row) =>
+      (!filters.status || row.enrollment_status === filters.status) &&
+      (!filters.cardiac || row.cardiac_clinic === filters.cardiac) &&
+      (!filters.primaryCare || row.primary_care_clinic === filters.primaryCare) &&
+      (!filters.category || row.diagnosis_category === filters.category) &&
+      (!filters.bpg || row.bpg_status === filters.bpg) &&
+      (!q ||
+        [row.full_name, row.rhd_id].some((value) =>
+          String(value ?? '')
+            .toLowerCase()
+            .includes(q),
+        )),
+  );
+}
+
+/** The distinct values a column takes, sorted, for a filter's options. */
+export function distinctValues(rows: Array<ReportRow>, column: string) {
+  return [
+    ...new Set(
+      rows
+        .map((row) => row[column])
+        .filter(Boolean)
+        .map(String),
+    ),
+  ].sort();
+}

package/src/registry/registry-flags.test.tsx

@@ -0,0 +1,67 @@
+import React from 'react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { render, screen, within } from '@testing-library/react';
+import { signInWith } from '../access/sign-in.test-helper';
+import { useReportDataset } from '../reports/report-dataset.resource';
+import { registryRows } from './registry.fixture';
+import Registry from './registry.component';
+
+vi.mock('../reports/report-dataset.resource', () => ({ useReportDataset: vi.fn() }));
+
+const flaggedRows = registryRows.map((row, i) => ({
+  ...row,
+  rhd_flags: ['RHD INR target missing|RHD prophylaxis overdue', 'RHD prophylaxis overdue', null][i] ?? null,
+}));
+
+function flagsOf(name: string) {
+  return within(screen.getByRole('row', { name: new RegExp(`${name}\\b`) }))
+    .queryAllByTestId('registry-flag')
+    .map((tag) => [tag.textContent, tag.getAttribute('data-priority'), tag.className.includes('cds--tag--red')]);
+}
+
+describe('Registry flags column', () => {
+  beforeEach(async () => {
+    window.getOpenmrsSpaBase = () => '/openmrs/spa/';
+    window.history.replaceState(null, '', '/openmrs/spa/home/act-registry');
+    await signInWith(['View Patient Flags']);
+    vi.mocked(useReportDataset).mockReturnValue({ columns: [], rows: flaggedRows, isLoading: false, error: undefined });
+  });
+
+  it("shows each patient's RHD flags from the report, risk flags red and missing data flags orange", () => {
+    render(<Registry />);
+
+    expect(screen.getAllByRole('columnheader').map((header) => header.textContent)).toContain('Flags');
+    expect(flagsOf('Patient 1')).toEqual([
+      ['RHD INR target missing', 'dataQuality', false],
+      ['RHD prophylaxis overdue', 'risk', true],
+    ]);
+    expect(flagsOf('Patient 2')).toEqual([['RHD prophylaxis overdue', 'risk', true]]);
+    expect(flagsOf('Patient 3')).toEqual([]);
+  });
+
+  it.each([
+    ['names', { namePrefix: 'RHD ', names: ['RHD prophylaxis overdue'] }],
+    ['namePrefix', { namePrefix: 'RHD prophylaxis', names: [] }],
+  ])('shows only the flags the configuration selects by %s', async (_, selection) => {
+    await signInWith(['View Patient Flags'], {
+      flagLists: { riskFlags: ['RHD prophylaxis overdue'], ...selection },
+    });
+
+    render(<Registry />);
+
+    expect(flagsOf('Patient 1')).toEqual([['RHD prophylaxis overdue', 'risk', true]]);
+  });
+
+  it('takes the risk flags from the configuration', async () => {
+    await signInWith(['View Patient Flags'], {
+      flagLists: { namePrefix: 'RHD ', names: [], riskFlags: ['RHD INR target missing'] },
+    });
+
+    render(<Registry />);
+
+    expect(flagsOf('Patient 1')).toEqual([
+      ['RHD INR target missing', 'risk', true],
+      ['RHD prophylaxis overdue', 'dataQuality', false],
+    ]);
+  });
+});

package/src/registry/registry.component.tsx

@@ -0,0 +1,255 @@
+import React, { useEffect, useMemo, useState } from 'react';
+import dayjs from 'dayjs';
+import { useTranslation } from 'react-i18next';
+import {
+  Button,
+  DataTableSkeleton,
+  InlineNotification,
+  Pagination,
+  Search,
+  Select,
+  SelectItem,
+  Table,
+  Tag,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from '@carbon/react';
+import { ConfigurableLink, formatDate, navigate, useConfig, usePagination } from '@openmrs/esm-framework';
+import { type Config } from '../config-schema';
+import { useScreenAccess } from '../access/screen-access.component';
+import { flagPriority, isListedFlag } from '../rhd-flags/rhd-flag-lists.resource';
+import { useReportDataset, type ReportRow } from '../reports/report-dataset.resource';
+import { parseReportDate } from '../reports/report-date';
+import { downloadCsv } from './csv';
+import { distinctValues, filterRegistry, useRegistryFilters } from './registry-filters';
+import styles from './registry.scss';
+
+const pageSizes = [25, 50, 100];
+
+const chartUrl = (row: ReportRow) => '${openmrsSpaBase}' + `/patient/${row.patient_uuid}/chart`;
+
+function nextConsultation(row: ReportRow) {
+  const date = parseReportDate(row.next_consultation_date);
+  return date ? formatDate(date, { time: false, noToday: true }) : '';
+}
+
+function RegistryTable() {
+  const { t } = useTranslation();
+  const { registry, flagLists } = useConfig<Config>();
+  const params = useMemo(() => ({ startDate: '1900-01-01', endDate: dayjs().format('YYYY-MM-DD') }), []);
+  // Coming back from a chart paints the cached rows, then evaluates the report again for what the chart changed.
+  const { rows, isLoading, error } = useReportDataset(registry.report, params);
+  const [filters, setFilters] = useRegistryFilters();
+  // A BPG status in the URL has no filter to clear it while the setting is off, so it is not applied.
+  const shown = useMemo(
+    () => filterRegistry(rows, registry.showBpgColumns ? filters : { ...filters, bpg: '' }),
+    [rows, filters, registry.showBpgColumns],
+  );
+  const [pageSize, setPageSize] = useState(pageSizes[0]);
+  const { results, currentPage, goTo } = usePagination(shown, pageSize);
+  // A change of filters, chosen here or by following the Registry link again, starts from the first page.
+  useEffect(() => goTo(1), [filters, goTo]);
+  const filterSelect = (id: string, label: string, value: string, options: Array<string>, key: string) => (
+    <Select id={id} labelText={label} value={value} onChange={(event) => setFilters({ [key]: event.target.value })}>
+      <SelectItem value="" text={t('all', 'All')} />
+      {/* A value from a bookmarked URL that no longer matches still shows, so it can be cleared. */}
+      {[...options, ...(value && !options.includes(value) ? [value] : [])].map((option) => (
+        <SelectItem key={option} value={option} text={option} />
+      ))}
+    </Select>
+  );
+  // The report lists the flags whose patient lists each patient is on, separated by |; the configured ones show.
+  const flagsOf = (row: ReportRow) =>
+    String(row.rhd_flags ?? '')
+      .split('|')
+      .filter((flagName) => flagName && isListedFlag(flagLists, flagName))
+      .map((flagName) => ({ flagName, priority: flagPriority(flagLists, flagName) }));
+  const text = (column: string) => (row: ReportRow) => String(row[column] ?? '');
+  const columns: Array<{
+    header: string;
+    text: (row: ReportRow) => string;
+    render?: (row: ReportRow) => React.ReactNode;
+  }> = [
+    {
+      header: t('name', 'Name'),
+      text: text('full_name'),
+      render: (row) => <ConfigurableLink to={chartUrl(row)}>{String(row.full_name ?? '')}</ConfigurableLink>,
+    },
+    { header: t('actId', 'ACT ID'), text: text('rhd_id') },
+    { header: t('age', 'Age'), text: text('age_years') },
+    { header: t('sex', 'Sex'), text: text('sex') },
+    { header: t('diagnosisCategory', 'Diagnosis category'), text: text('diagnosis_category') },
+    { header: t('prophylaxisRegimen', 'Prophylaxis regimen'), text: text('prophylaxis_regimen') },
+    { header: t('nextConsultation', 'Next consultation'), text: nextConsultation },
+    ...(registry.showBpgColumns
+      ? [
+          { header: t('bpgStatus', 'BPG status'), text: text('bpg_status') },
+          {
+            header: t('adherence', 'Adherence'),
+            text: (row: ReportRow) => (row.adherence == null ? '' : `${row.adherence}%`),
+          },
+        ]
+      : []),
+    {
+      header: t('flags', 'Flags'),
+      text: (row) =>
+        flagsOf(row)
+          .map((list) => list.flagName)
+          .join('; '),
+      render: (row) =>
+        flagsOf(row).map((list) => (
+          <Tag
+            key={list.flagName}
+            data-testid="registry-flag"
+            data-priority={list.priority}
+            type={list.priority === 'risk' ? 'red' : 'warm-gray'}
+            className={styles[list.priority]}
+            size="sm"
+          >
+            {list.flagName}
+          </Tag>
+        )),
+    },
+  ];
+
+  if (error) {
+    return (
+      <InlineNotification
+        kind="error"
+        lowContrast
+        hideCloseButton
+        title={t('couldNotLoadRegistry', 'Could not load the registry')}
+      />
+    );
+  }
+  if (isLoading) {
+    return (
+      <div data-testid="registry-loading">
+        <DataTableSkeleton columnCount={columns.length} showHeader={false} showToolbar={false} />
+      </div>
+    );
+  }
+  if (!rows.length) {
+    return <p className={styles.message}>{t('noRegistryPatients', 'No patients are enrolled in the registry.')}</p>;
+  }
+  return (
+    <>
+      <div className={styles.filters}>
+        <Search
+          labelText={t('searchRegistry', 'Search by name or ACT ID')}
+          placeholder={t('searchRegistry', 'Search by name or ACT ID')}
+          value={filters.q}
+          onChange={(event) => setFilters({ q: event.target.value })}
+        />
+        {filterSelect(
+          'registry-status',
+          t('status', 'Status'),
+          filters.status,
+          distinctValues(rows, 'enrollment_status'),
+          'status',
+        )}
+        {filterSelect(
+          'registry-cardiac',
+          t('cardiacClinic', 'Cardiac clinic'),
+          filters.cardiac,
+          distinctValues(rows, 'cardiac_clinic'),
+          'cardiac',
+        )}
+        {filterSelect(
+          'registry-primary-care',
+          t('primaryCareClinic', 'Primary care clinic'),
+          filters.primaryCare,
+          distinctValues(rows, 'primary_care_clinic'),
+          'primaryCare',
+        )}
+        {filterSelect(
+          'registry-category',
+          t('categoryAtDiagnosis', 'Category at diagnosis'),
+          filters.category,
+          distinctValues(rows, 'diagnosis_category'),
+          'category',
+        )}
+        {registry.showBpgColumns &&
+          filterSelect(
+            'registry-bpg',
+            t('bpgStatus', 'BPG status'),
+            filters.bpg,
+            distinctValues(rows, 'bpg_status'),
+            'bpg',
+          )}
+      </div>
+      <div className={styles.actions}>
+        <Button
+          kind="tertiary"
+          size="sm"
+          disabled={!shown.length}
+          onClick={() =>
+            downloadCsv(
+              `registry-${dayjs().format('YYYY-MM-DD')}.csv`,
+              columns.map((column) => column.header),
+              shown.map((row) => columns.map((column) => column.text(row))),
+            )
+          }
+        >
+          {t('downloadCsv', 'Download CSV')}
+        </Button>
+      </div>
+      {shown.length ? (
+        <Table>
+          <TableHead>
+            <TableRow>
+              {columns.map((column) => (
+                <TableHeader key={column.header}>{column.header}</TableHeader>
+              ))}
+            </TableRow>
+          </TableHead>
+          <TableBody>
+            {results.map((row) => (
+              <TableRow
+                key={String(row.patient_uuid)}
+                className={styles.row}
+                onClick={(event) => (event.target as HTMLElement).closest('a') || navigate({ to: chartUrl(row) })}
+              >
+                {columns.map((column) => (
+                  <TableCell key={column.header}>{column.render ? column.render(row) : column.text(row)}</TableCell>
+                ))}
+              </TableRow>
+            ))}
+          </TableBody>
+        </Table>
+      ) : (
+        <p className={styles.message}>{t('noRegistryMatches', 'No patients match these filters.')}</p>
+      )}
+      {shown.length > 0 && (
+        <Pagination
+          page={currentPage}
+          pageSize={pageSize}
+          pageSizes={pageSizes}
+          totalItems={shown.length}
+          onChange={({ page, pageSize: size }) => {
+            setPageSize(size);
+            goTo(page);
+          }}
+        />
+      )}
+    </>
+  );
+}
+
+export default function Registry() {
+  const { t } = useTranslation();
+  const canSeeRegistry = useScreenAccess('registry');
+
+  if (!canSeeRegistry) {
+    return <p className={styles.message}>{t('noAccessToRegistry', 'You do not have access to the registry.')}</p>;
+  }
+  return (
+    <div className={styles.registry}>
+      <h1 className={styles.title}>{t('registry', 'Registry')}</h1>
+      <RegistryTable />
+    </div>
+  );
+}

package/src/registry/registry.fixture.ts

@@ -0,0 +1,14 @@
+/** Rows shaped as the RHD Patient List report returns them. */
+export const registryRows = Array.from({ length: 30 }, (_, i) => ({
+  rhd_id: `rhd${String(i + 1).padStart(5, '0')}`,
+  full_name: `Patient ${i + 1}`,
+  sex: i % 2 ? 'M' : 'F',
+  age_years: 10 + i,
+  enrollment_status: i === 3 ? 'Completed' : 'Active',
+  diagnosis_category: ['RHD A', 'RHD B', 'RHD C'][i % 3],
+  prophylaxis_regimen: i === 1 ? 'Oral penicillin V' : 'Q28 day BPG',
+  next_consultation_date: i === 0 ? '2026-10-15T00:00:00.000+0000' : null,
+  cardiac_clinic: i % 2 ? 'Gulu RRH' : 'Lira RRH',
+  primary_care_clinic: i % 2 ? 'Anyeke HCIV' : null,
+  patient_uuid: `patient-${i + 1}`,
+}));

package/src/registry/registry.meta.ts

@@ -0,0 +1,6 @@
+/** The home app finds this dashboard by `name` (the URL after /home/) and renders its `slot`. */
+export const registryDashboardMeta = {
+  name: 'act-registry',
+  slot: 'rhd-registry-dashboard-slot',
+  title: 'registry',
+};

package/src/registry/registry.scss

@@ -0,0 +1,41 @@
+@use '@carbon/colors';
+@use '@carbon/layout';
+@use '@carbon/type';
+
+.registry {
+  padding: layout.$spacing-07 layout.$spacing-07 layout.$spacing-09;
+}
+
+.title {
+  @include type.type-style('heading-05');
+  margin-bottom: layout.$spacing-06;
+}
+
+.row {
+  cursor: pointer;
+}
+
+.message {
+  @include type.type-style('body-01');
+  padding: layout.$spacing-05;
+}
+
+.filters {
+  display: grid;
+  grid-template-columns: 2fr repeat(4, 1fr);
+  gap: layout.$spacing-05;
+  align-items: end;
+  margin-bottom: layout.$spacing-05;
+}
+
+// Carbon has no orange tag, so missing data flags are drawn in Carbon's orange here.
+.dataQuality {
+  background-color: colors.$orange-10;
+  color: colors.$orange-70;
+}
+
+.actions {
+  display: flex;
+  justify-content: flex-end;
+  margin-bottom: layout.$spacing-05;
+}

package/src/registry/registry.test.tsx

@@ -0,0 +1,147 @@
+import React from 'react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { render, screen, within } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { navigate } from '@openmrs/esm-framework';
+import { signInWith } from '../access/sign-in.test-helper';
+import { useReportDataset } from '../reports/report-dataset.resource';
+import { registryRows } from './registry.fixture';
+import Registry from './registry.component';
+
+vi.mock('../reports/report-dataset.resource', () => ({ useReportDataset: vi.fn() }));
+const mockUseReportDataset = vi.mocked(useReportDataset);
+
+function dataset(value: Partial<ReturnType<typeof useReportDataset>>) {
+  mockUseReportDataset.mockReturnValue({ columns: [], rows: [], isLoading: false, error: undefined, ...value });
+}
+
+const registryPrivilege = 'View Patient Flags';
+
+describe('Registry', () => {
+  beforeEach(async () => {
+    window.getOpenmrsSpaBase = () => '/openmrs/spa/';
+    await signInWith([registryPrivilege]);
+  });
+
+  it("lists the report's patients with their name, ACT ID, age, sex, diagnosis, regimen and next consultation", () => {
+    dataset({ rows: registryRows });
+
+    render(<Registry />);
+
+    const headers = screen.getAllByRole('columnheader').map((header) => header.textContent);
+    expect(headers).toEqual([
+      'Name',
+      'ACT ID',
+      'Age',
+      'Sex',
+      'Diagnosis category',
+      'Prophylaxis regimen',
+      'Next consultation',
+      'Flags',
+    ]);
+    const first = screen.getByRole('row', { name: /Patient 1\b/ });
+    expect(
+      within(first)
+        .getAllByRole('cell')
+        .map((cell) => cell.textContent),
+    ).toEqual(['Patient 1', 'rhd00001', '10', 'F', 'RHD A', 'Q28 day BPG', '15-Oct-2026', '']);
+  });
+
+  it('evaluates the configured report over every enrolment up to today', () => {
+    vi.useFakeTimers({ now: new Date(2026, 8, 29, 10) });
+    dataset({ rows: registryRows });
+
+    render(<Registry />);
+
+    vi.useRealTimers();
+    expect(mockUseReportDataset).toHaveBeenLastCalledWith('f1a2b3c4-d5e6-7890-abcd-ef1234567890', {
+      startDate: '1900-01-01',
+      endDate: '2026-09-29',
+    });
+  });
+
+  it('shows the patients a page at a time', async () => {
+    dataset({ rows: registryRows });
+
+    render(<Registry />);
+
+    expect(screen.getAllByRole('row')).toHaveLength(1 + 25);
+    await userEvent.click(screen.getByRole('button', { name: /next page/i }));
+    expect(screen.getAllByRole('row')).toHaveLength(1 + 5);
+    expect(screen.getByRole('row', { name: /Patient 30\b/ })).toBeInTheDocument();
+  });
+
+  it("opens a patient's chart from their row", async () => {
+    dataset({ rows: registryRows });
+
+    render(<Registry />);
+
+    await userEvent.click(screen.getByRole('row', { name: /Patient 2\b/ }));
+    expect(vi.mocked(navigate)).toHaveBeenCalledWith({ to: '${openmrsSpaBase}/patient/patient-2/chart' });
+  });
+
+  it('offers larger pages, and shows as many rows as the page size chosen', async () => {
+    dataset({ rows: registryRows });
+
+    render(<Registry />);
+
+    await userEvent.selectOptions(screen.getByLabelText(/items per page/i), '50');
+    expect(screen.getAllByRole('row')).toHaveLength(1 + 30);
+  });
+
+  it("opens a patient's chart once when their name is clicked", async () => {
+    dataset({ rows: registryRows });
+
+    render(<Registry />);
+
+    await userEvent.click(screen.getByRole('link', { name: 'Patient 2' }));
+    expect(vi.mocked(navigate)).toHaveBeenCalledTimes(0);
+  });
+
+  it("links each patient's name to their chart, for keyboard and new-tab use", () => {
+    dataset({ rows: registryRows });
+
+    render(<Registry />);
+
+    expect(screen.getByRole('link', { name: 'Patient 2' })).toHaveAttribute(
+      'href',
+      '/openmrs/spa/patient/patient-2/chart',
+    );
+  });
+
+  it('says so when no patient is enrolled', () => {
+    dataset({ rows: [] });
+
+    render(<Registry />);
+
+    expect(screen.getByText('No patients are enrolled in the registry.')).toBeInTheDocument();
+  });
+
+  it('says so when the report cannot be loaded', () => {
+    dataset({ error: new Error('Server responded with 404') });
+
+    render(<Registry />);
+
+    expect(screen.getByText('Could not load the registry')).toBeInTheDocument();
+  });
+
+  it('shows a placeholder while the report runs', () => {
+    dataset({ isLoading: true });
+
+    render(<Registry />);
+
+    expect(screen.getByTestId('registry-loading')).toBeInTheDocument();
+  });
+
+  it('tells a user without the registry privilege that they cannot see it', async () => {
+    await signInWith(['Get Patients'], {
+      screenPrivileges: { home: 'x', registry: 'App: act.registry', waitingList: 'x', screenPositive: 'x' },
+    });
+    dataset({ rows: registryRows });
+
+    render(<Registry />);
+
+    expect(screen.getByText('You do not have access to the registry.')).toBeInTheDocument();
+    expect(screen.queryByRole('table')).not.toBeInTheDocument();
+  });
+});