@carto/ps-react-ui 4.3.3 → 4.3.5

package/src/widgets/actions/shared/styles.ts

@@ -0,0 +1,12 @@
+import type { SxProps, Theme } from '@mui/material'
+
+/**
+ * Shared styles for widget action buttons
+ */
+export const actionButtonStyles = {
+  trigger: {
+    '&[data-active="true"]': {
+      background: (theme: Theme) => theme.palette.primary.relatedLight,
+    },
+  },
+} satisfies Record<string, SxProps<Theme>>

package/src/widgets/actions/stack-toggle/grouped-bar-chart-icon.tsx

@@ -0,0 +1,14 @@
+export const GroupedBarChartIcon = () => (
+  <svg
+    width='24'
+    height='24'
+    viewBox='0 0 24 24'
+    fill='none'
+    xmlns='http://www.w3.org/2000/svg'
+  >
+    <path
+      d='M4 20V8H8V20H4ZM9 20V13H13V20H9ZM16 20V4H20V20H16Z'
+      fill='currentColor'
+    />
+  </svg>
+)

package/src/widgets/actions/stack-toggle/stack-toggle.test.tsx

@@ -0,0 +1,270 @@
+import { describe, test, expect, beforeEach } from 'vitest'
+import { render, screen, fireEvent, waitFor } from '@testing-library/react'
+import { StackToggle } from './stack-toggle'
+import { useWidgetStore } from '../../stores/widget-store'
+import { DEFAULT_STACK_GROUP } from '../../echart/const'
+
+describe('StackToggle', () => {
+  const widgetId = 'test-stack-widget'
+
+  // Helper to set up widget with multiple series (required for component to render)
+  function setupMultiSeriesWidget(overrides = {}) {
+    useWidgetStore.getState().setWidget(widgetId, {
+      option: {
+        series: [
+          { name: 'Series 1', type: 'bar' },
+          { name: 'Series 2', type: 'bar' },
+        ],
+      },
+      ...overrides,
+    })
+  }
+
+  beforeEach(() => {
+    useWidgetStore.getState().clearWidgets()
+    setupMultiSeriesWidget()
+  })
+
+  test('renders stack toggle button', () => {
+    render(<StackToggle id={widgetId} />)
+
+    const button = screen.getByRole('button')
+    expect(button).toBeTruthy()
+  })
+
+  test('shows stacked tooltip when in unstacked mode', () => {
+    render(<StackToggle id={widgetId} />)
+
+    const button = screen.getByRole('button', { name: 'Enable stacking' })
+    expect(button).toBeTruthy()
+  })
+
+  test('toggles to stacked mode and updates widget store', () => {
+    render(<StackToggle id={widgetId} />)
+
+    const button = screen.getByRole('button')
+    fireEvent.click(button)
+
+    const widget = useWidgetStore.getState().getWidget(widgetId)
+    expect((widget as { isStacked?: boolean })?.isStacked).toBe(true)
+  })
+
+  test('toggles back to unstacked mode', () => {
+    render(<StackToggle id={widgetId} />)
+
+    const button = screen.getByRole('button')
+
+    // Toggle to stacked
+    fireEvent.click(button)
+
+    // Toggle back to unstacked
+    fireEvent.click(button)
+
+    const widget = useWidgetStore.getState().getWidget(widgetId)
+    expect((widget as { isStacked?: boolean })?.isStacked).toBe(false)
+  })
+
+  test('has active state when in stacked mode', () => {
+    render(<StackToggle id={widgetId} />)
+
+    const button = screen.getByRole('button')
+
+    expect(button.getAttribute('data-active')).toBe('false')
+
+    fireEvent.click(button)
+
+    expect(button.getAttribute('data-active')).toBe('true')
+  })
+
+  test('starts in stacked mode when defaultIsStacked is true', () => {
+    render(<StackToggle id={widgetId} defaultIsStacked />)
+
+    const button = screen.getByRole('button')
+    expect(button.getAttribute('data-active')).toBe('true')
+
+    // Should show unstacked tooltip when in stacked mode
+    expect(button.getAttribute('aria-label')).toBe('Disable stacking')
+  })
+
+  test('uses custom labels when provided', () => {
+    const customLabels = {
+      stacked: 'Stack bars',
+      unstacked: 'Unstack bars',
+      ariaLabel: 'Toggle bar stacking',
+    }
+
+    render(<StackToggle id={widgetId} labels={customLabels} />)
+
+    const button = screen.getByRole('button', { name: 'Toggle bar stacking' })
+    expect(button).toBeTruthy()
+  })
+
+  test('initializes store with default values on mount', () => {
+    render(<StackToggle id={widgetId} />)
+
+    const widget = useWidgetStore.getState().getWidget(widgetId)
+    expect((widget as { isStacked?: boolean })?.isStacked).toBe(false)
+  })
+
+  test('initializes store with stacked values when defaultIsStacked is true', () => {
+    render(<StackToggle id={widgetId} defaultIsStacked />)
+
+    const widget = useWidgetStore.getState().getWidget(widgetId)
+    expect((widget as { isStacked?: boolean })?.isStacked).toBe(true)
+  })
+
+  test('updates EChart series options when toggling to stacked', () => {
+    // setupMultiSeriesWidget already ran in beforeEach
+    render(<StackToggle id={widgetId} />)
+    const button = screen.getByRole('button')
+    fireEvent.click(button)
+
+    const widget = useWidgetStore.getState().getWidget(widgetId)
+    const series = (widget as { option?: { series?: { stack?: string }[] } })
+      ?.option?.series?.[0]
+    expect(series?.stack).toBe(DEFAULT_STACK_GROUP)
+  })
+
+  test('removes stack from EChart series when toggling to unstacked', () => {
+    useWidgetStore.getState().setWidget(widgetId, {
+      option: {
+        series: [
+          { name: 'Series 1', type: 'bar', stack: DEFAULT_STACK_GROUP },
+          { name: 'Series 2', type: 'bar', stack: DEFAULT_STACK_GROUP },
+        ],
+      },
+    })
+
+    render(<StackToggle id={widgetId} />)
+    const button = screen.getByRole('button')
+
+    // First click unstacks (since series has stack, it starts stacked)
+    fireEvent.click(button)
+
+    const widget = useWidgetStore.getState().getWidget(widgetId)
+    const series = (widget as { option?: { series?: { stack?: string }[] } })
+      ?.option?.series?.[0]
+    expect(series?.stack).toBeUndefined()
+  })
+
+  test('updates multiple series when toggling stack', () => {
+    useWidgetStore.getState().setWidget(widgetId, {
+      option: {
+        series: [
+          { name: 'Series 1', type: 'bar' },
+          { name: 'Series 2', type: 'bar' },
+          { name: 'Series 3', type: 'bar' },
+        ],
+      },
+    })
+
+    render(<StackToggle id={widgetId} />)
+    const button = screen.getByRole('button')
+    fireEvent.click(button)
+
+    const widget = useWidgetStore.getState().getWidget(widgetId)
+    const seriesArray = (
+      widget as { option?: { series?: { stack?: string }[] } }
+    )?.option?.series
+
+    expect(seriesArray).toHaveLength(3)
+    seriesArray?.forEach((s) => {
+      expect(s.stack).toBe(DEFAULT_STACK_GROUP)
+    })
+  })
+
+  test('uses default stack group when re-stacking after unstacking', () => {
+    const customStackGroup = 'custom-group'
+    useWidgetStore.getState().setWidget(widgetId, {
+      option: {
+        series: [
+          { name: 'Series 1', type: 'bar', stack: customStackGroup },
+          { name: 'Series 2', type: 'bar', stack: customStackGroup },
+        ],
+      },
+    })
+
+    render(<StackToggle id={widgetId} />)
+    const button = screen.getByRole('button')
+
+    // Toggle off then on - re-stacking uses default stack group
+    fireEvent.click(button) // unstacked
+    fireEvent.click(button) // stacked again
+
+    void waitFor(() => {
+      const widget = useWidgetStore.getState().getWidget(widgetId)
+      const series = (widget as { option?: { series?: { stack?: string }[] } })
+        ?.option?.series?.[0]
+      expect(series?.stack).toBe(customStackGroup)
+    })
+  })
+
+  test('detects existing stack in series and defaults to stacked mode', () => {
+    useWidgetStore.getState().setWidget(widgetId, {
+      option: {
+        series: [
+          { name: 'Series 1', type: 'bar', stack: 'existing-stack' },
+          { name: 'Series 2', type: 'bar', stack: 'existing-stack' },
+        ],
+      },
+    })
+
+    render(<StackToggle id={widgetId} />)
+
+    const button = screen.getByRole('button')
+    expect(button.getAttribute('data-active')).toBe('true')
+    expect(button.getAttribute('aria-label')).toBe('Disable stacking')
+  })
+
+  test('returns null for single series (stacking not applicable)', () => {
+    useWidgetStore.getState().setWidget(widgetId, {
+      option: {
+        series: { name: 'Single Series', type: 'bar' },
+      },
+    })
+
+    const { container } = render(<StackToggle id={widgetId} />)
+    // Component returns null when there's only one series
+    expect(container.firstChild).toBeNull()
+  })
+
+  test('returns null when widget has no option defined', () => {
+    // Clear the widget set up in beforeEach and create one without option
+    useWidgetStore.getState().clearWidgets()
+    useWidgetStore.getState().setWidget(widgetId, {})
+
+    const { container } = render(<StackToggle id={widgetId} />)
+    // Component returns null when there's no series data
+    expect(container.firstChild).toBeNull()
+  })
+
+  test('preserves other option properties when updating series', () => {
+    useWidgetStore.getState().setWidget(widgetId, {
+      option: {
+        title: { text: 'My Chart' },
+        xAxis: { type: 'category' },
+        series: [
+          { name: 'Series 1', type: 'bar' },
+          { name: 'Series 2', type: 'bar' },
+        ],
+      },
+    })
+
+    render(<StackToggle id={widgetId} />)
+    const button = screen.getByRole('button')
+    fireEvent.click(button)
+
+    const widget = useWidgetStore.getState().getWidget(widgetId)
+    const option = (
+      widget as {
+        option?: {
+          title?: { text?: string }
+          xAxis?: { type?: string }
+        }
+      }
+    )?.option
+
+    expect(option?.title?.text).toBe('My Chart')
+    expect(option?.xAxis?.type).toBe('category')
+  })
+})

package/src/widgets/actions/stack-toggle/stack-toggle.tsx

@@ -0,0 +1,146 @@
+import { IconButton } from '@mui/material'
+import { useCallback, useEffect, useMemo } from 'react'
+import { useWidgetStore } from '../../stores/widget-store'
+import type { StackToggleProps, StackToggleState } from './types'
+import { actionButtonStyles } from '../shared/styles'
+import { Tooltip } from '../../../components'
+import { GroupedBarChartIcon } from './grouped-bar-chart-icon'
+import { getEChartStackConfig } from '../../echart/utils'
+import { DEFAULT_STACK_GROUP } from '../../echart/const'
+import type { EchartWidgetState } from '../../echart/types'
+import { useShallow } from 'zustand/shallow'
+
+/**
+ * Widget action to toggle stacking behavior in ECharts bar and histogram widgets.
+ *
+ * Stores the stack state in the widget store and updates the ECharts option
+ * using getEChartStackConfig to apply stacking to all series.
+ *
+ * @example
+ * ```tsx
+ * <StackToggle
+ *   id="my-widget"
+ *   defaultIsStacked={false}
+ * />
+ * ```
+ */
+export function StackToggle({
+  id,
+  defaultIsStacked = false,
+  labels,
+  Icon,
+  IconButtonProps,
+}: StackToggleProps) {
+  const setWidget = useWidgetStore((state) => state.setWidget)
+  const storeIsStacked = useWidgetStore(
+    useShallow((state) => state.getWidget<StackToggleState>(id)?.isStacked),
+  )
+
+  const getWidget = useWidgetStore((state) => state.getWidget)
+
+  /**
+   * Checks if there are multiple series in the chart
+   */
+  const hasMultiSeries = useMemo(() => {
+    const option = getWidget<EchartWidgetState>(id)?.option
+    if (!option) return false
+
+    const series = Array.isArray(option.series)
+      ? option.series
+      : [option.series]
+
+    return series.length > 1
+  }, [getWidget, id])
+
+  /**
+   * Checks if any series in the option has a stack property defined
+   */
+  const hasStackInSeries = useMemo(() => {
+    const option = getWidget<EchartWidgetState>(id)?.option
+    if (!option) return false
+
+    const series = Array.isArray(option.series)
+      ? option.series
+      : [option.series]
+
+    return series.some((s) => (s as { stack?: string })?.stack)
+  }, [getWidget, id])
+
+  // If series already has stack defined, default to stacked=true
+  const effectiveDefaultIsStacked = hasStackInSeries || defaultIsStacked
+  const isStacked = storeIsStacked ?? effectiveDefaultIsStacked
+
+  /**
+   * Updates the ECharts option with the stack configuration
+   * Preserves existing stack group names from series, falling back to DEFAULT_STACK_GROUP
+   */
+  const updateOptions = useCallback(
+    (stacked: boolean) => {
+      const option = getWidget<EchartWidgetState>(id)?.option
+
+      if (!option) return
+
+      const series = Array.isArray(option.series)
+        ? option.series
+        : [option.series]
+
+      const updatedSeries = series.map((s) => {
+        // Extract existing stack group from series, fallback to default
+        const existingStack = (s as { stack?: string })?.stack
+        const stackGroup =
+          typeof existingStack === 'string'
+            ? existingStack
+            : DEFAULT_STACK_GROUP
+
+        return {
+          ...s,
+          ...getEChartStackConfig(stacked, stackGroup),
+        }
+      })
+
+      setWidget(id, {
+        option: {
+          ...option,
+          series: updatedSeries,
+        },
+      })
+    },
+    [getWidget, id, setWidget],
+  )
+
+  // Initialize store with default value only if not already configured
+  useEffect(() => {
+    setWidget(id, { isStacked: effectiveDefaultIsStacked })
+  }, [effectiveDefaultIsStacked, id, setWidget])
+
+  const handleToggle = useCallback(() => {
+    const newIsStacked = !isStacked
+
+    setWidget(id, { isStacked: newIsStacked })
+    updateOptions(newIsStacked)
+  }, [isStacked, id, setWidget, updateOptions])
+
+  const tooltipLabel = isStacked
+    ? (labels?.unstacked ?? 'Disable stacking')
+    : (labels?.stacked ?? 'Enable stacking')
+
+  // Early return if there's only one series - stacking doesn't apply
+  if (!hasMultiSeries) {
+    return null
+  }
+
+  return (
+    <Tooltip title={tooltipLabel}>
+      <IconButton
+        size='small'
+        aria-label={labels?.ariaLabel ?? tooltipLabel}
+        onClick={handleToggle}
+        sx={actionButtonStyles.trigger}
+        data-active={isStacked}
+        {...IconButtonProps}
+      >
+        {Icon ?? <GroupedBarChartIcon />}
+      </IconButton>
+    </Tooltip>
+  )
+}

package/src/widgets/actions/stack-toggle/types.ts

@@ -0,0 +1,29 @@
+import type { IconButtonProps } from '@mui/material'
+import type { ReactNode } from 'react'
+import type { BaseWidgetState } from '../../stores/types'
+
+export interface StackToggleProps {
+  /** Widget ID to update stack configuration in the widget store */
+  id: string
+  /** Initial toggle state - when true, starts with stacking enabled */
+  defaultIsStacked?: boolean
+  /** Custom labels for the action */
+  labels?: {
+    /** Tooltip when stacking is disabled (button will enable stacking) */
+    stacked?: string
+    /** Tooltip when stacking is enabled (button will disable stacking) */
+    unstacked?: string
+    /** Accessibility label */
+    ariaLabel?: string
+  }
+  /** Props passed to the IconButton component */
+  IconButtonProps?: IconButtonProps
+  /** Custom icon to display */
+  Icon?: ReactNode
+}
+
+export type StackToggleState<T = unknown> = BaseWidgetState<
+  T & {
+    isStacked?: boolean
+  }
+>

package/src/widgets/actions/zoom-toggle/index.ts

@@ -0,0 +1,2 @@
+export { ZoomToggle } from './zoom-toggle'
+export type { ZoomToggleProps, ZoomState, ZoomConfig } from './types'

package/src/widgets/actions/zoom-toggle/style.ts

@@ -0,0 +1,14 @@
+import type { SxProps, Theme } from '@mui/material'
+
+export const styles = {
+  container: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: ({ spacing }) => spacing(0.25),
+  },
+  trigger: {
+    '&[data-active="true"]': {
+      background: (theme: Theme) => theme.palette.primary.relatedLight,
+    },
+  },
+} satisfies Record<string, SxProps<Theme>>

package/src/widgets/actions/zoom-toggle/types.ts

@@ -0,0 +1,44 @@
+import type { IconButtonProps } from '@mui/material'
+import type { ReactNode } from 'react'
+import type { BaseWidgetState } from '../../stores/types'
+
+/**
+ * State stored in widget store for zoom functionality
+ */
+export interface ZoomConfig {
+  zoom?: boolean
+  /** Start percentage for zoom range (0-100) */
+  zoomStart?: number
+  /** End percentage for zoom range (0-100) */
+  zoomEnd?: number
+}
+
+export type ZoomState<T = unknown> = BaseWidgetState<T & ZoomConfig>
+
+export interface ZoomToggleProps {
+  /** Widget ID to update zoom state in the widget store */
+  id: string
+  /** Initial zoom state - when true, zoom is enabled */
+  defaultZoom?: boolean
+  /** Initial start percentage for zoom range (0-100) */
+  defaultZoomStart?: number
+  /** Initial end percentage for zoom range (0-100) */
+  defaultZoomEnd?: number
+  /** Custom labels for the action */
+  labels?: {
+    /** Tooltip when zoom is disabled (button will enable zoom) */
+    enable?: string
+    /** Tooltip when zoom is enabled (button will disable zoom) */
+    disable?: string
+    /** Tooltip for reset button */
+    reset?: string
+    /** Accessibility label */
+    ariaLabel?: string
+  }
+  /** Props passed to the IconButton component */
+  IconButtonProps?: IconButtonProps
+  /** Custom icon to display for zoom toggle */
+  Icon?: ReactNode
+  /** Custom icon to display for reset button */
+  ResetIcon?: ReactNode
+}