@carto/ps-react-ui 4.4.3 → 4.5.1

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

@@ -604,6 +604,87 @@ describe('WidgetStore', () => {
 
       expect(executionOrder).not.toContain('config-tool')
     })
+
+    it('should not overwrite user-modified state when config lacks that property', async () => {
+      useWidgetStore.getState().setWidget(widgetId, {
+        type: 'table',
+        isLoading: false,
+      })
+
+      // Apply initial config (without selected — clean config pattern)
+      await useWidgetStore.getState().executeConfigPipeline(widgetId, {
+        columns: [],
+        selectable: true,
+        mode: 'local',
+      })
+
+      // Simulate user selecting rows via UI action
+      useWidgetStore.getState().setWidget(widgetId, {
+        selected: [1, 2, 3],
+      })
+
+      // Re-run config pipeline (e.g., triggered by tool registration or data change)
+      await useWidgetStore.getState().executeConfigPipeline(widgetId, {
+        columns: [],
+        selectable: true,
+        mode: 'local',
+      })
+
+      // Selection should be preserved — config doesn't include 'selected'
+      const widget = useWidgetStore.getState().getWidget(widgetId)
+      expect((widget as { selected?: (string | number)[] }).selected).toEqual([
+        1, 2, 3,
+      ])
+    })
+
+    it('should not overwrite user-modified state when a tool passes base config through unchanged', async () => {
+      const baseConfig = {
+        option: { series: [{ name: 'A' }] },
+        selected: [] as number[],
+      }
+
+      useWidgetStore.getState().setWidget(widgetId, {
+        type: 'bar',
+        isLoading: false,
+      })
+
+      // Register a config tool that only changes `option` but spreads
+      // the entire base config (the typical { ...config, option: modified } pattern)
+      useWidgetStore.getState().registerTool(widgetId, {
+        id: 'stack-tool',
+        type: 'config',
+        order: 10,
+        enabled: true,
+        fn: (config: unknown) => {
+          const c = config as typeof baseConfig
+          return { ...c, option: { series: [{ name: 'A', stack: 'group' }] } }
+        },
+      })
+
+      // Initial pipeline sets option and selected
+      await useWidgetStore
+        .getState()
+        .executeConfigPipeline(widgetId, baseConfig)
+
+      // Simulate user modifying selected via UI
+      useWidgetStore.getState().setWidget(widgetId, { selected: [1, 2] })
+
+      // Re-run pipeline — tool still only changes `option`,
+      // but spreads { ...config, option: modified } which includes selected: []
+      await useWidgetStore
+        .getState()
+        .executeConfigPipeline(widgetId, baseConfig)
+
+      const widget = useWidgetStore.getState().getWidget(widgetId) as {
+        selected?: number[]
+        option?: { series?: { stack?: string }[] }
+      }
+
+      // Tool's change should be applied
+      expect(widget.option?.series?.[0]?.stack).toBe('group')
+      // User's selection should be preserved — the tool didn't change `selected`
+      expect(widget.selected).toEqual([1, 2])
+    })
   })
 
   describe('Tool Dependency Management', () => {

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

@@ -1,5 +1,10 @@
 import { create } from 'zustand'
-import type { WidgetState, WidgetStore, ToolRegistration } from './types'
+import type {
+  WidgetState,
+  WidgetStore,
+  ToolRegistration,
+  WidgetStoreActions,
+} from './types'
 
 // Track active pipeline executions for cancellation
 const activePipelines = new Map<string, number>()
@@ -8,38 +13,40 @@ const activeConfigPipelines = new Map<string, number>()
 /**
  * Zustand store for managing widget state across the application.
  *
- * This store provides centralized state management for all widget UI components
+ * Provides centralized state management for all widget UI components, including
+ * data/config transformation pipelines via registered tools.
  *
- * @example
- * ```tsx
- * // Import the store
- * import { useWidgetStore } from '@carto/ps-react-ui/widgets'
+ * **Performance optimizations:**
+ * - `registerTool` skips the store update when structural properties (order, enabled,
+ *   type, disables) haven't changed — only `fn` and `config` are updated via direct
+ *   mutation, avoiding a new `registeredTools` array reference and WidgetLoader
+ *   pipeline cascades.
+ * - `setToolEnabled` skips the store update when the enabled state is already the
+ *   requested value.
+ * - `executeToolPipeline` / `executeConfigPipeline` skip the final `set()` when
+ *   the transformed data/config is referentially identical to what's already in the store.
+ * - Both pipelines support cancellation — newer executions for the same widget
+ *   automatically cancel in-progress ones.
  *
- * // Use in a component
- * function MyWidget() {
- *   const setWidget = useWidgetStore((state) => state.setWidget)
- *   const widget = useWidgetStore((state) => state.widgets['my-widget'])
- *
- *   useEffect(() => {
- *     setWidget({
- *       id: 'my-widget',
- *       type: 'formula',
- *       title: 'Total Sales',
- *       isLoading: false,
- *       visible: true,
- *       data: { value: 1000, prefix: '$' }
- *     })
- *   }, [setWidget])
+ * @example Reading widget state (prefer useWidgetSelector for performance)
+ * ```tsx
+ * import { useWidgetSelector } from '@carto/ps-react-ui/widgets'
  *
- *   return <div>{widget?.data?.value}</div>
+ * function MyWidget({ id }: { id: string }) {
+ *   const { title, data } = useWidgetSelector(id, (w) => ({
+ *     title: w?.title,
+ *     data: w?.data,
+ *   }))
+ *   return <div>{title}: {JSON.stringify(data)}</div>
  * }
  * ```
  *
- * @example
+ * @example Writing widget state
  * ```tsx
- * // Get widgets by type
- * const getWidgetsByType = useWidgetStore((state) => state.getWidgetsByType)
- * const formulaWidgets = getWidgetsByType('formula')
+ * import { widgetStoreActions } from '@carto/ps-react-ui/widgets'
+ *
+ * const { setWidget } = widgetStoreActions
+ * setWidget('my-widget', { type: 'formula', isLoading: false, data: { value: 1000 } })
  * ```
  */
 export const useWidgetStore = create<WidgetStore>()((set, get) => ({
@@ -47,21 +54,23 @@ export const useWidgetStore = create<WidgetStore>()((set, get) => ({
   widgets: {},
 
   // Actions
-  setWidget: (id, widget) =>
+
+  /** Merges partial state into the widget entry. Creates the widget if it doesn't exist. */
+  setWidget: (id, widget) => {
     set((state) => {
-      const current =
-        state.widgets[id] ?? ({} as WidgetStore['widgets'][string])
+      const prev = state.widgets[id] ?? ({} as WidgetStore['widgets'][string])
       return {
         widgets: {
           ...state.widgets,
           [id]: {
-            ...current,
+            ...prev,
             ...widget,
             id,
           },
         },
       }
-    }),
+    })
+  },
 
   removeWidget: (id) =>
     set((state) => {
@@ -81,10 +90,37 @@ export const useWidgetStore = create<WidgetStore>()((set, get) => ({
     return get().widgets[id] as T | undefined
   },
 
-  registerTool: (widgetId: string, tool: ToolRegistration) =>
+  /**
+   * Registers a transformation tool for a widget's data or config pipeline.
+   *
+   * **No-op optimization:** When a tool with the same `id` already exists and its
+   * structural properties (`order`, `enabled`, `type`, `disables`) are unchanged,
+   * only `fn` and `config` are updated via direct mutation — no store update is
+   * triggered. This allows action components to include all reactive dependencies
+   * in their `useEffect` arrays without causing WidgetLoader pipeline cascades.
+   */
+  registerTool: (widgetId: string, tool: ToolRegistration) => {
+    const current = get().widgets[widgetId]
+    const existingTool = current?.registeredTools?.find(
+      (t: ToolRegistration) => t.id === tool.id,
+    )
+
+    // No-op: structural properties unchanged — update fn/config via direct mutation.
+    // Safe because fn and config are only consumed imperatively during pipeline execution.
+    if (
+      existingTool?.order === tool.order &&
+      existingTool.enabled === tool.enabled &&
+      existingTool.type === tool.type &&
+      existingTool.disables === tool.disables
+    ) {
+      existingTool.fn = tool.fn
+      if (tool.config) existingTool.config = tool.config
+      return
+    }
+
     set((state) => {
-      const current = state.widgets[widgetId] ?? ({} as WidgetState)
-      const registeredTools = current.registeredTools ?? []
+      const widget = state.widgets[widgetId] ?? ({} as WidgetState)
+      const registeredTools = widget.registeredTools ?? []
 
       // Remove existing tool with same id if present
       const filteredTools = registeredTools.filter(
@@ -95,13 +131,14 @@ export const useWidgetStore = create<WidgetStore>()((set, get) => ({
         widgets: {
           ...state.widgets,
           [widgetId]: {
-            ...current,
+            ...widget,
             id: widgetId,
             registeredTools: [...filteredTools, tool],
           },
         },
       }
-    }),
+    })
+  },
 
   unregisterTool: (widgetId: string, toolId: string) =>
     set((state) => {
@@ -154,12 +191,26 @@ export const useWidgetStore = create<WidgetStore>()((set, get) => ({
       }
     }),
 
-  setToolEnabled: (widgetId: string, toolId: string, enabled: boolean) =>
+  /**
+   * Updates a tool's enabled state.
+   *
+   * **No-op optimization:** Skips the store update if the tool already has the
+   * requested enabled value.
+   */
+  setToolEnabled: (widgetId: string, toolId: string, enabled: boolean) => {
+    const current = get().widgets[widgetId]
+    if (current) {
+      const tool = current.registeredTools?.find(
+        (t: ToolRegistration) => t.id === toolId,
+      )
+      if (tool?.enabled === enabled) return
+    }
+
     set((state) => {
-      const current = state.widgets[widgetId]
-      if (!current) return state
+      const widget = state.widgets[widgetId]
+      if (!widget) return state
 
-      const registeredTools = current.registeredTools ?? []
+      const registeredTools = widget.registeredTools ?? []
       const updatedTools = registeredTools.map((tool: ToolRegistration) =>
         tool.id === toolId ? { ...tool, enabled } : tool,
       )
@@ -168,13 +219,26 @@ export const useWidgetStore = create<WidgetStore>()((set, get) => ({
         widgets: {
           ...state.widgets,
           [widgetId]: {
-            ...current,
+            ...widget,
             registeredTools: updatedTools,
           },
         },
       }
-    }),
+    })
+  },
 
+  /**
+   * Executes the data transformation pipeline for a widget.
+   *
+   * Filters to enabled data-type tools (respecting `disables`), sorts by `order`,
+   * and chains their `fn` calls. Supports async tools.
+   *
+   * **Cancellation:** Newer executions for the same widget automatically cancel
+   * in-progress ones via a version counter.
+   *
+   * **No-op optimization:** Skips the final `set()` if the transformed data is
+   * referentially identical (`Object.is`) to what's already in the store.
+   */
   executeToolPipeline: async (widgetId: string, sourceData: unknown) => {
     const widget = get().widgets[widgetId]
     if (!widget) return
@@ -221,6 +285,15 @@ export const useWidgetStore = create<WidgetStore>()((set, get) => ({
       }
     }
 
+    // Skip store update if data hasn't changed (e.g., passthrough pipeline with no tools)
+    const widgetAfter = get().widgets[widgetId]
+    if (widgetAfter && Object.is(widgetAfter.data, transformedData)) {
+      if (activePipelines.get(widgetId) === currentExecution) {
+        activePipelines.delete(widgetId)
+      }
+      return
+    }
+
     // Single store update with final transformed data
     set((state) => {
       const currentWidget = state.widgets[widgetId]
@@ -243,6 +316,18 @@ export const useWidgetStore = create<WidgetStore>()((set, get) => ({
     }
   },
 
+  /**
+   * Executes the config transformation pipeline for a widget.
+   *
+   * Filters to enabled config-type tools (respecting `disables`), sorts by `order`,
+   * and chains their `fn` calls. The transformed config is spread into the widget state.
+   *
+   * **Cancellation:** Newer executions for the same widget automatically cancel
+   * in-progress ones via a version counter.
+   *
+   * **No-op optimization:** Skips the final `set()` when the config object is unchanged
+   * and all its properties already match what's in the store.
+   */
   executeConfigPipeline: async (widgetId: string, baseConfig: object) => {
     const widget = get().widgets[widgetId]
     if (!widget) return
@@ -287,7 +372,50 @@ export const useWidgetStore = create<WidgetStore>()((set, get) => ({
       }
     }
 
-    // Set the transformed config into the widget
+    // Build a patch that only includes properties the pipeline should set.
+    // A property is applied when:
+    //   1. A config tool explicitly changed it (transformedConfig[k] !== baseConfig[k])
+    //   2. First pipeline run for this widget (no _lastConfig yet)
+    //   3. The widget value still matches what the pipeline last set — meaning the
+    //      user hasn't modified it via setWidget, so it's safe to overwrite.
+    // A property is SKIPPED when the widget value differs from _lastConfig,
+    // meaning the user (or a hook) changed it since the last pipeline run.
+    const base = baseConfig as Record<string, unknown>
+    const result = transformedConfig as Record<string, unknown>
+    const widgetNow = get().widgets[widgetId] as unknown as Record<
+      string,
+      unknown
+    >
+    const lastConfig = widgetNow?._lastConfig as
+      | Record<string, unknown>
+      | undefined
+
+    const patch: Record<string, unknown> = {}
+    for (const key of Object.keys(result)) {
+      const toolChanged = !Object.is(result[key], base[key])
+      const isFirstRun = !lastConfig || !(key in lastConfig)
+      const userUnmodified =
+        !isFirstRun && Object.is(widgetNow[key], lastConfig[key])
+
+      if (toolChanged || isFirstRun || userUnmodified) {
+        patch[key] = result[key]
+      }
+    }
+
+    // Skip store update if every patch value already matches the widget
+    const hasChanges = Object.keys(patch).some(
+      (k) => !Object.is(widgetNow?.[k], patch[k]),
+    )
+    const configRefChanged = !Object.is(transformedConfig, lastConfig)
+
+    if (!hasChanges && !configRefChanged) {
+      if (activeConfigPipelines.get(widgetId) === currentExecution) {
+        activeConfigPipelines.delete(widgetId)
+      }
+      return
+    }
+
+    // Apply the patch and store the pipeline output for next run's comparison
     set((state) => {
       const currentWidget = state.widgets[widgetId]
       if (!currentWidget) return state
@@ -297,7 +425,8 @@ export const useWidgetStore = create<WidgetStore>()((set, get) => ({
           ...state.widgets,
           [widgetId]: {
             ...currentWidget,
-            ...(transformedConfig as Record<string, unknown>),
+            ...patch,
+            _lastConfig: transformedConfig,
           },
         },
       }
@@ -308,3 +437,55 @@ export const useWidgetStore = create<WidgetStore>()((set, get) => ({
     }
   },
 }))
+
+/**
+ * Stable references to store actions, accessible without creating a subscription.
+ *
+ * Use this instead of `useWidgetStore((state) => state.setWidget)` to avoid
+ * unnecessary subscriber evaluations. Actions are stable functions that never
+ * change, so subscribing to them wastes cycles on every store update.
+ *
+ * @example
+ * ```tsx
+ * import { widgetStoreActions } from '@carto/ps-react-ui/widgets'
+ *
+ * const { setWidget, registerTool } = widgetStoreActions
+ *
+ * useEffect(() => {
+ *   registerTool(id, { id: 'my-tool', order: 10, enabled: true, fn: (d) => d })
+ *   return () => widgetStoreActions.unregisterTool(id, 'my-tool')
+ * }, [id])
+ * ```
+ */
+export const widgetStoreActions: WidgetStoreActions = {
+  get setWidget() {
+    return useWidgetStore.getState().setWidget
+  },
+  get removeWidget() {
+    return useWidgetStore.getState().removeWidget
+  },
+  get clearWidgets() {
+    return useWidgetStore.getState().clearWidgets
+  },
+  get getWidget() {
+    return useWidgetStore.getState().getWidget
+  },
+  get registerTool() {
+    return useWidgetStore.getState().registerTool
+  },
+  get unregisterTool() {
+    return useWidgetStore.getState().unregisterTool
+  },
+  get updateToolConfig() {
+    return useWidgetStore.getState().updateToolConfig
+  },
+  get setToolEnabled() {
+    return useWidgetStore.getState().setToolEnabled
+  },
+  get executeToolPipeline() {
+    return useWidgetStore.getState().executeToolPipeline
+  },
+  get executeConfigPipeline() {
+    return useWidgetStore.getState().executeConfigPipeline
+  },
+} as WidgetStoreActions

package/src/widgets/subheader/subheader.tsx

@@ -19,9 +19,17 @@ export function WidgetSubHeader({
   sx,
 }: WidgetSubHeaderProps) {
   return (
-    <Box sx={{ ...styles.root, ...sx }}>
-      {slotLeft && <Box sx={styles.slotLeft}>{slotLeft}</Box>}
-      <Box sx={styles.slotRight}>{slotRight}</Box>
+    <Box sx={{ ...styles.root, ...sx }} className='widget-subheader'>
+      {slotLeft && (
+        <Box sx={styles.slotLeft} className='widget-subheader-slot-left'>
+          {slotLeft}
+        </Box>
+      )}
+      {slotRight && (
+        <Box sx={styles.slotRight} className='widget-subheader-slot-right'>
+          {slotRight}
+        </Box>
+      )}
     </Box>
   )
 }

package/src/widgets/table/config.ts

@@ -70,7 +70,6 @@ export function tableConfig(columns: TableColumn[] = []): TableWidgetConfig {
   return {
     columns,
     selectable: false,
-    selected: [],
     mode: DEFAULT_MODE,
   }
 }

package/src/widgets/table/hooks/use-pagination.ts

@@ -1,8 +1,8 @@
 import { useCallback, useMemo } from 'react'
 import type { TableRow, TableWidgetState } from '../types'
 import { paginateData } from '../helpers'
-import { useWidgetStore } from '../../stores/widget-store'
-import { useShallow } from 'zustand/shallow'
+import { widgetStoreActions } from '../../stores/widget-store'
+import { useWidgetSelector } from '../../stores/use-widget-selector'
 import {
   DEFAULT_PAGE,
   DEFAULT_ROWS_PER_PAGE,
@@ -53,50 +53,26 @@ export function usePagination<T extends TableRow>(
   widgetId: string,
   data: T[],
 ): UsePaginationResult<T> {
-  // Get store actions and state
-  const setWidget = useWidgetStore((state) => state.setWidget)
-  const getWidget = useWidgetStore((state) => state.getWidget)
-  const paginationEnabled = useWidgetStore(
-    useShallow(
-      (state) =>
-        !!(state.widgets[widgetId] as TableWidgetState | undefined)?.pagination,
-    ),
-  )
-  const page = useWidgetStore(
-    useShallow(
-      (state) =>
-        (state.widgets[widgetId] as TableWidgetState | undefined)?.pagination
-          ?.page ?? DEFAULT_PAGE,
-    ),
-  )
-  const rowsPerPage = useWidgetStore(
-    useShallow(
-      (state) =>
-        (state.widgets[widgetId] as TableWidgetState | undefined)?.pagination
-          ?.rowsPerPage ?? DEFAULT_ROWS_PER_PAGE,
-    ),
-  )
-  const rowsPerPageOptions = useWidgetStore(
-    useShallow(
-      (state) =>
-        (state.widgets[widgetId] as TableWidgetState | undefined)?.pagination
-          ?.rowsPerPageOptions ?? DEFAULT_ROWS_PER_PAGE_OPTIONS,
-    ),
-  )
-  const total = useWidgetStore(
-    useShallow(
-      (state) =>
-        (state.widgets[widgetId] as TableWidgetState | undefined)?.pagination
-          ?.total ?? data.length,
-    ),
-  )
-
-  const mode = useWidgetStore(
-    useShallow((state) => {
-      const widget = state.widgets[widgetId] as TableWidgetState | undefined
-      return widget?.mode
-    }),
-  )
+  // Get store state
+  const {
+    paginationEnabled,
+    page,
+    rowsPerPage,
+    rowsPerPageOptions,
+    total,
+    mode,
+  } = useWidgetSelector(widgetId, (w) => {
+    const widget = w as TableWidgetState | undefined
+    return {
+      paginationEnabled: !!widget?.pagination,
+      page: widget?.pagination?.page ?? DEFAULT_PAGE,
+      rowsPerPage: widget?.pagination?.rowsPerPage ?? DEFAULT_ROWS_PER_PAGE,
+      rowsPerPageOptions:
+        widget?.pagination?.rowsPerPageOptions ?? DEFAULT_ROWS_PER_PAGE_OPTIONS,
+      total: widget?.pagination?.total ?? data.length,
+      mode: widget?.mode,
+    }
+  })
 
   // Calculate max page
   const maxPage = Math.max(0, Math.ceil(total / (rowsPerPage ?? 1)) - 1)
@@ -105,7 +81,7 @@ export function usePagination<T extends TableRow>(
   const setPage = useCallback(
     (newPage: number) => {
       // Read current state directly from store to avoid stale closures
-      const widget = getWidget<TableWidgetState>(widgetId)
+      const widget = widgetStoreActions.getWidget<TableWidgetState>(widgetId)
       const currentTotal = widget?.pagination?.total ?? data.length
       const currentRowsPerPage =
         widget?.pagination?.rowsPerPage ?? DEFAULT_ROWS_PER_PAGE
@@ -115,21 +91,21 @@ export function usePagination<T extends TableRow>(
       )
       const boundedPage = Math.max(0, Math.min(newPage, currentMaxPage))
 
-      setWidget<TableWidgetState>(widgetId, {
+      widgetStoreActions.setWidget<TableWidgetState>(widgetId, {
         pagination: {
           ...widget?.pagination,
           page: boundedPage,
         },
       })
     },
-    [data.length, getWidget, setWidget, widgetId],
+    [data.length, widgetId],
   )
 
   // Set rows per page and reset to first page
   const setRowsPerPage = useCallback(
     (newRowsPerPage: number) => {
-      const widget = getWidget<TableWidgetState>(widgetId)
-      setWidget<TableWidgetState>(widgetId, {
+      const widget = widgetStoreActions.getWidget<TableWidgetState>(widgetId)
+      widgetStoreActions.setWidget<TableWidgetState>(widgetId, {
         pagination: {
           ...widget?.pagination,
           rowsPerPage: newRowsPerPage,
@@ -137,7 +113,7 @@ export function usePagination<T extends TableRow>(
         },
       })
     },
-    [getWidget, setWidget, widgetId],
+    [widgetId],
   )
 
   // Navigation helpers