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

package/src/widgets-v2/bar/options.test.ts

@@ -0,0 +1,361 @@
+import { describe, it, expect } from 'vitest'
+import { createTheme, type Theme } from '@mui/material'
+import { barOptions, createBarOptionFactory } from './options'
+
+const theme = createTheme() as unknown as Theme
+
+describe('barOptions (structural)', () => {
+  it('returns a category x-axis without baked data', () => {
+    const out = barOptions({ theme })
+    const xAxis = out.xAxis as { type: string; data?: unknown }
+    expect(xAxis.type).toBe('category')
+    expect(xAxis.data).toBeUndefined()
+  })
+
+  it('returns no series and no dataset (data is fused at render time)', () => {
+    const out = barOptions({ theme })
+    expect(out.series).toBeUndefined()
+    expect(out.dataset).toBeUndefined()
+  })
+
+  it('hides x and y axis lines and ticks for the v1 minimal look', () => {
+    const out = barOptions({ theme })
+    const xAxis = out.xAxis as {
+      axisLine?: { show?: boolean }
+      axisTick?: { show?: boolean }
+    }
+    const yAxis = out.yAxis as {
+      axisLine?: { show?: boolean }
+      axisTick?: { show?: boolean }
+      splitLine?: { show?: boolean }
+    }
+    expect(xAxis.axisLine?.show).toBe(false)
+    expect(xAxis.axisTick?.show).toBe(false)
+    expect(yAxis.axisLine?.show).toBe(false)
+    expect(yAxis.axisTick?.show).toBe(false)
+    expect(yAxis.splitLine?.show).toBe(true)
+  })
+
+  it('y-axis label formatter only renders min/max via the user formatter', () => {
+    const fmt = (n: number): string => `$${n}`
+    const out = barOptions({ theme, formatter: fmt })
+    const yAxis = out.yAxis as {
+      axisLabel?: { formatter?: (v: number) => string }
+    }
+    // niceMin / niceMax default to 0 and 1 until min/max callbacks run.
+    expect(yAxis.axisLabel?.formatter?.(1)).toBe('$1')
+    // 0 is suppressed (matches v1) and intermediate values are blanked.
+    expect(yAxis.axisLabel?.formatter?.(0)).toBe('')
+    expect(yAxis.axisLabel?.formatter?.(0.5)).toBe('')
+  })
+
+  it('renders y-axis labels inside the plot, anchored to the bottom', () => {
+    const out = barOptions({ theme })
+    const yAxis = out.yAxis as {
+      axisLabel?: { inside?: boolean; verticalAlign?: string }
+    }
+    expect(yAxis.axisLabel?.inside).toBe(true)
+    expect(yAxis.axisLabel?.verticalAlign).toBe('bottom')
+  })
+
+  it('wires labelFormatter into the x-axis label', () => {
+    const lf = (v: string | number) => `[${v}]`
+    const out = barOptions({ theme, labelFormatter: lf })
+    const xAxis = out.xAxis as {
+      axisLabel?: { formatter?: (v: string | number) => string }
+    }
+    expect(xAxis.axisLabel?.formatter?.('A')).toBe('[A]')
+  })
+})
+
+describe('createBarOptionFactory', () => {
+  it('builds one dataset per series with the data array as source', () => {
+    const merge = createBarOptionFactory({ theme })
+    const data = [
+      [
+        { name: 'A', value: 1 },
+        { name: 'B', value: 2 },
+      ],
+      [
+        { name: 'A', value: 3 },
+        { name: 'B', value: 4 },
+      ],
+    ]
+    const out = merge({}, data) as { dataset: { source: object[] }[] }
+    expect(out.dataset).toHaveLength(2)
+    expect(out.dataset[0]?.source).toBe(data[0])
+    expect(out.dataset[1]?.source).toBe(data[1])
+  })
+
+  it('encodes name → x and value → y, with each series referencing its dataset by index', () => {
+    const merge = createBarOptionFactory({ theme })
+    const out = merge({}, [
+      [{ name: 'A', value: 1 }],
+      [{ name: 'A', value: 2 }],
+    ]) as {
+      series: {
+        type: string
+        datasetIndex: number
+        encode: { x: string; y: string }
+        barMaxWidth: number
+        emphasis: { focus: string }
+      }[]
+    }
+    expect(out.series[0]).toMatchObject({
+      type: 'bar',
+      datasetIndex: 0,
+      encode: { x: 'name', y: 'value' },
+      barMaxWidth: 100,
+      emphasis: { focus: 'series' },
+    })
+    expect(out.series[1]).toMatchObject({
+      type: 'bar',
+      datasetIndex: 1,
+      encode: { x: 'name', y: 'value' },
+      barMaxWidth: 100,
+      emphasis: { focus: 'series' },
+    })
+  })
+
+  it('uses series[i].name for legend names when provided', () => {
+    const merge = createBarOptionFactory({
+      theme,
+      series: [{ name: '2024' }, { name: '2025' }],
+    })
+    const out = merge({}, [
+      [{ name: 'A', value: 1 }],
+      [{ name: 'A', value: 2 }],
+    ]) as { series: { name: string }[] }
+    expect(out.series[0]?.name).toBe('2024')
+    expect(out.series[1]?.name).toBe('2025')
+  })
+
+  it('applies series[i].color as a per-series itemStyle override', () => {
+    const merge = createBarOptionFactory({
+      theme,
+      series: [
+        { name: '2024', color: '#ff0000' },
+        { name: '2025' }, // no color → falls back to palette
+      ],
+    })
+    const out = merge({}, [
+      [{ name: 'A', value: 1 }],
+      [{ name: 'A', value: 2 }],
+    ]) as { series: { color?: string }[] }
+    expect(out.series[0]?.color).toBe('#ff0000')
+    // Second series has no explicit color → echart palette picks one.
+    expect(out.series[1]?.color).toBeUndefined()
+  })
+
+  it('toggles legend visibility based on series count, preserving styling', () => {
+    const merge = createBarOptionFactory({ theme })
+    const baseLegend = { icon: 'circle', type: 'scroll' }
+    const single = merge({ legend: baseLegend }, [
+      [{ name: 'A', value: 1 }],
+    ]) as { legend: { show: boolean; icon?: string } }
+    const multi = merge({ legend: baseLegend }, [
+      [{ name: 'A', value: 1 }],
+      [{ name: 'A', value: 2 }],
+    ]) as { legend: { show: boolean; icon?: string } }
+    expect(single.legend.show).toBe(false)
+    expect(single.legend.icon).toBe('circle')
+    expect(multi.legend.show).toBe(true)
+    expect(multi.legend.icon).toBe('circle')
+  })
+
+  it('reserves extra grid bottom space when a legend is shown', () => {
+    const merge = createBarOptionFactory({ theme })
+    const baseGrid = { bottom: 24 }
+    const single = merge({ grid: baseGrid }, [[{ name: 'A', value: 1 }]]) as {
+      grid: { bottom: number }
+    }
+    const multi = merge({ grid: baseGrid }, [
+      [{ name: 'A', value: 1 }],
+      [{ name: 'A', value: 2 }],
+    ]) as { grid: { bottom: number } }
+    expect(single.grid.bottom).toBe(24)
+    expect(multi.grid.bottom).toBe(56)
+  })
+
+  it('returns empty dataset/series for empty data', () => {
+    const merge = createBarOptionFactory({ theme })
+    const out = merge({ xAxis: { type: 'category' } }, []) as {
+      dataset: unknown[]
+      series: unknown[]
+    }
+    expect(out.dataset).toEqual([])
+    expect(out.series).toEqual([])
+  })
+
+  it('merges incoming series template into every series (Stack survives)', () => {
+    // Simulates `addStack` having run as a config transform: the option
+    // arrives with a single broadcast template carrying { stack: 'total' }.
+    const merge = createBarOptionFactory({ theme })
+    const out = merge({ series: [{ stack: 'total' }] }, [
+      [{ name: 'A', value: 1 }],
+      [{ name: 'A', value: 2 }],
+    ]) as { series: { stack?: string; type: string; datasetIndex: number }[] }
+    expect(out.series).toHaveLength(2)
+    expect(out.series[0]?.stack).toBe('total')
+    expect(out.series[1]?.stack).toBe('total')
+    // Authoritative properties still win over the template.
+    expect(out.series[0]?.type).toBe('bar')
+    expect(out.series[0]?.datasetIndex).toBe(0)
+    expect(out.series[1]?.datasetIndex).toBe(1)
+  })
+
+  it('uses ctx.formatter for the y-axis min/max label (RelativeData support)', () => {
+    const merge = createBarOptionFactory({ theme })
+    const fmt = (n: number) => `${n}%`
+    const out = merge(
+      { yAxis: { type: 'value' } },
+      [
+        [
+          { name: 'A', value: 0 },
+          { name: 'B', value: 100 },
+        ],
+      ],
+      { formatter: fmt },
+    ) as {
+      yAxis: {
+        min: (extent: { min: number }) => number
+        max: (extent: { min: number; max: number }) => number
+        axisLabel: { formatter: (v: number) => string }
+      }
+    }
+    // Bounds are callbacks now: ECharts supplies the (post-stack) extent and
+    // we round it with niceNum. Invoke them as ECharts would before reading
+    // the label formatter (which keys off the closure-cached extents).
+    expect(typeof out.yAxis.min).toBe('function')
+    expect(typeof out.yAxis.max).toBe('function')
+    expect(out.yAxis.min({ min: 0 })).toBe(0)
+    expect(out.yAxis.max({ min: 0, max: 100 })).toBe(100)
+    expect(out.yAxis.axisLabel.formatter(100)).toBe('100%')
+    // Intermediate values are still suppressed.
+    expect(out.yAxis.axisLabel.formatter(50)).toBe('')
+    expect(out.yAxis.axisLabel.formatter(0)).toBe('')
+  })
+
+  it('rounds the ECharts-supplied (stacked) extent so stacked bars cannot overflow', () => {
+    // Regression: previously the merge phase precomputed the y-axis max from
+    // the largest *single* series value, so stacking (StackToggle →
+    // { stack: 'total' }) made the summed bars overflow the axis. The bound
+    // is now a callback: ECharts computes the extent AFTER stacking and we
+    // round that. Two series of 600 stack to 1200; ECharts hands us that
+    // extent and niceNum(1200) → 2000 contains it (vs. the old 600).
+    const merge = createBarOptionFactory({ theme })
+    const out = merge({ series: [{ stack: 'total' }] }, [
+      [{ name: 'A', value: 600 }],
+      [{ name: 'A', value: 600 }],
+    ]) as {
+      yAxis: {
+        min: (extent: { min: number }) => number
+        max: (extent: { min: number; max: number }) => number
+      }
+    }
+    expect(typeof out.yAxis.max).toBe('function')
+    expect(out.yAxis.max({ min: 0, max: 1200 })).toBe(2000)
+    expect(out.yAxis.min({ min: 0 })).toBe(0)
+  })
+
+  it('reserves grid bottom space for the zoom slider when dataZoom is present', () => {
+    const merge = createBarOptionFactory({ theme })
+    // Single series, no legend.
+    const single = merge(
+      {
+        grid: { bottom: 24 },
+        dataZoom: [{ type: 'inside' }, { type: 'slider', bottom: 0 }],
+      },
+      [[{ name: 'A', value: 1 }]],
+    ) as { grid: { bottom: number } }
+    // 24 (base) + 32 (slider height) + 8 (gap) = 64.
+    expect(single.grid.bottom).toBe(64)
+  })
+
+  it('lifts the zoom slider above the legend when both are present', () => {
+    const merge = createBarOptionFactory({ theme })
+    const out = merge(
+      {
+        dataZoom: [{ type: 'inside' }, { type: 'slider', bottom: 0 }],
+      },
+      [[{ name: 'A', value: 1 }], [{ name: 'A', value: 2 }]],
+    ) as {
+      dataZoom: { type: string; bottom?: number }[]
+      grid: { bottom: number }
+    }
+    const slider = out.dataZoom.find((d) => d.type === 'slider')
+    expect(slider?.bottom).toBe(28)
+    // Legend space (56) + slider height (32) + gap (8) = 96.
+    expect(out.grid.bottom).toBe(96)
+  })
+
+  describe('itemStyle.color (dim non-selected)', () => {
+    it('passes through the params color when no selection is set', () => {
+      const merge = createBarOptionFactory({ theme })
+      const out = merge({}, [[{ name: 'A', value: 1 }]]) as {
+        series: { itemStyle: { color: (p: unknown) => string } }[]
+      }
+      const colorFn = out.series[0]!.itemStyle.color
+      expect(colorFn({ value: { name: 'A' }, color: '#abc', name: 'A' })).toBe(
+        '#abc',
+      )
+    })
+
+    it('keeps the base colour for bars matching the selection', () => {
+      const merge = createBarOptionFactory({ theme, selection: ['A'] })
+      const out = merge({}, [[{ name: 'A', value: 1 }]]) as {
+        series: { itemStyle: { color: (p: unknown) => string } }[]
+      }
+      const colorFn = out.series[0]!.itemStyle.color
+      expect(colorFn({ value: { name: 'A' }, color: '#abc', name: 'A' })).toBe(
+        '#abc',
+      )
+    })
+
+    it('dims bars outside the selection via 15% alpha', () => {
+      const merge = createBarOptionFactory({ theme, selection: ['B'] })
+      const out = merge({}, [[{ name: 'A', value: 1 }]]) as {
+        series: { itemStyle: { color: (p: unknown) => string } }[]
+      }
+      const colorFn = out.series[0]!.itemStyle.color
+      const dimmed = colorFn({
+        value: { name: 'A' },
+        color: '#FF0000',
+        name: 'A',
+      })
+      expect(dimmed).not.toBe('#FF0000')
+    })
+
+    it('falls back to params.name when datum has no name', () => {
+      const merge = createBarOptionFactory({ theme, selection: ['A'] })
+      const out = merge({}, [[{ name: 'A', value: 1 }]]) as {
+        series: { itemStyle: { color: (p: unknown) => string } }[]
+      }
+      const colorFn = out.series[0]!.itemStyle.color
+      expect(colorFn({ value: undefined, color: '#abc', name: 'A' })).toBe(
+        '#abc',
+      )
+    })
+  })
+
+  it('uses ctx formatters for the tooltip (RelativeData support)', () => {
+    const merge = createBarOptionFactory({ theme })
+    const fmt = (n: number) => `${n}%`
+    const lf = (v: string | number) => `[ITEM:${v}]`
+    const out = merge({}, [[{ name: 'A', value: 50 }]], {
+      formatter: fmt,
+      labelFormatter: lf,
+    }) as { tooltip: { formatter: (params: unknown) => string } }
+    const html = out.tooltip.formatter([
+      {
+        value: { name: 'A', value: 50 },
+        name: 'A',
+        seriesName: '',
+        marker: '',
+      },
+    ])
+    // The percent formatter and label formatter both ran.
+    expect(html).toContain('50%')
+    expect(html).toContain('[ITEM:A]')
+  })
+})

package/src/widgets-v2/bar/options.ts

@@ -0,0 +1,333 @@
+import type { EChartsOption } from 'echarts'
+import * as echarts from 'echarts'
+import type { CallbackDataParams } from 'echarts/types/dist/shared'
+import {
+  buildAxisLabelStyle,
+  buildGridConfig,
+  buildLegendConfig,
+  createTooltipFormatter,
+  createTooltipPositioner,
+  niceNum,
+} from '../../widgets/utils/chart-config'
+import { ZOOM_LAYOUT } from '../actions/zoom-toggle'
+import type { OptionFactory } from '../echart'
+import { mergeOptions, resolveThemeColor } from '../utils'
+import { positionDataZoomForLegend } from '../utils/data-zoom-layout'
+import type {
+  BarEChartsOption,
+  BarOptionFactoryInput,
+  BarOptionsInput,
+  BarWidgetData,
+} from './types'
+
+/**
+ * Builds the **structural** ECharts option for a bar widget — axes, grid,
+ * tooltip styling, themed legend. Intentionally data-agnostic: no series,
+ * no dataset, no `legend.show` (those depend on data and are added by the
+ * option factory's merge phase). This separation is what lets data-side
+ * pipeline transforms (Searcher, RelativeData) drive the rendered chart —
+ * the merge happens at render time inside the Echart bridge.
+ *
+ * Styling matches the v1 `barConfig` look-and-feel: minimal axes (only
+ * min/max y-labels rendered inside the plot via `niceNum`), themed tooltip,
+ * scroll legend, and CARTO color palette. The y-axis min/max + label
+ * formatter and the tooltip formatter are wired here for the no-data case;
+ * {@link createBarOptionFactory} re-derives them at fusion time so reactive
+ * formatter changes (RelativeData) and stack templates (StackToggle) flow
+ * through to the chart.
+ */
+export function barOptions({
+  theme,
+  formatter,
+  labelFormatter,
+}: BarOptionsInput): BarEChartsOption {
+  // Closure shared between yAxis min/max callbacks and the label formatter,
+  // so only the rounded extents are labelled (matches v1).
+  let niceMin = 0
+  let niceMax = 1
+
+  return {
+    grid: {
+      left: parseInt(theme.spacing(1)),
+      top: parseInt(theme.spacing(3)),
+      right: parseInt(theme.spacing(1)),
+      // Default: no legend. Merger bumps this when there are >1 series.
+      ...buildGridConfig(false, theme),
+      containLabel: true,
+    },
+    tooltip: {
+      trigger: 'axis',
+      backgroundColor: theme.palette.grey[900],
+      borderWidth: 0,
+      padding: [parseInt(theme.spacing(1)), parseInt(theme.spacing(1))],
+      textStyle: {
+        color: theme.palette.common.white,
+        fontSize: 11,
+        fontFamily: theme.typography.caption.fontFamily,
+      },
+      axisPointer: { type: 'line' },
+      position: createTooltipPositioner(theme),
+      formatter: buildBarTooltipFormatter(formatter, labelFormatter),
+    },
+    // Legend styling baked here; `show` is toggled by the merger based on
+    // series count.
+    legend: {
+      ...buildLegendConfig({ hasLegend: false, labelFormatter }),
+    },
+    axisPointer: { lineStyle: { color: theme.palette.grey[400] } },
+    color: [
+      theme.palette.secondary.main,
+      ...Object.values(
+        (theme.palette as { qualitative?: { bold?: Record<string, string> } })
+          .qualitative?.bold ?? {},
+      ),
+    ],
+    xAxis: {
+      type: 'category',
+      axisLine: { show: false },
+      axisTick: { show: false },
+      axisLabel: {
+        ...buildAxisLabelStyle(theme),
+        padding: [parseInt(theme.spacing(0.5)), 0, 0, 0],
+        margin: 0,
+        // `interval: 0` makes every category label a candidate so `hideOverlap`
+        // can pack the maximum number that physically fit; the category-axis
+        // default (`'auto'`) sub-samples first and shows fewer than fit.
+        interval: 0,
+        hideOverlap: true,
+        ...(labelFormatter && {
+          formatter: (v: string | number) => String(labelFormatter(v)),
+        }),
+      },
+    },
+    yAxis: {
+      type: 'value',
+      min: (extent: { min: number }) => {
+        niceMin = extent.min < 0 ? niceNum(extent.min) : 0
+        return niceMin
+      },
+      max: (extent: { min: number; max: number }) => {
+        niceMax = extent.max <= 0 ? 1 : niceNum(extent.max)
+        return niceMax
+      },
+      axisLine: { show: false },
+      axisTick: { show: false },
+      splitLine: {
+        show: true,
+        lineStyle: { color: theme.palette.black?.[4] ?? theme.palette.divider },
+      },
+      axisLabel: {
+        ...buildAxisLabelStyle(theme),
+        margin: parseInt(theme.spacing(1)),
+        show: true,
+        showMaxLabel: true,
+        showMinLabel: true,
+        verticalAlign: 'bottom',
+        inside: true,
+        formatter: (value: number) => {
+          if (value !== niceMax && value !== niceMin) return ''
+          if (value === 0) return ''
+          return formatter ? formatter(value) : String(value)
+        },
+      },
+    },
+  } as BarEChartsOption
+}
+
+/**
+ * Returns the bar widget's {@link OptionFactory} — a single closure that
+ * handles BOTH option-construction phases:
+ *
+ *   - **Structural phase** (`option == null`) — builds the theme-aware
+ *     structural option via {@link barOptions}, optionally merging the
+ *     consumer-supplied `optionsOverride` on top. Called once by Provider
+ *     to seed `rawOptions` in the store; configTransforms (StackToggle /
+ *     ZoomToggle / BrushToggle) then mutate it via the pipeline middleware.
+ *   - **Merge phase** (`option != null`) — fuses post-pipeline `state.data`
+ *     (`BarWidgetData`) into the option via the dataset API: one dataset
+ *     per series, each series referencing its dataset by index, encoded
+ *     by `name` (x) and `value` (y). Spreads any series-template fields
+ *     already on the incoming option (e.g. `{ stack: 'total' }` from
+ *     `addStack`) into every emitted series so configTransforms compose
+ *     end-to-end. Reactive `ctx.formatter` / `ctx.labelFormatter` drive
+ *     the y-axis min/max-only label and the tooltip formatter at fusion
+ *     time so RelativeData's percent formatter flows through without a
+ *     structural rebuild.
+ *
+ * Stable identity when the inputs don't change (consumers should wrap the
+ * call in `useMemo` keyed on the same inputs).
+ */
+export function createBarOptionFactory(
+  options: BarOptionFactoryInput,
+): OptionFactory {
+  const { theme, formatter, labelFormatter, optionsOverride } = options
+  const series = options.series
+  const selection = options.selection
+  const selectionSet =
+    selection && selection.length > 0
+      ? new Set<string | number>(selection)
+      : null
+  return (option, data, ctx) => {
+    // Structural phase: Provider seeds rawOptions with this branch. No data
+    // is read; we just emit the theme-aware base (optionally with override).
+    if (option == null) {
+      const structural = barOptions({ theme, formatter, labelFormatter })
+      return optionsOverride
+        ? (mergeOptions(
+            structural as unknown as Record<string, unknown>,
+            optionsOverride as Partial<Record<string, unknown>>,
+          ) as EChartsOption)
+        : structural
+    }
+
+    const seriesArr = Array.isArray(data) ? (data as BarWidgetData) : []
+    if (seriesArr.length === 0) {
+      return { ...option, dataset: [], series: [] }
+    }
+    const hasLegend = seriesArr.length > 1
+    const baseLegend =
+      typeof option.legend === 'object' && !Array.isArray(option.legend)
+        ? option.legend
+        : {}
+    const baseGrid =
+      typeof option.grid === 'object' && !Array.isArray(option.grid)
+        ? option.grid
+        : {}
+    const baseTooltip =
+      typeof option.tooltip === 'object' && !Array.isArray(option.tooltip)
+        ? option.tooltip
+        : {}
+    const baseYAxis =
+      typeof option.yAxis === 'object' && !Array.isArray(option.yAxis)
+        ? option.yAxis
+        : {}
+
+    const seriesTemplates = Array.isArray(option.series) ? option.series : []
+    const broadcastTemplate = seriesTemplates[0] ?? {}
+
+    // Reactive (live store) formatters from ctx — distinct from the
+    // closure-time `formatter` / `labelFormatter` captured for the
+    // structural-build branch above. RelativeData can install a percent
+    // formatter on the store after the factory was constructed; the merge
+    // phase reads `ctx` to pick that up.
+    const liveFormatter = ctx?.formatter
+    const liveLabelFormatter = ctx?.labelFormatter
+
+    // Closure shared between the yAxis min/max callbacks and the label
+    // formatter, so only the rounded extents are labelled (matches v1).
+    // Delegating the extent to ECharts (rather than precomputing scalars
+    // from the raw data) is what keeps stacked bars inside the plot: when
+    // StackToggle marks the series, ECharts feeds the *post-stack* extent
+    // to these callbacks, so `niceNum` rounds the stacked total instead of
+    // a single series.
+    let niceMin = 0
+    let niceMax = 1
+
+    // Zoom slider layout: when ZoomToggle has installed `dataZoom`, push the
+    // slider above the legend (if any) and reserve room in the grid below.
+    const dataZoomLayout = positionDataZoomForLegend(option.dataZoom, hasLegend)
+    const fallbackBottom =
+      typeof baseGrid.bottom === 'number' ? baseGrid.bottom : 24
+    const baseBottom = hasLegend ? 56 : fallbackBottom
+    const gridBottom = dataZoomLayout
+      ? baseBottom + ZOOM_LAYOUT.sliderHeight + ZOOM_LAYOUT.sliderGap
+      : baseBottom
+
+    // When a selection is active, dim non-selected bars by routing the
+    // resolved palette color through `modifyAlpha`. Per-row `itemStyle` on
+    // dataset object-rows is silently ignored when `series.encode` is in
+    // play — the callback approach is the standard ECharts pattern for
+    // per-data styling derived from a dataset.
+    //
+    // We *always* emit `itemStyle.color` (a passthrough when nothing is
+    // selected), not conditionally — dropping the key between renders
+    // would let ECharts' default merge keep the previous callback alive
+    // and bars would stay dimmed forever after an external clear. Always
+    // emitting lets normal merge swap the callback in place, no
+    // `replaceMerge` and no entry-animation flash on selection on/off.
+    const dimItemStyle = {
+      color: (params: CallbackDataParams) => {
+        const base = params.color as string
+        if (!selectionSet) return base
+        const datum = params.value as { name?: string | number } | undefined
+        const name = datum?.name ?? params.name
+        return name != null && selectionSet.has(name)
+          ? base
+          : echarts.color.modifyAlpha(base, 0.15)
+      },
+    }
+
+    return {
+      ...option,
+      dataset: seriesArr.map((s) => ({ source: s as readonly object[] })),
+      series: seriesArr.map((_, i) => {
+        const template =
+          (seriesTemplates[i] as object | undefined) ??
+          (broadcastTemplate as object)
+        // Per-series `color` override: ECharts sets `params.color` from
+        // `series[i].color` when resolving styles, so the dim callback
+        // above keeps working — it just dims the user's colour rather
+        // than the palette default.
+        const overrideColor = resolveThemeColor(theme, series?.[i]?.color)
+        return {
+          ...(typeof template === 'object' ? template : {}),
+          type: 'bar' as const,
+          datasetIndex: i,
+          name: series?.[i]?.name ?? `Series ${i + 1}`,
+          encode: { x: 'name', y: 'value' },
+          barMaxWidth: 100,
+          emphasis: { focus: 'series' },
+          itemStyle: dimItemStyle,
+          ...(overrideColor ? { color: overrideColor } : {}),
+        }
+      }),
+      legend: { ...baseLegend, show: hasLegend },
+      grid: {
+        ...baseGrid,
+        bottom: gridBottom,
+      },
+      ...(dataZoomLayout ? { dataZoom: dataZoomLayout } : {}),
+      yAxis: {
+        ...baseYAxis,
+        min: (extent: { min: number }) => {
+          niceMin = extent.min < 0 ? niceNum(extent.min) : 0
+          return niceMin
+        },
+        max: (extent: { min: number; max: number }) => {
+          niceMax = extent.max <= 0 ? 1 : niceNum(extent.max)
+          return niceMax
+        },
+        axisLabel: {
+          ...((baseYAxis as { axisLabel?: object }).axisLabel ?? {}),
+          formatter: (value: number) => {
+            if (value !== niceMax && value !== niceMin) return ''
+            if (value === 0) return ''
+            return liveFormatter ? liveFormatter(value) : String(value)
+          },
+        },
+      } as EChartsOption['yAxis'],
+      tooltip: {
+        ...baseTooltip,
+        formatter: buildBarTooltipFormatter(liveFormatter, liveLabelFormatter),
+      },
+    } as EChartsOption
+  }
+}
+
+function buildBarTooltipFormatter(
+  formatter: ((value: number) => string) | undefined,
+  labelFormatter: ((value: string | number) => string | number) | undefined,
+) {
+  return createTooltipFormatter((item) => {
+    const row = item.value as { name?: string | number; value?: number }
+    const raw = row?.value
+    const formattedValue =
+      typeof raw === 'number' && formatter ? formatter(raw) : (raw ?? '')
+    const marker = typeof item.marker === 'string' ? item.marker : ''
+    const seriesName = item.seriesName ? `${item.seriesName}: ` : ''
+    const name = labelFormatter
+      ? String(labelFormatter(item.name ?? ''))
+      : (item.name ?? '')
+    return { name: String(name), seriesName, marker, value: formattedValue }
+  })
+}