@openmrs/esm-react-utils 8.0.1-pre.3783 → 8.0.1-pre.3786

package/.turbo/turbo-build.log

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

package/dist/ConfigurableLink.d.ts

@@ -1,9 +1,7 @@
 /** @module @category Navigation */
 import React, { type MouseEvent, type AnchorHTMLAttributes, type PropsWithChildren } from 'react';
 import { type TemplateParams } from '@openmrs/esm-navigation';
-/**
- * @noInheritDoc
- */
+/** @noInheritDoc */
 export interface ConfigurableLinkProps extends AnchorHTMLAttributes<HTMLAnchorElement> {
     /** The target path or URL. Supports interpolation. See [[navigate]] */
     to: string;
@@ -13,7 +11,7 @@ export interface ConfigurableLinkProps extends AnchorHTMLAttributes<HTMLAnchorEl
     onBeforeNavigate?: (event: MouseEvent) => void;
 }
 /**
- * A React link component which calls [[navigate]] when clicked
+ * A React link component which calls {@link navigate} when clicked
  */
 export declare function ConfigurableLink({ to, templateParams, onBeforeNavigate, children, ...otherProps }: PropsWithChildren<ConfigurableLinkProps>): React.JSX.Element;
 //# sourceMappingURL=ConfigurableLink.d.ts.map

package/dist/ConfigurableLink.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ConfigurableLink.d.ts","sourceRoot":"","sources":["../src/ConfigurableLink.tsx"],"names":[],"mappings":"AAAA,mCAAmC;AACnC,OAAO,KAAK,EAAE,EAAE,KAAK,UAAU,EAAE,KAAK,oBAAoB,EAAE,KAAK,iBAAiB,EAAa,MAAM,OAAO,CAAC;AAC7G,OAAO,EAA4B,KAAK,cAAc,EAAE,MAAM,yBAAyB,CAAC;AA+BxF;;GAEG;AACH,MAAM,WAAW,qBAAsB,SAAQ,oBAAoB,CAAC,iBAAiB,CAAC;IACpF,uEAAuE;IACvE,EAAE,EAAE,MAAM,CAAC;IACX,8HAA8H;IAC9H,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,4DAA4D;IAC5D,gBAAgB,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;CAChD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,EAC/B,EAAE,EACF,cAAc,EACd,gBAAgB,EAChB,QAAQ,EACR,GAAG,UAAU,EACd,EAAE,iBAAiB,CAAC,qBAAqB,CAAC,qBAsB1C"}
+{"version":3,"file":"ConfigurableLink.d.ts","sourceRoot":"","sources":["../src/ConfigurableLink.tsx"],"names":[],"mappings":"AAAA,mCAAmC;AACnC,OAAO,KAAK,EAAE,EAAE,KAAK,UAAU,EAAE,KAAK,oBAAoB,EAAE,KAAK,iBAAiB,EAAa,MAAM,OAAO,CAAC;AAC7G,OAAO,EAA4B,KAAK,cAAc,EAAE,MAAM,yBAAyB,CAAC;AA+BxF,oBAAoB;AACpB,MAAM,WAAW,qBAAsB,SAAQ,oBAAoB,CAAC,iBAAiB,CAAC;IACpF,uEAAuE;IACvE,EAAE,EAAE,MAAM,CAAC;IACX,8HAA8H;IAC9H,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,4DAA4D;IAC5D,gBAAgB,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;CAChD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,EAC/B,EAAE,EACF,cAAc,EACd,gBAAgB,EAChB,QAAQ,EACR,GAAG,UAAU,EACd,EAAE,iBAAiB,CAAC,qBAAqB,CAAC,qBAsB1C"}

package/dist/ConfigurableLink.js

@@ -24,7 +24,7 @@ function handleClick(event, to, templateParams, onBeforeNavigate) {
     }
 }
 /**
- * A React link component which calls [[navigate]] when clicked
+ * A React link component which calls {@link navigate} when clicked
  */ export function ConfigurableLink({ to, templateParams, onBeforeNavigate, children, ...otherProps }) {
     useEffect(()=>{
         if (otherProps.href) {

package/dist/getLifecycle.d.ts

@@ -2,10 +2,62 @@
 import type { ComponentType } from 'react';
 import singleSpaReact from 'single-spa-react';
 import type { ComponentDecoratorOptions } from './openmrsComponentDecorator';
+/**
+ * Creates a single-spa lifecycle object for a React component. The component is
+ * wrapped with the OpenMRS component decorator which provides standard functionality
+ * like error boundaries, configuration, and extension support.
+ *
+ * @param Component The React component to create a lifecycle for.
+ * @param options Configuration options for the OpenMRS component decorator.
+ * @returns A single-spa lifecycle object with bootstrap, mount, and unmount functions.
+ *
+ * @example
+ * ```ts
+ * import { getLifecycle } from '@openmrs/esm-framework';
+ * import MyComponent from './MyComponent';
+ * export const lifecycle = getLifecycle(MyComponent, { featureName: 'my-feature', moduleName: '@openmrs/esm-my-app' });
+ * ```
+ */
 export declare function getLifecycle<T>(Component: ComponentType<T>, options: ComponentDecoratorOptions): singleSpaReact.ReactAppOrParcel<T>;
+/**
+ * Creates a lazy-loading single-spa lifecycle for a React component. The component
+ * is loaded asynchronously via dynamic import only when it's needed, which helps
+ * reduce initial bundle size. This is the recommended way to define lifecycles
+ * for most modules.
+ *
+ * @param lazy A function that returns a Promise resolving to a module with the
+ *   component as its default export (i.e., a dynamic import).
+ * @param options Configuration options for the OpenMRS component decorator.
+ * @returns A function that returns a Promise resolving to a single-spa lifecycle object.
+ *
+ * @example
+ * ```ts
+ * import { getAsyncLifecycle } from '@openmrs/esm-framework';
+ * const options = { featureName: 'my-feature', moduleName: '@openmrs/esm-my-app' };
+ * export const root = getAsyncLifecycle(() => import('./root.component'), options);
+ * ```
+ */
 export declare function getAsyncLifecycle<T>(lazy: () => Promise<{
     default: ComponentType<T>;
 }>, options: ComponentDecoratorOptions): () => Promise<singleSpaReact.ReactAppOrParcel<T>>;
+/**
+ * Creates a single-spa lifecycle for a React component that is already loaded.
+ * Unlike {@link getAsyncLifecycle}, this wraps a synchronously-available component
+ * in a Promise to match the expected lifecycle interface. Use this when the
+ * component doesn't need lazy loading.
+ *
+ * @param Component The React component to create a lifecycle for.
+ * @param options Configuration options for the OpenMRS component decorator.
+ * @returns A function that returns a Promise resolving to a single-spa lifecycle object.
+ *
+ * @example
+ * ```ts
+ * import { getSyncLifecycle } from '@openmrs/esm-framework';
+ * import MyComponent from './MyComponent';
+ * const options = { featureName: 'my-feature', moduleName: '@openmrs/esm-my-app' };
+ * export const myExtension = getSyncLifecycle(MyComponent, options);
+ * ```
+ */
 export declare function getSyncLifecycle<T>(Component: ComponentType<T>, options: ComponentDecoratorOptions): () => Promise<singleSpaReact.ReactAppOrParcel<T>>;
 /**
  * @deprecated Use getAsyncLifecycle instead.

package/dist/getLifecycle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"getLifecycle.d.ts","sourceRoot":"","sources":["../src/getLifecycle.ts"],"names":[],"mappings":"AAAA,kCAAkC;AAClC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAI3C,OAAO,cAAyC,MAAM,kBAAkB,CAAC;AACzE,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,6BAA6B,CAAC;AAG7E,wBAAgB,YAAY,CAAC,CAAC,EAAE,SAAS,EAAE,aAAa,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,yBAAyB,sCAM9F;AAED,wBAAgB,iBAAiB,CAAC,CAAC,EACjC,IAAI,EAAE,MAAM,OAAO,CAAC;IAAE,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,CAAA;CAAE,CAAC,EAClD,OAAO,EAAE,yBAAyB,qDAGnC;AAED,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,SAAS,EAAE,aAAa,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,yBAAyB,qDAElG;AAED;;GAEG;AACH,eAAO,MAAM,0BAA0B,0BAAoB,CAAC"}
+{"version":3,"file":"getLifecycle.d.ts","sourceRoot":"","sources":["../src/getLifecycle.ts"],"names":[],"mappings":"AAAA,kCAAkC;AAClC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAI3C,OAAO,cAAyC,MAAM,kBAAkB,CAAC;AACzE,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,6BAA6B,CAAC;AAG7E;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,SAAS,EAAE,aAAa,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,yBAAyB,sCAM9F;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EACjC,IAAI,EAAE,MAAM,OAAO,CAAC;IAAE,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,CAAA;CAAE,CAAC,EAClD,OAAO,EAAE,yBAAyB,qDAGnC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,SAAS,EAAE,aAAa,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,yBAAyB,qDAElG;AAED;;GAEG;AACH,eAAO,MAAM,0BAA0B,0BAAoB,CAAC"}

package/dist/getLifecycle.js

@@ -2,17 +2,66 @@
 import ReactDOMClient from "react-dom/client";
 import singleSpaReact from "single-spa-react";
 import { openmrsComponentDecorator } from "./openmrsComponentDecorator.js";
-export function getLifecycle(Component, options) {
+/**
+ * Creates a single-spa lifecycle object for a React component. The component is
+ * wrapped with the OpenMRS component decorator which provides standard functionality
+ * like error boundaries, configuration, and extension support.
+ *
+ * @param Component The React component to create a lifecycle for.
+ * @param options Configuration options for the OpenMRS component decorator.
+ * @returns A single-spa lifecycle object with bootstrap, mount, and unmount functions.
+ *
+ * @example
+ * ```ts
+ * import { getLifecycle } from '@openmrs/esm-framework';
+ * import MyComponent from './MyComponent';
+ * export const lifecycle = getLifecycle(MyComponent, { featureName: 'my-feature', moduleName: '@openmrs/esm-my-app' });
+ * ```
+ */ export function getLifecycle(Component, options) {
     return singleSpaReact({
         React,
         ReactDOMClient,
         rootComponent: openmrsComponentDecorator(options)(Component)
     });
 }
-export function getAsyncLifecycle(lazy, options) {
+/**
+ * Creates a lazy-loading single-spa lifecycle for a React component. The component
+ * is loaded asynchronously via dynamic import only when it's needed, which helps
+ * reduce initial bundle size. This is the recommended way to define lifecycles
+ * for most modules.
+ *
+ * @param lazy A function that returns a Promise resolving to a module with the
+ *   component as its default export (i.e., a dynamic import).
+ * @param options Configuration options for the OpenMRS component decorator.
+ * @returns A function that returns a Promise resolving to a single-spa lifecycle object.
+ *
+ * @example
+ * ```ts
+ * import { getAsyncLifecycle } from '@openmrs/esm-framework';
+ * const options = { featureName: 'my-feature', moduleName: '@openmrs/esm-my-app' };
+ * export const root = getAsyncLifecycle(() => import('./root.component'), options);
+ * ```
+ */ export function getAsyncLifecycle(lazy, options) {
     return ()=>lazy().then(({ default: Component })=>getLifecycle(Component, options));
 }
-export function getSyncLifecycle(Component, options) {
+/**
+ * Creates a single-spa lifecycle for a React component that is already loaded.
+ * Unlike {@link getAsyncLifecycle}, this wraps a synchronously-available component
+ * in a Promise to match the expected lifecycle interface. Use this when the
+ * component doesn't need lazy loading.
+ *
+ * @param Component The React component to create a lifecycle for.
+ * @param options Configuration options for the OpenMRS component decorator.
+ * @returns A function that returns a Promise resolving to a single-spa lifecycle object.
+ *
+ * @example
+ * ```ts
+ * import { getSyncLifecycle } from '@openmrs/esm-framework';
+ * import MyComponent from './MyComponent';
+ * const options = { featureName: 'my-feature', moduleName: '@openmrs/esm-my-app' };
+ * export const myExtension = getSyncLifecycle(MyComponent, options);
+ * ```
+ */ export function getSyncLifecycle(Component, options) {
     return ()=>Promise.resolve(getLifecycle(Component, options));
 }
 /**

package/dist/useAttachments.d.ts

@@ -1,5 +1,30 @@
 import { type FetchResponse } from '@openmrs/esm-api';
 import { 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.
+ * @param includeEncounterless Whether to include attachments that are not
+ *   associated with any encounter.
+ * @returns An object containing:
+ *   - `data`: Array of attachment objects (empty array while loading)
+ *   - `isLoading`: Whether the initial fetch is in progress
+ *   - `isValidating`: Whether any request (initial or revalidation) is in progress
+ *   - `error`: Any error that occurred during fetching
+ *   - `mutate`: Function to trigger a revalidation of the data
+ *
+ * @example
+ * ```tsx
+ * import { useAttachments } from '@openmrs/esm-framework';
+ * function PatientAttachments({ patientUuid }) {
+ *   const { data, isLoading, error } = useAttachments(patientUuid, true);
+ *   if (isLoading) return <span>Loading...</span>;
+ *   if (error) return <span>Error loading attachments</span>;
+ *   return <AttachmentList attachments={data} />;
+ * }
+ * ```
+ */
 export declare function useAttachments(patientUuid: string, includeEncounterless: boolean): {
     isLoading: boolean;
     data: AttachmentResponse[];

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,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,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"}

package/dist/useAttachments.js

@@ -2,7 +2,31 @@
 import useSWR from "swr";
 import { openmrsFetch } from "@openmrs/esm-api";
 import { attachmentUrl } from "@openmrs/esm-emr-api";
-export function useAttachments(patientUuid, includeEncounterless) {
+/**
+ * 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.
+ * @param includeEncounterless Whether to include attachments that are not
+ *   associated with any encounter.
+ * @returns An object containing:
+ *   - `data`: Array of attachment objects (empty array while loading)
+ *   - `isLoading`: Whether the initial fetch is in progress
+ *   - `isValidating`: Whether any request (initial or revalidation) is in progress
+ *   - `error`: Any error that occurred during fetching
+ *   - `mutate`: Function to trigger a revalidation of the data
+ *
+ * @example
+ * ```tsx
+ * import { useAttachments } from '@openmrs/esm-framework';
+ * function PatientAttachments({ patientUuid }) {
+ *   const { data, isLoading, error } = useAttachments(patientUuid, true);
+ *   if (isLoading) return <span>Loading...</span>;
+ *   if (error) return <span>Error loading attachments</span>;
+ *   return <AttachmentList attachments={data} />;
+ * }
+ * ```
+ */ export function useAttachments(patientUuid, includeEncounterless) {
     const { data, error, mutate, isLoading, isValidating } = useSWR(`${attachmentUrl}?patient=${patientUuid}&includeEncounterless=${includeEncounterless}`, openmrsFetch);
     const results = useMemo(()=>({
             isLoading,

package/dist/useBodyScrollLock.d.ts

@@ -1,2 +1,20 @@
+/**
+ * A React hook that prevents scrolling on the document body when active.
+ * Useful for modals, overlays, or any full-screen UI that should prevent
+ * background scrolling. The original overflow style is restored when the
+ * hook becomes inactive or the component unmounts.
+ *
+ * @param active Whether to lock the body scroll. When `true`, sets
+ *   `document.body.style.overflow` to 'hidden'.
+ *
+ * @example
+ * ```tsx
+ * import { useBodyScrollLock } from '@openmrs/esm-framework';
+ * function Modal({ isOpen }) {
+ *   useBodyScrollLock(isOpen);
+ *   return isOpen ? <div className="modal">...</div> : null;
+ * }
+ * ```
+ */
 export declare function useBodyScrollLock(active: boolean): void;
 //# sourceMappingURL=useBodyScrollLock.d.ts.map

package/dist/useBodyScrollLock.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useBodyScrollLock.d.ts","sourceRoot":"","sources":["../src/useBodyScrollLock.ts"],"names":[],"mappings":"AAGA,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,OAAO,QAUhD"}
+{"version":3,"file":"useBodyScrollLock.d.ts","sourceRoot":"","sources":["../src/useBodyScrollLock.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,OAAO,QAUhD"}

package/dist/useBodyScrollLock.js

@@ -1,5 +1,22 @@
 /** @module @category UI */ import { useEffect } from "react";
-export function useBodyScrollLock(active) {
+/**
+ * A React hook that prevents scrolling on the document body when active.
+ * Useful for modals, overlays, or any full-screen UI that should prevent
+ * background scrolling. The original overflow style is restored when the
+ * hook becomes inactive or the component unmounts.
+ *
+ * @param active Whether to lock the body scroll. When `true`, sets
+ *   `document.body.style.overflow` to 'hidden'.
+ *
+ * @example
+ * ```tsx
+ * import { useBodyScrollLock } from '@openmrs/esm-framework';
+ * function Modal({ isOpen }) {
+ *   useBodyScrollLock(isOpen);
+ *   return isOpen ? <div className="modal">...</div> : null;
+ * }
+ * ```
+ */ export function useBodyScrollLock(active) {
     useEffect(()=>{
         if (active) {
             const original = window.getComputedStyle(document.body).overflow;

package/dist/useConnectivity.d.ts

@@ -1,2 +1,18 @@
+/**
+ * A React hook that returns the current online/offline status and automatically
+ * updates when connectivity changes. Useful for showing offline indicators or
+ * conditionally rendering UI based on network availability.
+ *
+ * @returns `true` if the browser is online, `false` if offline.
+ *
+ * @example
+ * ```tsx
+ * import { useConnectivity } from '@openmrs/esm-framework';
+ * function NetworkStatus() {
+ *   const isOnline = useConnectivity();
+ *   return <span>{isOnline ? 'Online' : 'Offline'}</span>;
+ * }
+ * ```
+ */
 export declare function useConnectivity(): boolean;
 //# sourceMappingURL=useConnectivity.d.ts.map

package/dist/useConnectivity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useConnectivity.d.ts","sourceRoot":"","sources":["../src/useConnectivity.ts"],"names":[],"mappings":"AAKA,wBAAgB,eAAe,YAM9B"}
+{"version":3,"file":"useConnectivity.d.ts","sourceRoot":"","sources":["../src/useConnectivity.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,YAM9B"}

package/dist/useConnectivity.js

@@ -1,7 +1,22 @@
 /** @module @category Offline */ import { subscribeConnectivityChanged } from "@openmrs/esm-globals";
 import { isOnline as isOnlineFn } from "@openmrs/esm-utils";
 import { useEffect, useState } from "react";
-export function useConnectivity() {
+/**
+ * A React hook that returns the current online/offline status and automatically
+ * updates when connectivity changes. Useful for showing offline indicators or
+ * conditionally rendering UI based on network availability.
+ *
+ * @returns `true` if the browser is online, `false` if offline.
+ *
+ * @example
+ * ```tsx
+ * import { useConnectivity } from '@openmrs/esm-framework';
+ * function NetworkStatus() {
+ *   const isOnline = useConnectivity();
+ *   return <span>{isOnline ? 'Online' : 'Offline'}</span>;
+ * }
+ * ```
+ */ export function useConnectivity() {
     let [isOnline, setIsOnline] = useState(isOnlineFn());
     useEffect(()=>subscribeConnectivityChanged(({ online })=>setIsOnline(online)), []);
     return isOnline;

package/dist/useLeftNav.d.ts

@@ -1,3 +1,23 @@
 import { type SetLeftNavParams } from '@openmrs/esm-extensions';
+/**
+ * A React hook that registers a left navigation menu for the current component.
+ * The navigation is automatically registered when the component mounts and
+ * unregistered when it unmounts.
+ *
+ * **Important:** This hook should only be used in "page" components, not in
+ * "extension" components. Extensions should not control the left navigation.
+ *
+ * @param params Configuration parameters for the left navigation, excluding the
+ *   module name which is automatically determined from the component context.
+ *
+ * @example
+ * ```tsx
+ * import { useLeftNav } from '@openmrs/esm-framework';
+ * function MyPageComponent() {
+ *   useLeftNav({ name: 'my-nav', slots: ['nav-slot-1', 'nav-slot-2'] });
+ *   return <div>My Page</div>;
+ * }
+ * ```
+ */
 export declare function useLeftNav(params: Omit<SetLeftNavParams, 'module'>): void;
 //# sourceMappingURL=useLeftNav.d.ts.map

package/dist/useLeftNav.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useLeftNav.d.ts","sourceRoot":"","sources":["../src/useLeftNav.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,gBAAgB,EAA4B,MAAM,yBAAyB,CAAC;AAG1F,wBAAgB,UAAU,CAAC,MAAM,EAAE,IAAI,CAAC,gBAAgB,EAAE,QAAQ,CAAC,QAclE"}
+{"version":3,"file":"useLeftNav.d.ts","sourceRoot":"","sources":["../src/useLeftNav.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,gBAAgB,EAA4B,MAAM,yBAAyB,CAAC;AAG1F;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,IAAI,CAAC,gBAAgB,EAAE,QAAQ,CAAC,QAclE"}

package/dist/useLeftNav.js

@@ -1,7 +1,26 @@
-import { useContext, useEffect } from "react";
+/** @module @category UI */ import { useContext, useEffect } from "react";
 import { setLeftNav, unsetLeftNav } from "@openmrs/esm-extensions";
 import { ComponentContext } from "./ComponentContext.js";
-export function useLeftNav(params) {
+/**
+ * A React hook that registers a left navigation menu for the current component.
+ * The navigation is automatically registered when the component mounts and
+ * unregistered when it unmounts.
+ *
+ * **Important:** This hook should only be used in "page" components, not in
+ * "extension" components. Extensions should not control the left navigation.
+ *
+ * @param params Configuration parameters for the left navigation, excluding the
+ *   module name which is automatically determined from the component context.
+ *
+ * @example
+ * ```tsx
+ * import { useLeftNav } from '@openmrs/esm-framework';
+ * function MyPageComponent() {
+ *   useLeftNav({ name: 'my-nav', slots: ['nav-slot-1', 'nav-slot-2'] });
+ *   return <div>My Page</div>;
+ * }
+ * ```
+ */ export function useLeftNav(params) {
     const componentContext = useContext(ComponentContext);
     useEffect(()=>{
         if (componentContext && componentContext.moduleName) {

package/dist/useLeftNavStore.d.ts

@@ -1,2 +1,17 @@
+/**
+ * A React hook that provides access to the left navigation store state.
+ * The component will re-render whenever the left navigation state changes.
+ *
+ * @returns The current state of the left navigation store.
+ *
+ * @example
+ * ```tsx
+ * import { useLeftNavStore } from '@openmrs/esm-framework';
+ * function MyComponent() {
+ *   const leftNavState = useLeftNavStore();
+ *   return <div>Current nav: {leftNavState.activeNavName}</div>;
+ * }
+ * ```
+ */
 export declare function useLeftNavStore(): import("@openmrs/esm-extensions").LeftNavStore;
 //# sourceMappingURL=useLeftNavStore.d.ts.map

package/dist/useLeftNavStore.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useLeftNavStore.d.ts","sourceRoot":"","sources":["../src/useLeftNavStore.ts"],"names":[],"mappings":"AAGA,wBAAgB,eAAe,mDAE9B"}
+{"version":3,"file":"useLeftNavStore.d.ts","sourceRoot":"","sources":["../src/useLeftNavStore.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,mDAE9B"}

package/dist/useLeftNavStore.js

@@ -1,5 +1,19 @@
-import { leftNavStore } from "@openmrs/esm-extensions";
+/** @module @category UI */ import { leftNavStore } from "@openmrs/esm-extensions";
 import { useStore } from "./useStore.js";
-export function useLeftNavStore() {
+/**
+ * A React hook that provides access to the left navigation store state.
+ * The component will re-render whenever the left navigation state changes.
+ *
+ * @returns The current state of the left navigation store.
+ *
+ * @example
+ * ```tsx
+ * import { useLeftNavStore } from '@openmrs/esm-framework';
+ * function MyComponent() {
+ *   const leftNavState = useLeftNavStore();
+ *   return <div>Current nav: {leftNavState.activeNavName}</div>;
+ * }
+ * ```
+ */ export function useLeftNavStore() {
     return useStore(leftNavStore);
 }

package/dist/useLocations.d.ts

@@ -1,3 +1,27 @@
 import { type Location } from '@openmrs/esm-emr-api';
+/**
+ * A React hook that fetches and returns locations from the OpenMRS server.
+ * Locations can be filtered by a tag UUID/name and/or a search query string.
+ *
+ * @param tagUuidOrName Optional tag UUID or name to filter locations by.
+ *   Pass `null` to not filter by tag.
+ * @param query Optional search query string to filter locations. Pass `null`
+ *   to not filter by query.
+ * @returns An array of Location objects. Returns an empty array while loading
+ *   or if an error occurs.
+ *
+ * @example
+ * ```tsx
+ * import { useLocations } from '@openmrs/esm-framework';
+ * function LocationList() {
+ *   const locations = useLocations('Login Location');
+ *   return (
+ *     <ul>
+ *       {locations.map((loc) => <li key={loc.uuid}>{loc.display}</li>)}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ */
 export declare function useLocations(tagUuidOrName?: string | null, query?: string | null): Array<Location>;
 //# sourceMappingURL=useLocations.d.ts.map

package/dist/useLocations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useLocations.d.ts","sourceRoot":"","sources":["../src/useLocations.tsx"],"names":[],"mappings":"AAEA,OAAO,EAAgB,KAAK,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAEnE,wBAAgB,YAAY,CAAC,aAAa,GAAE,MAAM,GAAG,IAAW,EAAE,KAAK,GAAE,MAAM,GAAG,IAAW,GAAG,KAAK,CAAC,QAAQ,CAAC,CAgB9G"}
+{"version":3,"file":"useLocations.d.ts","sourceRoot":"","sources":["../src/useLocations.tsx"],"names":[],"mappings":"AAEA,OAAO,EAAgB,KAAK,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAEnE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,YAAY,CAAC,aAAa,GAAE,MAAM,GAAG,IAAW,EAAE,KAAK,GAAE,MAAM,GAAG,IAAW,GAAG,KAAK,CAAC,QAAQ,CAAC,CAgB9G"}

package/dist/useLocations.js

@@ -1,6 +1,29 @@
 /** @module @category API */ import { useState, useEffect } from "react";
 import { getLocations } from "@openmrs/esm-emr-api";
-export function useLocations(tagUuidOrName = null, query = null) {
+/**
+ * A React hook that fetches and returns locations from the OpenMRS server.
+ * Locations can be filtered by a tag UUID/name and/or a search query string.
+ *
+ * @param tagUuidOrName Optional tag UUID or name to filter locations by.
+ *   Pass `null` to not filter by tag.
+ * @param query Optional search query string to filter locations. Pass `null`
+ *   to not filter by query.
+ * @returns An array of Location objects. Returns an empty array while loading
+ *   or if an error occurs.
+ *
+ * @example
+ * ```tsx
+ * import { useLocations } from '@openmrs/esm-framework';
+ * function LocationList() {
+ *   const locations = useLocations('Login Location');
+ *   return (
+ *     <ul>
+ *       {locations.map((loc) => <li key={loc.uuid}>{loc.display}</li>)}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ */ export function useLocations(tagUuidOrName = null, query = null) {
     const [locations, setLocations] = useState([]);
     useEffect(()=>{
         const locationSub = getLocations(tagUuidOrName, query).subscribe((locations)=>{

package/dist/useOnClickOutside.d.ts

@@ -1,2 +1,29 @@
+/**
+ * A React hook that detects clicks outside of a referenced element. Useful for
+ * implementing dropdown menus, modals, or any component that should close when
+ * clicking outside of it.
+ *
+ * @typeParam T The type of HTML element the ref will be attached to.
+ * @param handler A callback function invoked when a click occurs outside the
+ *   referenced element.
+ * @param active Whether the outside click detection is active. Defaults to `true`.
+ *   Set to `false` to temporarily disable the detection.
+ * @returns A React ref object to attach to the element you want to detect
+ *   outside clicks for.
+ *
+ * @example
+ * ```tsx
+ * import { useOnClickOutside } from '@openmrs/esm-framework';
+ * function Dropdown() {
+ *   const [isOpen, setIsOpen] = useState(false);
+ *   const ref = useOnClickOutside<HTMLDivElement>(() => setIsOpen(false), isOpen);
+ *   return (
+ *     <div ref={ref}>
+ *       {isOpen && <ul>...</ul>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
 export declare function useOnClickOutside<T extends HTMLElement = HTMLElement>(handler: (event: MouseEvent) => void, active?: boolean): import("react").RefObject<T>;
 //# sourceMappingURL=useOnClickOutside.d.ts.map

package/dist/useOnClickOutside.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useOnClickOutside.d.ts","sourceRoot":"","sources":["../src/useOnClickOutside.ts"],"names":[],"mappings":"AAGA,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EACnE,OAAO,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,EACpC,MAAM,UAAO,gCA0Bd"}
+{"version":3,"file":"useOnClickOutside.d.ts","sourceRoot":"","sources":["../src/useOnClickOutside.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EACnE,OAAO,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,EACpC,MAAM,UAAO,gCA0Bd"}

package/dist/useOnClickOutside.js

@@ -1,5 +1,31 @@
 /** @module @category UI */ import { useRef, useEffect } from "react";
-export function useOnClickOutside(handler, active = true) {
+/**
+ * A React hook that detects clicks outside of a referenced element. Useful for
+ * implementing dropdown menus, modals, or any component that should close when
+ * clicking outside of it.
+ *
+ * @typeParam T The type of HTML element the ref will be attached to.
+ * @param handler A callback function invoked when a click occurs outside the
+ *   referenced element.
+ * @param active Whether the outside click detection is active. Defaults to `true`.
+ *   Set to `false` to temporarily disable the detection.
+ * @returns A React ref object to attach to the element you want to detect
+ *   outside clicks for.
+ *
+ * @example
+ * ```tsx
+ * import { useOnClickOutside } from '@openmrs/esm-framework';
+ * function Dropdown() {
+ *   const [isOpen, setIsOpen] = useState(false);
+ *   const ref = useOnClickOutside<HTMLDivElement>(() => setIsOpen(false), isOpen);
+ *   return (
+ *     <div ref={ref}>
+ *       {isOpen && <ul>...</ul>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */ export function useOnClickOutside(handler, active = true) {
     const ref = useRef(null);
     useEffect(()=>{
         const listener = (event)=>{

package/dist/usePatient.d.ts

@@ -4,6 +4,11 @@ export type NullablePatient = fhir.Patient | null;
  * as a parameter, then the patient for that UUID is returned. If the parameter
  * is not provided, the patient UUID is obtained from the current route, and
  * a route listener is set up to update the patient whenever the route changes.
+ *
+ * @param patientUuid Optional UUID of the patient to fetch. If not provided,
+ *   the UUID is extracted from the current URL path.
+ * @returns An object containing the patient data, loading state, current patient UUID, and any error.
+ *
  */
 export declare function usePatient(patientUuid?: string): {
     isLoading: boolean;

package/dist/usePatient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"usePatient.d.ts","sourceRoot":"","sources":["../src/usePatient.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,eAAe,GAAG,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;AAOlD;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,WAAW,CAAC,EAAE,MAAM;;;;;EAgC9C"}
+{"version":3,"file":"usePatient.d.ts","sourceRoot":"","sources":["../src/usePatient.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,eAAe,GAAG,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;AAOlD;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,WAAW,CAAC,EAAE,MAAM;;;;;EAgC9C"}

package/dist/usePatient.js

@@ -10,6 +10,11 @@ function getPatientUuidFromUrl() {
  * as a parameter, then the patient for that UUID is returned. If the parameter
  * is not provided, the patient UUID is obtained from the current route, and
  * a route listener is set up to update the patient whenever the route changes.
+ *
+ * @param patientUuid Optional UUID of the patient to fetch. If not provided,
+ *   the UUID is extracted from the current URL path.
+ * @returns An object containing the patient data, loading state, current patient UUID, and any error.
+ *
  */ export function usePatient(patientUuid) {
     const [currentPatientUuid, setCurrentPatientUuid] = useState(patientUuid ?? getPatientUuidFromUrl());
     const { data: patient, error, isValidating } = useSWR(currentPatientUuid ? [

package/dist/usePrimaryIdentifierResource.d.ts

@@ -1,6 +1,14 @@
 export interface PrimaryIdentifier {
     metadataUuid: string;
 }
+/**
+ * A React hook that retrieves the UUID of the primary patient identifier type
+ * from the metadata mapping configuration. This identifier type is commonly used
+ * to display the main identifier for a patient, such as their medical record number.
+ *
+ * @returns An object containing the primary identifier type UUID, loading state, and any error.
+ *
+ */
 export declare function usePrimaryIdentifierCode(): {
     primaryIdentifierCode: string | undefined;
     isLoading: boolean;

package/dist/usePrimaryIdentifierResource.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"usePrimaryIdentifierResource.d.ts","sourceRoot":"","sources":["../src/usePrimaryIdentifierResource.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,iBAAiB;IAChC,YAAY,EAAE,MAAM,CAAC;CACtB;AAKD,wBAAgB,wBAAwB,IAAI;IAC1C,qBAAqB,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,KAAK,GAAG,SAAS,CAAC;CAC1B,CAcA"}
+{"version":3,"file":"usePrimaryIdentifierResource.d.ts","sourceRoot":"","sources":["../src/usePrimaryIdentifierResource.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,iBAAiB;IAChC,YAAY,EAAE,MAAM,CAAC;CACtB;AAKD;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,IAAI;IAC1C,qBAAqB,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,KAAK,GAAG,SAAS,CAAC;CAC1B,CAcA"}

package/dist/usePrimaryIdentifierResource.js

@@ -1,7 +1,14 @@
 /** @module @category API */ import { useMemo } from "react";
 import useSWR from "swr";
 import { openmrsFetch, restBaseUrl } from "@openmrs/esm-api";
-export function usePrimaryIdentifierCode() {
+/**
+ * A React hook that retrieves the UUID of the primary patient identifier type
+ * from the metadata mapping configuration. This identifier type is commonly used
+ * to display the main identifier for a patient, such as their medical record number.
+ *
+ * @returns An object containing the primary identifier type UUID, loading state, and any error.
+ *
+ */ export function usePrimaryIdentifierCode() {
     const url = `${restBaseUrl}/metadatamapping/termmapping?v=custom:(metadataUuid)&code=emr.primaryIdentifierType`;
     const { data, error, isLoading } = useSWR(url, openmrsFetch);
     const results = useMemo(()=>({

package/dist/useVisitTypes.d.ts

@@ -1,4 +1,26 @@
 /** @module @category API */
 import { type VisitType } from '@openmrs/esm-emr-api';
+/**
+ * A React hook that fetches and returns all available visit types from the
+ * OpenMRS server. The data is fetched once when the component mounts.
+ *
+ * @returns An array of VisitType objects. Returns an empty array while loading
+ *   or if an error occurs.
+ *
+ * @example
+ * ```tsx
+ * import { useVisitTypes } from '@openmrs/esm-framework';
+ * function VisitTypeSelector() {
+ *   const visitTypes = useVisitTypes();
+ *   return (
+ *     <select>
+ *       {visitTypes.map((vt) => (
+ *         <option key={vt.uuid} value={vt.uuid}>{vt.display}</option>
+ *       ))}
+ *     </select>
+ *   );
+ * }
+ * ```
+ */
 export declare function useVisitTypes(): VisitType[];
 //# sourceMappingURL=useVisitTypes.d.ts.map

package/dist/useVisitTypes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useVisitTypes.d.ts","sourceRoot":"","sources":["../src/useVisitTypes.ts"],"names":[],"mappings":"AAAA,4BAA4B;AAC5B,OAAO,EAAiB,KAAK,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAGrE,wBAAgB,aAAa,gBAe5B"}
+{"version":3,"file":"useVisitTypes.d.ts","sourceRoot":"","sources":["../src/useVisitTypes.ts"],"names":[],"mappings":"AAAA,4BAA4B;AAC5B,OAAO,EAAiB,KAAK,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAGrE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,aAAa,gBAe5B"}

package/dist/useVisitTypes.js

@@ -1,6 +1,27 @@
 /** @module @category API */ import { getVisitTypes } from "@openmrs/esm-emr-api";
 import { useEffect, useState } from "react";
-export function useVisitTypes() {
+/**
+ * A React hook that fetches and returns all available visit types from the
+ * OpenMRS server. The data is fetched once when the component mounts.
+ *
+ * @returns An array of VisitType objects. Returns an empty array while loading
+ *   or if an error occurs.
+ *
+ * @example
+ * ```tsx
+ * import { useVisitTypes } from '@openmrs/esm-framework';
+ * function VisitTypeSelector() {
+ *   const visitTypes = useVisitTypes();
+ *   return (
+ *     <select>
+ *       {visitTypes.map((vt) => (
+ *         <option key={vt.uuid} value={vt.uuid}>{vt.display}</option>
+ *       ))}
+ *     </select>
+ *   );
+ * }
+ * ```
+ */ export function useVisitTypes() {
     const [visitTypes, setVisitTypes] = useState([]);
     useEffect(()=>{
         const visitTypesSub = getVisitTypes().subscribe((visitTypes)=>{

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openmrs/esm-react-utils",
-  "version": "8.0.1-pre.3783",
+  "version": "8.0.1-pre.3786",
   "license": "MPL-2.0",
   "description": "React utilities for OpenMRS.",
   "type": "module",
@@ -79,17 +79,17 @@
     "swr": "2.x"
   },
   "devDependencies": {
-    "@openmrs/esm-api": "8.0.1-pre.3783",
-    "@openmrs/esm-config": "8.0.1-pre.3783",
-    "@openmrs/esm-context": "8.0.1-pre.3783",
-    "@openmrs/esm-emr-api": "8.0.1-pre.3783",
-    "@openmrs/esm-error-handling": "8.0.1-pre.3783",
-    "@openmrs/esm-extensions": "8.0.1-pre.3783",
-    "@openmrs/esm-feature-flags": "8.0.1-pre.3783",
-    "@openmrs/esm-globals": "8.0.1-pre.3783",
-    "@openmrs/esm-navigation": "8.0.1-pre.3783",
-    "@openmrs/esm-state": "8.0.1-pre.3783",
-    "@openmrs/esm-utils": "8.0.1-pre.3783",
+    "@openmrs/esm-api": "8.0.1-pre.3786",
+    "@openmrs/esm-config": "8.0.1-pre.3786",
+    "@openmrs/esm-context": "8.0.1-pre.3786",
+    "@openmrs/esm-emr-api": "8.0.1-pre.3786",
+    "@openmrs/esm-error-handling": "8.0.1-pre.3786",
+    "@openmrs/esm-extensions": "8.0.1-pre.3786",
+    "@openmrs/esm-feature-flags": "8.0.1-pre.3786",
+    "@openmrs/esm-globals": "8.0.1-pre.3786",
+    "@openmrs/esm-navigation": "8.0.1-pre.3786",
+    "@openmrs/esm-state": "8.0.1-pre.3786",
+    "@openmrs/esm-utils": "8.0.1-pre.3786",
     "@swc/cli": "^0.7.7",
     "@swc/core": "^1.11.29",
     "@vitest/coverage-v8": "^4.0.7",

package/src/ConfigurableLink.tsx

@@ -31,9 +31,7 @@ function handleClick(
   }
 }
 
-/**
- * @noInheritDoc
- */
+/** @noInheritDoc */
 export interface ConfigurableLinkProps extends AnchorHTMLAttributes<HTMLAnchorElement> {
   /** The target path or URL. Supports interpolation. See [[navigate]] */
   to: string;
@@ -44,7 +42,7 @@ export interface ConfigurableLinkProps extends AnchorHTMLAttributes<HTMLAnchorEl
 }
 
 /**
- * A React link component which calls [[navigate]] when clicked
+ * A React link component which calls {@link navigate} when clicked
  */
 export function ConfigurableLink({
   to,

package/src/getLifecycle.ts

@@ -7,6 +7,22 @@ import singleSpaReact, { type ReactAppOrParcel } from 'single-spa-react';
 import type { ComponentDecoratorOptions } from './openmrsComponentDecorator';
 import { openmrsComponentDecorator } from './openmrsComponentDecorator';
 
+/**
+ * Creates a single-spa lifecycle object for a React component. The component is
+ * wrapped with the OpenMRS component decorator which provides standard functionality
+ * like error boundaries, configuration, and extension support.
+ *
+ * @param Component The React component to create a lifecycle for.
+ * @param options Configuration options for the OpenMRS component decorator.
+ * @returns A single-spa lifecycle object with bootstrap, mount, and unmount functions.
+ *
+ * @example
+ * ```ts
+ * import { getLifecycle } from '@openmrs/esm-framework';
+ * import MyComponent from './MyComponent';
+ * export const lifecycle = getLifecycle(MyComponent, { featureName: 'my-feature', moduleName: '@openmrs/esm-my-app' });
+ * ```
+ */
 export function getLifecycle<T>(Component: ComponentType<T>, options: ComponentDecoratorOptions) {
   return singleSpaReact<T>({
     React,
@@ -15,6 +31,24 @@ export function getLifecycle<T>(Component: ComponentType<T>, options: ComponentD
   });
 }
 
+/**
+ * Creates a lazy-loading single-spa lifecycle for a React component. The component
+ * is loaded asynchronously via dynamic import only when it's needed, which helps
+ * reduce initial bundle size. This is the recommended way to define lifecycles
+ * for most modules.
+ *
+ * @param lazy A function that returns a Promise resolving to a module with the
+ *   component as its default export (i.e., a dynamic import).
+ * @param options Configuration options for the OpenMRS component decorator.
+ * @returns A function that returns a Promise resolving to a single-spa lifecycle object.
+ *
+ * @example
+ * ```ts
+ * import { getAsyncLifecycle } from '@openmrs/esm-framework';
+ * const options = { featureName: 'my-feature', moduleName: '@openmrs/esm-my-app' };
+ * export const root = getAsyncLifecycle(() => import('./root.component'), options);
+ * ```
+ */
 export function getAsyncLifecycle<T>(
   lazy: () => Promise<{ default: ComponentType<T> }>,
   options: ComponentDecoratorOptions,
@@ -22,6 +56,24 @@ export function getAsyncLifecycle<T>(
   return () => lazy().then(({ default: Component }) => getLifecycle(Component, options));
 }
 
+/**
+ * Creates a single-spa lifecycle for a React component that is already loaded.
+ * Unlike {@link getAsyncLifecycle}, this wraps a synchronously-available component
+ * in a Promise to match the expected lifecycle interface. Use this when the
+ * component doesn't need lazy loading.
+ *
+ * @param Component The React component to create a lifecycle for.
+ * @param options Configuration options for the OpenMRS component decorator.
+ * @returns A function that returns a Promise resolving to a single-spa lifecycle object.
+ *
+ * @example
+ * ```ts
+ * import { getSyncLifecycle } from '@openmrs/esm-framework';
+ * import MyComponent from './MyComponent';
+ * const options = { featureName: 'my-feature', moduleName: '@openmrs/esm-my-app' };
+ * export const myExtension = getSyncLifecycle(MyComponent, options);
+ * ```
+ */
 export function getSyncLifecycle<T>(Component: ComponentType<T>, options: ComponentDecoratorOptions) {
   return () => Promise.resolve(getLifecycle(Component, options));
 }

package/src/useAttachments.ts

@@ -4,6 +4,31 @@ import useSWR from 'swr';
 import { openmrsFetch, type FetchResponse } from '@openmrs/esm-api';
 import { attachmentUrl, 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.
+ * @param includeEncounterless Whether to include attachments that are not
+ *   associated with any encounter.
+ * @returns An object containing:
+ *   - `data`: Array of attachment objects (empty array while loading)
+ *   - `isLoading`: Whether the initial fetch is in progress
+ *   - `isValidating`: Whether any request (initial or revalidation) is in progress
+ *   - `error`: Any error that occurred during fetching
+ *   - `mutate`: Function to trigger a revalidation of the data
+ *
+ * @example
+ * ```tsx
+ * import { useAttachments } from '@openmrs/esm-framework';
+ * function PatientAttachments({ patientUuid }) {
+ *   const { data, isLoading, error } = useAttachments(patientUuid, true);
+ *   if (isLoading) return <span>Loading...</span>;
+ *   if (error) return <span>Error loading attachments</span>;
+ *   return <AttachmentList attachments={data} />;
+ * }
+ * ```
+ */
 export function useAttachments(patientUuid: string, includeEncounterless: boolean) {
   const { data, error, mutate, isLoading, isValidating } = useSWR<
     FetchResponse<{ results: Array<AttachmentResponse> }>

package/src/useBodyScrollLock.ts

@@ -1,6 +1,24 @@
 /** @module @category UI */
 import { useEffect } from 'react';
 
+/**
+ * A React hook that prevents scrolling on the document body when active.
+ * Useful for modals, overlays, or any full-screen UI that should prevent
+ * background scrolling. The original overflow style is restored when the
+ * hook becomes inactive or the component unmounts.
+ *
+ * @param active Whether to lock the body scroll. When `true`, sets
+ *   `document.body.style.overflow` to 'hidden'.
+ *
+ * @example
+ * ```tsx
+ * import { useBodyScrollLock } from '@openmrs/esm-framework';
+ * function Modal({ isOpen }) {
+ *   useBodyScrollLock(isOpen);
+ *   return isOpen ? <div className="modal">...</div> : null;
+ * }
+ * ```
+ */
 export function useBodyScrollLock(active: boolean) {
   useEffect(() => {
     if (active) {

package/src/useConnectivity.ts

@@ -3,6 +3,22 @@ import { subscribeConnectivityChanged } from '@openmrs/esm-globals';
 import { isOnline as isOnlineFn } from '@openmrs/esm-utils';
 import { useEffect, useState } from 'react';
 
+/**
+ * A React hook that returns the current online/offline status and automatically
+ * updates when connectivity changes. Useful for showing offline indicators or
+ * conditionally rendering UI based on network availability.
+ *
+ * @returns `true` if the browser is online, `false` if offline.
+ *
+ * @example
+ * ```tsx
+ * import { useConnectivity } from '@openmrs/esm-framework';
+ * function NetworkStatus() {
+ *   const isOnline = useConnectivity();
+ *   return <span>{isOnline ? 'Online' : 'Offline'}</span>;
+ * }
+ * ```
+ */
 export function useConnectivity() {
   let [isOnline, setIsOnline] = useState(isOnlineFn());
 

package/src/useLeftNav.ts

@@ -1,7 +1,28 @@
+/** @module @category UI */
 import { useContext, useEffect } from 'react';
 import { type SetLeftNavParams, setLeftNav, unsetLeftNav } from '@openmrs/esm-extensions';
 import { ComponentContext } from './ComponentContext';
 
+/**
+ * A React hook that registers a left navigation menu for the current component.
+ * The navigation is automatically registered when the component mounts and
+ * unregistered when it unmounts.
+ *
+ * **Important:** This hook should only be used in "page" components, not in
+ * "extension" components. Extensions should not control the left navigation.
+ *
+ * @param params Configuration parameters for the left navigation, excluding the
+ *   module name which is automatically determined from the component context.
+ *
+ * @example
+ * ```tsx
+ * import { useLeftNav } from '@openmrs/esm-framework';
+ * function MyPageComponent() {
+ *   useLeftNav({ name: 'my-nav', slots: ['nav-slot-1', 'nav-slot-2'] });
+ *   return <div>My Page</div>;
+ * }
+ * ```
+ */
 export function useLeftNav(params: Omit<SetLeftNavParams, 'module'>) {
   const componentContext = useContext(ComponentContext);
 

package/src/useLeftNavStore.ts

@@ -1,6 +1,22 @@
+/** @module @category UI */
 import { leftNavStore } from '@openmrs/esm-extensions';
 import { useStore } from './useStore';
 
+/**
+ * A React hook that provides access to the left navigation store state.
+ * The component will re-render whenever the left navigation state changes.
+ *
+ * @returns The current state of the left navigation store.
+ *
+ * @example
+ * ```tsx
+ * import { useLeftNavStore } from '@openmrs/esm-framework';
+ * function MyComponent() {
+ *   const leftNavState = useLeftNavStore();
+ *   return <div>Current nav: {leftNavState.activeNavName}</div>;
+ * }
+ * ```
+ */
 export function useLeftNavStore() {
   return useStore(leftNavStore);
 }

package/src/useLocations.tsx

@@ -2,6 +2,30 @@
 import { useState, useEffect } from 'react';
 import { getLocations, type Location } from '@openmrs/esm-emr-api';
 
+/**
+ * A React hook that fetches and returns locations from the OpenMRS server.
+ * Locations can be filtered by a tag UUID/name and/or a search query string.
+ *
+ * @param tagUuidOrName Optional tag UUID or name to filter locations by.
+ *   Pass `null` to not filter by tag.
+ * @param query Optional search query string to filter locations. Pass `null`
+ *   to not filter by query.
+ * @returns An array of Location objects. Returns an empty array while loading
+ *   or if an error occurs.
+ *
+ * @example
+ * ```tsx
+ * import { useLocations } from '@openmrs/esm-framework';
+ * function LocationList() {
+ *   const locations = useLocations('Login Location');
+ *   return (
+ *     <ul>
+ *       {locations.map((loc) => <li key={loc.uuid}>{loc.display}</li>)}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ */
 export function useLocations(tagUuidOrName: string | null = null, query: string | null = null): Array<Location> {
   const [locations, setLocations] = useState<Array<Location>>([]);
 

package/src/useOnClickOutside.ts

@@ -1,6 +1,33 @@
 /** @module @category UI */
 import { useRef, useEffect } from 'react';
 
+/**
+ * A React hook that detects clicks outside of a referenced element. Useful for
+ * implementing dropdown menus, modals, or any component that should close when
+ * clicking outside of it.
+ *
+ * @typeParam T The type of HTML element the ref will be attached to.
+ * @param handler A callback function invoked when a click occurs outside the
+ *   referenced element.
+ * @param active Whether the outside click detection is active. Defaults to `true`.
+ *   Set to `false` to temporarily disable the detection.
+ * @returns A React ref object to attach to the element you want to detect
+ *   outside clicks for.
+ *
+ * @example
+ * ```tsx
+ * import { useOnClickOutside } from '@openmrs/esm-framework';
+ * function Dropdown() {
+ *   const [isOpen, setIsOpen] = useState(false);
+ *   const ref = useOnClickOutside<HTMLDivElement>(() => setIsOpen(false), isOpen);
+ *   return (
+ *     <div ref={ref}>
+ *       {isOpen && <ul>...</ul>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
 export function useOnClickOutside<T extends HTMLElement = HTMLElement>(
   handler: (event: MouseEvent) => void,
   active = true,

package/src/usePatient.ts

@@ -15,6 +15,11 @@ function getPatientUuidFromUrl() {
  * as a parameter, then the patient for that UUID is returned. If the parameter
  * is not provided, the patient UUID is obtained from the current route, and
  * a route listener is set up to update the patient whenever the route changes.
+ *
+ * @param patientUuid Optional UUID of the patient to fetch. If not provided,
+ *   the UUID is extracted from the current URL path.
+ * @returns An object containing the patient data, loading state, current patient UUID, and any error.
+ *
  */
 export function usePatient(patientUuid?: string) {
   const [currentPatientUuid, setCurrentPatientUuid] = useState(patientUuid ?? getPatientUuidFromUrl());

package/src/usePrimaryIdentifierResource.ts

@@ -10,6 +10,14 @@ interface PrimaryIdentifierResponse {
   results: Array<PrimaryIdentifier>;
 }
 
+/**
+ * A React hook that retrieves the UUID of the primary patient identifier type
+ * from the metadata mapping configuration. This identifier type is commonly used
+ * to display the main identifier for a patient, such as their medical record number.
+ *
+ * @returns An object containing the primary identifier type UUID, loading state, and any error.
+ *
+ */
 export function usePrimaryIdentifierCode(): {
   primaryIdentifierCode: string | undefined;
   isLoading: boolean;

package/src/useVisitTypes.ts

@@ -2,6 +2,28 @@
 import { getVisitTypes, type VisitType } from '@openmrs/esm-emr-api';
 import { useEffect, useState } from 'react';
 
+/**
+ * A React hook that fetches and returns all available visit types from the
+ * OpenMRS server. The data is fetched once when the component mounts.
+ *
+ * @returns An array of VisitType objects. Returns an empty array while loading
+ *   or if an error occurs.
+ *
+ * @example
+ * ```tsx
+ * import { useVisitTypes } from '@openmrs/esm-framework';
+ * function VisitTypeSelector() {
+ *   const visitTypes = useVisitTypes();
+ *   return (
+ *     <select>
+ *       {visitTypes.map((vt) => (
+ *         <option key={vt.uuid} value={vt.uuid}>{vt.display}</option>
+ *       ))}
+ *     </select>
+ *   );
+ * }
+ * ```
+ */
 export function useVisitTypes() {
   const [visitTypes, setVisitTypes] = useState<Array<VisitType>>([]);