@carto/ps-react-ui 4.4.0-chat-ui.6 → 4.4.0-chat-ui.7

package/src/widgets/actions/change-column/sortable-column-item.test.tsx

@@ -0,0 +1,124 @@
+/**
+ * Tests for SortableColumnItem — a DnD-kit sortable menu item.
+ *
+ * `useSortable` is mocked so we can drive isDragging / transform independently
+ * and exercise the conditional style branches without spinning up a real
+ * DndContext + SortableContext.
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { render } from '@testing-library/react'
+
+// Mock @dnd-kit/sortable's useSortable. Tests can override the return value
+// per-test via setSortableReturn.
+interface SortableReturn {
+  attributes: Record<string, unknown>
+  listeners: Record<string, unknown>
+  setNodeRef: (el: HTMLElement | null) => void
+  transform: { x: number; y: number; scaleX: number; scaleY: number } | null
+  transition: string | undefined
+  isDragging: boolean
+}
+
+let sortableReturn: SortableReturn = {
+  attributes: { 'aria-roledescription': 'sortable' },
+  listeners: {},
+  setNodeRef: () => undefined,
+  transform: null,
+  transition: undefined,
+  isDragging: false,
+}
+
+const setSortableReturn = (overrides: Partial<SortableReturn>) => {
+  sortableReturn = { ...sortableReturn, ...overrides }
+}
+
+vi.mock('@dnd-kit/sortable', () => ({
+  useSortable: () => sortableReturn,
+}))
+
+import { SortableColumnItem } from './sortable-column-item'
+import type { TableColumn } from '../../table/types'
+
+const baseColumn: TableColumn = {
+  id: 'col-1',
+  label: 'Name',
+}
+
+beforeEach(() => {
+  // Reset to defaults so each test starts clean.
+  sortableReturn = {
+    attributes: { 'aria-roledescription': 'sortable' },
+    listeners: {},
+    setNodeRef: () => undefined,
+    transform: null,
+    transition: undefined,
+    isDragging: false,
+  }
+})
+
+describe('SortableColumnItem', () => {
+  it('renders the column label', () => {
+    const { getByText } = render(<SortableColumnItem column={baseColumn} />)
+    expect(getByText('Name')).toBeDefined()
+  })
+
+  it('renders as a menuitem role', () => {
+    const { getByRole } = render(<SortableColumnItem column={baseColumn} />)
+    expect(getByRole('menuitem')).toBeDefined()
+  })
+
+  it('applies grab cursor + opacity=1 when not dragging', () => {
+    setSortableReturn({ isDragging: false })
+    const { getByRole } = render(<SortableColumnItem column={baseColumn} />)
+    const item = getByRole('menuitem')
+    expect(item.style.cursor).toBe('grab')
+    expect(item.style.opacity).toBe('1')
+  })
+
+  it('applies grabbing cursor + opacity=0.5 when dragging', () => {
+    setSortableReturn({ isDragging: true })
+    const { getByRole } = render(<SortableColumnItem column={baseColumn} />)
+    const item = getByRole('menuitem')
+    expect(item.style.cursor).toBe('grabbing')
+    expect(item.style.opacity).toBe('0.5')
+  })
+
+  it('forces transform.x to 0 when transform is non-null (vertical-only drag)', () => {
+    setSortableReturn({
+      transform: { x: 50, y: 20, scaleX: 1, scaleY: 1 },
+      transition: 'transform 200ms ease',
+    })
+    const { getByRole } = render(<SortableColumnItem column={baseColumn} />)
+    const item = getByRole('menuitem')
+    // CSS.Transform.toString({x: 0, y: 20, ...}) → 'translate3d(0px, 20px, 0)'
+    expect(item.style.transform).toContain('0px')
+    expect(item.style.transform).toContain('20px')
+  })
+
+  it('handles a null transform (no drag offset applied)', () => {
+    setSortableReturn({ transform: null })
+    const { getByRole } = render(<SortableColumnItem column={baseColumn} />)
+    const item = getByRole('menuitem')
+    // CSS.Transform.toString(null) is undefined → no transform attr
+    expect(item.style.transform).toBe('')
+  })
+
+  it('threads dnd-kit attributes onto the rendered element', () => {
+    setSortableReturn({
+      attributes: { 'aria-roledescription': 'draggable column' },
+    })
+    const { getByRole } = render(<SortableColumnItem column={baseColumn} />)
+    expect(getByRole('menuitem').getAttribute('aria-roledescription')).toBe(
+      'draggable column',
+    )
+  })
+
+  it('renders a column with a ReactNode label', () => {
+    const column: TableColumn = {
+      id: 'col-x',
+      label: <span data-testid='custom-label'>Custom</span>,
+    }
+    const { getByTestId } = render(<SortableColumnItem column={column} />)
+    expect(getByTestId('custom-label')).toBeDefined()
+  })
+})

package/src/widgets/actions/change-column/sortable-column-item.tsx

@@ -22,7 +22,9 @@ export function SortableColumnItem({ column }: SortableColumnItemProps) {
   } = useSortable({ id: column.id })
 
   const style = {
-    transform: CSS.Transform.toString(transform),
+    transform: CSS.Transform.toString(
+      transform ? { ...transform, x: 0 } : null,
+    ),
     transition,
     opacity: isDragging ? 0.5 : 1,
     cursor: isDragging ? 'grabbing' : 'grab',

package/src/widgets/actions/download/download.test.tsx

@@ -1,7 +1,7 @@
 import { describe, test, expect, beforeEach, vi } from 'vitest'
 import { render, screen, fireEvent, waitFor } from '@testing-library/react'
 import { Download } from './download'
-import { useWidgetStore } from '../../../widgets'
+import { useWidgetStore } from '../../../widgets/stores'
 import type { DownloadItem } from './types'
 
 describe('Download', () => {

package/src/widgets/actions/download/download.tsx

@@ -9,11 +9,21 @@ import {
 import type { DownloadItem, DownloadProps } from './types'
 import { FileDownloadOutlined } from '@mui/icons-material'
 import { useState, type MouseEvent } from 'react'
-import { useWidgetStore } from '../../../widgets'
-import { useShallow } from 'zustand/shallow'
+import { useWidgetSelector } from '../../stores/use-widget-selector'
 
 const EMPTY_LABELS: NonNullable<DownloadProps['labels']> = {}
 
+/**
+ * Dropdown menu action for exporting widget data in various formats (CSV, PNG, etc.).
+ *
+ * Reads widget data from the store and triggers downloads using the modifier
+ * function defined in each `DownloadItem`.
+ *
+ * @example
+ * ```tsx
+ * <Download id={widgetId} items={barDownloadConfig({ refUI })} />
+ * ```
+ */
 export function Download({
   id,
   items,
@@ -21,7 +31,9 @@ export function Download({
   Icon,
   IconButtonProps,
 }: DownloadProps) {
-  const data = useWidgetStore(useShallow((state) => state.getWidget(id)?.data))
+  const { data } = useWidgetSelector(id, (w) => ({
+    data: w?.data,
+  }))
 
   const [isDownloading, setIsDownloading] = useState(false)
   const [anchorEl, setAnchorEl] = useState<null | HTMLElement>(null)

package/src/widgets/actions/download/exports.tsx

@@ -28,6 +28,12 @@ async function downloadFileToCSV<D>(data: D[][]) {
   return Promise.resolve(URL.createObjectURL(blob))
 }
 
+/**
+ * Pre-configured download item for exporting widget data as a CSV file.
+ *
+ * Converts a 2D array of data into CSV format with proper escaping and
+ * triggers a browser download. Revokes the object URL after download.
+ */
 export const downloadToCSV: DownloadItem<unknown[][]> = {
   id: 'csv',
   label: 'CSV',
@@ -91,6 +97,15 @@ async function downloadFileToPNG(ref: Ref<HTMLElement | null> | undefined) {
   return Promise.resolve(result)
 }
 
+/**
+ * Pre-configured download item for exporting a widget as a PNG image.
+ *
+ * Uses html2canvas to capture the widget DOM element referenced by a React ref.
+ * Strips toolbar and action elements before capturing.
+ *
+ * @remarks
+ * The modifier expects a React ref to the widget's root HTML element, not raw data.
+ */
 export const downloadToPNG: Omit<DownloadItem, 'modifier'> & {
   modifier: (
     ref: Ref<HTMLElement | null> | undefined,

package/src/widgets/actions/fullscreen/fullscreen.tsx

@@ -5,7 +5,8 @@ import {
   IconButton,
   Typography,
 } from '@mui/material'
-import { useWidgetStore } from '../../stores/widget-store'
+import { widgetStoreActions } from '../../stores/widget-store'
+import { useWidgetSelector } from '../../stores/use-widget-selector'
 import { Close, FullscreenOutlined } from '@mui/icons-material'
 import type {
   FullScreenConfig,
@@ -13,12 +14,24 @@ import type {
   FullScreenState,
 } from './types'
 import { styles } from './styles'
-import { useShallow } from 'zustand/shallow'
 
 const EMPTY_DIALOG_CONTENT_PROPS: NonNullable<
   FullScreenProps['DialogContentProps']
 > = {}
 
+/**
+ * Displays widget content in a fullscreen modal dialog.
+ *
+ * Manages fullscreen state via the widget store and renders a MUI Dialog
+ * with the widget title and a close button.
+ *
+ * @example
+ * ```tsx
+ * <FullScreen id="my-widget" labels={{ ariaLabel: 'Expand chart' }}>
+ *   <ChartContent id="my-widget" />
+ * </FullScreen>
+ * ```
+ */
 export function FullScreen({
   id,
   labels,
@@ -31,16 +44,12 @@ export function FullScreen({
   } = EMPTY_DIALOG_CONTENT_PROPS,
   DialogProps,
 }: FullScreenProps) {
-  const isFullScreen = useWidgetStore(
-    useShallow((state) => state.getWidget<FullScreenState>(id)?.isFullScreen),
-  )
-  const title = useWidgetStore(
-    useShallow((state) => state.getWidget<FullScreenState>(id)?.title),
-  )
-  const setWidget = useWidgetStore((state) => state.setWidget)
-
+  const { isFullScreen, title } = useWidgetSelector(id, (w) => ({
+    isFullScreen: (w as FullScreenState | undefined)?.isFullScreen,
+    title: (w as FullScreenState | undefined)?.title,
+  }))
   const updateFullScreenConfig = (updates: Partial<FullScreenConfig>) => {
-    setWidget<FullScreenState>(id, {
+    widgetStoreActions.setWidget<FullScreenState>(id, {
       isFullScreen: updates.isFullScreen,
     })
   }

package/src/widgets/actions/index.ts

@@ -1,6 +1,10 @@
 /* Fullscreen Widget */
 export { FullScreen } from './fullscreen/fullscreen'
-export type { FullScreenState, FullScreenConfig } from './fullscreen/types'
+export type {
+  FullScreenState,
+  FullScreenConfig,
+  FullScreenProps,
+} from './fullscreen/types'
 
 /* Download Widget */
 export { Download } from './download/download'
@@ -11,8 +15,12 @@ export { downloadToCSV, downloadToPNG } from './download/exports'
 export {
   RelativeData,
   RELATIVE_DATA_TOOL_ID,
+  RELATIVE_DATA_CONFIG_TOOL_ID,
 } from './relative-data/relative-data'
-export type { RelativeDataProps } from './relative-data/types'
+export type {
+  RelativeDataProps,
+  RelativeDataState,
+} from './relative-data/types'
 
 /* Zoom Toggle Widget */
 export { ZoomToggle, ZOOM_TOGGLE_TOOL_ID } from './zoom-toggle/zoom-toggle'
@@ -34,6 +42,7 @@ export type {
   SearcherProps,
   SearcherFilterFn,
   SearcherState,
+  SearcherStateProps,
 } from './searcher/types'
 
 /* Change Column Widget */
@@ -51,4 +60,14 @@ export {
 export type {
   LockSelectionProps,
   LockSelectionState,
+  LockSelectionStateProps,
 } from './lock-selection/types'
+
+/* Brush Toggle Widget */
+export { BrushToggle, BRUSH_TOGGLE_TOOL_ID } from './brush-toggle/brush-toggle'
+export type {
+  BrushToggleProps,
+  BrushState,
+  BrushConfig,
+  BrushSelectedItems,
+} from './brush-toggle/types'

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

@@ -3,6 +3,7 @@ import { render, screen, fireEvent } from '@testing-library/react'
 import { LockSelection, LOCK_SELECTION_TOOL_ID } 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
@@ -110,6 +111,19 @@ describe('LockSelection', () => {
     expect(tool?.enabled).toBe(false)
   })
 
+  test('clears lock state when selectedItems becomes empty while locked', () => {
+    // Simulate remount: isLocked persists in store but selectedItems is now empty
+    useWidgetStore
+      .getState()
+      .setWidget(widgetId, { isLocked: true, lockedItems: ['Electronics'] })
+
+    render(<LockSelection id={widgetId} selectedItems={[]} />)
+
+    const widget = useWidgetStore.getState().getWidget(widgetId)
+    expect((widget as LockSelectionState | undefined)?.isLocked).toBe(false)
+    expect((widget as LockSelectionState | undefined)?.lockedItems).toEqual([])
+  })
+
   test('has active state when locked', () => {
     render(<LockSelection id={widgetId} selectedItems={['Electronics']} />)
 

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

@@ -1,11 +1,11 @@
 import { IconButton } from '@mui/material'
 import { CheckBoxOutlined } from '@mui/icons-material'
-import { useCallback, useEffect, useMemo } from 'react'
+import { useCallback, useEffect } 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 { widgetStoreActions } from '../../stores/widget-store'
+import { useWidgetSelector } from '../../stores/use-widget-selector'
 import type { EchartWidgetData } from '../../echart/types'
 
 export const LOCK_SELECTION_TOOL_ID = 'lock-selection'
@@ -34,61 +34,56 @@ export function LockSelection({
   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 { storeIsLocked } = useWidgetSelector(id, (w) => ({
+    storeIsLocked: (w as LockSelectionState | undefined)?.isLocked,
+  }))
 
   const isLocked = storeIsLocked ?? false
-  const lockedItems = useMemo(
-    () => (isLocked ? selectedItems : []),
-    [isLocked, selectedItems],
-  )
 
-  // Register tool on mount
+  // Register tool once — fn reads lockedItems from the store at execution time
   useEffect(() => {
-    registerTool(id, {
+    widgetStoreActions.registerTool(id, {
       id: LOCK_SELECTION_TOOL_ID,
       order,
-      enabled: isLocked,
-      fn: (data, config) => {
-        const items = (config?.lockedItems as string[]) || []
+      enabled: false,
+      fn: (data) => {
+        const widget = widgetStoreActions.getWidget<LockSelectionState>(id)
+        const items = widget?.lockedItems ?? []
         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])
+    return () => widgetStoreActions.unregisterTool(id, LOCK_SELECTION_TOOL_ID)
+  }, [id, order])
 
-  // Update enabled flag and config when they change
+  // Sync enabled from store — lightweight, no re-registration.
+  // When selectedItems is empty (e.g., remount with no active selection),
+  // disable the tool and clear stale lock state.
   useEffect(() => {
-    setToolEnabled(id, LOCK_SELECTION_TOOL_ID, isLocked)
-    updateToolConfig(id, LOCK_SELECTION_TOOL_ID, { lockedItems })
-  }, [id, isLocked, lockedItems, setToolEnabled, updateToolConfig])
+    if (isLocked && selectedItems.length === 0) {
+      widgetStoreActions.setWidget(id, { isLocked: false, lockedItems: [] })
+      return
+    }
+    widgetStoreActions.setToolEnabled(id, LOCK_SELECTION_TOOL_ID, isLocked)
+  }, [id, isLocked, selectedItems.length])
 
   const handleToggle = useCallback(() => {
     if (isLocked) {
       // Unlock: clear locked items and disable tool
-      setWidget(id, {
+      widgetStoreActions.setWidget(id, {
         isLocked: false,
         lockedItems: [],
       })
     } else {
       // Lock: save selected items and enable tool
-      setWidget(id, {
+      widgetStoreActions.setWidget(id, {
         isLocked: true,
         lockedItems: selectedItems,
       })
     }
-  }, [id, isLocked, selectedItems, setWidget])
+  }, [id, isLocked, selectedItems])
 
   // Don't render if no selections
   if (selectedItems.length === 0) {

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

@@ -38,4 +38,6 @@ export interface LockSelectionProps {
 export interface LockSelectionStateProps {
   /** Whether the selection is currently locked */
   isLocked?: boolean
+  /** Items locked for filtering */
+  lockedItems?: string[]
 }