@boostdev/design-system-components 2.3.0 → 2.4.0

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

@@ -55,9 +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 — 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.
+ *   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
@@ -89,7 +92,7 @@ declare class BdsGrid extends LitElement {
             reflect: boolean;
         };
         masonryPreferredColumnSpan: {
-            type: NumberConstructor;
+            type: StringConstructor;
             attribute: string;
             reflect: boolean;
         };
@@ -99,7 +102,7 @@ declare class BdsGrid extends LitElement {
     isCentered: boolean;
     isMasonry: boolean;
     autoSpanMedia: boolean;
-    masonryPreferredColumnSpan: number | undefined;
+    masonryPreferredColumnSpan: string | undefined;
     private _ro?;
     private _mo?;
     private _frame;
@@ -110,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");
 }
+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,15 +173,19 @@ function applyMasonryLayout(container, rawChildren, options = {}) {
     child.style.gridRowEnd = "";
     child.style.alignSelf = "start";
   }
-  const preferred = options.preferredColumnSpan ?? 0;
-  if (preferred >= 2) {
+  const preferred = options.preferredColumnSpan;
+  if (preferred !== void 0) {
     const totalCols = countGridColumns(container);
-    if (totalCols > 0) {
+    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(preferred, remaining));
+          const span = Math.max(1, Math.min(preferredCols, remaining));
           child.style.gridColumn = `span ${span}`;
           col = (col + span) % totalCols;
         } else {
@@ -165,6 +194,10 @@ function applyMasonryLayout(container, rawChildren, options = {}) {
         }
       }
     }
+  } else {
+    for (const child of children) {
+      restoreOriginalColumn(child);
+    }
   }
   const heights = children.map((child) => child.offsetHeight);
   for (let i3 = 0; i3 < children.length; i3++) {
@@ -195,17 +228,21 @@ 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 = "";
-    if (child.hasAttribute("data-column-span-auto")) {
-      child.style.gridColumn = "";
-    }
+    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 {
@@ -264,7 +301,7 @@ var BdsGrid = class extends i2 {
     isMasonry: { type: Boolean, attribute: "is-masonry", reflect: true },
     autoSpanMedia: { type: Boolean, attribute: "auto-span-media", reflect: true },
     masonryPreferredColumnSpan: {
-      type: Number,
+      type: String,
       attribute: "masonry-preferred-column-span",
       reflect: true
     }
@@ -321,11 +358,18 @@ var BdsGrid = class extends i2 {
       const container = this._gridEl();
       if (container) {
         applyMasonryLayout(container, this._items(), {
-          preferredColumnSpan: this.masonryPreferredColumnSpan
+          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();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boostdev/design-system-components",
-  "version": "2.3.0",
+  "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

@@ -203,16 +203,18 @@ Intrinsic dimensions are read from `img.naturalWidth/naturalHeight` and `video.v
 
 ## 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.
+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={2}>
+<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.

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);
@@ -179,12 +196,13 @@ describe('applyMasonryLayout', () => {
     }
 
     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: 2 });
+      applyMasonryLayout(container, [a, b], { preferredColumnSpan: 'half' });
       expect(a.style.gridColumn).toBe('span 2');
       expect(b.style.gridColumn).toBe('span 2');
     });
@@ -195,7 +213,8 @@ describe('applyMasonryLayout', () => {
       const a = makeAutoItem(50);
       const b = makeAutoItem(50);
       container.append(a, b);
-      applyMasonryLayout(container, [a, b], { preferredColumnSpan: 2 });
+      // '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');
@@ -208,7 +227,7 @@ describe('applyMasonryLayout', () => {
       explicit.style.gridColumn = 'span 3';
       const auto = makeAutoItem(50);
       container.append(explicit, auto);
-      applyMasonryLayout(container, [explicit, auto], { preferredColumnSpan: 2 });
+      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');
@@ -223,16 +242,53 @@ describe('applyMasonryLayout', () => {
       expect(a.style.gridColumn).toBe('');
     });
 
-    it('clearMasonryLayout resets gridColumn on data-column-span-auto items only', () => {
+    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: 2 });
+      applyMasonryLayout(container, [auto, explicit], { preferredColumnSpan: 'half' });
       clearMasonryLayout(container, [auto, explicit]);
-      expect(auto.style.gridColumn).toBe('');
+      expect(auto.style.gridColumn).toBe('var(--bds-grid_span-100)');
       expect(explicit.style.gridColumn).toBe('span 2');
     });
   });

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

@@ -10,7 +10,10 @@ const meta = {
     columns: { control: 'number' },
     isCentered: { control: 'boolean' },
     isMasonry: { control: 'boolean' },
-    masonryPreferredColumnSpan: { control: { type: 'number', min: 1, max: 4 } },
+    masonryPreferredColumnSpan: {
+      control: 'select',
+      options: ['full', 'three-quarters', 'two-thirds', 'half', 'one-third', 'one-quarter'],
+    },
   },
 } satisfies Meta<typeof Grid>;
 
@@ -142,17 +145,21 @@ 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
+ * `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 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.
+ * 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: 2 },
+  args: { isMasonry: true, masonryPreferredColumnSpan: 'half' },
   render: (args) => (
     <Grid {...args}>
       {Array.from({ length: 7 }).map((_, i) => (
@@ -170,7 +177,7 @@ export const MasonryPreferredColumnSpan: Story = {
  * so the auto items fill the remaining row consistently.
  */
 export const MasonryPreferredColumnSpanWithHero: Story = {
-  args: { isMasonry: true, masonryPreferredColumnSpan: 2 },
+  args: { isMasonry: true, masonryPreferredColumnSpan: 'half' },
   render: (args) => (
     <Grid {...args}>
       <GridItem columnSpan="three-quarters" style={masonryCellStyle(0)}>

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';
 
@@ -46,13 +47,17 @@ type GridOwnProps = WithClassName & {
    */
   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.
+   * 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?: number;
+  masonryPreferredColumnSpan?: Exclude<GridItemSpanValue, 'auto'>;
   as?: ElementType;
 };
 

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

@@ -1,4 +1,43 @@
 import { RefObject, useLayoutEffect } from 'react';
+import type { GridItemSpanValue } from './GridItem';
+
+type NamedSpan = Exclude<GridItemSpanValue, 'auto' | number>;
+
+// Named spans resolve through the foundation's responsive column tokens so they
+// match the behavior of `columnSpan` on `GridItem`. The polyfill reads the live
+// value at each run, which is how a single `preferredColumnSpan: 'half'` gives
+// 2 cols on a 4-col mobile grid and 6 cols on a 12-col desktop grid.
+const NAMED_SPAN_VAR: Record<Exclude<NamedSpan, 'full'>, string> = {
+  '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',
+};
+
+// Mathematical fallback for environments where the foundation CSS isn't loaded
+// (e.g. jsdom tests). Round to the nearest integer; clamp to [1, totalCols].
+const NAMED_SPAN_FRACTION: Record<Exclude<NamedSpan, 'full'>, number> = {
+  'three-quarters': 0.75,
+  'two-thirds': 2 / 3,
+  half: 0.5,
+  'one-third': 1 / 3,
+  'one-quarter': 0.25,
+};
+
+function resolvePreferredColumns(
+  container: HTMLElement,
+  value: Exclude<GridItemSpanValue, 'auto'>,
+  totalCols: number,
+): number {
+  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]));
+}
 
 /**
  * Masonry layout polyfill based on CSS Grid Layout Module Level 3 (a.k.a. "grid-lanes").
@@ -38,16 +77,24 @@ export function supportsNativeMasonry(): boolean {
 
 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.
+   * When set, the polyfill assigns column spans to items marked
+   * `data-column-span-auto`. Named values (`'half'`, `'one-third'`, etc.) are
+   * resolved through the foundation's responsive column tokens so the same
+   * option yields the right span at every breakpoint. A `number` is a literal
+   * column count. 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;
+  preferredColumnSpan?: Exclude<GridItemSpanValue, 'auto'>;
 };
 
+// Data attribute used to remember an auto item's inline `grid-column` before the
+// polyfill overwrites it — restored on cleanup or when the preferred option is
+// unset, so a Storybook control going from preferred=2 → undefined doesn't leave
+// items pinned to their polyfill-assigned span.
+const ORIGINAL_COL_ATTR = 'data-bds-masonry-original-column';
+
 export function applyMasonryLayout(
   container: HTMLElement,
   rawChildren: HTMLElement[],
@@ -63,6 +110,13 @@ export function applyMasonryLayout(
   container.style.gridAutoRows = `${ROW_UNIT_PX}px`;
   container.style.rowGap = '0px';
   container.style.gridAutoFlow = 'dense';
+  // `dense` + per-child `ResizeObserver` can fight the browser's scroll anchoring:
+  // a subpixel child resize (scrollbar toggling, late image decode, font swap) re-runs
+  // the pack, items above the viewport shift, and the browser yanks the viewport up
+  // to "follow" them. Opting this container out of scroll anchoring means the browser
+  // picks something outside the grid as the anchor, so internal reshuffles are invisible
+  // to scroll position. Cleared in clearMasonryLayout.
+  container.style.overflowAnchor = 'none';
 
   const children = rawChildren.filter(
     (el) => el.nodeType === 1 && window.getComputedStyle(el).display !== 'none',
@@ -81,16 +135,23 @@ export function applyMasonryLayout(
 
   // 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) {
+  // are measured at the width they will actually render. When the option is not set,
+  // any previously-written spans are restored to their original inline value so
+  // a Storybook control change from preferred='half' → undefined doesn't leave auto
+  // items pinned.
+  const preferred = options.preferredColumnSpan;
+  if (preferred !== undefined) {
     const totalCols = countGridColumns(container);
-    if (totalCols > 0) {
+    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(preferred, remaining));
+          const span = Math.max(1, Math.min(preferredCols, remaining));
           child.style.gridColumn = `span ${span}`;
           col = (col + span) % totalCols;
         } else {
@@ -100,6 +161,11 @@ export function applyMasonryLayout(
         }
       }
     }
+  } else {
+    // No preferred span — restore any items the polyfill previously wrote.
+    for (const child of children) {
+      restoreOriginalColumn(child);
+    }
   }
 
   // Pass 2 — read all heights in a tight loop. The first offsetHeight read forces one
@@ -149,21 +215,25 @@ export function clearMasonryLayout(container: HTMLElement, rawChildren: HTMLElem
   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 = '';
-    // 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 = '';
-    }
+    // Restore any `gridColumn` value the polyfill overwrote. Items the
+    // polyfill never touched have no ORIGINAL_COL_ATTR and are left alone.
+    restoreOriginalColumn(child);
   }
 }
 
+function restoreOriginalColumn(el: HTMLElement): void {
+  if (!el.hasAttribute(ORIGINAL_COL_ATTR)) return;
+  el.style.gridColumn = el.getAttribute(ORIGINAL_COL_ATTR) ?? '';
+  el.removeAttribute(ORIGINAL_COL_ATTR);
+}
+
 /**
  * React hook that runs the polyfill against `ref.current` and re-runs on
  * size / mutation changes. No-op when `enabled` is false or when the browser

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

@@ -49,7 +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). |
+| `masonry-preferred-column-span` | named span \| number             | —        | In masonry mode, items without an explicit `column-span` try to span this value, demoting to fit at row ends. Accepts the same named values as `column-span` (`"half"`, `"one-third"`, etc.). See [Masonry preferred column span](#masonry-preferred-column-span). |
 
 ## Slots
 
@@ -164,15 +164,17 @@ Named-span responsive behavior still applies — on mobile every item collapses
 
 ## 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.
+For a uniform "cards mostly half-width" feed, set `masonry-preferred-column-span` on the `<bds-grid>`. Items without an explicit `column-span` 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.
 
 ```html
-<bds-grid is-masonry masonry-preferred-column-span="2">
+<bds-grid is-masonry masonry-preferred-column-span="half">
   <bds-grid-item>…</bds-grid-item>
   <bds-grid-item>…</bds-grid-item>
 </bds-grid>
 ```
 
+Accepted values match `column-span` on `<bds-grid-item>`: `"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 numeric string (e.g. `"2"`) is accepted too, but is a literal column count and does **not** adapt — prefer named values unless you're using `variant="custom"`.
+
 Rules:
 
 - Requires `is-masonry`. No-op on non-masonry grids.

package/src/web-components/layout/BdsGrid.stories.tsx

@@ -16,7 +16,7 @@ function BdsGrid({
   columns?: number;
   isCentered?: boolean;
   isMasonry?: boolean;
-  masonryPreferredColumnSpan?: number;
+  masonryPreferredColumnSpan?: string;
   children?: React.ReactNode;
 }) {
   return React.createElement(
@@ -74,7 +74,10 @@ const meta = {
     columns: { control: 'number' },
     isCentered: { control: 'boolean' },
     isMasonry: { control: 'boolean' },
-    masonryPreferredColumnSpan: { control: { type: 'number', min: 1, max: 4 } },
+    masonryPreferredColumnSpan: {
+      control: 'select',
+      options: ['full', 'three-quarters', 'two-thirds', 'half', 'one-third', 'one-quarter'],
+    },
   },
 } satisfies Meta<typeof BdsGrid>;
 
@@ -194,16 +197,19 @@ export const MasonryWithSpans: Story = {
 };
 
 /**
- * `masonry-preferred-column-span="2"` makes every auto-span item span 2 columns.
- * With 7 items in a 12-column desktop grid, the 7th would normally leave a trailing
- * gap — the polyfill **demotes** its span to fill just the remaining columns.
+ * `masonry-preferred-column-span="half"` makes every auto-span item try to
+ * span half the grid. Named values resolve through the foundation's responsive
+ * column tokens, so the same value yields 2 cols on a 4-col mobile grid, 4 on
+ * an 8-col tablet grid, and 6 on a 12-col desktop grid.
+ *
+ * When an item would overflow the row, the polyfill **demotes** its span to
+ * fill just the remaining columns, so no trailing gap appears.
  *
- * Flip `masonryPreferredColumnSpan` between 1–4 in the Controls to see the
- * packing re-run. Resize the viewport to watch the demotion adapt to the
- * current column count.
+ * Swap `masonryPreferredColumnSpan` between named values in the Controls and
+ * resize the viewport to watch the demotion adapt to the current column count.
  */
 export const MasonryPreferredColumnSpan: Story = {
-  args: { isMasonry: true, masonryPreferredColumnSpan: 2 },
+  args: { isMasonry: true, masonryPreferredColumnSpan: 'half' },
   render: (args) => (
     <BdsGrid {...args}>
       {Array.from({ length: 7 }).map((_, i) => (
@@ -219,7 +225,7 @@ export const MasonryPreferredColumnSpan: Story = {
  * auto items fill the remaining row consistently.
  */
 export const MasonryPreferredColumnSpanWithHero: Story = {
-  args: { isMasonry: true, masonryPreferredColumnSpan: 2 },
+  args: { isMasonry: true, masonryPreferredColumnSpan: 'half' },
   render: (args) => (
     <BdsGrid {...args}>
       <Item columnSpan="three-quarters"><div style={masonryCellStyle(0)}>Hero (three-quarters)</div></Item>