@trackunit/react-core-hooks 1.7.28 → 1.7.31

package/index.cjs.js

@@ -5,6 +5,7 @@ var jsxRuntime = require('react/jsx-runtime');
 var fflate = require('fflate');
 var irisAppRuntimeCore = require('@trackunit/iris-app-runtime-core');
 var sharedUtils = require('@trackunit/shared-utils');
+var esToolkit = require('es-toolkit');
 
 const AnalyticsContext = react.createContext(null);
 const AnalyticsContextProvider = AnalyticsContext.Provider; // easy import
@@ -1188,6 +1189,31 @@ function useTextSearch(items, props) {
     return react.useMemo(() => [result, searchText, setSearchText], [result, searchText, setSearchText]);
 }
 
+const UNINITIALIZED = Symbol("UNINITIALIZED");
+/**
+ * Hook to watch for changes in a value and react to them.
+ * Uses deep equality comparison via es-toolkit's isEqual.
+ *
+ * @param props - The hook properties
+ * @param props.value - The value to watch for changes
+ * @param props.onChange - Function to call when the value changes
+ * @param props.immediate - Whether to run the callback immediately on mount (default: false)
+ */
+const useWatch = ({ value, onChange, immediate = false }) => {
+    const prevValue = react.useRef(UNINITIALIZED);
+    react.useEffect(() => {
+        const prev = prevValue.current;
+        const hasChanged = prev === UNINITIALIZED ? false : !esToolkit.isEqual(value, prev);
+        if (immediate && prev === UNINITIALIZED) {
+            onChange(value, null);
+        }
+        else if (hasChanged && prev !== UNINITIALIZED) {
+            onChange(value, prev);
+        }
+        prevValue.current = value;
+    }, [value, onChange, immediate]);
+};
+
 const WidgetConfigContext = react.createContext(null);
 /**
  * This is a hook to use the WidgetConfigProvider.
@@ -1344,5 +1370,6 @@ exports.useTimeRange = useTimeRange;
 exports.useToast = useToast;
 exports.useToken = useToken;
 exports.useUserSubscription = useUserSubscription;
+exports.useWatch = useWatch;
 exports.useWidgetConfig = useWidgetConfig;
 exports.useWidgetConfigAsync = useWidgetConfigAsync;

package/index.esm.js

@@ -3,6 +3,7 @@ import { jsx } from 'react/jsx-runtime';
 import { gzipSync, gunzipSync } from 'fflate';
 import { AssetRuntime, CustomerRuntime, EventRuntime, ParamsRuntime, SiteRuntime, WidgetConfigRuntime } from '@trackunit/iris-app-runtime-core';
 import { filterByMultiple } from '@trackunit/shared-utils';
+import { isEqual } from 'es-toolkit';
 
 const AnalyticsContext = createContext(null);
 const AnalyticsContextProvider = AnalyticsContext.Provider; // easy import
@@ -1186,6 +1187,31 @@ function useTextSearch(items, props) {
     return useMemo(() => [result, searchText, setSearchText], [result, searchText, setSearchText]);
 }
 
+const UNINITIALIZED = Symbol("UNINITIALIZED");
+/**
+ * Hook to watch for changes in a value and react to them.
+ * Uses deep equality comparison via es-toolkit's isEqual.
+ *
+ * @param props - The hook properties
+ * @param props.value - The value to watch for changes
+ * @param props.onChange - Function to call when the value changes
+ * @param props.immediate - Whether to run the callback immediately on mount (default: false)
+ */
+const useWatch = ({ value, onChange, immediate = false }) => {
+    const prevValue = useRef(UNINITIALIZED);
+    useEffect(() => {
+        const prev = prevValue.current;
+        const hasChanged = prev === UNINITIALIZED ? false : !isEqual(value, prev);
+        if (immediate && prev === UNINITIALIZED) {
+            onChange(value, null);
+        }
+        else if (hasChanged && prev !== UNINITIALIZED) {
+            onChange(value, prev);
+        }
+        prevValue.current = value;
+    }, [value, onChange, immediate]);
+};
+
 const WidgetConfigContext = createContext(null);
 /**
  * This is a hook to use the WidgetConfigProvider.
@@ -1289,4 +1315,4 @@ const useWidgetConfig = () => {
     return result;
 };
 
-export { AnalyticsContext, AnalyticsContextProvider, AssetSortingProvider, ConfirmationDialogProvider, CurrentUserPreferenceProvider, CurrentUserProvider, EnvironmentContextProvider, ErrorHandlingContext, ErrorHandlingContextProvider, FilterBarProvider, ModalDialogContextProvider, NavigationContextProvider, OemBrandingContextProvider, TimeRangeProvider, ToastProvider, TokenProvider, UserSubscriptionProvider, WidgetConfigContext, WidgetConfigProvider, fetchAssetBlobUrl, useAnalytics, useAssetRuntime, useAssetSorting, useConfirmationDialog, useCurrentUser, useCurrentUserLanguage, useCurrentUserSystemOfMeasurement, useCurrentUserTimeZonePreference, useCustomEncoding, useCustomerRuntime, useEnvironment, useErrorHandler, useErrorHandlerOrNull, useEventRuntime, useFeatureBranchQueryString, useFilterBarContext, useHasAccessTo, useImageUploader, useIrisAppId, useIrisAppImage, useIrisAppName, useLocalStorage, useLocalStorageReducer, useModalDialogContext, useNavigateInHost, useOemBrandingContext, usePrevious, useSiteRuntime, useTextSearch, useTimeRange, useToast, useToken, useUserSubscription, useWidgetConfig, useWidgetConfigAsync };
+export { AnalyticsContext, AnalyticsContextProvider, AssetSortingProvider, ConfirmationDialogProvider, CurrentUserPreferenceProvider, CurrentUserProvider, EnvironmentContextProvider, ErrorHandlingContext, ErrorHandlingContextProvider, FilterBarProvider, ModalDialogContextProvider, NavigationContextProvider, OemBrandingContextProvider, TimeRangeProvider, ToastProvider, TokenProvider, UserSubscriptionProvider, WidgetConfigContext, WidgetConfigProvider, fetchAssetBlobUrl, useAnalytics, useAssetRuntime, useAssetSorting, useConfirmationDialog, useCurrentUser, useCurrentUserLanguage, useCurrentUserSystemOfMeasurement, useCurrentUserTimeZonePreference, useCustomEncoding, useCustomerRuntime, useEnvironment, useErrorHandler, useErrorHandlerOrNull, useEventRuntime, useFeatureBranchQueryString, useFilterBarContext, useHasAccessTo, useImageUploader, useIrisAppId, useIrisAppImage, useIrisAppName, useLocalStorage, useLocalStorageReducer, useModalDialogContext, useNavigateInHost, useOemBrandingContext, usePrevious, useSiteRuntime, useTextSearch, useTimeRange, useToast, useToken, useUserSubscription, useWatch, useWidgetConfig, useWidgetConfigAsync };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trackunit/react-core-hooks",
-  "version": "1.7.28",
+  "version": "1.7.31",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {
@@ -10,11 +10,12 @@
     "react": "19.0.0",
     "jest-fetch-mock": "^3.0.3",
     "zod": "^3.23.8",
-    "@trackunit/react-core-contexts-api": "1.8.26",
-    "@trackunit/iris-app-runtime-core": "1.8.26",
-    "@trackunit/shared-utils": "1.9.24",
-    "@trackunit/react-test-setup": "1.4.24",
-    "fflate": "^0.8.2"
+    "@trackunit/react-core-contexts-api": "1.8.28",
+    "@trackunit/iris-app-runtime-core": "1.8.28",
+    "@trackunit/shared-utils": "1.9.26",
+    "@trackunit/react-test-setup": "1.4.26",
+    "fflate": "^0.8.2",
+    "es-toolkit": "^1.39.10"
   },
   "module": "./index.esm.js",
   "main": "./index.cjs.js",

package/src/index.d.ts

@@ -27,4 +27,5 @@ export * from "./usePrevious";
 export * from "./user/CurrentUserPreferenceProvider";
 export * from "./user/CurrentUserProvider";
 export * from "./useTextSearch";
+export * from "./useWatch";
 export * from "./widgetConfig/WidgetConfigProvider";

package/src/useWatch.d.ts

@@ -0,0 +1,18 @@
+interface UseWatchOptions {
+    immediate?: boolean;
+}
+interface UseWatchProps<TValue> extends UseWatchOptions {
+    value: TValue;
+    onChange: (value: TValue, prevValue: TValue | null) => void;
+}
+/**
+ * Hook to watch for changes in a value and react to them.
+ * Uses deep equality comparison via es-toolkit's isEqual.
+ *
+ * @param props - The hook properties
+ * @param props.value - The value to watch for changes
+ * @param props.onChange - Function to call when the value changes
+ * @param props.immediate - Whether to run the callback immediately on mount (default: false)
+ */
+export declare const useWatch: <TValue>({ value, onChange, immediate }: UseWatchProps<TValue>) => void;
+export {};