An open source design system that's fully customizable and agent ready
TypeScript
fix(Carousel): remove scale animation, add hasEdgeFade + padding props, fix hasButtons (#2566)
Cindy Zhang307d4ee2245c
diff --git a/apps/docsite/src/app/(site)/_landing/ThemingShowcase.tsx b/apps/docsite/src/app/(site)/_landing/ThemingShowcase.tsxindex 23fe3ba3fe..7a03ae740f 100644--- a/apps/docsite/src/app/(site)/_landing/ThemingShowcase.tsx+++ b/apps/docsite/src/app/(site)/_landing/ThemingShowcase.tsx@@ -304,44 +304,15 @@ export function ThemingShowcase() {<HeaderLinks /></XDSHStack>- {/* Carousel customisations that aren't expressible through- XDSCarousel's prop surface. Scoped via the aria-label of- *this* carousel so other XDSCarousel elsewhere in the- docsite are unaffected. Rules only exist while- ThemingShowcase is mounted (landing route only).+ {/* Scroller padding that aligns the first tile to the heading+ text column. This is a layout concern (not chrome) so it+ remains as a scoped style targeting this carousel's scroller.- TODO(xds#2509): Remove this block once XDSCarousel ships- `hasEdgeFade` / `hasScaleAnimation` props and a reliable- `hasButtons={false}`. Tracking issue:- https://github.com/facebookexperimental/xds/issues/2509-- 1. Hide XDSCarousel's built-in prev/next pills — our own- controls render in the header row. `hasButtons={false}`- prop is intermittently flaky across HMR/popover states,- so we belt-and-suspender with CSS targeting the- popover-portal'd buttons by their aria-label.-- 2. Strip XDSCarousel's mask-image edge fade. The default- reads as a smudgy band; full-bleed filmstrip uses the- clean viewport clip instead.-- 3. Disable the scroll-driven 0.85→1.0→0.85 scale animation- on each item — reads as inconsistent sizing rather than- a helpful focus cue when each tile has its own theme.-- 4. Add left-padding equal to the page gutter so the FIRST- tile aligns with the heading column's left edge instead- of sitting flush against the viewport (the right end- stays flush so the last tile clips at the viewport edge,- signalling "more").+ TODO: Consider a `scrollerXstyle` prop or padding prop on+ XDSCarousel if this pattern recurs in other full-bleed usages.*/}<style>{`- [popover]:has([aria-label="Scroll left"]),- [popover]:has([aria-label="Scroll right"]) {- display: none !important;- }[aria-label="Available themes"] > div:first-child {- mask-image: none !important;/* Gutter that aligns the first tile to the heading textleading edge. Applied as padding on the scroller (nota margin on the wrapper) so the gutter is INSIDE the@@ -359,9 +330,6 @@ export function ThemingShowcase() {padding-inline-end: ${CONTENT_GUTTER_FORMULA} !important;scroll-padding-inline-end: ${CONTENT_GUTTER_FORMULA} !important;}- [aria-label="Available themes"] > div > div {- animation: none !important;- }`}</style><div {...stylex.props(styles.carouselWrap)}>@@ -369,7 +337,8 @@ export function ThemingShowcase() {aria-label="Available themes"gap={4}hasSnap- hasButtons={false}>+ hasButtons={false}+ hasEdgeFade={false}>{themePackages.map(pkg => {const theme = themeObjects[pkg.name];if (!theme) {diff --git a/packages/core/src/Carousel/XDSCarousel.test.tsx b/packages/core/src/Carousel/XDSCarousel.test.tsxindex f1378088d0..fb2ead72b0 100644--- a/packages/core/src/Carousel/XDSCarousel.test.tsx+++ b/packages/core/src/Carousel/XDSCarousel.test.tsx@@ -56,4 +56,26 @@ describe('XDSCarousel', () => {const el = screen.getByTestId('cls-test');expect(el.className).toContain('xds-carousel');});++ it('does not render button layer when hasButtons={false}', () => {+ render(+ <XDSCarousel hasButtons={false} aria-label="No buttons">+ <div>Item 1</div>+ <div>Item 2</div>+ </XDSCarousel>,+ );+ expect(screen.queryByLabelText('Scroll left')).not.toBeInTheDocument();+ expect(screen.queryByLabelText('Scroll right')).not.toBeInTheDocument();+ });++ it('renders buttons by default', () => {+ render(+ <XDSCarousel aria-label="With buttons">+ <div>Item 1</div>+ <div>Item 2</div>+ </XDSCarousel>,+ );+ expect(screen.getByLabelText('Scroll left')).toBeInTheDocument();+ expect(screen.getByLabelText('Scroll right')).toBeInTheDocument();+ });});diff --git a/packages/core/src/Carousel/XDSCarousel.tsx b/packages/core/src/Carousel/XDSCarousel.tsxindex c4c41b6f0a..37bed3a59a 100644--- a/packages/core/src/Carousel/XDSCarousel.tsx+++ b/packages/core/src/Carousel/XDSCarousel.tsx@@ -31,6 +31,7 @@ import {useXDSLayer} from '../Layer';import {useScrollOverflow} from '../hooks/useScrollOverflow';import type {XDSBaseProps} from '../XDSBaseProps';import {xdsClassName, mergeProps, mergeRefs} from '../utils';+import type {SpacingStep} from '../utils/types';export interface XDSCarouselProps extends XDSBaseProps<HTMLDivElement> {ref?: React.Ref<HTMLDivElement>;@@ -46,11 +47,28 @@ export interface XDSCarouselProps extends XDSBaseProps<HTMLDivElement> {* @default true*/hasButtons?: boolean;+ /**+ * Show gradient edge-fade mask when content overflows, signalling that+ * more items exist off-screen. Can be suppressed when items have+ * full-fidelity surfaces that look broken when masked.+ * @default true+ */+ hasEdgeFade?: boolean;/*** Enable scroll-snap on items. Each direct child snaps to the start edge.* @default false*/hasSnap?: boolean;+ /**+ * Inline padding on the scroll container. Applied as padding-inline+ * so the gutter is inside the scrollable area — items can scroll fully+ * into the padded region. Also sets matching scroll-padding so snap+ * points align to the content edge rather than the viewport edge.+ *+ * Accepts numeric spacing steps: 0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10.+ * @default undefined (no padding)+ */+ padding?: SpacingStep;/*** Accessible label for the carousel region.* @default 'Carousel'@@ -107,21 +125,6 @@ const styles = stylex.create({scrollSnapAlign: 'start',display: 'flex',flexShrink: 0,- // Entry: 0% = item just touching edge, ~15% = item half in view, ~30% = fully in view- // Exit mirrors in reverse. Scale down only while partially out of view.- animationName: stylex.keyframes({- '0%': {transform: 'scale(0.85)'},- '15%': {transform: 'scale(1)'},- '85%': {transform: 'scale(1)'},- '100%': {transform: 'scale(0.85)'},- }),- animationTimeline: 'view(inline)',- animationRange: 'cover',- animationFillMode: 'both',- animationDuration: {- default: null,- '@media (prefers-reduced-motion: reduce)': '0ms',- },},// Overlay on top layer — covers the carousel anchor areabuttonOverlay: {@@ -169,6 +172,20 @@ const gapStyles = stylex.create({4: {gap: spacingVars['--spacing-4']},});+const paddingStyles = stylex.create({+ 0: {paddingInline: spacingVars['--spacing-0'], scrollPaddingInline: spacingVars['--spacing-0']},+ 0.5: {paddingInline: spacingVars['--spacing-0-5'], scrollPaddingInline: spacingVars['--spacing-0-5']},+ 1: {paddingInline: spacingVars['--spacing-1'], scrollPaddingInline: spacingVars['--spacing-1']},+ 1.5: {paddingInline: spacingVars['--spacing-1-5'], scrollPaddingInline: spacingVars['--spacing-1-5']},+ 2: {paddingInline: spacingVars['--spacing-2'], scrollPaddingInline: spacingVars['--spacing-2']},+ 3: {paddingInline: spacingVars['--spacing-3'], scrollPaddingInline: spacingVars['--spacing-3']},+ 4: {paddingInline: spacingVars['--spacing-4'], scrollPaddingInline: spacingVars['--spacing-4']},+ 5: {paddingInline: spacingVars['--spacing-5'], scrollPaddingInline: spacingVars['--spacing-5']},+ 6: {paddingInline: spacingVars['--spacing-6'], scrollPaddingInline: spacingVars['--spacing-6']},+ 8: {paddingInline: spacingVars['--spacing-8'], scrollPaddingInline: spacingVars['--spacing-8']},+ 10: {paddingInline: spacingVars['--spacing-10'], scrollPaddingInline: spacingVars['--spacing-10']},+});+// =============================================================================// Component// =============================================================================@@ -196,7 +213,9 @@ export function XDSCarousel({children,gap = 1,hasButtons = true,+ hasEdgeFade = true,hasSnap = false,+ padding,'aria-label': ariaLabel = 'Carousel',xstyle,className,@@ -242,14 +261,15 @@ export function XDSCarousel({});}, []);- const fadeStyle =- overflowStart && overflowEnd+ const fadeStyle = hasEdgeFade+ ? overflowStart && overflowEnd? styles.fadeBoth: overflowStart? styles.fadeStart: overflowEnd? styles.fadeEnd- : null;+ : null+ : null;const coverStyle: React.CSSProperties = {positionArea: 'center',@@ -276,6 +296,7 @@ export function XDSCarousel({{...stylex.props(styles.scroller,gapStyles[gap],+ padding != null && paddingStyles[padding],hasSnap && styles.snap,fadeStyle,)}>@@ -284,48 +305,49 @@ export function XDSCarousel({))}</div>- {layer.render(- <>- <div- {...stylex.props(- styles.buttonPill,- styles.buttonPillStart,- !overflowStart && styles.buttonHidden,- )}>- <XDSButton- icon={<XDSIcon icon="chevronLeft" size="xsm" />}- label="Scroll left"- variant="ghost"- size="sm"- isIconOnly- onClick={() => scrollBy(-1)}- xstyle={styles.buttonRadiusOverride}- />- </div>- <div- {...stylex.props(- styles.buttonPill,- styles.buttonPillEnd,- !overflowEnd && styles.buttonHidden,- )}>- <XDSButton- icon={<XDSIcon icon="chevronRight" size="xsm" />}- label="Scroll right"- variant="ghost"- size="sm"- isIconOnly- onClick={() => scrollBy(1)}- xstyle={styles.buttonRadiusOverride}- />- </div>- </>,- {- placement: 'below',- alignment: 'center',- style: coverStyle,- xstyle: styles.buttonOverlay,- },- )}+ {hasButtons &&+ layer.render(+ <>+ <div+ {...stylex.props(+ styles.buttonPill,+ styles.buttonPillStart,+ !overflowStart && styles.buttonHidden,+ )}>+ <XDSButton+ icon={<XDSIcon icon="chevronLeft" size="xsm" />}+ label="Scroll left"+ variant="ghost"+ size="sm"+ isIconOnly+ onClick={() => scrollBy(-1)}+ xstyle={styles.buttonRadiusOverride}+ />+ </div>+ <div+ {...stylex.props(+ styles.buttonPill,+ styles.buttonPillEnd,+ !overflowEnd && styles.buttonHidden,+ )}>+ <XDSButton+ icon={<XDSIcon icon="chevronRight" size="xsm" />}+ label="Scroll right"+ variant="ghost"+ size="sm"+ isIconOnly+ onClick={() => scrollBy(1)}+ xstyle={styles.buttonRadiusOverride}+ />+ </div>+ </>,+ {+ placement: 'below',+ alignment: 'center',+ style: coverStyle,+ xstyle: styles.buttonOverlay,+ },+ )}</div>);}