@koech/esm-core 8.0.0

package/packages/framework/esm-routes/src/loaders/pages.ts

@@ -0,0 +1,276 @@
+import { type ActivityFn, pathToActiveWhen, registerApplication } from 'single-spa';
+import { registerModuleWithConfigSystem } from '@openmrs/esm-config';
+import {
+  type WorkspaceGroupDefinition,
+  type ExtensionDefinition,
+  type FeatureFlagDefinition,
+  type ModalDefinition,
+  type OpenmrsAppRoutes,
+  type RegisteredPageDefinition,
+  type RouteDefinition,
+  type WorkspaceDefinition,
+} from '@openmrs/esm-globals';
+import { getFeatureFlag } from '@openmrs/esm-feature-flags';
+import { routeRegex } from './helpers';
+import {
+  tryRegisterExtension,
+  tryRegisterFeatureFlag,
+  tryRegisterModal,
+  tryRegisterWorkspace,
+  tryRegisterWorkspace2,
+  tryRegisterWorkspaceGroup,
+  tryRegisterWorkspaceGroups2,
+  tryRegisterWorkspaceWindows2,
+} from './components';
+import { loadLifeCycles } from './load-lifecycles';
+
+// this is the global holder of all pages registered in the app
+const pages: Array<RegisteredPageDefinition> = [];
+
+/**
+ * This takes a page's route definitions and returns a single-spa
+ * activityFn which returns true when the page matches the current
+ * route and false if it does not.
+ *
+ * @param route A string or regexp that matches the location when the
+ * page should be displayed, a boolean constant, or an array of such
+ * strings, regexps, and booleans
+ * @returns An activityFn suitable to use for a single-spa application
+ */
+function getActivityFn(route: RouteDefinition | Array<RouteDefinition>): ActivityFn {
+  if (Array.isArray(route)) {
+    const activators = route.map(getActivityFn);
+    return (location) => activators.some((activator) => activator(location));
+  } else if (typeof route === 'string') {
+    return pathToActiveWhen(window.getOpenmrsSpaBase() + route);
+  } else if (route instanceof RegExp) {
+    return (location) => routeRegex(route, location);
+  } else {
+    return () => route;
+  }
+}
+
+/**
+ * For pages, we also add support for rendered them based on online and offline mode as well as
+ * any feature flags.
+ *
+ * By default, we assume that all pages should be rendered when online, but only rendered
+ * offline if specifically configured to do so.
+ *
+ * @param activityFn A standard single-spa activityFn such as that returned by {@link getActivityFn()}
+ * @param pageDefinition The RegisteredPageDefinition object for this page
+ * @returns An activityFn suitable to use for a single-spa application
+ */
+function wrapPageActivityFn(
+  activityFn: ActivityFn,
+  { online, offline, featureFlag }: RegisteredPageDefinition,
+): ActivityFn {
+  if (window.offlineEnabled) {
+    return (location) => {
+      // basically, if the page should only work online and we're offline or if the
+      // page should only work offline and we're online, defaulting to always rendering
+      // the page
+      if (!((navigator.onLine && (online ?? true)) || (!navigator.onLine && (offline ?? false)))) {
+        return false;
+      }
+
+      if (featureFlag) {
+        if (!getFeatureFlag(featureFlag)) {
+          return false;
+        }
+      }
+
+      return activityFn(location);
+    };
+  } else {
+    return activityFn;
+  }
+}
+
+/**
+ * This is the main entry-point for registering an app with the app shell.
+ * Each app has a name and should have a `routes.json` file that defines it's
+ * associated routes.
+ *
+ * @param appName The name of the application, e.g. `@openmrs/esm-my-app`
+ * @param routes A Javascript object that corresponds to the app's  routes.json`
+ * definition.
+ */
+export function registerApp(appName: string, routes: OpenmrsAppRoutes) {
+  if (appName && routes && typeof routes === 'object') {
+    registerModuleWithConfigSystem(appName);
+
+    const availableExtensions: Array<ExtensionDefinition> = routes.extensions ?? [];
+    const availableModals: Array<ModalDefinition> = routes.modals ?? [];
+    const availableWorkspaces: Array<WorkspaceDefinition> = routes.workspaces ?? [];
+    const availableWorkspaceGroups: Array<WorkspaceGroupDefinition> = routes.workspaceGroups ?? [];
+    const availableFeatureFlags: Array<FeatureFlagDefinition> = routes.featureFlags ?? [];
+    const availableWorkspaceGroups2 = routes.workspaceGroups2 ?? [];
+    const availableWorkspaceWindows2 = routes.workspaceWindows2 ?? [];
+    const availableWorkspaces2 = routes.workspaces2 ?? [];
+
+    routes.pages?.forEach((p) => {
+      if (
+        p &&
+        typeof p === 'object' &&
+        Object.hasOwn(p, 'component') &&
+        (Object.hasOwn(p, 'route') || Object.hasOwn(p, 'routeRegex') || Object.hasOwn(p, 'routes'))
+      ) {
+        pages.push({
+          ...p,
+          appName,
+        });
+      } else {
+        console.warn(
+          `A page for ${appName} could not be registered as it does not appear to have the required properties`,
+          p,
+        );
+      }
+    });
+
+    availableExtensions.forEach((ext) => {
+      if (ext && typeof ext === 'object' && Object.hasOwn(ext, 'name') && Object.hasOwn(ext, 'component')) {
+        tryRegisterExtension(appName, ext);
+      } else {
+        console.warn(
+          `An extension for ${appName} could not be registered as it does not appear to have the required properties`,
+          ext,
+        );
+      }
+    });
+
+    availableModals.forEach((modal) => {
+      if (modal && typeof modal === 'object' && Object.hasOwn(modal, 'name') && Object.hasOwn(modal, 'component')) {
+        tryRegisterModal(appName, modal);
+      } else {
+        console.warn(
+          `A modal for ${appName} could not be registered as it does not appear to have the required properties`,
+          modal,
+        );
+      }
+    });
+
+    availableWorkspaces.forEach((workspace) => {
+      if (
+        workspace &&
+        typeof workspace === 'object' &&
+        Object.hasOwn(workspace, 'name') &&
+        Object.hasOwn(workspace, 'component')
+      ) {
+        tryRegisterWorkspace(appName, workspace);
+      } else {
+        console.warn(
+          `A workspace for ${appName} could not be registered as it does not appear to have the required properties`,
+          workspace,
+        );
+      }
+    });
+
+    availableWorkspaceGroups.forEach((workspaceGroup) => {
+      if (workspaceGroup && typeof workspaceGroup === 'object' && Object.hasOwn(workspaceGroup, 'name')) {
+        tryRegisterWorkspaceGroup(appName, workspaceGroup);
+      } else {
+        console.warn(
+          `A workspace group for ${appName} could not be registered as it does not appear to have the required properties`,
+          workspaceGroup,
+        );
+      }
+    });
+    tryRegisterWorkspaceGroups2(appName, availableWorkspaceGroups2);
+    tryRegisterWorkspaceWindows2(appName, availableWorkspaceWindows2);
+    tryRegisterWorkspace2(appName, availableWorkspaces2);
+
+    availableFeatureFlags.forEach((featureFlag) => {
+      if (featureFlag && typeof featureFlag === 'object' && Object.hasOwn(featureFlag, 'flagName')) {
+        tryRegisterFeatureFlag(appName, featureFlag);
+      } else {
+        console.warn(
+          `A feature flag for ${appName} could not be registered as it does not appear to have the required properties`,
+          featureFlag,
+        );
+      }
+    });
+  }
+}
+
+/**
+ * This is called by the app shell once all route entries have been processed.
+ * This registers the pages with the application, and creates the root div
+ * for each page in the DOM element specified by the page's containerDomId.
+ */
+export function finishRegisteringAllApps() {
+  pages.sort((a, b) => {
+    return a.appName.localeCompare(b.appName, 'en');
+  });
+
+  // Create a div for each page, unless the DOM already contains the div with
+  // the expected id for the page to be mounted on. See:
+  // https://single-spa.js.org/docs/configuration/#two-registered-applications-simultaneously
+  // The div is put inside the DOM element specified by the page's containerDomId.
+  // If we don't do this, Single-SPA 5 will create the DOM element only once
+  // the page becomes active, at the end of <body>.
+  let appIndices = new Map();
+  for (let page of pages) {
+    if (!appIndices.has(page.appName)) {
+      appIndices.set(page.appName, 0);
+    } else {
+      appIndices.set(page.appName, appIndices.get(page.appName) + 1);
+    }
+    const index = appIndices.get(page.appName);
+
+    const name = `${page.appName}-page-${index}`;
+    const containerDomId = page.containerDomId ?? 'omrs-apps-container';
+    const containerDiv = document.getElementById(containerDomId);
+    const appDomRootId = `single-spa-application:${name}`;
+
+    if (containerDiv) {
+      const div = document.createElement('div');
+      div.id = appDomRootId;
+      containerDiv?.appendChild(div);
+    } else {
+      throw new Error(
+        `${page.appName} ${page.component} cannot be mounted to "${containerDomId}"; DOM element does not exist.`,
+      );
+    }
+    tryRegisterPage(name, page);
+  }
+}
+
+/**
+ * This function converts each page definition into a single-spa application
+ * if that's possible. After this point, pages are rendered using single-spa's
+ * routing logic.
+ *
+ * @param appName The name of the app containing this page
+ * @param page An object that describes the page, derived from `routes.json`
+ */
+function tryRegisterPage(appName: string, page: RegisteredPageDefinition) {
+  const route =
+    typeof page.route !== 'undefined'
+      ? page.route
+      : typeof page.routeRegex !== 'undefined'
+        ? new RegExp(page.routeRegex)
+        : false;
+
+  if (route === false) {
+    console.warn(
+      `A registered page definition is missing a route and thus cannot be registered.
+To fix this, ensure that you define the "route" (or alternatively the "routeRegex") field inside the extension definition.`,
+      appName,
+    );
+    return;
+  }
+
+  if (!page.component) {
+    console.warn(
+      `A registered page definition is missing a component and thus cannot be registered.
+To fix this, ensure that you define the "component" field inside the page definition.`,
+      appName,
+    );
+    return;
+  }
+
+  const activityFn = wrapPageActivityFn(getActivityFn(route), page);
+  const loader = () => loadLifeCycles(page.appName, page.component);
+  registerApplication(appName, loader, activityFn);
+}

package/packages/framework/esm-routes/src/public.ts

@@ -0,0 +1,2 @@
+export * from './constants';
+export * from './routes';

package/packages/framework/esm-routes/src/routes.test.ts

@@ -0,0 +1,177 @@
+import createFetchMock from 'vitest-fetch-mock';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+createFetchMock(vi).enableMocks();
+
+import { addRoutesOverride, isOpenmrsAppRoutes } from './routes';
+
+describe('Openmrs Routes Utilities', () => {
+  describe('addRoutesOverride', () => {
+    beforeEach(() => localStorage.clear());
+
+    it('should add routes when provided as an object', () => {
+      addRoutesOverride('@openmrs/my-module', {
+        backendDependencies: {
+          fhir2: '^2.0.0',
+          'webservices.rest': '^1.4.0',
+        },
+        version: '1.2.0-pre.12345+build.8',
+        pages: [
+          {
+            component: 'root',
+            route: 'myPage',
+          },
+        ],
+        extensions: [
+          {
+            name: 'custom extension',
+            component: 'customExtension',
+          },
+        ],
+      });
+
+      expect(localStorage.getItem('openmrs-routes:@openmrs/my-module')).toBe(
+        '{"backendDependencies":{"fhir2":"^2.0.0","webservices.rest":"^1.4.0"},"version":"1.2.0-pre.12345+build.8","pages":[{"component":"root","route":"myPage"}],"extensions":[{"name":"custom extension","component":"customExtension"}]}',
+      );
+    });
+
+    it('should add routes when provided as a JSON string', () => {
+      addRoutesOverride(
+        '@openmrs/my-module',
+        JSON.stringify({
+          backendDependencies: {
+            fhir2: '^2.0.0',
+            'webservices.rest': '^1.4.0',
+          },
+          version: '1.2.0-pre.12345+build.8',
+          pages: [
+            {
+              component: 'root',
+              route: 'myPage',
+            },
+          ],
+          extensions: [
+            {
+              name: 'custom extension',
+              component: 'customExtension',
+            },
+          ],
+        }),
+      );
+
+      expect(localStorage.getItem('openmrs-routes:@openmrs/my-module')).toBe(
+        '{"backendDependencies":{"fhir2":"^2.0.0","webservices.rest":"^1.4.0"},"version":"1.2.0-pre.12345+build.8","pages":[{"component":"root","route":"myPage"}],"extensions":[{"name":"custom extension","component":"customExtension"}]}',
+      );
+    });
+
+    it('should add routes when loaded via a string HTTP endpoint', () => {
+      addRoutesOverride('@openmrs/my-module', 'http://localhost/my-route-override.json');
+
+      expect(localStorage.getItem('openmrs-routes:@openmrs/my-module')).toBe(
+        '"http://localhost/my-route-override.json"',
+      );
+    });
+
+    it('should add routes when loaded via a URL HTTP endpoint', () => {
+      addRoutesOverride('@openmrs/my-module', new URL('http://localhost/my-route-override.json'));
+
+      expect(localStorage.getItem('openmrs-routes:@openmrs/my-module')).toBe(
+        '"http://localhost/my-route-override.json"',
+      );
+    });
+  });
+
+  describe('isOpenmrsAppRoutes', () => {
+    it('should return true for a valid routes object', () => {
+      expect(
+        isOpenmrsAppRoutes({
+          backendDependencies: {
+            fhir2: '^2.0.0',
+            'webservices.rest': '^1.4.0',
+          },
+          version: '1.2.0-pre.12345+build.8',
+          pages: [
+            {
+              component: 'root',
+              route: 'myPage',
+            },
+          ],
+          extensions: [
+            {
+              name: 'custom extension',
+              component: 'customExtension',
+            },
+          ],
+          modals: [
+            {
+              name: 'custom modal',
+              component: 'customModal',
+            },
+          ],
+          workspaces: [
+            {
+              name: 'custom workspace',
+              component: 'customWorkspace',
+            },
+          ],
+        }),
+      ).toBe(true);
+    });
+
+    it('should accept an object with only pages', () => {
+      expect(
+        isOpenmrsAppRoutes({
+          pages: [
+            {
+              component: 'root',
+              route: 'myPage',
+            },
+          ],
+        }),
+      ).toBe(true);
+    });
+
+    it('should accept an object with only extensions', () => {
+      expect(
+        isOpenmrsAppRoutes({
+          extensions: [
+            {
+              name: 'custom extension',
+              component: 'customExtension',
+            },
+          ],
+        }),
+      ).toBe(true);
+    });
+
+    it('should accept an object with only modals', () => {
+      expect(
+        isOpenmrsAppRoutes({
+          modals: [
+            {
+              name: 'custom modal',
+              component: 'customModal',
+            },
+          ],
+        }),
+      ).toBe(true);
+    });
+
+    it('should accept an object with only workspaces', () => {
+      expect(
+        isOpenmrsAppRoutes({
+          workspaces: [
+            {
+              name: 'custom workspace',
+              component: 'customWorkspace',
+            },
+          ],
+        }),
+      ).toBe(true);
+    });
+
+    it('should report an empty object as valid', () => {
+      expect(isOpenmrsAppRoutes({})).toBe(true);
+    });
+  });
+});

package/packages/framework/esm-routes/src/routes.ts

@@ -0,0 +1,154 @@
+/** @module @category Routes Utilities */
+import type { OpenmrsAppRoutes, OpenmrsRoutes } from '@openmrs/esm-globals';
+import { canAccessStorage } from '@openmrs/esm-utils';
+import { localStorageRoutesPrefix } from './constants';
+
+const isEnabled = canAccessStorage();
+
+/**
+ * Used to add a route override to local storage. These are read as the routes registry
+ * is assembled, so the app must be reloaded for new overrides to take effect.
+ *
+ * @internal
+ * @param moduleName The name of the module the routes are for
+ * @param routes Either an {@link OpenmrsAppRoutes} object, a string that represents a JSON
+ *  version of an {@link OpenmrsAppRoutes} object or a string or URL that resolves to a
+ *  JSON document that represents an {@link OpenmrsAppRoutes} object
+ */
+export function addRoutesOverride(moduleName: string, routes: OpenmrsAppRoutes | string | URL) {
+  if (!isEnabled) {
+    return;
+  }
+
+  if (typeof routes === 'string') {
+    if (routes.startsWith('http')) {
+      return addRouteOverrideInternal(moduleName, routes);
+    } else {
+      try {
+        const maybeRoutes = JSON.parse(routes);
+        if (isOpenmrsAppRoutes(maybeRoutes)) {
+          return addRouteOverrideInternal(moduleName, maybeRoutes);
+        } else {
+          console.error(`The supplied routes for ${moduleName} is not a valid OpenmrsAppRoutes object`, routes);
+        }
+      } catch (e) {
+        console.error(`Could not add routes override for ${moduleName}: `, e);
+      }
+    }
+  } else if (routes instanceof URL) {
+    return addRouteOverrideInternal(moduleName, routes.toString());
+  } else if (isOpenmrsAppRoutes(routes)) {
+    return addRouteOverrideInternal(moduleName, routes);
+  }
+
+  console.error(
+    `Override for ${moduleName} is not in a valid format. Expected either a Javascript Object, a JSON string of a Javascript object, or a URL`,
+    routes,
+  );
+}
+
+/**
+ * Used to remove an existing routes override from local storage. These are read as the routes registry
+ * is assembled, so the app must be reloaded for removed override to be removed.
+ *
+ * @internal
+ * @param moduleName The module to remove the overrides for
+ */
+export function removeRoutesOverride(moduleName: string) {
+  if (!isEnabled) {
+    return;
+  }
+
+  const key = localStorageRoutesPrefix + moduleName;
+  localStorage.removeItem(key);
+}
+
+/**
+ * Used to remove all existing routes overrides from local storage. These are read as the routes registry
+ * is assembled, so the app must be reloaded for the removed overrides to appear to be removed.
+ *
+ * @internal
+ */
+export function resetAllRoutesOverrides() {
+  if (!isEnabled) {
+    return;
+  }
+
+  const localStorage = window.localStorage;
+  for (let i = 0; i < localStorage.length; i++) {
+    const key = localStorage.key(i);
+    if (key?.startsWith(localStorageRoutesPrefix)) {
+      localStorage.removeItem(key);
+    }
+  }
+}
+
+function addRouteOverrideInternal(moduleName: string, routes: OpenmrsAppRoutes | string) {
+  const key = localStorageRoutesPrefix + moduleName;
+  localStorage.setItem(key, JSON.stringify(routes));
+}
+
+/**
+ * Simple type-predicate to ensure that the value can be treated as an OpenmrsAppRoutes
+ * object.
+ *
+ * @internal
+ * @param routes the object to check to see if it is an OpenmrsAppRoutes object
+ * @returns true if the routes value is an OpenmrsAppRoutes
+ */
+export function isOpenmrsAppRoutes(routes: OpenmrsAppRoutes | unknown): routes is OpenmrsAppRoutes {
+  if (routes && typeof routes === 'object') {
+    const hasOwnProperty = Object.prototype.hasOwnProperty;
+    // we cast maybeRoutes as OpenmrsAppRoutes mainly so we can refer to the properties it should
+    // have without repeated casts
+    const maybeRoutes = routes as OpenmrsAppRoutes;
+
+    if (hasOwnProperty.call(routes, 'pages')) {
+      if (!Boolean(maybeRoutes.pages) || !Array.isArray(maybeRoutes.pages)) {
+        return false;
+      }
+    }
+
+    if (hasOwnProperty.call(routes, 'extensions')) {
+      if (!Boolean(maybeRoutes.extensions) || !Array.isArray(maybeRoutes.extensions)) {
+        return false;
+      }
+    }
+
+    if (hasOwnProperty.call(routes, 'workspaces')) {
+      if (!Boolean(maybeRoutes.workspaces) || !Array.isArray(maybeRoutes.workspaces)) {
+        return false;
+      }
+    }
+
+    if (hasOwnProperty.call(routes, 'modals')) {
+      if (!Boolean(maybeRoutes.modals) || !Array.isArray(maybeRoutes.modals)) {
+        return false;
+      }
+    }
+
+    // Notice that we're essentially testing for things that cannot be treated as an OpenmrsAppRoutes
+    // object. This is because a completely empty object is a valid OpenmrsAppRoutes object.
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Simple type-predicate to ensure that the value can be treated as an OpenmrsRoutes
+ * object.
+ *
+ * @internal
+ * @param routes the object to check to see if it is an OpenmrsRoutes object
+ * @returns true if the routes value is an OpenmrsRoutes
+ */
+export function isOpenmrsRoutes(routes: OpenmrsRoutes | unknown): routes is OpenmrsRoutes {
+  if (routes && typeof routes === 'object') {
+    const maybeRoutes = routes as OpenmrsRoutes;
+
+    return Object.entries(maybeRoutes).every(([key, value]) => typeof key === 'string' && isOpenmrsAppRoutes(value));
+  }
+
+  return false;
+}

package/packages/framework/esm-routes/tsconfig.build.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig.json",
+  "compilerOptions": {
+    "declarationDir": "dist",
+    "emitDeclarationOnly": true
+  },
+  "extends": "./tsconfig.json",
+  "exclude": ["**/*.test.*", "**/setup-tests.*"]
+}

package/packages/framework/esm-routes/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig.json",
+  "extends": "../tsconfig.json",
+  "include": ["src/**/*.ts*"]
+}

package/packages/framework/esm-routes/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    environment: 'happy-dom',
+    mockReset: true,
+  },
+});

package/packages/framework/esm-state/.swcrc

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://swc.rs/schema.json",
+  "exclude": [".*\\.test\\..*", "setup-tests\\..*"],
+  "module": {
+    "type": "es6",
+    "resolveFully": true
+  },
+  "jsc": {
+    "parser": {
+      "syntax": "typescript",
+      "tsx": false
+    },
+    "target": "es2020",
+    "baseUrl": "src"
+  }
+}

package/packages/framework/esm-state/README.md

@@ -0,0 +1,9 @@
+# openmrs-esm-state
+
+openmrs-esm-state provides functions for managing OpenMRS state using
+[Unistore](https://github.com/developit/unistore#unistore).
+
+It also provides a global Unistore store called `app`.
+
+Please see the Developer Documentation page on
+[Storing values](https://o3-docs.openmrs.org/docs/recipes/store-values).