rust_widgets 2.7.0

// SPDX-FileCopyrightText: Copyright (c) 2026 Mike Li/Mikewolfli/Wei Li(mikewolfli@163.com)
// SPDX-License-Identifier: MIT

//! BottomSheet widget — a modal panel that slides up from the bottom edge of the
//! screen, similar to Android/Material Design bottom sheets.
//!
//! The BottomSheet displays a semi-transparent overlay behind a rounded-rect panel
//! at the bottom of its geometry. It supports open/close state, a drag handle at
//! the top of the sheet, and emits a `dismissed` signal when the user taps outside
//! or directly on the sheet area.

use crate::core::{Color, Rect, Size};
use crate::event::{Event, EventHandler};
use crate::render::RenderContext;
use crate::signal::GenericSignal;
use crate::style::{MotionSlot, PropertyDriver};
use crate::widget::capability::coercion::{expect_bool, expect_f32};
use crate::widget::capability::properties_trait::{base_property_get, base_property_set};
use crate::widget::capability::types::{CapabilityAccessError, CapabilityValue};
use crate::widget::capability::WidgetProperties;
use crate::widget::{BaseWidget, Draw, Widget, WidgetKind};
use crate::{impl_widget_property_hooks, property_names_of};

/// BottomSheet widget — a modal panel that slides up from the bottom edge.
///
/// The sheet occupies the bottom `content_height` pixels of its geometry rect.
/// When `open` is true, a semi-transparent gray overlay fills the area above the
/// sheet and a rounded panel is drawn at the bottom with a small drag handle.
/// Any click dismisses the sheet and fires the `dismissed` signal.
pub struct BottomSheet {
    base: BaseWidget,
    open: bool,
    content_height: u32,
    /// How far the sheet has risen, `0.0` fully stowed below the page and `1.0` fully shown.
    ///
    /// # Why this is separate from `open`
    ///
    /// `open` is the logical state a caller reads the instant it changes; `rise` is what the draw
    /// path measures the panel and the scrim with. Drawing straight from `open` put the sheet at its
    /// final position on the first frame and removed it on the last, so a bottom sheet — whose whole
    /// gesture *is* "slide up from the bottom edge" — teleported. Same split, same reason, as
    /// `Switch`'s `checked`/`travel`. It starts at `0.0` because a freshly built sheet is closed.
    rise: PropertyDriver,
    /// Emitted when the sheet is dismissed by user interaction.
    pub dismissed: GenericSignal,
}

impl BottomSheet {
    /// Creates a new BottomSheet widget with the given geometry.
    ///
    /// The sheet starts closed. Default content height is half the geometry height.
    pub fn new(geometry: Rect) -> Self {
        Self {
            base: BaseWidget::new(WidgetKind::BottomSheet, geometry, "BottomSheet"),
            open: false,
            content_height: geometry.height / 2,
            // At rest at the stowed end: a freshly built sheet is closed, so it must not animate
            // *down* on its first frame.
            rise: PropertyDriver::at(0.0, MotionSlot::Normal),
            dismissed: GenericSignal::new(),
        }
    }

    /// Opens the bottom sheet, making it visible.
    pub fn open(&mut self) {
        if !self.open {
            self.open = true;
            // Aim the slide; the frames that follow carry the panel up. No redraw is requested
            // here, because a redraw would not be what makes the motion visible --
            // `tick_animations` reports the movement itself and that is what keeps the loop
            // painting.
            self.rise.set_target(1.0);
        }
    }

    /// Dismisses (closes) the bottom sheet without emitting the dismissed signal.
    pub fn dismiss(&mut self) {
        if self.open {
            self.open = false;
            self.rise.set_target(0.0);
            self.base.request_redraw();
        }
    }

    /// How far the sheet has risen, `0.0` stowed and `1.0` fully shown.
    ///
    /// This is the *drawn* fraction: the panel's offset and the scrim's strength are both functions
    /// of it, so a test can assert the sheet slid rather than appeared by sampling it per frame.
    pub fn rise_progress(&self) -> f32 {
        self.rise.value()
    }

    /// Advances the rise by `delta_ms`; `true` while it is still moving.
    pub fn tick(&mut self, delta_ms: u32) -> bool {
        self.rise.tick(delta_ms)
    }

    /// Whether the sheet is between two positions -- answers only, never advances.
    pub fn is_animating(&self) -> bool {
        self.rise.is_moving()
    }

    /// Sets the content height of the sheet panel (in pixels).
    ///
    /// The sheet is drawn at the bottom of the geometry rect using this height.
    /// Clamped to the geometry height.
    pub fn set_content_height(&mut self, height: u32) {
        self.content_height = height.min(self.base.geometry.height);
        self.base.request_redraw();
    }

    /// Returns whether the bottom sheet is currently open.
    pub fn is_open(&self) -> bool {
        self.open
    }

    /// Returns the height of the sheet panel in pixels.
    pub fn content_height(&self) -> u32 {
        self.content_height
    }
}

impl Widget for BottomSheet {
    fn base(&self) -> &BaseWidget {
        &self.base
    }

    fn base_mut(&mut self) -> &mut BaseWidget {
        &mut self.base
    }

    fn size_hint(&self) -> Size {
        crate::core::Size::new(300, 200)
    }

    // The rise is the control's own animation; the trait spelling is what the frame bus reaches
    // through `&mut dyn Widget`, which is the only way the slide actually happens.
    fn tick(&mut self, delta_ms: u32) -> bool {
        BottomSheet::tick(self, delta_ms)
    }

    fn is_animating(&self) -> bool {
        BottomSheet::is_animating(self)
    }
    impl_draw_bridge!();
    impl_widget_property_hooks!();
}

/// `BottomSheet`'s property contract.
///
/// Read/write semantics are carried over unchanged from the centralised
/// `access_read_dialog.in.rs` / `access_write_dialog.in.rs` dispatch, so callers see
/// the same coercions and the same errors as before. The panel height is stored as
/// a `u32` internally and published as `Float` to match the legacy shape.
impl WidgetProperties for BottomSheet {
    fn get(&self, name: &str) -> Result<CapabilityValue, CapabilityAccessError> {
        match name {
            "expanded" => Ok(CapabilityValue::Bool(self.is_open())),
            "peek_height" => Ok(CapabilityValue::Float(f64::from(self.content_height()))),
            _ => base_property_get(self, name),
        }
    }

    fn set(&mut self, name: &str, value: CapabilityValue) -> Result<(), CapabilityAccessError> {
        match name {
            "expanded" => {
                if expect_bool(value)? {
                    self.open();
                } else {
                    self.dismiss();
                }
                Ok(())
            }
            "peek_height" => {
                self.set_content_height(expect_f32(value)? as u32);
                Ok(())
            }
            _ => base_property_set(self, name, value),
        }
    }

    fn property_names(&self) -> &'static [&'static str] {
        property_names_of!["expanded", "peek_height", BASE_PROPERTY_NAMES]
    }

    /// Runs one of the commands `bottom_sheet` publishes.
    ///
    /// Both names carry a payload, so they are answered through the property
    /// route (`expanded` / `peek_height`). The trait default would answer
    /// `UnknownCommand` for names the capability does publish, which
    /// `invoke_command` reports as a registry/implementation disagreement.
    fn command(&mut self, name: &str) -> Result<(), CapabilityAccessError> {
        match name {
            "set_expanded" | "set_peek_height" => Err(CapabilityAccessError::OutOfRange),
            _ => Err(CapabilityAccessError::UnknownCommand),
        }
    }
}

impl Draw for BottomSheet {
    fn draw(&mut self, context: &mut RenderContext) {
        let rect = self.geometry();
        if rect.width == 0 || rect.height == 0 {
            return;
        }

        // Chrome colours resolve explicit style first, then the theme's resolved style for
        // this control, and only then a literal. Every colour below used to be a literal, so
        // a light/dark switch left the pane and its handle unchanged — the rendering census
        // reported the control as theme-blind.
        //
        // The theme reads take and release the global manager's lock internally, so no
        // guard is held across the draw (the mutex is not re-entrant).
        let style = self.base.style().clone();
        let theme = crate::style::resolved_theme_style("bottom_sheet");
        // `bottom_sheet` is absent from `WidgetRole::for_kind_name`'s table, so it classifies
        // as `Surface` and resolves to `theme.colors.background` — the window's own fill. A
        // pane painted in that colour would be byte-identical to the frame behind it, so a
        // resolved surface equal to the window fill is re-derived a visible step away from
        // it, the same distinction `Colors::input_background` draws for a field.
        //
        // Read as its own lock acquisition and copied out as a value, so the guard is
        // dropped before anything else touches the theme.
        let window_fill = {
            let manager = crate::style::theme_manager();
            manager.current_theme().map(|active| active.colors.background).unwrap_or(Color::WHITE)
        };
        let ink = style
            .text_color
            .or_else(|| theme.as_ref().and_then(|t| t.text_color))
            .unwrap_or(Color::rgb(40, 40, 40));
        let sheet_color = match style
            .background_color
            .or_else(|| theme.as_ref().and_then(|t| t.background_color))
        {
            Some(resolved) if resolved != window_fill => resolved,
            _ => window_fill.blend(&ink, 0.08),
        };
        let border_color = style
            .border_color
            .or_else(|| theme.as_ref().and_then(|t| t.border_color))
            .filter(|resolved| *resolved != sheet_color)
            .unwrap_or_else(|| sheet_color.blend(&ink, 0.35));
        let handle_color = ink.blend(&sheet_color, 0.35);

        let sheet_height = self.content_height.min(rect.height);

        // 1. Draw the modal scrim covering the area above the sheet.
        //
        // Painting the scrim is what keeps the control visible in its default (closed)
        // state. It used to `return` early while closed, so a freshly constructed sheet
        // painted nothing at all and the census reported `ink = 0`; the scrim is drawn at
        // partial opacity in both states, which reads as a dimmed backdrop in either
        // appearance and still leaves the sheet itself the opaque element when open.
        //
        // The scrim darkens the *backdrop it covers* toward an absolute black. Blending
        // toward black is what every platform's modal scrim does (Material's
        // `Colors.black54`, UIKit and SwiftUI all dim toward black); none blends toward
        // the foreground colour.
        //
        // The old `ink.blend(&sheet_color, 0.55)` blended toward the *foreground*, so on the
        // dark appearance it brightened the backdrop instead of dimming it — the SVG showed
        // `rgba(121,121,121)` over an `rgba(18,18,18)` frame, so the modal backplate was lit
        // up while the sheet it was meant to sit behind ended up darker than its own scrim.
        //
        // # Why the old value looked plausible
        //
        // With the two presets this ships with, the old expression happened to produce 120 on
        // the dark appearance and 122 on the light one — nearly identical values in both. That
        // is not agreement but coincidence: `ink` and `sheet_color` *swap roles* between the
        // presets (dark ink is the light preset's surface and vice versa), so the same weights
        // land on nearly the same bytes from opposite directions. A quantity that only
        // coincides because the two inputs are mirror images of each other is derived from
        // nothing — which is exactly why it could invert the scrim's direction on one
        // appearance without the number changing.
        //
        // # Why the source is the window fill and not the sheet colour
        //
        // The scrim covers the *window*, so the colour it must darken is the window fill.
        // Deriving it from the panel's own colour instead leaves it lighter than the frame
        // wherever the panel itself is lighter than the window — which is the dark preset,
        // where the panel is `rgb(35,35,35)` over a `rgb(18,18,18)` window and a scrim of
        // `rgb(24,24,24)` would still read as a lift rather than a dimming.
        let overlay_height = rect.height - sheet_height;
        // The rise drives both halves of the appearance: the scrim fades in and the panel slides up.
        // Deriving them from *one* value is what keeps the two in step, so the backdrop can never be
        // fully dimmed while the panel is still below the edge.
        let rise = self.rise.value();
        const SCRIM_DARKEN: f32 = 0.32;
        // The token wins when a theme provides one; the blend is the honest fallback for an
        // unthemed build. The token is read here so a theme author can express the dimming
        // *once*, instead of every modal re-deriving the same weight and drifting apart --
        // which is why `Colors::scrim` exists as a role at all.
        let scrim_color = crate::style::layer_color(crate::style::LayerColor::Scrim)
            .unwrap_or_else(|| window_fill.blend(&Color::BLACK, SCRIM_DARKEN));
        if overlay_height > 0 && rise > 0.0 {
            // A rising sheet's scrim is a fraction of its own alpha, not a second colour: fading by
            // scaling the token's alpha is the one form that works for a theme that authored its
            // scrim as a translucent white as well as one that authored it as a black veil.
            let scrim_color = scrim_color.with_alpha((scrim_color.a as f32 * rise) as u8);
            let overlay_rect = Rect::new(rect.x, rect.y, rect.width, overlay_height);
            context.fill_rect(overlay_rect, scrim_color);
        }

        // A sheet that has not risen at all paints only that much scrim (nothing, at rest); the
        // panel and its handle belong to the risen part alone. This replaces the old `if !self.open
        // { return; }`: the guard is now on the *drawn* position rather than the logical flag, so the
        // last frame of a dismissal still paints the panel where it is.
        if rise <= 0.0 {
            return;
        }

        // The panel slides up from the bottom edge: at `rise == 0` it is entirely below the page,
        // and at `rise == 1` it is at its resting position. Interpolating the *y* rather than the
        // height keeps the panel's own shape fixed while it travels, which is what a sheet does --
        // a growing height would read as the content being revealed rather than the panel arriving.
        let resting_y = rect.y + rect.height as i32 - sheet_height as i32;
        let stowed_y = rect.y + rect.height as i32;
        let sheet_y = resting_y + ((stowed_y - resting_y) as f32 * (1.0 - rise)) as i32;
        let sheet_rect = Rect::new(rect.x, sheet_y, rect.width, sheet_height);

        // 2. Draw the sheet panel with rounded top corners
        let sheet_radius = 16;
        context.fill_rounded_rect(sheet_rect, sheet_radius, sheet_color);

        // 3. Draw a thin stroke at the rounded top edge for definition
        context.draw_rounded_rect_stroke(sheet_rect, sheet_radius, border_color, 1);

        // 4. Draw the drag handle at the top center of the sheet
        let handle_width = 32;
        let handle_height = 5;
        let handle_x = rect.x + (rect.width as i32 - handle_width as i32) / 2;
        let handle_y = sheet_y + 8;
        let handle_rect = Rect::new(handle_x, handle_y, handle_width, handle_height);
        context.fill_rounded_rect(handle_rect, handle_height / 2, handle_color);
    }
}

impl EventHandler for BottomSheet {
    fn handle_event(&mut self, event: &Event) {
        if !self.base.is_enabled() {
            return;
        }

        match event {
            Event::MousePress { pos: _, button } => {
                if *button == 1 && self.open {
                    self.open = false;
                    self.dismissed.emit();
                    self.base.request_redraw();
                }
            }
            _ => {
                self.base.handle_event(event);
            }
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::core::Point;
    use crate::widget::svg::render_to_svg;
    use std::sync::atomic::{AtomicBool, Ordering};
    use std::sync::Arc;

    fn make_sheet() -> BottomSheet {
        BottomSheet::new(Rect::new(0, 0, 400, 600))
    }

    #[test]
    fn bottom_sheet_default_is_closed() {
        let sheet = make_sheet();
        assert!(!sheet.is_open());
        assert_eq!(sheet.kind(), WidgetKind::BottomSheet);
        assert_eq!(sheet.base.geometry, Rect::new(0, 0, 400, 600));
    }

    #[test]
    fn bottom_sheet_open_and_close() {
        let mut sheet = make_sheet();
        assert!(!sheet.is_open());

        sheet.open();
        assert!(sheet.is_open());

        sheet.dismiss();
        assert!(!sheet.is_open());
    }

    #[test]
    fn bottom_sheet_set_content_height() {
        let mut sheet = make_sheet();
        assert_eq!(sheet.content_height, 300); // half of 600

        sheet.set_content_height(200);
        assert_eq!(sheet.content_height, 200);

        // Clamp to geometry height
        sheet.set_content_height(999);
        assert_eq!(sheet.content_height, 600);
    }

    #[test]
    fn bottom_sheet_dismiss_signal_emits() {
        let mut sheet = make_sheet();
        sheet.open();
        assert!(sheet.is_open());

        let dismissed = Arc::new(AtomicBool::new(false));
        let d = dismissed.clone();
        sheet.dismissed.connect(move || {
            d.store(true, Ordering::SeqCst);
        });

        sheet.handle_event(&Event::MousePress { pos: Point::new(200, 300), button: 1 });
        assert!(!sheet.is_open());
        assert!(dismissed.load(Ordering::SeqCst));
    }

    #[test]
    fn bottom_sheet_mouse_press_dismisses_when_open() {
        let mut sheet = make_sheet();
        sheet.open();
        assert!(sheet.is_open());

        sheet.handle_event(&Event::MousePress { pos: Point::new(50, 50), button: 1 });
        assert!(!sheet.is_open());
    }

    #[test]
    fn bottom_sheet_mouse_press_noop_when_closed() {
        let mut sheet = make_sheet();
        assert!(!sheet.is_open());

        let dismissed = Arc::new(AtomicBool::new(false));
        let d = dismissed.clone();
        sheet.dismissed.connect(move || {
            d.store(true, Ordering::SeqCst);
        });

        sheet.handle_event(&Event::MousePress { pos: Point::new(50, 50), button: 1 });
        assert!(!dismissed.load(Ordering::SeqCst));
    }

    #[test]
    fn bottom_sheet_other_button_noop() {
        let mut sheet = make_sheet();
        sheet.open();

        sheet.handle_event(&Event::MousePress { pos: Point::new(50, 50), button: 2 });
        assert!(sheet.is_open());
    }

    #[test]
    fn bottom_sheet_disabled_blocks_events() {
        let mut sheet = make_sheet();
        sheet.set_enabled(false);
        sheet.open();
        assert!(sheet.is_open());

        let dismissed = Arc::new(AtomicBool::new(false));
        let d = dismissed.clone();
        sheet.dismissed.connect(move || {
            d.store(true, Ordering::SeqCst);
        });

        sheet.handle_event(&Event::MousePress { pos: Point::new(50, 50), button: 1 });
        assert!(sheet.is_open());
        assert!(!dismissed.load(Ordering::SeqCst));
    }

    #[test]
    fn bottom_sheet_open_twice_noop() {
        let mut sheet = make_sheet();
        sheet.open();
        sheet.open(); // should not change anything
        assert!(sheet.is_open());
    }

    #[test]
    fn bottom_sheet_dismiss_twice_noop() {
        let mut sheet = make_sheet();
        sheet.dismiss(); // no-op when already closed
        assert!(!sheet.is_open());

        sheet.open();
        sheet.dismiss();
        sheet.dismiss(); // no-op when already closed
        assert!(!sheet.is_open());
    }

    #[test]
    fn bottom_sheet_svg_output_open() {
        let mut sheet = make_sheet();
        sheet.open();
        let svg = render_to_svg(&mut sheet);
        assert!(svg.starts_with("<svg"));
        assert!(svg.ends_with("</svg>"));
        assert!(svg.contains("width=\"400\""));
        assert!(svg.contains("height=\"600\""));
    }

    #[test]
    fn bottom_sheet_svg_output_closed() {
        let mut sheet = make_sheet();
        let svg = render_to_svg(&mut sheet);
        assert!(svg.starts_with("<svg"));
        assert!(svg.ends_with("</svg>"));
    }

    #[test]
    fn bottom_sheet_content_height_default_is_half_geometry() {
        let sheet = BottomSheet::new(Rect::new(0, 0, 400, 800));
        assert_eq!(sheet.content_height, 400);
    }

    #[test]
    fn bottom_sheet_dismiss_via_overlay_click() {
        let mut sheet = make_sheet();
        sheet.open();

        // Click in the overlay area (above the sheet panel, in the top half)
        let dismissed = Arc::new(AtomicBool::new(false));
        let d = dismissed.clone();
        sheet.dismissed.connect(move || {
            d.store(true, Ordering::SeqCst);
        });

        sheet.handle_event(&Event::MousePress { pos: Point::new(100, 50), button: 1 });
        assert!(!sheet.is_open());
        assert!(dismissed.load(Ordering::SeqCst));
    }

    #[test]
    fn bottom_sheet_dismiss_via_sheet_click() {
        let mut sheet = make_sheet();
        sheet.open();

        // Click in the sheet area (bottom half)
        let dismissed = Arc::new(AtomicBool::new(false));
        let d = dismissed.clone();
        sheet.dismissed.connect(move || {
            d.store(true, Ordering::SeqCst);
        });

        sheet.handle_event(&Event::MousePress { pos: Point::new(200, 450), button: 1 });
        assert!(!sheet.is_open());
        assert!(dismissed.load(Ordering::SeqCst));
    }

    /// Opening a sheet slides the panel up instead of placing it there.
    ///
    /// # The defect this pins
    ///
    /// The draw read `open` directly, so the panel appeared at its final position on the first frame
    /// and vanished on the last — on the one control whose whole gesture *is* "slide up from the
    /// bottom edge".
    ///
    /// # Why this asserts on pixels as well as on the model
    ///
    /// A first version sampled only `rise_progress()` and **passed with the draw reverted to a fixed
    /// panel** — a progress nothing reads is not a slide. So the assertions are in two halves: the
    /// model must take an interior value, and the *painted* panel must be somewhere else at that
    /// moment than at either end. The painted position is read from the document's panel rectangle,
    /// which the sheet is the only element to emit at that width.
    #[test]
    fn opening_the_sheet_slides_the_panel_up() {
        use crate::widget::svg::render_to_svg;

        let mut sheet = BottomSheet::new(Rect::new(0, 0, 240, 120));
        assert_eq!(sheet.rise_progress(), 0.0, "a fresh sheet is stowed");
        assert!(!sheet.is_animating(), "and owes no frames");

        sheet.open();
        assert!(sheet.is_open(), "the logical state answers at once");
        assert!(sheet.is_animating(), "while the drawn position owes frames");
        assert_eq!(sheet.rise_progress(), 0.0, "the slide starts where the panel was");

        // The panel's own top edge, read from the emitted document. The panel is the only element
        // the sheet draws with a corner radius (`rx=16`), so naming it that way is what keeps the
        // measurement from picking up the scrim -- which is also full width, at y=0, and would
        // satisfy any test that merely looked for "a wide rectangle".
        fn panel_top(svg: &str) -> Option<i32> {
            svg.split("<rect ")
                .filter(|chunk| chunk.contains("rx=\"16\""))
                .filter_map(|chunk| {
                    let y = chunk.split("y=\"").nth(1)?;
                    y.split('"').next()?.parse::<i32>().ok()
                })
                .max()
        }

        let stowed_top = panel_top(&render_to_svg(&mut sheet));
        assert!(sheet.tick(60), "still moving after one step");
        let mid = sheet.rise_progress();
        assert!(
            mid > 0.0 && mid < 1.0,
            "the sheet must pass through an interior position (got {mid})"
        );
        let mid_top = panel_top(&render_to_svg(&mut sheet));

        while sheet.tick(60) {}
        assert_eq!(sheet.rise_progress(), 1.0, "and settle fully shown");
        let shown_top = panel_top(&render_to_svg(&mut sheet));

        // At rest the panel is entirely below the page, so it is not painted at all; as soon as the
        // slide begins it appears from the bottom edge and travels *upward* (a smaller y each frame
        // it is compared across).
        assert_eq!(stowed_top, None, "a stowed panel is below the page, so nothing of it is painted");
        let middle = mid_top.expect("a mid-slide sheet paints a panel");
        let shown = shown_top.expect("a settled sheet paints a panel");
        assert!(
            middle > shown,
            "the panel must rise: mid-slide top {middle} must be below its settled top {shown}"
        );
        assert_eq!(shown, 60, "and settle where the stowed geometry says it belongs (60)");

        // Dismissing is the same movement in reverse, so the panel does not vanish on the last frame.
        sheet.dismiss();
        assert!(!sheet.is_open());
        assert!(sheet.is_animating(), "closing is also a slide");
        assert!(!sheet.tick(1000) || true, "one long frame is allowed to finish it");
        while sheet.tick(60) {}
        assert_eq!(sheet.rise_progress(), 0.0, "back to stowed");
    }
}