@ninetailed/experience.js-react 7.15.1 → 7.16.0

package/index.cjs.js

@@ -153,32 +153,34 @@ const usePersonalize = (baseline, variants, options = {
 };
 
 /**
- * Hook to access a Ninetailed variable flag with built-in tracking.
+ * Hook to access a Ninetailed variable flag with manual tracking control.
  */
-function useFlag(flagKey, defaultValue, options = {}) {
+function useFlagWithManualTracking(flagKey, defaultValue) {
   const ninetailed = useNinetailed();
-  const lastProcessedState = React.useRef(null);
-  const defaultValueRef = React.useRef(defaultValue);
   const flagKeyRef = React.useRef(flagKey);
+  const defaultValueRef = React.useRef(defaultValue);
+  const lastProcessedState = React.useRef(null);
+  const changeRef = React.useRef(null);
   const [result, setResult] = React.useState({
     value: defaultValue,
     status: 'loading',
     error: null
   });
-  // Reset on input change
+  // Reset if inputs change
   React.useEffect(() => {
     if (!radash.isEqual(defaultValueRef.current, defaultValue) || flagKeyRef.current !== flagKey) {
       defaultValueRef.current = defaultValue;
       flagKeyRef.current = flagKey;
+      lastProcessedState.current = null;
+      changeRef.current = null;
       setResult({
         value: defaultValue,
         status: 'loading',
         error: null
       });
-      lastProcessedState.current = null;
     }
   }, [flagKey, defaultValue]);
-  // Track changes
+  // Listen for personalization state changes
   React.useEffect(() => {
     const unsubscribe = ninetailed.onChangesChange(changesState => {
       if (lastProcessedState.current && radash.isEqual(lastProcessedState.current, changesState)) {
@@ -201,46 +203,59 @@ function useFlag(flagKey, defaultValue, options = {}) {
         });
         return;
       }
-      try {
-        const change = changesState.changes.find(change => change.key === flagKeyRef.current);
-        if (change && change.type === experience_jsShared.ChangeTypes.Variable) {
-          const rawValue = change.value;
-          const actualValue = rawValue && typeof rawValue === 'object' && rawValue !== null && 'value' in rawValue && typeof rawValue['value'] === 'object' ? rawValue['value'] : rawValue;
-          setResult({
-            value: actualValue,
-            status: 'success',
-            error: null
-          });
-          const key = flagKeyRef.current;
-          const shouldTrack = typeof options.shouldTrack === 'function' ? options.shouldTrack() : options.shouldTrack !== false;
-          if (shouldTrack) {
-            ninetailed.trackVariableComponentView({
-              variable: change.value,
-              variant: {
-                id: `Variable-${key}`
-              },
-              componentType: 'Variable',
-              variantIndex: change.meta.variantIndex,
-              experienceId: change.meta.experienceId
-            });
-          }
-        } else {
-          setResult({
-            value: defaultValueRef.current,
-            status: 'success',
-            error: null
-          });
-        }
-      } catch (error) {
+      // Find relevant change for this flag
+      const change = changesState.changes.find(c => c.key === flagKeyRef.current && c.type === experience_jsShared.ChangeTypes.Variable);
+      if (change) {
+        changeRef.current = change;
+        const rawValue = change.value;
+        const actualValue = rawValue && typeof rawValue === 'object' && rawValue !== null && 'value' in rawValue && typeof rawValue['value'] === 'object' ? rawValue['value'] : rawValue;
+        setResult({
+          value: actualValue,
+          status: 'success',
+          error: null
+        });
+      } else {
+        changeRef.current = null;
         setResult({
           value: defaultValueRef.current,
-          status: 'error',
-          error: error instanceof Error ? error : new Error(String(error))
+          status: 'success',
+          error: null
         });
       }
     });
     return unsubscribe;
   }, [ninetailed]);
+  // Manual tracking function
+  const track = React.useCallback(() => {
+    const change = changeRef.current;
+    if (!change) return;
+    ninetailed.trackVariableComponentView({
+      variable: change.value,
+      variant: {
+        id: `Variable-${flagKeyRef.current}`
+      },
+      componentType: 'Variable',
+      variantIndex: change.meta.variantIndex,
+      experienceId: change.meta.experienceId
+    });
+  }, [ninetailed]);
+  return [result, track];
+}
+
+/**
+ * Hook to access a Ninetailed variable flag with built-in auto-tracking.
+ *
+ * @remarks
+ * For manual control over tracking behavior, consider using {@link useFlagWithManualTracking}.
+ */
+function useFlag(flagKey, defaultValue, options = {}) {
+  const [result, track] = useFlagWithManualTracking(flagKey, defaultValue);
+  React.useEffect(() => {
+    const shouldAutoTrack = typeof options.shouldAutoTrack === 'function' ? options.shouldAutoTrack() : options.shouldAutoTrack !== false;
+    if (result.status === 'success' && shouldAutoTrack) {
+      track();
+    }
+  }, [result.status, track, options.shouldAutoTrack]);
   return result;
 }
 
@@ -720,6 +735,7 @@ exports.Personalize = Personalize;
 exports.TrackHasSeenComponent = TrackHasSeenComponent;
 exports.useExperience = useExperience;
 exports.useFlag = useFlag;
+exports.useFlagWithManualTracking = useFlagWithManualTracking;
 exports.useNinetailed = useNinetailed;
 exports.usePersonalize = usePersonalize;
 exports.useProfile = useProfile;

package/index.esm.js

@@ -1,4 +1,4 @@
-import React, { createContext, useMemo, useContext, useState, useRef, useEffect, createElement, forwardRef } from 'react';
+import React, { createContext, useMemo, useContext, useState, useRef, useEffect, useCallback, createElement, forwardRef } from 'react';
 import { Ninetailed, selectVariant, selectHasExperienceVariants } from '@ninetailed/experience.js';
 import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
 import { logger, ChangeTypes, isBrowser, circularJsonStringify } from '@ninetailed/experience.js-shared';
@@ -134,34 +134,36 @@ const usePersonalize = (baseline, variants, options = {
 };
 
 /**
- * Hook to access a Ninetailed variable flag with built-in tracking.
+ * Hook to access a Ninetailed variable flag with manual tracking control.
  */
-function useFlag(flagKey, defaultValue, options = {}) {
+function useFlagWithManualTracking(flagKey, defaultValue) {
   const ninetailed = useNinetailed();
-  const lastProcessedState = useRef(null);
-  const defaultValueRef = useRef(defaultValue);
   const flagKeyRef = useRef(flagKey);
+  const defaultValueRef = useRef(defaultValue);
+  const lastProcessedState = useRef(null);
+  const changeRef = useRef(null);
   const [result, setResult] = useState({
     value: defaultValue,
     status: 'loading',
     error: null
   });
 
-  // Reset on input change
+  // Reset if inputs change
   useEffect(() => {
     if (!isEqual(defaultValueRef.current, defaultValue) || flagKeyRef.current !== flagKey) {
       defaultValueRef.current = defaultValue;
       flagKeyRef.current = flagKey;
+      lastProcessedState.current = null;
+      changeRef.current = null;
       setResult({
         value: defaultValue,
         status: 'loading',
         error: null
       });
-      lastProcessedState.current = null;
     }
   }, [flagKey, defaultValue]);
 
-  // Track changes
+  // Listen for personalization state changes
   useEffect(() => {
     const unsubscribe = ninetailed.onChangesChange(changesState => {
       if (lastProcessedState.current && isEqual(lastProcessedState.current, changesState)) {
@@ -184,46 +186,61 @@ function useFlag(flagKey, defaultValue, options = {}) {
         });
         return;
       }
-      try {
-        const change = changesState.changes.find(change => change.key === flagKeyRef.current);
-        if (change && change.type === ChangeTypes.Variable) {
-          const rawValue = change.value;
-          const actualValue = rawValue && typeof rawValue === 'object' && rawValue !== null && 'value' in rawValue && typeof rawValue['value'] === 'object' ? rawValue['value'] : rawValue;
-          setResult({
-            value: actualValue,
-            status: 'success',
-            error: null
-          });
-          const key = flagKeyRef.current;
-          const shouldTrack = typeof options.shouldTrack === 'function' ? options.shouldTrack() : options.shouldTrack !== false;
-          if (shouldTrack) {
-            ninetailed.trackVariableComponentView({
-              variable: change.value,
-              variant: {
-                id: `Variable-${key}`
-              },
-              componentType: 'Variable',
-              variantIndex: change.meta.variantIndex,
-              experienceId: change.meta.experienceId
-            });
-          }
-        } else {
-          setResult({
-            value: defaultValueRef.current,
-            status: 'success',
-            error: null
-          });
-        }
-      } catch (error) {
+
+      // Find relevant change for this flag
+      const change = changesState.changes.find(c => c.key === flagKeyRef.current && c.type === ChangeTypes.Variable);
+      if (change) {
+        changeRef.current = change;
+        const rawValue = change.value;
+        const actualValue = rawValue && typeof rawValue === 'object' && rawValue !== null && 'value' in rawValue && typeof rawValue['value'] === 'object' ? rawValue['value'] : rawValue;
+        setResult({
+          value: actualValue,
+          status: 'success',
+          error: null
+        });
+      } else {
+        changeRef.current = null;
         setResult({
           value: defaultValueRef.current,
-          status: 'error',
-          error: error instanceof Error ? error : new Error(String(error))
+          status: 'success',
+          error: null
         });
       }
     });
     return unsubscribe;
   }, [ninetailed]);
+
+  // Manual tracking function
+  const track = useCallback(() => {
+    const change = changeRef.current;
+    if (!change) return;
+    ninetailed.trackVariableComponentView({
+      variable: change.value,
+      variant: {
+        id: `Variable-${flagKeyRef.current}`
+      },
+      componentType: 'Variable',
+      variantIndex: change.meta.variantIndex,
+      experienceId: change.meta.experienceId
+    });
+  }, [ninetailed]);
+  return [result, track];
+}
+
+/**
+ * Hook to access a Ninetailed variable flag with built-in auto-tracking.
+ *
+ * @remarks
+ * For manual control over tracking behavior, consider using {@link useFlagWithManualTracking}.
+ */
+function useFlag(flagKey, defaultValue, options = {}) {
+  const [result, track] = useFlagWithManualTracking(flagKey, defaultValue);
+  useEffect(() => {
+    const shouldAutoTrack = typeof options.shouldAutoTrack === 'function' ? options.shouldAutoTrack() : options.shouldAutoTrack !== false;
+    if (result.status === 'success' && shouldAutoTrack) {
+      track();
+    }
+  }, [result.status, track, options.shouldAutoTrack]);
   return result;
 }
 
@@ -696,4 +713,4 @@ const ESRLoadingComponent = _ref => {
   }));
 };
 
-export { DefaultExperienceLoadingComponent, ESRLoadingComponent, ESRProvider, Experience, MergeTag, NinetailedProvider, Personalize, TrackHasSeenComponent, useExperience, useFlag, useNinetailed, usePersonalize, useProfile };
+export { DefaultExperienceLoadingComponent, ESRLoadingComponent, ESRProvider, Experience, MergeTag, NinetailedProvider, Personalize, TrackHasSeenComponent, useExperience, useFlag, useFlagWithManualTracking, useNinetailed, usePersonalize, useProfile };

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@ninetailed/experience.js-react",
-  "version": "7.15.1",
+  "version": "7.16.0",
   "description": "Ninetailed SDK for React",
   "dependencies": {
-    "@ninetailed/experience.js": "7.15.1",
-    "@ninetailed/experience.js-shared": "7.15.1",
-    "@ninetailed/experience.js-plugin-analytics": "7.15.1",
+    "@ninetailed/experience.js": "7.16.0",
+    "@ninetailed/experience.js-shared": "7.16.0",
+    "@ninetailed/experience.js-plugin-analytics": "7.16.0",
     "radash": "10.9.0",
     "react-is": "18.2.0"
   },

package/src/lib/index.d.ts

@@ -6,6 +6,7 @@ export { useNinetailed } from './useNinetailed';
 export { useProfile } from './useProfile';
 export { usePersonalize } from './usePersonalize';
 export { useFlag } from './useFlag';
+export { useFlagWithManualTracking } from './useFlagWithManualTracking';
 export { Personalize } from './Personalize';
 export type { PersonalizedComponent } from './Personalize';
 export { MergeTag } from './MergeTag';

package/src/lib/useFlag.d.ts

@@ -13,10 +13,13 @@ export type FlagResult<T> = {
     error: Error;
 };
 type UseFlagOptions = {
-    shouldTrack?: boolean | (() => boolean);
+    shouldAutoTrack?: boolean | (() => boolean);
 };
 /**
- * Hook to access a Ninetailed variable flag with built-in tracking.
+ * Hook to access a Ninetailed variable flag with built-in auto-tracking.
+ *
+ * @remarks
+ * For manual control over tracking behavior, consider using {@link useFlagWithManualTracking}.
  */
 export declare function useFlag<T extends AllowedVariableType>(flagKey: string, defaultValue: T, options?: UseFlagOptions): FlagResult<T>;
 export {};

package/src/lib/useFlagWithManualTracking.d.ts

@@ -0,0 +1,19 @@
+import { AllowedVariableType } from '@ninetailed/experience.js-shared';
+export type FlagResult<T> = {
+    status: 'loading';
+    value: T;
+    error: null;
+} | {
+    status: 'success';
+    value: T;
+    error: null;
+} | {
+    status: 'error';
+    value: T;
+    error: Error;
+};
+export type FlagResultWithTracking<T> = [FlagResult<T>, () => void];
+/**
+ * Hook to access a Ninetailed variable flag with manual tracking control.
+ */
+export declare function useFlagWithManualTracking<T extends AllowedVariableType>(flagKey: string, defaultValue: T): FlagResultWithTracking<T>;