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

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

@@ -0,0 +1,354 @@
+import { describe, test, expect, beforeEach, vi, afterEach } from 'vitest'
+import { render, screen, fireEvent, act } from '@testing-library/react'
+import { SearcherToggle } from './searcher-toggle'
+import { Searcher } from './searcher'
+import { useWidgetStore } from '../../stores/widget-store'
+import type { EchartWidgetData } from '../../echart/types'
+import type { SearcherState } from './types'
+
+// Test data
+const mockData: EchartWidgetData = [
+  [
+    { name: 'Electronics', value: 440 },
+    { name: 'Clothing', value: 280 },
+    { name: 'Books', value: 100 },
+  ],
+]
+
+describe('SearcherToggle', () => {
+  const widgetId = 'test-searcher-toggle'
+
+  beforeEach(() => {
+    useWidgetStore.getState().clearWidgets()
+  })
+
+  test('renders search toggle button', () => {
+    render(<SearcherToggle id={widgetId} />)
+
+    const button = screen.getByRole('button')
+    expect(button).toBeTruthy()
+  })
+
+  test('shows enable tooltip when search is disabled', () => {
+    render(<SearcherToggle id={widgetId} />)
+
+    const button = screen.getByRole('button', { name: 'Enable search' })
+    expect(button).toBeTruthy()
+  })
+
+  test('shows disable tooltip when search is enabled', () => {
+    render(<SearcherToggle id={widgetId} defaultEnabled />)
+
+    const button = screen.getByRole('button', { name: 'Disable search' })
+    expect(button).toBeTruthy()
+  })
+
+  test('toggles isSearchEnabled in store when clicked', () => {
+    render(<SearcherToggle id={widgetId} />)
+
+    const button = screen.getByRole('button')
+    fireEvent.click(button)
+
+    const widget = useWidgetStore.getState().getWidget<SearcherState>(widgetId)
+    expect(widget?.isSearchEnabled).toBe(true)
+  })
+
+  test('has active state when enabled via store', () => {
+    render(<SearcherToggle id={widgetId} defaultEnabled />)
+
+    const button = screen.getByRole('button')
+    expect(button.getAttribute('data-active')).toBe('true')
+  })
+
+  test('has inactive state when disabled', () => {
+    render(<SearcherToggle id={widgetId} />)
+
+    const button = screen.getByRole('button')
+    expect(button.getAttribute('data-active')).toBe('false')
+  })
+
+  test('uses custom labels', () => {
+    render(
+      <SearcherToggle
+        id={widgetId}
+        labels={{
+          enable: 'Activar búsqueda',
+          disable: 'Desactivar búsqueda',
+          ariaLabel: 'Toggle search',
+        }}
+      />,
+    )
+
+    const button = screen.getByRole('button', { name: 'Toggle search' })
+    expect(button).toBeTruthy()
+  })
+
+  test('initializes store with defaultEnabled value', () => {
+    render(<SearcherToggle id={widgetId} defaultEnabled />)
+
+    const widget = useWidgetStore.getState().getWidget<SearcherState>(widgetId)
+    expect(widget?.isSearchEnabled).toBe(true)
+  })
+})
+
+describe('Searcher', () => {
+  const widgetId = 'test-searcher-input'
+
+  beforeEach(() => {
+    useWidgetStore.getState().clearWidgets()
+    vi.useFakeTimers()
+  })
+
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  test('does not render when search is disabled in store', () => {
+    // Set isSearchEnabled to false in store
+    useWidgetStore.getState().setWidget(widgetId, { isSearchEnabled: false })
+
+    render(<Searcher id={widgetId} />)
+
+    const input = screen.queryByRole('textbox')
+    expect(input).toBeNull()
+  })
+
+  test('renders input when search is enabled in store', () => {
+    // Set isSearchEnabled to true in store
+    useWidgetStore.getState().setWidget(widgetId, { isSearchEnabled: true })
+
+    render(<Searcher id={widgetId} />)
+
+    const input = screen.getByRole('textbox')
+    expect(input).toBeTruthy()
+  })
+
+  test('shows placeholder text', () => {
+    useWidgetStore.getState().setWidget(widgetId, { isSearchEnabled: true })
+
+    render(<Searcher id={widgetId} labels={{ placeholder: 'Search...' }} />)
+
+    const input = screen.getByPlaceholderText('Search...')
+    expect(input).toBeTruthy()
+  })
+
+  test('updates store with debounced filtered data', async () => {
+    // Initialize widget with data and enabled state
+    useWidgetStore
+      .getState()
+      .setWidget(widgetId, { data: mockData, isSearchEnabled: true })
+
+    render(<Searcher id={widgetId} />)
+
+    const input = screen.getByRole('textbox')
+    fireEvent.change(input, { target: { value: 'Electronics' } })
+
+    // Wait for debounce (300ms) and flush all pending promises
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(300)
+    })
+
+    // Execute the tool pipeline to apply the filter transformation
+    await useWidgetStore.getState().executeToolPipeline(widgetId, mockData)
+
+    const widget = useWidgetStore.getState().getWidget(widgetId)
+    const filteredData = widget?.data as EchartWidgetData | undefined
+
+    // Should only have Electronics item
+    expect(filteredData?.[0]?.length).toBe(1)
+    expect(filteredData?.[0]?.[0]?.name).toBe('Electronics')
+  })
+
+  test('shows clear button when there is text', () => {
+    useWidgetStore.getState().setWidget(widgetId, { isSearchEnabled: true })
+
+    render(<Searcher id={widgetId} />)
+
+    const input = screen.getByRole('textbox')
+    fireEvent.change(input, { target: { value: 'test' } })
+
+    const clearButton = screen.getByRole('button', { name: 'Clear search' })
+    expect(clearButton).toBeTruthy()
+  })
+
+  test('does not show clear button when input is empty', () => {
+    useWidgetStore.getState().setWidget(widgetId, { isSearchEnabled: true })
+
+    render(<Searcher id={widgetId} />)
+
+    const clearButton = screen.queryByRole('button', { name: 'Clear search' })
+    expect(clearButton).toBeNull()
+  })
+
+  test('clears search text and restores original data when clear button is clicked', () => {
+    // Initialize widget with data and enabled state
+    useWidgetStore
+      .getState()
+      .setWidget(widgetId, { data: mockData, isSearchEnabled: true })
+
+    render(<Searcher id={widgetId} />)
+
+    const input = screen.getByRole('textbox')
+    fireEvent.change(input, { target: { value: 'Electronics' } })
+
+    // Wait for debounce
+    act(() => {
+      vi.advanceTimersByTime(300)
+    })
+
+    // Click clear
+    const clearButton = screen.getByRole('button', { name: 'Clear search' })
+    fireEvent.click(clearButton)
+
+    // Data should be restored to original
+    const widget = useWidgetStore.getState().getWidget(widgetId)
+    const restoredData = widget?.data as EchartWidgetData | undefined
+    expect(restoredData?.[0]?.length).toBe(3)
+  })
+
+  test('uses custom clear button aria label', () => {
+    useWidgetStore.getState().setWidget(widgetId, { isSearchEnabled: true })
+
+    render(
+      <Searcher
+        id={widgetId}
+        labels={{ clearAriaLabel: 'Limpiar búsqueda' }}
+      />,
+    )
+
+    const input = screen.getByRole('textbox')
+    fireEvent.change(input, { target: { value: 'text' } })
+
+    const clearButton = screen.getByRole('button', {
+      name: 'Limpiar búsqueda',
+    })
+    expect(clearButton).toBeTruthy()
+  })
+
+  test('uses custom filter function', async () => {
+    // Custom filter that only matches exact values
+    const customFilterFn = async (
+      data: EchartWidgetData,
+      searchText: string,
+    ) => {
+      return Promise.resolve(
+        data.map((series) =>
+          series.filter((item) => item.value === parseInt(searchText, 10)),
+        ),
+      )
+    }
+
+    // Initialize widget with data and enabled state
+    useWidgetStore
+      .getState()
+      .setWidget(widgetId, { data: mockData, isSearchEnabled: true })
+
+    render(<Searcher id={widgetId} filterFn={customFilterFn} />)
+
+    const input = screen.getByRole('textbox')
+    fireEvent.change(input, { target: { value: '440' } })
+
+    // Wait for debounce and flush all pending promises
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(300)
+    })
+
+    // Execute the tool pipeline to apply the filter transformation
+    await useWidgetStore.getState().executeToolPipeline(widgetId, mockData)
+
+    // Should only have Electronics (value: 440)
+    const widget = useWidgetStore.getState().getWidget(widgetId)
+    const filteredData = widget?.data as EchartWidgetData | undefined
+    expect(filteredData?.[0]?.length).toBe(1)
+    expect(filteredData?.[0]?.[0]?.value).toBe(440)
+  })
+})
+
+describe('SearcherToggle + Searcher integration', () => {
+  const widgetId = 'test-integration'
+
+  beforeEach(() => {
+    useWidgetStore.getState().clearWidgets()
+  })
+
+  // Helper component that uses both SearcherToggle and Searcher with same id
+  function IntegrationTest() {
+    return (
+      <>
+        <SearcherToggle id={widgetId} />
+        <Searcher id={widgetId} />
+      </>
+    )
+  }
+
+  test('searcher becomes visible when toggle is clicked', () => {
+    render(<IntegrationTest />)
+
+    // Initially searcher should not be visible
+    expect(screen.queryByRole('textbox')).toBeNull()
+
+    // Click toggle
+    const toggleButton = screen.getByRole('button')
+    fireEvent.click(toggleButton)
+
+    // Searcher should now be visible
+    expect(screen.getByRole('textbox')).toBeTruthy()
+  })
+
+  test('searcher is hidden when toggle is clicked again', () => {
+    render(<IntegrationTest />)
+
+    const toggleButton = screen.getByRole('button')
+
+    // Enable
+    fireEvent.click(toggleButton)
+    expect(screen.getByRole('textbox')).toBeTruthy()
+
+    // Disable
+    fireEvent.click(toggleButton)
+    expect(screen.queryByRole('textbox')).toBeNull()
+  })
+
+  test('toggle button shows correct active state', () => {
+    render(<IntegrationTest />)
+
+    const toggleButton = screen.getByRole('button')
+
+    // Initially inactive
+    expect(toggleButton.getAttribute('data-active')).toBe('false')
+
+    // Enable - should be active
+    fireEvent.click(toggleButton)
+    expect(toggleButton.getAttribute('data-active')).toBe('true')
+
+    // Disable - should be inactive
+    fireEvent.click(toggleButton)
+    expect(toggleButton.getAttribute('data-active')).toBe('false')
+  })
+
+  test('store state is correctly updated when toggling', () => {
+    render(<IntegrationTest />)
+
+    const toggleButton = screen.getByRole('button')
+
+    // Initially should be false
+    expect(
+      useWidgetStore.getState().getWidget<SearcherState>(widgetId)
+        ?.isSearchEnabled,
+    ).toBe(false)
+
+    // Enable
+    fireEvent.click(toggleButton)
+    expect(
+      useWidgetStore.getState().getWidget<SearcherState>(widgetId)
+        ?.isSearchEnabled,
+    ).toBe(true)
+
+    // Disable
+    fireEvent.click(toggleButton)
+    expect(
+      useWidgetStore.getState().getWidget<SearcherState>(widgetId)
+        ?.isSearchEnabled,
+    ).toBe(false)
+  })
+})

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

@@ -0,0 +1,72 @@
+import { IconButton } from '@mui/material'
+import { SearchOutlined } from '@mui/icons-material'
+import { useCallback, useEffect } from 'react'
+import type { SearcherToggleProps, SearcherState } from './types'
+import { actionButtonStyles } from '../shared/styles'
+import { Tooltip } from '../../../components'
+import { widgetStoreActions } from '../../stores/widget-store'
+import { useWidgetSelector } from '../../stores/use-widget-selector'
+
+/**
+ * Widget action button to toggle search functionality.
+ *
+ * Stores the enabled state in the widget store using the provided id.
+ * When search is active, the button shows an active state with a light background.
+ * Use in conjunction with the Searcher component to display the search input.
+ *
+ * @example
+ * ```tsx
+ * <SearcherToggle id="my-widget" />
+ * <Searcher
+ *   id="my-widget"
+ *   data={widgetData}
+ * />
+ * ```
+ */
+export function SearcherToggle({
+  id,
+  defaultEnabled = false,
+  labels,
+  Icon,
+  IconButtonProps,
+}: SearcherToggleProps) {
+  const { storeIsEnabled } = useWidgetSelector(id, (w) => ({
+    storeIsEnabled: (w as SearcherState | undefined)?.isSearchEnabled,
+  }))
+
+  const isEnabled = storeIsEnabled ?? defaultEnabled
+
+  // Initialize store with default value on mount
+  useEffect(() => {
+    const currentValue =
+      widgetStoreActions.getWidget<SearcherState>(id)?.isSearchEnabled
+    if (currentValue === undefined) {
+      widgetStoreActions.setWidget(id, { isSearchEnabled: defaultEnabled })
+    }
+  }, [defaultEnabled, id])
+
+  const handleToggle = useCallback(() => {
+    widgetStoreActions.setWidget(id, { isSearchEnabled: !isEnabled })
+  }, [id, isEnabled])
+
+  const tooltipLabel = isEnabled
+    ? (labels?.disable ?? 'Disable search')
+    : (labels?.enable ?? 'Enable search')
+
+  const ariaLabel = labels?.ariaLabel ?? tooltipLabel
+
+  return (
+    <Tooltip title={tooltipLabel}>
+      <IconButton
+        size='small'
+        aria-label={ariaLabel}
+        onClick={handleToggle}
+        sx={actionButtonStyles.trigger}
+        data-active={isEnabled}
+        {...IconButtonProps}
+      >
+        {Icon ?? <SearchOutlined fontSize='small' />}
+      </IconButton>
+    </Tooltip>
+  )
+}

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

@@ -0,0 +1,196 @@
+import { TextField, InputAdornment, IconButton } from '@mui/material'
+import { ClearOutlined, SearchOutlined } from '@mui/icons-material'
+import { useEffect, useRef, useCallback } from 'react'
+import { widgetStoreActions } from '../../stores/widget-store'
+import { useWidgetSelector } from '../../stores/use-widget-selector'
+import type { SearcherProps, SearcherFilterFn, SearcherState } from './types'
+import type { EchartWidgetData } from '../../echart/types'
+import { LOCK_SELECTION_TOOL_ID } from '../lock-selection/lock-selection'
+
+export const SEARCHER_TOOL_ID = 'searcher'
+
+const DEBOUNCE_DELAY = 300
+
+/**
+ * Search input component that works with SearcherToggle.
+ *
+ * Registers a transformation tool in the widget pipeline when mounted.
+ * Reads the enabled state from the widget store using the provided id.
+ * Uses a debounced search to filter data via the transformation pipeline.
+ * Auto-focuses when enabled becomes true.
+ *
+ * @example
+ * ```tsx
+ * <SearcherToggle id="my-widget" />
+ * <Searcher
+ *   id="my-widget"
+ *   order={10}
+ *   labels={{ placeholder: 'Search categories...' }}
+ * />
+ * ```
+ */
+export function Searcher({
+  id,
+  filterFn,
+  order = 20,
+  labels,
+  TextFieldProps,
+  ClearIcon,
+  debounceDelay = DEBOUNCE_DELAY,
+}: SearcherProps) {
+  const inputRef = useRef<HTMLInputElement>(null)
+  const debounceTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+
+  // Read enabled state and search text from widget store
+  const { enabled, searchText } = useWidgetSelector(id, (w) => ({
+    enabled: (w as SearcherState | undefined)?.isSearchEnabled ?? false,
+    searchText: (w as SearcherState | undefined)?.searchText ?? '',
+  }))
+  const prevEnabledRef = useRef(enabled)
+
+  const filter = filterFn ?? defaultFilterFn
+
+  const setSearchText = useCallback(
+    (text: string) => {
+      widgetStoreActions.setWidget(id, { searchText: text })
+    },
+    [id],
+  )
+
+  // Register tool once — fn reads searchText from the store at execution time.
+  // Enabled is synced separately to avoid full re-registration on toggle.
+  useEffect(() => {
+    widgetStoreActions.registerTool(id, {
+      id: SEARCHER_TOOL_ID,
+      order,
+      enabled: false,
+      fn: async (data) => {
+        const widget = widgetStoreActions.getWidget<SearcherState>(id)
+        const currentSearchText = widget?.searchText ?? ''
+
+        // Execute filter (can be sync or async)
+        const result = filter(data as EchartWidgetData, currentSearchText)
+
+        // Return result directly (pipeline will handle Promise)
+        return result
+      },
+      disables: [LOCK_SELECTION_TOOL_ID],
+    })
+
+    return () => widgetStoreActions.unregisterTool(id, SEARCHER_TOOL_ID)
+  }, [id, order, filter])
+
+  // Sync enabled from store — lightweight, no re-registration
+  useEffect(() => {
+    widgetStoreActions.setToolEnabled(id, SEARCHER_TOOL_ID, enabled)
+  }, [id, enabled])
+
+  // Trigger pipeline re-execution when search text changes (debounced).
+  // The fn reads searchText from the store, so we just need to trigger the pipeline.
+  const debouncedTriggerPipeline = useCallback(() => {
+    if (debounceTimeoutRef.current) {
+      clearTimeout(debounceTimeoutRef.current)
+    }
+    debounceTimeoutRef.current = setTimeout(() => {
+      widgetStoreActions.triggerToolPipeline(id)
+    }, debounceDelay)
+  }, [id, debounceDelay])
+
+  // Auto-focus when enabled becomes true
+  useEffect(() => {
+    // Transition from disabled to enabled - focus input
+    if (enabled && !prevEnabledRef.current && inputRef.current) {
+      inputRef.current.focus()
+    }
+
+    prevEnabledRef.current = enabled
+  }, [enabled])
+
+  // Cleanup debounce timeout on unmount
+  useEffect(() => {
+    return () => {
+      if (debounceTimeoutRef.current) {
+        clearTimeout(debounceTimeoutRef.current)
+      }
+    }
+  }, [])
+
+  const handleChange = useCallback(
+    (event: React.ChangeEvent<HTMLInputElement>) => {
+      const newValue = event.target.value
+      setSearchText(newValue)
+      debouncedTriggerPipeline()
+    },
+    [debouncedTriggerPipeline, setSearchText],
+  )
+
+  const handleClear = useCallback(() => {
+    setSearchText('')
+    widgetStoreActions.triggerToolPipeline(id)
+    if (inputRef.current) {
+      inputRef.current.focus()
+    }
+  }, [id, setSearchText])
+
+  if (!enabled) {
+    return null
+  }
+
+  const placeholder = labels?.placeholder ?? 'Search...'
+  const clearAriaLabel = labels?.clearAriaLabel ?? 'Clear search'
+
+  return (
+    <TextField
+      inputRef={inputRef}
+      size='small'
+      fullWidth
+      variant='filled'
+      placeholder={placeholder}
+      value={searchText}
+      onChange={handleChange}
+      InputProps={{
+        startAdornment: (
+          <InputAdornment position='start'>
+            <SearchOutlined />
+          </InputAdornment>
+        ),
+        endAdornment: searchText ? (
+          <InputAdornment position='end'>
+            <IconButton
+              size='small'
+              aria-label={clearAriaLabel}
+              onClick={handleClear}
+              edge='end'
+            >
+              {ClearIcon ?? <ClearOutlined fontSize='small' />}
+            </IconButton>
+          </InputAdornment>
+        ) : null,
+      }}
+      {...TextFieldProps}
+    />
+  )
+}
+
+/**
+ * Default filter function that searches all string fields case-insensitively.
+ * Note: Should be synchronous for the new pipeline architecture.
+ */
+const defaultFilterFn: SearcherFilterFn = (
+  data: EchartWidgetData,
+  searchText: string,
+) => {
+  if (!searchText.trim()) return Promise.resolve(data)
+
+  const lowerSearch = searchText.toLowerCase()
+
+  return Promise.resolve(
+    data.map((series) =>
+      series.filter((item) =>
+        Object.values(item).some((value) =>
+          String(value).toLowerCase().includes(lowerSearch),
+        ),
+      ),
+    ),
+  )
+}

package/src/widgets/actions/searcher/types.ts

@@ -0,0 +1,72 @@
+import type { IconButtonProps, TextFieldProps } from '@mui/material'
+import type { ReactNode } from 'react'
+import type { EchartWidgetData } from '../../echart/types'
+import type { BaseWidgetState } from '../../stores/types'
+
+/**
+ * Filter function type for custom search filtering logic.
+ * Receives the original data and search text, returns filtered data.
+ * Can be synchronous or asynchronous to support remote filtering.
+ */
+export type SearcherFilterFn = (
+  data: EchartWidgetData,
+  searchText: string,
+) => Promise<EchartWidgetData> | EchartWidgetData
+
+/**
+ * Searcher-specific state properties.
+ */
+export interface SearcherStateProps {
+  /** Whether search is currently enabled */
+  isSearchEnabled?: boolean
+  /** Current search text */
+  searchText?: string
+}
+
+/**
+ * Widget state extension for searcher functionality.
+ * Extends the base widget state with search-specific properties.
+ */
+export type SearcherState<T = object> = BaseWidgetState<T & SearcherStateProps>
+
+export interface SearcherToggleProps {
+  /** Widget ID to store search enabled state */
+  id: string
+  /** Initial search enabled state. Defaults to false */
+  defaultEnabled?: boolean
+  /** Custom labels for the action */
+  labels?: {
+    /** Tooltip when search is disabled (button will enable search) */
+    enable?: string
+    /** Tooltip when search is enabled (button will disable search) */
+    disable?: string
+    /** Accessibility label */
+    ariaLabel?: string
+  }
+  /** Props passed to the IconButton component */
+  IconButtonProps?: IconButtonProps
+  /** Custom icon to display */
+  Icon?: ReactNode
+}
+
+export interface SearcherProps {
+  /** Widget ID to update filtered data in the widget store */
+  id: string
+  /** Custom filter function. Defaults to case-insensitive search across all string fields */
+  filterFn?: SearcherFilterFn
+  /** Execution order in the tool pipeline. Lower values execute first. Defaults to 10. */
+  order?: number
+  /** Custom labels for the searcher input */
+  labels?: {
+    /** Placeholder text for the input */
+    placeholder?: string
+    /** Accessibility label for clear button */
+    clearAriaLabel?: string
+  }
+  /** Props passed to the TextField component */
+  TextFieldProps?: Omit<TextFieldProps, 'value' | 'onChange' | 'size'>
+  /** Custom icon for clear button */
+  ClearIcon?: ReactNode
+  /** Debounce delay in milliseconds for search input. Defaults to 300ms */
+  debounceDelay?: number
+}

package/src/widgets/actions/shared/styles.ts

@@ -0,0 +1,12 @@
+import type { SxProps, Theme } from '@mui/material'
+
+/**
+ * Shared styles for widget action buttons
+ */
+export const actionButtonStyles = {
+  trigger: {
+    '&[data-active="true"]': {
+      background: (theme: Theme) => theme.palette.primary.relatedLight,
+    },
+  },
+} satisfies Record<string, SxProps<Theme>>