react-fathom 0.1.10 → 0.2.0

package/src/FathomProvider.test.tsx

@@ -1,4 +1,4 @@
-import React from 'react'
+import React, { useRef } from 'react'
 
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 
@@ -6,6 +6,7 @@ import { renderHook, waitFor } from '@testing-library/react'
 
 import { FathomProvider } from './FathomProvider'
 import { useFathom } from './hooks/useFathom'
+import type { FathomClient } from './types'
 
 // Mock fathom-client
 vi.mock('fathom-client', () => {
@@ -139,10 +140,10 @@ describe('FathomProvider', () => {
 
     const { result } = renderHook(() => useFathom(), { wrapper })
 
-    result.current.trackEvent?.('test-event', { id: 'test-id' })
+    result.current.trackEvent?.('test-event', { _site_id: 'test-id' })
 
     expect(mockClient.trackEvent).toHaveBeenCalledWith('test-event', {
-      id: 'test-id',
+      _site_id: 'test-id',
     })
   })
 
@@ -161,7 +162,7 @@ describe('FathomProvider', () => {
     const wrapper = ({ children }: { children: React.ReactNode }) => (
       <FathomProvider
         client={mockClient}
-        defaultEventOptions={{ id: 'default-id' }}
+        defaultEventOptions={{ _site_id: 'default-id' }}
       >
         {children}
       </FathomProvider>
@@ -169,11 +170,11 @@ describe('FathomProvider', () => {
 
     const { result } = renderHook(() => useFathom(), { wrapper })
 
-    result.current.trackEvent?.('test-event', { value: 100 })
+    result.current.trackEvent?.('test-event', { _value: 100 })
 
     expect(mockClient.trackEvent).toHaveBeenCalledWith('test-event', {
-      id: 'default-id',
-      value: 100,
+      _site_id: 'default-id',
+      _value: 100,
     })
   })
 
@@ -192,7 +193,7 @@ describe('FathomProvider', () => {
     const wrapper = ({ children }: { children: React.ReactNode }) => (
       <FathomProvider
         client={mockClient}
-        defaultEventOptions={{ id: 'default-id' }}
+        defaultEventOptions={{ _site_id: 'default-id' }}
       >
         {children}
       </FathomProvider>
@@ -200,10 +201,10 @@ describe('FathomProvider', () => {
 
     const { result } = renderHook(() => useFathom(), { wrapper })
 
-    result.current.trackEvent?.('test-event', { id: 'override-id' })
+    result.current.trackEvent?.('test-event', { _site_id: 'override-id' })
 
     expect(mockClient.trackEvent).toHaveBeenCalledWith('test-event', {
-      id: 'override-id',
+      _site_id: 'override-id',
     })
   })
 
@@ -479,7 +480,7 @@ describe('FathomProvider', () => {
     const wrapper = ({ children }: { children: React.ReactNode }) => (
       <FathomProvider
         client={mockClient}
-        defaultEventOptions={{ id: 'parent-id' }}
+        defaultEventOptions={{ _site_id: 'parent-id' }}
       >
         <FathomProvider>{children}</FathomProvider>
       </FathomProvider>
@@ -490,7 +491,7 @@ describe('FathomProvider', () => {
     result.current.trackEvent?.('test-event')
 
     expect(mockClient.trackEvent).toHaveBeenCalledWith('test-event', {
-      id: 'parent-id',
+      _site_id: 'parent-id',
     })
   })
 
@@ -509,9 +510,9 @@ describe('FathomProvider', () => {
     const wrapper = ({ children }: { children: React.ReactNode }) => (
       <FathomProvider
         client={mockClient}
-        defaultEventOptions={{ id: 'parent-id' }}
+        defaultEventOptions={{ _site_id: 'parent-id' }}
       >
-        <FathomProvider defaultEventOptions={{ id: 'child-id' }}>
+        <FathomProvider defaultEventOptions={{ _site_id: 'child-id' }}>
           {children}
         </FathomProvider>
       </FathomProvider>
@@ -522,11 +523,110 @@ describe('FathomProvider', () => {
     result.current.trackEvent?.('test-event')
 
     expect(mockClient.trackEvent).toHaveBeenCalledWith('test-event', {
-      id: 'child-id',
+      _site_id: 'child-id',
     })
   })
 
   it('should have displayName', () => {
     expect(FathomProvider.displayName).toBe('FathomProvider')
   })
+
+  describe('clientRef', () => {
+    it('should populate clientRef with the resolved client', () => {
+      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),
+      }
+
+      let clientRefValue: FathomClient | null = null
+
+      const TestWrapper = ({ children }: { children: React.ReactNode }) => {
+        const clientRef = useRef<FathomClient>(null)
+        // Capture the ref value after render
+        React.useEffect(() => {
+          clientRefValue = clientRef.current
+        })
+        return (
+          <FathomProvider client={mockClient} clientRef={clientRef}>
+            {children}
+          </FathomProvider>
+        )
+      }
+
+      renderHook(() => useFathom(), { wrapper: TestWrapper })
+
+      expect(clientRefValue).toBe(mockClient)
+    })
+
+    it('should allow parent to call client methods via clientRef', () => {
+      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),
+      }
+
+      const clientRef = React.createRef<FathomClient>() as React.MutableRefObject<FathomClient | null>
+      clientRef.current = null
+
+      const wrapper = ({ children }: { children: React.ReactNode }) => (
+        <FathomProvider client={mockClient} clientRef={clientRef}>
+          {children}
+        </FathomProvider>
+      )
+
+      renderHook(() => useFathom(), { wrapper })
+
+      // Parent can now use the client directly
+      clientRef.current?.trackEvent('parent-event', { _value: 50 })
+
+      expect(mockClient.trackEvent).toHaveBeenCalledWith('parent-event', {
+        _value: 50,
+      })
+    })
+
+    it('should populate clientRef with inherited parent client', () => {
+      const parentClient = {
+        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),
+      }
+
+      let clientRefValue: FathomClient | null = null
+
+      const TestWrapper = ({ children }: { children: React.ReactNode }) => {
+        const clientRef = useRef<FathomClient>(null)
+        React.useEffect(() => {
+          clientRefValue = clientRef.current
+        })
+        return (
+          <FathomProvider client={parentClient}>
+            <FathomProvider clientRef={clientRef}>
+              {children}
+            </FathomProvider>
+          </FathomProvider>
+        )
+      }
+
+      renderHook(() => useFathom(), { wrapper: TestWrapper })
+
+      // Should inherit the parent client
+      expect(clientRefValue).toBe(parentClient)
+    })
+  })
 })

package/src/FathomProvider.tsx

@@ -11,6 +11,7 @@ import type { FathomProviderProps } from './types'
 const FathomProvider: React.FC<FathomProviderProps> = ({
   children,
   client: providedClient,
+  clientRef,
   clientOptions,
   siteId,
   defaultPageviewOptions: providedDefaultPageviewOptions,
@@ -65,8 +66,8 @@ const FathomProvider: React.FC<FathomProviderProps> = ({
   )
 
   const trackEvent = useCallback(
-    (category: string, options?: EventOptions) => {
-      client.trackEvent(category, {
+    (eventName: string, options?: EventOptions) => {
+      client.trackEvent(eventName, {
         ...defaultEventOptions,
         ...options,
       })
@@ -97,6 +98,13 @@ const FathomProvider: React.FC<FathomProviderProps> = ({
     }
   }, [clientOptions, load, siteId])
 
+  // Populate the clientRef so the parent component can access the client
+  useEffect(() => {
+    if (clientRef) {
+      clientRef.current = client
+    }
+  }, [client, clientRef])
+
   return (
     <FathomContext.Provider
       value={{

package/src/components/TrackClick.test.tsx

@@ -55,7 +55,7 @@ describe('TrackClick', () => {
 
   it('should track event with options', () => {
     render(
-      <TrackClick eventName="test-event" id="test-id" value={100}>
+      <TrackClick eventName="test-event" _site_id="test-site" _value={100}>
         <button>Click me</button>
       </TrackClick>,
       { wrapper },
@@ -64,8 +64,8 @@ describe('TrackClick', () => {
     fireEvent.click(screen.getByText('Click me'))
 
     expect(mockTrackEvent).toHaveBeenCalledWith('test-event', {
-      id: 'test-id',
-      value: 100,
+      _site_id: 'test-site',
+      _value: 100,
     })
   })
 
@@ -168,14 +168,14 @@ describe('TrackClick', () => {
     const customWrapper = ({ children }: { children: React.ReactNode }) => (
       <FathomProvider
         client={mockClient}
-        defaultEventOptions={{ id: 'default-id' }}
+        defaultEventOptions={{ _site_id: 'default-site' }}
       >
         {children}
       </FathomProvider>
     )
 
     render(
-      <TrackClick eventName="test-event" value={100}>
+      <TrackClick eventName="test-event" _value={100}>
         <button>Click me</button>
       </TrackClick>,
       { wrapper: customWrapper },
@@ -184,8 +184,8 @@ describe('TrackClick', () => {
     fireEvent.click(screen.getByText('Click me'))
 
     expect(mockTrackEvent).toHaveBeenCalledWith('test-event', {
-      id: 'default-id',
-      value: 100,
+      _site_id: 'default-site',
+      _value: 100,
     })
   })
 })

package/src/components/TrackClick.tsx

@@ -35,7 +35,7 @@ export interface TrackClickProps extends EventOptions {
  *
  * @example
  * ```tsx
- * <TrackClick eventName="cta-clicked" id="hero-cta">
+ * <TrackClick eventName="cta-clicked" _value={100}>
  *   <button>Get Started</button>
  * </TrackClick>
  * ```

package/src/components/TrackVisible.test.tsx

@@ -99,7 +99,7 @@ describe('TrackVisible', () => {
 
   it('should track event with options', async () => {
     render(
-      <TrackVisible eventName="test-event" id="test-id" value={100}>
+      <TrackVisible eventName="test-event" _site_id="test-site" _value={100}>
         <div>Content</div>
       </TrackVisible>,
       { wrapper },
@@ -120,8 +120,8 @@ describe('TrackVisible', () => {
 
     await waitFor(() => {
       expect(mockTrackEvent).toHaveBeenCalledWith('test-event', {
-        id: 'test-id',
-        value: 100,
+        _site_id: 'test-site',
+        _value: 100,
       })
     })
   })
@@ -275,14 +275,14 @@ describe('TrackVisible', () => {
     const customWrapper = ({ children }: { children: React.ReactNode }) => (
       <FathomProvider
         client={mockClient}
-        defaultEventOptions={{ id: 'default-id' }}
+        defaultEventOptions={{ _site_id: 'default-site' }}
       >
         {children}
       </FathomProvider>
     )
 
     render(
-      <TrackVisible eventName="test-event" value={100}>
+      <TrackVisible eventName="test-event" _value={100}>
         <div>Content</div>
       </TrackVisible>,
       { wrapper: customWrapper },
@@ -303,8 +303,8 @@ describe('TrackVisible', () => {
 
     await waitFor(() => {
       expect(mockTrackEvent).toHaveBeenCalledWith('test-event', {
-        id: 'default-id',
-        value: 100,
+        _site_id: 'default-site',
+        _value: 100,
       })
     })
   })

package/src/components/TrackVisible.tsx

@@ -35,7 +35,7 @@ export interface TrackVisibleProps extends EventOptions {
  *
  * @example
  * ```tsx
- * <TrackVisible eventName="section-viewed" section="hero">
+ * <TrackVisible eventName="section-viewed" _value={1}>
  *   <HeroSection />
  * </TrackVisible>
  * ```

package/src/hooks/useFathom.test.tsx

@@ -37,12 +37,23 @@ describe('useFathom', () => {
     expect(result.current.isTrackingEnabled).toBeDefined()
   })
 
-  it('should return empty context when used outside FathomProvider', () => {
+  it('should return stub methods when used outside FathomProvider', () => {
+    const consoleSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+
     const { result } = renderHook(() => useFathom())
 
+    // Client should be undefined, but methods should be stub functions
     expect(result.current.client).toBeUndefined()
-    expect(result.current.trackEvent).toBeUndefined()
-    expect(result.current.trackPageview).toBeUndefined()
+    expect(typeof result.current.trackEvent).toBe('function')
+    expect(typeof result.current.trackPageview).toBe('function')
+
+    // Calling stub methods should warn in development
+    result.current.trackEvent('test')
+    expect(consoleSpy).toHaveBeenCalledWith(
+      '[react-fathom] trackEvent() called without a FathomProvider. Wrap your app with <FathomProvider> to enable analytics tracking.',
+    )
+
+    consoleSpy.mockRestore()
   })
 
   it('should have displayName', () => {

package/src/hooks/useTrackOnClick.test.tsx

@@ -54,8 +54,8 @@ describe('useTrackOnClick', () => {
       () =>
         useTrackOnClick({
           eventName: 'test-event',
-          id: 'test-id',
-          value: 100,
+          _site_id: 'test-site',
+          _value: 100,
         }),
       { wrapper },
     )
@@ -63,8 +63,8 @@ describe('useTrackOnClick', () => {
     result.current()
 
     expect(mockTrackEvent).toHaveBeenCalledWith('test-event', {
-      id: 'test-id',
-      value: 100,
+      _site_id: 'test-site',
+      _value: 100,
     })
   })
 

package/src/hooks/useTrackOnClick.ts

@@ -30,7 +30,7 @@ export interface UseTrackOnClickOptions extends EventOptions {
  * function Button() {
  *   const handleClick = useTrackOnClick({
  *     eventName: 'button-click',
- *     id: 'signup-button',
+ *     _value: 100, // Optional: value in cents
  *     callback: (e) => {
  *       console.log('Button clicked!')
  *       // Your custom logic here

package/src/hooks/useTrackOnVisible.test.tsx

@@ -110,8 +110,8 @@ describe('useTrackOnVisible', () => {
     const TestComponent = () => {
       const ref = useTrackOnVisible({
         eventName: 'test-event',
-        id: 'test-id',
-        value: 100,
+        _site_id: 'test-site',
+        _value: 100,
       })
       return <div ref={ref}>Test</div>
     }
@@ -137,8 +137,8 @@ describe('useTrackOnVisible', () => {
 
     await waitFor(() => {
       expect(mockTrackEvent).toHaveBeenCalledWith('test-event', {
-        id: 'test-id',
-        value: 100,
+        _site_id: 'test-site',
+        _value: 100,
       })
     })
   })

package/src/hooks/useTrackOnVisible.ts

@@ -34,7 +34,7 @@ export interface UseTrackOnVisibleOptions extends EventOptions {
  * function Section() {
  *   const ref = useTrackOnVisible({
  *     eventName: 'section-viewed',
- *     section: 'hero',
+ *     _value: 1, // Optional: value in cents
  *     callback: (entry) => {
  *       console.log('Section is visible!', entry.isIntersecting)
  *       // Your custom logic here

package/src/index.ts

@@ -2,3 +2,4 @@ export * from './FathomContext'
 export * from './FathomProvider'
 export * from './hooks'
 export * from './components'
+export * from './types'