dify

dify/web/hooks/use-tab-searchparams.spec.ts

@@ -0,0 +1,543 @@
+/**
+ * Test suite for useTabSearchParams hook
+ *
+ * This hook manages tab state through URL search parameters, enabling:
+ * - Bookmarkable tab states (users can share URLs with specific tabs active)
+ * - Browser history integration (back/forward buttons work with tabs)
+ * - Configurable routing behavior (push vs replace)
+ * - Optional search parameter syncing (can disable URL updates)
+ *
+ * The hook syncs a local tab state with URL search parameters, making tab
+ * navigation persistent and shareable across sessions.
+ */
+import { act, renderHook } from '@testing-library/react'
+import { useTabSearchParams } from './use-tab-searchparams'
+
+// Mock Next.js navigation hooks
+const mockPush = jest.fn()
+const mockReplace = jest.fn()
+const mockPathname = '/test-path'
+const mockSearchParams = new URLSearchParams()
+
+jest.mock('next/navigation', () => ({
+  usePathname: jest.fn(() => mockPathname),
+  useRouter: jest.fn(() => ({
+    push: mockPush,
+    replace: mockReplace,
+  })),
+  useSearchParams: jest.fn(() => mockSearchParams),
+}))
+
+// Import after mocks
+import { usePathname } from 'next/navigation'
+
+describe('useTabSearchParams', () => {
+  beforeEach(() => {
+    jest.clearAllMocks()
+    mockSearchParams.delete('category')
+    mockSearchParams.delete('tab')
+  })
+
+  describe('Basic functionality', () => {
+    /**
+     * Test that the hook returns a tuple with activeTab and setActiveTab
+     * This is the primary interface matching React's useState pattern
+     */
+    it('should return activeTab and setActiveTab function', () => {
+      const { result } = renderHook(() =>
+        useTabSearchParams({ defaultTab: 'overview' }),
+      )
+
+      const [activeTab, setActiveTab] = result.current
+
+      expect(typeof activeTab).toBe('string')
+      expect(typeof setActiveTab).toBe('function')
+    })
+
+    /**
+     * Test that the hook initializes with the default tab
+     * When no search param is present, should use defaultTab
+     */
+    it('should initialize with default tab when no search param exists', () => {
+      const { result } = renderHook(() =>
+        useTabSearchParams({ defaultTab: 'overview' }),
+      )
+
+      const [activeTab] = result.current
+      expect(activeTab).toBe('overview')
+    })
+
+    /**
+     * Test that the hook reads from URL search parameters
+     * When a search param exists, it should take precedence over defaultTab
+     */
+    it('should initialize with search param value when present', () => {
+      mockSearchParams.set('category', 'settings')
+
+      const { result } = renderHook(() =>
+        useTabSearchParams({ defaultTab: 'overview' }),
+      )
+
+      const [activeTab] = result.current
+      expect(activeTab).toBe('settings')
+    })
+
+    /**
+     * Test that setActiveTab updates the local state
+     * The active tab should change when setActiveTab is called
+     */
+    it('should update active tab when setActiveTab is called', () => {
+      const { result } = renderHook(() =>
+        useTabSearchParams({ defaultTab: 'overview' }),
+      )
+
+      act(() => {
+        const [, setActiveTab] = result.current
+        setActiveTab('settings')
+      })
+
+      const [activeTab] = result.current
+      expect(activeTab).toBe('settings')
+    })
+  })
+
+  describe('Routing behavior', () => {
+    /**
+     * Test default push routing behavior
+     * By default, tab changes should use router.push (adds to history)
+     */
+    it('should use push routing by default', () => {
+      const { result } = renderHook(() =>
+        useTabSearchParams({ defaultTab: 'overview' }),
+      )
+
+      act(() => {
+        const [, setActiveTab] = result.current
+        setActiveTab('settings')
+      })
+
+      expect(mockPush).toHaveBeenCalledWith('/test-path?category=settings')
+      expect(mockReplace).not.toHaveBeenCalled()
+    })
+
+    /**
+     * Test replace routing behavior
+     * When routingBehavior is 'replace', should use router.replace (no history)
+     */
+    it('should use replace routing when specified', () => {
+      const { result } = renderHook(() =>
+        useTabSearchParams({
+          defaultTab: 'overview',
+          routingBehavior: 'replace',
+        }),
+      )
+
+      act(() => {
+        const [, setActiveTab] = result.current
+        setActiveTab('settings')
+      })
+
+      expect(mockReplace).toHaveBeenCalledWith('/test-path?category=settings')
+      expect(mockPush).not.toHaveBeenCalled()
+    })
+
+    /**
+     * Test that URL encoding is applied to tab values
+     * Special characters in tab names should be properly encoded
+     */
+    it('should encode special characters in tab values', () => {
+      const { result } = renderHook(() =>
+        useTabSearchParams({ defaultTab: 'overview' }),
+      )
+
+      act(() => {
+        const [, setActiveTab] = result.current
+        setActiveTab('settings & config')
+      })
+
+      expect(mockPush).toHaveBeenCalledWith(
+        '/test-path?category=settings%20%26%20config',
+      )
+    })
+
+    /**
+     * Test that URL decoding is applied when reading from search params
+     * Encoded values in the URL should be properly decoded
+     */
+    it('should decode encoded values from search params', () => {
+      mockSearchParams.set('category', 'settings%20%26%20config')
+
+      const { result } = renderHook(() =>
+        useTabSearchParams({ defaultTab: 'overview' }),
+      )
+
+      const [activeTab] = result.current
+      expect(activeTab).toBe('settings & config')
+    })
+  })
+
+  describe('Custom search parameter name', () => {
+    /**
+     * Test using a custom search parameter name
+     * Should support different param names instead of default 'category'
+     */
+    it('should use custom search param name', () => {
+      mockSearchParams.set('tab', 'profile')
+
+      const { result } = renderHook(() =>
+        useTabSearchParams({
+          defaultTab: 'overview',
+          searchParamName: 'tab',
+        }),
+      )
+
+      const [activeTab] = result.current
+      expect(activeTab).toBe('profile')
+    })
+
+    /**
+     * Test that setActiveTab uses the custom param name in the URL
+     */
+    it('should update URL with custom param name', () => {
+      const { result } = renderHook(() =>
+        useTabSearchParams({
+          defaultTab: 'overview',
+          searchParamName: 'tab',
+        }),
+      )
+
+      act(() => {
+        const [, setActiveTab] = result.current
+        setActiveTab('profile')
+      })
+
+      expect(mockPush).toHaveBeenCalledWith('/test-path?tab=profile')
+    })
+  })
+
+  describe('Disabled search params mode', () => {
+    /**
+     * Test that disableSearchParams prevents URL updates
+     * When disabled, tab state should be local only
+     */
+    it('should not update URL when disableSearchParams is true', () => {
+      const { result } = renderHook(() =>
+        useTabSearchParams({
+          defaultTab: 'overview',
+          disableSearchParams: true,
+        }),
+      )
+
+      act(() => {
+        const [, setActiveTab] = result.current
+        setActiveTab('settings')
+      })
+
+      expect(mockPush).not.toHaveBeenCalled()
+      expect(mockReplace).not.toHaveBeenCalled()
+    })
+
+    /**
+     * Test that local state still updates when search params are disabled
+     * The tab state should work even without URL syncing
+     */
+    it('should still update local state when search params disabled', () => {
+      const { result } = renderHook(() =>
+        useTabSearchParams({
+          defaultTab: 'overview',
+          disableSearchParams: true,
+        }),
+      )
+
+      act(() => {
+        const [, setActiveTab] = result.current
+        setActiveTab('settings')
+      })
+
+      const [activeTab] = result.current
+      expect(activeTab).toBe('settings')
+    })
+
+    /**
+     * Test that disabled mode always uses defaultTab
+     * Search params should be ignored when disabled
+     */
+    it('should use defaultTab when search params disabled even if URL has value', () => {
+      mockSearchParams.set('category', 'settings')
+
+      const { result } = renderHook(() =>
+        useTabSearchParams({
+          defaultTab: 'overview',
+          disableSearchParams: true,
+        }),
+      )
+
+      const [activeTab] = result.current
+      expect(activeTab).toBe('overview')
+    })
+  })
+
+  describe('Edge cases', () => {
+    /**
+     * Test handling of empty string tab values
+     * Empty strings should be handled gracefully
+     */
+    it('should handle empty string tab values', () => {
+      const { result } = renderHook(() =>
+        useTabSearchParams({ defaultTab: 'overview' }),
+      )
+
+      act(() => {
+        const [, setActiveTab] = result.current
+        setActiveTab('')
+      })
+
+      const [activeTab] = result.current
+      expect(activeTab).toBe('')
+      expect(mockPush).toHaveBeenCalledWith('/test-path?category=')
+    })
+
+    /**
+     * Test that special characters in tab names are properly encoded
+     * This ensures URLs remain valid even with unusual tab names
+     */
+    it('should handle tabs with various special characters', () => {
+      const { result } = renderHook(() =>
+        useTabSearchParams({ defaultTab: 'overview' }),
+      )
+
+      // Test tab with slashes
+      act(() => result.current[1]('tab/with/slashes'))
+      expect(result.current[0]).toBe('tab/with/slashes')
+
+      // Test tab with question marks
+      act(() => result.current[1]('tab?with?questions'))
+      expect(result.current[0]).toBe('tab?with?questions')
+
+      // Test tab with hash symbols
+      act(() => result.current[1]('tab#with#hash'))
+      expect(result.current[0]).toBe('tab#with#hash')
+
+      // Test tab with equals signs
+      act(() => result.current[1]('tab=with=equals'))
+      expect(result.current[0]).toBe('tab=with=equals')
+    })
+
+    /**
+     * Test fallback when pathname is not available
+     * Should use window.location.pathname as fallback
+     */
+    it('should fallback to window.location.pathname when hook pathname is null', () => {
+      ;(usePathname as jest.Mock).mockReturnValue(null)
+
+      // Mock window.location.pathname
+      Object.defineProperty(window, 'location', {
+        value: { pathname: '/fallback-path' },
+        writable: true,
+      })
+
+      const { result } = renderHook(() =>
+        useTabSearchParams({ defaultTab: 'overview' }),
+      )
+
+      act(() => {
+        const [, setActiveTab] = result.current
+        setActiveTab('settings')
+      })
+
+      expect(mockPush).toHaveBeenCalledWith('/fallback-path?category=settings')
+
+      // Restore mock
+      ;(usePathname as jest.Mock).mockReturnValue(mockPathname)
+    })
+  })
+
+  describe('Multiple instances', () => {
+    /**
+     * Test that multiple instances with different param names work independently
+     * Different hooks should not interfere with each other
+     */
+    it('should support multiple independent tab states', () => {
+      mockSearchParams.set('category', 'overview')
+      mockSearchParams.set('subtab', 'details')
+
+      const { result: result1 } = renderHook(() =>
+        useTabSearchParams({
+          defaultTab: 'home',
+          searchParamName: 'category',
+        }),
+      )
+
+      const { result: result2 } = renderHook(() =>
+        useTabSearchParams({
+          defaultTab: 'info',
+          searchParamName: 'subtab',
+        }),
+      )
+
+      const [activeTab1] = result1.current
+      const [activeTab2] = result2.current
+
+      expect(activeTab1).toBe('overview')
+      expect(activeTab2).toBe('details')
+    })
+  })
+
+  describe('Integration scenarios', () => {
+    /**
+     * Test typical usage in a tabbed interface
+     * Simulates real-world tab switching behavior
+     */
+    it('should handle sequential tab changes', () => {
+      const { result } = renderHook(() =>
+        useTabSearchParams({ defaultTab: 'overview' }),
+      )
+
+      // Change to settings tab
+      act(() => {
+        const [, setActiveTab] = result.current
+        setActiveTab('settings')
+      })
+
+      expect(result.current[0]).toBe('settings')
+      expect(mockPush).toHaveBeenCalledWith('/test-path?category=settings')
+
+      // Change to profile tab
+      act(() => {
+        const [, setActiveTab] = result.current
+        setActiveTab('profile')
+      })
+
+      expect(result.current[0]).toBe('profile')
+      expect(mockPush).toHaveBeenCalledWith('/test-path?category=profile')
+
+      // Verify push was called twice
+      expect(mockPush).toHaveBeenCalledTimes(2)
+    })
+
+    /**
+     * Test that the hook works with complex pathnames
+     * Should handle nested routes and existing query params
+     */
+    it('should work with complex pathnames', () => {
+      ;(usePathname as jest.Mock).mockReturnValue('/app/123/settings')
+
+      const { result } = renderHook(() =>
+        useTabSearchParams({ defaultTab: 'overview' }),
+      )
+
+      act(() => {
+        const [, setActiveTab] = result.current
+        setActiveTab('advanced')
+      })
+
+      expect(mockPush).toHaveBeenCalledWith('/app/123/settings?category=advanced')
+
+      // Restore mock
+      ;(usePathname as jest.Mock).mockReturnValue(mockPathname)
+    })
+  })
+
+  describe('Type safety', () => {
+    /**
+     * Test that the return type is a const tuple
+     * TypeScript should infer [string, (tab: string) => void] as const
+     */
+    it('should return a const tuple type', () => {
+      const { result } = renderHook(() =>
+        useTabSearchParams({ defaultTab: 'overview' }),
+      )
+
+      // The result should be a tuple with exactly 2 elements
+      expect(result.current).toHaveLength(2)
+      expect(typeof result.current[0]).toBe('string')
+      expect(typeof result.current[1]).toBe('function')
+    })
+  })
+
+  describe('Performance', () => {
+    /**
+     * Test that the hook creates a new function on each render
+     * Note: The current implementation doesn't use useCallback,
+     * so setActiveTab is recreated on each render. This could lead to
+     * unnecessary re-renders in child components that depend on this function.
+     * TODO: Consider memoizing setActiveTab with useCallback for better performance.
+     */
+    it('should create new setActiveTab function on each render', () => {
+      const { result, rerender } = renderHook(() =>
+        useTabSearchParams({ defaultTab: 'overview' }),
+      )
+
+      const [, firstSetActiveTab] = result.current
+      rerender()
+      const [, secondSetActiveTab] = result.current
+
+      // Function reference changes on re-render (not memoized)
+      expect(firstSetActiveTab).not.toBe(secondSetActiveTab)
+
+      // But both functions should work correctly
+      expect(typeof firstSetActiveTab).toBe('function')
+      expect(typeof secondSetActiveTab).toBe('function')
+    })
+  })
+
+  describe('Browser history integration', () => {
+    /**
+     * Test that push behavior adds to browser history
+     * This enables back/forward navigation through tabs
+     */
+    it('should add to history with push behavior', () => {
+      const { result } = renderHook(() =>
+        useTabSearchParams({
+          defaultTab: 'overview',
+          routingBehavior: 'push',
+        }),
+      )
+
+      act(() => {
+        const [, setActiveTab] = result.current
+        setActiveTab('tab1')
+      })
+
+      act(() => {
+        const [, setActiveTab] = result.current
+        setActiveTab('tab2')
+      })
+
+      act(() => {
+        const [, setActiveTab] = result.current
+        setActiveTab('tab3')
+      })
+
+      // Each tab change should create a history entry
+      expect(mockPush).toHaveBeenCalledTimes(3)
+    })
+
+    /**
+     * Test that replace behavior doesn't add to history
+     * This prevents cluttering browser history with tab changes
+     */
+    it('should not add to history with replace behavior', () => {
+      const { result } = renderHook(() =>
+        useTabSearchParams({
+          defaultTab: 'overview',
+          routingBehavior: 'replace',
+        }),
+      )
+
+      act(() => {
+        const [, setActiveTab] = result.current
+        setActiveTab('tab1')
+      })
+
+      act(() => {
+        const [, setActiveTab] = result.current
+        setActiveTab('tab2')
+      })
+
+      // Should use replace instead of push
+      expect(mockReplace).toHaveBeenCalledTimes(2)
+      expect(mockPush).not.toHaveBeenCalled()
+    })
+  })
+})