@automattic/jetpack-components 3.2.0 → 3.3.0

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ### This is a list detailing changes for the Jetpack RNA Components package releases.
 
+## [3.3.0] - 2026-09-28
+### Added
+- Add a JitmSlot component so every dashboard renders the Jetpack in-dashboard message slot the same way, and keeps the message across route changes. [#52641]
+- IconTooltip: Add a `label` prop to give the icon trigger an accessible name. [#52800]
+
+### Changed
+- IconTooltip: Keep focus on the trigger when a tooltip opens, announce its content to screen readers, and show the trigger's focus ring the way other WordPress buttons do. [#52736]
+- Use logical CSS properties so layouts mirror in right-to-left languages. [#52749]
+
+### Deprecated
+- Deprecate GlobalNotices and useGlobalNotices. Use SnackbarNotices from @wordpress/notices instead. [#52193]
+
+### Fixed
+- IconTooltip: Close a tooltip opened on hover when Escape is pressed, without moving focus. [#52799]
+
 ## [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]
@@ -1963,6 +1978,7 @@
 ### Changed
 - Update node version requirement to 14.16.1
 
+[3.3.0]: https://github.com/Automattic/jetpack-components/compare/3.2.0...3.3.0
 [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

package/build/components/decorative-card/style.scss

@@ -29,7 +29,7 @@
 			display: block;
 			position: absolute;
 			top: 24px;
-			left: 24px;
+			inset-inline-start: 24px;
 			width: 38px;
 			height: 8px;
 			background-image: url('data:image/svg+xml,<svg width="38" height="8" viewBox="0 0 38 8" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M1 7C1 7 2.37087 1 6.89831 1C11.4257 1 14.3709 7 18.8983 7C23.4257 7 26.7777 1 31.3051 1C35.912 1 37 7 37 7" stroke="white" stroke-width="1.5" stroke-linejoin="round"/></svg>');
@@ -43,6 +43,9 @@
 	&__icon-container {
 		position: absolute;
 		top: 50%;
+		// Kept physical: translate(-50%) shifts by a fixed direction, not a
+		// logical one, so left must stay paired with it or the box goes
+		// off-center by its own width under RTL without rtlcss.
 		left: 50%;
 		transform: translate(-50%, -50%);
 		width: 80px;

package/build/components/global-notices/global-notices.d.ts

@@ -4,6 +4,10 @@ export type GlobalNoticesProps = {
 /**
  * Renders the global notices.
  *
+ * @deprecated Use `SnackbarNotices` from `@wordpress/notices` instead. Pages
+ * rendered by `@wordpress/boot` already mount one, so mounting this as well
+ * shows every notice twice.
+ *
  * @param {GlobalNoticesProps} props - Component props.
  *
  * @return {import('react').ReactNode} The rendered notices list.

package/build/components/global-notices/global-notices.js

@@ -5,6 +5,10 @@ import { useGlobalNotices } from './use-global-notices.js';
 /**
  * Renders the global notices.
  *
+ * @deprecated Use `SnackbarNotices` from `@wordpress/notices` instead. Pages
+ * rendered by `@wordpress/boot` already mount one, so mounting this as well
+ * shows every notice twice.
+ *
  * @param {GlobalNoticesProps} props - Component props.
  *
  * @return {import('react').ReactNode} The rendered notices list.

package/build/components/global-notices/use-global-notices.d.ts

@@ -4,6 +4,9 @@ export type TGlobalNotices = ReturnType<NoticesStore['getActions']> & ReturnType
 /**
  * The global notices hook.
  *
+ * @deprecated Dispatch to `@wordpress/notices` directly, passing
+ * `{ type: 'snackbar' }` — this hook only defaulted that option.
+ *
  * @return {TGlobalNotices} The global notices selectors and actions.
  */
 export declare function useGlobalNotices(): TGlobalNotices;

package/build/components/global-notices/use-global-notices.js

@@ -3,6 +3,9 @@ import { store as noticesStore } from '@wordpress/notices';
 /**
  * The global notices hook.
  *
+ * @deprecated Dispatch to `@wordpress/notices` directly, passing
+ * `{ type: 'snackbar' }` — this hook only defaulted that option.
+ *
  * @return {TGlobalNotices} The global notices selectors and actions.
  */
 export function useGlobalNotices() {

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

@@ -1,4 +1,5 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { speak } from '@wordpress/a11y';
 import { Popover } from '@wordpress/components';
 import { focus } from '@wordpress/dom';
 import { Icon, info } from '@wordpress/icons';
@@ -23,7 +24,7 @@ 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', trigger, onTriggerClick, closeOnClickOutside = true, forceShow = false, hoverShow = false, wide = false, inline = true, shift = false, }) => {
+const IconTooltip = ({ className = '', popoverClassName, iconClassName = '', placement = 'bottom-end', animate = true, iconCode = info, label, 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);
@@ -43,13 +44,16 @@ const IconTooltip = ({ className = '', popoverClassName, iconClassName = '', pla
         openedByHover.current = false;
         setIsVisible(!isVisible);
     }, [isVisible, setIsVisible, onTriggerClick]);
-    // Focus can stay on a text trigger while its tooltip is open, so it handles the dialog keys too.
+    // Focus can stay on the trigger while its tooltip is open, so it handles the dialog keys too.
     const handleTriggerKeyDown = useCallback((event) => {
+        // A held key repeats activation, so only its first press toggles.
+        if (event.repeat && (event.key === 'Enter' || event.key === ' ')) {
+            event.preventDefault();
+            return;
+        }
         // A link only activates on Enter; a button also activates on Space.
-        if (event.key === ' ') {
-            if (!event.repeat) {
-                toggleTooltip(event);
-            }
+        if (hasTextTrigger && event.key === ' ') {
+            toggleTooltip(event);
             return;
         }
         if (!isVisible) {
@@ -70,7 +74,7 @@ const IconTooltip = ({ className = '', popoverClassName, iconClassName = '', pla
                 hideTooltip();
             }
         }
-    }, [isVisible, hideTooltip, toggleTooltip]);
+    }, [hasTextTrigger, isVisible, hideTooltip, toggleTooltip]);
     const isAnchorWrapper = popoverAnchorStyle === 'wrapper';
     const isForcedToShow = isAnchorWrapper && forceShow;
     const handlePopoverKeyDown = useCallback((event) => {
@@ -104,9 +108,6 @@ const IconTooltip = ({ className = '', popoverClassName, iconClassName = '', pla
         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),
@@ -116,9 +117,9 @@ const IconTooltip = ({ className = '', popoverClassName, iconClassName = '', pla
         resize: false,
         flip: false,
         offset, // The distance (in px) between the anchor and the popover.
-        // 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,
+        // Focus stays on the trigger, which handles the dialog keys; a caller-controlled popover
+        // has no trigger, so it focuses its first button instead.
+        focusOnMount: isForcedToShow ? 'firstElement' : false,
         // 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,
@@ -126,7 +127,7 @@ const IconTooltip = ({ className = '', popoverClassName, iconClassName = '', pla
         ref: popoverRef,
         onClose: () => {
             const popover = popoverRef.current;
-            if (hasTextTrigger && popover?.contains(popover.ownerDocument.activeElement)) {
+            if (popover?.contains(popover.ownerDocument.activeElement)) {
                 focusAfterClose.current = triggerRef.current;
             }
             hideTooltip();
@@ -160,6 +161,20 @@ const IconTooltip = ({ className = '', popoverClassName, iconClassName = '', pla
         doc?.addEventListener('pointerdown', handlePointerDown);
         return () => doc?.removeEventListener('pointerdown', handlePointerDown);
     }, [isVisible, isForcedToShow, closeOnClickOutside, hideTooltip]);
+    // Hover leaves focus elsewhere, so Escape is watched directly to keep the content dismissible.
+    useEffect(() => {
+        if (!isVisible || !openedByHover.current) {
+            return;
+        }
+        const doc = wrapperRef.current?.ownerDocument;
+        const handleKeyDown = (event) => {
+            if (event.key === 'Escape') {
+                hideTooltip();
+            }
+        };
+        doc?.addEventListener('keydown', handleKeyDown);
+        return () => doc?.removeEventListener('keydown', handleKeyDown);
+    }, [isVisible, hideTooltip]);
     useEffect(() => {
         if (isForcedToShow || isVisible) {
             return;
@@ -168,6 +183,13 @@ const IconTooltip = ({ className = '', popoverClassName, iconClassName = '', pla
         focusAfterClose.current = null;
         destination?.focus();
     }, [isForcedToShow, isVisible]);
+    // Focus stays on the trigger, so a screen reader hears the popover through an announcement.
+    useEffect(() => {
+        const popover = popoverRef.current;
+        if (isVisible && !openedByHover.current && popover) {
+            speak(popover.innerText ?? popover.textContent, 'polite');
+        }
+    }, [isVisible]);
     const handleMouseEnter = useCallback(() => {
         if (hoverShow) {
             if (hoverTimeout) {
@@ -188,6 +210,6 @@ const IconTooltip = ({ className = '', popoverClassName, iconClassName = '', pla
         }
     }, [hoverShow]);
     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] }));
+    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, { ref: triggerRef, variant: "link", "aria-label": label, "aria-expanded": isVisible, onClick: toggleTooltip, onKeyDown: handleTriggerKeyDown, children: _jsx(Icon, { className: iconClassName, icon: iconCode, size: iconSize }) })), !hasTextTrigger && helper] }));
 };
 export default IconTooltip;

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

@@ -107,14 +107,6 @@ $arrow-color: var(--jp-gray);
 .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 {
 		padding: 24px;

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

@@ -31,6 +31,10 @@ export type IconTooltipProps = {
      * The icon to display. Accepts icon components from `@wordpress/icons`.
      */
     iconCode?: ComponentProps<typeof Icon>['icon'];
+    /**
+     * The accessible name of the icon button. Ignored when `trigger` is set, since its text names it.
+     */
+    label?: string;
     /**
      * The title of Popover.
      */

package/build/components/jitm-slot/index.d.ts

@@ -0,0 +1,15 @@
+import './style.scss';
+import type { JitmSlotProps } from './types.ts';
+import type { FC } from 'react';
+/**
+ * Hosts the element the JITM script re-parents its card into.
+ *
+ * The JITM script places its card once per page load, so the element outlives any
+ * one slot: an unmounted slot parks it, hidden, and the next slot takes it back.
+ * `className` is for width and alignment; `style.scss` owns spacing.
+ *
+ * @param {JitmSlotProps} props - Component props.
+ * @return {JSX.Element} The slot.
+ */
+declare const JitmSlot: FC<JitmSlotProps>;
+export default JitmSlot;

package/build/components/jitm-slot/index.js

@@ -0,0 +1,52 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import clsx from 'clsx';
+import { useLayoutEffect, useRef } from 'react';
+import './style.scss';
+const NOTICES_ID = 'jp-admin-notices';
+/**
+ * Returns the page's one `#jp-admin-notices`, creating it on first use.
+ *
+ * Found through the DOM, not a module variable: each wp-build route bundles its own copy
+ * of this module.
+ *
+ * @return {HTMLElement} The element.
+ */
+const getNotices = () => {
+    let element = document.getElementById(NOTICES_ID);
+    if (!element) {
+        element = document.createElement('div');
+        element.id = NOTICES_ID;
+    }
+    return element;
+};
+/**
+ * Hosts the element the JITM script re-parents its card into.
+ *
+ * The JITM script places its card once per page load, so the element outlives any
+ * one slot: an unmounted slot parks it, hidden, and the next slot takes it back.
+ * `className` is for width and alignment; `style.scss` owns spacing.
+ *
+ * @param {JitmSlotProps} props - Component props.
+ * @return {JSX.Element} The slot.
+ */
+const JitmSlot = ({ className, inset }) => {
+    const ref = useRef(null);
+    useLayoutEffect(() => {
+        const host = ref.current;
+        if (!host) {
+            return;
+        }
+        const element = getNotices();
+        element.hidden = false;
+        host.appendChild(element);
+        return () => {
+            // A slot that mounted before this one unmounted may already hold it.
+            if (element.parentNode === host) {
+                element.hidden = true;
+                document.body.appendChild(element);
+            }
+        };
+    }, []);
+    return (_jsx("div", { ref: ref, className: clsx('jp-jitm-slot', { 'jp-jitm-slot--inset': inset }, className), "data-testid": "jp-jitm-slot" }));
+};
+export default JitmSlot;

package/build/components/jitm-slot/style.scss

@@ -0,0 +1,16 @@
+// The slot is always rendered and usually empty, so it takes no space
+// of its own; spacing sits on the card so a dismissed one leaves no gap.
+.jp-jitm-slot {
+	margin: 0;
+	padding: 0;
+
+	// `jitm-card` comes from packages/jitm/src/js/jetpack-jitm.js.
+	.jitm-card {
+		margin: var(--wpds-dimension-gap-xl) 0;
+	}
+}
+
+// Same specificity as the rule above, so it has to come after it.
+.jp-jitm-slot--inset .jitm-card {
+	margin-inline: var(--wpds-dimension-padding-2xl);
+}

package/build/components/jitm-slot/types.d.ts

@@ -0,0 +1,10 @@
+export type JitmSlotProps = {
+    /**
+     * Layout the dashboard owns: width, column span, centering. Not spacing.
+     */
+    className?: string;
+    /**
+     * The slot sits outside the page's padded container, so the card takes the page gutter.
+     */
+    inset?: boolean;
+};

package/build/components/jitm-slot/types.js

@@ -0,0 +1 @@
+export {};

package/build/components/text/style.module.scss

@@ -89,9 +89,9 @@ $props: (
 
 $sides: (
 	"top": "t",
-	"right": "r",
+	"inline-end": "r",
 	"bottom": "b",
-	"left": "l",
+	"inline-start": "l",
 );
 
 @each $prop, $p in $props {
@@ -106,8 +106,8 @@ $sides: (
 
 		/* mx, px */
 		.#{$p}x-#{$size} {
-			#{$prop}-left: calc(var(--spacing-base) * #{$size});
-			#{$prop}-right: calc(var(--spacing-base) * #{$size});
+			#{$prop}-inline-start: calc(var(--spacing-base) * #{$size});
+			#{$prop}-inline-end: calc(var(--spacing-base) * #{$size});
 		}
 
 		.#{$p}y-#{$size} {

package/build/components/text/types.d.ts

@@ -7,11 +7,11 @@ export type TextProps = {
     m?: SpacingValue;
     /** margin-top */
     mt?: SpacingValue;
-    /** margin-right */
+    /** margin-inline-end (right in LTR) */
     mr?: SpacingValue;
     /** margin-bottom */
     mb?: SpacingValue;
-    /** margin-left */
+    /** margin-inline-start (left in LTR) */
     ml?: SpacingValue;
     /** margin left and right */
     mx?: SpacingValue;
@@ -21,11 +21,11 @@ export type TextProps = {
     p?: SpacingValue;
     /** padding-top */
     pt?: SpacingValue;
-    /** padding-right */
+    /** padding-inline-end (right in LTR) */
     pr?: SpacingValue;
     /** padding-bottom */
     pb?: SpacingValue;
-    /** padding-left */
+    /** padding-inline-start (left in LTR) */
     pl?: SpacingValue;
     /** padding left and right */
     px?: SpacingValue;

package/build/index.d.ts

@@ -20,6 +20,7 @@ export { default as Col } from './components/layout/col/index.tsx';
 export { default as Testimonials } from './components/testimonials/index.tsx';
 export { default as Container } from './components/layout/container/index.tsx';
 export { default as CopyToClipboard } from './components/copy-to-clipboard/index.tsx';
+export { default as JitmSlot } from './components/jitm-slot/index.tsx';
 export * from './components/icons/index.tsx';
 export { default as ThemeProvider } from './components/theme-provider/index.tsx';
 export { default as Text, H2, H3, Title } from './components/text/index.tsx';

package/build/index.js

@@ -33,6 +33,7 @@ export { default as Col } from './components/layout/col/index.js';
 export { default as Testimonials } from './components/testimonials/index.js';
 export { default as Container } from './components/layout/container/index.js';
 export { default as CopyToClipboard } from './components/copy-to-clipboard/index.js';
+export { default as JitmSlot } from './components/jitm-slot/index.js';
 export * from './components/icons/index.js';
 export { default as ThemeProvider } from './components/theme-provider/index.js';
 export { default as Text, H2, H3, Title } from './components/text/index.js';

package/components/decorative-card/style.scss

@@ -29,7 +29,7 @@
 			display: block;
 			position: absolute;
 			top: 24px;
-			left: 24px;
+			inset-inline-start: 24px;
 			width: 38px;
 			height: 8px;
 			background-image: url('data:image/svg+xml,<svg width="38" height="8" viewBox="0 0 38 8" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M1 7C1 7 2.37087 1 6.89831 1C11.4257 1 14.3709 7 18.8983 7C23.4257 7 26.7777 1 31.3051 1C35.912 1 37 7 37 7" stroke="white" stroke-width="1.5" stroke-linejoin="round"/></svg>');
@@ -43,6 +43,9 @@
 	&__icon-container {
 		position: absolute;
 		top: 50%;
+		// Kept physical: translate(-50%) shifts by a fixed direction, not a
+		// logical one, so left must stay paired with it or the box goes
+		// off-center by its own width under RTL without rtlcss.
 		left: 50%;
 		transform: translate(-50%, -50%);
 		width: 80px;

package/components/global-notices/README.md

@@ -0,0 +1,25 @@
+GlobalNotices
+=========
+
+> **Deprecated.** Use `SnackbarNotices` from `@wordpress/notices` instead, and
+> dispatch to that store directly with `{ type: 'snackbar' }`. Pages rendered by
+> `@wordpress/boot` already mount a `SnackbarNotices`, so mounting this one too
+> shows every notice twice. Retained as a compatibility shim for downstream
+> consumers and will be removed in the next major version.
+
+Renders the snackbar notices held in the `@wordpress/notices` store.
+
+## General Usage:
+
+```js
+import { GlobalNotices } from '@automattic/jetpack-components';
+render() {
+	return (
+		<GlobalNotices />
+	);
+}
+```
+
+## Props
+
+- `maxVisibleNotices`: how many notices to show at once. Defaults to 3.

package/components/global-notices/global-notices.tsx

@@ -9,6 +9,10 @@ export type GlobalNoticesProps = {
 /**
  * Renders the global notices.
  *
+ * @deprecated Use `SnackbarNotices` from `@wordpress/notices` instead. Pages
+ * rendered by `@wordpress/boot` already mount one, so mounting this as well
+ * shows every notice twice.
+ *
  * @param {GlobalNoticesProps} props - Component props.
  *
  * @return {import('react').ReactNode} The rendered notices list.

package/components/global-notices/use-global-notices.ts

@@ -9,6 +9,9 @@ export type TGlobalNotices = ReturnType< NoticesStore[ 'getActions' ] > &
 /**
  * The global notices hook.
  *
+ * @deprecated Dispatch to `@wordpress/notices` directly, passing
+ * `{ type: 'snackbar' }` — this hook only defaulted that option.
+ *
  * @return {TGlobalNotices} The global notices selectors and actions.
  */
 export function useGlobalNotices(): TGlobalNotices {

package/components/icon-tooltip/index.tsx

@@ -1,3 +1,4 @@
+import { speak } from '@wordpress/a11y';
 import { Popover } from '@wordpress/components';
 import { focus } from '@wordpress/dom';
 import { Icon, info } from '@wordpress/icons';
@@ -43,6 +44,7 @@ const IconTooltip: FC< IconTooltipProps > = ( {
 	placement = 'bottom-end',
 	animate = true,
 	iconCode = info,
+	label,
 	iconSize = 18,
 	offset = 10,
 	title,
@@ -62,7 +64,7 @@ const IconTooltip: FC< IconTooltipProps > = ( {
 	const [ hoverTimeout, setHoverTimeout ] = useState( null );
 	const wrapperRef = useRef< HTMLDivElement >( null );
 	const popoverRef = useRef< HTMLDivElement >( null );
-	const triggerRef = useRef< HTMLAnchorElement >( null );
+	const triggerRef = useRef< HTMLElement >( 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.
@@ -80,14 +82,17 @@ const IconTooltip: FC< IconTooltipProps > = ( {
 		[ isVisible, setIsVisible, onTriggerClick ]
 	);
 
-	// Focus can stay on a text trigger while its tooltip is open, so it handles the dialog keys too.
+	// Focus can stay on the trigger while its tooltip is open, so it handles the dialog keys too.
 	const handleTriggerKeyDown = useCallback(
-		( event: KeyboardEvent< HTMLAnchorElement > ) => {
+		( event: KeyboardEvent< HTMLElement > ) => {
+			// A held key repeats activation, so only its first press toggles.
+			if ( event.repeat && ( event.key === 'Enter' || event.key === ' ' ) ) {
+				event.preventDefault();
+				return;
+			}
 			// A link only activates on Enter; a button also activates on Space.
-			if ( event.key === ' ' ) {
-				if ( ! event.repeat ) {
-					toggleTooltip( event );
-				}
+			if ( hasTextTrigger && event.key === ' ' ) {
+				toggleTooltip( event );
 				return;
 			}
 			if ( ! isVisible ) {
@@ -107,7 +112,7 @@ const IconTooltip: FC< IconTooltipProps > = ( {
 				}
 			}
 		},
-		[ isVisible, hideTooltip, toggleTooltip ]
+		[ hasTextTrigger, isVisible, hideTooltip, toggleTooltip ]
 	);
 
 	const isAnchorWrapper = popoverAnchorStyle === 'wrapper';
@@ -151,10 +156,6 @@ const IconTooltip: FC< IconTooltipProps > = ( {
 		[ hideTooltip ]
 	);
 
-	const focusOnOpen =
-		isForcedToShow || ( hasTextTrigger && ! openedByHover.current )
-			? 'firstElement'
-			: ! openedByHover.current;
 	const args = {
 		// To be compatible with deprecating prop `position`.
 		position: placementsToPositions( placement ),
@@ -164,9 +165,9 @@ const IconTooltip: FC< IconTooltipProps > = ( {
 		resize: false,
 		flip: false,
 		offset, // The distance (in px) between the anchor and the popover.
-		// 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,
+		// Focus stays on the trigger, which handles the dialog keys; a caller-controlled popover
+		// has no trigger, so it focuses its first button instead.
+		focusOnMount: isForcedToShow ? 'firstElement' : false,
 		// 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,
@@ -174,7 +175,7 @@ const IconTooltip: FC< IconTooltipProps > = ( {
 		ref: popoverRef,
 		onClose: () => {
 			const popover = popoverRef.current;
-			if ( hasTextTrigger && popover?.contains( popover.ownerDocument.activeElement ) ) {
+			if ( popover?.contains( popover.ownerDocument.activeElement ) ) {
 				focusAfterClose.current = triggerRef.current;
 			}
 			hideTooltip();
@@ -215,6 +216,21 @@ const IconTooltip: FC< IconTooltipProps > = ( {
 		return () => doc?.removeEventListener( 'pointerdown', handlePointerDown );
 	}, [ isVisible, isForcedToShow, closeOnClickOutside, hideTooltip ] );
 
+	// Hover leaves focus elsewhere, so Escape is watched directly to keep the content dismissible.
+	useEffect( () => {
+		if ( ! isVisible || ! openedByHover.current ) {
+			return;
+		}
+		const doc = wrapperRef.current?.ownerDocument;
+		const handleKeyDown = ( event: globalThis.KeyboardEvent ) => {
+			if ( event.key === 'Escape' ) {
+				hideTooltip();
+			}
+		};
+		doc?.addEventListener( 'keydown', handleKeyDown );
+		return () => doc?.removeEventListener( 'keydown', handleKeyDown );
+	}, [ isVisible, hideTooltip ] );
+
 	useEffect( () => {
 		if ( isForcedToShow || isVisible ) {
 			return;
@@ -224,6 +240,14 @@ const IconTooltip: FC< IconTooltipProps > = ( {
 		destination?.focus();
 	}, [ isForcedToShow, isVisible ] );
 
+	// Focus stays on the trigger, so a screen reader hears the popover through an announcement.
+	useEffect( () => {
+		const popover = popoverRef.current;
+		if ( isVisible && ! openedByHover.current && popover ) {
+			speak( popover.innerText ?? popover.textContent, 'polite' );
+		}
+	}, [ isVisible ] );
+
 	const handleMouseEnter = useCallback( () => {
 		if ( hoverShow ) {
 			if ( hoverTimeout ) {
@@ -270,7 +294,7 @@ const IconTooltip: FC< IconTooltipProps > = ( {
 				<>
 					{ /* A link, not a button, so it keeps the host page's link styling. */ }
 					<a
-						ref={ triggerRef }
+						ref={ triggerRef as React.RefObject< HTMLAnchorElement > }
 						href="#"
 						role="button"
 						className="icon-tooltip-trigger"
@@ -286,7 +310,14 @@ const IconTooltip: FC< IconTooltipProps > = ( {
 				</>
 			) }
 			{ ! hasTextTrigger && ! isAnchorWrapper && (
-				<Button variant="link" aria-expanded={ isVisible } onClick={ toggleTooltip }>
+				<Button
+					ref={ triggerRef }
+					variant="link"
+					aria-label={ label }
+					aria-expanded={ isVisible }
+					onClick={ toggleTooltip }
+					onKeyDown={ handleTriggerKeyDown }
+				>
 					<Icon className={ iconClassName } icon={ iconCode } size={ iconSize } />
 				</Button>
 			) }

package/components/icon-tooltip/style.scss

@@ -107,14 +107,6 @@ $arrow-color: var(--jp-gray);
 .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 {
 		padding: 24px;

package/components/icon-tooltip/types.ts

@@ -41,6 +41,11 @@ export type IconTooltipProps = {
 	 */
 	iconCode?: ComponentProps< typeof Icon >[ 'icon' ];
 
+	/**
+	 * The accessible name of the icon button. Ignored when `trigger` is set, since its text names it.
+	 */
+	label?: string;
+
 	/**
 	 * The title of Popover.
 	 */

package/components/jitm-slot/index.tsx

@@ -0,0 +1,67 @@
+import clsx from 'clsx';
+import { useLayoutEffect, useRef } from 'react';
+import './style.scss';
+import type { JitmSlotProps } from './types.ts';
+import type { FC } from 'react';
+
+const NOTICES_ID = 'jp-admin-notices';
+
+/**
+ * Returns the page's one `#jp-admin-notices`, creating it on first use.
+ *
+ * Found through the DOM, not a module variable: each wp-build route bundles its own copy
+ * of this module.
+ *
+ * @return {HTMLElement} The element.
+ */
+const getNotices = (): HTMLElement => {
+	let element = document.getElementById( NOTICES_ID );
+	if ( ! element ) {
+		element = document.createElement( 'div' );
+		element.id = NOTICES_ID;
+	}
+	return element;
+};
+
+/**
+ * Hosts the element the JITM script re-parents its card into.
+ *
+ * The JITM script places its card once per page load, so the element outlives any
+ * one slot: an unmounted slot parks it, hidden, and the next slot takes it back.
+ * `className` is for width and alignment; `style.scss` owns spacing.
+ *
+ * @param {JitmSlotProps} props - Component props.
+ * @return {JSX.Element} The slot.
+ */
+const JitmSlot: FC< JitmSlotProps > = ( { className, inset } ) => {
+	const ref = useRef< HTMLDivElement >( null );
+
+	useLayoutEffect( () => {
+		const host = ref.current;
+		if ( ! host ) {
+			return;
+		}
+
+		const element = getNotices();
+		element.hidden = false;
+		host.appendChild( element );
+
+		return () => {
+			// A slot that mounted before this one unmounted may already hold it.
+			if ( element.parentNode === host ) {
+				element.hidden = true;
+				document.body.appendChild( element );
+			}
+		};
+	}, [] );
+
+	return (
+		<div
+			ref={ ref }
+			className={ clsx( 'jp-jitm-slot', { 'jp-jitm-slot--inset': inset }, className ) }
+			data-testid="jp-jitm-slot"
+		/>
+	);
+};
+
+export default JitmSlot;

package/components/jitm-slot/style.scss

@@ -0,0 +1,16 @@
+// The slot is always rendered and usually empty, so it takes no space
+// of its own; spacing sits on the card so a dismissed one leaves no gap.
+.jp-jitm-slot {
+	margin: 0;
+	padding: 0;
+
+	// `jitm-card` comes from packages/jitm/src/js/jetpack-jitm.js.
+	.jitm-card {
+		margin: var(--wpds-dimension-gap-xl) 0;
+	}
+}
+
+// Same specificity as the rule above, so it has to come after it.
+.jp-jitm-slot--inset .jitm-card {
+	margin-inline: var(--wpds-dimension-padding-2xl);
+}

package/components/jitm-slot/types.ts

@@ -0,0 +1,10 @@
+export type JitmSlotProps = {
+	/**
+	 * Layout the dashboard owns: width, column span, centering. Not spacing.
+	 */
+	className?: string;
+	/**
+	 * The slot sits outside the page's padded container, so the card takes the page gutter.
+	 */
+	inset?: boolean;
+};

package/components/text/style.module.scss

@@ -89,9 +89,9 @@ $props: (
 
 $sides: (
 	"top": "t",
-	"right": "r",
+	"inline-end": "r",
 	"bottom": "b",
-	"left": "l",
+	"inline-start": "l",
 );
 
 @each $prop, $p in $props {
@@ -106,8 +106,8 @@ $sides: (
 
 		/* mx, px */
 		.#{$p}x-#{$size} {
-			#{$prop}-left: calc(var(--spacing-base) * #{$size});
-			#{$prop}-right: calc(var(--spacing-base) * #{$size});
+			#{$prop}-inline-start: calc(var(--spacing-base) * #{$size});
+			#{$prop}-inline-end: calc(var(--spacing-base) * #{$size});
 		}
 
 		.#{$p}y-#{$size} {

package/components/text/types.ts

@@ -9,11 +9,11 @@ export type TextProps = {
 	m?: SpacingValue;
 	/** margin-top */
 	mt?: SpacingValue;
-	/** margin-right */
+	/** margin-inline-end (right in LTR) */
 	mr?: SpacingValue;
 	/** margin-bottom */
 	mb?: SpacingValue;
-	/** margin-left */
+	/** margin-inline-start (left in LTR) */
 	ml?: SpacingValue;
 	/** margin left and right */
 	mx?: SpacingValue;
@@ -23,11 +23,11 @@ export type TextProps = {
 	p?: SpacingValue;
 	/** padding-top */
 	pt?: SpacingValue;
-	/** padding-right */
+	/** padding-inline-end (right in LTR) */
 	pr?: SpacingValue;
 	/** padding-bottom */
 	pb?: SpacingValue;
-	/** padding-left */
+	/** padding-inline-start (left in LTR) */
 	pl?: SpacingValue;
 	/** padding left and right */
 	px?: SpacingValue;

package/index.ts

@@ -35,6 +35,7 @@ export { default as Col } from './components/layout/col/index.tsx';
 export { default as Testimonials } from './components/testimonials/index.tsx';
 export { default as Container } from './components/layout/container/index.tsx';
 export { default as CopyToClipboard } from './components/copy-to-clipboard/index.tsx';
+export { default as JitmSlot } from './components/jitm-slot/index.tsx';
 export * from './components/icons/index.tsx';
 export { default as ThemeProvider } from './components/theme-provider/index.tsx';
 export { default as Text, H2, H3, Title } from './components/text/index.tsx';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@automattic/jetpack-components",
-	"version": "3.2.0",
+	"version": "3.3.0",
 	"description": "Jetpack Components Package",
 	"homepage": "https://github.com/Automattic/jetpack/tree/HEAD/projects/js-packages/components/#readme",
 	"bugs": {
@@ -46,6 +46,10 @@
 			"types": "./build/components/jetpack-logo/index.d.ts",
 			"default": "./build/components/jetpack-logo/index.js"
 		},
+		"./jitm-slot": {
+			"types": "./build/components/jitm-slot/index.d.ts",
+			"default": "./build/components/jitm-slot/index.js"
+		},
 		"./pricing-table": {
 			"types": "./build/components/pricing-table/index.d.ts",
 			"default": "./build/components/pricing-table/index.js"
@@ -75,9 +79,10 @@
 		"@automattic/jetpack-api": "^2.0.0",
 		"@automattic/jetpack-boost-score-api": "^1.1.0",
 		"@automattic/jetpack-script-data": "^0.6.8",
-		"@automattic/number-formatters": "^1.2.9",
+		"@automattic/number-formatters": "^1.2.10",
 		"@babel/runtime": "^7",
 		"@gravatar-com/hovercards": "0.16.0",
+		"@wordpress/a11y": "4.55.0",
 		"@wordpress/admin-ui": "2.10.0",
 		"@wordpress/browserslist-config": "6.55.0",
 		"@wordpress/components": "40.1.0",
@@ -95,12 +100,12 @@
 		"js-sha256": "0.11.1",
 		"prop-types": "^15.7.2",
 		"qrcode.react": "4.2.0",
-		"social-logos": "^3.3.19",
+		"social-logos": "^3.4.0",
 		"uplot": "1.6.31",
 		"uplot-react": "1.1.4"
 	},
 	"devDependencies": {
-		"@automattic/jetpack-base-styles": "^1.2.14",
+		"@automattic/jetpack-base-styles": "^1.2.15",
 		"@babel/core": "7.29.7",
 		"@jest/globals": "30.5.1",
 		"@storybook/addon-docs": "10.4.6",