feat\!: improve FeatureFlag component API with predicate support

BREAKING CHANGE: Renamed `featureKey` prop to `flagKey` to avoid React key conflicts. Removed `negate` prop in favor of custom predicate functions.

- Rename `featureKey` prop to `flagKey` to prevent conflicts with React's reserved key prop
- Add optional `predicate` function prop for flexible custom matching logic
- Remove `negate` prop (negation can be handled via predicate functions)
- Improve type safety with generic types and FlagValue constraints
- Add default `equals` predicate function for standard equality matching
- Remove debug console.log statement
- Support truthy evaluation when no match value is provided

Signed-off-by: Weyert de Boer <[email protected]>

Author: weyert

packages/react/src/declarative/FeatureFlag.tsx

@@ -1,64 +1,76 @@
 import React from 'react';
 import { useFlag } from '../evaluation';
 import type { FlagQuery } from '../query';
+import type { FlagValue, EvaluationDetails } from '@openfeature/core';
 
 /**
- * Props for the Feature component that conditionally renders content based on feature flag state.
- * @interface FeatureProps
+ * Default predicate function that checks if the expected value equals the actual flag value.
+ * @param {T} expected The expected value to match against
+ * @param {EvaluationDetails<T>} actual The evaluation details containing the actual flag value
+ * @returns {boolean} true if the values match, false otherwise
  */
-interface FeatureProps {
+function equals<T extends FlagValue>(expected: T, actual: EvaluationDetails<T>): boolean {
+  return expected === actual.value;
+}
+
+/**
+ * Props for the FeatureFlag component that conditionally renders content based on feature flag state.
+ * @interface FeatureFlagProps
+ */
+interface FeatureFlagProps<T extends FlagValue = FlagValue> {
   /**
    * The key of the feature flag to evaluate.
    */
-  featureKey: string;
+  flagKey: string;
 
   /**
    * Optional value to match against the feature flag value.
    * If provided, the component will only render children when the flag value matches this value.
    * If a boolean, it will check if the flag is enabled (true) or disabled (false).
    * If a string, it will check if the flag variant equals this string.
    */
-  match?: string | boolean;
+  match?: T;
+
+  /**
+   * Optional predicate function for custom matching logic.
+   * If provided, this function will be used instead of the default equality check.
+   * @param expected The expected value (from match prop)
+   * @param actual The evaluation details
+   * @returns true if the condition is met, false otherwise
+   */
+  predicate?: (expected: T | undefined, actual: EvaluationDetails<T>) => boolean;
 
   /**
    * Default value to use when the feature flag is not found.
    */
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  defaultValue: any;
+  defaultValue: T;
 
   /**
    * 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.
    */
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  children: React.ReactNode | ((details: FlagQuery<any>) => React.ReactNode);
+  children: React.ReactNode | ((details: FlagQuery<T>) => React.ReactNode);
 
   /**
    * Optional content to render when the feature flag condition is not met.
    */
   fallback?: React.ReactNode;
-
-  /**
-   * If true, inverts the condition logic (renders children when condition is NOT met).
-   */
-  negate?: boolean;
 }
 
 /**
  * FeatureFlag component that conditionally renders its children based on the evaluation of a feature flag.
- *
- * @param {FeatureProps} props The properties for the FeatureFlag component.
+ * @param {FeatureFlagProps} props The properties for the FeatureFlag component.
  * @returns {React.ReactElement | null} The rendered component or null if the feature is not enabled.
  */
-export function FeatureFlag({
-  featureKey,
+export function FeatureFlag<T extends FlagValue = FlagValue>({
+  flagKey,
   match,
-  negate = false,
-  defaultValue = true,
+  predicate,
+  defaultValue,
   children,
   fallback = null,
-}: FeatureProps): React.ReactElement | null {
-  const details = useFlag(featureKey, defaultValue, {
+}: FeatureFlagProps<T>): React.ReactElement | null {
+  const details = useFlag(flagKey, defaultValue, {
     updateOnContextChanged: true,
   });
 
@@ -67,23 +79,20 @@ export function FeatureFlag({
     return <>{fallback}</>;
   }
 
-  let isMatch = false;
-  if (typeof match === 'string') {
-    isMatch = details.variant === match;
-  } else if (typeof match !== 'undefined') {
-    isMatch = details.value === match;
+  // Use custom predicate if provided, otherwise use default matching logic
+  let shouldRender = false;
+  if (predicate) {
+    shouldRender = predicate(match, details.details as EvaluationDetails<T>);
+  } else if (match !== undefined) {
+    // Default behavior: check if match value equals flag value
+    shouldRender = equals(match, details.details as EvaluationDetails<T>);
+  } else {
+    // If no match value is provided, render if flag is truthy
+    shouldRender = Boolean(details.value);
   }
 
-  // If match is undefined, we assume the flag is enabled
-  if (match === void 0) {
-    isMatch = true;
-  }
-
-  const shouldRender = negate ? !isMatch : isMatch;
-
   if (shouldRender) {
-    console.log('chop chop');
-    const childNode: React.ReactNode = typeof children === 'function' ? children(details) : children;
+    const childNode: React.ReactNode = typeof children === 'function' ? children(details as FlagQuery<T>) : children;
     return <>{childNode}</>;
   }