@carto/ps-react-ui 6.0.0 → 6.1.0

package/src/widgets/pie/download.ts

@@ -1,7 +1,8 @@
 import {
   buildCsvDownloadItem,
-  buildPngDownloadItem,
+  withPngItem,
   type DownloadItem,
+  type WidgetDownloadArgs,
 } from '../actions/download'
 import type { PieWidgetData } from './types'
 
@@ -9,33 +10,20 @@ import type { PieWidgetData } from './types'
  * Download menu items for the Pie widget. Always includes a CSV item with
  * `series, name, value` columns (one row per slice; series labels come from
  * `seriesNames` if provided, else `series_<n>`). When `getCaptureEl` is
- * supplied, prepends a PNG item that rasterises the captured element via
+ * given, prepends a PNG item that rasterises the captured element via
  * `html2canvas`.
  */
-export function createPieDownloadConfig(args: {
-  filename: string
-  getData: () => PieWidgetData
-  seriesNames?: readonly string[]
-  getCaptureEl?: () => HTMLElement | null
-  pngPixelRatio?: number
-  pngBackgroundColor?: string | null
-}): DownloadItem[] {
-  const items: DownloadItem[] = []
-  if (args.getCaptureEl) {
-    items.push(
-      buildPngDownloadItem({
-        filename: args.filename,
-        getCaptureEl: args.getCaptureEl,
-        pixelRatio: args.pngPixelRatio,
-        backgroundColor: args.pngBackgroundColor,
-      }),
-    )
-  }
-  items.push(
+export function createPieDownloadConfig(
+  args: WidgetDownloadArgs<PieWidgetData> & {
+    seriesNames?: readonly string[]
+  },
+): DownloadItem[] {
+  return withPngItem(
+    args,
     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}`
@@ -47,5 +35,4 @@ export function createPieDownloadConfig(args: {
       },
     }),
   )
-  return items
 }

package/src/widgets/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/scatterplot/download.ts

@@ -1,40 +1,28 @@
 import {
   buildCsvDownloadItem,
-  buildPngDownloadItem,
+  withPngItem,
   type DownloadItem,
+  type WidgetDownloadArgs,
 } from '../actions/download'
 import type { ScatterplotWidgetData } from './types'
 
 /**
- * Download menu items for the Scatterplot widget. Always includes a CSV
- * item with `series, x, y` columns (one row per point). When
- * `getCaptureEl` is supplied, prepends a PNG item that rasterises the
- * captured element via `html2canvas`.
+ * Download menu items for the Scatterplot widget. Always includes a CSV item
+ * with `series, x, y` columns (one row per point). When `getCaptureEl` is
+ * given, prepends a PNG item that rasterises the captured element via
+ * `html2canvas`.
  */
-export function createScatterplotDownloadConfig(args: {
-  filename: string
-  getData: () => ScatterplotWidgetData
-  seriesNames?: readonly string[]
-  getCaptureEl?: () => HTMLElement | null
-  pngPixelRatio?: number
-  pngBackgroundColor?: string | null
-}): DownloadItem[] {
-  const items: DownloadItem[] = []
-  if (args.getCaptureEl) {
-    items.push(
-      buildPngDownloadItem({
-        filename: args.filename,
-        getCaptureEl: args.getCaptureEl,
-        pixelRatio: args.pngPixelRatio,
-        backgroundColor: args.pngBackgroundColor,
-      }),
-    )
-  }
-  items.push(
+export function createScatterplotDownloadConfig(
+  args: WidgetDownloadArgs<ScatterplotWidgetData> & {
+    seriesNames?: readonly string[]
+  },
+): DownloadItem[] {
+  return withPngItem(
+    args,
     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}`
@@ -46,5 +34,4 @@ export function createScatterplotDownloadConfig(args: {
       },
     }),
   )
-  return items
 }

package/src/widgets/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/spread/download.ts

@@ -1,39 +1,26 @@
 import {
   buildCsvDownloadItem,
-  buildPngDownloadItem,
+  withPngItem,
   type DownloadItem,
+  type WidgetDownloadArgs,
 } from '../actions/download'
 import type { SpreadWidgetData } from './types'
 
 /**
- * Download menu items for the Spread widget. Always includes a CSV item
- * with `series, prefix, min, max, suffix, note` columns (one row per
- * entry). When `getCaptureEl` is supplied, prepends a PNG item that
- * rasterises the captured element via `html2canvas`.
+ * Download menu items for the Spread widget. Always includes a CSV item with
+ * `series, prefix, min, max, suffix, note` columns (one row per entry). When
+ * `getCaptureEl` is given, prepends a PNG item that rasterises the captured
+ * element via `html2canvas`.
  */
-export function createSpreadDownloadConfig(args: {
-  filename: string
-  getData: () => SpreadWidgetData
-  getCaptureEl?: () => HTMLElement | null
-  pngPixelRatio?: number
-  pngBackgroundColor?: string | null
-}): DownloadItem[] {
-  const items: DownloadItem[] = []
-  if (args.getCaptureEl) {
-    items.push(
-      buildPngDownloadItem({
-        filename: args.filename,
-        getCaptureEl: args.getCaptureEl,
-        pixelRatio: args.pngPixelRatio,
-        backgroundColor: args.pngBackgroundColor,
-      }),
-    )
-  }
-  items.push(
+export function createSpreadDownloadConfig(
+  args: WidgetDownloadArgs<SpreadWidgetData>,
+): DownloadItem[] {
+  return withPngItem(
+    args,
     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'],
         ]
@@ -51,5 +38,4 @@ export function createSpreadDownloadConfig(args: {
       },
     }),
   )
-  return items
 }

package/src/widgets/stores/index.ts

@@ -29,6 +29,8 @@ export {
   useWidgetShallow,
   setCaptureEl,
   getCaptureEl,
+  widgetStoreData,
+  widgetCaptureEl,
   clearAllCaptureEls,
   setEchartInstance,
   getEchartInstance,

package/src/widgets/stores/widget-store-registry.test.ts

@@ -20,6 +20,8 @@ import {
   setEchartInstance,
   subscribeEchartInstance,
   unregisterWidgetStore,
+  widgetCaptureEl,
+  widgetStoreData,
 } from './widget-store-registry'
 import type { ECharts } from 'echarts'
 
@@ -290,3 +292,26 @@ describe('widget-store-registry', () => {
     })
   })
 })
+
+describe('download getters', () => {
+  beforeEach(() => clearAllWidgetStores())
+  afterEach(() => clearAllWidgetStores())
+
+  it('read the store the menu was opened from, else the given id', () => {
+    registerWidgetStore('card', createWidgetStore('card', { data: 'card' }))
+    registerWidgetStore('modal', createWidgetStore('modal', { data: 'modal' }))
+    const getData = widgetStoreData<string>('card')
+    expect(getData({ id: 'modal' })).toBe('modal')
+    expect(getData({ id: null })).toBe('card')
+  })
+
+  it('capture element: same rule', () => {
+    const card = document.createElement('div')
+    const modal = document.createElement('div')
+    setCaptureEl('card', card)
+    setCaptureEl('modal', modal)
+    const getEl = widgetCaptureEl('card')
+    expect(getEl({ id: 'modal' })).toBe(modal)
+    expect(getEl({ id: null })).toBe(card)
+  })
+})

package/src/widgets/stores/widget-store-registry.ts

@@ -6,6 +6,7 @@ import { useShallow } from 'zustand/react/shallow'
 import { isDev } from '@carto/ps-utils'
 import { pipelineMiddleware } from './pipeline-middleware'
 import type { WidgetInit, WidgetState, WidgetStoreApi } from './types'
+import type { DownloadContext } from '../actions/download/types'
 
 const widgetStores = new Map<string, WidgetStoreApi>()
 
@@ -86,6 +87,27 @@ export function getCaptureEl(id: string): HTMLElement | null {
   return captureEls.get(id) ?? null
 }
 
+/**
+ * `getData` for a `create*DownloadConfig`: the `data` of the store the
+ * download menu was opened from (`ctx.id` — the fullscreen dialog's own
+ * while it's open), or of widget `id` when the menu sits outside a
+ * `<Widget.Provider>`.
+ */
+export function widgetStoreData<T>(id: string): (ctx: DownloadContext) => T {
+  return (ctx) => getWidgetStore(ctx.id ?? id).getState().data as T
+}
+
+/**
+ * `getCaptureEl` for a `create*DownloadConfig`: the capture element of the
+ * store the download menu was opened from (`ctx.id`), or of widget `id`
+ * outside a `<Widget.Provider>`.
+ */
+export function widgetCaptureEl(
+  id: string,
+): (ctx: DownloadContext) => HTMLElement | null {
+  return (ctx) => getCaptureEl(ctx.id ?? id)
+}
+
 /** @internal — exposed for tests and debugging only. */
 export function clearAllCaptureEls(): void {
   captureEls.clear()

package/src/widgets/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/table/download.ts

@@ -1,43 +1,29 @@
 import {
   buildCsvDownloadItem,
-  buildPngDownloadItem,
+  withPngItem,
   type DownloadItem,
+  type WidgetDownloadArgs,
 } from '../actions/download'
 import { tableDataToCsv } from './helpers'
 import type { TableColumn, TableWidgetData } from './types'
 
 /**
- * Download menu items for the Table widget. Always includes a CSV item
- * that pulls the latest data from the widget store via `getData()` (so
- * locked / sorted / filtered state is honored); headers come from
- * `column.label`, cells from `row[column.id]`. When `getCaptureEl` is
- * supplied, prepends a PNG item that rasterises the captured element via
- * `html2canvas`.
+ * Download menu items for the Table widget. Always includes a CSV item that
+ * pulls the latest data from the widget store via `getData()` (so locked /
+ * sorted / filtered state is honored); headers come from `column.label`,
+ * cells from `row[column.id]`. When `getCaptureEl` is given, prepends a PNG
+ * item that rasterises the captured element via `html2canvas`.
  */
-export function createTableDownloadConfig(opts: {
-  filename: string
-  getData: () => TableWidgetData
-  columns: readonly TableColumn[]
-  getCaptureEl?: () => HTMLElement | null
-  pngPixelRatio?: number
-  pngBackgroundColor?: string | null
-}): DownloadItem[] {
-  const items: DownloadItem[] = []
-  if (opts.getCaptureEl) {
-    items.push(
-      buildPngDownloadItem({
-        filename: opts.filename,
-        getCaptureEl: opts.getCaptureEl,
-        pixelRatio: opts.pngPixelRatio,
-        backgroundColor: opts.pngBackgroundColor,
-      }),
-    )
-  }
-  items.push(
+export function createTableDownloadConfig(
+  opts: WidgetDownloadArgs<TableWidgetData> & {
+    columns: readonly TableColumn[]
+  },
+): DownloadItem[] {
+  return withPngItem(
+    opts,
     buildCsvDownloadItem({
       filename: opts.filename,
-      getCsv: () => tableDataToCsv(opts.getData(), opts.columns),
+      getCsv: (ctx) => tableDataToCsv(opts.getData(ctx), opts.columns),
     }),
   )
-  return items
 }

package/src/widgets/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/timeseries/download.ts

@@ -1,41 +1,29 @@
 import {
   buildCsvDownloadItem,
-  buildPngDownloadItem,
+  withPngItem,
   type DownloadItem,
+  type WidgetDownloadArgs,
 } from '../actions/download'
 import type { TimeseriesWidgetData } from './types'
 
 /**
- * Download menu items for the Timeseries widget. Always includes a CSV
- * item with `time, series_1, series_2, …` columns (one row per unique time
- * across all series; ISO-8601 strings for `Date`/numeric times). When
- * `getCaptureEl` is supplied, prepends a PNG item that rasterises the
- * captured element via `html2canvas`.
+ * Download menu items for the Timeseries widget. Always includes a CSV item
+ * with `time, series_1, series_2, …` columns (one row per unique time across
+ * all series; ISO-8601 strings for `Date`/numeric times). When
+ * `getCaptureEl` is given, prepends a PNG item that rasterises the captured
+ * element via `html2canvas`.
  */
-export function createTimeseriesDownloadConfig(args: {
-  filename: string
-  getData: () => TimeseriesWidgetData
-  seriesNames?: readonly string[]
-  getCaptureEl?: () => HTMLElement | null
-  pngPixelRatio?: number
-  pngBackgroundColor?: string | null
-}): DownloadItem[] {
-  const items: DownloadItem[] = []
-  if (args.getCaptureEl) {
-    items.push(
-      buildPngDownloadItem({
-        filename: args.filename,
-        getCaptureEl: args.getCaptureEl,
-        pixelRatio: args.pngPixelRatio,
-        backgroundColor: args.pngBackgroundColor,
-      }),
-    )
-  }
-  items.push(
+export function createTimeseriesDownloadConfig(
+  args: WidgetDownloadArgs<TimeseriesWidgetData> & {
+    seriesNames?: readonly string[]
+  },
+): DownloadItem[] {
+  return withPngItem(
+    args,
     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.
@@ -72,7 +60,6 @@ export function createTimeseriesDownloadConfig(args: {
       },
     }),
   )
-  return items
 }
 
 function formatTime(v: Date | number | string): string {

package/src/widgets/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`.
  *