0
# Layout Engine
1

2
The layout engine is the central component that orchestrates the complete 13-step text layout process. It accepts an AttributedString and a Container object to layout text into, using various helper engines to perform specific layout tasks.
3

4
## Capabilities
5

6
### Layout Engine Factory
7

8
Creates a layout engine configured with the specified processing engines.
9

10
```typescript { .api }
11
/**
12
 * Creates a layout engine configured with the specified processing engines
13
 * @param engines - Collection of text processing engines
14
 * @returns Layout function that processes attributed strings
15
 */
16
function layoutEngine(engines: Engines): (
17
  attributedString: AttributedString,
18
  container: Container,
19
  options?: LayoutOptions
20
) => AttributedString;
21
```
22

23
**Usage Example:**
24

25
```typescript
26
import layoutEngine, { 
27
  bidi, 
28
  linebreaker, 
29
  justification, 
30
  textDecoration, 
31
  scriptItemizer, 
32
  wordHyphenation, 
33
  fontSubstitution 
34
} from "@react-pdf/textkit";
35

36
// Configure engines
37
const engines = {
38
  bidi: bidi(),
39
  linebreaker: linebreaker({ tolerance: 4 }),
40
  justification: justification({}),
41
  textDecoration: textDecoration(),
42
  scriptItemizer: scriptItemizer(),
43
  wordHyphenation: wordHyphenation(),
44
  fontSubstitution: fontSubstitution()
45
};
46

47
// Create layout engine
48
const layout = layoutEngine(engines);
49

50
// Use the layout engine
51
const result = layout(attributedString, container, options);
52
```
53

54
### Layout Processing Pipeline
55

56
The layout engine processes text through a 13-step pipeline:
57

58
1. **Split into paragraphs** - Separate text into paragraph units
59
2. **Get bidi runs and paragraph direction** - Handle bidirectional text
60
3. **Font substitution** - Map to resolved font runs
61
4. **Script itemization** - Group text by Unicode script
62
5. **Font shaping** - Convert text to glyphs
63
6. **Line breaking** - Determine optimal line breaks
64
7. **Bidi reordering** - Reorder text for proper display
65
8. **Justification** - Adjust spacing for text alignment
66
9. **Get rectangles** - Calculate line and exclusion rectangles
67
10. **Perform line breaking** - Apply break points to fragments
68
11. **Ellipsize** - Truncate lines if necessary
69
12. **Bidi reordering** - Final reordering pass
70
13. **Justification** - Final justification pass
71

72
## Types
73

74
```typescript { .api }
75
interface Engines {
76
  bidi: typeof bidi;
77
  linebreaker: typeof linebreaker;
78
  justification: typeof justification;
79
  textDecoration: typeof textDecoration;
80
  scriptItemizer: typeof scriptItemizer;
81
  wordHyphenation?: typeof wordHyphenation;
82
  fontSubstitution: typeof fontSubstitution;
83
}
84

85
interface Container extends Rect {
86
  truncateMode?: 'ellipsis';
87
  maxLines?: number;
88
  excludeRects?: Rect[];
89
}
90

91
interface LayoutOptions {
92
  hyphenationCallback?: (word: string) => string[];
93
  tolerance?: number;
94
  hyphenationPenalty?: number;
95
  expandCharFactor?: JustificationFactor;
96
  shrinkCharFactor?: JustificationFactor;
97
  expandWhitespaceFactor?: JustificationFactor;
98
  shrinkWhitespaceFactor?: JustificationFactor;
99
}
100

101
interface JustificationFactor {
102
  before: number;
103
  after: number;
104
  priority?: number;
105
  unconstrained?: boolean;
106
}
107
```