@boostdev/design-system-components 2.2.0 → 2.3.0

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

@@ -55,6 +55,9 @@ 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 — number; masonry only. Child items without a
+ *                     `column-span` attribute try to span this many columns; an
+ *                     item at row-end is demoted to the remaining column count.
  *
  * Slots:
  *   (default) — grid content; typically `<bds-grid-item>` children
@@ -85,12 +88,18 @@ declare class BdsGrid extends LitElement {
             attribute: string;
             reflect: boolean;
         };
+        masonryPreferredColumnSpan: {
+            type: NumberConstructor;
+            attribute: string;
+            reflect: boolean;
+        };
     };
     variant: GridVariant;
     columns: number | undefined;
     isCentered: boolean;
     isMasonry: boolean;
     autoSpanMedia: boolean;
+    masonryPreferredColumnSpan: number | undefined;
     private _ro?;
     private _mo?;
     private _frame;

package/dist/web-components/index.js

@@ -133,7 +133,7 @@ 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) {
+function applyMasonryLayout(container, rawChildren, options = {}) {
   const cs = window.getComputedStyle(container);
   const targetGap = parseFloat(cs.columnGap) || 0;
   container.style.gridAutoRows = `${ROW_UNIT_PX}px`;
@@ -146,6 +146,25 @@ function applyMasonryLayout(container, rawChildren) {
     child.style.gridRow = "";
     child.style.gridRowStart = "";
     child.style.gridRowEnd = "";
+    child.style.alignSelf = "start";
+  }
+  const preferred = options.preferredColumnSpan ?? 0;
+  if (preferred >= 2) {
+    const totalCols = countGridColumns(container);
+    if (totalCols > 0) {
+      let col = 0;
+      for (const child of children) {
+        if (child.hasAttribute("data-column-span-auto")) {
+          const remaining = totalCols - col;
+          const span = Math.max(1, Math.min(preferred, remaining));
+          child.style.gridColumn = `span ${span}`;
+          col = (col + span) % totalCols;
+        } else {
+          const consumed = Math.min(totalCols, readExplicitSpan(child, totalCols));
+          col = (col + consumed) % totalCols;
+        }
+      }
+    }
   }
   const heights = children.map((child) => child.offsetHeight);
   for (let i3 = 0; i3 < children.length; i3++) {
@@ -153,6 +172,25 @@ function applyMasonryLayout(container, rawChildren) {
     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 = "";
@@ -162,6 +200,10 @@ function clearMasonryLayout(container, rawChildren) {
     child.style.gridRow = "";
     child.style.gridRowStart = "";
     child.style.gridRowEnd = "";
+    child.style.alignSelf = "";
+    if (child.hasAttribute("data-column-span-auto")) {
+      child.style.gridColumn = "";
+    }
   }
 }
 
@@ -220,7 +262,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: Number,
+      attribute: "masonry-preferred-column-span",
+      reflect: true
+    }
   };
   _ro;
   _mo;
@@ -232,6 +279,7 @@ var BdsGrid = class extends i2 {
     this.isCentered = false;
     this.isMasonry = false;
     this.autoSpanMedia = false;
+    this.masonryPreferredColumnSpan = void 0;
   }
   disconnectedCallback() {
     super.disconnectedCallback();
@@ -271,7 +319,11 @@ 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.masonryPreferredColumnSpan
+        });
+      }
     });
   }
   _teardownMasonry() {
@@ -428,6 +480,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.0",
+  "version": "2.3.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,40 @@ 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 two columns wide" feed, set `masonryPreferredColumnSpan` on the `Grid`. Items without an explicit `columnSpan` try to span that many columns. 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={2}>
+  {cards.map((c) => (
+    <GridItem key={c.id}>…</GridItem>
+  ))}
+</Grid>
+```
+
+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

@@ -143,6 +143,19 @@ describe('applyMasonryLayout', () => {
     expect(hidden.style.gridRowEnd).toBe('');
   });
 
+  it('sets align-self: start on children so they shrink-wrap for measurement and do not stretch into the gap', () => {
+    // Regression: without this, default `align-self: stretch` grows every child
+    // to fill the 1px grid-auto-rows track, making offsetHeight return 1 and
+    // collapsing all items to minimum size.
+    const container = makeContainer(10);
+    const a = makeItem(100);
+    const b = makeItem(50);
+    container.append(a, b);
+    applyMasonryLayout(container, [a, b]);
+    expect(a.style.alignSelf).toBe('start');
+    expect(b.style.alignSelf).toBe('start');
+  });
+
   it('clearMasonryLayout undoes container and child styles', () => {
     const container = makeContainer(10);
     const item = makeItem(50);
@@ -155,6 +168,73 @@ describe('applyMasonryLayout', () => {
     expect(item.style.gridRowEnd).toBe('');
     expect(item.style.gridRowStart).toBe('');
     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', () => {
+      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: 2 });
+      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);
+      applyMasonryLayout(container, [a, b], { preferredColumnSpan: 2 });
+      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: 2 });
+      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('clearMasonryLayout resets gridColumn on data-column-span-auto items only', () => {
+      const container = makeContainer(10);
+      container.style.gridTemplateColumns = '100px 100px 100px 100px';
+      const auto = makeAutoItem(50);
+      const explicit = makeItem(50);
+      explicit.style.gridColumn = 'span 2';
+      container.append(auto, explicit);
+      applyMasonryLayout(container, [auto, explicit], { preferredColumnSpan: 2 });
+      clearMasonryLayout(container, [auto, explicit]);
+      expect(auto.style.gridColumn).toBe('');
+      expect(explicit.style.gridColumn).toBe('span 2');
+    });
   });
 });
 
@@ -206,6 +286,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,7 @@ const meta = {
     columns: { control: 'number' },
     isCentered: { control: 'boolean' },
     isMasonry: { control: 'boolean' },
+    masonryPreferredColumnSpan: { control: { type: 'number', min: 1, max: 4 } },
   },
 } satisfies Meta<typeof Grid>;
 
@@ -140,6 +141,50 @@ export const MasonryWithSpans: Story = {
   ),
 };
 
+/**
+ * `masonryPreferredColumnSpan={2}` makes every auto-span item span 2 columns.
+ * With 7 items in a 12-column desktop grid (6 per row × 2 cols), the 7th item
+ * would normally leave a 10-col gap — the polyfill **demotes** its span to
+ * fill just the remaining columns, so no trailing gap appears.
+ *
+ * Use the Controls to flip `masonryPreferredColumnSpan` between 1–4 and watch
+ * the packing re-run. Resize the viewport (or the Storybook canvas) to see
+ * the demotion adapt to the current column count.
+ */
+export const MasonryPreferredColumnSpan: Story = {
+  args: { isMasonry: true, masonryPreferredColumnSpan: 2 },
+  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: 2 },
+  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

@@ -1,4 +1,5 @@
 import {
+  Context,
   ElementType,
   ComponentPropsWithoutRef,
   CSSProperties,
@@ -23,9 +24,14 @@ export type GridContextValue = {
   autoSpanMedia: boolean;
 };
 
-export const GridContext = createContext<GridContextValue>({
-  autoSpanMedia: false,
-});
+// Lazy-initialised so the module can be evaluated in Next.js Server Components
+// without calling `createContext` at import time (which crashes RSC — `react-server`
+// export conditions don't expose `createContext`).
+let _GridContext: Context<GridContextValue>;
+export function getGridContext(): Context<GridContextValue> {
+  _GridContext ??= createContext<GridContextValue>({ autoSpanMedia: false });
+  return _GridContext;
+}
 
 type GridOwnProps = WithClassName & {
   variant?: GridVariant;
@@ -39,6 +45,14 @@ type GridOwnProps = WithClassName & {
    * are unaffected.
    */
   autoSpanMedia?: boolean;
+  /**
+   * Masonry only. When set (>= 2), each `GridItem` without an explicit
+   * `columnSpan` tries to span this many columns; an item at the end of a row
+   * is demoted to fill just the remaining columns rather than wrapping and
+   * leaving a gap. Requires `isMasonry`; no-op otherwise. Items with an
+   * explicit `columnSpan` keep their span.
+   */
+  masonryPreferredColumnSpan?: number;
   as?: ElementType;
 };
 
@@ -53,12 +67,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,
@@ -75,6 +90,7 @@ export function Grid<C extends ElementType = 'div'>({
 
   const Component = as ?? 'div';
 
+  const GridContext = getGridContext();
   const ctx = useMemo<GridContextValue>(() => ({ autoSpanMedia }), [autoSpanMedia]);
 
   return (

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

@@ -10,7 +10,7 @@ import {
 import css from './Grid.module.css';
 import { cn } from '@boostdev/design-system-foundation';
 import type { WithClassName } from '../../../types';
-import { GridContext } from './Grid';
+import { getGridContext } from './Grid';
 import {
   aspectToColumnSpan,
   findMediaChild,
@@ -75,7 +75,7 @@ export function GridItem<C extends ElementType = 'div'>({
   style,
   ...rest
 }: GridItemProps<C>) {
-  const { autoSpanMedia } = useContext(GridContext);
+  const { autoSpanMedia } = useContext(getGridContext());
   const effectiveSpan: GridItemSpanValue =
     columnSpan ?? (autoSpanMedia ? 'auto' : 'full');
 
@@ -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}
     >

package/src/components/layout/Grid/masonry.ts

@@ -36,7 +36,23 @@ export function supportsNativeMasonry(): boolean {
   );
 }
 
-export function applyMasonryLayout(container: HTMLElement, rawChildren: HTMLElement[]): void {
+export type MasonryOptions = {
+  /**
+   * When set (>= 2), the polyfill assigns column spans to items marked
+   * `data-column-span-auto` so they try to occupy this many columns each. If a
+   * preferred-span item would overflow the row, it is demoted to fill only the
+   * remaining columns (never less than 1). Items with an explicit `columnSpan`
+   * keep their span; their span still consumes column budget for the demotion
+   * calculation.
+   */
+  preferredColumnSpan?: number;
+};
+
+export function applyMasonryLayout(
+  container: HTMLElement,
+  rawChildren: HTMLElement[],
+  options: MasonryOptions = {},
+): void {
   // We override row-gap to 0, so reading it back would always give 0 on re-runs.
   // Read column-gap instead — `.grid` sets both via the `gap` shorthand and the
   // polyfill never touches column-gap. (If a consumer sets asymmetric gaps, the
@@ -53,10 +69,37 @@ export function applyMasonryLayout(container: HTMLElement, rawChildren: HTMLElem
   );
 
   // Pass 1 — clear prior row-span overrides so items measure at their natural height.
+  // Also force `align-self: start`: the default `stretch` would grow each item to fill
+  // the 1px track, making `offsetHeight` return 1 for every child. Keeping `start` after
+  // the span is assigned also prevents items from stretching into the gap region.
   for (const child of children) {
     child.style.gridRow = '';
     child.style.gridRowStart = '';
     child.style.gridRowEnd = '';
+    child.style.alignSelf = 'start';
+  }
+
+  // Preferred-column-span pass — optional. Assigns column spans to `data-column-span-auto`
+  // items, demoting to fit remaining row space. Runs before height measurement so items
+  // are measured at the width they will actually render.
+  const preferred = options.preferredColumnSpan ?? 0;
+  if (preferred >= 2) {
+    const totalCols = countGridColumns(container);
+    if (totalCols > 0) {
+      let col = 0;
+      for (const child of children) {
+        if (child.hasAttribute('data-column-span-auto')) {
+          const remaining = totalCols - col;
+          const span = Math.max(1, Math.min(preferred, remaining));
+          child.style.gridColumn = `span ${span}`;
+          col = (col + span) % totalCols;
+        } else {
+          // Item has an explicit span — consume its columns for the demotion budget.
+          const consumed = Math.min(totalCols, readExplicitSpan(child, totalCols));
+          col = (col + consumed) % totalCols;
+        }
+      }
+    }
   }
 
   // Pass 2 — read all heights in a tight loop. The first offsetHeight read forces one
@@ -72,6 +115,36 @@ export function applyMasonryLayout(container: HTMLElement, rawChildren: HTMLElem
   }
 }
 
+function countGridColumns(container: HTMLElement): number {
+  // `getComputedStyle` resolves `grid-template-columns` to concrete track sizes
+  // (e.g. "256px 256px 256px 256px"), regardless of whether the author used
+  // `repeat()`, `minmax()`, or CSS custom properties. Splitting by whitespace
+  // gives the actual track count at the current viewport width.
+  const value = window.getComputedStyle(container).gridTemplateColumns.trim();
+  if (!value || value === 'none') return 0;
+  return value.split(/\s+/).length;
+}
+
+function readExplicitSpan(el: HTMLElement, totalCols: number): number {
+  // Try the inline value first to avoid resolving CSS vars that haven't been
+  // registered with `@property` (computed style returns the literal string for
+  // those). Inline values look like `span N`, `span var(...)`, or `a / b`.
+  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: string, totalCols: number): number | null {
+  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)));
+  // `1 / -1` style — spans the whole row.
+  if (/\/\s*-1\b/.test(value)) return totalCols;
+  return null;
+}
+
 export function clearMasonryLayout(container: HTMLElement, rawChildren: HTMLElement[]): void {
   container.style.gridAutoRows = '';
   container.style.gridAutoFlow = '';
@@ -81,6 +154,13 @@ export function clearMasonryLayout(container: HTMLElement, rawChildren: HTMLElem
     child.style.gridRow = '';
     child.style.gridRowStart = '';
     child.style.gridRowEnd = '';
+    child.style.alignSelf = '';
+    // Only clear `gridColumn` on items the polyfill owned (marked as auto) —
+    // items with an author-specified span had their column set from the React
+    // render pass and should keep it.
+    if (child.hasAttribute('data-column-span-auto')) {
+      child.style.gridColumn = '';
+    }
   }
 }
 
@@ -89,7 +169,12 @@ export function clearMasonryLayout(container: HTMLElement, rawChildren: HTMLElem
  * size / mutation changes. No-op when `enabled` is false or when the browser
  * natively supports masonry.
  */
-export function useMasonry(ref: RefObject<HTMLElement | null>, enabled: boolean): void {
+export function useMasonry(
+  ref: RefObject<HTMLElement | null>,
+  enabled: boolean,
+  options: MasonryOptions = {},
+): void {
+  const { preferredColumnSpan } = options;
   useLayoutEffect(() => {
     const container = ref.current;
     if (!container || !enabled) return;
@@ -99,7 +184,9 @@ export function useMasonry(ref: RefObject<HTMLElement | null>, enabled: boolean)
     const schedule = () => {
       cancelAnimationFrame(frame);
       frame = requestAnimationFrame(() => {
-        applyMasonryLayout(container, Array.from(container.children) as HTMLElement[]);
+        applyMasonryLayout(container, Array.from(container.children) as HTMLElement[], {
+          preferredColumnSpan,
+        });
       });
     };
 
@@ -130,5 +217,5 @@ export function useMasonry(ref: RefObject<HTMLElement | null>, enabled: boolean)
       mo?.disconnect();
       clearMasonryLayout(container, Array.from(container.children) as HTMLElement[]);
     };
-  }, [ref, enabled]);
+  }, [ref, enabled, preferredColumnSpan]);
 }

package/src/web-components/layout/BdsGrid.mdx

@@ -49,6 +49,7 @@ Numeric `column-span="n"` is literal — it does not adapt. Use named values for
 | `is-centered`     | boolean                                        | `false`  | Caps max-width via `--bds-container_max-width`     |
 | `is-masonry`      | boolean                                        | `false`  | Enables masonry layout (CSS Grid Level 3 "grid-lanes"). Uses native CSS when supported, otherwise runs a JS polyfill. |
 | `auto-span-media` | boolean                                        | `false`  | Child `<bds-grid-item>`s without an explicit `column-span` resolve their span from the intrinsic aspect ratio of their first `<img>`/`<video>` descendant. See [Aspect-ratio auto-span](#aspect-ratio-auto-span). |
+| `masonry-preferred-column-span` | number                           | —        | In masonry mode, items without an explicit `column-span` try to span this many columns, demoting to fit at row ends. See [Masonry preferred column span](#masonry-preferred-column-span). |
 
 ## Slots
 
@@ -161,6 +162,39 @@ Individual items can opt out with an explicit `column-span` (e.g. `column-span="
 
 Named-span responsive behavior still applies — on mobile every item collapses to full-width regardless of its resolved span.
 
+## Masonry preferred column span
+
+For a uniform "cards mostly two columns wide" feed, set `masonry-preferred-column-span` on the `<bds-grid>`. Items without an explicit `column-span` try to span that many columns. 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.
+
+```html
+<bds-grid is-masonry masonry-preferred-column-span="2">
+  <bds-grid-item>…</bds-grid-item>
+  <bds-grid-item>…</bds-grid-item>
+</bds-grid>
+```
+
+Rules:
+
+- Requires `is-masonry`. No-op on non-masonry grids.
+- Items with an explicit `column-span` (named or numeric) keep their span. Their columns still consume the demotion budget, so a `column-span="three-quarters"` followed by an auto item in a 4-column grid correctly demotes the auto item to 1.
+- Items with `start-column` / `end-column` 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 `column-span` per item instead. `masonry-preferred-column-span` enforces a uniform visual rhythm and is the wrong tool for heterogeneous cards.
+- Alongside `auto-span-media` on the same grid. Both features target items without an explicit `column-span`, and `masonry-preferred-column-span` wins — `auto-span-media` 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 `column-span` 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 layout pass after upgrade, so it only executes on the client. The initial server render emits each auto item at its default `full` span until the custom element upgrades and the first polyfill pass runs — matching the existing masonry SSR behavior.
+
 ### Loading behavior
 
 Dimensions are read from `img.naturalWidth/naturalHeight` and `video.videoWidth/videoHeight` — no layout is triggered. If metadata is not yet available when the element upgrades, the item starts at `'one-quarter'` and re-resolves when the `load` (image) or `loadedmetadata` (video) event fires. Subsequent slot mutations re-run the resolver.