@carto/ps-react-ui 4.3.2 → 4.3.4

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

@@ -0,0 +1,77 @@
+import type { Paper, TooltipProps } from '@mui/material'
+import type { ComponentProps } from 'react'
+import type {
+  MeasurementMode,
+  MeasurementModes,
+  MeasurementOptionsMode,
+  MeasurementOptionsUnit,
+  MeasurementUnit,
+  MeasurementUnitImperialDistance,
+  MeasurementUnitMetricDistance,
+  MeasurementUnits,
+  MeasurementModesMapping,
+  MeasurementUnitsMapping,
+} from '../types'
+
+interface Labels {
+  action?: {
+    tooltip?: {
+      active?: string
+      inactive?: string
+    }
+  }
+  chip?: {
+    tooltip?: {
+      active?: string
+      inactive?: string
+    }
+  }
+  options?: {
+    mode?: {
+      title?: string
+      options?: MeasurementOptionsMode
+    }
+    units?: {
+      title?: string
+      modal?: {
+        title?: string
+        subtitle?: string
+        apply?: string
+        options?: {
+          metric: {
+            title: string
+            options: MeasurementOptionsUnit<MeasurementUnitMetricDistance>
+          }
+          imperial: {
+            title: string
+            options: MeasurementOptionsUnit<MeasurementUnitImperialDistance>
+          }
+        }
+      }
+    }
+  }
+}
+
+interface ActionProps {
+  TooltipProps?: Omit<TooltipProps, 'title'>
+}
+
+export interface MeasurementToolsComponentProps<
+  T extends string = MeasurementMode,
+  U extends string = MeasurementUnit,
+> {
+  enabled: boolean
+  value: string
+  labels?: Labels
+  modesMapping?: MeasurementModesMapping<T>
+  unitsMapping?: MeasurementUnitsMapping<U>
+  actionProps?: ActionProps
+  modeSelected?: T
+  modes: Partial<MeasurementModes<T>>
+  units: MeasurementUnits<T, U>
+  unitSelected?: string
+  PaperProps?: ComponentProps<typeof Paper>
+  onActionToggle: (data: boolean) => void
+  onChangeMode: (mode?: T) => void
+  onChangeUnit: (unit: string) => void
+}

package/src/components/no-data-alert/no-data-alert.test.tsx

@@ -0,0 +1,31 @@
+import { describe, expect, test } from 'vitest'
+import { render, within } from '@testing-library/react'
+import { NoDataAlert } from './no-data-alert'
+
+describe('NoDataAlert', () => {
+  test('with default props', () => {
+    const { container } = render(<NoDataAlert />)
+
+    const title = within(container).queryByText('No data available')
+    const body = within(container).queryByText(
+      'There are no results for the combination of filters applied to your data. Try tweaking your filters, or zoom and pan the map to adjust the Map View.',
+    )
+
+    expect(title).toBeTruthy()
+    expect(body).toBeTruthy()
+  })
+
+  test('with custom title', () => {
+    const { container } = render(<NoDataAlert title='Custom title' />)
+
+    const title = within(container).queryByText('Custom title')
+    expect(title).toBeTruthy()
+  })
+
+  test('with custom body', () => {
+    const { container } = render(<NoDataAlert body='Custom body' />)
+
+    const body = within(container).queryByText('Custom body')
+    expect(body).toBeTruthy()
+  })
+})

package/src/components/no-data-alert/no-data-alert.tsx

@@ -0,0 +1,59 @@
+import {
+  Alert,
+  Box,
+  Typography,
+  type AlertProps,
+  type TypographyProps,
+} from '@mui/material'
+
+interface NoDataAlertProps {
+  title?: string
+  body?: string
+  severity?: AlertProps['severity']
+}
+
+export function NoDataAlert({
+  title = 'No data available',
+  body = 'There are no results for the combination of filters applied to your data. Try tweaking your filters, or zoom and pan the map to adjust the Map View.',
+  severity,
+}: NoDataAlertProps) {
+  if (severity) {
+    return (
+      <Alert title={title} severity={severity}>
+        <AlertBody>{body}</AlertBody>
+      </Alert>
+    )
+  }
+
+  return (
+    <Box>
+      {title && <Typography variant='body2'>{title}</Typography>}
+      <AlertBody color='textSecondary'>{body}</AlertBody>
+    </Box>
+  )
+}
+
+// Aux
+interface AlertBodyProps {
+  color?: TypographyProps['color']
+  children: React.ReactNode
+}
+
+function AlertBody({ color, children }: AlertBodyProps) {
+  if (children) {
+    return (
+      <Box mt={0.5}>
+        <Typography
+          component='div'
+          variant='caption'
+          color={color ?? 'inherit'}
+          style={{ fontWeight: 'normal' }}
+        >
+          {children}
+        </Typography>
+      </Box>
+    )
+  }
+
+  return <Box mt={-1} />
+}

package/src/components/responsive-drawer/responsive-drawer.test.tsx

@@ -0,0 +1,91 @@
+import { render, screen, fireEvent } from '@testing-library/react'
+import { describe, test, expect, vi, beforeEach } from 'vitest'
+import { ResponsiveDrawer } from './responsive-drawer'
+import { ThemeProvider } from '@mui/material'
+import { createTheme } from '@mui/material/styles'
+
+// Create a basic theme for testing
+const theme = createTheme()
+
+describe('ResponsiveDrawer', () => {
+  const mockOnChangeCollapsed = vi.fn()
+
+  const defaultProps = {
+    collapsed: false,
+    onChangeCollapsed: mockOnChangeCollapsed,
+    position: 'top-left' as const,
+    isMobile: false,
+    children: <div data-testid='drawer-content'>Test Content</div>,
+  }
+
+  beforeEach(() => {
+    mockOnChangeCollapsed.mockReset()
+  })
+
+  test('renders in desktop mode when isMobile is false', () => {
+    const { container } = render(
+      <ThemeProvider theme={theme}>
+        <ResponsiveDrawer ref={null} {...defaultProps} />
+      </ThemeProvider>,
+    )
+
+    // Check if content is rendered
+    const content = screen.getByTestId('drawer-content')
+    expect(content).toBeDefined()
+
+    // Make sure we're not using the mobile Drawer (no presentation role)
+    const presentationElements = container.querySelectorAll(
+      '[role="presentation"]',
+    )
+    expect(presentationElements.length).toBe(0)
+  })
+
+  test('renders in mobile mode when isMobile is true', () => {
+    render(
+      <ThemeProvider theme={theme}>
+        <ResponsiveDrawer ref={null} {...defaultProps} isMobile={true} />
+      </ThemeProvider>,
+    )
+
+    // Check if content is rendered
+    const content = screen.getByTestId('drawer-content')
+    expect(content).toBeDefined()
+
+    // Mobile mode uses MUI Drawer which has a 'presentation' role
+    const presentationElements = document.querySelectorAll(
+      '[role="presentation"]',
+    )
+    expect(presentationElements.length).toBeGreaterThan(0)
+  })
+
+  test('hides content when collapsed is true in desktop mode', () => {
+    render(
+      <ThemeProvider theme={theme}>
+        <ResponsiveDrawer ref={null} {...defaultProps} collapsed={true} />
+      </ThemeProvider>,
+    )
+
+    // When collapsed, the Popover should be closed and content should not be in the document
+    const content = screen.queryByTestId('drawer-content')
+    expect(content).toBeNull()
+  })
+
+  test('closes drawer when clicking outside in mobile mode', () => {
+    const { container } = render(
+      <ThemeProvider theme={theme}>
+        <ResponsiveDrawer ref={null} {...defaultProps} isMobile={true} />
+      </ThemeProvider>,
+    )
+
+    // Find and click the backdrop to close the drawer
+    const backdrop = container.querySelector('[role="presentation"] > div')
+    expect(backdrop).toBeDefined()
+    if (backdrop) {
+      fireEvent.click(backdrop)
+
+      // onChangeCollapsed should be called to close the drawer
+      expect(mockOnChangeCollapsed).toHaveBeenCalledTimes(1)
+      expect(mockOnChangeCollapsed).toHaveBeenCalledWith(true)
+    }
+  })
+})

package/src/components/responsive-drawer/responsive-drawer.tsx

@@ -0,0 +1,53 @@
+import { Drawer, Popover, type PopoverProps } from '@mui/material'
+import type { ReactNode } from 'react'
+
+export function ResponsiveDrawer<
+  T extends {
+    collapsed: boolean
+    onChangeCollapsed: (collapsed: boolean) => void
+    position: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
+    slotProps?: PopoverProps['slotProps']
+  },
+>({
+  ref,
+  children,
+  collapsed,
+  isMobile = false,
+  position,
+  sx,
+  slotProps,
+  onChangeCollapsed,
+}: Required<Pick<T, 'collapsed' | 'onChangeCollapsed' | 'position'>> &
+  Pick<PopoverProps, 'slotProps' | 'sx'> & {
+    ref: HTMLElement | null
+    isMobile: boolean
+    children: ReactNode
+  }) {
+  if (isMobile) {
+    return (
+      <Drawer anchor='bottom' open={!collapsed} onClose={onChangeCollapsed}>
+        {children}
+      </Drawer>
+    )
+  }
+
+  return (
+    <Popover
+      sx={sx}
+      anchorEl={ref}
+      open={!collapsed}
+      onClose={() => onChangeCollapsed(true)}
+      anchorOrigin={{
+        vertical: position.startsWith('bottom') ? 'bottom' : 'top',
+        horizontal: position.endsWith('right') ? 'left' : 'right',
+      }}
+      transformOrigin={{
+        vertical: position.startsWith('bottom') ? 'bottom' : 'top',
+        horizontal: position.endsWith('right') ? 'right' : 'left',
+      }}
+      slotProps={slotProps}
+    >
+      {children}
+    </Popover>
+  )
+}

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,40 @@
+import type { TooltipProps } from '@mui/material'
+import { useLayoutEffect, useRef, useState, type JSX, type Ref } from 'react'
+import { Tooltip } from '../tooltip/tooltip'
+
+export function SmartTooltip<T extends HTMLElement>({
+  title,
+  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)
+
+  useLayoutEffect(() => {
+    const timerId = setTimeout(() => {
+      if (ref.current) {
+        const isOverflowing =
+          ref.current.scrollWidth > ref.current.clientWidth ||
+          ref.current.scrollHeight > ref.current.clientHeight
+
+        setIsOverflowing(isOverflowing)
+      }
+    }, timeout)
+
+    return () => clearTimeout(timerId)
+  }, [dependencies, 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,30 @@
+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>
+  )
+}
+
+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
+}