@carto/ps-react-ui 4.7.1 → 4.9.0

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>>

package/src/widgets-v2/actions/relative-data/transforms.test.ts

@@ -0,0 +1,151 @@
+import { describe, it, expect } from 'vitest'
+import { createPercentFormatter, toRelativeData } from './transforms'
+
+describe('toRelativeData (default — named-value shape)', () => {
+  it('rewrites each datum value as its share of the series total in 0-100', () => {
+    const input = [
+      [
+        { name: 'a', value: 25 },
+        { name: 'b', value: 75 },
+      ],
+    ]
+    expect(toRelativeData(input)).toEqual([
+      [
+        { name: 'a', value: 25 },
+        { name: 'b', value: 75 },
+      ],
+    ])
+  })
+
+  it('handles non-100 totals (50/200 = 25%)', () => {
+    const input = [
+      [
+        { name: 'a', value: 50 },
+        { name: 'b', value: 150 },
+      ],
+    ]
+    expect(toRelativeData(input)).toEqual([
+      [
+        { name: 'a', value: 25 },
+        { name: 'b', value: 75 },
+      ],
+    ])
+  })
+
+  it('handles multiple series independently', () => {
+    const input = [
+      [{ name: 'x', value: 10 }],
+      [
+        { name: 'x', value: 50 },
+        { name: 'y', value: 50 },
+      ],
+    ]
+    const out = toRelativeData(input) as { value: number }[][]
+    expect(out[0]?.[0]?.value).toBe(100)
+    expect(out[1]?.[0]?.value).toBe(50)
+    expect(out[1]?.[1]?.value).toBe(50)
+  })
+
+  it('preserves extra fields on each datum', () => {
+    const input = [[{ name: 'a', value: 10, color: '#fff' }]]
+    expect(toRelativeData(input)).toEqual([
+      [{ name: 'a', value: 100, color: '#fff' }],
+    ])
+  })
+
+  it('returns the series unchanged when total is zero', () => {
+    const input = [
+      [
+        { name: 'a', value: 0 },
+        { name: 'b', value: 0 },
+      ],
+    ]
+    expect(toRelativeData(input)).toEqual(input)
+  })
+
+  it('produces signed share-of-magnitude percentages for mixed-sign series', () => {
+    const input = [
+      [
+        { name: 'a', value: 1000 },
+        { name: 'b', value: -990 },
+      ],
+    ]
+    const out = toRelativeData(input) as { value: number }[][]
+    // Denominator is 1000 + 990 = 1990, so 1000 / 1990 ≈ 50.25%
+    expect(out[0]?.[0]?.value).toBeCloseTo(50.25126, 4)
+    expect(out[0]?.[1]?.value).toBeCloseTo(-49.74874, 4)
+  })
+
+  it('works for all-negative series (signed shares sum to -100)', () => {
+    const input = [
+      [
+        { name: 'a', value: -100 },
+        { name: 'b', value: -200 },
+      ],
+    ]
+    const out = toRelativeData(input) as { value: number }[][]
+    expect(out[0]?.[0]?.value).toBeCloseTo(-33.333, 2)
+    expect(out[0]?.[1]?.value).toBeCloseTo(-66.667, 2)
+  })
+
+  it('returns the input unchanged when shape does not match named-value', () => {
+    expect(toRelativeData(null)).toBe(null)
+    expect(toRelativeData('not an array')).toBe('not an array')
+    // A top-level array whose entries are neither arrays-of-named-value
+    // nor matching the predicate falls through. Each series that isn't
+    // a named-value array is returned as-is — that's how widgets with
+    // a different shape (and their own transform) avoid double-running
+    // through this one.
+    expect(toRelativeData([42])).toEqual([42])
+    expect(toRelativeData([[1, 2, 3]])).toEqual([[1, 2, 3]])
+    expect(
+      toRelativeData([
+        [
+          [1, 10],
+          [2, 20],
+        ],
+      ]),
+    ).toEqual([
+      [
+        [1, 10],
+        [2, 20],
+      ],
+    ])
+  })
+})
+
+describe('createPercentFormatter', () => {
+  it('formats 0-100 input as percentages via Intl.NumberFormat', () => {
+    const fmt = createPercentFormatter('en-US')
+    // minimumFractionDigits: 0, maximumFractionDigits: 2 — integers render
+    // without decimals, fractions get up to two decimal places.
+    expect(fmt(50)).toBe('50%')
+    expect(fmt(2.5)).toBe('2.5%')
+    expect(fmt(100)).toBe('100%')
+    expect(fmt(12.345)).toBe('12.35%')
+  })
+
+  it('respects the provided locale (en-US uses dot, es-ES uses comma)', () => {
+    const en = createPercentFormatter('en-US')
+    const es = createPercentFormatter('es-ES')
+    expect(en(12.3)).toContain('12.3')
+    // Spanish locale uses comma as decimal separator. Format strings vary by
+    // ICU version (some emit narrow no-break space before "%"); assert on the
+    // decimal separator and the digits rather than the entire output.
+    const esOut = es(12.3)
+    expect(esOut).toContain('12,3')
+    expect(esOut).toContain('%')
+  })
+
+  it('passes through non-finite values as their string form', () => {
+    const fmt = createPercentFormatter('en-US')
+    expect(fmt(NaN)).toBe('NaN')
+    expect(fmt(Infinity)).toBe('Infinity')
+  })
+
+  it('falls back to runtime default locale when none is provided', () => {
+    const fmt = createPercentFormatter()
+    // Whatever locale the runtime uses, 50 should produce a string ending in '%'
+    expect(fmt(50)).toMatch(/%$/)
+  })
+})

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

@@ -0,0 +1,70 @@
+/**
+ * Default data-side transform for `RelativeData`: rewrite each
+ * `{ name, value }` datum's `value` to its share of the series total
+ * expressed as 0–100 (matches v1's range). The companion percent
+ * formatter divides by 100 so it can call `Intl.NumberFormat` with
+ * `style: 'percent'`.
+ *
+ * Used by widgets whose series are arrays of `{ name, value }`
+ * objects — bar, pie, timeseries, category. Widgets with a different
+ * data shape pass their own transform via
+ * `<RelativeData transform={...} />`; see `widgets-v2/histogram` and
+ * `widgets-v2/scatterplot` for in-tree examples.
+ *
+ * The denominator is the sum of |value| across the series so mixed-sign
+ * series (e.g. cashflow with inflows + outflows) produce sane signed
+ * shares-of-magnitude. A series whose total magnitude is zero (all-zero
+ * or empty input) is returned unchanged so a stalled or empty data set
+ * doesn't show misleading 0% values. Series whose shape doesn't match
+ * the named-value pattern fall through untouched.
+ */
+
+interface NamedValue {
+  name: unknown
+  value: number
+  [k: string]: unknown
+}
+
+function isNamedValueArray(v: unknown): v is NamedValue[] {
+  if (!Array.isArray(v)) return false
+  return v.every(
+    (item) =>
+      item != null &&
+      typeof item === 'object' &&
+      'value' in item &&
+      typeof (item as { value: unknown }).value === 'number',
+  )
+}
+
+export const toRelativeData = (input: unknown): unknown => {
+  if (!Array.isArray(input)) return input
+  return input.map((series: unknown): unknown => {
+    if (!isNamedValueArray(series)) return series
+    const total = series.reduce((acc, d) => acc + Math.abs(d.value), 0)
+    if (total <= 0) return series
+    return series.map((d) => ({ ...d, value: (d.value / total) * 100 }))
+  })
+}
+
+/**
+ * Build a percent formatter using `Intl.NumberFormat`. The returned function
+ * expects values in the 0–100 range (output of {@link toRelativeData}) and
+ * divides by 100 internally before calling `style: 'percent'`.
+ *
+ * Locale: passed straight to `Intl.NumberFormat`. Falls back to the runtime
+ * default when omitted.
+ */
+export function createPercentFormatter(
+  locale?: string,
+): (value: number) => string {
+  const fmt = new Intl.NumberFormat(locale, {
+    style: 'percent',
+    minimumFractionDigits: 0,
+    maximumFractionDigits: 2,
+  })
+  return (value: number) => {
+    if (typeof value !== 'number' || !Number.isFinite(value))
+      return String(value)
+    return fmt.format(value / 100)
+  }
+}

package/src/widgets-v2/actions/searcher/filter.ts

@@ -0,0 +1,28 @@
+/**
+ * Filters a 2D series of `{name, ...}` records by case-insensitive substring on
+ * the `name` field. Keeps the dataset shape (one inner array per series).
+ * Used by the Searcher action's data transform.
+ */
+export function filterBySearchText(input: unknown, search: string): unknown {
+  if (!search) return input
+  const needle = search.toLowerCase()
+  if (!Array.isArray(input)) return input
+  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 rawName = (item as { name: unknown }).name
+        const name = rawName == null ? '' : stringifyPrimitive(rawName)
+        return name.toLowerCase().includes(needle)
+      }
+      return stringifyPrimitive(item).toLowerCase().includes(needle)
+    })
+  })
+}
+
+function stringifyPrimitive(v: unknown): string {
+  if (typeof v === 'string') return v
+  if (typeof v === 'number' || typeof v === 'boolean') return String(v)
+  return ''
+}

package/src/widgets-v2/actions/searcher/index.ts

@@ -0,0 +1,8 @@
+export { Searcher, type SearcherProps } from './searcher'
+export {
+  SearcherToggle,
+  setSearcherText,
+  type SearcherToggleProps,
+} from './searcher-toggle'
+export { filterBySearchText } from './filter'
+export { DEFAULT_SEARCHER_LABELS, type SearcherLabels } from './labels'

package/src/widgets-v2/actions/searcher/labels.ts

@@ -0,0 +1,13 @@
+export interface SearcherLabels {
+  toggle: string
+  placeholder: string
+  clearAriaLabel: string
+  noResults: string
+}
+
+export const DEFAULT_SEARCHER_LABELS: SearcherLabels = {
+  toggle: 'Search',
+  placeholder: 'Search…',
+  clearAriaLabel: 'Clear search',
+  noResults: 'No matches.',
+}