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

package/{dist/types/widgets/_shared/skeleton/index.d.ts → src/widgets/utils/skeleton/index.ts}

@@ -1,4 +1,5 @@
 /**
  * Shared skeleton styles for chart widgets
  */
-export { baseSkeletonStyles } from './styles';
+
+export { baseSkeletonStyles } from './styles'

package/src/widgets/utils/skeleton/styles.ts

@@ -0,0 +1,20 @@
+import type { Theme } from '@mui/material'
+
+/**
+ * Base skeleton styles shared across all chart widgets
+ */
+export const baseSkeletonStyles = {
+  graph: {
+    /**
+     * Common container style for chart widget skeletons
+     */
+    container: {
+      display: 'flex',
+      alignItems: 'center',
+      justifyContent: 'space-between',
+      flexDirection: 'column',
+      gap: ({ spacing }: Theme) => spacing(1),
+      height: ({ spacing }: Theme) => spacing(38),
+    },
+  },
+} as const

package/src/widgets/wrapper/components/actions.test.tsx

@@ -0,0 +1,105 @@
+import { describe, test, expect, vi } from 'vitest'
+import { render, screen, fireEvent } from '@testing-library/react'
+import { Actions } from './actions'
+
+describe('Actions', () => {
+  test('renders with empty actions array', () => {
+    const { container } = render(<Actions actions={[]} />)
+    expect(container.firstChild).toBeTruthy()
+  })
+
+  test('renders with undefined actions', () => {
+    const { container } = render(<Actions />)
+    expect(container.firstChild).toBeTruthy()
+  })
+
+  test('renders single action', () => {
+    const actions = [<button key='action1'>Action 1</button>]
+    render(<Actions actions={actions} />)
+    expect(screen.getByText('Action 1')).toBeTruthy()
+  })
+
+  test('renders multiple actions', () => {
+    const actions = [
+      <button key='action1'>Action 1</button>,
+      <button key='action2'>Action 2</button>,
+      <button key='action3'>Action 3</button>,
+    ]
+    render(<Actions actions={actions} />)
+    expect(screen.getByText('Action 1')).toBeTruthy()
+    expect(screen.getByText('Action 2')).toBeTruthy()
+    expect(screen.getByText('Action 3')).toBeTruthy()
+  })
+
+  test('stops event propagation on click', () => {
+    const onClick = vi.fn()
+    const parentOnClick = vi.fn()
+
+    const actions = [
+      <button key='action1' onClick={onClick}>
+        Action 1
+      </button>,
+    ]
+
+    render(
+      <div
+        role='button'
+        tabIndex={0}
+        onClick={parentOnClick}
+        onKeyDown={parentOnClick}
+      >
+        <Actions actions={actions} />
+      </div>,
+    )
+
+    const button = screen.getByText('Action 1')
+    fireEvent.click(button)
+
+    // The action's onClick should fire
+    expect(onClick).toHaveBeenCalledTimes(1)
+    // But parent onClick should not fire due to stopPropagation
+    expect(parentOnClick).not.toHaveBeenCalled()
+  })
+
+  test('renders actions with different types of elements', () => {
+    const actions = [
+      <button key='button'>Button</button>,
+      <button key='link'>Link</button>,
+      <span key='span'>Span</span>,
+    ]
+    render(<Actions actions={actions} />)
+    expect(screen.getByText('Button')).toBeTruthy()
+    expect(screen.getByText('Link')).toBeTruthy()
+    expect(screen.getByText('Span')).toBeTruthy()
+  })
+
+  test('wraps each action in a Box with correct key', () => {
+    const actions = [
+      <button key='action1'>Action 1</button>,
+      <button key='action2'>Action 2</button>,
+    ]
+    const { container } = render(<Actions actions={actions} />)
+
+    // Check that actions are rendered
+    expect(screen.getByText('Action 1')).toBeTruthy()
+    expect(screen.getByText('Action 2')).toBeTruthy()
+
+    // The container should have the actions box
+    expect(container.firstChild).toBeTruthy()
+  })
+
+  test('handles complex action components', () => {
+    const ComplexAction = () => (
+      <div>
+        <span>Complex</span>
+        <button>Action</button>
+      </div>
+    )
+
+    const actions = [<ComplexAction key='complex' />]
+    render(<Actions actions={actions} />)
+
+    expect(screen.getByText('Complex')).toBeTruthy()
+    expect(screen.getByText('Action')).toBeTruthy()
+  })
+})

package/src/widgets/wrapper/components/actions.tsx

@@ -0,0 +1,35 @@
+import { Box } from '@mui/material'
+import type { WrapperActionsProps } from '../types'
+import { styles } from '../styles'
+
+const EMPTY_ACTIONS: NonNullable<WrapperActionsProps['actions']> = []
+
+/**
+ * Renders action buttons in the widget wrapper header. Each action click event is stopped from propagating to the accordion.
+ */
+export function Actions({ actions = EMPTY_ACTIONS }: WrapperActionsProps) {
+  return (
+    <Box sx={styles.actions} className='widget-wrapper-actions'>
+      {actions.map((action, index) => {
+        // Prefer action.key if present (React elements), else fallback to index
+        const key =
+          action &&
+          typeof action === 'object' &&
+          'key' in action &&
+          action.key != null
+            ? action.key
+            : index
+        return (
+          <Box
+            key={key}
+            onClick={(e) => {
+              e.stopPropagation()
+            }}
+          >
+            {action}
+          </Box>
+        )
+      })}
+    </Box>
+  )
+}

package/src/widgets/wrapper/components/options.test.tsx

@@ -0,0 +1,331 @@
+import { describe, test, expect, vi } from 'vitest'
+import { render, screen, fireEvent } from '@testing-library/react'
+import { Options } from './options'
+
+describe('Options', () => {
+  test('renders options button with default label', () => {
+    const options = [
+      {
+        label: 'Option 1',
+        onClick: vi.fn(),
+      },
+    ]
+    render(<Options options={options} />)
+    expect(screen.getByLabelText('Options')).toBeTruthy()
+  })
+
+  test('renders options button with custom label', () => {
+    const options = [
+      {
+        label: 'Option 1',
+        onClick: vi.fn(),
+      },
+    ]
+    const labels = {
+      title: 'Custom Options Label',
+    }
+    render(<Options options={options} labels={labels} />)
+    expect(screen.getByLabelText('Custom Options Label')).toBeTruthy()
+  })
+
+  test('renders when options array is empty', () => {
+    render(<Options options={[]} />)
+    // Component still renders button even with empty options
+    // (In practice, WrapperUI doesn't render Options when options.length === 0)
+    expect(screen.getByLabelText('Options')).toBeTruthy()
+  })
+
+  test('renders when options is undefined', () => {
+    render(<Options />)
+    // Component still renders button even with undefined options
+    // (In practice, WrapperUI doesn't render Options when options.length === 0)
+    expect(screen.getByLabelText('Options')).toBeTruthy()
+  })
+
+  test('opens menu when button is clicked', () => {
+    const options = [
+      {
+        label: 'Option 1',
+        onClick: vi.fn(),
+      },
+    ]
+    render(<Options options={options} />)
+
+    const button = screen.getByLabelText('Options')
+    fireEvent.click(button)
+
+    expect(screen.getByText('Option 1')).toBeTruthy()
+  })
+
+  test('closes menu when option is clicked', () => {
+    const onClick = vi.fn()
+    const options = [
+      {
+        label: 'Option 1',
+        onClick,
+      },
+    ]
+    render(<Options options={options} />)
+
+    const button = screen.getByLabelText('Options')
+    fireEvent.click(button)
+
+    const menuItem = screen.getByText('Option 1')
+    fireEvent.click(menuItem)
+
+    expect(onClick).toHaveBeenCalledTimes(1)
+    // Menu should be closed after clicking
+    expect(screen.queryByRole('menu')).toBeNull()
+  })
+
+  test('stops event propagation when opening menu', () => {
+    const parentOnClick = vi.fn()
+    const options = [
+      {
+        label: 'Option 1',
+        onClick: vi.fn(),
+      },
+    ]
+
+    render(
+      <div
+        role='button'
+        tabIndex={0}
+        onClick={parentOnClick}
+        onKeyDown={parentOnClick}
+      >
+        <Options options={options} />
+      </div>,
+    )
+
+    const button = screen.getByLabelText('Options')
+    fireEvent.click(button)
+
+    // Parent onClick should not be called
+    expect(parentOnClick).not.toHaveBeenCalled()
+  })
+
+  test('stops event propagation when clicking option', () => {
+    const parentOnClick = vi.fn()
+    const onClick = vi.fn()
+    const options = [
+      {
+        label: 'Option 1',
+        onClick,
+      },
+    ]
+
+    render(
+      <div
+        role='button'
+        tabIndex={0}
+        onClick={parentOnClick}
+        onKeyDown={parentOnClick}
+      >
+        <Options options={options} />
+      </div>,
+    )
+
+    const button = screen.getByLabelText('Options')
+    fireEvent.click(button)
+
+    const menuItem = screen.getByText('Option 1')
+    fireEvent.click(menuItem)
+
+    expect(onClick).toHaveBeenCalledTimes(1)
+    expect(parentOnClick).not.toHaveBeenCalled()
+  })
+
+  test('renders multiple options', () => {
+    const options = [
+      {
+        label: 'Option 1',
+        onClick: vi.fn(),
+      },
+      {
+        label: 'Option 2',
+        onClick: vi.fn(),
+      },
+      {
+        label: 'Option 3',
+        onClick: vi.fn(),
+      },
+    ]
+    render(<Options options={options} />)
+
+    const button = screen.getByLabelText('Options')
+    fireEvent.click(button)
+
+    expect(screen.getByText('Option 1')).toBeTruthy()
+    expect(screen.getByText('Option 2')).toBeTruthy()
+    expect(screen.getByText('Option 3')).toBeTruthy()
+  })
+
+  test('renders disabled option', () => {
+    const options = [
+      {
+        label: 'Disabled Option',
+        disabled: true,
+        onClick: vi.fn(),
+      },
+    ]
+    render(<Options options={options} />)
+
+    const button = screen.getByLabelText('Options')
+    fireEvent.click(button)
+
+    const menuItem = screen.getByText('Disabled Option').closest('li')
+    expect(menuItem?.classList.contains('Mui-disabled')).toBe(true)
+  })
+
+  test('does not call onClick for disabled option', () => {
+    const onClick = vi.fn()
+    const options = [
+      {
+        label: 'Enabled Option',
+        onClick,
+      },
+      {
+        label: 'Disabled Option',
+        disabled: true,
+        onClick,
+      },
+    ]
+    render(<Options options={options} />)
+
+    const button = screen.getByLabelText('Options')
+    fireEvent.click(button)
+
+    // Click on enabled option first
+    const enabled = screen.getByText('Enabled Option')
+    fireEvent.click(enabled)
+
+    // onClick should be called once for enabled
+    expect(onClick).toHaveBeenCalledTimes(1)
+
+    // Open menu again and try clicking disabled
+    fireEvent.click(button)
+    const disabled = screen.getByText('Disabled Option').closest('li')
+
+    // Disabled should have the class
+    expect(disabled?.classList.contains('Mui-disabled')).toBe(true)
+  })
+
+  test('renders option with icon', () => {
+    const icon = <span data-testid='test-icon'>Icon</span>
+    const options = [
+      {
+        label: 'Option with Icon',
+        icon,
+        onClick: vi.fn(),
+      },
+    ]
+    render(<Options options={options} />)
+
+    const button = screen.getByLabelText('Options')
+    fireEvent.click(button)
+
+    expect(screen.getByTestId('test-icon')).toBeTruthy()
+    expect(screen.getByText('Option with Icon')).toBeTruthy()
+  })
+
+  test('renders option without icon', () => {
+    const options = [
+      {
+        label: 'Option without Icon',
+        onClick: vi.fn(),
+      },
+    ]
+    render(<Options options={options} />)
+
+    const button = screen.getByLabelText('Options')
+    fireEvent.click(button)
+
+    expect(screen.getByText('Option without Icon')).toBeTruthy()
+  })
+
+  test('closes menu when clicking outside', () => {
+    const options = [
+      {
+        label: 'Option 1',
+        onClick: vi.fn(),
+      },
+    ]
+    render(<Options options={options} />)
+
+    const button = screen.getByLabelText('Options')
+    fireEvent.click(button)
+
+    // Menu should be open
+    expect(screen.getByText('Option 1')).toBeTruthy()
+
+    // Click outside (on the backdrop)
+    const backdrop = document.querySelector('.MuiBackdrop-root')
+    if (backdrop) {
+      fireEvent.click(backdrop)
+    }
+
+    // Menu should be closed
+    expect(screen.queryByRole('menu')).toBeNull()
+  })
+
+  test('handles multiple option clicks correctly', () => {
+    const onClick1 = vi.fn()
+    const onClick2 = vi.fn()
+    const options = [
+      {
+        label: 'Option 1',
+        onClick: onClick1,
+      },
+      {
+        label: 'Option 2',
+        onClick: onClick2,
+      },
+    ]
+    render(<Options options={options} />)
+
+    // Open menu and click first option
+    const button = screen.getByLabelText('Options')
+    fireEvent.click(button)
+    fireEvent.click(screen.getByText('Option 1'))
+
+    expect(onClick1).toHaveBeenCalledTimes(1)
+    expect(onClick2).not.toHaveBeenCalled()
+
+    // Open menu again and click second option
+    fireEvent.click(button)
+    fireEvent.click(screen.getByText('Option 2'))
+
+    expect(onClick1).toHaveBeenCalledTimes(1)
+    expect(onClick2).toHaveBeenCalledTimes(1)
+  })
+
+  test('renders MoreVert icon', () => {
+    const options = [
+      {
+        label: 'Option 1',
+        onClick: vi.fn(),
+      },
+    ]
+    render(<Options options={options} />)
+
+    // Check that the button is rendered
+    const button = screen.getByLabelText('Options')
+    expect(button).toBeTruthy()
+  })
+
+  test('menu has correct attributes', () => {
+    const options = [
+      {
+        label: 'Option 1',
+        onClick: vi.fn(),
+      },
+    ]
+    render(<Options options={options} />)
+
+    const button = screen.getByLabelText('Options')
+    expect(button.getAttribute('aria-label')).toBe('Options')
+    expect(button.getAttribute('aria-controls')).toBe('options-menu')
+    expect(button.getAttribute('aria-haspopup')).toBe('true')
+  })
+})

package/src/widgets/wrapper/components/options.tsx

@@ -0,0 +1,81 @@
+import { MoreVert } from '@mui/icons-material'
+import {
+  IconButton,
+  Menu,
+  MenuItem,
+  ListItemIcon,
+  ListItemText,
+} from '@mui/material'
+import type { WrapperOptionsProps } from '../types'
+import { useState } from 'react'
+import { styles } from '../styles'
+
+const EMPTY_OPTIONS: NonNullable<WrapperOptionsProps['options']> = []
+
+/**
+ * Renders a dropdown options menu in the widget wrapper header, triggered by a vertical ellipsis icon button.
+ */
+export function Options({
+  labels,
+  options = EMPTY_OPTIONS,
+}: WrapperOptionsProps) {
+  const [anchorEl, setAnchorEl] = useState<null | HTMLElement>(null)
+
+  const handleOptionAction = (
+    e: React.MouseEvent<HTMLElement>,
+    option: NonNullable<WrapperOptionsProps['options']>[number],
+  ) => {
+    e.stopPropagation()
+    option.onClick()
+    setAnchorEl(null)
+  }
+
+  return (
+    <>
+      <IconButton
+        sx={styles.options.trigger}
+        size='small'
+        aria-label={labels?.title ?? 'Options'}
+        aria-controls='options-menu'
+        aria-haspopup='true'
+        onClick={(e) => {
+          e.stopPropagation()
+          setAnchorEl(e.currentTarget)
+        }}
+      >
+        <MoreVert />
+      </IconButton>
+      <Menu
+        variant='menu'
+        elevation={8}
+        anchorOrigin={{
+          vertical: 'top',
+          horizontal: 'right',
+        }}
+        transformOrigin={{
+          vertical: 'top',
+          horizontal: 'right',
+        }}
+        anchorEl={anchorEl}
+        open={Boolean(anchorEl)}
+        onClose={() => setAnchorEl(null)}
+        MenuListProps={{
+          sx: {
+            paddingBottom: 0,
+          },
+        }}
+      >
+        {options.map((option) => (
+          <MenuItem
+            key={option.label}
+            disabled={option.disabled}
+            onClick={(e) => handleOptionAction(e, option)}
+          >
+            {option.icon && <ListItemIcon>{option.icon}</ListItemIcon>}
+            <ListItemText>{option.label}</ListItemText>
+          </MenuItem>
+        ))}
+      </Menu>
+    </>
+  )
+}

package/src/widgets/wrapper/components/title.test.tsx

@@ -0,0 +1,126 @@
+import { describe, test, expect } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import { Title } from './title'
+
+describe('Title', () => {
+  test('renders with string children', () => {
+    render(<Title>Test Title</Title>)
+    expect(screen.getByText('Test Title')).toBeTruthy()
+  })
+
+  test('renders with ReactNode children', () => {
+    render(
+      <Title>
+        <span>Complex</span> <strong>Title</strong>
+      </Title>,
+    )
+    expect(screen.getByText('Complex')).toBeTruthy()
+    expect(screen.getByText('Title')).toBeTruthy()
+  })
+
+  test('renders with custom label', () => {
+    render(<Title label='Custom Label'>Display Text</Title>)
+    // The component should render the children
+    expect(screen.getByText('Display Text')).toBeTruthy()
+  })
+
+  test('uses children as tooltip when children is string and no label', () => {
+    render(<Title>String Title</Title>)
+    expect(screen.getByText('String Title')).toBeTruthy()
+  })
+
+  test('uses empty string tooltip when children is not string and no label', () => {
+    render(
+      <Title>
+        <div>Complex Title</div>
+      </Title>,
+    )
+    expect(screen.getByText('Complex Title')).toBeTruthy()
+  })
+
+  test('applies correct typography variant', () => {
+    render(<Title>Test Title</Title>)
+    const typography = screen.getByText('Test Title')
+    expect(typography.tagName).toBe('H6') // subtitle1 renders as h6
+  })
+
+  test('wraps content in SmartTooltip', () => {
+    render(<Title>Tooltip Title</Title>)
+    expect(screen.getByText('Tooltip Title')).toBeTruthy()
+  })
+
+  test('handles empty string children', () => {
+    render(<Title>{''}</Title>)
+    // Should render but be empty
+    const { container } = render(<Title>{''}</Title>)
+    expect(container).toBeTruthy()
+  })
+
+  test('handles numeric children', () => {
+    render(<Title>{123}</Title>)
+    expect(screen.getByText('123')).toBeTruthy()
+  })
+
+  test('renders with multiple children', () => {
+    render(
+      <Title>
+        <span>Part 1</span>
+        <span>Part 2</span>
+        <span>Part 3</span>
+      </Title>,
+    )
+    expect(screen.getByText('Part 1')).toBeTruthy()
+    expect(screen.getByText('Part 2')).toBeTruthy()
+    expect(screen.getByText('Part 3')).toBeTruthy()
+  })
+
+  test('prefers label over string children for tooltip', () => {
+    render(<Title label='Tooltip Text'>Display Text</Title>)
+    expect(screen.getByText('Display Text')).toBeTruthy()
+  })
+
+  test('renders with undefined label and string children', () => {
+    render(<Title label={undefined}>String Children</Title>)
+    expect(screen.getByText('String Children')).toBeTruthy()
+  })
+
+  test('handles complex nested structure', () => {
+    render(
+      <Title>
+        <div>
+          <span>Nested</span>
+          <div>Content</div>
+        </div>
+      </Title>,
+    )
+    expect(screen.getByText('Nested')).toBeTruthy()
+    expect(screen.getByText('Content')).toBeTruthy()
+  })
+
+  test('ref is passed to Typography component', () => {
+    const { container } = render(<Title>Title with Ref</Title>)
+    expect(screen.getByText('Title with Ref')).toBeTruthy()
+    // The Typography component should be in the DOM
+    const typography = container.querySelector('[class*="MuiTypography"]')
+    expect(typography).toBeTruthy()
+  })
+
+  test('renders with textTransform none', () => {
+    render(<Title>Title Text</Title>)
+    expect(screen.getByText('Title Text')).toBeTruthy()
+  })
+
+  test('handles boolean children', () => {
+    render(<Title>{true}</Title>)
+    // Boolean children don't render text
+    const { container } = render(<Title>{false}</Title>)
+    expect(container).toBeTruthy()
+  })
+
+  test('handles null children', () => {
+    render(<Title>{null}</Title>)
+    // Null children don't render
+    const { container } = render(<Title>{null}</Title>)
+    expect(container).toBeTruthy()
+  })
+})