@openmrs/esm-react-utils 9.0.3-pre.4556 → 9.0.3-pre.4622

package/.turbo/turbo-build.log

@@ -1,3 +1,3 @@
-[0] Successfully compiled: 53 files with swc (162.43ms)
+[0] Successfully compiled: 53 files with swc (168.97ms)
 [0] swc --strip-leading-paths src -d dist exited with code 0
 [1] tsc --project tsconfig.build.json exited with code 0

package/dist/useAppContext.d.ts

@@ -17,6 +17,37 @@
  *
  * @typeParam T The type of the value stored in the namespace
  * @param namespace The namespace to load properties from
+ * @returns The current value registered under `namespace`, or `undefined` when the namespace has not
+ * yet been registered, was unregistered (e.g. the owning component unmounted), or is a blank string.
+ * Consumers should handle the `undefined` case explicitly rather than defaulting to `{}`, since an
+ * empty-object default can mask a genuinely missing namespace and hide bugs.
  */
 export declare function useAppContext<T extends NonNullable<object> = NonNullable<object>>(namespace: string): Readonly<T> | undefined;
+/**
+ * This hook is used to access a namespace within the overall AppContext, so that a component can
+ * use any shared contextual values. A selector may be provided to further restrict the properties
+ * returned from the namespace.
+ *
+ * @example
+ * ```ts
+ * // load a full namespace
+ * const patientContext = useAppContext<PatientContext>('patient');
+ * ```
+ *
+ * @example
+ * ```ts
+ * // loads part of a namespace
+ * const patientName = useAppContext<PatientContext, string | undefined>('patient', (state) => state.display);
+ * ```
+ *
+ * @typeParam T The type of the value stored in the namespace
+ * @typeParam U The return type of this hook which is mostly relevant when using a selector
+ * @param namespace The namespace to load properties from
+ * @param selector An optional function which extracts the relevant part of the state
+ * @returns The selected value, or `undefined` when the namespace has not yet been registered, was
+ * unregistered (e.g. the owning component unmounted), or is a blank string. Consumers should handle
+ * the `undefined` case explicitly rather than defaulting to `{}`, since an empty-object default can
+ * mask a genuinely missing namespace and hide bugs.
+ */
+export declare function useAppContext<T extends NonNullable<object> = NonNullable<object>, U = T>(namespace: string, selector: (state: Readonly<T> | null) => Readonly<U>): Readonly<U> | undefined;
 //# sourceMappingURL=useAppContext.d.ts.map

package/dist/useAppContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useAppContext.d.ts","sourceRoot":"","sources":["../src/useAppContext.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,WAAW,CAAC,MAAM,CAAC,GAAG,WAAW,CAAC,MAAM,CAAC,EAC/E,SAAS,EAAE,MAAM,GAChB,QAAQ,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC"}
+{"version":3,"file":"useAppContext.d.ts","sourceRoot":"","sources":["../src/useAppContext.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,WAAW,CAAC,MAAM,CAAC,GAAG,WAAW,CAAC,MAAM,CAAC,EAC/E,SAAS,EAAE,MAAM,GAChB,QAAQ,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC;AAE3B;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,WAAW,CAAC,MAAM,CAAC,GAAG,WAAW,CAAC,MAAM,CAAC,EAAE,CAAC,GAAG,CAAC,EACtF,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,GACnD,QAAQ,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC"}

package/dist/useAppContext.js

@@ -1,31 +1,19 @@
 /** @module @category Context */ import { useEffect, useState } from "react";
-import { subscribeToContext } from "@openmrs/esm-context";
+import { getContext, subscribeToContext } from "@openmrs/esm-context";
 import { shallowEqual } from "@openmrs/esm-utils";
-/**
- * This hook is used to access a namespace within the overall AppContext, so that a component can
- * use any shared contextual values. A selector may be provided to further restrict the properties
- * returned from the namespace.
- *
- * @example
- * ```ts
- * // load a full namespace
- * const patientContext = useAppContext<PatientContext>('patient');
- * ```
- *
- * @example
- * ```ts
- * // loads part of a namespace
- * const patientName = useAppContext<PatientContext, string | undefined>('patient', (state) => state.display);
- * ```
- *
- * @typeParam T The type of the value stored in the namespace
- * @typeParam U The return type of this hook which is mostly relevant when using a selector
- * @param namespace The namespace to load properties from
- * @param selector An optional function which extracts the relevant part of the state
- */ export function useAppContext(namespace, selector = (state)=>state ?? {}) {
-    const [value, setValue] = useState();
+export function useAppContext(namespace, selector = (state)=>state ?? {}) {
+    const [value, setValue] = useState(()=>{
+        if (isBlankNamespace(namespace)) {
+            return undefined;
+        }
+        const current = getContext(namespace);
+        if (current === null) {
+            return undefined;
+        }
+        return selector ? selector(current) : current;
+    });
     useEffect(()=>{
-        if (namespace === null || typeof namespace === 'undefined' || namespace.replace(' ', '') === '') {
+        if (isBlankNamespace(namespace)) {
             throw new Error(`The namespace supplied to useAppContext must be a non-empty string, but was "${namespace}".`);
         }
     }, [
@@ -33,13 +21,19 @@ import { shallowEqual } from "@openmrs/esm-utils";
     ]);
     useEffect(()=>{
         return subscribeToContext(namespace, (state)=>{
-            if (typeof state !== 'undefined') {
-                const newValue = selector ? selector(state) : state ?? {};
-                if (!shallowEqual(value, newValue)) {
-                    setValue(newValue);
-                }
+            if (state == null) {
+                setValue(undefined);
+                return;
             }
+            const newValue = selector ? selector(state) : state;
+            setValue((prev)=>shallowEqual(prev, newValue) ? prev : newValue);
         });
-    }, []);
+    }, [
+        namespace,
+        selector
+    ]);
     return value;
 }
+function isBlankNamespace(namespace) {
+    return typeof namespace !== 'string' || namespace.trim().length === 0;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openmrs/esm-react-utils",
-  "version": "9.0.3-pre.4556",
+  "version": "9.0.3-pre.4622",
   "license": "MPL-2.0",
   "description": "React utilities for OpenMRS.",
   "type": "module",
@@ -79,17 +79,17 @@
     "swr": "2.x"
   },
   "devDependencies": {
-    "@openmrs/esm-api": "9.0.3-pre.4556",
-    "@openmrs/esm-config": "9.0.3-pre.4556",
-    "@openmrs/esm-context": "9.0.3-pre.4556",
-    "@openmrs/esm-emr-api": "9.0.3-pre.4556",
-    "@openmrs/esm-error-handling": "9.0.3-pre.4556",
-    "@openmrs/esm-extensions": "9.0.3-pre.4556",
-    "@openmrs/esm-feature-flags": "9.0.3-pre.4556",
-    "@openmrs/esm-globals": "9.0.3-pre.4556",
-    "@openmrs/esm-navigation": "9.0.3-pre.4556",
-    "@openmrs/esm-state": "9.0.3-pre.4556",
-    "@openmrs/esm-utils": "9.0.3-pre.4556",
+    "@openmrs/esm-api": "9.0.3-pre.4622",
+    "@openmrs/esm-config": "9.0.3-pre.4622",
+    "@openmrs/esm-context": "9.0.3-pre.4622",
+    "@openmrs/esm-emr-api": "9.0.3-pre.4622",
+    "@openmrs/esm-error-handling": "9.0.3-pre.4622",
+    "@openmrs/esm-extensions": "9.0.3-pre.4622",
+    "@openmrs/esm-feature-flags": "9.0.3-pre.4622",
+    "@openmrs/esm-globals": "9.0.3-pre.4622",
+    "@openmrs/esm-navigation": "9.0.3-pre.4622",
+    "@openmrs/esm-state": "9.0.3-pre.4622",
+    "@openmrs/esm-utils": "9.0.3-pre.4622",
     "@swc/cli": "0.8.1",
     "@swc/core": "1.15.21",
     "@vitest/coverage-v8": "^4.1.2",

package/src/useAppContext.test.tsx

@@ -0,0 +1,104 @@
+import React from 'react';
+import { afterEach, describe, expect, it } from 'vitest';
+import { act, render, renderHook, screen } from '@testing-library/react';
+import { registerContext, unregisterContext, updateContext } from '@openmrs/esm-context';
+import { useAppContext } from './useAppContext';
+import { useDefineAppContext } from './useDefineAppContext';
+
+const namespace = 'test-context';
+
+interface TestContext {
+  value: string;
+  count: number;
+}
+
+afterEach(() => {
+  unregisterContext(namespace);
+});
+
+describe('useAppContext', () => {
+  it('returns undefined when the namespace is not registered', () => {
+    const { result } = renderHook(() => useAppContext<TestContext>(namespace));
+
+    expect(result.current).toBeUndefined();
+  });
+
+  it('returns the currently-registered value on the very first render', () => {
+    registerContext<TestContext>(namespace, { value: 'initial', count: 1 });
+
+    const { result } = renderHook(() => useAppContext<TestContext>(namespace));
+
+    expect(result.current).toEqual({ value: 'initial', count: 1 });
+  });
+
+  it('applies the selector on the first render', () => {
+    registerContext<TestContext>(namespace, { value: 'initial', count: 5 });
+
+    const { result } = renderHook(() => useAppContext<TestContext, number>(namespace, (state) => state?.count ?? 0));
+
+    expect(result.current).toBe(5);
+  });
+
+  it('exposes a sibling useDefineAppContext value to the consumer after effects flush', () => {
+    const Producer = () => {
+      useDefineAppContext<TestContext>(namespace, { value: 'from-producer', count: 42 });
+      return null;
+    };
+
+    const Consumer = () => {
+      const ctx = useAppContext<TestContext>(namespace);
+      return <div data-testid="consumer-value">{ctx ? `${ctx.value}:${ctx.count}` : 'UNDEFINED'}</div>;
+    };
+
+    render(
+      <>
+        <Producer />
+        <Consumer />
+      </>,
+    );
+
+    expect(screen.getByTestId('consumer-value')).toHaveTextContent('from-producer:42');
+  });
+
+  it('returns undefined (not {}) after the namespace owner unmounts (O3-4020 scenario)', () => {
+    // When the component that owns a namespace via useDefineAppContext
+    // unmounts while a consumer is still mounted, the consumer must observe
+    // undefined — not a frozen empty object that silently hides the absence.
+    const Producer = () => {
+      useDefineAppContext<TestContext>(namespace, { value: 'v', count: 1 });
+      return null;
+    };
+
+    const Consumer = () => {
+      const ctx = useAppContext<TestContext>(namespace);
+      return <div data-testid="consumer-value">{ctx ? `${ctx.value}:${ctx.count}` : 'UNDEFINED'}</div>;
+    };
+
+    const { rerender } = render(
+      <>
+        <Producer />
+        <Consumer />
+      </>,
+    );
+
+    expect(screen.getByTestId('consumer-value')).toHaveTextContent('v:1');
+
+    rerender(<Consumer />);
+
+    expect(screen.getByTestId('consumer-value')).toHaveTextContent('UNDEFINED');
+  });
+
+  it('re-applies the selector when the underlying context updates', () => {
+    registerContext<TestContext>(namespace, { value: 'a', count: 1 });
+
+    const { result } = renderHook(() => useAppContext<TestContext, number>(namespace, (state) => state?.count ?? -1));
+
+    expect(result.current).toBe(1);
+
+    act(() => {
+      updateContext<TestContext>(namespace, (state) => ({ ...state, count: 7 }));
+    });
+
+    expect(result.current).toBe(7);
+  });
+});

package/src/useAppContext.ts

@@ -1,6 +1,6 @@
 /** @module @category Context */
 import { useEffect, useState } from 'react';
-import { subscribeToContext } from '@openmrs/esm-context';
+import { getContext, subscribeToContext } from '@openmrs/esm-context';
 import { shallowEqual } from '@openmrs/esm-utils';
 
 /**
@@ -22,6 +22,10 @@ import { shallowEqual } from '@openmrs/esm-utils';
  *
  * @typeParam T The type of the value stored in the namespace
  * @param namespace The namespace to load properties from
+ * @returns The current value registered under `namespace`, or `undefined` when the namespace has not
+ * yet been registered, was unregistered (e.g. the owning component unmounted), or is a blank string.
+ * Consumers should handle the `undefined` case explicitly rather than defaulting to `{}`, since an
+ * empty-object default can mask a genuinely missing namespace and hide bugs.
  */
 export function useAppContext<T extends NonNullable<object> = NonNullable<object>>(
   namespace: string,
@@ -48,29 +52,51 @@ export function useAppContext<T extends NonNullable<object> = NonNullable<object
  * @typeParam U The return type of this hook which is mostly relevant when using a selector
  * @param namespace The namespace to load properties from
  * @param selector An optional function which extracts the relevant part of the state
+ * @returns The selected value, or `undefined` when the namespace has not yet been registered, was
+ * unregistered (e.g. the owning component unmounted), or is a blank string. Consumers should handle
+ * the `undefined` case explicitly rather than defaulting to `{}`, since an empty-object default can
+ * mask a genuinely missing namespace and hide bugs.
  */
+export function useAppContext<T extends NonNullable<object> = NonNullable<object>, U = T>(
+  namespace: string,
+  selector: (state: Readonly<T> | null) => Readonly<U>,
+): Readonly<U> | undefined;
+
 export function useAppContext<T extends NonNullable<object> = NonNullable<object>, U = T>(
   namespace: string,
   selector: (state: Readonly<T> | null) => Readonly<U> = (state) => (state ?? {}) as Readonly<U>,
 ): Readonly<U> | undefined {
-  const [value, setValue] = useState<Readonly<U>>();
+  const [value, setValue] = useState<Readonly<U> | undefined>(() => {
+    if (isBlankNamespace(namespace)) {
+      return undefined;
+    }
+    const current = getContext<T>(namespace);
+    if (current === null) {
+      return undefined;
+    }
+    return selector ? selector(current) : (current as unknown as Readonly<U>);
+  });
 
   useEffect(() => {
-    if (namespace === null || typeof namespace === 'undefined' || namespace.replace(' ', '') === '') {
+    if (isBlankNamespace(namespace)) {
       throw new Error(`The namespace supplied to useAppContext must be a non-empty string, but was "${namespace}".`);
     }
   }, [namespace]);
 
   useEffect(() => {
     return subscribeToContext<T>(namespace, (state) => {
-      if (typeof state !== 'undefined') {
-        const newValue = selector ? selector(state) : ((state ?? {}) as Readonly<U>);
-        if (!shallowEqual(value, newValue)) {
-          setValue(newValue);
-        }
+      if (state == null) {
+        setValue(undefined);
+        return;
       }
+      const newValue = selector ? selector(state) : (state as unknown as Readonly<U>);
+      setValue((prev) => (shallowEqual(prev, newValue) ? prev : newValue));
     });
-  }, []);
+  }, [namespace, selector]);
 
   return value;
 }
+
+function isBlankNamespace(namespace: unknown): boolean {
+  return typeof namespace !== 'string' || namespace.trim().length === 0;
+}