@carto/ps-react-ui 4.3.3 → 4.3.5

package/src/widgets/wrapper/components/options.tsx

@@ -0,0 +1,73 @@
+import { MoreVert } from '@mui/icons-material'
+import {
+  IconButton,
+  Menu,
+  MenuItem,
+  ListItemIcon,
+  ListItemText,
+} from '@mui/material'
+import type { WrapperOptionsProps } from '../types'
+import { useState } from 'react'
+import { styles } from '../styles'
+
+export function Options({ labels, options = [] }: WrapperOptionsProps) {
+  const [anchorEl, setAnchorEl] = useState<null | HTMLElement>(null)
+
+  const handleOptionAction = (
+    e: React.MouseEvent<HTMLElement>,
+    option: NonNullable<WrapperOptionsProps['options']>[number],
+  ) => {
+    e.stopPropagation()
+    option.onClick()
+    setAnchorEl(null)
+  }
+
+  return (
+    <>
+      <IconButton
+        sx={styles.options.trigger}
+        size='small'
+        aria-label={labels?.title ?? 'Options'}
+        aria-controls='options-menu'
+        aria-haspopup='true'
+        onClick={(e) => {
+          e.stopPropagation()
+          setAnchorEl(e.currentTarget)
+        }}
+      >
+        <MoreVert />
+      </IconButton>
+      <Menu
+        variant='menu'
+        elevation={8}
+        anchorOrigin={{
+          vertical: 'top',
+          horizontal: 'right',
+        }}
+        transformOrigin={{
+          vertical: 'top',
+          horizontal: 'right',
+        }}
+        anchorEl={anchorEl}
+        open={Boolean(anchorEl)}
+        onClose={() => setAnchorEl(null)}
+        MenuListProps={{
+          sx: {
+            paddingBottom: 0,
+          },
+        }}
+      >
+        {options.map((option, idx) => (
+          <MenuItem
+            key={`${option.label}-${idx}`}
+            disabled={option.disabled}
+            onClick={(e) => handleOptionAction(e, option)}
+          >
+            {option.icon && <ListItemIcon>{option.icon}</ListItemIcon>}
+            <ListItemText>{option.label}</ListItemText>
+          </MenuItem>
+        ))}
+      </Menu>
+    </>
+  )
+}

package/src/widgets/wrapper/components/title.test.tsx

@@ -0,0 +1,126 @@
+import { describe, test, expect } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import { Title } from './title'
+
+describe('Title', () => {
+  test('renders with string children', () => {
+    render(<Title>Test Title</Title>)
+    expect(screen.getByText('Test Title')).toBeTruthy()
+  })
+
+  test('renders with ReactNode children', () => {
+    render(
+      <Title>
+        <span>Complex</span> <strong>Title</strong>
+      </Title>,
+    )
+    expect(screen.getByText('Complex')).toBeTruthy()
+    expect(screen.getByText('Title')).toBeTruthy()
+  })
+
+  test('renders with custom label', () => {
+    render(<Title label='Custom Label'>Display Text</Title>)
+    // The component should render the children
+    expect(screen.getByText('Display Text')).toBeTruthy()
+  })
+
+  test('uses children as tooltip when children is string and no label', () => {
+    render(<Title>String Title</Title>)
+    expect(screen.getByText('String Title')).toBeTruthy()
+  })
+
+  test('uses empty string tooltip when children is not string and no label', () => {
+    render(
+      <Title>
+        <div>Complex Title</div>
+      </Title>,
+    )
+    expect(screen.getByText('Complex Title')).toBeTruthy()
+  })
+
+  test('applies correct typography variant', () => {
+    render(<Title>Test Title</Title>)
+    const typography = screen.getByText('Test Title')
+    expect(typography.tagName).toBe('H6') // subtitle1 renders as h6
+  })
+
+  test('wraps content in SmartTooltip', () => {
+    render(<Title>Tooltip Title</Title>)
+    expect(screen.getByText('Tooltip Title')).toBeTruthy()
+  })
+
+  test('handles empty string children', () => {
+    render(<Title>{''}</Title>)
+    // Should render but be empty
+    const { container } = render(<Title>{''}</Title>)
+    expect(container).toBeTruthy()
+  })
+
+  test('handles numeric children', () => {
+    render(<Title>{123}</Title>)
+    expect(screen.getByText('123')).toBeTruthy()
+  })
+
+  test('renders with multiple children', () => {
+    render(
+      <Title>
+        <span>Part 1</span>
+        <span>Part 2</span>
+        <span>Part 3</span>
+      </Title>,
+    )
+    expect(screen.getByText('Part 1')).toBeTruthy()
+    expect(screen.getByText('Part 2')).toBeTruthy()
+    expect(screen.getByText('Part 3')).toBeTruthy()
+  })
+
+  test('prefers label over string children for tooltip', () => {
+    render(<Title label='Tooltip Text'>Display Text</Title>)
+    expect(screen.getByText('Display Text')).toBeTruthy()
+  })
+
+  test('renders with undefined label and string children', () => {
+    render(<Title label={undefined}>String Children</Title>)
+    expect(screen.getByText('String Children')).toBeTruthy()
+  })
+
+  test('handles complex nested structure', () => {
+    render(
+      <Title>
+        <div>
+          <span>Nested</span>
+          <div>Content</div>
+        </div>
+      </Title>,
+    )
+    expect(screen.getByText('Nested')).toBeTruthy()
+    expect(screen.getByText('Content')).toBeTruthy()
+  })
+
+  test('ref is passed to Typography component', () => {
+    const { container } = render(<Title>Title with Ref</Title>)
+    expect(screen.getByText('Title with Ref')).toBeTruthy()
+    // The Typography component should be in the DOM
+    const typography = container.querySelector('[class*="MuiTypography"]')
+    expect(typography).toBeTruthy()
+  })
+
+  test('renders with textTransform none', () => {
+    render(<Title>Title Text</Title>)
+    expect(screen.getByText('Title Text')).toBeTruthy()
+  })
+
+  test('handles boolean children', () => {
+    render(<Title>{true}</Title>)
+    // Boolean children don't render text
+    const { container } = render(<Title>{false}</Title>)
+    expect(container).toBeTruthy()
+  })
+
+  test('handles null children', () => {
+    render(<Title>{null}</Title>)
+    // Null children don't render
+    const { container } = render(<Title>{null}</Title>)
+    expect(container).toBeTruthy()
+  })
+})

package/src/widgets/wrapper/components/title.tsx

@@ -0,0 +1,32 @@
+import { Box, Typography } from '@mui/material'
+import { styles } from '../styles'
+import { SmartTooltip } from '../../../components'
+import type { ReactNode } from 'react'
+import type { WrapperOptionsProps } from '../types'
+
+export function Title({
+  label,
+  children,
+}: {
+  children: ReactNode
+  label?: NonNullable<WrapperOptionsProps['labels']>['title']
+}) {
+  return (
+    <SmartTooltip
+      title={label ?? (typeof children === 'string' ? children : '')}
+    >
+      {({ ref }) => (
+        <Box sx={styles.title.container}>
+          <Typography
+            sx={styles.title.text}
+            ref={ref}
+            variant='subtitle1'
+            textTransform='none'
+          >
+            {children}
+          </Typography>
+        </Box>
+      )}
+    </SmartTooltip>
+  )
+}

package/src/widgets/wrapper/index.ts

@@ -0,0 +1,16 @@
+// Subcomponents for advanced stories
+export { Actions } from './components/actions'
+export { Options } from './components/options'
+export { Title } from './components/title'
+
+export { WidgetWrapper } from './wrapper'
+export { WrapperUI } from './wrapper-ui'
+
+export type {
+  WrapperActionsProps,
+  WrapperOption,
+  WrapperOptionsProps,
+  WrapperProps,
+  WrapperState,
+  WrapperUIProps,
+} from './types'

package/src/widgets/wrapper/styles.ts

@@ -0,0 +1,98 @@
+import type { SxProps, Theme } from '@mui/material'
+
+export const styles = {
+  root: {
+    '.Mui-disabled .MuiAccordionSummary-expandIconWrapper': {
+      display: 'none',
+    },
+    '.widget-wrapper-actions > *': {
+      opacity: 1,
+      transition: ({ transitions }) =>
+        transitions.create('opacity', {
+          duration: transitions.duration.standard,
+          easing: transitions.easing.easeInOut,
+        }),
+
+      '@media (hover: hover)': {
+        opacity: 0,
+      },
+
+      '&:has(.active)': {
+        opacity: 1,
+      },
+    },
+    '&:hover': {
+      '& .widget-wrapper-actions > *': {
+        opacity: 1,
+      },
+    },
+
+    '&.collapsed .widget-wrapper-actions > *': {
+      opacity: 0,
+      pointerEvents: 'none',
+
+      '&:has(.active)': {
+        opacity: 1,
+      },
+    },
+  },
+  summary: {
+    minHeight: ({ spacing }) => spacing(7),
+    '& .MuiAccordionSummary-content': {
+      gap: ({ spacing }) => spacing(0.5),
+      paddingInlineEnd: ({ spacing }) => spacing(0.75),
+    },
+  },
+  loading: {
+    height: ({ spacing }) => spacing(0.35),
+    left: 0,
+    position: 'absolute',
+    top: 0,
+    width: '100%',
+    zIndex: 1,
+  },
+  title: {
+    wrapper: {
+      flexGrow: 1,
+      flexShrink: 1,
+      minWidth: 0,
+      display: 'flex',
+      justifyContent: 'center',
+      flexDirection: 'column',
+    },
+    container: {
+      display: 'flex',
+      alignItems: 'center',
+      flexGrow: 1,
+      minHeight: ({ spacing }) => spacing(3),
+    },
+    text: {
+      wordBreak: 'break-word',
+      overflow: 'hidden',
+      display: '-webkit-box',
+      WebkitLineClamp: 2,
+      WebkitBoxOrient: 'vertical',
+    },
+  },
+  actions: {
+    display: 'flex',
+    gap: ({ spacing }) => spacing(0.5),
+    alignItems: 'center',
+    flexShrink: 0,
+    justifyContent: 'flex-end',
+    '& > div': {
+      pointerEvents: 'auto',
+    },
+  },
+  options: {
+    trigger: {
+      pointerEvents: 'auto',
+    },
+  },
+  detail: {
+    display: 'flex',
+    flexDirection: 'column',
+    gap: ({ spacing }) => spacing(1),
+    paddingTop: ({ spacing }) => spacing(0.5),
+  },
+} satisfies Record<string, SxProps<Theme>>

package/src/widgets/wrapper/types.ts

@@ -0,0 +1,55 @@
+import type { ReactNode, SyntheticEvent } from 'react'
+import type { SxProps, Theme } from '@mui/material'
+import type { BaseWidgetState } from '../stores/types'
+
+export interface WrapperProps
+  extends Pick<
+      WrapperUIProps,
+      'sx' | 'actions' | 'options' | 'labels' | 'children' | 'onChangeCollapsed'
+    >,
+    Pick<WrapperState, 'disabled' | 'title'> {
+  id: WrapperState['id']
+  defaultCollapsed?: boolean
+}
+
+export type WrapperState<T = unknown> = BaseWidgetState<
+  T & {
+    title: string
+    disabled?: boolean
+    collapsed?: boolean
+    isLoading?: boolean
+  }
+>
+
+export interface WrapperUIProps
+  extends WrapperActionsProps,
+    Omit<WrapperOptionsProps, 'labels' | ''> {
+  id: WrapperState['id']
+  children: ReactNode
+  sx?: SxProps<Theme>
+  labels?: {
+    options?: WrapperOptionsProps['labels']
+  }
+  onChangeCollapsed?: (
+    event: SyntheticEvent<Element, Event>,
+    collapsed: boolean,
+  ) => void
+}
+
+export interface WrapperActionsProps {
+  actions?: ReactNode[]
+}
+
+export interface WrapperOptionsProps {
+  labels?: {
+    title: string
+  }
+  options?: WrapperOption[]
+}
+
+export interface WrapperOption {
+  label: string
+  disabled?: boolean
+  icon?: ReactNode
+  onClick: () => void
+}

package/src/widgets/wrapper/wrapper-ui.test.tsx

@@ -0,0 +1,232 @@
+import { describe, test, expect, vi, beforeEach } from 'vitest'
+import { render, screen, fireEvent } from '@testing-library/react'
+import { WrapperUI } from './wrapper-ui'
+import { useWidgetStore } from '../stores/widget-store'
+import type { WrapperState } from './types'
+
+describe('WrapperUI', () => {
+  const widgetId = 'test-wrapper-ui'
+
+  const defaultProps = {
+    id: widgetId,
+    children: <div>Test Content</div>,
+  }
+
+  beforeEach(() => {
+    useWidgetStore.getState().clearWidgets()
+    // Pre-set the widget in the store with default values
+    useWidgetStore.getState().setWidget<WrapperState>(widgetId, {
+      title: 'Wrapper Widget',
+      collapsed: false,
+      disabled: false,
+      isFetching: false,
+    })
+  })
+
+  test('renders correctly with default props', () => {
+    render(<WrapperUI {...defaultProps} />)
+    expect(screen.getByText('Test Content')).toBeTruthy()
+    expect(screen.getByText('Wrapper Widget')).toBeTruthy()
+  })
+
+  test('renders with custom title from store', () => {
+    useWidgetStore.getState().setWidget<WrapperState>(widgetId, {
+      title: 'Custom Title',
+    })
+    render(<WrapperUI {...defaultProps} />)
+    expect(screen.getByText('Custom Title')).toBeTruthy()
+  })
+
+  test('renders in expanded state by default', () => {
+    useWidgetStore.getState().setWidget<WrapperState>(widgetId, {
+      collapsed: false,
+    })
+    render(<WrapperUI {...defaultProps} />)
+    const accordion = screen.getByRole('region')
+    expect(accordion).toBeTruthy()
+  })
+
+  test('renders in collapsed state', () => {
+    useWidgetStore.getState().setWidget<WrapperState>(widgetId, {
+      collapsed: true,
+    })
+    render(<WrapperUI {...defaultProps} />)
+    // When collapsed, AccordionDetails is not visible
+    const accordion = screen.getByRole('button')
+    expect(accordion).toBeTruthy()
+  })
+
+  test('renders loading indicator when isFetching is true', () => {
+    useWidgetStore.getState().setWidget<WrapperState>(widgetId, {
+      isFetching: true,
+    })
+    render(<WrapperUI {...defaultProps} />)
+    const progressBar = screen.getByRole('progressbar')
+    expect(progressBar).toBeTruthy()
+  })
+
+  test('does not render loading indicator when isFetching is false', () => {
+    useWidgetStore.getState().setWidget<WrapperState>(widgetId, {
+      isFetching: false,
+    })
+    render(<WrapperUI {...defaultProps} />)
+    const progressBar = screen.queryByRole('progressbar')
+    expect(progressBar).toBeNull()
+  })
+
+  test('renders actions when provided and not collapsed', () => {
+    const actions = [
+      <button key='action1'>Action 1</button>,
+      <button key='action2'>Action 2</button>,
+    ]
+    useWidgetStore.getState().setWidget<WrapperState>(widgetId, {
+      collapsed: false,
+    })
+    render(<WrapperUI {...defaultProps} actions={actions} />)
+    expect(screen.getByText('Action 1')).toBeTruthy()
+    expect(screen.getByText('Action 2')).toBeTruthy()
+  })
+
+  test('renders actions even when collapsed', () => {
+    const actions = [<button key='action1'>Action 1</button>]
+    useWidgetStore.getState().setWidget<WrapperState>(widgetId, {
+      collapsed: true,
+    })
+    render(<WrapperUI {...defaultProps} actions={actions} />)
+    // Actions are rendered in the AccordionSummary which is always visible
+    expect(screen.getByText('Action 1')).toBeTruthy()
+  })
+
+  test('does not render actions when array is empty', () => {
+    render(<WrapperUI {...defaultProps} actions={[]} />)
+    // No actions should be rendered
+    expect(screen.getByText('Test Content')).toBeTruthy()
+  })
+
+  test('renders options when provided', () => {
+    const options = [
+      {
+        label: 'Option 1',
+        onClick: vi.fn(),
+      },
+    ]
+    render(<WrapperUI {...defaultProps} options={options} />)
+    const optionsButton = screen.getByLabelText('Options')
+    expect(optionsButton).toBeTruthy()
+  })
+
+  test('renders options with custom label', () => {
+    const options = [
+      {
+        label: 'Option 1',
+        onClick: vi.fn(),
+      },
+    ]
+    const labels = {
+      options: {
+        title: 'Custom Options Label',
+      },
+    }
+    render(<WrapperUI {...defaultProps} options={options} labels={labels} />)
+    const optionsButton = screen.getByLabelText('Custom Options Label')
+    expect(optionsButton).toBeTruthy()
+  })
+
+  test('does not render options when array is empty', () => {
+    render(<WrapperUI {...defaultProps} options={[]} />)
+    const optionsButton = screen.queryByLabelText('Options')
+    expect(optionsButton).toBeNull()
+  })
+
+  test('handles onChangeCollapsed callback', () => {
+    const onChangeCollapsed = vi.fn()
+    render(
+      <WrapperUI {...defaultProps} onChangeCollapsed={onChangeCollapsed} />,
+    )
+
+    const accordion = screen.getByRole('button')
+    fireEvent.click(accordion)
+
+    expect(onChangeCollapsed).toHaveBeenCalledTimes(1)
+  })
+
+  test('renders disabled state', () => {
+    useWidgetStore.getState().setWidget<WrapperState>(widgetId, {
+      disabled: true,
+    })
+    render(<WrapperUI {...defaultProps} />)
+    const accordion = screen.getByRole('button')
+    expect(accordion.classList.contains('Mui-disabled')).toBe(true)
+  })
+
+  test('applies custom sx styles', () => {
+    const sx = { backgroundColor: 'red' }
+    render(<WrapperUI {...defaultProps} sx={sx} />)
+    // Component should render (we can't easily test sx application without jest-dom)
+    expect(screen.getByText('Test Content')).toBeTruthy()
+  })
+
+  test('renders children correctly', () => {
+    render(
+      <WrapperUI {...defaultProps}>
+        <div>Child 1</div>
+        <div>Child 2</div>
+      </WrapperUI>,
+    )
+    expect(screen.getByText('Child 1')).toBeTruthy()
+    expect(screen.getByText('Child 2')).toBeTruthy()
+  })
+
+  test('renders with all props combined', () => {
+    const actions = [<button key='action1'>Action 1</button>]
+    const options = [
+      {
+        label: 'Option 1',
+        onClick: vi.fn(),
+      },
+    ]
+    const labels = {
+      options: {
+        title: 'Custom Options',
+      },
+    }
+    const onChangeCollapsed = vi.fn()
+
+    useWidgetStore.getState().setWidget<WrapperState>(widgetId, {
+      title: 'Full Test',
+      collapsed: false,
+      disabled: false,
+      isFetching: true,
+    })
+
+    render(
+      <WrapperUI
+        {...defaultProps}
+        actions={actions}
+        options={options}
+        labels={labels}
+        sx={{ margin: 2 }}
+        onChangeCollapsed={onChangeCollapsed}
+      />,
+    )
+
+    expect(screen.getByText('Full Test')).toBeTruthy()
+    expect(screen.getByText('Action 1')).toBeTruthy()
+    expect(screen.getByLabelText('Custom Options')).toBeTruthy()
+    expect(screen.getByRole('progressbar')).toBeTruthy()
+    expect(screen.getByText('Test Content')).toBeTruthy()
+  })
+
+  test('handles collapse toggle multiple times', () => {
+    const onChangeCollapsed = vi.fn()
+    render(
+      <WrapperUI {...defaultProps} onChangeCollapsed={onChangeCollapsed} />,
+    )
+
+    const accordion = screen.getByRole('button')
+    fireEvent.click(accordion)
+    fireEvent.click(accordion)
+
+    expect(onChangeCollapsed).toHaveBeenCalledTimes(2)
+  })
+})

package/src/widgets/wrapper/wrapper-ui.tsx

@@ -0,0 +1,57 @@
+import {
+  Accordion,
+  AccordionDetails,
+  AccordionSummary,
+  LinearProgress,
+} from '@mui/material'
+import { styles } from './styles'
+import { Title } from './components/title'
+import type { WrapperState, WrapperUIProps } from './types'
+import { Options } from './components/options'
+import { Actions } from './components/actions'
+import { useWidgetStore } from '../stores/widget-store'
+import { useShallow } from 'zustand/shallow'
+
+export function WrapperUI({
+  children,
+  id,
+  actions = [],
+  sx,
+  labels,
+  options = [],
+  onChangeCollapsed,
+}: WrapperUIProps) {
+  const widget = useWidgetStore(
+    useShallow((state) => {
+      const widget = state.getWidget<WrapperState>(id)
+      return {
+        title: widget?.title,
+        collapsed: widget?.collapsed,
+        disabled: widget?.disabled,
+        isFetching: widget?.isFetching,
+      }
+    }),
+  )
+
+  return (
+    <Accordion
+      className={widget?.collapsed ? 'collapsed' : ''}
+      sx={{ ...styles.root, ...sx }}
+      expanded={!widget?.collapsed}
+      onChange={onChangeCollapsed}
+      disabled={widget?.disabled}
+    >
+      <AccordionSummary sx={styles.summary}>
+        {widget?.isFetching && (
+          <LinearProgress sx={styles.loading} color='primary' />
+        )}
+        <Title>{widget?.title}</Title>
+        {!!actions.length && <Actions actions={actions} />}
+        {!!options.length && (
+          <Options labels={labels?.options} options={options} />
+        )}
+      </AccordionSummary>
+      <AccordionDetails sx={styles.detail}>{children}</AccordionDetails>
+    </Accordion>
+  )
+}