@openfeature/react-sdk 1.0.2 → 1.2.0

package/LICENSE

@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2025 OpenFeature Maintainers
+   Copyright OpenFeature Maintainers
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

package/README.md

@@ -16,8 +16,8 @@
     <img alt="Specification" src="https://img.shields.io/static/v1?label=specification&message=v0.8.0&color=yellow&style=for-the-badge" />
   </a>
   <!-- x-release-please-start-version -->
-  <a href="https://github.com/open-feature/js-sdk/releases/tag/react-sdk-v1.0.2">
-    <img alt="Release" src="https://img.shields.io/static/v1?label=release&message=v1.0.2&color=blue&style=for-the-badge" />
+  <a href="https://github.com/open-feature/js-sdk/releases/tag/react-sdk-v1.2.0">
+    <img alt="Release" src="https://img.shields.io/static/v1?label=release&message=v1.2.0&color=blue&style=for-the-badge" />
   </a>
   <!-- x-release-please-end -->
   <br/>
@@ -50,6 +50,8 @@ In addition to the feature provided by the [web sdk](https://openfeature.dev/doc
   - [Usage](#usage)
     - [OpenFeatureProvider context provider](#openfeatureprovider-context-provider)
     - [Evaluation hooks](#evaluation-hooks)
+    - [Declarative components](#declarative-components)
+      - [FeatureFlag Component](#featureflag-component)
     - [Multiple Providers and Domains](#multiple-providers-and-domains)
     - [Re-rendering with Context Changes](#re-rendering-with-context-changes)
     - [Re-rendering with Flag Configuration Changes](#re-rendering-with-flag-configuration-changes)
@@ -87,8 +89,8 @@ yarn add @openfeature/react-sdk @openfeature/web-sdk @openfeature/core
 The following list contains the peer dependencies of `@openfeature/react-sdk`.
 See the [package.json](./package.json) for the required versions.
 
-* `@openfeature/web-sdk`
-* `react`
+- `@openfeature/web-sdk`
+- `react`
 
 ### Usage
 
@@ -108,13 +110,13 @@ const flagConfig = {
       on: true,
       off: false,
     },
-    defaultVariant: "on",
+    defaultVariant: 'on',
     contextEvaluator: (context: EvaluationContext) => {
       if (context.silly) {
         return 'on';
       }
-      return 'off'
-    }
+      return 'off';
+    },
   },
 };
 
@@ -146,7 +148,7 @@ function Page() {
         {showNewMessage ? <p>Welcome to this OpenFeature-enabled React app!</p> : <p>Welcome to this React app.</p>}
       </header>
     </div>
-  )
+  );
 }
 ```
 
@@ -163,14 +165,71 @@ const value = useBooleanFlagValue('new-message', false);
 import { useBooleanFlagDetails } from '@openfeature/react-sdk';
 
 // "detailed" boolean flag evaluation
-const {
-  value,
-  variant,
-  reason,
-  flagMetadata
-} = useBooleanFlagDetails('new-message', false);
+const { value, variant, reason, flagMetadata } = useBooleanFlagDetails('new-message', false);
+```
+
+#### Declarative components
+
+The React SDK includes declarative components for feature flagging that provide a more JSX-native approach to conditional rendering.
+
+##### FeatureFlag Component
+
+The `FeatureFlag` component conditionally renders its children based on feature flag evaluation:
+
+```tsx
+import { FeatureFlag } from '@openfeature/react-sdk';
+
+function App() {
+  return (
+    <OpenFeatureProvider>
+      {/* Basic usage - renders children when flag is truthy */}
+      <FeatureFlag flagKey="new-feature" defaultValue={false}>
+        <NewFeatureComponent />
+      </FeatureFlag>
+
+      {/* Match specific values */}
+      <FeatureFlag flagKey="theme" matchValue="dark" defaultValue="light">
+        <DarkThemeStyles />
+      </FeatureFlag>
+
+      {/* Boolean flag with fallback */}
+      <FeatureFlag flagKey="premium-feature" matchValue={true} defaultValue={false} fallback={<UpgradePrompt />}>
+        <PremiumContent />
+      </FeatureFlag>
+
+      {/* Custom predicate function for complex matching */}
+      <FeatureFlag
+        flagKey="user-segment"
+        defaultValue=""
+        matchValue="beta"
+        // check if the actual flag value includes the match ('beta')
+        predicate={(expected, actual) => !!expected && actual.value.includes(expected)}
+      >
+        <BetaFeatures />
+      </FeatureFlag>
+
+      {/* Function as children for accessing flag details */}
+      <FeatureFlag flagKey="experiment" defaultValue="control" matchValue="beta">
+        {({ value, reason }) => (
+          <span>
+            value is {value}, reason is {reason?.toString()}
+          </span>
+        )}
+      </FeatureFlag>
+    </OpenFeatureProvider>
+  );
+}
 ```
 
+The `FeatureFlag` component supports the following props:
+
+- **`flagKey`** (required): The feature flag key to evaluate
+- **`defaultValue`** (required): Default value when the flag is not available
+- **`matchValue`** (required, except for boolean flags): Value to match against the flag value. By default, an optimized deep-comparison function is used.
+- **`predicate`** (optional): Custom function for matching logic that receives the expected value and evaluation details
+- **`children`**: Content to render when condition is met (can be JSX or a function receiving flag details)
+- **`fallback`** (optional): Content to render when condition is not met
+
 #### Multiple Providers and Domains
 
 Multiple providers can be used by passing a `domain` to the `OpenFeatureProvider`:
@@ -313,8 +372,8 @@ The [OpenFeature debounce hook](https://github.com/open-feature/js-sdk-contrib/t
 ### Testing
 
 The React SDK includes a built-in context provider for testing.
-This allows you to easily test components that use evaluation hooks, such as `useFlag`.
-If you try to test a component (in this case, `MyComponent`) which uses an evaluation hook, you might see an error message like:
+This allows you to easily test components that use evaluation hooks (such as `useFlag`) or declarative components (such as `FeatureFlag`).
+If you try to test a component (in this case, `MyComponent`) which uses feature flags, you might see an error message like:
 
 > No OpenFeature client available - components using OpenFeature must be wrapped with an `<OpenFeatureProvider>`.
 
@@ -335,6 +394,16 @@ If you'd like to control the values returned by the evaluation hooks, you can pa
 <OpenFeatureTestProvider flagValueMap={{ 'my-boolean-flag': true }}>
   <MyComponent />
 </OpenFeatureTestProvider>
+
+// testing declarative FeatureFlag components
+<OpenFeatureTestProvider flagValueMap={{ 'new-feature': true, 'theme': 'dark' }}>
+  <FeatureFlag flagKey="new-feature" defaultValue={false}>
+    <NewFeature />
+  </FeatureFlag>
+  <FeatureFlag flagKey="theme" matchValue="dark" defaultValue="light">
+    <DarkMode />
+  </FeatureFlag>
+</OpenFeatureTestProvider>
 ```
 
 Additionally, you can pass an artificial delay for the provider startup to test your suspense boundaries or loaders/spinners impacted by feature flags:
@@ -406,4 +475,4 @@ Avoid importing anything from `@openfeature/web-sdk` or `@openfeature/core`.
 
 ## Resources
 
- - [Example repo](https://github.com/open-feature/react-test-app)
+- [Example repo](https://github.com/open-feature/react-test-app)

package/dist/cjs/index.js

@@ -80,6 +80,7 @@ var __async = (__this, __arguments, generator) => {
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  FeatureFlag: () => FeatureFlag,
   OpenFeatureProvider: () => OpenFeatureProvider,
   OpenFeatureTestProvider: () => OpenFeatureTestProvider,
   useBooleanFlagDetails: () => useBooleanFlagDetails,
@@ -100,13 +101,18 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/declarative/FeatureFlag.tsx
+var import_react7 = __toESM(require("react"));
+
 // src/evaluation/use-feature-flag.ts
 var import_web_sdk5 = require("@openfeature/web-sdk");
 var import_react6 = require("react");
 
 // src/internal/context.ts
 var import_react = __toESM(require("react"));
-var Context = import_react.default.createContext(void 0);
+var Context = import_react.default.createContext(
+  void 0
+);
 function useProviderOptions() {
   const { options } = import_react.default.useContext(Context) || {};
   return normalizeOptions(options);
@@ -120,7 +126,7 @@ function isEqual(value, other) {
   if (typeof value !== typeof other) {
     return false;
   }
-  if (typeof value === "object" && value !== null && other !== null) {
+  if (typeof value === "object" && value !== null && typeof other === "object" && other !== null) {
     const valueKeys = Object.keys(value);
     const otherKeys = Object.keys(other);
     if (valueKeys.length !== otherKeys.length) {
@@ -242,8 +248,8 @@ var import_web_sdk2 = require("@openfeature/web-sdk");
 function useOpenFeatureClientStatus() {
   const client = useOpenFeatureClient();
   const [status, setStatus] = (0, import_react4.useState)(client.providerStatus);
-  const controller = new AbortController();
   (0, import_react4.useEffect)(() => {
+    const controller = new AbortController();
     const updateStatus = () => setStatus(client.providerStatus);
     client.addHandler(import_web_sdk2.ProviderEvents.ConfigurationChanged, updateStatus, { signal: controller.signal });
     client.addHandler(import_web_sdk2.ProviderEvents.ContextChanged, updateStatus, { signal: controller.signal });
@@ -266,7 +272,7 @@ function useOpenFeatureProvider() {
   if (!openFeatureContext) {
     throw new MissingContextError("No OpenFeature context available");
   }
-  return import_web_sdk3.OpenFeature.getProvider(openFeatureContext.domain);
+  return import_web_sdk3.OpenFeature.getProvider(openFeatureContext.client.metadata.domain);
 }
 
 // src/internal/hook-flag-query.ts
@@ -395,7 +401,7 @@ function attachHandlersAndResolve(flagKey, defaultValue, resolver, options) {
       return;
     }
     const newDetails = resolver(client).call(client, flagKey, defaultValue, options);
-    if (!isEqual(newDetails.value, evaluationDetails.value)) {
+    if (!isEqual(newDetails, evaluationDetails)) {
       setEvaluationDetails(newDetails);
     }
   }, [client, flagKey, defaultValue, options, resolver, evaluationDetails]);
@@ -405,7 +411,7 @@ function attachHandlersAndResolve(flagKey, defaultValue, resolver, options) {
   }, [evaluationDetails]);
   const updateEvaluationDetailsCallback = (0, import_react6.useCallback)(() => {
     const updatedEvaluationDetails = resolver(client).call(client, flagKey, defaultValue, options);
-    if (!isEqual(updatedEvaluationDetails.value, evaluationDetailsRef.current.value)) {
+    if (!isEqual(updatedEvaluationDetails, evaluationDetailsRef.current)) {
       setEvaluationDetails(updatedEvaluationDetails);
     }
   }, [client, flagKey, defaultValue, options, resolver]);
@@ -444,13 +450,51 @@ function attachHandlersAndResolve(flagKey, defaultValue, resolver, options) {
   return evaluationDetails;
 }
 
+// src/declarative/FeatureFlag.tsx
+function equals(expected, actual) {
+  return isEqual(expected, actual.value);
+}
+function FeatureFlag({
+  flagKey,
+  matchValue,
+  predicate,
+  defaultValue,
+  children,
+  evaluationOptions = {},
+  fallback = null
+}) {
+  const details = useFlag(flagKey, defaultValue, __spreadValues({
+    updateOnContextChanged: true
+  }, evaluationOptions));
+  if (details.reason === "ERROR") {
+    const fallbackNode2 = typeof fallback === "function" ? fallback(details.details) : fallback;
+    return /* @__PURE__ */ import_react7.default.createElement(import_react7.default.Fragment, null, fallbackNode2);
+  }
+  let shouldRender = false;
+  if (predicate) {
+    shouldRender = predicate(matchValue, details.details);
+  } else if (matchValue !== void 0) {
+    shouldRender = equals(matchValue, details.details);
+  } else if (details.type === "boolean") {
+    shouldRender = Boolean(details.value);
+  } else {
+    shouldRender = false;
+  }
+  if (shouldRender) {
+    const childNode = typeof children === "function" ? children(details) : children;
+    return /* @__PURE__ */ import_react7.default.createElement(import_react7.default.Fragment, null, childNode);
+  }
+  const fallbackNode = typeof fallback === "function" ? fallback(details.details) : fallback;
+  return /* @__PURE__ */ import_react7.default.createElement(import_react7.default.Fragment, null, fallbackNode);
+}
+
 // src/provider/provider.tsx
 var import_web_sdk6 = require("@openfeature/web-sdk");
-var React5 = __toESM(require("react"));
+var React6 = __toESM(require("react"));
 function OpenFeatureProvider(_a) {
   var _b = _a, { client, domain, children } = _b, options = __objRest(_b, ["client", "domain", "children"]);
-  const stableClient = React5.useMemo(() => client || import_web_sdk6.OpenFeature.getClient(domain), [client, domain]);
-  return /* @__PURE__ */ React5.createElement(Context.Provider, { value: { client: stableClient, options, domain } }, children);
+  const stableClient = React6.useMemo(() => client || import_web_sdk6.OpenFeature.getClient(domain), [client, domain]);
+  return /* @__PURE__ */ React6.createElement(Context.Provider, { value: { client: stableClient, options } }, children);
 }
 
 // src/provider/use-when-provider-ready.ts
@@ -468,7 +512,7 @@ function useWhenProviderReady(options) {
 
 // src/provider/test-provider.tsx
 var import_web_sdk8 = require("@openfeature/web-sdk");
-var import_react7 = __toESM(require("react"));
+var import_react8 = __toESM(require("react"));
 var TEST_VARIANT = "test-variant";
 var TEST_PROVIDER = "test-provider";
 var TestProvider = class extends import_web_sdk8.InMemoryProvider {
@@ -508,10 +552,12 @@ function OpenFeatureTestProvider(testProviderOptions) {
   const { flagValueMap, provider } = testProviderOptions;
   const effectiveProvider = flagValueMap ? new TestProvider(flagValueMap, testProviderOptions.delayMs) : mixInNoop(provider) || import_web_sdk8.NOOP_PROVIDER;
   testProviderOptions.domain ? import_web_sdk8.OpenFeature.setProvider(testProviderOptions.domain, effectiveProvider) : import_web_sdk8.OpenFeature.setProvider(effectiveProvider);
-  return /* @__PURE__ */ import_react7.default.createElement(OpenFeatureProvider, __spreadProps(__spreadValues({}, testProviderOptions), { domain: testProviderOptions.domain }), testProviderOptions.children);
+  return /* @__PURE__ */ import_react8.default.createElement(OpenFeatureProvider, __spreadProps(__spreadValues({}, testProviderOptions), { domain: testProviderOptions.domain }), testProviderOptions.children);
 }
 function mixInNoop(provider = {}) {
-  for (const prop of Object.getOwnPropertyNames(Object.getPrototypeOf(import_web_sdk8.NOOP_PROVIDER)).filter((prop2) => prop2 !== "constructor")) {
+  for (const prop of Object.getOwnPropertyNames(Object.getPrototypeOf(import_web_sdk8.NOOP_PROVIDER)).filter(
+    (prop2) => prop2 !== "constructor"
+  )) {
     const patchedProvider = provider;
     if (!Object.getPrototypeOf(patchedProvider)[prop] && !patchedProvider[prop]) {
       patchedProvider[prop] = Object.getPrototypeOf(import_web_sdk8.NOOP_PROVIDER)[prop];
@@ -524,31 +570,50 @@ function mixInNoop(provider = {}) {
 }
 
 // src/context/use-context-mutator.ts
-var import_react8 = require("react");
+var import_react9 = require("react");
 var import_web_sdk9 = require("@openfeature/web-sdk");
 function useContextMutator(options = { defaultContext: false }) {
-  const { domain } = (0, import_react8.useContext)(Context) || {};
-  const previousContext = (0, import_react8.useRef)(null);
-  const setContext = (0, import_react8.useCallback)((updatedContext) => __async(null, null, function* () {
-    if (previousContext.current !== updatedContext) {
-      if (!domain || (options == null ? void 0 : options.defaultContext)) {
-        import_web_sdk9.OpenFeature.setContext(updatedContext);
-      } else {
-        import_web_sdk9.OpenFeature.setContext(domain, updatedContext);
+  const { client } = (0, import_react9.useContext)(Context) || {};
+  const domain = client == null ? void 0 : client.metadata.domain;
+  const [warned, setWarned] = (0, import_react9.useState)(false);
+  (0, import_react9.useEffect)(() => {
+    if (options.defaultContext || domain) {
+      if (warned) {
+        setWarned(false);
       }
-      previousContext.current = updatedContext;
+      return;
+    }
+    if (!warned) {
+      console.warn(
+        "[useContextMutator] No domain available from OpenFeature context; are you using <OpenFeatureProvider/>? setContext will mutate the default context, as if `defaultContext: true` were set. This may result in a thrown error in the future."
+      );
+      setWarned(true);
     }
-  }), [domain]);
+  }, [warned]);
+  const setContext = (0, import_react9.useCallback)(
+    (updatedContext) => __async(null, null, function* () {
+      const previousContext = import_web_sdk9.OpenFeature.getContext((options == null ? void 0 : options.defaultContext) ? void 0 : domain);
+      const resolvedContext = typeof updatedContext === "function" ? updatedContext(previousContext) : updatedContext;
+      if (previousContext !== resolvedContext) {
+        if (!domain || (options == null ? void 0 : options.defaultContext)) {
+          yield import_web_sdk9.OpenFeature.setContext(resolvedContext);
+        } else {
+          yield import_web_sdk9.OpenFeature.setContext(domain, resolvedContext);
+        }
+      }
+    }),
+    [domain, options == null ? void 0 : options.defaultContext]
+  );
   return {
     setContext
   };
 }
 
 // src/tracking/use-track.ts
-var import_react9 = require("react");
+var import_react10 = require("react");
 function useTrack() {
   const client = useOpenFeatureClient();
-  const track = (0, import_react9.useCallback)((trackingEventName, trackingEventDetails) => {
+  const track = (0, import_react10.useCallback)((trackingEventName, trackingEventDetails) => {
     client.track(trackingEventName, trackingEventDetails);
   }, []);
   return {