@automattic/charts 3.1.1 → 4.0.0

package/src/components/trend-indicator/trend-indicator.module.scss

@@ -2,8 +2,8 @@
 	display: inline-flex;
 	align-items: center;
 	gap: 0.125em;
-	font-size: var(--wpds-typography-font-size-md, 13px);
-	font-weight: var(--wpds-typography-font-weight-emphasis, 600);
+	font-size: var(--wpds-typography-font-size-md);
+	font-weight: var(--wpds-typography-font-weight-emphasis);
 	line-height: 1;
 
 	&--up {

package/src/hooks/test/use-xychart-theme-style-reads.test.tsx

@@ -4,7 +4,7 @@ import { useXYChartTheme } from '../use-xychart-theme';
 import type { SeriesData } from '../../types';
 import type { ReactNode } from 'react';
 
-// The theme resolves five catalog roles — background, grid, axis, tick and axis label. Each `getComputedStyle` call can force the browser to flush pending style, and this memo re-runs only when the scope element attaches or a series colour changes, so a dashboard mounting N charts pays the count below N times over.
+// The theme resolves the background role and the five palette slots. Each `getComputedStyle` call can force the browser to flush pending style, and this memo re-runs only when the scope element attaches or a series color changes, so a dashboard mounting N charts pays the count below N times over.
 const STABLE_DATA: SeriesData[] = [];
 
 describe( 'useXYChartTheme style reads', () => {
@@ -13,7 +13,6 @@ describe( 'useXYChartTheme style reads', () => {
 
 	beforeEach( () => {
 		scope = document.createElement( 'div' );
-		scope.style.setProperty( '--a8c-charts-color-grid', '#00ff00' );
 		document.body.appendChild( scope );
 		getComputedStyleSpy = jest.spyOn( window, 'getComputedStyle' );
 	} );
@@ -33,14 +32,13 @@ describe( 'useXYChartTheme style reads', () => {
 
 	it( 'reads every role from one computed-style snapshot, not one per role', () => {
 		scope.style.setProperty( '--a8c-charts-color-background', '#111111' );
-		scope.style.setProperty( '--a8c-charts-color-axis', '#222222' );
+		scope.style.setProperty( '--a8c-charts-color-series-2', '#222222' );
 
 		const { result } = renderWithScope();
 
 		expect( getComputedStyleSpy ).toHaveBeenCalledTimes( 1 );
 		expect( result.current.backgroundColor ).toBe( '#111111' );
-		expect( result.current.gridStyles.stroke ).toBe( '#00ff00' );
-		expect( result.current.axisStyles.x.bottom.axisLine.stroke ).toBe( '#222222' );
+		expect( result.current.colors ).toContain( '#222222' );
 	} );
 
 	it( 'does not re-read styles when the hook re-renders with the same inputs', () => {
@@ -74,16 +72,25 @@ describe( 'useXYChartTheme style reads', () => {
 		expect( result.current.colors[ 0 ] ).toBe( 'rebeccapurple' );
 	} );
 
-	// The memo key serialises the strokes rather than joining them, so a colour containing a comma or a space survives the round-trip intact.
+	// The memo key serializes the strokes rather than joining them, so a color containing a comma or a space survives the round-trip intact. `rgba(0, 0, 0, 0.5)` is the one that proves it: it holds both separators and comes back whole.
+	//
+	// The `var()` entry resolves to its fallback rather than passing through, which is the point of resolving the palette at all — visx paints these as SVG presentation attributes, where a `var()` resolves to nothing.
 	it( 'keeps a stroke that contains separators intact', () => {
 		const { result } = renderWithScope( [
 			{ label: 'A', options: { stroke: 'rgba(0, 0, 0, 0.5)' }, data: [] },
 			{ label: 'B', options: { stroke: 'var(--brand, #fff)' }, data: [] },
 		] as unknown as SeriesData[] );
 
-		expect( result.current.colors.slice( 0, 2 ) ).toEqual( [
-			'rgba(0, 0, 0, 0.5)',
-			'var(--brand, #fff)',
-		] );
+		expect( result.current.colors.slice( 0, 2 ) ).toEqual( [ 'rgba(0, 0, 0, 0.5)', '#fff' ] );
+	} );
+
+	// Four of the five palette slots carry no catalog default, so in jsdom they resolve to nothing. Passing those to visx unresolved would make them its default stroke for any series without an explicit one, painting nothing at all.
+	it( 'drops palette entries that resolve to nothing', () => {
+		const { result } = renderWithScope( [] );
+
+		expect( result.current.colors ).not.toEqual(
+			expect.arrayContaining( [ expect.stringContaining( 'var(' ) ] )
+		);
+		expect( result.current.colors.length ).toBeGreaterThan( 0 );
 	} );
 } );

package/src/hooks/test/use-xychart-theme.test.tsx

@@ -4,11 +4,11 @@ import { useXYChartTheme } from '../use-xychart-theme';
 import type { ReactNode } from 'react';
 
 describe( 'useXYChartTheme', () => {
-	it( 'resolves grid colour against the scope element, not the document root', () => {
-		document.documentElement.style.setProperty( '--a8c-charts-color-grid', '#ff0000' );
+	it( 'resolves background color against the scope element, not the document root', () => {
+		document.documentElement.style.setProperty( '--a8c-charts-color-background', '#ff0000' );
 
 		const scope = document.createElement( 'div' );
-		scope.style.setProperty( '--a8c-charts-color-grid', '#00ff00' );
+		scope.style.setProperty( '--a8c-charts-color-background', '#00ff00' );
 		document.body.appendChild( scope );
 
 		const wrapper = ( { children }: { children: ReactNode } ) => (
@@ -17,9 +17,67 @@ describe( 'useXYChartTheme', () => {
 
 		const { result } = renderHook( () => useXYChartTheme( [] ), { wrapper } );
 
-		expect( result.current.gridStyles.stroke ).toBe( '#00ff00' );
+		expect( result.current.backgroundColor ).toBe( '#00ff00' );
 
-		document.documentElement.style.removeProperty( '--a8c-charts-color-grid' );
+		document.documentElement.style.removeProperty( '--a8c-charts-color-background' );
 		document.body.removeChild( scope );
 	} );
+
+	// jsdom does not compute `var()`, so what a pointer resolves *to* is covered in Storybook.
+	it( 'hands visx the catalog pointer for paint-only colors rather than a resolved value', () => {
+		const scope = document.createElement( 'div' );
+		document.body.appendChild( scope );
+
+		const wrapper = ( { children }: { children: ReactNode } ) => (
+			<ChartScopeContext.Provider value={ scope }>{ children }</ChartScopeContext.Provider>
+		);
+
+		const { result } = renderHook( () => useXYChartTheme( [] ), { wrapper } );
+
+		expect( result.current.gridStyles.stroke ).toBe( 'var(--a8c-charts-color-grid, #dbdbdb)' );
+		expect( result.current.axisStyles.x.bottom.axisLine.stroke ).toBe(
+			'var(--a8c-charts-color-axis-x, #dbdbdb)'
+		);
+		expect( result.current.axisStyles.x.bottom.tickLine.stroke ).toBe(
+			'var(--a8c-charts-color-tick-x, #dbdbdb)'
+		);
+		expect( result.current.axisStyles.x.bottom.tickLabel.fill ).toBe(
+			'var(--a8c-charts-color-label-axis, #1e1e1e)'
+		);
+
+		document.body.removeChild( scope );
+	} );
+
+	// The one label color that has to arrive resolved: visx paints it on a portal container appended to `document.body`, where the catalog is not declared, and concatenates it into `box-shadow: 0 1px 2px ${color}55`, which a `var()` chain would invalidate.
+	it( 'resolves the tooltip label color while the tick labels keep the pointer', () => {
+		const scope = document.createElement( 'div' );
+		scope.style.setProperty( '--a8c-charts-color-label-axis', '#0000ff' );
+		document.body.appendChild( scope );
+
+		const wrapper = ( { children }: { children: ReactNode } ) => (
+			<ChartScopeContext.Provider value={ scope }>{ children }</ChartScopeContext.Provider>
+		);
+
+		const { result } = renderHook( () => useXYChartTheme( [] ), { wrapper } );
+
+		expect( result.current.htmlLabel.color ).toBe( '#0000ff' );
+		expect( result.current.svgLabelSmall.fill ).toBe(
+			'var(--a8c-charts-color-label-axis, #1e1e1e)'
+		);
+
+		document.body.removeChild( scope );
+	} );
+
+	it( 'gives the y axis its own roles, resolving to none', () => {
+		const { result } = renderHook( () => useXYChartTheme( [] ) );
+
+		for ( const side of [ 'left', 'right' ] as const ) {
+			expect( result.current.axisStyles.y[ side ].axisLine.stroke ).toBe(
+				'var(--a8c-charts-color-axis-y, none)'
+			);
+			expect( result.current.axisStyles.y[ side ].tickLine.stroke ).toBe(
+				'var(--a8c-charts-color-tick-y, none)'
+			);
+		}
+	} );
 } );

package/src/hooks/use-xychart-theme.ts

@@ -1,15 +1,16 @@
 import { buildChartTheme } from '@visx/xychart';
 import { useMemo } from 'react';
 import { useGlobalChartsTheme } from '../providers';
+import { CATALOG_POINTERS } from '../providers/chart-context/private/catalog-pointers';
 import { useChartScopeElement } from '../providers/chart-scope';
-import { createCssVariableResolver } from '../utils';
+import { createCssVariableResolver, normalizeColorToHex } from '../utils';
 import type { SeriesData } from '../types';
 
 export const useXYChartTheme = ( data: SeriesData[] ) => {
 	const theme = useGlobalChartsTheme();
 	const scopeElement = useChartScopeElement();
 
-	// The only thing the theme takes from `data` is the series strokes, so key the memo on those rather than on the array's identity. A caller passing an inline literal — `<LineChart data={ [ … ] } />`, which the stories and several consumers do — otherwise rebuilds the whole theme on every render. Serialised rather than joined: a stroke can be `rgba(0, 0, 0, 0.5)` or `var(--brand, #fff)`, and any separator that reads naturally inside a colour cannot round-trip.
+	// The only thing the theme takes from `data` is the series strokes, so key the memo on those rather than on the array's identity. A caller passing an inline literal — `<LineChart data={ [ … ] } />`, which the stories and several consumers do — otherwise rebuilds the whole theme on every render. Serialized rather than joined: a stroke can be `rgba(0, 0, 0, 0.5)` or `var(--brand, #fff)`, and any separator that reads naturally inside a color cannot round-trip.
 	const seriesColorKey = JSON.stringify(
 		( data ?? [] )
 			.map( series => series.options?.stroke )
@@ -17,35 +18,44 @@ export const useXYChartTheme = ( data: SeriesData[] ) => {
 	);
 
 	return useMemo( () => {
-		// visx applies grid, axis, and tick-label colours as SVG presentation attributes, where CSS var() cannot resolve. Resolve the catalog token against the chart's own scope element — never :root — so this reads any override set inside the provider tree, the same one a CSS-painted element would inherit.
-		//
-		// One resolver per theme build, so the five roles below share a single getComputedStyle call rather than taking one each: this memo re-runs only when the scope element attaches or a series colour changes, which for a dashboard of charts is the difference between two style queries per chart and ten.
+		// Only what is read as a string is resolved: the palette, `backgroundColor`, `htmlLabel.color`.
+		// At the chart's scope element, never :root, so an override inside the provider tree is seen.
+		// One resolver for all three, so they share a single getComputedStyle call.
 		const resolve = createCssVariableResolver( scopeElement );
 		const resolveColor = ( value?: string ): string | undefined =>
 			value ? resolve( value ) ?? value : value;
 
 		const seriesColors: string[] = JSON.parse( seriesColorKey );
 
+		// visx uses this as the default stroke for a series without one, so an
+		// unresolved entry paints nothing.
+		const paletteColors = [ ...seriesColors, ...CATALOG_POINTERS.series ]
+			.map( color => resolveColor( color ) )
+			.filter( ( color ): color is string => Boolean( color ) && ! color.includes( 'var(' ) );
+
+		// The tooltip is painted in a portal outside the scope, and visx concatenates this color into a `box-shadow` where a chain cannot take a suffix; see TOKENS.md#the-svg-bridge. Passing it explicitly leaves `svgLabelSmall.fill`, which visx derives it from, a chain for the SVG tick labels.
+		// Hex specifically: that concatenation appends `55`, which only yields a color
+		// after a 6-digit hex. An `rgb()` computed value takes the whole shadow down.
+		const resolvedLabelColor = resolveColor( CATALOG_POINTERS.labelAxis );
+		const htmlLabelColor = resolvedLabelColor
+			? normalizeColorToHex( resolvedLabelColor ) || resolvedLabelColor
+			: resolvedLabelColor;
+
+		// visx's fallbacks for whichever axis or grid style object it is not given. All four are
+		// supplied, so these reach nothing; they stay because the config type requires them.
 		return buildChartTheme( {
 			...theme,
-			colors: [ ...seriesColors, ...( theme.colors ?? [] ) ],
-			backgroundColor: resolveColor( theme.backgroundColor ),
-			gridStyles: theme.gridStyles && {
-				...theme.gridStyles,
-				stroke: resolveColor( theme.gridStyles.stroke ),
-			},
-			xAxisLineStyles: theme.xAxisLineStyles && {
-				...theme.xAxisLineStyles,
-				stroke: resolveColor( theme.xAxisLineStyles.stroke ),
-			},
-			xTickLineStyles: theme.xTickLineStyles && {
-				...theme.xTickLineStyles,
-				stroke: resolveColor( theme.xTickLineStyles.stroke ),
-			},
-			svgLabelSmall: theme.svgLabelSmall && {
-				...theme.svgLabelSmall,
-				fill: resolveColor( theme.svgLabelSmall.fill ),
-			},
+			gridColor: '',
+			gridColorDark: '',
+			colors: paletteColors,
+			backgroundColor: resolveColor( CATALOG_POINTERS.background ),
+			htmlLabel: htmlLabelColor ? { color: htmlLabelColor } : undefined,
+			gridStyles: { ...theme.gridStyles, stroke: CATALOG_POINTERS.grid },
+			xAxisLineStyles: { ...theme.xAxisLineStyles, stroke: CATALOG_POINTERS.axisX },
+			xTickLineStyles: { ...theme.xTickLineStyles, stroke: CATALOG_POINTERS.tickX },
+			yAxisLineStyles: { stroke: CATALOG_POINTERS.axisY },
+			yTickLineStyles: { stroke: CATALOG_POINTERS.tickY },
+			svgLabelSmall: { ...theme.svgLabelSmall, fill: CATALOG_POINTERS.labelAxis },
 		} );
 	}, [ theme, seriesColorKey, scopeElement ] );
 };

package/src/index.ts

@@ -32,6 +32,7 @@ export {
 	GlobalChartsProvider,
 	useGlobalChartsContext,
 	useGlobalChartsTheme,
+	useChartFormatting,
 	GlobalChartsContext,
 	defaultTheme,
 	useChartScopeElement,
@@ -55,6 +56,7 @@ export type {
 	ChartTheme,
 	CompleteChartTheme,
 	AxisOptions,
+	ChartFormatting,
 	TickResolution,
 	ScaleOptions,
 	LegendItemStyles,
@@ -126,6 +128,7 @@ export type { SparklineProps, GradientConfig, SparklineDataPoint } from './chart
 
 // Utilities
 export {
+	getBucketInfo,
 	parseAsLocalDate,
 	formatMetricValue,
 	formatPercentage,
@@ -134,3 +137,4 @@ export {
 } from './utils';
 export * from './utils/color-utils';
 export type { MetricValueType } from './utils';
+export type { BucketInfo } from './types';

package/src/providers/chart-context/global-charts-provider.tsx

@@ -21,24 +21,39 @@ import {
 	resolveCssVariable,
 	normalizeColorToHex,
 } from '../../utils';
+import { sanitizeFormatting } from '../../utils/date-formatting';
 // Imported from the module rather than the `chart-scope` barrel: the barrel also pulls `use-standalone-scope-class`, which imports `GlobalChartsContext` back from this file. That cycle resolves today only because the binding is read lazily inside the hook body.
 import { ChartScopeContext } from '../chart-scope/chart-scope-context';
 import { getChartColor, type ColorCache } from './private/get-chart-color';
-import { themeOverrideVars } from './private/theme-override-vars';
-import { withCatalogPointers } from './private/with-catalog-pointers';
+import { SERIES_PALETTE_POINTERS } from './private/series-palette';
 import { defaultTheme } from './themes';
 import type { GlobalChartsContextValue, ChartRegistration } from './types';
 import type { ChartTheme, CompleteChartTheme } from '../../types';
-import type { CSSProperties, FC, ReactNode } from 'react';
+import type { FC, ReactNode } from 'react';
 
 export const GlobalChartsContext = createContext< GlobalChartsContextValue | null >( null );
 
 export interface GlobalChartsProviderProps {
 	children: ReactNode;
 	theme?: Partial< ChartTheme >;
+	/**
+	 * BCP-47 language tag every date label is rendered in, e.g. `de-DE`.
+	 * Defaults to the viewer's browser locale.
+	 */
+	locale?: string;
+	/**
+	 * IANA time zone every date label is dated in, e.g. `Asia/Tokyo`.
+	 * Defaults to the viewer's browser time zone.
+	 */
+	timeZone?: string;
 }
 
-export const GlobalChartsProvider: FC< GlobalChartsProviderProps > = ( { children, theme } ) => {
+export const GlobalChartsProvider: FC< GlobalChartsProviderProps > = ( {
+	children,
+	theme,
+	locale,
+	timeZone,
+} ) => {
 	const [ charts, setCharts ] = useState< Map< string, ChartRegistration > >( () => new Map() );
 	// Track hidden series per chart: chartId -> Set<seriesLabel>
 	const [ hiddenSeries, setHiddenSeries ] = useState< Map< string, Set< string > > >(
@@ -58,20 +73,11 @@ export const GlobalChartsProvider: FC< GlobalChartsProviderProps > = ( { childre
 		setScopeNode( node );
 	}, [] );
 
-	// themeOverrideVars reads the raw `theme` prop, never `providerTheme` — feeding it the restored theme below would make an overridden role's pointer look like a self-reference and drop the var (see themeOverrideVars' own doc comment).
-	const { vars: overrideVars, roles: overriddenRoles } = useMemo(
-		() => themeOverrideVars( theme ),
+	const providerTheme: CompleteChartTheme = useMemo(
+		() => ( theme ? mergeThemes( defaultTheme, theme ) : defaultTheme ),
 		[ theme ]
 	);
 
-	const providerTheme: CompleteChartTheme = useMemo( () => {
-		if ( ! theme ) {
-			return defaultTheme;
-		}
-
-		return withCatalogPointers( mergeThemes( defaultTheme, theme ), overriddenRoles );
-	}, [ theme, overriddenRoles ] );
-
 	// Cache expensive color computations that only change when theme colors change
 	// Using useState + useLayoutEffect instead of useMemo to ensure CSS variables
 	// in <style> tags are applied to the DOM before we try to resolve them
@@ -87,49 +93,42 @@ export const GlobalChartsProvider: FC< GlobalChartsProviderProps > = ( { childre
 	// Useful for animations that should only run after the color palette is resolved
 	const [ isColorPaletteResolved, setIsColorPaletteResolved ] = useState( false );
 
-	// Compute color cache after DOM is updated (so CSS variables are available)
-	// Resolves CSS variables from the wrapper element's scope to handle scoped variables
-	// Note: Only re-runs when providerTheme changes, not when wrapper element changes.
-	// This is intentional, as wrapperRef is expected to be stable for the lifetime of the provider.
+	// A layout effect rather than a memo: the catalog reaches the wrapper as a stylesheet, which
+	// must be applied before `getComputedStyle` can answer. Mount only — the slots are a fixed
+	// manifest and `wrapperRef` is stable for the provider's life.
+
 	useLayoutEffect( () => {
 		setIsColorPaletteResolved( false );
-		const { colors } = providerTheme;
 		const resolvedColors: string[] = [];
 		const hues: number[] = [];
 		const existingHslColors: Array< [ number, number, number ] > = [];
 		let minHue = 360;
 		let maxHue = 0;
 
-		// Process all colors once and cache the results
-		if ( Array.isArray( colors ) ) {
-			for ( const color of colors ) {
-				if ( color && typeof color === 'string' ) {
-					// Normalize color to hex format, handling CSS variables, RGB, HSL, etc.
-					// This uses normalizeColorToHex which resolves CSS variables and converts
-					// rgb(), rgba(), hsl() formats to hex
-					const normalizedColor = normalizeColorToHex(
-						color,
-						wrapperRef.current,
-						resolveCssVariable
-					);
-
-					// Only process valid hex colors
-					if ( normalizedColor.startsWith( '#' ) ) {
-						resolvedColors.push( normalizedColor );
-						const hslColor = d3Hsl( normalizedColor );
-						// d3Hsl returns NaN values for invalid colors
-						if ( ! isNaN( hslColor.h ) ) {
-							const hslTuple: [ number, number, number ] = [
-								hslColor.h,
-								hslColor.s * 100,
-								hslColor.l * 100,
-							];
-							hues.push( hslTuple[ 0 ] );
-							existingHslColors.push( hslTuple );
-							minHue = Math.min( minHue, hslTuple[ 0 ] );
-							maxHue = Math.max( maxHue, hslTuple[ 0 ] );
-						}
-					}
+		for ( const color of SERIES_PALETTE_POINTERS ) {
+			// Normalize color to hex format, handling CSS variables, RGB, HSL, etc.
+			// This uses normalizeColorToHex which resolves CSS variables and converts
+			// rgb(), rgba(), hsl() formats to hex
+			const normalizedColor = normalizeColorToHex( color, wrapperRef.current, resolveCssVariable );
+
+			// Only process valid hex colors. An unset palette slot returns its own
+			// `var()` unchanged, so this is also what compacts the palette: slots the
+			// consumer never set drop out here and `getChartColor` generates past
+			// whatever survived.
+			if ( normalizedColor.startsWith( '#' ) ) {
+				resolvedColors.push( normalizedColor );
+				const hslColor = d3Hsl( normalizedColor );
+				// d3Hsl returns NaN values for invalid colors
+				if ( ! isNaN( hslColor.h ) ) {
+					const hslTuple: [ number, number, number ] = [
+						hslColor.h,
+						hslColor.s * 100,
+						hslColor.l * 100,
+					];
+					hues.push( hslTuple[ 0 ] );
+					existingHslColors.push( hslTuple );
+					minHue = Math.min( minHue, hslTuple[ 0 ] );
+					maxHue = Math.max( maxHue, hslTuple[ 0 ] );
 				}
 			}
 		}
@@ -141,7 +140,7 @@ export const GlobalChartsProvider: FC< GlobalChartsProviderProps > = ( { childre
 			minHue,
 			maxHue,
 		} );
-	}, [ providerTheme ] );
+	}, [] );
 
 	useEffect( () => {
 		if ( colorCache.colors.length > 0 ) {
@@ -153,11 +152,14 @@ export const GlobalChartsProvider: FC< GlobalChartsProviderProps > = ( { childre
 		() => new Map()
 	);
 
-	// Reset group color mappings when theme colors change
+	// Keyed on the resolved colors rather than the cache object, so a consumer passing an inline
+	// `theme` cannot reset the map on every render.
+	const paletteKey = colorCache.colors.join( ',' );
+
 	useEffect( () => {
 		// Create a completely new Map instance to trigger dependencies, e.g. useChartLegendItems
 		setGroupToColorMap( new Map() );
-	}, [ providerTheme.colors ] );
+	}, [ paletteKey ] );
 
 	const registerChart = useCallback( ( id: string, data: ChartRegistration ) => {
 		setCharts( prev => new Map( prev ).set( id, data ) );
@@ -347,6 +349,12 @@ export const GlobalChartsProvider: FC< GlobalChartsProviderProps > = ( { childre
 		[ hiddenSeries ]
 	);
 
+	// Held as one object so a chart's formatting memos key on a single stable reference.
+	const formatting = useMemo(
+		() => sanitizeFormatting( { locale, timeZone } ),
+		[ locale, timeZone ]
+	);
+
 	const value: GlobalChartsContextValue = useMemo(
 		() => ( {
 			charts,
@@ -354,6 +362,7 @@ export const GlobalChartsProvider: FC< GlobalChartsProviderProps > = ( { childre
 			unregisterChart,
 			getChartData,
 			theme: providerTheme,
+			formatting,
 			getElementStyles,
 			toggleSeriesVisibility,
 			setSeriesVisibility,
@@ -370,6 +379,7 @@ export const GlobalChartsProvider: FC< GlobalChartsProviderProps > = ( { childre
 			unregisterChart,
 			getChartData,
 			providerTheme,
+			formatting,
 			getElementStyles,
 			toggleSeriesVisibility,
 			setSeriesVisibility,
@@ -388,7 +398,7 @@ export const GlobalChartsProvider: FC< GlobalChartsProviderProps > = ( { childre
 				ref={ setWrapperNode }
 				className={ CHART_SCOPE_CLASS }
 				data-testid="charts-scope"
-				style={ { display: 'contents', ...overrideVars } as CSSProperties }
+				style={ { display: 'contents' } }
 			>
 				<ChartScopeContext.Provider value={ scopeNode }>{ children }</ChartScopeContext.Provider>
 			</div>

package/src/providers/chart-context/hooks/use-chart-formatting.ts

@@ -0,0 +1,22 @@
+import { useContext } from 'react';
+import { GlobalChartsContext } from '../global-charts-provider';
+import type { ChartFormatting } from '../../../types';
+
+// A stable reference, so a chart mounted without a provider doesn't rebuild its
+// formatting memos on every render.
+const RUNTIME_FORMATTING: ChartFormatting = {};
+
+/**
+ * The locale and time zone dates are rendered in, as set on `GlobalChartsProvider`.
+ *
+ * Falls back to the runtime's own rather than throwing: charts render outside a
+ * provider, and a host that sets neither gets exactly the browser-default
+ * behavior this package had before the context existed.
+ *
+ * @return The host's formatting context.
+ */
+export const useChartFormatting = (): ChartFormatting => {
+	const context = useContext( GlobalChartsContext );
+
+	return context?.formatting ?? RUNTIME_FORMATTING;
+};

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

@@ -3,6 +3,7 @@ export { useGlobalChartsContext } from './hooks/use-global-charts-context';
 export { useChartId } from './hooks/use-chart-id';
 export { useChartRegistration } from './hooks/use-chart-registration';
 export { useGlobalChartsTheme } from './hooks/use-global-charts-theme';
+export { useChartFormatting } from './hooks/use-chart-formatting';
 export type {
 	GlobalChartsContextValue,
 	ChartRegistration,

package/src/providers/chart-context/private/catalog-pointers.ts

@@ -0,0 +1,42 @@
+import { SERIES_PALETTE_POINTERS } from './series-palette';
+
+/*
+ * The `var()` chain for each color JS has to hand to something. Nothing here is resolved in JS —
+ * the chain lands on the element; the terminal literal covers SSR and jsdom. See TOKENS.md.
+ */
+export const CATALOG_POINTERS = {
+	background: 'var(--a8c-charts-color-background, #fff)',
+	labelAxis: 'var(--a8c-charts-color-label-axis, #1e1e1e)',
+	grid: 'var(--a8c-charts-color-grid, #dbdbdb)',
+	// The y pair resolves to `none`: that axis carries labels only until a consumer declares them.
+	axisX: 'var(--a8c-charts-color-axis-x, #dbdbdb)',
+	tickX: 'var(--a8c-charts-color-tick-x, #dbdbdb)',
+	axisY: 'var(--a8c-charts-color-axis-y, none)',
+	tickY: 'var(--a8c-charts-color-tick-y, none)',
+	annotation: 'var(--a8c-charts-color-annotation, #1e1e1e)',
+	surface: 'var(--a8c-charts-color-surface, #fff)',
+	surfaceSecondary: 'var(--a8c-charts-color-surface-secondary, #f4f4f4)',
+	// Only for `renderMainMetric`, which hands a consumer's own markup something to paint with.
+	trendUp: 'var(--a8c-charts-color-trend-up, #008030)',
+	trendDown: 'var(--a8c-charts-color-trend-down, #cc1818)',
+	series: SERIES_PALETTE_POINTERS,
+} as const;
+
+/**
+ * The annotation parts visx paints, in the shape `@visx/annotation` takes. `radius`
+ * rides along as the base the theme and the per-datum styles merge onto.
+ */
+export const ANNOTATION_POINTERS = {
+	label: {
+		anchorLineStroke: CATALOG_POINTERS.annotation,
+		backgroundFill: CATALOG_POINTERS.surface,
+	},
+	connector: {
+		stroke: CATALOG_POINTERS.annotation,
+	},
+	circleSubject: {
+		stroke: 'transparent',
+		fill: CATALOG_POINTERS.annotation,
+		radius: 5,
+	},
+} as const;

package/src/providers/chart-context/private/series-palette.ts

@@ -0,0 +1,35 @@
+/**
+ * The series palette's slot manifest. Which slots exist is a fact about the catalog
+ * `chart-scope.scss` emits, not a theme value, so it is declared here rather than in `themes.ts`.
+ */
+
+/** How many series-palette slots the catalog emits. */
+export const SERIES_SLOT_COUNT = 5;
+
+/**
+ * The catalog role holding one series-palette slot.
+ *
+ * @param slot - The one-based slot number.
+ * @return The role name.
+ */
+export const seriesRole = ( slot: number ): string => `--a8c-charts-color-series-${ slot }`;
+
+/*
+ * Only slot 1 carries a terminal literal, and it is reached only where `getComputedStyle` resolves
+ * nothing — SSR and jsdom. The rest resolve to nothing until a consumer sets them, and the provider
+ * drops what resolves to nothing, so the palette compacts rather than repeating one color.
+ *
+ * The literal matches slot 1's own last-resort fallback in `chart-scope.scss`. It is deliberately
+ * the bare hex rather than that slot's full `var()` chain: this string is resolved against the DOM,
+ * where the chain has already been walked, and is only read at all when no DOM answered.
+ */
+const SERIES_SLOT_1_FALLBACK = '#3858e9';
+
+/** The catalog pointer for every slot, in slot order. */
+export const SERIES_PALETTE_POINTERS: readonly string[] = Array.from(
+	{ length: SERIES_SLOT_COUNT },
+	( _, index ) =>
+		index === 0
+			? `var(${ seriesRole( 1 ) }, ${ SERIES_SLOT_1_FALLBACK })`
+			: `var(${ seriesRole( index + 1 ) })`
+);