@carto/ps-react-ui 4.14.1 → 4.16.0

package/src/chat/bubbles/chat-agent-message.tsx

@@ -1,11 +1,31 @@
+import { forwardRef } from 'react'
 import { Box, styled, type BoxProps } from '@mui/material'
+import type { ChatAgentMessageProps } from '../types'
 import { styles } from './styles'
 
 const InnerBox = ({ className, ...props }: BoxProps) => (
   <Box className={`PsChat--agent-message ${className ?? ''}`} {...props} />
 )
 
-export const ChatAgentMessage = styled(InnerBox)(({ theme }) =>
+const StyledAgentMessage = styled(InnerBox)(({ theme }) =>
   styles.agentMessageContainer(theme),
 )
+
+/**
+ * Agent reply bubble. A styles container that positions the reply and its
+ * composed pieces (text, loaders, tool traces, …); it renders `children`
+ * verbatim and forwards its `ref` to the underlying element. For Markdown
+ * replies, compose `ChatAgentMessageMarkdown` instead of teaching this
+ * container about the markdown engine.
+ */
+export const ChatAgentMessage = forwardRef<
+  HTMLDivElement,
+  ChatAgentMessageProps
+>(function ChatAgentMessage({ children, ...props }, ref) {
+  return (
+    <StyledAgentMessage ref={ref} {...props}>
+      {children}
+    </StyledAgentMessage>
+  )
+})
 ChatAgentMessage.displayName = 'ChatAgentMessage'

package/src/chat/bubbles/index.ts

@@ -1,4 +1,5 @@
 export { ChatUserMessage } from './chat-user-message'
 export { ChatAgentMessage } from './chat-agent-message'
+export { ChatAgentMessageMarkdown } from './chat-agent-message-markdown'
 export { ChatErrorMessage } from './chat-error-message'
 export { ChatSuggestionButton } from './chat-suggestion-button'

package/src/chat/index.ts

@@ -4,6 +4,7 @@ export type {
   ChatErrorAction,
   ChatUserMessageProps,
   ChatAgentMessageProps,
+  ChatAgentMessageMarkdownProps,
   ChatErrorMessageProps,
   ChatSuggestionButtonProps,
   ChatThinkingProps,
@@ -37,6 +38,7 @@ export { useTypewriter } from './use-typewriter'
 // Messages
 export { ChatUserMessage } from './bubbles/chat-user-message'
 export { ChatAgentMessage } from './bubbles/chat-agent-message'
+export { ChatAgentMessageMarkdown } from './bubbles/chat-agent-message-markdown'
 export { ChatErrorMessage } from './bubbles/chat-error-message'
 export { ChatSuggestionButton } from './bubbles/chat-suggestion-button'
 export { ChatMessageOverflow } from './bubbles/styles'

package/src/chat/types.ts

@@ -25,6 +25,16 @@ export interface ChatAgentMessageProps extends ChatSxProps {
   children: ReactNode
 }
 
+export interface ChatAgentMessageMarkdownProps extends ChatSxProps {
+  /**
+   * Markdown source — rendered as GitHub-Flavored Markdown (tables, task lists,
+   * strikethrough) through the library's sanitized renderer, inside a
+   * `ChatAgentMessage`. Raw HTML is skipped and images are stripped, since the
+   * content is model output.
+   */
+  children: string
+}
+
 export interface ChatErrorMessageProps extends ChatSxProps {
   errors: string[]
   icon?: ReactNode

package/src/components/index.ts

@@ -28,11 +28,13 @@ export type {
   LassoGeometryType,
   LassoLayerFiltersUIProps,
   LassoLayerFilterItem,
+  LassoMessageUIProps,
 } from './lasso-tool/types'
 export { LassoToolsUI } from './lasso-tool/lasso-tool'
 export { LassoToolsInlineUI } from './lasso-tool/lasso-tool-inline'
 export { LassoGeometryToolbarUI } from './lasso-tool/geometry-toolbar'
 export { LassoLayerFiltersUI } from './lasso-tool/layer-filters'
+export { LassoMessageUI } from './lasso-tool/message'
 export {
   DEFAULT_LASSO_TOOLS_MODES_MAPPING,
   LASSO_TOOLS_LABELS,

package/src/components/lasso-tool/message.tsx

@@ -0,0 +1,36 @@
+import { Alert, AlertTitle, Snackbar } from '@mui/material'
+import type { LassoMessageUIProps } from './types'
+
+/**
+ * Presentational counterpart of `LassoTools.Message` (`@carto/ps-react-maps`),
+ * positioned by that render-props component. Auto-hides after 5 seconds via
+ * MUI `Snackbar` (calls `onDismiss`, which removes the message from the store).
+ */
+export function LassoMessageUI({
+  message,
+  onDismiss,
+  AlertProps,
+  SnackbarProps,
+}: LassoMessageUIProps) {
+  return (
+    <Snackbar
+      open
+      autoHideDuration={5000}
+      // 'clickaway' is ignored so map interactions don't dismiss the message.
+      onClose={(_, reason) => reason !== 'clickaway' && onDismiss()}
+      // Stay in flow — the maps-side `LassoTools.Message` owns positioning.
+      sx={{ position: 'static', transform: 'none' }}
+      {...SnackbarProps}
+    >
+      <Alert
+        severity={message.severity ?? 'info'}
+        action={message.action}
+        onClose={onDismiss}
+        {...AlertProps}
+      >
+        <AlertTitle>{message.title}</AlertTitle>
+        {message.content}
+      </Alert>
+    </Snackbar>
+  )
+}

package/src/components/lasso-tool/types.ts

@@ -1,11 +1,14 @@
 import type {
+  AlertColor,
+  AlertProps,
   Box,
   ChipProps,
   DialogProps,
   Paper,
+  SnackbarProps,
   TooltipProps,
 } from '@mui/material'
-import type { ComponentProps, ComponentType } from 'react'
+import type { ComponentProps, ComponentType, ReactNode } from 'react'
 import type {
   LassoToolsMode,
   LassoToolsModes,
@@ -153,6 +156,22 @@ export interface LassoGeometryToolbarUIProps {
   PaperProps?: ComponentProps<typeof Paper>
 }
 
+export interface LassoMessageUIProps {
+  /** Message from the lasso tools store (`LassoToolsMessage` in `@carto/ps-react-maps`). */
+  message: {
+    id: string
+    title: string
+    /** Body rendered under the title. */
+    content?: ReactNode
+    /** @default 'info' */
+    severity?: AlertColor
+    action?: ReactNode
+  }
+  onDismiss: () => void
+  AlertProps?: Omit<AlertProps, 'severity' | 'onClose' | 'children' | 'action'>
+  SnackbarProps?: Omit<SnackbarProps, 'open' | 'onClose' | 'children'>
+}
+
 export interface LassoLayerFilterItem {
   id: string
   label: string

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

package/src/legend/components/index.ts

@@ -1,4 +1,3 @@
-// Composition shell
 export { LegendGroup } from './legend-group/legend-group'
 export type { LegendGroupProps } from './legend-group/legend-group'
 export { LegendRow } from './legend-row/legend-row'
@@ -8,12 +7,13 @@ export type { LegendActionsProps } from './legend-actions/legend-actions'
 export {
   LegendRowContext,
   LegendGroupContext,
+  LegendMenuContext,
   useLegendRow,
   useLegendGroupId,
+  useLegendMenu,
 } from './contexts'
-export type { LegendRowContextValue } from './contexts'
+export type { LegendRowContextValue, LegendMenuController } 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'
@@ -21,7 +21,6 @@ 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 {

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

@@ -15,9 +15,10 @@ export interface LegendActionsProps {
 /**
  * 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).
+ * renders this slot inside the header, wrapped in the hover-fade group
+ * (`PsLegend-rowFade` in rows, `PsLegend-groupFade` in group headers —
+ * resolved from the nearest context). Compose the ⋮ menu last so it sits
+ * rightmost, per design.
  *
  * @experimental This API is new and may change in a future release.
  */