feat: product tours

Author: adboio

packages/browser/src/entrypoints/main.cjs.ts

@@ -3,5 +3,6 @@ import { init_as_module } from '../posthog-core'
 export { PostHog } from '../posthog-core'
 export * from '../types'
 export * from '../posthog-surveys-types'
+export * from '../posthog-product-tours-types'
 export const posthog = init_as_module()
 export default posthog

packages/browser/src/entrypoints/module.no-external.es.ts

@@ -2,5 +2,6 @@ import { init_as_module } from '../posthog-core'
 export { PostHog } from '../posthog-core'
 export * from '../types'
 export * from '../posthog-surveys-types'
+export * from '../posthog-product-tours-types'
 export const posthog = init_as_module()
 export default posthog

packages/browser/src/extensions/product-tours/components/ProductTourTooltip.tsx

@@ -0,0 +1,360 @@
+/**
+ * Product Tour Tooltip Component
+ *
+ * Preact component that renders the tooltip and overlay for product tours.
+ * Handles smooth transitions between steps with proper scroll detection.
+ */
+
+import { h } from 'preact'
+import { useEffect, useState, useCallback, useRef } from 'preact/hooks'
+import { ProductTour, ProductTourStep, ProductTourDismissReason } from '../../../posthog-product-tours-types'
+import {
+    calculateTooltipPosition,
+    getSpotlightStyle,
+    mergeAppearance,
+    renderTipTapContent,
+    TooltipPosition,
+} from '../product-tours-utils'
+import { addEventListener } from '../../../utils'
+import { window as _window } from '../../../utils/globals'
+import { IconPosthogLogo, cancelSVG } from '../../surveys/icons'
+
+const window = _window as Window & typeof globalThis
+
+type TransitionState = 'initializing' | 'entering' | 'visible' | 'exiting'
+
+export interface ProductTourTooltipProps {
+    tour: ProductTour
+    step: ProductTourStep
+    stepIndex: number
+    totalSteps: number
+    targetElement: HTMLElement
+    onNext: () => void
+    onPrevious: () => void
+    onDismiss: (reason: ProductTourDismissReason) => void
+}
+
+function getOppositePosition(position: TooltipPosition): TooltipPosition {
+    const opposites: Record<TooltipPosition, TooltipPosition> = {
+        top: 'bottom',
+        bottom: 'top',
+        left: 'right',
+        right: 'left',
+    }
+    return opposites[position]
+}
+
+/**
+ * Scroll element into view and return a promise that resolves when scrolling is complete
+ */
+function scrollToElement(element: HTMLElement): Promise<void> {
+    return new Promise((resolve) => {
+        // Get initial position
+        const initialRect = element.getBoundingClientRect()
+        const viewportHeight = window.innerHeight
+        const viewportWidth = window.innerWidth
+
+        // Define "safe zone" - center 2/3 of viewport
+        // This ensures there's room for the tooltip around the element
+        const safeMarginY = viewportHeight / 6 // ~16.7% margin top and bottom
+        const safeMarginX = viewportWidth / 6
+
+        const isInSafeZone =
+            initialRect.top >= safeMarginY &&
+            initialRect.bottom <= viewportHeight - safeMarginY &&
+            initialRect.left >= safeMarginX &&
+            initialRect.right <= viewportWidth - safeMarginX
+
+        // If already in safe zone, resolve immediately
+        if (isInSafeZone) {
+            resolve()
+            return
+        }
+
+        // Start scrolling
+        element.scrollIntoView({ behavior: 'smooth', block: 'center' })
+
+        // Poll for position stability - works regardless of scrollend support
+        let lastTop = initialRect.top
+        let stableCount = 0
+        let resolved = false
+
+        const checkStability = () => {
+            if (resolved) return
+
+            const currentRect = element.getBoundingClientRect()
+            if (Math.abs(currentRect.top - lastTop) < 1) {
+                stableCount++
+                if (stableCount >= 3) {
+                    resolved = true
+                    resolve()
+                    return
+                }
+            } else {
+                stableCount = 0
+            }
+            lastTop = currentRect.top
+            setTimeout(checkStability, 50)
+        }
+
+        // Start checking after a brief delay to let scroll begin
+        setTimeout(checkStability, 30)
+
+        // Fallback timeout (shorter since polling should catch most cases)
+        setTimeout(() => {
+            if (!resolved) {
+                resolved = true
+                resolve()
+            }
+        }, 500)
+    })
+}
+
+export function ProductTourTooltip({
+    tour,
+    step,
+    stepIndex,
+    totalSteps,
+    targetElement,
+    onNext,
+    onPrevious,
+    onDismiss,
+}: ProductTourTooltipProps): h.JSX.Element {
+    const appearance = mergeAppearance(tour.appearance)
+    const [transitionState, setTransitionState] = useState<TransitionState>('initializing')
+    const [position, setPosition] = useState<ReturnType<typeof calculateTooltipPosition> | null>(null)
+    const [spotlightStyle, setSpotlightStyle] = useState<ReturnType<typeof getSpotlightStyle> | null>(null)
+
+    // Store displayed content separately so it doesn't change during transitions
+    const [displayedStep, setDisplayedStep] = useState(step)
+    const [displayedStepIndex, setDisplayedStepIndex] = useState(stepIndex)
+
+    const previousStepRef = useRef(stepIndex)
+    const isTransitioningRef = useRef(false)
+    const isFirstRender = useRef(true)
+
+    const updatePosition = useCallback(() => {
+        const rect = targetElement.getBoundingClientRect()
+        setPosition(calculateTooltipPosition(rect))
+        setSpotlightStyle(getSpotlightStyle(rect))
+    }, [targetElement])
+
+    // Handle initial mount and step changes
+    useEffect(() => {
+        const isStepChange = previousStepRef.current !== stepIndex
+
+        // Capture the current stepIndex to check if it's still valid when async operations complete
+        const currentStepIndex = stepIndex
+
+        // On first render, scroll first then show
+        if (isFirstRender.current) {
+            isFirstRender.current = false
+            previousStepRef.current = stepIndex
+            isTransitioningRef.current = true
+
+            scrollToElement(targetElement).then(() => {
+                // Check if step changed during scroll (user clicked rapidly)
+                if (previousStepRef.current !== currentStepIndex) {
+                    return // Abort - a newer transition will handle this
+                }
+
+                // Now that scroll is complete, calculate position and show
+                const rect = targetElement.getBoundingClientRect()
+                setPosition(calculateTooltipPosition(rect))
+                setSpotlightStyle(getSpotlightStyle(rect))
+                setTransitionState('visible')
+                isTransitioningRef.current = false
+            })
+            return
+        }
+
+        // On step change, do exit -> scroll -> enter
+        if (isStepChange) {
+            previousStepRef.current = stepIndex
+            isTransitioningRef.current = true
+
+            // Exit animation first
+            setTransitionState('exiting')
+
+            // Wait for exit animation, then update content and scroll
+            setTimeout(() => {
+                // Check if step changed during exit animation (user clicked rapidly)
+                if (previousStepRef.current !== currentStepIndex) {
+                    return // Abort - a newer transition will handle this
+                }
+
+                // Now update the displayed content
+                setDisplayedStep(step)
+                setDisplayedStepIndex(stepIndex)
+                setTransitionState('entering')
+
+                scrollToElement(targetElement).then(() => {
+                    // Check again after scroll completes
+                    if (previousStepRef.current !== currentStepIndex) {
+                        return // Abort - a newer transition will handle this
+                    }
+
+                    updatePosition()
+                    setTimeout(() => {
+                        // Final check before showing
+                        if (previousStepRef.current !== currentStepIndex) {
+                            return
+                        }
+                        setTransitionState('visible')
+                        isTransitioningRef.current = false
+                    }, 50)
+                })
+            }, 150) // Match the exit animation duration
+        }
+    }, [targetElement, stepIndex, step, updatePosition])
+
+    // Handle scroll and resize (only when visible, not during transitions)
+    useEffect(() => {
+        if (transitionState !== 'visible') {
+            return
+        }
+
+        const handleUpdate = () => {
+            if (!isTransitioningRef.current) {
+                updatePosition()
+            }
+        }
+
+        addEventListener(window, 'scroll', handleUpdate as EventListener, { capture: true })
+        addEventListener(window, 'resize', handleUpdate as EventListener)
+
+        return () => {
+            window?.removeEventListener('scroll', handleUpdate, true)
+            window?.removeEventListener('resize', handleUpdate)
+        }
+    }, [updatePosition, transitionState])
+
+    // Handle escape key
+    useEffect(() => {
+        const handleKeyDown = (e: KeyboardEvent) => {
+            if (e.key === 'Escape') {
+                onDismiss('escape_key')
+            }
+        }
+        addEventListener(window, 'keydown', handleKeyDown as EventListener)
+        return () => {
+            window?.removeEventListener('keydown', handleKeyDown)
+        }
+    }, [onDismiss])
+
+    const handleOverlayClick = (e: MouseEvent) => {
+        e.stopPropagation()
+        onDismiss('user_clicked_outside')
+    }
+
+    const handleTooltipClick = (e: MouseEvent) => {
+        e.stopPropagation()
+    }
+
+    const isLastStep = displayedStepIndex >= totalSteps - 1
+    const isFirstStep = displayedStepIndex === 0
+
+    const containerStyle = {
+        '--ph-tour-background-color': appearance.backgroundColor,
+        '--ph-tour-text-color': appearance.textColor,
+        '--ph-tour-button-color': appearance.buttonColor,
+        '--ph-tour-button-text-color': appearance.buttonTextColor,
+        '--ph-tour-border-radius': `${appearance.borderRadius}px`,
+        '--ph-tour-border-color': appearance.borderColor,
+    } as h.JSX.CSSProperties
+
+    // During 'initializing', render nothing (wait for scroll to complete)
+    // During 'visible', show everything
+    // During 'entering'/'exiting', show dimming but hide spotlight and tooltip
+    const isReady = transitionState !== 'initializing' && position && spotlightStyle
+    const isVisible = transitionState === 'visible'
+
+    // During initialization, just show the dimming overlay
+    if (!isReady) {
+        return (
+            <div class="ph-tour-container" style={containerStyle}>
+                <div class="ph-tour-click-overlay" onClick={handleOverlayClick} />
+                <div class="ph-tour-spotlight" style={{ top: '50%', left: '50%', width: '0px', height: '0px' }} />
+            </div>
+        )
+    }
+
+    return (
+        <div class="ph-tour-container" style={containerStyle}>
+            {/* Click overlay - always present for dismissing */}
+            <div class="ph-tour-click-overlay" onClick={handleOverlayClick} />
+
+            {/* Spotlight with box-shadow dimming - shrinks to zero during transitions */}
+            <div
+                class="ph-tour-spotlight"
+                style={isVisible ? spotlightStyle : {
+                    top: '50%',
+                    left: '50%',
+                    width: '0px',
+                    height: '0px',
+                }}
+            />
+
+            {/* Tooltip */}
+            <div
+                class={`ph-tour-tooltip ${isVisible ? 'ph-tour-tooltip--visible' : 'ph-tour-tooltip--hidden'}`}
+                style={{
+                    top: `${position.top}px`,
+                    left: `${position.left}px`,
+                    opacity: isVisible ? 1 : 0,
+                    transform: isVisible ? 'translateY(0)' : 'translateY(10px)',
+                    transition: 'opacity 0.15s ease-out, transform 0.15s ease-out',
+                }}
+                onClick={handleTooltipClick}
+            >
+                {/* Arrow */}
+                <div class={`ph-tour-arrow ph-tour-arrow--${getOppositePosition(position.position)}`} />
+
+                {/* Dismiss button - positioned in header area */}
+                <button
+                    class="ph-tour-dismiss"
+                    onClick={() => onDismiss('user_clicked_skip')}
+                    aria-label="Close tour"
+                >
+                    {cancelSVG}
+                </button>
+
+                {/* Content - uses displayedStep to prevent flash */}
+                <div
+                    class="ph-tour-content"
+                    dangerouslySetInnerHTML={{ __html: renderTipTapContent(displayedStep.content) }}
+                />
+
+                {/* Footer */}
+                <div class="ph-tour-footer">
+                    <span class="ph-tour-progress">
+                        {displayedStepIndex + 1} of {totalSteps}
+                    </span>
+
+                    <div class="ph-tour-buttons">
+                        {!isFirstStep && (
+                            <button class="ph-tour-button ph-tour-button--secondary" onClick={onPrevious}>
+                                Back
+                            </button>
+                        )}
+                        <button class="ph-tour-button ph-tour-button--primary" onClick={onNext}>
+                            {isLastStep ? 'Done' : 'Next'}
+                        </button>
+                    </div>
+                </div>
+
+                {/* Branding - matches surveys style */}
+                {!appearance.whiteLabel && (
+                    <a
+                        href="https://posthog.com/product-tours"
+                        target="_blank"
+                        rel="noopener noreferrer"
+                        class="ph-tour-branding"
+                    >
+                        Tour by {IconPosthogLogo}
+                    </a>
+                )}
+            </div>
+        </div>
+    )
+}

packages/browser/src/extensions/product-tours/index.ts

@@ -0,0 +1,14 @@
+/**
+ * Product Tours Extension
+ *
+ * Exports the ProductTourManager for use by the PostHog instance.
+ */
+
+export { ProductTourManager } from './product-tours'
+export {
+    checkTourConditions,
+    findElementBySelector,
+    getElementMetadata,
+    getProductTourStylesheet,
+    PRODUCT_TOUR_IN_PROGRESS_KEY,
+} from './product-tours-utils'