@carto/ps-react-ui 5.1.0 → 6.0.0

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

@@ -1,166 +1,483 @@
+import { useCallback, useMemo, useRef, useState } from 'react'
 import { Box, useTheme } from '@mui/material'
-import { useWidgetSelector } from '../stores/use-widget-selector'
-import { styles } from './style'
-import type { CategoryUIProps, CategoryWidgetState } from './types'
 import { CategoryRowSingle } from './components/category-row-single'
 import { CategoryRowMulti } from './components/category-row-multi'
+import { CategoryRowStacked } from './components/category-row-stacked'
 import { CategoryRowOther } from './components/category-row-other'
 import { CategoryLegend } from './components/category-legend'
-import { useState } from 'react'
-import { defaultFormatter, defaultLabelFormatter } from '../utils/formatter'
-import { useWidgetRef } from '../../hooks'
+import type {
+  CategoryKey,
+  CategoryLabels,
+  CategorySeriesConfig,
+  CategorySize,
+  CategoryWidgetData,
+} from './types'
+import { styles } from './style'
+import { resolveThemeColor } from '../utils'
+
+const DEFAULT_MAX_ITEMS = 20
+
+// Fallback viewport height used in scroll mode ONLY when no natural
+// measurement is available yet — i.e., the consumer mounts directly into
+// `maxItems === 0` (e.g., SearcherToggle pre-enabled), so the list has
+// never rendered in capped form for us to measure.
+//
+//   small: label(~20) + gap(4) + bar(4) + list-gap(8) ≈ 36
+//   medium: label(~20) + gap(4) + bar(12) + list-gap(8) ≈ 44
+const ROW_HEIGHT_PX: Record<CategorySize, number> = { small: 36, medium: 44 }
+const SCROLL_VIEWPORT_FALLBACK_ROWS = 8
+
+export interface CategoryUIProps {
+  data: CategoryWidgetData
+  /** Currently-selected category names (destination-owned). */
+  selection?: readonly CategoryKey[]
+  /** Fires with the next selection set when a row is clicked. */
+  onSelectionChange?: (next: readonly CategoryKey[]) => void
+  /** Number formatter applied to each row's value. */
+  formatter?: (value: number) => string
+  /**
+   * Display-only transform for category names. Selection callbacks always
+   * receive the raw `item.name` regardless of this formatter.
+   */
+  labelFormatter?: (value: string | number) => string | number
+  /**
+   * Per-series metadata. Enables the legend (for multi-series) and
+   * overrides palette colors per series index. Length need not match
+   * `data.length`; mismatches degrade gracefully (extras ignored, gaps
+   * fall back to palette).
+   */
+  series?: readonly CategorySeriesConfig[]
+  /**
+   * Caps the number of visible category rows.
+   *
+   * - `undefined` (omitted) — caps at {@link DEFAULT_MAX_ITEMS} (20).
+   *   Surplus rows fold into a single "Others <count>" footer row.
+   *   `undefined` cannot mean "no cap" because it's consumed by the
+   *   default-parameter syntax — pass `null` instead.
+   * - positive finite N — same as the default but with a custom cap.
+   * - `0` — **no cap WITH scroll**: every row renders inside a
+   *   fixed-height viewport that scrolls internally. The viewport's
+   *   max-height is the list's natural `clientHeight` measured on the
+   *   first render where the list was NOT in scroll mode (i.e., the
+   *   capped view) — frozen for the component's lifetime. If the
+   *   consumer mounts directly into scroll mode and we never see a
+   *   capped render, the viewport falls back to `8 × ROW_HEIGHT_PX`.
+   *   Composers flip into this mode while the user is searching
+   *   (`maxItems = searcherOpen ? 0 : userMaxItems`) so the widget
+   *   card height stays stable.
+   * - `null` / `Infinity` / negative — **no cap, no scroll**: render
+   *   every row; the list grows with content. Matches v1's "undefined"
+   *   behavior. Use `null` as the canonical explicit form.
+   */
+  maxItems?: number | null
+  /** Labels for the "Other" overflow row. `{count}` placeholder is replaced. */
+  labels?: CategoryLabels
+  /**
+   * When provided, the "Other" overflow row becomes a button — clicking it
+   * fires `onShowAll`, which a composer typically wires to expand the widget
+   * (drop the row cap) so every category becomes reachable. When omitted the
+   * overflow row stays a static summary.
+   */
+  onShowAll?: () => void
+  /** Manual override for the bar-width denominator. */
+  maxOverride?: number
+  /**
+   * Visual density of the bar primitive. `'small'` (default) keeps the
+   * historical 4px-tall pill; `'medium'` switches to a 12px-tall track
+   * with a 2px corner radius. Only the bar track + fill change.
+   */
+  size?: CategorySize
+  /**
+   * Multi-series stacked mode. When `true` and `data.length > 1`, each
+   * category renders as a single segmented bar (one segment per series)
+   * with a `formatter(sum)` total in the header and a per-series
+   * breakdown line below. Composers typically thread this from
+   * `useTransformEnabled(id, 'stack-toggle')`.
+   *
+   * No-op for single-series data — same convention as the legend.
+   */
+  stacked?: boolean
+}
+
+interface GroupedRow {
+  name: CategoryKey
+  values: number[]
+  /** Per-series per-row color override (first non-undefined wins). */
+  rowColors: (string | undefined)[]
+}
 
 /**
- * Renders a category widget displaying horizontal bars for categorical data with support for single and multi-series layouts, selection, and overflow grouping.
+ * The hidden set as the chart applies it: indices past the current series
+ * count are ignored, and an all-hidden result falls back to all visible.
+ * The stored set is never rewritten from here, so hidden indices survive a
+ * data shrink and come back if the data regrows.
  */
-export function CategoryUI({ id }: CategoryUIProps) {
-  const { ref } = useWidgetRef<HTMLDivElement>(id)
-  const theme = useTheme()
+function effectiveHidden(
+  hidden: ReadonlySet<number>,
+  seriesCount: number,
+): Set<number> {
+  const clamped = new Set([...hidden].filter((i) => i < seriesCount))
+  return clamped.size >= seriesCount ? new Set<number>() : clamped
+}
 
-  // Single consolidated subscription instead of 9 separate ones.
-  const {
-    _formatter,
-    _labelFormatter,
-    _series,
-    data,
-    maxItems,
-    labels,
-    onRowClick,
-    selected,
-    max,
-  } = useWidgetSelector(id, (w) => {
-    const cw = w as CategoryWidgetState | undefined
-    return {
-      _formatter: cw?.formatter,
-      _labelFormatter: cw?.labelFormatter,
-      _series: cw?.series,
-      data: cw?.data,
-      maxItems: cw?.maxItems,
-      labels: cw?.labels,
-      onRowClick: cw?.onRowClick,
-      selected: cw?.selected,
-      max: cw?.max,
+/**
+ * Group items by `name` across series so each unique name produces one
+ * row containing N values (zero-filled where a series has no entry for
+ * that name). First-seen order across series is preserved.
+ *
+ * Ported from v1
+ * (`packages/react-ui/src/widgets/category/category-ui.tsx:137-166`)
+ * with readonly typing + per-row color capture.
+ */
+function generateGroupedData(data: CategoryWidgetData): GroupedRow[] {
+  if (!data || data.length === 0) return []
+  const seriesCount = Math.max(data.length, 1)
+  const grouped = new Map<CategoryKey, GroupedRow>()
+  const order: CategoryKey[] = []
+  for (let s = 0; s < data.length; s++) {
+    const series = data[s] ?? []
+    for (const item of series) {
+      let row = grouped.get(item.name)
+      if (!row) {
+        row = {
+          name: item.name,
+          values: new Array<number>(seriesCount).fill(0),
+          rowColors: new Array<string | undefined>(seriesCount).fill(undefined),
+        }
+        grouped.set(item.name, row)
+        order.push(item.name)
+      }
+      row.values[s] = item.value
+      row.rowColors[s] = item.color
     }
-  })
+  }
+  return order.map((k) => grouped.get(k)!)
+}
+
+/**
+ * Pure presentational component for the Category widget. Renders
+ * single-series rows (`data.length === 1`) as a compact grid or
+ * multi-series rows (`data.length > 1`) as stacked-bar groups, capped at
+ * `maxItems` with an overflow summary, and an optional sticky color
+ * legend when `series` metadata is supplied.
+ *
+ * Selection is destination-owned: clicking a row fires
+ * `onSelectionChange(next)` with the toggled set; the consumer keeps the
+ * list in their own store. `aria-pressed` + Enter/Space keyboard
+ * activation give full a11y parity with the mouse path.
+ *
+ * Returns `null` when there's nothing to render — `Widget.State` is the
+ * empty-state authority in the canonical compositor.
+ */
+export function CategoryUI({
+  data,
+  selection,
+  onSelectionChange,
+  formatter,
+  labelFormatter,
+  series,
+  maxItems = DEFAULT_MAX_ITEMS,
+  labels,
+  onShowAll,
+  maxOverride,
+  size = 'small',
+  stacked = false,
+}: CategoryUIProps) {
+  const theme = useTheme()
+  const fmt = formatter ?? ((n: number) => String(n))
 
-  const formatter = _formatter ?? defaultFormatter
-  const labelFormatter = _labelFormatter ?? defaultLabelFormatter
-  const series = _series ?? []
+  const hasSelection = !!selection && selection.length > 0
+  const selectionSet = useMemo(
+    () => new Set<CategoryKey>(selection ?? []),
+    [selection],
+  )
 
-  const [maxHeight] = useState<string | number | undefined>(
-    maxItems ? 40 * (series.length || 1) * maxItems : undefined,
+  const toggle = useCallback(
+    (name: CategoryKey) => {
+      if (!onSelectionChange) return
+      const cur = selection ?? []
+      const next = cur.includes(name)
+        ? cur.filter((n) => n !== name)
+        : [...cur, name]
+      onSelectionChange(next)
+    },
+    [onSelectionChange, selection],
   )
 
-  const qualitativeColors = Object.values(theme.palette.qualitative.bold)
+  // Palette: same convention as Bar/Pie/Histogram/Scatterplot/Timeseries v2.
+  const paletteColors = useMemo<readonly string[]>(
+    () => [
+      theme.palette.secondary.main,
+      ...Object.values(
+        (theme.palette as { qualitative?: { bold?: Record<string, string> } })
+          .qualitative?.bold ?? {},
+      ),
+    ],
+    [theme],
+  )
 
-  const colors =
-    series.length > 0
-      ? series.map(
-          (s, index: number) =>
-            s.color ??
-            qualitativeColors[index % qualitativeColors.length] ??
-            theme.palette.secondary.main,
-        )
-      : [theme.palette.secondary.main]
+  // Resolved here, not at the paint site: the bars and the legend dot use
+  // inline `style` to keep emotion from minting a class per value/colour
+  // pair, and inline style has no theme resolver behind it — a caller's
+  // `'primary.main'` would reach the DOM verbatim and paint nothing.
+  const colorAt = useCallback(
+    (seriesIndex: number, rowColor?: string): string => {
+      const override = rowColor ?? series?.[seriesIndex]?.color
+      if (override) return resolveThemeColor(theme, override) ?? override
+      return (
+        paletteColors[seriesIndex % paletteColors.length] ??
+        theme.palette.secondary.main
+      )
+    },
+    [series, paletteColors, theme],
+  )
 
-  // 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 })
+  // Dim color for non-selected rows when a selection exists. Swapped in
+  // at the bar-fill level only — text + track stay at their real colors.
+  // Theme-driven so it survives palette swaps.
+  const dimColor = theme.palette.action.disabled
 
-  if (groupedData.length === 0) {
-    return null
+  const grouped = useMemo(() => generateGroupedData(data), [data])
+
+  const maxValue = useMemo(() => {
+    if (typeof maxOverride === 'number' && maxOverride > 0) return maxOverride
+    let m = 0
+    for (const row of grouped) {
+      for (const v of row.values) if (v > m) m = v
+    }
+    return m
+  }, [grouped, maxOverride])
+
+  // Three modes:
+  //   * positive finite N (default `DEFAULT_MAX_ITEMS = 20` when prop
+  //     omitted): cap at N rows; surplus folds into "Others <count>".
+  //   * `0`: no cap WITH scroll — every row renders, the list locks to a
+  //     fixed viewport and scrolls internally. Composers use this to
+  //     bypass pagination while the user is searching:
+  //         `maxItems = searcherOpen ? 0 : userMaxItems`
+  //   * `null` / `Infinity` / negative: no cap, no scroll — every row
+  //     renders and the list grows with content. `null` is the canonical
+  //     explicit form (`undefined` is consumed by the default param above).
+  const scrollMode = maxItems === 0
+
+  // Natural-height measurement. In scroll mode (`maxItems === 0`,
+  // set by the composer when the SearcherToggle is open) every row
+  // renders inside a scrollable viewport. The viewport's max-height
+  // must match the pre-overflow content area — i.e., whatever the
+  // list was rendering BEFORE the composer dropped the cap.
+  //
+  // We measure the list's `clientHeight` exactly once, the first time
+  // it attaches while NOT in scroll mode (otherwise we'd capture the
+  // wrong layout). Once set, `naturalHeight` is the lock anchor
+  // forever — matches v1's frozen-at-mount semantics, just with a
+  // real DOM measurement instead of a hard-coded constant.
+  //
+  // Implemented via a callback ref instead of `useLayoutEffect` so
+  // setState fires during commit, not inside an effect — satisfies
+  // the `react-hooks/set-state-in-effect` rule. React invokes
+  // callback refs on attach (and re-invokes them when the callback
+  // identity changes, which it does when `scrollMode` flips), so
+  // toggling the searcher off after a scroll-mode mount triggers the
+  // first measurement at that point.
+  //
+  // Fallback: if the consumer never lands a non-scroll render
+  // (e.g., searcher pre-enabled and never closed), `naturalHeight`
+  // stays `null` → viewport falls back to `8 × ROW_HEIGHT_PX`.
+  const measuredRef = useRef(false)
+  const [naturalHeight, setNaturalHeight] = useState<number | null>(null)
+  const listRefCallback = useCallback(
+    (node: HTMLDivElement | null) => {
+      if (!node) return
+      if (measuredRef.current) return
+      if (scrollMode) return
+      const h = node.clientHeight
+      if (h > 0) {
+        measuredRef.current = true
+        setNaturalHeight(h)
+      }
+    },
+    [scrollMode],
+  )
+
+  // Which series are hidden via a legend click. Local UI-only state — not
+  // synced to `selection`/`onSelectionChange` (that's row-level filter
+  // selection, unrelated). Never allowed to reach "every series hidden":
+  // toggling the last visible one instead resets to "all visible" rather
+  // than leaving the widget blank.
+  const [hiddenSeries, setHiddenSeries] = useState<ReadonlySet<number>>(
+    () => new Set(),
+  )
+  // A reload with a different series breakdown invalidates hidden indices —
+  // index 2 may now point at an entirely different series. Reset rather
+  // than keep hiding whatever now occupies a stale index. Adjusted directly
+  // during render (React's documented "adjusting state when a prop changes"
+  // pattern) instead of in a `useEffect`, which would commit the stale
+  // hidden-set for one extra frame before the effect fires. Compared by a
+  // content-derived key, not the raw `series` reference — an inline
+  // `series={[...]}` literal (no useMemo) gets a new reference on every
+  // unrelated parent re-render, which would otherwise reset hiddenSeries
+  // right after the user hides one.
+  const seriesKey = JSON.stringify(series?.map((s) => s.name) ?? [])
+  const [prevSeriesKey, setPrevSeriesKey] = useState(seriesKey)
+  if (seriesKey !== prevSeriesKey) {
+    setPrevSeriesKey(seriesKey)
+    setHiddenSeries(new Set())
   }
+  // Real number of data series — NOT `series?.length`, which is legend
+  // metadata and may legitimately be shorter than the actual series count
+  // (unnamed trailing series fall back to `Series N`). Using the metadata
+  // length here would trip the "never fully hidden" guard early whenever
+  // `series` is shorter than `data`.
+  const seriesCount = Math.max(data.length, 1)
+  const toggleSeries = useCallback(
+    (index: number) => {
+      setHiddenSeries((prev) => {
+        // Start from what the user sees, not the stored set: `data` can
+        // shrink while the `series` names hold (the reset only watches the
+        // names), and a stale index would otherwise count toward the guard
+        // below — or make unchecking one series hide a different one.
+        const next = effectiveHidden(prev, seriesCount)
+        if (next.has(index)) next.delete(index)
+        else next.add(index)
+        return next.size >= seriesCount ? new Set() : next
+      })
+    },
+    [seriesCount],
+  )
+
+  if (grouped.length === 0) return null
 
-  const maxValue =
-    max ?? Math.max(...groupedData.flatMap((item) => item.values))
+  const hasCap =
+    typeof maxItems === 'number' && Number.isFinite(maxItems) && maxItems > 0
+  const visible = hasCap ? grouped.slice(0, maxItems) : grouped
+  const hiddenCount = hasCap ? grouped.length - visible.length : 0
 
-  // Slice data to maxItems and compute hidden count
-  const visibleData =
-    maxItems !== undefined && maxItems >= 0
-      ? groupedData.slice(0, maxItems)
-      : groupedData
+  const isMulti = data.length > 1
+  const hasLegend = isMulti && !!series && series.length > 0
+  // Invariant across every row in this render — only depends on
+  // `hiddenSeries`/`seriesCount`, not on any particular row's data — so
+  // it's computed once here instead of per row inside the render loop.
+  const activeHidden = effectiveHidden(hiddenSeries, seriesCount)
+  const visibleIdx = Array.from({ length: seriesCount }, (_, i) => i).filter(
+    (i) => !activeHidden.has(i),
+  )
 
-  const hiddenCount = groupedData.length - visibleData.length
-  const isMulti = series.length > 1
+  // Fallback viewport height matches the documented "8 × ROW_HEIGHT_PX"
+  // (see the constants at the top of the file). Earlier code multiplied
+  // this by `seriesCount`, making a 3-series widget render 3× the
+  // intended viewport on the first frame before `naturalHeight` was
+  // measured — a visible layout jump.
+  const scrollMaxHeight = scrollMode
+    ? (naturalHeight ?? ROW_HEIGHT_PX[size] * SCROLL_VIEWPORT_FALLBACK_ROWS)
+    : undefined
 
   return (
-    <Box
-      ref={ref}
-      sx={{
-        ...styles.root,
-      }}
-    >
+    <Box sx={styles.root}>
       <Box
-        sx={styles.list}
-        style={{ maxHeight, overflow: hiddenCount === 0 ? 'auto' : 'hidden' }}
+        ref={listRefCallback}
+        sx={scrollMode ? { ...styles.list, ...styles.listScroll } : styles.list}
+        style={
+          scrollMaxHeight !== undefined
+            ? { maxHeight: scrollMaxHeight, overflowY: 'auto' }
+            : undefined
+        }
       >
-        {isMulti
-          ? visibleData.map((item) => (
+        {visible.map((row) => {
+          const selected = selectionSet.has(row.name)
+          const dimmed = hasSelection && !selected
+          const displayName = labelFormatter
+            ? labelFormatter(row.name)
+            : undefined
+          // When the row is dimmed, every series' bar fill is replaced
+          // with `dimColor`. Text + track are untouched. This is the
+          // ONLY visual difference between selected and non-selected
+          // rows — no row-level opacity, no `rowSelected` bg tint.
+          const fill = (i: number): string =>
+            dimmed ? dimColor : colorAt(i, row.rowColors[i])
+          // Series hidden via the legend are dropped before reaching the
+          // row components — they render whatever arrays they're given
+          // with no notion of "hidden" themselves. `visibleIdx` is hoisted
+          // above this loop (same for every row).
+          if (isMulti) {
+            if (stacked) {
+              // Stacked-mode branch: one segmented bar per row. Toggling
+              // `stacked` after the natural-height measurement does NOT
+              // re-trigger measurement (see the `naturalHeight` comment
+              // above) — accepted trade-off: stacked rows have a slightly
+              // different height, so the scroll viewport may show extra
+              // whitespace after the toggle. Visual only, not functional.
+              // Stacked rows are per-row normalized — they don't take
+              // the global `maxValue`. Each row's bar fills 100% of the
+              // track and the segments split it by `value_i / sum`. The
+              // numeric total in the header preserves the per-row
+              // magnitude information.
+              return (
+                <CategoryRowStacked
+                  key={String(row.name)}
+                  name={row.name}
+                  displayName={displayName}
+                  values={visibleIdx.map((i) => row.values[i]!)}
+                  colors={visibleIdx.map((i) => fill(i))}
+                  seriesNames={visibleIdx.map(
+                    (i) => series?.[i]?.name ?? `Series ${i + 1}`,
+                  )}
+                  formatter={fmt}
+                  selected={selected}
+                  onToggle={toggle}
+                  size={size}
+                />
+              )
+            }
+            return (
               <CategoryRowMulti
-                key={item.name}
-                name={item.name}
-                values={item.values}
+                key={String(row.name)}
+                name={row.name}
+                displayName={displayName}
+                values={visibleIdx.map((i) => row.values[i]!)}
+                colors={visibleIdx.map((i) => fill(i))}
                 maxValue={maxValue}
-                colors={colors}
-                formatter={formatter}
-                labelFormatter={labelFormatter}
-                onClick={onRowClick}
-                selected={selected?.(item.name) ?? true}
+                formatter={fmt}
+                selected={selected}
+                onToggle={toggle}
+                size={size}
               />
-            ))
-          : 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}
-                labelFormatter={labelFormatter}
-                onClick={onRowClick}
-              />
-            ))}
+            )
+          }
+          return (
+            <CategoryRowSingle
+              key={String(row.name)}
+              name={row.name}
+              displayName={displayName}
+              value={row.values[0] ?? 0}
+              maxValue={maxValue}
+              color={fill(0)}
+              formatter={fmt}
+              selected={selected}
+              onToggle={toggle}
+              size={size}
+            />
+          )
+        })}
         {hiddenCount > 0 && (
           <CategoryRowOther
             hiddenCount={hiddenCount}
             otherLabel={labels?.other}
             otherCountLabel={labels?.otherCount}
+            showAllLabel={labels?.showAll}
+            onShowAll={onShowAll}
           />
         )}
       </Box>
-      {series.length > 0 && <CategoryLegend series={series} colors={colors} />}
+      {hasLegend && series && (
+        <CategoryLegend
+          // Trimmed: `series` is caller metadata and may outrun `data`,
+          // and an entry with no data behind it has nothing to hide.
+          series={series.slice(0, seriesCount)}
+          colorAt={(i) => colorAt(i)}
+          hiddenSeries={activeHidden}
+          onToggle={toggleSeries}
+        />
+      )}
     </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-v2 → widgets}/category/components/category-bar-stacked.tsx

@@ -1,3 +1,4 @@
+import type { CssColor } from '../../../components/types'
 import { Box } from '@mui/material'
 import type { CategorySize } from '../types'
 import { styles } from '../style'
@@ -6,7 +7,7 @@ export interface CategoryBarStackedProps {
   /** One value per series. Zero values render no segment (visually + in the DOM). */
   values: readonly number[]
   /** One color per series. Resolved upstream by `CategoryUI.colorAt`. */
-  colors: readonly string[]
+  colors: readonly CssColor[]
   /**
    * Shared denominator across all rows + series (or `maxOverride`). Same
    * value `CategoryBar` uses — segments scale identically to single-bar rows