Text Decoration & Script Processing

Utilities for text decoration (underlines, strike-through) and Unicode script processing for proper text rendering across different writing systems.

Capabilities

Text Decoration Engine

Generates decoration lines for text including underlines and strike-through effects. Calculates proper positioning, thickness, and styling for decorations based on font metrics.

/**
 * Creates a text decoration engine for generating underlines and strike-through
 * @returns Function that adds decoration lines to attributed string lines
 */
function textDecoration(): (line: AttributedString) => AttributedString;

Usage Example:

import { textDecoration } from "@react-pdf/textkit";

// Create decoration engine
const decorationEngine = textDecoration();

// Apply decorations to a line with underline and strike attributes
const decoratedLine = decorationEngine(line);

// The engine will add decorationLines to the AttributedString
console.log(decoratedLine.decorationLines);

The text decoration engine processes runs with the following attributes:

• underline: Creates underline decoration
• underlineColor: Sets underline color (default: "black")
• underlineStyle: Sets underline style (default: "solid")
• strike: Creates strike-through decoration
• strikeColor: Sets strike-through color (default: "black")
• strikeStyle: Sets strike-through style (default: "solid")

Script Itemization Engine

Performs Unicode script itemization by analyzing text and grouping consecutive characters with the same script. This is essential for proper text shaping and rendering, especially for complex scripts and mixed-language text.

/**
 * Creates a script itemization engine for Unicode script analysis
 * @returns Function that groups attributed string characters by Unicode script
 */
function scriptItemizer(): (attributedString: AttributedString) => AttributedString;

Usage Example:

import { scriptItemizer } from "@react-pdf/textkit";

// Create script itemizer
const scriptEngine = scriptItemizer();

// Process mixed-script text
const mixedText = fromFragments([
  { string: "Hello مرحبا" } // Latin + Arabic
]);

const itemizedString = scriptEngine(mixedText);

// Results in runs grouped by script:
// Run 1: "Hello " (script: "Latin")
// Run 2: "مرحبا" (script: "Arabic")

The script itemizer:

• Analyzes each character's Unicode script property
• Groups consecutive characters with the same script into runs
• Ignores "Common", "Inherited", and "Unknown" scripts
• Creates runs with script attribute set to the detected script name

Word Hyphenation Engine

Provides word hyphenation functionality using the hyphen library with English (US) patterns. Splits words into syllable parts for line breaking purposes.

/**
 * Creates a word hyphenation engine using English hyphenation patterns
 * @returns Function that splits words into hyphenation syllables
 */
function wordHyphenation(): (word: string | null) => string[];

Usage Example:

import { wordHyphenation } from "@react-pdf/textkit";

// Create hyphenation engine
const hyphenationEngine = wordHyphenation();

// Hyphenate words
const syllables1 = hyphenationEngine("hyphenation");
// Result: ["hy", "phen", "ation"]

const syllables2 = hyphenationEngine("beautiful");
// Result: ["beau", "ti", "ful"]

const syllables3 = hyphenationEngine("cat");
// Result: ["cat"] (single syllable)

// Handles null input
const syllables4 = hyphenationEngine(null);
// Result: []

The hyphenation engine:

• Uses cached results for performance
• Supports soft hyphen (\u00ad) in input words
• Returns array of syllable parts
• Returns empty array for null input
• Uses English (US) hyphenation patterns by default

Text Decoration Types

interface DecorationLine {
  rect: Rect;
  opacity: number;
  color: string;
  style: string;
}

interface Rect {
  x: number;
  y: number;
  width: number;
  height: number;
}

Decoration Calculation

The text decoration engine calculates decoration properties as follows:

Underline Positioning

• Y Position: ascent(line) + thickness * 2
• Thickness: Math.max(0.5, Math.floor(fontSize / 12))
• Width: Constrained by line width and overflow settings

Strike-through Positioning

• Y Position: ascent(line) - runAscent(run) / 3
• Thickness: Same as underline
• Width: Same as underline

Color and Style

• Uses underlineColor/strikeColor attributes or defaults to "black"
• Uses underlineStyle/strikeStyle attributes or defaults to "solid"
• Respects opacity attribute from run

Script Processing

The script itemizer recognizes all Unicode scripts and creates appropriate groupings for:

• Latin scripts: English, European languages
• Arabic scripts: Arabic, Persian, Urdu
• Cyrillic scripts: Russian, Bulgarian, Serbian
• CJK scripts: Chinese, Japanese, Korean
• Indic scripts: Hindi, Tamil, Bengali
• And many others: As defined by Unicode properties

Scripts marked as "Common", "Inherited", or "Unknown" are ignored during itemization, allowing surrounding script context to determine grouping.