@astryxdesign/core 0.1.3 → 0.1.4-canary.01e5b29

package/src/FieldStatus/FieldStatus.test.tsx

@@ -0,0 +1,282 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file FieldStatus.test.tsx
+ * @input Uses vitest, @testing-library/react, FieldStatus component
+ * @output Characterization coverage for FieldStatus behavior
+ * @position Testing; validates FieldStatus.tsx implementation
+ *
+ * SYNC: When FieldStatus.tsx changes, update tests to match new behavior
+ */
+
+import {describe, it, expect, vi} from 'vitest';
+import {render, screen} from '@testing-library/react';
+import * as stylex from '@stylexjs/stylex';
+import {FieldStatus} from './FieldStatus';
+
+const testStyles = stylex.create({
+  custom: {color: 'rebeccapurple'},
+});
+
+describe('FieldStatus', () => {
+  it('renders the message text', () => {
+    render(<FieldStatus type="error" message="This field is required" />);
+    expect(screen.getByText('This field is required')).toBeInTheDocument();
+  });
+
+  it('renders the message inside a <div>', () => {
+    render(<FieldStatus type="error" message="Boom" data-testid="fs" />);
+    expect(screen.getByTestId('fs').tagName).toBe('DIV');
+  });
+
+  describe('role semantics', () => {
+    // Errors are urgent — they get role="alert" so assistive tech interrupts.
+    it('uses role="alert" for error status', () => {
+      render(<FieldStatus type="error" message="msg" />);
+      expect(screen.getByRole('alert')).toHaveTextContent('msg');
+    });
+
+    // Non-error statuses are advisory — role="status" is a polite live region.
+    it('uses role="status" for warning status', () => {
+      render(<FieldStatus type="warning" message="msg" data-testid="fs" />);
+      expect(screen.getByTestId('fs')).toHaveAttribute('role', 'status');
+      expect(screen.queryByRole('alert')).not.toBeInTheDocument();
+    });
+
+    it('uses role="status" for success status', () => {
+      render(<FieldStatus type="success" message="msg" data-testid="fs" />);
+      expect(screen.getByTestId('fs')).toHaveAttribute('role', 'status');
+    });
+  });
+
+  describe('aria-live politeness', () => {
+    // Error → assertive so screen readers announce immediately.
+    it('sets aria-live="assertive" for error', () => {
+      render(<FieldStatus type="error" message="msg" data-testid="fs" />);
+      expect(screen.getByTestId('fs')).toHaveAttribute(
+        'aria-live',
+        'assertive',
+      );
+    });
+
+    it('sets aria-live="polite" for warning', () => {
+      render(<FieldStatus type="warning" message="msg" data-testid="fs" />);
+      expect(screen.getByTestId('fs')).toHaveAttribute('aria-live', 'polite');
+    });
+
+    it('sets aria-live="polite" for success', () => {
+      render(<FieldStatus type="success" message="msg" data-testid="fs" />);
+      expect(screen.getByTestId('fs')).toHaveAttribute('aria-live', 'polite');
+    });
+
+    // The element is a live region, never hidden from assistive tech.
+    it('does not mark itself aria-hidden', () => {
+      render(<FieldStatus type="error" message="msg" data-testid="fs" />);
+      expect(screen.getByTestId('fs')).not.toHaveAttribute('aria-hidden');
+    });
+  });
+
+  describe('theme class + data attribute reflection', () => {
+    it('renders the stable astryx-field-status class', () => {
+      render(<FieldStatus type="error" message="msg" data-testid="fs" />);
+      expect(screen.getByTestId('fs')).toHaveClass('astryx-field-status');
+    });
+
+    it('reflects the type as a class token and data-type attribute', () => {
+      render(<FieldStatus type="warning" message="msg" data-testid="fs" />);
+      const el = screen.getByTestId('fs');
+      expect(el).toHaveClass('warning');
+      expect(el).toHaveAttribute('data-type', 'warning');
+    });
+
+    it('reflects the variant as a class token and data-variant attribute', () => {
+      render(
+        <FieldStatus
+          type="error"
+          message="msg"
+          variant="detached"
+          data-testid="fs"
+        />,
+      );
+      const el = screen.getByTestId('fs');
+      expect(el).toHaveClass('detached');
+      expect(el).toHaveAttribute('data-variant', 'detached');
+    });
+
+    it('defaults data-variant to "attached"', () => {
+      render(<FieldStatus type="error" message="msg" data-testid="fs" />);
+      const el = screen.getByTestId('fs');
+      expect(el).toHaveAttribute('data-variant', 'attached');
+      expect(el).toHaveClass('attached');
+    });
+  });
+
+  describe('color styling per status type', () => {
+    // Each status type maps to a distinct color treatment. The rendered class
+    // list must therefore differ between types — a regression that collapsed
+    // them onto one color would be caught here.
+    it('applies distinct StyleX classes for each type', () => {
+      const {rerender} = render(
+        <FieldStatus type="error" message="msg" data-testid="fs" />,
+      );
+      const errorClass = screen.getByTestId('fs').getAttribute('class');
+
+      rerender(<FieldStatus type="warning" message="msg" data-testid="fs" />);
+      const warningClass = screen.getByTestId('fs').getAttribute('class');
+
+      rerender(<FieldStatus type="success" message="msg" data-testid="fs" />);
+      const successClass = screen.getByTestId('fs').getAttribute('class');
+
+      expect(errorClass).not.toEqual(warningClass);
+      expect(warningClass).not.toEqual(successClass);
+      expect(errorClass).not.toEqual(successClass);
+    });
+
+    it('applies distinct StyleX classes for each variant', () => {
+      const {rerender} = render(
+        <FieldStatus
+          type="error"
+          message="msg"
+          variant="attached"
+          data-testid="fs"
+        />,
+      );
+      const attachedClass = screen.getByTestId('fs').getAttribute('class');
+
+      rerender(
+        <FieldStatus
+          type="error"
+          message="msg"
+          variant="detached"
+          data-testid="fs"
+        />,
+      );
+      const detachedClass = screen.getByTestId('fs').getAttribute('class');
+
+      expect(attachedClass).not.toEqual(detachedClass);
+    });
+  });
+
+  describe('prop forwarding', () => {
+    it('forwards a ref to the root element', () => {
+      const ref = vi.fn();
+      render(<FieldStatus ref={ref} type="error" message="msg" />);
+      expect(ref).toHaveBeenCalledWith(expect.any(HTMLDivElement));
+    });
+
+    it('applies the id attribute', () => {
+      render(
+        <FieldStatus
+          type="error"
+          message="msg"
+          id="email-error"
+          data-testid="fs"
+        />,
+      );
+      expect(screen.getByTestId('fs')).toHaveAttribute('id', 'email-error');
+    });
+
+    it('passes through arbitrary DOM props', () => {
+      render(
+        <FieldStatus
+          type="error"
+          message="msg"
+          data-testid="fs"
+          data-custom="xyz"
+        />,
+      );
+      expect(screen.getByTestId('fs')).toHaveAttribute('data-custom', 'xyz');
+    });
+
+    it('merges a consumer className with the stable class', () => {
+      render(
+        <FieldStatus
+          type="error"
+          message="msg"
+          className="my-status"
+          data-testid="fs"
+        />,
+      );
+      const el = screen.getByTestId('fs');
+      expect(el).toHaveClass('my-status');
+      expect(el).toHaveClass('astryx-field-status');
+    });
+
+    it('merges a consumer inline style', () => {
+      render(
+        <FieldStatus
+          type="error"
+          message="msg"
+          style={{marginTop: '10px'}}
+          data-testid="fs"
+        />,
+      );
+      expect(screen.getByTestId('fs')).toHaveStyle({marginTop: '10px'});
+    });
+
+    it('applies an xstyle as an extra class', () => {
+      const {rerender} = render(
+        <FieldStatus type="error" message="msg" data-testid="fs" />,
+      );
+      const withoutXstyle = screen.getByTestId('fs').getAttribute('class');
+
+      // xstyle values are compiled StyleX styles; passing one adds classes.
+      rerender(
+        <FieldStatus
+          type="error"
+          message="msg"
+          data-testid="fs"
+          xstyle={testStyles.custom}
+        />,
+      );
+      const withXstyle = screen.getByTestId('fs').getAttribute('class');
+      expect(withXstyle).not.toEqual(withoutXstyle);
+    });
+  });
+
+  describe('dynamic updates', () => {
+    it('updates the rendered message on rerender', () => {
+      const {rerender} = render(
+        <FieldStatus type="error" message="First" data-testid="fs" />,
+      );
+      expect(screen.getByTestId('fs')).toHaveTextContent('First');
+
+      rerender(<FieldStatus type="error" message="Second" data-testid="fs" />);
+      expect(screen.getByTestId('fs')).toHaveTextContent('Second');
+    });
+
+    // Switching from error to a non-error type must relax both the role and
+    // the live-region politeness in lockstep.
+    it('relaxes role and aria-live when type changes from error', () => {
+      const {rerender} = render(
+        <FieldStatus type="error" message="msg" data-testid="fs" />,
+      );
+      let el = screen.getByTestId('fs');
+      expect(el).toHaveAttribute('role', 'alert');
+      expect(el).toHaveAttribute('aria-live', 'assertive');
+
+      rerender(<FieldStatus type="success" message="msg" data-testid="fs" />);
+      el = screen.getByTestId('fs');
+      expect(el).toHaveAttribute('role', 'status');
+      expect(el).toHaveAttribute('aria-live', 'polite');
+    });
+  });
+
+  describe('edge cases', () => {
+    it('renders an empty message without crashing', () => {
+      render(<FieldStatus type="error" message="" data-testid="fs" />);
+      const el = screen.getByTestId('fs');
+      expect(el).toBeInTheDocument();
+      expect(el).toHaveTextContent('');
+    });
+
+    it('renders message content verbatim, including whitespace-only strings', () => {
+      render(<FieldStatus type="warning" message="   " data-testid="fs" />);
+      expect(screen.getByTestId('fs').textContent).toBe('   ');
+    });
+  });
+
+  it('exposes a displayName for devtools', () => {
+    expect(FieldStatus.displayName).toBe('FieldStatus');
+  });
+});

package/src/FileInput/FileInput.doc.mjs

@@ -92,7 +92,7 @@ export const docs = {
       name: 'disabledMessage',
       type: 'string',
       description:
-        'Explains why the input is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the trigger focusable via aria-disabled (opening the file picker stays blocked). Use this instead of wrapping a disabled FileInput in Tooltip — disabled controls swallow the hover events an external Tooltip needs.',
+        'Explains why the input is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the trigger focusable via aria-disabled (opening the file picker stays blocked). Use this instead of wrapping a disabled FileInput in Tooltip; disabled controls swallow the hover events an external Tooltip needs.',
     },
     {
       name: 'isLoading',

package/src/FormLayout/__snapshots__/FormLayout.test.tsx.snap

@@ -4,7 +4,6 @@ exports[`FormLayout > matches snapshot for horizontal direction 1`] = `
 <div
   class="astryx-form-layout horizontal FormLayout__styles.base xdt5ytf x18g69wz FormLayout__styles.horizontal xrvj5dj x1mt1orb xu6a5m6"
   data-direction="horizontal"
-  data-style-src="@astryxdesign/core:src/FormLayout/FormLayout.tsx:40; @astryxdesign/core:src/FormLayout/FormLayout.tsx:45"
   data-testid="layout"
 >
   <input
@@ -20,7 +19,6 @@ exports[`FormLayout > matches snapshot for horizontal-labels direction 1`] = `
 <div
   class="astryx-form-layout horizontal-labels FormLayout__styles.base xdt5ytf FormLayout__styles.horizontalLabels xrvj5dj x1pmbctz xlaq8a2 x7a106z xedohl4 x1rpgqan x1a1jff"
   data-direction="horizontal-labels"
-  data-style-src="@astryxdesign/core:src/FormLayout/FormLayout.tsx:40; @astryxdesign/core:src/FormLayout/FormLayout.tsx:50"
   data-testid="layout"
 >
   <label>
@@ -36,7 +34,6 @@ exports[`FormLayout > matches snapshot for vertical direction 1`] = `
 <div
   class="astryx-form-layout vertical FormLayout__styles.base x78zum5 xdt5ytf x18g69wz"
   data-direction="vertical"
-  data-style-src="@astryxdesign/core:src/FormLayout/FormLayout.tsx:40"
   data-testid="layout"
 >
   <input

package/src/Grid/Grid.doc.mjs

@@ -17,7 +17,7 @@ export const docs = {
       { guidance: true, description: 'Use `repeat: \'fill\'` (the default) for consistent item widths. Use `\'fit\'` when items should stretch to fill leftover space.' },
       { guidance: false, description: 'Write manual CSS grid; Grid handles spacing and responsive behavior for you.' },
       { guidance: false, description: 'Use `HStack` with wrapping for grids; use Grid instead.' },
-      { guidance: true, description: 'Track templates use CSS-variable indirection (not raw inline styles), so `xstyle` overrides of `gridTemplateColumns` — including inside `@media` queries — take effect.' },
+      { guidance: true, description: 'Track templates use CSS-variable indirection (not raw inline styles), so `xstyle` overrides of `gridTemplateColumns` (including inside `@media` queries) take effect.' },
     ],
   },
   theming: {
@@ -112,7 +112,7 @@ export const docsZh = {
       { guidance: true, description: 'Use `repeat: \'fill\'` (the default) for consistent item widths. Use `\'fit\'` when items should stretch to fill leftover space.' },
       { guidance: false, description: 'Write manual CSS grid; Grid handles spacing and responsive behavior for you.' },
       { guidance: false, description: 'Use `HStack` with wrapping for grids; use Grid instead.' },
-      { guidance: true, description: 'Track templates use CSS-variable indirection (not raw inline styles), so `xstyle` overrides of `gridTemplateColumns` — including inside `@media` queries — take effect.' },
+      { guidance: true, description: 'Track templates use CSS-variable indirection (not raw inline styles), so `xstyle` overrides of `gridTemplateColumns` (including inside `@media` queries) take effect.' },
     ],
   },
 };
@@ -128,7 +128,7 @@ export const docsDense = {
       { guidance: true, description: 'Use repeat: \'fill\' (the default) for consistent item widths. Use \'fit\' when items should stretch to fill leftover space.' },
       { guidance: false, description: 'Write manual CSS grid; Grid handles spacing and responsive behavior for you.' },
       { guidance: false, description: 'Use HStack with wrapping for grids; use Grid instead.' },
-      { guidance: true, description: 'track templates use CSS-var indirection, not inline styles — xstyle/@media overrides of gridTemplateColumns work.' },
+      { guidance: true, description: 'track templates use CSS-var indirection, not inline styles, so xstyle/@media overrides of gridTemplateColumns work.' },
     ],
   },
 };

package/src/Grid/Grid.test.tsx

@@ -65,7 +65,7 @@ describe('Grid', () => {
     expect(templateColumns(grid)).toBe('repeat(auto-fill, minmax(250px, 1fr))');
   });
 
-  it('renders with columns object max (capped via track-max)', () => {
+  it('renders with columns object max (count capped, tracks still fill)', () => {
     render(
       <Grid columns={{minWidth: 250, max: 3}} gap={4} data-testid="grid">
         <div>Item 1</div>
@@ -74,13 +74,37 @@ describe('Grid', () => {
       </Grid>,
     );
     const grid = screen.getByTestId('grid');
-    // Track max caps at (100% - 2 * gap) / 3 — no maxWidth on container
+    // Cap lives on the track MIN (min(100%, max(minWidth, perColumn))); the
+    // track MAX stays 1fr so present columns fill the row (a lone column on
+    // mobile stretches to 100% instead of leaving dead space).
     expect(templateColumns(grid)).toBe(
-      'repeat(auto-fill, minmax(250px, calc((100% - 2 * var(--spacing-4)) / 3)))',
+      'repeat(auto-fill, minmax(min(100%, max(250px, calc((100% - 2 * var(--spacing-4)) / 3))), 1fr))',
     );
     expect(grid.style.maxWidth).toBe('');
   });
 
+  it('keeps track max at 1fr with a max cap so a lone column can fill (#3391)', () => {
+    // Regression: previously the cap was applied to the track MAX
+    // (minmax(minWidth, 100%/max)), so when fewer than `max` columns fit —
+    // e.g. a single column on mobile — the lone column was pinned to ~100%/max
+    // and left dead space on the right. The cap now lives on the track MIN and
+    // the track MAX stays 1fr, so present columns always stretch to fill.
+    render(
+      <Grid columns={{minWidth: 360, max: 2}} gap={4} data-testid="grid">
+        <div>Left</div>
+        <div>Right</div>
+      </Grid>,
+    );
+    const grid = screen.getByTestId('grid');
+    const template = templateColumns(grid);
+    // Track max must be 1fr (fills), not a fraction-of-container cap.
+    expect(template).toMatch(/, 1fr\)\)$/);
+    expect(template).not.toMatch(/, calc\([^)]*\/ 2\)\)\)$/);
+    expect(template).toBe(
+      'repeat(auto-fill, minmax(min(100%, max(360px, calc((100% - 1 * var(--spacing-4)) / 2))), 1fr))',
+    );
+  });
+
   it('renders with columns object max using columnGap', () => {
     render(
       <Grid columns={{minWidth: 200, max: 4}} columnGap={6} data-testid="grid">
@@ -89,9 +113,9 @@ describe('Grid', () => {
       </Grid>,
     );
     const grid = screen.getByTestId('grid');
-    // columnGap takes precedence for track-max calculation
+    // columnGap takes precedence in the perColumn floor calculation
     expect(templateColumns(grid)).toBe(
-      'repeat(auto-fill, minmax(200px, calc((100% - 3 * var(--spacing-6)) / 4)))',
+      'repeat(auto-fill, minmax(min(100%, max(200px, calc((100% - 3 * var(--spacing-6)) / 4))), 1fr))',
     );
     expect(grid.style.maxWidth).toBe('');
   });
@@ -165,7 +189,7 @@ describe('Grid', () => {
     expect(templateColumns(grid)).toBe('1fr');
   });
 
-  it('uses auto-fill without track-max cap when no max specified', () => {
+  it('uses auto-fill with a plain 1fr track when no max specified', () => {
     render(
       <Grid columns={{minWidth: 200}} data-testid="grid">
         <div>Item</div>
@@ -220,7 +244,7 @@ describe('Grid', () => {
 
   // --- P2: columns object + columnGap interaction (hardening #719) ---
 
-  it('uses columnGap var in track-max when both columnGap and gap are set', () => {
+  it('uses columnGap var in the count-cap floor when both columnGap and gap are set', () => {
     render(
       <Grid
         columns={{minWidth: 200, max: 3}}
@@ -231,14 +255,14 @@ describe('Grid', () => {
       </Grid>,
     );
     const grid = screen.getByTestId('grid');
-    // columnGap takes precedence over gap in track-max
+    // columnGap takes precedence over gap in the perColumn floor
     expect(templateColumns(grid)).toBe(
-      'repeat(auto-fill, minmax(200px, calc((100% - 2 * var(--spacing-6)) / 3)))',
+      'repeat(auto-fill, minmax(min(100%, max(200px, calc((100% - 2 * var(--spacing-6)) / 3))), 1fr))',
     );
     expect(grid.style.maxWidth).toBe('');
   });
 
-  it('uses gap var in track-max when columnGap is not set', () => {
+  it('uses gap var in the count-cap floor when columnGap is not set', () => {
     render(
       <Grid columns={{minWidth: 150, max: 2}} gap={3} data-testid="grid">
         <div>Item</div>
@@ -246,12 +270,12 @@ describe('Grid', () => {
     );
     const grid = screen.getByTestId('grid');
     expect(templateColumns(grid)).toBe(
-      'repeat(auto-fill, minmax(150px, calc((100% - 1 * var(--spacing-3)) / 2)))',
+      'repeat(auto-fill, minmax(min(100%, max(150px, calc((100% - 1 * var(--spacing-3)) / 2))), 1fr))',
     );
     expect(grid.style.maxWidth).toBe('');
   });
 
-  it('uses simple fraction in track-max when no gap is set', () => {
+  it('uses simple fraction in the count-cap floor when no gap is set', () => {
     render(
       <Grid columns={{minWidth: 100, max: 3}} data-testid="grid">
         <div>Item</div>
@@ -259,7 +283,7 @@ describe('Grid', () => {
     );
     const grid = screen.getByTestId('grid');
     expect(templateColumns(grid)).toBe(
-      'repeat(auto-fill, minmax(100px, calc(100% / 3)))',
+      'repeat(auto-fill, minmax(min(100%, max(100px, calc(100% / 3))), 1fr))',
     );
     expect(grid.style.maxWidth).toBe('');
   });
@@ -332,7 +356,7 @@ describe('Grid', () => {
     expect(templateColumns(grid)).toBe('repeat(auto-fill, minmax(280px, 1fr))');
   });
 
-  it('renders with columns={{minWidth, max}} capping via track-max', () => {
+  it('renders with columns={{minWidth, max}} capping the count while filling', () => {
     render(
       <Grid columns={{minWidth: 280, max: 3}} gap={4} data-testid="grid">
         <div>Item 1</div>
@@ -340,14 +364,15 @@ describe('Grid', () => {
       </Grid>,
     );
     const grid = screen.getByTestId('grid');
-    // Track-max limits columns — grid stays full width
+    // Count is capped via the track MIN; track MAX stays 1fr so present
+    // columns fill the row (grid stays full width).
     expect(templateColumns(grid)).toBe(
-      'repeat(auto-fill, minmax(280px, calc((100% - 2 * var(--spacing-4)) / 3)))',
+      'repeat(auto-fill, minmax(min(100%, max(280px, calc((100% - 2 * var(--spacing-4)) / 3))), 1fr))',
     );
     expect(grid.style.maxWidth).toBe('');
   });
 
-  it('renders with columns={{minWidth, max, repeat: "fit"}} using auto-fit + track-max', () => {
+  it('renders with columns={{minWidth, max, repeat: "fit"}} using auto-fit + count cap', () => {
     render(
       <Grid
         columns={{minWidth: 280, max: 3, repeat: 'fit'}}
@@ -359,7 +384,7 @@ describe('Grid', () => {
     );
     const grid = screen.getByTestId('grid');
     expect(templateColumns(grid)).toBe(
-      'repeat(auto-fit, minmax(280px, calc((100% - 2 * var(--spacing-4)) / 3)))',
+      'repeat(auto-fit, minmax(min(100%, max(280px, calc((100% - 2 * var(--spacing-4)) / 3))), 1fr))',
     );
     expect(grid.style.maxWidth).toBe('');
   });

package/src/Grid/Grid.tsx

@@ -38,9 +38,10 @@ 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 by limiting track max size.
- *     The grid stretches to 100% of its parent; `max` only limits how many
- *     columns appear.
+ *   - `max` — caps the maximum number of columns. The grid stretches to 100%
+ *     of its parent and the columns that are present always fill the row, so a
+ *     layout collapsing to a single column on mobile stretches to full width
+ *     (no dead space on the right).
  */
 export type GridColumns =
   | number
@@ -321,9 +322,20 @@ const spacingVarNames: Record<SpacingStep, string> = {
 };
 
 /**
- * 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.
+ * Build a grid-template-columns value that caps the column *count* at `max`
+ * while still letting the columns that are actually present stretch to fill
+ * the row.
+ *
+ * The cap lives on the track's **min** size, not its max: each track is at
+ * least `perColumn = (100% - (max-1) * gap) / max`, so more than `max` columns
+ * can never fit. The track **max** stays `1fr`, so whenever fewer than `max`
+ * columns fit (most importantly a lone column on mobile) they still grow to
+ * fill the whole row — no dead space on the right.
+ *
+ * The track min is `max(minWidth, perColumn)` so an explicit `minWidth` is
+ * still honored, wrapped in `min(100%, …)` so a single column on a viewport
+ * narrower than `minWidth`/`perColumn` shrinks to the container instead of
+ * overflowing it.
  */
 function buildCappedTemplate(
   minWidth: number,
@@ -339,12 +351,17 @@ function buildCappedTemplate(
         ? spacingVarNames[gap]
         : null;
 
-  // trackMax = (100% - (maxCols - 1) * gap) / maxCols
-  const trackMax = gapVar
+  // perColumn = (100% - (maxCols - 1) * gap) / maxCols — the width a track
+  // would have if exactly `maxCols` columns were present. Used as a floor so
+  // the grid never fits more than `maxCols` columns.
+  const perColumn = gapVar
     ? `calc((100% - ${maxCols - 1} * var(${gapVar})) / ${maxCols})`
     : `calc(100% / ${maxCols})`;
 
-  return `repeat(${repeatMode}, minmax(${minWidth}px, ${trackMax}))`;
+  // Track min caps the count; track max stays 1fr so present columns fill.
+  const trackMin = `min(100%, max(${minWidth}px, ${perColumn}))`;
+
+  return `repeat(${repeatMode}, minmax(${trackMin}, 1fr))`;
 }
 
 /**