@carto/ps-react-ui 4.7.1 → 4.8.0

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 SearchIcon from '@mui/icons-material/Search'
+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,112 @@
+import { useCallback, useMemo, useRef, useState } from 'react'
+import { IconButton, InputAdornment, TextField } from '@mui/material'
+import SearchIcon from '@mui/icons-material/Search'
+import ClearIcon from '@mui/icons-material/Clear'
+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,
+      }}
+    />
+  )
+}

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

@@ -0,0 +1,15 @@
+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,
+  },
+  input: {
+    width: '100%',
+    mb: 1,
+  },
+} satisfies Record<string, SxProps<Theme>>

package/src/widgets-v2/actions/stack-toggle/index.ts

@@ -0,0 +1,3 @@
+export { StackToggle, type StackToggleProps } from './stack-toggle'
+export { addStack } from './transforms'
+export { DEFAULT_STACK_TOGGLE_LABELS, type StackToggleLabels } from './labels'

package/src/widgets-v2/actions/stack-toggle/labels.ts

@@ -0,0 +1,9 @@
+export interface StackToggleLabels {
+  on: string
+  off: string
+}
+
+export const DEFAULT_STACK_TOGGLE_LABELS: StackToggleLabels = {
+  on: 'Unstack series',
+  off: 'Stack series',
+}

package/src/widgets-v2/actions/stack-toggle/stack-toggle.test.tsx

@@ -0,0 +1,61 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { fireEvent, render, screen } from '@testing-library/react'
+import { Provider } from '../../provider/widget-provider'
+import { clearAllWidgetStores, getWidgetStore } from '../../stores'
+import { StackToggle } from './stack-toggle'
+
+beforeEach(() => clearAllWidgetStores())
+afterEach(() => clearAllWidgetStores())
+
+/**
+ * Stack/Zoom/Brush share the same toggle wiring. This file is the exemplar.
+ * The transforms themselves are tested in `transforms.test.ts` /
+ * `…/zoom-toggle/transforms.test.ts` / `…/brush-toggle/transforms.test.ts`.
+ */
+describe('<StackToggle>', () => {
+  it('starts disabled by default and uses the off-state label', () => {
+    render(
+      <Provider id='st1' data={[]}>
+        <StackToggle />
+      </Provider>,
+    )
+    const btn = screen.getByRole('button', { name: 'Stack series' })
+    expect(btn.getAttribute('aria-pressed')).toBe('false')
+  })
+
+  it('toggles aria-pressed and label on click', () => {
+    render(
+      <Provider id='st2' data={[]}>
+        <StackToggle />
+      </Provider>,
+    )
+    fireEvent.click(screen.getByRole('button', { name: 'Stack series' }))
+    const after = screen.getByRole('button', { name: 'Unstack series' })
+    expect(after.getAttribute('aria-pressed')).toBe('true')
+  })
+
+  it('persists the enabled flag on the widget store under transformStates', () => {
+    render(
+      <Provider id='st3' data={[]}>
+        <StackToggle />
+      </Provider>,
+    )
+    fireEvent.click(screen.getByRole('button', { name: 'Stack series' }))
+    expect(
+      getWidgetStore('st3').getState().transformStates['stack-toggle']?.enabled,
+    ).toBe(true)
+  })
+
+  it('initialEnabled=true mounts already-on', () => {
+    render(
+      <Provider id='st4' data={[]}>
+        <StackToggle initialEnabled />
+      </Provider>,
+    )
+    expect(
+      screen
+        .getByRole('button', { name: 'Unstack series' })
+        .getAttribute('aria-pressed'),
+    ).toBe('true')
+  })
+})

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

@@ -0,0 +1,54 @@
+import { type ComponentType } from 'react'
+import { IconButton, type SvgIconProps } from '@mui/material'
+import StackedBarChartIcon from '@mui/icons-material/StackedBarChart'
+import { Tooltip } from '../../../components'
+import { useSingleTransform, useWidgetId } from '../../stores'
+import { addStack } from './transforms'
+import { DEFAULT_STACK_TOGGLE_LABELS, type StackToggleLabels } from './labels'
+import { styles } from './style'
+
+const STACK_DESCRIPTOR = {
+  id: 'stack-toggle',
+  type: 'config' as const,
+  order: 30,
+}
+
+export interface StackToggleProps {
+  initialEnabled?: boolean
+  labels?: Partial<StackToggleLabels>
+  icon?: ComponentType<SvgIconProps>
+  iconProps?: SvgIconProps
+}
+
+export function StackToggle({
+  initialEnabled = false,
+  labels,
+  icon: Icon = StackedBarChartIcon,
+  iconProps,
+}: StackToggleProps) {
+  const id = useWidgetId()
+  const _labels = { ...DEFAULT_STACK_TOGGLE_LABELS, ...labels }
+  const { enabled, toggle } = useSingleTransform(
+    id,
+    STACK_DESCRIPTOR,
+    addStack,
+    {
+      initialEnabled,
+    },
+  )
+  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/stack-toggle/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/stack-toggle/transforms.test.ts

@@ -0,0 +1,43 @@
+import { describe, it, expect } from 'vitest'
+import { addStack } from './transforms'
+
+describe('addStack', () => {
+  it('passes through non-objects unchanged', () => {
+    expect(addStack(undefined)).toBe(undefined)
+    expect(addStack(null)).toBe(null)
+    expect(addStack(42)).toBe(42)
+  })
+
+  it('marks every existing series with stack:"total"', () => {
+    const out = addStack({
+      title: { text: 'x' },
+      series: [{ type: 'bar' }, { type: 'bar' }],
+    }) as { series: { type: string; stack: string }[]; title: { text: string } }
+    expect(out.series).toHaveLength(2)
+    expect(out.series[0]).toMatchObject({ type: 'bar', stack: 'total' })
+    expect(out.series[1]).toMatchObject({ type: 'bar', stack: 'total' })
+    expect(out.title).toEqual({ text: 'x' })
+  })
+
+  it('emits a broadcast template when there are no existing series (data-fusion widgets)', () => {
+    const out = addStack({}) as { series: { stack: string }[] }
+    expect(out.series).toEqual([{ stack: 'total' }])
+  })
+
+  it('emits a broadcast template when series is missing entirely', () => {
+    const out = addStack({ tooltip: {} }) as {
+      series: { stack: string }[]
+      tooltip: object
+    }
+    expect(out.series).toEqual([{ stack: 'total' }])
+    expect(out.tooltip).toBeDefined()
+  })
+
+  it('preserves non-object series entries (defensive)', () => {
+    const out = addStack({ series: ['weird', { type: 'bar' }] }) as {
+      series: unknown[]
+    }
+    expect(out.series[0]).toBe('weird')
+    expect(out.series[1]).toMatchObject({ type: 'bar', stack: 'total' })
+  })
+})

package/src/widgets-v2/actions/stack-toggle/transforms.ts

@@ -0,0 +1,25 @@
+/**
+ * Stack-mode config transform: marks every series with `stack: 'total'` so
+ * ECharts stacks them vertically (bar) or by value (line). Module-level
+ * constant so identity is stable across renders — no `useCallback` needed.
+ *
+ * Widgets that bake series into options at build time get marked in place.
+ * Widgets that build series at data-fusion time (`bar`, `histogram`,
+ * `timeseries`) have no `series` array yet at config-transform time, so we
+ * also emit a single-entry **broadcast template** (`[{ stack: 'total' }]`).
+ * Their option factories merge that template into every series they emit
+ * at fusion time, so the `stack` mark survives end-to-end.
+ */
+export const addStack = (option: unknown): unknown => {
+  if (option == null || typeof option !== 'object') return option
+  const cfg = option as Record<string, unknown>
+  const existing = Array.isArray(cfg.series) ? cfg.series : []
+  const series =
+    existing.length === 0
+      ? [{ stack: 'total' }]
+      : existing.map((s: unknown): unknown => {
+          if (s == null || typeof s !== 'object') return s
+          return { ...s, stack: 'total' }
+        })
+  return { ...cfg, series }
+}

package/src/widgets-v2/actions/zoom-toggle/index.ts

@@ -0,0 +1,9 @@
+export { ZoomToggle, type ZoomToggleProps } from './zoom-toggle'
+export {
+  addZoom,
+  createAddZoom,
+  ZOOM_LAYOUT,
+  type ZoomAxis,
+  type CreateAddZoomOptions,
+} from './transforms'
+export { DEFAULT_ZOOM_TOGGLE_LABELS, type ZoomToggleLabels } from './labels'

package/src/widgets-v2/actions/zoom-toggle/labels.ts

@@ -0,0 +1,9 @@
+export interface ZoomToggleLabels {
+  on: string
+  off: string
+}
+
+export const DEFAULT_ZOOM_TOGGLE_LABELS: ZoomToggleLabels = {
+  on: 'Disable zoom',
+  off: 'Enable zoom',
+}

package/src/widgets-v2/actions/zoom-toggle/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>>