@carto/ps-react-ui 4.15.0 → 4.16.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 { LayersOutlined as GroupIcon } from '@mui/icons-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,
+  )
+
+  if (!parsed || label === undefined) return null
+
+  return (
+    <Box sx={styles.overlay}>
+      {parsed.kind === 'group' && (
+        <Box sx={styles.overlayIcon}>
+          <GroupIcon fontSize='small' />
+        </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,56 @@
+import type { SxProps, Theme } from '@mui/material'
+
+export const styles = {
+  // Absolute handle — no flex slot; sticky header is the containing block.
+  handleSlot: {
+    position: 'absolute',
+    zIndex: 1,
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    height: 24,
+  },
+  handleSlotLayer: {
+    right: 2,
+  },
+  handleSlotGroup: {
+    right: 2,
+  },
+  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-visibility-toggle/legend-visibility-toggle.tsx

@@ -4,6 +4,7 @@ import {
   VisibilityOutlined as VisibilityIcon,
   VisibilityOffOutlined as VisibilityOffIcon,
 } from '@mui/icons-material'
+import { Tooltip } from '../../../components/tooltip/tooltip'
 import {
   selectGroupVisibility,
   useLegendId,
@@ -113,15 +114,20 @@ export function LegendVisibilityToggle({
 
   const { hideLayer, showLayer } = labelPair ?? configLabels
   const EyeIcon = ICONS[state]
+  const label = state === 'hidden' ? showLayer : hideLayer
 
   return (
-    <IconButton
-      size='small'
-      className={state === 'visible' ? undefined : 'active'}
-      onClick={handleToggle}
-      aria-label={state === 'hidden' ? showLayer : hideLayer}
-    >
-      <EyeIcon fontSize='small' />
-    </IconButton>
+    // Tooltip clones the button (no wrapper element), so the hover-fade
+    // group's direct-child rules and the `.active` pin keep working.
+    <Tooltip title={label}>
+      <IconButton
+        size='small'
+        className={state === 'visible' ? undefined : 'active'}
+        onClick={handleToggle}
+        aria-label={label}
+      >
+        <EyeIcon fontSize='small' />
+      </IconButton>
+    </Tooltip>
   )
 }

package/src/legend/components/legend-visible-layers/legend-visible-layers.test.tsx

@@ -0,0 +1,86 @@
+import { afterEach, describe, it, expect } from 'vitest'
+import { act, fireEvent, render, screen } from '@testing-library/react'
+import { LegendProvider } from '../../provider'
+import { LegendVisibleLayers } from './legend-visible-layers'
+import {
+  clearAllLegendStores,
+  getLegendStore,
+  type LegendLayerInput,
+  type LegendVariable,
+} from '../../stores'
+
+const cat: LegendVariable = {
+  type: 'category',
+  items: [{ label: 'A', color: '#123456' }],
+}
+
+const layers: LegendLayerInput[] = [
+  { id: 'a', name: 'Suitability', groupId: 'g1', variables: [cat] },
+  { id: 'b', name: 'Population', groupId: 'g2', variables: [cat] },
+  { id: 'c', name: 'Facilities', variables: [cat] }, // ungrouped → last
+]
+const groups = [
+  { id: 'g1', label: 'Site selection' },
+  { id: 'g2', label: 'Demographics' },
+]
+
+afterEach(() => clearAllLegendStores())
+
+function renderSummary(id: string, layerInputs = layers) {
+  return render(
+    <LegendProvider id={id} layers={layerInputs} groups={groups}>
+      <LegendVisibleLayers />
+    </LegendProvider>,
+  )
+}
+
+describe('<LegendVisibleLayers>', () => {
+  it('lists only visible layers grouped under their captions, ungrouped last', () => {
+    renderSummary('vl1', [
+      ...layers.slice(0, 2),
+      { ...layers[2]!, visible: false } as LegendLayerInput,
+    ])
+    fireEvent.click(screen.getByLabelText('Enabled layers'))
+    // Count excludes the hidden ungrouped layer.
+    expect(screen.getByText('Enabled layers (2)')).toBeTruthy()
+    expect(screen.getByText('Site selection')).toBeTruthy()
+    expect(screen.getByText('Suitability')).toBeTruthy()
+    expect(screen.getByText('Population')).toBeTruthy()
+    // Hidden layer (and its would-be section) not listed.
+    expect(screen.queryByText('Facilities')).toBeNull()
+  })
+
+  it('clicking an entry hides the layer and removes it without closing the menu', () => {
+    renderSummary('vl2')
+    fireEvent.click(screen.getByLabelText('Enabled layers'))
+    expect(screen.getByText('Enabled layers (3)')).toBeTruthy()
+
+    // The whole item is the hide action (keyboard-reachable menu item).
+    fireEvent.click(screen.getByRole('menuitem', { name: 'Suitability' }))
+    expect(getLegendStore('vl2').getState().layers.a!.visible).toBe(false)
+    // Menu stayed open, entry gone, count updated live.
+    expect(screen.getByText('Enabled layers (2)')).toBeTruthy()
+    expect(screen.queryByText('Suitability')).toBeNull()
+  })
+
+  it('hiding the last visible layer closes the menu and disables the trigger', () => {
+    renderSummary('vl3', [layers[0]!])
+    const trigger = screen.getByLabelText<HTMLButtonElement>('Enabled layers')
+    fireEvent.click(trigger)
+    fireEvent.click(screen.getByRole('menuitem', { name: 'Suitability' }))
+    // Nothing left to list → the menu closed itself (role queries skip the
+    // aria-hidden exit transition)…
+    expect(screen.queryByRole('menu')).toBeNull()
+    // …and the trigger is disabled until a layer is shown again.
+    expect(trigger.disabled).toBe(true)
+  })
+
+  it('closes when the last visible layer is hidden from elsewhere', () => {
+    renderSummary('vl4', [layers[0]!])
+    fireEvent.click(screen.getByLabelText('Enabled layers'))
+    expect(screen.getByRole('menu')).toBeTruthy()
+    // External change (e.g. a row eye) while the menu is open.
+    act(() => getLegendStore('vl4').getState().setVisibility('a', false))
+    expect(screen.queryByRole('menu')).toBeNull()
+  })
+})

package/src/legend/components/legend-visible-layers/legend-visible-layers.tsx

@@ -0,0 +1,135 @@
+import { useState, type MouseEvent } from 'react'
+import {
+  Box,
+  Divider,
+  IconButton,
+  Menu,
+  MenuItem,
+  Typography,
+} from '@mui/material'
+import {
+  ChecklistOutlined as ChecklistIcon,
+  VisibilityOutlined as VisibilityIcon,
+} from '@mui/icons-material'
+import { Tooltip } from '../../../components/tooltip/tooltip'
+import {
+  getLegendStore,
+  selectVisibleLayersGrouped,
+  useLegendId,
+  useLegendShallow,
+  useLegendStore,
+} from '../../stores'
+import { useLegendConfig } from '../../provider'
+import { styles } from './styles'
+
+/** `key` ties section derivation to the visibility fingerprint subscription. */
+function sectionsForKey(legendId: string, key: string) {
+  void key
+  return selectVisibleLayersGrouped(getLegendStore(legendId).getState())
+}
+
+/**
+ * Panel checklist of visible layers — each entry hides its layer; the menu
+ * closes when nothing remains to list.
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export function LegendVisibleLayers() {
+  const id = useLegendId()
+  const [anchorEl, setAnchorEl] = useState<HTMLElement | null>(null)
+  // Fingerprint avoids opacity-driven re-renders (React Compiler would hoist stale useMemo).
+  const visibleKey = useLegendStore(id, (s) =>
+    selectVisibleLayersGrouped(s)
+      .map(
+        ({ group, layers }) =>
+          `${group?.id ?? ''}\x1f${group?.label ?? ''}:${layers
+            .map((l) => `${l.id}\x1f${l.name}`)
+            .join(',')}`,
+      )
+      .join('|'),
+  )
+  const sections = sectionsForKey(id, visibleKey)
+  const setVisibility = useLegendShallow(id, (s) => s.setVisibility)
+  const { labels } = useLegendConfig()
+
+  const count = sections.reduce((n, s) => n + s.layers.length, 0)
+  // Derived close when count hits 0; clear anchor on exit so it can't reopen stale.
+  const open = Boolean(anchorEl) && count > 0
+
+  const handleOpen = (e: MouseEvent<HTMLElement>) =>
+    setAnchorEl(e.currentTarget)
+  const handleClose = () => setAnchorEl(null)
+
+  return (
+    <>
+      <Tooltip title={labels.toggleEnabledLayers}>
+        {/* Span: MUI Tooltip can't attach listeners to a disabled button. */}
+        <Box component='span' sx={styles.triggerWrap}>
+          <IconButton
+            size='small'
+            className={open ? 'active' : undefined}
+            disabled={count === 0}
+            onClick={handleOpen}
+            aria-label={labels.enabledLayers}
+            aria-haspopup='menu'
+            aria-expanded={open}
+          >
+            <ChecklistIcon fontSize='small' />
+          </IconButton>
+        </Box>
+      </Tooltip>
+      <Menu
+        anchorEl={anchorEl}
+        open={open}
+        onClose={handleClose}
+        TransitionProps={{ onExited: handleClose }}
+        // No list padding — sticky header sits flush (avoids scroll peek-through).
+        MenuListProps={{ disablePadding: true }}
+        slotProps={{ paper: { sx: styles.paper } }}
+      >
+        <Typography
+          component='div'
+          variant='caption'
+          color='text.primary'
+          sx={styles.stickyHeader}
+        >
+          {`${labels.enabledLayers} (${count})`}
+        </Typography>
+        {sections.flatMap((section, index) => [
+          index > 0 ? (
+            <Divider
+              key={`divider-${section.group?.id ?? 'ungrouped'}`}
+              sx={styles.divider}
+            />
+          ) : null,
+          section.group ? (
+            <Typography
+              key={`caption-${section.group.id}`}
+              variant='caption'
+              fontWeight='medium'
+              color='text.secondary'
+              sx={styles.groupCaption}
+            >
+              {section.group.label}
+            </Typography>
+          ) : null,
+          ...section.layers.map((layer) => (
+            <MenuItem
+              key={layer.id}
+              disableRipple
+              sx={styles.item}
+              onClick={() => setVisibility(layer.id, false)}
+            >
+              <Typography variant='body2' sx={styles.itemName}>
+                {layer.name}
+              </Typography>
+              <Tooltip title={labels.hideLayer}>
+                <VisibilityIcon sx={styles.eye} />
+              </Tooltip>
+            </MenuItem>
+          )),
+        ])}
+      </Menu>
+    </>
+  )
+}

package/src/legend/components/legend-visible-layers/styles.ts

@@ -0,0 +1,60 @@
+import type { SxProps, Theme } from '@mui/material'
+
+// Figma "Menu" (node 6962-12862): 232px paper, sticky caption header with a
+// hairline below, caption-medium group subtitles, 32px items (12px left / 8px
+// right inset) with an 18px eye, and 8px-padded dividers between sections.
+export const styles = {
+  // Tooltip wrapper around the (possibly disabled) trigger button. A plain
+  // inline span would be sized by the line box and end up taller than the
+  // button inside.
+  triggerWrap: {
+    display: 'inline-flex',
+  },
+  paper: {
+    width: 240,
+    maxHeight: 320,
+    // List padding is disabled (flush sticky header); keep a small bottom
+    // inset so the last 32px item doesn't touch the paper edge.
+    paddingBottom: 0.5,
+  },
+  stickyHeader: {
+    position: 'sticky',
+    top: 0,
+    zIndex: 1,
+    backgroundColor: 'background.paper',
+    padding: 1,
+    marginBlockEnd: 1,
+    lineHeight: '16px',
+    borderBottom: '1px solid',
+    borderColor: 'divider',
+  },
+  groupCaption: {
+    display: 'block',
+    padding: ({ spacing }) => spacing(0.5, 1.5),
+  },
+  // The whole item is the hide action (keyboard-friendly); the eye is its
+  // visual affordance.
+  item: {
+    minHeight: 32,
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'space-between',
+    gap: 1,
+    padding: ({ spacing }) => spacing(0, 1, 0, 1.5),
+  },
+  itemName: {
+    minWidth: 0,
+    overflow: 'hidden',
+    textOverflow: 'ellipsis',
+    whiteSpace: 'nowrap',
+  },
+  // Design's 18px glyph — decorative (the item itself is the action).
+  eye: {
+    fontSize: 18,
+    color: 'action.active',
+    flexShrink: 0,
+  },
+  divider: {
+    marginY: 1,
+  },
+} satisfies Record<string, SxProps<Theme>>