Skip to content

The Open Standard for Generative UI

14.8 KB
Raw Blame
import { scaleBand, scaleQuantize } from "d3-scale";
import { useMemo, useRef } from "react";

import type { ChartColorPalette } from "../../../ThemeProvider";
import { useTheme } from "../../../ThemeProvider";
import type { LegendItem } from "../../types";
import { buildContainerStyle } from "../../utils/buildContainerStyle";
import { CHART_MARGIN_TOP, DEFAULT_CHART_HEIGHT } from "../../utils/constants";
import { getDataKeys } from "../../utils/dataUtils";
import type { HeatmapRampMode } from "../../utils/heatmapUtils";
import {
  buildColumnKeys,
  computeHeatmapColorDomain,
  computeLabelInterval,
} from "../../utils/heatmapUtils";
import {
  DIVERGING_DEFAULT_DARK,
  DIVERGING_DEFAULT_LIGHT,
  orientRampToSurface,
  resolvePalette,
} from "../../utils/paletteUtils";
import { useCanvasContextForLabelSize } from "../core/useCanvasContextForLabelSize";
import { useChartShell } from "../core/useChartShell";
import { useLegendHeight } from "../core/useLegendHeight";
import { usePerElementHover } from "../core/usePerElementHover";
import { useSeriesVisibility } from "../core/useSeriesVisibility";
import { useXAxisHeight } from "./useXAxisHeight";

// Mirror measureYAxisWidth's clamp (its constants are private and its
// formatting is numeric-tick-only — heatmap row labels are category strings).
const MIN_Y_AXIS_WIDTH = 20;
const MAX_Y_AXIS_WIDTH = 200;
const Y_AXIS_PADDING = 10;

// X labels thin out (every n-th) so each shown label gets room for the widest
// label text, between these bounds: at least ~3 characters of the tick font,
// and no more than this so one long label doesn't thin the whole axis (longer
// labels truncate). The gap keeps neighbouring labels apart.
const MIN_X_LABEL_PX = 28;
const MAX_X_LABEL_PX = 64;
const X_LABEL_GAP = 8;

export interface HoveredHeatmapCell {
  rowKey: string;
  columnIndex: number;
  columnLabel: string;
  /** null = the cell has no numeric value. */
  value: number | null;
}

/**
 * A cell's numeric value, or null for "no value". Empty/whitespace-only
 * strings are treated as missing — `Number('')` is 0, which would otherwise
 * paint blank cells as value-0 AND drag the quantize domain's min to 0,
 * recoloring every other cell. Single source of truth for the extent scan,
 * the cell renderer, and the legend row means — they must agree or the color
 * domain and the painted cells drift apart.
 */
export const heatmapCellValue = (raw: string | number | undefined): number | null => {
  if (raw === undefined || (typeof raw === "string" && raw.trim() === "")) {
    return null;
  }
  const value = Number(raw);
  return Number.isFinite(value) ? value : null;
};

/** Tooltip context rows show means at one decimal — enough to compare by. */
const roundMean = (mean: number): number => Math.round(mean * 10) / 10;

export interface UseHeatmapChartOrchestratorParams<
  T extends Array<Record<string, string | number>>,
> {
  data: T;
  categoryKey: keyof T[number];
  themePaletteName: keyof ChartColorPalette;
  customPalette?: string[];
  rampMode: HeatmapRampMode;
  showLegend: boolean;
  showColorScale: boolean;
  showYAxis: boolean;
  height?: number | string;
  width?: number | string;
  fitLegendInHeight?: boolean;
}

/**
 * Orchestrator for the heatmap: a band×band grid where the VALUE axis is
 * color. Follows useScatterChartOrchestrator's standalone fit-only shape, with
 * three deliberate differences: the y axis is categorical (row labels measured
 * as text, not numeric ticks), the palette is consumed as an ORDERED ramp via
 * resolvePalette (never getDistributedColors — a heatmap wants the gradient,
 * not center-out series picks), and hover is per-cell (the chart's cells own
 * their mouse handlers; there is no plot-level hit search). Per-cell hover is
 * the pie/radial regime and, like those charts, is mouse-only for now — touch
 * support belongs to a unified pass over the per-element-handler charts, not
 * a heatmap one-off.
 */
export function useHeatmapChartOrchestrator<T extends Array<Record<string, string | number>>>({
  data,
  categoryKey,
  themePaletteName,
  customPalette,
  rampMode,
  showLegend,
  showColorScale,
  showYAxis,
  height,
  width,
  fitLegendInHeight,
}: UseHeatmapChartOrchestratorParams<T>) {
  const containerRef = useRef<HTMLDivElement>(null);
  const legendRef = useRef<HTMLDivElement>(null);
  const colorScaleRef = useRef<HTMLDivElement>(null);
  const {
    hovered: hoveredCell,
    mousePos,
    handleMouseMove: handleCellMouseMove,
    handleMouseLeave,
  } = usePerElementHover<HoveredHeatmapCell>();

  const {
    isPrinting,
    containerWidth,
    containerHeight,
    isEmpty,
    legendHeight,
    shouldFitLegend,
    isLegendExpanded,
    setIsLegendExpanded,
  } = useChartShell({
    data,
    showLegend,
    containerRef,
    legendRef,
    width,
    height,
    fitLegendInHeight,
    // Heatmap is ALSO empty when row 0 carries no series keys — nothing to
    // draw even with rows present, which a bare row count can't see.
    isEmptyOverride:
      !data || data.length === 0 || getDataKeys(data, String(categoryKey)).length === 0,
  });
  // Same measured-deduction mechanism as the legend: the color-scale strip is
  // HTML below the svg, so its real height (typography-dependent) comes from
  // observation, not a constant. Shares the shell's isEmpty so the strip
  // remounts/re-observes in lockstep with the legend.
  const colorScaleHeight = useLegendHeight(colorScaleRef, showColorScale && !isEmpty);
  const context = useCanvasContextForLabelSize(containerRef);
  const { theme, mode } = useTheme();

  const catKey = String(categoryKey);

  // --- Data shape: columns from the category field, rows from the series keys ---
  const columns = useMemo(() => data.map((row) => String(row[catKey])), [data, catKey]);
  const rowKeys = useMemo(() => getDataKeys(data, catKey), [data, catKey]);

  const { hiddenSeries: hiddenRows, toggleSeries: toggleRow } = useSeriesVisibility(rowKeys);

  const visibleRowKeys = useMemo(
    () => rowKeys.filter((key) => !hiddenRows.has(key)),
    [rowKeys, hiddenRows],
  );

  // --- Color: ordered ramp quantized over the visible value extent ---
  // Diverging mode without a customPalette uses the built-in two-hue ramps:
  // the theme's sequential ramp can't express "neutral at zero" (mirroring it
  // would give both signs the same hue). A customPalette always wins — in
  // diverging mode it's read as the full low→neutral→high ramp.
  const ramp = useMemo(() => {
    if (rampMode === "diverging" && !customPalette) {
      return mode === "dark" ? DIVERGING_DEFAULT_DARK : DIVERGING_DEFAULT_LIGHT;
    }
    // A customPalette is used as given; the theme's palette is oriented so low
    // values sit nearest the surface.
    return customPalette
      ? resolvePalette(theme, themePaletteName, customPalette)
      : orientRampToSurface(resolvePalette(theme, themePaletteName), mode);
  }, [rampMode, customPalette, mode, theme, themePaletteName]);

  const [minValue, maxValue] = useMemo(() => {
    let min = Infinity;
    let max = -Infinity;
    for (const row of data) {
      for (const key of visibleRowKeys) {
        const value = heatmapCellValue(row[key]);
        if (value !== null) {
          min = Math.min(min, value);
          max = Math.max(max, value);
        }
      }
    }
    if (!Number.isFinite(min)) return [0, 1];
    return [min, max];
  }, [data, visibleRowKeys]);

  const colorScale = useMemo(() => {
    // Domain rules (collapsed-extent widening; diverging = symmetric about
    // zero) live in computeHeatmapColorDomain — unit-tested there.
    const [domainMin, domainMax] = computeHeatmapColorDomain(minValue, maxValue, rampMode);
    return scaleQuantize<string>().domain([domainMin, domainMax]).range(ramp);
  }, [minValue, maxValue, rampMode, ramp]);

  // The color-scale legend strip: one swatch per ramp bucket, each with the
  // exact value range the quantize scale assigns it — honest by construction.
  // Extents come from thresholds() BY INDEX, not invertExtent(color):
  // invertExtent looks colors up with indexOf, so a customPalette that
  // repeats a color would hand every repeat the FIRST occurrence's range.
  const colorScaleBuckets = useMemo(() => {
    const [domainMin, domainMax] = colorScale.domain();
    const thresholds = colorScale.thresholds();
    return ramp.map((color, index) => ({
      color,
      lo: index === 0 ? domainMin : thresholds[index - 1]!,
      hi: index === ramp.length - 1 ? domainMax : thresholds[index]!,
    }));
  }, [ramp, colorScale]);

  // --- Dimensions (scatter's standalone fit math) ---
  // Width measured over ALL rows (not just visible) so toggling a row in the
  // legend doesn't shift the whole plot horizontally.
  const yAxisWidth = useMemo(() => {
    if (!showYAxis) return 0;
    let max = 0;
    for (const key of rowKeys) {
      max = Math.max(max, context.measureText(key).width);
    }
    return Math.max(MIN_Y_AXIS_WIDTH, Math.min(MAX_Y_AXIS_WIDTH, Math.ceil(max) + Y_AXIS_PADDING));
  }, [showYAxis, rowKeys, context]);

  const xAxisHeight = useXAxisHeight(data, catKey, "singleLine");

  const effectiveHeight = containerHeight || (typeof height === "number" ? height : 0);
  const totalHeight = effectiveHeight || DEFAULT_CHART_HEIGHT;
  const legendDeduction = showLegend && shouldFitLegend ? legendHeight : 0;
  const colorScaleDeduction = showColorScale && shouldFitLegend ? colorScaleHeight : 0;
  const chartInnerHeight =
    totalHeight - CHART_MARGIN_TOP - xAxisHeight - legendDeduction - colorScaleDeduction;
  const chartAreaWidth = Math.max(0, (containerWidth || 0) - yAxisWidth);

  const totalSvgWidth = containerWidth || 0;
  const totalSvgHeight = CHART_MARGIN_TOP + Math.max(0, chartInnerHeight) + xAxisHeight;

  // --- Scales (band × band; cell gap is applied at render time so it stays
  // an exact pixel inset instead of a proportional band padding) ---
  const xScale = useMemo(
    () => scaleBand<string>().domain(columns).range([0, chartAreaWidth]),
    [columns, chartAreaWidth],
  );

  // React keys for the cell columns — duplicate labels disambiguated (the
  // x scale interns duplicates into one band, but React keys must be unique).
  const columnKeys = useMemo(() => buildColumnKeys(columns), [columns]);

  // Thin the x labels once columns get narrower than their labels. The step
  // comes from the SCALE: its domain interns duplicate labels, and XAxis thins
  // over those unique bands — columns.length would over-count (and over-thin)
  // whenever an LLM re-emits a category.
  const widestColumnLabel = useMemo(
    () => columns.reduce((max, label) => Math.max(max, context.measureText(label).width), 0),
    [columns, context],
  );
  const labelInterval = computeLabelInterval(
    xScale.step(),
    Math.min(MAX_X_LABEL_PX, Math.max(MIN_X_LABEL_PX, widestColumnLabel)) + X_LABEL_GAP,
  );
  const yScale = useMemo(
    () =>
      scaleBand<string>()
        .domain(visibleRowKeys)
        .range([0, Math.max(0, chartInnerHeight)]),
    [visibleRowKeys, chartInnerHeight],
  );

  // --- Row/column means: tooltip context + the row-legend swatch colors.
  // Row means scan ALL columns (a hidden row's swatch should still summarize
  // its own data); column means scan only VISIBLE rows (they contextualize
  // what's on screen).
  const rowMeans = useMemo(() => {
    const means = new Map<string, number>();
    for (const key of rowKeys) {
      let sum = 0;
      let count = 0;
      for (const row of data) {
        const value = heatmapCellValue(row[key]);
        if (value !== null) {
          sum += value;
          count++;
        }
      }
      if (count > 0) means.set(key, sum / count);
    }
    return means;
  }, [rowKeys, data]);

  const columnMeans = useMemo(
    () =>
      data.map((row) => {
        let sum = 0;
        let count = 0;
        for (const key of visibleRowKeys) {
          const value = heatmapCellValue(row[key]);
          if (value !== null) {
            sum += value;
            count++;
          }
        }
        return count > 0 ? sum / count : null;
      }),
    [data, visibleRowKeys],
  );

  // --- Tooltip ---
  const tooltipPayload = useMemo(() => {
    if (!hoveredCell) return null;
    const { rowKey, columnIndex, columnLabel, value } = hoveredCell;
    if (value === null) {
      // An empty cell is still a place on the grid — name it instead of
      // leaving a tooltip-less dead zone indistinguishable from a miss.
      return {
        label: columnLabel,
        items: [{ name: rowKey, value: "No value", color: "transparent" }],
      };
    }
    const items: { name: string; value: number | string; color: string }[] = [
      { name: rowKey, value, color: colorScale(value) },
    ];
    // Context rows: where this cell sits against its row and column. The
    // swatches are the means' own quantize colors — a ramp readout for free.
    const rowMean = rowMeans.get(rowKey);
    if (data.length > 1 && rowMean !== undefined) {
      items.push({
        name: "Row avg",
        value: roundMean(rowMean),
        color: colorScale(rowMean),
      });
    }
    const columnMean = columnMeans[columnIndex];
    if (visibleRowKeys.length > 1 && columnMean != null) {
      items.push({
        name: "Column avg",
        value: roundMean(columnMean),
        color: colorScale(columnMean),
      });
    }
    return { label: columnLabel, items };
  }, [hoveredCell, colorScale, rowMeans, columnMeans, data, visibleRowKeys]);

  // --- Legend: one item per row. A row has no single color under a value
  // ramp, so the swatch shows the quantize color of the row's MEAN value —
  // a row-level summary that keeps swatches distinguishable. ---
  const legendItems: LegendItem[] = useMemo(
    () =>
      rowKeys.map((key) => {
        const mean = rowMeans.get(key);
        const midColor = ramp[Math.floor(ramp.length / 2)] ?? "#000000";
        return {
          key,
          label: key,
          color: mean !== undefined ? colorScale(mean) : midColor,
        };
      }),
    [rowKeys, rowMeans, colorScale, ramp],
  );

  const containerStyle = useMemo(() => buildContainerStyle({}, width, height), [width, height]);

  return {
    refs: { containerRef, legendRef, colorScaleRef },
    isPrinting,
    isEmpty,
    data: {
      catKey,
      columns,
      columnKeys,
      rowKeys,
      visibleRowKeys,
      hiddenRows,
      toggleRow,
    },
    dimensions: {
      containerWidth,
      effectiveYAxisWidth: yAxisWidth,
      chartAreaWidth,
      chartInnerHeight: Math.max(0, chartInnerHeight),
      totalSvgWidth,
      totalSvgHeight,
      xAxisHeight,
      labelInterval,
      CHART_MARGIN_TOP,
    },
    scales: { xScale, yScale, colorScale },
    colorScaleLegend: {
      buckets: colorScaleBuckets,
      domainMin: colorScale.domain()[0],
      domainMax: colorScale.domain()[1],
    },
    hover: { hoveredCell, mousePos, handleCellMouseMove, handleMouseLeave },
    legend: { legendItems, isLegendExpanded, setIsLegendExpanded },
    tooltip: { tooltipPayload },
    style: { containerStyle },
  };
}