@boostdev/design-system-components 2.2.1 → 2.4.0

package/dist/web-components/index.d.ts

@@ -55,6 +55,12 @@ type GridVariant = 'main' | 'page' | 'funnel' | 'custom';
  *   auto-span-media — boolean; child `<bds-grid-item>`s without a `column-span`
  *                     attribute resolve their span from the intrinsic aspect
  *                     ratio of their first `<img>`/`<video>` child.
+ *   masonry-preferred-column-span — named span or number; masonry only. Child
+ *                     items without a `column-span` attribute try to span this
+ *                     value (e.g. `"half"`, `"one-third"`). Named values adapt
+ *                     across breakpoints via the foundation's responsive column
+ *                     tokens. An item at row-end is demoted to the remaining
+ *                     column count. Numeric values are literal and don't adapt.
  *
  * Slots:
  *   (default) — grid content; typically `<bds-grid-item>` children
@@ -85,12 +91,18 @@ declare class BdsGrid extends LitElement {
             attribute: string;
             reflect: boolean;
         };
+        masonryPreferredColumnSpan: {
+            type: StringConstructor;
+            attribute: string;
+            reflect: boolean;
+        };
     };
     variant: GridVariant;
     columns: number | undefined;
     isCentered: boolean;
     isMasonry: boolean;
     autoSpanMedia: boolean;
+    masonryPreferredColumnSpan: string | undefined;
     private _ro?;
     private _mo?;
     private _frame;
@@ -101,6 +113,7 @@ declare class BdsGrid extends LitElement {
     private _items;
     private _setupMasonry;
     private _scheduleMasonry;
+    private _resolvePreferredColumnSpan;
     private _teardownMasonry;
     render(): lit.TemplateResult<1>;
 }

package/dist/web-components/index.js

@@ -128,17 +128,42 @@ import {
 
 // src/components/layout/Grid/masonry.ts
 import { useLayoutEffect } from "react";
+var NAMED_SPAN_VAR = {
+  "three-quarters": "--bds-grid_columns-75",
+  "two-thirds": "--bds-grid_columns-66",
+  half: "--bds-grid_columns-50",
+  "one-third": "--bds-grid_columns-33",
+  "one-quarter": "--bds-grid_columns-25"
+};
+var NAMED_SPAN_FRACTION = {
+  "three-quarters": 0.75,
+  "two-thirds": 2 / 3,
+  half: 0.5,
+  "one-third": 1 / 3,
+  "one-quarter": 0.25
+};
+function resolvePreferredColumns(container, value, totalCols) {
+  if (value === "full") return totalCols;
+  if (typeof value === "number") return Math.max(1, Math.min(totalCols, value));
+  const varName = NAMED_SPAN_VAR[value];
+  const raw = window.getComputedStyle(container).getPropertyValue(varName).trim();
+  const n = parseInt(raw, 10);
+  if (Number.isFinite(n) && n > 0) return Math.min(totalCols, n);
+  return Math.max(1, Math.round(totalCols * NAMED_SPAN_FRACTION[value]));
+}
 var ROW_UNIT_PX = 1;
 function supportsNativeMasonry() {
   if (typeof CSS === "undefined" || typeof CSS.supports !== "function") return false;
   return CSS.supports("display", "grid-lanes") || CSS.supports("grid-template-rows", "masonry");
 }
-function applyMasonryLayout(container, rawChildren) {
+var ORIGINAL_COL_ATTR = "data-bds-masonry-original-column";
+function applyMasonryLayout(container, rawChildren, options = {}) {
   const cs = window.getComputedStyle(container);
   const targetGap = parseFloat(cs.columnGap) || 0;
   container.style.gridAutoRows = `${ROW_UNIT_PX}px`;
   container.style.rowGap = "0px";
   container.style.gridAutoFlow = "dense";
+  container.style.overflowAnchor = "none";
   const children = rawChildren.filter(
     (el) => el.nodeType === 1 && window.getComputedStyle(el).display !== "none"
   );
@@ -148,24 +173,76 @@ function applyMasonryLayout(container, rawChildren) {
     child.style.gridRowEnd = "";
     child.style.alignSelf = "start";
   }
+  const preferred = options.preferredColumnSpan;
+  if (preferred !== void 0) {
+    const totalCols = countGridColumns(container);
+    const preferredCols = totalCols > 0 ? resolvePreferredColumns(container, preferred, totalCols) : 0;
+    if (totalCols > 0 && preferredCols > 0) {
+      let col = 0;
+      for (const child of children) {
+        if (child.hasAttribute("data-column-span-auto")) {
+          if (!child.hasAttribute(ORIGINAL_COL_ATTR)) {
+            child.setAttribute(ORIGINAL_COL_ATTR, child.style.gridColumn);
+          }
+          const remaining = totalCols - col;
+          const span = Math.max(1, Math.min(preferredCols, remaining));
+          child.style.gridColumn = `span ${span}`;
+          col = (col + span) % totalCols;
+        } else {
+          const consumed = Math.min(totalCols, readExplicitSpan(child, totalCols));
+          col = (col + consumed) % totalCols;
+        }
+      }
+    }
+  } else {
+    for (const child of children) {
+      restoreOriginalColumn(child);
+    }
+  }
   const heights = children.map((child) => child.offsetHeight);
   for (let i3 = 0; i3 < children.length; i3++) {
     const span = Math.max(1, Math.ceil(heights[i3] + targetGap));
     children[i3].style.gridRowEnd = `span ${span}`;
   }
 }
+function countGridColumns(container) {
+  const value = window.getComputedStyle(container).gridTemplateColumns.trim();
+  if (!value || value === "none") return 0;
+  return value.split(/\s+/).length;
+}
+function readExplicitSpan(el, totalCols) {
+  const inline = el.style.gridColumn || el.style.gridColumnEnd;
+  const fromInline = parseSpan(inline, totalCols);
+  if (fromInline !== null) return fromInline;
+  const computed = window.getComputedStyle(el).gridColumn;
+  return parseSpan(computed, totalCols) ?? 1;
+}
+function parseSpan(value, totalCols) {
+  if (!value) return null;
+  const match = value.match(/^\s*span\s+(\d+)/);
+  if (match) return Math.max(1, Math.min(totalCols, parseInt(match[1], 10)));
+  if (/\/\s*-1\b/.test(value)) return totalCols;
+  return null;
+}
 function clearMasonryLayout(container, rawChildren) {
   container.style.gridAutoRows = "";
   container.style.gridAutoFlow = "";
   container.style.rowGap = "";
+  container.style.overflowAnchor = "";
   for (const child of rawChildren) {
     if (child.nodeType !== 1) continue;
     child.style.gridRow = "";
     child.style.gridRowStart = "";
     child.style.gridRowEnd = "";
     child.style.alignSelf = "";
+    restoreOriginalColumn(child);
   }
 }
+function restoreOriginalColumn(el) {
+  if (!el.hasAttribute(ORIGINAL_COL_ATTR)) return;
+  el.style.gridColumn = el.getAttribute(ORIGINAL_COL_ATTR) ?? "";
+  el.removeAttribute(ORIGINAL_COL_ATTR);
+}
 
 // src/web-components/layout/bds-grid.ts
 var BdsGrid = class extends i2 {
@@ -222,7 +299,12 @@ var BdsGrid = class extends i2 {
     columns: { type: Number, reflect: true },
     isCentered: { type: Boolean, attribute: "is-centered", reflect: true },
     isMasonry: { type: Boolean, attribute: "is-masonry", reflect: true },
-    autoSpanMedia: { type: Boolean, attribute: "auto-span-media", reflect: true }
+    autoSpanMedia: { type: Boolean, attribute: "auto-span-media", reflect: true },
+    masonryPreferredColumnSpan: {
+      type: String,
+      attribute: "masonry-preferred-column-span",
+      reflect: true
+    }
   };
   _ro;
   _mo;
@@ -234,6 +316,7 @@ var BdsGrid = class extends i2 {
     this.isCentered = false;
     this.isMasonry = false;
     this.autoSpanMedia = false;
+    this.masonryPreferredColumnSpan = void 0;
   }
   disconnectedCallback() {
     super.disconnectedCallback();
@@ -273,9 +356,20 @@ var BdsGrid = class extends i2 {
     cancelAnimationFrame(this._frame);
     this._frame = requestAnimationFrame(() => {
       const container = this._gridEl();
-      if (container) applyMasonryLayout(container, this._items());
+      if (container) {
+        applyMasonryLayout(container, this._items(), {
+          preferredColumnSpan: this._resolvePreferredColumnSpan()
+        });
+      }
     });
   }
+  _resolvePreferredColumnSpan() {
+    const raw = this.masonryPreferredColumnSpan;
+    if (raw === void 0 || raw === null || raw === "") return void 0;
+    const n = Number(raw);
+    if (Number.isFinite(n) && String(n) === raw) return n;
+    return raw;
+  }
   _teardownMasonry() {
     cancelAnimationFrame(this._frame);
     this._ro?.disconnect();
@@ -430,6 +524,9 @@ var BdsGridItem = class extends i2 {
     const gridColumn = hasExplicitRange ? `${this.startColumn ?? "auto"} / ${this.endColumn ?? "auto"}` : resolveSpan(resolved);
     this.style.gridColumn = gridColumn;
     this.style.gridRow = this.rowSpan !== void 0 ? `span ${this.rowSpan}` : "";
+    const isColumnSpanAuto = (this.columnSpan === void 0 || this.columnSpan === null) && !hasExplicitRange;
+    if (isColumnSpanAuto) this.setAttribute("data-column-span-auto", "");
+    else this.removeAttribute("data-column-span-auto");
   }
   render() {
     return T`<slot></slot>`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boostdev/design-system-components",
-  "version": "2.2.1",
+  "version": "2.4.0",
   "description": "BoostDev React component library: accessible, token-driven components built on @boostdev/design-system-foundation",
   "keywords": [
     "React",

package/src/components/layout/Grid/Grid.mdx

@@ -201,6 +201,42 @@ Intrinsic dimensions are read from `img.naturalWidth/naturalHeight` and `video.v
 - Event subscriptions are `{ once: true }` so there's no cleanup ceremony per item.
 - Re-resolution cost is bounded by the number of items whose media changes, not the total item count.
 
+## Masonry preferred column span
+
+For a uniform "cards mostly half-width" feed, set `masonryPreferredColumnSpan` on the `Grid`. Items without an explicit `columnSpan` try to span that named fraction of the row. When an item would sit at the end of a row with fewer columns remaining than the preferred span, the polyfill **demotes** its span to just fill the remaining columns — the item never wraps to a new row leaving a visible gap behind it.
+
+```tsx
+<Grid isMasonry masonryPreferredColumnSpan="half">
+  {cards.map((c) => (
+    <GridItem key={c.id}>…</GridItem>
+  ))}
+</Grid>
+```
+
+The accepted values match `columnSpan` on `GridItem`: `'full'`, `'three-quarters'`, `'two-thirds'`, `'half'`, `'one-third'`, `'one-quarter'`. Named values resolve through the foundation's responsive column tokens, so the same option adapts across breakpoints — `"half"` yields 2 cols on a 4-col mobile grid, 4 cols on an 8-col tablet grid, and 6 cols on a 12-col desktop grid. A `number` is accepted too, but is a literal column count and does **not** adapt — prefer named values unless you're using `variant="custom"`.
+
+Rules:
+
+- Requires `isMasonry`. No-op on non-masonry grids.
+- Items with an explicit `columnSpan` (named or numeric) keep their span. Their columns still consume the demotion budget, so a `columnSpan="three-quarters"` followed by an auto item in a 4-column grid correctly demotes the auto item to 1.
+- Items with `startColumn` / `endColumn` are unaffected.
+- Responsive: the polyfill reads the live column count at the current viewport width, so the same grid can be 2+2 on wide screens and 1+1+1+1 on mobile without any media-query wiring.
+
+### When NOT to use
+
+- When span should reflect **content importance** or media shape — set `columnSpan` per item instead. `masonryPreferredColumnSpan` enforces a uniform visual rhythm and is the wrong tool for heterogeneous cards.
+- Alongside `autoSpanMedia` on the same grid. Both features target items without an explicit `columnSpan`, and `masonryPreferredColumnSpan` wins — `autoSpanMedia` silently does nothing. Pick one strategy per grid.
+- In a non-masonry grid. The feature depends on the polyfill's packing pass and is a no-op otherwise — use a plain `columnSpan` default instead.
+
+### Performance
+
+- One extra `getComputedStyle(container).gridTemplateColumns` read per masonry layout pass to count columns; the demotion pass itself is a single O(n) walk over auto items.
+- Shares the polyfill's existing `ResizeObserver` + `MutationObserver` + `requestAnimationFrame` coalescing — no new observers, no separate render.
+
+### SSR / hydration
+
+Column detection runs inside the masonry polyfill's `useLayoutEffect`, so it only executes on the client after mount. The initial server render emits each auto item at its default `full` span until hydration resolves the first polyfill pass — which matches the existing masonry SSR behavior.
+
 ## Migration from `@greenchoice/design-system`
 
 | Greenchoice                     | BoostDev equivalent                    |

package/src/components/layout/Grid/Grid.spec.tsx

@@ -101,6 +101,23 @@ describe('applyMasonryLayout', () => {
     expect(container.style.rowGap).toBe('0px');
   });
 
+  it('sets overflow-anchor: none on the container to prevent scroll-anchor jitter', () => {
+    // Regression: `grid-auto-flow: dense` + per-child ResizeObserver caused
+    // scroll anchoring to yank the viewport up when an item above the fold resized
+    // (scrollbar toggle, late image decode). Opting the container out makes the
+    // browser anchor against content outside the grid instead.
+    const container = makeContainer(10);
+    applyMasonryLayout(container, []);
+    expect(container.style.overflowAnchor).toBe('none');
+  });
+
+  it('clearMasonryLayout restores overflow-anchor', () => {
+    const container = makeContainer(10);
+    applyMasonryLayout(container, []);
+    clearMasonryLayout(container, []);
+    expect(container.style.overflowAnchor).toBe('');
+  });
+
   it('assigns grid-row-end: span ceil(height + targetGap) to each item', () => {
     const container = makeContainer(10);
     const a = makeItem(100);
@@ -170,6 +187,111 @@ describe('applyMasonryLayout', () => {
     expect(item.style.gridRow).toBe('');
     expect(item.style.alignSelf).toBe('');
   });
+
+  describe('preferredColumnSpan', () => {
+    function makeAutoItem(height: number) {
+      const el = makeItem(height);
+      el.setAttribute('data-column-span-auto', '');
+      return el;
+    }
+
+    it('assigns the preferred span to data-column-span-auto items that fit', () => {
+      // 'half' in a 4-col grid → 2 cols (via fraction fallback; jsdom has no foundation CSS).
+      const container = makeContainer(10);
+      container.style.gridTemplateColumns = '100px 100px 100px 100px';
+      const a = makeAutoItem(50);
+      const b = makeAutoItem(50);
+      container.append(a, b);
+      applyMasonryLayout(container, [a, b], { preferredColumnSpan: 'half' });
+      expect(a.style.gridColumn).toBe('span 2');
+      expect(b.style.gridColumn).toBe('span 2');
+    });
+
+    it('demotes the span at row end instead of wrapping with a gap', () => {
+      const container = makeContainer(10);
+      container.style.gridTemplateColumns = '100px 100px 100px';
+      const a = makeAutoItem(50);
+      const b = makeAutoItem(50);
+      container.append(a, b);
+      // 'two-thirds' in a 3-col grid → 2 cols.
+      applyMasonryLayout(container, [a, b], { preferredColumnSpan: 'two-thirds' });
+      expect(a.style.gridColumn).toBe('span 2');
+      // Only 1 col remains after `a` — `b` gets demoted.
+      expect(b.style.gridColumn).toBe('span 1');
+    });
+
+    it('leaves items with an explicit span untouched and consumes their columns for the demotion budget', () => {
+      const container = makeContainer(10);
+      container.style.gridTemplateColumns = '100px 100px 100px 100px';
+      const explicit = makeItem(50);
+      explicit.style.gridColumn = 'span 3';
+      const auto = makeAutoItem(50);
+      container.append(explicit, auto);
+      applyMasonryLayout(container, [explicit, auto], { preferredColumnSpan: 'half' });
+      expect(explicit.style.gridColumn).toBe('span 3');
+      // 3 cols consumed, 1 remains → auto demoted.
+      expect(auto.style.gridColumn).toBe('span 1');
+    });
+
+    it('is a no-op without preferredColumnSpan', () => {
+      const container = makeContainer(10);
+      container.style.gridTemplateColumns = '100px 100px';
+      const a = makeAutoItem(50);
+      container.append(a);
+      applyMasonryLayout(container, [a]);
+      expect(a.style.gridColumn).toBe('');
+    });
+
+    it('resolves named spans through foundation CSS vars when present', () => {
+      const container = makeContainer(10);
+      container.style.gridTemplateColumns = '100px 100px 100px 100px 100px 100px 100px 100px';
+      // Override the foundation var to a non-fractional value to prove we read it.
+      container.style.setProperty('--bds-grid_columns-50', '5');
+      const a = makeAutoItem(50);
+      container.append(a);
+      applyMasonryLayout(container, [a], { preferredColumnSpan: 'half' });
+      expect(a.style.gridColumn).toBe('span 5');
+    });
+
+    it('accepts numeric preferredColumnSpan as a literal column count', () => {
+      const container = makeContainer(10);
+      container.style.gridTemplateColumns = '100px 100px 100px 100px';
+      const a = makeAutoItem(50);
+      const b = makeAutoItem(50);
+      container.append(a, b);
+      applyMasonryLayout(container, [a, b], { preferredColumnSpan: 1 });
+      expect(a.style.gridColumn).toBe('span 1');
+      expect(b.style.gridColumn).toBe('span 1');
+    });
+
+    it('restores the original gridColumn when preferredColumnSpan is removed', () => {
+      // Simulates a Storybook control going preferred='half' → undefined.
+      // Without restore, items would stay pinned at `span 2`.
+      const container = makeContainer(10);
+      container.style.gridTemplateColumns = '100px 100px 100px 100px';
+      const a = makeAutoItem(50);
+      a.style.gridColumn = 'var(--bds-grid_span-100)';
+      container.append(a);
+      applyMasonryLayout(container, [a], { preferredColumnSpan: 'half' });
+      expect(a.style.gridColumn).toBe('span 2');
+      applyMasonryLayout(container, [a]); // preferredColumnSpan dropped
+      expect(a.style.gridColumn).toBe('var(--bds-grid_span-100)');
+    });
+
+    it('clearMasonryLayout restores gridColumn on data-column-span-auto items', () => {
+      const container = makeContainer(10);
+      container.style.gridTemplateColumns = '100px 100px 100px 100px';
+      const auto = makeAutoItem(50);
+      auto.style.gridColumn = 'var(--bds-grid_span-100)';
+      const explicit = makeItem(50);
+      explicit.style.gridColumn = 'span 2';
+      container.append(auto, explicit);
+      applyMasonryLayout(container, [auto, explicit], { preferredColumnSpan: 'half' });
+      clearMasonryLayout(container, [auto, explicit]);
+      expect(auto.style.gridColumn).toBe('var(--bds-grid_span-100)');
+      expect(explicit.style.gridColumn).toBe('span 2');
+    });
+  });
 });
 
 describe('GridItem', () => {
@@ -220,6 +342,21 @@ describe('GridItem', () => {
     const { container } = render(<GridItem as="article">x</GridItem>);
     expect(container.firstChild?.nodeName).toBe('ARTICLE');
   });
+
+  it('marks data-column-span-auto when columnSpan is not provided', () => {
+    const { container } = render(<GridItem>x</GridItem>);
+    expect((container.firstChild as HTMLElement).hasAttribute('data-column-span-auto')).toBe(true);
+  });
+
+  it('does not mark data-column-span-auto when columnSpan is set', () => {
+    const { container } = render(<GridItem columnSpan="half">x</GridItem>);
+    expect((container.firstChild as HTMLElement).hasAttribute('data-column-span-auto')).toBe(false);
+  });
+
+  it('does not mark data-column-span-auto when startColumn or endColumn is set', () => {
+    const { container } = render(<GridItem startColumn={2} endColumn={4}>x</GridItem>);
+    expect((container.firstChild as HTMLElement).hasAttribute('data-column-span-auto')).toBe(false);
+  });
 });
 
 describe('aspectToColumnSpan', () => {

package/src/components/layout/Grid/Grid.stories.tsx

@@ -10,6 +10,10 @@ const meta = {
     columns: { control: 'number' },
     isCentered: { control: 'boolean' },
     isMasonry: { control: 'boolean' },
+    masonryPreferredColumnSpan: {
+      control: 'select',
+      options: ['full', 'three-quarters', 'two-thirds', 'half', 'one-third', 'one-quarter'],
+    },
   },
 } satisfies Meta<typeof Grid>;
 
@@ -140,6 +144,54 @@ export const MasonryWithSpans: Story = {
   ),
 };
 
+/**
+ * `masonryPreferredColumnSpan="half"` makes every auto-span item try to span
+ * half the grid. Because `"half"` resolves through the foundation's responsive
+ * column tokens, the same value yields 2 cols on a 4-col mobile grid, 4 cols
+ * on an 8-col tablet grid, and 6 cols on a 12-col desktop grid — the layout
+ * adapts without you configuring per-breakpoint values.
+ *
+ * When an item would overflow the row, the polyfill **demotes** its span to
+ * fill just the remaining columns, so no trailing gap appears.
+ *
+ * Use the Controls to swap `masonryPreferredColumnSpan` between named values
+ * and watch the packing re-run. Resize the viewport to see the demotion adapt
+ * to the current column count.
+ */
+export const MasonryPreferredColumnSpan: Story = {
+  args: { isMasonry: true, masonryPreferredColumnSpan: 'half' },
+  render: (args) => (
+    <Grid {...args}>
+      {Array.from({ length: 7 }).map((_, i) => (
+        <GridItem key={i} style={masonryCellStyle(i)}>
+          Card {i + 1}
+        </GridItem>
+      ))}
+    </Grid>
+  ),
+};
+
+/**
+ * Mixing an explicit `columnSpan="three-quarters"` hero with auto items.
+ * The hero keeps its span; its columns still consume the demotion budget,
+ * so the auto items fill the remaining row consistently.
+ */
+export const MasonryPreferredColumnSpanWithHero: Story = {
+  args: { isMasonry: true, masonryPreferredColumnSpan: 'half' },
+  render: (args) => (
+    <Grid {...args}>
+      <GridItem columnSpan="three-quarters" style={masonryCellStyle(0)}>
+        Hero (three-quarters)
+      </GridItem>
+      {Array.from({ length: 8 }).map((_, i) => (
+        <GridItem key={i} style={masonryCellStyle(i + 1)}>
+          Card {i + 1}
+        </GridItem>
+      ))}
+    </Grid>
+  ),
+};
+
 export const ComplexLayout: Story = {
   args: {},
   render: () => (

package/src/components/layout/Grid/Grid.tsx

@@ -11,6 +11,7 @@ import css from './Grid.module.css';
 import { cn } from '@boostdev/design-system-foundation';
 import type { WithClassName } from '../../../types';
 import { useMasonry } from './masonry';
+import type { GridItemSpanValue } from './GridItem';
 
 export type GridVariant = 'main' | 'page' | 'funnel' | 'custom';
 
@@ -45,6 +46,18 @@ type GridOwnProps = WithClassName & {
    * are unaffected.
    */
   autoSpanMedia?: boolean;
+  /**
+   * Masonry only. When set, each `GridItem` without an explicit `columnSpan`
+   * tries to span this value; an item at the end of a row is demoted to fill
+   * just the remaining columns rather than wrapping and leaving a gap. Uses
+   * the same named span vocabulary as `columnSpan` on `GridItem`, so a value
+   * like `"half"` adapts across breakpoints via the foundation's responsive
+   * column tokens (4/8/12). A `number` is a literal column count and does
+   * **not** adapt — prefer named values unless you're using `variant="custom"`.
+   * Requires `isMasonry`; no-op otherwise. Items with an explicit `columnSpan`
+   * keep their span.
+   */
+  masonryPreferredColumnSpan?: Exclude<GridItemSpanValue, 'auto'>;
   as?: ElementType;
 };
 
@@ -59,12 +72,13 @@ export function Grid<C extends ElementType = 'div'>({
   isCentered = false,
   isMasonry = false,
   autoSpanMedia = false,
+  masonryPreferredColumnSpan,
   as,
   style,
   ...rest
 }: GridProps<C>) {
   const ref = useRef<HTMLElement>(null);
-  useMasonry(ref, isMasonry);
+  useMasonry(ref, isMasonry, { preferredColumnSpan: masonryPreferredColumnSpan });
 
   const classNames = cn(
     css.grid,

package/src/components/layout/Grid/GridItem.tsx

@@ -137,10 +137,16 @@ export function GridItem<C extends ElementType = 'div'>({
 
   const Component = as ?? 'div';
 
+  // Marker the masonry polyfill reads to know this item's span wasn't set by the
+  // consumer — it may override the span with `masonryPreferredColumnSpan` on Grid.
+  // Items with an explicit range or explicit `columnSpan` are never eligible.
+  const isColumnSpanAuto = columnSpan === undefined && !hasExplicitRange;
+
   return (
     <Component
       ref={ref as never}
       {...rest}
+      data-column-span-auto={isColumnSpanAuto ? '' : undefined}
       className={cn(css.item, className)}
       style={composedStyle}
     >