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.

19.8 KB
Raw Blame
import clsx from 'clsx'
import { useActions, useValues } from 'kea'
import { useEffect, useMemo } from 'react'

import { LemonBanner, LemonButton } from '@posthog/lemon-ui'

import type { Sorting } from 'lib/lemon-ui/LemonTable/sorting'
import { SortingIndicator, getNextSorting } from 'lib/lemon-ui/LemonTable/sorting'
import { InsightEmptyState } from 'scenes/insights/EmptyStates'

import { HeatmapSettings, NodeKind } from '~/queries/schema/schema-general'

import { getContrastingTextClass } from '../../colorUtils'
import { dataVisualizationLogic, formatDataWithSettings } from '../../dataVisualizationLogic'
import {
    buildFallbackGradientStops,
    formatHeatmapLabel,
    formatHeatmapValue,
    getHeatmapNullLabel,
    getHeatmapNullValue,
    interpolateHeatmapColor,
    resolveGradientStops,
    stretchGradientStopsToValues,
} from './heatmapUtils'
import {
    getDistinctHeatmapLabels,
    getHeatmapSettingsWithSorting,
    getSortingFromHeatmapSettings,
    HEATMAP_ROW_LABEL_SORT_KEY,
    sortHeatmapRows,
} from './twoDimensionalHeatmapUtils'

const parseNumericValue = (value: unknown): number | null => {
    if (value === null || value === undefined || value === '') {
        return null
    }

    const numericValue = Number(value)
    if (Number.isNaN(numericValue)) {
        return null
    }

    return numericValue
}

type HeatmapData = {
    xValues: string[]
    yValues: string[]
    cellValues: Record<string, Record<string, number | null>>
    numericValues: number[]
    duplicateCellCount: number
    isTooLarge: boolean
}

const MAX_HEATMAP_CELLS = 10_000

type HeatmapDataSettings = Pick<
    HeatmapSettings,
    'xAxisColumn' | 'yAxisColumn' | 'valueColumn' | 'nullLabel' | 'nullValue'
>

const buildHeatmapData = (
    rows: any[],
    heatmapSettings: HeatmapDataSettings,
    columnIndexes: Record<string, number>,
    axisLabels?: { x: Map<unknown, string>; y: Map<unknown, string> }
): HeatmapData => {
    const xValues: string[] = []
    const yValues: string[] = []
    // Prototype-less: row labels are attacker-controlled and used as keys, so a `__proto__`
    // label on a plain object would write through to Object.prototype (prototype pollution).
    const cellValues: Record<string, Record<string, number | null>> = Object.create(null)
    const numericValues: number[] = []
    let duplicateCellCount = 0

    const xIndex = columnIndexes[heatmapSettings.xAxisColumn ?? '']
    const yIndex = columnIndexes[heatmapSettings.yAxisColumn ?? '']
    const valueIndex = columnIndexes[heatmapSettings.valueColumn ?? '']

    if (xIndex === undefined || yIndex === undefined || valueIndex === undefined) {
        return {
            xValues,
            yValues,
            cellValues,
            numericValues,
            duplicateCellCount,
            isTooLarge: false,
        }
    }

    const xIndexMap = new Map<string, number>()
    const yIndexMap = new Map<string, number>()
    const seenCells = new Set<string>()
    const nullLabel = getHeatmapNullLabel(heatmapSettings)

    rows.forEach((row) => {
        const xLabel = axisLabels?.x.get(row[xIndex]) ?? formatHeatmapLabel(row[xIndex], nullLabel)
        const yLabel = axisLabels?.y.get(row[yIndex]) ?? formatHeatmapLabel(row[yIndex], nullLabel)
        const numericValue = parseNumericValue(row[valueIndex])

        if (!xIndexMap.has(xLabel)) {
            xIndexMap.set(xLabel, xValues.length)
            xValues.push(xLabel)
        }

        if (!yIndexMap.has(yLabel)) {
            yIndexMap.set(yLabel, yValues.length)
            yValues.push(yLabel)
        }

        if (!cellValues[yLabel]) {
            cellValues[yLabel] = Object.create(null)
        }

        const cellKey = JSON.stringify([yLabel, xLabel])
        if (seenCells.has(cellKey)) {
            duplicateCellCount += 1
        }
        seenCells.add(cellKey)

        cellValues[yLabel][xLabel] = numericValue
    })

    const isTooLarge = xValues.length * yValues.length > MAX_HEATMAP_CELLS
    if (!isTooLarge) {
        yValues.forEach((yValue) => {
            Object.values(cellValues[yValue]).forEach((cellValue) => {
                if (cellValue !== null && cellValue !== undefined) {
                    numericValues.push(cellValue)
                }
            })
        })
    }

    return {
        xValues,
        yValues,
        cellValues,
        numericValues,
        duplicateCellCount,
        isTooLarge,
    }
}

const getAriaSort = (order: Sorting['order'] | null): 'ascending' | 'descending' | 'none' => {
    if (order === 1) {
        return 'ascending'
    }

    if (order === -1) {
        return 'descending'
    }

    return 'none'
}

const getNextSortingTitle = (currentSorting: Sorting | null, columnKey: string, defaultSortOrder: 1 | -1): string => {
    const nextSorting = getNextSorting(currentSorting, columnKey, false, defaultSortOrder)

    if (!nextSorting) {
        return 'Click to cancel sorting'
    }

    return `Click to sort rows ${nextSorting.order === 1 ? 'ascending' : 'descending'}`
}

export function TwoDimensionalHeatmap({
    allowSorting = true,
    onInspect,
}: {
    allowSorting?: boolean
    onInspect?: (record: Record<string, unknown>) => void
}): JSX.Element {
    const { response, columns, chartSettings, query } = useValues(dataVisualizationLogic)
    const { updateChartSettings } = useActions(dataVisualizationLogic)

    const heatmapSettings = chartSettings.heatmap ?? {}
    const { xAxisColumn, yAxisColumn, valueColumn, nullLabel, nullValue } = heatmapSettings
    const valueSettings = chartSettings.yAxis?.find((axis) => axis.column === valueColumn)?.settings
    const sorting = useMemo(
        () => getSortingFromHeatmapSettings(heatmapSettings),
        [heatmapSettings.sortColumn, heatmapSettings.sortOrder, heatmapSettings]
    )
    const selectedColumns = [xAxisColumn, yAxisColumn, valueColumn]
    const rows =
        response && 'results' in response ? response.results : response && 'result' in response ? response.result : []
    const columnIndexes = useMemo(() => {
        return columns.reduce(
            (acc, column) => {
                acc[column.name] = column.dataIndex
                return acc
            },
            {} as Record<string, number>
        )
    }, [columns])
    const axisLabels = useMemo(
        () =>
            (onInspect || query.kind === NodeKind.BIVisualizationNode) && xAxisColumn && yAxisColumn
                ? {
                      x: getDistinctHeatmapLabels(
                          rows.map((row: unknown[]) => row[columnIndexes[xAxisColumn]]),
                          getHeatmapNullLabel(heatmapSettings)
                      ),
                      y: getDistinctHeatmapLabels(
                          rows.map((row: unknown[]) => row[columnIndexes[yAxisColumn]]),
                          getHeatmapNullLabel(heatmapSettings)
                      ),
                  }
                : undefined,
        [rows, columnIndexes, xAxisColumn, yAxisColumn, heatmapSettings, onInspect, query.kind]
    )
    const sourceRowsByCell = useMemo(() => {
        const cells = new Map<string, unknown[] | null>()
        if (onInspect && xAxisColumn && yAxisColumn) {
            for (const row of rows) {
                const key = JSON.stringify([
                    axisLabels?.x.get(row[columnIndexes[xAxisColumn]]),
                    axisLabels?.y.get(row[columnIndexes[yAxisColumn]]),
                ])
                cells.set(key, cells.has(key) ? null : row)
            }
        }
        return cells
    }, [rows, columnIndexes, xAxisColumn, yAxisColumn, axisLabels, onInspect])

    const hasSelection = selectedColumns.every(Boolean)
    const hasValidColumns = selectedColumns.every((columnName) => {
        if (!columnName) {
            return false
        }
        return columnIndexes[columnName] !== undefined
    })

    const heatmapData = useMemo(() => {
        if (!hasSelection || !hasValidColumns) {
            return {
                xValues: [],
                yValues: [],
                cellValues: {},
                numericValues: [],
                duplicateCellCount: 0,
                isTooLarge: false,
            }
        }

        return buildHeatmapData(
            rows,
            { xAxisColumn, yAxisColumn, valueColumn, nullLabel, nullValue },
            columnIndexes,
            axisLabels
        )
    }, [
        rows,
        hasSelection,
        hasValidColumns,
        xAxisColumn,
        yAxisColumn,
        valueColumn,
        nullLabel,
        nullValue,
        columnIndexes,
        axisLabels,
    ])

    useEffect(() => {
        if (
            sorting &&
            sorting.columnKey !== HEATMAP_ROW_LABEL_SORT_KEY &&
            !heatmapData.xValues.includes(sorting.columnKey)
        ) {
            updateChartSettings({ heatmap: getHeatmapSettingsWithSorting(heatmapSettings, null) })
        }
    }, [heatmapData.xValues, heatmapSettings, sorting, updateChartSettings])

    const sortedYValues = useMemo(
        () => sortHeatmapRows(heatmapData.yValues, heatmapData.cellValues, sorting),
        [heatmapData.cellValues, heatmapData.yValues, sorting]
    )

    const gradientStops = resolveGradientStops(
        chartSettings.heatmap?.gradient,
        buildFallbackGradientStops(heatmapData.numericValues)
    )
    const scaledGradientStops =
        heatmapSettings.gradientScaleMode === 'relative'
            ? stretchGradientStopsToValues(gradientStops, heatmapData.numericValues)
            : gradientStops
    const xAxisLabel = heatmapSettings.xAxisLabel || heatmapSettings.xAxisColumn || 'X-axis'
    const yAxisLabel = heatmapSettings.yAxisLabel || heatmapSettings.yAxisColumn || 'Y-axis'
    const nullValueDisplay = getHeatmapNullValue(heatmapSettings)

    if (!hasSelection || !hasValidColumns) {
        return (
            <div className="flex items-center justify-center h-full">
                <InsightEmptyState
                    heading="Select columns to build a 2d heatmap"
                    detail="Choose X-axis, Y-axis, and value columns to render the heatmap."
                />
            </div>
        )
    }

    if (heatmapData.xValues.length === 0 || heatmapData.yValues.length === 0) {
        return (
            <div className="flex items-center justify-center h-full">
                <InsightEmptyState heading="No data for selected columns" detail="" />
            </div>
        )
    }

    if (heatmapData.isTooLarge) {
        return (
            <div className="flex items-center justify-center h-full">
                <InsightEmptyState
                    heading="Too many cells to display"
                    detail="Use columns with fewer unique values or reduce the query result size."
                />
            </div>
        )
    }

    return (
        <div className="flex flex-col gap-2 p-2">
            {heatmapData.duplicateCellCount > 0 && (
                <LemonBanner type="warning">
                    {`Some rows share the same X/Y combination. Only the latest value is shown for ${heatmapData.duplicateCellCount} duplicate cell${
                        heatmapData.duplicateCellCount === 1 ? '' : 's'
                    }.`}
                </LemonBanner>
            )}
            <div className="text-center text-sm font-medium">{xAxisLabel}</div>
            <div className="overflow-auto">
                <table className="min-w-full border-collapse text-xs">
                    <thead>
                        <tr>
                            <th
                                className="sticky left-0 z-10 bg-surface-primary border border-border px-2 py-1 text-left"
                                aria-sort={
                                    allowSorting
                                        ? getAriaSort(
                                              sorting?.columnKey === HEATMAP_ROW_LABEL_SORT_KEY ? sorting.order : null
                                          )
                                        : undefined
                                }
                            >
                                {allowSorting ? (
                                    <button
                                        type="button"
                                        className={clsx(
                                            'flex w-full min-w-0 items-center justify-between gap-1 text-left',
                                            sorting?.columnKey === HEATMAP_ROW_LABEL_SORT_KEY && 'font-medium'
                                        )}
                                        onClick={() =>
                                            updateChartSettings({
                                                heatmap: getHeatmapSettingsWithSorting(
                                                    heatmapSettings,
                                                    getNextSorting(sorting, HEATMAP_ROW_LABEL_SORT_KEY, false, 1)
                                                ),
                                            })
                                        }
                                        title={getNextSortingTitle(sorting, HEATMAP_ROW_LABEL_SORT_KEY, 1)}
                                    >
                                        <span className="truncate">{yAxisLabel}</span>
                                        <SortingIndicator
                                            order={
                                                sorting?.columnKey === HEATMAP_ROW_LABEL_SORT_KEY ? sorting.order : null
                                            }
                                        />
                                    </button>
                                ) : (
                                    yAxisLabel
                                )}
                            </th>
                            {heatmapData.xValues.map((xValue, index) => (
                                <th
                                    key={`${xValue}-${index}`}
                                    className="border border-border px-2 py-1 text-left"
                                    aria-sort={
                                        allowSorting
                                            ? getAriaSort(sorting?.columnKey === xValue ? sorting.order : null)
                                            : undefined
                                    }
                                >
                                    {allowSorting ? (
                                        <button
                                            type="button"
                                            className={clsx(
                                                'flex w-full min-w-0 items-center justify-between gap-1 text-left',
                                                sorting?.columnKey === xValue && 'font-medium'
                                            )}
                                            onClick={() =>
                                                updateChartSettings({
                                                    heatmap: getHeatmapSettingsWithSorting(
                                                        heatmapSettings,
                                                        getNextSorting(sorting, xValue, false, -1)
                                                    ),
                                                })
                                            }
                                            title={getNextSortingTitle(sorting, xValue, -1)}
                                        >
                                            <span className="truncate">{xValue}</span>
                                            <SortingIndicator
                                                order={sorting?.columnKey === xValue ? sorting.order : null}
                                            />
                                        </button>
                                    ) : (
                                        xValue
                                    )}
                                </th>
                            ))}
                        </tr>
                    </thead>
                    <tbody>
                        {sortedYValues.map((yValue) => (
                            <tr key={yValue}>
                                <th className="sticky left-0 z-10 bg-surface-primary border border-border px-2 py-1 text-left">
                                    {yValue}
                                </th>
                                {heatmapData.xValues.map((xValue) => {
                                    const cellValue = heatmapData.cellValues[yValue]?.[xValue] ?? null
                                    const cellColor =
                                        cellValue === null
                                            ? 'transparent'
                                            : interpolateHeatmapColor(cellValue, scaledGradientStops)
                                    const formattedValue =
                                        typeof cellValue === 'number' && valueSettings
                                            ? String(
                                                  formatDataWithSettings(
                                                      cellValue *
                                                          (valueSettings.formatting?.style === 'percent' ? 100 : 1),
                                                      valueSettings
                                                  )
                                              )
                                            : formatHeatmapValue(cellValue, nullValueDisplay)
                                    const sourceRow = sourceRowsByCell.get(JSON.stringify([xValue, yValue]))

                                    return (
                                        <td
                                            key={`${yValue}-${xValue}`}
                                            className={clsx(
                                                'border border-border px-2 py-1 text-center',
                                                cellValue !== null && getContrastingTextClass(cellColor)
                                            )}
                                            style={{ backgroundColor: cellColor }}
                                        >
                                            {onInspect && sourceRow ? (
                                                <LemonButton
                                                    type="tertiary"
                                                    size="xsmall"
                                                    className="w-full justify-center !text-inherit"
                                                    tooltip="Explore this result"
                                                    onClick={() =>
                                                        onInspect(
                                                            Object.fromEntries(
                                                                columns.map((column) => [
                                                                    column.name,
                                                                    sourceRow[column.dataIndex],
                                                                ])
                                                            )
                                                        )
                                                    }
                                                >
                                                    {formattedValue}
                                                </LemonButton>
                                            ) : (
                                                formattedValue
                                            )}
                                        </td>
                                    )
                                })}
                            </tr>
                        ))}
                    </tbody>
                </table>
            </div>
        </div>
    )
}