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

package/src/ThreeD/ThreeDSurface.tsx

@@ -0,0 +1,142 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file ThreeDSurface.tsx
+ * @output 3D surface mesh — projected triangulated grid with color mapping
+ */
+
+import {useMemo} from 'react';
+import {use3D} from './ThreeDContext';
+
+export interface ThreeDSurfaceProps {
+  /**
+   * Color ramp for surface height — low to high.
+   * Use useChartColors().sequential.blue(5).
+   */
+  colorRange: string[];
+  opacity?: number;
+  wireframe?: boolean;
+}
+
+function lerpColor(colors: string[], t: number): string {
+  const clamped = Math.max(0, Math.min(1, t));
+  if (colors.length === 1) {
+    return colors[0];
+  }
+  const scaled = clamped * (colors.length - 1);
+  const lo = Math.floor(scaled);
+  const hi = Math.min(lo + 1, colors.length - 1);
+  // Simple: just return the nearest
+  return scaled - lo < 0.5 ? colors[lo] : colors[hi];
+}
+
+/**
+ * 3D surface mesh. Data should be a grid of points with x, y (height), z.
+ * Points are triangulated in order and colored by y-value.
+ */
+export function ThreeDSurface({
+  colorRange,
+  opacity = 0.8,
+  wireframe = false,
+}: ThreeDSurfaceProps) {
+  const {
+    data,
+    xKey,
+    yKey,
+    zKey,
+    project,
+    xDomain,
+    yDomain,
+    zDomain,
+    normalize,
+  } = use3D();
+
+  const faces = useMemo(() => {
+    // Detect grid dimensions from unique x and z values
+    const xVals = [...new Set(data.map(d => d[xKey] as number))].sort(
+      (a, b) => a - b,
+    );
+    const zVals = [...new Set(data.map(d => d[zKey] as number))].sort(
+      (a, b) => a - b,
+    );
+    const cols = xVals.length;
+    const rows = zVals.length;
+
+    if (cols < 2 || rows < 2) {
+      return [];
+    }
+
+    // Build lookup grid
+    const grid = new Map<string, Record<string, unknown>>();
+    for (const d of data) {
+      grid.set(`${d[xKey]},${d[zKey]}`, d);
+    }
+
+    const result: {points: string; color: string; depth: number}[] = [];
+
+    for (let r = 0; r < rows - 1; r++) {
+      for (let c = 0; c < cols - 1; c++) {
+        const corners = [
+          grid.get(`${xVals[c]},${zVals[r]}`),
+          grid.get(`${xVals[c + 1]},${zVals[r]}`),
+          grid.get(`${xVals[c + 1]},${zVals[r + 1]}`),
+          grid.get(`${xVals[c]},${zVals[r + 1]}`),
+        ];
+
+        if (corners.some(c => !c)) {
+          continue;
+        }
+
+        const validCorners = corners.filter(
+          (c): c is Record<string, unknown> => c != null,
+        );
+
+        const projected = validCorners.map(d => {
+          const nx = normalize(d[xKey] as number, xDomain);
+          const ny = normalize(d[yKey] as number, yDomain);
+          const nz = normalize(d[zKey] as number, zDomain);
+          return {...project(nx, ny, nz), ny};
+        });
+
+        const avgY = projected.reduce((s, p) => s + p.ny, 0) / 4;
+        const avgDepth = projected.reduce((s, p) => s + p.depth, 0) / 4;
+        const color = lerpColor(colorRange, avgY);
+
+        result.push({
+          points: projected.map(p => `${p.px},${p.py}`).join(' '),
+          color,
+          depth: avgDepth,
+        });
+      }
+    }
+
+    return result.sort((a, b) => a.depth - b.depth);
+  }, [
+    data,
+    xKey,
+    yKey,
+    zKey,
+    project,
+    xDomain,
+    yDomain,
+    zDomain,
+    normalize,
+    colorRange,
+  ]);
+
+  return (
+    <g>
+      {faces.map((f, i) => (
+        <polygon
+          key={i}
+          points={f.points}
+          fill={wireframe ? 'none' : f.color}
+          fillOpacity={opacity}
+          stroke={wireframe ? f.color : f.color}
+          strokeWidth={wireframe ? 1 : 0.5}
+          strokeOpacity={wireframe ? 0.8 : 0.3}
+        />
+      ))}
+    </g>
+  );
+}

package/src/ThreeD/index.ts

@@ -0,0 +1,11 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+export {ThreeDChart, type ThreeDChartProps} from './ThreeDChart';
+export {ThreeDScatter, type ThreeDScatterProps} from './ThreeDScatter';
+export {ThreeDScatterGL, type ThreeDScatterGLProps} from './ThreeDScatterGL';
+export {ThreeDBar, type ThreeDBarProps} from './ThreeDBar';
+export {ThreeDGrid, type ThreeDGridProps} from './ThreeDGrid';
+export {ThreeDAxis, type ThreeDAxisProps} from './ThreeDAxis';
+export {ThreeDSurface, type ThreeDSurfaceProps} from './ThreeDSurface';
+export {use3D} from './ThreeDContext';
+export type {ThreeDContext, Camera, Point3D, ProjectedPoint} from './types';

package/src/ThreeD/projection.test.ts

@@ -0,0 +1,132 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect} from 'vitest';
+
+/**
+ * Verifies that the ThreeDScatterGL shader projection produces identical
+ * output to ThreeDChart's project() function. This is a Tier 1 guarantee —
+ * SVG and WebGL marks must agree on pixel positions.
+ *
+ * The shader's rotation math is replicated here in JS. If someone changes
+ * project() or the shader without updating the other, this test fails.
+ */
+
+// JS implementation of project() from ThreeDChart
+function projectJS(
+  nx: number,
+  ny: number,
+  nz: number,
+  azDeg: number,
+  elDeg: number,
+  width: number,
+  height: number,
+): {px: number; py: number; depth: number} {
+  const azRad = (azDeg * Math.PI) / 180;
+  const elRad = (elDeg * 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;
+
+  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};
+}
+
+// JS implementation of the GLSL shader's projection (what the GPU does)
+function projectShader(
+  nx: number,
+  ny: number,
+  nz: number,
+  azDeg: number,
+  elDeg: number,
+  width: number,
+  height: number,
+): {px: number; py: number; depth: number} {
+  const azRad = (azDeg * Math.PI) / 180;
+  const elRad = (elDeg * 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;
+
+  // Step 1: center
+  const x = nx - 0.5,
+    y = ny - 0.5,
+    z = nz - 0.5;
+  // Step 2: azimuth
+  const x1 = x * cosAz + z * sinAz;
+  const z1 = -x * sinAz + z * cosAz;
+  // Step 3: elevation
+  const y1 = y * cosEl - z1 * sinEl;
+  const z2 = y * sinEl + z1 * cosEl;
+  // Step 4: project to pixels
+  const px = cx + x1 * scale;
+  const py = cy - y1 * scale;
+
+  return {px, py, depth: z2};
+}
+
+describe('3D projection parity (Tier 1)', () => {
+  const testCases = [
+    {nx: 0, ny: 0, nz: 0, label: 'origin'},
+    {nx: 1, ny: 1, nz: 1, label: 'corner'},
+    {nx: 0.5, ny: 0.5, nz: 0.5, label: 'center'},
+    {nx: 0, ny: 1, nz: 0.5, label: 'top-front'},
+    {nx: 1, ny: 0, nz: 0, label: 'right-bottom-front'},
+    {nx: 0.3, ny: 0.7, nz: 0.9, label: 'arbitrary'},
+  ];
+
+  const cameras = [
+    {az: 0, el: 0, label: 'front'},
+    {az: 35, el: 25, label: 'default'},
+    {az: 90, el: 0, label: 'side'},
+    {az: 45, el: 45, label: 'diagonal'},
+    {az: -30, el: 15, label: 'negative azimuth'},
+    {az: 180, el: -20, label: 'behind'},
+  ];
+
+  const width = 600,
+    height = 400;
+
+  for (const cam of cameras) {
+    for (const pt of testCases) {
+      it(`${pt.label} at camera ${cam.label} (az=${cam.az}, el=${cam.el})`, () => {
+        const js = projectJS(
+          pt.nx,
+          pt.ny,
+          pt.nz,
+          cam.az,
+          cam.el,
+          width,
+          height,
+        );
+        const gl = projectShader(
+          pt.nx,
+          pt.ny,
+          pt.nz,
+          cam.az,
+          cam.el,
+          width,
+          height,
+        );
+
+        expect(gl.px).toBeCloseTo(js.px, 6);
+        expect(gl.py).toBeCloseTo(js.py, 6);
+        expect(gl.depth).toBeCloseTo(js.depth, 6);
+      });
+    }
+  }
+});

package/src/ThreeD/types.ts

@@ -0,0 +1,62 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file types.ts
+ * @output 3D chart types and context
+ * @position Foundation types consumed by all 3D sub-components
+ *
+ * Uses a simple perspective projection — no WebGL dependency for the
+ * coordinate system. Marks can render as projected SVG or WebGL.
+ */
+
+/** 3D point in data space */
+export interface Point3D {
+  x: number;
+  y: number;
+  z: number;
+}
+
+/** 2D projected point with depth for sorting */
+export interface ProjectedPoint {
+  px: number;
+  py: number;
+  depth: number;
+}
+
+/** Camera configuration */
+export interface Camera {
+  /** Rotation around the vertical axis in degrees (default: 30) */
+  azimuth: number;
+  /** Rotation above the horizontal plane in degrees (default: 20) */
+  elevation: number;
+  /** Distance from origin — affects perspective strength (default: 5) */
+  distance?: number;
+}
+
+/** 3D context provided by ThreeDChart to children */
+export interface ThreeDContext {
+  /** Inner width in pixels */
+  width: number;
+  /** Inner height in pixels */
+  height: number;
+  /** The full dataset */
+  data: Record<string, unknown>[];
+  /** Data key for x dimension */
+  xKey: string;
+  /** Data key for y dimension (vertical) */
+  yKey: string;
+  /** Data key for z dimension (depth) */
+  zKey: string;
+  /** Project a 3D data point to 2D screen coordinates */
+  project: (x: number, y: number, z: number) => ProjectedPoint;
+  /** Domain for x axis [min, max] */
+  xDomain: [number, number];
+  /** Domain for y axis [min, max] */
+  yDomain: [number, number];
+  /** Domain for z axis [min, max] */
+  zDomain: [number, number];
+  /** Normalize a value within a domain to [0, 1] */
+  normalize: (value: number, domain: [number, number]) => number;
+  /** Camera settings */
+  camera: Camera;
+}

package/src/index.ts

@@ -0,0 +1,250 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @astryxdesign/lab — Experimental Astryx components
+ *
+ * Components here are functional but not yet hardened for production.
+ * They're available in storybook and sandbox for testing and iteration.
+ * Once vetted, components graduate to @astryxdesign/core.
+ *
+ * This package is published to npm ONLY under the @canary dist-tag
+ * (npm install @astryxdesign/lab@canary). It is never released as a
+ * stable (latest) version.
+ */
+
+// Code components — syntax highlighting domain
+export {CodeBlock, type CodeBlockProps} from './CodeBlock';
+export {CodeEditor, type CodeEditorProps} from './CodeEditor';
+export {
+  tokenize,
+  tokenizeAsync,
+  SYNC_TOKENIZE_THRESHOLD,
+  type SyntaxToken,
+} from '@astryxdesign/core/CodeBlock';
+
+// Chat — experimental reasoning display
+export {
+  ChatReasoning,
+  type ChatReasoningProps,
+} from './ChatReasoning/ChatReasoning';
+
+// Schedule — experimental full-calendar views
+export * from './Schedule';
+
+// SVG Icon system — CSS-variable-driven multi-variation icons
+export {
+  SVGIcon,
+  type SVGIconProps,
+  type SVGIconVariation,
+  type SVGIconSize,
+  type SVGIconColor,
+  type SVGIconDef,
+  type IconShape,
+  type IconShapeRole,
+  iconVars,
+  variations,
+  opticalSize,
+  xIcon,
+  checkIcon,
+  bellIcon,
+  homeIcon,
+  settingsIcon,
+  calendarIcon,
+  menuIcon,
+  heartIcon,
+  eyeIcon,
+  starIcon,
+  folderIcon,
+  shieldIcon,
+  searchIcon,
+  mailIcon,
+  lockIcon,
+  starterIcons,
+} from './SVGIcon';
+
+// Chart components — composable d3-based data visualization
+export {
+  Chart,
+  type ChartProps,
+  type YBaseline,
+  ChartAxis,
+  type ChartAxisProps,
+  ChartGrid,
+  type ChartGridProps,
+  ChartBar,
+  type ChartBarProps,
+  ChartLine,
+  type ChartLineProps,
+  ChartArea,
+  type ChartAreaProps,
+  ChartErrorBar,
+  type ChartErrorBarProps,
+  ChartCandlestick,
+  type ChartCandlestickProps,
+  ChartDot,
+  type ChartDotProps,
+  ChartDotGL,
+  type ChartDotGLProps,
+  ChartDotGLInteractive,
+  type ChartDotGLInteractiveProps,
+  ChartHeatmapGL,
+  type ChartHeatmapGLProps,
+  ChartStreamGL,
+  type ChartStreamGLProps,
+  type ChartStreamGLHandle,
+  ChartTooltip,
+  type ChartTooltipProps,
+  type ChartCrosshairMode,
+  ChartLegend,
+  type ChartLegendProps,
+  type ChartLegendItem,
+  useChart,
+  type ChartContext,
+  type ChartMargin,
+  type ChartScale,
+  m4Reduce,
+  type M4Point,
+  useChartColors,
+  useChartRange,
+  type UseChartRangeOptions,
+  type UseChartRangeReturn,
+  getChartColors,
+  getChartColorsFromResolver,
+  type ChartColorsAPI,
+  type SequentialHue,
+  type TokenResolver,
+  compactNumber,
+  currency,
+  percent,
+  shortDate,
+  monthYear,
+} from './Chart';
+
+// Radial charts — spider, pie, donut
+export {
+  RadialChart,
+  type RadialChartProps,
+  RadialGrid,
+  type RadialGridProps,
+  RadialArea,
+  type RadialAreaProps,
+  RadialAxis,
+  type RadialAxisProps,
+  RadialSlice,
+  type RadialSliceProps,
+  RadialTooltip,
+  type RadialTooltipProps,
+  type RadialTooltipDatum,
+  useRadial,
+  type RadialContext,
+  type RadialMode,
+} from './Radial';
+
+// 3D charts — projected SVG with interactive rotation
+export {
+  ThreeDChart,
+  type ThreeDChartProps,
+  ThreeDScatter,
+  ThreeDScatterGL,
+  type ThreeDScatterProps,
+  type ThreeDScatterGLProps,
+  ThreeDBar,
+  type ThreeDBarProps,
+  ThreeDGrid,
+  type ThreeDGridProps,
+  ThreeDAxis,
+  type ThreeDAxisProps,
+  ThreeDSurface,
+  type ThreeDSurfaceProps,
+  use3D,
+  type ThreeDContext,
+  type Camera,
+  type Point3D,
+  type ProjectedPoint,
+} from './ThreeD';
+
+// Chart interactions
+export {
+  ChartBrush,
+  type ChartBrushProps,
+  type BrushMode,
+  type BrushRange,
+  ChartZoom,
+  type ChartZoomProps,
+  ChartSelect,
+  type ChartSelectProps,
+  ChartReferenceLine,
+  type ChartReferenceLineProps,
+} from './Chart';
+
+// Sankey / flow diagrams — ribbon-based flow visualization
+export {
+  SankeyChart,
+  type SankeyChartProps,
+  SankeyLink,
+  type SankeyLinkProps,
+  SankeyNode,
+  type SankeyNodeProps,
+  SankeyLabel,
+  type SankeyLabelProps,
+  useSankey,
+  type SankeyNodeDatum,
+  type SankeyLinkDatum,
+  type SankeyColumn,
+  type SankeyColumnDef,
+  type SankeyNodeLayout,
+  type SankeyLinkLayout,
+  type SankeyColumnLayout,
+  SankeyGrid,
+  type SankeyGridProps,
+  type SankeyContext,
+} from './Sankey';
+
+// Chart v2 — config model
+export {
+  Chart as ChartV2,
+  type ChartProps as ChartV2Props,
+  ChartLegend as ChartV2Legend,
+  type ChartLegendProps as ChartV2LegendProps,
+  type LegendItem as ChartV2LegendItem,
+  ChartAxis as ChartV2Axis,
+  type ChartAxisProps as ChartV2AxisProps,
+  ChartGrid as ChartV2Grid,
+  type ChartGridProps as ChartV2GridProps,
+  ChartSwatch as ChartV2Swatch,
+  swatchVariantForType as xdsChartV2SwatchVariantForType,
+  type ChartSwatchProps as ChartV2SwatchProps,
+  type ChartSwatchVariant as ChartV2SwatchVariant,
+  ChartTooltip as ChartV2Tooltip,
+  type ChartTooltipProps as ChartV2TooltipProps,
+  type ChartTooltipPlacement as ChartV2TooltipPlacement,
+  type TooltipSeriesValue as ChartV2TooltipSeriesValue,
+  bar,
+  line,
+  dot,
+  area,
+  band,
+  candlestick,
+  errorBar,
+  referenceLine,
+  dotGL,
+  dotGLInteractive,
+  heatmapGL,
+  streamGL,
+  useChartV2,
+  type SeriesDef,
+  type ChartV2Context,
+  type ChartPointerEvent,
+  type ResolvedPoint,
+  type ResolvedPositions,
+  type SeriesContext,
+  type ErrorBarOptions,
+  type ReferenceLineOptions,
+  type DotGLOptions,
+  type DotGLInteractiveOptions,
+  type HeatmapGLOptions,
+  type StreamGLOptions,
+  type StreamGLHandle,
+} from './ChartV2';
+export * from './Stepper';
+export * from './CircularProgress';