An open source design system that's fully customizable and agent ready
TypeScript
fix(Grid): cap column count via track-max instead of container max-width (#1761)
Cindy Zhange285e72b0881
diff --git a/apps/storybook/stories/Grid.stories.tsx b/apps/storybook/stories/Grid.stories.tsxindex 0e673ecf5a..b3c7f143eb 100644--- a/apps/storybook/stories/Grid.stories.tsx+++ b/apps/storybook/stories/Grid.stories.tsx@@ -233,8 +233,7 @@ export const CappedResponsive: Story = {render: () => (<div {...stylex.props(styles.container)}><XDSText type="supporting" xstyle={styles.sectionLabel}>- Responsive with max 3 columns (min 250px per item, capped via- max-width)+ Responsive with max 3 columns (min 250px per item, capped via track-max)</XDSText><XDSGrid columns={{minWidth: 250, max: 3}} gap={4}><GridItem>Item 1</GridItem>diff --git a/packages/core/src/Grid/XDSGrid.test.tsx b/packages/core/src/Grid/XDSGrid.test.tsxindex 33704d8a3b..3d74ad07c8 100644--- a/packages/core/src/Grid/XDSGrid.test.tsx+++ b/packages/core/src/Grid/XDSGrid.test.tsx@@ -39,7 +39,7 @@ describe('XDSGrid', () => {);});- it('renders with columns object max (capped)', () => {+ it('renders with columns object max (capped via track-max)', () => {render(<XDSGrid columns={{minWidth: 250, max: 3}} gap={4} data-testid="grid"><div>Item 1</div>@@ -48,23 +48,29 @@ describe('XDSGrid', () => {</XDSGrid>,);const grid = screen.getByTestId('grid');+ // Track max caps at (100% - 2 * gap) / 3 — no maxWidth on containerexpect(grid.style.gridTemplateColumns).toBe(- 'repeat(auto-fill, minmax(250px, 1fr))',+ 'repeat(auto-fill, minmax(250px, calc((100% - 2 * var(--spacing-4)) / 3)))',);- // maxWidth = 3 * 250 + 2 * 16 = 750 + 32 = 782px- expect(grid.style.maxWidth).toBe('782px');+ expect(grid.style.maxWidth).toBe('');});it('renders with columns object max using columnGap', () => {render(- <XDSGrid columns={{minWidth: 200, max: 4}} columnGap={6} data-testid="grid">+ <XDSGrid+ columns={{minWidth: 200, max: 4}}+ columnGap={6}+ data-testid="grid"><div>Item 1</div><div>Item 2</div></XDSGrid>,);const grid = screen.getByTestId('grid');- // maxWidth = 4 * 200 + 3 * 24 = 800 + 72 = 872px- expect(grid.style.maxWidth).toBe('872px');+ // columnGap takes precedence for track-max calculation+ expect(grid.style.gridTemplateColumns).toBe(+ 'repeat(auto-fill, minmax(200px, calc((100% - 3 * var(--spacing-6)) / 4)))',+ );+ expect(grid.style.maxWidth).toBe('');});it('applies gap correctly', () => {@@ -136,7 +142,7 @@ describe('XDSGrid', () => {expect(grid.style.gridTemplateColumns).toBe('1fr');});- it('uses auto-fill without maxWidth cap when no max specified', () => {+ it('uses auto-fill without track-max cap when no max specified', () => {render(<XDSGrid columns={{minWidth: 200}} data-testid="grid"><div>Item</div>@@ -193,7 +199,7 @@ describe('XDSGrid', () => {// --- P2: columns object + columnGap interaction (hardening #719) ---- it('calculates maxWidth using columnGap when both columnGap and gap are set', () => {+ it('uses columnGap var in track-max when both columnGap and gap are set', () => {render(<XDSGridcolumns={{minWidth: 200, max: 3}}@@ -204,31 +210,37 @@ describe('XDSGrid', () => {</XDSGrid>,);const grid = screen.getByTestId('grid');- // columnGap should take precedence over gap for maxWidth calculation- // maxWidth = 3 * 200 + 2 * 24 (space6=24px) = 600 + 48 = 648px- expect(grid.style.maxWidth).toBe('648px');+ // columnGap takes precedence over gap in track-max+ expect(grid.style.gridTemplateColumns).toBe(+ 'repeat(auto-fill, minmax(200px, calc((100% - 2 * var(--spacing-6)) / 3)))',+ );+ expect(grid.style.maxWidth).toBe('');});- it('calculates maxWidth using gap when columnGap is not set', () => {+ it('uses gap var in track-max when columnGap is not set', () => {render(<XDSGrid columns={{minWidth: 150, max: 2}} gap={3} data-testid="grid"><div>Item</div></XDSGrid>,);const grid = screen.getByTestId('grid');- // maxWidth = 2 * 150 + 1 * 12 (space3=12px) = 300 + 12 = 312px- expect(grid.style.maxWidth).toBe('312px');+ expect(grid.style.gridTemplateColumns).toBe(+ 'repeat(auto-fill, minmax(150px, calc((100% - 1 * var(--spacing-3)) / 2)))',+ );+ expect(grid.style.maxWidth).toBe('');});- it('calculates maxWidth with zero gap when neither gap nor columnGap is set', () => {+ it('uses simple fraction in track-max when no gap is set', () => {render(<XDSGrid columns={{minWidth: 100, max: 3}} data-testid="grid"><div>Item</div></XDSGrid>,);const grid = screen.getByTestId('grid');- // maxWidth = 3 * 100 + 2 * 0 = 300px- expect(grid.style.maxWidth).toBe('300px');+ expect(grid.style.gridTemplateColumns).toBe(+ 'repeat(auto-fill, minmax(100px, calc(100% / 3)))',+ );+ expect(grid.style.maxWidth).toBe('');});it('forwards ref correctly', () => {@@ -305,7 +317,7 @@ describe('XDSGrid', () => {);});- it('renders with columns={{minWidth, max}} capping via maxWidth', () => {+ it('renders with columns={{minWidth, max}} capping via track-max', () => {render(<XDSGrid columns={{minWidth: 280, max: 3}} gap={4} data-testid="grid"><div>Item 1</div>@@ -313,14 +325,14 @@ describe('XDSGrid', () => {</XDSGrid>,);const grid = screen.getByTestId('grid');+ // Track-max limits columns — grid stays full widthexpect(grid.style.gridTemplateColumns).toBe(- 'repeat(auto-fill, minmax(280px, 1fr))',+ 'repeat(auto-fill, minmax(280px, calc((100% - 2 * var(--spacing-4)) / 3)))',);- // maxWidth = 3 * 280 + 2 * 16 = 840 + 32 = 872px- expect(grid.style.maxWidth).toBe('872px');+ expect(grid.style.maxWidth).toBe('');});- it('renders with columns={{minWidth, max, repeat: "fit"}} using auto-fit + maxWidth', () => {+ it('renders with columns={{minWidth, max, repeat: "fit"}} using auto-fit + track-max', () => {render(<XDSGridcolumns={{minWidth: 280, max: 3, repeat: 'fit'}}@@ -332,12 +344,10 @@ describe('XDSGrid', () => {);const grid = screen.getByTestId('grid');expect(grid.style.gridTemplateColumns).toBe(- 'repeat(auto-fit, minmax(280px, 1fr))',+ 'repeat(auto-fit, minmax(280px, calc((100% - 2 * var(--spacing-4)) / 3)))',);- // maxWidth = 3 * 280 + 2 * 16 = 840 + 32 = 872px- expect(grid.style.maxWidth).toBe('872px');+ expect(grid.style.maxWidth).toBe('');});-});describe('XDSGridSpan', () => {diff --git a/packages/core/src/Grid/XDSGrid.tsx b/packages/core/src/Grid/XDSGrid.tsxindex 609b8950b3..82f0bb4485 100644--- a/packages/core/src/Grid/XDSGrid.tsx+++ b/packages/core/src/Grid/XDSGrid.tsx@@ -12,7 +12,6 @@* - /apps/storybook/stories/Grid.stories.tsx*/-import {type ReactNode} from 'react';import type {XDSBaseProps} from '../XDSBaseProps';import * as stylex from '@stylexjs/stylex';@@ -36,7 +35,9 @@ export type GridAlignment = 'start' | 'center' | 'end' | 'stretch';* - `minWidth` — minimum width (px) for each column track* - `repeat` — `'fill'` (default) preserves empty tracks for consistent widths;* `'fit'` collapses empty tracks so items stretch to fill- * - `max` — caps the maximum number of columns via max-width+ * - `max` — caps the maximum number of columns by limiting track max size.+ * The grid stretches to 100% of its parent; `max` only limits how many+ * columns appear.*/export type XDSGridColumns =| number@@ -296,38 +297,48 @@ const columnGapStyles = stylex.create({},});-// Spacing token values in pixels for max-width calculation-const spacingPixels: Record<SpacingStep, number> = {- 0: 0,- 0.5: 2,- 1: 4,- 1.5: 6,- 2: 8,- 3: 12,- 4: 16,- 5: 20,- 6: 24,- 8: 32,- 10: 40,+/**+ * Spacing token CSS var names for gap calculation in track-max expressions.+ */+const spacingVarNames: Record<SpacingStep, string> = {+ 0: '--spacing-0',+ 0.5: '--spacing-0-5',+ 1: '--spacing-1',+ 1.5: '--spacing-1-5',+ 2: '--spacing-2',+ 3: '--spacing-3',+ 4: '--spacing-4',+ 5: '--spacing-5',+ 6: '--spacing-6',+ 8: '--spacing-8',+ 10: '--spacing-10',};/**- * Calculate max-width when capping columns.- * maxWidth = maxCols * minWidth + (maxCols - 1) * gapPx+ * Build a grid-template-columns value that caps columns at `max` by+ * limiting each track's max size to `(100% - (max-1) * gap) / max`.+ * The grid stays 100% width; the track-max prevents more than `max` columns.*/-function calculateMaxWidth(- maxCols: number,+function buildCappedTemplate(minWidth: number,+ maxCols: number,+ repeatMode: 'auto-fill' | 'auto-fit',gap: SpacingStep | undefined,columnGap: SpacingStep | undefined,-): number {- const gapPx =+): string {+ const gapVar =columnGap != null- ? spacingPixels[columnGap]+ ? spacingVarNames[columnGap]: gap != null- ? spacingPixels[gap]- : 0;- return maxCols * minWidth + (maxCols - 1) * gapPx;+ ? spacingVarNames[gap]+ : null;++ // trackMax = (100% - (maxCols - 1) * gap) / maxCols+ const trackMax = gapVar+ ? `calc((100% - ${maxCols - 1} * var(${gapVar})) / ${maxCols})`+ : `calc(100% / ${maxCols})`;++ return `repeat(${repeatMode}, minmax(${minWidth}px, ${trackMax}))`;}/**@@ -368,33 +379,36 @@ export function XDSGrid({}: XDSGridProps) {// Determine grid-template-columns valuelet gridTemplateColumns: string;- let calculatedMaxWidth: number | undefined;if (typeof columns === 'object' && columns != null) {- // New responsive API: columns={{minWidth, max?, repeat?}}+ // Responsive API: columns={{minWidth, max?, repeat?}}const repeatMode = columns.repeat === 'fit' ? 'auto-fit' : 'auto-fill';- gridTemplateColumns = `repeat(${repeatMode}, minmax(${columns.minWidth}px, 1fr))`;if (columns.max != null && columns.max > 0) {- calculatedMaxWidth = calculateMaxWidth(- columns.max,+ // Cap column count by limiting each track's max size+ gridTemplateColumns = buildCappedTemplate(columns.minWidth,+ columns.max,+ repeatMode,gap,columnGap,);+ } else {+ gridTemplateColumns = `repeat(${repeatMode}, minmax(${columns.minWidth}px, 1fr))`;}} else if (minChildWidth > 0) {// Deprecated path: minChildWidth uses auto-fit for backward compat- gridTemplateColumns = `repeat(auto-fit, minmax(${minChildWidth}px, 1fr))`;-const numColumns = typeof columns === 'number' ? columns : 0;if (numColumns > 0) {- calculatedMaxWidth = calculateMaxWidth(- numColumns,+ gridTemplateColumns = buildCappedTemplate(minChildWidth,+ numColumns,+ 'auto-fit',gap,columnGap,);+ } else {+ gridTemplateColumns = `repeat(auto-fit, minmax(${minChildWidth}px, 1fr))`;}} else if (typeof columns === 'number' && columns > 0) {// Fixed columns mode@@ -408,7 +422,6 @@ export function XDSGrid({const inlineStyle: React.CSSProperties = {gridTemplateColumns,...(rowHeight != null && {gridAutoRows: `${rowHeight}px`}),- ...(calculatedMaxWidth != null && {maxWidth: `${calculatedMaxWidth}px`}),...(width != null && {width: typeof width === 'number' ? `${width}px` : width,}),