@boostdev/design-system-components 2.4.0 → 2.4.2

package/dist/web-components/index.js

@@ -157,6 +157,7 @@ function supportsNativeMasonry() {
   return CSS.supports("display", "grid-lanes") || CSS.supports("grid-template-rows", "masonry");
 }
 var ORIGINAL_COL_ATTR = "data-bds-masonry-original-column";
+var LAST_SPAN_ATTR = "data-bds-masonry-span";
 function applyMasonryLayout(container, rawChildren, options = {}) {
   const cs = window.getComputedStyle(container);
   const targetGap = parseFloat(cs.columnGap) || 0;
@@ -168,10 +169,8 @@ function applyMasonryLayout(container, rawChildren, options = {}) {
     (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;
   if (preferred !== void 0) {
@@ -200,9 +199,19 @@ function applyMasonryLayout(container, rawChildren, options = {}) {
     }
   }
   const heights = children.map((child) => child.offsetHeight);
+  const spans = heights.map((h) => Math.max(1, Math.ceil(h + targetGap)));
+  let changed = false;
+  for (let i3 = 0; i3 < children.length; i3++) {
+    const prev = children[i3].getAttribute(LAST_SPAN_ATTR);
+    if (prev !== String(spans[i3])) {
+      changed = true;
+      break;
+    }
+  }
+  if (!changed) return;
   for (let i3 = 0; i3 < children.length; i3++) {
-    const span = Math.max(1, Math.ceil(heights[i3] + targetGap));
-    children[i3].style.gridRowEnd = `span ${span}`;
+    children[i3].style.gridRowEnd = `span ${spans[i3]}`;
+    children[i3].setAttribute(LAST_SPAN_ATTR, String(spans[i3]));
   }
 }
 function countGridColumns(container) {
@@ -235,6 +244,8 @@ function clearMasonryLayout(container, rawChildren) {
     child.style.gridRowStart = "";
     child.style.gridRowEnd = "";
     child.style.alignSelf = "";
+    child.style.overflowAnchor = "";
+    child.removeAttribute(LAST_SPAN_ATTR);
     restoreOriginalColumn(child);
   }
 }

package/package.json

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

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

@@ -118,6 +118,29 @@ describe('applyMasonryLayout', () => {
     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);
@@ -173,6 +196,37 @@ describe('applyMasonryLayout', () => {
     expect(b.style.alignSelf).toBe('start');
   });
 
+  it('skips re-writing row-spans when measured heights match the cached value', () => {
+    // ResizeObserver fires freely on `<img>` decode in Firefox even when the
+    // parent's reserved aspect-ratio box hasn't actually changed. Without this
+    // short-circuit, every fire triggers a `grid-auto-flow: dense` re-pack —
+    // visible as image overlap during fast scroll because Firefox's compositor
+    // hasn't caught up with the newly shuffled item positions.
+    const container = makeContainer(10);
+    const item = makeItem(50);
+    container.append(item);
+    applyMasonryLayout(container, [item]);
+    expect(item.style.gridRowEnd).toBe('span 60');
+
+    // Simulate something else writing to gridRowEnd — if the polyfill re-runs
+    // unnecessarily, this would be overwritten.
+    item.style.gridRowEnd = 'span 999';
+    applyMasonryLayout(container, [item]);
+    expect(item.style.gridRowEnd).toBe('span 999');
+  });
+
+  it('re-writes row-spans when measured heights change', () => {
+    const container = makeContainer(10);
+    const item = makeItem(50);
+    container.append(item);
+    applyMasonryLayout(container, [item]);
+    expect(item.style.gridRowEnd).toBe('span 60');
+
+    Object.defineProperty(item, 'offsetHeight', { configurable: true, value: 80 });
+    applyMasonryLayout(container, [item]);
+    expect(item.style.gridRowEnd).toBe('span 90');
+  });
+
   it('clearMasonryLayout undoes container and child styles', () => {
     const container = makeContainer(10);
     const item = makeItem(50);

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

@@ -95,6 +95,16 @@ export type MasonryOptions = {
 // items pinned to their polyfill-assigned span.
 const ORIGINAL_COL_ATTR = 'data-bds-masonry-original-column';
 
+// Data attribute caching the last applied row-span. Used to short-circuit no-op
+// re-runs: when every child's newly-measured span matches the cached value, the
+// polyfill skips all writes. This prevents `grid-auto-flow: dense` from
+// re-packing on spurious ResizeObserver fires (subpixel fluctuations, `<img>`
+// decode in Firefox where offsetHeight briefly wobbles). Dense re-packing
+// during fast scroll in Firefox is visible as images overlapping, because
+// Firefox's compositor paints cached tiles from the pre-shuffle layout on top
+// of the newly laid out items for a frame or two.
+const LAST_SPAN_ATTR = 'data-bds-masonry-span';
+
 export function applyMasonryLayout(
   container: HTMLElement,
   rawChildren: HTMLElement[],
@@ -113,24 +123,31 @@ export function applyMasonryLayout(
   // `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.
+  // 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`
@@ -173,11 +190,27 @@ export function applyMasonryLayout(
   // O(N) forced-reflow cost of a read-then-write loop.
   const heights = children.map((child) => child.offsetHeight);
 
+  // Compute spans; skip the entire write pass if every span matches the
+  // previously-applied value. ResizeObserver fires freely in Firefox during
+  // image decode and scroll — without this guard, each fire triggers a dense
+  // re-pack that's visible as overlap on fast scroll (the compositor hasn't
+  // caught up with the newly shuffled positions).
+  const spans = heights.map((h) => Math.max(1, Math.ceil(h + targetGap)));
+  let changed = false;
+  for (let i = 0; i < children.length; i++) {
+    const prev = children[i].getAttribute(LAST_SPAN_ATTR);
+    if (prev !== String(spans[i])) {
+      changed = true;
+      break;
+    }
+  }
+  if (!changed) return;
+
   // Pass 3 — batch all row-span writes. No reads in between, so the browser can
   // coalesce style invalidation and do layout once for the whole batch.
   for (let i = 0; i < children.length; i++) {
-    const span = Math.max(1, Math.ceil(heights[i] + targetGap));
-    children[i].style.gridRowEnd = `span ${span}`;
+    children[i].style.gridRowEnd = `span ${spans[i]}`;
+    children[i].setAttribute(LAST_SPAN_ATTR, String(spans[i]));
   }
 }
 
@@ -222,6 +255,8 @@ export function clearMasonryLayout(container: HTMLElement, rawChildren: HTMLElem
     child.style.gridRowStart = '';
     child.style.gridRowEnd = '';
     child.style.alignSelf = '';
+    child.style.overflowAnchor = '';
+    child.removeAttribute(LAST_SPAN_ATTR);
     // Restore any `gridColumn` value the polyfill overwrote. Items the
     // polyfill never touched have no ORIGINAL_COL_ATTR and are left alone.
     restoreOriginalColumn(child);
@@ -251,31 +286,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;