From ea61304784b77fd38b52200fd5e67f7bef20886a Mon Sep 17 00:00:00 2001
From: Even <evenkkl@stud.ntnu.no>
Date: Wed, 16 Sep 2026 20:56:11 +0200
Subject: [PATCH] feat: improve accessibility of library controls and book
 viewer (#31)

- Announce loading, empty-result and changed-book feedback through one
  persistent role="status" region in App; errors keep role="alert"
- Keep Previous/Next focusable at the boundaries with aria-disabled
  instead of disabled
- Move focus to the Favorites heading after removing a favorite
- Include the book title in the no-cover fallback to match the alt text
- Add tests for the announcements, focus handling and keyboard-only use
- Update App, BookCard, FavoritesView and NavigationControls snapshots
  deliberately for the markup changes above

Closes #31

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 src/App.css                                   |  9 ++++
 src/App.test.tsx                              | 47 ++++++++++++++++++-
 src/App.tsx                                   | 15 ++++--
 src/__snapshots__/App.test.tsx.snap           | 22 +++++++--
 src/components/BookCard.test.tsx              |  2 +-
 src/components/BookCard.tsx                   |  2 +-
 src/components/FavoritesView.test.tsx         |  8 ++++
 src/components/FavoritesView.tsx              | 13 ++++-
 src/components/NavigationControls.css         |  4 +-
 src/components/NavigationControls.test.tsx    | 34 ++++++++++++--
 src/components/NavigationControls.tsx         | 13 +++--
 .../__snapshots__/BookCard.test.tsx.snap      |  3 +-
 .../__snapshots__/FavoritesView.test.tsx.snap |  1 +
 .../NavigationControls.test.tsx.snap          |  3 +-
 14 files changed, 151 insertions(+), 25 deletions(-)

diff --git a/src/App.css b/src/App.css
index 7188ed3..f85c675 100644
--- a/src/App.css
+++ b/src/App.css
@@ -34,6 +34,15 @@
   margin: 0 auto;
 }
 
+.visually-hidden {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+}
+
 .app-footer {
   padding: 0.75rem;
   text-align: center;
diff --git a/src/App.test.tsx b/src/App.test.tsx
index de5f00a..c0d6da8 100644
--- a/src/App.test.tsx
+++ b/src/App.test.tsx
@@ -46,7 +46,52 @@ describe("App", () => {
   it("shows an empty message when no books match the subject", async () => {
     server.use(emptySearchHandler);
     withProviders(<App />);
-    expect(await screen.findByText(/No books found/)).toBeInTheDocument();
+    await waitFor(() => expect(screen.getByRole("status")).toHaveTextContent("No books found"));
+  });
+
+  it("announces the book shown after navigating", async () => {
+    const user = userEvent.setup();
+    withProviders(<App />);
+    await screen.findByRole("heading", { name: "A Wizard of Earthsea" });
+
+    await user.click(screen.getByRole("button", { name: "Show next book" }));
+
+    expect(screen.getByRole("status")).toHaveTextContent("Showing book 2 of 3: The Hobbit");
+  });
+
+  it("operates the library controls with the keyboard only", async () => {
+    const user = userEvent.setup();
+    withProviders(<App />);
+    await screen.findByRole("heading", { name: "A Wizard of Earthsea" });
+
+    await user.tab();
+    expect(screen.getByRole("combobox", { name: "Subject" })).toHaveFocus();
+    await user.tab();
+    expect(screen.getByRole("combobox", { name: "Sort by" })).toHaveFocus();
+
+    await user.tab();
+    expect(
+      screen.getByRole("button", { name: "Add A Wizard of Earthsea to favorites" }),
+    ).toHaveFocus();
+    await user.keyboard("{Enter}");
+    expect(localStorage.getItem("t19.favorites")).toBe(JSON.stringify(["/works/OL2"]));
+
+    await user.tab();
+    expect(screen.getByRole("button", { name: "Show previous book" })).toHaveFocus();
+    await user.tab();
+    expect(screen.getByRole("button", { name: "Show next book" })).toHaveFocus();
+    await user.keyboard("{Enter}");
+    expect(await screen.findByRole("heading", { name: "The Hobbit" })).toBeInTheDocument();
+
+    await user.tab();
+    expect(screen.getByRole("combobox", { name: "Jump to book" })).toHaveFocus();
+
+    await user.tab();
+    expect(
+      screen.getByRole("button", { name: "Remove A Wizard of Earthsea from favorites list" }),
+    ).toHaveFocus();
+    await user.keyboard("{Enter}");
+    expect(localStorage.getItem("t19.favorites")).toBe(JSON.stringify([]));
   });
 
   it("navigates to the next and previous book with the controls", async () => {
diff --git a/src/App.tsx b/src/App.tsx
index 25a4c54..bd05b5b 100644
--- a/src/App.tsx
+++ b/src/App.tsx
@@ -43,11 +43,18 @@ function App() {
       <main className="app-main">
         <SubjectFilter subject={subject} onSubjectChange={handleSubjectChange} />
         <SortSelect sort={sort} onSortChange={handleSortChange} />
-        {isLoading && <p role="status">Loading books…</p>}
+        <div role="status">
+          {isLoading && <p>Loading books…</p>}
+          {!isLoading && !isError && books.length === 0 && (
+            <p>No books found for the subject “{subject}”.</p>
+          )}
+          {current && (
+            <p className="visually-hidden">
+              Showing book {safeIndex + 1} of {sortedBooks.length}: {current.title}
+            </p>
+          )}
+        </div>
         {isError && <p role="alert">Could not load books. Please try refreshing the page.</p>}
-        {!isLoading && !isError && books.length === 0 && (
-          <p>No books found for the subject “{subject}”.</p>
-        )}
         {current && (
           <section className="book-viewer" aria-label="Book viewer">
             <BookCard
diff --git a/src/__snapshots__/App.test.tsx.snap b/src/__snapshots__/App.test.tsx.snap
index 69cfc6c..50cfcd5 100644
--- a/src/__snapshots__/App.test.tsx.snap
+++ b/src/__snapshots__/App.test.tsx.snap
@@ -88,6 +88,20 @@ exports[`App > matches the snapshot 1`] = `
           </option>
         </select>
       </label>
+      <div
+        role="status"
+      >
+        <p
+          class="visually-hidden"
+        >
+          Showing book 
+          1
+           of 
+          3
+          : 
+          A Wizard of Earthsea
+        </p>
+      </div>
       <section
         aria-label="Book viewer"
         class="book-viewer"
@@ -99,7 +113,8 @@ exports[`App > matches the snapshot 1`] = `
             class="book-card-cover"
           >
             <p>
-              No cover available
+              No cover available for 
+              A Wizard of Earthsea
             </p>
           </div>
           <div
@@ -143,14 +158,13 @@ exports[`App > matches the snapshot 1`] = `
           class="navigation-controls"
         >
           <button
+            aria-disabled="true"
             aria-label="Show previous book"
-            disabled=""
             type="button"
           >
             Previous
           </button>
           <p
-            aria-live="polite"
             class="navigation-progress"
           >
             1
@@ -158,6 +172,7 @@ exports[`App > matches the snapshot 1`] = `
             3
           </p>
           <button
+            aria-disabled="false"
             aria-label="Show next book"
             type="button"
           >
@@ -196,6 +211,7 @@ exports[`App > matches the snapshot 1`] = `
       >
         <h2
           id="favorites-heading"
+          tabindex="-1"
         >
           Favorites
         </h2>
diff --git a/src/components/BookCard.test.tsx b/src/components/BookCard.test.tsx
index 4e74de9..029f9e0 100644
--- a/src/components/BookCard.test.tsx
+++ b/src/components/BookCard.test.tsx
@@ -37,7 +37,7 @@ describe("BookCard", () => {
 
     expect(screen.getByRole("heading", { name: minimalBook.title })).toBeInTheDocument();
     expect(screen.getByText("Unknown author")).toBeInTheDocument();
-    expect(screen.getByText("No cover available")).toBeInTheDocument();
+    expect(screen.getByText(`No cover available for ${minimalBook.title}`)).toBeInTheDocument();
     expect(screen.queryByRole("img")).not.toBeInTheDocument();
     expect(container).toMatchSnapshot();
   });
diff --git a/src/components/BookCard.tsx b/src/components/BookCard.tsx
index 72d95fd..7d83927 100644
--- a/src/components/BookCard.tsx
+++ b/src/components/BookCard.tsx
@@ -19,7 +19,7 @@ export function BookCard({ book, isFavorite = false, onFavoriteToggle }: BookCar
         {imageUrl ? (
           <img src={imageUrl} alt={`Cover of ${book.title}`} />
         ) : (
-          <p>No cover available</p>
+          <p>No cover available for {book.title}</p>
         )}
       </div>
       <div className="book-card-content">
diff --git a/src/components/FavoritesView.test.tsx b/src/components/FavoritesView.test.tsx
index d983911..131be14 100644
--- a/src/components/FavoritesView.test.tsx
+++ b/src/components/FavoritesView.test.tsx
@@ -27,6 +27,14 @@ describe("FavoritesView", () => {
     expect(onRemove).toHaveBeenCalledWith("/works/OL1");
   });
 
+  it("moves focus to the favorites heading after a removal", () => {
+    render(<FavoritesView books={books} favoriteKeys={["/works/OL1"]} onRemove={vi.fn()} />);
+
+    fireEvent.click(screen.getByRole("button", { name: "Remove The Hobbit from favorites list" }));
+
+    expect(screen.getByRole("heading", { name: "Favorites" })).toHaveFocus();
+  });
+
   it("shows an empty state", () => {
     render(<FavoritesView books={books} favoriteKeys={[]} onRemove={vi.fn()} />);
 
diff --git a/src/components/FavoritesView.tsx b/src/components/FavoritesView.tsx
index 64e4e5f..9ca8d51 100644
--- a/src/components/FavoritesView.tsx
+++ b/src/components/FavoritesView.tsx
@@ -1,3 +1,4 @@
+import { useRef } from "react";
 import type { Book } from "../types";
 import "./FavoritesView.css";
 
@@ -9,10 +10,18 @@ interface FavoritesViewProps {
 
 export function FavoritesView({ books, favoriteKeys, onRemove }: FavoritesViewProps) {
   const favorites = books.filter((book) => favoriteKeys.includes(book.key));
+  const headingRef = useRef<HTMLHeadingElement>(null);
+
+  function handleRemove(bookKey: string) {
+    onRemove(bookKey);
+    headingRef.current?.focus();
+  }
 
   return (
     <section className="favorites-view" aria-labelledby="favorites-heading">
-      <h2 id="favorites-heading">Favorites</h2>
+      <h2 id="favorites-heading" ref={headingRef} tabIndex={-1}>
+        Favorites
+      </h2>
       {favorites.length === 0 ? (
         <p>No favorite books yet.</p>
       ) : (
@@ -26,7 +35,7 @@ export function FavoritesView({ books, favoriteKeys, onRemove }: FavoritesViewPr
               <button
                 type="button"
                 aria-label={`Remove ${book.title} from favorites list`}
-                onClick={() => onRemove(book.key)}
+                onClick={() => handleRemove(book.key)}
               >
                 Remove
               </button>
diff --git a/src/components/NavigationControls.css b/src/components/NavigationControls.css
index 1b3019d..c8e73b1 100644
--- a/src/components/NavigationControls.css
+++ b/src/components/NavigationControls.css
@@ -20,7 +20,7 @@
   color: #1f2933;
 }
 
-.navigation-controls button:hover:not(:disabled) {
+.navigation-controls button:hover:not([aria-disabled="true"]) {
   background-color: #f5f7fa;
 }
 
@@ -29,7 +29,7 @@
   outline-offset: 2px;
 }
 
-.navigation-controls button:disabled {
+.navigation-controls button[aria-disabled="true"] {
   opacity: 0.5;
   cursor: not-allowed;
 }
diff --git a/src/components/NavigationControls.test.tsx b/src/components/NavigationControls.test.tsx
index b37a86e..cee42c1 100644
--- a/src/components/NavigationControls.test.tsx
+++ b/src/components/NavigationControls.test.tsx
@@ -34,7 +34,31 @@ describe("NavigationControls", () => {
     expect(onNext).toHaveBeenCalledTimes(1);
   });
 
-  it("disables the buttons at the boundaries", async () => {
+  it("activates the buttons with the keyboard", async () => {
+    const user = userEvent.setup();
+    const onPrevious = vi.fn();
+    const onNext = vi.fn();
+    render(
+      <NavigationControls
+        currentIndex={2}
+        totalCount={10}
+        onPrevious={onPrevious}
+        onNext={onNext}
+      />,
+    );
+
+    await user.tab();
+    expect(screen.getByRole("button", { name: "Show previous book" })).toHaveFocus();
+    await user.keyboard("{Enter}");
+    await user.tab();
+    expect(screen.getByRole("button", { name: "Show next book" })).toHaveFocus();
+    await user.keyboard(" ");
+
+    expect(onPrevious).toHaveBeenCalledTimes(1);
+    expect(onNext).toHaveBeenCalledTimes(1);
+  });
+
+  it("marks the buttons as disabled at the boundaries but keeps them focusable", async () => {
     const user = userEvent.setup();
     const onPrevious = vi.fn();
     const onNext = vi.fn();
@@ -47,8 +71,10 @@ describe("NavigationControls", () => {
       />,
     );
     const previous = screen.getByRole("button", { name: "Show previous book" });
-    expect(previous).toBeDisabled();
-    await user.click(previous);
+    expect(previous).toHaveAttribute("aria-disabled", "true");
+    await user.tab();
+    expect(previous).toHaveFocus();
+    await user.keyboard("{Enter}");
     expect(onPrevious).not.toHaveBeenCalled();
 
     rerender(
@@ -60,7 +86,7 @@ describe("NavigationControls", () => {
       />,
     );
     const next = screen.getByRole("button", { name: "Show next book" });
-    expect(next).toBeDisabled();
+    expect(next).toHaveAttribute("aria-disabled", "true");
     await user.click(next);
     expect(onNext).not.toHaveBeenCalled();
     expect(screen.getByText("10 / 10")).toBeInTheDocument();
diff --git a/src/components/NavigationControls.tsx b/src/components/NavigationControls.tsx
index 58f9b25..ca7731e 100644
--- a/src/components/NavigationControls.tsx
+++ b/src/components/NavigationControls.tsx
@@ -13,23 +13,26 @@ export function NavigationControls({
   onPrevious,
   onNext,
 }: NavigationControlsProps) {
+  const isFirst = currentIndex === 0;
+  const isLast = currentIndex >= totalCount - 1;
+
   return (
     <nav className="navigation-controls" aria-label="Book navigation">
       <button
         type="button"
-        onClick={onPrevious}
-        disabled={currentIndex === 0}
+        onClick={isFirst ? undefined : onPrevious}
+        aria-disabled={isFirst}
         aria-label="Show previous book"
       >
         Previous
       </button>
-      <p className="navigation-progress" aria-live="polite">
+      <p className="navigation-progress">
         {currentIndex + 1} / {totalCount}
       </p>
       <button
         type="button"
-        onClick={onNext}
-        disabled={currentIndex >= totalCount - 1}
+        onClick={isLast ? undefined : onNext}
+        aria-disabled={isLast}
         aria-label="Show next book"
       >
         Next
diff --git a/src/components/__snapshots__/BookCard.test.tsx.snap b/src/components/__snapshots__/BookCard.test.tsx.snap
index 3d54a76..e89b630 100644
--- a/src/components/__snapshots__/BookCard.test.tsx.snap
+++ b/src/components/__snapshots__/BookCard.test.tsx.snap
@@ -53,7 +53,8 @@ exports[`BookCard > renders a placeholder for a minimal book 1`] = `
       class="book-card-cover"
     >
       <p>
-        No cover available
+        No cover available for 
+        Untitled Book
       </p>
     </div>
     <div
diff --git a/src/components/__snapshots__/FavoritesView.test.tsx.snap b/src/components/__snapshots__/FavoritesView.test.tsx.snap
index 2fe9c39..bb4e211 100644
--- a/src/components/__snapshots__/FavoritesView.test.tsx.snap
+++ b/src/components/__snapshots__/FavoritesView.test.tsx.snap
@@ -8,6 +8,7 @@ exports[`FavoritesView > matches the rendered snapshot 1`] = `
   >
     <h2
       id="favorites-heading"
+      tabindex="-1"
     >
       Favorites
     </h2>
diff --git a/src/components/__snapshots__/NavigationControls.test.tsx.snap b/src/components/__snapshots__/NavigationControls.test.tsx.snap
index 8ec68b3..8a8b8be 100644
--- a/src/components/__snapshots__/NavigationControls.test.tsx.snap
+++ b/src/components/__snapshots__/NavigationControls.test.tsx.snap
@@ -7,13 +7,13 @@ exports[`NavigationControls > matches the snapshot 1`] = `
     class="navigation-controls"
   >
     <button
+      aria-disabled="false"
       aria-label="Show previous book"
       type="button"
     >
       Previous
     </button>
     <p
-      aria-live="polite"
       class="navigation-progress"
     >
       3
@@ -21,6 +21,7 @@ exports[`NavigationControls > matches the snapshot 1`] = `
       10
     </p>
     <button
+      aria-disabled="false"
       aria-label="Show next book"
       type="button"
     >