@carto/ps-react-ui 5.0.0-widgets.8 → 5.0.0

package/src/chat/types.ts

@@ -0,0 +1,247 @@
+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 ChatAgentMessageMarkdownProps extends ChatSxProps {
+  /**
+   * Markdown source — rendered as GitHub-Flavored Markdown (tables, task lists,
+   * strikethrough) through the library's sanitized renderer, inside a
+   * `ChatAgentMessage`. Raw HTML is skipped and images are stripped, since the
+   * content is model output.
+   */
+  children: string
+}
+
+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
+    /** `aria-label` for the model-selector trigger. Defaults to `'Select model'`. */
+    model?: string
+  }
+  /** Helper text rendered under the input. Defaults to an AI disclaimer; pass `null` to hide. */
+  caption?: ReactNode
+  /**
+   * Selectable models for the in-toolbar model selector. The selector is only
+   * rendered when this is a non-empty array; the component is otherwise
+   * model-agnostic (the host owns the list, selection, and default).
+   */
+  models?: ChatModelOption[]
+  /** Currently selected model `value`. Controlled — the host owns the state. */
+  selectedModel?: string
+  /** Called with the picked model `value` when the user selects one. */
+  onModelChange?: (value: string) => void
+  /** Extra controls rendered at the start (left) of the toolbar, before the model selector. */
+  startToolbarSlot?: ReactNode
+  /** Extra controls rendered at the end (right) of the toolbar, before the send/stop button. */
+  endToolbarSlot?: ReactNode
+}
+
+/** An option for the `ChatFooter` model selector. */
+export interface ChatModelOption {
+  value: string
+  label: string
+}
+
+// === 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)
+  })
+})

package/src/chat/use-typewriter.ts

@@ -0,0 +1,90 @@
+import { useEffect, useRef, useState } from 'react'
+
+interface UseTypewriterOptions {
+  /** Characters revealed per second (default: `500`). */
+  speed?: number
+  /** When true, reveal the full text immediately (and snap to it if it grows). */
+  skipAnimation?: boolean
+}
+
+interface UseTypewriterResult {
+  /** The portion of `fullText` revealed so far. */
+  displayedText: string
+  /** `true` while characters are still being revealed. */
+  isTyping: boolean
+}
+
+/**
+ * Reveals a string character-by-character at a steady rate via
+ * `requestAnimationFrame`. Designed for bursty, streamed agent text: as
+ * `fullText` grows the reveal keeps chasing the new end, and flipping
+ * `skipAnimation` to `true` (e.g. once generation finishes) snaps to the full
+ * text. Pair it with `ChatAgentMessage`.
+ *
+ * @example
+ * ```tsx
+ * const { displayedText, isTyping } = useTypewriter(message)
+ * return (
+ *   <ChatAgentMessage>
+ *     <Markdown>{displayedText}</Markdown>
+ *     {isTyping ? <Cursor /> : null}
+ *   </ChatAgentMessage>
+ * )
+ * ```
+ */
+export function useTypewriter(
+  fullText: string,
+  options: UseTypewriterOptions = {},
+): UseTypewriterResult {
+  const { speed = 500, skipAnimation = false } = options
+
+  const [charIndex, setCharIndex] = useState(() =>
+    skipAnimation ? fullText.length : 0,
+  )
+
+  // Mirror of the revealed count, read/written ONLY inside the rAF loop (never
+  // during render). This lets the animation effect omit `charIndex` from its
+  // deps: were it a dep, the loop would tear down and restart on every revealed
+  // frame — resetting its frame timer — and never accumulate the elapsed time
+  // needed to advance, which stalls completely while `fullText` is also growing
+  // (the streaming case).
+  const charRef = useRef(charIndex)
+
+  useEffect(() => {
+    // When `skipAnimation` is set there's nothing to animate — the full text is
+    // shown directly via the derived `displayedText` below (no setState here, so
+    // a streamed message snaps to its full text the moment generation finishes,
+    // without an extra render or a `set-state-in-effect` cascade).
+    if (skipAnimation) return
+
+    // Already fully revealed (e.g. text hasn't grown since the last frame).
+    if (charRef.current >= fullText.length) return
+
+    const msPerChar = 1000 / speed
+    let rafId: number
+    let lastTime: number | null = null
+
+    function tick(timestamp: number) {
+      // Plain `?? =` not `??=`: the React Compiler can't lower logical-assignment
+      // operators and would bail this hook out of optimization.
+      lastTime = lastTime ?? timestamp
+      const charsToAdd = Math.floor((timestamp - lastTime) / msPerChar)
+      if (charsToAdd > 0) {
+        lastTime = timestamp
+        const next = Math.min(charRef.current + charsToAdd, fullText.length)
+        charRef.current = next
+        setCharIndex(next)
+        if (next >= fullText.length) return // fully revealed — stop the loop
+      }
+      rafId = requestAnimationFrame(tick)
+    }
+
+    rafId = requestAnimationFrame(tick)
+    return () => cancelAnimationFrame(rafId)
+  }, [fullText, speed, skipAnimation])
+
+  return {
+    displayedText: skipAnimation ? fullText : fullText.slice(0, charIndex),
+    isTyping: !skipAnimation && charIndex < fullText.length,
+  }
+}

package/src/components/basemaps/basemaps.test.tsx

@@ -0,0 +1,196 @@
+import { describe, test, expect, vi, beforeEach } from 'vitest'
+import { render, screen, fireEvent } from '@testing-library/react'
+import { BasemapsUI } from './basemaps'
+import type { BasemapOption } from './types'
+
+// Mock the child components
+vi.mock('./header', () => ({
+  Header: ({ onChangeCollapsed }: { onChangeCollapsed: () => void }) => (
+    <div data-testid='mock-header'>
+      <button data-testid='close-button' onClick={onChangeCollapsed}>
+        Close
+      </button>
+    </div>
+  ),
+}))
+
+vi.mock('./group', () => ({
+  Group: ({
+    values,
+    selected,
+    onChange,
+  }: {
+    values: BasemapOption[]
+    selected: string | null
+    onChange: (id: string) => void
+  }) => (
+    <div data-testid='mock-group'>
+      {values.map((option) => (
+        <button
+          key={option.id}
+          data-testid={`basemap-option-${option.id}`}
+          data-selected={option.id === selected}
+          onClick={() => onChange(option.id)}
+        >
+          {option.label}
+        </button>
+      ))}
+    </div>
+  ),
+}))
+
+vi.mock('./group-wrapper', () => ({
+  GroupWrapper: ({
+    title,
+    children,
+  }: {
+    title: string
+    children: React.ReactNode
+  }) => (
+    <div data-testid='mock-group-wrapper' data-title={title}>
+      {children}
+    </div>
+  ),
+}))
+
+vi.mock('../responsive-drawer/responsive-drawer', () => ({
+  ResponsiveDrawer: ({
+    children,
+    collapsed,
+  }: {
+    children: React.ReactNode
+    collapsed: boolean
+  }) => (
+    <div data-testid='mock-drawer' data-collapsed={collapsed}>
+      {children}
+    </div>
+  ),
+}))
+
+describe('BasemapsUI', () => {
+  const mockOptions: BasemapOption[] = [
+    { id: 'basemap1', label: 'Basemap 1', icon: 'icon1.png', group: 'Group 1' },
+    { id: 'basemap2', label: 'Basemap 2', icon: 'icon2.png', group: 'Group 1' },
+    { id: 'basemap3', label: 'Basemap 3', icon: 'icon3.png', group: 'Group 2' },
+  ]
+
+  const mockOnChange = vi.fn()
+
+  beforeEach(() => {
+    mockOnChange.mockReset()
+  })
+
+  test('should render with toggle button initially', () => {
+    render(
+      <BasemapsUI
+        options={mockOptions}
+        selected='basemap1'
+        onChange={mockOnChange}
+      />,
+    )
+
+    // Drawer should be collapsed initially
+    const drawer = screen.getByTestId('mock-drawer')
+    expect(drawer.getAttribute('data-collapsed')).toBe('true')
+
+    // Toggle button should be visible
+    expect(screen.getAllByRole('button')[0]).toBeDefined()
+  })
+
+  test('should show drawer when toggle button is clicked', () => {
+    render(
+      <BasemapsUI
+        options={mockOptions}
+        selected='basemap1'
+        onChange={mockOnChange}
+      />,
+    )
+
+    // Click toggle button
+    const toggleButton = screen.getAllByRole('button')[0]!
+    fireEvent.click(toggleButton)
+
+    // Drawer should not be collapsed after toggle
+    const drawer = screen.getByTestId('mock-drawer')
+    expect(drawer.getAttribute('data-collapsed')).toBe('false')
+  })
+
+  test('should pass correct props to Group component', () => {
+    render(
+      <BasemapsUI
+        options={mockOptions}
+        selected='basemap1'
+        onChange={mockOnChange}
+      />,
+    )
+
+    // Click toggle button to show drawer
+    const toggleButton = screen.getAllByRole('button')[0]!
+    fireEvent.click(toggleButton)
+
+    // Group wrappers should be rendered with correct titles
+    const groupWrappers = screen.getAllByTestId('mock-group-wrapper')
+    expect(groupWrappers.length).toBe(2) // Two groups
+    expect(groupWrappers[0]?.getAttribute('data-title')).toContain('Group 1')
+    expect(groupWrappers[1]?.getAttribute('data-title')).toContain('Group 2')
+
+    // Check basemap options are rendered
+    expect(screen.getByTestId('basemap-option-basemap1')).toBeDefined()
+    expect(screen.getByTestId('basemap-option-basemap2')).toBeDefined()
+    expect(screen.getByTestId('basemap-option-basemap3')).toBeDefined()
+  })
+
+  test('should call onChange when a basemap is selected', () => {
+    render(
+      <BasemapsUI
+        options={mockOptions}
+        selected='basemap1'
+        onChange={mockOnChange}
+      />,
+    )
+
+    // Click toggle button to show drawer
+    const toggleButton = screen.getAllByRole('button')[0]!
+    fireEvent.click(toggleButton)
+
+    // Click a basemap option
+    const basemapOption = screen.getByTestId('basemap-option-basemap2')
+    fireEvent.click(basemapOption)
+
+    // onChange should be called with correct ID
+    expect(mockOnChange).toHaveBeenCalledWith('basemap2')
+  })
+
+  test('should handle small devices correctly using media query', () => {
+    // Mock matchMedia for small devices
+    window.matchMedia = vi.fn().mockImplementation((query: string) => ({
+      matches: query.includes('max-width'),
+      media: query,
+      onchange: null,
+      addListener: vi.fn(),
+      removeListener: vi.fn(),
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+      dispatchEvent: vi.fn(),
+    }))
+
+    render(
+      <BasemapsUI
+        options={mockOptions}
+        selected='basemap1'
+        onChange={mockOnChange}
+        position='bottom-right'
+      />,
+    )
+
+    // Check if drawer behavior is appropriate for small devices
+    const drawer = screen.getByTestId('mock-drawer')
+
+    // Toggle button should still be visible on small devices
+    const toggleButton = screen.getAllByRole('button')[0]
+    expect(toggleButton).toBeDefined()
+
+    // Drawer should be collapsed initially even on small devices
+    expect(drawer.getAttribute('data-collapsed')).toBe('true')
+  })
+})