@carto/ps-react-ui 4.15.0 → 4.17.0

package/src/legend/components/contexts.ts

@@ -3,13 +3,11 @@ import { createContext, useContext } from 'react'
 /**
  * Per-row composition context provided by `Legend.Row`. Actions placed inside
  * the row resolve their target layer from here instead of taking a `layerId`
- * prop, and the opacity compound shares its popover state through it (the
- * popover anchors to the row's sticky header element to span its full width).
+ * prop, and the opacity compound (`Legend.Opacity.Item` / `.Inline`) shares
+ * its open state through it.
  */
 export interface LegendRowContextValue {
   layerId: string
-  /** The row's sticky header element — anchor for `Legend.Opacity.Popover`. */
-  headerEl: HTMLElement | null
   opacityOpen: boolean
   setOpacityOpen: (open: boolean) => void
 }
@@ -30,3 +28,30 @@ export const LegendGroupContext = createContext<string | null>(null)
 export function useLegendGroupId(): string | null {
   return useContext(LegendGroupContext)
 }
+
+/**
+ * Overflow-menu controller for `Legend.RowMenu` / `Legend.GroupMenu` /
+ * `Legend.PanelMenu`. Async items (e.g. `Legend.ZoomTo`) use `setBusy` to keep
+ * the menu open and show in-item loading feedback, then `close()` when the
+ * handler settles. Prefer `runAsyncMenuAction` over calling these by hand.
+ */
+export interface LegendMenuController {
+  /** Reactive busy flag for UI (spinner / disabled). */
+  busy: boolean
+  /**
+   * Synchronous busy check (ref-backed) — use this to gate clicks so a second
+   * press before React re-renders cannot start another async action.
+   */
+  isBusy: () => boolean
+  setBusy: (busy: boolean) => void
+  close: () => void
+}
+
+export const LegendMenuContext = createContext<LegendMenuController | null>(
+  null,
+)
+
+/** Nearest overflow-menu controller, or `null` outside a row/group menu. */
+export function useLegendMenu(): LegendMenuController | null {
+  return useContext(LegendMenuContext)
+}

package/src/legend/components/index.ts

@@ -1,4 +1,3 @@
-// Composition shell
 export { LegendGroup } from './legend-group/legend-group'
 export type { LegendGroupProps } from './legend-group/legend-group'
 export { LegendRow } from './legend-row/legend-row'
@@ -8,12 +7,13 @@ export type { LegendActionsProps } from './legend-actions/legend-actions'
 export {
   LegendRowContext,
   LegendGroupContext,
+  LegendMenuContext,
   useLegendRow,
   useLegendGroupId,
+  useLegendMenu,
 } from './contexts'
-export type { LegendRowContextValue } from './contexts'
+export type { LegendRowContextValue, LegendMenuController } from './contexts'
 
-// Store-connected actions & controls (context-driven)
 export { LegendVisibilityToggle } from './legend-visibility-toggle/legend-visibility-toggle'
 export { LegendRowMenu } from './legend-row-menu/legend-row-menu'
 export { LegendZoomTo } from './legend-row-menu/legend-zoom-to'
@@ -21,7 +21,6 @@ export { LegendOpacity } from './legend-opacity/legend-opacity'
 export { LegendConfigSelect } from './legend-config-select/legend-config-select'
 export { LegendItem } from './legend-item/legend-item'
 
-// Item renderers (pure UI)
 export { LegendItemUI } from './legend-item/legend-item-ui'
 export type { LegendItemUIProps } from './legend-item/legend-item-ui'
 export {

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

@@ -15,9 +15,10 @@ export interface LegendActionsProps {
 /**
  * Header actions slot for `Legend.Row` / `Legend.Group` (widgets-v2 `Actions`
  * parity): the wrapper partitions its children by component identity and
- * renders this slot inside the header, next to the collapse chevron, wrapped
- * in the hover-fade group (`PsLegend-rowFade` in rows, `PsLegend-groupFade`
- * in group headers — resolved from the nearest context).
+ * renders this slot inside the header, wrapped in the hover-fade group
+ * (`PsLegend-rowFade` in rows, `PsLegend-groupFade` in group headers —
+ * resolved from the nearest context). Compose the ⋮ menu last so it sits
+ * rightmost, per design.
  *
  * @experimental This API is new and may change in a future release.
  */

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

@@ -1,10 +1,18 @@
-import { afterEach, describe, it, expect } from 'vitest'
+import { afterEach, describe, it, expect, vi } from 'vitest'
 import { fireEvent, render, screen } from '@testing-library/react'
 import { LegendProvider } from '../../provider'
 import { LegendGroup } from './legend-group'
 import { LegendRow } from '../legend-row/legend-row'
 import { LegendActions } from '../legend-actions/legend-actions'
 import { LegendVisibilityToggle } from '../legend-visibility-toggle/legend-visibility-toggle'
+import { LegendGroupMenu } from '../legend-group-menu/legend-group-menu'
+import {
+  LegendShowOnlyGroup,
+  LegendShowAllGroups,
+  LegendCollapseAllGroups,
+  LegendZoomToGroup,
+} from '../legend-group-menu/legend-group-menu-items'
+import { LegendShowAllLayers } from '../legend-row-menu/legend-row-menu-items'
 import {
   clearAllLegendStores,
   getLegendStore,
@@ -70,10 +78,16 @@ describe('<LegendGroup> composition', () => {
     expect(state.layers.b!.visible).toBe(true)
   })
 
-  it('toggles group collapse through the store', () => {
+  it('clicking the title row toggles group collapse (accordion header)', () => {
     renderGroup('g-col')
-    fireEvent.click(screen.getByLabelText('Collapse group'))
+    const header = screen.getByRole('button', { name: 'Demographics' })
+    expect(header.getAttribute('aria-expanded')).toBe('true')
+    fireEvent.click(header)
     expect(getLegendStore('g-col').getState().groups.g1!.collapsed).toBe(true)
+    expect(header.getAttribute('aria-expanded')).toBe('false')
+    // Keyboard parity: Enter re-expands.
+    fireEvent.keyDown(header, { key: 'Enter' })
+    expect(getLegendStore('g-col').getState().groups.g1!.collapsed).toBe(false)
   })
 
   it('shows the indeterminate icon (mixed) when only some layers are hidden', () => {
@@ -101,15 +115,183 @@ describe('<LegendGroup> composition', () => {
     expect(screen.getByLabelText('Show group').className).toContain('active')
   })
 
-  it('hiding the group collapses it, but the chevron stays usable', () => {
+  it('hiding the group collapses it, but the title row stays usable', () => {
     renderGroup('g-hide')
     fireEvent.click(screen.getByLabelText('Hide group'))
     expect(getLegendStore('g-hide').getState().groups.g1!.collapsed).toBe(true)
-    // The chevron reads "Expand group" and is NOT disabled — a hidden group
-    // can be peeked into to re-show layers one by one.
-    const chevron = screen.getByLabelText<HTMLButtonElement>('Expand group')
-    expect(chevron.disabled).toBe(false)
-    fireEvent.click(chevron)
+    // Groups are never force-collapsed by visibility — a hidden group can be
+    // peeked into to re-show layers one by one.
+    const header = screen.getByRole('button', { name: 'Demographics' })
+    fireEvent.click(header)
     expect(getLegendStore('g-hide').getState().groups.g1!.collapsed).toBe(false)
   })
+
+  it('renders no icon when the group has no icon configured', () => {
+    renderGroup('g-icon-none')
+    expect(screen.queryByTestId('LayersOutlinedIcon')).toBeNull()
+    expect(screen.queryByTestId('my-icon')).toBeNull()
+  })
+
+  it('renders the custom icon when provided', () => {
+    render(
+      <LegendProvider
+        id='g-icon-custom'
+        layers={layers}
+        groups={[
+          {
+            id: 'g1',
+            label: 'Demographics',
+            icon: <span data-testid='my-icon' />,
+          },
+        ]}
+      >
+        <LegendGroup groupId='g1' />
+      </LegendProvider>,
+    )
+    expect(screen.getByTestId('my-icon')).toBeTruthy()
+  })
+})
+
+describe('<LegendGroupMenu> + built-in items', () => {
+  function renderWithMenu(id: string) {
+    return render(
+      <LegendProvider
+        id={id}
+        layers={[...layers, { id: 'solo', name: 'Solo', variables: [cat] }]}
+        groups={[...groups, { id: 'g2', label: 'Business' }]}
+      >
+        <LegendGroup groupId='g1'>
+          <LegendActions>
+            <LegendVisibilityToggle />
+            <LegendGroupMenu>
+              <LegendShowOnlyGroup />
+              <LegendShowAllGroups />
+              <LegendCollapseAllGroups />
+              <LegendZoomToGroup onZoomTo={zoomSpy} />
+            </LegendGroupMenu>
+          </LegendActions>
+        </LegendGroup>
+      </LegendProvider>,
+    )
+  }
+  const zoomSpy = vi.fn()
+
+  it('Show only this group hides other groups and ungrouped layers', () => {
+    renderWithMenu('gm-only')
+    fireEvent.click(screen.getByLabelText('Group options'))
+    fireEvent.click(screen.getByText('Show only this group'))
+    const state = getLegendStore('gm-only').getState()
+    expect(state.layers.a!.visible).toBe(true)
+    expect(state.layers.solo!.visible).toBe(false)
+    // Menu closed after the pick.
+    expect(screen.queryByRole('menuitem')).toBeNull()
+
+    fireEvent.click(screen.getByLabelText('Group options'))
+    fireEvent.click(screen.getByText('Show all groups'))
+    expect(getLegendStore('gm-only').getState().layers.solo!.visible).toBe(true)
+  })
+
+  it('Collapse all groups toggles and flips its label', () => {
+    renderWithMenu('gm-collapse')
+    fireEvent.click(screen.getByLabelText('Group options'))
+    fireEvent.click(screen.getByText('Collapse all groups'))
+    const state = getLegendStore('gm-collapse').getState()
+    expect(state.groups.g1!.collapsed).toBe(true)
+    expect(state.groups.g2!.collapsed).toBe(true)
+    // Reopen: the item now offers Expand.
+    fireEvent.click(screen.getByLabelText('Group options'))
+    fireEvent.click(screen.getByText('Expand all groups'))
+    expect(getLegendStore('gm-collapse').getState().groups.g1!.collapsed).toBe(
+      false,
+    )
+  })
+
+  it('Zoom to group fires the composed handler with the group id', async () => {
+    renderWithMenu('gm-zoom')
+    fireEvent.click(screen.getByLabelText('Group options'))
+    fireEvent.click(screen.getByText('Zoom to group'))
+    expect(zoomSpy).toHaveBeenCalledWith('g1')
+    await vi.waitFor(() => {
+      expect(screen.queryByRole('menuitem')).toBeNull()
+    })
+  })
+
+  it('Zoom to group keeps the menu open with loading feedback while pending', async () => {
+    let resolveZoom!: () => void
+    const pendingZoom = vi.fn(
+      () =>
+        new Promise<void>((resolve) => {
+          resolveZoom = resolve
+        }),
+    )
+    render(
+      <LegendProvider id='gm-zoom-busy' layers={layers} groups={groups}>
+        <LegendGroup groupId='g1'>
+          <LegendActions>
+            <LegendGroupMenu>
+              <LegendZoomToGroup onZoomTo={pendingZoom} />
+            </LegendGroupMenu>
+          </LegendActions>
+        </LegendGroup>
+      </LegendProvider>,
+    )
+    fireEvent.click(screen.getByLabelText('Group options'))
+    fireEvent.click(screen.getByText('Zoom to group'))
+    expect(pendingZoom).toHaveBeenCalledWith('g1')
+    const item = await screen.findByRole('menuitem', { name: /Loading/ })
+    expect(item.getAttribute('aria-disabled')).toBe('true')
+    expect(screen.getByRole('progressbar')).toBeDefined()
+
+    resolveZoom()
+    await vi.waitFor(() => {
+      expect(screen.queryByRole('menuitem')).toBeNull()
+    })
+  })
+
+  it('Show all layers composed directly in the group menu targets only that group', () => {
+    render(
+      <LegendProvider
+        id='gm-showall-group'
+        layers={[...layers, { id: 'solo', name: 'Solo', variables: [cat] }]}
+        groups={groups}
+      >
+        <LegendGroup groupId='g1'>
+          <LegendActions>
+            <LegendVisibilityToggle />
+            <LegendGroupMenu>
+              <LegendShowAllLayers />
+            </LegendGroupMenu>
+          </LegendActions>
+        </LegendGroup>
+      </LegendProvider>,
+    )
+    getLegendStore('gm-showall-group').getState().setVisibility('a', false)
+    getLegendStore('gm-showall-group').getState().setVisibility('b', false)
+    getLegendStore('gm-showall-group').getState().setVisibility('solo', false)
+
+    fireEvent.click(screen.getByLabelText('Group options'))
+    fireEvent.click(screen.getByText('Show all layers'))
+    const state = getLegendStore('gm-showall-group').getState()
+    expect(state.layers.a!.visible).toBe(true)
+    expect(state.layers.b!.visible).toBe(true)
+    // Ungrouped sibling untouched — this instance only affects g1.
+    expect(state.layers.solo!.visible).toBe(false)
+  })
+})
+
+describe('panel-wide group actions with no groups', () => {
+  it('ShowAllGroups / CollapseAllGroups render null when the legend has no groups', () => {
+    render(
+      <LegendProvider
+        id='no-groups'
+        layers={[{ id: 'solo', name: 'Solo', variables: [cat] }]}
+        groups={[]}
+      >
+        <LegendShowAllGroups />
+        <LegendCollapseAllGroups />
+      </LegendProvider>,
+    )
+    expect(screen.queryByText('Show all groups')).toBeNull()
+    expect(screen.queryByText('Collapse all groups')).toBeNull()
+  })
 })

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

@@ -1,34 +1,34 @@
 import type { ReactNode } from 'react'
-import { Box, Collapse, IconButton, Typography } from '@mui/material'
-import {
-  LayersOutlined as GroupIcon,
-  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 { SortableContext, verticalListSortingStrategy } from '@dnd-kit/sortable'
 import { SmartTooltip } from '../../../components/smart-tooltip/smart-tooltip'
-import { useLegendId, useLegendShallow } from '../../stores'
-import { useLegendConfig } from '../../provider'
+import {
+  selectGroupVisibility,
+  selectLayersByGroup,
+  useLegendId,
+  useLegendShallow,
+  useLegendStore,
+} from '../../stores'
+import { accordionKeyDown } from '../a11y'
 import { LegendGroupContext } from '../contexts'
 import { partitionLegendChildren } from '../legend-actions/legend-actions'
+import { useLegendSortable } from '../legend-sortable/contexts'
+import {
+  SortableEntity,
+  type SortableEntityRenderProps,
+} from '../legend-sortable/sortable-entity'
+import { toSortableId } from '../legend-sortable/sortable-ids'
 import { styles } from './styles'
 
 export interface LegendGroupProps {
   groupId: string
-  /**
-   * Composition slots: `<Legend.Actions>` children render in the sticky
-   * header (hover-fade); everything else is the collapsible body — the
-   * consumer renders the member `<Legend.Row>`s explicitly (use
-   * `selectLayersByGroup` to resolve them).
-   */
+  /** `<Legend.Actions>` in the sticky header; member `<Legend.Row>`s in the body. */
   children?: ReactNode
 }
 
 /**
- * Store-connected group wrapper (widgets-v2 `Wrapper` parity). Renders the
- * sticky 48px header — group icon + label from the store, the partitioned
- * `<Legend.Actions>` slot, and the collapse chevron — over the collapsible
- * body. Provides the group composition context so `Legend.VisibilityToggle`
- * placed in the header becomes the tri-state group eye.
+ * Store-connected group wrapper. Draggable inside `<Legend.Sortable>`.
  *
  * @experimental This API is new and may change in a future release.
  */
@@ -36,53 +36,89 @@ export function LegendGroup({ groupId, children }: LegendGroupProps) {
   const id = useLegendId()
   const group = useLegendShallow(id, (s) => s.groups[groupId])
   const setGroupCollapsed = useLegendShallow(id, (s) => s.setGroupCollapsed)
-  const { labels } = useLegendConfig()
+  const hidden = useLegendStore(
+    id,
+    (s) => selectGroupVisibility(s, groupId) === 'hidden',
+  )
+  const sortable = useLegendSortable()
+  // Member ids only — useShallow ignores opacity/visibility noise on siblings.
+  const memberSortableIds = useLegendShallow(id, (s) =>
+    selectLayersByGroup(s, groupId).map((l) => toSortableId('layer', l.id)),
+  )
 
   if (!group) return null
 
   const { actions, body } = partitionLegendChildren(children)
+  const toggle = () => setGroupCollapsed(groupId, !group.collapsed)
 
-  return (
+  const renderGroup = (sortableProps?: SortableEntityRenderProps) => (
     <LegendGroupContext.Provider value={groupId}>
-      <Box sx={styles.group}>
+      <Box
+        ref={sortableProps?.rootRef}
+        style={sortableProps?.rootStyle}
+        sx={[
+          styles.group,
+          sortableProps?.dragging === true && styles.groupDragging,
+        ]}
+      >
         <Box sx={styles.header}>
-          <Box sx={styles.groupIcon}>
-            <GroupIcon fontSize='small' />
-          </Box>
-
-          <SmartTooltip title={group.label} dependencies={[group.label]}>
-            {({ ref }) => (
-              <Typography
-                ref={ref}
-                variant='button'
-                color='text.primary'
-                sx={styles.label}
-              >
-                {group.label}
-              </Typography>
+          {sortableProps?.handle}
+          {/* Whole title area toggles collapse (accordion header); the
+              actions box is a sibling outside the click target. */}
+          <Box
+            sx={styles.titleArea}
+            role='button'
+            tabIndex={0}
+            aria-expanded={!group.collapsed}
+            onClick={toggle}
+            onKeyDown={accordionKeyDown(toggle)}
+          >
+            {group.icon != null && (
+              <Box sx={styles.groupIcon}>{group.icon}</Box>
             )}
-          </SmartTooltip>
 
-          <Box sx={styles.actions}>
-            {actions}
-            <IconButton
-              size='small'
-              onClick={() => setGroupCollapsed(groupId, !group.collapsed)}
-              aria-label={
-                group.collapsed ? labels.expandGroup : labels.collapseGroup
-              }
-            >
-              {group.collapsed ? (
-                <ExpandMoreIcon fontSize='small' />
-              ) : (
-                <ExpandLessIcon fontSize='small' />
+            <SmartTooltip title={group.label} dependencies={[group.label]}>
+              {({ ref }) => (
+                <Typography
+                  ref={ref}
+                  variant='button'
+                  fontWeight='bold'
+                  color={hidden ? 'text.disabled' : 'text.primary'}
+                  sx={styles.label}
+                >
+                  {group.label}
+                </Typography>
               )}
-            </IconButton>
+            </SmartTooltip>
+
+            {/* Informative only (the row is the button); hidden on touch. */}
+            <ExpandMoreIcon
+              sx={[styles.chevron, group.collapsed && styles.chevronCollapsed]}
+            />
           </Box>
+
+          <Box sx={styles.actions}>{actions}</Box>
         </Box>
 
-        <Collapse in={!group.collapsed}>{body}</Collapse>
+        <Collapse in={!group.collapsed}>
+          {sortable ? (
+            <SortableContext
+              items={memberSortableIds}
+              strategy={verticalListSortingStrategy}
+            >
+              {body}
+            </SortableContext>
+          ) : (
+            body
+          )}
+        </Collapse>
       </Box>
     </LegendGroupContext.Provider>
   )
+
+  return sortable ? (
+    <SortableEntity kind='group' id={groupId} render={renderGroup} />
+  ) : (
+    renderGroup()
+  )
 }

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

@@ -38,6 +38,28 @@ export const styles = {
     '&:hover .PsLegend-groupFade > *, &:focus-within .PsLegend-groupFade > *': {
       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-group > *': {
+      opacity: 0,
+      transition: ({ transitions }: Theme) =>
+        transitions.create('opacity', {
+          duration: transitions.duration.standard,
+          easing: transitions.easing.easeInOut,
+        }),
+      '@media (hover: none)': {
+        opacity: 1,
+      },
+    },
+    '&:hover .PsLegend-dragHandle-group > *, &:focus-within .PsLegend-dragHandle-group > *':
+      {
+        opacity: 1,
+      },
+  },
+  // The original stays in place, dimmed, while its overlay clone is dragged.
+  groupDragging: {
+    opacity: 0.4,
   },
   // Figma: 48px tall, icon at 12px from the left, 8px gap to the label,
   // actions right-aligned with ~8px edge inset (the small icon-button padding
@@ -56,19 +78,54 @@ export const styles = {
     // Above the sticky row headers (2), which in turn sit above MUI's
     // z-index-1 form internals in row content.
     zIndex: 3,
-    backgroundColor: 'background.paper',
+    // Distinct from the row header / panel body (both `background.paper`) so
+    // the group header visually separates from the rest.
+    backgroundColor: 'background.default',
+  },
+  // Accordion click target: everything in the header but the actions box.
+  // Non-native button (role='button'), so it carries its own focus ring.
+  titleArea: {
+    flex: 1,
+    minWidth: 0,
+    display: 'flex',
+    alignItems: 'center',
+    gap: 1,
+    cursor: 'pointer',
+    userSelect: 'none',
+    '&:focus-visible': {
+      outline: '2px solid',
+      outlineColor: 'primary.main',
+      outlineOffset: -2,
+    },
   },
   groupIcon: {
     display: 'flex',
     color: 'text.secondary',
   },
   label: {
-    flex: 1,
     minWidth: 0,
     overflow: 'hidden',
     textOverflow: 'ellipsis',
     whiteSpace: 'nowrap',
   },
+  // Informative collapse indicator beside the title (the whole title area is
+  // the button). Points down when expanded, right when collapsed. Touch
+  // devices don't get it — the title row is the affordance there.
+  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)',
+  },
   // Icon buttons match the row header's 24×24 (2px padding + 20px icon).
   actions: {
     display: 'flex',