@carto/ps-react-ui 4.9.0 → 4.11.0

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

@@ -0,0 +1,47 @@
+import { Box, Link, Typography } from '@mui/material'
+import { ErrorOutline } from '@mui/icons-material'
+import type { ChatErrorMessageProps } from '../types'
+import { styles } from './styles'
+
+export function ChatErrorMessage({
+  errors,
+  icon,
+  actions,
+  sx,
+}: ChatErrorMessageProps) {
+  return (
+    <Box sx={{ ...styles.errorMessage, ...sx }}>
+      {icon ?? <ErrorOutline fontSize='medium' color='error' />}
+      {errors.map((error, index) => (
+        <Typography key={index} variant='subtitle2' color='error.relatedDark'>
+          {error}
+        </Typography>
+      ))}
+      {actions?.length ? (
+        <Box sx={styles.errorActions}>
+          {(actions ?? []).map((action, index) => (
+            <span key={index}>
+              {index > 0 && (
+                <Typography
+                  component='span'
+                  variant='body2'
+                  sx={styles.errorActionSeparator}
+                >
+                  &middot;
+                </Typography>
+              )}
+              <Link
+                component='button'
+                variant='body2'
+                onClick={action.onClick}
+                sx={styles.errorAction}
+              >
+                {action.label}
+              </Link>
+            </span>
+          ))}
+        </Box>
+      ) : null}
+    </Box>
+  )
+}

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)
+    })
+  })
+})