@carto/ps-react-ui 4.17.2 → 4.18.0

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,

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

@@ -55,6 +55,13 @@ export function pieOptions({
       left: 'center',
       type: 'scroll',
       itemGap: 16,
+      // The legend is presentational only here — the pie has its own
+      // click-to-select affordance on the slices themselves, so legend
+      // clicks toggling series visibility would be a second, redundant/
+      // conflicting interaction model. Hover-highlight is disabled per
+      // series via `legendHoverLink` (ECharts has no legend-level knob
+      // for it).
+      selectedMode: false,
     },
     tooltip: {
       // Pie uses item-trigger (no axis); the rest of the styling mirrors
@@ -89,6 +96,7 @@ export function pieOptions({
         colorBy: 'data',
         avoidLabelOverlap: true,
         selectedOffset: 0,
+        legendHoverLink: false,
         emphasis: { disabled: true },
         itemStyle: {
           borderColor: theme.palette.background.paper,
@@ -129,10 +137,14 @@ export function createPieOptionFactory(
   const { theme, formatter, labelFormatter, optionsOverride, series } = options
   const radius = options.radius ?? DEFAULT_RADIUS
   const selection = options.selection
+  // An explicit `[]` (deselected down to zero via chart clicks) is treated
+  // the same as no selection: the pie has no bar/histogram-style "nothing
+  // selected" affordance, so dimming every slice would just look broken —
+  // it renders fully active, same as the no-interaction state.
   const selectionSet =
-    selection && selection.length > 0
-      ? new Set<string | number>(selection)
-      : null
+    selection === undefined || selection === null || selection.length === 0
+      ? null
+      : new Set<string | number>(selection)
   return (option, data, ctx) => {
     if (option == null) {
       const structural = pieOptions({ theme, formatter, labelFormatter })
@@ -217,6 +229,13 @@ function buildSingleSeriesPieFusion(
   // not conditionally — same anti-stale-callback rationale as bar /
   // histogram. The slice border + width come from the structural
   // template's `itemStyle` and survive via the spread below.
+  //
+  // `selectionSet` is the *included* set, same direct semantics as
+  // bar/histogram/timeseries (no ADR-014 exclusion inversion). Dim a slice
+  // when its name is NOT in the set. `selectionSet` is never a non-null
+  // empty Set — the collapse above (`selection.length === 0 → null`) rules
+  // that out — so there's no "dim everything" case here, unlike a widget
+  // that gives `[]` its own "selected down to nothing" meaning.
   const colorFn = (params: CallbackDataParams): string => {
     const base = resolvePaletteColor(params)
     if (!selectionSet) return base
@@ -227,12 +246,33 @@ function buildSingleSeriesPieFusion(
       : echarts.color.modifyAlpha(base, 0.15)
   }
 
+  // Which slice renders the centre value+name: the greatest value among
+  // the *included* slices (all of them when there's no active
+  // selection), computed locally — no query round-trip. Only that one
+  // slice's formatter call returns text; every other slice returns ''
+  // so exactly one label ever renders at the shared centre anchor. Only
+  // `typeof value === 'number'` participates — if every included slice's
+  // value is non-numeric, `centerMaxName` stays `undefined` and no slice
+  // matches it in `labelTextFormatter` below, so the chart renders with no
+  // centre label at all (graceful no-op, not a crash).
+  const centerData = seriesArr[0] ?? []
+  let centerMaxName: string | number | undefined
+  let centerMaxValue = -Infinity
+  for (const d of centerData) {
+    if (selectionSet && !selectionSet.has(d.name)) continue
+    if (typeof d.value === 'number' && d.value > centerMaxValue) {
+      centerMaxValue = d.value
+      centerMaxName = d.name
+    }
+  }
+
   // Center label formatter — lives in the merger because it reads
   // reactive `formatter` / `labelFormatter` from ctx. The rich tags
   // `{c|…}` and `{b|…}` reference the rich styles baked into the
   // structural label template.
   const labelTextFormatter = (params: CallbackDataParams): string => {
     const { name } = params
+    if (name == null || name !== centerMaxName) return ''
     const encodeIndex = params.encode?.value?.[0]
     if (encodeIndex === undefined) return ''
     const value = (Object.values(params.data ?? {}) as unknown[]).at(
@@ -269,6 +309,7 @@ function buildSingleSeriesPieFusion(
       return {
         ...templateObj,
         type: 'pie' as const,
+        legendHoverLink: false,
         datasetIndex: i,
         name: series?.[i]?.name ?? `Series ${i + 1}`,
         radius: [...radius],
@@ -291,7 +332,27 @@ function buildSingleSeriesPieFusion(
     }),
     // Legend always shows for pie (mirrors v1) — slice names drive the
     // entries, so even a single donut benefits from a category list.
-    legend: { ...baseLegend, show: true },
+    //
+    // Exclusion is conveyed purely via `colorFn`/`labelTextFormatter`
+    // dimming above, never via the legend's `selected` map: for a pie
+    // series, ECharts treats `legend.selected[name] = false` as "remove
+    // this data point," which recomputes every remaining slice's angle —
+    // the excluded slice disappears instead of rendering dimmed. Forcing
+    // every name to `true` on every render also overrides ECharts' own
+    // internal toggle state from a native legend click (which flips a
+    // name to `false` and hides it before our `legendselectchanged`
+    // handler gets a chance to react), so a legend click never leaves a
+    // slice structurally removed — only the color/label dimming reflects
+    // exclusion, and it stays in sync with the slice itself since both
+    // read `selectionSet` on the same render.
+    legend: {
+      ...baseLegend,
+      show: true,
+      selectedMode: false,
+      selected: Object.fromEntries(
+        (seriesArr[0] ?? []).map((d) => [String(d.name), true]),
+      ),
+    },
     tooltip: {
       ...baseTooltip,
       formatter: buildPieTooltipFormatter(formatter, labelFormatter),
@@ -372,6 +433,7 @@ function buildMultiSeriesBarFusion(
         type: 'bar' as const,
         name: series?.[i]?.name ?? `Series ${i + 1}`,
         barMaxWidth: 100,
+        legendHoverLink: false,
         emphasis: { focus: 'series' },
         ...buildSeriesLabelConfig(formatter, 'x'),
         itemStyle: { color: barColorFn },
@@ -422,7 +484,20 @@ function buildMultiSeriesBarFusion(
         }),
       },
     },
-    legend: { ...baseLegend, show: true },
+    // Mirrors the donut branch's `selected` reset above — `selectedMode:
+    // false` blocks the native legend click that would otherwise undo an
+    // ECharts-internal toggle, so without forcing every entry back to
+    // `true` here a prior native toggle (from before `selectedMode` took
+    // effect, or a stale `keepAlive` instance) would stay hidden forever
+    // with no way to restore it.
+    legend: {
+      ...baseLegend,
+      show: true,
+      selectedMode: false,
+      selected: Object.fromEntries(
+        seriesArr.map((_, i) => [series?.[i]?.name ?? `Series ${i + 1}`, true]),
+      ),
+    },
     tooltip: {
       ...baseTooltip,
       trigger: 'axis',

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

@@ -1,7 +1,10 @@
 export { scatterplotOptions, createScatterplotOptionFactory } from './options'
 export { ScatterplotSkeleton, type ScatterplotSkeletonProps } from './skeleton'
 export { createScatterplotDownloadConfig } from './download'
-export { toRelativeScatterplotData } from './transforms'
+export {
+  toRelativeScatterplotData,
+  filterScatterplotByLockedPoints,
+} from './transforms'
 export type {
   ScatterplotDatum,
   ScatterplotWidgetData,

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

@@ -1,5 +1,8 @@
 import { describe, it, expect } from 'vitest'
-import { toRelativeScatterplotData } from './transforms'
+import {
+  toRelativeScatterplotData,
+  filterScatterplotByLockedPoints,
+} from './transforms'
 
 describe('toRelativeScatterplotData', () => {
   it('rewrites each tuple y as its share of the series total in 0-100, x stays raw', () => {
@@ -95,3 +98,37 @@ describe('toRelativeScatterplotData', () => {
     ])
   })
 })
+
+describe('filterScatterplotByLockedPoints', () => {
+  const DATA = [
+    [
+      [1, 10],
+      [2, 20],
+      [3, 30],
+    ],
+    [
+      [4, 40],
+      [5, 50],
+    ],
+  ]
+
+  it('returns input unchanged when locked set is empty', () => {
+    expect(filterScatterplotByLockedPoints(DATA, [])).toBe(DATA)
+  })
+
+  it('keeps only points whose `${seriesIndex}:${dataIndex}` key is locked', () => {
+    expect(
+      filterScatterplotByLockedPoints(DATA, ['0:0', '0:2', '1:1']),
+    ).toEqual([
+      [
+        [1, 10],
+        [3, 30],
+      ],
+      [[5, 50]],
+    ])
+  })
+
+  it('returns input unchanged when input is not array-shaped', () => {
+    expect(filterScatterplotByLockedPoints('nope', ['0:0'])).toBe('nope')
+  })
+})

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

@@ -36,3 +36,26 @@ function isXyTupleArray(v: unknown): v is [number, number][] {
       Number.isFinite(item[1]),
   )
 }
+
+/**
+ * `LockSelection` filter for Scatterplot. Data is `[number, number][][]` —
+ * points have no `name`, so selection (and locking) is keyed on a synthetic
+ * `${seriesIndex}:${dataIndex}` string (same format `useChartSelection`'s
+ * `keyFromClick`/`keysFromBrush` produce for this widget). Unlike Histogram,
+ * a point's position carries no external meaning (no `ticks` to desync from),
+ * so non-locked points are removed outright rather than zeroed.
+ */
+export function filterScatterplotByLockedPoints(
+  input: unknown,
+  lockedItems: readonly (string | number)[],
+): unknown {
+  if (lockedItems.length === 0) return input
+  if (!Array.isArray(input)) return input
+  const locked = new Set<string>(lockedItems.map(String))
+  return input.map((series: unknown, seriesIndex: number): unknown => {
+    if (!isXyTupleArray(series)) return series
+    return series.filter((_, dataIndex) =>
+      locked.has(`${seriesIndex}:${dataIndex}`),
+    )
+  })
+}

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

@@ -2,6 +2,7 @@ export { Table, type TableProps } from './table'
 export { TableUI, type TableUIProps } from './table-ui'
 export { TableSkeleton, type TableSkeletonProps } from './skeleton'
 export { createTableDownloadConfig } from './download'
+export { filterTableByLockedRows } from './transforms'
 export {
   compareValues,
   sortRows,

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

@@ -0,0 +1,40 @@
+import { describe, it, expect } from 'vitest'
+import { filterTableByLockedRows } from './transforms'
+
+describe('filterTableByLockedRows', () => {
+  const ROWS = [
+    { id: 'a', label: 'Alpha' },
+    { id: 'b', label: 'Beta' },
+    { id: 'c', label: 'Gamma' },
+  ]
+
+  it('returns input unchanged when locked set is empty', () => {
+    expect(filterTableByLockedRows(ROWS, [])).toBe(ROWS)
+  })
+
+  it('keeps only rows whose default `id` column is locked', () => {
+    expect(filterTableByLockedRows(ROWS, ['a', 'c'])).toEqual([
+      { id: 'a', label: 'Alpha' },
+      { id: 'c', label: 'Gamma' },
+    ])
+  })
+
+  it('uses a custom keyColumn when supplied', () => {
+    const rows = [
+      { sku: 'X1', name: 'Widget' },
+      { sku: 'X2', name: 'Gadget' },
+    ]
+    expect(filterTableByLockedRows(rows, ['X2'], 'sku')).toEqual([
+      { sku: 'X2', name: 'Gadget' },
+    ])
+  })
+
+  it('falls back to row index when the identity column is nullish', () => {
+    const rows = [{ label: 'first' }, { label: 'second' }]
+    expect(filterTableByLockedRows(rows, [1])).toEqual([{ label: 'second' }])
+  })
+
+  it('returns input unchanged when input is not array-shaped', () => {
+    expect(filterTableByLockedRows('nope', ['a'])).toBe('nope')
+  })
+})