waterui_controls/

button.rs

//! Button component for `WaterUI`
//!
//! This module provides a Button component that allows users to trigger actions
//! when clicked.
//! ![Button](https://raw.githubusercontent.com/water-rs/waterui/dev/docs/illustrations/button.svg)
//!
//!
//! # Examples
//!
//! ```rust,ignore
//! use waterui::prelude::*;
//!
//! let button = button("Click me").action(|| {
//!     println!("Button clicked!");
//! });
//!
//! // Button with link style
//! let link_button = button("Visit website")
//!     .style(ButtonStyle::Link)
//!     .action(|| { /* open URL */ });
//! ```
//!
//! Tip: `action` receives a `HandlerFn`, it can extract value from environment and pass it to the action.
//! To learn more about `HandlerFn`, see the [`HandlerFn`] documentation.

use core::fmt::Debug;

/// Visual style options for buttons.
///
/// Different button styles provide different visual emphasis and behavior.
#[non_exhaustive]
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
pub enum ButtonStyle {
    /// The default button style, determined by the platform and context.
    /// On macOS/iOS, this typically renders as a rounded rectangle with background.
    #[default]
    Automatic,
    /// A plain text button without any background or border.
    /// Suitable for low-emphasis actions.
    Plain,
    /// A button styled as a hyperlink, typically with underlined blue text.
    /// Used for URL navigation and text-based links.
    Link,
    /// A button without a visible border, but may show hover/press effects.
    /// Similar to Plain but with more interactive feedback.
    Borderless,
    /// A prominent button style for primary actions.
    /// Typically rendered with a filled background color.
    Bordered,
    /// A prominent button with visible border.
    /// Similar to Bordered but with more prominent styling.
    BorderedProminent,
}

use alloc::boxed::Box;
use waterui_core::handler::{
    BoxHandler, Handler, HandlerFn, HandlerFnWithState, IntoHandler, IntoHandlerWithState,
    into_handler, into_handler_with_state,
};
use waterui_core::view::{ConfigurableView, Hook, ViewConfiguration};
use waterui_core::{Environment, Native, NativeView, impl_debug};

use waterui_core::AnyView;
use waterui_core::View;

/// Configuration for a button component.
///
/// Use the `Button` struct's methods to customize these properties.
///
/// # Layout Behavior
///
/// Buttons size themselves to fit their label content and never stretch to fill
/// extra space. In a stack, they take only the space they need.
///
// ═══════════════════════════════════════════════════════════════════════════
// INTERNAL: Layout Contract for Backend Implementers
// ═══════════════════════════════════════════════════════════════════════════
//
// Size: Determined by label content + platform padding.
//
// ═══════════════════════════════════════════════════════════════════════════
#[non_exhaustive]
pub struct ButtonConfig {
    /// The label displayed on the button
    pub label: AnyView,
    /// The action to execute when the button is clicked
    pub action: BoxHandler<()>,
    /// The visual style of the button
    pub style: ButtonStyle,
}

impl_debug!(ButtonConfig);

impl NativeView for ButtonConfig {}

impl<Label, Action> View for Button<Label, Action>
where
    Label: View,
    Action: Handler<()>,
{
    fn body(self, env: &Environment) -> impl View {
        let config = self.config();
        if let Some(hook) = env.get::<Hook<ButtonConfig>>() {
            hook.apply(env, config)
        } else {
            AnyView::new(Native::new(config))
        }
    }

    fn stretch_axis(&self) -> waterui_core::layout::StretchAxis {
        waterui_core::layout::StretchAxis::None
    }
}

impl ViewConfiguration for ButtonConfig {
    type View = Button<AnyView, BoxHandler<()>>;

    fn render(self) -> Self::View {
        Button {
            label: self.label,
            action: self.action,
            style: self.style,
        }
    }
}

impl<Label, Action> ConfigurableView for Button<Label, Action>
where
    Label: View,
    Action: Handler<()>,
{
    type Config = ButtonConfig;

    fn config(self) -> Self::Config {
        ButtonConfig {
            label: AnyView::new(self.label),
            action: Box::new(self.action),
            style: self.style,
        }
    }
}

/// A button component that can be configured with a label and an action.
#[derive(Debug, Clone, PartialEq, Eq, Hash, Default)]
pub struct Button<Label, Action> {
    label: Label,
    action: Action,
    style: ButtonStyle,
}

impl<Label> Button<Label, ()> {
    /// Creates a new button with the specified label.
    ///
    /// # Arguments
    ///
    /// * `label` - The text or view to display on the button
    pub const fn new(label: Label) -> Self {
        Self {
            label,
            action: (),
            style: ButtonStyle::Automatic,
        }
    }
}

impl<Label, Action> Button<Label, Action> {
    /// Sets the visual style of the button.
    ///
    /// # Arguments
    ///
    /// * `style` - The button style to apply
    ///
    /// # Returns
    ///
    /// The modified button with the style set
    #[must_use]
    pub const fn style(mut self, style: ButtonStyle) -> Self {
        self.style = style;
        self
    }

    /// Sets the action to be performed when the button is clicked.
    ///
    /// # Arguments
    ///
    /// * `action` - The callback function to execute when button is clicked
    ///
    /// # Returns
    ///
    /// The modified button with the action set
    #[must_use]
    pub fn action<H, P>(self, action: H) -> Button<Label, IntoHandler<H, P, ()>>
    where
        H: HandlerFn<P, ()>,
        P: 'static,
    {
        Button {
            label: self.label,
            action: into_handler(action),
            style: self.style,
        }
    }
    /// Sets the action to be performed when the button is clicked, with access to a state.
    ///
    /// # Arguments
    ///
    /// * `state` - A reference to the state that the action can access.
    /// * `action` - The callback function to execute when the button is clicked.
    ///
    /// # Returns
    ///
    /// The modified button with the action and state set.
    #[must_use]
    pub fn action_with<H, P, S>(
        self,
        state: &S,
        action: H,
    ) -> Button<Label, IntoHandlerWithState<H, P, (), S>>
    where
        H: HandlerFnWithState<P, (), S>,
        S: 'static + Clone,
        P: 'static,
    {
        Button {
            label: self.label,
            action: into_handler_with_state(action, state.clone()),
            style: self.style,
        }
    }
}

/// Convenience function to create a new button with the specified label.
///
/// # Arguments
///
/// * `label` - The text or view to display on the button
///
/// # Returns
///
/// A new button instance
pub const fn button<Label>(label: Label) -> Button<Label, ()> {
    Button::new(label)
}