[JoelBrenstrum]

Problem

splitNodes has a special case for a node whose children all end up on the next page: if currentChildren.length === 0 it keeps the whole node on the current page, on the assumption that the page is empty and moving the node would only produce an empty page. That check only looks at the node's own siblings, so it also fires for a node that is merely the first child of its parent, however deep it sits on a page that already has content.

When that happens the node's box is clamped to the page edge by splitNode, but its children keep their full layout and are drawn past the bottom margin, over the footer. No warning is logged.

A minimal document that shows it:

Page (height 100)
├── View (height 30)
└── View
    └── View
        └── View wrap={false} (height 80)

The unwrappable view fits on a page but not in the 70pt left under the first view. Its parent has no earlier siblings, so the parent is kept on page 1 with the 80pt view clipped at the page edge, and the document stays one page long.

We hit this with form documents that render option groups as wrap={false} rows inside a chain of single-child containers: whenever the group started near the bottom of a page its last rows were cut off.

Related issues

• Fixes Content taller than one page is squashed/overlapped at the bottom instead of flowing onto the next page #3449. fix(layout): don't squash a container's sole child at a page break (#3449) #3450 proposes the same page-start flag through splitNodes; this PR additionally ignores zero-height siblings when deciding whether the page is empty above a node, and carries the flag into shouldBreak.
• Fixes minPresenceAhead not working #3586 (and the earlier minPresenceAhead Not working? #3233): minPresenceAhead on the first child of a View that is not the first element on the page.
• Fixes the second case in Text overlaps / squashes when using wrap={false} #3588, two columns whose first child is a small wrap={false} block near the page bottom. Its first case, a wrap={false} block taller than a page, is a separate limitation and is not changed here.
• Looks like the same mechanism as the blank trailing page in Page break is created but no content is pushed to the new page #2969 and the squashed nested wrap={false} view in Text in nested view with wrap={false} being compressed/squished after upgrading from v3.1.2 to v3.4.4  #2904.

I ran the repros from #3449, #3586 and #3588 against this branch. In each one the block starts the next page and nothing is drawn past the bottom margin.

Only the legacy engine is affected. The new engine behind experimentalPagination (#3502) already paginates these documents correctly, but the legacy engine is still the default in @react-pdf/layout 5.2.0.

Reproduction

Open in the REPL (runs against the published packages, @react-pdf/layout 5.2.0 with the default legacy engine at the time of writing).

Page 1 ends with the pink block drawn through the bottom margin and over the footer, and page 2 contains nothing but the footer. With this change the block starts page 2.

REPL source

import React from 'react';
import ReactPDF, { Document, Page, View, Text } from '@react-pdf/renderer';

// A wrap={false} block that fits on a page but not in the space left on the
// current one. Because it is the first child of its parent, react-pdf keeps the
// parent on page 1: the block is drawn past the bottom margin, over the footer,
// and page 2 only receives an empty leftover view.
const lines = Array.from({ length: 20 }, (_, i) => (
  <Text key={i}>{`line ${i + 1} of the block that should start on page 2`}</Text>
));

const Repro = () => (
  <Document>
    <Page size="A4" style={{ padding: 30, fontSize: 12 }}>
      <View style={{ height: 600, backgroundColor: '#e8e8e8', padding: 10 }}>
        <Text>Content above (600pt tall)</Text>
      </View>

      <View>
        <View>
          <View wrap={false} style={{ minHeight: 300, backgroundColor: '#f7b2a6', padding: 10 }}>
            {lines}
          </View>
        </View>
      </View>

      <Text
        fixed
        style={{ position: 'absolute', bottom: 12, left: 30 }}
        render={({ pageNumber, totalPages }) => `page ${pageNumber} / ${totalPages}`}
      />
    </Page>
  </Document>
);

ReactPDF.render(<Repro />);

Fix

• Thread a pageStart flag from splitPage through splitNodes → split → splitView → splitChildren, so the keep-on-page behaviour only applies when every ancestor is also at the top of the page. Fixed and zero-height siblings are ignored when deciding that, so a page footer or an empty element does not count as content.
• shouldBreak receives the same flag and honours minPresenceAhead on a first child that is not at the page start. Previously a first child could never break for presence, which stranded headings at the foot of a page. Direct callers that omit the argument keep the previous behaviour.

Nothing changes for nodes that genuinely are at the start of a page, so the existing infinite-loop guards still hold. The new should keep a nested first child on the page when it is already at the page start test covers that.

Tests

• resolvePagination.test.ts: nested first child moves to the next page; nested first child at the page start stays; minPresenceAhead on a first child that is not at the page start.
• shouldBreak.test.ts: the non-page-start minPresenceAhead case.

The two behavioural pagination tests fail on master and pass with this change. The full @react-pdf/layout suite passes (365 tests).

Includes a changeset for @react-pdf/layout.

🤖 Generated with Claude Code

[vercel]

@JoelBrenstrum is attempting to deploy a commit to the diegomura Team on Vercel.

A member of the Team first needs to authorize it.

[changeset-bot]

🦋 Changeset detected

Latest commit: 43a1103

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 6 packages

Name	Type
@react-pdf/layout	Patch
@react-pdf/renderer	Patch
@react-pdf/examples	Patch
@react-pdf/math	Patch
@react-pdf/mermaid	Patch
@react-pdf/ui	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR