@automattic/charts 3.2.0 → 4.0.0

package/src/providers/chart-context/test/use-global-charts-theme.test.tsx

@@ -22,21 +22,12 @@ describe( 'useGlobalChartsTheme', () => {
 
 	describe( 'with GlobalChartsProvider', () => {
 		it( 'should return merged theme when provider has custom theme', () => {
-			const customTheme = { colors: [ '#FF0000', '#00FF00', '#0000FF' ] };
-			const wrapper = createWrapper( customTheme );
+			const wrapper = createWrapper( { tickLength: 9 } );
 
 			const { result } = renderHook( () => useGlobalChartsTheme(), { wrapper } );
 
-			// `theme.colors` publishes the palette's theme layers, so the merged theme holds catalog pointers rather than the consumer's literals. Each keeps its consumer color as the pointer's terminal literal, for SSR and jsdom.
-			expect( result.current.colors ).toEqual( [
-				'var(--a8c-charts-color-series-1, #FF0000)',
-				'var(--a8c-charts-color-series-2, #00FF00)',
-				'var(--a8c-charts-color-series-3, #0000FF)',
-				'var(--a8c-charts-color-series-4)',
-				'var(--a8c-charts-color-series-5)',
-			] );
-			// Other properties should still come from default theme
-			expect( result.current.backgroundColor ).toBe( defaultTheme.backgroundColor );
+			expect( result.current.tickLength ).toBe( 9 );
+			// Everything the consumer did not set still comes from the default theme.
 			expect( result.current.gridStyles ).toEqual( defaultTheme.gridStyles );
 		} );
 
@@ -46,13 +37,12 @@ describe( 'useGlobalChartsTheme', () => {
 			const { result } = renderHook( () => useGlobalChartsTheme(), { wrapper } );
 
 			expect( result.current ).toEqual( defaultTheme );
-			expect( result.current.colors ).toBe( defaultTheme.colors );
 		} );
 	} );
 
 	describe( 'theme stability', () => {
 		it( 'should return the same theme object when provider theme does not change', () => {
-			const customTheme = { colors: [ '#FF0000' ] };
+			const customTheme = { tickLength: 9 };
 			const wrapper = createWrapper( customTheme );
 
 			const { result, rerender } = renderHook( () => useGlobalChartsTheme(), { wrapper } );
@@ -68,20 +58,12 @@ describe( 'useGlobalChartsTheme', () => {
 
 	describe( 'edge cases', () => {
 		it( 'should handle null/undefined theme values gracefully', () => {
-			const customTheme = { colors: undefined };
-			const wrapper = createWrapper( customTheme );
+			const customTheme = { tickLength: undefined };
+			const wrapper = createWrapper( customTheme as unknown as Partial< ChartTheme > );
 
 			const { result } = renderHook( () => useGlobalChartsTheme(), { wrapper } );
 
-			// Should still return a complete theme with undefined colors
-			expect( result.current.backgroundColor ).toBe( defaultTheme.backgroundColor );
-			expect( result.current.colors ).toBeUndefined();
-		} );
-
-		it( 'should not throw when GlobalChartsContext is not available', () => {
-			expect( () => {
-				renderHook( () => useGlobalChartsTheme() );
-			} ).not.toThrow();
+			expect( result.current.gridStyles ).toEqual( defaultTheme.gridStyles );
 		} );
 	} );
 } );

package/src/providers/chart-context/themes.ts

@@ -1,38 +1,24 @@
-import { SERIES_PALETTE_POINTERS } from './private/series-palette';
 import type { CompleteChartTheme } from '../../types';
 
 /**
- * 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`.
  */
 const defaultTheme: CompleteChartTheme = {
-	backgroundColor: 'var(--a8c-charts-color-background, #fff)',
-	labelBackgroundColor: 'var(--a8c-charts-color-label-background, transparent)',
-	// White label text sits on top of arbitrary series colors, so it has no WPDS content-foreground equivalent. Every other color here is a bare pointer at the catalog emitted by `chart-scope.scss`; the terminal literal is the last resort for the SSR and jsdom paths, where getComputedStyle resolves nothing.
-	labelTextColor: 'var(--a8c-charts-color-label-on-fill, #FFFFFF)',
-	// Derived, not authored: the slot manifest lives in `private/series-palette.ts` because which
-	// slots exist describes the catalog, not the theme. The field itself is still load-bearing —
-	// see that file for why the provider reads the palette through the theme and what has to move
-	// before this can be deleted.
-	colors: [ ...SERIES_PALETTE_POINTERS ],
 	gridStyles: {
-		stroke: 'var(--a8c-charts-color-grid, #dbdbdb)',
 		strokeWidth: 1,
 	},
 	tickLength: 4,
-	gridColor: '',
-	gridColorDark: '',
 	xTickLineStyles: {
-		stroke: 'var(--a8c-charts-color-tick, #dbdbdb)',
 		strokeWidth: 1,
 	},
 	xAxisLineStyles: {
-		stroke: 'var(--a8c-charts-color-axis, #dbdbdb)',
 		strokeWidth: 1,
 	},
 	legend: {
-		labelStyles: {
-			color: 'var(--a8c-charts-color-label, #1e1e1e)',
-		},
+		labelStyles: {},
 		containerStyles: {},
 		shapeStyles: [],
 	},
@@ -44,42 +30,12 @@ const defaultTheme: CompleteChartTheme = {
 	// elements for axis labels and ticks. Setting `inherit` lets SVG text
 	// pick up the host application's font-family via normal CSS inheritance.
 	svgLabelSmall: {
-		fill: 'var(--a8c-charts-color-label-axis, #1e1e1e)',
 		fontFamily: 'inherit',
 	},
 	svgLabelBig: { fontFamily: 'inherit' },
-	annotationStyles: {
-		label: {
-			anchorLineStroke: 'var(--a8c-charts-color-annotation, #1e1e1e)',
-			backgroundFill: 'var(--a8c-charts-color-surface, #fff)',
-		},
-		connector: {
-			stroke: 'var(--a8c-charts-color-annotation, #1e1e1e)',
-		},
-		circleSubject: {
-			stroke: 'transparent',
-			fill: 'var(--a8c-charts-color-annotation, #1e1e1e)',
-			radius: 5,
-		},
-	},
-	geoChart: {
-		featureFillColor: 'var(--a8c-charts-color-surface-secondary, #f4f4f4)',
-	},
+	annotationStyles: {},
 	leaderboardChart: {
-		rowGap: 12,
-		columnGap: 4,
 		labelSpacing: 'xs',
-		// [negative, neutral, positive]
-		deltaColors: [
-			'var(--a8c-charts-color-trend-down, #cc1818)',
-			'var(--a8c-charts-color-trend-neutral, #707070)',
-			'var(--a8c-charts-color-trend-up, #008030)',
-		],
-	},
-	conversionFunnelChart: {
-		backgroundColor: 'var(--a8c-charts-color-surface-secondary, #f4f4f4)',
-		positiveChangeColor: 'var(--a8c-charts-color-trend-up, #008030)',
-		negativeChangeColor: 'var(--a8c-charts-color-trend-down, #cc1818)',
 	},
 	lineChart: {
 		lineStyles: {
@@ -101,8 +57,7 @@ const defaultTheme: CompleteChartTheme = {
 		margin: { top: 2, right: 2, bottom: 2, left: 2 },
 		strokeWidth: 1.5,
 	},
-	// `primaryColor` is left unset so it falls back to the palette's `colors[0]`. The compact
-	// 11px square / 2px gap is the contribution-graph rhythm, which has no WPDS dimension.
+	// The compact 11px square / 2px gap is the contribution-graph rhythm, which has no WPDS dimension.
 	heatmapChart: {
 		compactCellGap: 2,
 		compactCellSize: 11,

package/src/providers/chart-context/types.ts

@@ -2,6 +2,7 @@ import { CSSProperties, ReactNode } from 'react';
 import type { BaseLegendItem } from '../../components/legend';
 import type {
 	BarStyles,
+	ChartFormatting,
 	ChartType,
 	CompleteChartTheme,
 	DataPointPercentage,
@@ -37,6 +38,8 @@ export 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;
 	// Series visibility management shared by charts, legends, and programmatic controls.
 	toggleSeriesVisibility: ( chartId: string, seriesLabel: string ) => void;

package/src/styles/chart-scope.scss

@@ -10,16 +10,6 @@
 // the same element wins. Chart roots deliberately do NOT re-declare these: an
 // element's own declaration beats an inherited one, so re-declaring lower down
 // would shadow a consumer override set inside the provider tree.
-
-// The roles a `theme` prop field can override read a `*-theme` variable first,
-// which GlobalChartsProvider writes inline from that field. Publishing the
-// consumer's value one layer out keeps the catalog default reachable: a value
-// that is invalid at computed-value time (a fallback-less `var()` naming a
-// token nothing set, which is how premium-analytics passes its grid stroke)
-// invalidates only the `*-theme` variable, leaving the role's own fallback to
-// resolve. Written as the role directly, it made the role guaranteed-invalid
-// and took every bare read site with it.
-// `src/styles/test/chart-scope.test.ts` pins which roles carry the layer.
 :where(.a8c-charts-scope) {
 	// The series palette. GlobalChartsProvider resolves these five slots at its
 	// wrapper and seeds ColorCache with whatever resolves; a slot that resolves
@@ -35,58 +25,42 @@
 	// admin color. Leading with the admin color costs nothing:
 	// @wordpress/theme writes --wp-admin-theme-color from a provider's own
 	// accent as a legacy wp-admin override, so a provider accent still wins.
-
-	// DO NOT SIMPLIFY the chain below. The innermost
-	// var(--wp-admin-theme-color, #3858e9) is unreachable — the outer leg
-	// already tried that variable — and reads like a copy-paste mistake. It is
-	// the design system's own spec value for the WPDS token, which
-	// `src/styles/test/wpds-fallbacks.test.ts` compares against literally, so
-	// collapsing it to a bare hex fails that test. Reordering to put the WPDS
-	// token first passes every test and breaks only on a host with no root
-	// provider.
-
-	// That test scans this file as text, comments included, so do not write an
-	// example --wpds-* reference in a comment here — it is read as a real one.
-	--a8c-charts-color-series-1: var(--a8c-charts-color-series-1-theme, var(--wp-admin-theme-color, var(--wpds-color-foreground-interactive-brand, var(--wp-admin-theme-color, #3858e9))));
-	--a8c-charts-color-series-2: var(--a8c-charts-color-series-2-theme);
-	--a8c-charts-color-series-3: var(--a8c-charts-color-series-3-theme);
-	--a8c-charts-color-series-4: var(--a8c-charts-color-series-4-theme);
-	--a8c-charts-color-series-5: var(--a8c-charts-color-series-5-theme);
-	--a8c-charts-color-grid: var(--a8c-charts-color-grid-theme, var(--wpds-color-stroke-surface-neutral, #dbdbdb));
-	--a8c-charts-color-axis: var(--a8c-charts-color-axis-theme, var(--wpds-color-stroke-surface-neutral, #dbdbdb));
-	--a8c-charts-color-tick: var(--a8c-charts-color-tick-theme, var(--wpds-color-stroke-surface-neutral, #dbdbdb));
-	--a8c-charts-color-label: var(--wpds-color-foreground-content-neutral, #1e1e1e);
-	--a8c-charts-color-label-secondary: var(--wpds-color-foreground-content-neutral-weak, #707070);
-	--a8c-charts-color-label-inverse: var(--wpds-color-foreground-interactive-neutral-strong, #f0f0f0);
-	// White label text sits on arbitrary series colors, so it has no WPDS
-	// content-foreground equivalent.
-	--a8c-charts-color-label-on-fill: var(--a8c-charts-color-label-on-fill-theme, #fff);
+	--a8c-charts-color-series-1: var(--wp-admin-theme-color, var(--wpds-color-foreground-interactive-brand));
+	--a8c-charts-color-grid: var(--wpds-color-stroke-surface-neutral);
+	--a8c-charts-color-axis-x: var(--wpds-color-stroke-surface-neutral);
+	--a8c-charts-color-tick-x: var(--wpds-color-stroke-surface-neutral);
+	// The y axis carries labels only until one of these is declared. `none`
+	// rather than `transparent` keeps the line out of hit-testing too.
+	--a8c-charts-color-axis-y: none;
+	--a8c-charts-color-tick-y: none;
+	--a8c-charts-color-label: var(--wpds-color-foreground-content-neutral);
+	--a8c-charts-color-label-secondary: var(--wpds-color-foreground-content-neutral-weak);
+	// Label text on a filled surface — a pie segment, a heatmap cell.
+	--a8c-charts-color-label-inverse: var(--wpds-color-foreground-interactive-neutral-strong);
 	// The plate behind a pie-slice label. Transparent by default, so a label
 	// reads straight off the slice; there is no WPDS token for "no surface".
-	--a8c-charts-color-label-background: var(--a8c-charts-color-label-background-theme, transparent);
-	// The SVG axis and tick labels. `svgLabelSmall.fill` publishes THIS role, so
-	// deriving from --a8c-charts-color-label is safe and wanted: the theme field
-	// moves only these labels, while setting the broad role in CSS still moves
-	// every label at once. (--a8c-charts-color-surface cannot derive the same
-	// way — see its comment; there the theme field owns the broad role.)
-	--a8c-charts-color-label-axis: var(--a8c-charts-color-label-axis-theme, var(--a8c-charts-color-label));
-	--a8c-charts-color-annotation: var(--wpds-color-foreground-content-neutral, #1e1e1e);
-	--a8c-charts-color-trend-up: var(--wpds-color-foreground-content-success-weak, #008030);
-	--a8c-charts-color-trend-down: var(--wpds-color-foreground-content-error-weak, #cc1818);
-	--a8c-charts-color-trend-neutral: var(--wpds-color-foreground-content-neutral-weak, #707070);
-	--a8c-charts-color-background: var(--a8c-charts-color-background-theme, var(--wpds-color-background-surface-neutral-strong, #fff));
-	// Surfaces that float over the chart — tooltips, the annotation label, the
-	// zoom-reset control. Same WPDS token as --a8c-charts-color-background, and
-	// deliberately NOT derived from it: `backgroundColor` publishes the
-	// background role, so deriving would let that theme field repaint these too.
-	// Sibling of the background role, not a child of it.
-	--a8c-charts-color-surface: var(--wpds-color-background-surface-neutral-strong, #fff);
-	--a8c-charts-color-surface-secondary: var(--wpds-color-background-surface-neutral-weak, #f4f4f4);
-	--a8c-charts-color-track: var(--wpds-color-background-track-neutral-weak, #f0f0f0);
+	// The literal is load-bearing: a `fill` reading a fallback-less var() on an
+	// undeclared property drops the declaration and paints black instead.
+	--a8c-charts-color-label-background: transparent;
+	// The SVG axis and tick labels. Narrower than --a8c-charts-color-label and
+	// derived from it, so setting the broad role moves every label at once while
+	// setting this one moves only the axis.
+	--a8c-charts-color-label-axis: var(--a8c-charts-color-label);
+	--a8c-charts-color-annotation: var(--wpds-color-foreground-content-neutral);
+	--a8c-charts-color-trend-up: var(--wpds-color-foreground-content-success-weak);
+	--a8c-charts-color-trend-down: var(--wpds-color-foreground-content-error-weak);
+	--a8c-charts-color-trend-neutral: var(--wpds-color-foreground-content-neutral-weak);
+	--a8c-charts-color-background: var(--wpds-color-background-surface-neutral-strong);
+	// Surfaces floating over the chart — tooltips, the annotation label, the
+	// zoom-reset control. Same WPDS token as --a8c-charts-color-background but
+	// deliberately not derived from it, so either can move without the other.
+	--a8c-charts-color-surface: var(--wpds-color-background-surface-neutral-strong);
+	--a8c-charts-color-surface-secondary: var(--wpds-color-background-surface-neutral-weak);
+	--a8c-charts-color-track: var(--wpds-color-background-track-neutral-weak);
 	// Translucent dark surface; no WPDS token carries this.
 	--a8c-charts-color-tooltip-surface: rgb(0 0 0 / 85%);
-	--a8c-charts-color-zoom-selection: var(--wpds-color-background-interactive-brand-strong, var(--wp-admin-theme-color, #3858e9));
-	--a8c-charts-color-zoom-selection-stroke: var(--wpds-color-stroke-interactive-brand, var(--wp-admin-theme-color, #3858e9));
+	--a8c-charts-color-zoom-selection: var(--wpds-color-background-interactive-brand-strong);
+	--a8c-charts-color-zoom-selection-stroke: var(--wpds-color-stroke-interactive-brand);
 
 	// @wordpress/theme 1.0.0 removed the whole --wpds-elevation-* group while the
 	// elevation model is redefined (gutenberg#80099). These carry the removed spec
@@ -102,10 +76,13 @@
 		0 6px 6px 0 #00000008,
 		0 8px 8px 0 #00000005;
 
-	--a8c-charts-motion-duration-entrance: var(--wpds-motion-duration-xl, 400ms);
-	--a8c-charts-motion-easing-entrance: var(--wpds-motion-easing-expressive, cubic-bezier(0.25, 0, 0, 1));
-	--a8c-charts-border-radius-bar: var(--wpds-border-radius-md, 4px);
-	--a8c-charts-border-radius-cell: var(--wpds-border-radius-sm, 2px);
+	--a8c-charts-motion-duration-entrance: var(--wpds-motion-duration-xl);
+	--a8c-charts-motion-easing-entrance: var(--wpds-motion-easing-expressive);
+	--a8c-charts-border-radius-bar: var(--wpds-border-radius-md);
+	--a8c-charts-border-radius-cell: var(--wpds-border-radius-sm);
 	// Pill shape; no WPDS radius reaches it.
 	--a8c-charts-border-radius-leaderboard-bar: 9999px;
+
+	--a8c-charts-dimension-leaderboard-row-gap: var(--wpds-dimension-gap-md);
+	--a8c-charts-dimension-leaderboard-column-gap: var(--wpds-dimension-gap-xs);
 }

package/src/styles/test/chart-scope.test.ts

@@ -1,13 +1,11 @@
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import {
-	THEME_LAYERED_ROLES,
-	themeLayerVar,
-} from '../../providers/chart-context/private/theme-override-vars';
 
 const stylesheet = readFileSync( join( __dirname, '..', 'chart-scope.scss' ), 'utf8' );
 const tokensDoc = readFileSync( join( __dirname, '..', '..', '..', 'TOKENS.md' ), 'utf8' );
 
+const normalize = ( value: string ): string => value.replace( /\s+/g, ' ' ).trim();
+
 type Entry = {
 	/** The custom property this one reads, or null when the value is a literal. */
 	reads: string | null;
@@ -15,26 +13,6 @@ type Entry = {
 	fallback: string | null;
 };
 
-const normalize = ( value: string ): string => value.replace( /\s+/g, ' ' ).trim();
-
-/**
- * Unwraps the theme layer a `theme`-prop-overridable role carries, so the tables in `TOKENS.md` keep documenting what a role ultimately resolves to — its `--wpds-*` token and spec fallback — rather than restating the override plumbing in every row. Which roles carry the layer is pinned separately below.
- *
- * A role with no catalog default reads its layer with no fallback at all — the empty series-palette slots — and unwraps to nothing, which is what it resolves to until a consumer sets it.
- *
- * @param name  - The declared property name.
- * @param value - Its normalized value.
- * @return The value with a leading `var(<name>-theme, … )` wrapper removed, or the empty string where that wrapper carried no fallback.
- */
-function stripThemeLayer( name: string, value: string ): string {
-	const layered = new RegExp(
-		`^var\\(\\s*${ themeLayerVar( name ) }\\s*(?:,\\s*(.*))?\\)$`,
-		's'
-	).exec( value );
-
-	return layered ? ( layered[ 1 ] ?? '' ).trim() : value;
-}
-
 /**
  * Parses each catalog declaration in the stylesheet into the property it reads and the fallback it carries. Splitting the `var()` arguments at the *first* comma keeps a fallback that is itself a function call intact — `cubic-bezier(0.25, 0, 0, 1)` would otherwise be truncated at its first argument.
  *
@@ -57,13 +35,7 @@ function parseStylesheet(): Map< string, Entry > {
 		}
 
 		const name = declaration.slice( 0, separator ).trim();
-		const value = stripThemeLayer( name, normalize( declaration.slice( separator + 1 ) ) );
-
-		// A role that unwrapped to nothing maps to nothing and falls back to nothing.
-		if ( value === '' ) {
-			entries.set( name, { reads: null, fallback: null } );
-			continue;
-		}
+		const value = normalize( declaration.slice( separator + 1 ) );
 
 		const wrapped = /^var\(\s*(.*)\)$/s.exec( value );
 
@@ -145,24 +117,24 @@ describe( 'chart scope catalog', () => {
 	} );
 
 	// The tables in TOKENS.md restate the stylesheet for consumers who only have the
-	// published package. This is the check that stops the two drifting apart.
-	it.each( [ ...declared.keys() ] )( 'documents %s with the value it is declared with', token => {
-		expect( documented.get( token ) ).toEqual( declared.get( token ) );
+	// published package. Mapping (what a role reads) must match the source. The
+	// Fallback column for `--wpds-*` mappings is injected at build time, so only
+	// literals and `--a8c-charts-*` derivations are compared as fallbacks.
+	it.each( [ ...declared.keys() ] )( 'documents %s with the mapping it is declared with', token => {
+		expect( documented.get( token )?.reads ).toEqual( declared.get( token )?.reads );
 	} );
 
-	// The layer is what keeps a `theme` prop override from being able to take its role down with it: an override that is invalid at computed-value time only invalidates `<role>-theme`, and the role's own fallback still resolves the mapped token. Drop the layer from a role and that role's overrides go back to blanking every read site.
-	it.each( THEME_LAYERED_ROLES )( 'declares %s reading its theme layer first', role => {
-		expect( stylesheet ).toMatch(
-			new RegExp( `${ role }:\\s*var\\(\\s*${ themeLayerVar( role ) }\\s*[,)]` )
-		);
-	} );
-
-	it( 'gives a theme layer to the overridable roles and to nothing else', () => {
-		const layered = [ ...declared.keys() ].filter( role =>
-			new RegExp( `${ role }:\\s*var\\(\\s*${ themeLayerVar( role ) }\\s*[,)]` ).test( stylesheet )
-		);
-
-		expect( layered.sort() ).toEqual( [ ...THEME_LAYERED_ROLES ].sort() );
+	it.each(
+		[ ...declared.keys() ].filter( token => {
+			const entry = declared.get( token );
+
+			return (
+				entry?.reads?.startsWith( '--wpds-' ) !== true &&
+				entry?.fallback?.includes( '--wpds-' ) !== true
+			);
+		} )
+	)( 'documents %s with the fallback it is declared with', token => {
+		expect( documented.get( token )?.fallback ).toEqual( declared.get( token )?.fallback );
 	} );
 
 	it( 'scopes the catalog to :where(.a8c-charts-scope) rather than :root', () => {

package/src/test-utils/series-fixtures.ts

@@ -0,0 +1,31 @@
+import type { SeriesData } from '../types';
+
+const series = ( start: string, count: number, stepInHours: number ): SeriesData[] => [
+	{
+		label: 'views',
+		data: Array.from( { length: count }, ( _, index ) => ( {
+			date: new Date( new Date( start ).getTime() + index * stepInHours * 60 * 60 * 1000 ),
+			value: index,
+		} ) ),
+	},
+];
+
+/**
+ * One series of hourly points starting at `start`, `count` long.
+ *
+ * @param start - ISO instant of the first point.
+ * @param count - Number of points.
+ * @return A single-series fixture.
+ */
+export const hourlySeries = ( start: string, count: number ): SeriesData[] =>
+	series( start, count, 1 );
+
+/**
+ * One series of daily points starting at `start`, `count` long.
+ *
+ * @param start - ISO instant of the first point.
+ * @param count - Number of points.
+ * @return A single-series fixture.
+ */
+export const dailySeries = ( start: string, count: number ): SeriesData[] =>
+	series( start, count, 24 );