spectraview 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,504 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as d3_scale from 'd3-scale';
+import { ScaleLinear } from 'd3-scale';
+import { ZoomTransform } from 'd3-zoom';
+
+/**
+ * Core type definitions for SpectraView.
+ *
+ * @module types
+ */
+/** Supported spectral technique types. */
+type SpectrumType = "IR" | "Raman" | "NIR" | "UV-Vis" | "fluorescence" | "other";
+/** A single spectrum dataset. */
+interface Spectrum {
+    /** Unique identifier. */
+    id: string;
+    /** Display label. */
+    label: string;
+    /** X-axis values (wavenumbers, wavelengths, Raman shift, etc.). */
+    x: Float64Array | number[];
+    /** Y-axis values (absorbance, transmittance, intensity, etc.). */
+    y: Float64Array | number[];
+    /** X-axis unit (e.g., "cm⁻¹", "nm"). */
+    xUnit?: string;
+    /** Y-axis unit (e.g., "Absorbance", "Transmittance"). */
+    yUnit?: string;
+    /** Spectral technique type. */
+    type?: SpectrumType;
+    /** Rendering color (CSS color string). */
+    color?: string;
+    /** Whether this spectrum is visible. */
+    visible?: boolean;
+    /** Arbitrary metadata from file headers. */
+    meta?: Record<string, string | number>;
+}
+/** A detected peak in a spectrum. */
+interface Peak {
+    /** X-axis position. */
+    x: number;
+    /** Y-axis position. */
+    y: number;
+    /** Optional display label (e.g., wavenumber annotation). */
+    label?: string;
+    /** Associated spectrum ID. */
+    spectrumId?: string;
+}
+/** A selected x-axis region. */
+interface Region {
+    /** Start X value. */
+    xStart: number;
+    /** End X value. */
+    xEnd: number;
+    /** Optional display label. */
+    label?: string;
+    /** Optional fill color. */
+    color?: string;
+}
+/** Current zoom/pan view state. */
+interface ViewState {
+    /** Visible x-axis domain [min, max]. */
+    xDomain: [number, number];
+    /** Visible y-axis domain [min, max]. */
+    yDomain: [number, number];
+}
+/** Theme configuration. */
+type Theme = "light" | "dark";
+/** Display mode for multiple spectra. */
+type DisplayMode = "overlay";
+/** Margin configuration for the chart area. */
+interface Margin {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+/** Props for the main SpectraView component. */
+interface SpectraViewProps {
+    /** Array of spectra to display. */
+    spectra: Spectrum[];
+    /** Width in pixels. */
+    width?: number;
+    /** Height in pixels. */
+    height?: number;
+    /** Reverse X axis (standard for IR wavenumber). */
+    reverseX?: boolean;
+    /** Show grid lines. */
+    showGrid?: boolean;
+    /** Show crosshair on hover. */
+    showCrosshair?: boolean;
+    /** Show toolbar controls. */
+    showToolbar?: boolean;
+    /** Peak markers to display. */
+    peaks?: Peak[];
+    /** Highlighted regions. */
+    regions?: Region[];
+    /** X-axis label override. */
+    xLabel?: string;
+    /** Y-axis label override. */
+    yLabel?: string;
+    /** Display mode for multiple spectra. */
+    displayMode?: DisplayMode;
+    /** Chart margins. */
+    margin?: Partial<Margin>;
+    /** Theme. */
+    theme?: Theme;
+    /** Custom CSS class name. */
+    className?: string;
+    /** Callback when user clicks a peak marker. */
+    onPeakClick?: (peak: Peak) => void;
+    /** Callback when zoom/pan state changes. */
+    onViewChange?: (view: ViewState) => void;
+    /** Callback when crosshair position changes. */
+    onCrosshairMove?: (x: number, y: number) => void;
+}
+/** Internal resolved configuration (defaults merged with user props). */
+interface ResolvedConfig {
+    width: number;
+    height: number;
+    reverseX: boolean;
+    showGrid: boolean;
+    showCrosshair: boolean;
+    showToolbar: boolean;
+    displayMode: DisplayMode;
+    margin: Margin;
+    theme: Theme;
+}
+
+declare function SpectraView(props: SpectraViewProps): react_jsx_runtime.JSX.Element;
+
+interface SpectrumCanvasProps {
+    /** Spectra to render. */
+    spectra: Spectrum[];
+    /** X-axis scale (already zoomed). */
+    xScale: ScaleLinear<number, number>;
+    /** Y-axis scale (already zoomed). */
+    yScale: ScaleLinear<number, number>;
+    /** Canvas width in pixels. */
+    width: number;
+    /** Canvas height in pixels. */
+    height: number;
+    /** ID of the currently highlighted spectrum. */
+    highlightedId?: string;
+}
+declare function SpectrumCanvas({ spectra, xScale, yScale, width, height, highlightedId, }: SpectrumCanvasProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Default color palette for rendering multiple spectra.
+ *
+ * Colors are chosen for good contrast on both light and dark backgrounds,
+ * and are distinguishable for common forms of color blindness.
+ */
+/** Default spectrum color palette (10 colors). */
+declare const SPECTRUM_COLORS: readonly ["#2563eb", "#dc2626", "#16a34a", "#9333ea", "#ea580c", "#0891b2", "#be185d", "#854d0e", "#4f46e5", "#65a30d"];
+/** Theme color definition. */
+interface ThemeColors {
+    background: string;
+    axisColor: string;
+    gridColor: string;
+    tickColor: string;
+    labelColor: string;
+    crosshairColor: string;
+    regionFill: string;
+    regionStroke: string;
+    tooltipBg: string;
+    tooltipBorder: string;
+    tooltipText: string;
+}
+/** Light theme colors. */
+declare const LIGHT_THEME: ThemeColors;
+/** Dark theme colors. */
+declare const DARK_THEME: ThemeColors;
+/**
+ * Get the color for a spectrum at the given index.
+ *
+ * Cycles through the palette if index exceeds palette length.
+ */
+declare function getSpectrumColor(index: number): string;
+/**
+ * Get theme colors for the given theme name.
+ */
+declare function getThemeColors(theme: "light" | "dark"): ThemeColors;
+
+interface AxisLayerProps {
+    /** X-axis scale (already zoomed). */
+    xScale: ScaleLinear<number, number>;
+    /** Y-axis scale (already zoomed). */
+    yScale: ScaleLinear<number, number>;
+    /** Plot area width (excluding margins). */
+    width: number;
+    /** Plot area height (excluding margins). */
+    height: number;
+    /** X-axis label. */
+    xLabel?: string;
+    /** Y-axis label. */
+    yLabel?: string;
+    /** Show grid lines. */
+    showGrid?: boolean;
+    /** Theme colors. */
+    colors: ThemeColors;
+}
+declare function AxisLayer({ xScale, yScale, width, height, xLabel, yLabel, showGrid, colors, }: AxisLayerProps): react_jsx_runtime.JSX.Element;
+
+interface PeakMarkersProps {
+    /** Peaks to display. */
+    peaks: Peak[];
+    /** X-axis scale (zoomed). */
+    xScale: ScaleLinear<number, number>;
+    /** Y-axis scale (zoomed). */
+    yScale: ScaleLinear<number, number>;
+    /** Theme colors. */
+    colors: ThemeColors;
+    /** Callback when a peak is clicked. */
+    onPeakClick?: (peak: Peak) => void;
+}
+declare function PeakMarkers({ peaks, xScale, yScale, colors, onPeakClick, }: PeakMarkersProps): react_jsx_runtime.JSX.Element;
+
+interface RegionSelectorProps {
+    /** Existing regions to display. */
+    regions: Region[];
+    /** X-axis scale (zoomed). */
+    xScale: ScaleLinear<number, number>;
+    /** Plot area height. */
+    height: number;
+    /** Theme colors. */
+    colors: ThemeColors;
+}
+declare function RegionSelector({ regions, xScale, height, colors, }: RegionSelectorProps): react_jsx_runtime.JSX.Element;
+
+/** Position data for the crosshair. */
+interface CrosshairPosition {
+    /** Pixel x coordinate within the plot area. */
+    px: number;
+    /** Pixel y coordinate within the plot area. */
+    py: number;
+    /** Data-space x value. */
+    dataX: number;
+    /** Data-space y value. */
+    dataY: number;
+}
+interface CrosshairProps {
+    /** Current crosshair position, or null when not hovering. */
+    position: CrosshairPosition | null;
+    /** Plot area width. */
+    width: number;
+    /** Plot area height. */
+    height: number;
+    /** Theme colors. */
+    colors: ThemeColors;
+}
+declare function Crosshair({ position, width, height, colors, }: CrosshairProps): react_jsx_runtime.JSX.Element | null;
+
+interface ToolbarProps {
+    /** Zoom in handler. */
+    onZoomIn: () => void;
+    /** Zoom out handler. */
+    onZoomOut: () => void;
+    /** Reset zoom handler. */
+    onReset: () => void;
+    /** Whether the view is currently zoomed. */
+    isZoomed: boolean;
+    /** Theme. */
+    theme: Theme;
+}
+declare function Toolbar({ onZoomIn, onZoomOut, onReset, isZoomed, theme, }: ToolbarProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Hook for zoom and pan behavior backed by d3-zoom.
+ *
+ * Provides smooth mouse wheel zoom, click-drag pan, and double-click
+ * reset. Works with both the SVG overlay and Canvas data layers.
+ */
+
+interface ZoomPanState {
+    /** Current d3 zoom transform. */
+    transform: ZoomTransform;
+    /** Whether the view is currently zoomed (not at identity). */
+    isZoomed: boolean;
+}
+interface UseZoomPanOptions {
+    /** Width of the plot area (excluding margins). */
+    plotWidth: number;
+    /** Height of the plot area (excluding margins). */
+    plotHeight: number;
+    /** Base x-scale (unzoomed). */
+    xScale: ScaleLinear<number, number>;
+    /** Base y-scale (unzoomed). */
+    yScale: ScaleLinear<number, number>;
+    /** Maximum zoom factor. */
+    scaleExtent?: [number, number];
+    /** Whether zoom/pan is enabled. */
+    enabled?: boolean;
+    /** Callback when the view changes. */
+    onViewChange?: (xDomain: [number, number], yDomain: [number, number]) => void;
+}
+interface UseZoomPanReturn {
+    /** Ref to attach to the interaction overlay element. */
+    zoomRef: React.RefObject<SVGRectElement | null>;
+    /** Current zoom/pan state. */
+    state: ZoomPanState;
+    /** Zoomed (rescaled) x-scale. */
+    zoomedXScale: ScaleLinear<number, number>;
+    /** Zoomed (rescaled) y-scale. */
+    zoomedYScale: ScaleLinear<number, number>;
+    /** Reset zoom to initial view. */
+    resetZoom: () => void;
+    /** Zoom in by a fixed step. */
+    zoomIn: () => void;
+    /** Zoom out by a fixed step. */
+    zoomOut: () => void;
+}
+declare function useZoomPan(options: UseZoomPanOptions): UseZoomPanReturn;
+
+/**
+ * Peak detection for spectral data.
+ *
+ * Uses a simple local-maxima algorithm with prominence filtering,
+ * suitable for identifying peaks in IR, Raman, and NIR spectra.
+ */
+
+interface PeakDetectionOptions {
+    /** Minimum prominence relative to the signal range. */
+    prominence?: number;
+    /** Minimum distance between peaks in data points. */
+    minDistance?: number;
+    /** Maximum number of peaks to return (sorted by prominence). */
+    maxPeaks?: number;
+}
+/**
+ * Detect peaks in a 1D signal using local maxima with prominence filtering.
+ *
+ * @param x - X-axis values (wavenumbers, wavelengths, etc.)
+ * @param y - Y-axis values (absorbance, intensity, etc.)
+ * @param options - Detection parameters
+ * @returns Array of detected peaks sorted by x position
+ */
+declare function detectPeaks(x: Float64Array | number[], y: Float64Array | number[], options?: PeakDetectionOptions): Peak[];
+
+/**
+ * Hook for automatic peak detection in spectral data.
+ *
+ * Wraps the peak detection algorithm with React state management
+ * and recalculates when spectra or options change.
+ */
+
+interface UsePeakPickingOptions extends PeakDetectionOptions {
+    /** Whether peak picking is enabled. */
+    enabled?: boolean;
+    /** Only detect peaks for these spectrum IDs (all if not specified). */
+    spectrumIds?: string[];
+}
+/**
+ * Automatically detect peaks across one or more spectra.
+ *
+ * @param spectra - Array of spectra to analyze
+ * @param options - Peak detection configuration
+ * @returns Array of detected peaks with associated spectrum IDs
+ */
+declare function usePeakPicking(spectra: Spectrum[], options?: UsePeakPickingOptions): Peak[];
+
+/**
+ * Hook for managing spectrum data loading and state.
+ *
+ * Handles file loading (drag-and-drop, file input), parsing,
+ * and managing the collection of loaded spectra.
+ */
+
+interface UseSpectrumDataReturn {
+    /** Currently loaded spectra. */
+    spectra: Spectrum[];
+    /** Whether a file is currently being loaded. */
+    loading: boolean;
+    /** Last error message, if any. */
+    error: string | null;
+    /** Load spectra from a File object (detects format from extension). */
+    loadFile: (file: File) => Promise<void>;
+    /** Load spectra from a raw text string with explicit format. */
+    loadText: (text: string, format: "jcamp" | "csv" | "json") => Promise<void>;
+    /** Add a spectrum directly. */
+    addSpectrum: (spectrum: Spectrum) => void;
+    /** Remove a spectrum by ID. */
+    removeSpectrum: (id: string) => void;
+    /** Toggle a spectrum's visibility. */
+    toggleVisibility: (id: string) => void;
+    /** Clear all loaded spectra. */
+    clear: () => void;
+}
+/**
+ * Hook for loading and managing spectral data.
+ */
+declare function useSpectrumData(initialSpectra?: Spectrum[]): UseSpectrumDataReturn;
+
+/**
+ * Hook for exporting the spectrum view as PNG, SVG, or CSV data.
+ */
+
+interface UseExportReturn {
+    /** Export the canvas as a PNG data URL. */
+    exportPng: (canvas: HTMLCanvasElement, filename?: string) => void;
+    /** Export visible spectra as CSV text. */
+    exportCsv: (spectra: Spectrum[], filename?: string) => void;
+    /** Export visible spectra as JSON. */
+    exportJson: (spectra: Spectrum[], filename?: string) => void;
+}
+/**
+ * Hook for exporting spectrum data and visualizations.
+ */
+declare function useExport(): UseExportReturn;
+
+/**
+ * JCAMP-DX parser for spectral data.
+ *
+ * Wraps the `jcampconverter` npm package (optional peer dependency)
+ * to parse .dx, .jdx, and .jcamp files into Spectrum objects.
+ *
+ * If jcampconverter is not installed, a lightweight built-in parser
+ * handles basic AFFN (ASCII Free Format Numeric) JCAMP-DX files.
+ */
+
+/**
+ * Parse a JCAMP-DX string into Spectrum objects.
+ *
+ * Uses jcampconverter if available, otherwise falls back to the built-in
+ * parser for basic AFFN format files.
+ *
+ * @param text - Raw JCAMP-DX file content
+ * @returns Array of parsed Spectrum objects
+ */
+declare function parseJcamp(text: string): Promise<Spectrum[]>;
+
+/**
+ * CSV/TSV parser for spectral data.
+ *
+ * Handles comma, tab, and semicolon delimiters with automatic detection.
+ * Supports files with or without header rows.
+ */
+
+interface CsvParseOptions {
+    /** Column delimiter (auto-detected if not provided). */
+    delimiter?: string;
+    /** Zero-based index of the x-value column. */
+    xColumn?: number;
+    /** Zero-based index of the y-value column. */
+    yColumn?: number;
+    /** Whether the first row is a header. */
+    hasHeader?: boolean;
+    /** Label for the parsed spectrum. */
+    label?: string;
+}
+/**
+ * Parse a CSV/TSV string into a Spectrum object.
+ *
+ * @param text - Raw CSV/TSV text content
+ * @param options - Parsing configuration
+ * @returns Parsed Spectrum
+ * @throws Error if the data cannot be parsed
+ */
+declare function parseCsv(text: string, options?: CsvParseOptions): Spectrum;
+/**
+ * Parse a CSV string containing multiple y-columns into multiple spectra.
+ *
+ * The first column is treated as x-values, and each subsequent column
+ * becomes a separate spectrum.
+ */
+declare function parseCsvMulti(text: string, options?: Omit<CsvParseOptions, "xColumn" | "yColumn">): Spectrum[];
+
+/**
+ * JSON parser for spectral data.
+ *
+ * Supports multiple JSON formats commonly used for spectral data exchange.
+ */
+
+/**
+ * Parse a JSON string into one or more Spectrum objects.
+ *
+ * Handles both single spectrum objects and arrays of spectra.
+ * Supports flexible key names (x/wavenumbers, y/intensities, etc.).
+ *
+ * @param text - Raw JSON string
+ * @returns Array of parsed Spectrum objects
+ * @throws Error if the JSON cannot be parsed or has invalid structure
+ */
+declare function parseJson(text: string): Spectrum[];
+
+/**
+ * Compute the x-axis extent across all visible spectra.
+ */
+declare function computeXExtent(spectra: Spectrum[]): [number, number];
+/**
+ * Compute the y-axis extent across all visible spectra with padding.
+ */
+declare function computeYExtent(spectra: Spectrum[]): [number, number];
+/**
+ * Create an x-axis scale.
+ *
+ * When `reverseX` is true, the domain is reversed so higher wavenumbers
+ * appear on the left (standard IR convention).
+ */
+declare function createXScale(domain: [number, number], width: number, margin: Margin, reverseX: boolean): d3_scale.ScaleLinear<number, number, never>;
+/**
+ * Create a y-axis scale (always low values at bottom, high at top).
+ */
+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 };