@carto/ps-react-ui 4.17.3 → 4.18.0

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],

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

@@ -1,5 +1,8 @@
 import { describe, it, expect } from 'vitest'
-import { toRelativeHistogramData } from './transforms'
+import {
+  toRelativeHistogramData,
+  filterHistogramByLockedBins,
+} from './transforms'
 
 describe('toRelativeHistogramData', () => {
   it('rewrites each bin count as its share of the series total in 0-100', () => {
@@ -44,3 +47,35 @@ describe('toRelativeHistogramData', () => {
     ])
   })
 })
+
+describe('filterHistogramByLockedBins', () => {
+  it('returns input unchanged when locked set is empty', () => {
+    const data = [[10, 20, 30]]
+    expect(filterHistogramByLockedBins(data, [])).toBe(data)
+  })
+
+  it('zeroes non-locked bin counts, preserving array length and position', () => {
+    expect(filterHistogramByLockedBins([[10, 20, 30]], [0, 2])).toEqual([
+      [10, 0, 30],
+    ])
+  })
+
+  it('handles multiple series independently', () => {
+    expect(
+      filterHistogramByLockedBins(
+        [
+          [1, 2, 3],
+          [4, 5, 6],
+        ],
+        [1],
+      ),
+    ).toEqual([
+      [0, 2, 0],
+      [0, 5, 0],
+    ])
+  })
+
+  it('returns input unchanged when input is not array-shaped', () => {
+    expect(filterHistogramByLockedBins('nope', [0])).toBe('nope')
+  })
+})

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

@@ -28,3 +28,26 @@ function isFlatNumberArray(v: unknown): v is number[] {
   if (!Array.isArray(v)) return false
   return v.every((item) => typeof item === 'number' && Number.isFinite(item))
 }
+
+/**
+ * `LockSelection` filter for Histogram. Data is `number[][]` — a flat list
+ * of bin counts per series, positionally paired with `ticks` (bin `i` covers
+ * `[ticks[i], ticks[i+1])`). Unlike name-keyed widgets, locked-out bins can't
+ * be REMOVED — that would shift every later bin's index and desync it from
+ * its `ticks` range. Zeroing them out instead preserves array length/position,
+ * so locked bins just render as empty (height 0) rather than disappearing.
+ *
+ * `lockedItems` holds bin indices (numbers, from Histogram's `selection`).
+ */
+export function filterHistogramByLockedBins(
+  input: unknown,
+  lockedItems: readonly (string | number)[],
+): unknown {
+  if (lockedItems.length === 0) return input
+  if (!Array.isArray(input)) return input
+  const locked = new Set<number>(lockedItems.map(Number))
+  return input.map((series: unknown): unknown => {
+    if (!isFlatNumberArray(series)) return series
+    return series.map((count, i) => (locked.has(i) ? count : 0))
+  })
+}

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

@@ -44,6 +44,15 @@ export interface HistogramOptionFactoryInput {
    * (`itemStyle.opacity: 0.15`). `null`/empty means no selection.
    */
   selection?: readonly number[] | null
+  /**
+   * Locked bin indices (from `LockSelection`). The x-axis crops its visible
+   * window to `[min(lockedItems), max(lockedItems)]` so the chart actually
+   * zooms into the locked range instead of showing every bin label with
+   * zeroed-out bars outside it. `null`/empty means no crop. Histogram's
+   * selection is always a contiguous run (`use-widget-filters`'s BETWEEN
+   * envelope round-trip fills any gaps), so min/max fully describes it.
+   */
+  lockedItems?: readonly number[] | null
   /**
    * Consumer-supplied partial option merged into the structural option at
    * structural-build time. Lets stories override pieces of the theme-aware

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

@@ -83,6 +83,20 @@ describe('pieOptions (structural)', () => {
     // re-emits it as { ...baseLegend, show: true } at fusion time.
     expect(out.legend?.show).toBe(true)
   })
+
+  it('disables legend click-to-toggle', () => {
+    const out = pieOptions({ theme }) as {
+      legend?: { selectedMode?: boolean }
+    }
+    expect(out.legend?.selectedMode).toBe(false)
+  })
+
+  it('disables legend hover-highlight on the series template (no legend-level knob in ECharts)', () => {
+    const out = pieOptions({ theme }) as {
+      series?: { legendHoverLink?: boolean }[]
+    }
+    expect(out.series?.[0]?.legendHoverLink).toBe(false)
+  })
 })
 
 describe('createPieOptionFactory — single-series (donut)', () => {
@@ -147,6 +161,16 @@ describe('createPieOptionFactory — single-series (donut)', () => {
     expect(single.legend?.show).toBe(true)
   })
 
+  it('keeps legend interactivity disabled after fusion', () => {
+    const merge = createPieOptionFactory({ theme })
+    const single = merge({}, [[{ name: 'A', value: 1 }]]) as {
+      legend?: { selectedMode?: boolean }
+      series?: { legendHoverLink?: boolean }[]
+    }
+    expect(single.legend?.selectedMode).toBe(false)
+    expect(single.series?.[0]?.legendHoverLink).toBe(false)
+  })
+
   it('uses series[0].name for the single series name when provided', () => {
     const merge = createPieOptionFactory({
       theme,
@@ -303,6 +327,215 @@ describe('createPieOptionFactory — single-series (donut)', () => {
     ).toBe('#FACADE')
   })
 
+  it('label formatter renders text only for the max-valued slice when no selection is passed (regression)', () => {
+    const merge = createPieOptionFactory({ theme })
+    const out = merge({}, [
+      [
+        { name: 'A', value: 10 },
+        { name: 'B', value: 25 },
+      ],
+    ]) as {
+      series: { label: { formatter: (p: Record<string, unknown>) => string } }[]
+    }
+    const fmt = out.series[0]!.label.formatter
+    expect(
+      fmt({
+        name: 'A',
+        encode: { value: [1] },
+        data: { name: 'A', value: 10 },
+      }),
+    ).toBe('')
+    expect(
+      fmt({
+        name: 'B',
+        encode: { value: [1] },
+        data: { name: 'B', value: 25 },
+      }),
+    ).not.toBe('')
+  })
+
+  it('label formatter shows the centre value only for the max-valued INCLUDED slice (direct/inclusive selection, computed locally)', () => {
+    const merge = createPieOptionFactory({ theme, selection: ['A', 'B'] })
+    const out = merge({}, [
+      [
+        { name: 'A', value: 10 },
+        { name: 'B', value: 25 },
+        { name: 'C', value: 100 },
+      ],
+    ]) as {
+      series: { label: { formatter: (p: Record<string, unknown>) => string } }[]
+    }
+    const fmt = out.series[0]!.label.formatter
+    // C has the highest value overall but is not included in the selection,
+    // so it's excluded from the max computation — B (the max of A/B) wins.
+    expect(
+      fmt({
+        name: 'A',
+        encode: { value: [1] },
+        data: { name: 'A', value: 10 },
+      }),
+    ).toBe('')
+    expect(
+      fmt({
+        name: 'B',
+        encode: { value: [1] },
+        data: { name: 'B', value: 25 },
+      }),
+    ).not.toBe('')
+    expect(
+      fmt({
+        name: 'C',
+        encode: { value: [1] },
+        data: { name: 'C', value: 100 },
+      }),
+    ).toBe('')
+  })
+
+  it('label formatter treats an explicit empty selection as no selection (renders the true max, not blank)', () => {
+    const merge = createPieOptionFactory({ theme, selection: [] })
+    const out = merge({}, [[{ name: 'A', value: 10 }]]) as {
+      series: { label: { formatter: (p: Record<string, unknown>) => string } }[]
+    }
+    const html = out.series[0]!.label.formatter({
+      name: 'A',
+      encode: { value: [1] },
+      data: { name: 'A', value: 10 },
+    })
+    expect(html).not.toBe('')
+  })
+
+  it('itemStyle color dims a slice NOT in the selection (direct/inclusive model, matches multi-series bar)', () => {
+    const merge = createPieOptionFactory({ theme, selection: ['A'] })
+    const out = merge({ color: ['#AAA', '#BBB'] }, [
+      [
+        { name: 'A', value: 10 },
+        { name: 'B', value: 5 },
+      ],
+    ]) as {
+      series: {
+        itemStyle: {
+          color: (p: {
+            dataIndex: number
+            color: string
+            value: object
+            name: string
+          }) => string
+        }
+      }[]
+    }
+    const colorFn = out.series[0]!.itemStyle.color
+    expect(
+      colorFn({
+        dataIndex: 0,
+        color: '#000',
+        value: { name: 'A', value: 10 },
+        name: 'A',
+      }),
+    ).toBe('#AAA')
+    const dimmedB = colorFn({
+      dataIndex: 1,
+      color: '#000',
+      value: { name: 'B', value: 5 },
+      name: 'B',
+    })
+    expect(dimmedB).not.toBe('#BBB')
+  })
+
+  it('itemStyle color dims neither slice when both are in a multi-item selection (regression: locked-then-searched-and-reselected)', () => {
+    const merge = createPieOptionFactory({ theme, selection: ['A', 'B'] })
+    const out = merge({ color: ['#AAA', '#BBB'] }, [
+      [
+        { name: 'A', value: 10 },
+        { name: 'B', value: 5 },
+      ],
+    ]) as {
+      series: {
+        itemStyle: {
+          color: (p: {
+            dataIndex: number
+            color: string
+            value: object
+            name: string
+          }) => string
+        }
+      }[]
+    }
+    const colorFn = out.series[0]!.itemStyle.color
+    expect(
+      colorFn({
+        dataIndex: 0,
+        color: '#000',
+        value: { name: 'A', value: 10 },
+        name: 'A',
+      }),
+    ).toBe('#AAA')
+    expect(
+      colorFn({
+        dataIndex: 1,
+        color: '#000',
+        value: { name: 'B', value: 5 },
+        name: 'B',
+      }),
+    ).toBe('#BBB')
+  })
+
+  it('itemStyle color dims nothing when selection is an explicit empty array (renders fully active, not all-dimmed)', () => {
+    const merge = createPieOptionFactory({ theme, selection: [] })
+    const out = merge({ color: ['#AAA', '#BBB'] }, [
+      [
+        { name: 'A', value: 10 },
+        { name: 'B', value: 5 },
+      ],
+    ]) as {
+      series: {
+        itemStyle: {
+          color: (p: {
+            dataIndex: number
+            color: string
+            value: object
+            name: string
+          }) => string
+        }
+      }[]
+    }
+    const colorFn = out.series[0]!.itemStyle.color
+    expect(
+      colorFn({
+        dataIndex: 0,
+        color: '#000',
+        value: { name: 'A', value: 10 },
+        name: 'A',
+      }),
+    ).toBe('#AAA')
+    expect(
+      colorFn({
+        dataIndex: 1,
+        color: '#000',
+        value: { name: 'B', value: 5 },
+        name: 'B',
+      }),
+    ).toBe('#BBB')
+  })
+
+  it('never sets legend.selected to false for a dimmed slice (would trigger ECharts native removal instead of dimming)', () => {
+    const merge = createPieOptionFactory({ theme, selection: ['A'] })
+    const out = merge({}, [
+      [
+        { name: 'A', value: 10 },
+        { name: 'B', value: 5 },
+      ],
+    ]) as { legend?: { selected?: Record<string, boolean> } }
+    expect(out.legend?.selected).toEqual({ A: true, B: true })
+  })
+
+  it('forces legend.selected back to true even with no active selection (overrides ECharts internal legend-click toggle state)', () => {
+    const merge = createPieOptionFactory({ theme })
+    const out = merge({}, [[{ name: 'A', value: 10 }]]) as {
+      legend?: { selected?: Record<string, boolean> }
+    }
+    expect(out.legend?.selected).toEqual({ A: true })
+  })
+
   it('re-emits tooltip.formatter at fusion time so RelativeData (ctx.formatter) flows through', () => {
     const merge = createPieOptionFactory({ theme })
     const out = merge(
@@ -539,6 +772,35 @@ describe('createPieOptionFactory — multi-series fallback (horizontal bar)', ()
     expect(out.legend?.show).toBe(true)
   })
 
+  it('keeps legend interactivity disabled in the multi-series bar fallback', () => {
+    const merge = createPieOptionFactory({ theme })
+    const out = merge({}, MULTI) as {
+      legend?: { selectedMode?: boolean }
+      series?: { legendHoverLink?: boolean }[]
+    }
+    expect(out.legend?.selectedMode).toBe(false)
+    expect(out.series?.[0]?.legendHoverLink).toBe(false)
+  })
+
+  it('forces legend.selected back to true for every series (mirrors the donut branch — selectedMode:false blocks the native click that would otherwise undo a toggle)', () => {
+    const merge = createPieOptionFactory({
+      theme,
+      series: [{ name: '2024' }, { name: '2025' }],
+    })
+    const out = merge({}, MULTI) as {
+      legend?: { selected?: Record<string, boolean> }
+    }
+    expect(out.legend?.selected).toEqual({ '2024': true, '2025': true })
+  })
+
+  it('falls back to Series N for legend.selected keys when series metadata is omitted', () => {
+    const merge = createPieOptionFactory({ theme })
+    const out = merge({}, MULTI) as {
+      legend?: { selected?: Record<string, boolean> }
+    }
+    expect(out.legend?.selected).toEqual({ 'Series 1': true, 'Series 2': true })
+  })
+
   describe('horizontal-bar tooltip formatter', () => {
     type AxisFormatter = (
       params: unknown,