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

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

@@ -0,0 +1,288 @@
+import {
+  describe,
+  test,
+  expect,
+  vi,
+  beforeEach,
+  afterEach,
+  type MockInstance,
+} 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
+  let warnSpy: MockInstance<typeof console.warn>
+
+  beforeEach(() => {
+    warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined)
+    // 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)
+    warnSpy.mockRestore()
+    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()
+    expect(warnSpy).toHaveBeenCalled()
+  })
+
+  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()
+    expect(warnSpy).toHaveBeenCalled()
+  })
+
+  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')
+  })
+})

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

@@ -0,0 +1,118 @@
+import type { Ref } from 'react'
+import type { DownloadItem } from './types'
+import html2canvas from 'html2canvas'
+import { ImageOutlined } from '@mui/icons-material'
+import { SvgIcon } from '@mui/material'
+
+// Helper to escape CSV cell values
+function escapeCSVCell<D>(value: D): string {
+  const str =
+    value == null
+      ? ''
+      : typeof value === 'object'
+        ? JSON.stringify(value)
+        : String(value)
+
+  // If the value contains a comma, quote, or newline, wrap in quotes and escape quotes
+  if (/[",\n]/.test(str)) {
+    return `"${str.replace(/"/g, '""')}"`
+  }
+  return str
+}
+
+async function downloadFileToCSV<D>(data: D[][]) {
+  const csvContent = data
+    .map((row) => row.map(escapeCSVCell<D>).join(','))
+    .join('\n')
+  const blob = new Blob([csvContent], { type: 'text/csv;charset=utf-8;' })
+  return Promise.resolve(URL.createObjectURL(blob))
+}
+
+/**
+ * Pre-configured download item for exporting widget data as a CSV file.
+ *
+ * Converts a 2D array of data into CSV format with proper escaping and
+ * triggers a browser download. Revokes the object URL after download.
+ */
+export const downloadToCSV: DownloadItem<unknown[][]> = {
+  id: 'csv',
+  label: 'CSV',
+  icon: (
+    <SvgIcon>
+      <svg
+        xmlns='http://www.w3.org/2000/svg'
+        width='18'
+        height='18'
+        fill='none'
+        viewBox='0 0 18 18'
+      >
+        <path
+          fill='currentColor'
+          d='M4.313 11.25h2.25v-1.125H4.688v-2.25h1.875V6.75h-2.25a.726.726 0 0 0-.535.216.726.726 0 0 0-.216.534v3c0 .213.072.39.216.534a.726.726 0 0 0 .534.216Zm2.925 0h2.25c.212 0 .39-.072.534-.216a.726.726 0 0 0 .216-.534V9.375a.931.931 0 0 0-.216-.59.658.658 0 0 0-.534-.273H8.363v-.637h1.875V6.75h-2.25a.726.726 0 0 0-.535.216.726.726 0 0 0-.216.534v1.125c0 .213.072.403.216.572a.675.675 0 0 0 .534.253h1.126v.675H7.238v1.125Zm4.95 0h1.124l1.313-4.5H13.5l-.75 2.588L12 6.75h-1.125l1.313 4.5ZM3 15c-.413 0-.766-.147-1.06-.44a1.445 1.445 0 0 1-.44-1.06v-9c0-.412.147-.766.44-1.06C2.235 3.148 2.588 3 3 3h12c.412 0 .766.147 1.06.44.293.294.44.648.44 1.06v9c0 .412-.147.766-.44 1.06-.294.293-.647.44-1.06.44H3Zm0-1.5h12v-9H3v9Z'
+        />
+      </svg>
+    </SvgIcon>
+  ),
+  modifier: downloadFileToCSV,
+  callback: (data) => {
+    URL.revokeObjectURL(data)
+  },
+}
+
+async function downloadFileToPNG(ref: Ref<HTMLElement | null> | undefined) {
+  if (!ref || typeof ref === 'function' || !ref.current) {
+    // eslint-disable-next-line no-console
+    console.warn(
+      '[CARTO downloadFileToPNG] Invalid ref passed to downloadFileToPNG. ' +
+        'Expected a React ref object with a .current property pointing to an HTMLElement. ' +
+        'Download aborted.',
+    )
+    return
+  }
+
+  const element = ref.current
+  const clone = element.cloneNode(true) as HTMLElement
+
+  clone.querySelector('.widget-toolbar-container')?.remove()
+  clone.querySelector('.widget-wrapper-actions')?.remove()
+
+  document.body.appendChild(clone)
+
+  const rect = clone.getBoundingClientRect()
+
+  const opts = {
+    useCORS: true,
+    scale: 2,
+    backgroundColor: '#fff',
+    width: rect.width,
+    height: rect.height,
+  }
+
+  const canvasResult: HTMLCanvasElement = await html2canvas(clone, opts)
+
+  const result = canvasResult.toDataURL('image/png')
+
+  document.body.removeChild(clone)
+
+  return Promise.resolve(result)
+}
+
+/**
+ * Pre-configured download item for exporting a widget as a PNG image.
+ *
+ * Uses html2canvas to capture the widget DOM element referenced by a React ref.
+ * Strips toolbar and action elements before capturing.
+ *
+ * @remarks
+ * The modifier expects a React ref to the widget's root HTML element, not raw data.
+ */
+export const downloadToPNG: Omit<DownloadItem, 'modifier'> & {
+  modifier: (
+    ref: Ref<HTMLElement | null> | undefined,
+  ) => Promise<string | undefined>
+} = {
+  id: 'png',
+  label: 'PNG',
+  icon: <ImageOutlined />,
+  modifier: downloadFileToPNG,
+}

package/src/widgets/actions/download/types.ts

@@ -0,0 +1,21 @@
+import type { JSX, ReactNode } from 'react'
+import type { IconButtonProps } from '@mui/material'
+import type { WidgetState } from '../../stores/types'
+
+export interface DownloadItem<D = unknown> {
+  id: string
+  label: string
+  icon?: JSX.Element
+  disabled?: boolean
+  filename?: string
+  modifier: (data: D) => Promise<string | undefined>
+  callback?: (data: string) => void
+}
+
+export interface DownloadProps {
+  id: WidgetState['id']
+  items: DownloadItem[]
+  labels?: { ariaLabel?: string }
+  IconButtonProps?: IconButtonProps
+  Icon?: ReactNode
+}

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

@@ -0,0 +1,269 @@
+import { describe, test, expect, beforeEach } from 'vitest'
+import { render, screen, fireEvent, within } from '@testing-library/react'
+import { FullScreen } from './fullscreen'
+import { useWidgetStore } from '../../stores/widget-store'
+import type { FullScreenState } from './types'
+
+describe('FullScreen', () => {
+  const widgetId = 'test-widget'
+
+  beforeEach(() => {
+    // Clear store before each test
+    useWidgetStore.getState().clearWidgets()
+    // Initialize widget with title
+    useWidgetStore.getState().setWidget<FullScreenState>(widgetId, {
+      title: 'Test Widget',
+    })
+  })
+
+  test('renders fullscreen button', () => {
+    render(
+      <FullScreen id={widgetId}>
+        <div>Widget Content</div>
+      </FullScreen>,
+    )
+
+    const button = screen.getByRole('button')
+    expect(button).toBeTruthy()
+  })
+
+  test('opens dialog when fullscreen button is clicked', () => {
+    render(
+      <FullScreen id={widgetId}>
+        <div>Widget Content</div>
+      </FullScreen>,
+    )
+
+    const button = screen.getByRole('button')
+    fireEvent.click(button)
+
+    // Check if dialog is opened
+    expect(screen.getByText('Test Widget')).toBeTruthy()
+    expect(screen.getByText('Widget Content')).toBeTruthy()
+  })
+
+  test('closes dialog when close button is clicked', () => {
+    render(
+      <FullScreen id={widgetId}>
+        <div>Widget Content</div>
+      </FullScreen>,
+    )
+
+    // Open dialog
+    const openButton = screen.getByRole('button')
+    fireEvent.click(openButton)
+
+    // Find and click close button (inside the dialog)
+    const dialog = screen.getByRole('dialog')
+    const closeButton = within(dialog).getAllByRole('button')[0]
+
+    fireEvent.click(closeButton!)
+
+    // Store should be updated
+    const widget = useWidgetStore
+      .getState()
+      .getWidget<FullScreenState>(widgetId)
+    expect(widget?.isFullScreen).toBe(false)
+  })
+
+  test('uses custom aria label when provided', () => {
+    const customLabels = {
+      ariaLabel: 'custom-fullscreen-dialog',
+    }
+
+    render(
+      <FullScreen id={widgetId} labels={customLabels}>
+        <div>Widget Content</div>
+      </FullScreen>,
+    )
+
+    const button = screen.getByRole('button')
+    fireEvent.click(button)
+
+    const dialog = screen.getByRole('dialog')
+    expect(dialog.getAttribute('aria-labelledby')).toBe(
+      'custom-fullscreen-dialog',
+    )
+  })
+
+  test('uses default aria label when not provided', () => {
+    render(
+      <FullScreen id={widgetId}>
+        <div>Widget Content</div>
+      </FullScreen>,
+    )
+
+    const button = screen.getByRole('button')
+    fireEvent.click(button)
+
+    const dialog = screen.getByRole('dialog')
+    expect(dialog.getAttribute('aria-labelledby')).toBe(
+      `fullscreen-dialog-title-${widgetId}`,
+    )
+  })
+
+  test('renders children inside dialog content', () => {
+    const TestChild = () => (
+      <div>
+        <p>First paragraph</p>
+        <p>Second paragraph</p>
+      </div>
+    )
+
+    render(
+      <FullScreen id={widgetId}>
+        <TestChild />
+      </FullScreen>,
+    )
+
+    const button = screen.getByRole('button')
+    fireEvent.click(button)
+
+    expect(screen.getByText('First paragraph')).toBeTruthy()
+    expect(screen.getByText('Second paragraph')).toBeTruthy()
+  })
+
+  test('dialog is not visible initially', () => {
+    render(
+      <FullScreen id={widgetId}>
+        <div>Widget Content</div>
+      </FullScreen>,
+    )
+
+    // Dialog should not be rendered until button is clicked
+    expect(screen.queryByRole('dialog')).toBeNull()
+  })
+
+  test('updates widget store when opening fullscreen', () => {
+    render(
+      <FullScreen id={widgetId}>
+        <div>Widget Content</div>
+      </FullScreen>,
+    )
+
+    const button = screen.getByRole('button')
+    fireEvent.click(button)
+
+    const widget = useWidgetStore
+      .getState()
+      .getWidget<FullScreenState>(widgetId)
+    expect(widget?.isFullScreen).toBe(true)
+  })
+
+  test('updates widget store when closing fullscreen', () => {
+    // Pre-set the widget to fullscreen
+    useWidgetStore.getState().setWidget<FullScreenState>(widgetId, {
+      title: 'Test Widget',
+      isFullScreen: true,
+    })
+
+    render(
+      <FullScreen id={widgetId}>
+        <div>Widget Content</div>
+      </FullScreen>,
+    )
+
+    // Find and click close button
+    const dialog = screen.getByRole('dialog')
+    const closeButton = within(dialog).getAllByRole('button')[0]
+
+    fireEvent.click(closeButton!)
+
+    const widget = useWidgetStore
+      .getState()
+      .getWidget<FullScreenState>(widgetId)
+    expect(widget?.isFullScreen).toBe(false)
+  })
+
+  test('handles multiple fullscreen widgets independently', () => {
+    const widget1Id = 'widget-1'
+    const widget2Id = 'widget-2'
+
+    // Initialize both widgets with titles
+    useWidgetStore.getState().setWidget<FullScreenState>(widget1Id, {
+      title: 'Widget 1',
+    })
+    useWidgetStore.getState().setWidget<FullScreenState>(widget2Id, {
+      title: 'Widget 2',
+    })
+
+    render(
+      <>
+        <FullScreen id={widget1Id}>
+          <div>Content 1</div>
+        </FullScreen>
+        <FullScreen id={widget2Id}>
+          <div>Content 2</div>
+        </FullScreen>
+      </>,
+    )
+
+    const buttons = screen.getAllByRole('button')
+
+    // Open first widget
+    fireEvent.click(buttons[0]!)
+    let widget1 = useWidgetStore
+      .getState()
+      .getWidget<FullScreenState>(widget1Id)
+    let widget2 = useWidgetStore
+      .getState()
+      .getWidget<FullScreenState>(widget2Id)
+
+    expect(widget1?.isFullScreen).toBe(true)
+    expect(widget2?.isFullScreen).toBeUndefined()
+
+    // Verify widget 1 content is displayed
+    expect(screen.getByText('Content 1')).toBeTruthy()
+
+    // Close first widget via store (simpler than clicking)
+    useWidgetStore.getState().setWidget<FullScreenState>(widget1Id, {
+      title: 'Widget 1',
+      isFullScreen: false,
+    })
+
+    // Open second widget
+    fireEvent.click(buttons[1]!)
+
+    widget1 = useWidgetStore.getState().getWidget<FullScreenState>(widget1Id)
+    widget2 = useWidgetStore.getState().getWidget<FullScreenState>(widget2Id)
+
+    expect(widget1?.isFullScreen).toBe(false)
+    expect(widget2?.isFullScreen).toBe(true)
+
+    // Verify widget 2 content is displayed
+    expect(screen.getByText('Content 2')).toBeTruthy()
+  })
+
+  test('renders dialog title with correct typography', () => {
+    render(
+      <FullScreen id={widgetId}>
+        <div>Widget Content</div>
+      </FullScreen>,
+    )
+
+    const button = screen.getByRole('button')
+    fireEvent.click(button)
+
+    const title = screen.getByText('Test Widget')
+    expect(title).toBeTruthy()
+    expect(title.tagName).toBe('SPAN')
+  })
+
+  test('dialog respects isFullScreen state from store', () => {
+    // Set initial state to fullscreen
+    useWidgetStore.getState().setWidget<FullScreenState>(widgetId, {
+      title: 'Test Widget',
+      isFullScreen: true,
+    })
+
+    render(
+      <FullScreen id={widgetId}>
+        <div>Widget Content</div>
+      </FullScreen>,
+    )
+
+    // Dialog should be visible immediately
+    expect(screen.getByRole('dialog')).toBeTruthy()
+    expect(screen.getByText('Widget Content')).toBeTruthy()
+  })
+})