@carto/ps-react-ui 4.12.1 → 4.13.0

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

@@ -1,6 +1,6 @@
 import { render, screen, fireEvent } from '@testing-library/react'
-import { describe, test, expect, vi, beforeEach } from 'vitest'
-import { ResponsiveDrawer } from './responsive-drawer'
+import { describe, test, expect, vi, beforeEach, afterEach } from 'vitest'
+import { ResponsiveDrawer, resolveOrigins } from './responsive-drawer'
 import { ThemeProvider } from '@mui/material'
 import { createTheme } from '@mui/material/styles'
 
@@ -10,6 +10,10 @@ const theme = createTheme()
 describe('ResponsiveDrawer', () => {
   const mockOnChangeCollapsed = vi.fn()
 
+  // A real anchor element: the desktop Popover only opens when `ref != null`
+  // (the open-by-default guard), and positioning needs a DOM node.
+  let anchor: HTMLElement
+
   const defaultProps = {
     collapsed: false,
     onChangeCollapsed: mockOnChangeCollapsed,
@@ -20,12 +24,18 @@ describe('ResponsiveDrawer', () => {
 
   beforeEach(() => {
     mockOnChangeCollapsed.mockReset()
+    anchor = document.createElement('div')
+    document.body.appendChild(anchor)
+  })
+
+  afterEach(() => {
+    anchor.remove()
   })
 
   test('renders in desktop mode when isMobile is false', () => {
     const { container } = render(
       <ThemeProvider theme={theme}>
-        <ResponsiveDrawer ref={null} {...defaultProps} />
+        <ResponsiveDrawer ref={anchor} {...defaultProps} />
       </ThemeProvider>,
     )
 
@@ -40,10 +50,21 @@ describe('ResponsiveDrawer', () => {
     expect(presentationElements.length).toBe(0)
   })
 
+  test('does not open the desktop popover until the anchor ref resolves', () => {
+    // Open-by-default guard: collapsed=false but ref=null → stays closed so the
+    // popover never renders with a null anchorEl.
+    render(
+      <ThemeProvider theme={theme}>
+        <ResponsiveDrawer ref={null} {...defaultProps} />
+      </ThemeProvider>,
+    )
+    expect(screen.queryByTestId('drawer-content')).toBeNull()
+  })
+
   test('renders in mobile mode when isMobile is true', () => {
     render(
       <ThemeProvider theme={theme}>
-        <ResponsiveDrawer ref={null} {...defaultProps} isMobile={true} />
+        <ResponsiveDrawer ref={anchor} {...defaultProps} isMobile={true} />
       </ThemeProvider>,
     )
 
@@ -61,7 +82,7 @@ describe('ResponsiveDrawer', () => {
   test('hides content when collapsed is true in desktop mode', () => {
     render(
       <ThemeProvider theme={theme}>
-        <ResponsiveDrawer ref={null} {...defaultProps} collapsed={true} />
+        <ResponsiveDrawer ref={anchor} {...defaultProps} collapsed={true} />
       </ThemeProvider>,
     )
 
@@ -73,7 +94,7 @@ describe('ResponsiveDrawer', () => {
   test('closes drawer when clicking outside in mobile mode', () => {
     const { container } = render(
       <ThemeProvider theme={theme}>
-        <ResponsiveDrawer ref={null} {...defaultProps} isMobile={true} />
+        <ResponsiveDrawer ref={anchor} {...defaultProps} isMobile={true} />
       </ThemeProvider>,
     )
 
@@ -90,9 +111,7 @@ describe('ResponsiveDrawer', () => {
   })
 
   // Each of the four `position` values produces a different
-  // anchorOrigin/transformOrigin combination. Exercising all four covers
-  // both ternary branches of position.startsWith('bottom') and
-  // position.endsWith('right').
+  // anchorOrigin/transformOrigin combination.
   test.each(['top-left', 'top-right', 'bottom-left', 'bottom-right'] as const)(
     'renders in desktop mode with position=%s',
     (position) => {
@@ -100,7 +119,7 @@ describe('ResponsiveDrawer', () => {
         render(
           <ThemeProvider theme={theme}>
             <ResponsiveDrawer
-              ref={null}
+              ref={anchor}
               {...defaultProps}
               position={position}
             />
@@ -110,22 +129,14 @@ describe('ResponsiveDrawer', () => {
     },
   )
 
-  test('desktop Popover onClose invokes onChangeCollapsed(true)', () => {
-    const { container } = render(
+  test('modal (default): renders an (invisible) backdrop', () => {
+    render(
       <ThemeProvider theme={theme}>
-        <ResponsiveDrawer ref={null} {...defaultProps} />
+        <ResponsiveDrawer ref={anchor} {...defaultProps} />
       </ThemeProvider>,
     )
-    // The Popover renders a backdrop that closes on click.
-    const backdrop = container.querySelector('.MuiBackdrop-root')
-    if (backdrop) {
-      fireEvent.click(backdrop)
-      expect(mockOnChangeCollapsed).toHaveBeenCalledWith(true)
-    } else {
-      // jsdom + Popover positioning quirks: simulate the close handler directly
-      // by re-rendering with collapsed=true via the props change.
-      expect(mockOnChangeCollapsed).toBeDefined()
-    }
+    // The popover portals to document.body, so query the whole document.
+    expect(document.querySelector('.MuiBackdrop-root')).not.toBeNull()
   })
 
   test('forwards slotProps to the underlying Popover', () => {
@@ -134,7 +145,7 @@ describe('ResponsiveDrawer', () => {
       render(
         <ThemeProvider theme={theme}>
           <ResponsiveDrawer
-            ref={null}
+            ref={anchor}
             {...defaultProps}
             slotProps={slotProps}
           />
@@ -148,7 +159,7 @@ describe('ResponsiveDrawer', () => {
       render(
         <ThemeProvider theme={theme}>
           <ResponsiveDrawer
-            ref={null}
+            ref={anchor}
             {...defaultProps}
             sx={{ zIndex: 9999 }}
           />
@@ -156,4 +167,97 @@ describe('ResponsiveDrawer', () => {
       ),
     ).not.toThrow()
   })
+
+  // ── Non-modal mode (modal={false}) ─────────────────────────────────────────
+
+  test('non-modal: renders no backdrop', () => {
+    render(
+      <ThemeProvider theme={theme}>
+        <ResponsiveDrawer ref={anchor} {...defaultProps} modal={false} />
+      </ThemeProvider>,
+    )
+    expect(document.querySelector('.MuiBackdrop-root')).toBeNull()
+    // Content still renders.
+    expect(screen.getByTestId('drawer-content')).toBeDefined()
+  })
+
+  test('non-modal: Escape does not close the panel', () => {
+    render(
+      <ThemeProvider theme={theme}>
+        <ResponsiveDrawer ref={anchor} {...defaultProps} modal={false} />
+      </ThemeProvider>,
+    )
+    // Fire on a node inside the Modal root so it reaches the Modal's key handler.
+    fireEvent.keyDown(screen.getByTestId('drawer-content'), {
+      key: 'Escape',
+      code: 'Escape',
+    })
+    expect(mockOnChangeCollapsed).not.toHaveBeenCalled()
+  })
+
+  test('modal (default): Escape closes the panel', () => {
+    render(
+      <ThemeProvider theme={theme}>
+        <ResponsiveDrawer ref={anchor} {...defaultProps} />
+      </ThemeProvider>,
+    )
+    fireEvent.keyDown(screen.getByTestId('drawer-content'), {
+      key: 'Escape',
+      code: 'Escape',
+    })
+    expect(mockOnChangeCollapsed).toHaveBeenCalledWith(true)
+  })
+})
+
+// ── resolveOrigins (pure) ─────────────────────────────────────────────────────
+
+describe('resolveOrigins', () => {
+  test('side placement opens beside the trigger (horizontal flip)', () => {
+    expect(resolveOrigins('bottom-right', 'side')).toEqual({
+      anchorOrigin: { vertical: 'bottom', horizontal: 'left' },
+      transformOrigin: { vertical: 'bottom', horizontal: 'right' },
+    })
+    expect(resolveOrigins('top-left', 'side')).toEqual({
+      anchorOrigin: { vertical: 'top', horizontal: 'right' },
+      transformOrigin: { vertical: 'top', horizontal: 'left' },
+    })
+  })
+
+  test('overlay placement pins corner-to-corner (panel sits on top of the anchor)', () => {
+    // anchorOrigin === transformOrigin for every corner → the panel lands on the
+    // anchor's own corner (it's hidden while open).
+    for (const position of [
+      'top-left',
+      'top-right',
+      'bottom-left',
+      'bottom-right',
+    ] as const) {
+      const { anchorOrigin, transformOrigin } = resolveOrigins(
+        position,
+        'overlay',
+      )
+      expect(anchorOrigin).toEqual(transformOrigin)
+    }
+    expect(resolveOrigins('bottom-right', 'overlay').anchorOrigin).toEqual({
+      vertical: 'bottom',
+      horizontal: 'right',
+    })
+    expect(resolveOrigins('top-left', 'overlay').anchorOrigin).toEqual({
+      vertical: 'top',
+      horizontal: 'left',
+    })
+  })
+
+  test('transformOrigin is independent of placement (panel keeps its own corner)', () => {
+    for (const position of [
+      'top-left',
+      'top-right',
+      'bottom-left',
+      'bottom-right',
+    ] as const) {
+      const side = resolveOrigins(position, 'side')
+      const overlay = resolveOrigins(position, 'overlay')
+      expect(overlay.transformOrigin).toEqual(side.transformOrigin)
+    }
+  })
 })

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

@@ -1,11 +1,64 @@
-import { Drawer, Popover, type PopoverProps } from '@mui/material'
-import type { ReactNode } from 'react'
+import {
+  Drawer,
+  Popover,
+  type PopoverActions,
+  type PopoverOrigin,
+  type PopoverProps,
+} from '@mui/material'
+import { useCallback, useRef, type CSSProperties, type ReactNode } from 'react'
+
+type ResponsiveDrawerPosition =
+  | 'top-left'
+  | 'top-right'
+  | 'bottom-left'
+  | 'bottom-right'
+
+/** Placement of the panel relative to its anchor (desktop popover only). */
+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.
+ */
+export function resolveOrigins(
+  position: ResponsiveDrawerPosition,
+  placement: ResponsiveDrawerPlacement,
+): { anchorOrigin: PopoverOrigin; transformOrigin: PopoverOrigin } {
+  const isBottom = position.startsWith('bottom')
+  const isRight = position.endsWith('right')
+  const overlay = placement === 'overlay'
+
+  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'
+          : 'left'
+        : isRight
+          ? 'left'
+          : 'right',
+    },
+    transformOrigin: {
+      vertical: isBottom ? 'bottom' : 'top',
+      horizontal: isRight ? 'right' : 'left',
+    },
+  }
+}
 
 export function ResponsiveDrawer<
   T extends {
     collapsed: boolean
     onChangeCollapsed: (collapsed: boolean) => void
-    position: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
+    position: ResponsiveDrawerPosition
     slotProps?: PopoverProps['slotProps']
   },
 >({
@@ -17,37 +70,117 @@ export function ResponsiveDrawer<
   sx,
   slotProps,
   onChangeCollapsed,
+  modal = true,
+  placement = 'side',
 }: Required<Pick<T, 'collapsed' | 'onChangeCollapsed' | 'position'>> &
   Pick<PopoverProps, 'slotProps' | 'sx'> & {
     ref: HTMLElement | null
     isMobile: boolean
     children: ReactNode
+    /**
+     * When `false`, the desktop popover is **non-modal**: no backdrop, clicks
+     * pass through to the content behind it (e.g. a map stays interactive), no
+     * focus trap, and neither backdrop-click nor Escape closes it (close it via
+     * `onChangeCollapsed`). Defaults to `true` (standard dismissable popover).
+     * Desktop-only — the mobile drawer is unaffected.
+     */
+    modal?: boolean
+    /**
+     * Desktop popover placement relative to the anchor: `'side'` (default) opens
+     * beside the trigger; `'overlay'` pins corner-to-corner, sitting on top of
+     * the anchor (e.g. a trigger hidden while the panel is open). Desktop-only.
+     */
+    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`.
+  const popoverActions = useRef<PopoverActions>(null)
+  const observerRef = useRef<ResizeObserver | null>(null)
+  const observeContent = useCallback((el: HTMLDivElement | null) => {
+    observerRef.current?.disconnect()
+    observerRef.current = null
+    if (el && typeof ResizeObserver !== 'undefined') {
+      const observer = new ResizeObserver(() =>
+        popoverActions.current?.updatePosition(),
+      )
+      observer.observe(el)
+      observerRef.current = observer
+    }
+  }, [])
+
   if (isMobile) {
+    // MUI calls `onClose(event, reason)`; adapt it to the boolean contract.
     return (
-      <Drawer anchor='bottom' open={!collapsed} onClose={onChangeCollapsed}>
+      <Drawer
+        anchor='bottom'
+        open={!collapsed}
+        onClose={() => onChangeCollapsed(true)}
+      >
         {children}
       </Drawer>
     )
   }
 
+  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,
+          },
+        },
+      }
+
   return (
     <Popover
+      action={popoverActions}
       sx={sx}
       anchorEl={ref}
-      open={!collapsed}
-      onClose={() => onChangeCollapsed(true)}
-      anchorOrigin={{
-        vertical: position.startsWith('bottom') ? 'bottom' : 'top',
-        horizontal: position.endsWith('right') ? 'left' : 'right',
-      }}
-      transformOrigin={{
-        vertical: position.startsWith('bottom') ? 'bottom' : 'top',
-        horizontal: position.endsWith('right') ? 'right' : 'left',
-      }}
-      slotProps={slotProps}
+      // 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}
+      disableEscapeKeyDown={!modal}
+      disableAutoFocus={!modal}
+      disableEnforceFocus={!modal}
+      disableRestoreFocus={!modal}
+      anchorOrigin={anchorOrigin}
+      transformOrigin={transformOrigin}
+      slotProps={mergedSlotProps}
     >
-      {children}
+      {/* Observed for content-resize → keeps the Popover pinned (see above). */}
+      <div ref={observeContent}>{children}</div>
     </Popover>
   )
 }

package/src/legend/components/contexts.ts

@@ -0,0 +1,32 @@
+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).
+ */
+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
+}
+
+export const LegendRowContext = createContext<LegendRowContextValue | null>(
+  null,
+)
+
+/** Nearest `Legend.Row` composition context, or `null` outside a row. */
+export function useLegendRow(): LegendRowContextValue | null {
+  return useContext(LegendRowContext)
+}
+
+/** Per-group composition context provided by `Legend.Group` (the group id). */
+export const LegendGroupContext = createContext<string | null>(null)
+
+/** Nearest `Legend.Group` id, or `null` outside a group. */
+export function useLegendGroupId(): string | null {
+  return useContext(LegendGroupContext)
+}

package/src/legend/components/icons.tsx

@@ -0,0 +1,22 @@
+import { createSvgIcon } from '@mui/material'
+
+/**
+ * Indeterminate visibility — an outlined eye with an internal slash, shown on
+ * a group whose member layers are partially hidden ("mixed" state). Path data
+ * exported from the Figma source (`MUI_visibility_indeterminate`, CARTO PS Lib
+ * Documentation node 5877-16982); the glyph is centered at (184, 24) in the
+ * header frame and drawn on a 18px grid (75% of the 24px box), so it is
+ * re-centered into the standard viewBox and scaled by 4/3 — the resulting
+ * 22×15-unit eye matches the MUI `Visibility*` icons exactly.
+ */
+export const VisibilityIndeterminateIcon = createSvgIcon(
+  <g transform='translate(12 12) scale(1.33333) translate(-184 -24)'>
+    <path
+      fillRule='evenodd'
+      clipRule='evenodd'
+      d='M184.901 29.5794L185.217 29.5415C185.803 29.4604 186.372 29.3216 186.918 29.1319L187 29.1007L187 29.1033L187.208 29.0255L187.536 28.8904C187.722 28.8088 187.906 28.721 188.086 28.6272L188.366 28.4747C188.381 28.4663 188.395 28.4578 188.41 28.4493C188.418 28.4451 188.425 28.4408 188.432 28.4365C188.455 28.4234 188.478 28.4102 188.5 28.3969C188.551 28.3668 188.601 28.3362 188.652 28.3052L188.912 28.1374C189.598 27.6788 190.217 27.1271 190.75 26.5002L190.751 26.4954C190.989 26.2164 191.21 25.9226 191.413 25.6152C191.488 25.5007 191.561 25.3843 191.631 25.2662L191.757 25.0445L191.878 24.8189L192.021 24.5306L192.15 24.2443L192.25 24C190.98 20.7776 187.885 18.4747 184.239 18.3782L184 18.375L183.716 18.3795L183.637 18.3823L183.373 18.3967L183.103 18.4198L182.838 18.4506L182.666 18.4749L182.426 18.5146C182.19 18.557 181.957 18.6087 181.728 18.6684L181.55 18.7175L181.271 18.8039L182.508 20.04L182.801 19.9854C183.194 19.9182 183.592 19.875 184 19.875C186.842 19.875 189.378 21.4725 190.615 24C190.172 24.915 189.55 25.7025 188.807 26.34L188.811 26.3446C188.71 26.4323 188.606 26.5172 188.5 26.5991C188.455 26.6337 188.41 26.6679 188.364 26.7015C188.108 26.8897 187.84 27.0611 187.562 27.2145C187.088 27.4755 186.585 27.6844 186.058 27.836L186.062 27.84L185.778 27.9125C185.707 27.9293 185.635 27.9452 185.563 27.9602C185.297 28.0173 185.025 28.06 184.75 28.0876V28.0866C184.503 28.1118 184.253 28.125 184 28.125C181.158 28.125 178.622 26.5275 177.385 24C177.91 22.9275 178.675 22.0425 179.582 21.3525L180.895 22.665L180.826 22.844C180.697 23.2065 180.625 23.595 180.625 24C180.625 25.86 182.14 27.375 184 27.375C184.258 27.375 184.509 27.3459 184.75 27.2915C185.462 27.129 186.09 26.7397 186.553 26.2048L179.79 19.4389C179.339 19.6833 178.912 19.9656 178.512 20.2817L178.517 20.2875L178.271 20.4884C177.704 20.9671 177.197 21.516 176.766 22.1227C176.404 22.6333 176.095 23.1838 175.845 23.7662L175.75 24C177.048 27.2925 180.25 29.625 184 29.625L184.285 29.6205L184.492 29.6116L184.628 29.6025L184.901 29.5794ZM182.133 23.9025L184.09 25.86L184.045 25.8703L184 25.875C182.965 25.875 182.125 25.035 182.125 24L182.133 23.9025Z'
+    />
+    <path d='M187.368 23.9925C187.375 22.1325 185.86 20.625 184 20.625C183.722 20.625 183.46 20.6625 183.198 20.73L184.75 22.2825L184.889 22.3507C185.252 22.5477 185.543 22.8625 185.71 23.2425L187.263 24.795L187.304 24.6011C187.342 24.4045 187.368 24.2006 187.368 23.9925Z' />
+  </g>,
+  'VisibilityIndeterminate',
+)

package/src/legend/components/index.ts

@@ -0,0 +1,39 @@
+// Composition shell
+export { LegendGroup } from './legend-group/legend-group'
+export type { LegendGroupProps } from './legend-group/legend-group'
+export { LegendRow } from './legend-row/legend-row'
+export type { LegendRowProps } from './legend-row/legend-row'
+export { LegendActions } from './legend-actions/legend-actions'
+export type { LegendActionsProps } from './legend-actions/legend-actions'
+export {
+  LegendRowContext,
+  LegendGroupContext,
+  useLegendRow,
+  useLegendGroupId,
+} from './contexts'
+export type { LegendRowContextValue } from './contexts'
+
+// Store-connected actions & controls (context-driven)
+export { LegendVisibilityToggle } from './legend-visibility-toggle/legend-visibility-toggle'
+export { LegendRowMenu } from './legend-row-menu/legend-row-menu'
+export { LegendZoomTo } from './legend-row-menu/legend-zoom-to'
+export { LegendOpacity } from './legend-opacity/legend-opacity'
+export { LegendConfigSelect } from './legend-config-select/legend-config-select'
+export { LegendItem } from './legend-item/legend-item'
+
+// Item renderers (pure UI)
+export { LegendItemUI } from './legend-item/legend-item-ui'
+export type { LegendItemUIProps } from './legend-item/legend-item-ui'
+export {
+  LegendSwatch,
+  DEFAULT_SWATCH_SIZE,
+} from './legend-swatch/legend-swatch'
+export type { LegendSwatchProps } from './legend-swatch/legend-swatch'
+export { LegendCategoryUI } from './legend-category/legend-category-ui'
+export type { LegendCategoryUIProps } from './legend-category/legend-category-ui'
+export { LegendRampUI } from './legend-ramp/legend-ramp-ui'
+export type { LegendRampUIProps } from './legend-ramp/legend-ramp-ui'
+export { LegendProportionUI } from './legend-proportion/legend-proportion-ui'
+export type { LegendProportionUIProps } from './legend-proportion/legend-proportion-ui'
+export { LegendIconUI } from './legend-icon/legend-icon-ui'
+export type { LegendIconUIProps } from './legend-icon/legend-icon-ui'

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

@@ -0,0 +1,57 @@
+import {
+  Children,
+  isValidElement,
+  type ReactElement,
+  type ReactNode,
+} from 'react'
+import { Box } from '@mui/material'
+import { useLegendRow } from '../contexts'
+import { styles } from './styles'
+
+export interface LegendActionsProps {
+  children?: ReactNode
+}
+
+/**
+ * Header actions slot for `Legend.Row` / `Legend.Group` (widgets-v2 `Actions`
+ * parity): the wrapper partitions its children by component identity and
+ * renders this slot inside the header, next to the collapse chevron, wrapped
+ * in the hover-fade group (`PsLegend-rowFade` in rows, `PsLegend-groupFade`
+ * in group headers — resolved from the nearest context).
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export function LegendActions({ children }: LegendActionsProps) {
+  const inRow = useLegendRow() !== null
+  return (
+    <Box
+      className={inRow ? 'PsLegend-rowFade' : 'PsLegend-groupFade'}
+      sx={styles.fadeGroup}
+    >
+      {children}
+    </Box>
+  )
+}
+
+/**
+ * Splits a wrapper's children by component identity: `<Legend.Actions>`
+ * elements belong in the header, everything else in the collapsible body.
+ * Identity comparison works because consumers import the slot from the same
+ * module (same pattern as widgets-v2 `Wrapper`).
+ */
+export function partitionLegendChildren(children: ReactNode): {
+  actions: ReactNode[]
+  body: ReactNode[]
+} {
+  const actions: ReactNode[] = []
+  const body: ReactNode[] = []
+  for (const child of Children.toArray(children)) {
+    if (isSlot(child, LegendActions)) actions.push(child)
+    else body.push(child)
+  }
+  return { actions, body }
+}
+
+function isSlot(node: ReactNode, type: unknown): node is ReactElement {
+  return isValidElement(node) && node.type === type
+}

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

@@ -0,0 +1,9 @@
+import type { SxProps, Theme } from '@mui/material'
+
+export const styles = {
+  fadeGroup: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: 0.25,
+  },
+} satisfies Record<string, SxProps<Theme>>