Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat(Grid): unified responsive columns API (#1422)

Kenton Quatman8fd3c1dc3cac
diff --git a/apps/storybook/stories/Grid.stories.tsx b/apps/storybook/stories/Grid.stories.tsx
index fb7b53e2c9..1ea0b3f5c7 100644
--- a/apps/storybook/stories/Grid.stories.tsx
+++ b/apps/storybook/stories/Grid.stories.tsx
@@ -4,6 +4,7 @@ import {XDSGrid, XDSGridSpan} from '@xds/core/Grid';
import {XDSCard} from '@xds/core/Card';
import {XDSSection} from '@xds/core/Section';
import {XDSText} from '@xds/core/Text';
+import {XDSVStack} from '@xds/core/Stack';
import {
colorVars,
spacingVars,
@@ -51,13 +52,9 @@ const meta: Meta<typeof XDSGrid> = {
tags: ['autodocs'],
argTypes: {
columns: {
- control: 'number',
- description: 'Maximum number of columns',
- },
- minChildWidth: {
- control: 'number',
+ control: 'object',
description:
- 'Minimum width of each grid item in pixels (enables auto-fit)',
+ 'Column configuration: number for fixed columns, or {minWidth, max?, repeat?} for responsive',
},
gap: {
control: 'select',
@@ -154,31 +151,92 @@ export const FixedColumns: Story = {
),
};
+/**
+ * auto-fit (repeat: 'fit') stretches items to fill when there are fewer
+ * items than available columns. Compare with auto-fill (default) which
+ * preserves consistent widths.
+ */
export const ResponsiveAutoFit: Story = {
+ render: () => (
+ <XDSVStack gap={6}>
+ <div {...stylex.props(styles.container)}>
+ <XDSText type="supporting" xstyle={styles.sectionLabel}>
+ minChildWidth=200 with 2 items — cards stretch to fill (auto-fit)
+ </XDSText>
+ <XDSGrid minChildWidth={200} gap={4}>
+ <GridItem>Item 1</GridItem>
+ <GridItem>Item 2</GridItem>
+ </XDSGrid>
+ </div>
+ <div {...stylex.props(styles.container)}>
+ <XDSText type="supporting" xstyle={styles.sectionLabel}>
+ Same grid with 6 items — looks fine because items fill the tracks
+ </XDSText>
+ <XDSGrid minChildWidth={200} gap={4}>
+ <GridItem>Item 1</GridItem>
+ <GridItem>Item 2</GridItem>
+ <GridItem>Item 3</GridItem>
+ <GridItem>Item 4</GridItem>
+ <GridItem>Item 5</GridItem>
+ <GridItem>Item 6</GridItem>
+ </XDSGrid>
+ </div>
+ </XDSVStack>
+ ),
+};
+
+/** New API: responsive columns with auto-fill (consistent widths) */
+export const ResponsiveAutoFill: Story = {
render: () => (
<div {...stylex.props(styles.container)}>
<XDSText type="supporting" xstyle={styles.sectionLabel}>
- Resize the viewport - columns adjust automatically (min 200px per item)
+ Resize the viewport — columns auto-fill, empty tracks preserved (min
+ 200px per item)
</XDSText>
- <XDSGrid minChildWidth={200} gap={4}>
+ <XDSGrid columns={{minWidth: 200}} gap={4}>
<GridItem>Item 1</GridItem>
<GridItem>Item 2</GridItem>
<GridItem>Item 3</GridItem>
- <GridItem>Item 4</GridItem>
- <GridItem>Item 5</GridItem>
- <GridItem>Item 6</GridItem>
</XDSGrid>
</div>
),
};
+/** Side-by-side comparison: auto-fill vs auto-fit with few items */
+export const FillVsFitComparison: Story = {
+ render: () => (
+ <XDSVStack gap={6}>
+ <div {...stylex.props(styles.container)}>
+ <XDSText type="supporting" xstyle={styles.sectionLabel}>
+ auto-fill (default) — items stay consistent width, empty tracks
+ preserved
+ </XDSText>
+ <XDSGrid columns={{minWidth: 250}} gap={4}>
+ <GridItem>Item 1</GridItem>
+ <GridItem>Item 2</GridItem>
+ </XDSGrid>
+ </div>
+ <div {...stylex.props(styles.container)}>
+ <XDSText type="supporting" xstyle={styles.sectionLabel}>
+ auto-fit — items stretch to fill all available space
+ </XDSText>
+ <XDSGrid columns={{minWidth: 250, repeat: 'fit'}} gap={4}>
+ <GridItem>Item 1</GridItem>
+ <GridItem>Item 2</GridItem>
+ </XDSGrid>
+ </div>
+ </XDSVStack>
+ ),
+};
+
export const CappedResponsive: Story = {
render: () => (
<div {...stylex.props(styles.container)}>
<XDSText type="supporting" xstyle={styles.sectionLabel}>
- Auto-fit with max 3 columns (min 250px per item, capped via max-width)
+ Responsive with max 3 columns (min 250px per item, capped via
+ max-width)
</XDSText>
- <XDSGrid columns={3} minChildWidth={250} gap={4}>
+ <XDSGrid columns={{minWidth: 250, max: 3}} gap={4}>
<GridItem>Item 1</GridItem>
<GridItem>Item 2</GridItem>
<GridItem>Item 3</GridItem>
@@ -239,9 +297,9 @@ export const GalleryExample: Story = {
render: () => (
<XDSSection variant="wash">
<XDSText type="supporting" xstyle={styles.sectionLabel}>
- Gallery/Card Grid - Responsive with min 280px cards
+ Gallery/Card Grid — Responsive with min 280px cards (auto-fill)
</XDSText>
- <XDSGrid minChildWidth={280} gap={5}>
+ <XDSGrid columns={{minWidth: 280}} gap={5}>
{Array.from({length: 8}, (_, i) => (
<XDSCard key={i}>
<div {...stylex.props(styles.cardImage)} />
diff --git a/packages/core/src/Grid/Grid.doc.mjs b/packages/core/src/Grid/Grid.doc.mjs
index 2ee6865255..43f62cd95d 100644
--- a/packages/core/src/Grid/Grid.doc.mjs
+++ b/packages/core/src/Grid/Grid.doc.mjs
@@ -2,12 +2,13 @@
export const docs = {
name: 'Grid',
- keywords: ["grid","columns","responsive","auto-fit","masonry","tiles","row","col","simplegrid"],
+ keywords: ["grid","columns","responsive","auto-fill","auto-fit","masonry","tiles","row","col","simplegrid","responsive grid","card grid"],
usage: {
- description: 'A CSS Grid-based layout component with responsive auto-fit support. Use Grid for any multi-column layout instead of manual CSS grid — it handles gap tokens and responsive column behavior automatically.',
+ description:
+ 'CSS Grid-based layout with responsive column support. Use for any grid layout instead of manual CSS grid — it handles gap tokens and responsive behavior automatically.',
bestPractices: [
- { guidance: true, description: 'Use minChildWidth for responsive layouts that adapt to container size.' },
- { guidance: true, description: 'Combine minChildWidth and columns to set a maximum column count while still allowing responsive wrapping.' },
+ { guidance: true, description: 'Use `columns={{minWidth: 280}}` for responsive layouts that adapt to container size with consistent item widths.' },
+ { guidance: true, description: 'Use `columns={{minWidth: 280, max: 4}}` to set a maximum column count while still allowing responsive wrapping.' },
{ guidance: false, description: 'Write manual CSS grid styles when Grid already supports your layout — it ensures consistent spacing through design tokens.' },
],
},
@@ -20,18 +21,19 @@ export const docs = {
components: [
{
name: 'XDSGrid',
- description: 'Grid container with fixed or responsive auto-fit columns.',
+ description: 'Grid container with fixed or responsive columns.',
props: [
{
name: 'columns',
- type: 'number',
- description: 'Maximum number of columns.',
+ type: "number | {minWidth: number, max?: number, repeat?: 'fill' | 'fit'}",
+ description:
+ 'Column configuration. Use a number for fixed columns (e.g. `columns={3}`). Use an object for responsive columns: `minWidth` sets the minimum column width in px, `repeat` controls track behavior (`"fill"` preserves empty tracks for consistent widths, `"fit"` collapses empty tracks so items stretch; defaults to `"fill"`), and `max` caps the maximum number of columns.',
},
{
name: 'minChildWidth',
type: 'number',
description:
- 'Minimum item width in px; enables responsive auto-fit column behaviour.',
+ 'Deprecated — use `columns={{minWidth: 280}}` instead. Minimum item width in px; enables responsive auto-fit.',
},
{
name: 'width',
@@ -81,7 +83,8 @@ export const docs = {
description:
'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object like style={{}}.',
},
- ], },
+ ],
+ },
{
name: 'XDSGridSpan',
description: 'Grid item that spans multiple columns or rows.',
@@ -118,18 +121,18 @@ export const docsZh = {
components: [
{
name: 'XDSGrid',
- description: '支持固定列或响应式自动适配列的网格容器。',
+ description: '支持固定列或响应式列的网格容器。',
props: [
{
name: 'columns',
- type: 'number',
- description: '最大列数。',
+ type: "number | {minWidth: number, max?: number, repeat?: 'fill' | 'fit'}",
+ description:
+ '列配置。使用数字表示固定列(如 `columns={3}`)。使用对象表示响应式列:`minWidth` 设置最小列宽(px),`repeat` 控制轨道行为(`"fill"` 保留空轨道保持一致宽度,`"fit"` 折叠空轨道使项目拉伸;默认为 `"fill"`),`max` 限制最大列数。',
},
{
name: 'minChildWidth',
type: 'number',
- description:
- '项目的最小宽度(px);启用响应式自动适配列行为。',
+ description: '已弃用 — 请使用 `columns={{minWidth: 280}}` 代替。',
},
{
name: 'width',
@@ -204,33 +207,35 @@ export const docsZh = {
},
],
usage: {
- description: 'A CSS Grid-based layout component with responsive auto-fit support. Use Grid for any multi-column layout instead of manual CSS grid — it handles gap tokens and responsive column behavior automatically.',
+ description: '基于 CSS Grid 的布局组件,支持响应式列。',
bestPractices: [
- { guidance: true, description: 'Use minChildWidth for responsive layouts that adapt to container size.' },
- { guidance: true, description: 'Combine minChildWidth and columns to set a maximum column count while still allowing responsive wrapping.' },
- { guidance: false, description: 'Write manual CSS grid styles when Grid already supports your layout — it ensures consistent spacing through design tokens.' },
+ { guidance: true, description: '使用 \`columns={{minWidth: 280}}\` 实现自适应容器宽度的响应式布局。' },
+ { guidance: true, description: '使用 \`columns={{minWidth: 280, max: 4}}\` 限制最大列数。' },
+ { guidance: false, description: '当 Grid 已支持你的布局时,不要编写手动 CSS grid 样式。' },
],
},
};
/** @type {import('../docs-types').TranslationDoc} */
export const docsDense = {
- description: 'CSS Grid-based layout w/ responsive auto-fit support.',
+ description: 'CSS Grid-based layout w/ responsive column support.',
usage: {
- description: 'A CSS Grid-based layout component with responsive auto-fit support. Use Grid for any multi-column layout instead of manual CSS grid — it handles gap tokens and responsive column behavior automatically.',
+ description: 'CSS Grid-based layout with responsive column support. Use for any grid layout instead of manual CSS grid.',
bestPractices: [
- { guidance: true, description: 'Use minChildWidth for responsive layouts that adapt to container size.' },
- { guidance: true, description: 'Combine minChildWidth and columns to set a maximum column count while still allowing responsive wrapping.' },
- { guidance: false, description: 'Write manual CSS grid styles when Grid already supports your layout — it ensures consistent spacing through design tokens.' },
+ { guidance: true, description: 'Use columns={{minWidth: 280}} for responsive layouts with consistent widths.' },
+ { guidance: true, description: 'Use columns={{minWidth: 280, max: 4}} to cap columns while keeping responsive wrapping.' },
+ { guidance: false, description: 'Write manual CSS grid when Grid supports your layout.' },
],
},
+
+
components: [
{
name: 'XDSGrid',
- description: 'Grid container w/ fixed or responsive auto-fit columns.',
+ description: 'Grid container w/ fixed or responsive columns.',
propDescriptions: {
- columns: 'Max number of columns.',
- minChildWidth: 'Min item width in px; enables responsive auto-fit.',
+ columns: "Column config. Number for fixed cols. Object {minWidth, max?, repeat?} for responsive. repeat: 'fill' (default, consistent widths) or 'fit' (stretch).",
+ minChildWidth: 'Deprecated — use columns={{minWidth}} instead.',
width: 'Container width.',
height: 'Container height.',
gap: 'Spacing between all items.',
diff --git a/packages/core/src/Grid/XDSGrid.test.tsx b/packages/core/src/Grid/XDSGrid.test.tsx
index f61fcec611..33704d8a3b 100644
--- a/packages/core/src/Grid/XDSGrid.test.tsx
+++ b/packages/core/src/Grid/XDSGrid.test.tsx
@@ -26,22 +26,22 @@ describe('XDSGrid', () => {
expect(grid.style.gridTemplateColumns).toBe('repeat(3, 1fr)');
});
- it('renders with minChildWidth (auto-fit)', () => {
+ it('renders with columns object (auto-fill default)', () => {
render(
- <XDSGrid minChildWidth={250} data-testid="grid">
+ <XDSGrid columns={{minWidth: 250}} data-testid="grid">
<div>Item 1</div>
<div>Item 2</div>
</XDSGrid>,
);
const grid = screen.getByTestId('grid');
expect(grid.style.gridTemplateColumns).toBe(
- 'repeat(auto-fit, minmax(250px, 1fr))',
+ 'repeat(auto-fill, minmax(250px, 1fr))',
);
});
- it('renders with both columns and minChildWidth (capped)', () => {
+ it('renders with columns object max (capped)', () => {
render(
- <XDSGrid columns={3} minChildWidth={250} gap={4} data-testid="grid">
+ <XDSGrid columns={{minWidth: 250, max: 3}} gap={4} data-testid="grid">
<div>Item 1</div>
<div>Item 2</div>
<div>Item 3</div>
@@ -49,15 +49,15 @@ describe('XDSGrid', () => {
);
const grid = screen.getByTestId('grid');
expect(grid.style.gridTemplateColumns).toBe(
- 'repeat(auto-fit, minmax(250px, 1fr))',
+ 'repeat(auto-fill, minmax(250px, 1fr))',
);
// maxWidth = 3 * 250 + 2 * 16 = 750 + 32 = 782px
expect(grid.style.maxWidth).toBe('782px');
});
- it('renders with columns and minChildWidth using columnGap', () => {
+ it('renders with columns object max using columnGap', () => {
render(
- <XDSGrid columns={4} minChildWidth={200} 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>,
@@ -136,16 +136,15 @@ describe('XDSGrid', () => {
expect(grid.style.gridTemplateColumns).toBe('1fr');
});
- it('uses auto-fit without maxWidth cap when columns={0} with minChildWidth', () => {
+ it('uses auto-fill without maxWidth cap when no max specified', () => {
render(
- <XDSGrid columns={0} minChildWidth={200} data-testid="grid">
+ <XDSGrid columns={{minWidth: 200}} data-testid="grid">
<div>Item</div>
</XDSGrid>,
);
const grid = screen.getByTestId('grid');
- // minChildWidth drives auto-fit; columns={0} should not set a maxWidth cap
expect(grid.style.gridTemplateColumns).toBe(
- 'repeat(auto-fit, minmax(200px, 1fr))',
+ 'repeat(auto-fill, minmax(200px, 1fr))',
);
expect(grid.style.maxWidth).toBe('');
});
@@ -192,13 +191,12 @@ describe('XDSGrid', () => {
expect(grid.style.height).toBe('50vh');
});
- // --- P2: minChildWidth + columnGap interaction (hardening #719) ---
+ // --- P2: columns object + columnGap interaction (hardening #719) ---
it('calculates maxWidth using columnGap when both columnGap and gap are set', () => {
render(
<XDSGrid
- columns={3}
- minChildWidth={200}
+ columns={{minWidth: 200, max: 3}}
gap={2}
columnGap={6}
data-testid="grid">
@@ -213,7 +211,7 @@ describe('XDSGrid', () => {
it('calculates maxWidth using gap when columnGap is not set', () => {
render(
- <XDSGrid columns={2} minChildWidth={150} gap={3} data-testid="grid">
+ <XDSGrid columns={{minWidth: 150, max: 2}} gap={3} data-testid="grid">
<div>Item</div>
</XDSGrid>,
);
@@ -224,7 +222,7 @@ describe('XDSGrid', () => {
it('calculates maxWidth with zero gap when neither gap nor columnGap is set', () => {
render(
- <XDSGrid columns={3} minChildWidth={100} data-testid="grid">
+ <XDSGrid columns={{minWidth: 100, max: 3}} data-testid="grid">
<div>Item</div>
</XDSGrid>,
);
@@ -265,6 +263,81 @@ describe('XDSGrid', () => {
expect(screen.getByText('Item 2')).toBeInTheDocument();
expect(screen.getByText('Item 3')).toBeInTheDocument();
});
+
+ // --- columns object API ---
+
+ it('renders with columns={{minWidth}} using auto-fill', () => {
+ render(
+ <XDSGrid columns={{minWidth: 280}} data-testid="grid">
+ <div>Item 1</div>
+ <div>Item 2</div>
+ </XDSGrid>,
+ );
+ const grid = screen.getByTestId('grid');
+ expect(grid.style.gridTemplateColumns).toBe(
+ 'repeat(auto-fill, minmax(280px, 1fr))',
+ );
+ });
+
+ it('renders with columns={{minWidth, repeat: "fit"}} using auto-fit', () => {
+ render(
+ <XDSGrid columns={{minWidth: 280, repeat: 'fit'}} data-testid="grid">
+ <div>Item 1</div>
+ <div>Item 2</div>
+ </XDSGrid>,
+ );
+ const grid = screen.getByTestId('grid');
+ expect(grid.style.gridTemplateColumns).toBe(
+ 'repeat(auto-fit, minmax(280px, 1fr))',
+ );
+ });
+
+ it('renders with columns={{minWidth, repeat: "fill"}} using auto-fill', () => {
+ render(
+ <XDSGrid columns={{minWidth: 280, repeat: 'fill'}} data-testid="grid">
+ <div>Item 1</div>
+ <div>Item 2</div>
+ </XDSGrid>,
+ );
+ const grid = screen.getByTestId('grid');
+ expect(grid.style.gridTemplateColumns).toBe(
+ 'repeat(auto-fill, minmax(280px, 1fr))',
+ );
+ });
+
+ it('renders with columns={{minWidth, max}} capping via maxWidth', () => {
+ render(
+ <XDSGrid columns={{minWidth: 280, max: 3}} gap={4} data-testid="grid">
+ <div>Item 1</div>
+ <div>Item 2</div>
+ </XDSGrid>,
+ );
+ const grid = screen.getByTestId('grid');
+ expect(grid.style.gridTemplateColumns).toBe(
+ 'repeat(auto-fill, minmax(280px, 1fr))',
+ );
+ // maxWidth = 3 * 280 + 2 * 16 = 840 + 32 = 872px
+ expect(grid.style.maxWidth).toBe('872px');
+ });
+
+ it('renders with columns={{minWidth, max, repeat: "fit"}} using auto-fit + maxWidth', () => {
+ render(
+ <XDSGrid
+ columns={{minWidth: 280, max: 3, repeat: 'fit'}}
+ gap={4}
+ data-testid="grid">
+ <div>Item 1</div>
+ <div>Item 2</div>
+ </XDSGrid>,
+ );
+ const grid = screen.getByTestId('grid');
+ expect(grid.style.gridTemplateColumns).toBe(
+ 'repeat(auto-fit, minmax(280px, 1fr))',
+ );
+ // maxWidth = 3 * 280 + 2 * 16 = 840 + 32 = 872px
+ expect(grid.style.maxWidth).toBe('872px');
+ });
+
});
describe('XDSGridSpan', () => {
diff --git a/packages/core/src/Grid/XDSGrid.tsx b/packages/core/src/Grid/XDSGrid.tsx
index 2feb44e3ef..ea4b329f89 100644
--- a/packages/core/src/Grid/XDSGrid.tsx
+++ b/packages/core/src/Grid/XDSGrid.tsx
@@ -3,7 +3,7 @@
/**
* @file XDSGrid.tsx
* @input Uses React, stylex, spacing tokens
- * @output Exports XDSGrid component and XDSGridProps
+ * @output Exports XDSGrid component, XDSGridProps, and XDSGridColumns
* @position Grid component; provides CSS Grid-based layout
*
* SYNC: When modified, update these files to stay in sync:
@@ -28,22 +28,42 @@ import {xdsClassName, mergeProps} from '../utils';
export type GridAlignment = 'start' | 'center' | 'end' | 'stretch';
+/**
+ * Column configuration for XDSGrid.
+ *
+ * - `number` — fixed equal-width columns (e.g. `columns={3}`)
+ * - `object` — responsive columns based on minimum child width:
+ * - `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
+ */
+export type XDSGridColumns =
+ | number
+ | {
+ minWidth: number;
+ max?: number;
+ repeat?: 'fill' | 'fit';
+ };
+
export interface XDSGridProps extends XDSBaseProps<HTMLDivElement> {
/** Ref forwarded to the root element */
ref?: React.Ref<HTMLElement>;
/**
- * Maximum number of columns.
- * - When only columns is set: creates fixed equal-width columns
- * - When both columns and minChildWidth are set: caps the max columns
- * - When neither is set with minChildWidth: unlimited columns
+ * Column configuration.
+ * - `number` — fixed equal-width columns
+ * - `{minWidth, max?, repeat?}` — responsive columns
+ *
+ * @see XDSGridColumns
*/
- columns?: number;
+ columns?: XDSGridColumns;
/**
* Minimum width of each grid item in pixels.
- * Enables auto-fit responsive behavior where columns automatically
- * adjust based on available width.
- * @default 0 (disabled - uses fixed columns)
+ * Enables responsive auto-fit behavior.
+ *
+ * @deprecated Use `columns={{minWidth: 280}}` instead.
+ * @default 0 (disabled)
*/
minChildWidth?: number;
@@ -277,12 +297,12 @@ const spacingPixels: Record<SpacingStep, number> = {
};
/**
- * Calculate max-width when capping columns with minChildWidth.
- * maxWidth = columns * minChildWidth + (columns - 1) * gapPx
+ * Calculate max-width when capping columns.
+ * maxWidth = maxCols * minWidth + (maxCols - 1) * gapPx
*/
function calculateMaxWidth(
- columns: number,
- minChildWidth: number,
+ maxCols: number,
+ minWidth: number,
gap: SpacingStep | undefined,
columnGap: SpacingStep | undefined,
): number {
@@ -292,17 +312,17 @@ function calculateMaxWidth(
: gap != null
? spacingPixels[gap]
: 0;
- return columns * minChildWidth + (columns - 1) * gapPx;
+ return maxCols * minWidth + (maxCols - 1) * gapPx;
}
/**
* Grid component for CSS Grid-based layouts.
*
- * Supports both fixed-column and responsive auto-fit layouts.
- * The `columns` and `minChildWidth` props work together:
- * - columns only: Fixed equal-width columns
- * - minChildWidth only: Auto-fit responsive, unlimited columns
- * - Both: Auto-fit responsive, capped at max columns
+ * Supports fixed-column and responsive layouts via the `columns` prop:
+ * - `columns={3}` — fixed 3-column grid
+ * - `columns={{minWidth: 280}}` — responsive auto-fill (consistent widths)
+ * - `columns={{minWidth: 280, repeat: 'fit'}}` — responsive auto-fit (stretch)
+ * - `columns={{minWidth: 280, max: 4}}` — responsive, capped at 4 columns
*
* @example
* ```
@@ -334,20 +354,33 @@ export function XDSGrid({
let gridTemplateColumns: string;
let calculatedMaxWidth: number | undefined;
- if (minChildWidth > 0) {
- // Auto-fit mode: responsive columns
+ if (typeof columns === 'object' && columns != null) {
+ // New 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,
+ columns.minWidth,
+ gap,
+ columnGap,
+ );
+ }
+ } else if (minChildWidth > 0) {
+ // Deprecated path: minChildWidth uses auto-fit for backward compat
gridTemplateColumns = `repeat(auto-fit, minmax(${minChildWidth}px, 1fr))`;
- // If columns is also set, cap the max columns via max-width
- if (columns != null && columns > 0) {
+ const numColumns = typeof columns === 'number' ? columns : 0;
+ if (numColumns > 0) {
calculatedMaxWidth = calculateMaxWidth(
- columns,
+ numColumns,
minChildWidth,
gap,
columnGap,
);
}
- } else if (columns != null && columns > 0) {
+ } else if (typeof columns === 'number' && columns > 0) {
// Fixed columns mode
gridTemplateColumns = `repeat(${columns}, 1fr)`;
} else {
@@ -367,11 +400,19 @@ export function XDSGrid({
}),
};
+ // For xdsClassName, extract numeric columns value for variant tracking
+ const columnsVariant =
+ typeof columns === 'number'
+ ? columns
+ : typeof columns === 'object'
+ ? undefined
+ : undefined;
+
return (
<div
ref={ref as React.Ref<HTMLDivElement>}
{...mergeProps(
- xdsClassName('grid', {columns, gap, align, justify}),
+ xdsClassName('grid', {columns: columnsVariant, gap, align, justify}),
stylex.props(
baseStyles.grid,
gap != null && gapStyles[gap],
diff --git a/packages/core/src/Grid/index.ts b/packages/core/src/Grid/index.ts
index a5d6734f30..6149ce8a16 100644
--- a/packages/core/src/Grid/index.ts
+++ b/packages/core/src/Grid/index.ts
@@ -10,7 +10,7 @@
*/
export {XDSGrid} from './XDSGrid';
-export type {XDSGridProps, GridAlignment} from './XDSGrid';
+export type {XDSGridProps, XDSGridColumns, GridAlignment} from './XDSGrid';
export {XDSGridSpan} from './XDSGridSpan';
export type {XDSGridSpanProps} from './XDSGridSpan';