@hanzo/insights-react 1.8.1

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

@@ -0,0 +1,291 @@
+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)
+    })
+
+    it('should not render when flag does not exist and no match is specified', () => {
+        render(
+            <PostHogProvider client={posthog}>
+                <PostHogFeature flag={'nonexistent_flag'}>
+                    <div data-testid="helloDiv">Hello</div>
+                </PostHogFeature>
+            </PostHogProvider>
+        )
+
+        expect(screen.queryByTestId('helloDiv')).not.toBeInTheDocument()
+        expect(posthog.capture).not.toHaveBeenCalled()
+    })
+
+    it('should render fallback when flag does not exist (like new-cta example)', () => {
+        render(
+            <PostHogProvider client={posthog}>
+                <PostHogFeature flag={'new-cta'} fallback={<div data-testid="oldButton">Old Button</div>}>
+                    <div data-testid="newButton">New Button</div>
+                </PostHogFeature>
+            </PostHogProvider>
+        )
+
+        expect(screen.queryByTestId('newButton')).not.toBeInTheDocument()
+        expect(screen.queryByTestId('oldButton')).toBeInTheDocument()
+        expect(posthog.capture).not.toHaveBeenCalled()
+    })
+
+    it('should render content when match=false and flag variant is false', () => {
+        render(
+            <PostHogProvider client={posthog}>
+                <PostHogFeature flag={'test_false'} match={false}>
+                    <div data-testid="disabledUI">Show when disabled</div>
+                </PostHogFeature>
+            </PostHogProvider>
+        )
+
+        expect(screen.queryByTestId('disabledUI')).toBeInTheDocument()
+    })
+})

package/src/components/index.ts

@@ -0,0 +1,7 @@
+export * from './PostHogFeature'
+export * from './PostHogCaptureOnViewed'
+export {
+    PostHogErrorBoundary,
+    PostHogErrorBoundaryProps,
+    PostHogErrorBoundaryFallbackProps,
+} from './PostHogErrorBoundary'

package/src/components/internal/VisibilityAndClickTracker.tsx

@@ -0,0 +1,49 @@
+import React, { MouseEventHandler, useEffect, useMemo, useRef, JSX } 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>
+    )
+}

package/src/components/internal/VisibilityAndClickTrackers.tsx

@@ -0,0 +1,60 @@
+import React, { Children, ReactNode, useCallback, useRef, JSX } from 'react'
+import { VisibilityAndClickTracker } from './VisibilityAndClickTracker'
+
+/**
+ * VisibilityAndClickTrackers is an internal component,
+ * its API might change without warning and without being signalled as a breaking change
+ *
+ * Wraps each of the children passed to it for visiblity and click tracking
+ *
+ */
+export function VisibilityAndClickTrackers({
+    children,
+    trackInteraction,
+    trackView,
+    options,
+    onInteract,
+    onView,
+    ...props
+}: {
+    flag: string
+    children: React.ReactNode
+    trackInteraction: boolean
+    trackView: boolean
+    options?: IntersectionObserverInit
+    onInteract?: () => void
+    onView?: () => void
+}): JSX.Element {
+    const clickTrackedRef = useRef(false)
+    const visibilityTrackedRef = useRef(false)
+
+    const cachedOnClick = useCallback(() => {
+        if (!clickTrackedRef.current && trackInteraction && onInteract) {
+            onInteract()
+            clickTrackedRef.current = true
+        }
+    }, [trackInteraction, onInteract])
+
+    const onIntersect = (entry: IntersectionObserverEntry) => {
+        if (!visibilityTrackedRef.current && entry.isIntersecting && onView) {
+            onView()
+            visibilityTrackedRef.current = true
+        }
+    }
+
+    const trackedChildren = Children.map(children, (child: ReactNode) => {
+        return (
+            <VisibilityAndClickTracker
+                onClick={cachedOnClick}
+                onIntersect={onIntersect}
+                trackView={trackView}
+                options={options}
+                {...props}
+            >
+                {child}
+            </VisibilityAndClickTracker>
+        )
+    })
+
+    return <>{trackedChildren}</>
+}

package/src/context/PostHogContext.ts

@@ -0,0 +1,9 @@
+import posthogJs, { BootstrapConfig } from '@hanzo/insights'
+import { createContext } from 'react'
+
+export type PostHog = typeof posthogJs
+
+export const PostHogContext = createContext<{ client: PostHog; bootstrap?: BootstrapConfig }>({
+    client: posthogJs,
+    bootstrap: undefined,
+})

package/src/context/PostHogProvider.tsx

@@ -0,0 +1,136 @@
+/* eslint-disable no-console */
+import posthogJs, { PostHogConfig } from '@hanzo/insights'
+
+import React, { useEffect, useMemo, useRef } from 'react'
+import { PostHog, PostHogContext } from './PostHogContext'
+import { isDeepEqual } from '../utils/object-utils'
+
+interface PreviousInitialization {
+    apiKey: string
+    options: Partial<PostHogConfig>
+}
+
+type WithOptionalChildren<T> = T & { children?: React.ReactNode | undefined }
+
+/**
+ * Props for the PostHogProvider component.
+ * This is a discriminated union type that ensures mutually exclusive props:
+ *
+ * - If `client` is provided, `apiKey` and `options` must not be provided
+ * - If `apiKey` is provided, `client` must not be provided, and `options` is optional
+ */
+type PostHogProviderProps =
+    | { client: PostHog; apiKey?: never; options?: never }
+    | { apiKey: string; options?: Partial<PostHogConfig>; client?: never }
+
+/**
+ * PostHogProvider is a React context provider for PostHog analytics.
+ * It can be initialized in two mutually exclusive ways:
+ *
+ * 1. By providing an existing PostHog `client` instance
+ * 2. By providing an `apiKey` (and optionally `options`) to create a new client
+ *
+ * These initialization methods are mutually exclusive - you must use one or the other,
+ * but not both simultaneously.
+ *
+ * We strongly suggest you memoize the `options` object to ensure that you don't
+ * accidentally trigger unnecessary re-renders. We'll properly detect if the options
+ * have changed and only call `posthogJs.set_config` if they have, but it's better to
+ * avoid unnecessary re-renders in the first place.
+ */
+export function PostHogProvider({ children, client, apiKey, options }: WithOptionalChildren<PostHogProviderProps>) {
+    // Used to detect if the client was already initialized
+    // This is used to prevent double initialization when running under React.StrictMode
+    // We're not storing a simple boolean here because we want to be able to detect if the
+    // apiKey or options have changed.
+    const previousInitializationRef = useRef<PreviousInitialization | null>(null)
+
+    const posthog = useMemo(() => {
+        if (client) {
+            if (apiKey) {
+                console.warn(
+                    '[PostHog.js] You have provided both `client` and `apiKey` to `PostHogProvider`. `apiKey` will be ignored in favour of `client`.'
+                )
+            }
+            if (options) {
+                console.warn(
+                    '[PostHog.js] You have provided both `client` and `options` to `PostHogProvider`. `options` will be ignored in favour of `client`.'
+                )
+            }
+            return client
+        }
+
+        if (apiKey) {
+            // return the global client, we'll initialize it in the useEffect
+            return posthogJs
+        }
+
+        console.warn(
+            '[PostHog.js] No `apiKey` or `client` were provided to `PostHogProvider`. Using default global `window.posthog` instance. You must initialize it manually. This is not recommended behavior.'
+        )
+        return posthogJs
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [client, apiKey, JSON.stringify(options)]) // Stringify options to be a stable reference
+
+    // TRICKY: The init needs to happen in a useEffect rather than useMemo, as useEffect does not happen during SSR. Otherwise
+    // we'd end up trying to call posthogJs.init() on the server, which can cause issues around hydration and double-init.
+    useEffect(() => {
+        if (client) {
+            // if the user has passed their own client, assume they will also handle calling init().
+            return
+        }
+        const previousInitialization = previousInitializationRef.current
+
+        if (!previousInitialization) {
+            // If it's the first time running this, but it has been loaded elsewhere, warn the user about it.
+            if (posthogJs.__loaded) {
+                console.warn('[PostHog.js] `posthog` was already loaded elsewhere. This may cause issues.')
+            }
+
+            // Init global client
+            posthogJs.init(apiKey, options)
+
+            // Keep track of whether the client was already initialized
+            // This is used to prevent double initialization when running under React.StrictMode, and to know when options change
+            previousInitializationRef.current = {
+                apiKey: apiKey,
+                options: options ?? {},
+            }
+        } else {
+            // If the client was already initialized, we might still end up running the effect again for a few reasons:
+            // * someone is developing locally under `React.StrictMode`
+            // * the config has changed
+            // * the apiKey has changed (not supported!)
+            //
+            // Changing the apiKey isn't well supported and we'll simply log a message suggesting them
+            // to take control of the `client` initialization themselves. This is tricky to handle
+            // ourselves because we wouldn't know if we should call `.reset()` or not, for example.
+            if (apiKey !== previousInitialization.apiKey) {
+                console.warn(
+                    "[PostHog.js] You have provided a different `apiKey` to `PostHogProvider` than the one that was already initialized. This is not supported by our provider and we'll keep using the previous key. If you need to toggle between API Keys you need to control the `client` yourself and pass it in as a prop rather than an `apiKey` prop."
+                )
+            }
+
+            // Changing options is better supported because we can just call `posthogJs.set_config(options)`
+            // and they'll be good to go with their new config. The SDK will know how to handle the changes.
+            if (options && !isDeepEqual(options, previousInitialization.options)) {
+                posthogJs.set_config(options)
+            }
+
+            // Keep track of the possibly-new set of apiKey and options
+            previousInitializationRef.current = {
+                apiKey: apiKey,
+                options: options ?? {},
+            }
+        }
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [client, apiKey, JSON.stringify(options)]) // Stringify options to be a stable reference
+
+    return (
+        <PostHogContext.Provider
+            value={{ client: posthog, bootstrap: options?.bootstrap ?? client?.config?.bootstrap }}
+        >
+            {children}
+        </PostHogContext.Provider>
+    )
+}

package/src/context/__tests__/PostHogContext.test.tsx

@@ -0,0 +1,35 @@
+import * as React from 'react'
+import { render } from '@testing-library/react'
+import { PostHogProvider, PostHog } from '..'
+
+describe('PostHogContext component', () => {
+    const posthog = {} as unknown as PostHog
+
+    it('should return a client instance from the context if available', () => {
+        render(
+            <PostHogProvider client={posthog}>
+                <div>Hello</div>
+            </PostHogProvider>
+        )
+    })
+
+    it("should not throw error if a client instance can't be found in the context", () => {
+        // eslint-disable-next-line no-console
+        console.warn = jest.fn()
+
+        expect(() => {
+            render(
+                // we have to cast `as any` so that we can test for when
+                // posthog might not exist - in SSR for example
+                <PostHogProvider client={undefined as any}>
+                    <div>Hello</div>
+                </PostHogProvider>
+            )
+        }).not.toThrow()
+
+        // eslint-disable-next-line no-console
+        expect(console.warn).toHaveBeenCalledWith(
+            '[PostHog.js] No `apiKey` or `client` were provided to `PostHogProvider`. Using default global `window.posthog` instance. You must initialize it manually. This is not recommended behavior.'
+        )
+    })
+})