@posthog/react 1.2.1 → 1.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@posthog/react",
-  "version": "1.2.1",
+  "version": "1.2.3",
   "description": "Provides components and hooks for React integrations of PostHog.",
   "repository": {
     "type": "git",
@@ -14,8 +14,8 @@
   "module": "dist/esm/index.js",
   "types": "dist/types/index.d.ts",
   "files": [
-    "dist/*",
-    "README.md"
+    "dist",
+    "src"
   ],
   "peerDependencies": {
     "@types/react": ">=16.8.0",
@@ -48,7 +48,7 @@
     "tslib": "^2.5.0",
     "typescript": "^5.5.4",
     "@posthog-tooling/rollup-utils": "1.0.0",
-    "posthog-js": "1.269.0"
+    "posthog-js": "1.270.1"
   },
   "scripts": {
     "clean": "rimraf dist",

package/src/components/PostHogErrorBoundary.tsx

@@ -0,0 +1,88 @@
+import React, { FunctionComponent } from 'react'
+import { PostHogContext } from '../context'
+import { isFunction } from '../utils/type-utils'
+
+export type Properties = Record<string, any>
+
+export type PostHogErrorBoundaryFallbackProps = {
+    error: unknown
+    exceptionEvent: unknown
+    componentStack: string
+}
+
+export type PostHogErrorBoundaryProps = {
+    children?: React.ReactNode | (() => React.ReactNode)
+    fallback?: React.ReactNode | FunctionComponent<PostHogErrorBoundaryFallbackProps>
+    additionalProperties?: Properties | ((error: unknown) => Properties)
+}
+
+type PostHogErrorBoundaryState = {
+    componentStack: string | null
+    exceptionEvent: unknown
+    error: unknown
+}
+
+const INITIAL_STATE: PostHogErrorBoundaryState = {
+    componentStack: null,
+    exceptionEvent: null,
+    error: null,
+}
+
+export const __POSTHOG_ERROR_MESSAGES = {
+    INVALID_FALLBACK:
+        '[PostHog.js][PostHogErrorBoundary] Invalid fallback prop, provide a valid React element or a function that returns a valid React element.',
+}
+
+export class PostHogErrorBoundary extends React.Component<PostHogErrorBoundaryProps, PostHogErrorBoundaryState> {
+    static contextType = PostHogContext
+
+    constructor(props: PostHogErrorBoundaryProps) {
+        super(props)
+        this.state = INITIAL_STATE
+    }
+
+    componentDidCatch(error: unknown, errorInfo: React.ErrorInfo) {
+        //eslint-disable-next-line react/prop-types
+        const { additionalProperties } = this.props
+        let currentProperties
+        if (isFunction(additionalProperties)) {
+            currentProperties = additionalProperties(error)
+        } else if (typeof additionalProperties === 'object') {
+            currentProperties = additionalProperties
+        }
+        const { client } = this.context
+        const exceptionEvent = client.captureException(error, currentProperties)
+
+        const { componentStack } = errorInfo
+        this.setState({
+            error,
+            componentStack,
+            exceptionEvent,
+        })
+    }
+
+    public render(): React.ReactNode {
+        //eslint-disable-next-line react/prop-types
+        const { children, fallback } = this.props
+        const state = this.state
+
+        if (state.componentStack == null) {
+            return isFunction(children) ? children() : children
+        }
+
+        const element = isFunction(fallback)
+            ? (React.createElement(fallback, {
+                  error: state.error,
+                  componentStack: state.componentStack,
+                  exceptionEvent: state.exceptionEvent,
+              }) as React.ReactNode)
+            : fallback
+
+        if (React.isValidElement(element)) {
+            return element as React.ReactElement
+        }
+        //eslint-disable-next-line no-console
+        console.warn(__POSTHOG_ERROR_MESSAGES.INVALID_FALLBACK)
+        return <></>
+    }
+}

package/src/components/PostHogFeature.tsx

@@ -0,0 +1,174 @@
+import { useFeatureFlagPayload, useFeatureFlagVariantKey, usePostHog } from '../hooks'
+import React, { Children, ReactNode, useCallback, useEffect, useRef } from 'react'
+import { PostHog } from '../context'
+import { isFunction, isNull, isUndefined } from '../utils/type-utils'
+
+export type PostHogFeatureProps = React.HTMLProps<HTMLDivElement> & {
+    flag: string
+    children: React.ReactNode | ((payload: any) => React.ReactNode)
+    fallback?: React.ReactNode
+    match?: string | boolean
+    visibilityObserverOptions?: IntersectionObserverInit
+    trackInteraction?: boolean
+    trackView?: boolean
+}
+
+export function PostHogFeature({
+    flag,
+    match,
+    children,
+    fallback,
+    visibilityObserverOptions,
+    trackInteraction,
+    trackView,
+    ...props
+}: PostHogFeatureProps): JSX.Element | null {
+    const payload = useFeatureFlagPayload(flag)
+    const variant = useFeatureFlagVariantKey(flag)
+
+    const shouldTrackInteraction = trackInteraction ?? true
+    const shouldTrackView = trackView ?? true
+
+    if (isUndefined(match) || variant === match) {
+        const childNode: React.ReactNode = isFunction(children) ? children(payload) : children
+        return (
+            <VisibilityAndClickTrackers
+                flag={flag}
+                options={visibilityObserverOptions}
+                trackInteraction={shouldTrackInteraction}
+                trackView={shouldTrackView}
+                {...props}
+            >
+                {childNode}
+            </VisibilityAndClickTrackers>
+        )
+    }
+    return <>{fallback}</>
+}
+
+function captureFeatureInteraction({
+    flag,
+    posthog,
+    flagVariant,
+}: {
+    flag: string
+    posthog: PostHog
+    flagVariant?: string | boolean
+}) {
+    const properties: Record<string, any> = {
+        feature_flag: flag,
+        $set: { [`$feature_interaction/${flag}`]: flagVariant ?? true },
+    }
+    if (typeof flagVariant === 'string') {
+        properties.feature_flag_variant = flagVariant
+    }
+    posthog.capture('$feature_interaction', properties)
+}
+
+function captureFeatureView({
+    flag,
+    posthog,
+    flagVariant,
+}: {
+    flag: string
+    posthog: PostHog
+    flagVariant?: string | boolean
+}) {
+    const properties: Record<string, any> = {
+        feature_flag: flag,
+        $set: { [`$feature_view/${flag}`]: flagVariant ?? true },
+    }
+    if (typeof flagVariant === 'string') {
+        properties.feature_flag_variant = flagVariant
+    }
+    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__/PostHogErrorBoundary.test.jsx

@@ -0,0 +1,109 @@
+/* eslint-disable no-console */
+
+import * as React from 'react'
+import { render } from '@testing-library/react'
+import { __POSTHOG_ERROR_MESSAGES, PostHogErrorBoundary } from '../PostHogErrorBoundary'
+import posthog from 'posthog-js'
+
+describe('PostHogErrorBoundary component', () => {
+    mockFunction(console, 'error')
+    mockFunction(console, 'warn')
+    mockFunction(posthog, 'captureException')
+
+    given('render_with_error', () => (props) => render(<RenderWithError {...props} />))
+    given('render_without_error', () => (props) => render(<RenderWithoutError {...props} />))
+
+    it('should call captureException with error message', () => {
+        const { container } = given.render_with_error({ 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 })
+        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' })
+        expect(posthog.captureException).toHaveBeenCalledWith(new Error('Error'), undefined)
+        expect(container.innerHTML).toBe('')
+        expect(console.warn).toHaveBeenCalledWith(__POSTHOG_ERROR_MESSAGES.INVALID_FALLBACK)
+    })
+
+    it('should add additional properties before sending event (as object)', () => {
+        const props = { team_id: '1234' }
+        given.render_with_error({ 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({
+            message: 'Kaboom',
+            additionalProperties: (err) => {
+                expect(err.message).toBe('Kaboom')
+                return props
+            },
+        })
+        expect(posthog.captureException).toHaveBeenCalledWith(new Error('Kaboom'), props)
+    })
+
+    it('should render children without errors', () => {
+        const { container } = given.render_without_error()
+        expect(container.innerHTML).toBe('<div>Amazing content</div>')
+    })
+})
+
+describe('captureException processing', () => {
+    mockFunction(console, 'error')
+    mockFunction(console, 'warn')
+    mockFunction(posthog, 'capture')
+
+    given('render_with_error', () => (props) => 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
+        expect(captureCalls.length).toBe(1)
+        const exceptionList = captureCalls[0][1].$exception_list
+        expect(exceptionList.length).toBe(1)
+        const stacktrace = exceptionList[0].stacktrace
+        expect(stacktrace.frames.length).toBe(44)
+    })
+})
+
+function mockFunction(object, funcName) {
+    const originalFunc = object[funcName]
+
+    beforeEach(() => {
+        object[funcName] = jest.fn()
+    })
+
+    afterEach(() => {
+        object[funcName] = originalFunc
+    })
+}
+
+function ComponentWithError({ message }) {
+    throw new Error(message)
+}
+
+function RenderWithError({ message = 'Error', fallback, additionalProperties }) {
+    return (
+        <PostHogErrorBoundary fallback={fallback} additionalProperties={additionalProperties}>
+            <ComponentWithError message={message} />
+        </PostHogErrorBoundary>
+    )
+}
+
+function RenderWithoutError({ additionalProperties }) {
+    return (
+        <PostHogErrorBoundary fallback={<div></div>} additionalProperties={additionalProperties}>
+            <div>Amazing content</div>
+        </PostHogErrorBoundary>
+    )
+}

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

@@ -0,0 +1,298 @@
+import * as React from 'react'
+import { useState } from 'react'
+import { render, screen, fireEvent } from '@testing-library/react'
+import { PostHogProvider } from '../../context'
+import { PostHogFeature } from '../'
+import '@testing-library/jest-dom'
+
+const FEATURE_FLAG_STATUS = {
+    multivariate_feature: 'string-value',
+    example_feature_payload: 'test',
+    test: true,
+    test_false: false,
+}
+
+const FEATURE_FLAG_PAYLOADS = {
+    example_feature_payload: {
+        id: 1,
+        name: 'example_feature_1_payload',
+        key: 'example_feature_1_payload',
+    },
+}
+
+describe('PostHogFeature component', () => {
+    given('featureFlag', () => 'test')
+    given('matchValue', () => true)
+    given(
+        'render',
+        () => () =>
+            render(
+                <PostHogProvider client={given.posthog}>
+                    <PostHogFeature flag={given.featureFlag} match={given.matchValue}>
+                        <div data-testid="helloDiv">Hello</div>
+                    </PostHogFeature>
+                </PostHogProvider>
+            )
+    )
+    given('posthog', () => ({
+        isFeatureEnabled: (flag) => !!FEATURE_FLAG_STATUS[flag],
+        getFeatureFlag: (flag) => FEATURE_FLAG_STATUS[flag],
+        getFeatureFlagPayload: (flag) => FEATURE_FLAG_PAYLOADS[flag],
+        onFeatureFlags: (callback) => {
+            const activeFlags = []
+            for (const flag in FEATURE_FLAG_STATUS) {
+                if (FEATURE_FLAG_STATUS[flag]) {
+                    activeFlags.push(flag)
+                }
+            }
+            callback(activeFlags)
+            return () => {}
+        },
+        capture: jest.fn(),
+    }))
+
+    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
+    })
+
+    it('should track interactions with the feature component', () => {
+        given.render()
+
+        fireEvent.click(screen.getByTestId('helloDiv'))
+        expect(given.posthog.capture).toHaveBeenCalledWith('$feature_interaction', {
+            feature_flag: 'test',
+            $set: { '$feature_interaction/test': true },
+        })
+        expect(given.posthog.capture).toHaveBeenCalledTimes(1)
+    })
+
+    it('should not fire for every interaction with the feature component', () => {
+        given.render()
+
+        fireEvent.click(screen.getByTestId('helloDiv'))
+        expect(given.posthog.capture).toHaveBeenCalledWith('$feature_interaction', {
+            feature_flag: 'test',
+            $set: { '$feature_interaction/test': true },
+        })
+        expect(given.posthog.capture).toHaveBeenCalledTimes(1)
+
+        fireEvent.click(screen.getByTestId('helloDiv'))
+        fireEvent.click(screen.getByTestId('helloDiv'))
+        fireEvent.click(screen.getByTestId('helloDiv'))
+        expect(given.posthog.capture).toHaveBeenCalledTimes(1)
+    })
+
+    it('should track an interaction with each child node of the feature component', () => {
+        given(
+            'render',
+            () => () =>
+                render(
+                    <PostHogProvider client={given.posthog}>
+                        <PostHogFeature flag={given.featureFlag} match={given.matchValue}>
+                            <div data-testid="helloDiv">Hello</div>
+                            <div data-testid="worldDiv">World!</div>
+                        </PostHogFeature>
+                    </PostHogProvider>
+                )
+        )
+        given.render()
+
+        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(given.posthog.capture).toHaveBeenCalledWith('$feature_interaction', {
+            feature_flag: 'test',
+            $set: { '$feature_interaction/test': true },
+        })
+        expect(given.posthog.capture).toHaveBeenCalledTimes(1)
+    })
+
+    it('should not fire events when interaction is disabled', () => {
+        given(
+            'render',
+            () => () =>
+                render(
+                    <PostHogProvider client={given.posthog}>
+                        <PostHogFeature flag={given.featureFlag} match={given.matchValue} trackInteraction={false}>
+                            <div data-testid="helloDiv">Hello</div>
+                        </PostHogFeature>
+                    </PostHogProvider>
+                )
+        )
+        given.render()
+
+        fireEvent.click(screen.getByTestId('helloDiv'))
+        expect(given.posthog.capture).not.toHaveBeenCalled()
+
+        fireEvent.click(screen.getByTestId('helloDiv'))
+        fireEvent.click(screen.getByTestId('helloDiv'))
+        fireEvent.click(screen.getByTestId('helloDiv'))
+        expect(given.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={given.featureFlag}
+                        match={given.matchValue}
+                        trackInteraction={trackInteraction}
+                    >
+                        <div data-testid="helloDiv">Hello</div>
+                    </PostHogFeature>
+                </>
+            )
+        }
+
+        given(
+            'render',
+            () => () =>
+                render(
+                    <PostHogProvider client={given.posthog}>
+                        <DynamicUpdateComponent />
+                    </PostHogProvider>
+                )
+        )
+        given.render()
+
+        fireEvent.click(screen.getByTestId('helloDiv'))
+        expect(given.posthog.capture).not.toHaveBeenCalled()
+
+        fireEvent.click(screen.getByTestId('clicker'))
+        fireEvent.click(screen.getByTestId('helloDiv'))
+        fireEvent.click(screen.getByTestId('helloDiv'))
+        expect(given.posthog.capture).toHaveBeenCalledWith('$feature_interaction', {
+            feature_flag: 'test',
+            $set: { '$feature_interaction/test': true },
+        })
+        expect(given.posthog.capture).toHaveBeenCalledTimes(1)
+    })
+
+    it('should not show the feature component if the flag is not enabled', () => {
+        given('featureFlag', () => 'test_false')
+        given.render()
+
+        expect(screen.queryByTestId('helloDiv')).not.toBeInTheDocument()
+        expect(given.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', () => {
+        given('featureFlag', () => 'test_false')
+        given(
+            'render',
+            () => () =>
+                render(
+                    <PostHogProvider client={given.posthog}>
+                        <PostHogFeature
+                            flag={given.featureFlag}
+                            match={given.matchValue}
+                            fallback={<div data-testid="nope">Nope</div>}
+                        >
+                            <div data-testid="helloDiv">Hello</div>
+                        </PostHogFeature>
+                    </PostHogProvider>
+                )
+        )
+        given.render()
+
+        expect(screen.queryByTestId('helloDiv')).not.toBeInTheDocument()
+        expect(given.posthog.capture).not.toHaveBeenCalled()
+
+        fireEvent.click(screen.getByTestId('nope'))
+        expect(given.posthog.capture).not.toHaveBeenCalled()
+    })
+
+    it('should handle showing multivariate flags with bool match', () => {
+        given('featureFlag', () => 'multivariate_feature')
+        given('matchValue', () => true)
+
+        given.render()
+
+        expect(screen.queryByTestId('helloDiv')).not.toBeInTheDocument()
+        expect(given.posthog.capture).not.toHaveBeenCalled()
+    })
+
+    it('should handle showing multivariate flags with incorrect match', () => {
+        given('featureFlag', () => 'multivariate_feature')
+        given('matchValue', () => 'string-valueCXCC')
+
+        given.render()
+
+        expect(screen.queryByTestId('helloDiv')).not.toBeInTheDocument()
+        expect(given.posthog.capture).not.toHaveBeenCalled()
+    })
+
+    it('should handle showing multivariate flags', () => {
+        given('featureFlag', () => 'multivariate_feature')
+        given('matchValue', () => 'string-value')
+
+        given.render()
+
+        expect(screen.queryByTestId('helloDiv')).toBeInTheDocument()
+        expect(given.posthog.capture).not.toHaveBeenCalled()
+
+        fireEvent.click(screen.getByTestId('helloDiv'))
+        expect(given.posthog.capture).toHaveBeenCalledWith('$feature_interaction', {
+            feature_flag: 'multivariate_feature',
+            feature_flag_variant: 'string-value',
+            $set: { '$feature_interaction/multivariate_feature': 'string-value' },
+        })
+        expect(given.posthog.capture).toHaveBeenCalledTimes(1)
+    })
+
+    it('should handle payload flags', () => {
+        given('featureFlag', () => 'example_feature_payload')
+        given('matchValue', () => 'test')
+        given(
+            'render',
+            () => () =>
+                render(
+                    <PostHogProvider client={given.posthog}>
+                        <PostHogFeature flag={given.featureFlag} match={given.matchValue}>
+                            {(payload) => {
+                                return <div data-testid={`hi_${payload.name}`}>Hullo</div>
+                            }}
+                        </PostHogFeature>
+                    </PostHogProvider>
+                )
+        )
+
+        given.render()
+
+        expect(screen.queryByTestId('hi_example_feature_1_payload')).toBeInTheDocument()
+        expect(given.posthog.capture).not.toHaveBeenCalled()
+
+        fireEvent.click(screen.getByTestId('hi_example_feature_1_payload'))
+        expect(given.posthog.capture).toHaveBeenCalledTimes(1)
+    })
+})