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.

chore(quill-charts): document four props that agents get wrong (#121095)

Sam Penningtondc183f4eee2b
diff --git a/packages/quill/packages/charts/src/charts/PieChart/PieChart.tsx b/packages/quill/packages/charts/src/charts/PieChart/PieChart.tsx
index cd10f99fcbba..6ed37d4f11f6 100644
--- a/packages/quill/packages/charts/src/charts/PieChart/PieChart.tsx
+++ b/packages/quill/packages/charts/src/charts/PieChart/PieChart.tsx
@@ -78,8 +78,8 @@ export interface PieChartProps<Meta = unknown> {
* Receives the raw slice magnitude; the chart handles percent conversion when
* `isPercent` is on. */
valueFormatter?: (value: number) => string
- /** Optional content rendered at the center of the chart — typically the aggregation
- * total for a donut. Receives the layout so consumers can position custom content. */
+ /** Content rendered in the center of the chart, typically the total of a donut
+ * (`config.innerRadiusRatio` above 0). A top-level prop, not a `config` key. */
centerLabel?: React.ReactNode
/** React children passed through to the radial overlay layer (custom decorations). */
children?: React.ReactNode
diff --git a/packages/quill/packages/charts/src/components/MetricCard/MetricCard.tsx b/packages/quill/packages/charts/src/components/MetricCard/MetricCard.tsx
index 093218ac51b2..c7a1789027f4 100644
--- a/packages/quill/packages/charts/src/components/MetricCard/MetricCard.tsx
+++ b/packages/quill/packages/charts/src/components/MetricCard/MetricCard.tsx
@@ -47,6 +47,7 @@ export interface MetricCardProps {
/** Classes for the headline number. Replaces the default `text-4xl` size, e.g. with container
* query sizes so a narrow tile keeps the number on one line. */
headlineClassName?: string
+ /** Formats the change pill. Receives a percent, so `8` for +8%, as in {@link MetricChange.value}. */
formatChange?: (percent: number) => string
showChange?: boolean
/** Fixed comparison pill. Supplied → no hover-driven fallback. Pass `null` to suppress. */
diff --git a/packages/quill/packages/charts/src/components/MetricCard/resolveDelta.ts b/packages/quill/packages/charts/src/components/MetricCard/resolveDelta.ts
index c3875137ffec..706bd3c1a857 100644
--- a/packages/quill/packages/charts/src/components/MetricCard/resolveDelta.ts
+++ b/packages/quill/packages/charts/src/components/MetricCard/resolveDelta.ts
@@ -1,7 +1,11 @@
import type { ReactNode } from 'react'
export interface MetricChange {
+ /** Percent change, so `8` means +8% and `-3` means -3%. The sign sets the pill's direction,
+ * and `goodDirection` on the card decides whether that direction reads as good. */
value: number
+ /** Replaces the formatted `value` in the pill, for example `+1.1 pts` for a change in
+ * percentage points. */
label?: ReactNode
}
diff --git a/packages/quill/packages/charts/src/core/types.ts b/packages/quill/packages/charts/src/core/types.ts
index eaf198974b2b..2789b9a38d11 100644
--- a/packages/quill/packages/charts/src/core/types.ts
+++ b/packages/quill/packages/charts/src/core/types.ts
@@ -250,11 +250,13 @@ export interface ChartConfig {
yScaleType?: 'linear' | 'log'
// — Axis formatting —
- /** Custom x-axis tick label formatter. Return null to skip a tick. Called with (label, index). */
+ /** Custom x-axis tick label formatter. Return null to skip a tick. Called with (label, index).
+ * On a horizontal bar chart it formats the category labels on the left axis. */
xTickFormatter?: (value: string, index: number) => string | null
/** Fixed x-axis tick-label rotation in degrees, clamped to -90..90. Defaults to 0. */
xTickLabelRotation?: number
- /** Custom y-axis tick label formatter. Overrides the built-in auto-precision formatter. */
+ /** Custom y-axis tick label formatter. Overrides the built-in auto-precision formatter.
+ * On a horizontal bar chart it formats the value axis along the bottom. */
yTickFormatter?: (value: number) => string
/** Hide the x-axis labels and reduce bottom margin. */
hideXAxis?: boolean
diff --git a/packages/quill/packages/charts/src/docs/bars.md b/packages/quill/packages/charts/src/docs/bars.md
index 9029741a7ea7..c95fbae250fb 100644
--- a/packages/quill/packages/charts/src/docs/bars.md
+++ b/packages/quill/packages/charts/src/docs/bars.md
@@ -7,6 +7,7 @@ Field docs live on `BarChartConfig` and `BarsConfig` in `core/types.ts`; the per
- `barLayout: 'stacked' | 'grouped' | 'percent'`. Percent stacks bar series to 100% and puts the value scale on 0..1, so formatters receive fractions. Stacking groups by axis.
- `axisOrientation: 'horizontal'` for horizontal bars. Drag-to-zoom is disabled there, since the interaction axis is vertical.
+- The formatters keep their roles when the bars turn horizontal. `yTickFormatter` formats the value axis, now along the bottom, and `xTickFormatter` formats the category labels, now on the left.
- `divergingStack` (stacked only) stacks negative values below the zero baseline instead of clamping them to 0. Same semantics on `ComboChart` and `TimeSeriesComboChart`.
- `barCornerRadius` rounds the end caps. It is a top-level key on every bar-capable chart, including the time-series and combo configs.
- Set `bandPadding: 0` to remove both category and within-group gaps. Set `barCornerRadius: 0` for adjoining square bars. `TimeSeriesComboChart` accepts the same top-level `bandPadding` setting.
diff --git a/packages/quill/packages/charts/src/docs/chart-types.md b/packages/quill/packages/charts/src/docs/chart-types.md
index 5d2226379543..cc2f3a4af236 100644
--- a/packages/quill/packages/charts/src/docs/chart-types.md
+++ b/packages/quill/packages/charts/src/docs/chart-types.md
@@ -168,6 +168,7 @@ A left-aligned tile: headline number, change pill, sparkline.
- `formatLabel` formats the point label in the default subtitle, for example an ISO time as a short date. The sparkline keeps the raw `labels`, so they stay unique.
- `hoverChangeFromPreviousPoint` keeps the resting `change` pill at rest but, while hovering, swaps it for the hovered point's change versus the previous point (hidden at the first point).
- `changeTooltip` shows a styled hover tooltip on the change pill, using the host's tooltip surface tokens with chart-surface fallbacks.
+- `change.value` is a percent, so `8` reads as +8%. Its sign sets the pill's direction, and `goodDirection` decides whether that direction is good. `change.label` replaces the formatted text, for example `+1.1 pts` for a change in percentage points.
The composable form is `Metric` in `@posthog/quill-components` (it needs `Card` and `Badge` from primitives, which charts cannot depend on).
It is built on `Sparkline` plus the headless helpers this package exports: `resolveDelta` and `computeFallbackChangePercent` (delta math), `useAnimatedNumber` (count-up headline), `useHoverIntent` (hover dwell), and the `MetricChange` and `ResolvedDelta` types.
diff --git a/packages/quill/packages/charts/src/docs/overlays.md b/packages/quill/packages/charts/src/docs/overlays.md
index d77ee549c71d..54f7ce294cd1 100644
--- a/packages/quill/packages/charts/src/docs/overlays.md
+++ b/packages/quill/packages/charts/src/docs/overlays.md
@@ -60,6 +60,7 @@ Use it to mirror an external selection (the rows visible in a paired virtualized
On band (bar) charts the box covers the endpoints' full bands; on point (line) charts it runs point to point.
`color`, `fillOpacity`, and `borderOpacity` tune the look (`borderOpacity: 0` drops the edge border).
It clamps to the plot area and renders null when an endpoint does not resolve.
+It draws no label. To name the range, such as an incident window, add a vertical `ReferenceLine` whose `value` is the range's start label, and give it a `label`.
### `AnomalyPointsLayer`
diff --git a/packages/quill/packages/charts/src/overlays/HighlightedRange.tsx b/packages/quill/packages/charts/src/overlays/HighlightedRange.tsx
index 956396a62f74..8b262bbed9f7 100644
--- a/packages/quill/packages/charts/src/overlays/HighlightedRange.tsx
+++ b/packages/quill/packages/charts/src/overlays/HighlightedRange.tsx
@@ -23,7 +23,8 @@ export interface HighlightedRangeProps {
* (e.g. the rows currently visible in a paired virtualized list) onto the chart. On band
* (bar) charts the box covers the full bands of both endpoints; on point (line) charts it
* runs from point to point. Composes as a chart child like {@link ReferenceLine}; renders
- * null when an endpoint doesn't resolve to a positioned label. */
+ * null when an endpoint doesn't resolve to a positioned label. It draws no label, so name
+ * the range with a vertical {@link ReferenceLine} whose `value` is the start label. */
export function HighlightedRange({
start,
end,