# 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