@helioviewer/event-tree/CLAUDE.md

A react component for grouping and listing and selecting solar events.

# CLAUDE.md

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

## Overview

This is a React component package `@helioviewer/event-tree` that provides a hierarchical tree interface for browsing, selecting, and managing solar events from various sources (HEK, CCMC, RHESSI, etc.). The component fetches event data from the Helioviewer API and displays it in an interactive tree structure with checkboxes for selection.

## Development Commands

Since this is a React component library package, there are no build, test, or development server commands configured. The package.json only includes:

```bash
npm test  # Currently returns error - no tests configured
```

## Architecture

### Core Components

- **HelioviewerEventTree** (`src/HelioviewerEventTree.jsx`): Main component that orchestrates the event tree functionality
- **EventTree** (`src/Core/EventTree.jsx`): Core data structure class that manages the hierarchical event tree state
- **API** (`src/Core/API.jsx`): Handles API communication with Helioviewer endpoints
- **Cache** (`src/Core/Cache.jsx`): Manages localStorage for user selections and preferences

### UI Components

- **Node** (`src/Node.jsx`): Renders individual tree nodes with expand/collapse functionality
- **SourceHeader** (`src/SourceHeader.jsx`): Top-level header for event sources with controls
- **Checkbox** (`src/Checkbox.jsx`): Custom checkbox component for selections
- **NodeLabel** (`src/NodeLabel.jsx`): Labels for tree nodes
- **Icons** (`src/Icons.jsx`): Collection of SVG icons used throughout the component

### Data Flow

1. **Event Fetching**: API.jsx fetches events from `https://api.helioviewer.org` with date and source parameters
2. **Tree Structure**: EventTree.jsx converts flat event data into hierarchical tree structure with parent-child relationships
3. **State Management**: Component maintains selection state, expand/collapse state, and loading state
4. **Caching**: Cache.jsx persists user selections and preferences in localStorage with source-specific keys
5. **Selection Logic**: Three-state checkboxes (checked/unchecked/undecided) with parent-child propagation

### Key Features

- **Hierarchical Selection**: Selecting parent nodes selects all children; mixed selections show "undecided" state
- **Expand/Collapse**: Tree nodes can be expanded/collapsed to show/hide children
- **Empty Branch Filtering**: Option to show/hide branches with no events
- **Hover Events**: Provides hover feedback for event highlighting
- **Persistent State**: User selections and preferences are saved to localStorage
- **Abort Controller**: Proper cleanup of API requests on component unmount

## API Integration

The component expects events data in a specific nested format:
- Top level: sources array
- Second level: groups with nested structure
- Leaf level: data array containing actual events

Each event should have properties like `id`, `label`, `short_label` for display.

## State Management

The EventTree class uses immutable patterns - operations return new instances rather than mutating existing state. Selection state propagates both up (to parents) and down (to children) the tree hierarchy.