@pih/esm-audit-app 2.1.1-pre.144 → 2.1.1-pre.151

package/src/audit/audit.resource.ts

@@ -1,4 +1,4 @@
-import { useEffect, useMemo, useState } from 'react';
+import { useEffect, useMemo, useRef, useState } from 'react';
 import useSWR from 'swr';
 import {
   type FetchResponse,
@@ -7,7 +7,23 @@ import {
   useOpenmrsFetchAll,
   useOpenmrsPagination,
 } from '@openmrs/esm-framework';
-import { type AuditEncounter, type AuditObs, type AuditPatient, type ObsTreeNode, type PagedResponse } from '../types';
+import {
+  type AuditEncounter,
+  type AuditObs,
+  type AuditPatient,
+  type AuditProvider,
+  type AuditUser,
+  type ObsTreeNode,
+  type OpenmrsResourceRef,
+  type PagedResponse,
+} from '../types';
+import {
+  buildAuditDateQuery,
+  ENCOUNTER_DATE_PARAMS,
+  OBS_CREATED_DATE_PARAMS,
+  OBS_VOIDED_DATE_PARAMS,
+  type DateRange,
+} from './date-range';
 import {
   buildEncounterFilterQuery,
   distinctEncounterTypes,
@@ -16,6 +32,17 @@ import {
 } from './encounter-filters';
 import { buildObsTree } from './obs-audit';
 import { buildAuditEvents, type ObsByEncounter, summariseByUser } from './patient-activity';
+import {
+  type AuditAction,
+  canDiscoverMore,
+  countUserObs,
+  discoverEncounters,
+  emptyStream,
+  filterByEncounterType,
+  type ObsStream,
+  streamToExtend,
+  type UserEncounterActivity,
+} from './user-encounters';
 
 const patientRep =
   'custom:(uuid,display,identifiers:(uuid,identifier,preferred,identifierType:(uuid,display))' +
@@ -50,6 +77,44 @@ const obsRep =
 /** A stable identity, so the unfiltered reads do not rebuild their memos on every render. */
 const noFilters: EncounterFilters = {};
 
+const userRep = 'custom:(uuid,display,username,systemId,retired,person:(uuid,display))';
+
+/**
+ * The pihapps audit endpoint, which searches observations by the user who created or voided them —
+ * something the core REST API cannot do, since neither the obs resource nor core's own
+ * `ObsSearchCriteria` has a creator or voidedBy field.
+ */
+const obsAuditUrl = `${restBaseUrl}/pihapps/obs`;
+
+/**
+ * The ordering an obs audit stream asks for: the column belonging to the action it searched on,
+ * most recent first. Ordering by the observation's own datetime would bury an obs backdated to last
+ * year but entered this morning, which is the opposite of what an audit needs; `obsId` breaks ties
+ * so that paging cannot repeat or skip a row when several share a timestamp.
+ */
+function obsSortQuery(actionDate: 'dateCreated' | 'dateVoided'): string {
+  return `&sortBy=${actionDate}-desc&sortBy=obsId-desc`;
+}
+
+/**
+ * The whole encounter rather than a reference, so the observations a user touched can be grouped
+ * into encounters and listed without a further request per encounter.
+ */
+const obsAuditRep =
+  'custom:(uuid,voided,obsDatetime,concept:(uuid,display),auditInfo' +
+  ',encounter:(uuid,display,encounterDatetime,voided,encounterType:(uuid,display)' +
+  ',form:(uuid,display),location:(uuid,display),patient:(uuid,display)))';
+
+const providerRep = 'custom:(uuid,display,identifier,retired,person:(uuid,display,gender))';
+
+/**
+ * A provider's encounters span patients, so the list names the patient and who entered it —
+ * `encounterListRep` carries only the patient's uuid, which is all a single patient's list needs.
+ */
+const providerEncounterRep =
+  'custom:(uuid,display,encounterDatetime,voided,patient:(uuid,display),encounterType:(uuid,display)' +
+  ',form:(uuid,display),location:(uuid,display),auditInfo)';
+
 /** Just enough of an obs to say who touched it and when. */
 const activityObsRep = 'custom:(uuid,voided,concept:(uuid,display),previousVersion:(uuid),auditInfo)';
 
@@ -68,27 +133,48 @@ const bulkPageSize = 100;
 const maxBulkPages = 25;
 
 /**
- * Reads every page of a paginated REST endpoint imperatively.
+ * A last-resort ceiling for a read that is meant to be exhaustive, so that a paging bug on either
+ * side cannot spin forever. It sits far above any real audit trail; reaching it means something is
+ * wrong, which is why it warns and is reported rather than silently truncating.
+ */
+const runawayRowLimit = 100000;
+
+interface FetchAllPagesOptions {
+  /** Stop after this many rows. Defaults to a bound suited to one encounter's observations. */
+  maxRows?: number;
+  /** Called with the running total after each page, for reads long enough to be worth reporting. */
+  onProgress?: (rowsRead: number) => void;
+}
+
+/**
+ * Reads the pages of a paginated REST endpoint imperatively.
  *
- * `useOpenmrsFetchAll` covers this wherever the url is known at render time. The activity scan is
- * the exception: it reads the observations of many encounters, and a hook cannot be called once
- * per encounter, so that one loop needs a plain function.
+ * `useOpenmrsFetchAll` covers this wherever one url is known at render time. Two callers cannot use
+ * it: the activity scan reads the observations of many encounters, and a hook cannot be called once
+ * per encounter; and the user audit scan needs to report its progress as it goes.
  */
-async function fetchAllPages<T>(url: string): Promise<Array<T>> {
+async function fetchAllPages<T>(url: string, options: FetchAllPagesOptions = {}): Promise<Array<T>> {
   const results: Array<T> = [];
   const separator = url.includes('?') ? '&' : '?';
+  const rowLimit = options.maxRows ?? maxBulkPages * bulkPageSize;
 
-  for (let page = 0; page < maxBulkPages; page++) {
+  while (results.length < rowLimit) {
+    const pageSize = Math.min(bulkPageSize, rowLimit - results.length);
     const response = await openmrsFetch<PagedResponse<T>>(
-      `${url}${separator}startIndex=${page * bulkPageSize}&limit=${bulkPageSize}`,
+      `${url}${separator}startIndex=${results.length}&limit=${pageSize}`,
     );
     const batch = response?.data?.results ?? [];
     results.push(...batch);
-    if (batch.length < bulkPageSize) {
+    options.onProgress?.(results.length);
+    if (batch.length < pageSize) {
       break;
     }
   }
 
+  if (results.length >= runawayRowLimit) {
+    console.warn(`Stopped reading ${url} after ${runawayRowLimit} rows; results are incomplete.`);
+  }
+
   return results;
 }
 
@@ -216,6 +302,41 @@ export function useAllPatientEncounters(
   };
 }
 
+/** One entry of the pihapps encounter type count endpoint. */
+interface EncounterTypeCount {
+  encounterType: OpenmrsResourceRef;
+  count: number;
+}
+
+/**
+ * The encounter types this implementation actually records against, for a filter that cannot be
+ * narrowed to what a particular search contains. The user and provider drill-downs need this
+ * because they discover encounters lazily or page them on the server, and so do not know which
+ * types a trail holds until all of it is read.
+ *
+ * Every type in the system would be mostly noise, since which ones are in use varies a great deal
+ * by country, so the types come from pihapps' count endpoint, which is asked to leave out those
+ * with no encounters. Deleted encounters count, as they do everywhere else in an audit: a type whose
+ * encounters have all been deleted still has a trail to look at. Retired types are kept for the
+ * same reason, since encounters recorded before a type was retired can still be audited.
+ */
+export function useUsedEncounterTypes() {
+  const { data, error, isLoading } = useSWR<FetchResponse<{ results: Array<EncounterTypeCount> }>>(
+    `${restBaseUrl}/pihapps/encounterTypeCount?includeVoided=true&onlyUsed=true&v=custom:(uuid,display)`,
+    openmrsFetch,
+  );
+
+  const encounterTypes = useMemo(
+    () =>
+      (data?.data?.results ?? [])
+        .map((entry) => entry.encounterType)
+        .sort((a, b) => (a.display ?? '').localeCompare(b.display ?? '')),
+    [data],
+  );
+
+  return { encounterTypes, error, isLoading };
+}
+
 /**
  * The encounter types to offer as filters: the ones this patient's own encounters use, so the
  * dropdown never offers a type that would return nothing. Read unfiltered, so choosing a type
@@ -407,3 +528,317 @@ export function usePatientActivity(
     isLoading: isLoadingEncounters || obsResult.isLoading,
   };
 }
+
+/** Searches providers by name or identifier, one page at a time. */
+export function useProviderSearch(query: string, page: number, pageSize: number) {
+  const startIndex = (page - 1) * pageSize;
+  const url = query
+    ? `${restBaseUrl}/provider?q=${encodeURIComponent(query)}&v=${providerRep}` +
+      `&startIndex=${startIndex}&limit=${pageSize}&totalCount=true`
+    : null;
+
+  const { data, error, isLoading } = useSWR<FetchResponse<PagedResponse<AuditProvider>>>(url, openmrsFetch);
+
+  return {
+    providers: data?.data?.results ?? [],
+    totalCount: data?.data?.totalCount ?? data?.data?.results?.length ?? 0,
+    error,
+    isLoading,
+  };
+}
+
+export function useAuditProvider(providerUuid: string | null) {
+  const url = providerUuid ? `${restBaseUrl}/provider/${providerUuid}?v=${providerRep}` : null;
+  const { data, error, isLoading } = useSWR<FetchResponse<AuditProvider>>(url, openmrsFetch);
+
+  return { provider: data?.data, error, isLoading };
+}
+
+/**
+ * The encounters a provider is recorded on, newest first, a page at a time.
+ *
+ * Core cannot search encounters by provider: `EncounterSearchCriteria` carries a providers field
+ * but no search handler exposes it, and the free-text encounter search only matches patient name
+ * and identifier. The pihapps audit endpoint can, and it returns whole encounters including
+ * `auditInfo`, so one paged request per page is the whole cost — no second read per row, and no
+ * FHIR detour.
+ */
+const PROVIDER_ENCOUNTER_SORT = ['encounterDatetime-desc', 'encounterId-desc'];
+
+export function useProviderEncounters(providerUuid: string | null, pageSize: number, filters: EncounterFilters) {
+  const filterQuery =
+    (filters.encounterType ? `&encounterType=${filters.encounterType.uuid}` : '') +
+    buildAuditDateQuery(filters, ENCOUNTER_DATE_PARAMS);
+  // `includeVoided=true` because this is an audit: the endpoint leaves voided encounters out unless
+  // asked, and an auditor wants to see what has since been deleted as much as what survives. The
+  // rows carry a `voided` flag so the table can mark them.
+  //
+  // The endpoint sorts nothing unless asked. A provider search names no audit action, so the most
+  // recent thing it is about is the encounter's own datetime; `encounterId` breaks ties so that
+  // paging cannot repeat or skip a row when several share a timestamp.
+  const url = providerUuid
+    ? `${restBaseUrl}/pihapps/encounter?provider=${providerUuid}&includeVoided=true` +
+      `&sortBy=${PROVIDER_ENCOUNTER_SORT.join('&sortBy=')}&v=${providerEncounterRep}${filterQuery}`
+    : null;
+  // `useOpenmrsPagination` appends limit, startIndex and totalCount itself, so the url omits them.
+  const result = useOpenmrsPagination<AuditEncounter>(url as string, pageSize, restFetchOptions);
+
+  /**
+   * Both filters narrow on the server, so a change makes the pages a different set. The hook keeps
+   * its own page number, so paging has to be sent back to the start or a filter applied on page
+   * three would ask for a page that may no longer exist.
+   */
+  useEffect(() => {
+    if (result.currentPage !== 1) {
+      result.goTo(1);
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [filterQuery, providerUuid]);
+
+  return {
+    encounters: result.data ?? [],
+    // The hook reports NaN until the first page has been read.
+    totalCount: Number.isNaN(result.totalCount) ? 0 : result.totalCount,
+    currentPage: result.currentPage,
+    goTo: result.goTo,
+    error: result.error,
+    isLoading: result.isLoading,
+  };
+}
+
+/** Searches user accounts by username, system id, or the person's name, one page at a time. */
+export function useUserSearch(query: string, page: number, pageSize: number) {
+  const startIndex = (page - 1) * pageSize;
+  const url = query
+    ? `${restBaseUrl}/user?q=${encodeURIComponent(query)}&v=${userRep}` +
+      `&startIndex=${startIndex}&limit=${pageSize}&totalCount=true`
+    : null;
+
+  const { data, error, isLoading } = useSWR<FetchResponse<PagedResponse<AuditUser>>>(url, openmrsFetch);
+
+  return {
+    users: data?.data?.results ?? [],
+    totalCount: data?.data?.totalCount ?? data?.data?.results?.length ?? 0,
+    error,
+    isLoading,
+  };
+}
+
+export function useAuditUser(userUuid: string | null) {
+  const url = userUuid ? `${restBaseUrl}/user/${userUuid}?v=${userRep}` : null;
+  const { data, error, isLoading } = useSWR<FetchResponse<AuditUser>>(url, openmrsFetch);
+
+  return { user: data?.data, error, isLoading };
+}
+
+/** Observations read per request while walking the audit searches. */
+const auditScanPageSize = 100;
+
+/**
+ * A safety ceiling on how many requests one page of encounters may cost, so that a pathological
+ * trail — thousands of observations all on a handful of encounters — cannot spin indefinitely.
+ */
+const maxScanRequestsPerPage = 40;
+
+/** Reads the next page of one of the two audit searches and folds it into that stream. */
+async function extendStream(baseUrl: string, stream: ObsStream): Promise<ObsStream> {
+  const response = await openmrsFetch<PagedResponse<AuditObs>>(
+    `${baseUrl}&startIndex=${stream.obs.length}&limit=${auditScanPageSize}`,
+  );
+  const batch = response?.data?.results ?? [];
+  return { obs: [...stream.obs, ...batch], exhausted: batch.length < auditScanPageSize };
+}
+
+/**
+ * The encounters whose observations a given user recorded or deleted, most recently changed first,
+ * discovered a page at a time.
+ *
+ * `createdBy` and `voidedBy` narrow rather than widen on the audit endpoint, so "touched" means
+ * merging two searches. Neither is read to the end: both return observations by audit date
+ * descending, so the merge yields encounters in the order the list wants them, and reading stops as
+ * soon as enough encounters are certain to fill the page being viewed. Paging further reads further,
+ * and paging back costs nothing, since what has been read is kept.
+ *
+ * A date range is handed to both searches, which bound it against their own audit column, so a
+ * range narrows the trail on the server rather than after it has been read.
+ *
+ * See `discoverEncounters` for why partial reads still give a stable order, and `countUserObs` for
+ * how the per-encounter counts are made exact for the rows on screen.
+ */
+export function useUserEncounters(
+  userUuid: string | null,
+  pageSize: number,
+  dateRange: DateRange,
+  encounterTypeUuid?: string,
+): {
+  activity: Array<UserEncounterActivity>;
+  currentPage: number;
+  goTo(page: number): void;
+  firstRowOnPage: number;
+  hasNextPage: boolean;
+  obsRead: number;
+  /** True when the scan gave up before the trail ran out, so more may match than is shown. */
+  stoppedEarly: boolean;
+  /**
+   * True while the trail is still being read behind a list that already has rows in it — which a
+   * filter makes common, since matching rows trickle in as more of the trail is read.
+   */
+  isDiscovering: boolean;
+  error: unknown;
+  isLoading: boolean;
+} {
+  const [page, setPage] = useState(1);
+  const [created, setCreated] = useState<ObsStream>(emptyStream);
+  const [voided, setVoided] = useState<ObsStream>(emptyStream);
+  const [isScanning, setIsScanning] = useState(false);
+  const [stoppedEarly, setStoppedEarly] = useState(false);
+  const [error, setError] = useState<unknown>(undefined);
+
+  // The range identifies the search rather than forming part of a url: each stream now builds its
+  // own date query against the column it searched on.
+  const dateKey = `${dateRange.fromDate ?? ''}..${dateRange.toDate ?? ''}`;
+
+  /**
+   * Identifies the search the streams belong to — the account and the range both, since changing
+   * either changes which observations exist — so a scan that was in flight when it changed cannot
+   * append its rows to the results of a different search.
+   */
+  const scanToken = useRef<string | null>(null);
+  const searchKey = userUuid ? `${userUuid}${dateKey}` : null;
+
+  useEffect(() => {
+    scanToken.current = searchKey;
+    setPage(1);
+    setCreated(emptyStream);
+    setVoided(emptyStream);
+    setStoppedEarly(false);
+    setError(undefined);
+  }, [searchKey]);
+
+  /**
+   * The type filter is applied here rather than by the server, so changing it does not invalidate
+   * what has been read — only which page of it is being looked at, and possibly how much more of
+   * the trail has to be read to fill that page.
+   */
+  useEffect(() => {
+    setPage(1);
+  }, [encounterTypeUuid]);
+
+  const discovered = useMemo(
+    () => filterByEncounterType(discoverEncounters(created, voided), encounterTypeUuid),
+    [created, encounterTypeUuid, voided],
+  );
+  const needed = page * pageSize;
+  // One more than the page needs, so that whether a next page exists is known without reading a
+  // whole further page of encounters.
+  const wanted = needed + 1;
+
+  useEffect(() => {
+    const token = searchKey;
+    if (!userUuid || !token || discovered.length >= wanted || !canDiscoverMore(created, voided)) {
+      return;
+    }
+
+    let cancelled = false;
+    // `includeVoided=true` because this is an audit: the endpoint leaves voided observations out
+    // unless asked, and the voidedBy stream would come back empty without it. The rows carry a
+    // `voided` flag so what was deleted can be told from what survives.
+    //
+    // The ordering and the date range are per stream rather than on the base url: the endpoint
+    // sorts nothing unless asked and bounds no column unless told which, and each stream wants the
+    // column belonging to the action it searched on.
+    const baseUrl = `${obsAuditUrl}?includeVoided=true&v=${obsAuditRep}`;
+
+    (async () => {
+      setIsScanning(true);
+      try {
+        let nextCreated = created;
+        let nextVoided = voided;
+        for (let request = 0; request < maxScanRequestsPerPage; request++) {
+          const action = streamToExtend(nextCreated, nextVoided);
+          if (!action) {
+            break;
+          }
+          if (action === 'created') {
+            nextCreated = await extendStream(
+              `${baseUrl}&createdBy=${userUuid}${obsSortQuery('dateCreated')}` +
+                buildAuditDateQuery(dateRange, OBS_CREATED_DATE_PARAMS),
+              nextCreated,
+            );
+          } else {
+            nextVoided = await extendStream(
+              `${baseUrl}&voidedBy=${userUuid}${obsSortQuery('dateVoided')}` +
+                buildAuditDateQuery(dateRange, OBS_VOIDED_DATE_PARAMS),
+              nextVoided,
+            );
+          }
+          if (cancelled || scanToken.current !== token) {
+            return;
+          }
+          if (filterByEncounterType(discoverEncounters(nextCreated, nextVoided), encounterTypeUuid).length >= wanted) {
+            break;
+          }
+        }
+        setCreated(nextCreated);
+        setVoided(nextVoided);
+        // Whether it ran out of trail or out of patience is the difference between an empty result
+        // that means "nothing more" and one that means "not found yet".
+        setStoppedEarly(
+          canDiscoverMore(nextCreated, nextVoided) &&
+            filterByEncounterType(discoverEncounters(nextCreated, nextVoided), encounterTypeUuid).length < wanted,
+        );
+      } catch (e) {
+        setError(e);
+      } finally {
+        if (!cancelled) {
+          setIsScanning(false);
+        }
+      }
+    })();
+
+    return () => {
+      cancelled = true;
+    };
+    // `created` and `voided` are the accumulators this effect appends to; re-running on them is how
+    // it continues a scan that needed more than one round.
+  }, [created, voided, dateKey, dateRange, discovered.length, encounterTypeUuid, searchKey, userUuid, wanted]);
+
+  const firstRowOnPage = (page - 1) * pageSize;
+  const pageRows = useMemo(
+    () => discovered.slice(firstRowOnPage, firstRowOnPage + pageSize),
+    [discovered, firstRowOnPage, pageSize],
+  );
+
+  // Exact counts for the rows on screen only: one small read per encounter, not per audit trail.
+  const countsResult = useSWR<Record<string, { obsCreated: number; obsVoided: number }>>(
+    userUuid && pageRows.length ? ['audit-user-obs-counts', userUuid, pageRows.map((row) => row.encounter.uuid)] : null,
+    async () => {
+      const uuids = pageRows.map((row) => row.encounter.uuid);
+      const counted = await mapWithConcurrency(uuids, scanConcurrency, async (encounterUuid) => {
+        const obs = await fetchAllPages<AuditObs>(
+          `${restBaseUrl}/obs?encounter=${encounterUuid}&includeAll=true&v=custom:(uuid,voided,auditInfo)`,
+        );
+        return countUserObs(obs, userUuid);
+      });
+      return Object.fromEntries(uuids.map((encounterUuid, index) => [encounterUuid, counted[index]]));
+    },
+  );
+
+  const activity = useMemo(
+    () => pageRows.map((row) => ({ ...row, ...countsResult.data?.[row.encounter.uuid] })),
+    [countsResult.data, pageRows],
+  );
+
+  return {
+    activity,
+    currentPage: page,
+    goTo: setPage,
+    firstRowOnPage,
+    hasNextPage: discovered.length > needed,
+    obsRead: created.obs.length + voided.obs.length,
+    stoppedEarly,
+    isDiscovering: isScanning && pageRows.length > 0,
+    error: error ?? countsResult.error,
+    isLoading: (isScanning && pageRows.length === 0) || (pageRows.length > 0 && countsResult.isLoading),
+  };
+}

package/src/audit/audit.scss

@@ -169,3 +169,9 @@
 .selectedRow td {
   background-color: $color-blue-10;
 }
+
+/* Sits above the pager while the trail is still being read, so the list does not look finished. */
+.discovering {
+  min-height: auto;
+  margin-bottom: layout.$spacing-03;
+}

package/src/audit/date-range-picker.test-stub.tsx

@@ -0,0 +1,40 @@
+import React, { useState } from 'react';
+import { OpenmrsDateRangePicker, type OpenmrsDateRangePickerProps } from '@openmrs/esm-framework';
+
+/** Reads `MM/DD/YYYY` into something shaped like the react-aria dates the real picker reports. */
+function parsePickerDate(text: string | undefined) {
+  const match = /^(\d{2})\/(\d{2})\/(\d{4})$/.exec(text?.trim() ?? '');
+  if (!match) {
+    return null;
+  }
+  const [, month, day, year] = match.map(Number);
+  return { toDate: () => new Date(year, month - 1, day) };
+}
+
+/**
+ * Stands in for `OpenmrsDateRangePicker` the way the real one behaves, which the framework's own
+ * mock does not: react-aria reports the range through `onChangeRaw`, and reports `null` on every
+ * change until both ends are complete. Type the range as `MM/DD/YYYY–MM/DD/YYYY`.
+ */
+export function stubDateRangePicker() {
+  jest
+    .mocked(OpenmrsDateRangePicker)
+    .mockImplementation(({ id, labelText, onChangeRaw }: OpenmrsDateRangePickerProps) => {
+      const [text, setText] = useState('');
+      return (
+        <div>
+          <label htmlFor={id}>{labelText}</label>
+          <input
+            id={id}
+            onChange={(event) => {
+              setText(event.target.value);
+              const [start, end] = event.target.value.split('–').map(parsePickerDate);
+              onChangeRaw?.(start && end ? ({ start, end } as never) : null);
+            }}
+            type="text"
+            value={text}
+          />
+        </div>
+      );
+    });
+}

package/src/audit/date-range.test.ts

@@ -0,0 +1,128 @@
+import {
+  buildAuditDateQuery,
+  ENCOUNTER_DATE_PARAMS,
+  fromDateKey,
+  fromPickerRange,
+  toPickerDefault,
+  hasDateRange,
+  OBS_CREATED_DATE_PARAMS,
+  OBS_VOIDED_DATE_PARAMS,
+  toDateKey,
+} from './date-range';
+
+describe('date keys', () => {
+  it('reads the calendar date a moment falls on', () => {
+    expect(toDateKey(new Date(2026, 8, 10, 14, 30))).toBe('2026-09-10');
+    expect(toDateKey(new Date(2026, 0, 5))).toBe('2026-01-05');
+  });
+
+  it('has nothing to say about a missing or unparseable date', () => {
+    expect(toDateKey(null)).toBeUndefined();
+    expect(toDateKey(undefined)).toBeUndefined();
+    expect(toDateKey(new Date('nonsense'))).toBeUndefined();
+  });
+
+  it('round-trips back to local midnight, not to UTC midnight', () => {
+    const date = fromDateKey('2026-09-10');
+
+    expect(date?.getHours()).toBe(0);
+    expect(toDateKey(date)).toBe('2026-09-10');
+  });
+
+  it('has nothing to round-trip when no date is set', () => {
+    expect(fromDateKey(undefined)).toBeNull();
+    expect(fromDateKey('')).toBeNull();
+  });
+});
+
+describe('fromPickerRange', () => {
+  // `new Date` would read a year below 100 as 19xx, where react-aria's `toDate` keeps it as typed
+  const pickerDate = (year: number, month: number, day: number) => ({
+    toDate: () => {
+      const date = new Date(2000, month - 1, day);
+      date.setFullYear(year);
+      return date;
+    },
+  });
+
+  it('reads a complete range as calendar dates', () => {
+    expect(fromPickerRange({ start: pickerDate(2026, 9, 1), end: pickerDate(2026, 9, 30) })).toEqual({
+      fromDate: '2026-09-01',
+      toDate: '2026-09-30',
+    });
+  });
+
+  /** What the picker reports on every keystroke until both ends of the range are complete. */
+  it('reads an incomplete range as no range at all', () => {
+    expect(hasDateRange(fromPickerRange(null))).toBe(false);
+    expect(hasDateRange(fromPickerRange(undefined))).toBe(false);
+  });
+
+  /** What the picker reports on the way to typing a year, as 2 and then 20 on the way to 2026. */
+  it('reads a range the picker would reject as no range at all', () => {
+    expect(hasDateRange(fromPickerRange({ start: pickerDate(2026, 9, 1), end: pickerDate(20, 9, 30) }))).toBe(false);
+    expect(hasDateRange(fromPickerRange({ start: pickerDate(20, 9, 1), end: pickerDate(2026, 9, 30) }))).toBe(false);
+  });
+});
+
+describe('toPickerDefault', () => {
+  it('seeds the picker with a range that is set', () => {
+    expect(toPickerDefault({ fromDate: '2026-09-01', toDate: '2026-09-30' })).toEqual([
+      new Date(2026, 8, 1),
+      new Date(2026, 8, 30),
+    ]);
+  });
+
+  /** An empty value hides what react-aria holds of a half-typed range; see `toPickerDefault`. */
+  it('leaves the picker empty rather than holding an empty range', () => {
+    expect(toPickerDefault({})).toBeUndefined();
+  });
+});
+
+describe('hasDateRange', () => {
+  it('knows when either end is set', () => {
+    expect(hasDateRange({})).toBe(false);
+    expect(hasDateRange({ fromDate: '2026-09-01' })).toBe(true);
+    expect(hasDateRange({ toDate: '2026-09-30' })).toBe(true);
+  });
+});
+
+describe('buildAuditDateQuery', () => {
+  it('sends nothing when no range is set', () => {
+    expect(buildAuditDateQuery({}, OBS_CREATED_DATE_PARAMS)).toBe('');
+  });
+
+  /**
+   * Bare dates on purpose: the pihapps endpoints read a date-only upper bound as the whole of that day,
+   * so spelling out a time would only risk disagreeing with it.
+   */
+  it('sends the range as plain calendar dates', () => {
+    expect(buildAuditDateQuery({ fromDate: '2026-09-01', toDate: '2026-09-30' }, OBS_CREATED_DATE_PARAMS)).toBe(
+      '&createdOnOrAfter=2026-09-01&createdOnOrBefore=2026-09-30',
+    );
+  });
+
+  it('sends whichever end is set on its own', () => {
+    expect(buildAuditDateQuery({ fromDate: '2026-09-01' }, OBS_CREATED_DATE_PARAMS)).toBe(
+      '&createdOnOrAfter=2026-09-01',
+    );
+    expect(buildAuditDateQuery({ toDate: '2026-09-30' }, OBS_CREATED_DATE_PARAMS)).toBe(
+      '&createdOnOrBefore=2026-09-30',
+    );
+  });
+
+  /** Each stream of an obs audit bounds the column it searched on, so they differ from each other. */
+  it('names the bounds the way the voided obs stream does when asked to', () => {
+    expect(buildAuditDateQuery({ fromDate: '2026-09-01', toDate: '2026-09-30' }, OBS_VOIDED_DATE_PARAMS)).toBe(
+      '&voidedOnOrAfter=2026-09-01&voidedOnOrBefore=2026-09-30',
+    );
+  });
+
+  /** No two endpoints agree on what the bounds are called, hence the parameter. */
+  it('names the bounds the way the encounter endpoint does when asked to', () => {
+    expect(buildAuditDateQuery({ fromDate: '2026-09-01', toDate: '2026-09-30' }, ENCOUNTER_DATE_PARAMS)).toBe(
+      '&encounterDatetimeOnOrAfter=2026-09-01&encounterDatetimeOnOrBefore=2026-09-30',
+    );
+    expect(buildAuditDateQuery({}, ENCOUNTER_DATE_PARAMS)).toBe('');
+  });
+});