@automattic/charts 4.4.0 → 4.6.0

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

@@ -0,0 +1,305 @@
+import { relativeLuminance } from '../../../utils';
+import {
+	hexToOklch,
+	hexToViews,
+	luminanceContrastRatio,
+	oklchToHex,
+	viewDistance,
+} from './perceptual-color';
+import type { ColorViews } from './perceptual-color';
+
+/** WCAG 1.4.11 non-text contrast, which a series mark needs against the chart background. */
+export const MIN_BACKGROUND_CONTRAST = 3;
+
+/** WCAG 1.4.3 text contrast, which a label drawn on a fill needs from at least one label color. */
+export const MIN_LABEL_CONTRAST = 4.5;
+
+/** ΔE00 every earlier color must clear before a candidate may be picked for its hue. */
+export const PREFERRED_SEPARATION = 12;
+
+/** Degrees of hue one unit of OKLCH chroma is worth when ranking candidates by hue. */
+const CHROMA_WEIGHT = 300;
+
+/** ΔE00 one unit of OKLCH chroma is worth when ranking candidates by distance. */
+const FAR_CHROMA_WEIGHT = 100;
+
+interface Candidate {
+	hex: string;
+	views: ColorViews;
+	luminance: number;
+	hue: number;
+	chroma: number;
+}
+
+const toCandidate = ( hex: string, oklch = hexToOklch( hex ) ): Candidate => ( {
+	hex,
+	views: hexToViews( hex ),
+	luminance: relativeLuminance( hex ),
+	hue: oklch.hue,
+	chroma: oklch.chroma,
+} );
+
+// Lower ranks first. With an anchor: degrees from it going round the wheel. Without: farthest first. Both favor saturation.
+const rank = ( candidate: Candidate, distance: number, anchorHue: number | null ): number =>
+	anchorHue === null
+		? -( distance + candidate.chroma * FAR_CHROMA_WEIGHT )
+		: ( ( candidate.hue - anchorHue + 360 ) % 360 ) - candidate.chroma * CHROMA_WEIGHT;
+
+const LIGHTNESS_STEPS = Array.from( { length: 13 }, ( _, step ) => 0.45 + step * 0.025 );
+const CHROMA_STEPS = [ 0.12, 0.15, 0.18, 0.21 ];
+const HUE_STEPS = Array.from( { length: 72 }, ( _, step ) => step * 5 );
+
+let candidateGrid: Candidate[] | null = null;
+
+const getCandidateGrid = (): Candidate[] => {
+	if ( ! candidateGrid ) {
+		const seen = new Set< string >();
+		candidateGrid = [];
+		for ( const lightness of LIGHTNESS_STEPS ) {
+			for ( const chroma of CHROMA_STEPS ) {
+				for ( const hue of HUE_STEPS ) {
+					const hex = oklchToHex( lightness, chroma, hue );
+					if ( hex && ! seen.has( hex ) ) {
+						seen.add( hex );
+						candidateGrid.push( toCandidate( hex, { hue, chroma } ) );
+					}
+				}
+			}
+		}
+	}
+	return candidateGrid;
+};
+
+// Every provider on a page usually shares one background and label pair, so each filters the grid only once.
+const legiblePools = new Map< string, Candidate[] >();
+
+const legibleCandidatesFor = (
+	rawBackground: string,
+	labelColors: readonly string[]
+): Candidate[] => {
+	const background = rawBackground.toLowerCase();
+	const key = [ background, ...labelColors.map( hex => hex.toLowerCase() ) ].join( '|' );
+	let pool = legiblePools.get( key );
+	if ( ! pool ) {
+		const backgroundLuminance = relativeLuminance( background );
+		const labelLuminances = labelColors.map( relativeLuminance );
+		const onBackground = getCandidateGrid().filter(
+			candidate =>
+				luminanceContrastRatio( candidate.luminance, backgroundLuminance ) >=
+				MIN_BACKGROUND_CONTRAST
+		);
+		const underLabels = onBackground.filter( candidate =>
+			labelLuminances.some(
+				labelLuminance =>
+					luminanceContrastRatio( candidate.luminance, labelLuminance ) >= MIN_LABEL_CONTRAST
+			)
+		);
+		// Label colors that no fill can serve would empty the pool; keep the background guarantee instead.
+		pool = underLabels.length > 0 ? underLabels : onBackground;
+		legiblePools.set( key, pool );
+	}
+	return pool;
+};
+
+/** A candidate pool with each unused candidate's current nearest distance to the palette. */
+interface Tracker {
+	pool: Candidate[];
+	nearest: Float64Array;
+}
+
+/**
+ * Build a tracker for a candidate pool, seeding each unused candidate's nearest distance against
+ * every color already in the palette.
+ *
+ * @param pool      - Candidates to track, in selection-priority order.
+ * @param palette   - Colors already placed.
+ * @param usedHexes - Hex values already placed; a used candidate's distance is never read.
+ * @return The tracker.
+ */
+const buildTracker = (
+	pool: Candidate[],
+	palette: readonly Candidate[],
+	usedHexes: ReadonlySet< string >
+): Tracker => {
+	const nearest = new Float64Array( pool.length ).fill( Infinity );
+	for ( let i = 0; i < pool.length; i++ ) {
+		if ( usedHexes.has( pool[ i ].hex ) ) {
+			continue;
+		}
+		for ( const color of palette ) {
+			const distance = viewDistance( pool[ i ].views, color.views );
+			if ( distance < nearest[ i ] ) {
+				nearest[ i ] = distance;
+			}
+		}
+	}
+	return { pool, nearest };
+};
+
+/**
+ * Fold one newly placed color into a tracker's nearest distances.
+ *
+ * @param tracker    - Tracker to update.
+ * @param addedColor - Color just added to the palette.
+ * @param usedHexes  - Hex values already placed; a used candidate's distance is never read.
+ */
+const updateTracker = (
+	tracker: Tracker,
+	addedColor: Candidate,
+	usedHexes: ReadonlySet< string >
+): void => {
+	for ( let i = 0; i < tracker.pool.length; i++ ) {
+		if ( usedHexes.has( tracker.pool[ i ].hex ) ) {
+			continue;
+		}
+		const distance = viewDistance( tracker.pool[ i ].views, addedColor.views );
+		if ( distance < tracker.nearest[ i ] ) {
+			tracker.nearest[ i ] = distance;
+		}
+	}
+};
+
+/**
+ * Pick the next color: the best-ranked unused candidate that clears `PREFERRED_SEPARATION` from
+ * every earlier color; otherwise the farthest candidate.
+ *
+ * @param tracker   - Tracker to read.
+ * @param usedHexes - Hex values already placed; a used candidate is never picked.
+ * @param anchorHue - Hue to walk the wheel from, or null to rank by distance.
+ * @return The picked candidate, or null if every candidate in the pool is used.
+ */
+const pickNext = (
+	tracker: Tracker,
+	usedHexes: ReadonlySet< string >,
+	anchorHue: number | null
+): Candidate | null => {
+	let farthestIndex = -1;
+	let farthestDistance = -Infinity;
+	let preferredIndex = -1;
+	let preferredRank = Infinity;
+	for ( let i = 0; i < tracker.pool.length; i++ ) {
+		if ( usedHexes.has( tracker.pool[ i ].hex ) ) {
+			continue;
+		}
+		const distance = tracker.nearest[ i ];
+		if ( distance > farthestDistance ) {
+			farthestDistance = distance;
+			farthestIndex = i;
+		}
+		if ( distance >= PREFERRED_SEPARATION ) {
+			const candidateRank = rank( tracker.pool[ i ], distance, anchorHue );
+			if (
+				candidateRank < preferredRank ||
+				( candidateRank === preferredRank && distance > tracker.nearest[ preferredIndex ] )
+			) {
+				preferredRank = candidateRank;
+				preferredIndex = i;
+			}
+		}
+	}
+	const index = preferredIndex === -1 ? farthestIndex : preferredIndex;
+	return index === -1 ? null : tracker.pool[ index ];
+};
+
+type ColorAt = ( index: number ) => string;
+
+// Generation is deterministic, so every provider on a page with the same inputs shares one generator.
+const generators = new Map< string, ColorAt >();
+const MAX_CACHED_GENERATORS = 32;
+
+/**
+ * Build the series palette: the seeds, then colors that stay apart from every earlier color in
+ * normal vision and under deuteranopia and protanopia.
+ *
+ * @param seeds       - Resolved hex palette slots, in slot order.
+ * @param background  - Resolved hex chart background.
+ * @param labelColors - Resolved hex label colors that may be drawn on a fill; each generated color reaches `MIN_LABEL_CONTRAST` with one of them.
+ * @return The color at a palette index.
+ */
+export const createPaletteGenerator = (
+	seeds: readonly string[],
+	background: string,
+	labelColors: readonly string[] = []
+): ColorAt => {
+	const normalizedSeeds = seeds.map( hex => hex.toLowerCase() );
+	const normalizedBackground = background.toLowerCase();
+	const normalizedLabels = labelColors.map( hex => hex.toLowerCase() );
+	const key = `${ normalizedSeeds.join( ',' ) }|${ normalizedBackground }|${ normalizedLabels.join(
+		','
+	) }`;
+	let colorAt = generators.get( key );
+	if ( ! colorAt ) {
+		if ( generators.size >= MAX_CACHED_GENERATORS ) {
+			generators.delete( generators.keys().next().value as string );
+		}
+		colorAt = buildPaletteGenerator( normalizedSeeds, normalizedBackground, normalizedLabels );
+		generators.set( key, colorAt );
+	}
+	return colorAt;
+};
+
+const buildPaletteGenerator = (
+	normalizedSeeds: readonly string[],
+	background: string,
+	labelColors: readonly string[]
+): ColorAt => {
+	const palette: Candidate[] = normalizedSeeds.map( hex => toCandidate( hex ) );
+	const usedHexes = new Set< string >( normalizedSeeds );
+	const anchorHue = palette.length > 0 ? palette[ 0 ].hue : null;
+
+	let legibleTracker: Tracker | null = null;
+	let legibleExhausted = false;
+	let gridTracker: Tracker | null = null;
+	let gridExhausted = false;
+	// Colors placed by the time the grid ran out; the fallback below cycles through only these.
+	let placedBeforeExhaustion = 0;
+	let repeatCount = 0;
+
+	const nextColor = (): Candidate => {
+		// Alternate far and near, starting far: charts often use the first two colors for comparison, so those must contrast.
+		const walkHue = ( palette.length - normalizedSeeds.length ) % 2 === 1 ? anchorHue : null;
+		if ( ! legibleExhausted ) {
+			legibleTracker ??= buildTracker(
+				legibleCandidatesFor( background, labelColors ),
+				palette,
+				usedHexes
+			);
+			const picked = pickNext( legibleTracker, usedHexes, walkHue );
+			if ( picked ) {
+				return picked;
+			}
+			legibleExhausted = true;
+		}
+		if ( ! gridExhausted ) {
+			gridTracker ??= buildTracker( getCandidateGrid(), palette, usedHexes );
+			const picked = pickNext( gridTracker, usedHexes, walkHue );
+			if ( picked ) {
+				return picked;
+			}
+			gridExhausted = true;
+			placedBeforeExhaustion = palette.length;
+		}
+		// Every candidate is already in the palette; cycle through the ones placed before the grid ran out.
+		const repeated = palette[ repeatCount % placedBeforeExhaustion ];
+		repeatCount++;
+		return repeated;
+	};
+
+	return ( index: number ): string => {
+		if ( index < palette.length ) {
+			return palette[ index ].hex;
+		}
+		while ( palette.length <= index ) {
+			const next = nextColor();
+			usedHexes.add( next.hex );
+			palette.push( next );
+			if ( legibleTracker && ! legibleExhausted ) {
+				updateTracker( legibleTracker, next, usedHexes );
+			}
+			if ( gridTracker && ! gridExhausted ) {
+				updateTracker( gridTracker, next, usedHexes );
+			}
+		}
+		return palette[ index ].hex;
+	};
+};

package/src/providers/chart-context/private/perceptual-color.ts

@@ -0,0 +1,219 @@
+import { relativeLuminance, validateHexColor } from '../../../utils';
+
+export type Lab = readonly [ number, number, number ];
+
+/** A color as seen in normal vision, then under deuteranopia and protanopia. */
+export type ColorViews = readonly [ Lab, Lab, Lab ];
+
+type Matrix = readonly number[];
+
+// Machado, Oliveira and Fernandes (2009), severity 1.0, on linear sRGB.
+const DEUTERANOPIA: Matrix = [
+	0.367322, 0.860646, -0.227968, 0.280085, 0.672501, 0.047413, -0.01182, 0.04294, 0.968881,
+];
+const PROTANOPIA: Matrix = [
+	0.152286, 1.052583, -0.204868, 0.114503, 0.786281, 0.099216, -0.003882, -0.048116, 1.051998,
+];
+
+const DEGREES = Math.PI / 180;
+
+const toLinear = ( channel: number ): number =>
+	channel <= 0.04045 ? channel / 12.92 : Math.pow( ( channel + 0.055 ) / 1.055, 2.4 );
+
+const fromLinear = ( channel: number ): number =>
+	channel <= 0.0031308 ? 12.92 * channel : 1.055 * Math.pow( channel, 1 / 2.4 ) - 0.055;
+
+const hexToLinear = ( hex: string ): number[] => {
+	validateHexColor( hex );
+	return [ 1, 3, 5 ].map( start =>
+		toLinear( parseInt( hex.slice( start, start + 2 ), 16 ) / 255 )
+	);
+};
+
+const linearToHex = ( linear: number[] ): string =>
+	'#' +
+	linear
+		.map( channel =>
+			Math.round( Math.min( 1, Math.max( 0, fromLinear( channel ) ) ) * 255 )
+				.toString( 16 )
+				.padStart( 2, '0' )
+		)
+		.join( '' );
+
+const simulate = ( matrix: Matrix, [ r, g, b ]: number[] ): number[] =>
+	[ 0, 3, 6 ].map( row =>
+		Math.min( 1, Math.max( 0, matrix[ row ] * r + matrix[ row + 1 ] * g + matrix[ row + 2 ] * b ) )
+	);
+
+const linearToLab = ( [ r, g, b ]: number[] ): Lab => {
+	const x = ( 0.4124564 * r + 0.3575761 * g + 0.1804375 * b ) / 0.95047;
+	const y = 0.2126729 * r + 0.7151522 * g + 0.072175 * b;
+	const z = ( 0.0193339 * r + 0.119192 * g + 0.9503041 * b ) / 1.08883;
+	const f = ( t: number ): number =>
+		t > 216 / 24389 ? Math.cbrt( t ) : ( ( 24389 / 27 ) * t + 16 ) / 116;
+	return [ 116 * f( y ) - 16, 500 * ( f( x ) - f( y ) ), 200 * ( f( y ) - f( z ) ) ];
+};
+
+/**
+ * CIEDE2000 color difference between two CIELAB colors.
+ *
+ * @param first  - First color in CIELAB.
+ * @param second - Second color in CIELAB.
+ * @return ΔE00; about 10 is where two chart categories stop being reliably distinguishable.
+ */
+export const deltaE2000 = ( first: Lab, second: Lab ): number => {
+	const [ l1, a1, b1 ] = first;
+	const [ l2, a2, b2 ] = second;
+	const chromaMean = ( Math.hypot( a1, b1 ) + Math.hypot( a2, b2 ) ) / 2;
+	const g = 0.5 * ( 1 - Math.sqrt( chromaMean ** 7 / ( chromaMean ** 7 + 25 ** 7 ) ) );
+	const a1p = a1 * ( 1 + g );
+	const a2p = a2 * ( 1 + g );
+	const c1p = Math.hypot( a1p, b1 );
+	const c2p = Math.hypot( a2p, b2 );
+	const hueOf = ( a: number, b: number ): number =>
+		a === 0 && b === 0 ? 0 : ( Math.atan2( b, a ) / DEGREES + 360 ) % 360;
+	const h1p = hueOf( a1p, b1 );
+	const h2p = hueOf( a2p, b2 );
+	const chromatic = c1p * c2p !== 0;
+
+	let hueDelta = chromatic ? h2p - h1p : 0;
+	if ( hueDelta > 180 ) {
+		hueDelta -= 360;
+	} else if ( hueDelta < -180 ) {
+		hueDelta += 360;
+	}
+
+	const lightnessDelta = l2 - l1;
+	const chromaDelta = c2p - c1p;
+	const hueDifference = 2 * Math.sqrt( c1p * c2p ) * Math.sin( ( hueDelta * DEGREES ) / 2 );
+	const lightnessMean = ( l1 + l2 ) / 2;
+	const chromaMeanPrime = ( c1p + c2p ) / 2;
+
+	let hueMean = h1p + h2p;
+	if ( chromatic ) {
+		if ( Math.abs( h1p - h2p ) > 180 ) {
+			hueMean += hueMean < 360 ? 360 : -360;
+		}
+		hueMean /= 2;
+	}
+
+	const t =
+		1 -
+		0.17 * Math.cos( ( hueMean - 30 ) * DEGREES ) +
+		0.24 * Math.cos( 2 * hueMean * DEGREES ) +
+		0.32 * Math.cos( ( 3 * hueMean + 6 ) * DEGREES ) -
+		0.2 * Math.cos( ( 4 * hueMean - 63 ) * DEGREES );
+	const lightnessScale =
+		1 + ( 0.015 * ( lightnessMean - 50 ) ** 2 ) / Math.sqrt( 20 + ( lightnessMean - 50 ) ** 2 );
+	const chromaScale = 1 + 0.045 * chromaMeanPrime;
+	const hueScale = 1 + 0.015 * chromaMeanPrime * t;
+	const rotation =
+		-2 *
+		Math.sqrt( chromaMeanPrime ** 7 / ( chromaMeanPrime ** 7 + 25 ** 7 ) ) *
+		Math.sin( 60 * Math.exp( -( ( ( hueMean - 275 ) / 25 ) ** 2 ) ) * DEGREES );
+
+	const lightnessTerm = lightnessDelta / lightnessScale;
+	const chromaTerm = chromaDelta / chromaScale;
+	const hueTerm = hueDifference / hueScale;
+
+	return Math.sqrt(
+		lightnessTerm ** 2 + chromaTerm ** 2 + hueTerm ** 2 + rotation * chromaTerm * hueTerm
+	);
+};
+
+/**
+ * A hex color in CIELAB as seen in normal vision, under deuteranopia and under protanopia.
+ *
+ * @param  hex - Six-digit hex color.
+ * @return The three views.
+ * @throws {Error} if hex string is malformed
+ */
+export const hexToViews = ( hex: string ): ColorViews => {
+	const linear = hexToLinear( hex );
+	return [
+		linearToLab( linear ),
+		linearToLab( simulate( DEUTERANOPIA, linear ) ),
+		linearToLab( simulate( PROTANOPIA, linear ) ),
+	];
+};
+
+/**
+ * The smallest ΔE00 between two colors across the three views.
+ *
+ * @param first  - First color's views.
+ * @param second - Second color's views.
+ * @return The distance in the view where the two are hardest to tell apart.
+ */
+export const viewDistance = ( first: ColorViews, second: ColorViews ): number =>
+	Math.min(
+		deltaE2000( first[ 0 ], second[ 0 ] ),
+		deltaE2000( first[ 1 ], second[ 1 ] ),
+		deltaE2000( first[ 2 ], second[ 2 ] )
+	);
+
+/**
+ * Convert an OKLCH color to sRGB hex.
+ *
+ * @param lightness - OKLab L, 0 to 1.
+ * @param chroma    - OKLCH C.
+ * @param hue       - Hue in degrees.
+ * @return Hex color, or null when the color is outside the sRGB gamut.
+ */
+export const oklchToHex = ( lightness: number, chroma: number, hue: number ): string | null => {
+	const a = chroma * Math.cos( hue * DEGREES );
+	const b = chroma * Math.sin( hue * DEGREES );
+	const l = ( lightness + 0.3963377774 * a + 0.2158037573 * b ) ** 3;
+	const m = ( lightness - 0.1055613458 * a - 0.0638541728 * b ) ** 3;
+	const s = ( lightness - 0.0894841775 * a - 1.291485548 * b ) ** 3;
+	const linear = [
+		4.0767416621 * l - 3.3077633306 * m + 0.2309645873 * s,
+		-1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s,
+		-0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s,
+	];
+	const tolerance = 1e-4;
+	if ( linear.some( channel => channel < -tolerance || channel > 1 + tolerance ) ) {
+		return null;
+	}
+	return linearToHex( linear );
+};
+
+/**
+ * OKLCH chroma and hue of a hex color.
+ *
+ * @param  hex - Six-digit hex color.
+ * @return Chroma, and hue in degrees from 0 to 360.
+ * @throws {Error} if hex string is malformed
+ */
+export const hexToOklch = ( hex: string ): { chroma: number; hue: number } => {
+	const [ r, g, b ] = hexToLinear( hex );
+	const l = Math.cbrt( 0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b );
+	const m = Math.cbrt( 0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b );
+	const s = Math.cbrt( 0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b );
+	const a = 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s;
+	const bAxis = 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s;
+	return {
+		chroma: Math.hypot( a, bAxis ),
+		hue: ( Math.atan2( bAxis, a ) / DEGREES + 360 ) % 360,
+	};
+};
+
+/**
+ * WCAG contrast ratio between two relative luminances.
+ *
+ * @param first  - First relative luminance.
+ * @param second - Second relative luminance.
+ * @return Ratio from 1 to 21.
+ */
+export const luminanceContrastRatio = ( first: number, second: number ): number =>
+	( Math.max( first, second ) + 0.05 ) / ( Math.min( first, second ) + 0.05 );
+
+/**
+ * WCAG contrast ratio between two hex colors.
+ *
+ * @param  first  - First hex color.
+ * @param  second - Second hex color.
+ * @return Ratio from 1 to 21.
+ * @throws {Error} if either hex string is malformed
+ */
+export const contrastRatio = ( first: string, second: string ): number =>
+	luminanceContrastRatio( relativeLuminance( first ), relativeLuminance( second ) );

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

@@ -23,7 +23,7 @@ export const seriesRole = ( slot: number ): string => `--a8c-charts-color-series
  * 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';
+export const SERIES_SLOT_1_FALLBACK = '#3858e9';
 
 /** The catalog pointer for every slot, in slot order. */
 export const SERIES_PALETTE_POINTERS: readonly string[] = Array.from(

package/src/providers/chart-context/test/chart-context.test.tsx

@@ -4,6 +4,7 @@ import { GlobalChartsProvider } from '../global-charts-provider';
 import { useChartId } from '../hooks/use-chart-id';
 import { useChartRegistration } from '../hooks/use-chart-registration';
 import { useGlobalChartsContext } from '../hooks/use-global-charts-context';
+import { createPaletteGenerator } from '../private/palette-generator';
 import { defaultTheme } from '../themes';
 import type { BaseLegendItem } from '../../../components/legend';
 import type { SeriesData } from '../../../types';
@@ -1893,13 +1894,22 @@ describe( 'ChartContext', () => {
 			return <div>Test</div>;
 		};
 
-		const renderWithSlots = ( slots: Array< string | undefined > ) => {
+		const renderWithSlots = (
+			slots: Array< string | undefined >,
+			extraRoles?: Record< string, string >
+		) => {
 			slots.forEach( ( color, slot ) => {
 				if ( color !== undefined ) {
 					container.style.setProperty( `--a8c-charts-color-series-${ slot + 1 }`, color );
 				}
 			} );
 
+			if ( extraRoles ) {
+				Object.entries( extraRoles ).forEach( ( [ property, value ] ) =>
+					container.style.setProperty( property, value )
+				);
+			}
+
 			return render(
 				<GlobalChartsProvider>
 					<TestComponent />
@@ -1990,19 +2000,16 @@ describe( 'ChartContext', () => {
 		} );
 
 		describe( 'Error Handling', () => {
-			it( 'keeps an unparseable value without crashing', () => {
+			it( 'compacts out an unparseable value without crashing', () => {
 				expect( () => renderWithSlots( [ '#invalid', '#ff0000' ] ) ).not.toThrow();
 
-				expect( colorAt( 0 ) ).toBe( '#invalid' );
-				expect( colorAt( 1 ) ).toBe( '#ff0000' );
+				expect( colorAt( 0 ) ).toBe( '#ff0000' );
 			} );
 
-			it( 'keeps malformed hex values without crashing', () => {
+			it( 'compacts out malformed hex values without crashing', () => {
 				expect( () => renderWithSlots( [ '#ff', '#gggggg', '#00ff00' ] ) ).not.toThrow();
 
-				expect( colorAt( 0 ) ).toBe( '#ff' );
-				expect( colorAt( 1 ) ).toBe( '#gggggg' );
-				expect( colorAt( 2 ) ).toBe( '#00ff00' );
+				expect( colorAt( 0 ) ).toBe( '#00ff00' );
 			} );
 
 			it( 'keeps resolving the later slots after one fails to convert', () => {
@@ -2034,6 +2041,79 @@ describe( 'ChartContext', () => {
 			} );
 		} );
 
+		describe( 'Background-aware generation', () => {
+			const seed = '#3858e9';
+			const labels = [ '#1e1e1e', '#f0f0f0' ];
+
+			it( 'wires the resolved dark background into the generator', () => {
+				// Fixture guard: proves index 1 actually depends on the background for this seed,
+				// so a match below can't pass by coincidence.
+				const onDark = createPaletteGenerator( [ seed ], '#1e1e1e', labels )( 1 );
+				const onLight = createPaletteGenerator( [ seed ], '#ffffff', labels )( 1 );
+				expect( onDark ).not.toBe( onLight );
+
+				renderWithSlots( [ seed ], { '--a8c-charts-color-background': '#1e1e1e' } );
+
+				expect( colorAt( 1 ) ).toBe( onDark );
+			} );
+
+			it( 'falls back to a white background when the resolved value does not normalize to hex', () => {
+				renderWithSlots( [ seed ], { '--a8c-charts-color-background': 'not-a-real-color' } );
+
+				expect( colorAt( 1 ) ).toBe( createPaletteGenerator( [ seed ], '#ffffff', labels )( 1 ) );
+			} );
+
+			it( 'falls back to a white background when the background is transparent', () => {
+				const onWhite = createPaletteGenerator( [ seed ], '#ffffff', labels )( 1 );
+				const onBlack = createPaletteGenerator( [ seed ], '#000000', labels )( 1 );
+				expect( onWhite ).not.toBe( onBlack );
+
+				renderWithSlots( [ seed ], { '--a8c-charts-color-background': 'transparent' } );
+
+				expect( colorAt( 1 ) ).toBe( onWhite );
+			} );
+
+			it( 'falls back to a white background when the background is a translucent color', () => {
+				const onWhite = createPaletteGenerator( [ seed ], '#ffffff', labels )( 1 );
+				const onBlack = createPaletteGenerator( [ seed ], '#000000', labels )( 1 );
+				expect( onWhite ).not.toBe( onBlack );
+
+				renderWithSlots( [ seed ], { '--a8c-charts-color-background': 'rgba(0, 0, 0, 0.5)' } );
+
+				expect( colorAt( 1 ) ).toBe( onWhite );
+			} );
+
+			it( 'wires the resolved label colors into the generator, leaving out a see-through one', () => {
+				const firstSix = ( at: ( index: number ) => string ) =>
+					Array.from( { length: 6 }, ( _, index ) => at( index ) );
+				const inverseOnly = firstSix(
+					createPaletteGenerator( [ seed ], '#ffffff', [ '#f0f0f0' ] )
+				);
+				expect( inverseOnly ).not.toEqual(
+					firstSix( createPaletteGenerator( [ seed ], '#ffffff', labels ) )
+				);
+
+				renderWithSlots( [ seed ], { '--a8c-charts-color-label': 'transparent' } );
+
+				expect( firstSix( colorAt ) ).toEqual( inverseOnly );
+			} );
+
+			it( 'uses the resolved background for group colors when no seed resolves', () => {
+				const background = '#1e1e1e';
+
+				// An unparseable slot 1 keeps the resolved palette empty even after resolution;
+				// an unset slot 1 would instead fall back to its own terminal literal.
+				renderWithSlots( [ '#invalid' ], { '--a8c-charts-color-background': background } );
+
+				const groupColor = contextValue.getElementStyles( {
+					data: createMockDataWithGroup( 'test-group' ),
+					index: 0,
+				} ).color;
+
+				expect( groupColor ).toBe( createPaletteGenerator( [], background, labels )( 0 ) );
+			} );
+		} );
+
 		describe( 'Server-Side Rendering', () => {
 			// Slot 1's terminal literal is the palette's only carrier under SSR.
 			it( 'falls back to the seed when getComputedStyle is unavailable', () => {

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

@@ -0,0 +1,27 @@
+import { render } from '@testing-library/react';
+import { GlobalChartsProvider } from '../global-charts-provider';
+import { useGlobalChartsContext } from '../hooks/use-global-charts-context';
+
+describe( 'GlobalChartsProvider before the palette resolves', () => {
+	it( 'renders the same colors an unthemed page resolves to', () => {
+		const renders: string[][] = [];
+
+		const FirstColors = () => {
+			const { getElementStyles } = useGlobalChartsContext();
+			renders.push(
+				Array.from( { length: 6 }, ( _, index ) => getElementStyles( { index } ).color )
+			);
+			return null;
+		};
+
+		render(
+			<GlobalChartsProvider>
+				<FirstColors />
+			</GlobalChartsProvider>
+		);
+
+		expect( renders.length ).toBeGreaterThan( 1 );
+		expect( renders[ 0 ][ 0 ] ).toBe( '#3858e9' );
+		expect( renders[ 0 ] ).toEqual( renders[ renders.length - 1 ] );
+	} );
+} );