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

package/src/Chart/ChartStreamGL.tsx

@@ -0,0 +1,189 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file ChartStreamGL.tsx
+ * @output WebGL streaming time-series line — ring buffer, canvas outside SVG
+ * @position Child of Chart; uses the chart's xScale/yScale for mapping
+ *
+ * Y-axis and x-axis domains are controlled by Chart.
+ * For streaming, the parent should update xDomain as new data arrives.
+ */
+
+import {useRef, useEffect, useImperativeHandle, useCallback} from 'react';
+import type {Ref} from 'react';
+import {mergeRefs} from '@astryxdesign/core/utils';
+import {useChart} from './ChartContext';
+import {
+  hexToGL,
+  getWebGLContext,
+  setupGLState,
+  sizeCanvas,
+  mountCanvasOverSVG,
+  createProgram,
+} from './webgl';
+
+export interface ChartStreamGLProps {
+  /** Ref forwarded to the SVG marker element used to position the canvas. */
+  ref?: Ref<SVGGElement>;
+  /** Imperative handle ref for streaming data control. */
+  handleRef?: Ref<ChartStreamGLHandle>;
+  color: string;
+  bufferSize?: number;
+  lineWidth?: number;
+  opacity?: number;
+}
+
+export interface ChartStreamGLHandle {
+  push(x: number, y: number): void;
+  clear(): void;
+}
+
+const VERT = `
+  attribute vec2 a_position;
+  uniform vec2 u_resolution;
+  void main() {
+    vec2 clip = (a_position / u_resolution) * 2.0 - 1.0;
+    gl_Position = vec4(clip.x, -clip.y, 0.0, 1.0);
+  }
+`;
+
+const FRAG = `
+  precision mediump float;
+  uniform vec3 u_color;
+  uniform float u_opacity;
+  void main() {
+    float a = u_opacity;
+    gl_FragColor = vec4(u_color * a, a);
+  }
+`;
+
+export function ChartStreamGL({
+  ref,
+  handleRef,
+  color,
+  bufferSize = 500,
+  lineWidth = 2,
+  opacity = 1,
+}: ChartStreamGLProps) {
+  const {width, height, xScale, yScale} = useChart();
+  const canvasRef = useRef<HTMLCanvasElement | null>(null);
+  const glRef = useRef<WebGLRenderingContext | null>(null);
+  const programRef = useRef<WebGLProgram | null>(null);
+  const bufRef = useRef<WebGLBuffer | null>(null);
+  const markerRef = useRef<SVGGElement>(null);
+
+  const ring = useRef({
+    data: new Float32Array(bufferSize * 2),
+    head: 0,
+    count: 0,
+  });
+
+  // Mount canvas outside SVG
+  useEffect(() => {
+    const marker = markerRef.current;
+    if (!marker) {
+      return;
+    }
+    if (!canvasRef.current) {
+      canvasRef.current = document.createElement('canvas');
+    }
+    return mountCanvasOverSVG(marker, canvasRef.current, width, height);
+  }, [width, height]);
+
+  // Size canvas
+  useEffect(() => {
+    const canvas = canvasRef.current;
+    if (!canvas || width <= 0 || height <= 0) {
+      return;
+    }
+    sizeCanvas(canvas, width, height);
+  }, [width, height]);
+
+  const draw = useCallback(() => {
+    const canvas = canvasRef.current;
+    if (!canvas) {
+      return;
+    }
+    if (!glRef.current) {
+      glRef.current = getWebGLContext(canvas);
+    }
+    const gl = glRef.current;
+    if (!gl) {
+      return;
+    }
+
+    if (!programRef.current) {
+      programRef.current = createProgram(gl, VERT, FRAG);
+    }
+    const program = programRef.current;
+    if (!program) {
+      return;
+    }
+
+    if (!bufRef.current) {
+      bufRef.current = gl.createBuffer();
+    }
+
+    const {data: ringData, head, count} = ring.current;
+    if (count < 2) {
+      return;
+    }
+
+    const linearX = xScale as (v: number) => number;
+    const drawBuf = new Float32Array(count * 2);
+    for (let i = 0; i < count; i++) {
+      const idx = ((head - count + i + bufferSize) % bufferSize) * 2;
+      drawBuf[i * 2] = linearX(ringData[idx]);
+      drawBuf[i * 2 + 1] = yScale(ringData[idx + 1]);
+    }
+
+    gl.viewport(0, 0, canvas.width, canvas.height);
+    setupGLState(gl);
+    gl.useProgram(program);
+
+    gl.bindBuffer(gl.ARRAY_BUFFER, bufRef.current);
+    gl.bufferData(gl.ARRAY_BUFFER, drawBuf, gl.DYNAMIC_DRAW);
+
+    const aPos = gl.getAttribLocation(program, 'a_position');
+    gl.enableVertexAttribArray(aPos);
+    gl.vertexAttribPointer(aPos, 2, gl.FLOAT, false, 0, 0);
+
+    const [r, g, b] = hexToGL(color);
+    gl.uniform2f(gl.getUniformLocation(program, 'u_resolution'), width, height);
+    gl.uniform3f(gl.getUniformLocation(program, 'u_color'), r, g, b);
+    gl.uniform1f(gl.getUniformLocation(program, 'u_opacity'), opacity);
+
+    gl.lineWidth(lineWidth);
+    gl.drawArrays(gl.LINE_STRIP, 0, count);
+  }, [width, height, color, lineWidth, opacity, bufferSize, xScale, yScale]);
+
+  useImperativeHandle(
+    handleRef,
+    () => ({
+      push(x: number, y: number) {
+        const r = ring.current;
+        const idx = r.head * 2;
+        r.data[idx] = x;
+        r.data[idx + 1] = y;
+        r.head = (r.head + 1) % bufferSize;
+        r.count = Math.min(r.count + 1, bufferSize);
+        draw();
+      },
+      clear() {
+        ring.current.head = 0;
+        ring.current.count = 0;
+        const gl = glRef.current;
+        if (gl) {
+          gl.clearColor(0, 0, 0, 0);
+          gl.clear(gl.COLOR_BUFFER_BIT);
+        }
+      },
+    }),
+    [bufferSize, draw],
+  );
+
+  if (width <= 0 || height <= 0) {
+    return null;
+  }
+  return <g ref={mergeRefs(markerRef, ref)} />;
+}

package/src/Chart/ChartTooltip.tsx

@@ -0,0 +1,451 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file ChartTooltip.tsx
+ * @output Hover tooltip with optional crosshair lines, rendered in the top layer
+ * @position Child of Chart; reads scales from context
+ *
+ * Combines tooltip content and crosshair display into one component.
+ * Uses the Astryx Layer system (Popover API) so the tooltip renders above
+ * all other content — portaled to the chart container div (outside SVG).
+ */
+
+'use client';
+
+import {useState, useCallback, useRef, type ReactNode} from 'react';
+import {createPortal} from 'react-dom';
+import {useLayer} from '@astryxdesign/core/Layer';
+import {useChart} from './ChartContext';
+import {xPixel} from './utils';
+import type {DataPoint} from './types';
+
+/**
+ * Crosshair mode:
+ * - `'x'` — vertical line only (most common for time series)
+ * - `'y'` — horizontal line only
+ * - `'xy'` — both axes
+ * - `false` — no crosshair lines
+ */
+export type ChartCrosshairMode = 'x' | 'y' | 'xy' | false;
+
+export interface ChartTooltipProps {
+  /**
+   * Custom render function for tooltip content.
+   * Receives the nearest data point and its index.
+   * Return `null` to hide the tooltip card while keeping crosshair visible.
+   *
+   * @default Renders all keys as "key: value" lines
+   */
+  render?: (datum: Record<string, unknown>, index: number) => ReactNode;
+
+  /**
+   * Crosshair line display mode.
+   * - `'x'` — vertical crosshair line (default)
+   * - `'y'` — horizontal crosshair line
+   * - `'xy'` — both axes
+   * - `false` — no crosshair lines, tooltip only
+   *
+   * @default 'x'
+   */
+  crosshair?: ChartCrosshairMode;
+
+  /**
+   * Whether to show axis value labels on the crosshair lines.
+   * Only relevant when `crosshair` is not `false`.
+   *
+   * @default false
+   */
+  crosshairLabels?: boolean;
+
+  /**
+   * Whether to snap to the nearest data point (true) or follow
+   * the pointer freely (false). Snap mode finds the closest datum
+   * by x-distance and positions the tooltip at that point.
+   *
+   * @default true
+   */
+  snap?: boolean;
+
+  /**
+   * Format function for x-axis crosshair label.
+   */
+  xFormat?: (value: number | string | null) => string;
+
+  /**
+   * Format function for y-axis crosshair label.
+   */
+  yFormat?: (value: number) => string;
+
+  /**
+   * Color for crosshair lines.
+   * @default 'var(--color-border-emphasized)'
+   */
+  crosshairColor?: string;
+
+  /**
+   * Whether to show a dot indicator at the snapped data point.
+   * @default true
+   */
+  dot?: boolean;
+}
+
+/**
+ * Chart tooltip with integrated crosshair.
+ *
+ * Renders crosshair lines within the SVG and a floating tooltip card
+ * in the top layer (via Popover API, portaled outside the SVG).
+ *
+ * @example
+ * ```tsx
+ * // Default: vertical crosshair + tooltip card
+ * <ChartTooltip />
+ *
+ * // Both axes, with labels
+ * <ChartTooltip crosshair="xy" crosshairLabels />
+ *
+ * // Tooltip only, no crosshair lines
+ * <ChartTooltip crosshair={false} />
+ *
+ * // Custom render
+ * <ChartTooltip render={(d) => <span>{d.month}: ${d.revenue}</span>} />
+ * ```
+ */
+export function ChartTooltip({
+  render,
+  crosshair = 'x',
+  crosshairLabels = false,
+  snap = true,
+  xFormat,
+  yFormat,
+  crosshairColor = 'var(--color-border-emphasized)',
+  dot = true,
+}: ChartTooltipProps) {
+  const {data, xKey, xScale, yScale, width, height, svgRef, pointerToData} =
+    useChart();
+
+  const [hoverState, setHoverState] = useState<{
+    index: number;
+    point: DataPoint;
+  } | null>(null);
+
+  // Screen-space coords for the tooltip popover
+  const [tooltipCoords, setTooltipCoords] = useState({x: 0, y: 0});
+  const layerContainerRef = useRef<HTMLElement | null>(null);
+  const active = useRef(false);
+
+  const layer = useLayer({mode: 'fixed'});
+
+  // Find nearest data point. Uses Euclidean distance for scatter (linear x)
+  // and x-only distance for categorical/time series (band x).
+  const findNearest = useCallback(
+    (px: number, py: number): {index: number; point: DataPoint} | null => {
+      if (data.length === 0) {
+        return null;
+      }
+
+      let closestIdx = 0;
+      let minDist = Infinity;
+
+      // Determine y keys (all numeric keys that aren't xKey)
+      const yKeys =
+        data.length > 0
+          ? Object.keys(data[0]).filter(
+              k => k !== xKey && typeof data[0][k] === 'number',
+            )
+          : [];
+
+      for (let i = 0; i < data.length; i++) {
+        const datum = data[i];
+        const datumPx = xPixel(datum, xKey, xScale);
+        const dx = datumPx - px;
+
+        // For each y key, compute distance to that point
+        let bestDistForDatum = Infinity;
+        let _bestYKey = yKeys[0];
+
+        for (const yk of yKeys) {
+          const yv = datum[yk];
+          if (typeof yv !== 'number') {
+            continue;
+          }
+          const datumPy = yScale(yv);
+          const dy = datumPy - py;
+          const dist = dx * dx + dy * dy; // squared euclidean
+          if (dist < bestDistForDatum) {
+            bestDistForDatum = dist;
+            _bestYKey = yk;
+          }
+        }
+
+        if (bestDistForDatum < minDist) {
+          minDist = bestDistForDatum;
+          closestIdx = i;
+        }
+      }
+
+      const datum = data[closestIdx];
+      const dpx = xPixel(datum, xKey, xScale);
+
+      // Use the y value of the closest key for this datum
+      let bestY = 0;
+      let bestPy = height / 2;
+      let bestDist = Infinity;
+      for (const yk of yKeys) {
+        const yv = datum[yk];
+        if (typeof yv !== 'number') {
+          continue;
+        }
+        const dpy = yScale(yv);
+        const dx = dpx - px;
+        const dy = dpy - py;
+        const dist = dx * dx + dy * dy;
+        if (dist < bestDist) {
+          bestDist = dist;
+          bestY = yv;
+          bestPy = dpy;
+        }
+      }
+
+      return {
+        index: closestIdx,
+        point: {
+          x: datum[xKey] as number | string | null,
+          y: bestY,
+          px: dpx,
+          py: bestPy,
+        },
+      };
+    },
+    [data, xKey, xScale, yScale, height],
+  );
+
+  const updateTooltip = useCallback(
+    (e: React.PointerEvent<SVGRectElement>) => {
+      const dataPoint = pointerToData(e);
+
+      const result = snap
+        ? findNearest(dataPoint.px, dataPoint.py)
+        : {index: -1, point: dataPoint};
+
+      if (result) {
+        setHoverState(result);
+        setTooltipCoords({x: e.clientX + 12, y: e.clientY - 8});
+        layer.show();
+      }
+
+      // Resolve portal container on first interaction
+      if (!layerContainerRef.current && svgRef.current) {
+        layerContainerRef.current = svgRef.current.parentElement;
+      }
+    },
+    [pointerToData, findNearest, snap, layer, svgRef],
+  );
+
+  // Touch: tap to show, drag to scrub
+  const handlePointerDown = useCallback(
+    (e: React.PointerEvent<SVGRectElement>) => {
+      if (e.pointerType !== 'mouse') {
+        e.preventDefault(); // blocks text selection on touch
+        active.current = true;
+        updateTooltip(e);
+      }
+    },
+    [updateTooltip],
+  );
+
+  // Mouse: hover to show. Touch: drag to scrub (only if active).
+  const handlePointerMove = useCallback(
+    (e: React.PointerEvent<SVGRectElement>) => {
+      if (e.pointerType !== 'mouse' && !active.current) {
+        return;
+      }
+      updateTooltip(e);
+    },
+    [updateTooltip],
+  );
+
+  // Touch: lift to dismiss
+  const handlePointerUp = useCallback(() => {
+    if (active.current) {
+      active.current = false;
+      setHoverState(null);
+      layer.hide();
+    }
+  }, [layer]);
+
+  const handlePointerLeave = useCallback(() => {
+    if (!active.current) {
+      setHoverState(null);
+      layer.hide();
+    }
+  }, [layer]);
+
+  const fmtX =
+    xFormat ??
+    ((v: number | string | null) =>
+      v != null ? (typeof v === 'number' ? v.toFixed(1) : String(v)) : '');
+  const fmtY = yFormat ?? ((v: number) => v.toFixed(1));
+
+  const datum = hoverState ? data[hoverState.index] : null;
+  const point = hoverState?.point ?? null;
+
+  const defaultRender = (d: Record<string, unknown>) => (
+    <div
+      style={{display: 'flex', flexDirection: 'column', gap: 2, fontSize: 12}}>
+      {Object.entries(d).map(([k, v]) => (
+        <div key={k}>
+          <span style={{color: 'var(--color-text-secondary)'}}>{k}:</span>{' '}
+          <span style={{fontWeight: 500}}>{String(v)}</span>
+        </div>
+      ))}
+    </div>
+  );
+
+  const showX = crosshair === 'x' || crosshair === 'xy';
+  const showY = crosshair === 'y' || crosshair === 'xy';
+
+  // Portal target: the chart's container div (parent of the SVG)
+  const portalTarget =
+    layerContainerRef.current ?? svgRef.current?.parentElement;
+
+  return (
+    <>
+      <g>
+        {/* Event capture rect — pointer events only, no capture/selection */}
+        <rect
+          x={0}
+          y={0}
+          width={width}
+          height={height}
+          fill="transparent"
+          style={{touchAction: 'none'}}
+          onPointerDown={handlePointerDown}
+          onPointerMove={handlePointerMove}
+          onPointerUp={handlePointerUp}
+          onPointerCancel={handlePointerUp}
+          onPointerLeave={handlePointerLeave}
+        />
+
+        {point && (
+          <>
+            {/* Vertical crosshair line */}
+            {showX && (
+              <line
+                x1={point.px}
+                x2={point.px}
+                y1={0}
+                y2={height}
+                stroke={crosshairColor}
+                strokeWidth={1}
+                strokeDasharray="3 3"
+                pointerEvents="none"
+              />
+            )}
+
+            {/* Horizontal crosshair line */}
+            {showY && (
+              <line
+                x1={0}
+                x2={width}
+                y1={point.py}
+                y2={point.py}
+                stroke={crosshairColor}
+                strokeWidth={1}
+                strokeDasharray="3 3"
+                pointerEvents="none"
+              />
+            )}
+
+            {/* Data point indicator dot */}
+            {dot && snap && hoverState && hoverState.index >= 0 && (
+              <circle
+                cx={point.px}
+                cy={point.py}
+                r={4}
+                fill="var(--color-background-surface)"
+                stroke={crosshairColor}
+                strokeWidth={2}
+                pointerEvents="none"
+              />
+            )}
+
+            {/* X-axis label */}
+            {crosshairLabels && showX && point.x != null && (
+              <g
+                transform={`translate(${point.px},${height})`}
+                pointerEvents="none">
+                <rect
+                  x={-24}
+                  y={2}
+                  width={48}
+                  height={16}
+                  rx={4}
+                  fill="var(--color-background-popover)"
+                  stroke={crosshairColor}
+                  strokeWidth={0.5}
+                />
+                <text
+                  y={14}
+                  textAnchor="middle"
+                  fontSize={10}
+                  fill="var(--color-text-primary)">
+                  {fmtX(point.x)}
+                </text>
+              </g>
+            )}
+
+            {/* Y-axis label */}
+            {crosshairLabels && showY && (
+              <g transform={`translate(0,${point.py})`} pointerEvents="none">
+                <rect
+                  x={-48}
+                  y={-8}
+                  width={44}
+                  height={16}
+                  rx={4}
+                  fill="var(--color-background-popover)"
+                  stroke={crosshairColor}
+                  strokeWidth={0.5}
+                />
+                <text
+                  x={-26}
+                  dy="0.35em"
+                  textAnchor="middle"
+                  fontSize={10}
+                  fill="var(--color-text-primary)">
+                  {fmtY(point.y)}
+                </text>
+              </g>
+            )}
+          </>
+        )}
+      </g>
+
+      {/* Tooltip card — portaled outside SVG into chart container div */}
+      {portalTarget &&
+        createPortal(
+          layer.render(
+            datum && hoverState && hoverState.index >= 0 ? (
+              <div
+                style={{
+                  background: 'var(--color-background-popover)',
+                  border: '1px solid var(--color-border)',
+                  borderRadius: 8,
+                  padding: '8px 12px',
+                  boxShadow: 'var(--shadow-med)',
+                  whiteSpace: 'nowrap',
+                  width: 'fit-content',
+                  pointerEvents: 'none',
+                }}>
+                {render
+                  ? render(datum, hoverState.index)
+                  : defaultRender(datum)}
+              </div>
+            ) : null,
+            {x: tooltipCoords.x, y: tooltipCoords.y},
+          ),
+          portalTarget,
+        )}
+    </>
+  );
+}