@koech/esm-core 8.0.0

package/packages/framework/esm-utils/src/patient-helpers.ts

@@ -0,0 +1,95 @@
+/** @module @category Utility */
+
+import { type NameUse } from '@openmrs/esm-globals';
+
+/**
+ * Gets the formatted display name for a patient.
+ *
+ * The display name will be taken from the patient's 'usual' name,
+ * or may fall back to the patient's 'official' name.
+ *
+ * @param patient The patient details in FHIR format.
+ * @returns The patient's display name or an empty string if name is not present.
+ */
+export function getPatientName(patient: fhir.Patient): string {
+  const name = selectPreferredName(patient, 'usual', 'official');
+  return formatPatientName(name);
+}
+
+/** @deprecated Use `getPatientName` */
+export function displayName(patient: fhir.Patient): string {
+  return getPatientName(patient);
+}
+
+/**
+ * Get a formatted display string for an FHIR name.
+ * @param name The name to be formatted.
+ * @returns The formatted display name or an empty string if name is undefined.
+ */
+export function formatPatientName(name: fhir.HumanName | undefined): string {
+  if (name) return name.text ?? defaultFormat(name);
+  return '';
+}
+
+/** @deprecated Use `formatPatientName` */
+export function formattedName(name: fhir.HumanName | undefined): string {
+  return formatPatientName(name);
+}
+
+/**
+ * Select the preferred name from the collection of names associated with a patient.
+ *
+ * Names may be specified with a usage such as 'usual', 'official', 'nickname', 'maiden', etc.
+ * A name with no usage specified is treated as the 'usual' name.
+ *
+ * The chosen name will be selected according to the priority order of `preferredNames`,
+ * @example
+ * // normal use case; prefer usual name, fallback to official name
+ * displayNameByUsage(patient, 'usual', 'official')
+ * @example
+ * // prefer usual name over nickname, fallback to official name
+ * displayNameByUsage(patient, 'usual', 'nickname', 'official')
+ *
+ * @param patient The patient from whom a name will be selected.
+ * @param preferredNames Optional ordered sequence of preferred name usages; defaults to 'usual' if not specified.
+ * @return the preferred name for the patient, or undefined if no acceptable name could be found.
+ */
+export function selectPreferredName(patient: fhir.Patient, ...preferredNames: NameUse[]): fhir.HumanName | undefined {
+  if (preferredNames.length == 0) {
+    preferredNames = ['usual'];
+  }
+  for (const usage of preferredNames) {
+    const name = patient.name?.find((name) => nameUsageMatches(name, usage));
+    if (name) {
+      return name;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Generate a display name by concatenating forenames and surname.
+ * @param name the person's name.
+ * @returns the person's name as a string.
+ */
+function defaultFormat(name: fhir.HumanName): string {
+  const forenames: string[] = name.given ?? [];
+  const names: string[] = name.family ? forenames.concat(name.family) : forenames;
+  return names.join(' ');
+}
+
+/**
+ * Determine whether the usage of a given name matches the given NameUse.
+ *
+ * A name with no usage is treated as the 'usual' name.
+ *
+ * @param name the name to test.
+ * @param usage the NameUse to test for.
+ */
+function nameUsageMatches(name: fhir.HumanName, usage: NameUse): boolean {
+  if (!name.use)
+    // a name with no usage is treated as 'usual'
+    return usage === 'usual';
+
+  return name.use === usage;
+}

package/packages/framework/esm-utils/src/retry.ts

@@ -0,0 +1,78 @@
+/** @module @category Utility */
+
+/**
+ * Options for configuring the behavior of the {@link retry} function.
+ */
+export interface RetryOptions {
+  /**
+   * Determines whether the retry function should retry executing the function after it failed
+   * with an error on the current attempt.
+   * @param attempt The current (zero-based) retry attempt. `0` indicates the initial attempt.
+   */
+  shouldRetry?(attempt: number);
+  /**
+   * Calculates the next delay (in milliseconds) before a retry attempt.
+   * Returning a value for the inital attempt (`0`) delays the initial function invocation.
+   * @param attempt The current (zero-based) retry attempt. `0` indicates the initial attempt.
+   */
+  getDelay?(attempt: number): number;
+  /**
+   * Called when invoking the function resulted in an error.
+   * Allows running side-effects on errors, e.g. logging.
+   * @param e The error thrown by the function.
+   * @param attempt The current (zero-based) retry attempt. `0` indicates the initial attempt.
+   */
+  onError?(e: any, attempt: number): void;
+}
+
+/**
+ * Executes the specified function and retries executing on failure with a custom backoff strategy
+ * defined by the options.
+ *
+ * If not configured otherwise, this function uses the following default options:
+ * * Retries 5 times beyond the initial attempt.
+ * * Uses an exponential backoff starting with an initial delay of 1000ms.
+ * @param fn The function to be executed and retried on failure.
+ * @param options Additional options which configure the retry behavior.
+ * @returns The result of successfully executing `fn`.
+ * @throws Rethrows the final error of running `fn` when the function stops retrying.
+ */
+export async function retry<T>(fn: () => Promise<T>, options: RetryOptions = {}) {
+  let { shouldRetry, getDelay, onError } = options;
+  shouldRetry = shouldRetry ?? ((attempt) => limitAttempts(attempt, 5));
+  getDelay = getDelay ?? ((attempt) => getExponentialDelay(attempt, 1000));
+
+  let attempt = 0;
+  let lastError: any = undefined;
+
+  do {
+    try {
+      await delay(getDelay(attempt));
+      return await fn();
+    } catch (e) {
+      onError?.(e, attempt);
+      lastError = e;
+    }
+  } while (shouldRetry(attempt++));
+
+  // If we reach this fn errored and shouldn't retry anymore. Simply rethrow the final error as
+  // a means of ending the retry process without a result.
+  throw lastError;
+}
+
+function limitAttempts(attempt: number, maxAttempts: number) {
+  return attempt <= maxAttempts;
+}
+
+function getExponentialDelay(attempt: number, startingDelay: number, initialDelay = false) {
+  const exponent = initialDelay ? attempt + 1 : attempt;
+  return startingDelay * Math.pow(2, exponent);
+}
+
+async function delay(ms: number) {
+  if (ms <= 0) {
+    return;
+  }
+
+  return new Promise<void>((res) => setTimeout(res, ms));
+}

package/packages/framework/esm-utils/src/shallowEqual.ts

@@ -0,0 +1,46 @@
+/** @module @category Utility */
+
+/**
+ * Checks whether two objects are equal, using a shallow comparison, similar to React.
+ *
+ * In essence, shallowEquals ensures two objects have the same own properties and that the values
+ * of these are equal (===) to each other.
+ *
+ * @param a The first value to compare
+ * @param b The second value to compare
+ * @returns true if the objects are shallowly equal to each other
+ */
+export function shallowEqual(a: unknown, b: unknown) {
+  if (a === b || Object.is(a, b)) {
+    return true;
+  }
+
+  if (Array.isArray(a)) {
+    if (!Array.isArray(b)) {
+      return false;
+    }
+
+    if (a.length !== b.length) {
+      return false;
+    }
+
+    for (let i = 0; i < a.length; i++) {
+      if (a[i] !== b[i]) {
+        return false;
+      }
+    }
+
+    return true;
+  } else if (Array.isArray(b)) {
+    return false;
+  }
+
+  if (typeof a !== 'object' || a === null || typeof b !== 'object' || b === null) {
+    return false;
+  }
+
+  const objAKeys = Object.getOwnPropertyNames(a);
+  const objBKeys = Object.getOwnPropertyNames(b);
+
+  return objAKeys.length === objBKeys.length && objAKeys.every((key) => a[key] === b[key]);
+}

package/packages/framework/esm-utils/src/storage.ts

@@ -0,0 +1,18 @@
+/** @module @category Utility */
+
+/**
+ * Simple utility function to determine if an object implementing the WebStorage API
+ * is actually available. Useful for testing the availability of `localStorage` or
+ * `sessionStorage`.
+ *
+ * @param storage The WebStorage API object to check. Defaults to `localStorage`.
+ * @returns True if the WebStorage API object is able to be accessed, false otherwise
+ */
+export function canAccessStorage(storage: Storage = window.localStorage) {
+  try {
+    storage.getItem('test');
+    return true;
+  } catch {
+    return false;
+  }
+}

package/packages/framework/esm-utils/src/test-helpers.ts

@@ -0,0 +1,36 @@
+/** @module @category Utility */
+
+/**
+ * Given a config schema, this returns an object like is returned by `useConfig`
+ * with all default values.
+ *
+ * This should be used in tests and not in production code.
+ *
+ * If all you need is the default values in your tests, these are returned by
+ * default from the `useConfig`/`getConfig` mock. This function is useful if you
+ * need to override some of the default values.
+ */
+export function getDefaultsFromConfigSchema<T = Record<string, any>>(
+  schema: Record<string | number | symbol, unknown>,
+): T {
+  let tmp = {};
+  for (let k of Object.keys(schema)) {
+    if (
+      isOrdinaryObject(schema[k]) &&
+      (schema[k] as Record<string | number | symbol, unknown>).hasOwnProperty('_default')
+    ) {
+      tmp[k] = (schema[k] as Record<string | number | symbol, unknown>)._default;
+    } else if (k.startsWith('_')) {
+      continue;
+    } else if (isOrdinaryObject(schema[k])) {
+      tmp[k] = getDefaultsFromConfigSchema(schema[k] as Record<string | number | symbol, unknown>);
+    } else {
+      tmp[k] = schema[k];
+    }
+  }
+  return tmp as T;
+}
+
+function isOrdinaryObject(x: any): x is Record<string | number | symbol, unknown> {
+  return !!x && x.constructor === Object;
+}

package/packages/framework/esm-utils/src/version.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it } from 'vitest';
+import { isVersionSatisfied } from './version';
+
+describe('Version utilities', () => {
+  it('Is satisfied if exactly equals', () => {
+    const result = isVersionSatisfied('1.2.3', '1.2.3');
+    expect(result).toBe(true);
+  });
+
+  it('Is satisfied if caret and minor change', () => {
+    const result = isVersionSatisfied('^1.2.3', '1.3.0');
+    expect(result).toBe(true);
+  });
+
+  it('Is not satisfied if exact and minor change', () => {
+    const result = isVersionSatisfied('1.2.3', '1.3.0');
+    expect(result).toBe(false);
+  });
+
+  it('Is not satisfied if caret and major change', () => {
+    const result = isVersionSatisfied('^1.2.3', '2.0.0');
+    expect(result).toBe(false);
+  });
+
+  it('Is satisfied if caret and minor change with prerelease', () => {
+    const result = isVersionSatisfied('^1.2.3', '1.3.0-alpha.1');
+    expect(result).toBe(true);
+  });
+
+  it('Is not satisfied if version equals same prerelease', () => {
+    const result = isVersionSatisfied('^3.1.10', '3.1.10-pre.284');
+    expect(result).toBe(false);
+  });
+
+  it('Is satisfied if version equals higher with build number', () => {
+    const result = isVersionSatisfied('^2.24.0', '2.30.0.7e24fb');
+    expect(result).toBe(true);
+  });
+
+  it('Is satisfied if version equals higher with build number and pre', () => {
+    const result = isVersionSatisfied('^2.24.0', '2.30.0.7e24fb-pre.3');
+    expect(result).toBe(true);
+  });
+
+  it('Is not satisfied if version equals same with build number and pre', () => {
+    const result = isVersionSatisfied('^2.24.0', '2.24.0.7e24fb-pre.3');
+    expect(result).toBe(false);
+  });
+
+  it('Is satisfied if version equals same with only build number', () => {
+    const result = isVersionSatisfied('^2.24.0', '2.24.0.7e24fb');
+    expect(result).toBe(true);
+  });
+
+  it('Is satisfied with major version caret specifier and pre', () => {
+    const result = isVersionSatisfied('^3', '3.1.14-pre.3');
+    expect(result).toBe(true);
+  });
+
+  it('Is satisfied with major version caret specifier and pre and a build number', () => {
+    const result = isVersionSatisfied('^3', '3.1.14.7e24fb-pre.3');
+    expect(result).toBe(true);
+  });
+
+  it('Is satisfied with major version caret specifier and a build number', () => {
+    const result = isVersionSatisfied('^3', '3.1.14.7e24fb');
+    expect(result).toBe(true);
+  });
+});

package/packages/framework/esm-utils/src/version.ts

@@ -0,0 +1,28 @@
+/** @module @category Utility */
+import * as semver from 'semver';
+
+function normalizeOnlyVersion(version: string) {
+  const [major, minor, patch] = version.split('.');
+  return `${major}.${minor}.${patch}`;
+}
+
+function normalizeFullVersion(version: string) {
+  const idx = version.indexOf('-');
+  const prerelease = idx >= 0;
+
+  if (prerelease) {
+    const ver = normalizeOnlyVersion(version.slice(0, idx));
+    const pre = version.slice(idx + 1);
+    return `${ver}-${pre}`;
+  }
+
+  return normalizeOnlyVersion(version);
+}
+
+export function isVersionSatisfied(requiredVersion: string, installedVersion: string) {
+  const version = normalizeFullVersion(installedVersion);
+
+  return semver.satisfies(version, requiredVersion, {
+    includePrerelease: true,
+  } as semver.Options);
+}

package/packages/framework/esm-utils/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-utils/tsconfig.json

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

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

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

package/packages/framework/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig.json",
+  "compilerOptions": {
+    "esModuleInterop": true,
+    "module": "ESNext",
+    "target": "es2020",
+    "allowSyntheticDefaultImports": true,
+    "jsx": "react",
+    "strictNullChecks": true,
+    "moduleResolution": "node",
+    "declaration": true,
+    "lib": ["dom", "es2022"],
+    "skipLibCheck": true
+  }
+}

package/packages/shell/esm-app-shell/dependencies.json

@@ -0,0 +1,14 @@
+[
+  "@carbon/react",
+  "i18next",
+  "dayjs",
+  "react",
+  "react-dom",
+  "react-router-dom",
+  "react-i18next",
+  "@openmrs/esm-framework",
+  "@openmrs/esm-framework/src/internal",
+  "rxjs",
+  "single-spa",
+  "swr"
+]

package/packages/shell/esm-app-shell/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@openmrs/esm-app-shell",
+  "version": "8.0.0",
+  "license": "MPL-2.0",
+  "main": "dist/openmrs.js",
+  "scripts": {
+    "start": "yarn run watch",
+    "test": "jest --passWithNoTests --color",
+    "watch": "cross-env OMRS_CLEAN_BEFORE_BUILD=\"true\" NODE_ENV=\"development\" OMRS_OFFLINE=\"disable\" webpack serve --mode development",
+    "watch:ref": "cross-env OMRS_ESM_IMPORTMAP_URL=\"https://dev3.openmrs.org/openmrs/spa/importmap.json\" OMRS_OFFLINE=\"disable\" OMRS_CLEAN_BEFORE_BUILD=\"true\" NODE_ENV=\"development\" webpack serve --mode development",
+    "build:production": "cross-env OMRS_ESM_IMPORTMAP_URL=\"https://dev3.openmrs.org/openmrs/spa/importmap.json\" OMRS_OFFLINE=\"enable\" OMRS_CLEAN_BEFORE_BUILD=\"true\" NODE_ENV=\"production\" webpack --mode production",
+    "build:development": "cross-env OMRS_OFFLINE=\"enable\" OMRS_CLEAN_BEFORE_BUILD=\"true\" NODE_ENV=\"development\" webpack --mode development",
+    "build": "yarn run build:production && yarn run build:development",
+    "analyze": "webpack --mode=production --env analyze=true",
+    "lint": "eslint src --ext ts,tsx"
+  },
+  "keywords": [
+    "openmrs",
+    "microfrontends"
+  ],
+  "browserslist": [
+    "extends browserslist-config-openmrs"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/openmrs/openmrs-esm-core.git"
+  },
+  "bugs": {
+    "url": "https://github.com/openmrs/openmrs-esm-core/issues"
+  },
+  "homepage": "https://github.com/openmrs/openmrs-esm-core#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@carbon/react": "^1.92.1",
+    "@internationalized/date": "^3.8.0",
+    "@openmrs/esm-framework": "workspace:*",
+    "@openmrs/esm-styleguide": "workspace:*",
+    "dayjs": "^1.11.13",
+    "dexie": "^3.0.3",
+    "html-webpack-plugin": "^5.5.0",
+    "i18next": "^25.5.3",
+    "i18next-browser-languagedetector": "^8.2.0",
+    "import-map-overrides": "^3.0.0",
+    "lodash-es": "4.17.21",
+    "mini-css-extract-plugin": "^2.9.1",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "react-i18next": "^16.0.0",
+    "react-router-dom": "^6.3.0",
+    "rxjs": "^6.5.3",
+    "semver": "^7.3.4",
+    "single-spa": "^6.0.3",
+    "swc-loader": "^0.2.6",
+    "swr": "2.2.5",
+    "webpack": "^5.99.9",
+    "webpack-pwa-manifest": "^4.3.0",
+    "workbox-core": "^6.1.5",
+    "workbox-routing": "^6.1.5",
+    "workbox-strategies": "^6.1.5",
+    "workbox-webpack-plugin": "^6.1.5",
+    "workbox-window": "^6.1.5"
+  },
+  "devDependencies": {
+    "cross-env": "^7.0.3"
+  }
+}

package/packages/shell/esm-app-shell/src/assets/logo.svg

@@ -0,0 +1,30 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   version="1.1"
+   height="56"
+   width="56"
+   fill="#231f20"
+   font-family="'Avenir 55 Roman'"
+   id="svg2">
+  <path
+     d="M 15.713,15.789 C 18.92,12.583 23.35,10.6 28.243,10.6 c 4.882,0 9.301,1.974 12.504,5.165 L 40.76,3.965 C 37.01,2.034 32.752,0.942 28.243,0.942 c -4.511,0 -8.791,1.229 -12.544,3.162 z"
+     fill="#f26522"
+     id="path4" />
+  <path
+     d="m 40.76,40.829 c -3.205,3.206 -7.634,5.188 -12.528,5.188 -4.879,0 -9.3,-1.973 -12.505,-5.164 l -0.014,11.799 c 3.754,1.932 8.008,3.023 12.519,3.023 4.511,0 8.768,-1.091 12.519,-3.024 z"
+     fill="#eea616"
+     id="path6" />
+  <path
+     d="m 15.738,40.844 c -3.206,-3.206 -5.19,-7.634 -5.19,-12.528 0,-4.88 1.974,-9.3 5.165,-12.506 l -11.8,-0.012 c -1.931,3.752 -3.022,8.007 -3.022,12.518 0,4.512 1.091,8.768 3.024,12.52 z"
+     fill="#5b57a6"
+     id="path8" />
+  <path
+     d="m 40.753,15.764 c 3.207,3.205 5.19,7.636 5.19,12.53 0,4.881 -1.974,9.3 -5.166,12.503 l 11.801,0.014 C 54.51,37.06 55.6,32.803 55.6,28.294 c 0,-4.512 -1.09,-8.769 -3.024,-12.522 z"
+     fill="#009384"
+     id="path10" />
+</svg>

package/packages/shell/esm-app-shell/src/core-config.ts

@@ -0,0 +1,38 @@
+import { defineConfigSchema, Type, getConfigStore } from '@openmrs/esm-framework';
+import { registerModuleLoad, featureFlagsStore } from '@openmrs/esm-framework/src/internal';
+import { appName } from './ui';
+
+/**
+ * Sets up the app shell's configuration.
+ */
+export function setupCoreConfig() {
+  defineConfigSchema(appName, {
+    'Enabled feature flags': {
+      _description: 'The feature flags that will be enabled',
+      _type: Type.Array,
+      _default: [],
+      _elements: {
+        _type: Type.String,
+      },
+    },
+  });
+  registerModuleLoad(appName);
+
+  // process feature flags
+  getConfigStore(appName).subscribe(({ config }) => {
+    const flagsToEnable = new Set((config?.['Enabled feature flags'] as Array<string>) || []);
+    if (flagsToEnable.size) {
+      const newFlags = { ...featureFlagsStore.getState().flags };
+      for (const flag of flagsToEnable) {
+        // validate the flag exists
+        if (!newFlags[flag]) {
+          console.error(`Feature flag "${flag}" does not exist. Please define the flag first.`);
+        } else {
+          newFlags[flag] = { ...newFlags[flag], enabled: true };
+        }
+      }
+
+      featureFlagsStore.setState({ flags: newFlags });
+    }
+  });
+}

package/packages/shell/esm-app-shell/src/events.ts

@@ -0,0 +1,16 @@
+import {
+  cleanupObsoleteFeatureFlags,
+  getCurrentUser,
+  subscribeOpenmrsEvent,
+} from '@openmrs/esm-framework/src/internal';
+import { setupOptionalDependencies } from './optionaldeps';
+
+subscribeOpenmrsEvent('started', () => cleanupObsoleteFeatureFlags());
+subscribeOpenmrsEvent('started', () => {
+  const subscription = getCurrentUser().subscribe((session) => {
+    if (session.authenticated) {
+      subscription?.unsubscribe();
+      setupOptionalDependencies();
+    }
+  });
+});