@carto/ps-react-ui 4.20.2 → 4.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carto/ps-react-ui",
-  "version": "4.20.2",
+  "version": "4.22.0",
   "description": "CARTO's Professional Service React Material library",
   "type": "module",
   "devDependencies": {
@@ -17,7 +17,7 @@
     "react-dom": "19.2.8",
     "react-markdown": "10.1.0",
     "zustand": "5.0.15",
-    "@carto/ps-utils": "2.1.0",
+    "@carto/ps-utils": "2.1.1",
     "@carto/ps-common-types": "1.0.0"
   },
   "peerDependencies": {
@@ -35,7 +35,7 @@
     "react-dom": "^19.2.0",
     "react-markdown": "^10.0.0",
     "zustand": "^5.0.0",
-    "@carto/ps-utils": "2.1.0"
+    "@carto/ps-utils": "2.1.1"
   },
   "exports": {
     "./chat": {
@@ -244,7 +244,8 @@
   "dependencies": {
     "rehype-raw": "7.0.0",
     "rehype-sanitize": "6.0.0",
-    "remark-gfm": "4.0.1"
+    "remark-gfm": "4.0.1",
+    "type-fest": "5.8.0"
   },
   "scripts": {
     "dev": "vite build --watch --emptyOutDir=false",

package/src/chat/bubbles/styles.ts

@@ -1,15 +1,34 @@
-import { styled, Typography, type SxProps, type Theme } from '@mui/material'
+import {
+  styled,
+  Typography,
+  type SxProps,
+  type Theme,
+  type TypographyProps,
+} from '@mui/material'
+import type { CSSObject } from '@mui/material/styles'
+import type { FC } from 'react'
 
-export const ChatMessageOverflow = styled(Typography)(() => ({
-  whiteSpace: 'pre-wrap',
-  overflowX: 'clip',
-  overflowWrap: 'break-word',
-  maxWidth: '100%',
-}))
+// The explicit annotation is what keeps this file's .d.ts emittable: the type
+// `styled()` infers can only be named through a pnpm-internal @mui/system path
+// (TS2742), and vite-plugin-dts drops the whole declaration when that happens.
+//
+// ponytail: `component` and `ref` still typecheck, but the prop re-typing that
+// comes with them does not — `component="a" href="#"` is rejected here and
+// accepted on `Typography` itself. Restoring it needs `OverridableComponent`,
+// which a MUI v5 `styled()` result isn't assignable to under React 19 types.
+// Consumers who need the polymorphism use `Typography` directly.
+export const ChatMessageOverflow: FC<TypographyProps> = styled(Typography)(
+  () => ({
+    whiteSpace: 'pre-wrap',
+    overflowX: 'clip',
+    overflowWrap: 'break-word',
+    maxWidth: '100%',
+  }),
+)
 ChatMessageOverflow.displayName = 'ChatMessageOverflow'
 
 export const styles = {
-  agentMessageContainer: (theme: Theme) => ({
+  agentMessageContainer: (theme: Theme): CSSObject => ({
     ...theme.typography.body2,
     width: '100%',
     display: 'flex',

package/src/chat/feedback/chat-actions-container.tsx

@@ -1,6 +1,9 @@
-import { Box, styled } from '@mui/material'
+import { Box, styled, type BoxProps } from '@mui/material'
+import type { FC } from 'react'
 
-export const ChatActionsContainer = styled(Box)(({ theme }) => ({
+// See chat/bubbles/styles.ts: the annotation keeps the declaration emittable,
+// and what it gives up on `component=`.
+export const ChatActionsContainer: FC<BoxProps> = styled(Box)(({ theme }) => ({
   display: 'flex',
   alignItems: 'center',
   gap: theme.spacing(0.5),

package/src/chat/feedback/styles.ts

@@ -121,12 +121,14 @@ export const styles = {
     padding: ({ spacing }) => spacing(1),
     borderRadius: ({ spacing }) => spacing(0.5),
     backgroundColor: ({ palette }) => palette.background.default,
-    fontFamily: ({ typography }) =>
+    fontFamily: ({ typography }): string =>
       typography.code3?.fontFamily ??
       typography.code1?.fontFamily ??
       'monospace',
-    fontSize: ({ typography }) => typography.code3?.fontSize ?? '0.75rem',
-    lineHeight: ({ typography }) => typography.code3?.lineHeight ?? 1.333,
+    fontSize: ({ typography }): string | number =>
+      typography.code3?.fontSize ?? '0.75rem',
+    lineHeight: ({ typography }): string | number =>
+      typography.code3?.lineHeight ?? 1.333,
     whiteSpace: 'pre-wrap',
     wordBreak: 'break-word',
     overflowY: 'auto',
@@ -164,11 +166,12 @@ export const styles = {
     padding: ({ spacing }) => spacing(1),
     background: ({ palette, spacing }) =>
       `linear-gradient(to right, ${palette.action.hover} calc(${spacing(1)} + 3em), ${palette.background.default} calc(${spacing(1)} + 3em))`,
-    fontFamily: ({ typography }) =>
+    fontFamily: ({ typography }): string =>
       typography.code3?.fontFamily ??
       typography.code1?.fontFamily ??
       'monospace',
-    fontSize: ({ typography }) => typography.code3?.fontSize ?? '0.75rem',
+    fontSize: ({ typography }): string | number =>
+      typography.code3?.fontSize ?? '0.75rem',
     whiteSpace: 'pre-wrap',
     wordBreak: 'break-word',
     lineHeight: 1.6,

package/src/components/basemaps/basemaps.tsx

@@ -40,7 +40,7 @@ export function BasemapsUI({
   onChange,
   TooltipProps,
 }: BasemapsUIProps): JSX.Element {
-  const [toggleRef, setToggleRef] = useState<HTMLButtonElement | null>(null)
+  const [anchorEl, setAnchorEl] = useState<HTMLButtonElement | null>(null)
   const [isOpen, setIsOpen] = useState(false)
   const timeoutRef = useRef<NodeJS.Timeout | null>(null)
   const [timer, setTimer] = useState<number | null>(null)
@@ -55,7 +55,7 @@ export function BasemapsUI({
   const groupCount = Object.keys(groups).length
 
   const handleClose = () => {
-    setToggleRef(null)
+    setAnchorEl(null)
     setIsOpen(false)
   }
 
@@ -93,7 +93,7 @@ export function BasemapsUI({
         <IconButton
           sx={styles.toggle}
           onClick={(e) => {
-            setToggleRef(e.currentTarget as HTMLButtonElement)
+            setAnchorEl(e.currentTarget as HTMLButtonElement)
             setIsOpen(true)
           }}
         >
@@ -105,7 +105,7 @@ export function BasemapsUI({
       </Tooltip>
 
       <ResponsiveDrawer
-        ref={toggleRef}
+        anchorEl={anchorEl}
         slotProps={{
           paper: {
             sx: {

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

@@ -10,8 +10,8 @@ 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.
+  // A real anchor element: the desktop Popover only opens when the anchor is
+  // non-null (the open-by-default guard), and positioning needs a DOM node.
   let anchor: HTMLElement
 
   const defaultProps = {
@@ -32,10 +32,20 @@ describe('ResponsiveDrawer', () => {
     anchor.remove()
   })
 
+  test('accepts the anchor through the deprecated `ref` alias', () => {
+    render(
+      <ThemeProvider theme={theme}>
+        <ResponsiveDrawer ref={anchor} {...defaultProps} />
+      </ThemeProvider>,
+    )
+
+    expect(screen.getByTestId('drawer-content')).toBeDefined()
+  })
+
   test('renders in desktop mode when isMobile is false', () => {
     const { container } = render(
       <ThemeProvider theme={theme}>
-        <ResponsiveDrawer ref={anchor} {...defaultProps} />
+        <ResponsiveDrawer anchorEl={anchor} {...defaultProps} />
       </ThemeProvider>,
     )
 
@@ -50,12 +60,12 @@ 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.
+  test('does not open the desktop popover until the anchor resolves', () => {
+    // Open-by-default guard: collapsed=false but anchorEl=null → stays closed so
+    // the popover never renders with a null anchorEl.
     render(
       <ThemeProvider theme={theme}>
-        <ResponsiveDrawer ref={null} {...defaultProps} />
+        <ResponsiveDrawer anchorEl={null} {...defaultProps} />
       </ThemeProvider>,
     )
     expect(screen.queryByTestId('drawer-content')).toBeNull()
@@ -64,7 +74,7 @@ describe('ResponsiveDrawer', () => {
   test('renders in mobile mode when isMobile is true', () => {
     render(
       <ThemeProvider theme={theme}>
-        <ResponsiveDrawer ref={anchor} {...defaultProps} isMobile={true} />
+        <ResponsiveDrawer anchorEl={anchor} {...defaultProps} isMobile={true} />
       </ThemeProvider>,
     )
 
@@ -82,7 +92,11 @@ describe('ResponsiveDrawer', () => {
   test('hides content when collapsed is true in desktop mode', () => {
     render(
       <ThemeProvider theme={theme}>
-        <ResponsiveDrawer ref={anchor} {...defaultProps} collapsed={true} />
+        <ResponsiveDrawer
+          anchorEl={anchor}
+          {...defaultProps}
+          collapsed={true}
+        />
       </ThemeProvider>,
     )
 
@@ -94,7 +108,7 @@ describe('ResponsiveDrawer', () => {
   test('closes drawer when clicking outside in mobile mode', () => {
     const { container } = render(
       <ThemeProvider theme={theme}>
-        <ResponsiveDrawer ref={anchor} {...defaultProps} isMobile={true} />
+        <ResponsiveDrawer anchorEl={anchor} {...defaultProps} isMobile={true} />
       </ThemeProvider>,
     )
 
@@ -119,7 +133,7 @@ describe('ResponsiveDrawer', () => {
         render(
           <ThemeProvider theme={theme}>
             <ResponsiveDrawer
-              ref={anchor}
+              anchorEl={anchor}
               {...defaultProps}
               position={position}
             />
@@ -132,7 +146,7 @@ describe('ResponsiveDrawer', () => {
   test('modal (default): renders an (invisible) backdrop', () => {
     render(
       <ThemeProvider theme={theme}>
-        <ResponsiveDrawer ref={anchor} {...defaultProps} />
+        <ResponsiveDrawer anchorEl={anchor} {...defaultProps} />
       </ThemeProvider>,
     )
     // The popover portals to document.body, so query the whole document.
@@ -145,7 +159,7 @@ describe('ResponsiveDrawer', () => {
       render(
         <ThemeProvider theme={theme}>
           <ResponsiveDrawer
-            ref={anchor}
+            anchorEl={anchor}
             {...defaultProps}
             slotProps={slotProps}
           />
@@ -157,7 +171,7 @@ describe('ResponsiveDrawer', () => {
   test('defaults to portaling into document.body when container is omitted', () => {
     render(
       <ThemeProvider theme={theme}>
-        <ResponsiveDrawer ref={anchor} {...defaultProps} />
+        <ResponsiveDrawer anchorEl={anchor} {...defaultProps} />
       </ThemeProvider>,
     )
     const content = screen.getByTestId('drawer-content')
@@ -172,7 +186,7 @@ describe('ResponsiveDrawer', () => {
       render(
         <ThemeProvider theme={theme}>
           <ResponsiveDrawer
-            ref={anchor}
+            anchorEl={anchor}
             {...defaultProps}
             container={customContainer}
           />
@@ -197,7 +211,7 @@ describe('ResponsiveDrawer', () => {
       render(
         <ThemeProvider theme={theme}>
           <ResponsiveDrawer
-            ref={anchor}
+            anchorEl={anchor}
             {...defaultProps}
             container={customContainer}
           />
@@ -225,7 +239,7 @@ describe('ResponsiveDrawer', () => {
   test('leaves paper maxHeight unset when no container is given', () => {
     render(
       <ThemeProvider theme={theme}>
-        <ResponsiveDrawer ref={anchor} {...defaultProps} />
+        <ResponsiveDrawer anchorEl={anchor} {...defaultProps} />
       </ThemeProvider>,
     )
     const paper = document.querySelector<HTMLElement>('.MuiPopover-paper')!
@@ -247,7 +261,7 @@ describe('ResponsiveDrawer', () => {
       render(
         <ThemeProvider theme={theme}>
           <ResponsiveDrawer
-            ref={anchor}
+            anchorEl={anchor}
             {...defaultProps}
             container={customContainer}
           />
@@ -271,7 +285,7 @@ describe('ResponsiveDrawer', () => {
       render(
         <ThemeProvider theme={theme}>
           <ResponsiveDrawer
-            ref={anchor}
+            anchorEl={anchor}
             {...defaultProps}
             container={customContainer}
             slotProps={
@@ -297,7 +311,7 @@ describe('ResponsiveDrawer', () => {
       render(
         <ThemeProvider theme={theme}>
           <ResponsiveDrawer
-            ref={anchor}
+            anchorEl={anchor}
             {...defaultProps}
             sx={{ zIndex: 9999 }}
           />
@@ -311,7 +325,7 @@ describe('ResponsiveDrawer', () => {
   test('non-modal: renders no backdrop', () => {
     render(
       <ThemeProvider theme={theme}>
-        <ResponsiveDrawer ref={anchor} {...defaultProps} modal={false} />
+        <ResponsiveDrawer anchorEl={anchor} {...defaultProps} modal={false} />
       </ThemeProvider>,
     )
     expect(document.querySelector('.MuiBackdrop-root')).toBeNull()
@@ -322,7 +336,7 @@ describe('ResponsiveDrawer', () => {
   test('non-modal: Escape does not close the panel', () => {
     render(
       <ThemeProvider theme={theme}>
-        <ResponsiveDrawer ref={anchor} {...defaultProps} modal={false} />
+        <ResponsiveDrawer anchorEl={anchor} {...defaultProps} modal={false} />
       </ThemeProvider>,
     )
     // Fire on a node inside the Modal root so it reaches the Modal's key handler.
@@ -336,7 +350,7 @@ describe('ResponsiveDrawer', () => {
   test('modal (default): Escape closes the panel', () => {
     render(
       <ThemeProvider theme={theme}>
-        <ResponsiveDrawer ref={anchor} {...defaultProps} />
+        <ResponsiveDrawer anchorEl={anchor} {...defaultProps} />
       </ThemeProvider>,
     )
     fireEvent.keyDown(screen.getByTestId('drawer-content'), {

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

@@ -14,10 +14,7 @@ import {
 } from 'react'
 
 type ResponsiveDrawerPosition =
-  | 'top-left'
-  | 'top-right'
-  | 'bottom-left'
-  | 'bottom-right'
+  'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
 
 /** Placement of the panel relative to its anchor (desktop popover only). */
 export type ResponsiveDrawerPlacement = 'side' | 'overlay'
@@ -59,6 +56,7 @@ export function ResponsiveDrawer<
     slotProps?: PopoverProps['slotProps']
   },
 >({
+  anchorEl,
   ref,
   children,
   collapsed,
@@ -72,8 +70,15 @@ export function ResponsiveDrawer<
   placement = 'side',
 }: Required<Pick<T, 'collapsed' | 'onChangeCollapsed' | 'position'>> &
   Pick<PopoverProps, 'slotProps' | 'sx' | 'container'> & {
-    ref: HTMLElement | null
-    isMobile: boolean
+    /** Element the desktop popover is anchored to. */
+    anchorEl?: HTMLElement | null
+    /**
+     * @deprecated Use `anchorEl`. A JSX prop named `ref` is non-reactive under
+     * the React Compiler, so a state-held anchor stays frozen at its initial
+     * `null` and the popover never opens. Removed in the next major.
+     */
+    ref?: HTMLElement | null
+    isMobile?: boolean
     children: ReactNode
     /**
      * When `false`, the desktop popover is **non-modal**: no backdrop, clicks
@@ -91,6 +96,8 @@ export function ResponsiveDrawer<
     placement?: ResponsiveDrawerPlacement
   }) {
   // Popover position is frozen on open — re-measure on content resize (callback ref: portal mounts after open).
+  const anchor = anchorEl ?? ref ?? null
+
   const popoverActions = useRef<PopoverActions>(null)
   const observerRef = useRef<ResizeObserver | null>(null)
   const observeContent = useCallback((el: HTMLDivElement | null) => {
@@ -191,8 +198,8 @@ export function ResponsiveDrawer<
       action={popoverActions}
       sx={sx}
       container={container}
-      anchorEl={ref}
-      open={!collapsed && ref != null}
+      anchorEl={anchor}
+      open={!collapsed && anchor != null}
       onClose={modal ? () => onChangeCollapsed(true) : undefined}
       hideBackdrop={!modal}
       disableScrollLock={!modal}

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

@@ -177,6 +177,25 @@ describe('<LegendRow> composition', () => {
     // …and the note renders exactly once, after all variables.
     expect(screen.getAllByText('One note for the whole layer.')).toHaveLength(1)
   })
+
+  // These render with no ThemeProvider, i.e. MUI's default theme, whose
+  // defaultVariantMapping has no `caption` entry and falls back to a `span`.
+  // An inline box ignores the line-height, so the type must not depend on a
+  // theme-level variantMapping to come out as a block.
+  it('renders the note and the subtitle as blocks, not inline', () => {
+    renderRow('boxes', [
+      {
+        id: 'a',
+        name: 'A',
+        subtitle: 'Zoom 0-12',
+        helperText: 'A note.',
+        variables: [cat],
+      },
+    ])
+
+    expect(screen.getByText('A note.').tagName).toBe('P')
+    expect(screen.getByText('Zoom 0-12').tagName).toBe('P')
+  })
 })
 
 describe('<LegendRow> grouped (inside Legend.Group)', () => {

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

@@ -112,7 +112,11 @@ export function LegendRow({ layerId, children }: LegendRowProps) {
               )}
             </Box>
             {layer.subtitle && !effectivelyCollapsed && (
-              <Typography variant='caption' color='text.secondary'>
+              <Typography
+                variant='caption'
+                color='text.secondary'
+                component='p'
+              >
                 {layer.subtitle}
               </Typography>
             )}
@@ -136,7 +140,16 @@ export function LegendRow({ layerId, children }: LegendRowProps) {
           {layer.helperText && (
             <Box sx={[styles.footer, inGroup && styles.footerGrouped]}>
               {typeof layer.helperText === 'string' ? (
-                <Typography variant='caption' color='text.secondary'>
+                // `component` is load-bearing: MUI's defaultVariantMapping has
+                // no entry for `caption`, so it falls back to a `span` and the
+                // line-height stops governing the box. Meridian maps it to `p`
+                // by theme, which makes the box type depend on the consumer's
+                // theme rather than on this component.
+                <Typography
+                  variant='caption'
+                  color='text.secondary'
+                  component='p'
+                >
                   {layer.helperText}
                 </Typography>
               ) : (

package/src/widgets/utils/chart-config/option-builders.ts

@@ -79,7 +79,11 @@ export function buildGridConfig(hasLegend: boolean, theme: Theme) {
  * @param theme - MUI theme providing the typography token and palette
  * @returns `{ fontSize, fontFamily, color }` for an ECharts `axisLabel`
  */
-export function buildAxisLabelStyle(theme: Theme) {
+export function buildAxisLabelStyle(theme: Theme): {
+  fontSize: string | number | undefined
+  fontFamily: string | undefined
+  color: string
+} {
   return {
     fontSize: theme.typography.overlineDelicate?.fontSize,
     fontFamily: theme.typography.overlineDelicate?.fontFamily,

package/src/widgets-v2/actions/fullscreen/fullscreen.test.tsx

@@ -104,6 +104,68 @@ describe('<FullScreen.Slot> — render-prop body + portal', () => {
     expect(closes.length).toBeGreaterThan(0)
   })
 
+  it('renders `actions` in the modal header, next to the close button', async () => {
+    render(
+      <Provider id='fs-actions' data={[]}>
+        <FullScreen.Trigger labels={{ open: 'OpenT', close: 'CloseT' }} />
+        <FullScreen.Slot
+          title='With actions'
+          actions={<button type='button'>Download</button>}
+        >
+          {() => <div>body</div>}
+        </FullScreen.Slot>
+      </Provider>,
+    )
+    fireEvent.click(screen.getByLabelText('OpenT'))
+    const action = await screen.findByText('Download')
+    // Same header row as the close button — the wrapper's action row is
+    // covered by the dialog, so the modal has to carry them itself.
+    const header = action.closest('.MuiDialogTitle-root')
+    expect(header).toBeTruthy()
+    expect(
+      header?.querySelector('[aria-label="Exit full screen"]'),
+    ).toBeTruthy()
+  })
+
+  it('keeps `actions` mounted across a fullscreen toggle', () => {
+    render(
+      <Provider id='fs-actions-keep' data={[]}>
+        <FullScreen.Trigger labels={{ open: 'OpenT', close: 'CloseT' }} />
+        <FullScreen.Slot
+          title='Y'
+          actions={<button type='button'>Download</button>}
+        >
+          {() => <div>body</div>}
+        </FullScreen.Slot>
+      </Provider>,
+    )
+    fireEvent.click(screen.getByLabelText('OpenT'))
+    const before = screen.getByText('Download')
+    fireEvent.click(screen.getByLabelText('CloseT'))
+    fireEvent.click(screen.getByLabelText('OpenT'))
+    expect(screen.getByText('Download')).toBe(before)
+  })
+
+  it('merges `paperSx` over the default dialog paper size', () => {
+    render(
+      <Provider id='fs-paper' data={[]}>
+        <FullScreen.Trigger />
+        <FullScreen.Slot title='P' paperSx={{ width: 560, height: 'auto' }}>
+          {() => <div>body</div>}
+        </FullScreen.Slot>
+      </Provider>,
+    )
+    fireEvent.click(screen.getByLabelText('Open in full screen'))
+    const paper = document.querySelector<HTMLElement>('.MuiDialog-paper')
+    expect(paper).toBeTruthy()
+    const css = getComputedStyle(paper!)
+    expect(css.width).toBe('560px')
+    expect(css.height).toBe('auto')
+    // Untouched keys still come from the default — `90vw`, resolved against
+    // the test viewport (1024px).
+    expect(css.maxWidth).toBe('921.6px')
+  })
+
   it('keeps the same DOM node across the fullscreen toggle (portal reparent)', () => {
     render(
       <Provider id='fs-reparent' data={[]}>