@boostdev/design-system-components 2.3.0 → 2.4.1

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,34 +110,55 @@ 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. `overflow-anchor: none` doesn't inherit, so setting it on the
+  // container alone doesn't exclude grid children from anchor selection — the browser
+  // will still pick one of the `<GridItem>`s as the anchor and drag the viewport when
+  // that item's row-span is rewritten. We set it on the container AND every child so
+  // the browser picks an anchor outside the grid entirely. Cleared in clearMasonryLayout.
+  container.style.overflowAnchor = 'none';
 
   const children = rawChildren.filter(
     (el) => el.nodeType === 1 && window.getComputedStyle(el).display !== 'none',
   );
 
-  // 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.
+  // Pass 1 — force `align-self: start`: the default `stretch` would grow each item
+  // to fill the 1px track, making `offsetHeight` return 1 for every child. Also
+  // propagate `overflow-anchor: none` to each child (see container comment above).
+  //
+  // We intentionally do NOT clear `gridRow*` before measuring — with `align-self: start`,
+  // an item's `offsetHeight` is its natural content height regardless of the assigned
+  // span, so the stale span doesn't bias the measurement. Keeping the old span during
+  // the measurement phase means the container's block-size doesn't momentarily collapse
+  // (which is the other shape the scroll jump can take: grid height drops → document
+  // scrollHeight drops → browser clamps `scrollTop` → visible jump even with
+  // `overflow-anchor: none`).
   for (const child of children) {
-    child.style.gridRow = '';
-    child.style.gridRowStart = '';
-    child.style.gridRowEnd = '';
     child.style.alignSelf = 'start';
+    child.style.overflowAnchor = 'none';
   }
 
   // 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 +168,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 +222,26 @@ 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 = '';
-    }
+    child.style.overflowAnchor = '';
+    // 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
@@ -181,31 +259,55 @@ export function useMasonry(
     if (supportsNativeMasonry()) return;
 
     let frame = 0;
-    const schedule = () => {
+    const runNow = () => {
       cancelAnimationFrame(frame);
-      frame = requestAnimationFrame(() => {
-        applyMasonryLayout(container, Array.from(container.children) as HTMLElement[], {
-          preferredColumnSpan,
-        });
+      applyMasonryLayout(container, Array.from(container.children) as HTMLElement[], {
+        preferredColumnSpan,
       });
     };
+    const schedule = () => {
+      cancelAnimationFrame(frame);
+      frame = requestAnimationFrame(runNow);
+    };
 
     schedule();
 
+    // ResizeObserver fires during the "update the rendering" step, AFTER layout and
+    // BEFORE paint. Running the polyfill synchronously here means the paint that
+    // follows uses the freshly-computed row-spans — not the next frame's. If we
+    // defer to rAF instead, there's a visible frame where a grown item (e.g. a
+    // lazy-loaded image whose dimensions just resolved) overflows its stale cell
+    // and visually overlaps the next item in its column — easy to see on fast
+    // scroll through a long gallery.
     const ro =
-      typeof ResizeObserver !== 'undefined' ? new ResizeObserver(schedule) : null;
+      typeof ResizeObserver !== 'undefined' ? new ResizeObserver(runNow) : null;
+    const observeDescendants = (child: Element) => {
+      if (!ro) return;
+      ro.observe(child);
+      // Also observe media descendants directly. `loading="lazy"` images decode
+      // asynchronously; if the consumer hasn't reserved aspect ratio, the parent
+      // GridItem's size only changes once the image pushes it larger — by which
+      // point the next frame has painted with the stale cell. Observing the image
+      // itself means the polyfill re-runs in the same frame as the decode.
+      for (const media of Array.from(child.querySelectorAll('img, video'))) {
+        ro.observe(media);
+      }
+    };
     if (ro) {
       // Observe each child's size, not the container — re-running when the container
       // resizes causes a feedback loop (we set grid-auto-rows, which changes container
       // block-size, which fires the observer). Child-size changes are what we actually
       // need to respond to.
-      for (const child of Array.from(container.children)) ro.observe(child);
+      for (const child of Array.from(container.children)) observeDescendants(child);
     }
 
+    // MutationObserver fires as a microtask after DOM mutations — layout hasn't
+    // happened yet, so defer to rAF to let the browser lay out the new children
+    // before we measure them.
     const mo =
       typeof MutationObserver !== 'undefined'
         ? new MutationObserver(() => {
-            if (ro) for (const child of Array.from(container.children)) ro.observe(child);
+            for (const child of Array.from(container.children)) observeDescendants(child);
             schedule();
           })
         : null;

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>

package/src/web-components/layout/bds-grid.spec.ts

@@ -60,11 +60,11 @@ describe('bds-grid', () => {
     cleanup(el);
   });
 
-  it('reflects masonry-preferred-column-span as a number property', async () => {
+  it('reflects masonry-preferred-column-span as a string property', async () => {
     const el = await fixture(
-      '<bds-grid is-masonry masonry-preferred-column-span="2"></bds-grid>',
+      '<bds-grid is-masonry masonry-preferred-column-span="half"></bds-grid>',
     ) as BdsGrid;
-    expect(el.masonryPreferredColumnSpan).toBe(2);
+    expect(el.masonryPreferredColumnSpan).toBe('half');
     cleanup(el);
   });
 });

package/src/web-components/layout/bds-grid.ts

@@ -1,5 +1,6 @@
 import { LitElement, css, html } from 'lit';
 import { applyMasonryLayout, clearMasonryLayout, supportsNativeMasonry } from '../../components/layout/Grid/masonry';
+import type { GridItemSpanValue } from '../../components/layout/Grid/GridItem';
 
 export type GridVariant = 'main' | 'page' | 'funnel' | 'custom';
 
@@ -16,9 +17,12 @@ export 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
@@ -80,7 +84,7 @@ export class BdsGrid extends LitElement {
     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,
     },
@@ -91,7 +95,7 @@ export class BdsGrid extends LitElement {
   declare isCentered: boolean;
   declare isMasonry: boolean;
   declare autoSpanMedia: boolean;
-  declare masonryPreferredColumnSpan: number | undefined;
+  declare masonryPreferredColumnSpan: string | undefined;
 
   private _ro?: ResizeObserver;
   private _mo?: MutationObserver;
@@ -156,12 +160,21 @@ export class BdsGrid extends LitElement {
       const container = this._gridEl();
       if (container) {
         applyMasonryLayout(container, this._items(), {
-          preferredColumnSpan: this.masonryPreferredColumnSpan,
+          preferredColumnSpan: this._resolvePreferredColumnSpan(),
         });
       }
     });
   }
 
+  private _resolvePreferredColumnSpan(): Exclude<GridItemSpanValue, 'auto'> | undefined {
+    const raw = this.masonryPreferredColumnSpan;
+    if (raw === undefined || raw === null || raw === '') return undefined;
+    // Numeric attribute → literal column count; otherwise treat as a named span.
+    const n = Number(raw);
+    if (Number.isFinite(n) && String(n) === raw) return n;
+    return raw as Exclude<GridItemSpanValue, 'auto'>;
+  }
+
   private _teardownMasonry() {
     cancelAnimationFrame(this._frame);
     this._ro?.disconnect();