@carto/ps-react-ui 6.1.1 → 6.3.0

package/src/widgets/category/components/category-row-stacked.tsx

@@ -26,6 +26,11 @@ export interface CategoryRowStackedProps {
   onToggle: (name: CategoryKey) => void
   /** Bar visual density. Forwarded to the inner {@link CategoryBarStacked}. */
   size?: CategorySize
+  /**
+   * Where the list's zero sits (% of the track), shared by every row so the
+   * zero lines up: `0` positive-only, `50` signed, `100` negative-only.
+   */
+  zeroPct?: number
 }
 
 /**
@@ -41,6 +46,10 @@ export interface CategoryRowStackedProps {
  * total relative to other rows. The total numeric value is still shown in
  * the header so the per-row magnitude isn't lost.
  *
+ * Signed data diverges from `zeroPct`: positives stack rightwards and
+ * negatives leftwards, and whichever side is longer reaches its edge of the
+ * track. The header total is the signed sum.
+ *
  * Visual selection / dim signal lives entirely in the segment colors
  * (`colors` prop) — every series in a dimmed row receives
  * `theme.palette.action.disabled`. The bar visually collapses to a single
@@ -57,6 +66,7 @@ export function CategoryRowStacked({
   selected,
   onToggle,
   size,
+  zeroPct = 0,
 }: CategoryRowStackedProps) {
   const handleKey = (e: KeyboardEvent<HTMLDivElement>): void => {
     if (e.key === 'Enter' || e.key === ' ') {
@@ -65,6 +75,18 @@ export function CategoryRowStacked({
     }
   }
   const total = values.reduce((a, b) => a + b, 0)
+  let pos = 0
+  let neg = 0
+  for (const v of values) {
+    if (v > 0) pos += v
+    else neg -= v
+  }
+  // Magnitude that would fill the whole track, picked so the longer side
+  // just reaches its edge: `pos` spans `100 - zeroPct`, `neg` spans `zeroPct`.
+  const scale = Math.max(
+    zeroPct < 100 ? (pos * 100) / (100 - zeroPct) : 0,
+    zeroPct > 0 ? (neg * 100) / zeroPct : 0,
+  )
   return (
     <Box
       role='button'
@@ -85,7 +107,8 @@ export function CategoryRowStacked({
       <CategoryBarStacked
         values={values}
         colors={colors}
-        maxValue={total}
+        maxValue={scale}
+        zeroPct={zeroPct}
         size={size}
       />
       <Box sx={styles.stackedBreakdown}>

package/src/widgets/category/style.ts

@@ -28,17 +28,19 @@ const bar: Record<CategorySize, SxProps<Theme>> = {
 const barFill: Record<CategorySize, SxProps<Theme>> = {
   small: {
     position: 'absolute',
-    inset: '0 auto 0 0',
+    top: 0,
+    bottom: 0,
     borderRadius: 1,
     transition:
-      'width 300ms ease-in-out, background-color 150ms ease, filter 150ms ease',
+      'left 300ms ease-in-out, width 300ms ease-in-out, background-color 150ms ease, filter 150ms ease',
   },
   medium: {
     position: 'absolute',
-    inset: '0 auto 0 0',
+    top: 0,
+    bottom: 0,
     borderRadius: 0.25,
     transition:
-      'width 300ms ease-in-out, background-color 150ms ease, filter 150ms ease',
+      'left 300ms ease-in-out, width 300ms ease-in-out, background-color 150ms ease, filter 150ms ease',
   },
 }
 
@@ -71,13 +73,47 @@ export const styles = {
     position: 'relative',
     width: '100%',
   },
-  // Flat list of category rows. Holds both single + multi rows.
+  // Flat list of category rows. A grid rather than a flex column so the
+  // multi-series rows can share one value column through `subgrid`: with
+  // every bar track the same width, the zero ticks line up across rows.
   list: {
-    display: 'flex',
-    flexDirection: 'column',
+    position: 'relative',
+    display: 'grid',
+    gridTemplateColumns: 'minmax(0, 1fr)',
     gap: 1,
     py: 0.5,
   },
+  // Layered on `list` for unstacked multi-series: bars | values.
+  listMulti: {
+    gridTemplateColumns: 'minmax(0, 1fr) max-content',
+  },
+  // Zero tick for signed data: one per bar track, drawn outside the track's
+  // `overflow: hidden` so it can stand 6px proud of it on both sides.
+  // Tracks share a width (see `listMulti`), so the ticks line up by rows.
+  barWrap: {
+    position: 'relative',
+  },
+  // Multi-series rows draw one zero line through every series bar instead
+  // of a tick per bar: this box is the row's bar column (grid area set
+  // inline) and holds a `zeroTick`, so the line stays out of the label.
+  multiZeroArea: {
+    position: 'absolute',
+    inset: 0,
+    gridColumn: '1 / 2',
+    pointerEvents: 'none',
+  },
+  zeroTick: {
+    position: 'absolute',
+    top: -6,
+    bottom: -6,
+    width: '1px',
+    // Centred on the zero so both halves of the bar meet it evenly. No
+    // z-index: it comes before the track in the DOM, so the bar paints over
+    // it and only the overhang shows.
+    transform: 'translateX(-50%)',
+    bgcolor: 'text.disabled',
+    pointerEvents: 'none',
+  },
   // Layered on `list` only in scroll mode (`maxItems === 0`): right padding
   // so the bars + right-aligned values clear the scrollbar. Right side only
   // — the left edge stays at 0 so content stays aligned with the capped
@@ -91,6 +127,7 @@ export const styles = {
   // bar fills the row width below. Mirrors `rowMulti` for visual
   // consistency.
   rowSingle: {
+    gridColumn: '1 / -1',
     display: 'flex',
     flexDirection: 'column',
     gap: 0.5,
@@ -124,10 +161,14 @@ export const styles = {
   // Flex column: label fills the top row; bar+value pairs stack below.
   // Bars get full track width — better legibility for N>=2 series than a
   // shared grid would give.
+  // Spans the list and adopts its columns, so every row's value column is
+  // as wide as the widest value in the list.
   rowMulti: {
-    display: 'flex',
-    flexDirection: 'column',
-    gap: 0.5,
+    position: 'relative',
+    gridColumn: '1 / -1',
+    display: 'grid',
+    gridTemplateColumns: 'subgrid',
+    rowGap: 0.5,
     // py: 0.5,
     // px: 0.5,
     cursor: 'pointer',
@@ -155,6 +196,7 @@ export const styles = {
     fontWeight: 'medium',
   },
   multiName: {
+    gridColumn: '1 / -1',
     overflow: 'hidden',
     whiteSpace: 'nowrap',
     textOverflow: 'ellipsis',
@@ -171,6 +213,7 @@ export const styles = {
     // minWidth here is also harmless in that context.
     minWidth: 48,
     textAlign: 'right',
+    alignSelf: 'center',
   },
 
   // ── Bar (track + fill) ────────────────────────────────────────────
@@ -184,13 +227,12 @@ export const styles = {
 
   // ── Multi-series internals ────────────────────────────────────────
   // One [bar | value] flex row per series, inside `rowMulti`'s column.
+  // `contents` hands the bar and the value to `rowMulti`'s subgrid cells.
   multiBarRow: {
-    display: 'flex',
-    alignItems: 'center',
-    gap: 1,
+    display: 'contents',
   },
   multiBarContainer: {
-    flex: 1,
+    alignSelf: 'center',
   },
 
   // ── Stacked-mode row ──────────────────────────────────────────────
@@ -198,6 +240,7 @@ export const styles = {
   // focus ring) but stack three children vertically: header line, bar,
   // breakdown line.
   rowStacked: {
+    gridColumn: '1 / -1',
     display: 'flex',
     flexDirection: 'column',
     gap: 0.5,
@@ -285,6 +328,7 @@ export const styles = {
   // (no parentheses). Only the label is the click target when interactive;
   // the count is always static text beside it.
   otherRow: {
+    gridColumn: '1 / -1',
     display: 'flex',
     alignItems: 'center',
     gap: 1,

package/src/widgets/histogram/bins.ts

@@ -0,0 +1,22 @@
+import type { HistogramBin } from './types'
+
+/** Count of a {@link HistogramBin}, whichever form it takes. */
+export function getHistogramBinValue(bin: HistogramBin): number {
+  return typeof bin === 'number' ? bin : bin.value
+}
+
+/** Whether `v` is a valid {@link HistogramBin} with a finite count. */
+export function isHistogramBin(v: unknown): v is HistogramBin {
+  if (typeof v === 'number') return Number.isFinite(v)
+  if (v == null || typeof v !== 'object') return false
+  const value = (v as { value?: unknown }).value
+  return typeof value === 'number' && Number.isFinite(value)
+}
+
+/** Same bin with its count replaced; keeps the object form (and `color`). */
+export function withHistogramBinValue(
+  bin: HistogramBin,
+  value: number,
+): HistogramBin {
+  return typeof bin === 'number' ? value : { ...bin, value }
+}

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

@@ -61,6 +61,16 @@ describe('createHistogramDownloadConfig', () => {
     )
   })
 
+  it('CSV writes the count of object bins (colour is not exported)', async () => {
+    const items = createHistogramDownloadConfig({
+      filename: 'h',
+      getData: () => [[{ value: 1, color: '#f00' }, 2, { value: 3 }]],
+      getTicks: () => ticks,
+    })
+    await items.find((i) => i.id === 'csv')!.resolve({ id: null })
+    expect(csvText).toBe('bin_low,bin_high,series_1\n0,10,1\n10,20,2\n20,30,3')
+  })
+
   it('CSV honours supplied seriesNames', async () => {
     const items = createHistogramDownloadConfig({
       filename: 'h',

package/src/widgets/histogram/download.ts

@@ -4,7 +4,8 @@ import {
   type DownloadItem,
   type WidgetDownloadArgs,
 } from '../actions/download'
-import type { HistogramWidgetData } from './types'
+import { getHistogramBinValue } from './bins'
+import type { HistogramBin, HistogramWidgetData } from './types'
 
 /**
  * Download menu items for histograms. Always includes a CSV item with
@@ -13,7 +14,7 @@ import type { HistogramWidgetData } from './types'
  * rasterises the captured element via `html2canvas`.
  */
 export function createHistogramDownloadConfig(
-  args: WidgetDownloadArgs<HistogramWidgetData> & {
+  args: WidgetDownloadArgs<HistogramWidgetData<HistogramBin>> & {
     getTicks: () => readonly number[]
     seriesNames?: readonly string[]
   },
@@ -33,7 +34,10 @@ export function createHistogramDownloadConfig(
         const rows: unknown[][] = [header]
         for (let bin = 0; bin < Math.max(0, ticks.length - 1); bin++) {
           const row: unknown[] = [ticks[bin], ticks[bin + 1]]
-          for (let s = 0; s < seriesCount; s++) row.push(data[s]?.[bin] ?? 0)
+          for (let s = 0; s < seriesCount; s++) {
+            const value = data[s]?.[bin]
+            row.push(value == null ? 0 : getHistogramBinValue(value))
+          }
           rows.push(row)
         }
         return rows

package/src/widgets/histogram/index.ts

@@ -5,7 +5,10 @@ export {
   toRelativeHistogramData,
   filterHistogramByLockedBins,
 } from './transforms'
+export { getHistogramBinValue } from './bins'
 export type {
+  HistogramBin,
+  HistogramBinObject,
   HistogramWidgetData,
   HistogramOptionsInput,
   HistogramOptionFactoryInput,

package/src/widgets/histogram/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 { createHistogramOptionFactory, histogramOptions } from './options'
 
@@ -409,3 +410,64 @@ describe('createHistogramOptionFactory (data → dataset merger)', () => {
     })
   })
 })
+
+describe('createHistogramOptionFactory — per-item colour', () => {
+  interface Out {
+    dataset: { source: (string | number)[][] }[]
+    series: { itemStyle: { color: (p: unknown) => string } }[]
+  }
+  const ticks = [0, 10, 20, 30]
+  const dim = (c: string) => echarts.color.modifyAlpha(c, 0.15)
+
+  it('accepts object bins: dataset carries the counts', () => {
+    const merge = createHistogramOptionFactory({ theme, ticks })
+    const out = merge({}, [[{ value: 1, color: '#00ff00' }, 2, { value: 3 }]])
+    expect((out as Out).dataset[0]!.source.map(([, v]) => v)).toEqual([1, 2, 3])
+  })
+
+  it('bin colour wins over the series colour; template next', () => {
+    const merge = createHistogramOptionFactory({
+      theme,
+      ticks,
+      series: [{ name: 'S', color: '#0000ff' }],
+      selection: [0, 1],
+    })
+    const out = merge(
+      { series: [{ type: 'bar', itemStyle: { color: '#123456' } }] },
+      [[{ value: 1, color: '#00ff00' }, 2, { value: 3 }]],
+    ) 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 = createHistogramOptionFactory({
+      theme,
+      ticks,
+      optionsOverride: {
+        series: [
+          {
+            type: 'bar',
+            itemStyle: {
+              color: (p: { dataIndex: number }) => `#c${p.dataIndex}`,
+            },
+          },
+        ],
+      },
+    })
+    const out = factory(factory(undefined, undefined), [[1, 2, 3]]) as Out
+    expect(out.series[0]!.itemStyle.color({ dataIndex: 2, color: '#x' })).toBe(
+      '#c2',
+    )
+  })
+
+  it('keeps the series / palette colour for plain number bins', () => {
+    const merge = createHistogramOptionFactory({ theme, ticks, selection: [1] })
+    const out = merge({}, [[1, 2, 3]]) as Out
+    const colorFn = out.series[0]!.itemStyle.color
+    expect(colorFn({ dataIndex: 0, color: '#abcdef' })).toBe(dim('#abcdef'))
+    expect(colorFn({ dataIndex: 1, color: '#abcdef' })).toBe('#abcdef')
+  })
+})

package/src/widgets/histogram/options.ts

@@ -12,11 +12,14 @@ 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 { getHistogramBinValue } from './bins'
 import { positionDataZoomForLegend } from '../utils/data-zoom-layout'
 import type {
   HistogramEChartsOption,
   HistogramOptionFactoryInput,
   HistogramOptionsInput,
+  HistogramBin,
   HistogramWidgetData,
 } from './types'
 
@@ -147,7 +150,7 @@ export function histogramOptions({
  *     the consumer-supplied `optionsOverride`. Called once by Provider to
  *     seed `rawOptions` in the store.
  *   - **Merge phase** (`option != null`) — fuses post-pipeline `state.data`
- *     (`HistogramWidgetData` — `number[][]`) into the option via the
+ *     (`HistogramWidgetData` — `HistogramBin[][]`) into the option via the
  *     dataset API. Each series gets its own dataset of `[binLabel, count]`
  *     pairs derived from `ticks`; series reference their dataset by
  *     `datasetIndex` and are encoded by column position. Reactive
@@ -199,8 +202,8 @@ export function createHistogramOptionFactory(
         : structural
     }
 
-    const seriesArr: HistogramWidgetData = Array.isArray(data)
-      ? (data as HistogramWidgetData)
+    const seriesArr: HistogramWidgetData<HistogramBin> = Array.isArray(data)
+      ? (data as HistogramWidgetData<HistogramBin>)
       : []
     if (seriesArr.length === 0 || binLabels.length === 0) {
       return { ...option, dataset: [], series: [] }
@@ -261,14 +264,28 @@ export function createHistogramOptionFactory(
     // and bins 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 base = params.color as string
-        if (!selectionSet) return base
-        return selectionSet.has(params.dataIndex)
-          ? base
-          : echarts.color.modifyAlpha(base, 0.15)
-      },
+    //
+    // The base colour is the bin's own `color` (object bins), else the
+    // template's `itemStyle.color`, else the series colour / palette.
+    const makeDimItemStyle = (
+      datums: readonly unknown[],
+      template: unknown,
+    ) => {
+      const baseColor = createItemColorResolver({
+        theme,
+        datums,
+        template,
+        fallback: (params) => params.color as string,
+      })
+      return {
+        color: (params: CallbackDataParams) => {
+          const base = baseColor(params)
+          if (!selectionSet) return base
+          return selectionSet.has(params.dataIndex)
+            ? base
+            : echarts.color.modifyAlpha(base, 0.15)
+        },
+      }
     }
 
     // A consumer's `optionsOverride.xAxis` may legitimately be an array
@@ -306,12 +323,16 @@ export function createHistogramOptionFactory(
     return {
       ...option,
       xAxis: nextXAxis,
-      dataset: seriesArr.map((counts) => ({
-        source: binLabels.map(
-          (label, i) => [label, counts[i] ?? 0] as [string, number],
-        ),
+      dataset: seriesArr.map((bins) => ({
+        source: binLabels.map((label, i) => {
+          const bin = bins[i]
+          return [label, bin == null ? 0 : getHistogramBinValue(bin)] as [
+            string,
+            number,
+          ]
+        }),
       })),
-      series: seriesArr.map((_, i) => {
+      series: seriesArr.map((bins, i) => {
         const template =
           (seriesTemplates[i] as object | undefined) ??
           (broadcastTemplate as object)
@@ -324,7 +345,7 @@ export function createHistogramOptionFactory(
           encode: { x: 0, y: 1 },
           barCategoryGap: '0%',
           emphasis: { focus: 'series' },
-          itemStyle: dimItemStyle,
+          itemStyle: makeDimItemStyle(bins, template),
           ...(overrideColor ? { color: overrideColor } : {}),
         }
       }),

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

@@ -36,15 +36,20 @@ describe('toRelativeHistogramData', () => {
     expect(out[0]?.[1]).toBeCloseTo(-49.74874, 4)
   })
 
-  it('returns the input unchanged when shape does not match number[][]', () => {
+  it('returns the input unchanged when shape does not match HistogramBin[][]', () => {
     expect(toRelativeHistogramData(null)).toBe(null)
     expect(toRelativeHistogramData('not an array')).toBe('not an array')
-    // Series that isn't a flat number array (e.g. named-value or tuple)
-    // is returned as-is — keeps the transform safe to attach to a
-    // widget whose shape changes through other actions.
-    expect(toRelativeHistogramData([[{ name: 'a', value: 10 }]])).toEqual([
-      [{ name: 'a', value: 10 }],
-    ])
+    // Series that isn't a list of bins (e.g. strings or tuples) is returned
+    // as-is — keeps the transform safe to attach to a widget whose shape
+    // changes through other actions.
+    expect(toRelativeHistogramData([['a', 'b']])).toEqual([['a', 'b']])
+    expect(toRelativeHistogramData([[[1, 2]]])).toEqual([[[1, 2]]])
+  })
+
+  it('relativizes object bins, keeping their colour', () => {
+    expect(
+      toRelativeHistogramData([[{ value: 5, color: '#f00' }, 15]]),
+    ).toEqual([[{ value: 25, color: '#f00' }, 75]])
   })
 })
 
@@ -75,6 +80,15 @@ describe('filterHistogramByLockedBins', () => {
     ])
   })
 
+  it('zeroes non-locked object bins, keeping their colour', () => {
+    expect(
+      filterHistogramByLockedBins(
+        [[{ value: 10, color: '#f00' }, { value: 20 }, 30]],
+        [1],
+      ),
+    ).toEqual([[{ value: 0, color: '#f00' }, { value: 20 }, 0]])
+  })
+
   it('returns input unchanged when input is not array-shaped', () => {
     expect(filterHistogramByLockedBins('nope', [0])).toBe('nope')
   })

package/src/widgets/histogram/transforms.ts

@@ -1,6 +1,14 @@
+import {
+  getHistogramBinValue,
+  isHistogramBin,
+  withHistogramBinValue,
+} from './bins'
+import type { HistogramBin } from './types'
+
 /**
  * Histogram-specific `RelativeData` transform. Histogram data is
- * `number[][]` — each series is a flat list of bin counts. This
+ * `HistogramBin[][]` — each series is a flat list of bin counts (plain
+ * numbers or `{ value, color? }`, whose shape is kept). This
  * rewrites each count to its share of the series total (0–100), so
  * pairing with `createPercentFormatter` renders the y-axis as
  * percentages.
@@ -11,27 +19,31 @@
  * inputs produce sane signed shares-of-magnitude. A series whose total
  * 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[][]` fall through untouched (same defensive
+ * whose shape isn't `HistogramBin[][]` fall through untouched (same defensive
  * shape-check pattern as the default transform).
  */
 export const toRelativeHistogramData = (input: unknown): unknown => {
   if (!Array.isArray(input)) return input
   return input.map((series: unknown): unknown => {
-    if (!isFlatNumberArray(series)) return series
-    const total = series.reduce((acc, v) => acc + Math.abs(v), 0)
+    if (!isBinArray(series)) return series
+    const total = series.reduce<number>(
+      (acc, b) => acc + Math.abs(getHistogramBinValue(b)),
+      0,
+    )
     if (total <= 0) return series
-    return series.map((v) => (v / total) * 100)
+    return series.map((b) =>
+      withHistogramBinValue(b, (getHistogramBinValue(b) / total) * 100),
+    )
   })
 }
 
-function isFlatNumberArray(v: unknown): v is number[] {
-  if (!Array.isArray(v)) return false
-  return v.every((item) => typeof item === 'number' && Number.isFinite(item))
+function isBinArray(v: unknown): v is HistogramBin[] {
+  return Array.isArray(v) && v.every(isHistogramBin)
 }
 
 /**
- * `LockSelection` filter for Histogram. Data is `number[][]` — a flat list
- * of bin counts per series, positionally paired with `ticks` (bin `i` covers
+ * `LockSelection` filter for Histogram. Data is `HistogramBin[][]` — a flat
+ * list of bin counts per series, positionally paired with `ticks` (bin `i` covers
  * `[ticks[i], ticks[i+1])`). Unlike name-keyed widgets, locked-out bins can't
  * be REMOVED — that would shift every later bin's index and desync it from
  * its `ticks` range. Zeroing them out instead preserves array length/position,
@@ -47,7 +59,9 @@ export function filterHistogramByLockedBins(
   if (!Array.isArray(input)) return input
   const locked = new Set<number>(lockedItems.map(Number))
   return input.map((series: unknown): unknown => {
-    if (!isFlatNumberArray(series)) return series
-    return series.map((count, i) => (locked.has(i) ? count : 0))
+    if (!isBinArray(series)) return series
+    return series.map((bin, i) =>
+      locked.has(i) ? bin : withHistogramBinValue(bin, 0),
+    )
   })
 }

package/src/widgets/histogram/types.ts

@@ -3,12 +3,32 @@ import type { EChartsOption } from 'echarts'
 import type { WidgetSeries } from '../types'
 
 /**
- * Histogram widget data — array of series, each a flat array of bin counts.
- * The option factory's merge phase (see {@link createHistogramOptionFactory})
- * combines this with `ticks` to produce a 2-column dataset (`[binLabel, count]`)
- * for ECharts.
+ * One histogram bin: either its count, or `{ value, color? }` to give the
+ * bar its own colour (CSS colour or theme palette path such as
+ * `'primary.main'`). A bin `color` wins over the template's
+ * `itemStyle.color` and the series colour; selection dimming still applies.
  */
-export type HistogramWidgetData = readonly (readonly number[])[]
+export type HistogramBin = number | HistogramBinObject
+
+/** Object form of a {@link HistogramBin}. */
+export interface HistogramBinObject {
+  value: number
+  color?: string
+}
+
+/**
+ * Histogram widget data — array of series, each a flat array of bins. The
+ * option factory's merge phase (see {@link createHistogramOptionFactory})
+ * combines this with `ticks` to produce a 2-column dataset
+ * (`[binLabel, count]`) for ECharts.
+ *
+ * Defaults to plain counts (`number[][]`) so existing code that reads bins
+ * as numbers keeps type-checking; use `HistogramWidgetData<HistogramBin>`
+ * to also accept `{ value, color? }` bins. Every histogram API (option
+ * factory, transforms, download) accepts both forms.
+ */
+export type HistogramWidgetData<B extends HistogramBin = number> =
+  readonly (readonly B[])[]
 
 /** Inputs to the structural-only {@link histogramOptions} builder. */
 export interface HistogramOptionsInput {

package/src/widgets/index.ts

@@ -175,7 +175,12 @@ export type {
 export type { MarkdownUIProps, MarkdownWidgetData } from './markdown'
 export type { PieDatum, PieWidgetData } from './pie'
 export type { TimeseriesDatum, TimeseriesWidgetData } from './timeseries'
-export type { ScatterplotDatum, ScatterplotWidgetData } from './scatterplot'
+export type {
+  ScatterplotDatum,
+  ScatterplotPoint,
+  ScatterplotItem,
+  ScatterplotWidgetData,
+} from './scatterplot'
 export type {
   SpreadUIProps,
   SpreadDataItem,