@openmrs/esm-react-utils 10.0.1-pre.5434 → 10.0.1-pre.5452

package/.turbo/turbo-build.log

@@ -1,3 +1,3 @@
-[0] Successfully compiled: 55 files with swc (157.5ms)
+[0] Successfully compiled: 55 files with swc (132.12ms)
 [0] swc --strip-leading-paths src -d dist exited with code 0
 [1] tsc --project tsconfig.build.json exited with code 0

package/dist/useAttachments.d.ts

@@ -5,8 +5,12 @@ import { type AttachmentResponse } from '@openmrs/esm-emr-api';
  * and automatic revalidation.
  *
  * @param patientUuid The UUID of the patient whose attachments should be fetched.
+ *   Nothing is fetched while this is empty, so callers can defer the request.
  * @param includeEncounterless Whether to include attachments that are not
- *   associated with any encounter.
+ *   associated with any encounter. Ignored when `encounterUuid` is set.
+ * @param encounterUuid When set, only attachments recorded on this encounter are
+ *   returned. An unknown encounter UUID makes the server fall back to every attachment
+ *   of the patient, so only pass a UUID you have loaded.
  * @returns An object containing:
  *   - `data`: Array of attachment objects (empty array while loading)
  *   - `isLoading`: Whether the initial fetch is in progress
@@ -23,9 +27,12 @@ import { type AttachmentResponse } from '@openmrs/esm-emr-api';
  *   if (error) return <span>Error loading attachments</span>;
  *   return <AttachmentList attachments={data} />;
  * }
+ *
+ * // Only the attachments recorded on one encounter
+ * const { data } = useAttachments(patientUuid, false, encounterUuid);
  * ```
  */
-export declare function useAttachments(patientUuid: string, includeEncounterless: boolean): {
+export declare function useAttachments(patientUuid: string | null | undefined, includeEncounterless: boolean, encounterUuid?: string): {
     isLoading: boolean;
     data: AttachmentResponse[];
     error: any;

package/dist/useAttachments.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useAttachments.d.ts","sourceRoot":"","sources":["../src/useAttachments.ts"],"names":[],"mappings":"AAGA,OAAO,EAAgB,KAAK,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACpE,OAAO,EAAiB,KAAK,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE9E;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,oBAAoB,EAAE,OAAO;;;;;iBAEpD,KAAK,CAAC,kBAAkB,CAAC;;;EAerD"}
+{"version":3,"file":"useAttachments.d.ts","sourceRoot":"","sources":["../src/useAttachments.ts"],"names":[],"mappings":"AAGA,OAAO,EAAgB,KAAK,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACpE,OAAO,EAAqB,KAAK,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAElF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,cAAc,CAC5B,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACtC,oBAAoB,EAAE,OAAO,EAC7B,aAAa,CAAC,EAAE,MAAM;;;;;iBAGK,KAAK,CAAC,kBAAkB,CAAC;;;EAerD"}

package/dist/useAttachments.js

@@ -1,14 +1,18 @@
 /** @module @category API */ import { useMemo } from "react";
 import useSWR from "swr";
 import { openmrsFetch } from "@openmrs/esm-api";
-import { attachmentUrl } from "@openmrs/esm-emr-api";
+import { getAttachmentsUrl } from "@openmrs/esm-emr-api";
 /**
  * A React hook that fetches attachments for a patient using SWR for caching
  * and automatic revalidation.
  *
  * @param patientUuid The UUID of the patient whose attachments should be fetched.
+ *   Nothing is fetched while this is empty, so callers can defer the request.
  * @param includeEncounterless Whether to include attachments that are not
- *   associated with any encounter.
+ *   associated with any encounter. Ignored when `encounterUuid` is set.
+ * @param encounterUuid When set, only attachments recorded on this encounter are
+ *   returned. An unknown encounter UUID makes the server fall back to every attachment
+ *   of the patient, so only pass a UUID you have loaded.
  * @returns An object containing:
  *   - `data`: Array of attachment objects (empty array while loading)
  *   - `isLoading`: Whether the initial fetch is in progress
@@ -25,9 +29,12 @@ import { attachmentUrl } from "@openmrs/esm-emr-api";
  *   if (error) return <span>Error loading attachments</span>;
  *   return <AttachmentList attachments={data} />;
  * }
+ *
+ * // Only the attachments recorded on one encounter
+ * const { data } = useAttachments(patientUuid, false, encounterUuid);
  * ```
- */ export function useAttachments(patientUuid, includeEncounterless) {
-    const { data, error, mutate, isLoading, isValidating } = useSWR(`${attachmentUrl}?patient=${patientUuid}&includeEncounterless=${includeEncounterless}`, openmrsFetch);
+ */ export function useAttachments(patientUuid, includeEncounterless, encounterUuid) {
+    const { data, error, mutate, isLoading, isValidating } = useSWR(patientUuid ? getAttachmentsUrl(patientUuid, includeEncounterless, encounterUuid) : null, openmrsFetch);
     const results = useMemo(()=>({
             isLoading,
             data: data?.data.results ?? [],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openmrs/esm-react-utils",
-  "version": "10.0.1-pre.5434",
+  "version": "10.0.1-pre.5452",
   "license": "MPL-2.0",
   "description": "React utilities for OpenMRS.",
   "type": "module",
@@ -60,17 +60,17 @@
     "single-spa-react": "^6.0.2"
   },
   "peerDependencies": {
-    "@openmrs/esm-api": "^10.0.1-pre.5434",
-    "@openmrs/esm-config": "^10.0.1-pre.5434",
-    "@openmrs/esm-context": "^10.0.1-pre.5434",
-    "@openmrs/esm-emr-api": "^10.0.1-pre.5434",
-    "@openmrs/esm-error-handling": "^10.0.1-pre.5434",
-    "@openmrs/esm-extensions": "^10.0.1-pre.5434",
-    "@openmrs/esm-feature-flags": "^10.0.1-pre.5434",
-    "@openmrs/esm-globals": "^10.0.1-pre.5434",
-    "@openmrs/esm-navigation": "^10.0.1-pre.5434",
-    "@openmrs/esm-state": "^10.0.1-pre.5434",
-    "@openmrs/esm-utils": "^10.0.1-pre.5434",
+    "@openmrs/esm-api": "^10.0.1-pre.5452",
+    "@openmrs/esm-config": "^10.0.1-pre.5452",
+    "@openmrs/esm-context": "^10.0.1-pre.5452",
+    "@openmrs/esm-emr-api": "^10.0.1-pre.5452",
+    "@openmrs/esm-error-handling": "^10.0.1-pre.5452",
+    "@openmrs/esm-extensions": "^10.0.1-pre.5452",
+    "@openmrs/esm-feature-flags": "^10.0.1-pre.5452",
+    "@openmrs/esm-globals": "^10.0.1-pre.5452",
+    "@openmrs/esm-navigation": "^10.0.1-pre.5452",
+    "@openmrs/esm-state": "^10.0.1-pre.5452",
+    "@openmrs/esm-utils": "^10.0.1-pre.5452",
     "dayjs": "1.x",
     "i18next": "25.x",
     "react": "18.x",
@@ -80,17 +80,17 @@
     "swr": "2.x"
   },
   "devDependencies": {
-    "@openmrs/esm-api": "10.0.1-pre.5434",
-    "@openmrs/esm-config": "10.0.1-pre.5434",
-    "@openmrs/esm-context": "10.0.1-pre.5434",
-    "@openmrs/esm-emr-api": "10.0.1-pre.5434",
-    "@openmrs/esm-error-handling": "10.0.1-pre.5434",
-    "@openmrs/esm-extensions": "10.0.1-pre.5434",
-    "@openmrs/esm-feature-flags": "10.0.1-pre.5434",
-    "@openmrs/esm-globals": "10.0.1-pre.5434",
-    "@openmrs/esm-navigation": "10.0.1-pre.5434",
-    "@openmrs/esm-state": "10.0.1-pre.5434",
-    "@openmrs/esm-utils": "10.0.1-pre.5434",
+    "@openmrs/esm-api": "10.0.1-pre.5452",
+    "@openmrs/esm-config": "10.0.1-pre.5452",
+    "@openmrs/esm-context": "10.0.1-pre.5452",
+    "@openmrs/esm-emr-api": "10.0.1-pre.5452",
+    "@openmrs/esm-error-handling": "10.0.1-pre.5452",
+    "@openmrs/esm-extensions": "10.0.1-pre.5452",
+    "@openmrs/esm-feature-flags": "10.0.1-pre.5452",
+    "@openmrs/esm-globals": "10.0.1-pre.5452",
+    "@openmrs/esm-navigation": "10.0.1-pre.5452",
+    "@openmrs/esm-state": "10.0.1-pre.5452",
+    "@openmrs/esm-utils": "10.0.1-pre.5452",
     "@swc/cli": "0.8.1",
     "@swc/core": "1.15.21",
     "@vitest/coverage-v8": "^4.1.2",

package/src/useAttachments.test.tsx

@@ -0,0 +1,71 @@
+import React from 'react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { renderHook, waitFor } from '@testing-library/react';
+import { SWRConfig } from 'swr';
+import { openmrsFetch, type FetchResponse } from '@openmrs/esm-api';
+import { attachmentUrl, type AttachmentResponse } from '@openmrs/esm-emr-api';
+import { useAttachments } from './useAttachments';
+
+vi.mock('@openmrs/esm-api', async (importOriginal) => ({
+  ...(await importOriginal<typeof import('@openmrs/esm-api')>()),
+  openmrsFetch: vi.fn(),
+}));
+
+const mockOpenmrsFetch = vi.mocked(openmrsFetch);
+
+const attachment: AttachmentResponse = {
+  uuid: 'attachment-uuid',
+  filename: 'photo.png',
+  comment: 'Wound photo',
+  dateTime: '2026-09-18T10:00:00.000+0000',
+  bytesMimeType: 'image/png',
+  bytesContentFamily: 'IMAGE',
+};
+
+// Each test gets its own SWR cache so keys requested in one test do not satisfy the next.
+const wrapper = ({ children }: { children: React.ReactNode }) => (
+  <SWRConfig value={{ provider: () => new Map(), dedupingInterval: 0 }}>{children}</SWRConfig>
+);
+
+describe('useAttachments', () => {
+  beforeEach(() => {
+    mockOpenmrsFetch.mockReset();
+    mockOpenmrsFetch.mockResolvedValue({ data: { results: [attachment] } } as FetchResponse<{
+      results: Array<AttachmentResponse>;
+    }>);
+  });
+
+  it('fetches the patient attachments and unwraps the results', async () => {
+    const { result } = renderHook(() => useAttachments('patient-uuid', true), { wrapper });
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    expect(mockOpenmrsFetch).toHaveBeenCalledWith(`${attachmentUrl}?patient=patient-uuid&includeEncounterless=true`);
+    expect(result.current.data).toEqual([attachment]);
+  });
+
+  it('fetches only the attachments on an encounter when one is given', async () => {
+    const { result } = renderHook(() => useAttachments('patient-uuid', true, 'encounter-uuid'), { wrapper });
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    expect(mockOpenmrsFetch).toHaveBeenCalledWith(`${attachmentUrl}?patient=patient-uuid&encounter=encounter-uuid`);
+    expect(result.current.data).toEqual([attachment]);
+  });
+
+  it('does not fetch while the patient UUID is empty', () => {
+    const { result } = renderHook(() => useAttachments(null, true), { wrapper });
+
+    expect(mockOpenmrsFetch).not.toHaveBeenCalled();
+    expect(result.current.isLoading).toBe(false);
+    expect(result.current.data).toEqual([]);
+  });
+
+  it('returns an empty list while loading', () => {
+    mockOpenmrsFetch.mockReturnValue(new Promise(() => {}));
+    const { result } = renderHook(() => useAttachments('patient-uuid', true), { wrapper });
+
+    expect(result.current.isLoading).toBe(true);
+    expect(result.current.data).toEqual([]);
+  });
+});

package/src/useAttachments.ts

@@ -2,15 +2,19 @@
 import { useMemo } from 'react';
 import useSWR from 'swr';
 import { openmrsFetch, type FetchResponse } from '@openmrs/esm-api';
-import { attachmentUrl, type AttachmentResponse } from '@openmrs/esm-emr-api';
+import { getAttachmentsUrl, type AttachmentResponse } from '@openmrs/esm-emr-api';
 
 /**
  * A React hook that fetches attachments for a patient using SWR for caching
  * and automatic revalidation.
  *
  * @param patientUuid The UUID of the patient whose attachments should be fetched.
+ *   Nothing is fetched while this is empty, so callers can defer the request.
  * @param includeEncounterless Whether to include attachments that are not
- *   associated with any encounter.
+ *   associated with any encounter. Ignored when `encounterUuid` is set.
+ * @param encounterUuid When set, only attachments recorded on this encounter are
+ *   returned. An unknown encounter UUID makes the server fall back to every attachment
+ *   of the patient, so only pass a UUID you have loaded.
  * @returns An object containing:
  *   - `data`: Array of attachment objects (empty array while loading)
  *   - `isLoading`: Whether the initial fetch is in progress
@@ -27,12 +31,19 @@ import { attachmentUrl, type AttachmentResponse } from '@openmrs/esm-emr-api';
  *   if (error) return <span>Error loading attachments</span>;
  *   return <AttachmentList attachments={data} />;
  * }
+ *
+ * // Only the attachments recorded on one encounter
+ * const { data } = useAttachments(patientUuid, false, encounterUuid);
  * ```
  */
-export function useAttachments(patientUuid: string, includeEncounterless: boolean) {
+export function useAttachments(
+  patientUuid: string | null | undefined,
+  includeEncounterless: boolean,
+  encounterUuid?: string,
+) {
   const { data, error, mutate, isLoading, isValidating } = useSWR<
     FetchResponse<{ results: Array<AttachmentResponse> }>
-  >(`${attachmentUrl}?patient=${patientUuid}&includeEncounterless=${includeEncounterless}`, openmrsFetch);
+  >(patientUuid ? getAttachmentsUrl(patientUuid, includeEncounterless, encounterUuid) : null, openmrsFetch);
 
   const results = useMemo(
     () => ({