@carto/ps-react-ui 4.4.2 → 4.5.0

package/src/widgets/pie/config.ts

@@ -29,6 +29,7 @@ export function pieConfig(props: PieConfig): PieWidgetConfig {
     type: 'pie',
     option: mergeEchartWidgetConfig(getCommonOptions(props), getOption(props)),
     formatter: props.formatter,
+    labelFormatter: props.labelFormatter,
   }
 }
 
@@ -36,6 +37,7 @@ function getOption({
   data = [],
   theme,
   formatter,
+  labelFormatter,
 }: PieConfig): EchartOptionsProps {
   const multiSeries = (data?.length ?? 0) > 1
 
@@ -44,7 +46,7 @@ function getOption({
     let niceMax = 1
 
     return {
-      legend: buildLegendConfig(true),
+      legend: buildLegendConfig({ hasLegend: true, labelFormatter }),
       grid: {
         ...buildGridConfig(true, theme),
         right: parseInt(theme.spacing(4)),
@@ -97,6 +99,10 @@ function getOption({
         },
         axisLabel: {
           padding: [parseInt(theme.spacing(0.5)), 0, 0, 0],
+          ...(labelFormatter && {
+            formatter: (value: string | number) =>
+              String(labelFormatter(value)),
+          }),
         },
       },
       tooltip: {
@@ -113,7 +119,9 @@ function getOption({
 
           const marker = typeof item.marker === 'string' ? item.marker : ''
           const seriesName = item.seriesName ? `${item.seriesName}: ` : ''
-          const name = item.name ?? ''
+          const name = labelFormatter
+            ? String(labelFormatter(item.name ?? ''))
+            : (item.name ?? '')
 
           return { name, seriesName, marker, value: formattedValue }
         }),
@@ -132,7 +140,7 @@ function getOption({
   const hasLegend = true
 
   return {
-    legend: buildLegendConfig(hasLegend),
+    legend: buildLegendConfig({ hasLegend, labelFormatter }),
     grid: {
       ...buildGridConfig(hasLegend, theme),
       left: 0,
@@ -164,7 +172,9 @@ function getOption({
 
         const marker = typeof item.marker === 'string' ? item.marker : ''
         const seriesName = item.seriesName ? `${item.seriesName}: ` : ''
-        const name = item.name ?? ''
+        const name = labelFormatter
+          ? String(labelFormatter(item.name ?? ''))
+          : (item.name ?? '')
 
         return {
           name: seriesName,
@@ -203,7 +213,9 @@ function getOption({
               ? formatter(value)
               : (value ?? '')
 
-          const nameFormatted = name
+          const nameFormatted = labelFormatter
+            ? String(labelFormatter(name ?? ''))
+            : (name ?? '')
 
           return `{c|${formattedValue}}\n\n{b|${nameFormatted}}`
         },

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/scatterplot/config.ts

@@ -14,6 +14,7 @@ import {
   createTooltipFormatter,
   createChartDownloadConfig,
   applyYAxisFormatter,
+  applyXAxisFormatter,
 } from '../utils/chart-config'
 
 export const scatterplotDownloadConfig =
@@ -32,6 +33,7 @@ export function scatterplotConfig(
     type: 'scatterplot',
     option: mergeEchartWidgetConfig(getCommonOptions(props), getOption(props)),
     formatter: props.formatter,
+    labelFormatter: props.labelFormatter,
   }
 }
 
@@ -39,6 +41,7 @@ function getOption({
   data = [],
   theme,
   formatter,
+  labelFormatter,
 }: ScatterplotConfig): EchartOptionsProps {
   const hasLegend = data.length > 1
 
@@ -94,12 +97,12 @@ function getOption({
   }
 
   return {
-    legend: buildLegendConfig(hasLegend),
+    legend: buildLegendConfig({ hasLegend, labelFormatter }),
     grid: {
       ...(!hasLegend && { bottom: parseInt(theme.spacing(1)) }),
       ...(hasLegend && { bottom: parseInt(theme.spacing(10)) }),
     },
-    xAxis,
+    xAxis: applyXAxisFormatter(xAxis, labelFormatter),
     yAxis: applyYAxisFormatter(yAxis, formatter),
     tooltip: {
       trigger: 'item',
@@ -114,7 +117,9 @@ function getOption({
             ? formatter(_value)
             : (_value ?? '')
         const marker = typeof item.marker === 'string' ? item.marker : ''
-        const name = item.seriesName ?? ''
+        const name = labelFormatter
+          ? String(labelFormatter(item.seriesName ?? ''))
+          : (item.seriesName ?? '')
 
         return { name, seriesName: '', marker, value: formattedValue }
       }),

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/types.ts

@@ -31,6 +31,8 @@ export interface WidgetsStoreProps {
   registeredTools?: ToolRegistration[]
   /** Formatter function for widget values */
   formatter?: (value: number) => string
+  /** Formatter function for widget label/category values */
+  labelFormatter?: (value: string | number) => string | number
   /** Locale for number formatting (e.g., 'en-US', 'es-ES', 'fr-FR') */
   locale?: string
 }

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]),
+    ),
+  )
+}