@automattic/charts 4.4.0 → 4.5.0

package/src/components/tooltip/test/accessible-tooltip.test.tsx

@@ -1,6 +1,6 @@
-import { render, screen } from '@testing-library/react';
+import { act, render, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
-import { useRef, useState } from 'react';
+import { useCallback, useRef, useState } from 'react';
 import { LineChartUnresponsive } from '../../../charts/line-chart/line-chart';
 import { GlobalChartsProvider } from '../../../providers';
 import { ChartScopeContext } from '../../../providers/chart-scope';
@@ -128,11 +128,17 @@ describe( 'AccessibleTooltip', () => {
 } );
 
 // Mirrors the charts' markup: the focusable grid wraps the element `chartRef` points at.
-const NavigationHarness = ( { totalPoints }: { totalPoints: number } ) => {
+const NavigationHarness = ( {
+	totalPoints,
+	trackBlur = false,
+}: {
+	totalPoints: number;
+	trackBlur?: boolean;
+} ) => {
 	const [ selectedIndex, setSelectedIndex ] = useState< number | undefined >();
 	const [ isNavigating, setIsNavigating ] = useState( false );
 	const chartRef = useRef< HTMLDivElement >( null );
-	const { onChartKeyDown } = useKeyboardNavigation( {
+	const { onChartKeyDown, onChartBlur, onChartPointerMove } = useKeyboardNavigation( {
 		selectedIndex,
 		setSelectedIndex,
 		isNavigating,
@@ -140,14 +146,24 @@ const NavigationHarness = ( { totalPoints }: { totalPoints: number } ) => {
 		chartRef,
 		totalPoints,
 	} );
+	const moveToFour = useCallback( () => onChartPointerMove( 4 ), [ onChartPointerMove ] );
+	const moveToOne = useCallback( () => onChartPointerMove( 1 ), [ onChartPointerMove ] );
 
 	return (
 		<>
-			<div role="grid" aria-label="Harness" tabIndex={ 0 } onKeyDown={ onChartKeyDown }>
+			<div
+				role="grid"
+				aria-label="Harness"
+				tabIndex={ 0 }
+				onKeyDown={ onChartKeyDown }
+				onBlur={ trackBlur ? onChartBlur : undefined }
+			>
 				<div ref={ chartRef } data-testid="selected-index">
 					{ selectedIndex ?? 'none' }
 					<button type="button">Inside</button>
 				</div>
+				<div data-testid="point-4" onPointerMove={ moveToFour } />
+				<div data-testid="point-1" onPointerMove={ moveToOne } />
 			</div>
 			<button type="button">Outside</button>
 		</>
@@ -207,6 +223,67 @@ describe( 'useKeyboardNavigation', () => {
 		expect( screen.getByRole( 'grid', { name: 'Harness' } ) ).toHaveFocus();
 	} );
 
+	it( 'hands a keyboard selection to the pointer and continues from where the pointer is', async () => {
+		const { user } = await navigate( 2 );
+
+		screen.getByRole( 'button', { name: 'Inside' } ).focus();
+		await user.hover( screen.getByTestId( 'point-4' ) );
+
+		expect( screen.getByTestId( 'selected-index' ) ).toHaveTextContent( 'none' );
+		expect( screen.getByRole( 'grid', { name: 'Harness' } ) ).toHaveFocus();
+
+		await user.keyboard( '{ArrowRight}' );
+
+		expect( screen.getByTestId( 'selected-index' ) ).toHaveTextContent( '5' );
+	} );
+
+	it( 'continues from the last point the pointer reached after taking over', async () => {
+		const { user } = await navigate( 2 );
+
+		await user.hover( screen.getByTestId( 'point-4' ) );
+		await user.hover( screen.getByTestId( 'point-1' ) );
+		await user.keyboard( '{ArrowRight}' );
+
+		expect( screen.getByTestId( 'selected-index' ) ).toHaveTextContent( '2' );
+	} );
+
+	it( 'restarts from the first point once focus leaves after the pointer took over', async () => {
+		const user = userEvent.setup();
+		render( <NavigationHarness totalPoints={ 6 } trackBlur /> );
+		const grid = screen.getByRole( 'grid', { name: 'Harness' } );
+
+		act( () => grid.focus() );
+		await user.keyboard( '{ArrowRight}{ArrowRight}' );
+		await user.hover( screen.getByTestId( 'point-4' ) );
+		act( () => screen.getByRole( 'button', { name: 'Outside' } ).focus() );
+		act( () => grid.focus() );
+		await user.keyboard( '{ArrowRight}' );
+
+		expect( screen.getByTestId( 'selected-index' ) ).toHaveTextContent( '0' );
+	} );
+
+	it( 'leaves focus outside the chart when the pointer ends a selection', async () => {
+		const { user } = await navigate( 2 );
+		const outside = screen.getByRole( 'button', { name: 'Outside' } );
+
+		outside.focus();
+		await user.hover( screen.getByTestId( 'point-4' ) );
+
+		expect( screen.getByTestId( 'selected-index' ) ).toHaveTextContent( 'none' );
+		expect( outside ).toHaveFocus();
+	} );
+
+	it( 'ignores the pointer when there is no keyboard selection', async () => {
+		const user = userEvent.setup();
+		render( <NavigationHarness totalPoints={ 6 } /> );
+
+		screen.getByRole( 'grid', { name: 'Harness' } ).focus();
+		await user.hover( screen.getByTestId( 'point-4' ) );
+		await user.keyboard( '{ArrowRight}' );
+
+		expect( screen.getByTestId( 'selected-index' ) ).toHaveTextContent( '0' );
+	} );
+
 	// The page sees the event after the handler, so this is what a surrounding scroll or Modal gets.
 	const recordPageKeyDown = () => {
 		const onKeyDown = jest.fn< void, [ KeyboardEvent ] >();

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

@@ -1,4 +1,4 @@
-import { hsl as d3Hsl } from '@visx/vendor/d3-color';
+import { color as d3Color } from '@visx/vendor/d3-color';
 import {
 	createContext,
 	useCallback,
@@ -17,6 +17,7 @@ import {
 	getItemShapeStyles,
 	getSeriesBarStyles,
 	getSeriesLineStyles,
+	isValidHexColor,
 	mergeThemes,
 	resolveCssVariable,
 	normalizeColorToHex,
@@ -24,13 +25,39 @@ import {
 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 {
+	BACKGROUND_FALLBACK,
+	CATALOG_POINTERS,
+	LABEL_FALLBACK,
+	LABEL_INVERSE_FALLBACK,
+} from './private/catalog-pointers';
+import { createPaletteGenerator } from './private/palette-generator';
+import { SERIES_PALETTE_POINTERS, SERIES_SLOT_1_FALLBACK } from './private/series-palette';
 import { defaultTheme } from './themes';
 import type { GlobalChartsContextValue, ChartRegistration } from './types';
 import type { ChartTheme, CompleteChartTheme } from '../../types';
 import type { FC, ReactNode } from 'react';
 
+interface ColorCache {
+	colors: string[];
+	background: string;
+	labelColors: string[];
+	colorAt: ( index: number ) => string;
+}
+
+// A see-through color (transparent, or any alpha below 1) says nothing about what it will look like
+// over the chart, so it resolves to null rather than let its RGB leak into the palette.
+const resolveOpaqueHex = ( pointer: string, element: HTMLElement | null ): string | null => {
+	const raw = resolveCssVariable( pointer, element );
+	if ( ! raw || d3Color( raw )?.opacity !== 1 ) {
+		return null;
+	}
+	const hex = normalizeColorToHex( pointer, element, resolveCssVariable );
+	return isValidHexColor( hex ) ? hex : null;
+};
+
+const PLACEHOLDER_LABEL_COLORS = [ LABEL_FALLBACK, LABEL_INVERSE_FALLBACK ];
+
 export const GlobalChartsContext = createContext< GlobalChartsContextValue | null >( null );
 
 export interface GlobalChartsProviderProps {
@@ -81,12 +108,17 @@ export const GlobalChartsProvider: FC< GlobalChartsProviderProps > = ( {
 	// 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
+	// Seeded with what slot 1 resolves to where no DOM answers, so a one-series first render
+	// never builds the candidate grid and SSR matches the unthemed client palette.
 	const [ colorCache, setColorCache ] = useState< ColorCache >( () => ( {
 		colors: [],
-		hues: [],
-		existingHslColors: [],
-		minHue: 360,
-		maxHue: 0,
+		background: BACKGROUND_FALLBACK,
+		labelColors: PLACEHOLDER_LABEL_COLORS,
+		colorAt: createPaletteGenerator(
+			[ SERIES_SLOT_1_FALLBACK ],
+			BACKGROUND_FALLBACK,
+			PLACEHOLDER_LABEL_COLORS
+		),
 	} ) );
 
 	// Track if the color palette has been resolved from the DOM
@@ -100,45 +132,29 @@ export const GlobalChartsProvider: FC< GlobalChartsProviderProps > = ( {
 	useLayoutEffect( () => {
 		setIsColorPaletteResolved( false );
 		const resolvedColors: string[] = [];
-		const hues: number[] = [];
-		const existingHslColors: Array< [ number, number, number ] > = [];
-		let minHue = 360;
-		let maxHue = 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( '#' ) ) {
+			// An unset palette slot returns its own `var()` unchanged, so this is also what
+			// compacts the palette: a slot the consumer never set drops out here.
+			if ( isValidHexColor( normalizedColor ) ) {
 				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 ] );
-				}
 			}
 		}
 
+		const backgroundHex =
+			resolveOpaqueHex( CATALOG_POINTERS.background, wrapperRef.current ) ?? BACKGROUND_FALLBACK;
+		// The two roles pie labels choose between on a fill; one left see-through is never painted there.
+		const labelColors = [ CATALOG_POINTERS.label, CATALOG_POINTERS.labelInverse ]
+			.map( pointer => resolveOpaqueHex( pointer, wrapperRef.current ) )
+			.filter( ( hex ): hex is string => hex !== null );
+
 		setColorCache( {
 			colors: resolvedColors,
-			hues,
-			existingHslColors,
-			minHue,
-			maxHue,
+			background: backgroundHex,
+			labelColors,
+			colorAt: createPaletteGenerator( resolvedColors, backgroundHex, labelColors ),
 		} );
 	}, [] );
 
@@ -152,9 +168,9 @@ export const GlobalChartsProvider: FC< GlobalChartsProviderProps > = ( {
 		() => new Map()
 	);
 
-	// 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( ',' );
+	// Keyed on the resolved colors, background and labels, not the cache object, so a consumer passing an
+	// inline `theme` cannot reset the map on every render.
+	const paletteKey = `${ colorCache.colors.join( ',' ) }|${ colorCache.background }|${ colorCache.labelColors.join( ',' ) }`;
 
 	useEffect( () => {
 		// Create a completely new Map instance to trigger dependencies, e.g. useChartLegendItems
@@ -206,13 +222,13 @@ export const GlobalChartsProvider: FC< GlobalChartsProviderProps > = ( {
 				// Use map size as index to assign colors sequentially (0, 1, 2...)
 				// ensuring each new group gets the next available palette color
 				const assignedCount = groupToColorMap.size;
-				const color = getChartColor( assignedCount, colorCache );
+				const color = colorCache.colorAt( assignedCount );
 				groupToColorMap.set( group, color );
 
 				return color;
 			}
 
-			return getChartColor( index, colorCache );
+			return colorCache.colorAt( index );
 		},
 		[ colorCache, groupToColorMap ]
 	);

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

@@ -4,9 +4,17 @@ 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.
  */
+/** Terminal literals the provider also generates from before its first read, so SSR and the first client render agree. */
+export const BACKGROUND_FALLBACK = '#ffffff';
+export const LABEL_FALLBACK = '#1e1e1e';
+export const LABEL_INVERSE_FALLBACK = '#f0f0f0';
+
 export const CATALOG_POINTERS = {
-	background: 'var(--a8c-charts-color-background, #fff)',
+	background: `var(--a8c-charts-color-background, ${ BACKGROUND_FALLBACK })`,
+	label: `var(--a8c-charts-color-label, ${ LABEL_FALLBACK })`,
 	labelAxis: 'var(--a8c-charts-color-label-axis, #1e1e1e)',
+	labelInverse: `var(--a8c-charts-color-label-inverse, ${ LABEL_INVERSE_FALLBACK })`,
+	labelBackground: 'var(--a8c-charts-color-label-background, transparent)',
 	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)',

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;
+	};
+};