@carto/ps-react-ui 5.1.0 → 6.0.0

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

@@ -1,327 +0,0 @@
-import { describe, it, expect, vi } from 'vitest'
-import { fireEvent, render, screen, waitFor } from '@testing-library/react'
-import { Download } from './download'
-import type { DownloadItem } from './types'
-import * as exports from './exports'
-
-function fakeItem(overrides?: Partial<DownloadItem>): DownloadItem {
-  return {
-    id: 'csv',
-    label: 'Download as CSV',
-    resolve: () =>
-      Promise.resolve({
-        url: 'blob:fake',
-        filename: 'data.csv',
-        revoke: vi.fn(),
-      }),
-    ...overrides,
-  }
-}
-
-describe('<Download>', () => {
-  it('renders a trigger and lists every item when opened', () => {
-    render(
-      <Download
-        items={[
-          fakeItem({ id: 'csv', label: 'Download CSV' }),
-          fakeItem({ id: 'png', label: 'Download PNG' }),
-        ]}
-      />,
-    )
-    fireEvent.click(screen.getByRole('button', { name: 'Download' }))
-    expect(screen.getByText('Download CSV')).toBeTruthy()
-    expect(screen.getByText('Download PNG')).toBeTruthy()
-  })
-
-  it('honors custom trigger label', () => {
-    render(
-      <Download items={[fakeItem()]} labels={{ trigger: 'Save to disk' }} />,
-    )
-    expect(screen.getByRole('button', { name: 'Save to disk' })).toBeTruthy()
-  })
-
-  it('selecting an item calls its resolve(); the menu then closes', async () => {
-    const resolve = vi.fn(() =>
-      Promise.resolve({
-        url: 'blob:abc',
-        filename: 'x.csv',
-        revoke: vi.fn(),
-      }),
-    )
-    render(<Download items={[fakeItem({ resolve })]} />)
-    fireEvent.click(screen.getByRole('button', { name: 'Download' }))
-    fireEvent.click(screen.getByText('Download as CSV'))
-    expect(resolve).toHaveBeenCalledTimes(1)
-    // Wait a tick for the resolve promise to settle.
-    await Promise.resolve()
-  })
-
-  it('renders a custom icon component when provided', () => {
-    function CustomIcon(props: React.SVGProps<SVGSVGElement>) {
-      return <svg data-testid='custom-dl-icon' {...props} />
-    }
-    render(<Download items={[fakeItem()]} icon={CustomIcon} />)
-    expect(screen.getByTestId('custom-dl-icon')).toBeTruthy()
-  })
-
-  it('renders a per-item leading icon inside ListItemIcon', () => {
-    render(
-      <Download
-        items={[
-          fakeItem({
-            icon: <svg data-testid='item-icon' />,
-          }),
-        ]}
-      />,
-    )
-    fireEvent.click(screen.getByRole('button', { name: 'Download' }))
-    const icon = screen.getByTestId('item-icon')
-    expect(icon.closest('.MuiListItemIcon-root')).not.toBeNull()
-  })
-
-  it('disables the menu item when the item is `disabled` and skips resolve()', () => {
-    const resolve = vi.fn(() =>
-      Promise.resolve({ url: 'blob:abc', filename: 'x.csv' }),
-    )
-    render(
-      <Download
-        items={[fakeItem({ id: 'csv', label: 'CSV', disabled: true, resolve })]}
-      />,
-    )
-    fireEvent.click(screen.getByRole('button', { name: 'Download' }))
-    const menuItem = screen.getByText('CSV').closest('li')
-    expect(menuItem?.getAttribute('aria-disabled')).toBe('true')
-    fireEvent.click(screen.getByText('CSV'))
-    expect(resolve).not.toHaveBeenCalled()
-  })
-
-  it('overrides the resolved filename when `item.filename` is set', async () => {
-    const trigger = vi
-      .spyOn(exports, 'triggerLinkDownload')
-      .mockImplementation(() => undefined)
-    try {
-      render(
-        <Download
-          items={[
-            fakeItem({
-              id: 'csv',
-              label: 'CSV',
-              filename: 'override.csv',
-              resolve: () =>
-                Promise.resolve({ url: 'blob:fake', filename: 'auto.csv' }),
-            }),
-          ]}
-        />,
-      )
-      fireEvent.click(screen.getByRole('button', { name: 'Download' }))
-      fireEvent.click(screen.getByText('CSV'))
-      // wait for the resolve() promise to settle
-      await Promise.resolve()
-      await Promise.resolve()
-      expect(trigger).toHaveBeenCalledWith({
-        url: 'blob:fake',
-        filename: 'override.csv',
-      })
-    } finally {
-      trigger.mockRestore()
-    }
-  })
-
-  it('uses the resolved filename when `item.filename` is not set', async () => {
-    const trigger = vi
-      .spyOn(exports, 'triggerLinkDownload')
-      .mockImplementation(() => undefined)
-    try {
-      render(
-        <Download
-          items={[
-            fakeItem({
-              id: 'csv',
-              label: 'CSV',
-              resolve: () =>
-                Promise.resolve({ url: 'blob:fake', filename: 'auto.csv' }),
-            }),
-          ]}
-        />,
-      )
-      fireEvent.click(screen.getByRole('button', { name: 'Download' }))
-      fireEvent.click(screen.getByText('CSV'))
-      await Promise.resolve()
-      await Promise.resolve()
-      expect(trigger).toHaveBeenCalledWith({
-        url: 'blob:fake',
-        filename: 'auto.csv',
-      })
-    } finally {
-      trigger.mockRestore()
-    }
-  })
-
-  it('shows a spinner and disables the trigger while resolve() is pending; clears once it settles', async () => {
-    const trigger = vi
-      .spyOn(exports, 'triggerLinkDownload')
-      .mockImplementation(() => undefined)
-    let releaseResolve: (v: {
-      url: string
-      filename: string
-      revoke?: () => void
-    }) => void = () => undefined
-    const pending = new Promise<{
-      url: string
-      filename: string
-      revoke?: () => void
-    }>((res) => {
-      releaseResolve = res
-    })
-    try {
-      render(
-        <Download
-          items={[
-            fakeItem({ id: 'csv', label: 'CSV', resolve: () => pending }),
-          ]}
-        />,
-      )
-      const triggerBtn = screen.getByRole('button', { name: 'Download' })
-      fireEvent.click(triggerBtn)
-      fireEvent.click(screen.getByText('CSV'))
-
-      // In flight: trigger label and aria-busy switch, button is disabled,
-      // wrapper hover-fade `.active` className is applied, spinner is shown.
-      const busyBtn = screen.getByRole('button', { name: 'Downloading…' })
-      expect(busyBtn.getAttribute('aria-busy')).toBe('true')
-      expect((busyBtn as HTMLButtonElement).disabled).toBe(true)
-      expect(busyBtn.className).toMatch(/\bactive\b/)
-      expect(busyBtn.querySelector('[role="progressbar"]')).not.toBeNull()
-
-      // Settle the resolve and wait for the trigger to flip back to idle.
-      releaseResolve({ url: 'blob:fake', filename: 'data.csv' })
-      const idleBtn = await screen.findByRole('button', { name: 'Download' })
-      expect(idleBtn.getAttribute('aria-busy')).toBeNull()
-      expect((idleBtn as HTMLButtonElement).disabled).toBe(false)
-      expect(idleBtn.querySelector('[role="progressbar"]')).toBeNull()
-    } finally {
-      trigger.mockRestore()
-    }
-  })
-
-  it('clears the spinner when resolve() rejects and fires onError', async () => {
-    const onError = vi.fn()
-    render(
-      <Download
-        onError={onError}
-        items={[
-          fakeItem({
-            id: 'csv',
-            label: 'CSV',
-            resolve: () => Promise.reject(new Error('boom')),
-          }),
-        ]}
-      />,
-    )
-    fireEvent.click(screen.getByRole('button', { name: 'Download' }))
-    fireEvent.click(screen.getByText('CSV'))
-    // After the rejection the trigger label flips to the error label and
-    // `data-error` is set; the spinner is cleared and the button is enabled.
-    const errBtn = await screen.findByRole('button', {
-      name: 'Download failed',
-    })
-    expect((errBtn as HTMLButtonElement).disabled).toBe(false)
-    expect(errBtn.querySelector('[role="progressbar"]')).toBeNull()
-    expect(errBtn.getAttribute('data-error')).toBe('true')
-    await waitFor(() => expect(onError).toHaveBeenCalledTimes(1))
-    const first = onError.mock.calls[0]?.[0] as Error | undefined
-    expect(first).toBeInstanceOf(Error)
-    expect(first?.message).toBe('boom')
-  })
-
-  it('normalises non-Error rejections into a real Error before onError', async () => {
-    const onError = vi.fn()
-    render(
-      <Download
-        onError={onError}
-        items={[
-          fakeItem({
-            id: 'csv',
-            label: 'CSV',
-            // eslint-disable-next-line @typescript-eslint/prefer-promise-reject-errors
-            resolve: () => Promise.reject('non-error-value'),
-          }),
-        ]}
-      />,
-    )
-    fireEvent.click(screen.getByRole('button', { name: 'Download' }))
-    fireEvent.click(screen.getByText('CSV'))
-    await screen.findByRole('button', { name: 'Download failed' })
-    const first = onError.mock.calls[0]?.[0] as Error | undefined
-    expect(first).toBeInstanceOf(Error)
-    expect(first?.message).toBe('non-error-value')
-  })
-
-  it('clears the error state when the menu is re-opened', async () => {
-    render(
-      <Download
-        items={[
-          fakeItem({
-            id: 'csv',
-            label: 'CSV',
-            resolve: () => Promise.reject(new Error('boom')),
-          }),
-        ]}
-      />,
-    )
-    fireEvent.click(screen.getByRole('button', { name: 'Download' }))
-    fireEvent.click(screen.getByText('CSV'))
-    const errBtn = await screen.findByRole('button', {
-      name: 'Download failed',
-    })
-    fireEvent.click(errBtn)
-    // After re-open the trigger flips back to the idle label and data-error
-    // is gone. The menu is now open so we look up the trigger by its
-    // aria-haspopup attribute rather than its role+name (other body nodes
-    // get aria-hidden while the menu is open).
-    await waitFor(() => {
-      const btn = document.querySelector('button[aria-haspopup="true"]')
-      expect(btn).not.toBeNull()
-      expect(btn?.getAttribute('data-error')).toBeNull()
-      expect(btn?.getAttribute('aria-label')).toBe('Download')
-    })
-  })
-
-  it('defers revoke past the current task so the browser can dispatch the download', async () => {
-    const trigger = vi
-      .spyOn(exports, 'triggerLinkDownload')
-      .mockImplementation(() => undefined)
-    const setTimeoutSpy = vi.spyOn(window, 'setTimeout')
-    const revoke = vi.fn()
-    try {
-      render(
-        <Download
-          items={[
-            fakeItem({
-              id: 'csv',
-              label: 'CSV',
-              resolve: () =>
-                Promise.resolve({
-                  url: 'blob:abc',
-                  filename: 'data.csv',
-                  revoke,
-                }),
-            }),
-          ]}
-        />,
-      )
-      fireEvent.click(screen.getByRole('button', { name: 'Download' }))
-      fireEvent.click(screen.getByText('CSV'))
-      // Trigger fires inside the resolve callback; revoke is scheduled via
-      // setTimeout(_, 0) rather than invoked inline. Wait until the trigger
-      // call has happened — at that point revoke must be scheduled, not run.
-      await waitFor(() => expect(trigger).toHaveBeenCalledTimes(1))
-      expect(setTimeoutSpy).toHaveBeenCalledWith(revoke, 0)
-      // After the queued timeout drains, revoke actually runs.
-      await waitFor(() => expect(revoke).toHaveBeenCalledTimes(1))
-    } finally {
-      trigger.mockRestore()
-      setTimeoutSpy.mockRestore()
-    }
-  })
-})

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

@@ -1,144 +0,0 @@
-import { useCallback, useState, type ComponentType } from 'react'
-import {
-  CircularProgress,
-  IconButton,
-  ListItemIcon,
-  ListItemText,
-  Menu,
-  MenuItem,
-  type SvgIconProps,
-} from '@mui/material'
-import { FileDownload as DownloadIcon } from '@mui/icons-material'
-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

@@ -1,198 +0,0 @@
-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/types.ts

@@ -1,32 +0,0 @@
-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 }>
-}