@openmrs/esm-react-utils 4.0.0-pre.0 → 4.0.1-pre.206

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": "4.0.0-pre.0",
+  "version": "4.0.1-pre.206",
   "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": "^4.0.0-pre.0",
-    "@openmrs/esm-config": "^4.0.0-pre.0",
-    "@openmrs/esm-error-handling": "^4.0.0-pre.0",
-    "@openmrs/esm-extensions": "^4.0.0-pre.0",
-    "@openmrs/esm-globals": "^4.0.0-pre.0",
+    "@openmrs/esm-api": "^4.0.1-pre.206",
+    "@openmrs/esm-config": "^4.0.1-pre.206",
+    "@openmrs/esm-error-handling": "^4.0.1-pre.206",
+    "@openmrs/esm-extensions": "^4.0.1-pre.206",
+    "@openmrs/esm-globals": "^4.0.1-pre.206",
     "dayjs": "^1.10.8",
     "i18next": "^19.6.0",
     "react": "^18.1.0",
@@ -68,5 +68,5 @@
     "rxjs": "^6.5.3",
     "unistore": "^3.5.2"
   },
-  "gitHead": "254a7226212aac82df4434639b2584e24ac240e4"
+  "gitHead": "7ac6e01b41238739cdf5d20efdff50062f46f500"
 }

package/src/ConfigurableLink.test.tsx

@@ -1,8 +1,8 @@
 import React from "react";
 import "@testing-library/jest-dom/extend-expect";
 import { render, screen } from "@testing-library/react";
-import { navigate, interpolateUrl } from "@openmrs/esm-config";
 import userEvent from "@testing-library/user-event";
+import { navigate, interpolateUrl } from "@openmrs/esm-config";
 import { ConfigurableLink } from "./ConfigurableLink";
 
 jest.mock("single-spa");
@@ -37,17 +37,21 @@ describe(`ConfigurableLink`, () => {
   });
 
   it(`calls navigate on normal click but not special clicks`, async () => {
+    const user = userEvent.setup();
+
     const link = screen.getByRole("link", { name: /spa home/i });
-    await userEvent.pointer({ target: link, keys: "[MouseRight]" });
+    await user.pointer({ target: link, keys: "[MouseRight]" });
     expect(navigate).not.toHaveBeenCalled();
-    await userEvent.click(link);
+    await user.click(link);
     expect(navigate).toHaveBeenCalledWith({ to: path });
   });
 
   it(`calls navigate on enter`, async () => {
+    const user = userEvent.setup();
+
     expect(navigate).not.toHaveBeenCalled();
     const link = screen.getByRole("link", { name: /spa home/i });
-    await userEvent.type(link, "{enter}");
+    await user.type(link, "{enter}");
     expect(navigate).toHaveBeenCalledWith({ to: path });
   });
 });

package/src/ConfigurableLink.tsx

@@ -1,8 +1,12 @@
 /** @module @category Navigation */
 import React, { MouseEvent, AnchorHTMLAttributes } from "react";
-import { navigate, interpolateUrl } from "@openmrs/esm-config";
+import { navigate, interpolateUrl, TemplateParams } from "@openmrs/esm-config";
 
-function handleClick(event: MouseEvent, to: string) {
+function handleClick(
+  event: MouseEvent,
+  to: string,
+  templateParams?: TemplateParams
+) {
   if (
     !event.metaKey &&
     !event.ctrlKey &&
@@ -10,7 +14,7 @@ function handleClick(event: MouseEvent, to: string) {
     event.button == 0
   ) {
     event.preventDefault();
-    navigate({ to });
+    navigate({ to, templateParams });
   }
 }
 
@@ -20,25 +24,30 @@ function handleClick(event: MouseEvent, to: string) {
 export interface ConfigurableLinkProps
   extends AnchorHTMLAttributes<HTMLAnchorElement> {
   to: string;
+  templateParams?: TemplateParams;
 }
 
 /**
  * A React link component which calls [[navigate]] when clicked
  *
  * @param to The target path or URL. Supports interpolation. See [[navigate]]
+ * @param urlParams: A dictionary of values to interpolate into the URL, in addition to the default keys `openmrsBase` and `openmrsSpaBase`.
  * @param children Inline elements within the link
  * @param otherProps Any other valid props for an <a> tag except `href` and `onClick`
  */
-export const ConfigurableLink: React.FC<ConfigurableLinkProps> = ({
+export function ConfigurableLink({
   to,
+  templateParams,
   children,
   ...otherProps
-}) => (
-  <a
-    onClick={(event) => handleClick(event, to)}
-    href={interpolateUrl(to)}
-    {...otherProps}
-  >
-    {children}
-  </a>
-);
+}: ConfigurableLinkProps) {
+  return (
+    <a
+      onClick={(event) => handleClick(event, to, templateParams)}
+      href={interpolateUrl(to, templateParams)}
+      {...otherProps}
+    >
+      {children}
+    </a>
+  );
+}

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,101 +4,141 @@ 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` */
+  extensionSlotName?: string;
+  select?: (extensions: Array<ConnectedExtension>) => Array<ConnectedExtension>;
+  state?: Record<string, any>;
 }
 
-export interface ExtensionSlotBaseProps {
+export interface OldExtensionSlotBaseProps {
+  name?: string;
+  /** @deprecated Use `name` */
   extensionSlotName: string;
   select?: (extensions: Array<ConnectedExtension>) => Array<ConnectedExtension>;
   state?: Record<string, any>;
 }
 
-export type ExtensionSlotProps = ExtensionSlotBaseProps &
-  React.HTMLAttributes<HTMLDivElement>;
+export type ExtensionSlotProps = (
+  | OldExtensionSlotBaseProps
+  | ExtensionSlotBaseProps
+) &
+  Omit<React.HTMLAttributes<HTMLDivElement>, "children"> & {
+    children?:
+      | React.ReactNode
+      | ((extension: ConnectedExtension) => React.ReactNode);
+  };
 
 function defaultSelect(extensions: Array<ConnectedExtension>) {
   return extensions;
 }
 
-export const ExtensionSlot: React.FC<ExtensionSlotProps> = ({
-  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 slotRef = useRef(null);
-  const { extensions, extensionSlotModuleName } =
-    useExtensionSlot(extensionSlotName);
-  const stateRef = useRef(state);
-
-  if (!isShallowEqual(stateRef.current, state)) {
-    stateRef.current = state;
+}: 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 content = useMemo(
-    () =>
-      extensionSlotName &&
-      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,
-              extensionSlotModuleName,
-            },
-          }}
-        >
-          {children ?? <Extension state={stateRef.current} />}
-        </ComponentContext.Provider>
-      )),
-    [select, extensions, extensionSlotName, stateRef.current]
+  const name = (extensionSlotName ?? legacyExtensionSlotName) as string;
+  const slotRef = useRef(null);
+  const { extensions, extensionSlotModuleName } = useExtensionSlot(name);
+
+  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}
-      data-extension-slot-name={extensionSlotName}
+      data-extension-slot-name={name}
       data-extension-slot-module-name={extensionSlotModuleName}
       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] ??
+              (typeof children != "function" ? children : null) ?? (
+                <Extension state={state} />
+              )}
+          </ComponentContext.Provider>
+        ))}
     </div>
   );
-};
+}

package/src/UserHasAccess.tsx

@@ -1,14 +1,16 @@
 /** @module @category API */
+import { getCurrentUser, LoggedInUser, userHasAccess } from "@openmrs/esm-api";
 import React, { useEffect, useState } from "react";
-import { getCurrentUser, userHasAccess, LoggedInUser } from "@openmrs/esm-api";
 
 export interface UserHasAccessProps {
-  privilege: string;
+  privilege: string | string[];
+  fallback?: React.ReactNode;
   children?: React.ReactNode;
 }
 
 export const UserHasAccess: React.FC<UserHasAccessProps> = ({
   privilege,
+  fallback,
   children,
 }) => {
   const [user, setUser] = useState<LoggedInUser | null>(null);
@@ -22,7 +24,7 @@ export const UserHasAccess: React.FC<UserHasAccessProps> = ({
 
   if (user && userHasAccess(privilege, user)) {
     return <>{children}</>;
+  } else {
+    return fallback ? <>{fallback}</> : null;
   }
-
-  return null;
 };