@carto/ps-react-ui 4.15.0 → 4.16.0

package/dist/types/legend/components/run-async-menu-action.d.ts

@@ -0,0 +1,7 @@
+import { LegendMenuController } from './contexts';
+/**
+ * Run an async menu action with busy gating. Uses `isBusy()` (ref-backed) so a
+ * second click before React re-renders cannot fire the handler twice. Keeps
+ * the menu open while pending, then clears busy and closes when it settles.
+ */
+export declare function runAsyncMenuAction(menu: LegendMenuController, action: () => void | Promise<void>): Promise<void>;

package/dist/types/legend/index.d.ts

@@ -5,6 +5,12 @@ import { LegendActions } from './components/legend-actions/legend-actions';
 import { LegendVisibilityToggle } from './components/legend-visibility-toggle/legend-visibility-toggle';
 import { LegendRowMenu } from './components/legend-row-menu/legend-row-menu';
 import { LegendZoomTo } from './components/legend-row-menu/legend-zoom-to';
+import { LegendShowOnlyLayer, LegendShowAllLayers } from './components/legend-row-menu/legend-row-menu-items';
+import { LegendGroupMenu } from './components/legend-group-menu/legend-group-menu';
+import { LegendShowOnlyGroup, LegendShowAllGroups, LegendCollapseAllGroups, LegendZoomToGroup } from './components/legend-group-menu/legend-group-menu-items';
+import { LegendPanelMenu } from './components/legend-panel-menu/legend-panel-menu';
+import { LegendVisibleLayers } from './components/legend-visible-layers/legend-visible-layers';
+import { LegendSortable } from './components/legend-sortable/legend-sortable';
 import { LegendConfigSelect } from './components/legend-config-select/legend-config-select';
 import { LegendItem } from './components/legend-item/legend-item';
 import { LegendItemUI } from './components/legend-item/legend-item-ui';
@@ -22,31 +28,58 @@ import { LegendIconUI } from './components/legend-icon/legend-icon-ui';
  * children — `<Legend.Actions>` renders in the sticky header (hover-fade),
  * everything else in the collapsible body.
  *
+ * Collapse is the title row itself (whole header minus the actions), with an
+ * informative chevron that touch devices don't show. The ⋮ menus are
+ * extensible shells: compose the built-in items and append your own
+ * `MenuItem`s. The built-in items are **self-contained** — their effect is
+ * implemented inside the component through the store's primitive setters, so
+ * they mount with zero wiring; only `ZoomTo`/`ZoomToGroup` take an `onZoomTo`
+ * handler (zooming is the map's concern). Pass an async handler to keep the
+ * menu open with in-item loading feedback until it settles.
+ *
  * ```tsx
  * import { Legend } from '@carto/ps-react-ui/legend'
  *
  * <Legend.Provider id='map-legend' layers={layers} groups={groups}>
+ *   // Panel-wide actions (Show all groups / Collapse all) live once here,
+ *   // not repeated per group.
+ *   <Legend.PanelMenu>
+ *     <Legend.ShowAllGroups />
+ *     <Legend.CollapseAllGroups />
+ *   </Legend.PanelMenu>
+ *
  *   <Legend.Group groupId='demographics'>
  *     <Legend.Actions>
  *       <Legend.VisibilityToggle />          // tri-state group eye
+ *       <Legend.GroupMenu>                   // ⋮ (rightmost)
+ *         <Legend.ShowOnlyGroup />
+ *         <Legend.ShowAllLayers />           // this group's members
+ *         <Legend.ZoomToGroup onZoomTo={zoomToGroup} />
+ *       </Legend.GroupMenu>
  *     </Legend.Actions>
  *     <Legend.Row layerId='income'>
- *       // Actions read L→R: options · opacity · visibility
+ *       // Actions read L→R: eye · ⋮ options
  *       <Legend.Actions>
+ *         <Legend.VisibilityToggle />        // layer eye
  *         <Legend.RowMenu>
+ *           <Legend.ShowOnlyLayer />
+ *           <Legend.Opacity.Item />
  *           <Legend.ZoomTo onZoomTo={zoomTo} />
  *         </Legend.RowMenu>
- *         <Legend.Opacity.Trigger />
- *         <Legend.VisibilityToggle />        // layer eye
  *       </Legend.Actions>
+ *       <Legend.Opacity.Inline />            // bar between header and body
  *       <Legend.ConfigSelect />
  *       <Legend.Item />
- *       <Legend.Opacity.Popover />           // anchors to the row header
  *     </Legend.Row>
  *   </Legend.Group>
  * </Legend.Provider>
  * ```
  *
+ * `Legend.ShowAllLayers` is composed at whichever site it targets: directly
+ * in a `Legend.GroupMenu` for that group's members (as above), or in an
+ * ungrouped row's `Legend.RowMenu` for the loose-layer bucket — it resolves
+ * its own scope from context either way.
+ *
  * @experimental This API is new and may change in a future release.
  */
 export declare const Legend: {
@@ -54,12 +87,22 @@ export declare const Legend: {
     readonly Group: typeof LegendGroup;
     readonly Row: typeof LegendRow;
     readonly Actions: typeof LegendActions;
+    readonly Sortable: typeof LegendSortable;
     readonly VisibilityToggle: typeof LegendVisibilityToggle;
     readonly RowMenu: typeof LegendRowMenu;
     readonly ZoomTo: typeof LegendZoomTo;
+    readonly ShowOnlyLayer: typeof LegendShowOnlyLayer;
+    readonly ShowAllLayers: typeof LegendShowAllLayers;
+    readonly GroupMenu: typeof LegendGroupMenu;
+    readonly ShowOnlyGroup: typeof LegendShowOnlyGroup;
+    readonly ShowAllGroups: typeof LegendShowAllGroups;
+    readonly CollapseAllGroups: typeof LegendCollapseAllGroups;
+    readonly ZoomToGroup: typeof LegendZoomToGroup;
+    readonly PanelMenu: typeof LegendPanelMenu;
+    readonly VisibleLayers: typeof LegendVisibleLayers;
     readonly Opacity: {
-        Trigger: () => import("react/jsx-runtime").JSX.Element | null;
-        Popover: () => import("react/jsx-runtime").JSX.Element | null;
+        Item: () => import("react/jsx-runtime").JSX.Element | null;
+        Inline: () => import("react/jsx-runtime").JSX.Element | null;
     };
     readonly ConfigSelect: typeof LegendConfigSelect;
     readonly Item: typeof LegendItem;
@@ -75,9 +118,13 @@ export type { LegendProviderProps, LegendLabels } from './provider';
 export type { LegendGroupProps } from './components/legend-group/legend-group';
 export type { LegendRowProps } from './components/legend-row/legend-row';
 export type { LegendActionsProps } from './components/legend-actions/legend-actions';
+export type { LegendSortableProps } from './components/legend-sortable/legend-sortable';
 export type { LegendVisibilityToggleProps } from './components/legend-visibility-toggle/legend-visibility-toggle';
 export type { LegendRowMenuProps } from './components/legend-row-menu/legend-row-menu';
 export type { LegendZoomToProps } from './components/legend-row-menu/legend-zoom-to';
+export type { LegendGroupMenuProps } from './components/legend-group-menu/legend-group-menu';
+export type { LegendZoomToGroupProps } from './components/legend-group-menu/legend-group-menu-items';
+export type { LegendPanelMenuProps } from './components/legend-panel-menu/legend-panel-menu';
 export type { LegendRowContextValue } from './components/contexts';
 export type { LegendItemUIProps } from './components/legend-item/legend-item-ui';
 export type { LegendSwatchProps } from './components/legend-swatch/legend-swatch';

package/dist/types/legend/provider/labels.d.ts

@@ -10,12 +10,33 @@ export interface LegendLabels {
     showLayer: string;
     layerOptions: string;
     zoomTo: string;
+    /** In-flight label for Zoom to layer / Zoom to group. */
+    loading: string;
+    showOnlyLayer: string;
+    showAllLayers: string;
     hideGroup: string;
     showGroup: string;
     expandGroup: string;
     collapseGroup: string;
+    groupOptions: string;
+    showOnlyGroup: string;
+    showAllGroups: string;
+    collapseAllGroups: string;
+    expandAllGroups: string;
+    zoomToGroup: string;
+    panelOptions: string;
+    /** Sticky header of the visible-layers summary; the count is appended. */
+    enabledLayers: string;
+    /** Tooltip of the visible-layers summary trigger. */
+    toggleEnabledLayers: string;
+    /** Tooltip shared by the ⋮ menu triggers (row, group and panel). */
+    moreOptions: string;
+    /** Drag handle of sortable groups/rows (aria + tooltip). */
+    reorder: string;
     opacity: string;
     attribute: string;
+    /** Generic close affordance (e.g. the inline opacity bar's ✕). */
+    close: string;
     radiusRangeBy: string;
     colorBasedOn: string;
     colorGradient: string;

package/dist/types/legend/stores/index.d.ts

@@ -2,4 +2,4 @@ export type { LegendPosition, LegendOrientation, LegendSwatchShape, LegendFillPa
 export { LegendContext, useLegendId } from './legend-context';
 export { createLegendStore, getLegendStore, hasLegendStore, deleteLegendStore, clearAllLegendStores, setLegendStoreEntry, registerLegendStore, unregisterLegendStore, useLegendStore, useLegendShallow, } from './legend-store-registry';
 export type { LegendVisibility } from './selectors';
-export { selectOrderedGroups, selectLayersByGroup, selectOrderedLayers, selectGroupVisibility, } from './selectors';
+export { selectOrderedGroups, selectLayersByGroup, selectOrderedLayers, selectGroupVisibility, selectLayerCollapsible, selectAllGroupsCollapsed, selectVisibleLayersGrouped, selectHasGroups, } from './selectors';

package/dist/types/legend/stores/selectors.d.ts

@@ -18,6 +18,37 @@ export declare function selectLayersByGroup(state: LegendState, groupId: string
  * @experimental This API is new and may change in a future release.
  */
 export declare function selectOrderedLayers(state: LegendState): LegendLayer[];
+/**
+ * `true` when every group is collapsed (`false` with no groups) — drives the
+ * "Collapse all groups" / "Expand all groups" menu label flip.
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export declare function selectAllGroupsCollapsed(state: LegendState): boolean;
+/**
+ * Whether the legend has groups — gates panel-level group actions.
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export declare function selectHasGroups(state: LegendState): boolean;
+/**
+ * Visible layers grouped for the enabled-layers menu.
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export declare function selectVisibleLayersGrouped(state: LegendState): {
+    group?: LegendGroup;
+    layers: LegendLayer[];
+}[];
+/**
+ * Whether a layer has any collapsible body — something the row's `Collapse`
+ * can actually fold. A layer with no variables, sections, or helper note
+ * renders an empty body, so there is nothing to collapse. Gates the row's
+ * title-area collapse affordance (chevron + click).
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export declare function selectLayerCollapsible(state: LegendState, layerId: string): boolean;
 /**
  * Tri-state visibility — derived for groups from their member layers, and the
  * state contract of a controlled `Legend.VisibilityToggle` for any custom

package/dist/types/legend/stores/types.d.ts

@@ -230,6 +230,12 @@ export interface LegendState {
      * section's `options`.
      */
     setSectionValue: (id: string, sectionId: string, value: string) => void;
+    /**
+     * Move a layer to `toIndex` **within its sibling bucket** (its group, or
+     * the ungrouped bucket). `toIndex` is clamped; orders stay dense. No-op
+     * for unknown ids or when the position doesn't change.
+     */
+    moveLayer: (id: string, toIndex: number) => void;
     /**
      * Show/hide **all member layers** of a group (the group itself has no stored
      * visibility — it is derived from its members). Each member keeps its own
@@ -239,6 +245,11 @@ export interface LegendState {
      */
     setGroupVisibility: (id: string, visible: boolean) => void;
     setGroupCollapsed: (id: string, collapsed: boolean) => void;
+    /**
+     * Move a group to `toIndex` within the group list. `toIndex` is clamped;
+     * orders stay dense. No-op for unknown ids or an unchanged position.
+     */
+    moveGroup: (id: string, toIndex: number) => void;
     /**
      * Add a layer, or update it if `input.id` already exists. Interactive state
      * (visible/opacity/collapsed/order and section actives) is preserved unless

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carto/ps-react-ui",
-  "version": "4.15.0",
+  "version": "4.16.0",
   "description": "CARTO's Professional Service React Material library",
   "type": "module",
   "devDependencies": {
@@ -18,7 +18,7 @@
     "react-markdown": "10.1.0",
     "zustand": "5.0.12",
     "@carto/ps-common-types": "1.0.0",
-    "@carto/ps-utils": "2.0.1"
+    "@carto/ps-utils": "2.1.0"
   },
   "peerDependencies": {
     "@carto/meridian-ds": "^2.0.0",
@@ -35,7 +35,7 @@
     "react-dom": "^19.2.0",
     "react-markdown": "^10.0.0",
     "zustand": "^5.0.0",
-    "@carto/ps-utils": "2.0.1"
+    "@carto/ps-utils": "2.1.0"
   },
   "exports": {
     "./chat": {

package/src/components/responsive-drawer/responsive-drawer.test.tsx

@@ -154,6 +154,144 @@ describe('ResponsiveDrawer', () => {
     ).not.toThrow()
   })
 
+  test('defaults to portaling into document.body when container is omitted', () => {
+    render(
+      <ThemeProvider theme={theme}>
+        <ResponsiveDrawer ref={anchor} {...defaultProps} />
+      </ThemeProvider>,
+    )
+    const content = screen.getByTestId('drawer-content')
+    const modalRoot = content.closest('.MuiModal-root')
+    expect(modalRoot?.parentElement).toBe(document.body)
+  })
+
+  test('portals into the given container instead of document.body', () => {
+    const customContainer = document.createElement('div')
+    document.body.appendChild(customContainer)
+    try {
+      render(
+        <ThemeProvider theme={theme}>
+          <ResponsiveDrawer
+            ref={anchor}
+            {...defaultProps}
+            container={customContainer}
+          />
+        </ThemeProvider>,
+      )
+      const content = screen.getByTestId('drawer-content')
+      const modalRoot = content.closest('.MuiModal-root')
+      expect(modalRoot?.parentElement).toBe(customContainer)
+    } finally {
+      customContainer.remove()
+    }
+  })
+
+  test('caps the popover paper height at 90% of a measured container element', () => {
+    const customContainer = document.createElement('div')
+    Object.defineProperty(customContainer, 'clientHeight', {
+      value: 500,
+      configurable: true,
+    })
+    document.body.appendChild(customContainer)
+    try {
+      render(
+        <ThemeProvider theme={theme}>
+          <ResponsiveDrawer
+            ref={anchor}
+            {...defaultProps}
+            container={customContainer}
+          />
+        </ThemeProvider>,
+      )
+      const paper = document.querySelector<HTMLElement>('.MuiPopover-paper')!
+      expect(paper.style.maxHeight).toBe('450px')
+      expect(paper.style.overflow).toBe('hidden')
+      expect(paper.style.display).toBe('flex')
+      expect(paper.style.flexDirection).toBe('column')
+
+      const content = screen.getByTestId('drawer-content')
+      const wrapper = content.parentElement!
+      expect(wrapper.style.display).toBe('flex')
+      expect(wrapper.style.flexDirection).toBe('column')
+      expect(wrapper.style.flex).toBe('1 1 0%')
+      expect(wrapper.style.minHeight).toBe('0')
+      expect(wrapper.style.maxHeight).toBe('100%')
+      expect(wrapper.style.overflow).toBe('hidden')
+    } finally {
+      customContainer.remove()
+    }
+  })
+
+  test('leaves paper maxHeight unset when no container is given', () => {
+    render(
+      <ThemeProvider theme={theme}>
+        <ResponsiveDrawer ref={anchor} {...defaultProps} />
+      </ThemeProvider>,
+    )
+    const paper = document.querySelector<HTMLElement>('.MuiPopover-paper')!
+    expect(paper.style.maxHeight).toBe('')
+    expect(paper.style.display).toBe('')
+
+    const content = screen.getByTestId('drawer-content')
+    expect(content.parentElement!.style.display).toBe('')
+  })
+
+  test('leaves paper maxHeight unset when the container reports height 0', () => {
+    const customContainer = document.createElement('div')
+    Object.defineProperty(customContainer, 'clientHeight', {
+      value: 0,
+      configurable: true,
+    })
+    document.body.appendChild(customContainer)
+    try {
+      render(
+        <ThemeProvider theme={theme}>
+          <ResponsiveDrawer
+            ref={anchor}
+            {...defaultProps}
+            container={customContainer}
+          />
+        </ThemeProvider>,
+      )
+      const paper = document.querySelector<HTMLElement>('.MuiPopover-paper')!
+      expect(paper.style.maxHeight).toBe('')
+    } finally {
+      customContainer.remove()
+    }
+  })
+
+  test('preserves slotProps.root when capping paper height under modal=true', () => {
+    const customContainer = document.createElement('div')
+    Object.defineProperty(customContainer, 'clientHeight', {
+      value: 500,
+      configurable: true,
+    })
+    document.body.appendChild(customContainer)
+    try {
+      render(
+        <ThemeProvider theme={theme}>
+          <ResponsiveDrawer
+            ref={anchor}
+            {...defaultProps}
+            container={customContainer}
+            slotProps={
+              {
+                root: { 'data-testid': 'drawer-root-slot' },
+                paper: { 'data-testid': 'drawer-paper-slot' },
+              } as never
+            }
+          />
+        </ThemeProvider>,
+      )
+      expect(screen.getByTestId('drawer-root-slot')).toBeDefined()
+      expect(screen.getByTestId('drawer-paper-slot')).toBeDefined()
+      const paper = document.querySelector<HTMLElement>('.MuiPopover-paper')!
+      expect(paper.style.maxHeight).toBe('450px')
+    } finally {
+      customContainer.remove()
+    }
+  })
+
   test('respects sx prop on the Popover', () => {
     expect(() =>
       render(

package/src/components/responsive-drawer/responsive-drawer.tsx

@@ -5,7 +5,13 @@ import {
   type PopoverOrigin,
   type PopoverProps,
 } from '@mui/material'
-import { useCallback, useRef, type CSSProperties, type ReactNode } from 'react'
+import {
+  useCallback,
+  useRef,
+  useSyncExternalStore,
+  type CSSProperties,
+  type ReactNode,
+} from 'react'
 
 type ResponsiveDrawerPosition =
   | 'top-left'
@@ -17,14 +23,7 @@ type ResponsiveDrawerPosition =
 export type ResponsiveDrawerPlacement = 'side' | 'overlay'
 
 /**
- * Resolve the Popover anchor/transform origins for a given corner + placement.
- *
- * `transformOrigin` (the panel corner that pins to the anchor point) is the same
- * for both placements: the panel's own corner matching `position`. `anchorOrigin`
- * (the point on the anchor the panel pins to) differs:
- * - `'side'` flips horizontally → the panel opens beside the trigger.
- * - `'overlay'` uses the same corner → the panel sits **on top of** the anchor
- *   (e.g. a trigger that's hidden while the panel is open), pinned corner-to-corner.
+ * Popover anchor/transform origins. `'overlay'` pins corner-to-corner on the anchor.
  */
 export function resolveOrigins(
   position: ResponsiveDrawerPosition,
@@ -37,8 +36,6 @@ export function resolveOrigins(
   return {
     anchorOrigin: {
       vertical: isBottom ? 'bottom' : 'top',
-      // `'side'` flips horizontally to open beside the anchor; `'overlay'` keeps
-      // the same edge so the panel lands on top of it.
       horizontal: overlay
         ? isRight
           ? 'right'
@@ -69,11 +66,12 @@ export function ResponsiveDrawer<
   position,
   sx,
   slotProps,
+  container,
   onChangeCollapsed,
   modal = true,
   placement = 'side',
 }: Required<Pick<T, 'collapsed' | 'onChangeCollapsed' | 'position'>> &
-  Pick<PopoverProps, 'slotProps' | 'sx'> & {
+  Pick<PopoverProps, 'slotProps' | 'sx' | 'container'> & {
     ref: HTMLElement | null
     isMobile: boolean
     children: ReactNode
@@ -92,18 +90,7 @@ export function ResponsiveDrawer<
      */
     placement?: ResponsiveDrawerPlacement
   }) {
-  // MUI Popover computes its position once on open and never re-measures when
-  // its content resizes — so a panel that grows/shrinks (e.g. collapsing legend
-  // groups) keeps its frozen `top` and detaches from the anchored edge (the
-  // "blink"). Re-run the Popover's own positioning (`action.updatePosition`)
-  // whenever the content changes size: with `transformOrigin` matching the
-  // anchor edge, that edge stays pinned (bottom for `bottom-*`, top for
-  // `top-*`) — and because updatePosition is synchronous, it tracks every
-  // animation frame smoothly rather than snapping after a debounce.
-  //
-  // A callback ref (not a `useEffect`) attaches the observer the moment the
-  // content mounts — the Popover renders into a portal behind a transition, so
-  // the element isn't available on the effect tick that follows `open`.
+  // Popover position is frozen on open — re-measure on content resize (callback ref: portal mounts after open).
   const popoverActions = useRef<PopoverActions>(null)
   const observerRef = useRef<ResizeObserver | null>(null)
   const observeContent = useCallback((el: HTMLDivElement | null) => {
@@ -118,8 +105,27 @@ export function ResponsiveDrawer<
     }
   }, [])
 
+  // Popover Paper is auto-height — `%` max-height needs a measured px cap from `container`.
+  const measurableContainer =
+    container && typeof container !== 'function' ? container : null
+  const subscribe = useCallback(
+    (onStoreChange: () => void) => {
+      if (!measurableContainer || typeof ResizeObserver === 'undefined') {
+        return () => undefined
+      }
+      const observer = new ResizeObserver(onStoreChange)
+      observer.observe(measurableContainer)
+      return () => observer.disconnect()
+    },
+    [measurableContainer],
+  )
+  const getSnapshot = useCallback(
+    () => measurableContainer?.clientHeight,
+    [measurableContainer],
+  )
+  const containerHeight = useSyncExternalStore(subscribe, getSnapshot)
+
   if (isMobile) {
-    // MUI calls `onClose(event, reason)`; adapt it to the boolean contract.
     return (
       <Drawer
         anchor='bottom'
@@ -133,41 +139,60 @@ export function ResponsiveDrawer<
 
   const { anchorOrigin, transformOrigin } = resolveOrigins(position, placement)
 
-  // Non-modal mode injects pointer-through `style` into the root/paper slots so
-  // clicks fall through to the content behind (the map) while the panel stays
-  // interactive. Only the legend uses it and it passes no `slotProps`, so the
-  // common path (modal, incl. Basemaps' callback/object slotProps) is passed
-  // straight through untouched.
   const objectSlotProps = slotProps as
     | { root?: Record<string, unknown>; paper?: { style?: CSSProperties } }
     | undefined
-  const mergedSlotProps: PopoverProps['slotProps'] = modal
-    ? slotProps
-    : {
-        root: {
-          style: { pointerEvents: 'none' },
-          ...objectSlotProps?.root,
-        },
-        paper: {
-          ...objectSlotProps?.paper,
-          style: {
-            pointerEvents: 'auto',
-            ...objectSlotProps?.paper?.style,
-          },
-        },
+  // Capped Paper: disable outer scroll + flex so inner scroll regions can shrink.
+  const paperMaxHeightStyle: CSSProperties | undefined =
+    containerHeight != null && containerHeight > 0
+      ? {
+          maxHeight: containerHeight * 0.9,
+          overflow: 'hidden',
+          display: 'flex',
+          flexDirection: 'column',
+        }
+      : undefined
+  const contentWrapperStyle: CSSProperties | undefined = paperMaxHeightStyle
+    ? {
+        display: 'flex',
+        flexDirection: 'column',
+        flex: 1,
+        minHeight: 0,
+        maxHeight: '100%',
+        overflow: 'hidden',
+        width: '100%',
       }
+    : undefined
+  const mergedSlotProps: PopoverProps['slotProps'] =
+    modal && !paperMaxHeightStyle
+      ? slotProps
+      : {
+          ...(typeof slotProps === 'object' && slotProps != null
+            ? slotProps
+            : {}),
+          ...(!modal && {
+            root: {
+              style: { pointerEvents: 'none' },
+              ...objectSlotProps?.root,
+            },
+          }),
+          paper: {
+            ...objectSlotProps?.paper,
+            style: {
+              ...(!modal && { pointerEvents: 'auto' }),
+              ...paperMaxHeightStyle,
+              ...objectSlotProps?.paper?.style,
+            },
+          },
+        }
 
   return (
     <Popover
       action={popoverActions}
       sx={sx}
+      container={container}
       anchorEl={ref}
-      // Guard on `ref` so an open-by-default panel doesn't render before the
-      // anchor callback-ref has resolved (avoids the null-anchorEl warning +
-      // one-frame misposition; it re-renders non-null immediately after mount).
       open={!collapsed && ref != null}
-      // In non-modal mode neither backdrop nor Escape dismisses — close via
-      // `onChangeCollapsed` (e.g. the panel's own ✕).
       onClose={modal ? () => onChangeCollapsed(true) : undefined}
       hideBackdrop={!modal}
       disableScrollLock={!modal}
@@ -179,8 +204,9 @@ export function ResponsiveDrawer<
       transformOrigin={transformOrigin}
       slotProps={mergedSlotProps}
     >
-      {/* Observed for content-resize → keeps the Popover pinned (see above). */}
-      <div ref={observeContent}>{children}</div>
+      <div ref={observeContent} style={contentWrapperStyle}>
+        {children}
+      </div>
     </Popover>
   )
 }

package/src/legend/components/a11y.ts

@@ -0,0 +1,14 @@
+import type { KeyboardEvent } from 'react'
+
+/**
+ * Enter/Space activate a non-native `role='button'` element (the accordion
+ * title areas of `Legend.Row` / `Legend.Group`), like a real button.
+ */
+export function accordionKeyDown(toggle: () => void) {
+  return (event: KeyboardEvent<HTMLElement>) => {
+    if (event.key === 'Enter' || event.key === ' ') {
+      event.preventDefault()
+      toggle()
+    }
+  }
+}

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