@carto/ps-react-ui 4.7.1 → 4.9.0

package/src/widgets-v2/formula/subcomponents.test.tsx

@@ -0,0 +1,107 @@
+import { describe, it, expect } from 'vitest'
+import { render } from '@testing-library/react'
+import { Series } from './series'
+import { Value } from './value'
+import { Note } from './note'
+import { Prefix } from './prefix'
+import { Suffix } from './suffix'
+import { Delta } from './delta'
+
+describe('<Series>', () => {
+  it('renders the first letter of name as an Avatar', () => {
+    const { getByLabelText } = render(<Series name='Revenue' />)
+    const av = getByLabelText('Revenue')
+    expect(av.textContent).toBe('R')
+  })
+
+  it('honours a custom size', () => {
+    const { getByLabelText } = render(<Series name='Cogs' size={40} />)
+    expect(getByLabelText('Cogs')).toBeTruthy()
+  })
+
+  it('passes a CSS colour through unchanged', () => {
+    const { getByLabelText } = render(<Series name='X' color='#ff0000' />)
+    expect(getByLabelText('X')).toBeTruthy()
+  })
+
+  it('resolves a dotted palette path to a concrete colour via the theme', () => {
+    const { getByLabelText } = render(<Series name='Y' color='primary.main' />)
+    expect(getByLabelText('Y')).toBeTruthy()
+  })
+
+  it('resolves a nested palette path (palette.warning.dark)', () => {
+    const { getByLabelText } = render(<Series name='W' color='warning.dark' />)
+    expect(getByLabelText('W')).toBeTruthy()
+  })
+})
+
+describe('<Value>', () => {
+  it('renders children', () => {
+    const { getByText } = render(<Value>42</Value>)
+    expect(getByText('42')).toBeTruthy()
+  })
+
+  it('applies the supplied color override', () => {
+    const { getByText } = render(<Value color='success.main'>ok</Value>)
+    expect(getByText('ok')).toBeTruthy()
+  })
+})
+
+describe('<Note>', () => {
+  it('renders children', () => {
+    const { getByText } = render(<Note>last 7 days</Note>)
+    expect(getByText('last 7 days')).toBeTruthy()
+  })
+})
+
+describe('<Prefix>', () => {
+  it('renders children', () => {
+    const { getByText } = render(<Prefix>$</Prefix>)
+    expect(getByText('$')).toBeTruthy()
+  })
+})
+
+describe('<Suffix>', () => {
+  it('renders children', () => {
+    const { getByText } = render(<Suffix>%</Suffix>)
+    expect(getByText('%')).toBeTruthy()
+  })
+})
+
+describe('<Delta>', () => {
+  it('infers positive severity from a positive value', () => {
+    const { container } = render(<Delta value={0.12} />)
+    // Default percent formatter with signDisplay='always'.
+    expect(container.textContent).toContain('+12%')
+    expect(container.querySelector('.MuiChip-colorSuccess')).not.toBeNull()
+  })
+
+  it('infers negative severity from a negative value', () => {
+    const { container } = render(<Delta value={-0.05} />)
+    expect(container.textContent).toContain('-5%')
+    expect(container.querySelector('.MuiChip-colorError')).not.toBeNull()
+  })
+
+  it('infers neutral severity from zero', () => {
+    const { container } = render(<Delta value={0} />)
+    expect(container.textContent).toContain('+0%')
+    expect(container.querySelector('.MuiChip-colorDefault')).not.toBeNull()
+  })
+
+  it('renders an explicit label, bypassing the formatter', () => {
+    const { getByText } = render(<Delta value={-1} label='down a lot' />)
+    expect(getByText('down a lot')).toBeTruthy()
+  })
+
+  it('uses a custom format() when provided', () => {
+    const { container } = render(
+      <Delta value={3.14} format={(v) => `${v.toFixed(2)}x`} />,
+    )
+    expect(container.textContent).toContain('3.14x')
+  })
+
+  it('honours an explicit severity override', () => {
+    const { container } = render(<Delta value={5} severity='neutral' />)
+    expect(container.querySelector('.MuiChip-colorDefault')).not.toBeNull()
+  })
+})

package/src/widgets-v2/formula/suffix.tsx

@@ -0,0 +1,25 @@
+import { Typography, type TypographyProps } from '@mui/material'
+import type { ReactNode } from 'react'
+
+export interface SuffixProps {
+  children: ReactNode
+  TypographyProps?: TypographyProps
+}
+
+/**
+ * Suffix slot for a Formula KPI — large, bold, muted (`text.secondary`).
+ * Composable building block for custom formula layouts; the canonical
+ * {@link FormulaUI} renders one of these per item when `suffix` is set.
+ */
+export function Suffix({ children, TypographyProps }: SuffixProps) {
+  return (
+    <Typography
+      variant='h5'
+      component='span'
+      sx={{ fontWeight: 600, color: 'text.secondary', lineHeight: 1 }}
+      {...TypographyProps}
+    >
+      {children}
+    </Typography>
+  )
+}

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

@@ -0,0 +1,48 @@
+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'
+
+/** Comparative delta rendered as a coloured chip on the right of a row. */
+export interface FormulaDelta {
+  /** Numeric magnitude. Default formatting renders as a percent (e.g. `-12,3 %`). */
+  value: number
+  /** Pre-formatted label override (skips the default percent formatter). */
+  label?: string
+  /**
+   * Visual treatment override. When omitted it's derived from `value`'s sign:
+   * `>0 → 'positive'`, `<0 → 'negative'`, `=0 → 'neutral'`.
+   */
+  severity?: DeltaSeverity
+}
+
+/** A single KPI value rendered by the Formula widget. */
+export interface FormulaDataItem {
+  value: number
+  prefix?: string
+  suffix?: string
+  /** Override the value's text colour (e.g. `'success.main'`). */
+  color?: string
+  /** Optional series indicator — coloured avatar with first letter of `name`. */
+  series?: FormulaSeries
+  /** Optional caption rendered below the value. */
+  note?: string
+  /** Optional comparative delta chip rendered to the right of the row. */
+  delta?: FormulaDelta
+}
+
+/**
+ * Formula widget data — an array of KPI items rendered top-to-bottom. A common
+ * "single big number" widget is just `[{ value: 123 }]`. Multi-series usage
+ * sets `series`, `note`, and/or `delta` per item.
+ */
+export type FormulaWidgetData = readonly FormulaDataItem[]

package/src/widgets-v2/formula/value.tsx

@@ -0,0 +1,31 @@
+import { Typography, type TypographyProps } from '@mui/material'
+import type { ReactNode } from 'react'
+
+export interface ValueProps {
+  children: ReactNode
+  /** Override the default `text.primary` color — useful for sparkline tints. */
+  color?: string
+  TypographyProps?: TypographyProps
+}
+
+/**
+ * Value slot for a Formula KPI — large, bold, primary text color. Composable
+ * building block for custom formula layouts; the canonical {@link FormulaUI}
+ * renders one of these per item.
+ */
+export function Value({ children, color, TypographyProps }: ValueProps) {
+  return (
+    <Typography
+      variant='h5'
+      component='span'
+      sx={{
+        fontWeight: 600,
+        color: color ?? 'text.primary',
+        lineHeight: 1,
+      }}
+      {...TypographyProps}
+    >
+      {children}
+    </Typography>
+  )
+}

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

@@ -0,0 +1,94 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { createHistogramDownloadConfig } from './download'
+import type { HistogramWidgetData } from './types'
+
+const data: HistogramWidgetData = [
+  [1, 2, 3],
+  [4, 5, 6],
+]
+const ticks = [0, 10, 20, 30]
+
+let csvText = ''
+
+beforeEach(() => {
+  csvText = ''
+  vi.spyOn(URL, 'createObjectURL').mockReturnValue('blob:mock')
+  vi.spyOn(URL, 'revokeObjectURL').mockImplementation(() => undefined)
+  const RealBlob = global.Blob
+  vi.stubGlobal(
+    'Blob',
+    class extends RealBlob {
+      constructor(parts: BlobPart[], opts?: BlobPropertyBag) {
+        csvText = typeof parts[0] === 'string' ? parts[0] : ''
+        super(parts, opts)
+      }
+    },
+  )
+})
+
+describe('createHistogramDownloadConfig', () => {
+  it('CSV-only by default', () => {
+    const items = createHistogramDownloadConfig({
+      filename: 'h',
+      getData: () => data,
+      getTicks: () => ticks,
+    })
+    expect(items.map((i) => i.id)).toEqual(['csv'])
+  })
+
+  it('prepends PNG when getCaptureEl is provided', () => {
+    const items = createHistogramDownloadConfig({
+      filename: 'h',
+      getData: () => data,
+      getTicks: () => ticks,
+      getCaptureEl: () => document.createElement('div'),
+    })
+    expect(items.map((i) => i.id)).toEqual(['png', 'csv'])
+  })
+
+  it('CSV resolve serialises bins × series with default series names', async () => {
+    const items = createHistogramDownloadConfig({
+      filename: 'h',
+      getData: () => data,
+      getTicks: () => ticks,
+    })
+    const handle = await items.find((i) => i.id === 'csv')!.resolve()
+    expect(handle.filename).toBe('h.csv')
+    expect(csvText).toBe(
+      'bin_low,bin_high,series_1,series_2\n0,10,1,4\n10,20,2,5\n20,30,3,6',
+    )
+  })
+
+  it('CSV honours supplied seriesNames', async () => {
+    const items = createHistogramDownloadConfig({
+      filename: 'h',
+      getData: () => data,
+      getTicks: () => ticks,
+      seriesNames: ['lo', 'hi'],
+    })
+    await items.find((i) => i.id === 'csv')!.resolve()
+    expect(csvText.startsWith('bin_low,bin_high,lo,hi')).toBe(true)
+  })
+
+  it('CSV emits header-only when ticks has < 2 entries', async () => {
+    const items = createHistogramDownloadConfig({
+      filename: 'h',
+      getData: () => data,
+      getTicks: () => [0],
+    })
+    await items.find((i) => i.id === 'csv')!.resolve()
+    expect(csvText).toBe('bin_low,bin_high,series_1,series_2')
+  })
+
+  it('CSV fills missing series values with 0', async () => {
+    const sparse: HistogramWidgetData = [[1, 2, 3], []]
+    const items = createHistogramDownloadConfig({
+      filename: 'h',
+      getData: () => sparse,
+      getTicks: () => ticks,
+    })
+    await items.find((i) => i.id === 'csv')!.resolve()
+    expect(csvText).toContain('0,10,1,0')
+    expect(csvText).toContain('10,20,2,0')
+  })
+})

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

@@ -0,0 +1,60 @@
+import {
+  buildPngDownloadItem,
+  downloadToCSV,
+  type DownloadItem,
+} from '../actions/download'
+import type { HistogramWidgetData } from './types'
+
+/**
+ * Download menu items for histograms. Always includes a CSV item with
+ * `bin_low, bin_high, series_1_count, series_2_count, …` columns (one row
+ * per bin). When `getCaptureEl` is supplied, prepends a PNG item that
+ * rasterises the captured element via `html2canvas`.
+ */
+export function createHistogramDownloadConfig(args: {
+  filename: string
+  getData: () => HistogramWidgetData
+  getTicks: () => readonly number[]
+  seriesNames?: readonly string[]
+  getCaptureEl?: () => HTMLElement | null
+  pngPixelRatio?: number
+  pngBackgroundColor?: string | null
+}): DownloadItem[] {
+  const items: DownloadItem[] = []
+  if (args.getCaptureEl) {
+    items.push(
+      buildPngDownloadItem({
+        filename: args.filename,
+        getCaptureEl: args.getCaptureEl,
+        pixelRatio: args.pngPixelRatio,
+        backgroundColor: args.pngBackgroundColor,
+      }),
+    )
+  }
+  items.push({
+    id: 'csv',
+    label: 'Download as CSV',
+    resolve: () => {
+      const data = args.getData()
+      const ticks = args.getTicks()
+      const seriesCount = data.length
+      const header: unknown[] = ['bin_low', 'bin_high']
+      for (let i = 0; i < seriesCount; i++) {
+        header.push(args.seriesNames?.[i] ?? `series_${i + 1}`)
+      }
+      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)
+        rows.push(row)
+      }
+      const handle = downloadToCSV(rows)
+      return Promise.resolve({
+        url: handle.url,
+        filename: `${args.filename}.csv`,
+        revoke: handle.revoke,
+      })
+    },
+  })
+  return items
+}

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

@@ -0,0 +1,10 @@
+export { histogramOptions, createHistogramOptionFactory } from './options'
+export { HistogramSkeleton, type HistogramSkeletonProps } from './skeleton'
+export { createHistogramDownloadConfig } from './download'
+export { toRelativeHistogramData } from './transforms'
+export type {
+  HistogramWidgetData,
+  HistogramOptionsInput,
+  HistogramOptionFactoryInput,
+  HistogramEChartsOption,
+} from './types'

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

@@ -0,0 +1,318 @@
+import { describe, it, expect } from 'vitest'
+import { createTheme, type Theme } from '@mui/material'
+import { createHistogramOptionFactory, histogramOptions } from './options'
+
+const theme = createTheme() as unknown as Theme
+
+describe('histogramOptions (structural)', () => {
+  it('returns a category x-axis without baked data', () => {
+    const out = histogramOptions({ theme })
+    const xAxis = out.xAxis as { type: string; data?: unknown }
+    expect(xAxis.type).toBe('category')
+    expect(xAxis.data).toBeUndefined()
+  })
+
+  it('returns no series and no dataset (data is fused at render time)', () => {
+    const out = histogramOptions({ theme })
+    expect(out.series).toBeUndefined()
+    expect(out.dataset).toBeUndefined()
+  })
+
+  it('hides x and y axis lines and ticks for the v1 minimal look', () => {
+    const out = histogramOptions({ theme })
+    const xAxis = out.xAxis as {
+      axisLine?: { show?: boolean }
+      axisTick?: { show?: boolean }
+    }
+    const yAxis = out.yAxis as {
+      axisLine?: { show?: boolean }
+      axisTick?: { show?: boolean }
+      splitLine?: { show?: boolean }
+    }
+    expect(xAxis.axisLine?.show).toBe(false)
+    expect(xAxis.axisTick?.show).toBe(false)
+    expect(yAxis.axisLine?.show).toBe(false)
+    expect(yAxis.axisTick?.show).toBe(false)
+    expect(yAxis.splitLine?.show).toBe(true)
+  })
+
+  it('emits a dark themed tooltip with a positioner and a formatter (matches bar)', () => {
+    const out = histogramOptions({ theme })
+    const tooltip = out.tooltip as {
+      backgroundColor?: string
+      borderWidth?: number
+      position?: unknown
+      formatter?: unknown
+      textStyle?: { color?: string }
+    }
+    expect(tooltip.backgroundColor).toBe(theme.palette.grey[900])
+    expect(tooltip.borderWidth).toBe(0)
+    expect(typeof tooltip.position).toBe('function')
+    expect(typeof tooltip.formatter).toBe('function')
+    expect(tooltip.textStyle?.color).toBe(theme.palette.common.white)
+  })
+
+  it('emits the CARTO color palette starting with secondary.main', () => {
+    const out = histogramOptions({ theme }) as { color?: string[] }
+    expect(Array.isArray(out.color)).toBe(true)
+    expect(out.color?.[0]).toBe(theme.palette.secondary.main)
+  })
+
+  it('emits a themed axisPointer line', () => {
+    const out = histogramOptions({ theme }) as {
+      axisPointer?: { lineStyle?: { color?: string } }
+    }
+    expect(out.axisPointer?.lineStyle?.color).toBe(theme.palette.grey[400])
+  })
+
+  it('renders y-axis labels inside the plot, anchored to the bottom (matches bar)', () => {
+    const out = histogramOptions({ theme })
+    const yAxis = out.yAxis as {
+      axisLabel?: { inside?: boolean; verticalAlign?: string }
+    }
+    expect(yAxis.axisLabel?.inside).toBe(true)
+    expect(yAxis.axisLabel?.verticalAlign).toBe('bottom')
+  })
+
+  it('y-axis min/max are callback closures (niceNum extents), label formatter shows only the extents', () => {
+    const fmt = (n: number): string => `${n}k`
+    const out = histogramOptions({ theme, formatter: fmt })
+    const yAxis = out.yAxis as {
+      min?: unknown
+      max?: unknown
+      axisLabel?: { formatter?: (v: number) => string }
+    }
+    expect(typeof yAxis.min).toBe('function')
+    expect(typeof yAxis.max).toBe('function')
+    // niceMin / niceMax default to 0 and 1 until the min/max callbacks run.
+    expect(yAxis.axisLabel?.formatter?.(1)).toBe('1k')
+    // 0 is suppressed (matches v1/bar) and intermediate values are blanked.
+    expect(yAxis.axisLabel?.formatter?.(0)).toBe('')
+    expect(yAxis.axisLabel?.formatter?.(0.5)).toBe('')
+  })
+})
+
+describe('createHistogramOptionFactory (data → dataset merger)', () => {
+  it('builds bin labels from consecutive tick pairs', () => {
+    const merge = createHistogramOptionFactory({
+      theme,
+      ticks: [0, 10, 20, 30],
+    })
+    const out = merge({}, [[5, 10, 3]]) as {
+      dataset: { source: [string, number][] }[]
+    }
+    const labels = out.dataset[0]!.source.map(([label]) => label)
+    expect(labels).toEqual(['0–10', '10–20', '20–30'])
+  })
+
+  it('produces one dataset per series with [binLabel, count] tuple rows', () => {
+    const merge = createHistogramOptionFactory({
+      theme,
+      ticks: [0, 10, 20, 30],
+    })
+    const out = merge({}, [
+      [1, 2, 3],
+      [10, 20, 30],
+    ]) as { dataset: { source: [string, number][] }[]; series: unknown[] }
+    expect(out.dataset).toHaveLength(2)
+    expect(out.dataset[0]!.source).toEqual([
+      ['0–10', 1],
+      ['10–20', 2],
+      ['20–30', 3],
+    ])
+    expect(out.dataset[1]!.source).toEqual([
+      ['0–10', 10],
+      ['10–20', 20],
+      ['20–30', 30],
+    ])
+    expect(out.series).toHaveLength(2)
+  })
+
+  it('encodes columns positionally (x: 0, y: 1) and references each series dataset by index', () => {
+    const merge = createHistogramOptionFactory({ theme, ticks: [0, 10] })
+    const out = merge({}, [[1], [2]]) as {
+      series: {
+        type: string
+        datasetIndex: number
+        encode: { x: number; y: number }
+      }[]
+    }
+    expect(out.series[0]).toMatchObject({
+      type: 'bar',
+      datasetIndex: 0,
+      encode: { x: 0, y: 1 },
+    })
+    expect(out.series[1]).toMatchObject({
+      type: 'bar',
+      datasetIndex: 1,
+      encode: { x: 0, y: 1 },
+    })
+  })
+
+  it('pads short series with 0 to match bin count', () => {
+    const merge = createHistogramOptionFactory({
+      theme,
+      ticks: [0, 10, 20, 30],
+    })
+    const out = merge({}, [[5]]) as {
+      dataset: { source: [string, number][] }[]
+    }
+    expect(out.dataset[0]!.source.map(([, count]) => count)).toEqual([5, 0, 0])
+  })
+
+  it('attaches an itemStyle.color callback to each series, whether or not a selection is set', () => {
+    const merge = createHistogramOptionFactory({
+      theme,
+      ticks: [0, 10, 20, 30],
+      selection: [1],
+    })
+    const out = merge({}, [[1, 2, 3]]) as {
+      series: { itemStyle?: { color?: unknown } }[]
+    }
+    // The merger ALWAYS emits an `itemStyle.color` callback — when no
+    // selection is set, the callback is a passthrough returning the
+    // palette color. Always emitting is required so the next setOption
+    // overrides the previous callback via normal merge; conditionally
+    // dropping the key would let ECharts keep a stale dim callback alive
+    // (items would stay dimmed forever after an external clear).
+    const noSel = createHistogramOptionFactory({ theme, ticks: [0, 10] })({}, [
+      [1],
+    ]) as {
+      series: { itemStyle?: { color?: unknown } }[]
+    }
+    expect(typeof noSel.series[0]?.itemStyle?.color).toBe('function')
+    expect(typeof out.series[0]?.itemStyle?.color).toBe('function')
+  })
+
+  it('toggles legend.show based on series count (matches bar)', () => {
+    const merge = createHistogramOptionFactory({ theme, ticks: [0, 10, 20] })
+    const single = merge({}, [[1, 2]]) as { legend?: { show?: boolean } }
+    const multi = merge({}, [
+      [1, 2],
+      [3, 4],
+    ]) as { legend?: { show?: boolean } }
+    expect(single.legend?.show).toBe(false)
+    expect(multi.legend?.show).toBe(true)
+  })
+
+  it('emits a tooltip.formatter function in the merger output', () => {
+    const merge = createHistogramOptionFactory({ theme, ticks: [0, 10] })
+    const out = merge({}, [[1]]) as {
+      tooltip?: { formatter?: unknown }
+    }
+    expect(typeof out.tooltip?.formatter).toBe('function')
+  })
+
+  it('resolves y-axis min/max to concrete niceNum bounds after fusion', () => {
+    const merge = createHistogramOptionFactory({ theme, ticks: [0, 10, 20] })
+    const out = merge({}, [[3, 47]]) as {
+      yAxis: { min?: number; max?: number }
+    }
+    expect(out.yAxis.min).toBe(0)
+    // 47 → niceNum → 50 (Math.ceil(47 / 10) * 10)
+    expect(out.yAxis.max).toBe(50)
+  })
+
+  it('uses series[i].name for series[i].name when provided', () => {
+    const merge = createHistogramOptionFactory({
+      theme,
+      ticks: [0, 10, 20],
+      series: [{ name: '2024' }, { name: '2025' }],
+    })
+    const out = merge({}, [
+      [1, 2],
+      [3, 4],
+    ]) 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 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,
+      ticks: [0, 10, 20],
+      labelFormatter: (s) => `[${s})`,
+    })
+    const out = merge({}, [[1, 2]]) as {
+      dataset: { source: [string, number][] }[]
+    }
+    expect(out.dataset[0]!.source.map(([label]) => label)).toEqual([
+      '[0–10)',
+      '[10–20)',
+    ])
+  })
+
+  it('returns empty dataset/series when no data', () => {
+    const merge = createHistogramOptionFactory({ theme, ticks: [0, 10, 20] })
+    const out = merge({ xAxis: { type: 'category' } }, []) as {
+      dataset: unknown[]
+      series: unknown[]
+    }
+    expect(out.dataset).toEqual([])
+    expect(out.series).toEqual([])
+  })
+
+  describe('tooltip formatter', () => {
+    type ItemFormatter = (
+      params: unknown,
+      ticket?: unknown,
+      callback?: unknown,
+    ) => string
+    const getFormatter = (ctx?: {
+      formatter?: (n: number) => string
+    }): ItemFormatter => {
+      const factory = createHistogramOptionFactory({
+        theme,
+        ticks: [0, 10, 20],
+      })
+      const out = factory({}, [[1, 2]], ctx) as {
+        tooltip: { formatter: ItemFormatter }
+      }
+      return out.tooltip.formatter
+    }
+    const baseItem = {
+      seriesName: '2024',
+      name: '[0–10)',
+      marker: '<i></i>',
+      value: ['[0–10)', 5] as [string, number],
+    } as const
+
+    it('reads the count from the value tuple and renders it', () => {
+      const html = getFormatter()([baseItem])
+      expect(html).toContain('5')
+      expect(html).toContain('2024')
+    })
+
+    it('applies the ctx formatter to numeric values', () => {
+      const html = getFormatter({ formatter: (n) => `${n}x` })([baseItem])
+      expect(html).toContain('5x')
+    })
+
+    it('renders without a series prefix when seriesName is empty', () => {
+      const html = getFormatter()([{ ...baseItem, seriesName: '' }])
+      expect(html).not.toContain('2024')
+    })
+
+    it('renders an empty value when the tuple is missing', () => {
+      const html = getFormatter()([
+        { ...baseItem, value: undefined as unknown as [string, number] },
+      ])
+      // Name still renders even when the value is empty.
+      expect(html).toContain('[0–10)')
+    })
+  })
+})