@carto/ps-react-ui 5.1.0 → 6.0.0

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

@@ -1,330 +0,0 @@
-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' }` with the caller's
-    // init — canvas wins.
-    const initOpts = initSpy.mock.calls[0]![2] as Record<string, unknown>
-    expect(initOpts.renderer).toBe('canvas')
-    // No `height`: zrender would store it and every later `resize()` would
-    // snap back to it, so the chart could never grow into a fullscreen
-    // dialog. Height is container-driven instead.
-    expect(initOpts.height).toBeUndefined()
-    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

@@ -1,236 +0,0 @@
-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'
-
-// No `height`: a numeric height here is stored in zrender's init opts, and
-// every later `resize()` resolves back to it — the chart would stay that tall
-// inside a fullscreen dialog. Height comes from the container instead
-// (`styles.root`'s `min-height` inline, `flex: 1` when the parent has one).
-export const DEFAULT_INIT_OPTS = {
-  renderer: 'svg',
-} 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 is container-driven, so prefer
-   * `sx={{ minHeight }}` over pinning `height` here.
-   */
-  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)
-}