@carto/ps-react-ui 5.2.0 → 5.4.0

package/src/widgets-v2/actions/searcher/filter.test.ts

@@ -0,0 +1,28 @@
+import { describe, it, expect } from 'vitest'
+import { filterBySearchText } from './filter'
+
+const DATA = [
+  [
+    { name: 'ES', value: 1 },
+    { name: 'FR', value: 2 },
+  ],
+]
+const COUNTRIES: Record<string, string> = { ES: 'Spain', FR: 'France' }
+const label = (v: string | number) => COUNTRIES[v] ?? v
+
+describe('filterBySearchText', () => {
+  it('matches the raw name when there is no label formatter', () => {
+    expect(filterBySearchText(DATA, 'es')).toEqual([[{ name: 'ES', value: 1 }]])
+  })
+
+  it('matches the formatted label, which is what the user sees', () => {
+    expect(filterBySearchText(DATA, 'spa', label)).toEqual([
+      [{ name: 'ES', value: 1 }],
+    ])
+  })
+
+  it('no longer matches a raw name the label does not show', () => {
+    // "es" is in the raw code "ES" but in neither "Spain" nor "France".
+    expect(filterBySearchText(DATA, 'es', label)).toEqual([[]])
+  })
+})

package/src/widgets-v2/actions/searcher/filter.ts

@@ -1,9 +1,14 @@
 /**
  * Filters a 2D series of `{name, ...}` records by case-insensitive substring on
- * the `name` field. Keeps the dataset shape (one inner array per series).
+ * the label the user sees: `labelFormatter(name)` when a formatter is given,
+ * `name` otherwise. Keeps the dataset shape (one inner array per series).
  * Used by the Searcher action's data transform.
  */
-export function filterBySearchText(input: unknown, search: string): unknown {
+export function filterBySearchText(
+  input: unknown,
+  search: string,
+  labelFormatter?: (value: string | number) => string | number,
+): unknown {
   if (!search) return input
   const needle = search.toLowerCase()
   if (!Array.isArray(input)) return input
@@ -13,14 +18,27 @@ export function filterBySearchText(input: unknown, search: string): unknown {
       if (item == null) return false
       if (typeof item === 'object' && 'name' in item) {
         const rawName = (item as { name: unknown }).name
-        const name = rawName == null ? '' : stringifyPrimitive(rawName)
-        return name.toLowerCase().includes(needle)
+        return labelOf(rawName, labelFormatter).toLowerCase().includes(needle)
       }
       return stringifyPrimitive(item).toLowerCase().includes(needle)
     })
   })
 }
 
+function labelOf(
+  name: unknown,
+  labelFormatter?: (value: string | number) => string | number,
+): string {
+  if (name == null) return ''
+  if (
+    labelFormatter &&
+    (typeof name === 'string' || typeof name === 'number')
+  ) {
+    return stringifyPrimitive(labelFormatter(name))
+  }
+  return stringifyPrimitive(name)
+}
+
 function stringifyPrimitive(v: unknown): string {
   if (typeof v === 'string') return v
   if (typeof v === 'number' || typeof v === 'boolean') return String(v)

package/src/widgets-v2/actions/searcher/searcher-toggle.tsx

@@ -46,11 +46,16 @@ export function SearcherToggle({
     (s) => (s.transformStates.searcher?.searchText as string | undefined) ?? '',
   )
 
-  // The transform fn closes over `text`. Memoize via useCallback so identity
-  // only changes when text changes, allowing useTransform to re-register.
+  // Matched against the label the user sees, so a formatted name is found
+  // by what's on screen rather than by its raw value.
+  const labelFormatter = useWidget(id, (s) => s.labelFormatter)
+
+  // The transform fn closes over `text` and `labelFormatter`. Memoize via
+  // useCallback so identity only changes when either does, allowing
+  // useTransform to re-register.
   const fn = useCallback(
-    (data: unknown) => filterBySearchText(data, text),
-    [text],
+    (data: unknown) => filterBySearchText(data, text, labelFormatter),
+    [text, labelFormatter],
   )
 
   const { enabled, toggle } = useSingleTransform(id, SEARCHER_DESCRIPTOR, fn, {

package/src/widgets-v2/actions/searcher/searcher.test.tsx

@@ -89,4 +89,26 @@ describe('<Searcher> + <SearcherToggle>', () => {
       vi.useRealTimers()
     }
   })
+
+  it('filters by the formatted label the widget shows', () => {
+    const labelFormatter = (v: string | number) =>
+      ({ apple: 'Manzana', banana: 'Plátano' })[String(v)] ?? v
+    render(
+      <Provider id='sr-label' data={DATA} labelFormatter={labelFormatter}>
+        <SearcherToggle initialEnabled />
+        <Searcher />
+      </Provider>,
+    )
+    act(() =>
+      getWidgetStore('sr-label').setState((s) => ({
+        transformStates: {
+          ...s.transformStates,
+          searcher: { ...s.transformStates.searcher!, searchText: 'manz' },
+        },
+      })),
+    )
+    expect(getWidgetStore('sr-label').getState().data).toEqual([
+      [{ name: 'apple', value: 1 }],
+    ])
+  })
 })

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

@@ -906,4 +906,143 @@ describe('<CategoryUI>', () => {
       fills.forEach((f) => expect(f.style.backgroundColor).toBe(DIM))
     })
   })
+
+  // ── Signed values ──────────────────────────────────────────────────
+  describe('negative values', () => {
+    const MIXED = [
+      [
+        { name: 'Income', value: 0.8 },
+        { name: 'Transit', value: -0.4 },
+        { name: 'Size', value: 0 },
+      ],
+    ]
+    const fills = (c: HTMLElement) =>
+      Array.from(c.querySelectorAll<HTMLElement>('[data-bar-fill="true"]'))
+    const ticks = (c: HTMLElement) =>
+      Array.from(c.querySelectorAll<HTMLElement>('[data-zero-tick="true"]'))
+
+    it('centres the zero with a symmetric domain and keeps the series color', () => {
+      const { container } = render(<CategoryUI data={MIXED} />)
+      const [income, transit, size] = fills(container)
+      expect([income!.style.left, income!.style.width]).toEqual(['50%', '50%'])
+      expect([transit!.style.left, transit!.style.width]).toEqual([
+        '25%',
+        '25%',
+      ])
+      expect(size!.style.width).toBe('0%')
+      expect(transit!.style.backgroundColor).toBe(income!.style.backgroundColor)
+    })
+
+    it('marks the zero with one tick per bar, none on "Others"', () => {
+      const { container } = render(<CategoryUI data={MIXED} maxItems={2} />)
+      expect(ticks(container).map((t) => t.style.left)).toEqual(['50%', '50%'])
+      expect(screen.getByText('Others')).toBeTruthy()
+    })
+
+    it('draws one zero line per multi-series row, spanning every bar', () => {
+      const { container } = render(
+        <CategoryUI
+          data={[
+            [
+              { name: 'A', value: 1 },
+              { name: 'B', value: 2 },
+            ],
+            [
+              { name: 'A', value: -1 },
+              { name: 'B', value: 0.5 },
+            ],
+            [
+              { name: 'A', value: 0 },
+              { name: 'B', value: -2 },
+            ],
+          ]}
+        />,
+      )
+      const t = ticks(container)
+      expect(t).toHaveLength(2)
+      expect(t[0]!.style.left).toBe('50%')
+      expect(t[0]!.parentElement!.style.gridRow).toBe('2 / span 3')
+    })
+
+    it.each([
+      ['positive-only', [1, 2]],
+      ['negative-only', [-1, -2]],
+      ['all-zero', [0, 0]],
+    ])('draws no zero tick for %s data', (_, values) => {
+      const { container } = render(
+        <CategoryUI
+          data={[values.map((value, i) => ({ name: `R${i}`, value }))]}
+        />,
+      )
+      expect(ticks(container)).toHaveLength(0)
+    })
+
+    it('hangs negative-only bars from the right edge', () => {
+      const { container } = render(
+        <CategoryUI
+          data={[
+            [
+              { name: 'A', value: -2 },
+              { name: 'B', value: -1 },
+            ],
+          ]}
+        />,
+      )
+      const [a, b] = fills(container)
+      expect([a!.style.left, a!.style.width]).toEqual(['0%', '100%'])
+      expect([b!.style.left, b!.style.width]).toEqual(['50%', '50%'])
+    })
+
+    it('treats maxOverride as a magnitude for signed data', () => {
+      const { container } = render(
+        <CategoryUI data={MIXED} maxOverride={1.6} />,
+      )
+      const [income, transit] = fills(container)
+      // domain [-1.6, 1.6]
+      expect([income!.style.left, income!.style.width]).toEqual(['50%', '25%'])
+      expect(transit!.style.width).toBe('12.5%')
+    })
+
+    it('minOverride pins the zero even when the data has no negatives', () => {
+      const { container } = render(
+        <CategoryUI data={[[{ name: 'A', value: 1 }]]} minOverride={-1} />,
+      )
+      expect(fills(container)[0]!.style.left).toBe('50%')
+      expect(ticks(container)).toHaveLength(1)
+    })
+
+    it('prefixes U+2212 itself and hands the formatter |v|', () => {
+      const formatter = vi.fn((n: number) => `$${n}`)
+      render(
+        <CategoryUI
+          data={[
+            [
+              { name: 'A', value: -0.5 },
+              { name: 'B', value: -0 },
+              { name: 'C', value: 0 },
+            ],
+          ]}
+          formatter={formatter}
+        />,
+      )
+      expect(screen.getByText('\u2212$0.5')).toBeTruthy()
+      expect(screen.getAllByText('$0')).toHaveLength(2)
+      formatter.mock.calls.forEach(([n]) => expect(n).toBeGreaterThanOrEqual(0))
+    })
+
+    it('stacked mode diverges around the shared zero and shows the signed total', () => {
+      const { container } = render(
+        <CategoryUI
+          stacked
+          data={[[{ name: 'A', value: 3 }], [{ name: 'A', value: -1 }]]}
+        />,
+      )
+      const [pos, neg] = fills(container)
+      // zero at 50%, longer side (3) fills its half
+      expect([pos!.style.left, pos!.style.width]).toEqual(['50%', '50%'])
+      expect(parseFloat(neg!.style.left)).toBeCloseTo(50 - 50 / 3)
+      expect(screen.getByText('2')).toBeTruthy()
+      expect(screen.getByText('Series 2: \u22121')).toBeTruthy()
+    })
+  })
 })

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

@@ -78,8 +78,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
@@ -161,6 +169,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
@@ -187,13 +231,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(
@@ -245,14 +291,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
@@ -382,7 +428,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' }
@@ -432,6 +482,7 @@ export function CategoryUI({
                   selected={selected}
                   onToggle={toggle}
                   size={size}
+                  zeroPct={zeroPct}
                 />
               )
             }
@@ -443,6 +494,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}
@@ -457,6 +509,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-v2/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-v2/category/category.tsx

@@ -42,13 +42,19 @@ interface CategoryWidgetState extends WidgetState {
 
 const NO_HIDDEN: ReadonlySet<number> = new Set()
 
-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 {
@@ -84,6 +90,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
@@ -113,23 +125,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 = JSON.stringify(series?.map((s) => s.name) ?? [])
   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-v2/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%'],
+    ])
+  })
 })