@carto/ps-react-ui 4.3.3 → 4.3.5

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

@@ -0,0 +1,399 @@
+import { describe, test, expect, beforeEach } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import { ThemeProvider, createTheme } from '@mui/material/styles'
+import { CategoryUI } from './category-ui'
+import { useWidgetStore } from '../stores/widget-store'
+import type { CategoryWidgetState } from './types'
+
+// Create a test theme with qualitative colors
+const testTheme = createTheme({
+  palette: {
+    primary: {
+      main: '#1976d2',
+    },
+    qualitative: {
+      bold: {
+        0: '#1f77b4',
+        1: '#ff7f0e',
+        2: '#2ca02c',
+        3: '#d62728',
+        4: '#9467bd',
+        5: '#8c564b',
+        6: '#e377c2',
+        7: '#7f7f7f',
+      },
+    },
+  },
+})
+
+// Helper function to render with theme
+function renderWithTheme(ui: React.ReactElement) {
+  return render(<ThemeProvider theme={testTheme}>{ui}</ThemeProvider>)
+}
+
+describe('CategoryUI', () => {
+  beforeEach(() => {
+    useWidgetStore.getState().clearWidgets()
+  })
+
+  test('returns null when widget does not exist', () => {
+    const { container } = renderWithTheme(<CategoryUI id='non-existent' />)
+    expect(container.firstChild).toBeNull()
+  })
+
+  test('returns null when data is empty', () => {
+    useWidgetStore.getState().setWidget<CategoryWidgetState>('test-category', {
+      type: 'category',
+      data: [[]],
+    })
+
+    const { container } = renderWithTheme(<CategoryUI id='test-category' />)
+    expect(container.firstChild).toBeNull()
+  })
+
+  test('renders basic category data', () => {
+    useWidgetStore.getState().setWidget<CategoryWidgetState>('test-category', {
+      type: 'category',
+      data: [
+        [
+          { name: 'Category A', value: 100 },
+          { name: 'Category B', value: 50 },
+        ],
+      ],
+    })
+
+    renderWithTheme(<CategoryUI id='test-category' />)
+
+    expect(screen.getByText('Category A')).toBeTruthy()
+    expect(screen.getByText('Category B')).toBeTruthy()
+    expect(screen.getByText('100')).toBeTruthy()
+    expect(screen.getByText('50')).toBeTruthy()
+  })
+
+  test('auto-calculates max value from data when max prop not provided', () => {
+    useWidgetStore.getState().setWidget<CategoryWidgetState>('test-category', {
+      type: 'category',
+      data: [
+        [
+          { name: 'Category A', value: 100 },
+          { name: 'Category B', value: 150 },
+          { name: 'Category C', value: 75 },
+        ],
+      ],
+    })
+
+    renderWithTheme(<CategoryUI id='test-category' />)
+
+    // Verify all categories are rendered
+    expect(screen.getByText('Category A')).toBeTruthy()
+    expect(screen.getByText('Category B')).toBeTruthy()
+    expect(screen.getByText('Category C')).toBeTruthy()
+    expect(screen.getByText('100')).toBeTruthy()
+    expect(screen.getByText('150')).toBeTruthy()
+    expect(screen.getByText('75')).toBeTruthy()
+  })
+
+  test('uses custom max value when provided', () => {
+    useWidgetStore.getState().setWidget<CategoryWidgetState>('test-category', {
+      type: 'category',
+      data: [
+        [
+          { name: 'Category A', value: 100 },
+          { name: 'Category B', value: 150 },
+        ],
+      ],
+      max: 200,
+    })
+
+    renderWithTheme(<CategoryUI id='test-category' />)
+
+    // Verify categories are rendered with custom max
+    expect(screen.getByText('Category A')).toBeTruthy()
+    expect(screen.getByText('Category B')).toBeTruthy()
+    expect(screen.getByText('100')).toBeTruthy()
+    expect(screen.getByText('150')).toBeTruthy()
+  })
+
+  test('handles max value of 0', () => {
+    useWidgetStore.getState().setWidget<CategoryWidgetState>('test-category', {
+      type: 'category',
+      data: [
+        [
+          { name: 'Category A', value: 100 },
+          { name: 'Category B', value: 50 },
+        ],
+      ],
+      max: 0,
+    })
+
+    renderWithTheme(<CategoryUI id='test-category' />)
+
+    // Verify categories are rendered even with max=0
+    expect(screen.getByText('Category A')).toBeTruthy()
+    expect(screen.getByText('Category B')).toBeTruthy()
+    expect(screen.getByText('100')).toBeTruthy()
+    expect(screen.getByText('50')).toBeTruthy()
+  })
+
+  test('handles max value less than actual data values', () => {
+    useWidgetStore.getState().setWidget<CategoryWidgetState>('test-category', {
+      type: 'category',
+      data: [
+        [
+          { name: 'Category A', value: 150 },
+          { name: 'Category B', value: 75 },
+        ],
+      ],
+      max: 100,
+    })
+
+    renderWithTheme(<CategoryUI id='test-category' />)
+
+    // Verify categories are rendered when values exceed max
+    expect(screen.getByText('Category A')).toBeTruthy()
+    expect(screen.getByText('Category B')).toBeTruthy()
+    expect(screen.getByText('150')).toBeTruthy()
+    expect(screen.getByText('75')).toBeTruthy()
+  })
+
+  test('uses custom max with multi-series data', () => {
+    useWidgetStore.getState().setWidget<CategoryWidgetState>('test-category', {
+      type: 'category',
+      data: [
+        [
+          { name: 'Product A', value: 80 },
+          { name: 'Product B', value: 60 },
+        ],
+        [
+          { name: 'Product A', value: 90 },
+          { name: 'Product B', value: 70 },
+        ],
+      ],
+      max: 100,
+      series: [{ name: 'Q1' }, { name: 'Q2' }],
+    })
+
+    renderWithTheme(<CategoryUI id='test-category' />)
+
+    // Multi-series should show legend
+    expect(screen.getByText('Q1')).toBeTruthy()
+    expect(screen.getByText('Q2')).toBeTruthy()
+
+    // Verify product names are displayed
+    expect(screen.getByText('Product A')).toBeTruthy()
+    expect(screen.getByText('Product B')).toBeTruthy()
+  })
+
+  test('updates when max value changes', () => {
+    useWidgetStore.getState().setWidget<CategoryWidgetState>('test-category', {
+      type: 'category',
+      data: [[{ name: 'Category A', value: 100 }]],
+      max: 200,
+    })
+
+    renderWithTheme(<CategoryUI id='test-category' />)
+
+    expect(screen.getByText('Category A')).toBeTruthy()
+    expect(screen.getByText('100')).toBeTruthy()
+
+    // Update max value
+    useWidgetStore.getState().setWidget<CategoryWidgetState>('test-category', {
+      type: 'category',
+      data: [[{ name: 'Category A', value: 100 }]],
+      max: 100,
+    })
+
+    // Widget should still render after update
+    expect(screen.getByText('Category A')).toBeTruthy()
+    expect(screen.getByText('100')).toBeTruthy()
+  })
+
+  test('uses formatter when provided', () => {
+    useWidgetStore.getState().setWidget<CategoryWidgetState>('test-category', {
+      type: 'category',
+      data: [[{ name: 'Category A', value: 1234 }]],
+      formatter: (value: number) => `$${value}`,
+    })
+
+    renderWithTheme(<CategoryUI id='test-category' />)
+
+    expect(screen.getByText('$1234')).toBeTruthy()
+  })
+
+  test('uses formatter with custom max', () => {
+    useWidgetStore.getState().setWidget<CategoryWidgetState>('test-category', {
+      type: 'category',
+      data: [[{ name: 'Sales', value: 125000 }]],
+      max: 200000,
+      formatter: (value: number) =>
+        new Intl.NumberFormat('en-US', {
+          style: 'currency',
+          currency: 'USD',
+          maximumFractionDigits: 0,
+        }).format(value),
+    })
+
+    renderWithTheme(<CategoryUI id='test-category' />)
+
+    // Should show formatted value
+    expect(screen.getByText('$125,000')).toBeTruthy()
+    expect(screen.getByText('Sales')).toBeTruthy()
+  })
+
+  test('max prop works with maxItems configuration', () => {
+    useWidgetStore.getState().setWidget<CategoryWidgetState>('test-category', {
+      type: 'category',
+      data: [
+        [
+          { name: 'Item 1', value: 80 },
+          { name: 'Item 2', value: 60 },
+          { name: 'Item 3', value: 40 },
+          { name: 'Item 4', value: 20 },
+        ],
+      ],
+      max: 100,
+      maxItems: 2,
+    })
+
+    renderWithTheme(<CategoryUI id='test-category' />)
+
+    // Should show only first 2 items
+    expect(screen.getByText('Item 1')).toBeTruthy()
+    expect(screen.getByText('Item 2')).toBeTruthy()
+
+    // Should show values
+    expect(screen.getByText('80')).toBeTruthy()
+    expect(screen.getByText('60')).toBeTruthy()
+  })
+
+  describe('Overflow behavior', () => {
+    test('applies overflow auto when hiddenCount is 0 (no maxItems)', () => {
+      useWidgetStore
+        .getState()
+        .setWidget<CategoryWidgetState>('test-category', {
+          type: 'category',
+          data: [
+            [
+              { name: 'Item 1', value: 100 },
+              { name: 'Item 2', value: 50 },
+            ],
+          ],
+          // No maxItems set, so hiddenCount will be 0
+        })
+
+      const { container } = renderWithTheme(<CategoryUI id='test-category' />)
+      // The list Box has inline style for overflow
+      const listBox = container.querySelector<HTMLElement>(
+        '[style*="overflow"]',
+      )!
+
+      expect(listBox).toBeTruthy()
+      expect(listBox.style.overflow).toBe('auto')
+    })
+
+    test('applies overflow hidden when hiddenCount is greater than 0', () => {
+      useWidgetStore
+        .getState()
+        .setWidget<CategoryWidgetState>('test-category', {
+          type: 'category',
+          data: [
+            [
+              { name: 'Item 1', value: 100 },
+              { name: 'Item 2', value: 80 },
+              { name: 'Item 3', value: 60 },
+              { name: 'Item 4', value: 40 },
+            ],
+          ],
+          maxItems: 2, // This creates hiddenCount = 2
+        })
+
+      const { container } = renderWithTheme(<CategoryUI id='test-category' />)
+      // The list Box has inline style for overflow
+      const listBox = container.querySelector<HTMLElement>(
+        '[style*="overflow"]',
+      )!
+
+      expect(listBox).toBeTruthy()
+      expect(listBox.style.overflow).toBe('hidden')
+    })
+
+    test('maintains overflow auto when maxItems equals data length', () => {
+      useWidgetStore
+        .getState()
+        .setWidget<CategoryWidgetState>('test-category', {
+          type: 'category',
+          data: [
+            [
+              { name: 'Item 1', value: 100 },
+              { name: 'Item 2', value: 50 },
+            ],
+          ],
+          maxItems: 2, // Same as data length, hiddenCount = 0
+        })
+
+      const { container } = renderWithTheme(<CategoryUI id='test-category' />)
+      // The list Box has inline style for overflow
+      const listBox = container.querySelector<HTMLElement>(
+        '[style*="overflow"]',
+      )!
+
+      expect(listBox).toBeTruthy()
+      expect(listBox.style.overflow).toBe('auto')
+    })
+
+    test('applies overflow auto when maxItems exceeds data length', () => {
+      useWidgetStore
+        .getState()
+        .setWidget<CategoryWidgetState>('test-category', {
+          type: 'category',
+          data: [
+            [
+              { name: 'Item 1', value: 100 },
+              { name: 'Item 2', value: 50 },
+            ],
+          ],
+          maxItems: 5, // More than data length, hiddenCount = 0
+        })
+
+      const { container } = renderWithTheme(<CategoryUI id='test-category' />)
+      // The list Box has inline style for overflow
+      const listBox = container.querySelector<HTMLElement>(
+        '[style*="overflow"]',
+      )!
+
+      expect(listBox).toBeTruthy()
+      expect(listBox.style.overflow).toBe('auto')
+    })
+
+    test('works correctly with multi-series data', () => {
+      useWidgetStore
+        .getState()
+        .setWidget<CategoryWidgetState>('test-category', {
+          type: 'category',
+          data: [
+            [
+              { name: 'Product A', value: 100 },
+              { name: 'Product B', value: 80 },
+              { name: 'Product C', value: 60 },
+            ],
+            [
+              { name: 'Product A', value: 90 },
+              { name: 'Product B', value: 70 },
+              { name: 'Product C', value: 50 },
+            ],
+          ],
+          series: [{ name: 'Q1' }, { name: 'Q2' }],
+          maxItems: 2, // hiddenCount = 1
+        })
+
+      const { container } = renderWithTheme(<CategoryUI id='test-category' />)
+      // The list Box has inline style for overflow
+      const listBox = container.querySelector<HTMLElement>(
+        '[style*="overflow"]',
+      )!
+
+      expect(listBox).toBeTruthy()
+      expect(listBox.style.overflow).toBe('hidden')
+    })
+  })
+})

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

@@ -0,0 +1,156 @@
+import { Box, useTheme } from '@mui/material'
+import { useWidgetStore } from '../stores/widget-store'
+import { styles } from './style'
+import type { CategoryUIProps, CategoryWidgetState } from './types'
+import {
+  CategoryRowSingle,
+  CategoryRowMulti,
+  CategoryRowOther,
+  CategoryLegend,
+} from './components'
+import { useShallow } from 'zustand/shallow'
+import { useState } from 'react'
+
+const defaultFormatter = (value: number) => value.toString()
+
+export function CategoryUI({ id }: CategoryUIProps) {
+  const theme = useTheme()
+  const widget = useWidgetStore(
+    useShallow((state) => {
+      const widget = state.getWidget<CategoryWidgetState>(id)
+      return {
+        formatter: widget?.formatter,
+        series: widget?.series,
+        data: widget?.data,
+        maxItems: widget?.maxItems,
+        labels: widget?.labels,
+        onRowClick: widget?.onRowClick,
+        selected: widget?.selected,
+        max: widget?.max,
+      }
+    }),
+  )
+
+  const formatter = widget?.formatter ?? defaultFormatter
+  const series = widget?.series ?? []
+  const data = widget?.data
+  const maxItems = widget?.maxItems
+  const labels = widget?.labels
+  const onRowClick = widget?.onRowClick
+  const selected = widget?.selected
+  const max = widget?.max
+
+  const [maxHeight] = useState<string | number | undefined>(
+    maxItems ? 40 * (series.length || 1) * maxItems : undefined,
+  )
+
+  const qualitativeColors = Object.values(theme.palette.qualitative.bold)
+
+  const colors =
+    series.length > 0
+      ? series.map(
+          (s, index: number) =>
+            s.color ??
+            qualitativeColors[index % qualitativeColors.length] ??
+            theme.palette.secondary.main,
+        )
+      : [theme.palette.secondary.main]
+
+  // Group data items by name to support multi-series display
+  // data is CategoryDataItem[][] where data[seriesIndex] contains items for that series
+  const groupedData = generateGroupedData({ data })
+
+  if (groupedData.length === 0) {
+    return null
+  }
+
+  const maxValue =
+    max ?? Math.max(...groupedData.flatMap((item) => item.values))
+
+  // Slice data to maxItems and compute hidden count
+  const visibleData =
+    maxItems !== undefined && maxItems >= 0
+      ? groupedData.slice(0, maxItems)
+      : groupedData
+
+  const hiddenCount = groupedData.length - visibleData.length
+  const isMulti = series.length > 1
+
+  return (
+    <Box
+      sx={{
+        ...styles.root,
+      }}
+    >
+      <Box
+        sx={styles.list}
+        style={{ maxHeight, overflow: hiddenCount === 0 ? 'auto' : 'hidden' }}
+      >
+        {isMulti
+          ? visibleData.map((item) => (
+              <CategoryRowMulti
+                key={item.name}
+                name={item.name}
+                values={item.values}
+                maxValue={maxValue}
+                colors={colors}
+                formatter={formatter}
+                onClick={onRowClick}
+                selected={selected?.(item.name) ?? true}
+              />
+            ))
+          : visibleData.map((item) => (
+              <CategoryRowSingle
+                key={item.name}
+                name={item.name}
+                value={item.values[0] ?? 0}
+                selected={selected?.(item.name) ?? true}
+                maxValue={maxValue}
+                color={colors[0]!}
+                formatter={formatter}
+                onClick={onRowClick}
+              />
+            ))}
+        {hiddenCount > 0 && (
+          <CategoryRowOther
+            hiddenCount={hiddenCount}
+            otherLabel={labels?.other}
+            otherCountLabel={labels?.otherCount}
+          />
+        )}
+      </Box>
+      {series.length > 0 && <CategoryLegend series={series} colors={colors} />}
+    </Box>
+  )
+}
+
+function generateGroupedData({
+  data,
+}: {
+  data: { name: string; value: number }[][] | undefined
+}) {
+  if (!data || data.length === 0) return []
+
+  const seriesCount = Math.max(data.length, 1)
+  const grouped = new Map<string, number[]>()
+  const nameOrder: string[] = []
+
+  // Iterate over each series (outer array)
+  for (let seriesIndex = 0; seriesIndex < data.length; seriesIndex++) {
+    const seriesData = data[seriesIndex]!
+    for (const item of seriesData) {
+      let values = grouped.get(item.name)
+      if (!values) {
+        values = new Array<number>(seriesCount).fill(0)
+        grouped.set(item.name, values)
+        nameOrder.push(item.name)
+      }
+      values[seriesIndex] = item.value
+    }
+  }
+
+  return nameOrder.map((name) => ({
+    name,
+    values: grouped.get(name)!,
+  }))
+}

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

@@ -0,0 +1,28 @@
+import { Box } from '@mui/material'
+import { styles } from '../style'
+
+export interface CategoryBarProps {
+  value: number
+  maxValue: number
+  color: string
+  selected?: boolean
+}
+
+export function CategoryBar({
+  value,
+  maxValue,
+  color,
+  selected = true,
+}: CategoryBarProps) {
+  const percentage = maxValue > 0 ? (value / maxValue) * 100 : 0
+
+  const barFillSx = selected
+    ? { ...styles.barFill, width: `${percentage}%`, backgroundColor: color }
+    : { ...styles.barFill, ...styles.barFillMuted, width: `${percentage}%` }
+
+  return (
+    <Box sx={styles.bar}>
+      <Box sx={barFillSx} />
+    </Box>
+  )
+}

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

@@ -0,0 +1,30 @@
+import { Box, Typography } from '@mui/material'
+import { styles } from '../style'
+import type { CategorySeriesConfig } from '../types'
+
+export interface CategoryLegendProps {
+  series: CategorySeriesConfig[]
+  colors: string[]
+}
+
+export function CategoryLegend({ series, colors }: CategoryLegendProps) {
+  if (series.length === 0) {
+    return null
+  }
+
+  return (
+    <Box sx={styles.legend}>
+      {series.map((item, index) => (
+        <Box key={item.name} sx={styles.legendItem}>
+          <Box
+            sx={{
+              ...styles.legendDot,
+              backgroundColor: item.color ?? colors[index % colors.length],
+            }}
+          />
+          <Typography sx={styles.legendLabel}>{item.name}</Typography>
+        </Box>
+      ))}
+    </Box>
+  )
+}

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

@@ -0,0 +1,50 @@
+import { Box, Typography } from '@mui/material'
+import { styles } from '../style'
+import { CategoryBar } from './category-bar'
+import type { CategoryWidgetConfig } from '../types'
+
+export interface CategoryRowMultiProps {
+  name: string
+  values: number[]
+  maxValue: number
+  colors: string[]
+  formatter: NonNullable<CategoryWidgetConfig['formatter']>
+  onClick?: CategoryWidgetConfig['onRowClick']
+  selected?: boolean
+}
+
+export function CategoryRowMulti({
+  name,
+  values,
+  maxValue,
+  colors,
+  formatter,
+  onClick,
+  selected = true,
+}: CategoryRowMultiProps) {
+  const handleClick = onClick ? () => onClick({ name }) : undefined
+  const rowStyle = onClick ? styles.rowClickable : styles.row
+
+  return (
+    <Box sx={rowStyle} onClick={handleClick}>
+      <Typography sx={styles.rowLabel}>{name}</Typography>
+      <Box sx={styles.barContainer}>
+        {values.map((value, index) => (
+          <Box key={`${name}-${value}-${index}`} sx={styles.multiBarRow}>
+            <Box sx={styles.multiBarContainer}>
+              <CategoryBar
+                value={value}
+                maxValue={maxValue}
+                color={colors[index % colors.length] ?? ''}
+                selected={selected}
+              />
+            </Box>
+            <Typography sx={styles.multiBarValue}>
+              {formatter(value)}
+            </Typography>
+          </Box>
+        ))}
+      </Box>
+    </Box>
+  )
+}

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

@@ -0,0 +1,23 @@
+import { Box, Typography } from '@mui/material'
+import { styles } from '../style'
+
+export interface CategoryRowOtherProps {
+  hiddenCount: number
+  otherLabel?: string
+  otherCountLabel?: string
+}
+
+export function CategoryRowOther({
+  hiddenCount,
+  otherLabel = 'Other',
+  otherCountLabel = '{count} more',
+}: CategoryRowOtherProps) {
+  const countText = otherCountLabel.replace('{count}', String(hiddenCount))
+
+  return (
+    <Box sx={styles.otherRow}>
+      <Typography sx={styles.otherLabel}>{otherLabel}</Typography>
+      <Typography sx={styles.otherCount}>({countText})</Typography>
+    </Box>
+  )
+}