Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions .changeset/carousel-scroll-area-name.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
'@astryxdesign/core': patch
---

[fix] Carousel's scroll area is a group named like the carousel, so a screen-reader user who tabs onto it hears where they are. It is a tab stop only while its content overflows; a carousel that fits no longer adds an empty stop.

@vjeux
7 changes: 7 additions & 0 deletions .changeset/scroll-overflow-follows-content.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
'@astryxdesign/core': patch
---

[fix] `useScrollOverflow` measures again when the container's content changes with the container keeping its size: a child added, removed or resized, or a new gap or padding. Carousel's scroll area, a tab stop only while its content overflows, and its edge buttons and fades follow slides added or removed and a slide that grows; TabList's fades follow its tabs the same way.

@vjeux
2 changes: 1 addition & 1 deletion packages/core/src/Carousel/Carousel.doc.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ export const docs = {
{guidance: true, description: 'Enable scroll-snap when each item should land precisely at the start edge, like a gallery or product list.'},
{guidance: true, description: 'Reach for hasLoop on small, cyclable sets like a photo gallery, where wrapping past the last item back to the first feels natural.'},
{guidance: true, description: 'Always provide an aria-label that describes what the carousel contains, like "Featured products" or "Team members".'},
{guidance: true, description: 'Carousel implements the WAI-ARIA APG carousel pattern (https://www.w3.org/WAI/ARIA/apg/patterns/carousel/) without auto-rotation: the region is labelled and carries aria-roledescription="carousel", each item is a group named "Slide N of M", and the scroll container is a tab stop so keyboard users can pan it with the arrow keys.'},
{guidance: true, description: 'Carousel implements the WAI-ARIA APG carousel pattern (https://www.w3.org/WAI/ARIA/apg/patterns/carousel/) without auto-rotation: the region is labelled and carries aria-roledescription="carousel", each item is a group named "Slide N of M", and the scroll container is a tab stop while its content overflows, so keyboard users can pan it with the arrow keys; while everything fits it stays out of the tab order.'},
{guidance: true, description: 'Use a consistent gap and item width so the carousel looks intentional, not like content overflowing by accident.'},
{guidance: true, description: 'Trust the built-in navigation: trackpad users can swipe horizontally, and mouse users can hold Shift while scrolling the wheel to move through items.'},
{guidance: false, description: 'Use a carousel for content every user must see. Not everyone scrolls horizontally, so put critical content above the fold.'},
Expand Down
18 changes: 9 additions & 9 deletions packages/core/src/Carousel/Carousel.spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,15 +27,15 @@ system_specs: [spec:AST-085, spec:AST-025]

## Contract at a glance

| Area | Contract |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Public contract | None changes. |
| Behavior | An edge scroll button whose direction has run out is hidden and takes no tab stop. When the focused edge button runs out, focus moves to the scroll area. |
| End-user impact | A keyboard user who scrolls to the first or last item stays inside the carousel instead of landing on the page body or on an invisible control. The scroll area has no role or name yet, so screen-reader users hear little at the destination until it meets `spec:AST-025` FR12. |
| Builder impact | None. |
| Compatibility/readiness | No API change. Shipped Carousel and its current tests still use native `disabled` and hand focus to the opposite button; they change with conformance work. |
| Review checks | Reject focus left on a hidden edge button, focus dropped to the page body, or an edge handoff that moves focus to anything but the scroll area. |
| Governing rules | `spec:AST-085` FR1, FR4; `spec:AST-025` FR12; `architecture:interaction-modality` INV1. |
| Area | Contract |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Public contract | None changes. |
| Behavior | An edge scroll button whose direction has run out is hidden and takes no tab stop. When the focused edge button runs out, focus moves to the scroll area. |
| End-user impact | A keyboard user who scrolls to the first or last item stays inside the carousel instead of landing on the page body or on an invisible control. The scroll area is a group named like the carousel (`spec:AST-025` FR12), so screen-reader users hear where they landed. |
| Builder impact | None. |
| Compatibility/readiness | No API change. Shipped Carousel and its current tests still use native `disabled` and hand focus to the opposite button; they change with conformance work. |
| Review checks | Reject focus left on a hidden edge button, focus dropped to the page body, or an edge handoff that moves focus to anything but the scroll area. |
| Governing rules | `spec:AST-085` FR1, FR4; `spec:AST-025` FR12; `architecture:interaction-modality` INV1. |

This table is a review projection; the body below is authoritative.

Expand Down
127 changes: 124 additions & 3 deletions packages/core/src/Carousel/Carousel.test.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -2,15 +2,18 @@

import {describe, it, expect, vi} from 'vitest';
import {createRef} from 'react';
import {render, screen, fireEvent} from '@testing-library/react';
import {act, render, screen, fireEvent} from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import {Carousel, type CarouselHandle} from './Carousel';

// Mock ResizeObserver (not available in jsdom)
class MockResizeObserver {
/** The shared observer, so a test can deliver a resize. */
static last: MockResizeObserver | null = null;
callback: ResizeObserverCallback;
constructor(callback: ResizeObserverCallback) {
this.callback = callback;
MockResizeObserver.last = this;
}
observe() {}
unobserve() {}
Expand Down Expand Up @@ -43,15 +46,133 @@ describe('Carousel', () => {
</Carousel>,
);
// APG carousel pattern: each slide container is role=group with
// aria-roledescription="slide" and an "N of M" accessible name.
const slides = screen.getAllByRole('group');
// aria-roledescription="slide" and an "N of M" accessible name. (The
// scroll area around them is a group too, named like the carousel.)
const slides = screen.getAllByRole('group', {name: /^Slide /});
expect(slides).toHaveLength(3);
slides.forEach((slide, i) => {
expect(slide).toHaveAttribute('aria-roledescription', 'slide');
expect(slide).toHaveAccessibleName(`Slide ${i + 1} of 3`);
});
});

describe('scroll area (spec:AST-025 FR12)', () => {
function getScroller() {
return screen.getByRole('group', {name: 'Photos'});
}

function setOverflow(el: HTMLElement, overflowing: boolean) {
Object.defineProperty(el, 'scrollWidth', {
value: overflowing ? 500 : 200,
configurable: true,
});
Object.defineProperty(el, 'clientWidth', {
value: 200,
configurable: true,
});
fireEvent.scroll(el);
}

it('is a group named like the carousel', () => {
render(
<Carousel aria-label="Photos">
<div>One</div>
<div>Two</div>
</Carousel>,
);
const scroller = getScroller();
expect(scroller).toHaveAttribute('role', 'group');
expect(scroller).toHaveAccessibleName('Photos');
// It is the region's scroll container, not a slide.
expect(scroller).not.toHaveAttribute('aria-roledescription');
expect(scroller.parentElement).toBe(
screen.getByRole('region', {name: 'Photos'}),
);
});

// Named by its owner (spec:AST-025 FR12): the caller's label above, else
// the carousel's translated default.
it("takes the carousel's translated default name when the caller gives none", () => {
render(
<Carousel>
<div>One</div>
<div>Two</div>
</Carousel>,
);
const scroller = screen.getByRole('group', {name: 'Carousel'});
expect(scroller).toHaveAccessibleName('Carousel');
expect(scroller.parentElement).toBe(
screen.getByRole('region', {name: 'Carousel'}),
);
});

it('takes a tab stop only while its content overflows', () => {
render(
<Carousel aria-label="Photos">
<div>One</div>
<div>Two</div>
</Carousel>,
);
const scroller = getScroller();
// Fitting: out of the tab order, still focusable from script (FR2).
setOverflow(scroller, false);
expect(scroller).toHaveAttribute('tabindex', '-1');
act(() => scroller.focus());
expect(scroller).toHaveFocus();
act(() => scroller.blur());
// Overflowing: a tab stop.
setOverflow(scroller, true);
expect(scroller).toHaveAttribute('tabindex', '0');
// Fitting again: leaves the tab order.
setOverflow(scroller, false);
expect(scroller).toHaveAttribute('tabindex', '-1');
});

// The content can come to overflow, or stop, with the scroll area
// keeping its size: the tab stop follows it.
it('follows its content: slides added or removed, or a slide that grows, move the tab stop', async () => {
const slides = (count: number) =>
Array.from({length: count}, (_, i) => <div key={i}>Slide {i}</div>);
const view = render(<Carousel aria-label="Photos">{slides(1)}</Carousel>);
const scroller = getScroller();
// A 200 px scroll area; 150 px of content per slide, plus what a slide
// grows by.
let grown = 0;
Object.defineProperty(scroller, 'clientWidth', {
value: 200,
configurable: true,
});
Object.defineProperty(scroller, 'scrollWidth', {
configurable: true,
get: () => scroller.children.length * 150 + grown,
});
expect(scroller).toHaveAttribute('tabindex', '-1');

view.rerender(<Carousel aria-label="Photos">{slides(2)}</Carousel>);
await act(async () => {});
expect(scroller).toHaveAttribute('tabindex', '0');

view.rerender(<Carousel aria-label="Photos">{slides(1)}</Carousel>);
await act(async () => {});
expect(scroller).toHaveAttribute('tabindex', '-1');

// The one slide's content grows past the scroll area.
grown = 100;
const observer = MockResizeObserver.last;
act(() => {
observer?.callback(
[
{
target: scroller.firstElementChild,
} as unknown as ResizeObserverEntry,
],
observer,
);
});
expect(scroller).toHaveAttribute('tabindex', '0');
});
});

it('renders children', () => {
render(
<Carousel aria-label="Test carousel">
Expand Down
12 changes: 10 additions & 2 deletions packages/core/src/Carousel/Carousel.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,9 @@
* scroll control. Exposes APG
* carousel semantics: the root is a labelled region with
* aria-roledescription="carousel" and each item wrapper is a group with
* aria-roledescription="slide" named "Slide N of M".
* aria-roledescription="slide" named "Slide N of M". The scroll area is a
* group named like the carousel and a tab stop only while its content
* overflows (AST-025 FR12).
*
* SYNC: When modified, update:
* - /packages/core/src/Carousel/index.ts (exports)
Expand Down Expand Up @@ -591,7 +593,13 @@ export function Carousel({
aria-roledescription="carousel">
<div
ref={composedRef}
tabIndex={0}
// The scroll area takes keyboard scrolling (spec:AST-025 FR12): a
// group named like the carousel, in the tab order only while its
// content overflows. While it fits it still takes focus
// programmatically, for the edge buttons' hand-off (FR2).
role="group"
aria-label={ariaLabel}
tabIndex={hasOverflow ? 0 : -1}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

hasOverflow comes from useScrollOverflow, which re-measures only on this element's own scroll events and own-box resize. Slides appended after mount inside an unchanged box (a one-slide-per-view carousel fed by async data) never flip it: in Chromium, 1280px of content in a 320px area stays at tabindex="-1" with both edge buttons hidden, so Tab skips the carousel and the arrow keys never reach it, where the base kept a reachable stop. spec:AST-025 FR12 requires overflowing content to stay keyboard reachable and leaves geometry to FR5 ("A viewport-only ResizeObserver is insufficient because content may grow while the viewport's own box remains unchanged"). Re-measuring when the slides change (or reading the shared useScrollableArea measurement) while keeping -1 for the fitting case would close it; a test that rerenders with more slides and a wider scrollWidth without firing scroll would pin it.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

hasOverflow comes from useScrollOverflow, which re-measures only on this element's own scroll events and own-box resize. Slides appended after mount inside an unchanged box (a one-slide-per-view carousel fed by async data) never flip it: in Chromium, 1280px of content in a 320px area stays at tabindex="-1" with both edge buttons hidden, so Tab skips the carousel and the arrow keys never reach it, where the base kept a reachable stop. spec:AST-025 FR12 requires overflowing content to stay keyboard reachable and leaves geometry to FR5 ("A viewport-only ResizeObserver is insufficient because content may grow while the viewport's own box remains unchanged"). Re-measuring when the slides change (or reading the shared useScrollableArea measurement), while keeping -1 for the fitting case, would close it; a test that rerenders with more slides and a wider scrollWidth without firing scroll would pin it.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in a2184a1: useScrollOverflow now also observes each slide's box, slides added or removed, and the scroll area's class and style (spec:AST-025 FR5), so slides appended inside an unchanged box make it a tab stop and show the edge buttons, and it stays -1 while everything fits. The new tests add and grow slides without a scroll or resize, and the doc's guidance is updated. Naming follows FR12 as #9088 states it, with a test for the translated default.

onWheel={handleWheel}
{...mergeProps(
themeProps('carousel-scroller', {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -9,19 +9,4 @@

import type {KnownFailure} from '@astryxdesign/a11y-spec';

export const CAROUSEL_KNOWN_FAILURES: ReadonlyArray<KnownFailure> = [
{
expectation: 'carousel.scroller.role-and-name',
binding: 'Carousel',
state: 'scroller-keyboard',
evidenceLayer: 'accessibility-tree',
failureEquals:
'the browser exposes the focusable scroll container with no role',
standardsReference:
'WCAG 2.2 4.1.2 Name, Role, Value; Astryx spec:AST-025 FR12 — a viewport that takes keyboard scrolling must provide an appropriate role and accessible name',
userImpact:
'A keyboard user who tabs onto the scroll container hears nothing about where they are or what the arrow keys will do; the named region around it is the only clue.',
reason:
'This test-only binding records the gap; naming the scroll container is a Carousel markup change that ships as its own spec-backed fix.',
},
];
export const CAROUSEL_KNOWN_FAILURES: ReadonlyArray<KnownFailure> = [];
2 changes: 1 addition & 1 deletion packages/core/src/hooks/useScrollOverflow.doc.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ export const docs = {
],
usage: {
description:
'Tracks scroll overflow state for a horizontally scrollable container. Returns a ref callback and state booleans that update as the user scrolls or the container resizes. Uses scroll event listeners and ResizeObserver for reactive updates. Tolerance of 1px is applied to avoid sub-pixel false positives.',
'Tracks scroll overflow state for a horizontally scrollable container. Returns a ref callback and state booleans that update as the user scrolls, the container resizes, or its content changes (a child added, removed or resized, or a new gap or padding). Uses scroll event listeners, ResizeObserver and MutationObserver for reactive updates. Tolerance of 1px is applied to avoid sub-pixel false positives.',
bestPractices: [
{ guidance: true, description: 'Use to show/hide scroll navigation buttons or fade edges on carousels and horizontal lists.' },
{ guidance: true, description: 'Apply the scrollRef to a container with overflow-x: auto or overflow-x: scroll.' },
Expand Down
Loading
Loading