@automattic/charts 3.2.0 → 4.1.0

package/dist/index.d.cts

@@ -60,27 +60,32 @@ type GoogleDataTableRow = GoogleDataTableCell[];
 type ChartType = 'area' | 'bar' | 'conversion-funnel' | 'leaderboard' | 'line' | 'pie' | 'pie-semi-circle';
 type OrientationType = ValueOf<typeof Orientation>;
 /**
- * Annotation styling.
- *
- * Each color member is deprecated on its own rather than the field it sits in: `radius`, `stroke` widths and the label geometry alongside them have no catalog role behind them and still apply.
+ * Styling for one annotation, as its `styles` prop. Colors belong here because
+ * `--a8c-charts-color-annotation` moves every annotation on the page at once and no
+ * selector narrows it to one.
  */
 type AnnotationStyles = {
   circleSubject?: Omit<CircleSubjectProps, 'x' | 'y' | 'fill'> & {
-    /** @deprecated Set the `--a8c-charts-color-annotation` custom property inside the provider tree instead. See `TOKENS.md`. */
     fill?: string;
   };
   lineSubject?: Omit<LineSubjectProps, 'x' | 'y'>;
-  connector?: Omit<ConnectorProps, 'x' | 'y' | 'dx' | 'dy' | 'stroke'> & {
-    /** @deprecated Set the `--a8c-charts-color-annotation` custom property inside the provider tree instead. See `TOKENS.md`. */
-    stroke?: ConnectorProps['stroke'];
+  connector?: Omit<ConnectorProps, 'x' | 'y' | 'dx' | 'dy'>;
+  label?: Omit<LabelProps, 'title' | 'subtitle' | 'x' | 'y'> & {
+    x?: number | 'start' | 'end';
+    y?: number | 'start' | 'end';
   };
+};
+/**
+ * Annotation styling on the theme: geometry only. Colors come from
+ * `--a8c-charts-color-annotation` and `--a8c-charts-color-surface`.
+ */
+type ThemeAnnotationStyles = {
+  circleSubject?: Omit<CircleSubjectProps, 'x' | 'y' | 'fill' | 'stroke'>;
+  lineSubject?: Omit<LineSubjectProps, 'x' | 'y' | 'stroke'>;
+  connector?: Omit<ConnectorProps, 'x' | 'y' | 'dx' | 'dy' | 'stroke'>;
   label?: Omit<LabelProps, 'title' | 'subtitle' | 'x' | 'y' | 'anchorLineStroke' | 'backgroundFill'> & {
     x?: number | 'start' | 'end';
     y?: number | 'start' | 'end';
-    /** @deprecated Set the `--a8c-charts-color-annotation` custom property inside the provider tree instead. See `TOKENS.md`. */
-    anchorLineStroke?: LabelProps['anchorLineStroke'];
-    /** @deprecated Set the `--a8c-charts-color-surface` custom property inside the provider tree instead. See `TOKENS.md`. */
-    backgroundFill?: LabelProps['backgroundFill'];
   };
 };
 type DataPoint = {
@@ -271,167 +276,53 @@ type DataPointPercentageCalculated = DataPointPercentage & {
   percentage: number;
 };
 /**
- * Base theme configuration for chart components with optional properties
+ * Base theme configuration for chart components: shape and spacing. Chart colors are
+ * `--a8c-charts-color-*` roles set in CSS inside the provider tree, catalogued in
+ * `TOKENS.md`.
  */
 type ChartTheme = {
-  /**
-   * Background color for chart components.
-   *
-   * Still resolved in JS — gradient stops, the glyph stroke and `GeoChart`'s Google Charts config each need a concrete string — but that is about where the value is *consumed*, not where it is *set*. `withCatalogPointers` parks a consumer's value in the catalog role and restores the pointer, so the field is only ever a carrier for `--a8c-charts-color-background`, and setting the role directly does the same job.
-   *
-   * Optional so the deprecation is actionable: a consumer writing a full theme literal can now stop setting it. `CompleteChartTheme` is `Required< ChartTheme >`, so `defaultTheme` must still carry one.
-   *
-   * @deprecated Set the `--a8c-charts-color-background` custom property inside the provider tree instead. See `TOKENS.md`.
-   */
-  backgroundColor?: string;
-  /**
-   * Background color for labels.
-   *
-   * @deprecated Set the `--a8c-charts-color-label-background` custom property inside the provider tree instead. See `TOKENS.md`.
-   */
-  labelBackgroundColor?: string;
-  /**
-   * Text color for labels.
-   *
-   * @deprecated Set the `--a8c-charts-color-label-on-fill` custom property inside the provider tree instead. See `TOKENS.md`.
-   */
-  labelTextColor?: string;
-  /**
-   * Series palette seeds. Entry N publishes `--a8c-charts-color-series-{N+1}`; entries past the fifth are ignored.
-   *
-   * Optional so the deprecation is actionable: a consumer writing a full theme literal can now stop setting it. `CompleteChartTheme` is `Required< ChartTheme >`, so `defaultTheme` must still carry one.
-   *
-   * @deprecated Set the `--a8c-charts-color-series-1` … `-5` custom properties inside the provider tree instead, or `options.stroke` on a series for a single one. See `TOKENS.md`.
-   */
-  colors?: string[];
-  /**
-   * Optional CSS styles for grid lines.
-   *
-   * `stroke` is deprecated on its own, not the whole field: `strokeWidth` has no CSS role behind it and still applies. The same shape is used for the other fields whose color moved to CSS — annotating the field itself would strike through the half that stays.
-   */
-  gridStyles?: Omit<GridStyles$1, 'stroke'> & {
-    /** @deprecated Set the `--a8c-charts-color-grid` custom property inside the provider tree instead. See `TOKENS.md`. */
-    stroke?: GridStyles$1['stroke'];
-  };
+  /** Optional CSS styles for grid lines. */
+  gridStyles?: Omit<GridStyles$1, 'stroke'>;
   /** Length of axis ticks in pixels */
   tickLength: number;
-  /**
-   * Set `--a8c-charts-color-grid` for the gridlines.
-   *
-   * @deprecated Do not drop this field without replacing it. Nothing in this package consults it, but `buildChartTheme` seeds `y.left/right.axisLine.stroke` and `y.*.tickLine.stroke` from it, and `defaultTheme`'s empty string is the only thing leaving the y axis unpainted — deleting the field hands those a black `#222` instead. CHARTS-263 replaces it with visx's own `yAxisLineStyles`/`yTickLineStyles` and a pair of catalog roles.
-   */
-  gridColor?: string;
-  /**
-   * @deprecated Paints nothing, and unlike `gridColor` is safe to delete: `buildChartTheme` seeds `x.*.axisLine.stroke` from it, but spreads `xAxisLineStyles` over the top and `defaultTheme` always carries that stroke. Charts follow the host's theme through the catalog rather than a dark-mode field of their own.
-   */
-  gridColorDark?: string;
   /** Styles for x-axis tick lines */
-  xTickLineStyles?: Omit<LineStyles$1, 'stroke'> & {
-    /** @deprecated Set the `--a8c-charts-color-tick` custom property inside the provider tree instead. See `TOKENS.md`. */
-    stroke?: LineStyles$1['stroke'];
-  };
+  xTickLineStyles?: Omit<LineStyles$1, 'stroke'>;
   /** Styles for x-axis line */
-  xAxisLineStyles?: Omit<LineStyles$1, 'stroke'> & {
-    /** @deprecated Set the `--a8c-charts-color-axis` custom property inside the provider tree instead. See `TOKENS.md`. */
-    stroke?: LineStyles$1['stroke'];
-  };
-  /** Styles for series lines */
-  seriesLineStyles?: LineStyles$1[];
+  xAxisLineStyles?: Omit<LineStyles$1, 'stroke'>;
+  /**
+   * Per-series line styling — dash pattern, width, cap. These spread on top of the
+   * palette-derived stroke, so a color here would override it; a single series takes
+   * one through `options.seriesLineStyle`.
+   */
+  seriesLineStyles?: Array<Omit<LineStyles$1, 'stroke'>>;
   /** Array of render functions for glyphs */
   glyphs?: Array<(<Datum extends object>(props: GlyphProps<Datum>) => ReactNode)>;
   /** Legend specific settings */
   legend?: {
     /** Styles for legend shapes */
     shapeStyles?: Record<string, unknown>[];
-    /**
-     * Styles for legend labels.
-     *
-     * `color` is deprecated on its own, not the whole field: everything else a consumer sets here — font size, weight, spacing — has no catalog role behind it and still applies.
-     */
-    labelStyles?: Omit<CSSProperties, 'color'> & {
-      /** @deprecated Set the `--a8c-charts-color-label` custom property inside the provider tree instead. See `TOKENS.md`. */
-      color?: CSSProperties['color'];
-    };
+    /** Styles for legend labels. */
+    labelStyles?: Omit<CSSProperties, 'color'>;
     /** Styles for legend container */
     containerStyles?: CSSProperties;
   };
   /**
    * Styles for small SVG text (eg. axis tick labels), passed through to the XYChart theme.
    *
-   * `fontFamily: 'inherit'` is load-bearing here — it overrides the font stack `buildChartTheme` injects inline on SVG `<text>` — so only `fill` is deprecated.
+   * `fontFamily: 'inherit'` is load-bearing here — it overrides the font stack
+   * `buildChartTheme` injects inline on SVG `<text>`.
    */
-  svgLabelSmall?: Omit<TextProps, 'fill'> & {
-    /** @deprecated Set the `--a8c-charts-color-label-axis` custom property inside the provider tree instead, or `--a8c-charts-color-label` to move every label at once. See `TOKENS.md`. */
-    fill?: TextProps['fill'];
-  };
+  svgLabelSmall?: Omit<TextProps, 'fill'>;
   /** Styles for large SVG text (eg. axis titles), passed through to the XYChart theme. */
   svgLabelBig?: TextProps;
-  annotationStyles?: AnnotationStyles;
-  /** GeoChart specific settings */
-  geoChart?: {
-    /**
-     * Default fill color for a geo chart feature (e.g. country) with no data.
-     *
-     * @deprecated Set the `--a8c-charts-color-surface-secondary` custom property inside the provider tree instead. Google Charts still takes a resolved hex, but the value is read from the role. See `TOKENS.md`.
-     */
-    featureFillColor?: string;
-  };
+  annotationStyles?: ThemeAnnotationStyles;
   /** LeaderboardChart specific settings */
   leaderboardChart?: {
-    /** Gap between rows in the leaderboard grid */
-    rowGap?: number;
-    /** Gap between columns in the leaderboard grid */
-    columnGap?: number;
     /** Spacing between label and progress bars */
     labelSpacing?: GapSize;
-    /**
-     * Primary color for current period bars.
-     *
-     * @deprecated Use the `primaryColor` prop on `LeaderboardChart` for one chart, or set `--a8c-charts-color-series-1` to move the palette this falls back to. See `TOKENS.md`.
-     */
-    primaryColor?: string;
-    /**
-     * Secondary color for comparison period bars.
-     *
-     * @deprecated Use the `secondaryColor` prop on `LeaderboardChart` for one chart, or set `--a8c-charts-color-series-2` to move the palette this falls back to. See `TOKENS.md`.
-     */
-    secondaryColor?: string;
-    /**
-     * Delta colors: [negative, neutral, positive].
-     *
-     * @deprecated Set the `--a8c-charts-color-trend-down`, `-trend-neutral` and `-trend-up` custom properties inside the provider tree instead. See `TOKENS.md`.
-     */
-    deltaColors?: [string, string, string];
-  };
-  /** ConversionFunnelChart specific settings */
-  conversionFunnelChart?: {
-    /**
-     * Primary color for funnel bars.
-     *
-     * @deprecated Set `--a8c-charts-color-series-1` to move the palette this falls back to. See `TOKENS.md`.
-     */
-    primaryColor?: string;
-    /**
-     * Background color for chart container.
-     *
-     * @deprecated Set the `--a8c-charts-color-surface-secondary` custom property inside the provider tree instead. See `TOKENS.md`.
-     */
-    backgroundColor?: string;
-    /**
-     * Color for positive change indicators.
-     *
-     * @deprecated Set the `--a8c-charts-color-trend-up` custom property inside the provider tree instead. See `TOKENS.md`.
-     */
-    positiveChangeColor?: string;
-    /**
-     * Color for negative change indicators.
-     *
-     * @deprecated Set the `--a8c-charts-color-trend-down` custom property inside the provider tree instead. See `TOKENS.md`.
-     */
-    negativeChangeColor?: string;
   };
   lineChart?: {
-    lineStyles?: Partial<Record<NonNullable<SeriesDataOptions['type']>, LineStyles$1>>;
+    lineStyles?: Partial<Record<NonNullable<SeriesDataOptions['type']>, Omit<LineStyles$1, 'stroke'>>>;
   };
   barChart?: {
     barStyles?: Partial<Record<NonNullable<SeriesDataOptions['type']>, BarStyles>>;
@@ -450,16 +341,9 @@ type ChartTheme = {
   };
   /**
    * HeatmapChart settings. Cell gap, radius, value size and the selection ring come from
-   * WPDS tokens in CSS, so only the scale color and the compact sizing live here.
+   * WPDS tokens in CSS, so only the compact sizing lives here.
    */
   heatmapChart?: {
-    /**
-     * Color the cell scale interpolates toward at the highest value (prop > this >
-     * palette `colors[0]`), fed to CSS `color-mix`. Omit to use the palette color.
-     *
-     * @deprecated Use the `primaryColor` prop on `HeatmapChart` for one chart, or set `--a8c-charts-color-series-1` to move the palette this falls back to. See `TOKENS.md`.
-     */
-    primaryColor?: string;
     /** Gap in px between cells in compact mode */
     compactCellGap?: number;
     /** Fixed square cell size in px for compact mode */
@@ -471,10 +355,9 @@ type ChartTheme = {
  * Useful for merged themes where defaults are provided for all optional properties.
  */
 type CompleteChartTheme = Required<ChartTheme> & {
-  leaderboardChart: Omit<Required<NonNullable<ChartTheme['leaderboardChart']>>, 'primaryColor' | 'secondaryColor'> & Pick<NonNullable<ChartTheme['leaderboardChart']>, 'primaryColor' | 'secondaryColor'>;
-  conversionFunnelChart: Omit<Required<NonNullable<ChartTheme['conversionFunnelChart']>>, 'primaryColor'> & Pick<NonNullable<ChartTheme['conversionFunnelChart']>, 'primaryColor'>;
+  leaderboardChart: Required<NonNullable<ChartTheme['leaderboardChart']>>;
   lineChart: {
-    lineStyles: Record<NonNullable<SeriesDataOptions['type']>, LineStyles$1>;
+    lineStyles: Record<NonNullable<SeriesDataOptions['type']>, Omit<LineStyles$1, 'stroke'>>;
   };
   barChart: {
     barStyles: Record<NonNullable<SeriesDataOptions['type']>, BarStyles>;
@@ -483,13 +366,47 @@ type CompleteChartTheme = Required<ChartTheme> & {
   sparkline: Required<NonNullable<ChartTheme['sparkline']>> & {
     margin: Required<NonNullable<ChartTheme['sparkline']>['margin']>;
   };
-  heatmapChart: Omit<Required<NonNullable<ChartTheme['heatmapChart']>>, 'primaryColor'> & Pick<NonNullable<ChartTheme['heatmapChart']>, 'primaryColor'>;
+  heatmapChart: Required<NonNullable<ChartTheme['heatmapChart']>>;
 };
 /**
  * Bucket resolution of time-series data, as known by the caller (e.g. a
  * granularity selector), for consumers that don't need to infer it.
  */
 type TickResolution = 'hour' | 'day' | 'week' | 'month' | 'year';
+/**
+ * How a chart classified the buckets of the data it's drawing.
+ */
+type BucketInfo = {
+  /**
+   * The bucket the series has. Only reports `'week'` when declared: seven-day
+   * spacing is indistinguishable from sparse daily data.
+   */
+  bucket: TickResolution;
+  /** The classification tick formats are keyed on. `'week'` reads as `'day'`. */
+  displayResolution: Exclude<TickResolution, 'week'>;
+};
+/**
+ * The locale and time zone the time axis and the built-in tooltips render dates
+ * in, set once by the host on `GlobalChartsProvider`.
+ *
+ * Both halves are plain strings the host resolves for itself, so a non-WordPress
+ * consumer needs no WordPress package to supply them. Both are optional and
+ * default to the JavaScript runtime's own — the viewer's browser locale and
+ * browser time zone — which is what every version before this one used
+ * unconditionally.
+ *
+ * `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. `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. */
+  locale?: string;
+  /** IANA time zone name, e.g. `Asia/Tokyo`. Defaults to the runtime's zone. */
+  timeZone?: string;
+};
 type AxisOptions = {
   orientation?: OrientationType;
   numTicks?: number;
@@ -875,20 +792,63 @@ 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;
+  /**
+   * Stacking order of the tooltip box inside the chart wrapper, which isolates
+   * its stacking context: the value never competes with page chrome outside
+   * the chart.
+   * @default 3
+   */
+  zIndex?: number;
+  /**
+   * @deprecated Accepted and ignored. The box renders inside the chart wrapper
+   * and moves with it, so it needs no scroll tracking.
+   */
+  scroll?: boolean;
+  /**
+   * @deprecated Accepted and ignored. Nothing measures the box any more, so
+   * there is no measurement to debounce.
+   */
+  debounce?: number;
+  /**
+   * @deprecated Accepted and ignored. No ResizeObserver is used.
+   */
   resizeObserverPolyfill?: UseTooltipPortalOptions['polyfill'];
-} & Omit<TooltipProps$1, 'left' | 'top' | 'children'> & Pick<UseTooltipPortalOptions, 'debounce' | 'detectBounds' | 'scroll' | 'zIndex'>;
+} & Omit<TooltipProps$1, 'left' | 'top' | 'children' | 'applyPositionStyle'>;
 //#endregion
 //#region src/charts/line-chart/types.d.ts
 type LineChartAnnotationProps = {
@@ -920,7 +880,18 @@ interface LineChartProps extends BaseChartProps<SeriesData[]>, SeriesVisibilityP
   withGradientFill: boolean;
   smoothing?: boolean;
   curveType?: CurveType;
-  renderTooltip?: (params: RenderTooltipParams<DataPointDate>) => ReactNode;
+  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;
@@ -929,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
@@ -983,7 +956,9 @@ interface AreaChartProps extends BaseChartProps<SeriesData[]>, SeriesVisibilityP
   /**
    * Custom tooltip renderer.
    */
-  renderTooltip?: (params: RenderTooltipParams<DataPointDate>) => ReactNode;
+  renderTooltip?: (params: RenderTooltipParams<DataPointDate> & {
+    bucketInfo?: BucketInfo;
+  }) => ReactNode;
   /**
    * Whether to show crosshair lines in the tooltip.
    */
@@ -1015,12 +990,6 @@ interface AreaChartProps extends BaseChartProps<SeriesData[]>, SeriesVisibilityP
    * @default true
    */
   rescaleYOnVisibilityChange?: boolean;
-  /**
-   * @deprecated Use `rescaleYOnVisibilityChange`. The behaviour keys off series
-   * visibility changing, not specifically a legend toggle. Still honoured when
-   * `rescaleYOnVisibilityChange` is not set.
-   */
-  rescaleYOnLegendToggle?: boolean;
   children?: ReactNode;
 }
 //#endregion
@@ -1320,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;
@@ -1358,8 +1333,8 @@ 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
-   * (this prop > theme `heatmapChart.primaryColor` > palette `colors[0]`).
+   * Color the cell scale interpolates toward at the highest value. Defaults to the
+   * first series palette slot, `--a8c-charts-color-series-1`.
    */
   primaryColor?: string;
   renderTooltip?: (data: HeatmapTooltipData) => ReactNode;
@@ -1371,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 {
@@ -1411,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'> {
   /**
@@ -1430,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
    */
@@ -1493,64 +1490,34 @@ declare const LeaderboardChartResponsive: (({ resizeDebounceTime, maxWidth, aspe
   } & import("react").RefAttributes<HTMLDivElement>>;
 };
 //#endregion
-//#region src/utils/date-parsing.d.ts
+//#region src/utils/bucket-info.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.
+ * How this data was classified, for consumers that render their own labels.
  *
- * 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
- *
- * 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
- * ```
+ * @param data           - The series the chart draws, in any order, dated by `date` or `dateString`.
+ * @param tickResolution - Caller-declared bucket resolution, when known.
+ * @return The declared or inferred bucket, and the resolution formats key on.
  */
+declare const getBucketInfo: (data: SeriesData[], tickResolution?: TickResolution) => BucketInfo;
+//#endregion
+//#region src/utils/date-parsing.d.ts
 /**
- * Parses any supported date string format and returns a local timezone date
+ * Parses any supported date string format into an instant, dated in `timeZone` or the runtime's own
+ *
+ * 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
 /**
@@ -1635,14 +1602,6 @@ declare const getColorDistance: (hsl1: [number, number, number], hsl2: [number,
  * @return HSL tuple [h, s, l] or null if invalid
  */
 declare const parseHslString: (hslString: string) => [number, number, number] | null;
-/**
- * Parse an RGB string like 'rgb(255, 0, 0)' into a hex color.
- *
- * @deprecated    Use normalizeColorToHex() instead, which handles all color formats including rgb() and rgba().
- * @param      rgbString - RGB color string (not RGBA)
- * @return        hex color string or null if invalid
- */
-declare const parseRgbString: (rgbString: string) => string | null;
 /**
  * Normalize any CSS color value to a hex color string.
  * Handles hex, HSL, HSLA, RGB, RGBA, named CSS colors, and CSS variables.
@@ -1915,7 +1874,7 @@ type GradientConfig = {
    */
   from?: string;
   /**
-   * End color for gradient (defaults to theme backgroundColor)
+   * End color for gradient (defaults to `--a8c-charts-color-background`)
    */
   to?: string;
   /**
@@ -2157,6 +2116,8 @@ interface GlobalChartsContextValue {
   unregisterChart: (id: string) => void;
   getChartData: (id: string) => ChartRegistration | undefined;
   theme: CompleteChartTheme;
+  /** Locale and time zone every date the charts print is rendered in. */
+  formatting: ChartFormatting;
   getElementStyles: (params: GetElementStylesParams) => ElementStyles;
   toggleSeriesVisibility: (chartId: string, seriesLabel: string) => void;
   setSeriesVisibility: (chartId: string, seriesLabel: string, visible: boolean) => void;
@@ -2175,6 +2136,16 @@ declare const GlobalChartsContext: import("react").Context<GlobalChartsContextVa
 interface GlobalChartsProviderProps {
   children: ReactNode;
   theme?: Partial<ChartTheme>;
+  /**
+   * BCP-47 language tag every date label is rendered in, e.g. `de-DE`.
+   * Defaults to the viewer's browser locale.
+   */
+  locale?: string;
+  /**
+   * IANA time zone every date label is dated in, e.g. `Asia/Tokyo`.
+   * Defaults to the viewer's browser time zone.
+   */
+  timeZone?: string;
 }
 declare const GlobalChartsProvider: FC<GlobalChartsProviderProps>;
 //#endregion
@@ -2198,9 +2169,24 @@ declare const useChartRegistration: ({ chartId, legendItems, chartType, isDataVa
  */
 declare const useGlobalChartsTheme: () => CompleteChartTheme;
 //#endregion
+//#region src/providers/chart-context/hooks/use-chart-formatting.d.ts
+/**
+ * The locale and time zone dates are rendered in, as set on `GlobalChartsProvider`.
+ *
+ * Falls back to the runtime's own rather than throwing: charts render outside a
+ * provider, and a host that sets neither gets exactly the browser-default
+ * behavior this package had before the context existed.
+ *
+ * @return The host's formatting context.
+ */
+declare const useChartFormatting: () => ChartFormatting;
+//#endregion
 //#region src/providers/chart-context/themes.d.ts
 /**
- * Default theme configuration
+ * Default theme configuration: the shape and spacing a consumer can override.
+ *
+ * For a color, set the matching `--a8c-charts-color-*` role in CSS instead; the `var()`
+ * chains that deliver those live in `private/catalog-pointers.ts`.
  */
 declare const defaultTheme: CompleteChartTheme;
 //#endregion
@@ -2212,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 CalendarHeatmapResult, 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, getColorDistance, hexToRgba, isValidHexColor, lightenHexColor, mergeThemes, mixHexColors, normalizeColorToHex, parseAsLocalDate, parseHslString, parseRgbString, prefersLightText, relativeLuminance, resolveCssVariable, 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