Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
100.00%
120 / 120
100.00%
9 / 9
 CRAP
100.00%
1 / 1
LayoutContext
100.00%
120 / 120
100.00%
9 / 9
 9
100.00%
1 / 1
 __construct
100.00%
1 / 1
100.00%
1 / 1
 1
 withOrigin
100.00%
15 / 15
100.00%
1 / 1
 1
 withContainingBlock
100.00%
15 / 15
100.00%
1 / 1
 1
 withContainingBlockHeightDefinite
100.00%
14 / 14
100.00%
1 / 1
 1
 withInFlowHeightDefinite
100.00%
15 / 15
100.00%
1 / 1
 1
 withLengthContext
100.00%
15 / 15
100.00%
1 / 1
 1
 withFloatContext
100.00%
15 / 15
100.00%
1 / 1
 1
 withPositionedAncestor
100.00%
15 / 15
100.00%
1 / 1
 1
 withParentWritingMode
100.00%
15 / 15
100.00%
1 / 1
 1
1<?php
2
3declare(strict_types=1);
4
5namespace Phpdftk\HtmlToPdf\Layout;
6
7use Phpdftk\Css\Cascade\LengthContext;
8use Phpdftk\Css\Cascade\WritingMode;
9use Phpdftk\FontParser\FontFaceData;
10
11/**
12 * Per-layout-step context: the containing block's content width / height,
13 * the current X / Y origin where the next child will go, the
14 * `LengthContext` used by the CSS resolver for em / rem / vw / vh / %, and
15 * the default font supplied to {@see InlineLayout} for text measurement.
16 *
17 * Layout creates child contexts (via `with*()`) when it descends into a
18 * box, shifting origin and updating the containing-block measurements so
19 * `%` resolves correctly.
20 *
21 * `defaultFont` is null when no font is wired in yet — in that case
22 * inline layout falls back to producing zero-height placeholders so
23 * block layout can still run end-to-end. Hosts that want real typography
24 * provide a parsed `FontFaceData` here (see `phpdftk/font-parser`).
25 */
26final readonly class LayoutContext
27{
28    public function __construct(
29        public float $containingBlockWidth,
30        public float $containingBlockHeight,
31        public float $originX,
32        public float $originY,
33        public LengthContext $lengthContext,
34        public ?FontFaceData $defaultFont = null,
35        /**
36         * Optional multi-font selector. When set, `InlineLayout` picks the
37         * shaping font per box from this resolver — falling back to
38         * `defaultFont` when no `font-family` matches.
39         */
40        public ?FontResolver $fontResolver = null,
41        /**
42         * Tracks active floats per CSS 2.1 §9.5 for the current block
43         * formatting context. `InlineLayout` queries this to shorten
44         * line boxes that overlap a float's vertical extent. Null when
45         * no BFC has registered any floats yet.
46         */
47        public ?FloatContext $floatContext = null,
48        /**
49         * CSS 2.1 §10.1 — the containing block for `position:
50         * absolute` / `fixed` descendants is the nearest positioned
51         * ancestor's PADDING box, not the immediate parent. We thread
52         * that ancestor's padding-box rectangle here so abs-pos
53         * layout can read it directly. Null when no positioned
54         * ancestor is established yet — `BlockLayout` falls back to
55         * the initial containing block (the canvas).
56         */
57        public ?PositionedAncestor $positionedAncestor = null,
58        /**
59         * CSS 2.1 §10.5 + CSS Position 3 §3.4 — whether
60         * `$containingBlockHeight` is the spec's "definite height"
61         * (resolves percentage `top` / `bottom` / `height` directly)
62         * or "indefinite" (those percentages resolve to 0). The
63         * viewport at the root is always definite; descending through
64         * an auto-height intermediate block breaks the chain. The
65         * `<html>` and `<body>` elements are special-cased to inherit
66         * the viewport per the HTML rendering rules.
67         */
68        public bool $containingBlockHeightDefinite = true,
69        /**
70         * CSS Writing Modes 4 §7.4 — the containing block's writing
71         * mode determines which axis is the inline-axis for
72         * percentage resolution of margin / padding. In `horizontal-
73         * tb` the inline axis is x, so percentages resolve against
74         * `containingBlockWidth`; in `vertical-*` the inline axis is
75         * y, so they resolve against `containingBlockHeight`. Set
76         * by the parent when it dispatches children; null at the
77         * root (initial value = `horizontal-tb`, the default basis).
78         */
79        public ?WritingMode $parentWritingMode = null,
80        /**
81         * The actual page (fragmentainer) content height for pagination,
82         * set once at the root and threaded UNCHANGED through descendants.
83         * Distinct from `containingBlockHeight`, which a nested definite-
84         * height block overwrites with its own height — using that for the
85         * page-break-straddle check made unbreakable replaced children
86         * inside a fill-the-container block spuriously shift as if the
87         * container were a page. `0.0` disables pagination.
88         */
89        public float $pageHeight = 0.0,
90        /**
91         * Whether the containing block has a definite height for the
92         * purpose of resolving an IN-FLOW `height: %` (CSS 2.1 §10.5).
93         * Unlike `containingBlockHeightDefinite` — which the HTML render
94         * rules keep "definite = viewport" through `<html>` / `<body>` so
95         * abspos offsets on their children resolve against the ICB — an
96         * auto-height `<html>` / `<body>` is INDEFINITE for an in-flow
97         * child's percentage height (the child sizes to content, it does
98         * not fill the viewport). Kept separate so the abspos path is
99         * unaffected. Defaults definite at the root (the ICB is definite).
100         */
101        public bool $inFlowHeightDefinite = true,
102    ) {}
103
104    public function withOrigin(float $x, float $y): self
105    {
106        return new self(
107            $this->containingBlockWidth,
108            $this->containingBlockHeight,
109            $x,
110            $y,
111            $this->lengthContext,
112            $this->defaultFont,
113            $this->fontResolver,
114            $this->floatContext,
115            $this->positionedAncestor,
116            $this->containingBlockHeightDefinite,
117            $this->parentWritingMode,
118            pageHeight: $this->pageHeight,
119            inFlowHeightDefinite: $this->inFlowHeightDefinite,
120        );
121    }
122
123    public function withContainingBlock(float $width, float $height): self
124    {
125        return new self(
126            $width,
127            $height,
128            $this->originX,
129            $this->originY,
130            $this->lengthContext,
131            $this->defaultFont,
132            $this->fontResolver,
133            $this->floatContext,
134            $this->positionedAncestor,
135            $this->containingBlockHeightDefinite,
136            $this->parentWritingMode,
137            pageHeight: $this->pageHeight,
138            inFlowHeightDefinite: $this->inFlowHeightDefinite,
139        );
140    }
141
142    public function withContainingBlockHeightDefinite(float $height, bool $definite): self
143    {
144        return new self(
145            $this->containingBlockWidth,
146            $height,
147            $this->originX,
148            $this->originY,
149            $this->lengthContext,
150            $this->defaultFont,
151            $this->fontResolver,
152            $this->floatContext,
153            $this->positionedAncestor,
154            $definite,
155            pageHeight: $this->pageHeight,
156            inFlowHeightDefinite: $this->inFlowHeightDefinite,
157        );
158    }
159
160    public function withInFlowHeightDefinite(bool $definite): self
161    {
162        return new self(
163            $this->containingBlockWidth,
164            $this->containingBlockHeight,
165            $this->originX,
166            $this->originY,
167            $this->lengthContext,
168            $this->defaultFont,
169            $this->fontResolver,
170            $this->floatContext,
171            $this->positionedAncestor,
172            $this->containingBlockHeightDefinite,
173            $this->parentWritingMode,
174            pageHeight: $this->pageHeight,
175            inFlowHeightDefinite: $definite,
176        );
177    }
178
179    public function withLengthContext(LengthContext $ctx): self
180    {
181        return new self(
182            $this->containingBlockWidth,
183            $this->containingBlockHeight,
184            $this->originX,
185            $this->originY,
186            $ctx,
187            $this->defaultFont,
188            $this->fontResolver,
189            $this->floatContext,
190            $this->positionedAncestor,
191            $this->containingBlockHeightDefinite,
192            $this->parentWritingMode,
193            pageHeight: $this->pageHeight,
194            inFlowHeightDefinite: $this->inFlowHeightDefinite,
195        );
196    }
197
198    public function withFloatContext(?FloatContext $ctx): self
199    {
200        return new self(
201            $this->containingBlockWidth,
202            $this->containingBlockHeight,
203            $this->originX,
204            $this->originY,
205            $this->lengthContext,
206            $this->defaultFont,
207            $this->fontResolver,
208            $ctx,
209            $this->positionedAncestor,
210            $this->containingBlockHeightDefinite,
211            $this->parentWritingMode,
212            pageHeight: $this->pageHeight,
213            inFlowHeightDefinite: $this->inFlowHeightDefinite,
214        );
215    }
216
217    public function withPositionedAncestor(?PositionedAncestor $pa): self
218    {
219        return new self(
220            $this->containingBlockWidth,
221            $this->containingBlockHeight,
222            $this->originX,
223            $this->originY,
224            $this->lengthContext,
225            $this->defaultFont,
226            $this->fontResolver,
227            $this->floatContext,
228            $pa,
229            $this->containingBlockHeightDefinite,
230            $this->parentWritingMode,
231            pageHeight: $this->pageHeight,
232            inFlowHeightDefinite: $this->inFlowHeightDefinite,
233        );
234    }
235
236    public function withParentWritingMode(?WritingMode $wm): self
237    {
238        return new self(
239            $this->containingBlockWidth,
240            $this->containingBlockHeight,
241            $this->originX,
242            $this->originY,
243            $this->lengthContext,
244            $this->defaultFont,
245            $this->fontResolver,
246            $this->floatContext,
247            $this->positionedAncestor,
248            $this->containingBlockHeightDefinite,
249            $wm,
250            pageHeight: $this->pageHeight,
251            inFlowHeightDefinite: $this->inFlowHeightDefinite,
252        );
253    }
254}