An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
import {describe, it, expect, vi} from 'vitest';
import {createRef, useEffect, useRef} from 'react';
import {act, render, screen, fireEvent} from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import {Carousel, type CarouselHandle} from './Carousel';
import {
makeSnapPaging,
type HeldRowListener,
} from '../SnapPaging/snapPagingValue';
// 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() {}
disconnect() {}
}
vi.stubGlobal('ResizeObserver', MockResizeObserver);
describe('Carousel', () => {
// Retained local tests (AST-021 FR6): the carousel contract keeps the
// aria-roledescription outcomes ADVISORY until a current Carousel record
// adopts the APG parts, so these component assertions remain the gate for
// the slide and region role descriptions. Removal blocker: component:Carousel
// adopting APG Carousel's aria-roledescription as current.
it('has carousel ARIA attributes', () => {
render(
<Carousel aria-label="Photos">
<div>Item</div>
</Carousel>,
);
const region = screen.getByRole('region', {name: 'Photos'});
expect(region).toHaveAttribute('aria-roledescription', 'carousel');
});
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. (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">
<div data-testid="item-1">Item 1</div>
<div data-testid="item-2">Item 2</div>
</Carousel>,
);
expect(screen.getByTestId('item-1')).toBeInTheDocument();
expect(screen.getByTestId('item-2')).toBeInTheDocument();
});
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>,
);
expect(
screen.getByRole('group', {name: 'Slide 1 of 2'}),
).toBeInTheDocument();
expect(
screen.getByRole('group', {name: 'Slide 2 of 2'}),
).toBeInTheDocument();
// Exactly two slides render: null and false children produce no empty
// slide (child filtering stays component-owned). The scroller is a named
// group too, so count the slides by their role description.
expect(
screen
.getAllByRole('group')
.filter(
group => group.getAttribute('aria-roledescription') === 'slide',
),
).toHaveLength(2);
});
it('applies data-testid', () => {
render(
<Carousel data-testid="my-carousel">
<div>Item</div>
</Carousel>,
);
expect(screen.getByTestId('my-carousel')).toBeInTheDocument();
});
it('has correct astryx class name', () => {
render(
<Carousel data-testid="cls-test">
<div>Item</div>
</Carousel>,
);
const el = screen.getByTestId('cls-test');
expect(el.className).toContain('astryx-carousel');
});
it('does not render button layer when hasButtons={false}', () => {
render(
<Carousel hasButtons={false} aria-label="No buttons">
<div>Item 1</div>
<div>Item 2</div>
</Carousel>,
);
expect(screen.queryByLabelText('Scroll left')).not.toBeInTheDocument();
expect(screen.queryByLabelText('Scroll right')).not.toBeInTheDocument();
});
it('renders buttons by default', () => {
render(
<Carousel aria-label="With buttons">
<div>Item 1</div>
<div>Item 2</div>
</Carousel>,
);
expect(screen.getByLabelText('Scroll left')).toBeInTheDocument();
expect(screen.getByLabelText('Scroll right')).toBeInTheDocument();
});
it('unmounts while the paging holds the row, with no flushSync in the commit', () => {
const error = vi.spyOn(console, 'error').mockImplementation(() => {});
let report: HeldRowListener | undefined;
// A stand-in paging: it reports a held row, and hands the row back as it
// detaches, as the pager does.
const paging = makeSnapPaging((_element, onHeld) => {
report = onHeld;
return {
detach: () => {
onHeld?.({offset: 0, travel: 400});
onHeld?.(null);
},
move: () => {},
moveHeld: () => false,
};
});
const view = render(
<Carousel aria-label="Held" hasSnap={paging}>
<div>Item 1</div>
<div>Item 2</div>
</Carousel>,
);
act(() => report?.({offset: 150, travel: 400}));
expect(screen.getByLabelText('Scroll left')).not.toHaveAttribute(
'aria-disabled',
'true',
);
// The detach runs in an effect cleanup, inside React's commit.
view.unmount();
expect(error).not.toHaveBeenCalled();
error.mockRestore();
});
it('scrolls from an Effect after a slide is added, with no flushSync in the commit', () => {
const error = vi.spyOn(console, 'error').mockImplementation(() => {});
// A stand-in paging: a move takes the row over and reports it at once,
// as the pager does.
const paging = makeSnapPaging((_element, onHeld) => ({
detach: () => {},
move: () => {
onHeld?.({offset: 150, travel: 400});
},
moveHeld: () => false,
}));
function Grows({count}: {count: number}) {
const ref = useRef<CarouselHandle>(null);
useEffect(() => {
if (count > 2) {
ref.current?.scrollNext();
}
}, [count]);
return (
<Carousel handleRef={ref} aria-label="Grows" hasSnap={paging}>
{Array.from({length: count}, (_, i) => (
<div key={i}>Item {i + 1}</div>
))}
</Carousel>
);
}
const view = render(<Grows count={2} />);
view.rerender(<Grows count={3} />);
expect(screen.getByLabelText('Scroll left')).not.toHaveAttribute(
'aria-disabled',
'true',
);
expect(error).not.toHaveBeenCalled();
error.mockRestore();
});
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).toHaveAttribute('aria-disabled', 'true');
expect(right).toHaveAttribute('aria-disabled', 'true');
// Disabled buttons stay focusable (spec:AST-085 FR1), so the hidden pill
// around each is inert: an invisible button is never a Tab stop.
expect(left.closest('[inert]')).not.toBeNull();
expect(right.closest('[inert]')).not.toBeNull();
});
describe('Shift + wheel horizontal scroll', () => {
// jsdom doesn't lay out elements, so we fake an overflowing scroll
// container and capture scrollBy calls.
function getScroller() {
const region = screen.getByRole('region');
return region.firstElementChild as HTMLElement;
}
function makeOverflowing(el: HTMLElement) {
Object.defineProperty(el, 'scrollWidth', {
value: 500,
configurable: true,
});
Object.defineProperty(el, 'clientWidth', {
value: 200,
configurable: true,
});
}
it('maps Shift + vertical wheel to horizontal scroll', () => {
render(
<Carousel aria-label="Wheel">
<div>Item 1</div>
<div>Item 2</div>
</Carousel>,
);
const scroller = getScroller();
makeOverflowing(scroller);
// The row measures its overflow again on a scroll.
fireEvent.scroll(scroller);
const scrollBy = vi.fn();
scroller.scrollBy = scrollBy;
fireEvent.wheel(scroller, {shiftKey: true, deltaY: 120, deltaX: 0});
expect(scrollBy).toHaveBeenCalledWith({left: 120, behavior: 'auto'});
});
it("stops the browser's own scroll, so a notch scrolls the row once", () => {
render(
<Carousel aria-label="Wheel">
<div>Item 1</div>
<div>Item 2</div>
</Carousel>,
);
const scroller = getScroller();
makeOverflowing(scroller);
// The row measures its overflow again on a scroll.
fireEvent.scroll(scroller);
scroller.scrollBy = vi.fn();
// A listener that called preventDefault() makes dispatch return false.
expect(
fireEvent.wheel(scroller, {shiftKey: true, deltaY: 120, deltaX: 0}),
).toBe(false);
});
it('does not translate wheel without Shift held', () => {
render(
<Carousel aria-label="Wheel">
<div>Item 1</div>
<div>Item 2</div>
</Carousel>,
);
const scroller = getScroller();
makeOverflowing(scroller);
// The row measures its overflow again on a scroll.
fireEvent.scroll(scroller);
const scrollBy = vi.fn();
scroller.scrollBy = scrollBy;
fireEvent.wheel(scroller, {shiftKey: false, deltaY: 120, deltaX: 0});
expect(scrollBy).not.toHaveBeenCalled();
});
it('leaves native horizontal wheel deltas alone', () => {
// Trackpads emit deltaX directly — don't double-handle those.
render(
<Carousel aria-label="Wheel">
<div>Item 1</div>
<div>Item 2</div>
</Carousel>,
);
const scroller = getScroller();
makeOverflowing(scroller);
// The row measures its overflow again on a scroll.
fireEvent.scroll(scroller);
const scrollBy = vi.fn();
scroller.scrollBy = scrollBy;
fireEvent.wheel(scroller, {shiftKey: true, deltaY: 120, deltaX: 40});
expect(scrollBy).not.toHaveBeenCalled();
});
it('reads no style or layout on a wheel over the row, with Shift or without', () => {
render(
<Carousel aria-label="Wheel">
<div>Item 1</div>
<div>Item 2</div>
</Carousel>,
);
const scroller = getScroller();
let reads = 0;
for (const [name, value] of [
['scrollWidth', 500],
['clientWidth', 200],
] as const) {
Object.defineProperty(scroller, name, {
configurable: true,
get: () => {
reads += 1;
return value;
},
});
}
fireEvent.scroll(scroller);
scroller.scrollBy = vi.fn();
reads = 0;
const style = vi.spyOn(window, 'getComputedStyle');
fireEvent.wheel(scroller, {deltaY: 120});
fireEvent.wheel(scroller, {shiftKey: true, deltaY: 120});
const styles = style.mock.calls.length;
style.mockRestore();
expect({reads, styles}).toEqual({reads: 0, styles: 0});
expect(scroller.scrollBy).toHaveBeenCalledTimes(1);
});
it('adds no wheel listener to a row with nothing to scroll', () => {
const addEventListener = vi.spyOn(
HTMLElement.prototype,
'addEventListener',
);
render(
<Carousel aria-label="Wheel">
<div>Item 1</div>
</Carousel>,
);
const scroller = getScroller();
const wheels = addEventListener.mock.contexts.filter(
(element, call) =>
element === scroller &&
addEventListener.mock.calls[call][0] === 'wheel',
);
addEventListener.mockRestore();
expect(wheels).toHaveLength(0);
});
it('does not intercept when there is no horizontal overflow', () => {
render(
<Carousel aria-label="Wheel">
<div>Item 1</div>
</Carousel>,
);
const scroller = getScroller();
Object.defineProperty(scroller, 'scrollWidth', {
value: 200,
configurable: true,
});
Object.defineProperty(scroller, 'clientWidth', {
value: 200,
configurable: true,
});
const scrollBy = vi.fn();
scroller.scrollBy = scrollBy;
fireEvent.wheel(scroller, {shiftKey: true, deltaY: 120, deltaX: 0});
expect(scrollBy).not.toHaveBeenCalled();
});
});
describe('hasLoop', () => {
// jsdom doesn't lay out elements, so we fake an overflowing scroll
// container, force it to rest at an edge, and capture scrollBy calls.
function getScroller() {
const region = screen.getByRole('region');
return region.firstElementChild as HTMLElement;
}
function makeOverflowing(el: HTMLElement, scrollLeft: number) {
Object.defineProperty(el, 'scrollWidth', {
value: 500,
configurable: true,
});
Object.defineProperty(el, 'clientWidth', {
value: 200,
configurable: true,
});
Object.defineProperty(el, 'scrollLeft', {
value: scrollLeft,
writable: true,
configurable: true,
});
// Drive the overflow hook's scroll listener so overflowStart/End settle.
fireEvent.scroll(el);
}
it('keeps both navigation buttons enabled at the edges when looping', () => {
render(
<Carousel hasLoop aria-label="Looping">
<div>Item 1</div>
<div>Item 2</div>
</Carousel>,
);
const scroller = getScroller();
// At the start edge: without loop the left button would be disabled.
makeOverflowing(scroller, 0);
expect(screen.getByLabelText('Scroll left')).not.toHaveAttribute(
'aria-disabled',
);
expect(screen.getByLabelText('Scroll right')).not.toHaveAttribute(
'aria-disabled',
);
});
it('wraps to the start when pressing next at the end', () => {
render(
<Carousel hasLoop aria-label="Looping">
<div>Item 1</div>
<div>Item 2</div>
</Carousel>,
);
const scroller = getScroller();
// At the end edge (scrolled fully right): overflowEnd is false.
makeOverflowing(scroller, 300);
const scrollBy = vi.fn();
scroller.scrollBy = scrollBy;
fireEvent.click(screen.getByLabelText('Scroll right'));
// Overshoots toward the start by the full scroll width; the browser
// clamps to scrollLeft 0.
expect(scrollBy).toHaveBeenCalledWith({
left: -500,
behavior: 'smooth',
});
});
it('wraps to the end when pressing prev at the start', () => {
render(
<Carousel hasLoop aria-label="Looping">
<div>Item 1</div>
<div>Item 2</div>
</Carousel>,
);
const scroller = getScroller();
makeOverflowing(scroller, 0);
const scrollBy = vi.fn();
scroller.scrollBy = scrollBy;
fireEvent.click(screen.getByLabelText('Scroll left'));
// Overshoots toward the end by the full scroll width.
expect(scrollBy).toHaveBeenCalledWith({
left: 500,
behavior: 'smooth',
});
});
it('does not wrap when content fits without overflowing', () => {
render(
<Carousel hasLoop aria-label="Looping">
<div>Only item</div>
</Carousel>,
);
const scroller = getScroller();
Object.defineProperty(scroller, 'scrollWidth', {
value: 200,
configurable: true,
});
Object.defineProperty(scroller, 'clientWidth', {
value: 200,
configurable: true,
});
Object.defineProperty(scroller, 'scrollLeft', {
value: 0,
writable: true,
configurable: true,
});
fireEvent.scroll(scroller);
const scrollBy = vi.fn();
scroller.scrollBy = scrollBy;
// Buttons are hidden/disabled with no overflow; invoking scroll is a
// no-op wrap-wise — a normal (non-wrap) scrollBy still runs, but there
// is nothing to wrap to, so the overshoot branch must not fire.
fireEvent.click(screen.getByLabelText('Scroll right'));
// Either not called (button disabled) or called with a normal delta —
// never the full-scrollWidth overshoot.
if (scrollBy.mock.calls.length > 0) {
expect(scrollBy).not.toHaveBeenCalledWith(
expect.objectContaining({left: 500}),
);
expect(scrollBy).not.toHaveBeenCalledWith(
expect.objectContaining({left: -500}),
);
}
});
});
describe('handleRef', () => {
function getScroller() {
const region = screen.getByRole('region');
return region.firstElementChild as HTMLElement;
}
function makeOverflowing(el: HTMLElement, scrollLeft: number) {
Object.defineProperty(el, 'scrollWidth', {
value: 500,
configurable: true,
});
Object.defineProperty(el, 'clientWidth', {
value: 200,
configurable: true,
});
Object.defineProperty(el, 'scrollLeft', {
value: scrollLeft,
writable: true,
configurable: true,
});
fireEvent.scroll(el);
}
it('exposes scrollNext/scrollPrev that drive the scroll container', () => {
const handle = createRef<CarouselHandle>();
render(
<Carousel handleRef={handle} aria-label="Handle">
<div>Item 1</div>
<div>Item 2</div>
</Carousel>,
);
const scroller = getScroller();
makeOverflowing(scroller, 100);
const scrollBy = vi.fn();
scroller.scrollBy = scrollBy;
handle.current?.scrollNext();
expect(scrollBy).toHaveBeenCalledTimes(1);
expect(scrollBy.mock.calls[0][0].left).toBeGreaterThan(0);
handle.current?.scrollPrev();
expect(scrollBy).toHaveBeenCalledTimes(2);
expect(scrollBy.mock.calls[1][0].left).toBeLessThan(0);
});
it('reports canScrollNext/canScrollPrev from live overflow state', () => {
const handle = createRef<CarouselHandle>();
render(
<Carousel handleRef={handle} aria-label="Handle">
<div>Item 1</div>
<div>Item 2</div>
</Carousel>,
);
const scroller = getScroller();
// At the start: can scroll toward the end, not the start.
makeOverflowing(scroller, 0);
expect(handle.current?.canScrollPrev()).toBe(false);
expect(handle.current?.canScrollNext()).toBe(true);
// Scroll into the middle: both directions available.
makeOverflowing(scroller, 150);
expect(handle.current?.canScrollPrev()).toBe(true);
expect(handle.current?.canScrollNext()).toBe(true);
});
it('reports both directions scrollable under hasLoop when overflowing', () => {
const handle = createRef<CarouselHandle>();
render(
<Carousel handleRef={handle} hasLoop aria-label="Handle">
<div>Item 1</div>
<div>Item 2</div>
</Carousel>,
);
const scroller = getScroller();
// Rest at the start edge — normally canScrollPrev would be false.
makeOverflowing(scroller, 0);
expect(handle.current?.canScrollPrev()).toBe(true);
expect(handle.current?.canScrollNext()).toBe(true);
});
it('scrollTo scrolls the container and clamps out-of-range indices', () => {
const handle = createRef<CarouselHandle>();
render(
<Carousel handleRef={handle} aria-label="Handle">
<div>Item 1</div>
<div>Item 2</div>
<div>Item 3</div>
</Carousel>,
);
const scroller = getScroller();
const scrollBy = vi.fn();
scroller.scrollBy = scrollBy;
// Out-of-range index is clamped to the last item — no throw, one call.
expect(() => handle.current?.scrollTo(99)).not.toThrow();
expect(scrollBy).toHaveBeenCalledTimes(1);
// Uses scrollBy (contained to the carousel), never scrollIntoView.
expect(scrollBy.mock.calls[0][0]).toHaveProperty('left');
});
});
describe('keyboard focus at the edges', () => {
function getScroller() {
const region = screen.getByRole('region');
return region.firstElementChild as HTMLElement;
}
// jsdom has no layout, so fake an overflowing container whose scrollBy
// moves scrollLeft and fires scroll, which is what drives the overflow
// state the buttons and the focus hand-off both read. `land` decides where
// the container comes to rest: the default clamps to the requested delta,
// and the snap arm overrides it to model mandatory scroll-snap carrying the
// container past what the press asked for.
function makeScrollable(
el: HTMLElement,
scrollWidth: number,
land?: (requested: number, maxScroll: number) => number,
) {
const clientWidth = 200;
const maxScroll = scrollWidth - clientWidth;
Object.defineProperty(el, 'scrollWidth', {
value: scrollWidth,
configurable: true,
});
Object.defineProperty(el, 'clientWidth', {
value: clientWidth,
configurable: true,
});
Object.defineProperty(el, 'scrollLeft', {
value: 0,
writable: true,
configurable: true,
});
el.scrollBy = ((options: ScrollToOptions) => {
const requested = Math.max(
0,
Math.min(maxScroll, el.scrollLeft + (options.left ?? 0)),
);
el.scrollLeft = land ? land(requested, maxScroll) : requested;
fireEvent.scroll(el);
}) as HTMLElement['scrollBy'];
fireEvent.scroll(el);
}
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">
<div>Item 1</div>
<div>Item 2</div>
<div>Item 3</div>
</Carousel>,
);
// clientWidth 200 against a 200px step, so one press lands exactly on the
// trailing edge and the trailing button disables.
makeScrollable(getScroller(), 400);
const next = screen.getByLabelText('Scroll right');
await user.click(next);
expect(next).toHaveAttribute('aria-disabled', 'true');
expect(document.activeElement).toBe(getScroller());
expect(document.activeElement).not.toBe(document.body);
});
it('hands off in the leading direction too', async () => {
const user = userEvent.setup();
render(
<Carousel aria-label="Gallery">
<div>Item 1</div>
<div>Item 2</div>
<div>Item 3</div>
</Carousel>,
);
const scroller = getScroller();
makeScrollable(scroller, 400);
// Park at the far end so the leading button is the one that runs out.
scroller.scrollLeft = 200;
fireEvent.scroll(scroller);
const previous = screen.getByLabelText('Scroll left');
await user.click(previous);
expect(previous).toHaveAttribute('aria-disabled', 'true');
expect(document.activeElement).toBe(getScroller());
});
it('hands off under RTL, where the scroll axis is inverted', async () => {
const user = userEvent.setup();
render(
<Carousel aria-label="Gallery">
<div>Item 1</div>
<div>Item 2</div>
<div>Item 3</div>
</Carousel>,
);
const scroller = getScroller();
// The component resolves direction with getComputedStyle, and jsdom does
// not inherit `dir` down to it, so set it on the element itself. RTL then
// scrolls negative, which the mock below mirrors.
scroller.style.direction = 'rtl';
const maxScroll = 200;
Object.defineProperty(scroller, 'scrollWidth', {
value: 400,
configurable: true,
});
Object.defineProperty(scroller, 'clientWidth', {
value: 200,
configurable: true,
});
Object.defineProperty(scroller, 'scrollLeft', {
value: 0,
writable: true,
configurable: true,
});
scroller.scrollBy = ((options: ScrollToOptions) => {
scroller.scrollLeft = Math.max(
-maxScroll,
Math.min(0, scroller.scrollLeft + (options.left ?? 0)),
);
fireEvent.scroll(scroller);
}) as HTMLElement['scrollBy'];
fireEvent.scroll(scroller);
const next = screen.getByLabelText('Scroll right');
await user.click(next);
expect(next).toHaveAttribute('aria-disabled', 'true');
expect(document.activeElement).toBe(getScroller());
});
it('hands off when scroll-snap carries the container past what the press asked for', async () => {
const user = userEvent.setup();
render(
<Carousel hasSnap aria-label="Gallery">
<div>Item 1</div>
<div>Item 2</div>
<div>Item 3</div>
</Carousel>,
);
// 700 gives 500 of travel against a 200 step, so the press alone lands
// mid-run. Mandatory snapping then carries it to the end, which is the
// landing position no press can predict.
makeScrollable(getScroller(), 700, (_requested, maxScroll) => maxScroll);
const next = screen.getByLabelText('Scroll right');
await user.click(next);
expect(next).toHaveAttribute('aria-disabled', 'true');
expect(document.activeElement).toBe(getScroller());
});
it('falls back to the scroll container when the carousel stops overflowing', async () => {
const user = userEvent.setup();
render(
<Carousel aria-label="Gallery">
<div>Item 1</div>
<div>Item 2</div>
</Carousel>,
);
const scroller = getScroller();
// The content shrinks to fit during the press, so BOTH buttons disable
// and there is no opposite control left to receive focus.
makeScrollable(scroller, 400, () => {
Object.defineProperty(scroller, 'scrollWidth', {
value: 200,
configurable: true,
});
return 0;
});
await user.click(screen.getByLabelText('Scroll right'));
expect(screen.getByLabelText('Scroll right')).toHaveAttribute(
'aria-disabled',
'true',
);
expect(screen.getByLabelText('Scroll left')).toHaveAttribute(
'aria-disabled',
'true',
);
expect(document.activeElement).toBe(scroller);
expect(document.activeElement).not.toBe(document.body);
});
it('does not pull focus back after the person has left the button', () => {
render(
<Carousel aria-label="Gallery">
<div>Item 1</div>
<div>Item 2</div>
<div>Item 3</div>
</Carousel>,
);
const scroller = getScroller();
makeScrollable(scroller, 400);
// Touch an arrow, then leave it without pressing it. Landing on <body> is
// the case that matters: focus somewhere else is already ignored, so a
// stale tracker only bites when there is nothing else holding focus.
const next = screen.getByLabelText('Scroll right');
next.focus();
next.blur();
expect(document.activeElement).toBe(document.body);
// The carousel reaches the edge on its own: a swipe, a resize, anything
// that is not this person. Their focus is not the carousel's to take.
scroller.scrollLeft = 200;
fireEvent.scroll(scroller);
expect(screen.getByLabelText('Scroll right')).toHaveAttribute(
'aria-disabled',
'true',
);
expect(document.activeElement).toBe(document.body);
});
it('hands off on a press, with the blur handlers in place', async () => {
const user = userEvent.setup();
render(
<Carousel aria-label="Gallery">
<div>Item 1</div>
<div>Item 2</div>
<div>Item 3</div>
</Carousel>,
);
makeScrollable(getScroller(), 400);
// The Effect clears the tracker itself before focusing, so the commit's
// own blur finds nothing left to clear and the guard is not what makes
// this pass. It is here so that deleting the blur handlers outright --
// rather than loosening the guard -- is caught.
await user.click(screen.getByLabelText('Scroll right'));
expect(document.activeElement).toBe(getScroller());
});
it('does not move focus on a press that leaves the direction available', async () => {
const user = userEvent.setup();
render(
<Carousel aria-label="Gallery">
<div>Item 1</div>
<div>Item 2</div>
<div>Item 3</div>
</Carousel>,
);
makeScrollable(getScroller(), 600);
const next = screen.getByLabelText('Scroll right');
await user.click(next);
expect(next).not.toHaveAttribute('aria-disabled');
expect(document.activeElement).toBe(next);
});
it('does not move focus when hasLoop keeps both buttons enabled', async () => {
const user = userEvent.setup();
render(
<Carousel hasLoop aria-label="Looping">
<div>Item 1</div>
<div>Item 2</div>
</Carousel>,
);
makeScrollable(getScroller(), 400);
const next = screen.getByLabelText('Scroll right');
await user.click(next);
expect(next).not.toHaveAttribute('aria-disabled');
expect(document.activeElement).toBe(next);
});
it('takes focus without scrolling the receiver into view', async () => {
const user = userEvent.setup();
render(
<Carousel aria-label="Gallery">
<div>Item 1</div>
<div>Item 2</div>
</Carousel>,
);
makeScrollable(getScroller(), 400);
const focus = vi.spyOn(getScroller(), 'focus');
await user.click(screen.getByLabelText('Scroll right'));
// A plain focus() scrolls its element into view, which on the scroll
// container cancels the scroll the same press started.
expect(focus).toHaveBeenCalledWith({preventScroll: true});
});
it('leaves focus alone when the imperative handle drives the scroll', () => {
const handle = createRef<CarouselHandle>();
render(
<Carousel handleRef={handle} aria-label="Gallery">
<div>Item 1</div>
<div>Item 2</div>
</Carousel>,
);
makeScrollable(getScroller(), 400);
const outside = document.createElement('button');
document.body.appendChild(outside);
outside.focus();
handle.current?.scrollNext();
expect(document.activeElement).toBe(outside);
outside.remove();
});
it('does not move focus a second time for one transition', async () => {
const user = userEvent.setup();
const {rerender} = render(
<Carousel aria-label="Gallery">
<div>Item 1</div>
<div>Item 2</div>
<div>Item 3</div>
</Carousel>,
);
makeScrollable(getScroller(), 400);
await user.click(screen.getByLabelText('Scroll right'));
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');
document.body.appendChild(outside);
outside.focus();
rerender(
<Carousel aria-label="Gallery">
<div>Item 1</div>
<div>Item 2</div>
<div>Item 3</div>
</Carousel>,
);
expect(document.activeElement).toBe(outside);
outside.remove();
});
it('reflects the scroll container as a theme target carrying its style-driving props', () => {
render(
<Carousel gap={2} padding={3} hasSnap aria-label="Gallery">
<div>Item 1</div>
</Carousel>,
);
const scroller = getScroller();
expect(scroller).toHaveClass('astryx-carousel-scroller');
expect(scroller).toHaveAttribute('data-gap', '2');
expect(scroller).toHaveAttribute('data-padding', '3');
expect(scroller).toHaveAttribute('data-snap', 'snap');
expect(scroller).toHaveAttribute('data-edge-fade', 'edge-fade');
});
it('omits the opt-out attributes a theme should not see', () => {
render(
<Carousel hasEdgeFade={false} aria-label="Gallery">
<div>Item 1</div>
</Carousel>,
);
const scroller = getScroller();
expect(scroller).not.toHaveAttribute('data-edge-fade');
expect(scroller).not.toHaveAttribute('data-snap');
expect(scroller).not.toHaveAttribute('data-padding');
});
});
describe('edge fade', () => {
function getScroller() {
const region = screen.getByRole('region');
return region.firstElementChild as HTMLElement;
}
function makeOverflowing(el: HTMLElement, scrollLeft: number) {
Object.defineProperty(el, 'scrollWidth', {
value: 500,
configurable: true,
});
Object.defineProperty(el, 'clientWidth', {
value: 200,
configurable: true,
});
Object.defineProperty(el, 'scrollLeft', {
value: scrollLeft,
writable: true,
configurable: true,
});
fireEvent.scroll(el);
}
function injectedCss(): string {
let out = '';
for (const sheet of Array.from(document.styleSheets)) {
try {
for (const rule of Array.from(sheet.cssRules)) {
out += rule.cssText + '\n';
}
} catch {
// Ignore cross-origin sheets.
}
}
return out;
}
it('fades the physical left edge when only the start overflows (LTR)', () => {
render(
<Carousel aria-label="Fade">
<div>Item 1</div>
<div>Item 2</div>
</Carousel>,
);
const scroller = getScroller();
makeOverflowing(scroller, 300);
expect(getComputedStyle(scroller).maskImage).toContain(
'linear-gradient(to right',
);
});
it('fades the physical right edge when only the end overflows (LTR)', () => {
render(
<Carousel aria-label="Fade">
<div>Item 1</div>
<div>Item 2</div>
</Carousel>,
);
const scroller = getScroller();
makeOverflowing(scroller, 0);
expect(getComputedStyle(scroller).maskImage).toContain(
'linear-gradient(to left',
);
});
it('mirrors both single-edge fade gradients under RTL', () => {
render(
<Carousel aria-label="Fade">
<div>Item 1</div>
<div>Item 2</div>
</Carousel>,
);
const css = injectedCss();
expect(css).toMatch(
/:is\(\[dir="rtl"\][^)]*\)[^{]*\{\s*mask-image:\s*linear-gradient\(to left/,
);
expect(css).toMatch(
/:is\(\[dir="rtl"\][^)]*\)[^{]*\{\s*mask-image:\s*linear-gradient\(to right/,
);
});
});
});