@pih/esm-audit-app 2.1.0

package/src/audit/patient-activity.component.test.tsx

@@ -0,0 +1,191 @@
+import React from 'react';
+import { render, screen, within } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { SWRConfig } from 'swr';
+import { openmrsFetch, useConfig } from '@openmrs/esm-framework';
+import { type AuditEncounter, type AuditObs, type AuditPatient } from '../types';
+import PatientActivity from './patient-activity.component';
+
+const mockOpenmrsFetch = jest.mocked(openmrsFetch);
+const mockUseConfig = jest.mocked(useConfig);
+
+const clerk = { uuid: 'user-clerk', display: 'Cos John' };
+const nurse = { uuid: 'user-nurse', display: 'Louidor Jean paul' };
+const created = '2026-09-01T11:09:00.000+0000';
+const dayAfter = '2026-09-02T08:30:00.000+0000';
+
+const patient: AuditPatient = {
+  uuid: 'patient-1',
+  display: 'Y2AHXV - Dave TestPatient',
+  identifiers: [{ uuid: 'id-1', identifier: 'Y2AHXV', preferred: true }],
+};
+
+const encounters: Array<AuditEncounter> = [
+  {
+    uuid: 'enc-1',
+    encounterDatetime: created,
+    encounterType: { uuid: 'type-1', display: 'COVID-19 Admission' },
+    auditInfo: { creator: clerk, dateCreated: created },
+  },
+];
+
+const obs: Array<AuditObs> = [
+  {
+    uuid: 'obs-pulse-new',
+    concept: { uuid: 'concept-pulse', display: 'Pulse' },
+    previousVersion: { uuid: 'obs-pulse-old' },
+    auditInfo: { creator: nurse, dateCreated: dayAfter },
+  },
+  {
+    uuid: 'obs-pulse-old',
+    concept: { uuid: 'concept-pulse', display: 'Pulse' },
+    voided: true,
+    auditInfo: { creator: clerk, dateCreated: created, voidedBy: nurse, dateVoided: dayAfter },
+  },
+];
+
+function mockRestApi({ encounterList = encounters }: { encounterList?: Array<AuditEncounter> } = {}) {
+  mockOpenmrsFetch.mockImplementation((url: string) => {
+    if (url.includes('/obs?encounter=')) {
+      return Promise.resolve({ data: { results: obs } }) as ReturnType<typeof openmrsFetch>;
+    }
+    return Promise.resolve({ data: { results: encounterList } }) as ReturnType<typeof openmrsFetch>;
+  });
+}
+
+function renderPatientActivity() {
+  const onSelectEncounter = jest.fn();
+  render(
+    <SWRConfig value={{ dedupingInterval: 0, provider: () => new Map() }}>
+      <PatientActivity filters={{}} includeDeleted={false} onSelectEncounter={onSelectEncounter} patient={patient} />
+    </SWRConfig>,
+  );
+  return onSelectEncounter;
+}
+
+function rowFor(name: string) {
+  return screen.getAllByRole('row').find((row) => row.textContent?.includes(name));
+}
+
+/** The activity log's rows, which are the ones naming an action. */
+function logRows() {
+  return screen
+    .getAllByRole('row')
+    .filter((row) =>
+      /Created encounter|Edited observation|Recorded observation|Deleted observation/.test(row.textContent ?? ''),
+    );
+}
+
+describe('<PatientActivity />', () => {
+  beforeEach(() => {
+    mockRestApi();
+  });
+
+  it('says who touched the record and what each of them did', async () => {
+    renderPatientActivity();
+
+    expect(await screen.findByText('Who modified this patient record')).toBeInTheDocument();
+
+    const clerkRow = rowFor('Cos John');
+    expect(within(clerkRow).getAllByRole('cell')[1]).toHaveTextContent('1');
+    expect(within(clerkRow).getAllByRole('cell')[2]).toHaveTextContent('1');
+
+    const nurseRow = rowFor('Louidor Jean paul');
+    expect(within(nurseRow).getAllByRole('cell')[3]).toHaveTextContent('1');
+  });
+
+  it('lists the individual events, most recent first', async () => {
+    renderPatientActivity();
+    await screen.findByText('Activity log');
+
+    const rows = logRows();
+    expect(rows[0]).toHaveTextContent('Edited observation');
+    expect(rows[0]).toHaveTextContent('Louidor Jean paul');
+    expect(rows[0]).toHaveTextContent('Pulse');
+    expect(rows[0]).toHaveTextContent('COVID-19 Admission');
+  });
+
+  it('narrows the activity log to one user, and back again', async () => {
+    renderPatientActivity();
+    await screen.findByText('Activity log');
+    expect(logRows()).toHaveLength(3);
+
+    await userEvent.click(screen.getByRole('button', { name: 'Louidor Jean paul' }));
+
+    const nurseOnly = logRows();
+    expect(nurseOnly).toHaveLength(1);
+    expect(nurseOnly[0]).toHaveTextContent('Edited observation');
+    expect(screen.getByRole('button', { name: 'Louidor Jean paul' })).toHaveAttribute('aria-pressed', 'true');
+
+    await userEvent.click(screen.getByRole('button', { name: /show everyone/i }));
+
+    expect(logRows()).toHaveLength(3);
+    expect(screen.getByRole('button', { name: 'Louidor Jean paul' })).toHaveAttribute('aria-pressed', 'false');
+  });
+
+  it('clicking the selected user again shows everyone', async () => {
+    renderPatientActivity();
+    await screen.findByText('Activity log');
+
+    await userEvent.click(screen.getByRole('button', { name: 'Cos John' }));
+    expect(logRows()).toHaveLength(2);
+
+    await userEvent.click(screen.getByRole('button', { name: 'Cos John' }));
+    expect(logRows()).toHaveLength(3);
+  });
+
+  it('drills into the encounter behind an event', async () => {
+    const onSelectEncounter = renderPatientActivity();
+    await screen.findByText('Activity log');
+
+    await userEvent.click(screen.getAllByRole('button', { name: /COVID-19 Admission/ })[0]);
+
+    expect(onSelectEncounter).toHaveBeenCalledWith('enc-1');
+  });
+
+  it("reads every encounter's observations, however many there are", async () => {
+    mockRestApi({
+      encounterList: [
+        encounters[0],
+        { ...encounters[0], uuid: 'enc-2', auditInfo: { creator: clerk, dateCreated: created } },
+      ],
+    });
+    renderPatientActivity();
+
+    await screen.findByText('Activity log');
+
+    // Both encounters are created by the clerk and both contribute their observations.
+    const clerkRow = rowFor('Cos John');
+    expect(within(clerkRow).getAllByRole('cell')[1]).toHaveTextContent('2');
+    expect(within(clerkRow).getAllByRole('cell')[2]).toHaveTextContent('2');
+    expect(mockOpenmrsFetch).toHaveBeenCalledWith(expect.stringContaining('/obs?encounter=enc-1'));
+    expect(mockOpenmrsFetch).toHaveBeenCalledWith(expect.stringContaining('/obs?encounter=enc-2'));
+  });
+
+  it('says how far the observation reads have got while they run', async () => {
+    let releaseObs: (value: unknown) => void = () => {};
+    const obsGate = new Promise((resolve) => {
+      releaseObs = resolve;
+    });
+    mockOpenmrsFetch.mockImplementation((url: string) => {
+      if (url.includes('/obs?encounter=')) {
+        return obsGate.then(() => ({ data: { results: obs } })) as ReturnType<typeof openmrsFetch>;
+      }
+      return Promise.resolve({ data: { results: encounters } }) as ReturnType<typeof openmrsFetch>;
+    });
+    renderPatientActivity();
+
+    expect(await screen.findByText(/reading observations from 0 of 1 encounters/i)).toBeInTheDocument();
+
+    releaseObs(null);
+
+    expect(await screen.findByText('Activity log')).toBeInTheDocument();
+  });
+
+  it('says when there is nothing to show', async () => {
+    mockRestApi({ encounterList: [] });
+    renderPatientActivity();
+
+    expect(await screen.findByText(/no recorded activity/i)).toBeInTheDocument();
+  });
+});

package/src/audit/patient-activity.component.tsx

@@ -0,0 +1,203 @@
+import React, { useEffect, useMemo, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+import {
+  DismissibleTag,
+  InlineLoading,
+  Pagination,
+  SkeletonText,
+  Table,
+  TableBody,
+  TableCell,
+  TableContainer,
+  TableHead,
+  TableHeader,
+  TableRow,
+  Tag,
+} from '@carbon/react';
+import { ErrorState } from '@openmrs/esm-framework';
+import { type AuditPatient } from '../types';
+import { formatAuditDatetime } from './audit-format';
+import { usePatientActivity } from './audit.resource';
+import { type EncounterFilters } from './encounter-filters';
+import { type AuditAction, eventUserUuid } from './patient-activity';
+import styles from './audit.scss';
+
+interface PatientActivityProps {
+  patient: AuditPatient | undefined;
+  includeDeleted: boolean;
+  filters: EncounterFilters;
+  onSelectEncounter(encounterUuid: string): void;
+}
+
+const eventsPerPage = 20;
+
+/**
+ * Who touched this patient's record: one row per user with what they did, and the individual
+ * events behind those counts.
+ */
+export default function PatientActivity({ patient, includeDeleted, filters, onSelectEncounter }: PatientActivityProps) {
+  const { t } = useTranslation();
+  const [selectedUserUuid, setSelectedUserUuid] = useState<string | null>(null);
+  const [page, setPage] = useState(1);
+  const { events, userActivity, scanProgress, error, isLoading } = usePatientActivity(patient, includeDeleted, filters);
+
+  const selectedUser = useMemo(
+    () => userActivity.find((activity) => activity.userUuid === selectedUserUuid),
+    [selectedUserUuid, userActivity],
+  );
+
+  const shownEvents = useMemo(
+    () => (selectedUserUuid ? events.filter((auditEvent) => eventUserUuid(auditEvent) === selectedUserUuid) : events),
+    [events, selectedUserUuid],
+  );
+
+  useEffect(() => {
+    setPage(1);
+  }, [selectedUserUuid]);
+
+  /** Clamped rather than reset, so a revalidation that shortens the log cannot blank the page. */
+  const totalPages = Math.max(1, Math.ceil(shownEvents.length / eventsPerPage));
+  const currentPage = Math.min(page, totalPages);
+  const pagedEvents = shownEvents.slice((currentPage - 1) * eventsPerPage, currentPage * eventsPerPage);
+
+  const actionLabels = useMemo<Record<AuditAction, { label: string; type: 'blue' | 'teal' | 'red' | 'gray' }>>(
+    () => ({
+      encounterCreated: { label: t('encounterCreatedAction', 'Created encounter'), type: 'teal' },
+      encounterChanged: { label: t('encounterChangedAction', 'Changed encounter'), type: 'blue' },
+      encounterDeleted: { label: t('encounterDeletedAction', 'Deleted encounter'), type: 'red' },
+      obsRecorded: { label: t('obsRecordedAction', 'Recorded observation'), type: 'gray' },
+      obsEdited: { label: t('obsEditedAction', 'Edited observation'), type: 'blue' },
+      obsDeleted: { label: t('obsDeletedAction', 'Deleted observation'), type: 'red' },
+    }),
+    [t],
+  );
+
+  if (error) {
+    return <ErrorState error={error} headerTitle={t('recordActivity', 'Patient activity')} />;
+  }
+
+  if (isLoading) {
+    return (
+      <>
+        {scanProgress.total > 0 ? (
+          <InlineLoading
+            description={t('readingObservations', 'Reading observations from {{read}} of {{total}} encounters…', {
+              read: scanProgress.read,
+              total: scanProgress.total,
+            })}
+          />
+        ) : null}
+        <SkeletonText heading paragraph role="progressbar" />
+      </>
+    );
+  }
+
+  if (events.length === 0) {
+    return <p className={styles.emptyState}>{t('noActivity', 'There is no recorded activity to show.')}</p>;
+  }
+
+  return (
+    <>
+      <h3 className={styles.sectionHeading}>{t('whoTouchedThisRecord', 'Who modified this patient record')}</h3>
+      <TableContainer className={styles.tableContainer}>
+        <Table size="sm" useZebraStyles>
+          <TableHead>
+            <TableRow>
+              <TableHeader>{t('user', 'User')}</TableHeader>
+              <TableHeader>{t('encountersCreated', 'Encounters created')}</TableHeader>
+              <TableHeader>{t('obsRecordedCount', 'Observations recorded')}</TableHeader>
+              <TableHeader>{t('obsEditedCount', 'Observations edited')}</TableHeader>
+              <TableHeader>{t('obsDeletedCount', 'Observations deleted')}</TableHeader>
+              <TableHeader>{t('firstActivity', 'First activity')}</TableHeader>
+              <TableHeader>{t('lastActivity', 'Last activity')}</TableHeader>
+            </TableRow>
+          </TableHead>
+          <TableBody>
+            {userActivity.map((activity) => {
+              const isSelected = activity.userUuid === selectedUserUuid;
+              return (
+                <TableRow className={isSelected ? styles.selectedRow : undefined} key={activity.userUuid}>
+                  <TableCell>
+                    <button
+                      aria-pressed={isSelected}
+                      className={styles.linkButton}
+                      onClick={() => setSelectedUserUuid(isSelected ? null : activity.userUuid)}
+                      title={t('showOnlyThisUser', "Show only this user's activity")}
+                      type="button">
+                      {activity.userDisplay || t('unknownUser', 'Unknown user')}
+                    </button>
+                  </TableCell>
+                  <TableCell>{activity.counts.encounterCreated}</TableCell>
+                  <TableCell>{activity.counts.obsRecorded}</TableCell>
+                  <TableCell>{activity.counts.obsEdited}</TableCell>
+                  <TableCell>{activity.counts.obsDeleted}</TableCell>
+                  <TableCell>{formatAuditDatetime(activity.firstActivity)}</TableCell>
+                  <TableCell>{formatAuditDatetime(activity.lastActivity)}</TableCell>
+                </TableRow>
+              );
+            })}
+          </TableBody>
+        </Table>
+      </TableContainer>
+
+      <div className={styles.logHeader}>
+        <h3 className={styles.sectionHeading}>{t('activityLog', 'Activity log')}</h3>
+        {selectedUserUuid ? (
+          <DismissibleTag
+            dismissTooltipLabel={t('showEveryone', 'Show everyone')}
+            onClose={() => setSelectedUserUuid(null)}
+            text={selectedUser?.userDisplay || t('unknownUser', 'Unknown user')}
+            title={t('showEveryone', 'Show everyone')}
+            type="blue"
+          />
+        ) : null}
+      </div>
+      <TableContainer className={styles.tableContainer}>
+        <Table size="sm">
+          <TableHead>
+            <TableRow>
+              <TableHeader>{t('when', 'When')}</TableHeader>
+              <TableHeader>{t('user', 'User')}</TableHeader>
+              <TableHeader>{t('action', 'Action')}</TableHeader>
+              <TableHeader>{t('detail', 'Detail')}</TableHeader>
+              <TableHeader>{t('encounter', 'Encounter')}</TableHeader>
+            </TableRow>
+          </TableHead>
+          <TableBody>
+            {pagedEvents.map((auditEvent) => (
+              <TableRow key={auditEvent.key}>
+                <TableCell>{formatAuditDatetime(auditEvent.timestamp)}</TableCell>
+                <TableCell>{auditEvent.user?.display || t('unknownUser', 'Unknown user')}</TableCell>
+                <TableCell>
+                  <Tag type={actionLabels[auditEvent.action].type}>{actionLabels[auditEvent.action].label}</Tag>
+                </TableCell>
+                <TableCell>{auditEvent.concept}</TableCell>
+                <TableCell>
+                  <button
+                    className={styles.linkButton}
+                    onClick={() => onSelectEncounter(auditEvent.encounter.uuid)}
+                    type="button">
+                    {[
+                      auditEvent.encounter.encounterType?.display,
+                      formatAuditDatetime(auditEvent.encounter.encounterDatetime),
+                    ]
+                      .filter(Boolean)
+                      .join(' · ')}
+                  </button>
+                </TableCell>
+              </TableRow>
+            ))}
+          </TableBody>
+        </Table>
+      </TableContainer>
+      <Pagination
+        onChange={({ page: nextPage }) => setPage(nextPage)}
+        page={currentPage}
+        pageSize={eventsPerPage}
+        pageSizes={[eventsPerPage]}
+        size="sm"
+        totalItems={shownEvents.length}
+      />
+    </>
+  );
+}

package/src/audit/patient-activity.test.ts

@@ -0,0 +1,155 @@
+import { type AuditEncounter, type AuditObs } from '../types';
+import { buildAuditEvents, eventUserUuid, summariseByUser, unknownUserUuid } from './patient-activity';
+
+const clerk = { uuid: 'user-clerk', display: 'Cos John' };
+const nurse = { uuid: 'user-nurse', display: 'Louidor Jean paul' };
+
+const encounterCreated = '2026-09-01T11:09:00.000+0000';
+const dayAfter = '2026-09-02T08:30:00.000+0000';
+
+const encounter: AuditEncounter = {
+  uuid: 'enc-1',
+  encounterDatetime: encounterCreated,
+  encounterType: { uuid: 'type-1', display: 'COVID-19 Admission' },
+  auditInfo: { creator: clerk, dateCreated: encounterCreated },
+};
+
+function obs(overrides: Partial<AuditObs> & { uuid: string }): AuditObs {
+  return {
+    concept: { uuid: 'concept-pulse', display: 'Pulse' },
+    auditInfo: { creator: clerk, dateCreated: encounterCreated },
+    ...overrides,
+  };
+}
+
+describe('buildAuditEvents', () => {
+  it('records who created an encounter', () => {
+    expect(buildAuditEvents([encounter], {})).toEqual([
+      expect.objectContaining({ action: 'encounterCreated', user: clerk, timestamp: encounterCreated }),
+    ]);
+  });
+
+  it('records an encounter that was changed and one that was deleted', () => {
+    const changed: AuditEncounter = {
+      ...encounter,
+      voided: true,
+      auditInfo: {
+        creator: clerk,
+        dateCreated: encounterCreated,
+        changedBy: nurse,
+        dateChanged: dayAfter,
+        voidedBy: nurse,
+        dateVoided: dayAfter,
+      },
+    };
+
+    expect(buildAuditEvents([changed], {}).map((auditEvent) => auditEvent.action)).toEqual([
+      'encounterChanged',
+      'encounterDeleted',
+      'encounterCreated',
+    ]);
+  });
+
+  it('counts an edit once, as an edit, rather than as a deletion and a recording', () => {
+    const events = buildAuditEvents([encounter], {
+      'enc-1': [
+        obs({
+          uuid: 'obs-new',
+          previousVersion: { uuid: 'obs-old' },
+          auditInfo: { creator: nurse, dateCreated: dayAfter },
+        }),
+        obs({
+          uuid: 'obs-old',
+          voided: true,
+          auditInfo: { creator: clerk, dateCreated: encounterCreated, voidedBy: nurse, dateVoided: dayAfter },
+        }),
+      ],
+    });
+
+    expect(events.map((auditEvent) => [auditEvent.action, auditEvent.user?.uuid])).toEqual([
+      ['obsEdited', 'user-nurse'],
+      ['encounterCreated', 'user-clerk'],
+      ['obsRecorded', 'user-clerk'],
+    ]);
+  });
+
+  it('records an outright deletion alongside the original recording', () => {
+    const events = buildAuditEvents([encounter], {
+      'enc-1': [
+        obs({
+          uuid: 'obs-gone',
+          voided: true,
+          auditInfo: { creator: clerk, dateCreated: encounterCreated, voidedBy: nurse, dateVoided: dayAfter },
+        }),
+      ],
+    });
+
+    expect(events.map((auditEvent) => [auditEvent.action, auditEvent.user?.uuid])).toEqual([
+      ['obsDeleted', 'user-nurse'],
+      ['encounterCreated', 'user-clerk'],
+      ['obsRecorded', 'user-clerk'],
+    ]);
+    expect(events[0].concept).toBe('Pulse');
+  });
+
+  it('leaves out events the api gave no timestamp for', () => {
+    expect(buildAuditEvents([{ uuid: 'enc-2' }], {})).toEqual([]);
+  });
+
+  it('puts the most recent event first', () => {
+    const events = buildAuditEvents([encounter], {
+      'enc-1': [obs({ uuid: 'obs-later', auditInfo: { creator: nurse, dateCreated: dayAfter } })],
+    });
+
+    expect(events[0].timestamp).toBe(dayAfter);
+  });
+});
+
+describe('eventUserUuid', () => {
+  it('keys an event by its user, or by the unknown user when the api named none', () => {
+    const [withUser] = buildAuditEvents([encounter], {});
+    const [withoutUser] = buildAuditEvents([{ uuid: 'enc-2', auditInfo: { dateCreated: dayAfter } }], {});
+
+    expect(eventUserUuid(withUser)).toBe(clerk.uuid);
+    expect(eventUserUuid(withoutUser)).toBe(unknownUserUuid);
+  });
+});
+
+describe('summariseByUser', () => {
+  const events = buildAuditEvents([encounter], {
+    'enc-1': [
+      obs({ uuid: 'obs-1' }),
+      obs({ uuid: 'obs-2' }),
+      obs({
+        uuid: 'obs-new',
+        previousVersion: { uuid: 'obs-2' },
+        auditInfo: { creator: nurse, dateCreated: dayAfter },
+      }),
+    ],
+  });
+
+  it('counts what each user did, busiest first', () => {
+    const summary = summariseByUser(events);
+
+    expect(summary.map((activity) => activity.userDisplay)).toEqual(['Cos John', 'Louidor Jean paul']);
+    expect(summary[0].counts).toMatchObject({ encounterCreated: 1, obsRecorded: 2, obsEdited: 0 });
+    expect(summary[0].totalEvents).toBe(3);
+    expect(summary[1].counts).toMatchObject({ obsEdited: 1 });
+  });
+
+  it('brackets each user’s activity with when they first and last touched the record', () => {
+    const summary = summariseByUser(events);
+
+    expect(summary[0].firstActivity).toBe(encounterCreated);
+    expect(summary[0].lastActivity).toBe(encounterCreated);
+    expect(summary[1].firstActivity).toBe(dayAfter);
+  });
+
+  it('gathers events with no named user rather than dropping them', () => {
+    const summary = summariseByUser(buildAuditEvents([{ uuid: 'enc-3', auditInfo: { dateCreated: dayAfter } }], {}));
+
+    expect(summary).toHaveLength(1);
+    expect(summary[0].userUuid).toBe(unknownUserUuid);
+    expect(summary[0].userDisplay).toBe('');
+  });
+});