@boostdev/design-system-components 2.4.1 → 2.5.0

package/dist/web-components/index.js

@@ -151,16 +151,17 @@ function resolvePreferredColumns(container, value, totalCols) {
   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;
+var TARGET_MAX_IMPLICIT_ROWS = 5e3;
 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";
+var LAST_SPAN_ATTR = "data-bds-masonry-span";
+var UNIT_ATTR = "data-bds-masonry-unit";
 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";
@@ -198,9 +199,38 @@ function applyMasonryLayout(container, rawChildren, options = {}) {
     }
   }
   const heights = children.map((child) => child.offsetHeight);
+  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 !== void 0 && options.rowUnitPx > 0 ? Math.floor(options.rowUnitPx) : autoUnit;
+  container.style.gridAutoRows = `${rowUnit}px`;
+  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));
+  }
+  const spans = heights.map(
+    (h) => Math.max(1, Math.ceil((h + targetGap) / rowUnit))
+  );
+  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) {
@@ -227,6 +257,7 @@ function clearMasonryLayout(container, rawChildren) {
   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 = "";
@@ -234,6 +265,7 @@ function clearMasonryLayout(container, rawChildren) {
     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.1",
+  "version": "2.5.0",
   "description": "BoostDev React component library: accessible, token-driven components built on @boostdev/design-system-foundation",
   "keywords": [
     "React",
@@ -26,7 +26,6 @@
   "type": "module",
   "exports": {
     ".": {
-      "react-native": "./dist/native/index.js",
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
@@ -262,7 +261,6 @@
     "./css/section-header": "./src/components/layout/SectionHeader/SectionHeader.module.css"
   },
   "main": "./dist/index.js",
-  "react-native": "./dist/native/index.js",
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
@@ -297,14 +295,12 @@
     "@types/node": "^25.5.0",
     "@types/react": "^19",
     "@types/react-dom": "^19",
-    "@types/react-native": "^0.73.0",
     "@vitejs/plugin-react": "^5.1.4",
     "eslint": "^9",
     "git-cliff": "^2.12.0",
     "identity-obj-proxy": "^3.0.0",
     "jsdom": "^28.1.0",
     "lit": "^3.3.2",
-    "react-native-web": "^0.21.2",
     "remark-gfm": "^4.0.1",
     "storybook": "^8.6.18",
     "storybook-addon-tag-badges": "^1.4.0",
@@ -321,15 +317,11 @@
   "peerDependencies": {
     "@boostdev/design-system-foundation": ">=2.0.0",
     "react": ">=18",
-    "react-dom": ">=18",
-    "react-native": ">=0.70"
+    "react-dom": ">=18"
   },
   "peerDependenciesMeta": {
     "react-dom": {
       "optional": true
-    },
-    "react-native": {
-      "optional": true
     }
   },
   "publishConfig": {

package/src/components/layout/Grid/Grid.mdx

@@ -131,7 +131,7 @@ Set `isMasonry` on any `Grid` to switch to a masonry (a.k.a. Pinterest-style) la
 Masonry targets [CSS Grid Layout Module Level 3](https://www.w3.org/TR/css-grid-3/) ("grid lanes"):
 
 - **Native path** — when the browser supports `display: grid-lanes` or `grid-template-rows: masonry`, CSS handles everything and the JS polyfill short-circuits. Currently Safari Technology Preview only; the polyfill runs in all other browsers.
-- **Polyfill path** — row-span packing. The container's row tracks are collapsed to a 1 px auto-track with `grid-auto-flow: dense`, and each item is given a `grid-row-end: span ceil(height + gap)`. Items stay in **normal document flow** (no absolute positioning), so surrounding content — footers, scroll anchors, page margins — lays out correctly around the grid.
+- **Polyfill path** — row-span packing. The container's row tracks are collapsed to a small auto-track with `grid-auto-flow: dense`, and each item is given a `grid-row-end: span ceil((height + gap) / rowUnit)`. Items stay in **normal document flow** (no absolute positioning), so surrounding content — footers, scroll anchors, page margins — lays out correctly around the grid. The row-unit defaults to 1 px; for very long galleries the polyfill auto-grows it — see [Row-unit auto-tuner](#row-unit-auto-tuner).
 
 The polyfill re-runs on child size changes (`ResizeObserver` on each child) and child addition/removal (`MutationObserver` on the container). The container itself is not observed — setting row-spans changes the container block-size, which would loop back through the observer.
 
@@ -145,7 +145,7 @@ The polyfill re-runs on child size changes (`ResizeObserver` on each child) and
 
 - **Initial layout** — three passes (clear, batch-read all heights, batch-write all spans). Height reads and writes are each grouped to avoid O(N) forced reflows; the measured cost is one layout pass regardless of item count.
 - **Re-layout** — on child resize or mutation the polyfill is scheduled via `requestAnimationFrame`, so bursts of observer callbacks coalesce into a single re-run per frame.
-- **Ceil overshoot** — the 1 px row track means each item's span can overshoot by up to 1 px. Not visible in practice (row-gap is 0; the gap is baked into each item's span).
+- **Ceil overshoot** — at the default 1 px row track each item's span can overshoot by up to 1 px. Not visible in practice (row-gap is 0; the gap is baked into each item's span). The auto-tuner may grow the row-unit for very long galleries — overshoot is then bounded by the chosen unit (still imperceptible at the unit sizes the auto-tuner picks).
 - **Long lists** — for galleries with hundreds of items, virtualisation is still the correct answer; masonry is orthogonal.
 
 ### SSR / hydration
@@ -237,6 +237,24 @@ Rules:
 
 Column detection runs inside the masonry polyfill's `useLayoutEffect`, so it only executes on the client after mount. The initial server render emits each auto item at its default `full` span until hydration resolves the first polyfill pass — which matches the existing masonry SSR behavior.
 
+## Row-unit auto-tuner
+
+Browsers cap the implicit grid track count for resource protection — historically Chromium at 1000 and Firefox at ~10000 tracks. Past that cap the engine clamps or wraps items, which the user sees as overlapping thumbnails toward the bottom of a long masonry stack. The polyfill expresses each item's height as a row-span (`ceil((height + gap) / rowUnit)`), so a long enough gallery at the default 1 px row-unit will hit the cap.
+
+To stay safely below it, the polyfill auto-tunes the row-unit on every layout pass:
+
+1. Project the implicit row count for the current children using the live column count (`sum(spans) / columns`).
+2. If the projection stays under the safe threshold (~5000 rows — 2× headroom under the strictest reasonable cap), keep the row-unit at 1 px and get pixel-accurate row gaps.
+3. If it would exceed the threshold, grow the row-unit just enough to bring the projection back under (`ceil(projectedRows / threshold)`). Each item's span is recomputed against the new unit; the per-child span cache is invalidated automatically when the unit changes between runs.
+
+This is automatic — most galleries never trigger it. For the rare case where you've measured the auto-tuner picking the wrong unit, escape with `masonryRowUnitPx`:
+
+```tsx
+<Grid isMasonry masonryRowUnitPx={4}>…</Grid>
+```
+
+Trade-off: smaller unit = more pixel-accurate row gaps; larger unit = more headroom under browser caps. Set this **only** when you've confirmed the auto-tuner is wrong for your case — the auto-pick is the right answer for almost every gallery.
+
 ## Migration from `@greenchoice/design-system`
 
 | Greenchoice                     | BoostDev equivalent                    |

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

@@ -1,5 +1,6 @@
 import { render, screen } from '@testing-library/react';
 import { act } from 'react';
+import { afterEach, beforeEach, vi } from 'vitest';
 import { Grid } from './Grid';
 import { GridItem, GridItemSpan } from './GridItem';
 import { applyMasonryLayout, clearMasonryLayout } from './masonry';
@@ -93,9 +94,12 @@ describe('applyMasonryLayout', () => {
     return el;
   }
 
-  it('overrides container to grid-auto-rows: 1px + grid-auto-flow: dense + row-gap: 0', () => {
+  it('overrides container to grid-auto-flow: dense + row-gap: 0 and picks a row-track unit', () => {
     const container = makeContainer(10);
     applyMasonryLayout(container, []);
+    // Auto-tuner picks 1px when the projected row count is well under
+    // the implicit-grid cap; long galleries get a larger unit (covered
+    // in dedicated tests below).
     expect(container.style.gridAutoRows).toBe('1px');
     expect(container.style.gridAutoFlow).toBe('dense');
     expect(container.style.rowGap).toBe('0px');
@@ -141,16 +145,15 @@ describe('applyMasonryLayout', () => {
     expect(a.style.overflowAnchor).toBe('');
   });
 
-  it('assigns grid-row-end: span ceil(height + targetGap) to each item', () => {
+  it('assigns grid-row-end: span ceil((height + targetGap) / rowUnit) to each item', () => {
     const container = makeContainer(10);
     const a = makeItem(100);
     const b = makeItem(201);
     container.append(a, b);
     applyMasonryLayout(container, [a, b]);
 
-    // ceil(100 + 10) = 110
+    // Auto-tuner stays at unit=1 here — projected rows is tiny.
     expect(a.style.gridRowEnd).toBe('span 110');
-    // ceil(201 + 10) = 211
     expect(b.style.gridRowEnd).toBe('span 211');
   });
 
@@ -196,6 +199,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);
@@ -211,6 +245,54 @@ describe('applyMasonryLayout', () => {
     expect(item.style.alignSelf).toBe('');
   });
 
+  describe('row-unit auto-tuner', () => {
+    it('grows the row-unit when projected implicit row count would exceed the safe threshold', () => {
+      // Build a worst-case scenario: many tall items in a single column so the
+      // projection equals sum(spans). 50 items × 600px each = 30,000 row-units
+      // at unit=1, well over the 5,000 threshold → auto picks unit=ceil(30000/5000)=6.
+      const container = makeContainer(0);
+      container.style.gridTemplateColumns = '100px';
+      const items = Array.from({ length: 50 }, () => makeItem(600));
+      container.append(...items);
+      applyMasonryLayout(container, items);
+      expect(container.style.gridAutoRows).toBe('6px');
+      // span = ceil(600 / 6) = 100
+      expect(items[0].style.gridRowEnd).toBe('span 100');
+    });
+
+    it('honors an explicit rowUnitPx override', () => {
+      const container = makeContainer(10);
+      const item = makeItem(100);
+      container.append(item);
+      applyMasonryLayout(container, [item], { rowUnitPx: 8 });
+      expect(container.style.gridAutoRows).toBe('8px');
+      // ceil((100 + 10) / 8) = 14
+      expect(item.style.gridRowEnd).toBe('span 14');
+    });
+
+    it('invalidates the per-child span cache when the row-unit changes between runs', () => {
+      const container = makeContainer(10);
+      const item = makeItem(100);
+      container.append(item);
+      applyMasonryLayout(container, [item], { rowUnitPx: 1 });
+      expect(item.style.gridRowEnd).toBe('span 110');
+      // Switching units must rewrite — without cache invalidation the diff
+      // check would short-circuit because the cached "110" still matches the
+      // newly-computed value (which would be 14 under unit=8).
+      applyMasonryLayout(container, [item], { rowUnitPx: 8 });
+      expect(item.style.gridRowEnd).toBe('span 14');
+    });
+
+    it('clearMasonryLayout removes the unit attribute so the next mount re-tunes', () => {
+      const container = makeContainer(10);
+      const item = makeItem(100);
+      container.append(item);
+      applyMasonryLayout(container, [item], { rowUnitPx: 8 });
+      clearMasonryLayout(container, [item]);
+      expect(container.hasAttribute('data-bds-masonry-unit')).toBe(false);
+    });
+  });
+
   describe('preferredColumnSpan', () => {
     function makeAutoItem(height: number) {
       const el = makeItem(height);
@@ -317,6 +399,126 @@ describe('applyMasonryLayout', () => {
   });
 });
 
+describe('useMasonry scroll debounce', () => {
+  // jsdom has no ResizeObserver — install a mock that captures the callback so
+  // tests can simulate an image decode firing during/outside of a scroll.
+  let roCallback: ResizeObserverCallback | null = null;
+  const originalRO = globalThis.ResizeObserver;
+
+  beforeEach(() => {
+    roCallback = null;
+    class MockResizeObserver {
+      constructor(cb: ResizeObserverCallback) {
+        roCallback = cb;
+      }
+      observe() {}
+      unobserve() {}
+      disconnect() {}
+    }
+    (globalThis as unknown as { ResizeObserver: typeof ResizeObserver }).ResizeObserver =
+      MockResizeObserver as unknown as typeof ResizeObserver;
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    if (originalRO) {
+      (globalThis as unknown as { ResizeObserver: typeof ResizeObserver }).ResizeObserver = originalRO;
+    } else {
+      delete (globalThis as unknown as Record<string, unknown>).ResizeObserver;
+    }
+  });
+
+  function stubHeight(el: Element, height: number) {
+    Object.defineProperty(el, 'offsetHeight', { configurable: true, value: height });
+  }
+
+  it('defers re-runs while the user is actively scrolling and applies them once scroll idles', () => {
+    // Regression: during fast scroll in Firefox, an image decode grows its GridItem,
+    // ResizeObserver fires, and the synchronous `grid-auto-flow: dense` re-pack
+    // races the compositor — items appear to overlap because cached tiles from the
+    // pre-shuffle layout are painted over the new layout for a frame or two.
+    const { container } = render(
+      <Grid isMasonry>
+        <GridItem data-testid="a">a</GridItem>
+      </Grid>,
+    );
+    const item = container.querySelector('[data-testid="a"]') as HTMLElement;
+    stubHeight(item, 100);
+
+    // Flush the initial rAF-scheduled layout pass.
+    act(() => {
+      vi.advanceTimersByTime(0);
+      // rAF in jsdom is backed by setTimeout(..., 0)
+    });
+    act(() => {
+      vi.runAllTimers();
+    });
+    const initialSpan = item.style.gridRowEnd;
+    expect(initialSpan).not.toBe('');
+
+    // User starts scrolling.
+    window.dispatchEvent(new Event('scroll'));
+
+    // Image decode grows the item; RO fires.
+    stubHeight(item, 300);
+    act(() => {
+      roCallback?.([] as unknown as ResizeObserverEntry[], {} as ResizeObserver);
+    });
+
+    // Mid-scroll: the new span is NOT applied — deferred until scroll idle.
+    expect(item.style.gridRowEnd).toBe(initialSpan);
+
+    // Scroll stops; after the idle window, the deferred layout pass runs.
+    act(() => {
+      vi.advanceTimersByTime(200);
+    });
+    expect(item.style.gridRowEnd).not.toBe(initialSpan);
+    expect(item.style.gridRowEnd).toBe('span 300');
+  });
+
+  it('still lays out newly-mounted children during active scroll', async () => {
+    // Regression: deferring the whole polyfill during scroll left skeletons
+    // invisible — a child mounted mid-scroll would keep `grid-auto-rows: 1px`
+    // and never receive a row-span write, collapsing to 1px tall until scroll
+    // stopped. Only RO-triggered resizes of already-laid-out items should
+    // defer; initial layout and MutationObserver-driven runs must not.
+    const stub = (h: number) => (el: HTMLElement | null) => {
+      if (el) stubHeight(el, h);
+    };
+
+    function Harness({ extra = false }: { extra?: boolean }) {
+      return (
+        <Grid isMasonry>
+          <GridItem data-testid="a" ref={stub(100)}>a</GridItem>
+          {extra ? <GridItem data-testid="b" ref={stub(80)}>b</GridItem> : null}
+        </Grid>
+      );
+    }
+
+    const { container, rerender } = render(<Harness />);
+    await act(async () => {
+      await vi.runAllTimersAsync();
+    });
+    const a = container.querySelector('[data-testid="a"]') as HTMLElement;
+    expect(a.style.gridRowEnd).not.toBe('');
+
+    // User is actively scrolling when the new child mounts.
+    window.dispatchEvent(new Event('scroll'));
+
+    await act(async () => {
+      rerender(<Harness extra />);
+    });
+    await act(async () => {
+      await vi.runAllTimersAsync();
+    });
+
+    const b = container.querySelector('[data-testid="b"]') as HTMLElement;
+    // The new child must have received a span even though we're mid-scroll.
+    expect(b.style.gridRowEnd).toBe('span 80');
+  });
+});
+
 describe('GridItem', () => {
   it('defaults to full span', () => {
     const { container } = render(<GridItem>x</GridItem>);

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

@@ -58,6 +58,16 @@ type GridOwnProps = WithClassName & {
    * keep their span.
    */
   masonryPreferredColumnSpan?: Exclude<GridItemSpanValue, 'auto'>;
+  /**
+   * Masonry only. 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. Omit to let the polyfill auto-pick the smallest unit
+   * that keeps the implicit row count under any browser cap — that's the
+   * right answer for almost every gallery and yields pixel-perfect row gaps
+   * when the gallery is short enough to not need rounding. Set this only if
+   * you've confirmed the auto-tuner is wrong for your case.
+   */
+  masonryRowUnitPx?: number;
   as?: ElementType;
 };
 
@@ -73,12 +83,16 @@ export function Grid<C extends ElementType = 'div'>({
   isMasonry = false,
   autoSpanMedia = false,
   masonryPreferredColumnSpan,
+  masonryRowUnitPx,
   as,
   style,
   ...rest
 }: GridProps<C>) {
   const ref = useRef<HTMLElement>(null);
-  useMasonry(ref, isMasonry, { preferredColumnSpan: masonryPreferredColumnSpan });
+  useMasonry(ref, isMasonry, {
+    preferredColumnSpan: masonryPreferredColumnSpan,
+    rowUnitPx: masonryRowUnitPx,
+  });
 
   const classNames = cn(
     css.grid,