@automattic/charts 2.0.0 → 3.0.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).
 
+## [3.0.0] - 2026-08-21
+### Changed
+- Emit the `--a8c-charts-*` token catalog on the charts provider, so any token can be overridden in CSS anywhere inside it or through the `theme` prop, and resolve tokens against the chart element so CSS-painted and SVG-painted colors honour the same override. A `theme`-prop override keeps the reach of the field it was set from: `svgLabelSmall.fill` moves the SVG axis labels without touching legend labels or heatmap cell values, and `backgroundColor` repaints the chart background without touching tooltips, the annotation label or the zoom-reset control.
+  
+  `useChartRegistration` and `useChartScopeElement` are now exported from the package root. Both were documented with a `@automattic/charts` import that did not resolve.
+  
+  Breaking changes:
+  
+  - An override set above `GlobalChartsProvider` — on `:root`, on `body`, or on any other ancestor — no longer applies, because the provider declares the role on its own wrapper and a declaration beats a value inherited from further up the tree. Replace `:root { --a8c-charts-… }` with `.a8c-charts-scope { --a8c-charts-… }`, which themes the whole page as before: it matches every provider wrapper, including the one a bare chart mounts for itself and the one a portal-rendered tooltip carries.
+  - `@wordpress/theme`'s `ThemeProvider` must sit above the charts provider rather than between it and a chart, or CSS-painted colors keep their light-mode defaults.
+  - The override names that predate the `--a8c-charts-{category}-{name}` convention are removed. Set `--a8c-charts-color-trend-up`, `--a8c-charts-color-trend-down` and `--a8c-charts-color-trend-neutral` in place of `--charts-trend-up-color`, `--charts-trend-down-color` and `--charts-trend-neutral-color`, and `--a8c-charts-border-radius-leaderboard-bar` in place of `--a8c--charts--leaderboard--bar--border-radius`.
+  - `--a8c-charts-color-focus` is removed. Focus and selection rings follow `--wpds-color-stroke-focus`, so override that token instead.
+  - The `GridProps` type is removed. It described a grid component that was never exported and is no longer part of the package; gridlines are drawn and coloured by the chart itself.
+  - `resolveThemeColor` is removed from the value returned by `useGlobalChartsContext`. It resolved against the `GlobalChartsProvider` wrapper, so it could not see an override set closer to a single chart — the reason every chart that needed a resolved color stopped calling it. Call `normalizeColorToHex( value, useChartScopeElement(), resolveCssVariable )` instead, which resolves at the scope the same override paints CSS at. `resolveCssVariable` is now exported for this. [#51308]
+
+## [2.0.1] - 2026-08-19
+### Changed
+- Charts: adapt bar chart time-axis tick labels to the data's bucket resolution and time span, support the `tickResolution` hint, and name each bar's bucket in its tooltip. [#51274]
+- Resolve an XY chart theme's color roles from a single computed-style snapshot, and rebuild the theme only when a series color changes rather than on every render. [#51342]
+
+### Fixed
+- Charts: keep a bar chart's time axis on the buckets it actually draws, so a labelled bar, a comparison series, or a series hidden from the legend can no longer strand a tick at the axis origin, and label such a bar by its label in both the axis and the tooltip. [#51343]
+- Charts: keep the year and the day on a bar chart's time axis, which could previously skip the tick that named them, and stop the same label falling on two ticks in a row. [#51339]
+- Charts: measure a horizontal chart's left margin from the labels it will actually draw, so a caller's tick formatter is applied exactly once and time-of-day labels stop reserving room for the string "Invalid Date". [#51272]
+- Charts: stop a bar chart's time axis dropping to a couple of ticks when it reaches for the year, and speed up how it picks them. [#51339]
+
 ## [2.0.0] - 2026-08-10
 ### Added
 - Time axis: Accept a tickResolution hint on the x-axis options so callers that know the data's bucket size can set tick formats directly instead of relying on inference. [#51017]
@@ -965,6 +991,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]
 
+[3.0.0]: https://github.com/Automattic/charts/compare/v2.0.1...v3.0.0
+[2.0.1]: https://github.com/Automattic/charts/compare/v2.0.0...v2.0.1
 [2.0.0]: https://github.com/Automattic/charts/compare/v1.12.0...v2.0.0
 [1.12.0]: https://github.com/Automattic/charts/compare/v1.11.0...v1.12.0
 [1.11.0]: https://github.com/Automattic/charts/compare/v1.10.3...v1.11.0

package/TOKENS.md

@@ -1,24 +1,86 @@
 # Charts CSS custom-property catalog
 
-`@automattic/charts` exposes its themeable values as CSS custom properties under a
-single convention: `--a8c-charts-{category}-{name}`. `{category}` mirrors the WPDS
-token type (`color`, `dimension`, `border-radius`).
+`@automattic/charts` exposes its themeable values as CSS custom properties under a single convention: `--a8c-charts-{category}-{name}`. `{category}` mirrors the WPDS token type (`color`, `dimension`, `border-radius`).
 
-## How it resolves today
+## How it resolves
 
-Nothing emits these variables at runtime yet (that is CHARTS-203). Each reference in
-the library carries its default inline as a fallback:
+`src/styles/chart-scope.scss` declares the whole catalog once, on the `GlobalChartsProvider` wrapper, via `:where(.a8c-charts-scope)`. `:where()` keeps the rule at zero specificity, so a consumer rule targeting that same element wins without `!important`. It is declared on the wrapper rather than `:root` because `@wordpress/theme`'s `ThemeProvider` emits its generated `--wpds-*` ramp as inline styles on its own wrapper div — a `:root` declaration would miss a `ThemeProvider` entirely.
+
+Chart roots deliberately do *not* carry the `a8c-charts-scope` class. Custom properties inherit down the tree, and an element only shadows an inherited value by re-declaring it, so a chart root that re-declared the catalog would beat an override set between it and the provider — closing off the one place consumers are meant to set overrides. This inheritance rule drives every precedence question below.
+
+Portal-rendered tooltips carry the class unconditionally, because a React portal renders outside the provider's DOM tree and would otherwise inherit nothing. `TrendIndicator`, `BaseTooltip` and `BaseLegend` carry it only when no provider is above them (`useStandaloneScopeClass()`).
+
+That unconditional class has a cost: a portal tooltip re-declares the catalog on itself, so it sees only the catalog *default*, never an instance override — both the provider's inline `theme` var and a consumer rule scoped to the provider wrapper live on an ancestor the portal is not a descendant of. A bare `.a8c-charts-scope { … }` rule does reach it, matching the tooltip's own class directly.
+
+Each catalog entry maps to a WPDS token with the WPDS spec value as its fallback:
+
+```scss
+:where(.a8c-charts-scope) {
+	--a8c-charts-color-grid: var(--wpds-color-stroke-surface-neutral, #dbdbdb);
+}
+```
+
+Charts reference the catalog bare — `stroke: var(--a8c-charts-color-grid)`. For anything that *is* a catalog role, `chart-scope.scss` is the only place its `--wpds-*` mapping is named, so design-system churn lands in one file. One kind of `--wpds-*` reference lives outside it, deliberately: **values that are not chart roles** — incidental typography, padding, gap and interaction motion read their design-system token directly at the call site, as interface chrome that should track the host's theme rather than charts-level theming.
+
+### Precedence
+
+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 theme layer `GlobalChartsProvider` writes inline from a `theme` prop override — see below.
+4. The catalog default on the provider wrapper, resolving the mapped `--wpds-*` token.
+5. The WPDS spec-value fallback, when no `--wpds-*` token is set either (SSR, jsdom, or WPDS not loaded).
+
+A CSS declaration of a role therefore beats a `theme` prop override *anywhere* it is set, the wrapper included — the prop writes a variable the role reads, not the role itself, and a role declared in CSS never reads it.
+
+An override set **above** `GlobalChartsProvider` does not apply: the provider's own declaration on its wrapper beats a value merely inherited from an ancestor. Set overrides inside the provider tree, or target the scope class itself — `.a8c-charts-scope { --a8c-charts-color-grid: #e0e0e0; }` matches every provider wrapper on the page, including the one a bare chart mounts for itself and the one a portal tooltip carries, and outranks the zero-specificity catalog default. That rule is the replacement for a page-level `:root` override. The same rule limits `@wordpress/theme`'s `ThemeProvider` to *above* the charts provider: the catalog substitutes its `--wpds-*` tokens at the wrapper, so a `ThemeProvider` mounted between the wrapper and a chart is never consulted and CSS-painted colours keep their light-mode spec fallbacks. The JS-painted ones do not — `getElementStyles` resolves at the chart element — so that nesting shows up as a chart whose SVG marks retint while its gridlines and surfaces do not.
+
+#### The theme layer
+
+Each of the five roles a `theme` prop field can override is declared reading a `*-theme` variable first:
 
 ```scss
-stroke: var(--a8c-charts-color-grid, var(--wpds-color-stroke-surface-neutral, #dbdbdb));
+:where(.a8c-charts-scope) {
+	--a8c-charts-color-grid: var(--a8c-charts-color-grid-theme, var(--wpds-color-stroke-surface-neutral, #dbdbdb));
+}
 ```
 
-So an `--a8c-charts-*` variable you set on a chart container wins; otherwise the
-mapped `--wpds-*` token wins; otherwise the spec-value hex wins. Setting any
-`--a8c-charts-*` variable on a chart ancestor overrides that role.
+`GlobalChartsProvider` writes `--a8c-charts-color-grid-theme` inline from `theme.gridStyles.stroke`. Publishing the consumer's value one layer out is what keeps the catalog default reachable: a value that is invalid at computed-value time — `var(--wpds-color-stroke-surface-neutral)` with no fallback, in a host that never loaded the WPDS stylesheet — invalidates only the theme layer, and the role still resolves its mapped token. Written as the role itself, that same value made the role guaranteed-invalid, and that propagates to every bare `var(--a8c-charts-color-grid)` read site: `stroke` computed to `unset`, so the gridlines disappeared rather than degrading to the spec grey.
+
+A value that reads the role it would override is not published at all. The role reads its theme layer, so such a value closes a cycle through the catalog entry, and CSS marks *every* custom property in a cycle invalid — the role's own fallback is not used, and the token resolves to nothing. `withCatalogPointers` restores the theme field to the catalog pointer whether or not the value was published, so visx never paints a literal the CSS side cannot see.
+
+`src/styles/test/chart-scope.test.ts` pins which roles carry the layer, from the same list the provider maps fields with.
+
+#### A `theme`-prop override keeps the reach of the field it was set from
+
+A role is a shared name, so publishing an override as a custom property could widen it — `theme={ { svgLabelSmall: { fill: 'purple' } } }` recolouring legend labels, heatmap cell values, funnel labels and the line-chart tooltip along with the SVG axis labels it names.
+
+It doesn't, because a mapped field publishes a role read by exactly the elements that field already controlled. Where the obvious role has wider readership, one side or the other gets a role of its own:
+
+| Theme field | Publishes | Kept off it | How |
+|---|---|---|---|
+| `svgLabelSmall.fill` | `--a8c-charts-color-label-axis` | legend labels, `.heatmap-chart__cell-value`, funnel labels, the line-chart tooltip | the field takes a narrow role deriving from `--a8c-charts-color-label` |
+| `backgroundColor` | `--a8c-charts-color-background` | the annotation label, `.x-zoom__reset`, tooltips | those readers take `--a8c-charts-color-surface` instead |
+
+**The two are shaped differently, and the difference is load-bearing.** `--a8c-charts-color-label-axis` *derives* from `--a8c-charts-color-label`: the theme field publishes the narrow role, so the broad one stays free as a move-every-label knob. `--a8c-charts-color-surface` is a **sibling** of `--a8c-charts-color-background`, not a child — there the theme field publishes the broad role, so deriving would hand the override straight back to the surfaces it is meant to spare. Deriving is only safe when the narrow role is the one the `theme` prop writes.
+
+The consequence: `--a8c-charts-color-label` moves every label, but no single role repaints the chart background and the floating surfaces together.
+
+`gridStyles.stroke`, `xAxisLineStyles.stroke` and `xTickLineStyles.stroke` need no narrow role — nothing outside the element each names reads their role.
+
+### The SVG bridge
+
+visx and Google Charts apply colours as SVG presentation attributes, where `var()` does not resolve. Those colours are resolved in JS through `getComputedStyle` against the chart's own scope element — never `document.documentElement` — so both delivery paths obey the same cascade. The JS theme in `themes.ts` therefore holds a bare catalog pointer with a terminal literal (`var(--a8c-charts-color-grid, #dbdbdb)`); the literal is 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. A role declared on that inner element is therefore invisible to this bridge: `.line-chart { --a8c-charts-color-grid: red }` recolours what the chart paints in CSS and leaves the gridlines, axis lines and tick labels at the inherited value, because the SVG carries a value already resolved higher up. Scope such a rule to a wrapper around the chart, not to the chart itself. CHARTS-255 tracks closing this.
+
+`GeoChart` (Google Charts) takes a resolved-hex snapshot at render, so it does not live-update on a theme change without a re-render.
 
 ## 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.
+
 | Role | Maps to `--wpds-*` | Fallback |
 |---|---|---|
 | `--a8c-charts-color-grid` | `--wpds-color-stroke-surface-neutral` | `#dbdbdb` |
@@ -27,64 +89,61 @@ mapped `--wpds-*` token wins; otherwise the spec-value hex wins. Setting any
 | `--a8c-charts-color-label` | `--wpds-color-foreground-content-neutral` | `#1e1e1e` |
 | `--a8c-charts-color-label-secondary` | `--wpds-color-foreground-content-neutral-weak` | `#707070` |
 | `--a8c-charts-color-label-inverse` | `--wpds-color-foreground-interactive-neutral-strong` | `#f0f0f0` |
-| `--a8c-charts-color-label-on-fill` | _(none — white-on-series-fill, no WPDS fit)_ | `#FFFFFF` |
+| `--a8c-charts-color-label-on-fill` | _(none — white-on-series-fill, no WPDS fit)_ | `#fff` |
+| `--a8c-charts-color-label-axis` | _(derives from `--a8c-charts-color-label`)_ | — |
 | `--a8c-charts-color-annotation` | `--wpds-color-foreground-content-neutral` | `#1e1e1e` |
 | `--a8c-charts-color-trend-up` | `--wpds-color-foreground-content-success-weak` | `#008030` |
 | `--a8c-charts-color-trend-down` | `--wpds-color-foreground-content-error-weak` | `#cc1818` |
 | `--a8c-charts-color-trend-neutral` | `--wpds-color-foreground-content-neutral-weak` | `#707070` |
 | `--a8c-charts-color-background` | `--wpds-color-background-surface-neutral-strong` | `#fff` |
+| `--a8c-charts-color-surface` | `--wpds-color-background-surface-neutral-strong` | `#fff` |
 | `--a8c-charts-color-surface-secondary` | `--wpds-color-background-surface-neutral-weak` | `#f4f4f4` |
 | `--a8c-charts-color-track` | `--wpds-color-background-track-neutral-weak` | `#f0f0f0` |
-| `--a8c-charts-color-tooltip-surface` | _(none — translucent dark surface, no WPDS fit)_ | `rgba(0,0,0,0.85)` |
-| `--a8c-charts-color-focus` | `--wpds-color-stroke-focus` | `#3858e9` |
+| `--a8c-charts-color-tooltip-surface` | _(none — translucent dark surface, no WPDS fit)_ | `rgb(0 0 0 / 85%)` |
+
+Axis and tick share grid's WPDS token but stay distinct roles, so the three can be themed independently.
 
-`--a8c-charts-color-axis` (axis line) and `--a8c-charts-color-tick` (tick marks)
-resolve to the same value as `--a8c-charts-color-grid` by default. They are kept as
-distinct roles so axis, tick marks, and gridlines can be themed independently; each
-maps directly to its own `--wpds-*` token rather than chaining through `grid`.
+## Non-colour roles
+
+| Role | Maps to `--wpds-*` | Fallback |
+|---|---|---|
+| `--a8c-charts-motion-duration-entrance` | `--wpds-motion-duration-xl` | `400ms` |
+| `--a8c-charts-motion-easing-entrance` | `--wpds-motion-easing-expressive` | `cubic-bezier(0.25, 0, 0, 1)` |
+| `--a8c-charts-border-radius-bar` | `--wpds-border-radius-md` | `4px` |
+| `--a8c-charts-border-radius-cell` | `--wpds-border-radius-sm` | `2px` |
+| `--a8c-charts-border-radius-leaderboard-bar` | _(none — pill shape, no WPDS radius fits)_ | `9999px` |
+| `--a8c-charts-elevation-xs` | _(none — `--wpds-elevation-*` removed in theme 1.0.0)_ | `0 1px 1px 0 #00000008, 0 1px 2px 0 #00000005, 0 3px 3px 0 #00000005, 0 4px 4px 0 #00000003` |
+| `--a8c-charts-elevation-sm` | _(none — `--wpds-elevation-*` removed in theme 1.0.0)_ | `0 1px 2px 0 #0000000d, 0 2px 3px 0 #0000000a, 0 6px 6px 0 #00000008, 0 8px 8px 0 #00000005` |
+
+The motion pair carries the one-shot reveal a data mark plays on first paint, across all six charts that animate in. It deliberately does **not** cover interaction motion: hover and transition timings read `--wpds-motion-*` directly, as interface chrome rather than a chart role.
+
+The elevation fallbacks hold the values their removed `--wpds-elevation-*` tokens used to resolve to, until a replacement exists.
 
 ## Tier 2 — component-specific variables
 
-Instance styling knobs, on the same convention but not shared semantic roles:
-`--a8c-charts-border-radius-leaderboard-bar`,
-`--a8c-charts-dimension-leaderboard-bar-hover-inset`,
-`--a8c-charts-color-heatmap-*`, `--a8c-charts-dimension-heatmap-*`,
-`--a8c-charts-heatmap-cell-intensity`,
-`--a8c-charts-color-zoom-selection`, `--a8c-charts-color-zoom-selection-stroke`,
-`--a8c-charts-elevation-xs`.
+Instance styling knobs, on the same convention but not shared semantic roles: `--a8c-charts-dimension-leaderboard-bar-hover-inset`, `--a8c-charts-color-heatmap-*`, `--a8c-charts-dimension-heatmap-*`, `--a8c-charts-heatmap-cell-intensity`, `--a8c-charts-color-zoom-selection`, `--a8c-charts-color-zoom-selection-stroke`.
 
 | Role | Maps to `--wpds-*` | Fallback |
 |---|---|---|
 | `--a8c-charts-color-zoom-selection` | `--wpds-color-background-interactive-brand-strong` | `#3858e9` |
 | `--a8c-charts-color-zoom-selection-stroke` | `--wpds-color-stroke-interactive-brand` | `#3858e9` |
-| `--a8c-charts-elevation-xs` | _(none — `--wpds-elevation-*` removed in theme 1.0.0)_ | `0 1px 1px 0 #00000008, 0 1px 2px 0 #00000005, 0 3px 3px 0 #00000005, 0 4px 4px 0 #00000003` |
 
-The zoom selection roles carry the drag-to-zoom rectangle's fill and border. Their
-translucency is not part of the role: it lives in the `fill-opacity` /
-`stroke-opacity` properties, so overriding either role sets an opaque colour and
-keeps the intended transparency.
+The zoom selection roles' translucency is not part of the role — it lives in `fill-opacity` / `stroke-opacity`, so an override sets an opaque colour and keeps the intended transparency.
 
-`--a8c-charts-elevation-xs` carries the zoom reset button's shadow. It has no
-`--wpds-*` mapping: `@wordpress/theme` 1.0.0 removed the whole
-`--wpds-elevation-*` group without a replacement, so the fallback holds the value
-`--wpds-elevation-xs` used to resolve to.
+`--a8c-charts-heatmap-cell-intensity` is the one variable without a `{category}` segment: it holds a unitless 0–1 scalar consumed inside `color-mix()`, not a colour.
 
-`--a8c-charts-heatmap-cell-intensity` is the one variable without a `{category}`
-segment: it holds a unitless 0–1 scalar consumed inside `color-mix()`, not a colour.
+The heatmap Tier-2 variables and `--a8c-charts-dimension-leaderboard-bar-hover-inset` are **component-emitted** — set from JS per render, or in the component's own stylesheet — rather than on the provider wrapper. They are deliberately absent from `chart-scope.scss` and are not consumer override points in the same sense as the catalog above.
 
-The heatmap Tier-2 variables (`--a8c-charts-color-heatmap-*`,
-`--a8c-charts-dimension-heatmap-*`, `--a8c-charts-heatmap-cell-intensity`) are
-**component-emitted** — the chart sets them from JS per render — not consumer
-override points.
+## Removed override variables
 
-## Public override variables
+Every role in the catalog is a supported override point, on the precedence rules above. These names are not, and no longer resolve — set the replacement instead:
 
-These are documented, supported override points. Deprecated names still work — they
-are read as an inner fallback behind the new name:
-
-| New | Deprecated alias |
+| Removed | Set instead |
 |---|---|
-| `--a8c-charts-color-trend-up` | `--charts-trend-up-color` |
-| `--a8c-charts-color-trend-down` | `--charts-trend-down-color` |
-| `--a8c-charts-color-trend-neutral` | `--charts-trend-neutral-color` |
-| `--a8c-charts-border-radius-leaderboard-bar` | `--a8c--charts--leaderboard--bar--border-radius` |
+| `--charts-trend-up-color` | `--a8c-charts-color-trend-up` |
+| `--charts-trend-down-color` | `--a8c-charts-color-trend-down` |
+| `--charts-trend-neutral-color` | `--a8c-charts-color-trend-neutral` |
+| `--a8c--charts--leaderboard--bar--border-radius` | `--a8c-charts-border-radius-leaderboard-bar` |
+| `--a8c-charts-color-focus` | `--wpds-color-stroke-focus` |
+
+Removing the first four also removes a second name for a role, read at its component's own call site rather than through the catalog: each sat inside the role as its fallback — `var(--a8c-charts-*, var(--deprecated-name, …))` — so it applied only where the role itself was unset. No `--a8c-charts-*` role is now read anywhere but bare.