@carto/ps-react-ui 4.4.0-chat-ui.5 → 4.4.0-chat-ui.7

package/src/chat/containers/chat-content.test.tsx

@@ -1,15 +1,269 @@
-import { describe, test, expect } from 'vitest'
-import { render, screen } from '@testing-library/react'
+import {
+  describe,
+  test,
+  expect,
+  vi,
+  beforeEach,
+  afterEach,
+  type MockInstance,
+} from 'vitest'
+import { createRef } from 'react'
+import { act, render, screen } from '@testing-library/react'
 import { ChatContent } from './chat-content'
+import type { ChatContentRef } from '../types'
+
+type IOCallback = (entries: IntersectionObserverEntry[]) => void
+
+interface FakeObserver {
+  callback: IOCallback
+  observed: Element[]
+  disconnected: boolean
+}
+
+interface FakeMutationObserverInstance {
+  callback: MutationCallback
+  target: Node | null
+  disconnected: boolean
+}
+
+let observers: FakeObserver[] = []
+let mutationObservers: FakeMutationObserverInstance[] = []
+let scrollToSpy: MockInstance<Element['scrollTo']>
+
+// Mutable "DOM measurements" the prototype getters read from.
+let scrollHeightValue = 0
+let scrollTopValue = 0
+let clientHeightValue = 0
+
+class FakeIntersectionObserver {
+  _obs: FakeObserver
+  constructor(cb: IOCallback) {
+    this._obs = { callback: cb, observed: [], disconnected: false }
+    observers.push(this._obs)
+  }
+  observe(el: Element) {
+    this._obs.observed.push(el)
+  }
+  unobserve() {
+    // NOOP
+  }
+  disconnect() {
+    this._obs.disconnected = true
+  }
+  takeRecords(): IntersectionObserverEntry[] {
+    return []
+  }
+}
+
+class FakeMutationObserver {
+  _inst: FakeMutationObserverInstance
+  constructor(cb: MutationCallback) {
+    this._inst = { callback: cb, target: null, disconnected: false }
+    mutationObservers.push(this._inst)
+  }
+  observe(target: Node) {
+    this._inst.target = target
+  }
+  disconnect() {
+    this._inst.disconnected = true
+  }
+  takeRecords(): MutationRecord[] {
+    return []
+  }
+}
+
+/**
+ * The component creates the top observer first, then the bottom one — so
+ * `observers[0]` is top and `observers[1]` is bottom. Helper trips one of them.
+ */
+function fireIntersection(index: 0 | 1, isIntersecting: boolean) {
+  const obs = observers[index]
+  if (!obs) throw new Error(`No observer at index ${index}`)
+  act(() => {
+    obs.callback([
+      { isIntersecting, target: obs.observed[0]! } as IntersectionObserverEntry,
+    ])
+  })
+}
+
+/** Triggers the most recent MutationObserver as if a DOM mutation happened. */
+function fireMutation() {
+  const obs = mutationObservers.at(-1)
+  if (!obs) throw new Error('No MutationObserver registered')
+  act(() => {
+    obs.callback([], obs as unknown as MutationObserver)
+  })
+}
 
 describe('ChatContent', () => {
+  beforeEach(() => {
+    observers = []
+    mutationObservers = []
+    scrollHeightValue = 0
+    scrollTopValue = 0
+    clientHeightValue = 0
+    vi.stubGlobal('IntersectionObserver', FakeIntersectionObserver)
+    vi.stubGlobal('MutationObserver', FakeMutationObserver)
+    // Run rAF synchronously so MutationObserver-driven scroll checks happen
+    // inside `act`.
+    vi.stubGlobal('requestAnimationFrame', (cb: FrameRequestCallback) => {
+      cb(0)
+      return 1
+    })
+    vi.stubGlobal('cancelAnimationFrame', () => {
+      // NOOP
+    })
+    scrollToSpy = vi
+      .spyOn(Element.prototype, 'scrollTo')
+      .mockImplementation(() => {
+        // NOOP
+      })
+    vi.spyOn(HTMLElement.prototype, 'scrollHeight', 'get').mockImplementation(
+      () => scrollHeightValue,
+    )
+    vi.spyOn(HTMLElement.prototype, 'scrollTop', 'get').mockImplementation(
+      () => scrollTopValue,
+    )
+    vi.spyOn(HTMLElement.prototype, 'clientHeight', 'get').mockImplementation(
+      () => clientHeightValue,
+    )
+  })
+
+  afterEach(() => {
+    vi.unstubAllGlobals()
+    vi.restoreAllMocks()
+  })
+
   test('renders children', () => {
     render(<ChatContent>Scrollable content</ChatContent>)
     expect(screen.getByText('Scrollable content')).toBeTruthy()
   })
 
-  // TODO: Test scroll behaviour - verify "Jump to latest" button appears
-  // when user scrolls up and disappears when scrolled to bottom.
-  // This requires mocking scroll container dimensions and dispatching
-  // scroll events with appropriate scrollHeight/scrollTop values.
+  test('observes the top and bottom sentinels', () => {
+    render(<ChatContent>content</ChatContent>)
+    expect(observers).toHaveLength(2)
+    expect(observers[0]?.observed).toHaveLength(1)
+    expect(observers[1]?.observed).toHaveLength(1)
+  })
+
+  test('ref starts with isAtTop and isAtBottom both true', () => {
+    const ref = createRef<ChatContentRef>()
+    render(<ChatContent ref={ref}>content</ChatContent>)
+    expect(ref.current?.isAtTop).toBe(true)
+    expect(ref.current?.isAtBottom).toBe(true)
+  })
+
+  test('isAtBottom flips when the bottom sentinel leaves the viewport', () => {
+    const ref = createRef<ChatContentRef>()
+    render(<ChatContent ref={ref}>content</ChatContent>)
+    fireIntersection(1, false)
+    expect(ref.current?.isAtBottom).toBe(false)
+    fireIntersection(1, true)
+    expect(ref.current?.isAtBottom).toBe(true)
+  })
+
+  test('isAtTop flips when the top sentinel leaves the viewport', () => {
+    const ref = createRef<ChatContentRef>()
+    render(<ChatContent ref={ref}>content</ChatContent>)
+    fireIntersection(0, false)
+    expect(ref.current?.isAtTop).toBe(false)
+    fireIntersection(0, true)
+    expect(ref.current?.isAtTop).toBe(true)
+  })
+
+  test('scrollToBottom() scrolls to scrollHeight with smooth behaviour', () => {
+    scrollHeightValue = 1000
+    const ref = createRef<ChatContentRef>()
+    render(<ChatContent ref={ref}>content</ChatContent>)
+    act(() => ref.current?.scrollToBottom())
+    expect(scrollToSpy).toHaveBeenCalledWith({
+      top: 1000,
+      behavior: 'smooth',
+    })
+  })
+
+  test('scrollToTop() scrolls the container to top 0', () => {
+    const ref = createRef<ChatContentRef>()
+    render(<ChatContent ref={ref}>content</ChatContent>)
+    act(() => ref.current?.scrollToTop())
+    expect(scrollToSpy).toHaveBeenCalledWith({
+      top: 0,
+      behavior: 'smooth',
+    })
+  })
+
+  test('clicking the jump-to-latest FAB scrolls to the bottom', () => {
+    render(<ChatContent>content</ChatContent>)
+    fireIntersection(1, false) // not at bottom anymore
+    const fab = screen.getByLabelText('Jump to latest')
+    act(() => fab.click())
+    expect(scrollToSpy).toHaveBeenCalled()
+  })
+
+  test('uses custom jumpToLatest label', () => {
+    render(
+      <ChatContent labels={{ jumpToLatest: 'Ir al final' }}>x</ChatContent>,
+    )
+    expect(screen.getByLabelText('Ir al final')).toBeTruthy()
+  })
+
+  test('disconnects observers on unmount', () => {
+    const { unmount } = render(<ChatContent>content</ChatContent>)
+    unmount()
+    expect(observers[0]?.disconnected).toBe(true)
+    expect(observers[1]?.disconnected).toBe(true)
+  })
+
+  describe('autoScroll', () => {
+    test('attaches a MutationObserver by default', () => {
+      render(<ChatContent>content</ChatContent>)
+      expect(mutationObservers).toHaveLength(1)
+    })
+
+    test('does not attach a MutationObserver when autoScroll={false}', () => {
+      render(<ChatContent autoScroll={false}>content</ChatContent>)
+      expect(mutationObservers).toHaveLength(0)
+    })
+
+    test('scrolls to the new bottom when content grows and the user is at the bottom', () => {
+      // At-bottom: scrollHeight - scrollTop - clientHeight = 0
+      scrollHeightValue = 1000
+      clientHeightValue = 500
+      scrollTopValue = 500
+
+      render(<ChatContent autoScroll>content</ChatContent>)
+      expect(mutationObservers).toHaveLength(1)
+
+      // Content grows by 200px while the user is still at the bottom.
+      scrollHeightValue = 1200
+      fireMutation()
+
+      expect(scrollToSpy).toHaveBeenCalledWith({
+        top: 1200,
+        behavior: 'smooth',
+      })
+    })
+
+    test('does NOT scroll when the user has scrolled up to read history', () => {
+      // 400px from the bottom: 1000 - 100 - 500 = 400 (well past the 32px slack)
+      scrollHeightValue = 1000
+      clientHeightValue = 500
+      scrollTopValue = 100
+
+      render(<ChatContent autoScroll>content</ChatContent>)
+
+      // Content grows by 200px — distance-from-bottom is now 600, growth is
+      // 200, so 600 > 200 + 32 → leave the user alone.
+      scrollHeightValue = 1200
+      fireMutation()
+
+      expect(scrollToSpy).not.toHaveBeenCalled()
+    })
+
+    test('disconnects the MutationObserver on unmount', () => {
+      const { unmount } = render(<ChatContent autoScroll>content</ChatContent>)
+      unmount()
+      expect(mutationObservers[0]?.disconnected).toBe(true)
+    })
+  })
 })

package/src/chat/containers/chat-content.tsx

@@ -1,32 +1,142 @@
-import { useRef } from 'react'
+import {
+  forwardRef,
+  useEffect,
+  useImperativeHandle,
+  useRef,
+  useState,
+} from 'react'
 import { Box, Fab } from '@mui/material'
 import { KeyboardArrowDown } from '@mui/icons-material'
-import type { ChatContentProps } from '../types'
+import type { ChatContentProps, ChatContentRef } from '../types'
 import { styles } from './styles'
 
-export function ChatContent({ children, labels = {}, sx }: ChatContentProps) {
-  const scrollRef = useRef<HTMLDivElement>(null)
-
-  const scrollToBottom = () => {
-    scrollRef.current?.scrollTo({
-      top: scrollRef.current.scrollHeight,
-      behavior: 'smooth',
-    })
-  }
-
-  return (
-    <Box ref={scrollRef} sx={{ ...styles.content, ...sx }}>
-      {children}
-      <Box sx={styles.jumpToLatestWrapper}>
-        <Fab
-          size='small'
-          onClick={scrollToBottom}
-          aria-label={labels.jumpToLatest ?? 'Jump to latest'}
-          sx={styles.jumpToLatest}
-        >
-          <KeyboardArrowDown />
-        </Fab>
+/** Slack in px for treating the user as "at the bottom" when content grows. */
+const AUTO_SCROLL_THRESHOLD = 32
+
+export const ChatContent = forwardRef<ChatContentRef, ChatContentProps>(
+  function ChatContent({ children, autoScroll = true, labels = {}, sx }, ref) {
+    const scrollRef = useRef<HTMLDivElement>(null)
+    const topSentinelRef = useRef<HTMLDivElement>(null)
+    const bottomSentinelRef = useRef<HTMLDivElement>(null)
+
+    const [isAtTop, setIsAtTop] = useState(true)
+    const [isAtBottom, setIsAtBottom] = useState(true)
+
+    const scrollToBottom = () => {
+      scrollRef.current?.scrollTo({
+        top: scrollRef.current.scrollHeight,
+        behavior: 'smooth',
+      })
+    }
+
+    const scrollToTop = () => {
+      scrollRef.current?.scrollTo({ top: 0, behavior: 'smooth' })
+    }
+
+    useImperativeHandle(
+      ref,
+      () => ({ scrollToBottom, scrollToTop, isAtBottom, isAtTop }),
+      [isAtBottom, isAtTop],
+    )
+
+    useEffect(() => {
+      const root = scrollRef.current
+      const topEl = topSentinelRef.current
+      const bottomEl = bottomSentinelRef.current
+      if (!root || !topEl || !bottomEl) return
+
+      const topObserver = new IntersectionObserver(
+        ([entry]) => setIsAtTop(entry?.isIntersecting ?? true),
+        { root },
+      )
+      const bottomObserver = new IntersectionObserver(
+        ([entry]) => setIsAtBottom(entry?.isIntersecting ?? true),
+        { root },
+      )
+      topObserver.observe(topEl)
+      bottomObserver.observe(bottomEl)
+      return () => {
+        topObserver.disconnect()
+        bottomObserver.disconnect()
+      }
+    }, [])
+
+    useEffect(() => {
+      if (!autoScroll) return
+      const root = scrollRef.current
+      if (!root) return
+
+      // We can't watch `children` to detect new content: tool traces and
+      // `useTypewriter` live inside child components and update via local
+      // state, so they mutate the DOM without re-rendering `ChatContent`.
+      // MutationObserver picks up every DOM change regardless of source.
+      let prevScrollHeight = root.scrollHeight
+      let rafId: number | null = null
+
+      const check = () => {
+        rafId = null
+        const newScrollHeight = root.scrollHeight
+        if (newScrollHeight > prevScrollHeight) {
+          const growth = newScrollHeight - prevScrollHeight
+          // If the distance from the bottom doesn't exceed the amount the
+          // content just grew (plus a small slack), the user was at the
+          // bottom *before* the growth — scroll them to the new bottom.
+          // Otherwise they've scrolled up to read history and we leave them
+          // alone.
+          const distanceFromBottom =
+            newScrollHeight - root.scrollTop - root.clientHeight
+          if (distanceFromBottom <= growth + AUTO_SCROLL_THRESHOLD) {
+            root.scrollTo({ top: newScrollHeight, behavior: 'smooth' })
+          }
+        }
+        prevScrollHeight = newScrollHeight
+      }
+
+      const mo = new MutationObserver(() => {
+        rafId ??= requestAnimationFrame(check)
+      })
+      mo.observe(root, {
+        childList: true,
+        subtree: true,
+        characterData: true,
+      })
+      return () => {
+        mo.disconnect()
+        if (rafId !== null) cancelAnimationFrame(rafId)
+      }
+    }, [autoScroll])
+
+    return (
+      <Box
+        ref={scrollRef}
+        sx={{
+          ...styles.content,
+          borderTopColor: ({ palette }) =>
+            isAtTop ? 'transparent' : palette.divider,
+          borderBottomColor: ({ palette }) =>
+            isAtBottom ? 'transparent' : palette.divider,
+          ...sx,
+        }}
+      >
+        <Box ref={topSentinelRef} sx={styles.sentinel} aria-hidden />
+        {children}
+        <Box ref={bottomSentinelRef} sx={styles.sentinel} aria-hidden />
+        <Box sx={styles.jumpToLatestWrapper}>
+          <Fab
+            size='small'
+            onClick={scrollToBottom}
+            aria-label={labels.jumpToLatest ?? 'Jump to latest'}
+            sx={{
+              ...styles.jumpToLatest,
+              opacity: isAtBottom ? 0 : 1,
+              pointerEvents: isAtBottom ? 'none' : 'auto',
+            }}
+          >
+            <KeyboardArrowDown />
+          </Fab>
+        </Box>
       </Box>
-    </Box>
-  )
-}
+    )
+  },
+)
+ChatContent.displayName = 'ChatContent'

package/src/chat/containers/chat-starter.tsx

@@ -61,9 +61,9 @@ export function ChatStarter({
           ...(items.length > 2 ? styles.starterItemsTwoCol : undefined),
         }}
       >
-        {fullItems.map((item) => (
+        {fullItems.map((item, i) => (
           <ChatSuggestionButton
-            key={item.label}
+            key={i}
             label={item.label}
             onClick={() => onSelect?.(item.label)}
             color={item.color}

package/src/chat/containers/styles.ts

@@ -1,20 +1,6 @@
 import type { SxProps, Theme } from '@mui/material'
-import { keyframes } from '@mui/material/styles'
 import { CHAT_MAX_WIDTH } from '../const'
 
-const scrollBorders = keyframes`
-  0%     { border-top-color: transparent;                border-bottom-color: var(--chat-border-color) }
-  0.1%   { border-top-color: var(--chat-border-color);   border-bottom-color: var(--chat-border-color) }
-  99.9%  { border-top-color: var(--chat-border-color);   border-bottom-color: var(--chat-border-color) }
-  100%   { border-top-color: var(--chat-border-color);   border-bottom-color: transparent }
-`
-
-const showFab = keyframes`
-  0%   { opacity: 1; pointer-events: auto }
-  95%  { opacity: 1; pointer-events: auto }
-  100% { opacity: 0; pointer-events: none }
-`
-
 export const styles = {
   header: {
     display: 'flex',
@@ -45,12 +31,13 @@ export const styles = {
   footer: {
     maxWidth: CHAT_MAX_WIDTH,
     margin: '0 auto',
-    '& .MuiInputBase-multiline.MuiInputBase-sizeSmall textarea': {
-      resize: 'none',
-      maxHeight: '10em',
-      overflowY: 'auto !important',
-      paddingRight: ({ spacing }) => spacing(5),
-    },
+    '&.MuiFilledInput-root.MuiInputBase-multiline.MuiInputBase-sizeSmall textarea':
+      {
+        resize: 'none',
+        maxHeight: '10em',
+        overflowY: 'auto !important',
+        paddingRight: ({ spacing }) => spacing(5),
+      },
   },
   footerCaption: {
     textAlign: 'center',
@@ -68,13 +55,14 @@ export const styles = {
     px: 2,
     display: 'flex',
     flexDirection: 'column',
-    '--chat-border-color': ({ palette }) => palette.divider,
-    borderTop: '1px solid transparent',
-    borderBottom: '1px solid transparent',
-    '@supports (animation-timeline: scroll())': {
-      animation: `${scrollBorders} linear both`,
-      animationTimeline: 'scroll(self)',
-    },
+    borderTopWidth: '1px',
+    borderTopStyle: 'solid',
+    borderBottomWidth: '1px',
+    borderBottomStyle: 'solid',
+  },
+  sentinel: {
+    height: '1px',
+    flexShrink: 0,
   },
   jumpToLatestWrapper: {
     position: 'sticky',
@@ -85,15 +73,7 @@ export const styles = {
     zIndex: 1,
   },
   jumpToLatest: {
-    opacity: 0,
-    pointerEvents: 'none',
-    '@supports (animation-timeline: scroll())': {
-      animation: `${showFab} linear both`,
-      animationTimeline: 'scroll(nearest)',
-    },
-    '@supports not (animation-timeline: scroll())': {
-      display: 'none',
-    },
+    transition: 'opacity 0.2s',
   },
   starter: {
     display: 'flex',

package/src/chat/feedback/chat-tool-code-area.tsx

@@ -12,7 +12,7 @@ export function ChatToolCodeArea({
   isError = false,
   labels = {},
   sx,
-}: ChatToolCodeAreaProps & { isError?: boolean }) {
+}: ChatToolCodeAreaProps) {
   const preRef = useRef<HTMLPreElement>(null)
   const [isOverflowing, setIsOverflowing] = useState(false)
   const [dialogOpen, setDialogOpen] = useState(false)

package/src/chat/feedback/chat-tool-group.tsx

@@ -123,7 +123,7 @@ export function ChatToolGroup({
                   <ChevronRight
                     sx={{
                       ...styles.traceChevron,
-                      transform: expanded ? 'rotate(90deg)' : 'rotate(0deg)',
+                      transform: isExpanded ? 'rotate(90deg)' : 'rotate(0deg)',
                     }}
                   />
                 </Button>

package/src/chat/feedback/chat-tool-trace.tsx

@@ -159,7 +159,12 @@ export function ChatToolTrace({
   }
 
   return (
-    <Box width='100%' sx={sx} className={`PsChat--tool-trace ${tool.name}`}>
+    <Box
+      width='100%'
+      sx={sx}
+      data-tool={tool.name}
+      className={`PsChat--tool-trace`}
+    >
       <Button
         size='small'
         variant='text'

package/src/chat/index.ts

@@ -9,11 +9,11 @@ export type {
   ChatThinkingProps,
   ChatLoaderProps,
   ChatContentProps,
+  ChatContentRef,
   ChatHeaderProps,
   ChatFooterProps,
   ChatStarterItem,
   ChatStarterProps,
-  ChatActionsContainerProps,
   ChatRatingActionProps,
   ChatToolItem,
   ChatToolTraceProps,

package/src/chat/types.ts

@@ -53,11 +53,34 @@ export interface ChatLoaderProps extends ChatSxProps {
 // === Layout props ===
 export interface ChatContentProps extends ChatSxProps {
   children: ReactNode
+  /**
+   * Smooth-scrolls to the bottom whenever new content is added — but only if
+   * the user was already at (or near) the bottom. Readers who scrolled up to
+   * revisit older messages are left alone. Defaults to `true`; pass `false`
+   * to opt out and manage scroll yourself via the ref.
+   */
+  autoScroll?: boolean
   labels?: {
     jumpToLatest?: string
   }
 }
 
+/**
+ * Imperative handle exposed by `ChatContent` via `ref`. Use it to drive scroll
+ * from the parent — for example, calling `scrollToBottom()` when a new agent
+ * message arrives.
+ */
+export interface ChatContentRef {
+  /** Smooth-scrolls the content area to the bottom. */
+  scrollToBottom: () => void
+  /** Smooth-scrolls the content area to the top. */
+  scrollToTop: () => void
+  /** `true` when the content area is scrolled to (or near) its bottom edge. */
+  isAtBottom: boolean
+  /** `true` when the content area is scrolled to (or near) its top edge. */
+  isAtTop: boolean
+}
+
 // === Container props ===
 export interface ChatHeaderProps extends ChatSxProps {
   leftSlot?: ReactNode
@@ -67,17 +90,28 @@ export interface ChatHeaderProps extends ChatSxProps {
 }
 
 export interface ChatFooterProps extends ChatSxProps {
+  /** Current value of the chat message area. */
   value: string
+  /** Called with the new textarea value on every keystroke. */
   onChange: (value: string) => void
+  /** Called when the send button is clicked or Enter is pressed (without Shift). */
   onSend: () => void
+  /** Called when the stop button is clicked. Only shown while `isGenerating` is true. */
   onStop?: () => void
+  /** When true, swaps the send button for a stop button and disables the textarea. */
   isGenerating?: boolean
+  /** Disables the textarea and both send/stop buttons. */
   disabled?: boolean
+  /** Placeholder text for the textarea. Defaults to `'Type a message...'`. */
   placeholder?: string
+  /** Accessible labels for the send and stop buttons (used as `aria-label`). */
   labels?: {
+    /** Defaults to `'Send'`. */
     send?: string
+    /** Defaults to `'Stop'`. */
     stop?: string
   }
+  /** Helper text rendered under the input. Defaults to an AI disclaimer; pass `null` to hide. */
   caption?: ReactNode
 }
 
@@ -96,10 +130,6 @@ export interface ChatStarterProps extends ChatSxProps {
   onSelect?: (prompt: string) => void
 }
 
-export interface ChatActionsContainerProps extends ChatSxProps {
-  children: ReactNode
-}
-
 export interface ChatRatingActionProps {
   onRatingChange?: (rating: 'up' | 'down' | null) => void
   rating?: 'up' | 'down' | null
@@ -152,6 +182,8 @@ export interface ChatToolCodeAreaProps extends ChatSxProps {
   content: string
   /** Label for the full view dialog title */
   title?: string
+  /** Render with error styling (red left border, tinted background) */
+  isError?: boolean
   labels?: {
     fullView?: string
   }