@carto/ps-react-ui 4.11.3 → 4.12.1

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

@@ -0,0 +1,71 @@
+import { DOWNLOAD_ITEM_IDS } from './constants'
+import { downloadToCSV } from './exports'
+import { CSVIcon } from './icons'
+import type { DownloadItem } from './types'
+
+interface BuildCsvDownloadItemBase {
+  /** Base filename (without extension). The item appends `.csv`. */
+  filename: string
+  /** Override the menu label. Default `'CSV'`. */
+  label?: string
+}
+
+/**
+ * Args for {@link buildCsvDownloadItem}. A discriminated union: a caller must
+ * supply exactly one content source — `getRows` (rows serialised through the
+ * shared `toCsvString`) or `getCsv` (a pre-built CSV string). The `?: never`
+ * arms make passing both — or neither — a compile-time error.
+ */
+export type BuildCsvDownloadItemArgs =
+  | (BuildCsvDownloadItemBase & {
+      /**
+       * Builds the CSV rows at click time. Used by most widgets — rows are run
+       * through `toCsvString` so escaping (incl. the spreadsheet
+       * formula-injection guard) stays consistent across widgets.
+       */
+      getRows: () => readonly (readonly unknown[])[]
+      getCsv?: never
+    })
+  | (BuildCsvDownloadItemBase & {
+      /**
+       * Returns a pre-built CSV string at click time. Escape hatch for widgets
+       * (e.g. Table) that already serialise their own CSV with bespoke
+       * header/cell handling.
+       */
+      getCsv: () => string
+      getRows?: never
+    })
+
+/**
+ * Builds the standard CSV `DownloadItem` used by every per-widget download
+ * config. Centralised so the menu label, icon, and `.csv` filename suffix stay
+ * consistent across widgets — mirrors {@link buildPngDownloadItem} so neither
+ * format can drift again.
+ */
+export function buildCsvDownloadItem(
+  args: BuildCsvDownloadItemArgs,
+): DownloadItem {
+  return {
+    id: DOWNLOAD_ITEM_IDS.csv,
+    label: args.label ?? 'CSV',
+    icon: <CSVIcon fontSize='small' />,
+    resolve: () => {
+      if (args.getCsv) {
+        const csv = args.getCsv()
+        const blob = new Blob([csv], { type: 'text/csv;charset=utf-8;' })
+        const url = URL.createObjectURL(blob)
+        return Promise.resolve({
+          url,
+          filename: `${args.filename}.csv`,
+          revoke: () => URL.revokeObjectURL(url),
+        })
+      }
+      const handle = downloadToCSV(args.getRows())
+      return Promise.resolve({
+        url: handle.url,
+        filename: `${args.filename}.csv`,
+        revoke: handle.revoke,
+      })
+    },
+  }
+}

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

@@ -1,5 +1,5 @@
 import { SvgIcon, type SvgIconProps } from '@mui/material'
-import { ImageOutlined } from '@mui/icons-material'
+import { ArticleOutlined, ImageOutlined } from '@mui/icons-material'
 
 /**
  * Generic "image" glyph used for the PNG download item. Wraps MUI's
@@ -10,6 +10,15 @@ export function PNGIcon(props: SvgIconProps) {
   return <ImageOutlined {...props} />
 }
 
+/**
+ * Generic "document" glyph used for the Markdown download item. Wraps MUI's
+ * `ArticleOutlined`, mirroring {@link PNGIcon}, so the Markdown menu item
+ * carries an icon consistent with the other download formats.
+ */
+export function MarkdownIcon(props: SvgIconProps) {
+  return <ArticleOutlined {...props} />
+}
+
 /**
  * "CSV" rectangle with the letters spelled inside — matches v1 visual and is
  * easier to recognise in a download menu than a generic table glyph.

package/src/widgets-v2/actions/download/index.ts

@@ -7,7 +7,9 @@ export {
   type DownloadHandle,
   type DownloadDOMToPNGOptions,
 } from './exports'
-export { CSVIcon, PNGIcon } from './icons'
+export { CSVIcon, PNGIcon, MarkdownIcon } from './icons'
 export { buildPngDownloadItem, type BuildPngDownloadItemArgs } from './png-item'
+export { buildCsvDownloadItem, type BuildCsvDownloadItemArgs } from './csv-item'
+export { DOWNLOAD_ITEM_IDS, type DownloadItemId } from './constants'
 export type { DownloadItem } from './types'
 export { DEFAULT_DOWNLOAD_LABELS, type DownloadLabels } from './labels'

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

@@ -1,3 +1,4 @@
+import { DOWNLOAD_ITEM_IDS } from './constants'
 import { downloadDOMToPNG } from './exports'
 import { PNGIcon } from './icons'
 import type { DownloadItem } from './types'
@@ -29,7 +30,7 @@ export function buildPngDownloadItem(
   args: BuildPngDownloadItemArgs,
 ): DownloadItem {
   return {
-    id: 'png',
+    id: DOWNLOAD_ITEM_IDS.png,
     label: args.label ?? 'PNG',
     icon: <PNGIcon fontSize='small' />,
     resolve: async () => {

package/src/widgets-v2/actions/index.ts

@@ -54,14 +54,19 @@ export {
   toCsvString,
   triggerLinkDownload,
   buildPngDownloadItem,
+  buildCsvDownloadItem,
   CSVIcon,
   PNGIcon,
+  MarkdownIcon,
   DEFAULT_DOWNLOAD_LABELS,
+  DOWNLOAD_ITEM_IDS,
   type DownloadProps,
   type DownloadItem,
+  type DownloadItemId,
   type DownloadHandle,
   type DownloadDOMToPNGOptions,
   type BuildPngDownloadItemArgs,
+  type BuildCsvDownloadItemArgs,
   type DownloadLabels,
 } from './download'
 export {

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

@@ -1,7 +1,6 @@
 import {
-  CSVIcon,
+  buildCsvDownloadItem,
   buildPngDownloadItem,
-  downloadToCSV,
   type DownloadItem,
 } from '../actions/download'
 import type { BarWidgetData } from './types'
@@ -42,25 +41,20 @@ export function createBarDownloadConfig(
       }),
     )
   }
-  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,
-      })
-    },
-  })
+  items.push(
+    buildCsvDownloadItem({
+      filename: args.filename,
+      getRows: () => {
+        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])
+        }
+        return rows
+      },
+    }),
+  )
   return items
 }

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

@@ -2,6 +2,7 @@ import type { EChartsOption } from 'echarts'
 import * as echarts from 'echarts'
 import type { CallbackDataParams } from 'echarts/types/dist/shared'
 import {
+  buildAxisLabelStyle,
   buildGridConfig,
   buildLegendConfig,
   createTooltipFormatter,
@@ -86,6 +87,7 @@ export function barOptions({
       axisLine: { show: false },
       axisTick: { show: false },
       axisLabel: {
+        ...buildAxisLabelStyle(theme),
         padding: [parseInt(theme.spacing(0.5)), 0, 0, 0],
         margin: 0,
         hideOverlap: true,
@@ -111,8 +113,7 @@ export function barOptions({
         lineStyle: { color: theme.palette.black?.[4] ?? theme.palette.divider },
       },
       axisLabel: {
-        fontSize: theme.typography.overlineDelicate?.fontSize,
-        fontFamily: theme.typography.overlineDelicate?.fontFamily,
+        ...buildAxisLabelStyle(theme),
         margin: parseInt(theme.spacing(1)),
         show: true,
         showMaxLabel: true,

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

@@ -37,6 +37,15 @@ describe('createCategoryDownloadConfig', () => {
     ).toEqual(['csv'])
   })
 
+  it('CSV item carries the canonical icon and short label', () => {
+    const item = createCategoryDownloadConfig({
+      filename: 'c',
+      getData: () => data,
+    }).find((i) => i.id === 'csv')!
+    expect(item.label).toBe('CSV')
+    expect(item.icon).toBeTruthy()
+  })
+
   it('prepends PNG when getCaptureEl is provided', () => {
     const items = createCategoryDownloadConfig({
       filename: 'c',

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

@@ -1,6 +1,6 @@
 import {
+  buildCsvDownloadItem,
   buildPngDownloadItem,
-  downloadToCSV,
   type DownloadItem,
 } from '../actions/download'
 import type { CategoryWidgetData } from './types'
@@ -30,25 +30,21 @@ export function createCategoryDownloadConfig(args: {
       }),
     )
   }
-  items.push({
-    id: 'csv',
-    label: 'Download as CSV',
-    resolve: () => {
-      const data = args.getData()
-      const rows: unknown[][] = [['series', 'name', 'value']]
-      for (const [i, series] of data.entries()) {
-        const seriesName = args.seriesNames?.[i] ?? `series_${i + 1}`
-        for (const item of series) {
-          rows.push([seriesName, item.name, item.value])
+  items.push(
+    buildCsvDownloadItem({
+      filename: args.filename,
+      getRows: () => {
+        const data = args.getData()
+        const rows: unknown[][] = [['series', 'name', 'value']]
+        for (const [i, series] of data.entries()) {
+          const seriesName = args.seriesNames?.[i] ?? `series_${i + 1}`
+          for (const item of series) {
+            rows.push([seriesName, item.name, item.value])
+          }
         }
-      }
-      const handle = downloadToCSV(rows)
-      return Promise.resolve({
-        url: handle.url,
-        filename: `${args.filename}.csv`,
-        revoke: handle.revoke,
-      })
-    },
-  })
+        return rows
+      },
+    }),
+  )
   return items
 }

package/src/widgets-v2/echart/edge-label-clamp.ts

@@ -28,10 +28,13 @@ export const CENTERED: EdgeAlignment = {
   alignMaxLabel: null,
 }
 
-// Bias toward anchoring when borderline: clipping is worse than a hair of
-// off-centering, and the reconstructed font may differ slightly from what
-// ECharts actually renders.
-const SAFETY_MARGIN_PX = 2
+// Small cushion biasing toward anchoring when borderline: clipping is worse
+// than a hair of off-centering, and the measured width can differ slightly
+// from the final render (mainly when the web font isn't loaded yet at measure
+// time). Kept to 1px — a wider margin anchored labels that only just clear the
+// edge, and an anchored edge label can then be dropped by the axis
+// `hideOverlap`, leaving a gap. 1px guards measurement error without that.
+const SAFETY_MARGIN_PX = 1
 
 /**
  * Pure overflow decision. Inputs are anchor-independent (tick centers and text

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

@@ -1,7 +1,6 @@
 import {
-  CSVIcon,
+  buildCsvDownloadItem,
   buildPngDownloadItem,
-  downloadToCSV,
   type DownloadItem,
 } from '../actions/download'
 import type { FormulaWidgetData } from './types'
@@ -38,32 +37,27 @@ export function createFormulaDownloadConfig(
       }),
     )
   }
-  items.push({
-    id: 'csv',
-    label: 'CSV',
-    icon: <CSVIcon fontSize='small' />,
-    resolve: () => {
-      const data = args.getData()
-      const rows: unknown[][] = [
-        ['series', 'prefix', 'value', 'suffix', 'note', 'delta'],
-      ]
-      for (const d of data) {
-        rows.push([
-          d.series?.name ?? '',
-          d.prefix ?? '',
-          d.value,
-          d.suffix ?? '',
-          d.note ?? '',
-          d.delta?.value ?? '',
-        ])
-      }
-      const handle = downloadToCSV(rows)
-      return Promise.resolve({
-        url: handle.url,
-        filename: `${args.filename}.csv`,
-        revoke: handle.revoke,
-      })
-    },
-  })
+  items.push(
+    buildCsvDownloadItem({
+      filename: args.filename,
+      getRows: () => {
+        const data = args.getData()
+        const rows: unknown[][] = [
+          ['series', 'prefix', 'value', 'suffix', 'note', 'delta'],
+        ]
+        for (const d of data) {
+          rows.push([
+            d.series?.name ?? '',
+            d.prefix ?? '',
+            d.value,
+            d.suffix ?? '',
+            d.note ?? '',
+            d.delta?.value ?? '',
+          ])
+        }
+        return rows
+      },
+    }),
+  )
   return items
 }

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

@@ -1,6 +1,6 @@
 import {
+  buildCsvDownloadItem,
   buildPngDownloadItem,
-  downloadToCSV,
   type DownloadItem,
 } from '../actions/download'
 import type { HistogramWidgetData } from './types'
@@ -31,30 +31,26 @@ export function createHistogramDownloadConfig(args: {
       }),
     )
   }
-  items.push({
-    id: 'csv',
-    label: 'Download as CSV',
-    resolve: () => {
-      const data = args.getData()
-      const ticks = args.getTicks()
-      const seriesCount = data.length
-      const header: unknown[] = ['bin_low', 'bin_high']
-      for (let i = 0; i < seriesCount; i++) {
-        header.push(args.seriesNames?.[i] ?? `series_${i + 1}`)
-      }
-      const rows: unknown[][] = [header]
-      for (let bin = 0; bin < Math.max(0, ticks.length - 1); bin++) {
-        const row: unknown[] = [ticks[bin], ticks[bin + 1]]
-        for (let s = 0; s < seriesCount; s++) row.push(data[s]?.[bin] ?? 0)
-        rows.push(row)
-      }
-      const handle = downloadToCSV(rows)
-      return Promise.resolve({
-        url: handle.url,
-        filename: `${args.filename}.csv`,
-        revoke: handle.revoke,
-      })
-    },
-  })
+  items.push(
+    buildCsvDownloadItem({
+      filename: args.filename,
+      getRows: () => {
+        const data = args.getData()
+        const ticks = args.getTicks()
+        const seriesCount = data.length
+        const header: unknown[] = ['bin_low', 'bin_high']
+        for (let i = 0; i < seriesCount; i++) {
+          header.push(args.seriesNames?.[i] ?? `series_${i + 1}`)
+        }
+        const rows: unknown[][] = [header]
+        for (let bin = 0; bin < Math.max(0, ticks.length - 1); bin++) {
+          const row: unknown[] = [ticks[bin], ticks[bin + 1]]
+          for (let s = 0; s < seriesCount; s++) row.push(data[s]?.[bin] ?? 0)
+          rows.push(row)
+        }
+        return rows
+      },
+    }),
+  )
   return items
 }

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

@@ -2,6 +2,7 @@ import type { EChartsOption } from 'echarts'
 import * as echarts from 'echarts'
 import type { CallbackDataParams } from 'echarts/types/dist/shared'
 import {
+  buildAxisLabelStyle,
   buildGridConfig,
   buildLegendConfig,
   createTooltipFormatter,
@@ -92,6 +93,7 @@ export function histogramOptions({
       axisLine: { show: false },
       axisTick: { show: false },
       axisLabel: {
+        ...buildAxisLabelStyle(theme),
         padding: [parseInt(theme.spacing(0.5)), 0, 0, 0],
         margin: 0,
         hideOverlap: true,
@@ -114,8 +116,7 @@ export function histogramOptions({
         lineStyle: { color: theme.palette.black?.[4] ?? theme.palette.divider },
       },
       axisLabel: {
-        fontSize: theme.typography.overlineDelicate?.fontSize,
-        fontFamily: theme.typography.overlineDelicate?.fontFamily,
+        ...buildAxisLabelStyle(theme),
         margin: parseInt(theme.spacing(1)),
         show: true,
         showMaxLabel: true,

package/src/widgets-v2/markdown/{download.ts → download.tsx}

@@ -1,4 +1,6 @@
 import {
+  DOWNLOAD_ITEM_IDS,
+  MarkdownIcon,
   buildPngDownloadItem,
   toCsvString,
   triggerLinkDownload,
@@ -31,8 +33,9 @@ export function createMarkdownDownloadConfig(args: {
     )
   }
   items.push({
-    id: 'md',
-    label: 'Download as Markdown',
+    id: DOWNLOAD_ITEM_IDS.markdown,
+    label: 'Markdown',
+    icon: <MarkdownIcon fontSize='small' />,
     resolve: () => {
       const data = args.getData()
       const blob = new Blob([data.content ?? ''], {

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

@@ -1,6 +1,6 @@
 import {
+  buildCsvDownloadItem,
   buildPngDownloadItem,
-  downloadToCSV,
   type DownloadItem,
 } from '../actions/download'
 import type { PieWidgetData } from './types'
@@ -31,25 +31,21 @@ export function createPieDownloadConfig(args: {
       }),
     )
   }
-  items.push({
-    id: 'csv',
-    label: 'Download as CSV',
-    resolve: () => {
-      const data = args.getData()
-      const rows: unknown[][] = [['series', 'name', 'value']]
-      for (const [i, series] of data.entries()) {
-        const seriesName = args.seriesNames?.[i] ?? `series_${i + 1}`
-        for (const slice of series) {
-          rows.push([seriesName, slice.name, slice.value])
+  items.push(
+    buildCsvDownloadItem({
+      filename: args.filename,
+      getRows: () => {
+        const data = args.getData()
+        const rows: unknown[][] = [['series', 'name', 'value']]
+        for (const [i, series] of data.entries()) {
+          const seriesName = args.seriesNames?.[i] ?? `series_${i + 1}`
+          for (const slice of series) {
+            rows.push([seriesName, slice.name, slice.value])
+          }
         }
-      }
-      const handle = downloadToCSV(rows)
-      return Promise.resolve({
-        url: handle.url,
-        filename: `${args.filename}.csv`,
-        revoke: handle.revoke,
-      })
-    },
-  })
+        return rows
+      },
+    }),
+  )
   return items
 }

package/src/widgets-v2/pie/skeleton.test.tsx

@@ -10,8 +10,11 @@ describe('<PieSkeleton>', () => {
     ).toBeGreaterThan(0)
   })
 
-  it('scales with count', () => {
-    const { container } = render(<PieSkeleton count={3} />)
-    expect(container.firstChild).not.toBeNull()
+  it('accepts count but always renders a single donut', () => {
+    const single = render(<PieSkeleton count={1} />)
+    const many = render(<PieSkeleton count={3} />)
+    const skeletonCount = (c: HTMLElement) =>
+      c.querySelectorAll('.MuiSkeleton-root').length
+    expect(skeletonCount(many.container)).toBe(skeletonCount(single.container))
   })
 })

package/src/widgets-v2/pie/skeleton.tsx

@@ -1,19 +1,55 @@
 import { Box, Skeleton } from '@mui/material'
 import type { SxProps, Theme } from '@mui/material'
 
+const OUTER_SIZE = 160
+const HOLE_SIZE = 96
+
 const styles = {
   root: {
     display: 'flex',
+    flexDirection: 'column',
     alignItems: 'center',
     justifyContent: 'center',
     minHeight: 200,
     py: 1,
-    gap: 2,
+    gap: ({ spacing }) => spacing(2),
   },
   donut: {
-    width: 160,
-    height: 160,
+    position: 'relative',
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  ring: {
+    width: OUTER_SIZE,
+    height: OUTER_SIZE,
+  },
+  hole: {
+    position: 'absolute',
+    zIndex: 1,
+    width: HOLE_SIZE,
+    height: HOLE_SIZE,
     borderRadius: '50%',
+    bgcolor: 'background.paper',
+  },
+  label: {
+    position: 'absolute',
+    zIndex: 2,
+    display: 'flex',
+    flexDirection: 'column',
+    alignItems: 'center',
+    justifyContent: 'center',
+    gap: ({ spacing }) => spacing(0.5),
+  },
+  legend: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: ({ spacing }) => spacing(2),
+  },
+  legendItem: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: ({ spacing }) => spacing(1.5),
   },
 } satisfies Record<string, SxProps<Theme>>
 
@@ -21,12 +57,38 @@ export interface PieSkeletonProps {
   count?: number
 }
 
-export function PieSkeleton({ count = 1 }: PieSkeletonProps) {
+/**
+ * Loading state for the Pie widget. Mirrors the donut silhouette — a ring
+ * (gray circle with a background-coloured hole punched out), a stacked
+ * value/name stub in the centre, and a centered legend stub below — so the
+ * skeleton reads as "a donut chart" rather than a solid disc.
+ *
+ * Single donut only: multi-series pie loads as a horizontal bar chart, so
+ * rendering one ring stays honest regardless of `count`.
+ */
+export function PieSkeleton({ count }: PieSkeletonProps) {
+  // `count` is accepted for API compatibility but intentionally unused: the
+  // skeleton always renders a single donut, since multi-series pie loads as a
+  // horizontal bar chart rather than multiple donuts.
+  void count
   return (
     <Box sx={styles.root}>
-      {Array.from({ length: count }).map((_, i) => (
-        <Skeleton key={`donut-${i}`} variant='circular' sx={styles.donut} />
-      ))}
+      <Box sx={styles.donut}>
+        <Skeleton variant='circular' sx={styles.ring} />
+        <Box sx={styles.hole} />
+        <Box sx={styles.label}>
+          <Skeleton width={56} height={18} />
+          <Skeleton width={36} height={8} />
+        </Box>
+      </Box>
+      <Box sx={styles.legend}>
+        {[0, 1].map((i) => (
+          <Box key={`legend-${i}`} sx={styles.legendItem}>
+            <Skeleton variant='circular' width={8} height={8} />
+            <Skeleton width={48} height={8} />
+          </Box>
+        ))}
+      </Box>
     </Box>
   )
 }