@carto/ps-react-ui 5.0.0-widgets.8 → 5.0.0

package/src/chat/bubbles/styles.ts

@@ -0,0 +1,171 @@
+import {
+  styled,
+  Typography,
+  type SxProps,
+  type Theme,
+  type TypographyProps,
+} from '@mui/material'
+import type { CSSObject } from '@mui/material/styles'
+import type { FC } from 'react'
+
+// The explicit annotation is what keeps this file's .d.ts emittable: the type
+// `styled()` infers can only be named through a pnpm-internal @mui/system path
+// (TS2742), and vite-plugin-dts drops the whole declaration when that happens.
+//
+// ponytail: `component` and `ref` still typecheck, but the prop re-typing that
+// comes with them does not — `component="a" href="#"` is rejected here and
+// accepted on `Typography` itself. Restoring it needs `OverridableComponent`,
+// which a MUI v5 `styled()` result isn't assignable to under React 19 types.
+// Consumers who need the polymorphism use `Typography` directly.
+export const ChatMessageOverflow: FC<TypographyProps> = styled(Typography)(
+  () => ({
+    whiteSpace: 'pre-wrap',
+    overflowX: 'clip',
+    overflowWrap: 'break-word',
+    maxWidth: '100%',
+  }),
+)
+ChatMessageOverflow.displayName = 'ChatMessageOverflow'
+
+export const styles = {
+  agentMessageContainer: (theme: Theme): CSSObject => ({
+    ...theme.typography.body2,
+    width: '100%',
+    display: 'flex',
+    flexDirection: 'column',
+    alignItems: 'flex-start',
+    // Separate the stacked turn blocks (tools → answer text → actions) per the
+    // Figma "Chat Turn" spec (gap-8).
+    gap: theme.spacing(1),
+    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.paper,
+    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,145 @@
+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(() => {
+        // Plain `?? =` rather than `??=`: the React Compiler can't yet lower
+        // logical-assignment operators, and bailing out would drop memoization
+        // for this scroll container (which re-renders on every message).
+        rafId = 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'

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

@@ -0,0 +1,93 @@
+import { describe, test, expect, vi } from 'vitest'
+import { render, screen, fireEvent } from '@testing-library/react'
+import { ChatFooter } from './chat-footer'
+
+describe('ChatFooter', () => {
+  const defaultProps = {
+    value: '',
+    onChange: vi.fn(),
+    onSend: vi.fn(),
+  }
+
+  test('renders send button', () => {
+    render(<ChatFooter {...defaultProps} />)
+    expect(screen.getByLabelText('Send')).toBeTruthy()
+  })
+
+  test('send button is disabled when value is empty', () => {
+    render(<ChatFooter {...defaultProps} />)
+    expect(screen.getByLabelText('Send').hasAttribute('disabled')).toBeTruthy()
+  })
+
+  test('renders stop button when generating', () => {
+    render(<ChatFooter {...defaultProps} isGenerating onStop={vi.fn()} />)
+    expect(screen.getByLabelText('Stop')).toBeTruthy()
+  })
+
+  test('calls onChange when typing', () => {
+    const onChange = vi.fn()
+    render(<ChatFooter {...defaultProps} onChange={onChange} />)
+    const input = screen.getByPlaceholderText('Type a message...')
+    fireEvent.change(input, { target: { value: 'hello' } })
+    expect(onChange).toHaveBeenCalledWith('hello')
+  })
+
+  const MODELS = [
+    { value: 'gpt-4o', label: 'gpt-4o' },
+    { value: 'gemini-2.5-pro', label: 'gemini-2.5-pro' },
+  ]
+
+  test('no model selector when models is empty/undefined', () => {
+    render(<ChatFooter {...defaultProps} />)
+    expect(screen.queryByLabelText('Select model')).toBeNull()
+  })
+
+  test('no model selector when only one model is available', () => {
+    render(
+      <ChatFooter
+        {...defaultProps}
+        models={[{ value: 'gpt-4o', label: 'gpt-4o' }]}
+        selectedModel='gpt-4o'
+      />,
+    )
+    expect(screen.queryByLabelText('Select model')).toBeNull()
+  })
+
+  test('renders the selected model label', () => {
+    render(
+      <ChatFooter {...defaultProps} models={MODELS} selectedModel='gpt-4o' />,
+    )
+    const trigger = screen.getByLabelText('Select model')
+    expect(trigger.textContent).toContain('gpt-4o')
+  })
+
+  test('opens the menu and fires onModelChange', () => {
+    const onModelChange = vi.fn()
+    render(
+      <ChatFooter
+        {...defaultProps}
+        models={MODELS}
+        selectedModel='gpt-4o'
+        onModelChange={onModelChange}
+      />,
+    )
+    fireEvent.click(screen.getByLabelText('Select model'))
+    fireEvent.click(screen.getByRole('menuitem', { name: 'gemini-2.5-pro' }))
+    expect(onModelChange).toHaveBeenCalledWith('gemini-2.5-pro')
+  })
+
+  test('model selector is disabled while generating', () => {
+    render(
+      <ChatFooter
+        {...defaultProps}
+        models={MODELS}
+        selectedModel='gpt-4o'
+        isGenerating
+        onStop={vi.fn()}
+      />,
+    )
+    expect(
+      screen.getByLabelText('Select model').hasAttribute('disabled'),
+    ).toBeTruthy()
+  })
+})