@hubspot/ui-extensions 0.9.3 → 0.9.5

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

@@ -0,0 +1,419 @@
+import { renderHook, waitFor } from '@testing-library/react';
+import { useAssociations } from '../../../experimental/hooks/useAssociations';
+import { fetchAssociations } from '../../../experimental/crm/fetchAssociations';
+// Mock the logger module
+jest.mock('../../../logger', () => ({
+    logger: {
+        debug: jest.fn(),
+        info: jest.fn(),
+        warn: jest.fn(),
+        error: jest.fn(),
+    },
+}));
+// Mock the fetchAssociations function, keep utility functions
+jest.mock('../../../experimental/crm/fetchAssociations', () => ({
+    ...jest.requireActual('../../../experimental/crm/fetchAssociations'),
+    fetchAssociations: jest.fn(),
+}));
+// Get reference to the mocked function
+const mockFetchAssociations = fetchAssociations;
+describe('useAssociations with Pagination', () => {
+    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);
+        };
+    });
+    beforeEach(() => {
+        // Reset the mock before each test
+        mockFetchAssociations.mockReset();
+    });
+    afterAll(() => {
+        console.error = originalError;
+    });
+    describe('initial state', () => {
+        it('should initialize with proper pagination state', async () => {
+            mockFetchAssociations.mockResolvedValue({
+                data: {
+                    results: [],
+                    hasMore: false,
+                    nextOffset: 0,
+                },
+                cleanup: jest.fn(),
+            });
+            const { result } = renderHook(() => useAssociations({
+                toObjectType: '0-1',
+                properties: ['firstname', 'lastname'],
+                pageLength: 10,
+            }));
+            await waitFor(() => {
+                expect(result.current.results).toEqual([]);
+                expect(result.current.error).toBeNull();
+                expect(result.current.isLoading).toBe(false);
+                expect(result.current.pagination.currentPage).toBe(1);
+                expect(result.current.pagination.pageSize).toBe(10);
+                expect(result.current.pagination.hasNextPage).toBe(false);
+                expect(result.current.pagination.hasPreviousPage).toBe(false);
+            });
+        });
+        it('should use default page size when not specified', async () => {
+            mockFetchAssociations.mockResolvedValue({
+                data: {
+                    results: [],
+                    hasMore: false,
+                    nextOffset: 0,
+                },
+                cleanup: jest.fn(),
+            });
+            const { result } = renderHook(() => useAssociations({
+                toObjectType: '0-1',
+                properties: ['firstname'],
+            }));
+            await waitFor(() => {
+                expect(result.current.pagination.pageSize).toBe(10); // DEFAULT_PAGE_SIZE
+            });
+        });
+    });
+    describe('data fetching', () => {
+        it('should successfully fetch and return associations with pagination info', async () => {
+            mockFetchAssociations.mockResolvedValue({
+                data: {
+                    results: [
+                        {
+                            toObjectId: 1001,
+                            associationTypes: [
+                                { category: 'HUBSPOT_DEFINED', typeId: 1, label: 'Primary' },
+                            ],
+                            properties: {
+                                firstname: 'John',
+                                lastname: 'Doe',
+                            },
+                        },
+                    ],
+                    hasMore: true,
+                    nextOffset: 10,
+                },
+                cleanup: jest.fn(),
+            });
+            const { result } = renderHook(() => useAssociations({
+                toObjectType: '0-1',
+                properties: ['firstname', 'lastname'],
+                pageLength: 10,
+            }));
+            await waitFor(() => {
+                expect(result.current.results).toHaveLength(1);
+                expect(result.current.results[0].toObjectId).toBe(1001);
+                expect(result.current.pagination.hasNextPage).toBe(true);
+                expect(result.current.pagination.hasPreviousPage).toBe(false);
+                expect(result.current.pagination.currentPage).toBe(1);
+                expect(result.current.isLoading).toBe(false);
+            });
+            expect(mockFetchAssociations).toHaveBeenCalledWith(expect.objectContaining({
+                toObjectType: '0-1',
+                properties: ['firstname', 'lastname'],
+                pageLength: 10,
+                offset: 0,
+            }), expect.any(Object));
+        });
+        it('should handle empty results correctly', async () => {
+            mockFetchAssociations.mockResolvedValue({
+                data: {
+                    results: [],
+                    hasMore: false,
+                    nextOffset: 0,
+                },
+                cleanup: jest.fn(),
+            });
+            const { result } = renderHook(() => useAssociations({
+                toObjectType: '0-1',
+                properties: ['firstname'],
+                pageLength: 5,
+            }));
+            await waitFor(() => {
+                expect(result.current.results).toEqual([]);
+                expect(result.current.pagination.hasNextPage).toBe(false);
+                expect(result.current.pagination.hasPreviousPage).toBe(false);
+                expect(result.current.isLoading).toBe(false);
+                expect(result.current.error).toBeNull();
+            });
+        });
+    });
+    describe('pagination actions', () => {
+        it('should navigate to next page correctly', async () => {
+            // First page response
+            mockFetchAssociations.mockResolvedValueOnce({
+                data: {
+                    results: [{ toObjectId: 1, associationTypes: [], properties: {} }],
+                    hasMore: true,
+                    nextOffset: 10,
+                },
+                cleanup: jest.fn(),
+            });
+            // Second page response
+            mockFetchAssociations.mockResolvedValueOnce({
+                data: {
+                    results: [{ toObjectId: 2, associationTypes: [], properties: {} }],
+                    hasMore: false,
+                    nextOffset: 20,
+                },
+                cleanup: jest.fn(),
+            });
+            const { result } = renderHook(() => useAssociations({
+                toObjectType: '0-1',
+                pageLength: 10,
+            }));
+            // Wait for initial load
+            await waitFor(() => {
+                expect(result.current.pagination.currentPage).toBe(1);
+                expect(result.current.pagination.hasNextPage).toBe(true);
+            });
+            // Navigate to next page
+            result.current.pagination.nextPage();
+            await waitFor(() => {
+                expect(result.current.pagination.currentPage).toBe(2);
+                expect(result.current.pagination.hasNextPage).toBe(false);
+                expect(result.current.pagination.hasPreviousPage).toBe(true);
+            });
+            // Verify API was called with correct offset for page 2
+            expect(mockFetchAssociations).toHaveBeenLastCalledWith(expect.objectContaining({
+                offset: 10, // (page 2 - 1) * pageSize 10 = 10
+            }), expect.any(Object));
+        });
+        it('should navigate to previous page correctly', async () => {
+            // First call: page 1 with hasMore: true (allows next page)
+            mockFetchAssociations.mockResolvedValueOnce({
+                data: {
+                    results: [{ toObjectId: 1, associationTypes: [], properties: {} }],
+                    hasMore: true,
+                    nextOffset: 10,
+                },
+                cleanup: jest.fn(),
+            });
+            // Second call: page 2 with hasMore: false
+            mockFetchAssociations.mockResolvedValueOnce({
+                data: {
+                    results: [{ toObjectId: 2, associationTypes: [], properties: {} }],
+                    hasMore: false,
+                    nextOffset: 20,
+                },
+                cleanup: jest.fn(),
+            });
+            // Third call: back to page 1
+            mockFetchAssociations.mockResolvedValueOnce({
+                data: {
+                    results: [{ toObjectId: 1, associationTypes: [], properties: {} }],
+                    hasMore: true,
+                    nextOffset: 10,
+                },
+                cleanup: jest.fn(),
+            });
+            const { result } = renderHook(() => useAssociations({
+                toObjectType: '0-1',
+                pageLength: 10,
+            }));
+            // Wait for initial load (page 1)
+            await waitFor(() => {
+                expect(result.current.pagination.currentPage).toBe(1);
+                expect(result.current.pagination.hasNextPage).toBe(true);
+            });
+            // Go to page 2
+            result.current.pagination.nextPage();
+            await waitFor(() => {
+                expect(result.current.pagination.currentPage).toBe(2);
+                expect(result.current.pagination.hasPreviousPage).toBe(true);
+            });
+            // Go back to previous page
+            result.current.pagination.previousPage();
+            await waitFor(() => {
+                expect(result.current.pagination.currentPage).toBe(1);
+                expect(result.current.pagination.hasPreviousPage).toBe(false);
+            });
+        });
+        it('should reset to first page correctly', async () => {
+            // Initial page 1 - has more pages
+            mockFetchAssociations.mockResolvedValue({
+                data: {
+                    results: [],
+                    hasMore: true,
+                    nextOffset: 10,
+                },
+                cleanup: jest.fn(),
+            });
+            const { result } = renderHook(() => useAssociations({
+                toObjectType: '0-1',
+                pageLength: 10,
+            }));
+            // Wait for initial load
+            await waitFor(() => {
+                expect(result.current.pagination.currentPage).toBe(1);
+                expect(result.current.pagination.hasNextPage).toBe(true);
+            });
+            // Navigate to page 2, then page 3
+            result.current.pagination.nextPage();
+            await waitFor(() => {
+                expect(result.current.pagination.currentPage).toBe(2);
+            });
+            result.current.pagination.nextPage();
+            await waitFor(() => {
+                expect(result.current.pagination.currentPage).toBe(3);
+            });
+            // Reset to first page
+            result.current.pagination.reset();
+            await waitFor(() => {
+                expect(result.current.pagination.currentPage).toBe(1);
+                expect(result.current.pagination.hasPreviousPage).toBe(false);
+            });
+        });
+        it('should not allow navigation beyond boundaries', async () => {
+            mockFetchAssociations.mockResolvedValue({
+                data: {
+                    results: [],
+                    hasMore: false,
+                    nextOffset: 10,
+                },
+                cleanup: jest.fn(),
+            });
+            const { result } = renderHook(() => useAssociations({
+                toObjectType: '0-1',
+                pageLength: 10,
+            }));
+            await waitFor(() => {
+                expect(result.current.pagination.currentPage).toBe(1);
+                expect(result.current.pagination.hasNextPage).toBe(false);
+            });
+            // Try to go to next page when there isn't one
+            result.current.pagination.nextPage();
+            // Should stay on page 1
+            expect(result.current.pagination.currentPage).toBe(1);
+            // Try to go to previous page from page 1
+            result.current.pagination.previousPage();
+            // Should stay on page 1
+            expect(result.current.pagination.currentPage).toBe(1);
+        });
+    });
+    describe('error handling', () => {
+        it('should handle fetch errors correctly', async () => {
+            const errorMessage = 'Failed to fetch associations';
+            mockFetchAssociations.mockRejectedValue(new Error(errorMessage));
+            const { result } = renderHook(() => useAssociations({
+                toObjectType: '0-1',
+                properties: ['firstname'],
+                pageLength: 10,
+            }));
+            await waitFor(() => {
+                expect(result.current.error).toBeInstanceOf(Error);
+                expect(result.current.error?.message).toBe(errorMessage);
+                expect(result.current.results).toEqual([]);
+                expect(result.current.isLoading).toBe(false);
+            });
+        });
+    });
+    describe('options handling', () => {
+        it('should pass formatting options to fetchAssociations', async () => {
+            mockFetchAssociations.mockResolvedValue({
+                data: {
+                    results: [],
+                    hasMore: false,
+                    nextOffset: 0,
+                },
+                cleanup: jest.fn(),
+            });
+            const config = {
+                toObjectType: '0-1',
+                properties: ['firstname', 'lastname'],
+                pageLength: 10,
+            };
+            const options = {
+                propertiesToFormat: ['firstname'],
+                formattingOptions: {
+                    date: {
+                        format: 'MM/DD/YYYY',
+                        relative: true,
+                    },
+                },
+            };
+            renderHook(() => useAssociations(config, options));
+            await waitFor(() => {
+                expect(mockFetchAssociations).toHaveBeenCalledWith(expect.objectContaining(config), options);
+            });
+        });
+        it('should use default empty options when no options provided', async () => {
+            mockFetchAssociations.mockResolvedValue({
+                data: {
+                    results: [],
+                    hasMore: false,
+                    nextOffset: 0,
+                },
+                cleanup: jest.fn(),
+            });
+            const config = {
+                toObjectType: '0-1',
+                properties: ['firstname'],
+                pageLength: 10,
+            };
+            renderHook(() => useAssociations(config));
+            await waitFor(() => {
+                expect(mockFetchAssociations).toHaveBeenCalledWith(expect.objectContaining(config), {});
+            });
+        });
+    });
+    describe('lifecycle management', () => {
+        it('should call cleanup function on unmount', async () => {
+            const mockCleanup = jest.fn();
+            mockFetchAssociations.mockResolvedValue({
+                data: {
+                    results: [],
+                    hasMore: false,
+                    nextOffset: 0,
+                },
+                cleanup: mockCleanup,
+            });
+            const config = {
+                toObjectType: '0-1',
+                properties: ['firstname'],
+                pageLength: 10,
+            };
+            const { unmount } = renderHook(() => useAssociations(config));
+            await waitFor(() => {
+                expect(mockFetchAssociations).toHaveBeenCalled();
+            });
+            unmount();
+            await waitFor(() => {
+                expect(mockCleanup).toHaveBeenCalled();
+            });
+        });
+        it('should handle stable reference optimization for config', async () => {
+            mockFetchAssociations.mockResolvedValue({
+                data: {
+                    results: [],
+                    hasMore: false,
+                    nextOffset: 0,
+                },
+                cleanup: jest.fn(),
+            });
+            const config = {
+                toObjectType: '0-1',
+                properties: ['firstname'],
+                pageLength: 10,
+            };
+            const { rerender } = renderHook(({ configProp }) => useAssociations(configProp), {
+                initialProps: { configProp: config },
+            });
+            await waitFor(() => {
+                expect(mockFetchAssociations).toHaveBeenCalledTimes(1);
+            });
+            // Rerender with the same config object content but different reference
+            rerender({ configProp: { ...config } });
+            await waitFor(() => {
+                // Should not call fetchAssociations again due to stable reference optimization
+                expect(mockFetchAssociations).toHaveBeenCalledTimes(1);
+            });
+        });
+    });
+});

package/dist/coreComponents.d.ts

@@ -794,3 +794,15 @@ export declare const SearchInput: "SearchInput" & {
     readonly props?: types.SearchInputProps | undefined;
     readonly children?: true | undefined;
 } & import("@remote-ui/react").ReactComponentTypeFromRemoteComponentType<import("@remote-ui/types").RemoteComponentType<"SearchInput", types.SearchInputProps, true>>;
+/**
+ * The `TimeInput` component renders an input field where a user can select a time. Commonly used within the `Form` component.
+ *
+ * **Links:**
+ *
+ * - {@link https://developers.hubspot.com/docs/reference/ui-components/standard-components/time-input Docs}
+ */
+export declare const TimeInput: "TimeInput" & {
+    readonly type?: "TimeInput" | undefined;
+    readonly props?: types.TimeInputProps | undefined;
+    readonly children?: true | undefined;
+} & import("@remote-ui/react").ReactComponentTypeFromRemoteComponentType<import("@remote-ui/types").RemoteComponentType<"TimeInput", types.TimeInputProps, true>>;

package/dist/coreComponents.js

@@ -534,3 +534,11 @@ export const Tooltip = createRemoteReactComponent('Tooltip');
  * - {@link https://developers.hubspot.com/docs/reference/ui-components/standard-components/search-input SearchInput Docs}
  */
 export const SearchInput = createRemoteReactComponent('SearchInput');
+/**
+ * The `TimeInput` component renders an input field where a user can select a time. Commonly used within the `Form` component.
+ *
+ * **Links:**
+ *
+ * - {@link https://developers.hubspot.com/docs/reference/ui-components/standard-components/time-input Docs}
+ */
+export const TimeInput = createRemoteReactComponent('TimeInput');

package/dist/experimental/crm/fetchAssociations.d.ts

@@ -0,0 +1,45 @@
+import { FetchCrmPropertiesOptions } from './fetchCrmProperties';
+export declare const DEFAULT_PAGE_SIZE = 10;
+/**
+ * Convert page number and page size to offset for API calls
+ */
+export declare function pageToOffset(page: number, pageSize: number): number;
+/**
+ * Convert offset and page size to page number
+ */
+export declare function offsetToPage(offset: number, pageSize: number): number;
+/**
+ * Calculate pagination flags based on current page and API hasMore flag
+ */
+export declare function calculatePaginationFlags(currentPage: number, hasMore: boolean): {
+    hasNextPage: boolean;
+    hasPreviousPage: boolean;
+};
+export type AssociationResult = {
+    toObjectId: number;
+    associationTypes: {
+        category: string;
+        typeId: number;
+        label: string;
+    }[];
+    properties: {
+        [key: string]: string | null;
+    };
+};
+export type AssociationsResponse = {
+    results: AssociationResult[];
+    hasMore: boolean;
+    nextOffset: number;
+};
+export type FetchAssociationsRequest = {
+    toObjectType: string;
+    properties?: string[];
+    pageLength?: number;
+    offset?: number;
+};
+export interface FetchAssociationsResult {
+    data: AssociationsResponse;
+    error?: string;
+    cleanup: () => void;
+}
+export declare const fetchAssociations: (request: FetchAssociationsRequest, options?: FetchCrmPropertiesOptions) => Promise<FetchAssociationsResult>;

package/dist/experimental/crm/fetchAssociations.js

@@ -0,0 +1,64 @@
+export const DEFAULT_PAGE_SIZE = 10;
+/**
+ * Convert page number and page size to offset for API calls
+ */
+export function pageToOffset(page, pageSize) {
+    return (page - 1) * pageSize;
+}
+/**
+ * Convert offset and page size to page number
+ */
+export function offsetToPage(offset, pageSize) {
+    return Math.floor(offset / pageSize) + 1;
+}
+/**
+ * Calculate pagination flags based on current page and API hasMore flag
+ */
+export function calculatePaginationFlags(currentPage, hasMore) {
+    return {
+        hasNextPage: hasMore,
+        hasPreviousPage: currentPage > 1,
+    };
+}
+function isAssociationsResponse(data) {
+    if (data === null ||
+        typeof data !== 'object' ||
+        !Array.isArray(data.results) ||
+        typeof data.hasMore !== 'boolean' ||
+        typeof data.nextOffset !== 'number') {
+        return false;
+    }
+    return data.results.every((result) => result !== null &&
+        typeof result === 'object' &&
+        typeof result.toObjectId === 'number' &&
+        Array.isArray(result.associationTypes) &&
+        result.properties !== null &&
+        typeof result.properties === 'object');
+}
+export const fetchAssociations = async (request, options) => {
+    let response;
+    let result;
+    try {
+        // eslint-disable-next-line hubspot-dev/no-confusing-browser-globals
+        response = await self.fetchAssociations(request, options);
+        result = await response.json();
+    }
+    catch (error) {
+        throw error instanceof Error
+            ? error
+            : new Error('Failed to fetch associations: Unknown error');
+    }
+    if (result.error) {
+        throw new Error(result.error);
+    }
+    if (!response.ok) {
+        throw new Error(`Failed to fetch associations: ${response.statusText}`);
+    }
+    if (!isAssociationsResponse(result.data)) {
+        throw new Error('Invalid response format');
+    }
+    return {
+        data: result.data,
+        cleanup: result.cleanup || (() => { }),
+    };
+};

package/dist/experimental/crm/fetchCrmProperties.d.ts

@@ -19,6 +19,7 @@ export type FetchCrmPropertiesOptions = {
 };
 export interface FetchCrmPropertiesResult {
     data: Record<string, string | null>;
+    error?: string;
     cleanup: () => void;
 }
 export declare const fetchCrmProperties: (propertyNames: string[], propertiesUpdatedCallback: (properties: Record<string, string | null>) => void, options?: FetchCrmPropertiesOptions) => Promise<FetchCrmPropertiesResult>;

package/dist/experimental/crm/fetchCrmProperties.js

@@ -12,22 +12,27 @@ function isCrmPropertiesResponse(data) {
     return true;
 }
 export const fetchCrmProperties = async (propertyNames, propertiesUpdatedCallback, options) => {
+    let response;
+    let result;
     try {
         // eslint-disable-next-line hubspot-dev/no-confusing-browser-globals
-        const response = await self.fetchCrmProperties(propertyNames, propertiesUpdatedCallback, options);
-        if (!response.ok) {
-            throw new Error(`Failed to fetch CRM properties: ${response.statusText}`);
-        }
-        const result = await response.json();
-        if (!isCrmPropertiesResponse(result.data)) {
-            throw new Error('Invalid response format');
-        }
-        return result;
+        response = await self.fetchCrmProperties(propertyNames, propertiesUpdatedCallback, options);
+        result = await response.json();
     }
     catch (error) {
-        if (error instanceof Error) {
-            throw error;
-        }
-        throw new Error('Failed to fetch CRM properties: Unknown error');
+        // Only handle network/parsing errors, not our validation errors
+        throw error instanceof Error
+            ? error
+            : new Error('Failed to fetch CRM properties: Unknown error');
     }
+    if (result.error) {
+        throw new Error(result.error);
+    }
+    if (!response.ok) {
+        throw new Error(`Failed to fetch CRM properties: ${response.statusText}`);
+    }
+    if (!isCrmPropertiesResponse(result.data)) {
+        throw new Error('Invalid response format');
+    }
+    return result;
 };

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

@@ -0,0 +1,22 @@
+import { type FetchAssociationsRequest, type AssociationResult } from '../crm/fetchAssociations';
+import { type FetchCrmPropertiesOptions } from '../crm/fetchCrmProperties';
+export interface 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;
+    pagination: UseAssociationsPagination;
+}
+export declare function useAssociations(config: Omit<FetchAssociationsRequest, 'offset'>, options?: UseAssociationsOptions): UseAssociationsResult;