@hanzo/insights-react 1.8.1

package/src/hooks/useFeatureFlagVariantKey.ts

@@ -0,0 +1,22 @@
+import { useContext, useEffect, useState } from 'react'
+import { PostHogContext } from '../context'
+
+export function useFeatureFlagVariantKey(flag: string): string | boolean | undefined {
+    const { client, bootstrap } = useContext(PostHogContext)
+
+    const [featureFlagVariantKey, setFeatureFlagVariantKey] = useState<string | boolean | undefined>(() =>
+        client.getFeatureFlag(flag)
+    )
+
+    useEffect(() => {
+        return client.onFeatureFlags(() => {
+            setFeatureFlagVariantKey(client.getFeatureFlag(flag))
+        })
+    }, [client, flag])
+
+    if (!client?.featureFlags?.hasLoadedFlags && bootstrap?.featureFlags) {
+        return bootstrap.featureFlags[flag]
+    }
+
+    return featureFlagVariantKey
+}

package/src/hooks/usePostHog.ts

@@ -0,0 +1,7 @@
+import { useContext } from 'react'
+import { PostHog, PostHogContext } from '../context'
+
+export const usePostHog = (): PostHog => {
+    const { client } = useContext(PostHogContext)
+    return client
+}

package/src/hooks/useThumbSurvey.ts

@@ -0,0 +1,146 @@
+import { useState, useCallback, useRef, useMemo, type RefCallback, useEffect } from 'react'
+import { usePostHog } from './usePostHog'
+import { DisplaySurveyType, SurveyEventName, SurveyEventProperties, SurveyPosition } from '@hanzo/insights'
+
+export interface UseThumbSurveyOptions {
+    /** ID of the target PostHog survey */
+    surveyId: string
+    /** Configure the position of the pop-up for followup questions, if applicable. Defaults to SurveyPosition.NextToTrigger */
+    displayPosition?: SurveyPosition
+    /** Custom event properties to pass with each survey result */
+    properties?: Record<string, any>
+    /** Callback on thumb button click */
+    onResponse?: (response: 'up' | 'down') => void
+    /** Disable automatically emitting `survey shown` on hook mount. Defaults to false. */
+    disableAutoShownTracking?: boolean
+}
+
+export interface UseThumbSurveyResult {
+    /** Call this to submit a survey response, with value 'up' or 'down' */
+    respond: (value: 'up' | 'down') => void
+    /** User's response value, available after submission */
+    response: 'up' | 'down' | null
+    /** Ref to attach to the trigger element for positioning the followup survey popup */
+    triggerRef: RefCallback<HTMLElement>
+    /** Method to manually trigger a `survey shown` event. Only available when disableAutoShownTracking is true. */
+    trackShown?: () => void
+}
+
+const TRIGGER_ATTR = 'data-ph-thumb-survey-trigger'
+
+/**
+ * Convenience hook for managing a "thumb" (1-2 rating scale) survey.
+ *
+ * Pre-requisites:
+ * 1) Ensure surveys are not disabled in your PostHog config (`disable_surveys: false`)
+ * 2) Ensure surveys are enabled in your PostHog project (Settings > Surveys > Enable surveys)
+ *
+ * How-to:
+ * 1) Create an API survey in PostHog (New survey > Presentation > API)
+ * 2) Set the first question to a thumb rating scale (Question type: Rating -> Display type: Emoji -> Scale: 1-2 (thumbs up/down))
+ * 3) Set the thumb question to "Automatically submit on selection"
+ * 4) Optionally add follow-up questions
+ * 5) Use the hook:
+ *
+ * ```typescript
+ * const { respond, response, triggerRef } = useThumbSurvey({
+ *  surveyId: 'my-survey-id',
+ *  properties: { foo: 'bar' }, // optional custom properties to pass along with the survey responses
+ *  onResponse: (response) => { console.log(response) }, // optional callback on submission
+ * })
+ *
+ * return (
+ *  <div ref={triggerRef}>
+ *      <button onClick={() => respond('up')} style={{ color: response === 'up' ? 'green' : undefined }}>👍</button>
+ *      <button onClick={() => respond('down')} style={{ color: response === 'down' ? 'red' : undefined }}>👎</button>
+ *  </div>
+ * )
+ * ```
+ *
+ * 6) If your survey has further questions, the survey will automatically display as a popover, either:
+ *  - [default] next to the triggerRef element,
+ *  - OR wherever you specify in options.position
+ *
+ * Notes:
+ * - The thumbs up/down response will ALWAYS be recorded, whether your survey is set to collect partial responses or not.
+ * - By default, followup questions will be displayed as a pop-up next to the triggerRef. Use options.position to change the position.
+ * - By default, `survey shown` is emitted automatically on hook mount. To prevent this behavior, set `disableAutoShownTracking: true`,
+ *   and manually call `trackShown()` when you want to emit this event.
+ *
+ * @param options UseThumbSurveyOptions
+ * @returns UseThumbSurveyResult
+ */
+export function useThumbSurvey({
+    surveyId,
+    displayPosition = SurveyPosition.NextToTrigger,
+    properties,
+    onResponse,
+    disableAutoShownTracking,
+}: UseThumbSurveyOptions): UseThumbSurveyResult {
+    const posthog = usePostHog()
+    const [responded, setResponded] = useState<'up' | 'down' | null>(null)
+    const [instanceId] = useState(() => Math.random().toString(36).slice(2, 9))
+    const triggerValue = useMemo(() => `${surveyId}-${instanceId}`, [surveyId, instanceId])
+
+    const elementRef = useRef<HTMLElement | null>(null)
+    const triggerRef = useCallback(
+        (el: HTMLElement | null) => {
+            if (elementRef.current) {
+                elementRef.current.removeAttribute(TRIGGER_ATTR)
+            }
+            elementRef.current = el
+            if (el) {
+                el.setAttribute(TRIGGER_ATTR, triggerValue)
+            }
+        },
+        [triggerValue]
+    )
+
+    const shownRef = useRef(false)
+    const respondedRef = useRef(false)
+
+    const trackShown = useCallback(() => {
+        if (shownRef.current || !posthog) return
+        shownRef.current = true
+        posthog.capture(SurveyEventName.SHOWN, {
+            [SurveyEventProperties.SURVEY_ID]: surveyId,
+            sessionRecordingUrl: posthog.get_session_replay_url?.(),
+            ...properties,
+        })
+    }, [posthog, surveyId, properties])
+
+    useEffect(() => {
+        if (!disableAutoShownTracking) {
+            trackShown()
+        }
+    }, [trackShown, disableAutoShownTracking])
+
+    const respond = useCallback(
+        (value: 'up' | 'down') => {
+            if (!posthog?.surveys || respondedRef.current) return
+            respondedRef.current = true
+
+            setResponded(value)
+            onResponse?.(value)
+
+            posthog.surveys.displaySurvey(surveyId, {
+                displayType: DisplaySurveyType.Popover,
+                ignoreConditions: true,
+                ignoreDelay: true,
+                properties,
+                initialResponses: { 0: value === 'up' ? 1 : 2 },
+                position: displayPosition,
+                selector: `[${TRIGGER_ATTR}="${triggerValue}"]`,
+                skipShownEvent: true,
+            })
+        },
+        [posthog, surveyId, displayPosition, properties, onResponse, triggerValue]
+    )
+
+    return {
+        respond,
+        response: responded,
+        triggerRef,
+        ...(disableAutoShownTracking && { trackShown }),
+    }
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from './context'
+export * from './hooks'
+export * from './components'
+export * from './helpers'

package/src/surveys/index.ts

@@ -0,0 +1 @@
+export * from '../hooks/useThumbSurvey'

package/src/utils/__tests__/object-utils.test.ts

@@ -0,0 +1,42 @@
+import { isDeepEqual } from '../object-utils'
+
+const circularArray1: any[] = []
+circularArray1.push(circularArray1)
+const circularArray2: any[] = []
+circularArray2.push(circularArray2)
+
+function f1() {}
+function f2() {}
+
+describe('object-utils', () => {
+    describe('isDeepEqual', () => {
+        it.each([
+            [true, { a: 1, b: 2 }, { a: 1, b: 2 }],
+            [true, { a: 1, b: { c: 2 } }, { a: 1, b: { c: 2 } }],
+            [false, { a: 1, b: 2 }, { a: 1, b: 3 }],
+            [false, { a: 1, b: 2 }, { a: 1 }],
+            [true, 'a', 'a'],
+            [false, 'a', 'b'],
+            [false, 1, 2],
+            [true, 0, -0],
+            [false, Number.POSITIVE_INFINITY, Number.NEGATIVE_INFINITY],
+            [false, 1, '1'],
+            [false, Number.NaN, Number.NaN],
+            [true, null, null],
+            [false, undefined, null],
+            [true, [], []],
+            [true, [[[[]]]], [[[[]]]]],
+            [false, [[[[]]]], [[[[[]]]]]],
+            [true, [1, 2, 3], [1, 2, 3]],
+            [false, [1, 2, 3], [1, 2, 4]],
+            [true, { a: circularArray1 }, { a: circularArray1 }],
+            [true, { a: circularArray1 }, { a: circularArray2 }],
+            [true, circularArray1, [circularArray1]],
+            [true, f1, f1],
+            [false, f1, f2],
+        ])('returns %s for %s and %s', (expected, obj1, obj2) => {
+            expect(isDeepEqual(obj1, obj2)).toBe(expected)
+            expect(isDeepEqual(obj2, obj1)).toBe(expected)
+        })
+    })
+})

package/src/utils/object-utils.ts

@@ -0,0 +1,36 @@
+// Deeply compares two objects for equality.
+// Use a WeakMap to keep track of visited objects to avoid infinite recursion.
+// WeakMap is supported in IE11, see https://caniuse.com/?search=JavaScript%20WeakMap
+
+export function isDeepEqual(obj1: any, obj2: any, visited = new WeakMap()): boolean {
+    if (obj1 === obj2) {
+        return true
+    }
+
+    if (typeof obj1 !== 'object' || obj1 === null || typeof obj2 !== 'object' || obj2 === null) {
+        return false
+    }
+
+    if (visited.has(obj1) && visited.get(obj1) === obj2) {
+        return true
+    }
+    visited.set(obj1, obj2)
+
+    const keys1 = Object.keys(obj1)
+    const keys2 = Object.keys(obj2)
+
+    if (keys1.length !== keys2.length) {
+        return false
+    }
+
+    for (const key of keys1) {
+        if (!keys2.includes(key)) {
+            return false
+        }
+        if (!isDeepEqual(obj1[key], obj2[key], visited)) {
+            return false
+        }
+    }
+
+    return true
+}

package/src/utils/type-utils.ts

@@ -0,0 +1,16 @@
+// from a comment on http://dbj.org/dbj/?p=286
+// fails on only one very rare and deliberate custom object:
+// let bomb = { toString : undefined, valueOf: function(o) { return "function BOMBA!"; }};
+export const isFunction = function (f: any): f is (...args: any[]) => any {
+    // eslint-disable-next-line posthog-js/no-direct-function-check
+    return typeof f === 'function'
+}
+
+export const isUndefined = function (x: unknown): x is undefined {
+    return x === void 0
+}
+
+export const isNull = function (x: unknown): x is null {
+    // eslint-disable-next-line posthog-js/no-direct-null-check
+    return x === null
+}

package/surveys/package.json

@@ -0,0 +1,7 @@
+{
+    "name": "@posthog/react-surveys",
+    "private": true,
+    "main": "../dist/umd/surveys/index.js",
+    "module": "../dist/esm/surveys/index.js",
+    "types": "../dist/types/surveys/index.d.ts"
+}