@carto/ps-react-ui 6.2.0 → 6.4.0

package/src/widgets/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/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
+}