repose_core/

scroll.rs

use std::cell::{Cell, RefCell};
use std::rc::Rc;

use web_time::Instant;

use crate::nested_scroll::{NestedScrollConnection, NestedScrollSource};
use crate::{ControlVisualSet, Dp, Signal, Vec2, request_frame, signal};

/// Axis (or axes) a scroll modifier operates on.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum ScrollAxis {
    Vertical,
    Horizontal,
    Both,
}

// Holds all callbacks that the layout engine needs from a scroll state.
// Stored in `Modifier.scroll`.

#[derive(Clone, Debug, PartialEq)]
pub struct ScrollbarStyle {
    pub thickness: Dp,
    pub track_inset: Dp,
    pub min_thumb_length: Dp,
    pub fixed_thumb_length: Option<Dp>,
    pub radius: Option<Dp>,
    pub track_visuals: ControlVisualSet,
    pub thumb_visuals: ControlVisualSet,
}

impl Default for ScrollbarStyle {
    fn default() -> Self {
        Self {
            thickness: Dp(4.0),
            track_inset: Dp(2.0),
            min_thumb_length: Dp(24.0),
            fixed_thumb_length: None,
            radius: None,
            track_visuals: ControlVisualSet::default(),
            thumb_visuals: ControlVisualSet::default(),
        }
    }
}

impl ScrollbarStyle {
    pub fn with_thickness(mut self, thickness: Dp) -> Self {
        self.thickness = thickness;
        self
    }

    pub fn with_track_inset(mut self, track_inset: Dp) -> Self {
        self.track_inset = track_inset;
        self
    }

    pub fn with_min_thumb_length(mut self, min_thumb_length: Dp) -> Self {
        self.min_thumb_length = min_thumb_length;
        self
    }

    pub fn with_fixed_thumb_length(mut self, length: Option<Dp>) -> Self {
        self.fixed_thumb_length = length;
        self
    }

    pub fn with_radius(mut self, radius: Option<Dp>) -> Self {
        self.radius = radius;
        self
    }

    pub fn with_track_visuals(mut self, visuals: ControlVisualSet) -> Self {
        self.track_visuals = visuals;
        self
    }

    pub fn with_thumb_visuals(mut self, visuals: ControlVisualSet) -> Self {
        self.thumb_visuals = visuals;
        self
    }
}

/// Callbacks for a single-axis (vertical or horizontal) scroll container.
#[derive(Clone, Default)]
pub struct ScrollAxisBinding {
    pub on_scroll: Option<Rc<dyn Fn(Vec2) -> Vec2>>,
    /// Set viewport size along the scroll axis (height for V, width for H).
    pub set_viewport_main: Option<Rc<dyn Fn(f32)>>,
    /// Set content size along the scroll axis.
    pub set_content_main: Option<Rc<dyn Fn(f32)>>,
    pub get_offset_main: Option<Rc<dyn Fn() -> f32>>,
    pub set_offset_main: Option<Rc<dyn Fn(f32)>>,
    pub show_scrollbar: bool,
    pub tick: Option<Rc<dyn Fn()>>,
    pub set_nested_scroll_parent: Option<Rc<dyn Fn(NestedScrollConnection)>>,
}

impl std::fmt::Debug for ScrollAxisBinding {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("ScrollAxisBinding")
            .field("has_on_scroll", &self.on_scroll.is_some())
            .field("set_viewport_main", &self.set_viewport_main.is_some())
            .field("set_content_main", &self.set_content_main.is_some())
            .field("get_offset_main", &self.get_offset_main.is_some())
            .field("set_offset_main", &self.set_offset_main.is_some())
            .field("show_scrollbar", &self.show_scrollbar)
            .field("tick", &self.tick.is_some())
            .field(
                "set_nested_scroll_parent",
                &self.set_nested_scroll_parent.is_some(),
            )
            .finish()
    }
}

/// Callbacks for a 2D (both-axis) scroll container.
#[derive(Clone, Default)]
pub struct ScrollBothBinding {
    pub on_scroll: Option<Rc<dyn Fn(Vec2) -> Vec2>>,
    pub set_viewport_width: Option<Rc<dyn Fn(f32)>>,
    pub set_viewport_height: Option<Rc<dyn Fn(f32)>>,
    pub set_content_width: Option<Rc<dyn Fn(f32)>>,
    pub set_content_height: Option<Rc<dyn Fn(f32)>>,
    pub get_offset_xy: Option<Rc<dyn Fn() -> (f32, f32)>>,
    pub set_offset_xy: Option<Rc<dyn Fn(f32, f32)>>,
    pub show_scrollbar: bool,
    pub tick: Option<Rc<dyn Fn()>>,
    pub set_nested_scroll_parent: Option<Rc<dyn Fn(NestedScrollConnection)>>,
}

impl std::fmt::Debug for ScrollBothBinding {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("ScrollBothBinding")
            .field("has_on_scroll", &self.on_scroll.is_some())
            .field("set_viewport_width", &self.set_viewport_width.is_some())
            .field("set_viewport_height", &self.set_viewport_height.is_some())
            .field("set_content_width", &self.set_content_width.is_some())
            .field("set_content_height", &self.set_content_height.is_some())
            .field("get_offset_xy", &self.get_offset_xy.is_some())
            .field("set_offset_xy", &self.set_offset_xy.is_some())
            .field("show_scrollbar", &self.show_scrollbar)
            .field("tick", &self.tick.is_some())
            .field(
                "set_nested_scroll_parent",
                &self.set_nested_scroll_parent.is_some(),
            )
            .finish()
    }
}

#[derive(Clone, Debug)]
pub enum ScrollBinding {
    Vertical(ScrollAxisBinding),
    Horizontal(ScrollAxisBinding),
    Both(ScrollBothBinding),
}

impl ScrollBinding {
    pub fn axis(&self) -> ScrollAxis {
        match self {
            ScrollBinding::Vertical(_) => ScrollAxis::Vertical,
            ScrollBinding::Horizontal(_) => ScrollAxis::Horizontal,
            ScrollBinding::Both(_) => ScrollAxis::Both,
        }
    }
}

const OVERSHOOT_DECAY_PER_60HZ: f32 = 0.78;

/// Per-60Hz-frame velocity decay at low speed. Higher stops the fling sooner.
pub const SCROLL_DECAY_PER_60HZ: f32 = 0.85;
/// Fling is abandoned once speed falls below this (px/s).
pub const SCROLL_STOP_VELOCITY: f32 = 15.0;
/// A gesture must exceed this speed (px/s) to leave a fling behind.
pub const SCROLL_FLING_ACTIVATE_VELOCITY: f32 = 50.0;
/// Rubber-band asymptote: overscroll never stretches past this many px.
pub const SCROLL_OVERSROLL_BAND_MAX: f32 = 150.0;

/// Clamp a scroll offset into `[0, max]` with NaN/inf sanitization.
/// `f32::clamp` propagates NaN, so one bad write would poison the offset
/// signal permanently (every later frame reads NaN). Central helper so all
/// `set_offset`/`scroll_immediate` paths stay sanitized long-term.
fn clamp_offset(off: f32, max: f32) -> f32 {
    let max = if max.is_finite() { max.max(0.0) } else { 0.0 };
    if off.is_finite() {
        off.clamp(0.0, max)
    } else {
        0.0
    }
}

/// Asymptotic rubber band: never reaches `max`, so pulling harder always
/// moves a little more without ever running away.
pub fn rubber_band(amount: f32, max: f32) -> f32 {
    let abs_val = amount.abs();
    if abs_val <= 0.0 {
        return 0.0;
    }
    (1.0 - 1.0 / (1.0 + abs_val / max)) * max * amount.signum()
}

/// Fold `leftover` into one axis's rubber band after the nested parent chain
/// has declined it. Returns whatever is still unconsumed.
pub fn os_scroll_axis(
    off: &Signal<f32>,
    os: &Signal<f32>,
    overscroll_enabled: bool,
    max_off: f32,
    before: f32,
    leftover: f32,
    physics: &RefCell<ScrollPhysics>,
) -> f32 {
    if !overscroll_enabled || leftover.abs() < 0.001 {
        return leftover;
    }
    let os_val = os.get();
    // Recovering from an active rubber band: absorb the reverse delta first.
    if os_val.abs() > 0.5 && os_val.signum() * leftover < 0.0 {
        let reduction = leftover.abs().min(os_val.abs());
        os.set(os_val - os_val.signum() * reduction);
        let remainder = leftover - leftover.signum() * reduction;
        if remainder.abs() > 0.5 {
            let new_off = clamp_offset(before + remainder, max_off);
            off.set(new_off);
            let consumed = new_off - before;
            physics.borrow_mut().record_nested_input(consumed);
            return remainder - consumed;
        }
        return 0.0;
    }

    // At the edge, pushing further: stretch the rubber band.
    let at_edge = (before <= 0.0 && leftover < 0.0) || (before >= max_off && leftover > 0.0);
    if max_off > 5.0 && at_edge && leftover.abs() > 0.5 {
        os.set(os_val + rubber_band(leftover, SCROLL_OVERSROLL_BAND_MAX));
        physics.borrow_mut().record_nested_input(0.0);
        return 0.0;
    }
    leftover
}

/// Decay one axis's rubber band back to rest. Returns true while it is active.
pub fn tick_os_axis(os: &Signal<f32>, enabled: bool, dt: f32) -> bool {
    if !enabled {
        return false;
    }
    let v = os.get();
    if v.abs() > 0.5 {
        let decayed = v * OVERSHOOT_DECAY_PER_60HZ.powf(dt * 60.0);
        if decayed.abs() < 0.5 {
            os.set(0.0);
        } else {
            os.set(decayed);
        }
        request_frame();
        true
    } else {
        false
    }
}

/// Handles velocity estimation from input deltas, frame-rate-independent
/// exponential decay, edge snapping, and animation state tracking.
#[derive(Clone)]
pub struct ScrollPhysics {
    pub(crate) vel: f32,
    last_t: Instant,
    last_input_t: Instant,
    pub(crate) animating: bool,
    /// Set when a delta arrived since the last integration.
    input_pending: bool,
    last_dt: f32,
    decay_per_60hz: f32,
    stop_velocity: f32,
    input_activate_velocity: f32,
}

impl Default for ScrollPhysics {
    fn default() -> Self {
        Self::new()
    }
}

impl ScrollPhysics {
    pub fn new() -> Self {
        Self::with_tuning(
            SCROLL_DECAY_PER_60HZ,
            SCROLL_STOP_VELOCITY,
            SCROLL_FLING_ACTIVATE_VELOCITY,
        )
    }

    pub fn with_tuning(
        decay_per_60hz: f32,
        stop_velocity: f32,
        input_activate_velocity: f32,
    ) -> Self {
        let now = Instant::now();
        Self {
            vel: 0.0,
            last_t: now,
            last_input_t: now,
            animating: false,
            input_pending: false,
            last_dt: 1.0 / 60.0,
            decay_per_60hz,
            stop_velocity,
            input_activate_velocity,
        }
    }

    /// Feed a delta that arrived from real user input.
    ///
    /// A first sample adopts its velocity outright, and a delta opposing an
    /// in-flight fling takes over from it. Both mirror Compose, where a new
    /// `scroll(MutatePriority.UserInput)` cancels the fling coroutine holding
    /// the `MutatorMutex` so the drag wins. Smoothing only applies between
    /// samples of one gesture: averaging up from zero on every frame would
    /// leave every flick at a fraction of its real speed.
    pub fn record_user_input(&mut self, consumed: f32) {
        let (instant_vel, fresh) = self.sample(consumed);
        if fresh || (self.animating && instant_vel * self.vel < 0.0) {
            self.vel = instant_vel;
        } else {
            const SMOOTHING: f32 = 0.35;
            self.vel = self.vel * (1.0 - SMOOTHING) + instant_vel * SMOOTHING;
        }
        self.finish_sample();
    }

    /// Feed a delta that arrived as leftover from a nested child. Never takes
    /// over an in-flight fling: Compose's `dispatchRawDelta` bypasses mutual
    /// exclusion precisely so a parent keeps coasting.
    pub fn record_nested_input(&mut self, consumed: f32) {
        let (instant_vel, _) = self.sample(consumed);
        const SMOOTHING: f32 = 0.35;
        self.vel = self.vel * (1.0 - SMOOTHING) + instant_vel * SMOOTHING;
        self.finish_sample();
    }

    fn sample(&mut self, consumed: f32) -> (f32, bool) {
        let now = Instant::now();
        let raw_dt = (now - self.last_input_t).as_secs_f32();
        let dt = raw_dt.clamp(1.0 / 240.0, 1.0 / 15.0);
        self.last_dt = dt;
        // A gap this long means a new gesture rather than another sample.
        let fresh = raw_dt > 0.05;
        self.last_input_t = now;
        if raw_dt > 0.1 {
            self.vel = 0.0;
        }
        (consumed / dt, fresh)
    }

    fn finish_sample(&mut self) {
        const MAX_VEL: f32 = 8000.0;
        self.vel = self.vel.clamp(-MAX_VEL, MAX_VEL);
        self.animating = self.vel.abs() > self.input_activate_velocity;
        self.input_pending = true;
    }

    fn dt(&mut self) -> f32 {
        let now = Instant::now();
        let dt = (now - self.last_t).as_secs_f32().min(0.1);
        self.last_t = now;
        dt
    }

    pub fn tick_integrate(&mut self, current: f32, min: f32, max: f32) -> Option<f32> {
        // Sample the clock first, unconditionally. Bailing out before this
        // would let `last_t` go stale for the whole duration of a drag and
        // then dump all of it into the first fling frame, which shows up as a
        // single large lurch the moment the finger lifts.
        let dt = self.dt();
        if self.input_pending {
            // A delta was applied since the last integration, so this frame's
            // motion is already accounted for. Compose feeds velocity from the
            // gesture layer and runs no integrator mid-drag; we infer velocity
            // from the same delta stream we also apply, so integrating here
            // would move the surface by roughly 2x.
            self.input_pending = false;
            return None;
        }
        if !self.animating {
            return None;
        }
        if dt <= 0.0 {
            return None;
        }
        let vel0 = self.vel;
        if vel0.abs() < self.stop_velocity {
            self.vel = 0.0;
            self.animating = false;
            return None;
        }
        let new = {
            let raw = current + vel0 * dt;
            let raw = if raw.is_finite() { raw } else { current };
            raw.clamp(min, max.max(min))
        };
        if (new - current).abs() < 0.01 && (current <= min || current >= max) {
            self.vel = 0.0;
            self.animating = false;
            return None;
        }
        let speed = self.vel.abs();
        let t = (speed / 4000.0).min(1.0);
        let effective_decay = (self.decay_per_60hz + t * 0.10).min(0.999);
        let decay = effective_decay.powf(dt * 60.0);
        self.vel = vel0 * decay;
        if self.vel.abs() < self.stop_velocity {
            self.vel = 0.0;
            self.animating = false;
            return None;
        }
        Some(new)
    }

    pub fn is_animating(&self) -> bool {
        self.animating
    }
}

/// Inertial scroll state (single axis Y).
#[derive(Clone)]
pub struct ScrollState {
    scroll_offset: Signal<f32>,
    viewport_height: Signal<f32>,
    content_height: Signal<f32>,
    physics: Rc<RefCell<ScrollPhysics>>,
    overscroll: Signal<f32>,
    overscroll_enabled: Cell<bool>,
    pub(crate) parent_connection: Rc<RefCell<Option<NestedScrollConnection>>>,
    show_scrollbar: Cell<bool>,
    prev_tick: Cell<Instant>,
}

impl Default for ScrollState {
    fn default() -> Self {
        Self::new()
    }
}

impl ScrollState {
    pub fn new() -> Self {
        Self {
            scroll_offset: signal(0.0),
            viewport_height: signal(0.0),
            content_height: signal(0.0),
            physics: Rc::new(RefCell::new(ScrollPhysics::new())),
            overscroll: signal(0.0),
            overscroll_enabled: Cell::new(true),
            parent_connection: Rc::new(RefCell::new(None)),
            show_scrollbar: Cell::new(true),
            prev_tick: Cell::new(Instant::now()),
        }
    }

    pub fn set_overscroll_enabled(&self, enabled: bool) {
        self.overscroll_enabled.set(enabled);
    }

    pub fn overscroll_offset(&self) -> f32 {
        self.overscroll.get()
    }

    pub fn set_nested_scroll_parent(&self, conn: NestedScrollConnection) {
        *self.parent_connection.borrow_mut() = Some(conn);
    }

    /// Use it to wire a child scrollable to a parent scroll container
    /// explicitly: `child_state.set_nested_scroll_parent(parent_state.connection())`.
    pub fn connection(&self) -> NestedScrollConnection {
        let this = Rc::new(self.clone());
        let pc = Rc::clone(&this.parent_connection);
        NestedScrollConnection::new().on_post_scroll(
            move |_consumed: Vec2, available: Vec2, _source: NestedScrollSource| -> Vec2 {
                if available.x.abs() < 0.001 && available.y.abs() < 0.001 {
                    return Vec2::ZERO;
                }
                let leftover_y = this.scroll_nested(available.y);
                let after = run_post_scroll(
                    &pc,
                    Vec2 {
                        x: available.x,
                        y: leftover_y,
                    },
                );
                Vec2 {
                    x: available.x - after.x,
                    y: available.y - after.y,
                }
            },
        )
    }

    pub fn set_show_scrollbar(&self, show: bool) {
        self.show_scrollbar.set(show);
    }

    pub fn set_viewport_height(&self, h: f32) {
        let h = h.max(0.0);
        if (self.viewport_height.get() - h).abs() > 0.5 {
            self.viewport_height.set(h);
            self.clamp_offset();
        }
    }

    pub fn set_content_height(&self, h: f32) {
        let h = h.max(0.0);
        if (self.content_height.get() - h).abs() > 0.5 {
            self.content_height.set(h);
            self.clamp_offset();
        }
    }

    pub fn set_overscroll(&self, val: f32) {
        self.overscroll.set(val);
    }

    pub fn set_offset(&self, off: f32) {
        let off = if off.is_finite() { off } else { 0.0 };
        let vh = self.viewport_height.get();
        let ch = self.content_height.get();
        let max_off = (ch - vh).max(0.0);
        self.scroll_offset.set(clamp_offset(off, max_off));
    }

    fn clamp_offset(&self) {
        let vh = self.viewport_height.get();
        let ch = self.content_height.get();
        let max_off = (ch - vh).max(0.0);
        self.scroll_offset.update(|o| {
            if *o > max_off {
                *o = max_off;
            }
            if *o < 0.0 {
                *o = 0.0;
            }
        });
    }

    pub fn get(&self) -> f32 {
        self.scroll_offset.get()
    }

    /// Apply a scroll delta from real user input. Pre-empts any in-flight
    /// fling, matching Compose where a new `scroll(UserInput)` cancels the
    /// fling coroutine holding the `MutatorMutex`.
    pub fn scroll_immediate(&self, dy: f32) -> f32 {
        self.apply_delta(dy, true)
    }

    /// Apply a delta that arrived as leftover from a nested child. This is
    /// Compose's `dispatchRawDelta`: it bypasses mutual exclusion, so it must
    /// not cancel this container's own fling.
    pub fn scroll_nested(&self, dy: f32) -> f32 {
        self.apply_delta(dy, false)
    }

    fn apply_delta(&self, dy: f32, user: bool) -> f32 {
        let dy = if dy.is_finite() { dy } else { 0.0 };
        let before = self.scroll_offset.get();
        let vh = self.viewport_height.get();
        let ch = self.content_height.get();
        let max_off = (ch - vh).max(0.0);

        let new_off = clamp_offset(before + dy, max_off);
        self.scroll_offset.set(new_off);
        let consumed = new_off - before;
        if user {
            self.physics.borrow_mut().record_user_input(consumed);
        } else {
            self.physics.borrow_mut().record_nested_input(consumed);
        }
        dy - consumed
    }

    /// Feed leftover (after the nested parent chain has had its chance via
    /// post-scroll) into the rubber-band overscroll. Returns the amount still
    /// unconsumed. Overscroll deliberately runs LAST so parents get first dibs.
    pub fn apply_overscroll(&self, leftover: f32) -> f32 {
        let vh = self.viewport_height.get();
        let ch = self.content_height.get();
        os_scroll_axis(
            &self.scroll_offset,
            &self.overscroll,
            self.overscroll_enabled.get(),
            (ch - vh).max(0.0),
            self.scroll_offset.get(),
            leftover,
            &self.physics,
        )
    }

    pub fn tick(&self) -> bool {
        let now = Instant::now();
        let dt = (now - self.prev_tick.get()).as_secs_f32().min(0.1);
        self.prev_tick.set(now);

        if tick_os_axis(&self.overscroll, self.overscroll_enabled.get(), dt) {
            return true;
        }

        let vh = self.viewport_height.get();
        let ch = self.content_height.get();
        let max_off = (ch - vh).max(0.0);

        let mut p = self.physics.borrow_mut();
        if let Some(new_off) = p.tick_integrate(self.scroll_offset.get(), 0.0, max_off) {
            drop(p);
            self.scroll_offset.set(new_off);
            request_frame();
            true
        } else {
            false
        }
    }

    pub fn show_scrollbar(&self) -> bool {
        self.show_scrollbar.get()
    }

    /// Build a `ScrollBinding::Vertical` from this state for use with `Modifier::vertical_scroll`.
    pub fn to_binding(&self) -> ScrollBinding {
        let this = Rc::new(self.clone());
        let pc = Rc::clone(&this.parent_connection);
        let c_on_scroll = {
            let state = Rc::clone(&pc);
            let this = Rc::clone(&this);
            Rc::new(move |d: Vec2| -> Vec2 {
                let d = run_pre_scroll(&state, d);
                // Clamp this scroller first; leftover goes to the nested parent
                // chain (post-scroll) BEFORE rubber-band overscroll.
                let leftover_y = this.scroll_immediate(d.y);
                let result = Vec2 {
                    x: d.x,
                    y: leftover_y,
                };
                let after_parent = run_post_scroll(&state, result);
                let final_y = this.apply_overscroll(after_parent.y);
                Vec2 {
                    x: after_parent.x,
                    y: final_y,
                }
            })
        } as Rc<dyn Fn(Vec2) -> Vec2>;
        let c_set_viewport = {
            let this = Rc::clone(&this);
            Rc::new(move |h: f32| this.set_viewport_height(h))
        };
        let c_set_content = {
            let this = Rc::clone(&this);
            Rc::new(move |h: f32| this.set_content_height(h))
        };
        let c_get = {
            let this = Rc::clone(&this);
            Rc::new(move || this.get() + this.overscroll_offset())
        };
        let c_set = {
            let this = Rc::clone(&this);
            Rc::new(move |off: f32| this.set_offset(off))
        };
        let c_tick = {
            let this = Rc::clone(&this);
            Rc::new(move || {
                this.tick();
            })
        };
        let c_set_nested = {
            let state = Rc::clone(&pc);
            Rc::new(move |conn| {
                *state.borrow_mut() = Some(conn);
            })
        };
        ScrollBinding::Vertical(ScrollAxisBinding {
            on_scroll: Some(c_on_scroll),
            set_viewport_main: Some(c_set_viewport),
            set_content_main: Some(c_set_content),
            get_offset_main: Some(c_get),
            set_offset_main: Some(c_set),
            show_scrollbar: self.show_scrollbar(),
            tick: Some(c_tick),
            set_nested_scroll_parent: Some(c_set_nested),
        })
    }
}

/// X-only state
#[derive(Clone)]
pub struct HorizontalScrollState {
    scroll_offset: Signal<f32>,
    viewport_width: Signal<f32>,
    content_width: Signal<f32>,
    physics: Rc<RefCell<ScrollPhysics>>,
    overscroll: Signal<f32>,
    overscroll_enabled: Cell<bool>,
    pub(crate) parent_connection: Rc<RefCell<Option<NestedScrollConnection>>>,
    show_scrollbar: Cell<bool>,
    prev_tick: Cell<Instant>,
}

impl Default for HorizontalScrollState {
    fn default() -> Self {
        Self::new()
    }
}

impl HorizontalScrollState {
    pub fn new() -> Self {
        Self {
            scroll_offset: signal(0.0),
            viewport_width: signal(0.0),
            content_width: signal(0.0),
            physics: Rc::new(RefCell::new(ScrollPhysics::new())),
            overscroll: signal(0.0),
            overscroll_enabled: Cell::new(true),
            parent_connection: Rc::new(RefCell::new(None)),
            show_scrollbar: Cell::new(true),
            prev_tick: Cell::new(Instant::now()),
        }
    }

    pub fn set_overscroll_enabled(&self, enabled: bool) {
        self.overscroll_enabled.set(enabled);
    }

    pub fn overscroll_offset(&self) -> f32 {
        self.overscroll.get()
    }

    pub fn set_nested_scroll_parent(&self, conn: NestedScrollConnection) {
        *self.parent_connection.borrow_mut() = Some(conn);
    }

    /// A `NestedScrollConnection` that consumes leftover scroll by scrolling
    /// THIS container, then chains anything still unabsorbed up to this
    /// container's own parent connection.
    pub fn connection(&self) -> NestedScrollConnection {
        let this = Rc::new(self.clone());
        let pc = Rc::clone(&this.parent_connection);
        NestedScrollConnection::new().on_post_scroll(
            move |_consumed: Vec2, available: Vec2, _source: NestedScrollSource| -> Vec2 {
                if available.x.abs() < 0.001 && available.y.abs() < 0.001 {
                    return Vec2::ZERO;
                }
                let leftover_x = this.scroll_nested(available.x);
                let after = run_post_scroll(
                    &pc,
                    Vec2 {
                        x: leftover_x,
                        y: available.y,
                    },
                );
                Vec2 {
                    x: available.x - after.x,
                    y: available.y - after.y,
                }
            },
        )
    }

    pub fn set_show_scrollbar(&self, show: bool) {
        self.show_scrollbar.set(show);
    }

    pub fn set_viewport_width(&self, w: f32) {
        let w = w.max(0.0);
        if (self.viewport_width.get() - w).abs() > 0.5 {
            self.viewport_width.set(w);
            self.clamp();
        }
    }

    pub fn set_content_width(&self, w: f32) {
        let w = w.max(0.0);
        if (self.content_width.get() - w).abs() > 0.5 {
            self.content_width.set(w);
            self.clamp();
        }
    }

    pub fn set_overscroll(&self, val: f32) {
        self.overscroll.set(val);
    }

    pub fn set_offset(&self, off: f32) {
        let max_off = (self.content_width.get() - self.viewport_width.get()).max(0.0);
        self.scroll_offset.set(clamp_offset(off, max_off));
    }

    fn clamp(&self) {
        let max_off = (self.content_width.get() - self.viewport_width.get()).max(0.0);
        self.scroll_offset.update(|o| {
            *o = clamp_offset(*o, max_off);
        });
    }

    pub fn get(&self) -> f32 {
        self.scroll_offset.get()
    }

    /// Apply a scroll delta from real user input; pre-empts any in-flight
    /// fling. See [`ScrollState::scroll_immediate`].
    pub fn scroll_immediate(&self, dx: f32) -> f32 {
        self.apply_delta(dx, true)
    }

    /// Apply leftover from a nested child without cancelling this container's
    /// own fling. See [`ScrollState::scroll_nested`].
    pub fn scroll_nested(&self, dx: f32) -> f32 {
        self.apply_delta(dx, false)
    }

    fn apply_delta(&self, dx: f32, user: bool) -> f32 {
        let dx = if dx.is_finite() { dx } else { 0.0 };
        let before = self.scroll_offset.get();
        let max_off = (self.content_width.get() - self.viewport_width.get()).max(0.0);

        let new_off = clamp_offset(before + dx, max_off);
        self.scroll_offset.set(new_off);
        let consumed = new_off - before;
        if user {
            self.physics.borrow_mut().record_user_input(consumed);
        } else {
            self.physics.borrow_mut().record_nested_input(consumed);
        }
        dx - consumed
    }

    /// Feed leftover (after the nested parent chain) into rubber-band overscroll.
    pub fn apply_overscroll(&self, leftover: f32) -> f32 {
        let max_off = (self.content_width.get() - self.viewport_width.get()).max(0.0);
        os_scroll_axis(
            &self.scroll_offset,
            &self.overscroll,
            self.overscroll_enabled.get(),
            max_off,
            self.scroll_offset.get(),
            leftover,
            &self.physics,
        )
    }

    pub fn tick(&self) -> bool {
        let now = Instant::now();
        let dt = (now - self.prev_tick.get()).as_secs_f32().min(0.1);
        self.prev_tick.set(now);

        if tick_os_axis(&self.overscroll, self.overscroll_enabled.get(), dt) {
            return true;
        }

        let max_off = (self.content_width.get() - self.viewport_width.get()).max(0.0);
        let mut p = self.physics.borrow_mut();
        if let Some(new_off) = p.tick_integrate(self.scroll_offset.get(), 0.0, max_off) {
            drop(p);
            self.scroll_offset.set(new_off);
            request_frame();
            true
        } else {
            false
        }
    }

    pub fn show_scrollbar(&self) -> bool {
        self.show_scrollbar.get()
    }

    pub fn to_binding(&self) -> ScrollBinding {
        let this = Rc::new(self.clone());
        let pc = Rc::clone(&this.parent_connection);
        let c_on_scroll = {
            let state = Rc::clone(&pc);
            let this = Rc::clone(&this);
            Rc::new(move |d: Vec2| -> Vec2 {
                let d = run_pre_scroll(&state, d);
                let leftover_x = this.scroll_immediate(d.x);
                let result = Vec2 {
                    x: leftover_x,
                    y: d.y,
                };
                let after_parent = run_post_scroll(&state, result);
                let final_x = this.apply_overscroll(after_parent.x);
                Vec2 {
                    x: final_x,
                    y: after_parent.y,
                }
            })
        } as Rc<dyn Fn(Vec2) -> Vec2>;
        let c_set_vp = {
            let this = Rc::clone(&this);
            Rc::new(move |w: f32| this.set_viewport_width(w))
        };
        let c_set_ct = {
            let this = Rc::clone(&this);
            Rc::new(move |w: f32| this.set_content_width(w))
        };
        let c_get = {
            let this = Rc::clone(&this);
            Rc::new(move || this.get() + this.overscroll_offset())
        };
        let c_set = {
            let this = Rc::clone(&this);
            Rc::new(move |off: f32| this.set_offset(off))
        };
        let c_tick = {
            let this = Rc::clone(&this);
            Rc::new(move || {
                this.tick();
            })
        };
        let c_set_nested = {
            let state = Rc::clone(&pc);
            Rc::new(move |conn| {
                *state.borrow_mut() = Some(conn);
            })
        };
        ScrollBinding::Horizontal(ScrollAxisBinding {
            on_scroll: Some(c_on_scroll),
            set_viewport_main: Some(c_set_vp),
            set_content_main: Some(c_set_ct),
            get_offset_main: Some(c_get),
            set_offset_main: Some(c_set),
            show_scrollbar: this.show_scrollbar(),
            tick: Some(c_tick),
            set_nested_scroll_parent: Some(c_set_nested),
        })
    }
}

/// 2D state
#[derive(Clone)]
pub struct ScrollStateXY {
    off_x: Signal<f32>,
    off_y: Signal<f32>,
    vp_w: Signal<f32>,
    vp_h: Signal<f32>,
    c_w: Signal<f32>,
    c_h: Signal<f32>,
    physics_x: Rc<RefCell<ScrollPhysics>>,
    physics_y: Rc<RefCell<ScrollPhysics>>,
    os_x: Signal<f32>,
    os_y: Signal<f32>,
    overscroll_enabled: Cell<bool>,
    pub(crate) parent_connection: Rc<RefCell<Option<NestedScrollConnection>>>,
    show_scrollbar: Cell<bool>,
    prev_tick: Cell<Instant>,
}

impl Default for ScrollStateXY {
    fn default() -> Self {
        Self::new()
    }
}

impl ScrollStateXY {
    pub fn new() -> Self {
        Self {
            off_x: signal(0.0),
            off_y: signal(0.0),
            vp_w: signal(0.0),
            vp_h: signal(0.0),
            c_w: signal(0.0),
            c_h: signal(0.0),
            physics_x: Rc::new(RefCell::new(ScrollPhysics::new())),
            physics_y: Rc::new(RefCell::new(ScrollPhysics::new())),
            os_x: signal(0.0),
            os_y: signal(0.0),
            overscroll_enabled: Cell::new(true),
            parent_connection: Rc::new(RefCell::new(None)),
            show_scrollbar: Cell::new(true),
            prev_tick: Cell::new(Instant::now()),
        }
    }

    pub fn set_overscroll_enabled(&self, enabled: bool) {
        self.overscroll_enabled.set(enabled);
    }

    pub fn set_show_scrollbar(&self, show: bool) {
        self.show_scrollbar.set(show);
    }

    pub fn overscroll_offset(&self) -> (f32, f32) {
        (self.os_x.get(), self.os_y.get())
    }

    pub fn set_nested_scroll_parent(&self, conn: NestedScrollConnection) {
        *self.parent_connection.borrow_mut() = Some(conn);
    }

    /// A `NestedScrollConnection` that consumes leftover scroll by scrolling
    /// THIS container, then chains anything still unabsorbed up to this
    /// container's own parent connection.
    pub fn connection(&self) -> NestedScrollConnection {
        let this = Rc::new(self.clone());
        let pc = Rc::clone(&this.parent_connection);
        NestedScrollConnection::new().on_post_scroll(
            move |_consumed: Vec2, available: Vec2, _source: NestedScrollSource| -> Vec2 {
                if available.x.abs() < 0.001 && available.y.abs() < 0.001 {
                    return Vec2::ZERO;
                }
                let after = this.scroll_nested(available);
                let after2 = run_post_scroll(&pc, after);
                Vec2 {
                    x: available.x - after2.x,
                    y: available.y - after2.y,
                }
            },
        )
    }

    pub fn set_viewport(&self, w: f32, h: f32) {
        let w = w.max(0.0);
        let h = h.max(0.0);
        let changed = (self.vp_w.get() - w).abs() > 0.5 || (self.vp_h.get() - h).abs() > 0.5;
        if changed {
            self.vp_w.set(w);
            self.vp_h.set(h);
            self.clamp();
        }
    }
    pub fn set_content(&self, w: f32, h: f32) {
        let w = w.max(0.0);
        let h = h.max(0.0);
        let changed = (self.c_w.get() - w).abs() > 0.5 || (self.c_h.get() - h).abs() > 0.5;
        if changed {
            self.c_w.set(w);
            self.c_h.set(h);
            self.clamp();
        }
    }
    pub fn set_offset_xy(&self, x: f32, y: f32) {
        let max_x = (self.c_w.get() - self.vp_w.get()).max(0.0);
        let max_y = (self.c_h.get() - self.vp_h.get()).max(0.0);
        self.off_x.set(clamp_offset(x, max_x));
        self.off_y.set(clamp_offset(y, max_y));
    }
    fn clamp(&self) {
        let max_x = (self.c_w.get() - self.vp_w.get()).max(0.0);
        let max_y = (self.c_h.get() - self.vp_h.get()).max(0.0);
        self.off_x.update(|x| *x = clamp_offset(*x, max_x));
        self.off_y.update(|y| *y = clamp_offset(*y, max_y));
    }
    pub fn get(&self) -> (f32, f32) {
        (self.off_x.get(), self.off_y.get())
    }

    fn os_scroll_axis(
        off: &Signal<f32>,
        os: &Signal<f32>,
        overscroll_enabled: bool,
        max_off: f32,
        before: f32,
        leftover: f32,
        physics: &RefCell<ScrollPhysics>,
    ) -> f32 {
        if !overscroll_enabled || leftover.abs() < 0.001 {
            return leftover;
        }
        let os_val = os.get();
        // Recovering from an active rubber band: absorb the reverse delta first.
        if os_val.abs() > 0.5 && os_val.signum() * leftover < 0.0 {
            let reduction = leftover.abs().min(os_val.abs());
            os.set(os_val - os_val.signum() * reduction);
            let remainder = leftover - leftover.signum() * reduction;
            if remainder.abs() > 0.5 {
                let new_off = clamp_offset(before + remainder, max_off);
                off.set(new_off);
                let consumed = new_off - before;
                physics.borrow_mut().record_nested_input(consumed);
                return remainder - consumed;
            }
            return 0.0;
        }

        // At the edge, pushing further: stretch the rubber band.
        let at_edge = (before <= 0.0 && leftover < 0.0) || (before >= max_off && leftover > 0.0);
        if max_off > 5.0 && at_edge && leftover.abs() > 0.5 {
            os.set(os_val + rubber_band(leftover, SCROLL_OVERSROLL_BAND_MAX));
            physics.borrow_mut().record_nested_input(0.0);
            return 0.0;
        }
        leftover
    }
    /// Apply a scroll delta from real user input; pre-empts any in-flight
    /// fling. See [`ScrollState::scroll_immediate`].
    pub fn scroll_immediate(&self, d: Vec2) -> Vec2 {
        self.apply_delta(d, true)
    }

    /// Apply leftover from a nested child without cancelling this container's
    /// own fling. See [`ScrollState::scroll_nested`].
    pub fn scroll_nested(&self, d: Vec2) -> Vec2 {
        self.apply_delta(d, false)
    }

    fn apply_delta(&self, d: Vec2, user: bool) -> Vec2 {
        let d = Vec2 {
            x: if d.x.is_finite() { d.x } else { 0.0 },
            y: if d.y.is_finite() { d.y } else { 0.0 },
        };
        let max_x = (self.c_w.get() - self.vp_w.get()).max(0.0);
        let max_y = (self.c_h.get() - self.vp_h.get()).max(0.0);
        let (bx, by) = (self.off_x.get(), self.off_y.get());

        let nx = clamp_offset(bx + d.x, max_x);
        let ny = clamp_offset(by + d.y, max_y);
        self.off_x.set(nx);
        self.off_y.set(ny);
        let (cx, cy) = (nx - bx, ny - by);

        let mut px = self.physics_x.borrow_mut();
        let mut py = self.physics_y.borrow_mut();
        if user {
            px.record_user_input(cx);
            py.record_user_input(cy);
        } else {
            px.record_nested_input(cx);
            py.record_nested_input(cy);
        }
        drop((px, py));

        Vec2 {
            x: d.x - cx,
            y: d.y - cy,
        }
    }

    /// Feed leftover (after the nested parent chain) into rubber-band overscroll.
    pub fn apply_overscroll(&self, d: Vec2) -> Vec2 {
        let max_x = (self.c_w.get() - self.vp_w.get()).max(0.0);
        let max_y = (self.c_h.get() - self.vp_h.get()).max(0.0);
        let (bx, by) = (self.off_x.get(), self.off_y.get());

        let lx = Self::os_scroll_axis(
            &self.off_x,
            &self.os_x,
            self.overscroll_enabled.get(),
            max_x,
            bx,
            d.x,
            &self.physics_x,
        );
        let ly = Self::os_scroll_axis(
            &self.off_y,
            &self.os_y,
            self.overscroll_enabled.get(),
            max_y,
            by,
            d.y,
            &self.physics_y,
        );
        Vec2 { x: lx, y: ly }
    }
    pub fn tick(&self) -> bool {
        let now = Instant::now();
        let dt = (now - self.prev_tick.get()).as_secs_f32().min(0.1);
        self.prev_tick.set(now);

        if self.overscroll_enabled.get()
            && (tick_os_axis(&self.os_x, true, dt) || tick_os_axis(&self.os_y, true, dt))
        {
            return true;
        }

        let max_x = (self.c_w.get() - self.vp_w.get()).max(0.0);
        let max_y = (self.c_h.get() - self.vp_h.get()).max(0.0);
        let (bx, by) = (self.off_x.get(), self.off_y.get());

        let mut px = self.physics_x.borrow_mut();
        let mut py = self.physics_y.borrow_mut();
        if !px.animating && !py.animating {
            return false;
        }
        if px.animating {
            if px.vel.abs() < px.stop_velocity {
                px.vel = 0.0;
                px.animating = false;
            } else {
                let nx = clamp_offset(bx + px.vel * dt, max_x);
                if (nx - bx).abs() < 0.01 && (bx <= 0.0 || bx >= max_x) {
                    px.vel = 0.0;
                    px.animating = false;
                } else {
                    let speed = px.vel.abs();
                    let t = (speed / 4000.0).min(1.0);
                    let effective_decay = 0.85 + t * 0.10;
                    px.vel *= effective_decay.powf(dt * 60.0);
                    if px.vel.abs() < px.stop_velocity {
                        px.vel = 0.0;
                        px.animating = false;
                    } else {
                        self.off_x.set(nx);
                    }
                }
            }
        }
        if py.animating {
            if py.vel.abs() < py.stop_velocity {
                py.vel = 0.0;
                py.animating = false;
            } else {
                let ny = clamp_offset(by + py.vel * dt, max_y);
                if (ny - by).abs() < 0.01 && (by <= 0.0 || by >= max_y) {
                    py.vel = 0.0;
                    py.animating = false;
                } else {
                    let speed = py.vel.abs();
                    let t = (speed / 4000.0).min(1.0);
                    let effective_decay = 0.85 + t * 0.10;
                    py.vel *= effective_decay.powf(dt * 60.0);
                    if py.vel.abs() < py.stop_velocity {
                        py.vel = 0.0;
                        py.animating = false;
                    } else {
                        self.off_y.set(ny);
                    }
                }
            }
        }
        let running = px.animating || py.animating;
        if running {
            request_frame();
        }
        running
    }

    pub fn show_scrollbar(&self) -> bool {
        self.show_scrollbar.get()
    }

    pub fn to_binding(&self) -> ScrollBinding {
        let this = Rc::new(self.clone());
        let pc = Rc::clone(&this.parent_connection);
        let c_on_scroll = {
            let state = Rc::clone(&pc);
            let this = Rc::clone(&this);
            Rc::new(move |d: Vec2| -> Vec2 {
                let d = run_pre_scroll(&state, d);
                let result = this.scroll_immediate(d);
                let after_parent = run_post_scroll(&state, result);
                this.apply_overscroll(after_parent)
            })
        } as Rc<dyn Fn(Vec2) -> Vec2>;
        let c_set_vw = {
            let this = Rc::clone(&this);
            Rc::new(move |w: f32| this.set_viewport(w, this.vp_h.get()))
        };
        let c_set_vh = {
            let this = Rc::clone(&this);
            Rc::new(move |h: f32| this.set_viewport(this.vp_w.get(), h))
        };
        let c_set_cw = {
            let this = Rc::clone(&this);
            Rc::new(move |w: f32| this.set_content(w, this.c_h.get()))
        };
        let c_set_ch = {
            let this = Rc::clone(&this);
            Rc::new(move |h: f32| this.set_content(this.c_w.get(), h))
        };
        let c_get_xy = {
            let this = Rc::clone(&this);
            Rc::new(move || {
                let (ox, oy) = this.get();
                let (osx, osy) = this.overscroll_offset();
                (ox + osx, oy + osy)
            })
        };
        let c_set_xy = {
            let this = Rc::clone(&this);
            Rc::new(move |x: f32, y: f32| this.set_offset_xy(x, y))
        };
        let c_tick = {
            let this = Rc::clone(&this);
            Rc::new(move || {
                this.tick();
            })
        };
        let c_set_nested = {
            let state = Rc::clone(&pc);
            Rc::new(move |conn| {
                *state.borrow_mut() = Some(conn);
            })
        };
        ScrollBinding::Both(ScrollBothBinding {
            on_scroll: Some(c_on_scroll),
            set_viewport_width: Some(c_set_vw),
            set_viewport_height: Some(c_set_vh),
            set_content_width: Some(c_set_cw),
            set_content_height: Some(c_set_ch),
            get_offset_xy: Some(c_get_xy),
            set_offset_xy: Some(c_set_xy),
            show_scrollbar: this.show_scrollbar(),
            tick: Some(c_tick),
            set_nested_scroll_parent: Some(c_set_nested),
        })
    }
}

pub fn run_pre_scroll(conn: &RefCell<Option<NestedScrollConnection>>, d: Vec2) -> Vec2 {
    if let Some(ref parent) = *conn.borrow() {
        let consumed = parent.dispatch_pre_scroll(d, NestedScrollSource::UserInput);
        d - consumed
    } else {
        d
    }
}

pub fn run_post_scroll(conn: &RefCell<Option<NestedScrollConnection>>, leftover: Vec2) -> Vec2 {
    if let Some(ref parent) = *conn.borrow() {
        let added =
            parent.dispatch_post_scroll(Vec2::ZERO, leftover, NestedScrollSource::UserInput);
        leftover - added
    } else {
        leftover
    }
}

#[cfg(test)]
mod fling_tests {
    use super::*;

    const FRAME: web_time::Duration = web_time::Duration::from_millis(16);

    fn seeded() -> ScrollState {
        let st = ScrollState::new();
        st.set_viewport_height(100.0);
        st.set_content_height(4000.0);
        st
    }

    /// Advance one 60Hz frame. The physics derives `dt` from the wall clock, so
    /// a test that never advances real time cannot observe fling integration at
    /// all and would pass even with the double-count restored.
    fn frame() {
        std::thread::sleep(FRAME);
    }

    /// A sustained drag must move the surface by the input and nothing more.
    /// This is the regression: the per-frame integrator used to run on the same
    /// frames that applied the drag delta, so travel was roughly doubled.
    #[test]
    fn drag_does_not_double_count() {
        let st = seeded();
        let (frames, step) = (10, 30.0);
        for _ in 0..frames {
            st.scroll_immediate(step);
            frame();
            st.tick();
        }
        let expected = step * frames as f32;
        assert!(
            (st.get() - expected).abs() < 1.0,
            "drag of {expected} over {frames} frames moved {}",
            st.get()
        );
    }

    /// Once input stops arriving the stored velocity must carry the surface on
    /// as a fling, so a flick still coasts.
    #[test]
    fn fling_continues_after_input_stops() {
        let st = seeded();
        st.scroll_immediate(200.0);
        frame();
        st.tick();
        let at_release = st.get();
        let mut coasted = 0.0;
        for _ in 0..10 {
            frame();
            if st.tick() {
                coasted += 1.0;
            }
        }
        assert!(coasted > 0.0, "fling stopped immediately after release");
        assert!(st.get() > at_release, "fling must travel further");
    }

    /// The first frame after release must continue at roughly the speed the
    /// finger was moving. A lurch here reads as a jitter kick: the integrator
    /// used to bail out before sampling the clock, so `last_t` went stale for
    /// the whole drag and all of it landed in one frame.
    #[test]
    fn release_is_continuous_with_the_drag() {
        for step in [8.0f32, 30.0, 70.0] {
            let st = seeded();
            for _ in 0..10 {
                st.scroll_immediate(step);
                frame();
                st.tick();
            }
            let released = st.get();
            frame();
            st.tick();
            let first = st.get() - released;
            assert!(
                (first - step).abs() < step * 0.25,
                "drag at {step}px/frame released into a {first}px step"
            );
        }
    }

    /// A drag landing mid-fling follows the finger instead of being yanked by
    /// the stale velocity.
    #[test]
    fn drag_cancels_stale_fling_direction() {
        let st = seeded();
        for _ in 0..6 {
            st.scroll_immediate(200.0);
            frame();
            st.tick();
        }
        let before = st.get();
        for _ in 0..6 {
            st.scroll_immediate(-20.0);
            frame();
            st.tick();
        }
        assert!(
            st.get() < before,
            "reverse drag must win over the old fling ({} -> {})",
            before,
            st.get()
        );
    }

    /// A parent handed leftover by a child must still be able to fling.
    #[test]
    fn parent_flings_after_taking_child_leftover() {
        let st = seeded();
        let conn = st.connection();
        let consumed = conn.dispatch_post_scroll(
            Vec2::ZERO,
            Vec2 { x: 0.0, y: 200.0 },
            NestedScrollSource::UserInput,
        );
        // `on_post_scroll` reports what THIS container consumed.
        assert!(
            (consumed.y - 200.0).abs() < 0.001,
            "consumed {}",
            consumed.y
        );
        assert!(st.get() > 0.0, "parent scrolled");
        assert!(st.physics.borrow().is_animating(), "parent has velocity");
        frame();
        st.tick();
        let before_coast = st.get();
        frame();
        st.tick();
        assert!(
            st.get() > before_coast,
            "parent must coast: nested velocity reached the driven physics"
        );
    }
}