@automattic/charts 3.1.1 → 4.0.0

package/dist/index.d.cts

@@ -7,7 +7,6 @@ import { EventHandlerParams, EventHandlerParams as EventHandlerParams$1, GlyphPr
 import { CSSProperties, ComponentClass, ComponentProps, ComponentType, FC, MouseEvent, PointerEvent, PropsWithChildren, ReactElement, ReactNode, SVGProps } from "react";
 import { TooltipProps as TooltipProps$1, UseTooltipPortalOptions } from "@visx/tooltip";
 import { PieProvidedProps } from "@visx/shape";
-
 //#region src/types.d.ts
 type ValueOf<T> = T[keyof T];
 type Optional<T, K extends keyof T> = Pick<Partial<T>, K> & Omit<T, K>;
@@ -60,8 +59,13 @@ type GoogleDataTableCell = {
 type GoogleDataTableRow = GoogleDataTableCell[];
 type ChartType = 'area' | 'bar' | 'conversion-funnel' | 'leaderboard' | 'line' | 'pie' | 'pie-semi-circle';
 type OrientationType = ValueOf<typeof Orientation>;
+/**
+ * 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'> & {
+  circleSubject?: Omit<CircleSubjectProps, 'x' | 'y' | 'fill'> & {
     fill?: string;
   };
   lineSubject?: Omit<LineSubjectProps, 'x' | 'y'>;
@@ -71,6 +75,19 @@ type AnnotationStyles = {
     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';
+  };
+};
 type DataPoint = {
   label: string;
   value: number;
@@ -240,7 +257,7 @@ type DataPointPercentage = {
    */
   valueDisplay?: string;
   /**
-   * Color code for the segment, by default colours are taken from the theme but this property can overrides it
+   * Color code for the segment, by default colors are taken from the theme but this property can overrides it
    */
   color?: string;
   /**
@@ -259,72 +276,77 @@ 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 */backgroundColor: string; /** Background color for labels */
-  labelBackgroundColor?: string; /** Text color for labels */
-  labelTextColor?: string; /** Array of colors used for data visualization */
-  colors: string[]; /** Optional CSS styles for grid lines */
-  gridStyles?: GridStyles$1; /** Length of axis ticks in pixels */
-  tickLength: number; /** Color of the grid lines */
-  gridColor: string; /** Color of the grid lines in dark mode */
-  gridColorDark: string; /** Styles for x-axis tick lines */
-  xTickLineStyles?: LineStyles$1; /** Styles for x-axis line */
-  xAxisLineStyles?: LineStyles$1; /** Styles for series lines */
-  seriesLineStyles?: LineStyles$1[]; /** Array of render functions for glyphs */
-  glyphs?: Array<(<Datum extends object>(props: GlyphProps<Datum>) => ReactNode)>; /** Legend specific settings */
+  /** Optional CSS styles for grid lines. */
+  gridStyles?: Omit<GridStyles$1, 'stroke'>;
+  /** Length of axis ticks in pixels */
+  tickLength: number;
+  /** Styles for x-axis tick lines */
+  xTickLineStyles?: Omit<LineStyles$1, 'stroke'>;
+  /** Styles for x-axis line */
+  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 */
-    labelStyles?: CSSProperties; /** Styles for legend container */
+    /** Styles for legend shapes */
+    shapeStyles?: Record<string, unknown>[];
+    /** 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. */
-  svgLabelSmall?: TextProps; /** Styles for large SVG text (eg. axis titles), passed through to the XYChart theme. */
+  };
+  /**
+   * 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>`.
+   */
+  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 */featureFillColor?: string;
-  }; /** LeaderboardChart specific settings */
+  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 */
-    primaryColor?: string; /** Secondary color for comparison period bars */
-    secondaryColor?: string; /** Delta colors: [negative, neutral, positive] */
-    deltaColors?: [string, string, string];
-  }; /** ConversionFunnelChart specific settings */
-  conversionFunnelChart?: {
-    /** Primary color for funnel bars */primaryColor?: string; /** Background color for chart container */
-    backgroundColor?: string; /** Color for positive change indicators */
-    positiveChangeColor?: string; /** Color for negative change indicators */
-    negativeChangeColor?: string;
+    /** Spacing between label and progress bars */
+    labelSpacing?: GapSize;
   };
   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>>;
-  }; /** Sparkline specific settings */
+  };
+  /** Sparkline specific settings */
   sparkline?: {
-    /** Margin around the sparkline chart */margin?: {
+    /** Margin around the sparkline chart */
+    margin?: {
       top?: number;
       right?: number;
       bottom?: number;
       left?: number;
-    }; /** Stroke width for the sparkline line */
+    };
+    /** Stroke width for the sparkline line */
     strokeWidth?: number;
   };
   /**
    * 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.
-     */
-    primaryColor?: string; /** Gap in px between cells in compact mode */
-    compactCellGap?: number; /** Fixed square cell size in px for compact mode */
+    /** Gap in px between cells in compact mode */
+    compactCellGap?: number;
+    /** Fixed square cell size in px for compact mode */
     compactCellSize?: number;
   };
 };
@@ -333,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>;
@@ -345,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. `HeatmapChart`'s
+ * calendar labels take neither — see `buildCalendarHeatmapData`.
+ */
+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;
@@ -426,7 +481,9 @@ type ScaleOptions = {
   paddingOuter?: number;
 };
 type LegendItemStyles = {
-  /** Margin around each legend item. */margin?: CSSProperties['margin']; /** Flex direction for items within each legend entry. */
+  /** Margin around each legend item. */
+  margin?: CSSProperties['margin'];
+  /** Flex direction for items within each legend entry. */
   flexDirection?: 'row' | 'row-reverse' | 'column' | 'column-reverse';
 };
 type LegendLabelStyles = Pick<CSSProperties, 'justifyContent' | 'flex' | 'margin'> & {
@@ -443,8 +500,11 @@ type LegendLabelStyles = Pick<CSSProperties, 'justifyContent' | 'flex' | 'margin
   textOverflow?: 'ellipsis' | 'wrap';
 };
 type LegendShapeStyles = {
-  /** Width of the legend shape in pixels. */width?: number; /** Height of the legend shape in pixels. */
-  height?: number; /** Margin around the legend shape. */
+  /** Width of the legend shape in pixels. */
+  width?: number;
+  /** Height of the legend shape in pixels. */
+  height?: number;
+  /** Margin around the legend shape. */
   margin?: CSSProperties['margin'];
 };
 /** Position of the legend relative to chart content. */
@@ -498,7 +558,7 @@ type ChartLegendConfig<T = DataPoint | DataPointDate | LeaderboardEntry> = {
 /**
  * Legend config for charts built from `SeriesData` (line, bar, area). Adds `collapseGroups` on top
  * of the shared config. It is intentionally absent from the base `ChartLegendConfig` so point-based
- * charts (pie, semi-circle pie) — whose data points carry `group` only to coordinate colours — can't
+ * charts (pie, semi-circle pie) — whose data points carry `group` only to coordinate colors — can't
  * set it.
  */
 type SeriesChartLegendConfig = ChartLegendConfig<SeriesData[]> & {
@@ -576,6 +636,16 @@ type BaseChartProps<T = DataPoint | DataPointDate | LeaderboardEntry> = {
    * Callback function for pointer out event
    */
   onPointerOut?: (event: PointerEvent<Element>) => void;
+  /**
+   * Callback for Enter or Space on the point keyboard navigation has selected:
+   * the keyboard counterpart of a click. `index` is the point's position in its
+   * series and `key` the series label.
+   */
+  onDatumActivate?: (params: {
+    datum: DataPoint | DataPointDate;
+    index: number;
+    key: string;
+  }) => void;
   /**
    * Whether to show tooltips on hover. False by default.
    */
@@ -622,11 +692,16 @@ type BaseLegendProps = VisxLegendProps & {
   items: BaseLegendItem[];
   orientation?: 'horizontal' | 'vertical';
   position?: LegendPosition;
-  alignment?: 'start' | 'center' | 'end'; /** Additional CSS class name for legend items. */
-  itemClassName?: string; /** CSS styles for each legend item (margin, flexDirection). */
-  itemStyles?: LegendItemStyles; /** Additional CSS class name for legend labels. */
-  labelClassName?: string; /** CSS styles for legend labels (justifyContent, flex, margin). */
-  labelStyles?: LegendLabelStyles; /** Styles for legend shapes (width, height, margin). */
+  alignment?: 'start' | 'center' | 'end';
+  /** Additional CSS class name for legend items. */
+  itemClassName?: string;
+  /** CSS styles for each legend item (margin, flexDirection). */
+  itemStyles?: LegendItemStyles;
+  /** Additional CSS class name for legend labels. */
+  labelClassName?: string;
+  /** CSS styles for legend labels (justifyContent, flex, margin). */
+  labelStyles?: LegendLabelStyles;
+  /** Styles for legend shapes (width, height, margin). */
   shapeStyles?: LegendShapeStyles;
   /**
    * Function for rendering a custom legend layout.
@@ -729,8 +804,36 @@ type XyChartTooltipProps<Datum extends object> = {
   verticalCrosshairStyle?: SVGProps<SVGLineElement>;
   horizontalCrosshairStyle?: SVGProps<SVGLineElement>;
   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.)
+   * @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 = {
@@ -762,7 +865,9 @@ interface LineChartProps extends BaseChartProps<SeriesData[]>, SeriesVisibilityP
   withGradientFill: boolean;
   smoothing?: boolean;
   curveType?: CurveType;
-  renderTooltip?: (params: RenderTooltipParams<DataPointDate>) => ReactNode;
+  renderTooltip?: (params: RenderTooltipParams<DataPointDate> & {
+    bucketInfo?: BucketInfo;
+  }) => ReactNode;
   withStartGlyphs?: boolean;
   withEndGlyphs?: boolean;
   renderGlyph?: <Datum extends object>(props: GlyphProps<Datum>) => ReactNode;
@@ -825,7 +930,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.
    */
@@ -857,12 +964,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
@@ -983,19 +1084,11 @@ interface RenderValueProps {
   formatter: (value: number) => string;
 }
 declare const BarListChart: FC<BarListChartProps>;
-declare const BarListChartResponsive: ({
-  resizeDebounceTime,
-  maxWidth,
-  aspectRatio,
-  size,
-  width,
-  height,
-  ...chartProps
-}: Omit<BarListChartProps, "height" | "size" | "width"> & {
+declare const BarListChartResponsive: ({ resizeDebounceTime, maxWidth, aspectRatio, size, width, height, ...chartProps }: Omit<BarListChartProps, "height" | "size" | "width"> & {
   width?: number;
   height?: number;
   size?: number;
-} & ResponsiveConfig) => import("react/jsx-runtime").JSX.Element;
+} & ResponsiveConfig) => import("react").JSX.Element;
 //#endregion
 //#region src/charts/conversion-funnel-chart/types.d.ts
 /**
@@ -1137,24 +1230,17 @@ interface GeoChartProps extends Pick<BaseChartProps, 'className' | 'chartId' | '
 //#endregion
 //#region src/charts/geo-chart/geo-chart.d.ts
 declare const GeoChartWithProvider: FC<GeoChartProps>;
-declare const GeoChartResponsive: ({
-  resizeDebounceTime,
-  maxWidth,
-  aspectRatio,
-  size,
-  width,
-  height,
-  ...chartProps
-}: Omit<GeoChartProps, "height" | "size" | "width"> & {
+declare const GeoChartResponsive: ({ resizeDebounceTime, maxWidth, aspectRatio, size, width, height, ...chartProps }: Omit<GeoChartProps, "height" | "size" | "width"> & {
   width?: number;
   height?: number;
   size?: number;
-} & ResponsiveConfig) => import("react/jsx-runtime").JSX.Element;
+} & ResponsiveConfig) => import("react").JSX.Element;
 //#endregion
 //#region src/charts/heatmap-chart/types.d.ts
 /** A single heatmap cell. `value: null` marks an empty cell. */
 type HeatmapCell = {
-  /** Per-cell label used in the tooltip / accessible name. */label?: string;
+  /** Per-cell label used in the tooltip / accessible name. */
+  label?: string;
   value: number | null;
   /**
    * Leave the cell's grid slot empty: nothing is painted and the cell is
@@ -1174,7 +1260,8 @@ type HeatmapCell = {
 };
 /** A heatmap column (rendered left→right); its cells render top→bottom. */
 type HeatmapColumn = {
-  /** x-axis label for this column. Empty/omitted renders blank. */label?: string;
+  /** x-axis label for this column. Empty/omitted renders blank. */
+  label?: string;
   data: HeatmapCell[];
 };
 type HeatmapTooltipData = {
@@ -1214,8 +1301,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;
@@ -1338,25 +1425,27 @@ declare const LeaderboardChart: FC<LeaderboardChartProps> & {
     chartId?: string;
   } & import("react").RefAttributes<HTMLDivElement>>;
 };
-declare const LeaderboardChartResponsive: (({
-  resizeDebounceTime,
-  maxWidth,
-  aspectRatio,
-  size,
-  width,
-  height,
-  ...chartProps
-}: Omit<LeaderboardChartProps, "height" | "size" | "width"> & {
+declare const LeaderboardChartResponsive: (({ resizeDebounceTime, maxWidth, aspectRatio, size, width, height, ...chartProps }: Omit<LeaderboardChartProps, "height" | "size" | "width"> & {
   width?: number;
   height?: number;
   size?: number;
-} & ResponsiveConfig) => import("react/jsx-runtime").JSX.Element) & {
+} & ResponsiveConfig) => import("react").JSX.Element) & {
   Legend: import("react").ForwardRefExoticComponent<Omit<BaseLegendProps, "items"> & {
     items?: BaseLegendItem[];
     chartId?: string;
   } & import("react").RefAttributes<HTMLDivElement>>;
 };
 //#endregion
+//#region src/utils/bucket-info.d.ts
+/**
+ * How this data was classified, for consumers that render their own labels.
+ *
+ * @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
 /**
  * @file Date parsing utilities using date-fns for local timezone handling
@@ -1438,11 +1527,7 @@ type FormatMetricValueOptions = {
  * @param options.signDisplay    - Controls when to display the sign (auto, always, never, exceptZero)
  * @return Formatted string
  */
-declare const formatMetricValue: (value: string | number, type?: MetricValueType, {
-  decimals,
-  useMultipliers,
-  signDisplay
-}?: FormatMetricValueOptions) => string;
+declare const formatMetricValue: (value: string | number, type?: MetricValueType, { decimals, useMultipliers, signDisplay }?: FormatMetricValueOptions) => string;
 //#endregion
 //#region src/utils/format-percentage.d.ts
 /**
@@ -1503,14 +1588,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.
@@ -1588,14 +1665,7 @@ declare const resolveCssVariable: (value: string, element?: HTMLElement | null)
  * @param root0.legendLabels.comparison - Label for comparison period data
  * @return Array of legend items for the leaderboard chart
  */
-declare function useLeaderboardLegendItems({
-  data,
-  primaryColor,
-  secondaryColor,
-  withComparison,
-  withOverlayLabel,
-  legendLabels
-}: {
+declare function useLeaderboardLegendItems({ data, primaryColor, secondaryColor, withComparison, withOverlayLabel, legendLabels }: {
   data: LeaderboardEntry[];
   primaryColor?: string;
   secondaryColor?: string;
@@ -1790,7 +1860,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;
   /**
@@ -1826,7 +1896,7 @@ interface SparklineProps {
   size?: number;
   /**
    * Color for the line stroke (hex or CSS color)
-   * @default Theme color (first color in theme.colors array)
+   * @default The first series palette color (`--a8c-charts-color-series-1`)
    */
   color?: string;
   /**
@@ -1886,19 +1956,11 @@ declare const SparklineUnresponsive: import("react").ForwardRefExoticComponent<S
 /**
  * Responsive Sparkline chart component
  */
-declare const Sparkline: ({
-  resizeDebounceTime,
-  maxWidth,
-  aspectRatio,
-  size,
-  width,
-  height,
-  ...chartProps
-}: Omit<SparklineProps, "height" | "size" | "width"> & {
+declare const Sparkline: ({ resizeDebounceTime, maxWidth, aspectRatio, size, width, height, ...chartProps }: Omit<SparklineProps, "height" | "size" | "width"> & {
   width?: number;
   height?: number;
   size?: number;
-} & ResponsiveConfig) => import("react/jsx-runtime").JSX.Element;
+} & ResponsiveConfig) => import("react").JSX.Element;
 //#endregion
 //#region src/components/tooltip/base-tooltip.d.ts
 type TooltipData = {
@@ -1933,16 +1995,7 @@ type CustomTooltip = {
   component?: never;
 };
 type BaseTooltipProps = TooltipCommonProps & (DefaultDataTooltip | CustomTooltip);
-declare const BaseTooltip: ({
-  data,
-  top,
-  left,
-  component: Component,
-  children,
-  className,
-  style,
-  renderContainer
-}: BaseTooltipProps) => string | number | true | import("react/jsx-runtime").JSX.Element | Iterable<ReactNode>;
+declare const BaseTooltip: ({ data, top, left, component: Component, children, className, style, renderContainer }: BaseTooltipProps) => string | number | true | import("react").JSX.Element | Iterable<ReactNode>;
 //#endregion
 //#region src/components/tooltip/accessible-tooltip.d.ts
 type FlattenedTooltipData = {
@@ -2022,13 +2075,7 @@ type TrendIndicatorProps = {
  * @param {TrendIndicatorProps} props - Component props
  * @return {JSX.Element} The rendered trend indicator
  */
-declare function TrendIndicator({
-  direction,
-  value,
-  className,
-  style,
-  showIcon
-}: TrendIndicatorProps): import("react/jsx-runtime").JSX.Element;
+declare function TrendIndicator({ direction, value, className, style, showIcon }: TrendIndicatorProps): import("react").JSX.Element;
 //#endregion
 //#region src/providers/chart-context/types.d.ts
 interface ChartRegistration {
@@ -2055,6 +2102,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;
@@ -2073,6 +2122,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
@@ -2080,13 +2139,7 @@ declare const GlobalChartsProvider: FC<GlobalChartsProviderProps>;
 declare const useGlobalChartsContext: () => GlobalChartsContextValue;
 //#endregion
 //#region src/providers/chart-context/hooks/use-chart-registration.d.ts
-declare const useChartRegistration: ({
-  chartId,
-  legendItems,
-  chartType,
-  isDataValid,
-  metadata
-}: {
+declare const useChartRegistration: ({ chartId, legendItems, chartType, isDataValid, metadata }: {
   chartId: string;
   legendItems: BaseLegendItem[];
   chartType: ChartType;
@@ -2102,9 +2155,24 @@ declare const useChartRegistration: ({
  */
 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
@@ -2116,5 +2184,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 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 };
 //# sourceMappingURL=index.d.cts.map