Word Overflow Strategy Proposal

[PejmanNik]

🚀 Why?

Currently, the pagination engine's behavior for handling word overflow (when a single word cannot fit on the current line or page) is hardcoded to a specific strategy. This proposal introduces a configurable option to allow users to switch between different word overflow policies.

By exposing the wordOverflowStrategy option, flexibility is achieved, allowing users to optimize the pagination behavior based on their content requirements (e.g., prioritizing page density over moving content to the next page). The engine currently defaults to the behavior defined by the proposed hyphenateAsFallback strategy.

---

💻 API Proposal

This proposal introduces a new optional property, wordOverflowStrategy, to the existing LayoutOptions interface.

/**
 * Defines the strategy for handling a word (a sequence of non-whitespace characters)
 * that causes text overflow when placed on the current page or line.
 *
 * - 'hyphenateAsFallback': **Paginate-First Fallback.** The system first attempts
 * to move the entire word to the next available page. If the word still does not fit
 * on that new page, the system discards the new page and falls back to hyphenating
 * the word on the **original current page** to resolve the overflow.
 *
 * - 'hyphenateFirst': **Hyphenate-Directly.** The system attempts to hyphenate the
 * word directly on the current page without first trying to move it to a new page.
 * This strategy prioritizes keeping content on the current page.
 *
 * @defaultValue 'hyphenateAsFallback'
 */
wordOverflowStrategy?: 'hyphenateAsFallback' | 'hyphenateFirst';