fret_ui_kit/declarative/

scroll.rs

use fret_core::{Color, Px};
use fret_ui::element::{
    AnyElement, ContainerProps, InsetStyle, LayoutStyle, Length, Overflow, PositionStyle,
    ScrollAxis, ScrollProps, ScrollbarAxis, ScrollbarProps, ScrollbarStyle, SizeStyle, StackProps,
};
use fret_ui::scroll::ScrollHandle;
use fret_ui::{ElementContext, Theme, UiHost};

use crate::IntoUiElement;
use crate::LayoutRefinement;
use crate::collect_children;
use crate::declarative::style;

/// Component-layer scroll helper (typed, declarative).
///
/// Fret treats scrolling as an explicit element (not a boolean overflow flag). This wrapper exists
/// to match gpui/tailwind ergonomics while keeping the runtime contract explicit.
#[track_caller]
pub fn overflow_scroll<H: UiHost, I, T>(
    cx: &mut ElementContext<'_, H>,
    layout: LayoutRefinement,
    show_scrollbar: bool,
    f: impl FnOnce(&mut ElementContext<'_, H>) -> I,
) -> AnyElement
where
    I: IntoIterator<Item = T>,
    T: IntoUiElement<H>,
{
    let (layout, scrollbar_w, thumb, thumb_hover) = {
        let theme = Theme::global(&*cx.app);
        let layout = style::layout_style(theme, layout);

        let scrollbar_w = theme.metric_token("metric.scrollbar.width");

        let thumb = theme.color_token("scrollbar.thumb.background");
        let thumb_hover = theme.color_token("scrollbar.thumb.hover.background");

        (layout, scrollbar_w, thumb, thumb_hover)
    };

    cx.stack_props(StackProps { layout }, move |cx| {
        let handle = cx.slot_state(ScrollHandle::default, |h| h.clone());
        let mut scroll_layout = LayoutStyle::default();
        scroll_layout.size.width = Length::Fill;
        scroll_layout.size.height = Length::Fill;
        scroll_layout.overflow = Overflow::Clip;

        let scroll = cx.scroll(
            ScrollProps {
                layout: scroll_layout,
                scroll_handle: Some(handle.clone()),
                ..Default::default()
            },
            move |cx| {
                let items = f(cx);
                collect_children(cx, items)
            },
        );

        let scroll_id = scroll.id;
        let mut children = vec![scroll];
        if show_scrollbar {
            let scrollbar_layout = LayoutStyle {
                position: PositionStyle::Absolute,
                inset: InsetStyle {
                    top: Some(Px(0.0)).into(),
                    right: Some(Px(0.0)).into(),
                    bottom: Some(Px(0.0)).into(),
                    left: None.into(),
                },
                size: SizeStyle {
                    width: Length::Px(scrollbar_w),
                    ..Default::default()
                },
                ..Default::default()
            };

            children.push(cx.scrollbar(ScrollbarProps {
                layout: scrollbar_layout,
                axis: ScrollbarAxis::Vertical,
                scroll_target: Some(scroll_id),
                scroll_handle: handle,
                style: ScrollbarStyle {
                    thumb,
                    thumb_hover,
                    ..Default::default()
                },
            }));
        }

        children
    })
}

pub fn overflow_scroll_with_handle<H: UiHost, I, T>(
    cx: &mut ElementContext<'_, H>,
    layout: LayoutRefinement,
    show_scrollbar: bool,
    handle: ScrollHandle,
    f: impl FnOnce(&mut ElementContext<'_, H>) -> I,
) -> AnyElement
where
    I: IntoIterator<Item = T>,
    T: IntoUiElement<H>,
{
    let (layout, scrollbar_w, thumb, thumb_hover) = {
        let theme = Theme::global(&*cx.app);
        let layout = style::layout_style(theme, layout);

        let scrollbar_w = theme.metric_token("metric.scrollbar.width");

        let thumb = theme.color_token("scrollbar.thumb.background");
        let thumb_hover = theme.color_token("scrollbar.thumb.hover.background");

        (layout, scrollbar_w, thumb, thumb_hover)
    };

    cx.stack_props(StackProps { layout }, move |cx| {
        let mut scroll_layout = LayoutStyle::default();
        scroll_layout.size.width = Length::Fill;
        scroll_layout.size.height = Length::Fill;
        scroll_layout.overflow = Overflow::Clip;

        let scroll = cx.scroll(
            ScrollProps {
                layout: scroll_layout,
                scroll_handle: Some(handle.clone()),
                ..Default::default()
            },
            move |cx| {
                let items = f(cx);
                collect_children(cx, items)
            },
        );

        let scroll_id = scroll.id;
        let mut children = vec![scroll];
        if show_scrollbar {
            let scrollbar_layout = LayoutStyle {
                position: PositionStyle::Absolute,
                inset: InsetStyle {
                    top: Some(Px(0.0)).into(),
                    right: Some(Px(0.0)).into(),
                    bottom: Some(Px(0.0)).into(),
                    left: None.into(),
                },
                size: SizeStyle {
                    width: Length::Px(scrollbar_w),
                    ..Default::default()
                },
                ..Default::default()
            };

            children.push(cx.scrollbar(ScrollbarProps {
                layout: scrollbar_layout,
                axis: ScrollbarAxis::Vertical,
                scroll_target: Some(scroll_id),
                scroll_handle: handle,
                style: ScrollbarStyle {
                    thumb,
                    thumb_hover,
                    ..Default::default()
                },
            }));
        }

        children
    })
}

pub fn overflow_scroll_with_handle_xy<H: UiHost, I, T>(
    cx: &mut ElementContext<'_, H>,
    layout: LayoutRefinement,
    show_scrollbar_x: bool,
    show_scrollbar_y: bool,
    handle: ScrollHandle,
    f: impl FnOnce(&mut ElementContext<'_, H>) -> I,
) -> AnyElement
where
    I: IntoIterator<Item = T>,
    T: IntoUiElement<H>,
{
    let (layout, scrollbar_w, thumb, thumb_hover, corner_bg) = {
        let theme = Theme::global(&*cx.app);
        let layout = style::layout_style(theme, layout);

        let scrollbar_w = theme.metric_token("metric.scrollbar.width");

        let thumb = theme.color_token("scrollbar.thumb.background");
        let thumb_hover = theme.color_token("scrollbar.thumb.hover.background");

        let corner_bg = theme
            .color_by_key("scrollbar.corner.background")
            .or_else(|| theme.color_by_key("scrollbar.track.background"))
            .unwrap_or(Color::TRANSPARENT);

        (layout, scrollbar_w, thumb, thumb_hover, corner_bg)
    };

    cx.stack_props(StackProps { layout }, move |cx| {
        let mut scroll_layout = LayoutStyle::default();
        scroll_layout.size.width = Length::Fill;
        scroll_layout.size.height = Length::Fill;
        scroll_layout.overflow = Overflow::Clip;

        let scroll = cx.scroll(
            ScrollProps {
                layout: scroll_layout,
                axis: ScrollAxis::Both,
                scroll_handle: Some(handle.clone()),
                ..Default::default()
            },
            move |cx| {
                let items = f(cx);
                collect_children(cx, items)
            },
        );

        let scroll_id = scroll.id;
        let mut children = vec![scroll];

        if show_scrollbar_y {
            let scrollbar_layout = LayoutStyle {
                position: PositionStyle::Absolute,
                inset: InsetStyle {
                    top: Some(Px(0.0)).into(),
                    right: Some(Px(0.0)).into(),
                    bottom: Some(if show_scrollbar_x {
                        scrollbar_w
                    } else {
                        Px(0.0)
                    })
                    .into(),
                    left: None.into(),
                },
                size: SizeStyle {
                    width: Length::Px(scrollbar_w),
                    ..Default::default()
                },
                ..Default::default()
            };

            children.push(cx.scrollbar(ScrollbarProps {
                layout: scrollbar_layout,
                axis: ScrollbarAxis::Vertical,
                scroll_target: Some(scroll_id),
                scroll_handle: handle.clone(),
                style: ScrollbarStyle {
                    thumb,
                    thumb_hover,
                    ..Default::default()
                },
            }));
        }

        if show_scrollbar_x {
            let scrollbar_layout = LayoutStyle {
                position: PositionStyle::Absolute,
                inset: InsetStyle {
                    top: None.into(),
                    right: Some(if show_scrollbar_y {
                        scrollbar_w
                    } else {
                        Px(0.0)
                    })
                    .into(),
                    bottom: Some(Px(0.0)).into(),
                    left: Some(Px(0.0)).into(),
                },
                size: SizeStyle {
                    height: Length::Px(scrollbar_w),
                    ..Default::default()
                },
                ..Default::default()
            };

            children.push(cx.scrollbar(ScrollbarProps {
                layout: scrollbar_layout,
                axis: ScrollbarAxis::Horizontal,
                scroll_target: Some(scroll_id),
                scroll_handle: handle.clone(),
                style: ScrollbarStyle {
                    thumb,
                    thumb_hover,
                    ..Default::default()
                },
            }));
        }

        if show_scrollbar_x && show_scrollbar_y {
            let corner_layout = LayoutStyle {
                position: PositionStyle::Absolute,
                inset: InsetStyle {
                    right: Some(Px(0.0)).into(),
                    bottom: Some(Px(0.0)).into(),
                    ..Default::default()
                },
                size: SizeStyle {
                    width: Length::Px(scrollbar_w),
                    height: Length::Px(scrollbar_w),
                    ..Default::default()
                },
                ..Default::default()
            };

            children.push(cx.container(
                ContainerProps {
                    layout: corner_layout,
                    background: Some(corner_bg),
                    ..Default::default()
                },
                |_cx| vec![],
            ));
        }

        children
    })
}

#[track_caller]
pub fn overflow_scrollbar<H: UiHost, I, T>(
    cx: &mut ElementContext<'_, H>,
    layout: LayoutRefinement,
    f: impl FnOnce(&mut ElementContext<'_, H>) -> I,
) -> AnyElement
where
    I: IntoIterator<Item = T>,
    T: IntoUiElement<H>,
{
    overflow_scroll(cx, layout, true, f)
}

/// Like `overflow_scroll`, but enforces a single content root.
///
/// Note: `Scroll` does not lay out multiple children; if you pass a `Vec` of siblings they will
/// overlap. Prefer this helper (or `*_vstack`) to make the intended structure explicit.
#[track_caller]
pub fn overflow_scroll_content<H: UiHost, T>(
    cx: &mut ElementContext<'_, H>,
    layout: LayoutRefinement,
    show_scrollbar: bool,
    content: impl FnOnce(&mut ElementContext<'_, H>) -> T,
) -> AnyElement
where
    T: IntoUiElement<H>,
{
    overflow_scroll(cx, layout, show_scrollbar, |cx| {
        std::iter::once(content(cx))
    })
}

/// Horizontal scrolling with a single content root.
#[track_caller]
pub fn overflow_scroll_x_content<H: UiHost, T>(
    cx: &mut ElementContext<'_, H>,
    layout: LayoutRefinement,
    show_scrollbar_x: bool,
    content: impl FnOnce(&mut ElementContext<'_, H>) -> T,
) -> AnyElement
where
    T: IntoUiElement<H>,
{
    let (layout, scrollbar_w, thumb, thumb_hover) = {
        let theme = Theme::global(&*cx.app);
        let layout = style::layout_style(theme, layout);

        let scrollbar_w = theme.metric_token("metric.scrollbar.width");

        let thumb = theme.color_token("scrollbar.thumb.background");
        let thumb_hover = theme.color_token("scrollbar.thumb.hover.background");

        (layout, scrollbar_w, thumb, thumb_hover)
    };

    cx.stack_props(StackProps { layout }, move |cx| {
        let handle = cx.slot_state(ScrollHandle::default, |h| h.clone());
        let mut scroll_layout = LayoutStyle::default();
        scroll_layout.size.width = Length::Fill;
        // For X-only scrolling, the common expectation is "height = content height" (e.g. code
        // blocks) while width fills the viewport.
        scroll_layout.size.height = Length::Auto;
        scroll_layout.overflow = Overflow::Clip;

        let scroll = cx.scroll(
            ScrollProps {
                layout: scroll_layout,
                axis: ScrollAxis::X,
                scroll_handle: Some(handle.clone()),
                ..Default::default()
            },
            move |cx| {
                let child = content(cx);
                vec![IntoUiElement::into_element(child, cx)]
            },
        );

        let scroll_id = scroll.id;
        let mut children = vec![scroll];

        if show_scrollbar_x {
            let scrollbar_layout = LayoutStyle {
                position: PositionStyle::Absolute,
                inset: InsetStyle {
                    top: None.into(),
                    right: Some(Px(0.0)).into(),
                    bottom: Some(Px(0.0)).into(),
                    left: Some(Px(0.0)).into(),
                },
                size: SizeStyle {
                    height: Length::Px(scrollbar_w),
                    ..Default::default()
                },
                ..Default::default()
            };

            children.push(cx.scrollbar(ScrollbarProps {
                layout: scrollbar_layout,
                axis: ScrollbarAxis::Horizontal,
                scroll_target: Some(scroll_id),
                scroll_handle: handle,
                style: ScrollbarStyle {
                    thumb,
                    thumb_hover,
                    ..Default::default()
                },
            }));
        }

        children
    })
}

// Horizontal scrolling with a `vstack` content root.
// Note: older versions of this module exposed `*_vstack` helpers that depended on the legacy stack
// helpers. Those were removed when the repo converged on
// `fret-ui-kit::ui::*` builders as the teaching surface. Prefer `overflow_scroll_content(...)`
// with an explicit content root (e.g. `ui::v_flex(|cx| ...)`).

/// Like `overflow_scroll_with_handle_xy`, but enforces a single content root.
pub fn overflow_scroll_with_handle_xy_content<H: UiHost, T>(
    cx: &mut ElementContext<'_, H>,
    layout: LayoutRefinement,
    show_scrollbar_x: bool,
    show_scrollbar_y: bool,
    handle: ScrollHandle,
    content: impl FnOnce(&mut ElementContext<'_, H>) -> T,
) -> AnyElement
where
    T: IntoUiElement<H>,
{
    overflow_scroll_with_handle_xy(
        cx,
        layout,
        show_scrollbar_x,
        show_scrollbar_y,
        handle,
        |cx| std::iter::once(content(cx)),
    )
}