@carto/ps-react-ui 5.1.0 → 6.0.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,83 @@
+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'
 
 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
 }
 
+const NO_HIDDEN_SERIES: ReadonlySet<number> = new Set()
+
 /**
- * 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/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'

package/src/widgets/category/skeleton.tsx

@@ -1,21 +1,71 @@
 import { Box, Skeleton } from '@mui/material'
-import { styles } from './style'
+import type { SxProps, Theme } from '@mui/material'
+import type { CategorySize } from './types'
 
-const widthPatterns = [85, 70, 55, 75, 60]
+const styles = {
+  root: {
+    display: 'flex',
+    flexDirection: 'column',
+    gap: 1,
+    py: 0.5,
+  },
+  // Mirror the real row layout: label + value on top, bar below.
+  row: {
+    display: 'flex',
+    flexDirection: 'column',
+    gap: 0.5,
+  },
+  rowHeader: {
+    display: 'flex',
+    justifyContent: 'space-between',
+    alignItems: 'center',
+    gap: 1,
+  },
+  // Small fixed-width shimmer pills — matches the visual density of the
+  // real label / value cells without claiming the full row width.
+  name: { height: 14, width: 80 },
+  value: { height: 14, width: 48 },
+} satisfies Record<string, SxProps<Theme>>
 
-export function CategorySkeleton() {
+// Bar shimmer height matches the live bar track for each size variant so
+// the skeleton doesn't visibly resize the row on data settle.
+const BAR_HEIGHT: Record<CategorySize, number> = {
+  small: 4,
+  medium: 12,
+}
+
+// Varied widths give the bar shimmer a more realistic, less uniform feel.
+// Cycles when `rows > WIDTH_PATTERNS.length`.
+const WIDTH_PATTERNS = ['95%', '80%', '55%', '75%', '60%']
+
+export interface CategorySkeletonProps {
+  rows?: number
+  /**
+   * Visual density. Mirrors the live widget's `size` prop so the loading
+   * shimmer's bar height matches what's about to render — no row jump
+   * on data settle.
+   */
+  size?: CategorySize
+}
+
+export function CategorySkeleton({
+  rows = 5,
+  size = 'small',
+}: CategorySkeletonProps) {
   return (
-    <Box sx={styles.list} aria-label='Category skeleton'>
-      {Array.from({ length: 5 }).map((_, index) => (
-        <Box key={index} sx={styles.row}>
+    <Box sx={styles.root}>
+      {Array.from({ length: rows }).map((_, i) => (
+        <Box key={`row-${i}`} sx={styles.row}>
           <Box sx={styles.rowHeader}>
-            <Skeleton width={80} height={16} />
-            <Skeleton width={40} height={16} />
+            <Skeleton variant='rectangular' sx={styles.name} />
+            <Skeleton variant='rectangular' sx={styles.value} />
           </Box>
           <Skeleton
             variant='rectangular'
-            height={4}
-            sx={{ borderRadius: 2, width: `${widthPatterns[index]}%` }}
+            sx={{
+              height: BAR_HEIGHT[size],
+              width: WIDTH_PATTERNS[i % WIDTH_PATTERNS.length],
+            }}
           />
         </Box>
       ))}