Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(core): expose APG slide semantics on Carousel items (#4004)

Baraa Hamodid83c4ca68666
diff --git a/.changeset/carousel-slide-semantics.md b/.changeset/carousel-slide-semantics.md
new file mode 100644
index 0000000000..0f6b290c86
--- /dev/null
+++ b/.changeset/carousel-slide-semantics.md
@@ -0,0 +1,6 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] Carousel: slides now expose APG slide semantics (role=group, aria-roledescription="slide", "Slide N of M" labels) instead of anonymous divs.
+@bhamodi
diff --git a/packages/core/locales/en.json b/packages/core/locales/en.json
index 65c7d25e01..1141104369 100644
--- a/packages/core/locales/en.json
+++ b/packages/core/locales/en.json
@@ -263,6 +263,10 @@
"defaultMessage": "Scroll right",
"description": "Screen-reader-only label on the right arrow button in a Carousel. Pairs with `carousel.scrollLeft`; same RTL note."
},
+ "@astryx.carousel.slideLabel": {
+ "defaultMessage": "Slide {current, number} of {total, number}",
+ "description": "Screen-reader accessible name for one slide in a Carousel, giving its position. `current` is the 1-based slide number; `total` is the slide count."
+ },
"@astryx.chat.status.sending": {
"defaultMessage": "Sending",
"description": "Chat send-status caption under an outgoing message while it is being transmitted. Part of the set sending → sent → delivered → read (or failed) — keep tense/aspect consistent."
diff --git a/packages/core/src/Carousel/Carousel.test.tsx b/packages/core/src/Carousel/Carousel.test.tsx
index 1a01b43d92..e4fe08680c 100644
--- a/packages/core/src/Carousel/Carousel.test.tsx
+++ b/packages/core/src/Carousel/Carousel.test.tsx
@@ -92,6 +92,59 @@ describe('Carousel', () => {
expect(screen.getByLabelText('Scroll right')).toBeInTheDocument();
});
+ describe('slide semantics', () => {
+ it('exposes each slide as a group with aria-roledescription="slide" and a positional name', () => {
+ render(
+ <Carousel aria-label="Photos">
+ <div>One</div>
+ <div>Two</div>
+ <div>Three</div>
+ </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');
+ expect(slides).toHaveLength(3);
+ slides.forEach((slide, i) => {
+ expect(slide).toHaveAttribute('aria-roledescription', 'slide');
+ expect(slide).toHaveAccessibleName(`Slide ${i + 1} of 3`);
+ });
+ });
+
+ it('reflects the rendered child count, skipping null and boolean children', () => {
+ render(
+ <Carousel aria-label="Photos">
+ <div>One</div>
+ {null}
+ {false}
+ <div>Two</div>
+ </Carousel>,
+ );
+ const slides = screen.getAllByRole('group');
+ expect(slides).toHaveLength(2);
+ expect(
+ screen.getByRole('group', {name: 'Slide 1 of 2'}),
+ ).toBeInTheDocument();
+ expect(
+ screen.getByRole('group', {name: 'Slide 2 of 2'}),
+ ).toBeInTheDocument();
+ });
+
+ it('keeps the container region semantics unchanged around labelled slides', () => {
+ render(
+ <Carousel aria-label="Gallery">
+ <div>One</div>
+ <div>Two</div>
+ </Carousel>,
+ );
+ const region = screen.getByRole('region', {name: 'Gallery'});
+ expect(region).toHaveAttribute('aria-roledescription', 'carousel');
+ const slides = screen.getAllByRole('group');
+ expect(slides).toHaveLength(2);
+ slides.forEach(slide => expect(region).toContainElement(slide));
+ });
+ });
+
it('disables edge scroll buttons instead of removing them from the tab order', () => {
// In jsdom there is no measurable overflow, so both edges are at rest and
// the scroll buttons are in their hidden/inert state. They must stay
diff --git a/packages/core/src/Carousel/Carousel.tsx b/packages/core/src/Carousel/Carousel.tsx
index 6f2de18f9a..dcc1d377a0 100644
--- a/packages/core/src/Carousel/Carousel.tsx
+++ b/packages/core/src/Carousel/Carousel.tsx
@@ -9,7 +9,10 @@
* @position Horizontal scroll container with fade-edge overflow indication,
* optional prev/next buttons on the top layer, scroll-snap, a 1px
* visual bleed allowance for child selection indicators, and Shift + wheel
- * mapping so mouse users can scroll horizontally.
+ * mapping so mouse users can scroll horizontally. 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".
*
* SYNC: When modified, update:
* - /packages/core/src/Carousel/index.ts (exports)
@@ -17,7 +20,14 @@
* - /packages/cli/templates/blocks/components/Carousel/ (showcase blocks)
*/
-import {type ReactNode, useRef, useCallback, useEffect, Children} from 'react';
+import {
+ type ReactNode,
+ useRef,
+ useCallback,
+ useEffect,
+ Children,
+ isValidElement,
+} from 'react';
import * as stylex from '@stylexjs/stylex';
import {
spacingVars,
@@ -270,6 +280,11 @@ export function Carousel({
const scrollElRef = useRef<HTMLElement | null>(null);
const {scrollRef, overflowStart, overflowEnd} = useScrollOverflow();
+ // Children.toArray drops null/undefined/boolean children and assigns
+ // stable keys, so slide numbering ("Slide N of M") matches what actually
+ // renders even when some children are conditionally omitted.
+ const slides = Children.toArray(children);
+
const layer = useLayer({
mode: 'context',
lightDismiss: false,
@@ -380,8 +395,23 @@ export function Carousel({
hasSnap && styles.snap,
fadeStyle,
)}>
- {Children.map(children, child => (
- <div {...stylex.props(styles.item)}>{child}</div>
+ {slides.map((child, index) => (
+ // APG carousel pattern: each slide container is a group with
+ // aria-roledescription="slide" and an "N of M" accessible name so
+ // ATs announce slide boundaries and position instead of anonymous
+ // generics.
+ <div
+ // eslint-disable-next-line @eslint-react/no-array-index-key -- index fallback only applies to text/number children, which are positional by definition; elements keep their Children.toArray keys
+ key={isValidElement(child) ? child.key : index}
+ role="group"
+ aria-roledescription="slide"
+ aria-label={t('@astryx.carousel.slideLabel', {
+ current: index + 1,
+ total: slides.length,
+ })}
+ {...stylex.props(styles.item)}>
+ {child}
+ </div>
))}
</div>