@automattic/jetpack-components 3.1.2 → 3.2.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ### This is a list detailing changes for the Jetpack RNA Components package releases.
 
+## [3.2.0] - 2026-09-23
+### Added
+- IconTooltip: Add a `trigger` prop that renders a text trigger in place of the icon, and a `closeOnClickOutside` prop to keep a tooltip open while the visitor works elsewhere on the page. [#52704]
+
+### Fixed
+- Tooltips: Open info tooltips with Enter or Space, close them with Escape, and keep hover tooltips from taking focus. [#52661]
+- Tooltips: Resume tab order from the tooltip's trigger when focus leaves it. [#52661]
+
 ## [3.1.2] - 2026-09-23
 ### Fixed
 - DiffViewer: Fix some inefficient regular expressions. [#52582]
@@ -1955,6 +1963,7 @@
 ### Changed
 - Update node version requirement to 14.16.1
 
+[3.2.0]: https://github.com/Automattic/jetpack-components/compare/3.1.2...3.2.0
 [3.1.2]: https://github.com/Automattic/jetpack-components/compare/3.1.1...3.1.2
 [3.1.1]: https://github.com/Automattic/jetpack-components/compare/3.1.0...3.1.1
 [3.1.0]: https://github.com/Automattic/jetpack-components/compare/3.0.3...3.1.0

package/build/components/icon-tooltip/index.js

@@ -1,8 +1,9 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Popover } from '@wordpress/components';
+import { focus } from '@wordpress/dom';
 import { Icon, info } from '@wordpress/icons';
 import clsx from 'clsx';
-import { useCallback, useState } from 'react';
+import { useCallback, useEffect, useRef, useState, } from 'react';
 import Button from '../button/index.js';
 import './style.scss';
 const placementsToPositions = (placement) => {
@@ -22,15 +23,90 @@ const placementsToPositions = (placement) => {
  * @param {IconTooltipProps} props - Props
  * @return {ReactElement} - JSX element
  */
-const IconTooltip = ({ className = '', popoverClassName, iconClassName = '', placement = 'bottom-end', animate = true, iconCode = info, iconSize = 18, offset = 10, title, children, popoverAnchorStyle = 'icon', forceShow = false, hoverShow = false, wide = false, inline = true, shift = false, }) => {
+const IconTooltip = ({ className = '', popoverClassName, iconClassName = '', placement = 'bottom-end', animate = true, iconCode = info, iconSize = 18, offset = 10, title, children, popoverAnchorStyle = 'icon', trigger, onTriggerClick, closeOnClickOutside = true, forceShow = false, hoverShow = false, wide = false, inline = true, shift = false, }) => {
     const POPOVER_HELPER_WIDTH = 124;
     const [isVisible, setIsVisible] = useState(false);
     const [hoverTimeout, setHoverTimeout] = useState(null);
+    const wrapperRef = useRef(null);
+    const popoverRef = useRef(null);
+    const triggerRef = useRef(null);
+    const hasTextTrigger = trigger !== undefined;
+    // Where focus should land after Tab leaves the tooltip. The effect below applies it, rather
+    // than the handler, because Popover puts focus back on the trigger as it unmounts.
+    const focusAfterClose = useRef(null);
+    // Opening on hover must not pull focus off whatever the visitor is using.
+    const openedByHover = useRef(false);
     const hideTooltip = useCallback(() => setIsVisible(false), [setIsVisible]);
     const toggleTooltip = useCallback(e => {
         e.preventDefault();
+        onTriggerClick?.();
+        openedByHover.current = false;
         setIsVisible(!isVisible);
-    }, [isVisible, setIsVisible]);
+    }, [isVisible, setIsVisible, onTriggerClick]);
+    // Focus can stay on a text trigger while its tooltip is open, so it handles the dialog keys too.
+    const handleTriggerKeyDown = useCallback((event) => {
+        // A link only activates on Enter; a button also activates on Space.
+        if (event.key === ' ') {
+            if (!event.repeat) {
+                toggleTooltip(event);
+            }
+            return;
+        }
+        if (!isVisible) {
+            return;
+        }
+        if (event.key === 'Escape') {
+            event.preventDefault();
+            hideTooltip();
+        }
+        else if (event.key === 'Tab') {
+            // Step into the popover even when it is portaled away from the trigger.
+            const first = event.shiftKey ? null : focus.tabbable.find(popoverRef.current)[0];
+            if (first) {
+                event.preventDefault();
+                first.focus();
+            }
+            else {
+                hideTooltip();
+            }
+        }
+    }, [isVisible, hideTooltip, toggleTooltip]);
+    const isAnchorWrapper = popoverAnchorStyle === 'wrapper';
+    const isForcedToShow = isAnchorWrapper && forceShow;
+    const handlePopoverKeyDown = useCallback((event) => {
+        const wrapper = wrapperRef.current;
+        const popover = popoverRef.current;
+        if (event.key !== 'Tab' || !wrapper || !popover) {
+            return;
+        }
+        const tabbables = focus.tabbable.find(popover);
+        const boundary = event.shiftKey ? tabbables[0] : tabbables[tabbables.length - 1];
+        const leaving = !tabbables.length ||
+            event.target === boundary ||
+            (event.shiftKey && event.target === popover);
+        if (!leaving) {
+            return;
+        }
+        if (event.shiftKey && triggerRef.current) {
+            event.preventDefault();
+            triggerRef.current.focus();
+            return;
+        }
+        // A popover rendered in a portal sits at the end of the document, so Tab out of it has
+        // to resume from the trigger's place in the page instead of the popover's.
+        const step = event.shiftKey ? focus.tabbable.findPrevious : focus.tabbable.findNext;
+        let destination = step(wrapper);
+        while (destination &&
+            (wrapper.contains(destination) || popover.contains(destination))) {
+            destination = step(destination);
+        }
+        event.preventDefault();
+        focusAfterClose.current = destination ?? null;
+        hideTooltip();
+    }, [hideTooltip]);
+    const focusOnOpen = isForcedToShow || (hasTextTrigger && !openedByHover.current)
+        ? 'firstElement'
+        : !openedByHover.current;
     const args = {
         // To be compatible with deprecating prop `position`.
         position: placementsToPositions(placement),
@@ -40,24 +116,65 @@ const IconTooltip = ({ className = '', popoverClassName, iconClassName = '', pla
         resize: false,
         flip: false,
         offset, // The distance (in px) between the anchor and the popover.
-        focusOnMount: 'firstElement',
-        onClose: hideTooltip,
+        // Focusing the popover itself puts Escape in reach even with nothing tabbable inside. A text
+        // trigger or caller-controlled popover moves focus to its first link, if it has one.
+        focusOnMount: focusOnOpen,
+        // Tab moves through the popover in document order rather than cycling inside it, and
+        // handlePopoverKeyDown decides where it lands on the way out.
+        constrainTabbing: false,
+        onKeyDownCapture: handlePopoverKeyDown,
+        ref: popoverRef,
+        onClose: () => {
+            const popover = popoverRef.current;
+            if (hasTextTrigger && popover?.contains(popover.ownerDocument.activeElement)) {
+                focusAfterClose.current = triggerRef.current;
+            }
+            hideTooltip();
+        },
+        onFocusOutside: (event) => {
+            // A pointer press on our own trigger dismisses through that trigger instead.
+            if (closeOnClickOutside && !wrapperRef.current?.contains(event.relatedTarget)) {
+                hideTooltip();
+            }
+        },
         className: clsx('icon-tooltip-container', popoverClassName),
         inline,
         shift,
     };
-    const isAnchorWrapper = popoverAnchorStyle === 'wrapper';
-    const wrapperClassNames = clsx('icon-tooltip-wrapper', className);
+    const wrapperClassNames = clsx('icon-tooltip-wrapper', { 'has-text-trigger': hasTextTrigger }, className);
     const iconShiftBySize = {
         left: isAnchorWrapper ? 0 : -(POPOVER_HELPER_WIDTH / 2 - iconSize / 2) + 'px',
     };
-    const isForcedToShow = isAnchorWrapper && forceShow;
+    // Focus may never enter the popover, so outside presses are watched directly.
+    useEffect(() => {
+        if (!isVisible || isForcedToShow || !closeOnClickOutside) {
+            return;
+        }
+        const doc = wrapperRef.current?.ownerDocument;
+        const handlePointerDown = (event) => {
+            const target = event.target;
+            if (!wrapperRef.current?.contains(target) && !popoverRef.current?.contains(target)) {
+                hideTooltip();
+            }
+        };
+        doc?.addEventListener('pointerdown', handlePointerDown);
+        return () => doc?.removeEventListener('pointerdown', handlePointerDown);
+    }, [isVisible, isForcedToShow, closeOnClickOutside, hideTooltip]);
+    useEffect(() => {
+        if (isForcedToShow || isVisible) {
+            return;
+        }
+        const destination = focusAfterClose.current;
+        focusAfterClose.current = null;
+        destination?.focus();
+    }, [isForcedToShow, isVisible]);
     const handleMouseEnter = useCallback(() => {
         if (hoverShow) {
             if (hoverTimeout) {
                 clearTimeout(hoverTimeout);
                 setHoverTimeout(null);
             }
+            openedByHover.current = true;
             setIsVisible(true);
         }
     }, [hoverShow, hoverTimeout]);
@@ -70,6 +187,7 @@ const IconTooltip = ({ className = '', popoverClassName, iconClassName = '', pla
             setHoverTimeout(id);
         }
     }, [hoverShow]);
-    return (_jsxs("div", { className: wrapperClassNames, "data-testid": "icon-tooltip_wrapper", onMouseEnter: handleMouseEnter, onMouseLeave: handleMouseLeave, children: [!isAnchorWrapper && (_jsx(Button, { variant: "link", onMouseDown: toggleTooltip, children: _jsx(Icon, { className: iconClassName, icon: iconCode, size: iconSize }) })), _jsx("div", { className: clsx('icon-tooltip-helper', { 'is-wide': wide }), style: iconShiftBySize, children: (isForcedToShow || isVisible) && (_jsx(Popover, { ...args, children: _jsxs("div", { children: [title && _jsx("div", { className: "icon-tooltip-title", children: title }), _jsx("div", { className: "icon-tooltip-content", children: children })] }) })) })] }));
+    const helper = (_jsx("div", { className: clsx('icon-tooltip-helper', { 'is-wide': wide }), style: iconShiftBySize, children: (isForcedToShow || isVisible) && (_jsx(Popover, { ...args, children: _jsxs("div", { children: [title && _jsx("div", { className: "icon-tooltip-title", children: title }), _jsx("div", { className: "icon-tooltip-content", children: children })] }) })) }));
+    return (_jsxs("div", { ref: wrapperRef, className: wrapperClassNames, "data-testid": "icon-tooltip_wrapper", onMouseEnter: handleMouseEnter, onMouseLeave: handleMouseLeave, children: [hasTextTrigger && (_jsxs(_Fragment, { children: [_jsx("a", { ref: triggerRef, href: "#", role: "button", className: "icon-tooltip-trigger", "aria-expanded": isVisible, onClick: toggleTooltip, onKeyDown: handleTriggerKeyDown, children: trigger }), _jsx("span", { className: "icon-tooltip-anchor", children: _jsx("span", { children: helper }) })] })), !hasTextTrigger && !isAnchorWrapper && (_jsx(Button, { variant: "link", "aria-expanded": isVisible, onClick: toggleTooltip, children: _jsx(Icon, { className: iconClassName, icon: iconCode, size: iconSize }) })), !hasTextTrigger && helper] }));
 };
 export default IconTooltip;

package/build/components/icon-tooltip/style.scss

@@ -79,9 +79,41 @@ $arrow-color: var(--jp-gray);
 	}
 }
 
+// A text trigger flows with the sentence around it.
+.icon-tooltip-wrapper.has-text-trigger {
+	display: inline;
+	color: inherit;
+}
+
+// The popover anchors at the trigger's baseline and paints under it.
+.icon-tooltip-trigger {
+	position: relative;
+	z-index: 10;
+}
+
+.icon-tooltip-anchor {
+	position: absolute;
+	inset-block-start: 0;
+	inset-inline-start: 0;
+	z-index: 9;
+
+	> span {
+		display: inline-block;
+		position: relative;
+		color: var(--jp-black);
+	}
+}
+
 .icon-tooltip-container {
 	// Recover events
 	pointer-events: all;
+	// Takes focus on open, but its box is wider than the visible content,
+	// so the ring goes on the content instead.
+	outline: none;
+
+	&:focus-visible .components-popover__content {
+		outline: var(--wp-admin-border-width-focus, 2px) solid var(--wp-admin-theme-color, #3858e9);
+	}
 
 	// __content styles here covers both the inline and portal modes
 	.components-popover__content {

package/build/components/icon-tooltip/types.d.ts

@@ -52,7 +52,21 @@ export type IconTooltipProps = {
      */
     popoverAnchorStyle?: 'icon' | 'wrapper';
     /**
-     * Force the Popover to show without an event trigger.
+     * Text to render as the trigger in place of the icon. The component owns the open state.
+     */
+    trigger?: ReactNode;
+    /**
+     * Called on every press of the trigger, e.g. to record analytics.
+     */
+    onTriggerClick?: () => void;
+    /**
+     * Whether a press outside the trigger and popover closes the tooltip. Turn it off for a
+     * reference the visitor keeps open while working elsewhere on the page.
+     */
+    closeOnClickOutside?: boolean;
+    /**
+     * Force the Popover to show without an event trigger. Only for a wrapper-anchored
+     * tooltip with no `trigger`, such as a programmatic tour step.
      */
     forceShow?: boolean;
     /**

package/components/icon-tooltip/index.tsx

@@ -1,7 +1,17 @@
 import { Popover } from '@wordpress/components';
+import { focus } from '@wordpress/dom';
 import { Icon, info } from '@wordpress/icons';
 import clsx from 'clsx';
-import { useCallback, useState, ReactElement, FC } from 'react';
+import {
+	useCallback,
+	useEffect,
+	useRef,
+	useState,
+	ReactElement,
+	FC,
+	FocusEvent,
+	KeyboardEvent,
+} from 'react';
 import Button from '../button/index.tsx';
 import { IconTooltipProps, Placement, Position } from './types.ts';
 
@@ -38,6 +48,9 @@ const IconTooltip: FC< IconTooltipProps > = ( {
 	title,
 	children,
 	popoverAnchorStyle = 'icon',
+	trigger,
+	onTriggerClick,
+	closeOnClickOutside = true,
 	forceShow = false,
 	hoverShow = false,
 	wide = false,
@@ -47,15 +60,101 @@ const IconTooltip: FC< IconTooltipProps > = ( {
 	const POPOVER_HELPER_WIDTH = 124;
 	const [ isVisible, setIsVisible ] = useState( false );
 	const [ hoverTimeout, setHoverTimeout ] = useState( null );
+	const wrapperRef = useRef< HTMLDivElement >( null );
+	const popoverRef = useRef< HTMLDivElement >( null );
+	const triggerRef = useRef< HTMLAnchorElement >( null );
+	const hasTextTrigger = trigger !== undefined;
+	// Where focus should land after Tab leaves the tooltip. The effect below applies it, rather
+	// than the handler, because Popover puts focus back on the trigger as it unmounts.
+	const focusAfterClose = useRef< HTMLElement | null >( null );
+	// Opening on hover must not pull focus off whatever the visitor is using.
+	const openedByHover = useRef( false );
 	const hideTooltip = useCallback( () => setIsVisible( false ), [ setIsVisible ] );
 	const toggleTooltip = useCallback(
 		e => {
 			e.preventDefault();
+			onTriggerClick?.();
+			openedByHover.current = false;
 			setIsVisible( ! isVisible );
 		},
-		[ isVisible, setIsVisible ]
+		[ isVisible, setIsVisible, onTriggerClick ]
 	);
 
+	// Focus can stay on a text trigger while its tooltip is open, so it handles the dialog keys too.
+	const handleTriggerKeyDown = useCallback(
+		( event: KeyboardEvent< HTMLAnchorElement > ) => {
+			// A link only activates on Enter; a button also activates on Space.
+			if ( event.key === ' ' ) {
+				if ( ! event.repeat ) {
+					toggleTooltip( event );
+				}
+				return;
+			}
+			if ( ! isVisible ) {
+				return;
+			}
+			if ( event.key === 'Escape' ) {
+				event.preventDefault();
+				hideTooltip();
+			} else if ( event.key === 'Tab' ) {
+				// Step into the popover even when it is portaled away from the trigger.
+				const first = event.shiftKey ? null : focus.tabbable.find( popoverRef.current )[ 0 ];
+				if ( first ) {
+					event.preventDefault();
+					first.focus();
+				} else {
+					hideTooltip();
+				}
+			}
+		},
+		[ isVisible, hideTooltip, toggleTooltip ]
+	);
+
+	const isAnchorWrapper = popoverAnchorStyle === 'wrapper';
+	const isForcedToShow = isAnchorWrapper && forceShow;
+
+	const handlePopoverKeyDown = useCallback(
+		( event: KeyboardEvent< HTMLDivElement > ) => {
+			const wrapper = wrapperRef.current;
+			const popover = popoverRef.current;
+			if ( event.key !== 'Tab' || ! wrapper || ! popover ) {
+				return;
+			}
+			const tabbables = focus.tabbable.find( popover );
+			const boundary = event.shiftKey ? tabbables[ 0 ] : tabbables[ tabbables.length - 1 ];
+			const leaving =
+				! tabbables.length ||
+				event.target === boundary ||
+				( event.shiftKey && event.target === popover );
+			if ( ! leaving ) {
+				return;
+			}
+			if ( event.shiftKey && triggerRef.current ) {
+				event.preventDefault();
+				triggerRef.current.focus();
+				return;
+			}
+			// A popover rendered in a portal sits at the end of the document, so Tab out of it has
+			// to resume from the trigger's place in the page instead of the popover's.
+			const step = event.shiftKey ? focus.tabbable.findPrevious : focus.tabbable.findNext;
+			let destination = step( wrapper );
+			while (
+				destination &&
+				( wrapper.contains( destination ) || popover.contains( destination ) )
+			) {
+				destination = step( destination );
+			}
+			event.preventDefault();
+			focusAfterClose.current = destination ?? null;
+			hideTooltip();
+		},
+		[ hideTooltip ]
+	);
+
+	const focusOnOpen =
+		isForcedToShow || ( hasTextTrigger && ! openedByHover.current )
+			? 'firstElement'
+			: ! openedByHover.current;
 	const args = {
 		// To be compatible with deprecating prop `position`.
 		position: placementsToPositions( placement ),
@@ -65,21 +164,65 @@ const IconTooltip: FC< IconTooltipProps > = ( {
 		resize: false,
 		flip: false,
 		offset, // The distance (in px) between the anchor and the popover.
-		focusOnMount: 'firstElement',
-		onClose: hideTooltip,
+		// Focusing the popover itself puts Escape in reach even with nothing tabbable inside. A text
+		// trigger or caller-controlled popover moves focus to its first link, if it has one.
+		focusOnMount: focusOnOpen,
+		// Tab moves through the popover in document order rather than cycling inside it, and
+		// handlePopoverKeyDown decides where it lands on the way out.
+		constrainTabbing: false,
+		onKeyDownCapture: handlePopoverKeyDown,
+		ref: popoverRef,
+		onClose: () => {
+			const popover = popoverRef.current;
+			if ( hasTextTrigger && popover?.contains( popover.ownerDocument.activeElement ) ) {
+				focusAfterClose.current = triggerRef.current;
+			}
+			hideTooltip();
+		},
+		onFocusOutside: ( event: FocusEvent ) => {
+			// A pointer press on our own trigger dismisses through that trigger instead.
+			if ( closeOnClickOutside && ! wrapperRef.current?.contains( event.relatedTarget as Node ) ) {
+				hideTooltip();
+			}
+		},
 		className: clsx( 'icon-tooltip-container', popoverClassName ),
 		inline,
 		shift,
 	} satisfies Omit< React.ComponentProps< typeof Popover >, 'children' >;
 
-	const isAnchorWrapper = popoverAnchorStyle === 'wrapper';
-
-	const wrapperClassNames = clsx( 'icon-tooltip-wrapper', className );
+	const wrapperClassNames = clsx(
+		'icon-tooltip-wrapper',
+		{ 'has-text-trigger': hasTextTrigger },
+		className
+	);
 	const iconShiftBySize = {
 		left: isAnchorWrapper ? 0 : -( POPOVER_HELPER_WIDTH / 2 - iconSize / 2 ) + 'px',
 	};
 
-	const isForcedToShow = isAnchorWrapper && forceShow;
+	// Focus may never enter the popover, so outside presses are watched directly.
+	useEffect( () => {
+		if ( ! isVisible || isForcedToShow || ! closeOnClickOutside ) {
+			return;
+		}
+		const doc = wrapperRef.current?.ownerDocument;
+		const handlePointerDown = ( event: PointerEvent ) => {
+			const target = event.target as Node;
+			if ( ! wrapperRef.current?.contains( target ) && ! popoverRef.current?.contains( target ) ) {
+				hideTooltip();
+			}
+		};
+		doc?.addEventListener( 'pointerdown', handlePointerDown );
+		return () => doc?.removeEventListener( 'pointerdown', handlePointerDown );
+	}, [ isVisible, isForcedToShow, closeOnClickOutside, hideTooltip ] );
+
+	useEffect( () => {
+		if ( isForcedToShow || isVisible ) {
+			return;
+		}
+		const destination = focusAfterClose.current;
+		focusAfterClose.current = null;
+		destination?.focus();
+	}, [ isForcedToShow, isVisible ] );
 
 	const handleMouseEnter = useCallback( () => {
 		if ( hoverShow ) {
@@ -87,6 +230,7 @@ const IconTooltip: FC< IconTooltipProps > = ( {
 				clearTimeout( hoverTimeout );
 				setHoverTimeout( null );
 			}
+			openedByHover.current = true;
 			setIsVisible( true );
 		}
 	}, [ hoverShow, hoverTimeout ] );
@@ -101,31 +245,52 @@ const IconTooltip: FC< IconTooltipProps > = ( {
 		}
 	}, [ hoverShow ] );
 
+	const helper = (
+		<div className={ clsx( 'icon-tooltip-helper', { 'is-wide': wide } ) } style={ iconShiftBySize }>
+			{ ( isForcedToShow || isVisible ) && (
+				<Popover { ...args }>
+					<div>
+						{ title && <div className="icon-tooltip-title">{ title }</div> }
+						<div className="icon-tooltip-content">{ children }</div>
+					</div>
+				</Popover>
+			) }
+		</div>
+	);
+
 	return (
 		<div
+			ref={ wrapperRef }
 			className={ wrapperClassNames }
 			data-testid="icon-tooltip_wrapper"
 			onMouseEnter={ handleMouseEnter }
 			onMouseLeave={ handleMouseLeave }
 		>
-			{ ! isAnchorWrapper && (
-				<Button variant="link" onMouseDown={ toggleTooltip }>
+			{ hasTextTrigger && (
+				<>
+					{ /* A link, not a button, so it keeps the host page's link styling. */ }
+					<a
+						ref={ triggerRef }
+						href="#"
+						role="button"
+						className="icon-tooltip-trigger"
+						aria-expanded={ isVisible }
+						onClick={ toggleTooltip }
+						onKeyDown={ handleTriggerKeyDown }
+					>
+						{ trigger }
+					</a>
+					<span className="icon-tooltip-anchor">
+						<span>{ helper }</span>
+					</span>
+				</>
+			) }
+			{ ! hasTextTrigger && ! isAnchorWrapper && (
+				<Button variant="link" aria-expanded={ isVisible } onClick={ toggleTooltip }>
 					<Icon className={ iconClassName } icon={ iconCode } size={ iconSize } />
 				</Button>
 			) }
-			<div
-				className={ clsx( 'icon-tooltip-helper', { 'is-wide': wide } ) }
-				style={ iconShiftBySize }
-			>
-				{ ( isForcedToShow || isVisible ) && (
-					<Popover { ...args }>
-						<div>
-							{ title && <div className="icon-tooltip-title">{ title }</div> }
-							<div className="icon-tooltip-content">{ children }</div>
-						</div>
-					</Popover>
-				) }
-			</div>
+			{ ! hasTextTrigger && helper }
 		</div>
 	);
 };

package/components/icon-tooltip/style.scss

@@ -79,9 +79,41 @@ $arrow-color: var(--jp-gray);
 	}
 }
 
+// A text trigger flows with the sentence around it.
+.icon-tooltip-wrapper.has-text-trigger {
+	display: inline;
+	color: inherit;
+}
+
+// The popover anchors at the trigger's baseline and paints under it.
+.icon-tooltip-trigger {
+	position: relative;
+	z-index: 10;
+}
+
+.icon-tooltip-anchor {
+	position: absolute;
+	inset-block-start: 0;
+	inset-inline-start: 0;
+	z-index: 9;
+
+	> span {
+		display: inline-block;
+		position: relative;
+		color: var(--jp-black);
+	}
+}
+
 .icon-tooltip-container {
 	// Recover events
 	pointer-events: all;
+	// Takes focus on open, but its box is wider than the visible content,
+	// so the ring goes on the content instead.
+	outline: none;
+
+	&:focus-visible .components-popover__content {
+		outline: var(--wp-admin-border-width-focus, 2px) solid var(--wp-admin-theme-color, #3858e9);
+	}
 
 	// __content styles here covers both the inline and portal modes
 	.components-popover__content {

package/components/icon-tooltip/types.ts

@@ -67,7 +67,24 @@ export type IconTooltipProps = {
 	popoverAnchorStyle?: 'icon' | 'wrapper';
 
 	/**
-	 * Force the Popover to show without an event trigger.
+	 * Text to render as the trigger in place of the icon. The component owns the open state.
+	 */
+	trigger?: ReactNode;
+
+	/**
+	 * Called on every press of the trigger, e.g. to record analytics.
+	 */
+	onTriggerClick?: () => void;
+
+	/**
+	 * Whether a press outside the trigger and popover closes the tooltip. Turn it off for a
+	 * reference the visitor keeps open while working elsewhere on the page.
+	 */
+	closeOnClickOutside?: boolean;
+
+	/**
+	 * Force the Popover to show without an event trigger. Only for a wrapper-anchored
+	 * tooltip with no `trigger`, such as a programmatic tour step.
 	 */
 	forceShow?: boolean;
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@automattic/jetpack-components",
-	"version": "3.1.2",
+	"version": "3.2.0",
 	"description": "Jetpack Components Package",
 	"homepage": "https://github.com/Automattic/jetpack/tree/HEAD/projects/js-packages/components/#readme",
 	"bugs": {
@@ -84,6 +84,7 @@
 		"@wordpress/compose": "8.8.0",
 		"@wordpress/data": "10.55.0",
 		"@wordpress/date": "5.55.0",
+		"@wordpress/dom": "4.55.0",
 		"@wordpress/element": "8.7.0",
 		"@wordpress/i18n": "6.28.0",
 		"@wordpress/icons": "16.0.0",