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

package/src/reports/report-dataset.resource.test.tsx

@@ -0,0 +1,189 @@
+import React from 'react';
+import { SWRConfig } from 'swr';
+import { describe, expect, it, vi } from 'vitest';
+import { renderHook, waitFor } from '@testing-library/react';
+import { openmrsFetch } from '@openmrs/esm-framework';
+import routes from '../routes.json';
+import { useReportDataset } from './report-dataset.resource';
+
+const mockOpenmrsFetch = vi.mocked(openmrsFetch);
+
+const waitingListUuid = '5b0f1c2e-9d3a-4c1b-8f6e-2a7d9e4b3c10';
+const columns = [
+  { name: 'patient_uuid', label: 'Patient', datatype: 'java.lang.String' },
+  { name: 'urgency', label: 'Urgency', datatype: 'java.lang.String' },
+];
+const rows = [{ patient_uuid: 'amina', urgency: '2: Urgent' }];
+
+function evaluated(datasetRows: Array<Record<string, unknown>>, datasetColumns = columns) {
+  return { uuid: waitingListUuid, dataSets: [{ metadata: { columns: datasetColumns }, rows: datasetRows }] };
+}
+
+function respond(byUrl: (url: string) => unknown) {
+  mockOpenmrsFetch.mockImplementation(((url: string) => {
+    const data = byUrl(url);
+    return data instanceof Error ? Promise.reject(data) : Promise.resolve({ data });
+  }) as never);
+}
+
+function renderDataset(report: string | null, params?: Record<string, string>, cache = new Map()) {
+  return renderHook(() => useReportDataset(report, params), {
+    wrapper: ({ children }) => <SWRConfig value={{ provider: () => cache, dedupingInterval: 0 }}>{children}</SWRConfig>,
+  });
+}
+
+describe('useReportDataset', () => {
+  it("evaluates the report with its parameters and returns the dataset's columns and rows", async () => {
+    respond(() => evaluated(rows));
+
+    const { result } = renderDataset(waitingListUuid, { startDate: '2026-01-01', clinic: 'Kitgum & Lira' });
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    expect(result.current).toMatchObject({ columns, rows, error: undefined });
+    const [url] = mockOpenmrsFetch.mock.calls.map(([url]) => url);
+    expect(url).toContain(`/reportingrest/reportdata/${waitingListUuid}?`);
+    expect(new URL(url, 'http://host').searchParams.get('clinic')).toBe('Kitgum & Lira');
+    expect(new URL(url, 'http://host').searchParams.get('startDate')).toBe('2026-01-01');
+  });
+
+  it('finds a report by its exact name among the reports whose names contain it', async () => {
+    respond((url) =>
+      url.includes('/reportDefinition')
+        ? {
+            results: [
+              { uuid: 'other-uuid', name: 'Procedural Waiting List (archived)' },
+              { uuid: waitingListUuid, name: 'Procedural Waiting List' },
+            ],
+          }
+        : evaluated(rows),
+    );
+
+    const { result } = renderDataset('Procedural Waiting List');
+
+    await waitFor(() => expect(result.current.rows).toEqual(rows));
+    const urls = mockOpenmrsFetch.mock.calls.map(([url]) => url);
+    expect(urls[0]).toContain('/reportingrest/reportDefinition?q=Procedural%20Waiting%20List');
+    expect(urls[1]).toContain(`/reportingrest/reportdata/${waitingListUuid}`);
+  });
+
+  it('finds the exact name on a later page of the search', async () => {
+    const hits = [
+      ...Array.from({ length: 50 }, (_, i) => ({ uuid: `archived-${i}`, name: `Procedural Waiting List ${i}` })),
+      { uuid: waitingListUuid, name: 'Procedural Waiting List' },
+    ];
+    respond((url) => {
+      if (!url.includes('/reportDefinition')) {
+        return evaluated(rows);
+      }
+      const start = Number(new URL(url, 'http://host').searchParams.get('startIndex'));
+      return { results: hits.slice(start, start + 50), totalCount: hits.length };
+    });
+
+    const { result } = renderDataset('Procedural Waiting List');
+
+    await waitFor(() => expect(result.current.rows).toEqual(rows));
+  });
+
+  it('says so when no report has the name', async () => {
+    respond(() => ({ results: [{ uuid: 'other-uuid', name: 'Procedural Waiting List (archived)' }] }));
+
+    const { result } = renderDataset('Procedural Waiting List');
+
+    await waitFor(() => expect(result.current.error?.message).toBe('No report is named "Procedural Waiting List"'));
+    expect(mockOpenmrsFetch.mock.calls.some(([url]) => url.includes('/reportdata/'))).toBe(false);
+  });
+
+  it('returns no columns and no rows for an empty dataset, as the server sends none', async () => {
+    respond(() => evaluated([], []));
+
+    const { result } = renderDataset(waitingListUuid);
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    expect(result.current).toMatchObject({ columns: [], rows: [], error: undefined });
+  });
+
+  it('returns the server error', async () => {
+    const serverError = Object.assign(new Error('Server responded with 500'), { response: { status: 500 } });
+    respond(() => serverError);
+
+    const { result } = renderDataset(waitingListUuid, { startDate: '2026-01-01' });
+
+    await waitFor(() => expect(result.current.error).toBe(serverError));
+    expect(result.current).toMatchObject({ columns: [], rows: [], isLoading: false });
+  });
+
+  it('does not evaluate a failing report again', async () => {
+    const serverError = Object.assign(new Error('Server responded with 500'), { response: { status: 500 } });
+    respond(() => serverError);
+
+    const { result } = renderHook(() => useReportDataset(waitingListUuid, { startDate: '' }), {
+      wrapper: ({ children }) => (
+        <SWRConfig value={{ provider: () => new Map(), errorRetryInterval: 1, errorRetryCount: 3 }}>
+          {children}
+        </SWRConfig>
+      ),
+    });
+
+    await waitFor(() => expect(result.current.error).toBe(serverError));
+    await new Promise((resolve) => setTimeout(resolve, 100));
+    expect(mockOpenmrsFetch).toHaveBeenCalledTimes(1);
+  });
+
+  it('evaluates the report once for the same parameters given in another order', async () => {
+    respond(() => evaluated(rows));
+
+    const { result } = renderHook(
+      () => [
+        useReportDataset(waitingListUuid, { startDate: '2026-01-01', endDate: '2026-12-31' }),
+        useReportDataset(waitingListUuid, { endDate: '2026-12-31', startDate: '2026-01-01' }),
+      ],
+      { wrapper: ({ children }) => <SWRConfig value={{ provider: () => new Map() }}>{children}</SWRConfig> },
+    );
+
+    await waitFor(() => expect(result.current.every((dataset) => dataset.rows.length === 1)).toBe(true));
+    expect(mockOpenmrsFetch).toHaveBeenCalledTimes(1);
+  });
+
+  it('evaluates the report again when its parameters change', async () => {
+    respond(() => evaluated(rows));
+
+    const { result, rerender } = renderHook(({ params }) => useReportDataset(waitingListUuid, params), {
+      initialProps: { params: { startDate: '2026-01-01' } },
+      wrapper: ({ children }) => <SWRConfig value={{ provider: () => new Map() }}>{children}</SWRConfig>,
+    });
+    await waitFor(() => expect(result.current.rows).toEqual(rows));
+    rerender({ params: { startDate: '2026-06-01' } });
+
+    await waitFor(() => expect(mockOpenmrsFetch).toHaveBeenCalledTimes(2));
+    expect(new URL(mockOpenmrsFetch.mock.calls[1][0], 'http://host').searchParams.get('startDate')).toBe('2026-06-01');
+  });
+
+  it('shows the cached rows when a screen mounts again, then evaluates the report again', async () => {
+    respond(() => evaluated(rows));
+    const cache = new Map();
+    const { result: firstMount, unmount } = renderDataset(waitingListUuid, {}, cache);
+    await waitFor(() => expect(firstMount.current.rows).toEqual(rows));
+    unmount();
+    const updatedRows = [{ patient_uuid: 'amina', urgency: '1: Emergency' }];
+    respond(() => evaluated(updatedRows));
+
+    const { result: secondMount } = renderDataset(waitingListUuid, {}, cache);
+
+    expect(secondMount.current).toMatchObject({ rows, isLoading: false });
+    await waitFor(() => expect(secondMount.current.rows).toEqual(updatedRows));
+    expect(mockOpenmrsFetch).toHaveBeenCalledTimes(2);
+  });
+
+  it('fetches nothing without a report', () => {
+    const { result } = renderDataset(null);
+
+    expect(result.current).toMatchObject({ columns: [], rows: [], isLoading: false });
+    expect(mockOpenmrsFetch).not.toHaveBeenCalled();
+  });
+});
+
+describe('routes.json', () => {
+  it('declares the reporting REST module the reports are evaluated through', () => {
+    expect(routes.backendDependencies).toHaveProperty('reportingrest');
+  });
+});

package/src/reports/report-dataset.resource.ts

@@ -0,0 +1,51 @@
+import useSWR from 'swr';
+import { openmrsFetch, restBaseUrl } from '@openmrs/esm-framework';
+import { fetchAll } from '../fetch-all';
+
+export interface ReportColumn {
+  name: string;
+  label: string;
+  datatype: string;
+}
+
+export type ReportRow = Record<string, unknown>;
+
+interface EvaluatedReport {
+  dataSets: Array<{ metadata: { columns: Array<ReportColumn> }; rows: Array<ReportRow> }>;
+}
+
+const uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/** reportDefinition?q matches names containing the text, so the exact name is picked from its hits. */
+async function findReportUuid(name: string) {
+  const definitions = await fetchAll<{ uuid: string; name: string }>(
+    `${restBaseUrl}/reportingrest/reportDefinition?q=${encodeURIComponent(name)}&v=custom:(uuid,name)`,
+  );
+  const report = definitions.find((definition) => definition.name === name);
+  if (!report) {
+    throw new Error(`No report is named "${name}"`);
+  }
+  return report.uuid;
+}
+
+async function evaluateReport(reportUuidOrName: string, params: Record<string, string>) {
+  const uuid = uuidPattern.test(reportUuidOrName) ? reportUuidOrName : await findReportUuid(reportUuidOrName);
+  const { data } = await openmrsFetch<EvaluatedReport>(
+    `${restBaseUrl}/reportingrest/reportdata/${uuid}?${new URLSearchParams(params)}`,
+  );
+  return data.dataSets[0];
+}
+
+/**
+ * Evaluates a report, given by uuid or by name, and returns its first dataset. A failure is not retried.
+ * The server sends `columns` only with rows, so an empty dataset has none and a screen defines its own headers.
+ */
+export function useReportDataset(reportUuidOrName: string | null, params: Record<string, string> = {}) {
+  const { data, error, isLoading } = useSWR(
+    reportUuidOrName ? ['rhd-report-dataset', reportUuidOrName, params] : null,
+    () => evaluateReport(reportUuidOrName, params),
+    { shouldRetryOnError: false },
+  );
+
+  return { columns: data?.metadata.columns ?? [], rows: data?.rows ?? [], isLoading, error };
+}

package/src/reports/report-date.test.ts

@@ -0,0 +1,18 @@
+import { describe, expect, it } from 'vitest';
+import { parseReportDate } from './report-date';
+
+describe('parseReportDate', () => {
+  it('reads an ISO string as its calendar day, whatever its offset', () => {
+    expect(parseReportDate('2026-10-15T00:00:00.000+0000')).toEqual(new Date(2026, 9, 15));
+    expect(parseReportDate('2026-10-15T23:00:00.000-0500')).toEqual(new Date(2026, 9, 15));
+  });
+
+  it('reads a Java-style array, whose month is 1-based', () => {
+    expect(parseReportDate([2026, 5, 1, 9, 0])).toEqual(new Date(2026, 4, 1));
+  });
+
+  it('gives null for an empty or unreadable value', () => {
+    expect(parseReportDate(null)).toBeNull();
+    expect(parseReportDate('soon')).toBeNull();
+  });
+});

package/src/reports/report-date.ts

@@ -0,0 +1,12 @@
+/**
+ * A date column's value as reporting REST sends it: an ISO string, or a Java-style array with a 1-based
+ * month. The date is read without its time or offset, so it shows the day the report recorded.
+ */
+export function parseReportDate(value: unknown): Date | null {
+  if (Array.isArray(value) && value.length >= 3) {
+    const [year, month, day] = value.map(Number);
+    return new Date(year, month - 1, day);
+  }
+  const match = typeof value === 'string' ? value.match(/^(\d{4})-(\d{2})-(\d{2})/) : null;
+  return match ? new Date(Number(match[1]), Number(match[2]) - 1, Number(match[3])) : null;
+}

package/src/rhd-flags/rhd-flag-lists.resource.test.tsx

@@ -0,0 +1,240 @@
+import React from 'react';
+import { SWRConfig } from 'swr';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { renderHook, waitFor } from '@testing-library/react';
+import { getDefaultsFromConfigSchema, openmrsFetch, useConfig } from '@openmrs/esm-framework';
+import { type Config, configSchema } from '../config-schema';
+import { listsForPatient, type RhdFlagList, useRhdFlagLists } from './rhd-flag-lists.resource';
+
+const mockOpenmrsFetch = vi.mocked(openmrsFetch);
+const mockUseConfig = vi.mocked(useConfig<Config>);
+
+const cohorts = [
+  { uuid: 'overdue', name: 'RHD prophylaxis overdue' },
+  { uuid: 'inr', name: 'RHD INR target missing' },
+  { uuid: 'new', name: 'RHD delivery outcome overdue' },
+  { uuid: 'other', name: 'HIV viral load due' },
+  { uuid: 'hand-made', name: 'Clinic RHD review' },
+  { uuid: 'deleted', name: 'RHD deleted flag', voided: true },
+];
+
+const members: Record<string, Array<{ patient: { uuid: string }; voided: boolean }>> = {
+  overdue: [
+    { patient: { uuid: 'amina' }, voided: false },
+    { patient: { uuid: 'peter' }, voided: false },
+    { patient: { uuid: 'voided' }, voided: true },
+  ],
+  inr: [{ patient: { uuid: 'peter' }, voided: false }],
+  new: [],
+  other: [{ patient: { uuid: 'amina' }, voided: false }],
+};
+
+function page<T>(results: Array<T>, url: string, pageSize = 50) {
+  const params = new URL(url, 'http://host').searchParams;
+  const start = Number(params.get('startIndex'));
+  const size = Math.min(pageSize, Number(params.get('limit') ?? pageSize));
+  return { results: results.slice(start, start + size), totalCount: results.length };
+}
+
+function respond({ pageSize = 50 } = {}) {
+  mockOpenmrsFetch.mockImplementation(((url: string) => {
+    const params = new URL(url, 'http://host').searchParams;
+    if (url.includes('/cohortm/cohortmember')) {
+      return Promise.resolve({ data: page(members[params.get('cohort')], url, pageSize) });
+    }
+    const q = params.get('q').toLowerCase();
+    return Promise.resolve({
+      data: page(
+        cohorts.filter((cohort) => cohort.name.toLowerCase().includes(q)),
+        url,
+        pageSize,
+      ),
+    });
+  }) as never);
+}
+
+function renderLists(cache = new Map(), options: { withMembers?: boolean } = {}) {
+  return renderHook(() => useRhdFlagLists(options), {
+    wrapper: ({ children }) => <SWRConfig value={{ provider: () => cache, dedupingInterval: 0 }}>{children}</SWRConfig>,
+  });
+}
+
+function useConfigWith(flagLists: Partial<Config['flagLists']> = {}) {
+  const defaults = getDefaultsFromConfigSchema(configSchema) as Config;
+  mockUseConfig.mockReturnValue({ ...defaults, flagLists: { ...defaults.flagLists, ...flagLists } });
+}
+
+function summary(lists: Array<RhdFlagList>) {
+  return lists.map(({ flagName, priority, memberCount, memberUuids, cohortUuid }) => ({
+    flagName,
+    priority,
+    memberCount,
+    members: memberUuids && [...memberUuids],
+    cohortUuid,
+  }));
+}
+
+describe('useRhdFlagLists', () => {
+  beforeEach(() => useConfigWith());
+
+  it('lists each list whose name has the prefix, with its current members and priority', async () => {
+    respond();
+
+    const { result } = renderLists(new Map(), { withMembers: true });
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    expect(result.current.error).toBeUndefined();
+    expect(summary(result.current.lists)).toEqual([
+      {
+        flagName: 'RHD prophylaxis overdue',
+        priority: 'risk',
+        memberCount: 2,
+        members: ['amina', 'peter'],
+        cohortUuid: 'overdue',
+      },
+      {
+        flagName: 'RHD INR target missing',
+        priority: 'dataQuality',
+        memberCount: 1,
+        members: ['peter'],
+        cohortUuid: 'inr',
+      },
+      {
+        flagName: 'RHD delivery outcome overdue',
+        priority: 'dataQuality',
+        memberCount: 0,
+        members: [],
+        cohortUuid: 'new',
+      },
+    ]);
+  });
+
+  it('counts each list with one small request when the members are not asked for', async () => {
+    respond();
+
+    const { result } = renderLists();
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    expect(
+      summary(result.current.lists).map(({ flagName, memberCount, members }) => [flagName, memberCount, members]),
+    ).toEqual([
+      ['RHD prophylaxis overdue', 3, undefined],
+      ['RHD INR target missing', 1, undefined],
+      ['RHD delivery outcome overdue', 0, undefined],
+    ]);
+    const memberUrls = mockOpenmrsFetch.mock.calls.map(([url]) => url).filter((url) => url.includes('/cohortm/'));
+    expect(memberUrls).toHaveLength(3);
+    expect(memberUrls.every((url) => url.includes('limit=1'))).toBe(true);
+  });
+
+  it('lists only the configured flags when names is set, with 0 for a flag that has no list yet', async () => {
+    useConfigWith({ names: ['HIV viral load due', 'RHD site infection not recorded', 'RHD delivery outcome'] });
+    respond();
+
+    const { result } = renderLists();
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    expect(
+      summary(result.current.lists).map(({ flagName, memberCount, cohortUuid }) => [flagName, memberCount, cohortUuid]),
+    ).toEqual([
+      ['HIV viral load due', 1, 'other'],
+      ['RHD site infection not recorded', 0, null],
+      ['RHD delivery outcome', 0, null],
+    ]);
+  });
+
+  it('reads every page, at the page size the server chooses', async () => {
+    respond({ pageSize: 1 });
+
+    const { result } = renderLists(new Map(), { withMembers: true });
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    expect(summary(result.current.lists).map(({ flagName, memberCount }) => [flagName, memberCount])).toEqual([
+      ['RHD prophylaxis overdue', 2],
+      ['RHD INR target missing', 1],
+      ['RHD delivery outcome overdue', 0],
+    ]);
+    expect(mockOpenmrsFetch.mock.calls.some(([url]) => url.includes('limit='))).toBe(false);
+    // One page each: 5 cohorts match the search; the lists' member rows take 3, 1 and 1 (an empty list is one page).
+    expect(mockOpenmrsFetch).toHaveBeenCalledTimes(5 + 3 + 1 + 1);
+  });
+
+  it('keeps the lists it has when a screen mounts again', async () => {
+    respond();
+    const cache = new Map();
+
+    const { result: firstMount, unmount } = renderLists(cache);
+    await waitFor(() => expect(firstMount.current.lists).toHaveLength(3));
+    const requests = mockOpenmrsFetch.mock.calls.length;
+    unmount();
+    const { result: secondMount } = renderLists(cache);
+
+    expect(secondMount.current.lists).toHaveLength(3);
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    expect(mockOpenmrsFetch).toHaveBeenCalledTimes(requests);
+  });
+
+  it('fetches the members for a screen that asks for them after one that counted', async () => {
+    respond();
+    const cache = new Map();
+
+    const { result: counted } = renderLists(cache);
+    await waitFor(() => expect(counted.current.lists).toHaveLength(3));
+    const { result: withMembers } = renderLists(cache, { withMembers: true });
+
+    await waitFor(() => expect(withMembers.current.lists[0]?.memberUuids).toEqual(new Set(['amina', 'peter'])));
+  });
+
+  it('stops reading members when a first page is empty though the server reports a total', async () => {
+    mockOpenmrsFetch.mockImplementation(((url: string) =>
+      Promise.resolve({
+        data: url.includes('/cohortm/cohortmember')
+          ? { results: [], totalCount: 5 }
+          : { results: cohorts.slice(0, 1), totalCount: 1 },
+      })) as never);
+
+    const { result } = renderLists(new Map(), { withMembers: true });
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    expect(summary(result.current.lists).map(({ memberCount, members }) => [memberCount, members])).toEqual([[0, []]]);
+  });
+
+  it('is loading until the lists arrive', () => {
+    mockOpenmrsFetch.mockReturnValue(new Promise(() => {}) as never);
+
+    const { result } = renderLists();
+
+    expect(result.current.isLoading).toBe(true);
+    expect(result.current.lists).toEqual([]);
+  });
+
+  it('reports a failed request', async () => {
+    const serverError = Object.assign(new Error('Server responded with 500'), { response: { status: 500 } });
+    respond();
+    mockOpenmrsFetch.mockImplementation(((url: string) =>
+      url.includes('/cohortm/cohortmember')
+        ? Promise.reject(serverError)
+        : Promise.resolve({ data: { results: cohorts, totalCount: cohorts.length } })) as never);
+
+    const { result } = renderLists();
+
+    await waitFor(() => expect(result.current.error).toBe(serverError));
+    expect(result.current.lists).toEqual([]);
+  });
+});
+
+describe('listsForPatient', () => {
+  it('names the lists the patient is on', () => {
+    const list = (flagName: string, memberUuids: Array<string>): RhdFlagList => ({
+      cohortUuid: flagName,
+      flagName,
+      priority: 'dataQuality',
+      memberCount: memberUuids.length,
+      memberUuids: new Set(memberUuids),
+    });
+    const lists = [list('RHD a', ['amina', 'peter']), list('RHD b', ['peter'])];
+
+    expect(listsForPatient(lists, 'amina').map((l) => l.flagName)).toEqual(['RHD a']);
+    expect(listsForPatient(lists, 'nobody')).toEqual([]);
+  });
+});

package/src/rhd-flags/rhd-flag-lists.resource.ts

@@ -0,0 +1,88 @@
+import useSWR from 'swr';
+import { openmrsFetch, restBaseUrl, useConfig } from '@openmrs/esm-framework';
+import { type Config } from '../config-schema';
+import { fetchAll } from '../fetch-all';
+
+/** The patient list rhdflags keeps for one flag, with the patients on it now. */
+export interface RhdFlagList {
+  cohortUuid: string | null;
+  flagName: string;
+  priority: 'risk' | 'dataQuality';
+  memberCount: number;
+  /** Present when the lists were asked for with their members. */
+  memberUuids?: ReadonlySet<string>;
+}
+
+/** Lists are read as cohorts: the flags themselves are readable only with privileges that run SQL. */
+function searchLists(text: string) {
+  return fetchAll<{ uuid: string; name: string; voided: boolean }>(
+    `${restBaseUrl}/cohort?q=${encodeURIComponent(text)}&v=custom:(uuid,name,voided)`,
+  ).then((lists) => lists.filter((list) => !list.voided));
+}
+
+/** Counts memberships that have not ended; the count also takes in memberships voided along with their patient. */
+async function countMembers(cohortUuid: string) {
+  const { data } = await openmrsFetch<{ totalCount: number }>(
+    `${restBaseUrl}/cohortm/cohortmember?cohort=${cohortUuid}&v=custom:(uuid)&limit=1&totalCount=true`,
+  );
+  return data.totalCount;
+}
+
+/** The cohort module returns only memberships that have not ended. */
+async function fetchMemberUuids(cohortUuid: string) {
+  const members = await fetchAll<{ patient: { uuid: string }; voided: boolean }>(
+    `${restBaseUrl}/cohortm/cohortmember?cohort=${cohortUuid}&v=custom:(patient:(uuid),voided)`,
+  );
+  return new Set(members.filter((member) => !member.voided).map((member) => member.patient.uuid));
+}
+
+/** Whether the flag is one of the configured RHD flags: named in names, or else starting with namePrefix. */
+export function isListedFlag({ names, namePrefix }: Config['flagLists'], flagName: string) {
+  return names.length ? names.includes(flagName) : flagName.startsWith(namePrefix);
+}
+
+export function flagPriority({ riskFlags }: Config['flagLists'], flagName: string): RhdFlagList['priority'] {
+  return riskFlags.includes(flagName) ? 'risk' : 'dataQuality';
+}
+
+async function findLists(flagLists: Config['flagLists']) {
+  const { names, namePrefix } = flagLists;
+  if (names.length) {
+    const found = await Promise.all(names.map(async (name) => (await searchLists(name)).find((l) => l.name === name)));
+    return names.map((name, i) => ({ name, uuid: found[i]?.uuid ?? null }));
+  }
+  return (await searchLists(namePrefix)).filter((list) => isListedFlag(flagLists, list.name));
+}
+
+/**
+ * The configured RHD flag lists, each with its current patient count, and its patients when `withMembers` is set.
+ * The cohort module loads a whole list on the server for every page it returns, so ask for members only where needed.
+ */
+export function useRhdFlagLists({ withMembers = false } = {}) {
+  const { flagLists } = useConfig<Config>();
+  const { data, error, isLoading } = useSWR<Array<RhdFlagList>, Error>(
+    ['rhd-flag-lists', flagLists, withMembers],
+    async () => {
+      const lists = await findLists(flagLists);
+      return Promise.all(
+        lists.map(async (list): Promise<RhdFlagList> => {
+          const common = { cohortUuid: list.uuid, flagName: list.name, priority: flagPriority(flagLists, list.name) };
+          if (!withMembers) {
+            return { ...common, memberCount: list.uuid ? await countMembers(list.uuid) : 0 };
+          }
+          const memberUuids = list.uuid ? await fetchMemberUuids(list.uuid) : new Set<string>();
+          return { ...common, memberCount: memberUuids.size, memberUuids };
+        }),
+      );
+    },
+    // rhdflags updates the lists daily, so a screen mounting again reuses the cached lists.
+    { revalidateIfStale: false },
+  );
+
+  return { lists: data ?? [], isLoading, error };
+}
+
+/** The lists the patient is on now, among lists fetched with their members. */
+export function listsForPatient(lists: Array<RhdFlagList>, patientUuid: string) {
+  return lists.filter((list) => list.memberUuids?.has(patientUuid));
+}

package/src/routes.json

@@ -0,0 +1,66 @@
+{
+  "$schema": "https://json.openmrs.org/routes.schema.json",
+  "backendDependencies": {
+    "webservices.rest": ">=2.40.0",
+    "rhdflags": ">=1.0.0-SNAPSHOT",
+    "cohort": ">=3.7.3",
+    "reportingrest": ">=2.0.0"
+  },
+  "extensions": [
+    {
+      "name": "act-home-dashboard-link",
+      "slot": "homepage-dashboard-slot",
+      "component": "actHomeDashboardLink",
+      "meta": {
+        "name": "act-home",
+        "slot": "rhd-home-dashboard-slot",
+        "title": "actHome"
+      }
+    },
+    {
+      "name": "act-home-dashboard",
+      "slot": "rhd-home-dashboard-slot",
+      "component": "actHomeDashboard"
+    },
+    {
+      "name": "act-home-quick-actions",
+      "slot": "rhd-home-widgets-slot",
+      "component": "actHomeQuickActions",
+      "order": 1
+    },
+    {
+      "name": "act-home-worklists",
+      "slot": "rhd-home-widgets-slot",
+      "component": "actHomeWorklists",
+      "order": 2
+    },
+    {
+      "name": "act-home-care-cascade",
+      "slot": "rhd-home-widgets-slot",
+      "component": "actHomeCareCascade",
+      "order": 4
+    },
+    {
+      "name": "act-registry-dashboard-link",
+      "slot": "homepage-dashboard-slot",
+      "component": "registryDashboardLink",
+      "meta": {
+        "name": "act-registry",
+        "slot": "rhd-registry-dashboard-slot",
+        "title": "registry"
+      }
+    },
+    {
+      "name": "act-registry-dashboard",
+      "slot": "rhd-registry-dashboard-slot",
+      "component": "registryDashboard"
+    }
+  ],
+  "workspaces2": [
+    {
+      "name": "rhd-flag-gaps-workspace",
+      "component": "flagGapsWorkspace",
+      "window": "patient-chart-clinical-forms"
+    }
+  ]
+}