@openmrs/esm-react-utils 5.1.0 → 5.1.1-pre.1003

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openmrs/esm-react-utils",
-  "version": "5.1.0",
+  "version": "5.1.1-pre.1003",
   "license": "MPL-2.0",
   "description": "React utilities for OpenMRS.",
   "browser": "dist/openmrs-esm-react-utils.js",
@@ -56,12 +56,12 @@
     "react-i18next": "11.x"
   },
   "devDependencies": {
-    "@openmrs/esm-api": "^5.1.0",
-    "@openmrs/esm-config": "^5.1.0",
-    "@openmrs/esm-error-handling": "^5.1.0",
-    "@openmrs/esm-extensions": "^5.1.0",
-    "@openmrs/esm-feature-flags": "^5.1.0",
-    "@openmrs/esm-globals": "^5.1.0",
+    "@openmrs/esm-api": "^5.1.1-pre.1003",
+    "@openmrs/esm-config": "^5.1.1-pre.1003",
+    "@openmrs/esm-error-handling": "^5.1.1-pre.1003",
+    "@openmrs/esm-extensions": "^5.1.1-pre.1003",
+    "@openmrs/esm-feature-flags": "^5.1.1-pre.1003",
+    "@openmrs/esm-globals": "^5.1.1-pre.1003",
     "dayjs": "^1.10.8",
     "i18next": "^19.6.0",
     "react": "^18.1.0",
@@ -70,5 +70,5 @@
     "rxjs": "^6.5.3",
     "webpack": "^5.88.0"
   },
-  "gitHead": "b3a3b5208270447ef1fd85b2f7e4ce55e717b9ec"
+  "gitHead": "1bd2d52c33783c93102f9c696db84faf26932c82"
 }

package/src/ConfigurableLink.tsx

@@ -1,8 +1,8 @@
 /** @module @category Navigation */
 import React, {
-  MouseEvent,
-  AnchorHTMLAttributes,
-  PropsWithChildren,
+  type MouseEvent,
+  type AnchorHTMLAttributes,
+  type PropsWithChildren,
 } from "react";
 import { navigate, interpolateUrl, TemplateParams } from "@openmrs/esm-config";
 

package/src/Extension.tsx

@@ -5,6 +5,7 @@ import React, {
   useEffect,
   useRef,
   useState,
+  type ReactElement,
 } from "react";
 import type { Parcel } from "single-spa";
 import { ComponentContext } from ".";
@@ -16,7 +17,7 @@ export type ExtensionProps = {
   wrap?(
     slot: React.ReactNode,
     extension: ExtensionData
-  ): React.ReactElement<any, any> | null;
+  ): ReactElement<any, any> | null;
 } & Omit<React.HTMLAttributes<HTMLDivElement>, "children"> & {
     children?:
       | React.ReactNode

package/src/getLifecycle.ts

@@ -1,5 +1,5 @@
 /** @module @category Framework */
-import React from "react";
+import React, { ComponentType } from "react";
 import ReactDOMClient from "react-dom/client";
 import singleSpaReact from "single-spa-react";
 import {
@@ -8,7 +8,7 @@ import {
 } from "./openmrsComponentDecorator";
 
 export function getLifecycle<T>(
-  Component: React.ComponentType<T>,
+  Component: ComponentType<T>,
   options: ComponentDecoratorOptions
 ) {
   return singleSpaReact({
@@ -19,7 +19,7 @@ export function getLifecycle<T>(
 }
 
 export function getAsyncLifecycle<T>(
-  lazy: () => Promise<{ default: React.ComponentType<T> }>,
+  lazy: () => Promise<{ default: ComponentType<T> }>,
   options: ComponentDecoratorOptions
 ) {
   return () =>
@@ -27,7 +27,7 @@ export function getAsyncLifecycle<T>(
 }
 
 export function getSyncLifecycle<T>(
-  Component: React.ComponentType<T>,
+  Component: ComponentType<T>,
   options: ComponentDecoratorOptions
 ) {
   return () => Promise.resolve(getLifecycle(Component, options));

package/src/index.ts

@@ -1,6 +1,5 @@
 export * from "./ComponentContext";
 export * from "./ConfigurableLink";
-export * from "./createUseStore";
 export * from "./Extension";
 export * from "./ExtensionSlot";
 export * from "./getLifecycle";

package/src/openmrsComponentDecorator.tsx

@@ -1,4 +1,4 @@
-import React, { Suspense, useEffect, useRef } from "react";
+import React, { type ComponentType, Suspense } from "react";
 import { I18nextProvider } from "react-i18next";
 import type {} from "@openmrs/esm-globals";
 import {
@@ -42,8 +42,8 @@ export function openmrsComponentDecorator(userOpts: ComponentDecoratorOptions) {
   const opts = Object.assign({}, defaultOpts, userOpts);
 
   return function decorateComponent(
-    Comp: React.ComponentType<any>
-  ): React.ComponentType<any> {
+    Comp: ComponentType<any>
+  ): ComponentType<any> {
     return class OpenmrsReactComponent extends React.Component<
       OpenmrsReactComponentProps,
       OpenmrsReactComponentState

package/src/public.ts

@@ -1,6 +1,5 @@
 export { type ExtensionData } from "./ComponentContext";
 export * from "./ConfigurableLink";
-export * from "./createUseStore";
 export * from "./Extension";
 export * from "./ExtensionSlot";
 export * from "./getLifecycle";

package/src/useConfig.test.tsx

@@ -20,6 +20,12 @@ function RenderConfig(props) {
   return <button>{config[props.configKey]}</button>;
 }
 
+function RenderExternalConfig(props) {
+  const config = useConfig({ externalModuleName: props.externalModuleName });
+
+  return <button>{config[props.configKey]}</button>;
+}
+
 function clearConfig() {
   mockConfigInternalStore.resetMock();
 }
@@ -297,4 +303,40 @@ describe(`useConfig in an extension`, () => {
       expect(screen.findByText("Yet another thing")).toBeTruthy()
     );
   });
+
+  it("can optionally load an external module's configuration", async () => {
+    defineConfigSchema("first-module", {
+      thing: {
+        _default: "first thing",
+      },
+    });
+
+    defineConfigSchema("second-module", {
+      thing: {
+        _default: "second thing",
+      },
+    });
+
+    render(
+      <React.Suspense fallback={<div>Suspense!</div>}>
+        <ComponentContext.Provider
+          value={{
+            moduleName: "first-module",
+            extension: {
+              extensionSlotName: "fooSlot",
+              extensionSlotModuleName: "slot-mod",
+              extensionId: "fooExt#id1",
+            },
+          }}
+        >
+          <RenderExternalConfig
+            externalModuleName="second-module"
+            configKey="thing"
+          />
+        </ComponentContext.Provider>
+      </React.Suspense>
+    );
+
+    await waitFor(() => expect(screen.findByText("second thing")).toBeTruthy());
+  });
 });

package/src/useConfig.ts

@@ -157,16 +157,24 @@ function useNormalConfig(moduleName: string) {
   return state;
 }
 
+interface UseConfigOptions {
+  /** An external module to load the configuration from. This option should only be used if
+      absolutely necessary as it can end up making frontend modules coupled to one another. */
+  externalModuleName?: string;
+}
+
 /**
  * Use this React Hook to obtain your module's configuration.
+ *
+ * @param options Additional options that can be passed to useConfig()
  */
-export function useConfig<
-  T = Omit<ConfigObject, "Display conditions" | "Translation overrides">
->() {
+export function useConfig<T = Record<string, any>>(options?: UseConfigOptions) {
   // This hook uses the config of the MF defining the component.
   // If the component is used in an extension slot then the slot
   // may override (part of) its configuration.
-  const { moduleName, extension } = useContext(ComponentContext);
+  const { moduleName: contextModuleName, extension } =
+    useContext(ComponentContext);
+  const moduleName = options?.externalModuleName ?? contextModuleName;
 
   if (!moduleName && !extension) {
     throw Error(errorMessage);
@@ -175,11 +183,11 @@ export function useConfig<
   const normalConfig = useNormalConfig(moduleName);
   const extensionConfig = useExtensionConfig(extension);
   const config = useMemo(
-    () => ({
-      ...normalConfig,
-      ...extensionConfig,
-    }),
-    [normalConfig, extensionConfig]
+    () =>
+      options?.externalModuleName && moduleName === options.externalModuleName
+        ? { ...normalConfig }
+        : { ...normalConfig, ...extensionConfig },
+    [moduleName, options?.externalModuleName, normalConfig, extensionConfig]
   );
 
   return config as T;

package/src/useExtensionInternalStore.ts

@@ -2,7 +2,7 @@ import {
   ExtensionInternalStore,
   getExtensionInternalStore,
 } from "@openmrs/esm-extensions";
-import { createUseStore } from "./createUseStore";
+import { createUseStore } from "./useStore";
 
 /** @internal
  * @deprecated Use `useStore(getExtensionInternalStore())`

package/src/useExtensionStore.ts

@@ -1,6 +1,6 @@
 /** @module @category Extension */
 import { ExtensionStore, getExtensionStore } from "@openmrs/esm-extensions";
-import { createUseStore } from "./createUseStore";
+import { createUseStore } from "./useStore";
 
 export const useExtensionStore = createUseStore<ExtensionStore>(
   getExtensionStore()

package/src/usePagination.ts

@@ -1,5 +1,5 @@
 /** @module @category UI */
-import { useMemo, useState } from "react";
+import { useCallback, useMemo, useState } from "react";
 
 const defaultResultsPerPage = 10;
 
@@ -22,25 +22,47 @@ export function usePagination<T>(
     return data.slice(lowerBound, upperBound);
   }, [data, page, resultsPerPage]);
 
-  return {
-    results,
-    totalPages,
-    currentPage: page,
-    paginated: data.length > resultsPerPage,
-    showNextButton: page < totalPages,
-    showPreviousButton: page > 1,
-    goTo(page: number) {
+  const goTo = useCallback(
+    (page: number) => {
       setPage(Math.max(1, Math.min(totalPages, page)));
     },
-    goToNext() {
-      if (page < totalPages) {
-        setPage(page + 1);
-      }
-    },
-    goToPrevious() {
-      if (page > 1) {
-        setPage(page - 1);
-      }
-    },
-  };
+    [setPage, totalPages]
+  );
+  const goToNext = useCallback(() => {
+    if (page < totalPages) {
+      setPage(page + 1);
+    }
+  }, [page, totalPages, setPage]);
+
+  const goToPrevious = useCallback(() => {
+    if (page > 1) {
+      setPage(page - 1);
+    }
+  }, [page, setPage]);
+
+  const memoisedPaginatedData = useMemo(
+    () => ({
+      results,
+      totalPages,
+      currentPage: page,
+      paginated: data.length > resultsPerPage,
+      showNextButton: page < totalPages,
+      showPreviousButton: page > 1,
+      goTo,
+      goToNext,
+      goToPrevious,
+    }),
+    [
+      results,
+      totalPages,
+      data.length,
+      resultsPerPage,
+      page,
+      goTo,
+      goToNext,
+      goToPrevious,
+    ]
+  );
+
+  return memoisedPaginatedData;
 }

package/src/useStore.test.ts

@@ -0,0 +1,50 @@
+import { act, renderHook } from "@testing-library/react";
+import { createGlobalStore } from "@openmrs/esm-state";
+import { useStore, useStoreWithActions } from "@openmrs/esm-react-utils";
+
+describe("useStore", () => {
+  it("updates state, selects, and correctly binds actions", () => {
+    const store = createGlobalStore("scoreboard", {
+      good: { count: 0 },
+      evil: { count: 0 },
+    });
+    const actions = {
+      tally: (state, team, number) => ({
+        [team]: { count: state[team].count + number },
+      }),
+    };
+
+    const { result } = renderHook(() =>
+      useStore(store, (state) => state.good, actions)
+    );
+
+    expect(result.current.count).toBe(0);
+    act(() => {
+      result.current.tally("good", 2);
+    });
+    expect(result.current.count).toBe(2);
+  });
+});
+
+describe("useStoreWithActions", () => {
+  it("should correctly bind actions", () => {
+    const store = createGlobalStore("counter", { count: 0 });
+    const actions = {
+      increment: (state) => ({ count: state.count + 1 }),
+      incrementBy: (state, number) => ({ count: state.count + number }),
+    };
+
+    const { result } = renderHook(() => useStoreWithActions(store, actions));
+
+    expect(result.current.count).toBe(0);
+    act(() => {
+      result.current.increment();
+    });
+    expect(store.getState().count).toBe(1);
+    expect(result.current.count).toBe(1);
+    act(() => {
+      result.current.incrementBy(3);
+    });
+    expect(result.current.count).toBe(4);
+  });
+});

package/src/useStore.ts

@@ -2,9 +2,14 @@
 import { subscribeTo } from "@openmrs/esm-state";
 import { useEffect, useMemo, useState } from "react";
 import type { StoreApi } from "zustand";
-import type { Actions, BoundActions } from "./createUseStore";
 
-function bindActions<T>(store: StoreApi<T>, actions: Actions): BoundActions {
+export type ActionFunction<T> = (state: T, ...args: any[]) => Partial<T>;
+export type Actions<T> =
+  | ((store: StoreApi<T>) => Record<string, ActionFunction<T>>)
+  | Record<string, ActionFunction<T>>;
+export type BoundActions = { [key: string]: (...args: any[]) => void };
+
+function bindActions<T>(store: StoreApi<T>, actions: Actions<T>): BoundActions {
   if (typeof actions == "function") {
     actions = actions(store);
   }
@@ -12,7 +17,7 @@ function bindActions<T>(store: StoreApi<T>, actions: Actions): BoundActions {
   const bound = {};
 
   for (let i in actions) {
-    bound[i] = () => {
+    bound[i] = function () {
       const args = arguments;
       store.setState((state) => {
         let _args = [state];
@@ -35,17 +40,17 @@ function useStore<T, U>(store: StoreApi<T>, select: (state: T) => U): U;
 function useStore<T, U>(
   store: StoreApi<T>,
   select: undefined,
-  actions: Actions
+  actions: Actions<T>
 ): T & BoundActions;
 function useStore<T, U>(
   store: StoreApi<T>,
   select: (state: T) => U,
-  actions: Actions
+  actions: Actions<T>
 ): U & BoundActions;
 function useStore<T, U>(
   store: StoreApi<T>,
   select: (state: T) => U = defaultSelectFunction,
-  actions?: Actions
+  actions?: Actions<T>
 ) {
   const [state, setState] = useState<U>(() => select(store.getState()));
   useEffect(() => subscribeTo(store, select, setState), [store, select]);
@@ -58,11 +63,39 @@ function useStore<T, U>(
   return { ...state, ...boundActions };
 }
 
+/**
+ *
+ * @param store A zustand store
+ * @param actions
+ * @returns
+ */
 function useStoreWithActions<T>(
   store: StoreApi<T>,
-  actions: Actions
+  actions: Actions<T>
 ): T & BoundActions {
   return useStore(store, defaultSelectFunction, actions);
 }
 
-export { useStore, useStoreWithActions };
+/**
+ * Whenever possible, use `useStore(yourStore)` instead. This function is for creating a
+ * custom hook for a specific store.
+ */
+function createUseStore<T>(store: StoreApi<T>) {
+  function useStore(): T;
+  function useStore(actions: Actions<T>): T & BoundActions;
+  function useStore(actions?: Actions<T>): T & BoundActions;
+  function useStore(actions?: Actions<T>) {
+    const [state, set] = useState(store.getState());
+    useEffect(() => store.subscribe((state) => set(state)), []);
+    let boundActions: BoundActions = useMemo(
+      () => (actions ? bindActions(store, actions) : {}),
+      [actions]
+    );
+
+    return { ...state, ...boundActions };
+  }
+
+  return useStore;
+}
+
+export { createUseStore, useStore, useStoreWithActions };

package/src/useVisit.ts

@@ -17,17 +17,30 @@ export interface VisitReturnType {
   error: Error;
   mutate: () => void;
   isValidating: boolean;
+  activeVisit: Visit | null;
   currentVisit: Visit | null;
-  isRetrospective: boolean;
+  currentVisitIsRetrospective: boolean;
   isLoading: boolean;
 }
 
 /**
- * This React hook returns a visit object. If the `patientUuid` is provided
- * as a parameter, then the currentVisit, error and mutate function
- * for that patient visit is returned.
+ * This React hook returns visit information if the patient UUID is not null. There are
+ * potentially two relevant visits at a time: "active" and "current".
+ *
+ * The active visit is the most recent visit without an end date. The presence of an active
+ * visit generally means that the patient is in the facility.
+ *
+ * The current visit is the active visit, unless a retrospective visit has been selected.
+ * If there is no active visit and no selected retrospective visit, then there is no
+ * current visit. If there is no active visit but there is a retrospective visit, then
+ * the retrospective visit is the current visit. `currentVisitIsRetrospective` tells you
+ * whether the current visit is a retrospective visit.
+ *
+ * The active visit and current visit require two separate API calls. `error` contains
+ * the error from either one, if there is an error. `isValidating` is true if either
+ * API call is in progress. `mutate` refreshes the data from both API calls.
+ *
  * @param patientUuid Unique patient identifier `string`
- * @returns Object {`error` `isValidating`, `currentVisit`, `mutate`}
  */
 export function useVisit(patientUuid: string): VisitReturnType {
   const { patientUuid: visitStorePatientUuid, manuallySetVisitUuid } = useStore(
@@ -38,31 +51,60 @@ export function useVisit(patientUuid: string): VisitReturnType {
     patientUuid && visitStorePatientUuid == patientUuid
       ? manuallySetVisitUuid
       : null;
-  const visitGetUrlSuffix = retrospectiveVisitUuid
-    ? `/${retrospectiveVisitUuid}`
-    : `?patient=${patientUuid}&v=${defaultVisitCustomRepresentation}&includeInactive=false`;
-  const { data, error, mutate, isValidating } = useSWR<{
+  const activeVisitUrlSuffix = `?patient=${patientUuid}&v=${defaultVisitCustomRepresentation}&includeInactive=false`;
+  const retrospectiveVisitUrlSuffix = `/${retrospectiveVisitUuid}`;
+
+  const {
+    data: activeData,
+    error: activeError,
+    mutate: activeMutate,
+    isValidating: activeIsValidating,
+  } = useSWR<{
     data: Visit | { results: Array<Visit> };
   }>(
-    patientUuid ? `/ws/rest/v1/visit${visitGetUrlSuffix}` : null,
+    patientUuid ? `/ws/rest/v1/visit${activeVisitUrlSuffix}` : null,
     openmrsFetch
   );
 
-  const currentVisit = useMemo(
+  const {
+    data: retroData,
+    error: retroError,
+    mutate: retroMutate,
+    isValidating: retroIsValidating,
+  } = useSWR<{
+    data: Visit | { results: Array<Visit> };
+  }>(
+    patientUuid && retrospectiveVisitUuid
+      ? `/ws/rest/v1/visit${retrospectiveVisitUrlSuffix}`
+      : null,
+    openmrsFetch
+  );
+
+  const activeVisit = useMemo(
     () =>
-      retrospectiveVisitUuid
-        ? data?.data
-        : data?.data.results.find((visit) => visit.stopDatetime === null) ??
-          null,
-    [data]
+      activeData?.data.results.find((visit) => visit.stopDatetime === null) ??
+      null,
+    [activeData]
+  );
+
+  const currentVisit = useMemo(
+    () => (retrospectiveVisitUuid ? retroData?.data : activeVisit ?? null),
+    [retroData, activeVisit, retrospectiveVisitUuid]
   );
 
   return {
-    error,
-    mutate,
-    isValidating,
+    error: activeError || retroError,
+    mutate: () => {
+      activeMutate();
+      retroMutate();
+    },
+    isValidating: activeIsValidating || retroIsValidating,
+    activeVisit,
     currentVisit,
-    isRetrospective: Boolean(retrospectiveVisitUuid),
-    isLoading: !data && !error,
+    currentVisitIsRetrospective: Boolean(retrospectiveVisitUuid),
+    isLoading: Boolean(
+      (!activeData || (retrospectiveVisitUuid && !retroData)) &&
+        (!activeError || !retroError)
+    ),
   };
 }

package/src/createUseStore.ts

@@ -1,49 +0,0 @@
-/** @module @category Store */
-import { useEffect, useMemo, useState } from "react";
-import type { StoreApi } from "zustand";
-
-export type Actions = Function | Record<string, Function>;
-export type BoundActions = { [key: string]: (...args: any[]) => void };
-
-function bindActions<T>(store: StoreApi<T>, actions: Actions): BoundActions {
-  if (typeof actions == "function") {
-    actions = actions(store);
-  }
-
-  const bound = {};
-
-  for (let i in actions) {
-    bound[i] = () => {
-      const args = arguments;
-      store.setState((state) => {
-        let _args = [state];
-        for (let i = 0; i < args.length; i++) {
-          _args.push(args[i]);
-        }
-
-        return actions[i](_args);
-      });
-    };
-  }
-
-  return bound;
-}
-
-/** Avoid this; generally prefer to have clients use `useStore(yourStore)` */
-export function createUseStore<T>(store: StoreApi<T>) {
-  function useStore(): T;
-  function useStore(actions: Actions): T & BoundActions;
-  function useStore(actions?: Actions): T & BoundActions;
-  function useStore(actions?: Actions) {
-    const [state, set] = useState(store.getState());
-    useEffect(() => store.subscribe((state) => set(state)), []);
-    let boundActions: BoundActions = useMemo(
-      () => (actions ? bindActions(store, actions) : {}),
-      [actions]
-    );
-
-    return { ...state, ...boundActions };
-  }
-
-  return useStore;
-}