Bibliotheca/docs/Feature-Tagging.md

Feature: Tagging

Status: Implemented

This document describes the tagging feature in Bibliotheca.

1. Database Schema

The database schema includes two tables for tagging support.

• A tags table stores all available tags.

  CREATE TABLE IF NOT EXISTS tags (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  name TEXT NOT NULL UNIQUE
  );
  

• A book_tags junction table associates tags with books.

  CREATE TABLE IF NOT EXISTS book_tags (
  book_id TEXT NOT NULL,
  tag_id INTEGER NOT NULL,
  FOREIGN KEY (book_id) REFERENCES books(id) ON DELETE CASCADE,
  FOREIGN KEY (tag_id) REFERENCES tags(id) ON DELETE CASCADE,
  PRIMARY KEY (book_id, tag_id)
  );
  

2. Model

• The Book class in Book.hpp includes a tags vector:

  class Book {
  // ... existing members
  std::vector<std::string> m_tags;
  };
  

• The DatabaseManager provides these tag methods:

  • add_tag_to_book(book_id, tag_name) - Associates a tag with a book (creates tag if needed)
  • remove_tag_from_book(book_id, tag_name) - Removes a tag association
  • get_tags_for_book(book_id) - Returns all tags for a book
  • load_all_books() - Returns all books with their tags loaded

3. View

• The BookDetails widget (src/BookDetails.cpp) provides:

  • Book cover, title, author, and file path display
  • FlowBox of tag chips with removal (X) buttons
  • Entry field and button to add new tags
  • Button to open the book file in the default application
  • Button to delete the book from the library

• The BibliothecaWindow navigates to BookDetails when a book is activated:

  • onBookActivated() calls m_bookDetails->set_book() and switches to details view
  • Back button returns to the shelf view
  • Keyboard navigation: Escape or Backspace to go back

4. User Interaction

• Users can add tags to a book from the BookDetails view by typing in the entry and clicking "Add Tag"
• Users can remove tags by clicking the X button on any tag chip
• Search supports tags in two ways:
  • Regular fuzzy search matches tag names alongside title/author
  • tag:fiction syntax filters to only books with matching tags