@carto/ps-react-ui 4.7.0 → 4.8.0

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
+}

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

@@ -0,0 +1,10 @@
+export { barOptions, createBarOptionFactory } from './options'
+export { BarSkeleton } from './skeleton'
+export { createBarDownloadConfig } from './download'
+export type {
+  BarDatum,
+  BarWidgetData,
+  BarOptionsInput,
+  BarOptionFactoryInput,
+  BarEChartsOption,
+} from './types'

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

@@ -0,0 +1,317 @@
+import { describe, it, expect } from 'vitest'
+import { createTheme, type Theme } from '@mui/material'
+import { barOptions, createBarOptionFactory } from './options'
+
+const theme = createTheme() as unknown as Theme
+
+describe('barOptions (structural)', () => {
+  it('returns a category x-axis without baked data', () => {
+    const out = barOptions({ theme })
+    const xAxis = out.xAxis as { type: string; data?: unknown }
+    expect(xAxis.type).toBe('category')
+    expect(xAxis.data).toBeUndefined()
+  })
+
+  it('returns no series and no dataset (data is fused at render time)', () => {
+    const out = barOptions({ theme })
+    expect(out.series).toBeUndefined()
+    expect(out.dataset).toBeUndefined()
+  })
+
+  it('hides x and y axis lines and ticks for the v1 minimal look', () => {
+    const out = barOptions({ theme })
+    const xAxis = out.xAxis as {
+      axisLine?: { show?: boolean }
+      axisTick?: { show?: boolean }
+    }
+    const yAxis = out.yAxis as {
+      axisLine?: { show?: boolean }
+      axisTick?: { show?: boolean }
+      splitLine?: { show?: boolean }
+    }
+    expect(xAxis.axisLine?.show).toBe(false)
+    expect(xAxis.axisTick?.show).toBe(false)
+    expect(yAxis.axisLine?.show).toBe(false)
+    expect(yAxis.axisTick?.show).toBe(false)
+    expect(yAxis.splitLine?.show).toBe(true)
+  })
+
+  it('y-axis label formatter only renders min/max via the user formatter', () => {
+    const fmt = (n: number): string => `$${n}`
+    const out = barOptions({ theme, formatter: fmt })
+    const yAxis = out.yAxis as {
+      axisLabel?: { formatter?: (v: number) => string }
+    }
+    // niceMin / niceMax default to 0 and 1 until min/max callbacks run.
+    expect(yAxis.axisLabel?.formatter?.(1)).toBe('$1')
+    // 0 is suppressed (matches v1) and intermediate values are blanked.
+    expect(yAxis.axisLabel?.formatter?.(0)).toBe('')
+    expect(yAxis.axisLabel?.formatter?.(0.5)).toBe('')
+  })
+
+  it('renders y-axis labels inside the plot, anchored to the bottom', () => {
+    const out = barOptions({ theme })
+    const yAxis = out.yAxis as {
+      axisLabel?: { inside?: boolean; verticalAlign?: string }
+    }
+    expect(yAxis.axisLabel?.inside).toBe(true)
+    expect(yAxis.axisLabel?.verticalAlign).toBe('bottom')
+  })
+
+  it('wires labelFormatter into the x-axis label', () => {
+    const lf = (v: string | number) => `[${v}]`
+    const out = barOptions({ theme, labelFormatter: lf })
+    const xAxis = out.xAxis as {
+      axisLabel?: { formatter?: (v: string | number) => string }
+    }
+    expect(xAxis.axisLabel?.formatter?.('A')).toBe('[A]')
+  })
+})
+
+describe('createBarOptionFactory', () => {
+  it('builds one dataset per series with the data array as source', () => {
+    const merge = createBarOptionFactory({ theme })
+    const data = [
+      [
+        { name: 'A', value: 1 },
+        { name: 'B', value: 2 },
+      ],
+      [
+        { name: 'A', value: 3 },
+        { name: 'B', value: 4 },
+      ],
+    ]
+    const out = merge({}, data) as { dataset: { source: object[] }[] }
+    expect(out.dataset).toHaveLength(2)
+    expect(out.dataset[0]?.source).toBe(data[0])
+    expect(out.dataset[1]?.source).toBe(data[1])
+  })
+
+  it('encodes name → x and value → y, with each series referencing its dataset by index', () => {
+    const merge = createBarOptionFactory({ theme })
+    const out = merge({}, [
+      [{ name: 'A', value: 1 }],
+      [{ name: 'A', value: 2 }],
+    ]) as {
+      series: {
+        type: string
+        datasetIndex: number
+        encode: { x: string; y: string }
+        barMaxWidth: number
+        emphasis: { focus: string }
+      }[]
+    }
+    expect(out.series[0]).toMatchObject({
+      type: 'bar',
+      datasetIndex: 0,
+      encode: { x: 'name', y: 'value' },
+      barMaxWidth: 100,
+      emphasis: { focus: 'series' },
+    })
+    expect(out.series[1]).toMatchObject({
+      type: 'bar',
+      datasetIndex: 1,
+      encode: { x: 'name', y: 'value' },
+      barMaxWidth: 100,
+      emphasis: { focus: 'series' },
+    })
+  })
+
+  it('uses seriesNames for legend names when provided', () => {
+    const merge = createBarOptionFactory({
+      theme,
+      seriesNames: ['2024', '2025'],
+    })
+    const out = merge({}, [
+      [{ name: 'A', value: 1 }],
+      [{ name: 'A', value: 2 }],
+    ]) as { series: { name: string }[] }
+    expect(out.series[0]?.name).toBe('2024')
+    expect(out.series[1]?.name).toBe('2025')
+  })
+
+  it('toggles legend visibility based on series count, preserving styling', () => {
+    const merge = createBarOptionFactory({ theme })
+    const baseLegend = { icon: 'circle', type: 'scroll' }
+    const single = merge({ legend: baseLegend }, [
+      [{ name: 'A', value: 1 }],
+    ]) as { legend: { show: boolean; icon?: string } }
+    const multi = merge({ legend: baseLegend }, [
+      [{ name: 'A', value: 1 }],
+      [{ name: 'A', value: 2 }],
+    ]) as { legend: { show: boolean; icon?: string } }
+    expect(single.legend.show).toBe(false)
+    expect(single.legend.icon).toBe('circle')
+    expect(multi.legend.show).toBe(true)
+    expect(multi.legend.icon).toBe('circle')
+  })
+
+  it('reserves extra grid bottom space when a legend is shown', () => {
+    const merge = createBarOptionFactory({ theme })
+    const baseGrid = { bottom: 24 }
+    const single = merge({ grid: baseGrid }, [[{ name: 'A', value: 1 }]]) as {
+      grid: { bottom: number }
+    }
+    const multi = merge({ grid: baseGrid }, [
+      [{ name: 'A', value: 1 }],
+      [{ name: 'A', value: 2 }],
+    ]) as { grid: { bottom: number } }
+    expect(single.grid.bottom).toBe(24)
+    expect(multi.grid.bottom).toBe(56)
+  })
+
+  it('returns empty dataset/series for empty data', () => {
+    const merge = createBarOptionFactory({ theme })
+    const out = merge({ xAxis: { type: 'category' } }, []) as {
+      dataset: unknown[]
+      series: unknown[]
+    }
+    expect(out.dataset).toEqual([])
+    expect(out.series).toEqual([])
+  })
+
+  it('merges incoming series template into every series (Stack survives)', () => {
+    // Simulates `addStack` having run as a config transform: the option
+    // arrives with a single broadcast template carrying { stack: 'total' }.
+    const merge = createBarOptionFactory({ theme })
+    const out = merge({ series: [{ stack: 'total' }] }, [
+      [{ name: 'A', value: 1 }],
+      [{ name: 'A', value: 2 }],
+    ]) as { series: { stack?: string; type: string; datasetIndex: number }[] }
+    expect(out.series).toHaveLength(2)
+    expect(out.series[0]?.stack).toBe('total')
+    expect(out.series[1]?.stack).toBe('total')
+    // Authoritative properties still win over the template.
+    expect(out.series[0]?.type).toBe('bar')
+    expect(out.series[0]?.datasetIndex).toBe(0)
+    expect(out.series[1]?.datasetIndex).toBe(1)
+  })
+
+  it('uses ctx.formatter for the y-axis min/max label (RelativeData support)', () => {
+    const merge = createBarOptionFactory({ theme })
+    const fmt = (n: number) => `${n}%`
+    const out = merge(
+      { yAxis: { type: 'value' } },
+      [
+        [
+          { name: 'A', value: 0 },
+          { name: 'B', value: 100 },
+        ],
+      ],
+      { formatter: fmt },
+    ) as {
+      yAxis: {
+        min: number
+        max: number
+        axisLabel: { formatter: (v: number) => string }
+      }
+    }
+    expect(out.yAxis.min).toBe(0)
+    expect(out.yAxis.max).toBe(100)
+    expect(out.yAxis.axisLabel.formatter(100)).toBe('100%')
+    // Intermediate values are still suppressed.
+    expect(out.yAxis.axisLabel.formatter(50)).toBe('')
+    expect(out.yAxis.axisLabel.formatter(0)).toBe('')
+  })
+
+  it('reserves grid bottom space for the zoom slider when dataZoom is present', () => {
+    const merge = createBarOptionFactory({ theme })
+    // Single series, no legend.
+    const single = merge(
+      {
+        grid: { bottom: 24 },
+        dataZoom: [{ type: 'inside' }, { type: 'slider', bottom: 0 }],
+      },
+      [[{ name: 'A', value: 1 }]],
+    ) as { grid: { bottom: number } }
+    // 24 (base) + 32 (slider height) + 8 (gap) = 64.
+    expect(single.grid.bottom).toBe(64)
+  })
+
+  it('lifts the zoom slider above the legend when both are present', () => {
+    const merge = createBarOptionFactory({ theme })
+    const out = merge(
+      {
+        dataZoom: [{ type: 'inside' }, { type: 'slider', bottom: 0 }],
+      },
+      [[{ name: 'A', value: 1 }], [{ name: 'A', value: 2 }]],
+    ) as {
+      dataZoom: { type: string; bottom?: number }[]
+      grid: { bottom: number }
+    }
+    const slider = out.dataZoom.find((d) => d.type === 'slider')
+    expect(slider?.bottom).toBe(28)
+    // Legend space (56) + slider height (32) + gap (8) = 96.
+    expect(out.grid.bottom).toBe(96)
+  })
+
+  describe('itemStyle.color (dim non-selected)', () => {
+    it('passes through the params color when no selection is set', () => {
+      const merge = createBarOptionFactory({ theme })
+      const out = merge({}, [[{ name: 'A', value: 1 }]]) as {
+        series: { itemStyle: { color: (p: unknown) => string } }[]
+      }
+      const colorFn = out.series[0]!.itemStyle.color
+      expect(colorFn({ value: { name: 'A' }, color: '#abc', name: 'A' })).toBe(
+        '#abc',
+      )
+    })
+
+    it('keeps the base colour for bars matching the selection', () => {
+      const merge = createBarOptionFactory({ theme, selection: ['A'] })
+      const out = merge({}, [[{ name: 'A', value: 1 }]]) as {
+        series: { itemStyle: { color: (p: unknown) => string } }[]
+      }
+      const colorFn = out.series[0]!.itemStyle.color
+      expect(colorFn({ value: { name: 'A' }, color: '#abc', name: 'A' })).toBe(
+        '#abc',
+      )
+    })
+
+    it('dims bars outside the selection via 15% alpha', () => {
+      const merge = createBarOptionFactory({ theme, selection: ['B'] })
+      const out = merge({}, [[{ name: 'A', value: 1 }]]) as {
+        series: { itemStyle: { color: (p: unknown) => string } }[]
+      }
+      const colorFn = out.series[0]!.itemStyle.color
+      const dimmed = colorFn({
+        value: { name: 'A' },
+        color: '#FF0000',
+        name: 'A',
+      })
+      expect(dimmed).not.toBe('#FF0000')
+    })
+
+    it('falls back to params.name when datum has no name', () => {
+      const merge = createBarOptionFactory({ theme, selection: ['A'] })
+      const out = merge({}, [[{ name: 'A', value: 1 }]]) as {
+        series: { itemStyle: { color: (p: unknown) => string } }[]
+      }
+      const colorFn = out.series[0]!.itemStyle.color
+      expect(colorFn({ value: undefined, color: '#abc', name: 'A' })).toBe(
+        '#abc',
+      )
+    })
+  })
+
+  it('uses ctx formatters for the tooltip (RelativeData support)', () => {
+    const merge = createBarOptionFactory({ theme })
+    const fmt = (n: number) => `${n}%`
+    const lf = (v: string | number) => `[ITEM:${v}]`
+    const out = merge({}, [[{ name: 'A', value: 50 }]], {
+      formatter: fmt,
+      labelFormatter: lf,
+    }) as { tooltip: { formatter: (params: unknown) => string } }
+    const html = out.tooltip.formatter([
+      {
+        value: { name: 'A', value: 50 },
+        name: 'A',
+        seriesName: '',
+        marker: '',
+      },
+    ])
+    // The percent formatter and label formatter both ran.
+    expect(html).toContain('50%')
+    expect(html).toContain('[ITEM:A]')
+  })
+})