From d8eb9a90fa6392960bd39c2a1022e65983610036 Mon Sep 17 00:00:00 2001 From: Logan Abell Date: Thu, 15 Oct 2026 01:31:43 -0400 Subject: [PATCH 1/2] Fix catalog controls and Hardcover compatibility (NOR-88, NOR-91, NOR-100) --- apps/web/playwright.ui.config.ts | 9 +- apps/web/src/api/schema.d.ts | 1 + apps/web/src/components/CatalogEditions.tsx | 66 ++++-- .../src/components/EditionFormatSelect.tsx | 25 +++ apps/web/src/components/SelectMenu.tsx | 125 +++++++----- apps/web/src/pages/DiscoverBook.tsx | 33 ++- apps/web/tests/ui/catalog-editions.spec.ts | 174 ++++++++++++++++ apps/web/tests/ui/select-menu.spec.ts | 156 +++++++++++++++ docs/DEVELOPMENT.md | 2 + docs/openapi.json | 22 ++ services/app/adapters/catalog_providers.py | 16 +- services/app/adapters/hardcover_follows.py | 16 +- services/app/api/metadata.py | 3 + tests/contracts/test_catalog_providers.py | 21 +- tests/integration/test_catalog_controls.py | 189 ++++++++++++++++++ tests/unit/test_hardcover_follows.py | 26 ++- 16 files changed, 788 insertions(+), 96 deletions(-) create mode 100644 apps/web/src/components/EditionFormatSelect.tsx create mode 100644 apps/web/tests/ui/catalog-editions.spec.ts create mode 100644 apps/web/tests/ui/select-menu.spec.ts create mode 100644 tests/integration/test_catalog_controls.py diff --git a/apps/web/playwright.ui.config.ts b/apps/web/playwright.ui.config.ts index f16ec9d0..dc339b4c 100644 --- a/apps/web/playwright.ui.config.ts +++ b/apps/web/playwright.ui.config.ts @@ -4,6 +4,13 @@ import shared from "./playwright.shared"; const port = Number(process.env.BOOK_UI_PORT || 4173); if (!Number.isInteger(port) || port < 1024 || port > 65535) throw new Error("BOOK_UI_PORT must be a port between 1024 and 65535"); +const browserName = process.env.BOOK_UI_BROWSER || "chromium"; +if ( + browserName !== "chromium" && + browserName !== "firefox" && + browserName !== "webkit" +) + throw new Error("BOOK_UI_BROWSER must be chromium, firefox, or webkit"); const baseURL = `http://127.0.0.1:${port}`; // Fully mocked browser journeys only: no PostgreSQL, Python API, migrations, or worker. @@ -12,7 +19,7 @@ export default defineConfig({ testDir: "./tests/ui", reporter: [["list"], ["junit", { outputFile: "test-results/ui.xml" }]], outputDir: "test-results/ui", - use: { ...shared.use, baseURL }, + use: { ...shared.use, baseURL, browserName }, webServer: { command: `node node_modules/vite/bin/vite.js preview --config vite.ui.config.ts --host 127.0.0.1 --port ${port} --strictPort`, url: baseURL, diff --git a/apps/web/src/api/schema.d.ts b/apps/web/src/api/schema.d.ts index 7e3938a2..4ac46320 100644 --- a/apps/web/src/api/schema.d.ts +++ b/apps/web/src/api/schema.d.ts @@ -22043,6 +22043,7 @@ export interface operations { offset?: number; limit?: number; scope?: "identity" | "display"; + medium?: ("ebook" | "audio" | "print" | "unknown") | null; }; header?: never; path: { diff --git a/apps/web/src/components/CatalogEditions.tsx b/apps/web/src/components/CatalogEditions.tsx index f8ea177f..6cc7a626 100644 --- a/apps/web/src/components/CatalogEditions.tsx +++ b/apps/web/src/components/CatalogEditions.tsx @@ -1,3 +1,4 @@ +import EditionFormatSelect, { type EditionFormat } from "./EditionFormatSelect"; import { useState } from "react"; import BookPagination from "./BookPagination"; import { Link } from "react-router-dom"; @@ -20,6 +21,10 @@ export default function CatalogEditions({ }) { const cache = useQueryClient(); const [page, setPage] = useState(1); + const [format, setFormat] = useState("all"); + const providerEditions = (readerBook?.editions || []).filter( + (edition) => format === "all" || edition.medium === format, + ); const [providerPage, setProviderPage] = useState(1); const group = useQuery({ queryKey: ["work-grouping", work.id], @@ -51,13 +56,18 @@ export default function CatalogEditions({ }, }); const query = useQuery({ - queryKey: ["reader-work-metadata", work.id, "editions", page], + queryKey: ["reader-work-metadata", work.id, "editions", page, format], queryFn: async ({ signal }) => result( await api.GET("/api/metadata/works/{work_id}", { params: { path: { work_id: work.id }, - query: { offset: (page - 1) * 20, limit: 20, scope: "display" }, + query: { + offset: (page - 1) * 20, + limit: 20, + scope: "display", + medium: format === "all" ? undefined : format, + }, }, signal, }), @@ -71,7 +81,21 @@ export default function CatalogEditions({ {query.data.versions_total} editions )} + { + setFormat(value); + setPage(1); + setProviderPage(1); + }} + /> + {query.data?.sources.some((source) => source.editions_more) && ( +

+ Some catalog editions have not been loaded. More formats may be + available; use Book metadata to load more editions. +

+ )} {query.isPending && } {query.error && ( @@ -186,8 +210,10 @@ export default function CatalogEditions({ ) : (

- No editions are linked yet. Use Book metadata to match or refresh a - catalog source. + {format === "all" + ? "No editions are linked yet." + : "No linked editions match this format."}{" "} + Use Book metadata to match or refresh a catalog source.

))} {query.data && ( @@ -218,12 +244,12 @@ export default function CatalogEditions({ )} - {!!readerBook?.editions?.length && ( + {readerBook && (

On Hardcover

- {readerBook.editions.length} + {providerEditions.length} {readerBook.editions_more ? "+" : ""} editions
@@ -238,7 +264,7 @@ export default function CatalogEditions({ - {readerBook.editions + {providerEditions .slice((providerPage - 1) * 20, providerPage * 20) .map((edition) => ( @@ -273,18 +299,28 @@ export default function CatalogEditions({ + {!providerEditions.length && ( +

+ No editions matching this format are in the loaded Hardcover + results. +

+ )} {readerBook.editions_more && ( - - Explore all editions on Hardcover → - +

+ Only the first {readerBook.editions?.length || 0} editions are + loaded. More formats may be available.{" "} + + Explore all editions on Hardcover → + +

)}
)} diff --git a/apps/web/src/components/EditionFormatSelect.tsx b/apps/web/src/components/EditionFormatSelect.tsx new file mode 100644 index 00000000..0a8e2fb4 --- /dev/null +++ b/apps/web/src/components/EditionFormatSelect.tsx @@ -0,0 +1,25 @@ +export type EditionFormat = "all" | "ebook" | "audio" | "print" | "unknown"; + +export default function EditionFormatSelect({ + value, + onChange, +}: { + value: EditionFormat; + onChange: (value: EditionFormat) => void; +}) { + return ( + + ); +} diff --git a/apps/web/src/components/SelectMenu.tsx b/apps/web/src/components/SelectMenu.tsx index 14786130..afbe5f81 100644 --- a/apps/web/src/components/SelectMenu.tsx +++ b/apps/web/src/components/SelectMenu.tsx @@ -1,5 +1,5 @@ import { Fragment, useEffect, useLayoutEffect, useRef, useState } from "react"; -import { createPortal } from "react-dom"; +import { createPortal, flushSync } from "react-dom"; import { Check } from "lucide-react"; type MenuOption = { @@ -20,7 +20,7 @@ type MenuState = { const MENU_ID = "app-select-menu"; function customMenusSupported() { - return "showPopover" in HTMLElement.prototype; + return typeof HTMLElement.prototype.showPopover === "function"; } function eligible(select: HTMLSelectElement | null) { @@ -40,7 +40,9 @@ function readOptions(select: HTMLSelectElement): MenuOption[] { return { value: option.value, label: option.label || option.value, - disabled: option.disabled, + disabled: + option.disabled || + (parent instanceof HTMLOptGroupElement && parent.disabled), group, }; }); @@ -103,6 +105,7 @@ function optionId(index: number) { export default function SelectMenu() { const popoverRef = useRef(null); + const nativeFallback = useRef(false); const menuRef = useRef(null); const [menu, setMenu] = useState(null); @@ -131,7 +134,7 @@ export default function SelectMenu() { ); const fallback = options.findIndex((option) => !option.disabled); const index = active >= 0 ? active : fallback; - if (index < 0) return; + if (index < 0 || nativeFallback.current) return false; const previous = menuRef.current; if (previous && previous.select !== select) { previous.select.removeAttribute("data-open"); @@ -143,13 +146,21 @@ export default function SelectMenu() { select.setAttribute("aria-expanded", "true"); select.setAttribute("aria-controls", MENU_ID); select.setAttribute("aria-activedescendant", optionId(index)); - sync({ - select, - options, - active: index, - label: selectName(select), - moveFocus, - }); + // Show the popover within the initiating event, before canceling the native + // picker. A failed custom open must leave that native default available. + flushSync(() => + sync({ + select, + options, + active: index, + label: selectName(select), + moveFocus, + }), + ); + return ( + menuRef.current?.select === select && + !!popoverRef.current?.matches(":popover-open") + ); }; const updateActive = (active: number, moveFocus = true) => { @@ -174,7 +185,7 @@ export default function SelectMenu() { useLayoutEffect(() => { const pop = popoverRef.current; - if (!pop) return; + if (!pop || !customMenusSupported()) return; if (!menu) { if (pop.matches(":popover-open")) pop.hidePopover(); return; @@ -187,6 +198,11 @@ export default function SelectMenu() { try { pop.showPopover(); } catch { + // Fall through to the native picker if showing throws or is canceled. + } + if (!pop.matches(":popover-open")) { + nativeFallback.current = true; + close(false); return; } } @@ -215,12 +231,16 @@ export default function SelectMenu() { useEffect(() => { if (!customMenusSupported()) return; - let suppressUntil = 0; + let pointerHandled = false; let buffer = ""; let bufferTimer = 0; const targetSelect = (event: Event) => { - if (!(event.target instanceof HTMLSelectElement)) return null; + if ( + nativeFallback.current || + !(event.target instanceof HTMLSelectElement) + ) + return null; if (popoverRef.current?.contains(event.target)) return null; return eligible(event.target); }; @@ -286,12 +306,13 @@ export default function SelectMenu() { const onMouseDown = (event: MouseEvent) => { const select = targetSelect(event); - if (!select || event.button !== 0) return; - event.preventDefault(); + if (select && event.button === 0 && pointerHandled) + event.preventDefault(); }; const labeledSelect = (event: Event) => { - if (!(event.target instanceof Element)) return null; + if (nativeFallback.current || !(event.target instanceof Element)) + return null; if (event.target instanceof HTMLSelectElement) return null; if (popoverRef.current?.contains(event.target)) return null; const label = event.target.closest("label"); @@ -302,43 +323,43 @@ export default function SelectMenu() { }; const onPointerDown = (event: PointerEvent) => { + pointerHandled = false; const select = targetSelect(event) || labeledSelect(event); - if (!select || event.button !== 0) return; - event.preventDefault(); - if (menuRef.current?.select === select) { - suppressUntil = performance.now() + 400; - close(false); + if (event.button !== 0) return; + if (!select) { + if ( + event.target instanceof Node && + !popoverRef.current?.contains(event.target) + ) + close(false); return; } - if (menuRef.current) close(false); + if (menuRef.current?.select === select) { + close(true); + pointerHandled = true; + } else { + if (menuRef.current) close(false); + select.focus({ preventScroll: true }); + pointerHandled = open(select, false); + } + if (pointerHandled) event.preventDefault(); }; - const onPointerUp = (event: PointerEvent) => { + const onClick = (event: MouseEvent) => { const select = targetSelect(event) || labeledSelect(event); if (!select || event.button !== 0) return; - if (performance.now() < suppressUntil) return; - if (menuRef.current?.select === select) return; - select.focus({ preventScroll: true }); - open(select, false); - }; - - const onClick = (event: MouseEvent) => { - if (performance.now() < suppressUntil) return; - if (!(event.target instanceof Element)) return; - if (event.target instanceof HTMLSelectElement) return; - if (popoverRef.current?.contains(event.target)) return; - const label = event.target.closest("label"); - if (!(label instanceof HTMLLabelElement)) return; - const select = eligible( - label.control instanceof HTMLSelectElement ? label.control : null, - ); - if (!select || menuRef.current?.select === select) return; - event.preventDefault(); + if (pointerHandled) { + pointerHandled = false; + event.preventDefault(); + return; + } + // Keyboard/assistive-technology clicks need no preceding pointer event. select.focus({ preventScroll: true }); - open(select, false); + if (open(select, false)) event.preventDefault(); }; const onKeyDown = (event: KeyboardEvent) => { + if (nativeFallback.current) return; const current = menuRef.current; const onSelect = event.target instanceof HTMLSelectElement @@ -358,9 +379,9 @@ export default function SelectMenu() { event.key === "ArrowUp" || event.key === " ")); if (!openKey) return; + if (!open(onSelect, true)) return; event.preventDefault(); event.stopPropagation(); - open(onSelect, true); if (event.key === "ArrowDown") step(1); else if (event.key === "ArrowUp") step(-1); return; @@ -431,11 +452,11 @@ export default function SelectMenu() { capture: true, passive: false, }); - document.addEventListener("pointerup", onPointerUp, true); document.addEventListener("click", onClick, true); const onKeyUp = (event: KeyboardEvent) => { if (!(event.target instanceof HTMLSelectElement)) return; - if (!eligible(event.target)) return; + if (!eligible(event.target) || nativeFallback.current || !menuRef.current) + return; if ( event.key === " " || event.key === "ArrowDown" || @@ -449,7 +470,6 @@ export default function SelectMenu() { return () => { document.removeEventListener("mousedown", onMouseDown, true); document.removeEventListener("pointerdown", onPointerDown, true); - document.removeEventListener("pointerup", onPointerUp, true); document.removeEventListener("click", onClick, true); document.removeEventListener("keydown", onKeyDown, true); document.removeEventListener("keyup", onKeyUp, true); @@ -464,12 +484,19 @@ export default function SelectMenu() {
{ - if (event.newState !== "closed" || !menuRef.current) return; + if ( + event.newState !== "closed" || + !menuRef.current || + popoverRef.current?.matches(":popover-open") + ) + return; menuRef.current.select.removeAttribute("data-open"); menuRef.current.select.removeAttribute("aria-expanded"); menuRef.current.select.removeAttribute("aria-controls"); diff --git a/apps/web/src/pages/DiscoverBook.tsx b/apps/web/src/pages/DiscoverBook.tsx index a186e9ea..bafc6fbc 100644 --- a/apps/web/src/pages/DiscoverBook.tsx +++ b/apps/web/src/pages/DiscoverBook.tsx @@ -1,3 +1,6 @@ +import EditionFormatSelect, { + type EditionFormat, +} from "../components/EditionFormatSelect"; import { ReturnLink, safeReturn } from "../components/NavigationContinuity"; import { AuthorFollows } from "../components/FollowCatalog"; import BookPagination from "../components/BookPagination"; @@ -110,7 +113,7 @@ function BookPage({ const [localWork, setLocalWork] = useState(null); const [action, setAction] = useState(null); const [listId, setListId] = useState(""); - const [format, setFormat] = useState("all"); + const [format, setFormat] = useState("all"); const [editionPage, setEditionPage] = useState(1); const preview = useQuery({ queryKey: ["provider-book", provider, externalId], @@ -534,22 +537,13 @@ function BookPage({ Explore print, ebook and audiobook editions.

- + { + setFormat(value); + setEditionPage(1); + }} + /> {shown.length ? (
@@ -622,7 +616,7 @@ function BookPage({ : format === "audio" ? "audiobook " : `${format} `} - editions are available in this catalog page. + editions are in the loaded catalog results.

)} {book.editions_more && (

- Showing the first {editions.length} editions.{" "} + Only the first {editions.length} editions are loaded. More + formats may be available.{" "} Explore all editions on {sourceName} → diff --git a/apps/web/tests/ui/catalog-editions.spec.ts b/apps/web/tests/ui/catalog-editions.spec.ts new file mode 100644 index 00000000..c06d5068 --- /dev/null +++ b/apps/web/tests/ui/catalog-editions.spec.ts @@ -0,0 +1,174 @@ +import { expect, test } from "../fixtures"; + +for (const view of ["discovery", "saved", "unlinked"] as const) { + test(`${view} edition filters retain the reported audiobook and explain partial results`, async ({ + page, + }) => { + page.on("pageerror", (error) => { + throw error; + }); + const id = "00000000-0000-0000-0000-000000000042"; + const title = "Tress of the Emerald Sea"; + const audio = { + external_id: "31639613", + id: "audio", + title: "Tress Graphic Audio", + medium: "audio", + identifiers: { isbn_13: "9798890553157" }, + narrators: [], + language: null, + publisher: "Graphic Audio LLC", + owned: false, + }; + const editions = [ + ...Array.from({ length: 21 }, (_, i) => ({ + id: `print-${i}`, + external_id: String(i + 1), + title: `Print edition ${i + 1}`, + medium: "print", + narrators: [], + identifiers: {}, + owned: false, + })), + audio, + ]; + const book = { + provider: "hardcover", + external_id: "602482", + title, + authors: ["Brandon Sanderson"], + editions, + editions_more: true, + series: [], + }; + const work = { + id, + title, + authors: book.authors, + provisional: false, + availability: { + owned: false, + ebook: false, + audio: false, + stale: false, + in_collection: false, + }, + }; + const requests: URL[] = []; + await page.route("**/api/**", (route) => { + const url = new URL(route.request().url()); + let data: unknown = []; + if (url.pathname === "/api/auth/me") + data = { + user: { + id: "reader", + role: "member", + display_name: "Reader", + onboarding_status: "complete", + }, + csrf_token: "test", + }; + else if (url.pathname === "/api/setup/onboarding") + data = { status: "completed" }; + else if (url.pathname.startsWith("/api/acquisition/preferences/")) + data = { effective: {}, inherited: {}, overrides: {}, revision: "one" }; + else if (url.pathname === `/api/catalog/works/${id}`) data = work; + else if (url.pathname === "/api/metadata/books/hardcover/602482") + data = { + book, + stale: true, + warning: "Showing saved catalog data while Hardcover refreshes.", + }; + else if (url.pathname.endsWith("/reader-match")) + data = { status: "matched", book }; + else if (url.pathname.endsWith("/reader-details")) + data = { + external_id: "602482", + contributors: [], + ratings: [], + reviews: [], + series: [], + }; + else if (url.pathname === `/api/metadata/works/${id}`) { + requests.push(url); + const medium = url.searchParams.get("medium"); + const matching = editions.filter((e) => !medium || e.medium === medium); + const offset = Number(url.searchParams.get("offset") || 0); + data = { + sources: + view === "unlinked" + ? [] + : [ + { + id: "source", + provider: "hardcover", + external_id: "602482", + title, + book, + editions_more: true, + series: [], + }, + ], + fields: {}, + versions: + view === "unlinked" ? [] : matching.slice(offset, offset + 20), + versions_total: view === "unlinked" ? 0 : matching.length, + cover_choices: [], + enrichment: null, + }; + } + return route.fulfill({ json: data }); + }); + await page.goto( + view === "discovery" + ? "/discover/books/hardcover/602482?tab=editions" + : `/books/${id}?tab=editions`, + ); + const selector = page.getByRole("combobox", { name: "Edition format" }); + await expect(selector).toBeVisible(); + // Start on a later page: changing the format must reset local/server paging. + await page + .getByRole("button", { + name: + view === "unlinked" + ? "Next hardcover editions page" + : "Next editions page", + exact: true, + }) + .click(); + await selector.click(); + await page + .getByRole("listbox", { name: "Edition format" }) + .getByRole("option", { name: "Audiobook", exact: true }) + .click(); + await expect( + page.getByText("Tress Graphic Audio", { exact: true }), + ).toBeVisible(); + await expect( + page.getByText("Print edition 1", { exact: true }), + ).toHaveCount(0); + if (view !== "discovery") + expect( + requests.some( + (url) => + url.searchParams.get("medium") === "audio" && + url.searchParams.get("offset") === "0", + ), + ).toBe(true); + await selector.click(); + await page + .getByRole("listbox", { name: "Edition format" }) + .getByRole("option", { name: "Ebook", exact: true }) + .click(); + await expect( + page.getByText("Tress Graphic Audio", { exact: true }), + ).toHaveCount(0); + await expect( + page.getByText(/More formats may be available/).first(), + ).toBeVisible(); + if (view === "discovery") + await expect( + page.getByText("Showing saved catalog data while Hardcover refreshes."), + ).toBeVisible(); + }); +} diff --git a/apps/web/tests/ui/select-menu.spec.ts b/apps/web/tests/ui/select-menu.spec.ts new file mode 100644 index 00000000..a4016e65 --- /dev/null +++ b/apps/web/tests/ui/select-menu.spec.ts @@ -0,0 +1,156 @@ +import { expect, test, type Page } from "../fixtures"; + +async function preferences(page: Page) { + const reads: string[] = []; + await page.route("**/api/**", (route) => { + const path = new URL(route.request().url()).pathname; + let data: unknown = []; + if (path === "/api/auth/me") + data = { + user: { + id: "admin", + role: "admin", + display_name: "Administrator", + onboarding_status: "complete", + }, + csrf_token: "test", + }; + else if (path === "/api/setup/onboarding") data = { status: "completed" }; + else if (path.startsWith("/api/acquisition/preferences/")) { + reads.push(path); + data = { effective: {}, inherited: {}, overrides: {}, revision: "one" }; + } + return route.fulfill({ json: data }); + }); + await page.goto("/settings#preferences"); + const select = page.getByRole("combobox", { name: "Apply to" }); + await expect(select).toHaveValue("personal"); + return { select, reads }; +} + +test("pointer selection opens the menu and changes application scope exactly once", async ({ + page, +}) => { + const { select, reads } = await preferences(page); + await select.click(); + const menu = page.getByRole("listbox", { name: "Apply to" }); + await expect(menu).toBeVisible(); + await menu.getByRole("option", { name: "Everyone on this server" }).click(); + await expect(select).toHaveValue("installation"); + expect(reads).toEqual([ + "/api/acquisition/preferences/personal", + "/api/acquisition/preferences/installation", + ]); + await expect(menu).toBeHidden(); +}); + +for (const fallback of [ + "failed", + "canceled", + "unsupported", + "forced-colors", +] as const) { + test(`${fallback} popovers leave a working native select`, async ({ + page, + }) => { + if (fallback === "forced-colors") + await page.emulateMedia({ forcedColors: "active" }); + else + await page.addInitScript((mode) => { + if (mode === "unsupported") + Object.defineProperty(HTMLElement.prototype, "showPopover", { + value: undefined, + }); + else if (mode === "failed") + HTMLElement.prototype.showPopover = () => { + throw new DOMException("Unavailable", "NotSupportedError"); + }; + else + document.addEventListener( + "beforetoggle", + (event) => { + if ((event as ToggleEvent).newState === "open") + event.preventDefault(); + }, + true, + ); + }, fallback); + const { select, reads } = await preferences(page); + await select.click(); + await expect(select).not.toHaveAttribute("aria-expanded", "true"); + // Dismiss the OS popup, then use native select typeahead. Arrow keys open + // platform-specific pickers; typing exercises the browser's DOM selection. + await page.keyboard.press("Escape"); + await select.focus(); + await page.keyboard.press("e"); + await page.keyboard.press("Tab"); + await expect(select).toHaveValue("installation"); + expect(reads).toEqual([ + "/api/acquisition/preferences/personal", + "/api/acquisition/preferences/installation", + ]); + }); +} + +test("labels, keyboard, outside dismissal, and modal disabled groups work", async ({ + page, +}) => { + const { select } = await preferences(page); + await page + .locator(".settings-scope-picker") + .click({ position: { x: 8, y: 8 } }); + await expect(page.getByRole("listbox", { name: "Apply to" })).toBeVisible(); + await page.keyboard.press("Escape"); + await expect(select).toBeFocused(); + await select.press("ArrowDown"); + await page.keyboard.press("Enter"); + await expect(select).toHaveValue("installation"); + await select.click(); + await page + .getByRole("heading", { name: "Download preferences", exact: true }) + .click(); + await expect(page.getByRole("listbox")).toBeHidden(); + await page.evaluate(() => { + const dialog = document.createElement("dialog"); + dialog.innerHTML = + 'ebook:0'; + let count = 0; + dialog.querySelector("select")!.addEventListener("change", (event) => { + dialog.querySelector("output")!.textContent = + `${(event.target as HTMLSelectElement).value}:${++count}`; + }); + document.body.append(dialog); + dialog.showModal(); + }); + const modal = page.getByRole("dialog"); + await modal.getByLabel("Modal format").click(); + await expect( + modal.getByRole("option", { name: "Blocked", exact: true }).last(), + ).toBeDisabled(); + await modal + .getByRole("listbox") + .getByRole("option", { name: "Audiobook" }) + .click(); + await expect(modal.locator("output")).toHaveText("audio:1"); +}); + +test.describe("touch", () => { + test.skip( + process.env.BOOK_UI_BROWSER === "firefox", + "Firefox does not support touch emulation", + ); + test.use({ hasTouch: true }); + test("tapping opens and chooses one scope", async ({ page }) => { + const { select, reads } = await preferences(page); + await select.tap(); + await page + .getByRole("listbox") + .getByRole("option", { name: "Everyone on this server" }) + .tap(); + await expect(select).toHaveValue("installation"); + expect(reads).toEqual([ + "/api/acquisition/preferences/personal", + "/api/acquisition/preferences/installation", + ]); + }); +}); diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md index 79fe652b..3c38e315 100644 --- a/docs/DEVELOPMENT.md +++ b/docs/DEVELOPMENT.md @@ -200,6 +200,8 @@ Start with the smallest relevant selection through the bounded local runner: npm --prefix apps/web test # Specific browser area (also no database). npm --prefix apps/web run test:ui -- library-browsing.spec.ts +# Optional Firefox control checks (install that Playwright browser first). +BOOK_UI_BROWSER=firefox python3 scripts/check.py ui select-menu.spec.ts # Cheap focused Python regressions. python3 scripts/check.py unit tests/unit/test_security.py # Collection only: no build, browsers, migrations, or worker. diff --git a/docs/openapi.json b/docs/openapi.json index b21726c6..43ca3e64 100644 --- a/docs/openapi.json +++ b/docs/openapi.json @@ -11122,6 +11122,28 @@ "default": "identity", "title": "Scope" } + }, + { + "name": "medium", + "in": "query", + "required": false, + "schema": { + "anyOf": [ + { + "enum": [ + "ebook", + "audio", + "print", + "unknown" + ], + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Medium" + } } ], "responses": { diff --git a/services/app/adapters/catalog_providers.py b/services/app/adapters/catalog_providers.py index a1e35dbf..8ee1c049 100644 --- a/services/app/adapters/catalog_providers.py +++ b/services/app/adapters/catalog_providers.py @@ -149,11 +149,16 @@ async def query(self, query, variables): if codes & {"access-denied", "permission-error", "insufficient_scope"} else FailureKind.PARSER ) - raise AdapterError( - kind, - "Hardcover could not complete this query. " - "Check token scopes and provider compatibility.", - ) + if kind == FailureKind.PERMISSION: + message = "Hardcover denied this query. Check the connected token's scopes." + elif codes & {"validation-failed", "validation-error"}: + message = ( + "Hardcover's API schema does not support this query. " + "Check for a Dewarr update with compatible Hardcover queries." + ) + else: + message = "Hardcover returned an unsuccessful query response. Try again later." + raise AdapterError(kind, message) if not isinstance(value.get("data"), dict): raise parse_failure() return value["data"] @@ -309,6 +314,7 @@ def edition(row, work_id): "e-book": "ebook", "audio": "audio", "audiobook": "audio", + "listened": "audio", "physical": "print", "print": "print", }.get(format_name, "unknown") diff --git a/services/app/adapters/hardcover_follows.py b/services/app/adapters/hardcover_follows.py index 57005705..510f4d18 100644 --- a/services/app/adapters/hardcover_follows.py +++ b/services/app/adapters/hardcover_follows.py @@ -33,8 +33,8 @@ class FollowFilters(BaseModel): order_by: {id: asc}, limit: 100) { id title cached_contributors cached_image cached_tags release_date release_year is_partial_book book_series(limit: 101, order_by: {id: asc}) { series_id position compilation } - matching_editions: editions_aggregate(where: {language: {code2: {_eq: $language}}}) { - aggregate { count } + matching_editions: editions(where: {language: {code2: {_eq: $language}}}, limit: 1) { + id } } }""" @@ -128,8 +128,14 @@ async def page(query, kind, external_id, cursor, filters): day = ( date.fromisoformat(raw["release_date"]).isoformat() if raw["release_date"] else None ) - matches = raw["matching_editions"]["aggregate"]["count"] - if type(matches) is not int or matches < 0: + matches = raw["matching_editions"] + if not isinstance(matches, list) or len(matches) > 1: + raise invalid() + if matches and ( + not isinstance(matches[0], dict) + or type(matches[0].get("id")) is not int + or not 1 <= matches[0]["id"] <= 2147483647 + ): raise invalid() record = { "source_kind": kind, @@ -144,7 +150,7 @@ async def page(query, kind, external_id, cursor, filters): "main_series": (main or (kind == "author" and not memberships)) and not raw["is_partial_book"], "classification": (book.title + " " + str(raw.get("cached_tags") or "")).casefold(), - "language_match": matches > 0, + "language_match": bool(matches), "cover_url": cover_url((raw.get("cached_image") or {}).get("url")), } record["filter_reason"] = filter_reason(record, filters, kind) diff --git a/services/app/api/metadata.py b/services/app/api/metadata.py index ba7e64c2..2f43ce1f 100644 --- a/services/app/api/metadata.py +++ b/services/app/api/metadata.py @@ -815,6 +815,7 @@ async def work_metadata( offset: int = Query(default=0, ge=0), limit: int = Query(default=40, ge=1, le=100), scope: Literal["identity", "display"] = "identity", + medium: Literal["ebook", "audio", "print", "unknown"] | None = None, ): work = await accessible_work(db, user, work_id) work_id = work.id @@ -898,6 +899,8 @@ async def work_metadata( accessible_asset.where(owned_coverage(), LibraryAsset.state.in_(["present", "stale"])) ) conditions = [Version.work_id.in_(members)] + if medium is not None: + conditions.append(Version.medium == medium) conditions.append(or_(catalog_version, exists(accessible_asset), file_edition)) needs_review = exists( select(ProviderObject.id).where( diff --git a/tests/contracts/test_catalog_providers.py b/tests/contracts/test_catalog_providers.py index 7c9a8e3b..af6506cb 100644 --- a/tests/contracts/test_catalog_providers.py +++ b/tests/contracts/test_catalog_providers.py @@ -46,7 +46,7 @@ async def request(method, path, *, json): "release_year": 2001, } for i, format_name in enumerate( - ["Audio", "Ebook", "Physical", "Unspecified"], 1 + ["Listened", "Ebook", "Physical", "Unspecified"], 1 ) ], } @@ -302,3 +302,22 @@ async def hardcover_request(method, path, *, json): result = await Hardcover(hardcover_request).search("Book", 1, "en") assert [book.external_id for book in result.items] == ["2"] + + +@pytest.mark.parametrize( + "code,kind,message", + [ + ("validation-failed", FailureKind.PARSER, "API schema does not support"), + ("insufficient_scope", FailureKind.PERMISSION, "token's scopes"), + ("access-denied", FailureKind.PERMISSION, "token's scopes"), + ], +) +async def test_hardcover_schema_and_scope_errors_have_distinct_safe_guidance(code, kind, message): + async def request(*args, **kwargs): + return {"errors": [{"message": "private diagnostic", "extensions": {"code": code}}]} + + with pytest.raises(AdapterError) as caught: + await Hardcover(request).search("Book", 1) + assert caught.value.kind == kind + assert message in str(caught.value) + assert "private diagnostic" not in str(caught.value) diff --git a/tests/integration/test_catalog_controls.py b/tests/integration/test_catalog_controls.py new file mode 100644 index 00000000..1f856aad --- /dev/null +++ b/tests/integration/test_catalog_controls.py @@ -0,0 +1,189 @@ +"""Provider responses through follow synchronization and catalog edition views.""" + +from copy import deepcopy +from uuid import UUID + +import httpx +import pytest +from sqlalchemy import select + +from app.adapters.catalog_providers import Hardcover +from app.db.models import CatalogAccount, ListObservation, ListSubscription, Operation +from app.domain.catalog_network import CatalogGateway +from app.security import encrypt_secrets +from tests.integration.test_follows import observe +from tests.unit.test_hardcover_follows import response + +pytestmark = pytest.mark.integration + + +@pytest.mark.parametrize("kind", ["author", "series"]) +@pytest.mark.parametrize("language", [None, "en"]) +async def test_current_schema_follows_publish_verified_language_filtered_pages( + client, database, admin, monkeypatch, kind, language +): + async with database() as db, db.begin(): + db.add( + CatalogAccount( + user_id=UUID(admin["id"]), + enabled=True, + generation=1, + encrypted_token=encrypt_secrets({"token": "fixture-only"}), + ) + ) + cursors = [] + + async def request(self, method, path, *, json): + # Replay the reported schema boundary, including the old query's failure. + if "editions_aggregate" in json["query"]: + return {"errors": [{"extensions": {"code": "validation-failed"}}]} + variables = json["variables"] + assert variables["language"] == (language or "") + cursor = variables["after"] + cursors.append(cursor) + data = response() + data["books_aggregate"]["aggregate"]["count"] = 3 + template = data["books"][0] + data["books"] = [] + for key in [42, 43, 44]: + if key <= cursor: + continue + row = deepcopy(template) + row.update( + id=key, + title=f"Book {key}", + release_date="2020-01-01", + matching_editions=[{"id": key * 10}] if key != 43 else [], + ) + data["books"].append(row) + data["books"] = data["books"][:2] + return {"data": data} + + monkeypatch.setattr(CatalogGateway, "request", request) + created = await client.post( + "/api/following", + json={ + "source_kind": kind, + "external_id": 9, + "name": "Writer", + "filters": {"language": language}, + }, + ) + assert created.status_code == 201, created.text + follow = created.json() + await observe(client, database, follow, initial=True) + assert cursors == [0, 43, 44, 0, 43, 44] + async with database() as db: + subscription = await db.get(ListSubscription, UUID(follow["subscription"]["id"])) + operation = await db.get(Operation, subscription.operation_id) + assert operation.status == "completed", operation.message + observations = ( + await db.scalars( + select(ListObservation) + .where(ListObservation.subscription_id == subscription.id) + .order_by(ListObservation.external_id) + ) + ).all() + assert [row.external_id for row in observations] == ["42", "43", "44"] + assert [row.snapshot["filter_reason"] for row in observations] == [ + None, + "No matching language edition" if language else None, + None, + ] + listing = (await client.get(f"/api/lists/{follow['list_id']}")).json() + assert sorted(row["title"] for row in listing["items"]) == ( + ["Book 42", "Book 44"] if language else ["Book 42", "Book 43", "Book 44"] + ) + + +async def test_reported_audiobook_survives_identifier_cache_import_and_format_paging( + client, database, admin, monkeypatch +): + from app.api import metadata + + calls = [] + book = { + "id": 602482, + "title": "Tress of the Emerald Sea", + "canonical_id": None, + "cached_contributors": [{"author": {"name": "Brandon Sanderson"}}], + } + # Observed on Hardcover's public edition page on 2026-10-15. The transport + # uses the GraphQL field names consumed by the adapter (the page uses camelCase). + audio = { + "id": 31639613, + "book_id": 602482, + "title": book["title"], + "isbn_13": "9798890553157", + "asin": "B0D9PHGVV7", + "reading_format": {"format": "Listened"}, + "language": None, + "publisher": {"name": "Graphic Audio LLC"}, + } + editions = [ + { + "id": key, + "book_id": 602482, + "title": f"Print {key}", + "reading_format": {"format": "Physical"}, + } + for key in range(1, 25) + ] + [audio] + + def respond(request): + import json + + payload = json.loads(request.content) + calls.append(payload) + if "LibraryIdentifierMatch" in payload["query"]: + return httpx.Response(200, json={"data": {"editions": [{**audio, "book": book}]}}) + assert payload["variables"] == {"id": 602482, "offset": 0} + return httpx.Response(200, json={"data": {"books": [book], "editions": editions}}) + + class Gateway(CatalogGateway): + def __init__(self, *args, **kwargs): + super().__init__(*args, **kwargs, transport=httpx.MockTransport(respond)) + + async def reserve(self): + pass + + monkeypatch.setattr(metadata, "CatalogGateway", Gateway) + async with database() as db, db.begin(): + db.add( + CatalogAccount( + user_id=UUID(admin["id"]), + enabled=True, + generation=1, + encrypted_token=encrypt_secrets({"token": "fixture-only"}), + ) + ) + async with Gateway("hardcover", "identifier-test", "fixture-only") as gateway: + identified = await Hardcover(gateway.request).identifier_search([("isbn", "9798890553157")]) + assert [(b.external_id, b.canonical_id) for b in identified.items] == [("602482", None)] + assert identified.items[0].editions[0].medium == "audio" + preview = await client.get("/api/metadata/books/hardcover/602482") + assert preview.status_code == 200, preview.text + result = preview.json() + assert result["stale"] is False and result["warning"] is None + assert result["book"]["editions"][-1]["external_id"] == "31639613" + assert result["book"]["editions"][-1]["medium"] == "audio" + imported = await client.post("/api/metadata/books/hardcover/602482/import") + assert imported.status_code == 200, imported.text + assert len(calls) == 2 # Import reuses the cached raw response and the same mapper. + url = f"/api/metadata/works/{imported.json()['id']}" + all_editions = (await client.get(url, params={"limit": 1, "scope": "display"})).json() + assert all_editions["versions_total"] == 25 + filtered = ( + await client.get(url, params={"medium": "audio", "limit": 1, "scope": "display"}) + ).json() + assert filtered["versions_total"] == 1 + assert [(v["medium"], v["identifiers"]["isbn_13"]) for v in filtered["versions"]] == [ + ("audio", "9798890553157") + ] + print_page = ( + await client.get(url, params={"medium": "print", "limit": 1, "offset": 23}) + ).json() + assert print_page["versions_total"] == 24 and print_page["versions"][0]["medium"] == "print" + empty = (await client.get(url, params={"medium": "ebook"})).json() + assert empty["versions_total"] == 0 and empty["versions"] == [] + assert (await client.get(url, params={"medium": "invalid"})).status_code == 422 diff --git a/tests/unit/test_hardcover_follows.py b/tests/unit/test_hardcover_follows.py index b7df4255..87eb7acb 100644 --- a/tests/unit/test_hardcover_follows.py +++ b/tests/unit/test_hardcover_follows.py @@ -21,7 +21,7 @@ def response(): "release_year": 2030, "is_partial_book": False, "book_series": [{"series_id": 9, "position": "1", "compilation": False}], - "matching_editions": {"aggregate": {"count": 1}}, + "matching_editions": [{"id": 123}], } ], } @@ -124,3 +124,27 @@ async def query(*args): result = await page(query, "author", "9", 0, FollowFilters()) assert result.items[0]["coming_soon"] is True assert result.items[0]["release_date"] is None + + +@pytest.mark.parametrize( + "matches", + [ + None, + {}, + [None], + [{}], + [{"id": True}], + [{"id": 0}], + [{"id": 2147483648}], + [{"id": 1}, {"id": 2}], + ], +) +async def test_language_existence_rows_must_be_bounded_valid_editions(matches): + data = response() + data["books"][0]["matching_editions"] = matches + + async def query(*args): + return data + + with pytest.raises(AdapterError): + await page(query, "author", "9", 0, FollowFilters(language="en")) From 8ed9e49b8f20dd48188255eedb1e9f3a8bc2c727 Mon Sep 17 00:00:00 2001 From: Logan Abell Date: Thu, 15 Oct 2026 09:32:08 -0400 Subject: [PATCH 2/2] test(web): scope library review success during next search --- apps/web/tests/ui/library-review.spec.ts | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/apps/web/tests/ui/library-review.spec.ts b/apps/web/tests/ui/library-review.spec.ts index f77cd967..371f6412 100644 --- a/apps/web/tests/ui/library-review.spec.ts +++ b/apps/web/tests/ui/library-review.spec.ts @@ -28,6 +28,10 @@ test("library review links unmatched items to Dewarr and Hardcover books", async page.on("pageerror", (e) => errors.push(e.message)); const matchSearches: string[] = []; const matches: { asset: string; body: unknown }[] = []; + let releaseNextSearch!: () => void; + const nextSearch = new Promise((resolve) => { + releaseNextSearch = resolve; + }); let imported = false; const items = [ { kind: "asset", asset: asset("a1", "Untagged Folder", ["title"]) }, @@ -115,6 +119,7 @@ test("library review links unmatched items to Dewarr and Hardcover books", async data = { items: shown, total: shown.length }; } else if (path === "/api/catalog/works") { matchSearches.push(url.searchParams.get("q") || ""); + if (url.searchParams.get("q") === "The Long Way") await nextSearch; data = { items: [work], total: 1 }; } else if (path.endsWith("/match") && method === "POST") { const id = path.split("/").at(-2)!; @@ -214,9 +219,16 @@ test("library review links unmatched items to Dewarr and Hardcover books", async part_total: null, }, }); - await expect(page.getByRole("status")).toContainText( - "Linked “Untagged Folder”", - ); + try { + // Saving and continuing can announce success while the next lookup is pending. + await expect(detail.getByRole("status")).toHaveText("Searching catalog…"); + await expect( + page.getByRole("status").filter({ hasText: "Linked “Untagged Folder”" }), + ).toBeVisible(); + } finally { + releaseNextSearch(); + } + await expect(detail.getByRole("status")).toHaveCount(0); await expect(cards).toHaveCount(2); await expect( nav.getByRole("link", { name: /^Library review/ }),