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.3 KB
Raw Blame
import { pluralize } from 'lib/utils/strings'

import type { RowShiftApi, ShiftBandApi } from '../generated/api.schemas'

/** How far the rows moved, the larger side when inserts and deletes cancel out. Zero when the pair aligned with no shift. */
export function shiftedRows(rowShift: RowShiftApi | null | undefined): number {
    return rowShift ? Math.max(rowShift.inserted_rows, rowShift.deleted_rows) : 0
}

/**
 * Only name a position when one band holds every moved row. Bands draw a
 * replaced region as one change, but the row counts keep the strict pairing,
 * so a single band can hold fewer rows than the counts and cannot locate them.
 */
function shiftPosition(rowShift: RowShiftApi): string {
    if (rowShift.bands.length !== 1) {
        return ''
    }
    const band = rowShift.bands[0]
    if (band.rows !== rowShift.inserted_rows + rowShift.deleted_rows) {
        return ''
    }
    return ` at y=${band.y}`
}

function formatResidual(value: number): string {
    if (value === 0) {
        return '0%'
    }
    return value < 0.01 ? `${value.toFixed(3)}%` : `${value.toFixed(2)}%`
}

/**
 * The movement in pixels, the same number the classifier judged. Signed when
 * the page only grew or only shrank; unsigned when rows moved both ways,
 * because the net height change would understate how far they moved.
 */
function signedShiftPx(rowShift: RowShiftApi): string {
    const px = `${shiftedRows(rowShift)}px`
    if (rowShift.deleted_rows === 0) {
        return `+${px}`
    }
    if (rowShift.inserted_rows === 0) {
        return `-${px}`
    }
    return px
}

function absorbedTooltip(rowShift: RowShiftApi): string {
    const where = shiftPosition(rowShift)
    let opening: string
    if (rowShift.deleted_rows === 0) {
        opening = `The page grew by ${pluralize(rowShift.inserted_rows, 'row')}${where}.`
    } else if (rowShift.inserted_rows === 0) {
        opening = `The page shrank by ${pluralize(rowShift.deleted_rows, 'row')}${where}.`
    } else {
        opening = `The page shifted by ${pluralize(shiftedRows(rowShift), 'row')}${where}.`
    }
    return (
        `${opening} Rows below it moved, and after aligning them only ${formatResidual(rowShift.residual_percentage)} ` +
        `of pixels differ, so this run was absorbed as noise. Without alignment it would have read as ` +
        `${rowShift.raw_diff_percentage.toFixed(2)}% pixel diff.`
    )
}

function layoutTooltip(rowShift: RowShiftApi): string {
    const parts: string[] = []
    if (rowShift.inserted_rows > 0) {
        parts.push(`${pluralize(rowShift.inserted_rows, 'row')} added`)
    }
    if (rowShift.deleted_rows > 0) {
        parts.push(`${pluralize(rowShift.deleted_rows, 'row')} removed`)
    }
    return (
        `${parts.join(' and ')}${shiftPosition(rowShift)}. Content in the matched rows changed by ` +
        `${formatResidual(rowShift.residual_percentage)} (residual).`
    )
}

export interface ShiftDescription {
    /** `neutral` for an absorbed shift, which needs no review; `warning` for a layout change. */
    tone: 'neutral' | 'warning'
    label: string
    compactLabel: string
    tooltip: string
}

/**
 * The one description both the badge and its predicate render from, so the
 * two cannot disagree about whether a snapshot has a shift worth showing.
 *
 * Chips speak pixels because that is the size of the move a person sees;
 * tooltips and the sidebar speak rows with positions, which is what somebody
 * chasing the cause needs. Returns null when nothing moved.
 */
export function describeShift(rowShift: RowShiftApi | null | undefined, absorbed: boolean): ShiftDescription | null {
    if (!rowShift || shiftedRows(rowShift) === 0) {
        return null
    }
    const px = signedShiftPx(rowShift)
    if (absorbed) {
        const magnitude = `${shiftedRows(rowShift)}px shift`
        return {
            tone: 'neutral',
            label: `Absorbed ${magnitude}`,
            compactLabel: magnitude,
            tooltip: absorbedTooltip(rowShift),
        }
    }
    return {
        tone: 'warning',
        label: `${px} Layout shift`,
        compactLabel: px,
        tooltip: layoutTooltip(rowShift),
    }
}

/** One band, as the sidebar names it. */
export function describeBand(band: ShiftBandApi): string {
    const verb = band.kind === 'deleted' ? 'deleted' : 'inserted'
    return `${pluralize(band.rows, 'row')} ${verb} at y=${band.y}`
}