An open source design system that's fully customizable and agent ready
TypeScript
fix(Carousel): Shift + vertical wheel scrolls horizontally (#4129) (#4192)
Cindy Zhang1d9a74d27d97
diff --git a/.changeset/carousel-shift-wheel-horizontal.md b/.changeset/carousel-shift-wheel-horizontal.mdnew file mode 100644index 0000000000..988566e8e3--- /dev/null+++ b/.changeset/carousel-shift-wheel-horizontal.md@@ -0,0 +1,7 @@+---+'@astryxdesign/core': patch+---++[fix] Carousel now scrolls horizontally when you hold Shift and scroll the mouse wheel. Trackpad users already got horizontal scroll for free; this brings standard mouse (vertical-only wheel) users to parity using the established Shift + wheel convention. Native trackpad horizontal scrolling and the prev/next buttons are unchanged.++@cixzhangdiff --git a/packages/core/src/Carousel/Carousel.doc.mjs b/packages/core/src/Carousel/Carousel.doc.mjsindex 5c45aa2409..d05780e1c4 100644--- a/packages/core/src/Carousel/Carousel.doc.mjs+++ b/packages/core/src/Carousel/Carousel.doc.mjs@@ -14,6 +14,7 @@ export const docs = {{guidance: true, description: 'Enable scroll-snap when each item should land precisely at the start edge, like a gallery or product list.'},{guidance: true, description: 'Always provide an aria-label that describes what the carousel contains, like "Featured products" or "Team members".'},{guidance: true, description: 'Use a consistent gap and item width so the carousel looks intentional, not like content overflowing by accident.'},+ {guidance: true, description: 'Trust the built-in navigation: trackpad users can swipe horizontally, and mouse users can hold Shift while scrolling the wheel to move through items.'},{guidance: false, description: 'Use a carousel for content every user must see. Not everyone scrolls horizontally, so put critical content above the fold.'},{guidance: false, description: 'Auto-advance items. Let the user scroll at their own pace.'},{guidance: false, description: 'Nest carousels. A carousel inside a carousel is confusing and breaks keyboard navigation.'},diff --git a/packages/core/src/Carousel/Carousel.test.tsx b/packages/core/src/Carousel/Carousel.test.tsxindex 7a6c80e200..1a01b43d92 100644--- a/packages/core/src/Carousel/Carousel.test.tsx+++ b/packages/core/src/Carousel/Carousel.test.tsx@@ -1,7 +1,7 @@// Copyright (c) Meta Platforms, Inc. and affiliates.import {describe, it, expect, vi} from 'vitest';-import {render, screen} from '@testing-library/react';+import {render, screen, fireEvent} from '@testing-library/react';import {Carousel} from './Carousel';// Mock ResizeObserver (not available in jsdom)@@ -111,4 +111,99 @@ describe('Carousel', () => {expect(left).toBeDisabled();expect(right).toBeDisabled();});++ 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);+ const scrollBy = vi.fn();+ scroller.scrollBy = scrollBy;++ fireEvent.wheel(scroller, {shiftKey: true, deltaY: 120, deltaX: 0});++ expect(scrollBy).toHaveBeenCalledWith({left: 120, behavior: 'auto'});+ });++ 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);+ 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);+ const scrollBy = vi.fn();+ scroller.scrollBy = scrollBy;++ fireEvent.wheel(scroller, {shiftKey: true, deltaY: 120, deltaX: 40});++ expect(scrollBy).not.toHaveBeenCalled();+ });++ 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();+ });+ });});diff --git a/packages/core/src/Carousel/Carousel.tsx b/packages/core/src/Carousel/Carousel.tsxindex 4796e11018..6f2de18f9a 100644--- a/packages/core/src/Carousel/Carousel.tsx+++ b/packages/core/src/Carousel/Carousel.tsx@@ -7,8 +7,9 @@* @input Uses React, StyleX, useScrollOverflow, useLayer, Button, Icon, theme tokens* @output Exports Carousel component* @position Horizontal scroll container with fade-edge overflow indication,- * optional prev/next buttons on the top layer, scroll-snap, and a 1px- * visual bleed allowance for child selection indicators.+ * 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.** SYNC: When modified, update:* - /packages/core/src/Carousel/index.ts (exports)@@ -290,6 +291,31 @@ export function Carousel({[scrollRef],);+ // Map Shift + vertical wheel to horizontal scroll. Trackpads emit+ // horizontal deltas natively, but a standard mouse only produces deltaY —+ // so mouse users can't wheel-scroll a horizontal container. Shift + wheel+ // is the long-established convention for horizontal scroll containers; we+ // honor it by translating the vertical delta into a horizontal scroll.+ //+ // Only kicks in when Shift is held and the wheel is purely vertical+ // (deltaX === 0), so native trackpad horizontal scrolling is untouched.+ const handleWheel = useCallback((event: React.WheelEvent<HTMLDivElement>) => {+ if (!event.shiftKey || event.deltaY === 0 || event.deltaX !== 0) {+ return;+ }+ const el = scrollElRef.current;+ if (!el) {+ return;+ }+ // Nothing to scroll horizontally — let the event fall through so the page+ // can scroll as it normally would.+ if (el.scrollWidth <= el.clientWidth) {+ return;+ }+ event.preventDefault();+ el.scrollBy({left: event.deltaY, behavior: 'auto'});+ }, []);+const scrollBy = useCallback((direction: -1 | 1) => {const el = scrollElRef.current;if (!el) {@@ -346,6 +372,7 @@ export function Carousel({<divref={composedRef}tabIndex={0}+ onWheel={handleWheel}{...stylex.props(styles.scroller,gapStyles[gap],