@astryxdesign/lab 0.1.4-canary.37c19d3 → 0.1.4-canary.39ffd21

package/src/ChartV2/ChartTooltip.tsx

@@ -0,0 +1,382 @@
+// 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 ChartV2Context — must render inside an <Chart>.
+ *
+ * @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 '@astryxdesign/core/theme/tokens.stylex';
+import {Text} from '@astryxdesign/core';
+import {VStack, HStack} from '@astryxdesign/core';
+import {useChartV2} from './ChartV2Context';
+import {ChartSwatch, swatchVariantForType} from './ChartSwatch';
+import {
+  deriveTooltipSeriesValues,
+  shouldRenderHoverDot,
+  type TooltipSeriesValue,
+} from './tooltip';
+import type {SeriesDef, ChartPointerEvent} from './types';
+import type {ScaleBand} from 'd3-scale';
+
+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 => (
+            <HStack key={row.key} 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,
+  } = useChartV2();
+  const [hoveredIndex, setHoveredIndex] = useState<number | null>(null);
+  const cardRef = useRef<HTMLDivElement>(null);
+
+  // 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) {
+        card.style.display = 'none';
+        return;
+      }
+      const svgRect = svg.getBoundingClientRect();
+      const screenX = svgRect.left + margin.left + e.nearest.px;
+      const screenY = svgRect.top + margin.top;
+      const cardWidth = card.offsetWidth;
+      const cardHeight = card.offsetHeight;
+      const viewportWidth = window.innerWidth;
+      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;
+        }
+      }
+
+      card.style.left = `${x}px`;
+      card.style.top = `${y}px`;
+      card.style.display = 'block';
+    },
+    [svgRef, margin, placement],
+  );
+
+  // ─── 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;
+        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 = resolved.get(s.key);
+      const point = points?.find(p => p.dataIndex === hoveredIndex);
+      if (!point) {
+        continue;
+      }
+      elements.push(
+        <circle
+          key={s.key}
+          cx={point.px}
+          cy={point.py}
+          r={4}
+          fill="var(--color-background-surface)"
+          stroke={s.color ?? '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 xv = data[hoveredIndex]?.[xKey];
+    if (xv == null) {
+      return null;
+    }
+    const isBandScale = 'bandwidth' in xScale;
+    const hasBars = series.some(s => s.type === 'bar');
+
+    // Bar charts on a band scale → soft column highlight.
+    if (hasBars && isBandScale) {
+      const bandScale = xScale as ScaleBand<string>;
+      const x = bandScale(String(xv)) ?? 0;
+      const bw = bandScale.bandwidth();
+      const pad = 8;
+      const rectX = Math.max(0, x - pad);
+      const rectRight = Math.min(width, x + bw + pad);
+      const rectWidth = rectRight - rectX;
+      const topPad = Math.min(pad, 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.
+    const px = isBandScale
+      ? ((xScale as ScaleBand<string>)(String(xv)) ?? 0) +
+        (xScale as ScaleBand<string>).bandwidth() / 2
+      : (xScale as (v: number) => number)(xv as number);
+    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,
+  ]);
+
+  // ─── Render ────────────────────────────────────────────────────────────
+  if (typeof document === 'undefined') {
+    // SSR: no DOM portal target; band highlight + dots still render in SVG.
+    return (
+      <>
+        {hoverIndicatorElement}
+        {dots}
+      </>
+    );
+  }
+
+  const cardContent =
+    hoveredIndex == null ? null : render ? (
+      render(xValue, seriesValues)
+    ) : (
+      <DefaultTooltipContent xValue={xValue} rows={seriesValues} />
+    );
+
+  return (
+    <>
+      {hoverIndicatorElement}
+      {dots}
+      {createPortal(
+        <div ref={cardRef} {...stylex.props(styles.card)}>
+          {cardContent}
+        </div>,
+        document.body,
+      )}
+    </>
+  );
+}

package/src/ChartV2/ChartV2.doc.mjs

@@ -0,0 +1,16 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../core/src/docs-types').ComponentDoc} */
+
+export const docs = {
+  name: 'ChartV2',
+  displayName: 'Chart V2',
+  group: 'ChartV2',
+  category: 'Data Visualization',
+
+  usage: {
+    description: '',
+  },
+
+  props: [],
+};

package/src/ChartV2/ChartV2Context.ts

@@ -0,0 +1,15 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {createContext, useContext} from 'react';
+import type {ChartV2Context} from './types';
+
+const Ctx = createContext<ChartV2Context | null>(null);
+export const ChartV2Provider = Ctx.Provider;
+
+export function useChartV2(): ChartV2Context {
+  const ctx = useContext(Ctx);
+  if (!ctx) {
+    throw new Error('Must be used inside <Chart>');
+  }
+  return ctx;
+}

package/src/ChartV2/index.ts

@@ -0,0 +1,62 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+export {Chart, type ChartProps} from './Chart';
+export {ChartAxis, type ChartAxisProps} from './ChartAxis';
+export {ChartGrid, type ChartGridProps} from './ChartGrid';
+export {
+  ChartLegend,
+  type ChartLegendProps,
+  type LegendPosition,
+  type LegendAlignment,
+} from './ChartLegend';
+export {type LegendItem} from './legend';
+export {
+  ChartSwatch,
+  swatchVariantForType,
+  type ChartSwatchProps,
+  type ChartSwatchVariant,
+} from './ChartSwatch';
+export {
+  ChartTooltip,
+  type ChartTooltipProps,
+  type ChartTooltipPlacement,
+} from './ChartTooltip';
+export {type TooltipSeriesValue} from './tooltip';
+export {
+  bar,
+  line,
+  dot,
+  area,
+  band,
+  candlestick,
+  errorBar,
+  referenceLine,
+  dotGL,
+  dotGLInteractive,
+  heatmapGL,
+  streamGL,
+} from './marks';
+export type {
+  BarOptions,
+  LineOptions,
+  DotOptions,
+  AreaOptions,
+  BandOptions,
+  CandlestickOptions,
+  ErrorBarOptions,
+  ReferenceLineOptions,
+  DotGLOptions,
+  DotGLInteractiveOptions,
+  HeatmapGLOptions,
+  StreamGLOptions,
+  StreamGLHandle,
+} from './marks';
+export {useChartV2} from './ChartV2Context';
+export type {
+  SeriesDef,
+  ChartV2Context,
+  ChartPointerEvent,
+  ResolvedPoint,
+  ResolvedPositions,
+  SeriesContext,
+} from './types';

package/src/ChartV2/layout.ts

@@ -0,0 +1,223 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file layout.ts
+ * @output Computes scales, stacking, grouping, then delegates to each series.resolve()
+ * @position Called by Chart root — the single layout pass
+ *
+ * The layout engine does NOT know about specific mark types.
+ * It handles cross-series coordination (scales, stacking, grouping)
+ * then calls each series' own resolve() method.
+ */
+
+import {scaleLinear, scaleBand} from 'd3-scale';
+import {stack as d3Stack, stackOrderNone, stackOffsetNone} from 'd3-shape';
+import type {
+  SeriesDef,
+  ChartScale,
+  ResolvedPoint,
+  SeriesContext,
+} from './types';
+
+export interface LayoutInput {
+  data: Record<string, unknown>[];
+  xKey: string;
+  series: SeriesDef[];
+  width: number;
+  height: number;
+}
+
+export interface LayoutResult {
+  xScale: ChartScale;
+  yScale: ReturnType<typeof scaleLinear<number, number>>;
+  resolved: Map<string, ResolvedPoint[]>;
+}
+
+export function computeLayout({
+  data,
+  xKey,
+  series,
+  width,
+  height,
+}: LayoutInput): LayoutResult {
+  // ─── 1. X scale ──────────────────────────────────────────────────────
+  const xValues = data.map(d => d[xKey]);
+  const isNumericX =
+    xValues.length > 0 && xValues.every(v => typeof v === 'number');
+
+  let xScale: ChartScale;
+  if (isNumericX) {
+    const nums = xValues as number[];
+    xScale = scaleLinear()
+      .domain([Math.min(...nums), Math.max(...nums)])
+      .range([0, width])
+      .nice();
+  } else {
+    xScale = scaleBand<string>()
+      .domain(xValues.map(String))
+      .range([0, width])
+      .padding(0.2);
+  }
+
+  // ─── 2. Y domain from all series dataKeys ────────────────────────────
+  const allKeys = new Set<string>();
+  let includeZero = false;
+  for (const s of series) {
+    for (const k of s.dataKeys) {
+      allKeys.add(k);
+    }
+    if (s.layout.includeZero) {
+      includeZero = true;
+    }
+  }
+
+  // Collect which keys are stacked together so we can compute stacked extents
+  const stackGroupKeys = new Map<string, string[]>();
+  for (const s of series) {
+    if (s.layout.stack) {
+      const group = stackGroupKeys.get(s.layout.stack) ?? [];
+      group.push(s.dataKeys[0]);
+      stackGroupKeys.set(s.layout.stack, group);
+    }
+  }
+
+  let yMin = Infinity,
+    yMax = -Infinity;
+
+  // For stacked series, compute the sum at each data point
+  const stackedKeys = new Set<string>();
+  for (const [, keys] of stackGroupKeys) {
+    for (const k of keys) {
+      stackedKeys.add(k);
+    }
+    for (const d of data) {
+      let sum = 0;
+      for (const k of keys) {
+        const v = d[k];
+        if (typeof v === 'number') {
+          sum += v;
+        }
+      }
+      if (sum > yMax) {
+        yMax = sum;
+      }
+      if (sum < yMin) {
+        yMin = sum;
+      }
+    }
+  }
+
+  // For non-stacked series, use individual values
+  for (const d of data) {
+    for (const k of allKeys) {
+      if (stackedKeys.has(k)) {
+        continue;
+      } // already handled above
+      const v = d[k];
+      if (typeof v === 'number') {
+        if (v < yMin) {
+          yMin = v;
+        }
+        if (v > yMax) {
+          yMax = v;
+        }
+      }
+    }
+  }
+
+  if (includeZero) {
+    if (yMin > 0) {
+      yMin = 0;
+    }
+    if (yMax < 0) {
+      yMax = 0;
+    }
+  }
+  const yScale = scaleLinear().domain([yMin, yMax]).range([height, 0]).nice();
+
+  // ─── 3. Stacking ─────────────────────────────────────────────────────
+  const stackGroups = new Map<string, string[]>();
+  for (const s of series) {
+    if (s.layout.stack) {
+      const group = stackGroups.get(s.layout.stack) ?? [];
+      group.push(s.dataKeys[0]);
+      stackGroups.set(s.layout.stack, group);
+    }
+  }
+
+  const stackedData = new Map<string, {y0: number; y1: number}[]>();
+  for (const [, keys] of stackGroups) {
+    const stackGen = d3Stack<Record<string, unknown>>()
+      .keys(keys)
+      .order(stackOrderNone)
+      .offset(stackOffsetNone);
+    const stacked = stackGen(data);
+    for (const layer of stacked) {
+      stackedData.set(
+        layer.key,
+        layer.map(d => ({y0: d[0], y1: d[1]})),
+      );
+    }
+  }
+
+  // ─── 4. Bar grouping ─────────────────────────────────────────────────
+  // Bars can be grouped (side-by-side) whether or not they are stacked.
+  // For grouped stacks, each unique stack group name within the same bar
+  // group gets its own sub-band. For ungrouped non-stacked bars with a
+  // group key, each series gets its own sub-band.
+  const barGroups = new Map<string, string[]>();
+  for (const s of series) {
+    if (s.type === 'bar' && s.layout.group) {
+      const group = barGroups.get(s.layout.group) ?? [];
+      // For grouped stacks: use the stack name as the group slot identifier
+      // so all series in the same stack share one slot.
+      const slotKey = s.layout.stack ?? s.key;
+      if (!group.includes(slotKey)) {
+        group.push(slotKey);
+      }
+      barGroups.set(s.layout.group, group);
+    }
+  }
+
+  // ─── 5. Resolve each series ──────────────────────────────────────────
+  const ctx: SeriesContext = {data, xKey, xScale, yScale, width, height};
+  const resolved = new Map<string, ResolvedPoint[]>();
+
+  // Determine which series is the topmost in each stack group
+  const stackTopKeys = new Set<string>();
+  for (const [, keys] of stackGroups) {
+    // Last key in the stack group is rendered on top
+    if (keys.length > 0) {
+      stackTopKeys.add(keys[keys.length - 1]);
+    }
+  }
+
+  for (const s of series) {
+    const stackOffsets = stackedData.get(s.dataKeys[0]);
+
+    // Mark whether this series is the topmost in its stack
+    if (s.layout.stack) {
+      s._isTopOfStack = stackTopKeys.has(s.dataKeys[0]);
+    } else {
+      s._isTopOfStack = true;
+    }
+
+    let groupInfo: {index: number; count: number} | undefined;
+    if (s.layout.group) {
+      const groupKeys = barGroups.get(s.layout.group);
+      if (groupKeys) {
+        // For grouped stacks, the slot key is the stack name
+        const slotKey = s.layout.stack ?? s.key;
+        groupInfo = {
+          index: groupKeys.indexOf(slotKey),
+          count: groupKeys.length,
+        };
+      }
+    }
+
+    const points = s.resolve(ctx, stackOffsets, groupInfo);
+    resolved.set(s.key, points);
+  }
+
+  return {xScale, yScale, resolved};
+}