Delineate public vs private API of esm-framework (#376)

docs/main/config.md

@@ -9,10 +9,7 @@ please see the the
 
 ## How to make a frontend module configurable
 
-You should use this part of the OpenMRS Frontend Framework to modules configurable.
-
-Start with `npm install --save-dev @openmrs/esm-framework`. This is a runtime
-dependency, so you should also include it in `peerDependencies`.
+You should use the OpenMRS Frontend Framework to make modules configurable.
 
 The main task is to create a config schema for your module. The config schema
 is what tells the framework what configuration files should look like,
@@ -151,7 +148,7 @@ colorPicker: {
 ```
 
 For convenience, some common validators are provided out of the box. See the
-[API / validators](../../packages/framework/esm-framework/docs/API.md#validators).
+[API / validators](https://github.com/openmrs/openmrs-esm-core/blob/master/packages/framework/esm-framework/docs/API.md#validators).
 
 #### Arrays
 
@@ -299,7 +296,7 @@ the element, but this may change in future versions.
 
 #### `_type`
 
-One of the values from [the `Type` enum](../../packages/framework/esm-framework/docs/enums/Type.md). Used for validation and to help the
+One of the values from [the `Type` enum](https://github.com/openmrs/openmrs-esm-core/blob/master/packages/framework/esm-framework/docs/enums/Type.md). Used for validation and to help the
 implementer tools work with the element.
 
 Should always appear alongside `_default`.
@@ -316,10 +313,10 @@ Can be used anywhere within the schema structure.
 An array of validator objects.
 
 Some common validators are
-provided: [API / validators](../../packages/framework/esm-framework/docs/API.md#const-validators).
+provided: [API / validators](https://github.com/openmrs/openmrs-esm-core/blob/master/packages/framework/esm-framework/docs/API.md#config-validation-functions).
 
 Custom validators should
-be created with the [validator](../../packages/framework/esm-framework/docs/API.md#validator) function.
+be created with the [validator](https://github.com/openmrs/openmrs-esm-core/blob/master/packages/framework/esm-framework/docs/API.md#validator) function.
 
 Can be used anywhere within the schema structure.
 
@@ -329,6 +326,10 @@ Only valid alongside `_type: Type.Array` or `_type: Type.Object`. A `_default`
 must also be provided at this level. Value should be an object which is
 a schema for the values contained in the array or object.
 
+## API Documentation
+
+See the Config Functions section of the [API docs](https://github.com/openmrs/openmrs-esm-core/blob/master/packages/framework/esm-framework/docs/API.md).
+
 ## The RFC
 
 This package was established as the result of

packages/apps/esm-implementer-tools-app/src/configuration/configuration.component.tsx

@@ -12,7 +12,7 @@ import {
   temporaryConfigStore,
   useStore,
   useStoreWithActions,
-} from "@openmrs/esm-framework";
+} from "@openmrs/esm-framework/src/internal";
 import {
   Button,
   TextInput,

packages/apps/esm-implementer-tools-app/src/configuration/configuration.test.tsx

@@ -6,7 +6,7 @@ import {
   implementerToolsConfigStore,
   temporaryConfigStore,
   Type,
-} from "@openmrs/esm-framework";
+} from "@openmrs/esm-framework/src/internal";
 import { Configuration } from "./configuration.component";
 import {
   performConceptSearch,

packages/apps/esm-implementer-tools-app/src/configuration/interactive-editor/editable-value.component.tsx

@@ -12,7 +12,7 @@ import {
   Type,
   Config,
   temporaryConfigStore,
-} from "@openmrs/esm-framework";
+} from "@openmrs/esm-framework/src/internal";
 import { ValueEditor, CustomValueType } from "./value-editor";
 import { implementerToolsStore, ImplementerToolsStore } from "../../store";
 import { DisplayValue } from "./display-value";

packages/apps/esm-implementer-tools-app/src/configuration/interactive-editor/value-editors/extension-slot-add.tsx

@@ -3,7 +3,7 @@ import { MultiSelect } from "carbon-components-react";
 import {
   ExtensionInternalStore,
   getExtensionInternalStore,
-} from "@openmrs/esm-framework";
+} from "@openmrs/esm-framework/src/internal";
 
 const extensionInternalStore = getExtensionInternalStore();
 

packages/apps/esm-implementer-tools-app/src/configuration/json-editor/json-editor.component.tsx

@@ -1,5 +1,8 @@
 import React, { useCallback, useEffect, useState } from "react";
-import { temporaryConfigStore, useStore } from "@openmrs/esm-framework";
+import {
+  temporaryConfigStore,
+  useStore,
+} from "@openmrs/esm-framework/src/internal";
 import AceEditor from "react-ace";
 import style from "./json-editor.scss";
 

packages/apps/esm-implementer-tools-app/src/ui-editor/ui-editor.tsx

@@ -5,7 +5,7 @@ import {
   getExtensionInternalStore,
   useStore,
   useStoreWithActions,
-} from "@openmrs/esm-framework";
+} from "@openmrs/esm-framework/src/internal";
 import { Button } from "carbon-components-react";
 import { Portal } from "./portal";
 import { ExtensionOverlay } from "./extension-overlay.component";

packages/apps/esm-offline-tools-app/src/hooks/offline-actions.ts

@@ -3,7 +3,7 @@ import {
   getOfflineDb,
   getSynchronizationItems,
   SyncItem,
-} from "@openmrs/esm-framework";
+} from "@openmrs/esm-framework/src/internal";
 import uniq from "lodash-es/uniq";
 import useSWR from "swr";
 

packages/apps/esm-offline-tools-app/src/offline-actions/offline-actions-mode-button.component.tsx

@@ -5,7 +5,7 @@ import Network20 from "@carbon/icons-react/es/network--3/20";
 import {
   getCurrentOfflineMode,
   setCurrentOfflineMode,
-} from "@openmrs/esm-framework";
+} from "@openmrs/esm-framework/src/internal";
 import styles from "./offline-actions-mode-button.component.scss";
 
 function doNotCloseMenu(ev: React.SyntheticEvent) {

packages/apps/esm-offline-tools-app/src/offline-actions/offline-actions-page.component.tsx

@@ -4,7 +4,7 @@ import {
   runSynchronization,
   useLayoutType,
   useStore,
-} from "@openmrs/esm-framework";
+} from "@openmrs/esm-framework/src/internal";
 import { Button } from "carbon-components-react";
 import { useTranslation } from "react-i18next";
 import SharedPageLayout from "../components/shared-page-layout.component";

packages/apps/esm-offline-tools-app/src/offline-actions/offline-actions-table.component.tsx

@@ -29,7 +29,7 @@ import {
   SyncItem,
   canBeginEditSynchronizationItemsOfType,
   beginEditSynchronizationItem,
-} from "@openmrs/esm-framework";
+} from "@openmrs/esm-framework/src/internal";
 
 export interface SyncItemWithPatient {
   item: SyncItem;

packages/apps/esm-offline-tools-app/src/offline-actions/offline-actions.component.tsx

@@ -4,7 +4,7 @@ import {
   showModal,
   SyncItem,
   useStore,
-} from "@openmrs/esm-framework";
+} from "@openmrs/esm-framework/src/internal";
 import React from "react";
 import { useTranslation } from "react-i18next";
 import OfflineActionsTable from "./offline-actions-table.component";

packages/apps/esm-offline-tools-app/src/offline-actions/synchronizing-notification.tsx

@@ -4,7 +4,7 @@ import {
   OfflineSynchronizationStore,
   showNotification,
   useStore,
-} from "@openmrs/esm-framework";
+} from "@openmrs/esm-framework/src/internal";
 import { getI18n, useTranslation } from "react-i18next";
 import { Loading, NotificationActionButton } from "carbon-components-react";
 import styles from "./synchronizing-notification.styles.scss";

packages/apps/esm-primary-navigation-app/src/components/choose-locale/change-locale.resource.tsx

@@ -3,7 +3,7 @@ import {
   queueSynchronizationItemFor,
   getSessionLocation,
   setSessionLocation,
-} from "@openmrs/esm-framework";
+} from "@openmrs/esm-framework/src/internal";
 import { userPropertyChange } from "../../constants";
 
 export type PostUserProperties = (

packages/apps/esm-primary-navigation-app/src/offline.ts

@@ -2,7 +2,7 @@ import {
   refetchCurrentUser,
   getLoggedInUser,
   SyncProcessOptions,
-} from "@openmrs/esm-framework";
+} from "@openmrs/esm-framework/src/internal";
 import { postUserPropertiesOnline } from "./components/choose-locale/change-locale.resource";
 
 export async function syncUserLanguagePreference(

packages/apps/esm-primary-navigation-app/src/root.resource.tsx

@@ -3,7 +3,7 @@ import {
   getCurrentUser,
   getSynchronizationItemsFor,
   openmrsObservableFetch,
-} from "@openmrs/esm-framework";
+} from "@openmrs/esm-framework/src/internal";
 import { mergeMap } from "rxjs/operators";
 import { userPropertyChange } from "./constants";
 

packages/framework/esm-api/src/fhir.ts

@@ -1,7 +1,4 @@
-/**
- * @module
- * @category API
- */
+/** @module @category API */
 import { openmrsFetch, FetchHeaders, OpenmrsFetchError } from "./openmrs-fetch";
 import type { FhirClient } from "./types/fhir";
 

packages/framework/esm-api/src/openmrs-fetch.ts

@@ -1,15 +1,21 @@
-/**
- * @module
- * @category API
- */
-
+/** @module @category API */
 import { Observable } from "rxjs";
 import isPlainObject from "lodash-es/isPlainObject";
 import { getConfig, navigate } from "@openmrs/esm-config";
 import { FetchResponse } from "./types";
 
 export const sessionEndpoint = "/ws/rest/v1/session";
 
+/**
+ * Append `path` to the OpenMRS SPA base.
+ *
+ * #### Example
+ *
+ * ```ts
+ * makeUrl('/foo/bar');
+ * // => '/openmrs/foo/bar'
+ * ```
+ */
 export function makeUrl(path: string) {
   return window.openmrsBase + path;
 }

packages/framework/esm-api/src/public.ts

@@ -0,0 +1,11 @@
+export * from "./types";
+export * from "./openmrs-fetch";
+export * from "./fhir";
+
+export * from "./shared-api-objects/current-user";
+export * from "./shared-api-objects/current-patient";
+export * from "./shared-api-objects/visit-utils";
+export * from "./shared-api-objects/visit-type";
+export * from "./shared-api-objects/location";
+
+export * from "./openmrs-backend-dependencies";

packages/framework/esm-api/src/shared-api-objects/current-patient.ts

@@ -1,8 +1,4 @@
-/**
- * @module
- * @category API
- */
-
+/** @module @category API */
 import { fhir } from "../fhir";
 import { FetchResponse } from "../types";
 

packages/framework/esm-api/src/shared-api-objects/current-user.ts

@@ -1,8 +1,4 @@
-/**
- * @module
- * @category API
- */
-
+/** @module @category API */
 import { Observable, ReplaySubject } from "rxjs";
 import { filter, map, tap, mergeAll } from "rxjs/operators";
 import { openmrsFetch, sessionEndpoint } from "../openmrs-fetch";

packages/framework/esm-api/src/shared-api-objects/location.ts

@@ -1,8 +1,4 @@
-/**
- * @module
- * @category API
- */
-
+/** @module @category API */
 import { Observable } from "rxjs";
 import { map, take } from "rxjs/operators";
 import { openmrsObservableFetch } from "../openmrs-fetch";

packages/framework/esm-api/src/shared-api-objects/visit-type.ts

@@ -1,8 +1,4 @@
-/**
- * @module
- * @category API
- */
-
+/** @module @category API */
 import { Observable } from "rxjs";
 import { map, take } from "rxjs/operators";
 import { openmrsObservableFetch } from "../openmrs-fetch";

packages/framework/esm-api/src/shared-api-objects/visit-utils.ts

@@ -1,8 +1,4 @@
-/**
- * @module
- * @category API
- */
-
+/** @module @category API */
 import { Observable, BehaviorSubject } from "rxjs";
 import { take, map } from "rxjs/operators";
 import { openmrsObservableFetch } from "../openmrs-fetch";

packages/framework/esm-breadcrumbs/src/db.ts

@@ -1,3 +1,4 @@
+/** @module @category Breadcrumb */
 import { pathToRegexp } from "path-to-regexp";
 import { createGlobalStore } from "@openmrs/esm-state";
 import { BreadcrumbSettings, BreadcrumbRegistration } from "./types";
@@ -17,21 +18,10 @@ function getMatcher(settings: BreadcrumbSettings) {
   }
 }
 
-/**
- *
- * @param breadcrumb
- * @returns
- * @category Breadcrumb
- */
 export function registerBreadcrumb(breadcrumb: BreadcrumbSettings) {
   return registerBreadcrumbs([breadcrumb]);
 }
 
-/**
- *
- * @param breadcrumbs
- * @category Breadcrumb
- */
 export function registerBreadcrumbs(breadcrumbs: Array<BreadcrumbSettings>) {
   const prevBreadcrumbs = getBreadcrumbs();
   const newBreadcrumbs = breadcrumbs.map((settings) => ({
@@ -42,11 +32,6 @@ export function registerBreadcrumbs(breadcrumbs: Array<BreadcrumbSettings>) {
   store.setState(nextBreadcrumbs, true);
 }
 
-/**
- *
- * @returns
- * @category Breadcrumb
- */
 export function getBreadcrumbs() {
   return store.getState();
 }

packages/framework/esm-breadcrumbs/src/filter.ts

@@ -1,3 +1,4 @@
+/** @module @category Breadcrumb */
 import { getBreadcrumbs } from "./db";
 import { BreadcrumbRegistration } from "./types";
 
@@ -39,13 +40,6 @@ function getNext(
   return undefined;
 }
 
-/**
- *
- * @param list
- * @param path
- * @returns
- * @category Breadcrumb
- */
 export function filterBreadcrumbs(
   list: Array<BreadcrumbRegistration>,
   path: string
@@ -69,12 +63,6 @@ export function filterBreadcrumbs(
   return [];
 }
 
-/**
- *
- * @param path
- * @returns
- * @category Breadcrumb
- */
 export function getBreadcrumbsFor(path: string) {
   const breadcrumbs = getBreadcrumbs();
   return filterBreadcrumbs(breadcrumbs, path);

packages/framework/esm-breadcrumbs/src/types.ts

@@ -1,3 +1,5 @@
+/** @module @category Breadcrumb */
+
 export interface BreadcrumbSettings {
   /**
    * Gets the path of breadcrumb for navigation purposes.

packages/framework/esm-config/src/module-config/module-config.ts

@@ -1,3 +1,4 @@
+/** @module @category Config */
 import { clone, reduce, mergeDeepRight, equals } from "ramda";
 import {
   Config,
@@ -271,6 +272,7 @@ export function getConfig(moduleName: string): Promise<Config> {
  * @param providedConfig  an object of config values (without the top-level module name)
  * @param keyPathContext  a dot-deparated string which helps the user figure out where
  *     the provided config came from
+ * @internal
  */
 export function processConfig(
   schema: ConfigSchema,

packages/framework/esm-config/src/module-config/state.ts

@@ -1,3 +1,4 @@
+/** @module @category Config */
 import { createGlobalStore, getGlobalStore } from "@openmrs/esm-state";
 import {
   Config,