@carto/ps-react-ui 5.0.0-widgets.9 → 5.1.0

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 { Percent as PercentIcon } from '@mui/icons-material'
+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.',
+}

package/src/widgets-v2/actions/searcher/searcher-toggle.tsx

@@ -0,0 +1,91 @@
+import { useCallback, type ComponentType } from 'react'
+import { IconButton, type SvgIconProps } from '@mui/material'
+import { Search as SearchIcon } from '@mui/icons-material'
+import { Tooltip } from '../../../components'
+import {
+  getWidgetStore,
+  useSingleTransform,
+  useWidget,
+  useWidgetId,
+} from '../../stores'
+import { filterBySearchText } from './filter'
+import { DEFAULT_SEARCHER_LABELS, type SearcherLabels } from './labels'
+import { styles } from './style'
+
+const SEARCHER_DESCRIPTOR = {
+  id: 'searcher',
+  type: 'data' as const,
+  order: 20,
+  disables: ['lock-selection'],
+}
+
+export interface SearcherToggleProps {
+  labels?: Partial<SearcherLabels>
+  icon?: ComponentType<SvgIconProps>
+  iconProps?: SvgIconProps
+  /**
+   * Whether the searcher transform is enabled on first mount. Defaults
+   * to `false` so the toggle renders un-pressed and the
+   * `filterBySearchText` transform stays dormant until the user clicks
+   * it. Set to `true` for search-first widgets where the input is the
+   * primary affordance.
+   */
+  initialEnabled?: boolean
+}
+
+export function SearcherToggle({
+  labels,
+  icon: Icon = SearchIcon,
+  iconProps,
+  initialEnabled = false,
+}: SearcherToggleProps) {
+  const id = useWidgetId()
+  const resolved = { ...DEFAULT_SEARCHER_LABELS, ...labels }
+  const text = useWidget(
+    id,
+    (s) => (s.transformStates.searcher?.searchText as string | undefined) ?? '',
+  )
+
+  // The transform fn closes over `text`. Memoize via useCallback so identity
+  // only changes when text changes, allowing useTransform to re-register.
+  const fn = useCallback(
+    (data: unknown) => filterBySearchText(data, text),
+    [text],
+  )
+
+  const { enabled, toggle } = useSingleTransform(id, SEARCHER_DESCRIPTOR, fn, {
+    initialEnabled,
+  })
+
+  return (
+    <Tooltip title={resolved.toggle}>
+      <IconButton
+        size='small'
+        aria-label={resolved.toggle}
+        aria-pressed={enabled}
+        onClick={toggle}
+        sx={{ ...styles.toggle, ...(enabled && styles.toggleActive) }}
+      >
+        <Icon fontSize='small' {...iconProps} />
+      </IconButton>
+    </Tooltip>
+  )
+}
+
+/**
+ * Imperatively writes the search text into the widget store. Used by the
+ * Searcher input to update text inside transformStates without going through
+ * a re-rendered React subscription.
+ */
+export function setSearcherText(widgetId: string, value: string): void {
+  getWidgetStore(widgetId).setState((s) => ({
+    transformStates: {
+      ...s.transformStates,
+      searcher: {
+        enabled: s.transformStates.searcher?.enabled ?? false,
+        ...s.transformStates.searcher,
+        searchText: value,
+      },
+    },
+  }))
+}

package/src/widgets-v2/actions/searcher/searcher.test.tsx

@@ -0,0 +1,92 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+import { fireEvent, render, screen, act } from '@testing-library/react'
+import { Provider } from '../../provider/widget-provider'
+import { clearAllWidgetStores, getWidgetStore } from '../../stores'
+import { Searcher } from './searcher'
+import { SearcherToggle } from './searcher-toggle'
+
+beforeEach(() => clearAllWidgetStores())
+afterEach(() => clearAllWidgetStores())
+
+const DATA = [
+  [
+    { name: 'apple', value: 1 },
+    { name: 'banana', value: 2 },
+    { name: 'cherry', value: 3 },
+  ],
+]
+
+describe('<Searcher> + <SearcherToggle>', () => {
+  it('toggle defaults off — aria-pressed=false and input hidden', () => {
+    render(
+      <Provider id='sr1' data={DATA}>
+        <SearcherToggle />
+        <Searcher />
+      </Provider>,
+    )
+    const btn = screen.getByRole('button', { name: 'Search' })
+    expect(btn.getAttribute('aria-pressed')).toBe('false')
+    expect(screen.queryByPlaceholderText('Search…')).toBeNull()
+  })
+
+  it('initialEnabled=true opts into the legacy "search-first" behavior', () => {
+    render(
+      <Provider id='sr1b' data={DATA}>
+        <SearcherToggle initialEnabled />
+        <Searcher />
+      </Provider>,
+    )
+    const btn = screen.getByRole('button', { name: 'Search' })
+    expect(btn.getAttribute('aria-pressed')).toBe('true')
+    expect(screen.getByPlaceholderText('Search…')).toBeTruthy()
+  })
+
+  it('clicking the toggle reveals the input and flips aria-pressed', () => {
+    render(
+      <Provider id='sr2' data={DATA}>
+        <SearcherToggle />
+        <Searcher />
+      </Provider>,
+    )
+    fireEvent.click(screen.getByRole('button', { name: 'Search' }))
+    expect(screen.getByPlaceholderText('Search…')).toBeTruthy()
+    expect(
+      screen
+        .getByRole('button', { name: 'Search' })
+        .getAttribute('aria-pressed'),
+    ).toBe('true')
+  })
+
+  it('debounces input changes; after the timer fires the searchText is committed and the data is filtered', () => {
+    vi.useFakeTimers({ shouldAdvanceTime: true })
+    try {
+      render(
+        <Provider id='sr3' data={DATA}>
+          <SearcherToggle initialEnabled />
+          <Searcher debounceMs={100} />
+        </Provider>,
+      )
+      // `initialEnabled` opens the input straight away — no click needed.
+      const input = screen.getByPlaceholderText('Search…')
+      fireEvent.change(input, { target: { value: 'app' } })
+      // Pre-debounce: store still has no committed searchText.
+      expect(
+        getWidgetStore('sr3').getState().transformStates.searcher?.searchText,
+      ).toBeUndefined()
+
+      act(() => {
+        vi.advanceTimersByTime(120)
+      })
+
+      expect(
+        getWidgetStore('sr3').getState().transformStates.searcher?.searchText,
+      ).toBe('app')
+      const filtered = getWidgetStore('sr3').getState().data as {
+        name: string
+      }[][]
+      expect(filtered.flat().map((r) => r.name)).toEqual(['apple'])
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+})

package/src/widgets-v2/actions/searcher/searcher.tsx

@@ -0,0 +1,111 @@
+import { useCallback, useMemo, useRef, useState } from 'react'
+import { IconButton, InputAdornment, TextField } from '@mui/material'
+import { Search as SearchIcon } from '@mui/icons-material'
+import { Clear as ClearIcon } from '@mui/icons-material'
+import { debounce } from '@carto/ps-utils'
+import { getWidgetStore, useWidget, useWidgetId } from '../../stores'
+import { setSearcherText } from './searcher-toggle'
+import { DEFAULT_SEARCHER_LABELS, type SearcherLabels } from './labels'
+import { styles } from './style'
+
+export interface SearcherProps {
+  labels?: Partial<SearcherLabels>
+  /** Debounce delay before the input value is written to the widget store. */
+  debounceMs?: number
+}
+
+const DEFAULT_DEBOUNCE = 300
+
+/**
+ * Renders only when the matching `<SearcherToggle />` is enabled — drives the
+ * `transformStates['searcher'].searchText` field via a debounced setter.
+ */
+export function Searcher({
+  labels,
+  debounceMs = DEFAULT_DEBOUNCE,
+}: SearcherProps) {
+  const id = useWidgetId()
+  const resolved = { ...DEFAULT_SEARCHER_LABELS, ...labels }
+  const enabled = useWidget(
+    id,
+    (s) => s.transformStates.searcher?.enabled ?? false,
+  )
+
+  const inputRef = useRef<HTMLInputElement | null>(null)
+
+  // Hydrate from the store so re-toggling the input preserves any prior text.
+  const [local, setLocal] = useState<string>(
+    () =>
+      (getWidgetStore(id).getState().transformStates.searcher?.searchText as
+        string | undefined) ?? '',
+  )
+
+  const debouncedWrite = useMemo(
+    () =>
+      debounce(
+        (value: unknown) => setSearcherText(id, value as string),
+        debounceMs,
+      ),
+    [id, debounceMs],
+  )
+
+  const handleSearchTextChange = useCallback(
+    (e: React.ChangeEvent<HTMLInputElement>) => {
+      const value = e.target.value
+      setLocal(value)
+      debouncedWrite(value)
+    },
+    [debouncedWrite],
+  )
+
+  const handleClear = useCallback(() => {
+    setLocal('')
+    setSearcherText(id, '')
+    // Re-arm the debounced timer with '' so any pending stale write resolves
+    // to the cleared value rather than re-applying the previous text.
+    debouncedWrite('')
+    inputRef.current?.focus()
+  }, [id, debouncedWrite])
+
+  if (!enabled) return null
+
+  return (
+    <TextField
+      inputRef={inputRef}
+      size='small'
+      fullWidth
+      variant='filled'
+      placeholder={resolved.placeholder}
+      value={local}
+      onChange={handleSearchTextChange}
+      // The Searcher only mounts when the user explicitly toggles the
+      // SearcherToggle action — focusing the input on mount matches user
+      // intent, so the jsx-a11y/no-autofocus warning is the false-positive
+      // case (the rule targets unsolicited autofocus that disorients
+      // screen readers).
+      // eslint-disable-next-line
+      autoFocus
+      aria-label={resolved.placeholder}
+      sx={styles.input}
+      InputProps={{
+        startAdornment: (
+          <InputAdornment position='start'>
+            <SearchIcon fontSize='small' />
+          </InputAdornment>
+        ),
+        endAdornment: local ? (
+          <InputAdornment position='end'>
+            <IconButton
+              size='small'
+              edge='end'
+              aria-label={resolved.clearAriaLabel}
+              onClick={handleClear}
+            >
+              <ClearIcon fontSize='small' />
+            </IconButton>
+          </InputAdornment>
+        ) : null,
+      }}
+    />
+  )
+}