@carto/ps-react-ui 6.2.0 → 6.4.0

package/src/widgets/actions/fullscreen/fullscreen-store.test.tsx

@@ -130,26 +130,90 @@ describe('<FullScreen.Slot> — the dialog runs on its own store', () => {
   // Legend / dataZoom / brush live in the chart instance, not the store.
   // The Slot moves them through the instance registry, so Widget.Echart
   // doesn't need to know about fullscreen.
+  const fakeChart = (option: object, brushAreas?: unknown[]) =>
+    ({
+      getOption: vi.fn(() => option),
+      setOption: vi.fn(),
+      dispatchAction: vi.fn(),
+      getModel: () => ({
+        getComponent: (type: string) =>
+          type === 'brush' ? { areas: brushAreas } : undefined,
+      }),
+      isDisposed: () => false,
+    }) as unknown as ECharts & {
+      setOption: ReturnType<typeof vi.fn>
+      dispatchAction: ReturnType<typeof vi.fn>
+    }
+
   it('starts the dialog chart from the card chart and hands it back on close', async () => {
-    const fakeChart = (option: object) =>
-      ({
-        getOption: vi.fn(() => option),
-        setOption: vi.fn(),
-        dispatchAction: vi.fn(),
-        isDisposed: () => false,
-      }) as unknown as ECharts & {
-        setOption: ReturnType<typeof vi.fn>
-      }
-    const card = fakeChart({ from: 'card' })
-    const dialog = fakeChart({ from: 'dialog' })
+    const cardOption = {
+      series: [{ type: 'bar' }],
+      xAxis: [{ type: 'category' }],
+      legend: [{ selected: { a: true, b: false } }],
+      dataZoom: [{ start: 10, end: 60 }],
+    }
+    const card = fakeChart(cardOption)
+    const dialog = fakeChart({
+      legend: [{ selected: { a: false, b: true } }],
+      dataZoom: [{ start: 20, end: 80 }],
+    })
+    render(<Widget />)
+    act(() => setEchartInstance('w', card))
+
+    // The empty dialog chart takes the whole option, so the view state has
+    // the card's axes and series to land on.
+    fireEvent.click(screen.getByLabelText('OpenT'))
+    act(() => setEchartInstance(dialogId, dialog))
+    expect(dialog.setOption).toHaveBeenCalledWith(cardOption)
+
+    await close()
+    expect(card.setOption).toHaveBeenCalledWith({
+      legend: [{ selected: { a: false, b: true } }],
+      dataZoom: [{ start: 20, end: 80 }],
+    })
+  })
+
+  // The dialog often renders with its own styling (bigger axis labels,
+  // value labels on the series). Copying the whole option back would leave
+  // that styling on the card after closing.
+  it('hands back only the view state, not the dialog styling', async () => {
+    const card = fakeChart({ series: [{ type: 'bar' }] })
+    const dialog = fakeChart({
+      series: [{ type: 'bar', label: { show: true, rotate: 90 } }],
+      xAxis: [{ axisLabel: { fontSize: 13 } }],
+      dataZoom: [{ start: 0, end: 50, startValue: 3, endValue: 9 }],
+    })
+    render(<Widget />)
+    act(() => setEchartInstance('w', card))
+    fireEvent.click(screen.getByLabelText('OpenT'))
+    act(() => setEchartInstance(dialogId, dialog))
+
+    await close()
+    expect(card.setOption).toHaveBeenCalledWith({
+      dataZoom: [{ start: 0, end: 50, startValue: 3, endValue: 9 }],
+    })
+  })
+
+  // Brush areas aren't in getOption(); they travel through the brush action.
+  it('starts the dialog chart with the card brush areas and hands them back on close', async () => {
+    const cardAreas = [{ brushType: 'lineX', coordRange: [1, 3] }]
+    const dialogAreas = [{ brushType: 'lineX', coordRange: [4, 7] }]
+    const card = fakeChart({}, cardAreas)
+    const dialog = fakeChart({}, dialogAreas)
     render(<Widget />)
     act(() => setEchartInstance('w', card))
 
     fireEvent.click(screen.getByLabelText('OpenT'))
     act(() => setEchartInstance(dialogId, dialog))
-    expect(dialog.setOption).toHaveBeenCalledWith({ from: 'card' })
+    expect(dialog.dispatchAction).toHaveBeenCalledWith({
+      type: 'brush',
+      areas: cardAreas,
+    })
 
     await close()
-    expect(card.setOption).toHaveBeenCalledWith({ from: 'dialog' })
+    expect(card.dispatchAction).toHaveBeenCalledWith({
+      type: 'brush',
+      areas: dialogAreas,
+    })
   })
 })

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

@@ -312,15 +312,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])
@@ -340,10 +342,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' })
@@ -363,6 +370,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/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/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/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/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/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>>