@carto/ps-react-ui 6.1.1 → 6.3.0

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

@@ -1,4 +1,5 @@
 import { describe, it, expect } from 'vitest'
+import * as echarts from 'echarts'
 import { createTheme, type Theme } from '@mui/material'
 import { createPieOptionFactory, pieOptions } from './options'
 
@@ -936,3 +937,93 @@ describe('createPieOptionFactory — multi-series fallback (horizontal bar)', ()
     })
   })
 })
+
+describe('createPieOptionFactory — per-item colour', () => {
+  interface Out {
+    series: { itemStyle: { color: (p: unknown) => string } }[]
+  }
+  const dim = (c: string) => echarts.color.modifyAlpha(c, 0.15)
+  const palette = ['#p0', '#p1', '#p2']
+
+  it('donut: slice colour wins over the palette; template next', () => {
+    const merge = createPieOptionFactory({ theme, selection: ['A', 'B'] })
+    const out = merge(
+      {
+        color: palette,
+        series: [{ type: 'pie', itemStyle: { color: '#123456' } }],
+      },
+      [
+        [
+          { name: 'A', value: 1, color: '#00ff00' },
+          { name: 'B', value: 2 },
+          { name: 'C', value: 3 },
+        ],
+      ],
+    ) as Out
+    const colorFn = out.series[0]!.itemStyle.color
+    expect(colorFn({ dataIndex: 0, name: 'A', color: '#x' })).toBe('#00ff00')
+    expect(colorFn({ dataIndex: 1, name: 'B', color: '#x' })).toBe('#123456')
+    expect(colorFn({ dataIndex: 2, name: 'C', color: '#x' })).toBe(
+      dim('#123456'),
+    )
+  })
+
+  it('donut: keeps the per-data palette when no item colour is given', () => {
+    const merge = createPieOptionFactory({ theme })
+    const out = merge({ color: palette }, [
+      [
+        { name: 'A', value: 1, color: '#00ff00' },
+        { name: 'B', value: 2 },
+      ],
+    ]) as Out
+    const colorFn = out.series[0]!.itemStyle.color
+    expect(colorFn({ dataIndex: 0, name: 'A', color: '#x' })).toBe('#00ff00')
+    expect(colorFn({ dataIndex: 1, name: 'B', color: '#x' })).toBe('#p1')
+  })
+
+  it('donut: template itemStyle.color callback via optionsOverride', () => {
+    const factory = createPieOptionFactory({
+      theme,
+      optionsOverride: {
+        series: [
+          {
+            type: 'pie',
+            itemStyle: {
+              color: (p: { dataIndex: number }) => `#c${p.dataIndex}`,
+            },
+          },
+        ],
+      },
+    })
+    const out = factory(factory(undefined, undefined), [
+      [{ name: 'A', value: 1 }],
+    ]) as Out
+    expect(
+      out.series[0]!.itemStyle.color({ dataIndex: 0, name: 'A', color: '#x' }),
+    ).toBe('#c0')
+  })
+
+  it('multi-series bar fallback: datum colour wins over the series palette', () => {
+    const merge = createPieOptionFactory({ theme, selection: ['B'] })
+    const out = merge({ color: palette }, [
+      [{ name: 'A', value: 1, color: '#00ff00' }],
+      [{ name: 'A', value: 2 }],
+    ]) as Out
+    expect(
+      out.series[0]!.itemStyle.color({
+        dataIndex: 0,
+        seriesIndex: 0,
+        name: 'A',
+        color: '#x',
+      }),
+    ).toBe(dim('#00ff00'))
+    expect(
+      out.series[1]!.itemStyle.color({
+        dataIndex: 0,
+        seriesIndex: 1,
+        name: 'B',
+        color: '#x',
+      }),
+    ).toBe('#p1')
+  })
+})

package/src/widgets/pie/options.ts

@@ -12,6 +12,7 @@ import {
 } from '../utils/option-builders'
 import type { OptionFactory, OptionFactoryContext } from '../echart'
 import { mergeOptions, resolveThemeColor } from '../utils'
+import { createItemColorResolver } from '../utils/item-color'
 import type { WidgetSeries } from '../types'
 import type {
   PieEChartsOption,
@@ -168,6 +169,7 @@ export function createPieOptionFactory(
     return buildSingleSeriesPieFusion(
       option,
       seriesArr,
+      theme,
       radius,
       series,
       ctx,
@@ -185,6 +187,7 @@ export function createPieOptionFactory(
 function buildSingleSeriesPieFusion(
   option: EChartsOption,
   seriesArr: PieWidgetData,
+  theme: Theme,
   radius: readonly [string, string],
   series: readonly WidgetSeries[] | undefined,
   ctx: OptionFactoryContext | undefined,
@@ -231,14 +234,25 @@ function buildSingleSeriesPieFusion(
   // 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
-    const datum = params.value as { name?: string | number } | undefined
-    const name = datum?.name ?? params.name
-    return name != null && selectionSet.has(name)
-      ? base
-      : echarts.color.modifyAlpha(base, 0.15)
+  //
+  // The base colour is the slice's own `color`, else the template's
+  // `itemStyle.color`, else the per-data palette swatch.
+  const makeColorFn = (datums: readonly object[], template: unknown) => {
+    const baseColor = createItemColorResolver({
+      theme,
+      datums,
+      template,
+      fallback: resolvePaletteColor,
+    })
+    return (params: CallbackDataParams): string => {
+      const base = baseColor(params)
+      if (!selectionSet) return base
+      const datum = params.value as { name?: string | number } | undefined
+      const name = datum?.name ?? params.name
+      return name != null && selectionSet.has(name)
+        ? base
+        : echarts.color.modifyAlpha(base, 0.15)
+    }
   }
 
   // ECharts anchors EVERY slice's `position: 'center'` label at the same
@@ -316,7 +330,7 @@ function buildSingleSeriesPieFusion(
   return {
     ...option,
     dataset: seriesArr.map((s) => ({ source: s as readonly object[] })),
-    series: seriesArr.map((_, i) => {
+    series: seriesArr.map((s, i) => {
       const template =
         (seriesTemplates[i] as object | undefined) ??
         (broadcastTemplate as object)
@@ -344,7 +358,7 @@ function buildSingleSeriesPieFusion(
         },
         itemStyle: {
           ...templateItemStyle,
-          color: colorFn,
+          color: makeColorFn(s, templateObj),
         },
       }
     }),
@@ -419,17 +433,31 @@ function buildMultiSeriesBarFusion(
   const palette = Array.isArray(option.color)
     ? (option.color as readonly (string | undefined)[])
     : []
-  const barColorFn = (params: CallbackDataParams): string => {
+  // The base colour is the datum's own `color`, else the template's
+  // `itemStyle.color`, else the per-series palette swatch.
+  const seriesTemplates = Array.isArray(option.series) ? option.series : []
+  const paletteColor = (params: CallbackDataParams): string => {
     const seriesIdx = params.seriesIndex ?? 0
     const seriesSwatch =
       palette.length > 0 ? palette[seriesIdx % palette.length] : undefined
-    const base = (seriesSwatch ?? params.color) as string
-    if (!selectionSet) return base
-    const datum = params.value as { name?: string | number } | undefined
-    const name = datum?.name ?? params.name
-    return name != null && selectionSet.has(name)
-      ? base
-      : echarts.color.modifyAlpha(base, 0.15)
+    return (seriesSwatch ?? params.color) as string
+  }
+  const makeBarColorFn = (datums: readonly object[], template: unknown) => {
+    const baseColor = createItemColorResolver({
+      theme,
+      datums,
+      template,
+      fallback: paletteColor,
+    })
+    return (params: CallbackDataParams): string => {
+      const base = baseColor(params)
+      if (!selectionSet) return base
+      const datum = params.value as { name?: string | number } | undefined
+      const name = datum?.name ?? params.name
+      return name != null && selectionSet.has(name)
+        ? base
+        : echarts.color.modifyAlpha(base, 0.15)
+    }
   }
 
   return {
@@ -444,7 +472,7 @@ function buildMultiSeriesBarFusion(
     // Drop pie-specific structural keys that shouldn't render in the
     // bar fallback. ECharts ignores undefined keys, so this is a clean
     // override.
-    series: seriesArr.map((_, i) => {
+    series: seriesArr.map((s, i) => {
       const overrideColor = resolveThemeColor(theme, series?.[i]?.color)
       return {
         datasetIndex: i,
@@ -454,7 +482,9 @@ function buildMultiSeriesBarFusion(
         legendHoverLink: false,
         emphasis: { focus: 'series' },
         ...buildSeriesLabelConfig(formatter, 'x'),
-        itemStyle: { color: barColorFn },
+        itemStyle: {
+          color: makeBarColorFn(s, seriesTemplates[i] ?? seriesTemplates[0]),
+        },
         ...(overrideColor ? { color: overrideColor } : {}),
       }
     }),

package/src/widgets/pie/types.ts

@@ -6,6 +6,12 @@ import type { WidgetSeries } from '../types'
 export interface PieDatum {
   name: string | number
   value: number
+  /**
+   * Optional colour for this item (CSS colour or theme palette path such as
+   * `'primary.main'`). Wins over the template's `itemStyle.color` and the
+   * series colour; selection dimming still applies on top.
+   */
+  color?: string
 }
 
 /** Pie widget data — one slice array per series (rendered as side-by-side donuts). */

package/src/widgets/scatterplot/download.test.ts

@@ -61,6 +61,15 @@ describe('createScatterplotDownloadConfig', () => {
     )
   })
 
+  it('CSV writes x/y of object points (colour is not exported)', async () => {
+    const items = createScatterplotDownloadConfig({
+      filename: 's',
+      getData: () => [[{ x: 1, y: 10, color: '#f00' }, [2, 20]]],
+    })
+    await items.find((i) => i.id === 'csv')!.resolve({ id: null })
+    expect(csvText).toBe('series,x,y\nseries_1,1,10\nseries_1,2,20')
+  })
+
   it('CSV honours supplied seriesNames', async () => {
     const items = createScatterplotDownloadConfig({
       filename: 's',

package/src/widgets/scatterplot/download.ts

@@ -4,7 +4,8 @@ import {
   type DownloadItem,
   type WidgetDownloadArgs,
 } from '../actions/download'
-import type { ScatterplotWidgetData } from './types'
+import { getScatterplotXY } from './points'
+import type { ScatterplotItem, ScatterplotWidgetData } from './types'
 
 /**
  * Download menu items for the Scatterplot widget. Always includes a CSV item
@@ -13,7 +14,7 @@ import type { ScatterplotWidgetData } from './types'
  * `html2canvas`.
  */
 export function createScatterplotDownloadConfig(
-  args: WidgetDownloadArgs<ScatterplotWidgetData> & {
+  args: WidgetDownloadArgs<ScatterplotWidgetData<ScatterplotItem>> & {
     seriesNames?: readonly string[]
   },
 ): DownloadItem[] {
@@ -26,7 +27,8 @@ export function createScatterplotDownloadConfig(
         const rows: unknown[][] = [['series', 'x', 'y']]
         for (const [i, series] of data.entries()) {
           const seriesName = args.seriesNames?.[i] ?? `series_${i + 1}`
-          for (const [x, y] of series) {
+          for (const point of series) {
+            const [x, y] = getScatterplotXY(point)
             rows.push([seriesName, x, y])
           }
         }

package/src/widgets/scatterplot/index.ts

@@ -5,8 +5,11 @@ export {
   toRelativeScatterplotData,
   filterScatterplotByLockedPoints,
 } from './transforms'
+export { getScatterplotXY } from './points'
 export type {
   ScatterplotDatum,
+  ScatterplotPoint,
+  ScatterplotItem,
   ScatterplotWidgetData,
   ScatterplotOptionsInput,
   ScatterplotOptionFactoryInput,

package/src/widgets/scatterplot/options.test.ts

@@ -1,4 +1,5 @@
 import { describe, it, expect } from 'vitest'
+import * as echarts from 'echarts'
 import { createTheme, type Theme } from '@mui/material'
 import { createScatterplotOptionFactory, scatterplotOptions } from './options'
 
@@ -409,3 +410,80 @@ describe('createScatterplotOptionFactory', () => {
     expect(insideOnly.grid.right).toBe(baseline.grid.right)
   })
 })
+
+describe('createScatterplotOptionFactory — per-item colour', () => {
+  interface Out {
+    dataset: { source: number[][] }[]
+    series: { itemStyle: { color: (p: unknown) => string } }[]
+    xAxis: { min: number; max: number }
+    yAxis: { min: number; max: number }
+  }
+  const dim = (c: string) => echarts.color.modifyAlpha(c, 0.15)
+  const data = [
+    [{ x: 1, y: 2, color: '#00ff00' }, [3, 4] as const, { x: -5, y: 60 }],
+  ]
+
+  it('flattens object points to [x, y] rows and bounds them', () => {
+    const merge = createScatterplotOptionFactory({ theme })
+    const out = merge({}, data) as Out
+    expect(out.dataset[0]!.source).toEqual([
+      [1, 2],
+      [3, 4],
+      [-5, 60],
+    ])
+    expect(out.xAxis.min).toBeLessThanOrEqual(-5)
+    expect(out.xAxis.max).toBeGreaterThanOrEqual(3)
+    expect(out.yAxis.max).toBeGreaterThanOrEqual(60)
+  })
+
+  it('keeps tuple-only series as the dataset source', () => {
+    const merge = createScatterplotOptionFactory({ theme })
+    const series = [[1, 2] as const, [3, 4] as const]
+    const out = merge({}, [series]) as Out
+    expect(out.dataset[0]!.source).toBe(series)
+  })
+
+  it('point colour wins over the series colour; template next; dims', () => {
+    const merge = createScatterplotOptionFactory({
+      theme,
+      series: [{ name: 'S', color: '#0000ff' }],
+      selection: ['0:0', '0:1'],
+    })
+    const out = merge(
+      { series: [{ type: 'scatter', itemStyle: { color: '#123456' } }] },
+      data,
+    ) as Out
+    const colorFn = out.series[0]!.itemStyle.color
+    expect(colorFn({ dataIndex: 0, color: '#0000ff' })).toBe('#00ff00')
+    expect(colorFn({ dataIndex: 1, color: '#0000ff' })).toBe('#123456')
+    expect(colorFn({ dataIndex: 2, color: '#0000ff' })).toBe(dim('#123456'))
+  })
+
+  it('calls a function template itemStyle.color via optionsOverride', () => {
+    const factory = createScatterplotOptionFactory({
+      theme,
+      optionsOverride: {
+        series: [
+          {
+            type: 'scatter',
+            itemStyle: {
+              color: (p: { dataIndex: number }) => `#c${p.dataIndex}`,
+            },
+          },
+        ],
+      },
+    })
+    const out = factory(factory(undefined, undefined), [[[1, 2]]]) as Out
+    expect(out.series[0]!.itemStyle.color({ dataIndex: 0, color: '#x' })).toBe(
+      '#c0',
+    )
+  })
+
+  it('keeps the series / palette colour for plain tuples', () => {
+    const merge = createScatterplotOptionFactory({ theme })
+    const out = merge({}, [[[1, 2]]]) as Out
+    expect(
+      out.series[0]!.itemStyle.color({ dataIndex: 0, color: '#abc' }),
+    ).toBe('#abc')
+  })
+})

package/src/widgets/scatterplot/options.ts

@@ -12,10 +12,13 @@ import {
 import { ZOOM_LAYOUT } from '../actions/zoom-toggle'
 import type { OptionFactory } from '../echart'
 import { mergeOptions, resolveThemeColor } from '../utils'
+import { createItemColorResolver } from '../utils/item-color'
+import { getScatterplotXY } from './points'
 import type {
   ScatterplotEChartsOption,
   ScatterplotOptionFactoryInput,
   ScatterplotOptionsInput,
+  ScatterplotItem,
   ScatterplotWidgetData,
 } from './types'
 
@@ -156,7 +159,9 @@ export function createScatterplotOptionFactory(
         : structural
     }
 
-    const seriesArr = Array.isArray(data) ? (data as ScatterplotWidgetData) : []
+    const seriesArr = Array.isArray(data)
+      ? (data as ScatterplotWidgetData<ScatterplotItem>)
+      : []
     if (seriesArr.length === 0) {
       return { ...option, dataset: [], series: [] }
     }
@@ -198,15 +203,26 @@ export function createScatterplotOptionFactory(
     // Keeping the key always-present means a plain setOption merge swaps
     // the callback in place, no `replaceMerge` and no entry-animation
     // flash on selection on/off.
-    const makeDimColor =
-      (seriesIdx: number) => (params: CallbackDataParams) => {
-        const base = params.color as string
+    //
+    // The base colour is the point's own `color` (object points), else the
+    // template's `itemStyle.color`, else the series colour / palette.
+    const seriesTemplates = Array.isArray(option.series) ? option.series : []
+    const makeDimColor = (seriesIdx: number, datums: readonly unknown[]) => {
+      const baseColor = createItemColorResolver({
+        theme,
+        datums,
+        template: seriesTemplates[seriesIdx] ?? seriesTemplates[0],
+        fallback: (params) => params.color as string,
+      })
+      return (params: CallbackDataParams) => {
+        const base = baseColor(params)
         if (!selectionSet) return base
         const key = `${seriesIdx}:${params.dataIndex}`
         return selectionSet.has(key)
           ? base
           : echarts.color.modifyAlpha(base, 0.15)
       }
+    }
 
     // Zoom slider layout: when ZoomToggle has installed `dataZoom`,
     // reserve grid space and lift any x-slider above the legend (if
@@ -232,9 +248,15 @@ export function createScatterplotOptionFactory(
     return {
       ...option,
       // ECharts dataset.source wants a mutable [number, number][] shape; we
-      // hold readonly tuples internally, so cast at the boundary.
-      dataset: seriesArr.map((s) => ({ source: s as unknown as number[][] })),
-      series: seriesArr.map((_, i) => {
+      // hold readonly tuples internally, so cast at the boundary. Object
+      // points are flattened to `[x, y]` so the positional encode and the
+      // tooltip keep reading tuples.
+      dataset: seriesArr.map((s) => ({
+        source: (s.every(Array.isArray)
+          ? s
+          : s.map(getScatterplotXY)) as unknown as number[][],
+      })),
+      series: seriesArr.map((s, i) => {
         const overrideColor = resolveThemeColor(theme, series?.[i]?.color)
         return {
           type: 'scatter' as const,
@@ -243,7 +265,7 @@ export function createScatterplotOptionFactory(
           encode: { x: 0, y: 1 },
           symbolSize,
           emphasis: { focus: 'series' },
-          itemStyle: { color: makeDimColor(i) },
+          itemStyle: { color: makeDimColor(i, s) },
           ...(overrideColor ? { color: overrideColor } : {}),
         }
       }),
@@ -386,7 +408,9 @@ function buildScatterTooltipFormatter(
   })
 }
 
-function computeScatterBounds(seriesArr: ScatterplotWidgetData): {
+function computeScatterBounds(
+  seriesArr: ScatterplotWidgetData<ScatterplotItem>,
+): {
   niceMinX: number
   niceMaxX: number
   niceMinY: number
@@ -398,8 +422,8 @@ function computeScatterBounds(seriesArr: ScatterplotWidgetData): {
   let maxY = -Infinity
   for (const series of seriesArr) {
     for (const point of series) {
-      const x = point?.[0]
-      const y = point?.[1]
+      if (point == null) continue
+      const [x, y] = getScatterplotXY(point)
       if (typeof x === 'number' && Number.isFinite(x)) {
         if (x < minX) minX = x
         if (x > maxX) maxX = x

package/src/widgets/scatterplot/points.ts

@@ -0,0 +1,35 @@
+import type { ScatterplotItem } from './types'
+
+/** `[x, y]` of a {@link ScatterplotItem}, whichever form it takes. */
+export function getScatterplotXY(
+  point: ScatterplotItem,
+): readonly [number, number] {
+  return isTuple(point) ? point : [point.x, point.y]
+}
+
+/** Whether `v` is a valid {@link ScatterplotItem} with finite coordinates. */
+export function isScatterplotDatum(v: unknown): v is ScatterplotItem {
+  if (Array.isArray(v)) {
+    return v.length === 2 && isFiniteNumber(v[0]) && isFiniteNumber(v[1])
+  }
+  if (v == null || typeof v !== 'object') return false
+  const { x, y } = v as { x?: unknown; y?: unknown }
+  return isFiniteNumber(x) && isFiniteNumber(y)
+}
+
+/** Same point with new coordinates; keeps the object form (and `color`). */
+export function withScatterplotXY(
+  point: ScatterplotItem,
+  x: number,
+  y: number,
+): ScatterplotItem {
+  return isTuple(point) ? [x, y] : { ...point, x, y }
+}
+
+function isTuple(point: ScatterplotItem): point is readonly [number, number] {
+  return Array.isArray(point)
+}
+
+function isFiniteNumber(v: unknown): v is number {
+  return typeof v === 'number' && Number.isFinite(v)
+}

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

@@ -99,6 +99,25 @@ describe('toRelativeScatterplotData', () => {
   })
 })
 
+describe('toRelativeScatterplotData (object points)', () => {
+  it('relativizes y of object points, keeping x and colour', () => {
+    expect(
+      toRelativeScatterplotData([[{ x: 1, y: 5, color: '#f00' }, [2, 15]]]),
+    ).toEqual([[{ x: 1, y: 25, color: '#f00' }, [2, 75]]])
+  })
+})
+
+describe('filterScatterplotByLockedPoints (object points)', () => {
+  it('keeps locked object points as they are', () => {
+    expect(
+      filterScatterplotByLockedPoints(
+        [[{ x: 1, y: 2, color: '#f00' }, { x: 3, y: 4 }, [5, 6]]],
+        ['0:0', '0:2'],
+      ),
+    ).toEqual([[{ x: 1, y: 2, color: '#f00' }, [5, 6]]])
+  })
+})
+
 describe('filterScatterplotByLockedPoints', () => {
   const DATA = [
     [

package/src/widgets/scatterplot/transforms.ts

@@ -1,6 +1,14 @@
+import {
+  getScatterplotXY,
+  isScatterplotDatum,
+  withScatterplotXY,
+} from './points'
+import type { ScatterplotItem } from './types'
+
 /**
  * Scatterplot-specific `RelativeData` transform. Scatter data is
- * `[number, number][]` — each series is a list of `[x, y]` tuples.
+ * `ScatterplotItem[][]` — each series is a list of `[x, y]` tuples or
+ * `{ x, y, color? }` points (whose shape is kept).
  * Relative is a values-axis concept, so this rewrites `y` to its
  * share of the series's total `y` (0–100) and leaves `x` raw — x is
  * coordinate space, not part of the cohort total.
@@ -11,34 +19,31 @@
  * y values produce sane signed shares-of-magnitude. A series whose
  * total y-magnitude is zero (all-zero or empty input) is returned
  * unchanged so a stalled or empty data set doesn't show misleading 0%
- * values. Inputs whose shape isn't `[number, number][]` fall through
+ * values. Inputs whose shape isn't `ScatterplotItem[]` fall through
  * untouched.
  */
 export const toRelativeScatterplotData = (input: unknown): unknown => {
   if (!Array.isArray(input)) return input
   return input.map((series: unknown): unknown => {
-    if (!isXyTupleArray(series)) return series
-    const total = series.reduce((acc, [, y]) => acc + Math.abs(y), 0)
+    if (!isPointArray(series)) return series
+    const total = series.reduce(
+      (acc, p) => acc + Math.abs(getScatterplotXY(p)[1]),
+      0,
+    )
     if (total <= 0) return series
-    return series.map(([x, y]) => [x, (y / total) * 100] as [number, number])
+    return series.map((p) => {
+      const [x, y] = getScatterplotXY(p)
+      return withScatterplotXY(p, x, (y / total) * 100)
+    })
   })
 }
 
-function isXyTupleArray(v: unknown): v is [number, number][] {
-  if (!Array.isArray(v)) return false
-  return v.every(
-    (item) =>
-      Array.isArray(item) &&
-      item.length === 2 &&
-      typeof item[0] === 'number' &&
-      Number.isFinite(item[0]) &&
-      typeof item[1] === 'number' &&
-      Number.isFinite(item[1]),
-  )
+function isPointArray(v: unknown): v is ScatterplotItem[] {
+  return Array.isArray(v) && v.every(isScatterplotDatum)
 }
 
 /**
- * `LockSelection` filter for Scatterplot. Data is `[number, number][][]` —
+ * `LockSelection` filter for Scatterplot. Data is `ScatterplotItem[][]` —
  * 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,
@@ -53,7 +58,7 @@ export function filterScatterplotByLockedPoints(
   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
+    if (!isPointArray(series)) return series
     return series.filter((_, dataIndex) =>
       locked.has(`${seriesIndex}:${dataIndex}`),
     )

package/src/widgets/scatterplot/types.ts

@@ -5,8 +5,31 @@ import type { WidgetSeries } from '../types'
 /** A single point — `[x, y]` tuple. */
 export type ScatterplotDatum = readonly [number, number]
 
-/** Scatterplot widget data — array of series, each a list of `[x, y]` tuples. */
-export type ScatterplotWidgetData = readonly (readonly ScatterplotDatum[])[]
+/**
+ * Object form of a point, to give it its own colour. `color` (CSS colour or
+ * theme palette path such as `'primary.main'`) wins over the template's
+ * `itemStyle.color` and the series colour; selection dimming still applies.
+ */
+export interface ScatterplotPoint {
+  x: number
+  y: number
+  color?: string
+}
+
+/** Any accepted point: an `[x, y]` tuple or a {@link ScatterplotPoint}. */
+export type ScatterplotItem = ScatterplotDatum | ScatterplotPoint
+
+/**
+ * Scatterplot widget data — array of series, each a list of points.
+ *
+ * Defaults to `[x, y]` tuples so existing code that destructures points
+ * keeps type-checking; use `ScatterplotWidgetData<ScatterplotItem>` to also
+ * accept `{ x, y, color? }` points. Every scatterplot API (option factory,
+ * transforms, download) accepts both forms.
+ */
+export type ScatterplotWidgetData<
+  P extends ScatterplotItem = ScatterplotDatum,
+> = readonly (readonly P[])[]
 
 /** Inputs to the structural-only {@link scatterplotOptions} builder. */
 export interface ScatterplotOptionsInput {