candle-annotator/openspec/specs/label-management/spec.md

ADDED Requirements

Requirement: Select label by clicking marker

The system SHALL allow users to select label annotations by clicking on their marker symbols on the chart.

Scenario: Click on break_up marker

• WHEN user clicks on a green arrow (break_up) marker on the chart
• THEN system sets selectedLabelId state to the annotation ID, highlights the marker with increased size and glow effect, and scrolls to the label in the sidebar list

Scenario: Click on break_down marker

• WHEN user clicks on a red arrow (break_down) marker on the chart
• THEN system sets selectedLabelId state to the annotation ID, highlights the marker with increased size and glow effect, and scrolls to the label in the sidebar list

Scenario: Click already selected marker

• WHEN user clicks on a marker that is already selected
• THEN system deselects the marker by setting selectedLabelId to null and removes highlight effects

Scenario: Click different marker while one is selected

• WHEN user clicks on a different marker while another marker is already selected
• THEN system deselects the previous marker, selects the new marker, and updates the highlight to the new marker

Scenario: Tool mode during label selection

• WHEN user selects a label marker
• THEN selection works regardless of active tool (works in all modes: none, line, delete, break_up, break_down)

Requirement: Delete selected label with keyboard

The system SHALL allow users to delete the currently selected label annotation using keyboard shortcuts.

Scenario: Delete selected label with Delete key

• WHEN a label is selected (selectedLabelId is set) and user presses Delete key
• THEN system sends DELETE request to /api/annotations/{id}, removes marker from display, clears selection state, and triggers annotation refresh

Scenario: Delete selected label with Backspace key

• WHEN a label is selected and user presses Backspace key
• THEN system sends DELETE request to /api/annotations/{id}, removes marker from display, clears selection state, and triggers annotation refresh

Scenario: No label selected when pressing delete

• WHEN no label is selected (selectedLabelId is null) and user presses Delete or Backspace key
• THEN system takes no action on labels (may still delete selected line if line is selected)

Requirement: Label list in sidebar

The Toolbox SHALL display a collapsible section showing all label annotations for the active chart with interactive controls.

Scenario: Display label list section

• WHEN Toolbox renders with an active chart selected
• THEN system displays "Label Annotations" section below the annotation tools with collapse/expand toggle button, showing only annotations belonging to the active chart

Scenario: Label list expanded

• WHEN "Label Annotations" section is expanded
• THEN system displays scrollable list of label annotations for the active chart sorted by timestamp (newest first), with each entry showing timestamp, label type badge, and delete button

Scenario: Label list collapsed

• WHEN user clicks collapse button on "Label Annotations" section
• THEN system hides the label list but shows count summary "Labels: X break_up, Y break_down" for the active chart

Scenario: Empty label list

• WHEN no label annotations exist for the active chart
• THEN section displays message "No labels yet. Click Break Up or Break Down tools to add labels."

Scenario: Label entry format

• WHEN displaying a label in the list
• THEN each entry shows formatted timestamp (e.g., "Feb 12, 14:30"), colored badge ("BREAK UP" in green or "BREAK DOWN" in red), and trash icon delete button

Scenario: Label list updates on chart switch

• WHEN user switches to a different chart via the chart selector
• THEN the label list clears and reloads with annotations belonging to the newly selected chart

Requirement: Click label in list to select on chart

The system SHALL allow users to click a label in the sidebar list to select and highlight it on the chart.

Scenario: Click label entry in sidebar

• WHEN user clicks on a label entry in the sidebar list
• THEN system sets selectedLabelId to that annotation ID, highlights the corresponding marker on chart, and centers the chart view on that timestamp

Scenario: Click already selected label in list

• WHEN user clicks on a label entry that is already selected
• THEN system deselects the label by setting selectedLabelId to null and removes highlights

Scenario: Selected label visual in list

• WHEN a label is selected
• THEN the corresponding entry in the sidebar list has a highlighted background and border

Requirement: Delete label from sidebar

The system SHALL provide delete buttons for each label in the sidebar list.

Scenario: Click delete button for label

• WHEN user clicks trash icon button next to a label in the sidebar
• THEN system sends DELETE request to /api/annotations/{id}, removes label from list and chart, clears selection if that label was selected, and triggers annotation refresh

Scenario: Delete button styling

• WHEN displaying delete buttons in label list
• THEN buttons use red/destructive color on hover and show tooltip "Delete this label"

Requirement: Search and filter labels

The Toolbox label section SHALL provide search and filter controls.

Scenario: Filter by label type

• WHEN user selects filter dropdown and chooses "Break Up"
• THEN system displays only break_up annotations in the list

Scenario: Filter by label type - Break Down

• WHEN user selects filter dropdown and chooses "Break Down"
• THEN system displays only break_down annotations in the list

Scenario: Show all labels

• WHEN user selects filter dropdown and chooses "All"
• THEN system displays all label annotations regardless of type

Scenario: Search by timestamp

• WHEN user types text into search input field
• THEN system filters list to show only labels whose formatted timestamp contains the search text (case-insensitive)

Scenario: Combined search and filter

• WHEN user has both search text and type filter active
• THEN system shows labels that match both criteria (AND logic)

Requirement: Label count display

The Toolbox SHALL display counts of each label type for the active chart.

Scenario: Display label counts

• WHEN Toolbox renders and labels exist for the active chart
• THEN system displays count summary "Break Up: X | Break Down: Y" at top of label section, reflecting only the active chart's annotations

Scenario: Zero labels

• WHEN no labels exist for the active chart
• THEN count summary displays "Break Up: 0 | Break Down: 0"

Scenario: Count updates after delete

• WHEN user deletes a label from the active chart
• THEN count summary updates immediately to reflect the new totals

Scenario: Counts update on chart switch

• WHEN user switches to a different chart
• THEN count summary updates to reflect the new chart's label counts

Requirement: Delete all labels with confirmation

The system SHALL provide a "Delete All Labels" button with confirmation dialog. The deletion SHALL only affect labels belonging to the active chart.

Scenario: Click Delete All Labels button

• WHEN user clicks "Delete All Labels" button in Toolbox
• THEN system displays confirmation dialog with message "Delete all label annotations for this chart (Break Up and Break Down)? This cannot be undone." and Cancel/Confirm buttons

Scenario: User confirms delete all labels

• WHEN confirmation dialog is open and user clicks Confirm button
• THEN system deletes only label annotations belonging to the active chart, removes all label markers from chart, clears label list, clears selection state, triggers annotation refresh, and closes dialog

Scenario: User cancels delete all labels

• WHEN confirmation dialog is open and user clicks Cancel button
• THEN system closes dialog without making any API calls or removing any labels

Scenario: Delete All Labels button visibility

• WHEN one or more label annotations exist
• THEN "Delete All Labels" button is enabled with destructive styling
• WHEN no label annotations exist
• THEN "Delete All Labels" button is disabled with reduced opacity

Requirement: API support for label operations

The API SHALL support filtering and bulk deletion of label annotations.

Scenario: Delete all break_up labels

• WHEN DELETE request sent to /api/annotations?type=break_up
• THEN system deletes all annotations where label_type equals 'break_up' and returns { success: true, deleted: <count> }

Scenario: Delete all break_down labels

• WHEN DELETE request sent to /api/annotations?type=break_down
• THEN system deletes all annotations where label_type equals 'break_down' and returns { success: true, deleted: <count> }

Scenario: Delete multiple types at once

• WHEN DELETE request sent to /api/annotations?type=break_up,break_down
• THEN system deletes all annotations where label_type is either 'break_up' or 'break_down' and returns { success: true, deleted: <count> }

Scenario: Get labels with type filter

• WHEN GET request sent to /api/annotations?type=break_up
• THEN system returns only annotations where label_type equals 'break_up'