@envive-ai/react-widgets 0.3.66 → 0.3.68

package/dist/SearchResults/SearchResults.d.cts

@@ -1,11 +1,11 @@
 import { SearchResultsEntryPointWidgetConfig } from "./types.cjs";
-import * as react_jsx_runtime0 from "react/jsx-runtime";
+import * as react_jsx_runtime1 from "react/jsx-runtime";
 import { SearchResultsHocProps } from "@envive-ai/react-hooks/hooks/Search";
 
 //#region src/SearchResults/SearchResults.d.ts
 interface SearchResultsProps extends SearchResultsHocProps {
   widgetConfig: SearchResultsEntryPointWidgetConfig;
 }
-declare const SearchResults: (props: Omit<SearchResultsProps, string | number | symbol>) => react_jsx_runtime0.JSX.Element;
+declare const SearchResults: (props: Omit<SearchResultsProps, string | number | symbol>) => react_jsx_runtime1.JSX.Element;
 //#endregion
 export { SearchResults };

package/dist/SearchResults/SearchResultsWidget.d.cts

@@ -1,6 +1,6 @@
-import * as react_jsx_runtime0 from "react/jsx-runtime";
+import * as react_jsx_runtime3 from "react/jsx-runtime";
 
 //#region src/SearchResults/SearchResultsWidget.d.ts
-declare const SearchResultsWidget: () => react_jsx_runtime0.JSX.Element;
+declare const SearchResultsWidget: () => react_jsx_runtime3.JSX.Element;
 //#endregion
 export { SearchResultsWidget };

package/dist/SearchZeroState/SearchZeroStateWidget.d.cts

@@ -1,4 +1,4 @@
-import * as react_jsx_runtime3 from "react/jsx-runtime";
+import * as react_jsx_runtime0 from "react/jsx-runtime";
 
 //#region src/SearchZeroState/SearchZeroStateWidget.d.ts
 type SearchZeroStateWidgetProps = {
@@ -10,6 +10,6 @@ declare const SearchZeroStateWidget: ({
   initialIsOpen,
   widgetConfigId,
   entryPointRef
-}: SearchZeroStateWidgetProps) => react_jsx_runtime3.JSX.Element;
+}: SearchZeroStateWidgetProps) => react_jsx_runtime0.JSX.Element;
 //#endregion
 export { SearchZeroStateWidget };

package/dist/SuggestionBar/SuggestionBar.cjs

@@ -2,8 +2,10 @@ const require_rolldown_runtime = require('../_virtual/rolldown_runtime.cjs');
 const require_index = require('../node_modules/react-indiana-drag-scroll/dist/index.cjs');
 const require_v4 = require('../node_modules/uuid/dist-node/v4.cjs');
 const require_types = require('./types.cjs');
+const require_useReducedMotionWithOverride = require('../util/useReducedMotionWithOverride.cjs');
 const require_SuggestionButtonContainer = require('../SuggestionButtonContainer/SuggestionButtonContainer.cjs');
 require('../SuggestionButtonContainer/index.cjs');
+const require_SuggestionBarAnimationToggle = require('./SuggestionBarAnimationToggle.cjs');
 let react = require("react");
 let jotai = require("jotai");
 let react_jsx_runtime = require("react/jsx-runtime");
@@ -21,7 +23,12 @@ function SuggestionBar({ id, locationForMetrics, buttonTexts, buttonVariation, h
 	const { ref } = (0, import_dist.useScrollContainer)();
 	const isSmallScreen = (0, __envive_ai_react_hooks_hooks_IsSmallScreen.useIsSmallScreen)();
 	const logPerfMetric = (0, jotai.useSetAtom)(__envive_ai_react_hooks_atoms_chat.logPerfMetricAtom);
-	(0, __envive_ai_react_hooks_hooks_TrackComponentVisibleEvent.useTrackComponentVisibleEvent)(componentVisibleTriggerRef, { animated: animationSpeed !== "none" });
+	const reducedMotion = require_useReducedMotionWithOverride.useReducedMotionWithOverride();
+	const [isUserPaused, setIsUserPaused] = (0, react.useState)(false);
+	const isAnimated = animationSpeed !== "none";
+	const showAnimationToggle = isAnimated && !reducedMotion;
+	const scrollContainerId = `${id}-scroll-container`;
+	(0, __envive_ai_react_hooks_hooks_TrackComponentVisibleEvent.useTrackComponentVisibleEvent)(componentVisibleTriggerRef, { animated: isAnimated });
 	const handleClickSuggestion = (0, react.useCallback)((buttonText) => {
 		handleReply({
 			id: require_v4.default(),
@@ -43,10 +50,19 @@ function SuggestionBar({ id, locationForMetrics, buttonTexts, buttonVariation, h
 		logPerfMetric,
 		setRefs
 	]);
-	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 		id,
 		className: "spiffy-tw-w-full spiffy-tw-justify-center spiffy-tw-overflow-hidden",
-		children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+		style: showAnimationToggle ? { position: "relative" } : void 0,
+		children: [showAnimationToggle && /* @__PURE__ */ (0, react_jsx_runtime.jsx)(require_SuggestionBarAnimationToggle.SuggestionBarAnimationToggle, {
+			isPaused: isUserPaused,
+			onToggle: () => setIsUserPaused((paused) => !paused),
+			buttonVariation,
+			hoverButtonVariation,
+			buttonBorderRadius,
+			controlsId: scrollContainerId
+		}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+			id: scrollContainerId,
 			className: `spiffy-tw-no-scrollbar spiffy-tw-relative spiffy-tw-w-full spiffy-tw-overflow-y-hidden spiffy-tw-overflow-x-scroll ${twoRowsOnMobile && isSmallScreen ? "spiffy-tw-h-20" : "spiffy-tw-h-9"} `,
 			ref: handleContainerRef,
 			children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
@@ -62,10 +78,11 @@ function SuggestionBar({ id, locationForMetrics, buttonTexts, buttonVariation, h
 					boldFirstButton,
 					twoRowsOnMobile,
 					animationSpeed,
-					buttonBorderRadius
+					buttonBorderRadius,
+					isUserPaused
 				})
 			})
-		})
+		})]
 	});
 }
 

package/dist/SuggestionBar/SuggestionBar.d.cts

@@ -1,5 +1,5 @@
 import { SuggestionBarLocationForMetrics } from "./types.cjs";
-import * as react_jsx_runtime2 from "react/jsx-runtime";
+import * as react_jsx_runtime0 from "react/jsx-runtime";
 import { SuggestionButtonVariant } from "@envive-ai/react-hooks/contexts/types";
 import { Message } from "postcss";
 
@@ -29,6 +29,6 @@ declare function SuggestionBar({
   buttonBorderRadius,
   handleReply,
   dataTestId
-}: Readonly<SuggestionBarProps>): react_jsx_runtime2.JSX.Element;
+}: Readonly<SuggestionBarProps>): react_jsx_runtime0.JSX.Element;
 //#endregion
 export { SuggestionBar };

package/dist/SuggestionBar/SuggestionBar.js

@@ -1,10 +1,12 @@
 import v4_default from "../node_modules/uuid/dist/v4.js";
 import { SuggestionBarLocationForMetrics } from "./types.js";
+import { useReducedMotionWithOverride } from "../util/useReducedMotionWithOverride.js";
 import { SuggestionButtonContainer } from "../SuggestionButtonContainer/SuggestionButtonContainer.js";
 import "../SuggestionButtonContainer/index.js";
-import { useCallback, useRef } from "react";
+import { SuggestionBarAnimationToggle } from "./SuggestionBarAnimationToggle.js";
+import { useCallback, useRef, useState } from "react";
 import { useSetAtom } from "jotai";
-import { jsx } from "react/jsx-runtime";
+import { jsx, jsxs } from "react/jsx-runtime";
 import { MessageRole, MessageType } from "@envive-ai/react-hooks/application/models";
 import { useScrollContainer } from "react-indiana-drag-scroll";
 import { PerfMetricsEvents, logPerfMetricAtom } from "@envive-ai/react-hooks/atoms/chat";
@@ -19,7 +21,12 @@ function SuggestionBar({ id, locationForMetrics, buttonTexts, buttonVariation, h
 	const { ref } = useScrollContainer();
 	const isSmallScreen = useIsSmallScreen();
 	const logPerfMetric = useSetAtom(logPerfMetricAtom);
-	useTrackComponentVisibleEvent(componentVisibleTriggerRef, { animated: animationSpeed !== "none" });
+	const reducedMotion = useReducedMotionWithOverride();
+	const [isUserPaused, setIsUserPaused] = useState(false);
+	const isAnimated = animationSpeed !== "none";
+	const showAnimationToggle = isAnimated && !reducedMotion;
+	const scrollContainerId = `${id}-scroll-container`;
+	useTrackComponentVisibleEvent(componentVisibleTriggerRef, { animated: isAnimated });
 	const handleClickSuggestion = useCallback((buttonText) => {
 		handleReply({
 			id: v4_default(),
@@ -41,10 +48,19 @@ function SuggestionBar({ id, locationForMetrics, buttonTexts, buttonVariation, h
 		logPerfMetric,
 		setRefs
 	]);
-	return /* @__PURE__ */ jsx("div", {
+	return /* @__PURE__ */ jsxs("div", {
 		id,
 		className: "spiffy-tw-w-full spiffy-tw-justify-center spiffy-tw-overflow-hidden",
-		children: /* @__PURE__ */ jsx("div", {
+		style: showAnimationToggle ? { position: "relative" } : void 0,
+		children: [showAnimationToggle && /* @__PURE__ */ jsx(SuggestionBarAnimationToggle, {
+			isPaused: isUserPaused,
+			onToggle: () => setIsUserPaused((paused) => !paused),
+			buttonVariation,
+			hoverButtonVariation,
+			buttonBorderRadius,
+			controlsId: scrollContainerId
+		}), /* @__PURE__ */ jsx("div", {
+			id: scrollContainerId,
 			className: `spiffy-tw-no-scrollbar spiffy-tw-relative spiffy-tw-w-full spiffy-tw-overflow-y-hidden spiffy-tw-overflow-x-scroll ${twoRowsOnMobile && isSmallScreen ? "spiffy-tw-h-20" : "spiffy-tw-h-9"} `,
 			ref: handleContainerRef,
 			children: /* @__PURE__ */ jsx("div", {
@@ -60,10 +76,11 @@ function SuggestionBar({ id, locationForMetrics, buttonTexts, buttonVariation, h
 					boldFirstButton,
 					twoRowsOnMobile,
 					animationSpeed,
-					buttonBorderRadius
+					buttonBorderRadius,
+					isUserPaused
 				})
 			})
-		})
+		})]
 	});
 }
 

package/dist/SuggestionBar/SuggestionBarAnimationToggle.cjs

@@ -0,0 +1,100 @@
+const require_rolldown_runtime = require('../_virtual/rolldown_runtime.cjs');
+let react = require("react");
+let classnames = require("classnames");
+classnames = require_rolldown_runtime.__toESM(classnames);
+let react_jsx_runtime = require("react/jsx-runtime");
+let __envive_ai_react_toolkit_SuggestionButton = require("@envive-ai/react-toolkit/SuggestionButton");
+
+//#region src/SuggestionBar/SuggestionBarAnimationToggle.tsx
+const SUGGESTION_BAR_ANIMATION_TOGGLE_TESTID = "suggestion-bar-animation-toggle";
+const PauseIcon = () => /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("svg", {
+	width: "12",
+	height: "12",
+	viewBox: "0 0 12 12",
+	"aria-hidden": "true",
+	focusable: "false",
+	fill: "currentColor",
+	children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("rect", {
+		x: "2",
+		y: "1",
+		width: "3",
+		height: "10",
+		rx: "1"
+	}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("rect", {
+		x: "7",
+		y: "1",
+		width: "3",
+		height: "10",
+		rx: "1"
+	})]
+});
+const PlayIcon = () => /* @__PURE__ */ (0, react_jsx_runtime.jsx)("svg", {
+	width: "12",
+	height: "12",
+	viewBox: "0 0 12 12",
+	"aria-hidden": "true",
+	focusable: "false",
+	fill: "currentColor",
+	children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("path", { d: "M3 1.5v9a.75.75 0 0 0 1.14.64l7.2-4.5a.75.75 0 0 0 0-1.28l-7.2-4.5A.75.75 0 0 0 3 1.5Z" })
+});
+const VISUALLY_HIDDEN_STYLE = {
+	position: "absolute",
+	width: 1,
+	height: 1,
+	padding: 0,
+	margin: -1,
+	overflow: "hidden",
+	clip: "rect(0 0 0 0)",
+	whiteSpace: "nowrap",
+	border: 0
+};
+const FOCUSED_STYLE = {
+	position: "absolute",
+	top: 0,
+	left: 0,
+	zIndex: 1,
+	height: 36,
+	minHeight: 36,
+	gap: 6,
+	whiteSpace: "nowrap",
+	outline: "2px solid currentColor",
+	outlineOffset: -4
+};
+const SOLID_BACKDROP_BY_VARIANT = {
+	outlined: "var(--spiffy-colors-background-light, #ffffff)",
+	transparentDark: "var(--spiffy-colors-background-light, #ffffff)",
+	transparent: "var(--spiffy-colors-background-dark, #000000)"
+};
+/**
+* Keyboard-accessible pause/play control for the auto-scrolling suggestion bar
+* (WCAG 2.2.2 Pause, Stop, Hide). Styled with the same variant as the suggestion
+* buttons so it blends in with the merchant's theme when it shows up on focus.
+* Styles are inline so they don't depend on the host generating new utility classes.
+*/
+const SuggestionBarAnimationToggle = ({ isPaused, onToggle, buttonVariation, hoverButtonVariation, buttonBorderRadius, controlsId }) => {
+	const [isFocused, setIsFocused] = (0, react.useState)(false);
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("button", {
+		type: "button",
+		onClick: onToggle,
+		onFocus: () => setIsFocused(true),
+		onBlur: () => setIsFocused(false),
+		"aria-controls": controlsId,
+		"data-testid": SUGGESTION_BAR_ANIMATION_TOGGLE_TESTID,
+		style: isFocused ? {
+			...FOCUSED_STYLE,
+			backgroundColor: SOLID_BACKDROP_BY_VARIANT[buttonVariation]
+		} : VISUALLY_HIDDEN_STYLE,
+		className: (0, classnames.default)("spiffy-tw-flex spiffy-tw-cursor-pointer spiffy-tw-items-center spiffy-tw-px-4", {
+			"!spiffy-tw-rounded-[20px]": buttonBorderRadius === "lg",
+			"!spiffy-tw-rounded-[8px]": buttonBorderRadius === "md",
+			"!spiffy-tw-rounded-[0px]": buttonBorderRadius === "sm"
+		}, (0, __envive_ai_react_toolkit_SuggestionButton.getSuggestionButtonVariantClasses)(buttonVariation, hoverButtonVariation)),
+		children: [isPaused ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)(PlayIcon, {}) : /* @__PURE__ */ (0, react_jsx_runtime.jsx)(PauseIcon, {}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+			className: "spiffy-tw-text-[14px]",
+			children: isPaused ? "Play scrolling suggestions" : "Pause scrolling suggestions"
+		})]
+	});
+};
+
+//#endregion
+exports.SuggestionBarAnimationToggle = SuggestionBarAnimationToggle;

package/dist/SuggestionBar/SuggestionBarAnimationToggle.js

@@ -0,0 +1,98 @@
+import { useState } from "react";
+import classNames from "classnames";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { getSuggestionButtonVariantClasses } from "@envive-ai/react-toolkit/SuggestionButton";
+
+//#region src/SuggestionBar/SuggestionBarAnimationToggle.tsx
+const SUGGESTION_BAR_ANIMATION_TOGGLE_TESTID = "suggestion-bar-animation-toggle";
+const PauseIcon = () => /* @__PURE__ */ jsxs("svg", {
+	width: "12",
+	height: "12",
+	viewBox: "0 0 12 12",
+	"aria-hidden": "true",
+	focusable: "false",
+	fill: "currentColor",
+	children: [/* @__PURE__ */ jsx("rect", {
+		x: "2",
+		y: "1",
+		width: "3",
+		height: "10",
+		rx: "1"
+	}), /* @__PURE__ */ jsx("rect", {
+		x: "7",
+		y: "1",
+		width: "3",
+		height: "10",
+		rx: "1"
+	})]
+});
+const PlayIcon = () => /* @__PURE__ */ jsx("svg", {
+	width: "12",
+	height: "12",
+	viewBox: "0 0 12 12",
+	"aria-hidden": "true",
+	focusable: "false",
+	fill: "currentColor",
+	children: /* @__PURE__ */ jsx("path", { d: "M3 1.5v9a.75.75 0 0 0 1.14.64l7.2-4.5a.75.75 0 0 0 0-1.28l-7.2-4.5A.75.75 0 0 0 3 1.5Z" })
+});
+const VISUALLY_HIDDEN_STYLE = {
+	position: "absolute",
+	width: 1,
+	height: 1,
+	padding: 0,
+	margin: -1,
+	overflow: "hidden",
+	clip: "rect(0 0 0 0)",
+	whiteSpace: "nowrap",
+	border: 0
+};
+const FOCUSED_STYLE = {
+	position: "absolute",
+	top: 0,
+	left: 0,
+	zIndex: 1,
+	height: 36,
+	minHeight: 36,
+	gap: 6,
+	whiteSpace: "nowrap",
+	outline: "2px solid currentColor",
+	outlineOffset: -4
+};
+const SOLID_BACKDROP_BY_VARIANT = {
+	outlined: "var(--spiffy-colors-background-light, #ffffff)",
+	transparentDark: "var(--spiffy-colors-background-light, #ffffff)",
+	transparent: "var(--spiffy-colors-background-dark, #000000)"
+};
+/**
+* Keyboard-accessible pause/play control for the auto-scrolling suggestion bar
+* (WCAG 2.2.2 Pause, Stop, Hide). Styled with the same variant as the suggestion
+* buttons so it blends in with the merchant's theme when it shows up on focus.
+* Styles are inline so they don't depend on the host generating new utility classes.
+*/
+const SuggestionBarAnimationToggle = ({ isPaused, onToggle, buttonVariation, hoverButtonVariation, buttonBorderRadius, controlsId }) => {
+	const [isFocused, setIsFocused] = useState(false);
+	return /* @__PURE__ */ jsxs("button", {
+		type: "button",
+		onClick: onToggle,
+		onFocus: () => setIsFocused(true),
+		onBlur: () => setIsFocused(false),
+		"aria-controls": controlsId,
+		"data-testid": SUGGESTION_BAR_ANIMATION_TOGGLE_TESTID,
+		style: isFocused ? {
+			...FOCUSED_STYLE,
+			backgroundColor: SOLID_BACKDROP_BY_VARIANT[buttonVariation]
+		} : VISUALLY_HIDDEN_STYLE,
+		className: classNames("spiffy-tw-flex spiffy-tw-cursor-pointer spiffy-tw-items-center spiffy-tw-px-4", {
+			"!spiffy-tw-rounded-[20px]": buttonBorderRadius === "lg",
+			"!spiffy-tw-rounded-[8px]": buttonBorderRadius === "md",
+			"!spiffy-tw-rounded-[0px]": buttonBorderRadius === "sm"
+		}, getSuggestionButtonVariantClasses(buttonVariation, hoverButtonVariation)),
+		children: [isPaused ? /* @__PURE__ */ jsx(PlayIcon, {}) : /* @__PURE__ */ jsx(PauseIcon, {}), /* @__PURE__ */ jsx("span", {
+			className: "spiffy-tw-text-[14px]",
+			children: isPaused ? "Play scrolling suggestions" : "Pause scrolling suggestions"
+		})]
+	});
+};
+
+//#endregion
+export { SuggestionBarAnimationToggle };

package/dist/SuggestionButtonContainer/SuggestionButtonContainer.cjs

@@ -1,4 +1,5 @@
 const require_rolldown_runtime = require('../_virtual/rolldown_runtime.cjs');
+const require_useReducedMotionWithOverride = require('../util/useReducedMotionWithOverride.cjs');
 const require_useHorizontalScrollAnimation = require('../util/useHorizontalScrollAnimation.cjs');
 let react = require("react");
 let react_jsx_runtime = require("react/jsx-runtime");
@@ -14,14 +15,16 @@ function ButtonContainer({ children }) {
 		children
 	});
 }
-const SuggestionButtonContainer = ({ buttonVariation, hoverButtonVariation, buttonTexts = [], boldFirstButton = false, twoRowsOnMobile = false, animationSpeed = "none", buttonBorderRadius = "lg", scrollContainerRef, onButtonClick }) => {
+const SuggestionButtonContainer = ({ buttonVariation, hoverButtonVariation, buttonTexts = [], boldFirstButton = false, twoRowsOnMobile = false, animationSpeed = "none", buttonBorderRadius = "lg", scrollContainerRef, onButtonClick, isUserPaused = false }) => {
 	const componentVisibleTriggerRef = (0, react.useRef)(null);
 	require_useHorizontalScrollAnimation.useHorizontalScrollAnimation({
 		scrollContainerRef,
-		animationSpeed
+		animationSpeed,
+		isUserPaused
 	});
 	const isSmallScreen = (0, __envive_ai_react_hooks_hooks_IsSmallScreen.useIsSmallScreen)();
-	const isAnimated = animationSpeed !== "none";
+	const reducedMotion = require_useReducedMotionWithOverride.useReducedMotionWithOverride();
+	const isAnimated = animationSpeed !== "none" && !reducedMotion;
 	(0, __envive_ai_react_hooks_hooks_TrackComponentVisibleEvent.useTrackComponentVisibleEvent)(componentVisibleTriggerRef, { animated: isAnimated });
 	const visibleButtonsFirstRow = buttonTexts.slice(0, twoRowsOnMobile && isSmallScreen ? Math.ceil((buttonTexts.length + 1) / 2) : void 0);
 	const visibleButtonsSecondRow = buttonTexts.slice(Math.ceil((buttonTexts.length + 1) / 2), buttonTexts.length);
@@ -44,7 +47,9 @@ const SuggestionButtonContainer = ({ buttonVariation, hoverButtonVariation, butt
 			boldText: boldFirstButton && i === 0,
 			borderRadius: buttonBorderRadius,
 			onClick: () => onButtonClick(suggestion),
-			dataTestId: __envive_ai_react_hooks_config.SUGGESTION_BAR_BUTTON_TESTID
+			dataTestId: __envive_ai_react_hooks_config.SUGGESTION_BAR_BUTTON_TESTID,
+			ariaHidden: true,
+			tabIndex: -1
 		}, `animation-dupe-${i}`))] }), twoRowsOnMobile && isSmallScreen && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
 			className: "spiffy-tw-mt-1.5",
 			children: /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(ButtonContainer, { children: [visibleButtonsSecondRow.map((suggestion, i) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)(__envive_ai_react_toolkit_SuggestionButton.SuggestionButton, {
@@ -64,7 +69,9 @@ const SuggestionButtonContainer = ({ buttonVariation, hoverButtonVariation, butt
 				boldText: boldFirstButton && i === 0,
 				borderRadius: buttonBorderRadius,
 				onClick: () => onButtonClick(suggestion),
-				dataTestId: __envive_ai_react_hooks_config.SUGGESTION_BAR_BUTTON_TESTID
+				dataTestId: __envive_ai_react_hooks_config.SUGGESTION_BAR_BUTTON_TESTID,
+				ariaHidden: true,
+				tabIndex: -1
 			}, `animation-dupe-${i}`))] })
 		})]
 	});

package/dist/SuggestionButtonContainer/SuggestionButtonContainer.js

@@ -1,3 +1,4 @@
+import { useReducedMotionWithOverride } from "../util/useReducedMotionWithOverride.js";
 import { useHorizontalScrollAnimation } from "../util/useHorizontalScrollAnimation.js";
 import { useRef } from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
@@ -13,14 +14,16 @@ function ButtonContainer({ children }) {
 		children
 	});
 }
-const SuggestionButtonContainer = ({ buttonVariation, hoverButtonVariation, buttonTexts = [], boldFirstButton = false, twoRowsOnMobile = false, animationSpeed = "none", buttonBorderRadius = "lg", scrollContainerRef, onButtonClick }) => {
+const SuggestionButtonContainer = ({ buttonVariation, hoverButtonVariation, buttonTexts = [], boldFirstButton = false, twoRowsOnMobile = false, animationSpeed = "none", buttonBorderRadius = "lg", scrollContainerRef, onButtonClick, isUserPaused = false }) => {
 	const componentVisibleTriggerRef = useRef(null);
 	useHorizontalScrollAnimation({
 		scrollContainerRef,
-		animationSpeed
+		animationSpeed,
+		isUserPaused
 	});
 	const isSmallScreen = useIsSmallScreen();
-	const isAnimated = animationSpeed !== "none";
+	const reducedMotion = useReducedMotionWithOverride();
+	const isAnimated = animationSpeed !== "none" && !reducedMotion;
 	useTrackComponentVisibleEvent(componentVisibleTriggerRef, { animated: isAnimated });
 	const visibleButtonsFirstRow = buttonTexts.slice(0, twoRowsOnMobile && isSmallScreen ? Math.ceil((buttonTexts.length + 1) / 2) : void 0);
 	const visibleButtonsSecondRow = buttonTexts.slice(Math.ceil((buttonTexts.length + 1) / 2), buttonTexts.length);
@@ -43,7 +46,9 @@ const SuggestionButtonContainer = ({ buttonVariation, hoverButtonVariation, butt
 			boldText: boldFirstButton && i === 0,
 			borderRadius: buttonBorderRadius,
 			onClick: () => onButtonClick(suggestion),
-			dataTestId: SUGGESTION_BAR_BUTTON_TESTID
+			dataTestId: SUGGESTION_BAR_BUTTON_TESTID,
+			ariaHidden: true,
+			tabIndex: -1
 		}, `animation-dupe-${i}`))] }), twoRowsOnMobile && isSmallScreen && /* @__PURE__ */ jsx("div", {
 			className: "spiffy-tw-mt-1.5",
 			children: /* @__PURE__ */ jsxs(ButtonContainer, { children: [visibleButtonsSecondRow.map((suggestion, i) => /* @__PURE__ */ jsx(SuggestionButton, {
@@ -63,7 +68,9 @@ const SuggestionButtonContainer = ({ buttonVariation, hoverButtonVariation, butt
 				boldText: boldFirstButton && i === 0,
 				borderRadius: buttonBorderRadius,
 				onClick: () => onButtonClick(suggestion),
-				dataTestId: SUGGESTION_BAR_BUTTON_TESTID
+				dataTestId: SUGGESTION_BAR_BUTTON_TESTID,
+				ariaHidden: true,
+				tabIndex: -1
 			}, `animation-dupe-${i}`))] })
 		})]
 	});

package/dist/SuggestionButtonContainer/types.d.cts

@@ -12,6 +12,8 @@ interface SuggestionButtonContainerProps extends TestProps {
   twoRowsOnMobile?: boolean | undefined;
   animationSpeed?: 'standard' | 'slow' | 'none';
   buttonBorderRadius?: 'sm' | 'md' | 'lg';
+  /** Pauses the auto-scroll animation until toggled back (user pause/play control). */
+  isUserPaused?: boolean;
 }
 //#endregion
 export { SuggestionButtonContainerProps };

package/dist/SuggestionButtonContainer/types.d.ts

@@ -12,6 +12,8 @@ interface SuggestionButtonContainerProps extends TestProps {
   twoRowsOnMobile?: boolean | undefined;
   animationSpeed?: 'standard' | 'slow' | 'none';
   buttonBorderRadius?: 'sm' | 'md' | 'lg';
+  /** Pauses the auto-scroll animation until toggled back (user pause/play control). */
+  isUserPaused?: boolean;
 }
 //#endregion
 export { SuggestionButtonContainerProps };

package/dist/util/useHorizontalScrollAnimation.cjs

@@ -3,10 +3,12 @@ const require_useReducedMotionWithOverride = require('./useReducedMotionWithOver
 let react = require("react");
 
 //#region src/util/useHorizontalScrollAnimation.ts
-function useHorizontalScrollAnimation({ scrollContainerRef, animationSpeed = "standard" }) {
+function useHorizontalScrollAnimation({ scrollContainerRef, animationSpeed = "standard", isUserPaused = false }) {
 	const reducedMotion = require_useReducedMotionWithOverride.useReducedMotionWithOverride();
 	const resumeTimeoutRef = (0, react.useRef)(null);
 	const scrollAnimationRef = (0, react.useRef)(null);
+	const isUserPausedRef = (0, react.useRef)(isUserPaused);
+	isUserPausedRef.current = isUserPaused;
 	const pauseOnHover = true;
 	let PIXELS_PER_SECOND = 40;
 	switch (animationSpeed) {
@@ -32,8 +34,9 @@ function useHorizontalScrollAnimation({ scrollContainerRef, animationSpeed = "st
 		let lastTimestamp = null;
 		let accumulatedScroll = 0;
 		const step = (timestamp) => {
-			if (lastTimestamp === null) lastTimestamp = timestamp;
-			if (!isPaused) {
+			if (isPaused || isUserPausedRef.current) lastTimestamp = null;
+			else {
+				if (lastTimestamp === null) lastTimestamp = timestamp;
 				const delta = timestamp - lastTimestamp;
 				lastTimestamp = timestamp;
 				accumulatedScroll += PIXELS_PER_SECOND * (delta / 1e3);
@@ -58,21 +61,31 @@ function useHorizontalScrollAnimation({ scrollContainerRef, animationSpeed = "st
 			}
 		};
 		const scheduleResumeAnimation = () => {
+			if (resumeTimeoutRef.current) clearTimeout(resumeTimeoutRef.current);
 			resumeTimeoutRef.current = setTimeout(() => {
+				if (container.contains(document.activeElement)) return;
 				isPaused = false;
-				lastTimestamp = null;
 			}, RESUME_DELAY_MS);
 		};
+		const handleFocusOut = (event) => {
+			const nextTarget = event.relatedTarget;
+			if (nextTarget && container.contains(nextTarget)) return;
+			scheduleResumeAnimation();
+		};
 		container.addEventListener("mouseenter", pauseAnimation);
 		container.addEventListener("mouseleave", scheduleResumeAnimation);
 		container.addEventListener("touchstart", pauseAnimation);
 		container.addEventListener("touchend", scheduleResumeAnimation);
+		container.addEventListener("focusin", pauseAnimation);
+		container.addEventListener("focusout", handleFocusOut);
 		return function cleanup() {
 			if (scrollAnimationRef.current) cancelAnimationFrame(scrollAnimationRef.current);
 			container.removeEventListener("mouseenter", pauseAnimation);
 			container.removeEventListener("mouseleave", scheduleResumeAnimation);
 			container.removeEventListener("touchstart", pauseAnimation);
 			container.removeEventListener("touchend", scheduleResumeAnimation);
+			container.removeEventListener("focusin", pauseAnimation);
+			container.removeEventListener("focusout", handleFocusOut);
 			if (resumeTimeoutRef.current) clearTimeout(resumeTimeoutRef.current);
 		};
 	}, [

package/dist/util/useHorizontalScrollAnimation.js

@@ -2,10 +2,12 @@ import { useReducedMotionWithOverride } from "./useReducedMotionWithOverride.js"
 import { useEffect, useRef } from "react";
 
 //#region src/util/useHorizontalScrollAnimation.ts
-function useHorizontalScrollAnimation({ scrollContainerRef, animationSpeed = "standard" }) {
+function useHorizontalScrollAnimation({ scrollContainerRef, animationSpeed = "standard", isUserPaused = false }) {
 	const reducedMotion = useReducedMotionWithOverride();
 	const resumeTimeoutRef = useRef(null);
 	const scrollAnimationRef = useRef(null);
+	const isUserPausedRef = useRef(isUserPaused);
+	isUserPausedRef.current = isUserPaused;
 	const pauseOnHover = true;
 	let PIXELS_PER_SECOND = 40;
 	switch (animationSpeed) {
@@ -31,8 +33,9 @@ function useHorizontalScrollAnimation({ scrollContainerRef, animationSpeed = "st
 		let lastTimestamp = null;
 		let accumulatedScroll = 0;
 		const step = (timestamp) => {
-			if (lastTimestamp === null) lastTimestamp = timestamp;
-			if (!isPaused) {
+			if (isPaused || isUserPausedRef.current) lastTimestamp = null;
+			else {
+				if (lastTimestamp === null) lastTimestamp = timestamp;
 				const delta = timestamp - lastTimestamp;
 				lastTimestamp = timestamp;
 				accumulatedScroll += PIXELS_PER_SECOND * (delta / 1e3);
@@ -57,21 +60,31 @@ function useHorizontalScrollAnimation({ scrollContainerRef, animationSpeed = "st
 			}
 		};
 		const scheduleResumeAnimation = () => {
+			if (resumeTimeoutRef.current) clearTimeout(resumeTimeoutRef.current);
 			resumeTimeoutRef.current = setTimeout(() => {
+				if (container.contains(document.activeElement)) return;
 				isPaused = false;
-				lastTimestamp = null;
 			}, RESUME_DELAY_MS);
 		};
+		const handleFocusOut = (event) => {
+			const nextTarget = event.relatedTarget;
+			if (nextTarget && container.contains(nextTarget)) return;
+			scheduleResumeAnimation();
+		};
 		container.addEventListener("mouseenter", pauseAnimation);
 		container.addEventListener("mouseleave", scheduleResumeAnimation);
 		container.addEventListener("touchstart", pauseAnimation);
 		container.addEventListener("touchend", scheduleResumeAnimation);
+		container.addEventListener("focusin", pauseAnimation);
+		container.addEventListener("focusout", handleFocusOut);
 		return function cleanup() {
 			if (scrollAnimationRef.current) cancelAnimationFrame(scrollAnimationRef.current);
 			container.removeEventListener("mouseenter", pauseAnimation);
 			container.removeEventListener("mouseleave", scheduleResumeAnimation);
 			container.removeEventListener("touchstart", pauseAnimation);
 			container.removeEventListener("touchend", scheduleResumeAnimation);
+			container.removeEventListener("focusin", pauseAnimation);
+			container.removeEventListener("focusout", handleFocusOut);
 			if (resumeTimeoutRef.current) clearTimeout(resumeTimeoutRef.current);
 		};
 	}, [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@envive-ai/react-widgets",
-  "version": "0.3.66",
+  "version": "0.3.68",
   "description": "React widget library for Envive services.",
   "keywords": [
     "react",

package/src/SuggestionBar/SuggestionBar.tsx

@@ -1,4 +1,4 @@
-import { useCallback, useRef } from 'react';
+import { useCallback, useRef, useState } from 'react';
 import { useScrollContainer } from 'react-indiana-drag-scroll';
 import { v4 as uuid } from 'uuid';
 import { useSetAtom } from 'jotai';
@@ -13,6 +13,8 @@ import { Message } from 'postcss';
 import { SuggestionButtonVariant } from '@envive-ai/react-hooks/contexts/types';
 import { SuggestionBarLocationForMetrics } from './types';
 import { SuggestionButtonContainer } from '../SuggestionButtonContainer';
+import { useReducedMotionWithOverride } from '../util/useReducedMotionWithOverride';
+import { SuggestionBarAnimationToggle } from './SuggestionBarAnimationToggle';
 
 // SuggestionBarV2 Props
 interface SuggestionBarProps {
@@ -51,8 +53,13 @@ function SuggestionBar({
   const { ref } = useScrollContainer();
   const isSmallScreen = useIsSmallScreen();
   const logPerfMetric = useSetAtom(logPerfMetricAtom);
+  const reducedMotion = useReducedMotionWithOverride();
+  const [isUserPaused, setIsUserPaused] = useState(false);
 
   const isAnimated = animationSpeed !== 'none';
+  // Moving content needs a keyboard-accessible pause control (WCAG 2.2.2).
+  const showAnimationToggle = isAnimated && !reducedMotion;
+  const scrollContainerId = `${id}-scroll-container`;
 
   // Track component visibility
   useTrackComponentVisibleEvent(componentVisibleTriggerRef, {
@@ -101,8 +108,21 @@ function SuggestionBar({
     <div
       id={id}
       className="spiffy-tw-w-full spiffy-tw-justify-center spiffy-tw-overflow-hidden"
+      // Anchors the pause control, which overlays the bar only while it has keyboard focus.
+      style={showAnimationToggle ? { position: 'relative' } : undefined}
     >
+      {showAnimationToggle && (
+        <SuggestionBarAnimationToggle
+          isPaused={isUserPaused}
+          onToggle={() => setIsUserPaused(paused => !paused)}
+          buttonVariation={buttonVariation}
+          hoverButtonVariation={hoverButtonVariation}
+          buttonBorderRadius={buttonBorderRadius}
+          controlsId={scrollContainerId}
+        />
+      )}
       <div
+        id={scrollContainerId}
         className={`spiffy-tw-no-scrollbar spiffy-tw-relative spiffy-tw-w-full spiffy-tw-overflow-y-hidden spiffy-tw-overflow-x-scroll ${twoRowsOnMobile && isSmallScreen ? 'spiffy-tw-h-20' : 'spiffy-tw-h-9'} `}
         ref={handleContainerRef}
       >
@@ -121,6 +141,7 @@ function SuggestionBar({
             twoRowsOnMobile={twoRowsOnMobile}
             animationSpeed={animationSpeed}
             buttonBorderRadius={buttonBorderRadius}
+            isUserPaused={isUserPaused}
           />
         </div>
       </div>

package/src/SuggestionBar/SuggestionBarAnimationToggle.tsx

@@ -0,0 +1,137 @@
+import classNames from 'classnames';
+import { useState } from 'react';
+import { getSuggestionButtonVariantClasses } from '@envive-ai/react-toolkit/SuggestionButton';
+import { SuggestionButtonVariant } from '@envive-ai/react-hooks/contexts/types';
+
+export const SUGGESTION_BAR_ANIMATION_TOGGLE_TESTID = 'suggestion-bar-animation-toggle';
+
+interface SuggestionBarAnimationToggleProps {
+  isPaused: boolean;
+  onToggle: () => void;
+  buttonVariation: SuggestionButtonVariant;
+  hoverButtonVariation: SuggestionButtonVariant;
+  buttonBorderRadius: 'sm' | 'md' | 'lg';
+  controlsId?: string;
+}
+
+const PauseIcon = () => (
+  <svg
+    width="12"
+    height="12"
+    viewBox="0 0 12 12"
+    aria-hidden="true"
+    focusable="false"
+    fill="currentColor"
+  >
+    <rect
+      x="2"
+      y="1"
+      width="3"
+      height="10"
+      rx="1"
+    />
+    <rect
+      x="7"
+      y="1"
+      width="3"
+      height="10"
+      rx="1"
+    />
+  </svg>
+);
+
+const PlayIcon = () => (
+  <svg
+    width="12"
+    height="12"
+    viewBox="0 0 12 12"
+    aria-hidden="true"
+    focusable="false"
+    fill="currentColor"
+  >
+    <path d="M3 1.5v9a.75.75 0 0 0 1.14.64l7.2-4.5a.75.75 0 0 0 0-1.28l-7.2-4.5A.75.75 0 0 0 3 1.5Z" />
+  </svg>
+);
+
+// Visually hidden until focused (skip-link pattern): mouse/touch users never see it,
+// keyboard users get it as the first tab stop of the bar.
+const VISUALLY_HIDDEN_STYLE: React.CSSProperties = {
+  position: 'absolute',
+  width: 1,
+  height: 1,
+  padding: 0,
+  margin: -1,
+  overflow: 'hidden',
+  clip: 'rect(0 0 0 0)',
+  whiteSpace: 'nowrap',
+  border: 0,
+};
+
+// When focused it overlays the start of the bar instead of pushing the suggestions.
+const FOCUSED_STYLE: React.CSSProperties = {
+  position: 'absolute',
+  top: 0,
+  left: 0,
+  zIndex: 1,
+  height: 36,
+  minHeight: 36,
+  gap: 6,
+  whiteSpace: 'nowrap',
+  outline: '2px solid currentColor',
+  outlineOffset: -4,
+};
+
+// Variants without a background of their own would let the overlaid control blend
+// into the suggestion underneath, so give them a solid backdrop matching their text.
+const SOLID_BACKDROP_BY_VARIANT: Partial<Record<SuggestionButtonVariant, string>> = {
+  outlined: 'var(--spiffy-colors-background-light, #ffffff)',
+  transparentDark: 'var(--spiffy-colors-background-light, #ffffff)',
+  transparent: 'var(--spiffy-colors-background-dark, #000000)',
+};
+
+/**
+ * Keyboard-accessible pause/play control for the auto-scrolling suggestion bar
+ * (WCAG 2.2.2 Pause, Stop, Hide). Styled with the same variant as the suggestion
+ * buttons so it blends in with the merchant's theme when it shows up on focus.
+ * Styles are inline so they don't depend on the host generating new utility classes.
+ */
+export const SuggestionBarAnimationToggle = ({
+  isPaused,
+  onToggle,
+  buttonVariation,
+  hoverButtonVariation,
+  buttonBorderRadius,
+  controlsId,
+}: SuggestionBarAnimationToggleProps) => {
+  const [isFocused, setIsFocused] = useState(false);
+
+  return (
+    <button
+      type="button"
+      onClick={onToggle}
+      onFocus={() => setIsFocused(true)}
+      onBlur={() => setIsFocused(false)}
+      aria-controls={controlsId}
+      data-testid={SUGGESTION_BAR_ANIMATION_TOGGLE_TESTID}
+      style={
+        isFocused
+          ? { ...FOCUSED_STYLE, backgroundColor: SOLID_BACKDROP_BY_VARIANT[buttonVariation] }
+          : VISUALLY_HIDDEN_STYLE
+      }
+      className={classNames(
+        'spiffy-tw-flex spiffy-tw-cursor-pointer spiffy-tw-items-center spiffy-tw-px-4',
+        {
+          '!spiffy-tw-rounded-[20px]': buttonBorderRadius === 'lg',
+          '!spiffy-tw-rounded-[8px]': buttonBorderRadius === 'md',
+          '!spiffy-tw-rounded-[0px]': buttonBorderRadius === 'sm',
+        },
+        getSuggestionButtonVariantClasses(buttonVariation, hoverButtonVariation),
+      )}
+    >
+      {isPaused ? <PlayIcon /> : <PauseIcon />}
+      <span className="spiffy-tw-text-[14px]">
+        {isPaused ? 'Play scrolling suggestions' : 'Pause scrolling suggestions'}
+      </span>
+    </button>
+  );
+};

package/src/SuggestionButtonContainer/SuggestionButtonContainer.tsx

@@ -5,6 +5,7 @@ import { SUGGESTION_BAR_BUTTON_TESTID } from '@envive-ai/react-hooks/config';
 import { useIsSmallScreen } from '@envive-ai/react-hooks/hooks/IsSmallScreen';
 import { useTrackComponentVisibleEvent } from '@envive-ai/react-hooks/hooks/TrackComponentVisibleEvent';
 import { useHorizontalScrollAnimation } from 'src/util/useHorizontalScrollAnimation';
+import { useReducedMotionWithOverride } from 'src/util/useReducedMotionWithOverride';
 import { SuggestionButtonContainerProps } from './types';
 
 // ButtonContainer props
@@ -31,6 +32,7 @@ const SuggestionButtonContainer: React.FC<SuggestionButtonContainerProps> = ({
   buttonBorderRadius = 'lg',
   scrollContainerRef,
   onButtonClick,
+  isUserPaused = false,
 }: Readonly<SuggestionButtonContainerProps>) => {
   // Refs
   const componentVisibleTriggerRef = useRef<HTMLDivElement>(null);
@@ -39,10 +41,13 @@ const SuggestionButtonContainer: React.FC<SuggestionButtonContainerProps> = ({
   useHorizontalScrollAnimation({
     scrollContainerRef,
     animationSpeed,
+    isUserPaused,
   });
   const isSmallScreen = useIsSmallScreen();
+  const reducedMotion = useReducedMotionWithOverride();
 
-  const isAnimated = animationSpeed !== 'none';
+  // The hook never animates under reduced motion, so skip the looping copies too.
+  const isAnimated = animationSpeed !== 'none' && !reducedMotion;
 
   // Track component visibility
   useTrackComponentVisibleEvent(componentVisibleTriggerRef, {
@@ -88,6 +93,10 @@ const SuggestionButtonContainer: React.FC<SuggestionButtonContainerProps> = ({
               borderRadius={buttonBorderRadius}
               onClick={() => onButtonClick(suggestion)}
               dataTestId={SUGGESTION_BAR_BUTTON_TESTID}
+              // Looping copies exist only for the visual marquee: keep them out of the
+              // tab order and the accessibility tree so each suggestion is reachable once.
+              ariaHidden
+              tabIndex={-1}
             />
           ))}
       </ButtonContainer>
@@ -119,6 +128,8 @@ const SuggestionButtonContainer: React.FC<SuggestionButtonContainerProps> = ({
                   borderRadius={buttonBorderRadius}
                   onClick={() => onButtonClick(suggestion)}
                   dataTestId={SUGGESTION_BAR_BUTTON_TESTID}
+                  ariaHidden
+                  tabIndex={-1}
                 />
               ))}
           </ButtonContainer>

package/src/SuggestionButtonContainer/types.ts

@@ -12,4 +12,6 @@ export interface SuggestionButtonContainerProps extends TestProps {
   twoRowsOnMobile?: boolean | undefined;
   animationSpeed?: 'standard' | 'slow' | 'none';
   buttonBorderRadius?: 'sm' | 'md' | 'lg';
+  /** Pauses the auto-scroll animation until toggled back (user pause/play control). */
+  isUserPaused?: boolean;
 }

package/src/stories/SuggestionBar.stories.tsx

@@ -1,4 +1,5 @@
 import { type Meta, type StoryObj } from '@storybook/react-vite';
+import { expect, userEvent, within } from 'storybook/test';
 import { SuggestionBar, SuggestionBarLocationForMetrics } from 'src/SuggestionBar';
 
 const meta: Meta<typeof SuggestionBar> = {
@@ -42,4 +43,46 @@ export const Animated: Story = {
     ...Default.args,
     animationSpeed: 'standard',
   },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+
+    // WCAG 2.2.2: the moving bar exposes a keyboard-accessible pause control,
+    // first in the tab order.
+    const toggle = await canvas.findByRole('button', { name: 'Pause scrolling suggestions' });
+    const [firstTabStop] = [...canvasElement.querySelectorAll('button')].filter(
+      button => button.tabIndex >= 0,
+    );
+    await expect(firstTabStop).toBe(toggle);
+
+    // Hidden for mouse users, revealed only while it has keyboard focus.
+    await expect(toggle.style.position).toBe('absolute');
+    await expect(toggle.style.width).toBe('1px');
+    toggle.focus();
+    await expect(toggle).toHaveFocus();
+    await expect(toggle.style.width).toBe('');
+
+    await userEvent.keyboard('{Enter}');
+    await expect(
+      canvas.getByRole('button', { name: 'Play scrolling suggestions' }),
+    ).toBeInTheDocument();
+
+    // Looping copies are hidden, so each suggestion is exposed (and tabbable) once.
+    await expect(canvas.getAllByRole('button', { name: /Button \d/ })).toHaveLength(3);
+    const copies = canvasElement.querySelectorAll('button[aria-hidden="true"]');
+    await expect(copies).toHaveLength(3);
+    copies.forEach(copy => expect(copy).toHaveAttribute('tabindex', '-1'));
+  },
+};
+
+export const Static: Story = {
+  args: Default.args,
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    // No motion, so no pause control and no looping copies.
+    await canvas.findByRole('button', { name: /Button 1/ });
+    await expect(
+      canvas.queryByRole('button', { name: /scrolling suggestions/ }),
+    ).not.toBeInTheDocument();
+    await expect(canvas.getAllByRole('button')).toHaveLength(3);
+  },
 };

package/src/util/useHorizontalScrollAnimation.ts

@@ -5,6 +5,11 @@ import { useReducedMotionWithOverride } from 'src/util/useReducedMotionWithOverr
 interface UseHorizontalScrollAnimationOptions {
   scrollContainerRef: RefObject<HTMLDivElement>;
   animationSpeed?: 'standard' | 'slow' | 'none';
+  /**
+   * Explicit pause requested by the user via the pause/play control. Unlike the
+   * hover/focus/touch pause, it never auto-resumes.
+   */
+  isUserPaused?: boolean;
 }
 
 // When using this hook, ensure that scrouuContainerRef is not undefined. It is allowed to
@@ -12,10 +17,14 @@ interface UseHorizontalScrollAnimationOptions {
 export function useHorizontalScrollAnimation({
   scrollContainerRef,
   animationSpeed = 'standard',
+  isUserPaused = false,
 }: UseHorizontalScrollAnimationOptions): void {
   const reducedMotion = useReducedMotionWithOverride();
   const resumeTimeoutRef = useRef<NodeJS.Timeout | null>(null);
   const scrollAnimationRef = useRef<number | null>(null);
+  // Read through a ref so toggling the control doesn't restart the animation effect.
+  const isUserPausedRef = useRef(isUserPaused);
+  isUserPausedRef.current = isUserPaused;
 
   const pauseOnHover = true; // This is unlikely to need to be configurable but I'm throwing it up here just in case.
 
@@ -55,8 +64,12 @@ export function useHorizontalScrollAnimation({
     let accumulatedScroll = 0; // Accumulate fractional pixels
 
     const step = (timestamp: number) => {
-      if (lastTimestamp === null) lastTimestamp = timestamp;
-      if (!isPaused) {
+      if (isPaused || isUserPausedRef.current) {
+        // Drop the timestamp so the first frame after resuming doesn't jump by
+        // the whole paused duration.
+        lastTimestamp = null;
+      } else {
+        if (lastTimestamp === null) lastTimestamp = timestamp;
         const delta = timestamp - lastTimestamp;
         lastTimestamp = timestamp;
 
@@ -90,18 +103,32 @@ export function useHorizontalScrollAnimation({
       }
     };
     const scheduleResumeAnimation = () => {
+      if (resumeTimeoutRef.current) clearTimeout(resumeTimeoutRef.current);
       resumeTimeoutRef.current = setTimeout(() => {
+        // Keep paused while keyboard focus is still inside the bar, e.g. the mouse
+        // left but the user is tabbing through the suggestions.
+        if (container.contains(document.activeElement)) return;
         isPaused = false;
-        lastTimestamp = null; // Reset timestamp so delta is correct after pause
       }, RESUME_DELAY_MS);
     };
 
+    // Only resume when focus leaves the bar entirely, not when it moves between
+    // suggestions.
+    const handleFocusOut = (event: FocusEvent) => {
+      const nextTarget = event.relatedTarget as Node | null;
+      if (nextTarget && container.contains(nextTarget)) return;
+      scheduleResumeAnimation();
+    };
+
     if (pauseOnHover) {
       container.addEventListener('mouseenter', pauseAnimation);
       container.addEventListener('mouseleave', scheduleResumeAnimation);
       container.addEventListener('touchstart', pauseAnimation);
       container.addEventListener('touchend', scheduleResumeAnimation);
     }
+    // Keyboard users get the same pause as hover (WCAG 2.2.2).
+    container.addEventListener('focusin', pauseAnimation);
+    container.addEventListener('focusout', handleFocusOut);
 
     return function cleanup() {
       if (scrollAnimationRef.current) {
@@ -113,6 +140,8 @@ export function useHorizontalScrollAnimation({
         container.removeEventListener('touchstart', pauseAnimation);
         container.removeEventListener('touchend', scheduleResumeAnimation);
       }
+      container.removeEventListener('focusin', pauseAnimation);
+      container.removeEventListener('focusout', handleFocusOut);
       if (resumeTimeoutRef.current) {
         clearTimeout(resumeTimeoutRef.current);
       }