@automattic/charts 4.8.0 → 4.10.0

package/src/charts/pie-semi-circle-chart/pie-semi-circle-chart.tsx

@@ -1,11 +1,10 @@
 import { Group } from '@visx/group';
-import { Pie } from '@visx/shape';
+import { arc, pie } from '@visx/shape';
 import { Text } from '@visx/text';
-import { useTooltip } from '@visx/tooltip';
+import { __ } from '@wordpress/i18n';
 import clsx from 'clsx';
-import { useCallback, useContext, useMemo, useRef } from 'react';
+import { useContext, useMemo } from 'react';
 import { Legend, useChartLegendItems } from '../../components/legend';
-import { BoundedTooltip } from '../../components/tooltip/private/bounded-tooltip';
 import { LabelValueContent } from '../../components/tooltip/private/label-value-content';
 import {
 	useDataWithPercentages,
@@ -19,12 +18,17 @@ import {
 	useGlobalChartsContext,
 	GlobalChartsContext,
 } from '../../providers';
-import { useStandaloneScopeClass } from '../../providers/chart-scope';
 import { attachSubComponents } from '../../utils';
 import { Center } from '../private/center';
 import { ChartSVG, ChartHTML, useChartChildren } from '../private/chart-composition';
 import { ChartInstanceContext } from '../private/chart-instance-context';
 import { ChartLayout } from '../private/chart-layout';
+import {
+	orderArcsForNavigation,
+	PieSelectionOutput,
+	SelectedSegmentRing,
+	usePieKeyboardNavigation,
+} from '../private/pie-keyboard-navigation';
 import { RadialWipeAnimation } from '../private/radial-wipe-animation';
 import { getAllHiddenMessage, SvgEmptyState } from '../private/svg-empty-state';
 import { withResponsive } from '../private/with-responsive';
@@ -39,7 +43,7 @@ import type {
 import type { ChartComponentWithComposition } from '../private/chart-composition';
 import type { ResponsiveConfig } from '../private/with-responsive';
 import type { PieProvidedProps } from '@visx/shape';
-import type { FC, MouseEvent, ReactNode } from 'react';
+import type { FC, ReactNode } from 'react';
 
 /**
  * Parameters passed to the renderTooltip function for semi-circle charts.
@@ -138,6 +142,9 @@ type PieSemiCircleChartResponsiveComponent = ChartComponentWithComposition<
 
 export type ArcData = PieProvidedProps< DataPointPercentageCalculated >[ 'arcs' ][ number ];
 
+type PieDatum = DataPointPercentageCalculated & { index: number };
+type PieArcDatum = PieProvidedProps< PieDatum >[ 'arcs' ][ number ];
+
 /**
  * Validates the semi-circle pie chart data
  * @param data - The data to validate
@@ -182,45 +189,13 @@ const PieSemiCircleChartInternal: FC< PieSemiCircleChartProps > = ( {
 	tooltipOffsetX = 0,
 	tooltipOffsetY = -15,
 	renderTooltip = renderDefaultPieSemiCircleTooltip,
+	ariaLabel,
 	gap = 'md',
 } ) => {
 	const legendInteractive = legend.interactive ?? false;
 	const legendPosition = legend.position ?? 'bottom';
 
 	const chartId = useChartId( providedChartId );
-	const { tooltipOpen, tooltipLeft, tooltipTop, tooltipData, hideTooltip, showTooltip } =
-		useTooltip< DataPointPercentageCalculated >();
-	const standaloneScopeClass = useStandaloneScopeClass();
-
-	// The tooltip renders inside this element, so pointer coordinates are taken relative to it.
-	const containerRef = useRef< HTMLDivElement >( null );
-
-	const handleMouseMove = useCallback(
-		( event: MouseEvent< SVGElement >, arc: ArcData ) => {
-			const bounds = containerRef.current?.getBoundingClientRect();
-			if ( ! bounds ) {
-				return;
-			}
-
-			showTooltip( {
-				tooltipData: arc.data,
-				tooltipLeft: event.clientX - bounds.left + tooltipOffsetX,
-				tooltipTop: event.clientY - bounds.top + tooltipOffsetY,
-			} );
-		},
-		[ showTooltip, tooltipOffsetX, tooltipOffsetY ]
-	);
-
-	const handleMouseLeave = useCallback( () => {
-		hideTooltip();
-	}, [ hideTooltip ] );
-
-	const handleArcMouseMove = useCallback(
-		( arc: ArcData ) => ( event: MouseEvent< SVGElement > ) => {
-			handleMouseMove( event, arc );
-		},
-		[ handleMouseMove ]
-	);
 
 	// Validate data first to get validation result
 	const { isValid, message } = validateData( data );
@@ -285,9 +260,48 @@ const PieSemiCircleChartInternal: FC< PieSemiCircleChartProps > = ( {
 	} );
 
 	const prefersReducedMotion = usePrefersReducedMotion();
+	const wipeMask = animation && ! prefersReducedMotion ? `url(#radial-wipe-${ chartId })` : null;
 
 	const effectiveWidth = propWidth || DEFAULT_WIDTH;
 
+	// Map data with index for color assignment
+	// When interactive, we need to find the original index to maintain consistent colors
+	const dataWithIndex = visibleData.map( d => {
+		const originalIndex = data.findIndex( item => item.label === d.label );
+		return {
+			...d,
+			index: originalIndex >= 0 ? originalIndex : 0,
+		};
+	} );
+
+	// Configure pie angles based on clockwise direction
+	const startAngle = clockwise ? -Math.PI / 2 : Math.PI / 2;
+	const endAngle = clockwise ? Math.PI / 2 : -Math.PI / 2;
+
+	const arcs = pie< PieDatum >( {
+		value: accessors.value,
+		sort: accessors.sort,
+		padAngle: PAD_ANGLE,
+		startAngle,
+		endAngle,
+	} )( dataWithIndex );
+	const navigationArcs = orderArcsForNavigation( arcs );
+
+	const {
+		chartRef,
+		svgRef,
+		selectedArc,
+		getSegmentHandlers,
+		getKeyboardTooltipAnchor,
+		selectionOutputProps,
+		chartProps,
+	} = usePieKeyboardNavigation( {
+		navigationArcs,
+		withTooltips,
+		tooltipOffsetX,
+		tooltipOffsetY,
+	} );
+
 	if ( ! isValid ) {
 		const errorWidth = propHeight
 			? Math.min( propWidth || propHeight * 2, propHeight * 2 )
@@ -307,20 +321,6 @@ const PieSemiCircleChartInternal: FC< PieSemiCircleChartProps > = ( {
 		);
 	}
 
-	// Map data with index for color assignment
-	// When interactive, we need to find the original index to maintain consistent colors
-	const dataWithIndex = visibleData.map( d => {
-		const originalIndex = data.findIndex( item => item.label === d.label );
-		return {
-			...d,
-			index: originalIndex >= 0 ? originalIndex : 0,
-		};
-	} );
-
-	// Configure pie angles based on clockwise direction
-	const startAngle = clockwise ? -Math.PI / 2 : Math.PI / 2;
-	const endAngle = clockwise ? Math.PI / 2 : -Math.PI / 2;
-
 	const legendElement = showLegend && (
 		<Legend
 			orientation={ legend.orientation ?? 'horizontal' }
@@ -376,9 +376,17 @@ const PieSemiCircleChartInternal: FC< PieSemiCircleChartProps > = ( {
 					const radius = height; // For a semi-circle, radius equals the SVG height
 					const innerRadius = radius * ( 1 - thickness );
 
+					const path = arc< PieArcDatum >( { innerRadius, outerRadius: radius, cornerRadius: 3 } );
+
 					return (
-						<Center ref={ containerRef } className={ styles[ 'pie-semi-circle-chart__plot' ] }>
+						<Center
+							ref={ chartRef }
+							className={ styles[ 'pie-semi-circle-chart__plot' ] }
+							{ ...chartProps }
+							aria-label={ ariaLabel ?? __( 'Semi-circle chart', 'jetpack-charts' ) }
+						>
 							<svg
+								ref={ svgRef }
 								width={ width }
 								height={ height }
 								viewBox={ `0 0 ${ width } ${ height }` }
@@ -395,81 +403,70 @@ const PieSemiCircleChartInternal: FC< PieSemiCircleChartProps > = ( {
 								</defs>
 
 								{ /* Main chart group centered horizontally and positioned at bottom */ }
-								<Group
-									top={ height }
-									left={ width / 2 }
-									mask={
-										animation && ! prefersReducedMotion ? `url(#radial-wipe-${ chartId })` : null
-									}
-								>
+								<Group top={ height } left={ width / 2 } mask={ wipeMask }>
 									{ allSegmentsHidden ? (
 										<SvgEmptyState x={ 0 } y={ -radius / 2 } width={ width } height={ height }>
 											{ getAllHiddenMessage( legendInteractive, 'segments' ) }
 										</SvgEmptyState>
 									) : (
-										<>
-											{ /* Pie chart */ }
-											<Pie< DataPointPercentageCalculated & { index: number } >
-												data={ dataWithIndex }
-												pieValue={ accessors.value }
-												outerRadius={ radius }
-												innerRadius={ innerRadius }
-												cornerRadius={ 3 }
-												padAngle={ PAD_ANGLE }
-												startAngle={ startAngle }
-												endAngle={ endAngle }
-												pieSort={ accessors.sort }
+										arcs.map( arcDatum => (
+											<g
+												key={ arcDatum.data.label }
+												{ ...getSegmentHandlers(
+													arcDatum.data,
+													navigationArcs.indexOf( arcDatum )
+												) }
 											>
-												{ pie => {
-													return pie.arcs.map( arc => (
-														<g
-															key={ arc.data.label }
-															onMouseMove={ withTooltips ? handleArcMouseMove( arc ) : undefined }
-															onMouseLeave={ withTooltips ? handleMouseLeave : undefined }
-														>
-															<path
-																d={ pie.path( arc ) || '' }
-																fill={ accessors.fill( arc.data ) }
-																data-testid="pie-segment"
-															/>
-														</g>
-													) );
-												} }
-											</Pie>
-
-											{ /* Label and note text */ }
-											<Group>
-												<Text
-													textAnchor="middle"
-													verticalAnchor="start"
-													y={ -40 } // Position above the chart with space for note
-													className={ styles.label }
-												>
-													{ label }
-												</Text>
-												<Text
-													textAnchor="middle"
-													verticalAnchor="start"
-													y={ -20 } // Position between label and chart
-													className={ styles.note }
-												>
-													{ note }
-												</Text>
-											</Group>
-
-											{ /* Render SVG children from composition API */ }
-											{ ! allSegmentsHidden && svgChildren }
-										</>
+												<path
+													d={ path( arcDatum ) || '' }
+													fill={ accessors.fill( arcDatum.data ) }
+													data-testid="pie-segment"
+												/>
+											</g>
+										) )
 									) }
 								</Group>
+								{ /* Unmasked so the entry wipe cannot hide the focus indicator. */ }
+								{ selectedArc && (
+									<Group top={ height } left={ width / 2 }>
+										<SelectedSegmentRing chartId={ chartId } d={ path( selectedArc ) || '' } />
+									</Group>
+								) }
+								{ ! allSegmentsHidden && (
+									<Group top={ height } left={ width / 2 } mask={ wipeMask }>
+										{ /* Label and note text */ }
+										<Group>
+											<Text
+												textAnchor="middle"
+												verticalAnchor="start"
+												y={ -40 } // Position above the chart with space for note
+												className={ styles.label }
+											>
+												{ label }
+											</Text>
+											<Text
+												textAnchor="middle"
+												verticalAnchor="start"
+												y={ -20 } // Position between label and chart
+												className={ styles.note }
+											>
+												{ note }
+											</Text>
+										</Group>
+
+										{ /* Render SVG children from composition API */ }
+										{ svgChildren }
+									</Group>
+								) }
 							</svg>
-							{ withTooltips && tooltipOpen && tooltipData && (
-								<BoundedTooltip top={ tooltipTop || 0 } left={ tooltipLeft || 0 }>
-									<div className={ standaloneScopeClass } role="tooltip">
-										{ renderTooltip( { tooltipData } ) }
-									</div>
-								</BoundedTooltip>
-							) }
+							<PieSelectionOutput
+								{ ...selectionOutputProps }
+								keyboardTooltipAnchor={
+									selectedArc &&
+									getKeyboardTooltipAnchor( width / 2, height, path.centroid( selectedArc ) )
+								}
+								renderTooltip={ renderTooltip }
+							/>
 						</Center>
 					);
 				} }

package/src/charts/pie-semi-circle-chart/test/pie-semi-circle-chart.test.tsx

@@ -363,6 +363,60 @@ describe( 'PieSemiCircleChart', () => {
 	} );
 } );
 
+describe( 'PieSemiCircleChart keyboard navigation', () => {
+	it( 'names the focusable chart', () => {
+		renderPieChart( { data: mockData } );
+		expect( screen.getByRole( 'application', { name: 'Semi-circle chart' } ) ).toHaveAttribute(
+			'tabindex',
+			'0'
+		);
+	} );
+
+	it( 'starts at the leftmost segment, which is the largest value', async () => {
+		const user = userEvent.setup();
+		renderPieChart( { data: mockData, withTooltips: true } );
+
+		await user.tab();
+		await user.keyboard( '{ArrowRight}' );
+
+		await expect( screen.findByTestId( 'chart-tooltip-0' ) ).resolves.toHaveTextContent(
+			'Category B'
+		);
+		expect( screen.getByTestId( 'pie-selected-ring' ) ).toHaveAttribute(
+			'd',
+			screen.getAllByTestId( 'pie-segment' )[ 1 ].getAttribute( 'd' )
+		);
+	} );
+
+	it( 'clears the selection when new values reorder the segments', async () => {
+		const user = userEvent.setup();
+		const { rerender } = renderPieChart( { data: mockData, withTooltips: true } );
+
+		await user.tab();
+		await user.keyboard( '{ArrowRight}' );
+		await expect( screen.findByTestId( 'chart-tooltip-0' ) ).resolves.toHaveTextContent(
+			'Category B'
+		);
+
+		rerender(
+			<GlobalChartsProvider>
+				<PieSemiCircleChart
+					data={ [
+						{ ...mockData[ 0 ], value: 70 },
+						{ ...mockData[ 1 ], value: 30 },
+					] }
+					withTooltips
+				/>
+			</GlobalChartsProvider>
+		);
+
+		await waitFor( () =>
+			expect( screen.queryByTestId( 'pie-selected-ring' ) ).not.toBeInTheDocument()
+		);
+		expect( screen.queryByTestId( 'chart-tooltip-0' ) ).not.toBeInTheDocument();
+	} );
+} );
+
 // Chart container at (100, 50); the tooltip box measures 120x40. Everything
 // else the charts measure (wrapper, clipping lookups) reports the container.
 const mockRects = () =>

package/src/charts/private/chart-composition/use-chart-children.ts

@@ -1,8 +1,9 @@
 import { Group } from '@visx/group';
 import { useMemo, Children, isValidElement } from 'react';
 import { Legend } from '../../../components/legend';
+import type { LegendProps } from '../../../components/legend/types';
 import type { LegendPosition } from '../../../types';
-import type { ReactElement, ReactNode } from 'react';
+import type { PropsWithChildren, ReactElement, ReactNode } from 'react';
 
 export type LegendChild = {
 	element: ReactElement;
@@ -39,7 +40,7 @@ export function useChartChildren( children: ReactNode, chartType: string ): Char
 			if ( isValidElement( child ) ) {
 				// Extract Legend children for position-based slot rendering
 				if ( child.type === Legend ) {
-					const rawPosition = child.props?.position;
+					const rawPosition = ( child as ReactElement< LegendProps > ).props?.position;
 					const position =
 						rawPosition === 'top' || rawPosition === 'bottom' ? rawPosition : 'bottom';
 
@@ -55,15 +56,19 @@ export function useChartChildren( children: ReactNode, chartType: string ): Char
 				// Handle chart-specific compound components (e.g., PieChart.SVG)
 				if ( displayName === `${ chartType }.SVG` || displayName === 'Chart.SVG' ) {
 					// Extract children from Chart.SVG with safety checks
-					if ( child.props?.children ) {
-						Children.forEach( child.props.children, svgChild => {
+					const { children: svgChildren } =
+						( child as ReactElement< PropsWithChildren > ).props ?? {};
+					if ( svgChildren ) {
+						Children.forEach( svgChildren, svgChild => {
 							svg.push( svgChild );
 						} );
 					}
 				} else if ( displayName === `${ chartType }.HTML` || displayName === 'Chart.HTML' ) {
 					// Extract children from Chart.HTML with safety checks
-					if ( child.props?.children ) {
-						Children.forEach( child.props.children, htmlChild => {
+					const { children: htmlChildren } =
+						( child as ReactElement< PropsWithChildren > ).props ?? {};
+					if ( htmlChildren ) {
+						Children.forEach( htmlChildren, htmlChild => {
 							html.push( htmlChild );
 						} );
 					}

package/src/charts/private/pie-keyboard-navigation/index.ts

@@ -0,0 +1,4 @@
+export { orderArcsForNavigation } from './order-arcs-for-navigation';
+export { PieSelectionOutput } from './pie-selection-output';
+export { SelectedSegmentRing } from './selected-segment-ring';
+export { usePieKeyboardNavigation } from './use-pie-keyboard-navigation';

package/src/charts/private/pie-keyboard-navigation/order-arcs-for-navigation.ts

@@ -0,0 +1,10 @@
+type AngledArc = { startAngle: number; endAngle: number };
+
+/**
+ * Orders arcs the way they appear: clockwise from 12 o'clock, which for a semi-circle is left to right.
+ *
+ * @param arcs - Arcs from visx's `pie` factory, in data order.
+ * @return A copy of `arcs` sorted by angular midpoint.
+ */
+export const orderArcsForNavigation = < T extends AngledArc >( arcs: T[] ): T[] =>
+	[ ...arcs ].sort( ( a, b ) => a.startAngle + a.endAngle - ( b.startAngle + b.endAngle ) );

package/src/charts/private/pie-keyboard-navigation/pie-keyboard-navigation.module.scss

@@ -0,0 +1,16 @@
+// The clip to the segment removes the outer half of each stroke,
+// so widths are doubled.
+.selected-ring__contrast,
+.selected-ring__focus {
+	fill: none;
+}
+
+.selected-ring__contrast {
+	stroke: var(--a8c-charts-color-background, #fff);
+	stroke-width: calc(4 * var(--wpds-border-width-focus));
+}
+
+.selected-ring__focus {
+	stroke: var(--wpds-color-stroke-focus);
+	stroke-width: calc(2 * var(--wpds-border-width-focus));
+}

package/src/charts/private/pie-keyboard-navigation/pie-selection-announcement.tsx

@@ -0,0 +1,14 @@
+import { VisuallyHidden } from '@wordpress/ui';
+import { LabelValueContent } from '../../../components/tooltip/private/label-value-content';
+import type { DataPointPercentageCalculated } from '../../../types';
+
+interface PieSelectionAnnouncementProps {
+	/** The keyboard-selected segment, when no tooltip is showing to announce it. */
+	data?: DataPointPercentageCalculated;
+}
+
+export const PieSelectionAnnouncement = ( { data }: PieSelectionAnnouncementProps ) => (
+	<VisuallyHidden role="status" aria-atomic="true">
+		{ data && <LabelValueContent data={ data } /> }
+	</VisuallyHidden>
+);

package/src/charts/private/pie-keyboard-navigation/pie-selection-output.tsx

@@ -0,0 +1,82 @@
+import { useLayoutEffect, useState } from 'react';
+import { PieSelectionAnnouncement } from './pie-selection-announcement';
+import { PieTooltip } from './pie-tooltip';
+import type { DataPointPercentageCalculated } from '../../../types';
+import type { ReactNode, RefObject } from 'react';
+
+interface Position {
+	top: number;
+	left: number;
+}
+
+interface PieSelectionOutputProps {
+	withTooltips: boolean;
+	selectedIndex?: number;
+	/** The keyboard-selected segment's data. */
+	selectedData?: DataPointPercentageCalculated;
+	/** Where the keyboard tooltip points, in SVG coordinates. */
+	keyboardTooltipAnchor?: Position;
+	pointerTooltip?: { data?: DataPointPercentageCalculated; top: number; left: number };
+	/** The element the tooltips are positioned in. */
+	chartRef: RefObject< HTMLDivElement >;
+	svgRef: RefObject< SVGSVGElement >;
+	tooltipRef: ( element: HTMLDivElement | null ) => void;
+	renderTooltip: ( params: { tooltipData: DataPointPercentageCalculated } ) => ReactNode;
+}
+
+/**
+ * Reports the selected segment: a focused tooltip for a keyboard selection, a pointer tooltip on hover, or a screen reader announcement without tooltips.
+ *
+ * @param {PieSelectionOutputProps} props - Component props
+ * @return {JSX.Element} The announcement region and the tooltip, if any
+ */
+export const PieSelectionOutput = ( {
+	withTooltips,
+	selectedIndex,
+	selectedData,
+	keyboardTooltipAnchor,
+	pointerTooltip,
+	chartRef,
+	svgRef,
+	tooltipRef,
+	renderTooltip,
+}: PieSelectionOutputProps ) => {
+	const [ svgOffset, setSvgOffset ] = useState< Position >( { top: 0, left: 0 } );
+	const showKeyboardTooltip = withTooltips && selectedData && keyboardTooltipAnchor;
+
+	// Measured after commit, because during render the SVG still has the previous commit's size and position.
+	// eslint-disable-next-line react-hooks/exhaustive-deps -- A resize re-renders this without changing any prop, and the bail-out below ends the chain.
+	useLayoutEffect( () => {
+		const chartBounds = chartRef.current?.getBoundingClientRect();
+		const svgBounds = svgRef.current?.getBoundingClientRect();
+		if ( ! showKeyboardTooltip || ! chartBounds || ! svgBounds ) {
+			return;
+		}
+		const top = svgBounds.top - chartBounds.top;
+		const left = svgBounds.left - chartBounds.left;
+		setSvgOffset( current =>
+			current.top === top && current.left === left ? current : { top, left }
+		);
+	} );
+
+	return (
+		<>
+			<PieSelectionAnnouncement data={ withTooltips ? undefined : selectedData } />
+			{ showKeyboardTooltip && (
+				<PieTooltip
+					top={ svgOffset.top + keyboardTooltipAnchor.top }
+					left={ svgOffset.left + keyboardTooltipAnchor.left }
+					selectedIndex={ selectedIndex }
+					tooltipRef={ tooltipRef }
+				>
+					{ renderTooltip( { tooltipData: selectedData } ) }
+				</PieTooltip>
+			) }
+			{ withTooltips && ! selectedData && pointerTooltip?.data && (
+				<PieTooltip top={ pointerTooltip.top } left={ pointerTooltip.left }>
+					{ renderTooltip( { tooltipData: pointerTooltip.data } ) }
+				</PieTooltip>
+			) }
+		</>
+	);
+};

package/src/charts/private/pie-keyboard-navigation/pie-tooltip.tsx

@@ -0,0 +1,49 @@
+import {
+	BoundedTooltip,
+	TOOLTIP_Z_INDEX,
+} from '../../../components/tooltip/private/bounded-tooltip';
+import { useStandaloneScopeClass } from '../../../providers/chart-scope';
+import type { CSSProperties, ReactNode } from 'react';
+
+const TOOLTIP_BOX_STYLE: CSSProperties = { zIndex: TOOLTIP_Z_INDEX };
+
+interface PieTooltipProps {
+	top: number;
+	left: number;
+	/** Set while a keyboard selection drives the tooltip, which then takes focus. */
+	selectedIndex?: number;
+	tooltipRef?: ( element: HTMLDivElement | null ) => void;
+	children: ReactNode;
+}
+
+export const PieTooltip = ( {
+	top,
+	left,
+	selectedIndex,
+	tooltipRef,
+	children,
+}: PieTooltipProps ) => {
+	const standaloneScopeClass = useStandaloneScopeClass();
+
+	return (
+		<BoundedTooltip top={ top } left={ left } style={ TOOLTIP_BOX_STYLE }>
+			{ selectedIndex === undefined ? (
+				<div className={ standaloneScopeClass } role="tooltip">
+					{ children }
+				</div>
+			) : (
+				<div
+					ref={ tooltipRef }
+					tabIndex={ -1 }
+					role="tooltip"
+					aria-atomic="true"
+					className={ standaloneScopeClass }
+					data-testid={ `chart-tooltip-${ selectedIndex }` }
+					key={ `chart-tooltip-${ selectedIndex }` }
+				>
+					{ children }
+				</div>
+			) }
+		</BoundedTooltip>
+	);
+};

package/src/charts/private/pie-keyboard-navigation/selected-segment-ring.tsx

@@ -0,0 +1,47 @@
+import styles from './pie-keyboard-navigation.module.scss';
+
+interface SelectedSegmentRingProps {
+	/** The chart's id, which keeps the clip path unique on a page with several charts. */
+	chartId: string;
+	/** The selected segment's path, from the same arc generator that draws the segment. */
+	d: string;
+}
+
+/**
+ * Encodes `value` for an SVG id, losslessly so distinct chart ids never share a clip path.
+ *
+ * @param value - Any string.
+ * @return `value` with each character outside `[A-Za-z0-9-]` written as `_<hex code point>_`.
+ */
+export const toSvgId = ( value: string ) =>
+	Array.from( value, character =>
+		/[A-Za-z0-9-]/.test( character )
+			? character
+			: `_${ character.codePointAt( 0 )?.toString( 16 ) }_`
+	).join( '' );
+
+/**
+ * Marks the selected segment with a two-tone ring drawn inside its edge, so the SVG edge cannot cut it off.
+ *
+ * @param {SelectedSegmentRingProps} props - Component props
+ * @return {JSX.Element} The ring
+ */
+export const SelectedSegmentRing = ( { chartId, d }: SelectedSegmentRingProps ) => {
+	const clipId = `pie-selected-ring-clip-${ toSvgId( chartId ) }`;
+	const clipPath = `url(#${ clipId })`;
+
+	return (
+		<g pointerEvents="none" aria-hidden="true">
+			<clipPath id={ clipId }>
+				<path d={ d } />
+			</clipPath>
+			<path d={ d } clipPath={ clipPath } className={ styles[ 'selected-ring__contrast' ] } />
+			<path
+				d={ d }
+				clipPath={ clipPath }
+				className={ styles[ 'selected-ring__focus' ] }
+				data-testid="pie-selected-ring"
+			/>
+		</g>
+	);
+};