@carto/ps-react-ui 4.4.2 → 4.5.0

package/src/widgets/echart/echart.tsx

@@ -5,8 +5,7 @@ import type {
   EchartOptionsProps,
 } from './types'
 import { EchartUI } from './echart-ui'
-import { useWidgetStore } from '../stores/widget-store'
-import { useShallow } from 'zustand/shallow'
+import { useWidgetSelector } from '../stores/use-widget-selector'
 import { useMemo } from 'react'
 
 /**
@@ -16,31 +15,18 @@ import { useMemo } from 'react'
  * Transforms widget data into ECharts dataset format and delegates rendering to {@link EchartUI}.
  */
 export function Echart(props: EchartProps) {
-  const id = useWidgetStore(
-    useShallow((state) => state.getWidget<EchartWidgetState>(props.id)?.id),
-  )
-
-  const data = useWidgetStore(
-    useShallow(
-      (state) =>
-        state.getWidget<EchartWidgetState>(props.id)?.data as
-          | EchartWidgetData
-          | undefined,
-    ),
-  )
-
-  const widgetOption = useWidgetStore(
-    useShallow((state) => state.getWidget<EchartWidgetState>(props.id)?.option),
-  )
-
-  const onEvents = useWidgetStore(
-    useShallow(
-      (state) => state.getWidget<EchartWidgetState>(props.id)?.onEvents,
-    ),
-  )
-
-  const init = useWidgetStore(
-    (state) => state.getWidget<EchartWidgetState>(props.id)?.init,
+  // Single consolidated subscription instead of 5 separate ones.
+  const { id, data, widgetOption, onEvents, init } = useWidgetSelector(
+    props.id,
+    (w) => ({
+      id: w?.id,
+      data: (w as EchartWidgetState | undefined)?.data as
+        | EchartWidgetData
+        | undefined,
+      widgetOption: (w as EchartWidgetState | undefined)?.option,
+      onEvents: (w as EchartWidgetState | undefined)?.onEvents,
+      init: (w as EchartWidgetState | undefined)?.init,
+    }),
   )
 
   // Memoize dataset transformation to avoid re-computing on every render

package/src/widgets/echart/shared-resize-observer.ts

@@ -0,0 +1,45 @@
+/**
+ * Shared ResizeObserver singleton for all ECharts instances.
+ *
+ * Instead of creating 100+ individual ResizeObserver instances (one per chart),
+ * this module provides a single shared observer that efficiently handles resize
+ * callbacks for all registered elements.
+ */
+
+type ResizeCallback = () => void
+
+const callbacks = new Map<Element, ResizeCallback>()
+
+let observer: ResizeObserver | null = null
+
+function getObserver(): ResizeObserver {
+  observer ??= new ResizeObserver((entries) => {
+    for (const entry of entries) {
+      const callback = callbacks.get(entry.target)
+      callback?.()
+    }
+  })
+  return observer
+}
+
+export function observeResize(
+  element: Element,
+  callback: ResizeCallback,
+): () => void {
+  callbacks.set(element, callback)
+  getObserver().observe(element)
+
+  return () => {
+    callbacks.delete(element)
+    getObserver().unobserve(element)
+  }
+}
+
+/** Reset the shared observer (for testing only). */
+export function resetSharedResizeObserver(): void {
+  if (observer) {
+    observer.disconnect()
+    observer = null
+  }
+  callbacks.clear()
+}

package/src/widgets/echart/types.ts

@@ -33,6 +33,7 @@ export interface EchartWidgetOptionProps<D> {
   data?: D
   theme: typeof CartoTheme
   formatter?: (value: number) => string
+  labelFormatter?: (value: string | number) => string | number
 }
 
 export interface EchartWidgetProps {
@@ -40,4 +41,5 @@ export interface EchartWidgetProps {
   option: EchartUIProps['option']
   onEvents?: EchartUIProps['onEvents']
   formatter?: (value: number) => string
+  labelFormatter?: (value: string | number) => string | number
 }

package/src/widgets/error/error.tsx

@@ -1,6 +1,5 @@
 import { Alert, AlertTitle } from '@mui/material'
-import { useWidgetStore } from '../stores/widget-store'
-import { useShallow } from 'zustand/shallow'
+import { useWidgetSelector } from '../stores/use-widget-selector'
 import type { WidgetErrorProps } from './types'
 
 /**
@@ -19,13 +18,12 @@ export function WidgetError({
   title: titleProp,
   description,
 }: WidgetErrorProps) {
-  const isLoading = useWidgetStore(
-    useShallow((state) => state.widgets[id]?.isLoading),
-  )
-  const isFetching = useWidgetStore(
-    useShallow((state) => state.widgets[id]?.isFetching),
-  )
-  const error = useWidgetStore(useShallow((state) => state.widgets[id]?.error))
+  // Single consolidated subscription instead of 3 separate ones.
+  const { isLoading, isFetching, error } = useWidgetSelector(id, (w) => ({
+    isLoading: w?.isLoading,
+    isFetching: w?.isFetching,
+    error: w?.error,
+  }))
 
   // Don't show error during loading/fetching states
   if (isLoading || isFetching) {

package/src/widgets/formula/components/prefix.tsx

@@ -1,16 +1,14 @@
 import { type FormulaWidgetState, type ValueProps } from '../types'
-import { useWidgetStore } from '../../stores/widget-store'
 import { Item } from './item'
-import { useShallow } from 'zustand/shallow'
+import { useWidgetSelector } from '../../stores/use-widget-selector'
 
 /**
  * Renders the prefix content (e.g., currency symbol) before a formula value, if defined in the data item.
  */
 export function Prefix({ id, index = 0, ...props }: ValueProps) {
-  const prefix = useWidgetStore(
-    useShallow(
-      (state) => state.getWidget<FormulaWidgetState>(id)?.data?.[index]?.prefix,
-    ),
+  const prefix = useWidgetSelector(
+    id,
+    (w) => (w as FormulaWidgetState | undefined)?.data?.[index]?.prefix,
   )
 
   if (!prefix) {

package/src/widgets/formula/components/row.tsx

@@ -1,15 +1,15 @@
 import { Box } from '@mui/material'
 import { styles } from '../style'
 import type { FormulaWidgetState, RowProps } from '../types'
-import { useWidgetStore } from '../../stores/widget-store'
-import { useShallow } from 'zustand/shallow'
+import { useWidgetSelector } from '../../stores/use-widget-selector'
 
 /**
  * Iterates over the widget's data items and renders a row for each one using render props.
  */
 export function Row(props: RowProps) {
-  const data = useWidgetStore(
-    useShallow((state) => state.getWidget<FormulaWidgetState>(props.id)?.data),
+  const data = useWidgetSelector(
+    props.id,
+    (w) => (w as FormulaWidgetState | undefined)?.data,
   )
 
   return data?.map((_, index) => {

package/src/widgets/formula/components/series.tsx

@@ -1,16 +1,14 @@
 import { Avatar } from '@mui/material'
 import type { FormulaWidgetState, ValueProps } from '../types'
-import { useWidgetStore } from '../../stores/widget-store'
-import { useShallow } from 'zustand/shallow'
+import { useWidgetSelector } from '../../stores/use-widget-selector'
 
 /**
  * Renders a colored avatar badge showing the first letter of the series name for multi-value formula widgets.
  */
 export function Series({ id, index = 0 }: Pick<ValueProps, 'id' | 'index'>) {
-  const serie = useWidgetStore(
-    useShallow(
-      (state) => state.getWidget<FormulaWidgetState>(id)?.series?.[index],
-    ),
+  const serie = useWidgetSelector(
+    id,
+    (w) => (w as FormulaWidgetState | undefined)?.series?.[index],
   )
   if (!serie) {
     return null

package/src/widgets/formula/components/suffix.tsx

@@ -1,17 +1,15 @@
 import { type FormulaWidgetState, type ValueProps } from '../types'
-import { useWidgetStore } from '../../stores/widget-store'
 import { Item } from './item'
 import type { Theme } from '@mui/material'
-import { useShallow } from 'zustand/shallow'
+import { useWidgetSelector } from '../../stores/use-widget-selector'
 
 /**
  * Renders the suffix content (e.g., unit label) after a formula value, if defined in the data item.
  */
 export function Suffix({ id, index = 0, ...props }: ValueProps) {
-  const suffix = useWidgetStore(
-    useShallow(
-      (state) => state.getWidget<FormulaWidgetState>(id)?.data?.[index]?.suffix,
-    ),
+  const suffix = useWidgetSelector(
+    id,
+    (w) => (w as FormulaWidgetState | undefined)?.data?.[index]?.suffix,
   )
 
   if (!suffix) {

package/src/widgets/formula/components/value.tsx

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

package/src/widgets/histogram/config.ts

@@ -3,27 +3,104 @@ import {
   mergeEchartWidgetConfig,
   type EchartOptionsProps,
 } from '../echart'
-import type {
-  HistogramConfig,
-  HistogramWidgetConfig,
-  HistogramWidgetData,
-} from './types'
+import type { HistogramConfig, HistogramWidgetConfig } from './types'
 import {
-  flattenObjectArrayToCSV,
   buildLegendConfig,
   buildGridConfig,
   createTooltipPositioner,
   createTooltipFormatter,
-  createChartDownloadConfig,
   niceNum,
 } from '../utils/chart-config'
+import { downloadToCSV, downloadToPNG, type DownloadItem } from '../actions'
+import type { ConfigProps } from '../loader/types'
+
+export interface HistogramDownloadConfigProps extends ConfigProps {
+  ticks: number[]
+  labelFormatter?: (value: string | number) => string | number
+}
+
+export function histogramDataToCSV(
+  data: number[][],
+  ticks: number[],
+  labelFormatter?: (value: string | number) => string | number,
+): string[][] {
+  if (!data?.length || data[0]?.length === 0) return []
+
+  const dataLength = data[0]?.length ?? 0
+  const labels = createAxisLabels(dataLength, ticks, labelFormatter)
+  const seriesCount = data.length
+  const isMulti = seriesCount > 1
+
+  const headers = isMulti
+    ? [
+        'Bin',
+        ...Array.from({ length: seriesCount }, (_, i) => `Series ${i + 1}`),
+      ]
+    : ['Bin', 'Value']
+
+  return [
+    headers,
+    ...labels.map((label, i) => [
+      label,
+      ...data.map((series) => String(series[i] ?? 0)),
+    ]),
+  ]
+}
+
+export function histogramDownloadConfig({
+  refUI,
+  ticks,
+  labelFormatter,
+}: HistogramDownloadConfigProps): DownloadItem<number[][]>[] {
+  return [
+    {
+      ...downloadToPNG,
+      modifier: () => downloadToPNG.modifier(refUI),
+    },
+    {
+      ...downloadToCSV,
+      modifier: async (data) =>
+        downloadToCSV.modifier(histogramDataToCSV(data, ticks, labelFormatter)),
+    },
+  ]
+}
 
-export const histogramDownloadConfig =
-  createChartDownloadConfig<HistogramWidgetData>(flattenObjectArrayToCSV)
 /**
- * Generates ECharts configuration for distribution histogram widgets with adjacent bars (minimal gap) and axis formatting styled with the CARTO theme.
+ * Creates formatted axis labels from tick boundaries.
  *
- * @param props - Histogram configuration including bin data and theme.
+ * @param dataLength - Number of data points (determines number of labels).
+ * @param ticks - Bin boundaries. If `ticks.length === dataLength + 1`, all
+ *   bins are ranges. If `ticks.length === dataLength`, the last bin is
+ *   open-ended (`+`). A last tick of `Infinity` also produces `+`.
+ * @param labelFormatter - Optional formatter applied to each individual tick
+ *   value when building the bin range label.
+ */
+function createAxisLabels(
+  dataLength: number,
+  ticks: number[],
+  labelFormatter?: (value: string | number) => string | number,
+): string[] {
+  const fmt = (v: number) =>
+    labelFormatter ? String(labelFormatter(v)) : String(v)
+
+  return Array.from({ length: dataLength }, (_, i) => {
+    const low = ticks[i] ?? i
+    const high = ticks[i + 1]
+    return high !== undefined && isFinite(high)
+      ? `${fmt(low)}-${fmt(high)}`
+      : `${fmt(low)}+`
+  })
+}
+
+/**
+ * Generates ECharts configuration for distribution histogram widgets with
+ * adjacent bars (minimal gap) and axis formatting styled with the CARTO theme.
+ *
+ * Accepts raw `number[][]` data and `ticks` boundaries. The ticks and
+ * `labelFormatter` are used to create the x-axis category labels; the raw
+ * numeric data is embedded directly in each series.
+ *
+ * @param props - Histogram configuration including raw data, ticks, and theme.
  * @returns Widget config with ECharts option object.
  */
 export function histogramConfig(props: HistogramConfig): HistogramWidgetConfig {
@@ -33,21 +110,27 @@ export function histogramConfig(props: HistogramConfig): HistogramWidgetConfig {
     formatter: props.formatter,
   }
 }
+
 function getOption({
   data = [],
+  ticks,
   theme,
   formatter,
+  labelFormatter,
 }: HistogramConfig): EchartOptionsProps {
   const hasLegend = (data?.length ?? 0) > 1
+  const dataLength = data[0]?.length ?? 0
+  const axisLabels = createAxisLabels(dataLength, ticks, labelFormatter)
 
   let niceMin = 0
   let niceMax = 1
 
   return {
-    legend: buildLegendConfig(hasLegend),
+    legend: buildLegendConfig({ hasLegend }),
     grid: buildGridConfig(hasLegend, theme),
     xAxis: {
       type: 'category',
+      data: axisLabels,
       axisLine: {
         show: false,
       },
@@ -117,14 +200,12 @@ function getOption({
     tooltip: {
       position: createTooltipPositioner(theme),
       formatter: createTooltipFormatter((item) => {
-        const value = item.value as Record<string, string | number>
-        const index = item.dimensionNames?.[item.encode?.y?.at(0) ?? 1]
-        const _value = value[index ?? '']
+        const _value = item.value as number
 
         const formattedValue =
           typeof _value === 'number' && formatter
             ? formatter(_value)
-            : (_value ?? '')
+            : String(_value ?? '')
 
         const marker = typeof item.marker === 'string' ? item.marker : ''
         const seriesName = item.seriesName ? `${item.seriesName}: ` : ''
@@ -133,11 +214,11 @@ function getOption({
         return { name, seriesName, marker, value: formattedValue }
       }),
     },
-    series: data.map((_: unknown, index: number) => ({
-      datasetIndex: index,
+    series: data.map((seriesData: number[]) => ({
       type: 'bar',
-      barGap: '1%', // No gap between bars in histogram
-      barCategoryGap: '1%', // No gap between categories in histogram
+      data: seriesData,
+      barGap: '1%',
+      barCategoryGap: '1%',
       emphasis: {
         focus: 'series',
       },

package/src/widgets/histogram/index.ts

@@ -4,5 +4,10 @@ export type {
   HistogramWidgetData,
   HistogramWidgetState,
 } from './types'
-export { histogramConfig, histogramDownloadConfig } from './config'
+export type { HistogramDownloadConfigProps } from './config'
+export {
+  histogramConfig,
+  histogramDataToCSV,
+  histogramDownloadConfig,
+} from './config'
 export { HistogramSkeleton } from './skeleton'

package/src/widgets/histogram/types.ts

@@ -1,11 +1,11 @@
-import type { EchartWidgetData, EchartWidgetState } from '../echart'
+import type { EchartWidgetState } from '../echart'
 import type {
   EchartWidgetOptionProps,
   EchartWidgetProps,
 } from '../echart/types'
 import type { ConfigProps } from '../loader'
 
-export type HistogramWidgetData = EchartWidgetData
+export type HistogramWidgetData = number[][]
 
 export type HistogramWidgetState = EchartWidgetState
 
@@ -14,4 +14,10 @@ export type HistogramWidgetConfig = EchartWidgetProps & {
 }
 
 export type HistogramConfig = ConfigProps &
-  EchartWidgetOptionProps<HistogramWidgetData>
+  Pick<
+    EchartWidgetOptionProps<unknown>,
+    'theme' | 'formatter' | 'labelFormatter'
+  > & {
+    data?: number[][]
+    ticks: number[]
+  }

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