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

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

@@ -0,0 +1,297 @@
+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,
+  type LegendGroupInput,
+  type LegendLayerInput,
+  type LegendVariable,
+} from '../../stores'
+
+const cat: LegendVariable = {
+  type: 'category',
+  items: [{ label: 'A', color: '#123456' }],
+}
+
+const groups: LegendGroupInput[] = [{ id: 'g1', label: 'Demographics' }]
+const layers: LegendLayerInput[] = [
+  { id: 'a', name: 'Alpha', variables: [cat], groupId: 'g1', order: 1 },
+  { id: 'b', name: 'Beta', variables: [cat], groupId: 'g1', order: 0 },
+]
+
+afterEach(() => clearAllLegendStores())
+
+/** Module-shaped composition: group eye in the header, explicit member rows. */
+function renderGroup(id: string) {
+  return render(
+    <LegendProvider id={id} layers={layers} groups={groups}>
+      <LegendGroup groupId='g1'>
+        <LegendActions>
+          <LegendVisibilityToggle />
+        </LegendActions>
+        {['b', 'a'].map((layerId) => (
+          <LegendRow key={layerId} layerId={layerId}>
+            <LegendActions>
+              <LegendVisibilityToggle />
+            </LegendActions>
+          </LegendRow>
+        ))}
+      </LegendGroup>
+    </LegendProvider>,
+  )
+}
+
+describe('<LegendGroup> composition', () => {
+  it('renders the label from the store, Actions in the header, rows in the body', () => {
+    const { container } = renderGroup('g-comp')
+    expect(screen.getByText('Demographics')).toBeTruthy()
+    // The group eye landed in the group fade slot of the header…
+    const fade = container.querySelector('.PsLegend-groupFade')!
+    expect(fade.contains(screen.getByLabelText('Hide group'))).toBe(true)
+    // …and both member rows render in the body.
+    expect(screen.getByText('Alpha')).toBeTruthy()
+    expect(screen.getByText('Beta')).toBeTruthy()
+  })
+
+  it('the group eye cascades visibility to every member layer', () => {
+    renderGroup('g-vis')
+    fireEvent.click(screen.getByLabelText('Hide group'))
+    let state = getLegendStore('g-vis').getState()
+    expect(state.layers.a!.visible).toBe(false)
+    expect(state.layers.b!.visible).toBe(false)
+    fireEvent.click(screen.getByLabelText('Show group'))
+    state = getLegendStore('g-vis').getState()
+    expect(state.layers.a!.visible).toBe(true)
+    expect(state.layers.b!.visible).toBe(true)
+  })
+
+  it('clicking the title row toggles group collapse (accordion header)', () => {
+    renderGroup('g-col')
+    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', () => {
+    renderGroup('g-mixed')
+    // Hide one member row via its own (row-context) eye.
+    fireEvent.click(screen.getAllByLabelText('Hide layer')[0]!)
+    // Mixed: the group eye still offers "Hide group", is pinned active, and
+    // renders the indeterminate glyph.
+    const eye = screen.getByLabelText('Hide group')
+    expect(eye.className).toContain('active')
+    expect(
+      eye.querySelector('[data-testid="VisibilityIndeterminateIcon"]'),
+    ).toBeTruthy()
+    // Clicking on mixed hides the remaining visible member.
+    fireEvent.click(eye)
+    const state = getLegendStore('g-mixed').getState()
+    expect(state.layers.a!.visible).toBe(false)
+    expect(state.layers.b!.visible).toBe(false)
+    expect(screen.getByLabelText('Show group')).toBeTruthy()
+  })
+
+  it('marks the visibility toggle active while the group is hidden', () => {
+    renderGroup('g-active')
+    fireEvent.click(screen.getByLabelText('Hide group'))
+    expect(screen.getByLabelText('Show group').className).toContain('active')
+  })
+
+  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)
+    // 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

@@ -0,0 +1,126 @@
+import type { ReactNode } from 'react'
+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 {
+  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
+  /** `<Legend.Actions>` in the sticky header; member `<Legend.Row>`s in the body. */
+  children?: ReactNode
+}
+
+/**
+ * Store-connected group wrapper. Draggable inside `<Legend.Sortable>`.
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+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 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)
+
+  const renderGroup = (sortableProps?: SortableEntityRenderProps) => (
+    <LegendGroupContext.Provider value={groupId}>
+      <Box
+        ref={sortableProps?.rootRef}
+        style={sortableProps?.rootStyle}
+        sx={[
+          styles.group,
+          sortableProps?.dragging === true && styles.groupDragging,
+        ]}
+      >
+        <Box sx={styles.header}>
+          {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 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>
+              )}
+            </SmartTooltip>
+
+            {/* Informative only (the row is the button); hidden on touch. */}
+            <ExpandMoreIcon
+              sx={[styles.chevron, group.collapsed && styles.chevronCollapsed]}
+            />
+          </Box>
+
+          <Box className='PsLegend-groupActions' sx={styles.actions}>
+            {actions}
+          </Box>
+        </Box>
+
+        <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

@@ -0,0 +1,184 @@
+import type { SxProps, Theme } from '@mui/material'
+
+/**
+ * Design height of the group header (Figma "Group layers header", 48px).
+ * Grouped layer-row headers use it as their sticky `top` offset so they pin
+ * just below their group's header while the panel scrolls.
+ */
+export const LEGEND_GROUP_HEADER_HEIGHT = 48
+
+export const styles = {
+  group: {
+    display: 'flex',
+    flexDirection: 'column',
+    '& + &': {
+      borderTop: '1px solid',
+      borderColor: 'divider',
+    },
+  },
+  // The original stays in place, dimmed, while its overlay clone is dragged.
+  groupDragging: {
+    opacity: 0.4,
+  },
+  // Figma: 48px tall, 16px left inset (matches the row's own left inset),
+  // 8px gap to the label, actions right-aligned with ~8px edge inset (the
+  // small icon-button padding brings the glyphs to the design's 16px optical
+  // inset), hairline divider below. Sticky: pins to the top of the panel's
+  // scroll container.
+  header: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: 1,
+    padding: ({ spacing }) => spacing(1.5, 2, 1.5, 2),
+    minHeight: LEGEND_GROUP_HEADER_HEIGHT,
+    borderBottom: '1px solid',
+    borderColor: 'divider',
+    position: 'sticky',
+    top: 0,
+    // Above the sticky row headers (2), which in turn sit above MUI's
+    // z-index-1 form internals in row content.
+    zIndex: 3,
+    // Distinct from the row header / panel body (both `background.paper`) so
+    // the group header visually separates from the rest.
+    backgroundColor: 'background.default',
+    // Hover-fade group actions (widgets-v2 Wrapper parity). Scoped to the
+    // header itself (not the group root) so hovering a member row's body
+    // below never lights up the group's own actions/handle — only hovering
+    // the header (title/handle/actions) does. A control carrying `.active`
+    // (hidden group) stays visible. Touch devices always show them. The
+    // collapse chevron sits outside the fade group. Each non-active child
+    // also collapses to zero width on its own (not just the whole actions
+    // slot) so a sibling's `.active` pin (e.g. the eye on a mixed-visibility
+    // group) doesn't leave a same-sized invisible hole where the still-faded
+    // ⋮ menu would've been.
+    '& .PsLegend-groupFade > *': {
+      opacity: 1,
+      transition: ({ transitions }: Theme) =>
+        transitions.create(['opacity', 'width'], {
+          duration: transitions.duration.standard,
+          easing: transitions.easing.easeInOut,
+        }),
+      '@media (hover: hover)': {
+        opacity: 0,
+      },
+      '&.active': {
+        opacity: 1,
+      },
+    },
+    // Faded actions don't reserve flex space on fine-pointer devices — the
+    // label grows to the trailing edge. Hover/focus-within restores the slot
+    // so the label reflows with the buttons; a dirty `.active` child keeps
+    // the slot open even outside hover.
+    '@media (hover: hover)': {
+      '& .PsLegend-groupFade > *:not(.active)': {
+        width: 0,
+        minWidth: 0,
+        // border-box IconButtons keep their padding inside `width` — zero it
+        // too, otherwise the fixed 2px+2px padding survives as a tiny but
+        // needless residual gap.
+        padding: 0,
+        overflow: 'hidden',
+        pointerEvents: 'none',
+      },
+      '& .PsLegend-groupActions:not(:has(.active))': {
+        width: 0,
+        minWidth: 0,
+        overflow: 'hidden',
+        // Cancel the header gap so nothing is left behind the label.
+        marginInlineStart: ({ spacing }: Theme) => `calc(-1 * ${spacing(1)})`,
+        pointerEvents: 'none',
+      },
+    },
+    '&:hover .PsLegend-groupFade > *, &:focus-within .PsLegend-groupFade > *': {
+      opacity: 1,
+      width: 'auto',
+      minWidth: 0,
+      padding: '2px',
+      overflow: 'visible',
+      pointerEvents: 'auto',
+    },
+    '&:hover .PsLegend-groupActions, &:focus-within .PsLegend-groupActions': {
+      width: 'auto',
+      minWidth: 0,
+      overflow: 'visible',
+      marginInlineStart: 0,
+      pointerEvents: 'auto',
+    },
+    // 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,
+      },
+  },
+  // 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',
+  },
+  // No `flex:1` here — the label sizes to its own text (shrinking to
+  // ellipsis when too long) so the chevron sits right after it, instead of
+  // being dragged to the trailing edge of `titleArea` (which keeps its own
+  // `flex:1` to fill the header up to the actions).
+  label: {
+    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',
+    alignItems: 'center',
+    gap: 0.25,
+    flexShrink: 0,
+    '& .MuiIconButton-root': {
+      padding: '2px',
+    },
+  },
+} satisfies Record<string, SxProps<Theme>>