cloud-reader/docs/frontend/012-library-context-menu.md

012 — Library book context menu

Status: Implemented
Created: 2026-06-03

Objective

Add a custom right-click context menu on each book card in the library with Sync metadata (Open Library refresh) and Remove (delete from library). Show toast notifications for success, warning, and error outcomes.

Architecture

Library book card (contextmenu)
  → BookContextMenu
    → Sync metadata: POST /api/books/ebooks/{id}/enrich-metadata/
    → Remove: confirm dialog → DELETE /api/books/ebooks/{id}/
  → ToastProvider (app-wide) → success | warning | error toasts

Backend endpoints already exist; no API changes required.

Frontend changes

File	Change
api/books.ts	enrichEBookMetadata(id) → POST .../enrich-metadata/
types/book.ts	OpenLibraryMetadata with match_status
hooks/useToast.tsx	ToastProvider, showToast({ message, variant }), auto-dismiss ~4s
components/ToastContainer.tsx	Fixed bottom-right toast stack
components/BookContextMenu.tsx	Positioned menu; sync + remove actions
pages/Library.tsx	onContextMenu on cards; local state updates
App.tsx	Wrap routes with ToastProvider

Context menu behavior

• Opens on right-click (contextmenu); browser default menu suppressed
• Position clamped to viewport; closes on outside click, Escape, or scroll
• Sync metadata: updates card title/author/cover from response; toast by metadata.match_status:
  • matched → success
  • not_found → warning
  • other → neutral success
• Remove: window.confirm before delete; removes card from list on success
• Menu clicks do not trigger card navigation to reader

Dependencies

None (no new npm packages).

Verification

1. Right-click a book → menu appears at cursor
2. Sync metadata on a matched book → cover/title may update, success toast
3. Sync on unmatched book → warning toast, no crash
4. Remove → confirm → book disappears, success toast
5. Cancel remove → book stays, menu closes
6. Left-click still opens reader (EPUB) or PDF notice