trentuna/candle-annotator
8
0
Fork 0
Code Issues Pull requests Releases Packages Activity Actions

chore: archive both OpenSpec changes and sync specs to main

Browse source
This commit is contained in:
Marko Djordjevic 2026-02-12 17:56:25 +01:00
parent a6e763c153
commit 50229e2ccf
25 changed files with 927 additions and 1 deletions
Download patch file Download diff file Expand all files Collapse all files

70
openspec/specs/annotation-tools/spec.md Normal file
View file

@ -0,0 +1,70 @@
## ADDED Requirements
### Requirement: Active tool mode
The system SHALL maintain an "active tool" state that determines what happens when the user clicks on the chart. Available tool modes are: "select" (default, no action on click), "break_up" (label Break Up), "break_down" (label Break Down), "line" (draw trend line), and "delete" (remove annotation). Only one tool SHALL be active at a time.
#### Scenario: Tool activation
- **WHEN** user clicks a tool button in the sidebar
- **THEN** that tool becomes the active tool and the button appears visually selected
#### Scenario: Tool deactivation
- **WHEN** user clicks the already-active tool button
- **THEN** the tool deactivates and the mode returns to "select"
### Requirement: Break Up labeling
When the "break_up" tool is active and the user clicks on the chart, the system SHALL identify the nearest candle to the click coordinates using `chart.timeScale().coordinateToTime()`. The system SHALL save an annotation with `label_type: "break_up"` and the candle's timestamp to the database. A green upward arrow marker SHALL appear on the chart immediately.
#### Scenario: Place Break Up label
- **WHEN** "break_up" tool is active and user clicks on a candle
- **THEN** system saves a "break_up" annotation for that candle's timestamp and displays a green arrow marker above the bar
#### Scenario: Click between candles
- **WHEN** "break_up" tool is active and user clicks between two candles
- **THEN** system snaps to the nearest candle timestamp and places the annotation there
### Requirement: Break Down labeling
When the "break_down" tool is active and the user clicks on the chart, the system SHALL behave identically to Break Up labeling but save `label_type: "break_down"` and display a red downward arrow below the bar.
#### Scenario: Place Break Down label
- **WHEN** "break_down" tool is active and user clicks on a candle
- **THEN** system saves a "break_down" annotation for that candle's timestamp and displays a red arrow marker below the bar
### Requirement: Two-click line drawing
When the "line" tool is active, the system SHALL implement a two-click drawing interaction. The first click sets the start point (time, price). The second click sets the end point (time, price). After the second click, the system SHALL save an annotation with `label_type: "line"` and `geometry` containing JSON: `{"startTime": <unix>, "startPrice": <float>, "endTime": <unix>, "endPrice": <float>}`. The line SHALL render immediately on the SVG overlay.
#### Scenario: Draw a trend line
- **WHEN** "line" tool is active and user clicks two points on the chart
- **THEN** system saves a line annotation with start/end coordinates and renders the line on the overlay
#### Scenario: Visual feedback during line drawing
- **WHEN** "line" tool is active and user has clicked the first point but not the second
- **THEN** system displays a preview line from the first point to the current cursor position
#### Scenario: Cancel line drawing
- **WHEN** user presses Escape during a two-click line drawing (after first click)
- **THEN** system cancels the line drawing and clears the preview without saving
### Requirement: Delete annotation
When the "delete" tool is active and the user clicks on or near an existing annotation (marker or line), the system SHALL remove that annotation from the database and update the chart display immediately.
#### Scenario: Delete a marker annotation
- **WHEN** "delete" tool is active and user clicks on a candle that has a marker annotation
- **THEN** system removes the annotation from the database and the marker disappears from the chart
#### Scenario: Delete a line annotation
- **WHEN** "delete" tool is active and user clicks near an existing line on the overlay
- **THEN** system removes the line annotation from the database and the line disappears from the overlay
### Requirement: Coordinate mapping
The system SHALL convert mouse click pixel coordinates to chart data coordinates (time and price) using the lightweight-charts API: `chart.timeScale().coordinateToTime(x)` for time and `series.coordinateToPrice(y)` for price. For point annotations, the time SHALL be snapped to the nearest candle timestamp.
#### Scenario: Pixel to data coordinate conversion
- **WHEN** user clicks at pixel position (x, y) on the chart
- **THEN** system correctly converts to the corresponding time and price values using the chart API
### Requirement: Annotations database table
The system SHALL store annotations in an `annotations` table with columns: `id` (integer primary key, auto-increment), `timestamp` (integer, Unix timestamp referencing a candle time), `label_type` (text: "break_up", "break_down", or "line"), `geometry` (text, nullable, JSON string for line coordinates), `created_at` (integer, Unix timestamp of creation).
#### Scenario: Schema structure
- **WHEN** the database is initialized
- **THEN** the `annotations` table exists with all required columns