@carto/ps-react-ui 4.11.1 → 4.11.2

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

@@ -208,7 +208,15 @@ export function createBarOptionFactory(
     const liveFormatter = ctx?.formatter
     const liveLabelFormatter = ctx?.labelFormatter
 
-    const { niceMinVal, niceMaxVal } = computeNiceBounds(seriesArr)
+    // 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.
@@ -276,12 +284,18 @@ export function createBarOptionFactory(
       ...(dataZoomLayout ? { dataZoom: dataZoomLayout } : {}),
       yAxis: {
         ...baseYAxis,
-        min: niceMinVal,
-        max: niceMaxVal,
+        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 !== niceMaxVal && value !== niceMinVal) return ''
+            if (value !== niceMax && value !== niceMin) return ''
             if (value === 0) return ''
             return liveFormatter ? liveFormatter(value) : String(value)
           },
@@ -312,21 +326,3 @@ function buildBarTooltipFormatter(
     return { name: String(name), seriesName, marker, value: formattedValue }
   })
 }
-
-function computeNiceBounds(seriesArr: BarWidgetData): {
-  niceMinVal: number
-  niceMaxVal: number
-} {
-  let min = 0
-  let max = -Infinity
-  for (const series of seriesArr) {
-    for (const d of series) {
-      if (typeof d?.value !== 'number' || !Number.isFinite(d.value)) continue
-      if (d.value < min) min = d.value
-      if (d.value > max) max = d.value
-    }
-  }
-  const niceMinVal = min < 0 ? niceNum(min) : 0
-  const niceMaxVal = max <= 0 ? 1 : niceNum(max)
-  return { niceMinVal, niceMaxVal }
-}

package/src/widgets-v2/echart/echart-ui.test.tsx

@@ -11,6 +11,11 @@ const mockChart = {
   resize: vi.fn(),
   on: vi.fn(),
   off: vi.fn(),
+  // Stubbed for the edge-label clamp; tests override per-case.
+  convertToPixel: vi.fn((_finder: unknown, index: number) =>
+    index === 0 ? 4 : 296,
+  ),
+  getWidth: vi.fn(() => 300),
 }
 const initSpy = vi.fn((...args: unknown[]): typeof mockChart => {
   void args
@@ -20,8 +25,20 @@ const initSpy = vi.fn((...args: unknown[]): typeof mockChart => {
 vi.mock('echarts', () => ({
   __esModule: true,
   init: (...args: unknown[]) => initSpy(...args),
+  // Fake text measurement: width ∝ character count, enough to make a long
+  // edge label overflow a near-edge tick in the clamp tests.
+  format: {
+    getTextRect: (text: unknown) => ({ width: String(text).length * 10 }),
+  },
 }))
 
+/** Invoke the `finished` listener the bridge bound on the mock chart. */
+function fireFinished(): void {
+  for (const [event, handler] of mockChart.on.mock.calls) {
+    if (event === 'finished') (handler as () => void)()
+  }
+}
+
 // Resize observer mock — capture the callback so tests can trigger it.
 let resizeCb: (() => void) | null = null
 const observeResizeSpy = vi.fn((_node: HTMLElement, cb: () => void) => {
@@ -43,11 +60,27 @@ beforeEach(() => {
   mockChart.resize.mockReset()
   mockChart.on.mockReset()
   mockChart.off.mockReset()
+  mockChart.convertToPixel.mockClear()
+  mockChart.getWidth.mockClear()
   initSpy.mockClear()
   observeResizeSpy.mockClear()
   resizeCb = null
 })
 
+const categoryOption = {
+  xAxis: { type: 'category', axisLabel: {} },
+  series: [{ type: 'bar', encode: { x: 'name', y: 'value' }, datasetIndex: 0 }],
+  dataset: [
+    {
+      source: [
+        { name: 'California', value: 3 },
+        { name: 'Texas', value: 2 },
+        { name: 'Wyoming', value: 1 },
+      ],
+    },
+  ],
+} as unknown as echarts.EChartsOption
+
 describe('<EchartUI>', () => {
   it('initialises echarts on mount with merged init opts and notifies onInstance', () => {
     const onInstance = vi.fn()
@@ -186,6 +219,43 @@ describe('<EchartUI>', () => {
     expect(mockChart.dispose).toHaveBeenCalledTimes(1)
   })
 
+  it('clamps overflowing edge labels on `finished` (category x-axis)', () => {
+    render(<EchartUI option={categoryOption} />)
+    mockChart.setOption.mockClear()
+    // First tick at x=4, 'California' ~100px wide (half 50) → overflows left.
+    act(() => fireFinished())
+    expect(mockChart.setOption).toHaveBeenCalledTimes(1)
+    const applied = mockChart.setOption.mock.calls[0]![0] as {
+      xAxis: { axisLabel: { alignMinLabel: string | null } }
+    }
+    expect(applied.xAxis.axisLabel.alignMinLabel).toBe('left')
+  })
+
+  it('does not clamp again on a second `finished` with the same verdict', () => {
+    render(<EchartUI option={categoryOption} />)
+    act(() => fireFinished())
+    mockChart.setOption.mockClear()
+    act(() => fireFinished())
+    expect(mockChart.setOption).not.toHaveBeenCalled()
+  })
+
+  it('does not clamp a non-category (time) x-axis', () => {
+    render(
+      <EchartUI
+        option={
+          {
+            xAxis: { type: 'time', axisLabel: {} },
+            series: [{ type: 'line', encode: { x: 'name', y: 'value' } }],
+            dataset: [{ source: [{ name: 1, value: 2 }] }],
+          } as unknown as echarts.EChartsOption
+        }
+      />,
+    )
+    mockChart.setOption.mockClear()
+    act(() => fireFinished())
+    expect(mockChart.setOption).not.toHaveBeenCalled()
+  })
+
   it('treats a non-array series as a single-fingerprint signature', () => {
     // The fingerprint helper handles both array AND object/single-series
     // forms. Re-render with a *fresh* option object that has the same

package/src/widgets-v2/echart/echart-ui.tsx

@@ -1,6 +1,11 @@
 import { useEffect, useEffectEvent, useRef } from 'react'
 import { Box, type SxProps, type Theme } from '@mui/material'
 import * as echarts from 'echarts'
+import {
+  clampEdgeLabels,
+  CENTERED,
+  type EdgeAlignment,
+} from './edge-label-clamp'
 import { observeResize } from './shared-resize-observer'
 import { styles } from './style'
 
@@ -70,6 +75,12 @@ export function EchartUI({
   const seriesFingerprintRef = useRef<string | null>(null)
   const datasetFingerprintRef = useRef<string | null>(null)
 
+  // Latest applied option (read by the `finished` clamp listener, which is
+  // bound once and must see the current option) + the edge-label alignment
+  // currently applied to the chart (so the clamp skips redundant setOptions).
+  const optionRef = useRef<echarts.EChartsOption>(option)
+  const edgeAlignRef = useRef<EdgeAlignment>(CENTERED)
+
   // Stable notify wrapper — always reads the latest `onInstance` prop
   // without forcing the init effect below to re-run when the parent
   // passes a fresh function reference. The init effect now only fires
@@ -89,7 +100,22 @@ export function EchartUI({
     })
     chartRef.current = chart
     notifyInstance(chart)
+    // Edge-label clamp: after each layout settles (option change OR resize both
+    // end in a render → `finished`), measure the category x-axis edge labels
+    // and anchor them inward only if they'd clip. `finished` (not rAF) so
+    // `convertToPixel` sees the flushed `lazyUpdate` layout. Loop-safe: the
+    // verdict is anchor-independent, so our own clamp setOption recomputes the
+    // same result and the ref guard short-circuits.
+    const onFinished = (): void => {
+      edgeAlignRef.current = clampEdgeLabels(
+        chart,
+        optionRef.current,
+        edgeAlignRef.current,
+      )
+    }
+    chart.on('finished', onFinished)
     return () => {
+      chart.off('finished', onFinished)
       // Notify observers *before* disposal so any queued imperative
       // dispatches (e.g. ZoomToggle's `setOption` cleanup) see the
       // instance disappear before its DOM is torn down.
@@ -108,6 +134,8 @@ export function EchartUI({
     if (datasetFp !== datasetFingerprintRef.current) augmented.add('dataset')
     seriesFingerprintRef.current = seriesFp
     datasetFingerprintRef.current = datasetFp
+    // Expose the latest option to the `finished` clamp listener (bound once).
+    optionRef.current = option
     chartRef.current?.setOption(option, {
       notMerge: false,
       lazyUpdate: true,

package/src/widgets-v2/echart/edge-label-clamp.test.ts

@@ -0,0 +1,198 @@
+import { describe, it, expect, vi } from 'vitest'
+import type { ECharts, EChartsOption } from 'echarts'
+import {
+  CENTERED,
+  clampEdgeLabels,
+  decideEdgeAlignment,
+  resolveEdgeLabels,
+} from './edge-label-clamp'
+
+const FONT = '12px sans-serif'
+
+describe('decideEdgeAlignment', () => {
+  // 'California' at 12px is ~50px wide → half ~25px. Tick offsets are chosen
+  // well below/above that so the verdict is robust to exact font metrics.
+  it("anchors 'left' when the first label overflows the left edge", () => {
+    const out = decideEdgeAlignment({
+      firstLabel: 'California',
+      lastLabel: 'X',
+      font: FONT,
+      firstTickX: 2,
+      lastTickX: 690,
+      width: 700,
+    })
+    expect(out.alignMinLabel).toBe('left')
+  })
+
+  it("anchors 'right' when the last label overflows the right edge", () => {
+    const out = decideEdgeAlignment({
+      firstLabel: 'X',
+      lastLabel: 'Wyoming',
+      font: FONT,
+      firstTickX: 350,
+      lastTickX: 698,
+      width: 700,
+    })
+    expect(out.alignMaxLabel).toBe('right')
+  })
+
+  it('leaves both centered (null) when the edge labels fit', () => {
+    const out = decideEdgeAlignment({
+      firstLabel: 'California',
+      lastLabel: 'Wyoming',
+      font: FONT,
+      firstTickX: 120,
+      lastTickX: 580,
+      width: 700,
+    })
+    expect(out).toEqual(CENTERED)
+  })
+})
+
+describe('resolveEdgeLabels', () => {
+  const barOption = (): EChartsOption =>
+    ({
+      xAxis: { type: 'category', axisLabel: {} },
+      series: [
+        { type: 'bar', encode: { x: 'name', y: 'value' }, datasetIndex: 0 },
+      ],
+      dataset: [
+        {
+          source: [
+            { name: 'California', value: 3 },
+            { name: 'Texas', value: 2 },
+            { name: 'Wyoming', value: 1 },
+          ],
+        },
+      ],
+    }) as unknown as EChartsOption
+
+  it('reads first/last category from the bar dataset via encode.x = name', () => {
+    const out = resolveEdgeLabels(barOption())
+    expect(out?.firstLabel).toBe('California')
+    expect(out?.lastLabel).toBe('Wyoming')
+    expect(out?.count).toBe(3)
+    expect(out?.font).toBe('12px sans-serif')
+  })
+
+  it('reads positional encode.x = 0 for the histogram tuple dataset', () => {
+    const out = resolveEdgeLabels({
+      xAxis: { type: 'category', axisLabel: {} },
+      series: [{ type: 'bar', encode: { x: 0, y: 1 }, datasetIndex: 0 }],
+      dataset: [
+        {
+          source: [
+            ['0–10', 5],
+            ['90–100', 2],
+          ],
+        },
+      ],
+    } as unknown as EChartsOption)
+    expect(out?.firstLabel).toBe('0–10')
+    expect(out?.lastLabel).toBe('90–100')
+  })
+
+  it('applies the axisLabel formatter to the category value', () => {
+    const opt = barOption() as unknown as {
+      xAxis: { axisLabel: { formatter: (v: string | number) => string } }
+    }
+    opt.xAxis.axisLabel.formatter = (v) => `[${v}]`
+    const out = resolveEdgeLabels(opt as unknown as EChartsOption)
+    expect(out?.firstLabel).toBe('[California]')
+  })
+
+  it('builds the font from axisLabel fontSize/fontFamily', () => {
+    const out = resolveEdgeLabels({
+      xAxis: {
+        type: 'category',
+        axisLabel: { fontSize: 10, fontFamily: 'Inter' },
+      },
+      series: [{ encode: { x: 'name' }, datasetIndex: 0 }],
+      dataset: [{ source: [{ name: 'A' }, { name: 'B' }] }],
+    } as unknown as EChartsOption)
+    expect(out?.font).toBe('10px Inter')
+  })
+
+  it('returns null for a non-category x-axis', () => {
+    expect(
+      resolveEdgeLabels({
+        xAxis: { type: 'value' },
+        series: [{ encode: { x: 'name' }, datasetIndex: 0 }],
+        dataset: [{ source: [{ name: 'A' }, { name: 'B' }] }],
+      } as unknown as EChartsOption),
+    ).toBeNull()
+  })
+
+  it('returns null with fewer than two categories', () => {
+    expect(resolveEdgeLabels(barOption2(['Solo']))).toBeNull()
+  })
+})
+
+function barOption2(names: string[]): EChartsOption {
+  return {
+    xAxis: { type: 'category', axisLabel: {} },
+    series: [{ encode: { x: 'name' }, datasetIndex: 0 }],
+    dataset: [{ source: names.map((name) => ({ name })) }],
+  } as unknown as EChartsOption
+}
+
+describe('clampEdgeLabels', () => {
+  const fakeChart = (firstTickX: number, lastTickX: number, width: number) => {
+    const setOption = vi.fn()
+    const chart = {
+      convertToPixel: (_finder: unknown, index: number) =>
+        index === 0 ? firstTickX : lastTickX,
+      getWidth: () => width,
+      setOption,
+    } as unknown as ECharts
+    return { chart, setOption }
+  }
+
+  const overflowOption = barOption2(['California', 'Texas', 'Wyoming'])
+
+  it('applies alignment via setOption when an edge overflows', () => {
+    const { chart, setOption } = fakeChart(2, 698, 700)
+    const result = clampEdgeLabels(chart, overflowOption, CENTERED)
+    expect(result.alignMinLabel).toBe('left')
+    expect(setOption).toHaveBeenCalledTimes(1)
+    const applied = setOption.mock.calls[0]![0] as {
+      xAxis: { axisLabel: { alignMinLabel: string | null } }
+    }
+    expect(applied.xAxis.axisLabel.alignMinLabel).toBe('left')
+  })
+
+  it('does not call setOption when the verdict matches the previous state', () => {
+    const { chart, setOption } = fakeChart(2, 698, 700)
+    const prev = {
+      alignMinLabel: 'left' as const,
+      alignMaxLabel: 'right' as const,
+    }
+    clampEdgeLabels(chart, overflowOption, prev)
+    expect(setOption).not.toHaveBeenCalled()
+  })
+
+  it('resets to centered under dataZoom (zoom guard) without measuring', () => {
+    const { chart, setOption } = fakeChart(2, 698, 700)
+    const zoomed = {
+      ...(overflowOption as object),
+      dataZoom: [{ type: 'slider' }],
+    } as unknown as EChartsOption
+    const prev = { alignMinLabel: 'left' as const, alignMaxLabel: null }
+    const result = clampEdgeLabels(chart, zoomed, prev)
+    expect(result).toEqual(CENTERED)
+    // Cleared the stale 'left' from before zoom.
+    expect(setOption).toHaveBeenCalledTimes(1)
+  })
+
+  it('leaves a non-category axis centered and untouched', () => {
+    const { chart, setOption } = fakeChart(2, 698, 700)
+    const valueAxis = {
+      xAxis: { type: 'value' },
+      series: [{ encode: { x: 'name' }, datasetIndex: 0 }],
+      dataset: [{ source: [{ name: 'A' }, { name: 'B' }] }],
+    } as unknown as EChartsOption
+    const result = clampEdgeLabels(chart, valueAxis, CENTERED)
+    expect(result).toEqual(CENTERED)
+    expect(setOption).not.toHaveBeenCalled()
+  })
+})

package/src/widgets-v2/echart/edge-label-clamp.ts

@@ -0,0 +1,216 @@
+import * as echarts from 'echarts'
+import type { ECharts, EChartsOption } from 'echarts'
+
+/**
+ * Render-time clamp that stops the first/last **category x-axis** labels from
+ * clipping at the chart edges — *only when they actually overflow*.
+ *
+ * ECharts centers each category label on its tick; the first/last ticks sit at
+ * the plot boundary, so a wide edge label spills past the chart and is cut off.
+ * `grid.containLabel` does not contain this horizontal overflow and the v6
+ * `outerBounds` shrink is unreliable, so we measure at render time and anchor
+ * the overflowing edge label inward (`alignMinLabel: 'left'` /
+ * `alignMaxLabel: 'right'`). Labels that fit stay centered.
+ *
+ * Lives in the generic bridge because the verdict needs the laid-out chart
+ * (`convertToPixel`, `getWidth`); everything else is read from the `option`.
+ * Auto-targets bar + histogram (category x-axis); pie's horizontal-bar fallback
+ * (category *y*-axis), scatterplot (value) and timeseries (time) are skipped.
+ */
+
+export interface EdgeAlignment {
+  alignMinLabel: 'left' | null
+  alignMaxLabel: 'right' | null
+}
+
+export const CENTERED: EdgeAlignment = {
+  alignMinLabel: null,
+  alignMaxLabel: null,
+}
+
+// Bias toward anchoring when borderline: clipping is worse than a hair of
+// off-centering, and the reconstructed font may differ slightly from what
+// ECharts actually renders.
+const SAFETY_MARGIN_PX = 2
+
+/**
+ * Pure overflow decision. Inputs are anchor-independent (tick centers and text
+ * width don't depend on the label's current `text-anchor`), so feeding the
+ * result back via `setOption` doesn't change them — the next pass yields the
+ * same verdict, keeping the clamp loop-stable.
+ */
+export function decideEdgeAlignment(args: {
+  firstLabel: string
+  lastLabel: string
+  font: string
+  firstTickX: number
+  lastTickX: number
+  width: number
+}): EdgeAlignment {
+  const halfFirst =
+    echarts.format.getTextRect(args.firstLabel, args.font).width / 2
+  const halfLast =
+    echarts.format.getTextRect(args.lastLabel, args.font).width / 2
+  return {
+    alignMinLabel:
+      halfFirst + SAFETY_MARGIN_PX > args.firstTickX ? 'left' : null,
+    alignMaxLabel:
+      halfLast + SAFETY_MARGIN_PX > args.width - args.lastTickX
+        ? 'right'
+        : null,
+  }
+}
+
+interface AxisLabel {
+  formatter?: (value: string | number) => string | number
+  fontSize?: number | string
+  fontFamily?: string
+  fontWeight?: number | string
+}
+
+interface CategoryXAxis {
+  type?: string
+  axisLabel?: AxisLabel
+}
+
+interface SeriesLike {
+  encode?: { x?: string | number }
+  datasetIndex?: number
+}
+
+type Cell = string | number | null | undefined
+
+function firstOf<T>(value: T | T[] | undefined): T | undefined {
+  if (Array.isArray(value)) return value[0]
+  return value
+}
+
+function firstXAxis(option: EChartsOption): CategoryXAxis | undefined {
+  const axis = firstOf(
+    option.xAxis as CategoryXAxis | CategoryXAxis[] | undefined,
+  )
+  return axis && typeof axis === 'object' ? axis : undefined
+}
+
+function hasDataZoom(option: EChartsOption): boolean {
+  const dz = option.dataZoom
+  return Array.isArray(dz) ? dz.length > 0 : dz != null
+}
+
+function cellToText(value: Cell, fmt: AxisLabel['formatter']): string {
+  if (typeof fmt === 'function') return String(fmt(value ?? ''))
+  return value == null ? '' : String(value)
+}
+
+/**
+ * Extracts the displayed first/last category strings and the label font from
+ * the option, reading categories generically via `series[0].encode.x` into the
+ * referenced dataset (`'name'` for bar, `0` for histogram). Returns `null` when
+ * the option isn't a measurable category x-axis (fewer than 2 categories, no
+ * dataset, etc.).
+ */
+export function resolveEdgeLabels(option: EChartsOption): {
+  firstLabel: string
+  lastLabel: string
+  font: string
+  count: number
+} | null {
+  const xAxis = firstXAxis(option)
+  if (!xAxis) return null
+  if (xAxis.type !== 'category') return null
+
+  const series0 = firstOf(
+    option.series as SeriesLike | SeriesLike[] | undefined,
+  )
+  const encodeX = series0?.encode?.x
+  if (encodeX == null) return null
+
+  const datasetIndex = series0?.datasetIndex ?? 0
+  const allDatasets = option.dataset as
+    | { source?: unknown }
+    | { source?: unknown }[]
+    | undefined
+  const dataset = Array.isArray(allDatasets)
+    ? allDatasets[datasetIndex]
+    : allDatasets
+  const source = dataset?.source
+  if (!Array.isArray(source) || source.length < 2) return null
+
+  const rows = source as Record<string | number, Cell>[]
+  const fmt = xAxis.axisLabel?.formatter
+  const axisLabel = xAxis.axisLabel ?? {}
+  const size =
+    typeof axisLabel.fontSize === 'number'
+      ? `${axisLabel.fontSize}px`
+      : (axisLabel.fontSize ?? '12px')
+  const family = axisLabel.fontFamily ?? 'sans-serif'
+  const weight = axisLabel.fontWeight != null ? `${axisLabel.fontWeight} ` : ''
+
+  return {
+    firstLabel: cellToText(rows[0]?.[encodeX], fmt),
+    lastLabel: cellToText(rows[rows.length - 1]?.[encodeX], fmt),
+    font: `${weight}${size} ${family}`,
+    count: source.length,
+  }
+}
+
+/**
+ * Measures the rendered chart and, when the edge labels would clip, applies
+ * `alignMinLabel`/`alignMaxLabel` (or clears them) via an imperative merge
+ * `setOption`. Returns the alignment now in effect so the caller can keep a
+ * `prev` ref and skip redundant `setOption`s. Should be invoked from the
+ * chart's `finished` event (layout is settled, so `convertToPixel` is valid).
+ */
+export function clampEdgeLabels(
+  chart: ECharts,
+  option: EChartsOption,
+  prev: EdgeAlignment,
+): EdgeAlignment {
+  const next = computeAlignment(chart, option)
+  if (
+    next.alignMinLabel === prev.alignMinLabel &&
+    next.alignMaxLabel === prev.alignMaxLabel
+  ) {
+    return prev
+  }
+  chart.setOption({ xAxis: { axisLabel: { ...next } } } as EChartsOption, {
+    lazyUpdate: true,
+  })
+  return next
+}
+
+function computeAlignment(
+  chart: ECharts,
+  option: EChartsOption,
+): EdgeAlignment {
+  // Under dataZoom, convertToPixel on the absolute first/last index returns
+  // off-plot pixels, so the overflow math is invalid — reset to centered.
+  if (hasDataZoom(option)) return CENTERED
+
+  const labels = resolveEdgeLabels(option)
+  if (!labels) return CENTERED
+
+  const firstTickX = chart.convertToPixel({ xAxisIndex: 0 }, 0)
+  const lastTickX = chart.convertToPixel({ xAxisIndex: 0 }, labels.count - 1)
+  const width = chart.getWidth()
+  // Layout not measurable yet (defensive — `finished` normally fires after
+  // layout). Fall back to centered; a later `finished` re-measures.
+  if (
+    typeof firstTickX !== 'number' ||
+    typeof lastTickX !== 'number' ||
+    !Number.isFinite(firstTickX) ||
+    !Number.isFinite(lastTickX) ||
+    !width
+  ) {
+    return CENTERED
+  }
+
+  return decideEdgeAlignment({
+    firstLabel: labels.firstLabel,
+    lastLabel: labels.lastLabel,
+    font: labels.font,
+    firstTickX,
+    lastTickX,
+    width,
+  })
+}

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

@@ -203,14 +203,21 @@ describe('createHistogramOptionFactory (data → dataset merger)', () => {
     expect(typeof out.tooltip?.formatter).toBe('function')
   })
 
-  it('resolves y-axis min/max to concrete niceNum bounds after fusion', () => {
+  it('resolves y-axis min/max via niceNum callbacks after fusion', () => {
     const merge = createHistogramOptionFactory({ theme, ticks: [0, 10, 20] })
     const out = merge({}, [[3, 47]]) as {
-      yAxis: { min?: number; max?: number }
+      yAxis: {
+        min: (extent: { min: number }) => number
+        max: (extent: { min: number; max: number }) => number
+      }
     }
-    expect(out.yAxis.min).toBe(0)
+    // Bounds are callbacks: ECharts supplies the (post-stack) extent and we
+    // round it with niceNum, so stacked bins can't overflow the axis.
+    expect(typeof out.yAxis.min).toBe('function')
+    expect(typeof out.yAxis.max).toBe('function')
+    expect(out.yAxis.min({ min: 0 })).toBe(0)
     // 47 → niceNum → 50 (Math.ceil(47 / 10) * 10)
-    expect(out.yAxis.max).toBe(50)
+    expect(out.yAxis.max({ min: 0, max: 47 })).toBe(50)
   })
 
   it('uses series[i].name for series[i].name when provided', () => {