@carto/ps-react-ui 5.0.0-widgets.9 → 5.0.0

package/src/widgets/echart/shared-resize-observer.ts

@@ -0,0 +1,45 @@
+/**
+ * Shared ResizeObserver singleton for all ECharts instances.
+ *
+ * Instead of creating 100+ individual ResizeObserver instances (one per chart),
+ * this module provides a single shared observer that efficiently handles resize
+ * callbacks for all registered elements.
+ */
+
+type ResizeCallback = () => void
+
+const callbacks = new Map<Element, ResizeCallback>()
+
+let observer: ResizeObserver | null = null
+
+function getObserver(): ResizeObserver {
+  observer ??= new ResizeObserver((entries) => {
+    for (const entry of entries) {
+      const callback = callbacks.get(entry.target)
+      callback?.()
+    }
+  })
+  return observer
+}
+
+export function observeResize(
+  element: Element,
+  callback: ResizeCallback,
+): () => void {
+  callbacks.set(element, callback)
+  getObserver().observe(element)
+
+  return () => {
+    callbacks.delete(element)
+    getObserver().unobserve(element)
+  }
+}
+
+/** Reset the shared observer (for testing only). */
+export function resetSharedResizeObserver(): void {
+  if (observer) {
+    observer.disconnect()
+    observer = null
+  }
+  callbacks.clear()
+}

package/src/widgets/echart/types.ts

@@ -0,0 +1,45 @@
+import type { EChartsOption } from 'echarts'
+import type * as echarts from 'echarts'
+import type { BaseWidgetState } from '../stores/types'
+import type { Ref, RefObject } from 'react'
+import { theme as CartoTheme } from '@carto/meridian-ds/theme'
+
+export type EchartOptionsProps = EChartsOption
+
+export interface EchartUIProps {
+  id: string
+  option: EchartOptionsProps
+  className?: string
+  init?: echarts.EChartsInitOpts
+  style?: React.CSSProperties
+  ref?: Ref<echarts.ECharts>
+  onEvents?: Record<string, Parameters<echarts.ECharts['on']>[2]>
+}
+
+export interface EchartProps {
+  id: EchartUIProps['id']
+}
+
+export type EchartWidgetData = Record<string, string | number>[][]
+
+export type EchartWidgetState = BaseWidgetState<{
+  option: EchartUIProps['option']
+  onEvents?: EchartUIProps['onEvents']
+  init?: EchartUIProps['init']
+  instance?: RefObject<echarts.ECharts | null>
+}>
+
+export interface EchartWidgetOptionProps<D> {
+  data?: D
+  theme: typeof CartoTheme
+  formatter?: (value: number) => string
+  labelFormatter?: (value: string | number) => string | number
+}
+
+export interface EchartWidgetProps {
+  type: string
+  option: EchartUIProps['option']
+  onEvents?: EchartUIProps['onEvents']
+  formatter?: (value: number) => string
+  labelFormatter?: (value: string | number) => string | number
+}

package/src/widgets/echart/utils.test.ts

@@ -0,0 +1,277 @@
+import { describe, it, expect } from 'vitest'
+import type { Theme } from '@mui/material'
+
+import {
+  mergeEchartWidgetConfig,
+  getEChartZoomConfig,
+  getEChartBrushConfig,
+  getEChartStackConfig,
+} from './utils'
+
+const theme = {
+  spacing: (n: number) => `${n * 8}`,
+  palette: {
+    common: { white: '#ffffff' },
+    secondary: { main: '#3366ff' },
+    black: { 60: 'rgba(0,0,0,0.6)' },
+  },
+  typography: {
+    overlineDelicate: { fontSize: '11', fontFamily: 'Inter, sans-serif' },
+  },
+} as unknown as Theme
+
+describe('mergeEchartWidgetConfig', () => {
+  it('returns a deep-merged base + override when no custom merger is provided', () => {
+    const a = { title: { text: 'A' }, tooltip: { trigger: 'axis' } } as never
+    const b = { title: { subtext: 'sub' } } as never
+    const merged = mergeEchartWidgetConfig(a, b) as unknown as {
+      title: { text: string; subtext: string }
+    }
+    expect(merged.title.text).toBe('A')
+    expect(merged.title.subtext).toBe('sub')
+  })
+
+  it('handles both inputs being undefined (defaults to {})', () => {
+    const merged = mergeEchartWidgetConfig(undefined, undefined)
+    expect(merged).toEqual({})
+  })
+
+  it('replaces `color` arrays rather than concatenating', () => {
+    const merged = mergeEchartWidgetConfig(
+      { color: ['#ff0000', '#00ff00'] },
+      { color: ['#0000ff'] },
+    )
+    expect(merged.color).toEqual(['#0000ff'])
+  })
+
+  it('composes `axisLabel` formatter functions so base formatter can suppress', () => {
+    const base = {
+      xAxis: {
+        axisLabel: {
+          formatter: (v: unknown) => (v === 0 ? '' : `BASE-${String(v)}`),
+        },
+      },
+    }
+    const override = {
+      xAxis: {
+        axisLabel: {
+          formatter: (v: unknown) => `OVR-${String(v)}`,
+        },
+      },
+    }
+    const merged = mergeEchartWidgetConfig(base, override)
+    const fmt = (
+      merged.xAxis as { axisLabel: { formatter: (v: unknown) => unknown } }
+    ).axisLabel.formatter
+    expect(fmt(0)).toBe('') // base returned '' → suppressed
+    expect(fmt(5)).toBe('OVR-5') // base non-empty → fall through to override
+  })
+
+  it('merges plain object axisLabel keys when no formatter present', () => {
+    const merged = mergeEchartWidgetConfig(
+      { xAxis: { axisLabel: { color: 'red' } } },
+      { xAxis: { axisLabel: { fontSize: 12 } } },
+    )
+    const al = (merged.xAxis as { axisLabel: Record<string, unknown> })
+      .axisLabel
+    expect(al.color).toBe('red')
+    expect(al.fontSize).toBe(12)
+  })
+
+  it('merges `series` element-by-element rather than concatenating', () => {
+    const a = {
+      series: [
+        { name: 'a1', data: [1, 2] },
+        { name: 'a2', data: [3] },
+      ],
+    } as never
+    const b = { series: [{ barWidth: '60%' }] } as never
+    const merged = mergeEchartWidgetConfig(a, b) as unknown as {
+      series: { name?: string; barWidth?: string; data?: number[] }[]
+    }
+    const s = merged.series
+    expect(s).toHaveLength(2)
+    expect(s[0]!.name).toBe('a1')
+    expect(s[0]!.barWidth).toBe('60%')
+    expect(s[1]!.name).toBe('a2')
+  })
+
+  it('handles series merge when one side has no series array (defaults to length 0)', () => {
+    const merged = mergeEchartWidgetConfig(
+      { series: [{ name: 'only' }] },
+      { series: [] },
+    )
+    const s = merged.series as { name?: string }[]
+    expect(s).toHaveLength(1)
+    expect(s[0]!.name).toBe('only')
+  })
+
+  it('delegates to a custom merger when provided and it returns a function', () => {
+    const merged = mergeEchartWidgetConfig(
+      { title: { text: 'A' } },
+      { title: { text: 'B' } },
+      (key) =>
+        key === 'title'
+          ? (_a: unknown, b: unknown) => ({ ...(b as object), custom: true })
+          : undefined,
+    )
+    expect((merged.title as { text: string; custom: boolean }).text).toBe('B')
+    expect((merged.title as { text: string; custom: boolean }).custom).toBe(
+      true,
+    )
+  })
+
+  it('falls through to default merger when custom merger returns undefined for the key', () => {
+    const merged = mergeEchartWidgetConfig(
+      { color: ['#a'] },
+      { color: ['#b'] },
+      () => undefined,
+    )
+    expect(merged.color).toEqual(['#b'])
+  })
+})
+
+describe('getEChartZoomConfig', () => {
+  it('returns a default config (inside + xSlider) with no args', () => {
+    const cfg = getEChartZoomConfig()
+    expect(cfg.dataZoom).toBeDefined()
+    // inside + xSlider both true → 2 entries
+    expect(cfg.dataZoom.length).toBeGreaterThanOrEqual(2)
+  })
+
+  it('honours an explicit range start/end', () => {
+    const cfg = getEChartZoomConfig({ start: 25, end: 75 })
+    const insideCfg = cfg.dataZoom.find(
+      (z) => (z as { type: string }).type === 'inside',
+    ) as { start: number; end: number }
+    expect(insideCfg.start).toBe(25)
+    expect(insideCfg.end).toBe(75)
+  })
+
+  it('emits a vertical inside zoom when ySlider=true and inside=true', () => {
+    const cfg = getEChartZoomConfig(
+      { start: 0, end: 100 },
+      { inside: true, ySlider: true },
+    )
+    const verticalInside = cfg.dataZoom.find(
+      (z) =>
+        (z as { type: string; orientation?: string }).type === 'inside' &&
+        (z as { orientation?: string }).orientation === 'vertical',
+    )
+    expect(verticalInside).toBeDefined()
+  })
+
+  it('omits the inside entry when inside=false', () => {
+    const cfg = getEChartZoomConfig(
+      { start: 0, end: 100 },
+      { inside: false, xSlider: true },
+    )
+    const insideEntries = cfg.dataZoom.filter(
+      (z) => (z as { type: string }).type === 'inside',
+    )
+    expect(insideEntries).toHaveLength(0)
+  })
+
+  it('omits the xSlider entry when xSlider=false', () => {
+    const cfg = getEChartZoomConfig(
+      { start: 0, end: 100 },
+      { inside: false, xSlider: false, ySlider: false },
+    )
+    expect(cfg.dataZoom).toHaveLength(0)
+  })
+
+  it('includes a yAxis slider when ySlider=true', () => {
+    const cfg = getEChartZoomConfig(
+      { start: 0, end: 100 },
+      { inside: false, xSlider: false, ySlider: true },
+    )
+    const yAxisSlider = cfg.dataZoom.find((z) => {
+      const c = z as { type: string; yAxisIndex?: number[] }
+      return c.type === 'slider' && Array.isArray(c.yAxisIndex)
+    })
+    expect(yAxisSlider).toBeDefined()
+  })
+
+  it('respects bottomOffset for the xAxis slider', () => {
+    const cfg = getEChartZoomConfig(
+      { start: 0, end: 100 },
+      { bottomOffset: 16 },
+    )
+    const xSlider = cfg.dataZoom.find(
+      (z) =>
+        (z as { type: string; bottom?: number }).type === 'slider' &&
+        (z as { bottom?: number }).bottom === 16,
+    )
+    expect(xSlider).toBeDefined()
+  })
+
+  it('threads through xAxisLabelFormatter to the xSlider config', () => {
+    const fmt = (v: number) => `lbl-${v}`
+    const cfg = getEChartZoomConfig(
+      { start: 0, end: 100 },
+      { xAxisLabelFormatter: fmt },
+    )
+    const xSlider = cfg.dataZoom.find(
+      (z) =>
+        (z as { type: string; xAxisIndex?: number[] }).type === 'slider' &&
+        Array.isArray((z as { xAxisIndex?: number[] }).xAxisIndex),
+    ) as { labelFormatter: typeof fmt }
+    expect(xSlider.labelFormatter).toBe(fmt)
+  })
+
+  it('hides sliders when showSliders=false (`show` field is false)', () => {
+    const cfg = getEChartZoomConfig(
+      { start: 0, end: 100 },
+      { showSliders: false },
+    )
+    const xSlider = cfg.dataZoom.find(
+      (z) => (z as { type: string }).type === 'slider',
+    ) as { show: boolean }
+    expect(xSlider.show).toBe(false)
+  })
+
+  it('falls back to default spacing strings when theme.spacing is missing', () => {
+    const cfg = getEChartZoomConfig(undefined, undefined, undefined)
+    expect(cfg.dataZoom).toBeDefined()
+  })
+
+  it('applies theme-derived slider styles when a theme is provided', () => {
+    const cfg = getEChartZoomConfig({ start: 0, end: 100 }, undefined, theme)
+    const xSlider = cfg.dataZoom.find(
+      (z) =>
+        (z as { type: string; xAxisIndex?: number[] }).type === 'slider' &&
+        Array.isArray((z as { xAxisIndex?: number[] }).xAxisIndex),
+    ) as unknown as { fillerColor: string }
+    expect(xSlider.fillerColor).toBeDefined()
+  })
+})
+
+describe('getEChartBrushConfig', () => {
+  it('returns a default brush config when called with no args', () => {
+    const cfg = getEChartBrushConfig()
+    expect(cfg.brush.brushType).toBe('lineX')
+    expect(cfg.brush.brushMode).toBe('single')
+    expect(cfg.brush.xAxisIndex).toBe(0)
+  })
+
+  it('respects explicit brushType, brushMode, and xAxisIndex', () => {
+    const cfg = getEChartBrushConfig({
+      brushType: 'polygon',
+      brushMode: 'multiple',
+      xAxisIndex: 2,
+    })
+    expect(cfg.brush.brushType).toBe('polygon')
+    expect(cfg.brush.brushMode).toBe('multiple')
+    expect(cfg.brush.xAxisIndex).toBe(2)
+  })
+})
+
+describe('getEChartStackConfig', () => {
+  it('uses the default stack group when no arg passed', () => {
+    expect(getEChartStackConfig().stack).toBe('stacked')
+  })
+
+  it('respects an explicit stack group name', () => {
+    expect(getEChartStackConfig('foo').stack).toBe('foo')
+  })
+})

package/src/widgets/echart/utils.ts

@@ -0,0 +1,244 @@
+import deepmerge from 'deepmerge'
+import type { EchartOptionsProps } from './types'
+import type { Theme } from '@mui/material'
+import { DEFAULT_STACK_GROUP } from './const'
+
+/**
+ * Deep-merges two ECharts option objects with smart handling for `color`, `axisLabel`, and `series` keys.
+ *
+ * @param optionA - Base ECharts options.
+ * @param optionB - Override ECharts options to merge on top.
+ * @param customMergeFn - Optional function returning a custom merge strategy per key.
+ * @returns The merged ECharts options object.
+ *
+ * @remarks
+ * - `color` arrays are replaced entirely (not concatenated).
+ * - `axisLabel` formatters are composed so the base formatter can suppress values by returning `''`.
+ * - `series` arrays are merged element-by-element rather than concatenated.
+ *
+ * @example
+ * ```tsx
+ * const option = mergeEchartWidgetConfig(props.option, {
+ *   series: [{ barWidth: '60%', itemStyle: { borderRadius: [4, 4, 0, 0] } }],
+ *   tooltip: { trigger: 'axis' },
+ * })
+ * ```
+ */
+export function mergeEchartWidgetConfig<T extends EchartOptionsProps>(
+  optionA: T | undefined,
+  optionB: T | undefined,
+  customMergeFn?: (
+    key: string,
+  ) => ((a: unknown, b: unknown) => unknown) | undefined,
+): T {
+  return deepmerge(optionA ?? {}, optionB ?? {}, {
+    customMerge: (key) => {
+      const externalMerge = customMergeFn?.(key)
+      if (externalMerge) return externalMerge
+
+      if (key === 'color') {
+        return (_, b: T['color']) => b
+      }
+      if (key === 'axisLabel') {
+        return (
+          a: Record<string, unknown> | undefined,
+          b: Record<string, unknown> | undefined,
+        ) => {
+          const merged = { ...a, ...b }
+          if (
+            typeof a?.formatter === 'function' &&
+            typeof b?.formatter === 'function'
+          ) {
+            const baseFormatter = a.formatter as (value: unknown) => unknown
+            const customFormatter = b.formatter as (value: unknown) => unknown
+            merged.formatter = (value: unknown) => {
+              const baseResult = baseFormatter(value)
+              if (baseResult === '') return ''
+              return customFormatter(value)
+            }
+          }
+          return merged
+        }
+      }
+      if (key === 'series') {
+        return (a: T['series'][], b: T['series'][]) => {
+          const maxLength = Math.max(a?.length ?? 0, b?.length ?? 0)
+          return Array.from({ length: maxLength }, (_, index) => {
+            const aItem = a?.[index] ?? {}
+            const bItem = b?.[index] ?? {}
+            return deepmerge(aItem, bItem as object)
+          })
+        }
+      }
+    },
+  }) as T
+}
+
+/**
+ * Generates ECharts `dataZoom` configuration for interactive zoom and pan on chart axes.
+ *
+ * @param range - Initial visible range as `{ start, end }` percentages (0-100). Defaults to full range.
+ * @param options - Zoom behavior options including axis sliders, inside zoom, and formatter.
+ * @param theme - Optional MUI theme for styled slider handles and backgrounds.
+ * @returns An object containing the `dataZoom` array configuration.
+ */
+export function getEChartZoomConfig(
+  { start, end }: { start: number; end: number } = { start: 0, end: 100 },
+  {
+    inside = true,
+    xSlider = true,
+    ySlider = false,
+    showSliders = true,
+    xAxisLabelFormatter,
+    bottomOffset = 0,
+  } = {} as {
+    inside?: boolean
+    xSlider?: boolean
+    ySlider?: boolean
+    showSliders?: boolean
+    xAxisLabelFormatter?: (value: number) => string
+    bottomOffset?: number
+  },
+  theme?: Theme,
+) {
+  const zoom = true
+  const sliderStyles = theme ? getEChartZoomSliderStyles(theme) : {}
+
+  return {
+    dataZoom: [
+      inside && {
+        throttle: 0,
+        type: 'inside',
+        xAxisIndex: xSlider ? [0] : [],
+        yAxisIndex: ySlider ? [0] : [],
+        show: zoom,
+        zoomLock: !zoom,
+        start,
+        end,
+      },
+      inside &&
+        ySlider && {
+          throttle: 0,
+          type: 'inside',
+          show: zoom,
+          zoomLock: !zoom,
+          start,
+          end,
+          orientation: 'vertical',
+        },
+      xSlider && {
+        throttle: 0,
+        type: 'slider',
+        xAxisIndex: [0],
+        bottom: bottomOffset,
+        height: parseInt(theme?.spacing?.(4) ?? '32'),
+        show: zoom && showSliders,
+        zoomLock: !zoom,
+        start,
+        end,
+        labelFormatter: xAxisLabelFormatter,
+        showDetail: false,
+        ...sliderStyles,
+        brushSelect: false,
+        moveHandleSize: 8,
+        handleSize: '100%',
+        handleIcon:
+          'image://data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iOSIgaGVpZ2h0PSIzNiIgdmlld0JveD0iMCAwIDkgMzYiIGZpbGw9Im5vbmUiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyI+CjxyZWN0IHg9IjAuNSIgeT0iLTAuNSIgd2lkdGg9IjgiIGhlaWdodD0iMTgiIHJ4PSI0IiB0cmFuc2Zvcm09Im1hdHJpeCgxIDAgMCAtMSAwIDI3KSIgZmlsbD0id2hpdGUiIHN0cm9rZT0iIzM1OEJFNyIvPgo8cmVjdCB3aWR0aD0iMyIgaGVpZ2h0PSIyIiByeD0iMSIgdHJhbnNmb3JtPSJtYXRyaXgoMSAwIDAgLTEgMyAyMykiIGZpbGw9IiMzNThCRTciLz4KPHJlY3Qgd2lkdGg9IjMiIGhlaWdodD0iMiIgcng9IjEiIHRyYW5zZm9ybT0ibWF0cml4KDEgMCAwIC0xIDMgMTkpIiBmaWxsPSIjMzU4QkU3Ii8+CjxyZWN0IHdpZHRoPSIzIiBoZWlnaHQ9IjIiIHJ4PSIxIiB0cmFuc2Zvcm09Im1hdHJpeCgxIDAgMCAtMSAzIDE1KSIgZmlsbD0iIzM1OEJFNyIvPgo8L3N2Zz4=',
+      },
+      ySlider && {
+        throttle: 0,
+        type: 'slider',
+        left: parseInt(theme?.spacing?.(6) ?? '48'),
+        width: parseInt(theme?.spacing?.(4) ?? '32'),
+        yAxisIndex: [0],
+        show: zoom && showSliders,
+        zoomLock: !zoom,
+        start,
+        end,
+        ...sliderStyles,
+        brushSelect: false,
+        moveHandleSize: 8,
+        handleSize: '100%',
+        handleIcon:
+          'image://data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMzYiIGhlaWdodD0iOSIgdmlld0JveD0iMCAwIDM2IDkiIGZpbGw9Im5vbmUiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyI+CjxyZWN0IHg9IjAuNSIgeT0iMC41IiB3aWR0aD0iOCIgaGVpZ2h0PSIxOCIgcng9IjQiIHRyYW5zZm9ybT0icm90YXRlKC05MCAwLjUgMC41KSIgZmlsbD0id2hpdGUiIHN0cm9rZT0iIzM1OEJFNyIvPgo8cmVjdCB3aWR0aD0iMyIgaGVpZ2h0PSIyIiByeD0iMSIgdHJhbnNmb3JtPSJyb3RhdGUoLTkwIDEzIDYpIiBmaWxsPSIjMzU4QkU3Ii8+CjxyZWN0IHdpZHRoPSIzIiBoZWlnaHQ9IjIiIHJ4PSIxIiB0cmFuc2Zvcm09InJvdGF0ZSgtOTAgMTcgNikiIGZpbGw9IiMzNThCRTciLz4KPHJlY3Qgd2lkdGg9IjMiIGhlaWdodD0iMiIgcng9IjEiIHRyYW5zZm9ybT0icm90YXRlKC05MCAyMSA2KSIgZmlsbD0iIzM1OEJFNyIvPgo8L3N2Zz4=',
+      },
+    ].filter((d) => !!d),
+  }
+}
+
+function getEChartZoomSliderStyles(theme: Theme) {
+  return {
+    fillerColor: 'rgba(53, 139, 231, 0.25)',
+    borderColor: 'rgba(53, 139, 231, 0.3)',
+    borderWidth: 0.5,
+    backgroundColor: 'transparent',
+    borderRadius: 4,
+    dataBackground: {
+      lineStyle: {
+        opacity: 0,
+      },
+      areaStyle: {
+        opacity: 1,
+        color: theme.palette.secondary.main,
+      },
+    },
+    selectedDataBackground: {
+      lineStyle: {
+        opacity: 0,
+      },
+      areaStyle: {
+        opacity: 1,
+        color: theme.palette.secondary.main,
+      },
+    },
+    handleStyle: {
+      color: theme.palette.common.white,
+      borderColor: 'rgba(3, 111, 226, 0.08)',
+      borderWidth: 1,
+      shadowBlur: 3,
+      shadowColor: 'rgba(0, 0, 0, 0.1)',
+      shadowOffsetX: 0,
+      shadowOffsetY: 1,
+    },
+    textStyle: {
+      color: theme.palette.black[60],
+      fontSize: parseInt(theme.typography.overlineDelicate.fontSize as string),
+      fontFamily: theme.typography.overlineDelicate.fontFamily,
+    },
+  } as const
+}
+
+/**
+ * Generates ECharts `brush` configuration for interactive data selection on charts.
+ *
+ * @param options - Brush options including type, mode, and target axis index.
+ * @returns An object containing the `brush` configuration.
+ */
+export function getEChartBrushConfig(
+  { brushType = 'lineX', brushMode = 'single', xAxisIndex = 0 } = {} as {
+    brushType?: string
+    brushMode?: string
+    xAxisIndex?: number
+    throttleType?: string
+    throttleDelay?: number
+  },
+) {
+  return {
+    brush: {
+      toolbox: ['lineX', 'clear'],
+      brushType,
+      brushMode,
+      xAxisIndex,
+    },
+  }
+}
+
+/**
+ * Returns an ECharts `stack` configuration to group series into a stacked layout.
+ *
+ * @param stackGroup - The stack group identifier. Defaults to the library's default group.
+ * @returns An object with the `stack` property set to the group name.
+ */
+export function getEChartStackConfig(stackGroup: string = DEFAULT_STACK_GROUP) {
+  return { stack: stackGroup }
+}