feat: experimentalPagination page prop — new engine opt-in per document (#3505)

Author: diegomura

.changeset/experimental-pagination.md

@@ -0,0 +1,31 @@
+---
+'@react-pdf/layout': minor
+'@react-pdf/renderer': minor
+'@react-pdf/primitives': minor
+'@react-pdf/types': minor
+---
+
+Experimental pagination engine, opt-in per page
+
+A new pagination engine ships alongside the current one: content is
+measured once and packed into pages instead of relayouting on every split,
+making long documents paginate orders of magnitude faster (a 300-page
+document drops from ~40s to ~200ms).
+
+Opt in with `<Page experimentalPagination>` — any page opting in switches
+the whole document. The default behavior is unchanged.
+
+Under the new engine:
+
+- `<Page layout={Layout}>` renders per-page chrome (headers, footers,
+  sidebars) around the content. The layout component receives
+  `{ pageNumber, totalPages, subPageNumber, subPageTotalPages }` and the
+  page content as `children`, and runs once per output page. Using `layout`
+  implies `experimentalPagination`.
+- One `fixed` semantic: in-flow fixed elements repeat at the top of every
+  page they span; footers are the layout's job.
+- `minPresenceAhead` is supported, with one refinement: a trailing element
+  with nothing after it stays in place instead of moving to its own page.
+
+The current engine remains the default until the next major, when the new
+engine takes over.

packages/layout/src/index.ts

@@ -20,11 +20,18 @@ import resolveLinkSubstitution from './steps/resolveLinkSubstitution';
 import resolvePaginationNext from './paginate';
 import { SafeDocumentNode } from './types';
 
-// The new pagination engine, shipped dark: flip to true to enable.
-const NEXT_PAGINATION: boolean = true;
+// The new engine is opt-in until the cutover major. Engines work on whole
+// documents, so any page asking for it — or using `layout`, which requires
+// it — switches the document.
+const wantsNextPagination = (root: SafeDocumentNode) =>
+  root.children.some(
+    (page) =>
+      (page.props as any)?.experimentalPagination ||
+      (page.props as any)?.layout,
+  );
 
 const paginationStep = (root: SafeDocumentNode, fontStore) =>
-  NEXT_PAGINATION
+  wantsNextPagination(root)
     ? resolvePaginationNext(root, fontStore)
     : resolvePagination(root, fontStore);
 

packages/layout/src/types/page.ts

@@ -88,6 +88,10 @@ interface PageProps extends NodeProps {
    * @see https://react-pdf.org/components#page-wrapping
    */
   wrap?: boolean;
+  /**
+   * Opt the document into the new pagination engine. Implied by `layout`.
+   */
+  experimentalPagination?: boolean;
   size?: PageSize;
   orientation?: Orientation;
   dpi?: number;

packages/layout/tests/engineSelection.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, test } from 'vitest';
+import FontStore from '@react-pdf/font';
+
+import layout from '../src';
+
+const fontStore = new FontStore();
+
+const view = (style: any, props: any = {}): any => ({
+  type: 'VIEW',
+  props,
+  style,
+  box: {},
+  children: [],
+});
+
+// A trailing minPresenceAhead is the one place the engines diverge: legacy
+// moves the node to its own page, the new engine leaves it in place. That
+// difference tells us which engine ran.
+const doc = (pageProps: any = {}): any => ({
+  type: 'DOCUMENT',
+  props: {},
+  children: [
+    {
+      type: 'PAGE',
+      props: { size: [100, 100], ...pageProps },
+      style: {},
+      box: {},
+      children: [
+        view({ height: 60 }),
+        view({ height: 30 }, { minPresenceAhead: 500 }),
+      ],
+    },
+  ],
+});
+
+describe('pagination engine selection', () => {
+  test('legacy by default', async () => {
+    const result = await layout(doc(), fontStore);
+
+    expect(result.children).toHaveLength(2);
+  });
+
+  test('experimentalPagination opts into the new engine', async () => {
+    const result = await layout(
+      doc({ experimentalPagination: true }),
+      fontStore,
+    );
+
+    expect(result.children).toHaveLength(1);
+  });
+
+  test('a page layout implies the new engine', async () => {
+    const pageLayout = (_: any, children: any[]) => children;
+    const result = await layout(doc({ layout: pageLayout }), fontStore);
+
+    expect(result.children).toHaveLength(1);
+  });
+});

packages/renderer/index.d.ts

@@ -112,9 +112,16 @@ declare namespace ReactPDF {
      * A template component rendered around every page this Page produces.
      * Where it renders `children` is where page content flows; everything
      * else repeats as page chrome with its space reserved. Like render
-     * props, layout components may not use hooks.
+     * props, layout components may not use hooks. Implies
+     * `experimentalPagination`.
      */
     layout?: (props: PageLayoutProps) => React.ReactNode;
+    /**
+     * Opt the document into the new pagination engine: content is measured
+     * once and packed into pages, dramatically faster on long documents.
+     * Any page opting in switches the whole document. Implied by `layout`.
+     */
+    experimentalPagination?: boolean;
     /**
      * Enables debug mode on page bounding box.
      * @see https://react-pdf.org/advanced#debugging