@carto/ps-react-ui 4.15.0 → 4.16.0

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

@@ -1,36 +1,40 @@
 import { useMemo, useState, type ReactNode } from 'react'
-import { Box, Collapse, IconButton, Typography } from '@mui/material'
-import {
-  ExpandMore as ExpandMoreIcon,
-  ExpandLess as ExpandLessIcon,
-} from '@mui/icons-material'
+import { Box, Collapse, Typography } from '@mui/material'
+import { ExpandMore as ExpandMoreIcon } from '@mui/icons-material'
 import { SmartTooltip } from '../../../components/smart-tooltip/smart-tooltip'
-import { useLegendId, useLegendShallow } from '../../stores'
-import { useLegendConfig } from '../../provider'
-import { LegendRowContext, type LegendRowContextValue } from '../contexts'
+import {
+  selectLayerCollapsible,
+  useLegendId,
+  useLegendShallow,
+  useLegendStore,
+} from '../../stores'
+import { accordionKeyDown } from '../a11y'
+import {
+  LegendRowContext,
+  type LegendRowContextValue,
+  useLegendGroupId,
+} from '../contexts'
 import { partitionLegendChildren } from '../legend-actions/legend-actions'
 import { LEGEND_GROUP_HEADER_HEIGHT } from '../legend-group/styles'
+import { useLegendSortable } from '../legend-sortable/contexts'
+import {
+  SortableEntity,
+  type SortableEntityRenderProps,
+} from '../legend-sortable/sortable-entity'
 import { styles } from './styles'
 
 export interface LegendRowProps {
   layerId: string
   /**
-   * Composition slots: `<Legend.Actions>` children render in the sticky
-   * header next to the collapse chevron (hover-fade); everything else renders
-   * in the collapsible body, followed by the layer's `helperText` footer.
+   * `<Legend.Actions>` in the sticky header; body children + `helperText` footer.
+   * Place `<Legend.Opacity.Inline />` first in the body.
    */
   children?: ReactNode
 }
 
 /**
- * Store-connected layer-row wrapper (widgets-v2 `Wrapper` parity). Renders
- * the sticky header — title + subtitle from the store with a smart-truncating
- * tooltip, the partitioned `<Legend.Actions>` slot, and the collapse chevron —
- * over the collapsible body. Provides the row composition context so actions
- * (`Legend.VisibilityToggle`, `Legend.Opacity.*`, `Legend.RowMenu`,
- * `Legend.ConfigSelect`, `Legend.Item`) resolve the layer without props.
- * When the layer is hidden the body is force-collapsed, the content dims,
- * and the chevron is disabled.
+ * Store-connected layer row. Provides row context for actions; hidden layers
+ * force-collapse the body.
  *
  * @experimental This API is new and may change in a future release.
  */
@@ -38,67 +42,80 @@ export function LegendRow({ layerId, children }: LegendRowProps) {
   const id = useLegendId()
   const layer = useLegendShallow(id, (s) => s.layers[layerId])
   const setCollapsed = useLegendShallow(id, (s) => s.setCollapsed)
-  const { labels } = useLegendConfig()
+  const collapsible = useLegendStore(id, (s) =>
+    selectLayerCollapsible(s, layerId),
+  )
+  const inGroup = useLegendGroupId() !== null
+  const sortable = useLegendSortable()
 
-  const [headerEl, setHeaderEl] = useState<HTMLElement | null>(null)
   const [opacityOpen, setOpacityOpen] = useState(false)
+  // Hidden rows derive opacityOpen=false so menu `.active` never pins while hidden.
+  const visible = layer?.visible ?? true
   const rowContext = useMemo<LegendRowContextValue>(
-    () => ({ layerId, headerEl, opacityOpen, setOpacityOpen }),
-    [layerId, headerEl, opacityOpen],
+    () => ({ layerId, opacityOpen: opacityOpen && visible, setOpacityOpen }),
+    [layerId, opacityOpen, visible],
   )
 
   if (!layer) return null
 
   const { actions, body } = partitionLegendChildren(children)
   const effectivelyCollapsed = !layer.visible || layer.collapsed
-  // Grouped rows pin below their group's sticky header.
-  const stickyTop = layer.groupId ? LEGEND_GROUP_HEADER_HEIGHT : 0
+  const stickyTop = inGroup ? LEGEND_GROUP_HEADER_HEIGHT : 0
+  const canToggle = layer.visible && collapsible
+  const toggle = () => setCollapsed(layerId, !layer.collapsed)
 
-  return (
+  const renderRow = (sortableProps?: SortableEntityRenderProps) => (
     <LegendRowContext.Provider value={rowContext}>
-      <Box sx={styles.row}>
-        {/* Inline style: per-instance sticky offset (0 or the group-header
-            height), no emotion class churn. */}
-        <Box ref={setHeaderEl} sx={styles.header} style={{ top: stickyTop }}>
-          <Box sx={styles.titleBox}>
+      <Box
+        ref={sortableProps?.rootRef}
+        style={sortableProps?.rootStyle}
+        sx={[
+          styles.row,
+          sortableProps?.dragging === true && styles.rowDragging,
+        ]}
+      >
+        <Box sx={styles.header} style={{ top: stickyTop }}>
+          {sortableProps?.handle}
+          <Box
+            sx={[styles.titleBox, canToggle && styles.titleBoxInteractive]}
+            {...(canToggle && {
+              role: 'button',
+              tabIndex: 0,
+              'aria-expanded': !layer.collapsed,
+              onClick: toggle,
+              onKeyDown: accordionKeyDown(toggle),
+            })}
+          >
             <Box sx={styles.titleLine}>
               <SmartTooltip title={layer.name} dependencies={[layer.name]}>
                 {({ ref }) => (
                   <Typography
                     ref={ref}
                     variant='button'
-                    color='text.primary'
+                    color={layer.visible ? 'text.primary' : 'text.disabled'}
                     sx={styles.title}
                   >
                     {layer.name}
                   </Typography>
                 )}
               </SmartTooltip>
+              {canToggle && (
+                <ExpandMoreIcon
+                  sx={[
+                    styles.chevron,
+                    layer.collapsed && styles.chevronCollapsed,
+                  ]}
+                />
+              )}
             </Box>
-            {layer.subtitle && (
+            {layer.subtitle && !effectivelyCollapsed && (
               <Typography variant='caption' color='text.secondary'>
                 {layer.subtitle}
               </Typography>
             )}
           </Box>
 
-          <Box sx={styles.actions}>
-            {actions}
-            <IconButton
-              size='small'
-              onClick={() => setCollapsed(layerId, !layer.collapsed)}
-              disabled={!layer.visible}
-              aria-label={
-                effectivelyCollapsed ? labels.expandLayer : labels.collapseLayer
-              }
-            >
-              {effectivelyCollapsed ? (
-                <ExpandMoreIcon fontSize='small' />
-              ) : (
-                <ExpandLessIcon fontSize='small' />
-              )}
-            </IconButton>
-          </Box>
+          <Box sx={styles.actions}>{actions}</Box>
         </Box>
 
         <Collapse in={!effectivelyCollapsed}>
@@ -126,4 +143,10 @@ export function LegendRow({ layerId, children }: LegendRowProps) {
       </Box>
     </LegendRowContext.Provider>
   )
+
+  return sortable ? (
+    <SortableEntity kind='layer' id={layerId} render={renderRow} />
+  ) : (
+    renderRow()
+  )
 }

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

@@ -6,6 +6,8 @@ export const styles = {
   row: {
     display: 'flex',
     flexDirection: 'column',
+    position: 'relative',
+
     '& + &': {
       borderTop: '1px solid',
       borderColor: 'divider',
@@ -38,6 +40,28 @@ export const styles = {
     '&:hover .PsLegend-value, &:focus-within .PsLegend-value': {
       opacity: 1,
     },
+    // Drag handle (Legend.Sortable): absolutely positioned (no reserved flex
+    // slot, so it never shifts the title/icon); the button inside fades in
+    // on hover/focus and is always visible on touch devices.
+    '& .PsLegend-dragHandle-layer > *': {
+      opacity: 0,
+      transition: ({ transitions }: Theme) =>
+        transitions.create('opacity', {
+          duration: transitions.duration.standard,
+          easing: transitions.easing.easeInOut,
+        }),
+      '@media (hover: none)': {
+        opacity: 1,
+      },
+    },
+    '&:hover .PsLegend-dragHandle-layer > *, &:focus-within .PsLegend-dragHandle-layer > *':
+      {
+        opacity: 1,
+      },
+  },
+  // The original stays in place, dimmed, while its overlay clone is dragged.
+  rowDragging: {
+    opacity: 0.4,
   },
   // Figma `_Legend header`: 16px top/left inset (title glyphs start at
   // y≈17, x=16 in the 68px-tall header), actions share the title's vertical
@@ -63,6 +87,17 @@ export const styles = {
     display: 'flex',
     flexDirection: 'column',
   },
+  // Accordion click target (whole title block + spare space). Non-native
+  // button, so it carries its own focus ring.
+  titleBoxInteractive: {
+    cursor: 'pointer',
+    userSelect: 'none',
+    '&:focus-visible': {
+      outline: '2px solid',
+      outlineColor: 'primary.main',
+      outlineOffset: -2,
+    },
+  },
   // The title line and the actions box share the same 24px band, centered,
   // so the title and the action icons stay aligned under the header's
   // `flex-start` — no padding magic. The subtitle flows below.
@@ -70,14 +105,32 @@ export const styles = {
     minHeight: 24,
     display: 'flex',
     alignItems: 'center',
+    gap: 0.5,
   },
   title: {
-    flex: 1,
     minWidth: 0,
     overflow: 'hidden',
     textOverflow: 'ellipsis',
     whiteSpace: 'nowrap',
   },
+  // Informative collapse indicator beside the title (the title area is the
+  // button). Points down when expanded, right when collapsed; not shown on
+  // touch devices — there the title row itself is the affordance.
+  chevron: {
+    fontSize: 16,
+    color: 'text.secondary',
+    flexShrink: 0,
+    transition: ({ transitions }: Theme) =>
+      transitions.create('transform', {
+        duration: transitions.duration.shorter,
+      }),
+    '@media (hover: none)': {
+      display: 'none',
+    },
+  },
+  chevronCollapsed: {
+    transform: 'rotate(-90deg)',
+  },
   // Same 24px band as the title line, so both sides of the header stay
   // aligned even when the composed actions are shorter (or fade out).
   // Icon buttons (actions + collapse chevron) are squeezed to 24×24:

package/src/legend/components/legend-row-menu/legend-row-menu-items.tsx

@@ -0,0 +1,57 @@
+import { MenuItem } from '@mui/material'
+import { getLegendStore, selectLayersByGroup, useLegendId } from '../../stores'
+import { useLegendConfig } from '../../provider'
+import { useLegendGroupId, useLegendRow } from '../contexts'
+
+/**
+ * Show only this layer (and hide siblings in the same bucket).
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export function LegendShowOnlyLayer() {
+  const id = useLegendId()
+  const row = useLegendRow()
+  const { labels } = useLegendConfig()
+
+  if (!row) return null
+
+  const showOnly = () => {
+    const state = getLegendStore(id).getState()
+    const target = state.layers[row.layerId]
+    // No-op if the layer vanished (e.g. a provider resync while the menu was
+    // open) — otherwise `groupId: undefined` would act on the ungrouped bucket.
+    if (!target) return
+    for (const layer of selectLayersByGroup(state, target.groupId)) {
+      state.setVisibility(layer.id, layer.id === row.layerId)
+    }
+  }
+
+  return <MenuItem onClick={showOnly}>{labels.showOnlyLayer}</MenuItem>
+}
+
+/**
+ * Show all layers in the enclosing group, or all ungrouped layers at row scope.
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export function LegendShowAllLayers() {
+  const id = useLegendId()
+  const groupId = useLegendGroupId()
+  const row = useLegendRow()
+  const { labels } = useLegendConfig()
+
+  if (groupId === null && !row) return null
+
+  const showAll = () => {
+    const state = getLegendStore(id).getState()
+    if (groupId !== null) {
+      state.setGroupVisibility(groupId, true)
+    } else {
+      for (const layer of selectLayersByGroup(state, undefined)) {
+        state.setVisibility(layer.id, true)
+      }
+    }
+  }
+
+  return <MenuItem onClick={showAll}>{labels.showAllLayers}</MenuItem>
+}

package/src/legend/components/legend-row-menu/legend-row-menu.tsx

@@ -1,68 +1,30 @@
-import { useState, type MouseEvent, type ReactNode } from 'react'
-import { IconButton, Menu } from '@mui/material'
-import { MoreVert as MoreVertIcon } from '@mui/icons-material'
-import { useLegendId, useLegendStore } from '../../stores'
+import type { ReactNode } from 'react'
 import { useLegendConfig } from '../../provider'
 import { useLegendRow } from '../contexts'
+import { LegendOverflowMenu } from '../legend-overflow-menu/legend-overflow-menu'
 
 export interface LegendRowMenuProps {
-  /**
-   * The menu items — composed by the consumer (e.g. `<Legend.ZoomTo>` or any
-   * MUI `MenuItem`). A click on any item bubbles to the menu and closes it;
-   * an item that must keep the menu open should `event.stopPropagation()`.
-   */
+  /** Menu items; async items use `stopPropagation` + `runAsyncMenuAction`. */
   children?: ReactNode
 }
 
 /**
- * Agnostic overflow (⋮) menu shell for a layer row — the items are passed as
- * children, like `Legend.Actions`. Renders nothing without children, outside
- * a row, or while the layer is hidden (a hidden row keeps only its
- * visibility eye + collapse chevron).
+ * Overflow (⋮) menu for a layer row. Pins `.active` while open, busy, or the
+ * inline opacity bar is open. Items self-gate when hidden.
  *
  * @experimental This API is new and may change in a future release.
  */
 export function LegendRowMenu({ children }: LegendRowMenuProps) {
-  const id = useLegendId()
-  const [anchorEl, setAnchorEl] = useState<HTMLElement | null>(null)
-  const open = Boolean(anchorEl)
   const row = useLegendRow()
-  const visible = useLegendStore(id, (s) =>
-    row ? (s.layers[row.layerId]?.visible ?? true) : true,
-  )
   const { labels } = useLegendConfig()
 
-  if (!row || !children || !visible) return null
-
-  const handleOpen = (e: MouseEvent<HTMLElement>) => {
-    e.stopPropagation()
-    setAnchorEl(e.currentTarget)
-  }
-  const handleClose = () => setAnchorEl(null)
-
   return (
-    <>
-      <IconButton
-        size='small'
-        className={open ? 'active' : undefined}
-        disabled={!visible}
-        onClick={handleOpen}
-        aria-label={labels.layerOptions}
-        aria-haspopup='menu'
-        aria-expanded={open}
-      >
-        <MoreVertIcon fontSize='small' />
-      </IconButton>
-      {/* Menu-level onClick: any item click (bubbling) closes the menu, so
-          consumer items need no legend wiring. */}
-      <Menu
-        anchorEl={anchorEl}
-        open={open}
-        onClose={handleClose}
-        onClick={handleClose}
-      >
-        {children}
-      </Menu>
-    </>
+    <LegendOverflowMenu
+      gate={Boolean(row)}
+      ariaLabel={labels.layerOptions}
+      active={row?.opacityOpen ?? false}
+    >
+      {children}
+    </LegendOverflowMenu>
   )
 }

package/src/legend/components/legend-row-menu/legend-zoom-to.tsx

@@ -1,35 +1,43 @@
-import { ListItemIcon, MenuItem } from '@mui/material'
-import { CenterFocusStrong as ZoomIcon } from '@mui/icons-material'
+import type { MouseEvent } from 'react'
+import { CircularProgress, MenuItem } from '@mui/material'
+import { useLegendId, useLegendStore } from '../../stores'
 import { useLegendConfig } from '../../provider'
-import { useLegendRow } from '../contexts'
+import { useLegendMenu, useLegendRow } from '../contexts'
+import { runAsyncMenuAction } from '../run-async-menu-action'
 
 export interface LegendZoomToProps {
-  /**
-   * Fit the map viewport to the layer. The handler lives at the composition
-   * site (not the Provider) — each menu can wire its own behavior.
-   */
-  onZoomTo: (layerId: string) => void
+  /** Fit viewport to the layer; may return a Promise for async menu feedback. */
+  onZoomTo: (layerId: string) => void | Promise<void>
 }
 
 /**
- * "Zoom to" menu item for `Legend.RowMenu` — resolves its layer from the
- * enclosing `Legend.Row` context and calls the `onZoomTo` it was composed
- * with. The click bubbles to the menu, which closes itself.
+ * Zoom-to-layer menu item for `Legend.RowMenu`. Self-hides when the layer is hidden.
  *
  * @experimental This API is new and may change in a future release.
  */
 export function LegendZoomTo({ onZoomTo }: LegendZoomToProps) {
+  const id = useLegendId()
   const row = useLegendRow()
+  const menu = useLegendMenu()
+  const visible = useLegendStore(id, (s) =>
+    row ? (s.layers[row.layerId]?.visible ?? false) : false,
+  )
   const { labels } = useLegendConfig()
 
-  if (!row) return null
+  if (!row || !visible) return null
+
+  const busy = menu?.busy ?? false
+
+  const handleClick = (e: MouseEvent) => {
+    e.stopPropagation()
+    if (!menu) return
+    void runAsyncMenuAction(menu, () => onZoomTo(row.layerId))
+  }
 
   return (
-    <MenuItem onClick={() => onZoomTo(row.layerId)}>
-      <ListItemIcon>
-        <ZoomIcon fontSize='small' />
-      </ListItemIcon>
-      {labels.zoomTo}
+    <MenuItem disabled={busy} onClick={handleClick}>
+      {busy && <CircularProgress size={16} sx={{ mr: 1 }} />}
+      {busy ? labels.loading : labels.zoomTo}
     </MenuItem>
   )
 }

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

@@ -0,0 +1,12 @@
+import { createContext, useContext } from 'react'
+
+/**
+ * Present (true) below a `<Legend.Sortable>` wrapper — `Legend.Group` /
+ * `Legend.Row` read it to become draggable (sortable shell + drag handle).
+ */
+export const LegendSortableContext = createContext(false)
+
+/** Whether the nearest legend composition is wrapped in `Legend.Sortable`. */
+export function useLegendSortable(): boolean {
+  return useContext(LegendSortableContext)
+}

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

@@ -0,0 +1,144 @@
+/**
+ * Drives `Legend.Sortable`'s onDragEnd through the shared dnd-kit mock
+ * harness (DndContext passthrough exposing its props) against the **real**
+ * legend store — asserting the committed `moveGroup` / `moveLayer` effects
+ * and the cross-kind/cross-bucket guards.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import {
+  dndKitCoreMock,
+  dndKitSortableMock,
+  lastDndContextProps,
+  resetDndKitMocks,
+} from '../../../../tests/mocks/dnd-kit'
+
+vi.mock('@dnd-kit/core', () => dndKitCoreMock())
+vi.mock('@dnd-kit/sortable', () => dndKitSortableMock())
+
+import { LegendProvider } from '../../provider'
+import { LegendGroup } from '../legend-group/legend-group'
+import { LegendRow } from '../legend-row/legend-row'
+import { LegendItem } from '../legend-item/legend-item'
+import { LegendSortable } from './legend-sortable'
+import {
+  clearAllLegendStores,
+  getLegendStore,
+  selectLayersByGroup,
+  selectOrderedGroups,
+  type LegendVariable,
+} from '../../stores'
+
+const cat: LegendVariable = {
+  type: 'category',
+  items: [{ label: 'A', color: '#123456' }],
+}
+
+const layers = [
+  { id: 'a', name: 'Alpha', groupId: 'g1', variables: [cat] },
+  { id: 'b', name: 'Beta', groupId: 'g1', variables: [cat] },
+  { id: 'c', name: 'Gamma', groupId: 'g2', variables: [cat] },
+  { id: 'x', name: 'Loose X', variables: [cat] },
+  { id: 'y', name: 'Loose Y', variables: [cat] },
+]
+const groups = [
+  { id: 'g1', label: 'One' },
+  { id: 'g2', label: 'Two' },
+]
+
+beforeEach(() => resetDndKitMocks())
+afterEach(() => clearAllLegendStores())
+
+function renderSortable(id: string, sortable = true) {
+  const tree = (
+    <>
+      {groups.map((g) => (
+        <LegendGroup key={g.id} groupId={g.id}>
+          {layers
+            .filter((l) => l.groupId === g.id)
+            .map((l) => (
+              <LegendRow key={l.id} layerId={l.id}>
+                <LegendItem />
+              </LegendRow>
+            ))}
+        </LegendGroup>
+      ))}
+      {layers
+        .filter((l) => !l.groupId)
+        .map((l) => (
+          <LegendRow key={l.id} layerId={l.id}>
+            <LegendItem />
+          </LegendRow>
+        ))}
+    </>
+  )
+  return render(
+    <LegendProvider id={id} layers={layers} groups={groups}>
+      {sortable ? <LegendSortable>{tree}</LegendSortable> : tree}
+    </LegendProvider>,
+  )
+}
+
+const dragEnd = (activeId: string, overId: string | null) =>
+  lastDndContextProps().onDragEnd?.({
+    active: { id: activeId },
+    over: overId ? { id: overId } : null,
+  })
+
+describe('<LegendSortable> opt-in', () => {
+  it('without the wrapper there are no drag handles', () => {
+    renderSortable('plain', false)
+    expect(screen.queryAllByLabelText('Reorder')).toHaveLength(0)
+  })
+
+  it('with the wrapper every group and row exposes its handle', () => {
+    renderSortable('handles')
+    // 2 groups + 5 rows.
+    expect(screen.getAllByLabelText('Reorder')).toHaveLength(7)
+  })
+})
+
+describe('<LegendSortable> onDragEnd commits', () => {
+  it('group over group → moveGroup', () => {
+    renderSortable('dnd-groups')
+    dragEnd('group:g2', 'group:g1')
+    expect(
+      selectOrderedGroups(getLegendStore('dnd-groups').getState()).map(
+        (g) => g.id,
+      ),
+    ).toEqual(['g2', 'g1'])
+  })
+
+  it('layer over layer in the same bucket → moveLayer', () => {
+    renderSortable('dnd-rows')
+    dragEnd('layer:b', 'layer:a')
+    expect(
+      selectLayersByGroup(getLegendStore('dnd-rows').getState(), 'g1').map(
+        (l) => l.id,
+      ),
+    ).toEqual(['b', 'a'])
+
+    // Ungrouped bucket too.
+    dragEnd('layer:y', 'layer:x')
+    expect(
+      selectLayersByGroup(getLegendStore('dnd-rows').getState(), undefined).map(
+        (l) => l.id,
+      ),
+    ).toEqual(['y', 'x'])
+  })
+
+  it('cross-kind and cross-bucket drops are ignored (snap back)', () => {
+    renderSortable('dnd-guards')
+    const before = getLegendStore('dnd-guards').getState().layers
+    const beforeGroups = getLegendStore('dnd-guards').getState().groups
+
+    dragEnd('group:g1', 'layer:x') // group over a row
+    dragEnd('layer:a', 'group:g2') // row over a group
+    dragEnd('layer:a', 'layer:c') // row over another group's row
+    dragEnd('layer:a', 'layer:x') // grouped row over an ungrouped one
+    dragEnd('layer:a', null) // dropped outside
+
+    expect(getLegendStore('dnd-guards').getState().layers).toBe(before)
+    expect(getLegendStore('dnd-guards').getState().groups).toBe(beforeGroups)
+  })
+})