@hubspot/ui-extensions 0.12.4 → 0.13.0

package/dist/crm/hooks/useAssociations.js

@@ -1,5 +1,6 @@
-import { useCallback, useEffect, useMemo, useReducer, useRef } from 'react';
-import { createMockAwareHook } from "../../internal/hook-utils.js";
+import { useCallback, useMemo, useReducer } from 'react';
+import { useFetchLifecycle } from "../../hooks/utils/useFetchLifecycle.js";
+import { createMockAwareHook, useStableValue, } from "../../internal/hook-utils.js";
 import { calculatePaginationFlags, DEFAULT_PAGE_SIZE, } from "../../utils/pagination.js";
 import { fetchAssociations } from "../utils/fetchAssociations.js";
 function createInitialState(pageSize) {
@@ -109,39 +110,8 @@ const DEFAULT_OPTIONS = {};
 function useAssociationsInternal(config, options = DEFAULT_OPTIONS) {
     const pageSize = config?.pageLength ?? DEFAULT_PAGE_SIZE;
     const [state, dispatch] = useReducer(associationsReducer, useMemo(() => createInitialState(pageSize), [pageSize]));
-    /**
-     * HOOK OPTIMIZATION:
-     *
-     * Create stable references for config and options to prevent unnecessary re-renders and API calls.
-     * Then, external developers can pass inline objects without worrying about memoization
-     * We handle the deep equality comparison ourselves, and return the same object reference when content is equivalent.
-     */
-    const lastConfigRef = useRef();
-    const lastConfigKeyRef = useRef();
-    const lastOptionsRef = useRef();
-    const lastOptionsKeyRef = useRef();
-    // Track in-flight refetch to support cancellation
-    const refetchAbortRef = useRef(null);
-    // Track refetch cleanup function to prevent memory leaks
-    const refetchCleanupRef = useRef(null);
-    const stableConfig = useMemo(() => {
-        const configKey = JSON.stringify(config);
-        if (configKey === lastConfigKeyRef.current) {
-            return lastConfigRef.current;
-        }
-        lastConfigKeyRef.current = configKey;
-        lastConfigRef.current = config;
-        return config;
-    }, [config]);
-    const stableOptions = useMemo(() => {
-        const optionsKey = JSON.stringify(options);
-        if (optionsKey === lastOptionsKeyRef.current) {
-            return lastOptionsRef.current;
-        }
-        lastOptionsKeyRef.current = optionsKey;
-        lastOptionsRef.current = options;
-        return options;
-    }, [options]);
+    const stableConfig = useStableValue(config);
+    const stableOptions = useStableValue(options);
     // Pagination actions
     const nextPage = useCallback(() => {
         const paginationFlags = calculatePaginationFlags(state.currentPage, state.hasMore);
@@ -156,122 +126,59 @@ function useAssociationsInternal(config, options = DEFAULT_OPTIONS) {
         }
     }, [state.currentPage, state.hasMore]);
     const reset = useCallback(() => {
-        dispatch({ type: 'RESET' });
-    }, []);
-    // Fetch the associations
-    useEffect(() => {
-        let cancelled = false;
-        let cleanup = null;
-        const fetchData = async () => {
-            try {
-                dispatch({ type: 'FETCH_START' });
-                // Build request using current offset token
-                const request = {
-                    toObjectType: stableConfig?.toObjectType,
-                    properties: stableConfig?.properties,
-                    pageLength: pageSize,
-                    offset: state.currentOffset,
-                };
-                const result = await fetchAssociations(request, {
-                    propertiesToFormat: stableOptions.propertiesToFormat,
-                    formattingOptions: stableOptions.formattingOptions,
-                });
-                if (!cancelled) {
-                    dispatch({
-                        type: 'FETCH_SUCCESS',
-                        payload: {
-                            results: result.data.results,
-                            hasMore: result.data.hasMore,
-                            nextOffset: result.data.nextOffset,
-                            currentOffset: state.currentOffset,
-                        },
-                    });
-                    cleanup = result.cleanup;
-                }
-            }
-            catch (err) {
-                if (!cancelled) {
-                    const errorData = err instanceof Error
-                        ? err
-                        : new Error('Failed to fetch associations');
-                    dispatch({ type: 'FETCH_ERROR', payload: errorData });
-                }
-            }
-        };
-        fetchData();
-        return () => {
-            cancelled = true;
-            // Call cleanup function to release resources
-            if (cleanup) {
-                cleanup();
-            }
-            // Clean up any active refetch subscription
-            if (refetchCleanupRef.current) {
-                refetchCleanupRef.current();
-                refetchCleanupRef.current = null;
-            }
-        };
-    }, [
-        stableConfig,
-        stableOptions,
-        state.currentPage,
-        state.currentOffset,
-        pageSize,
-    ]);
-    const refetch = useCallback(async () => {
-        if (refetchAbortRef.current) {
-            refetchAbortRef.current.cancelled = true;
-        }
-        if (refetchCleanupRef.current) {
-            refetchCleanupRef.current();
-            refetchCleanupRef.current = null;
+        const paginationFlags = calculatePaginationFlags(state.currentPage, state.hasMore);
+        // Only reset to first page if we're not already on the first page
+        if (paginationFlags.hasPreviousPage) {
+            dispatch({ type: 'RESET' });
         }
-        const abortSignal = { cancelled: false };
-        refetchAbortRef.current = abortSignal;
-        try {
-            dispatch({ type: 'REFETCH_START' });
-            // Build request using current offset token to refetch current page
+    }, [state.currentPage, state.hasMore]);
+    const { refetch } = useFetchLifecycle({
+        fetchFn: () => {
             const request = {
                 toObjectType: stableConfig?.toObjectType,
                 properties: stableConfig?.properties,
                 pageLength: pageSize,
                 offset: state.currentOffset,
             };
-            const result = await fetchAssociations(request, {
+            return fetchAssociations(request, {
                 propertiesToFormat: stableOptions.propertiesToFormat,
                 formattingOptions: stableOptions.formattingOptions,
             });
-            if (!abortSignal.cancelled) {
-                dispatch({
+        },
+        callbacks: {
+            onStart: ({ isRefetch }) => dispatch({ type: isRefetch ? 'REFETCH_START' : 'FETCH_START' }),
+            onSuccess: (data, { isRefetch }) => dispatch(isRefetch
+                ? {
                     type: 'REFETCH_SUCCESS',
                     payload: {
-                        results: result.data.results,
-                        hasMore: result.data.hasMore,
-                        nextOffset: result.data.nextOffset,
+                        results: data.results,
+                        hasMore: data.hasMore,
+                        nextOffset: data.nextOffset,
                     },
-                });
-                refetchCleanupRef.current = result.cleanup;
-            }
-            else {
-                if (result.cleanup) {
-                    result.cleanup();
                 }
-            }
-        }
-        catch (err) {
-            if (!abortSignal.cancelled) {
-                const errorData = err instanceof Error
-                    ? err
-                    : new Error('Failed to refetch associations');
-                dispatch({ type: 'REFETCH_ERROR', payload: errorData });
-            }
-        }
-        finally {
-            if (refetchAbortRef.current === abortSignal) {
-                refetchAbortRef.current = null;
-            }
-        }
-    }, [stableConfig, stableOptions, state.currentOffset, pageSize]);
+                : {
+                    type: 'FETCH_SUCCESS',
+                    payload: {
+                        results: data.results,
+                        hasMore: data.hasMore,
+                        nextOffset: data.nextOffset,
+                        currentOffset: state.currentOffset,
+                    },
+                }),
+            onError: (error, { isRefetch }) => dispatch({
+                type: isRefetch ? 'REFETCH_ERROR' : 'FETCH_ERROR',
+                payload: error,
+            }),
+        },
+        deps: [
+            stableConfig,
+            stableOptions,
+            state.currentPage,
+            state.currentOffset,
+            pageSize,
+        ],
+        defaultErrorMessage: 'Failed to fetch associations',
+    });
     // Calculate pagination flags
     const paginationFlags = calculatePaginationFlags(state.currentPage, state.hasMore);
     return {

package/dist/crm/hooks/useCrmProperties.js

@@ -1,5 +1,6 @@
-import { useCallback, useEffect, useMemo, useReducer, useRef } from 'react';
-import { createMockAwareHook } from "../../internal/hook-utils.js";
+import { useMemo, useReducer } from 'react';
+import { useFetchLifecycle } from "../../hooks/utils/useFetchLifecycle.js";
+import { createMockAwareHook, useStableValue, } from "../../internal/hook-utils.js";
 import { fetchCrmProperties } from "../utils/fetchCrmProperties.js";
 const initialState = {
     properties: {},
@@ -58,130 +59,33 @@ const DEFAULT_OPTIONS = {};
  */
 function useCrmPropertiesInternal(propertyNames, options = DEFAULT_OPTIONS) {
     const [state, dispatch] = useReducer(crmPropertiesReducer, initialState);
-    /**
-     * HOOK OPTIMIZATION:
-     *
-     * Create stable references for propertyNames and options to prevent unnecessary re-renders and API calls.
-     * Then, external developers can pass inline arrays/objects without worrying about memoization
-     * We handle the deep equality comparison ourselves, and return the same object reference when content is equivalent.
-     */
-    const lastPropertyNamesRef = useRef();
-    const lastPropertyNamesKeyRef = useRef();
-    const lastOptionsRef = useRef();
-    const lastOptionsKeyRef = useRef();
-    // Track in-flight refetch to support cancellation
-    const refetchAbortRef = useRef(null);
-    // Track refetch cleanup function to prevent memory leaks
-    const refetchCleanupRef = useRef(null);
-    const stablePropertyNames = useMemo(() => {
-        if (!Array.isArray(propertyNames)) {
-            return propertyNames;
-        }
-        const sortedNames = [...propertyNames].sort();
-        const propertyNamesKey = JSON.stringify(sortedNames);
-        if (propertyNamesKey === lastPropertyNamesKeyRef.current) {
-            return lastPropertyNamesRef.current;
-        }
-        lastPropertyNamesKeyRef.current = propertyNamesKey;
-        lastPropertyNamesRef.current = sortedNames;
-        return sortedNames;
-    }, [propertyNames]);
-    const stableOptions = useMemo(() => {
-        const optionsKey = JSON.stringify(options);
-        if (optionsKey === lastOptionsKeyRef.current) {
-            return lastOptionsRef.current;
-        }
-        lastOptionsKeyRef.current = optionsKey;
-        lastOptionsRef.current = options;
-        return options;
-    }, [options]);
-    // Fetch the properties
-    useEffect(() => {
-        let cancelled = false;
-        let cleanup = null;
-        const fetchData = async () => {
-            try {
-                dispatch({ type: 'FETCH_START' });
-                const result = await fetchCrmProperties(stablePropertyNames, (data) => {
-                    if (!cancelled) {
-                        dispatch({ type: 'FETCH_SUCCESS', payload: data });
-                    }
-                }, stableOptions);
-                if (!cancelled) {
-                    dispatch({ type: 'FETCH_SUCCESS', payload: result.data });
-                    cleanup = result.cleanup;
-                }
+    // Sort property names so that order doesn't matter for cache keys
+    const sortedPropertyNames = useMemo(() => Array.isArray(propertyNames) ? [...propertyNames].sort() : propertyNames, [propertyNames]);
+    const stablePropertyNames = useStableValue(sortedPropertyNames);
+    const stableOptions = useStableValue(options);
+    const { refetch } = useFetchLifecycle({
+        fetchFn: (signal) => fetchCrmProperties(stablePropertyNames, (data) => {
+            if (!signal.cancelled) {
+                dispatch({
+                    type: signal.isRefetch ? 'REFETCH_SUCCESS' : 'FETCH_SUCCESS',
+                    payload: data,
+                });
             }
-            catch (err) {
-                if (!cancelled) {
-                    const errorData = err instanceof Error
-                        ? err
-                        : new Error('Failed to fetch CRM properties');
-                    dispatch({ type: 'FETCH_ERROR', payload: errorData });
-                }
-            }
-        };
-        fetchData();
-        return () => {
-            cancelled = true;
-            // Call cleanup function to release RPC resources
-            if (cleanup) {
-                cleanup();
-            }
-            // Clean up any active refetch subscription
-            if (refetchCleanupRef.current) {
-                refetchCleanupRef.current();
-                refetchCleanupRef.current = null;
-            }
-        };
-    }, [stablePropertyNames, stableOptions]);
-    const refetch = useCallback(async () => {
-        // Cancel any in-flight refetch
-        if (refetchAbortRef.current) {
-            refetchAbortRef.current.cancelled = true;
-        }
-        // Clean up old refetch subscription to prevent memory leaks
-        if (refetchCleanupRef.current) {
-            refetchCleanupRef.current();
-            refetchCleanupRef.current = null;
-        }
-        // Create new abort signal for this refetch
-        const abortSignal = { cancelled: false };
-        refetchAbortRef.current = abortSignal;
-        try {
-            dispatch({ type: 'REFETCH_START' });
-            const result = await fetchCrmProperties(stablePropertyNames, (data) => {
-                if (!abortSignal.cancelled) {
-                    dispatch({ type: 'REFETCH_SUCCESS', payload: data });
-                }
-            }, stableOptions);
-            if (!abortSignal.cancelled) {
-                dispatch({ type: 'REFETCH_SUCCESS', payload: result.data });
-                // Store cleanup for next refetch or unmount
-                refetchCleanupRef.current = result.cleanup;
-            }
-            else {
-                // If cancelled, clean up immediately
-                if (result.cleanup) {
-                    result.cleanup();
-                }
-            }
-        }
-        catch (err) {
-            if (!abortSignal.cancelled) {
-                const errorData = err instanceof Error
-                    ? err
-                    : new Error('Failed to refetch CRM properties');
-                dispatch({ type: 'REFETCH_ERROR', payload: errorData });
-            }
-        }
-        finally {
-            // Clear the abort ref if this is still the current refetch
-            if (refetchAbortRef.current === abortSignal) {
-                refetchAbortRef.current = null;
-            }
-        }
-    }, [stablePropertyNames, stableOptions]);
+        }, stableOptions),
+        callbacks: {
+            onStart: ({ isRefetch }) => dispatch({ type: isRefetch ? 'REFETCH_START' : 'FETCH_START' }),
+            onSuccess: (data, { isRefetch }) => dispatch({
+                type: isRefetch ? 'REFETCH_SUCCESS' : 'FETCH_SUCCESS',
+                payload: data,
+            }),
+            onError: (error, { isRefetch }) => dispatch({
+                type: isRefetch ? 'REFETCH_ERROR' : 'FETCH_ERROR',
+                payload: error,
+            }),
+        },
+        deps: [stablePropertyNames, stableOptions],
+        defaultErrorMessage: 'Failed to fetch CRM properties',
+    });
     return {
         ...state,
         refetch,

package/dist/hooks/useDebounce.d.ts

@@ -0,0 +1,19 @@
+import type { JsonSerializable } from '../shared/types/shared.ts';
+/**
+ * Returns a debounced version of `value` that only updates after the value
+ * has stopped changing for `delayMs` milliseconds (default: 300ms).
+ *
+ * Useful for delaying expensive operations (e.g. search requests) until the
+ * user has finished typing.
+ *
+ * Object and array values are compared by deep equality (via `JSON.stringify`),
+ * so values must be JSON-serializable. Functions, Symbols, BigInts, and
+ * circular references are not supported.
+ *
+ * @example
+ * ```ts
+ * const [searchText, setSearchText] = useState('');
+ * const debouncedQuery = useDebounce(searchText, 200);
+ * ```
+ */
+export declare function useDebounce<T extends JsonSerializable>(value: T, delayMs?: number): T;

package/dist/hooks/useDebounce.js

@@ -0,0 +1,32 @@
+import { useEffect, useState } from 'react';
+import { useStableValue } from "../internal/hook-utils.js";
+/**
+ * Returns a debounced version of `value` that only updates after the value
+ * has stopped changing for `delayMs` milliseconds (default: 300ms).
+ *
+ * Useful for delaying expensive operations (e.g. search requests) until the
+ * user has finished typing.
+ *
+ * Object and array values are compared by deep equality (via `JSON.stringify`),
+ * so values must be JSON-serializable. Functions, Symbols, BigInts, and
+ * circular references are not supported.
+ *
+ * @example
+ * ```ts
+ * const [searchText, setSearchText] = useState('');
+ * const debouncedQuery = useDebounce(searchText, 200);
+ * ```
+ */
+export function useDebounce(value, delayMs = 300) {
+    const stableValue = useStableValue(value);
+    const [debouncedValue, setDebouncedValue] = useState(stableValue);
+    useEffect(() => {
+        const timer = setTimeout(() => {
+            setDebouncedValue(stableValue);
+        }, delayMs);
+        return () => {
+            clearTimeout(timer);
+        };
+    }, [stableValue, delayMs]);
+    return debouncedValue;
+}

package/dist/hooks/utils/useFetchLifecycle.d.ts

@@ -0,0 +1,35 @@
+export interface FetchSignal {
+    cancelled: boolean;
+    isRefetch: boolean;
+}
+export interface FetchResult<TData> {
+    data: TData;
+    cleanup?: () => void;
+}
+export interface FetchContext {
+    isRefetch: boolean;
+}
+export interface FetchLifecycleCallbacks<TData> {
+    onStart: (context: FetchContext) => void;
+    onSuccess: (data: TData, context: FetchContext) => void;
+    onError: (error: Error, context: FetchContext) => void;
+}
+export interface UseFetchLifecycleOptions<TData> {
+    fetchFn: (signal: FetchSignal) => Promise<FetchResult<TData>>;
+    callbacks: FetchLifecycleCallbacks<TData>;
+    deps: React.DependencyList;
+    defaultErrorMessage?: string;
+}
+export interface UseFetchLifecycleResult {
+    refetch: () => Promise<void>;
+}
+/**
+ * Shared fetch/refetch/cleanup/abort lifecycle for data hooks.
+ *
+ * Manages:
+ * - Initial fetch on mount and when deps change
+ * - Cancellation of in-flight fetches on unmount or deps change
+ * - Refetch with abort signal and cleanup tracking
+ * - Error normalization
+ */
+export declare function useFetchLifecycle<TData>({ fetchFn, callbacks, deps, defaultErrorMessage, }: UseFetchLifecycleOptions<TData>): UseFetchLifecycleResult;

package/dist/hooks/utils/useFetchLifecycle.js

@@ -0,0 +1,103 @@
+import { useCallback, useEffect, useRef } from 'react';
+function normalizeError(err, defaultMessage) {
+    return err instanceof Error ? err : new Error(defaultMessage);
+}
+/**
+ * Shared fetch/refetch/cleanup/abort lifecycle for data hooks.
+ *
+ * Manages:
+ * - Initial fetch on mount and when deps change
+ * - Cancellation of in-flight fetches on unmount or deps change
+ * - Refetch with abort signal and cleanup tracking
+ * - Error normalization
+ */
+export function useFetchLifecycle({ fetchFn, callbacks, deps, defaultErrorMessage = 'An error occurred', }) {
+    // Store latest versions in refs to avoid stale closures in refetch
+    const fetchFnRef = useRef(fetchFn);
+    fetchFnRef.current = fetchFn;
+    const callbacksRef = useRef(callbacks);
+    callbacksRef.current = callbacks;
+    const defaultErrorMessageRef = useRef(defaultErrorMessage);
+    defaultErrorMessageRef.current = defaultErrorMessage;
+    // Track in-flight refetch to support cancellation
+    const refetchAbortRef = useRef(null);
+    // Track refetch cleanup function to prevent memory leaks
+    const refetchCleanupRef = useRef(null);
+    useEffect(() => {
+        let cancelled = false;
+        let cleanup = null;
+        const signal = { cancelled: false, isRefetch: false };
+        const fetchData = async () => {
+            const context = { isRefetch: false };
+            try {
+                callbacksRef.current.onStart(context);
+                const result = await fetchFnRef.current(signal);
+                if (!cancelled) {
+                    callbacksRef.current.onSuccess(result.data, context);
+                    cleanup = result.cleanup ?? null;
+                }
+            }
+            catch (err) {
+                if (!cancelled) {
+                    callbacksRef.current.onError(normalizeError(err, defaultErrorMessageRef.current), context);
+                }
+            }
+        };
+        fetchData();
+        return () => {
+            cancelled = true;
+            signal.cancelled = true;
+            // Call cleanup function to release resources
+            if (cleanup) {
+                cleanup();
+            }
+            // Clean up any active refetch subscription
+            if (refetchCleanupRef.current) {
+                refetchCleanupRef.current();
+                refetchCleanupRef.current = null;
+            }
+        };
+    }, deps);
+    const refetch = useCallback(async () => {
+        // Cancel any in-flight refetch
+        if (refetchAbortRef.current) {
+            refetchAbortRef.current.cancelled = true;
+        }
+        // Clean up old refetch subscription to prevent memory leaks
+        if (refetchCleanupRef.current) {
+            refetchCleanupRef.current();
+            refetchCleanupRef.current = null;
+        }
+        // Create new abort signal for this refetch
+        const abortSignal = { cancelled: false, isRefetch: true };
+        refetchAbortRef.current = abortSignal;
+        const context = { isRefetch: true };
+        try {
+            callbacksRef.current.onStart(context);
+            const result = await fetchFnRef.current(abortSignal);
+            if (!abortSignal.cancelled) {
+                callbacksRef.current.onSuccess(result.data, context);
+                // Store cleanup for next refetch or unmount
+                refetchCleanupRef.current = result.cleanup ?? null;
+            }
+            else {
+                // If cancelled, clean up immediately
+                if (result.cleanup) {
+                    result.cleanup();
+                }
+            }
+        }
+        catch (err) {
+            if (!abortSignal.cancelled) {
+                callbacksRef.current.onError(normalizeError(err, defaultErrorMessageRef.current), context);
+            }
+        }
+        finally {
+            // Clear the abort ref if this is still the current refetch
+            if (refetchAbortRef.current === abortSignal) {
+                refetchAbortRef.current = null;
+            }
+        }
+    }, []);
+    return { refetch };
+}

package/dist/index.d.ts

@@ -3,6 +3,7 @@ export { hubspot } from './hubspot.ts';
 export { logger } from './logger.ts';
 export * from './shared/types/index.ts';
 export { Accordion, Alert, AutoGrid, BarChart, Box, Button, ButtonRow, Card, Checkbox, CurrencyInput, DateInput, DescriptionList, DescriptionListItem, Divider, Dropdown, EmptyState, ErrorState, Flex, Form, Heading, Icon, Illustration, Image, Inline, Input, LineChart, Link, List, LoadingButton, LoadingSpinner, Modal, ModalBody, ModalFooter, MultiSelect, NumberInput, Panel, PanelBody, PanelFooter, PanelSection, ProgressBar, RadioButton, ScoreCircle, SearchInput, Select, Spacer, Stack, Statistics, StatisticsItem, StatisticsTrend, StatusTag, StepIndicator, StepperInput, Tab, Table, TableBody, TableCell, TableFooter, TableHead, TableHeader, TableRow, Tabs, Tag, Text, TextArea, Textarea, Tile, TimeInput, Toggle, ToggleGroup, Tooltip, } from './shared/remoteComponents.tsx';
+export { useDebounce } from './hooks/useDebounce.ts';
 export { useExtensionContext } from './hooks/useExtensionContext.tsx';
 export { useExtensionActions } from './hooks/useExtensionActions.tsx';
 export { useExtensionApi } from './hooks/useExtensionApi.tsx';

package/dist/index.js

@@ -4,6 +4,7 @@ export { hubspot } from "./hubspot.js";
 export { logger } from "./logger.js";
 export * from "./shared/types/index.js";
 export { Accordion, Alert, AutoGrid, BarChart, Box, Button, ButtonRow, Card, Checkbox, CurrencyInput, DateInput, DescriptionList, DescriptionListItem, Divider, Dropdown, EmptyState, ErrorState, Flex, Form, Heading, Icon, Illustration, Image, Inline, Input, LineChart, Link, List, LoadingButton, LoadingSpinner, Modal, ModalBody, ModalFooter, MultiSelect, NumberInput, Panel, PanelBody, PanelFooter, PanelSection, ProgressBar, RadioButton, ScoreCircle, SearchInput, Select, Spacer, Stack, Statistics, StatisticsItem, StatisticsTrend, StatusTag, StepIndicator, StepperInput, Tab, Table, TableBody, TableCell, TableFooter, TableHead, TableHeader, TableRow, Tabs, Tag, Text, TextArea, Textarea, Tile, TimeInput, Toggle, ToggleGroup, Tooltip, } from "./shared/remoteComponents.js";
+export { useDebounce } from "./hooks/useDebounce.js";
 export { useExtensionContext } from "./hooks/useExtensionContext.js";
 export { useExtensionActions } from "./hooks/useExtensionActions.js";
 export { useExtensionApi } from "./hooks/useExtensionApi.js";

package/dist/internal/hook-utils.d.ts

@@ -1,3 +1,4 @@
+import type { JsonSerializable } from '../shared/types/shared.ts';
 import type { RendererMocksContext } from '../testing/internal/mocks/index.ts';
 import type { RendererMocks } from '../testing/types.ts';
 type AnyFunction = (...args: any[]) => any;
@@ -24,4 +25,9 @@ export declare function useMocksContext(): RendererMocksContext | null;
  * @returns The children wrapped in the Mocks context provider.
  */
 export declare const MocksContextProvider: import("react").Provider<RendererMocksContext | null>;
+/**
+ * Stabilizes a value's reference identity across re-renders using deep
+ * comparison via JSON.stringify.
+ */
+export declare function useStableValue<T extends JsonSerializable>(value: T): T;
 export {};

package/dist/internal/hook-utils.js

@@ -1,4 +1,4 @@
-import { createContext, useContext } from 'react';
+import { createContext, useContext, useRef } from 'react';
 const ReactRenderMocksContext = createContext(null);
 /**
  * Creates a mock-aware hook function that can be used to mock the original hook function.
@@ -40,3 +40,18 @@ export function useMocksContext() {
  * @returns The children wrapped in the Mocks context provider.
  */
 export const MocksContextProvider = ReactRenderMocksContext.Provider;
+/**
+ * Stabilizes a value's reference identity across re-renders using deep
+ * comparison via JSON.stringify.
+ */
+export function useStableValue(value) {
+    const stableRef = useRef({
+        key: JSON.stringify(value),
+        value,
+    });
+    const key = JSON.stringify(value);
+    if (key !== stableRef.current.key) {
+        stableRef.current = { key, value };
+    }
+    return stableRef.current.value;
+}

package/dist/{experimental/pages → pages}/components/page-routes.d.ts

@@ -1,5 +1,5 @@
 import type { ComponentType, ReactNode } from 'react';
-import type { EmptyProps } from '../../../shared/types/shared.ts';
+import type { EmptyProps } from '../../shared/types/shared.ts';
 /**
  * The props type for the layout component of [PageRoutes](https://developers.hubspot.com/docs/apps/developer-platform/add-features/ui-extensibility/ui-components/app-page-components/page-routes#pageroutes).
  */
@@ -72,7 +72,6 @@ export interface PageRoutesProps {
  *
  * See [PageRoutes](https://developers.hubspot.com/docs/apps/developer-platform/add-features/ui-extensibility/ui-components/app-page-components/page-routes#pageroutes) for more information.
  *
- * @experimental This component is experimental. Avoid using it in production due to potential breaking changes. Your feedback is valuable for improvements. Stay tuned for updates.
  */
 export declare function PageRoutes(__props: PageRoutesProps): null;
 export declare namespace PageRoutes {