@carto/ps-react-ui 4.25.0 → 4.27.0

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

@@ -12,6 +12,7 @@ import {
 import { ZOOM_LAYOUT } from '../actions/zoom-toggle'
 import type { OptionFactory } from '../echart'
 import { mergeOptions, resolveThemeColor } from '../utils'
+import { createItemColorResolver } from '../utils/item-color'
 import { positionDataZoomForLegend } from '../utils/data-zoom-layout'
 import type {
   BarEChartsOption,
@@ -19,6 +20,7 @@ import type {
   BarOptionsInput,
   BarWidgetData,
 } from './types'
+import { fixedAxisBounds } from '../actions/relative-data/scale'
 
 /**
  * Builds the **structural** ECharts option for a bar widget — axes, grid,
@@ -201,6 +203,7 @@ export function createBarOptionFactory(
       typeof option.yAxis === 'object' && !Array.isArray(option.yAxis)
         ? option.yAxis
         : {}
+    const fixedY = fixedAxisBounds(baseYAxis)
 
     const seriesTemplates = Array.isArray(option.series) ? option.series : []
     const broadcastTemplate = seriesTemplates[0] ?? {}
@@ -234,10 +237,12 @@ export function createBarOptionFactory(
       : baseBottom
 
     // When a selection is active, dim non-selected bars by routing the
-    // resolved palette color through `modifyAlpha`. Per-row `itemStyle` on
+    // item's base colour 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.
+    // per-data styling derived from a dataset. The base colour is the
+    // datum's `color`, else the template's `itemStyle.color`, else the
+    // series colour / palette (`params.color`).
     //
     // We *always* emit `itemStyle.color` (a passthrough when nothing is
     // selected), not conditionally — dropping the key between renders
@@ -245,22 +250,30 @@ export function createBarOptionFactory(
     // 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)
-      },
+    const makeDimItemStyle = (datums: readonly object[], template: unknown) => {
+      const baseColor = createItemColorResolver({
+        theme,
+        datums,
+        template,
+        fallback: (params) => params.color as string,
+      })
+      return {
+        color: (params: CallbackDataParams) => {
+          const base = baseColor(params)
+          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) => {
+      series: seriesArr.map((s, i) => {
         const template =
           (seriesTemplates[i] as object | undefined) ??
           (broadcastTemplate as object)
@@ -277,7 +290,7 @@ export function createBarOptionFactory(
           encode: { x: 'name', y: 'value' },
           barMaxWidth: 100,
           emphasis: { focus: 'series' },
-          itemStyle: dimItemStyle,
+          itemStyle: makeDimItemStyle(s, template),
           ...(overrideColor ? { color: overrideColor } : {}),
         }
       }),
@@ -289,12 +302,14 @@ export function createBarOptionFactory(
       ...(dataZoomLayout ? { dataZoom: dataZoomLayout } : {}),
       yAxis: {
         ...baseYAxis,
+        // A config transform (RelativeData's `'total'` scale) may pin the
+        // ends; each applies only on the side the data reaches.
         min: (extent: { min: number }) => {
-          niceMin = extent.min < 0 ? niceNum(extent.min) : 0
+          niceMin = extent.min < 0 ? (fixedY.min ?? niceNum(extent.min)) : 0
           return niceMin
         },
         max: (extent: { min: number; max: number }) => {
-          niceMax = extent.max <= 0 ? 1 : niceNum(extent.max)
+          niceMax = extent.max <= 0 ? 1 : (fixedY.max ?? niceNum(extent.max))
           return niceMax
         },
         axisLabel: {

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

@@ -6,6 +6,12 @@ import type { WidgetSeries } from '../types'
 export interface BarDatum {
   name: string | number
   value: number
+  /**
+   * Optional colour for this item (CSS colour or theme palette path such as
+   * `'primary.main'`). Wins over the template's `itemStyle.color` and the
+   * series colour; selection dimming still applies on top.
+   */
+  color?: string
 }
 
 /** v2 bar widget data shape: array of series, each a flat list of `{name, value}`. */

package/src/widgets-v2/category/category.relative-data.test.tsx

@@ -1,11 +1,7 @@
 import { describe, it, expect, beforeEach, afterEach } from 'vitest'
 import { fireEvent, render, screen } from '@testing-library/react'
 import { Provider } from '../provider/widget-provider'
-import {
-  clearAllWidgetStores,
-  useTransformEnabled,
-  useWidgetId,
-} from '../stores'
+import { clearAllWidgetStores, getWidgetStore } from '../stores'
 import { Category } from './category'
 import { RelativeData } from '../actions/relative-data/relative-data'
 import type { CategoryWidgetData } from './types'
@@ -13,21 +9,7 @@ import type { CategoryWidgetData } from './types'
 beforeEach(() => clearAllWidgetStores())
 afterEach(() => clearAllWidgetStores())
 
-// Replicates `CategoryActionWiring` from the storybook composer
-// (apps/storybook/stories/modules/widgets/category/category.tsx). The
-// composer-level wiring isn't testable in `apps/storybook` (no vitest
-// infra), so we re-implement just the relative-data branch here and
-// assert the bar-width math end-to-end through Provider → action →
-// bridge → UI.
-function Wired({ maxOverride }: { maxOverride?: number }) {
-  const id = useWidgetId()
-  const relativeDataActive = useTransformEnabled(id, 'relative-data')
-  const effectiveMaxOverride = relativeDataActive ? 100 : maxOverride
-  return <Category maxOverride={effectiveMaxOverride} />
-}
-
-// Single-series dataset where the max value is 1000 so percent values
-// map to round numbers we can match exactly against bar widths.
+// Single series: shares of the 1750 total are ≈57.14 / 28.57 / 14.29.
 const DATA: CategoryWidgetData = [
   [
     { name: 'A', value: 1000 },
@@ -36,72 +18,78 @@ const DATA: CategoryWidgetData = [
   ],
 ]
 
-function getBarFills(): HTMLElement[] {
+function widths(): number[] {
   return Array.from(
     document.querySelectorAll<HTMLElement>('[data-bar-fill="true"]'),
-  )
+  ).map((el) => parseFloat(el.style.width))
 }
 
-describe('Category + RelativeData composer wiring', () => {
-  it('default (RelativeData off) → bars scale to data max', () => {
+const toggle = () =>
+  fireEvent.click(screen.getByRole('button', { name: /show relative values/i }))
+
+describe('Category + RelativeData', () => {
+  it('off → bars scale to the data max', () => {
     render(
       <Provider id='cat-rd-off' data={DATA}>
         <RelativeData />
-        <Wired />
+        <Category />
       </Provider>,
     )
-    const fills = getBarFills()
-    expect(fills).toHaveLength(3)
-    // 1000/1000, 500/1000, 250/1000
-    expect(fills[0]!.style.width).toBe('100%')
-    expect(fills[1]!.style.width).toBe('50%')
-    expect(fills[2]!.style.width).toBe('25%')
+    expect(widths()).toEqual([100, 50, 25])
   })
 
-  it('clicking the % action flips bars to a 100-denominator', () => {
+  it("scale 'max' (default): values are shares of the total, the top bar fills", () => {
     render(
-      <Provider id='cat-rd-toggle' data={DATA}>
+      <Provider id='cat-rd-max' data={DATA}>
         <RelativeData />
-        <Wired />
+        <Category />
+      </Provider>,
+    )
+    toggle()
+    const values = (
+      getWidgetStore('cat-rd-max').getState().data as CategoryWidgetData
+    )[0]!.map((d) => d.value)
+    expect(values[0]).toBeCloseTo(57.14, 2)
+    const [a, b, c] = widths()
+    expect(a).toBeCloseTo(100)
+    expect(b).toBeCloseTo(50)
+    expect(c).toBeCloseTo(25)
+  })
+
+  it("scale 'total': bars end at 100%", () => {
+    render(
+      <Provider id='cat-rd-total' data={DATA}>
+        <RelativeData scale='total' />
+        <Category />
       </Provider>,
     )
-    // Toggle ON. RelativeData rewrites data values into percentages
-    // (A=1000/1750 ≈ 57.14, B=500/1750 ≈ 28.57, C=250/1750 ≈ 14.29) AND
-    // the composer wiring forces maxOverride=100 so the bar widths
-    // match those percent values directly.
-    fireEvent.click(screen.getByRole('button', { name: /relative|percent/i }))
-    const fills = getBarFills()
-    expect(fills).toHaveLength(3)
-    // Allow a small rounding tolerance — the percent transform produces
-    // floats, the bar math multiplies by 100 again.
-    const a = parseFloat(fills[0]!.style.width)
-    const b = parseFloat(fills[1]!.style.width)
-    const c = parseFloat(fills[2]!.style.width)
-    expect(a).toBeGreaterThan(55)
-    expect(a).toBeLessThan(60)
-    expect(b).toBeGreaterThan(27)
-    expect(b).toBeLessThan(30)
-    expect(c).toBeGreaterThan(13)
-    expect(c).toBeLessThan(16)
-    // The largest bar must be NOT 100% — that's the whole point of the
-    // fix. Without the wiring, A would have been 100% (largest of the
-    // percent series).
-    expect(a).toBeLessThan(100)
+    toggle()
+    const [a, b, c] = widths()
+    expect(a).toBeCloseTo(57.14, 1)
+    expect(b).toBeCloseTo(28.57, 1)
+    expect(c).toBeCloseTo(14.29, 1)
+  })
+
+  it('ignores maxOverride while relative is on (legacy ±100 wiring)', () => {
+    render(
+      <Provider id='cat-rd-legacy' data={DATA}>
+        <RelativeData initialEnabled />
+        <Category maxOverride={100} minOverride={-100} />
+      </Provider>,
+    )
+    expect(widths()[0]).toBeCloseTo(100)
   })
 
   it('toggling off again restores data-max scaling', () => {
     render(
       <Provider id='cat-rd-restore' data={DATA}>
-        <RelativeData />
-        <Wired />
+        <RelativeData scale='total' />
+        <Category />
       </Provider>,
     )
-    const button = screen.getByRole('button', { name: /relative|percent/i })
+    const button = screen.getByRole('button', { name: /show relative values/i })
     fireEvent.click(button) // on
     fireEvent.click(button) // off
-    const fills = getBarFills()
-    expect(fills[0]!.style.width).toBe('100%')
-    expect(fills[1]!.style.width).toBe('50%')
-    expect(fills[2]!.style.width).toBe('25%')
+    expect(widths()).toEqual([100, 50, 25])
   })
 })

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

@@ -6,6 +6,7 @@ import {
   useWidgetShallow,
   type WidgetState,
 } from '../stores'
+import { selectRelativeScale } from '../actions/relative-data/scale'
 import { CategoryUI } from './category-ui'
 import type {
   CategoryKey,
@@ -87,7 +88,8 @@ export interface CategoryProps {
    * stay coherent across data transforms (e.g., the Searcher filtering
    * rows in and out — bars don't rescale just because the larger rows
    * got hidden). Pass an explicit number to fix the denominator
-   * regardless of the data.
+   * regardless of the data. Ignored while `RelativeData` is on, whose
+   * `scale` decides the denominator instead.
    */
   maxOverride?: number
   /**
@@ -134,18 +136,30 @@ export function Category({
   // Auto-fill both ends of the scale from `rawData` so bar widths and the
   // zero stay coherent across data transforms (e.g., the Searcher filtering
   // rows in/out). Consumer's explicit value wins, but each end only applies
-  // when `rawData` reaches past zero on that side: a relative-data wiring can
-  // then pass `100` / `-100` unconditionally and positive-only data keeps its
-  // zero at the left edge, negative-only at the right. With no data on a side
-  // we pass nothing and CategoryUI falls back to the live `data`.
-  const [naturalMin, naturalMax] = useMemo(
-    () => extentFromCategoryData(slice.rawData),
-    [slice.rawData],
-  )
+  // when the data reaches past zero on that side, so positive-only data
+  // keeps its zero at the left edge, negative-only at the right. With no
+  // data on a side we pass nothing and CategoryUI falls back to the live
+  // `data`.
+  // With RelativeData on, the values are percentages: `'total'` ends the
+  // scale at ±100, `'max'` at the largest share so the top row fills.
+  const relativeScale = useWidget(id, selectRelativeScale)
+  const [naturalMin, naturalMax] = useMemo(() => {
+    const [min, max] = extentFromCategoryData(slice.rawData)
+    if (relativeScale === 'total')
+      return [min < 0 ? -100 : 0, max > 0 ? 100 : 0]
+    if (relativeScale === 'max') return extentFromCategoryData(slice.data)
+    return [min, max]
+  }, [slice.rawData, slice.data, relativeScale])
+  // The overrides are in absolute units, so they sit out while relative
+  // values are on.
   const effectiveMaxOverride =
-    naturalMax > 0 ? (maxOverride ?? naturalMax) : undefined
+    naturalMax > 0
+      ? ((relativeScale ? undefined : maxOverride) ?? naturalMax)
+      : undefined
   const effectiveMinOverride =
-    naturalMin < 0 ? (minOverride ?? naturalMin) : undefined
+    naturalMin < 0
+      ? ((relativeScale ? undefined : minOverride) ?? naturalMin)
+      : undefined
 
   const seriesKey = JSON.stringify(series?.map((s) => s.name) ?? [])
   const stored = useWidget<

package/src/widgets-v2/histogram/bins.ts

@@ -0,0 +1,22 @@
+import type { HistogramBin } from './types'
+
+/** Count of a {@link HistogramBin}, whichever form it takes. */
+export function getHistogramBinValue(bin: HistogramBin): number {
+  return typeof bin === 'number' ? bin : bin.value
+}
+
+/** Whether `v` is a valid {@link HistogramBin} with a finite count. */
+export function isHistogramBin(v: unknown): v is HistogramBin {
+  if (typeof v === 'number') return Number.isFinite(v)
+  if (v == null || typeof v !== 'object') return false
+  const value = (v as { value?: unknown }).value
+  return typeof value === 'number' && Number.isFinite(value)
+}
+
+/** Same bin with its count replaced; keeps the object form (and `color`). */
+export function withHistogramBinValue(
+  bin: HistogramBin,
+  value: number,
+): HistogramBin {
+  return typeof bin === 'number' ? value : { ...bin, value }
+}

package/src/widgets-v2/histogram/download.test.ts

@@ -61,6 +61,16 @@ describe('createHistogramDownloadConfig', () => {
     )
   })
 
+  it('CSV writes the count of object bins (colour is not exported)', async () => {
+    const items = createHistogramDownloadConfig({
+      filename: 'h',
+      getData: () => [[{ value: 1, color: '#f00' }, 2, { value: 3 }]],
+      getTicks: () => ticks,
+    })
+    await items.find((i) => i.id === 'csv')!.resolve({ id: null })
+    expect(csvText).toBe('bin_low,bin_high,series_1\n0,10,1\n10,20,2\n20,30,3')
+  })
+
   it('CSV honours supplied seriesNames', async () => {
     const items = createHistogramDownloadConfig({
       filename: 'h',

package/src/widgets-v2/histogram/download.ts

@@ -4,7 +4,8 @@ import {
   type DownloadContext,
   type DownloadItem,
 } from '../actions/download'
-import type { HistogramWidgetData } from './types'
+import { getHistogramBinValue } from './bins'
+import type { HistogramBin, HistogramWidgetData } from './types'
 
 /**
  * Download menu items for histograms. Always includes a CSV item with
@@ -14,7 +15,7 @@ import type { HistogramWidgetData } from './types'
  */
 export function createHistogramDownloadConfig(args: {
   filename: string
-  getData: (ctx: DownloadContext) => HistogramWidgetData
+  getData: (ctx: DownloadContext) => HistogramWidgetData<HistogramBin>
   getTicks: () => readonly number[]
   seriesNames?: readonly string[]
   getCaptureEl?: (ctx: DownloadContext) => HTMLElement | null
@@ -46,7 +47,10 @@ export function createHistogramDownloadConfig(args: {
         const rows: unknown[][] = [header]
         for (let bin = 0; bin < Math.max(0, ticks.length - 1); bin++) {
           const row: unknown[] = [ticks[bin], ticks[bin + 1]]
-          for (let s = 0; s < seriesCount; s++) row.push(data[s]?.[bin] ?? 0)
+          for (let s = 0; s < seriesCount; s++) {
+            const value = data[s]?.[bin]
+            row.push(value == null ? 0 : getHistogramBinValue(value))
+          }
           rows.push(row)
         }
         return rows

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

@@ -5,7 +5,10 @@ export {
   toRelativeHistogramData,
   filterHistogramByLockedBins,
 } from './transforms'
+export { getHistogramBinValue } from './bins'
 export type {
+  HistogramBin,
+  HistogramBinObject,
   HistogramWidgetData,
   HistogramOptionsInput,
   HistogramOptionFactoryInput,

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

@@ -1,4 +1,5 @@
 import { describe, it, expect } from 'vitest'
+import * as echarts from 'echarts'
 import { createTheme, type Theme } from '@mui/material'
 import { createHistogramOptionFactory, histogramOptions } from './options'
 
@@ -409,3 +410,64 @@ describe('createHistogramOptionFactory (data → dataset merger)', () => {
     })
   })
 })
+
+describe('createHistogramOptionFactory — per-item colour', () => {
+  interface Out {
+    dataset: { source: (string | number)[][] }[]
+    series: { itemStyle: { color: (p: unknown) => string } }[]
+  }
+  const ticks = [0, 10, 20, 30]
+  const dim = (c: string) => echarts.color.modifyAlpha(c, 0.15)
+
+  it('accepts object bins: dataset carries the counts', () => {
+    const merge = createHistogramOptionFactory({ theme, ticks })
+    const out = merge({}, [[{ value: 1, color: '#00ff00' }, 2, { value: 3 }]])
+    expect((out as Out).dataset[0]!.source.map(([, v]) => v)).toEqual([1, 2, 3])
+  })
+
+  it('bin colour wins over the series colour; template next', () => {
+    const merge = createHistogramOptionFactory({
+      theme,
+      ticks,
+      series: [{ name: 'S', color: '#0000ff' }],
+      selection: [0, 1],
+    })
+    const out = merge(
+      { series: [{ type: 'bar', itemStyle: { color: '#123456' } }] },
+      [[{ value: 1, color: '#00ff00' }, 2, { value: 3 }]],
+    ) as Out
+    const colorFn = out.series[0]!.itemStyle.color
+    expect(colorFn({ dataIndex: 0, color: '#0000ff' })).toBe('#00ff00')
+    expect(colorFn({ dataIndex: 1, color: '#0000ff' })).toBe('#123456')
+    expect(colorFn({ dataIndex: 2, color: '#0000ff' })).toBe(dim('#123456'))
+  })
+
+  it('calls a function template itemStyle.color via optionsOverride', () => {
+    const factory = createHistogramOptionFactory({
+      theme,
+      ticks,
+      optionsOverride: {
+        series: [
+          {
+            type: 'bar',
+            itemStyle: {
+              color: (p: { dataIndex: number }) => `#c${p.dataIndex}`,
+            },
+          },
+        ],
+      },
+    })
+    const out = factory(factory(undefined, undefined), [[1, 2, 3]]) as Out
+    expect(out.series[0]!.itemStyle.color({ dataIndex: 2, color: '#x' })).toBe(
+      '#c2',
+    )
+  })
+
+  it('keeps the series / palette colour for plain number bins', () => {
+    const merge = createHistogramOptionFactory({ theme, ticks, selection: [1] })
+    const out = merge({}, [[1, 2, 3]]) as Out
+    const colorFn = out.series[0]!.itemStyle.color
+    expect(colorFn({ dataIndex: 0, color: '#abcdef' })).toBe(dim('#abcdef'))
+    expect(colorFn({ dataIndex: 1, color: '#abcdef' })).toBe('#abcdef')
+  })
+})

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

@@ -12,13 +12,17 @@ import {
 import { ZOOM_LAYOUT } from '../actions/zoom-toggle'
 import type { OptionFactory } from '../echart'
 import { mergeOptions, resolveThemeColor } from '../utils'
+import { createItemColorResolver } from '../utils/item-color'
+import { getHistogramBinValue } from './bins'
 import { positionDataZoomForLegend } from '../utils/data-zoom-layout'
 import type {
   HistogramEChartsOption,
   HistogramOptionFactoryInput,
   HistogramOptionsInput,
+  HistogramBin,
   HistogramWidgetData,
 } from './types'
+import { fixedAxisBounds } from '../actions/relative-data/scale'
 
 /**
  * Builds the **structural** ECharts option for a histogram widget — axes,
@@ -147,7 +151,7 @@ export function histogramOptions({
  *     the consumer-supplied `optionsOverride`. Called once by Provider to
  *     seed `rawOptions` in the store.
  *   - **Merge phase** (`option != null`) — fuses post-pipeline `state.data`
- *     (`HistogramWidgetData` — `number[][]`) into the option via the
+ *     (`HistogramWidgetData` — `HistogramBin[][]`) into the option via the
  *     dataset API. Each series gets its own dataset of `[binLabel, count]`
  *     pairs derived from `ticks`; series reference their dataset by
  *     `datasetIndex` and are encoded by column position. Reactive
@@ -199,8 +203,8 @@ export function createHistogramOptionFactory(
         : structural
     }
 
-    const seriesArr: HistogramWidgetData = Array.isArray(data)
-      ? (data as HistogramWidgetData)
+    const seriesArr: HistogramWidgetData<HistogramBin> = Array.isArray(data)
+      ? (data as HistogramWidgetData<HistogramBin>)
       : []
     if (seriesArr.length === 0 || binLabels.length === 0) {
       return { ...option, dataset: [], series: [] }
@@ -213,6 +217,7 @@ export function createHistogramOptionFactory(
       typeof option.yAxis === 'object' && !Array.isArray(option.yAxis)
         ? option.yAxis
         : {}
+    const fixedY = fixedAxisBounds(baseYAxis)
     const baseGrid =
       typeof option.grid === 'object' && !Array.isArray(option.grid)
         ? option.grid
@@ -261,14 +266,28 @@ export function createHistogramOptionFactory(
     // and bins 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
-        return selectionSet.has(params.dataIndex)
-          ? base
-          : echarts.color.modifyAlpha(base, 0.15)
-      },
+    //
+    // The base colour is the bin's own `color` (object bins), else the
+    // template's `itemStyle.color`, else the series colour / palette.
+    const makeDimItemStyle = (
+      datums: readonly unknown[],
+      template: unknown,
+    ) => {
+      const baseColor = createItemColorResolver({
+        theme,
+        datums,
+        template,
+        fallback: (params) => params.color as string,
+      })
+      return {
+        color: (params: CallbackDataParams) => {
+          const base = baseColor(params)
+          if (!selectionSet) return base
+          return selectionSet.has(params.dataIndex)
+            ? base
+            : echarts.color.modifyAlpha(base, 0.15)
+        },
+      }
     }
 
     // A consumer's `optionsOverride.xAxis` may legitimately be an array
@@ -306,12 +325,16 @@ export function createHistogramOptionFactory(
     return {
       ...option,
       xAxis: nextXAxis,
-      dataset: seriesArr.map((counts) => ({
-        source: binLabels.map(
-          (label, i) => [label, counts[i] ?? 0] as [string, number],
-        ),
+      dataset: seriesArr.map((bins) => ({
+        source: binLabels.map((label, i) => {
+          const bin = bins[i]
+          return [label, bin == null ? 0 : getHistogramBinValue(bin)] as [
+            string,
+            number,
+          ]
+        }),
       })),
-      series: seriesArr.map((_, i) => {
+      series: seriesArr.map((bins, i) => {
         const template =
           (seriesTemplates[i] as object | undefined) ??
           (broadcastTemplate as object)
@@ -324,7 +347,7 @@ export function createHistogramOptionFactory(
           encode: { x: 0, y: 1 },
           barCategoryGap: '0%',
           emphasis: { focus: 'series' },
-          itemStyle: dimItemStyle,
+          itemStyle: makeDimItemStyle(bins, template),
           ...(overrideColor ? { color: overrideColor } : {}),
         }
       }),
@@ -333,12 +356,14 @@ export function createHistogramOptionFactory(
       ...(dataZoomLayout ? { dataZoom: dataZoomLayout } : {}),
       yAxis: {
         ...baseYAxis,
+        // A config transform (RelativeData's `'total'` scale) may pin the
+        // ends; each applies only on the side the data reaches.
         min: (extent: { min: number }) => {
-          niceMin = extent.min < 0 ? niceNum(extent.min) : 0
+          niceMin = extent.min < 0 ? (fixedY.min ?? niceNum(extent.min)) : 0
           return niceMin
         },
         max: (extent: { min: number; max: number }) => {
-          niceMax = extent.max <= 0 ? 1 : niceNum(extent.max)
+          niceMax = extent.max <= 0 ? 1 : (fixedY.max ?? niceNum(extent.max))
           return niceMax
         },
         axisLabel: {