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

package/src/ChartV2/Chart.tsx

@@ -0,0 +1,348 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Chart.tsx (v2)
+ * @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
+ */
+
+import {
+  type ReactNode,
+  useId,
+  useMemo,
+  useRef,
+  useState,
+  useCallback,
+  useLayoutEffect,
+} from 'react';
+import type {SeriesDef} from './types';
+import type {ChartV2Context, ChartMargin, ChartPointerEvent} from './types';
+import {computeLayout} from './layout';
+import {ChartV2Provider} from './ChartV2Context';
+import {ChartProvider} from '../Chart/ChartContext';
+import {Text} from '@astryxdesign/core';
+import {VStack, HStack} from '@astryxdesign/core';
+import * as stylex from '@stylexjs/stylex';
+import {ChartLegend, type ChartLegendProps} from './ChartLegend';
+import {deriveLegendItems} from './legend';
+import {ChartTooltip, type ChartTooltipProps} from './ChartTooltip';
+
+export interface ChartProps {
+  data: Record<string, unknown>[];
+  xKey: string;
+  series: SeriesDef[];
+  height?: number;
+  margin?: Partial<ChartMargin>;
+  grid?: ReactNode;
+  axes?: ReactNode;
+  legend?: boolean | ChartLegendProps;
+  tooltip?: boolean | Omit<ChartTooltipProps, 'series'>;
+  interactions?: ReactNode;
+  children?: ReactNode;
+  title?: string;
+  subtitle?: string;
+}
+
+const DEFAULT_MARGIN: ChartMargin = {top: 24, right: 24, bottom: 32, left: 48};
+
+const styles = stylex.create({
+  container: {
+    width: '100%',
+  },
+  title: {
+    marginBottom: 16,
+  },
+  chartArea: {
+    flex: 1,
+    minWidth: 0,
+    overflow: 'hidden',
+  },
+});
+
+export function Chart({
+  data,
+  xKey,
+  series,
+  height = 300,
+  margin: marginOverride,
+  grid,
+  axes,
+  legend,
+  tooltip,
+  interactions,
+  children,
+  title,
+  subtitle,
+}: ChartProps) {
+  const chartId = useId();
+  const descId = `${chartId}-desc`;
+  const containerRef = useRef<HTMLDivElement>(null);
+  const svgRef = useRef<SVGSVGElement>(null);
+  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],
+  );
+  const innerWidth = Math.max(0, containerWidth - margin.left - margin.right);
+  const innerHeight = Math.max(0, height - margin.top - margin.bottom);
+
+  // ─── Layout pass ──────────────────────────────────────────────────────
+  const layout = useMemo(
+    () =>
+      computeLayout({
+        data,
+        xKey,
+        series,
+        width: innerWidth,
+        height: innerHeight,
+      }),
+    [data, xKey, series, innerWidth, innerHeight],
+  );
+
+  const seriesCtx = useMemo(
+    () => ({
+      data,
+      xKey,
+      xScale: layout.xScale,
+      yScale: layout.yScale,
+      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: ChartV2Context = useMemo(
+    () => ({
+      width: innerWidth,
+      height: innerHeight,
+      margin,
+      data,
+      xKey,
+      xScale: layout.xScale,
+      yScale: layout.yScale,
+      resolved: layout.resolved,
+      onPointer,
+      svgRef,
+    }),
+    [innerWidth, innerHeight, margin, data, xKey, layout, onPointer],
+  );
+
+  // Bridge v1 context for ChartGrid/Axis compatibility
+  const v1Ctx = useMemo(
+    () => ({
+      width: innerWidth,
+      height: innerHeight,
+      margin,
+      xKey,
+      data,
+      xScale: layout.xScale,
+      yScale: layout.yScale,
+      svgRef,
+      pointerToData: () => ({
+        x: null as string | number | null,
+        y: 0,
+        px: 0,
+        py: 0,
+      }),
+      pixelToData: (px: number, py: number) => ({
+        x: null as string | number | null,
+        y: 0,
+        px,
+        py,
+      }),
+    }),
+    [innerWidth, innerHeight, margin, xKey, data, layout, svgRef],
+  );
+
+  // ─── 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={containerRef}
+        {...stylex.props(styles.container)}
+        style={{height}}
+      />
+    );
+  }
+
+  return (
+    <div ref={containerRef} {...stylex.props(styles.container)}>
+      {(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>
+      )}
+      <ChartV2Provider value={ctx}>
+        <ChartProvider value={v1Ctx}>
+          {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>
+      </ChartV2Provider>
+    </div>
+  );
+
+  function renderSvg() {
+    return (
+      <svg
+        ref={svgRef}
+        width="100%"
+        height={height}
+        aria-label={title ?? undefined}
+        aria-describedby={subtitle ? descId : undefined}>
+        {title && <title>{title}</title>}
+        {subtitle && <desc id={descId}>{subtitle}</desc>}
+        <g transform={`translate(${margin.left},${margin.top})`}>
+          {/* 1. Grid */}
+          {grid}
+
+          {/* 2. Marks — each series renders itself */}
+          {series.map(s => {
+            const resolved = layout.resolved.get(s.key);
+            if (!resolved) {
+              return null;
+            }
+            return <g key={s.key}>{s.render(resolved, seriesCtx)}</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>
+    );
+  }
+}

package/src/ChartV2/ChartAxis.tsx

@@ -0,0 +1,209 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file ChartAxis.tsx (v2)
+ * @output Renders an axis (top, right, bottom, left) using the chart's scales
+ * @position Child of Chart v2; reads scales from chart context
+ *
+ * The axis edge line and tick marks are independently toggleable so callers
+ * can compose: line-only, line + ticks, or line + ticks + grid (paired with
+ * `<ChartGrid>`). To stay consistent with most charts, the bottom axis
+ * draws its edge line by default and other positions don't.
+ *
+ * Ticks use CSS transitions for smooth sliding during streaming updates.
+ */
+
+import {useMemo} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {colorVars} from '@astryxdesign/core/theme/tokens.stylex';
+import {useChart} from '../Chart/ChartContext';
+import {isBandScale} from '../Chart/utils';
+import type {ScaleLinear, ScaleTime} from 'd3-scale';
+
+export interface ChartAxisProps {
+  /** Which edge to render the axis on */
+  position: 'top' | 'right' | 'bottom' | 'left';
+  /** Number of ticks (approximate — d3 decides final count) */
+  tickCount?: number;
+  /** Maximum number of tick labels to show. Labels are evenly skipped when exceeded. */
+  maxTicks?: number;
+  /** Custom tick formatter */
+  tickFormat?: (value: unknown) => string;
+  /** Truncate labels to this many characters (appends "\u2026"). */
+  truncate?: number;
+  /** Enable smooth transitions for streaming (default: true) */
+  animated?: boolean;
+  /**
+   * Show the axis edge line. Defaults to `true` for `position="bottom"`,
+   * `false` otherwise. Forced to `true` when `showTicks` is enabled.
+   * Pair with `<ChartGrid vertical />` and pass `showAxisLine` on the
+   * corresponding side axis to keep the visual edge grounded.
+   */
+  showAxisLine?: boolean;
+  /** Show perpendicular tick marks at each tick label. Default: `false`. */
+  showTicks?: boolean;
+}
+
+const styles = stylex.create({
+  axisLine: {
+    stroke: colorVars['--color-text-primary'],
+    strokeWidth: 1,
+  },
+  tickMark: {
+    stroke: colorVars['--color-text-primary'],
+    strokeWidth: 1,
+  },
+});
+
+const TICK_SIZE = 6;
+
+/**
+ * Chart axis. Always draws tick labels; the axis edge line and tick marks
+ * are independently toggleable. Pair with `<ChartGrid>` for grid lines.
+ *
+ * @example
+ * ```
+ * <ChartAxis position="bottom" />               // edge line + labels
+ * <ChartAxis position="left" />                 // labels only (no edge line)
+ * <ChartAxis position="left" showAxisLine showTicks />
+ * ```
+ */
+export function ChartAxis({
+  position,
+  tickCount = 5,
+  maxTicks,
+  tickFormat,
+  truncate,
+  animated = true,
+  showAxisLine = position === 'bottom',
+  showTicks = false,
+}: ChartAxisProps) {
+  // Tick marks need an axis line to anchor against; force it on when ticks
+  // are enabled so the two visuals stay coherent.
+  const renderAxisLine = showAxisLine || showTicks;
+  const {width, height, xScale, yScale} = useChart();
+
+  const isHorizontal = position === 'top' || position === 'bottom';
+  const scale = isHorizontal ? xScale : yScale;
+
+  const ticks = useMemo(() => {
+    let allTicks: {value: unknown; offset: number}[];
+    if (isBandScale(scale)) {
+      allTicks = scale.domain().map(d => ({
+        value: d,
+        offset: (scale(d) ?? 0) + scale.bandwidth() / 2,
+      }));
+    } else {
+      const linearScale = scale as
+        | ScaleLinear<number, number>
+        | ScaleTime<number, number>;
+      allTicks = linearScale.ticks(tickCount).map(d => ({
+        value: d,
+        offset: linearScale(d as number & Date),
+      }));
+    }
+
+    // Auto-skip: show every Nth label if maxTicks is exceeded
+    if (maxTicks && allTicks.length > maxTicks) {
+      const step = Math.ceil(allTicks.length / maxTicks);
+      allTicks = allTicks.filter((_, i) => i % step === 0);
+    }
+
+    return allTicks;
+  }, [scale, tickCount, maxTicks]);
+
+  const transform =
+    position === 'bottom'
+      ? `translate(0,${height})`
+      : position === 'right'
+        ? `translate(${width},0)`
+        : undefined;
+
+  // For the bottom axis, draw the axis line at y=0 when the domain spans
+  // negative values (so the axis line still represents zero, not the chart edge).
+  const axisLineY = (() => {
+    if (position !== 'bottom') {
+      return 0;
+    }
+    const domain = yScale.domain();
+    if (domain[0] < 0 && domain[1] > 0) {
+      return yScale(0) - height;
+    }
+    return 0;
+  })();
+
+  const baseFormat = tickFormat ?? String;
+  const format = truncate
+    ? (value: unknown) => {
+        const str = baseFormat(value);
+        return str.length > truncate ? str.slice(0, truncate) + '\u2026' : str;
+      }
+    : baseFormat;
+
+  const tickTransition = animated
+    ? 'transform 150ms linear, opacity 150ms ease'
+    : undefined;
+
+  return (
+    <g transform={transform}>
+      {renderAxisLine && (
+        <line
+          x1={0}
+          x2={isHorizontal ? width : 0}
+          y1={isHorizontal ? axisLineY : 0}
+          y2={isHorizontal ? axisLineY : height}
+          {...stylex.props(styles.axisLine)}
+        />
+      )}
+      {ticks.map(({value, offset}) => {
+        const label = format(value);
+        const isVisible = isHorizontal
+          ? offset >= -10 && offset <= width + 10
+          : offset >= -10 && offset <= height + 10;
+
+        if (isHorizontal) {
+          const y = position === 'bottom' ? TICK_SIZE : -TICK_SIZE;
+          return (
+            <g
+              key={label}
+              style={{
+                transform: `translateX(${offset}px)`,
+                transition: tickTransition,
+                opacity: isVisible ? 1 : 0,
+              }}>
+              {showTicks && <line y2={y} {...stylex.props(styles.tickMark)} />}
+              <text
+                y={position === 'bottom' ? TICK_SIZE + 12 : -(TICK_SIZE + 4)}
+                textAnchor="middle"
+                fill="var(--color-text-secondary)"
+                fontSize={12}>
+                {label}
+              </text>
+            </g>
+          );
+        }
+        // Vertical axis
+        const x = position === 'left' ? -TICK_SIZE : TICK_SIZE;
+        return (
+          <g
+            key={label}
+            style={{
+              transform: `translateY(${offset}px)`,
+              transition: tickTransition,
+              opacity: isVisible ? 1 : 0,
+            }}>
+            {showTicks && <line x2={x} {...stylex.props(styles.tickMark)} />}
+            <text
+              x={position === 'left' ? -(TICK_SIZE + 4) : TICK_SIZE + 4}
+              dy="0.32em"
+              textAnchor={position === 'left' ? 'end' : 'start'}
+              fill="var(--color-text-secondary)"
+              fontSize={12}>
+              {label}
+            </text>
+          </g>
+        );
+      })}
+    </g>
+  );
+}

package/src/ChartV2/ChartGrid.tsx

@@ -0,0 +1,99 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file ChartGrid.tsx (v2)
+ * @output Grid lines behind chart marks
+ * @position Child of Chart v2; reads scales from chart context
+ */
+
+import {useMemo} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {colorVars} from '@astryxdesign/core/theme/tokens.stylex';
+import {useChart} from '../Chart/ChartContext';
+import {isBandScale} from '../Chart/utils';
+import type {ScaleLinear, ScaleTime} from 'd3-scale';
+
+export interface ChartGridProps {
+  /** Show horizontal grid lines. Default: `true`. */
+  horizontal?: boolean;
+  /** Show vertical grid lines. Default: `false`. */
+  vertical?: boolean;
+}
+
+const styles = stylex.create({
+  gridLine: {
+    stroke: colorVars['--color-border-emphasized'],
+    strokeWidth: 1,
+  },
+});
+
+/**
+ * Grid lines behind chart marks.
+ *
+ * Pair with `<ChartAxis>` so users always see an axis line beside the
+ * grid — the components are designed to be used together.
+ *
+ * @example
+ * ```
+ * <ChartGrid />                 // horizontal grid lines (default)
+ * <ChartGrid horizontal vertical />
+ * ```
+ */
+export function ChartGrid({
+  horizontal = true,
+  vertical = false,
+}: ChartGridProps) {
+  const {width, height, xScale, yScale} = useChart();
+
+  // Skip the y=0 line when emphasizing it via the axis. Without this we'd
+  // double-draw on top of the axis line.
+  const hLines = useMemo(() => {
+    if (!horizontal) {
+      return [];
+    }
+    return yScale
+      .ticks(5)
+      .filter(tick => tick !== 0)
+      .map(tick => yScale(tick));
+  }, [horizontal, yScale]);
+
+  const vLines = useMemo(() => {
+    if (!vertical) {
+      return [];
+    }
+    if (isBandScale(xScale)) {
+      return xScale
+        .domain()
+        .map(d => (xScale(d) ?? 0) + xScale.bandwidth() / 2);
+    }
+    const linear = xScale as
+      | ScaleLinear<number, number>
+      | ScaleTime<number, number>;
+    return linear.ticks(5).map(d => linear(d as number & Date));
+  }, [vertical, xScale]);
+
+  return (
+    <g>
+      {hLines.map(y => (
+        <line
+          key={`h-${y}`}
+          x1={0}
+          x2={width}
+          y1={y}
+          y2={y}
+          {...stylex.props(styles.gridLine)}
+        />
+      ))}
+      {vLines.map(x => (
+        <line
+          key={`v-${x}`}
+          x1={x}
+          x2={x}
+          y1={0}
+          y2={height}
+          {...stylex.props(styles.gridLine)}
+        />
+      ))}
+    </g>
+  );
+}