: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
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.tsxindex 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.ReactNodediff --git a/packages/quill/packages/charts/src/components/MetricCard/MetricCard.tsx b/packages/quill/packages/charts/src/components/MetricCard/MetricCard.tsxindex 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) => stringshowChange?: 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.tsindex 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.tsindex 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?: booleandiff --git a/packages/quill/packages/charts/src/docs/bars.md b/packages/quill/packages/charts/src/docs/bars.mdindex 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.mdindex 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.mdindex 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 virtualizedOn 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.tsxindex 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,