@automattic/charts 4.6.0 → 4.8.0

package/dist/index.css

@@ -1,4 +1,4 @@
-:where(.a8c-charts-scope) {
+:where(.a8c-charts-scope, .a8c-charts-tooltip-scope) {
   --a8c-charts-color-series-1: var(--wp-admin-theme-color, var(--wpds-color-foreground-interactive-brand, var(--wp-admin-theme-color, #3858e9)));
   --a8c-charts-color-grid: var(--wpds-color-stroke-surface-neutral, #dbdbdb);
   --a8c-charts-color-axis-x: var(--wpds-color-stroke-surface-neutral, #dbdbdb);
@@ -18,7 +18,7 @@
   --a8c-charts-color-surface: var(--wpds-color-background-surface-neutral-strong, #fff);
   --a8c-charts-color-surface-secondary: var(--wpds-color-background-surface-neutral-weak, #f4f4f4);
   --a8c-charts-color-track: var(--wpds-color-background-track-neutral-weak, #f0f0f0);
-  --a8c-charts-color-tooltip-surface: #000000d9;
+  --a8c-charts-color-tooltip-surface: #1e1e1e;
   --a8c-charts-color-zoom-selection: var(--wpds-color-background-interactive-brand-strong, var(--wp-admin-theme-color, #3858e9));
   --a8c-charts-color-zoom-selection-stroke: var(--wpds-color-stroke-interactive-brand, var(--wp-admin-theme-color, #3858e9));
   --a8c-charts-elevation-xs: 0 1px 1px 0 #00000008,
@@ -32,6 +32,7 @@
   --a8c-charts-motion-duration-entrance: var(--wpds-motion-duration-xl, .4s);
   --a8c-charts-motion-easing-entrance: var(--wpds-motion-easing-expressive, cubic-bezier(.25, 0, 0, 1));
   --a8c-charts-border-radius-bar: var(--wpds-border-radius-md, 4px);
+  --a8c-charts-border-radius-bar-chart: 0;
   --a8c-charts-border-radius-cell: var(--wpds-border-radius-sm, 2px);
   --a8c-charts-border-radius-leaderboard-bar: 9999px;
   --a8c-charts-dimension-leaderboard-row-gap: var(--wpds-dimension-gap-md, 12px);
@@ -39,7 +40,7 @@
 }
 
 @media (forced-colors: active) {
-  :where(.a8c-charts-scope) {
+  :where(.a8c-charts-scope, .a8c-charts-tooltip-scope) {
     --a8c-charts-color-label-axis: CanvasText;
     --a8c-charts-color-grid: GrayText;
     --a8c-charts-color-axis-x: GrayText;
@@ -104,19 +105,23 @@
   font-weight: var(--wpds-typography-font-weight-emphasis, 600);
   flex-shrink: 0;
 }
-.a8ccharts--zY0xG-surface, .a8ccharts--zY0xG-tooltip {
-  padding: var(--wpds-dimension-padding-sm, 8px);
-  background-color: var(--a8c-charts-color-tooltip-surface, #000000d9);
-  color: #fff;
+.a8ccharts-ddpU1W-surface {
+  padding: var(--wpds-dimension-padding-xs, 4px) var(--wpds-dimension-padding-sm, 8px);
+  background-color: var(--a8c-charts-color-surface);
+  color: var(--a8c-charts-color-label);
   border-radius: var(--wpds-border-radius-md, 4px);
-  font-size: var(--wpds-typography-font-size-md, 13px);
+  font-family: var(--wpds-typography-font-family-body, -apple-system, system-ui, "Segoe UI", "Roboto", "Oxygen-Sans", "Ubuntu", "Cantarell", "Helvetica Neue", sans-serif);
+  font-size: var(--wpds-typography-font-size-sm, 12px);
   box-shadow: var(--a8c-charts-elevation-sm, 0 1px 2px 0 #0000000d, 0 2px 3px 0 #0000000a, 0 6px 6px 0 #00000008, 0 8px 8px 0 #00000005);
   pointer-events: none;
+  min-width: fit-content;
+  line-height: 1.4;
 }
 
-.a8ccharts--zY0xG-tooltip {
-  position: absolute;
-  transform: translate(-50%, -100%);
+@media (forced-colors: active) {
+  .a8ccharts-ddpU1W-surface {
+    border: var(--wpds-border-width-xs, 1px) solid CanvasText;
+  }
 }
 .a8ccharts-fpNVAq-chart-layout__content {
   flex: 1;
@@ -191,7 +196,7 @@
   overflow: visible;
 }
 
-.a8ccharts-inuQka-line-chart__tooltip, .a8ccharts-inuQka-line-chart__annotation-label-popover {
+.a8ccharts-inuQka-line-chart__annotation-label-popover {
   background: var(--a8c-charts-color-surface);
   color: var(--a8c-charts-color-label);
   padding: var(--wpds-dimension-padding-sm, 8px);
@@ -202,10 +207,6 @@
   padding-bottom: var(--wpds-dimension-padding-md, 12px);
 }
 
-.a8ccharts-inuQka-line-chart__tooltip-row {
-  padding: var(--wpds-dimension-padding-xs, 4px) 0;
-}
-
 .a8ccharts-inuQka-line-chart__tooltip-label {
   font-weight: var(--wpds-typography-font-weight-emphasis, 600);
   padding-right: var(--wpds-dimension-padding-lg, 16px);
@@ -305,6 +306,10 @@
   overflow: visible;
 }
 
+.a8ccharts-97yN9W-bar-chart .visx-bar, .a8ccharts-97yN9W-bar-chart .bar-chart__comparison-bar {
+  rx: var(--a8c-charts-border-radius-bar-chart);
+}
+
 .a8ccharts-97yN9W-bar-chart--animated rect {
   transform-origin: bottom;
   transform-box: fill-box;
@@ -445,13 +450,6 @@
   }
 }
 
-.a8ccharts-mGEVca-tooltip-wrapper {
-  background: var(--a8c-charts-color-surface);
-  border-radius: var(--wpds-border-radius-md, 4px) !important;
-  padding: var(--wpds-dimension-padding-md, 12px) !important;
-  box-shadow: var(--a8c-charts-elevation-sm, 0 1px 2px 0 #0000000d, 0 2px 3px 0 #0000000a, 0 6px 6px 0 #00000008, 0 8px 8px 0 #00000005) !important;
-}
-
 .a8ccharts-mGEVca-tooltip-title {
   color: var(--a8c-charts-color-label);
   font-size: var(--wpds-typography-font-size-sm, 12px);
@@ -605,7 +603,7 @@
 }
 
 .a8ccharts-O3YMOW-heatmap-chart__cell--filled {
-  background: color-mix(in sRGB, var(--a8c-charts-color-heatmap-primary) calc((.15 + .85 * var(--a8c-charts-heatmap-cell-intensity)) * 100%), var(--a8c-charts-color-background, #fff));
+  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__cell--selected {
@@ -618,10 +616,18 @@
   font-size: var(--wpds-typography-font-size-md, 13px);
 }
 
-.a8ccharts-O3YMOW-heatmap-chart__cell--strong .a8ccharts-O3YMOW-heatmap-chart__cell-value {
+.a8ccharts-O3YMOW-heatmap-chart__cell-value--inverse {
   color: var(--a8c-charts-color-label-inverse);
 }
 
+.a8ccharts-O3YMOW-heatmap-chart__cell-value--black {
+  color: #000;
+}
+
+.a8ccharts-O3YMOW-heatmap-chart__cell-value--white {
+  color: #fff;
+}
+
 .a8ccharts-O3YMOW-heatmap-chart__legend-label {
   color: var(--a8c-charts-color-label);
 }
@@ -630,7 +636,7 @@
   width: var(--wpds-dimension-size-3xs, 12px);
   height: var(--wpds-dimension-size-3xs, 12px);
   border-radius: var(--a8c-charts-border-radius-cell);
-  background: color-mix(in sRGB, var(--a8c-charts-color-heatmap-primary) calc((.15 + .85 * var(--a8c-charts-heatmap-cell-intensity)) * 100%), var(--a8c-charts-color-background, #fff));
+  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-scale--bar {
@@ -854,6 +860,14 @@
 .a8ccharts-gnszbG-pie-chart__label-text--on-light {
   fill: var(--a8c-charts-color-label, #1e1e1e);
 }
+
+.a8ccharts-gnszbG-pie-chart__label-text--black {
+  fill: #000;
+}
+
+.a8ccharts-gnszbG-pie-chart__label-text--white {
+  fill: #fff;
+}
 .a8ccharts-YtTOxW-pie-semi-circle-chart__plot {
   position: relative;
 }

package/dist/index.d.cts

@@ -4,7 +4,7 @@ import { AxisRendererProps, AxisScale, Orientation, TickFormatter } from "@visx/
 import { PickD3Scale, ScaleInput, ScaleType } from "@visx/scale";
 import { TextProps } from "@visx/text";
 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, 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 { TooltipProps as TooltipProps$1, UseTooltipPortalOptions } from "@visx/tooltip";
 import { PieProvidedProps } from "@visx/shape";
 //#region src/types.d.ts
@@ -829,7 +829,7 @@ type XyChartTooltipProps<Datum extends object> = {
   tooltipPlacement?: TooltipPlacement;
   /** Override the tooltip top anchor in SVG coordinates, including negative offsets. */
   tooltipAnchorTop?: number;
-  /** Merge overrides with the default box styles; use `unstyled` to strip the box styling. */
+  /** Inline overrides on the tooltip surface; `unstyled` drops both. */
   style?: TooltipProps$1['style'];
   snapTooltipToDatumX?: boolean;
   snapTooltipToDatumY?: boolean;
@@ -1209,6 +1209,7 @@ interface TooltipRenderProps {
   index: number;
   top: number;
   left: number;
+  /** @deprecated The tooltip box draws the package surface; this is no longer set. */
   className?: string;
 }
 /**
@@ -1235,6 +1236,8 @@ interface ConversionFunnelChartProps extends Pick<BaseChartProps, 'className' |
   renderMainMetric?: (props: MainMetricRenderProps) => React.ReactNode;
   /** Custom render function for tooltip content */
   renderTooltip?: (props: TooltipRenderProps) => React.ReactNode;
+  /** Inline styles merged over the tooltip box defaults. */
+  tooltipStyle?: React.CSSProperties;
 }
 //#endregion
 //#region src/charts/conversion-funnel-chart/conversion-funnel-chart.d.ts
@@ -1325,7 +1328,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;
@@ -1419,18 +1422,15 @@ 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;
-  /**
-   * The tooltip box: `light` is the plain white box, `dark` the package's
-   * tooltip surface, themed through `--a8c-charts-color-tooltip-surface`.
-   * Default `light`.
-   */
+  /** @deprecated Every tooltip draws on the package tooltip surface; this prop has no effect. */
   tooltipVariant?: 'light' | 'dark';
-  /** Inline styles merged onto the tooltip box, over the variant's own. */
+  /** Inline styles merged onto the tooltip box, over the surface's own. */
   tooltipStyle?: CSSProperties;
   children?: ReactNode;
 }
@@ -1788,7 +1788,8 @@ declare const relativeLuminance: (hex: string) => number;
  * Whether light text reads better than dark text on the given background, using the W3C
  * luminance threshold (0.179) that maximizes contrast against black vs white.
  *
- * @param backgroundHex - Hex background color
+ * @deprecated Assumes black and white text, so it ignores label role overrides and cannot guarantee AA; charts no longer use it, and it will be removed in a future major version.
+ * @param      backgroundHex - Hex background color
  * @return true if light text should be used; false (dark text) for malformed colors
  */
 declare const prefersLightText: (backgroundHex: string) => boolean;
@@ -1932,7 +1933,7 @@ 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;
 }
@@ -1998,7 +1999,7 @@ 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;
 }
@@ -2119,30 +2120,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 +2165,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 +2210,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
 /**
@@ -2232,7 +2272,7 @@ type TrendIndicatorProps = {
  * @param {TrendIndicatorProps} props - Component props
  * @return {JSX.Element} The rendered trend indicator
  */
-declare function TrendIndicator({ direction, value, className, style, showIcon }: TrendIndicatorProps): import("react").JSX.Element;
+declare function TrendIndicator({ direction, value, className, style, showIcon }: TrendIndicatorProps): JSX.Element;
 //#endregion
 //#region src/providers/chart-context/types.d.ts
 interface ChartRegistration {
@@ -2341,5 +2381,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.cts.map

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, 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";
@@ -829,7 +829,7 @@ type XyChartTooltipProps<Datum extends object> = {
   tooltipPlacement?: TooltipPlacement;
   /** Override the tooltip top anchor in SVG coordinates, including negative offsets. */
   tooltipAnchorTop?: number;
-  /** Merge overrides with the default box styles; use `unstyled` to strip the box styling. */
+  /** Inline overrides on the tooltip surface; `unstyled` drops both. */
   style?: TooltipProps$1['style'];
   snapTooltipToDatumX?: boolean;
   snapTooltipToDatumY?: boolean;
@@ -1209,6 +1209,7 @@ interface TooltipRenderProps {
   index: number;
   top: number;
   left: number;
+  /** @deprecated The tooltip box draws the package surface; this is no longer set. */
   className?: string;
 }
 /**
@@ -1235,6 +1236,8 @@ interface ConversionFunnelChartProps extends Pick<BaseChartProps, 'className' |
   renderMainMetric?: (props: MainMetricRenderProps) => React.ReactNode;
   /** Custom render function for tooltip content */
   renderTooltip?: (props: TooltipRenderProps) => React.ReactNode;
+  /** Inline styles merged over the tooltip box defaults. */
+  tooltipStyle?: React.CSSProperties;
 }
 //#endregion
 //#region src/charts/conversion-funnel-chart/conversion-funnel-chart.d.ts
@@ -1325,7 +1328,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;
@@ -1419,18 +1422,15 @@ 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;
-  /**
-   * The tooltip box: `light` is the plain white box, `dark` the package's
-   * tooltip surface, themed through `--a8c-charts-color-tooltip-surface`.
-   * Default `light`.
-   */
+  /** @deprecated Every tooltip draws on the package tooltip surface; this prop has no effect. */
   tooltipVariant?: 'light' | 'dark';
-  /** Inline styles merged onto the tooltip box, over the variant's own. */
+  /** Inline styles merged onto the tooltip box, over the surface's own. */
   tooltipStyle?: CSSProperties;
   children?: ReactNode;
 }
@@ -1788,7 +1788,8 @@ declare const relativeLuminance: (hex: string) => number;
  * Whether light text reads better than dark text on the given background, using the W3C
  * luminance threshold (0.179) that maximizes contrast against black vs white.
  *
- * @param backgroundHex - Hex background color
+ * @deprecated Assumes black and white text, so it ignores label role overrides and cannot guarantee AA; charts no longer use it, and it will be removed in a future major version.
+ * @param      backgroundHex - Hex background color
  * @return true if light text should be used; false (dark text) for malformed colors
  */
 declare const prefersLightText: (backgroundHex: string) => boolean;
@@ -1932,7 +1933,7 @@ 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;
 }
@@ -1998,7 +1999,7 @@ 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;
 }
@@ -2119,30 +2120,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 +2165,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 +2210,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
 /**
@@ -2232,7 +2272,7 @@ type TrendIndicatorProps = {
  * @param {TrendIndicatorProps} props - Component props
  * @return {JSX.Element} The rendered trend indicator
  */
-declare function TrendIndicator({ direction, value, className, style, showIcon }: TrendIndicatorProps): import("react").JSX.Element;
+declare function TrendIndicator({ direction, value, className, style, showIcon }: TrendIndicatorProps): JSX.Element;
 //#endregion
 //#region src/providers/chart-context/types.d.ts
 interface ChartRegistration {
@@ -2341,5 +2381,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