@carto/ps-react-ui 5.0.0-widgets.8 → 5.0.0

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

@@ -0,0 +1,301 @@
+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'
+import { filterTableByLockedRows } from '../../table/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('uses a custom filterFn instead of filterByLockedItems when supplied', () => {
+    const customFilter = vi.fn(
+      (data: unknown, locked: readonly (string | number)[]) =>
+        (data as unknown[][]).map((series) =>
+          series.filter((_, i) => locked.includes(i)),
+        ),
+    )
+    render(
+      <Provider id='ls8' data={DATA}>
+        <LockSelection
+          selection={[0]}
+          lockedItems={[0]}
+          onLockChange={() => undefined}
+          filterFn={customFilter}
+        />
+      </Provider>,
+    )
+    // Third argument is `filterKey`, undefined when the prop is omitted.
+    expect(customFilter).toHaveBeenCalledWith(DATA, [0], undefined)
+    const locked = getWidgetStore('ls8').getState().data as unknown[][]
+    expect(locked).toEqual([[{ name: 'A', value: 10 }]])
+  })
+
+  it('does not rebuild the registered transform when filterFn gets a fresh identity but lockedItems is unchanged', () => {
+    // Mirrors the documented usage in table/transforms.ts: an inline lambda
+    // closing over `filterFn`, a new function identity on every render.
+    // `SELECTION`/`LOCKED` are hoisted so their *reference* stays stable
+    // across renders — only `filterFn`'s identity should vary here.
+    const SELECTION = ['A']
+    const LOCKED = ['A']
+    let renderCount = 0
+    const Wrapper = () => {
+      renderCount++
+      return (
+        <LockSelection
+          selection={SELECTION}
+          lockedItems={LOCKED}
+          onLockChange={() => undefined}
+          filterFn={(data, locked) => filterByLockedItems(data, locked)}
+        />
+      )
+    }
+    const { rerender } = render(
+      <Provider id='ls9' data={DATA}>
+        <Wrapper />
+      </Provider>,
+    )
+    const firstTransforms = getWidgetStore('ls9').getState().dataTransforms
+    rerender(
+      <Provider id='ls9' data={DATA}>
+        <Wrapper />
+      </Provider>,
+    )
+    expect(renderCount).toBe(2)
+    const secondTransforms = getWidgetStore('ls9').getState().dataTransforms
+    // Same reference — `useMemoPair`'s `useCallback` only depends on
+    // `lockedItems`, so a fresh inline `filterFn` each render must not
+    // rebuild the transform pair.
+    expect(secondTransforms).toBe(firstTransforms)
+    const locked = getWidgetStore('ls9').getState().data as unknown[][]
+    expect(locked).toEqual([[{ name: 'A', value: 10 }]])
+  })
+
+  it('rebuilds the transform when filterKey changes, with a stable filterFn reference', () => {
+    // `filterFn` is passed by reference here, so `filterKey` is the only
+    // thing that varies — and it has to be enough on its own. Nothing else
+    // would tell the pipeline the key changed: `filterFn`'s identity is not
+    // a dependency, and `rawData`/`dataTransforms` are the only recompute
+    // keys, so the widget would keep the rows matched by the old key.
+    const SELECTION = ['A']
+    const LOCKED = ['A']
+    const renderWith = (keyColumn: string) => (
+      <Provider id='ls-key' data={DATA}>
+        <LockSelection
+          selection={SELECTION}
+          lockedItems={LOCKED}
+          onLockChange={() => undefined}
+          // No closure: the key travels through `filterFn`'s third argument.
+          filterFn={filterTableByLockedRows}
+          filterKey={keyColumn}
+        />
+      </Provider>
+    )
+    const { rerender } = render(renderWith('id'))
+    const first = getWidgetStore('ls-key').getState().dataTransforms
+    rerender(renderWith('code'))
+    const second = getWidgetStore('ls-key').getState().dataTransforms
+    expect(second).not.toBe(first)
+  })
+
+  it('hands filterKey to filterFn as its third argument', () => {
+    // The identity check above cannot see this: an implementation that put
+    // `filterKey` in the deps but dropped it from the call still produces a
+    // new transform. That is the exact failure the component warns about, and
+    // it has to be pinned on the value, not the reference.
+    const spy = vi.fn(() => [] as unknown[])
+    const SELECTION = ['A']
+    const LOCKED = ['A']
+    render(
+      <Provider id='ls-key-value' data={DATA}>
+        <LockSelection
+          selection={SELECTION}
+          lockedItems={LOCKED}
+          onLockChange={() => undefined}
+          filterFn={spy}
+          filterKey='code'
+        />
+      </Provider>,
+    )
+
+    expect(spy).toHaveBeenCalledWith(DATA, LOCKED, 'code')
+  })
+
+  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,188 @@
+import {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  type ComponentType,
+} from 'react'
+import { IconButton, type SvgIconProps } from '@mui/material'
+import { Lock as LockIcon } from '@mui/icons-material'
+import { LockOpen as LockOpenIcon } from '@mui/icons-material'
+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<
+  K extends LockSelectionKey = LockSelectionKey,
+> {
+  /**
+   * Currently-selected items (destination-owned). On lock, this set is
+   * snapshotted into `lockedItems` via `onLockChange`.
+   */
+  selection: readonly K[]
+  /**
+   * Currently-locked items (destination-owned). When non-empty, the widget's
+   * data is filtered to these items via the registered transform.
+   */
+  lockedItems: readonly K[]
+  /**
+   * 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 K[]) => void
+  labels?: Partial<LockSelectionLabels>
+  /** Lock icon (default: `LockIcon`). */
+  lockIcon?: ComponentType<SvgIconProps>
+  /** Unlock icon (default: `LockOpenIcon`). */
+  unlockIcon?: ComponentType<SvgIconProps>
+  iconProps?: SvgIconProps
+  /**
+   * Data transform applied while locked. Defaults to {@link filterByLockedItems}
+   * (keeps only `{name, ...}` items whose `name` is in `lockedItems`, across a
+   * `X[][]` series shape — matches Bar/Pie/Category/Timeseries data). Widgets
+   * whose data shape or selection identity differs (bin index, composite
+   * point key, flat rows) pass their own — e.g. Histogram's
+   * `filterHistogramByLockedBins`, Scatterplot's
+   * `filterScatterplotByLockedPoints`, Table's `filterTableByLockedRows`.
+   */
+  filterFn?: (
+    data: unknown,
+    lockedItems: readonly K[],
+    filterKey?: string | number,
+  ) => unknown
+  /**
+   * Configuration the filter needs beyond the locked set — Table's
+   * `keyColumn`, say. Handed to `filterFn` as its third argument, so the
+   * filter can go by reference:
+   * `filterFn={filterTableByLockedRows} filterKey={keyColumn}`.
+   *
+   * Pass it rather than capturing it: `filterFn`'s identity is not a
+   * pipeline dependency (see {@link useMemoPair}), so a fresh closure over a
+   * new key is picked up while nothing re-runs.
+   */
+  filterKey?: string | number
+}
+
+/**
+ * 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<K extends LockSelectionKey = LockSelectionKey>({
+  selection,
+  lockedItems,
+  onLockChange,
+  labels,
+  lockIcon: LockSvg = LockIcon,
+  unlockIcon: UnlockSvg = LockOpenIcon,
+  iconProps,
+  filterFn = filterByLockedItems,
+  filterKey,
+}: LockSelectionProps<K>) {
+  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, filterFn, filterKey)
+  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` and reads `filterFn` from a ref kept fresh via
+ * `useEffect` (never mutated during render — that would break the compiler's
+ * memoization guarantees). `filterFn` is deliberately NOT a `useCallback`
+ * dep: callers may pass an inline closure, which has a new identity every
+ * render, and depending on it would rebuild the transform pair (and
+ * everything downstream of it) every render instead of only when
+ * `lockedItems` actually changes. `fn` itself is invoked later by the data
+ * pipeline, not during this component's render, so reading a ref there is
+ * safe.
+ *
+ * The cost of that ref is that captured config is invisible to the pipeline,
+ * which is what {@link LockSelectionProps.filterKey} is for.
+ */
+function useMemoPair<K extends LockSelectionKey>(
+  lockedItems: readonly K[],
+  filterFn: (
+    data: unknown,
+    lockedItems: readonly K[],
+    filterKey?: string | number,
+  ) => unknown,
+  filterKey: string | number | undefined,
+): readonly TransformPair[] {
+  const filterFnRef = useRef(filterFn)
+  useEffect(() => {
+    filterFnRef.current = filterFn
+  })
+  // Forwarded, not just declared as a dependency: the React Compiler infers
+  // deps from the body and drops any it never uses (even `void filterKey`,
+  // eliminated first), so declaring it alone would change nothing.
+  const fn = useCallback(
+    (data: unknown) => filterFnRef.current(data, lockedItems, filterKey),
+    [lockedItems, filterKey],
+  )
+  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)
+  })
+})