@carto/ps-react-ui 4.9.1 → 4.11.1

package/src/chat/bubbles/chat-suggestion-button.test.tsx

@@ -0,0 +1,24 @@
+import { describe, test, expect, vi } from 'vitest'
+import { render, screen, fireEvent } from '@testing-library/react'
+import { ChatSuggestionButton } from './chat-suggestion-button'
+
+describe('ChatSuggestionButton', () => {
+  test('renders label text', () => {
+    render(<ChatSuggestionButton label='Try this' onClick={vi.fn()} />)
+    expect(screen.getByText('Try this')).toBeTruthy()
+  })
+
+  test('calls onClick when clicked', () => {
+    const onClick = vi.fn()
+    render(<ChatSuggestionButton label='Click me' onClick={onClick} />)
+    fireEvent.click(screen.getByText('Click me'))
+    expect(onClick).toHaveBeenCalledTimes(1)
+  })
+
+  test('is disabled when disabled prop is true', () => {
+    const onClick = vi.fn()
+    render(<ChatSuggestionButton label='Disabled' onClick={onClick} disabled />)
+    const button = screen.getByRole('button')
+    expect(button.hasAttribute('disabled')).toBeTruthy()
+  })
+})

package/src/chat/bubbles/chat-suggestion-button.tsx

@@ -0,0 +1,27 @@
+import { ButtonBase, Typography } from '@mui/material'
+import { ArrowUpward } from '@mui/icons-material'
+import type { ChatSuggestionButtonProps } from '../types'
+import { styles } from './styles'
+
+export function ChatSuggestionButton({
+  label,
+  color,
+  sx,
+  ...props
+}: ChatSuggestionButtonProps) {
+  return (
+    <ButtonBase
+      sx={{
+        ...styles.suggestionButton,
+        ...(color ? { backgroundColor: color } : undefined),
+        ...sx,
+      }}
+      {...props}
+    >
+      <Typography color='inherit' variant='body2'>
+        {label}
+      </Typography>
+      <ArrowUpward />
+    </ButtonBase>
+  )
+}

package/src/chat/bubbles/chat-user-message.test.tsx

@@ -0,0 +1,27 @@
+import { describe, test, expect } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import { ChatUserMessage } from './chat-user-message'
+
+describe('ChatUserMessage', () => {
+  test('renders children content', () => {
+    render(<ChatUserMessage>Hello world</ChatUserMessage>)
+    expect(screen.getByText('Hello world')).toBeTruthy()
+  })
+
+  test('renders secondary content when provided', () => {
+    render(
+      <ChatUserMessage topContext={<span>Secondary</span>}>
+        Primary
+      </ChatUserMessage>,
+    )
+    expect(screen.getByText('Primary')).toBeTruthy()
+    expect(screen.getByText('Secondary')).toBeTruthy()
+  })
+
+  test('does not render secondary content when not provided', () => {
+    const { container } = render(
+      <ChatUserMessage>Only primary</ChatUserMessage>,
+    )
+    expect(container.textContent).toBe('Only primary')
+  })
+})

package/src/chat/bubbles/chat-user-message.tsx

@@ -0,0 +1,27 @@
+import { Box } from '@mui/material'
+import type { ChatUserMessageProps } from '../types'
+import { ChatMessageOverflow, styles } from './styles'
+
+export function ChatUserMessage({
+  children,
+  muted = false,
+  topContext,
+  sx,
+}: ChatUserMessageProps) {
+  return (
+    <Box className='PsChat--user-message' sx={styles.userMessageContainer}>
+      {topContext && <Box sx={styles.userMessageTop}>{topContext}</Box>}
+      <ChatMessageOverflow
+        className='PsChat--user-message-inner'
+        variant='body2'
+        sx={{
+          ...styles.userMessage,
+          ...(muted ? styles.muted : undefined),
+          ...sx,
+        }}
+      >
+        {children}
+      </ChatMessageOverflow>
+    </Box>
+  )
+}

package/src/chat/bubbles/index.ts

@@ -0,0 +1,4 @@
+export { ChatUserMessage } from './chat-user-message'
+export { ChatAgentMessage } from './chat-agent-message'
+export { ChatErrorMessage } from './chat-error-message'
+export { ChatSuggestionButton } from './chat-suggestion-button'

package/src/chat/bubbles/styles.ts

@@ -0,0 +1,148 @@
+import { styled, Typography, type SxProps, type Theme } from '@mui/material'
+
+export const ChatMessageOverflow = styled(Typography)(() => ({
+  whiteSpace: 'pre-wrap',
+  overflowX: 'clip',
+  overflowWrap: 'break-word',
+  maxWidth: '100%',
+}))
+ChatMessageOverflow.displayName = 'ChatMessageOverflow'
+
+export const styles = {
+  agentMessageContainer: (theme: Theme) => ({
+    width: '100%',
+    display: 'flex',
+    flexDirection: 'column',
+    alignItems: 'flex-start',
+    paddingRight: theme.spacing(4),
+    '& + .PsChat--agent-message': {
+      marginTop: theme.spacing(1),
+    },
+    '& + .PsChat--user-message': {
+      marginTop: theme.spacing(3),
+    },
+    '& > p:first-of-type': {
+      marginTop: 0,
+    },
+    '& table': {
+      alignSelf: 'stretch',
+      display: 'block',
+      overflowX: 'auto',
+      maxWidth: '100%',
+      borderCollapse: 'collapse',
+      margin: theme.spacing(1, 0),
+      fontSize: '0.875em',
+    },
+    '& th, & td': {
+      border: `1px solid ${theme.palette.divider}`,
+      padding: theme.spacing(0.5, 1),
+      textAlign: 'left',
+    },
+    '& th': {
+      backgroundColor: theme.palette.action.hover,
+      fontWeight: 600,
+    },
+    '& tr:nth-of-type(even) td': {
+      backgroundColor: theme.palette.action.hover,
+    },
+    '& ul.contains-task-list': {
+      listStyle: 'none',
+      paddingLeft: 0,
+    },
+    '& .task-list-item input[type="checkbox"]': {
+      marginRight: theme.spacing(0.5),
+    },
+    '& del': {
+      textDecoration: 'line-through',
+      opacity: 0.7,
+    },
+    '& > ul, & > ol': {
+      margin: theme.spacing(1, 0),
+      paddingLeft: theme.spacing(3),
+      '& > li + li': {
+        marginTop: theme.spacing(1),
+      },
+    },
+  }),
+  userMessageContainer: {
+    width: '100%',
+    display: 'flex',
+    flexDirection: 'column',
+    alignItems: 'flex-end',
+    paddingLeft: ({ spacing }) => spacing(4),
+    '&:has(+ .PsChat--user-message) > .PsChat--user-message-inner': {
+      borderRadius: ({ spacing }) => spacing(2),
+    },
+    '& + .PsChat--user-message': {
+      marginTop: ({ spacing }) => spacing(0.5),
+    },
+    '& + .PsChat--agent-message': {
+      marginTop: ({ spacing }) => spacing(3),
+    },
+  },
+  userMessage: {
+    padding: ({ spacing }) => spacing(0.75, 1.5),
+    borderRadius: ({ spacing }) => spacing(2, 2, 0.25, 2),
+    border: ({ palette }) => `1px solid ${palette.divider}`,
+    backgroundColor: ({ palette }) => palette.background.default,
+    color: ({ palette }) => palette.text.primary,
+    width: 'fit-content',
+  },
+  muted: {
+    color: ({ palette }) => palette.text.disabled,
+  },
+  userMessageTop: {
+    textAlign: 'right',
+    marginBottom: ({ spacing }) => spacing(0.5),
+  },
+  errorMessage: {
+    display: 'flex',
+    alignItems: 'center',
+    flexWrap: 'wrap',
+    gap: ({ spacing }) => spacing(1),
+  },
+  errorActions: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: ({ spacing }) => spacing(0.5),
+  },
+  errorAction: {
+    color: ({ palette }) => palette.text.primary,
+  },
+  errorActionSeparator: {
+    mr: 0.5,
+    color: ({ palette }) => palette.black[25],
+    fontWeight: 600,
+  },
+  suggestionButton: {
+    transition: 'border-color 0.2s',
+    width: '100%',
+    alignItems: 'flex-start',
+    justifyContent: 'space-between',
+    textAlign: 'left',
+    gap: ({ spacing }) => spacing(1),
+    padding: ({ spacing }) => spacing(0.75, 1.5),
+    borderRadius: ({ spacing }) => spacing(2),
+    border: ({ palette }) => `1px solid ${palette.divider}`,
+    '& .MuiSvgIcon-root': {
+      transition: 'color 0.2s',
+      color: 'inherit',
+      fontSize: ({ spacing }) => spacing(1.5),
+      width: ({ spacing }) => spacing(1.5),
+      minWidth: ({ spacing }) => spacing(1.5),
+      height: ({ spacing }) => spacing(2.5),
+    },
+    '&:not(.Mui-disabled) .MuiSvgIcon-root': {
+      color: ({ palette }) => palette.text.secondary,
+    },
+    '&:hover': {
+      borderColor: ({ palette }) => palette.text.hint,
+      '& .MuiSvgIcon-root': {
+        color: ({ palette }) => palette.text.primary,
+      },
+    },
+    '&.Mui-disabled': {
+      color: ({ palette }) => palette.text.disabled,
+    },
+  },
+} satisfies Record<string, SxProps<Theme>>

package/src/chat/const.ts

@@ -0,0 +1,4 @@
+export const CHAT_MAX_WIDTH = 768
+export const CHAT_SCROLL_DELAY = 300
+export const CHAT_DIVIDER_DELAY = 100
+export const CHAT_TOOL_CODE_AREA_MAX_HEIGHT = 126

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

@@ -0,0 +1,269 @@
+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()
+  })
+
+  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

@@ -0,0 +1,142 @@
+import {
+  forwardRef,
+  useEffect,
+  useImperativeHandle,
+  useRef,
+  useState,
+} from 'react'
+import { Box, Fab } from '@mui/material'
+import { KeyboardArrowDown } from '@mui/icons-material'
+import type { ChatContentProps, ChatContentRef } from '../types'
+import { styles } from './styles'
+
+/** 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>
+    )
+  },
+)
+ChatContent.displayName = 'ChatContent'