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

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' },
+}))
+
+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()
+  })
+})

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

@@ -0,0 +1,209 @@
+import { useCallback, useMemo } from 'react'
+import type { SxProps, Theme } from '@mui/material'
+import type * as echarts from 'echarts'
+import {
+  applyTransforms,
+  setEchartInstance,
+  useWidgetId,
+  useWidgetShallow,
+  type Transform,
+} from '../stores'
+import { EchartUI, type EchartsEventHandler } from './echart-ui'
+
+/**
+ * Default ECharts `replaceMerge` keys for every widget. `dataZoom` and
+ * `brush` are omitted so ZoomToggle / BrushToggle's user-driven runtime
+ * state (slider range, brushed areas in `multiple` mode) survives unrelated
+ * re-renders. `series` and `dataset` are also omitted: EchartUI fingerprints
+ * them per-render and adds them to `replaceMerge` only when their shape
+ * actually changes, keeping ECharts' per-series runtime state alive when
+ * only callback-style fields differ.
+ *
+ * Lives in this module (not the generic store) because it's an ECharts
+ * concept. Module-private — callers should not need it.
+ */
+const DEFAULT_REPLACE_MERGE: readonly string[] = ['toolbox']
+
+/**
+ * Reactive context passed to every {@link OptionFactory} call so the
+ * factory can rebuild render-time pieces (axis label / tooltip formatters)
+ * from the live store. Drives RelativeData / consumer-formatter changes
+ * through to the chart without rebuilding the structural option.
+ */
+export interface OptionFactoryContext {
+  formatter?: (value: number) => string
+  labelFormatter?: (value: string | number) => string | number
+}
+
+/**
+ * The per-widget option factory — a single callable that owns BOTH phases
+ * of option construction:
+ *
+ * - **Structural phase** — when `option == null`, return the theme-aware
+ *   structural option (tooltip / legend / color palette / series
+ *   template, optionally merged with a consumer-supplied `optionsOverride`).
+ *   No data is read. `<Widget.Echart>` calls the factory with
+ *   `(undefined, undefined)` synchronously during render to derive the
+ *   structural base; `configTransforms` (Stack/Zoom/Brush) then mutate it
+ *   in the same render pass.
+ * - **Merge phase** — when `option` is defined, fuse `data` into the
+ *   post-configTransforms option at fusion time. `<Widget.Echart>` calls
+ *   the factory with `(transformed, data, ctx)` on every render.
+ *
+ * The two phases share a closure (the factory creator captures `theme`,
+ * `formatter`, `labelFormatter`, `seriesNames`, `selection`, `optionsOverride`,
+ * …), so structural and merge agree on the same widget configuration.
+ *
+ * The third arg `ctx` carries the **live** store-side formatters at the
+ * call site — distinct from the closure-time formatters because actions
+ * like RelativeData can install a percent formatter on the store after
+ * the factory was constructed. The merge phase reads from `ctx`; the
+ * structural phase typically uses the closure-time values.
+ */
+export type OptionFactory = (
+  option: echarts.EChartsOption | undefined,
+  data: unknown,
+  ctx?: OptionFactoryContext,
+) => echarts.EChartsOption
+
+export interface EchartProps {
+  /**
+   * The per-widget {@link OptionFactory}. Required — `<Widget.Echart>`
+   * derives the structural option from it (so configTransforms have a base
+   * to mutate) and fuses `state.data` into the post-pipeline option at
+   * render time. Wrap the factory creator in `useMemo` so its identity is
+   * stable across renders.
+   */
+  optionFactory: OptionFactory
+  onEvents?: Record<string, EchartsEventHandler>
+  init?: echarts.EChartsInitOpts
+  className?: string
+  /**
+   * Styles for the chart container — this is where its height comes from.
+   * `min-height` defaults to the card height (304px) and `flex: 1` lets the
+   * chart fill a taller parent; override either here, e.g.
+   * `sx={{ minHeight: 400 }}` for a taller card.
+   */
+  sx?: SxProps<Theme>
+}
+
+interface EchartSlice {
+  data: unknown
+  configTransforms: readonly Transform[]
+  formatter?: (value: number) => string
+  labelFormatter?: (value: string | number) => string | number
+}
+
+const echartSelector = (s: {
+  data: unknown
+  configTransforms: readonly Transform[]
+  formatter?: (value: number) => string
+  labelFormatter?: (value: string | number) => string | number
+}): EchartSlice => ({
+  data: s.data,
+  configTransforms: s.configTransforms,
+  formatter: s.formatter,
+  labelFormatter: s.labelFormatter,
+})
+
+/**
+ * Stateful Echart bridge — owns the entire ECharts coupling. The whole
+ * option pipeline lives here, not in the store:
+ *
+ * 1. **Structural** — `optionFactory(undefined, undefined)` produces the
+ *    theme-aware base. Memoized on the factory identity, so the consumer's
+ *    `useMemo` ID gates the rebuild.
+ * 2. **Transformed** — `applyTransforms(structural, configTransforms)`
+ *    applies any registered configTransforms (Stack/Zoom/Brush) over the
+ *    structural base. Memoized on `[structural, configTransforms]`.
+ * 3. **`replaceMerge`** — derived from the enabled configTransforms'
+ *    `replaceMergeKeys`, deduped and sorted, seeded with
+ *    {@link DEFAULT_REPLACE_MERGE}. Memoized on `[configTransforms]` so
+ *    ECharts sees a stable array reference across non-transform changes.
+ * 4. **Merge** — `optionFactory(transformed, data, ctx)` fuses post-
+ *    pipeline data into the option. Reactive `ctx` carries the live store
+ *    formatters so RelativeData's percent formatter flows through without
+ *    a structural rebuild.
+ *
+ * The `<Widget.Provider>` doesn't know about the factory at all: it stays
+ * a renderer-agnostic shell. The `ProviderProps` surface has no ECharts
+ * coupling, so non-Echart widgets don't transitively import the type.
+ */
+export function Echart({
+  optionFactory,
+  onEvents,
+  init,
+  className,
+  sx,
+}: EchartProps) {
+  const id = useWidgetId()
+  const slice = useWidgetShallow(id, echartSelector)
+
+  // Publish the live ECharts instance to the per-id registry so actions
+  // (e.g. `ZoomToggle`'s disable handler) can reach it imperatively. The
+  // callback identity is stable across renders (only `id` is in deps), so
+  // EchartUI's init effect doesn't see a fresh `onInstance` and re-init.
+  const onInstance = useCallback(
+    (chart: echarts.ECharts | null) => setEchartInstance(id, chart),
+    [id],
+  )
+
+  // Destructure so React Compiler sees specific deps instead of inferring
+  // the whole `slice` object. `useWidgetShallow` already shallow-compares
+  // the slice, so per-field deps drive each memo exactly when its inputs
+  // change.
+  const {
+    data: sliceData,
+    configTransforms,
+    formatter: sliceFormatter,
+    labelFormatter: sliceLabelFormatter,
+  } = slice
+
+  const structural = useMemo(
+    () => optionFactory(undefined, undefined),
+    [optionFactory],
+  )
+
+  const transformed = useMemo(
+    () =>
+      applyTransforms(structural, configTransforms) as echarts.EChartsOption,
+    [structural, configTransforms],
+  )
+
+  const replaceMerge = useMemo(() => {
+    const keys = new Set<string>(DEFAULT_REPLACE_MERGE)
+    for (const xf of configTransforms) {
+      if (xf.enabled && xf.replaceMergeKeys?.length) {
+        for (const k of xf.replaceMergeKeys) keys.add(k)
+      }
+    }
+    return Array.from(keys).sort()
+  }, [configTransforms])
+
+  const option = useMemo(
+    () =>
+      optionFactory(transformed, sliceData, {
+        formatter: sliceFormatter,
+        labelFormatter: sliceLabelFormatter,
+      }),
+    [
+      optionFactory,
+      transformed,
+      sliceData,
+      sliceFormatter,
+      sliceLabelFormatter,
+    ],
+  )
+
+  return (
+    <EchartUI
+      option={option}
+      replaceMerge={replaceMerge}
+      onEvents={onEvents}
+      init={init}
+      onInstance={onInstance}
+      className={className}
+      sx={sx}
+    />
+  )
+}

package/src/widgets-v2/echart/edge-label-clamp.test.ts

@@ -0,0 +1,198 @@
+import { describe, it, expect, vi } from 'vitest'
+import type { ECharts, EChartsOption } from 'echarts'
+import {
+  CENTERED,
+  clampEdgeLabels,
+  decideEdgeAlignment,
+  resolveEdgeLabels,
+} from './edge-label-clamp'
+
+const FONT = '12px sans-serif'
+
+describe('decideEdgeAlignment', () => {
+  // 'California' at 12px is ~50px wide → half ~25px. Tick offsets are chosen
+  // well below/above that so the verdict is robust to exact font metrics.
+  it("anchors 'left' when the first label overflows the left edge", () => {
+    const out = decideEdgeAlignment({
+      firstLabel: 'California',
+      lastLabel: 'X',
+      font: FONT,
+      firstTickX: 2,
+      lastTickX: 690,
+      width: 700,
+    })
+    expect(out.alignMinLabel).toBe('left')
+  })
+
+  it("anchors 'right' when the last label overflows the right edge", () => {
+    const out = decideEdgeAlignment({
+      firstLabel: 'X',
+      lastLabel: 'Wyoming',
+      font: FONT,
+      firstTickX: 350,
+      lastTickX: 698,
+      width: 700,
+    })
+    expect(out.alignMaxLabel).toBe('right')
+  })
+
+  it('leaves both centered (null) when the edge labels fit', () => {
+    const out = decideEdgeAlignment({
+      firstLabel: 'California',
+      lastLabel: 'Wyoming',
+      font: FONT,
+      firstTickX: 120,
+      lastTickX: 580,
+      width: 700,
+    })
+    expect(out).toEqual(CENTERED)
+  })
+})
+
+describe('resolveEdgeLabels', () => {
+  const barOption = (): EChartsOption =>
+    ({
+      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 EChartsOption
+
+  it('reads first/last category from the bar dataset via encode.x = name', () => {
+    const out = resolveEdgeLabels(barOption())
+    expect(out?.firstLabel).toBe('California')
+    expect(out?.lastLabel).toBe('Wyoming')
+    expect(out?.count).toBe(3)
+    expect(out?.font).toBe('12px sans-serif')
+  })
+
+  it('reads positional encode.x = 0 for the histogram tuple dataset', () => {
+    const out = resolveEdgeLabels({
+      xAxis: { type: 'category', axisLabel: {} },
+      series: [{ type: 'bar', encode: { x: 0, y: 1 }, datasetIndex: 0 }],
+      dataset: [
+        {
+          source: [
+            ['0–10', 5],
+            ['90–100', 2],
+          ],
+        },
+      ],
+    } as unknown as EChartsOption)
+    expect(out?.firstLabel).toBe('0–10')
+    expect(out?.lastLabel).toBe('90–100')
+  })
+
+  it('applies the axisLabel formatter to the category value', () => {
+    const opt = barOption() as unknown as {
+      xAxis: { axisLabel: { formatter: (v: string | number) => string } }
+    }
+    opt.xAxis.axisLabel.formatter = (v) => `[${v}]`
+    const out = resolveEdgeLabels(opt as unknown as EChartsOption)
+    expect(out?.firstLabel).toBe('[California]')
+  })
+
+  it('builds the font from axisLabel fontSize/fontFamily', () => {
+    const out = resolveEdgeLabels({
+      xAxis: {
+        type: 'category',
+        axisLabel: { fontSize: 10, fontFamily: 'Inter' },
+      },
+      series: [{ encode: { x: 'name' }, datasetIndex: 0 }],
+      dataset: [{ source: [{ name: 'A' }, { name: 'B' }] }],
+    } as unknown as EChartsOption)
+    expect(out?.font).toBe('10px Inter')
+  })
+
+  it('returns null for a non-category x-axis', () => {
+    expect(
+      resolveEdgeLabels({
+        xAxis: { type: 'value' },
+        series: [{ encode: { x: 'name' }, datasetIndex: 0 }],
+        dataset: [{ source: [{ name: 'A' }, { name: 'B' }] }],
+      } as unknown as EChartsOption),
+    ).toBeNull()
+  })
+
+  it('returns null with fewer than two categories', () => {
+    expect(resolveEdgeLabels(barOption2(['Solo']))).toBeNull()
+  })
+})
+
+function barOption2(names: string[]): EChartsOption {
+  return {
+    xAxis: { type: 'category', axisLabel: {} },
+    series: [{ encode: { x: 'name' }, datasetIndex: 0 }],
+    dataset: [{ source: names.map((name) => ({ name })) }],
+  } as unknown as EChartsOption
+}
+
+describe('clampEdgeLabels', () => {
+  const fakeChart = (firstTickX: number, lastTickX: number, width: number) => {
+    const setOption = vi.fn()
+    const chart = {
+      convertToPixel: (_finder: unknown, index: number) =>
+        index === 0 ? firstTickX : lastTickX,
+      getWidth: () => width,
+      setOption,
+    } as unknown as ECharts
+    return { chart, setOption }
+  }
+
+  const overflowOption = barOption2(['California', 'Texas', 'Wyoming'])
+
+  it('applies alignment via setOption when an edge overflows', () => {
+    const { chart, setOption } = fakeChart(2, 698, 700)
+    const result = clampEdgeLabels(chart, overflowOption, CENTERED)
+    expect(result.alignMinLabel).toBe('left')
+    expect(setOption).toHaveBeenCalledTimes(1)
+    const applied = setOption.mock.calls[0]![0] as {
+      xAxis: { axisLabel: { alignMinLabel: string | null } }
+    }
+    expect(applied.xAxis.axisLabel.alignMinLabel).toBe('left')
+  })
+
+  it('does not call setOption when the verdict matches the previous state', () => {
+    const { chart, setOption } = fakeChart(2, 698, 700)
+    const prev = {
+      alignMinLabel: 'left' as const,
+      alignMaxLabel: 'right' as const,
+    }
+    clampEdgeLabels(chart, overflowOption, prev)
+    expect(setOption).not.toHaveBeenCalled()
+  })
+
+  it('resets to centered under dataZoom (zoom guard) without measuring', () => {
+    const { chart, setOption } = fakeChart(2, 698, 700)
+    const zoomed = {
+      ...(overflowOption as object),
+      dataZoom: [{ type: 'slider' }],
+    } as unknown as EChartsOption
+    const prev = { alignMinLabel: 'left' as const, alignMaxLabel: null }
+    const result = clampEdgeLabels(chart, zoomed, prev)
+    expect(result).toEqual(CENTERED)
+    // Cleared the stale 'left' from before zoom.
+    expect(setOption).toHaveBeenCalledTimes(1)
+  })
+
+  it('leaves a non-category axis centered and untouched', () => {
+    const { chart, setOption } = fakeChart(2, 698, 700)
+    const valueAxis = {
+      xAxis: { type: 'value' },
+      series: [{ encode: { x: 'name' }, datasetIndex: 0 }],
+      dataset: [{ source: [{ name: 'A' }, { name: 'B' }] }],
+    } as unknown as EChartsOption
+    const result = clampEdgeLabels(chart, valueAxis, CENTERED)
+    expect(result).toEqual(CENTERED)
+    expect(setOption).not.toHaveBeenCalled()
+  })
+})