@automattic/charts 3.1.1 → 4.0.0

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

@@ -22,14 +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 } );
 
-			expect( result.current.colors ).toEqual( [ '#FF0000', '#00FF00', '#0000FF' ] );
-			// 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 );
 		} );
 
@@ -39,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 } );
@@ -61,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,33 +1,24 @@
 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: 'transparent', // label background color (transparent by default)
-	// White label text sits on top of arbitrary series colors, so it has no WPDS content-foreground equivalent. Every other colour 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)',
-	colors: [ '#98C8DF', '#006DAB', '#A6DC80', '#1F9828', '#FF8C8F' ],
 	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: [],
 	},
@@ -39,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: {
@@ -96,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

@@ -1,64 +1,66 @@
 // The single mapping point between the --a8c-charts-* catalog and WordPress
-// design-system tokens.
+// design-system tokens. Declares custom properties only — this stylesheet must
+// never change layout.
 
-// Declared on the GlobalChartsProvider wrapper — not at :root — because
+// Declared on the GlobalChartsProvider wrapper, not at :root, because
 // @wordpress/theme's ThemeProvider emits its generated --wpds-* ramp as inline
-// styles on its own wrapper div, not on the document root. Substituting at the
-// provider means a ThemeProvider above it is picked up; substituting at :root
-// would miss it entirely.
+// styles on its own wrapper div. Substituting at :root would miss it entirely.
 
-// :where() keeps the rule at zero specificity so any consumer rule
-// targeting 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 five 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, rather than as the role itself, is what
-// 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, and the role's own fallback still resolves the mapped
-// --wpds-* token. Written as the role directly, that same value made the role
-// guaranteed-invalid and took every bare `var(--a8c-charts-color-grid)` read
-// site with it — gridlines painted `unset` instead of the spec grey.
-// `src/styles/test/chart-scope.test.ts` pins which roles carry the layer.
-
-// Declares custom properties only. This stylesheet must never change layout.
+// :where() keeps the rule at zero specificity so any consumer rule targeting
+// 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.
 :where(.a8c-charts-scope) {
-	--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 colours, so it has no WPDS
-	// content-foreground equivalent.
-	--a8c-charts-color-label-on-fill: #fff;
-	// 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 series palette. GlobalChartsProvider resolves these five slots at its
+	// wrapper and seeds ColorCache with whatever resolves; a slot that resolves
+	// to nothing is skipped, so setting only slots 1 and 3 gives a two-color
+	// palette, and charts generate accessible colors beyond the seeds. Only
+	// slot 1 carries a default.
+
+	// Slot 1 names --wp-admin-theme-color first, because that is the only leg
+	// that does not depend on someone else's runtime. The design system's brand
+	// token tracks the admin color scheme only where a WPDS root provider
+	// boots and emits its generated ramp inline; without one the token falls to
+	// the plain stylesheet rule, a static #3858e9 with no reference to the
+	// 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.
+	--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".
+	// 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
@@ -74,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,23 +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.
- *
- * @param name  - The declared property name.
- * @param value - Its normalized value.
- * @return The value with a leading `var(<name>-theme, … )` wrapper removed.
- */
-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.
  *
@@ -54,7 +35,8 @@ function parseStylesheet(): Map< string, Entry > {
 		}
 
 		const name = declaration.slice( 0, separator ).trim();
-		const value = stripThemeLayer( name, normalize( declaration.slice( separator + 1 ) ) );
+		const value = normalize( declaration.slice( separator + 1 ) );
+
 		const wrapped = /^var\(\s*(.*)\)$/s.exec( value );
 
 		if ( ! wrapped ) {
@@ -112,10 +94,13 @@ function parseTokensDoc(): Map< string, Entry > {
 		// "no mapping" before looking for a token name inside it.
 		const unmapped = mapping.startsWith( '_(none' );
 		const derives = /derives from (--[\w-]+)/.exec( mapping );
-		const wpds = /(--wpds-[\w-]+)/.exec( mapping );
+		// `--wp-*` rather than `--wpds-*`: the series palette maps to WordPress's own
+		// `--wp-admin-theme-color`, since the design system's brand token is a static
+		// hex on every admin screen and cannot carry the admin color scheme.
+		const token = /(--wp[\w-]+)/.exec( mapping );
 
 		entries.set( role, {
-			reads: unmapped ? null : derives?.[ 1 ] ?? wpds?.[ 1 ] ?? null,
+			reads: unmapped ? null : derives?.[ 1 ] ?? token?.[ 1 ] ?? null,
 			fallback: fallback === '—' ? null : normalize( fallback ),
 		} );
 	}
@@ -132,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 ) );
-	} );
-
-	// 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*,` )
-		);
+	// 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 );
 	} );
 
-	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 );