@automattic/charts 3.2.0 → 4.0.0

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,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( [] );
+	} );
+} );