@astryxdesign/lab 0.0.0-bootstrap.0 → 0.1.2-canary.04e71b2

package/src/ChartV2/ChartLegend.tsx

@@ -0,0 +1,69 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file ChartLegend.tsx
+ * @output Standalone chart legend component
+ * @position Can be used inside Chart via the `legend` prop, or independently
+ *
+ * @example
+ * // Via Chart
+ * <Chart legend={{position: 'top', alignment: 'start'}} ... />
+ *
+ * // Standalone
+ * <ChartLegend items={[{label: 'Revenue', color: '#3b82f6'}]} />
+ */
+
+import {Text} from '@astryxdesign/core';
+import {VStack, HStack} from '@astryxdesign/core';
+import {ChartSwatch, swatchVariantForType} from './ChartSwatch';
+import type {LegendItem} from './legend';
+
+export type {LegendItem};
+
+export type LegendPosition = 'top' | 'bottom' | 'start' | 'end';
+export type LegendAlignment = 'start' | 'center' | 'end';
+
+export interface ChartLegendProps {
+  /** Legend items to display */
+  items?: LegendItem[];
+  /** Position of the legend relative to the chart. Default: 'bottom' */
+  position?: LegendPosition;
+  /** Alignment of the legend within its position. Default: 'start' */
+  alignment?: LegendAlignment;
+}
+
+export function ChartLegend({
+  items = [],
+  position = 'bottom',
+  alignment = 'start',
+}: ChartLegendProps) {
+  if (items.length === 0) {
+    return null;
+  }
+
+  const isVertical = position === 'start' || position === 'end';
+
+  const legendItems = items.map(item => (
+    <HStack key={item.label} gap={2} vAlign="center">
+      <ChartSwatch
+        color={item.color}
+        variant={swatchVariantForType(item.type)}
+      />
+      <Text type="supporting">{item.label}</Text>
+    </HStack>
+  ));
+
+  if (isVertical) {
+    return (
+      <VStack gap={2} hAlign={alignment}>
+        {legendItems}
+      </VStack>
+    );
+  }
+
+  return (
+    <HStack gap={4} justify={alignment} vAlign="center" wrap="wrap">
+      {legendItems}
+    </HStack>
+  );
+}

package/src/ChartV2/ChartSwatch.doc.mjs

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

package/src/ChartV2/ChartSwatch.tsx

@@ -0,0 +1,86 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file ChartSwatch.tsx
+ * @output Color swatch primitive for legends, tooltips, and standalone use
+ * @position Composable primitive — used by ChartLegend (and future
+ *           ChartTooltip), or independently anywhere a series indicator
+ *           is needed.
+ *
+ * @example
+ * ```
+ * <ChartSwatch color="#3b82f6" variant="square" />
+ * <ChartSwatch color="#f59e0b" variant="line" />
+ * ```
+ */
+
+import {memo} from 'react';
+import * as stylex from '@stylexjs/stylex';
+
+/**
+ * Visual variant — drives shape.
+ * - `'square'` — square chip (bar series)
+ * - `'line'` — short stroke (line, dot, area, and other non-bar series)
+ */
+export type ChartSwatchVariant = 'square' | 'line';
+
+export interface ChartSwatchProps {
+  /** Fill color — typically a series color token */
+  color: string;
+  /** Visual variant. Default: `'square'`. */
+  variant?: ChartSwatchVariant;
+}
+
+const styles = stylex.create({
+  base: {
+    flexShrink: 0,
+  },
+  square: {
+    width: 8,
+    height: 8,
+    borderRadius: 2,
+    marginInline: 1,
+  },
+  line: {
+    width: 10,
+    height: 3,
+    borderRadius: 1.5,
+  },
+});
+
+/**
+ * Color swatch primitive.
+ *
+ * Used by ChartLegend (and ChartTooltip) to render the colored
+ * indicator next to a series label. Exported as a primitive so consumers
+ * can build their own custom legend/tooltip layouts while keeping visuals
+ * consistent.
+ */
+function ChartSwatchImpl({color, variant = 'square'}: ChartSwatchProps) {
+  return (
+    <div
+      aria-hidden
+      {...stylex.props(styles.base, styles[variant])}
+      style={{backgroundColor: color}}
+    />
+  );
+}
+
+/**
+ * Memoized — swatches are static for a given (color, variant) tuple
+ * and can render many times in a tooltip/legend with several series.
+ */
+export const ChartSwatch = memo(ChartSwatchImpl);
+
+/**
+ * Map a SeriesDef.type string to its swatch variant.
+ *
+ * Bar series get a square chip; everything else (line, dot, area, and any
+ * other non-bar mark) gets a short stroke. Centralized so legend, tooltip,
+ * and any custom chrome stay consistent.
+ */
+export function swatchVariantForType(
+  type: string | undefined,
+): ChartSwatchVariant {
+  return type === 'bar' ? 'square' : 'line';
+}

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';