chore: add js docs for context mutator hook (#1045)

Minor refactors, but mostly adding js-doc after
#1031.

---------

Signed-off-by: Todd Baert <[email protected]>

Author: toddbaert

packages/react/src/provider/context.ts renamed to packages/react/src/common/context.ts

@@ -1,7 +1,7 @@
 import type { Client } from '@openfeature/web-sdk';
 import React from 'react';
-import type { NormalizedOptions, ReactFlagEvaluationOptions} from '../common/options';
-import { normalizeOptions } from '../common/options';
+import type { NormalizedOptions, ReactFlagEvaluationOptions} from '../common';
+import { normalizeOptions } from '../common';
 
 /**
  * The underlying React context.

packages/react/src/common/index.ts

@@ -0,0 +1,4 @@
+export * from './context';
+export * from './is-equal';
+export * from './options';
+export * from './suspense';

packages/react/src/context/index.ts

@@ -0,0 +1 @@
+export * from './use-context-mutator';

packages/react/src/context/use-context-mutator.ts

@@ -0,0 +1,51 @@
+import { useCallback, useContext, useRef } from 'react';
+import type { EvaluationContext } from '@openfeature/web-sdk';
+import { OpenFeature } from '@openfeature/web-sdk';
+import { Context } from '../common';
+
+export type ContextMutationOptions = {
+  /**
+   * Mutate the default context instead of the domain scoped context applied at the `<OpenFeatureProvider/>`.
+   * Note, if the `<OpenFeatureProvider/>` has no domain specified, the default is used.
+   * See the {@link https://openfeature.dev/docs/reference/technologies/client/web/#manage-evaluation-context-for-domains|documentation} for more information.
+   * @default false
+   */
+  defaultContext?: boolean;
+};
+
+export type ContextMutation = {
+  /**
+   * A function to set the desired context (see: {@link ContextMutationOptions} for details).
+   * There's generally no need to await the result of this function; flag evaluation hooks will re-render when the context is updated.
+   * This promise never rejects.
+   * @param updatedContext
+   * @returns Promise for awaiting the context update
+   */
+  setContext: (updatedContext: EvaluationContext) => Promise<void>;
+};
+
+/**
+ * Get function(s) for mutating the evaluation context associated with this domain, or the default context if `defaultContext: true`.
+ * See the {@link https://openfeature.dev/docs/reference/technologies/client/web/#targeting-and-context|documentation} for more information.
+ * @param {ContextMutationOptions} options options for the generated function
+ * @returns {ContextMutation} function(s) to mutate context
+ */
+export function useContextMutator(options: ContextMutationOptions = { defaultContext: false }): ContextMutation {
+    const { domain } = useContext(Context) || {};
+    const previousContext = useRef<null | EvaluationContext>(null);
+
+    const setContext = useCallback(async (updatedContext: EvaluationContext) => {
+        if (previousContext.current !== updatedContext) {
+            if (!domain || options?.defaultContext) {
+                OpenFeature.setContext(updatedContext);
+            } else {
+                OpenFeature.setContext(domain, updatedContext);
+            }
+            previousContext.current = updatedContext;
+        }
+    }, [domain]);
+
+    return {
+        setContext,
+    };
+}

packages/react/src/evaluation/use-feature-flag.ts

@@ -11,15 +11,12 @@ import {
   ProviderStatus,
 } from '@openfeature/web-sdk';
 import { useEffect, useRef, useState } from 'react';
-import type { ReactFlagEvaluationOptions} from '../common/options';
-import { DEFAULT_OPTIONS, normalizeOptions } from '../common/options';
-import { suspendUntilReady } from '../common/suspense';
-import { useProviderOptions } from '../provider/context';
+import type { ReactFlagEvaluationOptions} from '../common';
+import { DEFAULT_OPTIONS, isEqual, normalizeOptions, suspendUntilReady, useProviderOptions } from '../common';
 import { useOpenFeatureClient } from '../provider/use-open-feature-client';
 import { useOpenFeatureClientStatus } from '../provider/use-open-feature-client-status';
 import type { FlagQuery } from '../query';
 import { HookFlagQuery } from './hook-flag-query';
-import { isEqual } from '../common/is-equal';
 
 // This type is a bit wild-looking, but I think we need it.
 // We have to use the conditional, because otherwise useFlag('key', false) would return false, not boolean (too constrained).

packages/react/src/index.ts

@@ -1,5 +1,6 @@
 export * from './evaluation';
 export * from './query';
 export * from './provider';
+export * from './context';
 // re-export the web-sdk so consumers can access that API from the react-sdk
 export * from '@openfeature/web-sdk';

packages/react/src/provider/index.ts

@@ -2,4 +2,3 @@ export * from './provider';
 export * from './use-open-feature-client';
 export * from './use-when-provider-ready';
 export * from './test-provider';
-export * from './use-context-mutator';

packages/react/src/provider/provider.tsx

@@ -1,8 +1,8 @@
 import type { Client} from '@openfeature/web-sdk';
 import { OpenFeature } from '@openfeature/web-sdk';
 import * as React from 'react';
-import type { ReactFlagEvaluationOptions } from '../common/options';
-import { Context } from './context';
+import type { ReactFlagEvaluationOptions } from '../common';
+import { Context } from '../common';
 
 type ClientOrDomain =
   | {

packages/react/src/provider/test-provider.tsx

@@ -7,7 +7,7 @@ import {
   OpenFeature
 } from '@openfeature/web-sdk';
 import React from 'react';
-import type { NormalizedOptions } from '../common/options';
+import type { NormalizedOptions } from '../common';
 import { OpenFeatureProvider } from './provider';
 
 type FlagValueMap = { [flagKey: string]: JsonValue };
@@ -119,4 +119,4 @@ function mixInNoop(provider: Partial<Provider> = {}) {
     (provider.metadata as unknown) = { name: TEST_PROVIDER };
   }
   return provider;
-}
+}