@carto/ps-react-ui 5.0.0 → 6.0.0

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

@@ -1,218 +1,106 @@
-import { Box, IconButton, useTheme } from '@mui/material'
+import { useCallback, useMemo, type ComponentType } from 'react'
+import { IconButton, useTheme, type SvgIconProps } from '@mui/material'
+import { ZoomIn as ZoomInIcon } from '@mui/icons-material'
+import { Tooltip } from '../../../components'
 import {
-  SubdirectoryArrowLeftOutlined,
-  ZoomInOutlined,
-} from '@mui/icons-material'
-import { useEffect, useCallback } from 'react'
-import { widgetStoreActions } from '../../stores/widget-store'
-import type { ZoomToggleProps, ZoomState } from './types'
+  getEchartInstance,
+  useSingleTransform,
+  useWidgetId,
+} from '../../stores'
+import { createAddZoom, type ZoomAxis } from './transforms'
+import { DEFAULT_ZOOM_TOGGLE_LABELS, type ZoomToggleLabels } from './labels'
 import { styles } from './style'
-import { Tooltip } from '../../../components'
-import { getEChartZoomConfig } from '../../echart/utils'
-import type { EchartOptionsProps } from '../../echart/types'
-import { useWidgetSelector } from '../../stores/use-widget-selector'
 
-export const ZOOM_TOGGLE_TOOL_ID = 'zoom-toggle'
+const ZOOM_DESCRIPTOR = {
+  id: 'zoom-toggle',
+  type: 'config' as const,
+  order: 20,
+}
+
+export interface ZoomToggleProps {
+  initialEnabled?: boolean
+  labels?: Partial<ZoomToggleLabels>
+  icon?: ComponentType<SvgIconProps>
+  iconProps?: SvgIconProps
+  /**
+   * Which axes the zoom controls. Default `['x']` — matches bar /
+   * histogram / timeseries (horizontal pan on the category axis). Pass
+   * `['x', 'y']` for 2D zoom on a scatterplot-style chart (mouse-wheel
+   * scales both axes; horizontal slider at bottom + vertical slider on
+   * the right).
+   */
+  axes?: readonly ZoomAxis[]
+}
 
 /**
- * Widget action to toggle EChart zoom functionality.
- *
- * Registers as a config pipeline tool so that zoom configuration is automatically
- * re-applied when the base config is updated (e.g., by WidgetLoader).
- *
- * Zoom state (enabled, range) is stored in the widget store root, and the tool
- * derives its `enabled` flag from the store. This keeps state accessible across
- * component instances.
+ * Toggle a `dataZoom` slider + wheel-zoom on the chart. The transform is
+ * theme-bound so the slider gets v1's CARTO chrome (blue-tinted filler,
+ * secondary-color preview, white pill handles).
  *
- * When zoom is active, displays an inline reset button to disable zoom.
- * Only intended for use in fullscreen ToolbarActions for bar and histogram widgets.
+ * `dataZoom` is intentionally NOT in `replaceMergeKeys` — ECharts merges
+ * subsequent `setOption` calls so the user's dragged range survives
+ * unrelated re-renders (data updates, formatter swaps, RelativeData toggles).
  *
- * @example
- * ```tsx
- * <ZoomToggle
- *   id="my-widget"
- *   defaultZoom={false}
- *   zoomStart={0}
- *   zoomEnd={100}
- * />
- * ```
+ * On disable the transform is unregistered, but ECharts' merge semantics
+ * would otherwise *keep* the live `dataZoom` component visible. To remove
+ * the slider immediately we issue a one-shot
+ * `setOption({}, { replaceMerge: ['dataZoom'] })` against the live chart
+ * instance via {@link getEchartInstance} — this bypasses the pipeline so
+ * unrelated transforms aren't disturbed.
  */
 export function ZoomToggle({
-  id,
-  defaultZoom = false,
-  defaultZoomStart = 0,
-  defaultZoomEnd = 100,
+  initialEnabled = false,
   labels,
-  Icon,
-  ResetIcon,
-  IconButtonProps,
+  icon: Icon = ZoomInIcon,
+  iconProps,
+  axes,
 }: ZoomToggleProps) {
+  const id = useWidgetId()
   const theme = useTheme()
-
-  // Read zoom state from widget store root — single source of truth
-  const { zoom, zoomStart, zoomEnd } = useWidgetSelector(id, (w) => ({
-    zoom: (w as ZoomState | undefined)?.zoom ?? defaultZoom,
-    zoomStart: (w as ZoomState | undefined)?.zoomStart ?? defaultZoomStart,
-    zoomEnd: (w as ZoomState | undefined)?.zoomEnd ?? defaultZoomEnd,
-  }))
-
-  // Initialize store with default values on mount
-  useEffect(() => {
-    const current = widgetStoreActions.getWidget<ZoomState>(id)
-    if (current?.zoom === undefined) {
-      widgetStoreActions.setWidget(id, {
-        zoom: defaultZoom,
-        zoomStart: defaultZoomStart,
-        zoomEnd: defaultZoomEnd,
-      })
-    }
-  }, [id, defaultZoom, defaultZoomStart, defaultZoomEnd])
-
-  // Handle dataZoom event — update store (source of truth)
-  const handleDataZoom = useCallback(
-    (event: unknown) => {
-      const zoomEvent = event as {
-        start?: number
-        end?: number
-        batch?: {
-          start?: number
-          end?: number
-        }[]
-      }
-
-      const start = zoomEvent.start ?? zoomEvent.batch?.[0]?.start
-      const end = zoomEvent.end ?? zoomEvent.batch?.[0]?.end
-
-      if (start !== undefined && end !== undefined) {
-        widgetStoreActions.setWidget(id, {
-          zoom: true,
-          zoomStart: start,
-          zoomEnd: end,
-        })
-      }
-    },
-    [id],
+  const _labels = { ...DEFAULT_ZOOM_TOGGLE_LABELS, ...labels }
+  // Reduce `axes` to two structural booleans before memoizing so the memo
+  // depends on stable primitive values, not an array reference (callers
+  // typically pass an inline `axes={['x', 'y']}` literal that changes
+  // identity each render). Default — no `axes` prop — is x-axis only,
+  // matching `createAddZoom`'s default.
+  const includeX = axes ? axes.includes('x') : true
+  const includeY = axes ? axes.includes('y') : false
+  const transform = useMemo(() => {
+    const resolved: ZoomAxis[] = []
+    if (includeX) resolved.push('x')
+    if (includeY) resolved.push('y')
+    return createAddZoom(theme, { axes: resolved })
+  }, [theme, includeX, includeY])
+  const { enabled, toggle } = useSingleTransform(
+    id,
+    ZOOM_DESCRIPTOR,
+    transform,
+    { initialEnabled },
   )
 
-  // Register config tool once — fn reads zoom range from the store at execution time.
-  useEffect(() => {
-    widgetStoreActions.registerTool(id, {
-      id: ZOOM_TOGGLE_TOOL_ID,
-      type: 'config',
-      order: 20,
-      enabled: defaultZoom,
-      fn: (currentConfig) => {
-        const config = currentConfig as Record<string, unknown>
-        const option = config.option as EchartOptionsProps | undefined
-        const currentOnEvents =
-          (config.onEvents as Record<string, unknown> | undefined) ?? {}
-
-        const widget = widgetStoreActions.getWidget<ZoomState>(id)
-        const start = widget?.zoomStart ?? 0
-        const end = widget?.zoomEnd ?? 100
-
-        const legend = option?.legend as { show?: boolean } | undefined
-        const hasLegend = legend?.show !== false && legend !== undefined
-
-        const sliderHeight = parseInt(theme?.spacing?.(4) ?? '32')
-        const sliderGap = 8
-        const legendBottomOffset = hasLegend ? 28 : 0
-
-        const zoomConfig = getEChartZoomConfig(
-          { start, end },
-          {
-            inside: true,
-            xSlider: true,
-            ySlider: false,
-            bottomOffset: legendBottomOffset,
-          },
-          theme,
-        )
-
-        const grid = option?.grid as { bottom?: number | string } | undefined
-        const currentGridBottom =
-          typeof grid?.bottom === 'number'
-            ? grid.bottom
-            : parseInt(grid?.bottom ?? '24')
-
-        const gridBottom = currentGridBottom + sliderHeight + sliderGap
-
-        const onEvents = { ...currentOnEvents, dataZoom: handleDataZoom }
-
-        return {
-          ...config,
-          option: {
-            ...option,
-            ...zoomConfig,
-            grid: { ...grid, bottom: gridBottom },
-          },
-          onEvents,
-        }
-      },
-    })
-    return () => widgetStoreActions.unregisterTool(id, ZOOM_TOGGLE_TOOL_ID)
-  }, [id, theme, handleDataZoom, defaultZoom, defaultZoomStart, defaultZoomEnd])
-
-  // Sync enabled from store — lightweight, no re-registration
-  useEffect(() => {
-    widgetStoreActions.setToolEnabled(id, ZOOM_TOGGLE_TOOL_ID, zoom)
-  }, [id, zoom])
-
-  // Trigger pipeline when zoom range changes — fn reads from store at execution time,
-  // but the pipeline only re-runs when registeredTools reference changes.
-  // setToolEnabled handles the zoom on/off case, this handles range-only changes.
-  useEffect(() => {
-    widgetStoreActions.triggerToolPipeline(id)
-  }, [id, zoomStart, zoomEnd])
-
-  const handleToggle = () => {
-    const newZoom = !zoom
-    widgetStoreActions.setWidget(id, {
-      zoom: newZoom,
-      zoomStart: newZoom ? zoomStart : 0,
-      zoomEnd: newZoom ? zoomEnd : 100,
-    })
-  }
-
-  const handleReset = () => {
-    widgetStoreActions.setWidget(id, {
-      zoom: true,
-      zoomStart: defaultZoomStart,
-      zoomEnd: defaultZoomEnd,
-    })
-  }
+  const handleToggle = useCallback(() => {
+    if (enabled) {
+      // About to disable — clear the dataZoom component on the live
+      // instance so the slider disappears immediately.
+      getEchartInstance(id)?.setOption({}, { replaceMerge: ['dataZoom'] })
+    }
+    toggle()
+  }, [enabled, toggle, id])
 
-  const enableLabel = labels?.enable ?? 'Enable zoom'
-  const disableLabel = labels?.disable ?? 'Disable zoom'
-  const resetLabel = labels?.reset ?? 'Reset zoom'
-  const tooltipLabel = zoom ? disableLabel : enableLabel
+  const tooltip = enabled ? _labels.on : _labels.off
 
   return (
-    <Box sx={styles.container}>
-      <Tooltip title={tooltipLabel}>
-        <IconButton
-          size='small'
-          aria-label={labels?.ariaLabel ?? tooltipLabel}
-          onClick={handleToggle}
-          sx={styles.trigger}
-          data-active={zoom}
-          {...IconButtonProps}
-        >
-          {Icon ?? <ZoomInOutlined />}
-        </IconButton>
-      </Tooltip>
-      {zoom && (
-        <Tooltip title={resetLabel}>
-          <IconButton
-            size='small'
-            aria-label={resetLabel}
-            onClick={handleReset}
-            {...IconButtonProps}
-          >
-            {ResetIcon ?? <SubdirectoryArrowLeftOutlined />}
-          </IconButton>
-        </Tooltip>
-      )}
-    </Box>
+    <Tooltip title={tooltip}>
+      <IconButton
+        size='small'
+        aria-label={tooltip}
+        aria-pressed={enabled}
+        onClick={handleToggle}
+        className={enabled ? 'active' : undefined}
+        sx={{ ...styles.toggle, ...(enabled && styles.toggleActive) }}
+      >
+        <Icon fontSize='small' {...iconProps} />
+      </IconButton>
+    </Tooltip>
   )
 }

package/src/widgets/bar/index.ts

@@ -1,9 +1,10 @@
-export { barConfig, barDownloadConfig } from './config'
+export { barOptions, createBarOptionFactory } from './options'
 export { BarSkeleton } from './skeleton'
-
+export { createBarDownloadConfig } from './download'
 export type {
+  BarDatum,
   BarWidgetData,
-  BarWidgetState,
-  BarConfig,
-  BarWidgetConfig,
+  BarOptionsInput,
+  BarOptionFactoryInput,
+  BarEChartsOption,
 } from './types'

package/src/{widgets-v2 → widgets}/bar/options.ts

@@ -8,7 +8,7 @@ import {
   createTooltipFormatter,
   createTooltipPositioner,
   niceNum,
-} from '../../widgets/utils/chart-config'
+} from '../utils/option-builders'
 import { ZOOM_LAYOUT } from '../actions/zoom-toggle'
 import type { OptionFactory } from '../echart'
 import { mergeOptions, resolveThemeColor } from '../utils'

package/src/widgets/bar/skeleton.tsx

@@ -1,59 +1,68 @@
-import { Box, Skeleton } from '@mui/material'
-import { styles } from './style'
+import { Box, Skeleton, type SxProps, type Theme } from '@mui/material'
 
+const styles = {
+  container: {
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'space-between',
+    flexDirection: 'column',
+    gap: ({ spacing }) => spacing(1),
+    height: ({ spacing }) => spacing(38),
+  },
+  grid: {
+    display: 'flex',
+    justifyContent: 'space-between',
+    flex: '1 1 auto',
+    alignItems: 'flex-end',
+    width: '100%',
+  },
+  bar: {
+    flex: 1,
+    maxWidth: ({ spacing }) => spacing(12),
+    '& + &': {
+      marginLeft: ({ spacing }) => spacing(1),
+    },
+  },
+  legend: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: ({ spacing }) => spacing(2),
+    height: ({ spacing }) => spacing(5),
+  },
+  legendItem: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: ({ spacing }) => spacing(1.5),
+  },
+} satisfies Record<string, SxProps<Theme>>
+
+const BAR_HEIGHTS = ['20%', '40%', '60%', '20%', '80%'] as const
+
+/**
+ * Loading state for the Bar widget. Mirrors a bar chart's silhouette — five
+ * vertical bars at staggered heights anchored to the bottom, plus a legend
+ * stub — so the skeleton reads as "a bar chart" rather than a generic list.
+ */
 export function BarSkeleton() {
   return (
-    <Box sx={styles.skeleton.graph.container}>
-      <Box sx={styles.skeleton.graph.grid}>
-        <Skeleton
-          sx={styles.skeleton.item}
-          variant='rectangular'
-          height='20%'
-        />
-        <Skeleton
-          sx={styles.skeleton.item}
-          variant='rectangular'
-          height='40%'
-        />
-        <Skeleton
-          sx={styles.skeleton.item}
-          variant='rectangular'
-          height='60%'
-        />
-        <Skeleton
-          sx={styles.skeleton.item}
-          variant='rectangular'
-          height='20%'
-        />
-        <Skeleton
-          sx={styles.skeleton.item}
-          variant='rectangular'
-          height='80%'
-        />
+    <Box sx={styles.container}>
+      <Box sx={styles.grid}>
+        {BAR_HEIGHTS.map((height, i) => (
+          <Skeleton
+            key={`bar-${i}`}
+            sx={styles.bar}
+            variant='rectangular'
+            height={height}
+          />
+        ))}
       </Box>
-      <Box
-        sx={{
-          display: 'flex',
-          alignItems: 'center',
-          gap: ({ spacing }) => spacing(2),
-          height: ({ spacing }) => spacing(5),
-        }}
-      >
-        {Array(2)
-          .fill(0)
-          .map((_, i) => (
-            <Box
-              key={`skeleton-${i}`}
-              sx={{
-                display: 'flex',
-                alignItems: 'center',
-                gap: ({ spacing }) => spacing(1.5),
-              }}
-            >
-              <Skeleton variant='circular' width={8} height={8} />
-              <Skeleton width={48} height={8} />
-            </Box>
-          ))}
+      <Box sx={styles.legend}>
+        {[0, 1].map((i) => (
+          <Box key={`legend-${i}`} sx={styles.legendItem}>
+            <Skeleton variant='circular' width={8} height={8} />
+            <Skeleton width={48} height={8} />
+          </Box>
+        ))}
       </Box>
     </Box>
   )

package/src/widgets/bar/types.ts

@@ -1,16 +1,51 @@
-import type { EchartWidgetData, EchartWidgetState } from '../echart'
-import type {
-  EchartWidgetOptionProps,
-  EchartWidgetProps,
-} from '../echart/types'
-import type { ConfigProps } from '../loader'
+import type { Theme } from '@mui/material'
+import type { EChartsOption } from 'echarts'
+import type { WidgetSeries } from '../types'
 
-export type BarWidgetData = EchartWidgetData
+/** A single category entry in a bar series. */
+export interface BarDatum {
+  name: string | number
+  value: number
+}
+
+/** v2 bar widget data shape: array of series, each a flat list of `{name, value}`. */
+export type BarWidgetData = readonly (readonly BarDatum[])[]
 
-export type BarWidgetState = EchartWidgetState
+/** Inputs to the structural-only {@link barOptions} builder. */
+export interface BarOptionsInput {
+  theme: Theme
+  formatter?: (value: number) => string
+  labelFormatter?: (value: string | number) => string | number
+}
 
-export type BarWidgetConfig = EchartWidgetProps & {
-  type: 'bar'
+/**
+ * Combined inputs for the option factory creator. Carries everything the
+ * widget needs across BOTH phases — the structural-build (`theme`,
+ * `formatter`, `labelFormatter`, `optionsOverride`) AND the data merge
+ * (`series`, `selection`).
+ */
+export interface BarOptionFactoryInput {
+  theme: Theme
+  formatter?: (value: number) => string
+  labelFormatter?: (value: string | number) => string | number
+  /**
+   * Per-series metadata — drives the legend, `series[i].name`, and
+   * (when `color` is set) per-series `itemStyle.color`. Paired with the
+   * data series by index.
+   */
+  series?: readonly WidgetSeries[]
+  /**
+   * When set, every datum whose `name` is **not** in this list renders dimmed
+   * (`itemStyle.opacity: 0.15`, matching `outOfBrush` styling). `null`/empty
+   * means "no selection active" — every bar is fully opaque.
+   */
+  selection?: readonly (string | number)[] | null
+  /**
+   * Consumer-supplied partial option merged into the structural option at
+   * structural-build time (via `mergeOptions`). Lets stories override pieces
+   * of the theme-aware base without forking the structural builder.
+   */
+  optionsOverride?: Partial<EChartsOption>
 }
 
-export type BarConfig = ConfigProps & EchartWidgetOptionProps<BarWidgetData>
+export type BarEChartsOption = EChartsOption