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

package/src/Chart/getChartColors.ts

@@ -0,0 +1,249 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file getChartColors.ts
+ * @output Pure function to resolve chart colors from a theme — no React required
+ * @position Foundation utility; consumed by useChartColors and non-React contexts
+ *
+ * Takes a token resolver function (or a defined theme + mode) and returns
+ * the full chart colors API. The useChartColors hook wraps this.
+ */
+
+import type {DefinedTheme} from '@astryxdesign/core/theme';
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/** Hue names available in the sequential ramps */
+export type SequentialHue =
+  | 'blue'
+  | 'shamrock'
+  | 'orange'
+  | 'pink'
+  | 'purple'
+  | 'red'
+  | 'teal'
+  | 'yellow'
+  | 'gray';
+
+/** The chart colors API returned by both getChartColors and useChartColors */
+export interface ChartColorsAPI {
+  categorical(n: number): string[];
+  sequential: Record<SequentialHue, (n: number) => string[]>;
+  diverging: {
+    positiveNegative(n: number): string[];
+    coldHot(n: number): string[];
+    custom(
+      neg: SequentialHue,
+      pos: SequentialHue,
+      n: number,
+      midpoint?: string,
+    ): string[];
+  };
+  semantic: {
+    positive: string;
+    negative: string;
+    warning: string;
+    neutral: string;
+  };
+  /** Structural colors for chart chrome — axes, grid, ticks, labels */
+  structural: {
+    axis: string;
+    grid: string;
+    tick: string;
+    label: string;
+  };
+  alpha(hex: string, opacity: number): string;
+}
+
+/** A function that resolves a token name to its current value */
+export type TokenResolver = (name: string) => string;
+
+// =============================================================================
+// Internals
+// =============================================================================
+
+const CATEGORICAL_TOKENS = [
+  '--color-data-categorical-blue',
+  '--color-data-categorical-orange',
+  '--color-data-categorical-purple',
+  '--color-data-categorical-green',
+  '--color-data-categorical-pink',
+  '--color-data-categorical-cyan',
+  '--color-data-categorical-red',
+  '--color-data-categorical-teal',
+  '--color-data-categorical-brown',
+  '--color-data-categorical-indigo',
+] as const;
+
+const SEQUENTIAL_HUES: SequentialHue[] = [
+  'blue',
+  'shamrock',
+  'orange',
+  'pink',
+  'purple',
+  'red',
+  'teal',
+  'yellow',
+  'gray',
+];
+
+function pickFromRamp(stops: string[], n: number): string[] {
+  if (n <= 0) {
+    return [];
+  }
+  if (n >= 5) {
+    return stops;
+  }
+  if (n === 1) {
+    return [stops[2]];
+  }
+  return Array.from(
+    {length: n},
+    (_, i) => stops[Math.round((i * 4) / (n - 1))],
+  );
+}
+
+function hexAlpha(hex: string, opacity: number): string {
+  const match = hex.match(
+    /^#?([0-9A-Fa-f]{2})([0-9A-Fa-f]{2})([0-9A-Fa-f]{2})$/,
+  );
+  if (!match) {
+    return hex;
+  }
+  const r = parseInt(match[1], 16);
+  const g = parseInt(match[2], 16);
+  const b = parseInt(match[3], 16);
+  return `rgba(${r},${g},${b},${Math.max(0, Math.min(1, opacity))})`;
+}
+
+// =============================================================================
+// Public API
+// =============================================================================
+
+/**
+ * Build chart colors from a token resolver function.
+ * This is the lowest-level API — pass any function that maps token names to values.
+ */
+export function getChartColorsFromResolver(
+  resolve: TokenResolver,
+): ChartColorsAPI {
+  const categorical = CATEGORICAL_TOKENS.map(t => resolve(t));
+
+  const ramp = (hue: SequentialHue): string[] =>
+    [5, 4, 3, 2, 1].map(step => resolve(`--color-data-${hue}-${step}`));
+
+  const gray1 = resolve('--color-data-gray-1');
+
+  function buildDiverging(
+    negHue: SequentialHue,
+    posHue: SequentialHue,
+    n: number,
+    midpoint: string = gray1,
+  ): string[] {
+    if (n <= 0) {
+      return [];
+    }
+    if (n === 1) {
+      return [midpoint];
+    }
+    const neg = ramp(negHue);
+    const pos = ramp(posHue);
+    const half = Math.floor(n / 2);
+    const hasCenter = n % 2 === 1;
+    const negSide = pickFromRamp(neg, half);
+    const posSide = pickFromRamp(pos, half).reverse();
+    if (hasCenter) {
+      return [...negSide, midpoint, ...posSide];
+    }
+    return [...negSide, ...posSide];
+  }
+
+  return {
+    categorical(n: number): string[] {
+      if (n <= 0) {
+        return [];
+      }
+      return categorical.slice(0, Math.min(n, categorical.length));
+    },
+
+    sequential: Object.fromEntries(
+      SEQUENTIAL_HUES.map(hue => [
+        hue,
+        (n: number): string[] => {
+          if (n <= 0) {
+            return [];
+          }
+          return pickFromRamp(ramp(hue), n);
+        },
+      ]),
+    ) as Record<SequentialHue, (n: number) => string[]>,
+
+    diverging: {
+      positiveNegative: (n: number) => buildDiverging('shamrock', 'red', n),
+      coldHot: (n: number) => buildDiverging('blue', 'red', n),
+      custom: (
+        neg: SequentialHue,
+        pos: SequentialHue,
+        n: number,
+        mid?: string,
+      ) => buildDiverging(neg, pos, n, mid),
+    },
+
+    semantic: {
+      positive: resolve('--color-data-categorical-green'),
+      negative: resolve('--color-data-categorical-red'),
+      warning: resolve('--color-data-categorical-orange'),
+      neutral: resolve('--color-data-neutral'),
+    },
+
+    structural: {
+      axis: resolve('--color-border-emphasized'),
+      grid: resolve('--color-border'),
+      tick: resolve('--color-border-emphasized'),
+      label: resolve('--color-text-secondary'),
+    },
+
+    alpha: hexAlpha,
+  };
+}
+
+/**
+ * Build chart colors from a defined theme and color mode.
+ *
+ * Use this in non-React contexts — WebGL setup, SSR, tests, Node scripts.
+ *
+ * @example
+ * ```
+ * import { neutralTheme } from '@astryxdesign/theme-neutral';
+ * const colors = getChartColors(neutralTheme, 'light');
+ * colors.categorical(5)
+ * ```
+ */
+export function getChartColors(
+  theme: DefinedTheme,
+  mode: 'light' | 'dark' = 'light',
+): ChartColorsAPI {
+  // Build a resolver from the theme's token map
+  const resolve: TokenResolver = (name: string) => {
+    // Check theme token overrides first, then fall back to defaults
+    const raw = theme.tokens?.[name] ?? '';
+    if (!raw) {
+      return '';
+    }
+    // Resolve light-dark() for the given mode
+    if (raw.startsWith('light-dark(') && raw.endsWith(')')) {
+      const inner = raw.slice(11, -1);
+      const commaIdx = inner.indexOf(',');
+      if (commaIdx !== -1) {
+        const light = inner.slice(0, commaIdx).trim();
+        const dark = inner.slice(commaIdx + 1).trim();
+        return mode === 'light' ? light : dark;
+      }
+    }
+    return raw;
+  };
+
+  return getChartColorsFromResolver(resolve);
+}

package/src/Chart/index.ts

@@ -0,0 +1,90 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+export {Chart, type ChartProps, type YBaseline} from './Chart';
+export {ChartAxis, type ChartAxisProps} from './ChartAxis';
+export {
+  compactNumber,
+  currency,
+  percent,
+  shortDate,
+  monthYear,
+} from './formatters';
+export {ChartGrid, type ChartGridProps} from './ChartGrid';
+export {ChartBar, type ChartBarProps} from './ChartBar';
+export {ChartLine, type ChartLineProps} from './ChartLine';
+export {ChartArea, type ChartAreaProps} from './ChartArea';
+export {ChartErrorBar, type ChartErrorBarProps} from './ChartErrorBar';
+export {
+  ChartCandlestick,
+  type ChartCandlestickProps,
+} from './ChartCandlestick';
+export {ChartDot, type ChartDotProps} from './ChartDot';
+export {ChartDotGL, type ChartDotGLProps} from './ChartDotGL';
+export {
+  ChartDotGLInteractive,
+  type ChartDotGLInteractiveProps,
+} from './ChartDotGLInteractive';
+export {
+  ChartHeatmapGL,
+  type ChartHeatmapGLProps,
+} from './ChartHeatmapGL';
+export {
+  ChartStreamGL,
+  type ChartStreamGLProps,
+  type ChartStreamGLHandle,
+} from './ChartStreamGL';
+export {
+  ChartTooltip,
+  type ChartTooltipProps,
+  type ChartCrosshairMode,
+} from './ChartTooltip';
+export {
+  ChartLegend,
+  type ChartLegendProps,
+  type ChartLegendItem,
+} from './ChartLegend';
+export {useChart} from './ChartContext';
+export type {ChartContext, ChartMargin, ChartScale, DataPoint} from './types';
+export {m4Reduce, type M4Point} from './m4';
+export {isBandScale, xPixel} from './utils';
+export {useChartColors} from './useChartColors';
+export {
+  getChartColors,
+  getChartColorsFromResolver,
+  type ChartColorsAPI,
+  type SequentialHue,
+  type TokenResolver,
+} from './getChartColors';
+export {
+  useChartRange,
+  type UseChartRangeOptions,
+  type UseChartRangeReturn,
+} from './useChartRange';
+export {
+  hexToGL,
+  getCanvasDPR,
+  getWebGLContext,
+  setupGLState,
+  sizeCanvas,
+  mountCanvasOverSVG,
+  compileShader,
+  createProgram as createGLProgram,
+  CIRCLE_FRAG_BODY,
+  POINT_SIZE_COMPENSATION,
+} from './webgl';
+export {
+  ChartBrush,
+  type ChartBrushProps,
+  type BrushMode,
+  type BrushRange,
+} from './ChartBrush';
+export {
+  ChartZoom,
+  type ChartZoomProps,
+  type ZoomToolbarPosition,
+} from './ChartZoom';
+export {ChartSelect, type ChartSelectProps} from './ChartSelect';
+export {
+  ChartReferenceLine,
+  type ChartReferenceLineProps,
+} from './ChartReferenceLine';

package/src/Chart/m4.test.ts

@@ -0,0 +1,66 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect} from 'vitest';
+import {m4Reduce, type M4Point} from './m4';
+
+describe('m4Reduce', () => {
+  it('returns empty for empty input', () => {
+    expect(m4Reduce([], 100)).toEqual([]);
+  });
+
+  it('returns data as-is when small enough', () => {
+    const data: M4Point[] = [
+      {x: 0, y: 1},
+      {x: 1, y: 2},
+      {x: 2, y: 3},
+    ];
+    expect(m4Reduce(data, 100)).toEqual(data);
+  });
+
+  it('reduces large dataset', () => {
+    // 10k points into 100px width = at most 400 output points
+    const data: M4Point[] = Array.from({length: 10000}, (_, i) => ({
+      x: i,
+      y: Math.sin(i * 0.01) * 100,
+    }));
+    const reduced = m4Reduce(data, 100);
+    expect(reduced.length).toBeLessThanOrEqual(400);
+    expect(reduced.length).toBeGreaterThan(0);
+  });
+
+  it('preserves min and max values', () => {
+    // Create data with a known spike
+    const data: M4Point[] = Array.from({length: 1000}, (_, i) => ({
+      x: i,
+      y: i === 500 ? 999 : 0,
+    }));
+    const reduced = m4Reduce(data, 10);
+    const maxY = Math.max(...reduced.map(p => p.y));
+    expect(maxY).toBe(999); // spike must be preserved
+  });
+
+  it('preserves first and last points', () => {
+    const data: M4Point[] = Array.from({length: 1000}, (_, i) => ({
+      x: i,
+      y: i,
+    }));
+    const reduced = m4Reduce(data, 10);
+    expect(reduced[0].x).toBe(0);
+    expect(reduced[reduced.length - 1].x).toBe(999);
+  });
+
+  it('handles single point', () => {
+    const data: M4Point[] = [{x: 5, y: 10}];
+    expect(m4Reduce(data, 100)).toEqual([{x: 5, y: 10}]);
+  });
+
+  it('respects custom xDomain', () => {
+    const data: M4Point[] = Array.from({length: 1000}, (_, i) => ({
+      x: i + 500,
+      y: i,
+    }));
+    const reduced = m4Reduce(data, 10, [500, 1499]);
+    expect(reduced.length).toBeLessThanOrEqual(40);
+    expect(reduced.length).toBeGreaterThan(0);
+  });
+});

package/src/Chart/m4.ts

@@ -0,0 +1,128 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file m4.ts
+ * @output m4Reduce — pixel-aware time series data reduction
+ * @position Utility consumed by chart line/stream components for large datasets
+ *
+ * Implements the M4 algorithm from "M4: A Visualization-Oriented Time Series
+ * Data Aggregation" (Jugel et al., VLDB 2014).
+ *
+ * For each pixel column, retains 4 values: first, last, min, max.
+ * This is the minimum set needed to visually reproduce a line chart at the
+ * target resolution. A 1M-point dataset becomes ~4×width points.
+ */
+
+export interface M4Point {
+  x: number;
+  y: number;
+}
+
+/**
+ * Reduce a time-series dataset to at most 4 points per pixel column.
+ *
+ * The output preserves all visual features (peaks, troughs, trends) that
+ * are distinguishable at the given pixel width. Points within the same
+ * pixel column are collapsed to first/min/max/last.
+ *
+ * @param data — input points, must be sorted by x ascending
+ * @param width — chart width in pixels (determines bucket count)
+ * @param xDomain — [min, max] of the x-axis. If omitted, derived from data.
+ * @returns reduced points (at most 4 × width, typically much fewer)
+ *
+ * @example
+ * ```
+ * // Reduce 100k points to fit a 600px chart
+ * const reduced = m4Reduce(rawData, 600);
+ * ```
+ */
+export function m4Reduce(
+  data: M4Point[],
+  width: number,
+  xDomain?: [number, number],
+): M4Point[] {
+  if (data.length === 0 || width <= 0) {
+    return [];
+  }
+
+  // If data fits without reduction, return as-is
+  if (data.length <= width * 4) {
+    return data;
+  }
+
+  const xMin = xDomain ? xDomain[0] : data[0].x;
+  const xMax = xDomain ? xDomain[1] : data[data.length - 1].x;
+  const xRange = xMax - xMin;
+  if (xRange <= 0) {
+    return [data[0]];
+  }
+
+  const bucketCount = Math.ceil(width);
+
+  // Each bucket tracks: first, last, min, max
+  interface Bucket {
+    first: M4Point | null;
+    last: M4Point | null;
+    min: M4Point | null;
+    max: M4Point | null;
+  }
+
+  const buckets: Bucket[] = Array.from({length: bucketCount}, () => ({
+    first: null,
+    last: null,
+    min: null,
+    max: null,
+  }));
+
+  // Single pass through the data
+  for (const point of data) {
+    const bucketIdx = Math.min(
+      bucketCount - 1,
+      Math.floor(((point.x - xMin) / xRange) * bucketCount),
+    );
+    const bucket = buckets[bucketIdx];
+
+    if (!bucket.first) {
+      bucket.first = point;
+      bucket.last = point;
+      bucket.min = point;
+      bucket.max = point;
+    } else {
+      bucket.last = point;
+      if (bucket.min && point.y < bucket.min.y) {
+        bucket.min = point;
+      }
+      if (bucket.max && point.y > bucket.max.y) {
+        bucket.max = point;
+      }
+    }
+  }
+
+  // Emit points in order: first, min, max, last per bucket
+  // Sort min/max by x within bucket to maintain temporal order
+  const result: M4Point[] = [];
+
+  for (const bucket of buckets) {
+    if (!bucket.first || !bucket.min || !bucket.max || !bucket.last) {
+      continue;
+    }
+
+    const points = [bucket.first, bucket.min, bucket.max, bucket.last];
+
+    // Deduplicate (some may be the same point)
+    const seen = new Set<M4Point>();
+    const unique: M4Point[] = [];
+    for (const p of points) {
+      if (!seen.has(p)) {
+        seen.add(p);
+        unique.push(p);
+      }
+    }
+
+    // Sort by x to maintain line continuity
+    unique.sort((a, b) => a.x - b.x);
+    result.push(...unique);
+  }
+
+  return result;
+}

package/src/Chart/types.ts

@@ -0,0 +1,64 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file types.ts
+ * @output Chart types, scale context, and margin convention
+ * @position Foundation types consumed by all chart sub-components
+ */
+
+import type {ScaleLinear, ScaleBand, ScaleTime} from 'd3-scale';
+
+/** Margin convention for chart SVG */
+export interface ChartMargin {
+  top: number;
+  right: number;
+  bottom: number;
+  left: number;
+}
+
+/** Any d3 scale that maps a domain to a pixel range */
+export type ChartScale =
+  | ScaleLinear<number, number>
+  | ScaleBand<string>
+  | ScaleTime<number, number>;
+
+/** Resolved data coordinates from pixel position */
+export interface DataPoint {
+  /** X value in data space (number for linear, string for band) */
+  x: number | string | null;
+  /** Y value in data space */
+  y: number;
+  /** Pixel x within the plot area */
+  px: number;
+  /** Pixel y within the plot area */
+  py: number;
+}
+
+/** Scale context provided by Chart to children */
+export interface ChartContext {
+  /** Inner width (SVG width minus margins) */
+  width: number;
+  /** Inner height (SVG height minus margins) */
+  height: number;
+  /** Margin offsets */
+  margin: ChartMargin;
+  /** The data key used for x-axis values */
+  xKey: string;
+  /** The full dataset */
+  data: Record<string, unknown>[];
+  /** X scale — band for categorical, linear/time for continuous */
+  xScale: ChartScale;
+  /** Y scale — typically linear */
+  yScale: ScaleLinear<number, number>;
+  /** Ref to the SVG element — used for coordinate transforms */
+  svgRef: React.RefObject<SVGSVGElement | null>;
+  /**
+   * Convert a pointer event to data coordinates.
+   * Handles SVG coordinate transform (margin offset) automatically.
+   */
+  pointerToData: (e: React.PointerEvent) => DataPoint;
+  /**
+   * Convert pixel coordinates (relative to plot area) to data values.
+   */
+  pixelToData: (px: number, py: number) => DataPoint;
+}

package/src/Chart/useChartColors.ts

@@ -0,0 +1,34 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file useChartColors.ts
+ * @output Theme-aware chart color palette hook
+ * @position React hook wrapping getChartColors — resolves from live theme context
+ */
+
+import {useMemo} from 'react';
+import {useTheme} from '@astryxdesign/core/theme';
+import {getChartColorsFromResolver} from './getChartColors';
+import type {ChartColorsAPI} from './getChartColors';
+
+/**
+ * Theme-aware chart colors. Resolves data-viz tokens from the current
+ * theme context — respects light/dark mode and custom themes.
+ *
+ * @example
+ * ```
+ * const colors = useChartColors();
+ * colors.categorical(5)
+ * colors.sequential.blue(3)
+ * colors.diverging.positiveNegative(5)
+ * colors.alpha('#0171E3', 0.5)
+ * ```
+ */
+export function useChartColors(): ChartColorsAPI {
+  const {token} = useTheme();
+
+  return useMemo(
+    () => getChartColorsFromResolver(name => token(name) || ''),
+    [token],
+  );
+}