@posthog/react 1.2.3 → 1.4.0

package/src/components/PostHogFeature.tsx

@@ -1,7 +1,8 @@
 import { useFeatureFlagPayload, useFeatureFlagVariantKey, usePostHog } from '../hooks'
-import React, { Children, ReactNode, useCallback, useEffect, useRef } from 'react'
+import React from 'react'
 import { PostHog } from '../context'
-import { isFunction, isNull, isUndefined } from '../utils/type-utils'
+import { isFunction, isUndefined } from '../utils/type-utils'
+import { VisibilityAndClickTrackers } from './internal/VisibilityAndClickTrackers'
 
 export type PostHogFeatureProps = React.HTMLProps<HTMLDivElement> & {
     flag: string
@@ -25,6 +26,7 @@ export function PostHogFeature({
 }: PostHogFeatureProps): JSX.Element | null {
     const payload = useFeatureFlagPayload(flag)
     const variant = useFeatureFlagVariantKey(flag)
+    const posthog = usePostHog()
 
     const shouldTrackInteraction = trackInteraction ?? true
     const shouldTrackView = trackView ?? true
@@ -37,6 +39,8 @@ export function PostHogFeature({
                 options={visibilityObserverOptions}
                 trackInteraction={shouldTrackInteraction}
                 trackView={shouldTrackView}
+                onInteract={() => captureFeatureInteraction({ flag, posthog, flagVariant: variant })}
+                onView={() => captureFeatureView({ flag, posthog, flagVariant: variant })}
                 {...props}
             >
                 {childNode}
@@ -46,7 +50,7 @@ export function PostHogFeature({
     return <>{fallback}</>
 }
 
-function captureFeatureInteraction({
+export function captureFeatureInteraction({
     flag,
     posthog,
     flagVariant,
@@ -65,7 +69,7 @@ function captureFeatureInteraction({
     posthog.capture('$feature_interaction', properties)
 }
 
-function captureFeatureView({
+export function captureFeatureView({
     flag,
     posthog,
     flagVariant,
@@ -83,92 +87,3 @@ function captureFeatureView({
     }
     posthog.capture('$feature_view', properties)
 }
-
-function VisibilityAndClickTracker({
-    flag,
-    children,
-    onIntersect,
-    onClick,
-    trackView,
-    options,
-    ...props
-}: {
-    flag: string
-    children: React.ReactNode
-    onIntersect: (entry: IntersectionObserverEntry) => void
-    onClick: () => void
-    trackView: boolean
-    options?: IntersectionObserverInit
-}): JSX.Element {
-    const ref = useRef<HTMLDivElement>(null)
-    const posthog = usePostHog()
-
-    useEffect(() => {
-        if (isNull(ref.current) || !trackView) return
-
-        // eslint-disable-next-line compat/compat
-        const observer = new IntersectionObserver(([entry]) => onIntersect(entry), {
-            threshold: 0.1,
-            ...options,
-        })
-        observer.observe(ref.current)
-        return () => observer.disconnect()
-    }, [flag, options, posthog, ref, trackView, onIntersect])
-
-    return (
-        <div ref={ref} {...props} onClick={onClick}>
-            {children}
-        </div>
-    )
-}
-
-function VisibilityAndClickTrackers({
-    flag,
-    children,
-    trackInteraction,
-    trackView,
-    options,
-    ...props
-}: {
-    flag: string
-    children: React.ReactNode
-    trackInteraction: boolean
-    trackView: boolean
-    options?: IntersectionObserverInit
-}): JSX.Element {
-    const clickTrackedRef = useRef(false)
-    const visibilityTrackedRef = useRef(false)
-    const posthog = usePostHog()
-    const variant = useFeatureFlagVariantKey(flag)
-
-    const cachedOnClick = useCallback(() => {
-        if (!clickTrackedRef.current && trackInteraction) {
-            captureFeatureInteraction({ flag, posthog, flagVariant: variant })
-            clickTrackedRef.current = true
-        }
-    }, [flag, posthog, trackInteraction, variant])
-
-    const onIntersect = (entry: IntersectionObserverEntry) => {
-        if (!visibilityTrackedRef.current && entry.isIntersecting) {
-            captureFeatureView({ flag, posthog, flagVariant: variant })
-            visibilityTrackedRef.current = true
-        }
-    }
-
-    const trackedChildren = Children.map(children, (child: ReactNode) => {
-        return (
-            <VisibilityAndClickTracker
-                flag={flag}
-                onClick={cachedOnClick}
-                onIntersect={onIntersect}
-                trackView={trackView}
-                options={options}
-                {...props}
-            >
-                {child}
-            </VisibilityAndClickTracker>
-        )
-    })
-
-    return <>{trackedChildren}</>
-}

package/src/components/__tests__/PostHogCaptureOnViewed.test.tsx

@@ -0,0 +1,110 @@
+import * as React from 'react'
+import { render, screen } from '@testing-library/react'
+import { PostHog, PostHogProvider } from '../../context'
+import { PostHogCaptureOnViewed } from '../'
+import '@testing-library/jest-dom'
+
+describe('PostHogCaptureOnViewed component', () => {
+    let mockObserverCallback: any = null
+
+    let fakePosthog: PostHog
+
+    beforeEach(() => {
+        fakePosthog = {
+            capture: jest.fn(),
+        } as unknown as PostHog
+
+        const mockIntersectionObserver = jest.fn((callback) => {
+            mockObserverCallback = callback
+            return {
+                observe: jest.fn(),
+                unobserve: jest.fn(),
+                disconnect: jest.fn(),
+            }
+        })
+
+        mockIntersectionObserver.prototype = {}
+        // eslint-disable-next-line compat/compat
+        window.IntersectionObserver = mockIntersectionObserver as unknown as typeof IntersectionObserver
+    })
+
+    it('should render children', () => {
+        render(
+            <PostHogProvider client={fakePosthog}>
+                <PostHogCaptureOnViewed name="test-element">
+                    <div data-testid="child">Hello</div>
+                </PostHogCaptureOnViewed>
+            </PostHogProvider>
+        )
+
+        expect(screen.getByTestId('child')).toBeInTheDocument()
+    })
+
+    it('should track when element comes into view', () => {
+        render(
+            <PostHogProvider client={fakePosthog}>
+                <PostHogCaptureOnViewed name="test-element">
+                    <div data-testid="child">Hello</div>
+                </PostHogCaptureOnViewed>
+            </PostHogProvider>
+        )
+
+        expect(fakePosthog.capture).not.toHaveBeenCalled()
+
+        mockObserverCallback([{ isIntersecting: true }])
+
+        expect(fakePosthog.capture).toHaveBeenCalledWith('$element_viewed', {
+            element_name: 'test-element',
+        })
+        expect(fakePosthog.capture).toHaveBeenCalledTimes(1)
+    })
+
+    it('should only track visibility once', () => {
+        render(
+            <PostHogProvider client={fakePosthog}>
+                <PostHogCaptureOnViewed name="test-element">
+                    <div data-testid="child">Hello</div>
+                </PostHogCaptureOnViewed>
+            </PostHogProvider>
+        )
+
+        mockObserverCallback([{ isIntersecting: true }])
+        expect(fakePosthog.capture).toHaveBeenCalledTimes(1)
+
+        mockObserverCallback([{ isIntersecting: true }])
+        mockObserverCallback([{ isIntersecting: true }])
+        expect(fakePosthog.capture).toHaveBeenCalledTimes(1)
+    })
+
+    it('should include custom properties', () => {
+        render(
+            <PostHogProvider client={fakePosthog}>
+                <PostHogCaptureOnViewed name="test-element" properties={{ category: 'hero', priority: 'high' }}>
+                    <div data-testid="child">Hello</div>
+                </PostHogCaptureOnViewed>
+            </PostHogProvider>
+        )
+
+        mockObserverCallback([{ isIntersecting: true }])
+
+        expect(fakePosthog.capture).toHaveBeenCalledWith('$element_viewed', {
+            element_name: 'test-element',
+            category: 'hero',
+            priority: 'high',
+        })
+    })
+
+    it('should not track when element is not intersecting', () => {
+        render(
+            <PostHogProvider client={fakePosthog}>
+                <PostHogCaptureOnViewed name="test-element">
+                    <div data-testid="child">Hello</div>
+                </PostHogCaptureOnViewed>
+            </PostHogProvider>
+        )
+
+        mockObserverCallback([{ isIntersecting: false }])
+
+        expect(fakePosthog.capture).not.toHaveBeenCalled()
+    })
+})

package/src/components/__tests__/{PostHogErrorBoundary.test.jsx → PostHogErrorBoundary.test.tsx}

@@ -10,25 +10,25 @@ describe('PostHogErrorBoundary component', () => {
     mockFunction(console, 'warn')
     mockFunction(posthog, 'captureException')
 
-    given('render_with_error', () => (props) => render(<RenderWithError {...props} />))
-    given('render_without_error', () => (props) => render(<RenderWithoutError {...props} />))
+    const renderWithError = (props: any) => render(<RenderWithError {...props} />)
+    const renderWithoutError = (props?: any) => render(<RenderWithoutError {...props} />)
 
     it('should call captureException with error message', () => {
-        const { container } = given.render_with_error({ message: 'Test error', fallback: <div></div> })
+        const { container } = renderWithError({ message: 'Test error', fallback: <div></div> })
         expect(posthog.captureException).toHaveBeenCalledWith(new Error('Test error'), undefined)
         expect(container.innerHTML).toBe('<div></div>')
         expect(console.error).toHaveBeenCalledTimes(2)
     })
 
     it('should warn user when fallback is null', () => {
-        const { container } = given.render_with_error({ fallback: null })
+        const { container } = renderWithError({ fallback: null })
         expect(posthog.captureException).toHaveBeenCalledWith(new Error('Error'), undefined)
         expect(container.innerHTML).toBe('')
         expect(console.warn).toHaveBeenCalledWith(__POSTHOG_ERROR_MESSAGES.INVALID_FALLBACK)
     })
 
     it('should warn user when fallback is a string', () => {
-        const { container } = given.render_with_error({ fallback: 'hello' })
+        const { container } = renderWithError({ fallback: 'hello' })
         expect(posthog.captureException).toHaveBeenCalledWith(new Error('Error'), undefined)
         expect(container.innerHTML).toBe('')
         expect(console.warn).toHaveBeenCalledWith(__POSTHOG_ERROR_MESSAGES.INVALID_FALLBACK)
@@ -36,15 +36,15 @@ describe('PostHogErrorBoundary component', () => {
 
     it('should add additional properties before sending event (as object)', () => {
         const props = { team_id: '1234' }
-        given.render_with_error({ message: 'Kaboom', additionalProperties: props })
+        renderWithError({ message: 'Kaboom', additionalProperties: props })
         expect(posthog.captureException).toHaveBeenCalledWith(new Error('Kaboom'), props)
     })
 
     it('should add additional properties before sending event (as function)', () => {
         const props = { team_id: '1234' }
-        given.render_with_error({
+        renderWithError({
             message: 'Kaboom',
-            additionalProperties: (err) => {
+            additionalProperties: (err: Error) => {
                 expect(err.message).toBe('Kaboom')
                 return props
             },
@@ -53,7 +53,7 @@ describe('PostHogErrorBoundary component', () => {
     })
 
     it('should render children without errors', () => {
-        const { container } = given.render_without_error()
+        const { container } = renderWithoutError()
         expect(container.innerHTML).toBe('<div>Amazing content</div>')
     })
 })
@@ -63,11 +63,11 @@ describe('captureException processing', () => {
     mockFunction(console, 'warn')
     mockFunction(posthog, 'capture')
 
-    given('render_with_error', () => (props) => render(<RenderWithError {...props} />))
+    const renderWithError = (props: any) => render(<RenderWithError {...props} />)
 
     it('should call capture with a stacktrace', () => {
-        given.render_with_error({ message: 'Kaboom', fallback: <div></div>, additionalProperties: {} })
-        const captureCalls = posthog.capture.mock.calls
+        renderWithError({ message: 'Kaboom', fallback: <div></div>, additionalProperties: {} })
+        const captureCalls = (posthog.capture as jest.Mock).mock.calls
         expect(captureCalls.length).toBe(1)
         const exceptionList = captureCalls[0][1].$exception_list
         expect(exceptionList.length).toBe(1)
@@ -76,7 +76,7 @@ describe('captureException processing', () => {
     })
 })
 
-function mockFunction(object, funcName) {
+function mockFunction(object: any, funcName: string) {
     const originalFunc = object[funcName]
 
     beforeEach(() => {
@@ -88,11 +88,11 @@ function mockFunction(object, funcName) {
     })
 }
 
-function ComponentWithError({ message }) {
+function ComponentWithError({ message }: { message: string }): React.ReactElement {
     throw new Error(message)
 }
 
-function RenderWithError({ message = 'Error', fallback, additionalProperties }) {
+function RenderWithError({ message = 'Error', fallback, additionalProperties }: any) {
     return (
         <PostHogErrorBoundary fallback={fallback} additionalProperties={additionalProperties}>
             <ComponentWithError message={message} />
@@ -100,7 +100,7 @@ function RenderWithError({ message = 'Error', fallback, additionalProperties })
     )
 }
 
-function RenderWithoutError({ additionalProperties }) {
+function RenderWithoutError({ additionalProperties }: any) {
     return (
         <PostHogErrorBoundary fallback={<div></div>} additionalProperties={additionalProperties}>
             <div>Amazing content</div>

package/src/components/__tests__/PostHogFeature.test.tsx

@@ -0,0 +1,252 @@
+import * as React from 'react'
+import { useState } from 'react'
+import { render, screen, fireEvent } from '@testing-library/react'
+import { PostHogProvider, PostHog } from '../../context'
+import { PostHogFeature } from '../'
+import '@testing-library/jest-dom'
+
+const FEATURE_FLAG_STATUS: Record<string, string | boolean> = {
+    multivariate_feature: 'string-value',
+    example_feature_payload: 'test',
+    test: true,
+    test_false: false,
+}
+
+const FEATURE_FLAG_PAYLOADS: Record<string, any> = {
+    example_feature_payload: {
+        id: 1,
+        name: 'example_feature_1_payload',
+        key: 'example_feature_1_payload',
+    },
+}
+
+describe('PostHogFeature component', () => {
+    let posthog: PostHog
+
+    const renderWith = (instance: PostHog, flag = 'test', matchValue: string | boolean | undefined = true) =>
+        render(
+            <PostHogProvider client={instance}>
+                <PostHogFeature flag={flag} match={matchValue}>
+                    <div data-testid="helloDiv">Hello</div>
+                </PostHogFeature>
+            </PostHogProvider>
+        )
+
+    beforeEach(() => {
+        // IntersectionObserver isn't available in test environment
+        const mockIntersectionObserver = jest.fn()
+        mockIntersectionObserver.mockReturnValue({
+            observe: () => null,
+            unobserve: () => null,
+            disconnect: () => null,
+        })
+
+        // eslint-disable-next-line compat/compat
+        window.IntersectionObserver = mockIntersectionObserver
+
+        posthog = {
+            isFeatureEnabled: (flag: string) => !!FEATURE_FLAG_STATUS[flag],
+            getFeatureFlag: (flag: string) => FEATURE_FLAG_STATUS[flag],
+            getFeatureFlagPayload: (flag: string) => FEATURE_FLAG_PAYLOADS[flag],
+            onFeatureFlags: (callback: any) => {
+                const activeFlags: string[] = []
+                for (const flag in FEATURE_FLAG_STATUS) {
+                    if (FEATURE_FLAG_STATUS[flag]) {
+                        activeFlags.push(flag)
+                    }
+                }
+                callback(activeFlags)
+                return () => {}
+            },
+            capture: jest.fn(),
+            featureFlags: {
+                hasLoadedFlags: true,
+            },
+        } as unknown as PostHog
+    })
+
+    it('should track interactions with the feature component', () => {
+        renderWith(posthog)
+
+        fireEvent.click(screen.getByTestId('helloDiv'))
+        expect(posthog.capture).toHaveBeenCalledWith('$feature_interaction', {
+            feature_flag: 'test',
+            $set: { '$feature_interaction/test': true },
+        })
+        expect(posthog.capture).toHaveBeenCalledTimes(1)
+    })
+
+    it('should not fire for every interaction with the feature component', () => {
+        renderWith(posthog)
+
+        fireEvent.click(screen.getByTestId('helloDiv'))
+        expect(posthog.capture).toHaveBeenCalledWith('$feature_interaction', {
+            feature_flag: 'test',
+            $set: { '$feature_interaction/test': true },
+        })
+        expect(posthog.capture).toHaveBeenCalledTimes(1)
+
+        fireEvent.click(screen.getByTestId('helloDiv'))
+        fireEvent.click(screen.getByTestId('helloDiv'))
+        fireEvent.click(screen.getByTestId('helloDiv'))
+        expect(posthog.capture).toHaveBeenCalledTimes(1)
+    })
+
+    it('should track an interaction with each child node of the feature component', () => {
+        render(
+            <PostHogProvider client={posthog}>
+                <PostHogFeature flag={'test'} match={true}>
+                    <div data-testid="helloDiv">Hello</div>
+                    <div data-testid="worldDiv">World!</div>
+                </PostHogFeature>
+            </PostHogProvider>
+        )
+
+        fireEvent.click(screen.getByTestId('helloDiv'))
+        fireEvent.click(screen.getByTestId('helloDiv'))
+        fireEvent.click(screen.getByTestId('worldDiv'))
+        fireEvent.click(screen.getByTestId('worldDiv'))
+        fireEvent.click(screen.getByTestId('worldDiv'))
+        expect(posthog.capture).toHaveBeenCalledWith('$feature_interaction', {
+            feature_flag: 'test',
+            $set: { '$feature_interaction/test': true },
+        })
+        expect(posthog.capture).toHaveBeenCalledTimes(1)
+    })
+
+    it('should not fire events when interaction is disabled', () => {
+        render(
+            <PostHogProvider client={posthog}>
+                <PostHogFeature flag={'test'} match={true} trackInteraction={false}>
+                    <div data-testid="helloDiv">Hello</div>
+                </PostHogFeature>
+            </PostHogProvider>
+        )
+
+        fireEvent.click(screen.getByTestId('helloDiv'))
+        expect(posthog.capture).not.toHaveBeenCalled()
+
+        fireEvent.click(screen.getByTestId('helloDiv'))
+        fireEvent.click(screen.getByTestId('helloDiv'))
+        fireEvent.click(screen.getByTestId('helloDiv'))
+        expect(posthog.capture).not.toHaveBeenCalled()
+    })
+
+    it('should fire events when interaction is disabled but re-enabled after', () => {
+        const DynamicUpdateComponent = () => {
+            const [trackInteraction, setTrackInteraction] = useState(false)
+
+            return (
+                <>
+                    <div
+                        data-testid="clicker"
+                        onClick={() => {
+                            setTrackInteraction(true)
+                        }}
+                    >
+                        Click me
+                    </div>
+                    <PostHogFeature flag={'test'} match={true} trackInteraction={trackInteraction}>
+                        <div data-testid="helloDiv">Hello</div>
+                    </PostHogFeature>
+                </>
+            )
+        }
+
+        render(
+            <PostHogProvider client={posthog}>
+                <DynamicUpdateComponent />
+            </PostHogProvider>
+        )
+
+        fireEvent.click(screen.getByTestId('helloDiv'))
+        expect(posthog.capture).not.toHaveBeenCalled()
+
+        fireEvent.click(screen.getByTestId('clicker'))
+        fireEvent.click(screen.getByTestId('helloDiv'))
+        fireEvent.click(screen.getByTestId('helloDiv'))
+        expect(posthog.capture).toHaveBeenCalledWith('$feature_interaction', {
+            feature_flag: 'test',
+            $set: { '$feature_interaction/test': true },
+        })
+        expect(posthog.capture).toHaveBeenCalledTimes(1)
+    })
+
+    it('should not show the feature component if the flag is not enabled', () => {
+        renderWith(posthog, 'test_value')
+
+        expect(screen.queryByTestId('helloDiv')).not.toBeInTheDocument()
+        expect(posthog.capture).not.toHaveBeenCalled()
+
+        // check if any elements are found
+        const allTags = screen.queryAllByText(/.*/)
+
+        // Assert that no random elements are found
+        expect(allTags.length).toEqual(2)
+        expect(allTags[0].tagName).toEqual('BODY')
+        expect(allTags[1].tagName).toEqual('DIV')
+    })
+
+    it('should fallback when provided', () => {
+        render(
+            <PostHogProvider client={posthog}>
+                <PostHogFeature flag={'test_false'} match={true} fallback={<div data-testid="nope">Nope</div>}>
+                    <div data-testid="helloDiv">Hello</div>
+                </PostHogFeature>
+            </PostHogProvider>
+        )
+
+        expect(screen.queryByTestId('helloDiv')).not.toBeInTheDocument()
+        expect(posthog.capture).not.toHaveBeenCalled()
+
+        fireEvent.click(screen.getByTestId('nope'))
+        expect(posthog.capture).not.toHaveBeenCalled()
+    })
+
+    it('should handle showing multivariate flags with bool match', () => {
+        renderWith(posthog, 'multivariate_feature')
+
+        expect(screen.queryByTestId('helloDiv')).not.toBeInTheDocument()
+        expect(posthog.capture).not.toHaveBeenCalled()
+    })
+
+    it('should handle showing multivariate flags with incorrect match', () => {
+        renderWith(posthog, 'multivariate_feature', 'string-valueCXCC')
+
+        expect(screen.queryByTestId('helloDiv')).not.toBeInTheDocument()
+        expect(posthog.capture).not.toHaveBeenCalled()
+    })
+
+    it('should handle showing multivariate flags', () => {
+        renderWith(posthog, 'multivariate_feature', 'string-value')
+
+        expect(screen.queryByTestId('helloDiv')).toBeInTheDocument()
+        expect(posthog.capture).not.toHaveBeenCalled()
+
+        fireEvent.click(screen.getByTestId('helloDiv'))
+        expect(posthog.capture).toHaveBeenCalledWith('$feature_interaction', {
+            feature_flag: 'multivariate_feature',
+            feature_flag_variant: 'string-value',
+            $set: { '$feature_interaction/multivariate_feature': 'string-value' },
+        })
+        expect(posthog.capture).toHaveBeenCalledTimes(1)
+    })
+
+    it('should handle payload flags', () => {
+        render(
+            <PostHogProvider client={posthog}>
+                <PostHogFeature flag={'example_feature_payload'} match={'test'}>
+                    {(payload: any) => {
+                        return <div data-testid={`hi_${payload.name}`}>Hullo</div>
+                    }}
+                </PostHogFeature>
+            </PostHogProvider>
+        )
+
+        expect(screen.queryByTestId('hi_example_feature_1_payload')).toBeInTheDocument()
+        expect(posthog.capture).not.toHaveBeenCalled()
+
+        fireEvent.click(screen.getByTestId('hi_example_feature_1_payload'))
+        expect(posthog.capture).toHaveBeenCalledTimes(1)
+    })
+})

package/src/components/index.ts

@@ -1,4 +1,5 @@
 export * from './PostHogFeature'
+export * from './PostHogCaptureOnViewed'
 export {
     PostHogErrorBoundary,
     PostHogErrorBoundaryProps,

package/src/components/internal/VisibilityAndClickTracker.tsx

@@ -0,0 +1,49 @@
+import React, { MouseEventHandler, useEffect, useMemo, useRef } from 'react'
+import { isNull } from '../../utils/type-utils'
+
+/**
+ * VisibilityAndClickTracker is an internal component,
+ * its API might change without warning and without being signalled as a breaking change
+ *
+ * Wraps the provided children in a div, and tracks visibility of and clicks on that div
+ */
+export function VisibilityAndClickTracker({
+    children,
+    onIntersect,
+    onClick,
+    trackView,
+    options,
+    ...props
+}: {
+    children: React.ReactNode
+    onIntersect: (entry: IntersectionObserverEntry) => void
+    onClick?: MouseEventHandler<HTMLDivElement>
+    trackView: boolean
+    options?: IntersectionObserverInit
+}): JSX.Element {
+    const ref = useRef<HTMLDivElement>(null)
+
+    const observerOptions = useMemo(
+        () => ({
+            threshold: 0.1,
+            ...options,
+        }),
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+        [options?.threshold, options?.root, options?.rootMargin]
+    )
+
+    useEffect(() => {
+        if (isNull(ref.current) || !trackView) return
+
+        // eslint-disable-next-line compat/compat
+        const observer = new IntersectionObserver(([entry]) => onIntersect(entry), observerOptions)
+        observer.observe(ref.current)
+        return () => observer.disconnect()
+    }, [observerOptions, trackView, onIntersect])
+
+    return (
+        <div ref={ref} {...props} onClick={onClick}>
+            {children}
+        </div>
+    )
+}