@carto/ps-react-ui 4.7.1 → 4.8.0

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

@@ -0,0 +1,49 @@
+import { Box } from '@mui/material'
+import type { CategorySize } from '../types'
+import { styles } from '../style'
+
+export interface CategoryBarProps {
+  /** Numeric value driving the fill width. */
+  value: number
+  /** Denominator for the percentage fill. `0` → empty bar (no division by zero). */
+  maxValue: number
+  /** Fill color. Honors any CSS color or MUI theme token. */
+  color: string
+  /**
+   * Visual density. `'small'` (default) keeps the historical 4px pill;
+   * `'medium'` renders a 12px-tall track with a 2px corner radius. Only
+   * the bar track + fill change — every other token in the parent row is
+   * size-invariant.
+   */
+  size?: CategorySize
+}
+
+/**
+ * Single horizontal bar (track + proportional fill). Pure presentation.
+ * Selection / dimming live at the row level; this component is unaware of
+ * both — bars stay vivid regardless of selection state (per the v2
+ * "row-bg + row-dim, never muted bar" rule).
+ */
+export function CategoryBar({
+  value,
+  maxValue,
+  color,
+  size = 'small',
+}: CategoryBarProps) {
+  const pct = maxValue > 0 ? (value / maxValue) * 100 : 0
+  // Width + color rendered as inline `style` (not `sx`) to avoid
+  // generating a new emotion class for every distinct value/color pair
+  // — also makes the rendered DOM testable without computed-style math.
+  return (
+    <Box sx={styles.bar[size]} data-size={size}>
+      <Box
+        sx={styles.barFill[size]}
+        style={{ width: `${pct}%`, backgroundColor: color }}
+        // Tag the fill so an ancestor row's `:hover` selector can target
+        // it (`&:hover [data-bar-fill]`) — the brightening affordance now
+        // fires from anywhere in the row, not only the bar track.
+        data-bar-fill='true'
+      />
+    </Box>
+  )
+}

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

@@ -0,0 +1,51 @@
+import { describe, it, expect } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import { CategoryLegend } from './category-legend'
+
+const noColors = () => undefined
+
+describe('<CategoryLegend>', () => {
+  it('renders nothing when series is empty', () => {
+    const { container } = render(
+      <CategoryLegend series={[]} colorAt={noColors} />,
+    )
+    expect(container.firstChild).toBeNull()
+  })
+
+  it('renders one item per series with its name', () => {
+    render(
+      <CategoryLegend
+        series={[{ name: '2024' }, { name: '2025' }]}
+        colorAt={(i) => (i === 0 ? 'rgb(1, 1, 1)' : 'rgb(2, 2, 2)')}
+      />,
+    )
+    expect(screen.getByText('2024')).toBeTruthy()
+    expect(screen.getByText('2025')).toBeTruthy()
+  })
+
+  it('per-series color override (series[i].color) wins over colorAt(i)', () => {
+    const { container } = render(
+      <CategoryLegend
+        series={[{ name: 'S1', color: 'rgb(99, 0, 0)' }]}
+        colorAt={() => 'rgb(0, 0, 0)'}
+      />,
+    )
+    const dot = Array.from(container.querySelectorAll('div')).find(
+      (d) => (d as HTMLElement).style.backgroundColor === 'rgb(99, 0, 0)',
+    )
+    expect(dot).toBeTruthy()
+  })
+
+  it('falls back to colorAt(i) when series[i].color is absent', () => {
+    const { container } = render(
+      <CategoryLegend
+        series={[{ name: 'S1' }]}
+        colorAt={() => 'rgb(7, 7, 7)'}
+      />,
+    )
+    const dot = Array.from(container.querySelectorAll('div')).find(
+      (d) => (d as HTMLElement).style.backgroundColor === 'rgb(7, 7, 7)',
+    )
+    expect(dot).toBeTruthy()
+  })
+})

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

@@ -0,0 +1,39 @@
+import { Box, Typography } from '@mui/material'
+import type { CategorySeriesConfig } from '../types'
+import { styles } from '../style'
+
+export interface CategoryLegendProps {
+  /** Series metadata. Empty array → renders nothing. */
+  series: readonly CategorySeriesConfig[]
+  /**
+   * Per-series colour resolver. Receives the series index and returns the
+   * palette colour (or `undefined` to fall back to the MUI default). The
+   * legend derives its dot colour from this on the fly — the caller does
+   * NOT pre-compute a `colors` array (avoids passing two views of the
+   * same source).
+   */
+  colorAt: (index: number) => string | undefined
+}
+
+/**
+ * Sticky color legend rendered below a multi-series Category list.
+ * Per-series `color` overrides the matching `colorAt(i)` result.
+ */
+export function CategoryLegend({ series, colorAt }: CategoryLegendProps) {
+  if (series.length === 0) return null
+  return (
+    <Box sx={styles.legend}>
+      {series.map((s, i) => (
+        <Box key={s.name} sx={styles.legendItem}>
+          <Box
+            sx={styles.legendDot}
+            style={{ backgroundColor: s.color ?? colorAt(i) }}
+          />
+          <Typography variant='caption' sx={styles.legendLabel}>
+            {s.name}
+          </Typography>
+        </Box>
+      ))}
+    </Box>
+  )
+}

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

@@ -0,0 +1,86 @@
+import type { KeyboardEvent } from 'react'
+import { Box, Typography } from '@mui/material'
+import { CategoryBar } from './category-bar'
+import type { CategoryKey, CategorySize } from '../types'
+import { styles } from '../style'
+
+export interface CategoryRowMultiProps {
+  /** Raw category key — what gets emitted to `onToggle`. */
+  name: CategoryKey
+  /** Display label (post-`labelFormatter`). Falls back to `name`. */
+  displayName?: string | number
+  /** One value per series. `0` is rendered as an empty bar (track only). */
+  values: readonly number[]
+  /** One color per series (palette + per-series overrides resolved upstream). */
+  colors: readonly string[]
+  /** Shared max across all series + rows (or `maxOverride`). */
+  maxValue: number
+  formatter: (n: number) => string
+  selected: boolean
+  onToggle: (name: CategoryKey) => void
+  /** Bar visual density. Forwarded to every {@link CategoryBar} in the row. */
+  size?: CategorySize
+}
+
+/**
+ * Multi-series category row: label spans the top; bar+value pairs stack
+ * vertically below, one per series. Each bar uses the full row width
+ * track (no shared grid) for legibility at N>=2 series. Click anywhere
+ * in the row (label OR any bar/value) toggles selection by `name`.
+ *
+ * Visual selection / dim signal lives ENTIRELY in the bar colors
+ * (`colors` prop) — every series in a dimmed row receives
+ * `theme.palette.action.disabled`; selected / unselected-no-selection
+ * rows receive their real palette colors. Computed upstream by
+ * `CategoryUI`. The row itself has no bg tint, no opacity rule.
+ */
+export function CategoryRowMulti({
+  name,
+  displayName,
+  values,
+  colors,
+  maxValue,
+  formatter,
+  selected,
+  onToggle,
+  size,
+}: CategoryRowMultiProps) {
+  const handleKey = (e: KeyboardEvent<HTMLDivElement>): void => {
+    if (e.key === 'Enter' || e.key === ' ') {
+      e.preventDefault()
+      onToggle(name)
+    }
+  }
+  return (
+    <Box
+      role='button'
+      aria-pressed={selected}
+      tabIndex={0}
+      onClick={() => onToggle(name)}
+      onKeyDown={handleKey}
+      sx={styles.rowMulti}
+    >
+      <Typography variant='body2' sx={styles.multiName}>
+        {displayName ?? name}
+      </Typography>
+      {values.map((v, i) => (
+        // Multi-bar rows iterate per series — the bar belongs to series `i`,
+        // and the row is keyed on the parent's `name`, so a composite of
+        // `name` + the series index is stable across reorders.
+        <Box key={`${name}-series-${i}`} sx={styles.multiBarRow}>
+          <Box sx={styles.multiBarContainer}>
+            <CategoryBar
+              value={v}
+              maxValue={maxValue}
+              color={colors[i] ?? ''}
+              size={size}
+            />
+          </Box>
+          <Typography variant='body2' sx={styles.value}>
+            {formatter(v)}
+          </Typography>
+        </Box>
+      ))}
+    </Box>
+  )
+}

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

@@ -0,0 +1,28 @@
+import { describe, it, expect } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import { CategoryRowOther } from './category-row-other'
+
+describe('<CategoryRowOther>', () => {
+  it('renders the default labels with substituted count', () => {
+    render(<CategoryRowOther hiddenCount={7} />)
+    expect(screen.getByText('Other')).toBeTruthy()
+    expect(screen.getByText('(7 more)')).toBeTruthy()
+  })
+
+  it('honors custom labels with {count} placeholder', () => {
+    render(
+      <CategoryRowOther
+        hiddenCount={3}
+        otherLabel='Hidden'
+        otherCountLabel='+{count} not shown'
+      />,
+    )
+    expect(screen.getByText('Hidden')).toBeTruthy()
+    expect(screen.getByText('(+3 not shown)')).toBeTruthy()
+  })
+
+  it('is not a button (non-interactive)', () => {
+    const { container } = render(<CategoryRowOther hiddenCount={1} />)
+    expect(container.querySelectorAll('[role="button"]').length).toBe(0)
+  })
+})

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

@@ -0,0 +1,33 @@
+import { Box, Typography } from '@mui/material'
+import { styles } from '../style'
+
+export interface CategoryRowOtherProps {
+  hiddenCount: number
+  /** Label for the overflow row. Defaults to `'Other'`. */
+  otherLabel?: string
+  /** Count text with `{count}` placeholder. Defaults to `'{count} more'`. */
+  otherCountLabel?: string
+}
+
+/**
+ * Static "Other (X more)" overflow summary row. Rendered after the last
+ * visible category row when `data.length > maxItems`. Non-interactive —
+ * no selection, no keyboard target.
+ */
+export function CategoryRowOther({
+  hiddenCount,
+  otherLabel = 'Other',
+  otherCountLabel = '{count} more',
+}: CategoryRowOtherProps) {
+  const countText = otherCountLabel.replace('{count}', String(hiddenCount))
+  return (
+    <Box sx={styles.otherRow}>
+      <Typography variant='body2' sx={styles.otherLabel}>
+        {otherLabel}
+      </Typography>
+      <Typography variant='body2' sx={styles.otherCount}>
+        ({countText})
+      </Typography>
+    </Box>
+  )
+}

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

@@ -0,0 +1,76 @@
+import type { KeyboardEvent } from 'react'
+import { Box, Typography } from '@mui/material'
+import { CategoryBar } from './category-bar'
+import type { CategoryKey, CategorySize } from '../types'
+import { styles } from '../style'
+
+export interface CategoryRowSingleProps {
+  /** Raw category key — what gets emitted to `onToggle` regardless of formatter. */
+  name: CategoryKey
+  /** Display label (post-`labelFormatter`). Falls back to `name` when omitted. */
+  displayName?: string | number
+  value: number
+  maxValue: number
+  color: string
+  formatter: (n: number) => string
+  selected: boolean
+  onToggle: (name: CategoryKey) => void
+  /** Bar visual density. Forwarded to {@link CategoryBar}. */
+  size?: CategorySize
+}
+
+/**
+ * Single-series category row: `[label] [bar] [value]` grid. Click /
+ * Enter / Space toggles `name` in/out of the selection set via
+ * `onToggle`. Selection key is always the raw `name` — `displayName` is
+ * presentation only.
+ *
+ * Visual selection / dim signal lives ENTIRELY in the bar color
+ * (`color` prop) — computed upstream by `CategoryUI` (real palette
+ * color when selected or no-selection; `theme.palette.action.disabled`
+ * when a selection exists and this row isn't in it). The row itself
+ * has no bg tint, no opacity rule.
+ */
+export function CategoryRowSingle({
+  name,
+  displayName,
+  value,
+  maxValue,
+  color,
+  formatter,
+  selected,
+  onToggle,
+  size,
+}: CategoryRowSingleProps) {
+  const handleKey = (e: KeyboardEvent<HTMLDivElement>): void => {
+    if (e.key === 'Enter' || e.key === ' ') {
+      e.preventDefault()
+      onToggle(name)
+    }
+  }
+  return (
+    <Box
+      role='button'
+      aria-pressed={selected}
+      tabIndex={0}
+      onClick={() => onToggle(name)}
+      onKeyDown={handleKey}
+      sx={styles.rowSingle}
+    >
+      <Box sx={styles.rowHeader}>
+        <Typography variant='body2' sx={styles.name}>
+          {displayName ?? name}
+        </Typography>
+        <Typography variant='body2' sx={styles.value}>
+          {formatter(value)}
+        </Typography>
+      </Box>
+      <CategoryBar
+        value={value}
+        maxValue={maxValue}
+        color={color}
+        size={size}
+      />
+    </Box>
+  )
+}

package/src/widgets-v2/category/components/category-row-stacked.test.tsx

@@ -0,0 +1,244 @@
+import { describe, it, expect, vi } from 'vitest'
+import { fireEvent, render, screen, within } from '@testing-library/react'
+import { CategoryRowStacked } from './category-row-stacked'
+
+const COLORS = ['rgb(0, 200, 0)', 'rgb(0, 100, 0)']
+
+describe('<CategoryRowStacked>', () => {
+  it('renders displayName ?? name on the left of the header', () => {
+    render(
+      <CategoryRowStacked
+        name='cat-key'
+        displayName='Cat'
+        values={[45, 32]}
+        colors={COLORS}
+        seriesNames={['Women', 'Men']}
+        formatter={(n) => String(n)}
+        selected={false}
+        onToggle={vi.fn()}
+      />,
+    )
+    expect(screen.getByText('Cat')).toBeTruthy()
+    expect(screen.queryByText('cat-key')).toBeNull()
+  })
+
+  it('falls back to the raw name when displayName is omitted', () => {
+    render(
+      <CategoryRowStacked
+        name='Plain'
+        values={[1]}
+        colors={['rgb(0, 0, 0)']}
+        seriesNames={['S']}
+        formatter={(n) => String(n)}
+        selected={false}
+        onToggle={vi.fn()}
+      />,
+    )
+    expect(screen.getByText('Plain')).toBeTruthy()
+  })
+
+  it('renders formatter(sum) on the right of the header', () => {
+    render(
+      <CategoryRowStacked
+        name='Cat'
+        values={[45, 32]}
+        colors={COLORS}
+        seriesNames={['Women', 'Men']}
+        formatter={(n) => `${n}K`}
+        selected={false}
+        onToggle={vi.fn()}
+      />,
+    )
+    expect(screen.getByText('77K')).toBeTruthy()
+  })
+
+  it('renders one breakdown entry per series, including zero values', () => {
+    render(
+      <CategoryRowStacked
+        name='Cat'
+        values={[45, 0, 32]}
+        colors={[...COLORS, 'rgb(0, 50, 0)']}
+        seriesNames={['Women', 'Other', 'Men']}
+        formatter={(n) => String(n)}
+        selected={false}
+        onToggle={vi.fn()}
+      />,
+    )
+    expect(screen.getByText('Women: 45')).toBeTruthy()
+    expect(screen.getByText('Other: 0')).toBeTruthy()
+    expect(screen.getByText('Men: 32')).toBeTruthy()
+  })
+
+  it('falls back to "Series N" for missing series names (1-indexed)', () => {
+    render(
+      <CategoryRowStacked
+        name='Cat'
+        values={[45, 32]}
+        colors={COLORS}
+        seriesNames={[]}
+        formatter={(n) => String(n)}
+        selected={false}
+        onToggle={vi.fn()}
+      />,
+    )
+    expect(screen.getByText('Series 1: 45')).toBeTruthy()
+    expect(screen.getByText('Series 2: 32')).toBeTruthy()
+  })
+
+  it('per-row normalization: bar fills 100% with segments proportional to the row sum', () => {
+    // values [30, 70] sum to 100 → segments at 30% and 70%, cumulative
+    // offsets 0% and 30%. The bar saturates regardless of any
+    // hypothetical global max — that's the point of stacked mode.
+    const { container } = render(
+      <CategoryRowStacked
+        name='Cat'
+        values={[30, 70]}
+        colors={COLORS}
+        seriesNames={['A', 'B']}
+        formatter={(n) => String(n)}
+        selected={false}
+        onToggle={vi.fn()}
+      />,
+    )
+    const fills = container.querySelectorAll<HTMLElement>(
+      '[data-bar-fill="true"]',
+    )
+    expect(fills.length).toBe(2)
+    expect(fills[0]!.style.left).toBe('0%')
+    expect(fills[0]!.style.width).toBe('30%')
+    expect(fills[1]!.style.left).toBe('30%')
+    expect(fills[1]!.style.width).toBe('70%')
+  })
+
+  it('per-row normalization: bar still fills 100% for an arbitrary row total (45 + 32 → 77)', () => {
+    const { container } = render(
+      <CategoryRowStacked
+        name='Cat'
+        values={[45, 32]}
+        colors={COLORS}
+        seriesNames={['Women', 'Men']}
+        formatter={(n) => String(n)}
+        selected={false}
+        onToggle={vi.fn()}
+      />,
+    )
+    const fills = container.querySelectorAll<HTMLElement>(
+      '[data-bar-fill="true"]',
+    )
+    // 45/77 ≈ 58.44…, 32/77 ≈ 41.56…
+    const w0 = parseFloat(fills[0]!.style.width)
+    const w1 = parseFloat(fills[1]!.style.width)
+    expect(w0 + w1).toBeCloseTo(100, 1)
+    expect(w0).toBeGreaterThan(58)
+    expect(w0).toBeLessThan(59)
+    expect(w1).toBeGreaterThan(41)
+    expect(w1).toBeLessThan(42)
+  })
+
+  it('renders the stacked bar with one data-bar-fill per non-zero series', () => {
+    const { container } = render(
+      <CategoryRowStacked
+        name='Cat'
+        values={[45, 0, 32]}
+        colors={[...COLORS, 'rgb(0, 50, 0)']}
+        seriesNames={['Women', 'Other', 'Men']}
+        formatter={(n) => String(n)}
+        selected={false}
+        onToggle={vi.fn()}
+      />,
+    )
+    const fills = container.querySelectorAll('[data-bar-fill="true"]')
+    // Zero series is skipped in the bar, present in the breakdown.
+    expect(fills).toHaveLength(2)
+  })
+
+  it('clicking anywhere in the row toggles by raw name', () => {
+    const onToggle = vi.fn()
+    render(
+      <CategoryRowStacked
+        name='raw-key'
+        displayName='Pretty'
+        values={[45, 32]}
+        colors={COLORS}
+        seriesNames={['Women', 'Men']}
+        formatter={(n) => String(n)}
+        selected={false}
+        onToggle={onToggle}
+      />,
+    )
+    fireEvent.click(screen.getByRole('button'))
+    expect(onToggle).toHaveBeenCalledWith('raw-key')
+  })
+
+  it('toggles via keyboard Enter and Space, preventing default on space', () => {
+    const onToggle = vi.fn()
+    render(
+      <CategoryRowStacked
+        name='K'
+        values={[1]}
+        colors={['rgb(0, 0, 0)']}
+        seriesNames={['S']}
+        formatter={(n) => String(n)}
+        selected={false}
+        onToggle={onToggle}
+      />,
+    )
+    const row = screen.getByRole('button')
+    fireEvent.keyDown(row, { key: 'Enter' })
+    expect(onToggle).toHaveBeenCalledWith('K')
+    onToggle.mockClear()
+    fireEvent.keyDown(row, { key: ' ' })
+    expect(onToggle).toHaveBeenCalledWith('K')
+  })
+
+  it('reflects selection via aria-pressed', () => {
+    const { rerender } = render(
+      <CategoryRowStacked
+        name='K'
+        values={[1]}
+        colors={['rgb(0, 0, 0)']}
+        seriesNames={['S']}
+        formatter={(n) => String(n)}
+        selected={false}
+        onToggle={vi.fn()}
+      />,
+    )
+    expect(screen.getByRole('button').getAttribute('aria-pressed')).toBe(
+      'false',
+    )
+    rerender(
+      <CategoryRowStacked
+        name='K'
+        values={[1]}
+        colors={['rgb(0, 0, 0)']}
+        seriesNames={['S']}
+        formatter={(n) => String(n)}
+        selected={true}
+        onToggle={vi.fn()}
+      />,
+    )
+    expect(screen.getByRole('button').getAttribute('aria-pressed')).toBe('true')
+  })
+
+  it('when dim colors are passed in, every segment paints with the dim color (breakdown text unchanged)', () => {
+    const DIM = 'rgba(0, 0, 0, 0.26)'
+    render(
+      <CategoryRowStacked
+        name='Cat'
+        values={[45, 32]}
+        colors={[DIM, DIM]}
+        seriesNames={['Women', 'Men']}
+        formatter={(n) => String(n)}
+        selected={false}
+        onToggle={vi.fn()}
+      />,
+    )
+    const row = screen.getByRole('button')
+    const fills = row.querySelectorAll<HTMLElement>('[data-bar-fill="true"]')
+    expect(fills.length).toBe(2)
+    fills.forEach((f) => expect(f.style.backgroundColor).toBe(DIM))
+    // Breakdown text remains visible and unchanged.
+    expect(within(row).getByText('Women: 45')).toBeTruthy()
+    expect(within(row).getByText('Men: 32')).toBeTruthy()
+  })
+})