@openmrs/esm-react-utils 10.0.1-pre.5263 → 10.0.1-pre.5295

package/src/Extension.tsx

@@ -21,72 +21,128 @@ export const Extension: React.FC<ExtensionProps> = ({ state, children, ...divPro
   const { extension } = useContext(ComponentContext);
   const parcel = useRef<Parcel | null>(null);
   const updatePromise = useRef<Promise<void>>(Promise.resolve());
+  const isUnmounted = useRef(false);
+  const isRendering = useRef(false);
+  const latestState = useRef(state);
 
-  const ref = useCallback((node: HTMLDivElement) => {
+  // Takes the parcel to tear down rather than reading `parcel.current`, which can be reassigned
+  // between scheduling this and running it.
+  const unmountParcel = useCallback((target: Parcel | null) => {
+    if (!target) {
+      return;
+    }
+
+    const unmountWhenMounted = () => {
+      if (target.getStatus() === 'MOUNTED') {
+        target.unmount();
+      }
+    };
+
+    switch (target.getStatus()) {
+      case 'MOUNTED':
+        target.unmount();
+        break;
+      case 'UPDATING':
+        // The rejection is reported by whoever owns `updatePromise`; here it only matters that a
+        // failed update still runs the teardown, or the parcel is left broken and mounted.
+        updatePromise.current?.then(unmountWhenMounted, unmountWhenMounted);
+        break;
+      default:
+        // Any other status: the parcel either hasn't finished coming up or is already gone.
+        // `mountPromise` has settled or will, and `unmountWhenMounted` re-checks the status.
+        target.mountPromise.then(unmountWhenMounted, () => {});
+    }
+  }, []);
+
+  const applyUpdate = useCallback((target: Parcel, nextState: ExtensionProps['state']) => {
+    if (!target.update || target.getStatus() === 'UNMOUNTING') {
+      return;
+    }
+
+    // Every later update chains onto this promise, so it has to settle even when an update fails.
+    updatePromise.current = Promise.all([target.mountPromise, updatePromise.current])
+      .then(() => {
+        if (parcel.current?.getStatus() === 'MOUNTED' && parcel.current.update) {
+          return parcel.current.update({ ...nextState });
+        }
+      })
+      .catch((err) => {
+        // A parcel torn down while its update was in flight rejects, and that race is expected.
+        // We use the status to distinguish reject reasons as the message isn't reliable
+        const status = parcel.current?.getStatus();
+
+        if (status !== 'UNMOUNTING' && status !== 'NOT_MOUNTED' && status !== 'UNLOADING') {
+          console.error(`The extension '${extension?.extensionId}' failed to update`, err);
+        }
+      });
+  }, []);
+
+  const ref = useCallback((node: HTMLDivElement | null) => {
+    // React detaches a ref by calling it with null. If we render something in response to this,
+    // React ignores it and we're left tracking a parcel with no visible DOM, so skip conditions
+    // we can't handle.
     if (
-      extension?.extensionSlotName &&
-      extension.extensionSlotModuleName &&
-      extension.extensionSlotModuleName &&
-      !parcel.current
+      !node ||
+      parcel.current ||
+      isRendering.current ||
+      !extension?.extensionSlotName ||
+      !extension.extensionSlotModuleName
     ) {
-      renderExtension(
-        node,
-        extension.extensionSlotName,
-        extension.extensionSlotModuleName,
-        extension.extensionId,
-        undefined,
-        state,
-      ).then((newParcel: Parcel) => {
-        parcel.current = newParcel;
-      });
+      return;
     }
+
+    isRendering.current = true;
+
+    renderExtension(
+      node,
+      extension.extensionSlotName,
+      extension.extensionSlotModuleName,
+      extension.extensionId,
+      undefined,
+      state,
+    ).then(
+      (newParcel: Parcel | null) => {
+        isRendering.current = false;
+        parcel.current = newParcel;
+
+        // Loading an extension's bundle can outlast the component that asked for it: the cleanup
+        // effect has already run and saw no parcel, so teardown has to happen here instead, or the
+        // parcel mounts into a detached node and its rendering record outlives the page.
+        if (isUnmounted.current) {
+          unmountParcel(newParcel);
+          return;
+        }
+
+        // Ensure we update the state of the parcel to the latest version we've received
+        if (newParcel && latestState.current !== state) {
+          applyUpdate(newParcel, latestState.current);
+        }
+      },
+      // Cleared so a later reattach can try again; `renderExtension` reports its own failures.
+      () => {
+        isRendering.current = false;
+      },
+    );
   }, []);
 
   useEffect(() => {
+    // Reset on every run, not just the first: StrictMode mounts, tears down and mounts again, so
+    // a flag only ever set by the cleanup would still read "unmounted" for the live component.
+    isUnmounted.current = false;
+
     return () => {
-      if (parcel && parcel.current) {
-        const status = parcel.current.getStatus();
-        switch (status) {
-          case 'MOUNTING':
-            parcel.current.mountPromise.then(() => {
-              if (parcel.current?.getStatus() === 'MOUNTED') {
-                parcel.current.unmount();
-              }
-            });
-            break;
-          case 'MOUNTED':
-            parcel.current.unmount();
-            break;
-          case 'UPDATING':
-            if (updatePromise.current) {
-              updatePromise.current.then(() => {
-                if (parcel.current?.getStatus() === 'MOUNTED') {
-                  parcel.current.unmount();
-                }
-              });
-            }
-        }
-      }
+      isUnmounted.current = true;
+      unmountParcel(parcel.current);
     };
   }, []);
 
   useEffect(() => {
-    if (parcel.current && parcel.current.update && parcel.current.getStatus() !== 'UNMOUNTING') {
-      Promise.all([parcel.current.mountPromise, updatePromise.current]).then(() => {
-        if (parcel?.current?.getStatus() === 'MOUNTED' && parcel.current.update) {
-          updatePromise.current = parcel.current.update({ ...state }).catch((err) => {
-            // if we were trying to update but the component was unmounted
-            // while this was happening, ignore the error
-            if (
-              !(err instanceof Error) ||
-              !err.message.includes('minified message #32') ||
-              parcel.current?.getStatus() === 'MOUNTED'
-            ) {
-              throw err;
-            }
-          });
-        }
-      });
+    // Recorded before the parcel is checked, so that a state that arrives before there is a parcel
+    // to receive it is still the one applied once there is.
+    latestState.current = state;
+
+    if (parcel.current) {
+      applyUpdate(parcel.current, state);
     }
   }, [state]);
 

package/src/extensions.test.tsx

@@ -7,6 +7,7 @@ import { act, render, screen, waitFor, within } from '@testing-library/react';
 import { registerFeatureFlag, setFeatureFlag } from '@openmrs/esm-feature-flags';
 import {
   attach,
+  getExtensionRenderingsStore,
   getExtensionNameFromId,
   registerExtension,
   updateInternalExtensionStore,
@@ -57,6 +58,69 @@ describe('ExtensionSlot, Extension, and useExtensionSlotMeta', () => {
     expect(screen.getByText(/English/)).toHaveTextContent('English?');
   });
 
+  it('Extension reports a failed update instead of rejecting silently', async () => {
+    const user = userEvent.setup();
+    const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {});
+    const delivered: Array<number> = [];
+    let failNextUpdate = true;
+
+    registerExtension({
+      name: 'Flaky',
+      moduleName: 'esm-flaky-app',
+      meta: {},
+      load: async () => ({
+        bootstrap: async () => {},
+        mount: async (props: any) => {
+          props.domElement.textContent = 'flaky extension';
+        },
+        unmount: async (props: any) => {
+          props.domElement.textContent = '';
+        },
+        update: async (props: any) => {
+          if (failNextUpdate) {
+            failNextUpdate = false;
+            throw new Error('update blew up');
+          }
+
+          delivered.push(props.value);
+        },
+      }),
+    });
+    attach('FlakyBox', 'Flaky');
+
+    const App = openmrsComponentDecorator({
+      moduleName: 'esm-flaky-app',
+      featureName: 'Flaky',
+      disableTranslations: true,
+    })(() => {
+      const [value, next] = useReducer((value: number) => value + 1, 1);
+
+      return (
+        <div>
+          <ExtensionSlot name="FlakyBox" state={{ value }} />
+          <button onClick={next}>Next</button>
+        </div>
+      );
+    });
+
+    render(<App />);
+    expect(await screen.findByText('flaky extension')).toBeInTheDocument();
+
+    // The first of these fails, which makes single-spa hard-fail the parcel, so no later update
+    // reaches the extension. What must not happen is the failure going unreported and the promise
+    // chain being left rejected, which used to produce an unhandled rejection per later change.
+    await user.click(screen.getByText('Next'));
+    await user.click(screen.getByText('Next'));
+    await user.click(screen.getByText('Next'));
+
+    await waitFor(() =>
+      expect(consoleError).toHaveBeenCalledWith("The extension 'Flaky' failed to update", expect.any(Error)),
+    );
+    expect(consoleError).toHaveBeenCalledTimes(1);
+    expect(delivered).toEqual([]);
+    consoleError.mockRestore();
+  });
+
   it('Extension receives state changes (using <Extension>)', async () => {
     const user = userEvent.setup();
 
@@ -281,6 +345,54 @@ describe('ExtensionSlot, Extension, and useExtensionSlotMeta', () => {
   });
 });
 
+describe('Extension teardown', () => {
+  beforeEach(() => {
+    updateInternalExtensionStore(() => ({ slots: {}, extensions: {} }));
+    getExtensionRenderingsStore().setState({ renderings: new Map() });
+  });
+
+  it('releases the rendering when the slot unmounts while the bundle is still loading', async () => {
+    const consoleWarn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    let releaseLoad = () => {};
+    const loadGate = new Promise<void>((resolve) => (releaseLoad = resolve));
+    const lifecycle = getSyncLifecycle(() => <div>Fred</div>, {
+      moduleName: 'esm-flintstone',
+      featureName: 'Flintstone',
+      disableTranslations: true,
+    });
+
+    registerExtension({
+      name: 'Fred',
+      moduleName: 'esm-flintstone',
+      load: async () => {
+        await loadGate;
+        return lifecycle();
+      },
+      meta: {},
+    });
+    attach('Box', 'Fred');
+
+    const App = openmrsComponentDecorator({
+      moduleName: 'esm-flintstone',
+      featureName: 'Flintstone',
+      disableTranslations: true,
+    })(() => <ExtensionSlot name="Box" />);
+
+    const { unmount } = render(<App />);
+    await act(async () => {});
+    expect(getExtensionRenderingsStore().getState().renderings.size).toBe(1);
+
+    unmount();
+    releaseLoad();
+
+    await waitFor(() => expect(getExtensionRenderingsStore().getState().renderings.size).toBe(0));
+    // React detaches the ref by calling it with `null`; taking that for a render request starts a
+    // second render that resolves to null and clears the parcel still coming up.
+    expect(consoleWarn).not.toHaveBeenCalledWith(expect.stringContaining('no DOM element was available'));
+    consoleWarn.mockRestore();
+  });
+});
+
 function registerSimpleExtension(
   name: string,
   moduleName: string,

package/src/index.ts

@@ -10,6 +10,8 @@ export * from './useAbortController';
 export * from './useAppContext';
 export * from './useAssignedExtensionIds';
 export * from './useAssignedExtensions';
+export * from './useCandidateExtensions';
+export * from './useShallowStableValue';
 export * from './useAttachments';
 export * from './useBodyScrollLock';
 export * from './useConfig';

package/src/useAssignedExtensionIds.ts

@@ -1,26 +1,16 @@
 /** @module @category Extension */
-import { useEffect, useState } from 'react';
-import { getExtensionStore } from '@openmrs/esm-extensions';
-import { isEqual } from 'lodash-es';
+import { useMemo } from 'react';
+import { useAssignedExtensions } from './useAssignedExtensions';
 
 /**
  * Gets the assigned extension ids for a given extension slot name.
- * Does not consider if offline or online.
+ *
  * @param slotName The name of the slot to get the assigned IDs for.
  *
  * @deprecated Use `useAssignedExtensions`
  */
 export function useAssignedExtensionIds(slotName: string) {
-  const [ids, setIds] = useState<Array<string>>([]);
-
-  useEffect(() => {
-    return getExtensionStore().subscribe((state) => {
-      const newIds = state.slots[slotName]?.assignedExtensions.map((e) => e.id) ?? [];
-      if (!isEqual(newIds, ids)) {
-        setIds(newIds);
-      }
-    });
-  }, []);
+  const assignedExtensions = useAssignedExtensions(slotName);
 
-  return ids;
+  return useMemo(() => assignedExtensions.map((extension) => extension.id), [assignedExtensions]);
 }

package/src/useAssignedExtensions.ts

@@ -1,11 +1,38 @@
 /** @module @category Extension */
+import { useMemo } from 'react';
+import { sessionStore, type SessionStore } from '@openmrs/esm-api';
+import { type ExtensionSlotCustomState, getAssignedExtensions } from '@openmrs/esm-extensions';
+import { useShallowStableValue } from './useShallowStableValue';
 import { useExtensionSlotStore } from './useExtensionSlotStore';
+import { useStore } from './useStore';
+
+const selectSession = (state: SessionStore) => state.session;
 
 /**
  * Gets the assigned extensions for a given extension slot name.
+ *
+ * The reactive form of `getAssignedExtensions`, and it answers the same thing: display conditions
+ * are always applied, so the result is what should actually be displayed. Pass `state` whenever you
+ * know it: the same slot can be rendered in several places at once with different state, so
+ * conditions are resolved against the state of this rendering. Omitting it resolves them against
+ * the session alone, hiding any extension whose condition depends on state.
+ *
+ * The returned array is a copy, so sorting or filtering it in place can't corrupt the extension
+ * store. Its reference is stable for as long as the slot's extensions, the state and the session are.
+ *
  * @param slotName The name of the slot to get the assigned extensions for.
+ * @param state The state of this rendering of the slot.
  */
-export function useAssignedExtensions(slotName: string) {
-  const slotStore = useExtensionSlotStore(slotName);
-  return slotStore?.assignedExtensions ?? [];
+export function useAssignedExtensions(slotName: string, state?: ExtensionSlotCustomState) {
+  // Subscribes so that this re-runs when the slot's extensions change; `getAssignedExtensions` reads
+  // the same store, so the value below is what it is about to return.
+  const { candidateExtensions } = useExtensionSlotStore(slotName);
+  // Display conditions may refer to `session`, so they have to be re-evaluated when it changes.
+  const session = useStore(sessionStore, selectSession);
+  const stableState = useShallowStableValue(state);
+
+  return useMemo(
+    () => getAssignedExtensions(slotName, stableState),
+    [slotName, stableState, session, candidateExtensions],
+  );
 }

package/src/useCandidateExtensions.ts

@@ -0,0 +1,15 @@
+/** @module @category Extension */
+import { useExtensionSlotStore } from './useExtensionSlotStore';
+
+/**
+ * The reactive form of `getCandidateExtensions`: everything assigned to a slot, with no display
+ * condition evaluated. Intended for tools that present a slot's configuration rather than render it.
+ *
+ * Use {@link useAssignedExtensions} to decide what to display.
+ *
+ * @param slotName The name of the slot to get the candidate extensions for.
+ * @internal
+ */
+export function useCandidateExtensions(slotName: string) {
+  return useExtensionSlotStore(slotName).candidateExtensions;
+}

package/src/useExtensionSlot.ts

@@ -1,33 +1,23 @@
-import { useContext, useEffect, useRef } from 'react';
-import {
-  type ExtensionSlotCustomState,
-  registerExtensionSlot,
-  updateExtensionSlotState,
-} from '@openmrs/esm-extensions';
+import { useContext, useEffect } from 'react';
+import { type ExtensionSlotCustomState, registerExtensionSlot } from '@openmrs/esm-extensions';
 import { ComponentContext } from './ComponentContext';
 import { useAssignedExtensions } from './useAssignedExtensions';
 
 /** @internal */
 export function useExtensionSlot(slotName: string, state?: ExtensionSlotCustomState) {
   const { moduleName } = useContext(ComponentContext);
-  const isInitialRender = useRef(true);
 
   if (!moduleName) {
     throw Error('ComponentContext has not been provided. This should come from @openmrs/esm-react-utils.');
   }
 
   useEffect(() => {
-    registerExtensionSlot(moduleName, slotName, state);
-    isInitialRender.current = false;
-  }, []);
+    registerExtensionSlot(moduleName, slotName);
+  }, [moduleName, slotName]);
 
-  useEffect(() => {
-    if (!isInitialRender.current) {
-      updateExtensionSlotState(slotName, state);
-    }
-  }, [slotName, state]);
-
-  const extensions = useAssignedExtensions(slotName);
+  // `state` must be local to the rendering rather than written to the store as state is
+  // render-specific
+  const extensions = useAssignedExtensions(slotName, state);
 
   return {
     extensions,

package/src/useExtensionSlotStore.ts

@@ -1,6 +1,26 @@
 /** @module @category Extension */
-import { type ExtensionSlotState, type ExtensionStore, getExtensionStore } from '@openmrs/esm-extensions';
+import { useCallback } from 'react';
+import {
+  type AssignedExtension,
+  type ExtensionSlotState,
+  type ExtensionStore,
+  getExtensionStore,
+} from '@openmrs/esm-extensions';
 import { useStore } from './useStore';
 
-export const useExtensionSlotStore = (slot: string) =>
-  useStore<ExtensionStore, ExtensionSlotState>(getExtensionStore(), (state) => state.slots?.[slot]);
+/**
+ * Stands in for a slot that has not been registered or attached to. Shared rather than built per
+ * call, so the snapshot stays reference-stable across renders — and frozen because that sharing
+ * means an in-place sort or push would otherwise corrupt every unregistered slot in the page.
+ */
+const emptyCandidates: Array<AssignedExtension> = [];
+Object.freeze(emptyCandidates);
+
+const emptySlotState: ExtensionSlotState = { candidateExtensions: emptyCandidates };
+Object.freeze(emptySlotState);
+
+export const useExtensionSlotStore = (slot: string) => {
+  // Memoized so that `useStore`'s snapshot function is stable across renders.
+  const select = useCallback((state: ExtensionStore) => state.slots?.[slot] ?? emptySlotState, [slot]);
+  return useStore<ExtensionStore, ExtensionSlotState>(getExtensionStore(), select);
+};

package/src/useShallowStableValue.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it } from 'vitest';
+import { renderHook } from '@testing-library/react';
+import { useShallowStableValue } from './useShallowStableValue';
+
+describe('useShallowStableValue', () => {
+  it('keeps its reference across an equal object literal', () => {
+    const { result, rerender } = renderHook(({ value }) => useShallowStableValue(value), {
+      initialProps: { value: { patientUuid: 'abc' } },
+    });
+    const first = result.current;
+
+    rerender({ value: { patientUuid: 'abc' } });
+
+    expect(result.current).toBe(first);
+  });
+
+  it('takes the new reference when a value changes', () => {
+    const { result, rerender } = renderHook(({ value }) => useShallowStableValue(value), {
+      initialProps: { value: { patientUuid: 'abc' } },
+    });
+    const first = result.current;
+    const next = { patientUuid: 'def' };
+
+    rerender({ value: next });
+
+    expect(result.current).not.toBe(first);
+    expect(result.current).toBe(next);
+  });
+
+  it('takes the new reference when a key is added or removed', () => {
+    const { result, rerender } = renderHook(({ value }) => useShallowStableValue(value), {
+      initialProps: { value: { a: 1 } as Record<string, number> },
+    });
+    const first = result.current;
+
+    rerender({ value: { a: 1, b: 2 } });
+    expect(result.current).not.toBe(first);
+
+    const both = result.current;
+    rerender({ value: { a: 1 } });
+    expect(result.current).not.toBe(both);
+  });
+
+  it('returns the latest of two equal values rather than the first one it ever saw', () => {
+    const { result, rerender } = renderHook(({ value }) => useShallowStableValue(value), {
+      initialProps: { value: { n: 1 } },
+    });
+    const first = result.current;
+
+    rerender({ value: { n: 2 } });
+    const third = { n: 1 };
+    rerender({ value: third });
+
+    // Equal to the first value, but the run of equal values was broken, so it is a new reference.
+    expect(result.current).toBe(third);
+    expect(result.current).not.toBe(first);
+  });
+
+  it('compares only one level deep', () => {
+    const { result, rerender } = renderHook(({ value }) => useShallowStableValue(value), {
+      initialProps: { value: { patient: { uuid: 'abc' } } },
+    });
+    const first = result.current;
+
+    rerender({ value: { patient: { uuid: 'abc' } } });
+
+    expect(result.current).not.toBe(first);
+  });
+});

package/src/useShallowStableValue.ts

@@ -0,0 +1,24 @@
+/** @module @category Utility */
+import { useRef } from 'react';
+import { shallowEqual } from '@openmrs/esm-utils';
+
+/**
+ * Returns `value` with a reference that only changes when its contents do, so that it can be used
+ * as a dependency of `useMemo`, `useEffect` and friends.
+ *
+ * This exists for props that are almost always written as object literals — `state={{ patientUuid }}`
+ * — which get a new identity on every render while meaning the same thing. Comparison is shallow,
+ * so a value nested more than one level deep still reads as a change.
+ *
+ * @param value The value to stabilize
+ * @returns `value`, or the last value this hook returned if the two are shallowly equal
+ */
+export function useShallowStableValue<T>(value: T): T {
+  const stable = useRef(value);
+
+  if (!shallowEqual(stable.current, value)) {
+    stable.current = value;
+  }
+
+  return stable.current;
+}

package/src/useStore.test.ts

@@ -1,3 +1,4 @@
+import React from 'react';
 import { describe, expect, it } from 'vitest';
 import { act, renderHook } from '@testing-library/react';
 import { createGlobalStore } from '@openmrs/esm-state';
@@ -25,6 +26,44 @@ describe('useStore', () => {
   });
 });
 
+describe('useStore reference stability', () => {
+  it('returns the store state itself when there are no actions to merge in', () => {
+    const store = createGlobalStore('stability-plain', { renderings: new Map<string, number>() });
+    const { result, rerender } = renderHook(() => useStore(store));
+
+    // Not a copy: consumers of the extension renderings store depend on this, because the map
+    // inside is mutated in place and only the state object around it changes identity.
+    expect(result.current).toBe(store.getState());
+
+    const before = result.current;
+    rerender();
+    expect(result.current).toBe(before);
+  });
+
+  it('keeps its reference across an unrelated re-render, so it can be a memo dependency', () => {
+    const store = createGlobalStore('stability-memo', { a: 1, b: 2 });
+    let memoRuns = 0;
+
+    const { result, rerender } = renderHook(() => {
+      const state = useStore(store);
+
+      const derived = React.useMemo(() => ++memoRuns, [state]);
+      return derived;
+    });
+
+    expect(memoRuns).toBe(1);
+    rerender();
+    expect(memoRuns).toBe(1);
+
+    act(() => {
+      store.setState({ a: 2 });
+    });
+
+    expect(memoRuns).toBe(2);
+    expect(result.current).toBe(2);
+  });
+});
+
 describe('useStoreWithActions', () => {
   it('should correctly bind actions', () => {
     const store = createGlobalStore('counter', { count: 0 });