@carto/ps-react-ui 4.17.2 → 4.18.0

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

@@ -281,6 +281,48 @@ export function CategoryUI({
     [scrollMode],
   )
 
+  // Which series are hidden via a legend click. Local UI-only state — not
+  // synced to `selection`/`onSelectionChange` (that's row-level filter
+  // selection, unrelated). Never allowed to reach "every series hidden":
+  // toggling the last visible one instead resets to "all visible" rather
+  // than leaving the widget blank.
+  const [hiddenSeries, setHiddenSeries] = useState<ReadonlySet<number>>(
+    () => new Set(),
+  )
+  // A reload with a different series breakdown invalidates hidden indices —
+  // index 2 may now point at an entirely different series. Reset rather
+  // than keep hiding whatever now occupies a stale index. Adjusted directly
+  // during render (React's documented "adjusting state when a prop changes"
+  // pattern) instead of in a `useEffect`, which would commit the stale
+  // hidden-set for one extra frame before the effect fires. Compared by a
+  // content-derived key, not the raw `series` reference — an inline
+  // `series={[...]}` literal (no useMemo) gets a new reference on every
+  // unrelated parent re-render, which would otherwise reset hiddenSeries
+  // right after the user hides one.
+  const seriesKey = JSON.stringify(series?.map((s) => s.name) ?? [])
+  const [prevSeriesKey, setPrevSeriesKey] = useState(seriesKey)
+  if (seriesKey !== prevSeriesKey) {
+    setPrevSeriesKey(seriesKey)
+    setHiddenSeries(new Set())
+  }
+  // Real number of data series — NOT `series?.length`, which is legend
+  // metadata and may legitimately be shorter than the actual series count
+  // (unnamed trailing series fall back to `Series N`). Using the metadata
+  // length here would trip the "never fully hidden" guard early whenever
+  // `series` is shorter than `data`.
+  const seriesCount = Math.max(data.length, 1)
+  const toggleSeries = useCallback(
+    (index: number) => {
+      setHiddenSeries((prev) => {
+        const next = new Set(prev)
+        if (next.has(index)) next.delete(index)
+        else next.add(index)
+        return next.size >= seriesCount ? new Set() : next
+      })
+    },
+    [seriesCount],
+  )
+
   if (grouped.length === 0) return null
 
   const hasCap =
@@ -290,6 +332,12 @@ export function CategoryUI({
 
   const isMulti = data.length > 1
   const hasLegend = isMulti && !!series && series.length > 0
+  // Invariant across every row in this render — only depends on
+  // `hiddenSeries`/`seriesCount`, not on any particular row's data — so
+  // it's computed once here instead of per row inside the render loop.
+  const visibleIdx = Array.from({ length: seriesCount }, (_, i) => i).filter(
+    (i) => !hiddenSeries.has(i),
+  )
 
   // Fallback viewport height matches the documented "8 × ROW_HEIGHT_PX"
   // (see the constants at the top of the file). Earlier code multiplied
@@ -323,6 +371,10 @@ export function CategoryUI({
           // rows — no row-level opacity, no `rowSelected` bg tint.
           const fill = (i: number): string =>
             dimmed ? dimColor : colorAt(i, row.rowColors[i])
+          // Series hidden via the legend are dropped before reaching the
+          // row components — they render whatever arrays they're given
+          // with no notion of "hidden" themselves. `visibleIdx` is hoisted
+          // above this loop (same for every row).
           if (isMulti) {
             if (stacked) {
               // Stacked-mode branch: one segmented bar per row. Toggling
@@ -341,9 +393,11 @@ export function CategoryUI({
                   key={String(row.name)}
                   name={row.name}
                   displayName={displayName}
-                  values={row.values}
-                  colors={row.values.map((_, i) => fill(i))}
-                  seriesNames={series?.map((s) => s.name) ?? []}
+                  values={visibleIdx.map((i) => row.values[i]!)}
+                  colors={visibleIdx.map((i) => fill(i))}
+                  seriesNames={visibleIdx.map(
+                    (i) => series?.[i]?.name ?? `Series ${i + 1}`,
+                  )}
                   formatter={fmt}
                   selected={selected}
                   onToggle={toggle}
@@ -356,8 +410,8 @@ export function CategoryUI({
                 key={String(row.name)}
                 name={row.name}
                 displayName={displayName}
-                values={row.values}
-                colors={row.values.map((_, i) => fill(i))}
+                values={visibleIdx.map((i) => row.values[i]!)}
+                colors={visibleIdx.map((i) => fill(i))}
                 maxValue={maxValue}
                 formatter={fmt}
                 selected={selected}
@@ -392,7 +446,12 @@ export function CategoryUI({
         )}
       </Box>
       {hasLegend && series && (
-        <CategoryLegend series={series} colorAt={(i) => colorAt(i)} />
+        <CategoryLegend
+          series={series}
+          colorAt={(i) => colorAt(i)}
+          hiddenSeries={hiddenSeries}
+          onToggle={toggleSeries}
+        />
       )}
     </Box>
   )

package/src/widgets-v2/category/components/category-legend.test.tsx

@@ -1,13 +1,21 @@
-import { describe, it, expect } from 'vitest'
+import { describe, it, expect, vi } from 'vitest'
 import { render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
 import { CategoryLegend } from './category-legend'
 
 const noColors = () => undefined
+const noHidden = new Set<number>()
+const noop = vi.fn()
 
 describe('<CategoryLegend>', () => {
   it('renders nothing when series is empty', () => {
     const { container } = render(
-      <CategoryLegend series={[]} colorAt={noColors} />,
+      <CategoryLegend
+        series={[]}
+        colorAt={noColors}
+        hiddenSeries={noHidden}
+        onToggle={noop}
+      />,
     )
     expect(container.firstChild).toBeNull()
   })
@@ -17,6 +25,8 @@ describe('<CategoryLegend>', () => {
       <CategoryLegend
         series={[{ name: '2024' }, { name: '2025' }]}
         colorAt={(i) => (i === 0 ? 'rgb(1, 1, 1)' : 'rgb(2, 2, 2)')}
+        hiddenSeries={noHidden}
+        onToggle={noop}
       />,
     )
     expect(screen.getByText('2024')).toBeTruthy()
@@ -28,6 +38,8 @@ describe('<CategoryLegend>', () => {
       <CategoryLegend
         series={[{ name: 'S1', color: 'rgb(99, 0, 0)' }]}
         colorAt={() => 'rgb(0, 0, 0)'}
+        hiddenSeries={noHidden}
+        onToggle={noop}
       />,
     )
     const dot = Array.from(container.querySelectorAll('div')).find(
@@ -41,6 +53,8 @@ describe('<CategoryLegend>', () => {
       <CategoryLegend
         series={[{ name: 'S1' }]}
         colorAt={() => 'rgb(7, 7, 7)'}
+        hiddenSeries={noHidden}
+        onToggle={noop}
       />,
     )
     const dot = Array.from(container.querySelectorAll('div')).find(
@@ -48,4 +62,41 @@ describe('<CategoryLegend>', () => {
     )
     expect(dot).toBeTruthy()
   })
+
+  it('clicking a legend item calls onToggle with its series index', async () => {
+    const onToggle = vi.fn()
+    render(
+      <CategoryLegend
+        series={[{ name: '2024' }, { name: '2025' }]}
+        colorAt={noColors}
+        hiddenSeries={noHidden}
+        onToggle={onToggle}
+      />,
+    )
+    await userEvent.click(screen.getByText('2025'))
+    expect(onToggle).toHaveBeenCalledWith(1)
+  })
+
+  it('marks a hidden series as aria-checked=false (dimmed)', () => {
+    render(
+      <CategoryLegend
+        series={[{ name: '2024' }, { name: '2025' }]}
+        colorAt={noColors}
+        hiddenSeries={new Set([1])}
+        onToggle={noop}
+      />,
+    )
+    expect(
+      screen
+        .getByText('2024')
+        .closest('[role="checkbox"]')
+        ?.getAttribute('aria-checked'),
+    ).toBe('true')
+    expect(
+      screen
+        .getByText('2025')
+        .closest('[role="checkbox"]')
+        ?.getAttribute('aria-checked'),
+    ).toBe('false')
+  })
 })

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

@@ -13,27 +13,70 @@ export interface CategoryLegendProps {
    * same source).
    */
   colorAt: (index: number) => string | undefined
+  /**
+   * Series indices currently hidden from the chart. Renders dimmed.
+   * Optional — defaults to none hidden. Added after this component's first
+   * release; kept optional (not required) so it stays a non-breaking
+   * addition for any direct consumer of `CategoryLegend` (a public
+   * subpath export) that predates the hide feature.
+   */
+  hiddenSeries?: ReadonlySet<number>
+  /**
+   * Fires with the series index when its legend item is clicked. Optional
+   * — omitting it renders a legend with no hide affordance (same
+   * reasoning as `hiddenSeries`).
+   */
+  onToggle?: (index: number) => void
 }
 
+const NO_HIDDEN_SERIES: ReadonlySet<number> = new Set()
+
 /**
  * Sticky color legend rendered below a multi-series Category list.
- * Per-series `color` overrides the matching `colorAt(i)` result.
+ * Per-series `color` overrides the matching `colorAt(i)` result. Clicking an
+ * item toggles that series' visibility in the rows above (mirrors ECharts'
+ * native legend click-to-hide).
  */
-export function CategoryLegend({ series, colorAt }: CategoryLegendProps) {
+export function CategoryLegend({
+  series,
+  colorAt,
+  hiddenSeries = NO_HIDDEN_SERIES,
+  onToggle,
+}: CategoryLegendProps) {
   if (series.length === 0) return null
   return (
     <Box sx={styles.legend}>
-      {series.map((s, i) => (
-        <Box key={s.name} sx={styles.legendItem}>
+      {series.map((s, i) => {
+        const hidden = hiddenSeries.has(i)
+        return (
           <Box
-            sx={styles.legendDot}
-            style={{ backgroundColor: s.color ?? colorAt(i) }}
-          />
-          <Typography variant='caption' sx={styles.legendLabel}>
-            {s.name}
-          </Typography>
-        </Box>
-      ))}
+            key={s.name}
+            // `checkbox`/`aria-checked`, not `button`/`aria-pressed` — this
+            // toggles a persistent visibility state (closer to a checkbox)
+            // AND keeps it out of `getByRole('button')` queries that count
+            // category ROWS throughout this widget's test suite.
+            role='checkbox'
+            aria-checked={!hidden}
+            tabIndex={0}
+            onClick={() => onToggle?.(i)}
+            onKeyDown={(e) => {
+              if (e.key === 'Enter' || e.key === ' ') {
+                e.preventDefault()
+                onToggle?.(i)
+              }
+            }}
+            sx={hidden ? styles.legendItemHidden : styles.legendItem}
+          >
+            <Box
+              sx={styles.legendDot}
+              style={{ backgroundColor: s.color ?? colorAt(i) }}
+            />
+            <Typography variant='caption' sx={styles.legendLabel}>
+              {s.name}
+            </Typography>
+          </Box>
+        )
+      })}
     </Box>
   )
 }

package/src/widgets-v2/category/components/category-row-stacked.test.tsx

@@ -69,20 +69,24 @@ describe('<CategoryRowStacked>', () => {
     expect(screen.getByText('Men: 32')).toBeTruthy()
   })
 
-  it('falls back to "Series N" for missing series names (1-indexed)', () => {
+  it("renders whatever seriesNames it is given — fallback resolution is the caller's responsibility", () => {
+    // The component has no notion of which series were hidden upstream, so
+    // it must not recompute a positional "Series N" fallback itself — the
+    // caller (category-ui.tsx) resolves names, including fallbacks, using
+    // each series' ORIGINAL index before this component ever sees them.
     render(
       <CategoryRowStacked
         name='Cat'
         values={[45, 32]}
         colors={COLORS}
-        seriesNames={[]}
+        seriesNames={['Series 1', 'Series 3']}
         formatter={(n) => String(n)}
         selected={false}
         onToggle={vi.fn()}
       />,
     )
     expect(screen.getByText('Series 1: 45')).toBeTruthy()
-    expect(screen.getByText('Series 2: 32')).toBeTruthy()
+    expect(screen.getByText('Series 3: 32')).toBeTruthy()
   })
 
   it('per-row normalization: bar fills 100% with segments proportional to the row sum', () => {

package/src/widgets-v2/category/components/category-row-stacked.tsx

@@ -13,7 +13,12 @@ export interface CategoryRowStackedProps {
   values: readonly number[]
   /** One color per series (palette + per-series overrides resolved upstream). */
   colors: readonly string[]
-  /** Series names for the breakdown row. Missing entries fall back to `Series N`. */
+  /**
+   * Series names for the breakdown row, one per visible series, already
+   * resolved by the caller (unnamed series fall back to `Series N` using
+   * their ORIGINAL series index — this component has no notion of which
+   * series were hidden, so it must not recompute a positional fallback).
+   */
   seriesNames: readonly string[]
   formatter: (n: number) => string
   selected: boolean
@@ -86,11 +91,11 @@ export function CategoryRowStacked({
         {values.map((v, i) => (
           // Series name is the stable identity for the breakdown line.
           <Typography
-            key={`breakdown-${seriesNames[i] ?? `series-${i}`}`}
+            key={`breakdown-${seriesNames[i]}`}
             variant='body2'
             sx={styles.stackedBreakdownItem}
           >
-            {`${seriesNames[i] ?? `Series ${i + 1}`}: ${formatter(v)}`}
+            {`${seriesNames[i]}: ${formatter(v)}`}
           </Typography>
         ))}
       </Box>

package/src/widgets-v2/category/style.ts

@@ -260,10 +260,18 @@ export const styles = {
     display: 'flex',
     alignItems: 'center',
     gap: 1,
+    cursor: 'pointer',
+  },
+  legendItemHidden: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: 1,
+    cursor: 'pointer',
+    opacity: 0.5,
   },
   legendDot: {
-    width: 8,
-    height: 8,
+    width: 14,
+    height: 14,
     borderRadius: '50%',
   },
   legendLabel: {

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

@@ -11,6 +11,7 @@ const mockChart = {
   resize: vi.fn(),
   on: vi.fn(),
   off: vi.fn(),
+  dispatchAction: vi.fn(),
   // Stubbed for the edge-label clamp; tests override per-case.
   convertToPixel: vi.fn((_finder: unknown, index: number) =>
     index === 0 ? 4 : 296,
@@ -39,6 +40,15 @@ function fireFinished(): void {
   }
 }
 
+/** Invoke the `legendselectchanged` listener the bridge bound on the mock chart. */
+function fireLegendSelectChanged(selected: Record<string, boolean>): void {
+  for (const [event, handler] of mockChart.on.mock.calls) {
+    if (event === 'legendselectchanged') {
+      ;(handler as (params: unknown) => void)({ selected })
+    }
+  }
+}
+
 // Resize observer mock — capture the callback so tests can trigger it.
 let resizeCb: (() => void) | null = null
 const observeResizeSpy = vi.fn((_node: HTMLElement, cb: () => void) => {
@@ -60,6 +70,7 @@ beforeEach(() => {
   mockChart.resize.mockReset()
   mockChart.on.mockReset()
   mockChart.off.mockReset()
+  mockChart.dispatchAction.mockReset()
   mockChart.convertToPixel.mockClear()
   mockChart.getWidth.mockClear()
   initSpy.mockClear()
@@ -219,6 +230,20 @@ describe('<EchartUI>', () => {
     expect(mockChart.dispose).toHaveBeenCalledTimes(1)
   })
 
+  it('restores every legend item when a legend click hides the last one', () => {
+    render(<EchartUI option={{}} />)
+    fireLegendSelectChanged({ A: false, B: false, C: false })
+    expect(mockChart.dispatchAction).toHaveBeenCalledWith({
+      type: 'legendAllSelect',
+    })
+  })
+
+  it('does nothing while at least one legend item stays visible', () => {
+    render(<EchartUI option={{}} />)
+    fireLegendSelectChanged({ A: true, B: false, C: false })
+    expect(mockChart.dispatchAction).not.toHaveBeenCalled()
+  })
+
   it('clamps overflowing edge labels on `finished` (category x-axis)', () => {
     render(<EchartUI option={categoryOption} />)
     mockChart.setOption.mockClear()

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

@@ -114,8 +114,28 @@ export function EchartUI({
       )
     }
     chart.on('finished', onFinished)
+    // Never let the legend end up with every item hidden — a user can click
+    // series off one by one until the chart goes blank. `selected` on this
+    // event is always the FULL name→boolean map (not just the clicked item),
+    // so "every value false" reliably means "nothing left visible". Restore
+    // all of them instead. `legendAllSelect` fires its own `legendselectall`
+    // event, not `legendselectchanged`, so this can't re-trigger itself.
+    // Always-on and independent of the consumer's `onEvents` — applies to
+    // every ECharts widget in the library for free. A widget that disables
+    // legend clicks entirely (e.g. Pie's `selectedMode: false`) never fires
+    // `legendselectchanged`, so this is a no-op there.
+    const onLegendSelectChanged = (params: unknown): void => {
+      const { selected } = params as { selected?: Record<string, boolean> }
+      if (!selected) return
+      const names = Object.keys(selected)
+      if (names.length > 0 && names.every((name) => !selected[name])) {
+        chart.dispatchAction({ type: 'legendAllSelect' })
+      }
+    }
+    chart.on('legendselectchanged', onLegendSelectChanged)
     return () => {
       chart.off('finished', onFinished)
+      chart.off('legendselectchanged', onLegendSelectChanged)
       // 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.

package/src/widgets-v2/echart/use-chart-selection.test.tsx

@@ -61,7 +61,7 @@ describe('useChartSelection', () => {
     expect(onSelectionChange).toHaveBeenLastCalledWith([3, 7, 11])
   })
 
-  it('reports null `selection` when the consumer passes nothing or an empty list', () => {
+  it('collapses undefined/null/an explicit empty list to null, since no merger treats them differently', () => {
     const { result, rerender } = renderHook(
       ({ selection }: { selection?: readonly string[] }) =>
         useChartSelection<string>({
@@ -81,6 +81,8 @@ describe('useChartSelection', () => {
     expect(result.current.selection).toBeNull()
     rerender({ selection: ['A'] })
     expect(result.current.selection).toEqual(['A'])
+    rerender({ selection: undefined })
+    expect(result.current.selection).toBeNull()
   })
 
   it('is a no-op when `onSelectionChange` is missing', () => {

package/src/widgets-v2/echart/use-chart-selection.ts

@@ -5,7 +5,13 @@ import type { EchartsEventHandler } from './echart-ui'
 export type SelectionKey = string | number
 
 export interface UseChartSelectionOptions<K extends SelectionKey> {
-  /** Controlled selection. `undefined` is treated the same as `[]`. */
+  /**
+   * Controlled selection. `undefined`/`null`/an explicit `[]` all mean "no
+   * selection interaction" — every current merger already treats an empty
+   * selection as "nothing excluded," so this hook collapses all three to
+   * `null` rather than promising per-merger `[]` semantics it doesn't
+   * implement.
+   */
   selection?: readonly K[]
   /** Receives the next selection. When omitted the wiring is a no-op. */
   onSelectionChange?: (next: readonly K[]) => void
@@ -32,9 +38,9 @@ export interface ChartSelectionWiring<K extends SelectionKey> {
    */
   onEvents: Record<string, EchartsEventHandler>
   /**
-   * The current selection — `null` when the consumer didn't pass one or it's
-   * empty. Mergers should treat `null` as "no dimming" and a non-null array
-   * as "render only these as fully opaque, dim the rest".
+   * The current selection — `null` for "no selection interaction"
+   * (`undefined`/`null`/an explicit `[]`), or a non-empty array meaning
+   * "render only these as fully opaque, dim the rest".
    */
   selection: readonly K[] | null
 }

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

@@ -1,7 +1,10 @@
 export { histogramOptions, createHistogramOptionFactory } from './options'
 export { HistogramSkeleton, type HistogramSkeletonProps } from './skeleton'
 export { createHistogramDownloadConfig } from './download'
-export { toRelativeHistogramData } from './transforms'
+export {
+  toRelativeHistogramData,
+  filterHistogramByLockedBins,
+} from './transforms'
 export type {
   HistogramWidgetData,
   HistogramOptionsInput,

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

@@ -273,6 +273,92 @@ describe('createHistogramOptionFactory (data → dataset merger)', () => {
     expect(out.series).toEqual([])
   })
 
+  describe('lockedItems → x-axis crop', () => {
+    it('crops xAxis.min/max to the locked bin range (data stays full-length)', () => {
+      const merge = createHistogramOptionFactory({
+        theme,
+        ticks: [0, 10, 20, 30, 40],
+        lockedItems: [1, 2],
+      })
+      const out = merge({}, [[5, 10, 15, 20]]) as {
+        xAxis: { min?: string | null; max?: string | null }
+        dataset: { source: [string, number][] }[]
+      }
+      expect(out.xAxis.min).toBe('10–20')
+      expect(out.xAxis.max).toBe('20–30')
+      // Data isn't sliced — every bin still has an entry, just scrolled
+      // out of the cropped view.
+      expect(out.dataset[0]!.source).toHaveLength(4)
+    })
+
+    it('resets to null (not omitted) when lockedItems is empty, clearing a prior crop', () => {
+      const merge = createHistogramOptionFactory({
+        theme,
+        ticks: [0, 10, 20, 30],
+        lockedItems: [],
+      })
+      const out = merge({}, [[1, 2, 3]]) as {
+        xAxis: { min?: string | null; max?: string | null }
+      }
+      expect(out.xAxis.min).toBeNull()
+      expect(out.xAxis.max).toBeNull()
+    })
+
+    it('preserves a consumer-supplied optionsOverride.xAxis.min/max when never locked, instead of clobbering it to null', () => {
+      const merge = createHistogramOptionFactory({
+        theme,
+        ticks: [0, 10, 20, 30],
+        lockedItems: [],
+      })
+      // `option` here stands in for the post-structural-phase option, which
+      // already has `optionsOverride.xAxis` baked in — the min/max a
+      // consumer set for an unrelated reason, with locking never engaged.
+      const out = merge({ xAxis: { min: 'custom-min', max: 'custom-max' } }, [
+        [1, 2, 3],
+      ]) as { xAxis: { min?: string | null; max?: string | null } }
+      expect(out.xAxis.min).toBe('custom-min')
+      expect(out.xAxis.max).toBe('custom-max')
+    })
+
+    it('handles a single locked bin (min === max)', () => {
+      const merge = createHistogramOptionFactory({
+        theme,
+        ticks: [0, 10, 20, 30],
+        lockedItems: [1],
+      })
+      const out = merge({}, [[1, 2, 3]]) as {
+        xAxis: { min?: string | null; max?: string | null }
+      }
+      expect(out.xAxis.min).toBe('10–20')
+      expect(out.xAxis.max).toBe('10–20')
+    })
+
+    it('merges the crop into the primary axis and preserves the rest of an array xAxis override, instead of discarding it', () => {
+      const merge = createHistogramOptionFactory({
+        theme,
+        ticks: [0, 10, 20, 30, 40],
+        lockedItems: [1, 2],
+      })
+      const out = merge(
+        {
+          xAxis: [
+            { type: 'category', name: 'primary' },
+            { type: 'value', name: 'secondary' },
+          ],
+        },
+        [[5, 10, 15, 20]],
+      ) as {
+        xAxis: { name?: string; min?: string | null; max?: string | null }[]
+      }
+      expect(Array.isArray(out.xAxis)).toBe(true)
+      expect(out.xAxis).toHaveLength(2)
+      expect(out.xAxis[0]!.name).toBe('primary')
+      expect(out.xAxis[0]!.min).toBe('10–20')
+      expect(out.xAxis[0]!.max).toBe('20–30')
+      expect(out.xAxis[1]).toEqual({ type: 'value', name: 'secondary' })
+    })
+  })
+
   describe('tooltip formatter', () => {
     type ItemFormatter = (
       params: unknown,

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

@@ -160,6 +160,7 @@ export function createHistogramOptionFactory(
 ): OptionFactory {
   const { theme, formatter, ticks, series, labelFormatter, selection } = options
   const optionsOverride = options.optionsOverride
+  const lockedItems = options.lockedItems
   const selectionSet =
     selection && selection.length > 0 ? new Set<number>(selection) : null
 
@@ -171,6 +172,22 @@ export function createHistogramOptionFactory(
     binLabels.push(labelFormatter ? labelFormatter(raw) : raw)
   }
 
+  // Locked range → x-axis crop. `min`/`max` on a category axis accept a
+  // category value (the bin label string), bounding the visible window
+  // without touching `dataset`/`series` — the zeroed-out bins from
+  // `filterHistogramByLockedBins` stay in the data, just scrolled out of
+  // view. `null` (not omitted) on unlock, since ECharts' option merge skips
+  // `undefined` keys and would otherwise leave a stale crop in place.
+  const lockedRange =
+    lockedItems && lockedItems.length > 0
+      ? (() => {
+          const indices = lockedItems.map(Number)
+          const min = binLabels[Math.min(...indices)]
+          const max = binLabels[Math.max(...indices)]
+          return min != null && max != null ? { min, max } : null
+        })()
+      : null
+
   return (option, data, ctx) => {
     if (option == null) {
       const structural = histogramOptions({ theme, formatter })
@@ -254,8 +271,41 @@ export function createHistogramOptionFactory(
       },
     }
 
+    // A consumer's `optionsOverride.xAxis` may legitimately be an array
+    // (ECharts supports multiple x-axes on one grid). Merge the locked-range
+    // crop into the primary (first) axis instead of discarding the rest via
+    // an object fallback — `min`/`max` here bound a category axis by label
+    // string, which is only ambiguous if `labelFormatter` produces duplicate
+    // labels across bins (a structural limitation of label-string bounds,
+    // not fixed here).
+    //
+    // `min`/`max` are ALWAYS written explicitly below (never omitted) —
+    // ECharts' merge silently keeps whatever value it last received for an
+    // omitted key, so omitting them while unlocked would leave a stale crop
+    // in place from a previous locked render. But the fallback when there's
+    // no active crop must be the CONSUMER's own `optionsOverride.xAxis.min/max`
+    // (if they set one), not an unconditional `null` — `option.xAxis` here
+    // is the post-structural-phase axis, which only ever carries the
+    // consumer's static override (never our own prior crop — the structural
+    // phase is rebuilt from scratch on every factory recreation, so it can't
+    // have picked up a merge-phase write from a previous render).
+    const currentAxis = (
+      Array.isArray(option.xAxis) ? option.xAxis[0] : option.xAxis
+    ) as { min?: unknown; max?: unknown } | undefined
+    const lockedRangeAxis = {
+      min: lockedRange?.min ?? currentAxis?.min ?? null,
+      max: lockedRange?.max ?? currentAxis?.max ?? null,
+    }
+    const nextXAxis = Array.isArray(option.xAxis)
+      ? [{ ...option.xAxis[0], ...lockedRangeAxis }, ...option.xAxis.slice(1)]
+      : {
+          ...(typeof option.xAxis === 'object' ? option.xAxis : {}),
+          ...lockedRangeAxis,
+        }
+
     return {
       ...option,
+      xAxis: nextXAxis,
       dataset: seriesArr.map((counts) => ({
         source: binLabels.map(
           (label, i) => [label, counts[i] ?? 0] as [string, number],