hxbooks/docs/frontend-plan.md

Frontend Rebuild Plan - Phase 1: Pure HTML Responsive Design

Created: March 17, 2026
Phase: 1 of 3 (Pure HTML → HTMX → JavaScript Components)

Overview

Rebuild HXBooks frontend with mobile-first responsive design using pure HTML and Bootstrap. Create clean, component-based template structure that will be HTMX-ready for Phase 2.

Core Views:

• Book List: Main view with search bar, sidebar, results grid
• Book Details: Full book data display and edit forms

Design Decisions:

• Mobile-first responsive (768px breakpoint)
• Visible sidebar (desktop), hamburger menu (mobile)
• User selector as filter dropdown (not login-style)
• Clean URLs with full search state persistence
• Component-based templates for HTMX compatibility
• HTML5 + server-side validation

Implementation Plan

Phase A: Foundation Setup (Steps 1-3)

Step 1: Base Layout & Components

• templates/base.html.j2 - Main layout with Bootstrap, responsive sidebar framework
• templates/components/header.html.j2 - Header with user selector dropdown
• templates/components/sidebar.html.j2 - Collapsible sidebar with search list
• src/hxbooks/static/style.css - Custom responsive CSS

Step 2: Clean URL Routing

• Rewrite src/hxbooks/app.py routes with clean URLs:
  • / - Book list (main view)
  • /search?q=...&filters=... - Search with URL persistence
  • /book/new - Create book
  • /book/<id> - Book details/edit
  • /book/<id>/delete - Delete confirmation
  • /import - Import from ISBN

Step 3: Sidebar Component

• Default searches (All, Owned, Wishlist, Reading, Read)
• Saved user searches with edit/delete
• Create/Import buttons in top section
• Responsive collapse behavior

Phase B: Book List View (Steps 4-7)

Step 4: Search Infrastructure

• templates/components/search_bar.html.j2 - Search input with suggestions
• templates/components/search_filters.html.j2 - Advanced filters panel
• URL parameter handling for persistent search state
• Mobile-optimized search interface

Step 5: Search Results Display

• templates/components/book_card.html.j2 - Individual book preview card
• templates/book/list.html.j2 - Results grid with responsive columns
• Card layout optimized for future HTMX partial updates
• Loading state placeholders (simple for Phase 1)

Step 6: Search State Persistence

• URL serialization/deserialization for all search params
• Browser history support with clean URLs
• Bookmarkable search results
• Form state preservation on validation errors

Step 7: Save Search Functionality

• templates/components/save_search_modal.html.j2 - Save search form
• Integration with user saved searches in sidebar
• Validation and error handling

Phase C: Book Details View (Steps 8-11)

Step 8: Book Details Structure

• templates/book/detail.html.j2 - Full book display and edit forms
• templates/components/book_form.html.j2 - Reusable book edit form
• All metadata fields (title, authors, genres, location, notes)
• Responsive form layout for mobile/desktop

Step 9: User-Specific Data

• templates/components/reading_status.html.j2 - Reading tracking component
• templates/components/wishlist_status.html.j2 - Wishlist management
• Reading history display based on selected user context
• User-specific action buttons

Step 10: Book Action Buttons

• Accept/Discard changes with form state management
• Delete book with confirmation
• Start/Finish reading workflow
• Add/Remove from wishlist
• Action buttons optimized for HTMX target attributes

Step 11: Book Creation Workflow

• templates/book/create.html.j2 - New book form
• templates/components/import_modal.html.j2 - ISBN import modal
• Google Books API integration form
• Form validation with inline error display

Phase D: Integration & Polish (Steps 12-13)

Step 12: Form Validation

• HTML5 client-side validation attributes
• Server-side Pydantic validation integration
• templates/components/error_display.html.j2 - Error message component
• Form state preservation and error recovery

Step 13: Responsive Testing & Cleanup

• Cross-device testing (phone, tablet, desktop)
• Sidebar behavior verification at 768px breakpoint
• Form flow validation and error handling
• Performance optimization for large libraries

Technical Architecture

Component Structure

templates/
├── base.html.j2                    # Main layout
├── components/                     # Reusable components (HTMX-ready)
│   ├── header.html.j2             # User selector, branding
│   ├── sidebar.html.j2            # Search list, actions
│   ├── search_bar.html.j2         # Search input
│   ├── search_filters.html.j2     # Advanced filters
│   ├── book_card.html.j2          # Book preview card
│   ├── book_form.html.j2          # Book edit form
│   ├── reading_status.html.j2     # Reading tracking
│   ├── wishlist_status.html.j2    # Wishlist management
│   ├── save_search_modal.html.j2  # Save search dialog
│   ├── import_modal.html.j2       # ISBN import dialog
│   └── error_display.html.j2      # Error messages
└── book/
    ├── list.html.j2               # Book list with search results
    ├── detail.html.j2             # Book details and edit
    └── create.html.j2             # New book creation

HTMX-Ready Design Patterns

• Atomic Components: Each component can be updated independently
• Target Attributes: Components designed for hx-target updates
• Fragment Boundaries: Clear separation for partial page updates
• State Management: URL-based state for HTMX navigation
• Form Structure: Post-redirect-get pattern for HTMX compatibility

URL Structure (Clean)

/                           # Book list (main view)
/search?q=tolkien&read=true # Search with filters (bookmarkable)
/book/new                   # Create new book
/book/123                   # View/edit book details  
/book/123/delete           # Delete confirmation
/import                    # Import book from ISBN

Responsive Breakpoints

• Mobile: < 768px (hamburger sidebar, stacked layout)
• Desktop: ≥ 768px (visible sidebar, grid layout)
• Component Flexibility: Cards adapt to container width

Implementation Notes

Backend Integration

• Rewrite routes in src/hxbooks/app.py (clean implementation vs book.py)
• Use library.py as business logic interface (following CLI pattern)
• Mock missing functionality in library.py (saved searches handling, etc.)
• Utilize existing Pydantic schemas for validation
• Note: Implement missing library.py methods as needed during development

Development Priorities

1. Mobile-first: Design components for mobile, enhance for desktop
2. Component Isolation: Prepare for HTMX partial updates
3. Clean URLs: Ensure bookmarkable and shareable search states
4. Form Validation: HTML5 + server-side with good error UX

Excluded from Phase 1

• HTMX dynamic updates (Phase 2)
• JavaScript component enhancement (Phase 3)
• Advanced loading states and error recovery
• Mobile gesture optimization
• Accessibility features (deferred)
• Alternative view formats (table, detailed list)

Verification Checklist

Responsive Behavior

• Sidebar collapses to hamburger on mobile (< 768px)
• Card grid adapts to screen width
• Forms are usable on mobile devices
• Header user selector works on all devices

Search Functionality

• URL persistence for all search parameters
• Saved searches load correctly from sidebar
• Search results display in responsive card grid
• Navigation between search and details preserves context

Book Management

• Create new book workflow functions
• ISBN import modal works
• Book details editing with validation
• Accept/Discard/Delete actions work correctly

User Context

• User selector dropdown updates context
• Reading status reflects selected user
• Wishlist data shows for correct user
• User-specific actions function properly

Form Validation

• HTML5 validation prevents submission of invalid data
• Server-side Pydantic validation shows errors
• Error messages display clearly
• Form state preserved after validation errors

---

Next Phase Preview: Phase 2 will enhance these components with HTMX for:

• Partial page updates (search results, form submissions)
• Inline editing capabilities
• Progressive enhancement of user interactions
• Dynamic form validation and feedback