@koech/esm-core 8.0.0

package/packages/framework/esm-framework/docs/functions/launchWorkspace2.md

@@ -0,0 +1,79 @@
+[O3 Framework](../API.md) / launchWorkspace2
+
+# Function: launchWorkspace2()
+
+> **launchWorkspace2**\<`WorkspaceProps`, `WindowProps`, `GroupProp`\>(`workspaceName`, `workspaceProps`, `windowProps`, `groupProps`): `Promise`\<`boolean`\>
+
+Defined in: [packages/framework/esm-styleguide/src/workspaces2/workspace2.ts:135](https://github.com/Kipkemoii/openmrs-esm-core/blob/main/packages/framework/esm-styleguide/src/workspaces2/workspace2.ts#L135)
+
+**`Experimental`**
+
+Attempts to launch the specified workspace with the given workspace props. This also implicitly opens
+the workspace window to which the workspace belongs (if it's not opened already),
+and the workspace group to which the window belongs (if it's not opened already).
+
+When calling `launchWorkspace2`, we need to also pass in the workspace props. While not required,
+we can also pass in the window props (shared by other workspaces in the window) and the group props
+(shared by all windows and their workspaces). Omitting the window props or the group props[^1] means the caller
+explicitly does not care what the current window props and group props are, and that they may be set
+by other actions (like calling `launchWorkspace2` on a different workspace with those props passed in)
+at a later time.
+
+If there is already an opened workspace group, and it's not the group the workspace belongs to
+or has incompatible[^2] group props, then we prompt the user to close the group (and its windows and their workspaces).
+On user confirm, the existing opened group is closed and the new workspace, along with its window and its group,
+is opened.
+
+If the window is already opened, but with incompatible window props, we prompt the user to close
+the window (and all its opened workspaces), and reopen the window with (only) the newly requested workspace.
+
+If the workspace is already opened, but with incompatible workspace props, we also prompt the user to close
+the **window** (and all its opened workspaces), and reopen the window with (only) the newly requested workspace.
+This is true regardless of whether the already opened workspace has any child workspaces.
+
+Note that calling this function *never* results in creating a child workspace in the affected window.
+To do so, we need to call `launchChildWorkspace` instead.
+
+[^1] Omitting window or group props is useful for workspaces that don't have ties to the window or group "context" (props).
+For example, in the patient chart, the visit notes / clinical forms / order basket action menu button all share
+a "group context" of the current visit. However, the "patient list" action menu button does not need to share that group
+context, so opening that workspace should not need to cause other workspaces / windows / groups to potentially close.
+The "patient search" workspace in the queues and ward apps is another example.
+
+[^2] 2 sets of props are compatible if either one is nullish, or if they are shallow equal.
+
+## Type Parameters
+
+### WorkspaceProps
+
+`WorkspaceProps` *extends* `object`
+
+### WindowProps
+
+`WindowProps` *extends* `object`
+
+### GroupProp
+
+`GroupProp` *extends* `object`
+
+## Parameters
+
+### workspaceName
+
+`string`
+
+### workspaceProps
+
+`null` | `WorkspaceProps`
+
+### windowProps
+
+`null` | `WindowProps`
+
+### groupProps
+
+`null` | `GroupProp`
+
+## Returns
+
+`Promise`\<`boolean`\>

package/packages/framework/esm-framework/docs/functions/launchWorkspaceGroup.md

@@ -0,0 +1,38 @@
+[O3 Framework](../API.md) / launchWorkspaceGroup
+
+# Function: launchWorkspaceGroup()
+
+> **launchWorkspaceGroup**(`groupName`, `args`): `void`
+
+Defined in: [packages/framework/esm-styleguide/src/workspaces/workspaces.ts:210](https://github.com/Kipkemoii/openmrs-esm-core/blob/main/packages/framework/esm-styleguide/src/workspaces/workspaces.ts#L210)
+
+Launches a workspace group with the specified name and configuration.
+If there are any open workspaces, it will first close them before launching the new workspace group.
+
+## Parameters
+
+### groupName
+
+`string`
+
+The name of the workspace group to launch
+
+### args
+
+`LaunchWorkspaceGroupArg`
+
+Configuration object for launching the workspace group
+
+## Returns
+
+`void`
+
+## Example
+
+```ts
+launchWorkspaceGroup("myGroup", {
+  state: initialState,
+  onWorkspaceGroupLaunch: () => console.log("Workspace group launched"),
+  workspaceGroupCleanup: () => console.log("Cleaning up workspace group")
+});
+```

package/packages/framework/esm-framework/docs/functions/launchWorkspaceGroup2.md

@@ -0,0 +1,40 @@
+[O3 Framework](../API.md) / launchWorkspaceGroup2
+
+# Function: launchWorkspaceGroup2()
+
+> **launchWorkspaceGroup2**\<`GroupProps`\>(`groupName`, `groupProps`): `Promise`\<`boolean`\>
+
+Defined in: [packages/framework/esm-styleguide/src/workspaces2/workspace2.ts:32](https://github.com/Kipkemoii/openmrs-esm-core/blob/main/packages/framework/esm-styleguide/src/workspaces2/workspace2.ts#L32)
+
+**`Experimental`**
+
+Attempts to launch the specified workspace group with the given group props. Note that only one workspace group
+may be opened at any given time. If a workspace group is already opened, calling `launchWorkspaceGroup2` with
+either a different group name, or same group name but different incompatible props**, will result in prompting to
+confirm closing workspaces. If the user confirms, the opened group, along with its windows (and their workspaces), is closed, and
+the requested group is immediately opened.
+
+** 2 sets of props are compatible if either one is nullish, or if they are shallow equal.
+
+## Type Parameters
+
+### GroupProps
+
+`GroupProps` *extends* `object`
+
+## Parameters
+
+### groupName
+
+`string`
+
+### groupProps
+
+`null` | `GroupProps`
+
+## Returns
+
+`Promise`\<`boolean`\>
+
+a Promise that resolves to true if the specified workspace group with the specified group props
+ is successfully opened, or that it already is opened.

package/packages/framework/esm-framework/docs/functions/makeUrl.md

@@ -0,0 +1,26 @@
+[O3 Framework](../API.md) / makeUrl
+
+# Function: makeUrl()
+
+> **makeUrl**(`path`): `string`
+
+Defined in: [packages/framework/esm-api/src/openmrs-fetch.ts:23](https://github.com/Kipkemoii/openmrs-esm-core/blob/main/packages/framework/esm-api/src/openmrs-fetch.ts#L23)
+
+Append `path` to the OpenMRS SPA base.
+
+#### Example
+
+```ts
+makeUrl('/foo/bar');
+// => '/openmrs/foo/bar'
+```
+
+## Parameters
+
+### path
+
+`string`
+
+## Returns
+
+`string`

package/packages/framework/esm-framework/docs/functions/messageOmrsServiceWorker.md

@@ -0,0 +1,23 @@
+[O3 Framework](../API.md) / messageOmrsServiceWorker
+
+# Function: messageOmrsServiceWorker()
+
+> **messageOmrsServiceWorker**(`message`): `Promise`\<[`MessageServiceWorkerResult`](../interfaces/MessageServiceWorkerResult.md)\<`any`\>\>
+
+Defined in: [packages/framework/esm-offline/src/service-worker-messaging.ts:11](https://github.com/Kipkemoii/openmrs-esm-core/blob/main/packages/framework/esm-offline/src/service-worker-messaging.ts#L11)
+
+Sends the specified message to the application's service worker.
+
+## Parameters
+
+### message
+
+[`KnownOmrsServiceWorkerMessages`](../type-aliases/KnownOmrsServiceWorkerMessages.md)
+
+The message to be sent.
+
+## Returns
+
+`Promise`\<[`MessageServiceWorkerResult`](../interfaces/MessageServiceWorkerResult.md)\<`any`\>\>
+
+A promise which completes when the message has been successfully processed by the Service Worker.

package/packages/framework/esm-framework/docs/functions/navigate.md

@@ -0,0 +1,48 @@
+[O3 Framework](../API.md) / navigate
+
+# Function: navigate()
+
+> **navigate**(`to`): `void`
+
+Defined in: [packages/framework/esm-navigation/src/navigation/navigate.ts:49](https://github.com/Kipkemoii/openmrs-esm-core/blob/main/packages/framework/esm-navigation/src/navigation/navigate.ts#L49)
+
+Calls `location.assign` for non-SPA paths and [navigateToUrl](https://single-spa.js.org/docs/api/#navigatetourl) for SPA paths
+
+#### Example usage:
+```js
+@example
+const config = useConfig();
+const submitHandler = () => {
+  navigate({ to: config.links.submitSuccess });
+};
+```
+
+#### Example behavior::
+```js
+@example
+navigate({ to: "/some/path" }); // => window.location.assign("/some/path")
+navigate({ to: "https://single-spa.js.org/" }); // => window.location.assign("https://single-spa.js.org/")
+navigate({ to: "${openmrsBase}/some/path" }); // => window.location.assign("/openmrs/some/path")
+navigate({ to: "/openmrs/spa/foo/page" }); // => navigateToUrl("/openmrs/spa/foo/page")
+navigate({ to: "${openmrsSpaBase}/bar/page" }); // => navigateToUrl("/openmrs/spa/bar/page")
+navigate({ to: "/${openmrsSpaBase}/baz/page" }) // => navigateToUrl("/openmrs/spa/baz/page")
+navigate({ to: "https://o3.openmrs.org/${openmrsSpaBase}/qux/page" }); // => navigateToUrl("/openmrs/spa/qux/page")
+  if `window.location.origin` == "https://o3.openmrs.org", else will use window.location.assign
+```
+
+## Parameters
+
+### to
+
+[`NavigateOptions`](../interfaces/NavigateOptions.md)
+
+The target path or URL. Supports templating with 'openmrsBase', 'openmrsSpaBase',
+and any additional template parameters defined in `templateParams`.
+For example, `${openmrsSpaBase}/home` will resolve to `/openmrs/spa/home`
+for implementations using the standard OpenMRS and SPA base paths.
+If `templateParams` contains `{ foo: "bar" }`, then the URL `${openmrsBase}/${foo}`
+will become `/openmrs/bar`.
+
+## Returns
+
+`void`

package/packages/framework/esm-framework/docs/functions/navigateAndLaunchWorkspace.md

@@ -0,0 +1,33 @@
+[O3 Framework](../API.md) / navigateAndLaunchWorkspace
+
+# Function: navigateAndLaunchWorkspace()
+
+> **navigateAndLaunchWorkspace**(`__namedParameters`): `void`
+
+Defined in: [packages/framework/esm-styleguide/src/workspaces/workspaces.ts:389](https://github.com/Kipkemoii/openmrs-esm-core/blob/main/packages/framework/esm-styleguide/src/workspaces/workspaces.ts#L389)
+
+Use this function to navigate to a new page and launch a workspace on that page.
+
+## Parameters
+
+### \_\_namedParameters
+
+#### additionalProps?
+
+`object`
+
+#### contextKey
+
+`string`
+
+#### targetUrl
+
+`string`
+
+#### workspaceName
+
+`string`
+
+## Returns
+
+`void`

package/packages/framework/esm-framework/docs/functions/oneOf.md

@@ -0,0 +1,21 @@
+[O3 Framework](../API.md) / oneOf
+
+# Function: oneOf()
+
+> **oneOf**(`allowedValues`): [`Validator`](../type-aliases/Validator.md)
+
+Defined in: [packages/framework/esm-config/src/validators/validators.ts:58](https://github.com/Kipkemoii/openmrs-esm-core/blob/main/packages/framework/esm-config/src/validators/validators.ts#L58)
+
+Verifies that the value is one of the allowed options.
+
+## Parameters
+
+### allowedValues
+
+The list of allowable values
+
+`any`[] | readonly `any`[]
+
+## Returns
+
+[`Validator`](../type-aliases/Validator.md)

package/packages/framework/esm-framework/docs/functions/openmrsFetch.md

@@ -0,0 +1,75 @@
+[O3 Framework](../API.md) / openmrsFetch
+
+# Function: openmrsFetch()
+
+> **openmrsFetch**\<`T`\>(`path`, `fetchInit`): `Promise`\<[`FetchResponse`](../interfaces/FetchResponse.md)\<`T`\>\>
+
+Defined in: [packages/framework/esm-api/src/openmrs-fetch.ts:83](https://github.com/Kipkemoii/openmrs-esm-core/blob/main/packages/framework/esm-api/src/openmrs-fetch.ts#L83)
+
+The openmrsFetch function is a wrapper around the
+[browser's built-in fetch function](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch),
+with extra handling for OpenMRS-specific API behaviors, such as
+request headers, authentication, authorization, and the API urls.
+
+## Type Parameters
+
+### T
+
+`T` = `any`
+
+## Parameters
+
+### path
+
+`string`
+
+A string url to make the request to. Note that the
+  openmrs base url (by default `/openmrs`) will be automatically
+  prepended to the URL, so there is no need to include it.
+
+### fetchInit
+
+[`FetchConfig`](../interfaces/FetchConfig.md) = `{}`
+
+A [fetch init object](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch#Syntax).
+  Note that the `body` property does not need to be `JSON.stringify()`ed
+  because openmrsFetch will do that for you.
+
+## Returns
+
+`Promise`\<[`FetchResponse`](../interfaces/FetchResponse.md)\<`T`\>\>
+
+A [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)
+  that resolves with a [Response object](https://developer.mozilla.org/en-US/docs/Web/API/Response).
+  Note that the openmrs version of the Response object has already
+  downloaded the HTTP response body as json, and has an additional
+  `data` property with the HTTP response json as a javascript object.
+
+#### Example
+```js
+import { openmrsFetch } from '@openmrs/esm-api'
+const abortController = new AbortController();
+openmrsFetch(`${restBaseUrl}/session', {signal: abortController.signal})
+  .then(response => {
+    console.log(response.data.authenticated)
+  })
+  .catch(err => {
+    console.error(err.status);
+  })
+abortController.abort();
+openmrsFetch(`${restBaseUrl}/session', {
+  method: 'POST',
+  body: {
+    username: 'hi',
+    password: 'there',
+  }
+})
+```
+
+#### Cancellation
+
+To cancel a network request, use an
+[AbortController](https://developer.mozilla.org/en-US/docs/Web/API/AbortController/abort).
+It is best practice to cancel your network requests when the user
+navigates away from a page while the request is pending request, to
+free up memory and network resources and to prevent race conditions.

package/packages/framework/esm-framework/docs/functions/openmrsObservableFetch.md

@@ -0,0 +1,55 @@
+[O3 Framework](../API.md) / openmrsObservableFetch
+
+# Function: openmrsObservableFetch()
+
+> **openmrsObservableFetch**\<`T`\>(`url`, `fetchInit`): `Observable`\<[`FetchResponse`](../interfaces/FetchResponse.md)\<`T`\>\>
+
+Defined in: [packages/framework/esm-api/src/openmrs-fetch.ts:272](https://github.com/Kipkemoii/openmrs-esm-core/blob/main/packages/framework/esm-api/src/openmrs-fetch.ts#L272)
+
+The openmrsObservableFetch function is a wrapper around openmrsFetch
+that returns an [Observable](https://rxjs-dev.firebaseapp.com/guide/observable)
+instead of a promise. It exists in case using an Observable is
+preferred or more convenient than a promise.
+
+## Type Parameters
+
+### T
+
+`T`
+
+## Parameters
+
+### url
+
+`string`
+
+See [[openmrsFetch]]
+
+### fetchInit
+
+[`FetchConfig`](../interfaces/FetchConfig.md) = `{}`
+
+See [[openmrsFetch]]
+
+## Returns
+
+`Observable`\<[`FetchResponse`](../interfaces/FetchResponse.md)\<`T`\>\>
+
+An Observable that produces exactly one Response object.
+The response object is exactly the same as for [[openmrsFetch]].
+
+#### Example
+
+```js
+import { openmrsObservableFetch } from '@openmrs/esm-api'
+const subscription = openmrsObservableFetch(`${restBaseUrl}/session').subscribe(
+  response => console.log(response.data),
+  err => {throw err},
+  () => console.log('finished')
+)
+subscription.unsubscribe()
+```
+
+#### Cancellation
+
+To cancel the network request, simply call `subscription.unsubscribe();`

package/packages/framework/esm-framework/docs/functions/parseDate.md

@@ -0,0 +1,20 @@
+[O3 Framework](../API.md) / parseDate
+
+# Function: parseDate()
+
+> **parseDate**(`dateString`): `Date`
+
+Defined in: packages/framework/esm-utils/dist/dates/date-util.d.ts:31
+
+Utility function to parse an arbitrary string into a date.
+Uses `dayjs(dateString)`.
+
+## Parameters
+
+### dateString
+
+`string`
+
+## Returns
+
+`Date`

package/packages/framework/esm-framework/docs/functions/provide.md

@@ -0,0 +1,21 @@
+[O3 Framework](../API.md) / provide
+
+# Function: provide()
+
+> **provide**(`config`, `sourceName`): `void`
+
+Defined in: [packages/framework/esm-config/src/module-config/module-config.ts:270](https://github.com/Kipkemoii/openmrs-esm-core/blob/main/packages/framework/esm-config/src/module-config/module-config.ts#L270)
+
+## Parameters
+
+### config
+
+[`Config`](../interfaces/Config.md)
+
+### sourceName
+
+`string` = `'provided'`
+
+## Returns
+
+`void`

package/packages/framework/esm-framework/docs/functions/putDynamicOfflineData.md

@@ -0,0 +1,28 @@
+[O3 Framework](../API.md) / putDynamicOfflineData
+
+# Function: putDynamicOfflineData()
+
+> **putDynamicOfflineData**(`type`, `identifier`): `Promise`\<`void`\>
+
+Defined in: [packages/framework/esm-offline/src/dynamic-offline-data.ts:157](https://github.com/Kipkemoii/openmrs-esm-core/blob/main/packages/framework/esm-offline/src/dynamic-offline-data.ts#L157)
+
+Declares that dynamic offline data of the given [type](#putdynamicofflinedata) with the given [identifier](#putdynamicofflinedata)
+should be made available offline for the currently logged in user.
+
+## Parameters
+
+### type
+
+`string`
+
+The type of the offline data. See [DynamicOfflineData](../interfaces/DynamicOfflineData.md) for details.
+
+### identifier
+
+`string`
+
+The identifier of the offline data. See [DynamicOfflineData](../interfaces/DynamicOfflineData.md) for details.
+
+## Returns
+
+`Promise`\<`void`\>

package/packages/framework/esm-framework/docs/functions/putDynamicOfflineDataFor.md

@@ -0,0 +1,34 @@
+[O3 Framework](../API.md) / putDynamicOfflineDataFor
+
+# Function: putDynamicOfflineDataFor()
+
+> **putDynamicOfflineDataFor**(`userId`, `type`, `identifier`): `Promise`\<`void`\>
+
+Defined in: [packages/framework/esm-offline/src/dynamic-offline-data.ts:169](https://github.com/Kipkemoii/openmrs-esm-core/blob/main/packages/framework/esm-offline/src/dynamic-offline-data.ts#L169)
+
+Declares that dynamic offline data of the given [type](#putdynamicofflinedatafor) with the given [identifier](#putdynamicofflinedatafor)
+should be made available offline for the user with the given ID.
+
+## Parameters
+
+### userId
+
+`string`
+
+The ID of the user for whom the dynamic offline data should be made available.
+
+### type
+
+`string`
+
+The type of the offline data. See [DynamicOfflineData](../interfaces/DynamicOfflineData.md) for details.
+
+### identifier
+
+`string`
+
+The identifier of the offline data. See [DynamicOfflineData](../interfaces/DynamicOfflineData.md) for details.
+
+## Returns
+
+`Promise`\<`void`\>

package/packages/framework/esm-framework/docs/functions/queueSynchronizationItem.md

@@ -0,0 +1,39 @@
+[O3 Framework](../API.md) / queueSynchronizationItem
+
+# Function: queueSynchronizationItem()
+
+> **queueSynchronizationItem**\<`T`\>(`type`, `content`, `descriptor?`): `Promise`\<`number`\>
+
+Defined in: [packages/framework/esm-offline/src/sync.ts:261](https://github.com/Kipkemoii/openmrs-esm-core/blob/main/packages/framework/esm-offline/src/sync.ts#L261)
+
+Enqueues a new item in the sync queue and associates the item with the currently signed in user.
+
+## Type Parameters
+
+### T
+
+`T`
+
+## Parameters
+
+### type
+
+`string`
+
+The identifying type of the synchronization item.
+
+### content
+
+`T`
+
+The actual data to be synchronized.
+
+### descriptor?
+
+[`QueueItemDescriptor`](../interfaces/QueueItemDescriptor.md)
+
+An optional descriptor providing additional metadata about the sync item.
+
+## Returns
+
+`Promise`\<`number`\>

package/packages/framework/esm-framework/docs/functions/refetchCurrentUser.md

@@ -0,0 +1,33 @@
+[O3 Framework](../API.md) / refetchCurrentUser
+
+# Function: refetchCurrentUser()
+
+> **refetchCurrentUser**(`username?`, `password?`): `Promise`\<[`SessionStore`](../type-aliases/SessionStore.md)\>
+
+Defined in: [packages/framework/esm-api/src/current-user.ts:163](https://github.com/Kipkemoii/openmrs-esm-core/blob/main/packages/framework/esm-api/src/current-user.ts#L163)
+
+The `refetchCurrentUser` function causes a network request to redownload
+the user. All subscribers to the current user will be notified of the
+new users once the new version of the user object is downloaded.
+
+## Parameters
+
+### username?
+
+`string`
+
+### password?
+
+`string`
+
+## Returns
+
+`Promise`\<[`SessionStore`](../type-aliases/SessionStore.md)\>
+
+The same observable as returned by [[getCurrentUser]].
+
+#### Example
+```js
+import { refetchCurrentUser } from '@openmrs/esm-api'
+refetchCurrentUser()
+```

package/packages/framework/esm-framework/docs/functions/registerBreadcrumb.md

@@ -0,0 +1,17 @@
+[O3 Framework](../API.md) / registerBreadcrumb
+
+# Function: registerBreadcrumb()
+
+> **registerBreadcrumb**(`breadcrumb`): `void`
+
+Defined in: [packages/framework/esm-navigation/src/breadcrumbs/db.ts:18](https://github.com/Kipkemoii/openmrs-esm-core/blob/main/packages/framework/esm-navigation/src/breadcrumbs/db.ts#L18)
+
+## Parameters
+
+### breadcrumb
+
+[`BreadcrumbSettings`](../interfaces/BreadcrumbSettings.md)
+
+## Returns
+
+`void`

package/packages/framework/esm-framework/docs/functions/registerBreadcrumbs.md

@@ -0,0 +1,17 @@
+[O3 Framework](../API.md) / registerBreadcrumbs
+
+# Function: registerBreadcrumbs()
+
+> **registerBreadcrumbs**(`breadcrumbs`): `void`
+
+Defined in: [packages/framework/esm-navigation/src/breadcrumbs/db.ts:22](https://github.com/Kipkemoii/openmrs-esm-core/blob/main/packages/framework/esm-navigation/src/breadcrumbs/db.ts#L22)
+
+## Parameters
+
+### breadcrumbs
+
+[`BreadcrumbSettings`](../interfaces/BreadcrumbSettings.md)[]
+
+## Returns
+
+`void`