@boostdev/design-system-components 2.4.0 → 2.4.1

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);

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

@@ -113,24 +113,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`
@@ -222,6 +229,7 @@ export function clearMasonryLayout(container: HTMLElement, rawChildren: HTMLElem
     child.style.gridRowStart = '';
     child.style.gridRowEnd = '';
     child.style.alignSelf = '';
+    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);
@@ -251,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;