@openfeature/react-sdk 1.1.0 → 1.2.0

package/dist/types.d.ts

@@ -1,8 +1,56 @@
-import { FlagEvaluationOptions, FlagValue as FlagValue$1, JsonValue, EvaluationDetails as EvaluationDetails$1, Client, ProviderStatus, Provider, EvaluationContext, Tracking } from '@openfeature/web-sdk';
-export * from '@openfeature/web-sdk';
-import { FlagValue, EvaluationDetails, FlagMetadata, StandardResolutionReasons, ErrorCode } from '@openfeature/core';
 import * as React from 'react';
 import React__default from 'react';
+import { FlagValue, EvaluationDetails, FlagMetadata, StandardResolutionReasons, ErrorCode } from '@openfeature/core';
+import { FlagEvaluationOptions, FlagValue as FlagValue$1, JsonValue, EvaluationDetails as EvaluationDetails$1, Client, ProviderStatus, Provider, EvaluationContext, Tracking } from '@openfeature/web-sdk';
+export * from '@openfeature/web-sdk';
+
+interface FlagQuery<T extends FlagValue = FlagValue> {
+    /**
+     * A structure representing the result of the flag evaluation process
+     */
+    readonly details: EvaluationDetails<T>;
+    /**
+     * The flag value
+     */
+    readonly value: T;
+    /**
+     * A variant is a semantic identifier for a value.
+     * Not available from all providers.
+     */
+    readonly variant: string | undefined;
+    /**
+     * Arbitrary data associated with this flag or evaluation.
+     * Not available from all providers.
+     */
+    readonly flagMetadata: FlagMetadata;
+    /**
+     * The reason the evaluation resolved to the particular value.
+     * Not available from all providers.
+     */
+    readonly reason: typeof StandardResolutionReasons | string | undefined;
+    /**
+     * Indicates if this flag defaulted due to an error.
+     * Specifically, indicates reason equals {@link StandardResolutionReasons.ERROR} or the errorCode is set, this field is truthy.
+     */
+    readonly isError: boolean;
+    /**
+     * The error code, see {@link ErrorCode}.
+     */
+    readonly errorCode: ErrorCode | undefined;
+    /**
+     * A message associated with the error.
+     */
+    readonly errorMessage: string | undefined;
+    /**
+     * Indicates this flag is up-to-date and in sync with the source of truth.
+     * Specifically, indicates the evaluation did not default due to error, and the reason is neither {@link StandardResolutionReasons.STALE} or {@link StandardResolutionReasons.DISABLED}.
+     */
+    readonly isAuthoritative: boolean;
+    /**
+     * The type of the value, as returned by "typeof" operator.
+     */
+    readonly type: 'string' | 'number' | 'bigint' | 'boolean' | 'symbol' | 'undefined' | 'object' | 'function';
+}
 
 type ReactFlagEvaluationOptions = ({
     /**
@@ -50,53 +98,69 @@ type ReactFlagEvaluationOptions = ({
 type ReactFlagEvaluationNoSuspenseOptions = Omit<ReactFlagEvaluationOptions, 'suspend' | 'suspendUntilReady' | 'suspendWhileReconciling'>;
 type NormalizedOptions = Omit<ReactFlagEvaluationOptions, 'suspend'>;
 
-interface FlagQuery<T extends FlagValue = FlagValue> {
-    /**
-     * A structure representing the result of the flag evaluation process
-     */
-    readonly details: EvaluationDetails<T>;
+/**
+ * Props for the FeatureFlag component that conditionally renders content based on feature flag state.
+ * @interface FeatureFlagProps
+ */
+interface FeatureFlagProps<T extends FlagValue = FlagValue> {
     /**
-     * The flag value
+     * The key of the feature flag to evaluate.
      */
-    readonly value: T;
+    flagKey: string;
     /**
-     * A variant is a semantic identifier for a value.
-     * Not available from all providers.
-     */
-    readonly variant: string | undefined;
-    /**
-     * Arbitrary data associated with this flag or evaluation.
-     * Not available from all providers.
+     * Optional predicate function for custom matching logic.
+     * If provided, this function will be used instead of the default equality check.
+     * @param matchValue The value to match (matchValue prop)
+     * @param details The evaluation details
+     * @returns true if the condition is met, false otherwise
      */
-    readonly flagMetadata: FlagMetadata;
+    predicate?: (matchValue: T | undefined, details: EvaluationDetails<T>) => boolean;
     /**
-     * The reason the evaluation resolved to the particular value.
-     * Not available from all providers.
+     * Content to render when the feature flag condition is met.
+     * Can be a React node or a function that receives flag query details and returns a React node.
      */
-    readonly reason: typeof StandardResolutionReasons | string | undefined;
+    children: React__default.ReactNode | ((details: FlagQuery<T>) => React__default.ReactNode);
     /**
-     * Indicates if this flag defaulted due to an error.
-     * Specifically, indicates reason equals {@link StandardResolutionReasons.ERROR} or the errorCode is set, this field is truthy.
+     * Optional content to render when the feature flag condition is not met.
+     * Can be a React node or a function that receives evaluation details and returns a React node.
      */
-    readonly isError: boolean;
+    fallback?: React__default.ReactNode | ((details: EvaluationDetails<T>) => React__default.ReactNode);
     /**
-     * The error code, see {@link ErrorCode}.
+     * Flag evaluation options that will be passed to useFlag hook.
      */
-    readonly errorCode: ErrorCode | undefined;
+    evaluationOptions?: ReactFlagEvaluationOptions;
+}
+/**
+ * Configuration for matching flag values.
+ * For boolean flags, `match` is optional (defaults to checking truthiness).
+ * For non-boolean flags (string, number, object), `match` is required to determine when to render.
+ */
+type FeatureFlagMatchConfig<T extends FlagValue> = {
     /**
-     * A message associated with the error.
+     * Default value to use when the feature flag is not found.
      */
-    readonly errorMessage: string | undefined;
+    defaultValue: T;
+} & (T extends boolean ? {
     /**
-     * Indicates this flag is up-to-date and in sync with the source of truth.
-     * Specifically, indicates the evaluation did not default due to error, and the reason is neither {@link StandardResolutionReasons.STALE} or {@link StandardResolutionReasons.DISABLED}.
+     * Optional value to match against the feature flag value.
      */
-    readonly isAuthoritative: boolean;
+    matchValue?: T | undefined;
+} : {
     /**
-     * The type of the value, as returned by "typeof" operator.
+     * Value to match against the feature flag value.
+     * Required for non-boolean flags to determine when children should render.
+     * By default, strict equality is used for comparison.
      */
-    readonly type: 'string' | 'number' | 'bigint' | 'boolean' | 'symbol' | 'undefined' | 'object' | 'function';
-}
+    matchValue: T;
+});
+type FeatureFlagComponentProps<T extends FlagValue> = FeatureFlagProps<T> & FeatureFlagMatchConfig<T>;
+/**
+ * @experimental This API is experimental, and is subject to change.
+ * FeatureFlag component that conditionally renders its children based on the evaluation of a feature flag.
+ * @param {FeatureFlagComponentProps} props The properties for the FeatureFlag component.
+ * @returns {React.ReactElement | null} The rendered component or null if the feature is not enabled.
+ */
+declare function FeatureFlag<T extends FlagValue = FlagValue>({ flagKey, matchValue, predicate, defaultValue, children, evaluationOptions, fallback, }: FeatureFlagComponentProps<T>): React__default.ReactElement | null;
 
 /**
  * Evaluates a feature flag generically, returning an react-flavored queryable object.
@@ -230,7 +294,7 @@ type ProviderProps = {
  * @param {ProviderProps} properties props for the context provider
  * @returns {OpenFeatureProvider} context provider
  */
-declare function OpenFeatureProvider({ client, domain, children, ...options }: ProviderProps): JSX.Element;
+declare function OpenFeatureProvider({ client, domain, children, ...options }: ProviderProps): React.JSX.Element;
 
 /**
  * Get the {@link Client} instance for this OpenFeatureProvider context.
@@ -294,7 +358,7 @@ declare function OpenFeatureTestProvider(testProviderOptions: TestProviderProps)
 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.
+     * By default, will use the domain set on `<OpenFeatureProvider/>` (or the domain associated with the client set on `<OpenFeatureProvider/>`).
      * See the {@link https://openfeature.dev/docs/reference/technologies/client/web/#manage-evaluation-context-for-domains|documentation} for more information.
      * @default false
      */
@@ -333,5 +397,5 @@ type Track = {
  */
 declare function useTrack(): Track;
 
-export { OpenFeatureProvider, OpenFeatureTestProvider, useBooleanFlagDetails, useBooleanFlagValue, useContextMutator, useFlag, useNumberFlagDetails, useNumberFlagValue, useObjectFlagDetails, useObjectFlagValue, useOpenFeatureClient, useOpenFeatureClientStatus, useStringFlagDetails, useStringFlagValue, useSuspenseFlag, useTrack, useWhenProviderReady };
+export { FeatureFlag, OpenFeatureProvider, OpenFeatureTestProvider, useBooleanFlagDetails, useBooleanFlagValue, useContextMutator, useFlag, useNumberFlagDetails, useNumberFlagValue, useObjectFlagDetails, useObjectFlagValue, useOpenFeatureClient, useOpenFeatureClientStatus, useStringFlagDetails, useStringFlagValue, useSuspenseFlag, useTrack, useWhenProviderReady };
 export type { ContextMutation, ContextMutationOptions, FlagQuery, NormalizedOptions, ReactFlagEvaluationNoSuspenseOptions, ReactFlagEvaluationOptions, Track };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openfeature/react-sdk",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "OpenFeature React SDK",
   "main": "./dist/cjs/index.js",
   "files": [