@carto/ps-react-ui 4.3.3 → 4.3.5

package/src/widgets/actions/download/download.test.tsx

@@ -0,0 +1,322 @@
+import { describe, test, expect, beforeEach, vi } from 'vitest'
+import { render, screen, fireEvent, waitFor } from '@testing-library/react'
+import { Download } from './download'
+import { useWidgetStore } from '../../../widgets'
+import type { DownloadItem } from './types'
+
+describe('Download', () => {
+  const widgetId = 'test-download-widget'
+
+  beforeEach(() => {
+    // Clear store before each test
+    useWidgetStore.getState().clearWidgets()
+  })
+
+  test('disables button when download items array is empty', () => {
+    render(<Download id={widgetId} items={[]} />)
+    const button = screen.getByRole('button', { name: 'download options' })
+    expect(button.hasAttribute('disabled')).toBeTruthy()
+  })
+
+  test('renders download button when download options exist', () => {
+    const mockDownload: DownloadItem[] = [
+      {
+        id: 'csv',
+        label: 'CSV',
+        modifier: vi.fn().mockResolvedValue('data:text/csv;base64,'),
+      },
+    ]
+
+    useWidgetStore.getState().setWidget(widgetId, {
+      data: [['a', 'b']],
+    })
+
+    render(<Download id={widgetId} items={mockDownload} />)
+
+    const button = screen.getByRole('button', { name: 'download options' })
+    expect(button).toBeTruthy()
+  })
+
+  test('uses custom aria label when provided', () => {
+    const mockDownload: DownloadItem[] = [
+      {
+        id: 'csv',
+        label: 'CSV',
+        modifier: vi.fn().mockResolvedValue('data:text/csv;base64,'),
+      },
+    ]
+
+    render(
+      <Download
+        id={widgetId}
+        items={mockDownload}
+        labels={{ ariaLabel: 'custom download' }}
+      />,
+    )
+
+    const button = screen.getByRole('button', { name: 'custom download' })
+    expect(button).toBeTruthy()
+  })
+
+  test('opens menu when button is clicked', async () => {
+    const mockDownload: DownloadItem[] = [
+      {
+        id: 'csv',
+        label: 'CSV',
+        modifier: vi.fn().mockResolvedValue('data:text/csv;base64,'),
+      },
+      {
+        id: 'png',
+        label: 'PNG',
+        modifier: vi.fn().mockResolvedValue('data:image/png;base64,'),
+      },
+    ]
+
+    render(<Download id={widgetId} items={mockDownload} />)
+
+    const button = screen.getByRole('button', { name: 'download options' })
+    fireEvent.click(button)
+
+    await waitFor(() => {
+      expect(screen.getByText('CSV')).toBeTruthy()
+      expect(screen.getByText('PNG')).toBeTruthy()
+    })
+  })
+
+  test('renders menu items with icons when provided', async () => {
+    const mockIcon = <span data-testid='test-icon'>Icon</span>
+    const mockDownload: DownloadItem[] = [
+      {
+        id: 'csv',
+        label: 'CSV',
+        icon: mockIcon,
+        modifier: vi.fn().mockResolvedValue('data:text/csv;base64,'),
+      },
+    ]
+
+    render(<Download id={widgetId} items={mockDownload} />)
+
+    const button = screen.getByRole('button', { name: 'download options' })
+    fireEvent.click(button)
+
+    await waitFor(() => {
+      expect(screen.getByTestId('test-icon')).toBeTruthy()
+    })
+  })
+
+  test('calls modifier and triggers download when menu item is clicked', async () => {
+    const mockModifier = vi.fn().mockResolvedValue('data:text/csv;base64,test')
+    const mockCallback = vi.fn()
+    const mockDownload: DownloadItem[] = [
+      {
+        id: 'csv',
+        label: 'CSV',
+        filename: 'test.csv',
+        modifier: mockModifier,
+        callback: mockCallback,
+      },
+    ]
+
+    useWidgetStore.getState().setWidget(widgetId, {
+      data: [['test', 'data']],
+    })
+
+    // Mock document methods
+    const createElementSpy = vi.spyOn(document, 'createElement')
+    const appendChildSpy = vi.spyOn(document.body, 'appendChild')
+    const removeChildSpy = vi.spyOn(document.body, 'removeChild')
+
+    render(<Download id={widgetId} items={mockDownload} />)
+
+    const button = screen.getByRole('button', { name: 'download options' })
+    fireEvent.click(button)
+
+    const csvMenuItem = await screen.findByText('CSV')
+    fireEvent.click(csvMenuItem)
+
+    await waitFor(() => {
+      expect(mockModifier).toHaveBeenCalledWith([['test', 'data']])
+      expect(createElementSpy).toHaveBeenCalledWith('a')
+      expect(mockCallback).toHaveBeenCalled()
+    })
+
+    createElementSpy.mockRestore()
+    appendChildSpy.mockRestore()
+    removeChildSpy.mockRestore()
+  })
+
+  test('shows loading spinner during download', async () => {
+    const mockModifier = vi.fn().mockImplementation(
+      () =>
+        new Promise((resolve) => {
+          setTimeout(() => resolve('data:text/csv;base64,test'), 100)
+        }),
+    )
+
+    const mockDownload: DownloadItem[] = [
+      {
+        id: 'csv',
+        label: 'CSV',
+        modifier: mockModifier,
+      },
+    ]
+
+    render(<Download id={widgetId} items={mockDownload} />)
+
+    const button = screen.getByRole('button', { name: 'download options' })
+    fireEvent.click(button)
+
+    const csvMenuItem = await screen.findByText('CSV')
+    fireEvent.click(csvMenuItem)
+
+    // Check that loading spinner is shown during download
+    await waitFor(() => {
+      expect(screen.getByRole('progressbar')).toBeTruthy()
+    })
+
+    // Wait for download to complete and spinner to disappear
+    await waitFor(
+      () => {
+        expect(screen.queryByRole('progressbar')).toBeNull()
+      },
+      { timeout: 200 },
+    )
+  })
+
+  test('handles disabled menu items', async () => {
+    const mockDownload: DownloadItem[] = [
+      {
+        id: 'csv',
+        label: 'CSV',
+        disabled: true,
+        modifier: vi.fn().mockResolvedValue('data:text/csv;base64,'),
+      },
+    ]
+
+    render(<Download id={widgetId} items={mockDownload} />)
+
+    const button = screen.getByRole('button', { name: 'download options' })
+    fireEvent.click(button)
+
+    const csvMenuItem = await screen.findByText('CSV')
+    expect(csvMenuItem.closest('li')?.getAttribute('aria-disabled')).toBe(
+      'true',
+    )
+  })
+
+  test('closes menu after clicking a menu item', async () => {
+    const mockDownload: DownloadItem[] = [
+      {
+        id: 'csv',
+        label: 'CSV',
+        modifier: vi.fn().mockResolvedValue('data:text/csv;base64,'),
+      },
+    ]
+
+    render(<Download id={widgetId} items={mockDownload} />)
+
+    const button = screen.getByRole('button', { name: 'download options' })
+    fireEvent.click(button)
+
+    const csvMenuItem = await screen.findByText('CSV')
+    fireEvent.click(csvMenuItem)
+
+    await waitFor(() => {
+      expect(screen.queryByRole('menu')).toBeNull()
+    })
+  })
+
+  test('does not download if modifier returns undefined', async () => {
+    const mockModifier = vi.fn().mockResolvedValue(undefined)
+    const mockCallback = vi.fn()
+    const mockDownload: DownloadItem[] = [
+      {
+        id: 'csv',
+        label: 'CSV',
+        modifier: mockModifier,
+        callback: mockCallback,
+      },
+    ]
+
+    const createElementSpy = vi.spyOn(document, 'createElement')
+
+    render(<Download id={widgetId} items={mockDownload} />)
+
+    const button = screen.getByRole('button', { name: 'download options' })
+    fireEvent.click(button)
+
+    const csvMenuItem = await screen.findByText('CSV')
+    fireEvent.click(csvMenuItem)
+
+    await waitFor(() => {
+      expect(mockModifier).toHaveBeenCalled()
+    })
+
+    // Should not create download link (check for 'a' element specifically)
+    expect(createElementSpy).not.toHaveBeenCalledWith('a')
+    expect(mockCallback).not.toHaveBeenCalled()
+
+    createElementSpy.mockRestore()
+  })
+
+  test('stops event propagation on button click', () => {
+    const mockDownload: DownloadItem[] = [
+      {
+        id: 'csv',
+        label: 'CSV',
+        modifier: vi.fn().mockResolvedValue('data:text/csv;base64,'),
+      },
+    ]
+
+    const parentClickHandler = vi.fn()
+
+    render(
+      // eslint-disable-next-line jsx-a11y/click-events-have-key-events, jsx-a11y/no-static-element-interactions
+      <div onClick={parentClickHandler}>
+        <Download id={widgetId} items={mockDownload} />
+      </div>,
+    )
+
+    const button = screen.getByRole('button', { name: 'download options' })
+    fireEvent.click(button)
+
+    expect(parentClickHandler).not.toHaveBeenCalled()
+  })
+
+  test('uses widget id as default filename when filename is not provided', async () => {
+    const mockModifier = vi.fn().mockResolvedValue('data:text/csv;base64,test')
+    const mockDownload: DownloadItem[] = [
+      {
+        id: 'csv',
+        label: 'CSV',
+        modifier: mockModifier,
+      },
+    ]
+
+    let capturedLink: HTMLAnchorElement | null = null
+    const originalCreateElement = document.createElement.bind(document)
+    const createElementSpy = vi
+      .spyOn(document, 'createElement')
+      .mockImplementation((tagName: string) => {
+        const element = originalCreateElement(tagName)
+        if (tagName === 'a') {
+          capturedLink = element as HTMLAnchorElement
+        }
+        return element
+      })
+
+    render(<Download id={widgetId} items={mockDownload} />)
+
+    const button = screen.getByRole('button', { name: 'download options' })
+    fireEvent.click(button)
+
+    const csvMenuItem = await screen.findByText('CSV')
+    fireEvent.click(csvMenuItem)
+
+    await waitFor(() => {
+      expect(capturedLink?.download).toBe(widgetId)
+    })
+
+    createElementSpy.mockRestore()
+  })
+})

package/src/widgets/actions/download/download.tsx

@@ -0,0 +1,118 @@
+import {
+  CircularProgress,
+  IconButton,
+  ListItemIcon,
+  ListItemText,
+  Menu,
+  MenuItem,
+} from '@mui/material'
+import type { DownloadItem, DownloadProps } from './types'
+import { FileDownloadOutlined } from '@mui/icons-material'
+import { useState, type MouseEvent } from 'react'
+import { useWidgetStore } from '../../../widgets'
+import { useShallow } from 'zustand/shallow'
+
+export function Download({
+  id,
+  items,
+  labels = {},
+  Icon,
+  IconButtonProps,
+}: DownloadProps) {
+  const data = useWidgetStore(useShallow((state) => state.getWidget(id)?.data))
+
+  const [isDownloading, setIsDownloading] = useState(false)
+  const [anchorEl, setAnchorEl] = useState<null | HTMLElement>(null)
+
+  const handleToggle = (event: MouseEvent<HTMLElement>) => {
+    event.stopPropagation()
+    setAnchorEl(event.currentTarget)
+  }
+
+  const handleDownload = (data: string, option: DownloadItem) => {
+    const link = document.createElement('a')
+    link.href = data
+    link.download = option.filename ?? id
+    link.style.display = 'none'
+    document.body.appendChild(link)
+    link.click()
+    document.body.removeChild(link)
+    option.callback?.(link.href)
+  }
+
+  const handleClick = async (
+    event: MouseEvent<HTMLElement>,
+    option: DownloadItem,
+  ) => {
+    event.stopPropagation()
+
+    setIsDownloading(true)
+    setAnchorEl(null)
+
+    const result = await option.modifier(data)
+
+    if (!result) {
+      setIsDownloading(false)
+      return
+    }
+
+    handleDownload(result, option)
+    setIsDownloading(false)
+  }
+
+  return (
+    <>
+      <IconButton
+        size='small'
+        aria-label={labels.ariaLabel ?? 'download options'}
+        aria-controls='options-menu'
+        aria-haspopup='true'
+        onClick={handleToggle}
+        {...IconButtonProps}
+        disabled={isDownloading || items.length === 0}
+        className={isDownloading || anchorEl ? 'active' : ''}
+      >
+        {isDownloading ? (
+          <CircularProgress size={18} color='inherit' />
+        ) : (
+          (Icon ?? <FileDownloadOutlined />)
+        )}
+      </IconButton>
+      <Menu
+        variant='menu'
+        elevation={8}
+        anchorOrigin={{
+          vertical: 'bottom',
+          horizontal: 'right',
+        }}
+        transformOrigin={{
+          vertical: 'top',
+          horizontal: 'right',
+        }}
+        anchorEl={anchorEl}
+        open={Boolean(anchorEl)}
+        onClose={() => setAnchorEl(null)}
+        MenuListProps={{
+          sx: {
+            paddingBottom: 0,
+          },
+        }}
+      >
+        {items.map((option) => (
+          <MenuItem
+            key={option.id}
+            disabled={option.disabled}
+            onClick={(e) => void handleClick(e, option)}
+          >
+            {option.icon && (
+              <ListItemIcon sx={{ color: 'text.primary' }}>
+                {option.icon}
+              </ListItemIcon>
+            )}
+            <ListItemText>{option.label}</ListItemText>
+          </MenuItem>
+        ))}
+      </Menu>
+    </>
+  )
+}

package/src/widgets/actions/download/exports.test.tsx

@@ -0,0 +1,275 @@
+import { describe, test, expect, vi, beforeEach, afterEach } from 'vitest'
+import { downloadToCSV, downloadToPNG } from './exports'
+import { createRef } from 'react'
+import type { RefObject } from 'react'
+
+// Mock html2canvas
+vi.mock('html2canvas', () => ({
+  default: vi.fn(),
+}))
+
+describe('downloadToCSV', () => {
+  test('has correct label', () => {
+    expect(downloadToCSV.label).toBe('CSV')
+  })
+
+  test('has icon', () => {
+    expect(downloadToCSV.icon).toBeTruthy()
+  })
+
+  test('converts data to CSV format', async () => {
+    const data: string[][] = [
+      ['Name', 'Age', 'City'],
+      ['John', '30', 'New York'],
+      ['Jane', '25', 'Los Angeles'],
+    ]
+
+    const result = await downloadToCSV.modifier(data)
+
+    expect(result).toBeTruthy()
+    expect(result).toContain('blob:')
+  })
+
+  test('creates blob URL from CSV data', async () => {
+    const data: string[][] = [
+      ['a', 'b'],
+      ['c', 'd'],
+    ]
+
+    const result = await downloadToCSV.modifier(data)
+
+    expect(result).toBeTruthy()
+    expect(typeof result).toBe('string')
+    expect(result!.startsWith('blob:')).toBe(true)
+  })
+
+  test('callback revokes object URL', () => {
+    const revokeObjectURLSpy = vi.spyOn(URL, 'revokeObjectURL')
+    const testUrl = 'blob:test-url'
+
+    downloadToCSV.callback?.(testUrl)
+
+    expect(revokeObjectURLSpy).toHaveBeenCalledWith(testUrl)
+
+    revokeObjectURLSpy.mockRestore()
+  })
+
+  test('handles empty data array', async () => {
+    const data: unknown[][] = []
+
+    const result = await downloadToCSV.modifier(data)
+
+    expect(result).toBeTruthy()
+  })
+
+  test('handles single row data', async () => {
+    const data: string[][] = [['single', 'row']]
+
+    const result = await downloadToCSV.modifier(data)
+
+    expect(result).toBeTruthy()
+    expect(result).toContain('blob:')
+  })
+
+  test('handles data with special characters', async () => {
+    const data: string[][] = [
+      ['Name', 'Description'],
+      ['Test', 'Hello, World!'],
+    ]
+
+    const result = await downloadToCSV.modifier(data)
+
+    expect(result).toBeTruthy()
+  })
+})
+
+describe('downloadToPNG', () => {
+  let mockRef: RefObject<HTMLDivElement>
+  let mockElement: HTMLDivElement
+
+  beforeEach(() => {
+    // Create a real DOM element
+    mockElement = document.createElement('div')
+    mockElement.style.width = '800px'
+    mockElement.style.height = '600px'
+    document.body.appendChild(mockElement)
+
+    mockRef = createRef() as RefObject<HTMLDivElement>
+    // Manually set the current property
+    Object.defineProperty(mockRef, 'current', {
+      writable: true,
+      value: mockElement,
+    })
+  })
+
+  afterEach(() => {
+    document.body.removeChild(mockElement)
+    vi.clearAllMocks()
+  })
+
+  test('returns download item with correct label', () => {
+    expect(downloadToPNG.label).toBe('PNG')
+  })
+
+  test('has icon', () => {
+    expect(downloadToPNG.icon).toBeTruthy()
+  })
+
+  test('modifier returns undefined when ref is null', async () => {
+    const nullRef = createRef() as RefObject<HTMLDivElement>
+
+    const result = await downloadToPNG.modifier(nullRef)
+
+    expect(result).toBeUndefined()
+  })
+
+  test('modifier returns undefined when ref is a function', async () => {
+    const functionRef = vi.fn() as unknown as RefObject<HTMLDivElement>
+
+    const result = await downloadToPNG.modifier(functionRef)
+
+    expect(result).toBeUndefined()
+  })
+
+  test('removes toolbar and actions containers from clone', async () => {
+    const html2canvas = (await import('html2canvas')).default as ReturnType<
+      typeof vi.fn
+    >
+
+    const toolbar = document.createElement('div')
+    toolbar.className = 'widget-toolbar-container'
+    mockElement.appendChild(toolbar)
+
+    const actions = document.createElement('div')
+    actions.className = 'widget-wrapper-actions'
+    mockElement.appendChild(actions)
+
+    const mockCanvas = document.createElement('canvas')
+    mockCanvas.toDataURL = vi.fn().mockReturnValue('data:image/png;base64,test')
+
+    let cloneElement: HTMLElement | undefined
+
+    html2canvas.mockImplementation((element: HTMLElement) => {
+      cloneElement = element
+      return mockCanvas
+    })
+
+    await downloadToPNG.modifier(mockRef)
+
+    // The clone should not have toolbar or actions
+    expect(cloneElement?.querySelector('.widget-toolbar-container')).toBeNull()
+    expect(cloneElement?.querySelector('.widget-wrapper-actions')).toBeNull()
+  })
+
+  test('does not modify original element', async () => {
+    const html2canvas = (await import('html2canvas')).default as ReturnType<
+      typeof vi.fn
+    >
+
+    const toolbar = document.createElement('div')
+    toolbar.className = 'widget-toolbar-container'
+    mockElement.appendChild(toolbar)
+
+    const actions = document.createElement('div')
+    actions.className = 'widget-wrapper-actions'
+    mockElement.appendChild(actions)
+
+    const mockCanvas = document.createElement('canvas')
+    mockCanvas.toDataURL = vi.fn().mockReturnValue('data:image/png;base64,test')
+
+    html2canvas.mockResolvedValue(mockCanvas)
+
+    await downloadToPNG.modifier(mockRef)
+
+    // Original element should still have toolbar and actions
+    expect(mockElement.querySelector('.widget-toolbar-container')).toBe(toolbar)
+    expect(mockElement.querySelector('.widget-wrapper-actions')).toBe(actions)
+  })
+
+  test('calls html2canvas with correct options', async () => {
+    const html2canvas = (await import('html2canvas')).default as ReturnType<
+      typeof vi.fn
+    >
+
+    const mockCanvas = document.createElement('canvas')
+    mockCanvas.toDataURL = vi.fn().mockReturnValue('data:image/png;base64,test')
+
+    html2canvas.mockResolvedValue(mockCanvas)
+
+    await downloadToPNG.modifier(mockRef)
+
+    expect(html2canvas).toHaveBeenCalledWith(
+      mockElement,
+      expect.objectContaining({
+        useCORS: true,
+        scale: 2,
+        backgroundColor: '#fff',
+      }),
+    )
+  })
+
+  test('returns PNG data URL', async () => {
+    const html2canvas = (await import('html2canvas')).default as ReturnType<
+      typeof vi.fn
+    >
+
+    const mockCanvas = document.createElement('canvas')
+    const testDataUrl = 'data:image/png;base64,testdata'
+    mockCanvas.toDataURL = vi.fn().mockReturnValue(testDataUrl)
+
+    html2canvas.mockResolvedValue(mockCanvas)
+
+    const result = await downloadToPNG.modifier(mockRef)
+
+    expect(result).toBe(testDataUrl)
+  })
+
+  test('calculates dimensions from clone element', async () => {
+    const html2canvas = (await import('html2canvas')).default as ReturnType<
+      typeof vi.fn
+    >
+
+    const toolbar = document.createElement('div')
+    toolbar.className = 'widget-toolbar-container'
+    toolbar.style.height = '50px'
+    mockElement.appendChild(toolbar)
+
+    const mockCanvas = document.createElement('canvas')
+    mockCanvas.toDataURL = vi.fn().mockReturnValue('data:image/png;base64,test')
+
+    let calledElement: HTMLElement | null = null
+
+    html2canvas.mockImplementation((element) => {
+      calledElement = element as HTMLElement
+      return mockCanvas
+    })
+
+    await downloadToPNG.modifier(mockRef)
+
+    // Should be called with a clone (different element)
+    expect(calledElement).not.toBe(mockElement)
+    expect(html2canvas).toHaveBeenCalledWith(
+      calledElement,
+      expect.objectContaining({
+        height: expect.any(Number) as number,
+        width: expect.any(Number) as number,
+      }),
+    )
+  })
+
+  test('handles element without toolbar or actions', async () => {
+    const html2canvas = (await import('html2canvas')).default as ReturnType<
+      typeof vi.fn
+    >
+
+    const mockCanvas = document.createElement('canvas')
+    mockCanvas.toDataURL = vi.fn().mockReturnValue('data:image/png;base64,test')
+
+    html2canvas.mockResolvedValue(mockCanvas)
+
+    const result = await downloadToPNG.modifier(mockRef)
+
+    expect(result).toBeTruthy()
+    expect(result).toContain('data:image/png')
+  })
+})