@carto/ps-react-ui 4.9.1 → 4.11.0

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'

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

@@ -0,0 +1,34 @@
+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')
+  })
+})

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

@@ -0,0 +1,78 @@
+import {
+  Box,
+  FilledInput,
+  FormControl,
+  FormHelperText,
+  IconButton,
+} from '@mui/material'
+import { ArrowUpwardOutlined, StopCircleOutlined } from '@mui/icons-material'
+import type { ChatFooterProps } from '../types'
+import { styles } from './styles'
+
+const DEFAULT_CAPTION =
+  'Responses are AI generated. Please verify key information.'
+
+export function ChatFooter({
+  value,
+  onChange,
+  onSend,
+  onStop,
+  isGenerating = false,
+  disabled = false,
+  placeholder = 'Type a message...',
+  labels = {},
+  caption = DEFAULT_CAPTION,
+  sx,
+}: ChatFooterProps) {
+  const canSend = value.trim() && !disabled && !isGenerating
+  const handleKeyDown = (e: React.KeyboardEvent) => {
+    if (e.key === 'Enter' && !e.shiftKey) {
+      e.preventDefault()
+      if (canSend) {
+        onSend()
+      }
+    }
+  }
+
+  return (
+    <FormControl fullWidth sx={{ ...styles.footerWrapper, ...sx }}>
+      <FilledInput
+        multiline
+        value={value}
+        onChange={(e) => onChange(e.target.value)}
+        onKeyDown={handleKeyDown}
+        placeholder={placeholder}
+        disabled={disabled || isGenerating}
+        sx={styles.footer}
+        style={{ minHeight: 0 }}
+        fullWidth
+        size='small'
+      />
+      <Box sx={styles.footerCorner}>
+        {isGenerating && onStop ? (
+          <IconButton
+            size='small'
+            onClick={onStop}
+            disabled={disabled}
+            aria-label={labels.stop ?? 'Stop'}
+          >
+            <StopCircleOutlined />
+          </IconButton>
+        ) : (
+          <IconButton
+            size='small'
+            variant='contained'
+            onClick={onSend}
+            disabled={!canSend}
+            aria-label={labels.send ?? 'Send'}
+          >
+            <ArrowUpwardOutlined />
+          </IconButton>
+        )}
+      </Box>
+      {caption ? (
+        <FormHelperText sx={styles.footerCaption}>{caption}</FormHelperText>
+      ) : null}
+    </FormControl>
+  )
+}

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

@@ -0,0 +1,28 @@
+import { describe, test, expect, vi } from 'vitest'
+import { render, screen, fireEvent } from '@testing-library/react'
+import { ChatHeader } from './chat-header'
+
+describe('ChatHeader', () => {
+  test('renders title', () => {
+    render(<ChatHeader title='Chat Assistant' />)
+    expect(screen.getByText('Chat Assistant')).toBeTruthy()
+  })
+
+  test('renders close button when onClose provided', () => {
+    const onClose = vi.fn()
+    render(<ChatHeader title='Test' onClose={onClose} />)
+    const closeButton = screen.getByLabelText('Close')
+    fireEvent.click(closeButton)
+    expect(onClose).toHaveBeenCalledTimes(1)
+  })
+
+  test('renders rightSlot', () => {
+    render(<ChatHeader title='Test' rightSlot={<button>Custom</button>} />)
+    expect(screen.getByText('Custom')).toBeTruthy()
+  })
+
+  test('renders leftSlot', () => {
+    render(<ChatHeader title='Test' leftSlot={<button>Back</button>} />)
+    expect(screen.getByText('Back')).toBeTruthy()
+  })
+})

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

@@ -0,0 +1,29 @@
+import { Box, IconButton, Typography } from '@mui/material'
+import { Close } from '@mui/icons-material'
+import type { ChatHeaderProps } from '../types'
+import { styles } from './styles'
+
+export function ChatHeader({
+  leftSlot,
+  title,
+  rightSlot,
+  onClose,
+  sx,
+}: ChatHeaderProps) {
+  return (
+    <Box sx={{ ...styles.header, ...sx }}>
+      {leftSlot}
+      <Typography variant='subtitle2' sx={styles.headerTitle}>
+        {title}
+      </Typography>
+      <Box sx={styles.headerActions}>
+        {rightSlot}
+        {onClose && (
+          <IconButton size='medium' onClick={onClose} aria-label='Close'>
+            <Close />
+          </IconButton>
+        )}
+      </Box>
+    </Box>
+  )
+}

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

@@ -0,0 +1,32 @@
+import { describe, test, expect, vi } from 'vitest'
+import { render, screen, fireEvent } from '@testing-library/react'
+import { ChatStarter } from './chat-starter'
+
+describe('ChatStarter', () => {
+  const defaultItems = ['Suggestion 1', 'Suggestion 2']
+
+  test('renders title and description', () => {
+    render(
+      <ChatStarter
+        title='Welcome'
+        description='How can I help?'
+        items={defaultItems}
+      />,
+    )
+    expect(screen.getByText('Welcome')).toBeTruthy()
+    expect(screen.getByText('How can I help?')).toBeTruthy()
+  })
+
+  test('renders suggestion items', () => {
+    render(<ChatStarter items={defaultItems} />)
+    expect(screen.getByText('Suggestion 1')).toBeTruthy()
+    expect(screen.getByText('Suggestion 2')).toBeTruthy()
+  })
+
+  test('calls item onClick when clicked', () => {
+    const onSelect = vi.fn()
+    render(<ChatStarter items={defaultItems} onSelect={onSelect} />)
+    fireEvent.click(screen.getByText('Suggestion 1'))
+    expect(onSelect).toHaveBeenCalledTimes(1)
+  })
+})

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

@@ -0,0 +1,75 @@
+import { Box, Typography } from '@mui/material'
+import type { ChatStarterProps } from '../types'
+import { ChatSuggestionButton } from '../bubbles/chat-suggestion-button'
+import { styles } from './styles'
+
+const DEFAULT_PALETTE = [
+  '#C9DB7440', // pastel green
+  '#FE88B140', // pastel red
+  '#9EB9F340', // pastel blue
+  '#F6CF7140', // pastel yellow
+]
+
+export function ChatStarter({
+  icon,
+  title,
+  description,
+  items,
+  size = 'small',
+  onSelect,
+  sx,
+}: ChatStarterProps) {
+  const fullItems = items.map((item, index) => {
+    if (typeof item === 'string') {
+      return {
+        label: item,
+        color: DEFAULT_PALETTE[index],
+      }
+    } else {
+      return {
+        label: item.label,
+        color: item.color ?? DEFAULT_PALETTE[index],
+      }
+    }
+  })
+  return (
+    <Box
+      sx={{
+        ...styles.starter,
+        gap: size === 'small' ? 1 : 2,
+        ...sx,
+      }}
+    >
+      {icon}
+      {title && (
+        <Typography variant={size === 'small' ? 'h6' : 'h5'}>
+          {title}
+        </Typography>
+      )}
+      {description && (
+        <Typography
+          variant={size === 'small' ? 'body2' : 'body1'}
+          color='text.secondary'
+        >
+          {description}
+        </Typography>
+      )}
+      <Box
+        sx={{
+          ...styles.starterItems,
+          gap: size === 'small' ? 1 : 2,
+          ...(items.length > 2 ? styles.starterItemsTwoCol : undefined),
+        }}
+      >
+        {fullItems.map((item, i) => (
+          <ChatSuggestionButton
+            key={i}
+            label={item.label}
+            onClick={() => onSelect?.(item.label)}
+            color={item.color}
+          />
+        ))}
+      </Box>
+    </Box>
+  )
+}

package/src/chat/containers/index.ts

@@ -0,0 +1,4 @@
+export { ChatContent } from './chat-content'
+export { ChatHeader } from './chat-header'
+export { ChatFooter } from './chat-footer'
+export { ChatStarter } from './chat-starter'

package/src/chat/containers/styles.ts

@@ -0,0 +1,96 @@
+import type { SxProps, Theme } from '@mui/material'
+import { CHAT_MAX_WIDTH } from '../const'
+
+export const styles = {
+  header: {
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'space-between',
+    padding: ({ spacing }) => spacing(1),
+  },
+  headerTitle: {
+    flexGrow: 1,
+    px: ({ spacing }) => spacing(0.5),
+  },
+  headerActions: {
+    display: 'flex',
+    alignItems: 'center',
+    marginLeft: ({ spacing }) => spacing(2),
+    gap: ({ spacing }) => spacing(0.5),
+  },
+  footerWrapper: {
+    padding: ({ spacing }) => spacing(1),
+    position: 'relative',
+  },
+  footerCorner: {
+    position: 'absolute',
+    bottom: '38px',
+    right: `max(16px, calc(50% - ${CHAT_MAX_WIDTH / 2}px + 6px))`,
+    margin: '0 auto',
+  },
+  footer: {
+    maxWidth: CHAT_MAX_WIDTH,
+    margin: '0 auto',
+    '&.MuiFilledInput-root.MuiInputBase-multiline.MuiInputBase-sizeSmall textarea':
+      {
+        resize: 'none',
+        maxHeight: '10em',
+        overflowY: 'auto !important',
+        paddingRight: ({ spacing }) => spacing(5),
+      },
+  },
+  footerCaption: {
+    textAlign: 'center',
+  },
+  content: {
+    overflowY: 'auto',
+    flex: 1,
+    position: 'relative',
+    mx: 'auto',
+    maxWidth: CHAT_MAX_WIDTH,
+    width: '100%',
+    maxHeight: '100%',
+    pt: 1,
+    pb: 2,
+    px: 2,
+    display: 'flex',
+    flexDirection: 'column',
+    borderTopWidth: '1px',
+    borderTopStyle: 'solid',
+    borderBottomWidth: '1px',
+    borderBottomStyle: 'solid',
+  },
+  sentinel: {
+    height: '1px',
+    flexShrink: 0,
+  },
+  jumpToLatestWrapper: {
+    position: 'sticky',
+    bottom: ({ spacing }) => spacing(3),
+    height: 0,
+    display: 'flex',
+    justifyContent: 'center',
+    zIndex: 1,
+  },
+  jumpToLatest: {
+    transition: 'opacity 0.2s',
+  },
+  starter: {
+    display: 'flex',
+    flexDirection: 'column',
+    alignItems: 'center',
+    justifyContent: 'center',
+    padding: ({ spacing }) => spacing(3),
+    textAlign: 'center',
+    maxWidth: CHAT_MAX_WIDTH,
+    margin: '0 auto',
+  },
+  starterItems: {
+    display: 'grid',
+    width: '100%',
+    marginTop: ({ spacing }) => spacing(2),
+  },
+  starterItemsTwoCol: {
+    gridTemplateColumns: 'repeat(2, 1fr)',
+  },
+} satisfies Record<string, SxProps<Theme>>

package/src/chat/feedback/chat-actions-container.test.tsx

@@ -0,0 +1,64 @@
+import { describe, test, expect, vi } from 'vitest'
+import { render, screen, fireEvent } from '@testing-library/react'
+import { ChatActionsContainer } from './chat-actions-container'
+import { ChatRatingAction } from './chat-rating-action'
+
+describe('ChatActionsContainer', () => {
+  test('renders children', () => {
+    render(
+      <ChatActionsContainer>
+        <span>child content</span>
+      </ChatActionsContainer>,
+    )
+    expect(screen.getByText('child content')).toBeTruthy()
+  })
+})
+
+describe('ChatRatingAction', () => {
+  test('renders thumb up and thumb down buttons', () => {
+    render(<ChatRatingAction />)
+    expect(screen.getByLabelText('Thumbs up')).toBeTruthy()
+    expect(screen.getByLabelText('Thumbs down')).toBeTruthy()
+  })
+
+  test('calls onRatingChange with up when thumbs up clicked', () => {
+    const onRatingChange = vi.fn()
+    render(<ChatRatingAction onRatingChange={onRatingChange} />)
+    fireEvent.click(screen.getByLabelText('Thumbs up'))
+    expect(onRatingChange).toHaveBeenCalledWith('up')
+  })
+
+  test('calls onRatingChange with null when active thumb up clicked', () => {
+    const onRatingChange = vi.fn()
+    render(<ChatRatingAction onRatingChange={onRatingChange} rating='up' />)
+    fireEvent.click(screen.getByLabelText('Thumbs up'))
+    expect(onRatingChange).toHaveBeenCalledWith(null)
+  })
+
+  test('calls onRatingChange with down when thumbs down clicked', () => {
+    const onRatingChange = vi.fn()
+    render(<ChatRatingAction onRatingChange={onRatingChange} />)
+    fireEvent.click(screen.getByLabelText('Thumbs down'))
+    expect(onRatingChange).toHaveBeenCalledWith('down')
+  })
+
+  test('highlights active rating up', () => {
+    const { container } = render(<ChatRatingAction rating='up' />)
+    expect(container.querySelector('[data-testid="ThumbUpIcon"]')).toBeTruthy()
+  })
+
+  test('highlights active rating down', () => {
+    const { container } = render(<ChatRatingAction rating='down' />)
+    expect(
+      container.querySelector('[data-testid="ThumbDownIcon"]'),
+    ).toBeTruthy()
+  })
+
+  test('renders with custom labels', () => {
+    render(
+      <ChatRatingAction labels={{ thumbUp: 'Like', thumbDown: 'Dislike' }} />,
+    )
+    expect(screen.getByLabelText('Like')).toBeTruthy()
+    expect(screen.getByLabelText('Dislike')).toBeTruthy()
+  })
+})

package/src/chat/feedback/chat-actions-container.tsx

@@ -0,0 +1,7 @@
+import { Box, styled } from '@mui/material'
+
+export const ChatActionsContainer = styled(Box)(({ theme }) => ({
+  display: 'flex',
+  alignItems: 'center',
+  gap: theme.spacing(0.5),
+}))

package/src/chat/feedback/chat-loader.test.tsx

@@ -0,0 +1,10 @@
+import { describe, test, expect } from 'vitest'
+import { render } from '@testing-library/react'
+import { ChatLoader } from './chat-loader'
+
+describe('ChatLoader', () => {
+  test('renders loading indicator', () => {
+    const { container } = render(<ChatLoader />)
+    expect(container.querySelector('[role="status"]')).toBeTruthy()
+  })
+})

package/src/chat/feedback/chat-loader.tsx

@@ -0,0 +1,31 @@
+import { Box } from '@mui/material'
+import type { ChatLoaderProps } from '../types'
+import { styles } from './styles'
+
+export function ChatLoader({ size = 24, labels = {}, sx }: ChatLoaderProps) {
+  return (
+    <Box
+      role='status'
+      aria-busy={true}
+      aria-label={labels.loading ?? 'Loading'}
+      sx={{ ...styles.loader, width: size, height: size, ...sx }}
+    >
+      <Box
+        component='span'
+        sx={{
+          ...styles.loaderOuterCircle,
+          width: size * 0.75,
+          height: size * 0.75,
+        }}
+      />
+      <Box
+        component='span'
+        sx={{
+          ...styles.loaderInnerCircle,
+          width: size * 0.32,
+          height: size * 0.32,
+        }}
+      />
+    </Box>
+  )
+}

package/src/chat/feedback/chat-rating-action.tsx

@@ -0,0 +1,43 @@
+import { IconButton } from '@mui/material'
+import {
+  ThumbUpOutlined,
+  ThumbDownOutlined,
+  ThumbUp,
+  ThumbDown,
+} from '@mui/icons-material'
+import type { ChatRatingActionProps } from '../types'
+
+export function ChatRatingAction({
+  rating,
+  onRatingChange,
+  labels = {},
+}: ChatRatingActionProps) {
+  return (
+    <>
+      <IconButton
+        size='small'
+        onClick={() => onRatingChange?.(rating === 'up' ? null : 'up')}
+        aria-label={labels.thumbUp ?? 'Thumbs up'}
+        color={rating === 'up' ? 'primary' : undefined}
+      >
+        {rating === 'up' ? (
+          <ThumbUp fontSize='small' />
+        ) : (
+          <ThumbUpOutlined fontSize='small' />
+        )}
+      </IconButton>
+      <IconButton
+        size='small'
+        onClick={() => onRatingChange?.(rating === 'down' ? null : 'down')}
+        aria-label={labels.thumbDown ?? 'Thumbs down'}
+        color={rating === 'down' ? 'primary' : undefined}
+      >
+        {rating === 'down' ? (
+          <ThumbDown fontSize='small' />
+        ) : (
+          <ThumbDownOutlined fontSize='small' />
+        )}
+      </IconButton>
+    </>
+  )
+}