@carto/ps-react-ui 4.3.10 → 4.4.0-chat-ui.0

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

@@ -0,0 +1,32 @@
+import { useRef } from 'react'
+import { Box, Fab } from '@mui/material'
+import { KeyboardArrowDown } from '@mui/icons-material'
+import type { ChatContentProps } 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>
+      </Box>
+    </Box>
+  )
+}

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) => (
+          <ChatSuggestionButton
+            key={item.label}
+            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,107 @@
+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',
+    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',
+  },
+  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',
+    '--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)',
+    },
+  },
+  jumpToLatestWrapper: {
+    position: 'sticky',
+    bottom: ({ spacing }) => spacing(3),
+    height: 0,
+    display: 'flex',
+    justifyContent: 'center',
+    zIndex: 1,
+  },
+  jumpToLatest: {
+    opacity: 0,
+    pointerEvents: 'none',
+    '@supports (animation-timeline: scroll())': {
+      animation: `${showFab} linear both`,
+      animationTimeline: 'scroll(nearest)',
+    },
+  },
+  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>
+    </>
+  )
+}

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

@@ -0,0 +1,15 @@
+import { describe, test, expect } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import { ChatThinking } from './chat-thinking'
+
+describe('ChatThinking', () => {
+  test('renders default thinking text', () => {
+    render(<ChatThinking />)
+    expect(screen.getByText('Thinking...')).toBeTruthy()
+  })
+
+  test('renders custom text', () => {
+    render(<ChatThinking>Processing your request...</ChatThinking>)
+    expect(screen.getByText('Processing your request...')).toBeTruthy()
+  })
+})

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

@@ -0,0 +1,23 @@
+import { Typography } from '@mui/material'
+import type { ChatThinkingProps } from '../types'
+import { styles } from './styles'
+
+export function ChatThinking({
+  children = 'Thinking...',
+  duration = 2000,
+  sx,
+}: ChatThinkingProps) {
+  const durSeconds = `${duration / 1000}s`
+  return (
+    <Typography
+      variant='body2'
+      sx={{
+        ...styles.thinking,
+        animationDuration: durSeconds,
+        ...sx,
+      }}
+    >
+      {children}
+    </Typography>
+  )
+}

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

@@ -0,0 +1,23 @@
+import { describe, test, expect } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import { ChatTools } from './chat-tools'
+
+describe('ChatTools', () => {
+  const defaultTools = [
+    { id: '1', name: 'Search', status: 'complete' as const },
+    { id: '2', name: 'Analyze', status: 'loading' as const },
+  ]
+
+  test('renders tool names', () => {
+    render(<ChatTools tools={defaultTools} />)
+    expect(screen.getByText('Search')).toBeTruthy()
+    expect(screen.getByText('Analyze')).toBeTruthy()
+  })
+
+  test('renders title label when provided', () => {
+    render(
+      <ChatTools tools={defaultTools} labels={{ title: 'Tool Activity' }} />,
+    )
+    expect(screen.getByText('Tool Activity')).toBeTruthy()
+  })
+})