@carto/ps-react-ui 6.3.0 → 6.5.0

package/src/widgets/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/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/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/bar/options.test.ts

@@ -237,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 →

package/src/widgets/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 { spacingPx } from '../utils/spacing-px'
 import { createItemColorResolver } from '../utils/item-color'
 import { positionDataZoomForLegend } from '../utils/data-zoom-layout'
 import type {
@@ -20,6 +21,7 @@ import type {
   BarOptionsInput,
   BarWidgetData,
 } from './types'
+import { fixedAxisBounds } from '../actions/relative-data/scale'
 
 /**
  * Builds the **structural** ECharts option for a bar widget — axes, grid,
@@ -49,9 +51,9 @@ export function barOptions({
 
   return {
     grid: {
-      left: parseInt(theme.spacing(1)),
-      top: parseInt(theme.spacing(3)),
-      right: parseInt(theme.spacing(1)),
+      left: spacingPx(theme, 1),
+      top: spacingPx(theme, 3),
+      right: spacingPx(theme, 1),
       // Default: no legend. Merger bumps this when there are >1 series.
       ...buildGridConfig(false, theme),
       containLabel: true,
@@ -60,7 +62,7 @@ export function barOptions({
       trigger: 'axis',
       backgroundColor: theme.palette.grey[900],
       borderWidth: 0,
-      padding: [parseInt(theme.spacing(1)), parseInt(theme.spacing(1))],
+      padding: [spacingPx(theme, 1), spacingPx(theme, 1)],
       textStyle: {
         color: theme.palette.common.white,
         fontSize: 11,
@@ -89,7 +91,7 @@ export function barOptions({
       axisTick: { show: false },
       axisLabel: {
         ...buildAxisLabelStyle(theme),
-        padding: [parseInt(theme.spacing(0.5)), 0, 0, 0],
+        padding: [spacingPx(theme, 0.5), 0, 0, 0],
         margin: 0,
         // `interval: 0` makes every category label a candidate so `hideOverlap`
         // can pack the maximum number that physically fit; the category-axis
@@ -119,7 +121,7 @@ export function barOptions({
       },
       axisLabel: {
         ...buildAxisLabelStyle(theme),
-        margin: parseInt(theme.spacing(1)),
+        margin: spacingPx(theme, 1),
         show: true,
         showMaxLabel: true,
         showMinLabel: true,
@@ -202,6 +204,7 @@ export function createBarOptionFactory(
       typeof option.yAxis === 'object' && !Array.isArray(option.yAxis)
         ? option.yAxis
         : {}
+    const fixedY = fixedAxisBounds(baseYAxis)
 
     const seriesTemplates = Array.isArray(option.series) ? option.series : []
     const broadcastTemplate = seriesTemplates[0] ?? {}
@@ -300,12 +303,14 @@ export function createBarOptionFactory(
       ...(dataZoomLayout ? { dataZoom: dataZoomLayout } : {}),
       yAxis: {
         ...baseYAxis,
+        // A config transform (RelativeData's `'total'` scale) may pin the
+        // ends; each applies only on the side the data reaches.
         min: (extent: { min: number }) => {
-          niceMin = extent.min < 0 ? niceNum(extent.min) : 0
+          niceMin = extent.min < 0 ? (fixedY.min ?? niceNum(extent.min)) : 0
           return niceMin
         },
         max: (extent: { min: number; max: number }) => {
-          niceMax = extent.max <= 0 ? 1 : niceNum(extent.max)
+          niceMax = extent.max <= 0 ? 1 : (fixedY.max ?? niceNum(extent.max))
           return niceMax
         },
         axisLabel: {

package/src/widgets/category/category.relative-data.test.tsx

@@ -1,11 +1,7 @@
 import { describe, it, expect, beforeEach, afterEach } from 'vitest'
 import { fireEvent, render, screen } from '@testing-library/react'
 import { Provider } from '../provider/widget-provider'
-import {
-  clearAllWidgetStores,
-  useTransformEnabled,
-  useWidgetId,
-} from '../stores'
+import { clearAllWidgetStores, getWidgetStore } from '../stores'
 import { Category } from './category'
 import { RelativeData } from '../actions/relative-data/relative-data'
 import type { CategoryWidgetData } from './types'
@@ -13,21 +9,7 @@ import type { CategoryWidgetData } from './types'
 beforeEach(() => clearAllWidgetStores())
 afterEach(() => clearAllWidgetStores())
 
-// Replicates `CategoryActionWiring` from the storybook composer
-// (apps/storybook/stories/modules/widgets/category/category.tsx). The
-// composer-level wiring isn't testable in `apps/storybook` (no vitest
-// infra), so we re-implement just the relative-data branch here and
-// assert the bar-width math end-to-end through Provider → action →
-// bridge → UI.
-function Wired({ maxOverride }: { maxOverride?: number }) {
-  const id = useWidgetId()
-  const relativeDataActive = useTransformEnabled(id, 'relative-data')
-  const effectiveMaxOverride = relativeDataActive ? 100 : maxOverride
-  return <Category maxOverride={effectiveMaxOverride} />
-}
-
-// Single-series dataset where the max value is 1000 so percent values
-// map to round numbers we can match exactly against bar widths.
+// Single series: shares of the 1750 total are ≈57.14 / 28.57 / 14.29.
 const DATA: CategoryWidgetData = [
   [
     { name: 'A', value: 1000 },
@@ -36,72 +18,78 @@ const DATA: CategoryWidgetData = [
   ],
 ]
 
-function getBarFills(): HTMLElement[] {
+function widths(): number[] {
   return Array.from(
     document.querySelectorAll<HTMLElement>('[data-bar-fill="true"]'),
-  )
+  ).map((el) => parseFloat(el.style.width))
 }
 
-describe('Category + RelativeData composer wiring', () => {
-  it('default (RelativeData off) → bars scale to data max', () => {
+const toggle = () =>
+  fireEvent.click(screen.getByRole('button', { name: /show relative values/i }))
+
+describe('Category + RelativeData', () => {
+  it('off → bars scale to the data max', () => {
     render(
       <Provider id='cat-rd-off' data={DATA}>
         <RelativeData />
-        <Wired />
+        <Category />
       </Provider>,
     )
-    const fills = getBarFills()
-    expect(fills).toHaveLength(3)
-    // 1000/1000, 500/1000, 250/1000
-    expect(fills[0]!.style.width).toBe('100%')
-    expect(fills[1]!.style.width).toBe('50%')
-    expect(fills[2]!.style.width).toBe('25%')
+    expect(widths()).toEqual([100, 50, 25])
   })
 
-  it('clicking the % action flips bars to a 100-denominator', () => {
+  it("scale 'max' (default): values are shares of the total, the top bar fills", () => {
     render(
-      <Provider id='cat-rd-toggle' data={DATA}>
+      <Provider id='cat-rd-max' data={DATA}>
         <RelativeData />
-        <Wired />
+        <Category />
+      </Provider>,
+    )
+    toggle()
+    const values = (
+      getWidgetStore('cat-rd-max').getState().data as CategoryWidgetData
+    )[0]!.map((d) => d.value)
+    expect(values[0]).toBeCloseTo(57.14, 2)
+    const [a, b, c] = widths()
+    expect(a).toBeCloseTo(100)
+    expect(b).toBeCloseTo(50)
+    expect(c).toBeCloseTo(25)
+  })
+
+  it("scale 'total': bars end at 100%", () => {
+    render(
+      <Provider id='cat-rd-total' data={DATA}>
+        <RelativeData scale='total' />
+        <Category />
       </Provider>,
     )
-    // Toggle ON. RelativeData rewrites data values into percentages
-    // (A=1000/1750 ≈ 57.14, B=500/1750 ≈ 28.57, C=250/1750 ≈ 14.29) AND
-    // the composer wiring forces maxOverride=100 so the bar widths
-    // match those percent values directly.
-    fireEvent.click(screen.getByRole('button', { name: /relative|percent/i }))
-    const fills = getBarFills()
-    expect(fills).toHaveLength(3)
-    // Allow a small rounding tolerance — the percent transform produces
-    // floats, the bar math multiplies by 100 again.
-    const a = parseFloat(fills[0]!.style.width)
-    const b = parseFloat(fills[1]!.style.width)
-    const c = parseFloat(fills[2]!.style.width)
-    expect(a).toBeGreaterThan(55)
-    expect(a).toBeLessThan(60)
-    expect(b).toBeGreaterThan(27)
-    expect(b).toBeLessThan(30)
-    expect(c).toBeGreaterThan(13)
-    expect(c).toBeLessThan(16)
-    // The largest bar must be NOT 100% — that's the whole point of the
-    // fix. Without the wiring, A would have been 100% (largest of the
-    // percent series).
-    expect(a).toBeLessThan(100)
+    toggle()
+    const [a, b, c] = widths()
+    expect(a).toBeCloseTo(57.14, 1)
+    expect(b).toBeCloseTo(28.57, 1)
+    expect(c).toBeCloseTo(14.29, 1)
+  })
+
+  it('ignores maxOverride while relative is on (legacy ±100 wiring)', () => {
+    render(
+      <Provider id='cat-rd-legacy' data={DATA}>
+        <RelativeData initialEnabled />
+        <Category maxOverride={100} minOverride={-100} />
+      </Provider>,
+    )
+    expect(widths()[0]).toBeCloseTo(100)
   })
 
   it('toggling off again restores data-max scaling', () => {
     render(
       <Provider id='cat-rd-restore' data={DATA}>
-        <RelativeData />
-        <Wired />
+        <RelativeData scale='total' />
+        <Category />
       </Provider>,
     )
-    const button = screen.getByRole('button', { name: /relative|percent/i })
+    const button = screen.getByRole('button', { name: /show relative values/i })
     fireEvent.click(button) // on
     fireEvent.click(button) // off
-    const fills = getBarFills()
-    expect(fills[0]!.style.width).toBe('100%')
-    expect(fills[1]!.style.width).toBe('50%')
-    expect(fills[2]!.style.width).toBe('25%')
+    expect(widths()).toEqual([100, 50, 25])
   })
 })

package/src/widgets/category/category.tsx

@@ -6,6 +6,7 @@ import {
   useWidgetShallow,
   type WidgetState,
 } from '../stores'
+import { selectRelativeScale } from '../actions/relative-data/scale'
 import { CategoryUI } from './category-ui'
 import { categorySeriesKey, NO_HIDDEN_SERIES } from './helpers'
 import type {
@@ -86,7 +87,8 @@ export interface CategoryProps {
    * stay coherent across data transforms (e.g., the Searcher filtering
    * rows in and out — bars don't rescale just because the larger rows
    * got hidden). Pass an explicit number to fix the denominator
-   * regardless of the data.
+   * regardless of the data. Ignored while `RelativeData` is on, whose
+   * `scale` decides the denominator instead.
    */
   maxOverride?: number
   /**
@@ -133,18 +135,30 @@ export function Category({
   // 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],
-  )
+  // when the data reaches past zero on that side, so 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`.
+  // With RelativeData on, the values are percentages: `'total'` ends the
+  // scale at ±100, `'max'` at the largest share so the top row fills.
+  const relativeScale = useWidget(id, selectRelativeScale)
+  const [naturalMin, naturalMax] = useMemo(() => {
+    const [min, max] = extentFromCategoryData(slice.rawData)
+    if (relativeScale === 'total')
+      return [min < 0 ? -100 : 0, max > 0 ? 100 : 0]
+    if (relativeScale === 'max') return extentFromCategoryData(slice.data)
+    return [min, max]
+  }, [slice.rawData, slice.data, relativeScale])
+  // The overrides are in absolute units, so they sit out while relative
+  // values are on.
   const effectiveMaxOverride =
-    naturalMax > 0 ? (maxOverride ?? naturalMax) : undefined
+    naturalMax > 0
+      ? ((relativeScale ? undefined : maxOverride) ?? naturalMax)
+      : undefined
   const effectiveMinOverride =
-    naturalMin < 0 ? (minOverride ?? naturalMin) : undefined
+    naturalMin < 0
+      ? ((relativeScale ? undefined : minOverride) ?? naturalMin)
+      : undefined
 
   const seriesKey = categorySeriesKey(series)
   const stored = useWidget<