@trackunit/react-components 1.1.52 → 1.1.56

package/index.cjs.js

@@ -1147,6 +1147,21 @@ function getDevicePixelRatio(options) {
     return Math.min(Math.max(1, round ? Math.floor(dpr) : dpr), maxDpr);
 }
 
+/**
+ * Use this hook if you want to optionally elevate the reducer state of a component.
+ * Useful when you _want_ to be able to control the reducer state of a component
+ * from a parent component but keep the simplicity of not _having_ to.
+ *
+ * If no custom reducer state is provided, the fallback reducer state will be used and it works like a normal useReducer hook.
+ *
+ * @example
+ * const [state, dispatch] = useElevatedReducer(reducer, initialState, elevatedReducerState);
+ */
+const useElevatedReducer = (reducer, initialState, customState) => {
+    const fallbackState = react.useReducer(reducer, initialState);
+    return customState ?? fallbackState;
+};
+
 /**
  * Use this hook if you want to optionally elevate the state of a component.
  * Useful when you _want_ to be able to control the state of a component
@@ -1454,6 +1469,31 @@ const useViewportBreakpoints = () => {
     return viewportSize;
 };
 
+const UNINITIALIZED = Symbol("UNINITIALIZED");
+/**
+ * Hook to watch for changes in a value and react to them.
+ *
+ * @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)
+ * @param props.isEqual - Custom equality function to determine if value has changed. Defaults to stringified equality.
+ */
+const useWatch = ({ value, onChange, immediate = false, isEqual }) => {
+    const prevValue = react.useRef(UNINITIALIZED);
+    react.useEffect(() => {
+        const prev = prevValue.current;
+        const hasChanged = prev === UNINITIALIZED ? false : isEqual ? !isEqual(value, prev) : JSON.stringify(value) !== JSON.stringify(prev);
+        if (immediate && prev === UNINITIALIZED) {
+            onChange(value, null);
+        }
+        else if (hasChanged && prev !== UNINITIALIZED) {
+            onChange(value, prev);
+        }
+        prevValue.current = value;
+    }, [value, onChange, immediate, isEqual]);
+};
+
 const hasFocus = () => typeof document !== "undefined" && document.hasFocus();
 /**
  * Use this hook to disable functionality while the tab is hidden within the browser or to react to focus or blur events
@@ -3946,6 +3986,7 @@ exports.useContainerBreakpoints = useContainerBreakpoints;
 exports.useContinuousTimeout = useContinuousTimeout;
 exports.useDebounce = useDebounce;
 exports.useDevicePixelRatio = useDevicePixelRatio;
+exports.useElevatedReducer = useElevatedReducer;
 exports.useElevatedState = useElevatedState;
 exports.useGeometry = useGeometry;
 exports.useHover = useHover;
@@ -3960,4 +4001,5 @@ exports.useScrollDetection = useScrollDetection;
 exports.useSelfUpdatingRef = useSelfUpdatingRef;
 exports.useTimeout = useTimeout;
 exports.useViewportBreakpoints = useViewportBreakpoints;
+exports.useWatch = useWatch;
 exports.useWindowActivity = useWindowActivity;

package/index.esm.js

@@ -1,5 +1,5 @@
 import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
-import { useRef, useMemo, useEffect, forwardRef, useState, useCallback, createElement, memo, createContext, useContext, isValidElement, cloneElement, Children } from 'react';
+import { useRef, useMemo, useEffect, forwardRef, useState, useCallback, createElement, useReducer, memo, createContext, useContext, isValidElement, cloneElement, Children } from 'react';
 import { objectKeys, uuidv4, objectEntries, objectValues } from '@trackunit/shared-utils';
 import { rentalStatusPalette, intentPalette, generalPalette, criticalityPalette, activityPalette, utilizationPalette, sitesPalette, themeScreenSizeAsNumber, color } from '@trackunit/ui-design-tokens';
 import { iconNames } from '@trackunit/ui-icons';
@@ -1145,6 +1145,21 @@ function getDevicePixelRatio(options) {
     return Math.min(Math.max(1, round ? Math.floor(dpr) : dpr), maxDpr);
 }
 
+/**
+ * Use this hook if you want to optionally elevate the reducer state of a component.
+ * Useful when you _want_ to be able to control the reducer state of a component
+ * from a parent component but keep the simplicity of not _having_ to.
+ *
+ * If no custom reducer state is provided, the fallback reducer state will be used and it works like a normal useReducer hook.
+ *
+ * @example
+ * const [state, dispatch] = useElevatedReducer(reducer, initialState, elevatedReducerState);
+ */
+const useElevatedReducer = (reducer, initialState, customState) => {
+    const fallbackState = useReducer(reducer, initialState);
+    return customState ?? fallbackState;
+};
+
 /**
  * Use this hook if you want to optionally elevate the state of a component.
  * Useful when you _want_ to be able to control the state of a component
@@ -1452,6 +1467,31 @@ const useViewportBreakpoints = () => {
     return viewportSize;
 };
 
+const UNINITIALIZED = Symbol("UNINITIALIZED");
+/**
+ * Hook to watch for changes in a value and react to them.
+ *
+ * @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)
+ * @param props.isEqual - Custom equality function to determine if value has changed. Defaults to stringified equality.
+ */
+const useWatch = ({ value, onChange, immediate = false, isEqual }) => {
+    const prevValue = useRef(UNINITIALIZED);
+    useEffect(() => {
+        const prev = prevValue.current;
+        const hasChanged = prev === UNINITIALIZED ? false : isEqual ? !isEqual(value, prev) : JSON.stringify(value) !== JSON.stringify(prev);
+        if (immediate && prev === UNINITIALIZED) {
+            onChange(value, null);
+        }
+        else if (hasChanged && prev !== UNINITIALIZED) {
+            onChange(value, prev);
+        }
+        prevValue.current = value;
+    }, [value, onChange, immediate, isEqual]);
+};
+
 const hasFocus = () => typeof document !== "undefined" && document.hasFocus();
 /**
  * Use this hook to disable functionality while the tab is hidden within the browser or to react to focus or blur events
@@ -3843,4 +3883,4 @@ const cvaClickable = cvaMerge([
     },
 });
 
-export { ActionRenderer, Alert, Badge, Breadcrumb, BreadcrumbContainer, Button, Card, CardBody, CardFooter, CardHeader, Collapse, CompletionStatusIndicator, CopyableText, EmptyState, EmptyValue, ExternalLink, Heading, Icon, IconButton, Indicator, KPICard, MenuDivider, MenuItem, MenuList, MoreMenu, Notice, PackageNameStoryComponent, Page, PageContent, PageHeader, PageHeaderKpiMetrics, PageHeaderSecondaryActions, PageHeaderTitle, Pagination, Polygon, Popover, PopoverContent, PopoverTitle, PopoverTrigger, Portal, Prompt, ROLE_CARD, SectionHeader, Sidebar, SkeletonLines, Spacer, Spinner, StarButton, Tab, TabContent, TabList, Tabs, Tag, Text, ToggleGroup, ToggleItem, Tooltip, ValueBar, VirtualizedList, WidgetBody, ZStack, cvaButton, cvaButtonPrefixSuffix, cvaButtonSpinner, cvaButtonSpinnerContainer, cvaClickable, cvaContainerStyles, cvaIconButton, cvaImgStyles, cvaIndicator, cvaIndicatorIcon, cvaIndicatorIconBackground, cvaIndicatorLabel, cvaIndicatorPing, cvaInteractableItem, cvaMenuItem, cvaMenuItemLabel, cvaMenuItemPrefix, cvaMenuItemStyle, cvaMenuItemSuffix, cvaPageHeader, cvaPageHeaderContainer, cvaPageHeaderHeading, cvaToggleGroup, cvaToggleItem, cvaToggleItemText, cvaVirtualizedList, cvaVirtualizedListContainer, cvaVirtualizedListItem, cvaZStackContainer, cvaZStackItem, docs, getDevicePixelRatio, getValueBarColorByValue, iconColorNames, iconPalette, useClickOutside, useContainerBreakpoints, useContinuousTimeout, useDebounce, useDevicePixelRatio, useElevatedState, useGeometry, useHover, useIsFirstRender, useIsFullscreen, useIsTextTruncated, useOverflowItems, usePopoverContext, usePrompt, useResize, useScrollDetection, useSelfUpdatingRef, useTimeout, useViewportBreakpoints, useWindowActivity };
+export { ActionRenderer, Alert, Badge, Breadcrumb, BreadcrumbContainer, Button, Card, CardBody, CardFooter, CardHeader, Collapse, CompletionStatusIndicator, CopyableText, EmptyState, EmptyValue, ExternalLink, Heading, Icon, IconButton, Indicator, KPICard, MenuDivider, MenuItem, MenuList, MoreMenu, Notice, PackageNameStoryComponent, Page, PageContent, PageHeader, PageHeaderKpiMetrics, PageHeaderSecondaryActions, PageHeaderTitle, Pagination, Polygon, Popover, PopoverContent, PopoverTitle, PopoverTrigger, Portal, Prompt, ROLE_CARD, SectionHeader, Sidebar, SkeletonLines, Spacer, Spinner, StarButton, Tab, TabContent, TabList, Tabs, Tag, Text, ToggleGroup, ToggleItem, Tooltip, ValueBar, VirtualizedList, WidgetBody, ZStack, cvaButton, cvaButtonPrefixSuffix, cvaButtonSpinner, cvaButtonSpinnerContainer, cvaClickable, cvaContainerStyles, cvaIconButton, cvaImgStyles, cvaIndicator, cvaIndicatorIcon, cvaIndicatorIconBackground, cvaIndicatorLabel, cvaIndicatorPing, cvaInteractableItem, cvaMenuItem, cvaMenuItemLabel, cvaMenuItemPrefix, cvaMenuItemStyle, cvaMenuItemSuffix, cvaPageHeader, cvaPageHeaderContainer, cvaPageHeaderHeading, cvaToggleGroup, cvaToggleItem, cvaToggleItemText, cvaVirtualizedList, cvaVirtualizedListContainer, cvaVirtualizedListItem, cvaZStackContainer, cvaZStackItem, docs, getDevicePixelRatio, getValueBarColorByValue, iconColorNames, iconPalette, useClickOutside, useContainerBreakpoints, useContinuousTimeout, useDebounce, useDevicePixelRatio, useElevatedReducer, useElevatedState, useGeometry, useHover, useIsFirstRender, useIsFullscreen, useIsTextTruncated, useOverflowItems, usePopoverContext, usePrompt, useResize, useScrollDetection, useSelfUpdatingRef, useTimeout, useViewportBreakpoints, useWatch, useWindowActivity };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trackunit/react-components",
-  "version": "1.1.52",
+  "version": "1.1.56",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {
@@ -19,11 +19,11 @@
     "@tanstack/react-router": "1.47.1",
     "string-ts": "^2.0.0",
     "tailwind-merge": "^2.0.0",
-    "@trackunit/ui-design-tokens": "1.0.45",
-    "@trackunit/css-class-variance-utilities": "1.0.44",
-    "@trackunit/shared-utils": "1.2.41",
-    "@trackunit/ui-icons": "1.0.49",
-    "@trackunit/react-table-pagination": "1.0.45"
+    "@trackunit/ui-design-tokens": "1.0.48",
+    "@trackunit/css-class-variance-utilities": "1.0.47",
+    "@trackunit/shared-utils": "1.2.45",
+    "@trackunit/ui-icons": "1.0.52",
+    "@trackunit/react-table-pagination": "1.0.48"
   },
   "module": "./index.esm.js",
   "main": "./index.cjs.js",

package/src/hooks/index.d.ts

@@ -3,6 +3,7 @@ export * from "./useContainerBreakpoints";
 export * from "./useContinuousTimeout";
 export * from "./useDebounce";
 export * from "./useDevicePixelRatio";
+export * from "./useElevatedReducer";
 export * from "./useElevatedState";
 export * from "./useGeometry";
 export * from "./useHover";
@@ -14,4 +15,5 @@ export * from "./useScrollDetection";
 export * from "./useSelfUpdatingRef";
 export * from "./useTimeout";
 export * from "./useViewportBreakpoints";
+export * from "./useWatch";
 export * from "./useWindowActivity";

package/src/hooks/useElevatedReducer.d.ts

@@ -0,0 +1,12 @@
+import { Dispatch, Reducer } from "react";
+/**
+ * Use this hook if you want to optionally elevate the reducer state of a component.
+ * Useful when you _want_ to be able to control the reducer state of a component
+ * from a parent component but keep the simplicity of not _having_ to.
+ *
+ * If no custom reducer state is provided, the fallback reducer state will be used and it works like a normal useReducer hook.
+ *
+ * @example
+ * const [state, dispatch] = useElevatedReducer(reducer, initialState, elevatedReducerState);
+ */
+export declare const useElevatedReducer: <TState, TAction>(reducer: Reducer<TState, TAction>, initialState: TState, customState?: [TState, Dispatch<TAction>]) => [TState, Dispatch<TAction>];

package/src/hooks/useWatch.d.ts

@@ -0,0 +1,19 @@
+interface UseWatchOptions<TValue> {
+    immediate?: boolean;
+    isEqual?: (prev: TValue, next: TValue) => boolean;
+}
+interface UseWatchProps<TValue> extends UseWatchOptions<TValue> {
+    value: TValue;
+    onChange: (value: TValue, prevValue: TValue | null) => void;
+}
+/**
+ * Hook to watch for changes in a value and react to them.
+ *
+ * @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)
+ * @param props.isEqual - Custom equality function to determine if value has changed. Defaults to stringified equality.
+ */
+export declare const useWatch: <TValue>({ value, onChange, immediate, isEqual }: UseWatchProps<TValue>) => void;
+export {};