Implement standard scrollTo, scrollBy, and scrollIntoView

Signed-off-by: Nico Burns <nico@nicoburns.com>

Author: nicoburns

packages/blitz-dom/src/document.rs

@@ -178,6 +178,14 @@ pub enum DocumentEvent {
     ResourceLoad(ResourceLoadResponse),
 }
 
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
+pub enum ScrollBehavior {
+    #[default]
+    Auto,
+    Instant,
+    Smooth,
+}
+
 pub struct BaseDocument {
     /// ID of the document
     id: usize,
@@ -1879,7 +1887,7 @@ impl BaseDocument {
         self.viewport_scroll != initial
     }
 
-    pub fn scroll_by(
+    pub(crate) fn scroll_chain_by(
         &mut self,
         anchor_node_id: Option<usize>,
         scroll_x: f64,
@@ -1918,24 +1926,7 @@ impl BaseDocument {
         })
     }
 
-    /// Scroll the viewport so that the given node is aligned with the top of the viewport.
-    pub fn scroll_to_node(&mut self, node_id: usize) {
-        let Some(node) = self.nodes.get(node_id) else {
-            return;
-        };
-
-        // `absolute_position` gives the node's position in document space (it does not
-        // account for the viewport scroll), so it is the scroll offset we want to land on.
-        let target = node.absolute_position(0.0, 0.0);
-        let current = self.viewport_scroll;
-
-        // `scroll_viewport_by` subtracts the delta from the current scroll offset, so pass
-        // `current - target` in order to land on `target`.
-        self.scroll_viewport_by(current.x - target.x as f64, current.y - target.y as f64);
-    }
-
-    /// Duration (in milliseconds) of an animated scroll started via
-    /// [`BaseDocument::scroll_to_node_smooth`] or [`BaseDocument::scroll_to_fragment_smooth`].
+    /// Duration (in milliseconds) of an animated scroll.
     const SMOOTH_SCROLL_DURATION_MS: f64 = 300.0;
 
     /// Returns the current scroll offset and the maximum scroll offset (the minimum is
@@ -1999,52 +1990,64 @@ impl BaseDocument {
         self.shell_provider.request_redraw();
     }
 
-    /// Like [`BaseDocument::scroll_to_node`], but animates the viewport towards the node
-    /// instead of jumping instantly.
-    pub fn scroll_to_node_smooth(&mut self, node_id: usize) {
-        let Some(node) = self.nodes.get(node_id) else {
+    fn should_scroll_smoothly(&self, node_id: usize, behavior: ScrollBehavior) -> bool {
+        match behavior {
+            ScrollBehavior::Auto => self.nodes.get(node_id).is_some_and(|node| {
+                node.primary_styles().is_some_and(|style| {
+                    style.clone_scroll_behavior()
+                        == style::computed_values::scroll_behavior::T::Smooth
+                })
+            }),
+            ScrollBehavior::Instant => false,
+            ScrollBehavior::Smooth => true,
+        }
+    }
+
+    /// Scroll an element to the given absolute scroll offset in CSS pixels.
+    pub fn scroll_to(&mut self, node_id: usize, x: f64, y: f64, behavior: ScrollBehavior) {
+        if self.nodes.get(node_id).is_none() {
             return;
+        }
+
+        let (current, max) = self.node_scroll_state(node_id);
+        let target = crate::Point {
+            x: x.clamp(0.0, max.x),
+            y: y.clamp(0.0, max.y),
         };
 
-        let target = node.absolute_position(0.0, 0.0);
-        self.start_scroll_animation(
-            None,
-            crate::Point {
-                x: target.x as f64,
-                y: target.y as f64,
-            },
-        );
+        if self.should_scroll_smoothly(node_id, behavior) {
+            self.start_scroll_animation(Some(node_id), target);
+        } else {
+            self.scroll_animation = ScrollAnimationState::None;
+            self.scroll_node_by(
+                node_id,
+                current.x - target.x,
+                current.y - target.y,
+                &mut |_| {},
+            );
+            self.shell_provider.request_redraw();
+        }
     }
 
-    /// Scroll a node to the given absolute scroll offset (in CSS pixels), clamped to the
-    /// node's scrollable range. Scrolls on the root element are applied to the viewport.
-    pub fn scroll_node_to(&mut self, node_id: usize, x: f64, y: f64) {
-        let (current, max) = self.node_scroll_state(node_id);
-        let target_x = x.clamp(0.0, max.x);
-        let target_y = y.clamp(0.0, max.y);
-
-        // `scroll_node_by` works in deltas (subtracted from the current offset), so pass
-        // `current - target` to land on `target`. Because the target is pre-clamped to the
-        // scrollable range, no scroll is bubbled up to ancestors.
-        self.scroll_node_by(
-            node_id,
-            current.x - target_x,
-            current.y - target_y,
-            &mut |_| {},
-        );
+    /// Scroll an element by the given relative offset in CSS pixels.
+    pub fn scroll_by(&mut self, node_id: usize, x: f64, y: f64, behavior: ScrollBehavior) {
+        let current = self.node_scroll_state(node_id).0;
+        self.scroll_to(node_id, current.x + x, current.y + y, behavior);
     }
 
-    /// Like [`BaseDocument::scroll_node_to`], but animates towards the offset instead of
-    /// jumping instantly.
-    pub fn scroll_node_to_smooth(&mut self, node_id: usize, x: f64, y: f64) {
-        let (_, max) = self.node_scroll_state(node_id);
-        self.start_scroll_animation(
-            Some(node_id),
-            crate::Point {
-                x: x.clamp(0.0, max.x),
-                y: y.clamp(0.0, max.y),
-            },
-        );
+    /// Scroll the viewport so that the given element is aligned with its top-left edge.
+    pub fn scroll_into_view(&mut self, node_id: usize, behavior: ScrollBehavior) {
+        let Some(target) = self
+            .nodes
+            .get(node_id)
+            .map(|node| node.absolute_position(0.0, 0.0))
+        else {
+            return;
+        };
+        let Some(root_id) = self.try_root_element().map(|root| root.id) else {
+            return;
+        };
+        self.scroll_to(root_id, target.x as f64, target.y as f64, behavior);
     }
 
     /// Resolve a URL fragment (the `#...` part of a URL) to a scroll target.
@@ -2074,40 +2077,38 @@ impl BaseDocument {
         None
     }
 
-    /// Scroll to the element targeted by the given URL fragment (the `#...` part of a URL).
-    ///
-    /// An empty fragment (or a `top` fragment that matches no element) scrolls to the top
-    /// of the document, matching browser behaviour. Returns `true` if a scroll target was
-    /// found.
-    pub fn scroll_to_fragment(&mut self, fragment: &str) -> bool {
+    fn scroll_to_fragment_with_behavior(
+        &mut self,
+        fragment: &str,
+        behavior: ScrollBehavior,
+    ) -> bool {
         match self.resolve_fragment_scroll_target(fragment) {
             Some(Some(node_id)) => {
-                self.scroll_to_node(node_id);
+                self.scroll_into_view(node_id, behavior);
                 true
             }
             Some(None) => {
-                let current = self.viewport_scroll;
-                self.scroll_viewport_by(current.x, current.y);
+                let root_id = self.root_element().id;
+                self.scroll_to(root_id, 0.0, 0.0, behavior);
                 true
             }
             None => false,
         }
     }
 
+    /// Scroll to the element targeted by the given URL fragment (the `#...` part of a URL).
+    ///
+    /// An empty fragment (or a `top` fragment that matches no element) scrolls to the top
+    /// of the document, matching browser behaviour. Returns `true` if a scroll target was
+    /// found.
+    pub fn scroll_to_fragment(&mut self, fragment: &str) -> bool {
+        self.scroll_to_fragment_with_behavior(fragment, ScrollBehavior::Auto)
+    }
+
     /// Like [`BaseDocument::scroll_to_fragment`], but animates the viewport towards the
     /// target instead of jumping instantly. Returns `true` if a scroll target was found.
     pub fn scroll_to_fragment_smooth(&mut self, fragment: &str) -> bool {
-        match self.resolve_fragment_scroll_target(fragment) {
-            Some(Some(node_id)) => {
-                self.scroll_to_node_smooth(node_id);
-                true
-            }
-            Some(None) => {
-                self.start_scroll_animation(None, crate::Point::ZERO);
-                true
-            }
-            None => false,
-        }
+        self.scroll_to_fragment_with_behavior(fragment, ScrollBehavior::Smooth)
     }
 
     /// Computes the size and position of the `Node` relative to the viewport

packages/blitz-dom/src/events/pointer.rs

@@ -11,7 +11,7 @@ use blitz_traits::{
 };
 use keyboard_types::Modifiers;
 use markup5ever::local_name;
-use style::{computed_values::scroll_behavior::T as ScrollBehavior, values::computed::UserSelect};
+use style::values::computed::UserSelect;
 use taffy::AbsoluteAxis;
 
 use crate::{
@@ -233,7 +233,7 @@ pub(crate) fn handle_pointermove<F: FnMut(DomEvent)>(
         let target = state.target;
         let (dx, dy) = state.update(time_ms, event.screen_x(), event.screen_y());
 
-        let has_changed = doc.scroll_by(Some(target), dx, dy, &mut dispatch_event);
+        let has_changed = doc.scroll_chain_by(Some(target), dx, dy, &mut dispatch_event);
         return has_changed;
     }
 
@@ -253,7 +253,7 @@ pub(crate) fn handle_pointermove<F: FnMut(DomEvent)>(
             AbsoluteAxis::Horizontal => (-delta_px * ratio, 0.0),
             AbsoluteAxis::Vertical => (0.0, -delta_px * ratio),
         };
-        let has_changed = doc.scroll_by(Some(node_id), dx, dy, &mut dispatch_event);
+        let has_changed = doc.scroll_chain_by(Some(node_id), dx, dy, &mut dispatch_event);
         return has_changed;
     }
 
@@ -685,17 +685,7 @@ pub(crate) fn handle_click(
                             // perform in-page fragment navigation (scrolling) instead of a
                             // full navigation.
                             if url.fragment().is_some() && doc.url.is_same_document(&url) {
-                                let fragment = url.fragment().unwrap_or_default();
-                                let behavior = doc
-                                    .try_root_element()
-                                    .and_then(|root| root.primary_styles())
-                                    .map(|style| style.clone_scroll_behavior())
-                                    .unwrap_or(ScrollBehavior::Auto);
-                                if behavior == ScrollBehavior::Smooth {
-                                    doc.scroll_to_fragment_smooth(fragment);
-                                } else {
-                                    doc.scroll_to_fragment(fragment);
-                                }
+                                doc.scroll_to_fragment(url.fragment().unwrap_or_default());
                             } else {
                                 doc.navigation_provider.navigate_to(NavigationOptions::new(
                                     url,
@@ -792,7 +782,7 @@ pub(crate) fn handle_wheel<F: FnMut(DomEvent)>(
         BlitzWheelDelta::Pixels(x, y) => (x, y),
     };
 
-    let has_changed = doc.scroll_by(
+    let has_changed = doc.scroll_chain_by(
         doc.get_hover_node_id(),
         scroll_x,
         scroll_y,

packages/blitz-dom/src/lib.rs

@@ -72,7 +72,7 @@ mod accessibility;
 pub use crate::node::Widget;
 
 pub use config::{DocumentConfig, StyleThreading};
-pub use document::{BaseDocument, DocGuard, DocGuardMut, Document, PlainDocument};
+pub use document::{BaseDocument, DocGuard, DocGuardMut, Document, PlainDocument, ScrollBehavior};
 pub use markup5ever::{
     LocalName, Namespace, NamespaceStaticSet, Prefix, PrefixStaticSet, QualName, local_name,
     namespace_prefix, namespace_url, ns,

packages/blitz-dom/src/resolve.rs

@@ -218,7 +218,7 @@ impl BaseDocument {
                 let dx = fling_state.x_velocity * time_diff_ms;
                 let dy = fling_state.y_velocity * time_diff_ms;
 
-                self.scroll_by(Some(fling_state.target), dx, dy, &mut |_| {});
+                self.scroll_chain_by(Some(fling_state.target), dx, dy, &mut |_| {});
                 if fling_state.x_velocity.abs() < 0.1 && fling_state.y_velocity.abs() < 0.1 {
                     self.scroll_animation = ScrollAnimationState::None;
                 }

packages/blitz-html/tests/fragment_navigation.rs

@@ -1,7 +1,7 @@
 //! Fragment navigation: resolving a URL fragment (the `#...` part) to an element
 //! and scrolling the viewport to it.
 
-use blitz_dom::{Document, DocumentConfig, FontContext};
+use blitz_dom::{Document, DocumentConfig, FontContext, ScrollBehavior};
 use blitz_html::{HtmlDocument, HtmlProvider};
 use blitz_traits::{
     events::{
@@ -176,13 +176,13 @@ fn scroll_to_fragment_smooth_unknown_returns_false() {
 }
 
 #[test]
-fn scroll_to_node_smooth_animates() {
+fn scroll_into_view_smooth_animates() {
     let mut doc = layout_doc(HTML);
 
     let target = doc.query_selector("#target").unwrap().unwrap();
     let target_y = doc.get_node(target).unwrap().final_layout.location.y as f64;
 
-    doc.scroll_to_node_smooth(target);
+    doc.scroll_into_view(target, ScrollBehavior::Smooth);
     assert!(doc.is_animating());
 
     drive_until_settled(&mut doc);
@@ -222,37 +222,37 @@ fn fragment_link_uses_auto_scroll_behavior_from_root_style() {
 
 /// A page with a nested scrollable container (`#scroller`) whose content overflows.
 const SCROLLER_HTML: &str = r#"<html><body style="margin:0">
-    <div id="scroller" style="height:100px; overflow:scroll">
+    <div id="scroller" style="height:100px; overflow:scroll; scroll-behavior:smooth">
         <div style="height:1000px"></div>
     </div>
 </body></html>"#;
 
 #[test]
-fn scroll_node_to_sets_element_offset_and_clamps() {
+fn scroll_to_sets_element_offset_and_clamps() {
     let mut doc = layout_doc(SCROLLER_HTML);
     let scroller = doc.query_selector("#scroller").unwrap().unwrap();
 
     // Scroll the element's own content down by 200px.
-    doc.scroll_node_to(scroller, 0.0, 200.0);
+    doc.scroll_to(scroller, 0.0, 200.0, ScrollBehavior::Instant);
     assert_eq!(doc.get_node(scroller).unwrap().scroll_offset.y, 200.0);
 
     // Scrolling far past the end clamps to the element's maximum scroll offset.
     let max = doc.get_node(scroller).unwrap().final_layout.scroll_height() as f64;
     assert!(max > 0.0);
-    doc.scroll_node_to(scroller, 0.0, 100_000.0);
+    doc.scroll_to(scroller, 0.0, 100_000.0, ScrollBehavior::Instant);
     assert_eq!(doc.get_node(scroller).unwrap().scroll_offset.y, max);
 
     // Scrolling to a negative offset clamps to 0.
-    doc.scroll_node_to(scroller, 0.0, -100.0);
+    doc.scroll_to(scroller, 0.0, -100.0, ScrollBehavior::Instant);
     assert_eq!(doc.get_node(scroller).unwrap().scroll_offset.y, 0.0);
 }
 
 #[test]
-fn scroll_node_to_smooth_animates_element_offset() {
+fn scroll_to_smooth_animates_element_offset() {
     let mut doc = layout_doc(SCROLLER_HTML);
     let scroller = doc.query_selector("#scroller").unwrap().unwrap();
 
-    doc.scroll_node_to_smooth(scroller, 0.0, 200.0);
+    doc.scroll_to(scroller, 0.0, 200.0, ScrollBehavior::Smooth);
     assert!(doc.is_animating(), "node scroll should be animating");
     assert!(
         doc.get_node(scroller).unwrap().scroll_offset.y < 200.0,
@@ -263,3 +263,27 @@ fn scroll_node_to_smooth_animates_element_offset() {
     assert!(!doc.is_animating());
     assert_eq!(doc.get_node(scroller).unwrap().scroll_offset.y, 200.0);
 }
+
+#[test]
+fn scroll_by_uses_relative_offsets_and_clamps() {
+    let mut doc = layout_doc(SCROLLER_HTML);
+    let scroller = doc.query_selector("#scroller").unwrap().unwrap();
+
+    doc.scroll_to(scroller, 0.0, 100.0, ScrollBehavior::Instant);
+    doc.scroll_by(scroller, 0.0, 75.0, ScrollBehavior::Instant);
+    assert_eq!(doc.get_node(scroller).unwrap().scroll_offset.y, 175.0);
+
+    doc.scroll_by(scroller, 0.0, -300.0, ScrollBehavior::Instant);
+    assert_eq!(doc.get_node(scroller).unwrap().scroll_offset.y, 0.0);
+}
+
+#[test]
+fn auto_behavior_uses_scroll_behavior_style() {
+    let mut doc = layout_doc(SCROLLER_HTML);
+    let scroller = doc.query_selector("#scroller").unwrap().unwrap();
+
+    doc.scroll_to(scroller, 0.0, 200.0, ScrollBehavior::Auto);
+    assert!(doc.is_animating());
+    drive_until_settled(&mut doc);
+    assert_eq!(doc.get_node(scroller).unwrap().scroll_offset.y, 200.0);
+}