@automattic/charts 4.1.0 → 4.1.1

package/CHANGELOG.md

@@ -5,6 +5,14 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.1.1] - 2026-09-15
+### Changed
+- Update package dependencies. [#52297]
+
+### Fixed
+- Fix unreadable axis labels in forced-colors mode. [#52268]
+- Return keyboard focus to line and area charts after closing a tooltip with Escape. [#52284]
+
 ## [4.1.0] - 2026-09-14
 ### Added
 - Heatmap: add `locale` and `timeZone` options and a `useCalendarHeatmapData` hook, so a host can bucket and label the calendar in its own zone and language instead of the viewer's. Labels with no `locale` now follow the runtime locale rather than always rendering in English, and a calendar `dateString` must start `yyyy-MM-dd`. [#52114]
@@ -1063,6 +1071,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Fixed lints following ESLint rule changes for TS [#40584]
 - Fixing a bug in Chart storybook data. [#40640]
 
+[4.1.1]: https://github.com/Automattic/charts/compare/v4.1.0...v4.1.1
 [4.1.0]: https://github.com/Automattic/charts/compare/v4.0.0...v4.1.0
 [4.0.0]: https://github.com/Automattic/charts/compare/v3.2.0...v4.0.0
 [3.2.0]: https://github.com/Automattic/charts/compare/v3.1.1...v3.2.0

package/TOKENS.md

@@ -12,7 +12,7 @@ Tooltips render inside the chart, so they carry the class only when no provider
 
 Inside a provider a tooltip therefore inherits the provider's inline `theme` var and any consumer rule scoped to the provider wrapper, the same as the chart it belongs to.
 
-Each catalog entry maps to a WPDS token. Source writes the mapping bare; the LightningCSS plugin in `tsdown.config.ts` injects the WPDS spec value as a fallback into `dist/`:
+Catalog entries normally map to WPDS tokens. Source writes these mappings bare; the LightningCSS plugin in `tsdown.config.ts` injects the WPDS spec value as a fallback into `dist/`:
 
 ```scss
 :where(.a8c-charts-scope) {
@@ -28,7 +28,7 @@ Highest first:
 
 1. The role set on any element between the chart and the provider — the closest declaration wins. A role set on the chart's *own* element reaches only what CSS paints; see "The SVG bridge".
 2. The role set by a consumer rule targeting the provider wrapper. It beats the catalog default because `:where()` is zero-specificity.
-3. The catalog default on the provider wrapper, resolving the mapped `--wpds-*` token.
+3. The catalog default on the provider wrapper, including the [forced-colors defaults](#one-pair-of-roles-per-axis) when active.
 4. The WPDS spec-value fallback, when no `--wpds-*` token is set either (SSR, jsdom, or WPDS not loaded). This is not a rare corner: WordPress itself defines no `--wpds-*` typography tokens, so in wp-admin the fallback is what renders. It is injected at build time by `@wordpress/theme`'s LightningCSS plugin.
 
 Configure catalog colors through CSS; the `theme` prop carries no colors. For local LineChart tooltip overrides, see [Below-Axis Tooltips](./?path=/docs/js-packages-charts-library-charts-line-chart--docs#below-axis-tooltips).
@@ -44,7 +44,7 @@ Some roles are deliberately narrower than the obvious name, so that moving one t
 | `--a8c-charts-color-label-axis` | `--a8c-charts-color-label` | legend labels, `.heatmap-chart__cell-value`, funnel labels, the line-chart tooltip |
 | `--a8c-charts-color-background` | — | — |
 
-`--a8c-charts-color-label-axis` *derives* from `--a8c-charts-color-label`, so setting the broad role moves every label at once and setting the narrow one moves only the SVG axis labels.
+Outside forced-colors mode, `--a8c-charts-color-label-axis` derives from `--a8c-charts-color-label`, so setting the broad role moves every label at once and setting the narrow one moves only the SVG axis labels. See [One pair of roles per axis](#one-pair-of-roles-per-axis) for forced-colors defaults.
 
 `--a8c-charts-color-surface` — the annotation label, `.x-zoom__reset`, tooltips — is a **sibling** of `--a8c-charts-color-background`, not a child. The chart's own background and the surfaces floating over it are set apart from each other often enough that one has to be able to move without the other. The consequence: no single role repaints both.
 
@@ -72,7 +72,7 @@ The scope element is the wrapper a chart is rendered into, which sits **above**
 
 ## Tier 1 — semantic catalog (shared, themeable roles)
 
-> These tables are checked against `src/styles/chart-scope.scss` by `src/styles/test/chart-scope.test.ts`. Update the stylesheet and the table together.
+> These tables describe the base defaults outside forced-colors mode and are checked against `src/styles/chart-scope.scss` by `src/styles/test/chart-scope.test.ts`. Update the stylesheet and the table together.
 
 | Role | Maps to | Fallback |
 |---|---|---|
@@ -114,6 +114,8 @@ Each axis names itself: `--a8c-charts-color-axis-x` / `-tick-x` paint the x axis
 
 Gridlines also stay on one role, `--a8c-charts-color-grid`: visx paints rows and columns from a single style object, so the grid is genuinely one thing rather than two.
 
+Under `forced-colors: active`, the axis label role uses `CanvasText`, and the grid, x-axis line, and x-axis tick roles use `GrayText`. The y-axis line and ticks remain hidden by default.
+
 The terminal `none` in each chain is explicit rather than load-bearing: `stroke` already starts at `none`, so an undeclared role paints nothing either way.
 
 **It would be load-bearing on a `fill`.** A `var()` naming an undeclared property with no fallback is invalid at computed-value time, which drops the declaration rather than leaving it absent — and `fill` starts at *black*. That is why `--a8c-charts-color-label-background` carries a terminal `transparent`: without it, an undeclared role would put a black plate behind every pie label. Give any role read by a `fill` a terminal literal, even when the intent is "paint nothing".

package/dist/index.cjs

@@ -2489,7 +2489,7 @@ const XyChartTooltipContent = ({ tooltipContext, container, renderTooltip, rende
 		..._visx_tooltip.defaultStyles,
 		zIndex,
 		backgroundColor: theme?.backgroundColor ?? "white",
-		boxShadow: `0 1px 2px ${theme?.htmlLabel?.color ? `${theme.htmlLabel.color}55` : "#22222255"}`,
+		boxShadow: `0 1px 2px ${isValidHexColor(theme?.htmlLabel?.color) ? `${theme.htmlLabel.color}55` : "#22222255"}`,
 		...theme?.htmlLabel,
 		...style
 	};
@@ -2672,7 +2672,8 @@ const useKeyboardNavigation = ({ selectedIndex, setSelectedIndex, isNavigating,
 				else element.focus();
 			}
 		}, [preventTooltipScroll, selectedIndex]),
-		onChartFocus: (0, react.useCallback)(() => {
+		onChartFocus: (0, react.useCallback)((event) => {
+			if (event.currentTarget.contains(event.relatedTarget)) return;
 			if (!isNavigating && selectedIndex !== void 0) setSelectedIndex(0);
 		}, [
 			isNavigating,
@@ -2684,15 +2685,19 @@ const useKeyboardNavigation = ({ selectedIndex, setSelectedIndex, isNavigating,
 		}, [setIsNavigating]),
 		onChartKeyDown: (0, react.useCallback)((event) => {
 			if (totalPoints === 0) return;
+			const focusChart = () => {
+				if (preventTooltipScroll) chartRef.current?.focus({ preventScroll: true });
+				else chartRef.current?.focus();
+			};
 			if (event.key === "Tab") {
-				chartRef.current?.focus();
+				focusChart();
 				setSelectedIndex(void 0);
 				setIsNavigating(false);
 				return;
 			}
 			const currentSelectedIndex = selectedIndex === void 0 ? -1 : selectedIndex;
 			if (currentSelectedIndex + 1 >= totalPoints && ["ArrowRight"].includes(event.key)) {
-				chartRef.current?.focus();
+				focusChart();
 				setSelectedIndex(void 0);
 				setIsNavigating(false);
 				return;
@@ -2707,7 +2712,7 @@ const useKeyboardNavigation = ({ selectedIndex, setSelectedIndex, isNavigating,
 			} else if (event.key === "Escape") {
 				setSelectedIndex(void 0);
 				setIsNavigating(false);
-				chartRef.current?.focus();
+				focusChart();
 			} else if ((event.key === "Enter" || event.key === " ") && selectedIndex !== void 0) onActivate?.(selectedIndex);
 		}, [
 			totalPoints,
@@ -2715,7 +2720,8 @@ const useKeyboardNavigation = ({ selectedIndex, setSelectedIndex, isNavigating,
 			setSelectedIndex,
 			setIsNavigating,
 			chartRef,
-			onActivate
+			onActivate,
+			preventTooltipScroll
 		])
 	};
 };
@@ -4318,6 +4324,7 @@ const LineChartInternal = (0, react.forwardRef)(({ data, chartId: providedChartI
 			children: ({ contentHeight }) => {
 				const chartHeight = contentHeight > 0 ? contentHeight : height;
 				return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+					ref: chartRef,
 					role: "grid",
 					"aria-label": (0, _wordpress_i18n.__)("Line chart", "jetpack-charts"),
 					tabIndex: 0,
@@ -4325,7 +4332,6 @@ const LineChartInternal = (0, react.forwardRef)(({ data, chartId: providedChartI
 					onFocus: onChartFocus,
 					onBlur: onChartBlur,
 					children: chartHeight > 0 && /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
-						ref: chartRef,
 						className: xy_plot_module_default["xy-plot"],
 						children: [zoomable && zoom.domain && /* @__PURE__ */ (0, react_jsx_runtime.jsx)(ZoomResetButton, { onClick: zoom.reset }), /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(_visx_xychart.XYChart, {
 							theme,
@@ -4823,6 +4829,7 @@ const AreaChartInternal = (0, react.forwardRef)(({ data, chartId: providedChartI
 			children: ({ contentHeight }) => {
 				const chartHeight = contentHeight > 0 ? contentHeight : height;
 				return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+					ref: chartRef,
 					role: "grid",
 					"aria-label": (0, _wordpress_i18n.__)("Area chart", "jetpack-charts"),
 					tabIndex: 0,
@@ -4830,7 +4837,6 @@ const AreaChartInternal = (0, react.forwardRef)(({ data, chartId: providedChartI
 					onFocus: onChartFocus,
 					onBlur: onChartBlur,
 					children: chartHeight > 0 && /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
-						ref: chartRef,
 						className: xy_plot_module_default["xy-plot"],
 						children: [zoomable && zoom.domain && /* @__PURE__ */ (0, react_jsx_runtime.jsx)(ZoomResetButton, { onClick: zoom.reset }), /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(_visx_xychart.XYChart, {
 							theme,
@@ -6634,233 +6640,6 @@ const getNormalizedValue = (value, extent) => {
 	return Math.min(1, Math.max(0, (value - min) / (max - min)));
 };
 //#endregion
-//#region src/charts/heatmap-chart/private/civil-day.ts
-const DAY_MS = 864e5;
-const KEY_OPTIONS = {
-	calendar: "gregory",
-	numberingSystem: "latn",
-	year: "numeric",
-	month: "2-digit",
-	day: "2-digit"
-};
-const DATE_PREFIX = /^(\d{4})-(\d{2})-(\d{2})/;
-const pad = (value, length) => String(value).padStart(length, "0");
-/**
-* The day a UTC proxy stands for.
-*
-* @param date - UTC proxy.
-* @return Its day key.
-*/
-const civilKey = (date) => `${pad(date.getUTCFullYear(), 4)}-${pad(date.getUTCMonth() + 1, 2)}-${pad(date.getUTCDate(), 2)}`;
-/**
-* A day key as a UTC-midnight proxy. UTC has no DST, so every step below is exactly
-* `DAY_MS`.
-*
-* @param key - Day key.
-* @return The proxy, or null when the key names no real day.
-*/
-const civilDate = (key) => {
-	const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(key);
-	if (!match) return null;
-	const date = /* @__PURE__ */ new Date(0);
-	date.setUTCFullYear(Number(match[1]), Number(match[2]) - 1, Number(match[3]));
-	date.setUTCHours(0, 0, 0, 0);
-	return civilKey(date) === key ? date : null;
-};
-/**
-* The day a written date names, ignoring any time and zone it carries.
-*
-* @param text - `yyyy-MM-dd`, optionally followed by a time.
-* @return Its day key, or null.
-*/
-const writtenDayKey = (text) => {
-	const match = DATE_PREFIX.exec(text);
-	if (!match) return null;
-	const key = `${match[1]}-${match[2]}-${match[3]}`;
-	return civilDate(key) ? key : null;
-};
-/**
-* Reads the day an instant falls on in a zone.
-*
-* @param timeZone - IANA zone name; absent leaves the runtime's own.
-* @return Reader taking a `Date`, null for a day no key can hold.
-*/
-const instantDayReader = (timeZone) => {
-	const formatter = new Intl.DateTimeFormat("en-US", {
-		...KEY_OPTIONS,
-		timeZone
-	});
-	return (date) => {
-		const parts = formatter.formatToParts(date);
-		const read = (type) => parts.find((part) => part.type === type)?.value ?? "";
-		const key = `${pad(Number(read("year")), 4)}-${read("month")}-${read("day")}`;
-		return civilDate(key) ? key : null;
-	};
-};
-/**
-* The day a series point belongs to.
-*
-* A `Date`, or a string carrying `Z` or an offset, is an instant read in the host's
-* zone. Anything else is a wall clock the host wrote, so its date part is the day.
-*
-* @param point       - Series point.
-* @param readInstant - Reader from `instantDayReader`.
-* @return Its day key, or null when the point carries no usable date.
-*/
-const pointDayKey = (point, readInstant) => {
-	if (point.date instanceof Date && !isNaN(point.date.getTime())) {
-		const key = readInstant(point.date);
-		if (key) return key;
-	}
-	const text = point.dateString;
-	if (!text) return null;
-	if (!hasTimezone(text)) return writtenDayKey(text);
-	const parsed = (0, date_fns.parseISO)(text);
-	return isNaN(parsed.getTime()) ? null : readInstant(parsed);
-};
-/**
-* Steps a proxy by whole days.
-*
-* @param date - UTC proxy.
-* @param days - Days to add; may be negative.
-* @return The shifted proxy.
-*/
-const addCivilDays = (date, days) => new Date(date.getTime() + days * DAY_MS);
-/**
-* Rounds a proxy down to its week.
-*
-* @param date         - UTC proxy.
-* @param weekStartsOn - 0 for Sunday, 1 for Monday.
-* @return The proxy for that week's first day.
-*/
-const startOfCivilWeek = (date, weekStartsOn) => {
-	const daysSinceWeekStart = (date.getUTCDay() - weekStartsOn + 7) % 7;
-	return addCivilDays(date, -daysSinceWeekStart);
-};
-/**
-* Counts the columns a span needs.
-*
-* @param from         - Earlier UTC proxy.
-* @param to           - Later UTC proxy.
-* @param weekStartsOn - 0 for Sunday, 1 for Monday.
-* @return Columns needed to cover the span, inclusive.
-*/
-const civilWeekSpan = (from, to, weekStartsOn) => Math.floor((startOfCivilWeek(to, weekStartsOn).getTime() - startOfCivilWeek(from, weekStartsOn).getTime()) / (7 * DAY_MS)) + 1;
-//#endregion
-//#region src/charts/heatmap-chart/private/build-calendar-data.ts
-/** Rows that get a weekday label (Mon, Wed, Fri with a Monday week start). */
-const LABELLED_ROWS = [
-	0,
-	2,
-	4
-];
-/**
-* Resolve one grid bound: an unparseable or narrowing value falls back to the
-* series' own bound, so the grid can only ever be widened.
-*
-* @param bound     - Requested bound as `yyyy-MM-dd`, if any.
-* @param fallback  - The series' own bound on this side.
-* @param direction - Which way the bound is allowed to move.
-* @return The day key to draw to.
-*/
-const widenTo = (bound, fallback, direction) => {
-	const key = bound ? writtenDayKey(bound) : null;
-	if (!key) {
-		if (bound) warnOnce(`heatmap:gridSpan:${bound}`, `gridSpan.${direction === "earlier" ? "start" : "end"} ${JSON.stringify(bound)} is not a \`yyyy-MM-dd\` day, so the grid is drawn over the series' own span.`);
-		return fallback;
-	}
-	if (direction === "earlier") return key < fallback ? key : fallback;
-	return key > fallback ? key : fallback;
-};
-/**
-* 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`.
-*/
-const buildCalendarHeatmapData = (series, options = {}) => {
-	const weekStartsOn = options.weekStartsOn ?? 1;
-	const hideOutOfRangeDays = options.hideOutOfRangeDays ?? true;
-	const { locale, timeZone } = sanitizeFormatting({
-		locale: options.locale,
-		timeZone: options.timeZone
-	});
-	const readInstant = instantDayReader(timeZone);
-	const valueByDay = /* @__PURE__ */ new Map();
-	let minDayKey;
-	let maxDayKey;
-	for (const point of series) {
-		const key = pointDayKey(point, readInstant);
-		if (!key) {
-			const offending = point.dateString ?? (point.date && String(point.date));
-			warnOnce(`heatmap:unreadableDate:${offending}`, offending ? `${JSON.stringify(offending)} is not a day this can read, so its point is left out of the calendar. A \`dateString\` must start \`yyyy-MM-dd\`.` : "A point carries neither `date` nor `dateString`, so it is left out of the calendar.");
-			continue;
-		}
-		valueByDay.set(key, point.value);
-		if (!minDayKey || key < minDayKey) minDayKey = key;
-		if (!maxDayKey || key > maxDayKey) maxDayKey = key;
-	}
-	if (!minDayKey || !maxDayKey) return {
-		data: [],
-		rowLabels: []
-	};
-	const requestedMinDayKey = widenTo(options.gridSpan?.start, minDayKey, "earlier");
-	const gridMaxDayKey = widenTo(options.gridSpan?.end, maxDayKey, "later");
-	const requestedMinDate = civilDate(requestedMinDayKey);
-	const gridMaxDate = civilDate(gridMaxDayKey);
-	const labelFormatting = {
-		locale,
-		timeZone: "UTC"
-	};
-	const formatWeekday = createDateFormatter({ weekday: "short" }, labelFormatting);
-	const formatMonth = createDateFormatter({ month: "short" }, labelFormatting);
-	const formatDay = createDateFormatter({
-		weekday: "short",
-		month: "short",
-		day: "numeric",
-		year: "numeric"
-	}, labelFormatting);
-	const gridStart = startOfCivilWeek(requestedMinDate, weekStartsOn);
-	const gridMinDayKey = requestedMinDayKey < minDayKey ? civilKey(gridStart) : requestedMinDayKey;
-	const weekCount = civilWeekSpan(gridStart, gridMaxDate, weekStartsOn);
-	const rowLabels = Array.from({ length: 7 }, (_, row) => LABELLED_ROWS.includes(row) ? formatWeekday(addCivilDays(gridStart, row)) : "");
-	const MIN_FIRST_MONTH_WEEKS = 2;
-	const firstMonth = gridStart.getUTCMonth();
-	let firstMonthWeeks = 0;
-	while (firstMonthWeeks < weekCount && addCivilDays(gridStart, firstMonthWeeks * 7).getUTCMonth() === firstMonth) firstMonthWeeks++;
-	const showFirstMonthLabel = !(firstMonthWeeks < weekCount) || firstMonthWeeks >= MIN_FIRST_MONTH_WEEKS;
-	const data = [];
-	let previousMonth = -1;
-	for (let week = 0; week < weekCount; week++) {
-		const columnStart = addCivilDays(gridStart, week * 7);
-		const month = columnStart.getUTCMonth();
-		const label = month !== previousMonth && (week !== 0 || showFirstMonthLabel) ? formatMonth(columnStart) : "";
-		previousMonth = month;
-		const cells = [];
-		for (let row = 0; row < 7; row++) {
-			const day = addCivilDays(gridStart, week * 7 + row);
-			const key = civilKey(day);
-			const cell = {
-				label: formatDay(day),
-				value: valueByDay.has(key) ? valueByDay.get(key) : null
-			};
-			if (key < gridMinDayKey || key > gridMaxDayKey) {
-				if (hideOutOfRangeDays) cell.hidden = true;
-			} else if (key < minDayKey || key > maxDayKey) cell.placeholder = true;
-			cells.push(cell);
-		}
-		data.push({
-			label,
-			data: cells
-		});
-	}
-	return {
-		data,
-		rowLabels
-	};
-};
-//#endregion
 //#region src/charts/heatmap-chart/private/heatmap-context.ts
 /** Shared by the chart and legend without importing back from `heatmap-chart.tsx`. */
 const HeatmapContext = (0, react.createContext)(null);
@@ -7200,6 +6979,233 @@ const HeatmapChartResponsiveInner = (props) => /* @__PURE__ */ (0, react_jsx_run
 HeatmapChartResponsiveInner.displayName = "HeatmapChart";
 const HeatmapChartResponsive = attachSubComponents(withResponsive(HeatmapChartResponsiveInner), { Legend: HeatmapLegend });
 //#endregion
+//#region src/charts/heatmap-chart/private/civil-day.ts
+const DAY_MS = 864e5;
+const KEY_OPTIONS = {
+	calendar: "gregory",
+	numberingSystem: "latn",
+	year: "numeric",
+	month: "2-digit",
+	day: "2-digit"
+};
+const DATE_PREFIX = /^(\d{4})-(\d{2})-(\d{2})/;
+const pad = (value, length) => String(value).padStart(length, "0");
+/**
+* The day a UTC proxy stands for.
+*
+* @param date - UTC proxy.
+* @return Its day key.
+*/
+const civilKey = (date) => `${pad(date.getUTCFullYear(), 4)}-${pad(date.getUTCMonth() + 1, 2)}-${pad(date.getUTCDate(), 2)}`;
+/**
+* A day key as a UTC-midnight proxy. UTC has no DST, so every step below is exactly
+* `DAY_MS`.
+*
+* @param key - Day key.
+* @return The proxy, or null when the key names no real day.
+*/
+const civilDate = (key) => {
+	const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(key);
+	if (!match) return null;
+	const date = /* @__PURE__ */ new Date(0);
+	date.setUTCFullYear(Number(match[1]), Number(match[2]) - 1, Number(match[3]));
+	date.setUTCHours(0, 0, 0, 0);
+	return civilKey(date) === key ? date : null;
+};
+/**
+* The day a written date names, ignoring any time and zone it carries.
+*
+* @param text - `yyyy-MM-dd`, optionally followed by a time.
+* @return Its day key, or null.
+*/
+const writtenDayKey = (text) => {
+	const match = DATE_PREFIX.exec(text);
+	if (!match) return null;
+	const key = `${match[1]}-${match[2]}-${match[3]}`;
+	return civilDate(key) ? key : null;
+};
+/**
+* Reads the day an instant falls on in a zone.
+*
+* @param timeZone - IANA zone name; absent leaves the runtime's own.
+* @return Reader taking a `Date`, null for a day no key can hold.
+*/
+const instantDayReader = (timeZone) => {
+	const formatter = new Intl.DateTimeFormat("en-US", {
+		...KEY_OPTIONS,
+		timeZone
+	});
+	return (date) => {
+		const parts = formatter.formatToParts(date);
+		const read = (type) => parts.find((part) => part.type === type)?.value ?? "";
+		const key = `${pad(Number(read("year")), 4)}-${read("month")}-${read("day")}`;
+		return civilDate(key) ? key : null;
+	};
+};
+/**
+* The day a series point belongs to.
+*
+* A `Date`, or a string carrying `Z` or an offset, is an instant read in the host's
+* zone. Anything else is a wall clock the host wrote, so its date part is the day.
+*
+* @param point       - Series point.
+* @param readInstant - Reader from `instantDayReader`.
+* @return Its day key, or null when the point carries no usable date.
+*/
+const pointDayKey = (point, readInstant) => {
+	if (point.date instanceof Date && !isNaN(point.date.getTime())) {
+		const key = readInstant(point.date);
+		if (key) return key;
+	}
+	const text = point.dateString;
+	if (!text) return null;
+	if (!hasTimezone(text)) return writtenDayKey(text);
+	const parsed = (0, date_fns.parseISO)(text);
+	return isNaN(parsed.getTime()) ? null : readInstant(parsed);
+};
+/**
+* Steps a proxy by whole days.
+*
+* @param date - UTC proxy.
+* @param days - Days to add; may be negative.
+* @return The shifted proxy.
+*/
+const addCivilDays = (date, days) => new Date(date.getTime() + days * DAY_MS);
+/**
+* Rounds a proxy down to its week.
+*
+* @param date         - UTC proxy.
+* @param weekStartsOn - 0 for Sunday, 1 for Monday.
+* @return The proxy for that week's first day.
+*/
+const startOfCivilWeek = (date, weekStartsOn) => {
+	const daysSinceWeekStart = (date.getUTCDay() - weekStartsOn + 7) % 7;
+	return addCivilDays(date, -daysSinceWeekStart);
+};
+/**
+* Counts the columns a span needs.
+*
+* @param from         - Earlier UTC proxy.
+* @param to           - Later UTC proxy.
+* @param weekStartsOn - 0 for Sunday, 1 for Monday.
+* @return Columns needed to cover the span, inclusive.
+*/
+const civilWeekSpan = (from, to, weekStartsOn) => Math.floor((startOfCivilWeek(to, weekStartsOn).getTime() - startOfCivilWeek(from, weekStartsOn).getTime()) / (7 * DAY_MS)) + 1;
+//#endregion
+//#region src/charts/heatmap-chart/build-calendar-data.ts
+/** Rows that get a weekday label (Mon, Wed, Fri with a Monday week start). */
+const LABELLED_ROWS = [
+	0,
+	2,
+	4
+];
+/**
+* Resolve one grid bound: an unparseable or narrowing value falls back to the
+* series' own bound, so the grid can only ever be widened.
+*
+* @param bound     - Requested bound as `yyyy-MM-dd`, if any.
+* @param fallback  - The series' own bound on this side.
+* @param direction - Which way the bound is allowed to move.
+* @return The day key to draw to.
+*/
+const widenTo = (bound, fallback, direction) => {
+	const key = bound ? writtenDayKey(bound) : null;
+	if (!key) {
+		if (bound) warnOnce(`heatmap:gridSpan:${bound}`, `gridSpan.${direction === "earlier" ? "start" : "end"} ${JSON.stringify(bound)} is not a \`yyyy-MM-dd\` day, so the grid is drawn over the series' own span.`);
+		return fallback;
+	}
+	if (direction === "earlier") return key < fallback ? key : fallback;
+	return key > fallback ? key : fallback;
+};
+/**
+* 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`.
+*/
+const buildCalendarHeatmapData = (series, options = {}) => {
+	const weekStartsOn = options.weekStartsOn ?? 1;
+	const hideOutOfRangeDays = options.hideOutOfRangeDays ?? true;
+	const { locale, timeZone } = sanitizeFormatting({
+		locale: options.locale,
+		timeZone: options.timeZone
+	});
+	const readInstant = instantDayReader(timeZone);
+	const valueByDay = /* @__PURE__ */ new Map();
+	let minDayKey;
+	let maxDayKey;
+	for (const point of series) {
+		const key = pointDayKey(point, readInstant);
+		if (!key) {
+			const offending = point.dateString ?? (point.date && String(point.date));
+			warnOnce(`heatmap:unreadableDate:${offending}`, offending ? `${JSON.stringify(offending)} is not a day this can read, so its point is left out of the calendar. A \`dateString\` must start \`yyyy-MM-dd\`.` : "A point carries neither `date` nor `dateString`, so it is left out of the calendar.");
+			continue;
+		}
+		valueByDay.set(key, point.value);
+		if (!minDayKey || key < minDayKey) minDayKey = key;
+		if (!maxDayKey || key > maxDayKey) maxDayKey = key;
+	}
+	if (!minDayKey || !maxDayKey) return {
+		data: [],
+		rowLabels: []
+	};
+	const requestedMinDayKey = widenTo(options.gridSpan?.start, minDayKey, "earlier");
+	const gridMaxDayKey = widenTo(options.gridSpan?.end, maxDayKey, "later");
+	const requestedMinDate = civilDate(requestedMinDayKey);
+	const gridMaxDate = civilDate(gridMaxDayKey);
+	const labelFormatting = {
+		locale,
+		timeZone: "UTC"
+	};
+	const formatWeekday = createDateFormatter({ weekday: "short" }, labelFormatting);
+	const formatMonth = createDateFormatter({ month: "short" }, labelFormatting);
+	const formatDay = createDateFormatter({
+		weekday: "short",
+		month: "short",
+		day: "numeric",
+		year: "numeric"
+	}, labelFormatting);
+	const gridStart = startOfCivilWeek(requestedMinDate, weekStartsOn);
+	const gridMinDayKey = requestedMinDayKey < minDayKey ? civilKey(gridStart) : requestedMinDayKey;
+	const weekCount = civilWeekSpan(gridStart, gridMaxDate, weekStartsOn);
+	const rowLabels = Array.from({ length: 7 }, (_, row) => LABELLED_ROWS.includes(row) ? formatWeekday(addCivilDays(gridStart, row)) : "");
+	const MIN_FIRST_MONTH_WEEKS = 2;
+	const firstMonth = gridStart.getUTCMonth();
+	let firstMonthWeeks = 0;
+	while (firstMonthWeeks < weekCount && addCivilDays(gridStart, firstMonthWeeks * 7).getUTCMonth() === firstMonth) firstMonthWeeks++;
+	const showFirstMonthLabel = !(firstMonthWeeks < weekCount) || firstMonthWeeks >= MIN_FIRST_MONTH_WEEKS;
+	const data = [];
+	let previousMonth = -1;
+	for (let week = 0; week < weekCount; week++) {
+		const columnStart = addCivilDays(gridStart, week * 7);
+		const month = columnStart.getUTCMonth();
+		const label = month !== previousMonth && (week !== 0 || showFirstMonthLabel) ? formatMonth(columnStart) : "";
+		previousMonth = month;
+		const cells = [];
+		for (let row = 0; row < 7; row++) {
+			const day = addCivilDays(gridStart, week * 7 + row);
+			const key = civilKey(day);
+			const cell = {
+				label: formatDay(day),
+				value: valueByDay.has(key) ? valueByDay.get(key) : null
+			};
+			if (key < gridMinDayKey || key > gridMaxDayKey) {
+				if (hideOutOfRangeDays) cell.hidden = true;
+			} else if (key < minDayKey || key > maxDayKey) cell.placeholder = true;
+			cells.push(cell);
+		}
+		data.push({
+			label,
+			data: cells
+		});
+	}
+	return {
+		data,
+		rowLabels
+	};
+};
+//#endregion
 //#region src/charts/heatmap-chart/use-calendar-heatmap-data.ts
 /**
 * `buildCalendarHeatmapData` with the locale and zone taken from