@carto/ps-react-ui 5.3.0 → 6.1.0

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

@@ -1,288 +1,198 @@
-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'
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { render } from '@testing-library/react'
+
+// Hoisted mock for html2canvas — tests reach into `mockToBlob` to switch
+// between "blob produced" and "toBlob returned null" without re-mocking.
+type ToBlobCb = (blob: Blob | null) => void
+const mockToBlob = vi.fn((cb: ToBlobCb) => cb(new Blob(['png-bytes'])))
 
-// Mock html2canvas
 vi.mock('html2canvas', () => ({
-  default: vi.fn(),
+  default: () => Promise.resolve({ toBlob: mockToBlob }),
 }))
 
-describe('downloadToCSV', () => {
-  test('has correct label', () => {
-    expect(downloadToCSV.label).toBe('CSV')
-  })
+import {
+  toCsvString,
+  downloadToCSV,
+  triggerLinkDownload,
+  downloadDOMToPNG,
+  sanitizeFilename,
+} from './exports'
+import { CSVIcon, PNGIcon } from './icons'
+
+let csvText = ''
+
+let revokeSpy: ReturnType<typeof vi.spyOn>
+
+beforeEach(() => {
+  csvText = ''
+  mockToBlob.mockReset()
+  mockToBlob.mockImplementation((cb: ToBlobCb) => cb(new Blob(['png-bytes'])))
+  vi.spyOn(URL, 'createObjectURL').mockReturnValue('blob:mock')
+  revokeSpy = vi
+    .spyOn(URL, 'revokeObjectURL')
+    .mockImplementation(() => undefined)
+  const RealBlob = global.Blob
+  vi.stubGlobal(
+    'Blob',
+    class extends RealBlob {
+      constructor(parts: BlobPart[], opts?: BlobPropertyBag) {
+        csvText = typeof parts[0] === 'string' ? parts[0] : ''
+        super(parts, opts)
+      }
+    },
+  )
+})
 
-  test('has icon', () => {
-    expect(downloadToCSV.icon).toBeTruthy()
+describe('toCsvString', () => {
+  it('joins rows with newlines and cells with commas', () => {
+    expect(
+      toCsvString([
+        ['name', 'value'],
+        ['a', 1],
+        ['b', 2],
+      ]),
+    ).toBe('name,value\na,1\nb,2')
   })
 
-  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:')
+  it('emits blank cells for null and undefined', () => {
+    expect(toCsvString([[null, undefined, 'x']])).toBe(',,x')
   })
 
-  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)
+  it('stringifies numbers and booleans', () => {
+    expect(toCsvString([[1, false, true]])).toBe('1,false,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()
+  it('JSON.stringifies objects and arrays', () => {
+    expect(toCsvString([[{ a: 1 }, [1, 2]]])).toBe('"{""a"":1}","[1,2]"')
   })
 
-  test('handles empty data array', async () => {
-    const data: unknown[][] = []
-
-    const result = await downloadToCSV.modifier(data)
-
-    expect(result).toBeTruthy()
+  it('quotes cells containing comma / quote / newline', () => {
+    expect(toCsvString([['a,b', 'he said "hi"', 'line1\nline2']])).toBe(
+      '"a,b","he said ""hi""","line1\nline2"',
+    )
   })
 
-  test('handles single row data', async () => {
-    const data: string[][] = [['single', 'row']]
-
-    const result = await downloadToCSV.modifier(data)
+  describe('formula injection guard', () => {
+    it.each([
+      [
+        '=',
+        '=HYPERLINK("https://attacker.example")',
+        '\'=HYPERLINK("https://attacker.example")',
+      ],
+      ['+', '+1+1', "'+1+1"],
+      ['-', '-2+1', "'-2+1"],
+      ['@', '@SUM(A1:A2)', "'@SUM(A1:A2)"],
+      ['\\t', '\tleading-tab', "'\tleading-tab"],
+      ['\\r', '\rleading-cr', "'\rleading-cr"],
+    ])(
+      'prefixes cells starting with %s with a single quote',
+      (_label, raw, expectedRaw) => {
+        // The escape step also quotes if the value contains comma/quote/newline,
+        // so we re-derive the exact wire representation from the raw expected.
+        const expected = /[",\n\r]/.test(expectedRaw)
+          ? `"${expectedRaw.replace(/"/g, '""')}"`
+          : expectedRaw
+        expect(toCsvString([[raw]])).toBe(expected)
+      },
+    )
 
-    expect(result).toBeTruthy()
-    expect(result).toContain('blob:')
+    it('does not touch values where the dangerous char is not leading', () => {
+      expect(toCsvString([['a=b']])).toBe('a=b')
+      expect(toCsvString([['1+2']])).toBe('1+2')
+    })
   })
+})
 
-  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('downloadToCSV', () => {
+  it('serialises rows then wraps them in a URL handle with a working revoke', () => {
+    const handle = downloadToCSV([['x', 1]])
+    expect(handle.url).toBe('blob:mock')
+    expect(csvText).toBe('x,1')
+    handle.revoke?.()
+    expect(revokeSpy).toHaveBeenCalledWith('blob:mock')
   })
 })
 
-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,
+describe('triggerLinkDownload', () => {
+  it('synthesises an anchor, clicks it, then removes it', () => {
+    const appendSpy = vi.spyOn(document.body, 'appendChild')
+    triggerLinkDownload({ url: 'blob:x', filename: 'demo.csv' })
+    expect(appendSpy).toHaveBeenCalled()
+    const anchor = appendSpy.mock.calls[0]?.[0] as HTMLAnchorElement
+    expect(anchor.href).toBe('blob:x')
+    expect(anchor.download).toBe('demo.csv')
+    expect(anchor.isConnected).toBe(false)
+  })
+
+  it('applies sanitizeFilename to the anchor download attribute', () => {
+    const appendSpy = vi.spyOn(document.body, 'appendChild')
+    const before = appendSpy.mock.calls.length
+    triggerLinkDownload({
+      url: 'blob:y',
+      filename: '..\\evil\r\nname.csv',
     })
+    const anchor = appendSpy.mock.calls[before]?.[0] as HTMLAnchorElement
+    expect(anchor.download).toBe('.._evil__name.csv')
   })
+})
 
-  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()
+describe('sanitizeFilename', () => {
+  it('replaces path separators, NUL, and ASCII control chars with underscore', () => {
+    expect(sanitizeFilename('a/b\\c\x00\x07d\r\ne.csv')).toBe('a_b_c__d__e.csv')
   })
 
-  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()
+  it('clamps long filenames to 200 chars', () => {
+    const long = 'x'.repeat(500) + '.csv'
+    const out = sanitizeFilename(long)
+    expect(out.length).toBe(200)
+    expect(out.startsWith('x')).toBe(true)
   })
 
-  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()
+  it('falls back to "download" for empty or whitespace-only input', () => {
+    expect(sanitizeFilename('')).toBe('download')
+    // Whitespace stays — sanitizer only handles control bytes — but a leading
+    // NUL run that empties the string still falls back.
+    expect(sanitizeFilename('\x00\x00\x00')).toBe('___')
   })
+})
 
-  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
+describe('downloadDOMToPNG', () => {
+  it('rasterises the element via html2canvas and resolves with a handle', async () => {
+    const handle = await downloadDOMToPNG({
+      element: document.createElement('div'),
     })
-
-    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',
-      }),
-    )
+    expect(handle.url).toBe('blob:mock')
+    handle.revoke?.()
+    expect(revokeSpy).toHaveBeenCalledWith('blob:mock')
   })
 
-  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)
+  it('rejects when canvas.toBlob returns null', async () => {
+    mockToBlob.mockImplementation((cb: ToBlobCb) => cb(null))
+    await expect(
+      downloadDOMToPNG({ element: document.createElement('div') }),
+    ).rejects.toThrow(/toBlob/)
   })
 
-  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
+  it('forwards pixelRatio and backgroundColor overrides', async () => {
+    // We can't easily inspect the call args without re-hoisting the mock,
+    // so just guard the happy path still works with overrides supplied.
+    const handle = await downloadDOMToPNG({
+      element: document.createElement('div'),
+      pixelRatio: 4,
+      backgroundColor: '#fff',
     })
-
-    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,
-      }),
-    )
+    expect(handle.url).toBe('blob:mock')
   })
+})
 
-  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)
+describe('download icons', () => {
+  it('CSVIcon renders an SVG element', () => {
+    const { container } = render(<CSVIcon fontSize='small' />)
+    expect(container.querySelector('svg')).not.toBeNull()
+  })
 
-    expect(result).toBeTruthy()
-    expect(result).toContain('data:image/png')
+  it('PNGIcon renders an SVG element', () => {
+    const { container } = render(<PNGIcon fontSize='small' />)
+    expect(container.querySelector('svg')).not.toBeNull()
   })
 })

package/src/{widgets-v2 → widgets}/actions/download/exports.ts

@@ -105,7 +105,7 @@ export async function downloadDOMToPNG(
   return new Promise<DownloadHandle>((resolve, reject) => {
     canvas.toBlob((blob) => {
       if (!blob) {
-        reject(new Error('[widgets-v2] toBlob() returned null'))
+        reject(new Error('[widgets] toBlob() returned null'))
         return
       }
       const url = URL.createObjectURL(blob)

package/src/{widgets-v2 → widgets}/actions/download/index.ts

@@ -10,6 +10,7 @@ export {
 export { CSVIcon, PNGIcon, MarkdownIcon } from './icons'
 export { buildPngDownloadItem, type BuildPngDownloadItemArgs } from './png-item'
 export { buildCsvDownloadItem, type BuildCsvDownloadItemArgs } from './csv-item'
+export { withPngItem, type WidgetDownloadArgs } from './widget-download'
 export { DOWNLOAD_ITEM_IDS, type DownloadItemId } from './constants'
 export type { DownloadItem, DownloadContext } from './types'
 export { DEFAULT_DOWNLOAD_LABELS, type DownloadLabels } from './labels'

package/src/{widgets-v2 → widgets}/actions/download/png-item.tsx

@@ -9,7 +9,7 @@ export interface BuildPngDownloadItemArgs {
   /**
    * Reads the capture element to rasterise. Called at click time so the
    * download config doesn't capture a stale reference. Wire it to
-   * `() => getCaptureEl(id)` from `widgets-v2/stores`.
+   * `() => getCaptureEl(id)` from `widgets/stores`.
    */
   getCaptureEl: (ctx: DownloadContext) => HTMLElement | null
   /** html2canvas `scale`. Default 2. */
@@ -36,7 +36,7 @@ export function buildPngDownloadItem(
     resolve: async (ctx) => {
       const el = args.getCaptureEl(ctx)
       if (!el) {
-        throw new Error('[widgets-v2] No PNG capture element available')
+        throw new Error('[widgets] No PNG capture element available')
       }
       const handle = await downloadDOMToPNG({
         element: el,

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

@@ -1,21 +1,46 @@
-import type { JSX, ReactNode } from 'react'
-import type { IconButtonProps } from '@mui/material'
-import type { WidgetState } from '../../stores/types'
+import type { ReactElement } from 'react'
 
-export interface DownloadItem<D = unknown> {
+/**
+ * Passed to {@link DownloadItem.resolve} by `<Widget.Download>`.
+ */
+export interface DownloadContext {
+  /**
+   * Id of the widget store the menu was opened from — the dialog's own
+   * store when opened from `FullScreen.Slot`'s header, so an export matches
+   * what the user is looking at. `null` outside a `<Widget.Provider>`.
+   */
+  id: string | null
+}
+
+export interface DownloadItem {
+  /** Unique key (also used as menu label key). */
   id: string
+  /** Display label in the menu. */
   label: string
-  icon?: JSX.Element
+  /**
+   * Optional leading icon shown next to the label. Pass a rendered element
+   * (e.g. `<DownloadIcon fontSize='small' />`) so consumers can fully
+   * control sizing / colour. Rendered inside an MUI `<ListItemIcon>`.
+   */
+  icon?: ReactElement
+  /**
+   * When `true`, the menu item is rendered but non-clickable (greyed out).
+   * Useful for items whose underlying export is unavailable in the current
+   * widget state (no rows, missing permission, etc.).
+   */
   disabled?: boolean
+  /**
+   * Override for the resolved filename. When set, `resolve()`'s `filename`
+   * is ignored and this value is used instead — handy when the consumer
+   * wants to template the filename with widget metadata without having to
+   * close over it inside `resolve()`.
+   */
   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
+  /**
+   * Resolves to a Blob URL the trigger will click. Optional `revoke` is
+   * called after the click is dispatched.
+   */
+  resolve: (
+    ctx: DownloadContext,
+  ) => Promise<{ url: string; filename: string; revoke?: () => void }>
 }

package/src/widgets/actions/download/widget-download.test.ts

@@ -0,0 +1,30 @@
+import { describe, it, expect, vi } from 'vitest'
+import { buildCsvDownloadItem } from './csv-item'
+import { withPngItem } from './widget-download'
+
+vi.mock('html2canvas', () => ({
+  default: () =>
+    Promise.resolve({
+      toBlob: (cb: (blob: Blob | null) => void) => cb(new Blob(['png'])),
+    }),
+}))
+
+const csv = buildCsvDownloadItem({ filename: 'f', getRows: () => [] })
+
+describe('withPngItem', () => {
+  it('returns the items unchanged without getCaptureEl', () => {
+    expect(withPngItem({ filename: 'f' }, csv)).toEqual([csv])
+  })
+
+  it('puts a PNG item first when getCaptureEl is given, and uses it', async () => {
+    vi.spyOn(URL, 'createObjectURL').mockReturnValue('blob:png')
+    const getCaptureEl = vi.fn(() => document.createElement('div'))
+    const [png, rest] = withPngItem({ filename: 'f', getCaptureEl }, csv)
+    expect(png?.id).toBe('png')
+    expect(rest).toBe(csv)
+    await expect(png!.resolve({ id: 'w' })).resolves.toMatchObject({
+      filename: 'f.png',
+    })
+    expect(getCaptureEl).toHaveBeenCalledWith({ id: 'w' })
+  })
+})

package/src/widgets/actions/download/widget-download.ts

@@ -0,0 +1,41 @@
+import { buildPngDownloadItem } from './png-item'
+import type { DownloadContext, DownloadItem } from './types'
+
+/** Arguments every per-widget `create*DownloadConfig` shares. */
+export interface WidgetDownloadArgs<T> {
+  /** Base filename (without extension). */
+  filename: string
+  /**
+   * Reads the data to export at click time. `ctx.id` is the store the menu
+   * was opened from — the fullscreen dialog's own while it's open. See
+   * `widgetStoreData` in `widgets/stores`.
+   */
+  getData: (ctx: DownloadContext) => T
+  /**
+   * Reads the element the PNG item rasterises. When given, a PNG item is
+   * prepended to the menu. See `widgetCaptureEl` in `widgets/stores`.
+   */
+  getCaptureEl?: (ctx: DownloadContext) => HTMLElement | null
+  /** PNG `pixelRatio` (default 2). */
+  pngPixelRatio?: number
+  /** PNG `backgroundColor` (default transparent). */
+  pngBackgroundColor?: string | null
+}
+
+/**
+ * `items`, with a PNG item in front when `args.getCaptureEl` is given — the
+ * order every widget's download menu uses.
+ */
+export function withPngItem(
+  args: Omit<WidgetDownloadArgs<unknown>, 'getData'>,
+  ...items: DownloadItem[]
+): DownloadItem[] {
+  if (!args.getCaptureEl) return items
+  const png = buildPngDownloadItem({
+    filename: args.filename,
+    getCaptureEl: args.getCaptureEl,
+    pixelRatio: args.pngPixelRatio,
+    backgroundColor: args.pngBackgroundColor,
+  })
+  return [png, ...items]
+}