@carto/ps-react-ui 5.0.0-widgets.9 → 5.0.0

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

@@ -0,0 +1,189 @@
+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/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,11 @@
+export interface ChangeColumnLabels {
+  trigger: string
+  title?: string
+  reset: string
+}
+
+export const DEFAULT_CHANGE_COLUMN_LABELS: ChangeColumnLabels = {
+  trigger: 'Change column order',
+  title: 'Column reorder',
+  reset: 'Reset to default',
+}

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

@@ -0,0 +1,63 @@
+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/style.ts

@@ -0,0 +1,58 @@
+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',
+  },
+  header: {
+    color: 'text.secondary',
+    backgroundColor: 'transparent',
+    typography: 'caption',
+    px: 2,
+    py: 0.75,
+  },
+  item: {
+    position: 'relative',
+    cursor: 'grab',
+    px: 2,
+    touchAction: 'none',
+    '&:hover .change-column-drag-handle': {
+      opacity: 1,
+    },
+    '&:focus-visible': {
+      outline: '2px solid',
+      outlineColor: 'primary.main',
+      outlineOffset: -2,
+    },
+    '&:focus-visible .change-column-drag-handle': {
+      opacity: 1,
+    },
+  },
+  itemDragging: {
+    opacity: 0.5,
+    cursor: 'grabbing',
+  },
+  dragHandle: {
+    position: 'absolute',
+    left: 0,
+    top: '50%',
+    transform: 'translateY(-50%)',
+    color: 'text.secondary',
+    fontSize: 18,
+    opacity: 0,
+    transition: 'opacity 0.1s',
+    '@media (hover: none)': {
+      opacity: 1,
+    },
+  },
+  dragHandleVisible: {
+    opacity: 1,
+  },
+} 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/constants.ts

@@ -0,0 +1,14 @@
+/**
+ * Canonical `DownloadItem.id`s for the built-in download formats. Centralised
+ * so the per-format builders — and anything that keys off the id (menu logic,
+ * tests) — reference one source of truth instead of re-typing string literals.
+ * The Markdown format keeps the short `'md'` id to match its `.md` extension.
+ */
+export const DOWNLOAD_ITEM_IDS = {
+  png: 'png',
+  csv: 'csv',
+  markdown: 'md',
+} as const
+
+export type DownloadItemId =
+  (typeof DOWNLOAD_ITEM_IDS)[keyof typeof DOWNLOAD_ITEM_IDS]

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

@@ -0,0 +1,77 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { buildCsvDownloadItem } from './csv-item'
+
+let csvText = ''
+let revokeSpy: ReturnType<typeof vi.spyOn>
+
+beforeEach(() => {
+  csvText = ''
+  vi.spyOn(URL, 'createObjectURL').mockReturnValue('blob:csv')
+  revokeSpy = vi
+    .spyOn(URL, 'revokeObjectURL')
+    .mockImplementation(() => undefined)
+  const RealBlob = global.Blob
+  vi.stubGlobal(
+    'Blob',
+    class extends RealBlob {
+      constructor(parts: BlobPart[], opts?: BlobPropertyBag) {
+        csvText = typeof parts[0] === 'string' ? parts[0] : ''
+        super(parts, opts)
+      }
+    },
+  )
+})
+
+describe('buildCsvDownloadItem', () => {
+  it('returns an item with the canonical CSV shape (id, label, icon)', () => {
+    const item = buildCsvDownloadItem({ filename: 'demo', getRows: () => [] })
+    expect(item.id).toBe('csv')
+    expect(item.label).toBe('CSV')
+    expect(item.icon).toBeTruthy()
+  })
+
+  it('honours a label override', () => {
+    const item = buildCsvDownloadItem({
+      filename: 'demo',
+      getRows: () => [],
+      label: 'Export data',
+    })
+    expect(item.label).toBe('Export data')
+  })
+
+  it('getRows path serialises rows via toCsvString and returns a .csv handle', async () => {
+    const item = buildCsvDownloadItem({
+      filename: 'sales',
+      getRows: () => [
+        ['name', 'value'],
+        ['a', 1],
+      ],
+    })
+    const handle = await item.resolve()
+    expect(handle.url).toBe('blob:csv')
+    expect(handle.filename).toBe('sales.csv')
+    expect(csvText).toBe('name,value\na,1')
+    handle.revoke?.()
+    expect(revokeSpy).toHaveBeenCalledWith('blob:csv')
+  })
+
+  it('getRows path applies the formula-injection guard', async () => {
+    const item = buildCsvDownloadItem({
+      filename: 'sales',
+      getRows: () => [['=SUM(A1)']],
+    })
+    await item.resolve()
+    expect(csvText).toBe("'=SUM(A1)")
+  })
+
+  it('getCsv path passes the pre-built CSV through verbatim', async () => {
+    const item = buildCsvDownloadItem({
+      filename: 'table',
+      getCsv: () => 'col\n=raw',
+    })
+    const handle = await item.resolve()
+    expect(handle.filename).toBe('table.csv')
+    // getCsv is an escape hatch — content is used as-is, no extra escaping.
+    expect(csvText).toBe('col\n=raw')
+  })
+})

package/src/widgets-v2/actions/download/csv-item.tsx

@@ -0,0 +1,71 @@
+import { DOWNLOAD_ITEM_IDS } from './constants'
+import { downloadToCSV } from './exports'
+import { CSVIcon } from './icons'
+import type { DownloadItem } from './types'
+
+interface BuildCsvDownloadItemBase {
+  /** Base filename (without extension). The item appends `.csv`. */
+  filename: string
+  /** Override the menu label. Default `'CSV'`. */
+  label?: string
+}
+
+/**
+ * Args for {@link buildCsvDownloadItem}. A discriminated union: a caller must
+ * supply exactly one content source — `getRows` (rows serialised through the
+ * shared `toCsvString`) or `getCsv` (a pre-built CSV string). The `?: never`
+ * arms make passing both — or neither — a compile-time error.
+ */
+export type BuildCsvDownloadItemArgs =
+  | (BuildCsvDownloadItemBase & {
+      /**
+       * Builds the CSV rows at click time. Used by most widgets — rows are run
+       * through `toCsvString` so escaping (incl. the spreadsheet
+       * formula-injection guard) stays consistent across widgets.
+       */
+      getRows: () => readonly (readonly unknown[])[]
+      getCsv?: never
+    })
+  | (BuildCsvDownloadItemBase & {
+      /**
+       * Returns a pre-built CSV string at click time. Escape hatch for widgets
+       * (e.g. Table) that already serialise their own CSV with bespoke
+       * header/cell handling.
+       */
+      getCsv: () => string
+      getRows?: never
+    })
+
+/**
+ * Builds the standard CSV `DownloadItem` used by every per-widget download
+ * config. Centralised so the menu label, icon, and `.csv` filename suffix stay
+ * consistent across widgets — mirrors {@link buildPngDownloadItem} so neither
+ * format can drift again.
+ */
+export function buildCsvDownloadItem(
+  args: BuildCsvDownloadItemArgs,
+): DownloadItem {
+  return {
+    id: DOWNLOAD_ITEM_IDS.csv,
+    label: args.label ?? 'CSV',
+    icon: <CSVIcon fontSize='small' />,
+    resolve: () => {
+      if (args.getCsv) {
+        const csv = args.getCsv()
+        const blob = new Blob([csv], { type: 'text/csv;charset=utf-8;' })
+        const url = URL.createObjectURL(blob)
+        return Promise.resolve({
+          url,
+          filename: `${args.filename}.csv`,
+          revoke: () => URL.revokeObjectURL(url),
+        })
+      }
+      const handle = downloadToCSV(args.getRows())
+      return Promise.resolve({
+        url: handle.url,
+        filename: `${args.filename}.csv`,
+        revoke: handle.revoke,
+      })
+    },
+  }
+}