john-okeefe
9b3d8cc949
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.
71 lines
2.1 KiB
Markdown
71 lines
2.1 KiB
Markdown
# Search Media Items
|
|
|
|
Search for media items by title, author, series, tags, or contributors.
|
|
|
|
**Note:** Search is case-insensitive and punctuation-agnostic. The search query is matched against normalized tags_search and contributors_search fields, allowing users to find matches regardless of casing or punctuation.
|
|
|
|
Examples:
|
|
|
|
- Search "acme corp" finds items with "ACME CORP." or "Acme Corp"
|
|
- Search "oreilly" finds items with "O'Reilly Media" or "OReilly Media"
|
|
- Search "science fiction" finds items with "Science-Fiction" or "science-fiction"
|
|
|
|
**Endpoint**: `GET /api/media-items/search`
|
|
**Auth**: Required
|
|
|
|
## Query Parameters
|
|
|
|
| Parameter | Type | Required | Description |
|
|
| --------- | ------- | -------- | ------------------------------------------- |
|
|
| q | string | Yes | Search query (minimum 2 characters) |
|
|
| library_id| string | No | Filter results to specific library (UUID) |
|
|
| limit | integer | No | Number of results (default 20) |
|
|
| offset | integer | No | Number to skip |
|
|
|
|
## Request Headers
|
|
|
|
| Header | Type | Required | Description |
|
|
| ------------- | ------ | -------- | ------------ |
|
|
| Authorization | string | Yes | Bearer token |
|
|
|
|
### Example Request
|
|
|
|
Search all libraries:
|
|
|
|
```http
|
|
GET /api/media-items/search?q=Harry+Potter&limit=20&offset=0
|
|
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
|
|
```
|
|
|
|
Search within a specific library:
|
|
|
|
```http
|
|
GET /api/media-items/search?q=Harry&library_id=123e4567-e89b-12d3-a456-426614174000&limit=20
|
|
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
|
|
```
|
|
|
|
## Response (200 OK)
|
|
|
|
```json
|
|
{
|
|
"results": [
|
|
{
|
|
"id": "uuid",
|
|
"title": "Book Title",
|
|
"author": "Author Name",
|
|
"library_id": "...",
|
|
"library_name": "E-Books",
|
|
"match_score": 0.95
|
|
}
|
|
],
|
|
"total": 15
|
|
}
|
|
```
|
|
|
|
## Error Responses
|
|
|
|
| Code | Description |
|
|
| ---- | -------------------------------- |
|
|
| 400 | Invalid search query (too short) |
|
|
| 401 | Invalid or expired token |
|