Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-browser-engine

Source of release 0.6.0

0.6.0 / src / web / animations / scroll_timeline.lucb

#==============================================================================================
#
#   scroll_timeline - Animations::ScrollTimeline: a progress-based timeline driven by the
#                     scroll position of a scroll container
#
#   DESCRIPTION:
#       Port of Libraries/LibWeb/Animations/ScrollTimeline.cpp (lines 1-227) with the inline
#       members of ScrollTimeline.h, by region p4a: creating one (the `scroll()` notation of
#       animation-timeline makes one with an anonymous source), its source element, the
#       computed scroll axis, its current time (the scroll progress as a percentage), its
#       propagated source, and the CSS axis conversion. construct_impl takes its options from
#       script (phase 3 calls it).
#
#       Copyright (c) 2026, Callum Law <callumlaw1709@outlook.com>.
#       SPDX-License-Identifier: BSD-2-Clause
#
#==============================================================================================

# mark: Creation and source =====================================================================

## Ported from Libraries/LibWeb/Animations/ScrollTimeline.cpp:20 Web::Animations::ScrollTimeline::create.
pub func animations_scroll_timeline_create(realm: Realm*, document: DomDocument*, source: AnimationsScrollTimelineSource, axis: BindScrollAxis) -> AnimationsScrollTimeline*:
    let timeline = realm_create_animations_scroll_timeline(realm, realm, document, source, axis)

    # NB: The passed timestamp is ignored for ScrollTimelines so we can just pass 0 here.
    animations_animation_timeline_update_current_time(timeline.animations_animation_timeline(), 0.0)

    return timeline

## Ported from Libraries/LibWeb/Animations/ScrollTimeline.cpp:31 Web::Animations::ScrollTimeline::construct_impl.
# https://drafts.csswg.org/scroll-animations-1/#dom-scrolltimeline-scrolltimeline
pub func animations_scroll_timeline_construct_impl(realm: Realm*, options: AnimationsScrollTimelineOptions) -> AnimationsScrollTimeline*:
    let document = html_window_associated_document(as_html_window((gc.Cell*)realm_global_object(realm)))

    # 1. Let timeline be the new ScrollTimeline object.
    # 2. Set the source of timeline to:
    var source: DomElement*? = none
    # If the source member of options is present,
    # The source member of options.
    if let given = options.source:
        source = given
    # Otherwise,
    # The scrollingElement of the Document associated with the Window that is the current global object.
    elif let scrolling_element = dom_document_scrolling_element(document):
        source = scrolling_element

    # 3. Set the axis property of timeline to the corresponding value from options.
    return animations_scroll_timeline_create(realm, document, AnimationsScrollTimelineSource.element(source), options.axis)

## Ported from Libraries/LibWeb/Animations/ScrollTimeline.cpp:53 Web::Animations::ScrollTimeline::source.
pub func animations_scroll_timeline_source(this: AnimationsScrollTimeline*) -> DomElement*?:
    match this.m_source:
        .element(source):
            return source
        .anonymous_source(anonymous_source):
            match anonymous_source.scroller:
                .root:
                    return dom_document_document_element(dom_abstract_element_document(&anonymous_source.target))
                .nearest:
                    var ancestor = dom_abstract_element_parent_element(&anonymous_source.target)

                    while let element = ancestor:
                        if dom_element_is_scroll_container(element):
                            break
                        ancestor = dom_node_parent_element(element.dom_node())

                    return ancestor
                .self_:
                    var target = anonymous_source.target
                    return dom_abstract_element_element(&target)
                _:
                    trap("VERIFY_NOT_REACHED")

## Ported from Libraries/LibWeb/Animations/ScrollTimeline.h:39 Web::Animations::ScrollTimeline::duration (override).
pub func animations_scroll_timeline_duration_impl(base: AnimationsAnimationTimeline*) -> AnimationsTimeValue?:
    return AnimationsTimeValue(type_ = AnimationsTimeValueType.percentage, value = 100.0)

## Ported from Libraries/LibWeb/Animations/ScrollTimeline.h:42 Web::Animations::ScrollTimeline::axis.
pub func animations_scroll_timeline_axis(this: AnimationsScrollTimeline*) -> BindScrollAxis:
    return this.m_axis

## Ported from Libraries/LibWeb/Animations/ScrollTimeline.h:44 Web::Animations::ScrollTimeline::source_internal.
pub func animations_scroll_timeline_source_internal(this: AnimationsScrollTimeline*) -> AnimationsScrollTimelineSource:
    return this.m_source

## Ported from Libraries/LibWeb/Animations/ScrollTimeline.h:48 Web::Animations::ScrollTimeline::is_progress_based (override).
pub func animations_scroll_timeline_is_progress_based_impl(base: AnimationsAnimationTimeline*) -> bool:
    return true

## Ported from Libraries/LibWeb/Animations/ScrollTimeline.h:49 Web::Animations::ScrollTimeline::can_convert_a_timeline_time_to_an_origin_relative_time (override).
pub func animations_scroll_timeline_can_convert_a_timeline_time_to_an_origin_relative_time_impl(base: AnimationsAnimationTimeline*) -> bool:
    return false

# mark: Current time ============================================================================

## Web::Animations::ComputedScrollAxis (Libraries/LibWeb/Animations/ScrollTimeline.cpp:80).
struct AnimationsComputedScrollAxis:
    var is_vertical: bool
    var is_reversed: bool

## Ported from Libraries/LibWeb/Animations/ScrollTimeline.cpp:84 Web::Animations::computed_scroll_axis.
func animations_computed_scroll_axis(axis: BindScrollAxis, writing_mode: css_data.WritingMode, direction: css_data.Direction) -> AnimationsComputedScrollAxis:
    # NB: This is based on the table specified here: https://drafts.csswg.org/css-writing-modes-4/#logical-to-physical

    # FIXME: Note: The used direction depends on the computed writing-mode and text-orientation: in vertical writing
    #              modes, a text-orientation value of upright forces the used direction to ltr.
    let used_direction = direction

    match axis:
        .block:
            match writing_mode:
                .horizontal_tb:
                    return AnimationsComputedScrollAxis(is_vertical = true, is_reversed = false)
                .vertical_rl, .sideways_rl:
                    return AnimationsComputedScrollAxis(is_vertical = false, is_reversed = true)
                .vertical_lr, .sideways_lr:
                    return AnimationsComputedScrollAxis(is_vertical = false, is_reversed = false)
                _:
                    trap("VERIFY_NOT_REACHED")
        .inline:
            match writing_mode:
                .horizontal_tb:
                    return AnimationsComputedScrollAxis(is_vertical = false, is_reversed = used_direction == css_data.Direction.rtl)
                .vertical_rl, .sideways_rl, .vertical_lr:
                    return AnimationsComputedScrollAxis(is_vertical = true, is_reversed = used_direction == css_data.Direction.rtl)
                .sideways_lr:
                    return AnimationsComputedScrollAxis(is_vertical = true, is_reversed = used_direction == css_data.Direction.ltr)
                _:
                    trap("VERIFY_NOT_REACHED")
        .x:
            return AnimationsComputedScrollAxis(is_vertical = false, is_reversed = false)
        .y:
            return AnimationsComputedScrollAxis(is_vertical = true, is_reversed = false)
        _:
            trap("VERIFY_NOT_REACHED")

## Ported from Libraries/LibWeb/Animations/ScrollTimeline.cpp:131 Web::Animations::ScrollTimeline::update_current_time (override).
pub func animations_scroll_timeline_update_current_time_impl(base: AnimationsAnimationTimeline*, timestamp: f64):
    _ = timestamp
    let this = (AnimationsScrollTimeline*)base

    # https://drafts.csswg.org/scroll-animations-1/#ref-for-dom-animationtimeline-currenttime
    # currentTime represents the scroll progress of the scroll container as a percentage CSSUnitValue, with 0%
    # representing its startmost scroll position (in the writing mode of the scroll container). Null when the timeline
    # is inactive.

    # NB: We set the current time to null at the start of this so we can easily just return when the timeline should be
    #     inactive, only setting it to a resolved value if the timeline is active.
    animations_animation_timeline_set_current_time(base, none)

    let propagated_source = animations_scroll_timeline_get_propagated_source(this)

    # If the source of a ScrollTimeline is an element whose principal box does not exist or is not a scroll container,
    # or if there is no scrollable overflow, then the ScrollTimeline is inactive.
    # NB: Called during animation timeline update, which runs before layout is up to date.
    var layout_node: LayoutNodeWithStyle*? = none
    var paintable_box: PaintPaintableBox*? = none
    match propagated_source:
        .element(source):
            let element = source else return
            layout_node = dom_element_unsafe_layout_node(element)
            paintable_box = dom_node_unsafe_paintable_box(element.dom_node())
        .document(source):
            let document = source else return
            if let viewport = dom_document_unsafe_layout_node(document):
                layout_node = viewport.layout_node_with_style()
            paintable_box = dom_node_unsafe_paintable_box(document.dom_node())

    let node = layout_node else return
    if not layout_node_with_style_is_scroll_container(node):
        return

    let box = paintable_box else return
    if not paint_paintable_box_has_scrollable_overflow(box):
        return

    let scrollable_overflow_rect = paint_paintable_box_scrollable_overflow_rect(box) else trap("VERIFY: Optional::value()")
    let computed_values = &paint_paintable_computed_values(box.paint_paintable()).computed_values
    let computed_axis = animations_computed_scroll_axis(this.m_axis, css_computed_values_writing_mode(computed_values), css_computed_values_direction(computed_values))

    # https://drafts.csswg.org/scroll-animations-1/#scroll-timeline-progress
    # If the 0% position and 100% position coincide (i.e. the denominator in the current time formula is zero), the timeline is inactive.
    if computed_axis.is_vertical and gfx.css_pixel_rect_height(&scrollable_overflow_rect) == paint_paintable_box_content_height(box):
        return
    if not computed_axis.is_vertical and gfx.css_pixel_rect_width(&scrollable_overflow_rect) == paint_paintable_box_content_width(box):
        return

    # FIXME: In paged media, scroll progress timelines that would otherwise reference the document viewport are also inactive.

    # https://drafts.csswg.org/scroll-animations-1/#scroll-timeline-progress
    # Progress (the current time) for a scroll progress timeline is calculated as:
    #     scroll offset ÷ (scrollable overflow size − scroll container size)
    # FIXME: Scroll offset is currently incorrect as it is always relative to the top left of the scrollable overflow
    #        rect when it should instead be relative to the scroll origin.
    let scroll_offset = paint_paintable_box_scroll_offset(box)
    var progress = 0.0
    if computed_axis.is_vertical:
        progress = gfx.css_pixel_point_y(&scroll_offset).to_double() / (gfx.css_pixel_rect_height(&scrollable_overflow_rect).to_double() - paint_paintable_box_content_height(box).to_double())
    else:
        progress = gfx.css_pixel_point_x(&scroll_offset).to_double() / (gfx.css_pixel_rect_width(&scrollable_overflow_rect).to_double() - paint_paintable_box_content_width(box).to_double())

    # FIXME: Support the case where the computed scroll axis is reversed

    animations_animation_timeline_set_current_time(base, AnimationsTimeValue(type_ = AnimationsTimeValueType.percentage, value = progress * 100.0))

# mark: Construction and edges ==================================================================

## Ported from Libraries/LibWeb/Animations/ScrollTimeline.cpp:183 Web::Animations::ScrollTimeline::ScrollTimeline (private).
func animations_scroll_timeline_construct(this: AnimationsScrollTimeline*, realm: Realm*, document: DomDocument*, source: AnimationsScrollTimelineSource, axis: BindScrollAxis):
    animations_animation_timeline_construct(this.animations_animation_timeline(), realm)
    this.m_source = source
    this.m_axis = axis
    animations_animation_timeline_set_associated_document(this.animations_animation_timeline(), document)

## Ported from Libraries/LibWeb/Animations/ScrollTimeline.cpp:191 Web::Animations::ScrollTimeline::visit_edges (override).
func animations_scroll_timeline_visit_edges_impl(base: gc.Cell*, visitor: gc.CellVisitor*):
    let this = (AnimationsScrollTimeline*)base
    animations_animation_timeline_visit_edges_impl(base, visitor)
    match this.m_source:
        .element(source):
            gc.cell_visitor_visit_t(visitor, source)
        .anonymous_source(anonymous_source):
            dom_abstract_element_visit(&anonymous_source.target, visitor)

## Ported from Libraries/LibWeb/Animations/ScrollTimeline.cpp:199 Web::Animations::ScrollTimeline::initialize (override).
func animations_scroll_timeline_initialize_impl(base: JsCell*, realm: Realm*):
    web_set_prototype_for_interface(base, realm, BindInterfaceName.scroll_timeline)
    animations_animation_timeline_initialize_impl(base, realm)

## Variant<GC::Ptr<DOM::Element const>, GC::Ptr<DOM::Document>>: ScrollTimeline's propagated source.
enum AnimationsScrollTimelinePropagatedSource:
    element(value: DomElement*?)
    document(value: DomDocument*?)

## Ported from Libraries/LibWeb/Animations/ScrollTimeline.cpp:205 Web::Animations::ScrollTimeline::get_propagated_source (private).
func animations_scroll_timeline_get_propagated_source(this: AnimationsScrollTimeline*) -> AnimationsScrollTimelinePropagatedSource:
    let source = animations_scroll_timeline_source(this)

    # https://drafts.csswg.org/scroll-animations-1/#scroll-notation
    # References to the root element propagate to the document viewport (which functions as its scroll container).
    if let element = source:
        if dom_document_document_element(dom_node_document(element.dom_node())) == element:
            return AnimationsScrollTimelinePropagatedSource.document(dom_node_owner_document(element.dom_node()))

    return AnimationsScrollTimelinePropagatedSource.element(source)

## Ported from Libraries/LibWeb/Animations/ScrollTimeline.cpp:216 Web::Animations::css_axis_to_bindings_scroll_axis.
pub func animations_css_axis_to_bindings_scroll_axis(axis: css_data.Axis) -> BindScrollAxis:
    match axis:
        .block:
            return BindScrollAxis.block
        .inline:
            return BindScrollAxis.inline
        .x:
            return BindScrollAxis.x
        .y:
            return BindScrollAxis.y
        _:
            trap("VERIFY_NOT_REACHED")