281 lines
11 KiB
Markdown
281 lines
11 KiB
Markdown
# 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
|
|
- [x] Sidebar collapses to hamburger on mobile (< 768px)
|
|
- [x] Card grid adapts to screen width (optimized with better sizing)
|
|
- [x] Forms are usable on mobile devices
|
|
- [x] Header user selector works on all devices (fixed dropdown positioning)
|
|
|
|
### Search Functionality
|
|
- [x] URL persistence for all search parameters
|
|
- [x] Saved searches load correctly from sidebar
|
|
- [x] Search results display in responsive card grid
|
|
- [x] Navigation between search and details preserves context
|
|
|
|
### Book Management
|
|
- [x] Create new book workflow functions
|
|
- [x] ISBN import modal works
|
|
- [x] Book details editing with validation (Pydantic integration)
|
|
- [x] Accept/Discard/Delete actions work correctly
|
|
|
|
### User Context
|
|
- [x] User selector dropdown updates context
|
|
- [x] Reading status reflects selected user
|
|
- [x] Wishlist data shows for correct user
|
|
- [x] User-specific actions function properly
|
|
|
|
### Form Validation
|
|
- [x] HTML5 validation prevents submission of invalid data
|
|
- [x] Server-side Pydantic validation shows errors
|
|
- [x] Error messages display clearly
|
|
- [x] Form state preserved after validation errors
|
|
|
|
### ✨ Additional Features Delivered
|
|
- [x] **Status badges on book cards** - Reading status, ratings, and wishlist indicators
|
|
- [x] **Mobile expandable status component** - CSS-only solution for book details
|
|
- [x] **Shared template variables** - DRY approach with proper Jinja2 imports
|
|
- [x] **JavaScript elimination** - Pure HTML+CSS approach achieved
|
|
- [x] **Enhanced mobile UX** - Fixed dropdown issues, optimized layouts
|
|
- [x] **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 |