0
# @react-pdf/textkit
1
2
@react-pdf/textkit is an advanced text layout framework specifically designed for complex typography in PDF generation. It implements a comprehensive 13-step text layout process including paragraph splitting, bidirectional text handling, font substitution and shaping, script itemization, line breaking, text justification, and text decoration.
3
4
## Package Information
5
6
- **Package Name**: @react-pdf/textkit
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @react-pdf/textkit`
10
11
## Core Imports
12
13
```typescript
14
import layoutEngine, {
15
bidi,
16
linebreaker,
17
justification,
18
textDecoration,
19
scriptItemizer,
20
wordHyphenation,
21
fontSubstitution,
22
fromFragments,
23
type AttributedString,
24
type Container,
25
type LayoutOptions,
26
type Engines
27
} from "@react-pdf/textkit";
28
```
29
30
For CommonJS:
31
32
```javascript
33
const layoutEngine = require("@react-pdf/textkit").default;
34
const {
35
bidi,
36
linebreaker,
37
justification,
38
textDecoration,
39
scriptItemizer,
40
wordHyphenation,
41
fontSubstitution,
42
fromFragments
43
} = require("@react-pdf/textkit");
44
```
45
46
## Basic Usage
47
48
```typescript
49
import layoutEngine, {
50
bidi,
51
linebreaker,
52
justification,
53
textDecoration,
54
scriptItemizer,
55
wordHyphenation,
56
fontSubstitution,
57
fromFragments
58
} from "@react-pdf/textkit";
59
60
// Create text fragments
61
const fragments = [
62
{ string: "Hello ", attributes: { fontSize: 16 } },
63
{ string: "World", attributes: { fontSize: 16, color: "blue" } }
64
];
65
66
// Create attributed string from fragments
67
const attributedString = fromFragments(fragments);
68
69
// Set up engines
70
const engines = {
71
bidi: bidi(),
72
linebreaker: linebreaker({ tolerance: 4 }),
73
justification: justification({}),
74
textDecoration: textDecoration(),
75
scriptItemizer: scriptItemizer(),
76
wordHyphenation: wordHyphenation(),
77
fontSubstitution: fontSubstitution()
78
};
79
80
// Create layout engine and perform layout
81
const layout = layoutEngine(engines);
82
const container = { x: 0, y: 0, width: 200, height: 100 };
83
const result = layout(attributedString, container);
84
```
85
86
## Architecture
87
88
@react-pdf/textkit is built around several key components:
89
90
- **Layout Engine**: Central processor that orchestrates the 13-step text layout pipeline
91
- **Text Engines**: Specialized processors for bidirectional text, line breaking, justification, font substitution, script itemization, hyphenation, and text decoration
92
- **AttributedString System**: Core data structure representing styled text with runs of attributes
93
- **Utility Modules**: Helper functions for text measurement, glyph manipulation, and position calculations
94
- **Type System**: Comprehensive TypeScript definitions for all text layout operations
95
96
## Capabilities
97
98
### Layout Engine
99
100
Core text layout functionality that orchestrates the complete 13-step text processing pipeline. Handles complex typography including bidirectional text, font shaping, line breaking, and justification.
101
102
```typescript { .api }
103
function layoutEngine(engines: Engines): (
104
attributedString: AttributedString,
105
container: Container,
106
options?: LayoutOptions
107
) => AttributedString;
108
109
interface Engines {
110
bidi: typeof bidi;
111
linebreaker: typeof linebreaker;
112
justification: typeof justification;
113
textDecoration: typeof textDecoration;
114
scriptItemizer: typeof scriptItemizer;
115
wordHyphenation?: typeof wordHyphenation;
116
fontSubstitution: typeof fontSubstitution;
117
}
118
```
119
120
[Layout Engine](./layout-engine.md)
121
122
### Text Processing Engines
123
124
Specialized engines for different aspects of text processing including bidirectional text reordering, line breaking with Knuth & Plass algorithm, text justification, and font substitution.
125
126
```typescript { .api }
127
function bidi(): (attributedString: AttributedString) => AttributedString;
128
function linebreaker(options: LayoutOptions): (
129
attributedString: AttributedString,
130
availableWidths: number[]
131
) => AttributedString[];
132
function justification(options: LayoutOptions): (line: AttributedString) => AttributedString;
133
function fontSubstitution(): (attributedString: AttributedString) => AttributedString;
134
```
135
136
[Text Processing Engines](./engines.md)
137
138
### AttributedString Utilities
139
140
Core utilities for creating styled text. Provides functions for constructing attributed strings from text fragments.
141
142
```typescript { .api }
143
function fromFragments(fragments: Fragment[]): AttributedString;
144
```
145
146
[AttributedString Utilities](./attributed-string.md)
147
148
### Text Decoration and Script Processing
149
150
Utilities for text decoration (underlines, strike-through) and Unicode script itemization for proper text rendering across different writing systems.
151
152
```typescript { .api }
153
function textDecoration(): (line: AttributedString) => AttributedString;
154
function scriptItemizer(): (attributedString: AttributedString) => AttributedString;
155
function wordHyphenation(): (word: string | null) => string[];
156
```
157
158
[Text Decoration & Script Processing](./decoration-script.md)
159
160
## Core Types
161
162
```typescript { .api }
163
interface AttributedString {
164
string: string;
165
syllables?: string[];
166
runs: Run[];
167
box?: Rect;
168
decorationLines?: DecorationLine[];
169
overflowLeft?: number;
170
overflowRight?: number;
171
xAdvance?: number;
172
ascent?: number;
173
}
174
175
interface Fragment {
176
string: string;
177
attributes?: Attributes;
178
}
179
180
interface Container extends Rect {
181
truncateMode?: 'ellipsis';
182
maxLines?: number;
183
excludeRects?: Rect[];
184
}
185
186
interface LayoutOptions {
187
hyphenationCallback?: (word: string) => string[];
188
tolerance?: number;
189
hyphenationPenalty?: number;
190
expandCharFactor?: JustificationFactor;
191
shrinkCharFactor?: JustificationFactor;
192
expandWhitespaceFactor?: JustificationFactor;
193
shrinkWhitespaceFactor?: JustificationFactor;
194
}
195
196
interface JustificationFactor {
197
before: number;
198
after: number;
199
priority?: number;
200
unconstrained?: boolean;
201
}
202
203
interface Run {
204
start: number;
205
end: number;
206
attributes: Attributes;
207
glyphIndices?: number[];
208
glyphs?: Glyph[];
209
positions?: Position[];
210
xAdvance?: number;
211
height?: number;
212
descent?: number;
213
}
214
215
interface Attributes {
216
align?: string;
217
alignLastLine?: string;
218
attachment?: Attachment;
219
backgroundColor?: string;
220
bidiLevel?: number;
221
bullet?: unknown;
222
characterSpacing?: number;
223
color?: string;
224
direction?: 'rtl' | 'ltr';
225
features?: unknown[];
226
fill?: boolean;
227
font?: Font[];
228
fontSize?: number;
229
hangingPunctuation?: boolean;
230
hyphenationFactor?: number;
231
indent?: number;
232
justificationFactor?: number;
233
lineHeight?: number;
234
lineSpacing?: number;
235
link?: string;
236
margin?: number;
237
marginLeft?: number;
238
marginRight?: number;
239
opacity?: number;
240
padding?: number;
241
paddingTop?: number;
242
paragraphSpacing?: number;
243
scale?: number;
244
script?: unknown;
245
shrinkFactor?: number;
246
strike?: boolean;
247
strikeColor?: string;
248
strikeStyle?: string;
249
stroke?: boolean;
250
underline?: boolean;
251
underlineColor?: string;
252
underlineStyle?: string;
253
verticalAlign?: string;
254
wordSpacing?: number;
255
yOffset?: number;
256
}
257
258
interface Rect {
259
x: number;
260
y: number;
261
width: number;
262
height: number;
263
}
264
265
interface Position {
266
xAdvance: number;
267
yAdvance: number;
268
xOffset: number;
269
yOffset: number;
270
advanceWidth?: number;
271
}
272
273
interface DecorationLine {
274
rect: Rect;
275
opacity: number;
276
color: string;
277
style: string;
278
}
279
280
interface Attachment {
281
x?: number;
282
y?: number;
283
width: number;
284
height: number;
285
xOffset?: number;
286
yOffset?: number;
287
image: Buffer;
288
}
289
290
type Coordinate = {
291
x: number;
292
y: number;
293
};
294
295
type Glyph = FontkitGlyph;
296
type Paragraph = AttributedString[];
297
```