@carto/ps-react-ui 4.3.5 → 4.3.6

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

@@ -8,13 +8,16 @@ import { GroupedBarChartIcon } from './grouped-bar-chart-icon'
 import { getEChartStackConfig } from '../../echart/utils'
 import { DEFAULT_STACK_GROUP } from '../../echart/const'
 import type { EchartWidgetState } from '../../echart/types'
+import type { EchartOptionsProps } from '../../echart/types'
 import { useShallow } from 'zustand/shallow'
 
+export const STACK_TOGGLE_TOOL_ID = 'stack-toggle'
+
 /**
  * Widget action to toggle stacking behavior in ECharts bar and histogram widgets.
  *
- * Stores the stack state in the widget store and updates the ECharts option
- * using getEChartStackConfig to apply stacking to all series.
+ * Registers as a config pipeline tool so that stack configuration is automatically
+ * re-applied when the base config is updated (e.g., by WidgetLoader).
  *
  * @example
  * ```tsx
@@ -32,93 +35,81 @@ export function StackToggle({
   IconButtonProps,
 }: StackToggleProps) {
   const setWidget = useWidgetStore((state) => state.setWidget)
+  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 storeIsStacked = useWidgetStore(
     useShallow((state) => state.getWidget<StackToggleState>(id)?.isStacked),
   )
 
-  const getWidget = useWidgetStore((state) => state.getWidget)
-
-  /**
-   * Checks if there are multiple series in the chart
-   */
-  const hasMultiSeries = useMemo(() => {
-    const option = getWidget<EchartWidgetState>(id)?.option
-    if (!option) return false
-
-    const series = Array.isArray(option.series)
-      ? option.series
-      : [option.series]
-
-    return series.length > 1
-  }, [getWidget, id])
-
-  /**
-   * Checks if any series in the option has a stack property defined
-   */
-  const hasStackInSeries = useMemo(() => {
-    const option = getWidget<EchartWidgetState>(id)?.option
-    if (!option) return false
+  const option = useWidgetStore(
+    useShallow((state) => state.getWidget<EchartWidgetState>(id)?.option),
+  )
 
+  const { hasMultiSeries, hasStackInSeries } = useMemo(() => {
+    if (!option) return { hasMultiSeries: false, hasStackInSeries: false }
     const series = Array.isArray(option.series)
       ? option.series
       : [option.series]
-
-    return series.some((s) => (s as { stack?: string })?.stack)
-  }, [getWidget, id])
+    return {
+      hasMultiSeries: series.length > 1,
+      hasStackInSeries: series.some((s) => (s as { stack?: string })?.stack),
+    }
+  }, [option])
 
   // If series already has stack defined, default to stacked=true
   const effectiveDefaultIsStacked = hasStackInSeries || defaultIsStacked
   const isStacked = storeIsStacked ?? effectiveDefaultIsStacked
 
-  /**
-   * Updates the ECharts option with the stack configuration
-   * Preserves existing stack group names from series, falling back to DEFAULT_STACK_GROUP
-   */
-  const updateOptions = useCallback(
-    (stacked: boolean) => {
-      const option = getWidget<EchartWidgetState>(id)?.option
-
-      if (!option) return
-
-      const series = Array.isArray(option.series)
-        ? option.series
-        : [option.series]
-
-      const updatedSeries = series.map((s) => {
-        // Extract existing stack group from series, fallback to default
-        const existingStack = (s as { stack?: string })?.stack
-        const stackGroup =
-          typeof existingStack === 'string'
-            ? existingStack
-            : DEFAULT_STACK_GROUP
-
-        return {
-          ...s,
-          ...getEChartStackConfig(stacked, stackGroup),
-        }
-      })
-
-      setWidget(id, {
-        option: {
-          ...option,
-          series: updatedSeries,
-        },
-      })
-    },
-    [getWidget, id, setWidget],
-  )
+  // Register config tool on mount
+  useEffect(() => {
+    registerTool(id, {
+      id: STACK_TOGGLE_TOOL_ID,
+      type: 'config',
+      order: 10,
+      enabled: isStacked && hasMultiSeries,
+      fn: (currentConfig, toolConfig) => {
+        const config = currentConfig as Record<string, unknown>
+        const option = config.option as EchartOptionsProps | undefined
+        if (!option) return currentConfig
+
+        const stacked = (toolConfig?.stacked as boolean) ?? false
+        const series = Array.isArray(option.series)
+          ? option.series
+          : [option.series]
+        const updatedSeries = series.map((s) => {
+          const existingStack = (s as { stack?: string })?.stack
+          const stackGroup =
+            typeof existingStack === 'string'
+              ? existingStack
+              : DEFAULT_STACK_GROUP
+          return { ...s, ...getEChartStackConfig(stacked, stackGroup) }
+        })
+
+        return { ...config, option: { ...option, series: updatedSeries } }
+      },
+      config: { stacked: isStacked },
+    })
+    return () => unregisterTool(id, STACK_TOGGLE_TOOL_ID)
+  }, [id, registerTool, unregisterTool, isStacked, hasMultiSeries])
+
+  // Sync tool enabled/config when state changes
+  useEffect(() => {
+    setToolEnabled(id, STACK_TOGGLE_TOOL_ID, isStacked && hasMultiSeries)
+    updateToolConfig(id, STACK_TOGGLE_TOOL_ID, { stacked: isStacked })
+  }, [id, isStacked, hasMultiSeries, setToolEnabled, updateToolConfig])
 
   // Initialize store with default value only if not already configured
   useEffect(() => {
+    if (storeIsStacked !== undefined) return
     setWidget(id, { isStacked: effectiveDefaultIsStacked })
-  }, [effectiveDefaultIsStacked, id, setWidget])
+  }, [effectiveDefaultIsStacked, id, setWidget, storeIsStacked])
 
   const handleToggle = useCallback(() => {
-    const newIsStacked = !isStacked
-
-    setWidget(id, { isStacked: newIsStacked })
-    updateOptions(newIsStacked)
-  }, [isStacked, id, setWidget, updateOptions])
+    setWidget(id, { isStacked: !isStacked })
+  }, [isStacked, id, setWidget])
 
   const tooltipLabel = isStacked
     ? (labels?.unstacked ?? 'Disable stacking')

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/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>
 }
 
 /**

package/src/widgets/stores/widget-store.test.ts

@@ -465,6 +465,147 @@ describe('WidgetStore', () => {
     })
   })
 
+  describe('Config Tool Pipeline', () => {
+    const widgetId = 'test-widget-config'
+
+    beforeEach(() => {
+      useWidgetStore.getState().clearWidgets()
+    })
+
+    it('executes config tools and sets transformed config', async () => {
+      useWidgetStore.getState().setWidget(widgetId, {
+        type: 'bar',
+        isLoading: false,
+      })
+
+      const configTool: import('./types').ToolRegistration = {
+        id: 'stack-tool',
+        type: 'config',
+        order: 10,
+        enabled: true,
+        fn: (config) => {
+          const c = config as Record<string, unknown>
+          const option = c.option as { series?: { name: string }[] }
+          const series = option?.series ?? []
+          return {
+            ...c,
+            option: {
+              ...option,
+              series: series.map((s) => ({ ...s, stack: 'group' })),
+            },
+          }
+        },
+      }
+
+      useWidgetStore.getState().registerTool(widgetId, configTool)
+
+      await useWidgetStore.getState().executeConfigPipeline(widgetId, {
+        option: {
+          series: [{ name: 'Series 1' }, { name: 'Series 2' }],
+        },
+      })
+
+      const widget = useWidgetStore.getState().getWidget(widgetId)
+      const option = (widget as { option?: { series?: { stack?: string }[] } })
+        ?.option
+      expect(option?.series?.[0]?.stack).toBe('group')
+      expect(option?.series?.[1]?.stack).toBe('group')
+    })
+
+    it('passes base config through when no config tools registered', async () => {
+      useWidgetStore.getState().setWidget(widgetId, {
+        type: 'bar',
+        isLoading: false,
+      })
+
+      await useWidgetStore.getState().executeConfigPipeline(widgetId, {
+        option: { series: [{ name: 'Series 1' }] },
+      })
+
+      const widget = useWidgetStore.getState().getWidget(widgetId)
+      const option = (widget as { option?: { series?: { name: string }[] } })
+        ?.option
+      expect(option?.series?.[0]?.name).toBe('Series 1')
+    })
+
+    it('does not include config tools in data pipeline', async () => {
+      const executionOrder: string[] = []
+
+      useWidgetStore.getState().setWidget(widgetId, {
+        type: 'bar',
+        isLoading: false,
+      })
+
+      const dataTool: import('./types').ToolRegistration = {
+        id: 'data-tool',
+        type: 'data',
+        order: 10,
+        enabled: true,
+        fn: (data) => {
+          executionOrder.push('data-tool')
+          return data
+        },
+      }
+
+      const configTool: import('./types').ToolRegistration = {
+        id: 'config-tool',
+        type: 'config',
+        order: 10,
+        enabled: true,
+        fn: (config) => {
+          executionOrder.push('config-tool')
+          return config
+        },
+      }
+
+      useWidgetStore.getState().registerTool(widgetId, dataTool)
+      useWidgetStore.getState().registerTool(widgetId, configTool)
+
+      await useWidgetStore.getState().executeToolPipeline(widgetId, {})
+
+      expect(executionOrder).toEqual(['data-tool'])
+      expect(executionOrder).not.toContain('config-tool')
+    })
+
+    it('respects disables across tool types', async () => {
+      const executionOrder: string[] = []
+
+      useWidgetStore.getState().setWidget(widgetId, {
+        type: 'bar',
+        isLoading: false,
+      })
+
+      const configTool: import('./types').ToolRegistration = {
+        id: 'config-tool',
+        type: 'config',
+        order: 10,
+        enabled: true,
+        fn: (config) => {
+          executionOrder.push('config-tool')
+          return config
+        },
+      }
+
+      const disablerTool: import('./types').ToolRegistration = {
+        id: 'disabler',
+        type: 'data',
+        order: 10,
+        enabled: true,
+        fn: (data) => data,
+        disables: ['config-tool'],
+      }
+
+      useWidgetStore.getState().registerTool(widgetId, configTool)
+      useWidgetStore.getState().registerTool(widgetId, disablerTool)
+
+      await useWidgetStore.getState().executeConfigPipeline(widgetId, {
+        option: {},
+      })
+
+      expect(executionOrder).not.toContain('config-tool')
+    })
+  })
+
   describe('Tool Dependency Management', () => {
     const widgetId = 'test-widget-deps'