@openmrs/esm-react-utils 3.4.1-pre.151 → 3.4.1-pre.161

package/jest.config.js

@@ -1,10 +1,11 @@
 module.exports = {
   transform: {
-    "^.+\\.tsx?$": ["@swc/jest"],
+    "^.+\\.(j|t)sx?$": ["@swc/jest"],
   },
-  setupFiles: ["<rootDir>/src/setup-tests.js"],
+  setupFilesAfterEnv: ["<rootDir>/src/setup-tests.js"],
   moduleNameMapper: {
     "lodash-es": "lodash",
+    "^lodash-es/(.*)$": "lodash/$1",
     "@openmrs/esm-error-handling":
       "<rootDir>/__mocks__/openmrs-esm-error-handling.mock.ts",
     "@openmrs/esm-state": "<rootDir>/__mocks__/openmrs-esm-state.mock.ts",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openmrs/esm-react-utils",
-  "version": "3.4.1-pre.151",
+  "version": "3.4.1-pre.161",
   "license": "MPL-2.0",
   "description": "React utilities for OpenMRS.",
   "browser": "dist/openmrs-esm-react-utils.js",
@@ -55,11 +55,11 @@
     "react-i18next": "11.x"
   },
   "devDependencies": {
-    "@openmrs/esm-api": "^3.4.1-pre.151",
-    "@openmrs/esm-config": "^3.4.1-pre.151",
-    "@openmrs/esm-error-handling": "^3.4.1-pre.151",
-    "@openmrs/esm-extensions": "^3.4.1-pre.151",
-    "@openmrs/esm-globals": "^3.4.1-pre.151",
+    "@openmrs/esm-api": "^3.4.1-pre.161",
+    "@openmrs/esm-config": "^3.4.1-pre.161",
+    "@openmrs/esm-error-handling": "^3.4.1-pre.161",
+    "@openmrs/esm-extensions": "^3.4.1-pre.161",
+    "@openmrs/esm-globals": "^3.4.1-pre.161",
     "dayjs": "^1.10.8",
     "i18next": "^19.6.0",
     "react": "^16.13.1",
@@ -68,5 +68,5 @@
     "rxjs": "^6.5.3",
     "unistore": "^3.5.2"
   },
-  "gitHead": "f8709e7ec5c11e10682ef7e2f1463c4d343c22e5"
+  "gitHead": "6db8e72832eb5cd8ab262dbaab7e8eaf841f92fd"
 }

package/src/Extension.tsx

@@ -1,10 +1,18 @@
 import { renderExtension } from "@openmrs/esm-extensions";
-import React, { useCallback, useContext, useEffect, useState } from "react";
+import React, {
+  useCallback,
+  useContext,
+  useEffect,
+  useRef,
+  useState,
+} from "react";
+import { Parcel } from "single-spa";
 import { ComponentContext } from ".";
 import { ExtensionData } from "./ComponentContext";
 
 export interface ExtensionProps {
   state?: Record<string, any>;
+  /** @deprecated Pass a function as the child of `ExtensionSlot` instead. */
   wrap?(
     slot: React.ReactNode,
     extension: ExtensionData
@@ -23,14 +31,21 @@ export interface ExtensionProps {
 export const Extension: React.FC<ExtensionProps> = ({ state, wrap }) => {
   const [domElement, setDomElement] = useState<HTMLDivElement>();
   const { extension } = useContext(ComponentContext);
+  const parcel = useRef<Parcel | null>();
+
+  if (wrap) {
+    console.warn(
+      "`wrap` prop of Extension is being used. This will be removed in a future release."
+    );
+  }
 
   const ref = useCallback((node) => {
     setDomElement(node);
   }, []);
 
   useEffect(() => {
-    if (domElement != null && extension) {
-      return renderExtension(
+    if (domElement != null && extension && !parcel.current) {
+      parcel.current = renderExtension(
         domElement,
         extension.extensionSlotName,
         extension.extensionSlotModuleName,
@@ -38,6 +53,9 @@ export const Extension: React.FC<ExtensionProps> = ({ state, wrap }) => {
         undefined,
         state
       );
+      return () => {
+        parcel.current && parcel.current.unmount();
+      };
     }
   }, [
     extension?.extensionSlotName,
@@ -47,9 +65,15 @@ export const Extension: React.FC<ExtensionProps> = ({ state, wrap }) => {
     domElement,
   ]);
 
-  // The extension is rendered into the `<slot>`. It is surrounded by a
-  // `<div>` with relative positioning in order to allow the UI Editor
-  // to absolutely position elements within it.
+  useEffect(() => {
+    if (parcel.current && parcel.current.update) {
+      parcel.current.update({ ...state });
+    }
+  }, [parcel.current, state]);
+
+  // The extension is rendered into the `<div>`. The `<div>` has relative
+  // positioning in order to allow the UI Editor to absolutely position
+  // elements within it.
   const slot = (
     <div
       ref={ref}

package/src/ExtensionSlot.tsx

@@ -4,41 +4,6 @@ import { ComponentContext } from "./ComponentContext";
 import { Extension } from "./Extension";
 import { useExtensionSlot } from "./useExtensionSlot";
 
-function isShallowEqual(prevDeps: any, nextDeps: any) {
-  if (prevDeps === nextDeps) {
-    return true;
-  }
-
-  if (!prevDeps && nextDeps) {
-    return false;
-  }
-
-  if (prevDeps && !nextDeps) {
-    return false;
-  }
-
-  if (typeof prevDeps !== "object" || typeof nextDeps !== "object") {
-    return false;
-  }
-
-  const prev = Object.keys(prevDeps);
-  const next = Object.keys(nextDeps);
-
-  if (prev.length !== next.length) {
-    return false;
-  }
-
-  for (let i = 0; i < prev.length; i++) {
-    const key = prev[i];
-
-    if (!(key in nextDeps) || nextDeps[key] !== prevDeps[key]) {
-      return false;
-    }
-  }
-
-  return true;
-}
-
 export interface ExtensionSlotBaseProps {
   name: string;
   /** @deprecated Use `name` */
@@ -59,51 +24,94 @@ export type ExtensionSlotProps = (
   | OldExtensionSlotBaseProps
   | ExtensionSlotBaseProps
 ) &
-  React.HTMLAttributes<HTMLDivElement>;
+  React.HTMLAttributes<HTMLDivElement> & {
+    children?:
+      | React.ReactNode
+      | ((extension: ConnectedExtension) => React.ReactNode);
+  };
 
 function defaultSelect(extensions: Array<ConnectedExtension>) {
   return extensions;
 }
 
-export const ExtensionSlot: React.FC<ExtensionSlotProps> = ({
-  name: goodName,
-  extensionSlotName,
+/**
+ * An [extension slot](https://o3-dev.docs.openmrs.org/#/main/extensions).
+ * A place with a name. Extensions that get connected to that name
+ * will be rendered into this.
+ *
+ * @param props.name The name of the extension slot
+ * @param props.select An optional function for filtering or otherwise modifying
+ *   the list of extensions that will be rendered.
+ * @param props.state *Only works if no children are provided*. Passes data
+ *   through as props to the extensions that are mounted here. If `ExtensionSlot`
+ *   has children, you must pass the state through the `state` param of the
+ *   `Extension` component.
+ * @param props.children There are two different ways to use `ExtensionSlot`
+ *   children.
+ *  - Passing a `ReactNode`, the "normal" way. The child must contain the component
+ *     `Extension`. Whatever is passed as the child will be rendered once per extension.
+ *     See the first example below.
+ *  - Passing a function, the "render props" way. The child must be a function
+ *     which takes a [[ConnectedExtension]] as argument and returns a `ReactNode`.
+ *     the resulting react node must contain the component `Extension`. It will
+ *     be run for each extension. See the second example below.
+ *
+ * @example
+ * Passing a react node as children
+ *
+ * ```tsx
+ * <ExtensionSlot name="Foo">
+ *   <div style={{ width: 10rem }}>
+ *     <Extension />
+ *   </div>
+ * </ExtensionSlot>
+ * ```
+ *
+ * @example
+ * Passing a function as children
+ *
+ * ```tsx
+ * <ExtensionSlot name="Bar">
+ *   {(extension) => (
+ *     <h1>{extension.name}</h1>
+ *     <div style={{ color: extension.meta.color }}>
+ *       <Extension />
+ *     </div>
+ *   )}
+ * </ExtensionSlot>
+ * ```
+ *
+ */
+export function ExtensionSlot({
+  name: extensionSlotName,
+  extensionSlotName: legacyExtensionSlotName,
   select = defaultSelect,
   children,
   state,
   style,
   ...divProps
-}: ExtensionSlotProps) => {
-  const name = (goodName ?? extensionSlotName) as string;
+}: ExtensionSlotProps) {
+  if (children && state) {
+    throw new Error(
+      "Both children and state have been provided. If children are provided, the state must be passed as a prop to the `Extension` component."
+    );
+  }
+
+  const name = (extensionSlotName ?? legacyExtensionSlotName) as string;
   const slotRef = useRef(null);
   const { extensions, extensionSlotModuleName } = useExtensionSlot(name);
-  const stateRef = useRef(state);
-
-  if (!isShallowEqual(stateRef.current, state)) {
-    stateRef.current = state;
-  }
 
-  const content = useMemo(
-    () =>
-      name &&
-      select(extensions).map((extension) => (
-        <ComponentContext.Provider
-          key={extension.id}
-          value={{
-            moduleName: extensionSlotModuleName, // moduleName is not used by the receiving Extension
-            extension: {
-              extensionId: extension.id,
-              extensionSlotName: name,
-              extensionSlotModuleName,
-            },
-          }}
-        >
-          {children ?? <Extension state={stateRef.current} />}
-        </ComponentContext.Provider>
-      )),
-    [select, extensions, name, stateRef.current]
+  const extensionsToRender = useMemo(
+    () => select(extensions),
+    [select, extensions]
   );
 
+  const extensionsFromChildrenFunction = useMemo(() => {
+    if (typeof children == "function" && !React.isValidElement(children)) {
+      return extensionsToRender.map((extension) => children(extension));
+    }
+  }, [children, extensionsToRender]);
+
   return (
     <div
       ref={slotRef}
@@ -112,7 +120,24 @@ export const ExtensionSlot: React.FC<ExtensionSlotProps> = ({
       style={{ ...style, position: "relative" }}
       {...divProps}
     >
-      {content}
+      {name &&
+        extensionsToRender.map((extension, i) => (
+          <ComponentContext.Provider
+            key={extension.id}
+            value={{
+              moduleName: extensionSlotModuleName, // moduleName is not used by the receiving Extension
+              extension: {
+                extensionId: extension.id,
+                extensionSlotName: name,
+                extensionSlotModuleName,
+              },
+            }}
+          >
+            {extensionsFromChildrenFunction?.[i] ?? children ?? (
+              <Extension state={state} />
+            )}
+          </ComponentContext.Provider>
+        ))}
     </div>
   );
-};
+}

package/src/extensions.test.tsx

@@ -0,0 +1,272 @@
+import React, { useCallback, useReducer } from "react";
+import { render, screen, waitFor, within } from "@testing-library/react";
+import {
+  attach,
+  ConnectedExtension,
+  getExtensionNameFromId,
+  registerExtension,
+  updateInternalExtensionStore,
+} from "@openmrs/esm-extensions";
+import {
+  getSyncLifecycle,
+  Extension,
+  ExtensionSlot,
+  openmrsComponentDecorator,
+  useExtensionSlotMeta,
+  ExtensionData,
+} from ".";
+import userEvent from "@testing-library/user-event";
+
+// For some reason in the text context `isEqual` always returns true
+// when using the import substitution in jest.config.js. Here's a custom
+// mock.
+jest.mock(
+  "lodash-es/isEqual",
+  () => (a, b) => JSON.stringify(a) == JSON.stringify(b)
+);
+
+describe("ExtensionSlot, Extension, and useExtensionSlotMeta", () => {
+  beforeEach(() => {
+    updateInternalExtensionStore(() => ({ slots: {}, extensions: {} }));
+  });
+
+  test("Extension receives state changes passed through (not using <Extension>)", async () => {
+    function EnglishExtension({ suffix }) {
+      return <div>English{suffix}</div>;
+    }
+    registerSimpleExtension("English", "esm-languages-app", EnglishExtension);
+    attach("Box", "English");
+    const App = openmrsComponentDecorator({
+      moduleName: "esm-languages-app",
+      featureName: "Languages",
+      disableTranslations: true,
+    })(() => {
+      const [suffix, toggleSuffix] = useReducer(
+        (suffix) => (suffix == "!" ? "?" : "!"),
+        "!"
+      );
+      return (
+        <div>
+          <ExtensionSlot name="Box" state={{ suffix }} />
+          <button onClick={toggleSuffix}>Toggle suffix</button>
+        </div>
+      );
+    });
+    render(<App />);
+
+    await waitFor(() =>
+      expect(screen.getByText(/English/)).toBeInTheDocument()
+    );
+    expect(screen.getByText(/English/)).toHaveTextContent("English!");
+    userEvent.click(screen.getByText("Toggle suffix"));
+    await waitFor(() =>
+      expect(screen.getByText(/English/)).toHaveTextContent("English?")
+    );
+  });
+
+  test("Extension receives state changes (using <Extension>)", async () => {
+    function HaitianCreoleExtension({ suffix }) {
+      return <div>Haitian Creole{suffix}</div>;
+    }
+    registerSimpleExtension(
+      "Haitian",
+      "esm-languages-app",
+      HaitianCreoleExtension
+    );
+    attach("Box", "Haitian");
+    const App = openmrsComponentDecorator({
+      moduleName: "esm-languages-app",
+      featureName: "Languages",
+      disableTranslations: true,
+    })(() => {
+      const [suffix, toggleSuffix] = useReducer(
+        (suffix) => (suffix == "!" ? "?" : "!"),
+        "!"
+      );
+
+      return (
+        <div>
+          <ExtensionSlot name="Box">
+            {suffix}
+            <Extension state={{ suffix }} />
+          </ExtensionSlot>
+          <button onClick={toggleSuffix}>Toggle suffix</button>
+        </div>
+      );
+    });
+    render(<App />);
+
+    await waitFor(() =>
+      expect(screen.getByText(/Haitian/)).toBeInTheDocument()
+    );
+    expect(screen.getByText(/Haitian/)).toHaveTextContent("Haitian Creole!");
+    userEvent.click(screen.getByText("Toggle suffix"));
+    await waitFor(() =>
+      expect(screen.getByText(/Haitian/)).toHaveTextContent("Haitian Creole?")
+    );
+  });
+
+  test("ExtensionSlot throws error if both state and children provided", () => {
+    const App = () => (
+      <ExtensionSlot name="Box" state={{ color: "red" }}>
+        <Extension />
+      </ExtensionSlot>
+    );
+    expect(() => render(<App />)).toThrowError(
+      expect.objectContaining({
+        message: expect.stringMatching(/children.*state/),
+      })
+    );
+  });
+
+  test("Extension Slot receives meta", async () => {
+    registerSimpleExtension("Spanish", "esm-languages-app", undefined, {
+      code: "es",
+    });
+    attach("Box", "Spanish");
+    const App = openmrsComponentDecorator({
+      moduleName: "esm-languages-app",
+      featureName: "Languages",
+      disableTranslations: true,
+    })(() => {
+      const metas = useExtensionSlotMeta("Box");
+      const wrapItem = useCallback(
+        (slot: React.ReactNode, extension: ExtensionData) => {
+          return (
+            <div>
+              <h1>
+                {metas[getExtensionNameFromId(extension.extensionId)].code}
+              </h1>
+              {slot}
+            </div>
+          );
+        },
+        [metas]
+      );
+      return (
+        <div>
+          <ExtensionSlot name="Box">
+            <Extension wrap={wrapItem} />
+          </ExtensionSlot>
+        </div>
+      );
+    });
+    render(<App />);
+
+    await waitFor(() =>
+      expect(screen.getByRole("heading")).toBeInTheDocument()
+    );
+    expect(screen.getByRole("heading")).toHaveTextContent("es");
+    expect(screen.getByText("Spanish")).toBeInTheDocument();
+  });
+
+  test("Both meta and state can be used at the same time", async () => {
+    function SwahiliExtension({ suffix }) {
+      return <div>Swahili{suffix}</div>;
+    }
+    registerSimpleExtension("Swahili", "esm-languages-app", SwahiliExtension, {
+      code: "sw",
+    });
+    attach("Box", "Swahili");
+    const App = openmrsComponentDecorator({
+      moduleName: "esm-languages-app",
+      featureName: "Languages",
+      disableTranslations: true,
+    })(() => {
+      const [suffix, toggleSuffix] = useReducer(
+        (suffix) => (suffix == "!" ? "?" : "!"),
+        "!"
+      );
+      const metas = useExtensionSlotMeta("Box");
+      const wrapItem = useCallback(
+        (slot: React.ReactNode, extension: ExtensionData) => {
+          return (
+            <div>
+              <h1>
+                {metas[getExtensionNameFromId(extension.extensionId)].code}
+              </h1>
+              {slot}
+            </div>
+          );
+        },
+        [metas]
+      );
+      return (
+        <div>
+          <ExtensionSlot name="Box">
+            <Extension wrap={wrapItem} state={{ suffix }} />
+          </ExtensionSlot>
+          <button onClick={toggleSuffix}>Toggle suffix</button>
+        </div>
+      );
+    });
+    render(<App />);
+
+    await waitFor(() =>
+      expect(screen.getByRole("heading")).toBeInTheDocument()
+    );
+    expect(screen.getByRole("heading")).toHaveTextContent("sw");
+    expect(screen.getByText(/Swahili/)).toHaveTextContent("Swahili!");
+    userEvent.click(screen.getByText("Toggle suffix"));
+    await waitFor(() =>
+      expect(screen.getByText(/Swahili/)).toHaveTextContent("Swahili?")
+    );
+  });
+
+  test("Extension Slot renders function children", async () => {
+    registerSimpleExtension("Urdu", "esm-languages-app", undefined, {
+      code: "urd",
+    });
+    registerSimpleExtension("Hindi", "esm-languages-app", undefined, {
+      code: "hi",
+    });
+    attach("Box", "Urdu");
+    attach("Box", "Hindi");
+    const App = openmrsComponentDecorator({
+      moduleName: "esm-languages-app",
+      featureName: "Languages",
+      disableTranslations: true,
+    })(() => {
+      return (
+        <div>
+          <ExtensionSlot name="Box">
+            {(extension: ConnectedExtension) => (
+              <div data-testid={extension.name}>
+                <h2>{extension.meta.code}</h2>
+                <Extension />
+              </div>
+            )}
+          </ExtensionSlot>
+        </div>
+      );
+    });
+    render(<App />);
+
+    await waitFor(() => expect(screen.getByTestId("Urdu")).toBeInTheDocument());
+    expect(
+      within(screen.getByTestId("Urdu")).getByRole("heading")
+    ).toHaveTextContent("urd");
+    expect(
+      within(screen.getByTestId("Hindi")).getByRole("heading")
+    ).toHaveTextContent("hi");
+  });
+});
+
+function registerSimpleExtension(
+  name: string,
+  moduleName: string,
+  Component?: React.ComponentType<any>,
+  meta: object = {}
+) {
+  const SimpleComponent = () => <div>{name}</div>;
+  registerExtension({
+    name,
+    moduleName,
+    load: getSyncLifecycle(Component ?? SimpleComponent, {
+      moduleName,
+      featureName: moduleName,
+      disableTranslations: true,
+    }),
+    meta,
+  });
+}

package/src/public.ts

@@ -12,7 +12,6 @@ export * from "./useConnectedExtensions";
 export * from "./useConnectivity";
 export * from "./usePatient";
 export * from "./useCurrentPatient";
-export * from "./useExtensionSlot";
 export * from "./useExtensionSlotMeta";
 export * from "./useExtensionStore";
 export * from "./useLayoutType";

package/src/setup-tests.js

@@ -1,3 +1,5 @@
+import "@testing-library/jest-dom/extend-expect";
+
 window.System = {
   import: (name) => import(name),
   resolve: jest.fn().mockImplementation(() => {

package/src/useAssignedExtensionIds.ts

@@ -1,7 +1,7 @@
 /** @module @category Extension */
 import { useEffect, useState } from "react";
 import { getExtensionStore } from "@openmrs/esm-extensions";
-import { isEqual } from "lodash";
+import isEqual from "lodash-es/isEqual";
 
 /**
  * Gets the assigned extension ids for a given extension slot name.

package/src/useAssignedExtensions.ts

@@ -5,7 +5,7 @@ import {
   ExtensionStore,
   getExtensionStore,
 } from "@openmrs/esm-extensions";
-import { isEqual } from "lodash";
+import isEqual from "lodash/isEqual";
 
 /**
  * Gets the assigned extensions for a given extension slot name.