@automattic/charts 4.1.0 → 4.2.0

package/CHANGELOG.md

@@ -5,6 +5,32 @@ 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.2.0] - 2026-09-18
+### Added
+- Bar chart: Add a beside tooltip placement that flips only horizontally. [#52234]
+- Bar chart: Add an optional band highlight. [#52234]
+- Bar chart: Support individual data point colors. [#52234]
+- Heatmap: add `columnGroups` for labeled, gapped column runs, a `keyboardNavigation="calendar"` mode that steps by day, week and month, and `buildMonthCalendarHeatmapData` / `useMonthCalendarHeatmapData`, which draw a date-keyed map as one month calendar per month on a shared scale. The column-label row is omitted when no column has a label, the grid takes an `ariaLabel`, the keyboard selection scrolls into view, calendar labels stay Gregorian under any locale, and `CompleteChartTheme.heatmapChart` gains a required `groupGap`. [#52259]
+- Heatmap chart: Add `tooltipVariant="dark"`, which draws the tooltip on the package's dark tooltip surface, `tooltipStyle` for inline box overrides, and a `variant="bar"` legend that joins the scale steps into one continuous band. [#52368]
+
+### Changed
+- Update package dependencies. [#52187]
+- Update package dependencies. [#52401]
+
+### Fixed
+- Bar chart: Align grid lines with axis ticks (explicit or derived). [#52234]
+- Bar chart: Return focus to the chart after pressing Escape. [#52234]
+- Bar chart: Select the bar under the pointer for tooltips and pointer callbacks. [#52234]
+- Keep keyboard focus on the first or last data point when an arrow key reaches the end of a chart, return focus to the chart when Escape closes a tooltip, skip hidden series during bar chart keyboard navigation, stop a focused chart from swallowing keys it does not use such as Page Down, and close the tooltip when the series it describes is hidden. [#50140]
+
+## [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 +1089,8 @@ 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.2.0]: https://github.com/Automattic/charts/compare/v4.1.1...v4.2.0
+[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.
 
@@ -64,7 +64,7 @@ Two colors are still resolved before visx sees them. `htmlLabel.color`, in `useX
 
 Being resolved in JS, both then carry the bridge's limitations rather than the CSS path's: they read at the scope element, so a role declared on the chart's own class moves the gridlines but leaves the crosshair at the catalog value, and neither repaints on a theme change until something re-renders.
 
-Where a value is *consumed* says nothing about where it is *set*. These are set the same way as every other color — `--a8c-charts-color-background`, `--a8c-charts-color-series-*` — and resolved through `getComputedStyle` against the chart's own scope element, never `document.documentElement`, so both delivery paths obey the same cascade. Each pointer carries a terminal literal (`var(--a8c-charts-color-background, #fff)`) as the last resort for SSR and jsdom, where `getComputedStyle` resolves nothing.
+Where a value is *consumed* says nothing about where it is *set*. These are set the same way as every other catalog color — `--a8c-charts-color-background`, `--a8c-charts-color-series-*` — and resolved through `getComputedStyle` against the chart's own scope element, never `document.documentElement`, so both delivery paths obey the same cascade. Each pointer carries a terminal literal (`var(--a8c-charts-color-background, #fff)`) as the last resort for SSR and jsdom, where `getComputedStyle` resolves nothing.
 
 The scope element is the wrapper a chart is rendered into, which sits **above** the element the chart's own `className` lands on, so a role declared on that inner element is invisible to the JS bridge. `.line-chart { --a8c-charts-color-background: red }` therefore does not reach the glyph strokes, while `.line-chart { --a8c-charts-color-grid: red }` does reach the gridlines — the CSS-painted roles read at the painted element, so any ancestor of it will do. Scope a rule for a JS-resolved role to a wrapper around the chart rather than to the chart itself. CHARTS-255 tracks closing the remainder.
 
@@ -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".