: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.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
feat(quill-charts): add value bands and solid goal lines (#125546)
Ben Whitecb18db8dd568
diff --git a/frontend/snapshots.yml b/frontend/snapshots.ymlindex ea60bc5161a7..ae09ed5cd24b 100644--- a/frontend/snapshots.yml+++ b/frontend/snapshots.yml@@ -1588,6 +1588,10 @@ snapshots:hash: v1.k794b7964.cc8ac9ac87b0a9c42e694f6ef8eb17ee1cb2c808231334cddbc501b29bfd2803.DRyZznjL5omRxi2ORqWwouaqFGP6Y6mr8GIIDo7a1fMcomponents-hogcharts-trendlineoverlay--stacked-with-trend-lines--light:hash: v1.k794b7964.a7704eb3ae307e277f6efad56c1cebb4720451058325008b35944b4445e0b509.Fv0tV1Fyt0AhP_ZeikwMXWDVawcb_ryO_JJ7QE0G3tU+ components-hogcharts-valueband--threshold-zones--dark:+ hash: v1.k794b7964.8d2e202f6aa5084dd9ce5e41b4cfcb1cc2f9f0873ce831f9526ea28dda1f4779.M3WlD9WwDlICRpOgnHZ8xKfRxMy_6mg52BAT6C9_tmY+ components-hogcharts-valueband--threshold-zones--light:+ hash: v1.k794b7964.ce3cd0206eba9701650983b663cbb62d31a49e878fe8c487e9ba1fcec5afafd2.wNCQtGU59v_Zms889JW0KUa1vFZ9yW6WzMzRtjHMvW0components-hogcharts-valuelabels--cross-series-overlap-removal--dark:hash: v1.k794b7964.6f30b790996d5f9a72f60627b5a525a631336e999f1568bb2a77bacf433de98c.WbutrtIUPzoQzA1G6VJmvp9w_HM3aI4yIrxgvPwB8docomponents-hogcharts-valuelabels--cross-series-overlap-removal--light:diff --git a/packages/quill/packages/charts/AGENTS.md b/packages/quill/packages/charts/AGENTS.mdindex 23c1ebd270a5..6f28ff8c9de5 100644--- a/packages/quill/packages/charts/AGENTS.md+++ b/packages/quill/packages/charts/AGENTS.md@@ -85,7 +85,7 @@ Charts fill their container and need a parent with real dimensions — a zero-he</TimeSeriesLineChart>```-- Overlays (`ReferenceLine`/`ReferenceLines`, `ValueLabels`, `AxisTitles`, `TrendLineOverlay`, `HighlightedRange`, `AnomalyPointsLayer`) compose as children. Custom overlays read `useChartLayout()` / `useChartHover()`. [docs/overlays.md](./src/docs/overlays.md)+- Overlays (`ReferenceLine`/`ReferenceLines`, `ValueLabels`, `AxisTitles`, `TrendLineOverlay`, `HighlightedRange`, `ValueBand`, `AnomalyPointsLayer`) compose as children. Custom overlays read `useChartLayout()` / `useChartHover()`. [docs/overlays.md](./src/docs/overlays.md)- The built-in `DefaultTooltip` is configured through `config.tooltip`; a `tooltip` render prop replaces its content. [docs/tooltips.md](./src/docs/tooltips.md)- `config.legend` renders the built-in legend: plain click isolates, modifier click toggles. [docs/legend.md](./src/docs/legend.md)- Axis format, baseline, min/max, multi-axis, grid and axis-line chrome, margins. [docs/axes.md](./src/docs/axes.md)diff --git a/packages/quill/packages/charts/src/docs/TESTING.md b/packages/quill/packages/charts/src/docs/TESTING.mdindex 16c2d9774143..74cf9a405b26 100644--- a/packages/quill/packages/charts/src/docs/TESTING.md+++ b/packages/quill/packages/charts/src/docs/TESTING.md@@ -50,6 +50,7 @@ chart.yAxisLabelElement() // optional y-axis label SVG elementchart.hasRightAxis // booleanchart.referenceLines() // [{ label, position, color, orientation }, …]chart.valueLabels() // [{ text, color }, …]+chart.valueBands() // [{ top, left, width, height, color }, …]chart.anomalyPoints() // [{ element, color }, …] (TimeSeriesLineChart)chart.legend() // legend container in the render scope, null when hiddenchart.legendItems() // [{ label, secondaryLabel }, …] legend rows in the render scope, empty when hiddendiff --git a/packages/quill/packages/charts/src/docs/overlays.md b/packages/quill/packages/charts/src/docs/overlays.mdindex 0e80a7adcbe5..5fdcb147aea5 100644--- a/packages/quill/packages/charts/src/docs/overlays.md+++ b/packages/quill/packages/charts/src/docs/overlays.md@@ -54,6 +54,15 @@ The time-series charts render it from `xAxis.label` and `yAxis.label`; compose iRegression lines on vertical bar and combo charts. See [bars.md](./bars.md).+### `ValueBand`++A translucent band across the plot between `from` and `to` on the value axis, for threshold zones.+Omit `from` to run it to the plot bottom, or `to` to run it to the top; the part outside the axis range is clipped.+`yAxisId` picks a secondary axis.+The fill defaults to the theme's axis color.+It draws over the series, like a `ReferenceLine` fill, so keep `fillOpacity` low.+Pair each band with a goal line at its threshold (`GoalLineConfig.stroke: 'solid'` for a solid one), and expect the band to tint that line, because goal lines render first.+### `HighlightedRange`A translucent box spanning an x-axis range.diff --git a/packages/quill/packages/charts/src/index.ts b/packages/quill/packages/charts/src/index.tsindex 97881db1b090..fa3270e73a00 100644--- a/packages/quill/packages/charts/src/index.ts+++ b/packages/quill/packages/charts/src/index.ts@@ -234,6 +234,8 @@ export type {} from './overlays/ReferenceLine'export { HighlightedRange } from './overlays/HighlightedRange'export type { HighlightedRangeProps } from './overlays/HighlightedRange'+export { ValueBand } from './overlays/ValueBand'+export type { ValueBandProps } from './overlays/ValueBand'export { ValueLabels } from './overlays/ValueLabels'export type { ValueLabelContext, ValueLabelFormatter, ValueLabelsProps } from './overlays/ValueLabels'export { AxisTitles } from './overlays/AxisTitles'diff --git a/packages/quill/packages/charts/src/overlays/HighlightedRange.tsx b/packages/quill/packages/charts/src/overlays/HighlightedRange.tsxindex 8b262bbed9f7..a7838ea9a418 100644--- a/packages/quill/packages/charts/src/overlays/HighlightedRange.tsx+++ b/packages/quill/packages/charts/src/overlays/HighlightedRange.tsx@@ -4,7 +4,7 @@ import React from 'react'import { useChartLayout } from '../core/chart-context'/** Neutral gray matching the classic sparkline highlight, readable on light and dark surfaces. */-const DEFAULT_HIGHLIGHT_COLOR = '#8f8f8f'+export const DEFAULT_HIGHLIGHT_COLOR = '#8f8f8f'export interface HighlightedRangeProps {/** Start of the range — a data index (number) or an x-axis label (string). */diff --git a/packages/quill/packages/charts/src/overlays/ValueBand.stories.tsx b/packages/quill/packages/charts/src/overlays/ValueBand.stories.tsxnew file mode 100644index 000000000000..18cb0a193976--- /dev/null+++ b/packages/quill/packages/charts/src/overlays/ValueBand.stories.tsx@@ -0,0 +1,43 @@+import { Meta, StoryObj } from '@storybook/react'++import { TimeSeriesLineChart } from '../charts/TimeSeriesLineChart/TimeSeriesLineChart'+import type { Series } from '../core/types'+import { Stage, useReactiveTheme } from '../story-helpers'+import { ValueBand } from './ValueBand'++const LABELS = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']+const SERIES: Series[] = [{ key: 'cpu', label: 'CPU', data: [42, 55, 61, 83, 76, 91, 68] }]++const meta: Meta = {+ title: 'Components/HogCharts/ValueBand',+ parameters: { layout: 'centered' },+}+export default meta++type Story = StoryObj<{}>++export const ThresholdZones: Story = {+ render: () => {+ const theme = useReactiveTheme()+ return (+ <Stage>+ <TimeSeriesLineChart+ series={SERIES}+ labels={LABELS}+ theme={theme}+ config={{+ yAxis: { showGrid: true, min: 0, max: 100 },+ goalLines: [+ { value: 70, label: 'Warning', color: '#e8a317', stroke: 'solid' },+ { value: 85, label: 'Critical', color: '#d6336c' },+ ],+ }}+ >+ <ValueBand to={70} color="#2f9e44" />+ <ValueBand from={70} to={85} color="#e8a317" />+ <ValueBand from={85} color="#d6336c" fillOpacity={0.15} />+ </TimeSeriesLineChart>+ </Stage>+ )+ },+}diff --git a/packages/quill/packages/charts/src/overlays/ValueBand.test.tsx b/packages/quill/packages/charts/src/overlays/ValueBand.test.tsxnew file mode 100644index 000000000000..7fde5f2b4c01--- /dev/null+++ b/packages/quill/packages/charts/src/overlays/ValueBand.test.tsx@@ -0,0 +1,55 @@+import { cleanup } from '@testing-library/react'++import { makeOverlayContext, renderOverlayInChart } from '../testing'+import { readValueBands, type ValueBandSummary } from '../testing/accessor'+import { ValueBand, type ValueBandProps } from './ValueBand'++const DIMENSIONS = { width: 800, height: 400, plotLeft: 48, plotTop: 16, plotWidth: 720, plotHeight: 352 }+const PLOT_BOTTOM = 368++describe('ValueBand', () => {+ afterEach(() => cleanup())++ it.each<[string, ValueBandProps, 'vertical' | 'horizontal', Partial<ValueBandSummary> | null]>([+ ['spans two values', { from: 100, to: 200 }, 'vertical', { top: 168, height: 100, left: 48 }],+ ['swaps an inverted pair', { from: 200, to: 100 }, 'vertical', { top: 168, height: 100 }],+ ['runs to the plot top without `to`', { from: 300 }, 'vertical', { top: 16, height: 52 }],+ ['runs to the plot bottom without `from`', { to: 100 }, 'vertical', { top: 268, height: 100 }],+ ['clamps a band that spills past the plot', { from: 300, to: 900 }, 'vertical', { top: 16 }],+ ['renders nothing wholly outside the plot', { from: 500, to: 600 }, 'vertical', null],+ [+ 'reads the axis named by yAxisId',+ { from: 100, to: 200, yAxisId: 'right' },+ 'vertical',+ { top: 268, height: 50 },+ ],+ [+ 'spans the value axis on a horizontal chart',+ { from: 100, to: 200 },+ 'horizontal',+ { left: 148, width: 100, top: 16 },+ ],+ ['runs to the plot right on a horizontal chart', { from: 600 }, 'horizontal', { left: 648, width: 120 }],+ ])('%s', (_, props, axisOrientation, expected) => {+ const y = axisOrientation === 'vertical' ? (v: number) => PLOT_BOTTOM - v : (v: number) => 48 + v+ const right = { scale: (v: number) => PLOT_BOTTOM - v / 2, ticks: () => [], position: 'right' as const }+ const ctx = makeOverlayContext(+ { x: () => 0, y, yTicks: () => [], yAxes: { right } },+ { dimensions: DIMENSIONS, axisOrientation }+ )+ const { container } = renderOverlayInChart(<ValueBand {...props} />, ctx)+ expect(readValueBands(container)).toEqual(expected === null ? [] : [expect.objectContaining(expected)])+ })++ it.each([+ ['the theme axis color', undefined, 'rgb(1, 2, 3)'],+ ['an explicit color', 'rgb(4, 5, 6)', 'rgb(4, 5, 6)'],+ ])('fills with %s', (_, color, expected) => {+ const ctx = makeOverlayContext(+ { x: () => 0, y: (v: number) => PLOT_BOTTOM - v, yTicks: () => [] },+ { dimensions: DIMENSIONS, theme: { colors: ['#000'], axisColor: 'rgb(1, 2, 3)' } }+ )+ const { container } = renderOverlayInChart(<ValueBand from={100} to={200} color={color} />, ctx)+ expect(readValueBands(container).map((b) => b.color)).toEqual([expected])+ })+})diff --git a/packages/quill/packages/charts/src/overlays/ValueBand.tsx b/packages/quill/packages/charts/src/overlays/ValueBand.tsxnew file mode 100644index 000000000000..053024414783--- /dev/null+++ b/packages/quill/packages/charts/src/overlays/ValueBand.tsx@@ -0,0 +1,53 @@+/* eslint-disable react/forbid-dom-props -- dynamic pixel positions from d3 scales */+import React from 'react'++import { useChartLayout } from '../core/chart-context'+import { DEFAULT_HIGHLIGHT_COLOR } from './HighlightedRange'++export interface ValueBandProps {+ /** Low end of the band on the value axis. Omit to run the band to the bottom of the plot. */+ from?: number+ /** High end of the band on the value axis. Omit to run the band to the top of the plot. */+ to?: number+ /** CSS color for the fill. Supports `var(--my-color)`. Defaults to the theme's axis color. */+ color?: string+ /** Opacity 0-1 of the fill. Defaults to 0.1. */+ fillOpacity?: number+ /** Defaults to the primary axis. */+ yAxisId?: string+}++/** Translucent band between two values on the value axis. Draws over the series, so keep `fillOpacity` low. */+export function ValueBand({ from, to, color, fillOpacity = 0.1, yAxisId }: ValueBandProps): React.ReactElement | null {+ const { scales, dimensions, axis, theme } = useChartLayout()+ const { plotLeft, plotTop, plotWidth, plotHeight } = dimensions+ const scale = yAxisId && scales.yAxes?.[yAxisId] ? scales.yAxes[yAxisId].scale : scales.y+ const horizontal = axis.orientation === 'horizontal'+ const [lo, hi] = horizontal ? [plotLeft, plotLeft + plotWidth] : [plotTop, plotTop + plotHeight]+ const [axisMinEdge, axisMaxEdge] = horizontal ? [lo, hi] : [hi, lo]++ const ends = [from == null ? axisMinEdge : scale(from), to == null ? axisMaxEdge : scale(to)]+ if (!ends.every(isFinite)) {+ return null+ }+ const start = Math.max(lo, Math.min(...ends))+ const end = Math.min(hi, Math.max(...ends))+ if (end <= start) {+ return null+ }++ const rect: React.CSSProperties = horizontal+ ? { left: start, width: end - start, top: plotTop, height: plotHeight }+ : { left: plotLeft, width: plotWidth, top: start, height: end - start }+ return (+ <div+ data-attr="hog-chart-value-band"+ className="absolute pointer-events-none"+ style={{+ ...rect,+ backgroundColor: color ?? theme.axisColor ?? DEFAULT_HIGHLIGHT_COLOR,+ opacity: fillOpacity,+ }}+ />+ )+}diff --git a/packages/quill/packages/charts/src/testing/accessor.ts b/packages/quill/packages/charts/src/testing/accessor.tsindex 0754b49a780d..93b55fa0e36c 100644--- a/packages/quill/packages/charts/src/testing/accessor.ts+++ b/packages/quill/packages/charts/src/testing/accessor.ts@@ -38,6 +38,16 @@ interface ReferenceLineSummary {orientation: 'horizontal' | 'vertical' | null}+export interface ValueBandSummary {+ /** Pixel box of the band, from its inline style. */+ top: number | null+ left: number | null+ width: number | null+ height: number | null+ /** Fill color from inline style. */+ color: string+}+interface ValueLabelSummary {text: string/** Inline style backgroundColor (matches the series color). */@@ -92,6 +102,8 @@ export interface ChartAccessor<Meta = unknown> {hasRightAxis: boolean/** All reference lines currently rendered for this chart (goal/alert/marker). */referenceLines(): ReferenceLineSummary[]+ /** All value bands currently rendered for this chart. */+ valueBands(): ValueBandSummary[]/** All value-label overlays currently rendered for this chart. */valueLabels(): ValueLabelSummary[]/** All anomaly point markers currently rendered (TimeSeriesLineChart only). */@@ -172,7 +184,7 @@ function findCanvas(scope: HTMLElement): HTMLCanvasElement | null {return scope.querySelector('canvas[aria-label]')}-function parsePixelStyle(style: CSSStyleDeclaration, prop: 'top' | 'left'): number | null {+function parsePixelStyle(style: CSSStyleDeclaration, prop: 'top' | 'left' | 'width' | 'height'): number | null {const raw = style[prop]if (!raw || !raw.endsWith('px')) {return null@@ -181,6 +193,17 @@ function parsePixelStyle(style: CSSStyleDeclaration, prop: 'top' | 'left'): numbreturn Number.isFinite(n) ? n : null}+/** Value bands rendered inside `scope`. Exported for overlay tests that render without a chart. */+export function readValueBands(scope: ParentNode): ValueBandSummary[] {+ return Array.from(scope.querySelectorAll<HTMLElement>('[data-attr="hog-chart-value-band"]')).map((el) => ({+ top: parsePixelStyle(el.style, 'top'),+ left: parsePixelStyle(el.style, 'left'),+ width: parsePixelStyle(el.style, 'width'),+ height: parsePixelStyle(el.style, 'height'),+ color: el.style.backgroundColor,+ }))+}+// The reference-line component renders a 1px line as a single coloured border// edge on an otherwise zero-size div: horizontal lines colour `border-top`,// vertical lines colour `border-left`. Whichever of the two is set tells us@@ -261,6 +284,7 @@ export function getChart<Meta = unknown>(Array.from(wrapper.querySelectorAll<HTMLElement>('[data-attr="hog-chart-reference-line"]')).map(readReferenceLine),+ valueBands: () => readValueBands(wrapper),valueLabels: () =>Array.from(wrapper.querySelectorAll<HTMLElement>('[data-attr="hog-chart-value-label"]')).map((el) => ({text: el.textContent ?? '',diff --git a/packages/quill/packages/charts/src/utils/goal-lines.test.ts b/packages/quill/packages/charts/src/utils/goal-lines.test.tsindex 41921e575939..c0154e7d2417 100644--- a/packages/quill/packages/charts/src/utils/goal-lines.test.ts+++ b/packages/quill/packages/charts/src/utils/goal-lines.test.ts@@ -65,6 +65,7 @@ describe('goal-lines', () => {['omits label when displayLabel is false', { displayLabel: false }, { label: undefined }],['respects explicit labelPosition', { labelPosition: 'start' as const }, { labelPosition: 'start' }],['forwards showValueOnHover', { showValueOnHover: false }, { showValueOnHover: false }],+ ['forwards stroke via style.stroke', { stroke: 'solid' as const }, { style: { stroke: 'solid' } }],] as const)('%s', (_, lineOverrides, expectedProps) => {const lines: GoalLineConfig[] = [{ label: 'X', value: 50, ...lineOverrides }]expect(buildGoalLineReferenceLines(lines, series)[0]).toMatchObject(expectedProps)diff --git a/packages/quill/packages/charts/src/utils/goal-lines.ts b/packages/quill/packages/charts/src/utils/goal-lines.tsindex aeb2423e4f46..ceab8b6fa95f 100644--- a/packages/quill/packages/charts/src/utils/goal-lines.ts+++ b/packages/quill/packages/charts/src/utils/goal-lines.ts@@ -1,11 +1,13 @@import type { Series, ValueDomain } from '../core/types'-import type { ReferenceLineProps } from '../overlays/ReferenceLine'+import type { ReferenceLineProps, ReferenceLineStroke } from '../overlays/ReferenceLine'export interface GoalLineConfig {value: numberlabel?: stringdisplayLabel?: booleancolor?: string+ /** Line style. Defaults to `dashed`. */+ stroke?: ReferenceLineStrokelabelPosition?: 'start' | 'end'displayIfCrossed?: boolean/** Forwarded to {@link ReferenceLineProps.showValueOnHover}; defaults to true. */@@ -48,7 +50,7 @@ export function buildGoalLineReferenceLines(// Match the UI control and legacy chart.js, which both default an unset position to 'end'.labelPosition: line.labelPosition ?? 'end',variant: 'goal',- style: line.color ? { color: line.color } : undefined,+ style: { color: line.color, stroke: line.stroke },showValueOnHover: line.showValueOnHover,}))}