react-fathom 0.1.0

package/src/hooks/useTrackOnVisible.test.tsx

@@ -0,0 +1,313 @@
+import React from 'react'
+
+import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest'
+
+import { render, renderHook, waitFor } from '@testing-library/react'
+
+import { FathomProvider } from '../FathomProvider'
+import { useTrackOnVisible } from './useTrackOnVisible'
+
+describe('useTrackOnVisible', () => {
+  const mockTrackEvent = vi.fn()
+  const mockClient = {
+    trackEvent: mockTrackEvent,
+    trackPageview: vi.fn(),
+    trackGoal: vi.fn(),
+    load: vi.fn(),
+    setSite: vi.fn(),
+    blockTrackingForMe: vi.fn(),
+    enableTrackingForMe: vi.fn(),
+    isTrackingEnabled: vi.fn(() => true),
+  }
+
+  const wrapper = ({ children }: { children: React.ReactNode }) => (
+    <FathomProvider client={mockClient}>{children}</FathomProvider>
+  )
+
+  let mockObserve: ReturnType<typeof vi.fn>
+  let mockDisconnect: ReturnType<typeof vi.fn>
+  let observerCallback: (entries: IntersectionObserverEntry[]) => void
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mockObserve = vi.fn()
+    mockDisconnect = vi.fn()
+
+    global.IntersectionObserver = class MockIntersectionObserver {
+      observe = mockObserve
+      disconnect = mockDisconnect
+      unobserve = vi.fn()
+
+      constructor(callback: (entries: IntersectionObserverEntry[]) => void) {
+        observerCallback = callback
+      }
+    } as any
+  })
+
+  afterEach(() => {
+    delete (global as any).IntersectionObserver
+  })
+
+  it('should return a ref object', () => {
+    const { result } = renderHook(
+      () => useTrackOnVisible({ eventName: 'test-event' }),
+      { wrapper },
+    )
+
+    expect(result.current).toHaveProperty('current')
+  })
+
+  it('should create IntersectionObserver when ref is attached', async () => {
+    const TestComponent = () => {
+      const ref = useTrackOnVisible({ eventName: 'test-event' })
+      return <div ref={ref}>Test</div>
+    }
+
+    render(
+      <FathomProvider client={mockClient}>
+        <TestComponent />
+      </FathomProvider>,
+    )
+
+    await waitFor(() => {
+      expect(mockObserve).toHaveBeenCalled()
+    })
+  })
+
+  it('should track event when element becomes visible', async () => {
+    const TestComponent = () => {
+      const ref = useTrackOnVisible({ eventName: 'test-event' })
+      return <div ref={ref}>Test</div>
+    }
+
+    render(
+      <FathomProvider client={mockClient}>
+        <TestComponent />
+      </FathomProvider>,
+    )
+
+    // Wait for observer to be created
+    await waitFor(() => {
+      expect(mockObserve).toHaveBeenCalled()
+    })
+
+    // Simulate intersection
+    const element = document.querySelector('div')
+    const mockEntry = {
+      isIntersecting: true,
+      target: element!,
+    } as IntersectionObserverEntry
+
+    observerCallback([mockEntry])
+
+    await waitFor(() => {
+      expect(mockTrackEvent).toHaveBeenCalledTimes(1)
+      expect(mockTrackEvent).toHaveBeenCalledWith('test-event', {})
+    })
+  })
+
+  it('should track event with options', async () => {
+    const TestComponent = () => {
+      const ref = useTrackOnVisible({
+        eventName: 'test-event',
+        id: 'test-id',
+        value: 100,
+      })
+      return <div ref={ref}>Test</div>
+    }
+
+    render(
+      <FathomProvider client={mockClient}>
+        <TestComponent />
+      </FathomProvider>,
+    )
+
+    // Wait for observer to be created
+    await waitFor(() => {
+      expect(mockObserve).toHaveBeenCalled()
+    })
+
+    const element = document.querySelector('div')
+    const mockEntry = {
+      isIntersecting: true,
+      target: element!,
+    } as IntersectionObserverEntry
+
+    observerCallback([mockEntry])
+
+    await waitFor(() => {
+      expect(mockTrackEvent).toHaveBeenCalledWith('test-event', {
+        id: 'test-id',
+        value: 100,
+      })
+    })
+  })
+
+  it('should track only once when trackOnce is true', async () => {
+    const TestComponent = () => {
+      const ref = useTrackOnVisible({
+        eventName: 'test-event',
+        trackOnce: true,
+      })
+      return <div ref={ref}>Test</div>
+    }
+
+    render(
+      <FathomProvider client={mockClient}>
+        <TestComponent />
+      </FathomProvider>,
+    )
+
+    // Wait for observer to be created
+    await waitFor(() => {
+      expect(mockObserve).toHaveBeenCalled()
+    })
+
+    const element = document.querySelector('div')
+    const mockEntry = {
+      isIntersecting: true,
+      target: element!,
+    } as IntersectionObserverEntry
+
+    observerCallback([mockEntry])
+    observerCallback([mockEntry])
+    observerCallback([mockEntry])
+
+    await waitFor(() => {
+      expect(mockTrackEvent).toHaveBeenCalledTimes(1)
+    })
+  })
+
+  it('should track multiple times when trackOnce is false', async () => {
+    const TestComponent = () => {
+      const ref = useTrackOnVisible({
+        eventName: 'test-event',
+        trackOnce: false,
+      })
+      return <div ref={ref}>Test</div>
+    }
+
+    render(
+      <FathomProvider client={mockClient}>
+        <TestComponent />
+      </FathomProvider>,
+    )
+
+    // Wait for observer to be created
+    await waitFor(() => {
+      expect(mockObserve).toHaveBeenCalled()
+    })
+
+    const element = document.querySelector('div')
+    const mockEntry = {
+      isIntersecting: true,
+      target: element!,
+    } as IntersectionObserverEntry
+
+    observerCallback([mockEntry])
+    observerCallback([mockEntry])
+    observerCallback([mockEntry])
+
+    await waitFor(() => {
+      expect(mockTrackEvent).toHaveBeenCalledTimes(3)
+    })
+  })
+
+  it('should call callback when element becomes visible', async () => {
+    const callback = vi.fn()
+
+    const TestComponent = () => {
+      const ref = useTrackOnVisible({
+        eventName: 'test-event',
+        callback,
+      })
+      return <div ref={ref}>Test</div>
+    }
+
+    render(
+      <FathomProvider client={mockClient}>
+        <TestComponent />
+      </FathomProvider>,
+    )
+
+    // Wait for observer to be created
+    await waitFor(() => {
+      expect(mockObserve).toHaveBeenCalled()
+    })
+
+    const element = document.querySelector('div')
+    const mockEntry = {
+      isIntersecting: true,
+      target: element!,
+    } as IntersectionObserverEntry
+
+    observerCallback([mockEntry])
+
+    await waitFor(() => {
+      expect(callback).toHaveBeenCalledTimes(1)
+      expect(callback).toHaveBeenCalledWith(mockEntry)
+    })
+  })
+
+  it('should use custom observer options', async () => {
+    const observerOptions = { threshold: 0.5 }
+    let capturedOptions: IntersectionObserverInit | undefined
+
+    const OriginalObserver = global.IntersectionObserver
+    global.IntersectionObserver = class MockIntersectionObserver {
+      observe = mockObserve
+      disconnect = mockDisconnect
+      unobserve = vi.fn()
+
+      constructor(
+        callback: (entries: IntersectionObserverEntry[]) => void,
+        options?: IntersectionObserverInit,
+      ) {
+        capturedOptions = options
+        observerCallback = callback
+      }
+    } as any
+
+    const TestComponent = () => {
+      const ref = useTrackOnVisible({
+        eventName: 'test-event',
+        observerOptions,
+      })
+      return <div ref={ref}>Test</div>
+    }
+
+    render(
+      <FathomProvider client={mockClient}>
+        <TestComponent />
+      </FathomProvider>,
+    )
+
+    await waitFor(() => {
+      expect(capturedOptions?.threshold).toBe(0.5)
+    })
+
+    global.IntersectionObserver = OriginalObserver
+  })
+
+  it('should disconnect observer on unmount', async () => {
+    const TestComponent = () => {
+      const ref = useTrackOnVisible({ eventName: 'test-event' })
+      return <div ref={ref}>Test</div>
+    }
+
+    const { unmount } = render(
+      <FathomProvider client={mockClient}>
+        <TestComponent />
+      </FathomProvider>,
+    )
+
+    // Wait for observer to be created
+    await waitFor(() => {
+      expect(mockObserve).toHaveBeenCalled()
+    })
+
+    unmount()
+
+    expect(mockDisconnect).toHaveBeenCalledTimes(1)
+  })
+})

package/src/hooks/useTrackOnVisible.ts

@@ -0,0 +1,99 @@
+import { useEffect, useRef } from 'react'
+import type { RefObject } from 'react'
+
+import type { EventOptions } from 'fathom-client'
+
+import { useFathom } from './useFathom'
+
+export interface UseTrackOnVisibleOptions extends EventOptions {
+  /**
+   * Event name to track
+   */
+  eventName: string
+  /**
+   * Intersection observer options
+   */
+  observerOptions?: IntersectionObserverInit
+  /**
+   * Whether to track only once or every time it becomes visible
+   * @default true
+   */
+  trackOnce?: boolean
+  /**
+   * Optional callback function to run after tracking
+   * Receives the intersection observer entry as a parameter
+   */
+  callback?: (entry: IntersectionObserverEntry) => void
+}
+
+/**
+ * Hook to track an event when an element becomes visible (using Intersection Observer)
+ *
+ * @example
+ * ```tsx
+ * function Section() {
+ *   const ref = useTrackOnVisible({
+ *     eventName: 'section-viewed',
+ *     section: 'hero',
+ *     callback: (entry) => {
+ *       console.log('Section is visible!', entry.isIntersecting)
+ *       // Your custom logic here
+ *     },
+ *   })
+ *
+ *   return <section ref={ref}>Content</section>
+ * }
+ * ```
+ */
+export const useTrackOnVisible = (
+  options: UseTrackOnVisibleOptions,
+): RefObject<HTMLElement | null> => {
+  const { trackEvent } = useFathom()
+  const {
+    eventName,
+    observerOptions,
+    trackOnce = true,
+    callback,
+    ...eventOptions
+  } = options
+  const ref = useRef<HTMLElement | null>(null)
+  const hasTracked = useRef(false)
+
+  useEffect(() => {
+    const element = ref.current
+    if (!element) return
+
+    const observer = new IntersectionObserver(
+      (entries) => {
+        entries.forEach((entry) => {
+          if (entry.isIntersecting) {
+            if (!trackOnce || !hasTracked.current) {
+              trackEvent?.(eventName, eventOptions)
+              callback?.(entry)
+              hasTracked.current = true
+            }
+          }
+        })
+      },
+      {
+        threshold: 0.1,
+        ...observerOptions,
+      },
+    )
+
+    observer.observe(element)
+
+    return () => {
+      observer.disconnect()
+    }
+  }, [
+    eventName,
+    eventOptions,
+    observerOptions,
+    trackOnce,
+    trackEvent,
+    callback,
+  ])
+
+  return ref
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from './FathomContext'
+export * from './FathomProvider'
+export * from './hooks'
+export * from './components'

package/src/next/NextFathomProvider.test.tsx

@@ -0,0 +1,131 @@
+import React from 'react'
+
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { render, screen, waitFor } from '@testing-library/react'
+
+import { NextFathomProvider } from './NextFathomProvider'
+
+// Mock the lazy-loaded providers
+vi.mock('./NextFathomProviderApp', () => ({
+  default: ({
+    children,
+    siteId,
+  }: {
+    children: React.ReactNode
+    siteId?: string
+  }) => (
+    <div data-testid="app-provider" data-site-id={siteId}>
+      {children}
+    </div>
+  ),
+}))
+
+vi.mock('./NextFathomProviderPages', () => ({
+  default: ({
+    children,
+    siteId,
+  }: {
+    children: React.ReactNode
+    siteId?: string
+  }) => (
+    <div data-testid="pages-provider" data-site-id={siteId}>
+      {children}
+    </div>
+  ),
+}))
+
+describe('NextFathomProvider', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('should render App Router provider by default', async () => {
+    render(
+      <NextFathomProvider siteId="TEST_SITE_ID">
+        <div>Test Content</div>
+      </NextFathomProvider>,
+    )
+
+    await waitFor(() => {
+      expect(screen.getByTestId('app-provider')).toBeInTheDocument()
+      expect(screen.getByTestId('app-provider')).toHaveAttribute(
+        'data-site-id',
+        'TEST_SITE_ID',
+      )
+    })
+
+    expect(screen.getByText('Test Content')).toBeInTheDocument()
+  })
+
+  it('should render App Router provider when router="app"', async () => {
+    render(
+      <NextFathomProvider siteId="TEST_SITE_ID" router="app">
+        <div>Test Content</div>
+      </NextFathomProvider>,
+    )
+
+    await waitFor(() => {
+      expect(screen.getByTestId('app-provider')).toBeInTheDocument()
+    })
+
+    expect(screen.queryByTestId('pages-provider')).not.toBeInTheDocument()
+  })
+
+  it('should render Pages Router provider when router="pages"', async () => {
+    render(
+      <NextFathomProvider siteId="TEST_SITE_ID" router="pages">
+        <div>Test Content</div>
+      </NextFathomProvider>,
+    )
+
+    await waitFor(() => {
+      expect(screen.getByTestId('pages-provider')).toBeInTheDocument()
+      expect(screen.getByTestId('pages-provider')).toHaveAttribute(
+        'data-site-id',
+        'TEST_SITE_ID',
+      )
+    })
+
+    expect(screen.queryByTestId('app-provider')).not.toBeInTheDocument()
+    expect(screen.getByText('Test Content')).toBeInTheDocument()
+  })
+
+  it('should render custom fallback while loading', async () => {
+    render(
+      <NextFathomProvider
+        siteId="TEST_SITE_ID"
+        fallback={<div>Loading...</div>}
+      >
+        <div>Test Content</div>
+      </NextFathomProvider>,
+    )
+
+    // Suspense fallback may be shown briefly, but provider should load quickly
+    await waitFor(() => {
+      expect(screen.getByTestId('app-provider')).toBeInTheDocument()
+    })
+  })
+
+  it('should pass all props to the underlying provider', async () => {
+    const clientOptions = { honorDNT: true }
+    render(
+      <NextFathomProvider
+        siteId="TEST_SITE_ID"
+        router="app"
+        clientOptions={clientOptions}
+        disableAutoTrack
+      >
+        <div>Test Content</div>
+      </NextFathomProvider>,
+    )
+
+    await waitFor(() => {
+      expect(screen.getByTestId('app-provider')).toBeInTheDocument()
+    })
+  })
+
+  it('should have displayName', () => {
+    expect(NextFathomProvider.displayName).toBe('NextFathomProvider')
+  })
+})

package/src/next/NextFathomProvider.tsx

@@ -0,0 +1,62 @@
+import React, { Suspense, lazy, useMemo } from 'react'
+
+import type { NextFathomProviderProps } from './types'
+
+export interface NextFathomProviderComponentProps extends NextFathomProviderProps {
+  /**
+   * Router type to use
+   * @default 'app'
+   */
+  router?: 'pages' | 'app'
+  /**
+   * Fallback component to show while loading the router provider
+   * @default null
+   */
+  fallback?: React.ReactNode
+}
+
+// Dynamically import providers to enable code-splitting
+const NextFathomProviderAppLazy = lazy(
+  async () => await import('./NextFathomProviderApp'),
+)
+const NextFathomProviderPagesLazy = lazy(
+  async () => await import('./NextFathomProviderPages'),
+)
+
+/**
+ * Unified provider component that conditionally renders the appropriate
+ * Next.js router provider based on the `router` prop.
+ * Providers are dynamically loaded to avoid bundling both router types.
+ *
+ * @example
+ * ```tsx
+ * // App Router (default)
+ * <NextFathomProvider siteId="YOUR_SITE_ID" router="app">
+ *   <App>{children}</App>
+ * </NextFathomProvider>
+ *
+ * // Pages Router
+ * <NextFathomProvider siteId="YOUR_SITE_ID" router="pages">
+ *   <App>{children}</App>
+ * </NextFathomProvider>
+ * ```
+ */
+export const NextFathomProvider: React.FC<NextFathomProviderComponentProps> = ({
+  router = 'app',
+  fallback = null,
+  ...props
+}) => {
+  const Provider = useMemo(() => {
+    return router === 'pages'
+      ? NextFathomProviderPagesLazy
+      : NextFathomProviderAppLazy
+  }, [router])
+
+  return (
+    <Suspense fallback={fallback}>
+      <Provider {...props} />
+    </Suspense>
+  )
+}
+
+NextFathomProvider.displayName = 'NextFathomProvider'