@automattic/charts 3.2.0 → 4.1.0

package/src/hooks/use-chart-margin.tsx

@@ -1,6 +1,6 @@
 import { createScale, getTicks } from '@visx/scale';
 import { useMemo } from 'react';
-import { getLongestTickWidth, resolveFontSize } from '../utils';
+import { getEdgeTickWidths, getLongestTickWidth, resolveFontSize } from '../utils';
 import type { BaseChartProps, DataPointDate, SeriesData } from '../types';
 import type { XYChartTheme } from '@visx/xychart';
 
@@ -50,6 +50,33 @@ const DEFAULT_TICK_LENGTH = 8;
  */
 const DEFAULT_Y_TICK_WIDTH = 40;
 
+type LabelStyle = { fontSize?: number | string; letterSpacing?: number | string };
+
+/**
+ * Copy a label style with its lengths spelled out in px.
+ *
+ * `getStringWidth` applies the style through CSSOM. Blink resolves a bare number
+ * on an SVG `<text>`, but that is its own leniency rather than the CSS rule, and
+ * `buildChartTheme` hands us bare numbers.
+ *
+ * @param style - Raw label style from the theme.
+ * @return The same style with px-qualified lengths.
+ */
+const toMeasurableStyle = < T extends LabelStyle >( style?: T ) => {
+	if ( ! style ) {
+		return style;
+	}
+
+	const fontSize = resolveFontSize( style.fontSize );
+	const { letterSpacing } = style;
+
+	return {
+		...style,
+		...( fontSize === undefined ? {} : { fontSize: `${ fontSize }px` } ),
+		...( typeof letterSpacing === 'number' ? { letterSpacing: `${ letterSpacing }px` } : {} ),
+	};
+};
+
 const getXAxisLabelMetrics = ( theme: XYChartTheme, orientation: 'top' | 'bottom' ) => {
 	const xAxisStyles =
 		orientation === 'top' ? theme.axisStyles?.x?.top : theme.axisStyles?.x?.bottom;
@@ -61,7 +88,7 @@ const getXAxisLabelMetrics = ( theme: XYChartTheme, orientation: 'top' | 'bottom
 
 	const tickLength = xAxisStyles?.tickLength ?? DEFAULT_TICK_LENGTH;
 
-	return { fontSize, tickLength };
+	return { fontSize, tickLength, tickLabelStyle: toMeasurableStyle( xAxisStyles?.tickLabel ) };
 };
 
 export const useChartMargin = (
@@ -88,7 +115,9 @@ export const useChartMargin = (
 		const maxY = Math.max( ...allDataPoints.map( d => d.value ) );
 		const yScale = createScale( {
 			...options.yScale,
-			domain: [ minY, maxY ],
+			// A pinned domain is what the axis actually renders, so measure those
+			// ticks; the data's range would size the gutter for narrower labels.
+			domain: options.yScale?.domain ?? [ minY, maxY ],
 			range: [ height, 0 ],
 		} );
 
@@ -111,7 +140,7 @@ export const useChartMargin = (
 		const yTickWidth = getLongestTickWidth(
 			yTicks,
 			options.axis?.y?.tickFormat,
-			yAxisStyles.axisLabel
+			toMeasurableStyle( yAxisStyles.axisLabel )
 		);
 		// visx's default axis theme pushes y-axis tick labels a further 0.25em
 		// away from the axis (dx of -0.25em on the left, 0.25em on the right), so
@@ -125,17 +154,20 @@ export const useChartMargin = (
 			( yAxisStyles?.tickLength ?? 0 ) +
 			Math.ceil( yTickLabelFontSize * 0.25 );
 
-		if ( yAxisOrientation === 'right' ) {
-			defaultMargin.right = yMarginValue;
-		} else {
-			defaultMargin.left = yMarginValue;
+		// A hidden y axis reserves nothing; its gutter belongs to the plot area.
+		if ( options.axis?.y?.display !== false ) {
+			if ( yAxisOrientation === 'right' ) {
+				defaultMargin.right = yMarginValue;
+			} else {
+				defaultMargin.left = yMarginValue;
+			}
 		}
 
 		// Dynamically compute X-axis margin (bottom by default, or top if orientation is 'top').
 		// This mirrors Y-axis behavior where margin is based on label size and tick length,
 		// but keeps the padding minimal so consumers can control container spacing themselves.
 		const xOrientation = options.axis?.x?.orientation === 'top' ? 'top' : 'bottom';
-		const { fontSize, tickLength } = getXAxisLabelMetrics( theme, xOrientation );
+		const { fontSize, tickLength, tickLabelStyle } = getXAxisLabelMetrics( theme, xOrientation );
 		const computedXMargin = fontSize + tickLength;
 
 		if ( xOrientation === 'top' ) {
@@ -145,6 +177,19 @@ export const useChartMargin = (
 			defaultMargin.bottom = Math.max( defaultMargin.bottom, computedXMargin );
 		}
 
+		// An X-axis label is centered on its tick, so the ones at either end of the
+		// scale hang half their width outside the plot area and clip at the SVG edge.
+		if ( options.axis?.x?.display !== false ) {
+			const { first, last } = getEdgeTickWidths(
+				options.axis?.x?.tickValues ?? [],
+				options.axis?.x?.tickFormat,
+				tickLabelStyle
+			);
+
+			defaultMargin.left = Math.max( defaultMargin.left, Math.ceil( first / 2 ) );
+			defaultMargin.right = Math.max( defaultMargin.right, Math.ceil( last / 2 ) );
+		}
+
 		return defaultMargin;
 	}, [ options, theme, yTicks ] );
 };

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

@@ -1,8 +1,9 @@
 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[] ) => {
@@ -17,29 +18,44 @@ export const useXYChartTheme = ( data: SeriesData[] ) => {
 	);
 
 	return useMemo( () => {
-		// Only what is read as a string is resolved here — the palette and `backgroundColor` — plus `htmlLabel.color` below, which is painted outside the scope. Resolving against the chart's own scope element, never :root, is what reads an override set inside the provider tree.
-		//
-		// One resolver per theme build, so all three share a single getComputedStyle call.
+		// 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 );
 
-		// The palette gets the same treatment as every other color here, and needs it more: `theme.colors` is the one field that is always a `var()` chain, and the four slots without a catalog default resolve to nothing at all. visx builds its `colorScale` from this array and uses it as the default stroke for a series rendered without an explicit one, so an unresolved entry paints nothing rather than degrading. Entries that resolve to nothing are dropped so the scale compacts the way the provider's own palette does.
-		const paletteColors = [ ...seriesColors, ...( theme.colors ?? [] ) ]
+		// 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.
-		const htmlLabelColor = resolveColor( theme.svgLabelSmall?.fill );
+		// 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;
 
-		// The grid, axis, tick and label colors are spread through untouched, and that is the whole mechanism: visx writes each one onto the element it paints — as an inline style for the grid, a presentation attribute elsewhere — and a `var()` chain resolves there natively. So the role is read at the painted element rather than snapshot at the provider wrapper, which is what makes an override on a chart's own class work, keeps a theme change live without a re-render, and leaves nothing to resolve during SSR. Resolving them here would freeze the color instead.
+		// 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,
+			gridColor: '',
+			gridColorDark: '',
 			colors: paletteColors,
-			backgroundColor: resolveColor( theme.backgroundColor ),
+			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

@@ -10,6 +10,7 @@ export {
 	HeatmapChart,
 	HeatmapChartUnresponsive,
 	buildCalendarHeatmapData,
+	useCalendarHeatmapData,
 } from './charts/heatmap-chart';
 export { LeaderboardChart, LeaderboardChartUnresponsive } from './charts/leaderboard-chart';
 export { LineChart, LineChartUnresponsive } from './charts/line-chart';
@@ -32,6 +33,7 @@ export {
 	GlobalChartsProvider,
 	useGlobalChartsContext,
 	useGlobalChartsTheme,
+	useChartFormatting,
 	GlobalChartsContext,
 	defaultTheme,
 	useChartScopeElement,
@@ -55,6 +57,7 @@ export type {
 	ChartTheme,
 	CompleteChartTheme,
 	AxisOptions,
+	ChartFormatting,
 	TickResolution,
 	ScaleOptions,
 	LegendItemStyles,
@@ -111,6 +114,7 @@ export type {
 	HeatmapColumn,
 	HeatmapCell,
 	HeatmapTooltipData,
+	CalendarHeatmapOptions,
 	CalendarHeatmapResult,
 } from './charts/heatmap-chart';
 export type { LeaderboardChartProps } from './charts/leaderboard-chart';
@@ -126,6 +130,7 @@ export type { SparklineProps, GradientConfig, SparklineDataPoint } from './chart
 
 // Utilities
 export {
+	getBucketInfo,
 	parseAsLocalDate,
 	formatMetricValue,
 	formatPercentage,
@@ -134,3 +139,6 @@ export {
 } from './utils';
 export * from './utils/color-utils';
 export type { MetricValueType } from './utils';
+export type { BucketInfo } from './types';
+
+export type { CrosshairStyle } from './visx/types';

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

@@ -21,25 +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 { SERIES_PALETTE_POINTERS } from './private/series-palette';
-import { themeOverrideVars } from './private/theme-override-vars';
-import { withCatalogPointers } from './private/with-catalog-pointers';
 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 > > >(
@@ -59,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
@@ -88,14 +93,10 @@ 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 remount is not a gap in that: effects always run on mount, so a new instance resolves
-	// against its own node. Only a node swap *within* one instance would go unseen, and the catalog
-	// is declared on the `.a8c-charts-scope` class rather than on a particular element, so the
-	// replacement carries the same computed values anyway.
+	// 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 resolvedColors: string[] = [];
@@ -104,13 +105,7 @@ export const GlobalChartsProvider: FC< GlobalChartsProviderProps > = ( { childre
 		let minHue = 360;
 		let maxHue = 0;
 
-		// Resolved from the theme rather than from `SERIES_PALETTE_POINTERS`, and it has to be. In a
-		// browser the two are equivalent — both name the same slots, and the wrapper's theme-layer
-		// vars answer either. But `withCatalogPointers` puts the consumer's own color in each
-		// pointer's terminal position, and that literal is the only carrier for the palette where
-		// `getComputedStyle` resolves nothing: SSR and jsdom. Walking the manifest instead makes
-		// every consumer palette collapse to the catalog seed there.
-		for ( const color of providerTheme.colors ?? SERIES_PALETTE_POINTERS ) {
+		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
@@ -145,7 +140,7 @@ export const GlobalChartsProvider: FC< GlobalChartsProviderProps > = ( { childre
 			minHue,
 			maxHue,
 		} );
-	}, [ providerTheme ] );
+	}, [] );
 
 	useEffect( () => {
 		if ( colorCache.colors.length > 0 ) {
@@ -157,12 +152,8 @@ export const GlobalChartsProvider: FC< GlobalChartsProviderProps > = ( { childre
 		() => new Map()
 	);
 
-	// Reset group color mappings when the resolved palette changes.
-	//
-	// Keyed on the resolved colors rather than on `providerTheme.colors`, which holds five
-	// catalog pointers and so does not move with a `theme.colors` change — a consumer's colors
-	// reach the palette through the theme-layer vars on the wrapper. Keying on content also stops
-	// a consumer passing an inline `theme` object from resetting the map on every render.
+	// 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( () => {
@@ -358,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,
@@ -365,6 +362,7 @@ export const GlobalChartsProvider: FC< GlobalChartsProviderProps > = ( { childre
 			unregisterChart,
 			getChartData,
 			theme: providerTheme,
+			formatting,
 			getElementStyles,
 			toggleSeriesVisibility,
 			setSeriesVisibility,
@@ -381,6 +379,7 @@ export const GlobalChartsProvider: FC< GlobalChartsProviderProps > = ( { childre
 			unregisterChart,
 			getChartData,
 			providerTheme,
+			formatting,
 			getElementStyles,
 			toggleSeriesVisibility,
 			setSeriesVisibility,
@@ -399,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

@@ -1,19 +1,9 @@
 /**
- * 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`, which now derives `defaultTheme.colors` from it.
- *
- * That is as far as the separation goes, and the limit is worth knowing before the field is
- * deleted. `GlobalChartsProvider` still resolves `providerTheme.colors`, not this manifest,
- * because `withCatalogPointers` parks the consumer's own color in each pointer's terminal position
- * and that literal is the palette's only carrier where `getComputedStyle` resolves nothing — SSR
- * and jsdom. Swapping the provider onto this manifest passes in a browser and collapses every
- * consumer palette to the catalog seed under jsdom; 24 tests say so. Removing `colors` therefore
- * needs a different home for that literal first, not just a change of source here.
+ * 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. `theme.colors` entries past this are ignored. */
+/** How many series-palette slots the catalog emits. */
 export const SERIES_SLOT_COUNT = 5;
 
 /**

package/src/providers/chart-context/test/{sparse-theme.test.ts → catalog-pointers.test.ts}

@@ -1,3 +1,4 @@
+import { ANNOTATION_POINTERS, CATALOG_POINTERS } from '../private/catalog-pointers';
 import { defaultTheme } from '../themes';
 
 const flatten = ( value: unknown ): string[] => {
@@ -13,32 +14,31 @@ const flatten = ( value: unknown ): string[] => {
 	return [];
 };
 
-describe( 'defaultTheme', () => {
-	const strings = flatten( defaultTheme );
+const pointerStrings = [ ...flatten( CATALOG_POINTERS ), ...flatten( ANNOTATION_POINTERS ) ];
 
+describe( 'catalog pointers', () => {
 	it( 'holds no --wpds-* mapping — that lives only in the catalog stylesheet', () => {
-		expect( strings.filter( value => value.includes( '--wpds-' ) ) ).toEqual( [] );
+		expect( pointerStrings.filter( value => value.includes( '--wpds-' ) ) ).toEqual( [] );
 	} );
 
-	it( 'points every themed color at an --a8c-charts-* catalog role', () => {
-		const varStrings = strings.filter( value => value.startsWith( 'var(' ) );
+	it( 'points every color at an --a8c-charts-* catalog role', () => {
+		const varStrings = pointerStrings.filter( value => value.startsWith( 'var(' ) );
 
 		expect( varStrings.length ).toBeGreaterThan( 0 );
 		expect( varStrings.every( value => value.startsWith( 'var(--a8c-charts-' ) ) ).toBe( true );
 	} );
 
-	// The palette slots past the first are the exception, below: a terminal literal there would be a color nobody chose.
-	it( 'gives every catalog pointer a terminal literal for the SSR and jsdom paths', () => {
-		const varStrings = strings
+	// Palette slots past the first are the exception: a literal there would be a color nobody chose.
+	it( 'gives every pointer a terminal literal for the SSR and jsdom paths', () => {
+		const varStrings = pointerStrings
 			.filter( value => value.startsWith( 'var(--a8c-charts-' ) )
 			.filter( value => ! /^var\( *--a8c-charts-color-series-[2-9] *\)$/.test( value ) );
 
 		expect( varStrings.every( value => value.includes( ',' ) ) ).toBe( true );
 	} );
 
-	// Only slot 1 seeds a palette. The rest resolve to nothing until a consumer sets them, and the provider drops what resolves to nothing, so the palette compacts instead of repeating one color.
 	it( 'leaves the palette slots past the first with no default of their own', () => {
-		expect( defaultTheme.colors ).toEqual( [
+		expect( CATALOG_POINTERS.series ).toEqual( [
 			'var(--a8c-charts-color-series-1, #3858e9)',
 			'var(--a8c-charts-color-series-2)',
 			'var(--a8c-charts-color-series-3)',
@@ -47,3 +47,15 @@ describe( 'defaultTheme', () => {
 		] );
 	} );
 } );
+
+describe( 'defaultTheme', () => {
+	// A color has one route, a `--a8c-charts-color-*` role set in CSS. One reappearing
+	// here would be a second.
+	it( 'holds no color at all', () => {
+		const colorish = flatten( defaultTheme ).filter( value =>
+			/^(#|rgb|hsl|var\(--a8c-charts-color)/.test( value.trim() )
+		);
+
+		expect( colorish ).toEqual( [] );
+	} );
+} );