Skip to content

The Open Standard for Generative UI

17.6 KB
Raw Blame
import type { ScaleLinear } from "d3-scale";
import { scaleLinear } from "d3-scale";
import { pointer } from "d3-selection";
import React, { useCallback, useEffect, useMemo, useRef, useState } from "react";

import {
  BAR_GAP,
  BAR_HEIGHT,
  BAR_RADIUS,
  barValue,
  contentHeight as computeContentHeight,
  groupHeight as computeGroupHeight,
  rowOffsets as computeRowOffsets,
  snapPositions as computeSnapPositions,
  nearestSnap,
  radiusArray,
  showInternalLine,
  stackSegments,
  valueDomain,
  verticalPadding,
  X_AXIS_HEIGHT,
} from "../../BarChart/parts/horizontalBarGeometry";
import type { BarChartData, BarChartProps } from "../../BarChart/types";
import type { TooltipItem } from "../../shared/core/PortalTooltip/ChartTooltip";
import type { LegendItem } from "../../types";
import { buildContainerStyle } from "../../utils/buildContainerStyle";
import { DEFAULT_CHART_HEIGHT } from "../../utils/constants";
import { getDataKeys } from "../../utils/dataUtils";
import { buildColumnKeys } from "../../utils/heatmapUtils";
import { parseLineHeight } from "../../utils/labelWrap";
import { useChartPalette } from "../../utils/paletteUtils";
import { numberTickFormatter } from "../../utils/styleUtils";
import { useCanvasContextForLabelSize } from "../core/useCanvasContextForLabelSize";
import { useChartShell } from "../core/useChartShell";
import { useSeriesVisibility } from "../core/useSeriesVisibility";

/**
 * Small left margin (px) so the value-zero line / leftmost bar isn't flush
 * against the container edge. Kept SMALL — smaller than the category label's
 * left padding — so the leftmost gridline sits in the label's PADDING, never
 * through its text (the bug a bigger inset caused). Edge tick-label clipping is
 * handled by `NumericXAxis edgeAlign`, NOT by insetting the scale.
 */
const AXIS_PAD = 2;
/** Minimum px between value ticks — matched to `NumericXAxis`/`VerticalGrid` so
 *  the shared scale produces the same ticks in the grid and the bottom axis. */
const TICK_MIN_SPACING = 60;

/** One rendered bar (a whole grouped bar, or one segment of a stacked bar). */
export interface HorizontalBar {
  /** React key within the row (grouped: the series key; stacked: the segment
   *  key). */
  key: string;
  /** The series this bar/segment belongs to (drives color + tooltip). */
  seriesKey: string;
  /** Left edge (px) in the row SVG's coordinate space; negatives extend left of
   *  `valueScale(0)`, so `x` is already the LEFT edge for either sign. */
  x: number;
  /** Top edge (px) in the row SVG's coordinate space. */
  y: number;
  /** Bar extent along the value axis (px), always `>= 0`. */
  width: number;
  /** Cross-axis thickness (px) — always `BAR_HEIGHT`. */
  height: number;
  /** Series color (distributed palette, keyed to input order — matches the
   *  vertical BarChart). */
  color: string;
  /** Per-corner radii `[tl, tr, br, bl]` for `roundedBarPath`. */
  radii: [number, number, number, number];
  /** Value is `< 0` — the bar draws left of the zero line. */
  isNegative: boolean;
  /** Bar is wide enough to carry its internal decorative line. */
  showLine: boolean;
  /** The finite, signed value this bar represents. */
  value: number;
}

/** One category row: its label band plus every bar drawn under it. */
export interface HorizontalBarRow {
  /** Stable React key (duplicate categories disambiguated); NOT for display. */
  key: string;
  /** The category label (display string). */
  category: string;
  /** Top edge (px) of the whole group (label + bars) in the row SVG. */
  rowTop: number;
  /** Height (px) of the whole group — uniform across rows. */
  groupHeight: number;
  /** Bars under this row: grouped → one per visible series; stacked → the
   *  sign-diverging segments (positives then negatives). */
  bars: HorizontalBar[];
}

/**
 * Private orchestrator for the HORIZONTAL BarChart — the integration layer that
 * turns `BarChartProps` into a render-ready structure for the row renderer
 * (`HorizontalBarSeries`) and the shell (`HorizontalBarChartImpl`). Mirrors the
 * `ScatterChart`/`FunnelChart` precedent: renders through `ChartShell` WITHOUT
 * `CartesianChartLayout`, so it touches none of the shared vertical Line/Area
 * machinery.
 *
 * All orientation math is delegated to the pure `horizontalBarGeometry` module
 * (group/content heights, row offsets, snap targets, value domain, stack split,
 * corner radii, internal-line threshold); this hook is glue — measurement,
 * scales, per-row bar geometry, hover hit-testing, tooltip payload, and the
 * vertical snap-scroll state.
 *
 * @param props         The BarChart props (already on the horizontal path).
 * @param containerRef  Attached by the shell to the measured container (feeds
 *                      `useChartShell`'s size + emptiness).
 * @param scrollBodyRef Attached by the shell to the `overflow-y:auto` scroll
 *                      body; read for `scrollTop`/`scrollHeight`/`clientHeight`
 *                      to drive the snap-scroll buttons.
 *
 * Returned shape (consumed by Task 5/6):
 * - `isEmpty`, `isPrinting` — from the shell.
 * - `legendRef`, `containerStyle` — wire the legend + container.
 * - `dataKeys` (visible series), `colors` (parallel to `dataKeys`),
 *   `legendItems` (ALL series), `labelHeight` (measured band height).
 * - `valueScale` (zero-anchored, `.nice()`), `ticks`, `formatTick`.
 * - `rows` (one `HorizontalBarRow` per category, data order), `rowOffsets`,
 *   `groupHeight` (uniform row height, for the hover crosshair band),
 *   `snapPositions`, `contentHeight` (raw), `svgHeight` (drawn, incl. pad),
 *   `topPad`, `bodyHeight`, `chartWidth`, `chartHeight`.
 * - `hover` { hoveredIndex, hoveredCategory, onMouseMove, onMouseLeave }.
 * - `tooltip` { payload, position }.
 * - `legend` { hiddenSeries, toggleSeries, isLegendExpanded, setIsLegendExpanded }.
 * - `scroll` { canUp, canDown, needsScroll, onScrollUp, onScrollDown, onScroll }.
 */
export function useHorizontalBarChartOrchestrator<T extends BarChartData>(
  props: BarChartProps<T>,
  containerRef: React.RefObject<HTMLDivElement | null>,
  scrollBodyRef: React.RefObject<HTMLDivElement | null>,
) {
  const {
    data,
    categoryKey,
    variant = "grouped",
    customPalette,
    barRadius = BAR_RADIUS,
    legend: showLegend = true,
    height,
    width,
    fitLegendInHeight,
  } = props;

  const catKey = String(categoryKey);
  const legendRef = useRef<HTMLDivElement>(null);
  const context = useCanvasContextForLabelSize(containerRef);

  const {
    isPrinting,
    containerWidth,
    containerHeight,
    isEmpty,
    legendHeight,
    shouldFitLegend,
    isLegendExpanded,
    setIsLegendExpanded,
  } = useChartShell({
    data,
    showLegend,
    containerRef,
    legendRef,
    width,
    height,
    fitLegendInHeight,
  });

  // --- Series keys + visibility (legend toggle hides a series, matching the
  // vertical BarChart's useChartData path) ---
  const allDataKeys = useMemo(() => getDataKeys(data, catKey), [data, catKey]);
  const { hiddenSeries, toggleSeries } = useSeriesVisibility(allDataKeys);
  const dataKeys = useMemo(
    () => allDataKeys.filter((k) => !hiddenSeries.has(k)),
    [allDataKeys, hiddenSeries],
  );

  // --- Colors: DISTRIBUTED (middle-out) across the series, keyed to the
  // ORIGINAL index so a legend toggle never recolors the rest. This is the
  // SAME resolution the vertical BarChart uses — useChartData →
  // useChartPalette → getDistributedColors(resolvePalette(theme,
  // 'barChartPalette', customPalette), allDataKeys.length) — so a horizontal
  // and a vertical BarChart on the same data color identically (and match
  // openui, which also distributes rather than reading the raw ordered ramp).
  // ---
  const ramp = useChartPalette({
    customPalette,
    themePaletteName: "barChartPalette",
    dataLength: allDataKeys.length,
  });
  const colorMap = useMemo(() => {
    const map: Record<string, string> = {};
    allDataKeys.forEach((key, i) => {
      map[key] = ramp[i] ?? "#000000";
    });
    return map;
  }, [allDataKeys, ramp]);
  const colors = useMemo(
    () => dataKeys.map((key) => colorMap[key] ?? "#000000"),
    [dataKeys, colorMap],
  );

  const legendItems: LegendItem[] = useMemo(
    () =>
      allDataKeys.map((key) => ({
        key,
        label: key,
        color: colorMap[key] ?? "#000000",
      })),
    [allDataKeys, colorMap],
  );

  // --- Category-label band height: single line-height (from the theme font)
  // padded, floored at 24 (openui's `max(measured + 8, 24)`). ---
  const labelHeight = useMemo(
    () => Math.max(Math.ceil(parseLineHeight(context.font)) + 8, 24),
    [context],
  );

  // --- Dimensions (shell measurement → chart / body sizes) ---
  const effectiveHeight = containerHeight || (typeof height === "number" ? height : 0);
  const totalHeight = effectiveHeight || DEFAULT_CHART_HEIGHT;
  const legendDeduction = showLegend && shouldFitLegend ? legendHeight : 0;
  const chartHeight = Math.max(0, totalHeight - legendDeduction);
  const chartWidth = containerWidth || 0;
  const bodyHeight = Math.max(0, chartHeight - X_AXIS_HEIGHT);

  // --- Value scale: zero-anchored domain (0 always inside), niced, mapped to
  // the drawable width. One scale drives the bars, the grid, and the bottom
  // axis (pixel-exact vs openui's two-chart hack). ---
  const rightEdge = Math.max(AXIS_PAD, chartWidth - AXIS_PAD);
  const [domainMin, domainMax] = useMemo(
    () => valueDomain(data, dataKeys, variant),
    [data, dataKeys, variant],
  );
  const valueScale: ScaleLinear<number, number> = useMemo(
    () => scaleLinear().domain([domainMin, domainMax]).nice().range([AXIS_PAD, rightEdge]),
    [domainMin, domainMax, rightEdge],
  );
  const ticks = useMemo(() => {
    const tickCount = Math.max(2, Math.floor(chartWidth / TICK_MIN_SPACING));
    return valueScale.ticks(tickCount);
  }, [valueScale, chartWidth]);

  // --- Per-row layout (all delegated to the geometry module) ---
  const rowCount = data.length;
  const seriesCount = dataKeys.length;
  const groupHeight = useMemo(
    () => computeGroupHeight(seriesCount, variant, labelHeight),
    [seriesCount, variant, labelHeight],
  );
  const contentHeight = useMemo(
    () => computeContentHeight(rowCount, groupHeight),
    [rowCount, groupHeight],
  );
  const pad = useMemo(
    () => verticalPadding(contentHeight, bodyHeight),
    [contentHeight, bodyHeight],
  );
  const rowOffsets = useMemo(
    () => computeRowOffsets(rowCount, groupHeight, pad.top),
    [rowCount, groupHeight, pad.top],
  );
  const snapPositions = useMemo(
    () => computeSnapPositions(rowCount, groupHeight),
    [rowCount, groupHeight],
  );
  const svgHeight = pad.top + contentHeight + pad.bottom;
  const needsScroll = contentHeight > bodyHeight;

  // Stable React keys per row (LLMs re-emit duplicate categories).
  const rowKeys = useMemo(
    () => buildColumnKeys(data.map((row) => String(row[catKey]))),
    [data, catKey],
  );

  // --- Bars per row: grouped → one bar per visible series offset down the
  // group; stacked → sign-diverging segments laid from the zero line. ---
  const rows: HorizontalBarRow[] = useMemo(() => {
    const zeroX = valueScale(0);
    return data.map((row, i) => {
      const rowTop = rowOffsets[i] ?? 0;
      const barsTop = rowTop + labelHeight;
      const bars: HorizontalBar[] = [];

      if (variant === "stacked") {
        const { positives, negatives } = stackSegments(row, dataKeys);
        // Positives stack rightward from 0; negatives stack leftward from 0.
        let cumulative = 0;
        for (const seg of positives) {
          const start = valueScale(cumulative);
          cumulative += seg.value;
          const end = valueScale(cumulative);
          const width = Math.abs(end - start);
          bars.push({
            key: seg.key,
            seriesKey: seg.key,
            x: Math.min(start, end),
            y: barsTop,
            width,
            height: BAR_HEIGHT,
            color: colorMap[seg.key] ?? "#000000",
            radii: radiusArray("stacked", barRadius, seg.isFirst, seg.isLast, false),
            isNegative: false,
            showLine: showInternalLine(width),
            value: seg.value,
          });
        }
        cumulative = 0;
        for (const seg of negatives) {
          const start = valueScale(cumulative);
          cumulative += seg.value;
          const end = valueScale(cumulative);
          const width = Math.abs(end - start);
          bars.push({
            key: seg.key,
            seriesKey: seg.key,
            x: Math.min(start, end),
            y: barsTop,
            width,
            height: BAR_HEIGHT,
            color: colorMap[seg.key] ?? "#000000",
            radii: radiusArray("stacked", barRadius, seg.isFirst, seg.isLast, true),
            isNegative: true,
            showLine: showInternalLine(width),
            value: seg.value,
          });
        }
      } else {
        dataKeys.forEach((key, j) => {
          const value = barValue(row[key]);
          const valueX = valueScale(value);
          const width = Math.abs(valueX - zeroX);
          const isNegative = value < 0;
          bars.push({
            key,
            seriesKey: key,
            x: Math.min(zeroX, valueX),
            y: barsTop + j * (BAR_HEIGHT + BAR_GAP),
            width,
            height: BAR_HEIGHT,
            color: colorMap[key] ?? "#000000",
            radii: radiusArray("grouped", barRadius, false, false, isNegative),
            isNegative,
            showLine: showInternalLine(width),
            value,
          });
        });
      }

      return {
        key: rowKeys[i] ?? String(row[catKey]),
        category: String(row[catKey]),
        rowTop,
        groupHeight,
        bars,
      };
    });
  }, [
    data,
    catKey,
    dataKeys,
    variant,
    valueScale,
    rowOffsets,
    labelHeight,
    groupHeight,
    colorMap,
    barRadius,
    rowKeys,
  ]);

  // --- Hover: hit-test the pointer's SVG-local y against the row offsets
  // (whole group — label band + bars — highlights the category). ---
  const [hoveredIndex, setHoveredIndex] = useState<number | null>(null);
  const [mousePos, setMousePos] = useState<{ x: number; y: number } | null>(null);

  const handleMouseMove = useCallback(
    (event: React.MouseEvent<SVGSVGElement>) => {
      const [, my] = pointer(event.nativeEvent, event.currentTarget);
      let found: number | null = null;
      for (let i = 0; i < rowOffsets.length; i++) {
        const top = rowOffsets[i] ?? 0;
        if (my >= top && my < top + groupHeight) {
          found = i;
          break;
        }
      }
      setHoveredIndex(found);
      setMousePos({ x: event.clientX, y: event.clientY });
    },
    [rowOffsets, groupHeight],
  );

  const handleMouseLeave = useCallback(() => {
    setHoveredIndex(null);
    setMousePos(null);
  }, []);

  const hoveredCategory = hoveredIndex !== null ? (rows[hoveredIndex]?.category ?? null) : null;

  // --- Tooltip: category label + one row per visible series ---
  const tooltipPayload = useMemo(() => {
    if (hoveredIndex === null) return null;
    const row = data[hoveredIndex];
    if (!row) return null;
    const items: TooltipItem[] = dataKeys.map((key) => ({
      name: key,
      value: barValue(row[key]),
      color: colorMap[key] ?? "#000000",
    }));
    return { label: String(row[catKey]), items };
  }, [hoveredIndex, data, dataKeys, colorMap, catKey]);

  // --- Vertical snap-scroll (mirrors useChartScroll's boundary math on the Y
  // axis). Buttons render only when the content overflows the body. ---
  const [canScrollUp, setCanScrollUp] = useState(false);
  const [canScrollDown, setCanScrollDown] = useState(needsScroll);

  useEffect(() => {
    if (!needsScroll) {
      setCanScrollUp(false);
      setCanScrollDown(false);
      return;
    }
    const el = scrollBodyRef.current;
    if (el) {
      setCanScrollUp(el.scrollTop > 0);
      setCanScrollDown(el.scrollTop < el.scrollHeight - el.clientHeight - 1);
    } else {
      setCanScrollDown(true);
    }
  }, [needsScroll, scrollBodyRef, contentHeight, bodyHeight]);

  const onScroll = useCallback(() => {
    const el = scrollBodyRef.current;
    if (!el) return;
    setCanScrollUp(el.scrollTop > 0);
    setCanScrollDown(el.scrollTop < el.scrollHeight - el.clientHeight - 1);
  }, [scrollBodyRef]);

  const onScrollUp = useCallback(() => {
    const el = scrollBodyRef.current;
    if (!el) return;
    const idx = nearestSnap(snapPositions, el.scrollTop, "up");
    el.scrollTo({ top: snapPositions[idx] ?? 0, behavior: "smooth" });
  }, [scrollBodyRef, snapPositions]);

  const onScrollDown = useCallback(() => {
    const el = scrollBodyRef.current;
    if (!el) return;
    const idx = nearestSnap(snapPositions, el.scrollTop, "down");
    el.scrollTo({ top: snapPositions[idx] ?? 0, behavior: "smooth" });
  }, [scrollBodyRef, snapPositions]);

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

  return {
    isEmpty,
    isPrinting,
    legendRef,
    containerStyle,

    dataKeys,
    colors,
    legendItems,
    labelHeight,

    valueScale,
    ticks,
    formatTick: numberTickFormatter,

    rows,
    rowOffsets,
    groupHeight,
    snapPositions,
    contentHeight,
    svgHeight,
    topPad: pad.top,
    bodyHeight,
    chartWidth,
    chartHeight,

    hover: {
      hoveredIndex,
      hoveredCategory,
      onMouseMove: handleMouseMove,
      onMouseLeave: handleMouseLeave,
    },
    tooltip: { payload: tooltipPayload, position: mousePos },
    legend: {
      hiddenSeries,
      toggleSeries,
      isLegendExpanded,
      setIsLegendExpanded,
    },
    scroll: {
      canUp: canScrollUp,
      canDown: canScrollDown,
      needsScroll,
      onScrollUp,
      onScrollDown,
      onScroll,
    },
  };
}