0
# Text Processing Engines
1
2
Specialized engines that handle different aspects of text processing within the layout pipeline. Each engine is responsible for a specific transformation or analysis of the attributed string.
3
4
## Capabilities
5
6
### Bidirectional Text Engine
7
8
Handles bidirectional text reordering using the Unicode bidirectional algorithm. Analyzes text direction and creates runs with appropriate bidi levels.
9
10
```typescript { .api }
11
/**
12
* Creates a bidirectional text processing engine
13
* @returns Function that processes attributed strings for bidi text
14
*/
15
function bidi(): (attributedString: AttributedString) => AttributedString;
16
```
17
18
**Usage Example:**
19
20
```typescript
21
import { bidi } from "@react-pdf/textkit";
22
23
const bidiEngine = bidi();
24
const processedString = bidiEngine(attributedString);
25
```
26
27
### Line Breaking Engine
28
29
Implements the Knuth & Plass line breaking algorithm with best-fit fallback. Determines optimal line breaks based on available widths and layout constraints.
30
31
```typescript { .api }
32
/**
33
* Creates a line breaking engine using Knuth & Plass algorithm
34
* @param options - Layout configuration options
35
* @returns Function that breaks attributed strings into lines
36
*/
37
function linebreaker(options: LayoutOptions): (
38
attributedString: AttributedString,
39
availableWidths: number[]
40
) => AttributedString[];
41
```
42
43
**Usage Example:**
44
45
```typescript
46
import { linebreaker } from "@react-pdf/textkit";
47
48
const linebreakerEngine = linebreaker({
49
tolerance: 4,
50
hyphenationPenalty: 100
51
});
52
53
const lines = linebreakerEngine(attributedString, [200, 200, 200]);
54
```
55
56
### Justification Engine
57
58
Performs text justification using Apple's justification algorithm. Adjusts character and word spacing to achieve proper text alignment.
59
60
```typescript { .api }
61
/**
62
* Creates a text justification engine
63
* @param options - Layout configuration options
64
* @returns Function that justifies attributed string lines
65
*/
66
function justification(options: LayoutOptions): (line: AttributedString) => AttributedString;
67
```
68
69
**Usage Example:**
70
71
```typescript
72
import { justification } from "@react-pdf/textkit";
73
74
const justificationEngine = justification({
75
expandCharFactor: { priority: 0, unconditional: false },
76
shrinkCharFactor: { priority: 0, unconditional: false }
77
});
78
79
const justifiedLine = justificationEngine(line);
80
```
81
82
### Font Substitution Engine
83
84
Handles font fallback and substitution when fonts don't contain required glyphs. Selects appropriate fonts from font stacks based on Unicode code points.
85
86
```typescript { .api }
87
/**
88
* Creates a font substitution engine
89
* @returns Function that performs font substitution on attributed strings
90
*/
91
function fontSubstitution(): (attributedString: AttributedString) => AttributedString;
92
```
93
94
**Usage Example:**
95
96
```typescript
97
import { fontSubstitution } from "@react-pdf/textkit";
98
99
const fontSubEngine = fontSubstitution();
100
const substitutedString = fontSubEngine(attributedString);
101
```
102
103
### Script Itemization Engine
104
105
Performs Unicode script itemization by analyzing text and grouping consecutive characters with the same script. Essential for proper text shaping and rendering.
106
107
```typescript { .api }
108
/**
109
* Creates a script itemization engine
110
* @returns Function that itemizes attributed strings by Unicode script
111
*/
112
function scriptItemizer(): (attributedString: AttributedString) => AttributedString;
113
```
114
115
**Usage Example:**
116
117
```typescript
118
import { scriptItemizer } from "@react-pdf/textkit";
119
120
const scriptEngine = scriptItemizer();
121
const itemizedString = scriptEngine(attributedString);
122
```
123
124
### Word Hyphenation Engine
125
126
Provides word hyphenation functionality using hyphenation patterns. Splits words into syllables for line breaking purposes.
127
128
```typescript { .api }
129
/**
130
* Creates a word hyphenation engine
131
* @returns Function that hyphenates words into syllable parts
132
*/
133
function wordHyphenation(): (word: string | null) => string[];
134
```
135
136
**Usage Example:**
137
138
```typescript
139
import { wordHyphenation } from "@react-pdf/textkit";
140
141
const hyphenationEngine = wordHyphenation();
142
const syllables = hyphenationEngine("hyphenation"); // ['hy', 'phen', 'ation']
143
```
144
145
### Text Decoration Engine
146
147
Generates decoration lines for text including underlines and strike-through effects. Calculates proper positioning and styling for decorations.
148
149
```typescript { .api }
150
/**
151
* Creates a text decoration engine
152
* @returns Function that adds decoration lines to attributed strings
153
*/
154
function textDecoration(): (line: AttributedString) => AttributedString;
155
```
156
157
**Usage Example:**
158
159
```typescript
160
import { textDecoration } from "@react-pdf/textkit";
161
162
const decorationEngine = textDecoration();
163
const decoratedLine = decorationEngine(line);
164
```
165
166
## Engine Configuration
167
168
### Linebreaker Options
169
170
The linebreaker engine accepts several configuration options:
171
172
- **tolerance**: Acceptable badness level for line breaks (default: 4)
173
- **hyphenationPenalty**: Penalty for hyphenation points (default: 100 for justified, 600 for others)
174
- **hyphenationCallback**: Custom hyphenation function
175
176
### Justification Options
177
178
The justification engine supports factor-based spacing adjustments:
179
180
- **expandCharFactor**: Character expansion parameters
181
- **shrinkCharFactor**: Character shrinking parameters
182
- **expandWhitespaceFactor**: Whitespace expansion parameters
183
- **shrinkWhitespaceFactor**: Whitespace shrinking parameters
184
185
```typescript { .api }
186
interface JustificationFactor {
187
before: number;
188
after: number;
189
priority?: number;
190
unconstrained?: boolean;
191
}
192
```