Skip to content

The Open Standard for Generative UI

8.2 KB
Raw Blame
import { useId, useMemo } from "react";
import { useEffectiveAnimation } from "../hooks";
import { useCalendarHeatmapOrchestrator } from "../hooks/cartesian/useCalendarHeatmapOrchestrator";
import { ChartShell } from "../shared/core/ChartShell";
import { ChartTooltip } from "../shared/core/PortalTooltip/ChartTooltip";
import { CHART_CLASS_PREFIX } from "../utils/constants";
import { CalendarCells } from "./parts/CalendarCells";
import { CalendarLegend } from "./parts/CalendarLegend";
import { CalendarPatternDefs, calendarPatternId } from "./parts/CalendarPatternDefs";
import { CalendarSeparatorLabels, CalendarSeparators } from "./parts/CalendarSeparators";
import { MonthAxis } from "./parts/MonthAxis";
import { useDelayedHover } from "./parts/useDelayedHover";
import { WeekdayAxis } from "./parts/WeekdayAxis";
import type { CalendarHeatmapProps } from "./types";

const CLASS_PREFIX = `${CHART_CLASS_PREFIX}-calendar-heatmap`;

/** `` (q, year) => `Q1 2026` `` — the default quarter-label formatter. */
const defaultQuarterLabel = (quarter: number, year: number) => `Q${quarter} ${year}`;

export function CalendarHeatmap(props: CalendarHeatmapProps) {
  const {
    data,
    range,
    thresholds,
    levelColors,
    levelStyles,
    layout = "fluid",
    binSize,
    gap = 3,
    weekStartDay = 0,
    hideGhostCells = true,
    weekdayTickFilter = "odd",
    weekdayLabelFormat = "full",
    showMonthLabels = true,
    columnSeparators,
    legendVariant = "swatches",
    legendLabels,
    valueLabel = "Contributions",
    formatTooltipLabel,
    tooltipDelay,
    rowOpacity,
    isAnimationActive = false,
    animationDuration = 1600,
    width,
    height,
    customPalette,
    onClick,
    className,
  } = props;

  const showLegend = legendVariant !== "none";

  const orch = useCalendarHeatmapOrchestrator({
    data: data ?? [],
    // No calendarHeatmapPalette token on react-ui's ChartColorPalette yet (same
    // gap as heatmap/funnel/scatter) — the catch-all default palette is the token.
    themePaletteName: "defaultChartPalette",
    customPalette,
    levelColors,
    levelStyles,
    thresholds,
    range,
    layout,
    binSize,
    gap,
    weekStartDay,
    hideGhostCells,
    weekdayTickFilter,
    weekdayLabelFormat,
    showMonthLabels,
    columnSeparators,
    showLegend,
    valueLabel,
    formatTooltipLabel,
    width,
    height,
  });

  const animate = useEffectiveAnimation(isAnimationActive);

  // Namespace the pattern ids so several calendars on one page never collide.
  const patternBaseId = useId().replace(/:/g, "");

  const {
    separators,
    dimensions: {
      svgWidth,
      svgHeight,
      gutterLeft,
      gutterTop,
      pitchX,
      pitchY,
      cellW,
      cellH,
      plotHeight,
      monthLabelY,
      weekdayLabelX,
    },
  } = orch;

  // Per-level fill: the level CSS var, or a pattern ref when that level sets one.
  const levelFills = useMemo(
    () =>
      orch.levelStyles.map((style, level) =>
        style?.pattern
          ? `url(#${calendarPatternId(patternBaseId, level)})`
          : `var(--${CLASS_PREFIX}-level-${level})`,
      ),
    [orch.levelStyles, patternBaseId],
  );

  // Hovering a legend level highlights it and clears any cell hover/tooltip.
  const handleLevelEnter = (level: number) => {
    orch.hover.setHoveredLevel(level);
    orch.hover.handleMouseLeave();
  };
  const handleLevelLeave = () => orch.hover.setHoveredLevel(null);

  // Delay the tooltip's show/hide edges (grace period smooths cell-to-cell hops).
  const activeTooltip = useMemo(
    () =>
      orch.tooltip.tooltipPayload && orch.hover.mousePos
        ? {
            ...orch.tooltip.tooltipPayload,
            viewportPosition: orch.hover.mousePos,
          }
        : null,
    [orch.tooltip.tooltipPayload, orch.hover.mousePos],
  );
  const shownTooltip = useDelayedHover(activeTooltip, tooltipDelay);

  const labelFormat = columnSeparators?.labelFormat ?? defaultQuarterLabel;

  return (
    <ChartShell
      containerRef={orch.refs.containerRef}
      classPrefix={CLASS_PREFIX}
      className={className}
      style={orch.style.containerStyle}
      isEmpty={orch.isEmpty}
    >
      {() => (
        <>
          <div className={`${CLASS_PREFIX}-plot`} style={{ position: "relative", width: svgWidth }}>
            <svg
              width={svgWidth}
              height={svgHeight}
              style={{ overflow: "visible" }}
              role="img"
              aria-label="Calendar heatmap chart"
            >
              <CalendarPatternDefs
                baseId={patternBaseId}
                levelStyles={orch.levelStyles}
                levelColors={orch.levelColors}
              />

              {showMonthLabels && (
                <g transform={`translate(${gutterLeft}, 0)`}>
                  <MonthAxis
                    labels={orch.monthLabels}
                    pitchX={pitchX}
                    xOffsets={separators.offsets}
                    y={monthLabelY}
                    classPrefix={CLASS_PREFIX}
                  />
                </g>
              )}

              <g transform={`translate(0, ${gutterTop})`}>
                <WeekdayAxis
                  ticks={orch.weekdayTicks}
                  pitchY={pitchY}
                  x={weekdayLabelX}
                  classPrefix={CLASS_PREFIX}
                />
              </g>

              <g
                transform={`translate(${gutterLeft}, ${gutterTop})`}
                onMouseLeave={orch.hover.handleMouseLeave}
                // Grid dim is LEGEND-hover scoped (bklit parity): hovering a
                // cell only lights up its legend swatch, never re-shades the
                // grid — so this reads `hoveredLevel`, not `highlightedLevel`.
                {...{
                  [`data-${CHART_CLASS_PREFIX}-highlight-level`]:
                    orch.hover.hoveredLevel ?? undefined,
                }}
              >
                <CalendarCells
                  cells={orch.cells}
                  classPrefix={CLASS_PREFIX}
                  pitchX={pitchX}
                  pitchY={pitchY}
                  cellW={cellW}
                  cellH={cellH}
                  gap={gap}
                  levelFills={levelFills}
                  xOffsets={separators.offsets}
                  rowOpacity={rowOpacity}
                  animate={animate}
                  animationDuration={animationDuration}
                  onCellMouseMove={orch.hover.handleCellMouseMove}
                  onCellMouseLeave={orch.hover.handleMouseLeave}
                  onClick={onClick}
                />
                <CalendarSeparators
                  columns={separators.columns}
                  offsets={separators.offsets}
                  pitchX={pitchX}
                  spacing={separators.spacing}
                  gap={gap}
                  plotHeight={plotHeight}
                  stroke={columnSeparators?.stroke}
                  dashed={columnSeparators?.dashed}
                  classPrefix={CLASS_PREFIX}
                />
              </g>
            </svg>

            <CalendarSeparatorLabels
              labels={separators.labels}
              offsets={separators.offsets}
              pitchX={pitchX}
              gutterLeft={gutterLeft}
              format={labelFormat}
              classPrefix={CLASS_PREFIX}
            />
          </div>

          {showLegend && (
            <CalendarLegend
              ref={orch.refs.legendRef}
              variant={legendVariant === "gradient" ? "gradient" : "swatches"}
              levelColors={orch.levelColors}
              levelStyles={orch.levelStyles}
              patternBaseId={patternBaseId}
              labels={{
                less: legendLabels?.less ?? "Less",
                more: legendLabels?.more ?? "More",
              }}
              highlightedLevel={orch.hover.highlightedLevel}
              onLevelEnter={handleLevelEnter}
              onLevelLeave={handleLevelLeave}
              classPrefix={CLASS_PREFIX}
            />
          )}

          {shownTooltip && (
            <ChartTooltip
              label={shownTooltip.label}
              items={shownTooltip.items}
              viewportPosition={shownTooltip.viewportPosition}
            />
          )}
        </>
      )}
    </ChartShell>
  );
}