path: root/plans.md

# Bibiman Development Plans

This document outlines the planned features and improvements for bibiman, organized by priority and implementation complexity.

## 0. Cleanup UI

- Edit title line to take up less space - integrate 'BIBIMAN' into same line as 'Bibliolographic Entries'
- Change keywords section to be authors, sorted by num articles descending. (I guess configure this optionally).
- Change (optionally) author section to show first & last author last names. Maybe show first/middle name initials also? That's becoming a different project at that point perhaps. `Scholten ... Tetienne` for authors?
- Would be nice to also have pgup/down do what ctrl+u/d do now.
- Can we make more things 'click-able'?

## 1. Dynamic Column Configuration

### Overview
Allow users to fully customize the entry table columns through configuration, replacing the current hardcoded column structure.

### Goals
- **Flexibility**: Users can choose which fields to display and in what order
- **Performance**: Maintain current speed through pre-computed display data
- **Simplicity**: Easy-to-understand configuration format
- **Backward Compatibility**: Graceful handling of existing configs

### Design

#### Configuration Structure
```toml
[[entry_table_columns]]
title = "Author"
field = "authors"
width = "25%"

[[entry_table_columns]]
title = "Title"
field = "title"
width = "fill"

[[entry_table_columns]]
title = "Year"
field = "year"
width = "6"

[[entry_table_columns]]
title = "Res."
field = "symbols"
width = "auto"
```

#### Available Fields
- **Basic**: `authors`, `title`, `year`, `citekey`, `keywords`
- **Extended**: `journaltitle`, `organization`, `institution`, `series`, `publisher`, `pubtype`
- **Special**: `symbols` (resource indicators), `subtitle`, `doi_url`

#### Width Options
- `"fill"` - Takes remaining space (like current Title column)
- `"auto"` - Fits content automatically based on longest entry
- `"15"` - Fixed width in characters
- `"20%"` - Percentage of total table width

#### Implementation Plan

1. **Config Layer** (`src/config.rs`)
   - Add `ColumnDefinition` struct with `title`, `field`, `width` fields
   - Add `entry_table_columns: Vec<ColumnDefinition>` to `General` config
   - Implement width parsing (`"20%"` → percentage, `"15"` → fixed, etc.)
   - Provide sensible defaults matching current behavior
   - Add deprecation warning for `custom_column` field

2. **Data Layer** (`src/bibiman/bibisetup.rs`)
   - Modify `BibiData` to support dynamic field access
   - Replace `BibiRow` struct with `Vec<Text>` for dynamic columns
   - Add `get_field_content(field: &str) -> Text` method with explicit match statement
   - Pre-compute all display data based on configured columns

3. **UI Layer** (`src/tui/ui.rs`)
   - Refactor `render_entrytable()` to build table dynamically
   - Generate constraints from column width specifications
   - Build headers from column titles with sort indicators
   - Handle special cases (symbol column width calculation, sort adjustments)

4. **Sorting** (`src/bibiman/entries.rs`)
   - Replace `EntryTableColumn` enum with string-based field names
   - Update sorting logic to use field names instead of enum variants
   - Maintain sort state with field name strings

### Migration Strategy
- Detect `custom_column` in existing configs and show deprecation warning
- Provide automatic conversion suggestion or maintain backward compatibility
- Default column configuration matches current hardcoded behavior exactly

---

## 2. Duplicate Key Handling (Issue #52)

### Overview
Resolve crashes when loading multiple bib files containing entries with duplicate citekeys, enabling cross-project search workflows.

### Problem
- Current implementation concatenates all bib files and parses as one
- `biblatex` crate strictly enforces unique citekeys per BibLaTeX standard
- Application crashes immediately when duplicates found
- Prevents users from searching across multiple project files

### Solution Design

#### Core Approach
1. **Parse files individually** instead of concatenating
2. **Implement "first wins" deduplication** - keep first occurrence of duplicate citekeys
3. **Track source files** for transparency and debugging
4. **Provide clear user feedback** about duplicates found

#### Implementation Plan

1. **Parsing Changes** (`src/bibiman/bibisetup.rs`)
   - Modify `BibiSetup::new()` to parse each file separately
   - Collect entries from all files into single list
   - Implement duplicate detection after parsing
   - Keep first occurrence, discard subsequent duplicates

2. **Source Tracking**
   - Add `source_file: PathBuf` field to `BibiData` struct
   - Track which file each entry originated from
   - Display source in entry info panel: `"Source: project1.bib"`

3. **User Feedback**
   - Show non-blocking warning when duplicates found
   - Display count: `"Found 5 duplicate entries, kept first occurrence"`
   - Optional: Show which specific citekeys were duplicated
   - Log detailed information for debugging

4. **Configuration Options** (future)
   ```toml
   [general]
   duplicate_handling = "first_wins"  # or "last_wins", "error"
   show_duplicate_warnings = true
   show_source_in_info = true
   ```

#### Benefits
- **Enables cross-project workflows** - users can search all their bib files
- **Predictable behavior** - first file loaded wins for duplicates
- **Non-destructive** - original files remain unchanged
- **Transparent** - users know which version they're seeing
- **Robust** - no more crashes from duplicate keys

---

## 3. Bibliography Management Features

### Overview
Transform bibiman from a bibliography viewer into a comprehensive bibliography manager with editing, export, and project management capabilities.

### Planned Features

#### 3.1 Citekey Management
- **Pattern-based regeneration**: User-defined templates for consistent citekeys
- **Automatic deduplication**: Add suffixes for duplicates (`smith2023a`, `smith2023b`)
- **Batch operations**: Regenerate citekeys for entire collections
- **Validation**: Check for problematic characters, ensure uniqueness

Example configuration:
```toml
[citekey_patterns]
default = "{author_last}{year}{title_word}"
article = "{author_last}{year}{journal_short}"
book = "{author_last}_{year}_{title_short}"
```

#### 3.2 Export and Combination
- **Merge multiple files** into single clean output
- **Export filtered results** - save search/filter results as new .bib file
- **Split operations** - separate by criteria (year, journal, keywords, project)
- **Clean exports** - remove duplicates, fix formatting, validate required fields
- **Format options** - different BibLaTeX styles, field ordering

#### 3.3 Project Management
- **Project configurations** - predefined sets of bib files
- **Quick switching** between project contexts
- **Import/export** between projects
- **Shared libraries** - common files across projects

Example configuration:
```toml
[projects]
main_library = ["/path/to/main.bib"]
current_project = ["/path/to/project1.bib", "/path/to/shared.bib"]
thesis = ["/path/to/thesis.bib", "/path/to/main.bib"]
```

#### 3.4 Entry Editing and Creation
- **Enhanced DOI import** - expand current feature with more metadata sources
- **Manual entry creation** - forms for different entry types
- **In-place editing** - modify existing entries directly
- **Bulk operations** - update multiple entries (keywords, authors, formatting)
- **Field validation** - ensure required fields, proper formatting

#### 3.5 Advanced Workflows
- **Backup system** - automatic backups before modifications
- **Undo/redo** - revert changes safely
- **Preview mode** - see changes before writing to files
- **Batch find/replace** - across fields and entries
- **Git integration** - track changes in version control
- **Import from other formats** - EndNote, Zotero, etc.

### Implementation Priority
1. **Citekey regeneration** - builds on duplicate handling work
2. **Basic export/merge** - high user value, moderate complexity
3. **Entry editing** - expand current DOI feature
4. **Project management** - configuration-heavy but valuable
5. **Advanced workflows** - power-user features

### Technical Considerations
- **File safety** - always backup before modifications
- **Performance** - maintain speed even with large collections
- **Error handling** - robust validation and recovery
- **User experience** - clear feedback and confirmation for destructive operations

---

## Implementation Timeline

### Phase 1: Core Improvements (Immediate)
1. **Dynamic Column Configuration** - Major UI flexibility improvement
2. **Duplicate Key Handling** - Fixes existing pain point, enables new workflows

### Phase 2: Management Features (Medium-term)
1. **Citekey Regeneration** - Builds on duplicate handling infrastructure
2. **Basic Export/Merge** - High-value feature for multi-file workflows
3. **Enhanced Entry Creation** - Expand current DOI functionality

### Phase 3: Advanced Features (Long-term)
1. **Project Management** - Configuration and workflow improvements
2. **Advanced Editing** - Bulk operations, validation, etc.
3. **Integration Features** - Git, backup systems, import/export

---

## Design Principles

Throughout all implementations, maintain these core principles:

- **Performance First** - Keep bibiman fast and responsive
- **Simple Configuration** - Easy-to-understand config options
- **Robust Error Handling** - Graceful failures with clear messages
- **Non-destructive Operations** - Always preserve original data
- **Terminal-focused Workflow** - Maintain the TUI-first approach
- **Backward Compatibility** - Don't break existing user setups