spindrift 0.1.0

A HTML/CSS to PDF renderer, targeting spec compliance and efficiency
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
use super::*;

pub(crate) fn apply_cascaded_declarations_with_inheritance_source_and_parent_ch_advance(
    style: &mut ComputedStyle,
    declarations: &[CascadedDeclaration<'_>],
    inheritance_source: &ComputedStyle,
    parent_ch_advance: LayoutLength,
    is_document_root: bool,
    color_scheme_preference: ColorSchemePreference,
) {
    let (direction, writing_mode) =
        logical_mapping_context(style, declarations, inheritance_source);
    let mut declarations =
        declarations_after_css_wide_rollbacks(declarations, direction, writing_mode);
    // A declaration is ignored when its specified value does not match the
    // property's grammar.  Keep this boundary before the font-size/color
    // prepasses: CSS Conditional declaration queries and ordinary cascade
    // application must agree about the same specified-value operation.
    // <https://www.w3.org/TR/css-cascade-5/#filtering>
    declarations.retain(cascaded_declaration_is_canonical);
    apply_cascaded_custom_property_declarations(style, &declarations, inheritance_source);
    apply_cascaded_color_scheme_declarations(
        style,
        &declarations,
        inheritance_source,
        color_scheme_preference,
    );
    // Registered `<color>` values resolve `light-dark()` in the color scheme
    // selected by their owning element.  Keep their token form until the
    // color-scheme prepass has established that scheme, then substitute the
    // typed computed value into ordinary declarations.
    compute_registered_custom_property_values(style);
    let declarations = declarations_after_variable_substitution_and_shorthand_expansion(
        &declarations,
        &style.custom_properties,
        direction,
        writing_mode,
    );
    apply_cascaded_font_size_declarations_with_parent_ch_advance(
        style,
        &declarations,
        inheritance_source,
        parent_ch_advance,
    );
    apply_cascaded_color_declarations(style, &declarations, inheritance_source);
    update_dependency_prepass_provenance(style, &declarations, inheritance_source);

    // Font shorthand expansion emits consecutive components with their source
    // cascade metadata intact. Reuse one parsed shorthand for that group.
    let mut parsed_font_component = None;
    for (index, declaration) in declarations.iter().enumerate() {
        let Some(property) = declaration.property.modeled() else {
            continue;
        };
        let name = property.css_name();
        // These properties are fully resolved by dependency-ordered prepasses
        // above, including their CSS-wide keywords. Letting the generic
        // handler process an earlier defaulting declaration again would
        // overwrite the prepass's later winning longhand.
        if matches!(
            property,
            ModeledProperty::Longhand(
                ModeledLonghand::ColorScheme | ModeledLonghand::FontSize | ModeledLonghand::Color
            ) | ModeledProperty::FontComponent(ModeledLonghand::FontSize)
        ) {
            continue;
        }
        if is_shadowed_by_later_var_declaration(&declarations, index, &declaration.property) {
            continue;
        }
        let resolved_value;
        let value = trim_css_value(&declaration.value);
        let value = if contains_css_variable_reference(value) {
            let Some(resolved) = resolve_css_variables(value, &style.custom_properties) else {
                if matches!(
                    property,
                    ModeledProperty::Longhand(
                        ModeledLonghand::AnimationName
                            | ModeledLonghand::AnimationDuration
                            | ModeledLonghand::AnimationDelay
                    )
                ) {
                    // A winning unresolved variable makes this non-inherited
                    // animation longhand invalid at computed-value time. It
                    // therefore computes to its initial value; an earlier
                    // declaration must not revive.
                    apply_css_wide_default_keyword(
                        style,
                        property,
                        CssWideDefaultKeyword::Initial,
                        inheritance_source,
                    );
                }
                continue;
            };
            resolved_value = resolved;
            trim_css_value(&resolved_value)
        } else {
            value
        };
        if let Some(keyword) = CssWideDefaultKeyword::parse(value) {
            apply_css_wide_default_keyword(style, property, keyword, inheritance_source);
            for longhand in property.resolve_targets(direction, writing_mode) {
                if !matches!(keyword, CssWideDefaultKeyword::Inherit)
                    && !(matches!(keyword, CssWideDefaultKeyword::Unset) && longhand.is_inherited())
                {
                    mark_modeled_longhand_specified(style, longhand);
                }
            }
            continue;
        }
        if let Some(component) = property.font_component() {
            let source = (
                declaration.stylesheet_index,
                declaration.rule_order,
                declaration.declaration_order,
            );
            if parsed_font_component
                .as_ref()
                .is_none_or(|(cached_source, _)| *cached_source != source)
            {
                parsed_font_component = parse_font_shorthand_with_line_height_font_size(
                    value,
                    inheritance_source.font_size,
                    parent_ch_advance,
                    style.font_weight,
                    Some(style.font_size),
                    layout_pt(inheritance_source.line_height),
                )
                .map(|font| (source, font));
            }
            if let Some((_, font)) = &parsed_font_component {
                apply_font_shorthand_component(style, component, font);
                mark_modeled_longhand_specified(style, component);
            }
            continue;
        }
        parsed_font_component = None;
        // `match-parent` resolves the root's alignment as `start`: the root
        // has no element parent from which to inherit a physical start/end
        // direction, while its own used `direction` still maps logical start
        // to the correct inline edge. Descendants continue to resolve the
        // keyword against their parent's direction in `parse_text_align_all`:
        // <https://www.w3.org/TR/css-text-3/#text-align-property>.
        if is_document_root && value.eq_ignore_ascii_case("match-parent") {
            match name {
                "text-align" => {
                    style.text_align = TextAlign::Start;
                    style.text_align_last = TextAlignLast::Auto;
                    continue;
                }
                "text-align-all" => {
                    style.text_align = TextAlign::Start;
                    continue;
                }
                _ => {}
            }
        }
        if apply_cascaded_property(
            style,
            name,
            value,
            declaration,
            inheritance_source,
            parent_ch_advance,
        ) {
            for longhand in property.resolve_targets(direction, writing_mode) {
                mark_modeled_longhand_specified(style, longhand);
            }
            continue;
        }
    }
    normalize_overflow_axes(style);
    style.resolve_legacy_webkit_line_clamp();
    normalize_background_layers(style);
    // `em` and `rem` components remain deferred until layout has resolved a
    // viewport-dependent `font-size` chain. Resolving them here would freeze
    // dependent box values against the cascade's provisional font size.
    // <https://www.w3.org/TR/css-values-4/#em>
    // <https://www.w3.org/TR/css-values-4/#rem>
    style
        .row_gap
        .reduce_math_with_nonnegative_percentage_basis();
    style
        .column_gap
        .reduce_math_with_nonnegative_percentage_basis();
    // `zoom` itself is non-inherited, but its used value is the product of
    // the local computed value and all flat-tree ancestor values.  Keep that
    // layout-only quantity with the computed style so every later used-value
    // boundary receives the same semantic scale.
    // <https://drafts.csswg.org/css-viewport/#zoom-property>
    style.effective_zoom =
        EffectiveZoom::from_parent_and_local(inheritance_source.effective_zoom, style.zoom);
}

fn canonical_longhand(property: &ModeledProperty) -> Option<ModeledLonghand> {
    match property {
        ModeledProperty::Longhand(longhand) | ModeledProperty::FontComponent(longhand) => {
            Some(*longhand)
        }
        ModeledProperty::Shorthand(_)
        | ModeledProperty::Logical(_)
        | ModeledProperty::Alias(_)
        | ModeledProperty::All => None,
    }
}

fn update_dependency_prepass_provenance(
    style: &mut ComputedStyle,
    declarations: &[CascadedDeclaration<'_>],
    inheritance_source: &ComputedStyle,
) {
    for declaration in declarations {
        let Some(property) = declaration.property.modeled() else {
            continue;
        };
        let Some(longhand) = canonical_longhand(property) else {
            continue;
        };
        if !matches!(
            longhand,
            ModeledLonghand::ColorScheme | ModeledLonghand::FontSize | ModeledLonghand::Color
        ) {
            continue;
        }
        let resolved;
        let value = if contains_css_variable_reference(&declaration.value) {
            let Some(value) = resolve_css_variables(&declaration.value, &style.custom_properties)
            else {
                inherit_modeled_longhand_provenance(style, inheritance_source, longhand);
                continue;
            };
            resolved = value;
            trim_css_value(&resolved)
        } else {
            trim_css_value(&declaration.value)
        };
        if let Some(keyword) = CssWideDefaultKeyword::parse(value) {
            if matches!(keyword, CssWideDefaultKeyword::Inherit)
                || (matches!(keyword, CssWideDefaultKeyword::Unset) && longhand.is_inherited())
            {
                inherit_modeled_longhand_provenance(style, inheritance_source, longhand);
            } else {
                mark_modeled_longhand_specified(style, longhand);
            }
        } else if crate::css::parse::cascaded_declaration_is_valid(&declaration.property, value) {
            mark_modeled_longhand_specified(style, longhand);
        } else if longhand.is_inherited() {
            inherit_modeled_longhand_provenance(style, inheritance_source, longhand);
        } else {
            mark_modeled_longhand_specified(style, longhand);
        }
    }
}

/// Routes a canonical declaration to its owning feature handler.
///
/// The handlers retain the former mutually exclusive property match arms, in
/// their original cascade order. Keeping this dispatch boundary centralized
/// makes the cascade driver independent from how feature handlers are split
/// across files.
fn apply_cascaded_property(
    style: &mut ComputedStyle,
    name: &str,
    value: &str,
    declaration: &CascadedDeclaration<'_>,
    inheritance_source: &ComputedStyle,
    parent_ch_advance: LayoutLength,
) -> bool {
    if super::super::style::apply_animation_snapshot_longhand(style, name, value) {
        return true;
    }
    if name == "color-scheme" {
        return true;
    }
    apply_cascaded_layout_declaration(
        style,
        name,
        value,
        declaration,
        inheritance_source,
        parent_ch_advance,
    ) || apply_cascaded_sizing_declaration(
        style,
        name,
        value,
        declaration,
        inheritance_source,
        parent_ch_advance,
    ) || apply_cascaded_positioning_declaration(
        style,
        name,
        value,
        declaration,
        inheritance_source,
        parent_ch_advance,
    ) || apply_cascaded_visual_declaration(
        style,
        name,
        value,
        declaration,
        inheritance_source,
        parent_ch_advance,
    ) || apply_cascaded_text_declaration(
        style,
        name,
        value,
        declaration,
        inheritance_source,
        parent_ch_advance,
    )
}

/// Applies the modeled text properties that can affect a `::marker`'s text.
///
/// Marker boxes do not accept ordinary layout properties, but CSS Lists allows
/// text properties to cascade to their generated text. Keep the applicability
/// boundary here and reuse the ordinary declaration dispatcher so marker and
/// element values cannot drift apart.
/// <https://drafts.csswg.org/css-lists-3/#marker-properties>
pub(in crate::css) fn apply_cascaded_marker_text_property(
    style: &mut ComputedStyle,
    name: &str,
    value: &str,
    declaration: &CascadedDeclaration<'_>,
    inheritance_source: &ComputedStyle,
    parent_ch_advance: LayoutLength,
) -> bool {
    if !matches!(
        name,
        "direction"
            | "unicode-bidi"
            | "text-orientation"
            | "text-combine-upright"
            | "letter-spacing"
            | "word-spacing"
            | "tab-size"
            | "word-break"
            | "overflow-wrap"
            | "word-wrap"
            | "line-break"
            | "hyphens"
            | "text-decoration"
            | "text-decoration-line"
            | "text-decoration-style"
            | "text-decoration-color"
            | "text-decoration-thickness"
            | "text-decoration-inset"
            | "text-decoration-skip"
            | "text-decoration-skip-ink"
            | "text-decoration-skip-self"
            | "text-decoration-skip-box"
            | "text-decoration-skip-spaces"
            | "text-underline-offset"
            | "text-underline-position"
            | "text-emphasis"
            | "text-emphasis-style"
            | "text-emphasis-color"
            | "text-emphasis-position"
            | "text-emphasis-skip"
            | "text-shadow"
    ) {
        return false;
    }

    apply_cascaded_property(
        style,
        name,
        value,
        declaration,
        inheritance_source,
        parent_ch_advance,
    )
}

/// Whether a cascaded declaration survives specified-value validation.
///
/// Font shorthand components retain the original shorthand token stream until
/// their font-relative values are resolved, so their component token stream is
/// intentionally exempt from ordinary property grammar validation here.
pub(in crate::css) fn cascaded_declaration_is_canonical(
    declaration: &CascadedDeclaration<'_>,
) -> bool {
    // `font` is checked at specified-value time before it is split into
    // component declarations. A component retains the original shorthand
    // token stream, which is intentionally not valid as the component's own
    // grammar until its font-relative values are resolved below.
    if declaration
        .property
        .modeled()
        .is_some_and(|property| property.font_component().is_some())
    {
        return true;
    }
    crate::css::parse::cascaded_declaration_is_valid(
        &declaration.property,
        declaration.value.as_ref(),
    )
}

/// Apply Overflow's cross-axis computed-value adjustment.
///
/// A scrollable or clipped axis establishes the used overflow behavior of a
/// scroll container, so the other axis cannot remain `visible` or `clip`.
/// This happens after the complete cascade rather than while applying either
/// longhand, because cascade order must not affect the paired computed value.
/// <https://www.w3.org/TR/css-overflow-3/#overflow-properties>.
fn normalize_overflow_axes(style: &mut ComputedStyle) {
    let x_is_scroll_container = !matches!(style.overflow_x, Overflow::Visible | Overflow::Clip);
    let y_is_scroll_container = !matches!(style.overflow_y, Overflow::Visible | Overflow::Clip);
    if x_is_scroll_container {
        style.overflow_y = match style.overflow_y {
            Overflow::Visible => Overflow::Auto,
            Overflow::Clip => Overflow::Hidden,
            overflow => overflow,
        };
    }
    if y_is_scroll_container {
        style.overflow_x = match style.overflow_x {
            Overflow::Visible => Overflow::Auto,
            Overflow::Clip => Overflow::Hidden,
            overflow => overflow,
        };
    }
}

mod layout;
pub(in crate::css) use self::layout::*;
mod positioning;
pub(in crate::css) use self::positioning::*;
mod sizing;
pub(in crate::css) use self::sizing::*;
mod visual;
pub(in crate::css) use self::visual::*;
mod text;
pub(in crate::css) use self::text::*;