Skip to content

OpenPanel is an open-source web and product analytics platform, an open-source alternative to Mixpanel with optional self-hosting.

7.9 KB
Raw Blame
'use client';

import { motion } from 'motion/react';
import { useId, useLayoutEffect, useMemo } from 'react';
import { chartCssVars, useChartStable, useYScale } from './chart-context';
import { type PatternPresetId, renderPatternPreset } from './pattern-preset';
import {
  computeReferenceAreaRect,
  type ReferenceAreaIfOverflow,
} from './reference-area-geometry';
import { useReferenceAreaRegistration } from './reference-area-registration-context';
import { normalizeYAxisId } from './y-axis-scales';
import { isReferenceAreaVisiblePhase } from './y-domain-utils';

const DEFAULT_FILL =
  'color-mix(in oklch, var(--chart-foreground-muted) 12%, transparent)';

export type ReferenceAreaStrokeStyle = 'solid' | 'dashed';

export interface ReferenceAreaProps {
  /** Lower Y data bound (extends to plot top when omitted). */
  y1?: number;
  /** Upper Y data bound (extends to plot bottom when omitted). */
  y2?: number;
  /** Starting X data coordinate (extends to plot left when omitted). */
  x1?: Date | number;
  /** Ending X data coordinate (extends to plot right when omitted). */
  x2?: Date | number;
  /** Y-scale group id. Default: `"left"`. */
  yAxisId?: string | number;
  /** Solid fill when `pattern` is `"none"`. */
  fill?: string;
  fillOpacity?: number;
  /** Pattern preset. `"none"` uses solid `fill`. */
  pattern?: PatternPresetId;
  /** Pattern stroke / tile color. */
  patternColor?: string;
  patternScale?: number;
  patternStrokeWidth?: number;
  patternRadius?: number;
  patternComplement?: boolean;
  patternFill?: string;
  patternDotFill?: boolean;
  patternTileBackground?: string;
  stroke?: string;
  strokeWidth?: number;
  strokeStyle?: ReferenceAreaStrokeStyle;
  /** Dash array when `strokeStyle` is `"dashed"`. Default: `"4,4"`. */
  strokeDasharray?: string;
  /** Fade fill and edge lines at left/right. Default: true */
  fadeEdges?: boolean;
  /** Horizontal fade zone as % of plot width per edge. Default: 10 */
  fadeEdgesLength?: number;
  /** Y-axis tick label color for values inside this band. */
  axisLabelColor?: string;
  /** Inward bracket markers at the horizontal center of the band. */
  showMarkers?: boolean;
  markerColor?: string;
  markerSize?: number;
  ifOverflow?: ReferenceAreaIfOverflow;
  className?: string;
}

const ENTER_FADE_MS = 420;

function clampFadeLength(length: number): number {
  return Math.min(45, Math.max(0, length));
}

function bracketMarkerPath(
  centerX: number,
  edgeY: number,
  size: number,
  direction: 'down' | 'up'
): string {
  const half = size / 2;
  if (direction === 'down') {
    return `M ${centerX - half} ${edgeY} L ${centerX + half} ${edgeY} L ${centerX} ${edgeY + size} Z`;
  }
  return `M ${centerX - half} ${edgeY} L ${centerX + half} ${edgeY} L ${centerX} ${edgeY - size} Z`;
}

export function ReferenceArea({
  y1,
  y2,
  x1,
  x2,
  yAxisId,
  fill = DEFAULT_FILL,
  fillOpacity = 1,
  pattern = 'none',
  patternColor = chartCssVars.foregroundMuted,
  patternScale = 1,
  patternStrokeWidth,
  patternRadius,
  patternComplement,
  patternFill,
  patternDotFill,
  patternTileBackground,
  stroke = chartCssVars.foregroundMuted,
  strokeWidth = 1,
  strokeStyle = 'dashed',
  strokeDasharray = '4,4',
  fadeEdges = true,
  fadeEdgesLength = 10,
  axisLabelColor,
  showMarkers = false,
  markerColor = 'var(--chart-1)',
  markerSize = 6,
  ifOverflow = 'hidden',
  className,
}: ReferenceAreaProps) {
  const { innerWidth, innerHeight, xScale, chartPhase, enterTransition } =
    useChartStable();
  const yScale = useYScale(yAxisId);
  const uniqueId = useId().replace(/:/g, '');
  const registration = useReferenceAreaRegistration();

  useLayoutEffect(() => {
    if (!registration) {
      return;
    }
    registration.registerReferenceArea(uniqueId, {
      yAxisId: normalizeYAxisId(yAxisId),
      y1,
      y2,
      axisLabelColor,
    });
    return () => registration.unregisterReferenceArea(uniqueId);
  }, [registration, uniqueId, yAxisId, y1, y2, axisLabelColor]);

  const patternId = `chart-reference-area-pattern-${uniqueId}`;
  const hMaskId = `chart-reference-area-fade-${uniqueId}`;
  const hGradientId = `${hMaskId}-gradient`;

  const rect = useMemo(
    () =>
      computeReferenceAreaRect({
        innerWidth,
        innerHeight,
        x1,
        x2,
        y1,
        y2,
        ifOverflow,
        xScale,
        yScale,
      }),
    [innerWidth, innerHeight, x1, x2, y1, y2, ifOverflow, xScale, yScale]
  );

  const usesPattern = pattern !== 'none';
  const patternNode = useMemo(() => {
    if (!usesPattern) {
      return null;
    }
    return renderPatternPreset(pattern, patternId, {
      color: patternColor,
      scale: patternScale,
      strokeWidth: patternStrokeWidth,
      radius: patternRadius,
      complement: patternComplement,
      fill: patternFill,
      dotFill: patternDotFill,
      tileBackground: patternTileBackground,
    });
  }, [
    usesPattern,
    pattern,
    patternId,
    patternColor,
    patternScale,
    patternStrokeWidth,
    patternRadius,
    patternComplement,
    patternFill,
    patternDotFill,
    patternTileBackground,
  ]);

  const fadeEdge = clampFadeLength(fadeEdgesLength);
  const edgeMask = fadeEdges ? `url(#${hMaskId})` : undefined;
  const lineDash = strokeStyle === 'dashed' ? strokeDasharray : undefined;

  if (!rect) {
    return null;
  }

  const { x, y, width, height } = rect;
  const topEdgeY = y;
  const bottomEdgeY = y + height;
  const centerX = x + width / 2;
  const visible = isReferenceAreaVisiblePhase(chartPhase);
  const fadeTransition =
    enterTransition && typeof enterTransition === 'object'
      ? enterTransition
      : { duration: ENTER_FADE_MS / 1000, ease: 'easeOut' as const };
  const areaFill = usesPattern && patternNode ? `url(#${patternId})` : fill;

  return (
    // biome-ignore lint/a11y/noAriaHiddenOnFocusable: decorative reference band
    <motion.g
      animate={{ opacity: visible ? 1 : 0 }}
      aria-hidden="true"
      className={className ?? 'chart-reference-area'}
      initial={{ opacity: 0 }}
      transition={fadeTransition}
    >
      {edgeMask ? (
        <defs>
          <linearGradient id={hGradientId} x1="0%" x2="100%" y1="0%" y2="0%">
            <stop offset="0%" style={{ stopColor: 'white', stopOpacity: 0 }} />
            <stop
              offset={`${fadeEdge}%`}
              style={{ stopColor: 'white', stopOpacity: 1 }}
            />
            <stop
              offset={`${100 - fadeEdge}%`}
              style={{ stopColor: 'white', stopOpacity: 1 }}
            />
            <stop
              offset="100%"
              style={{ stopColor: 'white', stopOpacity: 0 }}
            />
          </linearGradient>
          <mask id={hMaskId}>
            <rect
              fill={`url(#${hGradientId})`}
              height={innerHeight}
              width={innerWidth}
              x={0}
              y={0}
            />
          </mask>
        </defs>
      ) : null}
      {patternNode ? <defs>{patternNode}</defs> : null}
      <rect
        fill={areaFill}
        fillOpacity={fillOpacity}
        height={height}
        mask={edgeMask}
        width={width}
        x={x}
        y={y}
      />
      <g mask={edgeMask}>
        <line
          stroke={stroke}
          strokeDasharray={lineDash}
          strokeWidth={strokeWidth}
          x1={x}
          x2={x + width}
          y1={topEdgeY}
          y2={topEdgeY}
        />
        <line
          stroke={stroke}
          strokeDasharray={lineDash}
          strokeWidth={strokeWidth}
          x1={x}
          x2={x + width}
          y1={bottomEdgeY}
          y2={bottomEdgeY}
        />
      </g>
      {showMarkers ? (
        <>
          <path
            d={bracketMarkerPath(centerX, topEdgeY, markerSize, 'down')}
            fill={markerColor}
          />
          <path
            d={bracketMarkerPath(centerX, bottomEdgeY, markerSize, 'up')}
            fill={markerColor}
          />
        </>
      ) : null}
    </motion.g>
  );
}

ReferenceArea.displayName = 'ReferenceArea';

export default ReferenceArea;