Files
AndreaSlopFotografie/aidlc-docs/bugs/hero-carousel-announce-and-pause/bug-fix.md
T
SluijsensandClaude Opus 5.5 b332f1a846
Continuous Integration / check (pull_request) Successful in 6m47s
Continuous Integration / deploy-test (pull_request) Skipped
Continuous Integration / lighthouse (pull_request) Successful in 3m47s
Continuous Integration / deploy-production (pull_request) Skipped
Announces pausing and resuming the hero slide show
The pause button only changed its name, which screen readers often do not read
for the focused button. The live region now also says when the slide show is
paused or plays again.

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

102 lines
8.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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](hero-repro.mjs) (puppeteer), output: [repro-before.txt](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).
**Follow-up after the owner's test (2026-10-19)**: "Nou is er eigenlijk hetzelfde probleem met de pauzeer-knop en de afspelen-knop. Zodra je erop klikt krijg je geen feedback dat de diavoorstelling is gepauzeerd. Verder vind ik de knop op een goede plek staan en er netjes uitzien."
- Same mechanism as the arrows: focus stays on the button and only its name changes; screen readers do not reliably read the new name of the focused button.
- `useHeroSlider.ts`: the boolean became `announcement: 'slide' | 'paused' | 'playing' | null`; `toggleStopped` sets `paused` or `playing`, `advance` still clears it.
- `Hero.tsx`: the same live region now also says "Diavoorstelling gepauzeerd" or "Diavoorstelling speelt weer af" (`announcementText`).
- Tests: the pause test checks both messages; the hook test checks them and that the next automatic change clears them.
- Placement and look of the button: approved by the owner.
**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](hero-repro.mjs) for the real animation.
**Before the fix** ([tests-before.txt](tests-before.txt), [repro-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](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 (run 545, `46fb2f6`; check on the Pi, deploy on the Pi, Lighthouse on the PC, all green; PR run 544 green): the same six results as locally, see [repro-after-test.txt](repro-after-test.txt).
- Placement: [hero-desktop.png](hero-desktop.png) (1440×900) and [hero-mobile.png](hero-mobile.png) (390×844): the button sits bottom right, level with the socials and below the right arrow.
- Owner's own screen reader check on test: (pending)
## Result
- **PR(s)**: #5 (https://gitea.slpsoftware.nl/SLP_Software/AndreaSlopFotografie/pulls/5)
- **Commit(s)**: 46fb2f6 (fix)
- **Completed**: —