@carto/ps-react-ui 4.3.3 → 4.3.5

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

@@ -0,0 +1,133 @@
+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 { 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'
+
+/**
+ * Widget action to toggle between relative (percentage) and absolute data display.
+ *
+ * Registers a transformation tool in the widget pipeline when mounted.
+ * When relative mode is active, transforms data to percentages via the pipeline.
+ *
+ * @example
+ * ```tsx
+ * <RelativeData
+ *   id="my-widget"
+ *   order={20}
+ *   defaultIsRelative={false}
+ * />
+ * ```
+ */
+export function RelativeData({
+  id,
+  order = 10,
+  defaultIsRelative = false,
+  labels,
+  Icon,
+  IconButtonProps,
+}: RelativeDataProps) {
+  const previousMaxValue = useRef<number | undefined>(undefined)
+  const originalFormatter = 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 storeIsRelative = useWidgetStore(
+    (state) => state.getWidget<RelativeDataState>(id)?.isRelative,
+  )
+
+  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,
+      fn: (data) => {
+        const echartData = data as EchartWidgetData
+        const total = calculateTotal(echartData)
+        return toRelativeData(echartData, total)
+      },
+    })
+
+    return () => unregisterTool(id, RELATIVE_DATA_TOOL_ID)
+  }, [id, order, registerTool, unregisterTool, isRelative])
+
+  // Update enabled flag when toggle changes
+  useEffect(() => {
+    setToolEnabled(id, RELATIVE_DATA_TOOL_ID, isRelative)
+  }, [id, isRelative, setToolEnabled])
+
+  const handleToggle = useCallback(() => {
+    const newIsRelative = !isRelative
+    let max = previousMaxValue.current
+
+    if (newIsRelative) {
+      // Backup current formatter to ref
+      const widget = getWidget(id) as {
+        formatter?: (value: number) => string
+        locale?: string
+      }
+      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
+    }
+
+    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])
+
+  const tooltipLabel = isRelative
+    ? (labels?.absolute ?? 'Show absolute values')
+    : (labels?.relative ?? 'Show relative values')
+
+  return (
+    <Tooltip title={tooltipLabel}>
+      <IconButton
+        size='small'
+        aria-label={labels?.ariaLabel ?? tooltipLabel}
+        onClick={handleToggle}
+        sx={actionButtonStyles.trigger}
+        data-active={isRelative}
+        {...IconButtonProps}
+      >
+        {Icon ?? <PercentOutlined />}
+      </IconButton>
+    </Tooltip>
+  )
+}

package/src/widgets/actions/relative-data/style.ts

@@ -0,0 +1,9 @@
+import type { SxProps, Theme } from '@mui/material'
+
+export const styles = {
+  trigger: {
+    '&[data-active="true"]': {
+      background: (theme: Theme) => theme.palette.primary.relatedLight,
+    },
+  },
+} satisfies Record<string, SxProps<Theme>>

package/src/widgets/actions/relative-data/types.ts

@@ -0,0 +1,31 @@
+import type { IconButtonProps } from '@mui/material'
+import type { ReactNode } from 'react'
+import type { BaseWidgetState } from '../../stores/types'
+
+export interface RelativeDataProps {
+  /** Widget ID to update data in the widget store */
+  id: string
+  /** Execution order in the tool pipeline. Lower values execute first. Defaults to 20. */
+  order?: number
+  /** Initial toggle state - when true, shows relative (percentage) values */
+  defaultIsRelative?: boolean
+  /** Custom labels for the action */
+  labels?: {
+    /** Tooltip when showing absolute values (button will switch to relative) */
+    relative?: string
+    /** Tooltip when showing relative values (button will switch to absolute) */
+    absolute?: string
+    /** Accessibility label */
+    ariaLabel?: string
+  }
+  /** Props passed to the IconButton component */
+  IconButtonProps?: IconButtonProps
+  /** Custom icon to display */
+  Icon?: ReactNode
+}
+
+export type RelativeDataState<T = unknown> = BaseWidgetState<
+  T & {
+    isRelative?: boolean
+  }
+>

package/src/widgets/actions/relative-data/utils.test.ts

@@ -0,0 +1,223 @@
+import { describe, test, expect } from 'vitest'
+import { calculateTotal, toRelativeData } from './utils'
+import type { EchartWidgetData } from '../../echart/types'
+
+describe('calculateTotal', () => {
+  test('calculates sum of all numeric values in single series', () => {
+    const data: EchartWidgetData = [
+      [
+        { category: 'A', value: 25 },
+        { category: 'B', value: 75 },
+      ],
+    ]
+
+    expect(calculateTotal(data)).toBe(100)
+  })
+
+  test('calculates sum across multiple series', () => {
+    const data: EchartWidgetData = [
+      [
+        { name: 'X', count: 10 },
+        { name: 'Y', count: 20 },
+      ],
+      [
+        { name: 'X', count: 30 },
+        { name: 'Y', count: 40 },
+      ],
+    ]
+
+    expect(calculateTotal(data)).toBe(100)
+  })
+
+  test('returns zero for empty data', () => {
+    const data: EchartWidgetData = []
+
+    expect(calculateTotal(data)).toBe(0)
+  })
+
+  test('returns zero for empty series', () => {
+    const data: EchartWidgetData = [[]]
+
+    expect(calculateTotal(data)).toBe(0)
+  })
+
+  test('handles data with only zero values', () => {
+    const data: EchartWidgetData = [
+      [
+        { category: 'A', value: 0 },
+        { category: 'B', value: 0 },
+      ],
+    ]
+
+    expect(calculateTotal(data)).toBe(0)
+  })
+
+  test('handles negative values', () => {
+    const data: EchartWidgetData = [
+      [
+        { category: 'A', value: -25 },
+        { category: 'B', value: 75 },
+      ],
+    ]
+
+    expect(calculateTotal(data)).toBe(50)
+  })
+
+  test('ignores string values in calculation', () => {
+    const data: EchartWidgetData = [
+      [
+        { label: 'First', value: 50, extra: 'text' },
+        { label: 'Second', value: 50, extra: 'more' },
+      ],
+    ]
+
+    expect(calculateTotal(data)).toBe(100)
+  })
+
+  test('handles multiple numeric fields per item', () => {
+    const data: EchartWidgetData = [
+      [
+        { category: 'A', value1: 10, value2: 20 },
+        { category: 'B', value1: 30, value2: 40 },
+      ],
+    ]
+
+    expect(calculateTotal(data)).toBe(100)
+  })
+})
+
+describe('toRelativeData', () => {
+  test('transforms values to percentages (25/100 = 25%, 75/100 = 75%)', () => {
+    const data: EchartWidgetData = [
+      [
+        { category: 'A', value: 25 },
+        { category: 'B', value: 75 },
+      ],
+    ]
+    const total = 100
+
+    const result = toRelativeData(data, total)
+
+    // With total 100, 25 becomes 25% and 75 becomes 75%
+    expect(result[0]?.[0]?.value).toBe(25)
+    expect(result[0]?.[1]?.value).toBe(75)
+  })
+
+  test('transforms values to percentages with non-100 total (50/200 = 25%)', () => {
+    const data: EchartWidgetData = [
+      [
+        { category: 'A', value: 50 },
+        { category: 'B', value: 150 },
+      ],
+    ]
+    const total = 200
+
+    const result = toRelativeData(data, total)
+
+    // 50/200 = 25%, 150/200 = 75%
+    expect(result[0]?.[0]?.value).toBe(25)
+    expect(result[0]?.[1]?.value).toBe(75)
+  })
+
+  test('returns original data when total is zero', () => {
+    const data: EchartWidgetData = [
+      [
+        { category: 'A', value: 0 },
+        { category: 'B', value: 0 },
+      ],
+    ]
+    const total = 0
+
+    const result = toRelativeData(data, total)
+
+    expect(result).toEqual(data)
+  })
+
+  test('preserves string values during transformation', () => {
+    const data: EchartWidgetData = [
+      [
+        { label: 'First', value: 50, extra: 'text' },
+        { label: 'Second', value: 50, extra: 'more' },
+      ],
+    ]
+    const total = 100
+
+    const result = toRelativeData(data, total)
+
+    expect(result[0]?.[0]?.label).toBe('First')
+    expect(result[0]?.[0]?.extra).toBe('text')
+    expect(result[0]?.[1]?.label).toBe('Second')
+    expect(result[0]?.[1]?.extra).toBe('more')
+  })
+
+  test('transforms data with multiple series', () => {
+    const data: EchartWidgetData = [
+      [
+        { name: 'X', count: 10 },
+        { name: 'Y', count: 20 },
+      ],
+      [
+        { name: 'X', count: 30 },
+        { name: 'Y', count: 40 },
+      ],
+    ]
+    const total = 100
+
+    const result = toRelativeData(data, total)
+
+    expect(result[0]?.[0]?.count).toBe(10)
+    expect(result[0]?.[1]?.count).toBe(20)
+    expect(result[1]?.[0]?.count).toBe(30)
+    expect(result[1]?.[1]?.count).toBe(40)
+  })
+
+  test('handles fractional percentages correctly', () => {
+    const data: EchartWidgetData = [
+      [
+        { category: 'A', value: 1 },
+        { category: 'B', value: 2 },
+        { category: 'C', value: 3 },
+      ],
+    ]
+    const total = 6
+
+    const result = toRelativeData(data, total)
+
+    expect(result[0]?.[0]?.value).toBeCloseTo(16.6667, 4)
+    expect(result[0]?.[1]?.value).toBeCloseTo(33.3333, 4)
+    expect(result[0]?.[2]?.value).toBeCloseTo(50, 4)
+  })
+
+  test('handles negative values', () => {
+    const data: EchartWidgetData = [
+      [
+        { category: 'A', value: -25 },
+        { category: 'B', value: 75 },
+      ],
+    ]
+    const total = 50
+
+    const result = toRelativeData(data, total)
+
+    expect(result[0]?.[0]?.value).toBe(-50)
+    expect(result[0]?.[1]?.value).toBe(150)
+  })
+
+  test('handles empty data', () => {
+    const data: EchartWidgetData = []
+    const total = 100
+
+    const result = toRelativeData(data, total)
+
+    expect(result).toEqual([])
+  })
+
+  test('handles empty series', () => {
+    const data: EchartWidgetData = [[]]
+    const total = 100
+
+    const result = toRelativeData(data, total)
+
+    expect(result).toEqual([[]])
+  })
+})

package/src/widgets/actions/relative-data/utils.ts

@@ -0,0 +1,58 @@
+import type { EchartWidgetData } from '../../echart/types'
+
+/**
+ * Calculates the sum of all numeric values in the data
+ */
+export function calculateTotal(data: EchartWidgetData): number {
+  return data.reduce((total, series) => {
+    return series.reduce((seriesTotal, item) => {
+      if (Array.isArray(item)) {
+        const value = item.at(-1) as number
+        return typeof value === 'number' ? seriesTotal + value : seriesTotal
+      }
+
+      return Object.entries(item).reduce((itemTotal: number, [key, value]) => {
+        if (key === 'name') {
+          return itemTotal
+        }
+        return typeof value === 'number' ? itemTotal + value : itemTotal
+      }, seriesTotal)
+    }, total)
+  }, 0)
+}
+
+/**
+ * Transforms data to relative (percentage) values
+ */
+export function toRelativeData(
+  data: EchartWidgetData,
+  total: number,
+): EchartWidgetData {
+  if (total === 0) return data
+
+  return data.map((series) =>
+    series.map((item) => {
+      if (Array.isArray(item)) {
+        return item.map((value: number, index) => {
+          if (index === item.length - 1 && typeof value === 'number') {
+            return (value / total) * 100
+          }
+          return value
+        }) as typeof item
+      }
+
+      const transformed: Record<string, string | number> = {}
+
+      for (const [key, value] of Object.entries(item)) {
+        if (key === 'name') {
+          transformed[key] = value
+          continue
+        }
+        transformed[key] =
+          typeof value === 'number' ? (value / total) * 100 : value
+      }
+
+      return transformed
+    }),
+  )
+}