@carto/ps-react-ui 4.24.0 → 4.26.0

package/src/widgets-v2/actions/fullscreen/fullscreen.tsx

@@ -315,15 +315,17 @@ function DialogStore({
     const unsubscribe = subscribeEchartInstance(dialogId, (chart) => {
       // Published from inside the chart's init, before its first
       // setOption, so the dialog's own option merges on top of the copy.
+      // The empty chart takes the card's whole option: the legend, dataZoom
+      // and brush areas need the card's components (axes, brush) to land on.
       const card = liveChart(sourceId)
-      if (chart && card) copyChartState(card, chart)
+      if (chart && card) copyChartState(card, chart, card.getOption())
       dialogChart = chart
     })
     return () => {
       unsubscribe()
       const card = liveChart(sourceId)
       if (card && dialogChart && !dialogChart.isDisposed()) {
-        copyChartState(dialogChart, card)
+        copyChartState(dialogChart, card, viewState(dialogChart))
       }
     }
   }, [dialogId, sourceId])
@@ -351,10 +353,15 @@ function liveChart(id: string): ECharts | null {
 /**
  * Put on `chart` what `peer` is showing: the legend selection, the dataZoom
  * window and any drawn brush areas, which live in the ECharts instance
- * rather than the widget store.
+ * rather than the widget store. `option` is what of `peer`'s option to merge
+ * into `chart`.
  */
-function copyChartState(peer: ECharts, chart: ECharts): void {
-  chart.setOption(peer.getOption())
+function copyChartState(
+  peer: ECharts,
+  chart: ECharts,
+  option: Parameters<ECharts['setOption']>[0],
+): void {
+  chart.setOption(option)
   // The pointer was over `peer`, not `chart`: drop the tooltip and axis
   // pointer that came along, or they'd stay drawn until the next hover.
   chart.dispatchAction({ type: 'hideTip' })
@@ -374,6 +381,42 @@ function copyChartState(peer: ECharts, chart: ECharts): void {
   if (areas?.length) chart.dispatchAction({ type: 'brush', areas })
 }
 
+interface ViewStateOption {
+  // setOption takes an indexed option.
+  [key: string]: unknown
+  legend?: { selected?: Record<string, boolean> }[]
+  dataZoom?: Record<string, unknown>[]
+}
+
+const ZOOM_WINDOW_KEYS = ['start', 'end', 'startValue', 'endValue'] as const
+
+/**
+ * The part of `peer`'s option that is user view state. Only this goes back
+ * to the card on close: the dialog's full option also carries its own
+ * styling (value labels, bigger axis text), and merging it into the card
+ * would leave that styling behind once the dialog closes.
+ */
+function viewState(peer: ECharts): ViewStateOption {
+  const { legend, dataZoom } = peer.getOption() as ViewStateOption
+  const state: ViewStateOption = {}
+  if (legend?.some((l) => l.selected)) {
+    state.legend = legend.map((l) =>
+      l.selected ? { selected: l.selected } : {},
+    )
+  }
+  if (dataZoom?.length) {
+    state.dataZoom = dataZoom.map((zoom) =>
+      Object.fromEntries(
+        ZOOM_WINDOW_KEYS.filter((k) => zoom[k] !== undefined).map((k) => [
+          k,
+          zoom[k],
+        ]),
+      ),
+    )
+  }
+  return state
+}
+
 /**
  * Merge a caller's `paperSx` over the default paper.
  *

package/src/widgets-v2/bar/options.test.ts

@@ -1,4 +1,5 @@
 import { describe, it, expect } from 'vitest'
+import * as echarts from 'echarts'
 import { createTheme, type Theme } from '@mui/material'
 import { barOptions, createBarOptionFactory } from './options'
 
@@ -359,3 +360,108 @@ describe('createBarOptionFactory', () => {
     expect(html).toContain('[ITEM:A]')
   })
 })
+
+describe('createBarOptionFactory — per-item colour', () => {
+  interface Out {
+    series: { itemStyle: { color: (p: unknown) => string } }[]
+  }
+  const data = [
+    [
+      { name: 'A', value: 1, color: '#00ff00' },
+      { name: 'B', value: -2 },
+    ],
+  ]
+  const dim = (c: string) => echarts.color.modifyAlpha(c, 0.15)
+
+  it('datum colour wins over the series colour', () => {
+    const merge = createBarOptionFactory({
+      theme,
+      series: [{ name: 'S', color: '#0000ff' }],
+    })
+    const out = merge({}, data) as Out
+    const colorFn = out.series[0]!.itemStyle.color
+    expect(colorFn({ dataIndex: 0, color: '#0000ff', name: 'A' })).toBe(
+      '#00ff00',
+    )
+    expect(colorFn({ dataIndex: 1, color: '#0000ff', name: 'B' })).toBe(
+      '#0000ff',
+    )
+  })
+
+  it('uses a string template itemStyle.color from optionsOverride', () => {
+    const factory = createBarOptionFactory({
+      theme,
+      series: [{ name: 'S', color: '#0000ff' }],
+      optionsOverride: {
+        series: [{ type: 'bar', itemStyle: { color: '#123456' } }],
+      },
+    })
+    const out = factory(factory(undefined, undefined), data) as Out
+    const colorFn = out.series[0]!.itemStyle.color
+    expect(colorFn({ dataIndex: 0, color: '#0000ff', name: 'A' })).toBe(
+      '#00ff00',
+    )
+    expect(colorFn({ dataIndex: 1, color: '#0000ff', name: 'B' })).toBe(
+      '#123456',
+    )
+  })
+
+  it('calls a function template itemStyle.color with the ECharts params', () => {
+    const merge = createBarOptionFactory({ theme })
+    const out = merge(
+      {
+        series: [
+          {
+            type: 'bar',
+            itemStyle: {
+              color: (p: { dataIndex: number }) =>
+                p.dataIndex === 1 ? '#ff0000' : '#00ff00',
+            },
+          },
+        ],
+      },
+      [
+        [
+          { name: 'A', value: 1 },
+          { name: 'B', value: -2 },
+        ],
+      ],
+    ) as Out
+    const colorFn = out.series[0]!.itemStyle.color
+    expect(colorFn({ dataIndex: 0, color: '#abc', name: 'A' })).toBe('#00ff00')
+    expect(colorFn({ dataIndex: 1, color: '#abc', name: 'B' })).toBe('#ff0000')
+  })
+
+  it('resolves theme palette paths on the datum colour', () => {
+    const merge = createBarOptionFactory({ theme })
+    const out = merge({}, [[{ name: 'A', value: 1, color: 'primary.main' }]])
+    const colorFn = (out as Out).series[0]!.itemStyle.color
+    expect(colorFn({ dataIndex: 0, color: '#abc', name: 'A' })).toBe(
+      theme.palette.primary.main,
+    )
+  })
+
+  it('dims both datum and template colours outside the selection', () => {
+    const merge = createBarOptionFactory({ theme, selection: ['Z'] })
+    const out = merge(
+      { series: [{ type: 'bar', itemStyle: { color: '#123456' } }] },
+      data,
+    ) as Out
+    const colorFn = out.series[0]!.itemStyle.color
+    expect(colorFn({ dataIndex: 0, color: '#abc', name: 'A' })).toBe(
+      dim('#00ff00'),
+    )
+    expect(colorFn({ dataIndex: 1, color: '#abc', name: 'B' })).toBe(
+      dim('#123456'),
+    )
+  })
+
+  it('keeps the series / palette colour when no item colour is given', () => {
+    const merge = createBarOptionFactory({ theme, selection: ['Z'] })
+    const out = merge({}, [[{ name: 'A', value: 1 }]]) as Out
+    const colorFn = out.series[0]!.itemStyle.color
+    expect(colorFn({ dataIndex: 0, color: '#abcdef', name: 'A' })).toBe(
+      dim('#abcdef'),
+    )
+  })
+})

package/src/widgets-v2/bar/options.ts

@@ -12,6 +12,7 @@ import {
 import { ZOOM_LAYOUT } from '../actions/zoom-toggle'
 import type { OptionFactory } from '../echart'
 import { mergeOptions, resolveThemeColor } from '../utils'
+import { createItemColorResolver } from '../utils/item-color'
 import { positionDataZoomForLegend } from '../utils/data-zoom-layout'
 import type {
   BarEChartsOption,
@@ -234,10 +235,12 @@ export function createBarOptionFactory(
       : baseBottom
 
     // When a selection is active, dim non-selected bars by routing the
-    // resolved palette color through `modifyAlpha`. Per-row `itemStyle` on
+    // item's base colour through `modifyAlpha`. Per-row `itemStyle` on
     // dataset object-rows is silently ignored when `series.encode` is in
     // play — the callback approach is the standard ECharts pattern for
-    // per-data styling derived from a dataset.
+    // per-data styling derived from a dataset. The base colour is the
+    // datum's `color`, else the template's `itemStyle.color`, else the
+    // series colour / palette (`params.color`).
     //
     // We *always* emit `itemStyle.color` (a passthrough when nothing is
     // selected), not conditionally — dropping the key between renders
@@ -245,22 +248,30 @@ export function createBarOptionFactory(
     // and bars would stay dimmed forever after an external clear. Always
     // emitting lets normal merge swap the callback in place, no
     // `replaceMerge` and no entry-animation flash on selection on/off.
-    const dimItemStyle = {
-      color: (params: CallbackDataParams) => {
-        const base = params.color as string
-        if (!selectionSet) return base
-        const datum = params.value as { name?: string | number } | undefined
-        const name = datum?.name ?? params.name
-        return name != null && selectionSet.has(name)
-          ? base
-          : echarts.color.modifyAlpha(base, 0.15)
-      },
+    const makeDimItemStyle = (datums: readonly object[], template: unknown) => {
+      const baseColor = createItemColorResolver({
+        theme,
+        datums,
+        template,
+        fallback: (params) => params.color as string,
+      })
+      return {
+        color: (params: CallbackDataParams) => {
+          const base = baseColor(params)
+          if (!selectionSet) return base
+          const datum = params.value as { name?: string | number } | undefined
+          const name = datum?.name ?? params.name
+          return name != null && selectionSet.has(name)
+            ? base
+            : echarts.color.modifyAlpha(base, 0.15)
+        },
+      }
     }
 
     return {
       ...option,
       dataset: seriesArr.map((s) => ({ source: s as readonly object[] })),
-      series: seriesArr.map((_, i) => {
+      series: seriesArr.map((s, i) => {
         const template =
           (seriesTemplates[i] as object | undefined) ??
           (broadcastTemplate as object)
@@ -277,7 +288,7 @@ export function createBarOptionFactory(
           encode: { x: 'name', y: 'value' },
           barMaxWidth: 100,
           emphasis: { focus: 'series' },
-          itemStyle: dimItemStyle,
+          itemStyle: makeDimItemStyle(s, template),
           ...(overrideColor ? { color: overrideColor } : {}),
         }
       }),

package/src/widgets-v2/bar/types.ts

@@ -6,6 +6,12 @@ import type { WidgetSeries } from '../types'
 export interface BarDatum {
   name: string | number
   value: number
+  /**
+   * Optional colour for this item (CSS colour or theme palette path such as
+   * `'primary.main'`). Wins over the template's `itemStyle.color` and the
+   * series colour; selection dimming still applies on top.
+   */
+  color?: string
 }
 
 /** v2 bar widget data shape: array of series, each a flat list of `{name, value}`. */

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

@@ -814,4 +814,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
@@ -147,6 +155,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
@@ -173,13 +217,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(
@@ -231,14 +277,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
@@ -363,7 +409,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' }
@@ -413,6 +463,7 @@ export function CategoryUI({
                   selected={selected}
                   onToggle={toggle}
                   size={size}
+                  zeroPct={zeroPct}
                 />
               )
             }
@@ -424,6 +475,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}
@@ -438,6 +490,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}>