@carto/ps-react-ui 4.15.0 → 4.17.0

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>
+  )
+}

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

@@ -3,13 +3,14 @@ import {
   Box,
   IconButton,
   InputAdornment,
+  MenuItem,
   OutlinedInput,
-  Popover,
   Slider,
-  Tooltip,
+  Typography,
 } from '@mui/material'
-import { Opacity as OpacityIcon } from '@carto/meridian-ds/custom-icons'
-import { useLegendId, useLegendStore } from '../../stores'
+import { Close as CloseIcon } from '@mui/icons-material'
+import { Tooltip } from '../../../components/tooltip/tooltip'
+import { useLegendId, useLegendShallow, useLegendStore } from '../../stores'
 import { useLegendConfig } from '../../provider'
 import { useLegendRow } from '../contexts'
 import { styles } from './styles'
@@ -18,82 +19,53 @@ const clampPercent = (value: number): number =>
   Math.min(100, Math.max(0, Math.round(value)))
 
 /**
- * Opacity header action for a layer row: a checkerboard icon button, pinned
- * `.active` in the hover-fade group while opacity ≠ 1 or the popover is open,
- * disabled while the layer is hidden. Opens `Legend.Opacity.Popover` through
- * the row context. Place it inside `<Legend.Actions>` of a `Legend.Row`.
+ * Opacity menu item — toggles the row's inline bar; self-hides when hidden or no `opacityControl`.
  *
  * @experimental This API is new and may change in a future release.
  */
-function OpacityTrigger() {
+function OpacityItem() {
   const id = useLegendId()
   const row = useLegendRow()
-  const layerId = row?.layerId
-  const opacity = useLegendStore(id, (s) =>
-    layerId ? (s.layers[layerId]?.opacity ?? 1) : 1,
-  )
-  const visible = useLegendStore(id, (s) =>
-    layerId ? (s.layers[layerId]?.visible ?? true) : true,
+  const layer = useLegendShallow(id, (s) =>
+    row ? s.layers[row.layerId] : undefined,
   )
+  const setCollapsed = useLegendShallow(id, (s) => s.setCollapsed)
   const { labels } = useLegendConfig()
 
-  // A hidden layer shows only its visibility eye + collapse chevron — the
-  // opacity action disappears entirely until the layer is shown again.
-  if (!row || !visible) return null
-  const dirty = opacity !== 1
+  if (!row || !layer?.visible || !layer.opacityControl) return null
+
+  const toggle = () => {
+    const next = !row.opacityOpen
+    row.setOpacityOpen(next)
+    if (next && layer.collapsed) setCollapsed(row.layerId, false)
+  }
 
   return (
-    // The wrapper keeps the Tooltip working on the button; as the fade
-    // group's direct child it also carries the `.active` pin.
-    <Tooltip title={labels.opacity}>
-      <Box
-        component='span'
-        className={dirty || row.opacityOpen ? 'active' : undefined}
-        sx={styles.triggerWrap}
-      >
-        <IconButton
-          size='small'
-          onClick={() => row.setOpacityOpen(true)}
-          aria-label={labels.opacity}
-        >
-          <OpacityIcon fontSize='small' />
-        </IconButton>
-      </Box>
-    </Tooltip>
+    <MenuItem selected={row.opacityOpen} onClick={toggle}>
+      {labels.opacity}
+    </MenuItem>
   )
 }
 
 /**
- * The opacity editing surface — a popover **anchored to the row's sticky
- * header, spanning its full width**, holding a slider (writes `setOpacity`
- * only on release, widgets-v2 parity) and a percent input (commits live as
- * soon as the draft parses, clamped 0–100; never ellipsizes "100 %").
- * Declare it anywhere inside the `Legend.Row` (it renders in a portal);
- * open it with `Legend.Opacity.Trigger`.
+ * Inline opacity bar (first body child of `Legend.Row`). Slider commits on release; input commits live.
  *
  * @experimental This API is new and may change in a future release.
  */
-function OpacityPopover() {
+function OpacityInline() {
   const id = useLegendId()
   const row = useLegendRow()
   const layerId = row?.layerId
   const opacity = useLegendStore(id, (s) =>
     layerId ? (s.layers[layerId]?.opacity ?? 1) : 1,
   )
-  const visible = useLegendStore(id, (s) =>
-    layerId ? (s.layers[layerId]?.visible ?? true) : true,
-  )
   const setOpacity = useLegendStore(id, (s) => s.setOpacity)
   const { labels } = useLegendConfig()
 
-  // Drag and typing drafts: the thumb and the input track each other through
-  // `percent` while only commits reach the store (and the map).
   const [dragPercent, setDragPercent] = useState<number | null>(null)
   const [draft, setDraft] = useState<string | null>(null)
 
-  // The trigger is gone while hidden; also gate `open` so a popover left open
-  // can't survive the layer being hidden elsewhere.
-  if (!row || !layerId || !visible) return null
+  if (!row || !layerId || !row.opacityOpen) return null
 
   const percent = dragPercent ?? clampPercent(opacity * 100)
 
@@ -109,7 +81,6 @@ function OpacityPopover() {
     const parsed = Number(raw)
     if (!Number.isFinite(parsed)) return
     const clamped = commitPercent(parsed)
-    // Out-of-range entries snap the visible draft to the committed value.
     if (clamped !== parsed) setDraft(String(clamped))
   }
 
@@ -120,16 +91,22 @@ function OpacityPopover() {
   }
 
   return (
-    <Popover
-      open={row.opacityOpen && Boolean(row.headerEl)}
-      anchorEl={row.headerEl}
-      onClose={handleClose}
-      anchorOrigin={{ vertical: 'bottom', horizontal: 'left' }}
-      transformOrigin={{ vertical: 'top', horizontal: 'left' }}
-      // Full row width: the paper matches the sticky header it anchors to.
-      slotProps={{ paper: { sx: { width: row.headerEl?.clientWidth } } }}
-    >
-      <Box sx={styles.popover}>
+    <Box sx={styles.inline}>
+      <Box sx={styles.inlineHeader}>
+        <Typography variant='caption' fontWeight='medium' color='text.primary'>
+          {labels.opacity}
+        </Typography>
+        <Tooltip title={labels.close}>
+          <IconButton
+            size='small'
+            onClick={handleClose}
+            aria-label={labels.close}
+          >
+            <CloseIcon fontSize='small' />
+          </IconButton>
+        </Tooltip>
+      </Box>
+      <Box sx={styles.inlineControls}>
         <Slider
           size='small'
           min={0}
@@ -151,8 +128,6 @@ function OpacityPopover() {
           size='small'
           value={draft ?? String(percent)}
           onChange={(event) => handleInputChange(event.target.value)}
-          // An abandoned draft (empty / non-numeric) snaps back to the
-          // store value on blur.
           onBlur={() => setDraft(null)}
           onKeyDown={(event) => {
             if (event.key === 'Enter') (event.target as HTMLElement).blur()
@@ -162,18 +137,16 @@ function OpacityPopover() {
           sx={styles.input}
         />
       </Box>
-    </Popover>
+    </Box>
   )
 }
 
 /**
- * Compound opacity control for layer rows (widgets-v2 `FullScreen` parity):
- * `Trigger` lives in the header `<Legend.Actions>`, `Popover` anywhere in the
- * row body — they share state through the row context.
+ * Compound opacity control: `Item` in the row menu, `Inline` in the body.
  *
  * @experimental This API is new and may change in a future release.
  */
 export const LegendOpacity = {
-  Trigger: OpacityTrigger,
-  Popover: OpacityPopover,
+  Item: OpacityItem,
+  Inline: OpacityInline,
 }

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

@@ -1,25 +1,30 @@
 import type { SxProps, Theme } from '@mui/material'
 
 export const styles = {
-  // Tooltip wrapper around the (possibly disabled) trigger button. A plain
-  // inline span would be sized by the line box (baseline + descender) and
-  // end up ~1px taller than the 24px button inside.
-  triggerWrap: {
-    display: 'inline-flex',
+  // Figma "Legend Opacity": a soft rounded bar between the row header and the
+  // body — caption label + ✕ on the first line, slider + % input below.
+  inline: {
+    display: 'flex',
+    flexDirection: 'column',
+    gap: 0.5,
+    borderRadius: 1,
+  },
+  inlineHeader: {
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'space-between',
   },
-  popover: {
+  inlineControls: {
     display: 'flex',
     alignItems: 'center',
     gap: 1.5,
-    padding: ({ spacing }) => spacing(1, 1.5),
-    width: 280,
   },
   slider: {
     flex: 1,
   },
   // Wide enough for "100 %" — the value must never ellipsize.
   input: {
-    width: 76,
+    width: 68,
     flexShrink: 0,
     '& input': {
       textAlign: 'right',

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

@@ -0,0 +1,84 @@
+import {
+  useCallback,
+  useMemo,
+  useRef,
+  useState,
+  type MouseEvent,
+  type ReactNode,
+} from 'react'
+import { IconButton, Menu } from '@mui/material'
+import { MoreVert as MoreVertIcon } from '@mui/icons-material'
+import { Tooltip } from '../../../components/tooltip/tooltip'
+import { useLegendConfig } from '../../provider'
+import { LegendMenuContext, type LegendMenuController } from '../contexts'
+
+export interface LegendOverflowMenuProps {
+  /** Menu items; async items use `stopPropagation` + `runAsyncMenuAction`. */
+  children?: ReactNode
+  /** When `false`, render nothing. Defaults to `true`. */
+  gate?: boolean
+  /** `aria-label` for the ⋮ trigger. */
+  ariaLabel: string
+  /** Extra `.active` pin (e.g. inline opacity bar open). */
+  active?: boolean
+}
+export function LegendOverflowMenu({
+  children,
+  gate = true,
+  ariaLabel,
+  active = false,
+}: LegendOverflowMenuProps) {
+  const [anchorEl, setAnchorEl] = useState<HTMLElement | null>(null)
+  const [busy, setBusyState] = useState(false)
+  // Ref so close-guards and click gates see the flag before the next render.
+  const busyRef = useRef(false)
+  const open = Boolean(anchorEl)
+  const { labels } = useLegendConfig()
+
+  const close = useCallback(() => setAnchorEl(null), [])
+  const setBusy = useCallback((next: boolean) => {
+    busyRef.current = next
+    setBusyState(next)
+  }, [])
+  const isBusy = useCallback(() => busyRef.current, [])
+  const handleClose = useCallback(() => {
+    if (busyRef.current) return
+    close()
+  }, [close])
+  const menu = useMemo<LegendMenuController>(
+    () => ({ busy, isBusy, setBusy, close }),
+    [busy, isBusy, setBusy, close],
+  )
+
+  if (!gate || !children) return null
+
+  const handleOpen = (e: MouseEvent<HTMLElement>) => {
+    e.stopPropagation()
+    setAnchorEl(e.currentTarget)
+  }
+
+  return (
+    <LegendMenuContext.Provider value={menu}>
+      <Tooltip title={labels.moreOptions}>
+        <IconButton
+          size='small'
+          className={open || busy || active ? 'active' : undefined}
+          onClick={handleOpen}
+          aria-label={ariaLabel}
+          aria-haspopup='menu'
+          aria-expanded={open}
+        >
+          <MoreVertIcon fontSize='small' />
+        </IconButton>
+      </Tooltip>
+      <Menu
+        anchorEl={anchorEl}
+        open={open}
+        onClose={handleClose}
+        onClick={handleClose}
+      >
+        {children}
+      </Menu>
+    </LegendMenuContext.Provider>
+  )
+}

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

@@ -0,0 +1,23 @@
+import type { ReactNode } from 'react'
+import { useLegendConfig } from '../../provider'
+import { LegendOverflowMenu } from '../legend-overflow-menu/legend-overflow-menu'
+
+export interface LegendPanelMenuProps {
+  /** Menu items; async items use `stopPropagation` + `runAsyncMenuAction`. */
+  children?: ReactNode
+}
+
+/**
+ * Overflow (⋮) menu for the panel header (no row/group context).
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export function LegendPanelMenu({ children }: LegendPanelMenuProps) {
+  const { labels } = useLegendConfig()
+
+  return (
+    <LegendOverflowMenu ariaLabel={labels.panelOptions}>
+      {children}
+    </LegendOverflowMenu>
+  )
+}

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

@@ -1,4 +1,5 @@
-import { Box, Tooltip, Typography } from '@mui/material'
+import { Box, Typography } from '@mui/material'
+import { Tooltip } from '../../../components/tooltip/tooltip'
 import { ErrorOutline as ErrorIcon } from '@mui/icons-material'
 import { styles } from './styles'
 import { DEFAULT_LEGEND_LABELS, type LegendLabels } from '../../provider/labels'