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

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

@@ -0,0 +1,54 @@
+import {
+  Accordion,
+  AccordionDetails,
+  AccordionSummary,
+  Box,
+  CircularProgress,
+  Typography,
+} from '@mui/material'
+import {
+  CheckCircleOutline,
+  ErrorOutline,
+  ExpandMore,
+} from '@mui/icons-material'
+import type { ChatToolsProps, ChatToolItem } from '../types'
+import { ChatThinking } from './chat-thinking'
+import { styles } from './styles'
+
+function ToolStatusIcon({ status }: { status: ChatToolItem['status'] }) {
+  switch (status) {
+    case 'loading':
+      return <CircularProgress size={16} />
+    case 'thinking':
+      return <ChatThinking>...</ChatThinking>
+    case 'complete':
+      return <CheckCircleOutline fontSize='small' color='success' />
+    case 'error':
+      return <ErrorOutline fontSize='small' color='error' />
+  }
+}
+
+export function ChatTools({ tools, labels = {}, sx }: ChatToolsProps) {
+  return (
+    <Box sx={{ ...styles.tools, ...sx }}>
+      {labels.title && (
+        <Typography variant='caption' color='text.secondary' sx={{ mb: 1 }}>
+          {labels.title}
+        </Typography>
+      )}
+      {tools.map((tool) => (
+        <Accordion key={tool.id} disableGutters elevation={0}>
+          <AccordionSummary expandIcon={<ExpandMore />}>
+            <Box sx={styles.toolHeader}>
+              <Box sx={styles.toolStatusIcon}>
+                <ToolStatusIcon status={tool.status} />
+              </Box>
+              <Typography variant='body2'>{tool.name}</Typography>
+            </Box>
+          </AccordionSummary>
+          {tool.content && <AccordionDetails>{tool.content}</AccordionDetails>}
+        </Accordion>
+      ))}
+    </Box>
+  )
+}

package/src/chat/feedback/index.ts

@@ -0,0 +1,5 @@
+export { ChatThinking } from './chat-thinking'
+export { ChatLoader } from './chat-loader'
+export { ChatActionsContainer } from './chat-actions-container'
+export { ChatRatingAction } from './chat-rating-action'
+export { ChatTools } from './chat-tools'

package/src/chat/feedback/styles.ts

@@ -0,0 +1,80 @@
+import { type SxProps, type Theme } from '@mui/material'
+import { keyframes } from '@mui/material/styles'
+
+const shimmer = keyframes`
+  0% {
+    background-position: 150% 0;
+  }
+  100% {
+    background-position: -50% 0;
+  }
+`
+
+const breatheOuter = keyframes`
+  0% { transform: scale(0.68); opacity: 0.7; }
+  40% { transform: scale(1); opacity: 1; }
+  80% { transform: scale(0.6); opacity: 0.65; }
+  100% { transform: scale(0.68); opacity: 0.7; }
+`
+
+const breatheInner = keyframes`
+  0% { transform: scale(1); }
+  40% { transform: scale(0.75); }
+  80% { transform: scale(1.125); }
+  100% { transform: scale(1); }
+`
+
+export const styles = {
+  thinking: {
+    display: 'flex',
+    alignItems: 'center',
+    minHeight: ({ spacing }) => spacing(3),
+    background: ({ palette }) => `linear-gradient(
+      90deg,
+      ${palette.text.disabled} 25%,
+      ${palette.text.secondary} 50%,
+      ${palette.text.disabled} 75%
+    )`,
+    backgroundSize: '200% 100%',
+    backgroundClip: 'text',
+    WebkitBackgroundClip: 'text',
+    WebkitTextFillColor: 'transparent',
+    animation: `${shimmer} 2s ease-in-out infinite`,
+    animationDuration: '2s',
+  },
+  loader: {
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    position: 'relative',
+    p: 1,
+  },
+  loaderOuterCircle: {
+    position: 'absolute',
+    inset: 0,
+    margin: 'auto',
+    borderRadius: '50%',
+    backgroundColor: ({ palette }) => palette.action.disabled,
+    animation: `${breatheOuter} 1s ease-in-out infinite`,
+  },
+  loaderInnerCircle: {
+    position: 'absolute',
+    inset: 0,
+    margin: 'auto',
+    borderRadius: '50%',
+    backgroundColor: ({ palette }) => palette.text.primary,
+    animation: `${breatheInner} 1s ease-in-out infinite`,
+  },
+  tools: {
+    width: '100%',
+  },
+  toolHeader: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: ({ spacing }) => spacing(1),
+  },
+  toolStatusIcon: {
+    display: 'flex',
+    alignItems: 'center',
+  },
+} satisfies Record<string, SxProps<Theme>>

package/src/chat/index.ts

@@ -0,0 +1,45 @@
+// Types
+export type {
+  ChatSxProps,
+  ChatErrorAction,
+  ChatUserMessageProps,
+  ChatAgentMessageProps,
+  ChatErrorMessageProps,
+  ChatSuggestionButtonProps,
+  ChatThinkingProps,
+  ChatLoaderProps,
+  ChatContentProps,
+  ChatHeaderProps,
+  ChatFooterProps,
+  ChatStarterItem,
+  ChatStarterProps,
+  ChatActionsContainerProps,
+  ChatRatingActionProps,
+  ChatToolItem,
+  ChatToolsProps,
+} from './types'
+
+// Constants
+export { CHAT_MAX_WIDTH, CHAT_SCROLL_DELAY, CHAT_DIVIDER_DELAY } from './const'
+
+// Messages
+export { ChatUserMessage } from './bubbles/chat-user-message'
+export { ChatAgentMessage } from './bubbles/chat-agent-message'
+export { ChatErrorMessage } from './bubbles/chat-error-message'
+export { ChatSuggestionButton } from './bubbles/chat-suggestion-button'
+export { ChatMessageOverflow } from './bubbles/styles'
+
+// Feedback
+export { ChatThinking } from './feedback/chat-thinking'
+export { ChatLoader } from './feedback/chat-loader'
+
+// Containers
+export { ChatContent } from './containers/chat-content'
+export { ChatHeader } from './containers/chat-header'
+export { ChatFooter } from './containers/chat-footer'
+export { ChatStarter } from './containers/chat-starter'
+
+// Feedback
+export { ChatActionsContainer } from './feedback/chat-actions-container'
+export { ChatRatingAction } from './feedback/chat-rating-action'
+export { ChatTools } from './feedback/chat-tools'

package/src/chat/types.ts

@@ -0,0 +1,124 @@
+import type { ReactNode } from 'react'
+import type { ButtonBaseProps, SxProps, Theme } from '@mui/material'
+
+// === Shared base props ===
+export interface ChatSxProps {
+  sx?: SxProps<Theme>
+}
+
+// === Error types ===
+export interface ChatErrorAction {
+  label: string
+  onClick: () => void
+}
+
+// === Message props ===
+export interface ChatUserMessageProps extends ChatSxProps {
+  children: ReactNode
+  /** enabled to render text with a lighter color for indicating things like an error sending the message */
+  muted?: boolean
+  /** content to render on top of the message for user attachments */
+  topContext?: ReactNode
+}
+
+export interface ChatAgentMessageProps extends ChatSxProps {
+  children: ReactNode
+}
+
+export interface ChatErrorMessageProps extends ChatSxProps {
+  errors: string[]
+  icon?: ReactNode
+  actions?: ChatErrorAction[]
+}
+
+export interface ChatSuggestionButtonProps
+  extends ChatSxProps, Omit<ButtonBaseProps, 'children'> {
+  label: ReactNode
+  color?: string
+}
+
+// === Feedback props ===
+export interface ChatThinkingProps extends ChatSxProps {
+  duration?: number
+  children?: ReactNode
+}
+
+export interface ChatLoaderProps extends ChatSxProps {
+  size?: number
+  labels?: {
+    loading?: string
+  }
+}
+
+// === Layout props ===
+export interface ChatContentProps extends ChatSxProps {
+  children: ReactNode
+  labels?: {
+    jumpToLatest?: string
+  }
+}
+
+// === Container props ===
+export interface ChatHeaderProps extends ChatSxProps {
+  leftSlot?: ReactNode
+  title: ReactNode
+  rightSlot?: ReactNode
+  onClose?: () => void
+}
+
+export interface ChatFooterProps extends ChatSxProps {
+  value: string
+  onChange: (value: string) => void
+  onSend: () => void
+  onStop?: () => void
+  isGenerating?: boolean
+  disabled?: boolean
+  placeholder?: string
+  labels?: {
+    send?: string
+    stop?: string
+  }
+  caption?: ReactNode
+}
+
+// === Extras props ===
+export interface ChatStarterItem {
+  label: string
+  color?: string
+}
+
+export interface ChatStarterProps extends ChatSxProps {
+  icon?: ReactNode
+  title?: ReactNode
+  description?: ReactNode
+  items: string[] | ChatStarterItem[]
+  size?: 'small' | 'medium'
+  onSelect?: (prompt: string) => void
+}
+
+export interface ChatActionsContainerProps extends ChatSxProps {
+  children: ReactNode
+}
+
+export interface ChatRatingActionProps {
+  onRatingChange?: (rating: 'up' | 'down' | null) => void
+  rating?: 'up' | 'down' | null
+  labels?: {
+    thumbUp?: string
+    thumbDown?: string
+  }
+}
+
+export interface ChatToolItem {
+  id: string
+  name: string
+  status: 'loading' | 'thinking' | 'complete' | 'error'
+  content?: ReactNode
+}
+
+export interface ChatToolsProps extends ChatSxProps {
+  tools: ChatToolItem[]
+  labels?: {
+    title?: string
+  }
+}

package/src/components/copy-button/copy-button.test.tsx

@@ -0,0 +1,41 @@
+import { describe, test, expect, vi } from 'vitest'
+import { render, screen, fireEvent } from '@testing-library/react'
+import { CopyButton } from './copy-button'
+
+vi.mock('@carto/ps-utils', () => ({
+  copy: vi.fn(() => Promise.resolve()),
+}))
+
+describe('CopyButton', () => {
+  test('renders copy button', () => {
+    render(
+      <CopyButton copyText='hello' onSuccess={vi.fn()} onError={vi.fn()} />,
+    )
+    expect(screen.getByRole('button')).toBeTruthy()
+  })
+
+  test('renders with custom aria-label', () => {
+    render(
+      <CopyButton
+        copyText='hello'
+        onSuccess={vi.fn()}
+        onError={vi.fn()}
+        aria-label='Copy response'
+      />,
+    )
+    expect(screen.getByLabelText('Copy response')).toBeTruthy()
+  })
+
+  test('calls copy utility when clicked', async () => {
+    const { copy } = await import('@carto/ps-utils')
+    render(
+      <CopyButton
+        copyText='hello world'
+        onSuccess={vi.fn()}
+        onError={vi.fn()}
+      />,
+    )
+    fireEvent.click(screen.getByRole('button'))
+    expect(copy).toHaveBeenCalledWith('hello world')
+  })
+})

package/src/components/copy-button/copy-button.tsx

@@ -0,0 +1,31 @@
+import { IconButton } from '@mui/material'
+import { ContentCopyOutlined } from '@mui/icons-material'
+import type { CopyButtonProps } from './types'
+import { copy } from '@carto/ps-utils'
+
+export function CopyButton({
+  copyText,
+  onSuccess,
+  onError,
+  'aria-label': ariaLabel,
+  ...props
+}: CopyButtonProps) {
+  async function onCopy() {
+    try {
+      await copy(copyText)
+      onSuccess?.()
+    } catch (err) {
+      onError?.(err as Error)
+    }
+  }
+  return (
+    <IconButton
+      size='small'
+      onClick={() => void onCopy()}
+      aria-label={ariaLabel ?? 'Copy'}
+      {...props}
+    >
+      <ContentCopyOutlined fontSize='small' />
+    </IconButton>
+  )
+}

package/src/components/copy-button/types.ts

@@ -0,0 +1,10 @@
+import type { IconButtonProps } from '@mui/material/IconButton'
+
+export interface CopyButtonProps extends Omit<
+  IconButtonProps,
+  'onError' | 'onClick'
+> {
+  copyText: string
+  onSuccess?: () => void
+  onError?: (err: Error) => void
+}

package/src/components/index.ts

@@ -62,3 +62,6 @@ export type { BasemapsUIProps } from './basemaps/types'
 
 export { Tooltip, setTooltipEnterDelay } from './tooltip/tooltip'
 export { SmartTooltip } from './smart-tooltip/smart-tooltip'
+
+export type { CopyButtonProps } from './copy-button/types'
+export { CopyButton } from './copy-button/copy-button'