@automattic/charts 4.0.0 → 4.1.0

package/dist/index.css

@@ -555,6 +555,27 @@
   background: color-mix(in sRGB, var(--a8c-charts-color-track) 45%, transparent);
 }
 
+.a8ccharts-O3YMOW-heatmap-chart__cell--summary {
+  background: none;
+}
+
+.a8ccharts-O3YMOW-heatmap-chart__col-label--summary, .a8ccharts-O3YMOW-heatmap-chart__cell--summary .a8ccharts-O3YMOW-heatmap-chart__cell-value {
+  font-weight: var(--wpds-typography-font-weight-emphasis, 600);
+}
+
+.a8ccharts-O3YMOW-heatmap-chart__grid--compact .a8ccharts-O3YMOW-heatmap-chart__cell--summary .a8ccharts-O3YMOW-heatmap-chart__cell-value {
+  font-size: var(--wpds-typography-font-size-xs, 11px);
+  line-height: 1;
+}
+
+.a8ccharts-O3YMOW-heatmap-chart__gap-start {
+  margin-inline-start: var(--a8c-charts-dimension-heatmap-cell-gap, var(--wpds-dimension-gap-xs, 4px));
+}
+
+.a8ccharts-O3YMOW-heatmap-chart__gap-end {
+  margin-inline-end: var(--a8c-charts-dimension-heatmap-cell-gap, var(--wpds-dimension-gap-xs, 4px));
+}
+
 .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));
 }

package/dist/index.d.cts

@@ -398,8 +398,8 @@ type BucketInfo = {
  * `timeZone` re-dates the instants the host supplies, so a value that is really a
  * calendar day shifts under it: `new Date( '2026-08-02' )` is UTC midnight and
  * labels as Aug 1 in `America/Los_Angeles`. Supply true instants alongside a
- * `timeZone`, or set only `locale` for day-bucketed data. `HeatmapChart`'s
- * calendar labels take neither — see `buildCalendarHeatmapData`.
+ * `timeZone`, or set only `locale` for day-bucketed data. `buildCalendarHeatmapData`
+ * is the exception: it reads a bare `yyyy-MM-dd` as the day it names.
  */
 type ChartFormatting = {
   /** BCP-47 language tag, e.g. `de-DE`. Defaults to the runtime's locale. */
@@ -792,23 +792,38 @@ interface RenderTooltipGlyphProps<Datum extends object> extends GlyphProps<Datum
   glyphStyle?: SVGProps<SVGCircleElement>;
   isNearestDatum: boolean;
 }
+type TooltipPlacement = 'auto' | 'below-axis';
+type CrosshairPaintProperty = 'stroke' | 'strokeWidth' | 'strokeOpacity' | 'strokeDasharray' | 'strokeLinecap' | 'opacity';
+type CrosshairStyle = Pick<SVGProps<SVGLineElement>, CrosshairPaintProperty> & {
+  className?: string;
+  style?: Pick<CSSProperties, CrosshairPaintProperty>;
+};
 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.
+   * @default 'auto'
+   */
+  tooltipPlacement?: TooltipPlacement;
+  /** Merge overrides with the default box styles; use `unstyled` to strip the box styling. */
+  style?: TooltipProps$1['style'];
   snapTooltipToDatumX?: boolean;
   snapTooltipToDatumY?: boolean;
   showVerticalCrosshair?: boolean;
   showHorizontalCrosshair?: boolean;
   showDatumGlyph?: boolean;
   showSeriesGlyphs?: boolean;
-  verticalCrosshairStyle?: SVGProps<SVGLineElement>;
-  horizontalCrosshairStyle?: SVGProps<SVGLineElement>;
+  verticalCrosshairStyle?: CrosshairStyle;
+  horizontalCrosshairStyle?: CrosshairStyle;
   glyphStyle?: SVGProps<SVGCircleElement>;
   /**
    * Flip and clamp the tooltip box so it stays inside the nearest ancestor
    * 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`.
    * @default true
    */
   detectBounds?: boolean;
@@ -868,6 +883,15 @@ interface LineChartProps extends BaseChartProps<SeriesData[]>, SeriesVisibilityP
   renderTooltip?: (params: RenderTooltipParams<DataPointDate> & {
     bucketInfo?: BucketInfo;
   }) => ReactNode;
+  /**
+   * 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'];
+  /**
+   * Inline container styles; see Below-Axis Tooltips in stories/index.docs.mdx for content color overrides.
+   */
+  tooltipStyle?: CSSProperties;
   withStartGlyphs?: boolean;
   withEndGlyphs?: boolean;
   renderGlyph?: <Datum extends object>(props: GlyphProps<Datum>) => ReactNode;
@@ -876,6 +900,8 @@ interface LineChartProps extends BaseChartProps<SeriesData[]>, SeriesVisibilityP
   withTooltipCrosshairs?: {
     showVertical?: boolean;
     showHorizontal?: boolean;
+    verticalStyle?: CrosshairStyle;
+    horizontalStyle?: CrosshairStyle;
   };
   /**
    * Enable drag-to-zoom on the X axis. The user drags horizontally to
@@ -1263,6 +1289,12 @@ type HeatmapColumn = {
   /** x-axis label for this column. Empty/omitted renders blank. */
   label?: string;
   data: HeatmapCell[];
+  /**
+   * A per-row roll-up such as a total or an average. Left out of the color
+   * scale, drawn unfilled with its figure always printed, on an `auto` track
+   * one gap apart from the data beside it. The chart never computes it.
+   */
+  summary?: boolean;
 };
 type HeatmapTooltipData = {
   value: number | null;
@@ -1314,29 +1346,40 @@ type CalendarHeatmapResult = {
   data: HeatmapColumn[];
   rowLabels: string[];
 };
-declare const buildCalendarHeatmapData: (series: DataPointDate[], options?: {
+type CalendarHeatmapOptions = {
   weekStartsOn?: 0 | 1;
   /**
-   * Mark the days completing the first/last week outside the series'
-   * date span as hidden cells (empty grid slots) instead of blank
-   * cells, giving the calendar ragged edges. Days inside the span stay
-   * blank cells even when the series has no entry for them.
+   * Mark the days completing the first and last week outside the series' span as
+   * hidden cells rather than blank ones, giving the calendar ragged edges. Days
+   * inside the span stay blank even where the series has no entry.
    */
   hideOutOfRangeDays?: boolean;
   /**
-   * Draw the grid over this span (`yyyy-MM-dd` bounds) instead of the
-   * series' own. Days inside the grid but outside the series become
-   * placeholder cells: painted as empty slots so a short series still
-   * fills its container, but reporting nothing, since they were never
-   * measured. A start bound is drawn from the beginning of its week, so
-   * the grid always opens on a whole column. Bounds narrower than the
-   * series are ignored — the grid never drops a day that carries data.
+   * Draw the grid over this span (`yyyy-MM-dd` bounds) instead of the series' own.
+   * Days inside the grid but outside the series become placeholder cells: painted,
+   * but reporting nothing, since they were never measured. A start bound opens from
+   * the beginning of its week, and bounds narrower than the series are ignored.
    */
   gridSpan?: {
     start?: string;
     end?: string;
   };
-}) => CalendarHeatmapResult;
+  /** BCP-47 tag the labels are written in. Defaults to the runtime's locale. */
+  locale?: string;
+  /**
+   * IANA zone the series' instants are bucketed into days in. Defaults to the
+   * runtime's zone. A `dateString` carrying no offset is taken as written.
+   */
+  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;
 //#endregion
 //#region src/charts/heatmap-chart/private/heatmap-legend.d.ts
 interface HeatmapLegendProps {
@@ -1354,6 +1397,17 @@ interface HeatmapChartSubComponents {
 declare const HeatmapChart: FC<HeatmapChartProps> & HeatmapChartSubComponents;
 declare const HeatmapChartResponsive: FC<HeatmapChartProps & ResponsiveConfig> & HeatmapChartSubComponents;
 //#endregion
+//#region src/charts/heatmap-chart/use-calendar-heatmap-data.d.ts
+/**
+ * `buildCalendarHeatmapData` with the locale and zone taken from
+ * `GlobalChartsProvider` where the caller names neither.
+ *
+ * @param series  - Points to bucket. Held by reference, so a caller that rebuilds it each render defeats the memo.
+ * @param options - As for `buildCalendarHeatmapData`; `locale` and `timeZone` win over the provider.
+ * @return Columns and row labels for `HeatmapChart`.
+ */
+declare const useCalendarHeatmapData: (series: DataPointDate[], options?: CalendarHeatmapOptions) => CalendarHeatmapResult;
+//#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'> {
   /**
@@ -1373,9 +1427,9 @@ interface LeaderboardChartProps extends Pick<BaseChartProps<LeaderboardEntry>, '
    */
   secondaryColor?: string;
   /**
-   * Formatter for values
+   * Formatter for values. May return an element, e.g. to attach a tooltip.
    */
-  valueFormatter?: (value: number) => string;
+  valueFormatter?: (value: number) => ReactNode;
   /**
    * Formatter for delta values
    */
@@ -1448,62 +1502,22 @@ declare const getBucketInfo: (data: SeriesData[], tickResolution?: TickResolutio
 //#endregion
 //#region src/utils/date-parsing.d.ts
 /**
- * @file Date parsing utilities using date-fns for local timezone handling
- *
- * This module provides utilities for parsing various date string formats and converting
- * them to local timezone dates using the battle-tested date-fns library. For formats
- * without timezone info, they're treated as local. For formats with timezone info,
- * they're converted to the equivalent local time.
- *
- * Note: And specifically it prevents format `YYYY-MM-DD` being parsed as UTC date.
- *
- * Key Features:
- * - All parsed dates are in local timezone
- * - Converts timezone-aware strings to local equivalent
- * - Robust input validation and error handling using date-fns
- * - TypeScript type safety
- * - Much smaller codebase than custom parsing
+ * Parses any supported date string format into an instant, dated in `timeZone` or the runtime's own
  *
- * Supported Formats:
- * - YYYY-MM-DD (treated as local)
- * - YYYY-MM-DD HH:mm:ss (treated as local)
- * - YYYY-MM-DD HH:mm (treated as local)
- * - YYYY-MM-DDTHH:mm:ss (treated as local)
- * - YYYY-MM-DDTHH:mm:ss.SSS (treated as local)
- * - YYYY-MM-DDTHH:mm (treated as local)
- * - YYYY-MM-DDTHH:mm:ssZ (converted to local)
- * - YYYY-MM-DDTHH:mm:ss±HH:mm (converted to local)
- *
- * @example
- * ```typescript
- * parseAsLocalDate("2025-01-01");                     // Local timezone
- * parseAsLocalDate("2025-01-01 14:30:00");            // Local timezone
- * parseAsLocalDate("2025-01-01 14:30");               // Local timezone
- * parseAsLocalDate("2025-01-01T14:30:45.123");        // Local timezone
- * parseAsLocalDate("2025-01-01T14:30:00Z");           // UTC 14:30 → Local equivalent
- * parseAsLocalDate("2025-01-01T14:30:00+05:00");      // +05:00 14:30 → Local equivalent
- * ```
- */
-/**
- * Parses any supported date string format and returns a local timezone date
+ * Uses date-fns for robust parsing and validation. A string carrying timezone info
+ * is already an instant and is returned as one, whatever `timeZone` says. A string
+ * without it is a wall-clock reading, dated in `timeZone` when one is supplied and
+ * in the runtime's own zone when none is.
  *
- * Uses date-fns for robust parsing and validation. For strings without timezone
- * info, treats as local timezone. For strings with timezone info, converts to
- * local timezone equivalent.
+ * A wall clock a DST gap deleted is moved forward past the gap; one a fall-back repeated
+ * resolves to a single instant. Neither policy is selectable. A zone `Intl` rejects falls
+ * back to the runtime's own, and warns once outside production.
  *
- * Supports:
- * - YYYY-MM-DD (local)
- * - YYYY-MM-DD HH:mm:ss (local)
- * - YYYY-MM-DD HH:mm (local)
- * - YYYY-MM-DDTHH:mm:ss (local)
- * - YYYY-MM-DDTHH:mm:ss.SSS (local)
- * - YYYY-MM-DDTHH:mm (local)
- * - YYYY-MM-DDTHH:mm:ssZ (UTC → local)
- * - YYYY-MM-DDTHH:mm:ss±HH:mm (offset → local)
- * @param {string} dateString - The date string to parse into a local timezone date
- * @return {Date} A Date object representing the parsed date in local timezone, or an invalid Date if parsing fails
+ * @param {string} dateString - The date string to parse into a date
+ * @param {string} [timeZone] - IANA zone a naive string is read in; the runtime's own when absent, and ignored by a string that carries its own offset
+ * @return {Date} A Date object representing the parsed instant, or an invalid Date if parsing fails
  */
-declare const parseAsLocalDate: (dateString: string) => Date;
+declare const parseAsLocalDate: (dateString: string, timeZone?: string) => Date;
 //#endregion
 //#region src/utils/format-metric-value.d.ts
 /**
@@ -2184,5 +2198,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 CalendarHeatmapResult, type ChartFormatting, type ChartLegendConfig, type ChartLegendOptions, type ChartTheme, type CompleteChartTheme, ConversionFunnelChartWithProvider as ConversionFunnelChart, type ConversionFunnelChartProps, 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 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, useChartFormatting, useChartLegendItems, useChartRegistration, useChartScopeElement, useGlobalChartsContext, useGlobalChartsTheme, useLeaderboardLegendItems, validateHexColor };
+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 };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.ts

@@ -398,8 +398,8 @@ type BucketInfo = {
  * `timeZone` re-dates the instants the host supplies, so a value that is really a
  * calendar day shifts under it: `new Date( '2026-08-02' )` is UTC midnight and
  * labels as Aug 1 in `America/Los_Angeles`. Supply true instants alongside a
- * `timeZone`, or set only `locale` for day-bucketed data. `HeatmapChart`'s
- * calendar labels take neither — see `buildCalendarHeatmapData`.
+ * `timeZone`, or set only `locale` for day-bucketed data. `buildCalendarHeatmapData`
+ * is the exception: it reads a bare `yyyy-MM-dd` as the day it names.
  */
 type ChartFormatting = {
   /** BCP-47 language tag, e.g. `de-DE`. Defaults to the runtime's locale. */
@@ -792,23 +792,38 @@ interface RenderTooltipGlyphProps<Datum extends object> extends GlyphProps<Datum
   glyphStyle?: SVGProps<SVGCircleElement>;
   isNearestDatum: boolean;
 }
+type TooltipPlacement = 'auto' | 'below-axis';
+type CrosshairPaintProperty = 'stroke' | 'strokeWidth' | 'strokeOpacity' | 'strokeDasharray' | 'strokeLinecap' | 'opacity';
+type CrosshairStyle = Pick<SVGProps<SVGLineElement>, CrosshairPaintProperty> & {
+  className?: string;
+  style?: Pick<CSSProperties, CrosshairPaintProperty>;
+};
 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.
+   * @default 'auto'
+   */
+  tooltipPlacement?: TooltipPlacement;
+  /** Merge overrides with the default box styles; use `unstyled` to strip the box styling. */
+  style?: TooltipProps$1['style'];
   snapTooltipToDatumX?: boolean;
   snapTooltipToDatumY?: boolean;
   showVerticalCrosshair?: boolean;
   showHorizontalCrosshair?: boolean;
   showDatumGlyph?: boolean;
   showSeriesGlyphs?: boolean;
-  verticalCrosshairStyle?: SVGProps<SVGLineElement>;
-  horizontalCrosshairStyle?: SVGProps<SVGLineElement>;
+  verticalCrosshairStyle?: CrosshairStyle;
+  horizontalCrosshairStyle?: CrosshairStyle;
   glyphStyle?: SVGProps<SVGCircleElement>;
   /**
    * Flip and clamp the tooltip box so it stays inside the nearest ancestor
    * 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`.
    * @default true
    */
   detectBounds?: boolean;
@@ -868,6 +883,15 @@ interface LineChartProps extends BaseChartProps<SeriesData[]>, SeriesVisibilityP
   renderTooltip?: (params: RenderTooltipParams<DataPointDate> & {
     bucketInfo?: BucketInfo;
   }) => ReactNode;
+  /**
+   * 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'];
+  /**
+   * Inline container styles; see Below-Axis Tooltips in stories/index.docs.mdx for content color overrides.
+   */
+  tooltipStyle?: CSSProperties;
   withStartGlyphs?: boolean;
   withEndGlyphs?: boolean;
   renderGlyph?: <Datum extends object>(props: GlyphProps<Datum>) => ReactNode;
@@ -876,6 +900,8 @@ interface LineChartProps extends BaseChartProps<SeriesData[]>, SeriesVisibilityP
   withTooltipCrosshairs?: {
     showVertical?: boolean;
     showHorizontal?: boolean;
+    verticalStyle?: CrosshairStyle;
+    horizontalStyle?: CrosshairStyle;
   };
   /**
    * Enable drag-to-zoom on the X axis. The user drags horizontally to
@@ -1263,6 +1289,12 @@ type HeatmapColumn = {
   /** x-axis label for this column. Empty/omitted renders blank. */
   label?: string;
   data: HeatmapCell[];
+  /**
+   * A per-row roll-up such as a total or an average. Left out of the color
+   * scale, drawn unfilled with its figure always printed, on an `auto` track
+   * one gap apart from the data beside it. The chart never computes it.
+   */
+  summary?: boolean;
 };
 type HeatmapTooltipData = {
   value: number | null;
@@ -1314,29 +1346,40 @@ type CalendarHeatmapResult = {
   data: HeatmapColumn[];
   rowLabels: string[];
 };
-declare const buildCalendarHeatmapData: (series: DataPointDate[], options?: {
+type CalendarHeatmapOptions = {
   weekStartsOn?: 0 | 1;
   /**
-   * Mark the days completing the first/last week outside the series'
-   * date span as hidden cells (empty grid slots) instead of blank
-   * cells, giving the calendar ragged edges. Days inside the span stay
-   * blank cells even when the series has no entry for them.
+   * Mark the days completing the first and last week outside the series' span as
+   * hidden cells rather than blank ones, giving the calendar ragged edges. Days
+   * inside the span stay blank even where the series has no entry.
    */
   hideOutOfRangeDays?: boolean;
   /**
-   * Draw the grid over this span (`yyyy-MM-dd` bounds) instead of the
-   * series' own. Days inside the grid but outside the series become
-   * placeholder cells: painted as empty slots so a short series still
-   * fills its container, but reporting nothing, since they were never
-   * measured. A start bound is drawn from the beginning of its week, so
-   * the grid always opens on a whole column. Bounds narrower than the
-   * series are ignored — the grid never drops a day that carries data.
+   * Draw the grid over this span (`yyyy-MM-dd` bounds) instead of the series' own.
+   * Days inside the grid but outside the series become placeholder cells: painted,
+   * but reporting nothing, since they were never measured. A start bound opens from
+   * the beginning of its week, and bounds narrower than the series are ignored.
    */
   gridSpan?: {
     start?: string;
     end?: string;
   };
-}) => CalendarHeatmapResult;
+  /** BCP-47 tag the labels are written in. Defaults to the runtime's locale. */
+  locale?: string;
+  /**
+   * IANA zone the series' instants are bucketed into days in. Defaults to the
+   * runtime's zone. A `dateString` carrying no offset is taken as written.
+   */
+  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;
 //#endregion
 //#region src/charts/heatmap-chart/private/heatmap-legend.d.ts
 interface HeatmapLegendProps {
@@ -1354,6 +1397,17 @@ interface HeatmapChartSubComponents {
 declare const HeatmapChart: FC<HeatmapChartProps> & HeatmapChartSubComponents;
 declare const HeatmapChartResponsive: FC<HeatmapChartProps & ResponsiveConfig> & HeatmapChartSubComponents;
 //#endregion
+//#region src/charts/heatmap-chart/use-calendar-heatmap-data.d.ts
+/**
+ * `buildCalendarHeatmapData` with the locale and zone taken from
+ * `GlobalChartsProvider` where the caller names neither.
+ *
+ * @param series  - Points to bucket. Held by reference, so a caller that rebuilds it each render defeats the memo.
+ * @param options - As for `buildCalendarHeatmapData`; `locale` and `timeZone` win over the provider.
+ * @return Columns and row labels for `HeatmapChart`.
+ */
+declare const useCalendarHeatmapData: (series: DataPointDate[], options?: CalendarHeatmapOptions) => CalendarHeatmapResult;
+//#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'> {
   /**
@@ -1373,9 +1427,9 @@ interface LeaderboardChartProps extends Pick<BaseChartProps<LeaderboardEntry>, '
    */
   secondaryColor?: string;
   /**
-   * Formatter for values
+   * Formatter for values. May return an element, e.g. to attach a tooltip.
    */
-  valueFormatter?: (value: number) => string;
+  valueFormatter?: (value: number) => ReactNode;
   /**
    * Formatter for delta values
    */
@@ -1448,62 +1502,22 @@ declare const getBucketInfo: (data: SeriesData[], tickResolution?: TickResolutio
 //#endregion
 //#region src/utils/date-parsing.d.ts
 /**
- * @file Date parsing utilities using date-fns for local timezone handling
- *
- * This module provides utilities for parsing various date string formats and converting
- * them to local timezone dates using the battle-tested date-fns library. For formats
- * without timezone info, they're treated as local. For formats with timezone info,
- * they're converted to the equivalent local time.
- *
- * Note: And specifically it prevents format `YYYY-MM-DD` being parsed as UTC date.
- *
- * Key Features:
- * - All parsed dates are in local timezone
- * - Converts timezone-aware strings to local equivalent
- * - Robust input validation and error handling using date-fns
- * - TypeScript type safety
- * - Much smaller codebase than custom parsing
+ * Parses any supported date string format into an instant, dated in `timeZone` or the runtime's own
  *
- * Supported Formats:
- * - YYYY-MM-DD (treated as local)
- * - YYYY-MM-DD HH:mm:ss (treated as local)
- * - YYYY-MM-DD HH:mm (treated as local)
- * - YYYY-MM-DDTHH:mm:ss (treated as local)
- * - YYYY-MM-DDTHH:mm:ss.SSS (treated as local)
- * - YYYY-MM-DDTHH:mm (treated as local)
- * - YYYY-MM-DDTHH:mm:ssZ (converted to local)
- * - YYYY-MM-DDTHH:mm:ss±HH:mm (converted to local)
- *
- * @example
- * ```typescript
- * parseAsLocalDate("2025-01-01");                     // Local timezone
- * parseAsLocalDate("2025-01-01 14:30:00");            // Local timezone
- * parseAsLocalDate("2025-01-01 14:30");               // Local timezone
- * parseAsLocalDate("2025-01-01T14:30:45.123");        // Local timezone
- * parseAsLocalDate("2025-01-01T14:30:00Z");           // UTC 14:30 → Local equivalent
- * parseAsLocalDate("2025-01-01T14:30:00+05:00");      // +05:00 14:30 → Local equivalent
- * ```
- */
-/**
- * Parses any supported date string format and returns a local timezone date
+ * Uses date-fns for robust parsing and validation. A string carrying timezone info
+ * is already an instant and is returned as one, whatever `timeZone` says. A string
+ * without it is a wall-clock reading, dated in `timeZone` when one is supplied and
+ * in the runtime's own zone when none is.
  *
- * Uses date-fns for robust parsing and validation. For strings without timezone
- * info, treats as local timezone. For strings with timezone info, converts to
- * local timezone equivalent.
+ * A wall clock a DST gap deleted is moved forward past the gap; one a fall-back repeated
+ * resolves to a single instant. Neither policy is selectable. A zone `Intl` rejects falls
+ * back to the runtime's own, and warns once outside production.
  *
- * Supports:
- * - YYYY-MM-DD (local)
- * - YYYY-MM-DD HH:mm:ss (local)
- * - YYYY-MM-DD HH:mm (local)
- * - YYYY-MM-DDTHH:mm:ss (local)
- * - YYYY-MM-DDTHH:mm:ss.SSS (local)
- * - YYYY-MM-DDTHH:mm (local)
- * - YYYY-MM-DDTHH:mm:ssZ (UTC → local)
- * - YYYY-MM-DDTHH:mm:ss±HH:mm (offset → local)
- * @param {string} dateString - The date string to parse into a local timezone date
- * @return {Date} A Date object representing the parsed date in local timezone, or an invalid Date if parsing fails
+ * @param {string} dateString - The date string to parse into a date
+ * @param {string} [timeZone] - IANA zone a naive string is read in; the runtime's own when absent, and ignored by a string that carries its own offset
+ * @return {Date} A Date object representing the parsed instant, or an invalid Date if parsing fails
  */
-declare const parseAsLocalDate: (dateString: string) => Date;
+declare const parseAsLocalDate: (dateString: string, timeZone?: string) => Date;
 //#endregion
 //#region src/utils/format-metric-value.d.ts
 /**
@@ -2184,5 +2198,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 CalendarHeatmapResult, type ChartFormatting, type ChartLegendConfig, type ChartLegendOptions, type ChartTheme, type CompleteChartTheme, ConversionFunnelChartWithProvider as ConversionFunnelChart, type ConversionFunnelChartProps, 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 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, useChartFormatting, useChartLegendItems, useChartRegistration, useChartScopeElement, useGlobalChartsContext, useGlobalChartsTheme, useLeaderboardLegendItems, validateHexColor };
+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 };
 //# sourceMappingURL=index.d.ts.map