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

package/src/widgets-v2/toolbox/toolbox.test.tsx

@@ -0,0 +1,200 @@
+import { useEffect, useRef } from 'react'
+import { describe, it, expect } from 'vitest'
+import { fireEvent, render, screen } from '@testing-library/react'
+import { IconButton } from '@mui/material'
+import { Star as StarIcon } from '@mui/icons-material'
+import { Toolbox } from './toolbox'
+
+function makeChildren(n: number) {
+  return Array.from({ length: n }).map((_, i) => (
+    <IconButton key={i} aria-label={`Tool ${i + 1}`} size='small'>
+      <StarIcon fontSize='small' />
+    </IconButton>
+  ))
+}
+
+/**
+ * Visible iff the item's Toolbox wrapper has `data-toolbox-item-visible`
+ * set to `'true'`. Items always mount (single-mount via portal) —
+ * visibility is the only thing that flips when the popper opens/closes.
+ */
+function isItemVisible(label: string): boolean {
+  const el = screen.getByLabelText(label)
+  const wrapper = el.closest('[data-toolbox-item-visible]')
+  if (!wrapper) throw new Error(`No toolbox wrapper for "${label}"`)
+  return wrapper.getAttribute('data-toolbox-item-visible') === 'true'
+}
+
+describe('<Toolbox>', () => {
+  it('renders nothing when there are no children', () => {
+    const { container } = render(<Toolbox>{null}</Toolbox>)
+    expect(container.firstChild).toBeNull()
+  })
+
+  it('renders every child inline when visibleCount is omitted', () => {
+    render(<Toolbox>{makeChildren(4)}</Toolbox>)
+    for (let i = 1; i <= 4; i++) {
+      expect(screen.getByLabelText(`Tool ${i}`)).toBeTruthy()
+    }
+  })
+
+  it('renders every child inline when count <= visibleCount', () => {
+    render(<Toolbox visibleCount={5}>{makeChildren(3)}</Toolbox>)
+    expect(screen.queryByLabelText('More actions')).toBeNull()
+    expect(screen.getByLabelText('Tool 1')).toBeTruthy()
+    expect(screen.getByLabelText('Tool 3')).toBeTruthy()
+  })
+
+  it('closed with overflow → first N visible inline, rest in DOM but hidden', () => {
+    render(<Toolbox visibleCount={2}>{makeChildren(5)}</Toolbox>)
+    // Every item is mounted exactly once.
+    for (let i = 1; i <= 5; i++) {
+      expect(screen.getAllByLabelText(`Tool ${i}`).length).toBe(1)
+    }
+    // Visibility: first 2 visible, rest display:none.
+    expect(isItemVisible('Tool 1')).toBe(true)
+    expect(isItemVisible('Tool 2')).toBe(true)
+    expect(isItemVisible('Tool 3')).toBe(false)
+    expect(isItemVisible('Tool 4')).toBe(false)
+    expect(isItemVisible('Tool 5')).toBe(false)
+  })
+
+  it('open with overflow → all items visible (popover) without remounting any of them', () => {
+    let mountCount = 0
+    function Counted() {
+      const counted = useRef(false)
+      useEffect(() => {
+        if (counted.current) return
+        counted.current = true
+        mountCount += 1
+      }, [])
+      return (
+        <IconButton aria-label='Counted' size='small'>
+          <StarIcon fontSize='small' />
+        </IconButton>
+      )
+    }
+    render(
+      <Toolbox visibleCount={1}>
+        <IconButton aria-label='Visible' size='small' key='v'>
+          <StarIcon fontSize='small' />
+        </IconButton>
+        <Counted key='c' />
+      </Toolbox>,
+    )
+    expect(mountCount).toBe(1)
+    expect(isItemVisible('Counted')).toBe(false)
+    fireEvent.click(screen.getByLabelText('More actions'))
+    // Still mounted exactly once — no remount on open.
+    expect(mountCount).toBe(1)
+    expect(isItemVisible('Counted')).toBe(true)
+    fireEvent.click(screen.getByLabelText('Close'))
+    // And still no remount on close.
+    expect(mountCount).toBe(1)
+    expect(isItemVisible('Counted')).toBe(false)
+  })
+
+  it('swaps the trigger label to "Close" when the Paper is open', () => {
+    render(<Toolbox visibleCount={2}>{makeChildren(4)}</Toolbox>)
+    const trigger = screen.getByLabelText('More actions')
+    expect(trigger.getAttribute('aria-pressed')).toBe('false')
+    fireEvent.click(trigger)
+    // Same button now exposes the close label.
+    expect(screen.getByLabelText('Close')).toBe(trigger)
+    expect(trigger.getAttribute('aria-pressed')).toBe('true')
+  })
+
+  it('honors a custom trigger label', () => {
+    render(
+      <Toolbox visibleCount={1} labels={{ trigger: 'Extra' }}>
+        {makeChildren(3)}
+      </Toolbox>,
+    )
+    expect(screen.getByLabelText('Extra')).toBeTruthy()
+  })
+
+  it('keeps a hidden marker between visible items in the inline preview', () => {
+    render(
+      <Toolbox visibleCount={2}>
+        <IconButton key='a' aria-label='Tool A' size='small'>
+          <StarIcon fontSize='small' />
+        </IconButton>
+        <span data-toolbar-hidden key='divider' aria-label='Divider' />
+        <IconButton key='b' aria-label='Tool B' size='small'>
+          <StarIcon fontSize='small' />
+        </IconButton>
+        <IconButton key='c' aria-label='Tool C' size='small'>
+          <StarIcon fontSize='small' />
+        </IconButton>
+      </Toolbox>,
+    )
+    // Every item is mounted exactly once. Inline visibility: A, divider, B
+    // (divider sits between visible items); Tool C is hidden inline.
+    expect(screen.getAllByLabelText('Tool A').length).toBe(1)
+    expect(screen.getAllByLabelText('Divider').length).toBe(1)
+    expect(screen.getAllByLabelText('Tool B').length).toBe(1)
+    expect(screen.getAllByLabelText('Tool C').length).toBe(1)
+    expect(isItemVisible('Tool A')).toBe(true)
+    expect(isItemVisible('Divider')).toBe(true)
+    expect(isItemVisible('Tool B')).toBe(true)
+    expect(isItemVisible('Tool C')).toBe(false)
+  })
+
+  it('drops trailing hidden items past the visible budget — no orphan dividers inline', () => {
+    render(
+      <Toolbox visibleCount={2}>
+        <IconButton key='a' aria-label='Tool A' size='small'>
+          <StarIcon fontSize='small' />
+        </IconButton>
+        <IconButton key='b' aria-label='Tool B' size='small'>
+          <StarIcon fontSize='small' />
+        </IconButton>
+        <span
+          data-toolbar-hidden
+          key='divider'
+          data-testid='trailing-divider'
+        />
+        <IconButton key='c' aria-label='Tool C' size='small'>
+          <StarIcon fontSize='small' />
+        </IconButton>
+      </Toolbox>,
+    )
+    // Inline visibility: A + B; the trailing divider is dropped from the
+    // inline-visible set so it doesn't appear as an orphan separator.
+    expect(isItemVisible('Tool A')).toBe(true)
+    expect(isItemVisible('Tool B')).toBe(true)
+    const divider = screen.getByTestId('trailing-divider')
+    const wrapper = divider.closest('[data-toolbox-item-visible]')
+    expect(wrapper?.getAttribute('data-toolbox-item-visible')).toBe('false')
+    expect(isItemVisible('Tool C')).toBe(false)
+  })
+
+  it('marks the trigger active (className) while the Paper is open so the wrapper hover-fade keeps it visible', () => {
+    render(<Toolbox visibleCount={2}>{makeChildren(4)}</Toolbox>)
+    const trigger = screen.getByLabelText('More actions')
+    expect(trigger.className).not.toMatch(/\bactive\b/)
+    fireEvent.click(trigger)
+    expect(trigger.className).toMatch(/\bactive\b/)
+  })
+
+  it('auto-closes and falls back to inline when visibleCount flips to undefined while the popper is open', () => {
+    function Wrap({ count }: { count: number | undefined }) {
+      return <Toolbox visibleCount={count}>{makeChildren(5)}</Toolbox>
+    }
+    const { rerender } = render(<Wrap count={2} />)
+    fireEvent.click(screen.getByLabelText('More actions'))
+    // Popper open, all items visible inside it.
+    for (let i = 1; i <= 5; i++) {
+      expect(isItemVisible(`Tool ${i}`)).toBe(true)
+    }
+    // Caller drops `visibleCount` (e.g. fullscreen opens). Overflow vanishes
+    // and so does the popper — items should keep showing inline, *not* be
+    // stranded in the detached paper node.
+    rerender(<Wrap count={undefined} />)
+    expect(screen.queryByLabelText('More actions')).toBeNull()
+    expect(screen.queryByLabelText('Close')).toBeNull()
+    for (let i = 1; i <= 5; i++) {
+      expect(isItemVisible(`Tool ${i}`)).toBe(true)
+    }
+  })
+})

package/src/widgets-v2/toolbox/toolbox.tsx

@@ -0,0 +1,309 @@
+import {
+  Children,
+  isValidElement,
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useState,
+  type ComponentType,
+  type ReactElement,
+  type ReactNode,
+} from 'react'
+import { createPortal } from 'react-dom'
+import {
+  Box,
+  Divider,
+  Grow,
+  IconButton,
+  Paper,
+  Popper,
+  type SvgIconProps,
+  type SxProps,
+  type Theme,
+} from '@mui/material'
+import { Close as CloseIcon } from '@mui/icons-material'
+import { WidgetOptions } from '@carto/meridian-ds/custom-icons'
+import { Tooltip } from '../../components'
+import { DEFAULT_TOOLBOX_LABELS, type ToolboxLabels } from './labels'
+import { styles } from './style'
+
+export interface ToolboxProps {
+  /**
+   * Maximum number of (non-`data-toolbar-hidden`) children rendered inline
+   * when collapsed. Excess children are revealed via the overflow trigger
+   * inside a floating Paper. When omitted, all children render inline.
+   */
+  visibleCount?: number
+  labels?: Partial<ToolboxLabels>
+  /**
+   * Glyph used for the closed-state trigger. Defaults to the meridian-ds
+   * `WidgetOptions` icon (matches v1's `ToolbarActions`).
+   */
+  icon?: ComponentType<SvgIconProps>
+  iconProps?: SvgIconProps
+  /**
+   * Side the overflow Paper opens toward. `'right'` (default) places the
+   * trigger on the left and the Paper covers the row to the right;
+   * `'left'` is the mirror.
+   */
+  direction?: 'left' | 'right'
+  sx?: SxProps<Theme>
+  children: ReactNode
+}
+
+/**
+ * Smart overflow toolbar with **single-mount** items. Children mount once
+ * into a stable, hidden host element and are *physically reparented* via
+ * `appendChild` between the inline preview area and the overflow `<Paper>`
+ * as the popper opens / closes — same pattern as `Widget.FullScreen.Slot`.
+ * Items with no inline space when closed are kept mounted but visually
+ * hidden via `display: none`.
+ *
+ * Why this matters: every toggle's `useTransform` registers a config /
+ * data transform on mount and removes it on unmount. If items remounted
+ * on each open / close, the brief setup → cleanup window would re-emit
+ * the pipeline (transform missing → transform present), causing a visible
+ * flicker on state-bearing transforms (Stack, Zoom, RelativeData). With
+ * stable mounts the transform stays registered across the whole popover
+ * lifecycle.
+ *
+ * Children flagged with `data-toolbar-hidden` (e.g. dividers) skip the
+ * visibility budget but still render in their natural position. Trailing
+ * hidden items past the budget are excluded from the inline preview so
+ * they don't appear as orphan separators in the inline row; they're still
+ * there in the popover.
+ */
+export function Toolbox({
+  visibleCount,
+  labels,
+  icon: Icon = WidgetOptions,
+  iconProps,
+  direction = 'right',
+  sx,
+  children,
+}: ToolboxProps) {
+  const _labels = { ...DEFAULT_TOOLBOX_LABELS, ...labels }
+  // Each useState below is independent UI state — not "related state" that
+  // `useReducer` would clean up. Justifications:
+  //   - `open`: toggles the overflow popover, drives JSX rendering.
+  //   - `anchorEl`: feeds `<Popper anchorEl>`; the Popper must re-render
+  //     when the trigger element first attaches.
+  //   - `inlineEl` / `paperEl`: read by the layout-effect dep array below
+  //     to reparent the stable host between shells; useRef wouldn't fire
+  //     the effect when the elements attach.
+  //   - `host` (further down): see its own comment — kept in state to make
+  //     the React Compiler happy reading it during render.
+  const [open, setOpen] = useState(false)
+  const [anchorEl, setAnchorEl] = useState<HTMLButtonElement | null>(null)
+  const [inlineEl, setInlineEl] = useState<HTMLElement | null>(null)
+  const [paperEl, setPaperEl] = useState<HTMLElement | null>(null)
+
+  const handleToggle = useCallback(() => setOpen((v) => !v), [])
+  const handleTriggerRef = useCallback((node: HTMLButtonElement | null) => {
+    setAnchorEl(node)
+  }, [])
+
+  // Esc closes the overflow paper. Outside-click is intentionally NOT wired:
+  // an action inside the Paper (e.g. RelativeData toggling, a Brush menu)
+  // can update widget state which momentarily reflows the page; if that's
+  // treated as a click-outside, the Paper would dismiss itself mid-action.
+  // Users explicitly close via the trigger or Escape.
+  useEffect(() => {
+    if (!open) return undefined
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') setOpen(false)
+    }
+    document.addEventListener('keydown', onKey)
+    return () => document.removeEventListener('keydown', onKey)
+  }, [open])
+
+  // Stable host element shared by every toolbox cycle. `display: contents`
+  // keeps it transparent in flow so items inherit layout (flex row + gap)
+  // from whichever shell currently parents the host (the inline preview
+  // Box or the popover Paper). Held in state — not a ref — so the React
+  // Compiler is happy reading it during render.
+  const [host] = useState<HTMLDivElement | null>(() => {
+    if (typeof document === 'undefined') return null
+    const div = document.createElement('div')
+    div.style.display = 'contents'
+    return div
+  })
+
+  const items = Children.toArray(children).filter((c): c is ReactElement =>
+    isValidElement(c),
+  )
+
+  const visibleCountActual = items.reduce(
+    (n, c) => n + (isToolbarHidden(c) ? 0 : 1),
+    0,
+  )
+  const showOverflow =
+    visibleCount !== undefined && visibleCountActual > visibleCount
+
+  // Indices that are visible inline when the popper is closed. When the
+  // popper is open, every item is visible (in the popover). `null` means
+  // "no overflow — all items visible inline".
+  const inlineVisibleIndices = useMemo<Set<number> | null>(() => {
+    if (!showOverflow || visibleCount === undefined) return null
+    return computeInlineVisibleIndices(items, visibleCount)
+  }, [items, visibleCount, showOverflow])
+
+  // Auto-close the popper when overflow disappears (e.g. `visibleCount`
+  // flips from a number to `undefined` because the consumer entered
+  // fullscreen and wants every action visible inline). Without this the
+  // popper component unmounts under us, `paperEl` goes null, and the host
+  // would be stranded in a detached node — the toolbox visibly disappears.
+  //
+  // Uses React's documented "store information from previous renders"
+  // pattern: a guarded inline `setOpen(false)` during render. The guard
+  // fires at most once per transition (`open` flips false the same render
+  // and the next render's predicate is false). React rebases the in-flight
+  // render before commit, so the layout effect below sees `open=false`
+  // immediately. See
+  // https://react.dev/reference/react/useState#storing-information-from-previous-renders
+  if (!showOverflow && open) {
+    setOpen(false)
+  }
+
+  // Reparent the host into the active shell whenever `open` (or either
+  // shell) changes. `useLayoutEffect` runs synchronously after commit
+  // (after refs have been written), so the popover Paper ref is already
+  // live when we read it. Falling back to `inlineEl` whenever `paperEl`
+  // is missing handles cases where the popper has unmounted (showOverflow
+  // flipped false) — the host always has a valid destination.
+  useLayoutEffect(() => {
+    const target = open && paperEl ? paperEl : inlineEl
+    if (host && target && host.parentNode !== target) {
+      target.appendChild(host)
+    }
+  }, [open, inlineEl, paperEl, host])
+
+  if (items.length === 0) return null
+
+  const tooltipLabel = open ? _labels.close : _labels.trigger
+  const flexDirection = direction === 'left' ? 'row-reverse' : 'row'
+
+  return (
+    <Box sx={{ ...styles.root, flexDirection, ...sx }}>
+      {showOverflow && (
+        <>
+          <Tooltip title={tooltipLabel}>
+            <IconButton
+              ref={handleTriggerRef}
+              size='small'
+              aria-label={tooltipLabel}
+              aria-pressed={open}
+              onClick={handleToggle}
+              className={open ? 'active' : undefined}
+              sx={{ ...(open && styles.triggerActive) }}
+            >
+              {open ? (
+                <CloseIcon fontSize='small' />
+              ) : (
+                <Icon fontSize='small' {...iconProps} />
+              )}
+            </IconButton>
+          </Tooltip>
+          <Divider orientation='vertical' flexItem sx={{ mx: 0.5 }} />
+        </>
+      )}
+
+      {/* Inline shell: when closed (or when there's no overflow) the host
+          lives here so first-N items appear inline beside the trigger. */}
+      <Box ref={setInlineEl} sx={styles.preview} />
+
+      {showOverflow && (
+        <Popper
+          open={open}
+          anchorEl={anchorEl}
+          placement={direction === 'left' ? 'left' : 'right'}
+          transition
+          // Disable flipping so the Paper stays on the configured side
+          // even when the trigger sits near a viewport edge — wrapper
+          // consumers expect a stable layout.
+          modifiers={[{ name: 'flip', enabled: false }]}
+          // Slot the popper *above* most modal stacking, but below MUI's
+          // own modal layer.
+          sx={{ zIndex: 'tooltip', mt: 0 }}
+        >
+          {({ TransitionProps }) => (
+            <Grow
+              {...TransitionProps}
+              style={{
+                transformOrigin:
+                  direction === 'left' ? 'right center' : 'left center',
+              }}
+            >
+              <Paper ref={setPaperEl} sx={styles.paper} />
+            </Grow>
+          )}
+        </Popper>
+      )}
+
+      {/* Items render once into the stable host. The host's parent is
+          whichever shell is currently active (inline or popper). When
+          closed-with-overflow, items beyond the budget get `display: none`
+          so they're mounted but invisible. The wrapper uses an inline
+          `style` (not `sx`) so the visibility decision lands on the
+          element itself — tests can inspect it without traversing
+          generated MUI class names. */}
+      {host
+        ? createPortal(
+            items.map((item, i) => {
+              const visible =
+                open || !inlineVisibleIndices || inlineVisibleIndices.has(i)
+              const key = item.key ?? i
+              return (
+                <div
+                  key={key}
+                  data-toolbox-item-visible={visible ? 'true' : 'false'}
+                  style={{ display: visible ? 'contents' : 'none' }}
+                >
+                  {item}
+                </div>
+              )
+            }),
+            host,
+          )
+        : null}
+    </Box>
+  )
+}
+
+function isToolbarHidden(child: ReactElement): boolean {
+  // Opt-in flag callers set on slot children (e.g. dividers between groups)
+  // so they don't count toward the inline visibility budget.
+  const props = (
+    child as unknown as { props: { 'data-toolbar-hidden'?: unknown } }
+  ).props
+  return props['data-toolbar-hidden'] === true
+}
+
+/**
+ * Compute the set of item indices visible inline when the popper is closed.
+ * Walk the items in order, accept each one until the visible budget is
+ * exhausted; hidden items (dividers, etc.) accept without bumping the
+ * counter. Strip trailing hidden items from the visible set so the inline
+ * row doesn't end with an orphan separator.
+ */
+function computeInlineVisibleIndices(
+  items: readonly ReactElement[],
+  visibleCount: number,
+): Set<number> {
+  const indices: number[] = []
+  let count = 0
+  for (let i = 0; i < items.length; i++) {
+    if (count >= visibleCount) break
+    indices.push(i)
+    if (!isToolbarHidden(items[i]!)) count++
+  }
+  // Strip trailing hidden items.
+  while (
+    indices.length > 0 &&
+    isToolbarHidden(items[indices[indices.length - 1]!]!)
+  ) {
+    indices.pop()
+  }
+  return new Set(indices)
+}

package/src/widgets-v2/types.ts

@@ -0,0 +1,25 @@
+/**
+ * Canonical cross-widget series metadata.
+ *
+ * Every widget that can carry multiple series (Bar, Pie, Histogram,
+ * Scatterplot, Timeseries, Category, Formula, Spread) accepts a
+ * `series: readonly WidgetSeries[]` prop. The `name` drives legends,
+ * tooltips, and category-row avatars; the optional `color` overrides
+ * the default palette assignment.
+ *
+ * For backward compatibility, the widget-specific names
+ * (`FormulaSeries`, `CategorySeriesConfig`) are kept as type aliases of
+ * `WidgetSeries` — see `formula/types.ts` and `category/types.ts`.
+ *
+ * Colours accept MUI theme paths (e.g. `'primary.main'`) as well as raw
+ * CSS strings (`'#ff0000'`, `'rgb(…)'`). The echart-based widgets
+ * resolve them through `resolveThemeColor` (see
+ * `widgets-v2/utils/resolve-theme-color.ts`); Category and Formula/Spread
+ * resolve them implicitly via MUI's `sx` prop.
+ */
+export interface WidgetSeries {
+  /** Display name — drives legend, tooltip, and avatar glyphs. */
+  name: string
+  /** Optional colour override. MUI theme path or raw CSS string. */
+  color?: string
+}

package/src/widgets-v2/utils/data-zoom-layout.ts

@@ -0,0 +1,26 @@
+import { ZOOM_LAYOUT } from '../actions/zoom-toggle'
+
+/**
+ * If the option includes a `dataZoom` array (from ZoomToggle's transform),
+ * lift any slider entries above the legend row so they don't overlap.
+ * Returns `null` when there is no `dataZoom` — caller skips the layout
+ * adjustment entirely.
+ *
+ * Shared between bar, histogram, and timeseries — every widget with a
+ * horizontal x-axis dataZoom slider needs the same offset when a legend
+ * is rendered below the plot.
+ */
+export function positionDataZoomForLegend(
+  dataZoom: unknown,
+  hasLegend: boolean,
+): unknown[] | null {
+  if (!Array.isArray(dataZoom) || dataZoom.length === 0) return null
+  return dataZoom.map((entry: unknown) => {
+    if (entry == null || typeof entry !== 'object') return entry
+    const dz = entry as { type?: string; bottom?: number }
+    if (dz.type === 'slider' && hasLegend) {
+      return { ...dz, bottom: ZOOM_LAYOUT.sliderBottomWithLegend }
+    }
+    return dz
+  })
+}

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

@@ -0,0 +1,3 @@
+export { mergeOptions } from './merge-options'
+export { positionDataZoomForLegend } from './data-zoom-layout'
+export { resolveThemeColor } from './resolve-theme-color'

package/src/widgets-v2/utils/merge-options.test.ts

@@ -0,0 +1,52 @@
+import { describe, it, expect } from 'vitest'
+import { mergeOptions } from './merge-options'
+
+describe('mergeOptions', () => {
+  it('returns base unchanged when override is undefined', () => {
+    const base = { a: 1, b: { c: 2 } }
+    expect(mergeOptions(base)).toBe(base)
+  })
+
+  it('shallow-merges top-level keys', () => {
+    const base: Record<string, unknown> = { a: 1, b: 2 }
+    const out = mergeOptions(base, { b: 3, c: 4 })
+    expect(out).toEqual({ a: 1, b: 3, c: 4 })
+  })
+
+  it('shallow-merges plain objects per key', () => {
+    const base: Record<string, unknown> = { x: { p: 1, q: 2 } }
+    const out = mergeOptions(base, { x: { q: 99, r: 3 } })
+    expect(out).toEqual({ x: { p: 1, q: 99, r: 3 } })
+  })
+
+  it('merges arrays element-wise, deep-merging plain-object elements', () => {
+    const base: Record<string, unknown> = {
+      series: [{ type: 'bar', data: [1, 2] }, { type: 'line' }],
+    }
+    const out = mergeOptions(base, {
+      series: [{ data: [3, 4] }, { name: 'second' }],
+    })
+    expect(out).toEqual({
+      series: [
+        { type: 'bar', data: [3, 4] },
+        { type: 'line', name: 'second' },
+      ],
+    })
+  })
+
+  it('primitive override replaces primitive base', () => {
+    expect(mergeOptions({ count: 1 }, { count: 99 })).toEqual({ count: 99 })
+  })
+
+  it('skips override values that are undefined', () => {
+    expect(mergeOptions({ a: 1, b: 2 }, { a: undefined })).toEqual({
+      a: 1,
+      b: 2,
+    })
+  })
+
+  it('uses base value when array is longer than override', () => {
+    const base: Record<string, unknown> = { s: [1, 2, 3] }
+    expect(mergeOptions(base, { s: [10] })).toEqual({ s: [10, 2, 3] })
+  })
+})

package/src/widgets-v2/utils/merge-options.ts

@@ -0,0 +1,50 @@
+/**
+ * Shallow-merges two ECharts option objects:
+ *   - Top-level keys from both are combined.
+ *   - Arrays are merged by index (element-wise shallow merge, primitive override).
+ *   - Plain objects are shallow-merged.
+ *   - Primitives are overridden by the override value.
+ *
+ * Designed for the two-stage memoization pattern: first build a base option
+ * object from data + theme + formatters, then call `mergeOptions(base, override)`
+ * inside a second `useMemo` keyed on `[base, override]`.
+ */
+export function mergeOptions<T extends Record<string, unknown>>(
+  base: T,
+  override?: Partial<T>,
+): T {
+  if (!override) return base
+  const out: Record<string, unknown> = { ...base }
+  for (const key of Object.keys(override) as (keyof T)[]) {
+    const a = base[key]
+    const b = override[key]
+    if (b === undefined) continue
+    out[key as string] = mergeValue(a, b)
+  }
+  return out as T
+}
+
+function mergeValue(a: unknown, b: unknown): unknown {
+  if (Array.isArray(a) && Array.isArray(b)) {
+    const len = Math.max(a.length, b.length)
+    const result = new Array<unknown>(len)
+    for (let i = 0; i < len; i++) {
+      const av: unknown = a[i]
+      const bv: unknown = b[i]
+      if (bv === undefined) result[i] = av
+      else if (av === undefined) result[i] = bv
+      else result[i] = mergeValue(av, bv)
+    }
+    return result
+  }
+  if (isPlainObject(a) && isPlainObject(b)) {
+    return { ...a, ...b }
+  }
+  return b
+}
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+  if (v === null || typeof v !== 'object') return false
+  const proto = Object.getPrototypeOf(v) as unknown
+  return proto === Object.prototype || proto === null
+}