Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

4.7 KB
Raw Blame
import React, { useMemo } from 'react'

import { computeVisibleXLabels, useChartLayout } from '@posthog/quill-charts'

import { AnnotationsOverlay, type AnnotationsOverlayProps } from './AnnotationsOverlay'
import type { AnnotationsChartGeometry } from './useAnnotationsPositioning'

interface AnnotationsLayerProps {
    /** Numeric insight id used by the annotations logic. Pass `'new'` for unsaved insights. */
    insightNumericId: number | 'new'
    /** Per-data-point date strings; used for grouping annotations. */
    dates: string[]
    /** Series key whose bar should anchor annotations in compare-against-previous grouped
     *  bar layouts. Without it, annotations land on the band center (between current
     *  and previous bars) instead of the current-period bar. */
    seriesKey?: string
    /** Per-data-point date strings for the previous period in compare-against-previous
     *  layouts. When provided alongside `previousSeriesKey`, a second overlay renders
     *  previous-period annotations anchored on the previous-period bar. */
    previousDates?: string[]
    /** Series key for the previous-period bar. Required for previous-period annotations
     *  to anchor on the correct bar within each band. */
    previousSeriesKey?: string
    annotationsScope?: AnnotationsOverlayProps['annotationsScope']
}

const WRAPPER_STYLE: React.CSSProperties = {
    // Re-enable pointer-events here because the chart's overlay layer disables them
    // for non-interactive overlays (axis labels, crosshair, reference lines).
    pointerEvents: 'auto',
}

// Annotation badges must not drive the chart's crosshair or onPointClick.
const stopPointerPropagation = (e: React.MouseEvent<HTMLDivElement>): void => {
    e.stopPropagation()
}

export function AnnotationsLayer({
    insightNumericId,
    dates,
    seriesKey,
    previousDates,
    previousSeriesKey,
    annotationsScope,
}: AnnotationsLayerProps): React.ReactElement | null {
    const { scales, dimensions, labels, axis } = useChartLayout()
    const xTickFormatter = axis.xTickFormatter

    const currentGeometry = useMemo<AnnotationsChartGeometry>(() => {
        const visibleXLabels = computeVisibleXLabels(labels, scales.x, xTickFormatter)
        return {
            xTicks: visibleXLabels.map((v) => ({ value: v.index })),
            pointsX: labels.map((label) => scales.x(label, seriesKey) ?? 0),
            plotLeft: dimensions.plotLeft,
            plotBottom: dimensions.plotTop + dimensions.plotHeight,
        }
        // eslint-disable-next-line react-hooks/exhaustive-deps -- only `scales.x` is read; `scales` itself is unused.
    }, [labels, scales.x, seriesKey, dimensions.plotLeft, dimensions.plotTop, dimensions.plotHeight, xTickFormatter])

    const previousGeometry = useMemo<AnnotationsChartGeometry | null>(() => {
        if (!previousDates || !previousSeriesKey) {
            return null
        }
        const visibleXLabels = computeVisibleXLabels(labels, scales.x, xTickFormatter)
        return {
            xTicks: visibleXLabels.map((v) => ({ value: v.index })),
            // Anchor on the previous-period bar (left bar in each band) but reuse the current
            // labels — only the x positions matter, not the labels themselves.
            pointsX: labels.map((label) => scales.x(label, previousSeriesKey) ?? 0),
            plotLeft: dimensions.plotLeft,
            plotBottom: dimensions.plotTop + dimensions.plotHeight,
        }
        // eslint-disable-next-line react-hooks/exhaustive-deps -- only `scales.x` is read; `scales` itself is unused.
    }, [
        labels,
        scales.x,
        previousSeriesKey,
        previousDates,
        dimensions.plotLeft,
        dimensions.plotTop,
        dimensions.plotHeight,
        xTickFormatter,
    ])

    if (currentGeometry.xTicks.length < 2) {
        return null
    }

    return (
        <div
            className="HogChartsAnnotationsLayer"
            style={WRAPPER_STYLE}
            onClick={stopPointerPropagation}
            onMouseMove={stopPointerPropagation}
            onMouseDown={stopPointerPropagation}
        >
            <AnnotationsOverlay
                geometry={currentGeometry}
                dates={dates}
                chartWidth={dimensions.width}
                insightNumericId={insightNumericId}
                annotationsScope={annotationsScope}
            />
            {previousGeometry && previousDates && (
                <AnnotationsOverlay
                    geometry={previousGeometry}
                    dates={previousDates}
                    chartWidth={dimensions.width}
                    insightNumericId={insightNumericId}
                    kind="previous"
                    annotationsScope={annotationsScope}
                />
            )}
        </div>
    )
}