@pharos-ds/charts 0.0.0-stage → 1.0.10

package/src/ChartTooltip.tsx

@@ -0,0 +1,452 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file ChartTooltip.tsx
+ * @output Grouped chart tooltip — shows all series values at the hovered x-position.
+ *         Composable: drop into `<Chart tooltip>` or render directly inside a chart
+ *         to take full control of props.
+ * @position Reads from ChartContext — must render inside an <Chart>.
+ *
+ * Pointer-only: the card is portaled with `pointer-events: none` and holds no
+ * focusable content, so it never traps keyboard focus. Keyboard/screen-reader
+ * users get the same values from the chart's hidden data table instead.
+ *
+ * In a horizontal chart the tooltip renders in the vertical plot space (Chart
+ * wraps it in the same transpose as the marks), so only the screen position of
+ * the card needs to know about `orientation`.
+ *
+ * @example
+ * ```
+ * // Default — declarative on Chart
+ * <Chart tooltip />
+ *
+ * // Custom render function via Chart prop
+ * <Chart tooltip={{render: (x, rows) => <MyCard x={x} rows={rows} />}} />
+ *
+ * // Composable — drop into the chart's children for full control
+ * <Chart>
+ *   <ChartTooltip hoverIndicator={false} placement="top" />
+ * </Chart>
+ * ```
+ */
+
+'use client';
+
+import {
+  memo,
+  useState,
+  useEffect,
+  useMemo,
+  useRef,
+  useCallback,
+  type ReactNode,
+} from 'react';
+import {createPortal} from 'react-dom';
+import * as stylex from '@stylexjs/stylex';
+import {
+  colorVars,
+  radiusVars,
+  shadowVars,
+  spacingVars,
+} from '@pharos-ds/core/theme/tokens.stylex';
+import {Text} from '@pharos-ds/core';
+import {VStack, HStack} from '@pharos-ds/core';
+import {useChart} from './ChartContext';
+import {ChartSwatch, swatchVariantForType} from './ChartSwatch';
+import {
+  deriveTooltipSeriesValues,
+  shouldRenderHoverDot,
+  type TooltipSeriesValue,
+} from './tooltip';
+import type {SeriesDef, ChartPointerEvent} from './types';
+import {isBandScale, xPixel} from './utils';
+
+export type ChartTooltipPlacement = 'auto' | 'right' | 'left' | 'top';
+
+export interface ChartTooltipProps {
+  /**
+   * Series definitions — used to map the hovered datum to per-series rows.
+   * When rendered via `<Chart tooltip />`, Chart injects this automatically.
+   * When composing directly, pass the same `series` array you gave Chart.
+   */
+  series?: readonly SeriesDef[];
+  /**
+   * Custom render function. Receives the x-value and one row per visible series.
+   * Returning `null` hides the card while still rendering the band highlight + dots.
+   */
+  render?: (xValue: unknown, seriesValues: TooltipSeriesValue[]) => ReactNode;
+  /**
+   * Whether to draw a hover indicator at the focused x-position.
+   * Picks the right shape automatically:
+   * - **band-highlight rect** when the chart includes bar series on a band scale
+   * - **vertical crosshair line** for line / area / dot charts
+   *
+   * Default: `true`.
+   */
+  hoverIndicator?: boolean;
+  /**
+   * Whether to draw a hover dot at each series' point (skipped for bars).
+   * Default: `true`.
+   */
+  showHoverDots?: boolean;
+  /**
+   * Card placement relative to the hovered point:
+   * - `'auto'` (default): right of the point, flips to left if it would overflow
+   * - `'right'` / `'left'` / `'top'`: pinned position
+   */
+  placement?: ChartTooltipPlacement;
+}
+
+const styles = stylex.create({
+  // Card chrome — static visual styles. Position (left/top/display) is updated
+  // imperatively via ref to keep pointer-move cost free of React renders.
+  card: {
+    position: 'fixed',
+    backgroundColor: colorVars['--color-background-popover'],
+    border: `1px solid ${colorVars['--color-border']}`,
+    borderRadius: radiusVars['--radius-container'],
+    paddingBlock: spacingVars['--spacing-2'],
+    paddingInline: spacingVars['--spacing-3'],
+    boxShadow: shadowVars['--shadow-med'],
+    pointerEvents: 'none',
+    whiteSpace: 'nowrap',
+    zIndex: 9999,
+    display: 'none',
+  },
+  crosshair: {
+    stroke: colorVars['--color-text-primary'],
+    strokeWidth: 1,
+  },
+});
+
+/** Default tooltip body — used when `render` is not provided. */
+const DefaultTooltipContent = memo(function DefaultTooltipContent({
+  xValue,
+  rows,
+}: {
+  xValue: unknown;
+  rows: TooltipSeriesValue[];
+}) {
+  return (
+    <VStack gap={1}>
+      <Text type="body" weight="semibold">
+        {String(xValue)}
+      </Text>
+      {rows.length === 1 ? (
+        <Text type="supporting">{String(rows[0].value)}</Text>
+      ) : (
+        <VStack gap={1}>
+          {rows.map((row, i) => (
+            <HStack key={`${row.key}-${i}`} gap={2} vAlign="center">
+              <ChartSwatch
+                color={row.color}
+                variant={swatchVariantForType(row.type)}
+              />
+              <Text type="supporting">{row.label}</Text>
+              <Text type="supporting" weight="semibold">
+                {String(row.value)}
+              </Text>
+            </HStack>
+          ))}
+        </VStack>
+      )}
+    </VStack>
+  );
+});
+
+/**
+ * Composable grouped tooltip for Chart.
+ *
+ * Subscribes to the chart's pointer event stream and only re-renders when the
+ * hovered data index changes (not on every pointer move). Card position is
+ * updated imperatively via a ref to keep pointer-move cost ~free.
+ */
+export function ChartTooltip({
+  series = [],
+  render,
+  hoverIndicator = true,
+  showHoverDots = true,
+  placement = 'auto',
+}: ChartTooltipProps) {
+  const {
+    data,
+    xKey,
+    resolved,
+    onPointer,
+    svgRef,
+    margin,
+    xScale,
+    width,
+    height,
+    orientation,
+  } = useChart();
+  const isHorizontal = orientation === 'horizontal';
+  const [hoveredIndex, setHoveredIndex] = useState<number | null>(null);
+  const cardRef = useRef<HTMLDivElement>(null);
+  // Whether the card is currently suppressed (no content, or a custom `render`
+  // opted out by returning null). positionCard reads this so a same-index
+  // pointer move — which repositions the card without a React commit — can't
+  // re-reveal a card the visibility effect below has hidden.
+  const cardHiddenRef = useRef(false);
+
+  // Stable Set of resolved series keys — used by deriveTooltipSeriesValues.
+  // Recomputed only when the resolved map identity changes (per layout pass).
+  const resolvedKeys = useMemo(() => new Set(resolved.keys()), [resolved]);
+
+  // ─── Card positioning ──────────────────────────────────────────────────
+  // Imperative — the card is portaled, and we don't want pointer-move to
+  // trigger React renders.
+  const positionCard = useCallback(
+    (e: ChartPointerEvent) => {
+      const card = cardRef.current;
+      const svg = svgRef.current;
+      if (!card) {
+        return;
+      }
+      if (!svg || !e.nearest || cardHiddenRef.current) {
+        card.style.display = 'none';
+        return;
+      }
+      const svgRect = svg.getBoundingClientRect();
+      const cardWidth = card.offsetWidth;
+      const cardHeight = card.offsetHeight;
+      // Plot space → screen. Horizontal charts are transposed: the category
+      // (px) runs down the y-axis and the value end of the mark (py) maps to
+      // x = plot height − py, so the card sits beside the hovered row.
+      const screenX = isHorizontal
+        ? svgRect.left +
+          margin.left +
+          (Number.isFinite(e.nearest.py) ? height - e.nearest.py : 0)
+        : svgRect.left + margin.left + e.nearest.px;
+      const screenY = isHorizontal
+        ? svgRect.top + margin.top + e.nearest.px - cardHeight / 2
+        : svgRect.top + margin.top;
+      const viewportWidth = window.innerWidth;
+      const viewportHeight = window.innerHeight;
+      const gap = 8;
+
+      let x: number;
+      let y = screenY;
+      switch (placement) {
+        case 'left':
+          x = screenX - cardWidth - gap;
+          break;
+        case 'right':
+          x = screenX + gap;
+          break;
+        case 'top':
+          x = screenX - cardWidth / 2;
+          y = screenY - cardHeight - gap;
+          break;
+        case 'auto':
+        default: {
+          const rightX = screenX + gap;
+          x =
+            rightX + cardWidth > viewportWidth
+              ? screenX - cardWidth - gap
+              : rightX;
+        }
+      }
+
+      // Clamp to the viewport so the card never clips off-screen — it's
+      // portaled and position:fixed, so this keeps it fully visible for every
+      // placement (pinned placements and the near-edge `auto` flip alike).
+      x = Math.max(gap, Math.min(x, viewportWidth - cardWidth - gap));
+      y = Math.max(gap, Math.min(y, viewportHeight - cardHeight - gap));
+
+      card.style.left = `${x}px`;
+      card.style.top = `${y}px`;
+      card.style.display = 'block';
+    },
+    [svgRef, margin, placement, isHorizontal, height],
+  );
+
+  // ─── Subscribe to pointer events ───────────────────────────────────────
+  useEffect(() => {
+    let currentIndex: number | null = null;
+    const unsub = onPointer((e: ChartPointerEvent) => {
+      const newIndex = e.nearest?.dataIndex ?? null;
+      if (newIndex !== currentIndex) {
+        currentIndex = newIndex;
+        // Optimistically treat the new index as showable; the visibility effect
+        // re-hides it after commit if there's no content (e.g. custom `render`
+        // returned null). This keeps the card appearing on the first move.
+        cardHiddenRef.current = false;
+        setHoveredIndex(newIndex);
+      }
+      positionCard(e);
+    });
+    return unsub;
+  }, [onPointer, positionCard]);
+
+  // ─── Derived data ──────────────────────────────────────────────────────
+  const datum = hoveredIndex != null ? data[hoveredIndex] : undefined;
+  const xValue = datum?.[xKey];
+
+  const seriesValues = useMemo(
+    () => deriveTooltipSeriesValues(series, datum, resolvedKeys),
+    [series, datum, resolvedKeys],
+  );
+
+  // Hover dots — read from the resolved map at the hovered index.
+  const dots = useMemo(() => {
+    if (!showHoverDots || hoveredIndex == null) {
+      return null;
+    }
+    const elements: ReactNode[] = [];
+    for (const s of series) {
+      if (!shouldRenderHoverDot(s.type)) {
+        continue;
+      }
+      const points = s._uid ? resolved.get(s._uid) : undefined;
+      const point = points?.find(p => p.dataIndex === hoveredIndex);
+      // A resolved point exists at every index, but its coordinates are NaN when
+      // this series' value here is missing/non-finite (the mark itself filters
+      // these at render time — mirror that so we never emit cx/cy="NaN").
+      if (!point || !Number.isFinite(point.px) || !Number.isFinite(point.py)) {
+        continue;
+      }
+      elements.push(
+        <circle
+          key={s._uid}
+          cx={point.px}
+          cy={point.py}
+          r={4}
+          fill="var(--color-background-surface)"
+          stroke={
+            s.color ?? s._resolvedColor ?? 'var(--color-border-emphasized)'
+          }
+          strokeWidth={2}
+          pointerEvents="none"
+        />,
+      );
+    }
+    return elements;
+  }, [showHoverDots, hoveredIndex, series, resolved]);
+
+  // Hover indicator — band-highlight rect for bar charts, vertical crosshair
+  // line for line/area charts. Same source-of-truth (hoveredIndex), distinct
+  // visual idioms picked automatically based on the series mix.
+  const hoverIndicatorElement = useMemo(() => {
+    if (!hoverIndicator || hoveredIndex == null) {
+      return null;
+    }
+    const hoveredDatum = data[hoveredIndex];
+    const xv = hoveredDatum?.[xKey];
+    if (hoveredDatum == null || xv == null) {
+      return null;
+    }
+    const hasBars = series.some(s => s.type === 'bar');
+
+    // Bar charts on a band scale → soft column highlight.
+    if (hasBars && isBandScale(xScale)) {
+      const x = xScale(String(xv)) ?? 0;
+      const bw = xScale.bandwidth();
+      const pad = 8;
+      const rectX = Math.max(0, x - pad);
+      const rectRight = Math.min(width, x + bw + pad);
+      const rectWidth = rectRight - rectX;
+      // Plot-space "top" is the display's right edge when horizontal.
+      const topPad = Math.min(pad, isHorizontal ? margin.right : margin.top);
+      return (
+        <rect
+          x={rectX}
+          y={-topPad}
+          width={rectWidth}
+          height={height + topPad}
+          fill="currentColor"
+          opacity={0.06}
+          rx={4}
+          pointerEvents="none"
+        />
+      );
+    }
+
+    // Line / area / dot charts → vertical crosshair through the point
+    // (band-center or linear position, resolved by the shared helper).
+    const px = xPixel(hoveredDatum, xKey, xScale);
+    // xPixel returns NaN for a non-finite x on a linear scale; skip rather than
+    // emit x1/x2="NaN". (The band branch above is always finite via `?? 0`.)
+    if (!Number.isFinite(px)) {
+      return null;
+    }
+    return (
+      <line
+        x1={px}
+        x2={px}
+        y1={0}
+        y2={height}
+        {...stylex.props(styles.crosshair)}
+        pointerEvents="none"
+      />
+    );
+  }, [
+    hoverIndicator,
+    hoveredIndex,
+    series,
+    xScale,
+    data,
+    xKey,
+    width,
+    height,
+    margin.top,
+    margin.right,
+    isHorizontal,
+  ]);
+
+  // Single source of truth for whether the card has anything to show. It's
+  // hidden when there's no hover, when the hovered index is stale/out-of-range
+  // (e.g. `data` shrank while hovering, so `datum` is undefined), or when a
+  // custom `render` opts out by returning null — the documented contract, which
+  // still shows the band highlight + dots. The decision is stored in a ref so
+  // the imperative positionCard honors it on subsequent same-index moves
+  // (otherwise it would re-reveal an empty bordered box). Runs after commit, so
+  // `render` (which may return null, or throw) never executes on the SSR path.
+  useEffect(() => {
+    const hidden =
+      hoveredIndex == null ||
+      datum == null ||
+      (render != null && render(xValue, seriesValues) == null);
+    cardHiddenRef.current = hidden;
+    if (hidden) {
+      const card = cardRef.current;
+      if (card) {
+        card.style.display = 'none';
+      }
+    }
+  }, [render, hoveredIndex, datum, xValue, seriesValues]);
+
+  // ─── Render ────────────────────────────────────────────────────────────
+  if (typeof document === 'undefined') {
+    // SSR: no DOM portal target; band highlight + dots still render in SVG.
+    return (
+      <>
+        {hoverIndicatorElement}
+        {dots}
+      </>
+    );
+  }
+
+  // Mirrors the visibility effect's first two conditions: no card when there's
+  // no hover or the hovered datum is stale/out-of-range (so `render` and the
+  // default body are never called with an undefined x-value + empty rows).
+  const cardContent =
+    hoveredIndex == null || datum == null ? null : render ? (
+      render(xValue, seriesValues)
+    ) : (
+      <DefaultTooltipContent xValue={xValue} rows={seriesValues} />
+    );
+
+  return (
+    <>
+      {hoverIndicatorElement}
+      {dots}
+      {createPortal(
+        <div ref={cardRef} role="tooltip" {...stylex.props(styles.card)}>
+          {cardContent}
+        </div>,
+        document.body,
+      )}
+    </>
+  );
+}

package/src/charts.css.d.ts

@@ -0,0 +1,3 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+export {};

package/src/dataTable.test.ts

@@ -0,0 +1,86 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, expect, it} from 'vitest';
+import {buildDataTable, fallbackChartLabel} from './dataTable';
+import {bar, line, band, candlestick, errorBar} from './marks';
+
+const data = [
+  {mes: 'jan', leads: 1200, custo: 300.5},
+  {mes: 'fev', leads: null, custo: 280},
+];
+
+describe('buildDataTable', () => {
+  it('builds headers from xKey + series labels and one row per datum', () => {
+    const model = buildDataTable(data, 'mes', [
+      bar('leads', {label: 'Leads'}),
+      line('custo'),
+    ]);
+    expect(model?.headers).toEqual(['mes', 'Leads', 'custo']);
+    expect(model?.rows.map(r => r.header)).toEqual(['jan', 'fev']);
+    expect(model?.rows[0].cells).toEqual([
+      (1200).toLocaleString(),
+      (300.5).toLocaleString(),
+    ]);
+    // Missing values become empty cells, never "null"/"NaN".
+    expect(model?.rows[1].cells[0]).toBe('');
+  });
+
+  it('skips utility marks and splits multi-key marks into columns', () => {
+    const model = buildDataTable(
+      [{d: 'seg', open: 1, high: 3, low: 0, close: 2, lo: 0, hi: 1}],
+      'd',
+      [
+        candlestick({
+          open: 'open',
+          high: 'high',
+          low: 'low',
+          close: 'close',
+        }),
+        band({lower: 'lo', upper: 'hi'}),
+        errorBar({low: 'lo', high: 'hi'}),
+      ],
+    );
+    expect(model?.headers).toEqual([
+      'd',
+      'ohlc-close (open)',
+      'ohlc-close (high)',
+      'ohlc-close (low)',
+      'ohlc-close (close)',
+    ]);
+  });
+
+  it('applies custom labels and formatters', () => {
+    const model = buildDataTable(data, 'mes', [bar('leads')], {
+      xLabel: 'Mês',
+      formatX: v => String(v).toUpperCase(),
+      formatValue: (v, s, key) => `${s.type}:${key}:${String(v)}`,
+    });
+    expect(model?.headers[0]).toBe('Mês');
+    expect(model?.rows[0]).toMatchObject({
+      header: 'JAN',
+      cells: ['bar:leads:1200'],
+    });
+  });
+
+  it('returns null for empty data, no data series, or more rows than maxRows', () => {
+    expect(buildDataTable([], 'mes', [bar('leads')])).toBeNull();
+    expect(
+      buildDataTable(data, 'mes', [band({lower: 'leads', upper: 'custo'})]),
+    ).toBeNull();
+    expect(
+      buildDataTable(data, 'mes', [bar('leads')], {maxRows: 1}),
+    ).toBeNull();
+  });
+});
+
+describe('fallbackChartLabel', () => {
+  it('joins the data series labels, skipping utility marks', () => {
+    expect(
+      fallbackChartLabel([
+        bar('leads', {label: 'Leads'}),
+        line('custo'),
+        band({lower: 'a', upper: 'b'}),
+      ]),
+    ).toBe('Leads, custo');
+  });
+});

package/src/dataTable.ts

@@ -0,0 +1,124 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file dataTable.ts
+ * @output Pure builder for the chart's text alternative (WCAG 1.1.1): turns
+ *   `data` + `xKey` + `series` into a header row and one row per x value.
+ * @position Used by Chart to render the visually hidden `<table>` that sits
+ *   next to the `role="img"` SVG. Mirrors legend.ts / tooltip.ts: data shaping
+ *   lives here, presentation lives in Chart.tsx.
+ *
+ * Utility marks (band, errorBar, referenceLine) are annotations, not data the
+ * reader compares, so they get no column — same rule as the legend and the
+ * tooltip. A mark that reads several keys (candlestick: open/high/low/close)
+ * gets one column per key.
+ *
+ * SYNC: When modified, update /packages/charts/src/Chart.doc.mjs
+ */
+
+import {isUtilityMarkType, type SeriesDef} from './types';
+
+/** Options for the hidden data table rendered by `<Chart>`. */
+export interface ChartDataTableOptions {
+  /** Header of the first column (the x values). Default: the chart's `xKey`. */
+  xLabel?: string;
+  /** Formats an x value for its row header cell. Default: `String(value)`. */
+  formatX?: (value: unknown) => string;
+  /**
+   * Formats one value cell. Receives the raw value, the series and the data key
+   * being read. Default: locale-formatted numbers, `String()` otherwise and an
+   * empty cell for missing values.
+   */
+  formatValue?: (value: unknown, series: SeriesDef, dataKey: string) => string;
+  /**
+   * Largest `data.length` that still renders a table. Above it the table is
+   * omitted (streaming/WebGL charts with thousands of points) and the chart
+   * relies on its accessible name and `description`. Default: `1000`.
+   */
+  maxRows?: number;
+}
+
+export interface ChartDataTableModel {
+  headers: string[];
+  rows: {key: string; header: string; cells: string[]}[];
+}
+
+/** Default row cap — see `ChartDataTableOptions.maxRows`. */
+export const DATA_TABLE_MAX_ROWS = 1000;
+
+function defaultFormatValue(value: unknown): string {
+  if (value == null) {
+    return '';
+  }
+  if (typeof value === 'number') {
+    return Number.isFinite(value) ? value.toLocaleString() : '';
+  }
+  if (value instanceof Date) {
+    return value.toLocaleDateString();
+  }
+  return String(value);
+}
+
+function defaultFormatX(value: unknown): string {
+  if (value instanceof Date) {
+    return value.toLocaleDateString();
+  }
+  return value == null ? '' : String(value);
+}
+
+/**
+ * Build the table model, or `null` when there is nothing to tabulate (no data,
+ * no data series) or `data` exceeds `maxRows`.
+ */
+export function buildDataTable(
+  data: readonly Record<string, unknown>[],
+  xKey: string,
+  series: readonly SeriesDef[],
+  options: ChartDataTableOptions = {},
+): ChartDataTableModel | null {
+  const maxRows = options.maxRows ?? DATA_TABLE_MAX_ROWS;
+  if (data.length === 0 || data.length > maxRows) {
+    return null;
+  }
+
+  const columns: {series: SeriesDef; dataKey: string; header: string}[] = [];
+  for (const s of series) {
+    if (isUtilityMarkType(s.type)) {
+      continue;
+    }
+    const label = s.label ?? s.key;
+    for (const dataKey of s.dataKeys) {
+      columns.push({
+        series: s,
+        dataKey,
+        header: s.dataKeys.length > 1 ? `${label} (${dataKey})` : label,
+      });
+    }
+  }
+  if (columns.length === 0) {
+    return null;
+  }
+
+  const formatX = options.formatX ?? defaultFormatX;
+  const formatValue = options.formatValue ?? defaultFormatValue;
+
+  return {
+    headers: [options.xLabel ?? xKey, ...columns.map(c => c.header)],
+    rows: data.map((d, i) => ({
+      key: String(i),
+      header: formatX(d[xKey]),
+      cells: columns.map(c => formatValue(d[c.dataKey], c.series, c.dataKey)),
+    })),
+  };
+}
+
+/**
+ * Accessible name fallback when the chart has neither `aria-label` nor
+ * `title`: the data series labels, so the name is never empty.
+ */
+export function fallbackChartLabel(series: readonly SeriesDef[]): string {
+  return series
+    .filter(s => !isUtilityMarkType(s.type))
+    .map(s => s.label ?? s.key)
+    .join(', ');
+}