@carto/ps-react-ui 4.4.1 → 4.4.2

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,25 @@ import {
   buildGridConfig,
   createTooltipPositioner,
   createTooltipFormatter,
+  createChartDownloadConfig,
   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,
   }
 }
 

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,9 +10,11 @@ import {
 } from './components'
 import { useShallow } from 'zustand/shallow'
 import { useState } from 'react'
+import { defaultFormatter } 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(

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

@@ -13,6 +13,9 @@ export interface CategoryRowMultiProps {
   selected?: boolean
 }
 
+/**
+ * Renders a multi-series category row with a label and multiple color-coded bars stacked vertically.
+ */
 export function CategoryRowMulti({
   name,
   values,

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

@@ -13,6 +13,9 @@ export interface CategoryRowSingleProps {
   selected?: boolean
 }
 
+/**
+ * Renders a single-series category row with a label, formatted value, and proportional bar.
+ */
 export function CategoryRowSingle({
   name,
   value,

package/src/widgets/category/config.ts

@@ -10,6 +10,12 @@ interface CategoryDownloadConfigProps extends ConfigProps {
   series?: CategorySeriesConfig[]
 }
 
+/**
+ * Creates download configuration for category widgets, supporting PNG (screenshot) and CSV (data) exports. CSV output groups values by category across multiple series.
+ *
+ * @param props - Configuration with `refUI` reference and optional `series` for CSV column headers.
+ * @returns Array of download items for use with the Download action.
+ */
 export function categoryDownloadConfig({
   refUI,
   series,
@@ -66,6 +72,11 @@ export function categoryDownloadConfig({
   ]
 }
 
+/**
+ * Returns the default configuration for category list widgets, including empty series and a default `maxItems` of 10.
+ *
+ * @returns Default category widget config.
+ */
 export function categoryConfig(): CategoryWidgetConfig {
   return {
     series: [],

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

@@ -3,6 +3,13 @@ import * as echarts from 'echarts'
 import type { EchartUIProps } from './types'
 import { useWidgetRef } from '../../hooks'
 
+/**
+ * Presentational component that initializes and manages an Apache ECharts instance.
+ *
+ * @remarks
+ * Handles chart lifecycle (init, dispose), option updates, resize observation, and event listener management.
+ * Uses SVG renderer with a default height of 304px.
+ */
 export function EchartUI(props: EchartUIProps) {
   const { id, ref, init, option, className, style, onEvents } = props
 

package/src/widgets/echart/echart.tsx

@@ -9,6 +9,12 @@ import { useWidgetStore } from '../stores/widget-store'
 import { useShallow } from 'zustand/shallow'
 import { useMemo } from 'react'
 
+/**
+ * Stateful EChart widget component that reads data and options from the widget store and renders an ECharts chart.
+ *
+ * @remarks
+ * 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),

package/src/widgets/echart/options.ts

@@ -1,5 +1,12 @@
 import type { EchartOptionsProps, EchartWidgetOptionProps } from './types'
 
+/**
+ * Returns the shared base ECharts options used across all EChart-based widgets (bar, pie, histogram, etc.).
+ *
+ * @remarks
+ * Configures grid spacing, tooltip styling, legend, axis pointer, and the default color palette
+ * derived from the MUI theme.
+ */
 export function getCommonOptions({
   theme,
 }: EchartWidgetOptionProps<unknown>): EchartOptionsProps {

package/src/widgets/echart/types.ts

@@ -39,4 +39,5 @@ export interface EchartWidgetProps {
   type: string
   option: EchartUIProps['option']
   onEvents?: EchartUIProps['onEvents']
+  formatter?: (value: number) => string
 }

package/src/widgets/echart/utils.ts

@@ -3,6 +3,27 @@ import type { EchartOptionsProps } from './types'
 import type { Theme } from '@mui/material'
 import { DEFAULT_STACK_GROUP } from './const'
 
+/**
+ * Deep-merges two ECharts option objects with smart handling for `color`, `axisLabel`, and `series` keys.
+ *
+ * @param optionA - Base ECharts options.
+ * @param optionB - Override ECharts options to merge on top.
+ * @param customMergeFn - Optional function returning a custom merge strategy per key.
+ * @returns The merged ECharts options object.
+ *
+ * @remarks
+ * - `color` arrays are replaced entirely (not concatenated).
+ * - `axisLabel` formatters are composed so the base formatter can suppress values by returning `''`.
+ * - `series` arrays are merged element-by-element rather than concatenated.
+ *
+ * @example
+ * ```tsx
+ * const option = mergeEchartWidgetConfig(props.option, {
+ *   series: [{ barWidth: '60%', itemStyle: { borderRadius: [4, 4, 0, 0] } }],
+ *   tooltip: { trigger: 'axis' },
+ * })
+ * ```
+ */
 export function mergeEchartWidgetConfig<T extends EchartOptionsProps>(
   optionA: T | undefined,
   optionB: T | undefined,
@@ -53,6 +74,14 @@ export function mergeEchartWidgetConfig<T extends EchartOptionsProps>(
   }) as T
 }
 
+/**
+ * Generates ECharts `dataZoom` configuration for interactive zoom and pan on chart axes.
+ *
+ * @param range - Initial visible range as `{ start, end }` percentages (0-100). Defaults to full range.
+ * @param options - Zoom behavior options including axis sliders, inside zoom, and formatter.
+ * @param theme - Optional MUI theme for styled slider handles and backgrounds.
+ * @returns An object containing the `dataZoom` array configuration.
+ */
 export function getEChartZoomConfig(
   { start, end }: { start: number; end: number } = { start: 0, end: 100 },
   {
@@ -179,6 +208,12 @@ function getEChartZoomSliderStyles(theme: Theme) {
   } as const
 }
 
+/**
+ * Generates ECharts `brush` configuration for interactive data selection on charts.
+ *
+ * @param options - Brush options including type, mode, and target axis index.
+ * @returns An object containing the `brush` configuration.
+ */
 export function getEChartBrushConfig(
   { brushType = 'lineX', brushMode = 'single', xAxisIndex = 0 } = {} as {
     brushType?: string
@@ -198,6 +233,12 @@ export function getEChartBrushConfig(
   }
 }
 
+/**
+ * Returns an ECharts `stack` configuration to group series into a stacked layout.
+ *
+ * @param stackGroup - The stack group identifier. Defaults to the library's default group.
+ * @returns An object with the `stack` property set to the group name.
+ */
 export function getEChartStackConfig(stackGroup: string = DEFAULT_STACK_GROUP) {
   return { stack: stackGroup }
 }

package/src/widgets/error/error.tsx

@@ -3,6 +3,16 @@ import { useWidgetStore } from '../stores/widget-store'
 import { useShallow } from 'zustand/shallow'
 import type { WidgetErrorProps } from './types'
 
+/**
+ * Displays an error alert when a widget encounters an error during data loading. Reads error state from the widget store and hides errors during loading/fetching to prevent flashing.
+ *
+ * @example
+ * ```tsx
+ * <WidgetError id="my-widget">
+ *   <WidgetContent />
+ * </WidgetError>
+ * ```
+ */
 export function WidgetError({
   id,
   children,

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

@@ -2,6 +2,9 @@ import { Typography } from '@mui/material'
 import type { ItemProps } from '../types'
 import { styles } from '../style'
 
+/**
+ * Base typography wrapper used by formula sub-components (Value, Prefix, Suffix) to render styled text.
+ */
 export function Item(props: ItemProps) {
   return (
     <Typography

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

@@ -3,6 +3,9 @@ import { useWidgetStore } from '../../stores/widget-store'
 import { Item } from './item'
 import { useShallow } from 'zustand/shallow'
 
+/**
+ * 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(

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

@@ -4,6 +4,9 @@ import type { FormulaWidgetState, RowProps } from '../types'
 import { useWidgetStore } from '../../stores/widget-store'
 import { useShallow } from 'zustand/shallow'
 
+/**
+ * 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),

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

@@ -3,6 +3,9 @@ import type { FormulaWidgetState, ValueProps } from '../types'
 import { useWidgetStore } from '../../stores/widget-store'
 import { useShallow } from 'zustand/shallow'
 
+/**
+ * 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(

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

@@ -4,6 +4,9 @@ import { Item } from './item'
 import type { Theme } from '@mui/material'
 import { useShallow } from 'zustand/shallow'
 
+/**
+ * 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(

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

@@ -2,9 +2,11 @@ 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'
 
-const defaultFormatter = (value: number) => value.toString()
-
+/**
+ * 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(

package/src/widgets/formula/config.ts

@@ -2,6 +2,12 @@ import { downloadToCSV, downloadToPNG } from '../actions'
 import type { ConfigProps } from '../loader/types'
 import type { FormulaDownloadConfig, FormulaWidgetConfig } from './types'
 
+/**
+ * Creates download configuration for formula widgets, supporting PNG (screenshot) and CSV (data) exports.
+ *
+ * @param props - Configuration with `refUI` reference for PNG export.
+ * @returns Array of download items for use with the Download action.
+ */
 export function formulaDownloadConfig({
   refUI,
 }: ConfigProps): FormulaDownloadConfig {
@@ -20,6 +26,11 @@ export function formulaDownloadConfig({
   ]
 }
 
+/**
+ * Returns the default configuration for formula (single or multiple numeric value) widgets.
+ *
+ * @returns Default formula widget config with empty series.
+ */
 export function formulaConfig(): FormulaWidgetConfig {
   return {
     series: [],

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

@@ -7,6 +7,9 @@ import { Series } from './components/series'
 import { useWidgetRef } from '../../hooks'
 import { Box } from '@mui/material'
 
+/**
+ * Renders a formula widget displaying one or more KPI values with optional prefixes, suffixes, and series indicators.
+ */
 export function FormulaUI(props: FormulaUIProps) {
   const { ref } = useWidgetRef(props.id)
 

package/src/widgets/histogram/config.ts

@@ -14,32 +14,23 @@ import {
   buildGridConfig,
   createTooltipPositioner,
   createTooltipFormatter,
+  createChartDownloadConfig,
   niceNum,
-} from '../_shared/chart-config'
-import { downloadToCSV, downloadToPNG, type DownloadItem } from '../actions'
-import type { ConfigProps } from '../loader/types'
+} from '../utils/chart-config'
 
-export function histogramDownloadConfig({
-  refUI,
-}: ConfigProps): DownloadItem<HistogramWidgetData>[] {
-  return [
-    {
-      ...downloadToPNG,
-      modifier: () => downloadToPNG.modifier(refUI),
-    },
-    {
-      ...downloadToCSV,
-      modifier: async (data) => {
-        const rows = flattenObjectArrayToCSV(data)
-        return downloadToCSV.modifier(rows)
-      },
-    },
-  ]
-}
+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.
+ *
+ * @param props - Histogram configuration including bin data and theme.
+ * @returns Widget config with ECharts option object.
+ */
 export function histogramConfig(props: HistogramConfig): HistogramWidgetConfig {
   return {
     type: 'histogram',
     option: mergeEchartWidgetConfig(getCommonOptions(props), getOption(props)),
+    formatter: props.formatter,
   }
 }
 function getOption({

package/src/widgets/histogram/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/loader/loader.tsx

@@ -3,6 +3,28 @@ import type { WidgetLoaderProps } from './types'
 import { useWidgetStore } from '../stores/widget-store'
 import type { WrapperState } from '../wrapper'
 
+/**
+ * Foundation component for all widgets that manages state initialization, synchronization with the widget store, and data transformation pipeline execution.
+ *
+ * @remarks
+ * The WidgetLoader is stateless -- it manages data flow but does not render any UI. Always wrap it with WidgetWrapper for consistent widget appearance.
+ *
+ * @example
+ * ```tsx
+ * <WidgetLoader
+ *   id="sales-chart"
+ *   type="bar"
+ *   data={data}
+ *   isLoading={false}
+ *   isFetching={false}
+ *   config={barConfig({ data })}
+ * >
+ *   <WidgetWrapper id="sales-chart" title="Sales">
+ *     <Echart id="sales-chart" />
+ *   </WidgetWrapper>
+ * </WidgetLoader>
+ * ```
+ */
 export function WidgetLoader<T extends object = Record<string, unknown>>(
   props: WidgetLoaderProps<T>,
 ) {