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.mdnew file mode 100644index 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)+@cixzhangdiff --git a/packages/core/src/Carousel/Carousel.test.tsx b/packages/core/src/Carousel/Carousel.test.tsxindex 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.tsxindex 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.tsxindex 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(<LightboxisOpen={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(<LightboxisOpen={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.tsxindex 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)}><IconButtonicon={<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)}><IconButtonicon={<Icon icon="chevronRight" size="sm" color="inherit" />}label="Next"variant="ghost"+ isDisabled={!canNext}onClick={goToNext}xstyle={styles.controlButton}/>