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

package/src/ThreeD/ThreeDChart.tsx

@@ -0,0 +1,262 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file ThreeDChart.tsx
+ * @output Root 3D chart container — projected SVG with depth sorting
+ * @position Parent component; all 3D marks read from its context
+ */
+
+import {
+  type CSSProperties,
+  type ReactNode,
+  useMemo,
+  useRef,
+  useState,
+  useEffect,
+  useLayoutEffect,
+  useCallback,
+} from 'react';
+import {ThreeDProvider} from './ThreeDContext';
+import type {Camera, ProjectedPoint} from './types';
+
+export interface ThreeDChartProps {
+  data: Record<string, unknown>[];
+  xKey: string;
+  yKey: string;
+  zKey: string;
+  xDomain?: [number, number];
+  yDomain?: [number, number];
+  zDomain?: [number, number];
+  height?: number;
+  azimuth?: number;
+  elevation?: number;
+  interactive?: boolean;
+  /** Auto-rotate speed in degrees per frame (default: 0 = off) */
+  autoRotate?: number;
+  children: ReactNode;
+}
+
+function computeDomain(
+  data: Record<string, unknown>[],
+  key: string,
+): [number, number] {
+  let min = Infinity,
+    max = -Infinity;
+  for (const d of data) {
+    const v = d[key];
+    if (typeof v === 'number') {
+      if (v < min) {
+        min = v;
+      }
+      if (v > max) {
+        max = v;
+      }
+    }
+  }
+  return [min === Infinity ? 0 : min, max === -Infinity ? 1 : max];
+}
+
+export function ThreeDChart({
+  data,
+  xKey,
+  yKey,
+  zKey,
+  xDomain: xDomainProp,
+  yDomain: yDomainProp,
+  zDomain: zDomainProp,
+  height = 400,
+  azimuth: azimuthProp = 35,
+  elevation: elevationProp = 25,
+  interactive = false,
+  autoRotate = 0,
+  children,
+}: ThreeDChartProps) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const [containerWidth, setContainerWidth] = useState(0);
+  const [camera, setCamera] = useState<Camera>({
+    azimuth: azimuthProp,
+    elevation: elevationProp,
+  });
+  const dragRef = useRef<{
+    startX: number;
+    startY: number;
+    startAz: number;
+    startEl: number;
+  } | null>(null);
+
+  useLayoutEffect(() => {
+    if (!containerRef.current) {
+      return;
+    }
+    const obs = new ResizeObserver(e => {
+      if (e[0]) {
+        setContainerWidth(e[0].contentRect.width);
+      }
+    });
+    obs.observe(containerRef.current);
+    return () => obs.disconnect();
+  }, []);
+
+  const width = containerWidth;
+  const xDomain = xDomainProp ?? computeDomain(data, xKey);
+  const yDomain = yDomainProp ?? computeDomain(data, yKey);
+  const zDomain = zDomainProp ?? computeDomain(data, zKey);
+
+  const normalize = useCallback((value: number, domain: [number, number]) => {
+    const range = domain[1] - domain[0];
+    return range === 0 ? 0.5 : (value - domain[0]) / range;
+  }, []);
+
+  // Projection: normalized [0,1]^3 → 2D pixel coords
+  // SYNC: This math is replicated in ThreeDScatterGL's vertex shader.
+  // Both must produce identical output. Verified by projection.test.ts.
+  // If you change this, update the shader and re-run the parity tests.
+  const project = useMemo(() => {
+    const azRad = (camera.azimuth * Math.PI) / 180;
+    const elRad = (camera.elevation * Math.PI) / 180;
+    const cosAz = Math.cos(azRad),
+      sinAz = Math.sin(azRad);
+    const cosEl = Math.cos(elRad),
+      sinEl = Math.sin(elRad);
+    const scale = Math.min(width, height) * 0.35;
+    const cx = width / 2,
+      cy = height / 2;
+
+    return (nx: number, ny: number, nz: number): ProjectedPoint => {
+      const x = nx - 0.5,
+        y = ny - 0.5,
+        z = nz - 0.5;
+      const x1 = x * cosAz + z * sinAz;
+      const z1 = -x * sinAz + z * cosAz;
+      const y1 = y * cosEl - z1 * sinEl;
+      const z2 = y * sinEl + z1 * cosEl;
+      return {px: cx + x1 * scale, py: cy - y1 * scale, depth: z2};
+    };
+  }, [camera.azimuth, camera.elevation, width, height]);
+
+  const handleStart = useCallback(
+    (clientX: number, clientY: number) => {
+      if (!interactive) {
+        return;
+      }
+      dragRef.current = {
+        startX: clientX,
+        startY: clientY,
+        startAz: camera.azimuth,
+        startEl: camera.elevation,
+      };
+    },
+    [interactive, camera],
+  );
+
+  const handleMove = useCallback((clientX: number, clientY: number) => {
+    if (!dragRef.current) {
+      return;
+    }
+    const dx = clientX - dragRef.current.startX;
+    const dy = clientY - dragRef.current.startY;
+    setCamera({
+      azimuth: dragRef.current.startAz + dx * 0.5,
+      elevation: Math.max(
+        -89,
+        Math.min(89, dragRef.current.startEl - dy * 0.5),
+      ),
+    });
+  }, []);
+
+  const handleEnd = useCallback(() => {
+    dragRef.current = null;
+  }, []);
+
+  // Auto-rotation — throttled to ~20fps to avoid overwhelming React with re-renders
+  useEffect(() => {
+    if (autoRotate === 0) {
+      return;
+    }
+    let raf: number;
+    let lastUpdate = 0;
+    const interval = 50; // ms between React updates (~20fps)
+    const tick = (now: number) => {
+      if (!dragRef.current && now - lastUpdate >= interval) {
+        const elapsed = lastUpdate === 0 ? interval : now - lastUpdate;
+        lastUpdate = now;
+        const degrees = autoRotate * (elapsed / 16.67); // normalize to 60fps equivalent
+        setCamera(prev => ({...prev, azimuth: prev.azimuth + degrees}));
+      }
+      raf = requestAnimationFrame(tick);
+    };
+    raf = requestAnimationFrame(tick);
+    return () => cancelAnimationFrame(raf);
+  }, [autoRotate]);
+
+  const ctx = useMemo(
+    () => ({
+      width,
+      height,
+      data,
+      xKey,
+      yKey,
+      zKey,
+      project,
+      xDomain,
+      yDomain,
+      zDomain,
+      normalize,
+      camera,
+    }),
+    [
+      width,
+      height,
+      data,
+      xKey,
+      yKey,
+      zKey,
+      project,
+      xDomain,
+      yDomain,
+      zDomain,
+      normalize,
+      camera,
+    ],
+  );
+
+  const containerStyle: CSSProperties = {
+    width: '100%',
+    touchAction: interactive ? 'none' : undefined,
+    userSelect: interactive ? 'none' : undefined,
+  };
+
+  return (
+    <div ref={containerRef} style={containerStyle}>
+      {containerWidth > 0 && (
+        <svg
+          width={containerWidth}
+          height={height}
+          onMouseDown={e => handleStart(e.clientX, e.clientY)}
+          onMouseMove={e => handleMove(e.clientX, e.clientY)}
+          onMouseUp={handleEnd}
+          onMouseLeave={handleEnd}
+          onTouchStart={e => {
+            const t = e.touches[0];
+            if (t) {
+              handleStart(t.clientX, t.clientY);
+            }
+          }}
+          onTouchMove={e => {
+            const t = e.touches[0];
+            if (t) {
+              e.preventDefault();
+              handleMove(t.clientX, t.clientY);
+            }
+          }}
+          onTouchEnd={handleEnd}
+          style={{
+            cursor: interactive ? 'grab' : undefined,
+            touchAction: interactive ? 'none' : undefined,
+          }}>
+          <ThreeDProvider value={ctx}>{children}</ThreeDProvider>
+        </svg>
+      )}
+    </div>
+  );
+}

package/src/ThreeD/ThreeDContext.ts

@@ -0,0 +1,22 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file ThreeDContext.ts
+ * @output React context for 3D chart components
+ */
+
+import {createContext, useContext} from 'react';
+import type {ThreeDContext} from './types';
+
+const ThreeDCtx = createContext<ThreeDContext | null>(null);
+
+export const ThreeDProvider = ThreeDCtx.Provider;
+
+/** Access the 3D chart context. Throws if used outside ThreeDChart. */
+export function use3D(): ThreeDContext {
+  const ctx = useContext(ThreeDCtx);
+  if (!ctx) {
+    throw new Error('3D components must be used inside <ThreeDChart>');
+  }
+  return ctx;
+}

package/src/ThreeD/ThreeDGrid.tsx

@@ -0,0 +1,68 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file ThreeDGrid.tsx
+ * @output 3D wireframe grid on the floor plane (y=0)
+ */
+
+import {useMemo} from 'react';
+import {use3D} from './ThreeDContext';
+
+export interface ThreeDGridProps {
+  divisions?: number;
+}
+
+export function ThreeDGrid({divisions = 5}: ThreeDGridProps) {
+  const {project} = use3D();
+
+  const lines = useMemo(() => {
+    const result: {
+      x1: number;
+      y1: number;
+      x2: number;
+      y2: number;
+      depth: number;
+    }[] = [];
+    for (let i = 0; i <= divisions; i++) {
+      const t = i / divisions;
+      // X-parallel lines (along z)
+      const a = project(t, 0, 0);
+      const b = project(t, 0, 1);
+      result.push({
+        x1: a.px,
+        y1: a.py,
+        x2: b.px,
+        y2: b.py,
+        depth: (a.depth + b.depth) / 2,
+      });
+      // Z-parallel lines (along x)
+      const c = project(0, 0, t);
+      const d = project(1, 0, t);
+      result.push({
+        x1: c.px,
+        y1: c.py,
+        x2: d.px,
+        y2: d.py,
+        depth: (c.depth + d.depth) / 2,
+      });
+    }
+    return result.sort((a, b) => a.depth - b.depth);
+  }, [project, divisions]);
+
+  return (
+    <g>
+      {lines.map((l, i) => (
+        <line
+          key={i}
+          x1={l.x1}
+          y1={l.y1}
+          x2={l.x2}
+          y2={l.y2}
+          stroke="var(--color-border)"
+          strokeOpacity={0.3}
+          strokeWidth={1}
+        />
+      ))}
+    </g>
+  );
+}

package/src/ThreeD/ThreeDScatter.tsx

@@ -0,0 +1,63 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file ThreeDScatter.tsx
+ * @output 3D scatter plot — projected circles with depth-based sizing/opacity
+ */
+
+import {useMemo} from 'react';
+import {use3D} from './ThreeDContext';
+
+export interface ThreeDScatterProps {
+  color: string;
+  radius?: number;
+  opacity?: number;
+}
+
+export function ThreeDScatter({
+  color,
+  radius = 4,
+  opacity = 0.85,
+}: ThreeDScatterProps) {
+  const {
+    data,
+    xKey,
+    yKey,
+    zKey,
+    project,
+    xDomain,
+    yDomain,
+    zDomain,
+    normalize,
+  } = use3D();
+
+  const points = useMemo(() => {
+    return data
+      .map((d, i) => {
+        const nx = normalize(d[xKey] as number, xDomain);
+        const ny = normalize(d[yKey] as number, yDomain);
+        const nz = normalize(d[zKey] as number, zDomain);
+        const {px, py, depth} = project(nx, ny, nz);
+        return {px, py, depth, index: i};
+      })
+      .sort((a, b) => a.depth - b.depth); // painter's algorithm
+  }, [data, xKey, yKey, zKey, project, xDomain, yDomain, zDomain, normalize]);
+
+  return (
+    <g>
+      {points.map(p => {
+        const depthFactor = 0.75 + (p.depth + 0.5) * 0.25; // 0.5-1.0
+        return (
+          <circle
+            key={p.index}
+            cx={p.px}
+            cy={p.py}
+            r={radius * depthFactor}
+            fill={color}
+            fillOpacity={opacity * depthFactor}
+          />
+        );
+      })}
+    </g>
+  );
+}

package/src/ThreeD/ThreeDScatterGL.tsx

@@ -0,0 +1,270 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file ThreeDScatterGL.tsx
+ * @output WebGL 3D scatter — canvas overlaid outside SVG for sharp DPR rendering
+ * @position Child of ThreeDChart; reads camera from context (Tier 1)
+ *
+ * SYNC: The vertex shader replicates ThreeDChart's project() math exactly.
+ * Verified by projection.test.ts.
+ *
+ * The canvas renders as an absolute-positioned sibling to the SVG (not inside
+ * foreignObject) to avoid the browser's 1x compositing of foreignObject content
+ * on Retina displays.
+ */
+
+import {useRef, useEffect, useMemo} from 'react';
+import {use3D} from './ThreeDContext';
+
+export interface ThreeDScatterGLProps {
+  color: string;
+  size?: number;
+  opacity?: number;
+}
+
+function hexToGL(hex: string): [number, number, number] {
+  const n = parseInt(hex.replace('#', ''), 16);
+  return [(n >> 16) / 255, ((n >> 8) & 0xff) / 255, (n & 0xff) / 255];
+}
+
+// SYNC: Steps 1-5 match ThreeDChart.project() exactly.
+const VERT = `
+  attribute vec3 a_position;
+  uniform vec2 u_resolution;
+  uniform vec2 u_center;
+  uniform float u_scale;
+  uniform float u_cosAz;
+  uniform float u_sinAz;
+  uniform float u_cosEl;
+  uniform float u_sinEl;
+  uniform float u_size;
+  varying float v_depth;
+  void main() {
+    vec3 p = a_position - 0.5;
+    float x1 = p.x * u_cosAz + p.z * u_sinAz;
+    float z1 = -p.x * u_sinAz + p.z * u_cosAz;
+    float y1 = p.y * u_cosEl - z1 * u_sinEl;
+    float z2 = p.y * u_sinEl + z1 * u_cosEl;
+    float px = u_center.x + x1 * u_scale;
+    float py = u_center.y - y1 * u_scale;
+    vec2 clip = (vec2(px, py) / u_resolution) * 2.0 - 1.0;
+    gl_Position = vec4(clip.x, -clip.y, z2, 1.0);
+    v_depth = z2;
+    float depthFactor = 0.75 + (z2 + 0.5) * 0.25;
+    // Compensate for smoothstep edge erosion (visible at r=0.48, not 0.5)
+    // so visible circle matches SVG radius exactly
+    gl_PointSize = (u_size * depthFactor) / 0.96;
+  }
+`;
+
+const FRAG = `
+  precision mediump float;
+  uniform vec3 u_color;
+  uniform float u_opacity;
+  varying float v_depth;
+  void main() {
+    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 depthFactor = 0.75 + (v_depth + 0.5) * 0.25;
+    float a = u_opacity * depthFactor * edge;
+    // Premultiplied alpha — required for correct compositing over page
+    gl_FragColor = vec4(u_color * a, a);
+  }
+`;
+
+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;
+}
+
+function createProgram(gl: WebGLRenderingContext): WebGLProgram | null {
+  const vs = compileShader(gl, gl.VERTEX_SHADER, VERT);
+  const fs = compileShader(gl, gl.FRAGMENT_SHADER, FRAG);
+  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;
+}
+
+export function ThreeDScatterGL({
+  color,
+  size = 4,
+  opacity = 0.85,
+}: ThreeDScatterGLProps) {
+  const {
+    data,
+    xKey,
+    yKey,
+    zKey,
+    xDomain,
+    yDomain,
+    zDomain,
+    normalize,
+    camera,
+    width,
+    height,
+  } = use3D();
+  const canvasRef = useRef<HTMLCanvasElement | null>(null);
+  const containerRef = useRef<HTMLDivElement | null>(null);
+  const glRef = useRef<WebGLRenderingContext | null>(null);
+  const programRef = useRef<WebGLProgram | null>(null);
+  const markerRef = useRef<SVGGElement>(null);
+
+  // Normalized 3D positions
+  const positions = useMemo(() => {
+    const buf = new Float32Array(data.length * 3);
+    for (let i = 0; i < data.length; i++) {
+      buf[i * 3] = normalize(data[i][xKey] as number, xDomain);
+      buf[i * 3 + 1] = normalize(data[i][yKey] as number, yDomain);
+      buf[i * 3 + 2] = normalize(data[i][zKey] as number, zDomain);
+    }
+    return buf;
+  }, [data, xKey, yKey, zKey, xDomain, yDomain, zDomain, normalize]);
+
+  // Mount canvas as sibling to SVG
+  useEffect(() => {
+    const marker = markerRef.current;
+    if (!marker) {
+      return;
+    }
+    const svg = marker.ownerSVGElement;
+    if (!svg) {
+      return;
+    }
+    const parent = svg.parentElement;
+    if (!parent) {
+      return;
+    }
+
+    // Ensure parent is positioned for absolute child
+    if (getComputedStyle(parent).position === 'static') {
+      parent.style.position = 'relative';
+    }
+
+    // Create canvas if not exists
+    if (!canvasRef.current) {
+      const canvas = document.createElement('canvas');
+      canvas.style.position = 'absolute';
+      canvas.style.top = '0';
+      canvas.style.left = '0';
+      canvas.style.pointerEvents = 'none';
+      canvasRef.current = canvas;
+    }
+
+    const canvas = canvasRef.current;
+    parent.appendChild(canvas);
+    containerRef.current = parent as HTMLDivElement;
+
+    return () => {
+      if (canvas.parentElement) {
+        canvas.parentElement.removeChild(canvas);
+      }
+    };
+  }, []);
+
+  // Draw
+  useEffect(() => {
+    const canvas = canvasRef.current;
+    if (!canvas || width <= 0 || height <= 0) {
+      return;
+    }
+
+    const dpr = (window.devicePixelRatio || 2) * 2; // 2x supersampling + smoothstep for crisp circles // supersampling for crisp circles
+    canvas.width = width * dpr;
+    canvas.height = height * dpr;
+    canvas.style.width = `${width}px`;
+    canvas.style.height = `${height}px`;
+
+    if (!glRef.current) {
+      glRef.current = canvas.getContext('webgl', {
+        alpha: true,
+        premultipliedAlpha: true,
+        antialias: true,
+      });
+    }
+    const gl = glRef.current;
+    if (!gl) {
+      return;
+    }
+
+    if (!programRef.current) {
+      programRef.current = createProgram(gl);
+    }
+    const program = programRef.current;
+    if (!program) {
+      return;
+    }
+
+    const buf = gl.createBuffer();
+    gl.bindBuffer(gl.ARRAY_BUFFER, buf);
+    gl.bufferData(gl.ARRAY_BUFFER, positions, gl.STATIC_DRAW);
+
+    gl.viewport(0, 0, canvas.width, canvas.height);
+    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);
+    gl.useProgram(program);
+
+    const aPos = gl.getAttribLocation(program, 'a_position');
+    gl.enableVertexAttribArray(aPos);
+    gl.vertexAttribPointer(aPos, 3, gl.FLOAT, false, 0, 0);
+
+    // All uniforms in logical pixels — viewport handles DPR
+    const azRad = (camera.azimuth * Math.PI) / 180;
+    const elRad = (camera.elevation * Math.PI) / 180;
+    const scale = Math.min(width, height) * 0.35;
+    const [r, g, b] = hexToGL(color);
+
+    gl.uniform2f(gl.getUniformLocation(program, 'u_resolution'), width, height);
+    gl.uniform2f(
+      gl.getUniformLocation(program, 'u_center'),
+      width / 2,
+      height / 2,
+    );
+    gl.uniform1f(gl.getUniformLocation(program, 'u_scale'), scale);
+    gl.uniform1f(gl.getUniformLocation(program, 'u_cosAz'), Math.cos(azRad));
+    gl.uniform1f(gl.getUniformLocation(program, 'u_sinAz'), Math.sin(azRad));
+    gl.uniform1f(gl.getUniformLocation(program, 'u_cosEl'), Math.cos(elRad));
+    gl.uniform1f(gl.getUniformLocation(program, 'u_sinEl'), Math.sin(elRad));
+    gl.uniform3f(gl.getUniformLocation(program, 'u_color'), r, g, b);
+    gl.uniform1f(gl.getUniformLocation(program, 'u_size'), size * dpr);
+    gl.uniform1f(gl.getUniformLocation(program, 'u_opacity'), opacity);
+
+    gl.drawArrays(gl.POINTS, 0, data.length);
+    gl.deleteBuffer(buf);
+  }, [positions, camera, color, size, opacity, width, height, data.length]);
+
+  if (width <= 0 || height <= 0) {
+    return null;
+  }
+
+  // Render an invisible SVG marker — the canvas is mounted imperatively as a sibling
+  return <g ref={markerRef} />;
+}