Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
16.4 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

/**
 * @file Chart.tsx (v2)
 * @input Data, scale configuration, series definitions, optional chrome, and root DOM props
 * @output Root chart — coordinates layout, rendering, and events
 * @position Top-level; delegates everything to series configs and interaction slots
 *
 * The chart root has ZERO knowledge of mark types. It:
 *   1. Runs the layout engine (scales + stacking + grouping)
 *   2. Calls each series' resolve() and render() methods
 *   3. Provides a single event layer for interaction children
 *
 * Accessibility: the svg is exposed as a named image (role="img"; `title` or a
 * derived default as aria-label), and small datasets are mirrored in a
 * visually hidden data table for screen reader users.
 */

'use client';

import {
  type ReactNode,
  type Ref,
  useId,
  useMemo,
  useRef,
  useState,
  useCallback,
  useLayoutEffect,
} from 'react';
import type {SeriesDef, YBaseline} from './types';
import type {ChartContext, ChartMargin, ChartPointerEvent} from './types';
import {computeLayout} from './layout';
import {ChartProvider} from './ChartContext';
import {
  Text,
  VStack,
  HStack,
  VisuallyHidden,
  useLocale,
  useTranslator,
  type BaseProps,
} from '@astryxdesign/core';
import {useMergedRefs} from '@astryxdesign/core/hooks';
import {mergeProps} from '@astryxdesign/core/utils';
import {spacingVars} from '@astryxdesign/core/theme/tokens.stylex';
import * as stylex from '@stylexjs/stylex';
import {ChartLegend, type ChartLegendProps} from './ChartLegend';
import {deriveLegendItems} from './legend';
import {ChartTooltip, type ChartTooltipProps} from './ChartTooltip';
import {useChartColors} from './useChartColors';
import {formatList} from './formatters';
import {isUtilityMarkType} from './types';

export interface ChartProps extends BaseProps<HTMLDivElement> {
  /** Ref forwarded to the root chart container. */
  ref?: Ref<HTMLDivElement>;
  /** Rows to visualize. Each row may contain the x field and one or more series fields. */
  data: Record<string, unknown>[];
  /** Field name read from each data row for the shared x scale. */
  xKey: string;
  /** Mark definitions rendered against the chart's shared scales. */
  series: SeriesDef[];
  /** Chart height in CSS pixels. Non-finite and negative values resolve to 0. @default 300 */
  height?: number;
  /** Partial plot inset override in CSS pixels. */
  margin?: Partial<ChartMargin>;
  /** How the y-domain is derived when `yDomain` is not set. @default 'auto' */
  yBaseline?: YBaseline;
  /** Explicit y-domain [min, max]. Authoritative — disables baseline/headroom. */
  yDomain?: [number, number];
  /**
   * Explicit x-domain [min, max] for numeric/linear x. Honored even when `data`
   * is empty (stable streaming window). Ignored for categorical (band) scales.
   */
  xDomain?: [number, number];
  /** Grid content rendered behind the series, normally `ChartGrid`. */
  grid?: ReactNode;
  /** Axis content rendered after the series, normally one or more `ChartAxis` elements. */
  axes?: ReactNode;
  /** Show the derived legend, or configure its items and layout. @default false */
  legend?: boolean | ChartLegendProps;
  /** Show the grouped pointer tooltip, or configure its presentation. @default false */
  tooltip?: boolean | Omit<ChartTooltipProps, 'series'>;
  /** Interaction overlays rendered above the pointer-capture layer. */
  interactions?: ReactNode;
  /** Additional SVG content rendered after the built-in tooltip. */
  children?: ReactNode;
  /** Visible chart heading and accessible name for the SVG image. */
  title?: string;
  /** Visible supporting text and accessible description for the SVG image. */
  subtitle?: string;
}

const DEFAULT_MARGIN: ChartMargin = {top: 24, right: 24, bottom: 32, left: 48};

/**
 * Maximum number of data points (rows × data keys) for which the visually
 * hidden data-table fallback is rendered. Beyond this a table is more noise
 * than signal for screen reader users, so larger charts are name-only.
 */
const MAX_TABLE_POINTS = 100;

/** Stringify a cell value for the hidden data table. */
function tableCell(value: unknown): string {
  return value == null ? '' : String(value);
}

const styles = stylex.create({
  container: {
    width: '100%',
  },
  title: {
    marginBlockEnd: spacingVars['--spacing-4'],
  },
  chartArea: {
    flex: 1,
    minWidth: 0,
    overflow: 'clip',
  },
});

/**
 * Renders several series against one responsive x/y coordinate system.
 *
 * @example
 * ```
 * <Chart
 *   data={monthlyRevenue}
 *   xKey="month"
 *   series={[bar('revenue'), line('trend')]}
 *   title="Monthly revenue"
 *   grid={<ChartGrid horizontal />}
 *   axes={<><ChartAxis position="bottom" /><ChartAxis position="left" /></>}
 *   legend
 *   tooltip
 * />
 * ```
 */
export function Chart({
  data,
  xKey,
  series,
  height = 300,
  margin: marginOverride,
  yBaseline,
  yDomain,
  xDomain,
  grid,
  axes,
  legend,
  tooltip,
  interactions,
  children,
  title,
  subtitle,
  ref,
  xstyle,
  className,
  style,
  ...rest
}: ChartProps) {
  const chartId = useId();
  const descId = `${chartId}-desc`;
  // useId() can contain ':' which is invalid in an SVG url(#id) reference.
  const clipId = `plot-${chartId.replace(/:/g, '')}`;
  const containerRef = useRef<HTMLDivElement>(null);
  const mergedContainerRef = useMergedRefs(containerRef, ref);
  const svgRef = useRef<SVGSVGElement>(null);
  const t = useTranslator();
  const locale = useLocale();
  const [containerWidth, setContainerWidth] = useState(0);
  const pointerHandlers = useRef<Set<(e: ChartPointerEvent) => void>>(
    new Set(),
  );

  useLayoutEffect(() => {
    if (!containerRef.current) {
      return;
    }
    const observer = new ResizeObserver(entries => {
      const entry = entries[0];
      if (entry) {
        setContainerWidth(entry.contentRect.width);
      }
    });
    observer.observe(containerRef.current);
    return () => observer.disconnect();
  }, []);

  const margin = useMemo(
    () => ({...DEFAULT_MARGIN, ...marginOverride}),
    [marginOverride],
  );
  // Clamp plot dimensions to finite, non-negative values. layout.ts hardens
  // against NaN in the *data*, but a non-finite `height` prop or margin override
  // would still collapse every scale range — and the clipPath/event-rect
  // geometry — into NaN. `containerWidth` is always finite (from ResizeObserver).
  const safeHeight = Number.isFinite(height) ? Math.max(0, height) : 0;
  const rawInnerWidth = containerWidth - margin.left - margin.right;
  const rawInnerHeight = safeHeight - margin.top - margin.bottom;
  const innerWidth = Number.isFinite(rawInnerWidth)
    ? Math.max(0, rawInnerWidth)
    : 0;
  const innerHeight = Number.isFinite(rawInnerHeight)
    ? Math.max(0, rawInnerHeight)
    : 0;

  // ─── Color assignment ─────────────────────────────────────────────────
  // Give every primary series that doesn't supply a static color (auto-colored
  // or accessor-colored) a distinct color from the theme's categorical palette.
  // Utility marks (band/errorBar/referenceLine) don't consume palette slots.
  // Assigned during render (like the layout pass annotates `_uid`) so the first
  // paint is already colored; intentionally not a `useMemo` — it mutates the
  // caller's series defs, and useMemo is allowed to drop its cached result.
  const chartColors = useChartColors();
  const needsColor = series.filter(
    s => !isUtilityMarkType(s.type) && s.color == null,
  );
  const palette = chartColors.categorical(Math.max(needsColor.length, 1));
  for (let i = 0; i < needsColor.length; i++) {
    needsColor[i]._resolvedColor = palette[i % palette.length];
  }

  // ─── Layout pass ──────────────────────────────────────────────────────
  const layout = useMemo(
    () =>
      computeLayout({
        data,
        xKey,
        series,
        width: innerWidth,
        height: innerHeight,
        yBaseline,
        yDomain,
        xDomain,
      }),
    [data, xKey, series, innerWidth, innerHeight, yBaseline, yDomain, xDomain],
  );

  const seriesCtx = useMemo(
    () => ({
      data,
      xKey,
      xScale: layout.xScale,
      yScale: layout.yScale,
      yBandScale: layout.yBandScale,
      width: innerWidth,
      height: innerHeight,
    }),
    [data, xKey, layout, innerWidth, innerHeight],
  );

  // ─── Event dispatch ───────────────────────────────────────────────────
  const onPointer = useCallback((handler: (e: ChartPointerEvent) => void) => {
    pointerHandlers.current.add(handler);
    return () => {
      pointerHandlers.current.delete(handler);
    };
  }, []);

  const dispatch = useCallback((e: ChartPointerEvent) => {
    for (const handler of pointerHandlers.current) {
      handler(e);
    }
  }, []);

  const handlePointerMove = useCallback(
    (e: React.PointerEvent<SVGRectElement>) => {
      const svg = svgRef.current;
      if (!svg) {
        return;
      }
      const point = svg.createSVGPoint();
      point.x = e.clientX;
      point.y = e.clientY;
      const ctm = e.currentTarget.getScreenCTM()?.inverse();
      if (!ctm) {
        return;
      }
      const cursor = point.matrixTransform(ctm);

      // Find nearest point by x-distance only (full vertical column is the hover zone)
      let nearest: ChartPointerEvent['nearest'] = null;
      let bestXDist = Infinity;
      for (const [seriesKey, points] of layout.resolved) {
        for (const p of points) {
          const xDist = Math.abs(p.px - cursor.x);
          if (xDist < bestXDist) {
            bestXDist = xDist;
            nearest = {...p, seriesKey};
          }
        }
      }
      dispatch({x: cursor.x, y: cursor.y, nearest, active: e.buttons > 0});
    },
    [layout.resolved, dispatch],
  );

  const handlePointerLeave = useCallback(() => {
    dispatch({x: -1, y: -1, nearest: null, active: false});
  }, [dispatch]);

  // ─── Context for interactions + v1 chrome ─────────────────────────────
  const ctx: ChartContext = useMemo(
    () => ({
      width: innerWidth,
      height: innerHeight,
      margin,
      data,
      xKey,
      xScale: layout.xScale,
      yScale: layout.yScale,
      yBandScale: layout.yBandScale,
      resolved: layout.resolved,
      onPointer,
      svgRef,
    }),
    [innerWidth, innerHeight, margin, data, xKey, layout, onPointer],
  );

  // ─── Accessibility ─────────────────────────────────────────────────────
  // The svg is exposed as a named image. `title` (when given) is the name;
  // otherwise a localized default is derived from the primary series + x key.
  const primarySeries = series.filter(s => !isUtilityMarkType(s.type));
  const accessibleLabel =
    title ??
    (primarySeries.length > 0
      ? t('@astryx.chart.labelWithSeries', {
          series: formatList(
            primarySeries.map(s => s.label ?? s.key),
            locale,
          ),
          xKey,
        })
      : t('@astryx.chart.label'));
  const tableKeys = Array.from(new Set(primarySeries.flatMap(s => s.dataKeys)));
  const showDataTable =
    data.length > 0 &&
    tableKeys.length > 0 &&
    data.length * tableKeys.length <= MAX_TABLE_POINTS;

  // ─── Legend ────────────────────────────────────────────────────────────
  const legendConfig = legend === true ? {} : legend || null;

  const legendElement = legendConfig ? (
    <ChartLegend
      items={legendConfig.items ?? deriveLegendItems(series)}
      position={legendConfig.position}
      alignment={legendConfig.alignment}
    />
  ) : null;

  const legendPosition = legendConfig?.position ?? 'bottom';
  const isLegendHorizontal =
    legendPosition === 'start' || legendPosition === 'end';

  // ─── Render ───────────────────────────────────────────────────────────
  if (containerWidth === 0) {
    return (
      <div
        ref={mergedContainerRef}
        {...mergeProps(
          stylex.props(styles.container, xstyle),
          {style: {height: safeHeight}},
          className,
          style,
        )}
        {...rest}
      />
    );
  }

  return (
    <div
      ref={mergedContainerRef}
      {...mergeProps(stylex.props(styles.container, xstyle), className, style)}
      {...rest}>
      {(title || subtitle) && (
        <div {...stylex.props(styles.title)}>
          {title && (
            <Text type="body" weight="semibold" display="block">
              {title}
            </Text>
          )}
          {subtitle && (
            <Text type="supporting" display="block">
              {subtitle}
            </Text>
          )}
        </div>
      )}
      <ChartProvider value={ctx}>
        {legendConfig == null ? (
          renderSvg()
        ) : isLegendHorizontal ? (
          <HStack gap={4}>
            {legendPosition === 'start' && legendElement}
            <div {...stylex.props(styles.chartArea)}>{renderSvg()}</div>
            {legendPosition === 'end' && legendElement}
          </HStack>
        ) : (
          <VStack gap={4}>
            {legendPosition === 'top' && legendElement}
            {renderSvg()}
            {legendPosition === 'bottom' && legendElement}
          </VStack>
        )}
      </ChartProvider>
      {renderDataTable()}
    </div>
  );

  function renderSvg() {
    return (
      <svg
        ref={svgRef}
        role="img"
        width="100%"
        height={safeHeight}
        aria-label={accessibleLabel}
        aria-describedby={subtitle ? descId : undefined}>
        {title && <title>{title}</title>}
        {subtitle && <desc id={descId}>{subtitle}</desc>}
        <defs>
          <clipPath id={clipId}>
            <rect x={0} y={0} width={innerWidth} height={innerHeight} />
          </clipPath>
        </defs>
        <g transform={`translate(${margin.left},${margin.top})`}>
          {/* 1. Grid */}
          {grid}

          {/* 2. Marks — each series renders itself. Clipped to the plot area so
              curve overshoot (monotone/natural) can't escape into the margins. */}
          <g clipPath={`url(#${clipId})`}>
            {series.map(s => {
              const resolved = s._uid ? layout.resolved.get(s._uid) : undefined;
              if (!resolved) {
                return null;
              }
              return <g key={s._uid}>{s.render(resolved, seriesCtx)}</g>;
            })}
          </g>

          {/* 3. Axes */}
          {axes}

          {/* 4. Event capture + interactions */}
          <rect
            x={0}
            y={0}
            width={innerWidth}
            height={innerHeight}
            fill="transparent"
            onPointerMove={handlePointerMove}
            onPointerLeave={handlePointerLeave}
          />
          {interactions}

          {/* 5. Tooltip — declarative shortcut. For full control, render
              <ChartTooltip> directly via the `children` slot. */}
          {tooltip && (
            <ChartTooltip
              series={series}
              {...(tooltip === true ? {} : tooltip)}
            />
          )}

          {/* 6. Escape hatch */}
          {children}
        </g>
      </svg>
    );
  }

  function renderDataTable() {
    if (!showDataTable) {
      return null;
    }
    return (
      <VisuallyHidden as="div">
        <table>
          <caption>
            {t('@astryx.chart.dataTableCaption', {label: accessibleLabel})}
          </caption>
          <thead>
            <tr>
              <th scope="col">{xKey}</th>
              {tableKeys.map(key => (
                <th key={key} scope="col">
                  {key}
                </th>
              ))}
            </tr>
          </thead>
          <tbody>
            {data.map((d, i) => (
              <tr key={i}>
                <th scope="row">{tableCell(d[xKey])}</th>
                {tableKeys.map(key => (
                  <td key={key}>{tableCell(d[key])}</td>
                ))}
              </tr>
            ))}
          </tbody>
        </table>
      </VisuallyHidden>
    );
  }
}

Chart.displayName = 'Chart';