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.

feat(quill-charts): add value bands and solid goal lines (#125546)

Ben Whitecb18db8dd568
diff --git a/frontend/snapshots.yml b/frontend/snapshots.yml
index ea60bc5161a7..ae09ed5cd24b 100644
--- a/frontend/snapshots.yml
+++ b/frontend/snapshots.yml
@@ -1588,6 +1588,10 @@ snapshots:
hash: v1.k794b7964.cc8ac9ac87b0a9c42e694f6ef8eb17ee1cb2c808231334cddbc501b29bfd2803.DRyZznjL5omRxi2ORqWwouaqFGP6Y6mr8GIIDo7a1fM
components-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_Zms889JW0KUa1vFZ9yW6WzMzRtjHMvW0
components-hogcharts-valuelabels--cross-series-overlap-removal--dark:
hash: v1.k794b7964.6f30b790996d5f9a72f60627b5a525a631336e999f1568bb2a77bacf433de98c.WbutrtIUPzoQzA1G6VJmvp9w_HM3aI4yIrxgvPwB8do
components-hogcharts-valuelabels--cross-series-overlap-removal--light:
diff --git a/packages/quill/packages/charts/AGENTS.md b/packages/quill/packages/charts/AGENTS.md
index 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.md
index 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 element
chart.hasRightAxis // boolean
chart.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 hidden
chart.legendItems() // [{ label, secondaryLabel }, …] legend rows in the render scope, empty when hidden
diff --git a/packages/quill/packages/charts/src/docs/overlays.md b/packages/quill/packages/charts/src/docs/overlays.md
index 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 i
Regression 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.ts
index 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.tsx
index 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.tsx
new file mode 100644
index 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.tsx
new file mode 100644
index 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.tsx
new file mode 100644
index 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.ts
index 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'): numb
return 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.ts
index 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.ts
index 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: number
label?: string
displayLabel?: boolean
color?: string
+ /** Line style. Defaults to `dashed`. */
+ stroke?: ReferenceLineStroke
labelPosition?: '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,
}))
}