@carto/ps-react-ui 4.3.9 → 4.4.0-chat-ui.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,106 @@
+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),
+    },
+  }),
+  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,3 @@
+export const CHAT_MAX_WIDTH = 768
+export const CHAT_SCROLL_DELAY = 300
+export const CHAT_DIVIDER_DELAY = 100

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

@@ -0,0 +1,15 @@
+import { describe, test, expect } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import { ChatContent } from './chat-content'
+
+describe('ChatContent', () => {
+  test('renders children', () => {
+    render(<ChatContent>Scrollable content</ChatContent>)
+    expect(screen.getByText('Scrollable content')).toBeTruthy()
+  })
+
+  // TODO: Test scroll behaviour - verify "Jump to latest" button appears
+  // when user scrolls up and disappears when scrolled to bottom.
+  // This requires mocking scroll container dimensions and dispatching
+  // scroll events with appropriate scrollHeight/scrollTop values.
+})

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'