@automattic/charts 4.1.0 → 4.2.0

package/dist/index.css

@@ -37,6 +37,15 @@
   --a8c-charts-dimension-leaderboard-row-gap: var(--wpds-dimension-gap-md, 12px);
   --a8c-charts-dimension-leaderboard-column-gap: var(--wpds-dimension-gap-xs, 4px);
 }
+
+@media (forced-colors: active) {
+  :where(.a8c-charts-scope) {
+    --a8c-charts-color-label-axis: CanvasText;
+    --a8c-charts-color-grid: GrayText;
+    --a8c-charts-color-axis-x: GrayText;
+    --a8c-charts-color-tick-x: GrayText;
+  }
+}
 .a8ccharts-04TogW-legend {
   align-self: stretch;
 }
@@ -95,7 +104,7 @@
   font-weight: var(--wpds-typography-font-weight-emphasis, 600);
   flex-shrink: 0;
 }
-.a8ccharts--zY0xG-tooltip {
+.a8ccharts--zY0xG-surface, .a8ccharts--zY0xG-tooltip {
   padding: var(--wpds-dimension-padding-sm, 8px);
   background-color: var(--a8c-charts-color-tooltip-surface, #000000d9);
   color: #fff;
@@ -103,6 +112,9 @@
   font-size: var(--wpds-typography-font-size-md, 13px);
   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;
+}
+
+.a8ccharts--zY0xG-tooltip {
   position: absolute;
   transform: translate(-50%, -100%);
 }
@@ -470,6 +482,7 @@
   white-space: nowrap;
 }
 .a8ccharts-O3YMOW-heatmap-chart {
+  isolation: isolate;
   width: 100%;
   height: 100%;
   min-height: 0;
@@ -507,6 +520,11 @@
   min-height: 0;
 }
 
+.a8ccharts-O3YMOW-heatmap-chart__grid--flex-gaps {
+  width: 100%;
+  min-width: max-content;
+}
+
 .a8ccharts-O3YMOW-heatmap-chart__grid--height-capped {
   flex: none;
   height: max-content;
@@ -520,6 +538,7 @@
 .a8ccharts-O3YMOW-heatmap-chart__col-label, .a8ccharts-O3YMOW-heatmap-chart__row-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);
   white-space: nowrap;
   overflow: visible;
 }
@@ -529,6 +548,15 @@
   align-self: end;
 }
 
+.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);
+  white-space: nowrap;
+  text-align: center;
+  padding-block-start: var(--wpds-dimension-padding-xs, 4px);
+}
+
 .a8ccharts-O3YMOW-heatmap-chart__row-label {
   text-align: right;
   place-self: center end;
@@ -604,6 +632,16 @@
   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));
 }
+
+.a8ccharts-O3YMOW-heatmap-chart__legend-scale--bar {
+  border-radius: var(--a8c-charts-border-radius-cell);
+  overflow: hidden;
+}
+
+.a8ccharts-O3YMOW-heatmap-chart__legend-scale--bar .a8ccharts-O3YMOW-heatmap-chart__legend-swatch {
+  width: var(--wpds-dimension-size-sm, 24px);
+  border-radius: 0;
+}
 .a8ccharts-GovfoW-leaderboardChart {
   transition: opacity var(--wpds-motion-duration-lg, .3s) var(--wpds-motion-easing-subtle, cubic-bezier(.15, 0, .15, 1));
 }

package/dist/index.d.cts

@@ -91,6 +91,7 @@ type ThemeAnnotationStyles = {
 type DataPoint = {
   label: string;
   value: number;
+  color?: string;
 };
 /**
  * Data format for GeoChart - uses Google Charts native data format for maximum flexibility.
@@ -140,6 +141,7 @@ type DataPointDate = {
   dateString?: string;
   value: number | null;
   label?: string;
+  color?: string;
 };
 type LeaderboardEntry = {
   /**
@@ -348,6 +350,8 @@ type ChartTheme = {
     compactCellGap?: number;
     /** Fixed square cell size in px for compact mode */
     compactCellSize?: number;
+    /** Gap in px between adjacent column groups; in compact mode the minimum, as the gaps share leftover width */
+    groupGap?: number;
   };
 };
 /**
@@ -792,7 +796,7 @@ interface RenderTooltipGlyphProps<Datum extends object> extends GlyphProps<Datum
   glyphStyle?: SVGProps<SVGCircleElement>;
   isNearestDatum: boolean;
 }
-type TooltipPlacement = 'auto' | 'below-axis';
+type TooltipPlacement = 'auto' | 'below-axis' | 'beside';
 type CrosshairPaintProperty = 'stroke' | 'strokeWidth' | 'strokeOpacity' | 'strokeDasharray' | 'strokeLinecap' | 'opacity';
 type CrosshairStyle = Pick<SVGProps<SVGLineElement>, CrosshairPaintProperty> & {
   className?: string;
@@ -802,11 +806,13 @@ type XyChartTooltipProps<Datum extends object> = {
   renderTooltip: (params: RenderTooltipParams<Datum>) => ReactNode;
   renderGlyph?: (params: RenderTooltipGlyphProps<Datum>) => ReactNode;
   /**
-   * Keep the panel below the x-axis label band, centered at the datum x and horizontally clamped.
-   * Vertical bounds do not move this placement; clipping ancestors can still cut it off.
+   * Use below-axis placement for centered axis anchoring, or beside placement to avoid vertical flipping.
+   * Below-axis ignores vertical bounds; beside placement clamps to them.
    * @default 'auto'
    */
   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. */
   style?: TooltipProps$1['style'];
   snapTooltipToDatumX?: boolean;
@@ -823,7 +829,7 @@ type XyChartTooltipProps<Datum extends object> = {
    * that clips its overflow, or the viewport when there is none. The box may
    * leave the chart wrapper. (It used to keep a body-level portal inside the
    * viewport.)
-   * Ignored by `below-axis`.
+   * Non-auto placements always apply their own bounds handling.
    * @default true
    */
   detectBounds?: boolean;
@@ -887,7 +893,7 @@ interface LineChartProps extends BaseChartProps<SeriesData[]>, SeriesVisibilityP
    * Place the panel below the x-axis tick labels with a pointer at the datum x; horizontal bounds still apply.
    * @default 'auto'
    */
-  tooltipPlacement?: XyChartTooltipProps<DataPointDate>['tooltipPlacement'];
+  tooltipPlacement?: 'auto' | 'below-axis';
   /**
    * Inline container styles; see Below-Axis Tooltips in stories/index.docs.mdx for content color overrides.
    */
@@ -1026,15 +1032,30 @@ declare const AreaChart: AreaChartComponent;
 declare const AreaChartResponsive: AreaChartResponsiveComponent;
 //#endregion
 //#region src/charts/bar-chart/bar-chart.d.ts
+type BandHighlightSelection = {
+  datum: DataPointDate;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+};
 interface BarChartProps extends BaseChartProps<SeriesData[]>, SeriesVisibilityProps {
   /**
    * Legend configuration. Supports `collapseGroups` on top of the shared options.
    */
   legend?: SeriesChartLegendConfig;
   renderTooltip?: (params: RenderTooltipParams<DataPointDate>) => ReactNode;
+  /** Place the tooltip beside its category without vertical flipping. */
+  tooltipPlacement?: 'auto' | 'beside';
+  /** Tooltip top anchor in SVG coordinates; negative offsets are supported. */
+  tooltipAnchorTop?: number;
   orientation?: 'horizontal' | 'vertical';
   withPatterns?: boolean;
   showZeroValues?: boolean;
+  /** Highlight the active band across the plot when tooltips are enabled. */
+  withBandHighlight?: boolean;
+  /** Receive active band bounds in SVG coordinates, or null when dismissed. */
+  onBandHighlightChange?: (selection: BandHighlightSelection | null) => void;
   children?: ReactNode;
 }
 type BarChartBaseProps = Optional<BarChartProps, 'width' | 'height' | 'size'>;
@@ -1296,10 +1317,18 @@ type HeatmapColumn = {
    */
   summary?: boolean;
 };
+/** A run of consecutive columns sharing one label beneath the grid. */
+type HeatmapColumnGroup = {
+  label: string;
+  /** Columns covered; a positive integer. */
+  span: number;
+};
 type HeatmapTooltipData = {
   value: number | null;
   rowLabel?: string;
   columnLabel?: string;
+  /** Label of the column group the cell falls in, if any. */
+  groupLabel?: string;
   cellLabel?: string;
   row: number;
   column: number;
@@ -1307,6 +1336,22 @@ type HeatmapTooltipData = {
 interface HeatmapChartProps extends Omit<BaseChartProps<HeatmapColumn[]>, 'showLegend' | 'legend' | 'gridVisibility'> {
   /** y-axis labels by row index. Empty entries render blank. */
   rowLabels?: string[];
+  /**
+   * Consecutive runs of columns sharing one label beneath the grid, set one
+   * group gap apart. Runs from the first column; columns past the last group
+   * stay ungrouped. Ignored, with a warning, when a span is not a positive
+   * integer or the spans reach past the last column.
+   */
+  columnGroups?: HeatmapColumnGroup[];
+  /**
+   * How the arrow keys move the selection. `grid` steps across the whole grid.
+   * `calendar` reads each column group as a page: Left/Right by one cell (wrapping
+   * to the next row, then the next group), Up/Down by one row into the neighboring
+   * 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;
   /** Render the numeric value inside each cell. Default `! compact`. */
@@ -1338,10 +1383,16 @@ interface HeatmapChartProps extends Omit<BaseChartProps<HeatmapColumn[]>, 'showL
    */
   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`.
+   */
+  tooltipVariant?: 'light' | 'dark';
+  /** Inline styles merged onto the tooltip box, over the variant's own. */
+  tooltipStyle?: CSSProperties;
   children?: ReactNode;
 }
-//#endregion
-//#region src/charts/heatmap-chart/private/build-calendar-data.d.ts
 type CalendarHeatmapResult = {
   data: HeatmapColumn[];
   rowLabels: string[];
@@ -1372,19 +1423,34 @@ type CalendarHeatmapOptions = {
    */
   timeZone?: string;
 };
-/**
- * Lay a day-bucketed series out as calendar columns.
- *
- * @param series  - Points to bucket.
- * @param options - Grid shape, plus the locale and zone to read days in.
- * @return Columns and row labels for `HeatmapChart`.
- */
-declare const buildCalendarHeatmapData: (series: DataPointDate[], options?: CalendarHeatmapOptions) => CalendarHeatmapResult;
+type MonthCalendarHeatmapRange = {
+  /** First measured day, `yyyy-MM-dd`. */
+  start: string;
+  /** Last measured day, `yyyy-MM-dd`, inclusive. */
+  end: string;
+};
+type MonthCalendarHeatmapOptions = {
+  /** 0 = Sunday, 1 = Monday. Default 1. */
+  weekStartsOn?: 0 | 1;
+  /** BCP-47 tag the month and day labels are written in. Defaults to the runtime's locale. */
+  locale?: string;
+};
+type MonthCalendarHeatmapResult = {
+  /** For `HeatmapChart`'s `data`: 7 columns per month, 6 cells each. */
+  data: HeatmapColumn[];
+  /** For `HeatmapChart`'s `columnGroups`: one per month, in order. */
+  columnGroups: HeatmapColumnGroup[];
+};
 //#endregion
 //#region src/charts/heatmap-chart/private/heatmap-legend.d.ts
 interface HeatmapLegendProps {
   /** Number of swatches in the scale. Default 5. */
   steps?: number;
+  /**
+   * `swatches` spaces the steps out as cell-sized squares; `bar` joins them
+   * into one continuous band with rounded ends. Default `swatches`.
+   */
+  variant?: 'swatches' | 'bar';
   lessLabel?: string;
   moreLabel?: string;
 }
@@ -1397,6 +1463,28 @@ interface HeatmapChartSubComponents {
 declare const HeatmapChart: FC<HeatmapChartProps> & HeatmapChartSubComponents;
 declare const HeatmapChartResponsive: FC<HeatmapChartProps & ResponsiveConfig> & HeatmapChartSubComponents;
 //#endregion
+//#region src/charts/heatmap-chart/build-calendar-data.d.ts
+/**
+ * Lay a day-bucketed series out as calendar columns.
+ *
+ * @param series  - Points to bucket.
+ * @param options - Grid shape, plus the locale and zone to read days in.
+ * @return Columns and row labels for `HeatmapChart`.
+ */
+declare const buildCalendarHeatmapData: (series: DataPointDate[], options?: CalendarHeatmapOptions) => CalendarHeatmapResult;
+//#endregion
+//#region src/charts/heatmap-chart/build-month-calendar-data.d.ts
+/**
+ * Lay a day-keyed map out as one month calendar per month, weekdays across and
+ * weeks down, for `HeatmapChart` with `columnGroups`.
+ *
+ * @param valueByDay - Value per `yyyy-MM-dd`. A missing day is `null`.
+ * @param range      - The measured days; every month from `start`'s through `end`'s is drawn.
+ * @param options    - Week start and label locale.
+ * @return Columns and one group per month; empty for an invalid or reversed range.
+ */
+declare const buildMonthCalendarHeatmapData: (valueByDay: Record<string, number | null>, range: MonthCalendarHeatmapRange, options?: MonthCalendarHeatmapOptions) => MonthCalendarHeatmapResult;
+//#endregion
 //#region src/charts/heatmap-chart/use-calendar-heatmap-data.d.ts
 /**
  * `buildCalendarHeatmapData` with the locale and zone taken from
@@ -1408,6 +1496,18 @@ declare const HeatmapChartResponsive: FC<HeatmapChartProps & ResponsiveConfig> &
  */
 declare const useCalendarHeatmapData: (series: DataPointDate[], options?: CalendarHeatmapOptions) => CalendarHeatmapResult;
 //#endregion
+//#region src/charts/heatmap-chart/use-month-calendar-heatmap-data.d.ts
+/**
+ * `buildMonthCalendarHeatmapData` with the locale taken from `GlobalChartsProvider`
+ * where the caller names none.
+ *
+ * @param valueByDay - Value per `yyyy-MM-dd`. Held by reference, so a caller that rebuilds it each render defeats the memo.
+ * @param range      - As for `buildMonthCalendarHeatmapData`.
+ * @param options    - As for `buildMonthCalendarHeatmapData`; `locale` wins over the provider.
+ * @return Columns and groups for `HeatmapChart`.
+ */
+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'> {
   /**
@@ -2198,5 +2298,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, 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 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 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 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, defaultTheme, formatMetricValue, formatPercentage, getBucketInfo, getColorDistance, hexToRgba, isValidHexColor, lightenHexColor, mergeThemes, mixHexColors, normalizeColorToHex, parseAsLocalDate, parseHslString, prefersLightText, relativeLuminance, resolveCssVariable, useCalendarHeatmapData, useChartFormatting, useChartLegendItems, useChartRegistration, useChartScopeElement, useGlobalChartsContext, useGlobalChartsTheme, useLeaderboardLegendItems, 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 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 };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.ts

@@ -91,6 +91,7 @@ type ThemeAnnotationStyles = {
 type DataPoint = {
   label: string;
   value: number;
+  color?: string;
 };
 /**
  * Data format for GeoChart - uses Google Charts native data format for maximum flexibility.
@@ -140,6 +141,7 @@ type DataPointDate = {
   dateString?: string;
   value: number | null;
   label?: string;
+  color?: string;
 };
 type LeaderboardEntry = {
   /**
@@ -348,6 +350,8 @@ type ChartTheme = {
     compactCellGap?: number;
     /** Fixed square cell size in px for compact mode */
     compactCellSize?: number;
+    /** Gap in px between adjacent column groups; in compact mode the minimum, as the gaps share leftover width */
+    groupGap?: number;
   };
 };
 /**
@@ -792,7 +796,7 @@ interface RenderTooltipGlyphProps<Datum extends object> extends GlyphProps<Datum
   glyphStyle?: SVGProps<SVGCircleElement>;
   isNearestDatum: boolean;
 }
-type TooltipPlacement = 'auto' | 'below-axis';
+type TooltipPlacement = 'auto' | 'below-axis' | 'beside';
 type CrosshairPaintProperty = 'stroke' | 'strokeWidth' | 'strokeOpacity' | 'strokeDasharray' | 'strokeLinecap' | 'opacity';
 type CrosshairStyle = Pick<SVGProps<SVGLineElement>, CrosshairPaintProperty> & {
   className?: string;
@@ -802,11 +806,13 @@ type XyChartTooltipProps<Datum extends object> = {
   renderTooltip: (params: RenderTooltipParams<Datum>) => ReactNode;
   renderGlyph?: (params: RenderTooltipGlyphProps<Datum>) => ReactNode;
   /**
-   * Keep the panel below the x-axis label band, centered at the datum x and horizontally clamped.
-   * Vertical bounds do not move this placement; clipping ancestors can still cut it off.
+   * Use below-axis placement for centered axis anchoring, or beside placement to avoid vertical flipping.
+   * Below-axis ignores vertical bounds; beside placement clamps to them.
    * @default 'auto'
    */
   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. */
   style?: TooltipProps$1['style'];
   snapTooltipToDatumX?: boolean;
@@ -823,7 +829,7 @@ type XyChartTooltipProps<Datum extends object> = {
    * that clips its overflow, or the viewport when there is none. The box may
    * leave the chart wrapper. (It used to keep a body-level portal inside the
    * viewport.)
-   * Ignored by `below-axis`.
+   * Non-auto placements always apply their own bounds handling.
    * @default true
    */
   detectBounds?: boolean;
@@ -887,7 +893,7 @@ interface LineChartProps extends BaseChartProps<SeriesData[]>, SeriesVisibilityP
    * Place the panel below the x-axis tick labels with a pointer at the datum x; horizontal bounds still apply.
    * @default 'auto'
    */
-  tooltipPlacement?: XyChartTooltipProps<DataPointDate>['tooltipPlacement'];
+  tooltipPlacement?: 'auto' | 'below-axis';
   /**
    * Inline container styles; see Below-Axis Tooltips in stories/index.docs.mdx for content color overrides.
    */
@@ -1026,15 +1032,30 @@ declare const AreaChart: AreaChartComponent;
 declare const AreaChartResponsive: AreaChartResponsiveComponent;
 //#endregion
 //#region src/charts/bar-chart/bar-chart.d.ts
+type BandHighlightSelection = {
+  datum: DataPointDate;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+};
 interface BarChartProps extends BaseChartProps<SeriesData[]>, SeriesVisibilityProps {
   /**
    * Legend configuration. Supports `collapseGroups` on top of the shared options.
    */
   legend?: SeriesChartLegendConfig;
   renderTooltip?: (params: RenderTooltipParams<DataPointDate>) => ReactNode;
+  /** Place the tooltip beside its category without vertical flipping. */
+  tooltipPlacement?: 'auto' | 'beside';
+  /** Tooltip top anchor in SVG coordinates; negative offsets are supported. */
+  tooltipAnchorTop?: number;
   orientation?: 'horizontal' | 'vertical';
   withPatterns?: boolean;
   showZeroValues?: boolean;
+  /** Highlight the active band across the plot when tooltips are enabled. */
+  withBandHighlight?: boolean;
+  /** Receive active band bounds in SVG coordinates, or null when dismissed. */
+  onBandHighlightChange?: (selection: BandHighlightSelection | null) => void;
   children?: ReactNode;
 }
 type BarChartBaseProps = Optional<BarChartProps, 'width' | 'height' | 'size'>;
@@ -1296,10 +1317,18 @@ type HeatmapColumn = {
    */
   summary?: boolean;
 };
+/** A run of consecutive columns sharing one label beneath the grid. */
+type HeatmapColumnGroup = {
+  label: string;
+  /** Columns covered; a positive integer. */
+  span: number;
+};
 type HeatmapTooltipData = {
   value: number | null;
   rowLabel?: string;
   columnLabel?: string;
+  /** Label of the column group the cell falls in, if any. */
+  groupLabel?: string;
   cellLabel?: string;
   row: number;
   column: number;
@@ -1307,6 +1336,22 @@ type HeatmapTooltipData = {
 interface HeatmapChartProps extends Omit<BaseChartProps<HeatmapColumn[]>, 'showLegend' | 'legend' | 'gridVisibility'> {
   /** y-axis labels by row index. Empty entries render blank. */
   rowLabels?: string[];
+  /**
+   * Consecutive runs of columns sharing one label beneath the grid, set one
+   * group gap apart. Runs from the first column; columns past the last group
+   * stay ungrouped. Ignored, with a warning, when a span is not a positive
+   * integer or the spans reach past the last column.
+   */
+  columnGroups?: HeatmapColumnGroup[];
+  /**
+   * How the arrow keys move the selection. `grid` steps across the whole grid.
+   * `calendar` reads each column group as a page: Left/Right by one cell (wrapping
+   * to the next row, then the next group), Up/Down by one row into the neighboring
+   * 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;
   /** Render the numeric value inside each cell. Default `! compact`. */
@@ -1338,10 +1383,16 @@ interface HeatmapChartProps extends Omit<BaseChartProps<HeatmapColumn[]>, 'showL
    */
   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`.
+   */
+  tooltipVariant?: 'light' | 'dark';
+  /** Inline styles merged onto the tooltip box, over the variant's own. */
+  tooltipStyle?: CSSProperties;
   children?: ReactNode;
 }
-//#endregion
-//#region src/charts/heatmap-chart/private/build-calendar-data.d.ts
 type CalendarHeatmapResult = {
   data: HeatmapColumn[];
   rowLabels: string[];
@@ -1372,19 +1423,34 @@ type CalendarHeatmapOptions = {
    */
   timeZone?: string;
 };
-/**
- * Lay a day-bucketed series out as calendar columns.
- *
- * @param series  - Points to bucket.
- * @param options - Grid shape, plus the locale and zone to read days in.
- * @return Columns and row labels for `HeatmapChart`.
- */
-declare const buildCalendarHeatmapData: (series: DataPointDate[], options?: CalendarHeatmapOptions) => CalendarHeatmapResult;
+type MonthCalendarHeatmapRange = {
+  /** First measured day, `yyyy-MM-dd`. */
+  start: string;
+  /** Last measured day, `yyyy-MM-dd`, inclusive. */
+  end: string;
+};
+type MonthCalendarHeatmapOptions = {
+  /** 0 = Sunday, 1 = Monday. Default 1. */
+  weekStartsOn?: 0 | 1;
+  /** BCP-47 tag the month and day labels are written in. Defaults to the runtime's locale. */
+  locale?: string;
+};
+type MonthCalendarHeatmapResult = {
+  /** For `HeatmapChart`'s `data`: 7 columns per month, 6 cells each. */
+  data: HeatmapColumn[];
+  /** For `HeatmapChart`'s `columnGroups`: one per month, in order. */
+  columnGroups: HeatmapColumnGroup[];
+};
 //#endregion
 //#region src/charts/heatmap-chart/private/heatmap-legend.d.ts
 interface HeatmapLegendProps {
   /** Number of swatches in the scale. Default 5. */
   steps?: number;
+  /**
+   * `swatches` spaces the steps out as cell-sized squares; `bar` joins them
+   * into one continuous band with rounded ends. Default `swatches`.
+   */
+  variant?: 'swatches' | 'bar';
   lessLabel?: string;
   moreLabel?: string;
 }
@@ -1397,6 +1463,28 @@ interface HeatmapChartSubComponents {
 declare const HeatmapChart: FC<HeatmapChartProps> & HeatmapChartSubComponents;
 declare const HeatmapChartResponsive: FC<HeatmapChartProps & ResponsiveConfig> & HeatmapChartSubComponents;
 //#endregion
+//#region src/charts/heatmap-chart/build-calendar-data.d.ts
+/**
+ * Lay a day-bucketed series out as calendar columns.
+ *
+ * @param series  - Points to bucket.
+ * @param options - Grid shape, plus the locale and zone to read days in.
+ * @return Columns and row labels for `HeatmapChart`.
+ */
+declare const buildCalendarHeatmapData: (series: DataPointDate[], options?: CalendarHeatmapOptions) => CalendarHeatmapResult;
+//#endregion
+//#region src/charts/heatmap-chart/build-month-calendar-data.d.ts
+/**
+ * Lay a day-keyed map out as one month calendar per month, weekdays across and
+ * weeks down, for `HeatmapChart` with `columnGroups`.
+ *
+ * @param valueByDay - Value per `yyyy-MM-dd`. A missing day is `null`.
+ * @param range      - The measured days; every month from `start`'s through `end`'s is drawn.
+ * @param options    - Week start and label locale.
+ * @return Columns and one group per month; empty for an invalid or reversed range.
+ */
+declare const buildMonthCalendarHeatmapData: (valueByDay: Record<string, number | null>, range: MonthCalendarHeatmapRange, options?: MonthCalendarHeatmapOptions) => MonthCalendarHeatmapResult;
+//#endregion
 //#region src/charts/heatmap-chart/use-calendar-heatmap-data.d.ts
 /**
  * `buildCalendarHeatmapData` with the locale and zone taken from
@@ -1408,6 +1496,18 @@ declare const HeatmapChartResponsive: FC<HeatmapChartProps & ResponsiveConfig> &
  */
 declare const useCalendarHeatmapData: (series: DataPointDate[], options?: CalendarHeatmapOptions) => CalendarHeatmapResult;
 //#endregion
+//#region src/charts/heatmap-chart/use-month-calendar-heatmap-data.d.ts
+/**
+ * `buildMonthCalendarHeatmapData` with the locale taken from `GlobalChartsProvider`
+ * where the caller names none.
+ *
+ * @param valueByDay - Value per `yyyy-MM-dd`. Held by reference, so a caller that rebuilds it each render defeats the memo.
+ * @param range      - As for `buildMonthCalendarHeatmapData`.
+ * @param options    - As for `buildMonthCalendarHeatmapData`; `locale` wins over the provider.
+ * @return Columns and groups for `HeatmapChart`.
+ */
+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'> {
   /**
@@ -2198,5 +2298,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, 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 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 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 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, defaultTheme, formatMetricValue, formatPercentage, getBucketInfo, getColorDistance, hexToRgba, isValidHexColor, lightenHexColor, mergeThemes, mixHexColors, normalizeColorToHex, parseAsLocalDate, parseHslString, prefersLightText, relativeLuminance, resolveCssVariable, useCalendarHeatmapData, useChartFormatting, useChartLegendItems, useChartRegistration, useChartScopeElement, useGlobalChartsContext, useGlobalChartsTheme, useLeaderboardLegendItems, 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 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 };
 //# sourceMappingURL=index.d.ts.map