@automattic/charts 4.8.0 → 4.10.0

package/dist/index.css

@@ -547,9 +547,9 @@
 }
 
 .a8ccharts-O3YMOW-heatmap-chart__group-label {
-  color: var(--a8c-charts-color-label-secondary);
-  font-size: var(--wpds-typography-font-size-xs, 11px);
-  line-height: var(--wpds-typography-line-height-xs, 16px);
+  color: var(--a8c-charts-color-label);
+  font-size: var(--wpds-typography-font-size-md, 13px);
+  line-height: var(--wpds-typography-line-height-sm, 20px);
   white-space: nowrap;
   text-align: center;
   padding-block-start: var(--wpds-dimension-padding-xs, 4px);
@@ -639,6 +639,10 @@
   background: color-mix(in sRGB, var(--a8c-charts-color-heatmap-high, var(--a8c-charts-color-heatmap-primary)) calc(var(--a8c-charts-heatmap-cell-intensity) * 100%), var(--a8c-charts-color-heatmap-low, color-mix(in sRGB, var(--a8c-charts-color-heatmap-primary) 15%, var(--a8c-charts-color-background, #fff))));
 }
 
+.a8ccharts-O3YMOW-heatmap-chart__legend-swatch--empty {
+  background: var(--a8c-charts-color-track);
+}
+
 .a8ccharts-O3YMOW-heatmap-chart__legend-scale--bar {
   border-radius: var(--a8c-charts-border-radius-cell);
   overflow: hidden;
@@ -766,6 +770,12 @@
   inset: 0;
 }
 
+.a8ccharts-GovfoW-rowItem {
+  grid-column: 1 / -1;
+  grid-template-columns: subgrid;
+  display: grid;
+}
+
 .a8ccharts-GovfoW-row {
   grid-column: 1 / -1;
   grid-template-columns: subgrid;
@@ -793,23 +803,23 @@
   transition: transform var(--wpds-motion-duration-sm, .1s) var(--wpds-motion-easing-subtle, cubic-bezier(.15, 0, .15, 1));
 }
 
-.a8ccharts-GovfoW-interactiveRow:hover, .a8ccharts-GovfoW-interactiveRow:focus-visible {
+.a8ccharts-GovfoW-interactiveRow:hover:not(:has(:is(a, button):not(.a8ccharts-GovfoW-rowButton):hover)), .a8ccharts-GovfoW-interactiveRow:focus-visible, .a8ccharts-GovfoW-interactiveRow:has( > .a8ccharts-GovfoW-rowButton:focus-visible) {
   --a8c-charts-dimension-leaderboard-bar-hover-inset: var(--wpds-dimension-gap-2xl, 32px);
 }
 
-.a8ccharts-GovfoW-interactiveRow:hover .a8ccharts-GovfoW-bar, .a8ccharts-GovfoW-interactiveRow:focus-visible .a8ccharts-GovfoW-bar {
+.a8ccharts-GovfoW-interactiveRow:hover:not(:has(:is(a, button):not(.a8ccharts-GovfoW-rowButton):hover)) .a8ccharts-GovfoW-bar, .a8ccharts-GovfoW-interactiveRow:focus-visible .a8ccharts-GovfoW-bar, .a8ccharts-GovfoW-interactiveRow:has( > .a8ccharts-GovfoW-rowButton:focus-visible) .a8ccharts-GovfoW-bar {
   opacity: .5;
 }
 
-.a8ccharts-GovfoW-interactiveRow:hover .a8ccharts-GovfoW-valueContainer, .a8ccharts-GovfoW-interactiveRow:focus-visible .a8ccharts-GovfoW-valueContainer {
+.a8ccharts-GovfoW-interactiveRow:hover:not(:has(:is(a, button):not(.a8ccharts-GovfoW-rowButton):hover)) .a8ccharts-GovfoW-valueContainer, .a8ccharts-GovfoW-interactiveRow:focus-visible .a8ccharts-GovfoW-valueContainer, .a8ccharts-GovfoW-interactiveRow:has( > .a8ccharts-GovfoW-rowButton:focus-visible) .a8ccharts-GovfoW-valueContainer {
   transform: translateX(calc(var(--a8c-charts-dimension-leaderboard-bar-hover-inset) * -1));
 }
 
-.a8ccharts-GovfoW-interactiveRow:hover .a8ccharts-GovfoW-chevron, .a8ccharts-GovfoW-interactiveRow:focus-visible .a8ccharts-GovfoW-chevron {
+.a8ccharts-GovfoW-interactiveRow:hover:not(:has(:is(a, button):not(.a8ccharts-GovfoW-rowButton):hover)) .a8ccharts-GovfoW-chevron, .a8ccharts-GovfoW-interactiveRow:focus-visible .a8ccharts-GovfoW-chevron, .a8ccharts-GovfoW-interactiveRow:has( > .a8ccharts-GovfoW-rowButton:focus-visible) .a8ccharts-GovfoW-chevron {
   opacity: 1;
 }
 
-[dir="rtl"] .a8ccharts-GovfoW-interactiveRow:hover .a8ccharts-GovfoW-valueContainer, [dir="rtl"] .a8ccharts-GovfoW-interactiveRow:focus-visible .a8ccharts-GovfoW-valueContainer {
+[dir="rtl"] .a8ccharts-GovfoW-interactiveRow:hover:not(:has(:is(a, button):not(.a8ccharts-GovfoW-rowButton):hover)) .a8ccharts-GovfoW-valueContainer, [dir="rtl"] .a8ccharts-GovfoW-interactiveRow:focus-visible .a8ccharts-GovfoW-valueContainer, [dir="rtl"] .a8ccharts-GovfoW-interactiveRow:has( > .a8ccharts-GovfoW-rowButton:focus-visible) .a8ccharts-GovfoW-valueContainer {
   transform: translateX(var(--a8c-charts-dimension-leaderboard-bar-hover-inset));
 }
 
@@ -819,6 +829,39 @@
   outline-offset: calc(-1 * var(--wpds-border-width-focus, var(--wp-admin-border-width-focus, 2px)));
 }
 
+.a8ccharts-GovfoW-layeredRow {
+  isolation: isolate;
+}
+
+.a8ccharts-GovfoW-layeredRow > :not(.a8ccharts-GovfoW-rowButton, .a8ccharts-GovfoW-chevron) {
+  z-index: 1;
+  pointer-events: none;
+  position: relative;
+}
+
+.a8ccharts-GovfoW-layeredRow :is(a, button):not(.a8ccharts-GovfoW-rowButton) {
+  z-index: 1;
+  pointer-events: auto;
+  position: relative;
+}
+
+.a8ccharts-GovfoW-rowButton {
+  appearance: none;
+  cursor: pointer;
+  z-index: 0;
+  background: none;
+  border: 0;
+  padding: 0;
+  position: absolute;
+  inset: 0;
+}
+
+.a8ccharts-GovfoW-rowButton:focus-visible {
+  border-radius: var(--wpds-border-radius-sm, 2px);
+  outline: var(--wpds-border-width-focus, var(--wp-admin-border-width-focus, 2px)) solid var(--wpds-color-stroke-focus, var(--wp-admin-theme-color, #3858e9));
+  outline-offset: calc(-1 * var(--wpds-border-width-focus, var(--wp-admin-border-width-focus, 2px)));
+}
+
 .a8ccharts-GovfoW-chevron {
   inset-inline-end: var(--wpds-dimension-padding-xs, 4px);
   opacity: 0;
@@ -840,6 +883,23 @@
     transition: none;
   }
 }
+.a8ccharts-V2HDKq-selected-ring__contrast, .a8ccharts-V2HDKq-selected-ring__focus {
+  fill: none;
+}
+
+.a8ccharts-V2HDKq-selected-ring__contrast {
+  stroke: var(--a8c-charts-color-background, #fff);
+  stroke-width: calc(4 * var(--wpds-border-width-focus, var(--wp-admin-border-width-focus, 2px)));
+}
+
+.a8ccharts-V2HDKq-selected-ring__focus {
+  stroke: var(--wpds-color-stroke-focus, var(--wp-admin-theme-color, #3858e9));
+  stroke-width: calc(2 * var(--wpds-border-width-focus, var(--wp-admin-border-width-focus, 2px)));
+}
+.a8ccharts-gnszbG-pie-chart {
+  isolation: isolate;
+}
+
 .a8ccharts-gnszbG-pie-chart__plot {
   position: relative;
 }
@@ -868,6 +928,10 @@
 .a8ccharts-gnszbG-pie-chart__label-text--white {
   fill: #fff;
 }
+.a8ccharts-YtTOxW-pie-semi-circle-chart {
+  isolation: isolate;
+}
+
 .a8ccharts-YtTOxW-pie-semi-circle-chart__plot {
   position: relative;
 }

package/dist/index.d.cts

@@ -145,7 +145,7 @@ type DataPointDate = {
   /** Per-point fill override for BarChart; other built-in charts ignore it. */
   color?: string;
 };
-type LeaderboardEntry = {
+type LeaderboardEntryFields = {
   /**
    * Unique internal key (e.g., 'key-direct')
    */
@@ -191,7 +191,8 @@ type LeaderboardEntry = {
    * For links or other interactive affordances (external-link icons, info
    * tooltips), put them in the `label` render prop instead of using onClick —
    * a row is either a button (onClick) or carries interactive label content,
-   * never both, since interactive elements cannot be nested in HTML.
+   * never both, since interactive elements cannot be nested in HTML. The
+   * exception is a row that sets `hasInteractiveLabel`.
    */
   onClick?: (event: MouseEvent<HTMLButtonElement>) => void;
   /**
@@ -205,6 +206,18 @@ type LeaderboardEntry = {
    */
   ariaLabel?: string;
 };
+type LeaderboardEntry = LeaderboardEntryFields & ({
+  hasInteractiveLabel?: false;
+} | {
+  /**
+   * Set when the `label` holds its own link or button. The row's button
+   * then sits behind the row instead of around it, so both stay operable.
+   * Requires `onClick`, and `ariaLabel` since the button wraps no text.
+   */
+  hasInteractiveLabel: true;
+  onClick: (event: MouseEvent<HTMLButtonElement>) => void;
+  ariaLabel: string;
+});
 type GradientStop = {
   offset: string;
   color?: string;
@@ -315,9 +328,15 @@ type ChartTheme = {
    *
    * `fontFamily: 'inherit'` is load-bearing here — it overrides the font stack
    * `buildChartTheme` injects inline on SVG `<text>`.
+   *
+   * Give `fontSize` in pixels (`12` or `'12px'`). Margins and pie labels cannot measure `rem`, `em`, `%` or `var()`, so they use the default size and labels can clip (CHARTS-303). An invalid size is dropped.
    */
   svgLabelSmall?: Omit<TextProps, 'fill'>;
-  /** Styles for large SVG text (eg. axis titles), passed through to the XYChart theme. */
+  /**
+   * Styles for large SVG text (eg. axis titles), passed through to the XYChart theme.
+   *
+   * Give `fontSize` in pixels, as for `svgLabelSmall`.
+   */
   svgLabelBig?: TextProps;
   annotationStyles?: ThemeAnnotationStyles;
   /** LeaderboardChart specific settings */
@@ -561,6 +580,8 @@ type ChartLegendConfig<T = DataPoint | DataPointDate | LeaderboardEntry> = {
    */
   shapeStyles?: LegendShapeStyles;
 };
+/** Names a comparison series' legend item after the label of the series it is compared with. */
+type ComparisonItemLabel = (seriesLabel: string) => string;
 /**
  * Legend config for charts built from `SeriesData` (line, bar, area). Adds `collapseGroups` on top
  * of the shared config. It is intentionally absent from the base `ChartLegendConfig` so point-based
@@ -581,6 +602,11 @@ type SeriesChartLegendConfig = ChartLegendConfig<SeriesData[]> & {
    * Pass a string to replace the default label.
    */
   comparisonItem?: boolean | string;
+  /**
+   * Append one static item per comparison series instead, named by calling this with the label
+   * of the series it is compared with, and left out while that series is hidden.
+   */
+  comparisonSeriesItems?: ComparisonItemLabel;
 };
 /**
  * Initial visibility options for charts built from labelled series.
@@ -609,6 +635,10 @@ type BaseChartProps<T = DataPoint | DataPointDate | LeaderboardEntry> = {
    * Additional CSS class name for the chart container
    */
   className?: string;
+  /**
+   * Accessible name of the chart. Name it after what it shows, and give each chart on a page a different name. Each chart type has a localized default, such as "Line chart".
+   */
+  ariaLabel?: string;
   /**
    * Width of the chart container in pixels. When omitted, the chart fills its parent's width.
    */
@@ -748,6 +778,8 @@ type BaseLegendItem = {
   seriesLabels?: string[];
   /** Set to false for a static item that cannot be toggled or dimmed. */
   interactive?: boolean;
+  /** Label of the series this static item describes; the item is left out while it is hidden. */
+  describesSeries?: string;
 };
 //#endregion
 //#region src/components/legend/legend.d.ts
@@ -775,7 +807,9 @@ interface ChartLegendOptions {
    * `options.type === 'comparison'`. Skipped when that series already has its own
    * item. Pass a string to replace the default label.
    */
-  comparisonItem?: boolean | string;
+  comparisonItem?: SeriesChartLegendConfig['comparisonItem'];
+  /** One static item per comparison series instead; see `SeriesChartLegendConfig`. */
+  comparisonSeriesItems?: SeriesChartLegendConfig['comparisonSeriesItems'];
 }
 /**
  * Hook to transform chart data into legend items
@@ -880,14 +914,14 @@ type LineChartAnnotationProps = {
   subjectType?: 'circle' | 'line-vertical' | 'line-horizontal';
   styles?: AnnotationStyles;
   testId?: string;
-  renderLabel?: FC<{
+  renderLabel?: (props: {
     title: string;
     subtitle?: string;
-  }>;
-  renderLabelPopover?: FC<{
+  }) => ReactNode;
+  renderLabelPopover?: (props: {
     title: string;
     subtitle?: string;
-  }>;
+  }) => ReactNode;
 };
 type CurveType = 'smooth' | 'linear' | 'monotone';
 type RenderLineGlyphProps<Datum extends object> = GlyphProps<Datum> & {
@@ -1215,7 +1249,7 @@ interface TooltipRenderProps {
 /**
  * Props for the ConversionFunnelChart component
  */
-interface ConversionFunnelChartProps extends Pick<BaseChartProps, 'className' | 'chartId' | 'animation'> {
+interface ConversionFunnelChartProps extends Pick<BaseChartProps, 'className' | 'chartId' | 'animation' | 'ariaLabel'> {
   /** Main conversion rate to highlight */
   mainRate: number;
   /** Change indicator (e.g., +2%, -1.5%) */
@@ -1275,7 +1309,7 @@ interface GeoChartError {
   detailedMessage?: string;
   options?: Record<string, unknown>;
 }
-interface GeoChartProps extends Pick<BaseChartProps, 'className' | 'chartId' | 'width' | 'height'> {
+interface GeoChartProps extends Pick<BaseChartProps, 'className' | 'chartId' | 'ariaLabel' | 'width' | 'height'> {
   /**
    * Data in Google Charts native format for maximum flexibility.
    * First row contains column headers, subsequent rows contain data.
@@ -1394,10 +1428,10 @@ interface HeatmapChartProps extends Omit<BaseChartProps<HeatmapColumn[]>, 'showL
    * group past the edge, Page Up/Down by one group. Default `grid`.
    */
   keyboardNavigation?: 'grid' | 'calendar';
-  /** Accessible name of the grid. Defaults to a localized "Heatmap chart". */
-  ariaLabel?: string;
   /** Compact mode: hide in-cell values, tighten gap, thin axis labels. Default false. */
   compact?: boolean;
+  /** Compact mode only: grow the cells to fill the chart's box, wrapping the column groups onto more rows when that makes them larger. Default false. */
+  fitCells?: boolean;
   /** Render the numeric value inside each cell. Default `! compact`. */
   showValues?: boolean;
   /**
@@ -1485,7 +1519,7 @@ type MonthCalendarHeatmapResult = {
 //#endregion
 //#region src/charts/heatmap-chart/private/heatmap-legend.d.ts
 interface HeatmapLegendProps {
-  /** Number of swatches in the scale. Default 5. */
+  /** Number of color swatches in the scale, not counting the empty-cell swatch. Default 5. */
   steps?: number;
   /**
    * `swatches` spaces the steps out as cell-sized squares; `bar` joins them
@@ -1550,7 +1584,12 @@ declare const useCalendarHeatmapData: (series: DataPointDate[], options?: Calend
 declare const useMonthCalendarHeatmapData: (valueByDay: Record<string, number | null>, range: MonthCalendarHeatmapRange, options?: MonthCalendarHeatmapOptions) => MonthCalendarHeatmapResult;
 //#endregion
 //#region src/charts/leaderboard-chart/types.d.ts
-interface LeaderboardChartProps extends Pick<BaseChartProps<LeaderboardEntry>, 'className' | 'data' | 'showLegend' | 'legend' | 'chartId' | 'width' | 'height' | 'size' | 'gap' | 'animation'> {
+interface LeaderboardChartProps extends Pick<BaseChartProps<LeaderboardEntry>, 'className' | 'showLegend' | 'legend' | 'chartId' | 'width' | 'height' | 'size' | 'gap' | 'animation' | 'ariaLabel'> {
+  /**
+   * Entries to display. Declared here rather than picked, since the base type
+   * would split the entry union into one array type per member.
+   */
+  data: LeaderboardEntry[];
   /**
    * Whether to show comparison data
    */
@@ -2381,5 +2420,5 @@ declare const defaultTheme: CompleteChartTheme;
  */
 declare const useChartScopeElement: () => HTMLElement | null;
 //#endregion
-export { AccessibleTooltip, type AnnotationStyles, type ArcData, AreaChartResponsive as AreaChart, type AreaChartProps, AreaChart as AreaChartUnresponsive, type AxisOptions, type BandHighlightSelection, BarChartResponsive as BarChart, type BarChartProps, BarChart as BarChartUnresponsive, BarListChartResponsive as BarListChart, type BarListChartProps, BarListChart as BarListChartUnresponsive, type BaseChartProps, type BaseLegendItem, type BaseLegendProps, BaseTooltip, type BaseTooltipProps, type BucketInfo, type CalendarHeatmapOptions, type CalendarHeatmapResult, type ChartFormatting, type ChartLegendConfig, type ChartLegendOptions, type ChartTheme, type CompleteChartTheme, ConversionFunnelChartWithProvider as ConversionFunnelChart, type ConversionFunnelChartProps, type CrosshairStyle, type CurveType, type DataPoint, type DataPointDate, type DataPointPercentage, type EventHandlerParams, type FunnelStep, GeoChartResponsive as GeoChart, type GeoChartError, type GeoChartProps, GeoChartWithProvider as GeoChartUnresponsive, type GeoData, type GeoDisplayMode, type GeoRegion, type GeoResolution, GlobalChartsContext, GlobalChartsProvider, GlobalChartsProvider as ThemeProvider, type GoogleDataTableColumn, GoogleDataTableColumnRoleType, type GoogleDataTableRow, type GradientConfig, type GradientStop, type GridStyles, type HeatmapCell, HeatmapChartResponsive as HeatmapChart, type HeatmapChartProps, HeatmapChart as HeatmapChartUnresponsive, type HeatmapColumn, type HeatmapColumnGroup, type HeatmapTooltipData, LeaderboardChartResponsive as LeaderboardChart, type LeaderboardChartProps, LeaderboardChart as LeaderboardChartUnresponsive, type LeaderboardEntry, Legend, type LegendItemStyles, type LegendLabelStyles, type LegendPosition, type LegendProps, type LegendShape, type LegendShapeLabel, type LegendShapeRenderProps, type LegendShapeStyles, type LegendValueDisplay, LineChartResponsive as LineChart, type LineChartAnnotationProps, type LineChartProps, LineChart as LineChartUnresponsive, type LineStyles, type MainMetricRenderProps, type MetricValueType, type MonthCalendarHeatmapOptions, type MonthCalendarHeatmapRange, type MonthCalendarHeatmapResult, type MultipleDataPointsDate, type Optional, type OrientationType, PieChartResponsive as PieChart, type PieChartProps, type PieChartRenderTooltipParams, PieChart as PieChartUnresponsive, PieSemiCircleChartResponsive as PieSemiCircleChart, type PieSemiCircleChartProps, type PieSemiCircleChartRenderTooltipParams, PieSemiCircleChart as PieSemiCircleChartUnresponsive, type RenderLabelProps, type RenderLineGlyphProps, type RenderTooltipGlyphProps, type RenderTooltipParams, type RenderValueProps, type ScaleOptions, type SeriesChartLegendConfig, type SeriesData, type SeriesDataOptions, type SeriesVisibilityProps, Sparkline, type SparklineDataPoint, type SparklineProps, SparklineUnresponsive, type StepLabelRenderProps, type StepRateRenderProps, type TickResolution, TooltipBox, type TooltipBoxProps, type TooltipData, type TooltipDatum, type TooltipPlacement, type TooltipProps, type TooltipRenderProps, type TrendDirection, TrendIndicator, type TrendIndicatorProps, XYChartTooltip, type XyChartTooltipProps, buildCalendarHeatmapData, buildMonthCalendarHeatmapData, defaultTheme, formatMetricValue, formatPercentage, getBucketInfo, getColorDistance, hexToRgba, isValidHexColor, lightenHexColor, mergeThemes, mixHexColors, normalizeColorToHex, parseAsLocalDate, parseHslString, prefersLightText, relativeLuminance, resolveCssVariable, useCalendarHeatmapData, useChartFormatting, useChartLegendItems, useChartRegistration, useChartScopeElement, useGlobalChartsContext, useGlobalChartsTheme, useLeaderboardLegendItems, useMonthCalendarHeatmapData, validateHexColor };
+export { AccessibleTooltip, type AnnotationStyles, type ArcData, AreaChartResponsive as AreaChart, type AreaChartProps, AreaChart as AreaChartUnresponsive, type AxisOptions, type BandHighlightSelection, BarChartResponsive as BarChart, type BarChartProps, BarChart as BarChartUnresponsive, BarListChartResponsive as BarListChart, type BarListChartProps, BarListChart as BarListChartUnresponsive, type BaseChartProps, type BaseLegendItem, type BaseLegendProps, BaseTooltip, type BaseTooltipProps, type BucketInfo, type CalendarHeatmapOptions, type CalendarHeatmapResult, type ChartFormatting, type ChartLegendConfig, type ChartLegendOptions, type ChartTheme, type ComparisonItemLabel, type CompleteChartTheme, ConversionFunnelChartWithProvider as ConversionFunnelChart, type ConversionFunnelChartProps, type CrosshairStyle, type CurveType, type DataPoint, type DataPointDate, type DataPointPercentage, type EventHandlerParams, type FunnelStep, GeoChartResponsive as GeoChart, type GeoChartError, type GeoChartProps, GeoChartWithProvider as GeoChartUnresponsive, type GeoData, type GeoDisplayMode, type GeoRegion, type GeoResolution, GlobalChartsContext, GlobalChartsProvider, GlobalChartsProvider as ThemeProvider, type GoogleDataTableColumn, GoogleDataTableColumnRoleType, type GoogleDataTableRow, type GradientConfig, type GradientStop, type GridStyles, type HeatmapCell, HeatmapChartResponsive as HeatmapChart, type HeatmapChartProps, HeatmapChart as HeatmapChartUnresponsive, type HeatmapColumn, type HeatmapColumnGroup, type HeatmapTooltipData, LeaderboardChartResponsive as LeaderboardChart, type LeaderboardChartProps, LeaderboardChart as LeaderboardChartUnresponsive, type LeaderboardEntry, Legend, type LegendItemStyles, type LegendLabelStyles, type LegendPosition, type LegendProps, type LegendShape, type LegendShapeLabel, type LegendShapeRenderProps, type LegendShapeStyles, type LegendValueDisplay, LineChartResponsive as LineChart, type LineChartAnnotationProps, type LineChartProps, LineChart as LineChartUnresponsive, type LineStyles, type MainMetricRenderProps, type MetricValueType, type MonthCalendarHeatmapOptions, type MonthCalendarHeatmapRange, type MonthCalendarHeatmapResult, type MultipleDataPointsDate, type Optional, type OrientationType, PieChartResponsive as PieChart, type PieChartProps, type PieChartRenderTooltipParams, PieChart as PieChartUnresponsive, PieSemiCircleChartResponsive as PieSemiCircleChart, type PieSemiCircleChartProps, type PieSemiCircleChartRenderTooltipParams, PieSemiCircleChart as PieSemiCircleChartUnresponsive, type RenderLabelProps, type RenderLineGlyphProps, type RenderTooltipGlyphProps, type RenderTooltipParams, type RenderValueProps, type ScaleOptions, type SeriesChartLegendConfig, type SeriesData, type SeriesDataOptions, type SeriesVisibilityProps, Sparkline, type SparklineDataPoint, type SparklineProps, SparklineUnresponsive, type StepLabelRenderProps, type StepRateRenderProps, type TickResolution, TooltipBox, type TooltipBoxProps, type TooltipData, type TooltipDatum, type TooltipPlacement, type TooltipProps, type TooltipRenderProps, type TrendDirection, TrendIndicator, type TrendIndicatorProps, XYChartTooltip, type XyChartTooltipProps, buildCalendarHeatmapData, buildMonthCalendarHeatmapData, defaultTheme, formatMetricValue, formatPercentage, getBucketInfo, getColorDistance, hexToRgba, isValidHexColor, lightenHexColor, mergeThemes, mixHexColors, normalizeColorToHex, parseAsLocalDate, parseHslString, prefersLightText, relativeLuminance, resolveCssVariable, useCalendarHeatmapData, useChartFormatting, useChartLegendItems, useChartRegistration, useChartScopeElement, useGlobalChartsContext, useGlobalChartsTheme, useLeaderboardLegendItems, useMonthCalendarHeatmapData, validateHexColor };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.ts

@@ -145,7 +145,7 @@ type DataPointDate = {
   /** Per-point fill override for BarChart; other built-in charts ignore it. */
   color?: string;
 };
-type LeaderboardEntry = {
+type LeaderboardEntryFields = {
   /**
    * Unique internal key (e.g., 'key-direct')
    */
@@ -191,7 +191,8 @@ type LeaderboardEntry = {
    * For links or other interactive affordances (external-link icons, info
    * tooltips), put them in the `label` render prop instead of using onClick —
    * a row is either a button (onClick) or carries interactive label content,
-   * never both, since interactive elements cannot be nested in HTML.
+   * never both, since interactive elements cannot be nested in HTML. The
+   * exception is a row that sets `hasInteractiveLabel`.
    */
   onClick?: (event: MouseEvent<HTMLButtonElement>) => void;
   /**
@@ -205,6 +206,18 @@ type LeaderboardEntry = {
    */
   ariaLabel?: string;
 };
+type LeaderboardEntry = LeaderboardEntryFields & ({
+  hasInteractiveLabel?: false;
+} | {
+  /**
+   * Set when the `label` holds its own link or button. The row's button
+   * then sits behind the row instead of around it, so both stay operable.
+   * Requires `onClick`, and `ariaLabel` since the button wraps no text.
+   */
+  hasInteractiveLabel: true;
+  onClick: (event: MouseEvent<HTMLButtonElement>) => void;
+  ariaLabel: string;
+});
 type GradientStop = {
   offset: string;
   color?: string;
@@ -315,9 +328,15 @@ type ChartTheme = {
    *
    * `fontFamily: 'inherit'` is load-bearing here — it overrides the font stack
    * `buildChartTheme` injects inline on SVG `<text>`.
+   *
+   * Give `fontSize` in pixels (`12` or `'12px'`). Margins and pie labels cannot measure `rem`, `em`, `%` or `var()`, so they use the default size and labels can clip (CHARTS-303). An invalid size is dropped.
    */
   svgLabelSmall?: Omit<TextProps, 'fill'>;
-  /** Styles for large SVG text (eg. axis titles), passed through to the XYChart theme. */
+  /**
+   * Styles for large SVG text (eg. axis titles), passed through to the XYChart theme.
+   *
+   * Give `fontSize` in pixels, as for `svgLabelSmall`.
+   */
   svgLabelBig?: TextProps;
   annotationStyles?: ThemeAnnotationStyles;
   /** LeaderboardChart specific settings */
@@ -561,6 +580,8 @@ type ChartLegendConfig<T = DataPoint | DataPointDate | LeaderboardEntry> = {
    */
   shapeStyles?: LegendShapeStyles;
 };
+/** Names a comparison series' legend item after the label of the series it is compared with. */
+type ComparisonItemLabel = (seriesLabel: string) => string;
 /**
  * Legend config for charts built from `SeriesData` (line, bar, area). Adds `collapseGroups` on top
  * of the shared config. It is intentionally absent from the base `ChartLegendConfig` so point-based
@@ -581,6 +602,11 @@ type SeriesChartLegendConfig = ChartLegendConfig<SeriesData[]> & {
    * Pass a string to replace the default label.
    */
   comparisonItem?: boolean | string;
+  /**
+   * Append one static item per comparison series instead, named by calling this with the label
+   * of the series it is compared with, and left out while that series is hidden.
+   */
+  comparisonSeriesItems?: ComparisonItemLabel;
 };
 /**
  * Initial visibility options for charts built from labelled series.
@@ -609,6 +635,10 @@ type BaseChartProps<T = DataPoint | DataPointDate | LeaderboardEntry> = {
    * Additional CSS class name for the chart container
    */
   className?: string;
+  /**
+   * Accessible name of the chart. Name it after what it shows, and give each chart on a page a different name. Each chart type has a localized default, such as "Line chart".
+   */
+  ariaLabel?: string;
   /**
    * Width of the chart container in pixels. When omitted, the chart fills its parent's width.
    */
@@ -748,6 +778,8 @@ type BaseLegendItem = {
   seriesLabels?: string[];
   /** Set to false for a static item that cannot be toggled or dimmed. */
   interactive?: boolean;
+  /** Label of the series this static item describes; the item is left out while it is hidden. */
+  describesSeries?: string;
 };
 //#endregion
 //#region src/components/legend/legend.d.ts
@@ -775,7 +807,9 @@ interface ChartLegendOptions {
    * `options.type === 'comparison'`. Skipped when that series already has its own
    * item. Pass a string to replace the default label.
    */
-  comparisonItem?: boolean | string;
+  comparisonItem?: SeriesChartLegendConfig['comparisonItem'];
+  /** One static item per comparison series instead; see `SeriesChartLegendConfig`. */
+  comparisonSeriesItems?: SeriesChartLegendConfig['comparisonSeriesItems'];
 }
 /**
  * Hook to transform chart data into legend items
@@ -880,14 +914,14 @@ type LineChartAnnotationProps = {
   subjectType?: 'circle' | 'line-vertical' | 'line-horizontal';
   styles?: AnnotationStyles;
   testId?: string;
-  renderLabel?: FC<{
+  renderLabel?: (props: {
     title: string;
     subtitle?: string;
-  }>;
-  renderLabelPopover?: FC<{
+  }) => ReactNode;
+  renderLabelPopover?: (props: {
     title: string;
     subtitle?: string;
-  }>;
+  }) => ReactNode;
 };
 type CurveType = 'smooth' | 'linear' | 'monotone';
 type RenderLineGlyphProps<Datum extends object> = GlyphProps<Datum> & {
@@ -1215,7 +1249,7 @@ interface TooltipRenderProps {
 /**
  * Props for the ConversionFunnelChart component
  */
-interface ConversionFunnelChartProps extends Pick<BaseChartProps, 'className' | 'chartId' | 'animation'> {
+interface ConversionFunnelChartProps extends Pick<BaseChartProps, 'className' | 'chartId' | 'animation' | 'ariaLabel'> {
   /** Main conversion rate to highlight */
   mainRate: number;
   /** Change indicator (e.g., +2%, -1.5%) */
@@ -1275,7 +1309,7 @@ interface GeoChartError {
   detailedMessage?: string;
   options?: Record<string, unknown>;
 }
-interface GeoChartProps extends Pick<BaseChartProps, 'className' | 'chartId' | 'width' | 'height'> {
+interface GeoChartProps extends Pick<BaseChartProps, 'className' | 'chartId' | 'ariaLabel' | 'width' | 'height'> {
   /**
    * Data in Google Charts native format for maximum flexibility.
    * First row contains column headers, subsequent rows contain data.
@@ -1394,10 +1428,10 @@ interface HeatmapChartProps extends Omit<BaseChartProps<HeatmapColumn[]>, 'showL
    * group past the edge, Page Up/Down by one group. Default `grid`.
    */
   keyboardNavigation?: 'grid' | 'calendar';
-  /** Accessible name of the grid. Defaults to a localized "Heatmap chart". */
-  ariaLabel?: string;
   /** Compact mode: hide in-cell values, tighten gap, thin axis labels. Default false. */
   compact?: boolean;
+  /** Compact mode only: grow the cells to fill the chart's box, wrapping the column groups onto more rows when that makes them larger. Default false. */
+  fitCells?: boolean;
   /** Render the numeric value inside each cell. Default `! compact`. */
   showValues?: boolean;
   /**
@@ -1485,7 +1519,7 @@ type MonthCalendarHeatmapResult = {
 //#endregion
 //#region src/charts/heatmap-chart/private/heatmap-legend.d.ts
 interface HeatmapLegendProps {
-  /** Number of swatches in the scale. Default 5. */
+  /** Number of color swatches in the scale, not counting the empty-cell swatch. Default 5. */
   steps?: number;
   /**
    * `swatches` spaces the steps out as cell-sized squares; `bar` joins them
@@ -1550,7 +1584,12 @@ declare const useCalendarHeatmapData: (series: DataPointDate[], options?: Calend
 declare const useMonthCalendarHeatmapData: (valueByDay: Record<string, number | null>, range: MonthCalendarHeatmapRange, options?: MonthCalendarHeatmapOptions) => MonthCalendarHeatmapResult;
 //#endregion
 //#region src/charts/leaderboard-chart/types.d.ts
-interface LeaderboardChartProps extends Pick<BaseChartProps<LeaderboardEntry>, 'className' | 'data' | 'showLegend' | 'legend' | 'chartId' | 'width' | 'height' | 'size' | 'gap' | 'animation'> {
+interface LeaderboardChartProps extends Pick<BaseChartProps<LeaderboardEntry>, 'className' | 'showLegend' | 'legend' | 'chartId' | 'width' | 'height' | 'size' | 'gap' | 'animation' | 'ariaLabel'> {
+  /**
+   * Entries to display. Declared here rather than picked, since the base type
+   * would split the entry union into one array type per member.
+   */
+  data: LeaderboardEntry[];
   /**
    * Whether to show comparison data
    */
@@ -2381,5 +2420,5 @@ declare const defaultTheme: CompleteChartTheme;
  */
 declare const useChartScopeElement: () => HTMLElement | null;
 //#endregion
-export { AccessibleTooltip, type AnnotationStyles, type ArcData, AreaChartResponsive as AreaChart, type AreaChartProps, AreaChart as AreaChartUnresponsive, type AxisOptions, type BandHighlightSelection, BarChartResponsive as BarChart, type BarChartProps, BarChart as BarChartUnresponsive, BarListChartResponsive as BarListChart, type BarListChartProps, BarListChart as BarListChartUnresponsive, type BaseChartProps, type BaseLegendItem, type BaseLegendProps, BaseTooltip, type BaseTooltipProps, type BucketInfo, type CalendarHeatmapOptions, type CalendarHeatmapResult, type ChartFormatting, type ChartLegendConfig, type ChartLegendOptions, type ChartTheme, type CompleteChartTheme, ConversionFunnelChartWithProvider as ConversionFunnelChart, type ConversionFunnelChartProps, type CrosshairStyle, type CurveType, type DataPoint, type DataPointDate, type DataPointPercentage, type EventHandlerParams, type FunnelStep, GeoChartResponsive as GeoChart, type GeoChartError, type GeoChartProps, GeoChartWithProvider as GeoChartUnresponsive, type GeoData, type GeoDisplayMode, type GeoRegion, type GeoResolution, GlobalChartsContext, GlobalChartsProvider, GlobalChartsProvider as ThemeProvider, type GoogleDataTableColumn, GoogleDataTableColumnRoleType, type GoogleDataTableRow, type GradientConfig, type GradientStop, type GridStyles, type HeatmapCell, HeatmapChartResponsive as HeatmapChart, type HeatmapChartProps, HeatmapChart as HeatmapChartUnresponsive, type HeatmapColumn, type HeatmapColumnGroup, type HeatmapTooltipData, LeaderboardChartResponsive as LeaderboardChart, type LeaderboardChartProps, LeaderboardChart as LeaderboardChartUnresponsive, type LeaderboardEntry, Legend, type LegendItemStyles, type LegendLabelStyles, type LegendPosition, type LegendProps, type LegendShape, type LegendShapeLabel, type LegendShapeRenderProps, type LegendShapeStyles, type LegendValueDisplay, LineChartResponsive as LineChart, type LineChartAnnotationProps, type LineChartProps, LineChart as LineChartUnresponsive, type LineStyles, type MainMetricRenderProps, type MetricValueType, type MonthCalendarHeatmapOptions, type MonthCalendarHeatmapRange, type MonthCalendarHeatmapResult, type MultipleDataPointsDate, type Optional, type OrientationType, PieChartResponsive as PieChart, type PieChartProps, type PieChartRenderTooltipParams, PieChart as PieChartUnresponsive, PieSemiCircleChartResponsive as PieSemiCircleChart, type PieSemiCircleChartProps, type PieSemiCircleChartRenderTooltipParams, PieSemiCircleChart as PieSemiCircleChartUnresponsive, type RenderLabelProps, type RenderLineGlyphProps, type RenderTooltipGlyphProps, type RenderTooltipParams, type RenderValueProps, type ScaleOptions, type SeriesChartLegendConfig, type SeriesData, type SeriesDataOptions, type SeriesVisibilityProps, Sparkline, type SparklineDataPoint, type SparklineProps, SparklineUnresponsive, type StepLabelRenderProps, type StepRateRenderProps, type TickResolution, TooltipBox, type TooltipBoxProps, type TooltipData, type TooltipDatum, type TooltipPlacement, type TooltipProps, type TooltipRenderProps, type TrendDirection, TrendIndicator, type TrendIndicatorProps, XYChartTooltip, type XyChartTooltipProps, buildCalendarHeatmapData, buildMonthCalendarHeatmapData, defaultTheme, formatMetricValue, formatPercentage, getBucketInfo, getColorDistance, hexToRgba, isValidHexColor, lightenHexColor, mergeThemes, mixHexColors, normalizeColorToHex, parseAsLocalDate, parseHslString, prefersLightText, relativeLuminance, resolveCssVariable, useCalendarHeatmapData, useChartFormatting, useChartLegendItems, useChartRegistration, useChartScopeElement, useGlobalChartsContext, useGlobalChartsTheme, useLeaderboardLegendItems, useMonthCalendarHeatmapData, validateHexColor };
+export { AccessibleTooltip, type AnnotationStyles, type ArcData, AreaChartResponsive as AreaChart, type AreaChartProps, AreaChart as AreaChartUnresponsive, type AxisOptions, type BandHighlightSelection, BarChartResponsive as BarChart, type BarChartProps, BarChart as BarChartUnresponsive, BarListChartResponsive as BarListChart, type BarListChartProps, BarListChart as BarListChartUnresponsive, type BaseChartProps, type BaseLegendItem, type BaseLegendProps, BaseTooltip, type BaseTooltipProps, type BucketInfo, type CalendarHeatmapOptions, type CalendarHeatmapResult, type ChartFormatting, type ChartLegendConfig, type ChartLegendOptions, type ChartTheme, type ComparisonItemLabel, type CompleteChartTheme, ConversionFunnelChartWithProvider as ConversionFunnelChart, type ConversionFunnelChartProps, type CrosshairStyle, type CurveType, type DataPoint, type DataPointDate, type DataPointPercentage, type EventHandlerParams, type FunnelStep, GeoChartResponsive as GeoChart, type GeoChartError, type GeoChartProps, GeoChartWithProvider as GeoChartUnresponsive, type GeoData, type GeoDisplayMode, type GeoRegion, type GeoResolution, GlobalChartsContext, GlobalChartsProvider, GlobalChartsProvider as ThemeProvider, type GoogleDataTableColumn, GoogleDataTableColumnRoleType, type GoogleDataTableRow, type GradientConfig, type GradientStop, type GridStyles, type HeatmapCell, HeatmapChartResponsive as HeatmapChart, type HeatmapChartProps, HeatmapChart as HeatmapChartUnresponsive, type HeatmapColumn, type HeatmapColumnGroup, type HeatmapTooltipData, LeaderboardChartResponsive as LeaderboardChart, type LeaderboardChartProps, LeaderboardChart as LeaderboardChartUnresponsive, type LeaderboardEntry, Legend, type LegendItemStyles, type LegendLabelStyles, type LegendPosition, type LegendProps, type LegendShape, type LegendShapeLabel, type LegendShapeRenderProps, type LegendShapeStyles, type LegendValueDisplay, LineChartResponsive as LineChart, type LineChartAnnotationProps, type LineChartProps, LineChart as LineChartUnresponsive, type LineStyles, type MainMetricRenderProps, type MetricValueType, type MonthCalendarHeatmapOptions, type MonthCalendarHeatmapRange, type MonthCalendarHeatmapResult, type MultipleDataPointsDate, type Optional, type OrientationType, PieChartResponsive as PieChart, type PieChartProps, type PieChartRenderTooltipParams, PieChart as PieChartUnresponsive, PieSemiCircleChartResponsive as PieSemiCircleChart, type PieSemiCircleChartProps, type PieSemiCircleChartRenderTooltipParams, PieSemiCircleChart as PieSemiCircleChartUnresponsive, type RenderLabelProps, type RenderLineGlyphProps, type RenderTooltipGlyphProps, type RenderTooltipParams, type RenderValueProps, type ScaleOptions, type SeriesChartLegendConfig, type SeriesData, type SeriesDataOptions, type SeriesVisibilityProps, Sparkline, type SparklineDataPoint, type SparklineProps, SparklineUnresponsive, type StepLabelRenderProps, type StepRateRenderProps, type TickResolution, TooltipBox, type TooltipBoxProps, type TooltipData, type TooltipDatum, type TooltipPlacement, type TooltipProps, type TooltipRenderProps, type TrendDirection, TrendIndicator, type TrendIndicatorProps, XYChartTooltip, type XyChartTooltipProps, buildCalendarHeatmapData, buildMonthCalendarHeatmapData, defaultTheme, formatMetricValue, formatPercentage, getBucketInfo, getColorDistance, hexToRgba, isValidHexColor, lightenHexColor, mergeThemes, mixHexColors, normalizeColorToHex, parseAsLocalDate, parseHslString, prefersLightText, relativeLuminance, resolveCssVariable, useCalendarHeatmapData, useChartFormatting, useChartLegendItems, useChartRegistration, useChartScopeElement, useGlobalChartsContext, useGlobalChartsTheme, useLeaderboardLegendItems, useMonthCalendarHeatmapData, validateHexColor };
 //# sourceMappingURL=index.d.ts.map