fix: include fixed siblings and margins in next-page box.top synthesis

exoego · exoego · commit f1d8b6f99a15 · 2026-06-10T13:47:17.000+09:00
The relayout-skip optimization left nextPage input with stale box.top values.
For a page with a normal-flow fixed header above a flex:1 body, the next
splitPage iteration saw the body at top=0 instead of below the header.
splitChildren then over-allocated content into subsequent pages and yoga
flex-shrank the result on render.
diff --git a/.changeset/two-pane-page-relative-top.md b/.changeset/two-pane-page-relative-top.md
@@ -0,0 +1,5 @@
+---
+"@react-pdf/layout": patch
+---
+
+fix: synthesize page-relative `box.top` for nodes pushed to the next page during pagination so subsequent iterations match what a yoga relayout would have produced. This accounts for normal-flow fixed siblings (e.g., a fixed header above a flex:1 body) and for sibling margins (`marginTop`/`marginBottom`). Without these, common two-pane report layouts packed too much content onto subsequent pages, causing yoga to flex-shrink content and overflow page borders.
diff --git a/packages/layout/src/steps/resolvePagination.ts b/packages/layout/src/steps/resolvePagination.ts
@@ -85,46 +85,90 @@ const warnUnavailableSpace = (node: SafeNode) => {
   );
 };
 
+const isAbsolutePositioned = (node: SafeNode) =>
+  node.style?.position === 'absolute';
+
+// Sum the vertical space a node would occupy in a flex column: top margin +
+// height + bottom margin. Yoga's flex layout positions siblings using this
+// (margins do not collapse in flexbox), so we mirror it when synthesizing
+// next-page positions without a yoga relayout.
+const getOutsetHeight = (node: SafeNode) =>
+  (node.box?.marginTop || 0) +
+  (node.box?.height || 0) +
+  (node.box?.marginBottom || 0);
+
 const splitNodes = (height: number, contentArea: number, nodes: SafeNode[]) => {
   const currentChildren: SafeNode[] = [];
   const nextChildren: SafeNode[] = [];
   const suffixFurthestEnd = computeSuffixFurthestEnd(nodes);
   const fixedIndices = collectFixedIndices(nodes);
+  const length = nodes.length;
 
   const pushFutureFixed = (target: SafeNode[], afterIndex: number) => {
     for (const idx of fixedIndices) {
       if (idx > afterIndex) target.push(nodes[idx]);
     }
   };
 
-  // Adjust box.top for remaining nodes that are pushed to nextChildren without relayout.
-  // Fixed nodes keep their positions (absolute positioning).
-  const adjustRemaining = (fromIndex: number): SafeNode[] =>
-    nodes.slice(fromIndex).map((node) => {
-      if (isFixed(node)) return node;
-      return Object.assign({}, node, {
-        box: Object.assign({}, node.box, { top: node.box.top - height }),
-      });
+  // The next iteration's splitNodes makes decisions from `box.top`/`box.height`.
+  // To match what yoga's relayout would have produced (the dropped step), we
+  // synthesize page-relative positions: cumFixedHeight is the bottom edge of the
+  // last normal-flow fixed sibling, cumNonFixedNextHeight is the bottom edge of
+  // the last non-fixed sibling already pushed to nextChildren.
+  let cumFixedHeight = 0;
+  let cumNonFixedNextHeight = 0;
+
+  // Returns `node` cloned with `box.top` set to its expected position on the
+  // next page. Mutates the running cursor — must only be called when pushing to
+  // nextChildren, in left-to-right sibling order.
+  const placeOnNextPage = (node: SafeNode): SafeNode => {
+    const marginTop = node.box?.marginTop || 0;
+    const newTop = cumFixedHeight + cumNonFixedNextHeight + marginTop;
+    cumNonFixedNextHeight += getOutsetHeight(node);
+    return Object.assign({}, node, {
+      box: Object.assign({}, node.box, { top: newTop }),
     });
+  };
+
+  // Keep cumFixedHeight in sync for normal-flow fixed siblings we encounter
+  // after the loop's break point — without this, non-fixed siblings that
+  // follow them in nextChildren would be positioned too high.
+  const advanceFixed = (node: SafeNode) => {
+    if (!isAbsolutePositioned(node)) {
+      cumFixedHeight += getOutsetHeight(node);
+    }
+  };
+
+  const adjustRemaining = (fromIndex: number): SafeNode[] => {
+    const result: SafeNode[] = [];
+    for (let j = fromIndex; j < length; j += 1) {
+      const node = nodes[j];
+      if (isFixed(node)) {
+        result.push(node);
+        advanceFixed(node);
+        continue;
+      }
+      result.push(placeOnNextPage(node));
+    }
+    return result;
+  };
 
   let hasNonFixedPrevious = false;
 
-  const length = nodes.length;
   for (let i = 0; i < length; i += 1) {
     const child = nodes[i];
 
     if (isFixed(child)) {
       nextChildren.push(child);
       currentChildren.push(child);
+      advanceFixed(child);
       continue;
     }
 
     const nodeTop = getTop(child);
     const isOutside = height <= nodeTop;
     if (isOutside) {
-      const box = Object.assign({}, child.box, { top: child.box.top - height });
-      const next = Object.assign({}, child, { box });
-      nextChildren.push(next);
+      nextChildren.push(placeOnNextPage(child));
       continue;
     }
 
@@ -144,12 +188,12 @@ const splitNodes = (height: number, contentArea: number, nodes: SafeNode[]) => {
       hasNonFixedPrevious,
     );
     if (shouldBreak) {
-      const box = Object.assign({}, child.box, { top: child.box.top - height });
       const props = Object.assign({}, child.props, {
         wrap: true,
         break: false,
       });
-      const next = Object.assign({}, child, { box, props });
+      const placed = placeOnNextPage(child);
+      const next = Object.assign({}, placed, { props });
 
       pushFutureFixed(currentChildren, i);
       nextChildren.push(next, ...adjustRemaining(i + 1));
@@ -166,19 +210,14 @@ const splitNodes = (height: number, contentArea: number, nodes: SafeNode[]) => {
           pushFutureFixed(currentChildren, i);
           nextChildren.push(...adjustRemaining(i + 1));
         } else {
-          const box = Object.assign({}, child.box, {
-            top: child.box.top - height,
-          });
-          const next = Object.assign({}, child, { box });
-
           pushFutureFixed(currentChildren, i);
-          nextChildren.push(next, ...adjustRemaining(i + 1));
+          nextChildren.push(placeOnNextPage(child), ...adjustRemaining(i + 1));
         }
         break;
       }
 
       if (currentChild) currentChildren.push(currentChild);
-      if (nextChild) nextChildren.push(nextChild);
+      if (nextChild) nextChildren.push(placeOnNextPage(nextChild));
 
       hasNonFixedPrevious = true;
       continue;
diff --git a/packages/layout/tests/steps/twoPaneRegression.test.ts b/packages/layout/tests/steps/twoPaneRegression.test.ts
@@ -0,0 +1,178 @@
+import { describe, expect, test } from 'vitest';
+import FontStore from '@react-pdf/font';
+
+import { loadYoga } from '../../src/yoga';
+import resolvePagination from '../../src/steps/resolvePagination';
+import resolveDimensions from '../../src/steps/resolveDimensions';
+import { SafeDocumentNode, SafeNode } from '../../src/types';
+
+const fontStore = new FontStore();
+
+const calcLayout = (node: SafeDocumentNode) =>
+  resolvePagination(resolveDimensions(node, fontStore), fontStore);
+
+const makeBlock = (id: string, style: Record<string, number>): SafeNode =>
+  ({
+    type: 'VIEW',
+    style,
+    props: { id },
+    children: [],
+  }) as any;
+
+describe('pagination with page-level fixed siblings', () => {
+  // Regression for a bug in the splitNodes optimization: when a page has a
+  // normal-flow fixed sibling (header) above a flex:1 container that must split
+  // across pages, the next-page input was given box.top=0 instead of the actual
+  // header-offset position. splitChildren then computed availableHeight=wrapArea
+  // instead of wrapArea-headerHeight, packing too much content onto subsequent
+  // pages and causing yoga to compress sections (content loss).
+  test('flex:1 body below fixed header splits without losing content', async () => {
+    const yoga = await loadYoga();
+
+    const layout = calcLayout({
+      type: 'DOCUMENT',
+      yoga,
+      props: {},
+      children: [
+        {
+          type: 'PAGE',
+          props: {},
+          style: { width: 100, height: 100 },
+          children: [
+            {
+              type: 'VIEW',
+              style: { height: 20 },
+              props: { id: 'header', fixed: true },
+              children: [],
+            },
+            {
+              type: 'VIEW',
+              style: { flex: 1, position: 'relative' },
+              props: { id: 'body' },
+              children: [
+                {
+                  type: 'VIEW',
+                  style: {
+                    position: 'absolute',
+                    bottom: 0,
+                    left: 0,
+                    right: 0,
+                    height: 1,
+                  },
+                  props: { id: 'bottomBorder', fixed: true },
+                  children: [],
+                },
+                makeBlock('section1', { height: 50 }) as any,
+                makeBlock('section2', { height: 50 }) as any,
+                makeBlock('section3', { height: 50 }) as any,
+                makeBlock('section4', { height: 50 }) as any,
+                makeBlock('section5', { height: 50 }) as any,
+              ],
+            },
+          ],
+        },
+      ],
+    });
+    // 5 sections × 50pt = 250pt; body area per page = 100 - 20 (header) = 80pt.
+    // ceil(250 / 80) = 4 pages expected.
+    expect(layout.children.length).toBe(4);
+
+    // Verify the body on every page is laid out below the header.
+    for (const page of layout.children) {
+      const body = page.children!.find(
+        (c) => c.props && (c.props as any).id === 'body',
+      );
+      expect(body).toBeDefined();
+      expect(body!.box!.top).toBe(20);
+      expect(body!.box!.height).toBe(80);
+    }
+
+    // Verify no content was lost — the heights of all section fragments across
+    // pages should sum back to the original (50pt × 5 = 250pt). Buggy behavior
+    // compresses sections via yoga shrink and the sum is < 250.
+    const fragmentHeightById = new Map<string, number>();
+    for (const page of layout.children) {
+      const body = page.children!.find(
+        (c) => c.props && (c.props as any).id === 'body',
+      )!;
+      for (const child of body.children || []) {
+        const id = (child.props as any).id as string;
+        if (!id?.startsWith('section')) continue;
+        fragmentHeightById.set(
+          id,
+          (fragmentHeightById.get(id) || 0) + (child.box?.height ?? 0),
+        );
+      }
+    }
+    for (const [id, total] of fragmentHeightById) {
+      expect(total, `section ${id} total height after split`).toBe(50);
+    }
+    expect(fragmentHeightById.size).toBe(5);
+  });
+
+  // Regression for incomplete fix: cumulative tracking in splitNodes ignored
+  // marginTop/marginBottom of siblings. Yoga's layout positions siblings with
+  // these margins included, so without margin awareness the synthesized box.top
+  // values for the next page diverge from what yoga relayout would produce —
+  // splitNode's `current.style.height = height - nodeTop` becomes too large and
+  // yoga compresses content via flex-shrink.
+  test('header marginBottom shifts body splits and no content is compressed', async () => {
+    const yoga = await loadYoga();
+
+    const layout = calcLayout({
+      type: 'DOCUMENT',
+      yoga,
+      props: {},
+      children: [
+        {
+          type: 'PAGE',
+          props: {},
+          style: { width: 100, height: 100 },
+          children: [
+            {
+              type: 'VIEW',
+              style: { height: 20, marginBottom: 10 },
+              props: { id: 'header', fixed: true },
+              children: [],
+            },
+            makeBlock('section1', { height: 30 }) as any,
+            makeBlock('section2', { height: 30 }) as any,
+            makeBlock('section3', { height: 30 }) as any,
+            makeBlock('section4', { height: 30 }) as any,
+            makeBlock('section5', { height: 30 }) as any,
+          ],
+        },
+      ],
+    });
+
+    // Effective space below header per page = 100 - 20 - 10 (mb) = 70.
+    // 5 sections × 30pt = 150pt; ceil(150 / 70) = 3 pages expected.
+    expect(layout.children.length).toBe(3);
+
+    // Heights of each section across pages should sum to original 30.
+    const fragmentHeightById = new Map<string, number>();
+    for (const page of layout.children) {
+      for (const child of page.children || []) {
+        const id = (child.props as any).id as string;
+        if (!id?.startsWith('section')) continue;
+        fragmentHeightById.set(
+          id,
+          (fragmentHeightById.get(id) || 0) + (child.box?.height ?? 0),
+        );
+      }
+    }
+    for (const [id, total] of fragmentHeightById) {
+      expect(total, `section ${id} total height after split`).toBe(30);
+    }
+    expect(fragmentHeightById.size).toBe(5);
+
+    // Header must keep its original height on every page (no flex-shrink).
+    for (const page of layout.children) {
+      const header = page.children!.find(
+        (c) => c.props && (c.props as any).id === 'header',
+      );
+      expect(header).toBeDefined();
+      expect(header!.box!.height).toBe(20);
+    }
+  });
+});
diff --git a/packages/renderer/tests/snapshots/two-pane-table-test-jsx-tests-two-pane-table-test-jsx-two-pane-table-page-wrap-should-match-snapshot-1-snap.png b/packages/renderer/tests/snapshots/two-pane-table-test-jsx-tests-two-pane-table-test-jsx-two-pane-table-page-wrap-should-match-snapshot-1-snap.png
diff --git a/packages/renderer/tests/twoPaneTable.test.jsx b/packages/renderer/tests/twoPaneTable.test.jsx
@@ -0,0 +1,74 @@
+import { describe, expect, test } from 'vitest';
+
+import { Document, Page, View, Text, StyleSheet } from '@react-pdf/renderer';
+import renderToImage from './renderComponent';
+
+const BORDER = '1pt solid #000';
+
+const styles = StyleSheet.create({
+  header: {
+    height: 30,
+    borderBottom: BORDER,
+    backgroundColor: '#f0f0f0',
+    flexDirection: 'row',
+    paddingHorizontal: 4,
+    alignItems: 'center',
+  },
+  body: {
+    borderLeft: BORDER,
+    borderRight: BORDER,
+    flex: 1,
+    position: 'relative',
+  },
+  bottomBorder: {
+    position: 'absolute',
+    bottom: 0,
+    left: -1,
+    right: -1,
+    borderBottom: BORDER,
+  },
+  row: {
+    height: 25,
+    borderBottom: '0.5pt solid #888',
+    flexDirection: 'row',
+    alignItems: 'center',
+    paddingHorizontal: 4,
+  },
+  rowLabel: { flex: 1, fontSize: 7 },
+  rowValue: { flex: 1, fontSize: 7 },
+});
+
+const Row = ({ no }) => (
+  <View style={styles.row} wrap={false}>
+    <Text style={styles.rowLabel}>Row {no} label</Text>
+    <Text style={styles.rowValue}>Row {no} value</Text>
+  </View>
+);
+
+const rowCount = 16;
+
+const TwoPaneTable = () => (
+  <Document>
+    <Page size={[260, 200]} style={{ padding: 8 }}>
+      <View style={styles.header} fixed>
+        <Text style={{ fontSize: 8 }}>Report header (fixed, 30pt tall)</Text>
+      </View>
+
+      <View style={styles.body}>
+        <View style={styles.bottomBorder} fixed />
+
+        {Array.from({ length: rowCount }, (_, i) => (
+          <Row key={i} no={i + 1} />
+        ))}
+      </View>
+    </Page>
+  </Document>
+);
+
+describe('two-pane table page wrap', () => {
+  test('should match snapshot', async () => {
+    const image = await renderToImage(<TwoPaneTable />);
+
+    expect(image).toMatchImageSnapshot();
+  }, 30_000);
+});

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +"@react-pdf/layout": patch
 +---
++
 +fix: synthesize page-relative `box.top` for nodes pushed to the next page during pagination so subsequent iterations match what a yoga relayout would have produced. This accounts for normal-flow fixed siblings (e.g., a fixed header above a flex:1 body) and for sibling margins (`marginTop`/`marginBottom`). Without these, common two-pane report layouts packed too much content onto subsequent pages, causing yoga to flex-shrink content and overflow page borders.