fran/hxbooks
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
main
hxbooks/docs/frontend-plan.md

11 KiB
Raw Permalink Blame History

Frontend Rebuild Plan - Phase 1: Pure HTML Responsive Design

Created: March 17, 2026
Completed: March 20, 2026
Status: ✅ PHASE 1 COMPLETE
Phase: 1 of 3 (Pure HTML → HTMX → JavaScript Components)

✅ Phase 1 Completion Summary

Phase 1 has been successfully completed with all core objectives achieved and several enhancements beyond the original scope.

🎯 Major Achievements

✅ Complete Responsive Redesign

  • Mobile-first responsive layout with 768px breakpoint
  • JavaScript completely eliminated (HTML + CSS only approach)
  • Component-based template architecture ready for HTMX integration
  • Clean URL structure with search state persistence

✅ Enhanced User Experience

  • User-specific status badges on book cards (reading, rating, wishlist)
  • Expandable mobile status bar using CSS-only approach
  • Fixed Bootstrap mobile dropdown positioning issues
  • Optimized book card sizing and layout for better screen utilization

✅ Technical Improvements

  • Pydantic 2.x server-side validation with proper error handling
  • Shared template component system (user_book_vars.html.j2)
  • Jinja2 import/export pattern for DRY template variables
  • Individual form handling to avoid nested HTML form issues

✅ Code Quality Enhancements

  • Eliminated code duplication across template components
  • Proper Jinja2 scoping with {% import %} and with context
  • Component isolation ready for HTMX partial updates
  • Clean separation between presentation and business logic

📱 Mobile Responsiveness Achievements

  • Header: Fixed user selector dropdown floating properly on mobile
  • Book Details: Expandable status component that collapses on mobile, stays expanded on desktop
  • Book Cards: Status badges properly positioned, optimized card sizing
  • Forms: All forms work seamlessly across device sizes

🛠️ Technical Architecture Delivered

  • Component-based templates in src/hxbooks/templates/components/
  • Shared variables system for user book data across components
  • Bootstrap 5.3 + custom CSS responsive framework
  • Server-side validation with Pydantic schemas
  • Clean URL routing with search state preservation

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 - COMPLETED

Responsive Behavior

  • Sidebar collapses to hamburger on mobile (< 768px)
  • Card grid adapts to screen width (optimized with better sizing)
  • Forms are usable on mobile devices
  • Header user selector works on all devices (fixed dropdown positioning)

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 (Pydantic integration)
  • 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

✨ Additional Features Delivered

  • Status badges on book cards - Reading status, ratings, and wishlist indicators
  • Mobile expandable status component - CSS-only solution for book details
  • Shared template variables - DRY approach with proper Jinja2 imports
  • JavaScript elimination - Pure HTML+CSS approach achieved
  • Enhanced mobile UX - Fixed dropdown issues, optimized layouts
  • Code quality improvements - Component refactoring and template organization

🚀 Phase 2 Preparation

Ready for Phase 2: The component-based architecture and clean URL structure are now ready for HTMX enhancement:

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

Key Files Ready for HTMX Integration:

  • All components in src/hxbooks/templates/components/
  • Clean separation between data and presentation
  • Atomic components designed for independent updates
  • URL-based state management compatible with HTMX navigation
Reference in New Issue View Git Blame Copy Permalink