@carto/ps-react-ui 5.3.0 → 6.1.0

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

@@ -1,31 +1,50 @@
+import type { CssColor } from '../../../components/types'
 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
-  color: string
-  selected?: boolean
+  /** Fill color, already resolved by `CategoryUI.colorAt`. */
+  color: CssColor
+  /**
+   * 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
 }
 
 /**
- * Renders a single horizontal bar fill proportional to its value relative to the maximum.
+ * 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,
-  selected = true,
+  size = 'small',
 }: CategoryBarProps) {
-  const percentage = maxValue > 0 ? (value / maxValue) * 100 : 0
-
-  const barFillSx = selected
-    ? { ...styles.barFill, width: `${percentage}%`, backgroundColor: color }
-    : { ...styles.barFill, ...styles.barFillMuted, width: `${percentage}%` }
-
+  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}>
-      <Box sx={barFillSx} />
+    <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 → widgets}/category/components/category-legend.test.tsx

@@ -33,17 +33,21 @@ describe('<CategoryLegend>', () => {
     expect(screen.getByText('2025')).toBeTruthy()
   })
 
-  it('per-series color override (series[i].color) wins over colorAt(i)', () => {
+  it('paints whatever colorAt(i) returns, ignoring series[i].color', () => {
+    // The precedence (row colour, then series colour, then palette) and the
+    // theme-path resolution both live in `CategoryUI.colorAt`. Reading
+    // `series[i].color` here again would bypass the resolution and paint an
+    // unresolved path into an inline style, which renders nothing.
     const { container } = render(
       <CategoryLegend
-        series={[{ name: 'S1', color: 'rgb(99, 0, 0)' }]}
+        series={[{ name: 'S1', color: 'primary.main' }]}
         colorAt={() => 'rgb(0, 0, 0)'}
         hiddenSeries={noHidden}
         onToggle={noop}
       />,
     )
     const dot = Array.from(container.querySelectorAll('div')).find(
-      (d) => (d as HTMLElement).style.backgroundColor === 'rgb(99, 0, 0)',
+      (d) => (d as HTMLElement).style.backgroundColor === 'rgb(0, 0, 0)',
     )
     expect(dot).toBeTruthy()
   })

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

@@ -1,33 +1,82 @@
+import type { CssColor } from '../../../components/types'
 import { Box, Typography } from '@mui/material'
-import { styles } from '../style'
 import type { CategorySeriesConfig } from '../types'
+import { styles } from '../style'
+import { NO_HIDDEN_SERIES } from '../helpers'
 
 export interface CategoryLegendProps {
-  series: CategorySeriesConfig[]
-  colors: string[]
+  /** 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) => CssColor | undefined
+  /**
+   * Series indices currently hidden from the chart. Renders dimmed.
+   * Optional — defaults to none hidden. Added after this component's first
+   * release; kept optional (not required) so it stays a non-breaking
+   * addition for any direct consumer of `CategoryLegend` (a public
+   * subpath export) that predates the hide feature.
+   */
+  hiddenSeries?: ReadonlySet<number>
+  /**
+   * Fires with the series index when its legend item is clicked. Optional
+   * — omitting it renders a legend with no hide affordance (same
+   * reasoning as `hiddenSeries`).
+   */
+  onToggle?: (index: number) => void
 }
 
 /**
- * Renders a color-coded legend for multi-series category widgets.
+ * Sticky color legend rendered below a multi-series Category list.
+ * Per-series `color` overrides the matching `colorAt(i)` result. Clicking an
+ * item toggles that series' visibility in the rows above (mirrors ECharts'
+ * native legend click-to-hide).
  */
-export function CategoryLegend({ series, colors }: CategoryLegendProps) {
-  if (series.length === 0) {
-    return null
-  }
-
+export function CategoryLegend({
+  series,
+  colorAt,
+  hiddenSeries = NO_HIDDEN_SERIES,
+  onToggle,
+}: CategoryLegendProps) {
+  if (series.length === 0) return null
   return (
     <Box sx={styles.legend}>
-      {series.map((item, index) => (
-        <Box key={item.name} sx={styles.legendItem}>
+      {series.map((s, i) => {
+        const hidden = hiddenSeries.has(i)
+        return (
           <Box
-            sx={{
-              ...styles.legendDot,
-              backgroundColor: item.color ?? colors[index % colors.length],
+            key={s.name}
+            // `checkbox`/`aria-checked`, not `button`/`aria-pressed` — this
+            // toggles a persistent visibility state (closer to a checkbox)
+            // AND keeps it out of `getByRole('button')` queries that count
+            // category ROWS throughout this widget's test suite.
+            role='checkbox'
+            aria-checked={!hidden}
+            tabIndex={0}
+            onClick={() => onToggle?.(i)}
+            onKeyDown={(e) => {
+              if (e.key === 'Enter' || e.key === ' ') {
+                e.preventDefault()
+                onToggle?.(i)
+              }
             }}
-          />
-          <Typography sx={styles.legendLabel}>{item.name}</Typography>
-        </Box>
-      ))}
+            sx={hidden ? styles.legendItemHidden : styles.legendItem}
+          >
+            <Box
+              sx={styles.legendDot}
+              style={{ backgroundColor: colorAt(i) }}
+            />
+            <Typography variant='caption' sx={styles.legendLabel}>
+              {s.name}
+            </Typography>
+          </Box>
+        )
+      })}
     </Box>
   )
 }

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

@@ -1,57 +1,87 @@
+import type { CssColor } from '../../../components/types'
+import type { KeyboardEvent } from 'react'
 import { Box, Typography } from '@mui/material'
-import { styles } from '../style'
 import { CategoryBar } from './category-bar'
-import type { CategoryWidgetConfig } from '../types'
+import type { CategoryKey, CategorySize } from '../types'
+import { styles } from '../style'
 
 export interface CategoryRowMultiProps {
-  name: string
-  values: number[]
+  /** 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 CssColor[]
+  /** Shared max across all series + rows (or `maxOverride`). */
   maxValue: number
-  colors: string[]
-  formatter: NonNullable<CategoryWidgetConfig['formatter']>
-  labelFormatter?: CategoryWidgetConfig['labelFormatter']
-  onClick?: CategoryWidgetConfig['onRowClick']
-  selected?: boolean
+  formatter: (n: number) => string
+  selected: boolean
+  onToggle: (name: CategoryKey) => void
+  /** Bar visual density. Forwarded to every {@link CategoryBar} in the row. */
+  size?: CategorySize
 }
 
 /**
- * Renders a multi-series category row with a label and multiple color-coded bars stacked vertically.
+ * 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,
-  maxValue,
   colors,
+  maxValue,
   formatter,
-  labelFormatter,
-  onClick,
-  selected = true,
+  selected,
+  onToggle,
+  size,
 }: CategoryRowMultiProps) {
-  const handleClick = onClick ? () => onClick({ name }) : undefined
-  const rowStyle = onClick ? styles.rowClickable : styles.row
-
+  const handleKey = (e: KeyboardEvent<HTMLDivElement>): void => {
+    if (e.key === 'Enter' || e.key === ' ') {
+      e.preventDefault()
+      onToggle(name)
+    }
+  }
   return (
-    <Box sx={rowStyle} onClick={handleClick}>
-      <Typography sx={styles.rowLabel}>
-        {labelFormatter ? labelFormatter(name) : name}
+    <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>
-      <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>
+      {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>
-        ))}
-      </Box>
+          <Typography variant='body2' sx={styles.value}>
+            {formatter(v)}
+          </Typography>
+        </Box>
+      ))}
     </Box>
   )
 }

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

@@ -1,26 +1,84 @@
+import type { KeyboardEvent } from 'react'
 import { Box, Typography } from '@mui/material'
+import { Tooltip } from '../../../components'
 import { styles } from '../style'
 
 export interface CategoryRowOtherProps {
   hiddenCount: number
+  /** Label for the overflow row. Defaults to `'Others'`. */
   otherLabel?: string
+  /** Count text with `{count}` placeholder. Defaults to `'{count}'`. */
   otherCountLabel?: string
+  /**
+   * When provided, the row becomes a button: clicking it (or Enter/Space)
+   * fires `onShowAll`, expanding the widget to reveal every category. When
+   * omitted the row renders as a static, non-interactive summary.
+   */
+  onShowAll?: () => void
+  /** Tooltip shown over the button form. Defaults to `'Show all'`. */
+  showAllLabel?: string
 }
 
 /**
- * Renders an "Other" summary row indicating how many additional categories are hidden beyond `maxItems`.
+ * Overflow summary row rendered after the last visible category row when
+ * `data.length > maxItems`. Shows `Others <count>` (count muted, no
+ * parentheses).
+ *
+ * When `onShowAll` is supplied the row is an interactive button — clicking
+ * it (or Enter/Space) expands the widget to show all categories, mirroring
+ * the Searcher's full-list view. Without `onShowAll` it stays a static,
+ * non-interactive summary (backward-compatible default).
  */
 export function CategoryRowOther({
   hiddenCount,
-  otherLabel = 'Other',
-  otherCountLabel = '{count} more',
+  otherLabel = 'Others',
+  otherCountLabel = '{count}',
+  onShowAll,
+  showAllLabel = 'Show all',
 }: CategoryRowOtherProps) {
   const countText = otherCountLabel.replace('{count}', String(hiddenCount))
 
+  const count = (
+    <Typography variant='body2' sx={styles.otherCount}>
+      {countText}
+    </Typography>
+  )
+
+  if (!onShowAll) {
+    return (
+      <Box sx={styles.otherRow}>
+        <Typography variant='body2' sx={styles.otherLabel}>
+          {otherLabel}
+        </Typography>
+        {count}
+      </Box>
+    )
+  }
+
+  const handleKey = (e: KeyboardEvent<HTMLSpanElement>): void => {
+    if (e.key === 'Enter' || e.key === ' ') {
+      e.preventDefault()
+      onShowAll()
+    }
+  }
+
+  // Only the label is the click target; the count stays static beside it.
   return (
     <Box sx={styles.otherRow}>
-      <Typography sx={styles.otherLabel}>{otherLabel}</Typography>
-      <Typography sx={styles.otherCount}>({countText})</Typography>
+      <Tooltip title={showAllLabel}>
+        <Typography
+          variant='body2'
+          component='span'
+          role='button'
+          tabIndex={0}
+          onClick={onShowAll}
+          onKeyDown={handleKey}
+          sx={{ ...styles.otherLabel, ...styles.otherLabelButton }}
+        >
+          {otherLabel}
+        </Typography>
+      </Tooltip>
+      {count}
     </Box>
   )
 }

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

@@ -1,53 +1,76 @@
+import type { CssColor } from '../../../components/types'
+import type { KeyboardEvent } from 'react'
 import { Box, Typography } from '@mui/material'
-import { styles } from '../style'
 import { CategoryBar } from './category-bar'
-import type { CategoryWidgetConfig } from '../types'
+import type { CategoryKey, CategorySize } from '../types'
+import { styles } from '../style'
 
 export interface CategoryRowSingleProps {
-  name: string
+  /** 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: NonNullable<CategoryWidgetConfig['formatter']>
-  labelFormatter?: CategoryWidgetConfig['labelFormatter']
-  onClick?: CategoryWidgetConfig['onRowClick']
-  selected?: boolean
+  color: CssColor
+  formatter: (n: number) => string
+  selected: boolean
+  onToggle: (name: CategoryKey) => void
+  /** Bar visual density. Forwarded to {@link CategoryBar}. */
+  size?: CategorySize
 }
 
 /**
- * Renders a single-series category row with a label, formatted value, and proportional bar.
+ * 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,
-  labelFormatter,
-  onClick,
-  selected = true,
+  selected,
+  onToggle,
+  size,
 }: CategoryRowSingleProps) {
-  const handleClick = onClick
-    ? () =>
-        onClick({
-          name,
-        })
-    : undefined
-  const rowStyle = onClick ? styles.rowClickable : styles.row
-
+  const handleKey = (e: KeyboardEvent<HTMLDivElement>): void => {
+    if (e.key === 'Enter' || e.key === ' ') {
+      e.preventDefault()
+      onToggle(name)
+    }
+  }
   return (
-    <Box sx={rowStyle} onClick={handleClick}>
+    <Box
+      role='button'
+      aria-pressed={selected}
+      tabIndex={0}
+      onClick={() => onToggle(name)}
+      onKeyDown={handleKey}
+      sx={styles.rowSingle}
+    >
       <Box sx={styles.rowHeader}>
-        <Typography sx={styles.rowLabel}>
-          {labelFormatter ? labelFormatter(name) : name}
+        <Typography variant='body2' sx={styles.name}>
+          {displayName ?? name}
+        </Typography>
+        <Typography variant='body2' sx={styles.value}>
+          {formatter(value)}
         </Typography>
-        <Typography sx={styles.rowValue}>{formatter(value)}</Typography>
       </Box>
       <CategoryBar
         value={value}
         maxValue={maxValue}
         color={color}
-        selected={selected}
+        size={size}
       />
     </Box>
   )

package/src/{widgets-v2 → widgets}/category/components/category-row-stacked.tsx

@@ -1,3 +1,4 @@
+import type { CssColor } from '../../../components/types'
 import type { KeyboardEvent } from 'react'
 import { Box, Typography } from '@mui/material'
 import { CategoryBarStacked } from './category-bar-stacked'
@@ -12,7 +13,7 @@ export interface CategoryRowStackedProps {
   /** One value per series. Zero values still appear in the breakdown row. */
   values: readonly number[]
   /** One color per series (palette + per-series overrides resolved upstream). */
-  colors: readonly string[]
+  colors: readonly CssColor[]
   /**
    * Series names for the breakdown row, one per visible series, already
    * resolved by the caller (unnamed series fall back to `Series N` using

package/src/widgets/category/download.ts

@@ -0,0 +1,37 @@
+import {
+  buildCsvDownloadItem,
+  withPngItem,
+  type DownloadItem,
+  type WidgetDownloadArgs,
+} from '../actions/download'
+import type { CategoryWidgetData } from './types'
+
+/**
+ * Download menu items for the Category widget. Always includes a CSV item
+ * with `series, name, value` columns (one row per item). When `getCaptureEl`
+ * is given, prepends a PNG item that rasterises the captured element via
+ * `html2canvas`.
+ */
+export function createCategoryDownloadConfig(
+  args: WidgetDownloadArgs<CategoryWidgetData> & {
+    seriesNames?: readonly string[]
+  },
+): DownloadItem[] {
+  return withPngItem(
+    args,
+    buildCsvDownloadItem({
+      filename: args.filename,
+      getRows: (ctx) => {
+        const data = args.getData(ctx)
+        const rows: unknown[][] = [['series', 'name', 'value']]
+        for (const [i, series] of data.entries()) {
+          const seriesName = args.seriesNames?.[i] ?? `series_${i + 1}`
+          for (const item of series) {
+            rows.push([seriesName, item.name, item.value])
+          }
+        }
+        return rows
+      },
+    }),
+  )
+}

package/src/widgets/category/helpers.test.ts

@@ -0,0 +1,17 @@
+import { describe, it, expect } from 'vitest'
+import { categorySeriesKey } from './helpers'
+
+describe('categorySeriesKey', () => {
+  it('depends on the series names only', () => {
+    expect(categorySeriesKey([{ name: 'A' }, { name: 'B' }])).toBe(
+      categorySeriesKey([{ name: 'A', color: 'red' }, { name: 'B' }]),
+    )
+    expect(categorySeriesKey([{ name: 'A' }])).not.toBe(
+      categorySeriesKey([{ name: 'B' }]),
+    )
+  })
+
+  it('treats no series as an empty breakdown', () => {
+    expect(categorySeriesKey(undefined)).toBe(categorySeriesKey([]))
+  })
+})

package/src/widgets/category/helpers.ts

@@ -0,0 +1,16 @@
+import type { CategorySeriesConfig } from './types'
+
+/** Shared empty set: "no series hidden" without a new identity per render. */
+export const NO_HIDDEN_SERIES: ReadonlySet<number> = new Set()
+
+/**
+ * Identifies a series breakdown by its names. Hidden-series indices are only
+ * valid for the breakdown they were made for, and both the store copy (in
+ * `Category`) and the local one (in `CategoryUI`) are tagged with this key —
+ * so they must compute it the same way.
+ */
+export function categorySeriesKey(
+  series: readonly CategorySeriesConfig[] | undefined,
+): string {
+  return JSON.stringify(series?.map((s) => s.name) ?? [])
+}

package/src/widgets/category/index.ts

@@ -1,29 +1,32 @@
-export { CategoryUI } from './category-ui'
-export { CategorySkeleton } from './skeleton'
-export { categoryConfig, categoryDownloadConfig } from './config'
+export { Category, type CategoryProps } from './category'
+export { CategoryUI, type CategoryUIProps } from './category-ui'
+export { CategorySkeleton, type CategorySkeletonProps } from './skeleton'
+export { createCategoryDownloadConfig } from './download'
 
-export { CategoryBar } from './components/category-bar'
-export type { CategoryBarProps } from './components/category-bar'
-
-export { CategoryRowSingle } from './components/category-row-single'
-export type { CategoryRowSingleProps } from './components/category-row-single'
-
-export { CategoryRowMulti } from './components/category-row-multi'
-export type { CategoryRowMultiProps } from './components/category-row-multi'
-
-export { CategoryRowOther } from './components/category-row-other'
-export type { CategoryRowOtherProps } from './components/category-row-other'
-
-export { CategoryLegend } from './components/category-legend'
-export type { CategoryLegendProps } from './components/category-legend'
+// Sub-components — subpath-only (not on the curated `Widget` namespace).
+export { CategoryBar, type CategoryBarProps } from './components/category-bar'
+export {
+  CategoryRowSingle,
+  type CategoryRowSingleProps,
+} from './components/category-row-single'
+export {
+  CategoryRowMulti,
+  type CategoryRowMultiProps,
+} from './components/category-row-multi'
+export {
+  CategoryRowOther,
+  type CategoryRowOtherProps,
+} from './components/category-row-other'
+export {
+  CategoryLegend,
+  type CategoryLegendProps,
+} from './components/category-legend'
 
 export type {
-  CategoryUIProps,
-  CategoryWidgetData,
-  CategoryWidgetState,
-  CategoryWidgetConfig,
-  CategoryDownloadConfig,
   CategoryDataItem,
+  CategoryWidgetData,
+  CategoryKey,
   CategorySeriesConfig,
   CategoryLabels,
+  CategorySize,
 } from './types'