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

package/src/components/smart-tooltip/smart-tooltip.test.tsx

@@ -0,0 +1,168 @@
+import { describe, test, expect, vi, beforeEach, afterEach } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import * as React from 'react'
+import { SmartTooltip } from './smart-tooltip'
+
+// Mock the useLayoutEffect hook for testing overflow scenarios
+vi.mock('react', async () => {
+  const actual = await vi.importActual('react')
+  return {
+    ...actual,
+    useLayoutEffect: (callback: () => void) => {
+      callback()
+    },
+  }
+})
+
+// Setup timers for useLayoutEffect timeout
+beforeEach(() => {
+  vi.useFakeTimers()
+})
+
+afterEach(() => {
+  vi.restoreAllMocks()
+  vi.useRealTimers()
+})
+
+describe('SmartTooltip', () => {
+  const defaultProps = {
+    title: 'Test Label',
+    children: ({ ref }: { ref: React.Ref<HTMLElement> }) => (
+      <div ref={ref as React.Ref<HTMLDivElement>} data-testid='test-child'>
+        Content
+      </div>
+    ),
+  }
+
+  test('renders correctly with child element', () => {
+    render(<SmartTooltip {...defaultProps} />)
+    const child = screen.getByTestId('test-child')
+    expect(child).toBeTruthy()
+    expect(child.textContent).toBe('Content')
+  })
+
+  test('passes ref to children function', () => {
+    const childrenSpy = vi
+      .fn()
+      .mockReturnValue(<div data-testid='test-child'>Content</div>)
+    render(<SmartTooltip title='Test Label'>{childrenSpy}</SmartTooltip>)
+
+    expect(childrenSpy).toHaveBeenCalledTimes(1)
+    // Just check that a ref was passed
+    expect(childrenSpy).toHaveBeenCalled()
+  })
+
+  test('handles undefined title', () => {
+    render(
+      <SmartTooltip title={undefined}>
+        {({ ref }) => (
+          <div ref={ref as React.Ref<HTMLDivElement>} data-testid='test-child'>
+            Content
+          </div>
+        )}
+      </SmartTooltip>,
+    )
+    const child = screen.getByTestId('test-child')
+    expect(child).toBeTruthy()
+  })
+
+  test('updates isOverflowing state when dependencies change', () => {
+    const { rerender } = render(
+      <SmartTooltip title='Test Label' dependencies={[1]}>
+        {({ ref }) => (
+          <div ref={ref as React.Ref<HTMLDivElement>} data-testid='test-child'>
+            Content
+          </div>
+        )}
+      </SmartTooltip>,
+    )
+
+    // Re-render with different dependencies to trigger useLayoutEffect
+    rerender(
+      <SmartTooltip title='Test Label' dependencies={[2]}>
+        {({ ref }) => (
+          <div ref={ref as React.Ref<HTMLDivElement>} data-testid='test-child'>
+            Content
+          </div>
+        )}
+      </SmartTooltip>,
+    )
+
+    expect(screen.getByTestId('test-child')).toBeTruthy()
+  })
+
+  test('tooltip behavior with overflowing content', () => {
+    // Mock the ref.current properties to simulate overflow
+    vi.spyOn(React, 'useRef').mockReturnValue({
+      current: {
+        scrollWidth: 100,
+        clientWidth: 50,
+        scrollHeight: 100,
+        clientHeight: 50,
+      },
+    } as React.RefObject<HTMLDivElement>)
+
+    render(<SmartTooltip {...defaultProps} />)
+
+    // Force the timeout in useLayoutEffect to execute
+    vi.runAllTimers()
+
+    // Verify the tooltip has the correct title
+    const tooltipWrapper = screen.getByTestId('test-child')
+    expect(tooltipWrapper).toBeTruthy()
+  })
+
+  test('tooltip behavior with non-overflowing content', () => {
+    // Mock the ref.current properties to simulate no overflow
+    vi.spyOn(React, 'useRef').mockReturnValue({
+      current: {
+        scrollWidth: 50,
+        clientWidth: 100,
+        scrollHeight: 50,
+        clientHeight: 100,
+      },
+    } as React.RefObject<HTMLDivElement>)
+
+    render(<SmartTooltip {...defaultProps} />)
+
+    // Force the timeout in useLayoutEffect to execute
+    vi.runAllTimers()
+
+    // Verify the tooltip doesn't have a title (since there's no overflow)
+    const tooltipWrapper = screen.getByTestId('test-child')
+    expect(tooltipWrapper).toBeTruthy()
+    // Check that the title attribute is not set since content is not overflowing
+    expect(tooltipWrapper?.getAttribute('title')).toBeFalsy()
+  })
+
+  test('accepts custom timeout parameter', () => {
+    const customTimeout = 1000
+
+    // Spy on setTimeout to verify it's called with the custom timeout
+    const setTimeoutSpy = vi.spyOn(global, 'setTimeout')
+
+    render(<SmartTooltip {...defaultProps} timeout={customTimeout} />)
+
+    expect(setTimeoutSpy).toHaveBeenCalledWith(
+      expect.any(Function),
+      customTimeout,
+    )
+
+    setTimeoutSpy.mockRestore()
+  })
+
+  test('passes TooltipProps to the Tooltip component', () => {
+    render(
+      <SmartTooltip
+        {...defaultProps}
+        TooltipProps={{
+          placement: 'bottom',
+          arrow: true,
+        }}
+      />,
+    )
+
+    const tooltipWrapper = screen.getByTestId('test-child')
+    expect(tooltipWrapper).toBeTruthy()
+  })
+})

package/src/components/smart-tooltip/smart-tooltip.tsx

@@ -0,0 +1,74 @@
+import type { TooltipProps } from '@mui/material'
+import { useLayoutEffect, useRef, useState, type JSX, type Ref } from 'react'
+import { Tooltip } from '../tooltip/tooltip'
+
+const EMPTY_DEPENDENCIES: unknown[] = []
+
+/**
+ * An intelligent tooltip wrapper that automatically detects text overflow and displays a tooltip only when content is truncated.
+ *
+ * @remarks
+ * Uses a render prop pattern. The child function receives a `ref` that must be attached to the element being monitored for overflow. Use the `dependencies` array to trigger re-evaluation when content or container size changes.
+ *
+ * @example
+ * ```tsx
+ * <SmartTooltip title="This is a long text that might get truncated">
+ *   {({ ref }) => (
+ *     <Typography ref={ref} noWrap sx={{ overflow: 'hidden', textOverflow: 'ellipsis' }}>
+ *       This is a long text that might get truncated
+ *     </Typography>
+ *   )}
+ * </SmartTooltip>
+ * ```
+ */
+export function SmartTooltip<T extends HTMLElement>({
+  title,
+  dependencies = EMPTY_DEPENDENCIES,
+  timeout = 500,
+  TooltipProps,
+  children,
+}: {
+  title: string | undefined
+  dependencies?: unknown[]
+  timeout?: number
+  children: (props: { ref: Ref<T> }) => JSX.Element
+  TooltipProps?: Partial<TooltipProps>
+}) {
+  const ref = useRef<T>(null)
+  const [isOverflowing, setIsOverflowing] = useState(false)
+  // Call sites pass a fresh `dependencies={[…]}` literal each render; key by
+  // value so the effect does not churn ResizeObserver on referential churn.
+  const dependenciesKey = JSON.stringify(dependencies)
+
+  useLayoutEffect(() => {
+    const checkOverflow = () => {
+      const el = ref.current
+      if (!el) return
+      setIsOverflowing(
+        el.scrollWidth > el.clientWidth || el.scrollHeight > el.clientHeight,
+      )
+    }
+
+    // Initial measure after layout settles (fonts, flex collapse, …).
+    const timerId = setTimeout(checkOverflow, timeout)
+    // Re-measure when the element is resized (e.g. legend title reflows as
+    // hover-faded actions collapse/expand).
+    const el = ref.current
+    const resizeObserver =
+      el && typeof ResizeObserver !== 'undefined'
+        ? new ResizeObserver(checkOverflow)
+        : null
+    if (el) resizeObserver?.observe(el)
+
+    return () => {
+      clearTimeout(timerId)
+      resizeObserver?.disconnect()
+    }
+  }, [dependenciesKey, timeout])
+
+  return (
+    <Tooltip title={isOverflowing && title} {...TooltipProps}>
+      {children({ ref })}
+    </Tooltip>
+  )
+}

package/src/components/tooltip/tooltip.test.tsx

@@ -0,0 +1,86 @@
+import { describe, expect, test } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import { Tooltip, setTooltipEnterDelay } from './tooltip'
+
+describe('Tooltip', () => {
+  test('renders children correctly', () => {
+    render(
+      <Tooltip title='Test tooltip'>
+        <button>Hover me</button>
+      </Tooltip>,
+    )
+
+    expect(screen.getByText('Hover me')).toBeTruthy()
+  })
+
+  test('uses default enterNextDelay of 1000ms', () => {
+    render(
+      <Tooltip title='Test tooltip'>
+        <button>Hover me</button>
+      </Tooltip>,
+    )
+
+    // Since we're wrapping MUI Tooltip and not altering its behavior much,
+    // and MUI applies most props internally, we can't easily test the
+    // enterNextDelay prop directly. Instead, we verify the component renders.
+    expect(screen.getByText('Hover me')).toBeTruthy()
+  })
+
+  test('accepts custom enterNextDelay', () => {
+    render(
+      <Tooltip title='Test tooltip' enterNextDelay={500}>
+        <button>Hover me</button>
+      </Tooltip>,
+    )
+
+    // Similar to above test, we mainly ensure the component renders correctly
+    expect(screen.getByText('Hover me')).toBeTruthy()
+  })
+
+  test('passes additional props to MUI Tooltip', () => {
+    render(
+      <Tooltip
+        title='Test tooltip'
+        placement='bottom'
+        arrow={true}
+        data-testid='custom-tooltip'
+      >
+        <button>Hover me</button>
+      </Tooltip>,
+    )
+
+    // Verify that our wrapper properly passes through props
+    const tooltipWrapper = screen
+      .getByText('Hover me')
+      .closest('[data-testid="custom-tooltip"]')
+    expect(tooltipWrapper).toBeTruthy()
+  })
+
+  test('setTooltipEnterDelay function sets the delay', () => {
+    const delay = 700
+    setTooltipEnterDelay(delay)
+
+    // We can't test the internal implementation, but we can ensure that
+    // the function can be called without errors.
+    expect(() => setTooltipEnterDelay(delay)).not.toThrow()
+  })
+
+  test('setTooltipEnterDelay updates the default enter delay', () => {
+    const newDelay = 2000
+    setTooltipEnterDelay(newDelay)
+
+    render(
+      <Tooltip title='Test tooltip'>
+        <button>Hover me</button>
+      </Tooltip>,
+    )
+
+    // After setting a new delay, the component should use that as the default
+    // We can verify by checking the props passed to the rendered component
+    const tooltipElement = screen.getByText('Hover me').parentElement
+    expect(tooltipElement).toBeTruthy()
+
+    // Reset the delay for other tests
+    setTooltipEnterDelay(1000)
+  })
+})

package/src/components/tooltip/tooltip.tsx

@@ -0,0 +1,43 @@
+import { Tooltip as MuiTooltip, type TooltipProps } from '@mui/material'
+
+let tooltipEnterDelay = 500
+
+/**
+ * A wrapper around MUI's Tooltip component with enterNextDelay set to 1000ms by default.
+ *
+ * This component ensures consistent tooltip behavior across the application.
+ *
+ * @example
+ * <Tooltip title="This is a tooltip">
+ *   <Button>Hover me</Button>
+ * </Tooltip>
+ */
+export function Tooltip({
+  children,
+  title,
+  enterNextDelay = tooltipEnterDelay,
+  ...props
+}: TooltipProps) {
+  return (
+    <MuiTooltip title={title} enterNextDelay={enterNextDelay} {...props}>
+      {children}
+    </MuiTooltip>
+  )
+}
+
+/**
+ * Sets the global default `enterNextDelay` for all Tooltip components in the application.
+ *
+ * @param delay - Delay in milliseconds before showing tooltips on subsequent hovers.
+ *
+ * @example
+ * ```tsx
+ * import { setTooltipEnterDelay } from '@carto/ps-react-ui/components';
+ *
+ * // Set global delay to 300ms at app initialization
+ * setTooltipEnterDelay(300);
+ * ```
+ */
+export function setTooltipEnterDelay(delay: number) {
+  tooltipEnterDelay = delay
+}

package/src/components/types.ts

@@ -0,0 +1 @@
+export * from './common-types'

package/src/components/zoom-controls/styles.ts

@@ -0,0 +1,27 @@
+import type { SxProps, Theme } from '@mui/material'
+
+export const styles = {
+  zoom: {
+    position: 'relative',
+    height: ({ spacing }) => spacing(4),
+    aspectRatio: 1,
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  paper: {
+    display: 'flex',
+    backgroundColor: ({ palette }) => palette.background.paper,
+    width: 'auto',
+    overflow: 'hidden',
+    boxShadow: ({ shadows }) => shadows[1],
+    borderRadius: ({ spacing }) => spacing(0.5),
+
+    button: {
+      borderRadius: 0,
+    },
+  },
+  circularProgress: {
+    position: 'absolute',
+  },
+} satisfies Record<string, SxProps<Theme>>

package/src/components/zoom-controls/types.ts

@@ -0,0 +1,19 @@
+import type { Paper } from '@mui/material'
+import type { ComponentProps, ElementType } from 'react'
+
+export interface ZoomControlProps {
+  zoom: number
+  direction?: 'vertical' | 'horizontal'
+  reverse?: boolean
+  disabled?: boolean
+  isLoading?: boolean
+  maxZoom?: number
+  minZoom?: number
+  PaperProps?: ComponentProps<typeof Paper>
+  ResetViewProps?: {
+    Icon: ElementType
+  }
+  showZoom?: boolean
+  onChange: (zoom: number) => void
+  onReset?: () => void
+}

package/src/components/zoom-controls/zoom-controls.test.tsx

@@ -0,0 +1,101 @@
+import { describe, test, expect, vi } from 'vitest'
+import { render, screen, fireEvent } from '@testing-library/react'
+import { ZoomControlsUI } from './zoom-controls'
+
+describe('ZoomControlsUI', () => {
+  const defaultProps = {
+    zoom: 10,
+    onChange: vi.fn(),
+  }
+
+  test('renders correctly with default props', () => {
+    render(<ZoomControlsUI {...defaultProps} />)
+
+    expect(screen.getByLabelText('Increase zoom')).toBeTruthy()
+    expect(screen.getByLabelText('Decrease zoom')).toBeTruthy()
+    expect(screen.getByText('10')).toBeTruthy()
+  })
+
+  test('handles zoom increase correctly', () => {
+    render(<ZoomControlsUI {...defaultProps} />)
+
+    fireEvent.click(screen.getByLabelText('Increase zoom'))
+    expect(defaultProps.onChange).toHaveBeenCalledWith(11)
+  })
+
+  test('handles zoom decrease correctly', () => {
+    render(<ZoomControlsUI {...defaultProps} />)
+
+    fireEvent.click(screen.getByLabelText('Decrease zoom'))
+    expect(defaultProps.onChange).toHaveBeenCalledWith(9)
+  })
+
+  test('respects min and max zoom limits', () => {
+    const props = {
+      ...defaultProps,
+      zoom: 24,
+      maxZoom: 24,
+      minZoom: 5,
+    }
+
+    const { rerender } = render(<ZoomControlsUI {...props} />)
+
+    fireEvent.click(screen.getByLabelText('Increase zoom'))
+    expect(props.onChange).toHaveBeenCalledWith(24) // Should not exceed maxZoom
+
+    props.zoom = 5
+    rerender(<ZoomControlsUI {...props} />)
+
+    fireEvent.click(screen.getByLabelText('Decrease zoom'))
+    expect(props.onChange).toHaveBeenCalledWith(5) // Should not go below minZoom
+  })
+
+  test('renders reset button when onReset is provided', () => {
+    const props = {
+      ...defaultProps,
+      onReset: vi.fn(),
+    }
+
+    render(<ZoomControlsUI {...props} />)
+
+    const resetButton = screen.getByLabelText('Reset action')
+    expect(resetButton).toBeTruthy()
+
+    fireEvent.click(resetButton)
+    expect(props.onReset).toHaveBeenCalledTimes(1)
+  })
+
+  test('does not render reset button when onReset is not provided', () => {
+    render(<ZoomControlsUI {...defaultProps} />)
+
+    expect(screen.queryByLabelText('Reset action')).toBeNull()
+  })
+
+  test('hides zoom display when showZoom is false', () => {
+    render(<ZoomControlsUI {...defaultProps} showZoom={false} />)
+
+    expect(screen.queryByText('10')).toBeNull()
+  })
+
+  test('shows loading indicator when isLoading is true', () => {
+    render(<ZoomControlsUI {...defaultProps} isLoading={true} />)
+
+    expect(screen.getByRole('progressbar')).toBeTruthy()
+  })
+
+  test('renders in horizontal direction when specified', () => {
+    render(<ZoomControlsUI {...defaultProps} direction='horizontal' />)
+
+    // We can't check styles directly without jest-dom, so we'll skip this assertion
+    expect(screen.getByText('10')).toBeTruthy()
+  })
+
+  test('disables buttons when disabled prop is true', () => {
+    render(<ZoomControlsUI {...defaultProps} disabled={true} />)
+
+    const increaseButton = screen.getByLabelText('Increase zoom')
+    const decreaseButton = screen.getByLabelText('Decrease zoom')
+    expect(increaseButton.hasAttribute('disabled')).toBeTruthy()
+    expect(decreaseButton.hasAttribute('disabled')).toBeTruthy()
+  })
+})

package/src/components/zoom-controls/zoom-controls.tsx

@@ -0,0 +1,130 @@
+import {
+  IconButton,
+  Divider,
+  Box,
+  Typography,
+  CircularProgress,
+  Paper,
+} from '@mui/material'
+import {
+  AddOutlined,
+  RemoveOutlined,
+  CropFreeOutlined,
+} from '@mui/icons-material'
+import { styles } from './styles'
+import type { ZoomControlProps } from './types'
+import { useCallback, type JSX } from 'react'
+
+/**
+ * Provides intuitive zoom controls for maps and zoomable interfaces with flexible layouts, loading states, and optional reset functionality.
+ *
+ * @remarks
+ * This is an uncontrolled component. Typically used with the `ZoomControls` HOC from `@carto/ps-react-maps` for automatic state management.
+ *
+ * @example
+ * ```tsx
+ * <ZoomControlsUI
+ *   zoom={zoom}
+ *   onChange={setZoom}
+ *   minZoom={2}
+ *   maxZoom={20}
+ * />
+ * ```
+ */
+export function ZoomControlsUI({
+  zoom,
+  disabled,
+  direction = 'vertical',
+  reverse = false,
+  isLoading,
+  maxZoom = 24,
+  minZoom = 0,
+  PaperProps,
+  ResetViewProps = {
+    Icon: CropFreeOutlined,
+  },
+  showZoom = true,
+  onChange,
+  onReset,
+}: ZoomControlProps): JSX.Element {
+  const increaseZoom = useCallback(() => {
+    const newZoom = Math.min(maxZoom, zoom + 1)
+    onChange(newZoom)
+  }, [maxZoom, onChange, zoom])
+
+  const decreaseZoom = useCallback(() => {
+    const newZoom = Math.max(minZoom, zoom - 1)
+    onChange(newZoom)
+  }, [minZoom, onChange, zoom])
+
+  const displayZoom = Math.floor(zoom)
+
+  const dividerOrientation =
+    direction === 'vertical' ? 'horizontal' : 'vertical'
+
+  let flexDirection = direction === 'vertical' ? 'column' : 'row'
+
+  if (reverse) {
+    flexDirection += '-reverse'
+  }
+
+  return (
+    <Paper
+      sx={{
+        ...styles.paper,
+        flexDirection,
+      }}
+      {...PaperProps}
+    >
+      {onReset && (
+        <>
+          <IconButton
+            onClick={onReset}
+            aria-label='Reset action'
+            disabled={disabled}
+          >
+            <ResetViewProps.Icon />
+          </IconButton>
+          <Divider orientation={dividerOrientation} flexItem />
+        </>
+      )}
+      <IconButton
+        onClick={increaseZoom}
+        aria-label='Increase zoom'
+        disabled={disabled}
+      >
+        <AddOutlined />
+      </IconButton>
+      <Divider orientation={dividerOrientation} flexItem />
+      {showZoom && (
+        <>
+          <Box sx={styles.zoom}>
+            <Typography
+              display='block'
+              align='center'
+              color='textSecondary'
+              variant='overline'
+            >
+              {displayZoom}
+            </Typography>
+            {isLoading && (
+              <CircularProgress
+                sx={styles.circularProgress}
+                variant='indeterminate'
+                size={24}
+              />
+            )}
+          </Box>
+          <Divider orientation={dividerOrientation} flexItem />
+        </>
+      )}
+      <IconButton
+        onClick={decreaseZoom}
+        aria-label='Decrease zoom'
+        disabled={disabled}
+      >
+        <RemoveOutlined />
+      </IconButton>
+    </Paper>
+  )
+}

package/src/hooks/index.ts

@@ -0,0 +1 @@
+export { useWidgetRef } from './use-widget-ref'

package/src/hooks/use-skeleton.test.tsx

@@ -0,0 +1,32 @@
+import { describe, expect, test } from 'vitest'
+import { renderHook } from '@testing-library/react'
+import { useSkeleton } from './use-skeleton'
+
+describe('useSkeleton', () => {
+  test('should return true if loading', () => {
+    const { result } = renderHook(() => useSkeleton(true))
+
+    expect(result.current).toBe(true)
+  })
+
+  test('should return false if not loading', () => {
+    const { result } = renderHook(() => useSkeleton(false))
+
+    expect(result.current).toBe(false)
+  })
+
+  test('should return false if skeleton was already rendered', () => {
+    const { result, rerender } = renderHook(
+      ({ showSkeleton }) => useSkeleton(showSkeleton),
+      { initialProps: { showSkeleton: true } },
+    )
+
+    expect(result.current).toBe(true)
+
+    rerender({ showSkeleton: false })
+    expect(result.current).toBe(false)
+
+    rerender({ showSkeleton: true })
+    expect(result.current).toBe(false)
+  })
+})