@carto/ps-react-ui 4.3.3 → 4.3.5

package/src/widgets/_shared/chart-config/csv-modifiers.ts

@@ -0,0 +1,56 @@
+/**
+ * Shared CSV export modifiers for chart widgets
+ */
+
+/**
+ * Flattens object array data into CSV-ready rows.
+ * Used by bar, pie, histogram, and timeseries widgets.
+ *
+ * @param data - Array of series, where each series is an array of data objects
+ * @returns CSV rows with headers and values
+ */
+export function flattenObjectArrayToCSV<T extends Record<string, unknown>>(
+  data: T[][],
+): string[][] {
+  const rows: string[][] = []
+
+  // Add headers from first data point if available
+  if (data.length > 0 && (data[0]?.length ?? 0) > 0) {
+    const firstDataPoint = data?.[0]?.[0] ?? {}
+    const headers = Object.keys(firstDataPoint)
+    rows.push(headers)
+  }
+
+  // Add data rows from all series
+  data.forEach((series) => {
+    series.forEach((dataPoint) => {
+      const values = Object.values(dataPoint).map((v) => String(v))
+      rows.push(values)
+    })
+  })
+
+  return rows
+}
+
+/**
+ * Creates CSV rows for scatterplot data.
+ * Scatterplot uses array format [x, y] instead of objects.
+ *
+ * @param data - Array of series, where each series is an array of [x, y] tuples
+ * @returns CSV rows with ['x', 'y'] headers
+ */
+export function scatterplotDataToCSV(data: number[][][]): string[][] {
+  const rows: string[][] = []
+
+  // Add headers
+  rows.push(['x', 'y'])
+
+  // Add data rows from all series
+  data.forEach((series) => {
+    series.forEach((dataPoint) => {
+      rows.push([String(dataPoint[0]), String(dataPoint[1])])
+    })
+  })
+
+  return rows
+}

package/src/widgets/_shared/chart-config/index.ts

@@ -0,0 +1,21 @@
+/**
+ * Shared utilities for chart widget configuration
+ */
+
+export { createChartWidgetConfig } from './config-factory'
+export type {
+  ChartWidgetBaseConfig,
+  CreateChartWidgetConfigParams,
+} from './config-factory'
+
+export { flattenObjectArrayToCSV, scatterplotDataToCSV } from './csv-modifiers'
+
+export {
+  buildLegendConfig,
+  buildGridConfig,
+  createTooltipPositioner,
+  createAxisLabelFormatter,
+  createTooltipFormatter,
+  applyXAxisFormatter,
+  applyYAxisFormatter,
+} from './option-builders'

package/src/widgets/_shared/chart-config/option-builders.ts

@@ -0,0 +1,203 @@
+import type { Theme } from '@mui/material'
+import type { LegendComponentOption } from 'echarts'
+import type {
+  CallbackDataParams,
+  TopLevelFormatterParams,
+} from 'node_modules/echarts/types/dist/shared'
+
+/**
+ * Shared EChart configuration builders for chart widgets
+ */
+
+/**
+ * Builds standard legend configuration for chart widgets
+ *
+ * @param hasLegend - Whether to show the legend
+ * @returns Legend configuration object
+ */
+export function buildLegendConfig(hasLegend: boolean): LegendComponentOption {
+  return {
+    show: hasLegend,
+    icon: 'circle' as const,
+    left: 0,
+    bottom: 0,
+    orient: 'horizontal',
+    type: 'scroll',
+  }
+}
+
+/**
+ * Builds standard grid configuration with legend-aware spacing
+ *
+ * @param hasLegend - Whether the chart has a legend
+ * @param theme - MUI theme for spacing
+ * @param additionalConfig - Additional grid configuration to merge
+ * @returns Grid configuration object
+ */
+export function buildGridConfig(hasLegend: boolean, theme: Theme) {
+  return {
+    ...(!hasLegend && { bottom: parseInt(theme.spacing(3)) }),
+    ...(hasLegend && { bottom: parseInt(theme.spacing(7)) }),
+  }
+}
+
+/**
+ * Creates a tooltip position calculator that handles overflow
+ * Used by bar, histogram, and scatterplot widgets
+ *
+ * @param theme - MUI theme for spacing
+ * @returns Tooltip position function
+ */
+export function createTooltipPositioner(theme: Theme) {
+  return function (
+    point: [number, number],
+    _params: unknown,
+    _dom: unknown,
+    _rect: unknown,
+    size: { contentSize: [number, number]; viewSize: [number, number] },
+  ) {
+    const position = { top: parseInt(theme.spacing(0.5)) } as Record<
+      string,
+      number
+    >
+
+    // Position tooltip left or right based on available space
+    if (size.contentSize[0] < size.viewSize[0] - point[0]) {
+      position.left = point[0]
+    } else {
+      position.right = size.viewSize[0] - point[0]
+    }
+
+    return position
+  }
+}
+
+/**
+ * Creates an axis label formatter for ECharts
+ * Used to format numeric axis labels with a widget formatter
+ *
+ * @param formatter - Optional formatter function from widget config
+ * @returns Axis label formatter function or undefined
+ */
+export function createAxisLabelFormatter(
+  formatter?: (value: number) => string,
+) {
+  if (!formatter) return undefined
+  return (value: number) => formatter(value)
+}
+
+/**
+ * Applies formatter to xAxis configuration
+ * Only applies to single axis objects (not arrays) with type 'value'
+ *
+ * @param xAxis - Existing xAxis configuration
+ * @param formatter - Optional formatter function from widget config
+ * @returns Updated xAxis configuration or undefined if no changes needed
+ */
+export function applyXAxisFormatter(
+  xAxis: unknown,
+  formatter?: (value: number) => string,
+) {
+  let axisFormatter = createAxisLabelFormatter(formatter)
+
+  const xAxisIsObject = xAxis && !Array.isArray(xAxis)
+  const xAxisTyped = xAxis as { type?: string; axisLabel?: unknown }
+
+  if (!xAxisIsObject || xAxisTyped.type !== 'value') {
+    axisFormatter = undefined
+  }
+
+  return {
+    ...xAxisTyped,
+    axisLabel: {
+      ...(typeof xAxisTyped.axisLabel === 'object' && xAxisTyped.axisLabel
+        ? xAxisTyped.axisLabel
+        : {}),
+      formatter: axisFormatter,
+    },
+  }
+}
+
+/**
+ * Applies formatter to yAxis configuration
+ * Only applies to single axis objects (not arrays) with type 'value'
+ *
+ * @param yAxis - Existing yAxis configuration
+ * @param formatter - Optional formatter function from widget config
+ * @returns Updated yAxis configuration or undefined if no changes needed
+ */
+export function applyYAxisFormatter(
+  yAxis: unknown,
+  formatter?: (value: number) => string,
+) {
+  let axisFormatter = createAxisLabelFormatter(formatter)
+
+  const yAxisIsObject = yAxis && !Array.isArray(yAxis)
+  const yAxisTyped = yAxis as { type?: string; axisLabel?: unknown }
+
+  if (!yAxisIsObject || yAxisTyped.type !== 'value') {
+    axisFormatter = undefined
+  }
+
+  return {
+    ...yAxisTyped,
+    axisLabel: {
+      ...(typeof yAxisTyped.axisLabel === 'object' && yAxisTyped.axisLabel
+        ? yAxisTyped.axisLabel
+        : {}),
+      formatter: axisFormatter,
+    },
+  }
+}
+
+/**
+ * Creates a tooltip formatter for ECharts
+ * Formats numeric values in tooltip using widget formatter
+ * Handles both axis trigger (array) and item trigger (object) modes
+ *
+ * @param formatter - Optional formatter function from widget config
+ * @returns Tooltip formatter function or undefined
+ */
+export function createTooltipFormatter(
+  callback: (
+    item: CallbackDataParams,
+    items: CallbackDataParams[],
+  ) => {
+    name: string
+    seriesName: string
+    marker: string
+    value: string | number
+  },
+) {
+  return (params: TopLevelFormatterParams) => {
+    // Handle both array (axis trigger) and object (item trigger)
+    const items = Array.isArray(params) ? params : [params]
+
+    const tooltip = (name: string, callback: string) =>
+      `<div style="margin: 0px 0 0;line-height:1;">${name ? `<div style="font-size:11px;color:#FFFFFF;font-weight:400;line-height:1; margin-bottom: 10px">${name}</div>` : ''}<div style="margin: 0;line-height:1;">${callback}</div><div style="clear:both"></div></div>`
+
+    const values = items.map((item) => {
+      const { name, seriesName, marker, value } = callback(item, items)
+      return {
+        name,
+        seriesName,
+        marker,
+        value,
+      }
+    })
+
+    const name = values[0]?.name ?? ''
+    // Show margin if name exists or there are multiple items
+    const showMargin = name || items.length > 1
+    const marginStyle = showMargin
+      ? 'margin: 10px 0 0;line-height:1;'
+      : 'margin: 0;line-height:1;'
+
+    const formattedValues = values.map(
+      ({ seriesName, marker, value }) =>
+        `<div style="${marginStyle}"><div style="margin: 0px 0 0;line-height:1;">${marker}${seriesName ? `<span style="font-size:11px;color:#FFFFFF;font-weight:400;margin-left:2px;margin-right:10px">${seriesName}</span>` : ''}<span style="float:right;margin-left:10px;font-size:11px;color:#FFFFFF;font-weight:900">${value}</span></div></div>`,
+    )
+
+    return tooltip(name, formattedValues.join(''))
+  }
+}

package/src/widgets/_shared/skeleton/index.ts

@@ -0,0 +1,5 @@
+/**
+ * Shared skeleton styles for chart widgets
+ */
+
+export { baseSkeletonStyles } from './styles'

package/src/widgets/_shared/skeleton/styles.ts

@@ -0,0 +1,20 @@
+import type { Theme } from '@mui/material'
+
+/**
+ * Base skeleton styles shared across all chart widgets
+ */
+export const baseSkeletonStyles = {
+  graph: {
+    /**
+     * Common container style for chart widget skeletons
+     */
+    container: {
+      display: 'flex',
+      alignItems: 'center',
+      justifyContent: 'space-between',
+      flexDirection: 'column',
+      gap: ({ spacing }: Theme) => spacing(1),
+      height: ({ spacing }: Theme) => spacing(38),
+    },
+  },
+} as const

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

@@ -0,0 +1,10 @@
+export const ChangeColumnIcon = () => (
+  <svg xmlns='http://www.w3.org/2000/svg' fill='none' viewBox='0 0 18 18'>
+    <path
+      fill='currentColor'
+      fillRule='evenodd'
+      d='M14.25 2.25H3.75c-.825 0-1.5.675-1.5 1.5v10.5c0 .825.675 1.5 1.5 1.5h10.5c.825 0 1.5-.675 1.5-1.5V3.75c0-.825-.675-1.5-1.5-1.5m-3.75 12h-3V3.75h3zM3.75 3.75H6v10.5H3.75zM12 14.25V3.75h2.25v10.5z'
+      clipRule='evenodd'
+    />
+  </svg>
+)

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

@@ -0,0 +1,163 @@
+import { describe, test, expect, beforeEach, vi } from 'vitest'
+import { render, screen, fireEvent } from '@testing-library/react'
+import { ChangeColumn } from './change-column'
+import { useWidgetStore } from '../../stores/widget-store'
+import type { TableColumn } from '../../table/types'
+
+// Mock @dnd-kit with minimal implementation for testing
+vi.mock('@dnd-kit/core', async () => {
+  const actual = await vi.importActual('@dnd-kit/core')
+  return {
+    ...actual,
+    useSensor: () => ({}),
+    useSensors: () => [],
+  }
+})
+
+describe('ChangeColumn', () => {
+  const widgetId = 'test-change-column-widget'
+
+  const mockColumns: TableColumn[] = [
+    { id: 'name', label: 'Name' },
+    { id: 'country', label: 'Country' },
+    { id: 'population', label: 'Population' },
+  ]
+
+  beforeEach(() => {
+    useWidgetStore.getState().clearWidgets()
+  })
+
+  test('returns null when widget has no columns', () => {
+    const { container } = render(<ChangeColumn id={widgetId} />)
+    expect(container.firstChild).toBeNull()
+  })
+
+  test('returns null when widget has fewer than 2 columns', () => {
+    useWidgetStore.getState().setWidget(widgetId, {
+      columns: [{ id: 'name', label: 'Name' }],
+    })
+
+    const { container } = render(<ChangeColumn id={widgetId} />)
+    expect(container.firstChild).toBeNull()
+  })
+
+  test('renders change column button when widget has 2 or more columns', () => {
+    useWidgetStore.getState().setWidget(widgetId, {
+      columns: mockColumns,
+    })
+
+    render(<ChangeColumn id={widgetId} />)
+
+    const button = screen.getByRole('button')
+    expect(button).toBeTruthy()
+  })
+
+  test('shows default tooltip label', () => {
+    useWidgetStore.getState().setWidget(widgetId, {
+      columns: mockColumns,
+    })
+
+    render(<ChangeColumn id={widgetId} />)
+
+    const button = screen.getByRole('button', { name: 'Change column' })
+    expect(button).toBeTruthy()
+  })
+
+  test('opens menu on button click', () => {
+    useWidgetStore.getState().setWidget(widgetId, {
+      columns: mockColumns,
+    })
+
+    render(<ChangeColumn id={widgetId} />)
+
+    const button = screen.getByRole('button')
+    fireEvent.click(button)
+
+    // Menu should be open with all columns for reordering
+    expect(screen.getByRole('menu')).toBeTruthy()
+    expect(screen.getByRole('menuitem', { name: /Name/i })).toBeTruthy()
+    expect(screen.getByRole('menuitem', { name: /Country/i })).toBeTruthy()
+    expect(screen.getByRole('menuitem', { name: /Population/i })).toBeTruthy()
+  })
+
+  test('displays all columns in menu for drag-and-drop reordering', () => {
+    useWidgetStore.getState().setWidget(widgetId, {
+      columns: mockColumns,
+    })
+
+    render(<ChangeColumn id={widgetId} />)
+
+    const button = screen.getByRole('button')
+    fireEvent.click(button)
+
+    // All three columns should be visible
+    const menuItems = screen.getAllByRole('menuitem')
+    expect(menuItems).toHaveLength(3)
+  })
+
+  test('uses custom labels when provided', () => {
+    useWidgetStore.getState().setWidget(widgetId, {
+      columns: mockColumns,
+    })
+
+    const customLabels = {
+      tooltip: 'Reorder columns',
+      ariaLabel: 'Reorder table columns',
+    }
+
+    render(<ChangeColumn id={widgetId} labels={customLabels} />)
+
+    const button = screen.getByRole('button', { name: 'Reorder table columns' })
+    expect(button).toBeTruthy()
+  })
+
+  test('works with exactly 2 columns', () => {
+    const twoColumns: TableColumn[] = [
+      { id: 'first', label: 'First' },
+      { id: 'second', label: 'Second' },
+    ]
+
+    useWidgetStore.getState().setWidget(widgetId, {
+      columns: twoColumns,
+    })
+
+    render(<ChangeColumn id={widgetId} />)
+
+    const button = screen.getByRole('button')
+    fireEvent.click(button)
+
+    // Both columns should be available for reordering
+    expect(screen.getByRole('menuitem', { name: /First/i })).toBeTruthy()
+    expect(screen.getByRole('menuitem', { name: /Second/i })).toBeTruthy()
+  })
+
+  test('sets data-active attribute when menu is open', () => {
+    useWidgetStore.getState().setWidget(widgetId, {
+      columns: mockColumns,
+    })
+
+    render(<ChangeColumn 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('menu items are keyboard focusable', () => {
+    useWidgetStore.getState().setWidget(widgetId, {
+      columns: mockColumns,
+    })
+
+    render(<ChangeColumn id={widgetId} />)
+
+    const button = screen.getByRole('button')
+    fireEvent.click(button)
+
+    const menuItems = screen.getAllByRole('menuitem')
+    menuItems.forEach((item) => {
+      expect(item.getAttribute('tabindex')).toBe('0')
+    })
+  })
+})

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

@@ -0,0 +1,141 @@
+import {
+  DndContext,
+  closestCenter,
+  KeyboardSensor,
+  PointerSensor,
+  useSensor,
+  useSensors,
+  type DragEndEvent,
+} from '@dnd-kit/core'
+import {
+  arrayMove,
+  SortableContext,
+  sortableKeyboardCoordinates,
+  verticalListSortingStrategy,
+} from '@dnd-kit/sortable'
+import { IconButton, Menu, SvgIcon } from '@mui/material'
+import { useCallback, useMemo, useState, type MouseEvent } from 'react'
+import { useWidgetStore } from '../../stores/widget-store'
+import type { ChangeColumnProps } from './types'
+import { actionButtonStyles } from '../shared/styles'
+import { Tooltip } from '../../../components'
+import type { TableWidgetState } from '../../table/types'
+import { ChangeColumnIcon } from './change-column-icon'
+import { SortableColumnItem } from './sortable-column-item'
+import { useShallow } from 'zustand/shallow'
+
+/**
+ * Widget action to reorder columns in a table widget via drag-and-drop.
+ *
+ * This action reads the columns from the widget store and allows users to
+ * drag and drop columns to reorder them. All columns are displayed and
+ * can be reordered.
+ *
+ * Returns null if there are fewer than 2 columns.
+ *
+ * @example
+ * ```tsx
+ * <ChangeColumn id="my-table-widget" />
+ * ```
+ */
+export function ChangeColumn({
+  id,
+  labels,
+  Icon,
+  IconButtonProps,
+  MenuProps,
+}: ChangeColumnProps) {
+  const [anchorEl, setAnchorEl] = useState<HTMLElement | null>(null)
+  const setWidget = useWidgetStore((state) => state.setWidget)
+  const columns = useWidgetStore(
+    useShallow((state) => state.getWidget<TableWidgetState>(id)?.columns),
+  )
+
+  const sensors = useSensors(
+    useSensor(PointerSensor),
+    useSensor(KeyboardSensor, {
+      coordinateGetter: sortableKeyboardCoordinates,
+    }),
+  )
+
+  const columnIds = useMemo(
+    () => columns?.map((col) => col.id) ?? [],
+    [columns],
+  )
+
+  const handleToggle = useCallback((event: MouseEvent<HTMLElement>) => {
+    event.stopPropagation()
+    setAnchorEl(event.currentTarget)
+  }, [])
+
+  const handleClose = useCallback(() => {
+    setAnchorEl(null)
+  }, [])
+
+  const handleDragEnd = (event: DragEndEvent) => {
+    const { active, over } = event
+    if (!over || active.id === over.id || !columns) return
+    const oldIndex = columns.findIndex((col) => col.id === active.id)
+    const newIndex = columns.findIndex((col) => col.id === over.id)
+    if (oldIndex !== -1 && newIndex !== -1) {
+      const newColumns = arrayMove(columns, oldIndex, newIndex)
+      setWidget(id, { columns: newColumns })
+    }
+  }
+
+  // Return null if there are fewer than 2 columns
+  if (!columns || columns.length < 2) {
+    return null
+  }
+
+  const tooltipLabel = labels?.tooltip ?? 'Change column'
+  const isOpen = Boolean(anchorEl)
+
+  return (
+    <>
+      <Tooltip title={tooltipLabel}>
+        <IconButton
+          size='small'
+          aria-label={labels?.ariaLabel ?? tooltipLabel}
+          aria-controls={isOpen ? 'change-column-menu' : undefined}
+          aria-haspopup='true'
+          aria-expanded={isOpen ? 'true' : undefined}
+          onClick={handleToggle}
+          data-active={isOpen}
+          sx={actionButtonStyles.trigger}
+          {...IconButtonProps}
+        >
+          {Icon ?? (
+            <SvgIcon>
+              <ChangeColumnIcon />
+            </SvgIcon>
+          )}
+        </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' }}
+          {...MenuProps}
+        >
+          <SortableContext
+            items={columnIds}
+            strategy={verticalListSortingStrategy}
+          >
+            {columns.map((column) => (
+              <SortableColumnItem key={column.id} column={column} />
+            ))}
+          </SortableContext>
+        </Menu>
+      </DndContext>
+    </>
+  )
+}

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

@@ -0,0 +1,49 @@
+import { useSortable } from '@dnd-kit/sortable'
+import { CSS } from '@dnd-kit/utilities'
+import { ListItemText, MenuItem } from '@mui/material'
+import type { TableColumn } from '../../table/types'
+
+export interface SortableColumnItemProps {
+  column: TableColumn
+}
+
+/**
+ * A draggable menu item for column reordering.
+ * Uses @dnd-kit/sortable for drag-and-drop functionality.
+ */
+export function SortableColumnItem({ column }: SortableColumnItemProps) {
+  const {
+    attributes,
+    listeners,
+    setNodeRef,
+    transform,
+    transition,
+    isDragging,
+  } = useSortable({ id: column.id })
+
+  const style = {
+    transform: CSS.Transform.toString(transform),
+    transition,
+    opacity: isDragging ? 0.5 : 1,
+    cursor: isDragging ? 'grabbing' : 'grab',
+  }
+
+  return (
+    <MenuItem
+      ref={setNodeRef}
+      style={style}
+      {...attributes}
+      {...listeners}
+      role='menuitem'
+      tabIndex={0}
+      sx={{
+        '&:focus-visible': {
+          outline: (theme) => `2px solid ${theme.palette.primary.main}`,
+          outlineOffset: -2,
+        },
+      }}
+    >
+      <ListItemText>{column.label}</ListItemText>
+    </MenuItem>
+  )
+}

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

@@ -0,0 +1,20 @@
+import type { IconButtonProps, MenuProps } from '@mui/material'
+import type { ReactNode } from 'react'
+
+export interface ChangeColumnProps {
+  /** Widget ID to update column configuration in the widget store */
+  id: string
+  /** Custom labels for the action */
+  labels?: {
+    /** Tooltip label */
+    tooltip?: string
+    /** Accessibility label */
+    ariaLabel?: string
+  }
+  /** Props passed to the IconButton component */
+  IconButtonProps?: IconButtonProps
+  /** Props passed to the Menu component */
+  MenuProps?: Partial<MenuProps>
+  /** Custom icon to display */
+  Icon?: ReactNode
+}