@carto/ps-react-ui 4.7.0 → 4.8.0

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

@@ -0,0 +1,144 @@
+import { useCallback, useState, type ComponentType } from 'react'
+import {
+  CircularProgress,
+  IconButton,
+  ListItemIcon,
+  ListItemText,
+  Menu,
+  MenuItem,
+  type SvgIconProps,
+} from '@mui/material'
+import DownloadIcon from '@mui/icons-material/FileDownload'
+import { Tooltip } from '../../../components'
+import { triggerLinkDownload } from './exports'
+import type { DownloadItem } from './types'
+import { DEFAULT_DOWNLOAD_LABELS, type DownloadLabels } from './labels'
+
+export interface DownloadProps {
+  items: readonly DownloadItem[]
+  labels?: Partial<DownloadLabels>
+  icon?: ComponentType<SvgIconProps>
+  iconProps?: SvgIconProps
+  /**
+   * Fires when an item's `resolve()` rejects (or any step in the click-through
+   * path throws). The error is normalised to a real `Error` first. Surface
+   * to your telemetry / toast layer here; the trigger already shows a visual
+   * error indicator independently.
+   */
+  onError?: (err: Error) => void
+}
+
+export function Download({
+  items,
+  labels,
+  icon: Icon = DownloadIcon,
+  iconProps,
+  onError,
+}: DownloadProps) {
+  const _labels = { ...DEFAULT_DOWNLOAD_LABELS, ...labels }
+  const [anchorEl, setAnchorEl] = useState<HTMLElement | null>(null)
+  const [isDownloading, setIsDownloading] = useState(false)
+  const [error, setError] = useState<Error | null>(null)
+
+  const open = useCallback((e: React.MouseEvent<HTMLButtonElement>) => {
+    // Clear any prior error when the user re-engages the menu — the next
+    // attempt is a fresh interaction, not a continuation of the failed one.
+    setError(null)
+    setAnchorEl(e.currentTarget)
+  }, [])
+  const close = useCallback(() => setAnchorEl(null), [])
+
+  const onSelect = useCallback(
+    (item: DownloadItem) => {
+      // Single-flight: ignore re-entry while a download is already in flight.
+      // The trigger is `disabled` and the menu is closed during that window,
+      // so this guard mostly defends against future call sites that bypass
+      // the menu (e.g. keyboard shortcuts).
+      if (item.disabled || isDownloading) return
+      close()
+      setIsDownloading(true)
+      setError(null)
+      item
+        .resolve()
+        .then(({ url, filename, revoke }) => {
+          // `item.filename` overrides what `resolve()` returns — lets consumers
+          // template the filename with widget metadata declaratively.
+          triggerLinkDownload({ url, filename: item.filename ?? filename })
+          // Defer revoke past the current task so Safari / Firefox-on-slow-disk
+          // can dispatch the download before the blob URL is invalidated.
+          // Synchronous revoke here can silently cancel the download.
+          if (revoke) setTimeout(revoke, 0)
+        })
+        .catch((err: unknown) => {
+          const e = err instanceof Error ? err : new Error(String(err))
+          setError(e)
+          onError?.(e)
+        })
+        .finally(() => {
+          setIsDownloading(false)
+        })
+    },
+    [close, isDownloading, onError],
+  )
+
+  const triggerLabel = isDownloading
+    ? _labels.loading
+    : error
+      ? _labels.error
+      : _labels.trigger
+  const triggerActive = Boolean(anchorEl) || isDownloading
+
+  return (
+    <>
+      <Tooltip title={triggerLabel}>
+        <IconButton
+          size='small'
+          aria-label={triggerLabel}
+          aria-haspopup='true'
+          aria-expanded={anchorEl ? 'true' : undefined}
+          aria-busy={isDownloading || undefined}
+          data-error={error ? 'true' : undefined}
+          disabled={isDownloading || items.length === 0}
+          onClick={open}
+          className={triggerActive ? 'active' : undefined}
+        >
+          {isDownloading ? (
+            <CircularProgress size={18} color='inherit' />
+          ) : (
+            <Icon fontSize='small' {...iconProps} />
+          )}
+        </IconButton>
+      </Tooltip>
+      <Menu
+        anchorEl={anchorEl}
+        open={Boolean(anchorEl)}
+        onClose={close}
+        variant='menu'
+        elevation={8}
+        anchorOrigin={{
+          vertical: 'bottom',
+          horizontal: 'right',
+        }}
+        transformOrigin={{
+          vertical: 'top',
+          horizontal: 'right',
+        }}
+      >
+        {items.map((item) => (
+          <MenuItem
+            key={item.id}
+            disabled={item.disabled}
+            onClick={() => void onSelect(item)}
+          >
+            {item.icon && (
+              <ListItemIcon sx={{ color: 'text.primary' }}>
+                {item.icon}
+              </ListItemIcon>
+            )}
+            <ListItemText>{item.label}</ListItemText>
+          </MenuItem>
+        ))}
+      </Menu>
+    </>
+  )
+}

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

@@ -0,0 +1,198 @@
+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'])))
+
+vi.mock('html2canvas', () => ({
+  default: () => Promise.resolve({ toBlob: mockToBlob }),
+}))
+
+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)
+      }
+    },
+  )
+})
+
+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')
+  })
+
+  it('emits blank cells for null and undefined', () => {
+    expect(toCsvString([[null, undefined, 'x']])).toBe(',,x')
+  })
+
+  it('stringifies numbers and booleans', () => {
+    expect(toCsvString([[1, false, true]])).toBe('1,false,true')
+  })
+
+  it('JSON.stringifies objects and arrays', () => {
+    expect(toCsvString([[{ a: 1 }, [1, 2]]])).toBe('"{""a"":1}","[1,2]"')
+  })
+
+  it('quotes cells containing comma / quote / newline', () => {
+    expect(toCsvString([['a,b', 'he said "hi"', 'line1\nline2']])).toBe(
+      '"a,b","he said ""hi""","line1\nline2"',
+    )
+  })
+
+  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)
+      },
+    )
+
+    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')
+    })
+  })
+})
+
+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('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')
+  })
+})
+
+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')
+  })
+
+  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)
+  })
+
+  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('___')
+  })
+})
+
+describe('downloadDOMToPNG', () => {
+  it('rasterises the element via html2canvas and resolves with a handle', async () => {
+    const handle = await downloadDOMToPNG({
+      element: document.createElement('div'),
+    })
+    expect(handle.url).toBe('blob:mock')
+    handle.revoke?.()
+    expect(revokeSpy).toHaveBeenCalledWith('blob:mock')
+  })
+
+  it('rejects when canvas.toBlob returns null', async () => {
+    mockToBlob.mockImplementation((cb: ToBlobCb) => cb(null))
+    await expect(
+      downloadDOMToPNG({ element: document.createElement('div') }),
+    ).rejects.toThrow(/toBlob/)
+  })
+
+  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',
+    })
+    expect(handle.url).toBe('blob:mock')
+  })
+})
+
+describe('download icons', () => {
+  it('CSVIcon renders an SVG element', () => {
+    const { container } = render(<CSVIcon fontSize='small' />)
+    expect(container.querySelector('svg')).not.toBeNull()
+  })
+
+  it('PNGIcon renders an SVG element', () => {
+    const { container } = render(<PNGIcon fontSize='small' />)
+    expect(container.querySelector('svg')).not.toBeNull()
+  })
+})

package/src/widgets-v2/actions/download/exports.ts

@@ -0,0 +1,115 @@
+/**
+ * Pure download helpers — no React, no DOM lifecycle outside the link click.
+ * Component layer in {@link ./download.tsx} orchestrates these.
+ */
+
+import html2canvas from 'html2canvas'
+
+export interface DownloadHandle {
+  url: string
+  revoke: () => void
+}
+
+// Leading characters that Excel / Sheets / Numbers interpret as a formula
+// when the CSV is opened. Prefixing the cell with a single quote forces the
+// spreadsheet app to render it as plain text. Tab and CR are included
+// because some tooling strips leading whitespace before formula evaluation.
+const CSV_FORMULA_PREFIX = /^[=+\-@\t\r]/
+
+export function toCsvString(rows: readonly (readonly unknown[])[]): string {
+  const escape = (cell: unknown): string => {
+    if (cell == null) return ''
+    let value =
+      typeof cell === 'string'
+        ? cell
+        : typeof cell === 'number' || typeof cell === 'boolean'
+          ? String(cell)
+          : JSON.stringify(cell)
+    if (CSV_FORMULA_PREFIX.test(value)) value = `'${value}`
+    if (/[",\n\r]/.test(value)) return `"${value.replace(/"/g, '""')}"`
+    return value
+  }
+  return rows.map((row) => row.map(escape).join(',')).join('\n')
+}
+
+export function downloadToCSV(
+  rows: readonly (readonly unknown[])[],
+): DownloadHandle {
+  const csv = toCsvString(rows)
+  const blob = new Blob([csv], { type: 'text/csv;charset=utf-8;' })
+  const url = URL.createObjectURL(blob)
+  return { url, revoke: () => URL.revokeObjectURL(url) }
+}
+
+// Path separators, NUL, and ASCII control chars. Filenames containing these
+// can confuse the browser download stack and historically enabled
+// Content-Disposition-style trickery.
+// eslint-disable-next-line no-control-regex
+const UNSAFE_FILENAME_CHARS = /[\\/\x00-\x1f\x7f]/g
+const MAX_FILENAME_LENGTH = 200
+
+export function sanitizeFilename(name: string): string {
+  return (
+    (name ?? '')
+      .replace(UNSAFE_FILENAME_CHARS, '_')
+      .slice(0, MAX_FILENAME_LENGTH) || 'download'
+  )
+}
+
+/**
+ * Triggers a browser download for the given URL by synthesizing an anchor,
+ * clicking it, and removing it. Pure DOM — no React. The filename is run
+ * through {@link sanitizeFilename} before being assigned to `a.download`.
+ */
+export function triggerLinkDownload(args: {
+  url: string
+  filename: string
+}): void {
+  const { url, filename } = args
+  const a = document.createElement('a')
+  a.href = url
+  a.download = sanitizeFilename(filename)
+  a.style.display = 'none'
+  document.body.appendChild(a)
+  a.click()
+  a.remove()
+}
+
+export interface DownloadDOMToPNGOptions {
+  element: HTMLElement
+  /** html2canvas `scale`. Default 2 — crisp on hi-DPI displays. */
+  pixelRatio?: number
+  /**
+   * html2canvas `backgroundColor`. Default `null` (transparent) so the PNG
+   * inherits whatever surface it lands on when the user pastes it.
+   */
+  backgroundColor?: string | null
+}
+
+/**
+ * Rasterise an HTMLElement to PNG via `html2canvas` and wrap the result in
+ * a `DownloadHandle`. The caller is responsible for calling `handle.revoke`
+ * after the link click is dispatched. Used by per-widget download configs
+ * to power the PNG menu item.
+ */
+export async function downloadDOMToPNG(
+  opts: DownloadDOMToPNGOptions,
+): Promise<DownloadHandle> {
+  const { element, pixelRatio = 2, backgroundColor = null } = opts
+  const canvas = await html2canvas(element, {
+    scale: pixelRatio,
+    backgroundColor,
+    useCORS: true,
+    logging: false,
+  })
+  return new Promise<DownloadHandle>((resolve, reject) => {
+    canvas.toBlob((blob) => {
+      if (!blob) {
+        reject(new Error('[widgets-v2] toBlob() returned null'))
+        return
+      }
+      const url = URL.createObjectURL(blob)
+      resolve({ url, revoke: () => URL.revokeObjectURL(url) })
+    }, 'image/png')
+  })
+}

package/src/widgets-v2/actions/download/icons.tsx

@@ -0,0 +1,26 @@
+import { SvgIcon, type SvgIconProps } from '@mui/material'
+import ImageOutlined from '@mui/icons-material/ImageOutlined'
+
+/**
+ * Generic "image" glyph used for the PNG download item. Wraps MUI's
+ * `ImageOutlined` so callers can swap it via the per-widget download
+ * config's `icon` override without pulling MUI directly.
+ */
+export function PNGIcon(props: SvgIconProps) {
+  return <ImageOutlined {...props} />
+}
+
+/**
+ * "CSV" rectangle with the letters spelled inside — matches v1 visual and is
+ * easier to recognise in a download menu than a generic table glyph.
+ */
+export function CSVIcon(props: SvgIconProps) {
+  return (
+    <SvgIcon viewBox='0 0 18 18' {...props}>
+      <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'
+      />
+    </SvgIcon>
+  )
+}

package/src/widgets-v2/actions/download/index.ts

@@ -0,0 +1,13 @@
+export { Download, type DownloadProps } from './download'
+export {
+  downloadToCSV,
+  downloadDOMToPNG,
+  toCsvString,
+  triggerLinkDownload,
+  type DownloadHandle,
+  type DownloadDOMToPNGOptions,
+} from './exports'
+export { CSVIcon, PNGIcon } from './icons'
+export { buildPngDownloadItem, type BuildPngDownloadItemArgs } from './png-item'
+export type { DownloadItem } from './types'
+export { DEFAULT_DOWNLOAD_LABELS, type DownloadLabels } from './labels'

package/src/widgets-v2/actions/download/labels.ts

@@ -0,0 +1,16 @@
+export interface DownloadLabels {
+  trigger: string
+  /** Tooltip / aria-label shown on the trigger while a download is in flight. */
+  loading: string
+  /**
+   * Tooltip / aria-label shown on the trigger after a download failed. Cleared
+   * the next time the menu opens.
+   */
+  error: string
+}
+
+export const DEFAULT_DOWNLOAD_LABELS: DownloadLabels = {
+  trigger: 'Download',
+  loading: 'Downloading…',
+  error: 'Download failed',
+}

package/src/widgets-v2/actions/download/png-item.test.tsx

@@ -0,0 +1,72 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { buildPngDownloadItem } from './png-item'
+
+type ToBlobCb = (blob: Blob | null) => void
+const mockToBlob = vi.fn((cb: ToBlobCb) => cb(new Blob(['png-bytes'])))
+
+vi.mock('html2canvas', () => ({
+  default: () => Promise.resolve({ toBlob: mockToBlob }),
+}))
+
+let revokeSpy: ReturnType<typeof vi.spyOn>
+
+beforeEach(() => {
+  mockToBlob.mockReset()
+  mockToBlob.mockImplementation((cb: ToBlobCb) => cb(new Blob(['png-bytes'])))
+  vi.spyOn(URL, 'createObjectURL').mockReturnValue('blob:png')
+  revokeSpy = vi
+    .spyOn(URL, 'revokeObjectURL')
+    .mockImplementation(() => undefined)
+})
+
+describe('buildPngDownloadItem', () => {
+  it('returns an item with the canonical PNG shape (id, label, icon)', () => {
+    const item = buildPngDownloadItem({
+      filename: 'demo',
+      getCaptureEl: () => document.createElement('div'),
+    })
+    expect(item.id).toBe('png')
+    expect(item.label).toBe('PNG')
+    expect(item.icon).toBeTruthy()
+  })
+
+  it('honours a label override', () => {
+    const item = buildPngDownloadItem({
+      filename: 'demo',
+      getCaptureEl: () => document.createElement('div'),
+      label: 'Export image',
+    })
+    expect(item.label).toBe('Export image')
+  })
+
+  it('resolve() rasterises the capture element and returns a handle with .png filename', async () => {
+    const item = buildPngDownloadItem({
+      filename: 'sales',
+      getCaptureEl: () => document.createElement('div'),
+    })
+    const handle = await item.resolve()
+    expect(handle.url).toBe('blob:png')
+    expect(handle.filename).toBe('sales.png')
+    handle.revoke?.()
+    expect(revokeSpy).toHaveBeenCalledWith('blob:png')
+  })
+
+  it('resolve() rejects when getCaptureEl returns null', async () => {
+    const item = buildPngDownloadItem({
+      filename: 'demo',
+      getCaptureEl: () => null,
+    })
+    await expect(item.resolve()).rejects.toThrow(/No PNG capture element/)
+  })
+
+  it('forwards pixelRatio and backgroundColor overrides', async () => {
+    const item = buildPngDownloadItem({
+      filename: 'sales',
+      getCaptureEl: () => document.createElement('div'),
+      pixelRatio: 4,
+      backgroundColor: '#fff',
+    })
+    const handle = await item.resolve()
+    expect(handle.filename).toBe('sales.png')
+  })
+})

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

@@ -0,0 +1,52 @@
+import { downloadDOMToPNG } from './exports'
+import { PNGIcon } from './icons'
+import type { DownloadItem } from './types'
+
+export interface BuildPngDownloadItemArgs {
+  /** Base filename (without extension). The item appends `.png`. */
+  filename: string
+  /**
+   * 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: () => HTMLElement | null
+  /** html2canvas `scale`. Default 2. */
+  pixelRatio?: number
+  /** html2canvas `backgroundColor`. Default transparent (`null`). */
+  backgroundColor?: string | null
+  /** Override the menu label. Default `'PNG'`. */
+  label?: string
+}
+
+/**
+ * Builds the standard PNG `DownloadItem` used by every per-widget download
+ * config. Centralised so the menu label, icon, error message, and filename
+ * suffix stay consistent across widgets without each `create*DownloadConfig`
+ * re-deriving the same shape.
+ */
+export function buildPngDownloadItem(
+  args: BuildPngDownloadItemArgs,
+): DownloadItem {
+  return {
+    id: 'png',
+    label: args.label ?? 'PNG',
+    icon: <PNGIcon fontSize='small' />,
+    resolve: async () => {
+      const el = args.getCaptureEl()
+      if (!el) {
+        throw new Error('[widgets-v2] No PNG capture element available')
+      }
+      const handle = await downloadDOMToPNG({
+        element: el,
+        pixelRatio: args.pixelRatio,
+        backgroundColor: args.backgroundColor,
+      })
+      return {
+        url: handle.url,
+        filename: `${args.filename}.png`,
+        revoke: handle.revoke,
+      }
+    },
+  }
+}

package/src/widgets-v2/actions/download/style.ts

@@ -0,0 +1,3 @@
+import type { SxProps, Theme } from '@mui/material'
+
+export const styles = {} satisfies Record<string, SxProps<Theme>>

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

@@ -0,0 +1,32 @@
+import type { ReactElement } from 'react'
+
+export interface DownloadItem {
+  /** Unique key (also used as menu label key). */
+  id: string
+  /** Display label in the menu. */
+  label: string
+  /**
+   * 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
+  /**
+   * Resolves to a Blob URL the trigger will click. Optional `revoke` is
+   * called after the click is dispatched.
+   */
+  resolve: () => Promise<{ url: string; filename: string; revoke?: () => void }>
+}