@pih/esm-audit-app 2.1.0

package/src/audit/encounter-filters.ts

@@ -0,0 +1,105 @@
+import { type AuditEncounter, type OpenmrsResourceRef } from '../types';
+
+/**
+ * The filters an auditor can narrow a patient's encounter list by. Dates are held as calendar
+ * dates (`YYYY-MM-DD`) rather than instants, because that is what someone picking a date means,
+ * and both bounds are inclusive.
+ */
+export interface EncounterFilters {
+  /**
+   * The whole reference rather than just the uuid, so that the chosen type stays displayable even
+   * if it drops out of the available options — which happens when deleted encounters are hidden
+   * again and the type only occurred on those.
+   */
+  encounterType?: OpenmrsResourceRef;
+  fromDate?: string;
+  toDate?: string;
+}
+
+/**
+ * The encounter types a patient actually has, which is what their encounter list is worth
+ * filtering by — a dropdown of every type in the system would mostly offer types that return
+ * nothing for this patient.
+ */
+export function distinctEncounterTypes(encounters: Array<AuditEncounter>): Array<OpenmrsResourceRef> {
+  const byUuid = new Map<string, OpenmrsResourceRef>();
+  for (const encounter of encounters) {
+    if (encounter.encounterType?.uuid) {
+      byUuid.set(encounter.encounterType.uuid, encounter.encounterType);
+    }
+  }
+  return Array.from(byUuid.values()).sort((a, b) => (a.display ?? '').localeCompare(b.display ?? ''));
+}
+
+function pad(value: number): string {
+  return String(value).padStart(2, '0');
+}
+
+/** The calendar date a `Date` falls on, in the browser's time zone. */
+export function toDateKey(date: Date | null | undefined): string | undefined {
+  if (!date || Number.isNaN(date.getTime())) {
+    return undefined;
+  }
+  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+}
+
+/** Local midnight on a calendar date, for handing a stored filter back to the date picker. */
+export function fromDateKey(key: string | undefined): Date | null {
+  if (!key) {
+    return null;
+  }
+  const [year, month, day] = key.split('-').map(Number);
+  if (!year || !month || !day) {
+    return null;
+  }
+  return new Date(year, month - 1, day);
+}
+
+export function hasActiveFilters(filters: EncounterFilters): boolean {
+  return Boolean(filters.encounterType || filters.fromDate || filters.toDate);
+}
+
+/**
+ * The query parameters the encounter-by-patient search understands. The dates are sent without a
+ * time zone so the server reads them as its own wall clock — the facility's day, which is what the
+ * auditor picking a date means — and `todate` covers the whole of its day, since the API compares
+ * it against `encounterDatetime` with `<=`.
+ */
+export function buildEncounterFilterQuery(filters: EncounterFilters): string {
+  let query = '';
+  if (filters.encounterType) {
+    query += `&encounterType=${filters.encounterType.uuid}`;
+  }
+  if (filters.fromDate) {
+    query += `&fromdate=${filters.fromDate}T00:00:00`;
+  }
+  if (filters.toDate) {
+    query += `&todate=${filters.toDate}T23:59:59`;
+  }
+  return query;
+}
+
+/**
+ * The same filters applied on the client, for the free-text search used to list deleted
+ * encounters, which the REST API cannot filter server-side.
+ */
+export function matchesEncounterFilters(encounter: AuditEncounter, filters: EncounterFilters): boolean {
+  if (filters.encounterType && encounter.encounterType?.uuid !== filters.encounterType.uuid) {
+    return false;
+  }
+
+  if (filters.fromDate || filters.toDate) {
+    const day = encounter.encounterDatetime ? toDateKey(new Date(encounter.encounterDatetime)) : undefined;
+    if (!day) {
+      return false;
+    }
+    if (filters.fromDate && day < filters.fromDate) {
+      return false;
+    }
+    if (filters.toDate && day > filters.toDate) {
+      return false;
+    }
+  }
+
+  return true;
+}

package/src/audit/obs-audit-table.component.tsx

@@ -0,0 +1,181 @@
+import React, { useMemo, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+import {
+  Checkbox,
+  Table,
+  TableBody,
+  TableCell,
+  TableContainer,
+  TableHead,
+  TableHeader,
+  TableRow,
+  Tag,
+} from '@carbon/react';
+import { type AuditObs, type ObsChangeStatus, type ObsTreeNode } from '../types';
+import { formatUserAndDate } from './audit-format';
+import { flattenObsTree, formatObsValue, getConceptDescription, isVoidedStatus } from './obs-audit';
+import styles from './audit.scss';
+
+interface ObsAuditTableProps {
+  obsTree: Array<ObsTreeNode>;
+}
+
+/** One indent step per level of obs group nesting. */
+const indentPerLevel = 1.5;
+
+function collectObs(nodes: Array<ObsTreeNode>, into: Map<string, AuditObs>): Map<string, AuditObs> {
+  for (const node of nodes) {
+    into.set(node.obs.uuid, node.obs);
+    collectObs(node.children, into);
+  }
+  return into;
+}
+
+/**
+ * The audit trail for one encounter's observations: what was entered, what was changed, what was
+ * deleted, and by whom. Deleted obs are struck through, as they were on the legacy admin page, and
+ * every obs carries the change status derived by `getObsChangeStatus`.
+ */
+export default function ObsAuditTable({ obsTree }: ObsAuditTableProps) {
+  const { t, i18n } = useTranslation();
+  const [showDeleted, setShowDeleted] = useState(true);
+  const [showDescriptions, setShowDescriptions] = useState(false);
+
+  /** The tag and the legend entry for each status that is worth calling out. */
+  const statusMeta = useMemo(
+    () => ({
+      edited: {
+        label: t('edited', 'Edited'),
+        type: 'blue' as const,
+        legend: t('editedLegend', 'the value was changed after it was first recorded'),
+      },
+      addedAfterEncounter: {
+        label: t('addedLater', 'Added later'),
+        type: 'teal' as const,
+        legend: t('addedLaterLegend', 'recorded after the encounter itself was created'),
+      },
+      deleted: {
+        label: t('deleted', 'Deleted'),
+        type: 'red' as const,
+        legend: t('deletedLegend', 'removed from the encounter'),
+      },
+      supersededValue: {
+        label: t('previousValue', 'Previous value'),
+        type: 'gray' as const,
+        legend: t('previousValueLegend', 'the value that an edit replaced'),
+      },
+    }),
+    [t],
+  );
+
+  const obsByUuid = useMemo(() => collectObs(obsTree, new Map<string, AuditObs>()), [obsTree]);
+  const rows = useMemo(() => flattenObsTree(obsTree, showDeleted), [obsTree, showDeleted]);
+  const hasDeletedObs = useMemo(() => Array.from(obsByUuid.values()).some((obs) => obs.voided), [obsByUuid]);
+
+  return (
+    <>
+      <h3 className={styles.sectionHeading}>{t('observations', 'Observations')}</h3>
+      <div className={styles.toolbar}>
+        <Checkbox
+          checked={showDeleted}
+          disabled={!hasDeletedObs}
+          id="show-deleted-obs"
+          labelText={t('showDeletedObs', 'Show deleted observations')}
+          onChange={(_event, { checked }) => setShowDeleted(checked)}
+        />
+        <Checkbox
+          checked={showDescriptions}
+          id="show-obs-descriptions"
+          labelText={t('showConceptDescriptions', 'Show concept descriptions')}
+          onChange={(_event, { checked }) => setShowDescriptions(checked)}
+        />
+      </div>
+      <div className={styles.legend}>
+        {Object.entries(statusMeta).map(([status, meta]) => (
+          <span className={styles.legendItem} key={status}>
+            <Tag type={meta.type}>{meta.label}</Tag>
+            {meta.legend}
+          </span>
+        ))}
+      </div>
+
+      {rows.length === 0 ? (
+        <p className={styles.emptyState}>{t('noObservations', 'This encounter has no observations.')}</p>
+      ) : (
+        <TableContainer className={styles.tableContainer}>
+          <Table size="sm">
+            <TableHead>
+              <TableRow>
+                <TableHeader>{t('questionConcept', 'Question concept')}</TableHeader>
+                <TableHeader>{t('value', 'Value')}</TableHeader>
+                <TableHeader>{t('change', 'Change')}</TableHeader>
+                <TableHeader>{t('recordedBy', 'Recorded by')}</TableHeader>
+                <TableHeader>{t('deletedBy', 'Deleted by')}</TableHeader>
+              </TableRow>
+            </TableHead>
+            <TableBody>
+              {rows.map(({ obs, status, depth, children }) => {
+                const meta = status === 'unchanged' ? undefined : statusMeta[status];
+                const previous = obs.previousVersion ? obsByUuid.get(obs.previousVersion.uuid) : undefined;
+                const description = showDescriptions ? getConceptDescription(obs, i18n?.language) : undefined;
+                const isGroup = children.length > 0;
+                const indent = { paddingInlineStart: `${depth * indentPerLevel}rem` };
+
+                return (
+                  <React.Fragment key={obs.uuid}>
+                    <TableRow className={isVoidedStatus(status) ? styles.voidedRow : undefined}>
+                      <TableCell>
+                        <span className={styles.obsConcept} style={indent}>
+                          {isGroup ? <strong>{obs.concept?.display}</strong> : obs.concept?.display}
+                        </span>
+                      </TableCell>
+                      <TableCell>
+                        {isGroup ? null : formatObsValue(obs.value)}
+                        {previous ? (
+                          <div className={styles.obsDescription}>
+                            {t('wasPreviously', 'was {{value}}', { value: formatObsValue(previous.value) })}
+                          </div>
+                        ) : null}
+                        {obs.comment ? <div className={styles.obsDescription}>{obs.comment}</div> : null}
+                      </TableCell>
+                      <TableCell>{meta ? <Tag type={meta.type}>{meta.label}</Tag> : null}</TableCell>
+                      <TableCell>
+                        <div>{formatUserAndDate(obs.auditInfo?.creator, obs.auditInfo?.dateCreated)}</div>
+                        {obs.auditInfo?.changedBy ? (
+                          <div className={styles.obsDescription}>
+                            {t('changedByUser', 'Changed by {{user}}', {
+                              user: formatUserAndDate(obs.auditInfo.changedBy, obs.auditInfo.dateChanged),
+                            })}
+                          </div>
+                        ) : null}
+                      </TableCell>
+                      <TableCell>
+                        {obs.voided ? (
+                          <>
+                            <div>{formatUserAndDate(obs.auditInfo?.voidedBy, obs.auditInfo?.dateVoided)}</div>
+                            {obs.auditInfo?.voidReason ? (
+                              <div className={styles.obsDescription}>{obs.auditInfo.voidReason}</div>
+                            ) : null}
+                          </>
+                        ) : null}
+                      </TableCell>
+                    </TableRow>
+                    {description ? (
+                      <TableRow>
+                        <TableCell colSpan={5}>
+                          <div className={styles.obsDescription} style={indent}>
+                            {description}
+                          </div>
+                        </TableCell>
+                      </TableRow>
+                    ) : null}
+                  </React.Fragment>
+                );
+              })}
+            </TableBody>
+          </Table>
+        </TableContainer>
+      )}
+    </>
+  );
+}

package/src/audit/obs-audit.test.ts

@@ -0,0 +1,170 @@
+import { type AuditEncounter, type AuditObs } from '../types';
+import {
+  buildObsTree,
+  flattenObsTree,
+  formatObsValue,
+  getConceptDescription,
+  getObsChangeStatus,
+  isVoidedStatus,
+} from './obs-audit';
+
+const encounterCreated = '2026-09-01T11:09:00.000+0000';
+const laterThanEncounter = '2026-09-02T08:30:00.000+0000';
+
+const encounter: AuditEncounter = {
+  uuid: 'enc-1',
+  auditInfo: { creator: { uuid: 'user-1', display: 'Cos John' }, dateCreated: encounterCreated },
+};
+
+function obs(overrides: Partial<AuditObs> & { uuid: string }): AuditObs {
+  return {
+    concept: { uuid: `concept-${overrides.uuid}`, display: 'Pulse' },
+    auditInfo: { creator: { uuid: 'user-1', display: 'Cos John' }, dateCreated: encounterCreated },
+    ...overrides,
+  };
+}
+
+describe('getObsChangeStatus', () => {
+  it('reports an obs created with its encounter as unchanged', () => {
+    expect(getObsChangeStatus(obs({ uuid: 'a' }), encounter, new Set())).toBe('unchanged');
+  });
+
+  it('reports an obs that replaced an earlier one as edited', () => {
+    const edited = obs({ uuid: 'a', previousVersion: { uuid: 'b' }, auditInfo: { dateCreated: laterThanEncounter } });
+    expect(getObsChangeStatus(edited, encounter, new Set())).toBe('edited');
+  });
+
+  it('reports an obs created after its encounter as added later', () => {
+    const added = obs({ uuid: 'a', auditInfo: { dateCreated: laterThanEncounter } });
+    expect(getObsChangeStatus(added, encounter, new Set())).toBe('addedAfterEncounter');
+  });
+
+  it('reports a voided obs as deleted', () => {
+    expect(getObsChangeStatus(obs({ uuid: 'a', voided: true }), encounter, new Set())).toBe('deleted');
+  });
+
+  it('reports a voided obs that a later obs replaced as a superseded value', () => {
+    expect(getObsChangeStatus(obs({ uuid: 'a', voided: true }), encounter, new Set(['a']))).toBe('supersededValue');
+  });
+
+  it('does not guess when either creation date is missing', () => {
+    expect(getObsChangeStatus(obs({ uuid: 'a', auditInfo: {} }), encounter, new Set())).toBe('unchanged');
+    expect(getObsChangeStatus(obs({ uuid: 'a' }), undefined, new Set())).toBe('unchanged');
+  });
+
+  it('knows which statuses mean the obs row is voided', () => {
+    expect(isVoidedStatus('deleted')).toBe(true);
+    expect(isVoidedStatus('supersededValue')).toBe(true);
+    expect(isVoidedStatus('edited')).toBe(false);
+  });
+});
+
+describe('buildObsTree', () => {
+  it('nests obs group members under their group and tags each obs with its status', () => {
+    const tree = buildObsTree(
+      [
+        obs({ uuid: 'member', obsGroup: { uuid: 'group' }, concept: { uuid: 'c-2', display: 'Sign/Symptom name' } }),
+        obs({ uuid: 'group', concept: { uuid: 'c-1', display: 'Sign/Symptom construct' } }),
+      ],
+      encounter,
+    );
+
+    expect(tree).toHaveLength(1);
+    expect(tree[0].obs.uuid).toBe('group');
+    expect(tree[0].depth).toBe(0);
+    expect(tree[0].status).toBe('unchanged');
+    expect(tree[0].children.map((child) => child.obs.uuid)).toEqual(['member']);
+    expect(tree[0].children[0].depth).toBe(1);
+  });
+
+  it('keeps an obs whose group is missing from the list at the top level', () => {
+    const tree = buildObsTree([obs({ uuid: 'orphan', obsGroup: { uuid: 'not-loaded' } })], encounter);
+
+    expect(tree.map((node) => node.obs.uuid)).toEqual(['orphan']);
+  });
+
+  it('puts the versions of one value together, newest first', () => {
+    const tree = buildObsTree(
+      [
+        obs({
+          uuid: 'pulse-old',
+          value: 67,
+          voided: true,
+          formFieldPath: 'covid.pulse',
+          auditInfo: { dateCreated: encounterCreated },
+        }),
+        obs({ uuid: 'temperature', value: 38, formFieldPath: 'covid.temperature' }),
+        obs({
+          uuid: 'pulse-new',
+          value: 68,
+          previousVersion: { uuid: 'pulse-old' },
+          formFieldPath: 'covid.pulse',
+          auditInfo: { dateCreated: laterThanEncounter },
+        }),
+      ],
+      encounter,
+    );
+
+    expect(tree.map((node) => [node.obs.uuid, node.status])).toEqual([
+      ['pulse-new', 'edited'],
+      ['pulse-old', 'supersededValue'],
+      ['temperature', 'unchanged'],
+    ]);
+  });
+});
+
+describe('flattenObsTree', () => {
+  const tree = buildObsTree(
+    [
+      obs({ uuid: 'group', voided: true, concept: { uuid: 'c-1', display: 'Group' } }),
+      obs({ uuid: 'member', voided: true, obsGroup: { uuid: 'group' } }),
+      obs({ uuid: 'kept' }),
+    ],
+    encounter,
+  );
+
+  it('returns every obs when deleted obs are shown', () => {
+    expect(flattenObsTree(tree, true).map((node) => node.obs.uuid)).toEqual(['group', 'member', 'kept']);
+  });
+
+  it('drops deleted obs, and anything nested inside them, when they are hidden', () => {
+    expect(flattenObsTree(tree, false).map((node) => node.obs.uuid)).toEqual(['kept']);
+  });
+});
+
+describe('formatObsValue', () => {
+  it('displays coded values by their name and scalar values as they are', () => {
+    expect(formatObsValue({ uuid: 'concept-yes', display: 'Yes' })).toBe('Yes');
+    expect(formatObsValue(68)).toBe('68');
+    expect(formatObsValue('advil 100')).toBe('advil 100');
+  });
+
+  it('displays nothing for an obs with no value, such as an obs group', () => {
+    expect(formatObsValue(null)).toBe('');
+    expect(formatObsValue(undefined)).toBe('');
+  });
+});
+
+describe('getConceptDescription', () => {
+  const described = obs({
+    uuid: 'a',
+    concept: {
+      uuid: 'c-1',
+      display: 'Pulse',
+      descriptions: [
+        { description: 'Battements par minute', locale: 'fr' },
+        { description: 'Beats per minute', locale: 'en' },
+      ],
+    },
+  });
+
+  it('prefers the description matching the given locale', () => {
+    expect(getConceptDescription(described, 'en_GB')).toBe('Beats per minute');
+    expect(getConceptDescription(described, 'fr')).toBe('Battements par minute');
+  });
+
+  it('falls back to the first description when nothing matches', () => {
+    expect(getConceptDescription(described, 'es')).toBe('Battements par minute');
+    expect(getConceptDescription(obs({ uuid: 'a' }), 'en')).toBeUndefined();
+  });
+});

package/src/audit/obs-audit.ts

@@ -0,0 +1,156 @@
+import { type AuditEncounter, type AuditObs, type ObsChangeStatus, type ObsTreeNode, type ObsValue } from '../types';
+
+/** Statuses that mean the obs row is voided in the database. */
+const voidedStatuses: Array<ObsChangeStatus> = ['deleted', 'supersededValue'];
+
+export function isVoidedStatus(status: ObsChangeStatus): boolean {
+  return voidedStatuses.includes(status);
+}
+
+function toTime(date: string | undefined): number | null {
+  if (!date) {
+    return null;
+  }
+  const time = new Date(date).getTime();
+  return Number.isNaN(time) ? null : time;
+}
+
+/**
+ * Works out how an obs came to look the way it does. This reproduces what the legacy
+ * `admin/encounters/encounter.form` page showed, using the data the REST API exposes:
+ *
+ * - an obs that points at a `previousVersion` replaced an earlier obs, so its value was edited;
+ * - an obs created later than its encounter was added after the encounter was first saved.
+ *   OpenMRS stamps the same `dateCreated` on an encounter and on every obs saved with it, so an
+ *   obs whose `dateCreated` differs from the encounter's was saved in a later transaction;
+ * - a voided obs was deleted, unless a surviving obs points back at it as its `previousVersion`,
+ *   in which case it is the value that was edited away.
+ *
+ * @param obs the obs to classify
+ * @param encounter the encounter the obs belongs to, for its creation date
+ * @param supersededUuids uuids that some other obs in the encounter names as its `previousVersion`
+ */
+export function getObsChangeStatus(
+  obs: AuditObs,
+  encounter: AuditEncounter | undefined,
+  supersededUuids: Set<string>,
+): ObsChangeStatus {
+  if (obs.voided) {
+    return supersededUuids.has(obs.uuid) ? 'supersededValue' : 'deleted';
+  }
+
+  if (obs.previousVersion) {
+    return 'edited';
+  }
+
+  const obsCreated = toTime(obs.auditInfo?.dateCreated);
+  const encounterCreated = toTime(encounter?.auditInfo?.dateCreated);
+  if (obsCreated !== null && encounterCreated !== null && obsCreated !== encounterCreated) {
+    return 'addedAfterEncounter';
+  }
+
+  return 'unchanged';
+}
+
+/**
+ * Sorts obs so that every version of a value sits together, newest first. Obs recorded through a
+ * form share a `formFieldPath`, which also approximates the order of the fields on that form; obs
+ * recorded some other way fall back to the concept name.
+ */
+function compareObs(a: AuditObs, b: AuditObs): number {
+  const groupA = a.formFieldPath ?? a.concept?.display ?? '';
+  const groupB = b.formFieldPath ?? b.concept?.display ?? '';
+  if (groupA !== groupB) {
+    return groupA.localeCompare(groupB);
+  }
+
+  const createdA = toTime(a.auditInfo?.dateCreated) ?? 0;
+  const createdB = toTime(b.auditInfo?.dateCreated) ?? 0;
+  if (createdA !== createdB) {
+    return createdB - createdA;
+  }
+
+  return a.uuid.localeCompare(b.uuid);
+}
+
+/**
+ * Turns the flat list of obs the REST API returns for an encounter — which includes obs group
+ * members and voided obs — into the group hierarchy, tagging each obs with its change status.
+ *
+ * An obs whose group is not in the list (which the API should not return, but which would
+ * otherwise silently drop the obs) is treated as a root so that it stays visible.
+ */
+export function buildObsTree(obsList: Array<AuditObs>, encounter?: AuditEncounter): Array<ObsTreeNode> {
+  const supersededUuids = new Set(
+    obsList.map((obs) => obs.previousVersion?.uuid).filter((uuid): uuid is string => Boolean(uuid)),
+  );
+
+  const nodes = new Map<string, ObsTreeNode>(
+    obsList.map((obs) => [
+      obs.uuid,
+      { obs, status: getObsChangeStatus(obs, encounter, supersededUuids), depth: 0, children: [] },
+    ]),
+  );
+
+  const roots: Array<ObsTreeNode> = [];
+  for (const node of nodes.values()) {
+    const parent = node.obs.obsGroup?.uuid ? nodes.get(node.obs.obsGroup.uuid) : undefined;
+    if (parent) {
+      parent.children.push(node);
+    } else {
+      roots.push(node);
+    }
+  }
+
+  const sortAndSetDepth = (siblings: Array<ObsTreeNode>, depth: number) => {
+    siblings.sort((a, b) => compareObs(a.obs, b.obs));
+    for (const sibling of siblings) {
+      sibling.depth = depth;
+      sortAndSetDepth(sibling.children, depth + 1);
+    }
+  };
+  sortAndSetDepth(roots, 0);
+
+  return roots;
+}
+
+/**
+ * Flattens the obs tree into the rows to render, dropping voided obs (along with anything nested
+ * inside them) unless deleted obs are being shown.
+ */
+export function flattenObsTree(nodes: Array<ObsTreeNode>, showDeleted: boolean): Array<ObsTreeNode> {
+  return nodes.flatMap((node) => {
+    if (!showDeleted && isVoidedStatus(node.status)) {
+      return [];
+    }
+    return [node, ...flattenObsTree(node.children, showDeleted)];
+  });
+}
+
+/**
+ * Renders an obs value for display. Coded obs (and the drug and location values OpenMRS stores
+ * alongside them) arrive as references rather than as scalars.
+ */
+export function formatObsValue(value: ObsValue | undefined): string {
+  if (value === null || value === undefined) {
+    return '';
+  }
+  if (typeof value === 'object') {
+    return value.display ?? '';
+  }
+  if (typeof value === 'boolean') {
+    return String(value);
+  }
+  return String(value);
+}
+
+/** Picks the concept description matching the given locale, falling back to whatever is there. */
+export function getConceptDescription(obs: AuditObs, locale: string | undefined): string | undefined {
+  const descriptions = obs.concept?.descriptions;
+  if (!descriptions?.length) {
+    return undefined;
+  }
+  const language = locale?.split(/[-_]/)[0];
+  const match = descriptions.find((description) => description.locale?.split(/[-_]/)[0] === language);
+  return (match ?? descriptions[0]).description;
+}