@carto/ps-react-ui 4.3.3 → 4.3.5

package/src/widgets/toolbar-actions/toolbar-actions.tsx

@@ -0,0 +1,145 @@
+import { CloseOutlined } from '@mui/icons-material'
+import { Box, Divider, Grow, IconButton, Paper } from '@mui/material'
+import { isValidElement, useState, type JSX, type MouseEvent } from 'react'
+import { Tooltip } from '../../components/tooltip/tooltip'
+import { styles } from './styles'
+import type { ToolbarActionsProps } from './types'
+import { WidgetOptions } from '@carto/meridian-ds/custom-icons'
+
+const DEFAULT_LABELS = {
+  trigger: 'More actions',
+  close: 'Close',
+}
+
+/**
+ * A floating toolbar component that displays action buttons.
+ * Shows a trigger button when there are more visible actions than the visibleCount,
+ * which expands to reveal all actions with a close button.
+ * When visibleCount is undefined, all actions are shown without overflow.
+ *
+ * Children with the `data-toolbar-hidden` attribute are ignored when counting
+ * visible actions but are included in the preview. This is useful for elements
+ * like Dividers that should appear between actions but not count toward the limit.
+ *
+ * Example: With visibleCount=2 and children [Action1, Divider, Action2, Divider, Action3]:
+ * - Preview shows: Action1, Divider, Action2 (2 visible actions + divider)
+ * - Hidden: Divider, Action3
+ */
+export function ToolbarActions({
+  children: _children,
+  visibleCount,
+  direction,
+  labels,
+  sx,
+  IconButtonProps,
+  TooltipProps,
+}: ToolbarActionsProps): JSX.Element | null {
+  const [anchorEl, setAnchorEl] = useState<null | HTMLElement>(null)
+
+  const triggerLabel = labels?.trigger ?? DEFAULT_LABELS.trigger
+  const closeLabel = labels?.close ?? DEFAULT_LABELS.close
+
+  const children = (Array.isArray(_children) ? _children : [_children]).filter(
+    Boolean,
+  )
+
+  // Don't render if no actions
+  if (children.length === 0) {
+    return null
+  }
+
+  // Filter out children with data-toolbar-hidden attribute for counting
+  const visibleChildren = children.filter(
+    (child) =>
+      !(
+        isValidElement<{ 'data-toolbar-hidden'?: boolean }>(child) &&
+        child.props['data-toolbar-hidden']
+      ),
+  )
+
+  // Show trigger only when visibleCount is defined and there are more visible actions
+  const showTrigger =
+    visibleCount !== undefined && visibleChildren.length > visibleCount
+
+  const handleToggle = (e: MouseEvent<HTMLElement>) => {
+    setAnchorEl((prev) => (prev ? null : e.currentTarget))
+  }
+
+  // Build preview by including hidden elements but only counting visible ones
+  const childrenPreview =
+    visibleCount === undefined
+      ? children
+      : children.reduce<{ result: React.ReactNode[]; count: number }>(
+          (acc, child) => {
+            // Stop if we've already collected enough visible actions
+            if (acc.count >= visibleCount) {
+              return acc
+            }
+
+            const isHidden =
+              isValidElement<{ 'data-toolbar-hidden'?: boolean }>(child) &&
+              child.props['data-toolbar-hidden']
+
+            return {
+              result: [...acc.result, child],
+              count: acc.count + (isHidden ? 0 : 1),
+            }
+          },
+          { result: [], count: 0 },
+        ).result
+
+  const width = anchorEl?.getBoundingClientRect().width
+
+  return (
+    <Box
+      sx={{
+        ...styles.root,
+        ...sx,
+        flexDirection: direction === 'left' ? 'row-reverse' : 'row',
+      }}
+    >
+      {/* Trigger button - only shown when 3+ actions */}
+      {showTrigger && (
+        <>
+          <Tooltip
+            title={anchorEl ? closeLabel : triggerLabel}
+            placement='top'
+            {...TooltipProps}
+          >
+            <IconButton
+              size='small'
+              aria-label={anchorEl ? closeLabel : triggerLabel}
+              onClick={handleToggle}
+              sx={styles.triggerButton}
+              data-active={!!anchorEl}
+              {...IconButtonProps}
+            >
+              {anchorEl ? <CloseOutlined /> : <WidgetOptions />}
+            </IconButton>
+          </Tooltip>
+          <Divider orientation='vertical' flexItem />
+        </>
+      )}
+
+      <Box sx={styles.preview}>{childrenPreview}</Box>
+
+      {/* Actions container - shown only when expanded (trigger is active) */}
+      <Grow in={!!anchorEl}>
+        <Paper
+          sx={{
+            ...styles.actionsContainer,
+            transform: `translate3d(${
+              direction === 'left' ? `-${width ?? 0}px` : `${width ?? 0}px`
+            }, 0, 0) !important`,
+            marginLeft: ({ spacing }) =>
+              direction === 'left' ? 0 : spacing(0.25),
+            marginRight: ({ spacing }) =>
+              direction === 'left' ? spacing(0.25) : 0,
+          }}
+        >
+          {children}
+        </Paper>
+      </Grow>
+    </Box>
+  )
+}

package/src/widgets/toolbar-actions/types.ts

@@ -0,0 +1,60 @@
+import type {
+  IconButtonProps,
+  SxProps,
+  Theme,
+  TooltipProps,
+} from '@mui/material'
+import type { ReactNode } from 'react'
+
+/**
+ * Represents a single action in the toolbar
+ */
+export interface ToolbarAction {
+  /** Unique identifier for the action */
+  id: string
+  /** Icon to display for the action */
+  icon: ReactNode
+  /** Label displayed in tooltip */
+  label: string
+  /** Callback when action is clicked */
+  onClick: () => void
+  /** Whether the action is disabled */
+  disabled?: boolean
+}
+
+/**
+ * Labels for toolbar UI elements
+ */
+export interface ToolbarActionsLabels {
+  /** Tooltip for the trigger button */
+  trigger?: string
+  /** Tooltip for the close button */
+  close?: string
+}
+
+/**
+ * Props for the ToolbarActions component
+ */
+export interface ToolbarActionsProps {
+  /**
+   * Array of React elements (typically IconButtons) to display in the toolbar.
+   * Elements with `data-toolbar-hidden` attribute are ignored when counting visible
+   * actions and excluded from the collapsed preview (e.g., Dividers).
+   */
+  children: ReactNode[] | ReactNode
+  /** Direction in which the toolbar expands */
+  direction?: 'left' | 'right'
+  /**
+   * Number of visible actions to show in collapsed mode.
+   * When undefined, shows all actions without overflow.
+   */
+  visibleCount?: number
+  /** Custom labels for UI elements */
+  labels?: ToolbarActionsLabels
+  /** Custom styles for the root container */
+  sx?: SxProps<Theme>
+  /** Props passed to action IconButtons */
+  IconButtonProps?: Omit<IconButtonProps, 'onClick' | 'disabled'>
+  /** Props passed to Tooltips */
+  TooltipProps?: Omit<TooltipProps, 'title' | 'children'>
+}

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

@@ -0,0 +1,101 @@
+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(
+      // eslint-disable-next-line jsx-a11y/click-events-have-key-events, jsx-a11y/no-static-element-interactions
+      <div onClick={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,30 @@
+import { Box } from '@mui/material'
+import type { WrapperActionsProps } from '../types'
+import { styles } from '../styles'
+
+export function Actions({ 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,323 @@
+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(
+      // eslint-disable-next-line jsx-a11y/click-events-have-key-events, jsx-a11y/no-static-element-interactions
+      <div onClick={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(
+      // eslint-disable-next-line jsx-a11y/click-events-have-key-events, jsx-a11y/no-static-element-interactions
+      <div onClick={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')
+  })
+})