@carto/ps-react-ui 4.7.1 → 4.9.0

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

@@ -0,0 +1,338 @@
+import type { EChartsOption } from 'echarts'
+import * as echarts from 'echarts'
+import type { CallbackDataParams } from 'echarts/types/dist/shared'
+import {
+  buildGridConfig,
+  buildLegendConfig,
+  createTooltipFormatter,
+  createTooltipPositioner,
+  niceNum,
+} from '../../widgets/utils/chart-config'
+import { ZOOM_LAYOUT } from '../actions/zoom-toggle'
+import type { OptionFactory } from '../echart'
+import { mergeOptions, resolveThemeColor } from '../utils'
+import { positionDataZoomForLegend } from '../utils/data-zoom-layout'
+import type {
+  HistogramEChartsOption,
+  HistogramOptionFactoryInput,
+  HistogramOptionsInput,
+  HistogramWidgetData,
+} from './types'
+
+/**
+ * Builds the **structural** ECharts option for a histogram widget — axes,
+ * grid, tooltip, value-axis label formatter, themed legend. Mirrors
+ * {@link import('../bar/options').barOptions} so the two widgets share v1
+ * look-and-feel: themed dark tooltip with positioner, CARTO color palette,
+ * structural legend (`show` toggled by the merger based on series count),
+ * y-axis labels rendered inside the plot via the `niceNum` closure pattern.
+ *
+ * Intentional deviations from bar (histogram-specific):
+ *   - **No `xAxis.axisLabel.formatter`.** Bin labels are pre-formatted in
+ *     the merger via `formatNumber(lo)–formatNumber(hi)` and optionally
+ *     the consumer's `labelFormatter`. The strings on the axis are
+ *     already display-ready, so there's nothing to post-format here.
+ *   - **Tooltip formatter reads the array-tuple row shape.** The dataset
+ *     uses positional `encode: { x: 0, y: 1 }`, so `item.value` comes in
+ *     as `[binLabel, count]` rather than bar's `{ name, value }` object.
+ *
+ * Intentionally data-agnostic: no series, no dataset, no x-axis category
+ * data (those depend on data + ticks and are added by the option factory's
+ * merge phase via {@link createHistogramOptionFactory}).
+ */
+export function histogramOptions({
+  theme,
+  formatter,
+}: HistogramOptionsInput): HistogramEChartsOption {
+  // Closure shared between yAxis min/max callbacks and the label formatter,
+  // so only the rounded extents are labelled (matches v1 + bar).
+  let niceMin = 0
+  let niceMax = 1
+
+  return {
+    grid: {
+      left: parseInt(theme.spacing(1)),
+      top: parseInt(theme.spacing(3)),
+      right: parseInt(theme.spacing(1)),
+      // Default: no legend. Merger bumps this when there are >1 series.
+      ...buildGridConfig(false, theme),
+      containLabel: true,
+    },
+    tooltip: {
+      trigger: 'axis',
+      backgroundColor: theme.palette.grey[900],
+      borderWidth: 0,
+      padding: [parseInt(theme.spacing(1)), parseInt(theme.spacing(1))],
+      textStyle: {
+        color: theme.palette.common.white,
+        fontSize: 11,
+        fontFamily: theme.typography.caption.fontFamily,
+      },
+      axisPointer: { type: 'line' },
+      position: createTooltipPositioner(theme),
+      formatter: buildHistogramTooltipFormatter(formatter),
+    },
+    // Legend styling baked here; `show` is toggled by the merger based on
+    // series count. Histogram doesn't accept `labelFormatter` at the
+    // options layer (bin labels are pre-formatted in the merger), so we
+    // skip the legend `labelFormatter` argument too.
+    legend: {
+      ...buildLegendConfig({ hasLegend: false }),
+    },
+    axisPointer: { lineStyle: { color: theme.palette.grey[400] } },
+    color: [
+      theme.palette.secondary.main,
+      ...Object.values(
+        (theme.palette as { qualitative?: { bold?: Record<string, string> } })
+          .qualitative?.bold ?? {},
+      ),
+    ],
+    xAxis: {
+      type: 'category',
+      axisLine: { show: false },
+      axisTick: { show: false },
+      axisLabel: {
+        padding: [parseInt(theme.spacing(0.5)), 0, 0, 0],
+        margin: 0,
+        hideOverlap: true,
+      },
+    },
+    yAxis: {
+      type: 'value',
+      min: (extent: { min: number }) => {
+        niceMin = extent.min < 0 ? niceNum(extent.min) : 0
+        return niceMin
+      },
+      max: (extent: { min: number; max: number }) => {
+        niceMax = extent.max <= 0 ? 1 : niceNum(extent.max)
+        return niceMax
+      },
+      axisLine: { show: false },
+      axisTick: { show: false },
+      splitLine: {
+        show: true,
+        lineStyle: { color: theme.palette.black?.[4] ?? theme.palette.divider },
+      },
+      axisLabel: {
+        fontSize: theme.typography.overlineDelicate?.fontSize,
+        fontFamily: theme.typography.overlineDelicate?.fontFamily,
+        margin: parseInt(theme.spacing(1)),
+        show: true,
+        showMaxLabel: true,
+        showMinLabel: true,
+        verticalAlign: 'bottom',
+        inside: true,
+        formatter: (value: number) => {
+          if (value !== niceMax && value !== niceMin) return ''
+          if (value === 0) return ''
+          return formatter ? formatter(value) : String(value)
+        },
+      },
+    },
+  } as HistogramEChartsOption
+}
+
+/**
+ * Returns the histogram widget's {@link OptionFactory} — one closure that
+ * owns BOTH phases of option construction:
+ *
+ *   - **Structural phase** (`option == null`) — builds the theme-aware
+ *     structural option via {@link histogramOptions}, optionally merging
+ *     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
+ *     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
+ *     `ctx.formatter` (driven by RelativeData → `%`) plus `niceMin`/`niceMax`
+ *     are re-derived here so the y-axis label formatter and the tooltip
+ *     pick up live store values, mirroring bar.
+ */
+export function createHistogramOptionFactory(
+  options: HistogramOptionFactoryInput,
+): OptionFactory {
+  const { theme, formatter, ticks, series, labelFormatter, selection } = options
+  const optionsOverride = options.optionsOverride
+  const selectionSet =
+    selection && selection.length > 0 ? new Set<number>(selection) : null
+
+  const binLabels: string[] = []
+  for (let i = 0; i < ticks.length - 1; i++) {
+    const lo = ticks[i]!
+    const hi = ticks[i + 1]!
+    const raw = `${formatNumber(lo)}–${formatNumber(hi)}`
+    binLabels.push(labelFormatter ? labelFormatter(raw) : raw)
+  }
+
+  return (option, data, ctx) => {
+    if (option == null) {
+      const structural = histogramOptions({ theme, formatter })
+      return optionsOverride
+        ? (mergeOptions(
+            structural as unknown as Record<string, unknown>,
+            optionsOverride as Partial<Record<string, unknown>>,
+          ) as EChartsOption)
+        : structural
+    }
+
+    const seriesArr: HistogramWidgetData = Array.isArray(data)
+      ? (data as HistogramWidgetData)
+      : []
+    if (seriesArr.length === 0 || binLabels.length === 0) {
+      return { ...option, dataset: [], series: [] }
+    }
+
+    const hasLegend = seriesArr.length > 1
+    const seriesTemplates = Array.isArray(option.series) ? option.series : []
+    const broadcastTemplate = seriesTemplates[0] ?? {}
+    const baseYAxis =
+      typeof option.yAxis === 'object' && !Array.isArray(option.yAxis)
+        ? option.yAxis
+        : {}
+    const baseGrid =
+      typeof option.grid === 'object' && !Array.isArray(option.grid)
+        ? option.grid
+        : {}
+    const baseTooltip =
+      typeof option.tooltip === 'object' && !Array.isArray(option.tooltip)
+        ? option.tooltip
+        : {}
+    const baseLegend =
+      typeof option.legend === 'object' && !Array.isArray(option.legend)
+        ? option.legend
+        : {}
+    // Reactive (live store) formatter from ctx — distinct from the
+    // closure-time `formatter` captured for the structural-build branch
+    // above. RelativeData can install a percent formatter on the store
+    // after the factory was constructed; the merge phase reads `ctx` to
+    // pick that up.
+    const liveFormatter = ctx?.formatter
+
+    const { niceMinVal, niceMaxVal } = computeHistogramNiceBounds(seriesArr)
+
+    // Zoom slider layout: when ZoomToggle has installed `dataZoom`, push
+    // the slider above the legend (if any) and reserve room in the grid.
+    const dataZoomLayout = positionDataZoomForLegend(option.dataZoom, hasLegend)
+    const fallbackBottom =
+      typeof baseGrid.bottom === 'number' ? baseGrid.bottom : 24
+    const baseBottom = hasLegend ? 56 : fallbackBottom
+    const gridBottom = dataZoomLayout
+      ? baseBottom + ZOOM_LAYOUT.sliderHeight + ZOOM_LAYOUT.sliderGap
+      : baseBottom
+
+    // Dim non-selected bins via `series.itemStyle.color`. Per-row
+    // `itemStyle` on dataset sources is silently ignored when
+    // `series.encode` is in play.
+    //
+    // We *always* emit `itemStyle.color` (a passthrough when nothing is
+    // selected), not conditionally — dropping the key between renders
+    // would let ECharts' default merge keep the previous callback alive
+    // 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)
+      },
+    }
+
+    return {
+      ...option,
+      dataset: seriesArr.map((counts) => ({
+        source: binLabels.map(
+          (label, i) => [label, counts[i] ?? 0] as [string, number],
+        ),
+      })),
+      series: seriesArr.map((_, i) => {
+        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: 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 },
+      grid: { ...baseGrid, bottom: gridBottom },
+      ...(dataZoomLayout ? { dataZoom: dataZoomLayout } : {}),
+      yAxis: {
+        ...baseYAxis,
+        min: niceMinVal,
+        max: niceMaxVal,
+        axisLabel: {
+          ...((baseYAxis as { axisLabel?: object }).axisLabel ?? {}),
+          formatter: (value: number) => {
+            if (value !== niceMaxVal && value !== niceMinVal) return ''
+            if (value === 0) return ''
+            return liveFormatter ? liveFormatter(value) : String(value)
+          },
+        },
+      } as EChartsOption['yAxis'],
+      tooltip: {
+        ...baseTooltip,
+        formatter: buildHistogramTooltipFormatter(liveFormatter),
+      },
+    } as EChartsOption
+  }
+}
+
+/**
+ * Tooltip formatter for the histogram's positional `[binLabel, count]`
+ * row shape. ECharts surfaces the x-axis category through `item.name`
+ * (already pre-formatted by the bin-label generator), and `item.value`
+ * comes in as the array tuple — distinct from bar's `{ name, value }`
+ * object row.
+ */
+function buildHistogramTooltipFormatter(
+  formatter: ((value: number) => string) | undefined,
+) {
+  return createTooltipFormatter((item) => {
+    const row = item.value as [string, number] | undefined
+    const raw = row?.[1]
+    const formattedValue =
+      typeof raw === 'number' && formatter ? formatter(raw) : (raw ?? '')
+    const marker = typeof item.marker === 'string' ? item.marker : ''
+    const seriesName = item.seriesName ? `${item.seriesName}: ` : ''
+    return {
+      name: String(item.name ?? ''),
+      seriesName,
+      marker,
+      value: formattedValue,
+    }
+  })
+}
+
+function computeHistogramNiceBounds(seriesArr: HistogramWidgetData): {
+  niceMinVal: number
+  niceMaxVal: number
+} {
+  let max = -Infinity
+  for (const counts of seriesArr) {
+    for (const v of counts) {
+      if (typeof v !== 'number' || !Number.isFinite(v)) continue
+      if (v > max) max = v
+    }
+  }
+  return {
+    niceMinVal: 0,
+    niceMaxVal: max <= 0 ? 1 : niceNum(max),
+  }
+}
+
+function formatNumber(n: number): string {
+  if (Number.isInteger(n)) return String(n)
+  return Number(n.toFixed(2)).toString()
+}

package/src/widgets-v2/histogram/skeleton.test.tsx

@@ -0,0 +1,16 @@
+import { describe, it, expect } from 'vitest'
+import { render } from '@testing-library/react'
+import { HistogramSkeleton } from './skeleton'
+
+describe('<HistogramSkeleton>', () => {
+  it('renders one Skeleton per bin (default 12) plus 4 legend stubs', () => {
+    const { container } = render(<HistogramSkeleton />)
+    // 12 bars + 2 legend items × (circle + label) = 16.
+    expect(container.querySelectorAll('.MuiSkeleton-root').length).toBe(16)
+  })
+
+  it('honours a custom bin count', () => {
+    const { container } = render(<HistogramSkeleton bins={4} />)
+    expect(container.querySelectorAll('.MuiSkeleton-root').length).toBe(8)
+  })
+})

package/src/widgets-v2/histogram/skeleton.tsx

@@ -0,0 +1,70 @@
+import { Box, Skeleton, type SxProps, type Theme } from '@mui/material'
+
+const styles = {
+  container: {
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'space-between',
+    flexDirection: 'column',
+    gap: ({ spacing }) => spacing(1),
+    height: ({ spacing }) => spacing(38),
+  },
+  grid: {
+    display: 'flex',
+    alignItems: 'flex-end',
+    flex: '1 1 auto',
+    gap: 0.5,
+    width: '100%',
+  },
+  legend: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: ({ spacing }) => spacing(2),
+    height: ({ spacing }) => spacing(5),
+  },
+  legendItem: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: ({ spacing }) => spacing(1.5),
+  },
+} satisfies Record<string, SxProps<Theme>>
+
+const barSx = (height: number): SxProps<Theme> => ({
+  flex: 1,
+  height: `${height}%`,
+  minWidth: 8,
+})
+
+export interface HistogramSkeletonProps {
+  bins?: number
+}
+
+/**
+ * Loading state for the Histogram widget. Mirrors Bar's skeleton structure
+ * — a grid of bars (bin-shaped silhouette, anchored to the bottom) plus a
+ * legend stub — so the placeholder reads consistently with Bar.
+ */
+export function HistogramSkeleton({ bins = 12 }: HistogramSkeletonProps) {
+  // Sample heights mimicking a typical bell-shaped distribution.
+  const heights = Array.from({ length: bins }, (_, i) => {
+    const t = i / Math.max(1, bins - 1)
+    return Math.round(20 + 80 * Math.exp(-((t - 0.5) ** 2) * 8))
+  })
+  return (
+    <Box sx={styles.container}>
+      <Box sx={styles.grid}>
+        {heights.map((h, i) => (
+          <Skeleton key={`bar-${i}`} variant='rectangular' sx={barSx(h)} />
+        ))}
+      </Box>
+      <Box sx={styles.legend}>
+        {[0, 1].map((i) => (
+          <Box key={`legend-${i}`} sx={styles.legendItem}>
+            <Skeleton variant='circular' width={8} height={8} />
+            <Skeleton width={48} height={8} />
+          </Box>
+        ))}
+      </Box>
+    </Box>
+  )
+}

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

@@ -0,0 +1,46 @@
+import { describe, it, expect } from 'vitest'
+import { toRelativeHistogramData } from './transforms'
+
+describe('toRelativeHistogramData', () => {
+  it('rewrites each bin count as its share of the series total in 0-100', () => {
+    expect(toRelativeHistogramData([[10, 20, 70]])).toEqual([[10, 20, 70]])
+  })
+
+  it('handles non-100 totals (5/20 = 25%)', () => {
+    expect(toRelativeHistogramData([[5, 15]])).toEqual([[25, 75]])
+  })
+
+  it('handles multiple series independently', () => {
+    expect(
+      toRelativeHistogramData([
+        [3, 7],
+        [50, 50],
+      ]),
+    ).toEqual([
+      [30, 70],
+      [50, 50],
+    ])
+  })
+
+  it('returns a series unchanged when its total is zero', () => {
+    expect(toRelativeHistogramData([[0, 0, 0]])).toEqual([[0, 0, 0]])
+  })
+
+  it('produces signed share-of-magnitude percentages for mixed-sign series', () => {
+    // Denominator is 1000 + 990 = 1990
+    const out = toRelativeHistogramData([[1000, -990]]) as number[][]
+    expect(out[0]?.[0]).toBeCloseTo(50.25126, 4)
+    expect(out[0]?.[1]).toBeCloseTo(-49.74874, 4)
+  })
+
+  it('returns the input unchanged when shape does not match number[][]', () => {
+    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 }],
+    ])
+  })
+})

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

@@ -0,0 +1,30 @@
+/**
+ * Histogram-specific `RelativeData` transform. Histogram data is
+ * `number[][]` — each series is a flat list of bin counts. This
+ * rewrites each count to its share of the series total (0–100), so
+ * pairing with `createPercentFormatter` renders the y-axis as
+ * percentages.
+ *
+ * Pass to `<Widget.RelativeData transform={toRelativeHistogramData} />`.
+ *
+ * The denominator is the sum of |value| across the series so mixed-sign
+ * 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
+ * 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 (total <= 0) return series
+    return series.map((v) => (v / 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))
+}

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

@@ -0,0 +1,55 @@
+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.
+ * The option factory's merge phase (see {@link createHistogramOptionFactory})
+ * combines this with `ticks` to produce a 2-column dataset (`[binLabel, count]`)
+ * for ECharts.
+ */
+export type HistogramWidgetData = readonly (readonly number[])[]
+
+/** Inputs to the structural-only {@link histogramOptions} builder. */
+export interface HistogramOptionsInput {
+  theme: Theme
+  formatter?: (value: number) => string
+}
+
+/**
+ * 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`,
+ * `series`, `labelFormatter`, `selection`).
+ */
+export interface HistogramOptionFactoryInput {
+  theme: Theme
+  formatter?: (value: number) => string
+  /** Bin boundaries — length = bins + 1. */
+  ticks: readonly number[]
+  /**
+   * 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
+   * categories): this one is histogram-specific and runs only on the
+   * generated bin-range strings before they hit the x-axis.
+   */
+  labelFormatter?: (label: string) => string
+  /**
+   * Selected bin indices. Bins not in this list render dimmed
+   * (`itemStyle.opacity: 0.15`). `null`/empty means no selection.
+   */
+  selection?: readonly number[] | null
+  /**
+   * Consumer-supplied partial option merged into the structural option at
+   * structural-build time. Lets stories override pieces of the theme-aware
+   * base without forking the structural builder.
+   */
+  optionsOverride?: Partial<EChartsOption>
+}
+
+export type HistogramEChartsOption = EChartsOption