@carto/ps-react-ui 4.4.0-chat-ui.1 → 4.4.0-chat-ui.3

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

@@ -0,0 +1,187 @@
+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} className={`PsChat--tool-trace ${tool.name}`}>
+      <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

@@ -2,4 +2,7 @@ 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'
+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

@@ -65,16 +65,165 @@ export const styles = {
     backgroundColor: ({ palette }) => palette.text.primary,
     animation: `${breatheInner} 1s ease-in-out infinite`,
   },
-  tools: {
+  // --- 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%',
   },
-  toolHeader: {
+  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',
-    gap: ({ spacing }) => spacing(1),
+    justifyContent: 'space-between',
+    padding: ({ spacing }) => spacing(2),
+    borderBottom: '1px solid',
+    borderBottomColor: 'divider',
+  },
+  fullViewDialogContent: {
+    padding: 0,
+    '&:first-of-type': { paddingTop: 0 },
   },
-  toolStatusIcon: {
+  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

@@ -16,11 +16,19 @@ export type {
   ChatActionsContainerProps,
   ChatRatingActionProps,
   ChatToolItem,
-  ChatToolsProps,
+  ChatToolTraceProps,
+  ChatToolCodeAreaProps,
+  ChatToolFullViewDialogProps,
+  ChatToolGroupProps,
 } from './types'
 
 // Constants
-export { CHAT_MAX_WIDTH, CHAT_SCROLL_DELAY, CHAT_DIVIDER_DELAY } from './const'
+export {
+  CHAT_MAX_WIDTH,
+  CHAT_SCROLL_DELAY,
+  CHAT_DIVIDER_DELAY,
+  CHAT_TOOL_CODE_AREA_MAX_HEIGHT,
+} from './const'
 
 // Messages
 export { ChatUserMessage } from './bubbles/chat-user-message'
@@ -42,4 +50,7 @@ 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'
+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'

package/src/chat/types.ts

@@ -112,13 +112,72 @@ export interface ChatRatingActionProps {
 export interface ChatToolItem {
   id: string
   name: string
-  status: 'loading' | 'thinking' | 'complete' | 'error'
-  content?: ReactNode
+  status: 'running' | 'complete' | 'error'
+  /** Display label shown while status is 'running'. Falls back to a capitalized `name`. */
+  runningLabel?: string
+  /** Display label shown for non-running statuses. Falls back to a capitalized `name`. */
+  label?: string
+  /** Friendly reference name for the tool (e.g. "add_marker"). Displayed with icon. */
+  reference?: string
+  /** Execution duration in seconds (e.g. 1.8) */
+  duration?: number
+  /** Input arguments as a JSON string or plain text */
+  inputArguments?: string
+  /** Output as a JSON string or plain text */
+  output?: string
+}
+
+export interface ChatToolTraceProps extends ChatSxProps {
+  tool: ChatToolItem
+  /** Whether the trace accordion is expanded */
+  expanded?: boolean
+  /** Callback when accordion expansion state changes */
+  onExpandedChange?: (expanded: boolean) => void
+  labels?: {
+    toolExecuted?: string
+    reference?: string
+    duration?: string
+    status?: string
+    inputArguments?: string
+    output?: string
+    fullView?: string
+    success?: string
+    error?: string
+    running?: string
+  }
 }
 
-export interface ChatToolsProps extends ChatSxProps {
-  tools: ChatToolItem[]
+export interface ChatToolCodeAreaProps extends ChatSxProps {
+  /** Code content to display */
+  content: string
+  /** Label for the full view dialog title */
+  title?: string
   labels?: {
-    title?: string
+    fullView?: string
+  }
+}
+
+export interface ChatToolFullViewDialogProps {
+  open: boolean
+  onClose: () => void
+  title: string
+  content: string
+}
+
+export interface ChatToolGroupProps extends ChatSxProps {
+  tools: ChatToolItem[]
+  /** Whether the group accordion is expanded */
+  expanded?: boolean
+  /** Callback when group expansion state changes */
+  onExpandedChange?: (expanded: boolean) => void
+  /** Map of tool IDs to their individual expanded state. Used to preserve expansion state during grouping. */
+  expandedTools?: Record<string, boolean>
+  /** Callback when an individual tool's expansion state changes */
+  onToolExpandedChange?: (
+    value: Record<string, boolean>,
+    toolId?: string,
+  ) => void
+  labels?: ChatToolTraceProps['labels'] & {
+    toolsUsed?: string
   }
 }

package/dist/types/chat/feedback/chat-tools.d.ts

@@ -1,2 +0,0 @@
-import { ChatToolsProps } from '../types';
-export declare function ChatTools({ tools, labels, sx }: ChatToolsProps): import("react/jsx-runtime").JSX.Element;

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

@@ -1,23 +0,0 @@
-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()
-  })
-})

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

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