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

package/src/Chart/useChartRange.test.ts

@@ -0,0 +1,101 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect} from 'vitest';
+import {renderHook, act} from '@testing-library/react';
+import {useChartRange} from './useChartRange';
+
+describe('useChartRange', () => {
+  it('initializes with zero domain', () => {
+    const {result} = renderHook(() => useChartRange({xWindow: 300}));
+    expect(result.current.xDomain).toEqual([0, 0]);
+    expect(result.current.yDomain).toEqual([0, 1]);
+  });
+
+  it('uses fixed yDomain when provided', () => {
+    const {result} = renderHook(() =>
+      useChartRange({xWindow: 300, yDomain: [0, 100]}),
+    );
+    expect(result.current.yDomain).toEqual([0, 100]);
+  });
+
+  it('grows xDomain during warmup then slides', () => {
+    const {result} = renderHook(() => useChartRange({xWindow: 100}));
+
+    // During warmup: [0, x]
+    act(() => {
+      result.current.push(50, 10);
+    });
+    expect(result.current.xDomain).toEqual([0, 50]);
+
+    // Still warmup
+    act(() => {
+      result.current.push(80, 20);
+    });
+    expect(result.current.xDomain).toEqual([0, 80]);
+
+    // Full window: slides
+    act(() => {
+      result.current.push(150, 20);
+    });
+    expect(result.current.xDomain).toEqual([50, 150]);
+  });
+
+  it('auto-tracks y range with padding', () => {
+    const {result} = renderHook(() =>
+      useChartRange({xWindow: 100, yPadding: 0.1}),
+    );
+
+    act(() => {
+      result.current.push(1, 50);
+    });
+    // Single point: range=1 (fallback), pad=0.1
+    expect(result.current.yDomain[0]).toBeLessThan(50);
+    expect(result.current.yDomain[1]).toBeGreaterThan(50);
+
+    act(() => {
+      result.current.push(2, 100);
+    });
+    // Range 50-100, padding 10% = 5
+    expect(result.current.yDomain[0]).toBeCloseTo(45, 0);
+    expect(result.current.yDomain[1]).toBeCloseTo(105, 0);
+  });
+
+  it('does not auto-track y when fixed yDomain is set', () => {
+    const {result} = renderHook(() =>
+      useChartRange({xWindow: 100, yDomain: [0, 100]}),
+    );
+
+    act(() => {
+      result.current.push(1, 200);
+    });
+    expect(result.current.yDomain).toEqual([0, 100]);
+  });
+
+  it('centers y around zero when yCenter is true', () => {
+    const {result} = renderHook(() =>
+      useChartRange({xWindow: 100, yCenter: true, yPadding: 0}),
+    );
+
+    act(() => {
+      result.current.push(1, -30);
+      result.current.push(2, 10);
+    });
+    expect(result.current.yDomain[0]).toBe(-30);
+    expect(result.current.yDomain[1]).toBe(30);
+  });
+
+  it('resets state', () => {
+    const {result} = renderHook(() => useChartRange({xWindow: 200}));
+
+    act(() => {
+      result.current.push(500, 99);
+    });
+    expect(result.current.xDomain[1]).toBe(500);
+
+    act(() => {
+      result.current.reset();
+    });
+    expect(result.current.xDomain).toEqual([0, 0]);
+    expect(result.current.yDomain).toEqual([0, 1]);
+  });
+});

package/src/Chart/useChartRange.ts

@@ -0,0 +1,146 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file useChartRange.ts
+ * @output Hook that tracks streaming data ranges and provides domains for Chart
+ * @position Helper hook; sits between the data source and Chart props
+ *
+ * Manages xDomain/yDomain as state. Domain updates are synchronous with
+ * every push — no throttling. The chart's declared domain must always
+ * match the data being rendered (Tier 1 guarantee).
+ */
+
+import {useState, useRef, useCallback} from 'react';
+import type {ChartStreamGLHandle} from './ChartStreamGL';
+
+export interface UseChartRangeOptions {
+  /** Sliding window size for x-axis (number of ticks visible). Required. */
+  xWindow: number;
+  /**
+   * Fixed y-axis domain. When provided, y auto-tracking is disabled.
+   * Use when the range is known (e.g. 0-100 for percentages).
+   */
+  yDomain?: [number, number];
+  /**
+   * Padding factor for auto-tracked y-axis (default: 0.1 = 10%).
+   * Applied symmetrically above max and below min.
+   */
+  yPadding?: number;
+  /**
+   * Anchor y=0 in the center of the y-axis (default: false).
+   * When true, y-domain is always symmetric around 0.
+   */
+  yCenter?: boolean;
+}
+
+export interface UseChartRangeReturn {
+  /** Current x-axis domain — pass to Chart xDomain prop */
+  xDomain: [number, number];
+  /** Current y-axis domain — pass to Chart yDomain prop */
+  yDomain: [number, number];
+  /**
+   * Push a data point. Updates domains synchronously, then optionally
+   * forwards to a stream ref.
+   */
+  push(
+    x: number,
+    y: number,
+    streamRef?: React.RefObject<ChartStreamGLHandle | null>,
+  ): void;
+  /** Reset all tracking state */
+  reset(): void;
+}
+
+/**
+ * Tracks streaming data ranges and provides xDomain/yDomain for Chart.
+ *
+ * Domain updates are synchronous with every push — no throttling, no lag.
+ * This ensures the chart's declared domain always matches the rendered data.
+ *
+ * @example
+ * ```
+ * const {xDomain, yDomain, push} = useChartRange({xWindow: 300, yPadding: 0.1});
+ *
+ * <Chart xDomain={xDomain} yDomain={yDomain} ...>
+ *   <ChartStreamGL handleRef={streamRef} ... />
+ * </Chart>
+ * ```
+ */
+export function useChartRange({
+  xWindow,
+  yDomain: fixedYDomain,
+  yPadding = 0.1,
+  yCenter = false,
+}: UseChartRangeOptions): UseChartRangeReturn {
+  const [xDomain, setXDomain] = useState<[number, number]>([0, 0]);
+  const [yDomain, setYDomain] = useState<[number, number]>(
+    fixedYDomain ?? [0, 1],
+  );
+
+  const rangeRef = useRef({
+    yMin: fixedYDomain ? fixedYDomain[0] : Infinity,
+    yMax: fixedYDomain ? fixedYDomain[1] : -Infinity,
+  });
+
+  const push = useCallback(
+    (
+      x: number,
+      y: number,
+      streamRef?: React.RefObject<ChartStreamGLHandle | null>,
+    ) => {
+      // Forward to stream
+      streamRef?.current?.push(x, y);
+
+      // x domain: during warmup grow from [0, x], once full slide
+      const xMin = x >= xWindow ? x - xWindow : 0;
+      const xMax = x >= xWindow ? x : Math.max(x, 1);
+      setXDomain([xMin, xMax]);
+
+      // y domain: track min/max, update on every push
+      if (!fixedYDomain) {
+        const r = rangeRef.current;
+        let changed = false;
+        if (y < r.yMin) {
+          r.yMin = y;
+          changed = true;
+        }
+        if (y > r.yMax) {
+          r.yMax = y;
+          changed = true;
+        }
+
+        if (changed) {
+          const range = r.yMax - r.yMin || 1;
+          const pad = range * yPadding;
+          let min = r.yMin - pad;
+          let max = r.yMax + pad;
+
+          if (yCenter) {
+            const abs = Math.max(Math.abs(min), Math.abs(max));
+            min = -abs;
+            max = abs;
+          }
+
+          setYDomain([min, max]);
+        }
+      }
+    },
+    [xWindow, fixedYDomain, yPadding, yCenter],
+  );
+
+  const reset = useCallback(() => {
+    rangeRef.current = {
+      yMin: fixedYDomain ? fixedYDomain[0] : Infinity,
+      yMax: fixedYDomain ? fixedYDomain[1] : -Infinity,
+    };
+    setXDomain([0, 0]);
+    setYDomain(fixedYDomain ?? [0, 1]);
+  }, [fixedYDomain]);
+
+  return {
+    xDomain,
+    yDomain: fixedYDomain ?? yDomain,
+    push,
+    reset,
+  };
+}

package/src/Chart/utils.ts

@@ -0,0 +1,31 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file utils.ts
+ * @output Shared utilities for chart components
+ * @position Internal helpers; consumed by mark, axis, and interaction components
+ */
+
+import type {ScaleBand} from 'd3-scale';
+import type {ChartScale} from './types';
+
+/** Type guard for d3 band scales */
+export function isBandScale(scale: ChartScale): scale is ScaleBand<string> {
+  return typeof scale === 'function' && 'bandwidth' in scale;
+}
+
+/**
+ * Get the x pixel position for a datum using the chart's xKey and xScale.
+ * For band scales, returns the center of the band.
+ */
+export function xPixel(
+  d: Record<string, unknown>,
+  xKey: string,
+  xScale: ChartScale,
+): number {
+  const raw = d[xKey];
+  if (isBandScale(xScale)) {
+    return (xScale(String(raw)) ?? 0) + xScale.bandwidth() / 2;
+  }
+  return (xScale as (v: number) => number)(raw as number);
+}

package/src/Chart/webgl.ts

@@ -0,0 +1,192 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file webgl.ts
+ * @output Shared WebGL utilities for chart components
+ * @position Internal helpers; consumed by all GL mark components
+ *
+ * Provides:
+ * - Canvas mounting outside SVG (avoids foreignObject DPR blur)
+ * - Premultiplied alpha setup (correct compositing over page)
+ * - Shader compilation helpers
+ * - Smoothstep circle fragment for crisp point sprites
+ */
+
+/** Compile a WebGL shader, returns null on failure */
+export function compileShader(
+  gl: WebGLRenderingContext,
+  type: number,
+  src: string,
+): WebGLShader | null {
+  const s = gl.createShader(type);
+  if (!s) {
+    return null;
+  }
+  gl.shaderSource(s, src);
+  gl.compileShader(s);
+  if (!gl.getShaderParameter(s, gl.COMPILE_STATUS)) {
+    gl.deleteShader(s);
+    return null;
+  }
+  return s;
+}
+
+/** Link a vertex + fragment shader into a program */
+export function createProgram(
+  gl: WebGLRenderingContext,
+  vertSrc: string,
+  fragSrc: string,
+): WebGLProgram | null {
+  const vs = compileShader(gl, gl.VERTEX_SHADER, vertSrc);
+  const fs = compileShader(gl, gl.FRAGMENT_SHADER, fragSrc);
+  if (!vs || !fs) {
+    return null;
+  }
+  const p = gl.createProgram();
+  if (!p) {
+    return null;
+  }
+  gl.attachShader(p, vs);
+  gl.attachShader(p, fs);
+  gl.linkProgram(p);
+  if (!gl.getProgramParameter(p, gl.LINK_STATUS)) {
+    gl.deleteProgram(p);
+    return null;
+  }
+  return p;
+}
+
+/** Parse hex (#RRGGBB) to [r, g, b] floats 0-1 */
+export function hexToGL(hex: string): [number, number, number] {
+  const n = parseInt(hex.replace('#', ''), 16);
+  return [(n >> 16) / 255, ((n >> 8) & 0xff) / 255, (n & 0xff) / 255];
+}
+
+/** DPR with supersampling for crisp circles */
+export function getCanvasDPR(): number {
+  return (window.devicePixelRatio || 2) * 2;
+}
+
+/**
+ * Create or get a WebGL context with correct alpha settings.
+ * Uses premultiplied alpha for correct compositing over the page.
+ */
+export function getWebGLContext(
+  canvas: HTMLCanvasElement,
+): WebGLRenderingContext | null {
+  return canvas.getContext('webgl', {
+    alpha: true,
+    premultipliedAlpha: true,
+    antialias: true,
+  });
+}
+
+/**
+ * Set up standard GL state for chart rendering:
+ * - Clear with transparent
+ * - Enable premultiplied alpha blending
+ */
+export function setupGLState(gl: WebGLRenderingContext): void {
+  gl.clearColor(0, 0, 0, 0);
+  gl.clear(gl.COLOR_BUFFER_BIT);
+  gl.enable(gl.BLEND);
+  gl.blendFunc(gl.ONE, gl.ONE_MINUS_SRC_ALPHA);
+}
+
+/**
+ * Size a canvas for sharp rendering, accounting for DPR.
+ * Returns the DPR used.
+ */
+export function sizeCanvas(
+  canvas: HTMLCanvasElement,
+  width: number,
+  height: number,
+): number {
+  const dpr = getCanvasDPR();
+  canvas.width = width * dpr;
+  canvas.height = height * dpr;
+  canvas.style.width = `${width}px`;
+  canvas.style.height = `${height}px`;
+  return dpr;
+}
+
+/**
+ * Mount a canvas as an absolute-positioned sibling to an SVG element.
+ * Automatically aligns with the SVG marker's position — no manual margin
+ * offset needed. This is a Tier 1 guarantee: the canvas lands exactly
+ * where the SVG content area is, regardless of chart margins or transforms.
+ *
+ * Call from a useEffect. Returns a cleanup function.
+ */
+export function mountCanvasOverSVG(
+  svgMarker: SVGGraphicsElement,
+  canvas: HTMLCanvasElement,
+  width: number,
+  height: number,
+): (() => void) | undefined {
+  const svg = svgMarker.ownerSVGElement;
+  if (!svg) {
+    return;
+  }
+  const parent = svg.parentElement;
+  if (!parent) {
+    return;
+  }
+
+  if (getComputedStyle(parent).position === 'static') {
+    parent.style.position = 'relative';
+  }
+
+  canvas.style.position = 'absolute';
+  canvas.style.pointerEvents = 'none';
+
+  // Compute offset from the SVG marker's actual screen position.
+  // The marker sits inside the chart's <g transform="translate(margin)">
+  // so its bounding rect includes the margin offset automatically.
+  // This is a Tier 1 guarantee — we derive position from the SVG, not from props.
+  const parentRect = parent.getBoundingClientRect();
+  const markerCTM = svgMarker.getScreenCTM();
+  if (markerCTM) {
+    canvas.style.left = `${markerCTM.e - parentRect.left}px`;
+    canvas.style.top = `${markerCTM.f - parentRect.top}px`;
+  } else {
+    canvas.style.left = '0';
+    canvas.style.top = '0';
+  }
+  canvas.style.width = `${width}px`;
+  canvas.style.height = `${height}px`;
+
+  parent.appendChild(canvas);
+
+  return () => {
+    if (canvas.parentElement === parent) {
+      parent.removeChild(canvas);
+    }
+  };
+}
+
+/**
+ * GLSL fragment for premultiplied-alpha circle with smoothstep AA.
+ * Use in fragment shaders that render point sprites.
+ *
+ * Expects:
+ * - varying float v_alpha (the final alpha before edge AA)
+ * - uniform vec3 u_color
+ *
+ * Returns: gl_FragColor with premultiplied alpha
+ */
+export const CIRCLE_FRAG_BODY = `
+    vec2 coord = gl_PointCoord - vec2(0.5);
+    float dist = length(coord);
+    if (dist > 0.5) discard;
+    float edge = 1.0 - smoothstep(0.48, 0.5, dist);
+    float a = v_alpha * edge;
+    gl_FragColor = vec4(u_color * a, a);
+`;
+
+/**
+ * Smoothstep compensation factor for gl_PointSize.
+ * The visible circle radius is 0.48 of the point sprite (smoothstep starts there),
+ * so we scale up by 1/0.96 to match SVG circle radius exactly.
+ */
+export const POINT_SIZE_COMPENSATION = 1.0 / 0.96;