spectraview 1.8.0 → 1.8.2

package/CHANGELOG.md

@@ -5,6 +5,211 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/),
 and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [1.8.2] — 2026-02-26
+
+### Added
+
+- ESLint 9 flat config with TypeScript, React, and React Hooks rules
+- Test coverage reporting in CI with PR comments and dynamic badge
+- Tests for StackedView (8), useExport (9), useResizeObserver (8) — 25 new tests
+- Coverage badge in README
+
+### Fixed
+
+- `Tooltip.tsx`: React rules-of-hooks violation (early return before useMemo)
+- `spc.ts`: `let` → `const` for single-assignment variable
+- README: `pip install spectrakit` → `pip install pyspectrakit`
+
+## [1.8.1] — 2026-02-26
+
+### Added
+
+- 9 new Storybook stories: Legend, AnnotationLayer, DataTable, DropZone, ExportMenu, Minimap, Tooltip, StackedView, SpectrumCanvas (15 total, 100% component coverage)
+- `.prettierrc` and `.editorconfig` for consistent formatting
+- `SECURITY.md` with vulnerability reporting policy
+- `.github/FUNDING.yml` for GitHub Sponsors
+- GitHub issue templates (bug report, feature request)
+- Pull request template with checklist
+
+### Changed
+
+- CHANGELOG.md now documents all versions 0.1.0 through 1.8.0
+- CONTRIBUTING.md updated: pnpm → npm, added Storybook development section
+- CITATION.cff version updated to 1.8.0 with new keywords
+- Removed empty `demo/` and `paper/` directories
+
+## [1.8.0] — 2026-02-26
+
+### Changed
+
+- Added npm keywords for better discoverability (SPC, canvas, d3, peak-detection, baseline-correction, savitzky-golay, normalization)
+- Updated README with comprehensive API documentation covering all v1.x features
+
+## [1.7.0] — 2026-02-26
+
+### Added
+
+- `DataTable` component — sortable tabular view of spectrum data with region highlighting
+- `spectrumToCsv()` — single spectrum CSV export with range filtering, delimiter, and precision options
+- `multiSpectraToCsv()` — multi-spectrum CSV with shared X column
+- `spectrumToJson()` — JSON export with range filtering
+- `downloadString()` — browser file download trigger utility
+
+## [1.6.0] — 2026-02-26
+
+### Added
+
+- `useHistory` hook — generic undo/redo with configurable max depth
+- Command pattern: `push()`, `undo()`, `redo()`, `reset()`, `canUndo`, `canRedo`
+
+## [1.5.0] — 2026-02-26
+
+### Added
+
+- `useNormalization` hook — reactive spectral transformations for in-viewer processing
+- Supports 7 modes: none, min-max, area, SNV, baseline, smooth, derivative
+- Memoized transformation pipeline
+
+## [1.4.0] — 2026-02-26
+
+### Added
+
+- `Tooltip` component — multi-spectrum hover tooltip with nearest peak indicator
+- Binary search for O(log n) value lookup at cursor position
+- Configurable number format (auto, fixed2, fixed4, scientific)
+- Smart positioning to avoid clipping at plot edges
+
+## [1.3.0] — 2026-02-26
+
+### Added
+
+- `differenceSpectrum()` — element-wise subtraction (A − B)
+- `addSpectra()` — element-wise addition (A + B)
+- `scaleSpectrum()` — scalar multiplication
+- `correlationCoefficient()` — Pearson correlation coefficient
+- `residualSpectrum()` — absolute difference |A − B|
+- `interpolateToGrid()` — linear interpolation to align spectra on a common X grid
+
+## [1.2.0] — 2026-02-26
+
+### Added
+
+- `Minimap` component — canvas-rendered overview navigator with SVG viewport overlay
+- Dims areas outside the visible viewport when zoomed
+- Decimated rendering for performance at any data size
+
+## [1.1.0] — 2026-02-26
+
+### Added
+
+- `baselineRubberBand()` — rubber-band baseline correction via lower convex hull
+- `normalizeMinMax()` — scale Y values to [0, 1]
+- `normalizeArea()` — area normalization using trapezoidal integration
+- `normalizeSNV()` — Standard Normal Variate normalization
+- `smoothSavitzkyGolay()` — Savitzky-Golay smoothing with pre-computed coefficients (windows 5–11)
+- `derivative1st()` — first derivative via central differences
+- `derivative2nd()` — second derivative via central differences
+
+## [1.0.0] — 2026-02-26
+
+### Added
+
+- `parseSpc()` — SPC binary format parser (Thermo/Galactic .spc files)
+- Supports single and multi-spectrum SPC files
+- Handles 16-bit integer and 32-bit float Y data
+- Automatic X/Y unit label detection from SPC type codes
+
+### Changed
+
+- Stable public API — first major release
+
+## [0.9.0] — 2026-02-26
+
+### Added
+
+- `lttbDownsample()` — Largest-Triangle-Three-Buckets downsampling algorithm
+
+### Changed
+
+- Replaced min-max decimation with LTTB in canvas rendering for better visual fidelity
+- Wrapped `Toolbar` and `Legend` in `React.memo` for performance
+
+### Removed
+
+- `decimateMinMax()` internal function (replaced by LTTB)
+
+## [0.8.0] — 2026-02-26
+
+### Added
+
+- `AnnotationLayer` component — text annotations with anchor dots and optional anchor lines
+- `binarySearchClosest()` — O(log n) binary search for sorted arrays (ascending and descending)
+- `snapToNearestSpectrum()` — finds nearest data point across all spectra in pixel space
+- `snapCrosshair` prop on `<SpectraView />` — crosshair snaps to nearest data point (default: true)
+- `annotations` prop on `<SpectraView />` — render text annotations on the chart
+- `Annotation` type in core types
+
+### Changed
+
+- `Crosshair` component now renders a snap dot with spectrum color when snapped
+
+## [0.7.0] — 2026-02-26
+
+### Added
+
+- `useKeyboardNavigation` hook — keyboard shortcuts: +/= zoom in, − zoom out, Esc reset
+- `generateChartDescription()` — generates ARIA-friendly chart descriptions
+- `prefersReducedMotion()` — detect reduced motion preference
+- `KEYBOARD_SHORTCUTS` constant for discoverability
+- ARIA attributes on `<SpectraView />`: `role="img"`, `aria-label`, `tabIndex`
+
+## [0.6.0] — 2026-02-25
+
+### Added
+
+- `ExportMenu` component — dropdown menu with PNG, SVG, CSV, JSON export options
+- `generateSvg()` — programmatic SVG export of chart
+- `downloadSvg()` — trigger SVG file download
+- `LINE_DASH_PATTERNS` — dash patterns for solid, dashed, dotted, dash-dot line styles
+- `LineStyle` type and `lineStyle` / `lineWidth` properties on `Spectrum`
+
+## [0.5.0] — 2026-02-25
+
+### Added
+
+- `StackedView` component — vertically separated panels for multi-spectrum display
+- `displayMode` prop: `"overlay"` (default) or `"stacked"`
+- `responsive` prop — auto-sizes component to fill container width
+- `useResizeObserver` hook — container size observation
+
+## [0.4.0] — 2026-02-25
+
+### Added
+
+- `DropZone` component — drag-and-drop file loading overlay
+- `RegionSelector` component — interactive Shift+drag region selection
+- `useRegionSelect` hook — handles region selection state and callbacks
+- `enableDragDrop`, `onFileDrop`, `enableRegionSelect`, `onRegionSelect` props
+
+## [0.3.0] — 2026-02-25
+
+### Added
+
+- `Legend` component — spectrum list with color swatches, visibility toggles, hover highlight
+- `showLegend` and `legendPosition` props on `<SpectraView />`
+- `onToggleVisibility` callback for spectrum hide/show
+- Auto-shown when more than one spectrum is displayed
+
+## [0.1.1] — 2026-02-25
+
+### Fixed
+
+- Counter-based clipPath IDs replaced with `useId()` to avoid collisions with multiple instances
+- Canvas decimation for large datasets
+- Export `ref` forwarding to internal canvas element
+- CJS type resolution with split `.d.cts` declarations
+- CI switched from pnpm to npm
+
 ## [0.1.0] — 2026-02-25
 
 ### Added

package/README.md

@@ -7,22 +7,34 @@ Interactive React component for vibrational spectroscopy (IR, Raman, NIR).
 [![bundle size](https://img.shields.io/bundlephobia/minzip/spectraview)](https://bundlephobia.com/package/spectraview)
 [![license](https://img.shields.io/npm/l/spectraview)](https://github.com/ktubhyam/spectraview/blob/main/LICENSE)
 [![CI](https://img.shields.io/github/actions/workflow/status/ktubhyam/spectraview/ci.yml?branch=main)](https://github.com/ktubhyam/spectraview/actions)
+[![coverage](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/ktubhyam/spectraview/coverage-badges/coverage.json)](https://github.com/ktubhyam/spectraview/actions/workflows/ci.yml)
 [![Storybook](https://img.shields.io/badge/storybook-deployed-ff4785)](https://ktubhyam.github.io/spectraview/)
 
 ## Features
 
-- **High-performance rendering** — Canvas 2D for spectral data (10K+ points at 60fps), SVG for axes and annotations
-- **Zoom and pan** — Mouse wheel zoom, click-drag pan, double-click reset
+- **High-performance rendering** — Canvas 2D with LTTB downsampling (10K+ points at 60fps), SVG for axes and annotations
+- **Zoom and pan** — Mouse wheel zoom, click-drag pan, double-click reset, keyboard shortcuts (+/−/Esc)
 - **Reversed x-axis** — Standard IR wavenumber convention (high → low)
 - **Peak detection** — Automatic peak picking with prominence filtering
-- **Region selection** — Click-drag to highlight wavenumber regions
-- **Multi-format loading** — JCAMP-DX, CSV/TSV, JSON
-- **Multi-spectrum overlay** — Compare spectra with automatic color assignment
-- **Crosshair** — Hover readout with coordinate display
-- **Export** — PNG image, CSV data, JSON
+- **Snap crosshair** — Hover readout that snaps to nearest data point with spectrum color indicator
+- **Region selection** — Shift+drag to select wavenumber regions interactively
+- **Annotations** — Positioned text labels with anchor lines on the chart
+- **Multi-format parsing** — JCAMP-DX, CSV/TSV, JSON, and SPC (Thermo/Galactic binary)
+- **Multi-spectrum overlay** — Compare spectra with automatic color assignment and legend
+- **Stacked display** — View multiple spectra in vertically separated panels
+- **Spectral processing** — Baseline correction (rubber-band), normalization (min-max, area, SNV), Savitzky-Golay smoothing, 1st/2nd derivatives
+- **Spectrum comparison** — Difference, addition, scaling, Pearson correlation, residuals, grid interpolation
+- **Export** — PNG, SVG, CSV, JSON with range filtering and precision control
+- **Data table** — Sortable tabular view of spectrum values with region highlighting
+- **Minimap** — Overview navigator showing viewport position within full spectrum
+- **Tooltip** — Multi-spectrum hover tooltip with nearest peak indicator
+- **Undo/redo** — Generic history hook for state management
+- **Drag-and-drop** — Built-in drop zone for loading spectrum files
+- **Responsive** — Optional auto-sizing to fill container width
+- **Accessible** — ARIA labels, keyboard navigation, screen reader support
 - **Themes** — Light and dark mode
 - **TypeScript** — Full type definitions included
-- **Tiny bundle** — ~50-70KB min+gzip (no Plotly dependency)
+- **Tiny bundle** — ~48KB ESM / ~51KB CJS (no Plotly dependency)
 
 ## Installation
 
@@ -51,26 +63,36 @@ function App() {
 
 ## Loading Files
 
+SpectraView supports drag-and-drop file loading out of the box:
+
 ```tsx
-import { useSpectrumData, SpectraView } from "spectraview";
+import { SpectraView, useSpectrumData } from "spectraview";
 
 function App() {
   const { spectra, loadFile } = useSpectrumData();
 
-  const handleDrop = (e: React.DragEvent) => {
-    e.preventDefault();
-    const file = e.dataTransfer.files[0];
-    if (file) loadFile(file);
-  };
-
   return (
-    <div onDrop={handleDrop} onDragOver={(e) => e.preventDefault()}>
-      <SpectraView spectra={spectra} reverseX showCrosshair />
-    </div>
+    <SpectraView
+      spectra={spectra}
+      reverseX
+      enableDragDrop
+      onFileDrop={(files) => files.forEach(loadFile)}
+    />
   );
 }
 ```
 
+Or parse files manually:
+
+```ts
+import { parseJcamp, parseCsv, parseJson, parseSpc } from "spectraview";
+
+const spectra = await parseJcamp(jcampText);   // JCAMP-DX (.dx, .jdx)
+const spectrum = parseCsv(csvText);             // CSV/TSV
+const spectra = parseJson(jsonText);            // JSON
+const spectra = parseSpc(arrayBuffer);           // SPC binary (.spc)
+```
+
 ## Peak Detection
 
 ```tsx
@@ -95,6 +117,98 @@ function App() {
 }
 ```
 
+## Spectral Processing
+
+Apply common preprocessing transformations:
+
+```ts
+import {
+  baselineRubberBand,
+  normalizeMinMax,
+  normalizeArea,
+  normalizeSNV,
+  smoothSavitzkyGolay,
+  derivative1st,
+  derivative2nd,
+} from "spectraview";
+
+const corrected = baselineRubberBand(spectrum.y);    // Rubber-band baseline correction
+const normed = normalizeMinMax(spectrum.y);           // Scale to [0, 1]
+const areaNormed = normalizeArea(spectrum.x, spectrum.y); // Unit area normalization
+const snv = normalizeSNV(spectrum.y);                 // Standard Normal Variate
+const smoothed = smoothSavitzkyGolay(spectrum.y, 7);  // SG smoothing (window=7)
+const dy = derivative1st(spectrum.x, spectrum.y);     // 1st derivative
+const d2y = derivative2nd(spectrum.x, spectrum.y);    // 2nd derivative
+```
+
+Or use the `useNormalization` hook for reactive transformations:
+
+```tsx
+import { useNormalization, SpectraView } from "spectraview";
+
+function App() {
+  const [mode, setMode] = useState("none");
+  const { spectra: processed, modeLabel } = useNormalization({
+    spectra: rawSpectra,
+    mode, // "none" | "min-max" | "area" | "snv" | "baseline" | "smooth" | "derivative"
+  });
+
+  return <SpectraView spectra={processed} reverseX />;
+}
+```
+
+## Spectrum Comparison
+
+```ts
+import {
+  differenceSpectrum,
+  addSpectra,
+  scaleSpectrum,
+  correlationCoefficient,
+  residualSpectrum,
+  interpolateToGrid,
+} from "spectraview";
+
+const diff = differenceSpectrum(spectrumA, spectrumB);  // A - B
+const sum = addSpectra(spectrumA, spectrumB);            // A + B
+const scaled = scaleSpectrum(spectrum, 2.5);             // Scale Y by factor
+const r = correlationCoefficient(spectrumA, spectrumB);  // Pearson r ∈ [-1, 1]
+const resid = residualSpectrum(spectrumA, spectrumB);    // |A - B|
+
+// Align spectra to a common X grid before comparison
+const aligned = interpolateToGrid(spectrumB, spectrumA.x);
+```
+
+## Data Export
+
+```ts
+import {
+  spectrumToCsv,
+  multiSpectraToCsv,
+  spectrumToJson,
+  downloadString,
+  generateSvg,
+  downloadSvg,
+} from "spectraview";
+
+// CSV export with options
+const csv = spectrumToCsv(spectrum, {
+  delimiter: ",",
+  precision: 4,
+  xRange: [1000, 2000],
+  includeHeader: true,
+});
+
+// Multi-spectrum CSV (shared X column)
+const multiCsv = multiSpectraToCsv([spectrumA, spectrumB]);
+
+// JSON export
+const json = spectrumToJson(spectrum, { xRange: [1000, 2000] });
+
+// Trigger browser download
+downloadString(csv, "spectrum.csv", "text/csv");
+```
+
 ## API Reference
 
 ### `<SpectraView />`
@@ -108,31 +222,73 @@ function App() {
 | `showGrid` | `boolean` | `true` | Show grid lines |
 | `showCrosshair` | `boolean` | `true` | Show hover crosshair |
 | `showToolbar` | `boolean` | `true` | Show zoom controls |
+| `showLegend` | `boolean` | `true` | Show spectrum legend |
+| `legendPosition` | `"top" \| "bottom"` | `"bottom"` | Legend placement |
+| `displayMode` | `"overlay" \| "stacked"` | `"overlay"` | Multi-spectrum display mode |
+| `responsive` | `boolean` | `false` | Auto-size to container width |
+| `theme` | `"light" \| "dark"` | `"light"` | Color theme |
 | `peaks` | `Peak[]` | `[]` | Peak markers to display |
 | `regions` | `Region[]` | `[]` | Highlighted regions |
-| `xLabel` | `string` | auto | X-axis label |
-| `yLabel` | `string` | auto | Y-axis label |
-| `theme` | `"light" \| "dark"` | `"light"` | Color theme |
+| `annotations` | `Annotation[]` | `[]` | Text annotations on the chart |
+| `snapCrosshair` | `boolean` | `true` | Snap crosshair to nearest data point |
+| `xLabel` | `string` | auto | X-axis label override |
+| `yLabel` | `string` | auto | Y-axis label override |
+| `margin` | `Partial<Margin>` | — | Custom chart margins |
+| `enableDragDrop` | `boolean` | `false` | Enable drag-and-drop file loading |
+| `enableRegionSelect` | `boolean` | `false` | Enable Shift+drag region selection |
+| `className` | `string` | — | Custom CSS class |
+| `canvasRef` | `RefObject<HTMLCanvasElement>` | — | Ref to canvas element (for export) |
 | `onPeakClick` | `(peak: Peak) => void` | — | Peak click callback |
-| `onViewChange` | `(view: ViewState) => void` | — | Zoom/pan callback |
-| `onCrosshairMove` | `(x, y) => void` | — | Crosshair move callback |
+| `onViewChange` | `(view: ViewState) => void` | — | Zoom/pan change callback |
+| `onCrosshairMove` | `(x: number, y: number) => void` | — | Crosshair move callback |
+| `onToggleVisibility` | `(id: string) => void` | — | Legend visibility toggle callback |
+| `onFileDrop` | `(files: File[]) => void` | — | File drop callback |
+| `onRegionSelect` | `(region: Region) => void` | — | Region selection callback |
 
-### Parsers
+### Sub-Components
 
-```ts
-import { parseJcamp, parseCsv, parseJson } from "spectraview";
+For advanced composition, individual layers are exported:
 
-const spectra = await parseJcamp(jcampText);  // JCAMP-DX (.dx, .jdx)
-const spectrum = parseCsv(csvText);            // CSV/TSV
-const spectra = parseJson(jsonText);           // JSON
+```tsx
+import {
+  SpectrumCanvas,
+  AxisLayer,
+  PeakMarkers,
+  RegionSelector,
+  Crosshair,
+  Toolbar,
+  Legend,
+  DropZone,
+  AnnotationLayer,
+  Minimap,
+  Tooltip,
+  DataTable,
+  StackedView,
+  ExportMenu,
+} from "spectraview";
 ```
 
 ### Hooks
 
-- **`useSpectrumData()`** — File loading and spectrum state management
-- **`useZoomPan(options)`** — Zoom/pan behavior backed by d3-zoom
-- **`usePeakPicking(spectra, options)`** — Automatic peak detection
-- **`useExport()`** — PNG, CSV, JSON export functions
+| Hook | Description |
+|------|-------------|
+| `useSpectrumData()` | File loading and spectrum state management |
+| `useZoomPan(options)` | Zoom/pan behavior backed by d3-zoom |
+| `usePeakPicking(spectra, options)` | Automatic peak detection |
+| `useExport()` | PNG, CSV, JSON export functions |
+| `useRegionSelect(options)` | Interactive Shift+drag region selection |
+| `useResizeObserver()` | Container resize observation for responsive sizing |
+| `useKeyboardNavigation(options)` | Keyboard shortcuts (+/−/Esc for zoom/reset) |
+| `useNormalization(options)` | Reactive spectral normalization/processing |
+| `useHistory(options)` | Generic undo/redo with configurable depth |
+
+### Keyboard Shortcuts
+
+| Key | Action |
+|-----|--------|
+| `+` or `=` | Zoom in |
+| `-` | Zoom out |
+| `Escape` | Reset zoom |
 
 ## Companion: SpectraKit (Python)
 
@@ -142,7 +298,7 @@ SpectraView pairs with [SpectraKit](https://github.com/ktubhyam/spectrakit), a P
 - **SpectraView** — View spectra: interactive visualization in the browser
 
 ```
-pip install spectrakit    # Process in Python
+pip install pyspectrakit  # Process in Python
 npm install spectraview   # View in the browser
 ```