@carto/ps-react-ui 4.9.0 → 4.11.0

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)
+  })
+})

package/src/chat/use-typewriter.ts

@@ -0,0 +1,82 @@
+import { useEffect, useRef, useState } from 'react'
+
+interface UseTypewriterOptions {
+  /** Characters revealed per second (default: `500`). */
+  speed?: number
+  /** When true on mount, skip the animation and reveal the full text immediately. */
+  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`. Useful for smoothing out bursty WebSocket-streamed
+ * agent message 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 skipRef = useRef(skipAnimation)
+
+  const [charIndex, setCharIndex] = useState(() =>
+    skipRef.current ? fullText.length : 0,
+  )
+
+  useEffect(() => {
+    if (skipRef.current) {
+      setCharIndex(fullText.length)
+      return
+    }
+
+    if (charIndex >= fullText.length) {
+      return
+    }
+
+    const msPerChar = 1000 / speed
+    let rafId: number
+    let lastTime: number | null = null
+
+    function tick(timestamp: number) {
+      lastTime ??= timestamp
+
+      const elapsed = timestamp - lastTime
+      const charsToAdd = Math.floor(elapsed / msPerChar)
+
+      if (charsToAdd > 0) {
+        lastTime = timestamp
+        setCharIndex((prev) => Math.min(prev + charsToAdd, fullText.length))
+      }
+
+      rafId = requestAnimationFrame(tick)
+    }
+
+    rafId = requestAnimationFrame(tick)
+
+    return () => cancelAnimationFrame(rafId)
+  }, [fullText, charIndex, speed])
+
+  return {
+    displayedText: fullText.slice(0, charIndex),
+    isTyping: charIndex < fullText.length,
+  }
+}

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'

package/src/components/lasso-tool/styles.ts

@@ -7,6 +7,7 @@ export const styles = {
     alignItems: 'center',
     justifyContent: 'flex-start',
     overflow: 'hidden',
+    width: 'fit-content',
 
     '&.inline': {
       flexDirection: 'column',

package/src/components/measurement-tools/styles.ts

@@ -8,6 +8,7 @@ export const styles = {
     justifyContent: 'flex-start',
     gap: ({ spacing }) => spacing(1),
     overflow: 'hidden',
+    width: 'fit-content',
   },
   actions: {
     icon: {

package/src/widgets-v2/actions/index.ts

@@ -15,6 +15,14 @@ export {
   type StackToggleProps,
   type StackToggleLabels,
 } from './stack-toggle'
+export {
+  ShowAllToggle,
+  setShowAll,
+  SHOW_ALL_ID,
+  DEFAULT_SHOW_ALL_LABELS,
+  type ShowAllToggleProps,
+  type ShowAllLabels,
+} from './show-all'
 export {
   ZoomToggle,
   addZoom,

package/src/widgets-v2/actions/show-all/index.ts

@@ -0,0 +1,7 @@
+export {
+  ShowAllToggle,
+  setShowAll,
+  SHOW_ALL_ID,
+  type ShowAllToggleProps,
+} from './show-all'
+export { DEFAULT_SHOW_ALL_LABELS, type ShowAllLabels } from './labels'

package/src/widgets-v2/actions/show-all/labels.ts

@@ -0,0 +1,8 @@
+export interface ShowAllLabels {
+  /** Tooltip + aria-label for the collapse (✕) button shown while expanded. */
+  toggle: string
+}
+
+export const DEFAULT_SHOW_ALL_LABELS: ShowAllLabels = {
+  toggle: 'Show less',
+}

package/src/widgets-v2/actions/show-all/show-all.test.tsx

@@ -0,0 +1,50 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { fireEvent, render, screen } from '@testing-library/react'
+import { Provider } from '../../provider/widget-provider'
+import { clearAllWidgetStores, getWidgetStore } from '../../stores'
+import { ShowAllToggle, setShowAll, SHOW_ALL_ID } from './show-all'
+
+beforeEach(() => clearAllWidgetStores())
+afterEach(() => clearAllWidgetStores())
+
+describe('setShowAll', () => {
+  it('writes the flag under transformStates[SHOW_ALL_ID]', () => {
+    render(
+      <Provider id='sa1' data={[]}>
+        <span />
+      </Provider>,
+    )
+    setShowAll('sa1', true)
+    expect(
+      getWidgetStore('sa1').getState().transformStates[SHOW_ALL_ID]?.enabled,
+    ).toBe(true)
+    setShowAll('sa1', false)
+    expect(
+      getWidgetStore('sa1').getState().transformStates[SHOW_ALL_ID]?.enabled,
+    ).toBe(false)
+  })
+})
+
+describe('<ShowAllToggle>', () => {
+  it('renders a collapse (✕) button', () => {
+    render(
+      <Provider id='sa2' data={[]}>
+        <ShowAllToggle />
+      </Provider>,
+    )
+    expect(screen.getByRole('button', { name: 'Show less' })).toBeTruthy()
+  })
+
+  it('clears the flag on click (collapses)', () => {
+    render(
+      <Provider id='sa3' data={[]}>
+        <ShowAllToggle />
+      </Provider>,
+    )
+    setShowAll('sa3', true)
+    fireEvent.click(screen.getByRole('button', { name: 'Show less' }))
+    expect(
+      getWidgetStore('sa3').getState().transformStates[SHOW_ALL_ID]?.enabled,
+    ).toBe(false)
+  })
+})

package/src/widgets-v2/actions/show-all/show-all.tsx

@@ -0,0 +1,72 @@
+import { type ComponentType } from 'react'
+import { IconButton, type SvgIconProps } from '@mui/material'
+import CloseIcon from '@mui/icons-material/Close'
+import { Tooltip } from '../../../components'
+import { getWidgetStore, useWidgetId } from '../../stores'
+import { DEFAULT_SHOW_ALL_LABELS, type ShowAllLabels } from './labels'
+import { styles } from './style'
+
+/**
+ * The `show-all` flag is a pure UI signal (no data/config transform): the
+ * Category overflow row writes it `true` via {@link setShowAll}, the
+ * composer reads it with `useTransformEnabled(id, SHOW_ALL_ID)` to drop the
+ * row cap, and this button writes it back `false` to collapse. Stored under
+ * `transformStates` so `useTransformEnabled` can observe it like any other
+ * action flag — but it never registers a pipeline transform, so toggling it
+ * never re-runs the data pipeline.
+ */
+export const SHOW_ALL_ID = 'show-all'
+
+export interface ShowAllToggleProps {
+  labels?: Partial<ShowAllLabels>
+  icon?: ComponentType<SvgIconProps>
+  iconProps?: SvgIconProps
+}
+
+/**
+ * Collapse (✕) affordance shown while a widget is expanded into its
+ * "show all" state. Clicking it clears the `show-all` flag, returning the
+ * widget to its capped view. Mount it conditionally (only while the flag is
+ * set) so it doesn't occupy a `Widget.Toolbox` visibility-budget slot when
+ * the widget is collapsed.
+ */
+export function ShowAllToggle({
+  labels,
+  icon: Icon = CloseIcon,
+  iconProps,
+}: ShowAllToggleProps) {
+  const id = useWidgetId()
+  const _labels = { ...DEFAULT_SHOW_ALL_LABELS, ...labels }
+
+  return (
+    <Tooltip title={_labels.toggle}>
+      <IconButton
+        size='small'
+        aria-label={_labels.toggle}
+        aria-pressed
+        onClick={() => setShowAll(id, false)}
+        sx={styles.toggle}
+      >
+        <Icon fontSize='small' {...iconProps} />
+      </IconButton>
+    </Tooltip>
+  )
+}
+
+/**
+ * Imperatively writes the `show-all` flag into the widget store. Mirrors
+ * {@link setSearcherText} — used by the Category overflow row (to expand)
+ * and the {@link ShowAllToggle} button (to collapse) without routing through
+ * a re-rendered subscription.
+ */
+export function setShowAll(widgetId: string, value: boolean): void {
+  getWidgetStore(widgetId).setState((s) => ({
+    transformStates: {
+      ...s.transformStates,
+      [SHOW_ALL_ID]: {
+        ...s.transformStates[SHOW_ALL_ID],
+        enabled: value,
+      },
+    },
+  }))
+}

package/src/widgets-v2/actions/show-all/style.ts

@@ -0,0 +1,8 @@
+import type { SxProps, Theme } from '@mui/material'
+
+export const styles = {
+  toggle: {
+    p: 0.5,
+    '& .MuiSvgIcon-root': { fontSize: 20 },
+  },
+} satisfies Record<string, SxProps<Theme>>