Files
AndreaSlopFotografie/aidlc-docs/bugs/hero-carousel-announce-and-pause/bug-fix.md
T
SluijsensandClaude Opus 5.5 46fb2f6b5c
Continuous Integration / check (pull_request) Successful in 59s
Continuous Integration / deploy-test (pull_request) Skipped
Continuous Integration / lighthouse (pull_request) Successful in 3m59s
Continuous Integration / deploy-production (pull_request) Skipped
Announces manual hero slide changes and adds a pause button
Screen readers now hear the new photo after an arrow or swipe, while automatic
changes stay silent. A pause button bottom right lets visitors stop the slide
show, which hover and keyboard focus alone did not allow on touch screens.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-19 19:31:31 +02:00

7.4 KiB

Bug Fix: Hero carousel gives no feedback on manual slide change and has no pause control

  • Slug: hero-carousel-announce-and-pause
  • Status: Fixing
  • Issue: None (raised by the owner after the frontend-shell feature)
  • Branch: fix/hero-carousel-announce-and-pause
  • Started: 2026-10-19
  • Documentation Language: English (inherited from frontend-shell)
  • Conversation Language: User Language (Dutch)

Report

Reproduction steps

  1. Open the home page (https://test.andreaslop.nl/) with a screen reader.
  2. Activate "Volgende foto" (or "Vorige foto") in the hero.
  3. Listen for what the screen reader says.
  4. Look for a way to stop the automatic slide show.

Expected behaviour

  • A slide change started by the visitor (arrow buttons, swipe) is announced, e.g. "Foto 2 van 8: Zwangerschapsfoto in de duinen".
  • An automatic slide change stays silent, otherwise the visitor is interrupted every 6 seconds.
  • There is a visible button to pause and restart the automatic slide show (WCAG 2.2.2 Pause, Stop, Hide; the W3C APG carousel pattern calls this the rotation control).

Actual behaviour

  • After activating an arrow, the screen reader says nothing; the focus stays on the unchanged button.
  • There is no pause control. Autoplay pauses only on mouse hover, keyboard focus inside the hero, a hidden tab, or prefers-reduced-motion. Touch users and screen reader users without keyboard focus in the hero cannot stop it.

Environment / context

  • Test environment, build 8f0f322 (master), Chrome headless 2026-10-19; applies to every browser and screen reader, as it is missing markup, not browser behaviour.
  • Reproduction script: hero-repro.mjs (puppeteer), output: repro-before.txt:
    • live regions in the hero before and after a click: none
    • active slide goes from "1 van 8" to "2 van 8"
    • buttons in the accessibility tree: "Menu openen", "Vorige foto", "Volgende foto" (no pause control)

Root Cause

Confidence: observed (reproduced on test and traced in code).

  1. No announcement — web/src/components/Hero/Hero.tsx:51-90 renders each slide as role="group" with aria-label="{n} van {total}" and hides inactive slides with aria-hidden. That is correct structure, but nothing in the hero is an aria-live region. Screen readers only speak a DOM change that happens inside a live region, or content that receives focus. HeroArrows.tsx:15-30 calls prev/next from useHeroSlider.ts:36-37, which only change index; focus stays on the arrow button, whose name does not change. So the change is silent.
    • The manual/automatic distinction is also absent: next is the same function for the arrow (HeroArrows), the swipe handler (useHeroSlider.ts:80-81) and the end of the progress-bar animation (Hero.tsx:151). A live region that simply mirrors the active slide would therefore also speak every automatic change.
  2. No pause control — useHeroSlider.ts:39-44 derives paused only from hovered, focused (:focus-visible inside the hero) and hidden, and autoplay from count > 1 && !reducedMotion. There is no user-controlled state, and Hero.tsx renders no control for it.

Ruled out: the slide aria-label and the image alt texts are present and correct; the problem is only that the change is not announced. The route-focus behaviour (useRouteFocus) is unrelated: it only acts on page navigation.

Confirmed with user: 2026-10-19 — "A) Ja, zo bouwen. Je mag zelf bouwen, committed en pushen. Deploy naar test zodat ik zelf even kan testen, maar ga door in het proces tot de merge. Als ik heb getest en toestemming geef gaan we pas door"

The pause button's place and look were proposed in the diagnosis and accepted with this answer: bottom right, mirroring the socials, same iconControl style, pause-outlined / caret-right-outlined icons, name switching between "Diavoorstelling pauzeren" and "Diavoorstelling afspelen".

The Fix

What changed

  • web/src/components/Hero/useHeroSlider.ts
    • Slide changes go through one go(to, visitor). next/prev (arrows, swipe) mark the change as made by the visitor; the new advance (end of the progress-bar animation) does not. announce exposes that flag.
    • New stopped state with toggleStopped; paused now also includes stopped, so a manual pause survives the mouse leaving the hero.
    • Resuming via the button also clears the hover and keyboard-focus pause. Without that, a click on "afspelen" did nothing visible: the click itself is a hover (and often a focus), which kept the slider paused. Found by the new test.
  • web/src/components/Hero/Hero.tsx
    • A VisuallyHidden live region (aria-live="polite", aria-atomic) that is always rendered (a live region must exist before its text changes). It shows "Foto {n} van {total}: {alt}" after a visitor change and is empty after an automatic change, so no stale message remains.
    • The progress bar calls advance instead of next, and carries data-state="running|paused".
    • Renders HeroPauseButton when autoplay is on.
  • web/src/components/Hero/HeroPauseButton.tsx (new): the pause/play button, bottom right at the socials' height, iconControl recipe (44 px target, white focus ring).
  • Tests: Hero.test.tsx (announcement, pause button, no button without autoplay, axe) and the new useHeroSlider.test.tsx (visitor vs. automatic change, wrap-around, resume clears hover and focus pause).

Why this and not something else

  • A live region that mirrors the active slide (or toggling aria-live between off and polite as in the W3C example): it would speak automatic changes too, or depend on exactly when rotation is paused. Separating visitor and automatic changes in the hook states the intent directly.
  • Moving focus to the new slide: would take the visitor away from the arrow they are pressing.
  • aria-pressed on the pause button: the W3C carousel pattern changes the button's name instead; doing both makes screen readers say contradictory things.
  • jsdom has no AnimationEvent, so React's onAnimationEnd cannot be triggered there; the automatic change is tested on the hook, and in a real browser by the script below.

Verification

Path used: Automated test framework (Vitest + Testing Library + axe), plus the scripted browser check hero-repro.mjs for the real animation.

Before the fix (tests-before.txt, repro-before.txt)

  • 3 of the new tests fail: no element hero-announcement, no hero-progress state, no button "Diavoorstelling pauzeren".
  • Browser on test (8f0f322): no live region before or after a click; buttons: "Menu openen", "Vorige foto", "Volgende foto".

After the fix

  • Hero tests: 10 passed. Full suite: 118 tests in 23 files passed; lint, format, typecheck and build clean.
  • Browser, local preview (repro-after-local.txt):
    1. before a click: live region present and empty
    2. after the arrow: "Foto 2 van 8: Knusse newbornfoto met de familie"
    3. after the automatic change to slide 3: live region empty
    4. buttons include "Diavoorstelling pauzeren"
    5. paused: slide stays at 3 for 7 s, button reads "Diavoorstelling afspelen"
    6. resumed: moves on to slide 4, button reads "Diavoorstelling pauzeren" again
  • On test after the deploy, and the owner's own screen reader check: (pending)

Result

  • PR(s): None yet
  • Commit(s): None yet
  • Completed: —