@carto/ps-react-ui 4.21.1 → 4.23.0

package/src/widgets-v2/category/category-ui.tsx

@@ -96,6 +96,14 @@ export interface CategoryUIProps {
    * No-op for single-series data — same convention as the legend.
    */
   stacked?: boolean
+  /**
+   * Series indices hidden via the legend. Leave both this and
+   * `onHiddenSeriesChange` unset and CategoryUI keeps the set itself; pass
+   * them to own it — `Category` does, so the card and the fullscreen copy
+   * share it through the widget store.
+   */
+  hiddenSeries?: ReadonlySet<number>
+  onHiddenSeriesChange?: (next: ReadonlySet<number>) => void
 }
 
 interface GroupedRow {
@@ -167,6 +175,8 @@ export function CategoryUI({
   maxOverride,
   size = 'small',
   stacked = false,
+  hiddenSeries: hiddenSeriesProp,
+  onHiddenSeriesChange,
 }: CategoryUIProps) {
   const theme = useTheme()
   const fmt = formatter ?? ((n: number) => String(n))
@@ -286,9 +296,10 @@ export function CategoryUI({
   // selection, unrelated). Never allowed to reach "every series hidden":
   // toggling the last visible one instead resets to "all visible" rather
   // than leaving the widget blank.
-  const [hiddenSeries, setHiddenSeries] = useState<ReadonlySet<number>>(
+  const [localHidden, setLocalHidden] = useState<ReadonlySet<number>>(
     () => new Set(),
   )
+  const hiddenSeries = hiddenSeriesProp ?? localHidden
   // A reload with a different series breakdown invalidates hidden indices —
   // index 2 may now point at an entirely different series. Reset rather
   // than keep hiding whatever now occupies a stale index. Adjusted directly
@@ -303,7 +314,7 @@ export function CategoryUI({
   const [prevSeriesKey, setPrevSeriesKey] = useState(seriesKey)
   if (seriesKey !== prevSeriesKey) {
     setPrevSeriesKey(seriesKey)
-    setHiddenSeries(new Set())
+    setLocalHidden(new Set())
   }
   // Real number of data series — NOT `series?.length`, which is legend
   // metadata and may legitimately be shorter than the actual series count
@@ -313,14 +324,14 @@ export function CategoryUI({
   const seriesCount = Math.max(data.length, 1)
   const toggleSeries = useCallback(
     (index: number) => {
-      setHiddenSeries((prev) => {
-        const next = new Set(prev)
-        if (next.has(index)) next.delete(index)
-        else next.add(index)
-        return next.size >= seriesCount ? new Set() : next
-      })
+      const next = new Set(hiddenSeries)
+      if (next.has(index)) next.delete(index)
+      else next.add(index)
+      ;(onHiddenSeriesChange ?? setLocalHidden)(
+        next.size >= seriesCount ? new Set() : next,
+      )
     },
-    [seriesCount],
+    [hiddenSeries, onHiddenSeriesChange, seriesCount],
   )
 
   if (grouped.length === 0) return null

package/src/widgets-v2/category/category.tsx

@@ -1,5 +1,11 @@
-import { useMemo } from 'react'
-import { useWidgetId, useWidgetShallow, type WidgetState } from '../stores'
+import { useCallback, useMemo } from 'react'
+import {
+  getWidgetStore,
+  useWidget,
+  useWidgetId,
+  useWidgetShallow,
+  type WidgetState,
+} from '../stores'
 import { CategoryUI } from './category-ui'
 import type {
   CategoryKey,
@@ -23,6 +29,19 @@ const categorySelector = (s: WidgetState): CategorySlice => ({
   labelFormatter: s.labelFormatter,
 })
 
+/**
+ * Legend-hidden series, kept on the widget store so every mounted Category
+ * of the widget — the card and its fullscreen copy — shows the same set.
+ * Tagged with the series breakdown it was made for: after a reload with
+ * different series the indices point elsewhere, so a stale set reads as
+ * empty instead of being reset with a write.
+ */
+interface CategoryWidgetState extends WidgetState {
+  categoryHiddenSeries?: { key: string; indices: ReadonlySet<number> }
+}
+
+const NO_HIDDEN: ReadonlySet<number> = new Set()
+
 function maxFromCategoryData(d: CategoryWidgetData | undefined): number {
   if (!d) return 0
   let m = 0
@@ -111,6 +130,20 @@ export function Category({
   )
   const effectiveMaxOverride =
     maxOverride ?? (naturalMax > 0 ? naturalMax : undefined)
+
+  const seriesKey = JSON.stringify(series?.map((s) => s.name) ?? [])
+  const stored = useWidget<
+    CategoryWidgetState['categoryHiddenSeries'],
+    CategoryWidgetState
+  >(id, (s) => s.categoryHiddenSeries)
+  const hiddenSeries = stored?.key === seriesKey ? stored.indices : NO_HIDDEN
+  const onHiddenSeriesChange = useCallback(
+    (indices: ReadonlySet<number>) =>
+      getWidgetStore(id).setState({
+        categoryHiddenSeries: { key: seriesKey, indices },
+      } as Partial<CategoryWidgetState>),
+    [id, seriesKey],
+  )
   return (
     <CategoryUI
       data={slice.data}
@@ -125,6 +158,8 @@ export function Category({
       maxOverride={effectiveMaxOverride}
       size={size}
       stacked={stacked}
+      hiddenSeries={hiddenSeries}
+      onHiddenSeriesChange={onHiddenSeriesChange}
     />
   )
 }

package/src/widgets-v2/category/download.test.ts

@@ -60,7 +60,9 @@ describe('createCategoryDownloadConfig', () => {
       filename: 'c',
       getData: () => data,
     })
-    const handle = await items.find((i) => i.id === 'csv')!.resolve()
+    const handle = await items
+      .find((i) => i.id === 'csv')!
+      .resolve({ id: null })
     expect(handle.filename).toBe('c.csv')
     expect(csvText).toBe(
       'series,name,value\nseries_1,a,1\nseries_1,b,2\nseries_2,a,10',
@@ -73,7 +75,7 @@ describe('createCategoryDownloadConfig', () => {
       getData: () => data,
       seriesNames: ['baseline', 'override'],
     })
-    await items.find((i) => i.id === 'csv')!.resolve()
+    await items.find((i) => i.id === 'csv')!.resolve({ id: null })
     expect(csvText.split('\n')[1]).toBe('baseline,a,1')
     expect(csvText.split('\n')[3]).toBe('override,a,10')
   })

package/src/widgets-v2/category/download.ts

@@ -1,6 +1,7 @@
 import {
   buildCsvDownloadItem,
   buildPngDownloadItem,
+  type DownloadContext,
   type DownloadItem,
 } from '../actions/download'
 import type { CategoryWidgetData } from './types'
@@ -13,9 +14,9 @@ import type { CategoryWidgetData } from './types'
  */
 export function createCategoryDownloadConfig(args: {
   filename: string
-  getData: () => CategoryWidgetData
+  getData: (ctx: DownloadContext) => CategoryWidgetData
   seriesNames?: readonly string[]
-  getCaptureEl?: () => HTMLElement | null
+  getCaptureEl?: (ctx: DownloadContext) => HTMLElement | null
   pngPixelRatio?: number
   pngBackgroundColor?: string | null
 }): DownloadItem[] {
@@ -33,8 +34,8 @@ export function createCategoryDownloadConfig(args: {
   items.push(
     buildCsvDownloadItem({
       filename: args.filename,
-      getRows: () => {
-        const data = args.getData()
+      getRows: (ctx) => {
+        const data = args.getData(ctx)
         const rows: unknown[][] = [['series', 'name', 'value']]
         for (const [i, series] of data.entries()) {
           const seriesName = args.seriesNames?.[i] ?? `series_${i + 1}`

package/src/widgets-v2/echart/echart-ui.test.tsx

@@ -103,11 +103,14 @@ describe('<EchartUI>', () => {
       />,
     )
     expect(initSpy).toHaveBeenCalledTimes(1)
-    // 3rd arg merges the default `{ renderer: 'svg', height: 304 }` with the
-    // caller's init — canvas wins.
+    // 3rd arg merges the default `{ renderer: 'svg' }` with the caller's
+    // init — canvas wins.
     const initOpts = initSpy.mock.calls[0]![2] as Record<string, unknown>
     expect(initOpts.renderer).toBe('canvas')
-    expect(initOpts.height).toBe(304)
+    // No `height`: zrender would store it and every later `resize()` would
+    // snap back to it, so the chart could never grow into a fullscreen
+    // dialog. Height is container-driven instead.
+    expect(initOpts.height).toBeUndefined()
     expect(onInstance).toHaveBeenCalledWith(mockChart)
   })
 

package/src/widgets-v2/echart/echart-ui.tsx

@@ -9,9 +9,12 @@ import {
 import { observeResize } from './shared-resize-observer'
 import { styles } from './style'
 
+// No `height`: a numeric height here is stored in zrender's init opts, and
+// every later `resize()` resolves back to it — the chart would stay that tall
+// inside a fullscreen dialog. Height comes from the container instead
+// (`styles.root`'s `min-height` inline, `flex: 1` when the parent has one).
 export const DEFAULT_INIT_OPTS = {
   renderer: 'svg',
-  height: 304,
 } satisfies echarts.EChartsInitOpts
 
 export type EchartsEventHandler = (event: unknown) => void
@@ -36,7 +39,8 @@ export interface EchartUIProps {
   /**
    * Init options forwarded to echarts.init. Captured at mount only — to change
    * `renderer` or `height` after mount, unmount and remount the chart.
-   * Defaults: `{ renderer: 'svg', height: 304 }`.
+   * Defaults: `{ renderer: 'svg' }` — height is container-driven, so prefer
+   * `sx={{ minHeight }}` over pinning `height` here.
    */
   init?: echarts.EChartsInitOpts
   /**

package/src/widgets-v2/echart/echart.test.tsx

@@ -45,7 +45,7 @@ vi.mock('./echart-ui', () => ({
     }, [onInstance])
     return null
   },
-  DEFAULT_INIT_OPTS: { renderer: 'svg', height: 304 },
+  DEFAULT_INIT_OPTS: { renderer: 'svg' },
 }))
 
 beforeEach(() => {

package/src/widgets-v2/echart/echart.tsx

@@ -1,4 +1,5 @@
 import { useCallback, useMemo } from 'react'
+import type { SxProps, Theme } from '@mui/material'
 import type * as echarts from 'echarts'
 import {
   applyTransforms,
@@ -77,6 +78,13 @@ export interface EchartProps {
   onEvents?: Record<string, EchartsEventHandler>
   init?: echarts.EChartsInitOpts
   className?: string
+  /**
+   * Styles for the chart container — this is where its height comes from.
+   * `min-height` defaults to the card height (304px) and `flex: 1` lets the
+   * chart fill a taller parent; override either here, e.g.
+   * `sx={{ minHeight: 400 }}` for a taller card.
+   */
+  sx?: SxProps<Theme>
 }
 
 interface EchartSlice {
@@ -126,6 +134,7 @@ export function Echart({
   onEvents,
   init,
   className,
+  sx,
 }: EchartProps) {
   const id = useWidgetId()
   const slice = useWidgetShallow(id, echartSelector)
@@ -194,6 +203,7 @@ export function Echart({
       init={init}
       onInstance={onInstance}
       className={className}
+      sx={sx}
     />
   )
 }

package/src/widgets-v2/echart/style.ts

@@ -3,6 +3,21 @@ import type { SxProps, Theme } from '@mui/material'
 export const styles = {
   root: {
     width: '100%',
-    minHeight: 0,
+    // `flex: 1` lets the chart fill a parent that has a definite height —
+    // the fullscreen dialog. Inline it has none (Widget.Content is an
+    // auto-height flex column), so flex-basis resolves to the content box,
+    // which is empty until ECharts measures it: at `min-height: 0` the
+    // container is 0px tall, ECharts draws nothing and the widget renders
+    // blank. 304 is not a new magic number — it's the height `init.height`
+    // used to pin, kept so cards look exactly as before. Override per widget
+    // with `<Widget.Echart sx={{ minHeight }} />`.
+    flex: 1,
+    minHeight: 304,
+    // ECharts puts its tooltip inside this box at `z-index: 9999999`. With
+    // no stacking context of its own, that number competes page-wide and
+    // beats MUI's modal layer — under `FullScreen.Slot` the card's chart
+    // mirrors the dialog's tooltip (echarts.connect) and it painted over
+    // the dialog. Isolating keeps the tooltip above its own chart only.
+    isolation: 'isolate',
   },
 } satisfies Record<string, SxProps<Theme>>

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

@@ -56,7 +56,9 @@ describe('createFormulaDownloadConfig', () => {
       filename: 'f',
       getData: () => data,
     })
-    const handle = await items.find((i) => i.id === 'csv')!.resolve()
+    const handle = await items
+      .find((i) => i.id === 'csv')!
+      .resolve({ id: null })
     expect(handle.filename).toBe('f.csv')
     expect(csvText).toBe(
       'series,prefix,value,suffix,note,delta\nRev,$,42,k,q1,12\n,,10,,,',

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

@@ -1,18 +1,19 @@
 import {
   buildCsvDownloadItem,
   buildPngDownloadItem,
+  type DownloadContext,
   type DownloadItem,
 } from '../actions/download'
 import type { FormulaWidgetData } from './types'
 
 export interface FormulaDownloadConfigArgs {
   filename: string
-  getData: () => FormulaWidgetData
+  getData: (ctx: DownloadContext) => FormulaWidgetData
   /**
    * Optional getter for the widget's capture element (registered by
    * `Widget.State`). When provided, a PNG item is prepended.
    */
-  getCaptureEl?: () => HTMLElement | null
+  getCaptureEl?: (ctx: DownloadContext) => HTMLElement | null
   pngPixelRatio?: number
   pngBackgroundColor?: string | null
 }
@@ -40,8 +41,8 @@ export function createFormulaDownloadConfig(
   items.push(
     buildCsvDownloadItem({
       filename: args.filename,
-      getRows: () => {
-        const data = args.getData()
+      getRows: (ctx) => {
+        const data = args.getData(ctx)
         const rows: unknown[][] = [
           ['series', 'prefix', 'value', 'suffix', 'note', 'delta'],
         ]

package/src/widgets-v2/histogram/download.test.ts

@@ -52,7 +52,9 @@ describe('createHistogramDownloadConfig', () => {
       getData: () => data,
       getTicks: () => ticks,
     })
-    const handle = await items.find((i) => i.id === 'csv')!.resolve()
+    const handle = await items
+      .find((i) => i.id === 'csv')!
+      .resolve({ id: null })
     expect(handle.filename).toBe('h.csv')
     expect(csvText).toBe(
       'bin_low,bin_high,series_1,series_2\n0,10,1,4\n10,20,2,5\n20,30,3,6',
@@ -66,7 +68,7 @@ describe('createHistogramDownloadConfig', () => {
       getTicks: () => ticks,
       seriesNames: ['lo', 'hi'],
     })
-    await items.find((i) => i.id === 'csv')!.resolve()
+    await items.find((i) => i.id === 'csv')!.resolve({ id: null })
     expect(csvText.startsWith('bin_low,bin_high,lo,hi')).toBe(true)
   })
 
@@ -76,7 +78,7 @@ describe('createHistogramDownloadConfig', () => {
       getData: () => data,
       getTicks: () => [0],
     })
-    await items.find((i) => i.id === 'csv')!.resolve()
+    await items.find((i) => i.id === 'csv')!.resolve({ id: null })
     expect(csvText).toBe('bin_low,bin_high,series_1,series_2')
   })
 
@@ -87,7 +89,7 @@ describe('createHistogramDownloadConfig', () => {
       getData: () => sparse,
       getTicks: () => ticks,
     })
-    await items.find((i) => i.id === 'csv')!.resolve()
+    await items.find((i) => i.id === 'csv')!.resolve({ id: null })
     expect(csvText).toContain('0,10,1,0')
     expect(csvText).toContain('10,20,2,0')
   })

package/src/widgets-v2/histogram/download.ts

@@ -1,6 +1,7 @@
 import {
   buildCsvDownloadItem,
   buildPngDownloadItem,
+  type DownloadContext,
   type DownloadItem,
 } from '../actions/download'
 import type { HistogramWidgetData } from './types'
@@ -13,10 +14,10 @@ import type { HistogramWidgetData } from './types'
  */
 export function createHistogramDownloadConfig(args: {
   filename: string
-  getData: () => HistogramWidgetData
+  getData: (ctx: DownloadContext) => HistogramWidgetData
   getTicks: () => readonly number[]
   seriesNames?: readonly string[]
-  getCaptureEl?: () => HTMLElement | null
+  getCaptureEl?: (ctx: DownloadContext) => HTMLElement | null
   pngPixelRatio?: number
   pngBackgroundColor?: string | null
 }): DownloadItem[] {
@@ -34,8 +35,8 @@ export function createHistogramDownloadConfig(args: {
   items.push(
     buildCsvDownloadItem({
       filename: args.filename,
-      getRows: () => {
-        const data = args.getData()
+      getRows: (ctx) => {
+        const data = args.getData(ctx)
         const ticks = args.getTicks()
         const seriesCount = data.length
         const header: unknown[] = ['bin_low', 'bin_high']

package/src/widgets-v2/index.ts

@@ -157,6 +157,7 @@ export type {
   RelativeDataProps,
   DownloadProps,
   DownloadItem,
+  DownloadContext,
   FullScreenTriggerProps,
   FullScreenSlotProps,
   LockSelectionProps,

package/src/widgets-v2/markdown/download.test.ts

@@ -46,7 +46,7 @@ describe('createMarkdownDownloadConfig', () => {
       filename: 'doc',
       getData: () => ({ content: '# title\n\nbody' }),
     })
-    const handle = await items.find((i) => i.id === 'md')!.resolve()
+    const handle = await items.find((i) => i.id === 'md')!.resolve({ id: null })
     expect(handle.url).toBe('blob:mock')
     expect(handle.filename).toBe('doc.md')
     expect(mdText).toBe('# title\n\nbody')
@@ -60,7 +60,7 @@ describe('createMarkdownDownloadConfig', () => {
       // missing content field — exercise the `?? ''` branch
       getData: () => ({}) as { content: string },
     })
-    await items.find((i) => i.id === 'md')!.resolve()
+    await items.find((i) => i.id === 'md')!.resolve({ id: null })
     expect(mdText).toBe('')
   })
 })

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

@@ -4,6 +4,7 @@ import {
   buildPngDownloadItem,
   toCsvString,
   triggerLinkDownload,
+  type DownloadContext,
   type DownloadItem,
 } from '../actions/download'
 import type { MarkdownWidgetData } from './types'
@@ -16,8 +17,8 @@ import type { MarkdownWidgetData } from './types'
  */
 export function createMarkdownDownloadConfig(args: {
   filename: string
-  getData: () => MarkdownWidgetData
-  getCaptureEl?: () => HTMLElement | null
+  getData: (ctx: DownloadContext) => MarkdownWidgetData
+  getCaptureEl?: (ctx: DownloadContext) => HTMLElement | null
   pngPixelRatio?: number
   pngBackgroundColor?: string | null
 }): DownloadItem[] {
@@ -36,8 +37,8 @@ export function createMarkdownDownloadConfig(args: {
     id: DOWNLOAD_ITEM_IDS.markdown,
     label: 'Markdown',
     icon: <MarkdownIcon fontSize='small' />,
-    resolve: () => {
-      const data = args.getData()
+    resolve: (ctx) => {
+      const data = args.getData(ctx)
       const blob = new Blob([data.content ?? ''], {
         type: 'text/markdown;charset=utf-8;',
       })

package/src/widgets-v2/pie/download.test.ts

@@ -51,7 +51,9 @@ describe('createPieDownloadConfig', () => {
       getCaptureEl: () => null,
     })
     expect(items.map((i) => i.id)).toEqual(['png', 'csv'])
-    await expect(items[0]!.resolve()).rejects.toThrow(/No PNG capture element/)
+    await expect(items[0]!.resolve({ id: null })).rejects.toThrow(
+      /No PNG capture element/,
+    )
   })
 
   it('CSV resolve uses default series_<n> when seriesNames is absent', async () => {
@@ -59,7 +61,9 @@ describe('createPieDownloadConfig', () => {
       filename: 'p',
       getData: () => multi,
     })
-    const handle = await items.find((i) => i.id === 'csv')!.resolve()
+    const handle = await items
+      .find((i) => i.id === 'csv')!
+      .resolve({ id: null })
     expect(handle.filename).toBe('p.csv')
     expect(csvText).toBe('series,name,value\nseries_1,a,1\nseries_2,c,3')
     handle.revoke?.()
@@ -72,7 +76,7 @@ describe('createPieDownloadConfig', () => {
       getData: () => multi,
       seriesNames: ['alpha', 'beta'],
     })
-    await items.find((i) => i.id === 'csv')!.resolve()
+    await items.find((i) => i.id === 'csv')!.resolve({ id: null })
     expect(csvText).toBe('series,name,value\nalpha,a,1\nbeta,c,3')
   })
 })

package/src/widgets-v2/pie/download.ts

@@ -1,6 +1,7 @@
 import {
   buildCsvDownloadItem,
   buildPngDownloadItem,
+  type DownloadContext,
   type DownloadItem,
 } from '../actions/download'
 import type { PieWidgetData } from './types'
@@ -14,9 +15,9 @@ import type { PieWidgetData } from './types'
  */
 export function createPieDownloadConfig(args: {
   filename: string
-  getData: () => PieWidgetData
+  getData: (ctx: DownloadContext) => PieWidgetData
   seriesNames?: readonly string[]
-  getCaptureEl?: () => HTMLElement | null
+  getCaptureEl?: (ctx: DownloadContext) => HTMLElement | null
   pngPixelRatio?: number
   pngBackgroundColor?: string | null
 }): DownloadItem[] {
@@ -34,8 +35,8 @@ export function createPieDownloadConfig(args: {
   items.push(
     buildCsvDownloadItem({
       filename: args.filename,
-      getRows: () => {
-        const data = args.getData()
+      getRows: (ctx) => {
+        const data = args.getData(ctx)
         const rows: unknown[][] = [['series', 'name', 'value']]
         for (const [i, series] of data.entries()) {
           const seriesName = args.seriesNames?.[i] ?? `series_${i + 1}`

package/src/widgets-v2/pie/options.test.ts

@@ -84,6 +84,14 @@ describe('pieOptions (structural)', () => {
     expect(out.legend?.show).toBe(true)
   })
 
+  it('anchors the legend bottom-left, like every other widget', () => {
+    const out = pieOptions({ theme }) as {
+      legend?: { left?: unknown; bottom?: unknown }
+    }
+    expect(out.legend?.left).toBe(0)
+    expect(out.legend?.bottom).toBe(0)
+  })
+
   it('disables legend click-to-toggle', () => {
     const out = pieOptions({ theme }) as {
       legend?: { selectedMode?: boolean }

package/src/widgets-v2/pie/options.ts

@@ -45,14 +45,9 @@ export function pieOptions({
   return {
     legend: {
       ...buildLegendConfig({ hasLegend: true, labelFormatter }),
-      // Pie reads better with a centered legend (the donut is radially
-      // symmetric — left-aligning the legend below it visually unbalances
-      // the chart). Override `buildLegendConfig`'s `type: 'scroll'` with
-      // `'plain'` so long category lists wrap to multiple rows instead
-      // of clipping the last visible item against the chart container.
-      // The wider `itemGap` gives chips breathing room in the typical
-      // 3–6 category case.
-      left: 'center',
+      // Bottom-left, same as every other widget — `buildLegendConfig`'s
+      // `left: 0` is kept deliberately. The wider `itemGap` gives chips
+      // breathing room in the typical 3–6 category case.
       type: 'scroll',
       itemGap: 16,
       // The legend is presentational only here — the pie has its own

package/src/widgets-v2/scatterplot/download.test.ts

@@ -52,7 +52,9 @@ describe('createScatterplotDownloadConfig', () => {
       filename: 's',
       getData: () => data,
     })
-    const handle = await items.find((i) => i.id === 'csv')!.resolve()
+    const handle = await items
+      .find((i) => i.id === 'csv')!
+      .resolve({ id: null })
     expect(handle.filename).toBe('s.csv')
     expect(csvText).toBe(
       'series,x,y\nseries_1,1,10\nseries_1,2,20\nseries_2,3,30',
@@ -65,7 +67,7 @@ describe('createScatterplotDownloadConfig', () => {
       getData: () => data,
       seriesNames: ['A', 'B'],
     })
-    await items.find((i) => i.id === 'csv')!.resolve()
+    await items.find((i) => i.id === 'csv')!.resolve({ id: null })
     expect(csvText.split('\n')[1]).toBe('A,1,10')
   })
 })

package/src/widgets-v2/scatterplot/download.ts

@@ -1,6 +1,7 @@
 import {
   buildCsvDownloadItem,
   buildPngDownloadItem,
+  type DownloadContext,
   type DownloadItem,
 } from '../actions/download'
 import type { ScatterplotWidgetData } from './types'
@@ -13,9 +14,9 @@ import type { ScatterplotWidgetData } from './types'
  */
 export function createScatterplotDownloadConfig(args: {
   filename: string
-  getData: () => ScatterplotWidgetData
+  getData: (ctx: DownloadContext) => ScatterplotWidgetData
   seriesNames?: readonly string[]
-  getCaptureEl?: () => HTMLElement | null
+  getCaptureEl?: (ctx: DownloadContext) => HTMLElement | null
   pngPixelRatio?: number
   pngBackgroundColor?: string | null
 }): DownloadItem[] {
@@ -33,8 +34,8 @@ export function createScatterplotDownloadConfig(args: {
   items.push(
     buildCsvDownloadItem({
       filename: args.filename,
-      getRows: () => {
-        const data = args.getData()
+      getRows: (ctx) => {
+        const data = args.getData(ctx)
         const rows: unknown[][] = [['series', 'x', 'y']]
         for (const [i, series] of data.entries()) {
           const seriesName = args.seriesNames?.[i] ?? `series_${i + 1}`

package/src/widgets-v2/spread/download.test.ts

@@ -55,7 +55,9 @@ describe('createSpreadDownloadConfig', () => {
       filename: 's',
       getData: () => data,
     })
-    const handle = await items.find((i) => i.id === 'csv')!.resolve()
+    const handle = await items
+      .find((i) => i.id === 'csv')!
+      .resolve({ id: null })
     expect(handle.filename).toBe('s.csv')
     expect(csvText).toBe(
       'series,prefix,min,max,suffix,note\nRevenue,$,1,9,k,q1\n,,0,10,,',

package/src/widgets-v2/spread/download.ts

@@ -1,6 +1,7 @@
 import {
   buildCsvDownloadItem,
   buildPngDownloadItem,
+  type DownloadContext,
   type DownloadItem,
 } from '../actions/download'
 import type { SpreadWidgetData } from './types'
@@ -13,8 +14,8 @@ import type { SpreadWidgetData } from './types'
  */
 export function createSpreadDownloadConfig(args: {
   filename: string
-  getData: () => SpreadWidgetData
-  getCaptureEl?: () => HTMLElement | null
+  getData: (ctx: DownloadContext) => SpreadWidgetData
+  getCaptureEl?: (ctx: DownloadContext) => HTMLElement | null
   pngPixelRatio?: number
   pngBackgroundColor?: string | null
 }): DownloadItem[] {
@@ -32,8 +33,8 @@ export function createSpreadDownloadConfig(args: {
   items.push(
     buildCsvDownloadItem({
       filename: args.filename,
-      getRows: () => {
-        const data = args.getData()
+      getRows: (ctx) => {
+        const data = args.getData(ctx)
         const rows: unknown[][] = [
           ['series', 'prefix', 'min', 'max', 'suffix', 'note'],
         ]