feat(textkit): use best-fit line breaking for long text

Author: wojtekmaj

.changeset/tiny-hats-brake.md

@@ -0,0 +1,8 @@
+---
+'@react-pdf/layout': minor
+'@react-pdf/renderer': minor
+'@react-pdf/textkit': minor
+'@react-pdf/types': minor
+---
+
+Use faster best-fit line breaking for long non-justified text and expose a lineBreakStrategy option.

packages/layout/src/svg/layoutText.ts

@@ -124,7 +124,11 @@ const layoutTspan = (fontStore: FontStore) => (node, xOffset) => {
     fontStore?.getHyphenationCallback() ||
     null;
 
-  const layoutOptions = { hyphenationCallback, shrinkWhitespaceFactor };
+  const layoutOptions = {
+    hyphenationCallback,
+    lineBreakStrategy: node.props.lineBreakStrategy,
+    shrinkWhitespaceFactor,
+  };
   const lines = engine(attributedString, container, layoutOptions).flat();
 
   return Object.assign({}, node, { lines });

packages/layout/src/text/layoutText.ts

@@ -58,6 +58,7 @@ const getContainer = (width, height, node) => {
  */
 const getLayoutOptions = (fontStore, node) => ({
   hyphenationPenalty: node.props.hyphenationPenalty,
+  lineBreakStrategy: node.props.lineBreakStrategy,
   shrinkWhitespaceFactor: { before: -0.5, after: -0.5 },
   hyphenationCallback:
     node.props.hyphenationCallback ||

packages/layout/src/types/text.ts

@@ -21,6 +21,10 @@ interface TextProps extends NodeProps {
    * @see https://react-pdf.org/fonts#registerhyphenationcallback
    */
   hyphenationCallback?: HyphenationCallback;
+  /**
+   * Controls which line-breaking strategy textkit uses.
+   */
+  lineBreakStrategy?: 'auto' | 'best-fit' | 'knuth-plass';
   /**
    * Specifies the minimum number of lines in a text element that must be shown at the bottom of a page or its container.
    * @see https://react-pdf.org/advanced#orphan-&-widow-protection

packages/renderer/index.d.ts

@@ -254,6 +254,10 @@ declare namespace ReactPDF {
      * @see https://react-pdf.org/fonts#registerhyphenationcallback
      */
     hyphenationCallback?: HyphenationCallback;
+    /**
+     * Controls which line-breaking strategy textkit uses.
+     */
+    lineBreakStrategy?: 'auto' | 'best-fit' | 'knuth-plass';
     /**
      * Specifies the minimum number of lines in a text element that must be shown at the bottom of a page or its container.
      * @see https://react-pdf.org/advanced#orphan-&-widow-protection

packages/textkit/README.md

@@ -97,12 +97,13 @@ const result = bidiEngine(attributedString);
 
 ### linebreaker
 
-Performs line breaking using the Knuth-Plass algorithm with fallback to best-fit. Handles hyphenation points and produces optimal line breaks.
+Performs line breaking using the Knuth-Plass algorithm with fallback to best-fit. Handles hyphenation points and produces optimal line breaks. In `auto` mode, long non-justified text uses best-fit line breaking to avoid expensive global line optimization.
 
 ```js
 import { linebreaker } from '@react-pdf/textkit';
 
 const linebreakerEngine = linebreaker({
+  lineBreakStrategy: 'auto',
   tolerance: 4,
   hyphenationPenalty: 100,
 });
@@ -318,6 +319,7 @@ type LayoutOptions = {
     word: string | null,
     fallback: (word: string | null) => string[],
   ) => string[];
+  lineBreakStrategy?: 'auto' | 'best-fit' | 'knuth-plass';
   tolerance?: number;
   hyphenationPenalty?: number;
   expandCharFactor?: JustificationFactor;

packages/textkit/src/engines/linebreaker/index.ts

@@ -9,6 +9,7 @@ import { Node } from './types';
 const HYPHEN = 0x002d;
 const TOLERANCE_STEPS = 5;
 const TOLERANCE_LIMIT = 50;
+const BEST_FIT_THRESHOLD = 2000;
 
 const opts = {
   width: 3,
@@ -131,6 +132,20 @@ const getAttributes = (attributedString: AttributedString) => {
   return attributedString.runs?.[0]?.attributes || {};
 };
 
+const shouldUseBestFit = (
+  attributedString: AttributedString,
+  attributes: Attributes,
+  options: LayoutOptions,
+) => {
+  if (options.lineBreakStrategy === 'best-fit') return true;
+  if (options.lineBreakStrategy === 'knuth-plass') return false;
+
+  return (
+    attributes.align !== 'justify' &&
+    attributedString.string.length > BEST_FIT_THRESHOLD
+  );
+};
+
 /**
  * Performs Knuth & Plass line breaking algorithm
  * Fallbacks to best fit algorithm if latter not successful
@@ -148,11 +163,14 @@ const linebreaker = (options: LayoutOptions) => {
 
     const attributes = getAttributes(attributedString);
     const nodes = getNodes(attributedString, attributes, options);
+    const useBestFit = shouldUseBestFit(attributedString, attributes, options);
 
-    let breaks = knuthPlass(nodes, availableWidths, tolerance);
+    let breaks = useBestFit
+      ? bestFit(nodes, availableWidths)
+      : knuthPlass(nodes, availableWidths, tolerance);
 
     // Try again with a higher tolerance if the line breaking failed.
-    while (breaks.length === 0 && tolerance < TOLERANCE_LIMIT) {
+    while (!useBestFit && breaks.length === 0 && tolerance < TOLERANCE_LIMIT) {
       tolerance += TOLERANCE_STEPS;
       breaks = knuthPlass(nodes, availableWidths, tolerance);
     }

packages/textkit/src/types.ts

@@ -134,6 +134,7 @@ export type LayoutOptions = {
     word: string | null,
     fallback: (word: string | null) => string[],
   ) => string[];
+  lineBreakStrategy?: 'auto' | 'best-fit' | 'knuth-plass';
   tolerance?: number;
   hyphenationPenalty?: number;
   expandCharFactor?: JustificationFactor;

packages/textkit/tests/engines/linebreaker.test.ts

@@ -10,6 +10,33 @@ const width = 50;
 describe('linebreaker', () => {
   const linebreaker = linebreakerFactory({});
 
+  const createLongAttributedString = (attributes = {}) => {
+    const string = Array(600).fill('word').join(' ');
+    const indices = Array.from({ length: string.length }, (_, index) => index);
+
+    return {
+      string,
+      runs: [
+        {
+          start: 0,
+          end: string.length,
+          attributes: { font: [font], ...attributes },
+          stringIndices: indices,
+          glyphIndices: indices,
+          positions: indices.map(() => ({
+            xAdvance: 1,
+            yAdvance: 0,
+            xOffset: 0,
+            yOffset: 0,
+            advanceWidth: 1,
+          })),
+          glyphs: [],
+        },
+      ],
+      syllables: string.split(/([ ]+)/g).filter(Boolean),
+    };
+  };
+
   test('should break lines and adds hyphens only where indicated', () => {
     const attributedString = {
       string: 'Potentieel broeikasgasemissierapport',
@@ -296,6 +323,31 @@ describe('linebreaker', () => {
       'rapport',
     ]);
   });
+
+  test('should use best-fit for long non-justified text in auto mode', () => {
+    const attributedString = createLongAttributedString();
+    const result = linebreakerFactory({})(attributedString, [50]);
+    const bestFitResult = linebreakerFactory({ lineBreakStrategy: 'best-fit' })(
+      attributedString,
+      [50],
+    );
+
+    expect(result.map((line) => line.string)).toEqual(
+      bestFitResult.map((line) => line.string),
+    );
+  });
+
+  test('should keep Knuth-Plass for long justified text in auto mode', () => {
+    const attributedString = createLongAttributedString({ align: 'justify' });
+    const result = linebreakerFactory({})(attributedString, [50]);
+    const knuthPlassResult = linebreakerFactory({
+      lineBreakStrategy: 'knuth-plass',
+    })(attributedString, [50]);
+
+    expect(result.map((line) => line.string)).toEqual(
+      knuthPlassResult.map((line) => line.string),
+    );
+  });
 });
 
 describe('bestFit', () => {

packages/types/node.d.ts

@@ -24,6 +24,7 @@ interface TextProps extends BaseProps {
   orphans?: number;
   render?: DynamicRenderCallback;
   hyphenationCallback?: HyphenationCallback;
+  lineBreakStrategy?: 'auto' | 'best-fit' | 'knuth-plass';
 }
 
 interface ViewProps extends BaseProps {