@carto/ps-react-ui 5.0.0-widgets.9 → 5.1.0

package/src/widgets-v2/utils/resolve-theme-color.test.ts

@@ -0,0 +1,43 @@
+import { describe, it, expect } from 'vitest'
+import { createTheme } from '@mui/material'
+import { resolveThemeColor } from './resolve-theme-color'
+
+describe('resolveThemeColor', () => {
+  const theme = createTheme({
+    palette: {
+      primary: { main: '#1976d2', dark: '#0d47a1' },
+      secondary: { main: '#9c27b0' },
+    },
+  })
+
+  it('returns undefined when the input is undefined', () => {
+    expect(resolveThemeColor(theme, undefined)).toBeUndefined()
+  })
+
+  it('passes raw CSS colors through unchanged', () => {
+    expect(resolveThemeColor(theme, '#ff0000')).toBe('#ff0000')
+    expect(resolveThemeColor(theme, 'rgb(255, 0, 0)')).toBe('rgb(255, 0, 0)')
+    expect(resolveThemeColor(theme, 'red')).toBe('red')
+  })
+
+  it('resolves dotted MUI theme palette paths', () => {
+    expect(resolveThemeColor(theme, 'primary.main')).toBe('#1976d2')
+    expect(resolveThemeColor(theme, 'primary.dark')).toBe('#0d47a1')
+    expect(resolveThemeColor(theme, 'secondary.main')).toBe('#9c27b0')
+  })
+
+  it('returns the raw input when the theme path does not resolve', () => {
+    // Non-existent palette path → caller's responsibility to recover; we
+    // pass the string through so ECharts can at least attempt to parse it.
+    expect(resolveThemeColor(theme, 'primary.does-not-exist')).toBe(
+      'primary.does-not-exist',
+    )
+    expect(resolveThemeColor(theme, 'nope.anywhere')).toBe('nope.anywhere')
+  })
+
+  it('handles a path that traverses but yields a non-string', () => {
+    // `primary` itself is an object, not a string — we return the raw
+    // input rather than `[object Object]`.
+    expect(resolveThemeColor(theme, 'primary')).toBe('primary')
+  })
+})

package/src/widgets-v2/utils/resolve-theme-color.ts

@@ -0,0 +1,34 @@
+import type { Theme } from '@mui/material'
+
+/**
+ * Resolve a colour string against the MUI theme palette.
+ *
+ * - `'primary.main'`, `'secondary.dark'`, `'success.contrastText'`, … →
+ *   walks `theme.palette` along the dot-separated path and returns the
+ *   resolved string when traversal succeeds.
+ * - `'#ff0000'`, `'rgb(255, 0, 0)'`, `'red'` → returned as-is (assumed
+ *   raw CSS; ECharts consumes them directly).
+ * - `undefined` → `undefined` (callers fall back to ECharts' palette).
+ *
+ * Used by the echart option factories (Bar, Pie, Histogram, Scatterplot,
+ * Timeseries) so per-series colours specified as theme paths in the
+ * unified `WidgetSeries` shape paint correctly. Category, Formula, and
+ * Spread render colours through MUI's `sx` resolver, which already
+ * handles theme paths — they don't need this helper.
+ */
+export function resolveThemeColor(
+  theme: Theme,
+  raw: string | undefined,
+): string | undefined {
+  if (raw == null) return undefined
+  if (!raw.includes('.')) return raw
+  const parts = raw.split('.')
+  let cursor: unknown = theme.palette
+  for (const part of parts) {
+    if (cursor == null || typeof cursor !== 'object') {
+      return raw
+    }
+    cursor = (cursor as Record<string, unknown>)[part]
+  }
+  return typeof cursor === 'string' ? cursor : raw
+}

package/src/widgets-v2/wrapper/index.ts

@@ -0,0 +1,14 @@
+export { Wrapper, type WrapperProps } from './widget-wrapper'
+export {
+  Actions,
+  Options,
+  type ActionsProps,
+  type OptionsProps,
+} from './widget-actions'
+export {
+  Content,
+  Footer,
+  type ContentProps,
+  type FooterProps,
+} from './widget-content'
+export { DEFAULT_WRAPPER_LABELS, type WrapperLabels } from './labels'

package/src/widgets-v2/wrapper/labels.ts

@@ -0,0 +1,11 @@
+export interface WrapperLabels {
+  collapse: string
+  expand: string
+  errorFallbackTitle: string
+}
+
+export const DEFAULT_WRAPPER_LABELS: WrapperLabels = {
+  collapse: 'Collapse',
+  expand: 'Expand',
+  errorFallbackTitle: 'Widget failed to render',
+}

package/src/widgets-v2/wrapper/style.ts

@@ -0,0 +1,128 @@
+import type { SxProps, Theme } from '@mui/material'
+
+export const styles = {
+  root: {
+    position: 'relative',
+    width: '100%',
+    minWidth: 0,
+    bgcolor: 'background.paper',
+    borderRadius: 1,
+    overflow: 'hidden',
+    boxShadow: 'none',
+    // MUI Accordion ships its own collapsed-state divider rules; clear them
+    // so they don't fight our card border.
+    '&::before': { display: 'none' },
+
+    // Hover-fade actions (v1 parity). Direct children of
+    // `.widget-wrapper-actions` are dimmed by default on fine-pointer devices
+    // and fade in on hover; an action carrying the `.active` class stays
+    // full-opacity even outside hover. Coarse-pointer devices show actions
+    // always.
+    //
+    // The class must sit on the action element itself
+    // (`<IconButton className='active'>`). v2 does NOT wrap each action in
+    // an extra container the way v1 does, so the `> *` selector lands on the
+    // action button directly — `&:has(.active)` would only match if the
+    // class were on a descendant, which is never the case here.
+    '& .widget-wrapper-actions > *': {
+      opacity: 1,
+      transition: ({ transitions }: Theme) =>
+        transitions.create('opacity', {
+          duration: transitions.duration.standard,
+          easing: transitions.easing.easeInOut,
+        }),
+      '@media (hover: hover)': {
+        opacity: 0,
+      },
+      '&.active': {
+        opacity: 1,
+      },
+    },
+    '&:hover .widget-wrapper-actions > *': {
+      opacity: 1,
+    },
+    '&[data-collapsed="true"] .widget-wrapper-actions > *': {
+      opacity: 0,
+      pointerEvents: 'none',
+      '&.active': {
+        opacity: 1,
+      },
+    },
+  },
+  loading: {
+    position: 'absolute',
+    top: 0,
+    left: 0,
+    width: '100%',
+    height: ({ spacing }: Theme) => spacing(0.35),
+    zIndex: 1,
+  },
+  summary: {
+    minHeight: ({ spacing }: Theme) => spacing(7),
+    '& .MuiAccordionSummary-content': {
+      gap: ({ spacing }: Theme) => spacing(0.5),
+      paddingInlineEnd: ({ spacing }: Theme) => spacing(0.75),
+      alignItems: 'center',
+    },
+  },
+  // Disabled state — only the collapse toggle is inert (enforced by the
+  // guarded `onChange` handler, not `pointer-events`). Actions and Options in
+  // the summary row, and the details panel, all keep their events. We just
+  // drop the toggle affordance: hide the chevron (handled in the component)
+  // and clear the pointer cursor. MUI's AccordionSummary sets
+  // `cursor: pointer` via `&:hover:not(.Mui-disabled)` — a two-class selector
+  // that outranks a plain `cursor` rule — so we override at matching
+  // specificity. Action/Option buttons restore their own pointer cursor.
+  summaryDisabled: {
+    '&, &:hover:not(.Mui-disabled)': {
+      cursor: 'default',
+    },
+  },
+  titleCell: {
+    flexGrow: 1,
+    flexShrink: 1,
+    minWidth: 0,
+    display: 'flex',
+    alignItems: 'center',
+    minHeight: ({ spacing }: Theme) => spacing(3),
+  },
+  titleText: {
+    minWidth: 0,
+    wordBreak: 'break-word',
+    overflow: 'hidden',
+    display: '-webkit-box',
+    WebkitLineClamp: 2,
+    WebkitBoxOrient: 'vertical',
+  },
+  actions: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: 0.5,
+    justifyContent: 'flex-end',
+    flexShrink: 0,
+    '& > *': {
+      pointerEvents: 'auto',
+    },
+  },
+  options: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: 0.5,
+    flexShrink: 0,
+  },
+  detail: {
+    display: 'flex',
+    flexDirection: 'column',
+    gap: ({ spacing }: Theme) => spacing(1),
+    paddingTop: ({ spacing }: Theme) => spacing(0.5),
+  },
+  content: {
+    minWidth: 0,
+    display: 'flex',
+    flexDirection: 'column',
+    gap: 1,
+  },
+  footer: {
+    pt: 1,
+  },
+} satisfies Record<string, SxProps<Theme>>

package/src/widgets-v2/wrapper/widget-actions.test.tsx

@@ -0,0 +1,52 @@
+import { describe, it, expect, vi } from 'vitest'
+import { fireEvent, render } from '@testing-library/react'
+import { Actions, Options } from './widget-actions'
+
+describe('<Actions>', () => {
+  it('renders children and applies the widget-wrapper-actions class', () => {
+    const { container, getByText } = render(
+      <Actions>
+        <button>act</button>
+      </Actions>,
+    )
+    expect(getByText('act')).toBeTruthy()
+    expect(container.querySelector('.widget-wrapper-actions')).not.toBeNull()
+  })
+
+  it('stops click propagation', () => {
+    const onWrapperClick = vi.fn()
+    const { getByText } = render(
+      <button type='button' onClick={onWrapperClick}>
+        <Actions>
+          <span>btn</span>
+        </Actions>
+      </button>,
+    )
+    fireEvent.click(getByText('btn'))
+    expect(onWrapperClick).not.toHaveBeenCalled()
+  })
+})
+
+describe('<Options>', () => {
+  it('renders children', () => {
+    const { getByText } = render(
+      <Options>
+        <span>opt</span>
+      </Options>,
+    )
+    expect(getByText('opt')).toBeTruthy()
+  })
+
+  it('stops click propagation', () => {
+    const onWrapperClick = vi.fn()
+    const { getByText } = render(
+      <button type='button' onClick={onWrapperClick}>
+        <Options>
+          <span>opt</span>
+        </Options>
+      </button>,
+    )
+    fireEvent.click(getByText('opt'))
+    expect(onWrapperClick).not.toHaveBeenCalled()
+  })
+})

package/src/widgets-v2/wrapper/widget-actions.tsx

@@ -0,0 +1,43 @@
+import { Box, type SxProps, type Theme } from '@mui/material'
+import type { ReactNode } from 'react'
+import { styles } from './style'
+
+export interface ActionsProps {
+  sx?: SxProps<Theme>
+  children: ReactNode
+}
+
+/**
+ * Slot for the wrapper header's right-side action buttons. The
+ * `widget-wrapper-actions` className activates the hover-fade CSS rule on
+ * `<Wrapper>`: action children fade in on hover (always visible on coarse-
+ * pointer devices), and stay full-opacity when a descendant is marked with
+ * `.active` — typically applied by toggled actions.
+ *
+ * The container also stops click propagation so interacting with an action
+ * doesn't toggle the wrapper's collapse.
+ */
+export function Actions({ sx, children }: ActionsProps) {
+  return (
+    <Box
+      className='widget-wrapper-actions'
+      onClick={(e) => e.stopPropagation()}
+      sx={{ ...styles.actions, ...sx }}
+    >
+      {children}
+    </Box>
+  )
+}
+
+export interface OptionsProps {
+  sx?: SxProps<Theme>
+  children: ReactNode
+}
+
+export function Options({ sx, children }: OptionsProps) {
+  return (
+    <Box onClick={(e) => e.stopPropagation()} sx={{ ...styles.options, ...sx }}>
+      {children}
+    </Box>
+  )
+}

package/src/widgets-v2/wrapper/widget-content.test.tsx

@@ -0,0 +1,27 @@
+import { describe, it, expect } from 'vitest'
+import { render } from '@testing-library/react'
+import { Content, Footer } from './widget-content'
+
+describe('<Content>', () => {
+  it('renders children inside a data-slot=content box', () => {
+    const { getByText, container } = render(
+      <Content>
+        <span>body</span>
+      </Content>,
+    )
+    expect(getByText('body')).toBeTruthy()
+    expect(container.querySelector('[data-slot="content"]')).not.toBeNull()
+  })
+})
+
+describe('<Footer>', () => {
+  it('renders children inside a data-slot=footer box', () => {
+    const { getByText, container } = render(
+      <Footer>
+        <span>foot</span>
+      </Footer>,
+    )
+    expect(getByText('foot')).toBeTruthy()
+    expect(container.querySelector('[data-slot="footer"]')).not.toBeNull()
+  })
+})

package/src/widgets-v2/wrapper/widget-content.tsx

@@ -0,0 +1,29 @@
+import { Box, type SxProps, type Theme } from '@mui/material'
+import type { ReactNode } from 'react'
+import { styles } from './style'
+
+export interface ContentProps {
+  sx?: SxProps<Theme>
+  children: ReactNode
+}
+
+export function Content({ sx, children }: ContentProps) {
+  return (
+    <Box data-slot='content' sx={{ ...styles.content, ...sx }}>
+      {children}
+    </Box>
+  )
+}
+
+export interface FooterProps {
+  sx?: SxProps<Theme>
+  children: ReactNode
+}
+
+export function Footer({ sx, children }: FooterProps) {
+  return (
+    <Box data-slot='footer' sx={{ ...styles.footer, ...sx }}>
+      {children}
+    </Box>
+  )
+}

package/src/widgets-v2/wrapper/widget-wrapper.test.tsx

@@ -0,0 +1,255 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { fireEvent, render, screen } from '@testing-library/react'
+import { Provider } from '../provider/widget-provider'
+import { clearAllWidgetStores } from '../stores'
+import { Wrapper } from './widget-wrapper'
+import { Actions } from './widget-actions'
+import { Content } from './widget-content'
+
+beforeEach(() => clearAllWidgetStores())
+afterEach(() => clearAllWidgetStores())
+
+function withProvider(id: string, ui: React.ReactNode, isFetching = false) {
+  return (
+    <Provider id={id} data={[]} isFetching={isFetching}>
+      {ui}
+    </Provider>
+  )
+}
+
+describe('<Wrapper>', () => {
+  it('renders the title', () => {
+    render(
+      withProvider(
+        'wrap-1',
+        <Wrapper title='Sales'>
+          <Content>body</Content>
+        </Wrapper>,
+      ),
+    )
+    expect(screen.getByText('Sales')).toBeTruthy()
+  })
+
+  it('renders Content children when expanded', () => {
+    render(
+      withProvider(
+        'wrap-2',
+        <Wrapper title='t'>
+          <Content>
+            <div data-testid='body'>body</div>
+          </Content>
+        </Wrapper>,
+      ),
+    )
+    expect(screen.getByTestId('body')).toBeTruthy()
+  })
+
+  it('keeps Content mounted but visually hidden when collapsed', () => {
+    // Accordion uses MUI <Collapse>, which animates the parent via height/visibility.
+    // Children stay mounted (the Collapse keeps `keepMounted` semantics by default).
+    render(
+      withProvider(
+        'wrap-3',
+        <Wrapper title='t' defaultCollapsed>
+          <Content>
+            <div data-testid='body'>body</div>
+          </Content>
+        </Wrapper>,
+      ),
+    )
+    expect(screen.getByTestId('body')).toBeTruthy()
+    // Find the AccordionDetails ancestor and confirm aria-hidden / inert reflects collapsed.
+    const root = screen.getByText('t').closest('.MuiAccordion-root')
+    expect(root?.getAttribute('data-collapsed')).toBe('true')
+  })
+
+  it('toggles via the chevron icon button — header summary owns the click', () => {
+    render(
+      withProvider(
+        'wrap-4',
+        <Wrapper title='t'>
+          <Content>body</Content>
+        </Wrapper>,
+      ),
+    )
+    const summary = screen.getByRole('button', { name: 'Collapse' })
+    expect(summary.getAttribute('aria-expanded')).toBe('true')
+    fireEvent.click(summary)
+    expect(
+      screen
+        .getByRole('button', { name: 'Expand' })
+        .getAttribute('aria-expanded'),
+    ).toBe('false')
+  })
+
+  it('honors custom collapse/expand labels on the summary', () => {
+    render(
+      withProvider(
+        'wrap-5',
+        <Wrapper title='t' labels={{ collapse: 'Hide', expand: 'Show' }}>
+          <Content>body</Content>
+        </Wrapper>,
+      ),
+    )
+    expect(screen.getByRole('button', { name: 'Hide' })).toBeTruthy()
+    fireEvent.click(screen.getByRole('button', { name: 'Hide' }))
+    expect(screen.getByRole('button', { name: 'Show' })).toBeTruthy()
+  })
+
+  it('renders <Actions> children inside the summary row, not the details panel', () => {
+    render(
+      withProvider(
+        'wrap-6',
+        <Wrapper title='t'>
+          <Actions>
+            <button data-testid='action-btn'>A</button>
+          </Actions>
+          <Content>
+            <div data-testid='body-content'>body</div>
+          </Content>
+        </Wrapper>,
+      ),
+    )
+    const actionBtn = screen.getByTestId('action-btn')
+    const bodyContent = screen.getByTestId('body-content')
+    // The action lives inside the AccordionSummary, the body inside AccordionDetails.
+    expect(actionBtn.closest('.MuiAccordionSummary-root')).not.toBeNull()
+    expect(bodyContent.closest('.MuiAccordionDetails-root')).not.toBeNull()
+  })
+
+  it('shows a LinearProgress at the top when the store reports isFetching', () => {
+    render(
+      withProvider(
+        'wrap-7',
+        <Wrapper title='t'>
+          <Content>body</Content>
+        </Wrapper>,
+        true,
+      ),
+    )
+    expect(screen.getByRole('progressbar')).toBeTruthy()
+  })
+
+  it('hides the LinearProgress when isFetching is false', () => {
+    render(
+      withProvider(
+        'wrap-8',
+        <Wrapper title='t'>
+          <Content>body</Content>
+        </Wrapper>,
+        false,
+      ),
+    )
+    expect(screen.queryByRole('progressbar')).toBeNull()
+  })
+
+  it('renders by default (elevation variant) with body intact', () => {
+    render(
+      withProvider(
+        'wrap-variant-default',
+        <Wrapper title='t'>
+          <Content>
+            <div data-testid='body'>body</div>
+          </Content>
+        </Wrapper>,
+      ),
+    )
+    expect(screen.getByText('t')).toBeTruthy()
+    expect(screen.getByTestId('body')).toBeTruthy()
+  })
+
+  it('renders the outlined variant with body intact', () => {
+    render(
+      withProvider(
+        'wrap-variant-outlined',
+        <Wrapper title='t' variant='outlined'>
+          <Content>
+            <div data-testid='body'>body</div>
+          </Content>
+        </Wrapper>,
+      ),
+    )
+    expect(screen.getByText('t')).toBeTruthy()
+    expect(screen.getByTestId('body')).toBeTruthy()
+  })
+
+  it('applies disabled styling without removing children', () => {
+    render(
+      withProvider(
+        'wrap-9',
+        <Wrapper title='t' disabled>
+          <Content>
+            <div data-testid='body'>body</div>
+          </Content>
+        </Wrapper>,
+      ),
+    )
+    expect(screen.getByTestId('body')).toBeTruthy()
+  })
+
+  it('disables only the summary, leaving the details panel interactive', () => {
+    let clicks = 0
+    render(
+      withProvider(
+        'wrap-10',
+        <Wrapper title='t' disabled>
+          <Content>
+            <button data-testid='body-btn' onClick={() => (clicks += 1)}>
+              click
+            </button>
+          </Content>
+        </Wrapper>,
+      ),
+    )
+    // The details panel keeps its events even while the wrapper is disabled.
+    fireEvent.click(screen.getByTestId('body-btn'))
+    expect(clicks).toBe(1)
+  })
+
+  it('does not toggle when the disabled summary is clicked', () => {
+    let lastCollapsed: boolean | undefined
+    render(
+      withProvider(
+        'wrap-11',
+        <Wrapper
+          title='t'
+          disabled
+          onCollapseChange={(c) => (lastCollapsed = c)}
+        >
+          <Content>body</Content>
+        </Wrapper>,
+      ),
+    )
+    fireEvent.click(screen.getByText('t'))
+    expect(lastCollapsed).toBeUndefined()
+  })
+
+  it('keeps summary actions clickable while the wrapper is disabled', () => {
+    let actionClicks = 0
+    let lastCollapsed: boolean | undefined
+    render(
+      withProvider(
+        'wrap-12',
+        <Wrapper
+          title='t'
+          disabled
+          onCollapseChange={(c) => (lastCollapsed = c)}
+        >
+          <Actions>
+            <button
+              data-testid='action-btn'
+              onClick={() => (actionClicks += 1)}
+            >
+              A
+            </button>
+          </Actions>
+          <Content>body</Content>
+        </Wrapper>,
+      ),
+    )
+    fireEvent.click(screen.getByTestId('action-btn'))
+    // The action fires, and clicking it must not toggle the disabled wrapper.
+    expect(actionClicks).toBe(1)
+    expect(lastCollapsed).toBeUndefined()
+  })
+})