@koech/esm-core 8.0.0

package/packages/framework/esm-globals/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@openmrs/esm-globals",
+  "version": "8.0.0",
+  "license": "MPL-2.0",
+  "type": "module",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./dist/index.js"
+    },
+    "./src/public": {
+      "types": "./src/public.ts",
+      "default": "./dist/public.js"
+    }
+  },
+  "source": true,
+  "scripts": {
+    "build": "rimraf dist && concurrently \"swc --strip-leading-paths src -d dist\" \"tsc --project tsconfig.build.json\"",
+    "build:development": "rimraf dist && concurrently \"swc --strip-leading-paths src -d dist\" \"tsc --project tsconfig.build.json\"",
+    "typescript": "tsc --project tsconfig.build.json",
+    "lint": "eslint src --ext ts,tsx"
+  },
+  "keywords": [
+    "openmrs",
+    "framework",
+    "frontend",
+    "ui",
+    "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": {
+    "@types/fhir": "0.0.31"
+  },
+  "peerDependencies": {
+    "single-spa": "6.x"
+  },
+  "devDependencies": {
+    "@swc/cli": "^0.7.7",
+    "@swc/core": "^1.11.29",
+    "concurrently": "^9.1.2",
+    "rimraf": "^6.0.1",
+    "single-spa": "^6.0.3"
+  }
+}

package/packages/framework/esm-globals/src/events.ts

@@ -0,0 +1,134 @@
+export interface ConnectivityChangedEvent {
+  online: boolean;
+}
+
+const connectivityChangedEventName = 'openmrs:connectivity-changed';
+
+/** @internal */
+export function dispatchConnectivityChanged(online: boolean) {
+  window.dispatchEvent(new CustomEvent(connectivityChangedEventName, { detail: { online } }));
+}
+
+/** @category Offline */
+export function subscribeConnectivityChanged(cb: (ev: ConnectivityChangedEvent) => void) {
+  if (!window.offlineEnabled) {
+    return () => {};
+  }
+
+  const handler = (ev: CustomEvent) => cb(ev.detail);
+  window.addEventListener(connectivityChangedEventName, handler);
+  return () => window.removeEventListener(connectivityChangedEventName, handler);
+}
+
+/** @category Offline */
+export function subscribeConnectivity(cb: (ev: ConnectivityChangedEvent) => void) {
+  cb({ online: window.offlineEnabled ? navigator.onLine : true });
+  return subscribeConnectivityChanged(cb);
+}
+
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface PrecacheStaticDependenciesEvent {}
+
+const precacheStaticDependenciesEventName = 'openmrs:precache-static-dependencies';
+
+export function dispatchPrecacheStaticDependencies(data: PrecacheStaticDependenciesEvent = {}) {
+  window.dispatchEvent(new CustomEvent(precacheStaticDependenciesEventName, { detail: data }));
+}
+
+/** @category Offline */
+export function subscribePrecacheStaticDependencies(cb: (data: PrecacheStaticDependenciesEvent) => void) {
+  const handler = (ev: CustomEvent) => cb(ev.detail);
+  window.addEventListener(precacheStaticDependenciesEventName, handler);
+  return () => window.removeEventListener(precacheStaticDependenciesEventName, handler);
+}
+
+/** @category UI */
+export interface ShowNotificationEvent {
+  description: any;
+  kind?: 'error' | 'info' | 'info-square' | 'success' | 'warning' | 'warning-alt';
+  title?: string;
+  action?: any;
+  millis?: number;
+}
+
+export interface ShowActionableNotificationEvent {
+  subtitle: any;
+  kind?: 'error' | 'info' | 'info-square' | 'success' | 'warning' | 'warning-alt';
+  title?: string;
+  actionButtonLabel: string | any;
+  onActionButtonClick: () => void;
+  progressActionLabel?: string;
+}
+
+/** @category UI */
+export interface ShowToastEvent {
+  description: any;
+  kind?: 'error' | 'info' | 'info-square' | 'success' | 'warning' | 'warning-alt';
+  title?: string;
+  actionButtonLabel?: string | any;
+  onActionButtonClick?: () => void;
+}
+
+/** @category UI */
+export interface ShowSnackbarEvent {
+  subtitle?: any;
+  kind?: 'error' | 'info' | 'info-square' | 'success' | 'warning' | 'warning-alt';
+  title: string;
+  actionButtonLabel?: string | any;
+  onActionButtonClick?: () => void;
+  progressActionLabel?: string;
+  isLowContrast?: boolean;
+  timeoutInMs?: number;
+}
+
+const notificationShownName = 'openmrs:notification-shown';
+const actionableNotificationShownName = 'openmrs:actionable-notification-shown';
+const toastShownName = 'openmrs:toast-shown';
+const snackbarShownName = 'openmrs:snack-bar-shown';
+
+export function dispatchNotificationShown(data: ShowNotificationEvent) {
+  window.dispatchEvent(new CustomEvent(notificationShownName, { detail: data }));
+}
+
+/** @internal */
+export function dispatchActionableNotificationShown(data: ShowActionableNotificationEvent) {
+  window.dispatchEvent(new CustomEvent(actionableNotificationShownName, { detail: data }));
+}
+
+/** @internal */
+export function dispatchSnackbarShown(data: ShowSnackbarEvent) {
+  window.dispatchEvent(new CustomEvent(snackbarShownName, { detail: data }));
+}
+
+/** @internal */
+export function dispatchToastShown(data: ShowToastEvent) {
+  window.dispatchEvent(new CustomEvent(toastShownName, { detail: data }));
+}
+
+/** @category UI */
+export function subscribeNotificationShown(cb: (data: ShowNotificationEvent) => void) {
+  const handler = (ev: CustomEvent) => cb(ev.detail);
+  window.addEventListener(notificationShownName, handler);
+  return () => window.removeEventListener(notificationShownName, handler);
+}
+
+/** @category UI */
+export function subscribeActionableNotificationShown(cb: (data: ShowActionableNotificationEvent) => void) {
+  const handler = (ev: CustomEvent) => cb(ev.detail);
+  window.addEventListener(actionableNotificationShownName, handler);
+  return () => window.removeEventListener(actionableNotificationShownName, handler);
+}
+
+/** @category UI */
+export function subscribeToastShown(cb: (data: ShowToastEvent) => void) {
+  const handler = (ev: CustomEvent) => cb(ev.detail);
+  window.addEventListener(toastShownName, handler);
+  return () => window.removeEventListener(toastShownName, handler);
+}
+
+/** @category UI */
+export function subscribeSnackbarShown(cb: (data: ShowSnackbarEvent) => void) {
+  const handler = (ev: CustomEvent) => cb(ev.detail);
+  window.addEventListener(snackbarShownName, handler);
+  return () => window.removeEventListener(snackbarShownName, handler);
+}

package/packages/framework/esm-globals/src/index.ts

@@ -0,0 +1,2 @@
+export * from './events';
+export * from './types';

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

@@ -0,0 +1,16 @@
+export {
+  type ConnectivityChangedEvent,
+  type PrecacheStaticDependenciesEvent,
+  type ShowNotificationEvent,
+  type ShowActionableNotificationEvent,
+  type ShowToastEvent,
+  type ShowSnackbarEvent,
+  subscribeConnectivity,
+  subscribeConnectivityChanged,
+  subscribePrecacheStaticDependencies,
+  subscribeNotificationShown,
+  subscribeActionableNotificationShown,
+  subscribeToastShown,
+  subscribeSnackbarShown,
+} from './events';
+export * from './types';

package/packages/framework/esm-globals/src/types.ts

@@ -0,0 +1,415 @@
+import type { i18n } from 'i18next';
+
+declare global {
+  const __webpack_share_scopes__: Record<
+    string,
+    Record<string, { loaded?: 1; get: () => Promise<unknown>; from: string; eager: boolean }>
+  >;
+
+  // eslint-disable-next-line no-var
+  var __webpack_init_sharing__: (scope: string) => Promise<void>;
+
+  interface Window {
+    /**
+     * Easily copies a text from an element.
+     * @param source The source element carrying the text.
+     */
+    copyText(source: HTMLElement): void;
+    /**
+     * Gets the OpenMRS SPA base path with a trailing slash.
+     */
+    getOpenmrsSpaBase(): string;
+    /**
+     * Starts the OpenMRS SPA application.
+     * @param config The configuration to use for running.
+     */
+    initializeSpa(config: SpaConfig): void;
+    /**
+     * Indicates whether offline mode is enabled in this install or not.
+     * This is used to determine whether offline functionality is present or not.
+     */
+    offlineEnabled: boolean;
+    /**
+     * Gets the API base path, e.g. /openmrs
+     */
+    openmrsBase: string;
+    /**
+     * Gets the SPA base path, e.g. /openmrs/spa
+     */
+    spaBase: string;
+    /**
+     * Set by the app shell. Indicates whether the app shell is running in production, development, or test mode.
+     */
+    spaEnv: SpaEnvironment;
+    /**
+     * The build number of the app shell. Set when the app shell is built by webpack.
+     */
+    spaVersion: string;
+    /**
+     * Gets a set of options from the import-map-overrides package.
+     */
+    importMapOverrides: {
+      addOverride(moduleName: string, url: string): void;
+      enableOverride(moduleName: string): void;
+      getCurrentPageMap(): Promise<ImportMap>;
+      getDefaultMap(): Promise<ImportMap>;
+      getNextPageMap(): Promise<ImportMap>;
+      addOverride(moduleName: string, url: string): void;
+      getOverrideMap(includeDisabled?: boolean): ImportMap;
+      getDisabledOverrides(): Array<string>;
+      isDisabled(moduleName: string): boolean;
+      removeOverride(moduleName: string): void;
+      resetOverrides(): void;
+    };
+    /**
+     * Gets the installed modules, which are tuples consisting of the module's name and exports.
+     */
+    installedModules: Array<[string, OpenmrsAppRoutes]>;
+    /**
+     * The i18next instance for the app.
+     */
+    i18next: i18n;
+  }
+}
+
+export type SpaEnvironment = 'production' | 'development' | 'test';
+
+export interface ImportMap {
+  imports: Record<string, string>;
+}
+
+/**
+ * The configuration passed to the app shell initialization function
+ */
+export interface SpaConfig {
+  /**
+   * The base path or URL for the OpenMRS API / endpoints.
+   */
+  apiUrl: string;
+  /**
+   * The base path for the SPA root path.
+   */
+  spaPath: string;
+  /**
+   * The environment to use.
+   * @default production
+   */
+  env?: SpaEnvironment;
+  /**
+   * URLs of configurations to load in the system.
+   */
+  configUrls?: Array<string>;
+  /**
+   * Defines if offline should be supported by installing a service worker.
+   * @default true
+   */
+  offline?: boolean;
+}
+
+/** @internal */
+export type RouteDefinition = RegExp | string | boolean;
+
+/** @internal */
+type AppComponent = {
+  appName: string;
+};
+
+/**
+ * A definition of a page extracted from an app's routes.json
+ */
+export type PageDefinition = {
+  /**
+   * The name of the component exported by this frontend module.
+   */
+  component: string;
+  /**
+   * If supplied, the page will only be rendered when this feature flag is enabled.
+   */
+  featureFlag?: string;
+  /**
+   * Determines whether the component renders while the browser is connected to the internet. If false, this page will never render while online.
+   */
+  online?: boolean;
+  /**
+   * Determines whether the component renders while the browser is not connected to the internet. If false, this page will never render while offline.
+   */
+  offline?: boolean;
+  /**
+   * If supplied, the page will be rendered within the DOM element with the specified ID. Defaults to "omrs-apps-container" if not supplied.
+   */
+  containerDomId?: string;
+} & (
+  | {
+      /**
+       * Either a string or a boolean.
+       *
+       * If a string value, this is used to indicate that this page should be rendered. For example, \"name\" will match when the current page is ${window.spaBase}/name.
+       *
+       * If a boolean, this either indicates that the component should always be rendered or should never be rendered.
+       */
+      route: string | boolean;
+      /**
+       * A regular expression used to match against the current route to determine whether this page should be rendered. Note that ${window.spaBase} will be removed before attempting to match, so setting this to \"^name.+\" will match any route that starts with ${window.spaBase}/name.
+       */
+      routeRegex?: never;
+    }
+  | {
+      /**
+       * Either a string or a boolean.
+       *
+       * If a string value, this is used to indicate that this page should be rendered. For example, \"name\" will match when the current page is ${window.spaBase}/name.
+       *
+       * If a boolean, this either indicates that the component should always be rendered or should never be rendered.
+       */
+      route?: never;
+      /**
+       * A regular expression used to match against the current route to determine whether this page should be rendered. Note that ${window.spaBase} will be removed before attempting to match, so setting this to \"^name.+\" will match any route that starts with ${window.spaBase}/name.
+       */
+      routeRegex: string;
+    }
+);
+
+/**
+ * @internal
+ * A definition of a page after the app has been registered.
+ */
+export type RegisteredPageDefinition = PageDefinition & AppComponent;
+
+/**
+ * A definition of an extension as extracted from an app's routes.json
+ */
+export type ExtensionDefinition = {
+  /**
+   * The name of this extension. This is used to refer to the extension in configuration.
+   */
+  name: string;
+  /**
+   * If supplied, the slot that this extension is rendered into by default.
+   */
+  slot?: string;
+  /**
+   * If supplied, the slots that this extension is rendered into by default.
+   */
+  slots?: Array<string>;
+  /**
+   * Determines whether the component renders while the browser is connected to the internet. If false, this page will never render while online.
+   */
+  online?: boolean;
+  /**
+   * Determines whether the component renders while the browser is not connected to the internet. If false, this page will never render while offline.
+   */
+  offline?: boolean;
+  /**
+   * Determines the order in which this component renders in its default extension slot. Note that this can be overridden by configuration.
+   */
+  order?: number;
+  /**
+   * The user must have ANY of these privileges to see this extension.
+   */
+  privileges?: string | Array<string>;
+  /**
+   * The expression that determines whether the extension is displayed.
+   */
+  displayExpression?: string;
+  /**
+   * If supplied, the extension will only be rendered when this feature flag is enabled.
+   */
+  featureFlag?: string;
+  /**
+   * Meta describes any properties that are passed down to the extension when it is loaded
+   */
+  meta?: {
+    [k: string]: unknown;
+  };
+  /**
+   * The name of the component exported by this frontend module.
+   */
+  component: string;
+};
+
+/**
+ * A definition of a modal as extracted from an app's routes.json
+ */
+export type ModalDefinition = {
+  /**
+   * The name of this modal. This is used to launch the modal.
+   */
+  name: string;
+  /**
+   * The name of the component exported by this frontend module.
+   */
+  component: string;
+};
+
+/* The possible states a workspace window can be opened in. */
+export type WorkspaceWindowState = 'maximized' | 'hidden' | 'normal';
+
+/**
+ * A definition of a workspace as extracted from an app's routes.json
+ */
+export type WorkspaceDefinition = {
+  /**
+   * The name of this workspace. This is used to launch the workspace.
+   */
+  name: string;
+  /**
+   * The title of the workspace. This will be looked up as a key in the translations of the module
+   * defining the workspace.
+   */
+  title: string;
+  /**
+   * The type of the workspace. Only one of each "type" of workspace is allowed to be open at a
+   * time. The default is "form". If the right sidebar is in use, then the type determines which
+   * right sidebar icon corresponds to the workspace.
+   */
+  type: string;
+  canHide?: boolean;
+  canMaximize?: boolean;
+  /**
+   * Controls the width of the workspace. The default is "narrow" and this should only be
+   * changed to "wider" if the workspace itself has internal navigation, like the form editor.
+   * The width "extra-wide" is for workspaces that contain their own sidebar.
+   */
+  width?: 'narrow' | 'wider' | 'extra-wide';
+  /**
+   * Launches the workspace in the preferred size, it defaults to the 'narrow' width
+   */
+  preferredWindowSize?: WorkspaceWindowState;
+
+  /**
+   * Workspaces can open either independently or as part of a "workspace group". A
+   * "workspace group" groups related workspaces together, so that only one is visible
+   * at a time. For example,
+   *
+   * @example
+   *
+   * {
+   *  name: 'order-basket',
+   *  type: 'order',
+   *  groups: ['ward-patient']
+   * }
+   *
+   * This means that the 'order-basket' workspace can be opened independently, or only
+   * in the 'ward-patient'.
+   * If a workspace group is already open and a new workspace is launched, and the
+   * groups in the newly launched workspace do not include the currently open group’s
+   * name, the entire workspace group will close, and the new workspace will launch independently.
+   *
+   */
+  groups: Array<string>;
+  /**
+   * The name of the component exported by this frontend module.
+   */
+  component: string;
+};
+
+export interface WorkspaceGroupDefinition {
+  /**
+   * Name of the workspace group. This is used to launch the workspace group
+   */
+  name: string;
+  /**
+   * List of workspace names which are part of the workspace group.
+   */
+  members?: Array<string>;
+}
+
+export interface WorkspaceGroupDefinition2 {
+  name: string;
+  closeable?: boolean;
+  overlay?: boolean;
+
+  /**
+   * In app-wide persistence mode, a workspace group renders its
+   * action menu without a close button. This is for
+   * workspace groups that are meant to be opened for the entire duration of the app
+   *
+   * In closable persistence mode, a workspace group renders its
+   * action menu with a close button. User may explicitly close the group, along
+   * with any opened windows / workspaces.
+   */
+  persistence?: 'app-wide' | 'closable';
+}
+
+export interface WorkspaceWindowDefinition2 {
+  name: string;
+  icon?: string;
+  canMaximize?: boolean;
+  group: string;
+  order?: number;
+  width?: 'narrow' | 'wider' | 'extra-wide';
+}
+
+export interface WorkspaceDefinition2 {
+  name: string;
+  component: string;
+  window: string;
+}
+
+/**
+ * A definition of a feature flag extracted from the routes.json
+ */
+export interface FeatureFlagDefinition {
+  /** A code-friendly name for the flag, which will be used to reference it in code */
+  flagName: string;
+  /** A human-friendly name which will be displayed in the Implementer Tools */
+  label: string;
+  /** An explanation of what the flag does, which will be displayed in the Implementer Tools */
+  description: string;
+}
+
+/** This interface describes the format of the routes provided by an app */
+export interface OpenmrsAppRoutes {
+  /** The version of this frontend module. */
+  version?: string;
+  /** A list of backend modules necessary for this frontend module and the corresponding required versions. */
+  backendDependencies?: Record<string, string>;
+  /** A list of backend modules that may enable optional functionality in this frontend module if available and the corresponding required versions. */
+  optionalBackendDependencies?: {
+    /** The name of the backend dependency and either the required version or an object describing the required version */
+    [key: string]:
+      | string
+      | {
+          /** The minimum version of this optional dependency that must be present. */
+          version: string;
+          /** The feature flag to enable if this backend dependency is present */
+          feature?: FeatureFlagDefinition;
+        };
+  };
+  /** An array of all pages supported by this frontend module. Pages are automatically mounted based on a route. */
+  pages?: Array<PageDefinition>;
+  /**  An array of all extensions supported by this frontend module. Extensions can be mounted in extension slots, either via declarations in this file or configuration. */
+  extensions?: Array<ExtensionDefinition>;
+  /** An array of all feature flags for any beta-stage features this module provides. */
+  featureFlags?: Array<FeatureFlagDefinition>;
+  /** An array of all modals supported by this frontend module. Modals can be launched by name. */
+  modals?: Array<ModalDefinition>;
+  /** An array of all workspaces supported by this frontend module. Workspaces can be launched by name. */
+  workspaces?: Array<WorkspaceDefinition>;
+  /** An array of all workspace groups supported by this frontend module. */
+  workspaceGroups?: Array<WorkspaceGroupDefinition>;
+
+  /** An array of all workspace groups (v2) supported by this frontend module. */
+  workspaceGroups2?: Array<WorkspaceGroupDefinition2>;
+
+  /** An array of all workspace windows (v2) supported by this frontend module. */
+  workspaceWindows2?: Array<WorkspaceWindowDefinition2>;
+
+  /** An array of all workspaces (v2) supported by this frontend module. */
+  workspaces2?: Array<WorkspaceDefinition2>;
+}
+
+/**
+ * This interfaces describes the format of the overall routes.json loaded by the app shell.
+ * Basically, this is the same as the app routes, with each routes definition keyed by the app's name
+ */
+export type OpenmrsRoutes = Record<string, OpenmrsAppRoutes>;
+
+export interface ResourceLoader<T = any> {
+  (): Promise<T>;
+}
+
+/*
+ * Supported values for FHIR HumanName.use as defined by https://hl7.org/fhir/R4/valueset-name-use.html
+ */
+export type NameUse = 'usual' | 'official' | 'temp' | 'nickname' | 'anonymous' | 'old' | 'maiden';

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

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

package/packages/framework/esm-navigation/.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-navigation/README.md

@@ -0,0 +1 @@
+# openmrs-esm-navigation