docs: add frontend implementation plan for comic metadata fields

Add comprehensive planning document for displaying new ComicInfo.xml metadata fields on the book detail page. New fields to be added: - Reading direction (RTL/LTR/vertical) badge - Community rating display (0-10 scale) - Universal fields: series count, volume, imprint, age rating - Comic-specific: manga type, story arc, scan info, B&W flag Implementation approach: - SSR-first rendering (no client-side fetching) - TailwindCSS only (no custom CSS) - Conditional display based on field validity - Follows existing template patterns This document provides step-by-step implementation guidance with code examples and testing scenarios for the frontend team. Related: IMPLEMENTATION_PLAN_MERGE_METADATA_READING_DIRECTION.md
2026-03-30 21:29:08 -04:00
parent eda79a1f92
commit 3a7c8e18c9
1 changed files with 510 additions and 0 deletions
@@ -0,0 +1,510 @@
+# Frontend Implementation Plan: Add Comic Metadata Fields to Book Detail Page
+
+**Status:** Planning Document (Not Implemented)
+**Date:** March 30, 2026
+**Scope:** Display new comic/manga metadata fields on the book detail page
+
+---
+
+## Overview
+
+This document outlines how to add the new ComicInfo.xml metadata fields to the book detail page frontend. These fields are already added to the database schema and backend models (per `IMPLEMENTATION_PLAN_MERGE_METADATA_READING_DIRECTION.md`).
+
+## New Fields to Display
+
+### Universal Fields (apply to all formats: ebooks, audiobooks, comics)
+- `series_count` - Total items in series
+- `volume` - Volume/omnibus number
+- `imprint` - Publisher imprint (e.g., Vertigo, HarperCollinsEpic)
+- `age_rating` - Age rating: Everyone, Teen, Mature, Adult
+- `web_url` - URL to info page (Goodreads, ComicVine, MangaUpdates, etc.)
+- `metadata_notes` - Notes from metadata files (ComicInfo.xml, EPUB, PDF)
+- `community_rating` - Pre-existing community rating (0.0-10.0) - **distinct from user ratings**
+
+### Comic-Specific Fields
+- `manga_type` - Raw Manga field: unknown, no, yes, yes_and_right_to_left
+- `reading_direction` - Computed reading direction: auto, ltr, rtl, vertical
+- `story_arc` - Story arc name (e.g., "The Dark Phoenix Saga", "Civil War")
+- `is_black_and_white` - Black and white flag
+- `alternate_info` - JSONB: {alternate_series, alternate_number, alternate_count}
+- `scan_information` - Scan information (scanner group, resolution, etc.)
+- `summary` - Summary from ComicInfo.xml (may merge with description)
+
+---
+
+## Current Book Detail Page Structure
+
+**File:** `templates/book_detail.templ`
+
+### Current Layout Sections:
+
+1. **Top Section** (lines 23-130)
+   - Cover image (left)
+   - Title, author, action buttons (right)
+   - Rating display (user ratings)
+   - Series badge
+   - Description/Synopsis
+
+2. **Progress Section** (lines 132-185)
+   - Reading progress bar
+   - Progress stats grid
+
+3. **Metadata Grid** (lines 186-253)
+   - Publication info (Publisher, Published, ISBN, Language, Edition, Pages, Genre, Copyright Year)
+   - Technical info (Format, File Size)
+   - External links section
+
+4. **Collections Section** (lines 347-367)
+
+---
+
+## Implementation Plan
+
+### Step 1: Add Reading Direction Badge (Display Priority: HIGH)
+
+**Location:** After Series Badge (line 117)
+
+**Rationale:** Reading direction is critical for manga/comic readers. Display prominently like the series badge.
+
+```templ
+<!-- Reading Direction Badge (for manga/comics) -->
+if book.ReadingDirection.Valid && book.ReadingDirection.String != "" && book.ReadingDirection.String != "auto" {
+    <div class="mb-4">
+        <span
+            class="px-3 py-1 rounded-full text-sm font-semibold"
+            style="background-color: var(--accent); color: white;"
+        >
+            📖 { strings.ToUpper(book.ReadingDirection.String) }
+        </span>
+    </div>
+}
+```
+
+**Styling Notes:**
+- Use `var(--accent)` for consistency with series badge
+- Only show if not "auto" (i.e., explicitly set to ltr, rtl, or vertical)
+- Icon: 📖 for visual clarity
+
+---
+
+### Step 2: Add Community Rating Display (Display Priority: HIGH)
+
+**Location:** After User Rating Display (line 103)
+
+**Rationale:** Community rating complements user rating. Show side-by-side for comparison.
+
+```templ
+<!-- Community Rating Display (from metadata) -->
+if book.CommunityRating.Valid && book.CommunityRating.Float64 > 0 {
+    <div class="mb-2">
+        <span class="text-lg" style="color: var(--text-secondary);">
+            Community Rating:
+            <span class="font-bold" style="color: var(--text-primary);">
+                @templ.Raw(renderStars(getBookRating(int(book.CommunityRating.Float64 * 2))))
+            </span>
+            <span class="ml-2 text-sm" style="color: var(--text-secondary);">
+                ({ fmt.Sprintf("%.1f", book.CommunityRating.Float64) } / 10)
+            </span>
+        </span>
+    </div>
+}
+```
+
+**Styling Notes:**
+- Smaller text than user rating (text-lg vs text-2xl)
+- Gray/subtle color to distinguish from user rating
+- Scale: Community rating is 0-10, user rating display is 0-5 stars
+  - Conversion: `community_rating * 2` to get 0-10 scale for star display
+
+---
+
+### Step 3: Add Comic-Specific Badges (Display Priority: MEDIUM)
+
+**Location:** After Reading Direction Badge (line 117)
+
+**Rationale:** Group all manga/comic-specific badges together for easy scanning.
+
+```templ
+<!-- Comic-Specific Badges -->
+<div class="flex flex-wrap gap-2 mb-4">
+    <!-- Age Rating Badge -->
+    if book.AgeRating.Valid && book.AgeRating.String != "" {
+        <span
+            class="px-2 py-1 rounded-full text-xs font-semibold"
+            style="background-color: var(--bg-primary); border: 1px solid var(--border); color: var(--text-secondary);"
+        >
+            { book.AgeRating.String }
+        </span>
+    }
+
+    <!-- Black and White Badge -->
+    if book.IsBlackAndWhite.Valid && book.IsBlackAndWhite.Bool {
+        <span
+            class="px-2 py-1 rounded-full text-xs font-semibold"
+            style="background-color: var(--bg-primary); border: 1px solid var(--border); color: var(--text-secondary);"
+        >
+            B&W
+        </span>
+    }
+
+    <!-- Story Arc Badge -->
+    if book.StoryArc.Valid && book.StoryArc.String != "" {
+        <span
+            class="px-2 py-1 rounded-full text-xs font-semibold"
+            style="background-color: var(--bg-primary); border: 1px solid var(--border); color: var(--text-secondary);"
+        >
+            📚 { book.StoryArc.String }
+        </span>
+    }
+</div>
+```
+
+**Styling Notes:**
+- Use subtle styling (smaller, outlined) to differentiate from primary badges
+- Flex wrap for responsive layout
+- Icons: 📚 for story arc
+
+---
+
+### Step 4: Add Universal Series Info to Metadata Grid (Display Priority: HIGH)
+
+**Location:** In Metadata Grid section, after Series/Number fields
+
+**Note:** The current template doesn't display Series/Number in the metadata grid (only as badge). We'll add all series-related fields together.
+
+**Insertion Point:** After Genre field (line 235)
+
+```templ
+<!-- Series Information (if not shown in badge) -->
+if book.SeriesCount.Valid && book.SeriesCount.Int32 > 0 {
+    <div>
+        <p style="color: var(--text-secondary)">Series Count</p>
+        <p>{ book.SeriesCount.Int32 } items</p>
+    </div>
+}
+if book.Volume.Valid && book.Volume.Int32 > 0 {
+    <div>
+        <p style="color: var(--text-secondary)">Volume</p>
+        <p>Vol. { book.Volume.Int32 }</p>
+    </div>
+}
+if book.Imprint.Valid && book.Imprint.String != "" {
+    <div>
+        <p style="color: var(--text-secondary)">Imprint</p>
+        <p>{ book.Imprint.String }</p>
+    </div>
+}
+```
+
+---
+
+### Step 5: Add Comic-Specific Metadata to Grid (Display Priority: MEDIUM)
+
+**Location:** In Metadata Grid section, after Copyright Year (line 241)
+
+```templ
+<!-- Comic-Specific Fields -->
+if book.MangaType.Valid && book.MangaType.String != "" && book.MangaType.String != "unknown" {
+    <div>
+        <p style="color: var(--text-secondary)">Manga Type</p>
+        <p class="capitalize">{ strings.ReplaceAll(book.MangaType.String, "_", " ") }</p>
+    </div>
+}
+if book.ScanInformation.Valid && book.ScanInformation.String != "" {
+    <div>
+        <p style="color: var(--text-secondary)">Scan Info</p>
+        <p class="text-sm" style="color: var(--text-secondary);">{ book.ScanInformation.String }</p>
+    </div>
+}
+if book.AlternateInfo.Valid && len(book.AlternateInfo.Bytes) > 0 {
+    <div>
+        <p style="color: var(--text-secondary)">Alternate Series</p>
+        <p class="text-sm">{ string(book.AlternateInfo.Bytes) }</p>
+    </div>
+}
+```
+
+**Note for AlternateInfo:** This is JSONB data stored as `[]byte`. You may want to:
+1. Parse the JSON and display formatted
+2. Or create a helper function to extract specific fields
+
+Helper function example (add to `templates/helpers.go`):
+
+```go
+// getAlternateSeries extracts the alternate series name from JSONB data
+func getAlternateSeries(data pgtype.Bytes) string {
+    if !data.Valid || len(data.Bytes) == 0 {
+        return ""
+    }
+    var result map[string]interface{}
+    if err := json.Unmarshal(data.Bytes, &result); err != nil {
+        return ""
+    }
+    if series, ok := result["alternate_series"].(string); ok {
+        return series
+    }
+    return ""
+}
+```
+
+Then in template:
+```templ
+if altSeries := getAlternateSeries(book.AlternateInfo); altSeries != "" {
+    <div>
+        <p style="color: var(--text-secondary)">Alternate Series</p>
+        <p>{ altSeries }</p>
+    </div>
+}
+```
+
+---
+
+### Step 6: Add Summary Section (Display Priority: MEDIUM)
+
+**Location:** After Description/Synopsis section (line 128)
+
+**Rationale:** Summary from ComicInfo.xml may differ from Calibre description. Show both if present.
+
+```templ
+<!-- Summary (from ComicInfo.xml, if different from description) -->
+if book.Summary.Valid && book.Summary.String != "" && book.Summary.String != book.Description.String {
+    <div class="mb-6">
+        <h3 class="font-semibold mb-2" style="color: var(--text-primary)">Comic Summary</h3>
+        <div class="max-h-[20rem] overflow-y-auto pr-2" style="color: var(--text-secondary)">
+            @UnsafeHTML(
+                bluemonday.UGCPolicy().Sanitize(book.Summary.String),
+            ).ToComponent()
+        </div>
+    </div>
+}
+```
+
+---
+
+### Step 7: Add Metadata Notes Section (Display Priority: LOW)
+
+**Location:** After Summary section (or at the bottom before Collections)
+
+**Rationale:** Metadata notes are technical/scanner information. Less important for end users.
+
+```templ
+<!-- Metadata Notes (technical notes from metadata files) -->
+if book.MetadataNotes.Valid && book.MetadataNotes.String != "" {
+    <div
+        class="card p-6 rounded-lg border mb-6"
+        style="background-color: var(--bg-secondary); border-color: var(--border);"
+    >
+        <h3 class="font-semibold mb-2" style="color: var(--text-primary)">Metadata Notes</h3>
+        <div class="text-sm" style="color: var(--text-secondary);">
+            { book.MetadataNotes.String }
+        </div>
+    </div>
+}
+```
+
+---
+
+### Step 8: Add Web URL Link (Display Priority: MEDIUM)
+
+**Location:** In External Links section (line 258)
+
+**Rationale:** Add web_url as another external link alongside Goodreads, OpenLibrary, etc.
+
+```templ
+<!-- In the External Links flex container -->
+if book.WebUrl.Valid && book.WebUrl.String != "" {
+    <a
+        href={ book.WebUrl.String }
+        target="_blank"
+        rel="noopener noreferrer"
+        class="text-sm hover:underline flex items-center gap-1"
+        style="color: var(--accent);"
+    >
+        🔗 { getDomainName(book.WebUrl.String) }
+    </a>
+}
+```
+
+Helper function to extract domain name (add to `templates/helpers.go`):
+
+```go
+// getDomainName extracts a clean domain name from URL for display
+func getDomainName(rawURL string) string {
+    if rawURL == "" {
+        return "Source"
+    }
+    u, err := url.Parse(rawURL)
+    if err != nil {
+        return "Source"
+    }
+    // Return hostname without www.
+    hostname := u.Hostname()
+    return strings.TrimPrefix(hostname, "www.")
+}
+```
+
+---
+
+## TypeScript Updates (No Changes Required)
+
+**File:** `web/src/book-detail.ts`
+
+**Status:** No changes needed. This file only handles Alpine.js modal visibility functions.
+
+**Note:** The book detail page uses SSR (server-side rendering) exclusively. No client-side data fetching or Alpine.js data manipulation is needed for these new fields.
+
+---
+
+## Template Helper Functions Needed
+
+Add these functions to `templates/helpers.go` (or existing helpers file):
+
+```go
+package templates
+
+import (
+    "encoding/json"
+    "net/url"
+    "strings"
+
+    "github.com/jackc/pgx/v5/pgtype"
+)
+
+// getAlternateSeries extracts the alternate series name from JSONB data
+func getAlternateSeries(data pgtype.Bytes) string {
+    if !data.Valid || len(data.Bytes) == 0 {
+        return ""
+    }
+    var result map[string]interface{}
+    if err := json.Unmarshal(data.Bytes, &result); err != nil {
+        return ""
+    }
+    if series, ok := result["alternate_series"].(string); ok {
+        return series
+    }
+    return ""
+}
+
+// getDomainName extracts a clean domain name from URL for display
+func getDomainName(rawURL string) string {
+    if rawURL == "" {
+        return "Source"
+    }
+    u, err := url.Parse(rawURL)
+    if err != nil {
+        return "Source"
+    }
+    hostname := u.Hostname()
+    return strings.TrimPrefix(hostname, "www.")
+}
+
+// formatAlternateInfo formats alternate series info as readable string
+func formatAlternateInfo(data pgtype.Bytes) string {
+    if !data.Valid || len(data.Bytes) == 0 {
+        return ""
+    }
+    var result map[string]interface{}
+    if err := json.Unmarshal(data.Bytes, &result); err != nil {
+        return ""
+    }
+
+    var parts []string
+    if series, ok := result["alternate_series"].(string); ok && series != "" {
+        parts = append(parts, series)
+    }
+    if num, ok := result["alternate_number"].(float64); ok && num > 0 {
+        parts = append(parts, fmt.Sprintf("#%d", int(num)))
+    }
+    if count, ok := result["alternate_count"].(float64); ok && count > 0 {
+        parts = append(parts, fmt.Sprintf("(of %d)", int(count)))
+    }
+
+    return strings.Join(parts, " ")
+}
+```
+
+---
+
+## Implementation Checklist
+
+- [ ] **Step 1:** Add Reading Direction Badge (after line 117)
+- [ ] **Step 2:** Add Community Rating Display (after line 103)
+- [ ] **Step 3:** Add Comic-Specific Badges (after line 117)
+- [ ] **Step 4:** Add Universal Series Info to Metadata Grid (after line 235)
+- [ ] **Step 5:** Add Comic-Specific Metadata to Grid (after line 241)
+- [ ] **Step 6:** Add Summary Section (after line 128)
+- [ ] **Step 7:** Add Metadata Notes Section (before Collections)
+- [ ] **Step 8:** Add Web URL Link (in External Links section)
+- [ ] Add template helper functions to `templates/helpers.go`
+- [ ] Test with manga book (RTL reading direction)
+- [ ] Test with Western comic (LTR reading direction)
+- [ ] Test with webtoon (vertical reading direction)
+- [ ] Test with ebook (no comic metadata)
+- [ ] Verify responsive layout on mobile/desktop
+- [ ] Verify dark/light theme compatibility
+
+---
+
+## Testing Scenarios
+
+### Test Case 1: Japanese Manga
+**Expected Display:**
+- Reading Direction: "RTL" badge
+- Manga Type: "yes_and_right_to_left" in metadata grid
+- Community Rating: displayed alongside user rating
+
+### Test Case 2: Western Comic
+**Expected Display:**
+- Reading Direction: "LTR" badge (or hidden if auto)
+- Age Rating: "Teen" or "Mature" badge
+- Story Arc: displayed if present
+- Publisher/Imprint: displayed in metadata grid
+
+### Test Case 3: Webtoon/Manhwa
+**Expected Display:**
+- Reading Direction: "vertical" badge
+- Language: "ko" (Korean) in metadata grid
+- Format-specific metadata displayed
+
+### Test Case 4: Regular Ebook
+**Expected Display:**
+- No reading direction badge (or "auto" hidden)
+- No comic-specific fields
+- Only universal fields (series count, volume, imprint, age rating) if present
+
+---
+
+## Design Principles Followed
+
+1. **✅ SSR-First:** All data server-side rendered, no client-side fetching
+2. **✅ Progressive Enhancement:** Page works without JavaScript
+3. **✅ TailwindCSS Only:** No custom CSS added
+4. **✅ Existing Patterns:** Follows current badge/grid styling
+5. **✅ Responsive:** Uses existing responsive grid classes
+6. **✅ Theme-Aware:** Uses CSS variables (`var(--accent)`, `var(--text-secondary)`, etc.)
+7. **✅ Accessible:** Semantic HTML, proper contrast
+8. **✅ Conditional Rendering:** Only show fields if they have values
+9. **✅ No Backend Changes:** Frontend-only, uses existing API/handler types
+
+---
+
+## Related Documentation
+
+- `IMPLEMENTATION_PLAN_MERGE_METADATA_READING_DIRECTION.md` - Full backend implementation
+- `PROJECT_GUIDELINES.md` - Project coding standards and conventions
+- `templates/book_detail.templ` - Current book detail template
+- `internal/handlers/media_detail.go` - MediaDetail struct definition
+
+---
+
+## Notes
+
+- **No TypeScript changes needed:** All data is SSR'd from Go handlers
+- **No API changes needed:** MediaDetail already embeds database.MediaItems with new fields
+- **Template helpers:** May need helper functions for JSONB parsing and URL display
+- **Styling consistency:** All new elements use existing CSS variables and Tailwind classes
+- **Conditional display:** Most fields should only display if they have values (check `.Valid`)
+
+---
+
+**End of Document**