@carto/ps-react-ui 4.4.0-chat-ui.6 → 4.4.0-chat-ui.7

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

@@ -4,13 +4,13 @@ import {
   ZoomInOutlined,
 } from '@mui/icons-material'
 import { useEffect, useCallback } from 'react'
-import { useWidgetStore } from '../../stores/widget-store'
-import type { ZoomToggleProps } from './types'
+import { widgetStoreActions } from '../../stores/widget-store'
+import type { ZoomToggleProps, ZoomState } from './types'
 import { styles } from './style'
 import { Tooltip } from '../../../components'
 import { getEChartZoomConfig } from '../../echart/utils'
 import type { EchartOptionsProps } from '../../echart/types'
-import { useShallow } from 'zustand/shallow'
+import { useWidgetSelector } from '../../stores/use-widget-selector'
 
 export const ZOOM_TOGGLE_TOOL_ID = 'zoom-toggle'
 
@@ -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.
  *
@@ -44,26 +48,27 @@ export function ZoomToggle({
   IconButtonProps,
 }: ZoomToggleProps) {
   const theme = useTheme()
-  const getWidget = useWidgetStore((state) => state.getWidget)
-  const registerTool = useWidgetStore((state) => state.registerTool)
-  const unregisterTool = useWidgetStore((state) => state.unregisterTool)
-  const setToolEnabled = useWidgetStore((state) => state.setToolEnabled)
-  const updateToolConfig = useWidgetStore((state) => state.updateToolConfig)
-
-  const zoomTool = useWidgetStore(
-    useShallow((state) => {
-      const tools = state.getWidget(id)?.registeredTools ?? []
-      return tools.find((tool) => tool.id === ZOOM_TOGGLE_TOOL_ID)
-    }),
-  )
 
-  const zoom = zoomTool?.enabled ?? defaultZoom
-  const zoomStart =
-    (zoomTool?.config?.start as number | undefined) ?? defaultZoomStart
-  const 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,
+  }))
 
-  // Handle dataZoom event to update zoom range in tool config
+  // 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 — update store (source of truth)
   const handleDataZoom = useCallback(
     (event: unknown) => {
       const zoomEvent = event as {
@@ -79,43 +84,32 @@ export function ZoomToggle({
       const end = zoomEvent.end ?? zoomEvent.batch?.[0]?.end
 
       if (start !== undefined && end !== undefined) {
-        setToolEnabled(id, ZOOM_TOGGLE_TOOL_ID, true)
-        updateToolConfig(id, ZOOM_TOGGLE_TOOL_ID, {
-          enabled: true,
-          start,
-          end,
+        widgetStoreActions.setWidget(id, {
+          zoom: true,
+          zoomStart: start,
+          zoomEnd: end,
         })
       }
     },
-    [id, setToolEnabled, updateToolConfig],
+    [id],
   )
 
-  // Register config tool on mount
+  // Register config tool once — fn reads zoom range from the store at execution time.
   useEffect(() => {
-    const existingTool = 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
-
-    registerTool(id, {
+    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 enabled = (toolConfig?.enabled as boolean) ?? false
-        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
@@ -125,7 +119,6 @@ export function ZoomToggle({
         const legendBottomOffset = hasLegend ? 28 : 0
 
         const zoomConfig = getEChartZoomConfig(
-          enabled,
           { start, end },
           {
             inside: true,
@@ -142,15 +135,9 @@ export function ZoomToggle({
             ? grid.bottom
             : parseInt(grid?.bottom ?? '24')
 
-        const gridBottom = enabled
-          ? currentGridBottom + sliderHeight + sliderGap
-          : currentGridBottom
+        const gridBottom = currentGridBottom + sliderHeight + sliderGap
 
-        const onEventsWithoutDataZoom = { ...currentOnEvents }
-        delete onEventsWithoutDataZoom.dataZoom
-        const onEvents = enabled
-          ? { ...currentOnEvents, dataZoom: handleDataZoom }
-          : onEventsWithoutDataZoom
+        const onEvents = { ...currentOnEvents, dataZoom: handleDataZoom }
 
         return {
           ...config,
@@ -162,41 +149,36 @@ export function ZoomToggle({
           onEvents,
         }
       },
-      config: {
-        enabled: initialEnabled,
-        start: initialStart,
-        end: initialEnd,
-      },
     })
-    return () => unregisterTool(id, ZOOM_TOGGLE_TOOL_ID)
-  }, [
-    defaultZoom,
-    defaultZoomEnd,
-    defaultZoomStart,
-    getWidget,
-    handleDataZoom,
-    id,
-    registerTool,
-    theme,
-    unregisterTool,
-  ])
+    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
-    setToolEnabled(id, ZOOM_TOGGLE_TOOL_ID, newZoom)
-    updateToolConfig(id, ZOOM_TOGGLE_TOOL_ID, {
-      enabled: newZoom,
-      start: newZoom ? zoomStart : 0,
-      end: newZoom ? zoomEnd : 100,
+    widgetStoreActions.setWidget(id, {
+      zoom: newZoom,
+      zoomStart: newZoom ? zoomStart : 0,
+      zoomEnd: newZoom ? zoomEnd : 100,
     })
   }
 
   const handleReset = () => {
-    setToolEnabled(id, ZOOM_TOGGLE_TOOL_ID, true)
-    updateToolConfig(id, ZOOM_TOGGLE_TOOL_ID, {
-      enabled: true,
-      start: defaultZoomStart,
-      end: defaultZoomEnd,
+    widgetStoreActions.setWidget(id, {
+      zoom: true,
+      zoomStart: defaultZoomStart,
+      zoomEnd: defaultZoomEnd,
     })
   }
 

package/src/widgets/bar/config.ts

@@ -10,33 +10,28 @@ import {
   buildGridConfig,
   createTooltipPositioner,
   createTooltipFormatter,
+  createChartDownloadConfig,
+  applyXAxisFormatter,
   niceNum,
-} from '../_shared/chart-config'
-import { downloadToCSV, downloadToPNG, type DownloadItem } from '../actions'
-import type { ConfigProps } from '../loader/types'
+  buildSeriesLabelConfig,
+} from '../utils/chart-config'
 
-export function barDownloadConfig({
-  refUI,
-}: ConfigProps): DownloadItem<BarWidgetData>[] {
-  return [
-    {
-      ...downloadToPNG,
-      modifier: () => downloadToPNG.modifier(refUI),
-    },
-    {
-      ...downloadToCSV,
-      modifier: async (data) => {
-        const rows = flattenObjectArrayToCSV(data)
-        return downloadToCSV.modifier(rows)
-      },
-    },
-  ]
-}
+export const barDownloadConfig = createChartDownloadConfig<BarWidgetData>(
+  flattenObjectArrayToCSV,
+)
 
+/**
+ * Generates ECharts configuration for bar chart widgets (vertical and horizontal), including axis, tooltip, legend, and series options styled with the CARTO theme.
+ *
+ * @param props - Bar chart configuration including data and theme.
+ * @returns Widget config with ECharts option object.
+ */
 export function barConfig(props: BarConfig): BarWidgetConfig {
   return {
     type: 'bar',
     option: mergeEchartWidgetConfig(getCommonOptions(props), getOption(props)),
+    formatter: props.formatter,
+    labelFormatter: props.labelFormatter,
   }
 }
 
@@ -44,6 +39,7 @@ function getOption({
   data = [],
   theme,
   formatter,
+  labelFormatter,
 }: BarConfig): EchartOptionsProps {
   const hasLegend = (data?.length ?? 0) > 1
 
@@ -51,21 +47,27 @@ function getOption({
   let niceMax = 1
 
   return {
-    legend: buildLegendConfig(hasLegend),
+    legend: buildLegendConfig({ hasLegend, labelFormatter }),
     grid: buildGridConfig(hasLegend, theme),
-    xAxis: {
-      type: 'category',
-      axisLine: {
-        show: false,
-      },
-      axisTick: {
-        show: false,
-      },
-      axisLabel: {
-        padding: [parseInt(theme.spacing(0.5)), 0, 0, 0],
-        margin: 0,
+    xAxis: applyXAxisFormatter(
+      {
+        type: 'category',
+        axisLine: {
+          show: false,
+        },
+        axisTick: {
+          show: false,
+        },
+        axisLabel: {
+          padding: [parseInt(theme.spacing(0.5)), 0, 0, 0],
+          margin: 0,
+          showMinLabel: undefined,
+          showMaxLabel: undefined,
+          hideOverlap: true,
+        },
       },
-    },
+      labelFormatter,
+    ),
     yAxis: {
       type: 'value' as const,
       min: (extent: { min: number }) => {
@@ -118,7 +120,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 }
       }),
@@ -130,6 +134,7 @@ function getOption({
       emphasis: {
         focus: 'series',
       },
+      ...buildSeriesLabelConfig(formatter),
     })),
   } as EchartOptionsProps
 }

package/src/widgets/bar/style.ts

@@ -1,5 +1,5 @@
 import type { SxProps, Theme } from '@mui/material'
-import { baseSkeletonStyles } from '../_shared/skeleton'
+import { baseSkeletonStyles } from '../utils/skeleton'
 
 export const styles = {
   skeleton: {

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

@@ -1,46 +1,50 @@
 import { Box, useTheme } from '@mui/material'
-import { useWidgetStore } from '../stores/widget-store'
+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 { useShallow } from 'zustand/shallow'
+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'
 
-const defaultFormatter = (value: number) => value.toString()
-
+/**
+ * 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()
-  const _formatter = useWidgetStore(
-    useShallow((state) => state.getWidget<CategoryWidgetState>(id)?.formatter),
-  )
-  const _series = useWidgetStore(
-    useShallow((state) => state.getWidget<CategoryWidgetState>(id)?.series),
-  )
-  const data = useWidgetStore(
-    useShallow((state) => state.getWidget<CategoryWidgetState>(id)?.data),
-  )
-  const maxItems = useWidgetStore(
-    useShallow((state) => state.getWidget<CategoryWidgetState>(id)?.maxItems),
-  )
-  const labels = useWidgetStore(
-    useShallow((state) => state.getWidget<CategoryWidgetState>(id)?.labels),
-  )
-  const onRowClick = useWidgetStore(
-    useShallow((state) => state.getWidget<CategoryWidgetState>(id)?.onRowClick),
-  )
-  const selected = useWidgetStore(
-    useShallow((state) => state.getWidget<CategoryWidgetState>(id)?.selected),
-  )
-  const max = useWidgetStore(
-    useShallow((state) => state.getWidget<CategoryWidgetState>(id)?.max),
-  )
+
+  // Single consolidated subscription instead of 9 separate ones.
+  const {
+    _formatter,
+    _labelFormatter,
+    _series,
+    data,
+    maxItems,
+    labels,
+    onRowClick,
+    selected,
+    max,
+  } = useWidgetSelector(id, (w) => {
+    const cw = w as CategoryWidgetState | undefined
+    return {
+      _formatter: cw?.formatter,
+      _labelFormatter: cw?.labelFormatter,
+      _series: cw?.series,
+      data: cw?.data,
+      maxItems: cw?.maxItems,
+      labels: cw?.labels,
+      onRowClick: cw?.onRowClick,
+      selected: cw?.selected,
+      max: cw?.max,
+    }
+  })
 
   const formatter = _formatter ?? defaultFormatter
+  const labelFormatter = _labelFormatter ?? defaultLabelFormatter
   const series = _series ?? []
 
   const [maxHeight] = useState<string | number | undefined>(
@@ -81,6 +85,7 @@ export function CategoryUI({ id }: CategoryUIProps) {
 
   return (
     <Box
+      ref={ref}
       sx={{
         ...styles.root,
       }}
@@ -98,6 +103,7 @@ export function CategoryUI({ id }: CategoryUIProps) {
                 maxValue={maxValue}
                 colors={colors}
                 formatter={formatter}
+                labelFormatter={labelFormatter}
                 onClick={onRowClick}
                 selected={selected?.(item.name) ?? true}
               />
@@ -111,6 +117,7 @@ export function CategoryUI({ id }: CategoryUIProps) {
                 maxValue={maxValue}
                 color={colors[0]!}
                 formatter={formatter}
+                labelFormatter={labelFormatter}
                 onClick={onRowClick}
               />
             ))}

package/src/widgets/category/components/category-bar.tsx

@@ -8,6 +8,9 @@ export interface CategoryBarProps {
   selected?: boolean
 }
 
+/**
+ * Renders a single horizontal bar fill proportional to its value relative to the maximum.
+ */
 export function CategoryBar({
   value,
   maxValue,

package/src/widgets/category/components/category-legend.tsx

@@ -7,6 +7,9 @@ export interface CategoryLegendProps {
   colors: string[]
 }
 
+/**
+ * Renders a color-coded legend for multi-series category widgets.
+ */
 export function CategoryLegend({ series, colors }: CategoryLegendProps) {
   if (series.length === 0) {
     return null

package/src/widgets/category/components/category-row-multi.tsx

@@ -9,16 +9,21 @@ export interface CategoryRowMultiProps {
   maxValue: number
   colors: string[]
   formatter: NonNullable<CategoryWidgetConfig['formatter']>
+  labelFormatter?: CategoryWidgetConfig['labelFormatter']
   onClick?: CategoryWidgetConfig['onRowClick']
   selected?: boolean
 }
 
+/**
+ * Renders a multi-series category row with a label and multiple color-coded bars stacked vertically.
+ */
 export function CategoryRowMulti({
   name,
   values,
   maxValue,
   colors,
   formatter,
+  labelFormatter,
   onClick,
   selected = true,
 }: CategoryRowMultiProps) {
@@ -27,10 +32,12 @@ export function CategoryRowMulti({
 
   return (
     <Box sx={rowStyle} onClick={handleClick}>
-      <Typography sx={styles.rowLabel}>{name}</Typography>
+      <Typography sx={styles.rowLabel}>
+        {labelFormatter ? labelFormatter(name) : name}
+      </Typography>
       <Box sx={styles.barContainer}>
         {values.map((value, index) => (
-          <Box key={`${name}-${value}`} sx={styles.multiBarRow}>
+          <Box key={`${name}-${value}-${index}`} sx={styles.multiBarRow}>
             <Box sx={styles.multiBarContainer}>
               <CategoryBar
                 value={value}

package/src/widgets/category/components/category-row-other.tsx

@@ -7,6 +7,9 @@ export interface CategoryRowOtherProps {
   otherCountLabel?: string
 }
 
+/**
+ * Renders an "Other" summary row indicating how many additional categories are hidden beyond `maxItems`.
+ */
 export function CategoryRowOther({
   hiddenCount,
   otherLabel = 'Other',

package/src/widgets/category/components/category-row-single.tsx

@@ -9,16 +9,21 @@ export interface CategoryRowSingleProps {
   maxValue: number
   color: string
   formatter: NonNullable<CategoryWidgetConfig['formatter']>
+  labelFormatter?: CategoryWidgetConfig['labelFormatter']
   onClick?: CategoryWidgetConfig['onRowClick']
   selected?: boolean
 }
 
+/**
+ * Renders a single-series category row with a label, formatted value, and proportional bar.
+ */
 export function CategoryRowSingle({
   name,
   value,
   maxValue,
   color,
   formatter,
+  labelFormatter,
   onClick,
   selected = true,
 }: CategoryRowSingleProps) {
@@ -33,7 +38,9 @@ export function CategoryRowSingle({
   return (
     <Box sx={rowStyle} onClick={handleClick}>
       <Box sx={styles.rowHeader}>
-        <Typography sx={styles.rowLabel}>{name}</Typography>
+        <Typography sx={styles.rowLabel}>
+          {labelFormatter ? labelFormatter(name) : name}
+        </Typography>
         <Typography sx={styles.rowValue}>{formatter(value)}</Typography>
       </Box>
       <CategoryBar