@carto/ps-react-ui 5.3.0 → 6.1.0

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

@@ -1,277 +0,0 @@
-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

@@ -1,244 +0,0 @@
-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 }
-}