Skip to content

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.tsx
index 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.tsx
index 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 container
expect(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(
<XDSGrid
columns={{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 width
expect(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(
<XDSGrid
columns={{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.tsx
index 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 value
let 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,
}),