@carto/ps-react-ui 4.17.3 → 4.19.0

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')
+  })
+})

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

@@ -0,0 +1,26 @@
+/**
+ * `LockSelection` filter for Table. Data is a FLAT `TableRow[]` (unlike every
+ * other widget's `X[][]` series shape) and row identity comes from
+ * `row[keyColumn]` (default `'id'`), not `name` — so `filterByLockedItems`
+ * doesn't apply here (its outer `.map` treats each row as a "series", and a
+ * plain row object isn't an array, so it would silently pass everything
+ * through unfiltered). Falls back to the row's index when the identity
+ * column is nullish, mirroring `TableUI`'s own `resolveRowId`.
+ *
+ * `keyColumn` isn't part of `LockSelection`'s generic `filterFn` signature —
+ * close over it: `filterFn={(data, locked) => filterTableByLockedRows(data, locked, keyColumn)}`.
+ */
+export function filterTableByLockedRows(
+  input: unknown,
+  lockedItems: readonly (string | number)[],
+  keyColumn = 'id',
+): unknown {
+  if (lockedItems.length === 0) return input
+  if (!Array.isArray(input)) return input
+  const locked = new Set<string | number>(lockedItems)
+  return input.filter((row: unknown, index: number): boolean => {
+    if (row == null || typeof row !== 'object') return false
+    const id = (row as Record<string, unknown>)[keyColumn] ?? index
+    return (typeof id === 'string' || typeof id === 'number') && locked.has(id)
+  })
+}

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

@@ -1,6 +1,7 @@
 export { timeseriesOptions, createTimeseriesOptionFactory } from './options'
 export { TimeseriesSkeleton } from './skeleton'
 export { createTimeseriesDownloadConfig } from './download'
+export { filterTimeseriesByLockedItems } from './transforms'
 export type {
   TimeseriesDatum,
   TimeseriesWidgetData,

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

@@ -0,0 +1,49 @@
+import { describe, it, expect } from 'vitest'
+import { filterTimeseriesByLockedItems } from './transforms'
+
+describe('filterTimeseriesByLockedItems', () => {
+  it('returns input unchanged when locked set is empty', () => {
+    const data = [[{ name: 1000, value: 10 }]]
+    expect(filterTimeseriesByLockedItems(data, [])).toBe(data)
+  })
+
+  it('keeps only items whose (numeric) name is in the locked set', () => {
+    const out = filterTimeseriesByLockedItems(
+      [
+        [
+          { name: 1000, value: 10 },
+          { name: 2000, value: 20 },
+        ],
+      ],
+      [2000],
+    )
+    expect(out).toEqual([[{ name: 2000, value: 20 }]])
+  })
+
+  it('normalizes Date names to ms-since-epoch before comparing', () => {
+    const d1 = new Date('2024-01-01T00:00:00.000Z')
+    const d2 = new Date('2024-01-02T00:00:00.000Z')
+    const out = filterTimeseriesByLockedItems(
+      [
+        [
+          { name: d1, value: 10 },
+          { name: d2, value: 20 },
+        ],
+      ],
+      [d2.getTime()],
+    )
+    expect(out).toEqual([[{ name: d2, value: 20 }]])
+  })
+
+  it('handles string names', () => {
+    const out = filterTimeseriesByLockedItems(
+      [[{ name: '2024-01-01', value: 10 }]],
+      ['2024-01-01'],
+    )
+    expect(out).toEqual([[{ name: '2024-01-01', value: 10 }]])
+  })
+
+  it('returns input unchanged when input is not array-shaped', () => {
+    expect(filterTimeseriesByLockedItems('nope', [1])).toBe('nope')
+  })
+})

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

@@ -0,0 +1,31 @@
+/**
+ * `LockSelection` filter for Timeseries. Data is `{name, value}[][]` like
+ * Bar/Pie/Category, but `name` may arrive as `Date | number | string` (the
+ * time axis stores a `Date`). `lockedItems` is snapshotted from `selection`,
+ * whose keys are already normalized to `Date → ms` (see `options.ts`'s
+ * `normalizeName`) — so a raw `Date` name must be normalized the same way
+ * before the membership check, or every point would compare a `Date` object
+ * against a `number` and silently fail to match, filtering everything out.
+ */
+export function filterTimeseriesByLockedItems(
+  input: unknown,
+  lockedItems: readonly (string | number)[],
+): unknown {
+  if (lockedItems.length === 0) return input
+  if (!Array.isArray(input)) return input
+  const locked = new Set<string | number>(lockedItems)
+  return input.map((series: unknown): unknown => {
+    if (!Array.isArray(series)) return series
+    return series.filter((item: unknown) => {
+      if (item == null || typeof item !== 'object' || !('name' in item)) {
+        return false
+      }
+      const raw = (item as { name: unknown }).name
+      const name = raw instanceof Date ? raw.getTime() : raw
+      return (
+        (typeof name === 'string' || typeof name === 'number') &&
+        locked.has(name)
+      )
+    })
+  })
+}