@carto/ps-react-ui 4.7.0 → 4.8.0

package/src/widgets-v2/actions/change-column/change-column.test.tsx

@@ -0,0 +1,59 @@
+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 { ChangeColumn } from './change-column'
+import type { ChangeColumnWidgetState } from './types'
+
+beforeEach(() => clearAllWidgetStores())
+afterEach(() => clearAllWidgetStores())
+
+const ITEMS = [
+  { id: 'a', label: 'Alpha' },
+  { id: 'b', label: 'Beta' },
+  { id: 'c', label: 'Gamma' },
+]
+
+describe('<ChangeColumn>', () => {
+  it('renders nothing when fewer than two columns are provided', () => {
+    const { container } = render(
+      <Provider id='cc1' data={[]}>
+        <ChangeColumn columns={[ITEMS[0]!]} />
+      </Provider>,
+    )
+    expect(container.querySelector('button')).toBeNull()
+  })
+
+  it('renders the trigger and opens the menu listing every column in order', () => {
+    render(
+      <Provider id='cc2' data={[]}>
+        <ChangeColumn columns={ITEMS} labels={{ trigger: 'Reorder' }} />
+      </Provider>,
+    )
+    fireEvent.click(screen.getByLabelText('Reorder'))
+    const items = screen.getAllByRole('menuitem')
+    expect(items.map((el) => el.textContent)).toEqual([
+      'Alpha',
+      'Beta',
+      'Gamma',
+    ])
+  })
+
+  it('uses columnOrder from the store when present', () => {
+    render(
+      <Provider id='cc3' data={[]}>
+        <ChangeColumn columns={ITEMS} labels={{ trigger: 'Reorder' }} />
+      </Provider>,
+    )
+    getWidgetStore('cc3').setState({
+      columnOrder: ['c', 'a', 'b'],
+    } as Partial<ChangeColumnWidgetState>)
+    fireEvent.click(screen.getByLabelText('Reorder'))
+    const items = screen.getAllByRole('menuitem')
+    expect(items.map((el) => el.textContent)).toEqual([
+      'Gamma',
+      'Alpha',
+      'Beta',
+    ])
+  })
+})

package/src/widgets-v2/actions/change-column/change-column.tsx

@@ -0,0 +1,180 @@
+import { useCallback, useMemo, useState, type ComponentType } from 'react'
+import {
+  DndContext,
+  KeyboardSensor,
+  PointerSensor,
+  closestCenter,
+  useSensor,
+  useSensors,
+  type DragEndEvent,
+} from '@dnd-kit/core'
+import {
+  SortableContext,
+  arrayMove,
+  sortableKeyboardCoordinates,
+  verticalListSortingStrategy,
+} from '@dnd-kit/sortable'
+import { IconButton, Menu, type SvgIconProps } from '@mui/material'
+import { Tooltip } from '../../../components'
+import { getWidgetStore, useWidget, useWidgetId } from '../../stores'
+import { ChangeColumnIcon } from './change-column-icon'
+import { DEFAULT_CHANGE_COLUMN_LABELS, type ChangeColumnLabels } from './labels'
+import { SortableColumnItem } from './sortable-column-item'
+import { styles } from './style'
+import type { ChangeColumnWidgetState } from './types'
+import type { ReactNode } from 'react'
+
+export interface ChangeColumnItem {
+  id: string
+  label: ReactNode
+}
+
+export interface ChangeColumnProps {
+  /**
+   * Master list of columns (id + label) in their default order. The current
+   * effective order is derived by combining this list with the widget's
+   * `columnOrder` extension state.
+   */
+  columns: readonly ChangeColumnItem[]
+  labels?: Partial<ChangeColumnLabels>
+  icon?: ComponentType<SvgIconProps>
+  iconProps?: SvgIconProps
+  dragHandleIcon?: ComponentType<SvgIconProps>
+}
+
+/**
+ * Action that lets users reorder columns via drag-and-drop. The new order is
+ * persisted on the widget store as `columnOrder` (an array of ids) on the
+ * {@link ChangeColumnWidgetState} extension. `<Table>` (and other column-aware
+ * bridges) merge that order with their own `columns` prop via
+ * `resolveColumns()` from the table primitives.
+ *
+ * Returns `null` when there are fewer than two columns to reorder.
+ */
+export function ChangeColumn({
+  columns,
+  labels,
+  icon: Icon = ChangeColumnIcon,
+  iconProps,
+  dragHandleIcon,
+}: ChangeColumnProps) {
+  const id = useWidgetId()
+  const _labels = { ...DEFAULT_CHANGE_COLUMN_LABELS, ...labels }
+  const [anchorEl, setAnchorEl] = useState<HTMLElement | null>(null)
+
+  const columnOrder = useWidget<
+    readonly string[] | undefined,
+    ChangeColumnWidgetState
+  >(id, (s) => s.columnOrder)
+
+  const orderedIds = useMemo(() => {
+    const masterIds = columns.map((c) => c.id)
+    if (!columnOrder || columnOrder.length === 0) return masterIds
+    // Set lookup so membership tests stay O(1) regardless of column count.
+    const masterIdSet = new Set(masterIds)
+    const seen = new Set<string>()
+    const out: string[] = []
+    for (const cid of columnOrder) {
+      if (masterIdSet.has(cid) && !seen.has(cid)) {
+        out.push(cid)
+        seen.add(cid)
+      }
+    }
+    for (const cid of masterIds) {
+      if (!seen.has(cid)) out.push(cid)
+    }
+    return out
+  }, [columnOrder, columns])
+
+  const orderedColumns = useMemo(() => {
+    const byId = new Map(columns.map((c) => [c.id, c]))
+    // Single pass instead of map().filter() — skips unknown ids inline.
+    const out: ChangeColumnItem[] = []
+    for (const cid of orderedIds) {
+      const c = byId.get(cid)
+      if (c != null) out.push(c)
+    }
+    return out
+  }, [orderedIds, columns])
+
+  const sensors = useSensors(
+    useSensor(PointerSensor),
+    useSensor(KeyboardSensor, {
+      coordinateGetter: sortableKeyboardCoordinates,
+    }),
+  )
+
+  const handleOpen = useCallback((e: React.MouseEvent<HTMLElement>) => {
+    e.stopPropagation()
+    setAnchorEl(e.currentTarget)
+  }, [])
+  const handleClose = useCallback(() => setAnchorEl(null), [])
+
+  const handleDragEnd = useCallback(
+    (event: DragEndEvent) => {
+      const { active, over } = event
+      if (!over || active.id === over.id) return
+      const oldIndex = orderedIds.indexOf(String(active.id))
+      const newIndex = orderedIds.indexOf(String(over.id))
+      if (oldIndex === -1 || newIndex === -1) return
+      const next = arrayMove([...orderedIds], oldIndex, newIndex)
+      getWidgetStore(id).setState({
+        columnOrder: next,
+      } as Partial<ChangeColumnWidgetState>)
+    },
+    [id, orderedIds],
+  )
+
+  if (columns.length < 2) return null
+
+  const isOpen = Boolean(anchorEl)
+
+  return (
+    <>
+      <Tooltip title={_labels.trigger}>
+        <IconButton
+          size='small'
+          aria-label={_labels.trigger}
+          aria-pressed={isOpen}
+          aria-haspopup='true'
+          aria-controls={isOpen ? 'change-column-menu' : undefined}
+          aria-expanded={isOpen ? 'true' : undefined}
+          onClick={handleOpen}
+          className={isOpen ? 'active' : undefined}
+          sx={{ ...styles.toggle, ...(isOpen && styles.toggleActive) }}
+        >
+          <Icon fontSize='small' {...iconProps} />
+        </IconButton>
+      </Tooltip>
+      <DndContext
+        sensors={sensors}
+        collisionDetection={closestCenter}
+        onDragEnd={handleDragEnd}
+      >
+        <Menu
+          id='change-column-menu'
+          anchorEl={anchorEl}
+          open={isOpen}
+          onClose={handleClose}
+          anchorOrigin={{ vertical: 'bottom', horizontal: 'right' }}
+          transformOrigin={{ vertical: 'top', horizontal: 'right' }}
+          slotProps={{ paper: { sx: styles.menuPaper } }}
+        >
+          <SortableContext
+            items={orderedIds}
+            strategy={verticalListSortingStrategy}
+          >
+            {orderedColumns.map((column) => (
+              <SortableColumnItem
+                key={column.id}
+                id={column.id}
+                label={column.label}
+                dragHandleIcon={dragHandleIcon}
+              />
+            ))}
+          </SortableContext>
+        </Menu>
+      </DndContext>
+    </>
+  )
+}

package/src/widgets-v2/actions/change-column/index.ts

@@ -0,0 +1,7 @@
+export {
+  ChangeColumn,
+  type ChangeColumnProps,
+  type ChangeColumnItem,
+} from './change-column'
+export { DEFAULT_CHANGE_COLUMN_LABELS, type ChangeColumnLabels } from './labels'
+export type { ChangeColumnWidgetState } from './types'

package/src/widgets-v2/actions/change-column/labels.ts

@@ -0,0 +1,9 @@
+export interface ChangeColumnLabels {
+  trigger: string
+  reset: string
+}
+
+export const DEFAULT_CHANGE_COLUMN_LABELS: ChangeColumnLabels = {
+  trigger: 'Change column order',
+  reset: 'Reset to default',
+}

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

@@ -0,0 +1,56 @@
+import { useSortable } from '@dnd-kit/sortable'
+import { CSS } from '@dnd-kit/utilities'
+import { ListItemText, MenuItem } from '@mui/material'
+import DragIndicatorIcon from '@mui/icons-material/DragIndicator'
+import type { ComponentType, ReactNode } from 'react'
+import type { SvgIconProps } from '@mui/material'
+import { styles } from './style'
+
+export interface SortableColumnItemProps {
+  id: string
+  label: ReactNode
+  dragHandleIcon?: ComponentType<SvgIconProps>
+}
+
+/**
+ * Draggable menu item used inside ChangeColumn's `<DndContext>`. Wraps a
+ * MUI `<MenuItem>` so it inherits keyboard / theming behavior, and exposes
+ * the dnd-kit listeners on the whole row so the user can grab anywhere on
+ * the row to reorder.
+ */
+export function SortableColumnItem({
+  id,
+  label,
+  dragHandleIcon: HandleIcon = DragIndicatorIcon,
+}: SortableColumnItemProps) {
+  const {
+    attributes,
+    listeners,
+    setNodeRef,
+    transform,
+    transition,
+    isDragging,
+  } = useSortable({ id })
+
+  const transformStyle = {
+    transform: CSS.Transform.toString(
+      transform ? { ...transform, x: 0 } : null,
+    ),
+    transition,
+  }
+
+  return (
+    <MenuItem
+      ref={setNodeRef}
+      style={transformStyle}
+      {...attributes}
+      {...listeners}
+      role='menuitem'
+      tabIndex={0}
+      sx={{ ...styles.item, ...(isDragging && styles.itemDragging) }}
+    >
+      <HandleIcon sx={styles.dragHandle} />
+      <ListItemText>{label}</ListItemText>
+    </MenuItem>
+  )
+}

package/src/widgets-v2/actions/change-column/style.ts

@@ -0,0 +1,32 @@
+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,
+  },
+  menuPaper: {
+    overflow: 'hidden',
+    minWidth: 220,
+  },
+  item: {
+    cursor: 'grab',
+    '&:focus-visible': {
+      outline: '2px solid',
+      outlineColor: 'primary.main',
+      outlineOffset: -2,
+    },
+  },
+  itemDragging: {
+    opacity: 0.5,
+    cursor: 'grabbing',
+  },
+  dragHandle: {
+    color: 'text.secondary',
+    mr: 1,
+    fontSize: 18,
+  },
+} satisfies Record<string, SxProps<Theme>>

package/src/widgets-v2/actions/change-column/types.ts

@@ -0,0 +1,11 @@
+import type { WidgetState } from '../../stores'
+
+/**
+ * State extension owned by the ChangeColumn action. Stored on the per-widget
+ * Zustand store; read by `<Table>` (and any other column-aware bridge) to
+ * resolve the effective column order.
+ */
+export interface ChangeColumnWidgetState extends WidgetState {
+  /** Ordered list of column ids. Empty / unset means "use props order". */
+  columnOrder?: readonly string[]
+}

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

@@ -0,0 +1,327 @@
+import { describe, it, expect, vi } from 'vitest'
+import { fireEvent, render, screen, waitFor } from '@testing-library/react'
+import { Download } from './download'
+import type { DownloadItem } from './types'
+import * as exports from './exports'
+
+function fakeItem(overrides?: Partial<DownloadItem>): DownloadItem {
+  return {
+    id: 'csv',
+    label: 'Download as CSV',
+    resolve: () =>
+      Promise.resolve({
+        url: 'blob:fake',
+        filename: 'data.csv',
+        revoke: vi.fn(),
+      }),
+    ...overrides,
+  }
+}
+
+describe('<Download>', () => {
+  it('renders a trigger and lists every item when opened', () => {
+    render(
+      <Download
+        items={[
+          fakeItem({ id: 'csv', label: 'Download CSV' }),
+          fakeItem({ id: 'png', label: 'Download PNG' }),
+        ]}
+      />,
+    )
+    fireEvent.click(screen.getByRole('button', { name: 'Download' }))
+    expect(screen.getByText('Download CSV')).toBeTruthy()
+    expect(screen.getByText('Download PNG')).toBeTruthy()
+  })
+
+  it('honors custom trigger label', () => {
+    render(
+      <Download items={[fakeItem()]} labels={{ trigger: 'Save to disk' }} />,
+    )
+    expect(screen.getByRole('button', { name: 'Save to disk' })).toBeTruthy()
+  })
+
+  it('selecting an item calls its resolve(); the menu then closes', async () => {
+    const resolve = vi.fn(() =>
+      Promise.resolve({
+        url: 'blob:abc',
+        filename: 'x.csv',
+        revoke: vi.fn(),
+      }),
+    )
+    render(<Download items={[fakeItem({ resolve })]} />)
+    fireEvent.click(screen.getByRole('button', { name: 'Download' }))
+    fireEvent.click(screen.getByText('Download as CSV'))
+    expect(resolve).toHaveBeenCalledTimes(1)
+    // Wait a tick for the resolve promise to settle.
+    await Promise.resolve()
+  })
+
+  it('renders a custom icon component when provided', () => {
+    function CustomIcon(props: React.SVGProps<SVGSVGElement>) {
+      return <svg data-testid='custom-dl-icon' {...props} />
+    }
+    render(<Download items={[fakeItem()]} icon={CustomIcon} />)
+    expect(screen.getByTestId('custom-dl-icon')).toBeTruthy()
+  })
+
+  it('renders a per-item leading icon inside ListItemIcon', () => {
+    render(
+      <Download
+        items={[
+          fakeItem({
+            icon: <svg data-testid='item-icon' />,
+          }),
+        ]}
+      />,
+    )
+    fireEvent.click(screen.getByRole('button', { name: 'Download' }))
+    const icon = screen.getByTestId('item-icon')
+    expect(icon.closest('.MuiListItemIcon-root')).not.toBeNull()
+  })
+
+  it('disables the menu item when the item is `disabled` and skips resolve()', () => {
+    const resolve = vi.fn(() =>
+      Promise.resolve({ url: 'blob:abc', filename: 'x.csv' }),
+    )
+    render(
+      <Download
+        items={[fakeItem({ id: 'csv', label: 'CSV', disabled: true, resolve })]}
+      />,
+    )
+    fireEvent.click(screen.getByRole('button', { name: 'Download' }))
+    const menuItem = screen.getByText('CSV').closest('li')
+    expect(menuItem?.getAttribute('aria-disabled')).toBe('true')
+    fireEvent.click(screen.getByText('CSV'))
+    expect(resolve).not.toHaveBeenCalled()
+  })
+
+  it('overrides the resolved filename when `item.filename` is set', async () => {
+    const trigger = vi
+      .spyOn(exports, 'triggerLinkDownload')
+      .mockImplementation(() => undefined)
+    try {
+      render(
+        <Download
+          items={[
+            fakeItem({
+              id: 'csv',
+              label: 'CSV',
+              filename: 'override.csv',
+              resolve: () =>
+                Promise.resolve({ url: 'blob:fake', filename: 'auto.csv' }),
+            }),
+          ]}
+        />,
+      )
+      fireEvent.click(screen.getByRole('button', { name: 'Download' }))
+      fireEvent.click(screen.getByText('CSV'))
+      // wait for the resolve() promise to settle
+      await Promise.resolve()
+      await Promise.resolve()
+      expect(trigger).toHaveBeenCalledWith({
+        url: 'blob:fake',
+        filename: 'override.csv',
+      })
+    } finally {
+      trigger.mockRestore()
+    }
+  })
+
+  it('uses the resolved filename when `item.filename` is not set', async () => {
+    const trigger = vi
+      .spyOn(exports, 'triggerLinkDownload')
+      .mockImplementation(() => undefined)
+    try {
+      render(
+        <Download
+          items={[
+            fakeItem({
+              id: 'csv',
+              label: 'CSV',
+              resolve: () =>
+                Promise.resolve({ url: 'blob:fake', filename: 'auto.csv' }),
+            }),
+          ]}
+        />,
+      )
+      fireEvent.click(screen.getByRole('button', { name: 'Download' }))
+      fireEvent.click(screen.getByText('CSV'))
+      await Promise.resolve()
+      await Promise.resolve()
+      expect(trigger).toHaveBeenCalledWith({
+        url: 'blob:fake',
+        filename: 'auto.csv',
+      })
+    } finally {
+      trigger.mockRestore()
+    }
+  })
+
+  it('shows a spinner and disables the trigger while resolve() is pending; clears once it settles', async () => {
+    const trigger = vi
+      .spyOn(exports, 'triggerLinkDownload')
+      .mockImplementation(() => undefined)
+    let releaseResolve: (v: {
+      url: string
+      filename: string
+      revoke?: () => void
+    }) => void = () => undefined
+    const pending = new Promise<{
+      url: string
+      filename: string
+      revoke?: () => void
+    }>((res) => {
+      releaseResolve = res
+    })
+    try {
+      render(
+        <Download
+          items={[
+            fakeItem({ id: 'csv', label: 'CSV', resolve: () => pending }),
+          ]}
+        />,
+      )
+      const triggerBtn = screen.getByRole('button', { name: 'Download' })
+      fireEvent.click(triggerBtn)
+      fireEvent.click(screen.getByText('CSV'))
+
+      // In flight: trigger label and aria-busy switch, button is disabled,
+      // wrapper hover-fade `.active` className is applied, spinner is shown.
+      const busyBtn = screen.getByRole('button', { name: 'Downloading…' })
+      expect(busyBtn.getAttribute('aria-busy')).toBe('true')
+      expect((busyBtn as HTMLButtonElement).disabled).toBe(true)
+      expect(busyBtn.className).toMatch(/\bactive\b/)
+      expect(busyBtn.querySelector('[role="progressbar"]')).not.toBeNull()
+
+      // Settle the resolve and wait for the trigger to flip back to idle.
+      releaseResolve({ url: 'blob:fake', filename: 'data.csv' })
+      const idleBtn = await screen.findByRole('button', { name: 'Download' })
+      expect(idleBtn.getAttribute('aria-busy')).toBeNull()
+      expect((idleBtn as HTMLButtonElement).disabled).toBe(false)
+      expect(idleBtn.querySelector('[role="progressbar"]')).toBeNull()
+    } finally {
+      trigger.mockRestore()
+    }
+  })
+
+  it('clears the spinner when resolve() rejects and fires onError', async () => {
+    const onError = vi.fn()
+    render(
+      <Download
+        onError={onError}
+        items={[
+          fakeItem({
+            id: 'csv',
+            label: 'CSV',
+            resolve: () => Promise.reject(new Error('boom')),
+          }),
+        ]}
+      />,
+    )
+    fireEvent.click(screen.getByRole('button', { name: 'Download' }))
+    fireEvent.click(screen.getByText('CSV'))
+    // After the rejection the trigger label flips to the error label and
+    // `data-error` is set; the spinner is cleared and the button is enabled.
+    const errBtn = await screen.findByRole('button', {
+      name: 'Download failed',
+    })
+    expect((errBtn as HTMLButtonElement).disabled).toBe(false)
+    expect(errBtn.querySelector('[role="progressbar"]')).toBeNull()
+    expect(errBtn.getAttribute('data-error')).toBe('true')
+    await waitFor(() => expect(onError).toHaveBeenCalledTimes(1))
+    const first = onError.mock.calls[0]?.[0] as Error | undefined
+    expect(first).toBeInstanceOf(Error)
+    expect(first?.message).toBe('boom')
+  })
+
+  it('normalises non-Error rejections into a real Error before onError', async () => {
+    const onError = vi.fn()
+    render(
+      <Download
+        onError={onError}
+        items={[
+          fakeItem({
+            id: 'csv',
+            label: 'CSV',
+            // eslint-disable-next-line @typescript-eslint/prefer-promise-reject-errors
+            resolve: () => Promise.reject('non-error-value'),
+          }),
+        ]}
+      />,
+    )
+    fireEvent.click(screen.getByRole('button', { name: 'Download' }))
+    fireEvent.click(screen.getByText('CSV'))
+    await screen.findByRole('button', { name: 'Download failed' })
+    const first = onError.mock.calls[0]?.[0] as Error | undefined
+    expect(first).toBeInstanceOf(Error)
+    expect(first?.message).toBe('non-error-value')
+  })
+
+  it('clears the error state when the menu is re-opened', async () => {
+    render(
+      <Download
+        items={[
+          fakeItem({
+            id: 'csv',
+            label: 'CSV',
+            resolve: () => Promise.reject(new Error('boom')),
+          }),
+        ]}
+      />,
+    )
+    fireEvent.click(screen.getByRole('button', { name: 'Download' }))
+    fireEvent.click(screen.getByText('CSV'))
+    const errBtn = await screen.findByRole('button', {
+      name: 'Download failed',
+    })
+    fireEvent.click(errBtn)
+    // After re-open the trigger flips back to the idle label and data-error
+    // is gone. The menu is now open so we look up the trigger by its
+    // aria-haspopup attribute rather than its role+name (other body nodes
+    // get aria-hidden while the menu is open).
+    await waitFor(() => {
+      const btn = document.querySelector('button[aria-haspopup="true"]')
+      expect(btn).not.toBeNull()
+      expect(btn?.getAttribute('data-error')).toBeNull()
+      expect(btn?.getAttribute('aria-label')).toBe('Download')
+    })
+  })
+
+  it('defers revoke past the current task so the browser can dispatch the download', async () => {
+    const trigger = vi
+      .spyOn(exports, 'triggerLinkDownload')
+      .mockImplementation(() => undefined)
+    const setTimeoutSpy = vi.spyOn(window, 'setTimeout')
+    const revoke = vi.fn()
+    try {
+      render(
+        <Download
+          items={[
+            fakeItem({
+              id: 'csv',
+              label: 'CSV',
+              resolve: () =>
+                Promise.resolve({
+                  url: 'blob:abc',
+                  filename: 'data.csv',
+                  revoke,
+                }),
+            }),
+          ]}
+        />,
+      )
+      fireEvent.click(screen.getByRole('button', { name: 'Download' }))
+      fireEvent.click(screen.getByText('CSV'))
+      // Trigger fires inside the resolve callback; revoke is scheduled via
+      // setTimeout(_, 0) rather than invoked inline. Wait until the trigger
+      // call has happened — at that point revoke must be scheduled, not run.
+      await waitFor(() => expect(trigger).toHaveBeenCalledTimes(1))
+      expect(setTimeoutSpy).toHaveBeenCalledWith(revoke, 0)
+      // After the queued timeout drains, revoke actually runs.
+      await waitFor(() => expect(revoke).toHaveBeenCalledTimes(1))
+    } finally {
+      trigger.mockRestore()
+      setTimeoutSpy.mockRestore()
+    }
+  })
+})