freya_components/scrollviews/

virtual_scrollview.rs

use std::{
    ops::Range,
    time::Duration,
};

use freya_core::prelude::*;
use freya_sdk::timeout::use_timeout;
use torin::{
    geometry::CursorPoint,
    node::Node,
    prelude::Direction,
    size::Size,
};

use crate::scrollviews::{
    ScrollBar,
    ScrollConfig,
    ScrollController,
    ScrollThumb,
    shared::{
        Axis,
        get_container_sizes,
        get_corrected_scroll_position,
        get_scroll_position_from_cursor,
        get_scroll_position_from_wheel,
        get_scrollbar_pos_and_size,
        handle_key_event,
        is_scrollbar_visible,
    },
    use_scroll_controller,
};

/// Defines how each item of a [`VirtualScrollView`] is sized along the scroll axis.
///
/// Build one from a fixed value or from a closure that resolves the size of each
/// item by its index:
///
/// ```rust
/// # use freya::prelude::*;
/// let fixed: ItemSize = 25.0f32.into();
/// let dynamic: ItemSize =
///     (|index: usize| if index.is_multiple_of(2) { 25.0 } else { 50.0 }).into();
/// ```
#[derive(Clone, PartialEq)]
pub enum ItemSize {
    /// Every item shares the same size in pixels.
    Fixed(f32),
    /// Each item is sized individually through a callback that receives its index.
    Dynamic(Callback<usize, f32>),
}

impl ItemSize {
    /// Size in pixels of the item at `index`.
    fn at(&self, index: usize) -> f32 {
        match self {
            Self::Fixed(size) => *size,
            Self::Dynamic(callback) => callback.call(index),
        }
    }

    /// Range of items that fall inside the viewport for the given scroll position,
    /// together with the offset that positions the first visible item correctly.
    fn visible_range(
        &self,
        viewport_size: f32,
        scroll_position: f32,
        length: usize,
    ) -> (Range<usize>, f32) {
        let scroll_distance = (-scroll_position).max(0.0);
        match self {
            Self::Fixed(size) => {
                if *size <= 0.0 {
                    return (0..0, 0.0);
                }
                let start = scroll_distance / size;
                let potentially_visible = (viewport_size / size) + 1.0;
                let start_index = (start as usize).min(length);
                let end_index = ((start + potentially_visible) as usize).min(length);
                (
                    start_index..end_index,
                    start.floor() * size - scroll_distance,
                )
            }
            Self::Dynamic(callback) => {
                let mut start = 0;
                let mut cumulative = 0.0;
                while start < length {
                    let item = callback.call(start);
                    if cumulative + item > scroll_distance {
                        break;
                    }
                    cumulative += item;
                    start += 1;
                }
                let offset = cumulative - scroll_distance;
                let mut end = start;
                while end < length && cumulative < scroll_distance + viewport_size {
                    cumulative += callback.call(end);
                    end += 1;
                }
                (start..end, offset)
            }
        }
    }

    /// Total size of the content along the scroll axis.
    ///
    /// [`Self::Fixed`] is exact. [`Self::Dynamic`] extrapolates from the average size of
    /// the items down to the viewport bottom, keeping the scrollbar stable as it scrolls.
    fn total_size(&self, viewport_size: f32, scroll_position: f32, length: usize) -> f32 {
        match self {
            Self::Fixed(size) => size * length as f32,
            Self::Dynamic(callback) => {
                if length == 0 {
                    return 0.0;
                }
                let viewport_bottom = (-scroll_position).max(0.0) + viewport_size;
                let mut measured = callback.call(0);
                let mut count = 1;
                while count < length && measured < viewport_bottom {
                    measured += callback.call(count);
                    count += 1;
                }
                (measured / count as f32) * length as f32
            }
        }
    }
}

impl Default for ItemSize {
    fn default() -> Self {
        Self::Fixed(0.)
    }
}

impl From<f32> for ItemSize {
    fn from(size: f32) -> Self {
        Self::Fixed(size)
    }
}

impl<F: Fn(usize) -> f32 + 'static> From<F> for ItemSize {
    fn from(callback: F) -> Self {
        Self::Dynamic(Callback::new(callback))
    }
}

/// Data passed to a [`VirtualScrollView`] builder for each rendered item.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct VirtualItem {
    pub index: usize,
    pub size: f32,
}

/// One-direction scrollable area that dynamically builds and renders items based in their size and current available size,
/// this is intended for apps using large sets of data that need good performance.
///
/// Unlike [`ScrollView`](crate::scrollviews::ScrollView), which lays out every child even when it is
/// off screen, a `VirtualScrollView` takes a builder closure and only calls it for the items that
/// are actually visible, so the cost stays roughly constant no matter how long the list is.
///
/// It needs two things to know which items fall inside the viewport:
/// [`item_size`](VirtualScrollView::item_size), the fixed size of each item along the scroll axis,
/// and [`length`](VirtualScrollView::length), the total number of items.
///
/// # Example
///
/// ```rust
/// # use freya::prelude::*;
/// fn app() -> impl IntoElement {
///     rect().child(
///         VirtualScrollView::new(|item, _| {
///             rect()
///                 .key(item.index)
///                 .height(Size::px(item.size))
///                 .padding(4.)
///                 .child(format!("Item {}", item.index))
///                 .into()
///         })
///         .length(300usize)
///         .item_size(25.),
///     )
/// }
///
/// # use freya_testing::prelude::*;
/// # launch_doc(|| {
/// #   rect().center().expanded().child(app())
/// # }, "./images/gallery_virtual_scrollview.png").with_hook(|t| {
/// #   t.move_cursor((125., 115.));
/// #   t.sync_and_update();
/// # });
/// ```
///
/// # Preview
/// ![VirtualScrollView Preview][virtual_scrollview]
#[cfg_attr(feature = "docs",
    doc = embed_doc_image::embed_image!("virtual_scrollview", "images/gallery_virtual_scrollview.png")
)]
#[derive(Clone)]
pub struct VirtualScrollView<D, B: Fn(VirtualItem, &D) -> Element> {
    builder: B,
    builder_data: D,
    item_size: ItemSize,
    length: usize,
    layout: LayoutData,
    show_scrollbar: bool,
    scroll_with_arrows: bool,
    scroll_controller: Option<ScrollController>,
    invert_scroll_wheel: bool,
    drag_scrolling: bool,
    key: DiffKey,
}

impl<D: PartialEq, B: Fn(VirtualItem, &D) -> Element> LayoutExt for VirtualScrollView<D, B> {
    fn get_layout(&mut self) -> &mut LayoutData {
        &mut self.layout
    }
}

impl<D: PartialEq, B: Fn(VirtualItem, &D) -> Element> ContainerSizeExt for VirtualScrollView<D, B> {}

impl<D: PartialEq, B: Fn(VirtualItem, &D) -> Element> KeyExt for VirtualScrollView<D, B> {
    fn write_key(&mut self) -> &mut DiffKey {
        &mut self.key
    }
}

impl<D: PartialEq, B: Fn(VirtualItem, &D) -> Element> PartialEq for VirtualScrollView<D, B> {
    fn eq(&self, other: &Self) -> bool {
        self.builder_data == other.builder_data
            && self.item_size == other.item_size
            && self.length == other.length
            && self.layout == other.layout
            && self.show_scrollbar == other.show_scrollbar
            && self.scroll_with_arrows == other.scroll_with_arrows
            && self.scroll_controller == other.scroll_controller
            && self.invert_scroll_wheel == other.invert_scroll_wheel
    }
}

impl<B: Fn(VirtualItem, &()) -> Element> VirtualScrollView<(), B> {
    /// Creates a virtual scroll view that builds each item on demand from its [`VirtualItem`].
    pub fn new(builder: B) -> Self {
        Self {
            builder,
            builder_data: (),
            item_size: ItemSize::default(),
            length: 0,
            layout: {
                let mut l = LayoutData::default();
                l.layout.width = Size::fill();
                l.layout.height = Size::fill();
                l
            },
            show_scrollbar: true,
            scroll_with_arrows: true,
            scroll_controller: None,
            invert_scroll_wheel: false,
            drag_scrolling: true,
            key: DiffKey::None,
        }
    }

    /// Like [`new`](Self::new) but driven by the given [`ScrollController`].
    pub fn new_controlled(builder: B, scroll_controller: ScrollController) -> Self {
        Self {
            builder,
            builder_data: (),
            item_size: ItemSize::default(),
            length: 0,
            layout: {
                let mut l = LayoutData::default();
                l.layout.width = Size::fill();
                l.layout.height = Size::fill();
                l
            },
            show_scrollbar: true,
            scroll_with_arrows: true,
            scroll_controller: Some(scroll_controller),
            invert_scroll_wheel: false,
            drag_scrolling: true,
            key: DiffKey::None,
        }
    }
}

impl<D, B: Fn(VirtualItem, &D) -> Element> VirtualScrollView<D, B> {
    /// Like [`new`](Self::new) but passes shared `builder_data` to every item build.
    ///
    /// The builder closure cannot be compared across renders, so data captured inside it never
    /// triggers a rebuild. Passing the data here instead makes it part of the view's `PartialEq`,
    /// so the visible items are rebuilt whenever it changes.
    ///
    /// ```rust
    /// # use freya::prelude::*;
    /// fn app() -> impl IntoElement {
    ///     let items = use_state(|| vec!["a".to_string(), "b".to_string(), "c".to_string()]);
    ///
    ///     // The current items are passed as data, so editing `items` rebuilds the visible rows.
    ///     VirtualScrollView::new_with_data(items.read().clone(), |item, items: &Vec<String>| {
    ///         rect()
    ///             .key(item.index)
    ///             .height(Size::px(item.size))
    ///             .child(items[item.index].clone())
    ///             .into()
    ///     })
    ///     .length(items.read().len())
    ///     .item_size(25.)
    /// }
    /// ```
    pub fn new_with_data(builder_data: D, builder: B) -> Self {
        Self {
            builder,
            builder_data,
            item_size: ItemSize::default(),
            length: 0,
            layout: Node {
                width: Size::fill(),
                height: Size::fill(),
                ..Default::default()
            }
            .into(),
            show_scrollbar: true,
            scroll_with_arrows: true,
            scroll_controller: None,
            invert_scroll_wheel: false,
            drag_scrolling: true,
            key: DiffKey::None,
        }
    }

    /// Like [`new_with_data`](Self::new_with_data) but driven by the given [`ScrollController`].
    pub fn new_with_data_controlled(
        builder_data: D,
        builder: B,
        scroll_controller: ScrollController,
    ) -> Self {
        Self {
            builder,
            builder_data,
            item_size: ItemSize::default(),
            length: 0,

            layout: Node {
                width: Size::fill(),
                height: Size::fill(),
                ..Default::default()
            }
            .into(),
            show_scrollbar: true,
            scroll_with_arrows: true,
            scroll_controller: Some(scroll_controller),
            invert_scroll_wheel: false,
            drag_scrolling: true,
            key: DiffKey::None,
        }
    }

    /// Toggles whether the scrollbar is shown when the content overflows.
    pub fn show_scrollbar(mut self, show_scrollbar: bool) -> Self {
        self.show_scrollbar = show_scrollbar;
        self
    }

    /// Sets the axis the items flow and scroll in.
    pub fn direction(mut self, direction: Direction) -> Self {
        self.layout.direction = direction;
        self
    }

    /// Toggles whether the arrow keys scroll the view while it is focused.
    pub fn scroll_with_arrows(mut self, scroll_with_arrows: impl Into<bool>) -> Self {
        self.scroll_with_arrows = scroll_with_arrows.into();
        self
    }

    /// Sets the size of the items along the scroll axis, used to decide which items to render.
    ///
    /// Accepts an [`ItemSize`], so it can be a fixed size for every item or a closure that
    /// resolves the size of each item by its index.
    pub fn item_size(mut self, item_size: impl Into<ItemSize>) -> Self {
        self.item_size = item_size.into();
        self
    }

    /// Sets the total number of items the view can scroll through.
    pub fn length(mut self, length: impl Into<usize>) -> Self {
        self.length = length.into();
        self
    }

    /// Inverts the direction of the mouse wheel relative to the content.
    pub fn invert_scroll_wheel(mut self, invert_scroll_wheel: impl Into<bool>) -> Self {
        self.invert_scroll_wheel = invert_scroll_wheel.into();
        self
    }

    /// Toggles scrolling by dragging the content, useful mainly for touch input.
    pub fn drag_scrolling(mut self, drag_scrolling: bool) -> Self {
        self.drag_scrolling = drag_scrolling;
        self
    }

    /// Attaches a [`ScrollController`] to drive this view externally.
    pub fn scroll_controller(
        mut self,
        scroll_controller: impl Into<Option<ScrollController>>,
    ) -> Self {
        self.scroll_controller = scroll_controller.into();
        self
    }

    /// Sets the minimum width the scroll view can shrink to.
    pub fn min_width(mut self, min_width: impl Into<Size>) -> Self {
        self.layout.minimum_width = min_width.into();
        self
    }

    /// Sets the minimum height the scroll view can shrink to.
    pub fn min_height(mut self, min_height: impl Into<Size>) -> Self {
        self.layout.minimum_height = min_height.into();
        self
    }

    /// Caps the width of the scroll view.
    pub fn max_width(mut self, max_width: impl Into<Size>) -> Self {
        self.layout.maximum_width = max_width.into();
        self
    }

    /// Caps the height of the scroll view.
    pub fn max_height(mut self, max_height: impl Into<Size>) -> Self {
        self.layout.maximum_height = max_height.into();
        self
    }
}

impl<D: PartialEq + 'static, B: Fn(VirtualItem, &D) -> Element + 'static> Component
    for VirtualScrollView<D, B>
{
    fn render(self: &VirtualScrollView<D, B>) -> impl IntoElement {
        let a11y_id = use_a11y();
        let mut timeout = use_timeout(|| Duration::from_millis(800));
        let mut pressing_shift = use_state(|| false);
        let mut clicking_scrollbar = use_state::<Option<(Axis, f64)>>(|| None);
        let mut size = use_state(SizedEventData::default);
        let mut scroll_controller = self
            .scroll_controller
            .unwrap_or_else(|| use_scroll_controller(ScrollConfig::default));
        let mut dragging_content = use_state::<Option<CursorPoint>>(|| None);
        let mut drag_origin = use_state::<Option<CursorPoint>>(|| None);
        let (scrolled_x, scrolled_y) = scroll_controller.into();
        let layout = &self.layout.layout;
        let direction = layout.direction;
        let drag_scrolling = self.drag_scrolling;

        let viewport_width = size.read().area.width();
        let viewport_height = size.read().area.height();

        let (inner_width, inner_height) = match direction {
            Direction::Vertical => (
                size.read().inner_sizes.width,
                self.item_size
                    .total_size(viewport_height, scrolled_y as f32, self.length),
            ),
            Direction::Horizontal => (
                self.item_size
                    .total_size(viewport_width, scrolled_x as f32, self.length),
                size.read().inner_sizes.height,
            ),
        };

        scroll_controller.use_apply(inner_width, inner_height);

        let corrected_scrolled_x =
            get_corrected_scroll_position(inner_width, size.read().area.width(), scrolled_x as f32);

        let corrected_scrolled_y = get_corrected_scroll_position(
            inner_height,
            size.read().area.height(),
            scrolled_y as f32,
        );
        let horizontal_scrollbar_is_visible = !timeout.elapsed()
            && is_scrollbar_visible(self.show_scrollbar, inner_width, size.read().area.width());
        let vertical_scrollbar_is_visible = !timeout.elapsed()
            && is_scrollbar_visible(self.show_scrollbar, inner_height, size.read().area.height());

        let (scrollbar_x, scrollbar_width) =
            get_scrollbar_pos_and_size(inner_width, size.read().area.width(), corrected_scrolled_x);
        let (scrollbar_y, scrollbar_height) = get_scrollbar_pos_and_size(
            inner_height,
            size.read().area.height(),
            corrected_scrolled_y,
        );

        let (container_width, content_width) = get_container_sizes(self.layout.width.clone());
        let (container_height, content_height) = get_container_sizes(self.layout.height.clone());

        let scroll_with_arrows = self.scroll_with_arrows;
        let invert_scroll_wheel = self.invert_scroll_wheel;

        let on_capture_global_pointer_press = move |e: Event<PointerEventData>| {
            if clicking_scrollbar.read().is_some() {
                e.prevent_default();
                clicking_scrollbar.set(None);
            }

            if drag_scrolling && (dragging_content().is_some() || drag_origin().is_some()) {
                dragging_content.set(None);
                drag_origin.set(None);
            }
        };

        let on_wheel = move |e: Event<WheelEventData>| {
            // Only invert direction on deviced-sourced wheel events
            let invert_direction = e.source == WheelSource::Device
                && (*pressing_shift.read() || invert_scroll_wheel)
                && (!*pressing_shift.read() || !invert_scroll_wheel);

            let (x_movement, y_movement) = if invert_direction {
                (e.delta_y as f32, e.delta_x as f32)
            } else {
                (e.delta_x as f32, e.delta_y as f32)
            };

            // Vertical scroll
            let scroll_position_y = get_scroll_position_from_wheel(
                y_movement,
                inner_height,
                size.read().area.height(),
                corrected_scrolled_y,
            );
            scroll_controller.scroll_to_y(scroll_position_y).then(|| {
                e.stop_propagation();
            });

            // Horizontal scroll
            let scroll_position_x = get_scroll_position_from_wheel(
                x_movement,
                inner_width,
                size.read().area.width(),
                corrected_scrolled_x,
            );
            scroll_controller.scroll_to_x(scroll_position_x).then(|| {
                e.stop_propagation();
            });
            timeout.reset();
        };

        let on_mouse_move = move |_| {
            timeout.reset();
        };

        let on_capture_global_pointer_move = move |e: Event<PointerEventData>| {
            if drag_scrolling {
                if let Some(prev) = dragging_content() {
                    let coords = e.global_location();
                    let delta = prev - coords;

                    scroll_controller.scroll_to_y((corrected_scrolled_y - delta.y as f32) as i32);
                    scroll_controller.scroll_to_x((corrected_scrolled_x - delta.x as f32) as i32);

                    dragging_content.set(Some(coords));
                    e.prevent_default();
                    timeout.reset();
                    a11y_id.request_focus();
                    return;
                } else if let Some(origin) = drag_origin() {
                    let coords = e.global_location();
                    let distance = (origin - coords).abs();

                    // Small threshold so taps can reach children (e.g. hover on buttons)
                    // without being immediately consumed by drag scrolling.
                    const DRAG_THRESHOLD: f64 = 2.0;

                    if distance.x > DRAG_THRESHOLD || distance.y > DRAG_THRESHOLD {
                        let delta = origin - coords;

                        scroll_controller
                            .scroll_to_y((corrected_scrolled_y - delta.y as f32) as i32);
                        scroll_controller
                            .scroll_to_x((corrected_scrolled_x - delta.x as f32) as i32);

                        dragging_content.set(Some(coords));
                        e.prevent_default();
                        timeout.reset();
                        a11y_id.request_focus();
                    }
                    return;
                }
            }

            let clicking_scrollbar = clicking_scrollbar.peek();

            if let Some((Axis::Y, y)) = *clicking_scrollbar {
                let coordinates = e.element_location();
                let cursor_y = coordinates.y - y - size.read().area.min_y() as f64;

                let scroll_position = get_scroll_position_from_cursor(
                    cursor_y as f32,
                    inner_height,
                    size.read().area.height(),
                );

                scroll_controller.scroll_to_y(scroll_position);
            } else if let Some((Axis::X, x)) = *clicking_scrollbar {
                let coordinates = e.element_location();
                let cursor_x = coordinates.x - x - size.read().area.min_x() as f64;

                let scroll_position = get_scroll_position_from_cursor(
                    cursor_x as f32,
                    inner_width,
                    size.read().area.width(),
                );

                scroll_controller.scroll_to_x(scroll_position);
            }

            if clicking_scrollbar.is_some() {
                e.prevent_default();
                timeout.reset();
                a11y_id.request_focus();
            }
        };

        let on_key_down = move |e: Event<KeyboardEventData>| {
            if !scroll_with_arrows
                && (e.key == Key::Named(NamedKey::ArrowUp)
                    || e.key == Key::Named(NamedKey::ArrowRight)
                    || e.key == Key::Named(NamedKey::ArrowDown)
                    || e.key == Key::Named(NamedKey::ArrowLeft))
            {
                return;
            }
            let x = corrected_scrolled_x;
            let y = corrected_scrolled_y;
            let inner_height = inner_height;
            let inner_width = inner_width;
            let viewport_height = size.read().area.height();
            let viewport_width = size.read().area.width();
            if let Some((x, y)) = handle_key_event(
                &e.key,
                (x, y),
                inner_height,
                inner_width,
                viewport_height,
                viewport_width,
                direction,
            ) {
                scroll_controller.scroll_to_x(x as i32);
                scroll_controller.scroll_to_y(y as i32);
                e.stop_propagation();
                timeout.reset();
            }
        };

        let on_global_key_down = move |e: Event<KeyboardEventData>| {
            let data = e;
            if data.key == Key::Named(NamedKey::Shift) {
                pressing_shift.set(true);
            }
        };

        let on_global_key_up = move |e: Event<KeyboardEventData>| {
            let data = e;
            if data.key == Key::Named(NamedKey::Shift) {
                pressing_shift.set(false);
            }
        };

        let (viewport_size, scroll_position) = if direction == Direction::vertical() {
            (viewport_height, corrected_scrolled_y)
        } else {
            (viewport_width, corrected_scrolled_x)
        };

        let (render_range, item_offset) =
            self.item_size
                .visible_range(viewport_size, scroll_position, self.length);

        let children = render_range
            .map(|i| {
                let item = VirtualItem {
                    index: i,
                    size: self.item_size.at(i),
                };
                (self.builder)(item, &self.builder_data)
            })
            .collect::<Vec<Element>>();

        let (offset_x, offset_y) = match direction {
            Direction::Vertical => (corrected_scrolled_x, item_offset),
            Direction::Horizontal => (item_offset, corrected_scrolled_y),
        };

        let on_pointer_down = move |e: Event<PointerEventData>| {
            if drag_scrolling && matches!(e.data(), PointerEventData::Touch(_)) {
                drag_origin.set(Some(e.global_location()));
            }
        };

        rect()
            .width(layout.width.clone())
            .height(layout.height.clone())
            .min_width(layout.minimum_width.clone())
            .min_height(layout.minimum_height.clone())
            .max_width(layout.maximum_width.clone())
            .max_height(layout.maximum_height.clone())
            .a11y_id(a11y_id)
            .a11y_focusable(false)
            .a11y_role(AccessibilityRole::ScrollView)
            .a11y_builder(move |node| {
                node.set_scroll_x(corrected_scrolled_x as f64);
                node.set_scroll_y(corrected_scrolled_y as f64)
            })
            .scrollable(true)
            .on_wheel(on_wheel)
            .on_capture_global_pointer_press(on_capture_global_pointer_press)
            .on_mouse_move(on_mouse_move)
            .on_capture_global_pointer_move(on_capture_global_pointer_move)
            .on_key_down(on_key_down)
            .on_global_key_up(on_global_key_up)
            .on_global_key_down(on_global_key_down)
            .on_pointer_down(on_pointer_down)
            .child(
                rect()
                    .width(container_width)
                    .height(container_height)
                    .horizontal()
                    .child(
                        rect()
                            .direction(direction)
                            .width(content_width)
                            .height(content_height)
                            .offset_x(offset_x)
                            .offset_y(offset_y)
                            .overflow(Overflow::Clip)
                            .on_sized(move |e: Event<SizedEventData>| {
                                size.set_if_modified(e.clone())
                            })
                            .children(children),
                    )
                    .maybe_child(vertical_scrollbar_is_visible.then_some({
                        rect().child(ScrollBar {
                            theme: None,
                            clicking_scrollbar,
                            axis: Axis::Y,
                            offset: scrollbar_y,
                            size: Size::px(size.read().area.height()),
                            thumb: ScrollThumb {
                                theme: None,
                                clicking_scrollbar,
                                axis: Axis::Y,
                                size: scrollbar_height,
                            },
                        })
                    })),
            )
            .maybe_child(horizontal_scrollbar_is_visible.then_some({
                rect().child(ScrollBar {
                    theme: None,
                    clicking_scrollbar,
                    axis: Axis::X,
                    offset: scrollbar_x,
                    size: Size::px(size.read().area.width()),
                    thumb: ScrollThumb {
                        theme: None,
                        clicking_scrollbar,
                        axis: Axis::X,
                        size: scrollbar_width,
                    },
                })
            }))
    }

    fn render_key(&self) -> DiffKey {
        self.key.clone().or(self.default_key())
    }
}