@boostdev/design-system-components 2.4.1 → 2.5.0

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

@@ -65,7 +65,15 @@ function resolvePreferredColumns(
  * `grid-template-rows: masonry` value, the polyfill yields to CSS.
  */
 
-const ROW_UNIT_PX = 1;
+// Target ceiling on the implicit grid row count produced by the polyfill.
+// Browsers cap implicit grid tracks for resource-protection — historically
+// Chromium at 1000 and Firefox at ~10000; past the cap, the layout engine
+// clamps/wraps items and they overlap visually (e.g. bottom thumbnails of a
+// long masonry stack on top of each other in Firefox). The auto-tuner picks
+// a `rowUnitPx` so the projected row count stays under this number. Lower
+// is safer; higher gives finer (more pixel-accurate) row gaps. 5000 leaves
+// 2× headroom under the strictest reasonable cap.
+const TARGET_MAX_IMPLICIT_ROWS = 5000;
 
 export function supportsNativeMasonry(): boolean {
   if (typeof CSS === 'undefined' || typeof CSS.supports !== 'function') return false;
@@ -87,6 +95,17 @@ export type MasonryOptions = {
    * budget for the demotion calculation.
    */
   preferredColumnSpan?: Exclude<GridItemSpanValue, 'auto'>;
+  /**
+   * Manual override for the row-track unit (in pixels) the polyfill uses for
+   * `grid-auto-rows` and as the ceil() granularity of each item's row span.
+   * When omitted (recommended), the polyfill auto-picks the smallest unit that
+   * keeps projected implicit row count under `TARGET_MAX_IMPLICIT_ROWS`.
+   *
+   * Trade-off: smaller = more pixel-accurate row gaps; larger = more headroom
+   * under browser implicit-grid-track caps for very long galleries. Set this
+   * only if you've confirmed the auto-tuner is wrong for your case.
+   */
+  rowUnitPx?: number;
 };
 
 // Data attribute used to remember an auto item's inline `grid-column` before the
@@ -95,6 +114,24 @@ 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';
+
+// Container attribute caching the last applied row-unit (px). When the
+// auto-tuner picks a different unit on a re-run (e.g. children added pushed
+// the projected row count past the threshold), every per-child cached span
+// becomes stale because they were computed against the old unit — we clear
+// them so the next diff check forces a full rewrite. Cleared in
+// clearMasonryLayout.
+const UNIT_ATTR = 'data-bds-masonry-unit';
+
 export function applyMasonryLayout(
   container: HTMLElement,
   rawChildren: HTMLElement[],
@@ -107,7 +144,6 @@ export function applyMasonryLayout(
   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';
   // `dense` + per-child `ResizeObserver` can fight the browser's scroll anchoring:
@@ -180,11 +216,66 @@ export function applyMasonryLayout(
   // O(N) forced-reflow cost of a read-then-write loop.
   const heights = children.map((child) => child.offsetHeight);
 
+  // Pick the row-track unit. Manual override wins; otherwise auto-tune.
+  //
+  // Auto-tune uses the projected implicit row count (assuming ideal `dense`
+  // packing across the current grid columns) and picks the smallest unit such
+  // that the projection stays under TARGET_MAX_IMPLICIT_ROWS. Galleries that
+  // don't risk hitting any browser cap stay at unit=1 and get pixel-perfect
+  // gaps; only galleries large enough to threaten the cap pay the rounding
+  // cost. The unit always grows monotonically with content, so once a gallery
+  // is above the threshold its layout is stable across runs.
+  const cols = countGridColumns(container) || 1;
+  const totalRowSum = heights.reduce(
+    (s, h) => s + Math.max(1, Math.ceil(h + targetGap)),
+    0,
+  );
+  const projectedRows = totalRowSum / cols;
+  const autoUnit = Math.max(
+    1,
+    Math.ceil(projectedRows / TARGET_MAX_IMPLICIT_ROWS),
+  );
+  const rowUnit =
+    options.rowUnitPx !== undefined && options.rowUnitPx > 0
+      ? Math.floor(options.rowUnitPx)
+      : autoUnit;
+
+  // Apply the chosen unit. Setting `gridAutoRows` here (not before measurement)
+  // is safe because `align-self: start` makes offsetHeight return the content
+  // height regardless of the cell size — heights are independent of the unit.
+  container.style.gridAutoRows = `${rowUnit}px`;
+
+  // If the unit changed since the last run, every cached span is stale.
+  // Force a re-write by clearing the cache attributes before the diff check.
+  const prevUnit = container.getAttribute(UNIT_ATTR);
+  if (prevUnit !== String(rowUnit)) {
+    for (const child of children) child.removeAttribute(LAST_SPAN_ATTR);
+    container.setAttribute(UNIT_ATTR, String(rowUnit));
+  }
+
+  // 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) / rowUnit)),
+  );
+  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]));
   }
 }
 
@@ -223,6 +314,7 @@ export function clearMasonryLayout(container: HTMLElement, rawChildren: HTMLElem
   container.style.gridAutoFlow = '';
   container.style.rowGap = '';
   container.style.overflowAnchor = '';
+  container.removeAttribute(UNIT_ATTR);
   for (const child of rawChildren) {
     if (child.nodeType !== 1) continue;
     child.style.gridRow = '';
@@ -230,6 +322,7 @@ export function clearMasonryLayout(container: HTMLElement, rawChildren: HTMLElem
     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);
@@ -252,24 +345,66 @@ export function useMasonry(
   enabled: boolean,
   options: MasonryOptions = {},
 ): void {
-  const { preferredColumnSpan } = options;
+  const { preferredColumnSpan, rowUnitPx } = options;
   useLayoutEffect(() => {
     const container = ref.current;
     if (!container || !enabled) return;
     if (supportsNativeMasonry()) return;
 
     let frame = 0;
-    const runNow = () => {
-      cancelAnimationFrame(frame);
+    let scrollTimer: ReturnType<typeof setTimeout> | null = null;
+    let scrolling = false;
+    let pending = false;
+
+    const apply = () => {
       applyMasonryLayout(container, Array.from(container.children) as HTMLElement[], {
         preferredColumnSpan,
+        rowUnitPx,
       });
     };
+    const runNow = () => {
+      cancelAnimationFrame(frame);
+      apply();
+    };
     const schedule = () => {
       cancelAnimationFrame(frame);
       frame = requestAnimationFrame(runNow);
     };
 
+    // RO-triggered re-runs (resizes of existing items — image decode, font swap) are
+    // the ones that cause the Firefox compositor race: `grid-auto-flow: dense` re-packs
+    // already-laid-out items, and cached tiles from the pre-shuffle layout paint over
+    // the new positions for a frame or two, looking like overlap. Deferring *those*
+    // writes until scroll stops hides the race. Initial mount and MutationObserver-
+    // triggered runs (new children added) must NOT defer — a skeleton mounting during
+    // active scroll would otherwise stay at `grid-auto-rows: 1px` height, invisibly
+    // collapsed, until scroll idles.
+    const onResize = () => {
+      if (scrolling) {
+        pending = true;
+        return;
+      }
+      apply();
+    };
+
+    const SCROLL_IDLE_MS = 150;
+    const onScroll = () => {
+      scrolling = true;
+      if (scrollTimer) clearTimeout(scrollTimer);
+      scrollTimer = setTimeout(() => {
+        scrolling = false;
+        scrollTimer = null;
+        if (pending) {
+          pending = false;
+          apply();
+        }
+      }, SCROLL_IDLE_MS);
+    };
+    // `capture: true` catches scroll events from any nested scroll container, since
+    // scroll doesn't bubble. `passive: true` tells the browser we won't preventDefault —
+    // critical for not blocking scroll performance.
+    window.addEventListener('scroll', onScroll, { passive: true, capture: true });
+
     schedule();
 
     // ResizeObserver fires during the "update the rendering" step, AFTER layout and
@@ -278,9 +413,10 @@ export function useMasonry(
     // 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.
+    // scroll through a long gallery. (onResize itself still defers writes when the
+    // user is actively scrolling — see its `scrolling` guard above.)
     const ro =
-      typeof ResizeObserver !== 'undefined' ? new ResizeObserver(runNow) : null;
+      typeof ResizeObserver !== 'undefined' ? new ResizeObserver(onResize) : null;
     const observeDescendants = (child: Element) => {
       if (!ro) return;
       ro.observe(child);
@@ -315,9 +451,11 @@ export function useMasonry(
 
     return () => {
       cancelAnimationFrame(frame);
+      if (scrollTimer) clearTimeout(scrollTimer);
+      window.removeEventListener('scroll', onScroll, { capture: true } as EventListenerOptions);
       ro?.disconnect();
       mo?.disconnect();
       clearMasonryLayout(container, Array.from(container.children) as HTMLElement[]);
     };
-  }, [ref, enabled, preferredColumnSpan]);
+  }, [ref, enabled, preferredColumnSpan, rowUnitPx]);
 }