@carto/ps-react-ui 5.0.0-widgets.8 → 5.0.0

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,414 @@
+import { describe, test, expect, beforeEach } from 'vitest'
+import { render, screen, fireEvent, waitFor } from '@testing-library/react'
+import { StackToggle, STACK_TOGGLE_TOOL_ID } 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 tool config', () => {
+    render(<StackToggle id={widgetId} />)
+
+    const button = screen.getByRole('button')
+    fireEvent.click(button)
+
+    const widget = useWidgetStore.getState().getWidget(widgetId)
+    const tool = widget?.registeredTools?.find(
+      (t) => t.id === STACK_TOGGLE_TOOL_ID,
+    )
+    expect(tool?.enabled).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)
+    const tool = widget?.registeredTools?.find(
+      (t) => t.id === STACK_TOGGLE_TOOL_ID,
+    )
+    expect(tool?.enabled).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 tool config with default values on mount', () => {
+    render(<StackToggle id={widgetId} />)
+
+    const widget = useWidgetStore.getState().getWidget(widgetId)
+    const tool = widget?.registeredTools?.find(
+      (t) => t.id === STACK_TOGGLE_TOOL_ID,
+    )
+    expect(tool?.enabled).toBe(false)
+  })
+
+  test('initializes tool config with stacked values when defaultIsStacked is true', () => {
+    render(<StackToggle id={widgetId} defaultIsStacked />)
+
+    const widget = useWidgetStore.getState().getWidget(widgetId)
+    const tool = widget?.registeredTools?.find(
+      (t) => t.id === STACK_TOGGLE_TOOL_ID,
+    )
+    expect(tool?.enabled).toBe(true)
+  })
+
+  test('applies stack to EChart series via config pipeline when toggling to stacked', async () => {
+    render(<StackToggle id={widgetId} />)
+    const button = screen.getByRole('button')
+    fireEvent.click(button)
+
+    // Run the config pipeline to apply the stack tool's transformation
+    await useWidgetStore.getState().executeConfigPipeline(widgetId, {
+      option: {
+        series: [
+          { name: 'Series 1', type: 'bar' },
+          { name: 'Series 2', type: 'bar' },
+        ],
+      },
+    })
+
+    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 via config pipeline when toggling to unstacked', async () => {
+    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)
+
+    // Run the config pipeline — tool is disabled when unstacked, so stack is removed
+    await useWidgetStore.getState().executeConfigPipeline(widgetId, {
+      option: {
+        series: [
+          { name: 'Series 1', type: 'bar' },
+          { name: 'Series 2', type: 'bar' },
+        ],
+      },
+    })
+
+    const widget = useWidgetStore.getState().getWidget(widgetId)
+    const series = (widget as { option?: { series?: { stack?: string }[] } })
+      ?.option?.series?.[0]
+    expect(series?.stack).toBeUndefined()
+  })
+
+  test('applies stack to multiple series via config pipeline', async () => {
+    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)
+
+    await useWidgetStore.getState().executeConfigPipeline(widgetId, {
+      option: {
+        series: [
+          { name: 'Series 1', type: 'bar' },
+          { name: 'Series 2', type: 'bar' },
+          { name: 'Series 3', type: 'bar' },
+        ],
+      },
+    })
+
+    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('preserves custom stack group via config pipeline', async () => {
+    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
+    fireEvent.click(button) // unstacked
+    fireEvent.click(button) // stacked again
+
+    await useWidgetStore.getState().executeConfigPipeline(widgetId, {
+      option: {
+        series: [
+          { name: 'Series 1', type: 'bar', stack: customStackGroup },
+          { name: 'Series 2', type: 'bar', stack: customStackGroup },
+        ],
+      },
+    })
+
+    await 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('config tool re-applies stack when config pipeline re-runs', async () => {
+    // Start with stacked widget
+    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} defaultIsStacked />)
+
+    // Simulate loader running config pipeline with base config (no stack)
+    await useWidgetStore.getState().executeConfigPipeline(widgetId, {
+      option: {
+        series: [
+          { name: 'Series 1', type: 'bar' },
+          { name: 'Series 2', type: 'bar' },
+        ],
+      },
+    })
+
+    // Stack should be re-applied by the config tool
+    await waitFor(() => {
+      const widget = useWidgetStore.getState().getWidget(widgetId)
+      const series = (widget as { option?: { series?: { stack?: string }[] } })
+        ?.option?.series
+      expect(series?.[0]?.stack).toBe(DEFAULT_STACK_GROUP)
+      expect(series?.[1]?.stack).toBe(DEFAULT_STACK_GROUP)
+    })
+  })
+
+  test('config tool does not apply stack when unstacked and pipeline re-runs', async () => {
+    // Start with unstacked widget
+    useWidgetStore.getState().setWidget(widgetId, {
+      option: {
+        series: [
+          { name: 'Series 1', type: 'bar' },
+          { name: 'Series 2', type: 'bar' },
+        ],
+      },
+    })
+
+    render(<StackToggle id={widgetId} />)
+
+    // Run config pipeline with base config
+    await useWidgetStore.getState().executeConfigPipeline(widgetId, {
+      option: {
+        series: [
+          { name: 'Series 1', type: 'bar' },
+          { name: 'Series 2', type: 'bar' },
+        ],
+      },
+    })
+
+    // Stack should NOT be applied since isStacked is false (tool disabled)
+    await waitFor(() => {
+      const widget = useWidgetStore.getState().getWidget(widgetId)
+      const series = (widget as { option?: { series?: { stack?: string }[] } })
+        ?.option?.series
+      expect(series?.[0]?.stack).toBeUndefined()
+      expect(series?.[1]?.stack).toBeUndefined()
+    })
+  })
+
+  test('preserves other option properties via config pipeline', async () => {
+    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)
+
+    await useWidgetStore.getState().executeConfigPipeline(widgetId, {
+      option: {
+        title: { text: 'My Chart' },
+        xAxis: { type: 'category' },
+        series: [
+          { name: 'Series 1', type: 'bar' },
+          { name: 'Series 2', type: 'bar' },
+        ],
+      },
+    })
+
+    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')
+  })
+
+  test('registers config tool on mount and unregisters on unmount', () => {
+    const { unmount } = render(<StackToggle id={widgetId} />)
+
+    const widget = useWidgetStore.getState().getWidget(widgetId)
+    const tools = widget?.registeredTools ?? []
+    const stackTool = tools.find((t) => t.id === STACK_TOGGLE_TOOL_ID)
+    expect(stackTool).toBeDefined()
+    expect(stackTool?.type).toBe('config')
+
+    unmount()
+
+    const widgetAfter = useWidgetStore.getState().getWidget(widgetId)
+    const toolsAfter = widgetAfter?.registeredTools ?? []
+    const stackToolAfter = toolsAfter.find((t) => t.id === STACK_TOGGLE_TOOL_ID)
+    expect(stackToolAfter).toBeUndefined()
+  })
+})

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

@@ -0,0 +1,129 @@
+import { IconButton } from '@mui/material'
+import { useCallback, useEffect, useMemo } from 'react'
+import { widgetStoreActions } 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 type { EchartOptionsProps } from '../../echart/types'
+import { useWidgetSelector } from '../../stores/use-widget-selector'
+
+export const STACK_TOGGLE_TOOL_ID = 'stack-toggle'
+
+/**
+ * Widget action to toggle stacking behavior in ECharts bar and histogram widgets.
+ *
+ * Registers as a config pipeline tool so that stack configuration is automatically
+ * re-applied when the base config is updated (e.g., by WidgetLoader).
+ *
+ * @example
+ * ```tsx
+ * <StackToggle
+ *   id="my-widget"
+ *   defaultIsStacked={false}
+ * />
+ * ```
+ */
+export function StackToggle({
+  id,
+  defaultIsStacked = false,
+  labels,
+  Icon,
+  IconButtonProps,
+}: StackToggleProps) {
+  const { storeIsStacked, option } = useWidgetSelector(id, (w) => ({
+    storeIsStacked: (w as StackToggleState | undefined)?.isStacked,
+    option: (w as EchartWidgetState | undefined)?.option,
+  }))
+
+  const { hasMultiSeries, hasStackInSeries } = useMemo(() => {
+    if (!option) return { hasMultiSeries: false, hasStackInSeries: false }
+    const series = Array.isArray(option.series)
+      ? option.series
+      : [option.series]
+    return {
+      hasMultiSeries: series.length > 1,
+      hasStackInSeries: series.some((s) => (s as { stack?: string })?.stack),
+    }
+  }, [option])
+
+  // If series already has stack defined, default to stacked=true
+  const effectiveDefaultIsStacked = hasStackInSeries || defaultIsStacked
+  const isStacked = storeIsStacked ?? effectiveDefaultIsStacked
+
+  // Register config tool once — fn has no closure deps
+  useEffect(() => {
+    widgetStoreActions.registerTool(id, {
+      id: STACK_TOGGLE_TOOL_ID,
+      type: 'config',
+      order: 10,
+      enabled: false,
+      fn: (currentConfig: unknown) => {
+        const config = currentConfig as Record<string, unknown>
+        const option = config.option as EchartOptionsProps | undefined
+        if (!option) return currentConfig
+
+        const series = Array.isArray(option.series)
+          ? option.series
+          : [option.series]
+        const updatedSeries = series.map((s) => {
+          const existingStack = (s as { stack?: string })?.stack
+          const stackGroup =
+            typeof existingStack === 'string'
+              ? existingStack
+              : DEFAULT_STACK_GROUP
+          return { ...s, ...getEChartStackConfig(stackGroup) }
+        })
+
+        return { ...config, option: { ...option, series: updatedSeries } }
+      },
+    })
+    return () => widgetStoreActions.unregisterTool(id, STACK_TOGGLE_TOOL_ID)
+  }, [id])
+
+  // Sync enabled from store — lightweight, no re-registration
+  useEffect(() => {
+    widgetStoreActions.setToolEnabled(
+      id,
+      STACK_TOGGLE_TOOL_ID,
+      isStacked && hasMultiSeries,
+    )
+  }, [id, isStacked, hasMultiSeries])
+
+  // Initialize store with default value only if not already configured
+  useEffect(() => {
+    if (storeIsStacked !== undefined) return
+    widgetStoreActions.setWidget(id, { isStacked: effectiveDefaultIsStacked })
+  }, [effectiveDefaultIsStacked, id, storeIsStacked])
+
+  const handleToggle = useCallback(() => {
+    widgetStoreActions.setWidget(id, { isStacked: !isStacked })
+  }, [isStacked, id])
+
+  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/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
+}