@carto/ps-react-ui 4.7.0 → 4.8.0

package/src/widgets-v2/actions/lock-selection/lock-selection.test.tsx

@@ -0,0 +1,187 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+import { fireEvent, render, screen } from '@testing-library/react'
+import { Provider } from '../../provider/widget-provider'
+import { clearAllWidgetStores, getWidgetStore } from '../../stores'
+import { LockSelection } from './lock-selection'
+import { filterByLockedItems } from './transforms'
+
+beforeEach(() => clearAllWidgetStores())
+afterEach(() => clearAllWidgetStores())
+
+const DATA = [
+  [
+    { name: 'A', value: 10 },
+    { name: 'B', value: 20 },
+    { name: 'C', value: 30 },
+  ],
+]
+
+describe('<LockSelection>', () => {
+  it('disables the trigger when nothing is selected and nothing is locked', () => {
+    render(
+      <Provider id='ls1' data={DATA}>
+        <LockSelection
+          selection={[]}
+          lockedItems={[]}
+          onLockChange={() => undefined}
+          labels={{ disabled: 'Pick rows' }}
+        />
+      </Provider>,
+    )
+    const btn = screen.getByRole('button', { name: 'Pick rows' })
+    expect(btn.getAttribute('disabled')).not.toBeNull()
+  })
+
+  it('shows the lock label when selection is non-empty and not locked', () => {
+    render(
+      <Provider id='ls2' data={DATA}>
+        <LockSelection
+          selection={['A']}
+          lockedItems={[]}
+          onLockChange={() => undefined}
+          labels={{ lock: 'Lock these' }}
+        />
+      </Provider>,
+    )
+    const btn = screen.getByRole('button', { name: 'Lock these' })
+    expect(btn.getAttribute('aria-pressed')).toBe('false')
+    expect(btn.getAttribute('disabled')).toBeNull()
+  })
+
+  it('shows the unlock label when locked and aria-pressed=true', () => {
+    render(
+      <Provider id='ls3' data={DATA}>
+        <LockSelection
+          selection={['A']}
+          lockedItems={['A']}
+          onLockChange={() => undefined}
+          labels={{ unlock: 'Release' }}
+        />
+      </Provider>,
+    )
+    const btn = screen.getByRole('button', { name: 'Release' })
+    expect(btn.getAttribute('aria-pressed')).toBe('true')
+  })
+
+  it('snapshots selection on lock — onLockChange called with current selection', () => {
+    const onLockChange = vi.fn()
+    render(
+      <Provider id='ls4' data={DATA}>
+        <LockSelection
+          selection={['A', 'B']}
+          lockedItems={[]}
+          onLockChange={onLockChange}
+          labels={{ lock: 'Lock' }}
+        />
+      </Provider>,
+    )
+    fireEvent.click(screen.getByRole('button', { name: 'Lock' }))
+    expect(onLockChange).toHaveBeenCalledTimes(1)
+    expect(onLockChange).toHaveBeenCalledWith(['A', 'B'])
+  })
+
+  it('clears the lock — onLockChange called with empty array', () => {
+    const onLockChange = vi.fn()
+    render(
+      <Provider id='ls5' data={DATA}>
+        <LockSelection
+          selection={['A']}
+          lockedItems={['A', 'B']}
+          onLockChange={onLockChange}
+          labels={{ unlock: 'Unlock' }}
+        />
+      </Provider>,
+    )
+    fireEvent.click(screen.getByRole('button', { name: 'Unlock' }))
+    expect(onLockChange).toHaveBeenCalledWith([])
+  })
+
+  it('registers a data transform that filters when locked, restores when unlocked', () => {
+    const { rerender } = render(
+      <Provider id='ls6' data={DATA}>
+        <LockSelection
+          selection={['A']}
+          lockedItems={['A']}
+          onLockChange={() => undefined}
+        />
+      </Provider>,
+    )
+    const locked = getWidgetStore('ls6').getState().data as unknown[][]
+    expect(locked).toEqual([[{ name: 'A', value: 10 }]])
+
+    rerender(
+      <Provider id='ls6' data={DATA}>
+        <LockSelection
+          selection={['A']}
+          lockedItems={[]}
+          onLockChange={() => undefined}
+        />
+      </Provider>,
+    )
+    const unlocked = getWidgetStore('ls6').getState().data as unknown[][]
+    // With no lockedItems and the transform disabled, the pipeline returns
+    // raw data. All three rows should be present.
+    expect(unlocked.flat().length).toBe(3)
+  })
+
+  it('lets the destination feed a different lockedItems set later', () => {
+    const { rerender } = render(
+      <Provider id='ls7' data={DATA}>
+        <LockSelection
+          selection={['A']}
+          lockedItems={['A']}
+          onLockChange={() => undefined}
+        />
+      </Provider>,
+    )
+    expect(
+      (getWidgetStore('ls7').getState().data as unknown[][]).flat(),
+    ).toEqual([{ name: 'A', value: 10 }])
+
+    rerender(
+      <Provider id='ls7' data={DATA}>
+        <LockSelection
+          selection={['A', 'B', 'C']}
+          lockedItems={['B', 'C']}
+          onLockChange={() => undefined}
+        />
+      </Provider>,
+    )
+    expect(
+      (getWidgetStore('ls7').getState().data as unknown[][]).flat(),
+    ).toEqual([
+      { name: 'B', value: 20 },
+      { name: 'C', value: 30 },
+    ])
+  })
+})
+
+describe('filterByLockedItems', () => {
+  it('returns input unchanged when locked set is empty', () => {
+    expect(filterByLockedItems(DATA, [])).toBe(DATA)
+  })
+
+  it('keeps only items whose name is in the locked set, preserving series shape', () => {
+    const out = filterByLockedItems(DATA, ['A', 'C']) as unknown[][]
+    expect(out).toEqual([
+      [
+        { name: 'A', value: 10 },
+        { name: 'C', value: 30 },
+      ],
+    ])
+  })
+
+  it('handles numeric names', () => {
+    const data = [
+      [
+        { name: 1, value: 10 },
+        { name: 2, value: 20 },
+      ],
+    ]
+    expect(filterByLockedItems(data, [2])).toEqual([[{ name: 2, value: 20 }]])
+  })
+
+  it('returns input unchanged when input is not array-shaped', () => {
+    expect(filterByLockedItems('nope', ['A'])).toBe('nope')
+  })
+})

package/src/widgets-v2/actions/lock-selection/lock-selection.tsx

@@ -0,0 +1,130 @@
+import { useCallback, useEffect, useMemo, type ComponentType } from 'react'
+import { IconButton, type SvgIconProps } from '@mui/material'
+import LockIcon from '@mui/icons-material/Lock'
+import LockOpenIcon from '@mui/icons-material/LockOpen'
+import { Tooltip } from '../../../components'
+import { useTransform, useWidgetId } from '../../stores'
+import type { TransformPair } from '../../stores'
+import { filterByLockedItems } from './transforms'
+import {
+  DEFAULT_LOCK_SELECTION_LABELS,
+  type LockSelectionLabels,
+} from './labels'
+import { styles } from './style'
+
+const LOCK_SELECTION_DESCRIPTOR = {
+  id: 'lock-selection',
+  type: 'data' as const,
+  order: 30,
+}
+
+export type LockSelectionKey = string | number
+
+export interface LockSelectionProps {
+  /**
+   * Currently-selected items (destination-owned). On lock, this set is
+   * snapshotted into `lockedItems` via `onLockChange`.
+   */
+  selection: readonly LockSelectionKey[]
+  /**
+   * Currently-locked items (destination-owned). When non-empty, the widget's
+   * data is filtered to these items via the registered transform.
+   */
+  lockedItems: readonly LockSelectionKey[]
+  /**
+   * Fires when the user toggles the lock. The destination is responsible for
+   * persisting the new locked set (and re-feeding it via `lockedItems`).
+   */
+  onLockChange: (next: readonly LockSelectionKey[]) => void
+  labels?: Partial<LockSelectionLabels>
+  /** Lock icon (default: `LockIcon`). */
+  lockIcon?: ComponentType<SvgIconProps>
+  /** Unlock icon (default: `LockOpenIcon`). */
+  unlockIcon?: ComponentType<SvgIconProps>
+  iconProps?: SvgIconProps
+}
+
+/**
+ * Action that pins the current selection so the widget's data filters down
+ * to those items even as the user changes selections. Selection and lock
+ * state are destination-owned; this component is a controlled UI + a data
+ * transform registered against the widget's pipeline.
+ *
+ * The trigger is disabled when there is nothing to lock and nothing locked.
+ */
+export function LockSelection({
+  selection,
+  lockedItems,
+  onLockChange,
+  labels,
+  lockIcon: LockSvg = LockIcon,
+  unlockIcon: UnlockSvg = LockOpenIcon,
+  iconProps,
+}: LockSelectionProps) {
+  const id = useWidgetId()
+  const _labels = { ...DEFAULT_LOCK_SELECTION_LABELS, ...labels }
+  const isLocked = lockedItems.length > 0
+  const canToggle = isLocked || selection.length > 0
+
+  // Pair memoized on lockedItems identity — useTransform re-registers the fn
+  // (which closes over the current locked set) whenever the destination feeds
+  // a new array. setEnabled drives the middleware-level `enabled` flag.
+  const pairs = useMemoPair(lockedItems)
+  const { enabled, setEnabled } = useTransform(id, pairs, {
+    initialEnabled: isLocked,
+  })
+
+  // Keep middleware `enabled` in sync with destination-owned `isLocked`. The
+  // pipeline only short-circuits the transform when enabled === false, so
+  // toggling here is what makes lock/unlock actually take effect.
+  useEffect(() => {
+    if (enabled !== isLocked) setEnabled(isLocked)
+  }, [enabled, isLocked, setEnabled])
+
+  const handleToggle = useCallback(() => {
+    if (isLocked) {
+      onLockChange([])
+    } else {
+      onLockChange([...selection])
+    }
+  }, [isLocked, onLockChange, selection])
+
+  const tooltip = !canToggle
+    ? _labels.disabled
+    : isLocked
+      ? _labels.unlock
+      : _labels.lock
+  const Icon = isLocked ? UnlockSvg : LockSvg
+
+  return (
+    <Tooltip title={tooltip}>
+      <span>
+        <IconButton
+          size='small'
+          aria-label={tooltip}
+          aria-pressed={isLocked}
+          disabled={!canToggle}
+          onClick={handleToggle}
+          sx={{ ...styles.toggle, ...(isLocked && styles.toggleActive) }}
+        >
+          <Icon fontSize='small' {...iconProps} />
+        </IconButton>
+      </span>
+    </Tooltip>
+  )
+}
+
+/**
+ * Builds a stable `[{ descriptor, fn }]` pair where `fn` closes over the
+ * latest `lockedItems`. Re-memoized whenever the array identity changes so
+ * `useTransform` re-registers the closure with the freshest data.
+ */
+function useMemoPair(
+  lockedItems: readonly LockSelectionKey[],
+): readonly TransformPair[] {
+  const fn = useCallback(
+    (data: unknown) => filterByLockedItems(data, lockedItems),
+    [lockedItems],
+  )
+  return useMemo(() => [{ descriptor: LOCK_SELECTION_DESCRIPTOR, fn }], [fn])
+}

package/src/widgets-v2/actions/lock-selection/style.ts

@@ -0,0 +1,11 @@
+import type { SxProps, Theme } from '@mui/material'
+
+export const styles = {
+  toggle: {
+    p: 0.5,
+    '& .MuiSvgIcon-root': { fontSize: 20 },
+  },
+  toggleActive: {
+    background: (theme: Theme) => theme.palette.primary.relatedLight,
+  },
+} satisfies Record<string, SxProps<Theme>>

package/src/widgets-v2/actions/lock-selection/transforms.ts

@@ -0,0 +1,27 @@
+/**
+ * Filters a 2D series of `{name, ...}` records, keeping only items whose
+ * `name` is in the locked set. Multi-series shape is preserved (one inner
+ * array per series). Used by the LockSelection action's data transform.
+ */
+export function filterByLockedItems(
+  input: unknown,
+  lockedItems: readonly (string | number)[],
+): unknown {
+  if (lockedItems.length === 0) return input
+  if (!Array.isArray(input)) return input
+  const set = new Set<string | number>(lockedItems)
+  return input.map((series: unknown): unknown => {
+    if (!Array.isArray(series)) return series
+    return series.filter((item: unknown) => {
+      if (item == null) return false
+      if (typeof item === 'object' && 'name' in item) {
+        const name = (item as { name: unknown }).name
+        if (typeof name === 'string' || typeof name === 'number') {
+          return set.has(name)
+        }
+        return false
+      }
+      return false
+    })
+  })
+}

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

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

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

@@ -0,0 +1,9 @@
+export interface RelativeDataLabels {
+  on: string
+  off: string
+}
+
+export const DEFAULT_RELATIVE_DATA_LABELS: RelativeDataLabels = {
+  on: 'Show absolute values',
+  off: 'Show relative values',
+}

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

@@ -0,0 +1,71 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { render } from '@testing-library/react'
+import { Provider } from '../../provider/widget-provider'
+import { clearAllWidgetStores, getWidgetStore } from '../../stores'
+import { RelativeData } from './relative-data'
+
+beforeEach(() => clearAllWidgetStores())
+afterEach(() => clearAllWidgetStores())
+
+const fmtA = (n: number) => `A${n}`
+const fmtB = (n: number) => `B${n}`
+
+describe('<RelativeData> — rawFormatter-driven restoration', () => {
+  it('Provider mirrors the formatter prop into both rawFormatter and formatter', () => {
+    render(
+      <Provider id='rd1' data={[]} formatter={fmtA}>
+        <RelativeData initialEnabled={false} />
+      </Provider>,
+    )
+    const s = getWidgetStore('rd1').getState()
+    expect(s.rawFormatter).toBe(fmtA)
+    expect(s.formatter).toBe(fmtA)
+  })
+
+  it('initialEnabled=true installs the percent formatter and leaves rawFormatter untouched', () => {
+    render(
+      <Provider id='rd2' data={[]} formatter={fmtA}>
+        <RelativeData initialEnabled={true} />
+      </Provider>,
+    )
+    const s = getWidgetStore('rd2').getState()
+    expect(s.rawFormatter).toBe(fmtA)
+    expect(typeof s.formatter).toBe('function')
+    expect(s.formatter).not.toBe(fmtA)
+    // Sanity: the override is the percent formatter (50 → "50%" via Intl).
+    expect(s.formatter?.(50)).toMatch(/%$/)
+  })
+
+  it('consumer prop change while enabled updates rawFormatter; effect re-applies percent', () => {
+    const { rerender } = render(
+      <Provider id='rd3' data={[]} formatter={fmtA}>
+        <RelativeData initialEnabled={true} />
+      </Provider>,
+    )
+    const store = getWidgetStore('rd3')
+    expect(store.getState().rawFormatter).toBe(fmtA)
+    const beforePercent = store.getState().formatter
+
+    rerender(
+      <Provider id='rd3' data={[]} formatter={fmtB}>
+        <RelativeData initialEnabled={true} />
+      </Provider>,
+    )
+    const after = store.getState()
+    expect(after.rawFormatter).toBe(fmtB)
+    // Formatter is still the percent formatter (re-applied via the effect).
+    expect(after.formatter).not.toBe(fmtB)
+    expect(after.formatter).toBe(beforePercent)
+  })
+
+  it('initialEnabled=false leaves formatter equal to rawFormatter', () => {
+    render(
+      <Provider id='rd4' data={[]} formatter={fmtA}>
+        <RelativeData initialEnabled={false} />
+      </Provider>,
+    )
+    const s = getWidgetStore('rd4').getState()
+    expect(s.formatter).toBe(s.rawFormatter)
+    expect(s.formatter).toBe(fmtA)
+  })
+})

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

@@ -0,0 +1,107 @@
+import { useEffect, useMemo, type ComponentType } from 'react'
+import { IconButton, type SvgIconProps } from '@mui/material'
+import PercentIcon from '@mui/icons-material/Percent'
+import { Tooltip } from '../../../components'
+import {
+  getWidgetStore,
+  useSingleTransform,
+  useWidget,
+  useWidgetId,
+} from '../../stores'
+import { createPercentFormatter, toRelativeData } from './transforms'
+import { DEFAULT_RELATIVE_DATA_LABELS, type RelativeDataLabels } from './labels'
+import { styles } from './style'
+
+const DATA_DESCRIPTOR = {
+  id: 'relative-data',
+  type: 'data' as const,
+  order: 15,
+}
+
+export interface RelativeDataProps {
+  initialEnabled?: boolean
+  /**
+   * BCP-47 locale tag forwarded to `Intl.NumberFormat`. Defaults to the
+   * runtime locale.
+   */
+  locale?: string
+  labels?: Partial<RelativeDataLabels>
+  icon?: ComponentType<SvgIconProps>
+  iconProps?: SvgIconProps
+  /**
+   * Data-side transform that rewrites the widget's series into their
+   * relative (0–100) form. Defaults to {@link toRelativeData}, which
+   * handles the canonical `{ name, value }[]` shape (bar / pie /
+   * timeseries / category). Widgets with a different data shape pass
+   * their own — `toRelativeHistogramData` for histogram's `number[]`,
+   * `toRelativeScatterplotData` for scatter's `[x, y][]`.
+   *
+   * Should be a stable top-level reference; inline `(data) => ...`
+   * literals re-register the transform every render.
+   */
+  transform?: (data: unknown) => unknown
+}
+
+/**
+ * Toggle between absolute and relative (percentage) values.
+ *
+ *   - **Data side**: a single data transform ({@link toRelativeData}) registered
+ *     through `useSingleTransform`. When disabled, the pipeline skips it and the
+ *     derived `data` reverts to `rawData` automatically.
+ *   - **Formatter side**: an effect writes directly to `state.formatter`. When
+ *     enabled it installs the Intl-based percent formatter; when disabled it
+ *     reads `state.rawFormatter` (the consumer-supplied original, always live)
+ *     and writes it back to `formatter`. No "original" snapshot is captured —
+ *     `rawFormatter` is the original.
+ */
+export function RelativeData({
+  initialEnabled = false,
+  locale,
+  labels,
+  icon: Icon = PercentIcon,
+  iconProps,
+  transform,
+}: RelativeDataProps) {
+  const id = useWidgetId()
+  const _labels = { ...DEFAULT_RELATIVE_DATA_LABELS, ...labels }
+
+  const { enabled, toggle } = useSingleTransform(
+    id,
+    DATA_DESCRIPTOR,
+    transform ?? toRelativeData,
+    { initialEnabled },
+  )
+
+  const percentFormatter = useMemo(
+    () => createPercentFormatter(locale),
+    [locale],
+  )
+
+  // Subscribe to rawFormatter so the effect re-runs and re-applies after the
+  // consumer's formatter prop changes (Provider syncs the new prop to both
+  // rawFormatter and formatter — re-applying restores the percent override
+  // when relative is on, and tracks the new rawFormatter when off).
+  const rawFormatter = useWidget(id, (s) => s.rawFormatter)
+
+  useEffect(() => {
+    getWidgetStore(id).setState({
+      formatter: enabled ? percentFormatter : rawFormatter,
+    })
+  }, [id, enabled, percentFormatter, rawFormatter])
+
+  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) }}
+      >
+        <Icon fontSize='small' {...iconProps} />
+      </IconButton>
+    </Tooltip>
+  )
+}

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

@@ -0,0 +1,11 @@
+import type { SxProps, Theme } from '@mui/material'
+
+export const styles = {
+  toggle: {
+    p: 0.5,
+    '& .MuiSvgIcon-root': { fontSize: 20 },
+  },
+  toggleActive: {
+    background: (theme: Theme) => theme.palette.primary.relatedLight,
+  },
+} satisfies Record<string, SxProps<Theme>>