@carto/ps-react-ui 4.3.3 → 4.3.5

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

@@ -0,0 +1,186 @@
+import { describe, test, expect, beforeEach } from 'vitest'
+import { render, screen, fireEvent } from '@testing-library/react'
+import { LockSelection } from './lock-selection'
+import { useWidgetStore } from '../../stores/widget-store'
+import type { EchartWidgetData } from '../../echart/types'
+import type { LockSelectionState } from './types'
+import { WidgetLoader } from '../../loader/loader'
+
+// Test data
+const mockData: EchartWidgetData = [
+  [
+    { name: 'Electronics', value: 440 },
+    { name: 'Clothing', value: 280 },
+    { name: 'Books', value: 100 },
+  ],
+]
+
+describe('LockSelection', () => {
+  const widgetId = 'test-lock-selection'
+
+  beforeEach(() => {
+    useWidgetStore.getState().clearWidgets()
+  })
+
+  test('renders nothing when no selections', () => {
+    const { container } = render(
+      <LockSelection id={widgetId} selectedItems={[]} />,
+    )
+
+    expect(container.firstChild).toBeNull()
+  })
+
+  test('renders lock button when there are selections', () => {
+    render(<LockSelection id={widgetId} selectedItems={['Electronics']} />)
+
+    const button = screen.getByRole('button')
+    expect(button).toBeTruthy()
+  })
+
+  test('shows lock tooltip when unlocked', () => {
+    render(<LockSelection id={widgetId} selectedItems={['Electronics']} />)
+
+    const button = screen.getByRole('button', { name: 'Lock selection' })
+    expect(button).toBeTruthy()
+  })
+
+  test('shows unlock tooltip when locked', () => {
+    // Pre-set the store to locked state
+    useWidgetStore.getState().setWidget(widgetId, { isLocked: true })
+
+    render(<LockSelection id={widgetId} selectedItems={['Electronics']} />)
+
+    const button = screen.getByRole('button', { name: 'Unlock selection' })
+    expect(button).toBeTruthy()
+  })
+
+  test('toggles isLocked in store when clicked', () => {
+    render(<LockSelection id={widgetId} selectedItems={['Electronics']} />)
+
+    const button = screen.getByRole('button')
+    fireEvent.click(button)
+
+    const widget = useWidgetStore
+      .getState()
+      .getWidget<LockSelectionState>(widgetId)
+    expect(widget?.isLocked).toBe(true)
+  })
+
+  test('filters data in store when locking', async () => {
+    const selectedItems = ['Electronics']
+
+    render(
+      <WidgetLoader
+        id={widgetId}
+        type='test'
+        data={mockData}
+        isLoading={false}
+        isFetching={false}
+      >
+        <LockSelection id={widgetId} selectedItems={selectedItems} />
+      </WidgetLoader>,
+    )
+
+    const button = screen.getByRole('button')
+    fireEvent.click(button)
+
+    await useWidgetStore.getState().executeToolPipeline(widgetId, mockData)
+
+    const widget = useWidgetStore
+      .getState()
+      .getWidget<LockSelectionState>(widgetId)
+    expect(widget?.data).toEqual([[{ name: 'Electronics', value: 440 }]])
+  })
+
+  test('clears locked items when unlocking', () => {
+    // Pre-set the store to locked state
+    useWidgetStore.getState().setWidget(widgetId, {
+      isLocked: true,
+      lockedItems: ['Electronics'],
+    })
+
+    render(<LockSelection id={widgetId} selectedItems={['Electronics']} />)
+
+    const button = screen.getByRole('button')
+    fireEvent.click(button)
+
+    const widget = useWidgetStore
+      .getState()
+      .getWidget<LockSelectionState>(widgetId)
+    expect(widget?.isLocked).toBe(false)
+  })
+
+  test('has active state when locked', () => {
+    useWidgetStore.getState().setWidget(widgetId, { isLocked: true })
+
+    render(<LockSelection id={widgetId} selectedItems={['Electronics']} />)
+
+    const button = screen.getByRole('button')
+    expect(button.getAttribute('data-active')).toBe('true')
+  })
+
+  test('has inactive state when unlocked', () => {
+    render(<LockSelection id={widgetId} selectedItems={['Electronics']} />)
+
+    const button = screen.getByRole('button')
+    expect(button.getAttribute('data-active')).toBe('false')
+  })
+
+  test('uses custom labels', () => {
+    render(
+      <LockSelection
+        id={widgetId}
+        selectedItems={['Electronics']}
+        labels={{
+          lock: 'Bloquear selección',
+          unlock: 'Desbloquear selección',
+          ariaLabel: 'Toggle lock',
+        }}
+      />,
+    )
+
+    const button = screen.getByRole('button', { name: 'Toggle lock' })
+    expect(button).toBeTruthy()
+  })
+
+  test('filters multiple series when locking', async () => {
+    const multiSeriesData: EchartWidgetData = [
+      [
+        { name: 'Electronics', value: 440 },
+        { name: 'Clothing', value: 280 },
+      ],
+      [
+        { name: 'Electronics', value: 520 },
+        { name: 'Clothing', value: 350 },
+      ],
+    ]
+    const selectedItems = ['Electronics']
+
+    render(
+      <WidgetLoader
+        id={widgetId}
+        type='test'
+        data={multiSeriesData}
+        isLoading={false}
+        isFetching={false}
+      >
+        <LockSelection id={widgetId} selectedItems={selectedItems} />
+      </WidgetLoader>,
+    )
+
+    const button = screen.getByRole('button')
+    fireEvent.click(button)
+
+    await useWidgetStore
+      .getState()
+      .executeToolPipeline(widgetId, multiSeriesData)
+
+    const widget = useWidgetStore
+      .getState()
+      .getWidget<LockSelectionState>(widgetId)
+    expect(widget?.data).toEqual([
+      [{ name: 'Electronics', value: 440 }],
+      [{ name: 'Electronics', value: 520 }],
+    ])
+  })
+})

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

@@ -0,0 +1,133 @@
+import { IconButton } from '@mui/material'
+import { CheckBoxOutlined } from '@mui/icons-material'
+import { useCallback, useEffect, useMemo } from 'react'
+import type { LockSelectionProps, LockSelectionState } from './types'
+import { actionButtonStyles } from '../shared/styles'
+import { Tooltip } from '../../../components'
+import { useWidgetStore } from '../../stores/widget-store'
+import { useShallow } from 'zustand/shallow'
+import type { EchartWidgetData } from '../../echart/types'
+
+export const LOCK_SELECTION_TOOL_ID = 'lock-selection'
+
+/**
+ * Widget action button to lock the current selection.
+ *
+ * When locked, the widget data is filtered to only show the selected items.
+ * The button is only visible when there are selected items.
+ * Registers a transformation tool in the widget pipeline when mounted.
+ *
+ * @example
+ * ```tsx
+ * <LockSelection
+ *   id="my-widget"
+ *   order={30}
+ *   selectedItems={selectedItems}
+ * />
+ * ```
+ */
+export function LockSelection({
+  id,
+  selectedItems,
+  order = 30,
+  labels,
+  Icon,
+  IconButtonProps,
+}: LockSelectionProps) {
+  const setWidget = useWidgetStore((state) => state.setWidget)
+  const registerTool = useWidgetStore((state) => state.registerTool)
+  const unregisterTool = useWidgetStore((state) => state.unregisterTool)
+  const setToolEnabled = useWidgetStore((state) => state.setToolEnabled)
+  const updateToolConfig = useWidgetStore((state) => state.updateToolConfig)
+
+  const storeIsLocked = useWidgetStore(
+    useShallow((state) => state.getWidget<LockSelectionState>(id)?.isLocked),
+  )
+
+  const isLocked = storeIsLocked ?? false
+  const lockedItems = useMemo(
+    () => (isLocked ? selectedItems : []),
+    [isLocked, selectedItems],
+  )
+
+  // Register tool on mount
+  useEffect(() => {
+    registerTool(id, {
+      id: LOCK_SELECTION_TOOL_ID,
+      order,
+      enabled: isLocked,
+      fn: (data, config) => {
+        const items = (config?.lockedItems as string[]) || []
+        if (items.length === 0) return data
+
+        return filterDataByLockedItems(data as EchartWidgetData, items)
+      },
+      config: { lockedItems },
+    })
+
+    return () => unregisterTool(id, LOCK_SELECTION_TOOL_ID)
+  }, [id, order, registerTool, unregisterTool, isLocked, lockedItems])
+
+  // Update enabled flag and config when they change
+  useEffect(() => {
+    setToolEnabled(id, LOCK_SELECTION_TOOL_ID, isLocked)
+    updateToolConfig(id, LOCK_SELECTION_TOOL_ID, { lockedItems })
+  }, [id, isLocked, lockedItems, setToolEnabled, updateToolConfig])
+
+  const handleToggle = useCallback(() => {
+    if (isLocked) {
+      // Unlock: clear locked items and disable tool
+      setWidget(id, {
+        isLocked: false,
+        lockedItems: [],
+      })
+    } else {
+      // Lock: save selected items and enable tool
+      setWidget(id, {
+        isLocked: true,
+        lockedItems: selectedItems,
+      })
+    }
+  }, [id, isLocked, selectedItems, setWidget])
+
+  // Don't render if no selections
+  if (selectedItems.length === 0) {
+    return null
+  }
+
+  const tooltipLabel = isLocked
+    ? (labels?.unlock ?? 'Unlock selection')
+    : (labels?.lock ?? 'Lock selection')
+
+  const ariaLabel = labels?.ariaLabel ?? tooltipLabel
+
+  return (
+    <Tooltip title={tooltipLabel}>
+      <IconButton
+        size='small'
+        aria-label={ariaLabel}
+        onClick={handleToggle}
+        sx={actionButtonStyles.trigger}
+        data-active={isLocked}
+        {...IconButtonProps}
+      >
+        {Icon ?? <CheckBoxOutlined fontSize='small' />}
+      </IconButton>
+    </Tooltip>
+  )
+}
+
+/**
+ * Filters widget data to only include items with names matching the locked items.
+ */
+function filterDataByLockedItems(
+  data: EchartWidgetData,
+  lockedItems: string[],
+): EchartWidgetData {
+  return data.map((series) =>
+    series.filter((item) => {
+      const name = item.name
+      return typeof name === 'string' && lockedItems.includes(name)
+    }),
+  )
+}

package/src/widgets/actions/lock-selection/types.ts

@@ -0,0 +1,41 @@
+import type { IconButtonProps } from '@mui/material'
+import type { ReactNode } from 'react'
+import type { BaseWidgetState } from '../../stores/types'
+
+/**
+ * Lock selection specific state properties.
+ */
+export interface LockSelectionStateProps {
+  /** Whether the selection is currently locked */
+  isLocked?: boolean
+}
+
+/**
+ * Widget state extension for lock selection functionality.
+ * Extends the base widget state with lock-specific properties.
+ */
+export type LockSelectionState<T = object> = BaseWidgetState<
+  T & LockSelectionStateProps
+>
+
+export interface LockSelectionProps {
+  /** Widget ID to store lock selection state */
+  id: string
+  /** Currently selected items (by name) */
+  selectedItems: string[]
+  /** Execution order in the tool pipeline. Lower values execute first. Defaults to 30. */
+  order?: number
+  /** Custom labels for the action */
+  labels?: {
+    /** Tooltip when unlocked (button will lock selection) */
+    lock?: string
+    /** Tooltip when locked (button will unlock selection) */
+    unlock?: string
+    /** Accessibility label */
+    ariaLabel?: string
+  }
+  /** Props passed to the IconButton component */
+  IconButtonProps?: IconButtonProps
+  /** Custom icon to display */
+  Icon?: ReactNode
+}

package/src/widgets/actions/relative-data/relative-data.test.tsx

@@ -0,0 +1,267 @@
+import { describe, test, expect, beforeEach } from 'vitest'
+import { render, screen, fireEvent, waitFor } from '@testing-library/react'
+import { RelativeData } from './relative-data'
+import { useWidgetStore } from '../../stores/widget-store'
+import type { EchartWidgetData } from '../../echart/types'
+import type { RelativeDataState } from './types'
+
+describe('RelativeData', () => {
+  const widgetId = 'test-relative-widget'
+
+  const mockData: EchartWidgetData = [
+    [
+      { category: 'A', value: 25 },
+      { category: 'B', value: 75 },
+    ],
+  ]
+
+  beforeEach(() => {
+    useWidgetStore.getState().clearWidgets()
+  })
+
+  test('renders relative data toggle button', () => {
+    render(<RelativeData id={widgetId} />)
+
+    const button = screen.getByRole('button')
+    expect(button).toBeTruthy()
+  })
+
+  test('shows relative tooltip when in absolute mode', () => {
+    render(<RelativeData id={widgetId} />)
+
+    const button = screen.getByRole('button', { name: 'Show relative values' })
+    expect(button).toBeTruthy()
+  })
+
+  test('toggles to relative mode and updates widget store with percentage values', async () => {
+    render(<RelativeData id={widgetId} />)
+
+    const button = screen.getByRole('button')
+    fireEvent.click(button)
+
+    // Execute the pipeline with the source data
+    await useWidgetStore.getState().executeToolPipeline(widgetId, mockData)
+
+    const widget = useWidgetStore.getState().getWidget(widgetId)
+    const data = widget?.data as EchartWidgetData
+
+    // Total is 100, so 25 becomes 25% and 75 becomes 75%
+    expect(data?.[0]?.[0]?.value).toBe(25)
+    expect(data?.[0]?.[1]?.value).toBe(75)
+    expect(data?.[0]?.[0]?.category).toBe('A')
+    expect(data?.[0]?.[1]?.category).toBe('B')
+  })
+
+  test('toggles back to absolute mode and restores original values', async () => {
+    render(<RelativeData id={widgetId} />)
+
+    const button = screen.getByRole('button')
+
+    // Toggle to relative
+    fireEvent.click(button)
+    await useWidgetStore.getState().executeToolPipeline(widgetId, mockData)
+
+    // Toggle back to absolute
+    fireEvent.click(button)
+    await useWidgetStore.getState().executeToolPipeline(widgetId, mockData)
+
+    const widget = useWidgetStore.getState().getWidget(widgetId)
+    const data = widget?.data as EchartWidgetData
+
+    expect(data?.[0]?.[0]?.value).toBe(25)
+    expect(data?.[0]?.[1]?.value).toBe(75)
+  })
+
+  test('has active state when in relative mode', () => {
+    render(<RelativeData id={widgetId} />)
+
+    const button = screen.getByRole('button')
+
+    expect(button.getAttribute('data-active')).toBe('false')
+
+    fireEvent.click(button)
+
+    expect(button.getAttribute('data-active')).toBe('true')
+  })
+
+  test('starts in relative mode when defaultIsRelative is true', () => {
+    render(<RelativeData id={widgetId} defaultIsRelative />)
+
+    const button = screen.getByRole('button')
+    expect(button.getAttribute('data-active')).toBe('true')
+
+    // Should show absolute tooltip when in relative mode
+    expect(button.getAttribute('aria-label')).toBe('Show absolute values')
+  })
+
+  test('initializes widget store with defaultIsRelative on mount', async () => {
+    render(<RelativeData id={widgetId} defaultIsRelative />)
+
+    await waitFor(() => {
+      const widget = useWidgetStore
+        .getState()
+        .getWidget<RelativeDataState>(widgetId)
+      expect(widget?.isRelative).toBe(true)
+    })
+  })
+
+  test('initializes widget store with false when defaultIsRelative is false', async () => {
+    render(<RelativeData id={widgetId} defaultIsRelative={false} />)
+
+    await waitFor(() => {
+      const widget = useWidgetStore
+        .getState()
+        .getWidget<RelativeDataState>(widgetId)
+      expect(widget?.isRelative).toBe(false)
+    })
+  })
+
+  test('uses custom labels when provided', () => {
+    const customLabels = {
+      relative: 'Switch to %',
+      absolute: 'Switch to numbers',
+      ariaLabel: 'Toggle data mode',
+    }
+
+    render(<RelativeData id={widgetId} labels={customLabels} />)
+
+    const button = screen.getByRole('button', { name: 'Toggle data mode' })
+    expect(button).toBeTruthy()
+  })
+
+  test('handles data with multiple series', async () => {
+    const multiSeriesData: EchartWidgetData = [
+      [
+        { name: 'X', count: 10 },
+        { name: 'Y', count: 20 },
+      ],
+      [
+        { name: 'X', count: 30 },
+        { name: 'Y', count: 40 },
+      ],
+    ]
+
+    render(<RelativeData id={widgetId} />)
+
+    const button = screen.getByRole('button')
+    fireEvent.click(button)
+
+    await useWidgetStore
+      .getState()
+      .executeToolPipeline(widgetId, multiSeriesData)
+
+    const widget = useWidgetStore.getState().getWidget(widgetId)
+    const data = widget?.data as EchartWidgetData
+
+    // Total is 100, so values become 10%, 20%, 30%, 40%
+    expect(data?.[0]?.[0]?.count).toBe(10)
+    expect(data?.[0]?.[1]?.count).toBe(20)
+    expect(data?.[1]?.[0]?.count).toBe(30)
+    expect(data?.[1]?.[1]?.count).toBe(40)
+  })
+
+  test('handles zero total gracefully', async () => {
+    const zeroData: EchartWidgetData = [
+      [
+        { category: 'A', value: 0 },
+        { category: 'B', value: 0 },
+      ],
+    ]
+
+    render(<RelativeData id={widgetId} />)
+
+    const button = screen.getByRole('button')
+    fireEvent.click(button)
+
+    await useWidgetStore.getState().executeToolPipeline(widgetId, zeroData)
+
+    const widget = useWidgetStore.getState().getWidget(widgetId)
+    const data = widget?.data as EchartWidgetData
+
+    // Should preserve original data when total is 0
+    expect(data?.[0]?.[0]?.value).toBe(0)
+    expect(data?.[0]?.[1]?.value).toBe(0)
+  })
+
+  test('preserves string values during transformation', async () => {
+    const mixedData: EchartWidgetData = [
+      [
+        { label: 'First', value: 50, extra: 'text' },
+        { label: 'Second', value: 50, extra: 'more' },
+      ],
+    ]
+
+    render(<RelativeData id={widgetId} />)
+
+    const button = screen.getByRole('button')
+    fireEvent.click(button)
+
+    await useWidgetStore.getState().executeToolPipeline(widgetId, mixedData)
+
+    const widget = useWidgetStore.getState().getWidget(widgetId)
+    const data = widget?.data as EchartWidgetData
+
+    expect(data?.[0]?.[0]?.label).toBe('First')
+    expect(data?.[0]?.[0]?.extra).toBe('text')
+    expect(data?.[0]?.[1]?.label).toBe('Second')
+    expect(data?.[0]?.[1]?.extra).toBe('more')
+  })
+
+  test('renders custom icon when provided', () => {
+    const customIcon = <span data-testid='custom-icon'>%</span>
+
+    render(<RelativeData id={widgetId} Icon={customIcon} />)
+
+    expect(screen.getByTestId('custom-icon')).toBeTruthy()
+  })
+
+  test('passes IconButtonProps to the button', () => {
+    render(<RelativeData id={widgetId} IconButtonProps={{ disabled: true }} />)
+
+    const button = screen.getByRole('button')
+    expect(button.hasAttribute('disabled')).toBeTruthy()
+  })
+
+  test('recalculates relative values when store data changes externally while in relative mode', async () => {
+    const initialData: EchartWidgetData = [
+      [
+        { category: 'A', value: 50 },
+        { category: 'B', value: 50 },
+      ],
+    ]
+
+    // Pre-populate the widget in the store with relative data
+    useWidgetStore.getState().setWidget(widgetId, {
+      data: initialData,
+      isRelative: true,
+    })
+
+    render(<RelativeData id={widgetId} defaultIsRelative />)
+
+    let widget
+    let data
+    await waitFor(() => {
+      widget = useWidgetStore.getState().getWidget(widgetId)
+      data = widget?.data as EchartWidgetData
+      // Initial data: 50/100 = 50%, 50/100 = 50%
+      expect(data?.[0]?.[0]?.value).toBe(50)
+      expect(data?.[0]?.[1]?.value).toBe(50)
+    })
+
+    // Simulate external store update with new absolute data
+    const newAbsoluteData: EchartWidgetData = [
+      [
+        { category: 'A', value: 25 },
+        { category: 'B', value: 75 },
+      ],
+    ]
+    useWidgetStore.getState().setWidget(widgetId, { data: newAbsoluteData })
+
+    // Component should detect external change and recalculate
+    // New data: 25/100 = 25%, 75/100 = 75%
+    widget = useWidgetStore.getState().getWidget(widgetId)
+    data = widget?.data as EchartWidgetData
+    expect(data?.[0]?.[0]?.value).toBe(25)
+    expect(data?.[0]?.[1]?.value).toBe(75)
+  })
+})