@carto/ps-react-ui 4.14.1 → 4.16.0

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,158 @@ 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)
   })
 })
+
+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,37 @@
 import type { ReactNode } from 'react'
-import { Box, Collapse, IconButton, Typography } from '@mui/material'
+import { Box, Collapse, Typography } from '@mui/material'
 import {
   LayersOutlined as GroupIcon,
   ExpandMore as ExpandMoreIcon,
-  ExpandLess as ExpandLessIcon,
 } 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 +39,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>
-            )}
-          </SmartTooltip>
+          {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)}
+          >
+            <Box sx={styles.groupIcon}>
+              <GroupIcon fontSize='small' />
+            </Box>
 
-          <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',

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

@@ -0,0 +1,132 @@
+import type { MouseEvent } from 'react'
+import { CircularProgress, MenuItem } from '@mui/material'
+import {
+  getLegendStore,
+  selectAllGroupsCollapsed,
+  selectGroupVisibility,
+  selectHasGroups,
+  selectLayersByGroup,
+  selectOrderedGroups,
+  useLegendId,
+  useLegendStore,
+} from '../../stores'
+import { useLegendConfig } from '../../provider'
+import { useLegendGroupId, useLegendMenu } from '../contexts'
+import { runAsyncMenuAction } from '../run-async-menu-action'
+
+/**
+ * Show only this group (hide all other layers).
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export function LegendShowOnlyGroup() {
+  const id = useLegendId()
+  const groupId = useLegendGroupId()
+  const { labels } = useLegendConfig()
+
+  if (groupId === null) return null
+
+  const showOnly = () => {
+    const state = getLegendStore(id).getState()
+    for (const group of selectOrderedGroups(state)) {
+      state.setGroupVisibility(group.id, group.id === groupId)
+    }
+    // Exclusive: the ungrouped layers hide too.
+    for (const layer of selectLayersByGroup(state, undefined)) {
+      state.setVisibility(layer.id, false)
+    }
+  }
+
+  return <MenuItem onClick={showOnly}>{labels.showOnlyGroup}</MenuItem>
+}
+
+/**
+ * Show every layer (panel-level `Legend.PanelMenu` only).
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export function LegendShowAllGroups() {
+  const id = useLegendId()
+  const hasGroups = useLegendStore(id, selectHasGroups)
+  const { labels } = useLegendConfig()
+
+  if (!hasGroups) return null
+
+  const showAll = () => {
+    const state = getLegendStore(id).getState()
+    for (const group of selectOrderedGroups(state)) {
+      state.setGroupVisibility(group.id, true)
+    }
+    for (const layer of selectLayersByGroup(state, undefined)) {
+      state.setVisibility(layer.id, true)
+    }
+  }
+
+  return <MenuItem onClick={showAll}>{labels.showAllGroups}</MenuItem>
+}
+
+/**
+ * Collapse / expand all groups (panel-level `Legend.PanelMenu` only).
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export function LegendCollapseAllGroups() {
+  const id = useLegendId()
+  const hasGroups = useLegendStore(id, selectHasGroups)
+  const allCollapsed = useLegendStore(id, selectAllGroupsCollapsed)
+  const { labels } = useLegendConfig()
+
+  if (!hasGroups) return null
+
+  const toggleAll = () => {
+    const state = getLegendStore(id).getState()
+    const collapsed = selectAllGroupsCollapsed(state)
+    for (const group of selectOrderedGroups(state)) {
+      state.setGroupCollapsed(group.id, !collapsed)
+    }
+  }
+
+  return (
+    <MenuItem onClick={toggleAll}>
+      {allCollapsed ? labels.expandAllGroups : labels.collapseAllGroups}
+    </MenuItem>
+  )
+}
+
+export interface LegendZoomToGroupProps {
+  /** Fit viewport to the group; may return a Promise for async menu feedback. */
+  onZoomTo: (groupId: string) => void | Promise<void>
+}
+
+/**
+ * Zoom-to-group menu item for `Legend.GroupMenu`. Self-hides when all members are hidden.
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export function LegendZoomToGroup({ onZoomTo }: LegendZoomToGroupProps) {
+  const id = useLegendId()
+  const groupId = useLegendGroupId()
+  const menu = useLegendMenu()
+  const hidden = useLegendStore(
+    id,
+    (s) => groupId !== null && selectGroupVisibility(s, groupId) === 'hidden',
+  )
+  const { labels } = useLegendConfig()
+
+  if (groupId === null || hidden) return null
+
+  const busy = menu?.busy ?? false
+
+  const handleClick = (e: MouseEvent) => {
+    e.stopPropagation()
+    if (!menu) return
+    void runAsyncMenuAction(menu, () => onZoomTo(groupId))
+  }
+
+  return (
+    <MenuItem disabled={busy} onClick={handleClick}>
+      {busy && <CircularProgress size={16} sx={{ mr: 1 }} />}
+      {busy ? labels.loading : labels.zoomToGroup}
+    </MenuItem>
+  )
+}

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

@@ -0,0 +1,25 @@
+import type { ReactNode } from 'react'
+import { useLegendConfig } from '../../provider'
+import { useLegendGroupId } from '../contexts'
+import { LegendOverflowMenu } from '../legend-overflow-menu/legend-overflow-menu'
+
+export interface LegendGroupMenuProps {
+  /** Menu items; async items use `stopPropagation` + `runAsyncMenuAction`. */
+  children?: ReactNode
+}
+
+/**
+ * Overflow (⋮) menu for a group header. Renders nothing outside a `Legend.Group`.
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export function LegendGroupMenu({ children }: LegendGroupMenuProps) {
+  const groupId = useLegendGroupId()
+  const { labels } = useLegendConfig()
+
+  return (
+    <LegendOverflowMenu gate={groupId !== null} ariaLabel={labels.groupOptions}>
+      {children}
+    </LegendOverflowMenu>
+  )
+}