@carto/ps-react-ui 4.4.3 → 4.5.0

package/src/widgets/loader/loader.tsx

@@ -1,6 +1,6 @@
-import { useEffect, useRef, useSyncExternalStore } from 'react'
+import { useEffect, useRef } from 'react'
 import type { WidgetLoaderProps } from './types'
-import { useWidgetStore } from '../stores/widget-store'
+import { useWidgetStore, widgetStoreActions } from '../stores/widget-store'
 import type { WrapperState } from '../wrapper'
 
 /**
@@ -28,17 +28,11 @@ import type { WrapperState } from '../wrapper'
 export function WidgetLoader<T extends object = Record<string, unknown>>(
   props: WidgetLoaderProps<T>,
 ) {
-  const setWidget = useWidgetStore((state) => state.setWidget)
-  const executeToolPipeline = useWidgetStore(
-    (state) => state.executeToolPipeline,
-  )
-  const executeConfigPipeline = useWidgetStore(
-    (state) => state.executeConfigPipeline,
-  )
-
-  const registeredTools = useSyncExternalStore(
-    useWidgetStore.subscribe,
-    () => useWidgetStore.getState().widgets[props.id]?.registeredTools,
+  // Subscribe only to this widget's registeredTools via Zustand selector.
+  // The selector returns a stable reference when other widgets change,
+  // avoiding unnecessary re-evaluations of Effect 4.
+  const registeredTools = useWidgetStore(
+    (state) => state.widgets[props.id]?.registeredTools,
   )
 
   const dataRef = useRef(props.data)
@@ -50,56 +44,49 @@ export function WidgetLoader<T extends object = Record<string, unknown>>(
     configRef.current = props.config
   })
 
-  // Split into 3 effects for metadata and 1 for data pipeline:
-  // Each property that can be modified independently gets its own effect to avoid
-  // accidentally resetting other properties.
-  //
-  // - Effect 1: Type (can be modified by tools that change visualization type)
-  // - Effect 2: Loading/Error states (change during fetch lifecycle)
-  // - Effect 3: Config (can be modified by tools that change widget configuration)
-  // - Effect 4: Data pipeline execution (transforms data through registered tools)
-  // - Effect 5: Re-execute pipeline when tool state changes
-
-  // Effect 1: Type updates
+  // Effect 1: Metadata — type, loading, and error states in a single setWidget call.
+  // Merged to reduce store updates from 2 to 1 per widget during initialization.
   useEffect(() => {
-    setWidget<WrapperState>(props.id, {
+    widgetStoreActions.setWidget<WrapperState>(props.id, {
       type: props.type,
-    })
-  }, [props.id, props.type, setWidget])
-
-  // Effect 2: Loading and error states
-  useEffect(() => {
-    setWidget<WrapperState>(props.id, {
       isLoading: props.isLoading ?? false,
       isFetching: props.isFetching ?? false,
       error: props.error,
     })
-  }, [props.id, props.isLoading, props.isFetching, props.error, setWidget])
+  }, [props.id, props.type, props.isLoading, props.isFetching, props.error])
 
-  // Effect 3: Config updates — run through config pipeline
+  // Effect 2: Config updates — run through config pipeline
   useEffect(() => {
     if (props.config) {
-      void executeConfigPipeline(props.id, props.config)
+      void widgetStoreActions.executeConfigPipeline(props.id, props.config)
     }
-  }, [props.id, props.config, executeConfigPipeline])
+  }, [props.id, props.config])
 
-  // Effect 4: Execute tool pipeline when props.data changes
+  // Effect 3: Execute tool pipeline when props.data changes
   useEffect(() => {
-    void executeToolPipeline(props.id, props.data)
-  }, [props.id, props.data, executeToolPipeline])
+    void widgetStoreActions.executeToolPipeline(props.id, props.data)
+  }, [props.id, props.data])
 
-  // Effect 5: Re-execute pipelines when registered tools change
+  // Effect 4: Re-execute pipelines when registered tools change.
+  // Uses requestAnimationFrame to coalesce rapid successive registeredTools
+  // changes (e.g., 6 action components each calling registerTool on mount)
+  // into a single pipeline execution instead of 6 pairs.
   useEffect(() => {
     if (!isMountedRef.current) {
       isMountedRef.current = true
       return
     }
 
-    void executeToolPipeline(props.id, dataRef.current)
-    if (configRef.current) {
-      void executeConfigPipeline(props.id, configRef.current)
-    }
-  }, [registeredTools, props.id, executeToolPipeline, executeConfigPipeline])
+    const rafId = requestAnimationFrame(() => {
+      const { executeToolPipeline, executeConfigPipeline } = widgetStoreActions
+      void executeToolPipeline(props.id, dataRef.current)
+      if (configRef.current) {
+        void executeConfigPipeline(props.id, configRef.current)
+      }
+    })
+
+    return () => cancelAnimationFrame(rafId)
+  }, [registeredTools, props.id])
 
   return props.children
 }

package/src/widgets/markdown/markdown.tsx

@@ -1,18 +1,15 @@
 import type { MarkdownUIProps } from './types'
-import { useWidgetStore } from '../stores/widget-store'
 import type { MarkdownWidgetData } from './types'
 import { MarkdownUI } from '.'
-import { useShallow } from 'zustand/shallow'
+import { useWidgetSelector } from '../stores/use-widget-selector'
 
 /**
  * Stateful markdown widget component that reads content from the widget store and renders it as formatted rich text.
  */
 export function Markdown({ id }: MarkdownUIProps) {
-  const content = useWidgetStore(
-    useShallow(
-      (state) =>
-        (state.getWidget(id)?.data as MarkdownWidgetData | undefined)?.content,
-    ),
+  const content = useWidgetSelector(
+    id,
+    (w) => (w?.data as MarkdownWidgetData | undefined)?.content,
   )
 
   if (!content) {

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

@@ -1,6 +1,5 @@
 import { Box, Typography } from '@mui/material'
-import { useShallow } from 'zustand/shallow'
-import { useWidgetStore } from '../stores/widget-store'
+import { useWidgetSelector } from '../stores/use-widget-selector'
 import type { WidgetNoDataProps } from './types'
 import { styles } from './style'
 
@@ -44,14 +43,12 @@ export function WidgetNoData({
   description = 'There are no results for the combination of filters applied to your data. Try tweaking your filters, or zoom and pan the map to adjust filters',
   isEmpty = defaultIsEmpty,
 }: WidgetNoDataProps) {
-  // Subscribe to widget store with selective subscription for optimal performance
-  const isLoading = useWidgetStore(
-    useShallow((state) => state.widgets[id]?.isLoading),
-  )
-  const isFetching = useWidgetStore(
-    useShallow((state) => state.widgets[id]?.isFetching),
-  )
-  const data = useWidgetStore(useShallow((state) => state.widgets[id]?.data))
+  // Single consolidated subscription instead of 3 separate ones.
+  const { isLoading, isFetching, data } = useWidgetSelector(id, (w) => ({
+    isLoading: w?.isLoading,
+    isFetching: w?.isFetching,
+    data: w?.data,
+  }))
 
   // If loading or fetching, show children
   // SkeletonLoader handles loading state, this allows proper composition

package/src/widgets/range/components/range-item.tsx

@@ -1,9 +1,9 @@
 import { Box, Slider, TextField } from '@mui/material'
 import { useState, useMemo, type FocusEvent, type KeyboardEvent } from 'react'
-import { useWidgetStore } from '../../stores/widget-store'
+import { widgetStoreActions } from '../../stores/widget-store'
+import { useWidgetSelector } from '../../stores/use-widget-selector'
 import type { RangeItemProps, RangeWidgetState } from '../types'
 import { styles } from '../style'
-import { useShallow } from 'zustand/shallow'
 
 import { defaultFormatter } from '../../utils/formatter'
 
@@ -13,18 +13,19 @@ type EditingState = '' | 'min' | 'max'
  * Renders a single range slider with editable min/max text inputs, reading its configuration from the widget store.
  */
 export function RangeItem({ id, index }: RangeItemProps) {
-  const item = useWidgetStore(
-    useShallow((state) => state.getWidget<RangeWidgetState>(id)?.data[index]),
-  )
-  const onChange = useWidgetStore(
-    useShallow((state) => state.getWidget<RangeWidgetState>(id)?.onChange),
-  )
-  const formatter =
-    useWidgetStore(
-      useShallow((state) => state.getWidget<RangeWidgetState>(id)?.formatter),
-    ) ?? defaultFormatter
-  const getWidget = useWidgetStore((store) => store.getWidget)
-  const setWidget = useWidgetStore((store) => store.setWidget)
+  const {
+    item,
+    onChange,
+    formatter: _formatter,
+  } = useWidgetSelector(id, (w) => {
+    const rw = w as RangeWidgetState | undefined
+    return {
+      item: rw?.data[index],
+      onChange: rw?.onChange,
+      formatter: rw?.formatter,
+    }
+  })
+  const formatter = _formatter ?? defaultFormatter
 
   const currentValue = useMemo(
     () => (item ? (item.value ?? [item.min, item.max]) : [0, 0]),
@@ -39,14 +40,15 @@ export function RangeItem({ id, index }: RangeItemProps) {
   const handleSliderChange = (_: Event, newValue: number | number[]) => {
     if (Array.isArray(newValue)) {
       const [min, max] = newValue
-      const data = getWidget<RangeWidgetState>(id)?.data ?? []
+      const data =
+        widgetStoreActions.getWidget<RangeWidgetState>(id)?.data ?? []
 
       data[index] = {
         ...item,
         value: newValue,
       }
 
-      setWidget(id, {
+      widgetStoreActions.setWidget(id, {
         data,
       })
 
@@ -80,9 +82,9 @@ export function RangeItem({ id, index }: RangeItemProps) {
       ]
     }
 
-    const data = getWidget<RangeWidgetState>(id)?.data ?? []
+    const data = widgetStoreActions.getWidget<RangeWidgetState>(id)?.data ?? []
 
-    setWidget(id, {
+    widgetStoreActions.setWidget(id, {
       data: data.map((d: RangeWidgetState['data'][number], i: number) =>
         i === index
           ? {

package/src/widgets/skeleton-loader/skeleton-loader.tsx

@@ -1,7 +1,6 @@
 import type { SkeletonLoaderProps } from './types'
-import { useWidgetStore } from '../stores/widget-store'
+import { useWidgetSelector } from '../stores/use-widget-selector'
 import { Suspense } from 'react'
-import { useShallow } from 'zustand/shallow'
 
 /**
  * Displays a skeleton loading placeholder while widget data is loading. Subscribes to widget loading state in the store and renders the provided Skeleton component or children accordingly.
@@ -18,9 +17,7 @@ export function SkeletonLoader({
   children,
   Skeleton,
 }: SkeletonLoaderProps) {
-  const isLoading = useWidgetStore(
-    useShallow((state) => state.widgets[id]?.isLoading),
-  )
+  const isLoading = useWidgetSelector(id, (w) => w?.isLoading)
 
   if (isLoading) {
     if (!Skeleton) {

package/src/widgets/spread/components/max-value.tsx

@@ -1,27 +1,25 @@
 import { type SpreadWidgetState, type ValueProps } from '../types'
-import { useWidgetStore } from '../../stores/widget-store'
+import { useWidgetSelector } from '../../stores/use-widget-selector'
 import { Item } from '../../formula/components/item'
-import { useShallow } from 'zustand/shallow'
 import { defaultFormatter } from '../../utils/formatter'
 
 /**
  * Displays the formatted maximum value for a spread widget data item.
  */
 export function MaxValue({ id, index = 0, ...props }: ValueProps) {
-  const max = useWidgetStore(
-    useShallow(
-      (state) => state.getWidget<SpreadWidgetState>(id)?.data[index]?.max,
-    ),
-  )
-  const color = useWidgetStore(
-    useShallow(
-      (state) => state.getWidget<SpreadWidgetState>(id)?.data[index]?.color,
-    ),
-  )
-  const formatter =
-    useWidgetStore(
-      useShallow((state) => state.getWidget<SpreadWidgetState>(id)?.formatter),
-    ) ?? defaultFormatter
+  const {
+    max,
+    color,
+    formatter: _formatter,
+  } = useWidgetSelector(id, (w) => {
+    const sw = w as SpreadWidgetState | undefined
+    return {
+      max: sw?.data[index]?.max,
+      color: sw?.data[index]?.color,
+      formatter: sw?.formatter,
+    }
+  })
+  const formatter = _formatter ?? defaultFormatter
 
   return (
     <Item TypographyProps={{ color }} {...props}>

package/src/widgets/spread/components/min-value.tsx

@@ -1,27 +1,25 @@
 import { type SpreadWidgetState, type ValueProps } from '../types'
-import { useWidgetStore } from '../../stores/widget-store'
+import { useWidgetSelector } from '../../stores/use-widget-selector'
 import { Item } from '../../formula/components/item'
-import { useShallow } from 'zustand/shallow'
 import { defaultFormatter } from '../../utils/formatter'
 
 /**
  * Displays the formatted minimum value for a spread widget data item.
  */
 export function MinValue({ id, index = 0, ...props }: ValueProps) {
-  const min = useWidgetStore(
-    useShallow(
-      (state) => state.getWidget<SpreadWidgetState>(id)?.data[index]?.min,
-    ),
-  )
-  const color = useWidgetStore(
-    useShallow(
-      (state) => state.getWidget<SpreadWidgetState>(id)?.data[index]?.color,
-    ),
-  )
-  const formatter =
-    useWidgetStore(
-      useShallow((state) => state.getWidget<SpreadWidgetState>(id)?.formatter),
-    ) ?? defaultFormatter
+  const {
+    min,
+    color,
+    formatter: _formatter,
+  } = useWidgetSelector(id, (w) => {
+    const sw = w as SpreadWidgetState | undefined
+    return {
+      min: sw?.data[index]?.min,
+      color: sw?.data[index]?.color,
+      formatter: sw?.formatter,
+    }
+  })
+  const formatter = _formatter ?? defaultFormatter
 
   return (
     <Item TypographyProps={{ color }} {...props}>

package/src/widgets/stores/index.ts

@@ -1,4 +1,5 @@
-export { useWidgetStore } from './widget-store'
+export { useWidgetStore, widgetStoreActions } from './widget-store'
+export { useWidgetSelector } from './use-widget-selector'
 export type {
   BaseWidgetState,
   ToolType,

package/src/widgets/stores/use-widget-selector.ts

@@ -0,0 +1,47 @@
+import { useWidgetStore } from './widget-store'
+import type { WidgetState } from './types'
+import { useShallow } from 'zustand/shallow'
+
+/**
+ * Scoped selector hook for reading a single widget's state from the store.
+ *
+ * Consolidates multiple `useWidgetStore(useShallow(...))` calls into a single
+ * subscription per component. The selector receives only this widget's state
+ * (or undefined if not yet registered), and uses shallow comparison to avoid
+ * re-renders when unrelated properties change.
+ *
+ * @param widgetId - The widget ID to subscribe to.
+ * @param selector - A function that extracts the needed properties from the widget state.
+ *   Must be a stable reference (inline arrow is fine due to useCallback wrapping).
+ *
+ * @example
+ * ```tsx
+ * // Before: 4 separate subscriptions
+ * const title = useWidgetStore(useShallow((s) => s.getWidget(id)?.title))
+ * const collapsed = useWidgetStore(useShallow((s) => s.getWidget(id)?.collapsed))
+ * const disabled = useWidgetStore(useShallow((s) => s.getWidget(id)?.disabled))
+ * const isFetching = useWidgetStore(useShallow((s) => s.getWidget(id)?.isFetching))
+ *
+ * // After: 1 subscription
+ * const { title, collapsed, disabled, isFetching } = useWidgetSelector(id, (w) => ({
+ *   title: w?.title, collapsed: w?.collapsed, disabled: w?.disabled, isFetching: w?.isFetching,
+ * }))
+ *
+ * // With extra dependencies (e.g., index prop):
+ * const value = useWidgetSelector(
+ *   id,
+ *   (w) => (w as MyState | undefined)?.data?.[index]?.value,
+ *   [index],
+ * )
+ * ```
+ */
+export function useWidgetSelector<T>(
+  widgetId: string,
+  selector: (widget: WidgetState | undefined) => T,
+): T {
+  return useWidgetStore(
+    useShallow((state: { widgets: Record<string, WidgetState> }) =>
+      selector(state.widgets[widgetId]),
+    ),
+  )
+}