@carto/ps-react-ui 4.3.4 → 4.3.6

package/src/widgets/actions/zoom-toggle/zoom-toggle.tsx

@@ -10,11 +10,17 @@ import { styles } from './style'
 import { Tooltip } from '../../../components'
 import { getEChartZoomConfig } from '../../echart/utils'
 import type { EchartWidgetState } from '../../echart/types'
+import type { EchartOptionsProps } from '../../echart/types'
 import { useShallow } from 'zustand/shallow'
 
+export const ZOOM_TOGGLE_TOOL_ID = 'zoom-toggle'
+
 /**
  * Widget action to toggle EChart zoom functionality.
  *
+ * Registers as a config pipeline tool so that zoom configuration is automatically
+ * re-applied when the base config is updated (e.g., by WidgetLoader).
+ *
  * When zoom is active, displays an inline reset button to disable zoom.
  * Only intended for use in fullscreen ToolbarActions for bar and histogram widgets.
  *
@@ -41,6 +47,10 @@ export function ZoomToggle({
   const theme = useTheme()
   const setWidget = useWidgetStore((state) => state.setWidget)
   const getWidget = useWidgetStore((state) => state.getWidget)
+  const registerTool = useWidgetStore((state) => state.registerTool)
+  const unregisterTool = useWidgetStore((state) => state.unregisterTool)
+  const setToolEnabled = useWidgetStore((state) => state.setToolEnabled)
+  const updateToolConfig = useWidgetStore((state) => state.updateToolConfig)
 
   const zoom = useWidgetStore(
     useShallow((state) => {
@@ -49,76 +59,94 @@ export function ZoomToggle({
     }),
   )
 
-  const updateZoomOption = useCallback(
-    (enabled: boolean, start: number, end: number) => {
-      const zoomConfig = getEChartZoomConfig(
-        enabled,
-        { start, end },
-        { inside: true, xSlider: true, ySlider: false },
-        theme,
-      )
-      const currentOption = getWidget<EchartWidgetState>(id)?.option
-
-      setWidget<EchartWidgetState & ZoomState>(id, {
-        zoom: enabled,
-        zoomStart: start,
-        zoomEnd: end,
-        option: {
-          ...currentOption,
-          ...zoomConfig,
-        },
-      })
-    },
-    [getWidget, id, setWidget, theme],
+  const zoomStart = useWidgetStore(
+    useShallow((state) => {
+      const widget = state.getWidget<ZoomState>(id)
+      return widget?.zoomStart ?? defaultZoomStart
+    }),
+  )
+
+  const zoomEnd = useWidgetStore(
+    useShallow((state) => {
+      const widget = state.getWidget<ZoomState>(id)
+      return widget?.zoomEnd ?? defaultZoomEnd
+    }),
   )
 
+  // Register config tool on mount
+  useEffect(() => {
+    registerTool(id, {
+      id: ZOOM_TOGGLE_TOOL_ID,
+      type: 'config',
+      order: 20,
+      enabled: zoom,
+      fn: (currentConfig, toolConfig) => {
+        const config = currentConfig as Record<string, unknown>
+        const option = config.option as EchartOptionsProps | undefined
+        const enabled = (toolConfig?.enabled as boolean) ?? false
+        const start = (toolConfig?.start as number) ?? 0
+        const end = (toolConfig?.end as number) ?? 100
+
+        const zoomConfig = getEChartZoomConfig(
+          enabled,
+          { start, end },
+          { inside: true, xSlider: true, ySlider: false },
+          theme,
+        )
+        return { ...config, option: { ...option, ...zoomConfig } }
+      },
+      config: { enabled: zoom, start: zoomStart, end: zoomEnd },
+    })
+    return () => unregisterTool(id, ZOOM_TOGGLE_TOOL_ID)
+  }, [id, registerTool, unregisterTool, zoom, theme, zoomStart, zoomEnd])
+
+  // Sync tool enabled/config when state changes
+  useEffect(() => {
+    setToolEnabled(id, ZOOM_TOGGLE_TOOL_ID, zoom)
+    updateToolConfig(id, ZOOM_TOGGLE_TOOL_ID, {
+      enabled: zoom,
+      start: zoomStart,
+      end: zoomEnd,
+    })
+  }, [id, zoom, zoomStart, zoomEnd, setToolEnabled, updateToolConfig])
+
   // Initialize zoom state from defaults only if not already set
   useEffect(() => {
     const existingState = getWidget<ZoomState>(id)
 
     if (existingState?.zoom) return
 
-    // Apply initial zoom config
-    updateZoomOption(
-      existingState?.zoom ?? defaultZoom,
-      existingState?.zoomStart ?? defaultZoomStart,
-      existingState?.zoomEnd ?? defaultZoomEnd,
-    )
-  }, [
-    defaultZoom,
-    defaultZoomEnd,
-    defaultZoomStart,
-    getWidget,
-    id,
-    updateZoomOption,
-  ])
-
-  // Cleanup: reset zoom when component unmounts
+    setWidget<ZoomState>(id, {
+      zoom: existingState?.zoom ?? defaultZoom,
+      zoomStart: existingState?.zoomStart ?? defaultZoomStart,
+      zoomEnd: existingState?.zoomEnd ?? defaultZoomEnd,
+    })
+  }, [defaultZoom, defaultZoomEnd, defaultZoomStart, getWidget, id, setWidget])
+
+  // Cleanup: disable zoom when component unmounts
   useEffect(() => {
     return () => {
-      const existingState = getWidget<ZoomState>(id)
-      updateZoomOption(
-        false,
-        existingState?.zoomStart ?? 0,
-        existingState?.zoomEnd ?? 100,
-      )
+      setWidget<ZoomState>(id, { zoom: false })
     }
-  }, [getWidget, id, updateZoomOption])
+  }, [id, setWidget])
 
   const handleToggle = () => {
     const newZoom = !zoom
-
     const existingState = getWidget<ZoomState>(id)
 
-    updateZoomOption(
-      newZoom,
-      newZoom ? (existingState?.zoomStart ?? defaultZoomStart) : 0,
-      newZoom ? (existingState?.zoomEnd ?? defaultZoomEnd) : 100,
-    )
+    setWidget<ZoomState>(id, {
+      zoom: newZoom,
+      zoomStart: newZoom ? (existingState?.zoomStart ?? defaultZoomStart) : 0,
+      zoomEnd: newZoom ? (existingState?.zoomEnd ?? defaultZoomEnd) : 100,
+    })
   }
 
   const handleReset = () => {
-    updateZoomOption(true, defaultZoomStart, defaultZoomEnd)
+    setWidget<ZoomState>(id, {
+      zoom: true,
+      zoomStart: defaultZoomStart,
+      zoomEnd: defaultZoomEnd,
+    })
   }
 
   // Handle dataZoom event to update zoom range in store
@@ -133,10 +161,14 @@ export function ZoomToggle({
       const end = zoomEvent.end
 
       if (start !== undefined && end !== undefined) {
-        updateZoomOption(true, start, end)
+        setWidget<ZoomState>(id, {
+          zoom: true,
+          zoomStart: start,
+          zoomEnd: end,
+        })
       }
     },
-    [updateZoomOption],
+    [id, setWidget],
   )
 
   // Register dataZoom event handler when zoom is enabled

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

@@ -175,6 +175,7 @@ describe('EchartUI', () => {
 
     expect(mockChart.setOption).toHaveBeenCalledWith(basicOption, {
       lazyUpdate: true,
+      replaceMerge: ['dataset', 'series'],
     })
   })
 
@@ -199,6 +200,22 @@ describe('EchartUI', () => {
 
     expect(mockChart.setOption).toHaveBeenCalledWith(newOption, {
       lazyUpdate: true,
+      replaceMerge: ['dataset', 'series'],
+    })
+  })
+
+  test('uses provided replaceMerge values', () => {
+    render(
+      <EchartUI
+        {...defaultProps}
+        option={basicOption}
+        replaceMerge={['series']}
+      />,
+    )
+
+    expect(mockChart.setOption).toHaveBeenCalledWith(basicOption, {
+      lazyUpdate: true,
+      replaceMerge: ['series'],
     })
   })
 
@@ -479,6 +496,7 @@ describe('EchartUI', () => {
 
     expect(mockChart.setOption).toHaveBeenCalledWith(complexOption, {
       lazyUpdate: true,
+      replaceMerge: ['dataset', 'series'],
     })
   })
 

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

@@ -3,15 +3,14 @@ import * as echarts from 'echarts'
 import type { EchartUIProps } from './types'
 import { useWidgetRef } from '../../hooks'
 
-export function EchartUI({
-  id,
-  ref,
-  init,
-  option,
-  className,
-  style,
-  onEvents,
-}: EchartUIProps) {
+const DEFAULT_REPLACE_MERGE: string[] = ['dataset', 'series']
+
+export function EchartUI(props: EchartUIProps) {
+  const { id, ref, init, option, className, style, onEvents } = props
+  const replaceMerge = toReplaceMerge(
+    (props as { replaceMerge?: unknown }).replaceMerge,
+  )
+
   const chartRef = useWidgetRef<HTMLDivElement>(id)
   const chartInstance = useRef<echarts.ECharts>(null)
   const resizeObserverRef = useRef<ResizeObserver | null>(null)
@@ -35,11 +34,16 @@ export function EchartUI({
 
   // Update chart when options change
   useEffect(() => {
-    chartInstance.current?.setOption(option, {
+    const setOptionConfig = {
       lazyUpdate: true,
-      // notMerge: true,
-    })
-  }, [option])
+      replaceMerge: replaceMerge ?? DEFAULT_REPLACE_MERGE,
+    }
+
+    chartInstance.current?.setOption(
+      option,
+      setOptionConfig as Parameters<echarts.ECharts['setOption']>[1],
+    )
+  }, [option, replaceMerge])
 
   // Handle resize using ResizeObserver
   useEffect(() => {
@@ -78,3 +82,11 @@ export function EchartUI({
 
   return <div id={id} ref={chartRef} style={style} className={className} />
 }
+
+function toReplaceMerge(value: unknown): string[] | undefined {
+  if (!Array.isArray(value)) {
+    return undefined
+  }
+
+  return value.filter((item): item is string => typeof item === 'string')
+}

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

@@ -184,6 +184,7 @@ describe('Echart', () => {
       }),
       {
         lazyUpdate: true,
+        replaceMerge: ['dataset', 'series'],
       },
     )
   })
@@ -276,6 +277,7 @@ describe('Echart', () => {
 
     expect(mockChart.setOption).toHaveBeenCalledWith(basicOption, {
       lazyUpdate: true,
+      replaceMerge: ['dataset', 'series'],
     })
 
     const newOption: EChartsOption = {
@@ -297,6 +299,7 @@ describe('Echart', () => {
 
     expect(mockChart.setOption).toHaveBeenCalledWith(newOption, {
       lazyUpdate: true,
+      replaceMerge: ['dataset', 'series'],
     })
   })
 
@@ -364,6 +367,7 @@ describe('Echart', () => {
 
     expect(mockChart.setOption).toHaveBeenCalledWith(complexOption, {
       lazyUpdate: true,
+      replaceMerge: ['dataset', 'series'],
     })
   })
 
@@ -400,6 +404,7 @@ describe('Echart', () => {
     )
     expect(mockChart.setOption).toHaveBeenCalledWith(basicOption, {
       lazyUpdate: true,
+      replaceMerge: ['dataset', 'series'],
     })
     expect(mockChart.on).toHaveBeenCalledWith('click', clickHandler)
   })
@@ -442,6 +447,7 @@ describe('Echart', () => {
 
     expect(mockChart.setOption).toHaveBeenCalledWith(emptyOption, {
       lazyUpdate: true,
+      replaceMerge: ['dataset', 'series'],
     })
   })
 
@@ -464,6 +470,7 @@ describe('Echart', () => {
       }),
       {
         lazyUpdate: true,
+        replaceMerge: ['dataset', 'series'],
       },
     )
   })
@@ -509,6 +516,7 @@ describe('Echart', () => {
 
     expect(mockChart.setOption).toHaveBeenCalledWith(basicOption, {
       lazyUpdate: true,
+      replaceMerge: ['dataset', 'series'],
     })
 
     rerender(<Echart id='chart-b' />)
@@ -517,10 +525,27 @@ describe('Echart', () => {
       { series: [{ type: 'line', data: [1, 2, 3] }] },
       {
         lazyUpdate: true,
+        replaceMerge: ['dataset', 'series'],
       },
     )
   })
 
+  test('passes replaceMerge from widget to EchartUI', () => {
+    useWidgetStore.getState().setWidget('test-echart', {
+      id: 'test-echart',
+      type: 'echart',
+      option: basicOption,
+      replaceMerge: ['series'],
+    } as EchartWidgetState)
+
+    render(<Echart id='test-echart' />)
+
+    expect(mockChart.setOption).toHaveBeenCalledWith(basicOption, {
+      lazyUpdate: true,
+      replaceMerge: ['series'],
+    })
+  })
+
   test('disposes chart when component unmounts', () => {
     useWidgetStore.getState().setWidget('test-echart', {
       id: 'test-echart',

package/src/widgets/echart/echart.tsx

@@ -19,6 +19,7 @@ export function Echart(props: EchartProps) {
         option: widget?.option,
         onEvents: widget?.onEvents,
         init: widget?.init,
+        replaceMerge: widget?.replaceMerge,
       }
     }),
   )
@@ -36,9 +37,16 @@ export function Echart(props: EchartProps) {
 
   const onEvents = widget.onEvents
   const init = widget.init
+  const replaceMerge = widget.replaceMerge
 
   return (
-    <EchartUI id={props.id} option={option} onEvents={onEvents} init={init} />
+    <EchartUI
+      id={props.id}
+      option={option}
+      onEvents={onEvents}
+      init={init}
+      replaceMerge={replaceMerge}
+    />
   )
 }
 

package/src/widgets/echart/types.ts

@@ -5,12 +5,14 @@ import type { Ref } from 'react'
 import { theme as CartoTheme } from '@carto/meridian-ds/theme'
 
 export type EchartOptionsProps = EChartsOption
+export type EchartReplaceMerge = string[]
 
 export interface EchartUIProps {
   id: string
   option: EchartOptionsProps
   className?: string
   init?: echarts.EChartsInitOpts
+  replaceMerge?: EchartReplaceMerge
   style?: React.CSSProperties
   ref?: Ref<echarts.ECharts>
   onEvents?: Record<string, Parameters<echarts.ECharts['on']>[2]>
@@ -26,6 +28,7 @@ export type EchartWidgetState = BaseWidgetState<{
   option: EchartUIProps['option']
   onEvents?: EchartUIProps['onEvents']
   init?: EchartUIProps['init']
+  replaceMerge?: EchartReplaceMerge
 }>
 
 export interface EchartWidgetOptionProps<D> {
@@ -38,4 +41,5 @@ export interface EchartWidgetProps {
   type: string
   option: EchartUIProps['option']
   onEvents?: EchartUIProps['onEvents']
+  replaceMerge?: EchartReplaceMerge
 }

package/src/widgets/loader/loader.tsx

@@ -3,11 +3,14 @@ import type { WidgetLoaderProps } from './types'
 import { useWidgetStore } from '../stores/widget-store'
 import type { WrapperState } from '../wrapper'
 
-export function WidgetLoader<T>(props: WidgetLoaderProps<T>) {
+export function WidgetLoader<T extends Record<string, unknown> = Record<string, unknown>>(props: WidgetLoaderProps<T>) {
   const setWidget = useWidgetStore((state) => state.setWidget)
   const executeToolPipeline = useWidgetStore(
     (state) => state.executeToolPipeline,
   )
+  const executeConfigPipeline = useWidgetStore(
+    (state) => state.executeConfigPipeline,
+  )
 
   // Split into 3 effects for metadata and 1 for data pipeline:
   // Each property that can be modified independently gets its own effect to avoid
@@ -35,21 +38,19 @@ export function WidgetLoader<T>(props: WidgetLoaderProps<T>) {
     })
   }, [props.id, props.isLoading, props.isFetching, props.error, setWidget])
 
-  // Effect 3: Config updates
+  // Effect 3: Config updates — run through config pipeline
   useEffect(() => {
     if (props.config) {
-      setWidget<WrapperState>(props.id, {
-        ...props.config,
-      })
+      void executeConfigPipeline(props.id, props.config)
     }
-  }, [props.id, props.config, setWidget])
+  }, [props.id, props.config, executeConfigPipeline])
 
   // Effect 4: Execute tool pipeline when props.data changes
   useEffect(() => {
     void executeToolPipeline(props.id, props.data)
   }, [props.id, props.data, executeToolPipeline])
 
-  // Effect 5: Re-execute pipeline when tool state changes (enabled/config)
+  // Effect 5: Re-execute pipelines when tool state changes (enabled/config)
   useEffect(() => {
     let prevTools = useWidgetStore.getState().widgets[props.id]?.registeredTools
 
@@ -60,11 +61,20 @@ export function WidgetLoader<T>(props: WidgetLoaderProps<T>) {
       if (currentTools !== prevTools) {
         prevTools = currentTools
         void executeToolPipeline(props.id, props.data)
+        if (props.config) {
+          void executeConfigPipeline(props.id, props.config)
+        }
       }
     })
 
     return unsubscribe
-  }, [props.id, props.data, executeToolPipeline])
+  }, [
+    props.id,
+    props.data,
+    props.config,
+    executeToolPipeline,
+    executeConfigPipeline,
+  ])
 
   return props.children
 }

package/src/widgets/loader/types.ts

@@ -1,7 +1,7 @@
 import type { ReactNode } from 'react'
 import type { WidgetsStoreProps, WidgetState } from '../stores/types'
 
-export interface WidgetLoaderProps<T> extends WidgetsStoreProps {
+export interface WidgetLoaderProps<T extends Record<string, unknown> = Record<string, unknown>> extends WidgetsStoreProps {
   children: ReactNode
   config?: T
 }

package/src/widgets/stores/index.ts

@@ -1,6 +1,7 @@
 export { useWidgetStore } from './widget-store'
 export type {
   BaseWidgetState,
+  ToolType,
   WidgetsStoreProps,
   WidgetState,
   WidgetStore,

package/src/widgets/stores/types.ts

@@ -1,5 +1,12 @@
 import type { RefObject } from 'react'
 
+/**
+ * Tool type determines which pipeline a tool participates in.
+ * - 'data': transforms widget data (default)
+ * - 'config': transforms widget config/option
+ */
+export type ToolType = 'data' | 'config'
+
 export interface WidgetsStoreProps {
   /** Unique identifier for the widget */
   id: string
@@ -77,6 +84,8 @@ export interface ToolRegistration {
   fn: ToolTransformFunction
   /** Whether tool is currently enabled */
   enabled: boolean
+  /** 'data' (default) transforms data, 'config' transforms widget config/option */
+  type?: ToolType
   /** Tool-specific configuration */
   config?: Record<string, unknown>
   /**
@@ -184,6 +193,17 @@ export interface WidgetStoreActions {
    * @param sourceData - Original data to transform
    */
   executeToolPipeline: (widgetId: string, sourceData: unknown) => Promise<void>
+
+  /**
+   * Execute the config transformation pipeline
+   * Applies config-type tools to the base config, then sets the result on the widget
+   * @param widgetId - Widget ID
+   * @param baseConfig - Base config to transform
+   */
+  executeConfigPipeline: (
+    widgetId: string,
+    baseConfig: Record<string, unknown>,
+  ) => Promise<void>
 }
 
 /**