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

package/src/widgets-v2/echart/echart-ui.test.tsx

@@ -0,0 +1,327 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { act, render } from '@testing-library/react'
+import type * as echarts from 'echarts'
+
+// ─── Hoisted mocks ──────────────────────────────────────────────────────────
+
+// Capture the mock chart so each test can introspect setOption / dispose calls.
+const mockChart = {
+  setOption: vi.fn(),
+  dispose: vi.fn(),
+  resize: vi.fn(),
+  on: vi.fn(),
+  off: vi.fn(),
+  dispatchAction: vi.fn(),
+  // Stubbed for the edge-label clamp; tests override per-case.
+  convertToPixel: vi.fn((_finder: unknown, index: number) =>
+    index === 0 ? 4 : 296,
+  ),
+  getWidth: vi.fn(() => 300),
+}
+const initSpy = vi.fn((...args: unknown[]): typeof mockChart => {
+  void args
+  return mockChart
+})
+
+vi.mock('echarts', () => ({
+  __esModule: true,
+  init: (...args: unknown[]) => initSpy(...args),
+  // Fake text measurement: width ∝ character count, enough to make a long
+  // edge label overflow a near-edge tick in the clamp tests.
+  format: {
+    getTextRect: (text: unknown) => ({ width: String(text).length * 10 }),
+  },
+}))
+
+/** Invoke the `finished` listener the bridge bound on the mock chart. */
+function fireFinished(): void {
+  for (const [event, handler] of mockChart.on.mock.calls) {
+    if (event === 'finished') (handler as () => void)()
+  }
+}
+
+/** Invoke the `legendselectchanged` listener the bridge bound on the mock chart. */
+function fireLegendSelectChanged(selected: Record<string, boolean>): void {
+  for (const [event, handler] of mockChart.on.mock.calls) {
+    if (event === 'legendselectchanged') {
+      ;(handler as (params: unknown) => void)({ selected })
+    }
+  }
+}
+
+// Resize observer mock — capture the callback so tests can trigger it.
+let resizeCb: (() => void) | null = null
+const observeResizeSpy = vi.fn((_node: HTMLElement, cb: () => void) => {
+  resizeCb = cb
+  return () => {
+    resizeCb = null
+  }
+})
+vi.mock('./shared-resize-observer', () => ({
+  observeResize: (node: HTMLElement, cb: () => void) =>
+    observeResizeSpy(node, cb),
+}))
+
+import { EchartUI } from './echart-ui'
+
+beforeEach(() => {
+  mockChart.setOption.mockReset()
+  mockChart.dispose.mockReset()
+  mockChart.resize.mockReset()
+  mockChart.on.mockReset()
+  mockChart.off.mockReset()
+  mockChart.dispatchAction.mockReset()
+  mockChart.convertToPixel.mockClear()
+  mockChart.getWidth.mockClear()
+  initSpy.mockClear()
+  observeResizeSpy.mockClear()
+  resizeCb = null
+})
+
+const categoryOption = {
+  xAxis: { type: 'category', axisLabel: {} },
+  series: [{ type: 'bar', encode: { x: 'name', y: 'value' }, datasetIndex: 0 }],
+  dataset: [
+    {
+      source: [
+        { name: 'California', value: 3 },
+        { name: 'Texas', value: 2 },
+        { name: 'Wyoming', value: 1 },
+      ],
+    },
+  ],
+} as unknown as echarts.EChartsOption
+
+describe('<EchartUI>', () => {
+  it('initialises echarts on mount with merged init opts and notifies onInstance', () => {
+    const onInstance = vi.fn()
+    render(
+      <EchartUI
+        option={{ xAxis: { type: 'category' } }}
+        init={{ renderer: 'canvas' }}
+        onInstance={onInstance}
+      />,
+    )
+    expect(initSpy).toHaveBeenCalledTimes(1)
+    // 3rd arg merges the default `{ renderer: 'svg', height: 304 }` with the
+    // caller's init — canvas wins.
+    const initOpts = initSpy.mock.calls[0]![2] as Record<string, unknown>
+    expect(initOpts.renderer).toBe('canvas')
+    expect(initOpts.height).toBe(304)
+    expect(onInstance).toHaveBeenCalledWith(mockChart)
+  })
+
+  it('applies setOption on mount and adds `series` to replaceMerge on first paint', () => {
+    render(<EchartUI option={{ series: [{ type: 'bar', data: [1, 2, 3] }] }} />)
+    expect(mockChart.setOption).toHaveBeenCalledTimes(1)
+    const args = mockChart.setOption.mock.calls[0]!
+    expect(
+      (args[1] as { replaceMerge?: readonly string[] }).replaceMerge,
+    ).toContain('series')
+  })
+
+  it('merges caller-provided replaceMerge keys with structural fingerprints', () => {
+    render(
+      <EchartUI
+        option={{ series: [{ type: 'bar' }] }}
+        replaceMerge={['legend', 'grid']}
+      />,
+    )
+    const augmented = (
+      mockChart.setOption.mock.calls[0]![1] as {
+        replaceMerge?: readonly string[]
+      }
+    ).replaceMerge!
+    expect(augmented).toContain('legend')
+    expect(augmented).toContain('grid')
+    expect(augmented).toContain('series')
+  })
+
+  it('skips `series` in replaceMerge when only style fields change between renders', () => {
+    const onInstance = vi.fn()
+    const { rerender } = render(
+      <EchartUI
+        option={{
+          series: [{ type: 'bar', name: 'a', data: [1] }],
+        }}
+        onInstance={onInstance}
+      />,
+    )
+    mockChart.setOption.mockClear()
+    rerender(
+      <EchartUI
+        option={{
+          // Same structural fields (type, name) — only itemStyle changed.
+          series: [
+            {
+              type: 'bar',
+              name: 'a',
+              data: [1],
+              itemStyle: { color: 'red' },
+            },
+          ],
+        }}
+        onInstance={onInstance}
+      />,
+    )
+    const replaceMerge = (
+      mockChart.setOption.mock.calls[0]![1] as {
+        replaceMerge?: readonly string[]
+      }
+    ).replaceMerge
+    // No structural change → no `series` flag added; nothing else passed.
+    expect(replaceMerge).toBeUndefined()
+  })
+
+  it('adds `series` to replaceMerge when a series field changes structurally', () => {
+    const { rerender } = render(
+      <EchartUI option={{ series: [{ type: 'bar', name: 'a' }] }} />,
+    )
+    mockChart.setOption.mockClear()
+    rerender(<EchartUI option={{ series: [{ type: 'line', name: 'a' }] }} />)
+    const replaceMerge = (
+      mockChart.setOption.mock.calls[0]![1] as {
+        replaceMerge?: readonly string[]
+      }
+    ).replaceMerge!
+    expect(replaceMerge).toContain('series')
+  })
+
+  it('adds `dataset` to replaceMerge when dataset length changes', () => {
+    const { rerender } = render(
+      <EchartUI option={{ dataset: [{ source: [] }] }} />,
+    )
+    mockChart.setOption.mockClear()
+    rerender(
+      <EchartUI option={{ dataset: [{ source: [] }, { source: [] }] }} />,
+    )
+    const replaceMerge = (
+      mockChart.setOption.mock.calls[0]![1] as {
+        replaceMerge?: readonly string[]
+      }
+    ).replaceMerge!
+    expect(replaceMerge).toContain('dataset')
+  })
+
+  it('binds onEvents handlers and unbinds them on unmount', () => {
+    const handler = vi.fn()
+    const { unmount } = render(
+      <EchartUI option={{}} onEvents={{ click: handler }} />,
+    )
+    expect(mockChart.on).toHaveBeenCalledWith('click', handler)
+    unmount()
+    expect(mockChart.off).toHaveBeenCalledWith('click', handler)
+  })
+
+  it('observes the container for resize and calls chart.resize on resize', () => {
+    render(<EchartUI option={{}} />)
+    expect(observeResizeSpy).toHaveBeenCalled()
+    expect(resizeCb).not.toBeNull()
+    act(() => resizeCb?.())
+    expect(mockChart.resize).toHaveBeenCalledTimes(1)
+  })
+
+  it('disposes the chart and calls onInstance(null) on unmount', () => {
+    const onInstance = vi.fn()
+    const { unmount } = render(<EchartUI option={{}} onInstance={onInstance} />)
+    onInstance.mockClear()
+    unmount()
+    expect(onInstance).toHaveBeenCalledWith(null)
+    expect(mockChart.dispose).toHaveBeenCalledTimes(1)
+  })
+
+  it('restores every legend item when a legend click hides the last one', () => {
+    render(<EchartUI option={{}} />)
+    fireLegendSelectChanged({ A: false, B: false, C: false })
+    expect(mockChart.dispatchAction).toHaveBeenCalledWith({
+      type: 'legendAllSelect',
+    })
+  })
+
+  it('does nothing while at least one legend item stays visible', () => {
+    render(<EchartUI option={{}} />)
+    fireLegendSelectChanged({ A: true, B: false, C: false })
+    expect(mockChart.dispatchAction).not.toHaveBeenCalled()
+  })
+
+  it('clamps overflowing edge labels on `finished` (category x-axis)', () => {
+    render(<EchartUI option={categoryOption} />)
+    mockChart.setOption.mockClear()
+    // First tick at x=4, 'California' ~100px wide (half 50) → overflows left.
+    act(() => fireFinished())
+    expect(mockChart.setOption).toHaveBeenCalledTimes(1)
+    const applied = mockChart.setOption.mock.calls[0]![0] as {
+      xAxis: { axisLabel: { alignMinLabel: string | null } }
+    }
+    expect(applied.xAxis.axisLabel.alignMinLabel).toBe('left')
+  })
+
+  it('does not clamp again on a second `finished` with the same verdict', () => {
+    render(<EchartUI option={categoryOption} />)
+    act(() => fireFinished())
+    mockChart.setOption.mockClear()
+    act(() => fireFinished())
+    expect(mockChart.setOption).not.toHaveBeenCalled()
+  })
+
+  it('does not clamp a non-category (time) x-axis', () => {
+    render(
+      <EchartUI
+        option={
+          {
+            xAxis: { type: 'time', axisLabel: {} },
+            series: [{ type: 'line', encode: { x: 'name', y: 'value' } }],
+            dataset: [{ source: [{ name: 1, value: 2 }] }],
+          } as unknown as echarts.EChartsOption
+        }
+      />,
+    )
+    mockChart.setOption.mockClear()
+    act(() => fireFinished())
+    expect(mockChart.setOption).not.toHaveBeenCalled()
+  })
+
+  it('treats a non-array series as a single-fingerprint signature', () => {
+    // The fingerprint helper handles both array AND object/single-series
+    // forms. Re-render with a *fresh* option object that has the same
+    // single-series shape — the apply effect re-runs (deps changed) but
+    // the fingerprint says nothing structural changed.
+    const { rerender } = render(
+      <EchartUI
+        option={{ series: { type: 'bar' } } as unknown as echarts.EChartsOption}
+      />,
+    )
+    mockChart.setOption.mockClear()
+    rerender(
+      <EchartUI
+        option={{ series: { type: 'bar' } } as unknown as echarts.EChartsOption}
+      />,
+    )
+    const replaceMerge = (
+      mockChart.setOption.mock.calls[0]![1] as {
+        replaceMerge?: readonly string[]
+      }
+    ).replaceMerge
+    expect(replaceMerge).toBeUndefined()
+  })
+
+  it('treats a non-array dataset as a single-fingerprint signature', () => {
+    const { rerender } = render(
+      <EchartUI
+        option={{ dataset: { source: [] } } as unknown as echarts.EChartsOption}
+      />,
+    )
+    mockChart.setOption.mockClear()
+    rerender(
+      <EchartUI
+        option={{ dataset: { source: [] } } as unknown as echarts.EChartsOption}
+      />,
+    )
+    const replaceMerge = (
+      mockChart.setOption.mock.calls[0]![1] as {
+        replaceMerge?: readonly string[]
+      }
+    ).replaceMerge
+    expect(replaceMerge).toBeUndefined()
+  })
+})

package/src/widgets-v2/echart/echart-ui.tsx

@@ -0,0 +1,232 @@
+import { useEffect, useEffectEvent, useRef } from 'react'
+import { Box, type SxProps, type Theme } from '@mui/material'
+import * as echarts from 'echarts'
+import {
+  clampEdgeLabels,
+  CENTERED,
+  type EdgeAlignment,
+} from './edge-label-clamp'
+import { observeResize } from './shared-resize-observer'
+import { styles } from './style'
+
+export const DEFAULT_INIT_OPTS = {
+  renderer: 'svg',
+  height: 304,
+} satisfies echarts.EChartsInitOpts
+
+export type EchartsEventHandler = (event: unknown) => void
+
+export interface EchartUIProps {
+  option: echarts.EChartsOption
+  /**
+   * Keys to merge as arrays (replace by index) instead of by id. The middleware
+   * memoizes this content-stably, so identical sets don't re-trigger setOption.
+   */
+  replaceMerge?: readonly string[]
+  /**
+   * Opaque ECharts event passthrough — handlers fire untransformed.
+   *
+   * **Must be referentially stable** (memoize it with `useMemo` /
+   * `useCallback`, or hoist to module scope). The binding effect depends on
+   * the `onEvents` object identity; an inline `{ click: handler }` literal
+   * recreates the object on every render and causes every listener to be
+   * detached and re-attached each commit.
+   */
+  onEvents?: Record<string, EchartsEventHandler>
+  /**
+   * Init options forwarded to echarts.init. Captured at mount only — to change
+   * `renderer` or `height` after mount, unmount and remount the chart.
+   * Defaults: `{ renderer: 'svg', height: 304 }`.
+   */
+  init?: echarts.EChartsInitOpts
+  /**
+   * Optional callback fired once after the ECharts instance is created
+   * (`onInstance(chart)`) and once when it's about to be disposed
+   * (`onInstance(null)`). Used by `Widget.Echart` to publish the live
+   * instance to the per-widget registry so other actions (e.g.
+   * `ZoomToggle`'s disable handler) can reach it without DOM lookups.
+   * No need to memoize — the bridge wraps it in `useEffectEvent` so an
+   * unstable reference does not re-init the chart.
+   */
+  onInstance?: (chart: echarts.ECharts | null) => void
+  className?: string
+  sx?: SxProps<Theme>
+}
+
+export function EchartUI({
+  option,
+  replaceMerge,
+  onEvents,
+  init,
+  onInstance,
+  className,
+  sx,
+}: EchartUIProps) {
+  const containerRef = useRef<HTMLDivElement>(null)
+  const chartRef = useRef<echarts.ECharts | null>(null)
+
+  // Structural fingerprint of the last applied series / dataset arrays.
+  // Used to decide whether the next `setOption` should *replace* those
+  // components (when their shape changed) or *merge* them (when only
+  // styling-level fields differ — e.g. a new `itemStyle.color` callback
+  // from a selection update). Replacing wipes ECharts' per-series runtime
+  // state (hover, animation cache, brush areas), so we want to do it only
+  // when the structure actually moved.
+  const seriesFingerprintRef = useRef<string | null>(null)
+  const datasetFingerprintRef = useRef<string | null>(null)
+
+  // Latest applied option (read by the `finished` clamp listener, which is
+  // bound once and must see the current option) + the edge-label alignment
+  // currently applied to the chart (so the clamp skips redundant setOptions).
+  const optionRef = useRef<echarts.EChartsOption>(option)
+  const edgeAlignRef = useRef<EdgeAlignment>(CENTERED)
+
+  // Stable notify wrapper — always reads the latest `onInstance` prop
+  // without forcing the init effect below to re-run when the parent
+  // passes a fresh function reference. The init effect now only fires
+  // when `init` actually changes (documented as mount-only anyway).
+  const notifyInstance = useEffectEvent(
+    (chart: echarts.ECharts | null): void => {
+      onInstance?.(chart)
+    },
+  )
+
+  // Init / dispose. `init` is captured once at mount.
+  useEffect(() => {
+    if (!containerRef.current) return undefined
+    const chart = echarts.init(containerRef.current, null, {
+      ...DEFAULT_INIT_OPTS,
+      ...init,
+    })
+    chartRef.current = chart
+    notifyInstance(chart)
+    // Edge-label clamp: after each layout settles (option change OR resize both
+    // end in a render → `finished`), measure the category x-axis edge labels
+    // and anchor them inward only if they'd clip. `finished` (not rAF) so
+    // `convertToPixel` sees the flushed `lazyUpdate` layout. Loop-safe: the
+    // verdict is anchor-independent, so our own clamp setOption recomputes the
+    // same result and the ref guard short-circuits.
+    const onFinished = (): void => {
+      edgeAlignRef.current = clampEdgeLabels(
+        chart,
+        optionRef.current,
+        edgeAlignRef.current,
+      )
+    }
+    chart.on('finished', onFinished)
+    // Never let the legend end up with every item hidden — a user can click
+    // series off one by one until the chart goes blank. `selected` on this
+    // event is always the FULL name→boolean map (not just the clicked item),
+    // so "every value false" reliably means "nothing left visible". Restore
+    // all of them instead. `legendAllSelect` fires its own `legendselectall`
+    // event, not `legendselectchanged`, so this can't re-trigger itself.
+    // Always-on and independent of the consumer's `onEvents` — applies to
+    // every ECharts widget in the library for free. A widget that disables
+    // legend clicks entirely (e.g. Pie's `selectedMode: false`) never fires
+    // `legendselectchanged`, so this is a no-op there.
+    const onLegendSelectChanged = (params: unknown): void => {
+      const { selected } = params as { selected?: Record<string, boolean> }
+      if (!selected) return
+      const names = Object.keys(selected)
+      if (names.length > 0 && names.every((name) => !selected[name])) {
+        chart.dispatchAction({ type: 'legendAllSelect' })
+      }
+    }
+    chart.on('legendselectchanged', onLegendSelectChanged)
+    return () => {
+      chart.off('finished', onFinished)
+      chart.off('legendselectchanged', onLegendSelectChanged)
+      // Notify observers *before* disposal so any queued imperative
+      // dispatches (e.g. ZoomToggle's `setOption` cleanup) see the
+      // instance disappear before its DOM is torn down.
+      notifyInstance(null)
+      chart.dispose()
+      chartRef.current = null
+    }
+  }, [init])
+
+  // Apply option / replaceMerge changes via merge mode (no remount required).
+  useEffect(() => {
+    const seriesFp = computeSeriesFingerprint(option)
+    const datasetFp = computeDatasetFingerprint(option)
+    const augmented = new Set<string>(replaceMerge ?? [])
+    if (seriesFp !== seriesFingerprintRef.current) augmented.add('series')
+    if (datasetFp !== datasetFingerprintRef.current) augmented.add('dataset')
+    seriesFingerprintRef.current = seriesFp
+    datasetFingerprintRef.current = datasetFp
+    // Expose the latest option to the `finished` clamp listener (bound once).
+    optionRef.current = option
+    chartRef.current?.setOption(option, {
+      notMerge: false,
+      lazyUpdate: true,
+      replaceMerge: augmented.size > 0 ? Array.from(augmented) : undefined,
+    })
+  }, [option, replaceMerge])
+
+  // Resize via shared singleton observer.
+  useEffect(() => {
+    const node = containerRef.current
+    if (!node) return undefined
+    return observeResize(node, () => {
+      chartRef.current?.resize()
+    })
+  }, [])
+
+  // Bind / unbind opaque event handlers.
+  useEffect(() => {
+    const chart = chartRef.current
+    if (!chart || !onEvents) return undefined
+    for (const [event, handler] of Object.entries(onEvents)) {
+      chart.on(event, handler)
+    }
+    return () => {
+      for (const [event, handler] of Object.entries(onEvents)) {
+        chart.off(event, handler)
+      }
+    }
+  }, [onEvents])
+
+  return (
+    <Box
+      ref={containerRef}
+      className={className}
+      sx={{ ...styles.root, ...sx }}
+    />
+  )
+}
+
+/**
+ * Cheap structural digest of the option's `series` array — covers the fields
+ * that actually demand a `replaceMerge` (length, type, datasetIndex, name,
+ * stack, encode). Excludes runtime-style fields like `itemStyle` (callbacks
+ * have unstable identity but don't change structure).
+ */
+function computeSeriesFingerprint(option: echarts.EChartsOption): string {
+  const series = option.series
+  if (!Array.isArray(series)) return series ? '1' : ''
+  return series
+    .map((s) => {
+      if (s == null || typeof s !== 'object') return String(s)
+      const o = s as Record<string, unknown>
+      return [
+        o.type,
+        o.datasetIndex,
+        o.name,
+        o.stack,
+        // `encode` is small; stringify is cheap and stable for plain objects.
+        JSON.stringify(o.encode ?? null),
+      ].join('|')
+    })
+    .join('||')
+}
+
+/**
+ * Structural digest of the option's `dataset` array — count is the only
+ * thing that needs `replaceMerge` here. Row-level changes are picked up by
+ * ECharts' default merge.
+ */
+function computeDatasetFingerprint(option: echarts.EChartsOption): string {
+  const dataset = option.dataset
+  if (!Array.isArray(dataset)) return dataset ? '1' : ''
+  return String(dataset.length)
+}