@pharos-ds/charts 0.0.0-stage → 1.0.10

package/src/types.ts

@@ -0,0 +1,212 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file types.ts
+ * @output Core types for the v2 chart architecture
+ * @position Foundation — consumed by layout, renderers, and interactions
+ */
+
+import type {ReactNode} from 'react';
+import type {ScaleLinear, ScaleBand} from 'd3-scale';
+
+export type ChartScale = ScaleLinear<number, number> | ScaleBand<string>;
+
+/**
+ * A color for a mark: either a constant CSS color/token, or an accessor that
+ * returns a color per datum (for per-element coloring, e.g. positive/negative).
+ */
+export type ColorAccessor =
+  string | ((datum: Record<string, unknown>, index: number) => string);
+
+/**
+ * Fallback series color used when a mark has neither an explicit color nor a
+ * palette color assigned by the chart root. Uses an EMITTED core token
+ * (`--color-accent`) — the data-viz `--color-data-*` tokens are JS-only values
+ * (resolved via useChartColors), not CSS custom properties, so `var(--color-data-*)`
+ * would render nothing. The chart root normally assigns a resolved palette color,
+ * so this is only a last-resort fallback.
+ */
+export const DEFAULT_SERIES_COLOR = 'var(--color-accent)';
+
+/**
+ * Controls how the y-axis domain is derived when no explicit `yDomain` is given:
+ * - `'auto'` (default) — bar/area marks pin an honest zero baseline; continuous-
+ *   only charts (line/dot/…) get a little headroom so points don't touch edges.
+ * - `'zero'` — symmetric around zero (good for +/- data like profit/loss).
+ * - `'data'` — tight fit to the data extent (no zero forcing, no headroom).
+ */
+export type YBaseline = 'auto' | 'zero' | 'data';
+
+export interface ChartMargin {
+  top: number;
+  right: number;
+  bottom: number;
+  left: number;
+}
+
+/** Resolved pixel position for a single data point in a series */
+export interface ResolvedPoint {
+  /** Pixel x in plot area coordinates */
+  px: number;
+  /** Pixel y in plot area coordinates (top of mark) */
+  py: number;
+  /** Pixel y baseline (bottom of mark) — differs from py when stacked */
+  py0: number;
+  /** Index into the data array */
+  dataIndex: number;
+}
+
+/** Context passed to resolve() and render() on each series */
+export interface SeriesContext {
+  data: Record<string, unknown>[];
+  xKey: string;
+  xScale: ChartScale;
+  yScale: ScaleLinear<number, number>;
+  /**
+   * Categorical y band scale for row-based marks (e.g. heatmap). Present only
+   * when a series declares `layout.yBandKey`; in that case the y-axis is
+   * categorical and the linear `yScale` is unused/degenerate.
+   */
+  yBandScale?: ScaleBand<string>;
+  /** Width of the plot area */
+  width: number;
+  /** Height of the plot area */
+  height: number;
+}
+
+/**
+ * The standardized shape every mark helper returns.
+ * Each mark type is self-contained: it knows how to resolve positions
+ * and how to render itself. The chart root just iterates and calls.
+ *
+ * A SeriesDef instance is single-use: the layout/render pass annotates it in
+ * place (`_uid`, `_isTopOfStack`, `_resolvedColor`), so a given def must belong
+ * to exactly one <Chart>. Build a fresh series array per chart rather than
+ * sharing the same mark objects across charts.
+ */
+export interface SeriesDef {
+  /** Mark type identifier */
+  readonly type: string;
+  /**
+   * Semantic key for this series — typically the dataKey. Used as a
+   * human-readable label fallback and for stack/group coordination. It is NOT
+   * guaranteed unique (two series can share a dataKey), so it must never be
+   * used as a Map key or React key — use `_uid` for identity instead.
+   */
+  readonly key: string;
+  /** Data keys this series reads from — used to compute y domain */
+  readonly dataKeys: string[];
+  /**
+   * Collision-free per-instance identity, assigned by the layout pass from the
+   * series' position in the `series` array. This is the key used for the
+   * resolved map, React keys, and tooltip/hover lookups. Never set it yourself.
+   */
+  _uid?: string;
+  /** Whether this series is the topmost in its stack (set during layout) */
+  _isTopOfStack?: boolean;
+  /** Static color for legend display. Undefined if color is dynamic (accessor function). */
+  readonly color?: string;
+  /**
+   * Palette color assigned by the chart root for series that don't supply a
+   * static color (auto-colored or accessor-colored). Used as the render fallback
+   * and the legend/tooltip representative color. Never set it yourself.
+   */
+  _resolvedColor?: string;
+  /** Human-readable label for legend. Falls back to key if not provided. */
+  readonly label?: string;
+  /** Layout hints the chart root uses for cross-series coordination */
+  readonly layout: {
+    /** Stack group — series with same stack accumulate */
+    stack?: string;
+    /** Bar group — series with same group subdivide bandwidth */
+    group?: string;
+    /** Whether this series contributes to y-domain zero inclusion */
+    includeZero?: boolean;
+    /**
+     * When set, the chart's y-axis is a band scale built from this data key's
+     * unique values (categorical rows, e.g. a heatmap's days) rather than a
+     * linear value scale. The layout pass exposes it to marks and the axis as
+     * `yBandScale`, so a left `<ChartAxis>` renders the categories aligned to
+     * each row. A heatmap should also declare `dataKeys: []` so it doesn't feed
+     * the (now unused) linear y-domain.
+     */
+    yBandKey?: string;
+  };
+  /**
+   * Resolve pixel positions for each data point.
+   * Called by the chart root during the layout pass.
+   * Receives pre-computed stack offsets if stacked.
+   */
+  resolve(
+    ctx: SeriesContext,
+    stackOffsets?: {y0: number; y1: number}[],
+    groupInfo?: {index: number; count: number},
+  ): ResolvedPoint[];
+  /**
+   * Render the mark given resolved positions.
+   * Called by the chart root during the render pass.
+   * Returns SVG elements (or manages its own canvas for WebGL).
+   */
+  render(resolved: ResolvedPoint[], ctx: SeriesContext): ReactNode;
+}
+
+/** Resolved positions for all series */
+export type ResolvedPositions = Map<string, ResolvedPoint[]>;
+
+/** Pointer event normalized to plot-area coordinates */
+export interface ChartPointerEvent {
+  x: number;
+  y: number;
+  nearest: (ResolvedPoint & {seriesKey: string}) | null;
+  active: boolean;
+}
+
+/**
+ * Which way the chart reads. `'vertical'` (default): categories along x, values
+ * grow up. `'horizontal'`: categories along y, values grow right (horizontal
+ * bars). Marks always resolve in the vertical "plot space"; the chart root
+ * transposes them on screen.
+ */
+export type ChartOrientation = 'vertical' | 'horizontal';
+
+/** Context provided by Chart to interaction children */
+export interface ChartContext {
+  /**
+   * Chart orientation. Chrome (axes, grid) receives display-space scales: for
+   * `'horizontal'`, `xScale` is the value scale and `yBandScale` the category
+   * scale. `resolved` points stay in plot space (see `ChartOrientation`).
+   */
+  orientation?: ChartOrientation;
+  width: number;
+  height: number;
+  margin: ChartMargin;
+  data: Record<string, unknown>[];
+  xKey: string;
+  xScale: ChartScale;
+  yScale: ScaleLinear<number, number>;
+  /**
+   * Categorical y band scale (e.g. heatmap rows), present when a series declares
+   * `layout.yBandKey`. Chrome that renders the y-axis (`ChartAxis`) should
+   * prefer this over the linear `yScale` when it exists.
+   */
+  yBandScale?: ScaleBand<string>;
+  resolved: Map<string, ResolvedPoint[]>;
+  onPointer: (handler: (e: ChartPointerEvent) => void) => () => void;
+  svgRef: React.RefObject<SVGSVGElement | null>;
+}
+
+/**
+ * Series mark types that are utility / annotation marks rather than primary
+ * data. They're skipped from chrome surfaces (legend, tooltip rows) since
+ * they don't represent values the user is comparing.
+ */
+export const UTILITY_MARK_TYPES: ReadonlySet<string> = new Set([
+  'referenceLine',
+  'errorBar',
+  'band',
+]);
+
+/** True if the series type is a utility / annotation mark. */
+export function isUtilityMarkType(type: string): boolean {
+  return UTILITY_MARK_TYPES.has(type);
+}

package/src/useChartColors.ts

@@ -0,0 +1,41 @@
+// 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
+ *
+ * Returns a stable reference across renders — the palette only rebuilds when the
+ * resolved theme tokens change (theme or color mode), so consumers can safely
+ * use the result in effect/memo dependency arrays.
+ */
+
+import {useMemo} from 'react';
+import {useTheme} from '@pharos-ds/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 {
+  // Depend on the memoized token map (stable per theme + mode), not useTheme's
+  // `token` function, which is a fresh closure on every render and would defeat
+  // memoization — returning a new palette object each render.
+  const {tokens} = useTheme();
+
+  return useMemo(
+    () => getChartColorsFromResolver(name => tokens[name] ?? ''),
+    [tokens],
+  );
+}

package/src/utils.ts

@@ -0,0 +1,38 @@
+// 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;
+  }
+  // Not a band scale → the guard narrows `xScale` to the linear scale, so no
+  // cast is needed. Coerce explicitly: finite numbers pass through, Date/
+  // numeric-string map as d3 would. Anything that coerces to a non-finite value
+  // — a non-numeric (→ NaN) or a raw ±Infinity — collapses to NaN, a single
+  // off-canvas sentinel that marks already skip, rather than a silently wrong
+  // position (d3 maps ±Infinity to an out-of-range pixel, not off-canvas).
+  const value = typeof raw === 'number' ? raw : Number(raw);
+  return Number.isFinite(value) ? xScale(value) : NaN;
+}

package/src/webgl.ts

@@ -0,0 +1,262 @@
+// 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
+ * - Hex-to-GL color conversion via the shared @pharos-ds/core/utils/color
+ *   parsers (fallback instead of NaN)
+ * - Context-loss registration + eager context teardown helpers
+ */
+
+import {parseHex, toGLFloats} from '@pharos-ds/core/utils';
+
+/** 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) {
+    // One shader may have compiled while the other failed — free the survivor
+    // so the failure path never leaks a shader object.
+    if (vs) {
+      gl.deleteShader(vs);
+    }
+    if (fs) {
+      gl.deleteShader(fs);
+    }
+    return null;
+  }
+  const p = gl.createProgram();
+  if (!p) {
+    gl.deleteShader(vs);
+    gl.deleteShader(fs);
+    return null;
+  }
+  gl.attachShader(p, vs);
+  gl.attachShader(p, fs);
+  gl.linkProgram(p);
+  // The shaders are now linked into the program; flag them for deletion so the
+  // GPU frees them once the program is deleted instead of leaving them attached
+  // (and allocated) for the program's whole lifetime.
+  gl.deleteShader(vs);
+  gl.deleteShader(fs);
+  if (!gl.getProgramParameter(p, gl.LINK_STATUS)) {
+    gl.deleteProgram(p);
+    return null;
+  }
+  return p;
+}
+
+/**
+ * Parse a hex color to [r, g, b] floats in 0-1.
+ *
+ * Accepts `#rgb`, `#rgba`, `#rrggbb`, and `#rrggbbaa`, with or without the
+ * leading `#` (any alpha byte is ignored). Non-hex input — CSS custom
+ * properties, `rgb()`, named colors, or malformed strings — returns a neutral
+ * fallback rather than producing NaN, so the GPU never receives a bad uniform.
+ */
+export function hexToGL(hex: string): [number, number, number] {
+  return toGLFloats(parseHex(hex));
+}
+
+/** DPR with 2x supersampling for crisp circles. SSR-safe (falls back to 2). */
+export function getCanvasDPR(): number {
+  const base = typeof window !== 'undefined' ? window.devicePixelRatio : 0;
+  return (base || 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();
+  // The drawing buffer must be a positive integer — a 0-sized (or fractional)
+  // buffer makes GL viewport/draw calls silently fail.
+  canvas.width = Math.max(1, Math.round(width * dpr));
+  canvas.height = Math.max(1, Math.round(height * dpr));
+  canvas.style.width = `${Math.max(0, width)}px`;
+  canvas.style.height = `${Math.max(0, 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);
+    }
+  };
+}
+
+/**
+ * Register WebGL context-loss/restore handlers on a canvas.
+ *
+ * Calling `preventDefault()` on the lost event is REQUIRED — without it the
+ * browser will never fire `webglcontextrestored`. `onLost` should drop any
+ * cached GL handles (they are all invalid after loss); `onRestored` should
+ * trigger a rebuild + redraw.
+ *
+ * Returns a cleanup that removes both listeners.
+ */
+export function registerContextLossHandlers(
+  canvas: HTMLCanvasElement,
+  onLost: () => void,
+  onRestored: () => void,
+): () => void {
+  const handleLost = (e: Event) => {
+    e.preventDefault();
+    onLost();
+  };
+  canvas.addEventListener('webglcontextlost', handleLost, false);
+  canvas.addEventListener('webglcontextrestored', onRestored, false);
+  return () => {
+    canvas.removeEventListener('webglcontextlost', handleLost, false);
+    canvas.removeEventListener('webglcontextrestored', onRestored, false);
+  };
+}
+
+/**
+ * Eagerly release a WebGL context and its GPU resources on teardown.
+ *
+ * Browsers cap the number of live contexts (~16), so freeing on unmount rather
+ * than waiting for GC prevents "too many active WebGL contexts" failures when
+ * many charts mount/unmount over a session.
+ */
+export function loseContext(gl: WebGLRenderingContext): void {
+  const ext = gl.getExtension('WEBGL_lose_context');
+  if (ext) {
+    ext.loseContext();
+  }
+}
+
+/**
+ * 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;