CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a Vue 3 + TypeScript + D3.js waveform visualization component library designed to replace Plotly.js with better performance for large datasets (10,000+ points). The main deliverable is a reusable WaveformChart component with waveform rendering, zoom, tooltip, and controlled point annotations.

Common Commands

# Development
pnpm install          # Install dependencies
pnpm dev              # Start Vite dev server
pnpm typecheck        # Run TypeScript type checking
pnpm lint             # Run ESLint (fails on warnings)
pnpm format           # Format code with Prettier
pnpm test             # Run Vitest unit tests
pnpm build            # Build for production (type-check + build)
pnpm preview          # Preview production build

Architecture

Core Component Structure

The project centers on WaveformChart.vue which provides:

Data flexibility: Accepts either:
- Sample arrays with sample rate: { kind: 'samples', values: number[], sampleRate: number }
- Explicit points: { kind: 'points', points: { x, y }[] }
- Multi-series data: { kind: 'series', series: WaveformSeries[] }
Interactions:
- Zoom and pan when zoomable is enabled
- Hover nearest data points and show tooltip details
- Add, edit, delete, hide and show point annotations
Display modes (via display-mode prop):
- independent - Each series on its own Y-axis
- separated - Series stacked vertically
- compact - All series on shared Y-axis

Data Normalization Flow

All input data flows through normalizeWaveformData() and normalizeWaveformSeries() in waveform.ts:

Converts samples+sampleRate to { x, y } points
Filters out non-finite values
Sorts points by X coordinate
Assigns stable series IDs (use explicit id in multi-channel data)

Multi-Series Coordination

For multi-channel waveforms, each WaveformSeries should have a stable id property. Time coordinates always use seconds; the timeUnit prop only affects display labels.

Annotations are chart-local and parent-controlled through v-model:annotations. They bind to seriesId plus x/y data coordinates; business fields such as frame keys and shot numbers do not belong in the reusable component. Right-clicking anywhere in the plot opens the creation editor and anchors the annotation to the corresponding data position with a connector line; existing annotations keep their edit/delete context menu. Y-axis ticks use one shared scientific exponent when the axis magnitude is below 0.01 or at least 100. Tooltips use localized plain values, while annotation X follows the selected time unit and annotation Y uses full plain decimal text. Raw numeric values remain unchanged.

Key Design Decisions

Performance: D3.js enables rendering 100k+ points smoothly. Component uses Vue's shallowRef for D3 instances to avoid deep reactivity overhead.
Time units: Internal coordinates are always in seconds. The timeUnit prop only controls axis label formatting.
Annotation state: The chart never mutates annotation input arrays. CRUD operations emit new arrays and lifecycle events; persistence remains the responsibility of the parent.
Chinese documentation: Primary documentation is in doc/ folder in Chinese, covering project planning, API design, and integration guides.

File Organization

src/components/WaveformChart.vue - Main component
src/components/waveform.ts - Type definitions and data normalization
src/components/annotation/ - Annotation rendering and interaction components
src/components/index.ts - Public API exports
src/App.vue - Demo application
doc/*.md - Comprehensive Chinese documentation

Testing

Tests are in WaveformChart.test.ts using Vitest + @vue/test-utils. Test setup is in src/test/setup.ts.

When adding features, verify:

Data normalization handles edge cases (empty arrays, NaN values, negative sample rates)
Multi-series with duplicate IDs get auto-generated unique IDs

4.2 KiB Raw Blame History