@carto/ps-react-ui 4.8.0 → 4.9.1

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

@@ -1,5 +1,6 @@
 import type { Theme } from '@mui/material'
 import type { EChartsOption } from 'echarts'
+import type { WidgetSeries } from '../types'
 
 /** A single category entry in a bar series. */
 export interface BarDatum {
@@ -21,14 +22,18 @@ export interface BarOptionsInput {
  * Combined inputs for the option factory creator. Carries everything the
  * widget needs across BOTH phases — the structural-build (`theme`,
  * `formatter`, `labelFormatter`, `optionsOverride`) AND the data merge
- * (`seriesNames`, `selection`).
+ * (`series`, `selection`).
  */
 export interface BarOptionFactoryInput {
   theme: Theme
   formatter?: (value: number) => string
   labelFormatter?: (value: string | number) => string | number
-  /** Series names — drives the legend and `series[i].name`. */
-  seriesNames?: readonly string[]
+  /**
+   * Per-series metadata — drives the legend, `series[i].name`, and
+   * (when `color` is set) per-series `itemStyle.color`. Paired with the
+   * data series by index.
+   */
+  series?: readonly WidgetSeries[]
   /**
    * When set, every datum whose `name` is **not** in this list renders dimmed
    * (`itemStyle.opacity: 0.15`, matching `outOfBrush` styling). `null`/empty

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

@@ -1,3 +1,5 @@
+import type { WidgetSeries } from '../types'
+
 /** A single row in a Category widget. `name` is the category key. */
 export interface CategoryDataItem {
   name: string | number
@@ -29,10 +31,13 @@ export type CategoryKey = string | number
  * gracefully (extra entries ignored; missing entries get palette
  * defaults and are absent from the legend).
  */
-export interface CategorySeriesConfig {
-  name: string
-  color?: string
-}
+/**
+ * Per-series metadata. Type alias of the cross-widget
+ * {@link WidgetSeries} shape (`{ name, color? }`) so Category, Formula,
+ * Spread, and the echart-based widgets all consume the same input
+ * shape. Kept as a named export for backwards compatibility.
+ */
+export type CategorySeriesConfig = WidgetSeries
 
 /**
  * Labels for the "Other" overflow row (rendered when `data.length`

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

@@ -1,10 +1,14 @@
-/** Series metadata rendered as a coloured avatar at the start of a row. */
-export interface FormulaSeries {
-  /** Used for the avatar's first-letter glyph and as accessible label. */
-  name: string
-  /** Avatar background colour (any MUI palette path or CSS colour). */
-  color?: string
-}
+import type { WidgetSeries } from '../types'
+
+/**
+ * Series metadata rendered as a coloured avatar at the start of a row.
+ *
+ * Type alias of the cross-widget {@link WidgetSeries} shape so the same
+ * `{ name, color? }` object can drive Formula avatars, Spread avatars,
+ * Category legends, and echart-widget legends with no per-widget shape
+ * gymnastics. Kept as a named export for backwards compatibility.
+ */
+export type FormulaSeries = WidgetSeries
 
 export type DeltaSeverity = 'positive' | 'negative' | 'neutral'
 

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

@@ -213,11 +213,11 @@ describe('createHistogramOptionFactory (data → dataset merger)', () => {
     expect(out.yAxis.max).toBe(50)
   })
 
-  it('uses seriesNames for series[i].name when provided', () => {
+  it('uses series[i].name for series[i].name when provided', () => {
     const merge = createHistogramOptionFactory({
       theme,
       ticks: [0, 10, 20],
-      seriesNames: ['2024', '2025'],
+      series: [{ name: '2024' }, { name: '2025' }],
     })
     const out = merge({}, [
       [1, 2],
@@ -227,6 +227,20 @@ describe('createHistogramOptionFactory (data → dataset merger)', () => {
     expect(out.series[1]?.name).toBe('2025')
   })
 
+  it('applies series[i].color as a per-series itemStyle override', () => {
+    const merge = createHistogramOptionFactory({
+      theme,
+      ticks: [0, 10, 20],
+      series: [{ name: '2024', color: '#ff0000' }, { name: '2025' }],
+    })
+    const out = merge({}, [
+      [1, 2],
+      [3, 4],
+    ]) as { series: { color?: string }[] }
+    expect(out.series[0]?.color).toBe('#ff0000')
+    expect(out.series[1]?.color).toBeUndefined()
+  })
+
   it('applies labelFormatter to bin labels', () => {
     const merge = createHistogramOptionFactory({
       theme,

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

@@ -10,7 +10,7 @@ import {
 } from '../../widgets/utils/chart-config'
 import { ZOOM_LAYOUT } from '../actions/zoom-toggle'
 import type { OptionFactory } from '../echart'
-import { mergeOptions } from '../utils'
+import { mergeOptions, resolveThemeColor } from '../utils'
 import { positionDataZoomForLegend } from '../utils/data-zoom-layout'
 import type {
   HistogramEChartsOption,
@@ -152,8 +152,7 @@ export function histogramOptions({
 export function createHistogramOptionFactory(
   options: HistogramOptionFactoryInput,
 ): OptionFactory {
-  const { theme, formatter, ticks, seriesNames, labelFormatter, selection } =
-    options
+  const { theme, formatter, ticks, series, labelFormatter, selection } = options
   const optionsOverride = options.optionsOverride
   const selectionSet =
     selection && selection.length > 0 ? new Set<number>(selection) : null
@@ -253,15 +252,17 @@ export function createHistogramOptionFactory(
         const template =
           (seriesTemplates[i] as object | undefined) ??
           (broadcastTemplate as object)
+        const overrideColor = resolveThemeColor(theme, series?.[i]?.color)
         return {
           ...(typeof template === 'object' ? template : {}),
           type: 'bar' as const,
           datasetIndex: i,
-          name: seriesNames?.[i] ?? `Series ${i + 1}`,
+          name: series?.[i]?.name ?? `Series ${i + 1}`,
           encode: { x: 0, y: 1 },
           barCategoryGap: '0%',
           emphasis: { focus: 'series' },
           itemStyle: dimItemStyle,
+          ...(overrideColor ? { color: overrideColor } : {}),
         }
       }),
       legend: { ...baseLegend, show: hasLegend },

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

@@ -1,5 +1,6 @@
 import type { Theme } from '@mui/material'
 import type { EChartsOption } from 'echarts'
+import type { WidgetSeries } from '../types'
 
 /**
  * Histogram widget data — array of series, each a flat array of bin counts.
@@ -19,15 +20,18 @@ export interface HistogramOptionsInput {
  * Combined inputs for the histogram option factory creator. Carries
  * everything the widget needs across BOTH phases — the structural-build
  * (`theme`, `formatter`, `optionsOverride`) AND the data merge (`ticks`,
- * `seriesNames`, `labelFormatter`, `selection`).
+ * `series`, `labelFormatter`, `selection`).
  */
 export interface HistogramOptionFactoryInput {
   theme: Theme
   formatter?: (value: number) => string
   /** Bin boundaries — length = bins + 1. */
   ticks: readonly number[]
-  /** Optional series names — drives the legend. */
-  seriesNames?: readonly string[]
+  /**
+   * Per-series metadata — drives the legend, `series[i].name`, and
+   * (when `color` is set) a per-series colour override on the bars.
+   */
+  series?: readonly WidgetSeries[]
   /**
    * Bin-range label transform (e.g. `"0–10"` → `"[0–10)"`). Distinct from
    * the standard `OptionFactoryContext.labelFormatter` (which operates on

package/src/widgets-v2/index.ts

@@ -199,3 +199,6 @@ export type {
   TableSortDirection,
   TableSortState,
 } from './table'
+
+// Canonical cross-widget series shape — see `widgets-v2/types.ts`.
+export type { WidgetSeries } from './types'

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

@@ -147,8 +147,11 @@ describe('createPieOptionFactory — single-series (donut)', () => {
     expect(single.legend?.show).toBe(true)
   })
 
-  it('uses seriesNames[0] for the single series name when provided', () => {
-    const merge = createPieOptionFactory({ theme, seriesNames: ['2024'] })
+  it('uses series[0].name for the single series name when provided', () => {
+    const merge = createPieOptionFactory({
+      theme,
+      series: [{ name: '2024' }],
+    })
     const out = merge({}, [[{ name: 'A', value: 1 }]]) as {
       series: { name: string }[]
     }
@@ -507,16 +510,29 @@ describe('createPieOptionFactory — multi-series fallback (horizontal bar)', ()
     ).toBe('#BBB')
   })
 
-  it('uses seriesNames for series.name when provided', () => {
+  it('uses series[i].name for series.name when provided', () => {
     const merge = createPieOptionFactory({
       theme,
-      seriesNames: ['2024', '2025'],
+      series: [{ name: '2024' }, { name: '2025' }],
     })
     const out = merge({}, MULTI) as { series: { name: string }[] }
     expect(out.series[0]?.name).toBe('2024')
     expect(out.series[1]?.name).toBe('2025')
   })
 
+  it('applies series[i].color as a per-series colour in the multi-series bar fusion', () => {
+    const merge = createPieOptionFactory({
+      theme,
+      series: [
+        { name: '2024', color: '#ff0000' },
+        { name: '2025' }, // no color
+      ],
+    })
+    const out = merge({}, MULTI) as { series: { color?: string }[] }
+    expect(out.series[0]?.color).toBe('#ff0000')
+    expect(out.series[1]?.color).toBeUndefined()
+  })
+
   it('keeps legend.show = true (the bar layout still surfaces series in the legend)', () => {
     const merge = createPieOptionFactory({ theme })
     const out = merge({}, MULTI) as { legend?: { show?: boolean } }

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

@@ -11,7 +11,8 @@ import {
   niceNum,
 } from '../../widgets/utils/chart-config'
 import type { OptionFactory, OptionFactoryContext } from '../echart'
-import { mergeOptions } from '../utils'
+import { mergeOptions, resolveThemeColor } from '../utils'
+import type { WidgetSeries } from '../types'
 import type {
   PieEChartsOption,
   PieOptionFactoryInput,
@@ -125,8 +126,7 @@ export function pieOptions({
 export function createPieOptionFactory(
   options: PieOptionFactoryInput,
 ): OptionFactory {
-  const { theme, formatter, labelFormatter, optionsOverride, seriesNames } =
-    options
+  const { theme, formatter, labelFormatter, optionsOverride, series } = options
   const radius = options.radius ?? DEFAULT_RADIUS
   const selection = options.selection
   const selectionSet =
@@ -153,7 +153,7 @@ export function createPieOptionFactory(
         option,
         seriesArr,
         theme,
-        seriesNames,
+        series,
         ctx,
         selectionSet,
       )
@@ -162,7 +162,7 @@ export function createPieOptionFactory(
       option,
       seriesArr,
       radius,
-      seriesNames,
+      series,
       ctx,
       selectionSet,
     )
@@ -179,7 +179,7 @@ function buildSingleSeriesPieFusion(
   option: EChartsOption,
   seriesArr: PieWidgetData,
   radius: readonly [string, string],
-  seriesNames: readonly string[] | undefined,
+  series: readonly WidgetSeries[] | undefined,
   ctx: OptionFactoryContext | undefined,
   selectionSet: Set<string | number> | null,
 ): EChartsOption {
@@ -270,7 +270,7 @@ function buildSingleSeriesPieFusion(
         ...templateObj,
         type: 'pie' as const,
         datasetIndex: i,
-        name: seriesNames?.[i] ?? `Series ${i + 1}`,
+        name: series?.[i]?.name ?? `Series ${i + 1}`,
         radius: [...radius],
         // Lift the donut up so the bottom-anchored legend has the
         // vertical real estate to wrap to multiple rows for long
@@ -312,7 +312,7 @@ function buildMultiSeriesBarFusion(
   option: EChartsOption,
   seriesArr: PieWidgetData,
   theme: Theme,
-  seriesNames: readonly string[] | undefined,
+  series: readonly WidgetSeries[] | undefined,
   ctx: OptionFactoryContext | undefined,
   selectionSet: Set<string | number> | null,
 ): EChartsOption {
@@ -365,15 +365,19 @@ 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) => ({
-      datasetIndex: i,
-      type: 'bar' as const,
-      name: seriesNames?.[i] ?? `Series ${i + 1}`,
-      barMaxWidth: 100,
-      emphasis: { focus: 'series' },
-      ...buildSeriesLabelConfig(formatter, 'x'),
-      itemStyle: { color: barColorFn },
-    })),
+    series: seriesArr.map((_, i) => {
+      const overrideColor = resolveThemeColor(theme, series?.[i]?.color)
+      return {
+        datasetIndex: i,
+        type: 'bar' as const,
+        name: series?.[i]?.name ?? `Series ${i + 1}`,
+        barMaxWidth: 100,
+        emphasis: { focus: 'series' },
+        ...buildSeriesLabelConfig(formatter, 'x'),
+        itemStyle: { color: barColorFn },
+        ...(overrideColor ? { color: overrideColor } : {}),
+      }
+    }),
     xAxis: {
       type: 'value',
       // Closures over the pre-computed nice bounds — ECharts calls them

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

@@ -1,5 +1,6 @@
 import type { Theme } from '@mui/material'
 import type { EChartsOption } from 'echarts'
+import type { WidgetSeries } from '../types'
 
 /** A single slice of a pie series. */
 export interface PieDatum {
@@ -23,7 +24,7 @@ export interface PieOptionsInput {
  * Combined inputs for the pie option factory creator. Carries everything
  * the widget needs across BOTH phases — the structural-build (`theme`,
  * `formatter`, `labelFormatter`, `optionsOverride`) AND the data merge
- * (`seriesNames`, `radius`, `selection`). The merger emits different
+ * (`series`, `radius`, `selection`). The merger emits different
  * chart shapes by series count: single → donut, multi → horizontal-bar
  * fallback (mirrors v1 pie); both branches read `theme` for styling.
  */
@@ -31,8 +32,14 @@ export interface PieOptionFactoryInput {
   theme: Theme
   formatter?: (value: number) => string
   labelFormatter?: (value: string | number) => string | number
-  /** Series names — drives the legend and series.name. */
-  seriesNames?: readonly string[]
+  /**
+   * Per-series metadata — drives the legend, `series[i].name`, and (in
+   * the multi-series bar fallback) per-series colour overrides.
+   * Single-series donuts always use the per-slice palette regardless of
+   * any `series[0].color`, since the donut palette is keyed by data
+   * index, not series index.
+   */
+  series?: readonly WidgetSeries[]
   /**
    * Inner/outer radius (percent). Default `['58%', '74%']` produces a
    * donut sized to leave room for the wrappable bottom legend. Set

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

@@ -106,20 +106,26 @@ describe('<RangeUI>', () => {
     ).toBe(true)
   })
 
-  it('commits a typed value to onChange on Enter, clamped to [min, max]', () => {
+  it('commits a typed value on Enter (fires both onChange and onChangeCommitted), clamped to [min, max]', () => {
+    // A text-input edit is both a value change and a final commit, so it
+    // notifies `onChange` AND `onChangeCommitted` — consumers that only wired
+    // `onChange` (the pre-`onChangeCommitted` API) still update.
     const onChange = vi.fn()
+    const onChangeCommitted = vi.fn()
     render(
       <RangeUI
         items={[{ min: 0, max: 100, value: [10, 90] }]}
         onChange={onChange}
+        onChangeCommitted={onChangeCommitted}
       />,
     )
     const min = screen.getByLabelText('Minimum value')
     // Type 150 — should clamp to max (100), then preserve ordering (low <= high).
     fireEvent.change(min, { target: { value: '150' } })
     fireEvent.keyDown(min, { key: 'Enter' })
+    expect(onChangeCommitted).toHaveBeenCalled()
     expect(onChange).toHaveBeenCalled()
-    const last = onChange.mock.calls.at(-1) as [
+    const last = onChangeCommitted.mock.calls.at(-1) as [
       number,
       readonly [number, number],
     ]

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

@@ -11,11 +11,19 @@ import { styles } from './style'
 export interface RangeUIProps {
   items: readonly RangeDataItem[]
   /**
-   * Fires when the user drags a thumb or commits a new value via the text
-   * inputs. Per the destination-owned principle, the consumer owns the
-   * value — this widget surfaces changes but does not store them.
+   * Fires on every pointer tick while a thumb is being dragged (mirrors
+   * MUI `<Slider>`'s `onChange`). Use this to update local UI state —
+   * not to persist expensive operations like remote queries.
    */
   onChange?: (index: number, value: RangeItemValue) => void
+  /**
+   * Fires once when the user *releases* a slider thumb after dragging,
+   * after an arrow-key adjustment commits, or when the text inputs
+   * blur / Enter. Mirrors MUI `<Slider>`'s `onChangeCommitted`. Use
+   * this for side-effects you want to throttle to "drag end" — e.g.
+   * writing the value to a source filter that triggers refetches.
+   */
+  onChangeCommitted?: (index: number, value: RangeItemValue) => void
   /** Number formatter for the slider tooltip and the text input display. */
   formatter?: (value: number) => string
 }
@@ -28,7 +36,12 @@ type Bound = 'min' | 'max'
  * UX. Each item is always a two-thumb range; supply `value` to seed the
  * starting selection, otherwise it defaults to `[min, max]`.
  */
-export function RangeUI({ items, onChange, formatter }: RangeUIProps) {
+export function RangeUI({
+  items,
+  onChange,
+  onChangeCommitted,
+  formatter,
+}: RangeUIProps) {
   const fmt = formatter ?? ((n: number) => String(n))
   return (
     <Box sx={styles.root}>
@@ -42,6 +55,7 @@ export function RangeUI({ items, onChange, formatter }: RangeUIProps) {
           item={item}
           fmt={fmt}
           onChange={onChange}
+          onChangeCommitted={onChangeCommitted}
         />
       ))}
     </Box>
@@ -53,23 +67,57 @@ interface RangeRowProps {
   item: RangeDataItem
   fmt: (n: number) => string
   onChange?: (index: number, value: RangeItemValue) => void
+  onChangeCommitted?: (index: number, value: RangeItemValue) => void
 }
 
-function RangeRow({ index, item, fmt, onChange }: RangeRowProps) {
+function RangeRow({
+  index,
+  item,
+  fmt,
+  onChange,
+  onChangeCommitted,
+}: RangeRowProps) {
   const current: readonly [number, number] = item.value ?? [item.min, item.max]
   const [editing, setEditing] = useState<'' | Bound>('')
 
-  const commit = useCallback(
-    (next: readonly [number, number]) => {
-      // Clamp inside [min, max] and keep `low <= high`.
+  // Clamp inside [min, max] and keep `low <= high`. Pulled out so both the
+  // live `onChange` path and the commit path share the same normalization.
+  const normalize = useCallback(
+    (next: readonly [number, number]): readonly [number, number] => {
       const [lowRaw, highRaw] = next
       const low = Math.min(Math.max(lowRaw, item.min), item.max)
       const high = Math.min(Math.max(highRaw, item.min), item.max)
-      const ordered: readonly [number, number] =
-        low <= high ? [low, high] : [high, low]
-      onChange?.(index, ordered)
+      return low <= high ? [low, high] : [high, low]
+    },
+    [item.min, item.max],
+  )
+
+  const commit = useCallback(
+    (next: readonly [number, number]) => {
+      onChange?.(index, normalize(next))
+    },
+    [index, normalize, onChange],
+  )
+
+  const commitFinal = useCallback(
+    (next: readonly [number, number]) => {
+      onChangeCommitted?.(index, normalize(next))
     },
-    [index, item.min, item.max, onChange],
+    [index, normalize, onChangeCommitted],
+  )
+
+  // A text-input commit (blur / Enter) is both a value change AND a final
+  // commit, so it fires `onChange` *and* `onChangeCommitted`. Firing both
+  // keeps the widget responsive for consumers that only wired `onChange`
+  // (the pre-`onChangeCommitted` API) — without it, typing a value and
+  // pressing Enter would silently no-op for them.
+  const commitText = useCallback(
+    (next: readonly [number, number]) => {
+      const value = normalize(next)
+      onChange?.(index, value)
+      onChangeCommitted?.(index, value)
+    },
+    [index, normalize, onChange, onChangeCommitted],
   )
 
   const handleSlider = (_: Event, raw: number | number[]) => {
@@ -81,6 +129,16 @@ function RangeRow({ index, item, fmt, onChange }: RangeRowProps) {
     commit([low, high])
   }
 
+  const handleSliderCommitted = (
+    _: Event | React.SyntheticEvent,
+    raw: number | number[],
+  ) => {
+    if (!Array.isArray(raw)) return
+    const low = raw[0] ?? item.min
+    const high = raw[1] ?? item.max
+    commitFinal([low, high])
+  }
+
   return (
     <Box sx={styles.item}>
       <Box sx={styles.sliderContainer}>
@@ -98,9 +156,13 @@ function RangeRow({ index, item, fmt, onChange }: RangeRowProps) {
           valueLabelDisplay='auto'
           valueLabelFormat={fmt}
           onChange={handleSlider}
+          onChangeCommitted={handleSliderCommitted}
         />
       </Box>
       <Box sx={styles.inputsRow}>
+        {/* Text-input commits (blur / Enter) are final, but also notify
+            `onChange` — see `commitText` — so consumers that only wired
+            `onChange` still update on a typed value. */}
         <BoundInput
           // Bumping the key on a fresh external value resets the local
           // editing state — matches v1's RangeItem behaviour.
@@ -111,7 +173,7 @@ function RangeRow({ index, item, fmt, onChange }: RangeRowProps) {
           fmt={fmt}
           editing={editing}
           setEditing={setEditing}
-          commit={commit}
+          commit={commitText}
           current={current}
           ariaLabel='Minimum value'
         />
@@ -123,7 +185,7 @@ function RangeRow({ index, item, fmt, onChange }: RangeRowProps) {
           fmt={fmt}
           editing={editing}
           setEditing={setEditing}
-          commit={commit}
+          commit={commitText}
           current={current}
           ariaLabel='Maximum value'
         />
@@ -144,6 +206,11 @@ interface BoundInputProps {
   fmt: (n: number) => string
   editing: '' | Bound
   setEditing: (next: '' | Bound) => void
+  /**
+   * Called when the user commits a new value (blur / Enter). Text input
+   * edits never produce intermediate "live" values, so the consumer
+   * only needs one callback — the row wires this to `commitFinal`.
+   */
   commit: (next: readonly [number, number]) => void
   current: readonly [number, number]
   ariaLabel: string

package/src/widgets-v2/range/range.tsx

@@ -17,23 +17,28 @@ const rangeSelector = (s: {
 
 export interface RangeProps {
   /**
-   * Fires when the user moves a slider thumb or commits a new value via the
-   * text inputs. Receives the item index in `state.data` and the new
-   * `[low, high]` tuple. The consumer owns the data state — the widget
-   * surfaces changes but does not persist them.
+   * Fires on every pointer tick while a thumb is being dragged. Use this
+   * for cheap UI updates (local state, optimistic display).
    */
   onChange?: (index: number, value: RangeItemValue) => void
+  /**
+   * Fires once when the user *releases* a slider thumb (or when the text
+   * inputs blur / Enter, or when an arrow-key adjustment settles). Use
+   * this for expensive side-effects you want throttled to drag end —
+   * e.g. writing the value to a source filter that refetches widgets.
+   */
+  onChangeCommitted?: (index: number, value: RangeItemValue) => void
 }
 
 /**
  * Stateful Range bridge — reads `data` (post-pipeline) and `formatter` from
  * the per-widget store and forwards them to the pure {@link RangeUI}. Per
  * the destination-owned principle, value changes flow back through
- * `onChange` — the consumer is expected to update the data prop on
- * `<Provider>`. Use `disabled` on individual `RangeDataItem`s to disable
- * specific rows.
+ * `onChange` (per-tick) and `onChangeCommitted` (drag end) — the consumer
+ * is expected to update the data prop on `<Provider>`. Use `disabled` on
+ * individual `RangeDataItem`s to disable specific rows.
  */
-export function Range({ onChange }: RangeProps) {
+export function Range({ onChange, onChangeCommitted }: RangeProps) {
   const id = useWidgetId()
   const slice = useWidgetShallow(id, rangeSelector)
   return (
@@ -41,6 +46,7 @@ export function Range({ onChange }: RangeProps) {
       items={slice.data}
       formatter={slice.formatter}
       onChange={onChange}
+      onChangeCommitted={onChangeCommitted}
     />
   )
 }

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

@@ -151,10 +151,10 @@ describe('createScatterplotOptionFactory', () => {
     expect(multi.legend.show).toBe(true)
   })
 
-  it('uses seriesNames for series.name when provided', () => {
+  it('uses series[i].name for series.name when provided', () => {
     const merge = createScatterplotOptionFactory({
       theme,
-      seriesNames: ['Group A', 'Group B'],
+      series: [{ name: 'Group A' }, { name: 'Group B' }],
     })
     const out = merge({}, [[[1, 2]], [[3, 4]]]) as {
       series: { name: string }[]
@@ -163,7 +163,19 @@ describe('createScatterplotOptionFactory', () => {
     expect(out.series[1]?.name).toBe('Group B')
   })
 
-  it('falls back to `Series N` naming when seriesNames is missing', () => {
+  it('applies series[i].color as a per-series colour override', () => {
+    const merge = createScatterplotOptionFactory({
+      theme,
+      series: [{ name: 'Group A', color: '#ff0000' }, { name: 'Group B' }],
+    })
+    const out = merge({}, [[[1, 2]], [[3, 4]]]) as {
+      series: { color?: string }[]
+    }
+    expect(out.series[0]?.color).toBe('#ff0000')
+    expect(out.series[1]?.color).toBeUndefined()
+  })
+
+  it('falls back to `Series N` naming when series is missing', () => {
     const merge = createScatterplotOptionFactory({ theme })
     const out = merge({}, [[[1, 2]], [[3, 4]]]) as {
       series: { name: string }[]