@carto/ps-react-ui 4.7.1 → 4.8.0

package/src/widgets-v2/category/types.ts

@@ -0,0 +1,54 @@
+/** A single row in a Category widget. `name` is the category key. */
+export interface CategoryDataItem {
+  name: string | number
+  value: number
+  /** Optional per-row color override (wins over series + palette). */
+  color?: string
+}
+
+/**
+ * Category widget data — array of series, each a flat list of `{name, value}`.
+ *
+ * Single-series (`data.length === 1`) renders one bar per row.
+ * Multi-series (`data.length > 1`) groups items by `name` across series and
+ * renders N vertically-stacked bars per row, with a sticky legend at the
+ * bottom when `series` metadata is supplied.
+ */
+export type CategoryWidgetData = readonly (readonly CategoryDataItem[])[]
+
+/**
+ * The keyspace of selectable items. Per the destination-owned selection
+ * principle, the consumer keeps this in their own store.
+ */
+export type CategoryKey = string | number
+
+/**
+ * Per-series metadata. Supplied to enable the legend and override the
+ * auto-assigned palette color for a given series index. Length should
+ * mirror `data.length` for a full legend; shorter/longer arrays degrade
+ * gracefully (extra entries ignored; missing entries get palette
+ * defaults and are absent from the legend).
+ */
+export interface CategorySeriesConfig {
+  name: string
+  color?: string
+}
+
+/**
+ * Labels for the "Other" overflow row (rendered when `data.length`
+ * exceeds `maxItems`). `{count}` in `otherCount` is replaced with the
+ * number of hidden categories.
+ */
+export interface CategoryLabels {
+  other?: string
+  otherCount?: string
+}
+
+/**
+ * Visual density of the bar primitive. `'small'` (default) keeps the
+ * original 4px-tall, fully-rounded track. `'medium'` renders a 12px-tall
+ * track with a 2px corner radius (squarer affordance for denser layouts).
+ * Only the bar track + fill are affected — row layout, label typography,
+ * value column, legend, and hover affordance are unchanged.
+ */
+export type CategorySize = 'small' | 'medium'

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

@@ -0,0 +1,232 @@
+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(),
+}
+const initSpy = vi.fn((...args: unknown[]): typeof mockChart => {
+  void args
+  return mockChart
+})
+
+vi.mock('echarts', () => ({
+  __esModule: true,
+  init: (...args: unknown[]) => initSpy(...args),
+}))
+
+// 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()
+  initSpy.mockClear()
+  observeResizeSpy.mockClear()
+  resizeCb = null
+})
+
+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('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,184 @@
+import { useEffect, useEffectEvent, useRef } from 'react'
+import { Box, type SxProps, type Theme } from '@mui/material'
+import * as echarts from 'echarts'
+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)
+
+  // 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)
+    return () => {
+      // 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
+    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)
+}

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

@@ -0,0 +1,229 @@
+import { useEffect } from 'react'
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+import { act, render } from '@testing-library/react'
+import type * as echarts from 'echarts'
+import { Provider } from '../provider/widget-provider'
+import { Echart } from './echart'
+import type { OptionFactory } from './echart'
+import {
+  clearAllWidgetStores,
+  getEchartInstance,
+  getWidgetStore,
+} from '../stores'
+
+// Capture the option that EchartUI receives, since we don't render real ECharts in tests.
+const captured: {
+  option: echarts.EChartsOption | null
+  replaceMerge: readonly string[] | null
+  setOptions: number
+} = {
+  option: null,
+  replaceMerge: null,
+  setOptions: 0,
+}
+
+vi.mock('./echart-ui', () => ({
+  EchartUI: ({
+    option,
+    replaceMerge,
+    onInstance,
+  }: {
+    option: echarts.EChartsOption
+    replaceMerge: readonly string[]
+    onInstance?: (chart: echarts.ECharts | null) => void
+  }) => {
+    captured.option = option
+    captured.replaceMerge = replaceMerge
+    captured.setOptions++
+    // Mimic the real bridge: publish a fake instance on mount, clear on
+    // unmount. Cast through unknown so the test doesn't depend on the full
+    // ECharts surface.
+    useEffect(() => {
+      const fake = { __mock: true } as unknown as echarts.ECharts
+      onInstance?.(fake)
+      return () => onInstance?.(null)
+    }, [onInstance])
+    return null
+  },
+  DEFAULT_INIT_OPTS: { renderer: 'svg', height: 304 },
+}))
+
+beforeEach(() => {
+  clearAllWidgetStores()
+  captured.option = null
+  captured.replaceMerge = null
+  captured.setOptions = 0
+})
+afterEach(() => clearAllWidgetStores())
+
+// Helper: build an OptionFactory whose structural branch returns `structural`
+// and whose merge branch passes the post-config-transforms option through
+// `mergeData(option, data, ctx)`.
+const makeFactory = (
+  structural: echarts.EChartsOption,
+  mergeData: (
+    option: echarts.EChartsOption,
+    data: unknown,
+  ) => echarts.EChartsOption,
+): OptionFactory => {
+  return (option, data) => {
+    if (option == null) return structural
+    return mergeData(option, data)
+  }
+}
+
+describe('<Echart> bridge — owns the option factory directly', () => {
+  it('forwards the structural option to EchartUI synchronously on first render', () => {
+    const factory = makeFactory(
+      { xAxis: { type: 'category' } } as echarts.EChartsOption,
+      // Merge branch: return the option as-is so the structural option
+      // flows through to ECharts unchanged.
+      (option) => option,
+    )
+    render(
+      <Provider id='e1' data={[]}>
+        <Echart optionFactory={factory} />
+      </Provider>,
+    )
+    expect(captured.option).toEqual({ xAxis: { type: 'category' } })
+    // No `rawOptions` on the store — the option pipeline is Echart-local now.
+    expect(
+      (getWidgetStore('e1').getState() as unknown as { rawOptions?: unknown })
+        .rawOptions,
+    ).toBeUndefined()
+  })
+
+  it('fuses state.data into the option via the factory merge branch (dataset)', () => {
+    const factory = makeFactory(
+      { xAxis: { type: 'category' } } as echarts.EChartsOption,
+      (option, data) =>
+        ({
+          ...option,
+          dataset: Array.isArray(data)
+            ? (data as { name: string; value: number }[][]).map((source) => ({
+                source,
+              }))
+            : [],
+        }) as echarts.EChartsOption,
+    )
+    render(
+      <Provider id='e2' data={[[{ name: 'A', value: 1 }]]}>
+        <Echart optionFactory={factory} />
+      </Provider>,
+    )
+    const captured2 = captured.option as { dataset: { source: unknown }[] }
+    expect(captured2.dataset).toHaveLength(1)
+    expect(captured2.dataset[0]?.source).toEqual([{ name: 'A', value: 1 }])
+  })
+
+  it('updates the option when a data transform changes state.data (no re-init)', () => {
+    interface Row {
+      name: string
+      value: number
+    }
+    const factory = makeFactory(
+      { xAxis: { type: 'category' } } as echarts.EChartsOption,
+      (option, data) =>
+        ({
+          ...option,
+          // Mark each dataset with the record count so changes are observable.
+          dataset: Array.isArray(data)
+            ? (data as Row[][]).map((s) => ({
+                source: s,
+                id: `len:${s.length}`,
+              }))
+            : [],
+        }) as echarts.EChartsOption,
+    )
+    render(
+      <Provider
+        id='e3'
+        data={[
+          [
+            { name: 'A', value: 1 },
+            { name: 'B', value: 2 },
+            { name: 'C', value: 3 },
+          ],
+        ]}
+      >
+        <Echart optionFactory={factory} />
+      </Provider>,
+    )
+
+    // Before transform: 3 records.
+    let dataset = (captured.option as { dataset: { id: string }[] }).dataset
+    expect(dataset[0]?.id).toBe('len:3')
+
+    // Register a data transform that filters out half the records.
+    act(() => {
+      getWidgetStore('e3').setState({
+        dataTransforms: [
+          {
+            id: 'cut',
+            type: 'data',
+            order: 1,
+            enabled: true,
+            fn: (input) => {
+              const arr = input as { name: string; value: number }[][]
+              return arr.map((s) => s.slice(0, 1))
+            },
+          },
+        ],
+      })
+    })
+
+    // Bridge should have re-rendered with post-pipeline data: 1 record.
+    dataset = (captured.option as { dataset: { id: string }[] }).dataset
+    expect(dataset[0]?.id).toBe('len:1')
+  })
+
+  it('applies configTransforms to the rendered option and forwards replaceMerge', () => {
+    const factory = makeFactory(
+      { xAxis: { type: 'category' } } as echarts.EChartsOption,
+      (option) => option,
+    )
+    render(
+      <Provider id='e-cfg' data={[]}>
+        <Echart optionFactory={factory} />
+      </Provider>,
+    )
+
+    // Before transform: untouched structural; replaceMerge is the default.
+    expect(captured.option).toEqual({ xAxis: { type: 'category' } })
+    expect(captured.replaceMerge).toEqual(['toolbox'])
+
+    // Register a config transform that stamps a field onto the option and
+    // contributes a `replaceMergeKeys` entry.
+    act(() => {
+      getWidgetStore('e-cfg').setState({
+        configTransforms: [
+          {
+            id: 'stamp',
+            type: 'config',
+            order: 1,
+            enabled: true,
+            replaceMergeKeys: ['stamp'],
+            fn: (o) => ({ ...(o as object), stamp: true }),
+          },
+        ],
+      })
+    })
+
+    // After transform: option carries the mutation, replaceMerge is
+    // deduped+sorted with the default and the transform's keys.
+    expect((captured.option as { stamp?: boolean }).stamp).toBe(true)
+    expect(captured.replaceMerge).toEqual(['stamp', 'toolbox'])
+  })
+
+  it('publishes the live ECharts instance to the per-id registry on mount and clears on unmount', () => {
+    const factory = makeFactory({} as echarts.EChartsOption, (option) => option)
+    const { unmount } = render(
+      <Provider id='e-instance' data={[]}>
+        <Echart optionFactory={factory} />
+      </Provider>,
+    )
+    expect(getEchartInstance('e-instance')).not.toBeNull()
+    unmount()
+    expect(getEchartInstance('e-instance')).toBeNull()
+  })
+})