react-fathom 0.1.0

package/src/components/TrackClick.test.tsx

@@ -0,0 +1,191 @@
+import React from 'react'
+
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { fireEvent, render, screen } from '@testing-library/react'
+
+import { FathomProvider } from '../FathomProvider'
+import { TrackClick } from './TrackClick'
+
+describe('TrackClick', () => {
+  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>
+  )
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('should render children', () => {
+    render(
+      <TrackClick eventName="test-event">
+        <button>Click me</button>
+      </TrackClick>,
+      { wrapper },
+    )
+
+    expect(screen.getByText('Click me')).toBeInTheDocument()
+  })
+
+  it('should track event on click', () => {
+    render(
+      <TrackClick eventName="test-event">
+        <button>Click me</button>
+      </TrackClick>,
+      { wrapper },
+    )
+
+    fireEvent.click(screen.getByText('Click me'))
+
+    expect(mockTrackEvent).toHaveBeenCalledTimes(1)
+    expect(mockTrackEvent).toHaveBeenCalledWith('test-event', {})
+  })
+
+  it('should track event with options', () => {
+    render(
+      <TrackClick eventName="test-event" id="test-id" value={100}>
+        <button>Click me</button>
+      </TrackClick>,
+      { wrapper },
+    )
+
+    fireEvent.click(screen.getByText('Click me'))
+
+    expect(mockTrackEvent).toHaveBeenCalledWith('test-event', {
+      id: 'test-id',
+      value: 100,
+    })
+  })
+
+  it('should prevent default when preventDefault is true', () => {
+    render(
+      <TrackClick eventName="test-event" preventDefault>
+        <a href="/test">Link</a>
+      </TrackClick>,
+      { wrapper },
+    )
+
+    const link = screen.getByText('Link')
+    const clickEvent = new MouseEvent('click', {
+      bubbles: true,
+      cancelable: true,
+    })
+    const preventDefaultSpy = vi.spyOn(clickEvent, 'preventDefault')
+
+    fireEvent(link, clickEvent)
+
+    expect(preventDefaultSpy).toHaveBeenCalled()
+    expect(mockTrackEvent).toHaveBeenCalledTimes(1)
+  })
+
+  it('should not prevent default when preventDefault is false', () => {
+    render(
+      <TrackClick eventName="test-event" preventDefault={false}>
+        <a href="/test">Link</a>
+      </TrackClick>,
+      { wrapper },
+    )
+
+    const link = screen.getByText('Link')
+    const clickEvent = new MouseEvent('click', {
+      bubbles: true,
+      cancelable: true,
+    })
+    const preventDefaultSpy = vi.spyOn(clickEvent, 'preventDefault')
+
+    fireEvent(link, clickEvent)
+
+    expect(preventDefaultSpy).not.toHaveBeenCalled()
+    expect(mockTrackEvent).toHaveBeenCalledTimes(1)
+  })
+
+  it('should call custom onClick handler', () => {
+    const onClick = vi.fn()
+
+    render(
+      <TrackClick eventName="test-event" onClick={onClick}>
+        <button>Click me</button>
+      </TrackClick>,
+      { wrapper },
+    )
+
+    fireEvent.click(screen.getByText('Click me'))
+
+    expect(onClick).toHaveBeenCalledTimes(1)
+    expect(mockTrackEvent).toHaveBeenCalledTimes(1)
+  })
+
+  it('should render with custom element type', () => {
+    render(
+      <TrackClick eventName="test-event" as="span">
+        <button>Click me</button>
+      </TrackClick>,
+      { wrapper },
+    )
+
+    const wrapperElement = screen.getByText('Click me').parentElement
+    expect(wrapperElement?.tagName).toBe('SPAN')
+  })
+
+  it('should render with default div wrapper', () => {
+    render(
+      <TrackClick eventName="test-event">
+        <button>Click me</button>
+      </TrackClick>,
+      { wrapper },
+    )
+
+    const wrapperElement = screen.getByText('Click me').parentElement
+    expect(wrapperElement?.tagName).toBe('DIV')
+  })
+
+  it('should handle multiple children', () => {
+    render(
+      <TrackClick eventName="test-event">
+        <button>Button 1</button>
+        <button>Button 2</button>
+      </TrackClick>,
+      { wrapper },
+    )
+
+    expect(screen.getByText('Button 1')).toBeInTheDocument()
+    expect(screen.getByText('Button 2')).toBeInTheDocument()
+  })
+
+  it('should merge defaultEventOptions from provider', () => {
+    const customWrapper = ({ children }: { children: React.ReactNode }) => (
+      <FathomProvider
+        client={mockClient}
+        defaultEventOptions={{ id: 'default-id' }}
+      >
+        {children}
+      </FathomProvider>
+    )
+
+    render(
+      <TrackClick eventName="test-event" value={100}>
+        <button>Click me</button>
+      </TrackClick>,
+      { wrapper: customWrapper },
+    )
+
+    fireEvent.click(screen.getByText('Click me'))
+
+    expect(mockTrackEvent).toHaveBeenCalledWith('test-event', {
+      id: 'default-id',
+      value: 100,
+    })
+  })
+})

package/src/components/TrackClick.tsx

@@ -0,0 +1,62 @@
+import React from 'react'
+import type { ElementType, MouseEvent, ReactNode } from 'react'
+
+import type { EventOptions } from 'fathom-client'
+
+import { useFathom } from '../hooks/useFathom'
+
+export interface TrackClickProps extends EventOptions {
+  /**
+   * Event name to track
+   */
+  eventName: string
+  /**
+   * Child element(s) to wrap
+   */
+  children: ReactNode
+  /**
+   * Whether to prevent default behavior
+   * @default false
+   */
+  preventDefault?: boolean
+  /**
+   * Custom onClick handler (will be called before tracking)
+   */
+  onClick?: (e: MouseEvent) => void
+  /**
+   * HTML element to render as wrapper
+   * @default 'div'
+   */
+  as?: ElementType
+}
+
+/**
+ * Component wrapper that automatically tracks clicks on its children
+ *
+ * @example
+ * ```tsx
+ * <TrackClick eventName="cta-clicked" id="hero-cta">
+ *   <button>Get Started</button>
+ * </TrackClick>
+ * ```
+ */
+export const TrackClick: React.FC<TrackClickProps> = ({
+  eventName,
+  children,
+  preventDefault = false,
+  onClick,
+  as: Component = 'div',
+  ...eventOptions
+}) => {
+  const { trackEvent } = useFathom()
+
+  const handleClick = (e: MouseEvent) => {
+    if (preventDefault) {
+      e.preventDefault()
+    }
+    onClick?.(e)
+    trackEvent?.(eventName, eventOptions)
+  }
+
+  return <Component onClick={handleClick}>{children}</Component>
+}

package/src/components/TrackPageview.test.tsx

@@ -0,0 +1,111 @@
+import React from 'react'
+
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { render, screen } from '@testing-library/react'
+
+import { FathomProvider } from '../FathomProvider'
+import { TrackPageview } from './TrackPageview'
+
+describe('TrackPageview', () => {
+  const mockTrackPageview = vi.fn()
+  const mockClient = {
+    trackEvent: vi.fn(),
+    trackPageview: mockTrackPageview,
+    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>
+  )
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('should track pageview on mount', () => {
+    render(<TrackPageview />, { wrapper })
+
+    expect(mockTrackPageview).toHaveBeenCalledTimes(1)
+    expect(mockTrackPageview).toHaveBeenCalledWith({})
+  })
+
+  it('should track pageview with options', () => {
+    render(<TrackPageview url="/test-page" />, { wrapper })
+
+    expect(mockTrackPageview).toHaveBeenCalledTimes(1)
+    expect(mockTrackPageview).toHaveBeenCalledWith({ url: '/test-page' })
+  })
+
+  it('should render children', () => {
+    render(
+      <TrackPageview>
+        <div>Page content</div>
+      </TrackPageview>,
+      { wrapper },
+    )
+
+    expect(screen.getByText('Page content')).toBeInTheDocument()
+    expect(mockTrackPageview).toHaveBeenCalledTimes(1)
+  })
+
+  it('should render without children', () => {
+    const { container } = render(<TrackPageview />, { wrapper })
+
+    expect(container.firstChild).toBeNull()
+    expect(mockTrackPageview).toHaveBeenCalledTimes(1)
+  })
+
+  it('should only track once on mount', () => {
+    const { rerender } = render(<TrackPageview />, { wrapper })
+
+    expect(mockTrackPageview).toHaveBeenCalledTimes(1)
+
+    rerender(<TrackPageview />)
+    expect(mockTrackPageview).toHaveBeenCalledTimes(1)
+  })
+
+  it('should merge defaultPageviewOptions from provider', () => {
+    const customWrapper = ({ children }: { children: React.ReactNode }) => (
+      <FathomProvider
+        client={mockClient}
+        defaultPageviewOptions={{ url: '/default' }}
+      >
+        {children}
+      </FathomProvider>
+    )
+
+    render(<TrackPageview />, { wrapper: customWrapper })
+
+    expect(mockTrackPageview).toHaveBeenCalledTimes(1)
+    // The component passes empty object, provider merges defaults internally
+    expect(mockTrackPageview).toHaveBeenCalledWith({ url: '/default' })
+  })
+
+  it('should override defaultPageviewOptions with props', () => {
+    const customWrapper = ({ children }: { children: React.ReactNode }) => (
+      <FathomProvider
+        client={mockClient}
+        defaultPageviewOptions={{ url: '/default' }}
+      >
+        {children}
+      </FathomProvider>
+    )
+
+    render(<TrackPageview url="/custom" />, { wrapper: customWrapper })
+
+    expect(mockTrackPageview).toHaveBeenCalledTimes(1)
+    expect(mockTrackPageview).toHaveBeenCalledWith({ url: '/custom' })
+  })
+
+  it('should not track when used outside FathomProvider', () => {
+    render(<TrackPageview />)
+
+    expect(mockTrackPageview).not.toHaveBeenCalled()
+  })
+})

package/src/components/TrackPageview.tsx

@@ -0,0 +1,36 @@
+import React, { useEffect } from 'react'
+import type { ReactNode } from 'react'
+
+import type { PageViewOptions } from 'fathom-client'
+
+import { useFathom } from '../hooks/useFathom'
+
+export interface TrackPageviewProps extends PageViewOptions {
+  /**
+   * Child element(s) to render
+   */
+  children?: ReactNode
+}
+
+/**
+ * Component that tracks a pageview when it mounts
+ *
+ * @example
+ * ```tsx
+ * <TrackPageview url="/custom-page">
+ *   <div>Page content</div>
+ * </TrackPageview>
+ * ```
+ */
+export const TrackPageview: React.FC<TrackPageviewProps> = ({
+  children,
+  ...pageviewOptions
+}) => {
+  const { trackPageview } = useFathom()
+
+  useEffect(() => {
+    trackPageview?.(pageviewOptions)
+  }, []) // eslint-disable-line react-hooks/exhaustive-deps
+
+  return <>{children}</>
+}

package/src/components/TrackVisible.test.tsx

@@ -0,0 +1,311 @@
+import React from 'react'
+
+import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest'
+
+import { render, screen, waitFor } from '@testing-library/react'
+
+import { FathomProvider } from '../FathomProvider'
+import { TrackVisible } from './TrackVisible'
+
+describe('TrackVisible', () => {
+  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 render children', () => {
+    render(
+      <TrackVisible eventName="test-event">
+        <div>Visible content</div>
+      </TrackVisible>,
+      { wrapper },
+    )
+
+    expect(screen.getByText('Visible content')).toBeInTheDocument()
+  })
+
+  it('should create IntersectionObserver on mount', () => {
+    render(
+      <TrackVisible eventName="test-event">
+        <div>Content</div>
+      </TrackVisible>,
+      { wrapper },
+    )
+
+    expect(mockObserve).toHaveBeenCalled()
+  })
+
+  it('should track event when element becomes visible', async () => {
+    render(
+      <TrackVisible eventName="test-event">
+        <div>Content</div>
+      </TrackVisible>,
+      { wrapper },
+    )
+
+    // Wait for IntersectionObserver to be created
+    await waitFor(() => {
+      expect(mockObserve).toHaveBeenCalled()
+    })
+
+    const element = screen.getByText('Content').parentElement
+    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 () => {
+    render(
+      <TrackVisible eventName="test-event" id="test-id" value={100}>
+        <div>Content</div>
+      </TrackVisible>,
+      { wrapper },
+    )
+
+    // Wait for IntersectionObserver to be created
+    await waitFor(() => {
+      expect(mockObserve).toHaveBeenCalled()
+    })
+
+    const element = screen.getByText('Content').parentElement
+    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 () => {
+    render(
+      <TrackVisible eventName="test-event" trackOnce>
+        <div>Content</div>
+      </TrackVisible>,
+      { wrapper },
+    )
+
+    // Wait for IntersectionObserver to be created
+    await waitFor(() => {
+      expect(mockObserve).toHaveBeenCalled()
+    })
+
+    const element = screen.getByText('Content').parentElement
+    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 () => {
+    render(
+      <TrackVisible eventName="test-event" trackOnce={false}>
+        <div>Content</div>
+      </TrackVisible>,
+      { wrapper },
+    )
+
+    // Wait for IntersectionObserver to be created
+    await waitFor(() => {
+      expect(mockObserve).toHaveBeenCalled()
+    })
+
+    const element = screen.getByText('Content').parentElement
+    const mockEntry = {
+      isIntersecting: true,
+      target: element!,
+    } as IntersectionObserverEntry
+
+    observerCallback([mockEntry])
+    observerCallback([mockEntry])
+    observerCallback([mockEntry])
+
+    await waitFor(() => {
+      expect(mockTrackEvent).toHaveBeenCalledTimes(3)
+    })
+  })
+
+  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
+
+    render(
+      <TrackVisible eventName="test-event" observerOptions={observerOptions}>
+        <div>Content</div>
+      </TrackVisible>,
+      { wrapper },
+    )
+
+    await waitFor(() => {
+      expect(capturedOptions?.threshold).toBe(0.5)
+    })
+
+    global.IntersectionObserver = OriginalObserver
+  })
+
+  it('should render with custom element type', () => {
+    render(
+      <TrackVisible eventName="test-event" as="section">
+        <div>Content</div>
+      </TrackVisible>,
+      { wrapper },
+    )
+
+    const wrapperElement = screen.getByText('Content').parentElement
+    expect(wrapperElement?.tagName).toBe('SECTION')
+  })
+
+  it('should render with default div wrapper', () => {
+    render(
+      <TrackVisible eventName="test-event">
+        <div>Content</div>
+      </TrackVisible>,
+      { wrapper },
+    )
+
+    const wrapperElement = screen.getByText('Content').parentElement
+    expect(wrapperElement?.tagName).toBe('DIV')
+  })
+
+  it('should forward ref', () => {
+    const ref = { current: null }
+
+    render(
+      <TrackVisible eventName="test-event" ref={ref}>
+        <div>Content</div>
+      </TrackVisible>,
+      { wrapper },
+    )
+
+    expect(ref.current).not.toBeNull()
+    expect(ref.current).toBeInstanceOf(HTMLDivElement)
+  })
+
+  it('should disconnect observer on unmount', async () => {
+    const { unmount } = render(
+      <TrackVisible eventName="test-event">
+        <div>Content</div>
+      </TrackVisible>,
+      { wrapper },
+    )
+
+    // Wait for IntersectionObserver to be created
+    await waitFor(() => {
+      expect(mockObserve).toHaveBeenCalled()
+    })
+
+    unmount()
+
+    expect(mockDisconnect).toHaveBeenCalledTimes(1)
+  })
+
+  it('should merge defaultEventOptions from provider', async () => {
+    const customWrapper = ({ children }: { children: React.ReactNode }) => (
+      <FathomProvider
+        client={mockClient}
+        defaultEventOptions={{ id: 'default-id' }}
+      >
+        {children}
+      </FathomProvider>
+    )
+
+    render(
+      <TrackVisible eventName="test-event" value={100}>
+        <div>Content</div>
+      </TrackVisible>,
+      { wrapper: customWrapper },
+    )
+
+    // Wait for IntersectionObserver to be created
+    await waitFor(() => {
+      expect(mockObserve).toHaveBeenCalled()
+    })
+
+    const element = screen.getByText('Content').parentElement
+    const mockEntry = {
+      isIntersecting: true,
+      target: element!,
+    } as IntersectionObserverEntry
+
+    observerCallback([mockEntry])
+
+    await waitFor(() => {
+      expect(mockTrackEvent).toHaveBeenCalledWith('test-event', {
+        id: 'default-id',
+        value: 100,
+      })
+    })
+  })
+})