spectraview 0.1.0 → 1.0.0

package/dist/index.d.cts

@@ -1,4 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
+import { ReactNode } from 'react';
 import * as d3_scale from 'd3-scale';
 import { ScaleLinear } from 'd3-scale';
 import { ZoomTransform } from 'd3-zoom';
@@ -10,6 +12,8 @@ import { ZoomTransform } from 'd3-zoom';
  */
 /** Supported spectral technique types. */
 type SpectrumType = "IR" | "Raman" | "NIR" | "UV-Vis" | "fluorescence" | "other";
+/** Supported line styles for spectrum rendering. */
+type LineStyle = "solid" | "dashed" | "dotted" | "dash-dot";
 /** A single spectrum dataset. */
 interface Spectrum {
     /** Unique identifier. */
@@ -28,6 +32,10 @@ interface Spectrum {
     type?: SpectrumType;
     /** Rendering color (CSS color string). */
     color?: string;
+    /** Line style for rendering. */
+    lineStyle?: LineStyle;
+    /** Line width in pixels. */
+    lineWidth?: number;
     /** Whether this spectrum is visible. */
     visible?: boolean;
     /** Arbitrary metadata from file headers. */
@@ -55,6 +63,25 @@ interface Region {
     /** Optional fill color. */
     color?: string;
 }
+/** A text annotation placed on the chart. */
+interface Annotation {
+    /** Unique identifier. */
+    id: string;
+    /** Data-space x position (anchor point). */
+    x: number;
+    /** Data-space y position (anchor point). */
+    y: number;
+    /** Annotation text. */
+    text: string;
+    /** Pixel offset from anchor point [dx, dy]. Defaults to [0, -20]. */
+    offset?: [number, number];
+    /** Font size in pixels. Defaults to 11. */
+    fontSize?: number;
+    /** Text color (CSS). Defaults to theme text color. */
+    color?: string;
+    /** Show anchor line from text to data point. Defaults to true. */
+    showAnchorLine?: boolean;
+}
 /** Current zoom/pan view state. */
 interface ViewState {
     /** Visible x-axis domain [min, max]. */
@@ -65,7 +92,9 @@ interface ViewState {
 /** Theme configuration. */
 type Theme = "light" | "dark";
 /** Display mode for multiple spectra. */
-type DisplayMode = "overlay";
+type DisplayMode = "overlay" | "stacked";
+/** Legend position relative to the chart. */
+type LegendPosition$1 = "top" | "bottom" | "left" | "right";
 /** Margin configuration for the chart area. */
 interface Margin {
     top: number;
@@ -93,6 +122,10 @@ interface SpectraViewProps {
     peaks?: Peak[];
     /** Highlighted regions. */
     regions?: Region[];
+    /** Text annotations to display on the chart. */
+    annotations?: Annotation[];
+    /** Snap crosshair to nearest spectrum data point. Defaults to true. */
+    snapCrosshair?: boolean;
     /** X-axis label override. */
     xLabel?: string;
     /** Y-axis label override. */
@@ -103,8 +136,26 @@ interface SpectraViewProps {
     margin?: Partial<Margin>;
     /** Theme. */
     theme?: Theme;
+    /** Show legend (auto-shown when >1 spectrum). */
+    showLegend?: boolean;
+    /** Legend position. */
+    legendPosition?: LegendPosition$1;
+    /** Callback when a spectrum's visibility is toggled via legend. */
+    onToggleVisibility?: (id: string) => void;
+    /** Enable drag-and-drop file loading. */
+    enableDragDrop?: boolean;
+    /** Callback when files are dropped. */
+    onFileDrop?: (files: File[]) => void;
+    /** Enable interactive region selection (Shift+drag). */
+    enableRegionSelect?: boolean;
+    /** Callback when a region is created. */
+    onRegionSelect?: (region: Region) => void;
+    /** Responsive sizing (fills container width). */
+    responsive?: boolean;
     /** Custom CSS class name. */
     className?: string;
+    /** Ref to access the underlying Canvas element (for export). */
+    canvasRef?: React.RefObject<HTMLCanvasElement | null>;
     /** Callback when user clicks a peak marker. */
     onPeakClick?: (peak: Peak) => void;
     /** Callback when zoom/pan state changes. */
@@ -120,9 +171,14 @@ interface ResolvedConfig {
     showGrid: boolean;
     showCrosshair: boolean;
     showToolbar: boolean;
+    showLegend: boolean;
+    legendPosition: LegendPosition$1;
     displayMode: DisplayMode;
     margin: Margin;
     theme: Theme;
+    responsive: boolean;
+    enableDragDrop: boolean;
+    enableRegionSelect: boolean;
 }
 
 declare function SpectraView(props: SpectraViewProps): react_jsx_runtime.JSX.Element;
@@ -141,7 +197,7 @@ interface SpectrumCanvasProps {
     /** ID of the currently highlighted spectrum. */
     highlightedId?: string;
 }
-declare function SpectrumCanvas({ spectra, xScale, yScale, width, height, highlightedId, }: SpectrumCanvasProps): react_jsx_runtime.JSX.Element;
+declare const SpectrumCanvas: react.ForwardRefExoticComponent<SpectrumCanvasProps & react.RefAttributes<HTMLCanvasElement>>;
 
 /**
  * Default color palette for rendering multiple spectra.
@@ -237,6 +293,19 @@ interface CrosshairPosition {
     /** Data-space y value. */
     dataY: number;
 }
+/** Snap point data for rendering a snap dot on the nearest spectrum. */
+interface SnapPoint {
+    /** Pixel x of the snapped data point. */
+    px: number;
+    /** Pixel y of the snapped data point. */
+    py: number;
+    /** Data-space x value. */
+    dataX: number;
+    /** Data-space y value. */
+    dataY: number;
+    /** Color of the spectrum (for dot fill). */
+    color?: string;
+}
 interface CrosshairProps {
     /** Current crosshair position, or null when not hovering. */
     position: CrosshairPosition | null;
@@ -246,8 +315,10 @@ interface CrosshairProps {
     height: number;
     /** Theme colors. */
     colors: ThemeColors;
+    /** Optional snap point on nearest spectrum. */
+    snapPoint?: SnapPoint | null;
 }
-declare function Crosshair({ position, width, height, colors, }: CrosshairProps): react_jsx_runtime.JSX.Element | null;
+declare function Crosshair({ position, width, height, colors, snapPoint, }: CrosshairProps): react_jsx_runtime.JSX.Element | null;
 
 interface ToolbarProps {
     /** Zoom in handler. */
@@ -261,7 +332,53 @@ interface ToolbarProps {
     /** Theme. */
     theme: Theme;
 }
-declare function Toolbar({ onZoomIn, onZoomOut, onReset, isZoomed, theme, }: ToolbarProps): react_jsx_runtime.JSX.Element;
+declare const Toolbar: react.NamedExoticComponent<ToolbarProps>;
+
+/** Position for the legend relative to the chart. */
+type LegendPosition = "top" | "bottom" | "left" | "right";
+interface LegendProps {
+    /** Spectra to list in the legend. */
+    spectra: Spectrum[];
+    /** Theme for styling. */
+    theme: Theme;
+    /** Legend position. */
+    position: LegendPosition;
+    /** Callback when a spectrum's visibility is toggled. */
+    onToggleVisibility?: (id: string) => void;
+    /** Callback when hovering a spectrum in the legend. */
+    onHighlight?: (id: string | null) => void;
+    /** Currently highlighted spectrum ID. */
+    highlightedId?: string | null;
+}
+declare const Legend: react.NamedExoticComponent<LegendProps>;
+
+interface DropZoneProps {
+    /** Whether drag-drop is enabled. */
+    enabled: boolean;
+    /** Theme for styling the overlay. */
+    theme: Theme;
+    /** Width of the drop zone. */
+    width: number;
+    /** Height of the drop zone. */
+    height: number;
+    /** Callback when files are dropped. */
+    onDrop?: (files: File[]) => void;
+    /** Children to render inside the drop zone. */
+    children: ReactNode;
+}
+declare function DropZone({ enabled, theme, width, height, onDrop, children, }: DropZoneProps): react_jsx_runtime.JSX.Element;
+
+interface AnnotationLayerProps {
+    /** Annotations to render. */
+    annotations: Annotation[];
+    /** X scale (zoomed). */
+    xScale: ScaleLinear<number, number>;
+    /** Y scale (zoomed). */
+    yScale: ScaleLinear<number, number>;
+    /** Theme colors. */
+    colors: ThemeColors;
+}
+declare function AnnotationLayer({ annotations, xScale, yScale, colors, }: AnnotationLayerProps): react_jsx_runtime.JSX.Element | null;
 
 /**
  * Hook for zoom and pan behavior backed by d3-zoom.
@@ -396,6 +513,8 @@ declare function useSpectrumData(initialSpectra?: Spectrum[]): UseSpectrumDataRe
 interface UseExportReturn {
     /** Export the canvas as a PNG data URL. */
     exportPng: (canvas: HTMLCanvasElement, filename?: string) => void;
+    /** Export visible spectra as SVG vector. */
+    exportSvg: (spectra: Spectrum[], xScale: ScaleLinear<number, number>, yScale: ScaleLinear<number, number>, width: number, height: number, filename?: string) => void;
     /** Export visible spectra as CSV text. */
     exportCsv: (spectra: Spectrum[], filename?: string) => void;
     /** Export visible spectra as JSON. */
@@ -406,6 +525,222 @@ interface UseExportReturn {
  */
 declare function useExport(): UseExportReturn;
 
+/**
+ * Hook for interactive region selection via Shift+drag.
+ *
+ * Tracks mouse drag state when Shift is held, converting pixel
+ * coordinates to data-space values using the provided x-scale.
+ */
+
+interface UseRegionSelectOptions {
+    /** Whether region selection is enabled. */
+    enabled: boolean;
+    /** X-axis scale for pixel-to-data conversion. */
+    xScale: ScaleLinear<number, number>;
+    /** Callback when a region is created. */
+    onRegionSelect?: (region: Region) => void;
+}
+interface UseRegionSelectReturn {
+    /** Pending region being dragged (null when not dragging). */
+    pendingRegion: Region | null;
+    /** Mouse down handler — call on the interaction rect. */
+    handleMouseDown: (event: React.MouseEvent<SVGRectElement>) => void;
+    /** Mouse move handler — call on the interaction rect. */
+    handleMouseMove: (event: React.MouseEvent<SVGRectElement>) => void;
+    /** Mouse up handler — call on the interaction rect. */
+    handleMouseUp: () => void;
+}
+declare function useRegionSelect(options: UseRegionSelectOptions): UseRegionSelectReturn;
+
+/**
+ * Hook for responsive sizing via ResizeObserver.
+ *
+ * Tracks the width (and optionally height) of a container element,
+ * enabling the chart to auto-size to its parent.
+ */
+interface ResizeObserverSize {
+    width: number;
+    height: number;
+}
+declare function useResizeObserver(): {
+    ref: React.RefCallback<HTMLElement>;
+    size: ResizeObserverSize | null;
+};
+
+/**
+ * Hook for keyboard navigation within the spectrum viewer.
+ *
+ * Handles arrow keys for panning, +/- for zoom, Escape for reset.
+ */
+interface UseKeyboardNavigationOptions {
+    /** Zoom in handler. */
+    onZoomIn: () => void;
+    /** Zoom out handler. */
+    onZoomOut: () => void;
+    /** Reset zoom handler. */
+    onReset: () => void;
+    /** Whether keyboard navigation is enabled. */
+    enabled?: boolean;
+}
+declare function useKeyboardNavigation(options: UseKeyboardNavigationOptions): (event: React.KeyboardEvent) => void;
+
+interface StackedViewProps {
+    /** Spectra to display. */
+    spectra: Spectrum[];
+    /** Zoomed x-scale (shared across panels). */
+    xScale: ScaleLinear<number, number>;
+    /** Full plot width. */
+    plotWidth: number;
+    /** Full plot height (will be divided among panels). */
+    plotHeight: number;
+    /** Chart margins. */
+    margin: Margin;
+    /** Theme. */
+    theme: Theme;
+    /** Show grid lines. */
+    showGrid: boolean;
+    /** X-axis label. */
+    xLabel: string;
+    /** Y-axis label. */
+    yLabel: string;
+}
+declare function StackedView({ spectra, xScale, plotWidth, plotHeight, margin, theme, showGrid, xLabel, yLabel, }: StackedViewProps): react_jsx_runtime.JSX.Element;
+
+interface ExportMenuProps {
+    /** Theme for styling. */
+    theme: Theme;
+    /** Export as PNG. */
+    onExportPng?: () => void;
+    /** Export as SVG. */
+    onExportSvg?: () => void;
+    /** Export as CSV. */
+    onExportCsv?: () => void;
+    /** Export as JSON. */
+    onExportJson?: () => void;
+}
+declare function ExportMenu({ theme, onExportPng, onExportSvg, onExportCsv, onExportJson, }: ExportMenuProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * SVG export utility for generating publication-quality vector figures.
+ *
+ * Serializes a chart's SVG element to a standalone SVG string with
+ * embedded spectral data paths.
+ */
+
+/** Line dash patterns for different line styles. */
+declare const LINE_DASH_PATTERNS: Record<string, string>;
+interface SvgExportOptions {
+    /** Width of the SVG. */
+    width: number;
+    /** Height of the SVG. */
+    height: number;
+    /** Background color. */
+    background?: string;
+    /** Title text for the SVG. */
+    title?: string;
+}
+/**
+ * Generate an SVG string for the given spectra.
+ */
+declare function generateSvg(spectra: Spectrum[], xScale: ScaleLinear<number, number>, yScale: ScaleLinear<number, number>, options: SvgExportOptions): string;
+/**
+ * Download an SVG string as a file.
+ */
+declare function downloadSvg(svg: string, filename?: string): void;
+
+/**
+ * Accessibility utilities for SpectraView.
+ *
+ * Provides helpers for reduced motion detection, ARIA label generation,
+ * and keyboard navigation constants.
+ */
+/** Check if the user prefers reduced motion. */
+declare function prefersReducedMotion(): boolean;
+/** Generate an accessible description for a spectrum chart. */
+declare function generateChartDescription(spectrumCount: number, xLabel: string, yLabel: string): string;
+/** Keyboard shortcut definitions. */
+declare const KEYBOARD_SHORTCUTS: {
+    readonly PAN_LEFT: "ArrowLeft";
+    readonly PAN_RIGHT: "ArrowRight";
+    readonly PAN_UP: "ArrowUp";
+    readonly PAN_DOWN: "ArrowDown";
+    readonly ZOOM_IN: "+";
+    readonly ZOOM_IN_ALT: "=";
+    readonly ZOOM_OUT: "-";
+    readonly RESET: "Escape";
+    readonly NEXT_PEAK: "Tab";
+    readonly PREV_PEAK: "Shift+Tab";
+};
+
+/**
+ * Binary search utilities for snapping crosshair to nearest spectrum data.
+ *
+ * Given a cursor x-position, finds the closest data point on visible spectra
+ * using binary search for O(log n) performance.
+ */
+
+/** Result of a snap-to-spectrum search. */
+interface SnapResult {
+    /** Spectrum ID of the closest match. */
+    spectrumId: string;
+    /** Index within the spectrum's data arrays. */
+    index: number;
+    /** Data-space x value of the snapped point. */
+    x: number;
+    /** Data-space y value of the snapped point. */
+    y: number;
+    /** Pixel distance from cursor to the snapped point. */
+    distance: number;
+}
+/**
+ * Binary search for the index of the closest x-value in a sorted array.
+ *
+ * Works with both ascending and descending arrays.
+ * Returns the index of the element closest to `target`.
+ */
+declare function binarySearchClosest(arr: Float64Array | number[], target: number, length: number): number;
+/**
+ * Find the nearest data point across all visible spectra to a given
+ * data-space x position. Uses pixel-space distance for ranking.
+ */
+declare function snapToNearestSpectrum(spectra: Spectrum[], dataX: number, cursorPy: number, xScale: (v: number) => number, yScale: (v: number) => number): SnapResult | null;
+
+/**
+ * Largest-Triangle-Three-Buckets (LTTB) downsampling algorithm.
+ *
+ * LTTB produces visually superior downsampled representations compared to
+ * simple min-max binning. It works by dividing data into buckets and
+ * selecting the point in each bucket that forms the largest triangle with
+ * the selected points in adjacent buckets.
+ *
+ * Reference: Sveinn Steinarsson, "Downsampling Time Series for Visual
+ * Representation" (2013).
+ *
+ * @module lttb
+ */
+/** A downsampled point with its original index. */
+interface LTTBPoint {
+    /** Pixel x coordinate. */
+    px: number;
+    /** Pixel y coordinate. */
+    py: number;
+    /** Original index in the source arrays. */
+    index: number;
+}
+/**
+ * Downsample data using the LTTB algorithm.
+ *
+ * @param x - Source x-values
+ * @param y - Source y-values
+ * @param startIdx - Start index (inclusive) in the source arrays
+ * @param endIdx - End index (exclusive) in the source arrays
+ * @param xScale - Function mapping data x to pixel x
+ * @param yScale - Function mapping data y to pixel y
+ * @param targetCount - Desired number of output points
+ * @returns Array of downsampled points
+ */
+declare function lttbDownsample(x: Float64Array | number[], y: Float64Array | number[], startIdx: number, endIdx: number, xScale: (v: number) => number, yScale: (v: number) => number, targetCount: number): LTTBPoint[];
+
 /**
  * JCAMP-DX parser for spectral data.
  *
@@ -481,6 +816,32 @@ declare function parseCsvMulti(text: string, options?: Omit<CsvParseOptions, "xC
  */
 declare function parseJson(text: string): Spectrum[];
 
+/**
+ * SPC file parser for Thermo/Galactic spectral data format.
+ *
+ * Parses the binary SPC format used by GRAMS, Thermo Scientific,
+ * PerkinElmer, and other spectroscopy software.
+ *
+ * Supports:
+ * - Single and multi-spectrum files
+ * - Even and uneven X spacing
+ * - 32-bit float and 16-bit integer Y data
+ * - File header metadata (resolution, instrument, etc.)
+ *
+ * Reference: "The New Galactic SPC File Format" specification
+ *
+ * @module spc
+ */
+
+/**
+ * Parse an SPC binary file into Spectrum objects.
+ *
+ * @param buffer - ArrayBuffer containing the SPC file data
+ * @returns Array of parsed Spectrum objects
+ * @throws Error if the file is not a valid SPC file
+ */
+declare function parseSpc(buffer: ArrayBuffer): Spectrum[];
+
 /**
  * Compute the x-axis extent across all visible spectra.
  */
@@ -501,4 +862,4 @@ declare function createXScale(domain: [number, number], width: number, margin: M
  */
 declare function createYScale(domain: [number, number], height: number, margin: Margin): d3_scale.ScaleLinear<number, number, never>;
 
-export { AxisLayer, Crosshair, type CrosshairPosition, type CrosshairProps, type CsvParseOptions, DARK_THEME, type DisplayMode, LIGHT_THEME, type Margin, type Peak, type PeakDetectionOptions, PeakMarkers, type Region, RegionSelector, type ResolvedConfig, SPECTRUM_COLORS, SpectraView, type SpectraViewProps, type Spectrum, SpectrumCanvas, type SpectrumType, type Theme, Toolbar, type UseExportReturn, type UsePeakPickingOptions, type UseSpectrumDataReturn, type UseZoomPanOptions, type UseZoomPanReturn, type ViewState, type ZoomPanState, computeXExtent, computeYExtent, createXScale, createYScale, detectPeaks, getSpectrumColor, getThemeColors, parseCsv, parseCsvMulti, parseJcamp, parseJson, useExport, usePeakPicking, useSpectrumData, useZoomPan };
+export { type Annotation, AnnotationLayer, type AnnotationLayerProps, AxisLayer, Crosshair, type CrosshairPosition, type CrosshairProps, type CsvParseOptions, DARK_THEME, type DisplayMode, DropZone, type DropZoneProps, ExportMenu, type ExportMenuProps, KEYBOARD_SHORTCUTS, LIGHT_THEME, LINE_DASH_PATTERNS, type LTTBPoint, Legend, type LegendPosition$1 as LegendPosition, type LegendProps, type LineStyle, type Margin, type Peak, type PeakDetectionOptions, PeakMarkers, type Region, RegionSelector, type ResolvedConfig, SPECTRUM_COLORS, type SnapPoint, type SnapResult, SpectraView, type SpectraViewProps, type Spectrum, SpectrumCanvas, type SpectrumType, StackedView, type SvgExportOptions, type Theme, Toolbar, type UseExportReturn, type UseKeyboardNavigationOptions, type UsePeakPickingOptions, type UseRegionSelectOptions, type UseRegionSelectReturn, type UseSpectrumDataReturn, type UseZoomPanOptions, type UseZoomPanReturn, type ViewState, type ZoomPanState, binarySearchClosest, computeXExtent, computeYExtent, createXScale, createYScale, detectPeaks, downloadSvg, generateChartDescription, generateSvg, getSpectrumColor, getThemeColors, lttbDownsample, parseCsv, parseCsvMulti, parseJcamp, parseJson, parseSpc, prefersReducedMotion, snapToNearestSpectrum, useExport, useKeyboardNavigation, usePeakPicking, useRegionSelect, useResizeObserver, useSpectrumData, useZoomPan };