An open source design system that's fully customizable and agent ready
TypeScript
fix(Carousel): a run-out edge button hands focus to the scroll area (#7926)
Cindy Zhang13df1cecf72a
diff --git a/.changeset/carousel-edge-focus-scroll-area.md b/.changeset/carousel-edge-focus-scroll-area.mdnew file mode 100644index 0000000000..299e81f46b--- /dev/null+++ b/.changeset/carousel-edge-focus-scroll-area.md@@ -0,0 +1,7 @@+---+'@astryxdesign/core': patch+---++[fix] Carousel: when the focused edge scroll button runs out (the carousel reached that edge), focus now moves to the scroll area without scrolling it, instead of to the opposite scroll button. This follows the Carousel record (`component:Carousel` FR2) and spec:AST-085 FR4. No API changes.++@cixzhangdiff --git a/packages/core/src/Carousel/Carousel.test.tsx b/packages/core/src/Carousel/Carousel.test.tsxindex a0be9fbceb..f2cfb100c0 100644--- a/packages/core/src/Carousel/Carousel.test.tsx+++ b/packages/core/src/Carousel/Carousel.test.tsx@@ -519,7 +519,7 @@ describe('Carousel', () => {fireEvent.scroll(el);}- it('hands focus to the opposite button when the edge disables the one in use', async () => {+ it('hands focus to the scroll area when the edge disables the one in use', async () => {const user = userEvent.setup();render(<Carousel aria-label="Gallery">@@ -536,7 +536,7 @@ describe('Carousel', () => {await user.click(next);expect(next).toBeDisabled();- expect(document.activeElement).toBe(screen.getByLabelText('Scroll left'));+ expect(document.activeElement).toBe(getScroller());expect(document.activeElement).not.toBe(document.body);});@@ -559,9 +559,7 @@ describe('Carousel', () => {await user.click(previous);expect(previous).toBeDisabled();- expect(document.activeElement).toBe(- screen.getByLabelText('Scroll right'),- );+ expect(document.activeElement).toBe(getScroller());});it('hands off under RTL, where the scroll axis is inverted', async () => {@@ -605,7 +603,7 @@ describe('Carousel', () => {await user.click(next);expect(next).toBeDisabled();- expect(document.activeElement).toBe(screen.getByLabelText('Scroll left'));+ expect(document.activeElement).toBe(getScroller());});it('hands off when scroll-snap carries the container past what the press asked for', async () => {@@ -626,7 +624,7 @@ describe('Carousel', () => {await user.click(next);expect(next).toBeDisabled();- expect(document.activeElement).toBe(screen.getByLabelText('Scroll left'));+ expect(document.activeElement).toBe(getScroller());});it('falls back to the scroll container when the carousel stops overflowing', async () => {@@ -701,7 +699,7 @@ describe('Carousel', () => {// rather than loosening the guard -- is caught.await user.click(screen.getByLabelText('Scroll right'));- expect(document.activeElement).toBe(screen.getByLabelText('Scroll left'));+ expect(document.activeElement).toBe(getScroller());});it('does not move focus on a press that leaves the direction available', async () => {@@ -748,8 +746,7 @@ describe('Carousel', () => {</Carousel>,);makeScrollable(getScroller(), 400);- const previous = screen.getByLabelText('Scroll left');- const focus = vi.spyOn(previous, 'focus');+ const focus = vi.spyOn(getScroller(), 'focus');await user.click(screen.getByLabelText('Scroll right'));@@ -789,8 +786,7 @@ describe('Carousel', () => {makeScrollable(getScroller(), 400);await user.click(screen.getByLabelText('Scroll right'));- const previous = screen.getByLabelText('Scroll left');- expect(document.activeElement).toBe(previous);+ expect(document.activeElement).toBe(getScroller());// Park focus outside and re-render: the transition is spent, so nothing// may pull focus back in.const outside = document.createElement('button');diff --git a/packages/core/src/Carousel/Carousel.tsx b/packages/core/src/Carousel/Carousel.tsxindex fe69f019cf..f41bc90f01 100644--- a/packages/core/src/Carousel/Carousel.tsx+++ b/packages/core/src/Carousel/Carousel.tsx@@ -504,9 +504,7 @@ export function Carousel({// the scroll, the position before it plus the step, and the settled position// reported by `scrollend` -- were each wrong somewhere, under reduced motion,// under mandatory scroll-snap, and on a browser that never fires the event.- // Running after the commit also makes the opposite button a valid receiver,- // which it is not during the press: at that moment it is still disabled and- // focus() on a disabled control does nothing. Ruled acceptable by the+ // Ruled acceptable by the// maintainer, 2026-08-27, on the conditions encoded below: it acts only on// the transition that newly disables the focused button, it moves focus and// nothing else, and it cannot fire twice for one transition.@@ -543,21 +541,16 @@ export function Carousel({return;}- const opposite =- side === 'start' ? endButtonRef.current : startButtonRef.current;- // The opposite button is the receiver. It is disabled only when the- // carousel stopped overflowing entirely, which happens when its content- // shrinks; the scroll container is then the nearest tab stop still inside- // the labelled region.- const receiver =- opposite != null && !opposite.disabled ? opposite : scrollElRef.current;+ // The scroll area is the receiver (component:Carousel FR2). It takes focus+ // programmatically even when it is out of the tab order.+ const receiver = scrollElRef.current;if (receiver == null) {return;}// One move per transition: clearing the tracker first means a re-render or// a StrictMode double-invoke re-runs this and returns at the `side == null`- // guard above. Focusing the receiver sets it again, to the other side.+ // guard above.focusedNavRef.current = null;// preventScroll: a plain focus() scrolls its element into view, which on// the scroll container cancels the scroll the press just started.@@ -661,7 +654,7 @@ export function Carousel({// button mounted (stable layout) 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. The Effect above- // hands focus to the other button when the state behind this+ // hands focus to the scroll area when the state behind this// one flips it disabled.isDisabled={!canScrollStart}onFocus={() => {