@carto/ps-react-ui 4.9.1 → 4.11.0

package/src/chat/feedback/chat-tool-trace.tsx

@@ -0,0 +1,192 @@
+import {
+  Box,
+  CircularProgress,
+  Typography,
+  Collapse,
+  Button,
+} from '@mui/material'
+import { ArrowRight, CheckCircle, Error } from '@mui/icons-material'
+import type { ChatToolTraceProps } from '../types'
+import { ChatToolCodeArea } from './chat-tool-code-area'
+import { styles } from './styles'
+import { ChatThinking } from './chat-thinking'
+import { getToolLabel } from './get-tool-label'
+import { McpTool } from '@carto/meridian-ds/custom-icons'
+
+function TraceStatusIndicator({
+  status,
+  labels,
+}: {
+  status: string
+  labels: ChatToolTraceProps['labels']
+}) {
+  switch (status) {
+    case 'complete':
+      return (
+        <Box sx={{ display: 'flex', alignItems: 'center', gap: 0.5 }}>
+          <CheckCircle sx={{ fontSize: 12 }} color='success' />
+          <Typography variant='caption'>
+            {labels?.success ?? 'Success'}
+          </Typography>
+        </Box>
+      )
+    case 'error':
+      return (
+        <Box sx={{ display: 'flex', alignItems: 'center', gap: 0.5 }}>
+          <Error sx={{ fontSize: 12 }} color='error' />
+          <Typography variant='code3'>{labels?.error ?? 'Error'}</Typography>
+        </Box>
+      )
+    case 'running':
+      return <CircularProgress size={14} />
+    default:
+      return null
+  }
+}
+
+export function ChatToolTraceDetails({
+  tool,
+  labels = {},
+}: Pick<ChatToolTraceProps, 'tool' | 'labels'>) {
+  const isError = tool.status === 'error'
+  const toolExecutedLabel = labels.toolExecuted ?? 'Tool executed'
+  const referenceLabel = labels.reference ?? 'Reference:'
+  const durationLabel = labels.duration ?? 'Duration:'
+  const statusLabel = labels.status ?? 'Status:'
+  const inputArgumentsLabel = labels.inputArguments ?? 'Input arguments:'
+  const outputLabel = labels.output ?? 'Output:'
+
+  return (
+    <Box>
+      {tool.reference && (
+        <Box sx={styles.traceField}>
+          <Typography
+            variant='code3'
+            fontWeight={600}
+            color='text.secondary'
+            sx={styles.traceFieldLabel}
+          >
+            {referenceLabel}
+          </Typography>
+          <Box sx={styles.traceReference}>
+            <McpTool color='success' />
+            <Typography variant='code3' fontWeight={600}>
+              {tool.reference}
+            </Typography>
+          </Box>
+        </Box>
+      )}
+
+      {tool.duration != null && (
+        <Box sx={styles.traceField}>
+          <Typography
+            variant='code3'
+            fontWeight={600}
+            color='text.secondary'
+            sx={styles.traceFieldLabel}
+          >
+            {durationLabel}
+          </Typography>
+          <Typography variant='code3'>{tool.duration}s</Typography>
+        </Box>
+      )}
+
+      <Box sx={styles.traceField}>
+        <Typography
+          variant='code3'
+          fontWeight={600}
+          color='text.secondary'
+          sx={styles.traceFieldLabel}
+        >
+          {statusLabel}
+        </Typography>
+        <TraceStatusIndicator status={tool.status} labels={labels} />
+      </Box>
+
+      {tool.inputArguments && (
+        <Box>
+          <Typography
+            variant='code3'
+            fontWeight={600}
+            color='text.secondary'
+            sx={styles.traceField}
+          >
+            {inputArgumentsLabel}
+          </Typography>
+          <ChatToolCodeArea
+            sx={{ mt: 0.5, mb: tool.output ? 1.5 : 0 }}
+            content={tool.inputArguments}
+            title={`${toolExecutedLabel}: ${inputArgumentsLabel}`}
+            isError={isError}
+          />
+        </Box>
+      )}
+
+      {tool.output && (
+        <Box>
+          <Typography
+            variant='code3'
+            fontWeight={600}
+            color='text.secondary'
+            sx={styles.traceField}
+          >
+            {outputLabel}
+          </Typography>
+          <ChatToolCodeArea
+            sx={{ mt: 0.5 }}
+            content={tool.output}
+            title={`${toolExecutedLabel}: ${outputLabel}`}
+            isError={isError}
+          />
+        </Box>
+      )}
+    </Box>
+  )
+}
+
+export function ChatToolTrace({
+  tool,
+  expanded,
+  onExpandedChange,
+  labels = {},
+  sx,
+}: ChatToolTraceProps) {
+  const isRunning = tool.status === 'running'
+  const toolExecutedLabel = labels.toolExecuted ?? 'Tool executed'
+
+  if (isRunning) {
+    return <ChatThinking>{getToolLabel(tool)}</ChatThinking>
+  }
+
+  return (
+    <Box
+      width='100%'
+      sx={sx}
+      data-tool={tool.name}
+      className={`PsChat--tool-trace`}
+    >
+      <Button
+        size='small'
+        variant='text'
+        onClick={() => onExpandedChange?.(!expanded)}
+        aria-expanded={expanded}
+        sx={styles.traceHeader}
+      >
+        <Typography variant='caption' fontWeight={600} color='text.secondary'>
+          {toolExecutedLabel}
+        </Typography>
+        <ArrowRight
+          sx={{
+            ...styles.traceChevron,
+            transform: expanded ? 'rotate(90deg)' : 'rotate(0deg)',
+          }}
+        />
+      </Button>
+      <Collapse in={expanded} unmountOnExit>
+        <Box sx={styles.traceDetailsWrapper}>
+          <ChatToolTraceDetails tool={tool} labels={labels} />
+        </Box>
+      </Collapse>
+    </Box>
+  )
+}

package/src/chat/feedback/get-tool-label.test.tsx

@@ -0,0 +1,91 @@
+import { describe, test, expect } from 'vitest'
+import { getToolLabel } from './get-tool-label'
+import type { ChatToolItem } from '../types'
+
+describe('getToolLabel', () => {
+  test('uses runningLabel when status is running', () => {
+    const tool: ChatToolItem = {
+      id: '1',
+      name: 'execute_sql',
+      status: 'running',
+      runningLabel: 'Running query',
+    }
+    expect(getToolLabel(tool)).toBe('Running query')
+  })
+
+  test('falls back to capitalized name when running without runningLabel', () => {
+    const tool: ChatToolItem = {
+      id: '1',
+      name: 'execute_sql',
+      status: 'running',
+    }
+    expect(getToolLabel(tool)).toBe('Execute sql')
+  })
+
+  test('uses label for completed status', () => {
+    const tool: ChatToolItem = {
+      id: '1',
+      name: 'execute_sql',
+      status: 'complete',
+      label: 'Database query',
+    }
+    expect(getToolLabel(tool)).toBe('Database query')
+  })
+
+  test('uses label for error status', () => {
+    const tool: ChatToolItem = {
+      id: '1',
+      name: 'execute_sql',
+      status: 'error',
+      label: 'Database query',
+    }
+    expect(getToolLabel(tool)).toBe('Database query')
+  })
+
+  test('falls back to capitalized name for non-running without label', () => {
+    const tool: ChatToolItem = {
+      id: '1',
+      name: 'add_marker',
+      status: 'complete',
+    }
+    expect(getToolLabel(tool)).toBe('Add marker')
+  })
+
+  test('replaces underscores with spaces and capitalizes first letter', () => {
+    const tool: ChatToolItem = {
+      id: '1',
+      name: 'geocode_address_v2',
+      status: 'complete',
+    }
+    expect(getToolLabel(tool)).toBe('Geocode address v2')
+  })
+
+  test('preserves names that are already formatted', () => {
+    const tool: ChatToolItem = {
+      id: '1',
+      name: 'Tool #1',
+      status: 'complete',
+    }
+    expect(getToolLabel(tool)).toBe('Tool #1')
+  })
+
+  test('runningLabel does not leak into non-running statuses', () => {
+    const tool: ChatToolItem = {
+      id: '1',
+      name: 'execute_sql',
+      status: 'complete',
+      runningLabel: 'Running query',
+    }
+    expect(getToolLabel(tool)).toBe('Execute sql')
+  })
+
+  test('label does not leak into running status', () => {
+    const tool: ChatToolItem = {
+      id: '1',
+      name: 'execute_sql',
+      status: 'running',
+      label: 'Database query',
+    }
+    expect(getToolLabel(tool)).toBe('Execute sql')
+  })
+})

package/src/chat/feedback/get-tool-label.ts

@@ -0,0 +1,13 @@
+import type { ChatToolItem } from '../types'
+
+function capitalize(str: string): string {
+  const spaced = str.replace(/_/g, ' ')
+  return spaced.charAt(0).toUpperCase() + spaced.slice(1)
+}
+
+export function getToolLabel(tool: ChatToolItem): string {
+  if (tool.status === 'running') {
+    return tool.runningLabel ?? capitalize(tool.name)
+  }
+  return tool.label ?? capitalize(tool.name)
+}

package/src/chat/feedback/index.ts

@@ -0,0 +1,8 @@
+export { ChatThinking } from './chat-thinking'
+export { ChatLoader } from './chat-loader'
+export { ChatActionsContainer } from './chat-actions-container'
+export { ChatRatingAction } from './chat-rating-action'
+export { ChatToolTrace } from './chat-tool-trace'
+export { ChatToolCodeArea } from './chat-tool-code-area'
+export { ChatToolFullViewDialog } from './chat-tool-full-view-dialog'
+export { ChatToolGroup } from './chat-tool-group'

package/src/chat/feedback/styles.ts

@@ -0,0 +1,229 @@
+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`,
+  },
+  // --- Tool Trace styles ---
+  traceHeader: {
+    display: 'flex',
+    alignItems: 'center',
+    padding: 0,
+    paddingLeft: ({ spacing }) => spacing(0.5),
+    borderRadius: ({ spacing }) => spacing(0.5),
+    width: 'fit-content',
+    color: ({ palette }) => palette.text.secondary,
+    '&:hover': {
+      backgroundColor: ({ palette }) => palette.action.hover,
+    },
+  },
+  traceChevron: {
+    color: ({ palette }) => palette.text.secondary,
+    transition: 'transform 0.2s',
+  },
+  traceDetailsWrapper: {
+    marginTop: ({ spacing }) => spacing(0.5),
+    padding: ({ spacing }) => spacing(1.5),
+    border: '1px solid',
+    borderColor: 'divider',
+    borderRadius: ({ spacing }) => spacing(1),
+  },
+  traceField: {
+    display: 'flex',
+    alignItems: 'flex-start',
+    gap: ({ spacing }) => spacing(1),
+  },
+  traceFieldLabel: {
+    flexShrink: 0,
+  },
+  traceReference: {
+    display: 'flex',
+    borderRadius: ({ spacing }) => spacing(0.25),
+    padding: ({ spacing }) => spacing(0, 0.5),
+    gap: ({ spacing }) => spacing(0.5),
+    backgroundColor: ({ palette }) => palette.success.relatedLight,
+    color: ({ palette }) => palette.success.dark,
+  },
+  traceStatusSuccess: {
+    color: ({ palette }) => palette.success.main,
+  },
+  traceStatusError: {
+    color: ({ palette }) => palette.error.main,
+  },
+  // --- Code Area styles ---
+  codeArea: {
+    position: 'relative',
+    width: '100%',
+  },
+  codeAreaPre: {
+    margin: 0,
+    padding: ({ spacing }) => spacing(1),
+    borderRadius: ({ spacing }) => spacing(0.5),
+    backgroundColor: ({ palette }) => palette.background.default,
+    fontSize: '0.75rem',
+    fontFamily: 'monospace',
+    whiteSpace: 'pre-wrap',
+    wordBreak: 'break-word',
+    overflowY: 'auto',
+  },
+  codeAreaPreError: {
+    borderLeft: ({ palette }) => `3px solid ${palette.error.main}`,
+    backgroundColor: ({ palette }) => `${palette.error.main}08`,
+  },
+  codeAreaFullViewButton: {
+    position: 'absolute',
+    top: ({ spacing }) => spacing(0.5),
+    right: ({ spacing }) => spacing(0.5),
+  },
+  // --- Full View Dialog styles ---
+  fullViewDialog: {
+    margin: ({ spacing }) => spacing(5),
+  },
+  fullViewPaper: {
+    borderRadius: 1,
+  },
+  fullViewTitle: {
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'space-between',
+    padding: ({ spacing }) => spacing(2),
+    borderBottom: '1px solid',
+    borderBottomColor: 'divider',
+  },
+  fullViewDialogContent: {
+    padding: 0,
+    '&:first-of-type': { paddingTop: 0 },
+  },
+  fullViewPre: {
+    margin: 0,
+    padding: ({ spacing }) => spacing(1),
+    background: ({ palette, spacing }) =>
+      `linear-gradient(to right, ${palette.action.hover} calc(${spacing(1)} + 3em), ${palette.background.default} calc(${spacing(1)} + 3em))`,
+    fontFamily: 'monospace',
+    fontSize: '0.8125rem',
+    whiteSpace: 'pre-wrap',
+    wordBreak: 'break-word',
+    lineHeight: 1.6,
+    counterReset: 'line',
+  },
+  fullViewLine: {
+    display: 'block',
+    '&::before': {
+      counterIncrement: 'line',
+      content: 'counter(line)',
+      display: 'inline-block',
+      width: '2em',
+      marginRight: '2em',
+      textAlign: 'right',
+      color: ({ palette }) => palette.text.secondary,
+      userSelect: 'none',
+    },
+  },
+  groupHeader: {
+    textAlign: 'left',
+    display: 'flex',
+    alignItems: 'center',
+    borderRadius: 0,
+    gap: ({ spacing }) => spacing(0.5),
+  },
+  errorBadge: {
+    color: ({ palette }) => palette.error.main,
+    fontWeight: 600,
+    display: 'flex',
+    alignItems: 'center',
+    gap: ({ spacing }) => spacing(0.25),
+  },
+  // --- Syntax highlighting token styles ---
+  syntaxToken_key: {
+    color: '#881280',
+  },
+  syntaxToken_string: {
+    color: '#c41a16',
+  },
+  syntaxToken_number: {
+    color: '#1c00cf',
+  },
+  syntaxToken_boolean: {
+    color: '#1c00cf',
+  },
+  syntaxToken_null: {
+    color: '#808080',
+  },
+  syntaxToken_punctuation: {
+    color: ({ palette }) => palette.text.primary,
+  },
+  groupListItem: {
+    borderBottom: '1px solid',
+    borderColor: 'divider',
+    '&:first-of-type .MuiButton-root': {
+      borderRadius: ({ spacing }) => spacing(1, 1, 0, 0),
+    },
+    '&:last-of-type:not([aria-expanded=true]) .MuiButton-root': {
+      borderRadius: ({ spacing }) => spacing(0, 0, 1, 1),
+    },
+    '&:last-of-type': {
+      borderBottomWidth: 0,
+    },
+  },
+} satisfies Record<string, SxProps<Theme>>

package/src/chat/index.ts

@@ -0,0 +1,59 @@
+// Types
+export type {
+  ChatSxProps,
+  ChatErrorAction,
+  ChatUserMessageProps,
+  ChatAgentMessageProps,
+  ChatErrorMessageProps,
+  ChatSuggestionButtonProps,
+  ChatThinkingProps,
+  ChatLoaderProps,
+  ChatContentProps,
+  ChatContentRef,
+  ChatHeaderProps,
+  ChatFooterProps,
+  ChatStarterItem,
+  ChatStarterProps,
+  ChatRatingActionProps,
+  ChatToolItem,
+  ChatToolTraceProps,
+  ChatToolCodeAreaProps,
+  ChatToolFullViewDialogProps,
+  ChatToolGroupProps,
+} from './types'
+
+// Constants
+export {
+  CHAT_MAX_WIDTH,
+  CHAT_SCROLL_DELAY,
+  CHAT_DIVIDER_DELAY,
+  CHAT_TOOL_CODE_AREA_MAX_HEIGHT,
+} from './const'
+
+// Hooks
+export { useTypewriter } from './use-typewriter'
+
+// 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 { ChatToolTrace } from './feedback/chat-tool-trace'
+export { ChatToolCodeArea } from './feedback/chat-tool-code-area'
+export { ChatToolFullViewDialog } from './feedback/chat-tool-full-view-dialog'
+export { ChatToolGroup } from './feedback/chat-tool-group'