Skip to content

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

TypeScript

fix(carousel,lightbox): keep edge controls focusable-stable, respect reduced motion (complex-9/10/11/13) (#3395)

Cindy Zhang67a970fdda90
diff --git a/.changeset/carousel-lightbox-focus.md b/.changeset/carousel-lightbox-focus.md
new file mode 100644
index 0000000000..5195f59fb1
--- /dev/null
+++ b/.changeset/carousel-lightbox-focus.md
@@ -0,0 +1,6 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] Carousel, Lightbox: keyboard focus is no longer trapped on invisible or unmounted edge controls. Carousel's scroll left/right buttons, when at an exhausted edge (or when there is no overflow), were hidden with `opacity: 0`/`pointer-events: none` but stayed in the tab order, so keyboard users could focus invisible controls (WCAG 2.4.7); they are now `disabled` in that state (still mounted, removed from the tab order and a11y tree). Button-driven scrolling also now respects `prefers-reduced-motion` (uses `behavior: 'auto'` instead of hardcoded `'smooth'`). In Lightbox gallery mode, the Prev/Next buttons previously unmounted at the range ends, so advancing onto the first/last item removed the focused control and dropped focus to `<body>`, dead-ending keyboard navigation; they now stay mounted and become `disabled` at the boundaries so focus stays within the dialog and arrow-key navigation keeps working (#3343)
+@cixzhang
diff --git a/packages/core/src/Carousel/Carousel.test.tsx b/packages/core/src/Carousel/Carousel.test.tsx
index 9977e3b6a8..44b28b7ad1 100644
--- a/packages/core/src/Carousel/Carousel.test.tsx
+++ b/packages/core/src/Carousel/Carousel.test.tsx
@@ -78,4 +78,24 @@ describe('Carousel', () => {
expect(screen.getByLabelText('Scroll left')).toBeInTheDocument();
expect(screen.getByLabelText('Scroll right')).toBeInTheDocument();
});
+
+ 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
+ // mounted but be disabled — a disabled <button> is skipped by the tab
+ // order and hidden from the a11y tree, so keyboard users don't focus an
+ // invisible control (WCAG 2.4.7).
+ render(
+ <Carousel aria-label="Edge state">
+ <div>Item 1</div>
+ <div>Item 2</div>
+ </Carousel>,
+ );
+ const left = screen.getByLabelText('Scroll left');
+ const right = screen.getByLabelText('Scroll right');
+ expect(left).toBeInTheDocument();
+ expect(right).toBeInTheDocument();
+ expect(left).toBeDisabled();
+ expect(right).toBeDisabled();
+ });
});
diff --git a/packages/core/src/Carousel/Carousel.tsx b/packages/core/src/Carousel/Carousel.tsx
index db330d16dc..8fbd8c67d2 100644
--- a/packages/core/src/Carousel/Carousel.tsx
+++ b/packages/core/src/Carousel/Carousel.tsx
@@ -295,9 +295,16 @@ export function Carousel({
const firstChild = el.firstElementChild as HTMLElement | null;
const itemWidth = firstChild ? firstChild.offsetWidth : 0;
const amount = el.clientWidth - itemWidth * 0.5;
+ // Respect the user's reduced-motion preference — mirrors the CSS
+ // scroll-behavior override so button-driven scrolling doesn't animate
+ // for users who opted out of motion.
+ const prefersReducedMotion =
+ typeof window !== 'undefined' &&
+ typeof window.matchMedia === 'function' &&
+ window.matchMedia('(prefers-reduced-motion: reduce)').matches;
el.scrollBy({
left: direction * Math.max(amount, itemWidth),
- behavior: 'smooth',
+ behavior: prefersReducedMotion ? 'auto' : 'smooth',
});
}, []);
@@ -360,6 +367,11 @@ export function Carousel({
variant="ghost"
size="sm"
isIconOnly
+ // Disabled when there's nothing to scroll toward. Keeps the
+ // button mounted (stable layout/focus) but removes it from the
+ // tab order and a11y tree while it's visually hidden, so
+ // keyboard users don't land on an invisible control.
+ isDisabled={!overflowStart}
onClick={() => scrollBy(-1)}
xstyle={styles.buttonRadiusOverride}
/>
@@ -376,6 +388,9 @@ export function Carousel({
variant="ghost"
size="sm"
isIconOnly
+ // See "Scroll left" — disabled while visually hidden so the
+ // button stays mounted but out of the tab order / a11y tree.
+ isDisabled={!overflowEnd}
onClick={() => scrollBy(1)}
xstyle={styles.buttonRadiusOverride}
/>
diff --git a/packages/core/src/Lightbox/Lightbox.test.tsx b/packages/core/src/Lightbox/Lightbox.test.tsx
index 690409169f..1e015f32f8 100644
--- a/packages/core/src/Lightbox/Lightbox.test.tsx
+++ b/packages/core/src/Lightbox/Lightbox.test.tsx
@@ -177,7 +177,7 @@ describe('Lightbox', () => {
expect(screen.getByLabelText('Next')).toBeInTheDocument();
});
- it('hides prev button on first item', () => {
+ it('keeps prev mounted and disabled on first item', () => {
render(
<Lightbox
isOpen={true}
@@ -186,11 +186,16 @@ describe('Lightbox', () => {
index={0}
/>,
);
- expect(screen.queryByLabelText('Previous')).not.toBeInTheDocument();
- expect(screen.getByLabelText('Next')).toBeInTheDocument();
+ // The Prev button stays mounted at the range boundary (disabled) rather
+ // than unmounting, so navigating to the first item never removes the
+ // focused control and drops focus to <body>.
+ const prev = screen.getByLabelText('Previous');
+ expect(prev).toBeInTheDocument();
+ expect(prev).toBeDisabled();
+ expect(screen.getByLabelText('Next')).not.toBeDisabled();
});
- it('hides next button on last item', () => {
+ it('keeps next mounted and disabled on last item', () => {
render(
<Lightbox
isOpen={true}
@@ -199,8 +204,51 @@ describe('Lightbox', () => {
index={2}
/>,
);
+ const next = screen.getByLabelText('Next');
+ expect(next).toBeInTheDocument();
+ expect(next).toBeDisabled();
+ expect(screen.getByLabelText('Previous')).not.toBeDisabled();
+ });
+
+ it('does not drop focus to <body> when navigating to the last item', () => {
+ const {rerender} = render(
+ <Lightbox
+ isOpen={true}
+ onOpenChange={() => {}}
+ media={media}
+ index={1}
+ />,
+ );
+ // Simulate arriving at the final item (Next becomes disabled).
+ rerender(
+ <Lightbox
+ isOpen={true}
+ onOpenChange={() => {}}
+ media={media}
+ index={2}
+ />,
+ );
+ // Both nav buttons remain in the DOM; the dialog stays available so
+ // keyboard gallery navigation isn't dead-ended.
expect(screen.getByLabelText('Previous')).toBeInTheDocument();
- expect(screen.queryByLabelText('Next')).not.toBeInTheDocument();
+ expect(screen.getByLabelText('Next')).toBeInTheDocument();
+ const dialog = document.querySelector('dialog');
+ expect(dialog).toBeInTheDocument();
+ // Arrow handling is on the dialog, so navigation still works at the edge.
+ const onIndexChange = vi.fn();
+ rerender(
+ <Lightbox
+ isOpen={true}
+ onOpenChange={() => {}}
+ media={media}
+ index={2}
+ onIndexChange={onIndexChange}
+ />,
+ );
+ if (dialog instanceof HTMLElement) {
+ fireEvent.keyDown(dialog, {key: 'ArrowLeft'});
+ }
+ expect(onIndexChange).toHaveBeenCalledWith(1);
});
it('calls onIndexChange when next is clicked', () => {
diff --git a/packages/core/src/Lightbox/Lightbox.tsx b/packages/core/src/Lightbox/Lightbox.tsx
index 6fba9a51e8..ca75a2fd50 100644
--- a/packages/core/src/Lightbox/Lightbox.tsx
+++ b/packages/core/src/Lightbox/Lightbox.tsx
@@ -496,13 +496,16 @@ export function Lightbox({
/>
</div>
- {/* Gallery nav: prev */}
- {isGallery && canPrev && (
+ {/* Gallery nav: prev — stays mounted and is disabled at the start of
+ the range so pressing/arrowing to the boundary doesn't unmount the
+ focused control and drop focus to <body>. */}
+ {isGallery && (
<div {...stylex.props(styles.navButton, styles.navPrev)}>
<IconButton
icon={<Icon icon="chevronLeft" size="sm" color="inherit" />}
label="Previous"
variant="ghost"
+ isDisabled={!canPrev}
onClick={goToPrev}
xstyle={styles.controlButton}
/>
@@ -549,13 +552,15 @@ export function Lightbox({
)}
</div>
- {/* Gallery nav: next */}
- {isGallery && canNext && (
+ {/* Gallery nav: next — see "prev" above; stays mounted and disabled at
+ the end of the range instead of unmounting. */}
+ {isGallery && (
<div {...stylex.props(styles.navButton, styles.navNext)}>
<IconButton
icon={<Icon icon="chevronRight" size="sm" color="inherit" />}
label="Next"
variant="ghost"
+ isDisabled={!canNext}
onClick={goToNext}
xstyle={styles.controlButton}
/>