@carto/ps-react-ui 4.5.0 → 4.6.0

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

@@ -5,7 +5,7 @@ import {
 } from '@mui/icons-material'
 import { useEffect, useCallback } from 'react'
 import { widgetStoreActions } from '../../stores/widget-store'
-import type { ZoomToggleProps } from './types'
+import type { ZoomToggleProps, ZoomState } from './types'
 import { styles } from './style'
 import { Tooltip } from '../../../components'
 import { getEChartZoomConfig } from '../../echart/utils'
@@ -20,6 +20,10 @@ export const ZOOM_TOGGLE_TOOL_ID = 'zoom-toggle'
  * Registers as a config pipeline tool so that zoom configuration is automatically
  * re-applied when the base config is updated (e.g., by WidgetLoader).
  *
+ * Zoom state (enabled, range) is stored in the widget store root, and the tool
+ * derives its `enabled` flag from the store. This keeps state accessible across
+ * component instances.
+ *
  * When zoom is active, displays an inline reset button to disable zoom.
  * Only intended for use in fullscreen ToolbarActions for bar and histogram widgets.
  *
@@ -45,19 +49,26 @@ export function ZoomToggle({
 }: ZoomToggleProps) {
   const theme = useTheme()
 
-  const { zoom, zoomStart, zoomEnd } = useWidgetSelector(id, (w) => {
-    const zoomTool = w?.registeredTools?.find(
-      (tool) => tool.id === ZOOM_TOGGLE_TOOL_ID,
-    )
-    return {
-      zoom: zoomTool?.enabled ?? defaultZoom,
-      zoomStart:
-        (zoomTool?.config?.start as number | undefined) ?? defaultZoomStart,
-      zoomEnd: (zoomTool?.config?.end as number | undefined) ?? defaultZoomEnd,
+  // Read zoom state from widget store root — single source of truth
+  const { zoom, zoomStart, zoomEnd } = useWidgetSelector(id, (w) => ({
+    zoom: (w as ZoomState | undefined)?.zoom ?? defaultZoom,
+    zoomStart: (w as ZoomState | undefined)?.zoomStart ?? defaultZoomStart,
+    zoomEnd: (w as ZoomState | undefined)?.zoomEnd ?? defaultZoomEnd,
+  }))
+
+  // Initialize store with default values on mount
+  useEffect(() => {
+    const current = widgetStoreActions.getWidget<ZoomState>(id)
+    if (current?.zoom === undefined) {
+      widgetStoreActions.setWidget(id, {
+        zoom: defaultZoom,
+        zoomStart: defaultZoomStart,
+        zoomEnd: defaultZoomEnd,
+      })
     }
-  })
+  }, [id, defaultZoom, defaultZoomStart, defaultZoomEnd])
 
-  // Handle dataZoom event to update zoom range in tool config
+  // Handle dataZoom event — update store (source of truth)
   const handleDataZoom = useCallback(
     (event: unknown) => {
       const zoomEvent = event as {
@@ -73,41 +84,32 @@ export function ZoomToggle({
       const end = zoomEvent.end ?? zoomEvent.batch?.[0]?.end
 
       if (start !== undefined && end !== undefined) {
-        widgetStoreActions.setToolEnabled(id, ZOOM_TOGGLE_TOOL_ID, true)
-        widgetStoreActions.updateToolConfig(id, ZOOM_TOGGLE_TOOL_ID, {
-          start,
-          end,
+        widgetStoreActions.setWidget(id, {
+          zoom: true,
+          zoomStart: start,
+          zoomEnd: end,
         })
       }
     },
     [id],
   )
 
-  // Register config tool with all reactive deps — store's no-op detection handles performance
+  // Register config tool once — fn reads zoom range from the store at execution time.
   useEffect(() => {
-    const existingTool = widgetStoreActions
-      .getWidget(id)
-      ?.registeredTools?.find((tool) => tool.id === ZOOM_TOGGLE_TOOL_ID)
-
-    const initialEnabled = existingTool?.enabled ?? defaultZoom
-    const initialStart =
-      (existingTool?.config?.start as number | undefined) ?? defaultZoomStart
-    const initialEnd =
-      (existingTool?.config?.end as number | undefined) ?? defaultZoomEnd
-
     widgetStoreActions.registerTool(id, {
       id: ZOOM_TOGGLE_TOOL_ID,
       type: 'config',
       order: 20,
-      enabled: initialEnabled,
-      fn: (currentConfig, toolConfig) => {
+      enabled: defaultZoom,
+      fn: (currentConfig) => {
         const config = currentConfig as Record<string, unknown>
         const option = config.option as EchartOptionsProps | undefined
         const currentOnEvents =
           (config.onEvents as Record<string, unknown> | undefined) ?? {}
 
-        const start = (toolConfig?.start as number) ?? 0
-        const end = (toolConfig?.end as number) ?? 100
+        const widget = widgetStoreActions.getWidget<ZoomState>(id)
+        const start = widget?.zoomStart ?? 0
+        const end = widget?.zoomEnd ?? 100
 
         const legend = option?.legend as { show?: boolean } | undefined
         const hasLegend = legend?.show !== false && legend !== undefined
@@ -135,8 +137,6 @@ export function ZoomToggle({
 
         const gridBottom = currentGridBottom + sliderHeight + sliderGap
 
-        const onEventsWithoutDataZoom = { ...currentOnEvents }
-        delete onEventsWithoutDataZoom.dataZoom
         const onEvents = { ...currentOnEvents, dataZoom: handleDataZoom }
 
         return {
@@ -149,28 +149,36 @@ export function ZoomToggle({
           onEvents,
         }
       },
-      config: {
-        start: initialStart,
-        end: initialEnd,
-      },
     })
     return () => widgetStoreActions.unregisterTool(id, ZOOM_TOGGLE_TOOL_ID)
   }, [id, theme, handleDataZoom, defaultZoom, defaultZoomStart, defaultZoomEnd])
 
+  // Sync enabled from store — lightweight, no re-registration
+  useEffect(() => {
+    widgetStoreActions.setToolEnabled(id, ZOOM_TOGGLE_TOOL_ID, zoom)
+  }, [id, zoom])
+
+  // Trigger pipeline when zoom range changes — fn reads from store at execution time,
+  // but the pipeline only re-runs when registeredTools reference changes.
+  // setToolEnabled handles the zoom on/off case, this handles range-only changes.
+  useEffect(() => {
+    widgetStoreActions.triggerToolPipeline(id)
+  }, [id, zoomStart, zoomEnd])
+
   const handleToggle = () => {
     const newZoom = !zoom
-    widgetStoreActions.setToolEnabled(id, ZOOM_TOGGLE_TOOL_ID, newZoom)
-    widgetStoreActions.updateToolConfig(id, ZOOM_TOGGLE_TOOL_ID, {
-      start: newZoom ? zoomStart : 0,
-      end: newZoom ? zoomEnd : 100,
+    widgetStoreActions.setWidget(id, {
+      zoom: newZoom,
+      zoomStart: newZoom ? zoomStart : 0,
+      zoomEnd: newZoom ? zoomEnd : 100,
     })
   }
 
   const handleReset = () => {
-    widgetStoreActions.setToolEnabled(id, ZOOM_TOGGLE_TOOL_ID, true)
-    widgetStoreActions.updateToolConfig(id, ZOOM_TOGGLE_TOOL_ID, {
-      start: defaultZoomStart,
-      end: defaultZoomEnd,
+    widgetStoreActions.setWidget(id, {
+      zoom: true,
+      zoomStart: defaultZoomStart,
+      zoomEnd: defaultZoomEnd,
     })
   }
 

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

@@ -2,19 +2,19 @@ import { Box, useTheme } from '@mui/material'
 import { useWidgetSelector } from '../stores/use-widget-selector'
 import { styles } from './style'
 import type { CategoryUIProps, CategoryWidgetState } from './types'
-import {
-  CategoryRowSingle,
-  CategoryRowMulti,
-  CategoryRowOther,
-  CategoryLegend,
-} from './components'
+import { CategoryRowSingle } from './components/category-row-single'
+import { CategoryRowMulti } from './components/category-row-multi'
+import { CategoryRowOther } from './components/category-row-other'
+import { CategoryLegend } from './components/category-legend'
 import { useState } from 'react'
 import { defaultFormatter, defaultLabelFormatter } from '../utils/formatter'
+import { useWidgetRef } from '../../hooks'
 
 /**
  * Renders a category widget displaying horizontal bars for categorical data with support for single and multi-series layouts, selection, and overflow grouping.
  */
 export function CategoryUI({ id }: CategoryUIProps) {
+  const { ref } = useWidgetRef<HTMLDivElement>(id)
   const theme = useTheme()
 
   // Single consolidated subscription instead of 9 separate ones.
@@ -85,6 +85,7 @@ export function CategoryUI({ id }: CategoryUIProps) {
 
   return (
     <Box
+      ref={ref}
       sx={{
         ...styles.root,
       }}

package/src/widgets/category/index.ts

@@ -2,21 +2,20 @@ export { CategoryUI } from './category-ui'
 export { CategorySkeleton } from './skeleton'
 export { categoryConfig, categoryDownloadConfig } from './config'
 
-export {
-  CategoryBar,
-  CategoryRowSingle,
-  CategoryRowMulti,
-  CategoryLegend,
-  CategoryRowOther,
-} from './components'
+export { CategoryBar } from './components/category-bar'
+export type { CategoryBarProps } from './components/category-bar'
 
-export type {
-  CategoryBarProps,
-  CategoryRowSingleProps,
-  CategoryRowMultiProps,
-  CategoryLegendProps,
-  CategoryRowOtherProps,
-} from './components'
+export { CategoryRowSingle } from './components/category-row-single'
+export type { CategoryRowSingleProps } from './components/category-row-single'
+
+export { CategoryRowMulti } from './components/category-row-multi'
+export type { CategoryRowMultiProps } from './components/category-row-multi'
+
+export { CategoryRowOther } from './components/category-row-other'
+export type { CategoryRowOtherProps } from './components/category-row-other'
+
+export { CategoryLegend } from './components/category-legend'
+export type { CategoryLegendProps } from './components/category-legend'
 
 export type {
   CategoryUIProps,

package/src/widgets/category/style.ts

@@ -5,6 +5,7 @@ export const styles = {
     display: 'flex',
     flexDirection: 'column',
     position: 'relative',
+    width: '100%',
   },
   list: {
     display: 'flex',

package/src/widgets/no-data/no-data.test.tsx

@@ -10,12 +10,12 @@ describe('WidgetNoData', () => {
     useWidgetStore.getState().clearWidgets()
   })
 
-  describe('when data is empty', () => {
+  describe('when sourceData is empty', () => {
     test('renders NoData UI with empty array', () => {
       useWidgetStore.getState().setWidget(widgetId, {
         isLoading: false,
         isFetching: false,
-        data: [],
+        sourceData: [],
       })
 
       render(
@@ -31,11 +31,11 @@ describe('WidgetNoData', () => {
       expect(screen.queryByText('Widget Content')).toBeNull()
     })
 
-    test('renders NoData UI with null data', () => {
+    test('renders NoData UI with null sourceData', () => {
       useWidgetStore.getState().setWidget(widgetId, {
         isLoading: false,
         isFetching: false,
-        data: null,
+        sourceData: null,
       })
 
       render(
@@ -48,11 +48,11 @@ describe('WidgetNoData', () => {
       expect(screen.queryByText('Widget Content')).toBeNull()
     })
 
-    test('renders NoData UI with undefined data', () => {
+    test('renders NoData UI with undefined sourceData', () => {
       useWidgetStore.getState().setWidget(widgetId, {
         isLoading: false,
         isFetching: false,
-        data: undefined,
+        sourceData: undefined,
       })
 
       render(
@@ -69,7 +69,7 @@ describe('WidgetNoData', () => {
       useWidgetStore.getState().setWidget(widgetId, {
         isLoading: false,
         isFetching: false,
-        data: [[], []],
+        sourceData: [[], []],
       })
 
       render(
@@ -86,7 +86,7 @@ describe('WidgetNoData', () => {
       useWidgetStore.getState().setWidget(widgetId, {
         isLoading: false,
         isFetching: false,
-        data: {},
+        sourceData: {},
       })
 
       render(
@@ -100,12 +100,12 @@ describe('WidgetNoData', () => {
     })
   })
 
-  describe('when data exists', () => {
-    test('renders children with array data', () => {
+  describe('when sourceData exists', () => {
+    test('renders children with array sourceData', () => {
       useWidgetStore.getState().setWidget(widgetId, {
         isLoading: false,
         isFetching: false,
-        data: [{ value: 1 }],
+        sourceData: [{ value: 1 }],
       })
 
       render(
@@ -118,11 +118,11 @@ describe('WidgetNoData', () => {
       expect(screen.queryByText('No data available')).toBeNull()
     })
 
-    test('renders children with object data', () => {
+    test('renders children with object sourceData', () => {
       useWidgetStore.getState().setWidget(widgetId, {
         isLoading: false,
         isFetching: false,
-        data: { content: 'Hello' },
+        sourceData: { content: 'Hello' },
       })
 
       render(
@@ -135,11 +135,11 @@ describe('WidgetNoData', () => {
       expect(screen.queryByText('No data available')).toBeNull()
     })
 
-    test('renders children with nested array data', () => {
+    test('renders children with nested array sourceData', () => {
       useWidgetStore.getState().setWidget(widgetId, {
         isLoading: false,
         isFetching: false,
-        data: [[{ name: 'A', value: 1 }]],
+        sourceData: [[{ name: 'A', value: 1 }]],
       })
 
       render(
@@ -152,11 +152,11 @@ describe('WidgetNoData', () => {
       expect(screen.queryByText('No data available')).toBeNull()
     })
 
-    test('renders children with primitive data (number)', () => {
+    test('renders children with primitive sourceData (number)', () => {
       useWidgetStore.getState().setWidget(widgetId, {
         isLoading: false,
         isFetching: false,
-        data: 0,
+        sourceData: 0,
       })
 
       render(
@@ -169,11 +169,11 @@ describe('WidgetNoData', () => {
       expect(screen.queryByText('No data available')).toBeNull()
     })
 
-    test('renders children with primitive data (string)', () => {
+    test('renders children with primitive sourceData (string)', () => {
       useWidgetStore.getState().setWidget(widgetId, {
         isLoading: false,
         isFetching: false,
-        data: 'test',
+        sourceData: 'test',
       })
 
       render(
@@ -186,11 +186,11 @@ describe('WidgetNoData', () => {
       expect(screen.queryByText('No data available')).toBeNull()
     })
 
-    test('renders children with primitive data (boolean)', () => {
+    test('renders children with primitive sourceData (boolean)', () => {
       useWidgetStore.getState().setWidget(widgetId, {
         isLoading: false,
         isFetching: false,
-        data: false,
+        sourceData: false,
       })
 
       render(
@@ -205,11 +205,10 @@ describe('WidgetNoData', () => {
   })
 
   describe('when loading or fetching', () => {
-    test('renders children when isLoading=true even if data is empty', () => {
+    test('renders children when isLoading=true even if sourceData is empty', () => {
       useWidgetStore.getState().setWidget(widgetId, {
         isLoading: true,
         isFetching: false,
-        data: [],
       })
 
       render(
@@ -222,11 +221,10 @@ describe('WidgetNoData', () => {
       expect(screen.queryByText('No data available')).toBeNull()
     })
 
-    test('renders children when isFetching=true even if data is empty', () => {
+    test('renders children when isFetching=true even if sourceData is empty', () => {
       useWidgetStore.getState().setWidget(widgetId, {
         isLoading: false,
         isFetching: true,
-        data: [],
       })
 
       render(
@@ -243,7 +241,6 @@ describe('WidgetNoData', () => {
       useWidgetStore.getState().setWidget(widgetId, {
         isLoading: true,
         isFetching: true,
-        data: [],
       })
 
       render(
@@ -262,7 +259,7 @@ describe('WidgetNoData', () => {
       useWidgetStore.getState().setWidget(widgetId, {
         isLoading: false,
         isFetching: false,
-        data: [],
+        sourceData: [],
       })
 
       render(
@@ -279,7 +276,7 @@ describe('WidgetNoData', () => {
       useWidgetStore.getState().setWidget(widgetId, {
         isLoading: false,
         isFetching: false,
-        data: [],
+        sourceData: [],
       })
 
       render(
@@ -298,10 +295,10 @@ describe('WidgetNoData', () => {
       useWidgetStore.getState().setWidget(widgetId, {
         isLoading: false,
         isFetching: false,
-        data: { customField: 'value' },
+        sourceData: { customField: 'value' },
       })
 
-      // Custom isEmpty that treats this object as empty
+      // Custom isEmpty that treats this sourceData as empty
       const customIsEmpty = (data: unknown) => {
         const d = data as { customField: string }
         return d?.customField === 'value'
@@ -321,7 +318,7 @@ describe('WidgetNoData', () => {
       useWidgetStore.getState().setWidget(widgetId, {
         isLoading: false,
         isFetching: false,
-        data: [],
+        sourceData: [],
       })
 
       // Custom isEmpty that treats empty array as having data
@@ -352,12 +349,66 @@ describe('WidgetNoData', () => {
     })
   })
 
+  describe('sourceData vs pipeline-transformed data', () => {
+    test('renders children when sourceData has data but pipeline data is empty', () => {
+      useWidgetStore.getState().setWidget(widgetId, {
+        isLoading: false,
+        isFetching: false,
+        sourceData: [{ value: 1 }, { value: 2 }],
+        data: [], // pipeline filtered everything out
+      })
+
+      render(
+        <WidgetNoData id={widgetId}>
+          <div>Widget Content</div>
+        </WidgetNoData>,
+      )
+
+      // Should show children because sourceData is not empty
+      expect(screen.getByText('Widget Content')).toBeTruthy()
+      expect(screen.queryByText('No data available')).toBeNull()
+    })
+
+    test('renders NoData when both sourceData and data are empty', () => {
+      useWidgetStore.getState().setWidget(widgetId, {
+        isLoading: false,
+        isFetching: false,
+        sourceData: [],
+      })
+
+      render(
+        <WidgetNoData id={widgetId}>
+          <div>Widget Content</div>
+        </WidgetNoData>,
+      )
+
+      expect(screen.getByText('No data available')).toBeTruthy()
+      expect(screen.queryByText('Widget Content')).toBeNull()
+    })
+
+    test('renders NoData when sourceData is null (API returned nothing)', () => {
+      useWidgetStore.getState().setWidget(widgetId, {
+        isLoading: false,
+        isFetching: false,
+        sourceData: null,
+      })
+
+      render(
+        <WidgetNoData id={widgetId}>
+          <div>Widget Content</div>
+        </WidgetNoData>,
+      )
+
+      expect(screen.getByText('No data available')).toBeTruthy()
+      expect(screen.queryByText('Widget Content')).toBeNull()
+    })
+  })
+
   describe('reactivity to store changes', () => {
-    test('updates from NoData to content when data arrives', () => {
+    test('updates from NoData to content when sourceData arrives', () => {
       useWidgetStore.getState().setWidget(widgetId, {
         isLoading: false,
         isFetching: false,
-        data: [],
       })
 
       const { rerender } = render(
@@ -369,9 +420,9 @@ describe('WidgetNoData', () => {
       expect(screen.getByText('No data available')).toBeTruthy()
       expect(screen.queryByText('Widget Content')).toBeNull()
 
-      // Update with data
+      // Update with sourceData
       useWidgetStore.getState().setWidget(widgetId, {
-        data: [{ value: 1 }],
+        sourceData: [{ value: 1 }],
       })
 
       // Force rerender to pick up store changes
@@ -385,11 +436,11 @@ describe('WidgetNoData', () => {
       expect(screen.queryByText('No data available')).toBeNull()
     })
 
-    test('updates from content to NoData when data becomes empty', () => {
+    test('updates from content to NoData when sourceData becomes empty', () => {
       useWidgetStore.getState().setWidget(widgetId, {
         isLoading: false,
         isFetching: false,
-        data: [{ value: 1 }],
+        sourceData: [{ value: 1 }],
       })
 
       const { rerender } = render(
@@ -401,8 +452,8 @@ describe('WidgetNoData', () => {
       expect(screen.getByText('Widget Content')).toBeTruthy()
       expect(screen.queryByText('No data available')).toBeNull()
 
-      // Clear data
-      useWidgetStore.getState().setWidget(widgetId, { data: [] })
+      // Clear sourceData
+      useWidgetStore.getState().setWidget(widgetId, { sourceData: [] })
 
       // Force rerender to pick up store changes
       rerender(
@@ -419,7 +470,6 @@ describe('WidgetNoData', () => {
       useWidgetStore.getState().setWidget(widgetId, {
         isLoading: false,
         isFetching: false,
-        data: [],
       })
 
       const { rerender } = render(

package/src/widgets/no-data/no-data.tsx

@@ -6,8 +6,9 @@ import { styles } from './style'
 /**
  * NoData wrapper component that displays empty state UI when widget has no data
  *
- * Integrates with widget store to check loading/fetching state and data availability.
- * Works in conjunction with SkeletonLoader for complete loading/empty state handling.
+ * Integrates with widget store to check loading/fetching state and source data availability.
+ * Uses `sourceData` (pre-pipeline data) instead of `data` (post-pipeline) to distinguish
+ * "API returned nothing" from "pipeline tools filtered everything out".
  *
  * @example Basic usage
  * ```tsx
@@ -44,10 +45,11 @@ export function WidgetNoData({
   isEmpty = defaultIsEmpty,
 }: WidgetNoDataProps) {
   // Single consolidated subscription instead of 3 separate ones.
-  const { isLoading, isFetching, data } = useWidgetSelector(id, (w) => ({
+  // Reads sourceData (pre-pipeline) to check emptiness, not data (post-pipeline).
+  const { isLoading, isFetching, sourceData } = useWidgetSelector(id, (w) => ({
     isLoading: w?.isLoading,
     isFetching: w?.isFetching,
-    data: w?.data,
+    sourceData: w?.sourceData,
   }))
 
   // If loading or fetching, show children
@@ -57,7 +59,7 @@ export function WidgetNoData({
   }
 
   // Check if data is empty
-  if (isEmpty(data)) {
+  if (isEmpty(sourceData)) {
     return (
       <Box sx={styles.root}>
         <Typography variant='body2' color='text.primary'>

package/src/widgets/no-data/types.ts

@@ -59,7 +59,11 @@ export interface WidgetNoDataProps {
   description?: string
 
   /**
-   * Optional custom function to determine if data is empty
+   * Optional custom function to determine if source data is empty.
+   * Receives `sourceData` (pre-pipeline data from the API), not `data`
+   * (post-pipeline). This allows distinguishing "API returned nothing"
+   * from "pipeline tools filtered everything out".
+   *
    * If not provided, uses default isEmpty logic that handles:
    * - null/undefined → empty
    * - [] (empty array) → empty

package/src/widgets/stores/index.ts

@@ -2,6 +2,8 @@ export { useWidgetStore, widgetStoreActions } from './widget-store'
 export { useWidgetSelector } from './use-widget-selector'
 export type {
   BaseWidgetState,
+  ToolRegistration,
+  ToolTransformFunction,
   ToolType,
   WidgetsStoreProps,
   WidgetState,