Bookhoard/bookhoard
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 12 Wiki Activity
883 Commits 5 Branches 13 Tags
9b3d8cc949d87e313b6c7d1862c72e044eed2840
Commit Graph
3 Commits
Author SHA1 Message Date
john-okeefe 9b3d8cc949 feat: implement collection library filter with WebSocket improvements and test coverage 
This commit adds comprehensive functionality for filtering collections by library,
improves WebSocket real-time updates with user activity detection, and adds
extensive test coverage.

## Core Features

### Collection Library Filter
- Added library_id parameter to media-items search API
- Collections can now be filtered by specific library
- Toggle UI component for enabling/disabling library filter
- Default state is "checked" when library_id is present
- Consistent behavior across partial and fuzzy search modes

### WebSocket Auto-Reload Mitigation
- Added user activity detection to prevent disruptive page reloads
- Checks if user is actively typing in INPUT/TEXTAREA/SELECT elements
- Skips auto-reload when user is interacting with form elements
- Toast notifications still show for awareness
- Prevents data loss during editing operations

## Implementation Changes

### Backend
- internal/database/queries.sql.go: Added library filter support to search queries
- internal/handlers/media.go: Enhanced search with library_id parameter validation
- internal/handlers/collections.go: Updated collection handlers with library filtering
- internal/sync/websocket.go: Improved broadcast mechanism with user-scoped updates
- internal/router/frontend.go: Pass libraryID to collection templates

### Frontend
- templates/collections.templ: Added library filter toggle UI component
- web/src/collections.ts: TypeScript implementation with WebSocket integration
- templates/collections_templ.go: Generated template code

### Testing
- cmd/server/tests/search_test.go: Added TestCollectionSearchLibraryFilter
- cmd/server/tests/websocket_test.go: Added TestWebSocketUserScopedBroadcast
- New helper functions for creating libraries and media items via API
- Comprehensive test coverage for library filtering and user-scoped broadcasts

## API Documentation Updates

### Bruno Tests (Comprehensive Documentation)
- bruno/collections/*: Added detailed API documentation for all collection endpoints
- bruno/devices/*: Added device management and sync API documentation
- bruno/devices/kobo/api.yml: Kobo-specific sync protocol docs
- bruno/devices/koreader/api.yml: KOReader-specific sync protocol docs
- bruno/opds/*: Added OPDS feed and download endpoint documentation
- bruno/library/browse-folders.yml: Library folder browsing API docs

### New Bruno Tests
- bruno/media-items/Search All Libraries.yml: Test search without library filter
- bruno/media-items/Search Specific Library.yml: Test search with library filter
- bruno/media-items/Search Invalid Library ID.yml: Test error handling

## Documentation

- docs/developer/api/media-items/search_media_items.md: Updated with library_id parameter
- IMPLEMENTATION_COLLECTION_FIX.md: Comprehensive implementation guide with test scenarios

## Testing

### Integration Tests
- Library filter tests verify correct filtering across multiple libraries
- Invalid library_id tests ensure proper error handling
- WebSocket tests verify user-scoped broadcast behavior
- User A no longer receives User B's collection updates

### Manual Testing Scenarios
- Open collection in multiple tabs - updates propagate correctly
- Type in search box while another tab adds books - no disruptive reload
- Add/remove books from collection - toast notifications appear
- Toggle library filter - results update dynamically

## Technical Details

- WebSocket broadcasts are now user-scoped for privacy
- Active element detection uses tagName and contenteditable attributes
- Library ID validation uses UUID format checking
- Progressive enhancement maintained - page works without JavaScript
- All changes follow PROJECT_GUIDELINES.md conventions
- TypeScript only for frontend logic
- TailwindCSS only for styling
- Procedural programming style throughout

## Breaking Changes

None - all changes are additive and backward compatible.
 2026-03-04 22:37:47 -05:00
john-okeefe 72f053d179 docs: comprehensive implementation plan for collection detail fix 
This implementation plan addresses multiple architectural improvements:

**Security Fix:**
- Add user-scoped WebSocket broadcasts to prevent cross-user data leaks
- Current broadcast sends ALL collection updates to ALL users
- New BroadcastToUser() method ensures privacy between users

**Features:**
- Add optional library_id filter to search API (partial + fuzzy)
- Add library filter toggle UI in Add Books modal
- Remove 265 lines of inline JavaScript from template
- Convert to proper TypeScript with type safety

**Architecture:**
- Full-stack task: backend, database, frontend, documentation
- User-scoped broadcasts follow JWT + device auth patterns
- Progressive enhancement maintained (SSR + JS enhancement)
- WebSocket real-time sync preserved for multi-device support

**Testing:**
- Integration tests using setupTestServer() helper
- Tests for library filtering (no filter, lib1, lib2, invalid)
- Tests for user-scoped WebSocket broadcasts
- Bruno API tests for new library_id parameter

**Documentation:**
- API docs at docs/developer/api/search.md
- Git strategy: 6 logical commits outlined
- Testing checklist for manual + automated verification

**Files Modified:**
- internal/sync/websocket.go: Add BroadcastToUser()
- internal/handlers/collections.go: Use user-scoped broadcasts
- internal/database/queries.sql: Add library_id filter
- internal/handlers/media.go: Accept library_id parameter
- templates/collections.templ: Remove inline JS, add toggle UI
- web/src/collections.ts: TypeScript with WebSocket support
- internal/router/frontend.go: Pass libraryID to template
- Tests, docs, Bruno tests

This plan follows all PROJECT_GUIDELINES.md requirements including
TypeScript conversion, TailwindCSS only, procedural style, proper
commit organization, and comprehensive testing.
 2026-03-02 21:02:47 -05:00
john-okeefe 240b3247aa docs: Add implementation plan for collection detail page fix and library filtering 
This document outlines the plan to fix the broken /collections/:id page
which has an inline JavaScript bug, and add library_id support to the
search API.

Key changes planned:
- Remove 265+ lines of inline JavaScript from collections.templ template
- Add minimal TypeScript module (~180 lines) in web/src/collections.ts
- Add optional library_id parameter to SearchMediaItems API endpoint
- Add library filter toggle UI to the Add Books modal
- Update template to accept libraryID parameter

The implementation uses a hybrid approach: minimal TypeScript for
client-only features while maintaining HTMX-like patterns for CRUD
operations. This reduces maintenance burden and improves code
organization.

Steps detailed:
1. Update Search API to accept optional library_id parameter
2. Add library_id filter to SQL query if not present
3. Remove inline JS from template, add data attributes
4. Add toggle UI for filtering books by library
5. Add TypeScript functions for modal, search, and book management
6. Update handler to pass libraryID to template
7. Update template function signature

Testing checklist included to verify:
- Page loads without JS errors
- Library filter toggle visibility
- Search results with/without library filtering
- Add/remove books functionality
- Client-side search filtering
 2026-03-02 15:45:52 -05:00