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")