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

package/src/legend/components/legend-sortable/legend-sortable.tsx

@@ -0,0 +1,195 @@
+import { useRef, useState, type ReactNode } from 'react'
+import {
+  DndContext,
+  DragOverlay,
+  KeyboardSensor,
+  PointerSensor,
+  closestCenter,
+  useSensor,
+  useSensors,
+  type CollisionDetection,
+  type DragEndEvent,
+  type DragStartEvent,
+  type KeyboardCoordinateGetter,
+} from '@dnd-kit/core'
+import { SortableContext, verticalListSortingStrategy } from '@dnd-kit/sortable'
+import { Box, Typography } from '@mui/material'
+import {
+  getLegendStore,
+  selectLayersByGroup,
+  selectOrderedGroups,
+  useLegendId,
+  useLegendShallow,
+  useLegendStore,
+} from '../../stores'
+import { LegendSortableContext } from './contexts'
+import { parseSortableId, toSortableId } from './sortable-ids'
+import { styles } from './styles'
+
+export interface LegendSortableProps {
+  /** Panel content (`Legend.Group` / ungrouped `Legend.Row` children). */
+  children?: ReactNode
+}
+
+/**
+ * Opt-in DnD reordering for legend groups and layers (within bucket only).
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export function LegendSortable({ children }: LegendSortableProps) {
+  const id = useLegendId()
+  const [activeId, setActiveId] = useState<string | null>(null)
+  // Cached on drag start — avoid re-reading groupId on every collision candidate.
+  const activeLayerGroupIdRef = useRef<string | undefined>(undefined)
+
+  const topLevelIds = useLegendShallow(id, (s) => [
+    ...selectOrderedGroups(s).map((g) => toSortableId('group', g.id)),
+    ...selectLayersByGroup(s, undefined).map((l) =>
+      toSortableId('layer', l.id),
+    ),
+  ])
+
+  // Same-kind + same-bucket legality — shared by collision detection and keyboard moves.
+  const isLegalTarget = (activeId: string, candidateId: string): boolean => {
+    const from = parseSortableId(activeId)
+    const to = parseSortableId(candidateId)
+    if (!from || to?.kind !== from.kind) return false
+    if (from.kind === 'layer') {
+      const state = getLegendStore(id).getState()
+      return state.layers[to.id]?.groupId === activeLayerGroupIdRef.current
+    }
+    return true
+  }
+
+  // Stock keyboard getter steps through nested member rows inside a group's rect.
+  const keyboardCoordinates: KeyboardCoordinateGetter = (
+    event,
+    { context },
+  ) => {
+    const { active, collisionRect, droppableRects, droppableContainers } =
+      context
+    if (!active || !collisionRect) return undefined
+    if (event.code !== 'ArrowDown' && event.code !== 'ArrowUp') return undefined
+    event.preventDefault()
+
+    const down = event.code === 'ArrowDown'
+    const candidates = droppableContainers
+      .getEnabled()
+      .filter(
+        (container) =>
+          container.id !== active.id &&
+          isLegalTarget(String(active.id), String(container.id)),
+      )
+      .flatMap((container) => {
+        const rect = droppableRects.get(container.id)
+        return rect ? [rect] : []
+      })
+      .filter((rect) =>
+        down ? rect.top > collisionRect.top : rect.top < collisionRect.top,
+      )
+      .sort((a, b) => (down ? a.top - b.top : b.top - a.top))
+
+    const target = candidates[0]
+    return target ? { x: target.left, y: target.top } : undefined
+  }
+
+  const sensors = useSensors(
+    useSensor(PointerSensor),
+    useSensor(KeyboardSensor, { coordinateGetter: keyboardCoordinates }),
+  )
+
+  // Nested droppables: filter to legal targets before closestCenter.
+  const collisionDetection: CollisionDetection = (args) => {
+    const droppableContainers = args.droppableContainers.filter((container) =>
+      isLegalTarget(String(args.active.id), String(container.id)),
+    )
+    return closestCenter({ ...args, droppableContainers })
+  }
+
+  const handleDragStart = (event: DragStartEvent) => {
+    const nextId = String(event.active.id)
+    setActiveId(nextId)
+    const parsed = parseSortableId(nextId)
+    activeLayerGroupIdRef.current =
+      parsed?.kind === 'layer'
+        ? getLegendStore(id).getState().layers[parsed.id]?.groupId
+        : undefined
+  }
+
+  const handleDragEnd = (event: DragEndEvent) => {
+    setActiveId(null)
+    const { active, over } = event
+    if (!over || active.id === over.id) return
+    const from = parseSortableId(String(active.id))
+    const to = parseSortableId(String(over.id))
+    if (!from || from.kind !== to?.kind) return
+
+    const state = getLegendStore(id).getState()
+    if (from.kind === 'group') {
+      const index = selectOrderedGroups(state).findIndex((g) => g.id === to.id)
+      if (index !== -1) state.moveGroup(from.id, index)
+      return
+    }
+    const fromLayer = state.layers[from.id]
+    const toLayer = state.layers[to.id]
+    if (!fromLayer || !toLayer || fromLayer.groupId !== toLayer.groupId) return
+    const bucket = selectLayersByGroup(state, fromLayer.groupId)
+    const index = bucket.findIndex((l) => l.id === to.id)
+    if (index !== -1) state.moveLayer(from.id, index)
+  }
+
+  return (
+    <LegendSortableContext.Provider value={true}>
+      <DndContext
+        sensors={sensors}
+        collisionDetection={collisionDetection}
+        onDragStart={handleDragStart}
+        onDragEnd={handleDragEnd}
+        onDragCancel={() => setActiveId(null)}
+      >
+        <SortableContext
+          items={topLevelIds}
+          strategy={verticalListSortingStrategy}
+        >
+          {children}
+        </SortableContext>
+        <DragOverlay>
+          {activeId && <OverlayCard activeId={activeId} />}
+        </DragOverlay>
+      </DndContext>
+    </LegendSortableContext.Provider>
+  )
+}
+
+function OverlayCard({ activeId }: { activeId: string }) {
+  const id = useLegendId()
+  const parsed = parseSortableId(activeId)
+  const label = useLegendStore(id, (s) =>
+    parsed
+      ? parsed.kind === 'group'
+        ? s.groups[parsed.id]?.label
+        : s.layers[parsed.id]?.name
+      : undefined,
+  )
+  const groupIcon = useLegendStore(id, (s) =>
+    parsed?.kind === 'group' ? s.groups[parsed.id]?.icon : undefined,
+  )
+
+  if (!parsed || label === undefined) return null
+
+  return (
+    <Box sx={styles.overlay}>
+      {parsed.kind === 'group' && groupIcon != null && (
+        <Box sx={styles.overlayIcon}>{groupIcon}</Box>
+      )}
+      <Typography
+        variant='button'
+        fontWeight={parsed.kind === 'group' ? 'bold' : undefined}
+        color='text.primary'
+        sx={styles.overlayLabel}
+      >
+        {label}
+      </Typography>
+    </Box>
+  )
+}

package/src/legend/components/legend-sortable/sortable-entity.tsx

@@ -0,0 +1,91 @@
+import type { CSSProperties, ReactElement, ReactNode } from 'react'
+import { useSortable } from '@dnd-kit/sortable'
+import { CSS } from '@dnd-kit/utilities'
+import { Box, IconButton } from '@mui/material'
+import { DragIndicator as DragIndicatorIcon } from '@mui/icons-material'
+import { Tooltip } from '../../../components/tooltip/tooltip'
+import { useLegendConfig } from '../../provider'
+import { toSortableId, type SortableKind } from './sortable-ids'
+import { styles } from './styles'
+
+/** What `SortableEntity` hands to its render callback. */
+export interface SortableEntityRenderProps {
+  /** Attach to the entity's existing root element. */
+  rootRef: (el: HTMLElement | null) => void
+  /** Sort transform/transition for the root (inline, per-frame values). */
+  rootStyle: CSSProperties
+  /** The original is dimmed in place while its overlay clone is dragged. */
+  dragging: boolean
+  /** The drag handle — absolutely positioned, place anywhere in the header. */
+  handle: ReactNode
+}
+
+export interface SortableEntityProps {
+  kind: SortableKind
+  id: string
+  render: (sortable: SortableEntityRenderProps) => ReactElement
+}
+
+/**
+ * Sortable shell for a legend group/row. Render-prop (instead of a wrapper
+ * element) so the entity keeps its own root — sibling CSS like the `& + &`
+ * dividers keeps working. Hosts `useSortable` and builds the drag handle
+ * (keyboard-activatable, labelled `labels.reorder`).
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export function SortableEntity({ kind, id, render }: SortableEntityProps) {
+  const { labels } = useLegendConfig()
+  const {
+    attributes,
+    listeners,
+    setNodeRef,
+    setActivatorNodeRef,
+    transform,
+    transition,
+    isDragging,
+  } = useSortable({ id: toSortableId(kind, id) })
+
+  const rootStyle: CSSProperties = {
+    // Vertical list: lock x so items only shift along the axis.
+    transform: CSS.Transform.toString(
+      transform ? { ...transform, x: 0 } : null,
+    ),
+    transition,
+  }
+
+  const handle = (
+    // Absolutely positioned (see styles.handleSlot) — no reserved flex slot,
+    // so it never shifts the title/icon; the fade rules live on the
+    // group/row root. Kind-scoped class so a group hover doesn't light up
+    // its member rows' handles.
+    <Box
+      component='span'
+      className={`PsLegend-dragHandle-${kind}`}
+      sx={[
+        styles.handleSlot,
+        kind === 'group' ? styles.handleSlotGroup : styles.handleSlotLayer,
+      ]}
+    >
+      <Tooltip title={labels.reorder}>
+        <IconButton
+          ref={setActivatorNodeRef}
+          size='xsmall'
+          aria-label={labels.reorder}
+          {...attributes}
+          {...listeners}
+          sx={styles.handle}
+        >
+          <DragIndicatorIcon />
+        </IconButton>
+      </Tooltip>
+    </Box>
+  )
+
+  return render({
+    rootRef: setNodeRef,
+    rootStyle,
+    dragging: isDragging,
+    handle,
+  })
+}

package/src/legend/components/legend-sortable/sortable-ids.ts

@@ -0,0 +1,17 @@
+// dnd-kit ids must be unique per DndContext, and legend group/layer id
+// namespaces may collide — so sortable ids carry a kind prefix.
+
+export type SortableKind = 'group' | 'layer'
+
+export const toSortableId = (kind: SortableKind, id: string): string =>
+  `${kind}:${id}`
+
+export function parseSortableId(
+  sortableId: string,
+): { kind: SortableKind; id: string } | null {
+  const sep = sortableId.indexOf(':')
+  if (sep === -1) return null
+  const kind = sortableId.slice(0, sep)
+  if (kind !== 'group' && kind !== 'layer') return null
+  return { kind, id: sortableId.slice(sep + 1) }
+}

package/src/legend/components/legend-sortable/styles.ts

@@ -0,0 +1,65 @@
+import type { SxProps, Theme } from '@mui/material'
+import { LEGEND_GROUP_HEADER_HEIGHT } from '../legend-group/styles'
+
+export const styles = {
+  // Absolute handle, flush against the header's top-left corner — no flex
+  // slot; sticky header is the containing block.
+  handleSlot: {
+    position: 'absolute',
+    zIndex: 1,
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    left: 0,
+    top: 0,
+  },
+  // Both headers center their title on the same 24px band from the header's
+  // top edge (group: 48px header, `alignItems:'center'`; row: 12px top
+  // padding + 24px `titleLine`, `alignItems:'flex-start'`) — so `height:48`
+  // centers the icon on the title in both cases, even though the row's own
+  // header is only 32px tall (a 32px-tall slot would center at 16px, 8px
+  // short of the title).
+  handleSlotLayer: {
+    height: LEGEND_GROUP_HEADER_HEIGHT,
+  },
+  handleSlotGroup: {
+    height: LEGEND_GROUP_HEADER_HEIGHT,
+  },
+  handle: {
+    padding: '2px',
+    cursor: 'grab',
+    touchAction: 'none',
+    color: 'text.secondary',
+    '& .MuiSvgIcon-root': {
+      fontSize: 18,
+    },
+    '&:active': {
+      cursor: 'grabbing',
+    },
+    '&:hover': {
+      backgroundColor: 'transparent',
+    },
+  },
+  overlay: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: 1,
+    padding: ({ spacing }) => spacing(1, 1.5),
+    backgroundColor: 'background.paper',
+    borderRadius: 1,
+    boxShadow: 4,
+    height: 'auto',
+    maxWidth: '100%',
+    overflow: 'hidden',
+  },
+  overlayIcon: {
+    display: 'flex',
+    color: 'text.secondary',
+  },
+  overlayLabel: {
+    minWidth: 0,
+    overflow: 'hidden',
+    textOverflow: 'ellipsis',
+    whiteSpace: 'nowrap',
+  },
+} satisfies Record<string, SxProps<Theme>>

package/src/legend/components/legend-swatch/legend-swatch.test.tsx

@@ -0,0 +1,109 @@
+import { describe, it, expect } from 'vitest'
+import { render } from '@testing-library/react'
+import { LegendSwatch } from './legend-swatch'
+
+function swatch(container: HTMLElement) {
+  return container.querySelector<SVGSVGElement>('svg')!
+}
+
+describe('<LegendSwatch>', () => {
+  it('renders a circle by default (filled, no border)', () => {
+    const { container } = render(<LegendSwatch color='#f00' />)
+    const svg = swatch(container)
+    expect(svg.getAttribute('data-shape')).toBe('circle')
+    const circle = svg.querySelector('circle')!
+    expect(circle.getAttribute('fill')).toBe('#f00')
+    expect(circle.getAttribute('stroke')).toBe('none')
+  })
+
+  it('renders a square shape', () => {
+    const { container } = render(<LegendSwatch shape='square' color='#f00' />)
+    expect(swatch(container).querySelector('rect')).toBeTruthy()
+  })
+
+  it('renders a line shape', () => {
+    const { container } = render(<LegendSwatch shape='line' color='#f00' />)
+    const svg = swatch(container)
+    expect(svg.getAttribute('data-shape')).toBe('line')
+    expect(svg.querySelector('line')).toBeTruthy()
+  })
+
+  it('isStrokeColor paints the border, not the fill', () => {
+    const { container } = render(
+      <LegendSwatch shape='square' color='#0f0' isStrokeColor />,
+    )
+    const rect = swatch(container).querySelector('rect')!
+    expect(rect.getAttribute('fill')).toBe('none')
+    expect(rect.getAttribute('stroke')).toBe('#0f0')
+  })
+
+  it('emits a <pattern> def for a patterned fill and references it', () => {
+    const { container } = render(
+      <LegendSwatch shape='square' color='#00f' fillPattern='diagonal' />,
+    )
+    const svg = swatch(container)
+    const pattern = svg.querySelector('pattern')!
+    expect(pattern).toBeTruthy()
+    const rect = svg.querySelector('rect')!
+    expect(rect.getAttribute('fill')).toBe(`url(#${pattern.id})`)
+  })
+
+  it('solid fill emits no <pattern>', () => {
+    const { container } = render(<LegendSwatch shape='square' color='#00f' />)
+    expect(swatch(container).querySelector('pattern')).toBeNull()
+  })
+
+  it('dashed border sets a stroke-dasharray', () => {
+    const { container } = render(
+      <LegendSwatch
+        shape='square'
+        color='#000'
+        isStrokeColor
+        strokeStyle='dashed'
+      />,
+    )
+    expect(
+      swatch(container).querySelector('rect')!.getAttribute('stroke-dasharray'),
+    ).toBeTruthy()
+  })
+
+  it('corner-marks render four paths (square only)', () => {
+    const { container } = render(
+      <LegendSwatch
+        shape='square'
+        color='#000'
+        isStrokeColor
+        strokeStyle='corners'
+      />,
+    )
+    const svg = swatch(container)
+    expect(svg.querySelectorAll('path')).toHaveLength(4)
+    expect(svg.querySelector('rect')).toBeNull()
+  })
+
+  it('gracefully degrades: corners on a circle falls back to a solid border', () => {
+    const { container } = render(
+      <LegendSwatch
+        shape='circle'
+        color='#000'
+        isStrokeColor
+        strokeStyle='corners'
+      />,
+    )
+    const svg = swatch(container)
+    // No corner paths; a plain stroked circle instead.
+    expect(svg.querySelectorAll('path')).toHaveLength(0)
+    const circle = svg.querySelector('circle')!
+    expect(circle.getAttribute('stroke')).toBe('#000')
+    expect(circle.getAttribute('stroke-dasharray')).toBeFalsy()
+  })
+
+  it('dash-dot line sets the dash-dot dasharray', () => {
+    const { container } = render(
+      <LegendSwatch shape='line' color='#000' strokeStyle='dash-dot' />,
+    )
+    expect(
+      swatch(container).querySelector('line')!.getAttribute('stroke-dasharray'),
+    ).toBe('5 2 0.1 2')
+  })
+})