@patternfly/chatbot 1.0.0

package/src/MessageBox/MessageBox.test.tsx

@@ -0,0 +1,316 @@
+import { createRef } from 'react';
+import { act, fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { MessageBox, MessageBoxHandle } from './MessageBox';
+import userEvent from '@testing-library/user-event';
+
+describe('MessageBox', () => {
+  beforeEach(() => {
+    jest.spyOn(window, 'requestAnimationFrame').mockImplementation((cb) => {
+      cb(0); // Immediately call the callback
+      return 0;
+    });
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  it('should render Message box', () => {
+    render(
+      <MessageBox>
+        <>Chatbot Messages</>
+      </MessageBox>
+    );
+    expect(screen.getByText('Chatbot Messages')).toBeTruthy();
+  });
+
+  it('should assign ref to Message box', () => {
+    const ref = createRef<MessageBoxHandle>();
+    render(
+      <MessageBox data-testid="message-box" ref={ref}>
+        <div>Test message content</div>
+      </MessageBox>
+    );
+
+    screen.getByText('Test message content');
+
+    expect(ref.current).not.toBeNull();
+    // should contain custom methods exposed by the ref
+    expect(typeof ref.current?.isSmartScrollActive).toBe('function');
+    expect(typeof ref.current?.scrollToTop).toBe('function');
+    expect(typeof ref.current?.scrollToBottom).toBe('function');
+    expect(ref.current?.isSmartScrollActive()).toBe(false);
+
+    expect(ref.current).toBeInstanceOf(HTMLDivElement);
+  });
+  it('should call onScrollToBottomClick when scroll to bottom button is clicked', async () => {
+    const spy = jest.fn();
+    render(
+      <MessageBox onScrollToBottomClick={spy}>
+        <div>Test message content</div>
+      </MessageBox>
+    );
+
+    // this forces button to show
+    const region = screen.getByRole('region');
+    Object.defineProperty(region, 'scrollHeight', { configurable: true, value: 1000 });
+    Object.defineProperty(region, 'clientHeight', { configurable: true, value: 500 });
+    Object.defineProperty(region, 'scrollTop', { configurable: true, value: 0 });
+    act(() => {
+      region.dispatchEvent(new Event('scroll'));
+    });
+
+    await waitFor(() => {
+      userEvent.click(screen.getByRole('button', { name: /Back to bottom/i }));
+      expect(spy).toHaveBeenCalled();
+    });
+  });
+  it('should call onScrollToTopClick when scroll to top button is clicked', async () => {
+    const spy = jest.fn();
+    render(
+      <MessageBox onScrollToTopClick={spy}>
+        <div>Test message content</div>
+      </MessageBox>
+    );
+
+    // this forces button to show
+    const region = screen.getByRole('region');
+    Object.defineProperty(region, 'scrollHeight', { configurable: true, value: 1000 });
+    Object.defineProperty(region, 'clientHeight', { configurable: true, value: 500 });
+    Object.defineProperty(region, 'scrollTop', {
+      configurable: true,
+      value: 500
+    });
+    act(() => {
+      region.dispatchEvent(new Event('scroll'));
+    });
+    await waitFor(() => {
+      userEvent.click(screen.getByRole('button', { name: /Back to top/i }));
+      expect(spy).toHaveBeenCalled();
+    });
+  });
+
+  it('should call user defined onWheel, onTouchMove and onTouchEnd handlers', async () => {
+    const ref = createRef<MessageBoxHandle>();
+    const onWheel = jest.fn();
+    const onTouchMove = jest.fn();
+    const onTouchEnd = jest.fn();
+
+    render(
+      <MessageBox ref={ref} enableSmartScroll onWheel={onWheel} onTouchMove={onTouchMove} onTouchEnd={onTouchEnd}>
+        <div>Test message content</div>
+      </MessageBox>
+    );
+
+    const element = ref.current!;
+    act(() => {
+      fireEvent.wheel(element, { deltaY: 10 });
+      fireEvent.touchMove(element, { touches: [{ clientY: 700 }] });
+      fireEvent.touchEnd(element);
+    });
+
+    expect(onWheel).toHaveBeenCalled();
+    expect(onTouchMove).toHaveBeenCalled();
+    expect(onTouchEnd).toHaveBeenCalled();
+  });
+
+  it('should scroll to the bottom when the method is called ', async () => {
+    const ref = createRef<MessageBoxHandle>();
+
+    render(
+      <MessageBox ref={ref} enableSmartScroll>
+        <div>Test message content</div>
+      </MessageBox>
+    );
+    const element = ref.current!;
+    const scrollSpy = jest.spyOn(element, 'scrollTo');
+
+    act(() => {
+      ref.current?.scrollToBottom();
+      ref.current?.scrollToBottom();
+      ref.current?.scrollToBottom();
+    });
+
+    expect(scrollSpy).toHaveBeenCalledWith({ top: element.scrollHeight, behavior: 'smooth' });
+    expect(ref.current?.isSmartScrollActive()).toBe(true);
+  });
+
+  it('should scroll to the top when the method is called ', async () => {
+    const ref = createRef<MessageBoxHandle>();
+
+    render(
+      <MessageBox ref={ref} enableSmartScroll>
+        <div>Test message content</div>
+      </MessageBox>
+    );
+    const element = ref.current!;
+    const scrollSpy = jest.spyOn(element, 'scrollTo');
+
+    act(() => {
+      ref.current?.scrollToTop();
+    });
+
+    expect(scrollSpy).toHaveBeenCalledWith({ top: 0, behavior: 'smooth' });
+    expect(ref.current?.isSmartScrollActive()).toBe(false);
+  });
+
+  it('should pause automatic scrolling when user scrolls up ', async () => {
+    const ref = createRef<MessageBoxHandle>();
+
+    render(
+      <MessageBox ref={ref} enableSmartScroll>
+        <div>Test message content</div>
+      </MessageBox>
+    );
+
+    expect(ref.current?.isSmartScrollActive()).toBe(true);
+
+    const element = ref.current!;
+
+    // Manually set scrollHeight and clientHeight for calculations
+    Object.defineProperty(element, 'scrollHeight', { configurable: true, value: 1000 });
+    Object.defineProperty(element, 'clientHeight', { configurable: true, value: 300 });
+
+    // Simulate scroll up by changing scrollTop
+    element.scrollTop = 200;
+    const scrollEvent = new Event('scroll', { bubbles: true });
+
+    act(() => {
+      element.dispatchEvent(scrollEvent);
+    });
+
+    expect(ref.current?.isSmartScrollActive()).toBe(false);
+  });
+
+  it('should resume automatic scrolling when user scrolls down to the bottom using scroll event', async () => {
+    jest.useFakeTimers();
+
+    const ref = createRef<MessageBoxHandle>();
+    render(
+      <MessageBox ref={ref} enableSmartScroll>
+        <div>Test message content</div>
+      </MessageBox>
+    );
+
+    const element = ref.current!;
+    // Manually set scrollHeight and clientHeight for calculations
+    Object.defineProperty(element, 'scrollHeight', { configurable: true, value: 1000 });
+    Object.defineProperty(element, 'clientHeight', { configurable: true, value: 300 });
+
+    // Simulate scroll up by changing scrollTop
+    element.scrollTop = 100;
+    const scrollEvent = new Event('scroll', { bubbles: true });
+
+    act(() => {
+      element.dispatchEvent(scrollEvent);
+    });
+
+    expect(ref.current?.isSmartScrollActive()).toBe(false);
+
+    act(() => {
+      // Simulate scroll down by changing scrollTop
+      element.scrollTop = 650; // scrollHeight - scrollTop - clientHeight - DELTA_DOWN (50) = 0
+      const scrollEvent = new Event('scroll', { bubbles: true });
+      element.dispatchEvent(scrollEvent);
+      jest.advanceTimersByTime(250);
+    });
+
+    expect(ref.current?.isSmartScrollActive()).toBe(true);
+    jest.useRealTimers();
+  });
+
+  it('should resume automatic scrolling when scrollToBottom method is used', async () => {
+    const ref = createRef<MessageBoxHandle>();
+    render(
+      <MessageBox ref={ref} enableSmartScroll>
+        <div>Test message content</div>
+      </MessageBox>
+    );
+
+    const element = ref.current!;
+    // Manually set scrollHeight and clientHeight for calculations
+    Object.defineProperty(element, 'scrollHeight', { configurable: true, value: 1000 });
+    Object.defineProperty(element, 'clientHeight', { configurable: true, value: 300 });
+
+    // Simulate scroll up by changing scrollTop
+    element.scrollTop = 100;
+    const scrollEvent = new Event('scroll', { bubbles: true });
+
+    act(() => {
+      element.dispatchEvent(scrollEvent);
+    });
+
+    expect(ref.current?.isSmartScrollActive()).toBe(false);
+
+    act(() => {
+      ref.current?.scrollToBottom({ resumeSmartScroll: true, behavior: 'auto' }); // resumes auto scroll and scrolls to bottom.
+    });
+
+    expect(ref.current?.isSmartScrollActive()).toBe(true);
+  });
+
+  it('should resume automatic scrolling when mouse wheel event is used', async () => {
+    const ref = createRef<MessageBoxHandle>();
+    render(
+      <MessageBox ref={ref} enableSmartScroll>
+        <div>Test message content</div>
+      </MessageBox>
+    );
+
+    const element = ref.current!;
+    // Manually set scrollHeight and clientHeight for calculations
+    Object.defineProperty(element, 'scrollHeight', { configurable: true, value: 1000 });
+    Object.defineProperty(element, 'clientHeight', { configurable: true, value: 300 });
+    Object.defineProperty(element, 'scrollTop', { configurable: true, value: 350 });
+
+    const scrollEvent = new Event('scroll', { bubbles: true });
+
+    act(() => {
+      element.dispatchEvent(scrollEvent);
+    });
+
+    expect(ref.current?.isSmartScrollActive()).toBe(false);
+
+    // Simulate mouse wheel event
+    act(() => {
+      Object.defineProperty(element, 'scrollTop', { configurable: true, value: 650 });
+      fireEvent.wheel(element, { deltaY: 10 });
+    });
+
+    expect(ref.current?.isSmartScrollActive()).toBe(true);
+  });
+
+  it('should resume automatic scrolling when user swipes up in touch screen', async () => {
+    const ref = createRef<MessageBoxHandle>();
+    render(
+      <MessageBox ref={ref} enableSmartScroll>
+        <div>Test message content</div>
+      </MessageBox>
+    );
+
+    const element = ref.current!;
+    // Manually set scrollHeight and clientHeight for calculations
+    Object.defineProperty(element, 'scrollHeight', { configurable: true, value: 1000 });
+    Object.defineProperty(element, 'clientHeight', { configurable: true, value: 300 });
+    Object.defineProperty(element, 'scrollTop', { configurable: true, value: 350 });
+
+    const scrollEvent = new Event('scroll', { bubbles: true });
+
+    act(() => {
+      element.dispatchEvent(scrollEvent);
+    });
+
+    expect(ref.current?.isSmartScrollActive()).toBe(false);
+
+    // Simulate touch event - swipe up
+    act(() => {
+      Object.defineProperty(element, 'scrollTop', { configurable: true, value: 650 });
+      fireEvent.touchStart(element, { touches: [{ clientY: 700 }] });
+      fireEvent.touchMove(element, { touches: [{ clientY: 700 }] });
+      fireEvent.touchMove(element, { touches: [{ clientY: 600 }] });
+      fireEvent.touchEnd(element);
+    });
+
+    expect(ref.current?.isSmartScrollActive()).toBe(true);
+  });
+});

package/src/MessageBox/MessageBox.tsx

@@ -0,0 +1,354 @@
+// ============================================================================
+// Chatbot Main - Messages
+// ============================================================================
+
+import {
+  HTMLProps,
+  useState,
+  useRef,
+  useCallback,
+  useEffect,
+  forwardRef,
+  ForwardedRef,
+  useImperativeHandle,
+  ReactNode,
+  TouchEventHandler,
+  TouchEvent,
+  WheelEvent,
+  WheelEventHandler
+} from 'react';
+import JumpButton from './JumpButton';
+import { ButtonProps, TooltipProps } from '@patternfly/react-core';
+
+export interface MessageBoxProps extends HTMLProps<HTMLDivElement> {
+  /** Content that can be announced, such as a new message, for screen readers */
+  announcement?: string;
+  /** Custom aria-label for scrollable portion of message box */
+  ariaLabel?: string;
+  /** Content to be displayed in the message box */
+  children: ReactNode;
+  /** Custom classname for the MessageBox component */
+  className?: string;
+  /** @deprecated innerRef has been deprecated. Use ref instead. Ref applied to message box  */
+  innerRef?: React.Ref<HTMLDivElement>;
+  /** Modifier that controls how content in MessageBox is positioned within the container */
+  position?: 'top' | 'bottom';
+  /** Click handler for additional logic for when scroll to top jump button is clicked */
+  onScrollToTopClick?: () => void;
+  /** Click handler for additional logic for when scroll to bottom jump button is clicked */
+  onScrollToBottomClick?: () => void;
+  /** Flag to enable automatic scrolling when new messages are added */
+  enableSmartScroll?: boolean;
+  /** Props passed to top jump button */
+  jumpButtonTopProps?: ButtonProps;
+  /** Props passed to bottom jump button */
+  jumpButtonBottomProps?: ButtonProps;
+  /** Props passed to top jump button tooltip */
+  jumpButtonTopTooltipProps?: TooltipProps;
+  /** Props passed to top jump button tooltip */
+  jumpButtonBottomTooltipProps?: TooltipProps;
+}
+
+export interface MessageBoxHandle extends HTMLDivElement {
+  /** Scrolls to the top of the message box */
+  scrollToTop: (options?: ScrollOptions) => void;
+  /** Scrolls to the bottom of the message box */
+  scrollToBottom: (options?: { resumeSmartScroll?: boolean } & ScrollOptions) => void;
+  /** Returns whether the smart scroll feature is currently active */
+  isSmartScrollActive: () => boolean;
+}
+
+export const MessageBox = forwardRef(
+  (
+    {
+      announcement,
+      ariaLabel = 'Scrollable message log',
+      children,
+      className,
+      position = 'top',
+      onScrollToTopClick,
+      onScrollToBottomClick,
+      enableSmartScroll = false,
+      jumpButtonTopProps,
+      jumpButtonBottomProps,
+      jumpButtonBottomTooltipProps,
+      jumpButtonTopTooltipProps,
+      ...props
+    }: MessageBoxProps,
+    ref: ForwardedRef<MessageBoxHandle | null>
+  ) => {
+    const [atTop, setAtTop] = useState(false);
+    const [atBottom, setAtBottom] = useState(true);
+    const [isOverflowing, setIsOverflowing] = useState(false);
+    const [autoScroll, setAutoScroll] = useState(true);
+    const lastScrollTop = useRef(0);
+    const animationFrame = useRef<any>(null);
+    const debounceTimeout = useRef<NodeJS.Timeout | null>(null);
+    const pauseAutoScrollRef = useRef(false);
+    const messageBoxRef = useRef<HTMLDivElement>(null);
+    const scrollQueued = useRef(false);
+    const resetUserScrollIntentTimeout = useRef<NodeJS.Timeout>();
+
+    // Configure handlers
+    const handleScroll = useCallback(() => {
+      const element = messageBoxRef.current;
+      if (!element) {
+        return;
+      }
+
+      const { scrollTop, scrollHeight, clientHeight } = element;
+
+      const roundedScrollTop = Math.round(scrollTop);
+      const roundedClientHeight = Math.round(clientHeight);
+      const roundedScrollHeight = Math.round(scrollHeight);
+
+      const distanceFromBottom = roundedScrollHeight - roundedScrollTop - roundedClientHeight;
+      const isScrollingDown = roundedScrollTop > lastScrollTop.current;
+
+      const DELTA_UP = 10;
+      const DELTA_DOWN = 50;
+      const DEBOUNCE_DELAY = 200;
+
+      const delta = isScrollingDown ? DELTA_DOWN : DELTA_UP;
+      const isAtBottom = distanceFromBottom <= delta;
+
+      setAtTop(roundedScrollTop === 0);
+      setAtBottom(roundedScrollTop + roundedClientHeight >= roundedScrollHeight - 1); // rounding means it could be within a pixel of the bottom
+
+      if (!enableSmartScroll || scrollQueued.current) {
+        return;
+      }
+
+      if (roundedScrollTop === 0) {
+        pauseAutoScrollRef.current = false;
+      }
+
+      if (debounceTimeout.current) {
+        clearTimeout(debounceTimeout.current);
+      }
+
+      if (!isAtBottom && !pauseAutoScrollRef.current) {
+        setAutoScroll(false);
+      }
+
+      // User is near bottom and scrolling down - debounce re-enabling auto-scroll
+      if (isAtBottom && isScrollingDown && !pauseAutoScrollRef.current) {
+        debounceTimeout.current = setTimeout(() => {
+          setAutoScroll(true);
+        }, DEBOUNCE_DELAY);
+      }
+
+      lastScrollTop.current = roundedScrollTop;
+    }, [messageBoxRef]);
+
+    const checkOverflow = useCallback(() => {
+      const element = messageBoxRef.current;
+      if (element) {
+        const { scrollHeight, clientHeight } = element;
+        setIsOverflowing(scrollHeight >= clientHeight);
+      }
+    }, [messageBoxRef]);
+
+    const resumeAutoScroll = useCallback(() => {
+      if (!enableSmartScroll) {
+        return;
+      }
+      pauseAutoScrollRef.current = false;
+      setAutoScroll(true);
+    }, [enableSmartScroll]);
+
+    const pauseAutoScroll = useCallback(() => {
+      if (!enableSmartScroll) {
+        return;
+      }
+      pauseAutoScrollRef.current = true;
+      setAutoScroll(false);
+    }, [enableSmartScroll]);
+    /**
+     * Scrolls to the top of the message box.
+     *
+     */
+    const scrollToTop = useCallback(
+      (options?: ScrollOptions) => {
+        const { behavior = 'smooth' } = options || {};
+
+        const element = messageBoxRef.current;
+
+        if (!element || scrollQueued.current) {
+          return;
+        }
+
+        scrollQueued.current = true;
+        pauseAutoScroll();
+
+        if (animationFrame.current) {
+          cancelAnimationFrame(animationFrame.current);
+          animationFrame.current = null;
+        }
+
+        animationFrame.current = requestAnimationFrame(() => {
+          element.scrollTo({ top: 0, behavior });
+          scrollQueued.current = false;
+        });
+        onScrollToTopClick && onScrollToTopClick();
+      },
+      [messageBoxRef]
+    );
+
+    /**
+     * Scrolls to the bottom of the message box.
+     *
+     * @param options.resumeSmartScroll - If true, resumes smart scroll behavior;
+     *                                    if false or omitted, scrolls without resuming auto-scroll.
+     * @param options.scrollOptions - Additional scroll options. behavior can be 'smooth' or 'auto'.
+     */
+    const scrollToBottom = useCallback(
+      (options?: { resumeSmartScroll?: boolean } & ScrollOptions) => {
+        const { behavior = 'smooth', resumeSmartScroll = false } = options || {};
+        resumeSmartScroll && resumeAutoScroll();
+
+        const element = messageBoxRef.current;
+        if (!element || pauseAutoScrollRef.current || scrollQueued.current) {
+          return;
+        }
+
+        scrollQueued.current = true;
+
+        if (animationFrame.current) {
+          cancelAnimationFrame(animationFrame.current);
+        }
+
+        animationFrame.current = requestAnimationFrame(() => {
+          element.scrollTo({ top: element.scrollHeight, behavior });
+          resumeAutoScroll();
+          scrollQueued.current = false;
+        });
+        onScrollToBottomClick && onScrollToBottomClick();
+      },
+      [messageBoxRef, enableSmartScroll]
+    );
+
+    // Detect scroll position
+    useEffect(() => {
+      const element = messageBoxRef.current;
+      if (!element) {
+        return;
+      }
+
+      // Listen for scroll events
+      element.addEventListener('scroll', handleScroll);
+
+      // Check initial position and overflow
+      handleScroll();
+      checkOverflow();
+
+      return () => {
+        element.removeEventListener('scroll', handleScroll);
+      };
+    }, [checkOverflow, handleScroll, messageBoxRef]);
+
+    useImperativeHandle(ref, (): MessageBoxHandle => {
+      const node = messageBoxRef.current! as MessageBoxHandle;
+
+      // Attach custom methods to the element
+      node.scrollToTop = scrollToTop;
+      node.scrollToBottom = scrollToBottom;
+      node.isSmartScrollActive = () => enableSmartScroll && autoScroll;
+
+      return node;
+    });
+
+    let lastTouchY: number | null = null;
+
+    const onTouchEnd: TouchEventHandler<HTMLDivElement> = (event: TouchEvent<HTMLDivElement>) => {
+      lastTouchY = null;
+      props.onTouchEnd && props.onTouchEnd(event);
+    };
+
+    const handleUserScroll = (isScrollingDown: boolean) => {
+      const container = messageBoxRef.current;
+      if (!enableSmartScroll || !container) {
+        return;
+      }
+
+      if (!isScrollingDown) {
+        pauseAutoScrollRef.current = true;
+        clearTimeout(resetUserScrollIntentTimeout.current);
+        return;
+      }
+
+      const { scrollTop, scrollHeight, clientHeight } = container;
+      const distanceFromBottom = scrollHeight - scrollTop - clientHeight;
+
+      if (distanceFromBottom < 100) {
+        pauseAutoScrollRef.current = false;
+        setAutoScroll(true);
+      }
+    };
+
+    const onWheel = (event: WheelEvent<HTMLDivElement>) => {
+      const isScrollingDown = event.deltaY > 0;
+      handleUserScroll(isScrollingDown);
+      props.onWheel && props.onWheel(event);
+    };
+
+    const onTouchMove = (event: TouchEvent<HTMLDivElement>) => {
+      const currentTouchY = event.touches[0].clientY;
+      let isScrollingDown = false;
+
+      if (lastTouchY !== null) {
+        isScrollingDown = currentTouchY < lastTouchY;
+      }
+
+      lastTouchY = currentTouchY;
+
+      handleUserScroll(isScrollingDown);
+      props.onTouchMove && props.onTouchMove(event);
+    };
+
+    const smartScrollHandlers: {
+      onWheel: WheelEventHandler<HTMLDivElement>;
+      onTouchMove: TouchEventHandler<HTMLDivElement>;
+      onTouchEnd: TouchEventHandler<HTMLDivElement>;
+    } = {
+      onWheel,
+      onTouchMove,
+      onTouchEnd
+    };
+
+    return (
+      <>
+        <JumpButton
+          position="top"
+          isHidden={isOverflowing && atTop}
+          onClick={scrollToTop}
+          jumpButtonProps={jumpButtonTopProps}
+          jumpButtonTooltipProps={jumpButtonTopTooltipProps}
+        />
+        <div
+          role="region"
+          tabIndex={0}
+          aria-label={ariaLabel}
+          className={`pf-chatbot__messagebox ${position === 'bottom' ? 'pf-chatbot__messagebox--bottom' : ''} ${className ?? ''}`}
+          ref={messageBoxRef}
+          {...props}
+          {...(enableSmartScroll ? { ...smartScrollHandlers } : {})}
+        >
+          {children}
+          <div className="pf-chatbot__messagebox-announcement pf-chatbot-m-hidden" aria-live="polite">
+            {announcement}
+          </div>
+        </div>
+        <JumpButton
+          position="bottom"
+          isHidden={isOverflowing && atBottom}
+          onClick={() => scrollToBottom({ resumeSmartScroll: true })}
+          jumpButtonProps={jumpButtonBottomProps}
+          jumpButtonTooltipProps={jumpButtonBottomTooltipProps}
+        />
+      </>
+    );
+  }
+);
+
+export default MessageBox;

package/src/MessageBox/index.ts

@@ -0,0 +1,4 @@
+export { default } from './MessageBox';
+
+export * from './MessageBox';
+export * from './JumpButton';