@carto/ps-react-ui 4.9.1 → 4.11.1

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'

package/src/chat/types.ts

@@ -0,0 +1,215 @@
+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
+  /**
+   * Smooth-scrolls to the bottom whenever new content is added — but only if
+   * the user was already at (or near) the bottom. Readers who scrolled up to
+   * revisit older messages are left alone. Defaults to `true`; pass `false`
+   * to opt out and manage scroll yourself via the ref.
+   */
+  autoScroll?: boolean
+  labels?: {
+    jumpToLatest?: string
+  }
+}
+
+/**
+ * Imperative handle exposed by `ChatContent` via `ref`. Use it to drive scroll
+ * from the parent — for example, calling `scrollToBottom()` when a new agent
+ * message arrives.
+ */
+export interface ChatContentRef {
+  /** Smooth-scrolls the content area to the bottom. */
+  scrollToBottom: () => void
+  /** Smooth-scrolls the content area to the top. */
+  scrollToTop: () => void
+  /** `true` when the content area is scrolled to (or near) its bottom edge. */
+  isAtBottom: boolean
+  /** `true` when the content area is scrolled to (or near) its top edge. */
+  isAtTop: boolean
+}
+
+// === Container props ===
+export interface ChatHeaderProps extends ChatSxProps {
+  leftSlot?: ReactNode
+  title: ReactNode
+  rightSlot?: ReactNode
+  onClose?: () => void
+}
+
+export interface ChatFooterProps extends ChatSxProps {
+  /** Current value of the chat message area. */
+  value: string
+  /** Called with the new textarea value on every keystroke. */
+  onChange: (value: string) => void
+  /** Called when the send button is clicked or Enter is pressed (without Shift). */
+  onSend: () => void
+  /** Called when the stop button is clicked. Only shown while `isGenerating` is true. */
+  onStop?: () => void
+  /** When true, swaps the send button for a stop button and disables the textarea. */
+  isGenerating?: boolean
+  /** Disables the textarea and both send/stop buttons. */
+  disabled?: boolean
+  /** Placeholder text for the textarea. Defaults to `'Type a message...'`. */
+  placeholder?: string
+  /** Accessible labels for the send and stop buttons (used as `aria-label`). */
+  labels?: {
+    /** Defaults to `'Send'`. */
+    send?: string
+    /** Defaults to `'Stop'`. */
+    stop?: string
+  }
+  /** Helper text rendered under the input. Defaults to an AI disclaimer; pass `null` to hide. */
+  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 ChatRatingActionProps {
+  onRatingChange?: (rating: 'up' | 'down' | null) => void
+  rating?: 'up' | 'down' | null
+  labels?: {
+    thumbUp?: string
+    thumbDown?: string
+  }
+}
+
+export interface ChatToolItem {
+  id: string
+  name: string
+  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 ChatToolCodeAreaProps extends ChatSxProps {
+  /** Code content to display */
+  content: string
+  /** Label for the full view dialog title */
+  title?: string
+  /** Render with error styling (red left border, tinted background) */
+  isError?: boolean
+  labels?: {
+    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/src/chat/use-typewriter.test.tsx

@@ -0,0 +1,38 @@
+import { describe, expect, test } from 'vitest'
+import { renderHook } from '@testing-library/react'
+import { useTypewriter } from './use-typewriter'
+
+describe('useTypewriter', () => {
+  test('starts with empty text and isTyping=true when fullText is non-empty', () => {
+    const { result } = renderHook(() => useTypewriter('hello'))
+    expect(result.current.displayedText).toBe('')
+    expect(result.current.isTyping).toBe(true)
+  })
+
+  test('returns the full text immediately when skipAnimation is true', () => {
+    const { result } = renderHook(() =>
+      useTypewriter('hello', { skipAnimation: true }),
+    )
+    expect(result.current.displayedText).toBe('hello')
+    expect(result.current.isTyping).toBe(false)
+  })
+
+  test('isTyping=false for empty fullText', () => {
+    const { result } = renderHook(() => useTypewriter(''))
+    expect(result.current.displayedText).toBe('')
+    expect(result.current.isTyping).toBe(false)
+  })
+
+  test('skipAnimation captured at mount — toggling later does not retrigger reveal', () => {
+    const { result, rerender } = renderHook(
+      ({ skip }: { skip: boolean }) =>
+        useTypewriter('hello', { skipAnimation: skip }),
+      { initialProps: { skip: true } },
+    )
+    expect(result.current.displayedText).toBe('hello')
+
+    rerender({ skip: false })
+    expect(result.current.displayedText).toBe('hello')
+    expect(result.current.isTyping).toBe(false)
+  })
+})