@carto/ps-react-ui 4.7.1 → 4.9.0

package/src/widgets-v2/actions/zoom-toggle/transforms.test.ts

@@ -0,0 +1,148 @@
+import { describe, it, expect } from 'vitest'
+import { createTheme, type Theme } from '@mui/material'
+import { addZoom, createAddZoom, ZOOM_LAYOUT } from './transforms'
+
+const theme = createTheme() as unknown as Theme
+
+describe('addZoom', () => {
+  it('appends an inside + slider dataZoom pair to the option', () => {
+    const out = addZoom({ xAxis: { type: 'value' } }) as {
+      xAxis: { type: string }
+      dataZoom: { type: string }[]
+    }
+    expect(out.xAxis).toEqual({ type: 'value' })
+    expect(out.dataZoom).toHaveLength(2)
+    expect(out.dataZoom[0]?.type).toBe('inside')
+    expect(out.dataZoom[1]?.type).toBe('slider')
+  })
+
+  it('replaces an existing dataZoom array (no append/stack across runs)', () => {
+    const seeded = { dataZoom: [{ type: 'inside' }, { type: 'inside' }] }
+    const out = addZoom(seeded) as { dataZoom: { type: string }[] }
+    expect(out.dataZoom).toHaveLength(2)
+    expect(out.dataZoom.map((z) => z.type)).toEqual(['inside', 'slider'])
+  })
+
+  it('omits start/end so ECharts preserves the user-dragged range across re-runs', () => {
+    const out = addZoom({}) as {
+      dataZoom: { start?: number; end?: number }[]
+    }
+    for (const dz of out.dataZoom) {
+      expect(dz.start).toBeUndefined()
+      expect(dz.end).toBeUndefined()
+    }
+  })
+
+  it('returns the input unchanged when not an object', () => {
+    expect(addZoom(null)).toBe(null)
+    expect(addZoom(undefined)).toBe(undefined)
+    expect(addZoom('not an object')).toBe('not an object')
+  })
+})
+
+describe('createAddZoom (theme-bound, v1-styled slider)', () => {
+  it('produces an inside zoom + a styled slider with the v1 chrome', () => {
+    const transform = createAddZoom(theme)
+    const out = transform({}) as {
+      dataZoom: {
+        type: string
+        height?: number
+        handleIcon?: string
+        fillerColor?: string
+        borderColor?: string
+        dataBackground?: { areaStyle?: { color?: string } }
+        textStyle?: { fontSize?: number }
+      }[]
+    }
+    expect(out.dataZoom).toHaveLength(2)
+    expect(out.dataZoom[0]?.type).toBe('inside')
+    const slider = out.dataZoom[1]!
+    expect(slider.type).toBe('slider')
+    // v1 hallmarks the new slider must carry.
+    expect(slider.height).toBe(ZOOM_LAYOUT.sliderHeight)
+    expect(slider.handleIcon).toMatch(/^image:\/\/data:image\/svg\+xml/)
+    expect(slider.fillerColor).toBeTruthy()
+    expect(slider.borderColor).toBeTruthy()
+    expect(slider.textStyle?.fontSize).toBeGreaterThan(0)
+  })
+
+  it('omits start/end so the dragged range survives re-runs', () => {
+    const transform = createAddZoom(theme)
+    const out = transform({}) as {
+      dataZoom: { start?: number; end?: number }[]
+    }
+    for (const dz of out.dataZoom) {
+      expect(dz.start).toBeUndefined()
+      expect(dz.end).toBeUndefined()
+    }
+  })
+
+  it('returns non-object input unchanged', () => {
+    const transform = createAddZoom(theme)
+    expect(transform(null)).toBe(null)
+    expect(transform(undefined)).toBe(undefined)
+  })
+
+  it('defaults to x-axis only (matches bar/histogram/timeseries semantics)', () => {
+    const transform = createAddZoom(theme)
+    const out = transform({}) as {
+      dataZoom: { type: string; xAxisIndex?: unknown; yAxisIndex?: unknown }[]
+    }
+    expect(out.dataZoom).toHaveLength(2)
+    for (const dz of out.dataZoom) {
+      expect(dz.xAxisIndex).toEqual([0])
+      expect(dz.yAxisIndex).toBeUndefined()
+    }
+  })
+
+  it('emits inside + slider per axis when axes=["x","y"] (2D zoom for scatter)', () => {
+    const transform = createAddZoom(theme, { axes: ['x', 'y'] })
+    const out = transform({}) as {
+      dataZoom: {
+        type: string
+        xAxisIndex?: unknown
+        yAxisIndex?: unknown
+        width?: number
+        right?: number
+        height?: number
+        bottom?: number
+      }[]
+    }
+    expect(out.dataZoom).toHaveLength(4)
+    const insides = out.dataZoom.filter((dz) => dz.type === 'inside')
+    const sliders = out.dataZoom.filter((dz) => dz.type === 'slider')
+    expect(insides).toHaveLength(2)
+    expect(sliders).toHaveLength(2)
+    // One inside per axis.
+    expect(insides.some((dz) => dz.xAxisIndex !== undefined)).toBe(true)
+    expect(insides.some((dz) => dz.yAxisIndex !== undefined)).toBe(true)
+    // X-slider: horizontal at the bottom (has height + bottom).
+    const xSlider = sliders.find((dz) => dz.xAxisIndex !== undefined)
+    expect(xSlider?.height).toBe(ZOOM_LAYOUT.sliderHeight)
+    expect(xSlider?.bottom).toBeDefined()
+    // Y-slider: vertical on the right (has width + right, no handleIcon).
+    const ySlider = sliders.find((dz) => dz.yAxisIndex !== undefined)
+    expect(ySlider?.width).toBe(ZOOM_LAYOUT.sliderHeight)
+    expect(ySlider?.right).toBeDefined()
+  })
+
+  it('emits y-only when axes=["y"]', () => {
+    const transform = createAddZoom(theme, { axes: ['y'] })
+    const out = transform({}) as {
+      dataZoom: { type: string; xAxisIndex?: unknown; yAxisIndex?: unknown }[]
+    }
+    expect(out.dataZoom).toHaveLength(2)
+    for (const dz of out.dataZoom) {
+      expect(dz.yAxisIndex).toEqual([0])
+      expect(dz.xAxisIndex).toBeUndefined()
+    }
+  })
+})
+
+describe('ZOOM_LAYOUT', () => {
+  it('exposes the layout constants used by data-fusion mergers', () => {
+    expect(ZOOM_LAYOUT.sliderHeight).toBe(32)
+    expect(ZOOM_LAYOUT.sliderGap).toBe(8)
+    expect(ZOOM_LAYOUT.sliderBottomWithLegend).toBe(28)
+  })
+})

package/src/widgets-v2/actions/zoom-toggle/transforms.ts

@@ -0,0 +1,171 @@
+import type { Theme } from '@mui/material'
+
+/**
+ * v1's slider handle — 9×36 SVG with a white pill body, secondary-colored
+ * stroke, and three grip lines. Inlined as a data URL so the chart can
+ * render it without a network fetch.
+ */
+const SLIDER_HANDLE_ICON =
+  'image://data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iOSIgaGVpZ2h0PSIzNiIgdmlld0JveD0iMCAwIDkgMzYiIGZpbGw9Im5vbmUiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyI+CjxyZWN0IHg9IjAuNSIgeT0iLTAuNSIgd2lkdGg9IjgiIGhlaWdodD0iMTgiIHJ4PSI0IiB0cmFuc2Zvcm09Im1hdHJpeCgxIDAgMCAtMSAwIDI3KSIgZmlsbD0id2hpdGUiIHN0cm9rZT0iIzM1OEJFNyIvPgo8cmVjdCB3aWR0aD0iMyIgaGVpZ2h0PSIyIiByeD0iMSIgdHJhbnNmb3JtPSJtYXRyaXgoMSAwIDAgLTEgMyAyMykiIGZpbGw9IiMzNThCRTciLz4KPHJlY3Qgd2lkdGg9IjMiIGhlaWdodD0iMiIgcng9IjEiIHRyYW5zZm9ybT0ibWF0cml4KDEgMCAwIC0xIDMgMTkpIiBmaWxsPSIjMzU4QkU3Ii8+CjxyZWN0IHdpZHRoPSIzIiBoZWlnaHQ9IjIiIHJ4PSIxIiB0cmFuc2Zvcm09Im1hdHJpeCgxIDAgMCAtMSAzIDE1KSIgZmlsbD0iIzM1OEJFNyIvPgo8L3N2Zz4='
+
+const SLIDER_HEIGHT = 32
+const SLIDER_BOTTOM = 0
+
+/** Which chart axis (or axes) zoom applies to. */
+export type ZoomAxis = 'x' | 'y'
+
+export interface CreateAddZoomOptions {
+  /**
+   * Axes to enable zoom on. Default `['x']` (matches bar / histogram /
+   * timeseries — horizontal pan/zoom on the category axis). Pass
+   * `['x', 'y']` for a scatterplot-style 2D zoom (mouse-wheel scales both
+   * axes; a horizontal slider sits at the bottom for x-range and a
+   * vertical slider sits on the right for y-range).
+   */
+  axes?: readonly ZoomAxis[]
+}
+
+/**
+ * Theme-bound zoom config transform: adds one inside `dataZoom`
+ * (mouse-wheel + drag) per axis plus a styled slider per axis with the
+ * v1 chrome (blue-tinted filler, secondary-color data preview, white
+ * pill handles, CARTO typography). The x-slider is horizontal at the
+ * bottom; the y-slider is vertical on the right.
+ *
+ * Returned function has stable identity for a given theme + axes
+ * combination; pair with `useMemo` at the call site.
+ *
+ * **No `start` / `end`** are emitted: ECharts defaults to `0–100` on the
+ * first `setOption` and then keeps the runtime slider state across
+ * subsequent merges (no `replaceMerge` for `dataZoom`). Re-running the
+ * transform on data/formatter/RelativeData updates therefore preserves the
+ * user's dragged range instead of snapping it back.
+ */
+export function createAddZoom(
+  theme: Theme,
+  options: CreateAddZoomOptions = {},
+): (option: unknown) => unknown {
+  const axes = options.axes ?? ['x']
+  const includeX = axes.includes('x')
+  const includeY = axes.includes('y')
+  const sliderStyles = getZoomSliderStyles(theme)
+  const baseSliderProps = {
+    throttle: 0,
+    showDetail: false,
+    brushSelect: false,
+    moveHandleSize: 8,
+    handleSize: '100%',
+    ...sliderStyles,
+  }
+  return (option: unknown): unknown => {
+    if (option == null || typeof option !== 'object') return option
+    const cfg = option as Record<string, unknown>
+    const dataZoom: object[] = []
+    if (includeX) {
+      dataZoom.push({ type: 'inside', xAxisIndex: [0], throttle: 0 })
+    }
+    if (includeY) {
+      dataZoom.push({ type: 'inside', yAxisIndex: [0], throttle: 0 })
+    }
+    if (includeX) {
+      dataZoom.push({
+        type: 'slider',
+        xAxisIndex: [0],
+        height: SLIDER_HEIGHT,
+        bottom: SLIDER_BOTTOM,
+        handleIcon: SLIDER_HANDLE_ICON,
+        ...baseSliderProps,
+      })
+    }
+    if (includeY) {
+      // Vertical slider — `width` is its thickness, `right` pins it to
+      // the right edge. We omit `handleIcon` so ECharts renders its
+      // default vertical handle (the inline SVG is shaped for a
+      // horizontal slider and looks wrong when rotated).
+      dataZoom.push({
+        type: 'slider',
+        yAxisIndex: [0],
+        width: SLIDER_HEIGHT,
+        right: SLIDER_BOTTOM,
+        ...baseSliderProps,
+      })
+    }
+    return { ...cfg, dataZoom }
+  }
+}
+
+/**
+ * Back-compat untyped transform — produces the bare `dataZoom` config from
+ * the original v2 implementation. Use {@link createAddZoom} when a theme is
+ * available so the slider matches the v1 styling.
+ *
+ * `start` / `end` are intentionally omitted so ECharts preserves the user's
+ * runtime range across subsequent `setOption` merges (see {@link createAddZoom}).
+ */
+export const addZoom = (option: unknown): unknown => {
+  if (option == null || typeof option !== 'object') return option
+  const cfg = option as Record<string, unknown>
+  return {
+    ...cfg,
+    dataZoom: [
+      { type: 'inside' },
+      {
+        type: 'slider',
+        height: SLIDER_HEIGHT,
+        bottom: SLIDER_BOTTOM,
+      },
+    ],
+  }
+}
+
+/** Style block matching v1's `getEChartZoomSliderStyles`. */
+function getZoomSliderStyles(theme: Theme) {
+  const secondary = theme.palette.secondary?.main ?? '#358BE7'
+  return {
+    fillerColor: 'rgba(53, 139, 231, 0.25)',
+    borderColor: 'rgba(53, 139, 231, 0.3)',
+    borderWidth: 0.5,
+    backgroundColor: 'transparent',
+    borderRadius: 4,
+    dataBackground: {
+      lineStyle: { opacity: 0 },
+      areaStyle: { opacity: 1, color: secondary },
+    },
+    selectedDataBackground: {
+      lineStyle: { opacity: 0 },
+      areaStyle: { opacity: 1, color: secondary },
+    },
+    handleStyle: {
+      color: theme.palette.common?.white ?? '#fff',
+      borderColor: 'rgba(3, 111, 226, 0.08)',
+      borderWidth: 1,
+      shadowBlur: 3,
+      shadowColor: 'rgba(0, 0, 0, 0.1)',
+      shadowOffsetX: 0,
+      shadowOffsetY: 1,
+    },
+    textStyle: {
+      color: theme.palette.black?.[60] ?? theme.palette.text?.primary,
+      fontSize: parseInt(
+        (theme.typography.overlineDelicate?.fontSize as string | undefined) ??
+          '11',
+      ),
+      fontFamily:
+        theme.typography.overlineDelicate?.fontFamily ??
+        theme.typography.caption?.fontFamily,
+    },
+  }
+}
+
+/**
+ * Visual layout constants used by the data-fusion mergers (bar, histogram,
+ * timeseries) when laying out the slider against the legend / grid.
+ */
+export const ZOOM_LAYOUT = {
+  /** Slider height in px (matches `createAddZoom` output). */
+  sliderHeight: SLIDER_HEIGHT,
+  /** Vertical gap between chart grid and the slider. */
+  sliderGap: 8,
+  /** Slider `bottom` when a legend is shown — sits above the legend row. */
+  sliderBottomWithLegend: 28,
+} as const

package/src/widgets-v2/actions/zoom-toggle/zoom-toggle.test.tsx

@@ -0,0 +1,107 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+import { fireEvent, render, screen } from '@testing-library/react'
+import type { ECharts } from 'echarts'
+import { ZoomToggle } from './zoom-toggle'
+import { Provider } from '../../provider/widget-provider'
+import {
+  applyTransforms,
+  clearAllWidgetStores,
+  getWidgetStore,
+  setEchartInstance,
+} from '../../stores'
+
+beforeEach(() => clearAllWidgetStores())
+afterEach(() => clearAllWidgetStores())
+
+describe('<ZoomToggle>', () => {
+  it('starts disabled by default', () => {
+    render(
+      <Provider id='zt-1' data={[]}>
+        <ZoomToggle />
+      </Provider>,
+    )
+    const trigger = screen.getByLabelText('Enable zoom')
+    expect(trigger.getAttribute('aria-pressed')).toBe('false')
+  })
+
+  it('respects initialEnabled=true', () => {
+    render(
+      <Provider id='zt-2' data={[]}>
+        <ZoomToggle initialEnabled />
+      </Provider>,
+    )
+    expect(screen.getByLabelText('Disable zoom')).toBeTruthy()
+  })
+
+  it('clicking enables the transform — dataZoom appears in the post-pipeline option', () => {
+    render(
+      <Provider id='zt-3' data={[1]}>
+        <ZoomToggle />
+      </Provider>,
+    )
+    fireEvent.click(screen.getByLabelText('Enable zoom'))
+    // configTransforms now apply inside <Widget.Echart>; replay the
+    // pipeline locally over a blank structural option.
+    const configTransforms = getWidgetStore('zt-3').getState().configTransforms
+    const opts = applyTransforms({}, configTransforms) as {
+      dataZoom?: { type: string }[]
+    }
+    expect(opts.dataZoom).toBeTruthy()
+    expect(opts.dataZoom).toHaveLength(2)
+    expect(opts.dataZoom?.[0]?.type).toBe('inside')
+    expect(opts.dataZoom?.[1]?.type).toBe('slider')
+  })
+
+  it('clicking to disable issues a one-shot setOption({}, replaceMerge: ["dataZoom"]) on the live instance', () => {
+    const setOption = vi.fn()
+    const chart = { setOption } as unknown as ECharts
+    render(
+      <Provider id='zt-4' data={[1]}>
+        <ZoomToggle initialEnabled />
+      </Provider>,
+    )
+    setEchartInstance('zt-4', chart)
+    fireEvent.click(screen.getByLabelText('Disable zoom'))
+    expect(setOption).toHaveBeenCalledTimes(1)
+    expect(setOption).toHaveBeenCalledWith({}, { replaceMerge: ['dataZoom'] })
+  })
+
+  it('clicking to enable does NOT touch the live instance (no cleanup needed)', () => {
+    const setOption = vi.fn()
+    const chart = { setOption } as unknown as ECharts
+    render(
+      <Provider id='zt-5' data={[1]}>
+        <ZoomToggle />
+      </Provider>,
+    )
+    setEchartInstance('zt-5', chart)
+    fireEvent.click(screen.getByLabelText('Enable zoom'))
+    expect(setOption).not.toHaveBeenCalled()
+  })
+
+  it('rehydrates enabled state from transformStates on remount', () => {
+    const { unmount } = render(
+      <Provider id='zt-6' data={[1]} keepAlive>
+        <ZoomToggle />
+      </Provider>,
+    )
+    fireEvent.click(screen.getByLabelText('Enable zoom'))
+    unmount()
+    render(
+      <Provider id='zt-6' data={[1]} keepAlive>
+        <ZoomToggle />
+      </Provider>,
+    )
+    // Re-mounted with keepAlive — enabled survived.
+    expect(screen.getByLabelText('Disable zoom')).toBeTruthy()
+  })
+
+  it('honors custom labels', () => {
+    render(
+      <Provider id='zt-7' data={[]}>
+        <ZoomToggle labels={{ off: 'Pan & zoom', on: 'Stop pan & zoom' }} />
+      </Provider>,
+    )
+    expect(screen.getByLabelText('Pan & zoom')).toBeTruthy()
+  })
+})

package/src/widgets-v2/actions/zoom-toggle/zoom-toggle.tsx

@@ -0,0 +1,106 @@
+import { useCallback, useMemo, type ComponentType } from 'react'
+import { IconButton, useTheme, type SvgIconProps } from '@mui/material'
+import ZoomInIcon from '@mui/icons-material/ZoomIn'
+import { Tooltip } from '../../../components'
+import {
+  getEchartInstance,
+  useSingleTransform,
+  useWidgetId,
+} from '../../stores'
+import { createAddZoom, type ZoomAxis } from './transforms'
+import { DEFAULT_ZOOM_TOGGLE_LABELS, type ZoomToggleLabels } from './labels'
+import { styles } from './style'
+
+const ZOOM_DESCRIPTOR = {
+  id: 'zoom-toggle',
+  type: 'config' as const,
+  order: 20,
+}
+
+export interface ZoomToggleProps {
+  initialEnabled?: boolean
+  labels?: Partial<ZoomToggleLabels>
+  icon?: ComponentType<SvgIconProps>
+  iconProps?: SvgIconProps
+  /**
+   * Which axes the zoom controls. Default `['x']` — matches bar /
+   * histogram / timeseries (horizontal pan on the category axis). Pass
+   * `['x', 'y']` for 2D zoom on a scatterplot-style chart (mouse-wheel
+   * scales both axes; horizontal slider at bottom + vertical slider on
+   * the right).
+   */
+  axes?: readonly ZoomAxis[]
+}
+
+/**
+ * Toggle a `dataZoom` slider + wheel-zoom on the chart. The transform is
+ * theme-bound so the slider gets v1's CARTO chrome (blue-tinted filler,
+ * secondary-color preview, white pill handles).
+ *
+ * `dataZoom` is intentionally NOT in `replaceMergeKeys` — ECharts merges
+ * subsequent `setOption` calls so the user's dragged range survives
+ * unrelated re-renders (data updates, formatter swaps, RelativeData toggles).
+ *
+ * On disable the transform is unregistered, but ECharts' merge semantics
+ * would otherwise *keep* the live `dataZoom` component visible. To remove
+ * the slider immediately we issue a one-shot
+ * `setOption({}, { replaceMerge: ['dataZoom'] })` against the live chart
+ * instance via {@link getEchartInstance} — this bypasses the pipeline so
+ * unrelated transforms aren't disturbed.
+ */
+export function ZoomToggle({
+  initialEnabled = false,
+  labels,
+  icon: Icon = ZoomInIcon,
+  iconProps,
+  axes,
+}: ZoomToggleProps) {
+  const id = useWidgetId()
+  const theme = useTheme()
+  const _labels = { ...DEFAULT_ZOOM_TOGGLE_LABELS, ...labels }
+  // Reduce `axes` to two structural booleans before memoizing so the memo
+  // depends on stable primitive values, not an array reference (callers
+  // typically pass an inline `axes={['x', 'y']}` literal that changes
+  // identity each render). Default — no `axes` prop — is x-axis only,
+  // matching `createAddZoom`'s default.
+  const includeX = axes ? axes.includes('x') : true
+  const includeY = axes ? axes.includes('y') : false
+  const transform = useMemo(() => {
+    const resolved: ZoomAxis[] = []
+    if (includeX) resolved.push('x')
+    if (includeY) resolved.push('y')
+    return createAddZoom(theme, { axes: resolved })
+  }, [theme, includeX, includeY])
+  const { enabled, toggle } = useSingleTransform(
+    id,
+    ZOOM_DESCRIPTOR,
+    transform,
+    { initialEnabled },
+  )
+
+  const handleToggle = useCallback(() => {
+    if (enabled) {
+      // About to disable — clear the dataZoom component on the live
+      // instance so the slider disappears immediately.
+      getEchartInstance(id)?.setOption({}, { replaceMerge: ['dataZoom'] })
+    }
+    toggle()
+  }, [enabled, toggle, id])
+
+  const tooltip = enabled ? _labels.on : _labels.off
+
+  return (
+    <Tooltip title={tooltip}>
+      <IconButton
+        size='small'
+        aria-label={tooltip}
+        aria-pressed={enabled}
+        onClick={handleToggle}
+        className={enabled ? 'active' : undefined}
+        sx={{ ...styles.toggle, ...(enabled && styles.toggleActive) }}
+      >
+        <Icon fontSize='small' {...iconProps} />
+      </IconButton>
+    </Tooltip>
+  )
+}

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

@@ -0,0 +1,91 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { createBarDownloadConfig } from './download'
+import type { BarWidgetData } from './types'
+
+const sample: BarWidgetData = [[{ name: 'a', value: 1 }]]
+const multi: BarWidgetData = [
+  [
+    { name: 'a', value: 1 },
+    { name: 'b', value: 2 },
+  ],
+  [{ name: 'c', value: 3 }],
+]
+
+let revokeSpy: ReturnType<typeof vi.spyOn>
+
+beforeEach(() => {
+  // jsdom/happy-dom often miss URL.* — stub deterministically.
+  vi.spyOn(URL, 'createObjectURL').mockReturnValue('blob:mock')
+  revokeSpy = vi
+    .spyOn(URL, 'revokeObjectURL')
+    .mockImplementation(() => undefined)
+})
+
+describe('createBarDownloadConfig', () => {
+  it('returns CSV-only items when getCaptureEl is not provided', () => {
+    const items = createBarDownloadConfig({
+      filename: 'demo',
+      getData: () => sample,
+    })
+    expect(items.map((i) => i.id)).toEqual(['csv'])
+  })
+
+  it('prepends a PNG item when getCaptureEl is provided', () => {
+    const items = createBarDownloadConfig({
+      filename: 'demo',
+      getData: () => sample,
+      getCaptureEl: () => document.createElement('div'),
+    })
+    expect(items.map((i) => i.id)).toEqual(['png', 'csv'])
+    const pngItem = items[0]
+    expect(pngItem?.label).toBe('PNG')
+    expect(pngItem?.icon).toBeTruthy()
+  })
+
+  it('the PNG item rejects when the captureEl getter returns null', async () => {
+    const items = createBarDownloadConfig({
+      filename: 'demo',
+      getData: () => sample,
+      getCaptureEl: () => null,
+    })
+    const png = items.find((i) => i.id === 'png')
+    expect(png).toBeTruthy()
+    await expect(png!.resolve()).rejects.toThrow(/No PNG capture element/)
+  })
+
+  it('CSV resolve returns a download handle with the filename + revoke fn (single series)', async () => {
+    const items = createBarDownloadConfig({
+      filename: 'sales',
+      getData: () => sample,
+    })
+    const csv = items.find((i) => i.id === 'csv')!
+    const handle = await csv.resolve()
+    expect(handle.url).toBe('blob:mock')
+    expect(handle.filename).toBe('sales.csv')
+    expect(typeof handle.revoke).toBe('function')
+    handle.revoke?.()
+    expect(revokeSpy).toHaveBeenCalledWith('blob:mock')
+  })
+
+  it('CSV resolve emits empty-row separators between multiple series', async () => {
+    let csvText = ''
+    // Intercept the Blob payload so we can assert on the serialised CSV.
+    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)
+        }
+      },
+    )
+    const items = createBarDownloadConfig({
+      filename: 'multi',
+      getData: () => multi,
+    })
+    await items.find((i) => i.id === 'csv')!.resolve()
+    expect(csvText).toBe('name,value\na,1\nb,2\n\nname,value\nc,3')
+    vi.unstubAllGlobals()
+  })
+})

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

@@ -0,0 +1,66 @@
+import {
+  CSVIcon,
+  buildPngDownloadItem,
+  downloadToCSV,
+  type DownloadItem,
+} from '../actions/download'
+import type { BarWidgetData } from './types'
+
+export interface BarDownloadConfigArgs {
+  filename: string
+  getData: () => BarWidgetData
+  /**
+   * Optional getter for the widget's capture element (registered by
+   * `Widget.State` on its success path). When provided, a PNG item is
+   * prepended to the returned list. Wire it to
+   * `() => getCaptureEl(id)`.
+   */
+  getCaptureEl?: () => HTMLElement | null
+  /** PNG `pixelRatio` (default 2). */
+  pngPixelRatio?: number
+  /** PNG `backgroundColor` (default transparent). */
+  pngBackgroundColor?: string | null
+}
+
+/**
+ * Builds download items for the Bar widget. Always includes a CSV item
+ * with one `name,value` block per series, separated by an empty row when
+ * there are multiple. When `getCaptureEl` is supplied, also prepends a PNG
+ * item that rasterises the captured element via `html2canvas`.
+ */
+export function createBarDownloadConfig(
+  args: BarDownloadConfigArgs,
+): DownloadItem[] {
+  const items: DownloadItem[] = []
+  if (args.getCaptureEl) {
+    items.push(
+      buildPngDownloadItem({
+        filename: args.filename,
+        getCaptureEl: args.getCaptureEl,
+        pixelRatio: args.pngPixelRatio,
+        backgroundColor: args.pngBackgroundColor,
+      }),
+    )
+  }
+  items.push({
+    id: 'csv',
+    label: 'CSV',
+    icon: <CSVIcon fontSize='small' />,
+    resolve: () => {
+      const data = args.getData()
+      const rows: unknown[][] = []
+      for (const [i, series] of data.entries()) {
+        if (i > 0) rows.push([])
+        rows.push(['name', 'value'])
+        for (const d of series) rows.push([d.name, d.value])
+      }
+      const handle = downloadToCSV(rows)
+      return Promise.resolve({
+        url: handle.url,
+        filename: `${args.filename}.csv`,
+        revoke: handle.revoke,
+      })
+    },
+  })
+  return items
+}