@openmrs/esm-styleguide 5.7.2-pre.2101 → 5.7.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openmrs/esm-styleguide",
-  "version": "5.7.2-pre.2101",
+  "version": "5.7.2",
   "license": "MPL-2.0",
   "description": "The styleguide for OpenMRS SPA",
   "browser": "dist/openmrs-esm-styleguide.js",
@@ -64,12 +64,12 @@
     "rxjs": "6.x"
   },
   "devDependencies": {
-    "@openmrs/esm-error-handling": "5.7.2-pre.2101",
-    "@openmrs/esm-extensions": "5.7.2-pre.2101",
-    "@openmrs/esm-navigation": "5.7.2-pre.2101",
-    "@openmrs/esm-react-utils": "5.7.2-pre.2101",
-    "@openmrs/esm-state": "5.7.2-pre.2101",
-    "@openmrs/esm-translations": "5.7.2-pre.2101",
+    "@openmrs/esm-error-handling": "5.7.2",
+    "@openmrs/esm-extensions": "5.7.2",
+    "@openmrs/esm-navigation": "5.7.2",
+    "@openmrs/esm-react-utils": "5.7.2",
+    "@openmrs/esm-state": "5.7.2",
+    "@openmrs/esm-translations": "5.7.2",
     "@types/geopattern": "^1.2.9",
     "autoprefixer": "^9.8.8",
     "css-minimizer-webpack-plugin": "^1.2.0",
@@ -82,6 +82,5 @@
     "rxjs": "^6.5.3",
     "svgo-loader": "^4.0.0",
     "webpack": "^5.88.0"
-  },
-  "stableVersion": "5.7.1"
+  }
 }

package/src/icons/svgs/sticky-note-add.svg

@@ -1,4 +1,4 @@
 <svg xmlns="http://www.w3.org/2000/svg">
-  <path d="M11.5 1H10.5V3H8.5V4H10.5V6H11.5V4H13.5V3H11.5V1Z" />
-  <path d="M7.5 1.99982H3.5C3.23502 2.0006 2.98112 2.10621 2.79375 2.29358C2.60638 2.48094 2.50078 2.73485 2.5 2.99982V12.9998C2.50078 13.2648 2.60638 13.5187 2.79375 13.7061C2.98112 13.8934 3.23502 13.999 3.5 13.9998H9.5C9.56572 14.0017 9.63106 13.9892 9.69149 13.9633C9.75192 13.9374 9.80601 13.8987 9.85 13.8498L13.35 10.3498C13.3989 10.3058 13.4376 10.2517 13.4635 10.1913C13.4894 10.1309 13.5018 10.0655 13.5 9.99982V7.00007H12.5V8.99982H9.5C9.23502 9.0006 8.98112 9.10621 8.79375 9.29358C8.60638 9.48094 8.50078 9.73485 8.5 9.99982V12.9998H3.5V2.99982H7.5V1.99982ZM12.3 9.99982L9.5 12.7998V9.99982H12.3Z" />
+    <path d="M14.375 1.25h-1.25v2.5h-2.5V5h2.5v2.5h1.25V5h2.5V3.75h-2.5v-2.5z" />
+    <path d="M9.375 2.5h-5a1.254 1.254 0 0 0-1.25 1.25v12.5a1.254 1.254 0 0 0 1.25 1.25h7.5a.567.567 0 0 0 .438-.188l4.374-4.375a.566.566 0 0 0 .188-.437V8.75h-1.25v2.5h-3.75a1.254 1.254 0 0 0-1.25 1.25v3.75h-6.25V3.75h5V2.5zm6 10-3.5 3.5v-3.5h3.5z" />
 </svg>

package/src/modals/index.tsx

@@ -1,8 +1,9 @@
 /** @module @category UI */
 import { mountRootParcel, type Parcel } from 'single-spa';
 import { createGlobalStore } from '@openmrs/esm-state';
-import { getModalRegistration } from '@openmrs/esm-extensions';
+import { getModalRegistration } from './registry';
 import { reportError } from '@openmrs/esm-error-handling';
+export * from './registry';
 
 type ModalInstanceState = 'NEW' | 'MOUNTED' | 'TO_BE_DELETED';
 

package/src/modals/registry.ts

@@ -0,0 +1,48 @@
+import { getExtensionRegistration } from '@openmrs/esm-extensions';
+import { createGlobalStore } from '@openmrs/esm-state';
+import type { LifeCycles } from 'single-spa';
+
+/** @internal */
+export interface ModalRegistration {
+  name: string;
+  load(): Promise<{ default?: LifeCycles } & LifeCycles>;
+  moduleName: string;
+}
+
+interface ModalRegistry {
+  /** Modals indexed by name */
+  modals: Record<string, ModalRegistration>;
+}
+
+const modalRegistryStore = createGlobalStore<ModalRegistry>('modalRegistry', {
+  modals: {},
+});
+
+/** @internal */
+export function registerModal(modalRegistration: ModalRegistration) {
+  modalRegistryStore.setState((state) => {
+    state.modals[modalRegistration.name] = modalRegistration;
+    return state;
+  });
+}
+
+/** @internal */
+export function getModalRegistration(modalName: string): ModalRegistration | undefined {
+  let modalRegistration = modalRegistryStore.getState().modals[modalName];
+  if (!modalRegistration) {
+    const extensionRegistration = getExtensionRegistration(modalName);
+    if (extensionRegistration) {
+      modalRegistration = {
+        name: modalName,
+        load: extensionRegistration.load,
+        moduleName: extensionRegistration.moduleName,
+      };
+      console.warn(
+        `Modal ${modalName} was registered as an extension. This is deprecated and will be removed in the future. Please register it in the "modals" section of routes.json instead of the "extensions" section.`,
+      );
+      // Register it so the warning only appears once
+      registerModal(modalRegistration);
+    }
+  }
+  return modalRegistration;
+}

package/src/workspaces/action-menu-button/action-menu-button.component.tsx

@@ -3,8 +3,8 @@ import React from 'react';
 import classNames from 'classnames';
 import { Button, IconButton } from '@carbon/react';
 import { useLayoutType } from '@openmrs/esm-react-utils';
-import styles from './action-menu-button.module.scss';
 import { useWorkspaces } from '../workspaces';
+import styles from './action-menu-button.module.scss';
 
 interface TagsProps {
   getIcon: (props: object) => JSX.Element;

package/src/workspaces/container/workspace-container.component.tsx

@@ -7,8 +7,8 @@ import { getCoreTranslation, translateFrom } from '@openmrs/esm-translations';
 
 import { ArrowLeftIcon, ArrowRightIcon, CloseIcon } from '../../icons';
 import { WorkspaceNotification } from '../notification/workspace-notification.component';
-import ActionMenu from './action-menu.component';
 import { type OpenWorkspace, updateWorkspaceWindowState, useWorkspaces } from '../workspaces';
+import ActionMenu from './action-menu.component';
 import { WorkspaceRenderer } from './workspace-renderer.component';
 import styles from './workspace.module.scss';
 

package/src/workspaces/container/workspace-container.test.tsx

@@ -2,9 +2,8 @@
 import React from 'react';
 import { screen, render, within, renderHook, act } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
-import { registerWorkspace } from '@openmrs/esm-extensions';
 import { ComponentContext, isDesktop, useLayoutType } from '@openmrs/esm-react-utils';
-import { type DefaultWorkspaceProps, WorkspaceContainer, launchWorkspace, useWorkspaces } from '..';
+import { type DefaultWorkspaceProps, WorkspaceContainer, launchWorkspace, registerWorkspace, useWorkspaces } from '..';
 
 jest.mock('./workspace-renderer.component.tsx', () => {
   return {
@@ -17,7 +16,7 @@ jest.mock('./workspace-renderer.component.tsx', () => {
   };
 });
 
-const mockedIsDesktop = isDesktop as unknown as jest.Mock;
+const mockedIsDesktop = isDesktop as jest.Mock;
 const mockedUseLayoutType = useLayoutType as jest.Mock;
 
 window.history.pushState({}, 'Workspace Container', '/workspace-container');

package/src/workspaces/container/workspace-renderer.component.tsx

@@ -3,8 +3,8 @@ import { mountRootParcel, type ParcelConfig } from 'single-spa';
 import Parcel from 'single-spa-react/parcel';
 import { InlineLoading } from '@carbon/react';
 import { getCoreTranslation } from '@openmrs/esm-translations';
-import styles from './workspace.module.scss';
 import { type OpenWorkspace } from '../workspaces';
+import styles from './workspace.module.scss';
 
 interface WorkspaceRendererProps {
   workspace: OpenWorkspace;

package/src/workspaces/index.ts

@@ -2,4 +2,5 @@ export * from './action-menu-button/action-menu-button.component';
 export * from './container/action-menu.component';
 export * from './container/workspace-container.component';
 export * from './notification/workspace-notification.component';
+export * from './types';
 export * from './workspaces';

package/src/workspaces/notification/workspace-notification.component.tsx

@@ -4,18 +4,18 @@ import { useTranslation } from 'react-i18next';
 import { Button, ComposedModal, ModalBody, ModalFooter, ModalHeader } from '@carbon/react';
 import { navigate } from '@openmrs/esm-navigation';
 import { reportError } from '@openmrs/esm-error-handling';
-import { escapeRegExp } from 'lodash-es';
-import { type SingleSpaCustomEventDetail } from 'single-spa';
-import styles from './workspace-notification.module.scss';
 import {
-  cancelPrompt,
   canCloseWorkspaceWithoutPrompting,
+  cancelPrompt,
   changeWorkspaceContext,
   closeAllWorkspaces,
   getWorkspaceStore,
   resetWorkspaceStore,
   useWorkspaces,
 } from '../workspaces';
+import { escapeRegExp } from 'lodash-es';
+import { type SingleSpaCustomEventDetail } from 'single-spa';
+import styles from './workspace-notification.module.scss';
 
 export interface WorkspaceNotificationProps {
   contextKey: string;

package/src/workspaces/public.ts

@@ -1,10 +1,5 @@
 export * from './action-menu-button/action-menu-button.component';
 export * from './container/workspace-container.component';
+export { type DefaultWorkspaceProps, type CloseWorkspaceOptions } from './types';
 export { closeWorkspace, launchWorkspace, navigateAndLaunchWorkspace, useWorkspaces } from './workspaces';
-export {
-  type DefaultWorkspaceProps,
-  type CloseWorkspaceOptions,
-  type OpenWorkspace,
-  type WorkspacesInfo,
-  type Prompt,
-} from './workspaces';
+export { type OpenWorkspace, type WorkspaceRegistration, type WorkspacesInfo, type Prompt } from './workspaces';

package/src/workspaces/types.ts

@@ -0,0 +1,70 @@
+import { type WorkspaceWindowState } from '@openmrs/esm-globals';
+import { type ReactNode } from 'react';
+
+export interface CloseWorkspaceOptions {
+  /**
+   * Whether to close the workspace ignoring all the changes present in the workspace.
+   *
+   * If ignoreChanges is true, the user will not be prompted to save changes before closing
+   * even if the `testFcn` passed to `promptBeforeClosing` returns `true`.
+   */
+  ignoreChanges?: boolean;
+  /**
+   * If you want to take an action after the workspace is closed, you can pass your function as
+   * `onWorkspaceClose`. This function will be called only after the workspace is closed, given
+   * that the user might be shown a prompt.
+   * @returns void
+   */
+  onWorkspaceClose?: () => void;
+}
+
+/** The default parameters received by all workspaces */
+export interface DefaultWorkspaceProps {
+  /**
+   * Call this function to close the workspace. This function will prompt the user
+   * if there are any unsaved changes to workspace.
+   *
+   * You can pass `onWorkspaceClose` function to be called when the workspace is finally
+   * closed, given the user forcefully closes the workspace.
+   */
+  closeWorkspace(closeWorkspaceOptions?: CloseWorkspaceOptions): void;
+  /**
+   * Call this with a no-args function that returns true if the user should be prompted before
+   * this workspace is closed; e.g. if there is unsaved data.
+   */
+  promptBeforeClosing(testFcn: () => boolean): void;
+  /**
+   * Call this function to close the workspace after the form is saved. This function
+   * will directly close the workspace without any prompt
+   */
+  closeWorkspaceWithSavedChanges(closeWorkspaceOptions?: CloseWorkspaceOptions): void;
+  /**
+   * Use this to set the workspace title if it needs to be set dynamically.
+   *
+   * Workspace titles generally are set in the workspace declaration in the routes.json file. They can also
+   * be set by the workspace launcher by passing `workspaceTitle` in the `additionalProps`
+   * parameter of the `launchWorkspace` function. This function is useful when the workspace
+   * title needs to be set dynamically.
+   *
+   * @param title The title to set. If using titleNode, set this to a human-readable string
+   *        which will identify the workspace in notifications and other places.
+   * @param titleNode A React object to put in the workspace header in place of the title. This
+   *        is useful for displaying custom elements in the header. Note that custom header
+   *        elements can also be attached to the workspace header extension slots.
+   */
+  setTitle(title: string, titleNode?: ReactNode): void;
+}
+
+export interface WorkspaceWindowSize {
+  size: WorkspaceWindowState;
+}
+
+export interface WorkspaceWindowSizeProviderProps {
+  children?: React.ReactNode;
+}
+
+export interface WorkspaceWindowSizeContext {
+  windowSize: WorkspaceWindowSize;
+  updateWindowSize?(value: WorkspaceWindowState): any;
+  active: boolean;
+}

package/src/workspaces/workspaces.test.ts

@@ -1,5 +1,12 @@
-import { type Prompt, cancelPrompt, getWorkspaceStore, launchWorkspace, resetWorkspaceStore } from './workspaces';
-import { registerExtension, registerWorkspace } from '@openmrs/esm-extensions';
+import {
+  type Prompt,
+  cancelPrompt,
+  getWorkspaceStore,
+  launchWorkspace,
+  registerWorkspace,
+  resetWorkspaceStore,
+} from './workspaces';
+import { registerExtension } from '@openmrs/esm-extensions';
 import { clearMockExtensionRegistry } from '@openmrs/esm-framework/mock';
 
 describe('workspace system', () => {

package/src/workspaces/workspaces.ts

@@ -1,80 +1,14 @@
 /** @module @category Workspace */
-import { useMemo, type ReactNode } from 'react';
+import { type ReactNode, useMemo } from 'react';
+import { type LifeCycles } from 'single-spa';
 import _i18n from 'i18next';
-import { getWorkspaceRegistration, type WorkspaceRegistration } from '@openmrs/esm-extensions';
+import { type ExtensionRegistration, getExtensionRegistration } from '@openmrs/esm-extensions';
 import { type WorkspaceWindowState } from '@openmrs/esm-globals';
+import { useStore } from '@openmrs/esm-react-utils';
 import { navigate } from '@openmrs/esm-navigation';
 import { getGlobalStore, createGlobalStore } from '@openmrs/esm-state';
 import { getCoreTranslation, translateFrom } from '@openmrs/esm-translations';
-import { useStore } from '@openmrs/esm-react-utils';
-
-export interface CloseWorkspaceOptions {
-  /**
-   * Whether to close the workspace ignoring all the changes present in the workspace.
-   *
-   * If ignoreChanges is true, the user will not be prompted to save changes before closing
-   * even if the `testFcn` passed to `promptBeforeClosing` returns `true`.
-   */
-  ignoreChanges?: boolean;
-  /**
-   * If you want to take an action after the workspace is closed, you can pass your function as
-   * `onWorkspaceClose`. This function will be called only after the workspace is closed, given
-   * that the user might be shown a prompt.
-   * @returns void
-   */
-  onWorkspaceClose?: () => void;
-}
-
-/** The default parameters received by all workspaces */
-export interface DefaultWorkspaceProps {
-  /**
-   * Call this function to close the workspace. This function will prompt the user
-   * if there are any unsaved changes to workspace.
-   *
-   * You can pass `onWorkspaceClose` function to be called when the workspace is finally
-   * closed, given the user forcefully closes the workspace.
-   */
-  closeWorkspace(closeWorkspaceOptions?: CloseWorkspaceOptions): void;
-  /**
-   * Call this with a no-args function that returns true if the user should be prompted before
-   * this workspace is closed; e.g. if there is unsaved data.
-   */
-  promptBeforeClosing(testFcn: () => boolean): void;
-  /**
-   * Call this function to close the workspace after the form is saved. This function
-   * will directly close the workspace without any prompt
-   */
-  closeWorkspaceWithSavedChanges(closeWorkspaceOptions?: CloseWorkspaceOptions): void;
-  /**
-   * Use this to set the workspace title if it needs to be set dynamically.
-   *
-   * Workspace titles generally are set in the workspace declaration in the routes.json file. They can also
-   * be set by the workspace launcher by passing `workspaceTitle` in the `additionalProps`
-   * parameter of the `launchWorkspace` function. This function is useful when the workspace
-   * title needs to be set dynamically.
-   *
-   * @param title The title to set. If using titleNode, set this to a human-readable string
-   *        which will identify the workspace in notifications and other places.
-   * @param titleNode A React object to put in the workspace header in place of the title. This
-   *        is useful for displaying custom elements in the header. Note that custom header
-   *        elements can also be attached to the workspace header extension slots.
-   */
-  setTitle(title: string, titleNode?: ReactNode): void;
-}
-
-export interface WorkspaceWindowSize {
-  size: WorkspaceWindowState;
-}
-
-export interface WorkspaceWindowSizeProviderProps {
-  children?: React.ReactNode;
-}
-
-export interface WorkspaceWindowSizeContext {
-  windowSize: WorkspaceWindowSize;
-  updateWindowSize?(value: WorkspaceWindowState): any;
-  active: boolean;
-}
+import { type DefaultWorkspaceProps, type CloseWorkspaceOptions } from './types';
 
 export interface Prompt {
   title: string;
@@ -93,10 +27,121 @@ export interface WorkspaceStoreState {
   workspaceWindowState: WorkspaceWindowState;
 }
 
+/** See [[WorkspaceDefinition]] for more information about these properties */
+export interface WorkspaceRegistration {
+  name: string;
+  title: string;
+  titleNode?: ReactNode;
+  type: string;
+  canHide: boolean;
+  canMaximize: boolean;
+  width: 'narrow' | 'wider' | 'extra-wide';
+  hasOwnSidebar: boolean;
+  sidebarFamily: string;
+  preferredWindowSize: WorkspaceWindowState;
+  load: () => Promise<{ default?: LifeCycles } & LifeCycles>;
+  moduleName: string;
+}
+
 export interface OpenWorkspace extends WorkspaceRegistration, DefaultWorkspaceProps {
   additionalProps: object;
 }
 
+interface WorkspaceRegistrationStore {
+  workspaces: Record<string, WorkspaceRegistration>;
+}
+
+const workspaceRegistrationStore = createGlobalStore<WorkspaceRegistrationStore>('workspaceRegistrations', {
+  workspaces: {},
+});
+
+/** See [[WorkspaceDefinition]] for more information about these properties */
+export interface RegisterWorkspaceOptions {
+  name: string;
+  title: string;
+  type?: string;
+  canHide?: boolean;
+  canMaximize?: boolean;
+  width?: 'narrow' | 'wider' | 'extra-wide';
+  hasOwnSidebar?: boolean;
+  sidebarFamily?: string;
+  preferredWindowSize?: WorkspaceWindowState;
+  load: () => Promise<{ default?: LifeCycles } & LifeCycles>;
+  moduleName: string;
+}
+
+/**
+ * Tells the workspace system about a workspace. This is used by the app shell
+ * to register workspaces defined in the `routes.json` file.
+ * @internal
+ */
+export function registerWorkspace(workspace: RegisterWorkspaceOptions) {
+  workspaceRegistrationStore.setState((state) => ({
+    workspaces: {
+      ...state.workspaces,
+      [workspace.name]: {
+        ...workspace,
+        preferredWindowSize: workspace.preferredWindowSize ?? 'normal',
+        type: workspace.type ?? 'form',
+        canHide: workspace.canHide ?? false,
+        canMaximize: workspace.canMaximize ?? false,
+        width: workspace.width ?? 'narrow',
+        hasOwnSidebar: workspace.hasOwnSidebar ?? false,
+        sidebarFamily: workspace.sidebarFamily ?? 'default',
+      },
+    },
+  }));
+}
+
+const workspaceExtensionWarningsIssued = new Set();
+/**
+ * This exists for compatibility with the old way of registering
+ * workspaces (as extensions).
+ *
+ * @param name of the workspace
+ */
+function getWorkspaceRegistration(name: string): WorkspaceRegistration {
+  const registeredWorkspaces = workspaceRegistrationStore.getState().workspaces;
+  if (registeredWorkspaces[name]) {
+    return registeredWorkspaces[name];
+  } else {
+    const workspaceExtension = getExtensionRegistration(name);
+    if (workspaceExtension) {
+      if (!workspaceExtensionWarningsIssued.has(name)) {
+        console.warn(
+          `The workspace '${name}' is registered as an extension. This is deprecated. Please register it in the "workspaces" section of the routes.json file.`,
+        );
+        workspaceExtensionWarningsIssued.add(name);
+      }
+      return {
+        name: workspaceExtension.name,
+        title: getTitleFromExtension(workspaceExtension),
+        moduleName: workspaceExtension.moduleName,
+        preferredWindowSize: workspaceExtension.meta?.screenSize ?? 'normal',
+        load: workspaceExtension.load,
+        type: workspaceExtension.meta?.type ?? 'form',
+        canHide: workspaceExtension.meta?.canHide ?? false,
+        canMaximize: workspaceExtension.meta?.canMaximize ?? false,
+        width: workspaceExtension.meta?.width ?? 'narrow',
+        sidebarFamily: 'default',
+        hasOwnSidebar: false,
+      };
+    } else {
+      throw new Error(`No workspace named '${name}' has been registered.`);
+    }
+  }
+}
+
+function getTitleFromExtension(ext: ExtensionRegistration) {
+  const title = ext?.meta?.title;
+  if (typeof title === 'string') {
+    return title;
+  } else if (title && typeof title === 'object') {
+    return translateFrom(ext.moduleName, title.key, title.default);
+  }
+  return ext.name;
+}
+
 /**
  *
  * @param name Name of the workspace