@boostdev/design-system-components 2.3.0 → 2.4.1

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,35 +128,62 @@ 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"
   );
   for (const child of children) {
-    child.style.gridRow = "";
-    child.style.gridRowStart = "";
-    child.style.gridRowEnd = "";
     child.style.alignSelf = "start";
+    child.style.overflowAnchor = "none";
   }
-  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 +192,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 +226,22 @@ 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 = "";
-    }
+    child.style.overflowAnchor = "";
+    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 +300,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 +357,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.1",
   "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,46 @@ 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('sets overflow-anchor: none on each child so the browser picks an anchor outside the grid', () => {
+    // `overflow-anchor` doesn't inherit — setting it only on the container leaves
+    // children anchor-eligible, so a child above the viewport being rewritten still
+    // drags the scroll position. Excluding each child forces the browser to anchor
+    // on content outside the grid.
+    const container = makeContainer(10);
+    const a = makeItem(100);
+    const b = makeItem(200);
+    container.append(a, b);
+    applyMasonryLayout(container, [a, b]);
+    expect(a.style.overflowAnchor).toBe('none');
+    expect(b.style.overflowAnchor).toBe('none');
+  });
+
+  it('clearMasonryLayout restores overflow-anchor on children', () => {
+    const container = makeContainer(10);
+    const a = makeItem(100);
+    container.append(a);
+    applyMasonryLayout(container, [a]);
+    clearMasonryLayout(container, [a]);
+    expect(a.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 +219,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 +236,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 +250,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 +265,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;
 };