@biohub/scatterplot 0.1.4

package/dist/index.d.ts

@@ -0,0 +1,354 @@
+import { JSX } from 'react/jsx-runtime';
+import { RefObject } from 'react';
+
+/**
+ * Calculate data bounds from raw position buffer
+ * @param positions - Float32Array of [x, y, x, y, ...] coordinates
+ * @param count - Number of points
+ * @returns Data bounds
+ */
+export declare function calculateBounds(positions: Float32Array, count: number): DataBounds;
+
+/**
+ * Camera state for scatterplot visualization
+ */
+export declare interface Camera {
+    /** Zoom level (1.0 = no zoom) */
+    zoom: number;
+    /** Pan offset in normalized device coordinates (-1 to 1) */
+    pan: {
+        x: number;
+        y: number;
+    };
+}
+
+/**
+ * Theme types for the scatterplot component
+ */
+export declare interface CanvasTheme {
+    background: string;
+    dataPadding: number;
+}
+
+export declare interface ContainerSize {
+    width: number;
+    height: number;
+}
+
+/**
+ * Create a flag buffer for a dataset
+ * @param count - Number of points
+ * @param selectedIndices - Set of selected point indices (optional)
+ * @param highlightedIndices - Set of highlighted point indices (optional)
+ * @param backgroundIndices - Set of background point indices (optional).
+ *        If not provided and selectedIndices has items, non-selected/non-highlighted points are auto-marked as background.
+ * @returns Uint8Array of encoded flags (8 bits per point, 0-255)
+ */
+export declare function createFlagBuffer(count: number, selectedIndices?: Set<number>, highlightedIndices?: Set<number>, backgroundIndices?: Set<number>): Uint8Array;
+
+/**
+ * Create a theme by merging overrides with a base theme.
+ *
+ * Uses explicit property spreading instead of a generic deep merge because
+ * the theme structure is fixed at 2 levels. This keeps the implementation
+ * simple and avoids adding a dependency for something trivial.
+ */
+export declare function createTheme(overrides: PartialTheme, base?: ScatterplotTheme): ScatterplotTheme;
+
+export declare const darkTheme: ScatterplotTheme;
+
+/**
+ * Geometry and normalization utilities for scatterplot
+ */
+export declare interface DataBounds {
+    xMin: number;
+    xMax: number;
+    yMin: number;
+    yMax: number;
+}
+
+/**
+ * Transform a data point to screen (canvas pixel) coordinates
+ * This is the core projection pipeline used for hit-testing and interaction
+ * @param x - Data X coordinate
+ * @param y - Data Y coordinate
+ * @param xMin - Minimum X value in data space
+ * @param yMin - Minimum Y value in data space
+ * @param scale - Isotropic scale factor from getNormalizationScales
+ * @param xOffset - X centering offset from getNormalizationScales
+ * @param yOffset - Y centering offset from getNormalizationScales
+ * @param scaleX - Viewport X scale from getViewportScales
+ * @param scaleY - Viewport Y scale from getViewportScales
+ * @param panX - Camera pan X offset
+ * @param panY - Camera pan Y offset
+ * @param canvasWidth - Canvas width in pixels
+ * @param canvasHeight - Canvas height in pixels
+ * @returns Screen coordinates { screenX, screenY }
+ */
+export declare function dataPointToScreen(x: number, y: number, xMin: number, yMin: number, scale: number, xOffset: number, yOffset: number, scaleX: number, scaleY: number, panX: number, panY: number, canvasWidth: number, canvasHeight: number): {
+    screenX: number;
+    screenY: number;
+};
+
+export declare interface DebugTheme {
+    background: string;
+    color: string;
+    fontFamily: string;
+    fontSize: string;
+}
+
+/**
+ * Utility type for partial theme overrides
+ */
+declare type DeepPartial<T> = {
+    [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
+};
+
+/**
+ * Default camera state: no zoom, no pan
+ */
+export declare const DEFAULT_CAMERA: Camera;
+
+export declare const defaultTheme: ScatterplotTheme;
+
+/**
+ * Find the closest point to a click position
+ * @param clickX - Click X coordinate in canvas space (0 to width)
+ * @param clickY - Click Y coordinate in canvas space (0 to height)
+ * @param positions - Float32Array of [x, y, x, y, ...] coordinates
+ * @param count - Number of points
+ * @param canvasWidth - Canvas width in pixels
+ * @param canvasHeight - Canvas height in pixels
+ * @param camera - Current camera state (zoom and pan)
+ * @param maxDistance - Maximum distance in pixels to consider. For default, @see {@link DEFAULT_INTERACTION_DISTANCE_PX}
+ * @param bounds - Pre-computed data bounds
+ * @param dataPadding - Padding around data in pixels. For default, @see {@link defaultTheme.canvas.dataPadding}
+ * @returns Index of closest point, or null if no point within maxDistance
+ */
+export declare function findClosestPointRaw(clickX: number, clickY: number, positions: Float32Array, count: number, canvasWidth: number, canvasHeight: number, camera: Camera, maxDistance: number | undefined, bounds: DataBounds, dataPadding?: number): number | null;
+
+/**
+ * Find all points within a lasso polygon
+ * @param polygon - Array of [x, y] screen coordinates defining the lasso
+ * @param positions - Float32Array of [x, y, x, y, ...] coordinates
+ * @param count - Number of points
+ * @param canvasWidth - Canvas width in CSS pixels
+ * @param canvasHeight - Canvas height in CSS pixels
+ * @param camera - Current camera state (zoom and pan)
+ * @param bounds - Pre-computed data bounds
+ * @param dataPadding - Padding around data in pixels. For default, @see {@link defaultTheme.canvas.dataPadding}
+ * @returns Set of indices for points within the lasso
+ */
+export declare function findPointsInLassoRaw(polygon: [number, number][], positions: Float32Array, count: number, canvasWidth: number, canvasHeight: number, camera: Camera, bounds: DataBounds, dataPadding?: number): Set<number>;
+
+/**
+ * Converts hex color string to RGBA byte values (0-255 range)
+ * @param hex - Hex color string (e.g., "#ff0000" or "#f00")
+ * @param alpha - Alpha value (0-255). For default, @see {@link DEFAULT_ALPHA}
+ * @returns Array of [r, g, b, a] values in 0-255 range
+ */
+export declare function hexToRgba(hex: string, alpha?: number): [number, number, number, number];
+
+export declare const highContrastTheme: ScatterplotTheme;
+
+export declare interface LassoTheme {
+    fill: string;
+    stroke: string;
+    strokeWidth: number;
+    strokeDasharray: string;
+}
+
+export declare const lightTheme: ScatterplotTheme;
+
+/**
+ * Normalizes raw positions to WebGL space (-1 to 1) with isotropic scaling
+ * Preserves aspect ratio by using the same scale for both X and Y dimensions
+ * @param positions - Float32Array of [x, y, x, y, ...] in data space
+ * @param count - Number of points
+ * @param xMin - Minimum X value in data space
+ * @param xMax - Maximum X value in data space
+ * @param yMin - Minimum Y value in data space
+ * @param yMax - Maximum Y value in data space
+ * @returns New Float32Array with normalized coordinates
+ */
+export declare function normalizePositionsIsotropic(positions: Float32Array, count: number, xMin: number, xMax: number, yMin: number, yMax: number): Float32Array;
+
+export declare type PartialTheme = DeepPartial<ScatterplotTheme>;
+
+/**
+ * Core types for the WebGL scatterplot
+ */
+/**
+ * Represents a single point in the scatterplot
+ */
+export declare interface Point {
+    x: number;
+    y: number;
+    color?: string;
+}
+
+export declare interface PointsTheme {
+    defaultColor: string;
+    size: number;
+    opacity: number;
+    backgroundOpacity: number;
+    highlightBrightness: number;
+    highlightSizeScale: number;
+    unselectedSizeScale: number;
+}
+
+/**
+ * Converts Point[] array to raw position and color buffers
+ * @param data - Array of points with x, y, and optional color properties
+ * @param defaultColor - Default color to use if point has no color. For default, @see {@link DEFAULT_COLOR}
+ * @returns Object containing positions (Float32Array) and colors (Uint8Array)
+ */
+export declare function pointsToBuffers(data: Point[], defaultColor?: string): {
+    positions: Float32Array;
+    colors: Uint8Array;
+};
+
+export declare function Scatterplot({ points: data, width, height, initialCamera, theme, pixelRatio, enableLasso, enablePanZoom, debug, onSelectionChange, lassoRealtimeThreshold, controlled, }: ScatterplotProps): JSX.Element;
+
+export declare function ScatterplotGL({ width, height, positions, colors, debug, pixelRatio, flags, onPointClick, lassoEnabled, onLassoComplete, onLassoUpdate, camera: controlledCamera, onCameraChange, panZoomEnabled, theme, className, }: ScatterplotGLProps): JSX.Element;
+
+/**
+ * Props for the ScatterplotGL component
+ *
+ * @example
+ * ```tsx
+ * <ScatterplotGL
+ *   positions={new Float32Array([0, 0, 1, 1, 2, 0])}
+ *   colors={new Uint8Array([255, 0, 0, 255, 0, 255, 0, 255, 0, 0, 255, 255])}
+ *   width={800}
+ *   height={600}
+ *   onLassoComplete={(indices) => console.log('Selected:', indices)}
+ * />
+ * ```
+ */
+declare interface ScatterplotGLProps {
+    /** Canvas width in CSS pixels (if not provided, fills container) */
+    width?: number;
+    /** Canvas height in CSS pixels (if not provided, fills container) */
+    height?: number;
+    /** Point positions as [x, y, x, y, ...] in data space. Automatically normalized with isotropic scaling. */
+    positions: Float32Array;
+    /** Point colors as [r, g, b, a, ...] in 0-255 range. Hardware-normalized to 0.0-1.0 in shader. */
+    colors: Uint8Array;
+    /** Show debug panel with performance metrics. */
+    debug?: boolean;
+    /** Device pixel ratio for crisp rendering on high-DPI displays. */
+    pixelRatio?: number;
+    /** Flag buffer for selection/highlight state (one byte per point). Use createFlagBuffer() to generate. */
+    flags?: Uint8Array;
+    /** Called when user clicks on or near a point. Receives point index or null if no point nearby. */
+    onPointClick?: (index: number | null) => void;
+    /** Enable lasso selection mode (disables pan/zoom and point click). */
+    lassoEnabled?: boolean;
+    /** Called when lasso selection completes with indices of selected points. */
+    onLassoComplete?: (indices: Set<number>) => void;
+    /** Called during lasso drawing for real-time highlight feedback. */
+    onLassoUpdate?: (indices: Set<number>) => void;
+    /** Current camera state (zoom and pan). If provided, component is controlled. */
+    camera?: Camera;
+    /** Called when camera changes (for controlled mode or to sync state). Supports functional updates. */
+    onCameraChange?: (camera: Camera | ((prev: Camera) => Camera)) => void;
+    /** Enable pan and zoom interactions. */
+    panZoomEnabled?: boolean;
+    /** Theme configuration for styling the scatterplot */
+    theme?: ScatterplotTheme;
+    /** Optional className for the wrapper div */
+    className?: string;
+}
+
+export declare interface ScatterplotProps {
+    /** Data points to visualize */
+    points: Point[];
+    /** Canvas width in pixels (if not provided, fills container). For default, @see {@link DEFAULT_FALLBACK_WIDTH} */
+    width?: number;
+    /** Canvas height in pixels (if not provided, fills container). For default, @see {@link DEFAULT_FALLBACK_HEIGHT} */
+    height?: number;
+    /** Initial camera state (zoom and pan) */
+    initialCamera?: Camera;
+    /** Theme configuration for styling */
+    theme?: ScatterplotTheme;
+    /** Device pixel ratio for high-DPI displays */
+    pixelRatio?: number;
+    /** Enable lasso selection mode */
+    enableLasso?: boolean;
+    /** Enable pan and zoom interactions */
+    enablePanZoom?: boolean;
+    /** Show debug panel with performance metrics */
+    debug?: boolean;
+    /** Callback when selection changes (receives Set of selected point indices) */
+    onSelectionChange?: (indices: Set<number>) => void;
+    /**
+     * Threshold for disabling real-time lasso highlighting.
+     * For default, @see {@link DEFAULT_LASSO_REALTIME_POINTS_THRESHOLD}
+     */
+    lassoRealtimeThreshold?: number;
+    /**
+     * Advanced: Control camera externally
+     * - If provided: fully controlled (parent manages state)
+     * - If omitted: component manages state internally
+     */
+    controlled?: {
+        camera: Camera;
+        onCameraChange?: (camera: Camera | ((prev: Camera) => Camera)) => void;
+    };
+}
+
+export declare interface ScatterplotTheme {
+    canvas: CanvasTheme;
+    points: PointsTheme;
+    lasso: LassoTheme;
+    debug: DebugTheme;
+}
+
+/**
+ * Hook that tracks the size of a container element using ResizeObserver
+ *
+ * Uses requestAnimationFrame to synchronize updates with the browser's
+ * paint cycle. Cancels pending updates when new resize events arrive
+ * to avoid unnecessary re-renders.
+ *
+ * @param containerRef - Ref to the container element to observe
+ * @returns Current width and height of the container
+ */
+export declare function useContainerSize<T extends HTMLElement>(containerRef: RefObject<T | null>): ContainerSize;
+
+/**
+ * Hook for managing point selection state
+ *
+ * @example
+ * ```tsx
+ * const { selectedIndices, handlePointClick } = useSelection();
+ *
+ * <ScatterplotGL
+ *   data={data}
+ *   flags={createFlagBuffer(data.length, selectedIndices)}
+ *   onPointClick={handlePointClick}
+ * />
+ * ```
+ */
+export declare function useSelection(): UseSelectionResult;
+
+/**
+ * Hook for managing point selection state
+ *
+ * Supports both single-point (click) and multi-point (lasso) selection.
+ */
+export declare interface UseSelectionResult {
+    /** Currently selected point indices (Set for efficient lookup) */
+    selectedIndices: Set<number>;
+    /** Handle point click - selects clicked point or clears if clicking empty space */
+    handlePointClick: (index: number | null) => void;
+    /** Set selection to specific indices (used by lasso tool) */
+    setSelection: (indices: Set<number>) => void;
+    /** Clear all selections */
+    clearSelection: () => void;
+    /** Check if a specific index is selected */
+    isSelected: (index: number) => boolean;
+}
+
+export { }

package/dist/scatterplot.css

@@ -0,0 +1 @@
+.scatterplot-lasso-polygon{fill:var(--scatterplot-lasso-fill);stroke:var(--scatterplot-lasso-stroke);stroke-width:var(--scatterplot-lasso-stroke-width);stroke-dasharray:var(--scatterplot-lasso-stroke-dasharray)}.scatterplot-debug-panel{position:absolute;top:10px;right:10px;padding:10px;border-radius:4px;min-width:180px;pointer-events:none;z-index:1000;line-height:1.5;background-color:var(--scatterplot-debug-background);color:var(--scatterplot-debug-color);font-family:var(--scatterplot-debug-font-family);font-size:var(--scatterplot-debug-font-size)}.scatterplot-debug-panel-title{margin-bottom:5px;font-weight:700;color:#fff}