@carto/ps-react-ui 4.4.1 → 4.4.3

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

@@ -2,15 +2,11 @@ import { Box, IconButton } from '@mui/material'
 import { HighlightAltOutlined } from '@mui/icons-material'
 import { useEffect, useCallback, useRef } from 'react'
 import { useWidgetStore } from '../../stores/widget-store'
-import type { BrushToggleProps } from './types'
+import type { BrushSelectedItems, BrushToggleProps } from './types'
 import { styles } from './style'
 import { Tooltip } from '../../../components'
 import { getEChartBrushConfig } from '../../echart/utils'
-import type {
-  EchartOptionsProps,
-  EchartWidgetData,
-  EchartWidgetState,
-} from '../../echart/types'
+import type { EchartOptionsProps, EchartWidgetState } from '../../echart/types'
 import { useShallow } from 'zustand/shallow'
 
 export const BRUSH_TOGGLE_TOOL_ID = 'brush-toggle'
@@ -44,7 +40,7 @@ export function BrushToggle({
   const registerTool = useWidgetStore((state) => state.registerTool)
   const unregisterTool = useWidgetStore((state) => state.unregisterTool)
   const setToolEnabled = useWidgetStore((state) => state.setToolEnabled)
-  const selected = useRef<(string | number)[]>([])
+  const selected = useRef<BrushSelectedItems>({ dataIndex: [], seriesIndex: 0 })
 
   const brushTool = useWidgetStore(
     useShallow((state) => {
@@ -67,7 +63,7 @@ export function BrushToggle({
     toggleTool(newBrush)
 
     if (newBrush) {
-      onBrushSelected?.([])
+      onBrushSelected?.({ dataIndex: [], seriesIndex: 0 }) // Clear selection when enabling brush
     }
   }, [brush, onBrushSelected, toggleTool])
 
@@ -102,46 +98,47 @@ export function BrushToggle({
   }, [brush, getWidget, id])
 
   // Handle brushSelected event to capture selected bar indices
-  const handleBrushSelected = useCallback(
-    (event: unknown) => {
-      const brushEvent = event as {
-        batch?: {
-          selected?: {
-            dataIndex?: number[]
-            seriesIndex?: number
-          }[]
+  const handleBrushSelected = useCallback((event: unknown) => {
+    const brushEvent = event as {
+      batch?: {
+        selected?: {
+          dataIndex?: number[]
+          seriesIndex?: number
         }[]
+      }[]
+    }
+
+    const allSelected =
+      brushEvent.batch?.flatMap((batchItem) => batchItem.selected ?? []) ?? []
+
+    if (!allSelected.length) {
+      selected.current = {
+        dataIndex: [],
+        seriesIndex: 0,
       }
+      return
+    }
 
-      // Resolve names from the widget dataset
-      const widget = getWidget(id)
-      const data = (widget?.data ?? []) as EchartWidgetData
-
-      const items = [
-        ...new Set(
-          brushEvent.batch?.flatMap(
-            (batch) =>
-              batch.selected?.flatMap(
-                (sel) =>
-                  sel.dataIndex?.map((dataIndex) => {
-                    const row = data[sel.seriesIndex ?? 0]?.[dataIndex]
-                    const firstValue = row ? Object.values(row)[0] : undefined
-                    const name =
-                      typeof firstValue === 'string' ||
-                      typeof firstValue === 'number'
-                        ? String(firstValue)
-                        : String(dataIndex)
-                    return name
-                  }) ?? [],
-              ) ?? [],
-          ),
-        ),
-      ]
-
-      selected.current = items ?? []
-    },
-    [getWidget, id],
-  )
+    // Use the first seriesIndex as the primary one (matches previous behavior)
+    const primarySeriesIndex = allSelected[0]?.seriesIndex ?? 0
+
+    const mergedDataIndex = Array.from(
+      new Set(
+        allSelected
+          .filter(
+            (item) =>
+              item.seriesIndex === undefined ||
+              item.seriesIndex === primarySeriesIndex,
+          )
+          .flatMap((item) => item.dataIndex ?? []),
+      ),
+    )
+
+    selected.current = {
+      dataIndex: mergedDataIndex,
+      seriesIndex: primarySeriesIndex,
+    }
+  }, [])
 
   const handleBrushEnd = useCallback(() => {
     onBrushSelected?.(selected.current)
@@ -169,8 +166,6 @@ export function BrushToggle({
 
         const brushConfig = getEChartBrushConfig()
 
-        const onEventsWithoutBrush = { ...currentOnEvents }
-        delete onEventsWithoutBrush.brushSelected
         const onEvents = {
           ...currentOnEvents,
           brushSelected: handleBrushSelected,

package/src/widgets/actions/brush-toggle/types.ts

@@ -3,9 +3,15 @@ import type { ReactNode } from 'react'
 import type { BaseWidgetState } from '../../stores/types'
 
 /**
- * Represents a single item selected by the brush
+ * Brush selection result emitted by BrushToggle.
+ * Contains raw indices so consumers can resolve data according to their widget type.
  */
-export type BrushSelectedItems = (string | number)[]
+export interface BrushSelectedItems {
+  /** Data indices of the selected items in the dataset */
+  dataIndex: number[]
+  /** Series index from the brush event (defaults to 0) */
+  seriesIndex: number
+}
 
 /**
  * State stored in widget store for brush functionality

package/src/widgets/actions/download/download.tsx

@@ -14,6 +14,17 @@ import { useShallow } from 'zustand/shallow'
 
 const EMPTY_LABELS: NonNullable<DownloadProps['labels']> = {}
 
+/**
+ * Dropdown menu action for exporting widget data in various formats (CSV, PNG, etc.).
+ *
+ * Reads widget data from the store and triggers downloads using the modifier
+ * function defined in each `DownloadItem`.
+ *
+ * @example
+ * ```tsx
+ * <Download id={widgetId} items={barDownloadConfig({ refUI })} />
+ * ```
+ */
 export function Download({
   id,
   items,

package/src/widgets/actions/download/exports.tsx

@@ -28,6 +28,12 @@ async function downloadFileToCSV<D>(data: D[][]) {
   return Promise.resolve(URL.createObjectURL(blob))
 }
 
+/**
+ * Pre-configured download item for exporting widget data as a CSV file.
+ *
+ * Converts a 2D array of data into CSV format with proper escaping and
+ * triggers a browser download. Revokes the object URL after download.
+ */
 export const downloadToCSV: DownloadItem<unknown[][]> = {
   id: 'csv',
   label: 'CSV',
@@ -91,6 +97,15 @@ async function downloadFileToPNG(ref: Ref<HTMLElement | null> | undefined) {
   return Promise.resolve(result)
 }
 
+/**
+ * Pre-configured download item for exporting a widget as a PNG image.
+ *
+ * Uses html2canvas to capture the widget DOM element referenced by a React ref.
+ * Strips toolbar and action elements before capturing.
+ *
+ * @remarks
+ * The modifier expects a React ref to the widget's root HTML element, not raw data.
+ */
 export const downloadToPNG: Omit<DownloadItem, 'modifier'> & {
   modifier: (
     ref: Ref<HTMLElement | null> | undefined,

package/src/widgets/actions/fullscreen/fullscreen.tsx

@@ -19,6 +19,19 @@ const EMPTY_DIALOG_CONTENT_PROPS: NonNullable<
   FullScreenProps['DialogContentProps']
 > = {}
 
+/**
+ * Displays widget content in a fullscreen modal dialog.
+ *
+ * Manages fullscreen state via the widget store and renders a MUI Dialog
+ * with the widget title and a close button.
+ *
+ * @example
+ * ```tsx
+ * <FullScreen id="my-widget" labels={{ ariaLabel: 'Expand chart' }}>
+ *   <ChartContent id="my-widget" />
+ * </FullScreen>
+ * ```
+ */
 export function FullScreen({
   id,
   labels,

package/src/widgets/actions/index.ts

@@ -11,6 +11,7 @@ export { downloadToCSV, downloadToPNG } from './download/exports'
 export {
   RelativeData,
   RELATIVE_DATA_TOOL_ID,
+  RELATIVE_DATA_CONFIG_TOOL_ID,
 } from './relative-data/relative-data'
 export type { RelativeDataProps } from './relative-data/types'
 

package/src/widgets/actions/relative-data/relative-data.test.tsx

@@ -1,6 +1,10 @@
 import { describe, test, expect, beforeEach } from 'vitest'
 import { render, screen, fireEvent, waitFor } from '@testing-library/react'
-import { RelativeData, RELATIVE_DATA_TOOL_ID } from './relative-data'
+import {
+  RelativeData,
+  RELATIVE_DATA_TOOL_ID,
+  RELATIVE_DATA_CONFIG_TOOL_ID,
+} from './relative-data'
 import { useWidgetStore } from '../../stores/widget-store'
 import type { EchartWidgetData } from '../../echart/types'
 
@@ -223,6 +227,63 @@ describe('RelativeData', () => {
     expect(button.hasAttribute('disabled')).toBeTruthy()
   })
 
+  test('registers config tool on mount', async () => {
+    render(<RelativeData id={widgetId} />)
+
+    await waitFor(() => {
+      const widget = useWidgetStore.getState().getWidget(widgetId)
+      const tool = widget?.registeredTools?.find(
+        (t) => t.id === RELATIVE_DATA_CONFIG_TOOL_ID,
+      )
+      expect(tool).toBeTruthy()
+      expect(tool?.type).toBe('config')
+      expect(tool?.enabled).toBe(true)
+    })
+  })
+
+  test('sets formatter via config pipeline when toggling to relative mode', async () => {
+    useWidgetStore.getState().setWidget(widgetId, { max: 500 })
+
+    render(<RelativeData id={widgetId} />)
+
+    const button = screen.getByRole('button')
+    fireEvent.click(button)
+
+    await waitFor(() => {
+      const widget = useWidgetStore.getState().getWidget(widgetId)
+      const tool = widget?.registeredTools?.find(
+        (t) => t.id === RELATIVE_DATA_CONFIG_TOOL_ID,
+      )
+      expect(tool?.config?.isRelative).toBe(true)
+      expect(tool?.config?.originalFormatter).toBeUndefined()
+      expect(tool?.config?.originalMax).toBe(500)
+    })
+  })
+
+  test('restores original formatter via config pipeline when toggling back', () => {
+    const customFormatter = (value: number) => `$${value}`
+    useWidgetStore
+      .getState()
+      .setWidget(widgetId, { formatter: customFormatter, max: 200 })
+
+    render(<RelativeData id={widgetId} />)
+
+    const button = screen.getByRole('button')
+
+    // Toggle to relative
+    fireEvent.click(button)
+    // Toggle back to absolute
+    fireEvent.click(button)
+
+    const widget = useWidgetStore.getState().getWidget(widgetId)
+    const tool = widget?.registeredTools?.find(
+      (t) => t.id === RELATIVE_DATA_CONFIG_TOOL_ID,
+    )
+    expect(tool?.config?.isRelative).toBe(false)
+    expect(tool?.config?.originalFormatter).toBe(customFormatter)
+    expect(tool?.config?.originalMax).toBe(200)
+  })
+
   test('recalculates relative values when store data changes externally while in relative mode', async () => {
     const initialData: EchartWidgetData = [
       [

package/src/widgets/actions/relative-data/relative-data.tsx

@@ -2,13 +2,14 @@ import { IconButton } from '@mui/material'
 import { PercentOutlined } from '@mui/icons-material'
 import { useCallback, useEffect, useRef } from 'react'
 import { useWidgetStore } from '../../stores/widget-store'
-import type { RelativeDataProps, RelativeDataState } from './types'
+import type { RelativeDataProps } from './types'
 import { actionButtonStyles } from '../shared/styles'
 import { Tooltip } from '../../../components'
 import { calculateTotal, toRelativeData } from './utils'
 import type { EchartWidgetData } from '../../../widgets/echart'
 
 export const RELATIVE_DATA_TOOL_ID = 'relative-data'
+export const RELATIVE_DATA_CONFIG_TOOL_ID = 'relative-data-config'
 
 /**
  * Widget action to toggle between relative (percentage) and absolute data display.
@@ -33,36 +34,30 @@ export function RelativeData({
   Icon,
   IconButtonProps,
 }: RelativeDataProps) {
-  const previousMaxValue = useRef<number | undefined>(undefined)
-  const originalFormatter = useRef<((value: number) => string) | undefined>(
+  const percentFormatterRef = useRef<((value: number) => string) | undefined>(
     undefined,
   )
-  const setWidget = useWidgetStore((state) => state.setWidget)
   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 storeIsRelative = useWidgetStore(
-    (state) => state.getWidget<RelativeDataState>(id)?.isRelative,
+    (state) =>
+      state.widgets[id]?.registeredTools?.find(
+        (t) => t.id === RELATIVE_DATA_CONFIG_TOOL_ID,
+      )?.config?.isRelative as boolean | undefined,
   )
 
   const isRelative = storeIsRelative ?? defaultIsRelative
 
-  // Initialize store with default value on mount
-  useEffect(() => {
-    const currentValue = getWidget<RelativeDataState>(id)?.isRelative
-    if (currentValue === undefined) {
-      setWidget(id, { isRelative: defaultIsRelative })
-    }
-  }, [defaultIsRelative, getWidget, id, setWidget])
-
   // Register tool on mount
   useEffect(() => {
     registerTool(id, {
       id: RELATIVE_DATA_TOOL_ID,
       order,
-      enabled: isRelative,
+      enabled: defaultIsRelative,
       fn: (data) => {
         const echartData = data as EchartWidgetData
         const total = calculateTotal(echartData)
@@ -71,42 +66,70 @@ export function RelativeData({
     })
 
     return () => unregisterTool(id, RELATIVE_DATA_TOOL_ID)
-  }, [id, order, registerTool, unregisterTool, isRelative])
+  }, [id, order, registerTool, unregisterTool, defaultIsRelative])
+
+  // Register config tool for formatter management
+  useEffect(() => {
+    registerTool(id, {
+      id: RELATIVE_DATA_CONFIG_TOOL_ID,
+      type: 'config',
+      order,
+      enabled: true,
+      fn: (currentConfig, toolConfig) => {
+        const config = currentConfig as Record<string, unknown>
+        if (toolConfig?.isRelative) {
+          if (!percentFormatterRef.current) {
+            const locale = toolConfig?.locale as string | undefined
+            percentFormatterRef.current = (value: number) =>
+              new Intl.NumberFormat(locale, {
+                style: 'percent',
+                minimumFractionDigits: 1,
+                maximumFractionDigits: 1,
+              }).format(value / 100)
+          }
+          return { ...config, formatter: percentFormatterRef.current, max: 100 }
+        }
+        // Switching back from relative mode
+        percentFormatterRef.current = undefined
+        if (toolConfig && 'originalFormatter' in toolConfig) {
+          return {
+            ...config,
+            formatter: toolConfig.originalFormatter,
+            max: toolConfig.originalMax,
+          }
+        }
+        return config
+      },
+      config: {
+        isRelative: defaultIsRelative,
+      },
+    })
+    return () => unregisterTool(id, RELATIVE_DATA_CONFIG_TOOL_ID)
+  }, [id, order, registerTool, unregisterTool, defaultIsRelative])
 
   const handleToggle = useCallback(() => {
     const newIsRelative = !isRelative
     setToolEnabled(id, RELATIVE_DATA_TOOL_ID, newIsRelative)
-    let max = previousMaxValue.current
 
     if (newIsRelative) {
-      // Backup current formatter to ref
       const widget = getWidget(id) as {
         formatter?: (value: number) => string
         locale?: string
+        max?: number
       }
-      originalFormatter.current = widget?.formatter
-
-      // Save current max value before setting to 100
-      const currentMax = (getWidget(id) as { max?: number })?.max
-      previousMaxValue.current = currentMax
-      max = 100
+      updateToolConfig(id, RELATIVE_DATA_CONFIG_TOOL_ID, {
+        isRelative: true,
+        originalFormatter: widget?.formatter,
+        originalMax: widget?.max,
+        locale: widget?.locale,
+      })
+    } else {
+      percentFormatterRef.current = undefined
+      updateToolConfig(id, RELATIVE_DATA_CONFIG_TOOL_ID, {
+        isRelative: false,
+      })
     }
-
-    setWidget(id, {
-      isRelative: newIsRelative,
-      max,
-      formatter: newIsRelative
-        ? (value: number) => {
-            const widget = getWidget(id) as { locale?: string }
-            return new Intl.NumberFormat(widget?.locale, {
-              style: 'percent',
-              minimumFractionDigits: 1,
-              maximumFractionDigits: 1,
-            }).format(value / 100)
-          }
-        : originalFormatter.current,
-    })
-  }, [isRelative, setWidget, id, getWidget, setToolEnabled])
+  }, [isRelative, id, getWidget, setToolEnabled, updateToolConfig])
 
   const tooltipLabel = isRelative
     ? (labels?.absolute ?? 'Show absolute values')

package/src/widgets/bar/config.ts

@@ -10,33 +10,27 @@ import {
   buildGridConfig,
   createTooltipPositioner,
   createTooltipFormatter,
+  createChartDownloadConfig,
+  applyXAxisFormatter,
   niceNum,
-} from '../_shared/chart-config'
-import { downloadToCSV, downloadToPNG, type DownloadItem } from '../actions'
-import type { ConfigProps } from '../loader/types'
+} 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 +38,7 @@ function getOption({
   data = [],
   theme,
   formatter,
+  labelFormatter,
 }: BarConfig): EchartOptionsProps {
   const hasLegend = (data?.length ?? 0) > 1
 
@@ -51,21 +46,24 @@ 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,
+        },
       },
-    },
+      labelFormatter,
+    ),
     yAxis: {
       type: 'value' as const,
       min: (extent: { min: number }) => {
@@ -118,7 +116,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 }
       }),

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

@@ -10,14 +10,21 @@ import {
 } from './components'
 import { useShallow } from 'zustand/shallow'
 import { useState } from 'react'
+import { defaultFormatter, defaultLabelFormatter } from '../utils/formatter'
 
-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 theme = useTheme()
   const _formatter = useWidgetStore(
     useShallow((state) => state.getWidget<CategoryWidgetState>(id)?.formatter),
   )
+  const _labelFormatter = useWidgetStore(
+    useShallow(
+      (state) => state.getWidget<CategoryWidgetState>(id)?.labelFormatter,
+    ),
+  )
   const _series = useWidgetStore(
     useShallow((state) => state.getWidget<CategoryWidgetState>(id)?.series),
   )
@@ -41,6 +48,7 @@ export function CategoryUI({ id }: CategoryUIProps) {
   )
 
   const formatter = _formatter ?? defaultFormatter
+  const labelFormatter = _labelFormatter ?? defaultLabelFormatter
   const series = _series ?? []
 
   const [maxHeight] = useState<string | number | undefined>(
@@ -98,6 +106,7 @@ export function CategoryUI({ id }: CategoryUIProps) {
                 maxValue={maxValue}
                 colors={colors}
                 formatter={formatter}
+                labelFormatter={labelFormatter}
                 onClick={onRowClick}
                 selected={selected?.(item.name) ?? true}
               />
@@ -111,6 +120,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}