From 18b88672ec4d15145c631cee52a096b3a8739e07 Mon Sep 17 00:00:00 2001
From: Marcel <marcel@familienarchiv>
Date: Fri, 24 Apr 2026 10:52:13 +0200
Subject: [PATCH] =?UTF-8?q?fix(pagination):=20bound=20controls=20render=20?=
 =?UTF-8?q?as=20aria-hidden=20spans=20=E2=80=94=20address=20@leonievoss?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

<a aria-disabled="true"> is the documented pattern but screen readers
still announce "Previous, link, disabled" on pagination bounds — noise
users don't need because the disabled state is purely visual. Switching
to <span aria-hidden="true"> removes the bound control from the AT tree
entirely (Leonie's recommendation). Visual parity preserved via a
disabledBase Tailwind class (same layout + cursor-not-allowed + opacity-40).

Tests updated: "disabled prev/next" assertions now check for aria-hidden
and no href — the active-state href/aria-current assertions are
unchanged. (#316)

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 frontend/src/lib/components/Pagination.svelte | 66 ++++++++++++-------
 .../lib/components/Pagination.svelte.spec.ts  | 10 +--
 2 files changed, 50 insertions(+), 26 deletions(-)

diff --git a/frontend/src/lib/components/Pagination.svelte b/frontend/src/lib/components/Pagination.svelte
index 0edf0fb7..01659e9e 100644
--- a/frontend/src/lib/components/Pagination.svelte
+++ b/frontend/src/lib/components/Pagination.svelte
@@ -16,8 +16,10 @@ const { page, totalPages, makeHref, ariaLabel }: Props = $props();
 
 const hasPrev = $derived(page > 0);
 const hasNext = $derived(page < totalPages - 1);
-const linkBase =
-	'inline-flex min-h-[44px] min-w-[44px] items-center justify-center gap-1.5 rounded-sm border border-line bg-white px-4 py-2 font-sans text-sm font-bold text-ink transition-colors hover:bg-surface focus-visible:ring-2 focus-visible:ring-brand-navy focus-visible:ring-offset-2 focus-visible:outline-none aria-disabled:pointer-events-none aria-disabled:cursor-not-allowed aria-disabled:opacity-40';
+const controlBase =
+	'inline-flex min-h-[44px] min-w-[44px] items-center justify-center gap-1.5 rounded-sm border border-line bg-white px-4 py-2 font-sans text-sm font-bold text-ink';
+const linkBase = `${controlBase} transition-colors hover:bg-surface focus-visible:ring-2 focus-visible:ring-brand-navy focus-visible:ring-offset-2 focus-visible:outline-none`;
+const disabledBase = `${controlBase} cursor-not-allowed opacity-40`;
 </script>
 
 {#if totalPages > 1}
@@ -25,16 +27,30 @@ const linkBase =
 		aria-label={ariaLabel ?? m.pagination_nav_label()}
 		class="mt-6 flex flex-col items-center gap-3 sm:flex-row sm:justify-between"
 	>
-		<a
-			data-testid="pagination-prev"
-			aria-label={m.pagination_prev()}
-			aria-disabled={!hasPrev}
-			href={hasPrev ? makeHref(page - 1) : undefined}
-			class={linkBase}
-		>
-			<span aria-hidden="true">«</span>
-			{m.pagination_prev()}
-		</a>
+		<!--
+			At the bounds we render a <span aria-hidden="true"> instead of an
+			<a aria-disabled>. aria-disabled on a link is the documented pattern
+			but screen readers still announce "Previous, link, disabled" — which
+			is confusing on a pagination control where the disabled state is
+			purely visual. Hiding the element from the AT tree entirely is the
+			cleaner semantic.
+		-->
+		{#if hasPrev}
+			<a
+				data-testid="pagination-prev"
+				aria-label={m.pagination_prev()}
+				href={makeHref(page - 1)}
+				class={linkBase}
+			>
+				<span aria-hidden="true">«</span>
+				{m.pagination_prev()}
+			</a>
+		{:else}
+			<span data-testid="pagination-prev" aria-hidden="true" class={disabledBase}>
+				<span aria-hidden="true">«</span>
+				{m.pagination_prev()}
+			</span>
+		{/if}
 
 		<span
 			data-testid="pagination-page-label"
@@ -44,15 +60,21 @@ const linkBase =
 			{m.pagination_page_of({ page: page + 1, total: totalPages })}
 		</span>
 
-		<a
-			data-testid="pagination-next"
-			aria-label={m.pagination_next()}
-			aria-disabled={!hasNext}
-			href={hasNext ? makeHref(page + 1) : undefined}
-			class={linkBase}
-		>
-			{m.pagination_next()}
-			<span aria-hidden="true">»</span>
-		</a>
+		{#if hasNext}
+			<a
+				data-testid="pagination-next"
+				aria-label={m.pagination_next()}
+				href={makeHref(page + 1)}
+				class={linkBase}
+			>
+				{m.pagination_next()}
+				<span aria-hidden="true">»</span>
+			</a>
+		{:else}
+			<span data-testid="pagination-next" aria-hidden="true" class={disabledBase}>
+				{m.pagination_next()}
+				<span aria-hidden="true">»</span>
+			</span>
+		{/if}
 	</nav>
 {/if}
diff --git a/frontend/src/lib/components/Pagination.svelte.spec.ts b/frontend/src/lib/components/Pagination.svelte.spec.ts
index 68af1558..90bf8532 100644
--- a/frontend/src/lib/components/Pagination.svelte.spec.ts
+++ b/frontend/src/lib/components/Pagination.svelte.spec.ts
@@ -33,12 +33,14 @@ describe('Pagination', () => {
 		await expect.element(prev).toHaveAttribute('href', '/documents?page=3');
 	});
 
-	it('disables prev on page 0 (no href, aria-disabled="true")', async () => {
+	it('renders disabled prev as an aria-hidden non-link so screen readers skip it', async () => {
 		render(Pagination, { page: 0, totalPages: 3, makeHref });
 
 		const prev = page.getByTestId('pagination-prev');
-		await expect.element(prev).toHaveAttribute('aria-disabled', 'true');
+		// Not a link — no href, no role=link
 		await expect.element(prev).not.toHaveAttribute('href');
+		// Hidden from assistive tech — AT shouldn't read "Previous, link, disabled"
+		await expect.element(prev).toHaveAttribute('aria-hidden', 'true');
 	});
 
 	it('renders next as a link pointing at page + 1 when not on last page', async () => {
@@ -48,12 +50,12 @@ describe('Pagination', () => {
 		await expect.element(next).toHaveAttribute('href', '/documents?page=1');
 	});
 
-	it('disables next on the last page (no href, aria-disabled="true")', async () => {
+	it('renders disabled next as an aria-hidden non-link on the last page', async () => {
 		render(Pagination, { page: 2, totalPages: 3, makeHref });
 
 		const next = page.getByTestId('pagination-next');
-		await expect.element(next).toHaveAttribute('aria-disabled', 'true');
 		await expect.element(next).not.toHaveAttribute('href');
+		await expect.element(next).toHaveAttribute('aria-hidden', 'true');
 	});
 
 	it('calls makeHref with p-1 and p+1', async () => {