@carto/ps-react-ui 4.22.0 → 4.24.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/style.ts

@@ -13,5 +13,11 @@ export const styles = {
     // 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/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'],
         ]

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

@@ -56,7 +56,9 @@ describe('createTableDownloadConfig', () => {
       getData: () => data,
       columns,
     })
-    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('t.csv')
     expect(csvText).toBe('Name,Score\nAlpha,10\nBeta,20')
   })
@@ -67,7 +69,7 @@ describe('createTableDownloadConfig', () => {
       getData: () => [{ id: 1, name: '=HYPERLINK("x")', score: 1 }],
       columns,
     })
-    await items.find((i) => i.id === 'csv')!.resolve()
+    await items.find((i) => i.id === 'csv')!.resolve({ id: null })
     expect(csvText).toBe('Name,Score\n"\'=HYPERLINK(""x"")",1')
   })
 
@@ -79,7 +81,7 @@ describe('createTableDownloadConfig', () => {
       columns,
     })
     snapshot = [{ id: 9, name: 'Gamma', score: 99 }]
-    await items.find((i) => i.id === 'csv')!.resolve()
+    await items.find((i) => i.id === 'csv')!.resolve({ id: null })
     expect(csvText).toBe('Name,Score\nGamma,99')
   })
 })

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

@@ -1,6 +1,7 @@
 import {
   buildCsvDownloadItem,
   buildPngDownloadItem,
+  type DownloadContext,
   type DownloadItem,
 } from '../actions/download'
 import { tableDataToCsv } from './helpers'
@@ -16,9 +17,9 @@ import type { TableColumn, TableWidgetData } from './types'
  */
 export function createTableDownloadConfig(opts: {
   filename: string
-  getData: () => TableWidgetData
+  getData: (ctx: DownloadContext) => TableWidgetData
   columns: readonly TableColumn[]
-  getCaptureEl?: () => HTMLElement | null
+  getCaptureEl?: (ctx: DownloadContext) => HTMLElement | null
   pngPixelRatio?: number
   pngBackgroundColor?: string | null
 }): DownloadItem[] {
@@ -36,7 +37,7 @@ export function createTableDownloadConfig(opts: {
   items.push(
     buildCsvDownloadItem({
       filename: opts.filename,
-      getCsv: () => tableDataToCsv(opts.getData(), opts.columns),
+      getCsv: (ctx) => tableDataToCsv(opts.getData(ctx), opts.columns),
     }),
   )
   return items

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

@@ -53,7 +53,9 @@ describe('createTimeseriesDownloadConfig', () => {
       filename: 't',
       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('t.csv')
     expect(csvText).toBe(
       'time,series_1,series_2\n' +
@@ -69,7 +71,7 @@ describe('createTimeseriesDownloadConfig', () => {
       filename: 't',
       getData: () => data,
     })
-    await items.find((i) => i.id === 'csv')!.resolve()
+    await items.find((i) => i.id === 'csv')!.resolve({ id: null })
     expect(csvText).toContain('2024-01-01T00:00:00.000Z,7')
   })
 
@@ -79,7 +81,7 @@ describe('createTimeseriesDownloadConfig', () => {
       filename: 't',
       getData: () => data,
     })
-    await items.find((i) => i.id === 'csv')!.resolve()
+    await items.find((i) => i.id === 'csv')!.resolve({ id: null })
     expect(csvText).toContain('2024-Q1,1')
   })
 
@@ -89,7 +91,7 @@ describe('createTimeseriesDownloadConfig', () => {
       getData: () => [[{ name: '2024', value: 1 }]],
       seriesNames: ['revenue'],
     })
-    await items.find((i) => i.id === 'csv')!.resolve()
+    await items.find((i) => i.id === 'csv')!.resolve({ id: null })
     expect(csvText.split('\n')[0]).toBe('time,revenue')
   })
 })

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

@@ -1,6 +1,7 @@
 import {
   buildCsvDownloadItem,
   buildPngDownloadItem,
+  type DownloadContext,
   type DownloadItem,
 } from '../actions/download'
 import type { TimeseriesWidgetData } from './types'
@@ -14,9 +15,9 @@ import type { TimeseriesWidgetData } from './types'
  */
 export function createTimeseriesDownloadConfig(args: {
   filename: string
-  getData: () => TimeseriesWidgetData
+  getData: (ctx: DownloadContext) => TimeseriesWidgetData
   seriesNames?: readonly string[]
-  getCaptureEl?: () => HTMLElement | null
+  getCaptureEl?: (ctx: DownloadContext) => HTMLElement | null
   pngPixelRatio?: number
   pngBackgroundColor?: string | null
 }): DownloadItem[] {
@@ -34,8 +35,8 @@ export function createTimeseriesDownloadConfig(args: {
   items.push(
     buildCsvDownloadItem({
       filename: args.filename,
-      getRows: () => {
-        const data = args.getData()
+      getRows: (ctx) => {
+        const data = args.getData(ctx)
         const seriesCount = data.length
 
         // Collect every unique time, preserving insertion order.

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

@@ -56,7 +56,7 @@ export interface ToolboxProps {
  * Smart overflow toolbar with **single-mount** items. Children mount once
  * into a stable, hidden host element and are *physically reparented* via
  * `appendChild` between the inline preview area and the overflow `<Paper>`
- * as the popper opens / closes — same pattern as `Widget.FullScreen.Slot`.
+ * as the popper opens / closes.
  * Items with no inline space when closed are kept mounted but visually
  * hidden via `display: none`.
  *