@automattic/charts 3.2.0 → 4.0.0

package/src/types.ts

@@ -109,30 +109,36 @@ export type ChartType =
 export 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.
  */
 export 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`.
+ */
+export 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' ];
 	};
 };
 
@@ -344,167 +350,55 @@ export type DataPointPercentageCalculated = DataPointPercentage & {
 };
 
 /**
- * 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`.
  */
 export 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, 'stroke' > & {
-		/** @deprecated Set the `--a8c-charts-color-grid` custom property inside the provider tree instead. See `TOKENS.md`. */
-		stroke?: GridStyles[ 'stroke' ];
-	};
+	/** Optional CSS styles for grid lines. */
+	gridStyles?: Omit< GridStyles, '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, 'stroke' > & {
-		/** @deprecated Set the `--a8c-charts-color-tick` custom property inside the provider tree instead. See `TOKENS.md`. */
-		stroke?: LineStyles[ 'stroke' ];
-	};
+	xTickLineStyles?: Omit< LineStyles, 'stroke' >;
 	/** Styles for x-axis line */
-	xAxisLineStyles?: Omit< LineStyles, 'stroke' > & {
-		/** @deprecated Set the `--a8c-charts-color-axis` custom property inside the provider tree instead. See `TOKENS.md`. */
-		stroke?: LineStyles[ 'stroke' ];
-	};
-	/** Styles for series lines */
-	seriesLineStyles?: LineStyles[];
+	xAxisLineStyles?: Omit< LineStyles, '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, '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 > >;
+		lineStyles?: Partial<
+			Record< NonNullable< SeriesDataOptions[ 'type' ] >, Omit< LineStyles, 'stroke' > >
+		>;
 	};
 	barChart?: {
 		barStyles?: Partial< Record< NonNullable< SeriesDataOptions[ 'type' ] >, BarStyles > >;
@@ -523,16 +417,9 @@ export 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 */
@@ -545,18 +432,9 @@ export type ChartTheme = {
  * Useful for merged themes where defaults are provided for all optional properties.
  */
 export 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 >;
+		lineStyles: Record< NonNullable< SeriesDataOptions[ 'type' ] >, Omit< LineStyles, 'stroke' > >;
 	};
 	barChart: {
 		barStyles: Record< NonNullable< SeriesDataOptions[ 'type' ] >, BarStyles >;
@@ -565,8 +443,7 @@ export 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' ] > >;
 };
 
 /**
@@ -575,6 +452,42 @@ export type CompleteChartTheme = Required< ChartTheme > & {
  */
 export type TickResolution = 'hour' | 'day' | 'week' | 'month' | 'year';
 
+/**
+ * How a chart classified the buckets of the data it's drawing.
+ */
+export 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`.
+ */
+export 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;
+};
+
 export type AxisOptions = {
 	orientation?: OrientationType;
 	numTicks?: number;

package/src/utils/bucket-info.ts

@@ -0,0 +1,87 @@
+import { differenceInHours } from 'date-fns';
+import { parseAsLocalDate } from './date-parsing';
+import type { BucketInfo, DataPoint, DataPointDate, SeriesData, TickResolution } from '../types';
+
+// `dateString` is parsed here too: `getBucketInfo` is public, and hosts call it
+// with the raw series, before `useChartDataTransform` has dated the points.
+const getInstant = ( point?: DataPointDate | DataPoint ): number | undefined => {
+	if ( ! point ) {
+		return undefined;
+	}
+	if ( 'date' in point && point.date ) {
+		return point.date.getTime();
+	}
+	if ( 'dateString' in point && point.dateString ) {
+		return parseAsLocalDate( point.dateString ).getTime();
+	}
+	return undefined;
+};
+
+// Smallest interval between consecutive points across all series, in hours.
+// Infinity when no series carries two distinct instants.
+const getPointSpacingInHours = ( data: SeriesData[] ) => {
+	return data.reduce( ( spacing, datom ) => {
+		// Sorted and deduplicated rather than read in array order: `getBucketInfo`
+		// is public, and a repeated instant is padding, not a sub-daily gap.
+		const instants = [ ...new Set( datom.data.map( point => getInstant( point ) ) ) ]
+			.filter( ( time ): time is number => time !== undefined && Number.isFinite( time ) )
+			.sort( ( a, b ) => a - b );
+
+		return instants.reduce(
+			( seriesSpacing, time, index ) =>
+				index === 0
+					? seriesSpacing
+					: Math.min( seriesSpacing, Math.abs( differenceInHours( time, instants[ index - 1 ] ) ) ),
+			spacing
+		);
+	}, Number.POSITIVE_INFINITY );
+};
+
+// 23, not 24: a daily gap shrinks to 23 wall-clock hours across a
+// spring-forward DST transition.
+const SUB_DAILY_SPACING_HOURS = 23;
+
+// The shortest month, so monthly buckets clear it but weekly ones don't.
+const MONTHLY_SPACING_HOURS = 28 * 24;
+
+// The bucket size behind the data, as the resolution label the tick formats are
+// keyed on. Exported so consumers that label a single point — bar chart
+// tooltips — read the same classification the axis does instead of inferring
+// the resolution a second way. Weeks report as 'day': both are calendar-date
+// buckets as far as labeling goes.
+export const getBucketResolution = (
+	data: SeriesData[],
+	tickResolution?: TickResolution
+): Exclude< TickResolution, 'week' > => {
+	if ( tickResolution ) {
+		return tickResolution === 'week' ? 'day' : tickResolution;
+	}
+
+	const spacingInHours = getPointSpacingInHours( data );
+	if ( spacingInHours < SUB_DAILY_SPACING_HOURS ) {
+		return 'hour';
+	}
+	// Fewer than two points leaves the spacing unknowable, so fall back to
+	// calendar dates rather than reading Infinity as a very coarse bucket.
+	if ( ! Number.isFinite( spacingInHours ) || spacingInHours < MONTHLY_SPACING_HOURS ) {
+		return 'day';
+	}
+	// Twelve shortest months: above any monthly gap (31 days at most) and below
+	// any yearly one (365 days at least).
+	return spacingInHours < 12 * MONTHLY_SPACING_HOURS ? 'month' : 'year';
+};
+
+/**
+ * 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.
+ */
+export const getBucketInfo = (
+	data: SeriesData[],
+	tickResolution?: TickResolution
+): BucketInfo => ( {
+	bucket: tickResolution ?? getBucketResolution( data ),
+	displayResolution: getBucketResolution( data, tickResolution ),
+} );

package/src/utils/color-utils.ts

@@ -108,33 +108,6 @@ export const parseHslString = ( hslString: string ): [ number, number, number ]
 	return [ h, parsed.s * 100, parsed.l * 100 ];
 };
 
-/**
- * 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
- */
-export const parseRgbString = ( rgbString: string ): string | null => {
-	const lower = rgbString.toLowerCase().trim();
-
-	// Check prefix - only handle rgb(), not rgba()
-	// This is intentional - use normalizeColorToHex for rgba() support
-	if ( ! lower.startsWith( 'rgb(' ) || lower.startsWith( 'rgba(' ) ) {
-		return null;
-	}
-
-	const parsed = d3Color( lower );
-
-	// d3Color returns null for invalid colors
-	if ( ! parsed ) {
-		return null;
-	}
-
-	// d3-color clamps values automatically
-	return parsed.formatHex();
-};
-
 /**
  * Normalize any CSS color value to a hex color string.
  * Handles hex, HSL, HSLA, RGB, RGBA, named CSS colors, and CSS variables.

package/src/utils/date-formatting.ts

@@ -0,0 +1,174 @@
+import type { ChartFormatting } from '../types';
+
+/**
+ * `process.env.NODE_ENV` is replaced by the bundler at build time. Declare a
+ * minimal `process` locally so this file type-checks as source under `jetpack:src`.
+ */
+declare const process: { env: Record< string, string | undefined > };
+
+// One `Intl.DateTimeFormat` per locale, zone and options triple. The axis formats
+// every bucket in the domain, and rebuilding the formatter is what costs; the tick
+// formats themselves are rebuilt on every resize, so a per-closure cache is not
+// enough. Bounded by the host's own locale and zone, so a handful of entries.
+const formatters = new Map< string, Intl.DateTimeFormat >();
+
+const getFormatter = (
+	options: Intl.DateTimeFormatOptions,
+	{ locale, timeZone }: ChartFormatting
+): Intl.DateTimeFormat => {
+	const key = `${ locale ?? '' }|${ timeZone ?? '' }|${ JSON.stringify( options ) }`;
+	let formatter = formatters.get( key );
+
+	if ( ! formatter ) {
+		formatter = new Intl.DateTimeFormat( locale, { ...options, timeZone } );
+		formatters.set( key, formatter );
+	}
+
+	return formatter;
+};
+
+const warned = new Set< string >();
+
+const warnOnce = ( key: string, message: string ): void => {
+	if ( warned.has( key ) || process.env.NODE_ENV === 'production' ) {
+		return;
+	}
+
+	warned.add( key );
+	// eslint-disable-next-line no-console
+	console.warn( `[Charts] ${ message }` );
+};
+
+const isUsable = ( formatting: ChartFormatting ): boolean => {
+	try {
+		// Constructing is the check: `Intl` throws on a tag or zone it cannot use.
+		Intl.DateTimeFormat( formatting.locale, { timeZone: formatting.timeZone } );
+		return true;
+	} catch {
+		return false;
+	}
+};
+
+// WordPress underscores its locales, where BCP-47 wants a hyphen: `get_locale()`
+// returns `en_US` for what Intl knows as `en-US`.
+const toBcp47 = ( locale?: string ) => locale?.replace( /_/g, '-' );
+
+/**
+ * Repairs a host locale for `Intl`, dropping either half it still cannot use.
+ *
+ * Every formatter below is built during render, so an unusable string would throw
+ * where React unmounts the whole host tree rather than one chart. WordPress hands
+ * out the likeliest one either way: `timezone_string` is `''` on a site set to a
+ * raw UTC offset, and has no repair.
+ *
+ * @param formatting - Locale and time zone as the host supplied them.
+ * @return The usable halves, each `undefined` where the host's value was not.
+ */
+export const sanitizeFormatting = ( formatting: ChartFormatting ): ChartFormatting => {
+	const repaired = { ...formatting, locale: toBcp47( formatting.locale ) };
+
+	if ( isUsable( repaired ) ) {
+		return repaired;
+	}
+
+	const locale = isUsable( { locale: repaired.locale } ) ? repaired.locale : undefined;
+	const timeZone = isUsable( { timeZone: repaired.timeZone } ) ? repaired.timeZone : undefined;
+
+	if ( locale === undefined && formatting.locale !== undefined ) {
+		warnOnce(
+			`locale:${ formatting.locale }`,
+			`locale ${ JSON.stringify(
+				formatting.locale
+			) } is not a BCP-47 tag Intl accepts, so dates render in the browser's locale.`
+		);
+	}
+
+	if ( timeZone === undefined && formatting.timeZone !== undefined ) {
+		warnOnce(
+			`timeZone:${ formatting.timeZone }`,
+			`timeZone ${ JSON.stringify(
+				formatting.timeZone
+			) } is not a zone Intl accepts, so dates render in the browser's zone. Pass an IANA name or a UTC offset such as "+05:30".`
+		);
+	}
+
+	return { locale, timeZone };
+};
+
+/**
+ * A date formatter bound to the host's locale and time zone.
+ *
+ * @param options    - Date-part options, as for `Intl.DateTimeFormat`.
+ * @param formatting - Host locale and time zone; either half absent leaves the runtime's own.
+ * @return Formatter taking a timestamp or a `Date`.
+ */
+export const createDateFormatter = (
+	options: Intl.DateTimeFormatOptions,
+	formatting: ChartFormatting
+) => {
+	return ( value: number | Date ): string => {
+		// `Intl.DateTimeFormat` throws on an invalid date where the `Date` methods
+		// it replaces return "Invalid Date", and charts are expected to render past
+		// a bad point rather than fail. visx hands its tick formatter a `Date`, so
+		// coerce before the check.
+		if ( ! Number.isFinite( Number( value ) ) ) {
+			return new Date( Number( value ) ).toLocaleDateString();
+		}
+		return getFormatter( options, formatting ).format( value );
+	};
+};
+
+// Enough of the calendar to place a tick on a boundary, read in the host's zone
+// rather than the browser's. `en-US` pins the digits as Latin and the calendar as
+// Gregorian: a non-Gregorian `locale` labels its own new year, but the boundary
+// still fires on January 1.
+const CLOCK_OPTIONS: Intl.DateTimeFormatOptions = {
+	month: 'numeric',
+	hour: 'numeric',
+	hourCycle: 'h23',
+};
+
+export type ZonedFields = {
+	/** 1-12. */
+	month: number;
+	/** 0-23. */
+	hour: number;
+};
+
+// What the `Date` getters answer for an invalid date, so a bad point leaves every
+// boundary untriggered rather than throwing out of `formatToParts`.
+const NO_FIELDS: ZonedFields = { month: NaN, hour: NaN };
+
+/**
+ * A clock reading calendar fields in the host's time zone.
+ *
+ * `Date`'s own getters read the browser's zone, so a chart viewed from another
+ * country anchors its ticks to the wrong midnights and the wrong January
+ * without this.
+ *
+ * @param timeZone - IANA zone name; absent leaves the runtime's own.
+ * @return Reader taking a `Date`.
+ */
+export const createZonedClock = ( timeZone?: string ) => {
+	// The `Date` getters already answer in the runtime zone, and cost nothing.
+	if ( ! timeZone ) {
+		return ( date: Date ): ZonedFields => ( {
+			month: date.getMonth() + 1,
+			hour: date.getHours(),
+		} );
+	}
+
+	return ( date: Date ): ZonedFields => {
+		if ( ! Number.isFinite( Number( date ) ) ) {
+			return NO_FIELDS;
+		}
+
+		const parts = getFormatter( CLOCK_OPTIONS, { locale: 'en-US', timeZone } ).formatToParts(
+			date
+		);
+		const read = ( type: Intl.DateTimeFormatPartTypes ) =>
+			Number( parts.find( part => part.type === type )?.value );
+
+		return { month: read( 'month' ), hour: read( 'hour' ) };
+	};
+};

package/src/utils/index.ts

@@ -1,6 +1,9 @@
 // Chart composition utilities
 export { attachSubComponents } from './create-composition';
 
+// Date bucket classification
+export { getBucketInfo } from './bucket-info';
+
 // Date parsing utilities
 export { parseAsLocalDate } from './date-parsing';