@carto/ps-react-ui 4.25.0 → 4.27.0

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

@@ -12,12 +12,16 @@ 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'
+import { fixedAxisBounds } from '../actions/relative-data/scale'
 
 /**
  * Builds the **structural** ECharts option for a scatterplot widget — both
@@ -156,7 +160,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: [] }
     }
@@ -184,8 +190,12 @@ export function createScatterplotOptionFactory(
 
     const reactiveFormatter = ctx?.formatter
 
-    const { niceMinX, niceMaxX, niceMinY, niceMaxY } =
-      computeScatterBounds(seriesArr)
+    const { niceMinX, niceMaxX, niceMinY, niceMaxY } = computeScatterBounds(
+      seriesArr,
+      // A config transform (RelativeData's `'total'` scale) may pin the
+      // y ends; each applies only on the side the data reaches.
+      fixedAxisBounds(baseYAxis),
+    )
 
     // Dim non-selected points via `series.itemStyle.color`. The selection
     // key is `${seriesIndex}:${dataIndex}`; we read those off the params
@@ -198,15 +208,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 +253,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 +270,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 +413,10 @@ function buildScatterTooltipFormatter(
   })
 }
 
-function computeScatterBounds(seriesArr: ScatterplotWidgetData): {
+function computeScatterBounds(
+  seriesArr: ScatterplotWidgetData<ScatterplotItem>,
+  fixedY: { min?: number; max?: number } = {},
+): {
   niceMinX: number
   niceMaxX: number
   niceMinY: number
@@ -398,8 +428,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
@@ -415,8 +445,16 @@ function computeScatterBounds(seriesArr: ScatterplotWidgetData): {
   // negative mins, and floor max=0 to 1 so the chart always has range.
   // Scatter can have free coordinates so we apply this per-axis.
   const niceMaxX = Number.isFinite(maxX) ? (maxX <= 0 ? 1 : niceNum(maxX)) : 1
-  const niceMaxY = Number.isFinite(maxY) ? (maxY <= 0 ? 1 : niceNum(maxY)) : 1
+  const niceMaxY = Number.isFinite(maxY)
+    ? maxY <= 0
+      ? 1
+      : (fixedY.max ?? niceNum(maxY))
+    : 1
   const niceMinX = Number.isFinite(minX) ? (minX < 0 ? niceNum(minX) : 0) : 0
-  const niceMinY = Number.isFinite(minY) ? (minY < 0 ? niceNum(minY) : 0) : 0
+  const niceMinY = Number.isFinite(minY)
+    ? minY < 0
+      ? (fixedY.min ?? niceNum(minY))
+      : 0
+    : 0
   return { niceMinX, niceMaxX, niceMinY, niceMaxY }
 }

package/src/widgets-v2/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-v2/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-v2/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-v2/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 {

package/src/widgets-v2/timeseries/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 { createTimeseriesOptionFactory, timeseriesOptions } from './options'
 
@@ -397,3 +398,67 @@ describe('createTimeseriesOptionFactory', () => {
     expect(out.grid.bottom).toBe(96)
   })
 })
+
+describe('createTimeseriesOptionFactory — per-item colour', () => {
+  interface Out {
+    series: {
+      showSymbol: boolean
+      itemStyle: { color: (p: unknown) => string }
+    }[]
+  }
+  const data = [
+    [
+      { name: 1, value: 1, color: '#00ff00' },
+      { name: 2, value: 2 },
+    ],
+  ]
+  const p = (dataIndex: number, name: number) => ({
+    dataIndex,
+    color: '#0000ff',
+    value: { name },
+  })
+  const dim = (c: string) => echarts.color.modifyAlpha(c, 0.15)
+
+  it('datum colour wins over the series colour; template next', () => {
+    const merge = createTimeseriesOptionFactory({
+      theme,
+      series: [{ name: 'S', color: '#0000ff' }],
+    })
+    const out = merge(
+      { series: [{ type: 'line', itemStyle: { color: '#123456' } }] },
+      data,
+    ) as Out
+    const colorFn = out.series[0]!.itemStyle.color
+    expect(colorFn(p(0, 1))).toBe('#00ff00')
+    expect(colorFn(p(1, 2))).toBe('#123456')
+  })
+
+  it('calls a function template itemStyle.color', () => {
+    const factory = createTimeseriesOptionFactory({
+      theme,
+      optionsOverride: {
+        series: [{ type: 'line', itemStyle: { color: () => '#ff0000' } }],
+      },
+    })
+    const out = factory(factory(undefined, undefined), [
+      [{ name: 1, value: 1 }],
+    ]) as Out
+    expect(out.series[0]!.itemStyle.color(p(0, 1))).toBe('#ff0000')
+  })
+
+  it('dims item colours outside the selection', () => {
+    const merge = createTimeseriesOptionFactory({ theme, selection: [2] })
+    const out = merge({}, data) as Out
+    const colorFn = out.series[0]!.itemStyle.color
+    expect(colorFn(p(0, 1))).toBe(dim('#00ff00'))
+    expect(colorFn(p(1, 2))).toBe('#0000ff')
+  })
+
+  it('shows symbols when a point has its own colour, not otherwise', () => {
+    const merge = createTimeseriesOptionFactory({ theme })
+    expect((merge({}, data) as Out).series[0]!.showSymbol).toBe(true)
+    const plain = merge({}, [[{ name: 1, value: 1 }]]) as Out
+    expect(plain.series[0]!.showSymbol).toBe(false)
+    expect(plain.series[0]!.itemStyle.color(p(0, 1))).toBe('#0000ff')
+  })
+})

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

@@ -12,6 +12,7 @@ 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 { positionDataZoomForLegend } from '../utils/data-zoom-layout'
 import type {
   TimeseriesEChartsOption,
@@ -19,6 +20,7 @@ import type {
   TimeseriesOptionsInput,
   TimeseriesWidgetData,
 } from './types'
+import { fixedAxisBounds } from '../actions/relative-data/scale'
 
 /**
  * Builds the **structural** ECharts option for a timeseries widget —
@@ -187,6 +189,7 @@ export function createTimeseriesOptionFactory(
       typeof option.yAxis === 'object' && !Array.isArray(option.yAxis)
         ? option.yAxis
         : {}
+    const fixedY = fixedAxisBounds(baseYAxis)
     const baseGrid =
       typeof option.grid === 'object' && !Array.isArray(option.grid)
         ? option.grid
@@ -237,24 +240,39 @@ export function createTimeseriesOptionFactory(
     // and points would stay dimmed forever after an external clear.
     // Always emitting lets normal merge swap the callback in place, no
     // `replaceMerge` and no entry-animation flash on selection on/off.
-    const dimItemStyle = {
-      color: (params: CallbackDataParams) => {
-        const datum = params.value as
-          | { name?: Date | number | string }
-          | undefined
-        const raw = datum?.name
-        const base = params.color as string
-        if (!selectionSet || raw == null) return base
-        return selectionSet.has(normalizeName(raw))
-          ? base
-          : echarts.color.modifyAlpha(base, 0.15)
-      },
+    //
+    // The base colour is the point's own `color`, else the template's
+    // `itemStyle.color`, else the series colour / palette (`params.color`).
+    const makeDimItemStyle = (datums: readonly object[], template: unknown) => {
+      const baseColor = createItemColorResolver({
+        theme,
+        datums,
+        template,
+        fallback: (params) => params.color as string,
+      })
+      return {
+        color: (params: CallbackDataParams) => {
+          const datum = params.value as
+            { name?: Date | number | string } | undefined
+          const raw = datum?.name
+          const base = baseColor(params)
+          if (!selectionSet || raw == null) return base
+          return selectionSet.has(normalizeName(raw))
+            ? base
+            : echarts.color.modifyAlpha(base, 0.15)
+        },
+      }
     }
+    // Per-point colours only show on markers, so surface them whenever a
+    // point carries its own `color` (same reason as the selection case).
+    const hasDatumColor = seriesArr.some((s) =>
+      s.some((d) => typeof d?.color === 'string' && d.color !== ''),
+    )
 
     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)
@@ -272,10 +290,10 @@ export function createTimeseriesOptionFactory(
           // When a selection is active, surface markers so the per-point
           // color callback has something to dim — a continuous line would
           // hide the visual selection feedback.
-          showSymbol: selectionSet != null,
+          showSymbol: selectionSet != null || hasDatumColor,
           ...(area ? { areaStyle: {} } : {}),
           emphasis: { focus: 'series' },
-          itemStyle: dimItemStyle,
+          itemStyle: makeDimItemStyle(s, template),
           ...(overrideColor
             ? { color: overrideColor, lineStyle: { color: overrideColor } }
             : {}),
@@ -286,12 +304,14 @@ export function createTimeseriesOptionFactory(
       ...(dataZoomLayout ? { dataZoom: dataZoomLayout } : {}),
       yAxis: {
         ...baseYAxis,
+        // A config transform (RelativeData's `'total'` scale) may pin the
+        // ends; each applies only on the side the data reaches.
         min: (extent: { min: number }) => {
-          niceMin = extent.min < 0 ? niceNum(extent.min) : 0
+          niceMin = extent.min < 0 ? (fixedY.min ?? niceNum(extent.min)) : 0
           return niceMin
         },
         max: (extent: { min: number; max: number }) => {
-          niceMax = extent.max <= 0 ? 1 : niceNum(extent.max)
+          niceMax = extent.max <= 0 ? 1 : (fixedY.max ?? niceNum(extent.max))
           return niceMax
         },
         axisLabel: {
@@ -327,8 +347,7 @@ function buildTimeseriesTooltipFormatter(
 ) {
   return createTooltipFormatter((item) => {
     const row = item.value as
-      | { name?: Date | number | string; value?: number }
-      | undefined
+      { name?: Date | number | string; value?: number } | undefined
     const raw = row?.value
     const formattedValue =
       typeof raw === 'number' && formatter ? formatter(raw) : (raw ?? '')

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

@@ -10,6 +10,12 @@ import type { WidgetSeries } from '../types'
 export interface TimeseriesDatum {
   name: Date | number | string
   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
 }
 
 /** Timeseries widget data — one array of points per series. */

package/src/widgets-v2/utils/item-color.test.ts

@@ -0,0 +1,74 @@
+import { describe, it, expect, vi } from 'vitest'
+import { createTheme } from '@mui/material'
+import type { CallbackDataParams } from 'echarts/types/dist/shared'
+import { createItemColorResolver } from './item-color'
+
+const theme = createTheme({ palette: { primary: { main: '#1976d2' } } })
+const params = (dataIndex: number) =>
+  ({ dataIndex, color: '#fallback' }) as unknown as CallbackDataParams
+const fallback = (p: CallbackDataParams) => p.color as string
+
+describe('createItemColorResolver', () => {
+  it('uses the datum colour first', () => {
+    const resolve = createItemColorResolver({
+      theme,
+      datums: [{ color: '#00ff00' }],
+      template: { itemStyle: { color: '#123456' } },
+      fallback,
+    })
+    expect(resolve(params(0))).toBe('#00ff00')
+  })
+
+  it('uses a string template itemStyle.color when the datum has none', () => {
+    const resolve = createItemColorResolver({
+      theme,
+      datums: [{}, 3],
+      template: { itemStyle: { color: '#123456' } },
+      fallback,
+    })
+    expect(resolve(params(0))).toBe('#123456')
+    expect(resolve(params(1))).toBe('#123456')
+  })
+
+  it('calls a function template itemStyle.color with the ECharts params', () => {
+    const color = vi.fn(() => '#abcdef')
+    const resolve = createItemColorResolver({
+      theme,
+      datums: [{}],
+      template: { itemStyle: { color } },
+      fallback,
+    })
+    const p = params(0)
+    expect(resolve(p)).toBe('#abcdef')
+    expect(color).toHaveBeenCalledWith(p)
+  })
+
+  it('falls back when neither datum nor template give a colour', () => {
+    const resolve = createItemColorResolver({
+      theme,
+      datums: [{ value: 1 }],
+      template: { itemStyle: { color: () => undefined } },
+      fallback,
+    })
+    expect(resolve(params(0))).toBe('#fallback')
+    expect(resolve(params(5))).toBe('#fallback')
+    const noTemplate = createItemColorResolver({
+      theme,
+      datums: [],
+      template: undefined,
+      fallback,
+    })
+    expect(noTemplate(params(0))).toBe('#fallback')
+  })
+
+  it('resolves theme palette paths on datum and template colours', () => {
+    const resolve = createItemColorResolver({
+      theme,
+      datums: [{ color: 'primary.main' }, {}],
+      template: { itemStyle: { color: () => 'primary.main' } },
+      fallback,
+    })
+    expect(resolve(params(0))).toBe('#1976d2')
+    expect(resolve(params(1))).toBe('#1976d2')
+  })
+})

package/src/widgets-v2/utils/item-color.ts

@@ -0,0 +1,55 @@
+import type { Theme } from '@mui/material'
+import type { CallbackDataParams } from 'echarts/types/dist/shared'
+import { resolveThemeColor } from './resolve-theme-color'
+
+/** ECharts `itemStyle.color` callback, as emitted by the chart widgets. */
+export type ItemColorCallback = (params: CallbackDataParams) => string
+
+/**
+ * Builds the callback that resolves the **base** colour of every item of one
+ * series, before any selection dimming. Priority:
+ *
+ *   1. the datum's own `color` (`datums[params.dataIndex].color`);
+ *   2. the consumer's `template.itemStyle.color` (from `optionsOverride`):
+ *      a string is used as is, a function is called with the ECharts params;
+ *   3. `fallback` — the widget's default (series colour / palette).
+ *
+ * The datum is looked up by `params.dataIndex` in the widget's own data
+ * rather than read off `params.data`, so it works whatever the dataset row
+ * shape is (object rows, `[label, count]` tuples, `[x, y]` tuples).
+ *
+ * Datum and template colours go through {@link resolveThemeColor}, same as
+ * per-series colours, so palette paths such as `'primary.main'` work.
+ */
+export function createItemColorResolver({
+  theme,
+  datums,
+  template,
+  fallback,
+}: {
+  theme: Theme
+  datums: readonly unknown[]
+  template: unknown
+  fallback: ItemColorCallback
+}): ItemColorCallback {
+  const templateColor = (template as { itemStyle?: { color?: unknown } })
+    ?.itemStyle?.color
+  return (params) => {
+    const datumColor = readColor(datums[params.dataIndex])
+    if (datumColor) return resolveThemeColor(theme, datumColor)!
+    const custom =
+      typeof templateColor === 'function'
+        ? (templateColor as (p: CallbackDataParams) => unknown)(params)
+        : templateColor
+    if (typeof custom === 'string' && custom !== '') {
+      return resolveThemeColor(theme, custom)!
+    }
+    return fallback(params)
+  }
+}
+
+function readColor(datum: unknown): string | undefined {
+  if (datum == null || typeof datum !== 'object') return undefined
+  const color = (datum as { color?: unknown }).color
+  return typeof color === 'string' && color !== '' ? color : undefined
+}