+ {isAdmin && (
+ <>
+
+ {
+ const next = Array.isArray(value) ? value[0] ?? 'direct' : value;
+ onSearchModeChange(next === 'universal' ? 'universal' : 'direct');
+ }}
+ placeholder="Choose a mode"
+ widthClassName="w-full"
+ />
- // When formClassName is provided (initial state), the form carries its own padding;
- // otherwise use the default positioning classes for the header-bar state.
- const wrapperClassName = formClassName
- ? 'px-2'
- : 'px-2 lg:ml-[calc(3rem+1rem)] lg:w-[calc(50vw+4rem)]';
-
- const universalForm = (
- ;
onFindDownloads?: (book: Book) => void; // For Universal mode
- onSearchSeries?: (seriesName: string) => void; // Callback to search for series
+ onSearchSeries?: (seriesName: string, seriesId?: string) => void; // Callback to search for series
buttonState: ButtonStateInfo;
}
@@ -283,7 +283,7 @@ export const DetailsModal = ({ book, onClose, onDownload, onFindDownloads, onSea
diff --git a/src/frontend/src/components/ReleaseModal.tsx b/src/frontend/src/components/ReleaseModal.tsx
index 8784ec12..903531cd 100644
--- a/src/frontend/src/components/ReleaseModal.tsx
+++ b/src/frontend/src/components/ReleaseModal.tsx
@@ -92,7 +92,7 @@ interface ReleaseModalProps {
bookLanguages: Language[];
currentStatus: StatusData;
defaultReleaseSource?: string; // Default tab to show (e.g., 'direct_download')
- onSearchSeries?: (seriesName: string) => void; // Callback to search for series
+ onSearchSeries?: (seriesName: string, seriesId?: string) => void; // Callback to search for series
defaultShowManualQuery?: boolean;
isRequestMode?: boolean;
}
@@ -383,7 +383,7 @@ const ReleaseRow = ({
);
};
-// Shimmer block with wave animation - same as DownloadsSidebar
+// Shimmer block with wave animation
function ShimmerBlock({ className }: { className: string }) {
return (
- {onManualSearchToggle && (
-
);
- return wrappedForm;
+ return renderWrapper ? (
+ renderWrapper(settingsForm)
+ ) : (
+
- Search Options
-
+ )}
- )}
- {isManualSearch && (
- - Manual search queries release sources directly. Some sources may return limited metadata, which can affect file naming templates. -
- )} - {!isManualSearch && metadataSearchFields.length > 0 && ( + + )} + + {searchMode === 'direct' && ( +
- )}
-
- );
-
- const wrappedUniversalForm = renderWrapper ? (
- renderWrapper(universalForm)
- ) : (
-
-
- );
-
- return wrappedUniversalForm;
- }
-
- // Direct download mode: render existing hardcoded filters
- const form = (
-
- );
-
- const wrappedForm = renderWrapper ? (
- renderWrapper(form)
- ) : (
- {universalForm}
-
-
+ )}
{form}
+
+
+
+ );
};
diff --git a/src/frontend/src/components/DetailsModal.tsx b/src/frontend/src/components/DetailsModal.tsx
index 4fa3050f..a6f746b9 100644
--- a/src/frontend/src/components/DetailsModal.tsx
+++ b/src/frontend/src/components/DetailsModal.tsx
@@ -8,7 +8,7 @@ interface DetailsModalProps {
onClose: () => void;
onDownload: (book: Book) => Promise{settingsForm}
+ {
- onSearchSeries(book.series_name!);
+ onSearchSeries(book.series_name!, book.series_id);
handleClose();
}}
className="inline-flex items-center gap-1 px-2 py-1 text-xs font-medium text-emerald-600 dark:text-emerald-400 bg-emerald-50 dark:bg-emerald-900/20 rounded-full hover:bg-emerald-100 dark:hover:bg-emerald-900/40 transition-colors"
diff --git a/src/frontend/src/components/SearchBar.tsx b/src/frontend/src/components/SearchBar.tsx
index d0f888b7..ca35657d 100644
--- a/src/frontend/src/components/SearchBar.tsx
+++ b/src/frontend/src/components/SearchBar.tsx
@@ -1,10 +1,28 @@
-import { KeyboardEvent, InputHTMLAttributes, useRef, forwardRef, useImperativeHandle, useState, useEffect } from 'react';
+import {
+ InputHTMLAttributes,
+ RefObject,
+ forwardRef,
+ startTransition,
+ useDeferredValue,
+ useEffect,
+ useImperativeHandle,
+ useMemo,
+ useRef,
+ useState,
+} from 'react';
import { useSearchMode } from '../contexts/SearchModeContext';
-import { ContentType } from '../types';
+import {
+ ContentType,
+ MetadataSearchField,
+ QueryTargetOption,
+ SortOption,
+} from '../types';
+import { DynamicFieldOption, fetchFieldOptions } from '../services/api';
interface SearchBarProps {
- value: string;
- onChange: (value: string) => void;
+ value: string | number | boolean;
+ valueLabel?: string;
+ onChange: (value: string | number | boolean, label?: string) => void;
onSubmit: () => void;
isLoading?: boolean;
onAdvancedToggle?: () => void;
@@ -21,35 +39,123 @@ interface SearchBarProps {
searchButtonTitle?: string;
autoComplete?: string;
enterKeyHint?: InputHTMLAttributes['enterKeyHint'];
- // Content type selector props
contentType?: ContentType;
onContentTypeChange?: (type: ContentType) => void;
allowedContentTypes?: ContentType[];
- // Manual search mode
- isManualSearch?: boolean;
+ queryTargets?: QueryTargetOption[];
+ activeQueryTarget?: string;
+ onQueryTargetChange?: (target: string) => void;
+ activeQueryField?: MetadataSearchField | null;
disabled?: boolean;
- activeListLabel?: string;
}
export interface SearchBarHandle {
submit: () => void;
}
+const useDismiss = (
+ isOpen: boolean,
+ refs: RefObject[],
+ onClose: () => void,
+) => {
+ const onCloseRef = useRef(onClose);
+ onCloseRef.current = onClose;
+ const refsRef = useRef(refs);
+ refsRef.current = refs;
+
+ useEffect(() => {
+ if (!isOpen) return;
+
+ const handleClickOutside = (event: MouseEvent) => {
+ const target = event.target as Node;
+ if (refsRef.current.some((r) => r.current?.contains(target))) return;
+ onCloseRef.current();
+ };
+
+ const handleEscape = (event: KeyboardEvent) => {
+ if (event.key === 'Escape') onCloseRef.current();
+ };
+
+ document.addEventListener('mousedown', handleClickOutside);
+ document.addEventListener('keydown', handleEscape);
+ return () => {
+ document.removeEventListener('mousedown', handleClickOutside);
+ document.removeEventListener('keydown', handleEscape);
+ };
+ }, [isOpen]);
+};
+
+const autocompleteOptionsCache = new Map();
+const AUTOCOMPLETE_CACHE_MAX = 100;
+
+const BookIcon = () => (
+
+);
+
+const AudiobookIcon = () => (
+
+);
+
+const getDefaultPlaceholder = (
+ contentType: ContentType,
+ activeQueryTarget: QueryTargetOption | undefined,
+ fallback?: string,
+): string => {
+ if (fallback) return fallback;
+
+ if (!activeQueryTarget || activeQueryTarget.source === 'general') {
+ return contentType === 'ebook' ? 'Search Books' : 'Search Audiobooks';
+ }
+
+ if (activeQueryTarget.source === 'manual') {
+ return 'Search releases directly…';
+ }
+
+ const field = activeQueryTarget.field;
+ if (field?.placeholder) {
+ return field.placeholder;
+ }
+
+ return `Search by ${activeQueryTarget.label.toLowerCase()}…`;
+};
+
+const hasActiveValue = (value: string | number | boolean): boolean => {
+ if (typeof value === 'string') {
+ return value.trim().length > 0;
+ }
+ if (typeof value === 'number') {
+ return true;
+ }
+ return value;
+};
+
+const getClearedValue = (field?: MetadataSearchField | null): string | boolean => {
+ if (field?.type === 'CheckboxSearchField') {
+ return false;
+ }
+ return '';
+};
+
export const SearchBar = forwardRef(({
value,
+ valueLabel,
onChange,
onSubmit,
isLoading = false,
onAdvancedToggle,
- placeholder = 'Search by ISBN, title, author...',
+ placeholder,
inputAriaLabel = 'Search books',
className = '',
inputClassName = '',
controlsClassName = '',
clearButtonLabel = 'Clear search input',
clearButtonTitle = 'Clear search',
- advancedButtonLabel = 'Advanced Search',
- advancedButtonTitle = 'Advanced Search',
+ advancedButtonLabel = 'Search settings',
+ advancedButtonTitle = 'Search settings',
searchButtonLabel = 'Search books',
searchButtonTitle = 'Search',
autoComplete = 'off',
@@ -57,60 +163,186 @@ export const SearchBar = forwardRef(({
contentType = 'ebook',
onContentTypeChange,
allowedContentTypes,
- isManualSearch = false,
+ queryTargets = [],
+ activeQueryTarget = 'general',
+ onQueryTargetChange,
+ activeQueryField,
disabled = false,
- activeListLabel,
}, ref) => {
- const { searchMode, isUniversalMode } = useSearchMode();
+ const { searchMode } = useSearchMode();
const inputRef = useRef(null);
const buttonRef = useRef(null);
- const dropdownRef = useRef(null);
- const hasSearchQuery = value.trim().length > 0;
+ const onSubmitRef = useRef(onSubmit);
+ onSubmitRef.current = onSubmit;
+ const selectorRef = useRef(null);
+ const hasSearchQuery = hasActiveValue(value);
+ const [isSelectorOpen, setIsSelectorOpen] = useState(false);
+ const [dynamicOptions, setDynamicOptions] = useState([]);
+ const [isDynamicLoading, setIsDynamicLoading] = useState(false);
+ const [isSelectOpen, setIsSelectOpen] = useState(false);
+ const [autocompleteOptions, setAutocompleteOptions] = useState([]);
+ const [isAutocompleteLoading, setIsAutocompleteLoading] = useState(false);
+ const [isAutocompleteOpen, setIsAutocompleteOpen] = useState(false);
+ const [textInputValue, setTextInputValue] = useState('');
+ const selectTriggerRef = useRef(null);
+ const selectPanelRef = useRef(null);
+ const autocompletePanelRef = useRef(null);
+ const deferredTextInputValue = useDeferredValue(textInputValue);
- // Content type dropdown state
- const [isDropdownOpen, setIsDropdownOpen] = useState(false);
const hasMultipleContentTypes = !allowedContentTypes || allowedContentTypes.length !== 1;
- const showContentTypeSelector = isUniversalMode && !!onContentTypeChange && hasMultipleContentTypes;
+ const showContentTypeSelector = searchMode !== 'direct' && !!onContentTypeChange && hasMultipleContentTypes;
+ const showQueryTargetSelector = showContentTypeSelector || queryTargets.length > 1;
+ const inputPaddingClass = showQueryTargetSelector
+ ? 'pl-3 rounded-r-full'
+ : 'pl-4 rounded-full';
+ const searchInputClass = [
+ 'w-full min-w-0 py-3 border-0 outline-none search-input bg-transparent',
+ inputPaddingClass,
+ ].join(' ');
- // Dynamic placeholder based on content type, manual search, and list browsing
- const isContentTypeAware = isUniversalMode && !!onContentTypeChange;
- const effectivePlaceholder = activeListLabel
- ? `${activeListLabel} selected`
- : isManualSearch
- ? 'Search releases directly...'
- : isContentTypeAware
- ? (contentType === 'ebook' ? 'Search Books' : 'Search Audiobooks')
- : placeholder;
+ const activeTarget = useMemo(
+ () => queryTargets.find((target) => target.key === activeQueryTarget) ?? queryTargets[0],
+ [queryTargets, activeQueryTarget],
+ );
+ const showActiveTargetLabel = Boolean(activeTarget && activeTarget.source !== 'general');
- // Close dropdown on click outside or escape
+ useDismiss(isSelectorOpen, [selectorRef], () => setIsSelectorOpen(false));
+ useDismiss(isSelectOpen, [selectPanelRef, selectTriggerRef], () => setIsSelectOpen(false));
+ useDismiss(isAutocompleteOpen, [autocompletePanelRef, inputRef], () => setIsAutocompleteOpen(false));
+
+ // Close select dropdown when active field changes
useEffect(() => {
- if (!isDropdownOpen) return;
+ setIsSelectOpen(false);
+ setIsAutocompleteOpen(false);
+ setAutocompleteOptions([]);
+ }, [activeQueryField?.key, activeQueryField?.type]);
- const handleClickOutside = (event: MouseEvent) => {
- if (dropdownRef.current && !dropdownRef.current.contains(event.target as Node)) {
- setIsDropdownOpen(false);
- }
- };
+ // Load dynamic options when a DynamicSelectSearchField is active
+ const dynamicEndpoint =
+ activeQueryField?.type === 'DynamicSelectSearchField'
+ ? activeQueryField.options_endpoint
+ : null;
+ const autocompleteEndpoint =
+ activeQueryField?.type === 'TextSearchField'
+ ? activeQueryField.suggestions_endpoint ?? null
+ : null;
+ const autocompleteMinQueryLength =
+ activeQueryField?.type === 'TextSearchField'
+ ? activeQueryField.suggestions_min_query_length ?? 2
+ : 2;
+ const autocompleteEmptyMessage =
+ activeQueryField?.key === 'author'
+ ? 'No authors found'
+ : activeQueryField?.key === 'title'
+ ? 'No titles found'
+ : activeQueryField?.key === 'series'
+ ? 'No series found'
+ : 'No suggestions found';
- const handleEscape = (event: KeyboardEvent) => {
- if (event.key === 'Escape') {
- setIsDropdownOpen(false);
- }
- };
+ useEffect(() => {
+ if (!dynamicEndpoint) {
+ setDynamicOptions([]);
+ return;
+ }
- document.addEventListener('mousedown', handleClickOutside);
- document.addEventListener('keydown', handleEscape as unknown as EventListener);
+ let cancelled = false;
+ setIsDynamicLoading(true);
+
+ fetchFieldOptions(dynamicEndpoint).then((loaded) => {
+ if (cancelled) return;
+ setDynamicOptions(loaded.map((o) => ({ value: o.value, label: o.label })));
+ setIsDynamicLoading(false);
+ }).catch(() => {
+ if (cancelled) return;
+ setDynamicOptions([]);
+ setIsDynamicLoading(false);
+ });
+
+ return () => { cancelled = true; };
+ }, [dynamicEndpoint]);
+
+ useEffect(() => {
+ if (!autocompleteEndpoint && activeQueryField?.type !== 'TextSearchField') {
+ setTextInputValue(typeof value === 'string' ? value : String(value ?? ''));
+ return;
+ }
+
+ const nextValue =
+ autocompleteEndpoint && valueLabel && typeof value === 'string' && value.trim() !== ''
+ ? valueLabel
+ : typeof value === 'string'
+ ? value
+ : String(value ?? '');
+
+ setTextInputValue(nextValue);
+ }, [activeQueryField?.key, activeQueryField?.type, autocompleteEndpoint, value, valueLabel]);
+
+ useEffect(() => {
+ if (!autocompleteEndpoint || !isAutocompleteOpen) {
+ setAutocompleteOptions([]);
+ setIsAutocompleteLoading(false);
+ return;
+ }
+
+ const normalizedQuery = deferredTextInputValue.trim();
+ if (normalizedQuery.length < autocompleteMinQueryLength) {
+ setAutocompleteOptions([]);
+ setIsAutocompleteLoading(false);
+ return;
+ }
+
+ const cacheKey = `${autocompleteEndpoint}::${normalizedQuery.toLowerCase()}`;
+ if (autocompleteOptionsCache.has(cacheKey)) {
+ startTransition(() => {
+ setAutocompleteOptions(autocompleteOptionsCache.get(cacheKey) ?? []);
+ });
+ setIsAutocompleteLoading(false);
+ return;
+ }
+
+ let cancelled = false;
+ const timeoutId = window.setTimeout(() => {
+ setIsAutocompleteLoading(true);
+ fetchFieldOptions(autocompleteEndpoint, normalizedQuery)
+ .then((loaded) => {
+ if (cancelled) return;
+ if (autocompleteOptionsCache.size >= AUTOCOMPLETE_CACHE_MAX) {
+ const oldest = autocompleteOptionsCache.keys().next().value;
+ if (oldest !== undefined) autocompleteOptionsCache.delete(oldest);
+ }
+ autocompleteOptionsCache.set(cacheKey, loaded);
+ startTransition(() => {
+ setAutocompleteOptions(loaded);
+ });
+ setIsAutocompleteLoading(false);
+ })
+ .catch(() => {
+ if (cancelled) return;
+ startTransition(() => {
+ setAutocompleteOptions([]);
+ });
+ setIsAutocompleteLoading(false);
+ });
+ }, 260);
return () => {
- document.removeEventListener('mousedown', handleClickOutside);
- document.removeEventListener('keydown', handleEscape as unknown as EventListener);
+ cancelled = true;
+ window.clearTimeout(timeoutId);
};
- }, [isDropdownOpen]);
+ }, [autocompleteEndpoint, autocompleteMinQueryLength, deferredTextInputValue, isAutocompleteOpen]);
- const handleContentTypeSelect = (type: ContentType) => {
- onContentTypeChange?.(type);
- setIsDropdownOpen(false);
- };
+ // Resolve options for any select-type field
+ const selectOptions: SortOption[] = useMemo(() => {
+ if (activeQueryField?.type === 'SelectSearchField') {
+ return activeQueryField.options;
+ }
+ if (activeQueryField?.type === 'DynamicSelectSearchField') {
+ return dynamicOptions;
+ }
+ return [];
+ }, [activeQueryField, dynamicOptions]);
+
+ const isSelectField = activeQueryField?.type === 'SelectSearchField' || activeQueryField?.type === 'DynamicSelectSearchField';
useImperativeHandle(ref, () => ({
submit: () => {
@@ -118,7 +350,7 @@ export const SearchBar = forwardRef(({
},
}));
- const handleKeyDown = (e: KeyboardEvent) => {
+ const handleKeyDown = (e: React.KeyboardEvent) => {
if (e.key === 'Enter') {
if (disabled) {
e.preventDefault();
@@ -130,161 +362,320 @@ export const SearchBar = forwardRef(({
};
const handleClearSearch = () => {
- onChange('');
+ onChange(getClearedValue(activeQueryField));
+ setIsSelectOpen(false);
+ setIsAutocompleteOpen(false);
+ setAutocompleteOptions([]);
+ setTextInputValue('');
inputRef.current?.focus();
};
- const wrapperClasses = ['relative', className].filter(Boolean).join(' ').trim();
- const inputClasses = [
- 'w-full pr-40 py-3 border outline-none search-input',
- showContentTypeSelector ? 'pl-3 rounded-r-full' : 'pl-4 rounded-full',
- disabled ? 'opacity-60 cursor-not-allowed' : '',
- inputClassName,
- ]
- .filter(Boolean)
- .join(' ')
- .trim();
+ const handleContentTypeSelect = (type: ContentType) => {
+ onContentTypeChange?.(type);
+ setIsSelectorOpen(false);
+ };
+
+ const handleQueryTargetSelect = (targetKey: string) => {
+ onQueryTargetChange?.(targetKey);
+ setIsSelectorOpen(false);
+ };
+
+ const effectivePlaceholder = getDefaultPlaceholder(contentType, activeTarget, placeholder);
+ const effectiveInputAriaLabel = activeTarget
+ ? `${inputAriaLabel}: ${activeTarget.label}`
+ : inputAriaLabel;
+
+ const selectDropdownOpen = isSelectField && isSelectOpen && selectOptions.length > 0;
+ const autocompleteDropdownOpen =
+ Boolean(autocompleteEndpoint)
+ && isAutocompleteOpen
+ && textInputValue.trim().length >= autocompleteMinQueryLength;
+ const wrapperClasses = ['relative flex items-center rounded-full border', className].filter(Boolean).join(' ').trim();
const controlsClasses = [
- 'absolute inset-y-0 right-0 flex items-center gap-1 pr-2',
+ 'flex items-center gap-1 pr-2 flex-shrink-0',
controlsClassName,
]
.filter(Boolean)
.join(' ')
.trim();
- // Content type icons
- const BookIcon = () => (
-
- );
+ const renderActiveInput = () => {
+ if (!activeQueryField || activeQueryField.type === 'TextSearchField') {
+ const inputName = activeQueryField ? `${activeQueryField.key}-search` : 'search-input';
+ return (
+ {
+ const nextValue = e.target.value;
+ if (autocompleteEndpoint) {
+ setTextInputValue(nextValue);
+ setIsAutocompleteOpen(nextValue.trim().length >= autocompleteMinQueryLength);
+ setIsSelectOpen(false);
+ setIsSelectorOpen(false);
+ onChange(nextValue);
+ return;
+ }
+ onChange(nextValue);
+ }}
+ onFocus={() => {
+ if (autocompleteEndpoint && textInputValue.trim().length >= autocompleteMinQueryLength) {
+ setIsAutocompleteOpen(true);
+ }
+ }}
+ onKeyDown={handleKeyDown}
+ ref={inputRef}
+ />
+ );
+ }
- const AudiobookIcon = () => (
-
- );
+ switch (activeQueryField.type) {
+ case 'NumberSearchField':
+ return (
+ {
+ const raw = e.target.value;
+ if (!raw) {
+ onChange('');
+ return;
+ }
+ const nextValue = Number.parseInt(raw, 10);
+ if (!Number.isNaN(nextValue)) {
+ onChange(nextValue);
+ }
+ }}
+ onKeyDown={handleKeyDown}
+ ref={inputRef}
+ />
+ );
+
+ case 'SelectSearchField':
+ case 'DynamicSelectSearchField': {
+ const currentValue = typeof value === 'string' ? value : String(value ?? '');
+ const selectedOption = selectOptions.find((o) => o.value === currentValue);
+ return (
+
+ );
+ }
+
+ case 'CheckboxSearchField':
+ return (
+
+ );
+
+ default:
+ return null;
+ }
+ };
return (
-
-
+
+ {item.title}
+
+
) : (
item.title
);
@@ -652,6 +654,8 @@ export const ActivityCard = ({
? getProgressConfig(badge.visualStatus, badge.progress)
: null;
+ const isError = badge.visualStatus === 'error';
+
return (
();
+const OPTIONS_CACHE_MAX = 50;
+
interface DynamicDropdownProps {
endpoint: string;
value: string;
onChange: (value: string, label?: string) => void;
placeholder?: string;
+ widthClassName?: string;
+ buttonClassName?: string;
+ triggerChrome?: 'default' | 'minimal';
}
const buildOptions = (
@@ -24,15 +30,25 @@ export const DynamicDropdown = ({
value,
onChange,
placeholder = 'Select...',
+ widthClassName,
+ buttonClassName,
+ triggerChrome = 'default',
}: DynamicDropdownProps) => {
- const [options, setOptions] = useState([]);
- const [isLoading, setIsLoading] = useState(true);
+ const cachedOptions = optionsCache.get(endpoint) ?? [];
+ const [options, setOptions] = useState(cachedOptions);
+ const [isLoading, setIsLoading] = useState(cachedOptions.length === 0);
const [loadError, setLoadError] = useState(null);
useEffect(() => {
let isMounted = true;
const load = async () => {
+ if (optionsCache.has(endpoint)) {
+ setOptions(optionsCache.get(endpoint) ?? []);
+ setIsLoading(false);
+ return;
+ }
+
setIsLoading(true);
setLoadError(null);
@@ -41,6 +57,11 @@ export const DynamicDropdown = ({
if (!isMounted) {
return;
}
+ if (optionsCache.size >= OPTIONS_CACHE_MAX) {
+ const oldest = optionsCache.keys().next().value;
+ if (oldest !== undefined) optionsCache.delete(oldest);
+ }
+ optionsCache.set(endpoint, loaded);
setOptions(loaded);
} catch (error) {
if (!isMounted) {
@@ -86,6 +107,9 @@ export const DynamicDropdown = ({
value={value}
onChange={handleChange}
placeholder={placeholder}
+ widthClassName={widthClassName}
+ buttonClassName={buttonClassName}
+ triggerChrome={triggerChrome}
/>
);
};
diff --git a/src/frontend/src/components/shared/Tooltip.tsx b/src/frontend/src/components/shared/Tooltip.tsx
index 478ad89d..fe15898e 100644
--- a/src/frontend/src/components/shared/Tooltip.tsx
+++ b/src/frontend/src/components/shared/Tooltip.tsx
@@ -10,6 +10,7 @@ interface TooltipProps {
unstyled?: boolean;
triggerClassName?: string;
alwaysWrap?: boolean;
+ interactive?: boolean;
}
export function Tooltip({
@@ -21,6 +22,7 @@ export function Tooltip({
unstyled = false,
triggerClassName = 'inline-flex max-w-full',
alwaysWrap = false,
+ interactive = false,
}: TooltipProps) {
const [isVisible, setIsVisible] = useState(false);
const [coords, setCoords] = useState<{ top: number; left: number } | null>(null);
@@ -67,11 +69,37 @@ export function Tooltip({
}, delay);
};
+ const isOverTooltipRef = useRef(false);
+
const hideTooltip = () => {
if (timeoutRef.current) {
clearTimeout(timeoutRef.current);
timeoutRef.current = null;
}
+ if (interactive) {
+ // Small delay so the user can move the mouse from trigger to tooltip
+ timeoutRef.current = setTimeout(() => {
+ if (!isOverTooltipRef.current) {
+ setIsVisible(false);
+ setCoords(null);
+ }
+ }, 100);
+ return;
+ }
+ setIsVisible(false);
+ setCoords(null);
+ };
+
+ const handleTooltipMouseEnter = () => {
+ isOverTooltipRef.current = true;
+ if (timeoutRef.current) {
+ clearTimeout(timeoutRef.current);
+ timeoutRef.current = null;
+ }
+ };
+
+ const handleTooltipMouseLeave = () => {
+ isOverTooltipRef.current = false;
setIsVisible(false);
setCoords(null);
};
@@ -164,7 +192,9 @@ export function Tooltip({
- {/* Content Type Selector */}
- {showContentTypeSelector && (
- ) => void;
- // Universal mode props
- metadataSearchFields?: MetadataSearchField[];
- searchFieldValues?: Record;
- onSearchFieldChange?: (key: string, value: string | number | boolean, label?: string) => void;
contentType?: ContentType;
onContentTypeChange?: (type: ContentType) => void;
allowedContentTypes?: ContentType[];
- // Manual search mode (universal only)
- isManualSearch?: boolean;
- onManualSearchToggle?: () => void;
- searchDisabled?: boolean;
- activeListLabel?: string;
+ activeQueryField?: MetadataSearchField | null;
+ searchMode: SearchMode;
+ onSearchModeChange: (mode: SearchMode) => void;
+ metadataProviders?: MetadataProviderSummary[];
+ activeMetadataProvider?: string | null;
+ onMetadataProviderChange?: (provider: string) => void;
+ isAdmin?: boolean;
}
export const SearchSection = ({
@@ -38,39 +45,28 @@ export const SearchSection = ({
isInitialState,
bookLanguages,
defaultLanguage,
- supportedFormats,
logoUrl,
- searchInput,
- onSearchInputChange,
+ queryValue,
+ queryValueLabel,
+ onQueryValueChange,
+ queryTargets,
+ activeQueryTarget,
+ onQueryTargetChange,
showAdvanced,
onAdvancedToggle,
advancedFilters,
onAdvancedFiltersChange,
- metadataSearchFields,
- searchFieldValues,
- onSearchFieldChange,
contentType = 'ebook',
onContentTypeChange,
allowedContentTypes,
- isManualSearch = false,
- onManualSearchToggle,
- searchDisabled = false,
- activeListLabel,
+ activeQueryField,
+ searchMode,
+ onSearchModeChange,
+ metadataProviders,
+ activeMetadataProvider,
+ onMetadataProviderChange,
+ isAdmin = false,
}: SearchSectionProps) => {
- const { searchMode } = useSearchMode();
-
- const handleSearch = () => {
- const query = buildSearchQuery({
- searchInput,
- showAdvanced,
- advancedFilters,
- bookLanguages,
- defaultLanguage,
- searchMode,
- });
- onSearch(query);
- };
-
return (
form}
- metadataSearchFields={metadataSearchFields}
- searchFieldValues={searchFieldValues}
- onSearchFieldChange={onSearchFieldChange}
- onSubmit={handleSearch}
- isManualSearch={isManualSearch}
- onManualSearchToggle={onManualSearchToggle}
+ searchMode={searchMode}
+ onSearchModeChange={onSearchModeChange}
+ metadataProviders={metadataProviders}
+ activeMetadataProvider={activeMetadataProvider}
+ onMetadataProviderChange={onMetadataProviderChange}
+ contentType={contentType}
+ isAdmin={isAdmin}
/>
diff --git a/src/frontend/src/components/activity/ActivityCard.tsx b/src/frontend/src/components/activity/ActivityCard.tsx
index fe905090..ba56fc87 100644
--- a/src/frontend/src/components/activity/ActivityCard.tsx
+++ b/src/frontend/src/components/activity/ActivityCard.tsx
@@ -518,12 +518,14 @@ export const ActivityCard = ({
const titleNode =
canShowDownloadLink && item.downloadBookId ? (
-
- {item.title}
-
+
+
);
});
diff --git a/src/frontend/src/components/SearchSection.tsx b/src/frontend/src/components/SearchSection.tsx
index aa149862..e7130675 100644
--- a/src/frontend/src/components/SearchSection.tsx
+++ b/src/frontend/src/components/SearchSection.tsx
@@ -1,35 +1,42 @@
-import { AdvancedFilterState, Language, MetadataSearchField, ContentType } from '../types';
-import { buildSearchQuery } from '../utils/buildSearchQuery';
-import { useSearchMode } from '../contexts/SearchModeContext';
+import {
+ AdvancedFilterState,
+ Language,
+ MetadataSearchField,
+ ContentType,
+ QueryTargetOption,
+ SearchMode,
+ MetadataProviderSummary,
+} from '../types';
import { AdvancedFilters } from './AdvancedFilters';
import { SearchBar } from './SearchBar';
interface SearchSectionProps {
- onSearch: (query: string) => void;
+ onSearch: () => void;
isLoading: boolean;
isInitialState: boolean;
bookLanguages: Language[];
defaultLanguage: string[];
- supportedFormats: string[];
logoUrl: string;
- searchInput: string;
- onSearchInputChange: (value: string) => void;
+ queryValue: string | number | boolean;
+ queryValueLabel?: string;
+ onQueryValueChange: (value: string | number | boolean, label?: string) => void;
+ queryTargets: QueryTargetOption[];
+ activeQueryTarget: string;
+ onQueryTargetChange: (key: string) => void;
showAdvanced: boolean;
- onAdvancedToggle: () => void;
+ onAdvancedToggle?: () => void;
advancedFilters: AdvancedFilterState;
onAdvancedFiltersChange: (updates: Partial
+ {showQueryTargetSelector && (
+
+
- {/* Divider */}
- {/* Dropdown Menu */}
- {isDropdownOpen && (
+ {isSelectorOpen && (
)}
- {/* Search Input */}
- onChange(e.target.value)}
- onKeyDown={handleKeyDown}
- ref={inputRef}
- />
-
-
)}
+ {renderActiveInput()}
+
- {/* Right-side controls */}
{hasSearchQuery && (
+
+ {selectDropdownOpen && (
+
+
+ )}
+
+ {autocompleteDropdownOpen && (
+
+ {selectOptions.map((option) => {
+ const currentValue = typeof value === 'string' ? value : String(value ?? '');
+ const isSelected = option.value === currentValue;
+ return (
+
+ );
+ })}
+
+
+
+ )}
+ {isAutocompleteLoading && (
+
+
+ Searching…
+
+ )}
+
+ {!isAutocompleteLoading && autocompleteOptions.length === 0 && (
+
+ {autocompleteEmptyMessage}
+
+ )}
+
+ {!isAutocompleteLoading && autocompleteOptions.map((option) => (
+
+ ))}
+ format !== 'pdf');
+const DEFAULT_FORMAT_SELECTION = DEFAULT_SUPPORTED_FORMATS;
interface UseSearchOptions {
showToast: (message: string, type: 'info' | 'success' | 'error') => void;
@@ -30,14 +30,15 @@ interface UseSearchReturn {
advancedFilters: AdvancedFilterState;
setAdvancedFilters: React.Dispatch>;
updateAdvancedFilters: (updates: Partial) => void;
- handleSearch: (
- query: string,
- config: AppConfig | null,
- fieldValues?: Record,
- contentTypeOverride?: ContentType
- ) => Promise;
+ handleSearch: (params: {
+ query: string;
+ config: AppConfig | null;
+ fieldValues?: Record;
+ contentTypeOverride?: ContentType;
+ searchMode?: SearchMode;
+ providerOverride?: string;
+ }) => Promise;
handleResetSearch: (config: AppConfig | null) => void;
- handleSortChange: (value: string, config: AppConfig | null) => void;
resetSortFilter: () => void;
// Universal mode search field values
searchFieldValues: SearchFieldValues;
@@ -46,7 +47,7 @@ interface UseSearchReturn {
// Pagination (universal mode only)
hasMore: boolean;
isLoadingMore: boolean;
- loadMore: (config: AppConfig | null) => Promise;
+ loadMore: (config: AppConfig | null, searchMode?: SearchMode) => Promise;
totalFound: number;
}
@@ -84,6 +85,8 @@ export function useSearch(options: UseSearchOptions): UseSearchReturn {
query: string;
sort: string;
fieldValues: SearchFieldValues;
+ providerOverride?: string;
+ contentType: ContentType;
} | null>(null);
const updateAdvancedFilters = useCallback((updates: Partial) => {
@@ -92,11 +95,20 @@ export function useSearch(options: UseSearchOptions): UseSearchReturn {
const updateSearchFieldValue = useCallback((key: string, value: string | number | boolean, label?: string) => {
setSearchFieldValues(prev => ({ ...prev, [key]: value }));
- if (label !== undefined) {
- setSearchFieldLabels(prev => ({ ...prev, [key]: label }));
- } else if (!value) {
- setSearchFieldLabels(prev => { const next = { ...prev }; delete next[key]; return next; });
- }
+ setSearchFieldLabels(prev => {
+ const next = { ...prev };
+ if (label !== undefined) {
+ if (label) {
+ next[key] = label;
+ } else {
+ delete next[key];
+ }
+ return next;
+ }
+
+ delete next[key];
+ return next;
+ });
}, []);
const resetSortFilter = useCallback(() => {
@@ -118,14 +130,23 @@ export function useSearch(options: UseSearchOptions): UseSearchReturn {
showToast(message, 'error');
}, [setIsAuthenticated, authRequired, navigate, showToast]);
- const handleSearch = useCallback(async (
- query: string,
- config: AppConfig | null,
- fieldValues?: Record,
- contentTypeOverride?: ContentType
- ) => {
+ const handleSearch = useCallback(async ({
+ query,
+ config,
+ fieldValues,
+ contentTypeOverride,
+ searchMode: searchModeOverride,
+ providerOverride,
+ }: {
+ query: string;
+ config: AppConfig | null;
+ fieldValues?: Record;
+ contentTypeOverride?: ContentType;
+ searchMode?: SearchMode;
+ providerOverride?: string;
+ }) => {
const effectiveContentType = contentTypeOverride ?? contentType;
- const searchMode = config?.search_mode || 'direct';
+ const searchMode = (searchModeOverride ?? config?.search_mode) || 'direct';
// In universal mode, check if we have either a query or field values
if (searchMode === 'universal') {
@@ -134,11 +155,7 @@ export function useSearch(options: UseSearchOptions): UseSearchReturn {
// Use explicitly passed fieldValues if provided, otherwise fall back to state
const effectiveFieldValues = fieldValues ?? searchFieldValues;
const hasFieldValues = Object.values(effectiveFieldValues).some(v => v !== '' && v !== false);
-
- // Auto-set sort to series_order when searching by series field
- const seriesValue = effectiveFieldValues.series;
- const hasSeriesSearch = typeof seriesValue === 'string' && seriesValue.trim() !== '';
- const sort = hasSeriesSearch ? 'series_order' : (params.get('sort') || 'relevance');
+ const sort = params.get('sort') || 'relevance';
if (!searchQuery && !hasFieldValues) {
setBooks([]);
@@ -150,11 +167,6 @@ export function useSearch(options: UseSearchOptions): UseSearchReturn {
return;
}
- // Update UI sort dropdown to reflect series_order when searching by series
- if (hasSeriesSearch) {
- setAdvancedFilters(prev => ({ ...prev, sort: 'series_order' }));
- }
-
setIsSearching(true);
setLastSearchQuery(query);
// Reset pagination for new search
@@ -163,13 +175,27 @@ export function useSearch(options: UseSearchOptions): UseSearchReturn {
setTotalFound(0);
try {
- const result = await searchMetadata(searchQuery, 40, sort, effectiveFieldValues, 1, effectiveContentType);
+ const result = await searchMetadata(
+ searchQuery,
+ 40,
+ sort,
+ effectiveFieldValues,
+ 1,
+ effectiveContentType,
+ providerOverride,
+ );
if (result.books.length > 0) {
setBooks(result.books);
setHasMore(result.hasMore);
setTotalFound(result.totalFound);
// Store params for loadMore
- lastSearchParamsRef.current = { query: searchQuery, sort, fieldValues: effectiveFieldValues };
+ lastSearchParamsRef.current = {
+ query: searchQuery,
+ sort,
+ fieldValues: effectiveFieldValues,
+ providerOverride,
+ contentType: effectiveContentType,
+ };
} else {
setBooks([]);
setHasMore(false);
@@ -237,6 +263,7 @@ export function useSearch(options: UseSearchOptions): UseSearchReturn {
// Reset universal mode search field values
setSearchFieldValues({});
+ setSearchFieldLabels({});
// Reset pagination
setCurrentPage(1);
@@ -246,19 +273,27 @@ export function useSearch(options: UseSearchOptions): UseSearchReturn {
}, [onSearchReset]);
// Load more results (universal mode pagination)
- const loadMore = useCallback(async (config: AppConfig | null) => {
- const searchMode = config?.search_mode || 'direct';
+ const loadMore = useCallback(async (config: AppConfig | null, searchModeOverride?: SearchMode) => {
+ const searchMode = (searchModeOverride ?? config?.search_mode) || 'direct';
if (searchMode !== 'universal') return;
if (!lastSearchParamsRef.current) return;
if (isLoadingMore || !hasMore) return;
- const { query, sort, fieldValues } = lastSearchParamsRef.current;
+ const { query, sort, fieldValues, providerOverride, contentType: searchContentType } = lastSearchParamsRef.current;
const nextPage = currentPage + 1;
setIsLoadingMore(true);
try {
- const result = await searchMetadata(query, 40, sort, fieldValues, nextPage, contentType);
+ const result = await searchMetadata(
+ query,
+ 40,
+ sort,
+ fieldValues,
+ nextPage,
+ searchContentType,
+ providerOverride,
+ );
if (result.books.length > 0) {
setBooks(prev => [...prev, ...result.books]);
setHasMore(result.hasMore);
@@ -271,23 +306,7 @@ export function useSearch(options: UseSearchOptions): UseSearchReturn {
} finally {
setIsLoadingMore(false);
}
- }, [currentPage, hasMore, isLoadingMore, handleSearchError, contentType]);
-
- const handleSortChange = useCallback((value: string, config: AppConfig | null) => {
- updateAdvancedFilters({ sort: value });
- if (!lastSearchQuery) return;
-
- const params = new URLSearchParams(lastSearchQuery);
- if (value) {
- params.set('sort', value);
- } else {
- params.delete('sort');
- }
-
- const nextQuery = params.toString();
- if (!nextQuery) return;
- handleSearch(nextQuery, config);
- }, [lastSearchQuery, updateAdvancedFilters, handleSearch]);
+ }, [currentPage, hasMore, isLoadingMore, handleSearchError]);
return {
books,
@@ -303,7 +322,6 @@ export function useSearch(options: UseSearchOptions): UseSearchReturn {
updateAdvancedFilters,
handleSearch,
handleResetSearch,
- handleSortChange,
resetSortFilter,
// Universal mode search field values
searchFieldValues,
diff --git a/src/frontend/src/services/api.ts b/src/frontend/src/services/api.ts
index 191dedbb..6b756268 100644
--- a/src/frontend/src/services/api.ts
+++ b/src/frontend/src/services/api.ts
@@ -9,6 +9,8 @@ import {
RequestPolicyResponse,
CreateRequestPayload,
RequestRecord,
+ MetadataProvidersResponse,
+ MetadataSearchConfig,
} from '../types';
import { SettingsResponse, ActionResult, UpdateResult, SettingsTab } from '../types/settings';
import {
@@ -34,6 +36,8 @@ const API_BASE = getApiBase();
// API endpoints
const API = {
metadataSearch: `${API_BASE}/metadata/search`,
+ metadataConfig: `${API_BASE}/metadata/config`,
+ metadataProviders: `${API_BASE}/metadata/providers`,
status: `${API_BASE}/status`,
cancelDownload: `${API_BASE}/download`,
retryDownload: `${API_BASE}/download`,
@@ -244,7 +248,8 @@ export const searchMetadata = async (
sort: string = 'relevance',
fields: Record = {},
page: number = 1,
- contentType: string = 'ebook'
+ contentType: string = 'ebook',
+ provider?: string
): Promise => {
const hasFields = Object.values(fields).some(v => v !== '' && v !== false);
@@ -260,6 +265,9 @@ export const searchMetadata = async (
params.set('sort', sort);
params.set('page', String(page));
params.set('content_type', contentType);
+ if (provider) {
+ params.set('provider', provider);
+ }
// Add custom search field values
Object.entries(fields).forEach(([key, value]) => {
@@ -278,13 +286,44 @@ export const searchMetadata = async (
};
};
-export const fetchFieldOptions = async (endpoint: string): Promise => {
+export const getMetadataProviders = async (): Promise => {
+ return fetchJSON(API.metadataProviders);
+};
+
+export const getMetadataSearchConfig = async (
+ contentType: string = 'ebook',
+ provider?: string,
+): Promise => {
+ const params = new URLSearchParams({
+ content_type: contentType,
+ });
+
+ if (provider) {
+ params.set('provider', provider);
+ }
+
+ return fetchJSON(`${API.metadataConfig}?${params.toString()}`);
+};
+
+export const fetchFieldOptions = async (
+ endpoint: string,
+ query?: string,
+): Promise => {
const normalizedEndpoint =
endpoint.startsWith('http://') || endpoint.startsWith('https://')
? endpoint
: withBasePath(endpoint);
- const response = await fetchJSON<{ options?: unknown }>(normalizedEndpoint);
+ const url = new URL(normalizedEndpoint, window.location.origin);
+ if (query && query.trim().length > 0) {
+ url.searchParams.set('query', query.trim());
+ }
+
+ const requestUrl = url.origin === window.location.origin
+ ? `${url.pathname}${url.search}`
+ : url.toString();
+
+ const response = await fetchJSON<{ options?: unknown }>(requestUrl);
if (!Array.isArray(response.options)) {
return [];
}
diff --git a/src/frontend/src/styles.css b/src/frontend/src/styles.css
index 11cb2c0c..0daa3026 100644
--- a/src/frontend/src/styles.css
+++ b/src/frontend/src/styles.css
@@ -433,6 +433,11 @@ button:disabled {
appearance: none;
}
+.search-input::placeholder {
+ color: var(--text);
+ opacity: 0.5;
+}
+
.search-input::-webkit-search-cancel-button,
.search-input::-webkit-search-decoration,
.search-input::-webkit-search-results-button,
diff --git a/src/frontend/src/tests/queryTargets.node.test.ts b/src/frontend/src/tests/queryTargets.node.test.ts
new file mode 100644
index 00000000..b85edd01
--- /dev/null
+++ b/src/frontend/src/tests/queryTargets.node.test.ts
@@ -0,0 +1,47 @@
+import * as assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import { buildQueryTargets, getDefaultQueryTargetKey } from '../utils/queryTargets.js';
+
+describe('queryTargets', () => {
+ it('builds direct-mode query targets', () => {
+ const targets = buildQueryTargets({ searchMode: 'direct' });
+
+ assert.deepEqual(
+ targets.map((target) => target.key),
+ ['general', 'isbn', 'author', 'title'],
+ );
+ });
+
+ it('builds universal query targets from provider fields', () => {
+ const targets = buildQueryTargets({
+ searchMode: 'universal',
+ metadataSearchFields: [
+ {
+ key: 'author',
+ label: 'Author',
+ type: 'TextSearchField',
+ description: 'Search by author name',
+ },
+ {
+ key: 'hardcover_list',
+ label: 'List',
+ type: 'DynamicSelectSearchField',
+ options_endpoint: '/api/metadata/field-options?provider=hardcover&field=hardcover_list',
+ description: 'Browse books from a list',
+ },
+ ],
+ manualSearchAllowed: true,
+ });
+
+ assert.deepEqual(
+ targets.map((target) => target.key),
+ ['general', 'author', 'hardcover_list', 'manual'],
+ );
+ assert.equal(targets[1]?.source, 'provider-field');
+ assert.equal(targets[3]?.source, 'manual');
+ });
+
+ it('falls back to general when choosing a default target', () => {
+ assert.equal(getDefaultQueryTargetKey([]), 'general');
+ });
+});
diff --git a/src/frontend/src/types/index.ts b/src/frontend/src/types/index.ts
index 59893d20..9e98bd95 100644
--- a/src/frontend/src/types/index.ts
+++ b/src/frontend/src/types/index.ts
@@ -43,6 +43,7 @@ export interface Book {
source_url?: string; // Link to book on provider's site
display_fields?: DisplayField[]; // Provider-specific display data
// Series info (if book is part of a series)
+ series_id?: string; // Provider-specific series ID
series_name?: string; // Name of the series
series_position?: number; // This book's position (e.g., 3, 1.5 for novellas)
series_count?: number; // Total books in the series
@@ -133,6 +134,8 @@ interface SearchFieldBase {
export interface TextSearchField extends SearchFieldBase {
type: 'TextSearchField';
+ suggestions_endpoint?: string;
+ suggestions_min_query_length?: number;
}
export interface NumberSearchField extends SearchFieldBase {
@@ -164,6 +167,20 @@ export type MetadataSearchField =
| CheckboxSearchField
| DynamicSelectSearchField;
+export type QueryTargetSource =
+ | 'general'
+ | 'manual'
+ | 'direct-field'
+ | 'provider-field';
+
+export interface QueryTargetOption {
+ key: string;
+ label: string;
+ description?: string;
+ source: QueryTargetSource;
+ field?: MetadataSearchField;
+}
+
// App configuration
// Content type for search (ebook vs audiobook)
export type ContentType = 'ebook' | 'audiobook';
@@ -251,6 +268,37 @@ export interface AppConfig {
metadata_default_sort: string; // Default sort for universal mode (from metadata provider)
}
+export interface MetadataProviderSummary {
+ name: string;
+ display_name: string;
+ requires_auth: boolean;
+ enabled: boolean;
+ available: boolean;
+}
+
+export interface MetadataProvidersResponse {
+ providers: MetadataProviderSummary[];
+ configured_provider: string | null;
+ configured_provider_audiobook: string | null;
+}
+
+export interface MetadataCapability {
+ key: string;
+ field_key?: string;
+ sort?: string;
+}
+
+export interface MetadataSearchConfig {
+ provider: string | null;
+ display_name: string | null;
+ enabled: boolean;
+ available: boolean;
+ search_fields: MetadataSearchField[];
+ capabilities: MetadataCapability[];
+ sort_options: SortOption[];
+ default_sort: string;
+}
+
// Authentication types
export interface LoginCredentials {
username: string;
diff --git a/src/frontend/src/utils/bookTransformers.ts b/src/frontend/src/utils/bookTransformers.ts
index e1886f89..6617f0eb 100644
--- a/src/frontend/src/utils/bookTransformers.ts
+++ b/src/frontend/src/utils/bookTransformers.ts
@@ -25,6 +25,7 @@ export interface MetadataBookData {
icon?: string;
}>;
// Series info
+ series_id?: string;
series_name?: string;
series_position?: number;
series_count?: number;
@@ -88,6 +89,7 @@ export function transformMetadataToBook(data: MetadataBookData): Book {
genres: data.genres,
source_url: data.source_url,
display_fields: data.display_fields,
+ series_id: data.series_id,
series_name: data.series_name,
series_position: data.series_position,
series_count: data.series_count,
diff --git a/src/frontend/src/utils/buildSearchQuery.ts b/src/frontend/src/utils/buildSearchQuery.ts
index 6f075259..beabd8f9 100644
--- a/src/frontend/src/utils/buildSearchQuery.ts
+++ b/src/frontend/src/utils/buildSearchQuery.ts
@@ -12,7 +12,7 @@ interface BuildSearchQueryOptions {
export const buildSearchQuery = ({
searchInput,
- showAdvanced,
+ showAdvanced: _showAdvanced,
advancedFilters,
bookLanguages,
defaultLanguage,
@@ -34,20 +34,18 @@ export const buildSearchQuery = ({
return queryParts.join('&');
}
- // Direct mode: include all filters
- if (showAdvanced) {
- const { isbn, author, title, content, formats, lang } = advancedFilters;
+ // Direct mode: include the active direct search settings regardless of panel visibility.
+ const { isbn, author, title, content, formats, lang } = advancedFilters;
- if (isbn) queryParts.push(`isbn=${encodeURIComponent(isbn)}`);
- if (author) queryParts.push(`author=${encodeURIComponent(author)}`);
- if (title) queryParts.push(`title=${encodeURIComponent(title)}`);
+ if (isbn) queryParts.push(`isbn=${encodeURIComponent(isbn)}`);
+ if (author) queryParts.push(`author=${encodeURIComponent(author)}`);
+ if (title) queryParts.push(`title=${encodeURIComponent(title)}`);
- const selectedLanguages = getLanguageFilterValues(lang, bookLanguages, defaultLanguage);
- selectedLanguages?.forEach(code => queryParts.push(`lang=${encodeURIComponent(code)}`));
+ const selectedLanguages = getLanguageFilterValues(lang, bookLanguages, defaultLanguage);
+ selectedLanguages?.forEach(code => queryParts.push(`lang=${encodeURIComponent(code)}`));
- if (content) queryParts.push(`content=${encodeURIComponent(content)}`);
- formats.forEach(format => queryParts.push(`format=${encodeURIComponent(format)}`));
- }
+ if (content) queryParts.push(`content=${encodeURIComponent(content)}`);
+ formats.forEach(format => queryParts.push(`format=${encodeURIComponent(format)}`));
if (advancedFilters.sort) {
queryParts.push(`sort=${encodeURIComponent(advancedFilters.sort)}`);
@@ -55,4 +53,3 @@ export const buildSearchQuery = ({
return queryParts.join('&');
};
-
diff --git a/src/frontend/src/utils/colorMaps.ts b/src/frontend/src/utils/colorMaps.ts
index 77dc0fa6..c9aad25f 100644
--- a/src/frontend/src/utils/colorMaps.ts
+++ b/src/frontend/src/utils/colorMaps.ts
@@ -1,4 +1,4 @@
-// Color styles with transparent backgrounds and contrasting text (matches DownloadsSidebar style)
+// Color styles with transparent backgrounds and contrasting text
interface ColorStyle {
bg: string;
text: string;
diff --git a/src/frontend/src/utils/queryTargets.ts b/src/frontend/src/utils/queryTargets.ts
new file mode 100644
index 00000000..2929aa88
--- /dev/null
+++ b/src/frontend/src/utils/queryTargets.ts
@@ -0,0 +1,87 @@
+import { MetadataSearchField, QueryTargetOption, SearchMode, TextSearchField } from '../types';
+
+const makeDirectField = (
+ key: 'isbn' | 'author' | 'title',
+ label: string,
+ description: string,
+): TextSearchField => ({
+ key,
+ label,
+ type: 'TextSearchField',
+ placeholder: `${label}…`,
+ description,
+});
+
+const GENERAL_QUERY_TARGET: QueryTargetOption = {
+ key: 'general',
+ label: 'General',
+ description: 'Search across all supported fields.',
+ source: 'general',
+};
+
+const DIRECT_QUERY_TARGETS: QueryTargetOption[] = [
+ GENERAL_QUERY_TARGET,
+ {
+ key: 'isbn',
+ label: 'ISBN',
+ description: 'Search for an exact ISBN.',
+ source: 'direct-field',
+ field: makeDirectField('isbn', 'ISBN', 'Search by ISBN'),
+ },
+ {
+ key: 'author',
+ label: 'Author',
+ description: 'Search by author name.',
+ source: 'direct-field',
+ field: makeDirectField('author', 'Author', 'Search by author name'),
+ },
+ {
+ key: 'title',
+ label: 'Title',
+ description: 'Search by title.',
+ source: 'direct-field',
+ field: makeDirectField('title', 'Title', 'Search by title'),
+ },
+];
+
+const mapMetadataFieldToTarget = (field: MetadataSearchField): QueryTargetOption => ({
+ key: field.key,
+ label: field.label,
+ description: field.description,
+ source: 'provider-field',
+ field,
+});
+
+export const buildQueryTargets = ({
+ searchMode,
+ metadataSearchFields = [],
+ manualSearchAllowed = false,
+}: {
+ searchMode: SearchMode;
+ metadataSearchFields?: MetadataSearchField[];
+ manualSearchAllowed?: boolean;
+}): QueryTargetOption[] => {
+ if (searchMode === 'direct') {
+ return DIRECT_QUERY_TARGETS;
+ }
+
+ const targets: QueryTargetOption[] = [
+ GENERAL_QUERY_TARGET,
+ ...metadataSearchFields.map(mapMetadataFieldToTarget),
+ ];
+
+ if (manualSearchAllowed) {
+ targets.push({
+ key: 'manual',
+ label: 'Manual',
+ description: 'Search release sources directly.',
+ source: 'manual',
+ });
+ }
+
+ return targets;
+};
+
+export const getDefaultQueryTargetKey = (targets: QueryTargetOption[]): string => {
+ return targets[0]?.key || 'general';
+};
diff --git a/tests/metadata/test_hardcover_field_options.py b/tests/metadata/test_hardcover_field_options.py
new file mode 100644
index 00000000..b704bf17
--- /dev/null
+++ b/tests/metadata/test_hardcover_field_options.py
@@ -0,0 +1,137 @@
+from shelfmark.metadata_providers.hardcover import HardcoverProvider
+
+
+class TestHardcoverFieldOptions:
+ def test_search_fields_enable_typeahead_for_author_title_and_series(self):
+ provider = HardcoverProvider(api_key="test-token")
+ fields_by_key = {field.key: field for field in provider.search_fields}
+
+ assert fields_by_key["author"].suggestions_endpoint == (
+ "/api/metadata/field-options?provider=hardcover&field=author"
+ )
+ assert fields_by_key["title"].suggestions_endpoint == (
+ "/api/metadata/field-options?provider=hardcover&field=title"
+ )
+ assert fields_by_key["series"].suggestions_endpoint == (
+ "/api/metadata/field-options?provider=hardcover&field=series"
+ )
+
+ def test_get_search_field_options_returns_author_suggestions(self, monkeypatch):
+ provider = HardcoverProvider(api_key="test-token")
+ captured: dict[str, object] = {}
+
+ monkeypatch.setattr(
+ provider,
+ "_execute_query",
+ lambda query, variables: captured.update({"query": query, "variables": variables}) or {
+ "search": {
+ "results": {
+ "hits": [
+ {"document": {"name": "Brandon Sanderson"}},
+ {"document": {"name": "Brandon Sanderson"}},
+ {"document": {"name": "Brian Sanderson"}},
+ ],
+ "found": 3,
+ }
+ }
+ },
+ )
+
+ options = provider.get_search_field_options("author", query="sand")
+
+ assert options == [
+ {"value": "Brandon Sanderson", "label": "Brandon Sanderson"},
+ {"value": "Brian Sanderson", "label": "Brian Sanderson"},
+ ]
+ assert captured["variables"] == {
+ "query": "sand",
+ "queryType": "Author",
+ "limit": 7,
+ "page": 1,
+ "sort": "_text_match:desc,books_count:desc",
+ "fields": "name,name_personal,alternate_names",
+ "weights": "4,3,2",
+ }
+
+ def test_get_search_field_options_returns_filtered_title_suggestions(self, monkeypatch):
+ provider = HardcoverProvider(api_key="test-token")
+ captured: dict[str, object] = {}
+
+ monkeypatch.setattr(
+ "shelfmark.metadata_providers.hardcover.app_config.get",
+ lambda key, default=None: {
+ "HARDCOVER_EXCLUDE_COMPILATIONS": True,
+ "HARDCOVER_EXCLUDE_UNRELEASED": True,
+ }.get(key, default),
+ )
+
+ monkeypatch.setattr(
+ provider,
+ "_execute_query",
+ lambda query, variables: captured.update({"query": query, "variables": variables}) or {
+ "search": {
+ "results": {
+ "hits": [
+ {
+ "document": {
+ "title": "Mistborn: The Final Empire",
+ "compilation": False,
+ "release_year": 2006,
+ }
+ },
+ {
+ "document": {
+ "title": "Mistborn Trilogy",
+ "compilation": True,
+ "release_year": 2001,
+ }
+ },
+ {
+ "document": {
+ "title": "Ghostbloods 1",
+ "compilation": False,
+ "release_year": 2028,
+ }
+ },
+ {
+ "document": {
+ "title": "Mistborn: The Final Empire",
+ "compilation": False,
+ "release_year": 2006,
+ }
+ },
+ {
+ "document": {
+ "title": "Mistborn: Secret History",
+ "compilation": False,
+ "release_year": 2016,
+ }
+ },
+ ],
+ "found": 5,
+ }
+ }
+ },
+ )
+
+ options = provider.get_search_field_options("title", query="mistborn")
+
+ assert options == [
+ {"value": "Mistborn: The Final Empire", "label": "Mistborn: The Final Empire"},
+ {"value": "Mistborn: Secret History", "label": "Mistborn: Secret History"},
+ ]
+ assert captured["variables"] == {
+ "query": "mistborn",
+ "queryType": "Book",
+ "limit": 7,
+ "page": 1,
+ "sort": "_text_match:desc,users_count:desc",
+ "fields": "title,alternative_titles",
+ "weights": "5,2",
+ }
+
+ def test_get_search_field_options_skips_short_text_queries(self):
+ provider = HardcoverProvider(api_key="test-token")
+
+ assert provider.get_search_field_options("author", query="a") == []
+ assert provider.get_search_field_options("title", query="i") == []
diff --git a/tests/metadata/test_hardcover_series_search.py b/tests/metadata/test_hardcover_series_search.py
new file mode 100644
index 00000000..389a8b1b
--- /dev/null
+++ b/tests/metadata/test_hardcover_series_search.py
@@ -0,0 +1,756 @@
+from shelfmark.metadata_providers import MetadataSearchOptions, SearchResult
+from shelfmark.metadata_providers.hardcover import HardcoverProvider
+
+
+class TestHardcoverSeriesSearch:
+ def test_get_search_field_options_returns_series_suggestions(self, monkeypatch):
+ provider = HardcoverProvider(api_key="test-token")
+
+ monkeypatch.setattr(
+ provider,
+ "_execute_query",
+ lambda query, variables: {
+ "search": {
+ "results": {
+ "hits": [
+ {
+ "document": {
+ "id": 7,
+ "name": "Mistborn",
+ "author_name": "Brandon Sanderson",
+ "primary_books_count": 7,
+ }
+ }
+ ],
+ "found": 1,
+ }
+ }
+ },
+ )
+
+ options = provider.get_search_field_options("series", query="mist")
+
+ assert options == [
+ {
+ "value": "id:7",
+ "label": "Mistborn",
+ "description": "by Brandon Sanderson • 7 books",
+ }
+ ]
+
+ def test_series_suggestions_prefer_direct_author_series_for_author_queries(self, monkeypatch):
+ provider = HardcoverProvider(api_key="test-token")
+
+ def fake_execute(query: str, variables):
+ if variables.get("queryType") == "Author":
+ return {
+ "search": {
+ "results": {
+ "hits": [
+ {
+ "document": {
+ "id": 204214,
+ "name": "Brandon Sanderson",
+ }
+ }
+ ],
+ "found": 1,
+ }
+ }
+ }
+ if variables.get("queryType") == "Series":
+ return {
+ "search": {
+ "results": {
+ "hits": [
+ {
+ "document": {
+ "id": 193594,
+ "name": " Brandon Sanderson",
+ "author_name": "Brandon Sanderson",
+ }
+ },
+ {
+ "document": {
+ "id": 1052,
+ "name": "White Sand",
+ "author_name": "Brandon Sanderson",
+ "primary_books_count": 3,
+ }
+ },
+ ],
+ "found": 2,
+ }
+ }
+ }
+ if variables.get("authorIds") == [204214]:
+ return {
+ "series": [
+ {
+ "id": 997,
+ "name": "The Stormlight Archive",
+ "primary_books_count": 10,
+ "books_count": 25,
+ "author": {"name": "Brandon Sanderson"},
+ },
+ {
+ "id": 5452,
+ "name": "The Mistborn Saga",
+ "primary_books_count": 10,
+ "books_count": 16,
+ "author": {"name": "Brandon Sanderson"},
+ },
+ ]
+ }
+ raise AssertionError(f"Unexpected query variables: {variables}")
+
+ monkeypatch.setattr(provider, "_execute_query", fake_execute)
+
+ options = provider.get_search_field_options("series", query="Brandon Sanderson")
+
+ assert options[:3] == [
+ {
+ "value": "id:997",
+ "label": "The Stormlight Archive",
+ "description": "by Brandon Sanderson • 10 books",
+ },
+ {
+ "value": "id:5452",
+ "label": "The Mistborn Saga",
+ "description": "by Brandon Sanderson • 10 books",
+ },
+ {
+ "value": "id:193594",
+ "label": "Brandon Sanderson",
+ "description": "by Brandon Sanderson",
+ },
+ ]
+
+ def test_search_paginated_uses_selected_series_id(self, monkeypatch):
+ provider = HardcoverProvider(api_key="test-token")
+ expected = SearchResult(books=[], page=2, total_found=14, has_more=True)
+ captured: dict[str, int] = {}
+
+ monkeypatch.setattr(
+ "shelfmark.metadata_providers.hardcover.app_config.get",
+ lambda key, default=None: {
+ "HARDCOVER_EXCLUDE_COMPILATIONS": True,
+ "HARDCOVER_EXCLUDE_UNRELEASED": True,
+ }.get(key, default),
+ )
+
+ def fake_fetch(
+ series_id: int,
+ page: int,
+ limit: int,
+ exclude_compilations: bool,
+ exclude_unreleased: bool,
+ ) -> SearchResult:
+ captured["series_id"] = series_id
+ captured["page"] = page
+ captured["limit"] = limit
+ captured["exclude_compilations"] = int(exclude_compilations)
+ captured["exclude_unreleased"] = int(exclude_unreleased)
+ return expected
+
+ monkeypatch.setattr(provider, "_fetch_series_books_by_id", fake_fetch)
+
+ result = provider.search_paginated(
+ MetadataSearchOptions(
+ query="",
+ page=2,
+ limit=20,
+ fields={"series": "id:42"},
+ )
+ )
+
+ assert result == expected
+ assert captured == {
+ "series_id": 42,
+ "page": 2,
+ "limit": 20,
+ "exclude_compilations": 1,
+ "exclude_unreleased": 1,
+ }
+
+ def test_search_paginated_resolves_typed_series_name_before_fetch(self, monkeypatch):
+ provider = HardcoverProvider(api_key="test-token")
+ expected = SearchResult(books=[], page=1, total_found=3, has_more=False)
+ captured: dict[str, int] = {}
+
+ def fake_execute(query: str, variables):
+ return {
+ "search": {
+ "results": {
+ "hits": [
+ {"document": {"id": 3, "name": "Mistborn Trilogy"}},
+ {"document": {"id": 9, "name": "Mistborn"}},
+ ],
+ "found": 2,
+ }
+ }
+ }
+
+ monkeypatch.setattr(
+ "shelfmark.metadata_providers.hardcover.app_config.get",
+ lambda key, default=None: {
+ "HARDCOVER_EXCLUDE_COMPILATIONS": False,
+ "HARDCOVER_EXCLUDE_UNRELEASED": True,
+ }.get(key, default),
+ )
+
+ def fake_fetch(
+ series_id: int,
+ page: int,
+ limit: int,
+ exclude_compilations: bool,
+ exclude_unreleased: bool,
+ ) -> SearchResult:
+ captured["series_id"] = series_id
+ captured["exclude_compilations"] = int(exclude_compilations)
+ captured["exclude_unreleased"] = int(exclude_unreleased)
+ return expected
+
+ monkeypatch.setattr(provider, "_execute_query", fake_execute)
+ monkeypatch.setattr(provider, "_fetch_series_books_by_id", fake_fetch)
+
+ result = provider.search_paginated(
+ MetadataSearchOptions(
+ query="",
+ page=1,
+ limit=40,
+ fields={"series": "Mistborn"},
+ )
+ )
+
+ assert result == expected
+ assert captured["series_id"] == 9
+ assert captured["exclude_compilations"] == 0
+ assert captured["exclude_unreleased"] == 1
+
+ def test_fetch_series_books_by_id_preserves_series_metadata(self, monkeypatch):
+ provider = HardcoverProvider(api_key="test-token")
+ captured: dict[str, object] = {}
+
+ monkeypatch.setattr(
+ "shelfmark.metadata_providers.hardcover.app_config.get",
+ lambda key, default=None: {
+ "HARDCOVER_EXCLUDE_COMPILATIONS": True,
+ "HARDCOVER_EXCLUDE_UNRELEASED": False,
+ }.get(key, default),
+ )
+
+ monkeypatch.setattr(
+ provider,
+ "_execute_query",
+ lambda query, variables: captured.update({"query": query, "variables": variables}) or {
+ "series": [
+ {
+ "id": 42,
+ "name": "Mistborn",
+ "primary_books_count": 3,
+ "book_series": [
+ {
+ "position": 1,
+ "book": {
+ "id": 100,
+ "title": "The Final Empire",
+ "subtitle": None,
+ "slug": "the-final-empire",
+ "release_date": "2006-07-17",
+ "headline": None,
+ "description": "A heist.",
+ "rating": 4.5,
+ "ratings_count": 120,
+ "users_count": 250,
+ "cached_image": {"url": "https://example.com/final-empire.jpg"},
+ "cached_contributors": [{"name": "Brandon Sanderson"}],
+ "contributions": [],
+ "featured_book_series": {
+ "position": 1,
+ "series": {
+ "id": 42,
+ "name": "Mistborn",
+ "primary_books_count": 3,
+ },
+ },
+ },
+ },
+ {
+ "position": 2,
+ "book": {
+ "id": 101,
+ "title": "The Well of Ascension",
+ "subtitle": None,
+ "slug": "the-well-of-ascension",
+ "release_date": "2007-08-21",
+ "headline": None,
+ "description": "The sequel.",
+ "rating": 4.4,
+ "ratings_count": 110,
+ "users_count": 220,
+ "cached_image": {"url": "https://example.com/well-of-ascension.jpg"},
+ "cached_contributors": [{"name": "Brandon Sanderson"}],
+ "contributions": [],
+ "featured_book_series": {
+ "position": 2,
+ "series": {
+ "id": 42,
+ "name": "Mistborn",
+ "primary_books_count": 3,
+ },
+ },
+ },
+ },
+ ],
+ }
+ ]
+ },
+ )
+
+ result = provider._fetch_series_books_by_id(
+ 42,
+ page=1,
+ limit=2,
+ exclude_compilations=True,
+ exclude_unreleased=False,
+ )
+
+ assert "canonical_id: {_is_null: true}" in str(captured["query"])
+ assert 'state: {_in: ["normalized", "normalizing"]}' in str(captured["query"])
+ assert result.total_found == 2
+ assert result.has_more is False
+ assert captured["variables"] == {"seriesId": 42}
+ assert [book.title for book in result.books] == [
+ "The Final Empire",
+ "The Well of Ascension",
+ ]
+ assert result.books[0].series_id == "42"
+ assert result.books[0].series_name == "Mistborn"
+ assert result.books[0].series_position == 1
+ assert result.books[0].series_count == 2
+
+ def test_fetch_series_books_by_id_skips_split_part_entries_for_standard_series(self, monkeypatch):
+ provider = HardcoverProvider(api_key="test-token")
+
+ monkeypatch.setattr(
+ "shelfmark.metadata_providers.hardcover.app_config.get",
+ lambda key, default=None: {
+ "HARDCOVER_EXCLUDE_COMPILATIONS": False,
+ "HARDCOVER_EXCLUDE_UNRELEASED": False,
+ }.get(key, default),
+ )
+
+ monkeypatch.setattr(
+ provider,
+ "_execute_query",
+ lambda query, variables: {
+ "series": [
+ {
+ "id": 10001,
+ "name": "The Mistborn Saga: The Original Trilogy",
+ "primary_books_count": 6,
+ "book_series": [
+ {
+ "position": 0.5,
+ "book": {
+ "id": 427844,
+ "title": "The Eleventh Metal",
+ "subtitle": None,
+ "slug": "the-eleventh-metal",
+ "release_date": "2012-04-11",
+ "headline": None,
+ "description": None,
+ "rating": 4.1,
+ "ratings_count": 404,
+ "users_count": 991,
+ "editions_count": 5,
+ "compilation": False,
+ "cached_image": {},
+ "cached_contributors": [{"name": "Brandon Sanderson"}],
+ "contributions": [],
+ "featured_book_series": {
+ "position": 0.5,
+ "series": {
+ "id": 10001,
+ "name": "The Mistborn Saga: The Original Trilogy",
+ "primary_books_count": 6,
+ },
+ },
+ },
+ },
+ {
+ "position": 1,
+ "book": {
+ "id": 369692,
+ "title": "Mistborn: The Final Empire",
+ "subtitle": None,
+ "slug": "mistborn-the-final-empire",
+ "release_date": "2006-01-01",
+ "headline": None,
+ "description": None,
+ "rating": 4.5,
+ "ratings_count": 3942,
+ "users_count": 8192,
+ "editions_count": 92,
+ "compilation": False,
+ "cached_image": {},
+ "cached_contributors": [{"name": "Brandon Sanderson"}],
+ "contributions": [],
+ "featured_book_series": {
+ "position": 1,
+ "series": {
+ "id": 10001,
+ "name": "The Mistborn Saga: The Original Trilogy",
+ "primary_books_count": 6,
+ },
+ },
+ },
+ },
+ {
+ "position": 2,
+ "book": {
+ "id": 427383,
+ "title": "The Well of Ascension",
+ "subtitle": None,
+ "slug": "the-well-of-ascension",
+ "release_date": "2007-08-21",
+ "headline": None,
+ "description": None,
+ "rating": 4.4,
+ "ratings_count": 3007,
+ "users_count": 5136,
+ "editions_count": 85,
+ "compilation": False,
+ "cached_image": {},
+ "cached_contributors": [{"name": "Brandon Sanderson"}],
+ "contributions": [],
+ "featured_book_series": {
+ "position": 2,
+ "series": {
+ "id": 10001,
+ "name": "The Mistborn Saga: The Original Trilogy",
+ "primary_books_count": 6,
+ },
+ },
+ },
+ },
+ {
+ "position": 3,
+ "book": {
+ "id": 103241,
+ "title": "The Hero of Ages",
+ "subtitle": None,
+ "slug": "the-hero-of-ages",
+ "release_date": "2007-12-30",
+ "headline": None,
+ "description": None,
+ "rating": 4.4,
+ "ratings_count": 2786,
+ "users_count": 4752,
+ "editions_count": 78,
+ "compilation": False,
+ "cached_image": {},
+ "cached_contributors": [{"name": "Brandon Sanderson"}],
+ "contributions": [],
+ "featured_book_series": {
+ "position": 3,
+ "series": {
+ "id": 10001,
+ "name": "The Mistborn Saga: The Original Trilogy",
+ "primary_books_count": 6,
+ },
+ },
+ },
+ },
+ {
+ "position": 3.5,
+ "book": {
+ "id": 427881,
+ "title": "Mistborn: Secret History",
+ "subtitle": None,
+ "slug": "mistborn-secret-history",
+ "release_date": "2016-01-01",
+ "headline": None,
+ "description": None,
+ "rating": 4.3,
+ "ratings_count": 717,
+ "users_count": 1546,
+ "editions_count": 13,
+ "compilation": False,
+ "cached_image": {},
+ "cached_contributors": [{"name": "Brandon Sanderson"}],
+ "contributions": [],
+ "featured_book_series": {
+ "position": 3.5,
+ "series": {
+ "id": 10001,
+ "name": "The Mistborn Saga: The Original Trilogy",
+ "primary_books_count": 6,
+ },
+ },
+ },
+ },
+ {
+ "position": 6,
+ "book": {
+ "id": 763900,
+ "title": "The Bands of Mourning, Part 2",
+ "subtitle": None,
+ "slug": "the-bands-of-mourning-part-2",
+ "release_date": "2011-11-08",
+ "headline": None,
+ "description": None,
+ "rating": 2.0,
+ "ratings_count": 1,
+ "users_count": 13,
+ "editions_count": 1,
+ "compilation": False,
+ "cached_image": {},
+ "cached_contributors": [{"name": "Brandon Sanderson"}],
+ "contributions": [],
+ "featured_book_series": {
+ "position": 6,
+ "series": {
+ "id": 10001,
+ "name": "The Mistborn Saga: The Original Trilogy",
+ "primary_books_count": 6,
+ },
+ },
+ },
+ },
+ ],
+ }
+ ]
+ },
+ )
+
+ result = provider._fetch_series_books_by_id(
+ 10001,
+ page=1,
+ limit=20,
+ exclude_compilations=False,
+ exclude_unreleased=False,
+ )
+
+ assert [book.title for book in result.books] == [
+ "The Eleventh Metal",
+ "Mistborn: The Final Empire",
+ "The Well of Ascension",
+ "The Hero of Ages",
+ "Mistborn: Secret History",
+ ]
+ assert result.total_found == 5
+ assert result.has_more is False
+
+ def test_fetch_series_books_by_id_prefers_best_book_per_position(self, monkeypatch):
+ provider = HardcoverProvider(api_key="test-token")
+
+ monkeypatch.setattr(
+ "shelfmark.metadata_providers.hardcover.app_config.get",
+ lambda key, default=None: {
+ "HARDCOVER_EXCLUDE_COMPILATIONS": False,
+ "HARDCOVER_EXCLUDE_UNRELEASED": True,
+ }.get(key, default),
+ )
+
+ monkeypatch.setattr(
+ provider,
+ "_execute_query",
+ lambda query, variables: {
+ "series": [
+ {
+ "id": 5452,
+ "name": "The Mistborn Saga",
+ "primary_books_count": 10,
+ "book_series": [
+ {
+ "position": 0.5,
+ "book": {
+ "id": 1389888,
+ "title": "Sunrise on the Reaping",
+ "subtitle": None,
+ "slug": "sunrise-on-the-reaping",
+ "release_date": "2025-01-01",
+ "headline": None,
+ "description": "The next Panem story.",
+ "rating": 4.5,
+ "ratings_count": 900,
+ "users_count": 2314,
+ "editions_count": 32,
+ "compilation": False,
+ "cached_image": {"url": "https://example.com/sunrise.jpg"},
+ "cached_contributors": [{"name": "Suzanne Collins"}],
+ "contributions": [],
+ "featured_book_series": {
+ "position": 0.5,
+ "series": {
+ "id": 5452,
+ "name": "The Mistborn Saga",
+ "primary_books_count": 10,
+ },
+ },
+ },
+ },
+ {
+ "position": 4,
+ "book": {
+ "id": 330249,
+ "title": "The Alloy of Law",
+ "subtitle": None,
+ "slug": "the-alloy-of-law",
+ "release_date": "2011-01-01",
+ "headline": None,
+ "description": "Wax and Wayne arrive.",
+ "rating": 4.2,
+ "ratings_count": 1630,
+ "users_count": 3142,
+ "editions_count": 53,
+ "compilation": False,
+ "cached_image": {"url": "https://example.com/alloy.jpg"},
+ "cached_contributors": [{"name": "Brandon Sanderson"}],
+ "contributions": [],
+ "featured_book_series": {
+ "position": 1,
+ "series": {
+ "id": 10825,
+ "name": "Wax & Wayne",
+ "primary_books_count": 4,
+ },
+ },
+ },
+ },
+ {
+ "position": 4,
+ "book": {
+ "id": 2190514,
+ "title": "Aleación de ley (Wax & Wayne 1): Una novela de Mistborn",
+ "subtitle": None,
+ "slug": "aleacion-de-ley",
+ "release_date": "2011-11-08",
+ "headline": None,
+ "description": "Localized duplicate.",
+ "rating": 4.0,
+ "ratings_count": 1,
+ "users_count": 2,
+ "editions_count": 1,
+ "compilation": False,
+ "cached_image": {"url": "https://example.com/aleacion.jpg"},
+ "cached_contributors": [{"name": "Brandon Sanderson"}],
+ "contributions": [],
+ "featured_book_series": {
+ "position": 4,
+ "series": {
+ "id": 5452,
+ "name": "The Mistborn Saga",
+ "primary_books_count": 10,
+ },
+ },
+ },
+ },
+ {
+ "position": 4.5,
+ "book": {
+ "id": 427892,
+ "title": "Allomancer Jak and the Pits of Eltania",
+ "subtitle": None,
+ "slug": "allomancer-jak",
+ "release_date": "2014-08-03",
+ "headline": None,
+ "description": "A novella.",
+ "rating": 4.1,
+ "ratings_count": 182,
+ "users_count": 572,
+ "editions_count": 3,
+ "compilation": False,
+ "cached_image": {"url": "https://example.com/jak.jpg"},
+ "cached_contributors": [{"name": "Brandon Sanderson"}],
+ "contributions": [],
+ "featured_book_series": {
+ "position": 4.5,
+ "series": {
+ "id": 5452,
+ "name": "The Mistborn Saga",
+ "primary_books_count": 10,
+ },
+ },
+ },
+ },
+ {
+ "position": 8,
+ "book": {
+ "id": 1878844,
+ "title": "Ghostbloods 1",
+ "subtitle": None,
+ "slug": "ghostbloods-1",
+ "release_date": "2028-12-01",
+ "headline": None,
+ "description": "Future title.",
+ "rating": None,
+ "ratings_count": 0,
+ "users_count": 68,
+ "editions_count": 1,
+ "compilation": False,
+ "cached_image": {"url": "https://example.com/ghostbloods.jpg"},
+ "cached_contributors": [{"name": "Brandon Sanderson"}],
+ "contributions": [],
+ "featured_book_series": {
+ "position": 8,
+ "series": {
+ "id": 5452,
+ "name": "The Mistborn Saga",
+ "primary_books_count": 10,
+ },
+ },
+ },
+ },
+ {
+ "position": 9,
+ "book": {
+ "id": 1898126,
+ "title": "Ghostbloods 2",
+ "subtitle": None,
+ "slug": "ghostbloods-2",
+ "release_date": None,
+ "headline": None,
+ "description": "No published date yet.",
+ "rating": None,
+ "ratings_count": 0,
+ "users_count": 40,
+ "editions_count": 1,
+ "compilation": False,
+ "cached_image": {"url": "https://example.com/ghostbloods-2.jpg"},
+ "cached_contributors": [{"name": "Brandon Sanderson"}],
+ "contributions": [],
+ "featured_book_series": {
+ "position": 9,
+ "series": {
+ "id": 5452,
+ "name": "The Mistborn Saga",
+ "primary_books_count": 10,
+ },
+ },
+ },
+ },
+ ],
+ }
+ ]
+ },
+ )
+
+ result = provider._fetch_series_books_by_id(
+ 5452,
+ page=1,
+ limit=10,
+ exclude_compilations=False,
+ exclude_unreleased=True,
+ )
+
+ assert result.total_found == 3
+ assert result.has_more is False
+ assert [book.title for book in result.books] == [
+ "Sunrise on the Reaping",
+ "The Alloy of Law",
+ "Allomancer Jak and the Pits of Eltania",
+ ]
+ assert [book.series_position for book in result.books] == [0.5, 4, 4.5]
diff --git a/tests/metadata/test_metadata_provider_capabilities.py b/tests/metadata/test_metadata_provider_capabilities.py
new file mode 100644
index 00000000..66781440
--- /dev/null
+++ b/tests/metadata/test_metadata_provider_capabilities.py
@@ -0,0 +1,15 @@
+from shelfmark.metadata_providers import get_provider_capabilities
+
+
+class TestMetadataProviderCapabilities:
+ def test_hardcover_exposes_view_series_capability(self):
+ assert get_provider_capabilities("hardcover") == [
+ {
+ "key": "view_series",
+ "field_key": "series",
+ "sort": "series_order",
+ }
+ ]
+
+ def test_providers_without_capabilities_return_empty_list(self):
+ assert get_provider_capabilities("openlibrary") == []