@carto/ps-react-ui 4.12.1 → 4.13.0

package/src/legend/components/legend-category/legend-category-ui.tsx

@@ -0,0 +1,91 @@
+import { Box, Typography } from '@mui/material'
+import { styles } from './styles'
+import {
+  LegendSwatch,
+  DEFAULT_SWATCH_SIZE,
+} from '../legend-swatch/legend-swatch'
+import type { LegendCategoryVariable } from '../../stores'
+
+export interface LegendCategoryUIProps {
+  data: LegendCategoryVariable
+}
+
+const MIN_GUTTER = 16
+
+/**
+ * Categorical legend — a list of swatches with labels (and optional trailing
+ * values, compact-formatted). The variable-level shape / fill pattern /
+ * stroke style / `isStrokeColor` act as defaults; each item may override any
+ * of them, so one list can mix patterns (or shapes) across entries.
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export function LegendCategoryUI({ data }: LegendCategoryUIProps) {
+  const {
+    items,
+    shape = 'circle',
+    isStrokeColor = false,
+    fillPattern = 'solid',
+    strokeStyle = 'solid',
+    orientation = 'vertical',
+  } = data
+  const horizontal = orientation === 'horizontal'
+
+  // Fixed gutter wide enough for the largest swatch so labels align — only
+  // meaningful in the vertical list; horizontal chips size to content.
+  const maxSize = items.reduce(
+    (m, it) => Math.max(m, it.size ?? DEFAULT_SWATCH_SIZE),
+    0,
+  )
+  const gutter = Math.max(MIN_GUTTER, maxSize)
+
+  return (
+    <Box
+      data-orientation={orientation}
+      sx={{ ...styles.list, ...(horizontal ? styles.listHorizontal : null) }}
+    >
+      {items.map((item, index) => (
+        <Box
+          key={`${item.label}-${index}`}
+          sx={{
+            ...styles.item,
+            ...(horizontal ? styles.itemHorizontal : null),
+          }}
+        >
+          <Box
+            sx={{ ...styles.gutter, width: horizontal ? undefined : gutter }}
+          >
+            <LegendSwatch
+              shape={item.shape ?? shape}
+              color={item.color}
+              isStrokeColor={item.isStrokeColor ?? isStrokeColor}
+              fillPattern={item.fillPattern ?? fillPattern}
+              strokeStyle={item.strokeStyle ?? strokeStyle}
+              size={item.size ?? DEFAULT_SWATCH_SIZE}
+            />
+          </Box>
+          <Typography
+            variant='caption'
+            color='text.primary'
+            sx={{
+              ...styles.label,
+              ...(horizontal ? styles.labelHorizontal : null),
+            }}
+          >
+            {item.label}
+          </Typography>
+          {item.value != null && (
+            <Typography
+              className='PsLegend-value'
+              variant='caption'
+              color='text.secondary'
+              sx={styles.value}
+            >
+              {item.value}
+            </Typography>
+          )}
+        </Box>
+      ))}
+    </Box>
+  )
+}

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

@@ -0,0 +1,61 @@
+import type { SxProps, Theme } from '@mui/material'
+
+export const styles = {
+  list: {
+    display: 'flex',
+    flexDirection: 'column',
+    gap: 0.5,
+    // Values are hidden until the legend content is hovered (or keyboard-
+    // focused). On hover-incapable (touch) devices they're always visible —
+    // tap-:hover is unreliable on non-interactive elements.
+    '&:hover .PsLegend-value, &:focus-within .PsLegend-value': {
+      opacity: 1,
+    },
+    '@media (hover: none)': {
+      '& .PsLegend-value': { opacity: 1 },
+    },
+  },
+  item: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: 1,
+  },
+  // Fixed-width gutter so labels stay column-aligned regardless of swatch
+  // shape or per-item size; the swatch is centered within it.
+  gutter: {
+    flexShrink: 0,
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  label: {
+    flex: 1,
+    minWidth: 0,
+    overflow: 'hidden',
+    textOverflow: 'ellipsis',
+    whiteSpace: 'nowrap',
+  },
+  value: {
+    flexShrink: 0,
+    opacity: 0,
+    transition: 'opacity 120ms',
+  },
+  // ─── Horizontal orientation modifiers (spread over the vertical base) ───
+  // Items flow left-to-right and wrap; each is a compact swatch+label pair.
+  listHorizontal: {
+    flexDirection: 'row',
+    flexWrap: 'wrap',
+    columnGap: 2,
+    rowGap: 0.5,
+  },
+  // No fixed gutter — the swatch sits at its natural size next to the label.
+  itemHorizontal: {
+    gap: 0.5,
+  },
+  // Each chip sizes to its content (no flex-grow / ellipsis).
+  labelHorizontal: {
+    flex: '0 0 auto',
+    overflow: 'visible',
+    textOverflow: 'clip',
+  },
+} satisfies Record<string, SxProps<Theme>>

package/src/legend/components/legend-config-select/legend-config-select.tsx

@@ -0,0 +1,96 @@
+import { useState } from 'react'
+import { ButtonBase, Menu, MenuItem, Typography } from '@mui/material'
+import { ArrowDropDown as ArrowDropDownIcon } from '@mui/icons-material'
+import { useLegendId, useLegendShallow } from '../../stores'
+import { useLegendConfig } from '../../provider'
+import { useLegendRow } from '../contexts'
+import { styles } from './styles'
+
+/**
+ * The layer configuration select — resolves its layer from the enclosing
+ * `Legend.Row` context. The closed field shows the **first section's** active
+ * option; the menu lists every section under its title (omitted when the
+ * layer has a single section) and each section highlights its own active
+ * option. Picking an option writes `setSectionValue` and closes the menu.
+ * Renders nothing when the layer declares no sections (or outside a row).
+ *
+ * A native single-value `Select` can't represent one active per section,
+ * hence the outlined-trigger + `Menu` composition.
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export function LegendConfigSelect() {
+  const id = useLegendId()
+  const row = useLegendRow()
+  const layerId = row?.layerId
+  const sections = useLegendShallow(id, (s) =>
+    layerId ? s.layers[layerId]?.sections : undefined,
+  )
+  const setSectionValue = useLegendShallow(id, (s) => s.setSectionValue)
+  const { labels } = useLegendConfig()
+  const [anchorEl, setAnchorEl] = useState<HTMLElement | null>(null)
+  const open = Boolean(anchorEl)
+
+  if (!layerId || !sections || sections.length === 0) return null
+
+  const display = sections[0]!.active
+  const showTitles = sections.length > 1
+
+  return (
+    <>
+      <ButtonBase
+        sx={styles.trigger}
+        onClick={(event) => setAnchorEl(event.currentTarget)}
+        aria-label={labels.attribute}
+        aria-haspopup='listbox'
+        aria-expanded={open}
+      >
+        <Typography variant='body2' sx={styles.value}>
+          {display}
+        </Typography>
+        <ArrowDropDownIcon
+          fontSize='small'
+          sx={
+            open ? { ...styles.chevron, ...styles.chevronOpen } : styles.chevron
+          }
+        />
+      </ButtonBase>
+
+      <Menu
+        anchorEl={anchorEl}
+        open={open}
+        onClose={() => setAnchorEl(null)}
+        slotProps={{
+          paper: { sx: { width: anchorEl?.clientWidth } },
+        }}
+      >
+        {sections.map((section) => [
+          showTitles && section.title ? (
+            <Typography
+              key={`${section.id}-title`}
+              variant='overline'
+              color='text.secondary'
+              component='li'
+              sx={styles.sectionTitle}
+            >
+              {section.title}
+            </Typography>
+          ) : null,
+          ...section.options.map((option) => (
+            <MenuItem
+              key={`${section.id}-${option}`}
+              selected={option === section.active}
+              sx={styles.option}
+              onClick={() => {
+                setSectionValue(layerId, section.id, option)
+                setAnchorEl(null)
+              }}
+            >
+              {option}
+            </MenuItem>
+          )),
+        ])}
+      </Menu>
+    </>
+  )
+}

package/src/legend/components/legend-config-select/styles.ts

@@ -0,0 +1,48 @@
+import type { SxProps, Theme } from '@mui/material'
+
+export const styles = {
+  // Outlined-input look-alike trigger (the design's select has no floating
+  // label — just the value + chevron in a 32px bordered field).
+  trigger: {
+    width: '100%',
+    minHeight: 32,
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'space-between',
+    gap: 1,
+    padding: ({ spacing }) => spacing(0, 1.5),
+    border: '1px solid',
+    borderColor: 'divider',
+    borderRadius: 1,
+    backgroundColor: 'background.paper',
+    color: 'text.primary',
+    '&:hover': {
+      borderColor: 'text.primary',
+    },
+  },
+  value: {
+    minWidth: 0,
+    overflow: 'hidden',
+    textOverflow: 'ellipsis',
+    whiteSpace: 'nowrap',
+  },
+  chevron: {
+    flexShrink: 0,
+    color: 'action.active',
+    transition: ({ transitions }: Theme) => transitions.create('transform'),
+  },
+  chevronOpen: {
+    transform: 'rotate(180deg)',
+  },
+  sectionTitle: {
+    padding: ({ spacing }) => spacing(1, 2, 0.5, 2),
+    lineHeight: 1.5,
+  },
+  // Figma: the active option reads as primary-colored text, no background.
+  option: {
+    '&.Mui-selected, &.Mui-selected:hover': {
+      backgroundColor: 'transparent',
+      color: 'primary.main',
+    },
+  },
+} satisfies Record<string, SxProps<Theme>>

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

@@ -0,0 +1,115 @@
+import { afterEach, describe, it, expect } 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 {
+  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('toggles group collapse through the store', () => {
+    renderGroup('g-col')
+    fireEvent.click(screen.getByLabelText('Collapse group'))
+    expect(getLegendStore('g-col').getState().groups.g1!.collapsed).toBe(true)
+  })
+
+  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 chevron 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)
+    expect(getLegendStore('g-hide').getState().groups.g1!.collapsed).toBe(false)
+  })
+})

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

@@ -0,0 +1,88 @@
+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 { SmartTooltip } from '../../../components/smart-tooltip/smart-tooltip'
+import { useLegendId, useLegendShallow } from '../../stores'
+import { useLegendConfig } from '../../provider'
+import { LegendGroupContext } from '../contexts'
+import { partitionLegendChildren } from '../legend-actions/legend-actions'
+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).
+   */
+  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.
+ *
+ * @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 { labels } = useLegendConfig()
+
+  if (!group) return null
+
+  const { actions, body } = partitionLegendChildren(children)
+
+  return (
+    <LegendGroupContext.Provider value={groupId}>
+      <Box sx={styles.group}>
+        <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>
+
+          <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' />
+              )}
+            </IconButton>
+          </Box>
+        </Box>
+
+        <Collapse in={!group.collapsed}>{body}</Collapse>
+      </Box>
+    </LegendGroupContext.Provider>
+  )
+}

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

@@ -0,0 +1,82 @@
+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',
+    },
+    // Hover-fade group actions (widgets-v2 Wrapper parity). Revealed by
+    // hovering anywhere in the group block (including member rows); a control
+    // carrying `.active` (hidden group) stays visible. Touch devices always
+    // show them. The collapse chevron sits outside the fade group. Member
+    // rows use the distinct `PsLegend-rowFade` class, so group hover never
+    // lights up row actions.
+    '& .PsLegend-groupFade > *': {
+      opacity: 1,
+      transition: ({ transitions }: Theme) =>
+        transitions.create('opacity', {
+          duration: transitions.duration.standard,
+          easing: transitions.easing.easeInOut,
+        }),
+      '@media (hover: hover)': {
+        opacity: 0,
+      },
+      '&.active': {
+        opacity: 1,
+      },
+    },
+    '&:hover .PsLegend-groupFade > *, &:focus-within .PsLegend-groupFade > *': {
+      opacity: 1,
+    },
+  },
+  // 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
+  // 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, 1),
+    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,
+    backgroundColor: 'background.paper',
+  },
+  groupIcon: {
+    display: 'flex',
+    color: 'text.secondary',
+  },
+  label: {
+    flex: 1,
+    minWidth: 0,
+    overflow: 'hidden',
+    textOverflow: 'ellipsis',
+    whiteSpace: 'nowrap',
+  },
+  // 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>>

package/src/legend/components/legend-icon/legend-icon-ui.tsx

@@ -0,0 +1,56 @@
+import { Box, Typography } from '@mui/material'
+import { styles } from './styles'
+import type { LegendIconVariable } from '../../stores'
+
+export interface LegendIconUIProps {
+  data: LegendIconVariable
+}
+
+/**
+ * Icon legend — a list of icon images with labels (and optional values).
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export function LegendIconUI({ data }: LegendIconUIProps) {
+  const orientation = data.orientation ?? 'vertical'
+  const horizontal = orientation === 'horizontal'
+
+  return (
+    <Box
+      data-orientation={orientation}
+      sx={{ ...styles.list, ...(horizontal ? styles.listHorizontal : null) }}
+    >
+      {data.items.map((item, index) => (
+        <Box
+          key={`${item.label}-${index}`}
+          sx={{
+            ...styles.item,
+            ...(horizontal ? styles.itemHorizontal : null),
+          }}
+        >
+          <Box component='img' src={item.icon} alt='' sx={styles.icon} />
+          <Typography
+            variant='caption'
+            color='text.primary'
+            sx={{
+              ...styles.label,
+              ...(horizontal ? styles.labelHorizontal : null),
+            }}
+          >
+            {item.label}
+          </Typography>
+          {item.value != null && (
+            <Typography
+              className='PsLegend-value'
+              variant='caption'
+              color='text.secondary'
+              sx={styles.value}
+            >
+              {item.value}
+            </Typography>
+          )}
+        </Box>
+      ))}
+    </Box>
+  )
+}