@envive-ai/react-toolkit-v3 0.3.18 → 0.3.20

package/src/components/FloatingChat/components/ProductResultsModal.tsx

@@ -0,0 +1,87 @@
+import classNames from 'classnames';
+import { Theme } from '../../../../tokens/theme/theme';
+import { ColorNames } from '../../../models/colorsConfig';
+import { SalesAgentProductCardProps } from '../../SalesAgentProductCard/types/types';
+import { ChatHeader } from '../../ChatHeader';
+import { ChatHeaderOptions, ChatHeaderVariant } from '../../ChatHeader/types';
+import { ResultsGridView } from './ResultsGridView';
+import type { ResultsViewData } from '../hooks/useProductResultsView';
+
+const overlayWrapperClasses = classNames(
+  'envive-tw-min-h-0 envive-tw-flex envive-tw-h-full envive-tw-w-full',
+  'envive-tw-items-center envive-tw-justify-center envive-tw-p-4',
+);
+const modalClasses = classNames(
+  'envive-tw-rounded-[16px] envive-tw-flex envive-tw-max-h-[90vh] envive-tw-w-full envive-tw-max-w-[900px]',
+  'envive-tw-flex-col envive-tw-overflow-hidden envive-tw-bg-white envive-tw-shadow-lg',
+);
+const headerWrapperClasses = classNames(
+  'envive-tw-rounded-t-[16px] envive-tw-flex-shrink-0 envive-tw-overflow-hidden',
+);
+const scrollContentClasses = classNames(
+  'envive-tw-flex-1 envive-tw-overflow-y-auto envive-tw-overflow-x-hidden',
+);
+const footerWrapperClasses = classNames('envive-tw-w-full envive-tw-flex-shrink-0');
+
+export interface ProductResultsModalProps {
+  theme: Theme;
+  resultsViewData: ResultsViewData;
+  onBackToChat: () => void;
+  onProductCardClick?: (product: SalesAgentProductCardProps) => void;
+  onClose: () => void;
+  logoDark?: string;
+  logoLight?: string;
+  headerBgColor?: ColorNames;
+  headerMode?: ChatHeaderVariant;
+  footer: React.ReactNode;
+}
+
+/**
+ * Desktop-only modal for "Explore All Results" view.
+ */
+export const ProductResultsModal = ({
+  theme,
+  resultsViewData,
+  onBackToChat,
+  onProductCardClick,
+  logoDark,
+  logoLight,
+  headerBgColor,
+  headerMode,
+  footer,
+}: ProductResultsModalProps) => {
+  const header = (
+    <ChatHeader
+      logoDark={logoDark}
+      logoLight={logoLight}
+      selectedOption={ChatHeaderOptions.ASSISTANT}
+      onToggle={() => {}}
+      onClose={onBackToChat}
+      showLogo
+      showCXToggle={false}
+      centralizeCXToggle
+      theme={theme}
+      variant={headerMode ?? ChatHeaderVariant.LIGHT}
+      headerBgColor={headerBgColor}
+    />
+  );
+
+  return (
+    <div className={overlayWrapperClasses}>
+      <div className={modalClasses}>
+        <div className={headerWrapperClasses}>{header}</div>
+        <div className={scrollContentClasses}>
+          <ResultsGridView
+            theme={theme}
+            searchQuery={resultsViewData.searchQuery}
+            products={resultsViewData.products}
+            onBackToChat={onBackToChat}
+            onProductCardClick={onProductCardClick}
+            gridCols={4}
+          />
+        </div>
+        {footer && <div className={footerWrapperClasses}>{footer}</div>}
+      </div>
+    </div>
+  );
+};

package/src/components/FloatingChat/components/ResultsGridView.tsx

@@ -0,0 +1,117 @@
+import classNames from 'classnames';
+import { Theme } from '../../../../tokens/theme/theme';
+import { SalesAgentProductCard } from '../../SalesAgentProductCard/SalesAgentProductCard';
+import {
+  SalesAgentProductCardProps,
+  SalesAgentProductCardVariant,
+} from '../../SalesAgentProductCard/types/types';
+import { resolveTheme } from '../../utils/resolveTheme';
+import { Stack } from '../../Stack';
+import { Typography, TypographyColor, TypographyVariant } from '../../Typography';
+
+export const NUM_COLUMNS_MOBILE = 2;
+export const NUM_COLUMNS_FPSA = 3;
+export const NUM_COLUMNS_DESKTOP_MODAL = 4;
+
+export type ResultsGridColumnCount =
+  | typeof NUM_COLUMNS_MOBILE
+  | typeof NUM_COLUMNS_FPSA
+  | typeof NUM_COLUMNS_DESKTOP_MODAL;
+
+const gridClassNameByColumnCount: Record<ResultsGridColumnCount, string> = {
+  [NUM_COLUMNS_MOBILE]: 'envive-tw-grid-cols-2 envive-tw-gap-4',
+  [NUM_COLUMNS_FPSA]: 'envive-tw-grid-cols-3 envive-tw-gap-2',
+  [NUM_COLUMNS_DESKTOP_MODAL]: 'envive-tw-grid-cols-4 envive-tw-gap-2',
+};
+
+export interface ResultsGridViewProps {
+  theme: Theme;
+  searchQuery: string;
+  products: SalesAgentProductCardProps[];
+  onBackToChat: () => void;
+  onProductCardClick?: (product: SalesAgentProductCardProps) => void;
+  gridCols?: ResultsGridColumnCount;
+}
+
+export const ResultsGridView = ({
+  theme,
+  searchQuery,
+  products,
+  onBackToChat,
+  onProductCardClick,
+  gridCols = NUM_COLUMNS_MOBILE,
+}: ResultsGridViewProps) => {
+  const finalTheme = resolveTheme(theme);
+
+  const forceShowCurrentPriceSpace = products.some(
+    product => product.currentPrice && product.previousPrice !== product.currentPrice,
+  );
+
+  const gridClassName = gridClassNameByColumnCount[gridCols];
+
+  const searchQueryHeadingClassName = classNames('envive-tw-mb-2', {
+    'envive-tw-text-center': gridCols !== NUM_COLUMNS_MOBILE,
+  });
+
+  return (
+    <Stack
+      direction="column"
+      gap="4"
+      className="envive-tw-pb-4 envive-tw-pl-4 envive-tw-pr-4"
+    >
+      <div className="envive-tw-top-0 envive-tw-sticky envive-tw-z-10 envive-tw-mb-2 envive-tw-bg-background-light envive-tw-pb-2 envive-tw-pt-2">
+        <button
+          type="button"
+          onClick={onBackToChat}
+          className="envive-tw-flex envive-tw-items-center envive-tw-gap-1 envive-tw-rounded-global-custom envive-tw-border envive-tw-border-border-medium envive-tw-bg-background-light envive-tw-p-2 envive-tw-shadow-sm hover:envive-tw-border-border-dark"
+          aria-label="Back to Chat"
+        >
+          <span
+            className="envive-tw-text-[--envive-colors-text-primary]"
+            aria-hidden
+          >
+            ←
+          </span>
+          <Typography
+            variant={TypographyVariant.B3_MD}
+            color={TypographyColor.TEXT_PRIMARY}
+          >
+            Back to Chat
+          </Typography>
+        </button>
+      </div>
+
+      {searchQuery && (
+        <Typography
+          variant={TypographyVariant.B3_MD}
+          color={TypographyColor.TEXT_PRIMARY}
+          className={searchQueryHeadingClassName}
+        >
+          Results for &quot;{searchQuery}&quot;
+        </Typography>
+      )}
+
+      {/* Product grid */}
+      <div className={classNames('envive-tw-grid', gridClassName)}>
+        {products.map((product, index) => (
+          <SalesAgentProductCard
+            key={product.id ?? `product-${index}`}
+            variant={SalesAgentProductCardVariant.LARGE}
+            productName={product.productName}
+            currentPrice={product.currentPrice}
+            previousPrice={product.previousPrice}
+            pricePrefix={product.pricePrefix ?? '$'}
+            forceShowCurrentPriceSpace={forceShowCurrentPriceSpace}
+            rate={product.rate}
+            numberOfReviews={product.numberOfReviews}
+            image={product.image}
+            url={product.url}
+            target="_blank"
+            theme={finalTheme}
+            onClick={() => onProductCardClick?.(product)}
+          />
+        ))}
+      </div>
+    </Stack>
+  );
+};

package/src/components/FloatingChat/components/SlideChatContent.tsx

@@ -0,0 +1,80 @@
+import { AnimatePresence, motion } from 'framer-motion';
+import { Theme } from '../../../../tokens/theme/theme';
+import { SalesAgentProductCardProps } from '../../SalesAgentProductCard/types/types';
+import {
+  NUM_COLUMNS_MOBILE,
+  type ResultsGridColumnCount,
+  ResultsGridView,
+} from './ResultsGridView';
+import type { ResultsViewData } from '../hooks/useProductResultsView';
+
+type SlideChatContentProps = {
+  isResultsView: boolean;
+  isResultsViewRef: React.MutableRefObject<boolean>;
+  resultsViewData: ResultsViewData | null;
+  onBackToChat: () => void;
+  onProductCardClick: (product: SalesAgentProductCardProps) => void;
+  theme: Theme;
+  chatMessages: React.ReactNode;
+  scrollToBottom: () => void;
+  /** Column count for ResultsGridView; defaults to mobile (2). */
+  resultsGridColumns?: ResultsGridColumnCount;
+};
+
+const slideVariants = {
+  // Chat → Grid: chat exits left (-100%), grid enters from right (100%)
+  // Grid → Chat: grid exits right (100%), chat enters from left (-100%)
+  enter: (isResults: boolean) => ({ x: isResults ? '100%' : '-100%' }),
+  center: { x: 0 },
+  exit: (isResults: boolean) => ({ x: isResults ? '100%' : '-100%' }),
+};
+
+export const SlideChatContent = ({
+  isResultsView,
+  isResultsViewRef,
+  resultsViewData,
+  onBackToChat,
+  onProductCardClick,
+  theme,
+  chatMessages,
+  scrollToBottom,
+  resultsGridColumns = NUM_COLUMNS_MOBILE,
+}: SlideChatContentProps) => {
+  const resultsViewContent = resultsViewData && (
+    <ResultsGridView
+      theme={theme}
+      searchQuery={resultsViewData.searchQuery}
+      products={resultsViewData.products}
+      onBackToChat={onBackToChat}
+      onProductCardClick={onProductCardClick}
+      gridCols={resultsGridColumns}
+    />
+  );
+
+  return (
+    <div className="envive-tw-relative envive-tw-min-h-[200px] envive-tw-w-full envive-tw-overflow-hidden">
+      <AnimatePresence
+        initial={false}
+        mode="wait"
+      >
+        <motion.div
+          key={isResultsView ? 'results' : 'chat'}
+          custom={isResultsView}
+          variants={slideVariants}
+          initial="enter"
+          animate="center"
+          exit="exit"
+          transition={{ duration: 0.3, ease: 'easeInOut' }}
+          onAnimationComplete={() => {
+            if (!isResultsViewRef.current) {
+              scrollToBottom();
+            }
+          }}
+          className="envive-tw-w-full"
+        >
+          {isResultsView ? resultsViewContent : chatMessages}
+        </motion.div>
+      </AnimatePresence>
+    </div>
+  );
+};

package/src/components/FloatingChat/components/index.ts

@@ -1,4 +1,7 @@
 import { Layout } from './Layout';
+import { ResultsGridView } from './ResultsGridView';
+import { ProductResultsModal } from './ProductResultsModal';
+import { SlideChatContent } from './SlideChatContent';
 import { UserMessage } from './UserMessage';
 import { AgentMessage } from './AgentMessage';
 import { ChatMessages } from './ChatMessages';
@@ -11,6 +14,9 @@ import { MessageDivider } from './MessageDivider';
 
 export const FloatingChatComponents = {
   Layout,
+  ResultsGridView,
+  ProductResultsModal,
+  SlideChatContent,
   UserMessage,
   AgentMessage,
   ChatMessages,

package/src/components/FloatingChat/hooks/useProductResultsView.ts

@@ -0,0 +1,73 @@
+import { Message, MessageType } from '@envive-ai/react-hooks/application/models';
+import { useCallback, useEffect, useRef, useState } from 'react';
+import {
+  getCleanProducts,
+  getCleanProductsForResultsGrid,
+  getSearchQueryFromMessageBlock,
+} from '../utils/functions';
+
+export type ResultsViewData = {
+  products: ReturnType<typeof getCleanProducts>;
+  searchQuery: string;
+};
+
+type UseResultsViewProps = {
+  scrollToBottom: () => void;
+};
+
+export const useProductResultsView = ({ scrollToBottom }: UseResultsViewProps) => {
+  const [resultsViewData, setResultsViewData] = useState<ResultsViewData | null>(null);
+  const isResultsView = resultsViewData !== null;
+
+  const scrollContainerRef = useRef<HTMLDivElement>(null);
+  const isResultsViewRef = useRef(isResultsView);
+  isResultsViewRef.current = isResultsView;
+
+  const handleBackToChat = () => {
+    setResultsViewData(null);
+  };
+
+  const handleExploreAllResults = useCallback(
+    (firstProductMessageId: string, messages: Message[][]) => {
+      const blockIndex = messages.findIndex(block =>
+        block.some(msg => msg.type === MessageType.Product && msg.id === firstProductMessageId),
+      );
+      if (blockIndex < 0) return;
+
+      const messageBlock = messages[blockIndex];
+      const productMessages = messageBlock.filter(msg => msg.type === MessageType.Product);
+      const products = getCleanProductsForResultsGrid(productMessages);
+      if (products.length === 0) return;
+
+      const searchQuery = getSearchQueryFromMessageBlock(messages, blockIndex);
+      setResultsViewData({ products, searchQuery });
+    },
+    [],
+  );
+
+  // Scroll to top when navigating to results view
+  useEffect(() => {
+    if (isResultsView && scrollContainerRef.current) {
+      scrollContainerRef.current.scrollTo({ top: 0, behavior: 'smooth' });
+    }
+  }, [isResultsView]);
+
+  // Scroll to bottom when navigating back to chat
+  const prevIsResultsViewRef = useRef(isResultsView);
+  useEffect(() => {
+    if (prevIsResultsViewRef.current && !isResultsView) {
+      scrollToBottom();
+    }
+    prevIsResultsViewRef.current = isResultsView;
+  }, [isResultsView, scrollToBottom]);
+
+  return {
+    resultsViewData,
+    setResultsViewData,
+    isResultsView,
+    scrollContainerRef,
+    isResultsViewRef,
+    handleBackToChat,
+    handleExploreAllResults,
+  };
+};

package/src/components/FloatingChat/types/types.ts

@@ -69,4 +69,8 @@ export interface FloatingChatProps {
    * Debug bar to display in the chat.
    */
   debugBar?: React.ReactNode;
+  /**
+   * Updates whether the product results modal is open (desktop full-width grid view).
+   */
+  setIsResultsModalOpen?: (isOpen: boolean) => void;
 }

package/src/components/FloatingChat/utils/functions.ts

@@ -34,27 +34,42 @@ export const checkIfHideAgentName = (messages: Message[]) => {
   );
 };
 
+const mapProductMessageToCardProps = (msg: Message): SalesAgentProductCardProps | null => {
+  if (msg.type !== MessageType.Product) return null;
+  return {
+    id: msg.id,
+    productName: msg.metadata.title,
+    currentPrice: msg.metadata.salePrice,
+    previousPrice: msg.metadata.originalPrice,
+    pricePrefix: '$',
+    rate: msg.metadata.averageRating,
+    numberOfReviews: msg.metadata.numberReviews,
+    url: msg.metadata.url,
+    image: {
+      src: msg.metadata.imageUrl,
+      alt: `${msg.metadata.title} image`,
+    },
+  };
+};
+
+/** Product cards for carousels; excludes grid-only rows from the API (`isForGrid`). */
 export const getCleanProducts = (messages: Message[]) => {
-  const products: SalesAgentProductCardProps[] = messages.map(msg => {
-    if (msg.type === MessageType.Product && !msg.metadata.isForGrid) {
-      return {
-        productName: msg.metadata.title,
-        currentPrice: msg.metadata.salePrice,
-        previousPrice: msg.metadata.originalPrice,
-        pricePrefix: '$',
-        rate: msg.metadata.averageRating,
-        numberOfReviews: msg.metadata.numberReviews,
-        url: msg.metadata.url,
-        image: {
-          src: msg.metadata.imageUrl,
-          alt: `${msg.metadata.title} image`,
-        },
-      };
-    }
-    return null;
-  });
+  const cleanProducts = messages
+    .map(msg =>
+      msg.type === MessageType.Product && !msg.metadata.isForGrid
+        ? mapProductMessageToCardProps(msg)
+        : null,
+    )
+    .filter((p): p is SalesAgentProductCardProps => p !== null);
+  return cleanProducts;
+};
 
-  return products.filter(product => product !== null);
+/** All product rows in a turn, including `isForGrid`, for the full results grid. */
+export const getCleanProductsForResultsGrid = (messages: Message[]) => {
+  const productsForGrid = messages
+    .map(msg => (msg.type === MessageType.Product ? mapProductMessageToCardProps(msg) : null))
+    .filter((p): p is SalesAgentProductCardProps => p !== null);
+  return productsForGrid;
 };
 
 export const getCleanReviews = (messages: Message[]) => {
@@ -121,6 +136,28 @@ export const getCleanOrders = (messages: Message[]) => {
 
 export const MOST_RELEVANT_DISPLAY_LIMIT = 8;
 
+/**
+ * Extracts the search query from a message block (or previous blocks) that led to product results.
+ * Looks for QueryTyped (metadata.content) or SuggestionClicked (metadata.suggestionContent).
+ */
+export const getSearchQueryFromMessageBlock = (
+  messages: Message[][],
+  productBlockIndex: number,
+): string => {
+  for (let i = productBlockIndex; i >= 0; i -= 1) {
+    const block = messages[i];
+    const queryTyped = block.find(msg => msg.type === MessageType.QueryTyped);
+    if (queryTyped && 'content' in queryTyped.metadata) {
+      return (queryTyped.metadata as { content?: string }).content ?? '';
+    }
+    const suggestionClicked = block.find(msg => msg.type === MessageType.SuggestionClicked);
+    if (suggestionClicked && 'suggestionContent' in suggestionClicked.metadata) {
+      return (suggestionClicked.metadata as { suggestionContent?: string }).suggestionContent ?? '';
+    }
+  }
+  return '';
+};
+
 export const getProductCarouselDisplayInfo = <T>(
   products: T[],
   numberOfProducts?: number,

package/src/components/FloatingChat/utils/trackProductCardInteraction.ts

@@ -0,0 +1,26 @@
+import { EnviveMetricsEventName } from '@envive-ai/react-hooks/contexts/amplitudeContext';
+import {
+  type WidgetInteraction,
+  WidgetInteractionComponent,
+  WidgetInteractionType,
+} from '@envive-ai/react-hooks/hooks/WidgetInteraction/types';
+import type { SalesAgentProductCardProps } from '../../SalesAgentProductCard/types/types';
+
+export const trackProductCardClicked = (
+  trackWidgetInteraction: (props: WidgetInteraction) => void,
+  widget: WidgetInteractionComponent,
+  product: SalesAgentProductCardProps,
+) => {
+  trackWidgetInteraction({
+    eventName: EnviveMetricsEventName.WidgetInteraction,
+    trigger: {
+      widget,
+      widget_interaction: WidgetInteractionType.PRODUCT_CARD_CLICKED,
+      widget_interaction_data: {
+        product_card_clicked: {
+          product_id: product.id,
+        },
+      },
+    },
+  });
+};

package/src/components/FullPageSalesAgent/FullPageSalesAgent.tsx

@@ -13,7 +13,10 @@ import { ChatFooter } from '../ChatFooter';
 import { Disclaimer } from '../Disclaimer';
 import { FloatingChatComponents } from '../FloatingChat/components';
 import { useChatSuggestions } from '../FloatingChat/hooks/useChatSuggestions';
+import { useProductResultsView } from '../FloatingChat/hooks/useProductResultsView';
 import { useScrollToBottom } from '../FloatingChat/hooks/useScrollToBottom';
+import { trackProductCardClicked } from '../FloatingChat/utils/trackProductCardInteraction';
+import { SalesAgentProductCardProps } from '../SalesAgentProductCard/types/types';
 import { PromptButtonVariant } from '../PromptButton';
 import { PromptCarousel, PromptCarouselRows, usePromptCarouselAnalytics } from '../PromptCarousel';
 import { Theme } from '../Tokens';
@@ -24,6 +27,11 @@ import { useGetFooterStyles } from './hooks/useGetFooterStyles';
 import { useGetMessagesStyles } from './hooks/useGetMessagesStyles';
 import { useGetScrollContentStyles } from './hooks/useGetScrollContentStyles';
 import { useIsMobile } from './hooks/useIsMobile';
+import {
+  NUM_COLUMNS_FPSA,
+  NUM_COLUMNS_MOBILE,
+  ResultsGridColumnCount,
+} from '../FloatingChat/components/ResultsGridView';
 
 interface FullPageSalesAgentProps {
   theme?: Theme;
@@ -107,6 +115,15 @@ export const FullPageSalesAgent = ({
     ],
   });
 
+  const {
+    resultsViewData,
+    isResultsView,
+    scrollContainerRef,
+    isResultsViewRef,
+    handleBackToChat,
+    handleExploreAllResults,
+  } = useProductResultsView({ scrollToBottom });
+
   const handleScrollToBottom = () => {
     scrollToBottom();
     trackWidgetInteraction({
@@ -128,6 +145,14 @@ export const FullPageSalesAgent = ({
     });
   };
 
+  const handleProductCardClick = (product: SalesAgentProductCardProps) => {
+    trackProductCardClicked(
+      trackWidgetInteraction,
+      WidgetInteractionComponent.FULL_PAGE_SALES_AGENT,
+      product,
+    );
+  };
+
   const welcomeMessage = (
     <div className={messageContainerClasses}>
       <WelcomeMessage
@@ -165,6 +190,7 @@ export const FullPageSalesAgent = ({
 
         setAnswerSuggestions([]);
         setGeneralSuggestions([]);
+        handleBackToChat();
       }}
       onChange={setQuery}
       onSubmit={() => {
@@ -175,6 +201,7 @@ export const FullPageSalesAgent = ({
         });
         setAnswerSuggestions([]);
         setGeneralSuggestions([]);
+        handleBackToChat();
       }}
       onFocus={handleInputQueryFocus}
       parentWidget={WidgetInteractionComponent.FULL_PAGE_SALES_AGENT}
@@ -197,6 +224,25 @@ export const FullPageSalesAgent = ({
       showVerifiedBuyer={showVerifiedBuyer}
       onFormResponseSubmitted={onFormResponseSubmitted}
       parentWidget={WidgetInteractionComponent.FULL_PAGE_SALES_AGENT}
+      onExploreAllResults={firstProductMessageId =>
+        handleExploreAllResults(firstProductMessageId, messages)
+      }
+    />
+  );
+
+  const middleContent = (
+    <FloatingChatComponents.SlideChatContent
+      isResultsView={isResultsView}
+      isResultsViewRef={isResultsViewRef}
+      resultsViewData={resultsViewData}
+      onBackToChat={handleBackToChat}
+      onProductCardClick={handleProductCardClick}
+      theme={resolvedTheme}
+      chatMessages={chatMessages}
+      scrollToBottom={scrollToBottom}
+      resultsGridColumns={
+        (isMobile ? NUM_COLUMNS_MOBILE : NUM_COLUMNS_FPSA) as ResultsGridColumnCount
+      }
     />
   );
 
@@ -232,18 +278,21 @@ export const FullPageSalesAgent = ({
   return (
     <FullPageSAComponents.Layout
       theme={resolvedTheme}
-      welcomeMessage={welcomeMessage}
+      welcomeMessage={isResultsView ? null : welcomeMessage}
       footer={footer}
-      chatMessages={chatMessages}
-      answerSuggestions={showAnswerSuggestions ? answerSuggestionsComponent : undefined}
+      chatMessages={middleContent}
+      answerSuggestions={
+        showAnswerSuggestions && !isResultsView ? answerSuggestionsComponent : undefined
+      }
       scrollToBottomButton={
-        showScrollButton ? (
+        !isResultsView && showScrollButton ? (
           <FloatingChatComponents.ScrollToBottomButton onClick={handleScrollToBottom} />
         ) : undefined
       }
-      disclaimer={disclaimer}
+      disclaimer={isResultsView ? null : disclaimer}
       headerContainer={headerContainer}
       autoHeight={autoHeight}
+      scrollContainerRef={scrollContainerRef}
     />
   );
 };

package/src/components/FullPageSalesAgent/components/Layout.tsx

@@ -17,6 +17,8 @@ export interface LayoutProps {
   disclaimer?: React.ReactNode;
   headerContainer?: string;
   autoHeight?: boolean;
+  /** Scrollable content ref (e.g. scroll to top when opening product results grid) */
+  scrollContainerRef?: React.RefObject<HTMLDivElement | null>;
 }
 
 export const Layout = ({
@@ -29,6 +31,7 @@ export const Layout = ({
   disclaimer,
   headerContainer,
   autoHeight,
+  scrollContainerRef,
 }: LayoutProps) => {
   const hasWelcomeMessage = isValidElement(welcomeMessage);
   const hasAnswerSuggestions = isValidElement(answerSuggestions);
@@ -45,7 +48,10 @@ export const Layout = ({
       className={containerClasses}
       style={containerStyles}
     >
-      <div className={contentClasses}>
+      <div
+        ref={scrollContainerRef}
+        className={contentClasses}
+      >
         <Stack
           direction="column"
           justify="between"