@automattic/charts 4.7.0 → 4.9.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { EventHandlerParams, EventHandlerParams as EventHandlerParams$1, GlyphProps, GridStyles, GridStyles as GridStyles$1, LineStyles, LineStyles as LineStyles$1, TooltipContextType } from "@visx/xychart";
-import { CSSProperties, ComponentClass, ComponentProps, ComponentType, FC, JSX, MouseEvent, PointerEvent, PropsWithChildren, ReactElement, ReactNode, SVGProps } from "react";
+import { CSSProperties, ComponentClass, ComponentProps, ComponentType, FC, HTMLAttributes, JSX, MouseEvent, PointerEvent, PropsWithChildren, ReactElement, ReactNode, SVGProps } from "react";
 import { TextProps } from "@visx/text";
 import { TooltipProps as TooltipProps$1, UseTooltipPortalOptions } from "@visx/tooltip";
 import { PickD3Scale, ScaleInput, ScaleType } from "@visx/scale";
@@ -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;
@@ -880,14 +893,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> & {
@@ -895,6 +908,8 @@ type RenderLineGlyphProps<Datum extends object> = GlyphProps<Datum> & {
   position?: 'start' | 'end';
 };
 interface LineChartProps extends BaseChartProps<SeriesData[]>, SeriesVisibilityProps {
+  /** Accessible name of the chart. Defaults to a localized "Line chart". */
+  ariaLabel?: string;
   /**
    * Legend configuration. Supports `collapseGroups` on top of the shared options.
    */
@@ -950,6 +965,8 @@ type TooltipDatum = {
 //#endregion
 //#region src/charts/area-chart/types.d.ts
 interface AreaChartProps extends BaseChartProps<SeriesData[]>, SeriesVisibilityProps {
+  /** Accessible name of the chart. Defaults to a localized "Area chart". */
+  ariaLabel?: string;
   /**
    * Legend configuration. Supports `collapseGroups` on top of the shared options.
    */
@@ -1059,6 +1076,8 @@ type BandHighlightSelection = {
   height: number;
 };
 interface BarChartProps extends BaseChartProps<SeriesData[]>, SeriesVisibilityProps {
+  /** Accessible name of the chart. Defaults to a localized "Bar chart". */
+  ariaLabel?: string;
   /**
    * Legend configuration. Supports `collapseGroups` on top of the shared options.
    */
@@ -1328,7 +1347,7 @@ declare const GeoChartResponsive: ({ resizeDebounceTime, maxWidth, aspectRatio,
 } & ResponsiveConfig) => import("react").JSX.Element;
 //#endregion
 //#region src/charts/heatmap-chart/types.d.ts
-/** A single heatmap cell. `value: null` marks an empty cell. */
+/** A single heatmap cell. `value: null` marks an empty cell, as does a zero when no value is negative. */
 type HeatmapCell = {
   /** Per-cell label used in the tooltip / accessible name. */
   label?: string;
@@ -1398,6 +1417,8 @@ interface HeatmapChartProps extends Omit<BaseChartProps<HeatmapColumn[]>, 'showL
   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;
   /**
@@ -1422,8 +1443,9 @@ interface HeatmapChartProps extends Omit<BaseChartProps<HeatmapColumn[]>, 'showL
   /** Floor a cell's height (px) in non-compact mode; see `minCellWidth`. */
   minCellHeight?: number;
   /**
-   * Color the cell scale interpolates toward at the highest value. Defaults to the
-   * first series palette slot, `--a8c-charts-color-series-1`.
+   * Color the cell scale is built from, deepened at the highest value toward 9:1
+   * against the background. Defaults to the first series palette slot,
+   * `--a8c-charts-color-series-1`.
    */
   primaryColor?: string;
   renderTooltip?: (data: HeatmapTooltipData) => ReactNode;
@@ -1484,7 +1506,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
@@ -1549,7 +1571,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'> {
+  /**
+   * 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
    */
@@ -1932,9 +1959,13 @@ interface PieChartProps extends BaseChartProps<DataPointPercentage[]> {
   tooltipOffsetY?: number;
   /**
    * Custom render function for tooltip content.
-   * When provided, replaces the default BaseTooltip with custom content.
+   * When provided, replaces the default `label: value` tooltip with custom content.
    */
   renderTooltip?: (params: PieChartRenderTooltipParams) => ReactNode;
+  /**
+   * Accessible name of the chart. Defaults to a localized "Pie chart".
+   */
+  ariaLabel?: string;
 }
 type PieChartBaseProps = Optional<PieChartProps, 'size'>;
 type PieChartComponent = ChartComponentWithComposition<PieChartBaseProps>;
@@ -1998,9 +2029,13 @@ interface PieSemiCircleChartProps extends BaseChartProps<DataPointPercentage[]>
   tooltipOffsetY?: number;
   /**
    * Custom render function for tooltip content.
-   * When provided, replaces the default BaseTooltip with custom content.
+   * When provided, replaces the default `label: value` tooltip with custom content.
    */
   renderTooltip?: (params: PieSemiCircleChartRenderTooltipParams) => ReactNode;
+  /**
+   * Accessible name of the chart. Defaults to a localized "Semi-circle chart".
+   */
+  ariaLabel?: string;
 }
 type PieSemiCircleChartBaseProps = Optional<PieSemiCircleChartProps, 'width'>;
 type PieSemiCircleChartComponent = ChartComponentWithComposition<PieSemiCircleChartBaseProps>;
@@ -2119,30 +2154,42 @@ declare const Sparkline: ({ resizeDebounceTime, maxWidth, aspectRatio, size, wid
   size?: number;
 } & ResponsiveConfig) => import("react").JSX.Element;
 //#endregion
-//#region src/components/tooltip/base-tooltip.d.ts
+//#region src/components/tooltip/types.d.ts
+type TooltipProps = {
+  data: {
+    label: string;
+    value: number;
+  };
+};
 type TooltipData = {
   label: string;
   value: number;
   valueDisplay?: string;
 };
+//#endregion
+//#region src/components/tooltip/base-tooltip.d.ts
 type TooltipComponentProps = {
   data: TooltipData;
   className?: string;
 };
 type TooltipCommonProps = {
-  top: number;
-  left: number;
+  /** @deprecated Position the box with `style`, or use `TooltipBox`. */
+  top?: number;
+  /** @deprecated Position the box with `style`, or use `TooltipBox`. */
+  left?: number;
   style?: CSSProperties;
   className?: string;
   /**
    * Whether to render the tooltip container div. When false, only renders the content.
-   * Useful when the tooltip is rendered inside a portal or custom container.
+   * @deprecated Render the content directly; `TooltipBox` draws the box.
    * @default true
    */
   renderContainer?: boolean;
 };
 type DefaultDataTooltip = {
+  /** @deprecated Pass the content as children, or use `TooltipBox`. */
   data: TooltipData;
+  /** @deprecated Pass the content as children, or use `TooltipBox`. */
   component?: ComponentType<TooltipComponentProps>;
   children?: never;
 };
@@ -2152,16 +2199,31 @@ type CustomTooltip = {
   component?: never;
 };
 type BaseTooltipProps = TooltipCommonProps & (DefaultDataTooltip | CustomTooltip);
+/**
+ * A tooltip box with children or `label: value` content. Prefer `TooltipBox`.
+ *
+ * @param props                 - Tooltip props.
+ * @param props.data            - Data for the default content.
+ * @param props.top             - Deprecated vertical position.
+ * @param props.left            - Deprecated horizontal position.
+ * @param props.component       - Deprecated content component.
+ * @param props.children        - Tooltip content.
+ * @param props.className       - Class name passed to the content component.
+ * @param props.style           - Styles for the box.
+ * @param props.renderContainer - Deprecated; render the content alone when false.
+ * @return The tooltip.
+ */
 declare const BaseTooltip: ({ data, top, left, component: Component, children, className, style, renderContainer }: BaseTooltipProps) => string | number | true | import("react").JSX.Element | Iterable<ReactNode>;
 //#endregion
-//#region src/components/tooltip/accessible-tooltip.d.ts
+//#region src/components/tooltip/xy-chart-tooltip.d.ts
 type FlattenedTooltipData = {
   datum: DataPointDate;
   seriesLabel: string;
   seriesIndex: number;
   dataPointIndex: number;
 };
-interface AccessibleTooltipProps extends Omit<XyChartTooltipProps<DataPointDate>, 'renderTooltip'> {
+/** The XY chart tooltip that LineChart, AreaChart and BarChart render; place it inside a visx `XYChart`. */
+interface XYChartTooltipProps extends Omit<XyChartTooltipProps<DataPointDate>, 'renderTooltip'> {
   renderTooltip?: (params: RenderTooltipParams<DataPointDate>) => ReactNode;
   selectedIndex?: number | undefined;
   tooltipRef?: (element: HTMLDivElement | null) => void;
@@ -2182,15 +2244,27 @@ interface AccessibleTooltipProps extends Omit<XyChartTooltipProps<DataPointDate>
    */
   mode?: 'individual' | 'group';
 }
-declare const AccessibleTooltip: React.FC<AccessibleTooltipProps>;
+declare const XYChartTooltip: React.FC<XYChartTooltipProps>;
+/** @deprecated Use `XYChartTooltip`. */
+declare const AccessibleTooltip: import("react").FC<XYChartTooltipProps>;
 //#endregion
-//#region src/components/tooltip/types.d.ts
-type TooltipProps = {
-  data: {
-    label: string;
-    value: number;
-  };
+//#region src/components/tooltip/tooltip-box.d.ts
+type TooltipBoxProps = HTMLAttributes<HTMLDivElement> & {
+  /** Drop the chart surface, scope class and dark theme, leaving a bare box. */
+  unstyled?: boolean;
 };
+/**
+ * The chart tooltip box: the dark surface every chart tooltip draws. It does not position itself; place it with `style` or a wrapper.
+ *
+ * @param props          - Div attributes, plus `unstyled`.
+ * @param props.unstyled - Drop the surface, scope class and theme.
+ * @param ref            - Forwarded to the box element.
+ * @return The tooltip box.
+ */
+declare const TooltipBox: import("react").ForwardRefExoticComponent<HTMLAttributes<HTMLDivElement> & {
+  /** Drop the chart surface, scope class and dark theme, leaving a bare box. */
+  unstyled?: boolean;
+} & import("react").RefAttributes<HTMLDivElement>>;
 //#endregion
 //#region src/components/trend-indicator/types.d.ts
 /**
@@ -2341,5 +2415,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, type TooltipData, type TooltipDatum, type TooltipPlacement, type TooltipProps, type TooltipRenderProps, type TrendDirection, TrendIndicator, type TrendIndicatorProps, 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 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