@carto/ps-react-ui 6.1.1 → 6.3.0

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

@@ -80,8 +80,16 @@ export interface CategoryUIProps {
    * overflow row stays a static summary.
    */
   onShowAll?: () => void
-  /** Manual override for the bar-width denominator. */
+  /**
+   * Manual override for the top of the bar scale. With signed data it is a
+   * magnitude: the scale stays symmetric around the centred zero.
+   */
   maxOverride?: number
+  /**
+   * Manual override for the bottom of the bar scale, the negative mirror of
+   * `maxOverride`. Ignored unless negative.
+   */
+  minOverride?: number
   /**
    * Visual density of the bar primitive. `'small'` (default) keeps the
    * historical 4px-tall pill; `'medium'` switches to a 12px-tall track
@@ -163,6 +171,42 @@ function generateGroupedData(data: CategoryWidgetData): GroupedRow[] {
   return order.map((k) => grouped.get(k)!)
 }
 
+/**
+ * Bar domain `[lo, hi]`, always containing zero. Positive-only data keeps
+ * the zero at the left edge and negative-only at the right; mixed data is
+ * made symmetric so the zero sits in the middle of the track.
+ */
+function signedDomain(
+  rows: readonly GroupedRow[],
+  minOverride?: number,
+  maxOverride?: number,
+): [lo: number, hi: number] {
+  let lo = 0
+  let hi = 0
+  for (const row of rows) {
+    for (const v of row.values) {
+      if (v < lo) lo = v
+      if (v > hi) hi = v
+    }
+  }
+  if (typeof minOverride === 'number' && minOverride < 0) lo = minOverride
+  if (typeof maxOverride === 'number' && maxOverride > 0) hi = maxOverride
+  if (lo < 0 && hi > 0) {
+    const m = Math.max(-lo, hi)
+    return [-m, m]
+  }
+  return [lo, hi]
+}
+
+/**
+ * The widget owns the sign: `formatter` only ever sees `|v|`, so a formatter
+ * that prefixes a unit reads `−$5`, not `$-5`, and one that emits its own
+ * `-` cannot double it. U+2212 is as wide as a tabular digit.
+ */
+function formatSigned(fmt: (n: number) => string, v: number): string {
+  return (v < 0 ? '\u2212' : '') + fmt(Math.abs(v))
+}
+
 /**
  * Pure presentational component for the Category widget. Renders
  * single-series rows (`data.length === 1`) as a compact grid or
@@ -189,13 +233,15 @@ export function CategoryUI({
   labels,
   onShowAll,
   maxOverride,
+  minOverride,
   size = 'small',
   stacked = false,
   hiddenSeries: hiddenSeriesProp,
   onHiddenSeriesChange,
 }: CategoryUIProps) {
   const theme = useTheme()
-  const fmt = formatter ?? ((n: number) => String(n))
+  const baseFmt = formatter ?? ((n: number) => String(n))
+  const fmt = (n: number) => formatSigned(baseFmt, n)
 
   const hasSelection = !!selection && selection.length > 0
   const selectionSet = useMemo(
@@ -250,14 +296,14 @@ export function CategoryUI({
 
   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])
+  const [minValue, maxValue] = useMemo(
+    () => signedDomain(grouped, minOverride, maxOverride),
+    [grouped, minOverride, maxOverride],
+  )
+  // Where the zero sits on the track, handed to stacked rows so their zero
+  // matches the other rows'. Positive-only data keeps it at the left edge.
+  const zeroPct =
+    maxValue > minValue ? (-minValue / (maxValue - minValue)) * 100 : 0
 
   // Three modes:
   //   * positive finite N (default `DEFAULT_MAX_ITEMS = 20` when prop
@@ -387,7 +433,11 @@ export function CategoryUI({
     <Box sx={styles.root}>
       <Box
         ref={listRefCallback}
-        sx={scrollMode ? { ...styles.list, ...styles.listScroll } : styles.list}
+        sx={{
+          ...styles.list,
+          ...(isMulti && !stacked && styles.listMulti),
+          ...(scrollMode && styles.listScroll),
+        }}
         style={
           scrollMaxHeight !== undefined
             ? { maxHeight: scrollMaxHeight, overflowY: 'auto' }
@@ -437,6 +487,7 @@ export function CategoryUI({
                   selected={selected}
                   onToggle={toggle}
                   size={size}
+                  zeroPct={zeroPct}
                 />
               )
             }
@@ -448,6 +499,7 @@ export function CategoryUI({
                 values={visibleIdx.map((i) => row.values[i]!)}
                 colors={visibleIdx.map((i) => fill(i))}
                 maxValue={maxValue}
+                minValue={minValue}
                 formatter={fmt}
                 selected={selected}
                 onToggle={toggle}
@@ -462,6 +514,7 @@ export function CategoryUI({
               displayName={displayName}
               value={row.values[0] ?? 0}
               maxValue={maxValue}
+              minValue={minValue}
               color={fill(0)}
               formatter={fmt}
               selected={selected}

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

@@ -238,6 +238,73 @@ describe('<Category> bridge', () => {
       expect(fills[0]!.style.width).toBe('25%')
     })
 
+    it('keeps the zero centred when a transform hides every negative row', () => {
+      render(
+        <Provider
+          id='cat-bridge-auto-neg'
+          data={[
+            [
+              { name: 'A', value: 1 },
+              { name: 'B', value: -1 },
+            ],
+          ]}
+        >
+          <Category />
+        </Provider>,
+      )
+      act(() => {
+        getWidgetStore('cat-bridge-auto-neg').setState({
+          data: [[{ name: 'A', value: 1 }]],
+        })
+      })
+      const fills = getBarFills()
+      expect(fills).toHaveLength(1)
+      expect(fills[0]!.style.left).toBe('50%')
+      expect(fills[0]!.style.width).toBe('50%')
+    })
+
+    it.each([
+      [
+        'positive-only',
+        [50, 25],
+        [
+          ['0%', '50%'],
+          ['0%', '25%'],
+        ],
+      ],
+      [
+        'negative-only',
+        [-50, -25],
+        [
+          ['50%', '50%'],
+          ['75%', '25%'],
+        ],
+      ],
+      [
+        'mixed',
+        [50, -25],
+        [
+          ['50%', '25%'],
+          ['37.5%', '12.5%'],
+        ],
+      ],
+    ])(
+      'applies ±100 overrides only on the side %s data reaches',
+      (_, values, expected) => {
+        render(
+          <Provider
+            id={`cat-bridge-side-${values.join('')}`}
+            data={[values.map((value, i) => ({ name: `R${i}`, value }))]}
+          >
+            <Category maxOverride={100} minOverride={-100} />
+          </Provider>,
+        )
+        expect(getBarFills().map((f) => [f.style.left, f.style.width])).toEqual(
+          expected,
+        )
+      },
+    )
+
     it('consumer-supplied maxOverride wins over the rawData auto-fill', () => {
       render(
         <Provider id='cat-bridge-auto-3' data={PEAK_DATA}>

package/src/widgets/category/category.tsx

@@ -41,13 +41,19 @@ interface CategoryWidgetState extends WidgetState {
   categoryHiddenSeries?: { key: string; indices: ReadonlySet<number> }
 }
 
-function maxFromCategoryData(d: CategoryWidgetData | undefined): number {
-  if (!d) return 0
-  let m = 0
-  for (const series of d) {
-    for (const item of series) if (item.value > m) m = item.value
+/** `[min, max]` of every value, each clamped to include zero. */
+function extentFromCategoryData(
+  d: CategoryWidgetData | undefined,
+): [min: number, max: number] {
+  let min = 0
+  let max = 0
+  for (const series of d ?? []) {
+    for (const item of series) {
+      if (item.value < min) min = item.value
+      if (item.value > max) max = item.value
+    }
   }
-  return m
+  return [min, max]
 }
 
 export interface CategoryProps {
@@ -83,6 +89,12 @@ export interface CategoryProps {
    * regardless of the data.
    */
   maxOverride?: number
+  /**
+   * Bottom of the bar scale for negative values, the mirror of
+   * `maxOverride`. Auto-filled from `rawData` the same way, so the zero
+   * does not move when the Searcher hides every negative row.
+   */
+  minOverride?: number
   /**
    * Visual density of the bar primitive. `'small'` (default) keeps the
    * historical 4px-tall pill; `'medium'` switches to a 12px-tall track
@@ -112,23 +124,27 @@ export function Category({
   labels,
   onShowAll,
   maxOverride,
+  minOverride,
   size,
   stacked,
 }: CategoryProps) {
   const id = useWidgetId()
   const slice = useWidgetShallow(id, categorySelector)
-  // Auto-fill `maxOverride` from `rawData` so bar widths stay coherent
-  // across data transforms (e.g., the Searcher filtering rows in/out).
-  // Consumer's explicit value always wins; we only fill when omitted
-  // AND `rawData` has at least one positive value (CategoryUI's
-  // `maxOverride > 0` guard would reject 0 anyway, but skipping is
-  // cleaner — it lets the live fallback path handle the empty case).
-  const naturalMax = useMemo(
-    () => maxFromCategoryData(slice.rawData),
+  // Auto-fill both ends of the scale from `rawData` so bar widths and the
+  // zero stay coherent across data transforms (e.g., the Searcher filtering
+  // rows in/out). Consumer's explicit value wins, but each end only applies
+  // when `rawData` reaches past zero on that side: a relative-data wiring can
+  // then pass `100` / `-100` unconditionally and positive-only data keeps its
+  // zero at the left edge, negative-only at the right. With no data on a side
+  // we pass nothing and CategoryUI falls back to the live `data`.
+  const [naturalMin, naturalMax] = useMemo(
+    () => extentFromCategoryData(slice.rawData),
     [slice.rawData],
   )
   const effectiveMaxOverride =
-    maxOverride ?? (naturalMax > 0 ? naturalMax : undefined)
+    naturalMax > 0 ? (maxOverride ?? naturalMax) : undefined
+  const effectiveMinOverride =
+    naturalMin < 0 ? (minOverride ?? naturalMin) : undefined
 
   const seriesKey = categorySeriesKey(series)
   const stored = useWidget<
@@ -156,6 +172,7 @@ export function Category({
       labels={labels}
       onShowAll={onShowAll}
       maxOverride={effectiveMaxOverride}
+      minOverride={effectiveMinOverride}
       size={size}
       stacked={stacked}
       hiddenSeries={hiddenSeries}

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

@@ -118,4 +118,22 @@ describe('<CategoryBarStacked>', () => {
     const track = container.querySelector('[data-size]')
     expect(track!.getAttribute('data-size')).toBe('medium')
   })
+
+  it('diverges from zeroPct: positives stack rightwards, negatives leftwards', () => {
+    const { container } = render(
+      <CategoryBarStacked
+        values={[20, -10, 30, -20]}
+        colors={['a', 'b', 'c', 'd']}
+        maxValue={100}
+        zeroPct={50}
+      />,
+    )
+    const segs = getSegments(container)
+    expect(segs.map((s) => [s.style.left, s.style.width])).toEqual([
+      ['50%', '20%'],
+      ['40%', '10%'],
+      ['70%', '30%'],
+      ['20%', '20%'],
+    ])
+  })
 })

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

@@ -2,6 +2,7 @@ import type { CssColor } from '../../../components/types'
 import { Box } from '@mui/material'
 import type { CategorySize } from '../types'
 import { styles } from '../style'
+import { ZeroTickWrap } from './category-bar'
 
 export interface CategoryBarStackedProps {
   /** One value per series. Zero values render no segment (visually + in the DOM). */
@@ -14,6 +15,13 @@ export interface CategoryBarStackedProps {
    * so cross-row comparison is preserved.
    */
   maxValue: number
+  /**
+   * Where the zero sits, as a percentage of the track. `0` (default) is the
+   * positive-only layout. Positive segments stack rightwards from it and
+   * negative ones leftwards, both scaled by `maxValue` against the full
+   * track width.
+   */
+  zeroPct?: number
   /** Visual density. Forwarded to the track styling; segments inherit height. */
   size?: CategorySize
 }
@@ -34,41 +42,46 @@ export function CategoryBarStacked({
   values,
   colors,
   maxValue,
+  zeroPct = 0,
   size = 'small',
 }: CategoryBarStackedProps) {
-  // Cumulative offsets pre-computed up front so the render map function
-  // stays pure (no mutable closure variable — keeps the React Compiler
-  // immutability check happy).
-  const offsets: number[] = []
+  // Left edges pre-computed up front so the render map function stays pure
+  // (no mutable closure variable — keeps the React Compiler immutability
+  // check happy). Each sign keeps its own running sum away from the zero.
+  const lefts: number[] = []
   {
-    let acc = 0
+    let pos = 0
+    let neg = 0
     for (const v of values) {
-      offsets.push(acc)
-      acc += v
+      if (v < 0) neg -= v
+      lefts.push(v < 0 ? -neg : pos)
+      if (v > 0) pos += v
     }
   }
   return (
-    <Box sx={styles.bar[size]} data-size={size}>
-      {values.map((v, i) => {
-        if (v <= 0) return null
-        const leftPct = maxValue > 0 ? (offsets[i]! / maxValue) * 100 : 0
-        const pct = maxValue > 0 ? (v / maxValue) * 100 : 0
-        return (
-          <Box
-            // Segments are keyed by per-series colour (the only stable
-            // distinguishing field on this side) plus the segment index for
-            // when callers reuse palette colours across series.
-            key={`seg-${colors[i] ?? 'none'}-${i}`}
-            sx={styles.stackedSegment[size]}
-            style={{
-              left: `${leftPct}%`,
-              width: `${pct}%`,
-              backgroundColor: colors[i] ?? '',
-            }}
-            data-bar-fill='true'
-          />
-        )
-      })}
-    </Box>
+    <ZeroTickWrap zeroPct={zeroPct > 0 && zeroPct < 100 ? zeroPct : undefined}>
+      <Box sx={styles.bar[size]} data-size={size}>
+        {values.map((v, i) => {
+          if (v === 0 || maxValue <= 0) return null
+          const leftPct = zeroPct + (lefts[i]! / maxValue) * 100
+          const pct = (Math.abs(v) / maxValue) * 100
+          return (
+            <Box
+              // Segments are keyed by per-series colour (the only stable
+              // distinguishing field on this side) plus the segment index for
+              // when callers reuse palette colours across series.
+              key={`seg-${colors[i] ?? 'none'}-${i}`}
+              sx={styles.stackedSegment[size]}
+              style={{
+                left: `${leftPct}%`,
+                width: `${pct}%`,
+                backgroundColor: colors[i] ?? '',
+              }}
+              data-bar-fill='true'
+            />
+          )
+        })}
+      </Box>
+    </ZeroTickWrap>
   )
 }

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

@@ -61,4 +61,70 @@ describe('<CategoryBar>', () => {
     expect(track).toBeTruthy()
     expect(track!.getAttribute('data-size')).toBe('medium')
   })
+
+  describe('signed domain (minValue < 0)', () => {
+    it('grows a positive value rightwards from the zero', () => {
+      const { container } = render(
+        <CategoryBar
+          value={0.5}
+          minValue={-1}
+          maxValue={1}
+          color='rgb(0, 0, 0)'
+        />,
+      )
+      const fill = getFill(container)!
+      expect(fill.style.left).toBe('50%')
+      expect(fill.style.width).toBe('25%')
+    })
+
+    it('grows a negative value leftwards from the zero, in the same color', () => {
+      const { container } = render(
+        <CategoryBar
+          value={-0.5}
+          minValue={-1}
+          maxValue={1}
+          color='rgb(0, 200, 0)'
+        />,
+      )
+      const fill = getFill(container)!
+      expect(fill.style.left).toBe('25%')
+      expect(fill.style.width).toBe('25%')
+      expect(fill.style.backgroundColor).toBe('rgb(0, 200, 0)')
+    })
+
+    it('squares the end that grows out of the zero', () => {
+      const { container: pos } = render(
+        <CategoryBar value={1} minValue={-1} maxValue={1} color='red' />,
+      )
+      const { container: neg } = render(
+        <CategoryBar value={-1} minValue={-1} maxValue={1} color='red' />,
+      )
+      expect(getFill(pos)!.style.borderTopLeftRadius).toBe('0px')
+      expect(getFill(pos)!.style.borderTopRightRadius).toBe('')
+      expect(getFill(neg)!.style.borderTopRightRadius).toBe('0px')
+      expect(getFill(neg)!.style.borderTopLeftRadius).toBe('')
+    })
+
+    it('puts the zero tick before the track so the bar paints over it', () => {
+      const { container } = render(
+        <CategoryBar value={1} minValue={-1} maxValue={1} color='red' />,
+      )
+      const tick = container.querySelector('[data-zero-tick="true"]')!
+      expect(tick.nextElementSibling!.getAttribute('data-size')).toBe('small')
+    })
+
+    it('hangs from the right edge when the domain is negative-only', () => {
+      const { container } = render(
+        <CategoryBar
+          value={-1}
+          minValue={-4}
+          maxValue={0}
+          color='rgb(0, 0, 0)'
+        />,
+      )
+      const fill = getFill(container)!
+      expect(fill.style.left).toBe('75%')
+      expect(fill.style.width).toBe('25%')
+    })
+  })
 })

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

@@ -1,4 +1,5 @@
 import type { CssColor } from '../../../components/types'
+import type { ReactNode } from 'react'
 import { Box } from '@mui/material'
 import type { CategorySize } from '../types'
 import { styles } from '../style'
@@ -6,8 +7,15 @@ 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). */
+  /** Upper end of the domain. `maxValue === minValue` → empty bar (no division by zero). */
   maxValue: number
+  /**
+   * Lower end of the domain. `0` (default) keeps the positive-only bar
+   * anchored at the left edge; a negative value moves the zero to
+   * `-minValue / (maxValue - minValue)` and bars grow from there in either
+   * direction, keeping the fill `color` whatever the sign.
+   */
+  minValue?: number
   /** Fill color, already resolved by `CategoryUI.colorAt`. */
   color: CssColor
   /**
@@ -17,6 +25,11 @@ export interface CategoryBarProps {
    * size-invariant.
    */
   size?: CategorySize
+  /**
+   * Draw the zero tick when the domain is signed. `false` when the parent
+   * draws its own zero line (multi-series rows span it across every bar).
+   */
+  zeroTick?: boolean
 }
 
 /**
@@ -28,23 +41,66 @@ export interface CategoryBarProps {
 export function CategoryBar({
   value,
   maxValue,
+  minValue = 0,
   color,
   size = 'small',
+  zeroTick = true,
 }: CategoryBarProps) {
-  const pct = maxValue > 0 ? (value / maxValue) * 100 : 0
+  const range = maxValue - minValue
+  const leftPct =
+    range > 0 ? ((Math.min(0, value) - minValue) / range) * 100 : 0
+  const pct = range > 0 ? (Math.abs(value) / range) * 100 : 0
+  const hasZeroTick = zeroTick && minValue < 0 && maxValue > 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}>
+    <ZeroTickWrap zeroPct={hasZeroTick ? (-minValue / range) * 100 : undefined}>
+      <Box sx={styles.bar[size]} data-size={size}>
+        <Box
+          sx={styles.barFill[size]}
+          style={{
+            left: `${leftPct}%`,
+            width: `${pct}%`,
+            backgroundColor: color,
+            // The end that grows out of the zero is square; only the far
+            // end keeps the rounded corners.
+            ...(value < 0
+              ? { borderTopRightRadius: 0, borderBottomRightRadius: 0 }
+              : { borderTopLeftRadius: 0, borderBottomLeftRadius: 0 }),
+          }}
+          // 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>
+    </ZeroTickWrap>
+  )
+}
+
+/**
+ * Wraps a bar track and, when `zeroPct` is set, marks the zero with a tick
+ * that overhangs the track. Positive-only, negative-only and all-zero bars
+ * pass `undefined` and get no tick.
+ */
+export function ZeroTickWrap({
+  zeroPct,
+  children,
+}: {
+  zeroPct: number | undefined
+  children: ReactNode
+}) {
+  if (zeroPct === undefined) return children
+  return (
+    <Box sx={styles.barWrap}>
       <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'
+        aria-hidden
+        data-zero-tick='true'
+        sx={styles.zeroTick}
+        style={{ left: `${zeroPct}%` }}
       />
+      {children}
     </Box>
   )
 }

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

@@ -16,6 +16,8 @@ export interface CategoryRowMultiProps {
   colors: readonly CssColor[]
   /** Shared max across all series + rows (or `maxOverride`). */
   maxValue: number
+  /** Lower end of the shared domain (`0` for positive-only data). */
+  minValue?: number
   formatter: (n: number) => string
   selected: boolean
   onToggle: (name: CategoryKey) => void
@@ -41,11 +43,13 @@ export function CategoryRowMulti({
   values,
   colors,
   maxValue,
+  minValue,
   formatter,
   selected,
   onToggle,
   size,
 }: CategoryRowMultiProps) {
+  const min = minValue ?? 0
   const handleKey = (e: KeyboardEvent<HTMLDivElement>): void => {
     if (e.key === 'Enter' || e.key === ' ') {
       e.preventDefault()
@@ -64,6 +68,21 @@ export function CategoryRowMulti({
       <Typography variant='body2' sx={styles.multiName}>
         {displayName ?? name}
       </Typography>
+      {min < 0 && maxValue > 0 && (
+        <Box
+          aria-hidden
+          sx={styles.multiZeroArea}
+          // Row 1 is the label; the bars fill the next `values.length` rows.
+          // Placed before the bars so their tracks paint over the line.
+          style={{ gridRow: `2 / span ${values.length}` }}
+        >
+          <Box
+            data-zero-tick='true'
+            sx={styles.zeroTick}
+            style={{ left: `${(-min / (maxValue - min)) * 100}%` }}
+          />
+        </Box>
+      )}
       {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
@@ -73,8 +92,10 @@ export function CategoryRowMulti({
             <CategoryBar
               value={v}
               maxValue={maxValue}
+              minValue={minValue}
               color={colors[i] ?? ''}
               size={size}
+              zeroTick={false}
             />
           </Box>
           <Typography variant='body2' sx={styles.value}>

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

@@ -12,6 +12,8 @@ export interface CategoryRowSingleProps {
   displayName?: string | number
   value: number
   maxValue: number
+  /** Lower end of the shared domain (`0` for positive-only data). */
+  minValue?: number
   color: CssColor
   formatter: (n: number) => string
   selected: boolean
@@ -37,6 +39,7 @@ export function CategoryRowSingle({
   displayName,
   value,
   maxValue,
+  minValue,
   color,
   formatter,
   selected,
@@ -69,6 +72,7 @@ export function CategoryRowSingle({
       <CategoryBar
         value={value}
         maxValue={maxValue}
+        minValue={minValue}
         color={color}
         size={size}
       />