@hubspot/ui-extensions 0.12.3 → 0.13.0

package/dist/__tests__/crm/hooks/useAssociations.spec.js

@@ -284,6 +284,34 @@ describe('useAssociations with Pagination', () => {
                 expect(result.current.pagination.hasPreviousPage).toBe(false);
             });
         });
+        it('should not reset if already on first page', async () => {
+            mockFetchAssociations.mockResolvedValueOnce({
+                data: {
+                    results: [{ toObjectId: 1, associationTypes: [], properties: {} }],
+                    hasMore: true,
+                    nextOffset: 10,
+                },
+                cleanup: vi.fn(),
+            });
+            const { result } = renderHook(() => useAssociations({
+                toObjectType: '0-1',
+                pageLength: 10,
+            }));
+            // Wait for initial load
+            await waitFor(() => {
+                expect(result.current.pagination.currentPage).toBe(1);
+            });
+            // Try to reset while on first page
+            result.current.pagination.reset();
+            await waitFor(() => {
+                expect(result.current.pagination.currentPage).toBe(1);
+            });
+            // Verify results were not wiped and API was not called again
+            expect(result.current.results).toEqual([
+                { toObjectId: 1, associationTypes: [], properties: {} },
+            ]);
+            expect(mockFetchAssociations).toHaveBeenCalledTimes(1);
+        });
         it('should not allow navigation beyond boundaries', async () => {
             mockFetchAssociations.mockResolvedValue({
                 data: {

package/dist/__tests__/crm/utils/fetchAssociations.spec.js

@@ -1,5 +1,6 @@
 import { vi } from 'vitest';
-import { calculatePaginationFlags, fetchAssociations, } from "../../../crm/utils/fetchAssociations.js";
+import { fetchAssociations } from "../../../crm/utils/fetchAssociations.js";
+import { calculatePaginationFlags } from "../../../utils/pagination.js";
 // Set up the mock before importing the module
 const mockFetchAssociations = vi.fn();
 const mockSelf = {

package/dist/__tests__/hooks/useDebounce.spec.js

@@ -0,0 +1,123 @@
+import { renderHook } from '@testing-library/react';
+import { act } from 'react';
+import { vi } from 'vitest';
+import { useDebounce } from "../../hooks/useDebounce.js";
+describe('useDebounce', () => {
+    beforeEach(() => {
+        vi.useFakeTimers();
+    });
+    afterEach(() => {
+        vi.useRealTimers();
+    });
+    it('should return the initial value immediately', () => {
+        const { result } = renderHook(() => useDebounce('hello', 300));
+        expect(result.current).toBe('hello');
+    });
+    it('should not update the value before the delay has elapsed', () => {
+        const { result, rerender } = renderHook(({ value, delay }) => useDebounce(value, delay), { initialProps: { value: 'initial', delay: 300 } });
+        rerender({ value: 'updated', delay: 300 });
+        act(() => {
+            vi.advanceTimersByTime(299);
+        });
+        expect(result.current).toBe('initial');
+    });
+    it('should update the value after the delay has elapsed', () => {
+        const { result, rerender } = renderHook(({ value, delay }) => useDebounce(value, delay), { initialProps: { value: 'initial', delay: 300 } });
+        rerender({ value: 'updated', delay: 300 });
+        act(() => {
+            vi.advanceTimersByTime(300);
+        });
+        expect(result.current).toBe('updated');
+    });
+    it('should only propagate the last value when changed rapidly', () => {
+        const { result, rerender } = renderHook(({ value, delay }) => useDebounce(value, delay), { initialProps: { value: 'a', delay: 300 } });
+        rerender({ value: 'ab', delay: 300 });
+        act(() => {
+            vi.advanceTimersByTime(100);
+        });
+        rerender({ value: 'abc', delay: 300 });
+        act(() => {
+            vi.advanceTimersByTime(300);
+        });
+        expect(result.current).toBe('abc');
+    });
+    it('should reset the timer when the delay changes', () => {
+        const { result, rerender } = renderHook(({ value, delay }) => useDebounce(value, delay), { initialProps: { value: 'initial', delay: 300 } });
+        rerender({ value: 'updated', delay: 300 });
+        act(() => {
+            vi.advanceTimersByTime(200);
+        });
+        // Change the delay — timer should restart
+        rerender({ value: 'updated', delay: 500 });
+        act(() => {
+            vi.advanceTimersByTime(300);
+        });
+        // 200 + 300 = 500ms total, but timer restarted at 200ms so only 300ms of 500ms elapsed
+        expect(result.current).toBe('initial');
+        act(() => {
+            vi.advanceTimersByTime(200);
+        });
+        expect(result.current).toBe('updated');
+    });
+    it('should clean up the timeout on unmount', () => {
+        const { result, rerender, unmount } = renderHook(({ value, delay }) => useDebounce(value, delay), { initialProps: { value: 'initial', delay: 300 } });
+        rerender({ value: 'updated', delay: 300 });
+        unmount();
+        // Advancing timers after unmount should not cause errors
+        act(() => {
+            vi.advanceTimersByTime(300);
+        });
+        expect(result.current).toBe('initial');
+    });
+    it('should work with numeric values', () => {
+        const { result, rerender } = renderHook(({ value, delay }) => useDebounce(value, delay), { initialProps: { value: 0, delay: 200 } });
+        rerender({ value: 42, delay: 200 });
+        act(() => {
+            vi.advanceTimersByTime(200);
+        });
+        expect(result.current).toBe(42);
+    });
+    it('should not reset the timer when an object value is deeply equal', () => {
+        const { result, rerender } = renderHook(({ value, delay }) => useDebounce(value, delay), { initialProps: { value: { query: 'a' }, delay: 300 } });
+        // Change the value
+        rerender({ value: { query: 'ab' }, delay: 300 });
+        act(() => {
+            vi.advanceTimersByTime(200);
+        });
+        // Pass a new reference with the same content — should NOT reset the timer
+        rerender({ value: { query: 'ab' }, delay: 300 });
+        act(() => {
+            vi.advanceTimersByTime(100);
+        });
+        // 200 + 100 = 300ms total — should have fired because the new reference didn't reset
+        expect(result.current).toEqual({ query: 'ab' });
+    });
+    it('should debounce when object content actually changes', () => {
+        const { result, rerender } = renderHook(({ value, delay }) => useDebounce(value, delay), { initialProps: { value: { query: 'a' }, delay: 300 } });
+        rerender({ value: { query: 'ab' }, delay: 300 });
+        act(() => {
+            vi.advanceTimersByTime(200);
+        });
+        // Actual content change — should reset the timer
+        rerender({ value: { query: 'abc' }, delay: 300 });
+        act(() => {
+            vi.advanceTimersByTime(200);
+        });
+        // Only 200ms since the real change — should still be the initial value
+        expect(result.current).toEqual({ query: 'a' });
+        act(() => {
+            vi.advanceTimersByTime(100);
+        });
+        expect(result.current).toEqual({ query: 'abc' });
+    });
+    it('should still defer by one render cycle when delayMs is 0', () => {
+        const { result, rerender } = renderHook(({ value, delay }) => useDebounce(value, delay), { initialProps: { value: 'initial', delay: 0 } });
+        rerender({ value: 'updated', delay: 0 });
+        // useEffect is async, so even with delay 0 the value is stale for one cycle
+        expect(result.current).toBe('initial');
+        act(() => {
+            vi.advanceTimersByTime(0);
+        });
+        expect(result.current).toBe('updated');
+    });
+});

package/dist/__tests__/hooks/utils/useFetchLifecycle.spec.js

@@ -0,0 +1,324 @@
+import { renderHook, waitFor } from '@testing-library/react';
+import { vi } from 'vitest';
+import { useFetchLifecycle, } from "../../../hooks/utils/useFetchLifecycle.js";
+function createMockCallbacks() {
+    return {
+        onStart: vi.fn(),
+        onSuccess: vi.fn(),
+        onError: vi.fn(),
+    };
+}
+describe('useFetchLifecycle', () => {
+    let originalError;
+    beforeAll(() => {
+        // Suppress React act() warnings coming from @testing-library/react
+        originalError = console.error;
+        console.error = (...args) => {
+            if (typeof args[0] === 'string' &&
+                (args[0].includes('ReactDOMTestUtils.act') ||
+                    args[0].includes('was not wrapped in act')))
+                return;
+            originalError.call(console, ...args);
+        };
+    });
+    afterAll(() => {
+        console.error = originalError;
+    });
+    describe('initial fetch', () => {
+        it('should call onStart then onSuccess on successful fetch', async () => {
+            const callbacks = createMockCallbacks();
+            const mockData = { name: 'test' };
+            const mockFetchFn = vi.fn().mockResolvedValue({
+                data: mockData,
+                cleanup: vi.fn(),
+            });
+            renderHook(() => useFetchLifecycle({
+                fetchFn: mockFetchFn,
+                callbacks,
+                deps: [],
+            }));
+            await waitFor(() => {
+                expect(callbacks.onStart).toHaveBeenCalledWith({ isRefetch: false });
+                expect(callbacks.onSuccess).toHaveBeenCalledWith(mockData, {
+                    isRefetch: false,
+                });
+                expect(callbacks.onError).not.toHaveBeenCalled();
+            });
+        });
+        it('should call onError when fetch rejects with an Error', async () => {
+            const callbacks = createMockCallbacks();
+            const error = new Error('Network failure');
+            const mockFetchFn = vi.fn().mockRejectedValue(error);
+            renderHook(() => useFetchLifecycle({
+                fetchFn: mockFetchFn,
+                callbacks,
+                deps: [],
+            }));
+            await waitFor(() => {
+                expect(callbacks.onError).toHaveBeenCalledWith(error, {
+                    isRefetch: false,
+                });
+                expect(callbacks.onSuccess).not.toHaveBeenCalled();
+            });
+        });
+        it('should use defaultErrorMessage for non-Error rejections', async () => {
+            const callbacks = createMockCallbacks();
+            const mockFetchFn = vi.fn().mockRejectedValue('string error');
+            renderHook(() => useFetchLifecycle({
+                fetchFn: mockFetchFn,
+                callbacks,
+                deps: [],
+                defaultErrorMessage: 'Custom error message',
+            }));
+            await waitFor(() => {
+                expect(callbacks.onError).toHaveBeenCalledTimes(1);
+                const [error] = callbacks.onError.mock.calls[0];
+                expect(error).toBeInstanceOf(Error);
+                expect(error.message).toBe('Custom error message');
+            });
+        });
+        it('should pass signal with isRefetch=false to fetchFn during initial fetch', async () => {
+            const callbacks = createMockCallbacks();
+            let capturedSignal;
+            const mockFetchFn = vi.fn().mockImplementation((signal) => {
+                capturedSignal = signal;
+                return Promise.resolve({ data: 'test' });
+            });
+            renderHook(() => useFetchLifecycle({
+                fetchFn: mockFetchFn,
+                callbacks,
+                deps: [],
+            }));
+            await waitFor(() => {
+                expect(capturedSignal).toBeDefined();
+                expect(capturedSignal?.isRefetch).toBe(false);
+                expect(capturedSignal?.cancelled).toBe(false);
+            });
+        });
+    });
+    describe('cleanup', () => {
+        it('should call cleanup function when component unmounts', async () => {
+            const callbacks = createMockCallbacks();
+            const mockCleanup = vi.fn();
+            const mockFetchFn = vi.fn().mockResolvedValue({
+                data: 'test',
+                cleanup: mockCleanup,
+            });
+            const { unmount } = renderHook(() => useFetchLifecycle({
+                fetchFn: mockFetchFn,
+                callbacks,
+                deps: [],
+            }));
+            await waitFor(() => {
+                expect(callbacks.onSuccess).toHaveBeenCalled();
+            });
+            unmount();
+            expect(mockCleanup).toHaveBeenCalledTimes(1);
+        });
+        it('should call cleanup when deps change and start new fetch', async () => {
+            const callbacks = createMockCallbacks();
+            const mockCleanup1 = vi.fn();
+            const mockCleanup2 = vi.fn();
+            const mockFetchFn = vi
+                .fn()
+                .mockResolvedValueOnce({ data: 'first', cleanup: mockCleanup1 })
+                .mockResolvedValueOnce({ data: 'second', cleanup: mockCleanup2 });
+            const { rerender } = renderHook(({ dep }) => useFetchLifecycle({
+                fetchFn: mockFetchFn,
+                callbacks,
+                deps: [dep],
+            }), { initialProps: { dep: 'a' } });
+            await waitFor(() => {
+                expect(mockFetchFn).toHaveBeenCalledTimes(1);
+            });
+            rerender({ dep: 'b' });
+            await waitFor(() => {
+                expect(mockFetchFn).toHaveBeenCalledTimes(2);
+                expect(mockCleanup1).toHaveBeenCalledTimes(1);
+            });
+        });
+        it('should not call onFetchSuccess when fetch resolves after cancellation', async () => {
+            const callbacks = createMockCallbacks();
+            let resolveFirst = () => { };
+            const firstFetchPromise = new Promise((resolve) => {
+                resolveFirst = resolve;
+            });
+            const mockFetchFn = vi
+                .fn()
+                .mockImplementationOnce(() => firstFetchPromise)
+                .mockResolvedValueOnce({ data: 'second' });
+            const { rerender } = renderHook(({ dep }) => useFetchLifecycle({
+                fetchFn: mockFetchFn,
+                callbacks,
+                deps: [dep],
+            }), { initialProps: { dep: 'a' } });
+            // Change deps before first fetch resolves
+            rerender({ dep: 'b' });
+            // Now resolve the first fetch
+            resolveFirst({ data: 'first', cleanup: vi.fn() });
+            await waitFor(() => {
+                expect(mockFetchFn).toHaveBeenCalledTimes(2);
+            });
+            // onSuccess should have been called with 'second' (from the second fetch), not 'first'
+            // onStart is called twice (once per fetch)
+            expect(callbacks.onStart).toHaveBeenCalledTimes(2);
+            expect(callbacks.onSuccess).toHaveBeenCalledWith('second', {
+                isRefetch: false,
+            });
+            // It should NOT have been called with 'first' (cancelled)
+            expect(callbacks.onSuccess).not.toHaveBeenCalledWith('first', expect.anything());
+        });
+    });
+    describe('refetch', () => {
+        it('should call onStart and onSuccess with isRefetch=true on successful refetch', async () => {
+            const callbacks = createMockCallbacks();
+            const mockFetchFn = vi
+                .fn()
+                .mockResolvedValueOnce({ data: 'initial', cleanup: vi.fn() })
+                .mockResolvedValueOnce({ data: 'refetched', cleanup: vi.fn() });
+            const { result } = renderHook(() => useFetchLifecycle({
+                fetchFn: mockFetchFn,
+                callbacks,
+                deps: [],
+            }));
+            await waitFor(() => {
+                expect(callbacks.onSuccess).toHaveBeenCalled();
+            });
+            await result.current.refetch();
+            // onStart called twice: once for fetch, once for refetch
+            expect(callbacks.onStart).toHaveBeenCalledTimes(2);
+            expect(callbacks.onStart).toHaveBeenLastCalledWith({ isRefetch: true });
+            expect(callbacks.onSuccess).toHaveBeenCalledWith('refetched', {
+                isRefetch: true,
+            });
+        });
+        it('should call onError with isRefetch=true when refetch fails', async () => {
+            const callbacks = createMockCallbacks();
+            const error = new Error('Refetch failed');
+            const mockFetchFn = vi
+                .fn()
+                .mockResolvedValueOnce({ data: 'initial', cleanup: vi.fn() })
+                .mockRejectedValueOnce(error);
+            const { result } = renderHook(() => useFetchLifecycle({
+                fetchFn: mockFetchFn,
+                callbacks,
+                deps: [],
+            }));
+            await waitFor(() => {
+                expect(callbacks.onSuccess).toHaveBeenCalled();
+            });
+            await result.current.refetch();
+            expect(callbacks.onError).toHaveBeenCalledWith(error, {
+                isRefetch: true,
+            });
+        });
+        it('should pass signal with isRefetch=true to fetchFn during refetch', async () => {
+            const callbacks = createMockCallbacks();
+            const capturedSignals = [];
+            const mockFetchFn = vi.fn().mockImplementation((signal) => {
+                capturedSignals.push({ ...signal });
+                return Promise.resolve({ data: 'test', cleanup: vi.fn() });
+            });
+            const { result } = renderHook(() => useFetchLifecycle({
+                fetchFn: mockFetchFn,
+                callbacks,
+                deps: [],
+            }));
+            await waitFor(() => {
+                expect(callbacks.onSuccess).toHaveBeenCalled();
+            });
+            await result.current.refetch();
+            expect(capturedSignals).toHaveLength(2);
+            expect(capturedSignals[0].isRefetch).toBe(false); // initial fetch
+            expect(capturedSignals[1].isRefetch).toBe(true); // refetch
+        });
+        it('should cancel in-flight refetch when called again', async () => {
+            const callbacks = createMockCallbacks();
+            const firstRefetchCleanup = vi.fn();
+            const secondRefetchCleanup = vi.fn();
+            const mockFetchFn = vi
+                .fn()
+                .mockResolvedValueOnce({ data: 'initial', cleanup: vi.fn() })
+                .mockResolvedValueOnce({
+                data: 'first-refetch',
+                cleanup: firstRefetchCleanup,
+            })
+                .mockResolvedValueOnce({
+                data: 'second-refetch',
+                cleanup: secondRefetchCleanup,
+            });
+            const { result } = renderHook(() => useFetchLifecycle({
+                fetchFn: mockFetchFn,
+                callbacks,
+                deps: [],
+            }));
+            await waitFor(() => {
+                expect(callbacks.onSuccess).toHaveBeenCalled();
+            });
+            // Call refetch twice rapidly
+            const first = result.current.refetch();
+            const second = result.current.refetch();
+            await Promise.all([first, second]);
+            // Second refetch should win
+            expect(callbacks.onSuccess).toHaveBeenCalledWith('second-refetch', {
+                isRefetch: true,
+            });
+            // First refetch's cleanup should have been called (cancelled)
+            expect(firstRefetchCleanup).toHaveBeenCalledTimes(1);
+            // Second refetch's cleanup should NOT be called yet
+            expect(secondRefetchCleanup).not.toHaveBeenCalled();
+        });
+        it('should clean up previous refetch subscription when starting new refetch', async () => {
+            const callbacks = createMockCallbacks();
+            const firstRefetchCleanup = vi.fn();
+            const mockFetchFn = vi
+                .fn()
+                .mockResolvedValueOnce({ data: 'initial', cleanup: vi.fn() })
+                .mockResolvedValueOnce({
+                data: 'first-refetch',
+                cleanup: firstRefetchCleanup,
+            })
+                .mockResolvedValueOnce({
+                data: 'second-refetch',
+                cleanup: vi.fn(),
+            });
+            const { result } = renderHook(() => useFetchLifecycle({
+                fetchFn: mockFetchFn,
+                callbacks,
+                deps: [],
+            }));
+            await waitFor(() => {
+                expect(callbacks.onSuccess).toHaveBeenCalled();
+            });
+            // First refetch completes normally
+            await result.current.refetch();
+            expect(firstRefetchCleanup).not.toHaveBeenCalled();
+            // Second refetch should clean up first refetch's subscription
+            await result.current.refetch();
+            expect(firstRefetchCleanup).toHaveBeenCalledTimes(1);
+        });
+        it('should clean up refetch subscription on unmount', async () => {
+            const callbacks = createMockCallbacks();
+            const refetchCleanup = vi.fn();
+            const mockFetchFn = vi
+                .fn()
+                .mockResolvedValueOnce({ data: 'initial', cleanup: vi.fn() })
+                .mockResolvedValueOnce({
+                data: 'refetched',
+                cleanup: refetchCleanup,
+            });
+            const { result, unmount } = renderHook(() => useFetchLifecycle({
+                fetchFn: mockFetchFn,
+                callbacks,
+                deps: [],
+            }));
+            await waitFor(() => {
+                expect(callbacks.onSuccess).toHaveBeenCalled();
+            });
+            await result.current.refetch();
+            expect(refetchCleanup).not.toHaveBeenCalled();
+            unmount();
+            expect(refetchCleanup).toHaveBeenCalledTimes(1);
+        });
+    });
+});

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

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/internal/hook-utils.spec.js

@@ -0,0 +1,17 @@
+import { renderHook } from '@testing-library/react';
+import { useStableValue } from "../../internal/hook-utils.js";
+describe('useStableValue', () => {
+    it('should preserve reference for deeply equal objects', () => {
+        const { result, rerender } = renderHook(({ value }) => useStableValue(value), { initialProps: { value: { a: 1, b: [2, 3] } } });
+        const firstRef = result.current;
+        rerender({ value: { a: 1, b: [2, 3] } });
+        expect(result.current).toBe(firstRef);
+    });
+    it('should return a new reference when content changes', () => {
+        const { result, rerender } = renderHook(({ value }) => useStableValue(value), { initialProps: { value: { a: 1 } } });
+        const firstRef = result.current;
+        rerender({ value: { a: 2 } });
+        expect(result.current).not.toBe(firstRef);
+        expect(result.current).toEqual({ a: 2 });
+    });
+});

package/dist/__tests__/test-d/extension-points.test-d.js

@@ -5,6 +5,7 @@ expectAssignable({
         addAlert: () => { },
         copyTextToClipboard: async () => { },
         closeOverlay: () => { },
+        navigateToPage: () => { },
         reloadPage: () => { },
         openIframeModal: () => { },
     },

package/dist/crm/hooks/useAssociations.d.ts

@@ -1,24 +1,16 @@
+import { type PaginationResult } from '../../utils/pagination.ts';
 import type { AssociationResult, FetchAssociationsRequest } from '../utils/fetchAssociations.ts';
 import { type FetchCrmPropertiesOptions } from '../utils/fetchCrmProperties.ts';
-export interface UseAssociationsOptions {
+export type UseAssociationsOptions = {
     propertiesToFormat?: 'all' | string[];
     formattingOptions?: FetchCrmPropertiesOptions['formattingOptions'];
-}
-export interface UseAssociationsPagination {
-    hasNextPage: boolean;
-    hasPreviousPage: boolean;
-    currentPage: number;
-    pageSize: number;
-    nextPage: () => void;
-    previousPage: () => void;
-    reset: () => void;
-}
+};
 export interface UseAssociationsResult {
     results: AssociationResult[];
     error: Error | null;
     isLoading: boolean;
     isRefetching: boolean;
-    pagination: UseAssociationsPagination;
+    pagination: PaginationResult;
     refetch: () => Promise<void>;
 }
 /**