@carto/ps-react-ui 5.3.0 → 6.1.0

package/src/widgets-v2/actions/brush-toggle/brush-toggle.tsx

@@ -1,154 +0,0 @@
-import { useEffect, type ComponentType } from 'react'
-import { IconButton, type SvgIconProps } from '@mui/material'
-import { HighlightAlt as HighlightAltIcon } from '@mui/icons-material'
-import { Tooltip } from '../../../components'
-import {
-  useEchartInstance,
-  useSingleTransform,
-  useWidgetId,
-} from '../../stores'
-import { addBrush } from './transforms'
-import { DEFAULT_BRUSH_TOGGLE_LABELS, type BrushToggleLabels } from './labels'
-import { styles } from './style'
-
-const BRUSH_DESCRIPTOR = {
-  id: 'brush-toggle',
-  type: 'config' as const,
-  order: 25,
-}
-
-export interface BrushToggleProps {
-  initialEnabled?: boolean
-  /**
-   * ECharts brush type. `'lineX'` (default) selects a range on the
-   * x-axis — appropriate for bar / histogram / timeseries. `'rect'`
-   * selects a 2-D rectangle — use for scatterplot. Other ECharts
-   * brush types (`'lineY'`, `'polygon'`) are also accepted.
-   */
-  brushType?: 'lineX' | 'lineY' | 'rect' | 'polygon'
-  /**
-   * `'multiple'` (default) lets the user draw additional brushes on
-   * top of existing ones. `'single'` replaces the previous brush on
-   * each new draw.
-   */
-  brushMode?: 'multiple' | 'single'
-  /**
-   * Optional view of the consumer-owned selection. When provided and
-   * the array is empty (`[]`), any brush rectangles currently drawn on
-   * the chart are wiped — keeps the UI in sync when the parent clears
-   * the selection externally (e.g. via `Widget.SelectionSummary`'s
-   * `onClear`). Pass the same array that drives `useChartSelection` /
-   * the option factory's `selection` input.
-   *
-   * Leave `undefined` to opt out — the sync effect becomes a no-op.
-   */
-  selection?: readonly unknown[] | null
-  labels?: Partial<BrushToggleLabels>
-  icon?: ComponentType<SvgIconProps>
-  iconProps?: SvgIconProps
-}
-
-/**
- * Toggle ECharts' brush selection mode. Two-part wiring:
- *
- *   1. The config transform (`addBrush`) installs the `brush`
- *      component on the option so brushed items get the
- *      `outOfBrush` dim treatment.
- *   2. ECharts only enters "brush cursor" mode when something
- *      dispatches `takeGlobalCursor({ key: 'brush', ... })`. This
- *      component drives that dispatch via {@link useEchartInstance},
- *      reacting when the chart instance becomes available (the
- *      `BrushToggle` mounts before `Widget.Echart` in tree order, so
- *      on first mount the chart isn't ready yet).
- *
- *   3. ECharts clears the global cursor on every `setOption`, so we
- *      re-dispatch on each `'finished'` event — required for
- *      `brushMode: 'multiple'` to keep working across selection-driven
- *      re-renders, RelativeData toggles, etc.
- *
- * Selection events (`brushSelected` / `brushEnd`) flow through the
- * existing `useChartSelection` wiring at the consumer level — no extra
- * plumbing here.
- */
-export function BrushToggle({
-  initialEnabled = false,
-  brushType = 'lineX',
-  brushMode = 'multiple',
-  selection,
-  labels,
-  icon: Icon = HighlightAltIcon,
-  iconProps,
-}: BrushToggleProps) {
-  const id = useWidgetId()
-  const _labels = { ...DEFAULT_BRUSH_TOGGLE_LABELS, ...labels }
-  const { enabled, toggle } = useSingleTransform(
-    id,
-    BRUSH_DESCRIPTOR,
-    addBrush,
-    { initialEnabled },
-  )
-
-  // Reactive read of the live instance — the effect below re-runs when
-  // the chart arrives, departs, or re-inits, instead of polling.
-  const chart = useEchartInstance(id)
-
-  useEffect(() => {
-    if (!chart) return undefined
-    if (!enabled) {
-      // Disabled: exit brush cursor and wipe any drawn rectangles.
-      chart.dispatchAction({ type: 'takeGlobalCursor' })
-      chart.dispatchAction({ type: 'brush', areas: [] })
-      return undefined
-    }
-
-    const enterBrush = (): void => {
-      chart.dispatchAction({
-        type: 'takeGlobalCursor',
-        key: 'brush',
-        brushOption: { brushType, brushMode },
-      })
-    }
-
-    // Every `setOption` clears the global cursor. Re-dispatch after
-    // each chart render so `brushMode: 'multiple'` stays usable across
-    // selection-driven re-renders, RelativeData toggles, etc.
-    const onFinished = (): void => enterBrush()
-    chart.on('finished', onFinished)
-    enterBrush()
-
-    return () => {
-      chart.off('finished', onFinished)
-    }
-  }, [chart, enabled, brushType, brushMode])
-
-  // Sync the drawn rectangles with the external selection. When the
-  // parent flips `selection` to `[]` (e.g. SelectionSummary's "Clear"
-  // button), wipe the brush areas so the chart UI matches the data.
-  // Dispatching with an empty `areas` array when nothing is drawn is a
-  // safe no-op on ECharts, so no extra "previous value" bookkeeping is
-  // needed. Kept as a separate effect so a parent selection change
-  // doesn't tear down / re-attach the `'finished'` listener above.
-  useEffect(() => {
-    if (!chart || !enabled) return
-    if (selection?.length === 0) {
-      chart.dispatchAction({ type: 'brush', areas: [] })
-    }
-  }, [chart, enabled, selection])
-
-  const tooltip = enabled ? _labels.on : _labels.off
-
-  return (
-    <Tooltip title={tooltip}>
-      <IconButton
-        size='small'
-        aria-label={tooltip}
-        aria-pressed={enabled}
-        onClick={toggle}
-        className={enabled ? 'active' : undefined}
-        sx={{ ...styles.toggle, ...(enabled && styles.toggleActive) }}
-      >
-        <Icon fontSize='small' {...iconProps} />
-      </IconButton>
-    </Tooltip>
-  )
-}

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

@@ -1,14 +0,0 @@
-import { SvgIcon, type SvgIconProps } from '@mui/material'
-
-export function ChangeColumnIcon(props: SvgIconProps) {
-  return (
-    <SvgIcon viewBox='0 0 18 18' {...props}>
-      <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'
-      />
-    </SvgIcon>
-  )
-}

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

@@ -1,59 +0,0 @@
-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

@@ -1,189 +0,0 @@
-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,
-  ListSubheader,
-  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}
-        autoScroll={false}
-      >
-        <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 } }}
-        >
-          <ListSubheader disableSticky role='presentation' sx={styles.header}>
-            {_labels.title}
-          </ListSubheader>
-          <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/sortable-column-item.tsx

@@ -1,63 +0,0 @@
-import { useSortable } from '@dnd-kit/sortable'
-import { CSS } from '@dnd-kit/utilities'
-import { ListItemText, MenuItem } from '@mui/material'
-import { DragIndicator as DragIndicatorIcon } from '@mui/icons-material'
-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}
-      disableGutters
-      role='menuitem'
-      tabIndex={0}
-      sx={{ ...styles.item, ...(isDragging && styles.itemDragging) }}
-    >
-      <HandleIcon
-        className='change-column-drag-handle'
-        sx={{
-          ...styles.dragHandle,
-          ...(isDragging && styles.dragHandleVisible),
-        }}
-      />
-      <ListItemText>{label}</ListItemText>
-    </MenuItem>
-  )
-}

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

@@ -1,11 +0,0 @@
-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[]
-}