react-fathom 0.1.0

package/src/next/NextFathomProviderPages.test.tsx

@@ -0,0 +1,330 @@
+import React from 'react'
+
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { renderHook, waitFor } from '@testing-library/react'
+
+import NextFathomProviderPages from './NextFathomProviderPages'
+import { useFathom } from '../hooks/useFathom'
+
+// Mock Next.js Pages Router hook
+const mockRouter = {
+  pathname: '/test-page',
+  query: { foo: 'bar' },
+  asPath: '/test-page?foo=bar',
+  isReady: true,
+  events: {
+    on: vi.fn(),
+    off: vi.fn(),
+  },
+}
+
+vi.mock('next/router', () => ({
+  useRouter: vi.fn(() => mockRouter),
+}))
+
+// Mock fathom-client
+vi.mock('fathom-client', async () => {
+  const mockFathomClient = {
+    trackEvent: vi.fn(),
+    trackPageview: vi.fn(),
+    trackGoal: vi.fn(),
+    load: vi.fn(),
+    setSite: vi.fn(),
+    blockTrackingForMe: vi.fn(),
+    enableTrackingForMe: vi.fn(),
+    isTrackingEnabled: vi.fn(() => true),
+  }
+
+  return {
+    default: mockFathomClient,
+  }
+})
+
+describe('NextFathomProviderPages', () => {
+  const mockClient = {
+    trackEvent: vi.fn(),
+    trackPageview: vi.fn(),
+    trackGoal: vi.fn(),
+    load: vi.fn(),
+    setSite: vi.fn(),
+    blockTrackingForMe: vi.fn(),
+    enableTrackingForMe: vi.fn(),
+    isTrackingEnabled: vi.fn(() => true),
+  }
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mockRouter.isReady = true
+    mockRouter.events.on = vi.fn()
+    mockRouter.events.off = vi.fn()
+    // Reset window.location
+    Object.defineProperty(window, 'location', {
+      value: {
+        origin: 'https://example.com',
+        href: 'https://example.com/test-page?foo=bar',
+      },
+      writable: true,
+    })
+  })
+
+  it('should load Fathom on mount when siteId is provided', async () => {
+    const loadSpy = vi.fn()
+    const client = { ...mockClient, load: loadSpy }
+
+    const wrapper = ({ children }: { children: React.ReactNode }) => (
+      <NextFathomProviderPages client={client} siteId="TEST_SITE_ID">
+        {children}
+      </NextFathomProviderPages>
+    )
+
+    renderHook(() => useFathom(), { wrapper })
+
+    await waitFor(() => {
+      expect(loadSpy).toHaveBeenCalledWith('TEST_SITE_ID', undefined)
+    })
+  })
+
+  it('should load Fathom with clientOptions', async () => {
+    const loadSpy = vi.fn()
+    const clientOptions = { honorDNT: true }
+    const client = { ...mockClient, load: loadSpy }
+
+    const wrapper = ({ children }: { children: React.ReactNode }) => (
+      <NextFathomProviderPages
+        client={client}
+        siteId="TEST_SITE_ID"
+        clientOptions={clientOptions}
+      >
+        {children}
+      </NextFathomProviderPages>
+    )
+
+    renderHook(() => useFathom(), { wrapper })
+
+    await waitFor(() => {
+      expect(loadSpy).toHaveBeenCalledWith('TEST_SITE_ID', clientOptions)
+    })
+  })
+
+  it('should track initial pageview when router is ready', async () => {
+    const trackPageviewSpy = vi.fn()
+    const client = { ...mockClient, trackPageview: trackPageviewSpy }
+
+    const wrapper = ({ children }: { children: React.ReactNode }) => (
+      <NextFathomProviderPages client={client} siteId="TEST_SITE_ID">
+        {children}
+      </NextFathomProviderPages>
+    )
+
+    renderHook(() => useFathom(), { wrapper })
+
+    await waitFor(() => {
+      expect(trackPageviewSpy).toHaveBeenCalled()
+    })
+
+    expect(trackPageviewSpy).toHaveBeenCalledWith({
+      url: 'https://example.com/test-page?foo=bar',
+    })
+  })
+
+  it('should not track initial pageview when router is not ready', async () => {
+    mockRouter.isReady = false
+    const trackPageviewSpy = vi.fn()
+    const client = { ...mockClient, trackPageview: trackPageviewSpy }
+
+    const wrapper = ({ children }: { children: React.ReactNode }) => (
+      <NextFathomProviderPages client={client} siteId="TEST_SITE_ID">
+        {children}
+      </NextFathomProviderPages>
+    )
+
+    renderHook(() => useFathom(), { wrapper })
+
+    // Wait a bit to ensure no tracking happens
+    await new Promise((resolve) => setTimeout(resolve, 100))
+
+    expect(trackPageviewSpy).not.toHaveBeenCalled()
+  })
+
+  it('should register route change listener', async () => {
+    const wrapper = ({ children }: { children: React.ReactNode }) => (
+      <NextFathomProviderPages client={mockClient} siteId="TEST_SITE_ID">
+        {children}
+      </NextFathomProviderPages>
+    )
+
+    renderHook(() => useFathom(), { wrapper })
+
+    await waitFor(() => {
+      expect(mockRouter.events.on).toHaveBeenCalledWith(
+        'routeChangeComplete',
+        expect.any(Function),
+      )
+    })
+  })
+
+  it('should unregister route change listener on unmount', async () => {
+    const wrapper = ({ children }: { children: React.ReactNode }) => (
+      <NextFathomProviderPages client={mockClient} siteId="TEST_SITE_ID">
+        {children}
+      </NextFathomProviderPages>
+    )
+
+    const { unmount } = renderHook(() => useFathom(), { wrapper })
+
+    await waitFor(() => {
+      expect(mockRouter.events.on).toHaveBeenCalled()
+    })
+
+    unmount()
+
+    expect(mockRouter.events.off).toHaveBeenCalledWith(
+      'routeChangeComplete',
+      expect.any(Function),
+    )
+  })
+
+  it('should track pageview on route change', async () => {
+    const trackPageviewSpy = vi.fn()
+    const client = { ...mockClient, trackPageview: trackPageviewSpy }
+
+    const wrapper = ({ children }: { children: React.ReactNode }) => (
+      <NextFathomProviderPages client={client} siteId="TEST_SITE_ID">
+        {children}
+      </NextFathomProviderPages>
+    )
+
+    renderHook(() => useFathom(), { wrapper })
+
+    await waitFor(() => {
+      expect(mockRouter.events.on).toHaveBeenCalled()
+    })
+
+    // Get the route change handler
+    const routeChangeHandler = mockRouter.events.on.mock.calls[0][1]
+    routeChangeHandler('/new-page')
+
+    expect(trackPageviewSpy).toHaveBeenCalledWith({
+      url: 'https://example.com/new-page',
+    })
+  })
+
+  it('should not track pageview when disableAutoTrack is true', async () => {
+    const trackPageviewSpy = vi.fn()
+    const client = { ...mockClient, trackPageview: trackPageviewSpy }
+
+    const wrapper = ({ children }: { children: React.ReactNode }) => (
+      <NextFathomProviderPages
+        client={client}
+        siteId="TEST_SITE_ID"
+        disableAutoTrack
+      >
+        {children}
+      </NextFathomProviderPages>
+    )
+
+    renderHook(() => useFathom(), { wrapper })
+
+    // Wait a bit to ensure no tracking happens
+    await new Promise((resolve) => setTimeout(resolve, 100))
+
+    expect(trackPageviewSpy).not.toHaveBeenCalled()
+    expect(mockRouter.events.on).not.toHaveBeenCalled()
+  })
+
+  it('should use provided client', () => {
+    const wrapper = ({ children }: { children: React.ReactNode }) => (
+      <NextFathomProviderPages client={mockClient} siteId="TEST_SITE_ID">
+        {children}
+      </NextFathomProviderPages>
+    )
+
+    const { result } = renderHook(() => useFathom(), { wrapper })
+
+    expect(result.current.client).toBe(mockClient)
+  })
+
+  it('should merge defaultPageviewOptions', async () => {
+    const trackPageviewSpy = vi.fn()
+    const client = { ...mockClient, trackPageview: trackPageviewSpy }
+
+    const wrapper = ({ children }: { children: React.ReactNode }) => (
+      <NextFathomProviderPages
+        client={client}
+        siteId="TEST_SITE_ID"
+        defaultPageviewOptions={{ referrer: 'https://example.com' }}
+      >
+        {children}
+      </NextFathomProviderPages>
+    )
+
+    renderHook(() => useFathom(), { wrapper })
+
+    await waitFor(() => {
+      expect(trackPageviewSpy).toHaveBeenCalled()
+    })
+
+    expect(trackPageviewSpy).toHaveBeenCalledWith({
+      referrer: 'https://example.com',
+      url: 'https://example.com/test-page?foo=bar',
+    })
+  })
+
+  it('should support deprecated trackDefaultOptions', async () => {
+    const trackPageviewSpy = vi.fn()
+    const client = { ...mockClient, trackPageview: trackPageviewSpy }
+
+    const wrapper = ({ children }: { children: React.ReactNode }) => (
+      <NextFathomProviderPages
+        client={client}
+        siteId="TEST_SITE_ID"
+        trackDefaultOptions={{ referrer: 'https://example.com' }}
+      >
+        {children}
+      </NextFathomProviderPages>
+    )
+
+    renderHook(() => useFathom(), { wrapper })
+
+    await waitFor(() => {
+      expect(trackPageviewSpy).toHaveBeenCalled()
+    })
+
+    expect(trackPageviewSpy).toHaveBeenCalledWith({
+      referrer: 'https://example.com',
+      url: 'https://example.com/test-page?foo=bar',
+    })
+  })
+
+  it('should prioritize defaultPageviewOptions over trackDefaultOptions', async () => {
+    const trackPageviewSpy = vi.fn()
+    const client = { ...mockClient, trackPageview: trackPageviewSpy }
+
+    const wrapper = ({ children }: { children: React.ReactNode }) => (
+      <NextFathomProviderPages
+        client={client}
+        siteId="TEST_SITE_ID"
+        trackDefaultOptions={{ referrer: 'old' }}
+        defaultPageviewOptions={{ referrer: 'new' }}
+      >
+        {children}
+      </NextFathomProviderPages>
+    )
+
+    renderHook(() => useFathom(), { wrapper })
+
+    await waitFor(() => {
+      expect(trackPageviewSpy).toHaveBeenCalled()
+    })
+
+    expect(trackPageviewSpy).toHaveBeenCalledWith({
+      referrer: 'new',
+      url: 'https://example.com/test-page?foo=bar',
+    })
+  })
+
+  it('should have displayName', () => {
+    expect(NextFathomProviderPages.displayName).toBe('NextFathomProviderPages')
+  })
+})

package/src/next/NextFathomProviderPages.tsx

@@ -0,0 +1,112 @@
+import React, { useCallback, useEffect, useRef, useMemo } from 'react'
+
+import * as Fathom from 'fathom-client'
+import type { PageViewOptions } from 'fathom-client'
+import { useRouter } from 'next/router'
+
+import { FathomProvider } from '../FathomProvider'
+import type { NextFathomProviderProps } from './types'
+import { useFathom } from '../hooks/useFathom'
+
+const NextFathomProviderPages: React.FC<NextFathomProviderProps> = ({
+  children,
+  client: providedClient,
+  clientOptions,
+  disableAutoTrack = false,
+  siteId,
+  trackDefaultOptions,
+  defaultPageviewOptions: providedDefaultPageviewOptions,
+}) => {
+  const router = useRouter()
+  const hasTrackedInitialPageview = useRef(false)
+  const parentContext = useFathom()
+
+  // Use provided client or fall back to parent client or default Fathom
+  const client = useMemo(
+    () => providedClient ?? parentContext.client ?? Fathom,
+    [providedClient, parentContext.client],
+  )
+
+  // Support both deprecated trackDefaultOptions and new defaultPageviewOptions
+  // Priority: providedDefaultPageviewOptions > trackDefaultOptions > parent defaultPageviewOptions
+  const defaultPageviewOptions = useMemo(
+    () =>
+      providedDefaultPageviewOptions ??
+      trackDefaultOptions ??
+      parentContext.defaultPageviewOptions,
+    [
+      providedDefaultPageviewOptions,
+      trackDefaultOptions,
+      parentContext.defaultPageviewOptions,
+    ],
+  )
+
+  const trackPageview = useCallback(
+    (options?: PageViewOptions) => {
+      if (siteId !== undefined && client !== undefined) {
+        client.trackPageview({
+          ...defaultPageviewOptions,
+          ...options,
+        })
+      }
+    },
+    [client, siteId, defaultPageviewOptions],
+  )
+
+  // Initialize Fathom on mount
+  useEffect(() => {
+    if (siteId !== undefined && client !== undefined) {
+      client.load(siteId, clientOptions)
+    }
+  }, [client, clientOptions, siteId])
+
+  // Track pageviews on route changes
+  useEffect(() => {
+    if (siteId === undefined || disableAutoTrack) {
+      return
+    }
+
+    const handleRouteChangeComplete = (url: string): void => {
+      trackPageview({
+        url: window.location.origin + url,
+      })
+    }
+
+    router.events.on('routeChangeComplete', handleRouteChangeComplete)
+
+    return () => {
+      router.events.off('routeChangeComplete', handleRouteChangeComplete)
+    }
+  }, [router.events, siteId, disableAutoTrack, trackPageview])
+
+  // Track initial pageview (routeChangeComplete doesn't fire on initial load)
+  useEffect(() => {
+    if (
+      siteId !== undefined &&
+      !disableAutoTrack &&
+      router.isReady &&
+      !hasTrackedInitialPageview.current
+    ) {
+      hasTrackedInitialPageview.current = true
+      trackPageview({
+        url: window.location.href,
+      })
+    }
+  }, [siteId, disableAutoTrack, router.isReady, trackPageview])
+
+  return (
+    <FathomProvider
+      client={client}
+      clientOptions={clientOptions}
+      siteId={siteId}
+      defaultPageviewOptions={defaultPageviewOptions}
+    >
+      {children}
+    </FathomProvider>
+  )
+}
+
+NextFathomProviderPages.displayName = 'NextFathomProviderPages'
+
+export default NextFathomProviderPages
+export { NextFathomProviderPages }

package/src/next/compositions/withAppRouter.test.tsx

@@ -0,0 +1,113 @@
+import React from 'react'
+
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { render, screen } from '@testing-library/react'
+
+import { withAppRouter } from './withAppRouter'
+
+// Mock NextFathomProviderApp
+vi.mock('../NextFathomProviderApp', () => ({
+  default: ({
+    children,
+    siteId,
+  }: {
+    children: React.ReactNode
+    siteId?: string
+  }) => (
+    <div data-testid="app-provider" data-site-id={siteId}>
+      {children}
+    </div>
+  ),
+}))
+
+describe('withAppRouter', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('should wrap component with NextFathomProviderApp', () => {
+    const TestComponent = ({ name }: { name: string }) => (
+      <div>Hello {name}</div>
+    )
+
+    const WrappedComponent = withAppRouter(TestComponent, {
+      siteId: 'TEST_SITE_ID',
+    })
+
+    render(<WrappedComponent name="World" />)
+
+    expect(screen.getByTestId('app-provider')).toBeInTheDocument()
+    expect(screen.getByTestId('app-provider')).toHaveAttribute(
+      'data-site-id',
+      'TEST_SITE_ID',
+    )
+    expect(screen.getByText('Hello World')).toBeInTheDocument()
+  })
+
+  it('should pass props to wrapped component', () => {
+    const TestComponent = ({ count }: { count: number }) => (
+      <div>Count: {count}</div>
+    )
+
+    const WrappedComponent = withAppRouter(TestComponent)
+
+    render(<WrappedComponent count={42} />)
+
+    expect(screen.getByText('Count: 42')).toBeInTheDocument()
+  })
+
+  it('should pass provider props to NextFathomProviderApp', () => {
+    const TestComponent = () => <div>Test</div>
+
+    const WrappedComponent = withAppRouter(TestComponent, {
+      siteId: 'TEST_SITE_ID',
+      disableAutoTrack: true,
+      clientOptions: { honorDNT: true },
+    })
+
+    render(<WrappedComponent />)
+
+    expect(screen.getByTestId('app-provider')).toBeInTheDocument()
+  })
+
+  it('should work without provider props', () => {
+    const TestComponent = () => <div>Test</div>
+
+    const WrappedComponent = withAppRouter(TestComponent)
+
+    render(<WrappedComponent />)
+
+    expect(screen.getByTestId('app-provider')).toBeInTheDocument()
+    expect(screen.getByText('Test')).toBeInTheDocument()
+  })
+
+  it('should set displayName correctly', () => {
+    const TestComponent = () => <div>Test</div>
+    TestComponent.displayName = 'TestComponent'
+
+    const WrappedComponent = withAppRouter(TestComponent)
+
+    expect(WrappedComponent.displayName).toBe('withAppRouter(TestComponent)')
+  })
+
+  it('should set displayName with component name when displayName is not set', () => {
+    function TestComponent() {
+      return <div>Test</div>
+    }
+
+    const WrappedComponent = withAppRouter(TestComponent)
+
+    expect(WrappedComponent.displayName).toBe('withAppRouter(TestComponent)')
+  })
+
+  it('should set displayName with Component fallback', () => {
+    const TestComponent = () => <div>Test</div>
+    // Remove displayName and name
+    Object.defineProperty(TestComponent, 'name', { value: '' })
+
+    const WrappedComponent = withAppRouter(TestComponent)
+
+    expect(WrappedComponent.displayName).toBe('withAppRouter(Component)')
+  })
+})

package/src/next/compositions/withAppRouter.tsx

@@ -0,0 +1,48 @@
+import React from 'react'
+import type { ComponentType } from 'react'
+
+import NextFathomProviderApp from '../NextFathomProviderApp'
+import type { NextFathomProviderProps } from '../types'
+
+/**
+ * Higher-order component that wraps your Next.js App Router app with FathomProvider
+ *
+ * @example
+ * ```tsx
+ * // app/layout.tsx
+ * import { withAppRouter } from 'react-fathom/next'
+ *
+ * function RootLayout({ children }) {
+ *   return (
+ *     <html>
+ *       <body>{children}</body>
+ *     </html>
+ *   )
+ * }
+ *
+ * export default withAppRouter(RootLayout, {
+ *   siteId: 'YOUR_SITE_ID',
+ *   clientOptions: {
+ *     spa: 'auto',
+ *   },
+ * })
+ * ```
+ */
+const withAppRouter = <P extends object>(
+  Component: ComponentType<P>,
+  providerProps?: NextFathomProviderProps,
+): ComponentType<P> => {
+  const WithAppRouter: React.FC<P> = (props) => {
+    return (
+      <NextFathomProviderApp {...providerProps}>
+        <Component {...props} />
+      </NextFathomProviderApp>
+    )
+  }
+
+  WithAppRouter.displayName = `withAppRouter(${Component.displayName || Component.name || 'Component'})`
+
+  return WithAppRouter
+}
+
+export { withAppRouter }