@carto/ps-react-ui 4.25.0 → 4.27.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/actions/index.ts

@@ -46,6 +46,7 @@ export {
   DEFAULT_RELATIVE_DATA_LABELS,
   type RelativeDataProps,
   type RelativeDataLabels,
+  type RelativeScale,
 } from './relative-data'
 export {
   Download,

package/src/widgets-v2/actions/relative-data/index.ts

@@ -1,3 +1,4 @@
 export { RelativeData, type RelativeDataProps } from './relative-data'
 export { toRelativeData, createPercentFormatter } from './transforms'
+export type { RelativeScale } from './scale'
 export { DEFAULT_RELATIVE_DATA_LABELS, type RelativeDataLabels } from './labels'

package/src/widgets-v2/actions/relative-data/labels.ts

@@ -1,9 +1,15 @@
 export interface RelativeDataLabels {
   on: string
   off: string
+  scaleMenu: string
+  scaleMax: string
+  scaleTotal: string
 }
 
 export const DEFAULT_RELATIVE_DATA_LABELS: RelativeDataLabels = {
   on: 'Show absolute values',
   off: 'Show relative values',
+  scaleMenu: 'Relative scale',
+  scaleMax: 'Relative to max',
+  scaleTotal: 'Relative to total',
 }

package/src/widgets-v2/actions/relative-data/relative-data.test.tsx

@@ -1,5 +1,5 @@
 import { describe, it, expect, beforeEach, afterEach } from 'vitest'
-import { render } from '@testing-library/react'
+import { act, fireEvent, render, screen } from '@testing-library/react'
 import { Provider } from '../../provider/widget-provider'
 import { clearAllWidgetStores, getWidgetStore } from '../../stores'
 import { RelativeData } from './relative-data'
@@ -69,3 +69,80 @@ describe('<RelativeData> — rawFormatter-driven restoration', () => {
     expect(s.formatter).toBe(fmtA)
   })
 })
+
+describe('<RelativeData> — scale', () => {
+  const DATA = [
+    [
+      { name: 'a', value: 50 },
+      { name: 'b', value: 150 },
+    ],
+  ]
+  const values = (id: string) =>
+    (getWidgetStore(id).getState().data as { value: number }[][])[0]!.map(
+      (d) => d.value,
+    )
+  // The value axis a structural option ends up with after the action's
+  // config transform.
+  const yAxis = (id: string) => {
+    const xf = getWidgetStore(id)
+      .getState()
+      .configTransforms.find((t) => t.id === 'relative-data-axis')!
+    return (xf.fn({ yAxis: { type: 'value' } }) as { yAxis: object }).yAxis
+  }
+  const slot = (id: string) =>
+    getWidgetStore(id).getState().transformStates['relative-data']
+
+  it("defaults to 'max': values are shares of the total, axis left to the data", () => {
+    render(
+      <Provider id='sc1' data={DATA}>
+        <RelativeData initialEnabled />
+      </Provider>,
+    )
+    expect(values('sc1')).toEqual([25, 75])
+    expect(yAxis('sc1')).toEqual({ type: 'value' })
+    expect(slot('sc1')).toMatchObject({ enabled: true, scale: 'max' })
+  })
+
+  it("scale='total' keeps the same values and pins the axis to ±100", () => {
+    render(
+      <Provider id='sc2' data={DATA}>
+        <RelativeData initialEnabled scale='total' />
+      </Provider>,
+    )
+    expect(values('sc2')).toEqual([25, 75])
+    expect(yAxis('sc2')).toEqual({ type: 'value', min: -100, max: 100 })
+  })
+
+  it('picking a scale in the menu switches it and turns relative on', () => {
+    render(
+      <Provider id='sc3' data={DATA}>
+        <RelativeData />
+      </Provider>,
+    )
+    fireEvent.click(screen.getByRole('button', { name: 'Relative scale' }))
+    fireEvent.click(screen.getByRole('menuitem', { name: 'Relative to total' }))
+    expect(slot('sc3')).toMatchObject({ enabled: true, scale: 'total' })
+    expect(values('sc3')).toEqual([25, 75])
+    expect(yAxis('sc3')).toMatchObject({ max: 100 })
+  })
+
+  it('follows a scale written to the store from outside', () => {
+    render(
+      <Provider id='sc4' data={DATA}>
+        <RelativeData initialEnabled />
+      </Provider>,
+    )
+    act(() => {
+      getWidgetStore('sc4').setState((s) => ({
+        transformStates: {
+          ...s.transformStates,
+          'relative-data': {
+            ...s.transformStates['relative-data']!,
+            scale: 'total',
+          },
+        },
+      }))
+    })
+    expect(yAxis('sc4')).toMatchObject({ max: 100 })
+  })
+})

package/src/widgets-v2/actions/relative-data/relative-data.tsx

@@ -1,25 +1,56 @@
-import { useEffect, useMemo, type ComponentType } from 'react'
-import { IconButton, type SvgIconProps } from '@mui/material'
-import { Percent as PercentIcon } from '@mui/icons-material'
+import { useEffect, useMemo, useState, type ComponentType } from 'react'
+import {
+  Box,
+  IconButton,
+  ListItemText,
+  Menu,
+  MenuItem,
+  type SvgIconProps,
+} from '@mui/material'
+import {
+  ArrowDropDown as ArrowDropDownIcon,
+  Percent as PercentIcon,
+} from '@mui/icons-material'
 import { Tooltip } from '../../../components'
 import {
   getWidgetStore,
-  useSingleTransform,
+  useTransform,
   useWidget,
   useWidgetId,
+  type TransformPair,
 } from '../../stores'
 import { createPercentFormatter, toRelativeData } from './transforms'
+import {
+  RELATIVE_DATA_ID,
+  toRelativeTotalAxis,
+  type RelativeScale,
+} from './scale'
 import { DEFAULT_RELATIVE_DATA_LABELS, type RelativeDataLabels } from './labels'
 import { styles } from './style'
 
 const DATA_DESCRIPTOR = {
-  id: 'relative-data',
+  id: RELATIVE_DATA_ID,
   type: 'data' as const,
   order: 15,
 }
 
+const AXIS_DESCRIPTOR = {
+  id: 'relative-data-axis',
+  type: 'config' as const,
+  order: 15,
+}
+
+const identity = (option: unknown) => option
+
 export interface RelativeDataProps {
   initialEnabled?: boolean
+  /**
+   * Initial bar scale: `'max'` (the largest item fills its bar) or
+   * `'total'` (bars end at 100%). Values are the share of the total
+   * either way. Only seeds the store — the menu, or a write to
+   * `transformStates['relative-data'].scale`, changes it afterwards.
+   */
+  scale?: RelativeScale
   /**
    * BCP-47 locale tag forwarded to `Intl.NumberFormat`. Defaults to the
    * runtime locale.
@@ -43,7 +74,8 @@ export interface RelativeDataProps {
 }
 
 /**
- * Toggle between absolute and relative (percentage) values.
+ * Toggle between absolute and relative (percentage) values, as a split
+ * button: the toggle plus an arrow that opens the scale menu.
  *
  *   - **Data side**: a single data transform ({@link toRelativeData}) registered
  *     through `useSingleTransform`. When disabled, the pipeline skips it and the
@@ -53,9 +85,15 @@ export interface RelativeDataProps {
  *     reads `state.rawFormatter` (the consumer-supplied original, always live)
  *     and writes it back to `formatter`. No "original" snapshot is captured —
  *     `rawFormatter` is the original.
+ *   - **Scale**: lives in `transformStates['relative-data'].scale` next to
+ *     `enabled`, so duplicate mounts (Toolbox inline + overflow) and
+ *     `keepAlive` remounts agree on it. It never changes the values; under
+ *     `'total'` a config transform pins the ECharts value axis to 100%, and
+ *     Category reads it through `selectRelativeScale`.
  */
 export function RelativeData({
   initialEnabled = false,
+  scale: initialScale = 'max',
   locale,
   labels,
   icon: Icon = PercentIcon,
@@ -65,12 +103,39 @@ export function RelativeData({
   const id = useWidgetId()
   const _labels = { ...DEFAULT_RELATIVE_DATA_LABELS, ...labels }
 
-  const { enabled, toggle } = useSingleTransform(
+  const persistedScale = useWidget(
     id,
-    DATA_DESCRIPTOR,
-    transform ?? toRelativeData,
-    { initialEnabled },
+    (s) =>
+      s.transformStates[DATA_DESCRIPTOR.id]?.scale as RelativeScale | undefined,
   )
+  const scale = persistedScale ?? initialScale
+
+  const pairs = useMemo<readonly TransformPair[]>(
+    () => [
+      { descriptor: DATA_DESCRIPTOR, fn: transform ?? toRelativeData },
+      {
+        descriptor: AXIS_DESCRIPTOR,
+        fn: scale === 'total' ? toRelativeTotalAxis : identity,
+      },
+    ],
+    [transform, scale],
+  )
+
+  const { enabled, setEnabled, toggle } = useTransform(id, pairs, {
+    initialEnabled,
+  })
+
+  useEffect(() => {
+    if (persistedScale === undefined)
+      writeScale(id, initialScale, initialEnabled)
+  }, [id, persistedScale, initialScale, initialEnabled])
+
+  const [anchorEl, setAnchorEl] = useState<HTMLElement | null>(null)
+  const selectScale = (next: RelativeScale) => {
+    writeScale(id, next, initialEnabled)
+    setEnabled(true)
+    setAnchorEl(null)
+  }
 
   const percentFormatter = useMemo(
     () => createPercentFormatter(locale),
@@ -92,16 +157,68 @@ export function RelativeData({
   const tooltip = enabled ? _labels.on : _labels.off
 
   return (
-    <Tooltip title={tooltip}>
-      <IconButton
-        size='small'
-        aria-label={tooltip}
-        aria-pressed={enabled}
-        onClick={toggle}
-        sx={{ ...styles.toggle, ...(enabled && styles.toggleActive) }}
+    <Box sx={styles.group}>
+      <Tooltip title={tooltip}>
+        <IconButton
+          size='small'
+          aria-label={tooltip}
+          aria-pressed={enabled}
+          onClick={toggle}
+          sx={{ ...styles.toggle, ...(enabled && styles.toggleActive) }}
+        >
+          <Icon fontSize='small' {...iconProps} />
+        </IconButton>
+      </Tooltip>
+      <Tooltip title={_labels.scaleMenu}>
+        <IconButton
+          size='small'
+          aria-label={_labels.scaleMenu}
+          aria-haspopup='true'
+          aria-expanded={anchorEl ? 'true' : undefined}
+          onClick={(e) => setAnchorEl(e.currentTarget)}
+          sx={styles.arrow}
+        >
+          <ArrowDropDownIcon />
+        </IconButton>
+      </Tooltip>
+      <Menu
+        anchorEl={anchorEl}
+        open={Boolean(anchorEl)}
+        onClose={() => setAnchorEl(null)}
+        variant='menu'
+        elevation={8}
+        anchorOrigin={{ vertical: 'bottom', horizontal: 'right' }}
+        transformOrigin={{ vertical: 'top', horizontal: 'right' }}
       >
-        <Icon fontSize='small' {...iconProps} />
-      </IconButton>
-    </Tooltip>
+        {SCALES.map((option) => (
+          <MenuItem
+            key={option}
+            selected={option === scale}
+            onClick={() => selectScale(option)}
+          >
+            <ListItemText>
+              {option === 'max' ? _labels.scaleMax : _labels.scaleTotal}
+            </ListItemText>
+          </MenuItem>
+        ))}
+      </Menu>
+    </Box>
   )
 }
+
+const SCALES: readonly RelativeScale[] = ['max', 'total']
+
+function writeScale(id: string, scale: RelativeScale, initialEnabled: boolean) {
+  getWidgetStore(id).setState((s) => ({
+    transformStates: {
+      ...s.transformStates,
+      [DATA_DESCRIPTOR.id]: {
+        // `useSingleTransform` seeds `enabled` itself; this fallback only
+        // keeps the slot well-typed if the scale lands first.
+        enabled: initialEnabled,
+        ...s.transformStates[DATA_DESCRIPTOR.id],
+        scale,
+      },
+    },
+  }))
+}

package/src/widgets-v2/actions/relative-data/scale.ts

@@ -0,0 +1,48 @@
+import type { WidgetState } from '../../stores/types'
+
+/**
+ * How far a bar reaches while `RelativeData` is on. The value is always
+ * the share of the series total; the scale only moves the end of the
+ * value axis: `'max'` ends it at the largest share so the top item fills
+ * the bar, `'total'` ends it at 100%.
+ */
+export type RelativeScale = 'max' | 'total'
+
+export const RELATIVE_DATA_ID = 'relative-data'
+
+/**
+ * The scale the value axis should use right now, or `null` when relative
+ * values are off. For widgets that size bars themselves (Category); the
+ * ECharts widgets get it through the config transform below.
+ */
+export function selectRelativeScale(s: WidgetState): RelativeScale | null {
+  const slot = s.transformStates[RELATIVE_DATA_ID]
+  if (slot?.enabled !== true) return null
+  return (slot.scale as RelativeScale | undefined) ?? 'max'
+}
+
+/**
+ * Config transform for `'total'`: pins the value axis to ±100. The widget
+ * mergers read numeric `yAxis.min` / `yAxis.max` back through
+ * {@link fixedAxisBounds} and apply each only on the side the data reaches.
+ */
+export const toRelativeTotalAxis = (option: unknown): unknown => {
+  if (option == null || typeof option !== 'object') return option
+  const cfg = option as Record<string, unknown>
+  const yAxis = cfg.yAxis
+  if (yAxis == null || typeof yAxis !== 'object' || Array.isArray(yAxis))
+    return option
+  return { ...cfg, yAxis: { ...yAxis, min: -100, max: 100 } }
+}
+
+/** Numeric bounds a config transform set on the structural `yAxis`. */
+export function fixedAxisBounds(yAxis: object): {
+  min?: number
+  max?: number
+} {
+  const { min, max } = yAxis as { min?: unknown; max?: unknown }
+  return {
+    min: typeof min === 'number' ? min : undefined,
+    max: typeof max === 'number' ? max : undefined,
+  }
+}

package/src/widgets-v2/actions/relative-data/style.ts

@@ -1,6 +1,10 @@
 import type { SxProps, Theme } from '@mui/material'
 
 export const styles = {
+  group: {
+    display: 'inline-flex',
+    alignItems: 'center',
+  },
   toggle: {
     p: 0.5,
     '& .MuiSvgIcon-root': { fontSize: 20 },
@@ -8,4 +12,10 @@ export const styles = {
   toggleActive: {
     background: (theme: Theme) => theme.palette.primary.relatedLight,
   },
+  arrow: {
+    p: 0,
+    width: 16,
+    borderRadius: 0.5,
+    '& .MuiSvgIcon-root': { fontSize: 18 },
+  },
 } satisfies Record<string, SxProps<Theme>>

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'
 
@@ -236,6 +237,22 @@ describe('createBarOptionFactory', () => {
     expect(out.yAxis.axisLabel.formatter(0)).toBe('')
   })
 
+  it("pins the axis ends a config transform set (RelativeData 'total')", () => {
+    const merge = createBarOptionFactory({ theme })
+    const out = merge({ yAxis: { type: 'value', min: -100, max: 100 } }, [
+      [{ name: 'A', value: 57 }],
+    ]) as {
+      yAxis: {
+        min: (extent: { min: number }) => number
+        max: (extent: { min: number; max: number }) => number
+      }
+    }
+    expect(out.yAxis.max({ min: 0, max: 57 })).toBe(100)
+    // The data never goes below zero, so the -100 end does not apply.
+    expect(out.yAxis.min({ min: 0 })).toBe(0)
+    expect(out.yAxis.min({ min: -20 })).toBe(-100)
+  })
+
   it('rounds the ECharts-supplied (stacked) extent so stacked bars cannot overflow', () => {
     // Regression: previously the merge phase precomputed the y-axis max from
     // the largest *single* series value, so stacking (StackToggle →
@@ -359,3 +376,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'),
+    )
+  })
+})