@openmrs/esm-framework 6.3.1-pre.3106 → 6.3.1-pre.3119

package/docs/functions/useLayoutType.md

@@ -0,0 +1,11 @@
+[O3 Framework](../API.md) / useLayoutType
+
+# Function: useLayoutType()
+
+> **useLayoutType**(): [`LayoutType`](../type-aliases/LayoutType.md)
+
+Defined in: [packages/framework/esm-react-utils/src/useLayoutType.ts:26](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-react-utils/src/useLayoutType.ts#L26)
+
+## Returns
+
+[`LayoutType`](../type-aliases/LayoutType.md)

package/docs/functions/useLeftNav.md

@@ -0,0 +1,17 @@
+[O3 Framework](../API.md) / useLeftNav
+
+# Function: useLeftNav()
+
+> **useLeftNav**(`params`): `void`
+
+Defined in: [packages/framework/esm-react-utils/src/useLeftNav.ts:5](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-react-utils/src/useLeftNav.ts#L5)
+
+## Parameters
+
+### params
+
+`Omit`\<`SetLeftNavParams`, `"module"`\>
+
+## Returns
+
+`void`

package/docs/functions/useLeftNavStore.md

@@ -0,0 +1,11 @@
+[O3 Framework](../API.md) / useLeftNavStore
+
+# Function: useLeftNavStore()
+
+> **useLeftNavStore**(): `LeftNavStore`
+
+Defined in: [packages/framework/esm-react-utils/src/useLeftNavStore.ts:4](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-react-utils/src/useLeftNavStore.ts#L4)
+
+## Returns
+
+`LeftNavStore`

package/docs/functions/useLocations.md

@@ -0,0 +1,21 @@
+[O3 Framework](../API.md) / useLocations
+
+# Function: useLocations()
+
+> **useLocations**(`tagUuidOrName`, `query`): `Location`[]
+
+Defined in: [packages/framework/esm-react-utils/src/useLocations.tsx:5](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-react-utils/src/useLocations.tsx#L5)
+
+## Parameters
+
+### tagUuidOrName
+
+`null` | `string`
+
+### query
+
+`null` | `string`
+
+## Returns
+
+`Location`[]

package/docs/functions/useOnClickOutside.md

@@ -0,0 +1,27 @@
+[O3 Framework](../API.md) / useOnClickOutside
+
+# Function: useOnClickOutside()
+
+> **useOnClickOutside**\<`T`\>(`handler`, `active`): `RefObject`\<`T`\>
+
+Defined in: [packages/framework/esm-react-utils/src/useOnClickOutside.ts:4](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-react-utils/src/useOnClickOutside.ts#L4)
+
+## Type Parameters
+
+### T
+
+`T` *extends* `HTMLElement` = `HTMLElement`
+
+## Parameters
+
+### handler
+
+(`event`) => `void`
+
+### active
+
+`boolean` = `true`
+
+## Returns
+
+`RefObject`\<`T`\>

package/docs/functions/useOnVisible.md

@@ -0,0 +1,28 @@
+[O3 Framework](../API.md) / useOnVisible
+
+# Function: useOnVisible()
+
+> **useOnVisible**(`callBack`): `MutableRefObject`\<`HTMLElement`\>
+
+Defined in: [packages/framework/esm-react-utils/src/useOnVisible.ts:15](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-react-utils/src/useOnVisible.ts#L15)
+
+Returns a ref that can be used on a HTML component to trigger
+an action when the component is scrolled into visible view,
+This is particularly useful for infinite scrolling UIs to load data on demand.
+
+## Parameters
+
+### callBack
+
+() => `void`
+
+The callback to run when the component is scrolled into visible view.
+  Care should be taken with this param. The callback should
+  be cached across re-renders (via useCallback) and it should have
+  logic to avoid doing work multiple times while scrolling.
+
+## Returns
+
+`MutableRefObject`\<`HTMLElement`\>
+
+a ref that can be passed to an HTML Element

package/docs/functions/useOpenmrsFetchAll.md

@@ -0,0 +1,46 @@
+[O3 Framework](../API.md) / useOpenmrsFetchAll
+
+# Function: useOpenmrsFetchAll()
+
+> **useOpenmrsFetchAll**\<`T`\>(`url`, `options`): `UseServerInfiniteReturnObject`\<`T`, `OpenMRSPaginatedResponse`\<`T`\>\>
+
+Defined in: [packages/framework/esm-react-utils/src/useOpenmrsFetchAll.ts:40](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-react-utils/src/useOpenmrsFetchAll.ts#L40)
+
+Most OpenMRS REST endpoints that return a list of objects, such as getAll or search, are server-side paginated.
+This hook handles fetching results from *all* pages of a paginated OpenMRS REST endpoint, making multiple requests
+as needed.
+
+## Type Parameters
+
+### T
+
+`T`
+
+## Parameters
+
+### url
+
+The URL of the paginated OpenMRS REST endpoint. Note that the `limit` GET param can be set to specify
+           the page size; if not set, the page size defaults to the `webservices.rest.maxResultsDefault` value defined
+           server-side.
+           Similar to useSWRInfinite, this param can be null to disable fetching.
+
+`string` | `URL`
+
+### options
+
+[`UseServerFetchAllOptions`](../interfaces/UseServerFetchAllOptions.md)\<`OpenMRSPaginatedResponse`\<`T`\>\> = `{}`
+
+The options object
+
+## Returns
+
+`UseServerInfiniteReturnObject`\<`T`, `OpenMRSPaginatedResponse`\<`T`\>\>
+
+a UseOpenmrsInfiniteReturnObject object
+
+## See
+
+ - `useOpenmrsPagination`
+ - `useOpenmrsInfinite`
+ - `useFhirFetchAll`

package/docs/functions/useOpenmrsInfinite.md

@@ -0,0 +1,54 @@
+[O3 Framework](../API.md) / useOpenmrsInfinite
+
+# Function: useOpenmrsInfinite()
+
+> **useOpenmrsInfinite**\<`T`\>(`url`, `options`): `UseServerInfiniteReturnObject`\<`T`, `OpenMRSPaginatedResponse`\<`T`\>\>
+
+Defined in: [packages/framework/esm-react-utils/src/useOpenmrsInfinite.ts:102](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-react-utils/src/useOpenmrsInfinite.ts#L102)
+
+Most REST endpoints that return a list of objects, such as getAll or search, are server-side paginated.
+The server limits the max number of results being returned, and multiple requests are needed to get the full data set
+if its size exceeds this limit.
+The max number of results per request is configurable server-side
+with the key "webservices.rest.maxResultsDefault". See: https://openmrs.atlassian.net/wiki/spaces/docs/pages/25469882/REST+Module
+
+This hook fetches data from a paginated rest endpoint, initially by fetching the first page of the results.
+It provides a callback to load data from subsequent pages as needed. This hook is intended to serve UIs that
+provide infinite loading / scrolling of results. Unlike `useOpenmrsPagination`, this hook does not allow random access
+(and lazy-loading) of any arbitrary page; rather, it fetches pages sequentially starting form the initial page, and the next page
+is fetched by calling `loadMore`. See: https://swr.vercel.app/docs/pagination#useswrinfinite
+
+## Type Parameters
+
+### T
+
+`T`
+
+## Parameters
+
+### url
+
+The URL of the paginated rest endpoint. Note that the `limit` GET param can be set to specify
+           the page size; if not set, the page size defaults to the `webservices.rest.maxResultsDefault` value defined
+           server-side.
+           Similar to useSWRInfinite, this param can be null to disable fetching.
+
+`string` | `URL`
+
+### options
+
+[`UseServerInfiniteOptions`](../interfaces/UseServerInfiniteOptions.md)\<`OpenMRSPaginatedResponse`\<`T`\>\> = `{}`
+
+The options object
+
+## Returns
+
+`UseServerInfiniteReturnObject`\<`T`, `OpenMRSPaginatedResponse`\<`T`\>\>
+
+a UseServerInfiniteReturnObject object
+
+## See
+
+ - `useOpenmrsPagination`
+ - `useOpenmrsFetchAll`
+ - `useFhirInfinite`

package/docs/functions/useOpenmrsPagination.md

@@ -0,0 +1,140 @@
+[O3 Framework](../API.md) / useOpenmrsPagination
+
+# Function: useOpenmrsPagination()
+
+> **useOpenmrsPagination**\<`T`\>(`url`, `pageSize`, `options`): `object`
+
+Defined in: [packages/framework/esm-react-utils/src/useOpenmrsPagination.ts:59](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-react-utils/src/useOpenmrsPagination.ts#L59)
+
+Most OpenMRS REST endpoints that return a list of objects, such as getAll or search, are server-side paginated.
+The server limits the max number of results being returned, and multiple requests are needed to get the full data set
+if its size exceeds this limit.
+The max number of results per request is configurable server-side
+with the key "webservices.rest.maxResultsDefault". See: https://openmrs.atlassian.net/wiki/spaces/docs/pages/25469882/REST+Module
+
+For any UI that displays a paginated view of the full data set, we MUST handle the server-side pagination properly,
+or else the UI does not correctly display the full data set.
+This hook does that by providing callback functions for navigating to different pages of the results, and
+lazy-loads the data on each page as needed.
+
+Note that this hook is not suitable for use for situations that require client-side sorting or filtering
+of the data set. In that case, all data must be loaded onto client-side first.
+
+## Type Parameters
+
+### T
+
+`T`
+
+## Parameters
+
+### url
+
+The URL of the paginated rest endpoint. \
+           It should be populated with any needed GET params, except `limit`, `startIndex` or `totalCount`,
+           which will be overridden and manipulated by the `goTo*` callbacks.
+           Similar to useSWR, this param can be null to disable fetching.
+
+`string` | `URL`
+
+### pageSize
+
+`number`
+
+The number of results to return per page / fetch. Note that this value MUST NOT exceed
+           "webservices.rest.maxResultsAbsolute", which should be reasonably high by default (1000).
+
+### options
+
+[`UseServerPaginationOptions`](../interfaces/UseServerPaginationOptions.md)\<`OpenMRSPaginatedResponse`\<`T`\>\> = `{}`
+
+The options object
+
+## Returns
+
+### currentPage
+
+> **currentPage**: `number`
+
+### currentPageSize
+
+> **currentPageSize**: `MutableRefObject`\<`number`\>
+
+### data
+
+> **data**: `undefined` \| `T`[]
+
+### error
+
+> **error**: `any`
+
+The error object thrown by the fetcher function.
+
+### goTo()
+
+> **goTo**: (`page`) => `void`
+
+#### Parameters
+
+##### page
+
+`number`
+
+#### Returns
+
+`void`
+
+### goToNext()
+
+> **goToNext**: () => `void`
+
+#### Returns
+
+`void`
+
+### goToPrevious()
+
+> **goToPrevious**: () => `void`
+
+#### Returns
+
+`void`
+
+### isLoading
+
+> **isLoading**: `boolean`
+
+### isValidating
+
+> **isValidating**: `boolean`
+
+### mutate
+
+> **mutate**: `KeyedMutator`\<`FetchResponse`\<`OpenMRSPaginatedResponse`\<`T`\>\>\>
+
+### paginated
+
+> **paginated**: `boolean`
+
+### showNextButton
+
+> **showNextButton**: `boolean`
+
+### showPreviousButton
+
+> **showPreviousButton**: `boolean`
+
+### totalCount
+
+> **totalCount**: `number` = `totalCount.current`
+
+### totalPages
+
+> **totalPages**: `number`
+
+## See
+
+ - `useOpenmrsInfinite`
+ - `useOpenmrsFetchAll`
+ - `usePagination` for pagination of client-side data`
+@see `useFhirPagination``

package/docs/functions/useOpenmrsSWR.md

@@ -0,0 +1,71 @@
+[O3 Framework](../API.md) / useOpenmrsSWR
+
+# Function: useOpenmrsSWR()
+
+> **useOpenmrsSWR**\<`DataType`, `ErrorType`\>(`key`, `options`): `SWRResponse`\<`FetchResponse`\<`DataType`\>, `ErrorType`, `undefined` \| `SWRConfiguration`\<`FetchResponse`\<`DataType`\>, `ErrorType`, `BareFetcher`\<`FetchResponse`\<`DataType`\>\>\>\>
+
+Defined in: [packages/framework/esm-react-utils/src/useOpenmrsSWR.ts:70](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-react-utils/src/useOpenmrsSWR.ts#L70)
+
+**`Beta`**
+
+This hook is intended to simplify using openmrsFetch in useSWR, while also ensuring that
+all useSWR usages properly use an abort controller, so that fetch requests are cancelled
+if the React component unmounts.
+
+## Type Parameters
+
+### DataType
+
+`DataType` = `any`
+
+### ErrorType
+
+`ErrorType` = `any`
+
+## Parameters
+
+### key
+
+[`Key`](../type-aliases/Key.md)
+
+The SWR key to use
+
+### options
+
+[`UseOpenmrsSWROptions`](../type-aliases/UseOpenmrsSWROptions.md) = `{}`
+
+An object of optional parameters to provide, including a [FetchConfig](../interfaces/FetchConfig.md) object
+  to pass to [openmrsFetch](openmrsFetch.md) or options to pass to SWR
+
+## Returns
+
+`SWRResponse`\<`FetchResponse`\<`DataType`\>, `ErrorType`, `undefined` \| `SWRConfiguration`\<`FetchResponse`\<`DataType`\>, `ErrorType`, `BareFetcher`\<`FetchResponse`\<`DataType`\>\>\>\>
+
+## Examples
+
+```tsx
+import { useOpenmrsSWR } from "@openmrs/esm-framework";
+
+function MyComponent() {
+ const { data } = useOpenmrsSWR(key);
+
+ return (
+   // render something with data
+ );
+}
+```
+
+Note that if you are using a complex SWR key you must provide a url function to the options parameter,
+which translates the key into a URL to be sent to `openmrsFetch()`
+
+```tsx
+import { useOpenmrsSWR } from "@openmrs/esm-framework";
+
+function MyComponent() {
+ const { data } = useOpenmrsSWR(['key', 'url'], { url: (key) => key[1] });
+
+ return (
+   // render something with data
+ );
+}
+```

package/docs/functions/usePagination.md

@@ -0,0 +1,89 @@
+[O3 Framework](../API.md) / usePagination
+
+# Function: usePagination()
+
+> **usePagination**\<`T`\>(`data`, `resultsPerPage`): `object`
+
+Defined in: [packages/framework/esm-react-utils/src/usePagination.ts:15](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-react-utils/src/usePagination.ts#L15)
+
+Use this hook to paginate data that already exists on the client side.
+Note that if the data is obtained from server-side, the caller must handle server-side pagination manually.
+
+## Type Parameters
+
+### T
+
+`T`
+
+## Parameters
+
+### data
+
+`T`[] = `[]`
+
+### resultsPerPage
+
+`number` = `defaultResultsPerPage`
+
+## Returns
+
+`object`
+
+### currentPage
+
+> **currentPage**: `number` = `page`
+
+### goTo()
+
+> **goTo**: (`page`) => `void`
+
+#### Parameters
+
+##### page
+
+`number`
+
+#### Returns
+
+`void`
+
+### goToNext()
+
+> **goToNext**: () => `void`
+
+#### Returns
+
+`void`
+
+### goToPrevious()
+
+> **goToPrevious**: () => `void`
+
+#### Returns
+
+`void`
+
+### paginated
+
+> **paginated**: `boolean`
+
+### results
+
+> **results**: `T`[]
+
+### showNextButton
+
+> **showNextButton**: `boolean`
+
+### showPreviousButton
+
+> **showPreviousButton**: `boolean`
+
+### totalPages
+
+> **totalPages**: `number`
+
+## See
+
+ - `useServerPagination` for hook that automatically manages server-side pagination.
+ - `useServerInfinite` for hook to get all data loaded onto the client-side

package/docs/functions/usePatient.md

@@ -0,0 +1,38 @@
+[O3 Framework](../API.md) / usePatient
+
+# Function: usePatient()
+
+> **usePatient**(`patientUuid?`): `object`
+
+Defined in: [packages/framework/esm-react-utils/src/usePatient.ts:19](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-react-utils/src/usePatient.ts#L19)
+
+This React hook returns a patient object. If the `patientUuid` is provided
+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.
+
+## Parameters
+
+### patientUuid?
+
+`string`
+
+## Returns
+
+`object`
+
+### error
+
+> **error**: `undefined` \| `null` \| `Error`
+
+### isLoading
+
+> **isLoading**: `boolean`
+
+### patient
+
+> **patient**: `undefined` \| [`NullablePatient`](../type-aliases/NullablePatient.md)
+
+### patientUuid
+
+> **patientUuid**: `null` \| `string` = `currentPatientUuid`

package/docs/functions/usePatientPhoto.md

@@ -0,0 +1,17 @@
+[O3 Framework](../API.md) / usePatientPhoto
+
+# Function: usePatientPhoto()
+
+> **usePatientPhoto**(`patientUuid`): [`UsePatientPhotoResult`](../interfaces/UsePatientPhotoResult.md)
+
+Defined in: [packages/framework/esm-styleguide/src/patient-photo/usePatientPhoto.ts:30](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-styleguide/src/patient-photo/usePatientPhoto.ts#L30)
+
+## Parameters
+
+### patientUuid
+
+`string`
+
+## Returns
+
+[`UsePatientPhotoResult`](../interfaces/UsePatientPhotoResult.md)

package/docs/functions/usePrimaryIdentifierCode.md

@@ -0,0 +1,23 @@
+[O3 Framework](../API.md) / usePrimaryIdentifierCode
+
+# Function: usePrimaryIdentifierCode()
+
+> **usePrimaryIdentifierCode**(): `object`
+
+Defined in: [packages/framework/esm-react-utils/src/usePrimaryIdentifierResource.ts:13](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-react-utils/src/usePrimaryIdentifierResource.ts#L13)
+
+## Returns
+
+`object`
+
+### error
+
+> **error**: `undefined` \| `Error`
+
+### isLoading
+
+> **isLoading**: `boolean`
+
+### primaryIdentifierCode
+
+> **primaryIdentifierCode**: `undefined` \| `string`

package/docs/functions/useRenderableExtensions.md

@@ -0,0 +1,43 @@
+[O3 Framework](../API.md) / useRenderableExtensions
+
+# Function: useRenderableExtensions()
+
+> **useRenderableExtensions**(`name`): `FC`\<`Pick`\<[`ExtensionProps`](../type-aliases/ExtensionProps.md), `"state"`\>\>[]
+
+Defined in: [packages/framework/esm-react-utils/src/useRenderableExtensions.tsx:31](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-react-utils/src/useRenderableExtensions.tsx#L31)
+
+This is an advanced hook for use-cases where its useful to use the extension system,
+but not the `ExtensionSlot` component's rendering of extensions. Use of this hook
+should be avoided if possible.
+
+Functionally, this hook is very similar to the `ExtensionSlot` component, but whereas
+an `ExtensionSlot` renders a DOM tree of extensions bound to the slot, this hook simply
+returns the extensions as an array of React components that can be wired into a component
+however makes sense.
+
+## Parameters
+
+### name
+
+`string`
+
+The name of the extension slot
+
+## Returns
+
+`FC`\<`Pick`\<[`ExtensionProps`](../type-aliases/ExtensionProps.md), `"state"`\>\>[]
+
+## Example
+
+```ts
+const extensions = useRenderableExtensions('my-extension-slot');
+return (
+ <>
+   {extensions.map((Ext, index) => (
+     <React.Fragment key={index}>
+       <Ext state={{key: 'value'}} />
+     </React.Fragment>
+   ))}
+ </>
+)
+```

package/docs/functions/useSession.md

@@ -0,0 +1,19 @@
+[O3 Framework](../API.md) / useSession
+
+# Function: useSession()
+
+> **useSession**(): `Session`
+
+Defined in: [packages/framework/esm-react-utils/src/useSession.ts:17](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-react-utils/src/useSession.ts#L17)
+
+Gets the current user session information. Returns an object with
+property `authenticated` == `false` if the user is not logged in.
+
+Uses Suspense. This hook will always either return a Session object
+or throw for Suspense. It will never return `null`/`undefined`.
+
+## Returns
+
+`Session`
+
+Current user session information